uisnap 0.1.0

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

@@ -0,0 +1,472 @@
+# Trace Capture and Analysis
+
+Complete reference for performance debugging with Chrome DevTools traces.
+
+## When to Use Trace Capture
+
+Use trace capture for performance profiling:
+- Slow page loads or interactions
+- Janky scrolling or animations
+- UI freezes during user actions
+- Long blocking tasks (>50ms)
+- JavaScript execution analysis
+- Layout thrashing or excessive repaints
+- Identifying performance bottlenecks
+
+## Chrome Trace vs Playwright Trace
+
+**Chrome Performance Trace** (this guide):
+- Captures browser internals: paint, layout, JS execution, style recalc
+- Uses Chrome DevTools Protocol (CDP)
+- Stores in DuckDB for efficient querying
+- 36MB JSON → 1.5MB database → 100-500 token queries
+- Use for: Performance profiling, blocking tasks, rendering analysis
+
+**Playwright Trace** (different tool):
+- Captures Playwright actions: clicks, navigations, assertions
+- Stores in .trace.zip format
+- Opens in Playwright Trace Viewer UI
+- Use for: Action replay, test debugging, visual timeline
+
+This guide covers Chrome Performance Traces only.
+
+## Capture Workflow
+
+### Basic Trace Capture
+
+Use the provided example script for scroll performance:
+
+```bash
+uisnap exec examples/scroll-perf-trace.js https://myapp.com
+```
+
+**Output**:
+```
+snapshots/myapp.com/scroll-perf-trace-2025-12-30-143052/
+├── chrome-trace.json   # Raw trace (potentially large, not for direct reading)
+└── chrome-trace.db     # DuckDB database (queryable)
+```
+
+### Custom Trace Script
+
+For custom interactions, create a script with trace boundaries:
+
+```javascript
+// examples/interaction-trace.js
+// Get CDP session
+const cdp = await context.newCDPSession(page);
+
+// Start Chrome tracing
+console.log('Starting Chrome performance trace...');
+await utils.startChromeTrace(cdp);
+
+// Navigate
+await page.goto(args[0]);
+await page.waitForLoadState('networkidle');
+
+// Perform interactions (all will be traced)
+await page.getByRole('button', { name: 'Open Modal' }).click();
+await page.waitForTimeout(100);
+
+await page.getByRole('textbox', { name: 'Search' }).fill('test query');
+await page.waitForTimeout(100);
+
+await page.evaluate(() => {
+  for (let i = 0; i < 10; i++) {
+    document.querySelector('.item').scrollIntoView({ behavior: 'smooth' });
+  }
+});
+
+console.log('Stopping trace and importing to database...');
+
+// Stop tracing and auto-import to DuckDB
+const tracePath = path.join(utils.baseOutputDir, 'chrome-trace.json');
+const dbPath = await utils.stopChromeTraceAndImport(cdp, tracePath);
+
+console.log('\nAnalyze with:');
+console.log(`  uisnap-chrome-trace-analyze ${dbPath} --full`);
+```
+
+**Key points**:
+- Start trace BEFORE interactions you want to profile
+- All browser activity between start/stop is captured
+- Auto-import creates queryable database
+- Don't try to read chrome-trace.json directly (too large)
+
+### Combining Snapshot and Trace
+
+Capture both functional state and performance data:
+
+```javascript
+// examples/comprehensive-debug.js
+// Capture initial state
+await utils.captureStep(page, 'initial-load', async () => {
+  await page.goto(args[0]);
+});
+
+// Start performance tracing
+const cdp = await context.newCDPSession(page);
+await utils.startChromeTrace(cdp);
+
+// Perform interactions (traced)
+await page.evaluate(() => window.scrollTo({ top: 1000, behavior: 'smooth' }));
+await page.waitForTimeout(500);
+
+await page.evaluate(() => window.scrollTo({ top: 2000, behavior: 'smooth' }));
+await page.waitForTimeout(500);
+
+// Capture final state
+await utils.captureStep(page, 'after-scroll', async () => {});
+
+// Stop trace
+const tracePath = path.join(utils.baseOutputDir, 'chrome-trace.json');
+const dbPath = await utils.stopChromeTraceAndImport(cdp, tracePath);
+
+console.log('Functional analysis:');
+console.log(`  uisnap-analyze-console step-1-initial-load/console.jsonl`);
+console.log(`  uisnap-analyze-console step-2-after-scroll/console.jsonl`);
+console.log('\nPerformance analysis:');
+console.log(`  uisnap-chrome-trace-analyze ${dbPath} --full`);
+```
+
+## Analysis Workflow
+
+### Progressive Disclosure Pattern
+
+Start with summary, drill into details as needed:
+
+```bash
+# 1. Summary (shows what's available)
+uisnap-chrome-trace-analyze snapshots/myapp.com/latest/chrome-trace.db
+
+# Output:
+# === Chrome Trace Summary ===
+# Total tasks: 48,234
+# Total duration: 3,847.52ms
+#
+# For details, use:
+#   --long-tasks     Show 8 task(s) over 50ms
+#   --js-time        Show JavaScript execution breakdown
+#   --layout-paint   Show layout and paint analysis
+
+# 2. Identify long blocking tasks
+uisnap-chrome-trace-analyze snapshots/myapp.com/latest/chrome-trace.db --long-tasks
+
+# 3. Analyze JS execution
+uisnap-chrome-trace-analyze snapshots/myapp.com/latest/chrome-trace.db --js-time
+
+# 4. Check layout/paint
+uisnap-chrome-trace-analyze snapshots/myapp.com/latest/chrome-trace.db --layout-paint
+
+# 5. See everything
+uisnap-chrome-trace-analyze snapshots/myapp.com/latest/chrome-trace.db --full
+```
+
+### Canned Queries
+
+#### --long-tasks
+
+Shows tasks exceeding threshold (default 50ms):
+
+```bash
+uisnap-chrome-trace-analyze trace.db --long-tasks
+uisnap-chrome-trace-analyze trace.db --long-tasks --threshold=100  # Custom threshold
+```
+
+**Output**:
+```
+=== Long Tasks (>50ms) ===
+  1. RunTask: 115.27ms (at 1234.56ms)
+  2. EvaluateScript: 87.45ms (at 2456.78ms)
+  3. FunctionCall: 62.33ms (at 3678.90ms)
+```
+
+#### --js-time
+
+Analyzes JavaScript execution breakdown:
+
+```bash
+uisnap-chrome-trace-analyze trace.db --js-time
+```
+
+**Output**:
+```
+=== JavaScript Execution ===
+  FunctionCall:
+    Count: 1624, Total: 1445.67ms, Avg: 0.89ms, Max: 62.33ms
+  EvaluateScript:
+    Count: 47, Total: 339.06ms, Avg: 7.21ms, Max: 87.45ms
+  Total JS time: 1784.73ms
+```
+
+#### --layout-paint
+
+Shows layout and paint operations:
+
+```bash
+uisnap-chrome-trace-analyze trace.db --layout-paint
+```
+
+**Output**:
+```
+=== Layout & Paint ===
+  Paint: 516x, Total: 73.82ms, Avg: 0.14ms
+  Layout: 411x, Total: 53.67ms, Avg: 0.13ms
+  UpdateLayoutTree: 387x, Total: 41.23ms, Avg: 0.11ms
+  RecalculateStyles: 215x, Total: 28.45ms, Avg: 0.13ms
+```
+
+#### --full
+
+Shows all analyses:
+
+```bash
+uisnap-chrome-trace-analyze trace.db --full
+```
+
+Equivalent to: `--long-tasks --js-time --layout-paint`
+
+### Custom SQL Queries
+
+For advanced analysis, query DuckDB directly:
+
+```bash
+# Open database
+duckdb snapshots/myapp.com/latest/chrome-trace.db
+```
+
+#### Database Schema
+
+```sql
+CREATE TABLE tasks (
+  name VARCHAR,        -- Event name (e.g., 'FunctionCall', 'Paint', 'Layout')
+  cat VARCHAR,         -- Category (e.g., 'devtools.timeline', 'v8.execute')
+  ts_ms DOUBLE,        -- Timestamp in milliseconds
+  dur_ms DOUBLE,       -- Duration in milliseconds
+  pid INTEGER,         -- Process ID
+  tid INTEGER,         -- Thread ID
+  args JSON            -- Additional event arguments
+);
+```
+
+#### Example Queries
+
+**Find slowest paint operations**:
+```sql
+SELECT name, dur_ms, ts_ms
+FROM tasks
+WHERE name LIKE '%Paint%'
+ORDER BY dur_ms DESC
+LIMIT 10;
+```
+
+**Calculate total time by category**:
+```sql
+SELECT cat,
+       COUNT(*) as count,
+       ROUND(SUM(dur_ms), 2) as total_ms,
+       ROUND(AVG(dur_ms), 2) as avg_ms
+FROM tasks
+GROUP BY cat
+ORDER BY total_ms DESC;
+```
+
+**Find tasks during specific time range**:
+```sql
+SELECT name, dur_ms, ts_ms
+FROM tasks
+WHERE ts_ms BETWEEN 1000 AND 2000  -- Between 1-2 seconds
+  AND dur_ms > 10
+ORDER BY ts_ms;
+```
+
+**Identify layout thrashing** (many rapid layouts):
+```sql
+SELECT
+  COUNT(*) as layout_count,
+  MIN(ts_ms) as first_layout,
+  MAX(ts_ms) as last_layout,
+  ROUND(MAX(ts_ms) - MIN(ts_ms), 2) as timespan_ms
+FROM tasks
+WHERE name = 'Layout'
+  AND ts_ms BETWEEN 1000 AND 1100  -- 100ms window
+HAVING COUNT(*) > 10;
+```
+
+**Find functions called most often**:
+```sql
+SELECT name,
+       COUNT(*) as count,
+       ROUND(SUM(dur_ms), 2) as total_ms,
+       ROUND(AVG(dur_ms), 2) as avg_ms
+FROM tasks
+WHERE name LIKE '%Function%'
+GROUP BY name
+ORDER BY count DESC
+LIMIT 20;
+```
+
+**Export results to JSON**:
+```sql
+COPY (
+  SELECT name, dur_ms, ts_ms
+  FROM tasks
+  WHERE dur_ms > 50
+  ORDER BY dur_ms DESC
+) TO 'long-tasks.json';
+```
+
+## Common Performance Patterns
+
+### Pattern 1: Identifying Blocking Tasks
+
+```bash
+# Find long tasks
+uisnap-chrome-trace-analyze trace.db --long-tasks
+
+# If found: "EvaluateScript: 340ms"
+# Indicates: Heavy synchronous script execution blocking the main thread
+# Solution: Break into smaller chunks, use requestIdleCallback, or web workers
+```
+
+### Pattern 2: Layout Thrashing
+
+```bash
+# Check layout operations
+uisnap-chrome-trace-analyze trace.db --layout-paint
+
+# If found: "Layout: 2,340x, Total: 850ms, Avg: 0.36ms"
+# High count + individual operations fast = layout thrashing
+# Cause: Reading layout properties (offsetTop, etc.) in a loop
+# Solution: Batch reads before writes (read all → write all)
+```
+
+### Pattern 3: JavaScript Execution Bottleneck
+
+```bash
+# Analyze JS execution
+uisnap-chrome-trace-analyze trace.db --js-time
+
+# If found: "FunctionCall: 1624x, Total: 1445ms"
+# Indicates: JS execution is main bottleneck
+# Custom query to find hot functions:
+duckdb trace.db "SELECT name, COUNT(*) FROM tasks WHERE name LIKE '%Function%' GROUP BY name ORDER BY COUNT(*) DESC LIMIT 10"
+```
+
+### Pattern 4: Paint Performance
+
+```bash
+# Check paint operations
+uisnap-chrome-trace-analyze trace.db --layout-paint
+
+# If found: "Paint: 516x, each taking 5-10ms"
+# Indicates: Expensive paint operations
+# Causes: Large paint areas, complex CSS (shadows, blurs, gradients)
+# Solution: Use will-change, reduce paint area, simplify styles
+```
+
+## Troubleshooting
+
+### Trace file is huge (>100MB)
+
+**Cause**: Traced too long (>30 seconds) or high-frequency events
+
+**Solution**:
+```javascript
+// Keep traces short (5-10 seconds)
+await utils.startChromeTrace(cdp);
+// ... interactions ...
+await utils.stopChromeTraceAndImport(cdp, tracePath);  // Stop after 5-10s
+```
+
+### Database import fails
+
+**Error**: `Error parsing Chrome trace JSON`
+
+**Cause**: Incomplete or corrupted trace file
+
+**Solution**:
+```bash
+# Check trace file validity
+node -e "const trace = require('./chrome-trace.json'); console.log('Valid JSON, events:', trace.length)"
+
+# If invalid, recapture
+```
+
+### No long tasks found
+
+```bash
+uisnap-chrome-trace-analyze trace.db --long-tasks
+# For details, use:
+#   --long-tasks     Show 0 task(s) over 50ms
+```
+
+**Cause**: Page is actually fast, or threshold is too high
+
+**Solution**:
+```bash
+# Lower threshold
+uisnap-chrome-trace-analyze trace.db --long-tasks --threshold=10
+
+# Or check total JS time
+uisnap-chrome-trace-analyze trace.db --js-time
+```
+
+### Query returns empty results
+
+**Check database has data**:
+```bash
+duckdb trace.db "SELECT COUNT(*) FROM tasks"
+# Should return thousands of events
+
+# If 0, re-import:
+uisnap-chrome-trace-import chrome-trace.json new-trace.db
+```
+
+### "Tasks" table doesn't exist
+
+**Error**: `Error: Catalog Error: Table with name tasks does not exist!`
+
+**Cause**: Opened wrong database or import failed
+
+**Solution**:
+```bash
+# Verify database path
+ls -lh chrome-trace.db
+
+# Re-import if needed
+uisnap-chrome-trace-import chrome-trace.json chrome-trace.db
+```
+
+## Manual Import (Advanced)
+
+If auto-import fails or you have existing trace JSON:
+
+```bash
+uisnap-chrome-trace-import <trace.json> <output.db>
+```
+
+**Example**:
+```bash
+# Import from downloaded Chrome trace
+uisnap-chrome-trace-import ~/Downloads/trace.json analysis.db
+
+# Analyze
+uisnap-chrome-trace-analyze analysis.db --full
+```
+
+The database stays on disk. Query it repeatedly without re-importing.
+
+### Reading the timeline
+
+Events are ordered by `ts_ms` (timestamp in milliseconds):
+
+```
+0ms     - Page load starts
+500ms   - EvaluateScript: 87ms (script execution)
+1200ms  - FunctionCall: 62ms (user code)
+1850ms  - Layout: 15ms (layout calculation)
+2000ms  - Paint: 8ms (rendering)
+```
+
+Use timestamps to correlate with user actions or identify patterns.

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-02
+
+**Initial release of uisnap** (formerly playwright-debug-toolkit)
+
+### Added
+
+#### Core Capture Commands
+- `uisnap snapshot` - Capture full page state (ARIA tree, console, network, web vitals, Chrome trace)
+- `uisnap exec` - Execute custom Playwright scripts for multi-step flows
+- Auto-generated timestamped output directories: `snapshots/{hostname}/{timestamp}/`
+- "latest" symlink for convenience when querying most recent snapshot
+
+#### Analysis Commands
+- `uisnap-analyze-console` - Analyze console logs with summary and grouping by type
+- `uisnap-analyze-network` - Analyze network requests by status, type, domain, and performance
+- `uisnap-query-a11y` - Query accessibility tree by role (buttons, links, headings) or text content
+- `uisnap-chrome-trace-analyze` - Analyze Chrome performance traces with progressive disclosure
+- `uisnap-chrome-trace-import` - Import Chrome trace JSON to DuckDB for custom queries
+
+#### Developer Experience
+- Comprehensive error messages with troubleshooting steps
+- Project root detection (walks up from CWD to find `.git` or `package.json`)
+- Clear output directory logging
+- Support for both auto-generated and explicit output paths
+
+#### Claude Code Integration
+- Skill definition for teaching Claude Code when to use this toolkit
+- Detailed reference documentation for snapshot and trace analysis
+- Installation guide for team sharing vs personal use
+
+#### Performance
+- Token efficiency: ~17x reduction vs traditional DOM debugging
+- Chrome trace: ~18,000x reduction vs raw JSON
+- DuckDB-backed trace storage enables sub-second queries on 36MB+ traces
+
+#### Data Formats
+- YAML accessibility snapshots (Playwright ARIA format)
+- JSONL console and network logs (one JSON object per line)
+- JSON metadata (page title, URL, viewport, timestamp, web vitals)
+- DuckDB trace databases for efficient querying
+
+#### Testing
+- 61 test cases across core runtime, snapshot analysis, and trace analysis
+- Test parallelization for fast CI/CD (10x speedup on unit tests)
+- Comprehensive error handling coverage
+
+### Technical Details
+
+**Supported Node Versions**: >=18.0.0
+
+**Dependencies**:
+- Playwright 1.49.0
+- DuckDB (async)
+- YAML parser
+- adm-zip (for trace handling)
+
+**Output Formats**:
+- `a11y.yaml` - Accessibility tree snapshot
+- `console.jsonl` - Console messages (errors, warnings, logs)
+- `network.jsonl` - Network requests (status, timing, type)
+- `metadata.json` - Page metadata and web vitals
+- `chrome-trace.json` - Chrome DevTools performance trace
+- `chrome-trace.db` - DuckDB database for trace queries
+
+**CLI Commands**:
+- `uisnap` - Main entry point
+- `uisnap-diagnose` - Diagnostic utilities
+- `uisnap-analyze-console` - Console log analysis
+- `uisnap-analyze-network` - Network request analysis
+- `uisnap-query-a11y` - Accessibility tree queries
+- `uisnap-chrome-trace-import` - Import Chrome trace to DuckDB
+- `uisnap-chrome-trace-analyze` - Analyze Chrome trace database
+- `uisnap-trace-import` - Legacy trace import utility
+
+### Known Limitations
+
+- Chromium only (Firefox/WebKit support planned for future releases)
+- Chrome trace import requires DuckDB (automatically installed)
+- Symlinks may not work on Windows (uses `fs.symlinkSync` with `'dir'` type)
+- Sequential execution required for DuckDB operations (file-level WAL locking)
+
+### Documentation
+
+- README.md - User-facing installation and usage guide
+- SKILL-INSTALLATION.md - Guide for installing Claude Code skill
+- `.claude/skills/uisnap/` - Skill definition and reference docs
+- `examples/` - Sample scripts for common debugging workflows
+
+[0.1.0]: https://github.com/tonyhschu/uisnap/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tony Chu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.