@lightpath-dev/browser 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lightpath contributors
+
+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/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @lightpath-dev/browser
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The browser collector of [Lightpath](https://github.com/Unknown-333/Lightpath#readme). It launches Chrome or Edge, marks the start of each click, and collects the frontend code that click ran.
+
+You don't need this package directly; [`@lightpath-dev/cli`](https://www.npmjs.com/package/@lightpath-dev/cli) uses it.

package/dist/collector.d.ts

@@ -0,0 +1,38 @@
+import { type IngestMessage } from '@lightpath-dev/protocol';
+import type { Page } from 'playwright-core';
+export interface CollectorOptions {
+    /** App URL to open, e.g. http://localhost:5173 */
+    url: string;
+    /** Origins whose fetch/XHR requests get the trace header. Defaults to the app origin. */
+    backendOrigins?: string[];
+    settleMs?: number;
+    maxSettleMs?: number;
+    headless?: boolean;
+    channel?: string;
+    /**
+     * Coverage reads slower than this move the click boundary from pointer press to release
+     * (default 20 ms). Tests set 0 to force the release boundary.
+     */
+    pressBudgetMs?: number;
+    /** Where ingest messages go; the CLI wires this to the daemon. */
+    send: (message: IngestMessage) => void;
+    log?: (msg: string) => void;
+    /** Messages the user should see even without --debug, like a boundary change. */
+    notice?: (msg: string) => void;
+}
+/** Script URL of the init script, so pauses inside it can be told apart from app pauses. */
+export declare const HOOK_URL = "lightpath://hook.js";
+/**
+ * Collects per-click frontend coverage from one Chromium page (docs/ARCHITECTURE.md section 5.1).
+ *
+ * While the page is paused in the hook: take coverage (background), open the trace, resume.
+ * After the settle window: take again; that delta is the click's frontend code.
+ */
+export declare class BrowserCollector {
+    #private;
+    constructor(opts: CollectorOptions);
+    get page(): Page | undefined;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=collector.d.ts.map

package/dist/collector.js

@@ -0,0 +1,427 @@
+import { newTraceId, webpackModulePath } from '@lightpath-dev/core';
+import { TRACE_HEADER } from '@lightpath-dev/protocol';
+import { launchBrowser } from './launch.js';
+import { countsTowardSettle, isNoiseScript, labelFor, shouldTag } from './rules.js';
+import { SettleTracker } from './settle.js';
+/** Script URL of the init script, so pauses inside it can be told apart from app pauses. */
+export const HOOK_URL = 'lightpath://hook.js';
+const LAST = '__lightpathLast';
+/** Function names of the hook's listeners, so the collector can tell which one paused. */
+const HOOK_ACTION = 'lightpathAction';
+const HOOK_LEAVE = 'lightpathLeave';
+/** Set on window when the boundary moves to pointer release; read by the hook at event time. */
+const RELEASE = '__lightpathRelease';
+const PRESSED = '__lightpathPressed';
+/**
+ * Longest coverage read the press boundary may cost. Chrome drops a mouse release that arrives
+ * while the page is paused at the press, so above this the boundary moves to the release, where a
+ * pause loses nothing (measured up to 200 ms). See bench/README.md.
+ */
+const PRESS_BUDGET_MS = 20;
+/**
+ * Runs in every page before any app script (an init script):
+ * - registers the first capture `pointerdown` and `keydown` listeners on window, so they run before
+ *   app handlers;
+ * - records a description of the target, then pauses with `debugger;` so the collector can take
+ *   coverage before any app code for this action runs (ADR 0003).
+ *
+ * Keys: Enter on anything but a multi-line text field, and Space on buttons, links, checkboxes,
+ * radios, and ARIA widgets, which is what activates them. Space or Enter while typing is text, not
+ * an action. Held keys (`repeat`) and IME composition are ignored.
+ *
+ * One pause per action, in our own frame only. The pause must stay short: Chrome drops the
+ * pointerup, mouseup, and click events that arrive while the page is paused (measured). Key events
+ * aren't dropped: Enter and Space still activate every element after a 70 ms pause (measured).
+ */
+const HOOK_SOURCE = `(() => {
+  const describe = (el) => {
+    // The nearest control names the click; a data-testid only when no control encloses it. A
+    // test id inside a link (a balance span in Actual's sidebar) must not win over the link (D-098).
+    const hit = el && el.closest &&
+      (el.closest('button, a, [role], input, select, textarea, label, summary') || el.closest('[data-testid]'));
+    const t = hit || el;
+    if (!t || !t.tagName) return {};
+    // Outside any control, only a leaf element's own text is a fair label: a container's
+    // textContent includes every descendant, inline scripts too (seen on a real app, D-090).
+    const leaf = hit || (t.childElementCount === 0 && !/^(HTML|BODY|SCRIPT|STYLE)$/.test(t.tagName));
+    const text = leaf ? (t.textContent || '').trim().slice(0, 80) : '';
+    return {
+      tag: t.tagName.toLowerCase(),
+      role: t.getAttribute('role') || undefined,
+      name: t.getAttribute('aria-label') || t.getAttribute('name') || t.getAttribute('placeholder') || undefined,
+      testId: t.getAttribute('data-testid') || undefined,
+      text: text || undefined,
+    };
+  };
+  const TEXT_INPUTS = /^(text|search|email|url|tel|password|number|date|datetime-local|month|week|time|)$/;
+  const isTyping = (el) =>
+    !!el && (el.isContentEditable || el.tagName === 'TEXTAREA' || (el.tagName === 'INPUT' && TEXT_INPUTS.test(el.type)));
+  const isAction = (event) => {
+    if (event.repeat || event.isComposing || event.altKey || event.ctrlKey || event.metaKey) return false;
+    const el = event.target;
+    if (event.key === 'Enter') return !(el && (el.isContentEditable || el.tagName === 'TEXTAREA'));
+    if (event.key === ' ') return !isTyping(el) && !!(el && el.closest && el.closest('button, a, input, summary, [role]'));
+    return false;
+  };
+  window.addEventListener('pointerdown', function ${HOOK_ACTION}(event) {
+    if (!event.isPrimary) return;
+    window.${LAST} = describe(event.target);
+    // Release boundary (large apps): note the press, pause at pointerup instead.
+    if (window.${RELEASE}) { window.${PRESSED} = true; return; }
+    debugger;
+  }, { capture: true });
+  window.addEventListener('pointerup', function ${HOOK_ACTION}(event) {
+    if (!event.isPrimary || !window.${RELEASE} || !window.${PRESSED}) return;
+    window.${PRESSED} = false;
+    debugger;
+  }, { capture: true });
+  window.addEventListener('keydown', function ${HOOK_ACTION}(event) {
+    if (!isAction(event)) return;
+    window.${LAST} = { ...describe(event.target), key: event.key === ' ' ? 'Space' : event.key };
+    debugger;
+  }, { capture: true });
+  // A full page load is about to replace this document: pause once more so its coverage can be
+  // read while it still exists. Never sets returnValue, so no "leave site?" prompt appears.
+  window.addEventListener('beforeunload', function ${HOOK_LEAVE}() {
+    debugger;
+  }, { capture: true });
+})();
+//# sourceURL=${HOOK_URL}`;
+/**
+ * Collects per-click frontend coverage from one Chromium page (docs/ARCHITECTURE.md section 5.1).
+ *
+ * While the page is paused in the hook: take coverage (background), open the trace, resume.
+ * After the settle window: take again; that delta is the click's frontend code.
+ */
+export class BrowserCollector {
+    #opts;
+    #log;
+    #settle;
+    #scripts = new Map();
+    #sentHashes = new Set();
+    /** Script ids the daemon has been told about (one per parse; a reload makes new ones). */
+    #sentScripts = new Set();
+    #backendOrigins;
+    #browser;
+    #context;
+    #page;
+    #cdp;
+    #active;
+    #warnedNoWebpackMaps = false;
+    /** True from a `beforeunload` during an action until the next document's `load` (D-091). */
+    #navigating = false;
+    /** Logs a message and shows it to the user once (the CLI prints notices in yellow). */
+    #notify(message) {
+        this.#log(message);
+        this.#opts.notice?.(message);
+    }
+    #clickChain = Promise.resolve();
+    /** True once the boundary has moved to pointer release (see PRESS_BUDGET_MS). */
+    #release = false;
+    constructor(opts) {
+        this.#opts = opts;
+        this.#log = opts.log ?? (() => { });
+        this.#settle = new SettleTracker({
+            settleMs: opts.settleMs ?? 300,
+            maxSettleMs: opts.maxSettleMs ?? 5000,
+        });
+        this.#backendOrigins = opts.backendOrigins ?? [new URL(opts.url).origin];
+    }
+    get page() {
+        return this.#page;
+    }
+    async start() {
+        this.#browser = await launchBrowser({
+            ...(this.#opts.headless !== undefined ? { headless: this.#opts.headless } : {}),
+            ...(this.#opts.channel ? { channel: this.#opts.channel } : {}),
+        });
+        // Service workers are blocked (D-089): a worker that answers the app's fetches sends them from
+        // its own context, where page.route never sees them, so no API call would join the click.
+        this.#context = await this.#browser.newContext({ viewport: null, serviceWorkers: 'block' });
+        const page = await this.#context.newPage();
+        this.#page = page;
+        const cdp = await this.#context.newCDPSession(page);
+        this.#cdp = cdp;
+        cdp.on('Debugger.scriptParsed', (s) => {
+            this.#scripts.set(s.scriptId, {
+                url: s.url,
+                hash: s.hash,
+                length: s.length ?? 0,
+                sourceMapURL: s.sourceMapURL ?? '',
+            });
+            if (!this.#warnedNoWebpackMaps &&
+                !s.sourceMapURL &&
+                !isNoiseScript(s.url) &&
+                webpackModulePath(s.url)) {
+                this.#warnedNoWebpackMaps = true;
+                this.#notify("webpack is serving your code without source maps (devtool 'eval'), so browser files can't be shown. " +
+                    "Set devtool: 'eval-cheap-module-source-map' in your webpack config for development.");
+            }
+        });
+        cdp.on('Debugger.paused', (e) => {
+            // CallFrame.url is empty for init scripts (measured); resolve the URL via scriptParsed.
+            const frame = e.callFrames[0];
+            const url = frame ? (this.#scripts.get(frame.location.scriptId)?.url ?? frame.url) : undefined;
+            this.#onPaused(url, frame?.functionName);
+        });
+        await cdp.send('Debugger.enable');
+        await cdp.send('Profiler.enable');
+        await cdp.send('Profiler.startPreciseCoverage', { callCount: true, detailed: true });
+        this.#opts.send({
+            type: 'hello',
+            protocolVersion: 1,
+            kind: 'browser',
+            pid: process.pid,
+            processTitle: `browser ${this.#opts.url}`,
+            cwd: process.cwd(),
+            runtime: { name: 'chromium', version: this.#browser.version() },
+        });
+        await page.addInitScript({ content: HOOK_SOURCE });
+        await page.route('**/*', (route, request) => this.#onRoute(route, request));
+        page.on('request', (r) => countsTowardSettle(r.resourceType()) && this.#settle.requestStarted());
+        page.on('requestfinished', (r) => countsTowardSettle(r.resourceType()) && this.#settle.requestEnded());
+        page.on('requestfailed', (r) => countsTowardSettle(r.resourceType()) && this.#settle.requestEnded());
+        // Page load compiles and runs most of the app. Reading that now keeps the first action's
+        // pause as short as later ones (bench/README.md: 40 ms vs 8 ms at 12,000 functions).
+        page.on('load', () => {
+            if (this.#navigating) {
+                this.#navigating = false;
+                this.#settle.requestEnded();
+            }
+            this.#afterLoad();
+        });
+        await page.goto(this.#opts.url);
+        this.#log(`browser open at ${this.#opts.url}`);
+    }
+    async stop() {
+        this.#settle.cancel();
+        await this.#clickChain;
+        await this.#browser?.close();
+    }
+    #onPaused(url, functionName) {
+        if (url !== HOOK_URL) {
+            // A `debugger;` statement in app code. Lightpath isn't a debugger; keep the app running.
+            void this.#resume();
+            return;
+        }
+        if (functionName === HOOK_LEAVE) {
+            void this.#onLeave();
+            return;
+        }
+        // A new click ends the previous window early. The previous click's closing take still runs
+        // before this click's code, because the page stays paused until #click resumes it.
+        if (this.#active)
+            this.#settle.cancel();
+        this.#clickChain = this.#clickChain
+            .then(() => this.#click())
+            .catch(async (err) => {
+            this.#log(`click handling failed: ${err.stack ?? err}`);
+            await this.#resume();
+        });
+    }
+    /** Runs while the page is paused in the hook. Does as little as possible before resuming. */
+    async #click() {
+        const pausedAt = performance.now();
+        let readMs = 0;
+        const [before, target] = await Promise.all([
+            this.#take().then((r) => {
+                readMs = performance.now() - pausedAt;
+                return r;
+            }),
+            this.#lastTarget(),
+        ]);
+        const traceId = newTraceId();
+        const at = Date.now();
+        this.#active = traceId; // before resuming, so the click's own requests are tagged
+        const settled = this.#settle.begin();
+        await this.#resume();
+        const boundary = this.#release ? 'release' : 'press';
+        this.#log(`click on ${labelFor(target)}: paused ${(performance.now() - pausedAt).toFixed(1)}ms, boundary ${boundary}, trace ${traceId}`);
+        // Key presses never lose events to a pause, so only pointer presses count toward the budget.
+        if (!target.key && boundary === 'press')
+            await this.#checkBudget(readMs);
+        void this.#emit('background', before, at);
+        this.#opts.send({
+            type: 'traceStart',
+            traceId,
+            label: labelFor(target),
+            target: {
+                ...(target.role ? { role: target.role } : {}),
+                ...(target.name ? { name: target.name } : {}),
+                ...(target.testId ? { testId: target.testId } : {}),
+                ...(target.text ? { text: target.text } : {}),
+            },
+            at,
+        });
+        const reason = await settled;
+        // A navigation that never loaded (a download, a cancelled leave) mustn't hold later windows open.
+        if (this.#navigating) {
+            this.#navigating = false;
+            this.#settle.requestEnded();
+        }
+        const coverage = await this.#take();
+        await this.#emit('action', coverage, at, traceId);
+        this.#opts.send({ type: 'traceEnd', traceId, at: Date.now(), settled: reason });
+        if (this.#active === traceId)
+            this.#active = undefined;
+    }
+    async #lastTarget() {
+        if (!this.#cdp)
+            return {};
+        const { result } = await this.#cdp.send('Runtime.evaluate', {
+            expression: `window.${LAST}`,
+            returnByValue: true,
+            silent: true,
+        });
+        return result.value ?? {};
+    }
+    async #resume() {
+        try {
+            await this.#cdp?.send('Debugger.resume');
+        }
+        catch {
+            // Not paused (already resumed, or the page navigated).
+        }
+    }
+    async #onRoute(route, request) {
+        const traceId = this.#active;
+        // A main-frame page load started by this action (a link, a form post) is backend work for it.
+        const type = request.isNavigationRequest() && request.frame() === this.#page?.mainFrame()
+            ? 'navigation'
+            : request.resourceType();
+        if (traceId && shouldTag(request.url(), type, this.#backendOrigins)) {
+            await route.continue({ headers: { ...request.headers(), [TRACE_HEADER]: traceId } });
+            return;
+        }
+        await route.continue();
+    }
+    /**
+     * Files everything since the page started loading as background. Queued on the click chain so it
+     * never runs during an action's reads; skipped if an action is open (a navigation's new page
+     * belongs to that action's trace).
+     */
+    #afterLoad() {
+        this.#clickChain = this.#clickChain
+            .then(async () => {
+            if (this.#active)
+                return;
+            await this.#emit('background', await this.#take(), Date.now());
+            // A second read files what the page ran right after load, background too. It isn't timed
+            // against the press budget: the page can still be busy here, so this read can cost more than
+            // any click's (Actual: 20.8 ms, while 103 press reads stayed under 18.9 ms). Only a read at a
+            // pointer press moves the boundary (D-082, D-105).
+            await this.#emit('background', await this.#take(), Date.now());
+        })
+            .catch((err) => this.#log(`load-time coverage read failed: ${err.message}`));
+    }
+    /** Called only with the read taken while the page is paused at a pointer press (D-105). */
+    async #checkBudget(readMs) {
+        const budget = this.#opts.pressBudgetMs ?? PRESS_BUDGET_MS;
+        if (this.#release || readMs <= budget)
+            return;
+        this.#release = true;
+        await this.#setReleaseFlag();
+        const message = `a coverage read took ${readMs.toFixed(1)} ms (budget ${budget} ms), so clicks now start at the mouse ` +
+            'release instead of the press: Chrome drops a release that arrives during a long pause. ' +
+            "Code that runs on press (pointerdown and mousedown handlers) won't appear in click traces.";
+        this.#log(message);
+        this.#opts.notice?.(message);
+    }
+    /** Turns on the release boundary now, and from the first moment of every later document. */
+    async #setReleaseFlag() {
+        const expression = `window.${RELEASE} = true`;
+        await this.#cdp?.send('Runtime.evaluate', { expression, silent: true });
+        await this.#page?.addInitScript({ content: expression });
+    }
+    /**
+     * Runs while the page is paused in the hook's `beforeunload` listener: the current document is
+     * about to go, and its coverage and sources go with it. Taking coverage from a route handler
+     * instead deadlocks, because the renderer waits for the request the handler holds (measured).
+     */
+    async #onLeave() {
+        const traceId = this.#active;
+        // The page is leaving during an action: count the navigation as in flight until the next
+        // document's `load`, so a slow read here can't end the window before the new page runs (D-091).
+        if (traceId && !this.#navigating) {
+            this.#navigating = true;
+            this.#settle.requestStarted();
+        }
+        try {
+            const coverage = await this.#take();
+            if (traceId) {
+                await this.#emit('action', coverage, Date.now(), traceId);
+                this.#log(`page unloading during ${traceId}: kept its coverage`);
+            }
+            else {
+                await this.#emit('background', coverage, Date.now());
+            }
+        }
+        catch (err) {
+            this.#log(`could not read coverage before unload: ${err.message}`);
+        }
+        finally {
+            await this.#resume();
+        }
+    }
+    async #take() {
+        if (!this.#cdp)
+            return [];
+        const { result } = await this.#cdp.send('Profiler.takePreciseCoverage');
+        return result;
+    }
+    async #emit(phase, raw, startedAt, traceId) {
+        const coverage = raw.filter((s) => !isNoiseScript(s.url));
+        if (coverage.length === 0 && phase === 'background')
+            return;
+        // Sources go first: the daemon can't map a delta for a script it has no source for.
+        await this.#pushSources(coverage);
+        this.#opts.send({
+            type: 'delta',
+            phase,
+            startedAt,
+            endedAt: Date.now(),
+            coverage,
+            ...(traceId ? { traceId } : {}),
+        });
+    }
+    /**
+     * Sends script info once per script id and the source once per hash, before the delta that needs
+     * them. A reload parses the same files again under new ids with the same hash; the daemon looks a
+     * delta up by id, so each new id must be announced even when its source was sent before (D-101).
+     */
+    async #pushSources(coverage) {
+        for (const { scriptId } of coverage) {
+            const meta = this.#scripts.get(scriptId);
+            if (!meta || this.#sentScripts.has(scriptId) || !this.#cdp)
+                continue;
+            this.#sentScripts.add(scriptId);
+            const needSource = !this.#sentHashes.has(meta.hash);
+            try {
+                const scriptSource = needSource
+                    ? (await this.#cdp.send('Debugger.getScriptSource', { scriptId })).scriptSource
+                    : undefined;
+                this.#opts.send({
+                    type: 'scripts',
+                    scripts: [
+                        {
+                            scriptId,
+                            url: meta.url,
+                            hash: meta.hash,
+                            length: meta.length,
+                            // Vite inlines maps as data: URLs (unverified, M3). External maps are not fetched yet.
+                            ...(meta.sourceMapURL.startsWith('data:') ? { sourceMapURL: meta.sourceMapURL } : {}),
+                        },
+                    ],
+                });
+                if (scriptSource !== undefined) {
+                    this.#sentHashes.add(meta.hash);
+                    this.#opts.send({ type: 'source', scriptId, hash: meta.hash, url: meta.url, source: scriptSource });
+                }
+            }
+            catch (err) {
+                this.#log(`could not read source of ${meta.url}: ${err.message}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=collector.js.map

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { BrowserCollector, type CollectorOptions } from './collector.js';
+export { type LaunchOptions, launchBrowser } from './launch.js';
+export { countsTowardSettle, isNoiseScript, labelFor, shouldTag, type TargetInfo } from './rules.js';
+export { type SettleOptions, type SettleReason, SettleTracker } from './settle.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,5 @@
+export { BrowserCollector } from './collector.js';
+export { launchBrowser } from './launch.js';
+export { countsTowardSettle, isNoiseScript, labelFor, shouldTag } from './rules.js';
+export { SettleTracker } from './settle.js';
+//# sourceMappingURL=index.js.map

package/dist/launch.d.ts

@@ -0,0 +1,8 @@
+import { type Browser } from 'playwright-core';
+export interface LaunchOptions {
+    headless?: boolean;
+    /** Force one channel, for example 'chrome-beta'. */
+    channel?: string;
+}
+export declare function launchBrowser(options?: LaunchOptions): Promise<Browser>;
+//# sourceMappingURL=launch.d.ts.map

package/dist/launch.js

@@ -0,0 +1,17 @@
+import { chromium } from 'playwright-core';
+/** Installed browsers first, so users don't download one; Playwright's own Chromium last. */
+const CHANNELS = ['chrome', 'msedge', undefined];
+export async function launchBrowser(options = {}) {
+    const tried = [];
+    for (const channel of options.channel ? [options.channel] : CHANNELS) {
+        try {
+            return await chromium.launch({ headless: options.headless ?? false, ...(channel ? { channel } : {}) });
+        }
+        catch (err) {
+            tried.push(`${channel ?? 'Playwright Chromium'}: ${String(err.message).split('\n')[0]}`);
+        }
+    }
+    throw new Error(`Lightpath couldn't start a Chromium-based browser. Tried:\n  ${tried.join('\n  ')}\n` +
+        'Install Google Chrome or Microsoft Edge, or run: npx playwright install chromium');
+}
+//# sourceMappingURL=launch.js.map

package/dist/rules.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Tags fetch/XHR requests to configured backend origins and to any loopback origin (D-086).
+ *
+ * The header is added by request interception after the browser has done its CORS checks, so it
+ * never triggers a preflight, even when the API's CORS policy doesn't allow custom headers
+ * (measured in Chrome). Loopback is the common dev setup: Vite on :5173 calling an API on :3001.
+ * Remote origins (a payment provider, a CDN) are never tagged: the trace ID is no business of theirs.
+ */
+export declare function shouldTag(requestUrl: string, resourceType: string, backendOrigins: readonly string[]): boolean;
+/** Requests that count toward the settle window. Long-lived streams would keep a click open forever. */
+export declare function countsTowardSettle(resourceType: string): boolean;
+export interface TargetInfo {
+    tag?: string | undefined;
+    role?: string | undefined;
+    name?: string | undefined;
+    testId?: string | undefined;
+    text?: string | undefined;
+    /** Set when the action was a key press (`Enter` or `Space`) rather than a pointer press. */
+    key?: string | undefined;
+}
+/** A short human label for an action target, like `button: Checkout` or `button: Checkout (Enter)`. */
+export declare function labelFor(target: TargetInfo): string;
+/**
+ * Scripts whose source never needs to leave the browser: dependencies and dev-server internals.
+ * Webpack's per-module scripts (`webpack://`, `webpack-internal://`) are kept unless they're
+ * dependencies or webpack's runtime (D-087).
+ */
+export declare function isNoiseScript(url: string): boolean;
+//# sourceMappingURL=rules.d.ts.map

package/dist/rules.js

@@ -0,0 +1,57 @@
+import { webpackModulePath } from '@lightpath-dev/core';
+/**
+ * Resource types that carry app requests worth tagging (ADR 0004). `navigation` is a main-frame
+ * page load started by an action (the collector passes it explicitly): a server-rendered page or a
+ * form post is backend work for that action. Navigations aren't subject to CORS, so the header
+ * can't trigger a preflight.
+ */
+const TAGGABLE = new Set(['fetch', 'xhr', 'navigation']);
+/**
+ * Tags fetch/XHR requests to configured backend origins and to any loopback origin (D-086).
+ *
+ * The header is added by request interception after the browser has done its CORS checks, so it
+ * never triggers a preflight, even when the API's CORS policy doesn't allow custom headers
+ * (measured in Chrome). Loopback is the common dev setup: Vite on :5173 calling an API on :3001.
+ * Remote origins (a payment provider, a CDN) are never tagged: the trace ID is no business of theirs.
+ */
+export function shouldTag(requestUrl, resourceType, backendOrigins) {
+    if (!TAGGABLE.has(resourceType))
+        return false;
+    let url;
+    try {
+        url = new URL(requestUrl);
+    }
+    catch {
+        return false;
+    }
+    if (backendOrigins.includes(url.origin))
+        return true;
+    return /^https?:$/.test(url.protocol) && LOOPBACK.has(url.hostname);
+}
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
+/** Requests that count toward the settle window. Long-lived streams would keep a click open forever. */
+export function countsTowardSettle(resourceType) {
+    return !['websocket', 'eventsource', 'media', 'manifest', 'ping'].includes(resourceType);
+}
+/** A short human label for an action target, like `button: Checkout` or `button: Checkout (Enter)`. */
+export function labelFor(target) {
+    const kind = target.role || target.tag || 'element';
+    const name = (target.name || target.testId || target.text || '').replace(/\s+/g, ' ').trim();
+    const short = name.length > 40 ? `${name.slice(0, 39)}…` : name;
+    const base = short ? `${kind}: ${short}` : kind;
+    return target.key ? `${base} (${target.key})` : base;
+}
+/**
+ * Scripts whose source never needs to leave the browser: dependencies and dev-server internals.
+ * Webpack's per-module scripts (`webpack://`, `webpack-internal://`) are kept unless they're
+ * dependencies or webpack's runtime (D-087).
+ */
+export function isNoiseScript(url) {
+    const webpack = webpackModulePath(url);
+    if (webpack !== undefined)
+        return webpack === 'internal' || webpack === 'node_modules';
+    if (!/^https?:\/\//.test(url))
+        return true;
+    return /\/node_modules\/|\/@vite\/|\/@react-refresh|\/@id\/__x00__|\/__vite/.test(url);
+}
+//# sourceMappingURL=rules.js.map

package/dist/settle.d.ts

@@ -0,0 +1,23 @@
+export type SettleReason = 'quiet' | 'timeout';
+export interface SettleOptions {
+    /** Quiet time with no requests in flight before a click counts as finished. */
+    settleMs: number;
+    /** Hard cap on a click's window. */
+    maxSettleMs: number;
+}
+/**
+ * Decides when a click is over (ARCHITECTURE section 5.1): no requests in flight for `settleMs`,
+ * or `maxSettleMs` since the click, whichever comes first.
+ */
+export declare class SettleTracker {
+    #private;
+    constructor(opts: SettleOptions);
+    get inFlight(): number;
+    /** Starts a window. Requests already in flight count toward it. */
+    begin(): Promise<SettleReason>;
+    requestStarted(): void;
+    requestEnded(): void;
+    /** Ends the current window early, for example when the next click starts. */
+    cancel(): void;
+}
+//# sourceMappingURL=settle.d.ts.map

package/dist/settle.js

@@ -0,0 +1,59 @@
+/**
+ * Decides when a click is over (ARCHITECTURE section 5.1): no requests in flight for `settleMs`,
+ * or `maxSettleMs` since the click, whichever comes first.
+ */
+export class SettleTracker {
+    #inFlight = 0;
+    #quietTimer;
+    #maxTimer;
+    #resolve;
+    #opts;
+    constructor(opts) {
+        this.#opts = opts;
+    }
+    get inFlight() {
+        return this.#inFlight;
+    }
+    /** Starts a window. Requests already in flight count toward it. */
+    begin() {
+        this.#finish('quiet');
+        return new Promise((resolve) => {
+            this.#resolve = resolve;
+            this.#maxTimer = setTimeout(() => this.#finish('timeout'), this.#opts.maxSettleMs);
+            if (this.#inFlight === 0)
+                this.#armQuiet();
+        });
+    }
+    requestStarted() {
+        this.#inFlight++;
+        this.#clearQuiet();
+    }
+    requestEnded() {
+        this.#inFlight = Math.max(0, this.#inFlight - 1);
+        if (this.#inFlight === 0 && this.#resolve)
+            this.#armQuiet();
+    }
+    /** Ends the current window early, for example when the next click starts. */
+    cancel() {
+        this.#finish('quiet');
+    }
+    #armQuiet() {
+        this.#clearQuiet();
+        this.#quietTimer = setTimeout(() => this.#finish('quiet'), this.#opts.settleMs);
+    }
+    #clearQuiet() {
+        if (this.#quietTimer)
+            clearTimeout(this.#quietTimer);
+        this.#quietTimer = undefined;
+    }
+    #finish(reason) {
+        this.#clearQuiet();
+        if (this.#maxTimer)
+            clearTimeout(this.#maxTimer);
+        this.#maxTimer = undefined;
+        const resolve = this.#resolve;
+        this.#resolve = undefined;
+        resolve?.(reason);
+    }
+}
+//# sourceMappingURL=settle.js.map

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@lightpath-dev/browser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "description": "Lightpath browser collector: launches Chrome, marks click boundaries, and collects frontend coverage",
+  "keywords": [
+    "coverage",
+    "chrome",
+    "cdp",
+    "click",
+    "trace",
+    "frontend"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/Unknown-333/Lightpath#readme",
+  "bugs": "https://github.com/Unknown-333/Lightpath/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Unknown-333/Lightpath.git",
+    "directory": "packages/browser"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lightpath-dev/core": "0.0.1",
+    "@lightpath-dev/protocol": "0.0.1",
+    "playwright-core": "1.64.1"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p test"
+  }
 }