@glubean/browser 0.1.2

package/dist/chrome.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Chrome browser resolution: launch, connect, and auto-discover.
+ *
+ * Supports three modes:
+ * 1. `launch: true` — find and launch a local Chrome/Chromium in headless mode
+ * 2. `endpoint: "ws://..."` — connect directly to a WebSocket debugger URL
+ * 3. `endpoint: "http://..."` — auto-discover WS URL via /json/version
+ *
+ * @module chrome
+ */
+import { type Browser } from "puppeteer-core";
+import type { PuppeteerLike } from "./page.js";
+/**
+ * Detect the path of a locally installed Chrome or Chromium.
+ * Checks well-known paths for the current OS, plus the CHROME_PATH env var.
+ *
+ * @internal Exported for testing.
+ * @returns The path to the Chrome executable, or null if not found.
+ */
+export declare function detectChromePath(): string | null;
+/**
+ * Launch a local Chrome instance.
+ *
+ * @param executablePath Explicit path to Chrome. If omitted, auto-detects.
+ * @param puppeteerInstance Custom puppeteer-compatible instance (e.g. puppeteer-extra).
+ * @param launchOptions Extra options forwarded to `puppeteer.launch()`. Merged with defaults; user values win.
+ * @returns A connected Browser instance. The caller is responsible for closing it.
+ */
+export declare function launchChrome(executablePath?: string, puppeteerInstance?: PuppeteerLike, launchOptions?: Record<string, unknown>): Promise<Browser>;
+/**
+ * Resolve an endpoint string to a WebSocket debugger URL.
+ *
+ * - `ws://` or `wss://` → returned as-is
+ * - `http://` or `https://` → fetches /json/version to discover the WS URL
+ */
+export declare function resolveEndpoint(endpoint: string): Promise<string>;
+/**
+ * Connect to a Chrome instance via WebSocket endpoint (with auto-discovery).
+ *
+ * @param endpoint WebSocket or HTTP endpoint URL.
+ * @param puppeteerInstance Custom puppeteer-compatible instance (e.g. puppeteer-extra).
+ */
+export declare function connectChrome(endpoint: string, puppeteerInstance?: PuppeteerLike): Promise<Browser>;
+//# sourceMappingURL=chrome.d.ts.map

package/dist/chrome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chrome.d.ts","sourceRoot":"","sources":["../src/chrome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAyB,EAAE,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAqB/C;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAiBhD;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,cAAc,CAAC,EAAE,MAAM,EACvB,iBAAiB,CAAC,EAAE,aAAa,EACjC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,OAAO,CAAC,OAAO,CAAC,CA0BlB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAyCvE;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE,aAAa,GAChC,OAAO,CAAC,OAAO,CAAC,CAIlB"}

package/dist/chrome.js

@@ -0,0 +1,134 @@
+/**
+ * Chrome browser resolution: launch, connect, and auto-discover.
+ *
+ * Supports three modes:
+ * 1. `launch: true` — find and launch a local Chrome/Chromium in headless mode
+ * 2. `endpoint: "ws://..."` — connect directly to a WebSocket debugger URL
+ * 3. `endpoint: "http://..."` — auto-discover WS URL via /json/version
+ *
+ * @module chrome
+ */
+import { statSync } from "node:fs";
+import puppeteerDefault from "puppeteer-core";
+const WELL_KNOWN_PATHS = {
+    darwin: [
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    ],
+    linux: [
+        "/usr/bin/google-chrome",
+        "/usr/bin/google-chrome-stable",
+        "/usr/bin/chromium",
+        "/usr/bin/chromium-browser",
+        "/snap/bin/chromium",
+    ],
+    win32: [
+        "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+        "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+    ],
+};
+/**
+ * Detect the path of a locally installed Chrome or Chromium.
+ * Checks well-known paths for the current OS, plus the CHROME_PATH env var.
+ *
+ * @internal Exported for testing.
+ * @returns The path to the Chrome executable, or null if not found.
+ */
+export function detectChromePath() {
+    // Explicit env override takes priority
+    const envPath = process.env.CHROME_PATH;
+    if (envPath)
+        return envPath;
+    const os = process.platform;
+    const candidates = WELL_KNOWN_PATHS[os] ?? [];
+    for (const candidate of candidates) {
+        try {
+            statSync(candidate);
+            return candidate;
+        }
+        catch {
+            // not found, try next
+        }
+    }
+    return null;
+}
+/**
+ * Launch a local Chrome instance.
+ *
+ * @param executablePath Explicit path to Chrome. If omitted, auto-detects.
+ * @param puppeteerInstance Custom puppeteer-compatible instance (e.g. puppeteer-extra).
+ * @param launchOptions Extra options forwarded to `puppeteer.launch()`. Merged with defaults; user values win.
+ * @returns A connected Browser instance. The caller is responsible for closing it.
+ */
+export async function launchChrome(executablePath, puppeteerInstance, launchOptions) {
+    const chromePath = executablePath ?? detectChromePath();
+    if (!chromePath) {
+        throw new Error("Could not find Chrome or Chromium on this machine.\n" +
+            "Install Chrome, or set the CHROME_PATH environment variable, " +
+            "or pass executablePath in browser options.\n\n" +
+            "Checked paths:\n" +
+            (WELL_KNOWN_PATHS[process.platform] ?? [])
+                .map((p) => `  - ${p}`)
+                .join("\n"));
+    }
+    const pptr = puppeteerInstance ?? puppeteerDefault;
+    return await pptr.launch({
+        headless: true,
+        args: [
+            "--no-sandbox",
+            "--disable-setuid-sandbox",
+            "--disable-dev-shm-usage",
+            "--disable-gpu",
+        ],
+        ...launchOptions,
+        executablePath: chromePath,
+    });
+}
+/**
+ * Resolve an endpoint string to a WebSocket debugger URL.
+ *
+ * - `ws://` or `wss://` → returned as-is
+ * - `http://` or `https://` → fetches /json/version to discover the WS URL
+ */
+export async function resolveEndpoint(endpoint) {
+    if (endpoint.startsWith("ws://") || endpoint.startsWith("wss://")) {
+        return endpoint;
+    }
+    if (endpoint.startsWith("http://") || endpoint.startsWith("https://")) {
+        const base = endpoint.endsWith("/") ? endpoint.slice(0, -1) : endpoint;
+        const url = `${base}/json/version`;
+        let response;
+        try {
+            response = await fetch(url);
+        }
+        catch (err) {
+            throw new Error(`Failed to connect to Chrome at ${url}.\n` +
+                `Is Chrome running with --remote-debugging-port?\n` +
+                `Original error: ${err instanceof Error ? err.message : err}`);
+        }
+        if (!response.ok) {
+            throw new Error(`Chrome endpoint returned HTTP ${response.status} for ${url}.`);
+        }
+        const data = await response.json();
+        if (!data.webSocketDebuggerUrl) {
+            throw new Error(`Chrome endpoint at ${url} did not return a webSocketDebuggerUrl.\n` +
+                `Response: ${JSON.stringify(data)}`);
+        }
+        return data.webSocketDebuggerUrl;
+    }
+    throw new Error(`Invalid Chrome endpoint: "${endpoint}".\n` +
+        `Expected ws://, wss://, http://, or https:// URL.`);
+}
+/**
+ * Connect to a Chrome instance via WebSocket endpoint (with auto-discovery).
+ *
+ * @param endpoint WebSocket or HTTP endpoint URL.
+ * @param puppeteerInstance Custom puppeteer-compatible instance (e.g. puppeteer-extra).
+ */
+export async function connectChrome(endpoint, puppeteerInstance) {
+    const wsEndpoint = await resolveEndpoint(endpoint);
+    const pptr = puppeteerInstance ?? puppeteerDefault;
+    return await pptr.connect({ browserWSEndpoint: wsEndpoint });
+}
+//# sourceMappingURL=chrome.js.map

package/dist/chrome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chrome.js","sourceRoot":"","sources":["../src/chrome.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @glubean/browser — Browser automation plugin for Glubean.
+ *
+ * Connects to or launches a Chrome instance via puppeteer-core and provides
+ * auto-instrumentation: navigation tracing, network request tracing,
+ * performance metrics, and console log forwarding — all wired into
+ * the Glubean test context.
+ *
+ * @example Launch mode (zero config)
+ * ```ts
+ * import { configure, test } from "@glubean/sdk";
+ * import { browser } from "@glubean/browser";
+ *
+ * const { chrome } = configure({
+ *   plugins: {
+ *     chrome: browser({ launch: true }),
+ *   },
+ * });
+ *
+ * const myTest = test.extend({
+ *   page: async (ctx, use) => {
+ *     const pg = await chrome.newPage(ctx);
+ *     try {
+ *       await use(pg);
+ *     } finally {
+ *       await pg.close();
+ *     }
+ *   },
+ * });
+ *
+ * export const homepage = myTest("homepage-loads", async (ctx) => {
+ *   await ctx.page.goto("/");
+ *   ctx.expect(await ctx.page.title()).toBe("My App");
+ * });
+ * ```
+ *
+ * @module
+ */
+export { browser } from "./plugin.js";
+export { GlubeanBrowser, GlubeanPage } from "./page.js";
+export type { ActionOptions, BrowserAction, BrowserEvent, BrowserOptions, BrowserTestContext, InstrumentedPage, PuppeteerLike, NetworkTraceOptions, ResponseChecks, ScreenshotMode, } from "./page.js";
+export type { WrappedLocator } from "./locator.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxD,YAAY,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,cAAc,EACd,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,41 @@
+/**
+ * @glubean/browser — Browser automation plugin for Glubean.
+ *
+ * Connects to or launches a Chrome instance via puppeteer-core and provides
+ * auto-instrumentation: navigation tracing, network request tracing,
+ * performance metrics, and console log forwarding — all wired into
+ * the Glubean test context.
+ *
+ * @example Launch mode (zero config)
+ * ```ts
+ * import { configure, test } from "@glubean/sdk";
+ * import { browser } from "@glubean/browser";
+ *
+ * const { chrome } = configure({
+ *   plugins: {
+ *     chrome: browser({ launch: true }),
+ *   },
+ * });
+ *
+ * const myTest = test.extend({
+ *   page: async (ctx, use) => {
+ *     const pg = await chrome.newPage(ctx);
+ *     try {
+ *       await use(pg);
+ *     } finally {
+ *       await pg.close();
+ *     }
+ *   },
+ * });
+ *
+ * export const homepage = myTest("homepage-loads", async (ctx) => {
+ *   await ctx.page.goto("/");
+ *   ctx.expect(await ctx.page.title()).toBe("My App");
+ * });
+ * ```
+ *
+ * @module
+ */
+export { browser } from "./plugin.js";
+export { GlubeanBrowser, GlubeanPage } from "./page.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}

package/dist/locator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * WrappedLocator — Proxy-based wrapper around Puppeteer's Locator that
+ * auto-injects trace events and screenshot capture for action methods.
+ *
+ * @module locator
+ */
+import type { Locator } from "puppeteer-core";
+/** Context required by the WrappedLocator for trace/screenshot injection. */
+export interface LocatorContext {
+    action(event: {
+        category: string;
+        target: string;
+        duration: number;
+        status: "ok" | "error" | "timeout";
+        detail?: Record<string, unknown>;
+    }): void;
+    captureStep(label: string): Promise<void>;
+    captureFailure(label: string): Promise<void>;
+}
+/** A Puppeteer Locator enhanced with auto-tracing and screenshot capture. */
+export type WrappedLocator = Locator<any> & {
+    /**
+     * Type text into the located element (appends — does not clear).
+     *
+     * Puppeteer's Locator has no `type()` method, so this is an extension
+     * that calls `waitHandle()` + `handle.type()` under the hood.
+     */
+    type(text: string): Promise<void>;
+};
+/**
+ * Create a WrappedLocator that proxies a Puppeteer Locator with auto-tracing.
+ *
+ * - **Chain methods** (setTimeout, setVisibility, etc.) return a new WrappedLocator.
+ * - **Action methods** (click, fill, hover, scroll) inject trace + screenshot.
+ * - **type()** is a custom extension (Locator has no type method).
+ * - Everything else is transparently forwarded.
+ */
+export declare function createWrappedLocator(inner: Locator<unknown>, ctx: LocatorContext, selector: string): WrappedLocator;
+//# sourceMappingURL=locator.d.ts.map

package/dist/locator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.d.ts","sourceRoot":"","sources":["../src/locator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE7D,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,KAAK,EAAE;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;QACnC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,GAAG,IAAI,CAAC;IACT,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED,6EAA6E;AAE7E,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG;IAC1C;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC,CAAC;AAsBF;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,EACvB,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,GACf,cAAc,CAoFhB"}

package/dist/locator.js

@@ -0,0 +1,116 @@
+/**
+ * WrappedLocator — Proxy-based wrapper around Puppeteer's Locator that
+ * auto-injects trace events and screenshot capture for action methods.
+ *
+ * @module locator
+ */
+/** Methods that return a new Locator — we re-wrap the result. */
+const CHAIN_METHODS = new Set([
+    "setTimeout",
+    "setVisibility",
+    "setEnsureElementIsInTheViewport",
+    "setWaitForEnabled",
+    "setWaitForStableBoundingBox",
+    "clone",
+    "filter",
+    "map",
+]);
+/** Action methods that get trace/screenshot injection. */
+const ACTION_METHODS = new Set([
+    "click",
+    "fill",
+    "hover",
+    "scroll",
+]);
+/**
+ * Create a WrappedLocator that proxies a Puppeteer Locator with auto-tracing.
+ *
+ * - **Chain methods** (setTimeout, setVisibility, etc.) return a new WrappedLocator.
+ * - **Action methods** (click, fill, hover, scroll) inject trace + screenshot.
+ * - **type()** is a custom extension (Locator has no type method).
+ * - Everything else is transparently forwarded.
+ */
+export function createWrappedLocator(inner, ctx, selector) {
+    const proxy = new Proxy(inner, {
+        get(target, prop, receiver) {
+            if (prop === "type") {
+                return async (text) => {
+                    const start = Date.now();
+                    try {
+                        const handle = await target.waitHandle();
+                        await handle.type(text);
+                        await handle.dispose();
+                        const duration = Date.now() - start;
+                        ctx.action({
+                            category: "browser:type",
+                            target: selector,
+                            duration,
+                            status: "ok",
+                            detail: { textLength: text.length },
+                        });
+                        await ctx.captureStep(`type-${selector}`);
+                    }
+                    catch (err) {
+                        const duration = Date.now() - start;
+                        ctx.action({
+                            category: "browser:type",
+                            target: selector,
+                            duration,
+                            status: "timeout",
+                            detail: { textLength: text.length, error: String(err) },
+                        });
+                        await ctx.captureFailure(`type-${selector}`);
+                        throw err;
+                    }
+                };
+            }
+            if (typeof prop === "string" && CHAIN_METHODS.has(prop)) {
+                const origFn = Reflect.get(target, prop, receiver);
+                if (typeof origFn === "function") {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    return (...args) => {
+                        const newLocator = origFn.apply(target, args);
+                        return createWrappedLocator(newLocator, ctx, selector);
+                    };
+                }
+            }
+            if (typeof prop === "string" && ACTION_METHODS.has(prop)) {
+                const origFn = Reflect.get(target, prop, receiver);
+                if (typeof origFn === "function") {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    return async (...args) => {
+                        const start = Date.now();
+                        try {
+                            const result = await origFn.apply(target, args);
+                            const duration = Date.now() - start;
+                            ctx.action({
+                                category: `browser:${prop}`,
+                                target: selector,
+                                duration,
+                                status: "ok",
+                            });
+                            await ctx.captureStep(`${prop}-${selector}`);
+                            return result;
+                        }
+                        catch (err) {
+                            const duration = Date.now() - start;
+                            ctx.action({
+                                category: `browser:${prop}`,
+                                target: selector,
+                                duration,
+                                status: "timeout",
+                                detail: { error: String(err) },
+                            });
+                            await ctx.captureFailure(`${prop}-${selector}`);
+                            throw err;
+                        }
+                    };
+                }
+            }
+            // Everything else — transparent passthrough
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+    return proxy;
+}
+//# sourceMappingURL=locator.js.map

package/dist/locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.js","sourceRoot":"","sources":["../src/locator.ts"],"names":[],"mappings":"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"}

package/dist/metrics.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Performance timing collection for browser pages.
+ *
+ * Collects Navigation Timing API metrics after page loads and emits them
+ * via the Glubean metric callback so they appear in dashboards and trend
+ * analysis alongside API latency data.
+ *
+ * @module metrics
+ */
+import type { Page } from "puppeteer-core";
+/** Callback shape matching `ctx.metric()`. */
+export type MetricFn = (name: string, value: number, options?: {
+    unit?: string;
+    tags?: Record<string, string>;
+}) => void;
+/**
+ * Collect Navigation Timing metrics from the page and emit them.
+ * Should be called after a successful `page.goto()` navigation.
+ *
+ * Silently skips if timing data is unavailable (e.g., page not fully loaded).
+ */
+export declare function collectNavigationMetrics(page: Page, metric: MetricFn, url: string): Promise<void>;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,8CAA8C;AAC9C,MAAM,MAAM,QAAQ,GAAG,CACrB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,KACvD,IAAI,CAAC;AAQV;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,QAAQ,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAkCf"}

package/dist/metrics.js

@@ -0,0 +1,54 @@
+/**
+ * Performance timing collection for browser pages.
+ *
+ * Collects Navigation Timing API metrics after page loads and emits them
+ * via the Glubean metric callback so they appear in dashboards and trend
+ * analysis alongside API latency data.
+ *
+ * @module metrics
+ */
+/**
+ * Collect Navigation Timing metrics from the page and emit them.
+ * Should be called after a successful `page.goto()` navigation.
+ *
+ * Silently skips if timing data is unavailable (e.g., page not fully loaded).
+ */
+export async function collectNavigationMetrics(page, metric, url) {
+    try {
+        const timing = await page.evaluate(() => {
+            // performance.timing is deprecated but universally supported and
+            // available in all Chrome versions. The newer PerformanceNavigationTiming
+            // API doesn't provide the same absolute timestamps needed here.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const t = performance.timing;
+            return {
+                navigationStart: t.navigationStart,
+                domContentLoadedEventEnd: t.domContentLoadedEventEnd,
+                loadEventEnd: t.loadEventEnd,
+            };
+        });
+        const tags = { url: shortenUrl(url) };
+        if (timing.loadEventEnd > 0 && timing.navigationStart > 0) {
+            metric("page_load_ms", timing.loadEventEnd - timing.navigationStart, {
+                unit: "ms",
+                tags,
+            });
+        }
+        if (timing.domContentLoadedEventEnd > 0 && timing.navigationStart > 0) {
+            metric("dom_content_loaded_ms", timing.domContentLoadedEventEnd - timing.navigationStart, { unit: "ms", tags });
+        }
+    }
+    catch {
+        // Page context may be destroyed or navigation incomplete — skip silently
+    }
+}
+function shortenUrl(url) {
+    try {
+        const u = new URL(url);
+        return u.pathname + u.search;
+    }
+    catch {
+        return url;
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAiBH;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,IAAU,EACV,MAAgB,EAChB,GAAW;IAEX,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;YACtC,iEAAiE;YACjE,0EAA0E;YAC1E,gEAAgE;YAChE,8DAA8D;YAC9D,MAAM,CAAC,GAAI,WAAmB,CAAC,MAAM,CAAC;YACtC,OAAO;gBACL,eAAe,EAAE,CAAC,CAAC,eAAyB;gBAC5C,wBAAwB,EAAE,CAAC,CAAC,wBAAkC;gBAC9D,YAAY,EAAE,CAAC,CAAC,YAAsB;aACvC,CAAC;QACJ,CAAC,CAAqB,CAAC;QAEvB,MAAM,IAAI,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAEtC,IAAI,MAAM,CAAC,YAAY,GAAG,CAAC,IAAI,MAAM,CAAC,eAAe,GAAG,CAAC,EAAE,CAAC;YAC1D,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,YAAY,GAAG,MAAM,CAAC,eAAe,EAAE;gBACnE,IAAI,EAAE,IAAI;gBACV,IAAI;aACL,CAAC,CAAC;QACL,CAAC;QAED,IAAI,MAAM,CAAC,wBAAwB,GAAG,CAAC,IAAI,MAAM,CAAC,eAAe,GAAG,CAAC,EAAE,CAAC;YACtE,MAAM,CACJ,uBAAuB,EACvB,MAAM,CAAC,wBAAwB,GAAG,MAAM,CAAC,eAAe,EACxD,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CACrB,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/network.d.ts

@@ -0,0 +1,55 @@
+/**
+ * CDP Network domain listener for auto-tracing in-page requests.
+ *
+ * Intercepts XHR, fetch, and document requests inside the browser page and
+ * emits them as Glubean trace events so they appear in the same timeline as
+ * `ctx.http` calls.
+ *
+ * @module network
+ */
+import type { Page } from "puppeteer-core";
+/** Callback shape matching `ctx.trace()`. */
+export type TraceFn = (trace: {
+    name?: string;
+    method: string;
+    url: string;
+    status: number;
+    duration: number;
+    requestBody?: unknown;
+    responseBody?: unknown;
+}) => void;
+/** @internal Exported for testing. */
+export declare function shouldSkipProtocol(url: string): boolean;
+/** @internal Exported for testing. */
+export declare function shouldSkipPath(url: string, excludePaths: string[]): boolean;
+/** @internal Exported for testing. */
+export declare function shouldInclude(contentType: string, include: string[]): boolean;
+/** Filter predicate for network requests. */
+export type NetworkFilter = (req: {
+    url: string;
+    contentType: string;
+    status: number;
+}) => boolean;
+export interface NetworkTracerOptions {
+    trace: TraceFn;
+    /**
+     * Content-type prefixes to include. Ignored when `filter` is provided.
+     * @default ["application/json", "text/html"]
+     */
+    include?: string[];
+    /**
+     * URL paths to skip. Pass `[]` to disable default exclusions.
+     * @default ["/favicon.ico", "/favicon.png", "/apple-touch-icon.png", "/apple-touch-icon-precomposed.png"]
+     */
+    excludePaths?: string[];
+    /** Custom predicate. Overrides `include` and `excludePaths` when provided. */
+    filter?: NetworkFilter;
+}
+/**
+ * Attach a CDP Network listener to the page that emits Glubean trace events
+ * for every in-page network request.
+ *
+ * Returns a cleanup function that detaches the listener.
+ */
+export declare function attachNetworkTracer(page: Page, options: NetworkTracerOptions): Promise<() => Promise<void>>;
+//# sourceMappingURL=network.d.ts.map

package/dist/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../src/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAc,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEvD,6CAA6C;AAC7C,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,KAAK,IAAI,CAAC;AAkBX,sCAAsC;AACtC,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAKvD;AAED,sCAAsC;AACtC,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAU3E;AAED,sCAAsC;AACtC,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAMT;AAED,6CAA6C;AAC7C,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB,KAAK,OAAO,CAAC;AAEd,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAcD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CA6H9B"}