uisnap 0.1.0

package/.claude/skills/uisnap/REFERENCE.md

@@ -0,0 +1,1261 @@
+# uisnap - Specification
+
+## Overview
+
+A Playwright-based debugging toolkit for Claude Code that provides efficient frontend debugging through disk-based state capture and analysis. The toolkit follows a "capture once, query many" philosophy to minimize token costs and enable systematic debugging workflows.
+
+## Architecture
+
+The system consists of four layers:
+
+1. **Core Runtime** - Playwright environment manager
+2. **Capture Commands** - Built-in data extractors that write to disk
+3. **Analysis Commands** - Query tools for captured data
+4. **Code Mode** - User script execution within Playwright context
+
+```
+┌─────────────────────────────────────────────┐
+│  Agent (Claude Code)                        │
+└─────────────────┬───────────────────────────┘
+                  │
+      ┌───────────┴───────────┐
+      │                       │
+      ▼                       ▼
+┌──────────┐         ┌─────────────────┐
+│ Built-in │         │ Custom Scripts  │
+│ Commands │         │ (Code Mode)     │
+└─────┬────┘         └────────┬────────┘
+      │                       │
+      └───────────┬───────────┘
+                  │
+                  ▼
+        ┌──────────────────┐
+        │  Core Runtime    │
+        │  (pw.js)         │
+        └────────┬─────────┘
+                 │
+                 ▼
+        ┌──────────────────┐
+        │  Playwright      │
+        │  (Browser)       │
+        └──────────────────┘
+                 │
+                 ▼
+        ┌──────────────────┐
+        │  Disk Output     │
+        │  (JSON/JSONL)    │
+        └──────────────────┘
+```
+
+## 1. Core Runtime
+
+### File: `scripts/pw.js`
+
+The core runtime is a single entry point that manages Playwright's lifecycle and routes commands.
+
+**Responsibilities:**
+- Launch and manage Playwright browser instance
+- Route to built-in commands or user scripts
+- Provide execution context for scripts
+- Handle cleanup on exit
+
+**Interface:**
+```bash
+node scripts/pw.js <command> [args...]
+```
+
+**Commands:**
+- `snapshot <url> <output-dir>` - Capture full page state
+- `interact <scenario.yml> <output-dir>` - Run interaction scenario
+- `exec <script.js> [args...]` - Execute user script in Playwright context
+
+**Implementation Structure:**
+```javascript
+#!/usr/bin/env node
+const { chromium } = require('playwright');
+const fs = require('fs');
+const path = require('path');
+
+// Built-in command modules
+const builtins = {
+  snapshot: require('./commands/snapshot'),
+  interact: require('./commands/interact'),
+};
+
+async function main() {
+  const command = process.argv[2];
+  const args = process.argv.slice(3);
+  
+  // Launch browser
+  const browser = await chromium.launch({
+    headless: true,
+    args: ['--disable-dev-shm-usage']
+  });
+  
+  const context = await browser.newContext({
+    viewport: { width: 1280, height: 720 }
+  });
+  
+  const page = await context.newPage();
+  
+  try {
+    if (builtins[command]) {
+      // Execute built-in command
+      await builtins[command](page, context, browser, args);
+    } else if (command === 'exec') {
+      // Execute user script
+      await executeUserScript(page, context, browser, args);
+    } else {
+      console.error(`Unknown command: ${command}`);
+      process.exit(1);
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+async function executeUserScript(page, context, browser, args) {
+  const scriptPath = args[0];
+  const scriptArgs = args.slice(1);
+  const scriptCode = fs.readFileSync(scriptPath, 'utf8');
+  
+  // Create execution environment for user script
+  const env = {
+    page,
+    context,
+    browser,
+    args: scriptArgs,
+    fs,
+    path,
+    utils: {
+      writeJson: (filepath, data) => {
+        fs.mkdirSync(path.dirname(filepath), { recursive: true });
+        fs.writeFileSync(filepath, JSON.stringify(data, null, 2));
+      },
+      writeJsonl: (filepath, items) => {
+        fs.mkdirSync(path.dirname(filepath), { recursive: true });
+        fs.writeFileSync(filepath, items.map(i => JSON.stringify(i)).join('\n'));
+      },
+      appendJsonl: (filepath, item) => {
+        fs.appendFileSync(filepath, JSON.stringify(item) + '\n');
+      }
+    }
+  };
+  
+  // Execute user script in async context
+  const wrappedScript = `
+    (async ({ page, context, browser, args, fs, path, utils }) => {
+      ${scriptCode}
+    })
+  `;
+  
+  const userFunction = eval(wrappedScript);
+  await userFunction(env);
+}
+
+main().catch(err => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});
+```
+
+## 2. Capture Commands
+
+Built-in commands that extract browser state and write to disk. All commands produce structured JSON/JSONL output.
+
+### 2.1 Snapshot Command
+
+**Purpose:** Capture complete page state in a single operation
+
+**Usage:**
+```bash
+node scripts/pw.js snapshot <url> <output-dir>
+```
+
+**Output Structure:**
+```
+<output-dir>/
+├── a11y.json       # Accessibility tree
+├── console.jsonl   # Console messages (one per line)
+├── network.jsonl   # Network requests (one per line)
+└── metadata.json   # Page metadata (title, URL, timestamp, viewport)
+```
+
+**File: `scripts/commands/snapshot.js`**
+```javascript
+module.exports = async (page, context, browser, args) => {
+  const [url, outputDir] = args;
+  const fs = require('fs');
+  const path = require('path');
+  
+  if (!url || !outputDir) {
+    throw new Error('Usage: snapshot <url> <output-dir>');
+  }
+  
+  fs.mkdirSync(outputDir, { recursive: true });
+  
+  // Set up event listeners before navigation
+  const consoleLogs = [];
+  page.on('console', msg => {
+    consoleLogs.push({
+      timestamp: new Date().toISOString(),
+      type: msg.type(),
+      text: msg.text(),
+      location: msg.location()
+    });
+  });
+  
+  const networkLogs = [];
+  page.on('response', response => {
+    networkLogs.push({
+      url: response.url(),
+      status: response.status(),
+      statusText: response.statusText(),
+      method: response.request().method(),
+      resourceType: response.request().resourceType(),
+      timing: response.request().timing()
+    });
+  });
+  
+  // Navigate to page
+  await page.goto(url, { waitUntil: 'networkidle' });
+  
+  // Extract accessibility tree
+  const a11yTree = await page.accessibility.snapshot();
+  
+  // Extract page metadata
+  const metadata = await page.evaluate(() => ({
+    title: document.title,
+    url: window.location.href,
+    viewport: {
+      width: window.innerWidth,
+      height: window.innerHeight
+    },
+    timestamp: new Date().toISOString()
+  }));
+  
+  // Write all data to disk
+  fs.writeFileSync(
+    path.join(outputDir, 'a11y.json'),
+    JSON.stringify(a11yTree, null, 2)
+  );
+  
+  fs.writeFileSync(
+    path.join(outputDir, 'console.jsonl'),
+    consoleLogs.map(l => JSON.stringify(l)).join('\n')
+  );
+  
+  fs.writeFileSync(
+    path.join(outputDir, 'network.jsonl'),
+    networkLogs.map(l => JSON.stringify(l)).join('\n')
+  );
+  
+  fs.writeFileSync(
+    path.join(outputDir, 'metadata.json'),
+    JSON.stringify(metadata, null, 2)
+  );
+  
+  // Summary output
+  console.log(`✓ Snapshot saved to ${outputDir}/`);
+  console.log(`  - Accessibility tree: ${JSON.stringify(a11yTree).length} bytes`);
+  console.log(`  - Console messages: ${consoleLogs.length}`);
+  console.log(`  - Network requests: ${networkLogs.length}`);
+};
+```
+
+**Data Formats:**
+
+*a11y.json:*
+```json
+{
+  "role": "WebArea",
+  "name": "Page Title",
+  "children": [
+    {
+      "role": "button",
+      "name": "Submit",
+      "disabled": false,
+      "focused": false
+    }
+  ]
+}
+```
+
+*console.jsonl:*
+```json
+{"timestamp":"2024-12-25T10:30:00.000Z","type":"error","text":"Uncaught TypeError: Cannot read property 'x' of null","location":{"url":"https://example.com/app.js","lineNumber":42}}
+{"timestamp":"2024-12-25T10:30:01.000Z","type":"log","text":"User clicked submit","location":{"url":"https://example.com/app.js","lineNumber":100}}
+```
+
+*network.jsonl:*
+```json
+{"url":"https://api.example.com/users","status":200,"statusText":"OK","method":"GET","resourceType":"fetch","timing":{"startTime":1234.5,"responseEnd":1456.7}}
+{"url":"https://api.example.com/submit","status":500,"statusText":"Internal Server Error","method":"POST","resourceType":"fetch","timing":{"startTime":2345.6,"responseEnd":2567.8}}
+```
+
+### 2.2 Interact Command
+
+**Purpose:** Run a sequence of actions and capture state after each step
+
+**Usage:**
+```bash
+node scripts/pw.js interact <scenario.yml> <output-dir>
+```
+
+**Scenario Format (YAML):**
+```yaml
+steps:
+  - action: goto
+    url: https://example.com/login
+  
+  - action: fill
+    selector: input[name="email"]
+    value: test@example.com
+  
+  - action: fill
+    selector: input[name="password"]
+    value: password123
+  
+  - action: click
+    selector: button[type="submit"]
+    wait: 2000  # Optional wait after action (ms)
+  
+  - action: wait
+    duration: 1000
+```
+
+**Output Structure:**
+```
+<output-dir>/
+├── step-1-goto/
+│   ├── a11y.json
+│   ├── console.jsonl
+│   └── network.jsonl
+├── step-2-fill/
+│   ├── a11y.json
+│   ├── console.jsonl
+│   └── network.jsonl
+└── step-3-click/
+    ├── a11y.json
+    ├── console.jsonl
+    └── network.jsonl
+```
+
+**File: `scripts/commands/interact.js`**
+```javascript
+module.exports = async (page, context, browser, args) => {
+  const [scenarioFile, outputDir] = args;
+  const fs = require('fs');
+  const path = require('path');
+  const yaml = require('yaml');
+  
+  if (!scenarioFile || !outputDir) {
+    throw new Error('Usage: interact <scenario.yml> <output-dir>');
+  }
+  
+  const scenario = yaml.parse(fs.readFileSync(scenarioFile, 'utf8'));
+  fs.mkdirSync(outputDir, { recursive: true });
+  
+  // Set up logging
+  const consoleLogs = [];
+  page.on('console', msg => {
+    consoleLogs.push({
+      timestamp: new Date().toISOString(),
+      type: msg.type(),
+      text: msg.text()
+    });
+  });
+  
+  const networkLogs = [];
+  page.on('response', response => {
+    networkLogs.push({
+      url: response.url(),
+      status: response.status(),
+      method: response.request().method()
+    });
+  });
+  
+  // Execute each step
+  for (let i = 0; i < scenario.steps.length; i++) {
+    const step = scenario.steps[i];
+    console.log(`Step ${i + 1}/${scenario.steps.length}: ${step.action}`);
+    
+    // Execute action
+    switch (step.action) {
+      case 'goto':
+        await page.goto(step.url, { waitUntil: 'networkidle' });
+        break;
+      
+      case 'click':
+        await page.click(step.selector);
+        if (step.wait) await page.waitForTimeout(step.wait);
+        break;
+      
+      case 'fill':
+        await page.fill(step.selector, step.value);
+        break;
+      
+      case 'wait':
+        await page.waitForTimeout(step.duration || 1000);
+        break;
+      
+      default:
+        throw new Error(`Unknown action: ${step.action}`);
+    }
+    
+    // Capture state after this step
+    const stepDir = path.join(outputDir, `step-${i + 1}-${step.action}`);
+    fs.mkdirSync(stepDir, { recursive: true });
+    
+    const a11y = await page.accessibility.snapshot();
+    fs.writeFileSync(
+      path.join(stepDir, 'a11y.json'),
+      JSON.stringify(a11y, null, 2)
+    );
+    
+    // Save new console logs since last step
+    const newConsoleLogs = consoleLogs.splice(0);
+    if (newConsoleLogs.length > 0) {
+      fs.writeFileSync(
+        path.join(stepDir, 'console.jsonl'),
+        newConsoleLogs.map(l => JSON.stringify(l)).join('\n')
+      );
+    }
+    
+    // Save new network logs since last step
+    const newNetworkLogs = networkLogs.splice(0);
+    if (newNetworkLogs.length > 0) {
+      fs.writeFileSync(
+        path.join(stepDir, 'network.jsonl'),
+        newNetworkLogs.map(l => JSON.stringify(l)).join('\n')
+      );
+    }
+  }
+  
+  console.log(`✓ Interaction complete: ${scenario.steps.length} steps captured`);
+};
+```
+
+## 3. Analysis Commands
+
+Query tools that operate on captured data without requiring browser access. These are standalone scripts (not Playwright commands).
+
+### 3.1 Query Accessibility Tree
+
+**Purpose:** Extract specific information from accessibility tree
+
+**Usage:**
+```bash
+node scripts/query-a11y.js <snapshot-dir/a11y.json> <query>
+```
+
+**Queries:**
+- `--buttons` - List all buttons
+- `--links` - List all links
+- `--inputs` - List all input fields
+- `--interactive` - List all interactive elements
+- `--disabled` - List disabled elements
+- `<text>` - Search by text content
+
+**File: `scripts/query-a11y.js`**
+```javascript
+#!/usr/bin/env node
+const fs = require('fs');
+
+const snapshotFile = process.argv[2];
+const query = process.argv[3];
+
+if (!snapshotFile || !query) {
+  console.error('Usage: query-a11y.js <a11y.json> <query>');
+  process.exit(1);
+}
+
+const tree = JSON.parse(fs.readFileSync(snapshotFile, 'utf8'));
+
+function traverse(node, matcher, results = []) {
+  if (!node) return results;
+  
+  if (matcher(node)) {
+    results.push(node);
+  }
+  
+  if (node.children) {
+    node.children.forEach(child => traverse(child, matcher, results));
+  }
+  
+  return results;
+}
+
+// Define matchers for different queries
+let matcher;
+switch (query) {
+  case '--buttons':
+    matcher = n => n.role === 'button';
+    break;
+  case '--links':
+    matcher = n => n.role === 'link';
+    break;
+  case '--inputs':
+    matcher = n => ['textbox', 'searchbox', 'combobox'].includes(n.role);
+    break;
+  case '--interactive':
+    matcher = n => ['button', 'link', 'textbox', 'checkbox', 'radio', 'searchbox'].includes(n.role);
+    break;
+  case '--disabled':
+    matcher = n => n.disabled === true;
+    break;
+  default:
+    // Text search
+    matcher = n => n.name && n.name.toLowerCase().includes(query.toLowerCase());
+}
+
+const results = traverse(tree, matcher);
+
+// Output compact JSON for each result
+results.forEach(r => {
+  console.log(JSON.stringify({
+    role: r.role,
+    name: r.name,
+    disabled: r.disabled,
+    focused: r.focused
+  }));
+});
+
+console.error(`\n✓ Found ${results.length} matches`);
+```
+
+**Example Usage:**
+```bash
+# Find all buttons
+node scripts/query-a11y.js snapshots/current/a11y.json --buttons
+
+# Find submit button
+node scripts/query-a11y.js snapshots/current/a11y.json "Submit"
+
+# Find disabled elements
+node scripts/query-a11y.js snapshots/current/a11y.json --disabled
+```
+
+### 3.2 Analyze Console Logs
+
+**Purpose:** Summarize and filter console messages
+
+**Usage:**
+```bash
+node scripts/analyze-console.js <snapshot-dir/console.jsonl>
+```
+
+**File: `scripts/analyze-console.js`**
+```javascript
+#!/usr/bin/env node
+const fs = require('fs');
+
+const logFile = process.argv[2];
+
+if (!logFile) {
+  console.error('Usage: analyze-console.js <console.jsonl>');
+  process.exit(1);
+}
+
+const logs = fs.readFileSync(logFile, 'utf8')
+  .split('\n')
+  .filter(Boolean)
+  .map(JSON.parse);
+
+// Count by type
+const counts = {};
+logs.forEach(log => {
+  counts[log.type] = (counts[log.type] || 0) + 1;
+});
+
+console.log('=== Console Summary ===');
+console.log(`Total messages: ${logs.length}`);
+Object.entries(counts).forEach(([type, count]) => {
+  console.log(`  ${type}: ${count}`);
+});
+
+// Show unique errors
+const errors = logs.filter(l => l.type === 'error');
+if (errors.length > 0) {
+  console.log('\n=== Errors ===');
+  const uniqueErrors = [...new Set(errors.map(e => e.text))];
+  uniqueErrors.forEach((err, i) => {
+    const count = errors.filter(e => e.text === err).length;
+    console.log(`${i + 1}. [${count}x] ${err}`);
+  });
+}
+
+// Show unique warnings
+const warnings = logs.filter(l => l.type === 'warning');
+if (warnings.length > 0) {
+  console.log('\n=== Warnings ===');
+  const uniqueWarnings = [...new Set(warnings.map(w => w.text))];
+  uniqueWarnings.forEach((warn, i) => {
+    const count = warnings.filter(w => w.text === warn).length;
+    console.log(`${i + 1}. [${count}x] ${warn}`);
+  });
+}
+```
+
+### 3.3 Analyze Network Requests
+
+**Purpose:** Summarize network activity and identify failures
+
+**Usage:**
+```bash
+node scripts/analyze-network.js <snapshot-dir/network.jsonl>
+```
+
+**File: `scripts/analyze-network.js`**
+```javascript
+#!/usr/bin/env node
+const fs = require('fs');
+
+const logFile = process.argv[2];
+
+if (!logFile) {
+  console.error('Usage: analyze-network.js <network.jsonl>');
+  process.exit(1);
+}
+
+const requests = fs.readFileSync(logFile, 'utf8')
+  .split('\n')
+  .filter(Boolean)
+  .map(JSON.parse);
+
+console.log('=== Network Summary ===');
+console.log(`Total requests: ${requests.length}`);
+
+// Count by resource type
+const byType = {};
+requests.forEach(req => {
+  byType[req.resourceType] = (byType[req.resourceType] || 0) + 1;
+});
+
+console.log('\nBy resource type:');
+Object.entries(byType).forEach(([type, count]) => {
+  console.log(`  ${type}: ${count}`);
+});
+
+// Failed requests
+const failed = requests.filter(r => r.status >= 400);
+if (failed.length > 0) {
+  console.log(`\n=== Failed Requests (${failed.length}) ===`);
+  failed.forEach(req => {
+    console.log(`  ${req.status} ${req.method} ${req.url}`);
+  });
+}
+
+// Slow requests (if timing available)
+const slow = requests.filter(r => 
+  r.timing && (r.timing.responseEnd - r.timing.startTime) > 1000
+);
+if (slow.length > 0) {
+  console.log(`\n=== Slow Requests (>1s, ${slow.length}) ===`);
+  slow.forEach(req => {
+    const duration = Math.round(r.timing.responseEnd - r.timing.startTime);
+    console.log(`  ${duration}ms ${req.method} ${req.url}`);
+  });
+}
+```
+
+### 3.4 Compare Snapshots
+
+**Purpose:** Diff two snapshots to identify changes
+
+**Usage:**
+```bash
+node scripts/compare.js <snapshot-dir-1> <snapshot-dir-2>
+```
+
+**File: `scripts/compare.js`**
+```javascript
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const dir1 = process.argv[2];
+const dir2 = process.argv[3];
+
+if (!dir1 || !dir2) {
+  console.error('Usage: compare.js <snapshot-1> <snapshot-2>');
+  process.exit(1);
+}
+
+function loadSnapshot(dir) {
+  const loadJsonl = (file) => {
+    const filepath = path.join(dir, file);
+    if (!fs.existsSync(filepath)) return [];
+    return fs.readFileSync(filepath, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map(JSON.parse);
+  };
+  
+  return {
+    a11y: JSON.parse(fs.readFileSync(path.join(dir, 'a11y.json'), 'utf8')),
+    console: loadJsonl('console.jsonl'),
+    network: loadJsonl('network.jsonl')
+  };
+}
+
+const snap1 = loadSnapshot(dir1);
+const snap2 = loadSnapshot(dir2);
+
+console.log('=== Snapshot Comparison ===\n');
+
+// Compare console logs
+const errors1 = snap1.console.filter(l => l.type === 'error').map(l => l.text);
+const errors2 = snap2.console.filter(l => l.type === 'error').map(l => l.text);
+
+const newErrors = errors2.filter(e => !errors1.includes(e));
+const fixedErrors = errors1.filter(e => !errors2.includes(e));
+
+console.log('Console Errors:');
+if (newErrors.length > 0) {
+  console.log(`  New (${newErrors.length}):`);
+  newErrors.forEach(e => console.log(`    + ${e}`));
+}
+if (fixedErrors.length > 0) {
+  console.log(`  Fixed (${fixedErrors.length}):`);
+  fixedErrors.forEach(e => console.log(`    - ${e}`));
+}
+if (newErrors.length === 0 && fixedErrors.length === 0) {
+  console.log('  No changes');
+}
+
+// Compare network failures
+const failed1 = snap1.network.filter(r => r.status >= 400).map(r => r.url);
+const failed2 = snap2.network.filter(r => r.status >= 400).map(r => r.url);
+
+const newFailures = failed2.filter(u => !failed1.includes(u));
+const fixedFailures = failed1.filter(u => !failed2.includes(u));
+
+console.log('\nNetwork Failures:');
+if (newFailures.length > 0) {
+  console.log(`  New (${newFailures.length}):`);
+  newFailures.forEach(u => console.log(`    + ${u}`));
+}
+if (fixedFailures.length > 0) {
+  console.log(`  Fixed (${fixedFailures.length}):`);
+  fixedFailures.forEach(u => console.log(`    - ${u}`));
+}
+if (newFailures.length === 0 && fixedFailures.length === 0) {
+  console.log('  No changes');
+}
+
+// Compare a11y tree size (rough indicator of structural changes)
+const a11ySize1 = JSON.stringify(snap1.a11y).length;
+const a11ySize2 = JSON.stringify(snap2.a11y).length;
+const sizeDiff = a11ySize2 - a11ySize1;
+
+console.log('\nAccessibility Tree:');
+console.log(`  Before: ${a11ySize1} bytes`);
+console.log(`  After:  ${a11ySize2} bytes`);
+if (sizeDiff !== 0) {
+  console.log(`  Change: ${sizeDiff > 0 ? '+' : ''}${sizeDiff} bytes`);
+}
+```
+
+## 4. Code Mode (User Scripts)
+
+The core runtime provides an execution environment for user-written scripts. This enables the agent to write custom debugging scripts for novel scenarios.
+
+### 4.1 Execution Model
+
+**Command:**
+```bash
+node scripts/pw.js exec <script.js> [args...]
+```
+
+**Script Context:**
+User scripts execute as async functions with access to:
+- `page` - Playwright Page instance
+- `context` - Playwright BrowserContext instance
+- `browser` - Playwright Browser instance
+- `args` - Array of command-line arguments
+- `fs` - Node.js filesystem module
+- `path` - Node.js path module
+- `utils` - Helper utilities for writing data
+
+**Utils Object:**
+```javascript
+utils = {
+  writeJson: (filepath, data) => {
+    // Creates directories if needed, writes JSON with formatting
+  },
+  writeJsonl: (filepath, items) => {
+    // Writes array of objects as JSONL (one JSON object per line)
+  },
+  appendJsonl: (filepath, item) => {
+    // Appends single object to JSONL file
+  }
+}
+```
+
+### 4.2 Script Template
+
+```javascript
+// user-script.js
+// Available context: page, context, browser, args, fs, path, utils
+
+const url = args[0];
+const output = args[1];
+
+// Navigate to page
+await page.goto(url);
+
+// Extract data using Playwright API
+const data = await page.evaluate(() => {
+  // Browser context - extract data from DOM
+  return {
+    // ... extracted data
+  };
+});
+
+// Write to disk
+utils.writeJson(output, data);
+
+console.log(`Results saved to ${output}`);
+```
+
+### 4.3 Example User Scripts
+
+**Extract Form Data:**
+```javascript
+// extract-forms.js
+// Usage: node pw.js exec extract-forms.js <url> <output>
+
+const url = args[0];
+const output = args[1];
+
+await page.goto(url, { waitUntil: 'networkidle' });
+
+const forms = await page.evaluate(() => {
+  return Array.from(document.querySelectorAll('form')).map(form => ({
+    action: form.action,
+    method: form.method,
+    fields: Array.from(form.elements).map(el => ({
+      name: el.name,
+      type: el.type,
+      required: el.required,
+      value: el.type === 'password' ? '[REDACTED]' : el.value,
+      disabled: el.disabled
+    }))
+  }));
+});
+
+utils.writeJson(output, {
+  url,
+  timestamp: new Date().toISOString(),
+  forms
+});
+
+console.log(`Found ${forms.length} forms, saved to ${output}`);
+```
+
+**Monitor Memory Over Time:**
+```javascript
+// monitor-memory.js
+// Usage: node pw.js exec monitor-memory.js <url> <duration-ms> <interval-ms> <output>
+
+const url = args[0];
+const duration = parseInt(args[1]) || 30000;  // 30 seconds default
+const interval = parseInt(args[2]) || 1000;   // 1 second default
+const output = args[3];
+
+await page.goto(url);
+
+const samples = [];
+const startTime = Date.now();
+
+console.log(`Monitoring memory for ${duration}ms...`);
+
+while (Date.now() - startTime < duration) {
+  const metrics = await page.metrics();
+  samples.push({
+    timestamp: Date.now() - startTime,
+    jsHeapUsed: metrics.JSHeapUsedSize,
+    jsHeapTotal: metrics.JSHeapTotalSize,
+    documents: metrics.Documents,
+    frames: metrics.Frames
+  });
+  
+  await page.waitForTimeout(interval);
+}
+
+utils.writeJsonl(output, samples);
+
+console.log(`Collected ${samples.length} memory samples`);
+console.log(`Heap growth: ${samples[samples.length-1].jsHeapUsed - samples[0].jsHeapUsed} bytes`);
+```
+
+**Test Interaction Flow:**
+```javascript
+// test-checkout.js
+// Usage: node pw.js exec test-checkout.js <base-url> <output-dir>
+
+const baseUrl = args[0];
+const outputDir = args[1];
+
+// Track errors during flow
+const errors = [];
+page.on('console', msg => {
+  if (msg.type() === 'error') {
+    errors.push({
+      timestamp: new Date().toISOString(),
+      text: msg.text()
+    });
+  }
+});
+
+// Step 1: Add item to cart
+await page.goto(`${baseUrl}/products/123`);
+const beforeCart = await page.accessibility.snapshot();
+utils.writeJson(`${outputDir}/1-before-add.json`, beforeCart);
+
+await page.click('button.add-to-cart');
+await page.waitForTimeout(1000);
+
+const afterCart = await page.accessibility.snapshot();
+utils.writeJson(`${outputDir}/2-after-add.json`, afterCart);
+
+// Step 2: Go to checkout
+await page.click('a[href="/cart"]');
+await page.waitForNavigation();
+
+const cartPage = await page.accessibility.snapshot();
+utils.writeJson(`${outputDir}/3-cart-page.json`, cartPage);
+
+await page.click('button.checkout');
+await page.waitForNavigation();
+
+const checkoutPage = await page.accessibility.snapshot();
+utils.writeJson(`${outputDir}/4-checkout-page.json`, checkoutPage);
+
+// Save errors if any occurred
+if (errors.length > 0) {
+  utils.writeJsonl(`${outputDir}/errors.jsonl`, errors);
+  console.log(`⚠️  ${errors.length} console errors during checkout flow`);
+}
+
+console.log('Checkout flow captured successfully');
+```
+
+**Extract All Links:**
+```javascript
+// extract-links.js
+// Usage: node pw.js exec extract-links.js <url> <output>
+
+const url = args[0];
+const output = args[1];
+
+await page.goto(url, { waitUntil: 'networkidle' });
+
+const links = await page.evaluate(() => {
+  return Array.from(document.links).map(link => ({
+    href: link.href,
+    text: link.textContent.trim(),
+    target: link.target,
+    rel: link.rel
+  }));
+});
+
+// Test each link
+const results = [];
+for (const link of links) {
+  try {
+    const response = await page.request.head(link.href);
+    results.push({
+      ...link,
+      status: response.status(),
+      ok: response.ok()
+    });
+  } catch (err) {
+    results.push({
+      ...link,
+      error: err.message
+    });
+  }
+}
+
+utils.writeJson(output, {
+  url,
+  totalLinks: links.length,
+  brokenLinks: results.filter(r => !r.ok && !r.error).length,
+  errors: results.filter(r => r.error).length,
+  links: results
+});
+
+console.log(`Checked ${links.length} links`);
+```
+
+## 5. Project Structure
+
+```
+uisnap/
+├── scripts/
+│   ├── pw.js                    # Core runtime
+│   ├── commands/                # Built-in commands
+│   │   ├── snapshot.js
+│   │   └── interact.js
+│   ├── query-a11y.js           # Analysis: query a11y tree
+│   ├── analyze-console.js      # Analysis: summarize console logs
+│   ├── analyze-network.js      # Analysis: summarize network
+│   ├── compare.js              # Analysis: diff snapshots
+│   └── examples/               # Example user scripts
+│       ├── extract-forms.js
+│       ├── monitor-memory.js
+│       ├── test-checkout.js
+│       └── extract-links.js
+├── snapshots/                   # Default output directory
+│   └── .gitkeep
+├── scenarios/                   # Interaction scenarios
+│   └── example-login.yml
+├── package.json
+└── README.md
+```
+
+## 6. Installation & Setup
+
+**package.json:**
+```json
+{
+  "name": "uisnap",
+  "version": "1.0.0",
+  "description": "Efficient frontend debugging toolkit for Claude Code",
+  "scripts": {
+    "snapshot": "node scripts/pw.js snapshot",
+    "interact": "node scripts/pw.js interact"
+  },
+  "dependencies": {
+    "playwright": "^1.40.0",
+    "yaml": "^2.3.4"
+  }
+}
+```
+
+**Installation:**
+```bash
+npm install
+npx playwright install chromium
+```
+
+## 7. Usage Workflows
+
+### 7.1 Basic Debugging Workflow
+
+```bash
+# 1. Capture page state
+node scripts/pw.js snapshot "https://app.example.com" snapshots/current/
+
+# 2. Analyze what was captured
+node scripts/analyze-console.js snapshots/current/console.jsonl
+node scripts/analyze-network.js snapshots/current/network.jsonl
+
+# 3. Query accessibility tree for specific elements
+node scripts/query-a11y.js snapshots/current/a11y.json --buttons
+node scripts/query-a11y.js snapshots/current/a11y.json "Submit"
+
+# 4. If needed, write custom script for deeper investigation
+node scripts/pw.js exec scripts/examples/extract-forms.js \
+  "https://app.example.com" snapshots/forms.json
+```
+
+### 7.2 Interaction Testing Workflow
+
+```bash
+# 1. Create scenario
+cat > scenarios/login-test.yml << EOF
+steps:
+  - action: goto
+    url: https://app.example.com/login
+  - action: fill
+    selector: input[name="email"]
+    value: test@example.com
+  - action: fill
+    selector: input[name="password"]
+    value: password123
+  - action: click
+    selector: button[type="submit"]
+    wait: 2000
+EOF
+
+# 2. Run interaction and capture state at each step
+node scripts/pw.js interact scenarios/login-test.yml snapshots/login-flow/
+
+# 3. Analyze each step
+node scripts/analyze-console.js snapshots/login-flow/step-1-goto/console.jsonl
+node scripts/analyze-console.js snapshots/login-flow/step-4-click/console.jsonl
+
+# 4. Compare before/after
+node scripts/compare.js \
+  snapshots/login-flow/step-1-goto/ \
+  snapshots/login-flow/step-4-click/
+```
+
+### 7.3 Regression Testing Workflow
+
+```bash
+# 1. Capture baseline
+node scripts/pw.js snapshot "https://app.example.com" snapshots/baseline/
+
+# 2. Make code changes
+# ... deploy new version ...
+
+# 3. Capture after changes
+node scripts/pw.js snapshot "https://app.example.com" snapshots/after-deploy/
+
+# 4. Compare
+node scripts/compare.js snapshots/baseline/ snapshots/after-deploy/
+```
+
+### 7.4 Custom Investigation Workflow
+
+```bash
+# Agent identifies need for custom data extraction
+# Writes a script:
+
+cat > scripts/check-memory-leak.js << 'EOF'
+const url = args[0];
+const output = args[1];
+
+await page.goto(url);
+
+const samples = [];
+for (let i = 0; i < 20; i++) {
+  await page.click('.trigger-action');
+  await page.waitForTimeout(500);
+  
+  const metrics = await page.metrics();
+  samples.push({
+    iteration: i,
+    heapUsed: metrics.JSHeapUsedSize
+  });
+}
+
+utils.writeJsonl(output, samples);
+
+const growth = samples[19].heapUsed - samples[0].heapUsed;
+console.log(`Heap grew by ${growth} bytes over 20 iterations`);
+EOF
+
+# Executes it:
+node scripts/pw.js exec scripts/check-memory-leak.js \
+  "https://app.example.com" snapshots/memory-test.jsonl
+
+# Analyzes results:
+jq -r '[.iteration, .heapUsed] | @tsv' snapshots/memory-test.jsonl
+```
+
+## 8. Design Principles
+
+### 8.1 Capture Once, Query Many
+- Expensive browser operations write to disk once
+- Cheap local queries can analyze data repeatedly
+- Agent avoids re-running browser for each question
+
+### 8.2 Structured Output
+- All data is JSON or JSONL
+- Can be queried with standard tools (jq, grep, awk)
+- Can be imported into analysis tools (DuckDB, Python, etc.)
+
+### 8.3 Composability
+- Built-in commands handle common cases
+- User scripts handle novel scenarios
+- Analysis tools work on any captured data
+- Scripts can be chained together
+
+### 8.4 Disk-First
+- Everything goes to files, not stdout (unless it's a summary)
+- Enables post-hoc analysis
+- Files can be version controlled
+- Results persist across sessions
+
+### 8.5 Progressive Disclosure
+- Start with summaries (analyze-*.js scripts)
+- Drill into details only when needed
+- Query locally before running browser again
+
+## 9. Token Efficiency
+
+**Problem:** Browser debugging traditionally expensive
+- Full DOM: ~15,000 tokens
+- All console logs: ~8,000 tokens
+- Screenshots: ~10,000 tokens
+- Total for basic debugging: ~40,000 tokens
+
+**Solution:** This toolkit's approach
+- Capture to disk: ~2,000 tokens (one-time)
+- Analyze console summary: ~100 tokens
+- Query a11y tree: ~50 tokens
+- Read filtered results: ~200 tokens
+- Total for same debugging: ~2,350 tokens
+
+**~17x reduction in token usage**
+
+## 10. Extension Points
+
+The toolkit is designed to be extended:
+
+### 10.1 New Capture Commands
+Add to `scripts/commands/`:
+- `performance.js` - Capture Core Web Vitals
+- `lighthouse.js` - Run Lighthouse audit
+- `coverage.js` - Capture code coverage
+
+### 10.2 New Analysis Scripts
+Add analysis tools:
+- `analyze-performance.js` - Analyze perf metrics
+- `find-unused-css.js` - Analyze coverage data
+- `extract-schema.js` - Extract structured data markup
+
+### 10.3 Integration Hooks
+Scripts can integrate with external tools:
+- Post results to monitoring systems
+- Generate reports
+- Trigger alerts
+- Update dashboards
+
+## 11. Skill Documentation
+
+The toolkit should be accompanied by a Claude Code skill that teaches the agent:
+- When to use built-in commands vs. custom scripts
+- How to structure user scripts
+- Common debugging patterns
+- Token-efficient workflows
+
+**Skill structure:**
+```markdown
+---
+name: uisnap
+description: Efficient frontend debugging with Playwright. Captures browser state to disk, enables local querying. Use when debugging web apps, investigating errors, or analyzing interactions.
+---
+
+# uisnap
+
+[Documentation of commands, workflows, examples]
+```
+
+## 12. Success Criteria
+
+The toolkit is successful if:
+
+1. **Token Efficient**: >10x reduction in tokens for common debugging tasks
+2. **Flexible**: Agent can write custom scripts for novel scenarios
+3. **Composable**: Scripts and commands work together naturally
+4. **Discoverable**: Built-in commands cover 80% of use cases
+5. **Extensible**: Easy to add new commands and analysis tools
+
+## 13. Future Enhancements
+
+Potential future additions:
+
+- **Visual regression**: Screenshot comparison with diff highlighting
+- **Performance tracking**: Time-series metrics capture
+- **Batch testing**: Run multiple scenarios in parallel
+- **Report generation**: HTML reports from captured data
+- **CI/CD integration**: Run in automated pipelines
+- **Real-device testing**: Mobile device emulation
+- **Network throttling**: Simulate slow connections
+- **Accessibility auditing**: Run aXe or similar tools