browsertrack 0.0.1 → 0.1.1

package/docs/incidents-diagnostics.md

@@ -0,0 +1,61 @@
+---
+title: Incidents & Diagnostics
+description: Automatic error grouping, runtime crash diagnostics, network tracking, and interaction breadcrumbs
+order: 4
+---
+
+# Incidents & Diagnostics ⚠️
+
+BrowserTrack continuously captures runtime errors, unhandled promise rejections, console warnings/errors, failed network calls, and user interaction breadcrumbs.
+
+---
+
+## ⚡ Automatic Error Grouping (Incidents)
+
+Instead of overwhelming AI agents with duplicate errors, BrowserTrack uses intelligent fingerprinting:
+- Grouped by `errorType`, normalized message, and source file line/column.
+- Tracks `occurrences`, `firstSeen`, and `lastSeen` timestamps.
+- Captures stack traces, route, and surrounding DOM state.
+
+---
+
+## 🍞 User Interaction Breadcrumbs
+
+BrowserTrack maintains a bounded chronological timeline of events leading up to an error:
+- **User Clicks**: Target selector, tag, text, and timestamp.
+- **Form Focus/Blur**: Inputs engaged prior to crash (values are never recorded).
+- **SPA & Browser Navigation**: `history.pushState` and URL route changes.
+- **Console Logs**: `console.log`, `console.warn`, `console.error`.
+- **Network Requests**: Method, URL, status code, and duration.
+
+---
+
+## 🌐 Network Failure Tracking
+
+Failed HTTP requests (`4xx`, `5xx`, timeouts, and aborts) are captured with:
+- Request method and sanitized URL (sensitive query parameters redacted by `@visulima/redact`).
+- HTTP status code and response duration in ms.
+- Error status and aborted flags.
+
+---
+
+## 🤖 Diagnostics Workflow for Coding Agents
+
+```mermaid
+sequenceDiagram
+    participant Agent as AI Coding Agent
+    participant MCP as BrowserTrack MCP
+    participant Daemon as Local Daemon
+    participant Browser as Browser Client
+
+    Agent->>MCP: list_incidents({ status: "OPEN" })
+    MCP->>Daemon: Query incidents from SQLite
+    Daemon-->>Agent: Returns grouped incidents
+    Agent->>MCP: get_incident({ incidentId: "inc_xxx" })
+    MCP-->>Agent: Stack trace, source line, breadcrumbs, screenshot
+    Agent->>Agent: Modifies code to fix bug
+    Agent->>MCP: verify_incident({ incidentId: "inc_xxx" })
+    MCP->>Browser: Dispatches reload & executes probes
+    Browser-->>Daemon: Reports runtime status & captures screenshot
+    Daemon-->>Agent: Verdict (VERIFIED / FAILED)
+```

package/docs/index.md

@@ -0,0 +1,46 @@
+---
+title: Introduction
+description: Overview of BrowserTrack - local browser diagnostics bridge for AI coding agents via MCP
+order: 1
+---
+
+# BrowserTrack 🔍
+
+> **Local browser diagnostics shared with AI coding agents through Model Context Protocol (MCP).**
+
+BrowserTrack is a lightweight, framework-agnostic local development daemon and MCP bridge. It continuously captures browser runtime errors, unhandled promise rejections, console logs, network failures (4xx/5xx), user interaction breadcrumbs, live DOM snapshots, and visual design annotations—making them instantly accessible to AI coding assistants (Antigravity, Cursor, Claude Code, Windsurf) for autonomous debugging and closed-loop verification.
+
+---
+
+## ⚡ Why BrowserTrack?
+
+Traditional browser debugging with AI coding agents relies on manual copy-pasting of truncated error messages or sending cropped screenshots. BrowserTrack removes the human in the middle:
+
+- 🚀 **Real-time Diagnostics Pipeline**: Your browser communicates with the local daemon via WebSockets.
+- 🎯 **Visual Annotations & Notes**: Hold <kbd>Alt</kbd> and click any element (or drag a region) to leave notes with DOM context and screenshots directly for coding agents.
+- 📌 **Persistent On-Screen Markers**: Visual note pins appear directly on your web pages and can be inspected or resolved with a single click.
+- 🤖 **Closed-Loop Verification**: After an agent edits your code, it automatically reloads the browser, executes verification probes, checks for regressions, and captures before/after screenshots.
+- 🛡️ **Zero-Leak Security**: Integrated with `@visulima/redact` to automatically sanitize passwords, auth tokens, cookies, credit cards, and secret query parameters.
+
+---
+
+## 🏗️ Architecture Overview
+
+```mermaid
+graph TD
+    A[Browser Client<br>Vanilla / React / Vue / Vite] <-->|WebSocket ws://127.0.0.1:7331| B[Local Daemon<br>SQLite Storage + Verification Engine]
+    B <-->|Model Context Protocol / stdio| C[AI Coding Agents<br>Antigravity / Cursor / Claude Code]
+    B -->|Static Docs & Web UI| D[Local Dashboard / Dev Server]
+```
+
+---
+
+## 🚀 Quick Navigation
+
+- [Getting Started](./getting-started.md) — Quick installation and setup in under 2 minutes.
+- [Visual Notes & Annotations](./visual-notes.md) — Screen notes, region selection, and persistent markers.
+- [Incidents & Error Diagnostics](./incidents-diagnostics.md) — Ingest runtime errors, stack traces, and breadcrumbs.
+- [Closed-Loop Verification](./closed-loop-verification.md) — Automated bug-fix and layout verification.
+- [MCP Tool Reference](./mcp-reference.md) — Complete guide to all 16 MCP tools.
+- [Security & Redaction](./security-privacy.md) — Privacy architecture and `@visulima/redact` integration.
+- [CLI Reference](./cli.md) — Command-line interface usage.

package/docs/mcp-reference.md

@@ -0,0 +1,128 @@
+---
+title: MCP Tool Reference
+description: Complete reference for all 16 Model Context Protocol (MCP) tools exposed to AI coding agents
+order: 6
+---
+
+# MCP Tool Reference 🛠️
+
+BrowserTrack exposes 16 specialized Model Context Protocol (MCP) tools for AI agents.
+
+---
+
+## 📋 Incidents & Error Diagnostics
+
+### `list_incidents`
+Lists recorded browser runtime errors, unhandled rejections, and console errors grouped into incidents.
+- **Arguments**:
+  - `status` (`string`): Filter by `OPEN`, `FIX_ATTEMPTED`, `VERIFYING`, `VERIFIED`, `FAILED`, `INCONCLUSIVE`.
+  - `severity` (`string`): Filter by `error`, `warn`, `fatal`.
+  - `projectId` (`string`): Filter by project ID or name.
+  - `limit` (`number`): Max number of incidents (default: 20).
+
+### `get_incident`
+Retrieves compact, high-signal debugging context for an error incident.
+- **Arguments**:
+  - `incidentId` (`string`, *required*): The unique ID of the incident (e.g. `inc_19a31a28`).
+- **Returns**: Stack trace, normalized error message, breadcrumbs timeline, failed network calls, last interacted element, error screenshot.
+
+### `get_console`
+Fetches recent console logs, warnings, and errors from a browser session.
+- **Arguments**:
+  - `sessionId` (`string`): Browser session ID (optional, defaults to active session).
+  - `limit` (`number`): Number of logs to retrieve (default: 30).
+
+### `get_network_failures`
+Retrieves recent failed HTTP requests (4xx, 5xx, timeouts, aborts).
+- **Arguments**:
+  - `sessionId` (`string`): Browser session ID (optional).
+  - `limit` (`number`): Maximum number of failed requests (default: 20).
+
+### `get_breadcrumbs`
+Retrieves the chronological user interaction timeline leading up to an error.
+- **Arguments**:
+  - `incidentId` (`string`): Associated incident ID.
+  - `sessionId` (`string`): Browser session ID.
+  - `limit` (`number`): Max breadcrumbs (default: 50).
+
+### `get_page_state`
+Queries live DOM and URL state from the connected browser tab.
+- **Arguments**:
+  - `sessionId` (`string`): Target session ID (optional).
+
+### `capture_element`
+Captures an on-demand screenshot of a specific DOM element or the entire visible page.
+- **Arguments**:
+  - `selector` (`string`): CSS selector of the target element.
+  - `sessionId` (`string`): Browser session ID (optional).
+
+---
+
+## 📝 Visual Notes & Layout Tools
+
+### `list_notes`
+Lists visual annotations left on elements, regions, or pages during development.
+- **Arguments**:
+  - `status` (`string`): `OPEN`, `IN_PROGRESS`, `VERIFYING`, `RESOLVED`, `FAILED`, `INCONCLUSIVE` (default: `OPEN`).
+  - `projectId` (`string`): Filter by project ID or name.
+  - `limit` (`number`): Max notes (default: 20).
+
+### `get_note`
+Retrieves full debugging context for a visual note.
+- **Arguments**:
+  - `noteId` (`string`, *required*): The unique ID of the visual note (e.g. `note_30a89599`).
+- **Returns**: Note message, route, viewport dimensions, target element selector, DOM context, screenshot file path.
+
+### `capture_note_context`
+Inspects live DOM context, bounding box, overflow, and computed styles for a target element.
+- **Arguments**:
+  - `selector` (`string`, *required*): CSS selector of target element.
+  - `sessionId` (`string`): Browser session ID (optional).
+
+### `verify_note`
+Runs closed-loop layout verification (visibility, viewport overflow, geometry delta, after-screenshot).
+- **Arguments**:
+  - `noteId` (`string`, *required*): The ID of the visual note to verify.
+  - `observationWindowMs` (`number`): Observation window in ms (default: 1000).
+
+### `get_note_verification`
+Retrieves latest layout verification verdict, screenshots, and geometry diff.
+- **Arguments**:
+  - `noteId` (`string`, *required*): The ID of the visual note.
+
+### `resolve_note`
+Marks a visual note as `RESOLVED`.
+- **Arguments**:
+  - `noteId` (`string`, *required*): The ID of the visual note.
+
+### `reopen_note`
+Reopens a previously resolved visual note.
+- **Arguments**:
+  - `noteId` (`string`, *required*): The ID of the visual note.
+
+---
+
+## 🎛️ Session & Project Management
+
+### `list_projects`
+Lists all registered development projects and mapped filesystem paths.
+
+### `list_sessions`
+Lists active and recent browser tabs connected to the local development daemon.
+- **Arguments**:
+  - `projectId` (`string`): Filter sessions by project ID or name.
+  - `activeOnly` (`boolean`): Show only active WebSocket sessions (default: `true`).
+
+### `verify_incident`
+Triggers closed-loop bug fix verification (reloads browser, evaluates probes, captures after-screenshot).
+- **Arguments**:
+  - `incidentId` (`string`, *required*): The ID of the incident.
+  - `route` (`string`): Optional route to navigate to.
+  - `targetSelector` (`string`): Optional element selector to inspect.
+  - `expect` (`array`): Optional verification probes (`no_incident`, `element_exists`, `element_visible`, `text_contains`, `route_is`).
+  - `observationWindowMs` (`number`): Observation window in ms (default: 2000).
+
+### `get_verification`
+Retrieves latest verification result and before/after screenshots for an incident.
+- **Arguments**:
+  - `incidentId` (`string`, *required*): The ID of the incident.

package/docs/security-privacy.md

@@ -0,0 +1,32 @@
+---
+title: Security & Privacy
+description: Security architecture, localhost binding, form value exclusion, and @visulima/redact sensitive data sanitization
+order: 7
+---
+
+# Security & Privacy 🛡️
+
+BrowserTrack is built with privacy-by-design principles to ensure sensitive developer tokens, credentials, and user data never leak to AI models or external servers.
+
+---
+
+## 🔒 Core Security Principles
+
+### 1. Strictly Localhost Bound
+- The daemon binds exclusively to `127.0.0.1`.
+- It cannot be reached from the public internet or external local network devices.
+
+### 2. Comprehensive Sensitive Data Masking (@visulima/redact)
+BrowserTrack integrates `@visulima/redact` to automatically scan and sanitize payloads before saving to SQLite or returning to MCP:
+- **Authentication & Headers**: `Authorization` (Bearer tokens, Basic auth), `Cookie`, `Set-Cookie`.
+- **API Keys & Credentials**: AWS Access Keys (`AKIA...`), Slack tokens (`xoxb-...`), JWTs (`eyJ...`), `private_key`, `secret`.
+- **Financial & Personal Data**: Credit card numbers, CVV/CVD, SSN / Social Security Numbers.
+- **Sensitive URL Parameters**: Query strings containing `token`, `key`, `apiKey`, `auth`, `secret`, `password`, `signature` are converted to `[REDACTED]`.
+
+### 3. No Form Input Recording
+- Values inside `<input>` and `<textarea>` fields are never read or stored.
+- Password inputs (`<input type="password">`) in DOM snapshot clones are explicitly sanitized to `value="[REDACTED]"`.
+
+### 4. Zero Request/Response Payloads
+- Network event interceptors capture only URL endpoints, HTTP methods, status codes, and latency.
+- Request and response body payloads are disabled by default.

package/docs/visual-notes.md

@@ -0,0 +1,67 @@
+---
+title: Visual Notes & Annotations
+description: Visual annotations, element hover notes, drag-and-drop region notes, and persistent on-screen pins
+order: 3
+---
+
+# Visual Notes & Screen Annotations 📝
+
+BrowserTrack enables developers and designers to leave visual feedback directly on DOM elements, custom screen regions, or full pages without leaving the browser.
+
+---
+
+## 🎯 Annotation Modes
+
+### 1. Element Notes (Alt + Click)
+- **How to use**: Hold <kbd>Alt</kbd> and hover over any element on the page. The element will highlight with its semantic CSS selector and dimensions. Click to open the note editor.
+- Alternatively, click the **🎯 Element** button in the floating toolbar.
+- **Context captured**:
+  - Semantic CSS selector (e.g. `[data-testid="stats-banner"]` or `#user-card`)
+  - Element dimensions and bounding rectangle (`x`, `y`, `width`, `height`)
+  - Sanitized outerHTML and DOM hierarchy
+  - Viewport dimensions and scroll offsets
+  - Element screenshot snapshot
+
+### 2. Region / Area Notes (Drag & Drop)
+- **How to use**: Click the **📐 Region** button in the floating toolbar.
+- Drag a bounding rectangle over any area on the screen.
+- A top banner will appear with a **✕ Cancel (Esc)** button.
+- Releasing the mouse opens the note modal with the cropped region screenshot and coordinates.
+
+### 3. Full-Page Notes
+- **How to use**: Click the **📄 Page** button in the toolbar.
+- Captures the entire page viewport state, URL route, and document context.
+
+---
+
+## 📌 Persistent On-Screen Markers
+
+When your application loads or syncs with the daemon:
+- BrowserTrack automatically fetches all open notes for the project.
+- **Element Pins (`📝 #1`)**: Placed at the top-left of each annotated element. Hovering highlights the element.
+- **Region Outlines (`📐 #2`)**: Renders a clean dashed boundary box around the selected area.
+- **Page Notes (`📄`)**: Pinned at the top right of the viewport.
+- **Responsive Tracking**: Markers dynamically stay anchored to elements as the page scrolls or resizes.
+
+---
+
+## 🔍 Interactive Popover Details Card
+
+Clicking on any note marker opens the Note Details Card:
+
+- **Full Message**: Displays the complete text/instruction.
+- **Target Metadata**: Viewport dimensions, target selector, and creation timestamp.
+- **Action Buttons**:
+  - **`✅ Resolve Note`**: Marks the note as `RESOLVED` in real time.
+  - **`🗑️ Delete Note`**: Removes the note permanently from the database.
+  - **`✕ Close`**: Closes the popover.
+
+---
+
+## 🛠️ Toolbar Controls
+
+The bottom-right floating toolbar gives quick access:
+- **`🎯 Element`**: Toggle element inspection mode.
+- **`📐 Region`**: Activate rectangle drag mode.
+- **`📄 Page`**: Open full-page note modal.
+- **`📌 Notes (N)`**: Toggle visibility of all note markers on screen.

package/examples/test-app/index.html

@@ -0,0 +1,299 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>BrowserTrack Fixture App</title>
+  <style>
+    :root {
+      --bg: #0f172a;
+      --card-bg: #1e293b;
+      --text: #f8fafc;
+      --muted: #94a3b8;
+      --primary: #3b82f6;
+      --danger: #ef4444;
+      --warning: #f59e0b;
+      --success: #10b981;
+      --border: #334155;
+    }
+
+    * { box-sizing: border-box; margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+    body { background-color: var(--bg); color: var(--text); padding: 2rem; display: flex; flex-direction: column; align-items: center; min-height: 100vh; }
+    .container { max-width: 800px; width: 100%; display: flex; flex-direction: column; gap: 1.5rem; }
+    
+    header { border-bottom: 1px solid var(--border); padding-bottom: 1rem; display: flex; justify-content: space-between; align-items: center; }
+    h1 { font-size: 1.5rem; font-weight: 600; display: flex; align-items: center; gap: 0.5rem; }
+    .badge { font-size: 0.75rem; padding: 0.2rem 0.6rem; border-radius: 999px; background: rgba(59, 130, 246, 0.2); color: var(--primary); border: 1px solid var(--primary); }
+    
+    .card { background: var(--card-bg); border: 1px solid var(--border); border-radius: 0.75rem; padding: 1.25rem; }
+    .card-title { font-size: 1rem; font-weight: 600; margin-bottom: 0.75rem; color: var(--muted); text-transform: uppercase; letter-spacing: 0.05em; }
+
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 0.75rem; }
+    
+    button {
+      padding: 0.75rem 1rem;
+      border-radius: 0.5rem;
+      border: 1px solid transparent;
+      font-weight: 500;
+      cursor: pointer;
+      transition: all 0.15s ease-in-out;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      gap: 0.5rem;
+      font-size: 0.9rem;
+    }
+    button:hover { filter: brightness(1.1); transform: translateY(-1px); }
+    button:active { transform: translateY(0); }
+
+    .btn-danger { background: rgba(239, 68, 68, 0.15); color: #fca5a5; border-color: rgba(239, 68, 68, 0.3); }
+    .btn-warning { background: rgba(245, 158, 11, 0.15); color: #fcd34d; border-color: rgba(245, 158, 11, 0.3); }
+    .btn-primary { background: rgba(59, 130, 246, 0.15); color: #93c5fd; border-color: rgba(59, 130, 246, 0.3); }
+    .btn-success { background: rgba(16, 185, 129, 0.15); color: #6ee7b7; border-color: rgba(16, 185, 129, 0.3); }
+
+    .element-card {
+      border: 2px dashed rgba(239, 68, 68, 0.4);
+      background: rgba(239, 68, 68, 0.05);
+      padding: 1rem;
+      border-radius: 0.5rem;
+      margin-top: 0.5rem;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    }
+
+    #log-panel {
+      background: #090d16;
+      border: 1px solid var(--border);
+      border-radius: 0.5rem;
+      padding: 0.75rem;
+      font-family: monospace;
+      font-size: 0.8rem;
+      max-height: 180px;
+      overflow-y: auto;
+      color: #38bdf8;
+    }
+    .log-item { margin-bottom: 0.3rem; }
+  </style>
+
+  <!-- BrowserTrack Client Auto-Injection -->
+  <script src="http://127.0.0.1:7331/client.js"></script>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1>🧪 BrowserTrack Fixture App</h1>
+      <span class="badge" id="status-badge">Connecting...</span>
+    </header>
+
+    <!-- Error Triggers Card -->
+    <div class="card">
+      <div class="card-title">1. Runtime & Console Triggers</div>
+      <div class="grid">
+        <button class="btn-danger" id="btn-throw-error" data-testid="throw-error-btn">
+          💥 Throw Error
+        </button>
+        <button class="btn-danger" id="btn-unhandled-promise" data-testid="unhandled-promise-btn">
+          ⚠️ Unhandled Promise
+        </button>
+        <button class="btn-warning" id="btn-console-error" data-testid="console-error-btn">
+          📝 Console Error
+        </button>
+        <button class="btn-warning" id="btn-console-warn" data-testid="console-warn-btn">
+          ⚠️ Console Warn
+        </button>
+      </div>
+    </div>
+
+    <!-- Network Triggers Card -->
+    <div class="card">
+      <div class="card-title">2. Network & Async Triggers</div>
+      <div class="grid">
+        <button class="btn-danger" id="btn-500-request" data-testid="fail-500-btn">
+          🌐 500 Network Request
+        </button>
+        <button class="btn-danger" id="btn-delayed-error" data-testid="delayed-error-btn">
+          ⏱️ Delayed Error (1s)
+        </button>
+        <button class="btn-primary" id="btn-navigate" data-testid="navigate-btn">
+          🔀 Navigate /users/42
+        </button>
+      </div>
+    </div>
+
+    <!-- Element Error with Visual Card -->
+    <div class="card">
+      <div class="card-title">3. Element Target & Verification Probe</div>
+      <div class="element-card" id="user-card" data-testid="user-card">
+        <div>
+          <strong id="user-name">User: John Doe (#42)</strong>
+          <p style="color: var(--muted); font-size: 0.85rem;" id="user-status">Status: Active</p>
+        </div>
+        <button class="btn-danger" id="btn-element-error" data-testid="element-error-btn">
+          Trigger Element Error
+        </button>
+      </div>
+    </div>
+
+    <!-- Visual Notes & Layout Cards -->
+    <div class="card">
+      <div class="card-title">4. Visual Notes & Responsive Layout (Alt+Click to Annotate)</div>
+      <p style="font-size: 0.85rem; color: var(--muted); margin-bottom: 0.75rem;">
+        Hold <kbd style="background:#334155;padding:2px 5px;border-radius:3px;">Alt</kbd> and click any element below to leave a visual note for coding agents.
+      </p>
+
+      <!-- Overflowing Stats Card (Simulating mobile layout issue) -->
+      <div class="stats-card" id="stats-banner" data-testid="stats-banner" style="background:#1e1b4b;border:1px solid #4338ca;padding:1rem;border-radius:0.5rem;display:flex;gap:1.5rem;min-width:600px;overflow-x:auto;">
+        <div>
+          <div style="font-size:0.75rem;color:#a5b4fc;">MONTHLY ACTIVE USERS</div>
+          <div style="font-size:1.4rem;font-weight:700;color:#e0e7ff;">142,890</div>
+        </div>
+        <div>
+          <div style="font-size:0.75rem;color:#a5b4fc;">PAGEVIEWS (30D)</div>
+          <div style="font-size:1.4rem;font-weight:700;color:#e0e7ff;">1,249,000</div>
+        </div>
+        <div>
+          <div style="font-size:0.75rem;color:#a5b4fc;">SERVER RESPONSE TIME</div>
+          <div style="font-size:1.4rem;font-weight:700;color:#e0e7ff;">42ms</div>
+        </div>
+      </div>
+
+      <!-- Sensitive Input masking demonstration -->
+      <div style="margin-top:1rem;display:flex;gap:0.75rem;align-items:center;flex-wrap:wrap;">
+        <input type="password" id="admin-pass" value="super-secret-password" data-testid="admin-pass-input" style="background:#0f172a;color:#f8fafc;border:1px solid #334155;border-radius:4px;padding:6px 10px;font-size:12px;" />
+        <button class="btn-primary" id="btn-manual-note" style="padding:6px 12px;font-size:12px;">
+          📝 Note on Stats
+        </button>
+        <button class="btn-primary" id="btn-select-element" style="padding:6px 12px;font-size:12px;background:rgba(59,130,246,0.25);">
+          🎯 Element Seç
+        </button>
+        <button class="btn-primary" id="btn-select-region" style="padding:6px 12px;font-size:12px;background:rgba(56,189,248,0.25);color:#38bdf8;">
+          📐 Alan / Bölge Seç (Drag)
+        </button>
+        <button class="btn-primary" id="btn-page-note" style="padding:6px 12px;font-size:12px;background:rgba(168,85,247,0.25);color:#c084fc;">
+          📄 Tüm Sayfa
+        </button>
+      </div>
+    </div>
+
+    <!-- Live Event Log -->
+    <div class="card">
+      <div class="card-title">Event Log</div>
+      <div id="log-panel">
+        <div class="log-item">[Init] Fixture app loaded. Ready for diagnostics testing.</div>
+      </div>
+    </div>
+  </div>
+
+  <script>
+    const logPanel = document.getElementById('log-panel');
+    function appendLog(msg) {
+      const div = document.createElement('div');
+      div.className = 'log-item';
+      div.textContent = `[${new Date().toLocaleTimeString()}] ${msg}`;
+      logPanel.appendChild(div);
+      logPanel.scrollTop = logPanel.scrollHeight;
+    }
+
+    // 1. Throw Error
+    document.getElementById('btn-throw-error').addEventListener('click', () => {
+      appendLog('Throwing synchronous Error');
+      throw new TypeError("Cannot read properties of undefined (reading 'calculateTotal')");
+    });
+
+    // 2. Unhandled Promise
+    document.getElementById('btn-unhandled-promise').addEventListener('click', () => {
+      appendLog('Triggering Unhandled Promise Rejection');
+      new Promise((_, reject) => {
+        reject(new Error("API authentication session expired (token expired)"));
+      });
+    });
+
+    // 3. Console Error
+    document.getElementById('btn-console-error').addEventListener('click', () => {
+      appendLog('Logging console.error');
+      console.error("Failed to render UserProfileComponent: missing user data", { id: 42, role: 'developer' });
+    });
+
+    // 4. Console Warn
+    document.getElementById('btn-console-warn').addEventListener('click', () => {
+      appendLog('Logging console.warn');
+      console.warn("Component UserCard is using deprecated prop 'legacyFormat'");
+    });
+
+    // 5. 500 Network Request
+    document.getElementById('btn-500-request').addEventListener('click', async () => {
+      appendLog('Sending fetch request to failing endpoint');
+      try {
+        await fetch('http://127.0.0.1:7331/api/invalid-endpoint-trigger-404?token=secret123');
+      } catch (e) {
+        console.error('Fetch threw error:', e);
+      }
+    });
+
+    // 6. Delayed Error
+    document.getElementById('btn-delayed-error').addEventListener('click', () => {
+      appendLog('Scheduled delayed error in 1000ms');
+      setTimeout(() => {
+        throw new ReferenceError("UserProfileService is not defined at background poll");
+      }, 1000);
+    });
+
+    // 7. SPA Navigation
+    document.getElementById('btn-navigate').addEventListener('click', () => {
+      const newUrl = '/users/42';
+      history.pushState({ page: 42 }, 'User Profile', newUrl);
+      appendLog(`Navigated history.pushState to ${newUrl}`);
+    });
+
+    // 8. Element Error
+    document.getElementById('btn-element-error').addEventListener('click', () => {
+      appendLog('Triggering error on user-card element');
+      throw new Error("Element user-card encountered unexpected state rendering card");
+    });
+
+    // 9. Manual Visual Note triggers
+    document.getElementById('btn-manual-note').addEventListener('click', () => {
+      appendLog('Opening visual note editor on stats-banner');
+      const stats = document.getElementById('stats-banner');
+      if (window.__BROWSERTRACK__?.getClient()) {
+        window.__BROWSERTRACK__.getClient().openNoteEditor(stats);
+      }
+    });
+
+    document.getElementById('btn-select-element').addEventListener('click', () => {
+      appendLog('Activated Element selection mode (click any element)');
+      if (window.__BROWSERTRACK__?.getClient()) {
+        window.__BROWSERTRACK__.getClient().startElementSelection();
+      }
+    });
+
+    document.getElementById('btn-select-region').addEventListener('click', () => {
+      appendLog('Activated Region selection mode (drag rectangle on screen)');
+      if (window.__BROWSERTRACK__?.getClient()) {
+        window.__BROWSERTRACK__.getClient().startRegionSelection();
+      }
+    });
+
+    document.getElementById('btn-page-note').addEventListener('click', () => {
+      appendLog('Opening full page note editor');
+      if (window.__BROWSERTRACK__?.getClient()) {
+        window.__BROWSERTRACK__.getClient().openNoteEditor(document.body, 'page');
+      }
+    });
+
+    // Check client status
+    setInterval(() => {
+      const badge = document.getElementById('status-badge');
+      if (window.__BROWSERTRACK__ && window.__BROWSERTRACK__.getClient()) {
+        badge.textContent = '🟢 BrowserTrack Active';
+        badge.style.borderColor = 'var(--success)';
+        badge.style.color = 'var(--success)';
+        badge.style.background = 'rgba(16, 185, 129, 0.2)';
+      } else {
+        badge.textContent = '⚪ Daemon Offline (Safe)';
+      }
+    }, 1000);
+  </script>
+</body>
+</html>