@jobshimo/browser-link 0.22.0 → 0.23.1

package/dist/cdp/keymap.js

@@ -0,0 +1,205 @@
+/**
+ * Independent copy of `packages/extension/src/keymap.ts` — see
+ * `inpage/deep-query.ts`'s header comment for why this package duplicates
+ * rather than imports extension-side modules. Byte-identical logic;
+ * `cdp/drift.test.ts` asserts the `MODIFIER_BITS` mapping stays in lockstep
+ * with the sibling at `packages/extension/src/keymap.ts`.
+ *
+ * Keyboard key definitions for CDP `Input.dispatchKeyEvent`, driving
+ * `browser.press` over the cdp-direct transport (`./transport.ts`).
+ *
+ * Modeled after Puppeteer's `USKeyboardLayout` (US keyboard — the only
+ * layout CDP's `Input.dispatchKeyEvent` needs; Chrome maps
+ * `windowsVirtualKeyCode` + `code` to the OS's actual layout on its own),
+ * trimmed to what `browser.press` exposes: the named control/navigation
+ * keys plus any single printable character.
+ */
+/** The named control/navigation keys `browser.press` accepts, keyed by
+ * their canonical human name. Values are the standard Windows virtual-key
+ * codes (VK_RETURN, VK_ESCAPE, VK_TAB, …) — well-known constants, stable
+ * across every Chromium build. */
+const NAMED_KEYS = {
+    // Enter carries text '\r' (matching Puppeteer's USKeyboardLayout): the
+    // WHATWG implicit form submission algorithm runs as the default action
+    // of the KEYPRESS event, and the CDP sequence only produces a keypress
+    // through the `char` event — which `buildKeyEventSequence` emits only
+    // for text-bearing keys. Without this, pressing Enter in a form field
+    // would fire keydown/keyup but never submit the form.
+    Enter: { key: 'Enter', code: 'Enter', keyCode: 13, text: '\r' },
+    Escape: { key: 'Escape', code: 'Escape', keyCode: 27 },
+    Tab: { key: 'Tab', code: 'Tab', keyCode: 9 },
+    Backspace: { key: 'Backspace', code: 'Backspace', keyCode: 8 },
+    Delete: { key: 'Delete', code: 'Delete', keyCode: 46 },
+    ArrowUp: { key: 'ArrowUp', code: 'ArrowUp', keyCode: 38 },
+    ArrowDown: { key: 'ArrowDown', code: 'ArrowDown', keyCode: 40 },
+    ArrowLeft: { key: 'ArrowLeft', code: 'ArrowLeft', keyCode: 37 },
+    ArrowRight: { key: 'ArrowRight', code: 'ArrowRight', keyCode: 39 },
+    Home: { key: 'Home', code: 'Home', keyCode: 36 },
+    End: { key: 'End', code: 'End', keyCode: 35 },
+    PageUp: { key: 'PageUp', code: 'PageUp', keyCode: 33 },
+    PageDown: { key: 'PageDown', code: 'PageDown', keyCode: 34 },
+    Space: { key: ' ', code: 'Space', keyCode: 32, text: ' ' },
+};
+/** Lowercased lookup so NAME matching is case-insensitive ("arrowup",
+ * "ENTER", "Escape" all resolve to the same definition). Single printable
+ * characters are resolved separately and stay case-SENSITIVE — "a" and
+ * "A" are different keystrokes. A `Map` (not a plain `Record`) so a missing
+ * key types as `undefined` — a `Record<string, KeyDefinition>` index would
+ * type as always-`KeyDefinition` (never falsy, since objects are always
+ * truthy) without `noUncheckedIndexedAccess`, which would make the
+ * presence check in `resolveKey` dead code from TypeScript's point of view. */
+const NAMED_KEYS_LOWER = new Map(Object.entries(NAMED_KEYS).map(([name, def]) => [name.toLowerCase(), def]));
+/** Physical key (code + Windows virtual-key code) for each punctuation key
+ * on a US keyboard, keyed by the character it produces UNSHIFTED. Shared
+ * with the shifted variant of the same physical key below. Values are the
+ * standard VK_OEM_* constants. */
+const PUNCTUATION_PHYSICAL = [
+    ['-', 'Minus', 189],
+    ['=', 'Equal', 187],
+    ['[', 'BracketLeft', 219],
+    [']', 'BracketRight', 221],
+    ['\\', 'Backslash', 220],
+    [';', 'Semicolon', 186],
+    ["'", 'Quote', 222],
+    ['`', 'Backquote', 192],
+    [',', 'Comma', 188],
+    ['.', 'Period', 190],
+    ['/', 'Slash', 191],
+];
+/** Shifted glyph produced by the same physical punctuation key, US layout. */
+const SHIFTED_PUNCTUATION = {
+    '-': '_',
+    '=': '+',
+    '[': '{',
+    ']': '}',
+    '\\': '|',
+    ';': ':',
+    "'": '"',
+    '`': '~',
+    ',': '<',
+    '.': '>',
+    '/': '?',
+};
+/** Shifted digit-row symbols, US layout — the physical key is the digit
+ * itself (Shift+2 -> "@", Shift+1 -> "!", …). */
+const SHIFTED_DIGITS = {
+    '1': '!',
+    '2': '@',
+    '3': '#',
+    '4': '$',
+    '5': '%',
+    '6': '^',
+    '7': '&',
+    '8': '*',
+    '9': '(',
+    '0': ')',
+};
+function buildPrintableTable() {
+    const table = new Map();
+    // A literal ' ' resolves to the same definition as the named 'Space' key —
+    // without this alias it would fall through to the generic printable
+    // fallback and lose the physical Space code/keyCode.
+    table.set(' ', NAMED_KEYS.Space);
+    for (let i = 0; i < 26; i++) {
+        const lower = String.fromCharCode(97 + i);
+        const upper = String.fromCharCode(65 + i);
+        const code = `Key${upper}`;
+        const keyCode = upper.charCodeAt(0);
+        table.set(lower, { key: lower, code, keyCode, text: lower });
+        table.set(upper, { key: upper, code, keyCode, text: upper, needsShift: true });
+    }
+    for (let d = 0; d <= 9; d++) {
+        const ch = String(d);
+        const code = `Digit${ch}`;
+        const keyCode = 48 + d;
+        table.set(ch, { key: ch, code, keyCode, text: ch });
+        const shifted = SHIFTED_DIGITS[ch];
+        table.set(shifted, { key: shifted, code, keyCode, text: shifted, needsShift: true });
+    }
+    for (const [unshifted, code, keyCode] of PUNCTUATION_PHYSICAL) {
+        table.set(unshifted, { key: unshifted, code, keyCode, text: unshifted });
+        const shifted = SHIFTED_PUNCTUATION[unshifted];
+        table.set(shifted, { key: shifted, code, keyCode, text: shifted, needsShift: true });
+    }
+    return table;
+}
+const PRINTABLE_TABLE = buildPrintableTable();
+/**
+ * Resolve a human-provided `key` name (the `browser.press` `key` param)
+ * into CDP dispatch parameters. Accepts:
+ *  - a named control/navigation key, case-insensitive ("Enter", "arrowup"),
+ *  - a single printable character, case-SENSITIVE ("a" vs "A", "@").
+ *
+ * Returns `null` when the name is neither — the caller surfaces that as a
+ * validation error instead of silently no-op'ing on an unrecognized key.
+ */
+export function resolveKey(name) {
+    const named = NAMED_KEYS_LOWER.get(name.toLowerCase());
+    if (named)
+        return named;
+    if (name.length === 1) {
+        const printable = PRINTABLE_TABLE.get(name);
+        if (printable)
+            return printable;
+        // Any other single printable character (unicode letters, symbols not
+        // in the curated punctuation table): best-effort. `key`/`text` are
+        // always correct — they drive what actually gets inserted via the
+        // `char` event. `code`/`keyCode` degrade to a generic placeholder
+        // since there is no physical-key mapping for it on a US layout.
+        return { key: name, code: 'Unidentified', keyCode: name.charCodeAt(0), text: name };
+    }
+    return null;
+}
+/** CDP `Input.dispatchKeyEvent` modifiers bitmask. */
+export const MODIFIER_BITS = {
+    Alt: 1,
+    Control: 2,
+    Meta: 4,
+    Shift: 8,
+};
+/** Fold a `modifiers` array (as accepted by `browser.press`) into the CDP
+ * bitmask. Unknown entries are ignored defensively — the server-side
+ * dispatcher already validates the enum, this is a second line of
+ * defence for direct/test callers. */
+export function modifiersToBitmask(modifiers) {
+    if (!modifiers || modifiers.length === 0)
+        return 0;
+    let mask = 0;
+    for (const m of modifiers) {
+        const bit = MODIFIER_BITS[m];
+        if (bit)
+            mask |= bit;
+    }
+    return mask;
+}
+/**
+ * Build the CDP `Input.dispatchKeyEvent` sequence for one key press.
+ * Pure function so the exact event shapes are unit-testable.
+ *
+ * Shape: a text-bearing key (printable characters, Space, Enter) gets a
+ * `keyDown` (identity only, no `text` field — Chrome would insert text
+ * from a text-bearing keyDown AND from a following char event, doubling
+ * the input) followed by a separate `char` event carrying the text — the
+ * `char` event is what produces the KEYPRESS whose default action drives
+ * text insertion and, for Enter ('\r'), the WHATWG implicit form
+ * submission. A control key with no text (Escape, Tab, arrows, …) gets
+ * `rawKeyDown` with nothing to follow but `keyUp`, matching real hardware
+ * (those keys never fire keypress in Blink).
+ */
+export function buildKeyEventSequence(def, modifiers) {
+    const base = {
+        modifiers,
+        key: def.key,
+        code: def.code,
+        windowsVirtualKeyCode: def.keyCode,
+        nativeVirtualKeyCode: def.keyCode,
+    };
+    const hasText = typeof def.text === 'string' && def.text.length > 0;
+    const events = [{ ...base, type: hasText ? 'keyDown' : 'rawKeyDown' }];
+    if (hasText) {
+        events.push({ ...base, type: 'char', text: def.text, unmodifiedText: def.text });
+    }
+    events.push({ ...base, type: 'keyUp' });
+    return events;
+}
+//# sourceMappingURL=keymap.js.map

package/dist/cdp/keymap.js.map

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

package/dist/cdp/settle.d.ts

@@ -0,0 +1,38 @@
+/** Defaults and hard ceilings — same clamp-at-the-boundary philosophy as
+ * the drag durations in the extension's background.ts. Mirrored by the
+ * schema bounds in `tools/browser-definitions.ts`. */
+export declare const DEFAULT_SETTLE_MS = 150;
+export declare const MAX_SETTLE_MS = 2000;
+export declare const DEFAULT_SETTLE_TIMEOUT_MS = 2000;
+export declare const MAX_SETTLE_TIMEOUT_MS = 10000;
+export interface SettleParams {
+    settleMs: number;
+    settleTimeoutMs: number;
+}
+/**
+ * Resolve the settle params for an action call. Returns `null` when settle
+ * is disabled (`settle_ms: 0`, explicit) — the caller skips the extra
+ * `Runtime.evaluate` round trip entirely in that case rather than running a
+ * zero-length wait. `settle_ms` omitted defaults to `DEFAULT_SETTLE_MS`
+ * (settle stays ON by default); any other numeric value is clamped into
+ * (0, MAX_SETTLE_MS].
+ */
+export declare function resolveSettleParams(p: Record<string, unknown>): SettleParams | null;
+/** Evaluate-in-page function shape settleSafely needs. */
+export type EvaluateFn = (expression: string) => Promise<unknown>;
+/**
+ * Run the settle wait, GUARANTEED not to throw. Returns the in-page settle
+ * result, a degraded-but-truthful fallback when the evaluation failed, or
+ * `undefined` when settle is disabled for this call.
+ *
+ * The guarantee matters because the action itself already SUCCEEDED by the
+ * time settle runs: if the action triggered a full-document navigation, the
+ * execution context the settle expression runs in is destroyed mid-wait and
+ * `Runtime.evaluate` rejects. Letting that rejection escape would flip the
+ * whole tool response to ok:false for an action that landed — an agent
+ * would retry it and risk a duplicate submission. Instead the caller gets
+ * `{ settled: false, reason: 'context-destroyed' | 'settle-error' }` spliced
+ * onto an ok:true result: 'context-destroyed' is itself a strong signal the
+ * action navigated the page.
+ */
+export declare function settleSafely(evaluate: EvaluateFn, settle: SettleParams | null): Promise<Record<string, unknown> | undefined>;

package/dist/cdp/settle.js

@@ -0,0 +1,76 @@
+/**
+ * Independent copy of `packages/extension/src/settle.ts`, adapted only to
+ * import `buildSettleJs` from this package's own `./inpage/builders.js`
+ * copy instead of the extension's — see `inpage/deep-query.ts`'s header
+ * comment for why this package duplicates rather than imports these
+ * modules. Logic is otherwise byte-identical; `cdp/drift.test.ts` asserts
+ * the numeric settle invariants stay in lockstep with the sibling at
+ * `packages/extension/src/settle.ts`.
+ *
+ * Shared `settle_ms` / `settle_timeout_ms` handling for the click / type /
+ * press actions in `cdp/transport.ts`. Takes the evaluate function as a
+ * parameter so the failure handling is unit-testable without a real CDP
+ * connection.
+ */
+import { buildSettleJs } from './inpage/builders.js';
+/** Defaults and hard ceilings — same clamp-at-the-boundary philosophy as
+ * the drag durations in the extension's background.ts. Mirrored by the
+ * schema bounds in `tools/browser-definitions.ts`. */
+export const DEFAULT_SETTLE_MS = 150;
+export const MAX_SETTLE_MS = 2000;
+export const DEFAULT_SETTLE_TIMEOUT_MS = 2000;
+export const MAX_SETTLE_TIMEOUT_MS = 10_000;
+/**
+ * Resolve the settle params for an action call. Returns `null` when settle
+ * is disabled (`settle_ms: 0`, explicit) — the caller skips the extra
+ * `Runtime.evaluate` round trip entirely in that case rather than running a
+ * zero-length wait. `settle_ms` omitted defaults to `DEFAULT_SETTLE_MS`
+ * (settle stays ON by default); any other numeric value is clamped into
+ * (0, MAX_SETTLE_MS].
+ */
+export function resolveSettleParams(p) {
+    const rawSettleMs = p.settle_ms;
+    const settleMs = typeof rawSettleMs === 'number' && Number.isFinite(rawSettleMs) && rawSettleMs >= 0
+        ? Math.min(rawSettleMs, MAX_SETTLE_MS)
+        : DEFAULT_SETTLE_MS;
+    if (settleMs <= 0)
+        return null;
+    const rawTimeout = p.settle_timeout_ms;
+    const settleTimeoutMs = typeof rawTimeout === 'number' && Number.isFinite(rawTimeout) && rawTimeout >= 0
+        ? Math.min(rawTimeout, MAX_SETTLE_TIMEOUT_MS)
+        : DEFAULT_SETTLE_TIMEOUT_MS;
+    return { settleMs, settleTimeoutMs };
+}
+/**
+ * Run the settle wait, GUARANTEED not to throw. Returns the in-page settle
+ * result, a degraded-but-truthful fallback when the evaluation failed, or
+ * `undefined` when settle is disabled for this call.
+ *
+ * The guarantee matters because the action itself already SUCCEEDED by the
+ * time settle runs: if the action triggered a full-document navigation, the
+ * execution context the settle expression runs in is destroyed mid-wait and
+ * `Runtime.evaluate` rejects. Letting that rejection escape would flip the
+ * whole tool response to ok:false for an action that landed — an agent
+ * would retry it and risk a duplicate submission. Instead the caller gets
+ * `{ settled: false, reason: 'context-destroyed' | 'settle-error' }` spliced
+ * onto an ok:true result: 'context-destroyed' is itself a strong signal the
+ * action navigated the page.
+ */
+export async function settleSafely(evaluate, settle) {
+    if (!settle)
+        return undefined;
+    try {
+        const result = await evaluate(buildSettleJs({ settle_ms: settle.settleMs, settle_timeout_ms: settle.settleTimeoutMs }));
+        if (result && typeof result === 'object')
+            return result;
+        // Defensive: the expression always returns an object; anything else
+        // means the evaluation pipeline degraded (e.g. serialization loss).
+        return { settled: false, reason: 'settle-error' };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const contextDestroyed = /context/i.test(message) || /navigat/i.test(message);
+        return { settled: false, reason: contextDestroyed ? 'context-destroyed' : 'settle-error' };
+    }
+}
+//# sourceMappingURL=settle.js.map

package/dist/cdp/settle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle.js","sourceRoot":"","sources":["../../src/cdp/settle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD;;sDAEsD;AACtD,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AACrC,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;AAClC,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAC9C,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAO5C;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAA0B;IAC5D,MAAM,WAAW,GAAG,CAAC,CAAC,SAAS,CAAC;IAChC,MAAM,QAAQ,GACZ,OAAO,WAAW,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC;QACjF,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,aAAa,CAAC;QACtC,CAAC,CAAC,iBAAiB,CAAC;IACxB,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,UAAU,GAAG,CAAC,CAAC,iBAAiB,CAAC;IACvC,MAAM,eAAe,GACnB,OAAO,UAAU,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,UAAU,IAAI,CAAC;QAC9E,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,qBAAqB,CAAC;QAC7C,CAAC,CAAC,yBAAyB,CAAC;IAChC,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;AACvC,CAAC;AAKD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAoB,EACpB,MAA2B;IAE3B,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAC3B,aAAa,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,QAAQ,EAAE,iBAAiB,EAAE,MAAM,CAAC,eAAe,EAAE,CAAC,CACzF,CAAC;QACF,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,MAAiC,CAAC;QACnF,oEAAoE;QACpE,oEAAoE;QACpE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IACpD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,gBAAgB,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9E,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC;IAC7F,CAAC;AACH,CAAC"}

package/dist/cdp/support.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Declarative v1 support table for browser-link's cdp-direct transport —
+ * the SINGLE source of truth `tools/browser-dispatch.ts`'s routing layer
+ * reads to decide whether a tool may address a `cdp:` tab, instead of
+ * scattered per-tool `if` checks. Kept in its own zero-dependency module so
+ * the dispatcher can import just the table without pulling in the whole
+ * transport (CDP client, WebSocket connections, in-page builders, …).
+ *
+ * Keyed by the WIRE-LEVEL tool name (what `callBrowserTool`/`callCdpTool`
+ * receive — `'click'`, not `'browser.click'`).
+ *
+ * `list_tabs`, `claim_tab`, `release_tab`, `my_tabs`, `events`, `reset` are
+ * dispatcher-only (they never reach a per-tab transport) and deliberately
+ * absent — see `tools/browser-dispatch.ts` for how each is handled.
+ *
+ * Kept out of scope for v1 (see the README's cdp-direct tool-support table
+ * and the CHANGELOG's Internal section for the future-work list): `drag`,
+ * `console`, `network`, `network_body`, `canvas_screenshot`,
+ * `dialog_respond`, `set_permission`, `wait_for_tab`.
+ */
+export declare const CDP_TOOL_SUPPORT: ReadonlyMap<string, boolean>;
+export declare function isCdpToolSupported(tool: string): boolean;
+/** Error a caller gets for a tool that is valid in general but explicitly
+ * not implemented over cdp-direct in v1 — names the limitation and points
+ * at the fallback transport. */
+export declare function cdpUnsupportedToolError(tool: string): Error;

package/dist/cdp/support.js

@@ -0,0 +1,58 @@
+/**
+ * Declarative v1 support table for browser-link's cdp-direct transport —
+ * the SINGLE source of truth `tools/browser-dispatch.ts`'s routing layer
+ * reads to decide whether a tool may address a `cdp:` tab, instead of
+ * scattered per-tool `if` checks. Kept in its own zero-dependency module so
+ * the dispatcher can import just the table without pulling in the whole
+ * transport (CDP client, WebSocket connections, in-page builders, …).
+ *
+ * Keyed by the WIRE-LEVEL tool name (what `callBrowserTool`/`callCdpTool`
+ * receive — `'click'`, not `'browser.click'`).
+ *
+ * `list_tabs`, `claim_tab`, `release_tab`, `my_tabs`, `events`, `reset` are
+ * dispatcher-only (they never reach a per-tab transport) and deliberately
+ * absent — see `tools/browser-dispatch.ts` for how each is handled.
+ *
+ * Kept out of scope for v1 (see the README's cdp-direct tool-support table
+ * and the CHANGELOG's Internal section for the future-work list): `drag`,
+ * `console`, `network`, `network_body`, `canvas_screenshot`,
+ * `dialog_respond`, `set_permission`, `wait_for_tab`.
+ */
+// A real Map (not a plain object/Record) so a tool name absent from the
+// table types as genuinely `undefined` at `.get()` — the same reason
+// keymap.ts's NAMED_KEYS_LOWER is a Map, not a Record: this tsconfig leaves
+// `noUncheckedIndexedAccess` off, so a `Record<string, boolean>`'s index
+// access would type as always-`boolean` (never `undefined`), which is
+// wrong for an unknown tool name and fights the linter either way you try
+// to guard it.
+export const CDP_TOOL_SUPPORT = new Map([
+    ['ping', true],
+    ['navigate', true],
+    ['snapshot', true],
+    ['find', true],
+    ['state', true],
+    ['click', true],
+    ['type', true],
+    ['press', true],
+    ['evaluate', true],
+    ['wait_for', true],
+    ['flow', true],
+    ['drag', false],
+    ['console', false],
+    ['network', false],
+    ['network_body', false],
+    ['canvas_screenshot', false],
+    ['dialog_respond', false],
+    ['set_permission', false],
+    ['wait_for_tab', false],
+]);
+export function isCdpToolSupported(tool) {
+    return CDP_TOOL_SUPPORT.get(tool) === true;
+}
+/** Error a caller gets for a tool that is valid in general but explicitly
+ * not implemented over cdp-direct in v1 — names the limitation and points
+ * at the fallback transport. */
+export function cdpUnsupportedToolError(tool) {
+    return new Error(`browser.${tool} is not supported over cdp-direct in v1. Use a tab connected through the Chrome extension instead.`);
+}
+//# sourceMappingURL=support.js.map

package/dist/cdp/support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"support.js","sourceRoot":"","sources":["../../src/cdp/support.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wEAAwE;AACxE,qEAAqE;AACrE,4EAA4E;AAC5E,yEAAyE;AACzE,sEAAsE;AACtE,0EAA0E;AAC1E,eAAe;AACf,MAAM,CAAC,MAAM,gBAAgB,GAAiC,IAAI,GAAG,CAAC;IACpE,CAAC,MAAM,EAAE,IAAI,CAAC;IACd,CAAC,UAAU,EAAE,IAAI,CAAC;IAClB,CAAC,UAAU,EAAE,IAAI,CAAC;IAClB,CAAC,MAAM,EAAE,IAAI,CAAC;IACd,CAAC,OAAO,EAAE,IAAI,CAAC;IACf,CAAC,OAAO,EAAE,IAAI,CAAC;IACf,CAAC,MAAM,EAAE,IAAI,CAAC;IACd,CAAC,OAAO,EAAE,IAAI,CAAC;IACf,CAAC,UAAU,EAAE,IAAI,CAAC;IAClB,CAAC,UAAU,EAAE,IAAI,CAAC;IAClB,CAAC,MAAM,EAAE,IAAI,CAAC;IACd,CAAC,MAAM,EAAE,KAAK,CAAC;IACf,CAAC,SAAS,EAAE,KAAK,CAAC;IAClB,CAAC,SAAS,EAAE,KAAK,CAAC;IAClB,CAAC,cAAc,EAAE,KAAK,CAAC;IACvB,CAAC,mBAAmB,EAAE,KAAK,CAAC;IAC5B,CAAC,gBAAgB,EAAE,KAAK,CAAC;IACzB,CAAC,gBAAgB,EAAE,KAAK,CAAC;IACzB,CAAC,cAAc,EAAE,KAAK,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;AAC7C,CAAC;AAED;;gCAEgC;AAChC,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO,IAAI,KAAK,CACd,WAAW,IAAI,oGAAoG,CACpH,CAAC;AACJ,CAAC"}

package/dist/cdp/targets.d.ts

@@ -0,0 +1,54 @@
+export interface CdpTargetTab {
+    tab_id: string;
+    url: string;
+    title: string;
+    transport: 'cdp';
+}
+/**
+ * Verify the endpoint at `port` is really a Chrome/Chromium-family
+ * DevTools endpoint before trusting anything else it returns — a random
+ * local service that happens to be listening on the configured port must
+ * never be treated as a browser target list. Mirrors the WS bridge's own
+ * "verify the peer before trusting it" posture (`auth/allowlist.ts`), just
+ * over HTTP instead of a kernel-level PID lookup.
+ */
+export declare function isChromeDevtoolsEndpoint(port: number): Promise<boolean>;
+/**
+ * The core "is this a real, drivable page target" predicate, shared by
+ * discovery (`isRealPageTarget` below, feeding `list_tabs`) AND by
+ * `cdp/transport.ts`'s connect-time re-validation. Keeping ONE
+ * implementation matters: discovery filters devtools/extension targets for
+ * DISPLAY, but the transport connects by a caller-supplied `cdp:<targetId>`
+ * that need not have come from a `list_tabs` this process produced — so the
+ * transport must re-run the same check against `Target.getTargetInfo` on
+ * connect, never trusting the id's provenance. A drift between the two
+ * checks would let a devtools/extension surface be driven through the
+ * connect path while hidden from the list.
+ */
+export declare function isDrivablePageTarget(type: string | undefined, url: string | undefined): boolean;
+/**
+ * Discover cdp-direct page targets for `browser.list_tabs`. Gated on
+ * `checkCdpDirectGate()` FIRST — when cdp-direct is disabled or has no live
+ * grant, this returns `[]` immediately without ever touching the network,
+ * exactly like an extension-only install that has never heard of
+ * cdp-direct. Every other failure (Chrome not running on the configured
+ * port, a non-Chrome service, a network hiccup) also degrades to `[]` —
+ * list_tabs must never fail or slow down because of cdp-direct trouble.
+ */
+export declare function listCdpTargets(): Promise<CdpTargetTab[]>;
+/** Prefix every cdp-direct tab_id carries, so the rest of the server can
+ * route by a single string check. */
+export declare const CDP_TAB_ID_PREFIX = "cdp:";
+export declare function isCdpTabId(tabId: string): boolean;
+/** Recover the raw CDP target id from a `cdp:<targetId>` tab_id, or `null`
+ * when `tabId` is not a cdp-direct id, or is one with an empty target id
+ * (`"cdp:"`, malformed). */
+export declare function cdpTargetIdFromTabId(tabId: string): string | null;
+/** Chrome's standard per-target DevTools WebSocket URL shape — the exact
+ * same URL `/json/list`'s `webSocketDebuggerUrl` field carries, derived
+ * directly from the port + target id instead of a second HTTP round trip.
+ * The port is re-sanitized here too (defense in depth) so this exported
+ * helper is safe regardless of caller; `targetId` sits in the URL PATH,
+ * after the host, so it cannot alter the host. `transport.ts` additionally
+ * asserts the built URL's host is loopback before connecting. */
+export declare function buildTargetWsUrl(port: number, targetId: string): string;

package/dist/cdp/targets.js

@@ -0,0 +1,176 @@
+import { loadConfig, sanitizeCdpPort } from '../config.js';
+import { checkCdpDirectGate } from './gate.js';
+/** The only host cdp-direct ever talks to. Never configurable. */
+const LOOPBACK_HOST = '127.0.0.1';
+/**
+ * Build a loopback discovery URL for `rawPort` + `path`, or `null` when the
+ * result would not be a loopback HTTP URL. Two barriers, both in the data
+ * flow before any `fetch`: (1) `sanitizeCdpPort` reduces the untrusted port
+ * to a validated integer, so a config.json string like `"9222@attacker.com"`
+ * can never survive into the URL; (2) the constructed URL's host is asserted
+ * `=== 127.0.0.1` — defense in depth, so even a port value that somehow
+ * slipped validation cannot produce an off-host request. A non-loopback (or
+ * unparseable) result is treated as "no endpoint" by the callers. */
+function loopbackHttpUrl(rawPort, path) {
+    const port = sanitizeCdpPort(rawPort);
+    let url;
+    try {
+        url = new URL(`http://${LOOPBACK_HOST}:${port}${path}`);
+    }
+    catch {
+        return null;
+    }
+    if (url.hostname !== LOOPBACK_HOST)
+        return null;
+    return url.href;
+}
+/** Short timeout on every discovery HTTP call — this runs on the hot
+ * `browser.list_tabs` path, so a Chrome that is not actually listening on
+ * the configured port must fail fast, not stall the tool call. */
+const DISCOVERY_TIMEOUT_MS = 1_000;
+function withTimeout(ms) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, ms);
+    return {
+        signal: controller.signal,
+        cancel: () => {
+            clearTimeout(timer);
+        },
+    };
+}
+/**
+ * Verify the endpoint at `port` is really a Chrome/Chromium-family
+ * DevTools endpoint before trusting anything else it returns — a random
+ * local service that happens to be listening on the configured port must
+ * never be treated as a browser target list. Mirrors the WS bridge's own
+ * "verify the peer before trusting it" posture (`auth/allowlist.ts`), just
+ * over HTTP instead of a kernel-level PID lookup.
+ */
+export async function isChromeDevtoolsEndpoint(port) {
+    const url = loopbackHttpUrl(port, '/json/version');
+    if (!url)
+        return false;
+    const { signal, cancel } = withTimeout(DISCOVERY_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, { signal });
+        if (!res.ok)
+            return false;
+        const info = (await res.json());
+        // "Chrome/123.0.0.0", "HeadlessChrome/...", "Edg/122...", etc. — every
+        // Chromium-family browser's Browser string contains "Chrome".
+        return typeof info.Browser === 'string' && info.Browser.includes('Chrome');
+    }
+    catch {
+        return false;
+    }
+    finally {
+        cancel();
+    }
+}
+/**
+ * The core "is this a real, drivable page target" predicate, shared by
+ * discovery (`isRealPageTarget` below, feeding `list_tabs`) AND by
+ * `cdp/transport.ts`'s connect-time re-validation. Keeping ONE
+ * implementation matters: discovery filters devtools/extension targets for
+ * DISPLAY, but the transport connects by a caller-supplied `cdp:<targetId>`
+ * that need not have come from a `list_tabs` this process produced — so the
+ * transport must re-run the same check against `Target.getTargetInfo` on
+ * connect, never trusting the id's provenance. A drift between the two
+ * checks would let a devtools/extension surface be driven through the
+ * connect path while hidden from the list.
+ */
+export function isDrivablePageTarget(type, url) {
+    if (type !== 'page')
+        return false;
+    if (typeof url !== 'string')
+        return false;
+    if (url.startsWith('devtools://'))
+        return false;
+    if (url.startsWith('chrome-extension://'))
+        return false;
+    return true;
+}
+/** A "page" target that is not Chrome's own DevTools UI or an extension
+ * page. Agents have no legitimate reason to drive those, and they are not
+ * "a Chrome tab" in the sense the rest of browser-link means. A type
+ * predicate (not a plain boolean) so the `.filter()` call site below
+ * narrows `id`/`url` to `string` for the following `.map()` — the fields
+ * this function actually validated, not a blind cast. */
+function isRealPageTarget(t) {
+    if (typeof t.id !== 'string' || t.id.length === 0)
+        return false;
+    return isDrivablePageTarget(t.type, t.url);
+}
+async function fetchTargets(port) {
+    const url = loopbackHttpUrl(port, '/json/list');
+    if (!url)
+        return [];
+    const { signal, cancel } = withTimeout(DISCOVERY_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, { signal });
+        if (!res.ok)
+            return [];
+        const list = (await res.json());
+        return Array.isArray(list) ? list : [];
+    }
+    catch {
+        return [];
+    }
+    finally {
+        cancel();
+    }
+}
+/**
+ * Discover cdp-direct page targets for `browser.list_tabs`. Gated on
+ * `checkCdpDirectGate()` FIRST — when cdp-direct is disabled or has no live
+ * grant, this returns `[]` immediately without ever touching the network,
+ * exactly like an extension-only install that has never heard of
+ * cdp-direct. Every other failure (Chrome not running on the configured
+ * port, a non-Chrome service, a network hiccup) also degrades to `[]` —
+ * list_tabs must never fail or slow down because of cdp-direct trouble.
+ */
+export async function listCdpTargets() {
+    const gate = checkCdpDirectGate();
+    if (!gate.ok)
+        return [];
+    const cfg = loadConfig();
+    const port = sanitizeCdpPort(cfg.cdpDirectPort);
+    const isChrome = await isChromeDevtoolsEndpoint(port);
+    if (!isChrome)
+        return [];
+    const targets = await fetchTargets(port);
+    return targets.filter(isRealPageTarget).map((t) => ({
+        tab_id: `cdp:${t.id}`,
+        url: t.url,
+        title: t.title ?? '',
+        transport: 'cdp',
+    }));
+}
+/** Prefix every cdp-direct tab_id carries, so the rest of the server can
+ * route by a single string check. */
+export const CDP_TAB_ID_PREFIX = 'cdp:';
+export function isCdpTabId(tabId) {
+    return tabId.startsWith(CDP_TAB_ID_PREFIX);
+}
+/** Recover the raw CDP target id from a `cdp:<targetId>` tab_id, or `null`
+ * when `tabId` is not a cdp-direct id, or is one with an empty target id
+ * (`"cdp:"`, malformed). */
+export function cdpTargetIdFromTabId(tabId) {
+    if (!isCdpTabId(tabId))
+        return null;
+    const id = tabId.slice(CDP_TAB_ID_PREFIX.length);
+    return id.length > 0 ? id : null;
+}
+/** Chrome's standard per-target DevTools WebSocket URL shape — the exact
+ * same URL `/json/list`'s `webSocketDebuggerUrl` field carries, derived
+ * directly from the port + target id instead of a second HTTP round trip.
+ * The port is re-sanitized here too (defense in depth) so this exported
+ * helper is safe regardless of caller; `targetId` sits in the URL PATH,
+ * after the host, so it cannot alter the host. `transport.ts` additionally
+ * asserts the built URL's host is loopback before connecting. */
+export function buildTargetWsUrl(port, targetId) {
+    return `ws://${LOOPBACK_HOST}:${sanitizeCdpPort(port)}/devtools/page/${targetId}`;
+}
+//# sourceMappingURL=targets.js.map