uisnap 0.1.0

package/.claude/skills/uisnap/SETUP.md

@@ -0,0 +1,75 @@
+# Setup Instructions
+
+## Installation
+
+This skill requires the uisnap to be installed.
+
+### Option 1: Global Installation (Recommended for Skill)
+
+```bash
+npm install -g uisnap
+npx playwright install chromium
+```
+
+After global install, the commands are available everywhere:
+- `uisnap`
+- `uisnap-analyze-console`
+- `uisnap-analyze-network`
+- `uisnap-query-a11y`
+
+### Option 2: Local Development
+
+If you're working on the toolkit itself:
+
+```bash
+cd uisnap
+npm install
+npm run build
+npx playwright install chromium
+
+# Use with node dist/pw.js instead of uisnap
+node dist/pw.js snapshot https://example.com
+```
+
+## Verify Installation
+
+```bash
+# Check that commands are available
+uisnap --help
+uisnap-analyze-console --help
+uisnap-query-a11y --help
+
+# Test with a simple capture
+uisnap snapshot https://example.com
+ls snapshots/example.com/latest/
+```
+
+## Skill Location
+
+This skill should be installed in one of:
+
+**Project skill** (shared with team via git):
+```
+your-project/.claude/skills/uisnap/
+```
+
+**Personal skill** (available across all projects):
+```
+~/.claude/skills/uisnap/
+```
+
+To share with your team, commit `.claude/skills/` to your repository.
+
+## Troubleshooting
+
+**"uisnap: command not found"**
+- Run `npm install -g uisnap`
+- Make sure npm global bin is in your PATH
+
+**"Browser not found"**
+- Run `npx playwright install chromium`
+
+**Skill not activating**
+- Check YAML frontmatter is valid (no tabs, proper indentation)
+- Ensure file is named `SKILL.md`
+- Try mentioning keywords from description: "debug", "console errors", "network failures"

package/.claude/skills/uisnap/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: uisnap
+description: Captures browser state to disk for token-efficient debugging. Use for frontend debugging, performance analysis, accessibility testing, or when investigating page behavior. Supports snapshots (functional debugging) and Chrome traces (performance profiling).
+---
+
+# uisnap
+
+Disk-based debugging for Claude Code. **Capture once, query many.**
+
+## Quick Decision Tree
+
+**User reports functional issues** → Snapshot capture
+- "Button doesn't work"
+- "Form submission fails"
+- "Console errors"
+- "API returns 404"
+- "Page doesn't load"
+
+→ See [snapshot-capture-and-analysis.md](snapshot-capture-and-analysis.md)
+
+**User reports performance issues** → Trace capture
+- "Page is slow/laggy"
+- "Scrolling is janky"
+- "Animations stutter"
+- "UI freezes"
+- "Long blocking tasks"
+
+→ See [trace-capture-and-analysis.md](trace-capture-and-analysis.md)
+
+**Not sure?** → Start with snapshot (faster, cheaper), escalate to trace if needed
+
+## Common Commands
+
+### Snapshot Workflow
+```bash
+# Capture
+uisnap snapshot https://myapp.com
+
+# Analyze
+uisnap-analyze-console snapshots/myapp.com/latest/console.jsonl
+uisnap-analyze-network snapshots/myapp.com/latest/network.jsonl
+uisnap-query-a11y snapshots/myapp.com/latest/a11y.yaml "Submit"
+```
+
+### Trace Workflow
+```bash
+# Capture
+uisnap exec examples/scroll-perf-trace.js https://myapp.com
+
+# Analyze
+uisnap-chrome-trace-analyze snapshots/myapp.com/latest/chrome-trace.db --full
+```
+
+## Available Tools
+
+**Capture commands**:
+- `uisnap snapshot <url>` - Capture page state (a11y, console, network)
+- `uisnap exec <script.js> <url>` - Run custom script with Playwright context
+
+**Analysis commands**:
+- `uisnap-analyze-console <console.jsonl>` - Summarize console messages
+- `uisnap-analyze-network <network.jsonl>` - Summarize network activity
+- `uisnap-query-a11y <a11y.yaml> <query>` - Query accessibility tree
+- `uisnap-chrome-trace-analyze <trace.db>` - Analyze performance trace
+
+## Installation
+
+```bash
+npm install -g uisnap
+npx playwright install chromium
+```
+
+## When to Read Reference Docs
+
+**For snapshot debugging**: See [snapshot-capture-and-analysis.md](snapshot-capture-and-analysis.md)
+- Complete capture and analysis guide
+- Multi-step flows with `utils.captureStep()`
+- Output formats and querying patterns
+- Examples and troubleshooting
+
+**For performance debugging**: See [trace-capture-and-analysis.md](trace-capture-and-analysis.md)
+- Chrome tracing setup and workflow
+- DuckDB schema and canned queries
+- Custom SQL for advanced analysis
+- Examples and troubleshooting
+
+## Progressive Workflow
+
+1. **Start with snapshot** - Check for functional errors first
+2. **If no errors but issues persist** - Capture trace for performance analysis
+3. **For comprehensive debugging** - Combine both approaches
+
+Example combining both:
+```javascript
+// Capture functional state
+await utils.captureStep(page, 'initial-load', async () => {
+  await page.goto('https://myapp.com');
+});
+
+// Start performance tracing
+const cdp = await context.newCDPSession(page);
+await utils.startChromeTrace(cdp);
+
+// Perform interactions (traced)
+await page.evaluate(() => window.scrollTo({ top: 1000 }));
+
+// Capture final state
+await utils.captureStep(page, 'after-scroll', async () => {});
+
+// Stop trace and auto-import
+const tracePath = path.join(utils.baseOutputDir, 'chrome-trace.json');
+await utils.stopChromeTraceAndImport(cdp, tracePath);
+```
+
+## Output Structure
+
+Auto-generated timestamped directories:
+```
+snapshots/
+├── myapp.com/
+│   ├── 2025-12-30-120000/
+│   │   ├── a11y.yaml
+│   │   ├── console.jsonl
+│   │   ├── network.jsonl
+│   │   └── metadata.json
+│   ├── 2025-12-30-130000/
+│   └── latest -> 2025-12-30-130000/
+```
+
+Use `latest` symlink for most recent capture.

package/.claude/skills/uisnap/snapshot-capture-and-analysis.md

@@ -0,0 +1,452 @@
+# Snapshot Capture and Analysis
+
+Complete reference for functional debugging with Playwright snapshots.
+
+## When to Use Snapshots
+
+Use snapshot capture for functional debugging:
+- Console errors or warnings
+- Network request failures (4xx, 5xx)
+- Missing or disabled UI elements
+- Incorrect page state
+- Accessibility issues
+- Multi-step user flows (login, checkout, forms)
+
+## Capture Commands
+
+### Basic Snapshot
+
+```bash
+uisnap snapshot <url> [output-dir]
+```
+
+**Auto-generated output** (when output-dir omitted):
+```
+snapshots/{hostname}/{timestamp}/
+├── a11y.yaml       # ARIA accessibility tree
+├── console.jsonl   # Console messages
+├── network.jsonl   # Network requests
+└── metadata.json   # Page metadata
+```
+
+**Example**:
+```bash
+uisnap snapshot https://myapp.com
+# Creates: snapshots/myapp.com/2025-12-30-143052/
+# Symlinks: snapshots/myapp.com/latest -> 2025-12-30-143052/
+```
+
+**Explicit output path**:
+```bash
+uisnap snapshot https://myapp.com snapshots/baseline/
+# Creates exactly: snapshots/baseline/
+# No timestamp, no symlink
+```
+
+Use explicit paths for baselines or comparisons.
+
+### Multi-Step Flows with captureStep
+
+For complex user flows, use `utils.captureStep()` to capture state at each step:
+
+```javascript
+// examples/login-flow.js
+// Usage: uisnap exec examples/login-flow.js https://myapp.com
+
+// Step 1: Navigate
+await utils.captureStep(page, 'goto-login', async () => {
+  await page.goto('https://myapp.com/login');
+});
+
+// Step 2: Fill email (use role-based selectors)
+await utils.captureStep(page, 'fill-email', async () => {
+  await page.getByLabel('Email').fill('test@example.com');
+});
+
+// Step 3: Fill password
+await utils.captureStep(page, 'fill-password', async () => {
+  await page.getByLabel('Password').fill('password123');
+});
+
+// Step 4: Submit
+await utils.captureStep(page, 'click-submit', async () => {
+  await page.getByRole('button', { name: 'Submit' }).click();
+});
+
+// Step 5: Verify redirect
+await utils.captureStep(page, 'after-login', async () => {
+  await page.waitForURL('**/dashboard');
+});
+```
+
+**Output structure**:
+```
+snapshots/myapp.com/login-flow-2025-12-30-143052/
+├── step-1-goto-login/
+│   ├── a11y.yaml
+│   └── metadata.json
+├── step-2-fill-email/
+│   ├── a11y.yaml
+│   └── metadata.json
+├── step-3-fill-password/
+│   └── ...
+├── step-4-click-submit/
+│   └── ...
+└── step-5-after-login/
+    └── ...
+```
+
+### Available Context in Scripts
+
+Scripts executed with `uisnap exec` have access to:
+
+- `page, context, browser` - Playwright instances
+- `args` - Command-line arguments (after URL and output-dir)
+- `fs, path` - Node.js modules (already loaded, don't require)
+- `utils.captureStep(page, name, action)` - Capture step with auto-numbering
+- `utils.writeJson(path, data)` - Write formatted JSON
+- `utils.writeJsonl(path, items)` - Write JSONL
+- `utils.appendJsonl(path, item)` - Append to JSONL
+- `utils.baseOutputDir` - Output directory path
+
+## Analysis Commands
+
+### Analyze Console Messages
+
+```bash
+uisnap-analyze-console <console.jsonl>
+```
+
+**Output**:
+- Message counts by type (error, warning, log, info)
+- Grouped errors with counts and locations
+- Grouped warnings with counts and locations
+
+**Example**:
+```bash
+uisnap-analyze-console snapshots/myapp.com/latest/console.jsonl
+
+# Output:
+# === Console Summary ===
+# Total messages: 47
+# Errors: 2
+# Warnings: 5
+# Logs: 40
+#
+# === Grouped Errors ===
+# 1. "Cannot read property 'submit' of null" (2 occurrences)
+#    app.js:123
+#    form.js:45
+```
+
+### Analyze Network Requests
+
+```bash
+uisnap-analyze-network <network.jsonl>
+```
+
+**Output**:
+- Request counts by resource type (fetch, xhr, script, stylesheet, etc.)
+- Request counts by HTTP method (GET, POST, etc.)
+- Request counts by status code
+- Failed requests (4xx, 5xx)
+- Slow requests (>1s)
+- Requests by domain
+
+**Example**:
+```bash
+uisnap-analyze-network snapshots/myapp.com/latest/network.jsonl
+
+# Output:
+# === Network Summary ===
+# Total requests: 87
+#
+# === By Resource Type ===
+# document: 1
+# fetch: 23
+# script: 18
+# stylesheet: 8
+#
+# === Failed Requests (4xx/5xx) ===
+# 1. POST https://api.myapp.com/submit - 500 Internal Server Error
+# 2. GET https://cdn.myapp.com/missing.js - 404 Not Found
+```
+
+### Query Accessibility Tree
+
+```bash
+uisnap-query-a11y <a11y.yaml> <query>
+```
+
+**Query options**:
+- `--buttons` - List all buttons
+- `--links` - List all links
+- `--headings` - List all headings
+- `--inputs` - List all input fields
+- `--interactive` - List all interactive elements
+- `--images` - List all images
+- `--disabled` - List disabled elements
+- `<text>` - Search by text content (case-insensitive)
+
+**Example**:
+```bash
+# Find all buttons
+uisnap-query-a11y snapshots/myapp.com/latest/a11y.yaml --buttons
+# Output: button "Submit" [disabled]
+#         button "Cancel"
+
+# Search for specific text
+uisnap-query-a11y snapshots/myapp.com/latest/a11y.yaml "Submit"
+# Output: button "Submit" [disabled]
+
+# Find all inputs
+uisnap-query-a11y snapshots/myapp.com/latest/a11y.yaml --inputs
+# Output: textbox "Email" [required]
+#         textbox "Password" [required]
+```
+
+## Output Formats
+
+### ARIA Snapshot (YAML)
+
+Human-readable accessibility tree:
+
+```yaml
+- heading "Example Domain" [level=1]
+- paragraph: This domain is for use in examples.
+- link "Learn more":
+  - /url: https://iana.org/domains/example
+- button "Submit" [disabled]
+- textbox "Email" [required]
+```
+
+### Console Logs (JSONL)
+
+One JSON object per line:
+
+```jsonl
+{"timestamp":"2025-12-30T10:30:00.000Z","type":"error","text":"Cannot read property 'submit' of null","location":{"url":"https://myapp.com/app.js","lineNumber":123}}
+{"timestamp":"2025-12-30T10:30:01.000Z","type":"log","text":"User clicked submit","location":{"url":"https://myapp.com/app.js","lineNumber":100}}
+```
+
+### Network Requests (JSONL)
+
+One JSON object per line:
+
+```jsonl
+{"url":"https://api.myapp.com/users","status":200,"statusText":"OK","method":"GET","resourceType":"fetch","timing":{"startTime":1234.5,"responseEnd":1456.7}}
+{"url":"https://api.myapp.com/submit","status":500,"statusText":"Internal Server Error","method":"POST","resourceType":"fetch"}
+```
+
+### Metadata (JSON)
+
+Page information:
+
+```json
+{
+  "title": "My App - Dashboard",
+  "url": "https://myapp.com/dashboard",
+  "timestamp": "2025-12-30T10:30:00.000Z",
+  "viewport": {
+    "width": 1280,
+    "height": 720
+  }
+}
+```
+
+## Common Workflows
+
+### Basic Debugging Workflow
+
+```bash
+# 1. Capture page state
+uisnap snapshot https://myapp.com
+
+# 2. Check for errors (use "latest" symlink)
+uisnap-analyze-console snapshots/myapp.com/latest/console.jsonl
+# Found: "Cannot read property 'submit' of null"
+
+# 3. Check network failures
+uisnap-analyze-network snapshots/myapp.com/latest/network.jsonl
+# Found: POST /api/submit - 500 Internal Server Error
+
+# 4. Find the submit button
+uisnap-query-a11y snapshots/myapp.com/latest/a11y.yaml "Submit"
+# Found: button "Submit" [disabled]
+
+# Diagnosis: Button is disabled, API returns 500, JS error on submit
+```
+
+### Iterative Debugging Workflow
+
+```bash
+# First capture
+uisnap snapshot https://myapp.com
+# Creates: snapshots/myapp.com/2025-12-30-143052/
+
+# Make code changes...
+
+# Second capture (doesn't overwrite!)
+uisnap snapshot https://myapp.com
+# Creates: snapshots/myapp.com/2025-12-30-144315/
+# Updates: snapshots/myapp.com/latest -> 2025-12-30-144315/
+
+# "latest" always points to most recent
+uisnap-analyze-console snapshots/myapp.com/latest/console.jsonl
+
+# View history
+ls snapshots/myapp.com/
+# 2025-12-30-143052/
+# 2025-12-30-144315/
+# latest -> 2025-12-30-144315/
+```
+
+### Multi-Step Flow Debugging
+
+```bash
+# 1. Capture entire flow
+uisnap exec examples/login-flow.js https://myapp.com
+
+# 2. Analyze specific step
+uisnap-query-a11y snapshots/myapp.com/latest/step-4-click-submit/a11y.yaml --buttons
+
+# 3. Check console for step 5
+uisnap-analyze-console snapshots/myapp.com/latest/step-5-after-login/console.jsonl
+
+# 4. Examine step directories
+ls snapshots/myapp.com/latest/
+# step-1-goto-login/
+# step-2-fill-email/
+# step-3-fill-password/
+# step-4-click-submit/
+# step-5-after-login/
+```
+
+### Regression Testing Workflow
+
+```bash
+# Before deployment (explicit path for baseline)
+uisnap snapshot https://myapp.com snapshots/baseline/
+
+# After deployment (auto-generated)
+uisnap snapshot https://myapp.com
+# Creates: snapshots/myapp.com/2025-12-30-150000/
+
+# Compare console logs
+diff snapshots/baseline/console.jsonl snapshots/myapp.com/latest/console.jsonl
+
+# Compare a11y trees
+diff snapshots/baseline/a11y.yaml snapshots/myapp.com/latest/a11y.yaml
+```
+
+## Playwright Selector Best Practices
+
+Use role-based selectors that align with ARIA snapshots:
+
+**Recommended** (matches a11y.yaml):
+```javascript
+await page.getByRole('button', { name: 'Submit' })  // button "Submit"
+await page.getByLabel('Email')                       // textbox "Email"
+await page.getByText('Welcome')                      // text: Welcome
+await page.getByRole('link', { name: 'Learn more' }) // link "Learn more"
+```
+
+**Avoid** (brittle, doesn't match a11y.yaml):
+```javascript
+await page.click('button[type="submit"]')            // CSS selector
+await page.click('#submit-btn')                      // ID selector
+await page.click('.btn-primary')                     // Class selector
+```
+
+Role-based selectors make it easy to correlate captured a11y.yaml with your script actions.
+
+## Custom Data Extraction
+
+For extracting custom data without step capture:
+
+```javascript
+// examples/extract-links.js
+await page.goto(args[0]);
+
+const data = await page.evaluate(() => {
+  return {
+    links: Array.from(document.links).map(l => ({ href: l.href, text: l.textContent })),
+    headings: Array.from(document.querySelectorAll('h1, h2, h3')).map(h => ({
+      level: h.tagName,
+      text: h.textContent
+    }))
+  };
+});
+
+utils.writeJson(path.join(utils.baseOutputDir, 'extracted.json'), data);
+console.log(`Extracted ${data.links.length} links, ${data.headings.length} headings`);
+```
+
+## Troubleshooting
+
+### Snapshot directory not found
+
+```bash
+uisnap snapshot https://myapp.com
+# Error: ENOENT: no such file or directory
+
+# Solution: Check that snapshots/ directory exists
+mkdir -p snapshots
+```
+
+### "latest" symlink points to wrong snapshot
+
+```bash
+# Symlinks update automatically on each capture
+# To manually fix:
+cd snapshots/myapp.com
+rm latest
+ln -s 2025-12-30-143052 latest
+```
+
+### captureStep doesn't capture console/network
+
+`captureStep()` only captures a11y.yaml and metadata.json. For console/network, use the snapshot command or add listeners in your script:
+
+```javascript
+// Capture console in custom script
+const consoleLogs = [];
+page.on('console', msg => consoleLogs.push({
+  type: msg.type(),
+  text: msg.text(),
+  timestamp: new Date().toISOString()
+}));
+
+// Later, write to file
+utils.writeJsonl(path.join(utils.baseOutputDir, 'console.jsonl'), consoleLogs);
+```
+
+### Query returns no results
+
+Check file path and query syntax:
+
+```bash
+# Correct: use relative or absolute path
+uisnap-query-a11y snapshots/myapp.com/latest/a11y.yaml --buttons
+
+# Incorrect: missing path
+uisnap-query-a11y --buttons  # Error: file not found
+```
+
+## Advanced: Manual JSONL Processing
+
+For custom analysis, use standard Unix tools:
+
+```bash
+# Count error messages
+grep '"type":"error"' snapshots/myapp.com/latest/console.jsonl | wc -l
+
+# Extract all API requests
+grep '"resourceType":"fetch"' snapshots/myapp.com/latest/network.jsonl > api-requests.jsonl
+
+# Find specific error message
+grep "Cannot read property" snapshots/myapp.com/latest/console.jsonl
+
+# Use jq for complex queries
+jq 'select(.status >= 400)' snapshots/myapp.com/latest/network.jsonl
+```