@vforsh/argus-watcher 0.3.0 → 0.4.0

package/dist/emulation/EmulationController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EmulationController.d.ts","sourceRoot":"","sources":["../../src/emulation/EmulationController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAC/H,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAK5D,MAAM,MAAM,mBAAmB,GAAG;IACjC,SAAS,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,KAAK,uBAAuB,CAAA;IAClE,UAAU,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACtG,YAAY,EAAE,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAA;IACnF,QAAQ,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtD,CAAA;AAED,eAAO,MAAM,yBAAyB,QAAO,mBAwF5C,CAAA"}
+{"version":3,"file":"EmulationController.d.ts","sourceRoot":"","sources":["../../src/emulation/EmulationController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAC/H,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAK5D,MAAM,MAAM,mBAAmB,GAAG;IACjC,SAAS,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,KAAK,uBAAuB,CAAA;IAClE,UAAU,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACtG,YAAY,EAAE,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAA;IACnF,QAAQ,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,QAAO,mBA6B5C,CAAA"}

package/dist/emulation/EmulationController.js

@@ -1,83 +1,39 @@
 import { applyEmulation, clearEmulation } from '../cdp/emulation.js';
+import { evaluateInPage } from '../cdp/pageState.js';
+import { createStickyController } from '../stickyController.js';
+/**
+ * Desired viewport/touch/user-agent emulation, re-applied on every attach until cleared.
+ *
+ * Unlike the other sticky controllers this carries a baseline: the pre-override user-agent
+ * has to be sampled from a fresh session before anything is applied, so clearing can
+ * restore it.
+ */
 export const createEmulationController = () => {
-    let desired = null;
-    let applied = false;
     let baselineUserAgent = null;
-    let lastError = null;
     const getBaseline = () => ({ userAgent: baselineUserAgent });
-    const getStatus = (ctx) => ({
-        ok: true,
-        attached: ctx.attached,
-        applied,
-        state: desired,
-        baseline: { userAgent: baselineUserAgent },
-        lastError,
-    });
-    const setDesired = async (state, session) => {
-        desired = state;
-        lastError = null;
-        if (!session || !session.isAttached()) {
-            applied = false;
-            return { ok: true, attached: false, applied: false, state: desired };
-        }
-        try {
-            await applyEmulation(session, state, getBaseline());
-            applied = true;
-            return { ok: true, attached: true, applied: true, state: desired };
-        }
-        catch (error) {
-            applied = false;
-            lastError = { message: error instanceof Error ? error.message : String(error) };
-            return { ok: true, attached: true, applied: false, state: desired, error: lastError };
-        }
-    };
-    const clearDesired = async (session) => {
-        desired = null;
-        lastError = null;
-        if (!session || !session.isAttached()) {
-            applied = false;
-            return { ok: true, attached: false, applied: false, state: null };
-        }
-        try {
-            await clearEmulation(session, getBaseline());
-            applied = false;
-            return { ok: true, attached: true, applied: true, state: null };
-        }
-        catch (error) {
-            applied = false;
-            lastError = { message: error instanceof Error ? error.message : String(error) };
-            return { ok: true, attached: true, applied: false, state: null, error: lastError };
-        }
-    };
-    const onAttach = async (session) => {
-        // Capture baseline UA before any overrides
-        try {
-            const result = (await session.sendAndWait('Runtime.evaluate', {
-                expression: 'navigator.userAgent',
-                returnByValue: true,
-            }));
-            const value = result?.result?.value;
+    const sticky = createStickyController({
+        label: 'Emulation',
+        apply: (session, state) => applyEmulation(session, state, getBaseline()),
+        clear: (session) => clearEmulation(session, getBaseline()),
+        onBeforeReapply: async (session) => {
+            const value = await evaluateInPage(session, 'navigator.userAgent').catch(() => null);
             baselineUserAgent = typeof value === 'string' ? value : null;
-        }
-        catch {
-            baselineUserAgent = null;
-        }
-        // Re-apply desired state if set (persist-until-clear semantics)
-        if (!desired) {
-            applied = false;
-            return;
-        }
-        try {
-            await applyEmulation(session, desired, getBaseline());
-            applied = true;
-            lastError = null;
-        }
-        catch (error) {
-            applied = false;
-            lastError = { message: error instanceof Error ? error.message : String(error) };
-            console.warn(`[Emulation] Failed to re-apply emulation on attach: ${lastError.message}`);
-        }
+        },
+    });
+    return {
+        getStatus: (ctx) => {
+            const { applied, state, lastError } = sticky.getState();
+            return { ok: true, attached: ctx.attached, applied, state, baseline: getBaseline(), lastError };
+        },
+        setDesired: async (state, session) => {
+            const { attached, applied, state: next, lastError } = await sticky.setDesired(state, session);
+            return { ok: true, attached, applied, state: next, ...(lastError ? { error: lastError } : {}) };
+        },
+        clearDesired: async (session) => {
+            const { attached, applied, lastError } = await sticky.clearDesired(session);
+            return { ok: true, attached, applied, state: null, ...(lastError ? { error: lastError } : {}) };
+        },
+        onAttach: sticky.onAttach,
     };
-    return { getStatus, setDesired, clearDesired, onAttach };
 };
 //# sourceMappingURL=EmulationController.js.map

package/dist/emulation/EmulationController.js.map

@@ -1 +1 @@
-{"version":3,"file":"EmulationController.js","sourceRoot":"","sources":["../../src/emulation/EmulationController.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"EmulationController.js","sourceRoot":"","sources":["../../src/emulation/EmulationController.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAS/D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAwB,EAAE;IAClE,IAAI,iBAAiB,GAAkB,IAAI,CAAA;IAC3C,MAAM,WAAW,GAAG,GAAG,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC,CAAA;IAE5D,MAAM,MAAM,GAAG,sBAAsB,CAAiB;QACrD,KAAK,EAAE,WAAW;QAClB,KAAK,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QACxE,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,CAAC;QAC1D,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YAClC,MAAM,KAAK,GAAG,MAAM,cAAc,CAAU,OAAO,EAAE,qBAAqB,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAA;YAC7F,iBAAiB,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAA;QAC7D,CAAC;KACD,CAAC,CAAA;IAEF,OAAO;QACN,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE;YAClB,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAA;YACvD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,SAAS,EAAE,CAAA;QAChG,CAAC;QACD,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACpC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;YAC7F,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;QAChG,CAAC;QACD,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YAC/B,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA;YAC3E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;QAChG,CAAC;QACD,QAAQ,EAAE,MAAM,CAAC,QAAQ;KACzB,CAAA;AACF,CAAC,CAAA"}

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The cross-layer coded-error contract.
+ *
+ * Failures travel from CDP and source layers up to the HTTP routes as an `Error` carrying
+ * a string `code`, which routes map onto the wire envelope. That contract had no owning
+ * type or constructor, so producers mutated-and-cast at six-plus sites and consumers
+ * re-derived the sniff at eight more, in four different idioms. The duplicated
+ * `createNotAttachedError` in two source modules was the tell: the concept existed, the
+ * abstraction did not.
+ */
+import { type ArgusErrorCode } from '@vforsh/argus-core';
+/** An `Error` carrying a machine-readable code. */
+export type CodedError = Error & {
+    code: ArgusErrorCode;
+};
+/** Build an error the HTTP layer can map onto an error code. */
+export declare const codedError: (code: ArgusErrorCode, message: string) => CodedError;
+/**
+ * Read the protocol error code off an error, or `undefined` when it carries none.
+ *
+ * Deliberately narrowed to {@link ArgusErrorCode}: errors reaching the HTTP layer include Node's
+ * own (`ENOENT`, `ESRCH`, …), and those must not be forwarded as if they were protocol codes.
+ */
+export declare const getErrorCode: (error: unknown) => ArgusErrorCode | undefined;
+/** True when an error carries this exact code. */
+export declare const hasErrorCode: (error: unknown, code: ArgusErrorCode) => boolean;
+/** The watcher is not attached to a CDP target. Raised by both transports. */
+export declare const createNotAttachedError: (message?: string) => CodedError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAE1E,mDAAmD;AACnD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,CAAA;AAEzD,gEAAgE;AAChE,eAAO,MAAM,UAAU,GAAI,MAAM,cAAc,EAAE,SAAS,MAAM,KAAG,UAAyD,CAAA;AAE5H;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,cAAc,GAAG,SAO9D,CAAA;AAED,kDAAkD;AAClD,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,EAAE,MAAM,cAAc,KAAG,OAAuC,CAAA;AAE3G,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,GAAI,gBAAyC,KAAG,UAAqD,CAAA"}

package/dist/errors.js

@@ -0,0 +1,31 @@
+/**
+ * The cross-layer coded-error contract.
+ *
+ * Failures travel from CDP and source layers up to the HTTP routes as an `Error` carrying
+ * a string `code`, which routes map onto the wire envelope. That contract had no owning
+ * type or constructor, so producers mutated-and-cast at six-plus sites and consumers
+ * re-derived the sniff at eight more, in four different idioms. The duplicated
+ * `createNotAttachedError` in two source modules was the tell: the concept existed, the
+ * abstraction did not.
+ */
+import { isArgusErrorCode } from '@vforsh/argus-core';
+/** Build an error the HTTP layer can map onto an error code. */
+export const codedError = (code, message) => Object.assign(new Error(message), { code });
+/**
+ * Read the protocol error code off an error, or `undefined` when it carries none.
+ *
+ * Deliberately narrowed to {@link ArgusErrorCode}: errors reaching the HTTP layer include Node's
+ * own (`ENOENT`, `ESRCH`, …), and those must not be forwarded as if they were protocol codes.
+ */
+export const getErrorCode = (error) => {
+    if (!error || typeof error !== 'object' || !('code' in error)) {
+        return undefined;
+    }
+    const code = error.code;
+    return isArgusErrorCode(code) ? code : undefined;
+};
+/** True when an error carries this exact code. */
+export const hasErrorCode = (error, code) => getErrorCode(error) === code;
+/** The watcher is not attached to a CDP target. Raised by both transports. */
+export const createNotAttachedError = (message = 'No tab attached via extension') => codedError('cdp_not_attached', message);
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,gBAAgB,EAAuB,MAAM,oBAAoB,CAAA;AAK1E,gEAAgE;AAChE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAoB,EAAE,OAAe,EAAc,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;AAE5H;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAc,EAA8B,EAAE;IAC1E,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC;QAC/D,OAAO,SAAS,CAAA;IACjB,CAAC;IAED,MAAM,IAAI,GAAI,KAA4B,CAAC,IAAI,CAAA;IAC/C,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AACjD,CAAC,CAAA;AAED,kDAAkD;AAClD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAc,EAAE,IAAoB,EAAW,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,IAAI,CAAA;AAE3G,8EAA8E;AAC9E,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,OAAO,GAAG,+BAA+B,EAAc,EAAE,CAAC,UAAU,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAA"}

package/dist/events.d.ts

@@ -1,4 +1,4 @@
-import type { LogLevel, NetRequestBodyPart } from '@vforsh/argus-core';
+import type { WatcherEndpoint, WatcherRequestQuery } from './http/endpoints.js';
 /**
  * Event payload for when the watcher attaches to a CDP target.
  */
@@ -37,55 +37,6 @@ export type CdpDetachedEvent = {
         url: string | null;
     } | null;
 };
-/**
- * Query parameters for log/tail requests.
- */
-export type LogRequestQuery = {
-    /** Opaque cursor returned by `/logs/cursor` or `/logs/epoch`. */
-    after?: string;
-    /** Alias for `after` with explicit baseline semantics. */
-    sinceEpoch?: string;
-    limit?: number;
-    levels?: LogLevel[];
-    match?: string[];
-    matchCase?: 'sensitive' | 'insensitive';
-    source?: string;
-    sinceTs?: number;
-    timeoutMs?: number;
-};
-/**
- * Query parameters for network/tail requests.
- */
-export type NetRequestQuery = {
-    id?: number;
-    requestId?: string;
-    part?: NetRequestBodyPart;
-    after?: number;
-    limit?: number;
-    sinceTs?: number;
-    timeoutMs?: number;
-    grep?: string;
-    ignoreHosts?: string[];
-    ignorePatterns?: string[];
-    hosts?: string[];
-    methods?: string[];
-    statuses?: string[];
-    resourceTypes?: string[];
-    mimeTypes?: string[];
-    scope?: string;
-    frame?: string;
-    party?: string;
-    failedOnly?: boolean;
-    minDurationMs?: number;
-    minTransferBytes?: number;
-    origin?: string;
-    domain?: string;
-    includeValues?: boolean;
-};
-export type TabListRequestQuery = {
-    url?: string;
-    title?: string;
-};
 /**
  * Event payload for when a client requests logs or tail via HTTP.
  */
@@ -95,11 +46,11 @@ export type HttpRequestEvent = {
     /** Unique watcher identifier. */
     watcherId: string;
     /** The requested endpoint. */
-    endpoint: 'logs' | 'tail' | 'net' | 'net/requests' | 'net/request' | 'net/request/body' | 'net/tail' | 'net/clear' | 'net/mock' | 'net/mock/add' | 'net/mock/remove' | 'net/mock/clear' | 'net/ws' | 'net/ws/connection' | 'net/sse' | 'auth/cookies' | 'auth/cookies/get' | 'auth/cookies/set' | 'auth/cookies/delete' | 'auth/cookies/clear' | 'auth/state' | 'auth/state/load' | 'eval' | 'trace/start' | 'trace/stop' | 'record' | 'record/start' | 'record/stop' | 'screenshot' | 'snapshot' | 'locate/role' | 'locate/text' | 'locate/label' | 'code/list' | 'code/read' | 'code/grep' | 'code/edit' | 'dom/tree' | 'dom/info' | 'dom/hover' | 'dom/click' | 'dom/drag' | 'dom/keydown' | 'dom/add' | 'dom/remove' | 'dom/modify' | 'dom/set-file' | 'dom/focus' | 'dom/fill' | 'dom/scroll' | 'dom/scroll-to' | 'emulation' | 'throttle' | 'dialog/status' | 'dialog/handle' | 'visibility' | 'storage/local' | 'storage/session' | 'reload' | 'shutdown' | 'tabs' | 'extension/diagnostics' | 'targets' | 'attach' | 'detach';
+    endpoint: WatcherEndpoint;
     /** IP address of the requester (best-effort). */
     remoteAddress: string | null;
     /** Parsed query parameters. */
-    query?: LogRequestQuery | NetRequestQuery | TabListRequestQuery;
+    query?: WatcherRequestQuery;
 };
 /**
  * Map of events emitted by the Argus watcher.

package/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAE/E;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,2BAA2B;IAC3B,MAAM,EAAE;QACP,gDAAgD;QAChD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;QACpB,+BAA+B;QAC/B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;QAClB,sDAAsD;QACtD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;QACnB,qFAAqF;QACrF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KACvB,GAAG,IAAI,CAAA;CACR,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAA;IACd,sCAAsC;IACtC,MAAM,EAAE;QACP,gDAAgD;QAChD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;QACpB,+BAA+B;QAC/B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAClB,GAAG,IAAI,CAAA;CACR,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,8BAA8B;IAC9B,QAAQ,EAAE,eAAe,CAAA;IACzB,iDAAiD;IACjD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,+BAA+B;IAC/B,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAC3B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,WAAW,EAAE,gBAAgB,CAAA;IAC7B,WAAW,EAAE,gBAAgB,CAAA;IAC7B,aAAa,EAAE,gBAAgB,CAAA;CAC/B,CAAA"}

package/dist/http/endpoints.d.ts

@@ -0,0 +1,54 @@
+import type { LogLevel, NetParty, NetRequestBodyPart, NetScope } from '@vforsh/argus-core';
+/**
+ * Every endpoint the watcher serves, as it appears in the public `httpRequested` event.
+ *
+ * One list, imported by both the HTTP server's request metadata and the public event type. It
+ * used to be hand-maintained in both files, so adding a route meant editing the same 61 literals
+ * twice or emitting an endpoint the public event could not name.
+ */
+export declare const WATCHER_ENDPOINTS: readonly ["logs", "tail", "net", "net/requests", "net/request", "net/request/body", "net/tail", "net/clear", "net/mock", "net/mock/add", "net/mock/remove", "net/mock/clear", "net/ws", "net/ws/connection", "net/sse", "auth/cookies", "auth/cookies/get", "auth/cookies/set", "auth/cookies/delete", "auth/cookies/clear", "auth/state", "auth/state/load", "eval", "trace/start", "trace/stop", "record", "record/start", "record/stop", "screenshot", "snapshot", "locate/role", "locate/text", "locate/label", "code/list", "code/read", "code/grep", "code/edit", "dom/tree", "dom/info", "dom/hover", "dom/click", "dom/drag", "dom/keydown", "dom/add", "dom/remove", "dom/modify", "dom/set-file", "dom/focus", "dom/fill", "dom/scroll", "dom/scroll-to", "emulation", "throttle", "dialog/status", "dialog/handle", "visibility", "storage/local", "storage/session", "reload", "shutdown", "tabs", "extension/diagnostics", "targets", "attach", "detach"];
+/** An endpoint the watcher serves. */
+export type WatcherEndpoint = (typeof WATCHER_ENDPOINTS)[number];
+/**
+ * Query parameters reported alongside a served request.
+ *
+ * Deliberately one all-optional shape rather than a union per endpoint family. The union that
+ * used to sit on the public event was decorative: its `TabListRequestQuery` arm was all-optional,
+ * so TypeScript's weak-type check accepted essentially any of the other arms' objects and nothing
+ * was ever actually discriminated — while every new route still had to be added to both models.
+ */
+export type WatcherRequestQuery = {
+    id?: number;
+    requestId?: string;
+    part?: NetRequestBodyPart;
+    /** Opaque cursor for logs; numeric record cursor for net. */
+    after?: number | string;
+    sinceEpoch?: string;
+    limit?: number;
+    levels?: LogLevel[];
+    match?: string[];
+    matchCase?: 'sensitive' | 'insensitive';
+    source?: string;
+    sinceTs?: number;
+    timeoutMs?: number;
+    grep?: string;
+    hosts?: string[];
+    methods?: string[];
+    statuses?: string[];
+    resourceTypes?: string[];
+    mimeTypes?: string[];
+    scope?: NetScope;
+    frame?: string;
+    party?: NetParty;
+    failedOnly?: boolean;
+    minDurationMs?: number;
+    minTransferBytes?: number;
+    ignoreHosts?: string[];
+    ignorePatterns?: string[];
+    origin?: string;
+    domain?: string;
+    url?: string;
+    title?: string;
+    includeValues?: boolean;
+};
+//# sourceMappingURL=endpoints.d.ts.map

package/dist/http/endpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.d.ts","sourceRoot":"","sources":["../../src/http/endpoints.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAE1F;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,w6BAkEpB,CAAA;AAEV,sCAAsC;AACtC,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEhE;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG;IACjC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,kBAAkB,CAAA;IACzB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,SAAS,CAAC,EAAE,WAAW,GAAG,aAAa,CAAA;IACvC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,aAAa,CAAC,EAAE,OAAO,CAAA;CACvB,CAAA"}

package/dist/http/endpoints.js

@@ -0,0 +1,75 @@
+/**
+ * Every endpoint the watcher serves, as it appears in the public `httpRequested` event.
+ *
+ * One list, imported by both the HTTP server's request metadata and the public event type. It
+ * used to be hand-maintained in both files, so adding a route meant editing the same 61 literals
+ * twice or emitting an endpoint the public event could not name.
+ */
+export const WATCHER_ENDPOINTS = [
+    'logs',
+    'tail',
+    'net',
+    'net/requests',
+    'net/request',
+    'net/request/body',
+    'net/tail',
+    'net/clear',
+    'net/mock',
+    'net/mock/add',
+    'net/mock/remove',
+    'net/mock/clear',
+    'net/ws',
+    'net/ws/connection',
+    'net/sse',
+    'auth/cookies',
+    'auth/cookies/get',
+    'auth/cookies/set',
+    'auth/cookies/delete',
+    'auth/cookies/clear',
+    'auth/state',
+    'auth/state/load',
+    'eval',
+    'trace/start',
+    'trace/stop',
+    'record',
+    'record/start',
+    'record/stop',
+    'screenshot',
+    'snapshot',
+    'locate/role',
+    'locate/text',
+    'locate/label',
+    'code/list',
+    'code/read',
+    'code/grep',
+    'code/edit',
+    'dom/tree',
+    'dom/info',
+    'dom/hover',
+    'dom/click',
+    'dom/drag',
+    'dom/keydown',
+    'dom/add',
+    'dom/remove',
+    'dom/modify',
+    'dom/set-file',
+    'dom/focus',
+    'dom/fill',
+    'dom/scroll',
+    'dom/scroll-to',
+    'emulation',
+    'throttle',
+    'dialog/status',
+    'dialog/handle',
+    'visibility',
+    'storage/local',
+    'storage/session',
+    'reload',
+    'shutdown',
+    'tabs',
+    'extension/diagnostics',
+    'targets',
+    'attach',
+    'detach',
+];
+//# sourceMappingURL=endpoints.js.map

package/dist/http/endpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.js","sourceRoot":"","sources":["../../src/http/endpoints.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAChC,MAAM;IACN,MAAM;IACN,KAAK;IACL,cAAc;IACd,aAAa;IACb,kBAAkB;IAClB,UAAU;IACV,WAAW;IACX,UAAU;IACV,cAAc;IACd,iBAAiB;IACjB,gBAAgB;IAChB,QAAQ;IACR,mBAAmB;IACnB,SAAS;IACT,cAAc;IACd,kBAAkB;IAClB,kBAAkB;IAClB,qBAAqB;IACrB,oBAAoB;IACpB,YAAY;IACZ,iBAAiB;IACjB,MAAM;IACN,aAAa;IACb,YAAY;IACZ,QAAQ;IACR,cAAc;IACd,aAAa;IACb,YAAY;IACZ,UAAU;IACV,aAAa;IACb,aAAa;IACb,cAAc;IACd,WAAW;IACX,WAAW;IACX,WAAW;IACX,WAAW;IACX,UAAU;IACV,UAAU;IACV,WAAW;IACX,WAAW;IACX,UAAU;IACV,aAAa;IACb,SAAS;IACT,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,WAAW;IACX,UAAU;IACV,YAAY;IACZ,eAAe;IACf,WAAW;IACX,UAAU;IACV,eAAe;IACf,eAAe;IACf,YAAY;IACZ,eAAe;IACf,iBAAiB;IACjB,QAAQ;IACR,UAAU;IACV,MAAM;IACN,uBAAuB;IACvB,SAAS;IACT,QAAQ;IACR,QAAQ;CACC,CAAA"}

package/dist/http/httpUtils.d.ts

@@ -1,14 +1,58 @@
 import http from 'node:http';
-import type { LogLevel } from '@vforsh/argus-core';
+import { type ArgusErrorCode, type LogLevel } from '@vforsh/argus-core';
 export declare const respondJson: <T extends object>(res: http.ServerResponse, body: T, status?: number) => void;
+/**
+ * Send an `ok: false` failure envelope.
+ *
+ * The only way a route should build one. Routes used to hand-roll the object literal without a
+ * `satisfies ErrorResponse`, so their `code` was an unchecked string and a rename of an
+ * {@link ArgusErrorCode} member would not have broken them — the typed `code` parameter here closes
+ * that hole for every caller at once. `undefined` is allowed only because an arbitrary thrown error
+ * may not map to a known code (see {@link respondError}).
+ */
+export declare const respondApiError: (res: http.ServerResponse, status: number, code: ArgusErrorCode | undefined, message: string) => void;
 export declare const respondInvalidMatch: (res: http.ServerResponse, message: string) => void;
 export declare const respondInvalidMatchCase: (res: http.ServerResponse) => void;
 export declare const respondInvalidBody: (res: http.ServerResponse, message: string) => void;
 export declare const respondInvalidJson: (res: http.ServerResponse) => void;
 export declare const respondPayloadTooLarge: (res: http.ServerResponse) => void;
 export declare const respondError: (res: http.ServerResponse, error: unknown) => void;
-export declare const readJsonBody: <T>(req: http.IncomingMessage, res: http.ServerResponse) => Promise<T | null>;
-export declare const clampNumber: (value: string | null, fallback?: number, min?: number, max?: number) => number;
+/**
+ * Read and parse a JSON request body.
+ *
+ * An absent or empty body yields `{}` rather than an error: `defineJsonRoute` hands the
+ * result straight to a protocol schema, which rejects it with a real per-field message.
+ * This used to be a documented gotcha ("routes must validate required fields explicitly")
+ * because the empty object was cast to the route's body type and reached the handler
+ * unvalidated; the schema layer now owns that proof.
+ *
+ * @returns The parsed body, or `null` when a response has already been sent (oversized
+ *   payload or malformed JSON).
+ */
+export declare const readJsonBody: (req: http.IncomingMessage, res: http.ServerResponse) => Promise<unknown | null>;
+/**
+ * Read a numeric query param that always resolves to a number.
+ *
+ * Absent or non-numeric values fall back to `fallback`; in-range values are clamped
+ * into `[min, max]`. Use {@link optionalNumber} when "absent" must stay distinguishable
+ * from a real value — this function cannot express it.
+ */
+export declare const clampNumber: (value: string | null, fallback: number, min?: number, max?: number) => number;
+/**
+ * Read an optional numeric query param.
+ *
+ * Returns `undefined` when the param is absent or non-numeric, so callers can tell
+ * "not provided" from a provided `0`. Provided values are clamped into `[min, max]`.
+ */
+export declare const optionalNumber: (value: string | null, min?: number, max?: number) => number | undefined;
+/**
+ * Read an optional positive-integer query param (buffer ids and other 1-based handles).
+ *
+ * Unlike {@link optionalNumber} this rejects rather than clamps: fractional, negative,
+ * zero, and unsafe-integer values all yield `undefined` so a bad id can never be
+ * silently coerced into a valid lookup.
+ */
+export declare const optionalPositiveInt: (value: string | null) => number | undefined;
 export declare const parseLevels: (value: string | null) => LogLevel[] | undefined;
 export declare const resolveMatchCase: (value: string | null) => "sensitive" | "insensitive" | null;
 export declare const normalizeMatchPatterns: (match: string[]) => {

package/dist/http/httpUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"httpUtils.d.ts","sourceRoot":"","sources":["../../src/http/httpUtils.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,KAAK,EAAiB,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAEjE,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,EAAE,eAAY,KAAG,IAK/F,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,KAAK,IAAI,CAAC,cAAc,EAAE,SAAS,MAAM,KAAG,IAE/E,CAAA;AAED,eAAO,MAAM,uBAAuB,GAAI,KAAK,IAAI,CAAC,cAAc,KAAG,IAElE,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAI,KAAK,IAAI,CAAC,cAAc,EAAE,SAAS,MAAM,KAAG,IAE9E,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAI,KAAK,IAAI,CAAC,cAAc,KAAG,IAE7D,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,KAAK,IAAI,CAAC,cAAc,KAAG,IAEjE,CAAA;AAED,eAAO,MAAM,YAAY,GAAI,KAAK,IAAI,CAAC,cAAc,EAAE,OAAO,OAAO,KAAG,IAIvE,CAAA;AAED,eAAO,MAAM,YAAY,GAAU,CAAC,EAAE,KAAK,IAAI,CAAC,eAAe,EAAE,KAAK,IAAI,CAAC,cAAc,KAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAkC3G,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,GAAG,IAAI,EAAE,WAAW,MAAM,EAAE,MAAM,MAAM,EAAE,MAAM,MAAM,KAAG,MAmBjG,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,GAAG,IAAI,KAAG,QAAQ,EAAE,GAAG,SAe/D,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,GAAG,IAAI,KAAG,WAAW,GAAG,aAAa,GAAG,IAUrF,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,OAAO,MAAM,EAAE,KAAG;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAW5F,CAAA;AAED,eAAO,MAAM,oBAAoB,GAChC,UAAU,MAAM,EAAE,EAClB,WAAW,WAAW,GAAG,aAAa,KACpC;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAiBpC,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,GAAG,IAAI,KAAG,MAAM,GAAG,SAWnE,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,EAAE,UAAU,OAAO,KAAG,OAKpE,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAS1D,CAAA"}
+{"version":3,"file":"httpUtils.d.ts","sourceRoot":"","sources":["../../src/http/httpUtils.ts"],"names":[],"mappings":"AACA,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAe,KAAK,cAAc,EAAsB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAExG,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,EAAE,eAAY,KAAG,IAK/F,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,IAAI,CAAC,cAAc,EAAE,QAAQ,MAAM,EAAE,MAAM,cAAc,GAAG,SAAS,EAAE,SAAS,MAAM,KAAG,IAE7H,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,KAAK,IAAI,CAAC,cAAc,EAAE,SAAS,MAAM,KAAG,IAE/E,CAAA;AAED,eAAO,MAAM,uBAAuB,GAAI,KAAK,IAAI,CAAC,cAAc,KAAG,IAElE,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAI,KAAK,IAAI,CAAC,cAAc,EAAE,SAAS,MAAM,KAAG,IAE9E,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAI,KAAK,IAAI,CAAC,cAAc,KAAG,IAE7D,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,KAAK,IAAI,CAAC,cAAc,KAAG,IAEjE,CAAA;AAED,eAAO,MAAM,YAAY,GAAI,KAAK,IAAI,CAAC,cAAc,EAAE,OAAO,OAAO,KAAG,IAEvE,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GAAU,KAAK,IAAI,CAAC,eAAe,EAAE,KAAK,IAAI,CAAC,cAAc,KAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAkC9G,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,GAAG,IAAI,EAAE,UAAU,MAAM,EAAE,MAAM,MAAM,EAAE,MAAM,MAAM,KAAG,MAOhG,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,GAAG,IAAI,EAAE,MAAM,MAAM,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,SAW1F,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,GAAG,IAAI,KAAG,MAAM,GAAG,SAWnE,CAAA;AAcD,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,GAAG,IAAI,KAAG,QAAQ,EAAE,GAAG,SAe/D,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,GAAG,IAAI,KAAG,WAAW,GAAG,aAAa,GAAG,IAUrF,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,OAAO,MAAM,EAAE,KAAG;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAW5F,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAI,UAAU,MAAM,EAAE,EAAE,WAAW,WAAW,GAAG,aAAa,KAAG;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAiBnI,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,GAAG,IAAI,KAAG,MAAM,GAAG,SAWnE,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,EAAE,UAAU,OAAO,KAAG,OAKpE,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAS1D,CAAA"}