@vforsh/argus-watcher 0.1.1 → 0.1.3

package/dist/http/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/http/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/http/server.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAU5B,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAiFtC,4DAA4D;AAC5D,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAAE,OAA0B,EAA6B,EAAE;IAC9F,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC7C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,UAAU,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;QACjF,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;IACjC,CAAC,CAAC,CAAA;IAEF,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAC5B,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAA;IAC3D,CAAC,CAAC,CAAA;IAEF,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAA;IAChC,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAA;IAEjF,OAAO;QACN,IAAI;QACJ,KAAK,EAAE,GAAG,EAAE,CACX,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC/B,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;gBACtB,IAAI,KAAK,EAAE,CAAC;oBACX,MAAM,CAAC,KAAK,CAAC,CAAA;oBACb,OAAM;gBACP,CAAC;gBACD,OAAO,EAAE,CAAA;YACV,CAAC,CAAC,CAAA;QACH,CAAC,CAAC;KACH,CAAA;AACF,CAAC,CAAA"}

package/dist/index.d.ts

@@ -1,27 +1,84 @@
 import type { WatcherMatch, WatcherChrome, WatcherRecord, LogEvent } from '@vforsh/argus-core';
+import Emittery from 'emittery';
+import { type PageIndicatorOptions } from './cdp/pageIndicator.js';
+import type { ArgusWatcherEventMap } from './events.js';
+/** Context for the optional log filename builder callback. */
+export type BuildFilenameContext = {
+    /** Unique watcher identifier. */
+    watcherId: string;
+    /** Watcher start time as milliseconds since Unix epoch. */
+    startedAt: number;
+    /** Watcher start time formatted for use in a filename (ISO but with ":" replaced by "-"). */
+    startedAtSafe: string;
+    /** Sequence number of the log file within the current watcher session (starts at 1). */
+    fileIndex: number;
+};
+/** Configuration for artifacts storage (logs, traces, screenshots). */
+export type ArtifactsOptions = {
+    /**
+     * Base directory for all artifacts.
+     * Defaults to `$TMPDIR/argus/<watcherId>`.
+     */
+    base?: string;
+    /** Optional file log persistence settings. Disabled by default. */
+    logs?: {
+        /** Enable file logging. Defaults to `false`. */
+        enabled?: boolean;
+        /** Whether to include ISO timestamps in log records. Defaults to `false`. */
+        includeTimestamps?: boolean;
+        /** Max number of log files to keep for this watcher. Defaults to `5`. */
+        maxFiles?: number;
+        /** Optional callback to customize the log filename. Return null/undefined to use default. */
+        buildFilename?: (context: BuildFilenameContext) => string | undefined | null;
+    };
+    /** Trace recording settings. Enabled by default. */
+    traces?: {
+        /** Enable trace recording. Defaults to `true`. */
+        enabled?: boolean;
+    };
+    /** Screenshot capture settings. Enabled by default. */
+    screenshots?: {
+        /** Enable screenshot capture. Defaults to `true`. */
+        enabled?: boolean;
+    };
+};
+/** Configuration for network request capture. */
+export type NetOptions = {
+    /** Enable network request capture. Defaults to `false`. */
+    enabled?: boolean;
+};
+/** Page console logging level for watcher lifecycle and request logs. */
+export type PageConsoleLogging = 'none' | 'minimal' | 'full';
+/** Source mode for CDP connection. */
+export type WatcherSourceMode = 'cdp' | 'extension';
 /** Options to start a watcher server. */
 export type StartWatcherOptions = {
     /** Unique watcher identifier (used for registry presence and removal on shutdown). */
     id: string;
+    /**
+     * Source mode for CDP connection.
+     * - `cdp` (default): Connect directly to Chrome via WebSocket.
+     * - `extension`: Connect via Chrome extension Native Messaging.
+     */
+    source?: WatcherSourceMode;
     /** Host/interface to bind the watcher HTTP server to. Defaults to `127.0.0.1`. */
     host?: string;
     /** Port to bind the watcher HTTP server to. Defaults to `0` (ephemeral). */
     port?: number;
-    /** Criteria for which Chrome target(s) to attach to. */
+    /** Criteria for which Chrome target(s) to attach to. Only used in CDP mode. */
     match?: WatcherMatch;
-    /** Chrome DevTools Protocol (CDP) connection settings. Defaults to `127.0.0.1:9222`. */
+    /** Chrome DevTools Protocol (CDP) connection settings. Defaults to `127.0.0.1:9222`. Only used in CDP mode. */
     chrome?: WatcherChrome;
     /** Max buffered log events before older entries are dropped. Defaults to `50_000`. */
     bufferSize?: number;
     /** How often (in ms) to refresh the watcher record in the registry. Defaults to `15_000`. */
     heartbeatMs?: number;
-    /** Optional file log persistence settings. */
-    fileLogs?: {
-        /** Directory to store watcher logs. Required when fileLogs is set. */
-        logsDir: string;
-        /** Max number of log files to keep for this watcher. Defaults to `5`. */
-        maxFiles?: number;
-    };
+    /**
+     * Artifacts storage configuration for logs, traces, and screenshots.
+     * All artifacts are stored under `artifacts.base` (default: `$TMPDIR/argus`).
+     * Subdirectories: `logs/`, `traces/`, `screenshots/`.
+     */
+    artifacts?: ArtifactsOptions;
     /** Optional ignore list filtering when selecting log/exception locations. */
     ignoreList?: {
         /** Enable ignore list filtering for log/exception locations. */
@@ -29,8 +86,6 @@ export type StartWatcherOptions = {
         /** Regex patterns (as strings) to ignore when selecting a stack frame. */
         rules?: string[];
     };
-    /** Whether to include ISO timestamps in log records. Defaults to `false`. */
-    includeTimestamps?: boolean;
     location?: {
         /**
          * Strip these literal prefixes from event.file for display/logging.
@@ -38,18 +93,66 @@ export type StartWatcherOptions = {
          */
         stripUrlPrefixes?: string[];
     };
+    /**
+     * Optional in-page indicator showing that the watcher is attached.
+     * When enabled, a small badge is injected into the page. Clicking it shows watcher info.
+     * The indicator auto-removes via TTL if the watcher dies without cleanup.
+     * Only supported in CDP mode.
+     */
+    pageIndicator?: PageIndicatorOptions;
+    /**
+     * Network request capture configuration.
+     * When enabled, captures HTTP requests and exposes them via `/net` and `/net/tail` endpoints.
+     * Disabled by default. Only supported in CDP mode.
+     */
+    net?: NetOptions;
+    /**
+     * Write watcher lifecycle and request logs into the attached page's DevTools console.
+     * - `none`: Do not write anything.
+     * - `minimal` (default): Write attach/detach lifecycle messages.
+     * - `full`: Same as minimal, plus log every HTTP request to the watcher API.
+     */
+    pageConsoleLogging?: PageConsoleLogging;
+    /**
+     * Optional JavaScript to inject on attach and document start.
+     * The script is provided as raw text to keep watcher package filesystem-agnostic.
+     */
+    inject?: {
+        script: string;
+        exposeArgus?: boolean;
+    };
 };
 /** Handle returned by startWatcher. */
 export type WatcherHandle = {
-    close: () => Promise<void>;
+    /**
+     * The current watcher record (including id/bind address/port and CDP match settings).
+     *
+     * This is the shape announced in the local registry and the same metadata served via the HTTP API.
+     */
     watcher: WatcherRecord;
+    /**
+     * Event emitter for watcher lifecycle and request events.
+     * Subscribe to 'cdpAttached', 'cdpDetached', and 'httpRequested'.
+     */
+    events: Emittery<ArgusWatcherEventMap>;
+    /**
+     * Stop the watcher and release resources.
+     *
+     * Shuts down CDP attachment, stops the HTTP server, closes any artifact writers (file logs),
+     * clears event listeners, and removes the watcher from the local registry.
+     *
+     * Safe to call multiple times.
+     */
+    close: () => Promise<void>;
 };
 /**
- * Start a watcher that connects to Chrome CDP, buffers console logs, and exposes the HTTP API.
- * @param options - Configuration for binding, CDP matching, and buffering.
+ * Start a watcher that connects to Chrome (via CDP or extension), buffers console logs, and exposes the HTTP API.
+ * @param options - Configuration for binding, source mode, and buffering.
  * @returns A handle that can be closed to stop the watcher and clean up registry state.
  */
 export declare const startWatcher: (options: StartWatcherOptions) => Promise<WatcherHandle>;
 /** Log event shape emitted by watchers. */
 export type { LogEvent };
+export type { ArgusWatcherEventMap, CdpAttachedEvent, CdpDetachedEvent, HttpRequestEvent, LogRequestQuery, NetRequestQuery } from './events.js';
+export type { PageIndicatorOptions, PageIndicatorPosition } from './cdp/pageIndicator.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAS9F,yCAAyC;AACzC,MAAM,MAAM,mBAAmB,GAAG;IACjC,sFAAsF;IACtF,EAAE,EAAE,MAAM,CAAA;IACV,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wDAAwD;IACxD,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,wFAAwF;IACxF,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,6FAA6F;IAC7F,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE;QACV,sEAAsE;QACtE,OAAO,EAAE,MAAM,CAAA;QACf,yEAAyE;QACzE,QAAQ,CAAC,EAAE,MAAM,CAAA;KACjB,CAAA;IACD,6EAA6E;IAC7E,UAAU,CAAC,EAAE;QACZ,gEAAgE;QAChE,OAAO,CAAC,EAAE,OAAO,CAAA;QACjB,0EAA0E;QAC1E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAChB,CAAA;IACD,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,EAAE;QACV;;;WAGG;QACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;KAC3B,CAAA;CACD,CAAA;AAED,uCAAuC;AACvC,MAAM,MAAM,aAAa,GAAG;IAC3B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,OAAO,EAAE,aAAa,CAAA;CACtB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAU,SAAS,mBAAmB,KAAG,OAAO,CAAC,aAAa,CAqFtF,CAAA;AAED,2CAA2C;AAC3C,YAAY,EAAE,QAAQ,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,107 +1,394 @@
+import os from 'node:os';
 import path from 'node:path';
-import { startCdpWatcher } from './cdp/watcher.js';
+import Emittery from 'emittery';
 import { LogBuffer } from './buffer/LogBuffer.js';
+import { NetBuffer } from './buffer/NetBuffer.js';
 import { startHttpServer } from './http/server.js';
-import { announceWatcher, removeWatcher, startRegistryHeartbeat } from './registry/registry.js';
+import { announceWatcher, removeWatcher, startRegistryHeartbeat, resolveUniqueWatcherId } from './registry/registry.js';
 import { WatcherFileLogger } from './fileLogs/WatcherFileLogger.js';
 import { buildIgnoreMatcher } from './cdp/ignoreList.js';
+import { createNetworkCapture } from './cdp/networkCapture.js';
+import { createTraceRecorder } from './cdp/tracing.js';
+import { createScreenshotter } from './cdp/screenshot.js';
+import { createCdpSessionHandle } from './cdp/connection.js';
+import { createPageIndicatorController, validatePageIndicatorOptions, } from './cdp/pageIndicator.js';
+import { createEmulationController } from './emulation/EmulationController.js';
+import { createThrottleController } from './throttle/ThrottleController.js';
+import { createCdpSource } from './sources/cdp-source.js';
+import { createExtensionSource } from './sources/extension-source.js';
 /**
- * Start a watcher that connects to Chrome CDP, buffers console logs, and exposes the HTTP API.
- * @param options - Configuration for binding, CDP matching, and buffering.
+ * Start a watcher that connects to Chrome (via CDP or extension), buffers console logs, and exposes the HTTP API.
+ * @param options - Configuration for binding, source mode, and buffering.
  * @returns A handle that can be closed to stop the watcher and clean up registry state.
  */
 export const startWatcher = async (options) => {
     if (!options.id) {
         throw new Error('Watcher id is required');
     }
+    const watcherId = await resolveUniqueWatcherId(options.id);
+    const sourceMode = options.source ?? 'cdp';
     const host = options.host ?? '127.0.0.1';
     const port = options.port ?? 0;
     const chrome = options.chrome ?? { host: '127.0.0.1', port: 9222 };
     const bufferSize = options.bufferSize ?? 50_000;
+    const netBufferSize = options.bufferSize ?? 50_000;
     const startedAt = Date.now();
-    const includeTimestamps = options.includeTimestamps ?? false;
     const ignoreMatcher = buildIgnoreMatcher(options.ignoreList);
     const stripUrlPrefixes = options.location?.stripUrlPrefixes;
+    // Resolve artifacts configuration
+    const artifactsBaseDir = resolveArtifactsBaseDir(options.artifacts?.base, watcherId);
+    const logsEnabled = options.artifacts?.logs?.enabled === true;
+    const logsDir = path.join(artifactsBaseDir, 'logs');
+    const includeTimestamps = options.artifacts?.logs?.includeTimestamps ?? false;
+    const maxFiles = resolveMaxFiles(options.artifacts?.logs?.maxFiles);
+    // Network capture is opt-in (disabled by default) and only in CDP mode
+    const netEnabled = sourceMode === 'cdp' && options.net?.enabled === true;
+    // Page console logging (default: minimal)
+    const pageConsoleLogging = options.pageConsoleLogging ?? 'minimal';
+    const events = new Emittery();
     const buffer = new LogBuffer(bufferSize);
+    const netBuffer = netEnabled ? new NetBuffer(netBufferSize) : null;
+    let closing = false;
+    let readyForShutdown = false;
+    let shutdownRequested = false;
+    let closeOnce = null;
     let cdpStatus = { attached: false, target: null };
-    const fileLogs = options.fileLogs;
-    const logsDir = fileLogs ? resolveLogsDir(fileLogs.logsDir) : null;
-    const maxFiles = fileLogs ? resolveMaxFiles(fileLogs.maxFiles) : null;
-    const fileLogger = logsDir
+    const fileLogger = logsEnabled
         ? new WatcherFileLogger({
-            watcherId: options.id,
+            watcherId,
             startedAt,
             logsDir,
-            chrome,
+            chrome: sourceMode === 'cdp' ? chrome : undefined,
             match: options.match,
-            maxFiles: maxFiles ?? 5,
+            maxFiles,
             includeTimestamps,
+            buildFilename: options.artifacts?.logs?.buildFilename,
         })
         : null;
     const record = {
-        id: options.id,
+        id: watcherId,
         host,
         port,
         pid: process.pid,
+        cwd: process.cwd(),
         startedAt,
         updatedAt: Date.now(),
-        match: options.match,
-        chrome,
+        match: sourceMode === 'cdp' ? options.match : undefined,
+        chrome: sourceMode === 'cdp' ? chrome : undefined,
         includeTimestamps,
+        source: sourceMode,
+    };
+    // Create session handle for CDP mode (used by network capture, tracing, etc.)
+    const sessionHandle = createCdpSessionHandle();
+    // Emulation controller (shared across CDP and extension modes)
+    const emulationController = createEmulationController();
+    // Throttle controller (CPU, network, cache — shared across CDP and extension modes)
+    const throttleController = createThrottleController();
+    const logToPageConsole = (message) => {
+        if (pageConsoleLogging === 'none') {
+            return;
+        }
+        if (!sourceHandle?.session.isAttached()) {
+            return;
+        }
+        const fullMessage = `[ARGUS] ${watcherId} :: ${message}`;
+        queueMicrotask(() => {
+            sourceHandle?.session
+                .sendAndWait('Runtime.evaluate', {
+                expression: `console.log(${JSON.stringify(fullMessage)})`,
+                silent: true,
+            })
+                .catch(() => { });
+        });
+    };
+    // Page indicator only supported in CDP mode
+    validatePageIndicatorOptions(options.pageIndicator);
+    const indicatorEnabled = sourceMode === 'cdp' && options.pageIndicator?.enabled === true;
+    let indicatorController = null;
+    let indicatorAttachedAt = null;
+    if (indicatorEnabled) {
+        indicatorController = createPageIndicatorController(options.pageIndicator);
+    }
+    const buildIndicatorInfo = (target) => ({
+        watcherId,
+        watcherHost: host,
+        watcherPort: record.port,
+        watcherPid: process.pid,
+        targetTitle: target?.title ?? null,
+        targetUrl: target?.url ?? null,
+        attachedAt: indicatorAttachedAt ?? Date.now(),
+    });
+    const maybeInjectOnAttach = async (session, target) => {
+        if (!options.inject?.script) {
+            return;
+        }
+        if (!session.isAttached()) {
+            return;
+        }
+        const trimmedScript = options.inject.script.trim();
+        if (trimmedScript === '') {
+            console.warn(`[Watcher] Inject script is empty for watcher ${record.id}. Skipping.`);
+            return;
+        }
+        const attachedAt = Date.now();
+        const exposeArgus = options.inject.exposeArgus ?? true;
+        const argusPayload = exposeArgus
+            ? {
+                watcherId: record.id,
+                watcherHost: record.host,
+                watcherPort: record.port,
+                watcherPid: record.pid,
+                attachedAt,
+                target: {
+                    title: target.title ?? null,
+                    url: target.url ?? null,
+                    type: target.type ?? 'page',
+                    parentId: target.parentId ?? null,
+                },
+            }
+            : null;
+        const expression = buildInjectExpression(trimmedScript, argusPayload);
+        try {
+            await session.sendAndWait('Page.addScriptToEvaluateOnNewDocument', { source: expression });
+        }
+        catch (error) {
+            console.warn(`[Watcher] Failed to register inject script for watcher ${record.id}: ${formatError(error)}`);
+        }
+        try {
+            await session.sendAndWait('Runtime.evaluate', { expression, silent: true });
+        }
+        catch (error) {
+            console.warn(`[Watcher] Failed to run inject script for watcher ${record.id}: ${formatError(error)}`);
+        }
     };
+    // Create the appropriate source based on mode
+    let sourceHandle;
+    let networkCapture = null;
+    let traceRecorder;
+    let screenshotter;
+    if (sourceMode === 'extension') {
+        // Extension mode
+        sourceHandle = createExtensionSource({
+            events: {
+                onLog: (event) => {
+                    buffer.add(event);
+                    fileLogger?.writeEvent(event);
+                },
+                onStatus: (status) => {
+                    const prevAttached = cdpStatus.attached;
+                    cdpStatus = status;
+                    if (status.attached && !prevAttached) {
+                        const url = status.target?.url ?? 'unknown';
+                        logToPageConsole(`attached (url=${url})`);
+                        void events.emit('cdpAttached', {
+                            ts: Date.now(),
+                            watcherId,
+                            target: status.target,
+                        });
+                    }
+                    else if (!status.attached && prevAttached) {
+                        void events.emit('cdpDetached', {
+                            ts: Date.now(),
+                            watcherId,
+                            target: status.target,
+                            reason: status.reason ?? 'unknown',
+                        });
+                    }
+                },
+                onPageNavigation: (info) => {
+                    fileLogger?.rotate(info);
+                },
+                onPageIntl: (info) => {
+                    fileLogger?.setPageIntl(info);
+                },
+                onAttach: async (session, target) => {
+                    await emulationController.onAttach(session);
+                    await throttleController.onAttach(session);
+                    await maybeInjectOnAttach(session, target);
+                },
+            },
+            ignoreMatcher: ignoreMatcher ? (url) => ignoreMatcher.matches(url) : null,
+            stripUrlPrefixes,
+        });
+        // Create trace/screenshot with proxy session
+        traceRecorder = createTraceRecorder({ session: sourceHandle.session, artifactsDir: artifactsBaseDir });
+        screenshotter = createScreenshotter({ session: sourceHandle.session, artifactsDir: artifactsBaseDir });
+    }
+    else {
+        // CDP mode
+        networkCapture = netBuffer ? createNetworkCapture({ session: sessionHandle.session, buffer: netBuffer }) : null;
+        traceRecorder = createTraceRecorder({ session: sessionHandle.session, artifactsDir: artifactsBaseDir });
+        screenshotter = createScreenshotter({ session: sessionHandle.session, artifactsDir: artifactsBaseDir });
+        sourceHandle = createCdpSource({
+            chrome,
+            match: options.match,
+            sessionHandle,
+            events: {
+                onLog: (event) => {
+                    buffer.add(event);
+                    fileLogger?.writeEvent(event);
+                },
+                onStatus: (status) => {
+                    const prevAttached = cdpStatus.attached;
+                    cdpStatus = status;
+                    if (status.attached && !prevAttached) {
+                        const url = status.target?.url ?? 'unknown';
+                        logToPageConsole(`attached (url=${url})`);
+                        void events.emit('cdpAttached', {
+                            ts: Date.now(),
+                            watcherId,
+                            target: status.target,
+                        });
+                    }
+                    else if (!status.attached && prevAttached) {
+                        void events.emit('cdpDetached', {
+                            ts: Date.now(),
+                            watcherId,
+                            target: status.target,
+                            reason: status.reason ?? 'unknown',
+                        });
+                    }
+                },
+                onPageNavigation: (info) => {
+                    fileLogger?.rotate(info);
+                    if (indicatorController) {
+                        indicatorController.onNavigation(sessionHandle.session, buildIndicatorInfo({ title: null, url: info.url }));
+                    }
+                },
+                onPageLoad: () => {
+                    if (indicatorController) {
+                        indicatorController.reinstall();
+                    }
+                },
+                onPageIntl: (info) => {
+                    fileLogger?.setPageIntl(info);
+                },
+                onAttach: async (session, target) => {
+                    await emulationController.onAttach(session);
+                    await throttleController.onAttach(session);
+                    await networkCapture?.onAttached();
+                    if (indicatorController) {
+                        indicatorAttachedAt = Date.now();
+                        indicatorController.onAttach(session, {
+                            id: target.id,
+                            title: target.title,
+                            url: target.url,
+                            type: target.type ?? 'page',
+                            parentId: target.parentId ?? null,
+                            webSocketDebuggerUrl: '',
+                        }, buildIndicatorInfo({ title: target.title, url: target.url }));
+                    }
+                    await maybeInjectOnAttach(session, target);
+                },
+                onDetach: (reason) => {
+                    networkCapture?.onDetached();
+                    traceRecorder.onDetached(reason);
+                    indicatorController?.onDetach();
+                },
+            },
+            ignoreMatcher: ignoreMatcher ? (url) => ignoreMatcher.matches(url) : null,
+            stripUrlPrefixes,
+        });
+    }
     const server = await startHttpServer({
         host,
         port,
         buffer,
+        netBuffer,
         getWatcher: () => record,
         getCdpStatus: () => cdpStatus,
+        cdpSession: sourceHandle.session,
+        traceRecorder,
+        screenshotter,
+        emulationController,
+        throttleController,
+        // Extension mode endpoints
+        sourceHandle: sourceMode === 'extension' ? sourceHandle : undefined,
+        onRequest: (event) => {
+            if (pageConsoleLogging === 'full') {
+                logToPageConsole(`http ${event.endpoint}`);
+            }
+            void events.emit('httpRequested', {
+                ...event,
+                watcherId,
+            });
+        },
+        onShutdown: () => {
+            if (!readyForShutdown || !closeOnce) {
+                shutdownRequested = true;
+                return;
+            }
+            void closeOnce();
+        },
     });
     record.port = server.port;
     await announceWatcher(record);
     const heartbeat = startRegistryHeartbeat(() => record, options.heartbeatMs ?? 15_000);
-    const cdp = startCdpWatcher({
-        chrome,
-        match: options.match,
-        ignoreMatcher,
-        stripUrlPrefixes,
-        onLog: (event) => {
-            buffer.add(event);
-            fileLogger?.writeEvent(event);
-        },
-        onPageNavigation: (info) => {
-            fileLogger?.rotate(info);
-        },
-        onPageIntl: (info) => {
-            fileLogger?.setPageIntl(info);
-        },
-        onStatus: (status) => {
-            cdpStatus = status;
-        },
-    });
+    closeOnce = async () => {
+        if (closing) {
+            return;
+        }
+        closing = true;
+        heartbeat.stop();
+        indicatorController?.stop();
+        if (cdpStatus.attached) {
+            logToPageConsole('detached (reason=watcher_stopped)');
+        }
+        await sourceHandle.stop();
+        await fileLogger?.close();
+        traceRecorder.onDetached('watcher_stopped');
+        await server.close();
+        await removeWatcher(record.id);
+        events.clearListeners();
+    };
+    readyForShutdown = true;
+    if (shutdownRequested) {
+        void closeOnce();
+    }
     return {
         watcher: record,
+        events,
         close: async () => {
-            heartbeat.stop();
-            await cdp.stop();
-            await fileLogger?.close();
-            await server.close();
-            await removeWatcher(record.id);
+            await closeOnce?.();
         },
     };
 };
-const resolveLogsDir = (logsDir) => {
-    if (typeof logsDir !== 'string' || logsDir.trim() === '') {
-        throw new Error('fileLogs.logsDir is required');
+const resolveArtifactsBaseDir = (base, watcherId) => {
+    if (base !== undefined && base !== null) {
+        if (typeof base !== 'string' || base.trim() === '') {
+            throw new Error('artifacts.base must be a non-empty string when provided');
+        }
+        return path.resolve(base);
     }
-    return path.resolve(logsDir);
+    return path.join(os.tmpdir(), 'argus', watcherId);
 };
 const resolveMaxFiles = (maxFiles) => {
     if (maxFiles === undefined) {
         return 5;
     }
     if (!Number.isInteger(maxFiles) || maxFiles < 1) {
-        throw new Error('fileLogs.maxFiles must be an integer >= 1');
+        throw new Error('artifacts.logs.maxFiles must be an integer >= 1');
     }
     return maxFiles;
 };
+const buildInjectExpression = (script, argusPayload) => {
+    const lines = ['(() => {'];
+    if (argusPayload) {
+        lines.push(`window.__ARGUS__ = ${JSON.stringify(argusPayload)};`);
+    }
+    lines.push(`const __argusScript = ${JSON.stringify(script)};`);
+    lines.push('const __argusFn = new Function(__argusScript);');
+    lines.push('__argusFn();');
+    lines.push('})();');
+    return lines.join('\n');
+};
+const formatError = (error) => {
+    if (!error) {
+        return 'Unknown error';
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+};
 //# sourceMappingURL=index.js.map