ContextScript

A browser-based tool that records user interactions with a website and generates LLM-optimized text transcriptions of the actions performed. Perfect for creating reproducible bug reports that AI assistants can understand.

Features

• Records mouse clicks, keyboard input, scrolling, and more
• Outputs human-readable, LLM-friendly text transcripts
• Real-time streaming to console during recording
• Configurable event categories
• Privacy-aware password masking
• Zero dependencies in production
• Works in any modern browser

Installation

npm

npm install contextscript

import { ContextScript } from 'contextscript';

CDN

<script type="module" src="https://unpkg.com/contextscript/ContextScript.js"></script>

Or use jsdelivr:

<script type="module" src="https://cdn.jsdelivr.net/npm/contextscript/ContextScript.js"></script>

Direct Download

Download ContextScript.js and the modules/ folder, then include locally:

<script type="module" src="ContextScript.js"></script>

Quick Start

After including the script (via npm, CDN, or local file), you can start recording immediately.

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Cmd+Shift+: (Mac) / Ctrl+Shift+: (Windows) | Toggle recording on/off | | Cmd+Escape (Mac) / Ctrl+Escape (Windows) | End recording |

Browser Console

Control recording from the developer console:

ContextScript.start()  // Start recording
ContextScript.end()    // End recording and show transcript

Programmatic API

// Start recording
ContextScript.start();

// ... user performs actions ...

// End and get transcript
const transcript = ContextScript.end();
console.log(transcript);

Configuration

Event Categories

Toggle which events are captured via the console:

ContextScript.help          // Show all available options
ContextScript.mouse = false // Disable mouse/click capture
ContextScript.keyboard = false // Disable keyboard capture
ContextScript.scroll = false   // Disable scroll capture
ContextScript.clipboard = false // Disable clipboard events
ContextScript.form = false     // Disable form events
ContextScript.window = false   // Disable window events
ContextScript.dragdrop = false // Disable drag & drop
ContextScript.media = false    // Disable video/audio events
ContextScript.touch = true     // Enable touch events (off by default)
ContextScript.pointer = true   // Enable pointer events (off by default)
ContextScript.navigation = false // Disable URL navigation tracking (on by default)
ContextScript.developer = false // Disable console/error capture (on by default)

Options

ContextScript.maskPasswords = true  // Mask password input with stars (default: true)
ContextScript.maskPasswords = false // Capture actual password characters

Programmatic Configuration

// Disable categories before recording
ContextScript.mouse = false;
ContextScript.scroll = false;

// Or use the config API
ContextScript.config.setEnabled('mouse', false);
ContextScript.config.isEnabled('keyboard'); // true
ContextScript.config.getEnabledCategories(); // Set { 'mouse', 'keyboard', ... }

// Start recording with current config
ContextScript.start();

Event Categories

Mouse Events

• Click (single, double, right-click)
• Hover states with duration
• Context menu triggers

Keyboard Events

• Typed text (batched for readability)
• Special keys (Enter, Tab, Escape, arrows)
• Backspace/delete with character count
• Select-all and delete combinations

Scroll Events

• Scroll direction and distance
• Debounced for readability

Clipboard Events

• Copy with selected text content
• Cut with selected text content
• Paste operations

Form Events

• Input focus/blur
• Select dropdown changes
• Checkbox/radio toggles
• Text selection
• Form submit/reset
• File input changes

Window Events

• Tab focus/blur (switching tabs)
• Page visibility changes
• Window resize
• Fullscreen changes

Navigation Events (enabled by default)

• URL path changes (pushState/replaceState)
• Hash changes
• Browser back/forward (popstate)

Drag & Drop Events

• Drag start/end with duration
• Drop zone enter/leave
• File drops with count

Media Events

• Video/audio play/pause
• Seeking with debounce
• Volume changes
• Mute/unmute

Touch Events (disabled by default)

• Tap and double-tap
• Long press with duration
• Swipe with direction
• Multi-touch gestures
• Pinch zoom (iOS)

Pointer Events (disabled by default)

• Unified mouse/touch/pen input
• Drag with distance and duration
• Pen pressure support

Developer Events (enabled by default)

• Console output (log, warn, error)
• Network request failures
• Uncaught JavaScript errors

Transcript Output

The transcript is formatted for optimal LLM consumption:

Recording started...
Clicked button#submit-form > div.form-container > main#app
(1.2s later)
Typed "Hello World" in input#username
Pressed Enter
Scrolled down 450px on div#content
(2.5s later)
Clicked a#nav-home.active > nav.main-nav > header#header

Recording ended. Total duration: 8.3s

Features:

• CSS selector paths for clicked elements
• Time gaps shown for context
• Typed text grouped for readability
• Total recording duration

API Reference

ContextScript Methods

| Method | Description | |--------|-------------| | ContextScript.start() | Begin recording | | ContextScript.end() | End recording and show transcript | | ContextScript.end({ silent: true }) | End recording and return transcript without UI | | ContextScript.isRecording | Boolean indicating recording state | | ContextScript.getTranscript(format) | Get transcript without ending (format: 'plaintext', 'json', 'xml', 'xmltags', 'markdown') | | ContextScript.getEvents() | Get raw events array | | ContextScript.prompt(options) | Show instruction overlay and optionally start recording (see AGENT_README) | | ContextScript.help | Show available options in console | | ContextScript.shortcut | Get or set the launch shortcut (default: 'Cmd+Shift+:') | | ContextScript.resetShortcut() | Reset the launch shortcut to default |

Keyboard Shortcuts

| Shortcut | Description | |----------|-------------| | Cmd+Shift+: (Mac) / Ctrl+Shift+: (Windows) | Toggle recording on/off | | Cmd+Escape | End recording |

Configuration

| Property | Description | |----------|-------------| | ContextScript.config | Access to Configuration instance | | ContextScript.streamToConsole | Boolean to enable/disable live streaming (default: true) |

Configuration Instance

| Method | Description | |--------|-------------| | isEnabled(category) | Check if category is enabled | | setEnabled(category, bool) | Enable/disable a category | | hasCategory(category) | Check if category exists | | getState() | Get all category states | | getEnabledCategories() | Get Set of enabled categories | | showHelp() | Display help in console |

Security & Privacy

• Password input is automatically masked with * characters
• Sensitive form fields are identified by type="password"
• Disable password masking only for testing: ContextScript.maskPasswords = false
• No data is sent to external servers - all processing is local

Use Cases

• Bug Reports — Generate transcripts that help AI assistants understand and reproduce bugs with exact action sequences and timing
• QA Documentation — Record manual test procedures as references for automation engineers writing Playwright/Cypress tests
• UX Analysis — Analyze user interaction patterns; record logs of user interations in human readable plaintext.
• AI Assistant Context — Paste transcripts into Claude/ChatGPT for debugging help with full action context
• Tutorial Generation — Convert recorded interactions into step-by-step documentation
• Performance Monitoring — Enable developer events to correlate user actions with console errors and network failures

Using ContextScript with AI Coding Agents

ContextScript can be used with AI coding agents to capture user demonstrations for debugging and testing. See AGENT_README.md for integration workflows, the prompt() API, and complete examples using Playwright.

Programmatic / Headless Mode

ContextScript supports silent operation for automation tools and LLMs that need to capture user interactions programmatically.

Silent API

// End recording without UI dialog
const transcript = ContextScript.end({ silent: true });

// Get transcript in specific format: 'plaintext' (default), 'json', 'xml', 'xmltags', 'markdown'
const json = ContextScript.end({ silent: true, format: 'json' });

// Peek at transcript without ending
const current = ContextScript.getTranscript('json');

// Get raw events array
const events = ContextScript.getEvents();

Browser Automation Example (Playwright)

The pattern is the same for any automation tool—only the JS execution syntax differs:

const { chromium } = require('playwright');

const browser = await chromium.launch({ headless: false });
const page = await browser.newPage();
await page.goto('https://your-app.com');

// Start recording
await page.evaluate(() => window.ContextScript.start());

// Wait for user to finish (Cmd+Escape to end)
await page.waitForFunction(() => !window.ContextScript.isRecording);

// Capture transcript
const transcript = await page.evaluate(() =>
  window.ContextScript.getTranscript('json')
);

Browser Close Handling

If the browser closes while recording, the transcript is automatically dumped to console with clear markers for capture by automation tools.

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! See DEVELOPMENT.md for setup instructions, architecture details, and contribution guidelines.