@squasher-ai/browser 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Squasher
-
-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.
+MIT License
+
+Copyright (c) 2026 Squasher
+
+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.

package/dist/__tests__/client/harness.d.ts

@@ -0,0 +1,18 @@
+import { BrowserClient } from "../../client.js";
+import type { ReplayRecorderConfig } from "../../replay.js";
+import type { BrowserClientRuntime, BrowserTransport } from "../../runtime/client.js";
+import type { BrowserConfig, BrowserErrorEvent } from "../../types.js";
+import type { VitalsCollectorConfig } from "../../vitals.js";
+export declare const installAutocaptureMock: import("vitest").Mock<(onBreadcrumb: import("../../console-capture.js").BreadcrumbCallback, options: import("../../autocapture.js").AutocaptureOptions) => () => void>;
+export declare const installGlobalErrorHandlersMock: import("vitest").Mock<(onError: (event: BrowserErrorEvent) => void) => () => void>;
+export declare const replayCtorMock: import("vitest").Mock<(config: ReplayRecorderConfig) => void>;
+export declare const replayDisposeMock: import("vitest").Mock<() => void>;
+export declare const startVitalsCollectionMock: import("vitest").Mock<(transport: BrowserTransport, config: VitalsCollectorConfig) => void>;
+export declare const vitalsSuppressMock: import("vitest").Mock<() => void>;
+export declare const browserClientRuntime: BrowserClientRuntime;
+export declare function buildConfig(overrides?: Partial<BrowserConfig>): BrowserConfig;
+export declare function createClient(overrides?: Partial<BrowserConfig>): BrowserClient;
+export declare function readBeaconEvent(callIndex: number): Promise<BrowserErrorEvent>;
+export declare function setupClientTest(): void;
+export declare function teardownClientTest(): void;
+//# sourceMappingURL=harness.d.ts.map

package/dist/__tests__/client/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../../src/__tests__/client/harness.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGtF,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE7D,eAAO,MAAM,sBAAsB,wKAAsD,CAAC;AAC1F,eAAO,MAAM,8BAA8B,oFACkB,CAAC;AAC9D,eAAO,MAAM,cAAc,iCAAkB,oBAAoB,KAAK,IAAI,CAAG,CAAC;AAC9E,eAAO,MAAM,iBAAiB,8BAAe,IAAI,CAAG,CAAC;AACrD,eAAO,MAAM,yBAAyB,oCAClB,gBAAgB,UAAU,qBAAqB,KAAK,IAAI,CAAG,CAAC;AAChF,eAAO,MAAM,kBAAkB,8BAAe,IAAI,CAAG,CAAC;AAEtD,eAAO,MAAM,oBAAoB,EAAE,oBAYlC,CAAC;AAuBF,wBAAgB,WAAW,CAAC,SAAS,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,aAAa,CASjF;AAED,wBAAgB,YAAY,CAAC,SAAS,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,aAAa,CAElF;AAED,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAQnF;AAED,wBAAgB,eAAe,IAAI,IAAI,CAwCtC;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC"}

package/dist/__tests__/client/harness.js

@@ -0,0 +1,106 @@
+import { vi } from "vitest";
+import { BrowserClient } from "../../client.js";
+import { resetSessionId } from "../../session.js";
+import { Transport } from "../../transport.js";
+export const installAutocaptureMock = vi.fn();
+export const installGlobalErrorHandlersMock = vi.fn();
+export const replayCtorMock = vi.fn();
+export const replayDisposeMock = vi.fn();
+export const startVitalsCollectionMock = vi.fn();
+export const vitalsSuppressMock = vi.fn();
+export const browserClientRuntime = {
+    createReplayRecorder: (config) => {
+        replayCtorMock(config);
+        return { dispose: replayDisposeMock };
+    },
+    createTransport: (config) => new Transport(config),
+    installAutocapture: (onBreadcrumb, options) => installAutocaptureMock(onBreadcrumb, options),
+    installGlobalErrorHandlers: (onError) => installGlobalErrorHandlersMock(onError),
+    startVitalsCollection: (transport, config) => {
+        startVitalsCollectionMock(transport, config);
+        return { suppress: vitalsSuppressMock };
+    },
+};
+function createStorage() {
+    const storage = {};
+    return {
+        clear: () => {
+            for (const key of Object.keys(storage))
+                delete storage[key];
+        },
+        getItem: (key) => storage[key] ?? null,
+        key: (index) => Object.keys(storage)[index] ?? null,
+        get length() {
+            return Object.keys(storage).length;
+        },
+        removeItem: (key) => {
+            delete storage[key];
+        },
+        setItem: (key, value) => {
+            storage[key] = value;
+        },
+    };
+}
+export function buildConfig(overrides = {}) {
+    return {
+        apiKey: "sq_pk_test",
+        projectId: "project-123",
+        enableVitals: false,
+        enableErrorCapture: false,
+        enableAutoBreadcrumbs: false,
+        ...overrides,
+    };
+}
+export function createClient(overrides = {}) {
+    return new BrowserClient(buildConfig(overrides), browserClientRuntime);
+}
+export async function readBeaconEvent(callIndex) {
+    const beaconCall = vi.mocked(navigator.sendBeacon).mock.calls[callIndex];
+    const payloadBlob = beaconCall?.[1];
+    if (!(payloadBlob instanceof Blob)) {
+        throw new Error("expected sendBeacon payload to be a Blob");
+    }
+    return JSON.parse(await payloadBlob.text());
+}
+export function setupClientTest() {
+    resetSessionId();
+    vi.useFakeTimers();
+    vi.restoreAllMocks();
+    const consoleLog = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    const consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    installAutocaptureMock.mockReset();
+    installGlobalErrorHandlersMock.mockReset();
+    replayCtorMock.mockReset();
+    replayDisposeMock.mockReset();
+    startVitalsCollectionMock.mockReset();
+    vitalsSuppressMock.mockReset();
+    vi.stubGlobal("console", { ...console, log: consoleLog, warn: consoleWarn });
+    vi.stubGlobal("crypto", {
+        randomUUID: vi.fn().mockReturnValue("aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"),
+    });
+    vi.stubGlobal("sessionStorage", createStorage());
+    vi.stubGlobal("navigator", {
+        sendBeacon: vi.fn().mockReturnValue(true),
+    });
+    vi.stubGlobal("fetch", vi.fn());
+    vi.stubGlobal("document", {
+        addEventListener: vi.fn(),
+        referrer: "https://referrer.example/from",
+        removeEventListener: vi.fn(),
+        title: "Settings",
+        visibilityState: "visible",
+    });
+    vi.stubGlobal("window", {
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+    });
+    vi.stubGlobal("location", {
+        href: "https://example.com/settings?tab=profile",
+        pathname: "/settings",
+        search: "?tab=profile",
+    });
+}
+export function teardownClientTest() {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+}

package/dist/__tests__/replay/coverage-harness.d.ts

@@ -0,0 +1,29 @@
+import type { ReplayNetworkCaptureOptions } from "../../replay-network.js";
+import type { ReplayPrivacyRecordOptions } from "../../replay-privacy.js";
+import { ReplayRecorder, type ReplayRecorderConfig } from "../../replay.js";
+import type { MockReplayEvent } from "./test-helpers.js";
+interface ReplayPayload {
+    session_id: string;
+    events: MockReplayEvent[];
+    page_url: string;
+    started_at: string;
+    visitor_id?: string;
+}
+export declare const replayUrl = "https://ingest.squasher.ai/v1/projects/project-123/replays";
+export declare const sessionId = "11111111-2222-4333-8444-555555555555";
+export declare const installReplayNetworkCaptureMock: import("vitest").Mock<(options: ReplayNetworkCaptureOptions) => () => void>;
+export declare const rrwebRecordMock: import("vitest").Mock<(options: ReplayPrivacyRecordOptions) => (() => void) | undefined>;
+export declare const rrwebStopMock: import("vitest").Mock<() => void>;
+export declare const rrwebAddCustomEventMock: import("vitest").Mock<(tag: string, payload: import("../../replay-network.js").ReplayNetworkEventPayload) => void>;
+export declare function setupReplayCoverageTest(): void;
+export declare function teardownReplayCoverageTest(): void;
+export declare function createRecorder(overrides?: Partial<ReplayRecorderConfig>): ReplayRecorder;
+export declare function readyRecorder(overrides?: Partial<ReplayRecorderConfig>): Promise<ReplayRecorder>;
+export declare function emitFromRecorder(event: MockReplayEvent, overrides?: Partial<ReplayRecorderConfig>): Promise<ReplayRecorder>;
+export declare function emitRecordedEvent(event: MockReplayEvent): void;
+export declare function flushFinal(eventName: "beforeunload" | "pagehide"): Promise<void>;
+export declare function fireLifecycleEvent(eventName: "beforeunload" | "pagehide"): void;
+export declare function getPayload(callIndex?: number): ReplayPayload;
+export declare function drainMicrotasks(turns?: number): Promise<void>;
+export {};
+//# sourceMappingURL=coverage-harness.d.ts.map

package/dist/__tests__/replay/coverage-harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-harness.d.ts","sourceRoot":"","sources":["../../../src/__tests__/replay/coverage-harness.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG5E,OAAO,KAAK,EAAE,eAAe,EAAc,MAAM,mBAAmB,CAAC;AAErE,UAAU,aAAa;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,SAAS,+DAA+D,CAAC;AACtF,eAAO,MAAM,SAAS,yCAAyC,CAAC;AAChE,eAAO,MAAM,+BAA+B,kCAC1B,2BAA2B,KAAK,MAAM,IAAI,CAAG,CAAC;AAChE,eAAO,MAAM,eAAe,kCACV,0BAA0B,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAG,CAAC;AAC7E,eAAO,MAAM,aAAa,8BAAe,IAAI,CAAG,CAAC;AACjD,eAAO,MAAM,uBAAuB,oHACkC,CAAC;AAkCvE,wBAAgB,uBAAuB,IAAI,IAAI,CAkC9C;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAKjD;AAED,wBAAgB,cAAc,CAAC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAAG,cAAc,CAa5F;AAED,wBAAsB,aAAa,CACjC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CAAC,cAAc,CAAC,CAIzB;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,eAAe,EACtB,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CAAC,cAAc,CAAC,CAIzB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAE9D;AAED,wBAAsB,UAAU,CAAC,SAAS,EAAE,cAAc,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtF;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,cAAc,GAAG,UAAU,GAAG,IAAI,CAE/E;AAED,wBAAgB,UAAU,CAAC,SAAS,SAAI,GAAG,aAAa,CAOvD;AAED,wBAAsB,eAAe,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/D"}

package/dist/__tests__/replay/coverage-harness.js

@@ -0,0 +1,123 @@
+import { expect, vi } from "vitest";
+import { ReplayRecorder } from "../../replay.js";
+import { resetSessionId } from "../../session.js";
+export const replayUrl = "https://ingest.squasher.ai/v1/projects/project-123/replays";
+export const sessionId = "11111111-2222-4333-8444-555555555555";
+export const installReplayNetworkCaptureMock = vi.fn();
+export const rrwebRecordMock = vi.fn();
+export const rrwebStopMock = vi.fn();
+export const rrwebAddCustomEventMock = vi.fn();
+const replayRuntime = {
+    installNetworkCapture: (options) => installReplayNetworkCaptureMock(options),
+    loadRecordingAdapter: async () => ({
+        emitCustomEvent: rrwebAddCustomEventMock,
+        start: rrwebRecordMock,
+    }),
+};
+let activeRecorder;
+let emitReplayEvent;
+let listeners = {};
+function createStorage() {
+    const storage = {};
+    return {
+        clear: () => {
+            for (const key of Object.keys(storage))
+                delete storage[key];
+        },
+        getItem: (key) => storage[key] ?? null,
+        key: (index) => Object.keys(storage)[index] ?? null,
+        get length() {
+            return Object.keys(storage).length;
+        },
+        removeItem: (key) => {
+            delete storage[key];
+        },
+        setItem: (key, value) => {
+            storage[key] = value;
+        },
+    };
+}
+export function setupReplayCoverageTest() {
+    activeRecorder = undefined;
+    emitReplayEvent = undefined;
+    listeners = {};
+    resetSessionId();
+    vi.useFakeTimers();
+    vi.restoreAllMocks();
+    vi.stubGlobal("crypto", { randomUUID: vi.fn().mockReturnValue(sessionId) });
+    vi.stubGlobal("sessionStorage", createStorage());
+    vi.stubGlobal("location", { href: "https://example.com/dashboard" });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response()));
+    vi.stubGlobal("navigator", {
+        sendBeacon: vi.fn().mockReturnValue(true),
+    });
+    vi.stubGlobal("document", {});
+    vi.stubGlobal("window", {
+        addEventListener: vi.fn((event, listener) => {
+            listeners[event] = [...(listeners[event] ?? []), listener];
+        }),
+        removeEventListener: vi.fn((event, listener) => {
+            listeners[event] = (listeners[event] ?? []).filter((value) => value !== listener);
+        }),
+    });
+    installReplayNetworkCaptureMock.mockReset();
+    rrwebAddCustomEventMock.mockReset();
+    rrwebStopMock.mockReset();
+    rrwebRecordMock.mockReset();
+    installReplayNetworkCaptureMock.mockImplementation(() => () => undefined);
+    rrwebRecordMock.mockImplementation((options) => {
+        emitReplayEvent = options.emit;
+        return rrwebStopMock;
+    });
+}
+export function teardownReplayCoverageTest() {
+    activeRecorder?.dispose();
+    activeRecorder = undefined;
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+}
+export function createRecorder(overrides = {}) {
+    activeRecorder = new ReplayRecorder({
+        endpoint: "https://ingest.squasher.ai",
+        projectId: "project-123",
+        apiKey: "sq_pk_test",
+        debug: false,
+        sampleRate: 1,
+        ...overrides,
+    }, replayRuntime);
+    return activeRecorder;
+}
+export async function readyRecorder(overrides = {}) {
+    const recorder = createRecorder(overrides);
+    await recorder.ready;
+    return recorder;
+}
+export async function emitFromRecorder(event, overrides = {}) {
+    const recorder = await readyRecorder(overrides);
+    emitReplayEvent?.(event);
+    return recorder;
+}
+export function emitRecordedEvent(event) {
+    emitReplayEvent?.(event);
+}
+export async function flushFinal(eventName) {
+    listeners[eventName]?.[0]?.();
+    await Promise.resolve();
+}
+export function fireLifecycleEvent(eventName) {
+    listeners[eventName]?.[0]?.();
+}
+export function getPayload(callIndex = 0) {
+    const body = vi.mocked(fetch).mock.calls[callIndex]?.[1]?.body;
+    expect(Object.prototype.toString.call(body)).toBe("[object String]");
+    if (Object.prototype.toString.call(body) !== "[object String]") {
+        throw new Error("expected replay request body to be a string");
+    }
+    return JSON.parse(String(body));
+}
+export async function drainMicrotasks(turns = 10) {
+    if (turns <= 0)
+        return;
+    await Promise.resolve();
+    await drainMicrotasks(turns - 1);
+}

package/dist/__tests__/replay/test-helpers.d.ts

@@ -0,0 +1,13 @@
+import type { ReplayPrivacyRecordOptions } from "../../replay-privacy.js";
+export type MockReplayValue = boolean | null | number | string | MockReplayObject | MockReplayValue[];
+export interface MockReplayObject {
+    [key: string]: MockReplayValue;
+}
+export type MockReplayEvent = {
+    type: number;
+    timestamp: number;
+    data: MockReplayObject;
+};
+export type ReplayEmit = NonNullable<ReplayPrivacyRecordOptions["emit"]>;
+export declare function createReplayEvent(type: number, timestamp: number): MockReplayEvent;
+//# sourceMappingURL=test-helpers.d.ts.map

package/dist/__tests__/replay/test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../../../src/__tests__/replay/test-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAE1E,MAAM,MAAM,eAAe,GACvB,OAAO,GACP,IAAI,GACJ,MAAM,GACN,MAAM,GACN,gBAAgB,GAChB,eAAe,EAAE,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAAC;CAChC;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,gBAAgB,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC,CAAC;AAEzE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAQlF"}

package/dist/__tests__/replay/test-helpers.js

@@ -0,0 +1,9 @@
+export function createReplayEvent(type, timestamp) {
+    return {
+        type,
+        timestamp,
+        data: {
+            source: type,
+        },
+    };
+}

package/dist/autocapture.d.ts

@@ -1,21 +1,17 @@
 /**
- * Auto-capture breadcrumbs for navigation, clicks, and fetch errors.
- *
- * Breadcrumbs are lightweight events that provide context about what the
- * user was doing before an error occurred. They are attached to error
- * events to help with debugging and AI triage.
- *
- * Categories:
- *   - "navigation" — route changes (pushState, replaceState, popstate)
- *   - "ui.click" — user clicks on elements
- *   - "fetch" — failed fetch requests (4xx/5xx)
- *   - "console" — console.error / console.warn calls
+ * Auto-capture breadcrumbs. Categories emitted:
+ *   - "navigation" — pushState/replaceState/popstate
+ *   - "ui.click"   — clicks on elements
+ *   - "fetch"      — 4xx/5xx fetch responses
+ *   - "console"    — console.error / console.warn calls
  */
-import type { Breadcrumb } from "./types";
-export type BreadcrumbCallback = (crumb: Omit<Breadcrumb, "timestamp">) => void;
-/**
- * Install all auto-capture hooks.
- * Returns a cleanup function to remove all hooks and restore originals.
- */
-export declare function installAutocapture(onBreadcrumb: BreadcrumbCallback): () => void;
+import { type BreadcrumbCallback } from "./console-capture.js";
+import type { BrowserErrorEvent } from "./types.js";
+export type { BreadcrumbCallback } from "./console-capture.js";
+export interface AutocaptureOptions {
+    captureBreadcrumbs?: boolean;
+    onConsoleError?: (event: BrowserErrorEvent) => void;
+}
+/** Installs all hooks. Returned function removes them and restores originals. */
+export declare function installAutocapture(onBreadcrumb: BreadcrumbCallback, options?: AutocaptureOptions): () => void;
 //# sourceMappingURL=autocapture.d.ts.map

package/dist/autocapture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"autocapture.d.ts","sourceRoot":"","sources":["../src/autocapture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,KAAK,IAAI,CAAC;AAEhF;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAa/E"}
+{"version":3,"file":"autocapture.d.ts","sourceRoot":"","sources":["../src/autocapture.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAE,iBAAiB,EAAc,MAAM,YAAY,CAAC;AAEhE,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACrD;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,kBAAkB,EAChC,OAAO,GAAE,kBAAuB,GAC/B,MAAM,IAAI,CAwBZ"}

package/dist/autocapture.js

@@ -1,26 +1,28 @@
 /**
- * Auto-capture breadcrumbs for navigation, clicks, and fetch errors.
- *
- * Breadcrumbs are lightweight events that provide context about what the
- * user was doing before an error occurred. They are attached to error
- * events to help with debugging and AI triage.
- *
- * Categories:
- *   - "navigation" — route changes (pushState, replaceState, popstate)
- *   - "ui.click" — user clicks on elements
- *   - "fetch" — failed fetch requests (4xx/5xx)
- *   - "console" — console.error / console.warn calls
+ * Auto-capture breadcrumbs. Categories emitted:
+ *   - "navigation" — pushState/replaceState/popstate
+ *   - "ui.click"   — clicks on elements
+ *   - "fetch"      — 4xx/5xx fetch responses
+ *   - "console"    — console.error / console.warn calls
  */
-/**
- * Install all auto-capture hooks.
- * Returns a cleanup function to remove all hooks and restore originals.
- */
-export function installAutocapture(onBreadcrumb) {
+import { attemptAsync } from "@squasher-ai/result-utils";
+import { readRuntimeProperty, readRuntimeString } from "@squasher-ai/sdk-core";
+import { captureConsole } from "./console-capture.js";
+/** Installs all hooks. Returned function removes them and restores originals. */
+export function installAutocapture(onBreadcrumb, options = {}) {
     const cleanups = [];
-    cleanups.push(captureNavigation(onBreadcrumb));
-    cleanups.push(captureClicks(onBreadcrumb));
-    cleanups.push(captureFetch(onBreadcrumb));
-    cleanups.push(captureConsole(onBreadcrumb));
+    const captureBreadcrumbs = options.captureBreadcrumbs ?? true;
+    if (captureBreadcrumbs) {
+        cleanups.push(captureNavigation(onBreadcrumb));
+        cleanups.push(captureClicks(onBreadcrumb));
+        cleanups.push(captureFetch(onBreadcrumb));
+    }
+    if (captureBreadcrumbs || options.onConsoleError) {
+        cleanups.push(captureConsole(onBreadcrumb, {
+            captureBreadcrumbs,
+            onConsoleError: options.onConsoleError,
+        }));
+    }
     return () => {
         for (const cleanup of cleanups) {
             cleanup();
@@ -43,13 +45,13 @@ function captureNavigation(onBreadcrumb) {
     };
     // Patch history.pushState
     const origPushState = history.pushState.bind(history);
-    history.pushState = function (...args) {
+    history.pushState = (...args) => {
         origPushState(...args);
         emitNavCrumb();
     };
     // Patch history.replaceState
     const origReplaceState = history.replaceState.bind(history);
-    history.replaceState = function (...args) {
+    history.replaceState = (...args) => {
         origReplaceState(...args);
         emitNavCrumb();
     };
@@ -65,20 +67,21 @@ function captureNavigation(onBreadcrumb) {
 // ─── Clicks ─────────────────────────────────────────────────────────────
 function captureClicks(onBreadcrumb) {
     const handler = (event) => {
-        const target = event.target;
+        const target = readClickTarget(event.target);
         if (!target)
             return;
         const descriptor = describeElement(target);
         if (!descriptor)
             return;
+        const data = { tag: target.tagName.toLowerCase() };
+        if (target.id)
+            data.id = target.id;
+        if (target.className)
+            data.className = target.className;
         onBreadcrumb({
             category: "ui.click",
             message: descriptor,
-            data: {
-                tag: target.tagName?.toLowerCase(),
-                id: target.id || undefined,
-                className: target.className || undefined,
-            },
+            data,
         });
     };
     // Use capture phase to catch clicks even if stopPropagation is called
@@ -87,27 +90,35 @@ function captureClicks(onBreadcrumb) {
         document.removeEventListener("click", handler, true);
     };
 }
+function readClickTarget(target) {
+    const tagName = readRuntimeString(readRuntimeProperty(target, "tagName"));
+    if (!tagName)
+        return null;
+    return {
+        className: readRuntimeString(readRuntimeProperty(target, "className")) ?? "",
+        id: readRuntimeString(readRuntimeProperty(target, "id")) ?? "",
+        tagName,
+        textContent: readRuntimeString(readRuntimeProperty(target, "textContent")) ?? "",
+    };
+}
 /**
  * Build a human-readable descriptor for a DOM element.
  * e.g. "button#submit-btn.primary" or "a.nav-link"
  */
 function describeElement(el) {
-    const tag = el.tagName?.toLowerCase();
-    if (!tag)
-        return null;
+    const tag = el.tagName.toLowerCase();
     let desc = tag;
-    const htmlEl = el;
-    if (htmlEl.id) {
-        desc += `#${htmlEl.id}`;
+    if (el.id) {
+        desc += `#${el.id}`;
     }
-    if (htmlEl.className && typeof htmlEl.className === "string") {
-        const classes = htmlEl.className.trim().split(/\s+/).slice(0, 2).join(".");
+    if (el.className) {
+        const classes = el.className.trim().split(/\s+/).slice(0, 2).join(".");
         if (classes) {
             desc += `.${classes}`;
         }
     }
     // Add text content for buttons/links (truncated)
-    const textContent = htmlEl.textContent?.trim();
+    const textContent = el.textContent?.trim();
     if (textContent && (tag === "button" || tag === "a")) {
         const truncated = textContent.length > 30 ? `${textContent.slice(0, 30)}...` : textContent;
         desc += `[${truncated}]`;
@@ -116,76 +127,47 @@ function describeElement(el) {
 }
 // ─── Fetch ──────────────────────────────────────────────────────────────
 function captureFetch(onBreadcrumb) {
-    if (typeof window === "undefined" || !window.fetch)
+    if (!globalThis.window?.fetch)
         return () => { };
     const origFetch = window.fetch.bind(window);
-    window.fetch = async function (input, init) {
+    window.fetch = async (input, init) => {
         const method = init?.method?.toUpperCase() || "GET";
-        const url = typeof input === "string"
-            ? input
-            : input instanceof URL
-                ? input.href
-                : input instanceof Request
-                    ? input.url
-                    : String(input);
-        try {
-            const response = await origFetch(input, init);
-            // Only breadcrumb on error responses (4xx/5xx)
-            if (response.status >= 400) {
+        const url = input instanceof URL ? input.href : input instanceof Request ? input.url : String(input);
+        return attemptAsync({
+            try: async () => {
+                const response = await origFetch(input, init);
+                // Only breadcrumb on error responses (4xx/5xx)
+                if (response.status >= 400) {
+                    onBreadcrumb({
+                        category: "fetch",
+                        message: `${method} ${url} [${response.status}]`,
+                        level: response.status >= 500 ? "error" : "warning",
+                        data: {
+                            method,
+                            url,
+                            status: response.status,
+                        },
+                    });
+                }
+                return response;
+            },
+            catch: ({ cause, error }) => {
+                // Network error
                 onBreadcrumb({
                     category: "fetch",
-                    message: `${method} ${url} [${response.status}]`,
-                    level: response.status >= 500 ? "error" : "warning",
+                    message: `${method} ${url} [network error]`,
+                    level: "error",
                     data: {
                         method,
                         url,
-                        status: response.status,
+                        error: error.message,
                     },
                 });
-            }
-            return response;
-        }
-        catch (error) {
-            // Network error
-            onBreadcrumb({
-                category: "fetch",
-                message: `${method} ${url} [network error]`,
-                level: "error",
-                data: {
-                    method,
-                    url,
-                    error: error instanceof Error ? error.message : String(error),
-                },
-            });
-            throw error;
-        }
-    };
-    return () => {
-        window.fetch = origFetch;
-    };
-}
-// ─── Console ────────────────────────────────────────────────────────────
-function captureConsole(onBreadcrumb) {
-    const origError = console.error.bind(console);
-    const origWarn = console.warn.bind(console);
-    console.error = (...args) => {
-        onBreadcrumb({
-            category: "console",
-            message: args.map(String).join(" ").slice(0, 200),
-            level: "error",
-        });
-        origError(...args);
-    };
-    console.warn = (...args) => {
-        onBreadcrumb({
-            category: "console",
-            message: args.map(String).join(" ").slice(0, 200),
-            level: "warning",
+                throw cause;
+            },
         });
-        origWarn(...args);
     };
     return () => {
-        console.error = origError;
-        console.warn = origWarn;
+        window.fetch = origFetch;
     };
 }