@jobshimo/browser-link 0.15.0 → 0.16.0

package/dist/extension/keymap.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Keyboard key definitions for CDP `Input.dispatchKeyEvent`, driving
+ * `browser.press` (trusted keyboard input — see `background.ts`'s
+ * `case 'press'`).
+ *
+ * Deliberately NOT an `inpage/*.ts` module: this runs in the extension's
+ * own service-worker context and only produces CDP command parameters —
+ * no page JS execution involved, nothing to inject via `Runtime.evaluate`.
+ *
+ * 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.
+ */
+export interface KeyDefinition {
+    /** DOM `KeyboardEvent.key` value. */
+    key: string;
+    /** DOM `KeyboardEvent.code` value — physical key identity. */
+    code: string;
+    /** CDP `windowsVirtualKeyCode` (mirrored into `nativeVirtualKeyCode`).
+     * Chrome derives the platform-native key from this plus `code` — the
+     * same numeric value works on every OS. */
+    keyCode: number;
+    /** Text CDP should insert via a `char` event. Only set for keys that
+     * produce visible input (printable characters, Space). Control keys
+     * (Enter, Escape, Tab, arrows, …) omit it — they dispatch keyDown/keyUp
+     * only, no `char` event, matching real hardware. */
+    text?: string;
+    /** True when producing this exact character requires the Shift modifier
+     * on a US layout (e.g. "@" is Shift+2, "_" is Shift+-). The caller ORs
+     * this into the dispatched modifiers bitmask so `event.shiftKey`
+     * reports correctly even when the caller only asked for the character,
+     * not the physical chord. */
+    needsShift?: boolean;
+}
+/**
+ * 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 declare function resolveKey(name: string): KeyDefinition | null;
+/** CDP `Input.dispatchKeyEvent` modifiers bitmask. */
+export declare const MODIFIER_BITS: Readonly<Record<string, number>>;
+/** 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 declare function modifiersToBitmask(modifiers: readonly string[] | undefined): number;
+/** One CDP `Input.dispatchKeyEvent` command payload. A type alias (not an
+ * interface) so it carries an implicit index signature and is directly
+ * assignable to the `Record<string, unknown>` the cdp() helper takes. */
+export type CdpKeyEvent = {
+    type: 'keyDown' | 'rawKeyDown' | 'char' | 'keyUp';
+    modifiers: number;
+    key: string;
+    code: string;
+    windowsVirtualKeyCode: number;
+    nativeVirtualKeyCode: number;
+    text?: string;
+    unmodifiedText?: string;
+};
+/**
+ * Build the CDP `Input.dispatchKeyEvent` sequence for one key press.
+ * Pure function (no chrome.* access) so the exact event shapes are
+ * unit-testable; background.ts dispatches each entry in order.
+ *
+ * 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 declare function buildKeyEventSequence(def: KeyDefinition, modifiers: number): CdpKeyEvent[];

package/dist/extension/keymap.js

@@ -0,0 +1,205 @@
+/**
+ * Keyboard key definitions for CDP `Input.dispatchKeyEvent`, driving
+ * `browser.press` (trusted keyboard input — see `background.ts`'s
+ * `case 'press'`).
+ *
+ * Deliberately NOT an `inpage/*.ts` module: this runs in the extension's
+ * own service-worker context and only produces CDP command parameters —
+ * no page JS execution involved, nothing to inject via `Runtime.evaluate`.
+ *
+ * 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 (no chrome.* access) so the exact event shapes are
+ * unit-testable; background.ts dispatches each entry in order.
+ *
+ * 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/extension/keymap.js.map

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

package/dist/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "browser-link",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Bridge between Chrome and an MCP client (Claude Code, OpenCode, GitHub Copilot CLI, …). Per-tab manual activation.",
   "permissions": [
     "debugger",

package/dist/extension/settle.d.ts

@@ -0,0 +1,39 @@
+/** Defaults and hard ceilings — same clamp-at-the-boundary philosophy as
+ * the drag durations in background.ts. Mirrored by the schema bounds in
+ * the server's 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 — background.ts
+ * passes `(expr) => evaluateInTab(tabId, expr)`. */
+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/extension/settle.js

@@ -0,0 +1,69 @@
+/**
+ * Shared `settle_ms` / `settle_timeout_ms` handling for the click / type /
+ * press actions in background.ts. Lives outside `inpage/` (this runs in the
+ * extension's service-worker context) and takes the evaluate function as a
+ * parameter so the failure handling is unit-testable without chrome.* —
+ * background.ts passes a closure over `evaluateInTab`.
+ */
+import { buildSettleJs } from './inpage/builders.js';
+/** Defaults and hard ceilings — same clamp-at-the-boundary philosophy as
+ * the drag durations in background.ts. Mirrored by the schema bounds in
+ * the server's 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/extension/settle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle.js","sourceRoot":"","sources":["../src/settle.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD;;0CAE0C;AAC1C,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;AAMD;;;;;;;;;;;;;;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/permissions.js

@@ -96,6 +96,12 @@ export const TOOL_CATALOGUE = [
         category: 'action',
         summary: 'Type text into an input',
     },
+    {
+        name: 'browser.press',
+        family: 'bridge',
+        category: 'action',
+        summary: 'Press a key (with modifiers) using trusted CDP input',
+    },
     {
         name: 'browser.drag',
         family: 'bridge',

package/dist/permissions.js.map

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

package/dist/tools/browser-definitions.js

@@ -9,6 +9,25 @@
  * structured shape keeps the "when to use" copy beside the tool that owns
  * it instead of drifting in a single monolithic string.
  */
+/**
+ * Shared `settle_ms` / `settle_timeout_ms` schema properties for
+ * click / type / press. Identical wording and semantics across all three —
+ * defined once so the descriptions cannot drift between tools.
+ */
+const SETTLE_SCHEMA_PROPERTIES = {
+    settle_ms: {
+        type: 'number',
+        minimum: 0,
+        maximum: 2000,
+        description: 'After dispatching the action, wait until the page goes quiet — no DOM mutations for this many consecutive ms — before returning. Folds the wait_for + snapshot round trip most flows need after an action into the action call itself. Default 150, hard ceiling 2000. Pass 0 to disable and return immediately (pre-v0.16.0 behavior). Blind spot to keep in mind: the observer installs right AFTER the action dispatches, so mutations that complete in that gap are invisible — mutation_count:0 with settled:true does NOT prove the action had no effect — and an async reaction that only starts after the quiet window is likewise missed. For a specific expected condition, browser.wait_for remains the right tool.',
+    },
+    settle_timeout_ms: {
+        type: 'number',
+        minimum: 0,
+        maximum: 10000,
+        description: 'Overall cap on the settle wait in ms, in case the page never goes fully quiet (polling animations, live tickers, spinners). Default 2000, hard ceiling 10000. Ignored when settle_ms is 0.',
+    },
+};
 export const BROWSER_TOOL_DEFINITIONS = [
     {
         name: 'browser.list_tabs',
@@ -503,7 +522,7 @@ export const BROWSER_TOOL_DEFINITIONS = [
     },
     {
         name: 'browser.click',
-        description: 'Click an element by CSS selector in the connected tab. The selector usually comes from browser.snapshot or browser.find. The lookup pierces open Shadow DOM roots and same-origin iframes (nested arbitrarily), so a selector for a web-component internal or an in-page iframe works without extra steps. Before dispatching the click, the element is hit-tested at its own click point (starting from its own shadow root / iframe document) — if a different element covers that point, the call returns ok:false with a description of the blocker instead of clicking the wrong thing blindly. Pass `force:true` to skip that guard.',
+        description: 'Click an element by CSS selector in the connected tab. The selector usually comes from browser.snapshot or browser.find. The lookup pierces open Shadow DOM roots and same-origin iframes (nested arbitrarily), so a selector for a web-component internal or an in-page iframe works without extra steps. Before dispatching the click, the element is hit-tested at its own click point (starting from its own shadow root / iframe document) — if a different element covers that point, the call returns ok:false with a description of the blocker instead of clicking the wrong thing blindly. Pass `force:true` to skip that guard. Optionally waits for the page to settle after the click — see `settle_ms`.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -514,6 +533,7 @@ export const BROWSER_TOOL_DEFINITIONS = [
                     default: false,
                     description: 'Skip the occlusion guard and dispatch the click even if another element currently covers the click point. Escape hatch for cases where the "covering" element is intentional (e.g. a transparent hit-target layer) or the guard produces a false positive. Default false.',
                 },
+                ...SETTLE_SCHEMA_PROPERTIES,
             },
             required: ['tab_id', 'selector'],
             additionalProperties: false,
@@ -528,12 +548,13 @@ export const BROWSER_TOOL_DEFINITIONS = [
                 'Auto-claims the tab on first use in multi-agent mode.',
                 'ok:false with an "Element covered by …" error means something else is on top of the target at click time (a modal backdrop, a loading overlay, a dropdown). Click or dismiss the covering element first, or re-snapshot — do not blindly retry with force:true.',
                 'CLOSED shadow roots (attachShadow({mode:"closed"})) are unreachable — there is no CDP-level workaround. Cross-origin iframes are also unreachable (same-origin policy).',
+                'The result carries a compact `settle` object (`{ settled, duration_ms, mutation_count, url_changed?, focus_moved?, reason? }`) unless `settle_ms:0`. `settled:false` means the page never went quiet within `settle_timeout_ms` — not necessarily an error, some pages never stop mutating (tickers, spinners). When the settle wait itself could not run to completion, `settled:false` comes with `reason`: "context-destroyed" (the action navigated the page, destroying the observer\'s execution context — the action still succeeded, and this is itself a strong navigation signal) or "settle-error" (any other settle-side failure). With settle on, a separate browser.wait_for right after a click is usually unnecessary.',
             ],
         },
     },
     {
         name: 'browser.type',
-        description: 'Focus an input by CSS selector and type text into it. If clear=true, clears the current value first. The lookup pierces open Shadow DOM roots and same-origin iframes, same as browser.click.',
+        description: 'Focus an input by CSS selector and type text into it. If clear=true, clears the current value first. The lookup pierces open Shadow DOM roots and same-origin iframes, same as browser.click. Optionally waits for the page to settle after typing — see `settle_ms`.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -541,6 +562,7 @@ export const BROWSER_TOOL_DEFINITIONS = [
                 selector: { type: 'string' },
                 text: { type: 'string' },
                 clear: { type: 'boolean', default: false },
+                ...SETTLE_SCHEMA_PROPERTIES,
             },
             required: ['tab_id', 'selector', 'text'],
             additionalProperties: false,
@@ -553,7 +575,51 @@ export const BROWSER_TOOL_DEFINITIONS = [
             gotchas: [
                 'Pass clear:true when you need to replace the current value instead of appending to it.',
                 'CLOSED shadow roots and cross-origin iframes are unreachable, same as browser.click.',
+                'For Enter/Tab/Escape/arrow keys after typing (submitting a form, confirming an autocomplete suggestion), use browser.press — dispatchEvent-based synthetic KeyboardEvent via browser.evaluate is NOT trusted input and many rich editors and autocompletes ignore it.',
+                'The result carries a compact `settle` object (same shape as browser.click) unless `settle_ms:0`.',
+            ],
+        },
+    },
+    {
+        name: 'browser.press',
+        description: 'Press a single key, optionally with modifiers, using a TRUSTED CDP `Input.dispatchKeyEvent` sequence (`isTrusted: true`) — not a synthetic `KeyboardEvent` dispatched via `browser.evaluate`, which many rich text editors, autocompletes, and non-DOM runtimes (Qt-WASM, WebGL — see browser.canvas_screenshot) silently ignore. `key` accepts a human name (`Enter`, `Escape`, `Tab`, `Backspace`, `Delete`, `ArrowUp`/`ArrowDown`/`ArrowLeft`/`ArrowRight`, `Home`, `End`, `PageUp`, `PageDown`, `Space`), case-insensitive, or a single printable character, case-sensitive (`"a"` vs `"A"`, `"@"`). `modifiers` combines with the key for shortcuts (`Ctrl+A` = `{ key: "a", modifiers: ["Control"] }`). Pass `selector` to focus an element first (same deep Shadow DOM / iframe search as click/type/find); omit it to send the key to whatever currently has focus. Optionally waits for the page to settle after the key press — see `settle_ms`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tab_id: { type: 'string' },
+                key: {
+                    type: 'string',
+                    description: 'Human key name ("Enter", "Escape", "Tab", "Backspace", "Delete", "ArrowUp"/"ArrowDown"/"ArrowLeft"/"ArrowRight", "Home", "End", "PageUp", "PageDown", "Space" — case-insensitive) or a single printable character (case-sensitive, e.g. "a", "A", "@").',
+                },
+                modifiers: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['Alt', 'Control', 'Meta', 'Shift'] },
+                    description: 'Modifier keys held during the press. Combine for shortcuts, e.g. ["Control"] + key:"a" for Ctrl+A, or ["Meta"] + key:"s" for Cmd+S on macOS.',
+                },
+                selector: {
+                    type: 'string',
+                    description: 'Optional. Focus this element (resolved via the same deep Shadow DOM / iframe search as browser.click) before dispatching the key. Omit to send the key to the currently focused element.',
+                },
+                ...SETTLE_SCHEMA_PROPERTIES,
+            },
+            required: ['tab_id', 'key'],
+            additionalProperties: false,
+        },
+        doc: {
+            purpose: 'Dispatch one trusted keyboard key press (optionally with modifiers) — Enter/Escape/Tab/arrows/shortcuts/a single character.',
+            when_to_use: [
+                'Submitting a form or confirming an autocomplete suggestion with Enter, dismissing a dialog with Escape, moving focus with Tab, navigating a list/menu with arrow keys.',
+                'A keyboard shortcut the page listens for (Ctrl+A select-all, Cmd+S save, Ctrl+Z undo) — pass modifiers plus the base key.',
+                'A rich text editor, autocomplete widget, or non-DOM runtime (Qt-WASM, WebGL) that discards synthetic input dispatched via browser.evaluate and needs a REAL, isTrusted:true keystroke.',
+            ],
+            gotchas: [
+                'For typing normal text into an input, use browser.type instead — it goes through the native value setter and is far cheaper per character than one browser.press call per keystroke.',
+                'For anything not covered by the named keys or a single character, browser.evaluate is the escape hatch — but note it produces isTrusted:false events, which some pages ignore.',
+                'Named keys are case-insensitive ("arrowup" works); single printable characters are case-SENSITIVE. Shift IS auto-added for characters that require it on a US layout — uppercase letters, shifted punctuation like "@" or "{" — so to type an uppercase letter just pass key:"A". Do NOT pass key:"a" with modifiers:["Shift"] expecting an "A": that inserts a lowercase "a" with shiftKey reported as held, a combination no physical keyboard produces.',
+                'CLOSED shadow roots and cross-origin iframes are unreachable for the optional `selector`, same as browser.click.',
+                'The result carries a compact `settle` object (same shape as browser.click) unless `settle_ms:0`.',
             ],
+            example: 'browser.press({ tab_id: "tab_1", key: "Enter" })',
         },
     },
     {