browsertrack 0.0.1 → 0.1.1

package/dist/notes-CBvN91Wf.d.ts

@@ -0,0 +1,260 @@
+type EventType = 'runtime_error' | 'unhandled_rejection' | 'console' | 'fetch' | 'xhr' | 'navigation' | 'interaction';
+type ConsoleLevel = 'error' | 'warn' | 'info' | 'log' | 'debug';
+interface ElementSummary {
+    selector: string;
+    tag: string;
+    id?: string;
+    classes?: string[];
+    attributes?: Record<string, string>;
+    outerHTML?: string;
+    innerText?: string;
+    boundingRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+    };
+    visible: boolean;
+}
+interface Breadcrumb {
+    id?: string;
+    type: 'navigation' | 'click' | 'submit' | 'fetch' | 'xhr' | 'console' | 'error';
+    category?: string;
+    message: string;
+    timestamp: number;
+    level?: 'info' | 'warn' | 'error';
+    data?: Record<string, any>;
+    element?: ElementSummary;
+}
+interface NetworkEvent {
+    id?: string;
+    url: string;
+    method: string;
+    status?: number;
+    statusText?: string;
+    durationMs: number;
+    error?: string;
+    aborted?: boolean;
+    timestamp: number;
+    requestHeaders?: Record<string, string>;
+}
+interface RuntimeErrorEvent {
+    message: string;
+    stack?: string;
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+    errorType: string;
+    timestamp: number;
+}
+interface ConsoleEvent {
+    level: ConsoleLevel;
+    message: string;
+    args?: any[];
+    stack?: string;
+    timestamp: number;
+}
+interface NavigationEvent {
+    from?: string;
+    to: string;
+    type: 'pushState' | 'replaceState' | 'popstate' | 'hashchange' | 'initial';
+    timestamp: number;
+}
+interface HelloMessage {
+    type: 'hello';
+    origin: string;
+    url: string;
+    title: string;
+    userAgent: string;
+    timestamp: number;
+    projectId?: string;
+}
+interface ClientEventMessage {
+    type: 'event';
+    sessionId: string;
+    eventType: EventType;
+    payload: RuntimeErrorEvent | ConsoleEvent | NetworkEvent | NavigationEvent | Breadcrumb;
+    breadcrumbs?: Breadcrumb[];
+    lastElement?: ElementSummary;
+    route?: string;
+    url: string;
+    title?: string;
+    timestamp: number;
+}
+
+type CommandType = 'reload' | 'navigate' | 'get_page_state' | 'query_element' | 'capture_element' | 'check_overflow' | 'get_element_rect' | 'get_element_style';
+interface ClientCommand<T = any> {
+    id: string;
+    type: CommandType;
+    params?: T;
+}
+interface ReloadParams {
+    force?: boolean;
+}
+interface NavigateParams {
+    url: string;
+}
+interface QueryElementParams {
+    selector: string;
+}
+interface CaptureElementParams {
+    selector?: string;
+}
+interface QueryElementResult {
+    exists: boolean;
+    visible?: boolean;
+    tag?: string;
+    id?: string;
+    classes?: string[];
+    boundingRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+    };
+    innerText?: string;
+    outerHTML?: string;
+}
+interface PageStateResult {
+    url: string;
+    route: string;
+    title: string;
+    readyState: string;
+    activeElement?: ElementSummary;
+}
+interface CaptureElementResult {
+    dataUrl?: string;
+    format?: string;
+    width?: number;
+    height?: number;
+}
+interface OverflowCheckResult {
+    selector: string;
+    overflow: boolean;
+    viewportWidth: number;
+    viewportHeight: number;
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+    };
+    overflowRightPx: number;
+    overflowBottomPx: number;
+    parentOverflow?: boolean;
+}
+interface ElementStyleResult {
+    selector: string;
+    styles: Record<string, string>;
+}
+interface CommandResponse<T = any> {
+    id: string;
+    ok: boolean;
+    result?: T;
+    error?: string;
+    reason?: string;
+}
+
+type NoteType = 'element' | 'region' | 'page';
+type NoteStatus = 'OPEN' | 'IN_PROGRESS' | 'VERIFYING' | 'READY_FOR_REVIEW' | 'VERIFIED' | 'RESOLVED' | 'FAILED' | 'INCONCLUSIVE';
+interface ViewportContext {
+    width: number;
+    height: number;
+    devicePixelRatio: number;
+}
+interface ScrollContext {
+    scrollX: number;
+    scrollY: number;
+}
+interface DOMRectJson {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+interface NoteTarget {
+    selector: string;
+    boundingRect: DOMRectJson;
+    visible: boolean;
+    confidence?: 'high' | 'medium' | 'low';
+}
+interface ElementContext {
+    selector: string;
+    tag: string;
+    attributes?: Record<string, string>;
+    outerHTML?: string;
+    innerText?: string;
+    parent?: {
+        selector: string;
+        tag: string;
+    };
+}
+interface RegionContext {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface VisualNote {
+    id: string;
+    projectId: string;
+    sessionId: string;
+    type: NoteType;
+    message: string;
+    route: string;
+    url: string;
+    viewport: ViewportContext;
+    scroll: ScrollContext;
+    target?: NoteTarget;
+    elementContext?: ElementContext;
+    region?: RegionContext;
+    status: NoteStatus;
+    incidentId?: string;
+    screenshots?: {
+        original?: string;
+        after?: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    resolvedAt?: string;
+}
+interface NoteVerificationResult {
+    noteId: string;
+    status: NoteStatus;
+    checks: Array<{
+        type: string;
+        passed: boolean;
+        details?: string;
+    }>;
+    geometryDiff?: {
+        before?: DOMRectJson;
+        current?: DOMRectJson;
+        viewportWidth?: number;
+        overflowFixed?: boolean;
+        overflowPx?: number;
+    };
+    screenshots?: {
+        before?: string;
+        after?: string;
+    };
+    timestamp: string;
+    message?: string;
+}
+
+export type { Breadcrumb as B, CaptureElementParams as C, DOMRectJson as D, ElementContext as E, HelloMessage as H, NavigateParams as N, OverflowCheckResult as O, PageStateResult as P, QueryElementParams as Q, RegionContext as R, ScrollContext as S, ViewportContext as V, CaptureElementResult as a, ClientCommand as b, ClientEventMessage as c, CommandResponse as d, CommandType as e, ConsoleEvent as f, ConsoleLevel as g, ElementStyleResult as h, ElementSummary as i, EventType as j, NavigationEvent as k, NetworkEvent as l, NoteStatus as m, NoteTarget as n, NoteType as o, NoteVerificationResult as p, QueryElementResult as q, ReloadParams as r, RuntimeErrorEvent as s, VisualNote as t };

package/dist/projects-CY8ungMt.d.ts

@@ -0,0 +1,99 @@
+import { B as Breadcrumb, l as NetworkEvent, i as ElementSummary } from './notes-CBvN91Wf.js';
+
+type IncidentStatus = 'OPEN' | 'FIX_ATTEMPTED' | 'VERIFYING' | 'VERIFIED' | 'FAILED' | 'INCONCLUSIVE';
+type IncidentSeverity = 'error' | 'warn' | 'fatal';
+interface IncidentSource {
+    file: string;
+    line: number;
+    column?: number;
+}
+interface Incident {
+    id: string;
+    projectId: string;
+    sessionId: string;
+    type: string;
+    severity: IncidentSeverity;
+    message: string;
+    source: IncidentSource;
+    fingerprint: string;
+    route: string;
+    firstSeen: string;
+    lastSeen: string;
+    occurrences: number;
+    status: IncidentStatus;
+    stack?: string;
+    breadcrumbs: Breadcrumb[];
+    networkFailures: NetworkEvent[];
+    lastElement?: ElementSummary;
+    screenshots?: {
+        error?: string;
+        before?: string;
+        after?: string;
+    };
+}
+interface IncidentOccurrence {
+    id: string;
+    incidentId: string;
+    sessionId: string;
+    timestamp: string;
+    route: string;
+    url: string;
+    stack?: string;
+    breadcrumbs: Breadcrumb[];
+    lastElement?: ElementSummary;
+}
+
+type ProbeType = 'element_exists' | 'element_visible' | 'text_contains' | 'route_is' | 'network_request_succeeded' | 'no_incident';
+interface VerificationProbe {
+    type: ProbeType;
+    selector?: string;
+    text?: string;
+    route?: string;
+    fingerprint?: string;
+    urlPattern?: string;
+    timeoutMs?: number;
+}
+interface VerificationRecipe {
+    route?: string;
+    targetSelector?: string;
+    expect?: VerificationProbe[];
+    observationWindowMs?: number;
+}
+interface ProbeResult {
+    type: ProbeType;
+    passed: boolean;
+    details?: string;
+}
+interface VerificationResult {
+    incidentId: string;
+    status: IncidentStatus;
+    checks: ProbeResult[];
+    screenshots?: {
+        before?: string;
+        after?: string;
+    };
+    timestamp: string;
+    message?: string;
+}
+
+interface Project {
+    id: string;
+    name: string;
+    origin: string;
+    path?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Session {
+    id: string;
+    projectId: string;
+    origin: string;
+    url: string;
+    title: string;
+    userAgent: string;
+    connectedAt: string;
+    lastSeenAt: string;
+    active: boolean;
+}
+
+export type { Incident as I, ProbeResult as P, Session as S, VerificationProbe as V, IncidentOccurrence as a, IncidentSeverity as b, IncidentSource as c, IncidentStatus as d, ProbeType as e, Project as f, VerificationRecipe as g, VerificationResult as h };

package/dist/server-Dd8NX2Mk.d.ts

@@ -0,0 +1,55 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { S as StorageDB, a as SessionManager, V as VerificationEngine, N as NoteVerificationEngine } from './engine-CeT9URuN.js';
+
+interface McpContext {
+    db: StorageDB;
+    sessionManager?: SessionManager;
+    verificationEngine?: VerificationEngine;
+    noteVerificationEngine?: NoteVerificationEngine;
+    daemonUrl?: string;
+}
+declare function handleToolCall(name: string, args: any, ctx: McpContext): Promise<any>;
+
+interface McpServerOptions {
+    dbPath?: string;
+    context?: Partial<McpContext>;
+}
+declare function createMcpServer(options?: McpServerOptions): {
+    server: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    startStdio(): Promise<void>;
+};
+
+export { type McpContext as M, type McpServerOptions as a, createMcpServer as c, handleToolCall as h };

package/docboot.config.js

@@ -0,0 +1,16 @@
+/** @type {import('docboot').DocbootConfig} */
+export default {
+  title: "BrowserTrack",
+  description: "Local browser diagnostics shared with coding agents through MCP",
+  docs: "./docs",
+  out: "./dist-docs",
+  theme: {
+    preset: "zinc",
+    defaultMode: "dark"
+  },
+  search: {
+    fuzzy: 0.2,
+    prefix: true,
+    maxResults: 10
+  }
+};

package/docs/cli.md

@@ -0,0 +1,51 @@
+---
+title: CLI Reference
+description: Command-line interface commands for daemon control, project tracking, error logs, and documentation
+order: 8
+---
+
+# CLI Reference 💻
+
+BrowserTrack provides a complete command-line interface for managing the daemon, tracked projects, and runtime errors.
+
+---
+
+## ⚡ Commands
+
+### Daemon Management
+```bash
+browsertrack start             # Start local daemon on http://127.0.0.1:7331
+browsertrack start --verbose   # Start with verbose message logging
+browsertrack stop              # Stop running daemon process
+browsertrack status            # Check status and connected browser sessions
+```
+
+### Project Registry
+```bash
+browsertrack projects          # List all tracked projects
+browsertrack project add <name> --origin <url> --path <path>
+```
+
+### Incident & Log Inspection
+```bash
+browsertrack errors            # List open runtime error incidents
+browsertrack errors --project <name>
+browsertrack clear             # Wipe stored logs, screenshots, and incidents
+```
+
+### MCP Integration
+```bash
+browsertrack mcp               # Start Model Context Protocol server over stdio
+```
+
+---
+
+## 📖 Documentation Commands (Docboot)
+
+To preview or build this documentation locally using [Docboot](https://github.com/litepacks/docboot):
+
+```bash
+npm run docs:dev     # Start live documentation server on http://localhost:3000
+npm run docs:build   # Build static production documentation to dist-docs/
+npm run docs:serve   # Preview production build locally
+```

package/docs/closed-loop-verification.md

@@ -0,0 +1,57 @@
+---
+title: Closed-Loop Verification
+description: Automated bug-fix verification, visual layout probes, before/after screenshot comparisons, and resolution verdicts
+order: 5
+---
+
+# Closed-Loop Verification 🔄
+
+BrowserTrack features an automated closed-loop verification engine for both runtime bug fixes and visual layout fixes.
+
+---
+
+## 🐞 Bug Fix Verification (`verify_incident`)
+
+When an agent fixes a code bug, it triggers `verify_incident`:
+
+1. **Browser Reload**: Reloads the active browser tab (or navigates to the incident route).
+2. **Error Monitoring**: Watches for the incident fingerprint during an observation window (e.g. 2000ms).
+3. **Probe Evaluation**: Evaluates custom verification probes:
+   - `no_incident`: Confirms zero runtime errors occurred.
+   - `element_exists`: Checks if a specific selector exists in the DOM.
+   - `element_visible`: Confirms the target is rendered and visible.
+   - `text_contains`: Asserts expected text content.
+   - `route_is`: Verifies current SPA route.
+4. **After Screenshot**: Automatically captures an after-fix screenshot.
+5. **Verdict**: Returns `VERIFIED`, `FAILED`, or `INCONCLUSIVE`.
+
+```typescript
+// Example MCP call
+await client.callTool("verify_incident", {
+  incidentId: "inc_19a31a28",
+  expect: [
+    { type: "no_incident" },
+    { type: "element_visible", selector: "#user-card" }
+  ]
+});
+```
+
+---
+
+## 📐 Layout & Visual Note Verification (`verify_note`)
+
+When an agent modifies CSS or HTML to resolve visual feedback, it triggers `verify_note`:
+
+1. **Target Element Inspection**: Queries element visibility, bounding rect, and computed styles.
+2. **Viewport Overflow Probe**: Checks if `rect.right > viewportWidth` or if container has unintended horizontal scroll.
+3. **Geometry Diff**: Calculates before vs after dimensional delta (`widthDiff`, `heightDiff`, `overflowFixed`).
+4. **After Screenshot**: Captures an updated visual snapshot.
+5. **Verdict & Auto-Resolution**: If all checks pass and overflow is eliminated, returns `VERIFIED`.
+
+```typescript
+// Example MCP call
+await client.callTool("verify_note", {
+  noteId: "note_30a89599",
+  observationWindowMs: 1000
+});
+```

package/docs/getting-started.md

@@ -0,0 +1,122 @@
+---
+title: Getting Started
+description: Installation, daemon setup, and browser client integration guide for BrowserTrack
+order: 2
+---
+
+# Getting Started 🚀
+
+Follow this guide to get BrowserTrack up and running in under 2 minutes.
+
+---
+
+## 1. Install & Start Daemon
+
+Install BrowserTrack globally via npm:
+
+```bash
+npm install -g browsertrack
+```
+
+Start the background diagnostics server:
+
+```bash
+browsertrack start
+```
+
+This will initialize the local server at `http://127.0.0.1:7331` (WebSocket bridge on `ws://127.0.0.1:7331`) and SQLite database at `~/.browsertrack/browsertrack.db`.
+
+---
+
+## 2. Connect Your Web Application
+
+Choose the integration method that best suits your tech stack:
+
+### Option A: Zero-Install Script Tag (Plain HTML / Vite / Next.js / Astro)
+
+Add the script tag to your root HTML or document layout:
+
+```html
+<script src="http://127.0.0.1:7331/client.js"></script>
+```
+
+> **Tip (Next.js / SSR)**: You can conditionally load this script tag only in development environments (`process.env.NODE_ENV !== 'production'`).
+
+### Option B: NPM Package (React / Vue / Svelte / Angular)
+
+Install the client package:
+
+```bash
+npm install -D browsertrack
+```
+
+Import the client in your main application entry point (e.g. `main.ts` or `src/index.tsx`):
+
+```typescript
+import 'browsertrack/client';
+```
+
+Or configure custom options programmatically:
+
+```typescript
+import { BrowserTrackClient } from 'browsertrack/client';
+
+const client = new BrowserTrackClient({
+  daemonUrl: 'ws://127.0.0.1:7331',
+  captureErrors: true,
+  captureConsole: true,
+  captureNetwork: true,
+  captureInteractions: true,
+  notes: {
+    enabled: true,
+    shortcut: 'Alt+Click',
+  },
+}).init();
+```
+
+---
+
+## 3. Configure Your IDE for MCP
+
+Add BrowserTrack MCP server to your AI editor configuration:
+
+### Antigravity (`~/.gemini/antigravity-ide/mcp_config.json`)
+```json
+{
+  "mcpServers": {
+    "browsertrack": {
+      "command": "browsertrack",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### Cursor (`~/.cursor/mcp.json`) & Claude Code
+```json
+{
+  "mcpServers": {
+    "browsertrack": {
+      "command": "npx",
+      "args": ["browsertrack", "mcp"]
+    }
+  }
+}
+```
+
+---
+
+## 4. Add Project Agent Guidelines
+
+Place an `AGENTS.md` file in the root of your project to instruct AI agents on how and when to use BrowserTrack tools:
+
+```markdown
+# AGENTS.md
+This project is integrated with BrowserTrack MCP. Always check `list_incidents` and `list_notes` when debugging runtime errors or fixing layout feedback. Use `verify_incident` and `verify_note` after making code changes.
+```
+
+---
+
+## 5. Verify the Connection
+
+Open your web application in any browser. You will see the floating BrowserTrack dock in the bottom-right corner with **Element**, **Region**, **Page**, and **Notes** controls!