@jackwener/opencli 1.7.10 → 1.7.12

package/dist/src/adapter-shadow.test.js

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { findShadowedUserAdapters, formatAdapterShadowIssue } from './adapter-shadow.js';
+describe('adapter shadow detection', () => {
+    it('reports user adapters that shadow packaged manifest commands', () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-adapter-shadow-'));
+        try {
+            const userClisDir = path.join(root, 'user-clis');
+            const builtinRoot = path.join(root, 'pkg');
+            const builtinClisDir = path.join(builtinRoot, 'clis');
+            fs.mkdirSync(path.join(userClisDir, 'instagram'), { recursive: true });
+            fs.mkdirSync(path.join(userClisDir, 'twitter'), { recursive: true });
+            fs.mkdirSync(path.join(builtinClisDir, 'instagram'), { recursive: true });
+            fs.mkdirSync(path.join(builtinClisDir, 'twitter'), { recursive: true });
+            fs.writeFileSync(path.join(userClisDir, 'instagram', 'saved.js'), '', 'utf-8');
+            fs.writeFileSync(path.join(userClisDir, 'instagram', 'utils.js'), '', 'utf-8');
+            fs.writeFileSync(path.join(userClisDir, 'twitter', 'search.js'), '', 'utf-8');
+            fs.writeFileSync(path.join(builtinClisDir, 'instagram', 'saved.js'), '', 'utf-8');
+            fs.writeFileSync(path.join(builtinClisDir, 'instagram', 'utils.js'), '', 'utf-8');
+            fs.writeFileSync(path.join(builtinClisDir, 'twitter', 'search.js'), '', 'utf-8');
+            fs.writeFileSync(path.join(builtinRoot, 'cli-manifest.json'), `${JSON.stringify([
+                { site: 'instagram', name: 'saved', sourceFile: 'instagram/saved.js' },
+            ])}\n`, 'utf-8');
+            expect(findShadowedUserAdapters({ userClisDir, builtinClisDir })).toEqual([
+                {
+                    name: 'instagram/saved',
+                    userPath: path.join(userClisDir, 'instagram', 'saved.js'),
+                    builtinPath: path.join(builtinClisDir, 'instagram', 'saved.js'),
+                },
+            ]);
+        }
+        finally {
+            fs.rmSync(root, { recursive: true, force: true });
+        }
+    });
+    it('formats a concise doctor issue', () => {
+        const issue = formatAdapterShadowIssue([
+            {
+                name: 'instagram/saved',
+                userPath: '/home/me/.opencli/clis/instagram/saved.js',
+                builtinPath: '/pkg/clis/instagram/saved.js',
+            },
+        ]);
+        expect(issue).toContain('instagram/saved');
+        expect(issue).toContain('opencli adapter reset <site>');
+    });
+});

package/dist/src/adapter-source.test.js

@@ -3,7 +3,7 @@ import { resolveAdapterSourcePath } from './adapter-source.js';
 function makeCmd(overrides = {}) {
     return {
         site: 'test-site',
-        name: 'test-cmd',
+        name: 'test-cmd', access: 'read',
         description: 'test',
         args: [],
         ...overrides,

package/dist/src/browser/analyze.test.js

@@ -20,8 +20,10 @@ function mkCmd(site, name, domain) {
     return {
         site,
         name,
+        access: 'read',
         description: '',
         domain,
+        browser: false,
         args: [],
     };
 }

package/dist/src/browser/base-page.d.ts

@@ -23,6 +23,7 @@ export declare abstract class BasePage implements IPage {
     protected _lastUrl: string | null;
     /** Cached previous snapshot hashes for incremental diff marking */
     private _prevSnapshotHashes;
+    private _cdpTargetMarkerSeq;
     abstract goto(url: string, options?: {
         waitUntil?: 'load' | 'none';
         settleMs?: number;
@@ -47,8 +48,20 @@ export declare abstract class BasePage implements IPage {
     abstract tabs(): Promise<unknown[]>;
     abstract selectTab(target: number | string): Promise<void>;
     click(ref: string, opts?: ResolveOptions): Promise<ResolveSuccess>;
-    /** Override in subclasses with CDP native click support */
-    protected tryNativeClick(_x: number, _y: number): Promise<boolean>;
+    /** Uses native CDP click support when the concrete page exposes it. */
+    protected tryNativeClick(x: number, y: number): Promise<boolean>;
+    /** Uses native CDP text insertion when the concrete page exposes it. */
+    protected tryNativeType(text: string): Promise<boolean>;
+    /** Uses native CDP key events when the concrete page exposes them. */
+    protected tryNativeKeyPress(key: string, modifiers: string[]): Promise<boolean>;
+    /**
+     * Run a DOM-domain CDP command against `window.__resolved`.
+     *
+     * CDP DOM.focus / DOM.scrollIntoViewIfNeeded need a nodeId, while our
+     * resolver stores the live Element in page JS. Bridge the two worlds with a
+     * short-lived marker attribute, then query it through CDP.
+     */
+    protected tryCdpOnResolvedElement(method: 'DOM.focus' | 'DOM.scrollIntoViewIfNeeded'): Promise<boolean>;
     typeText(ref: string, text: string, opts?: ResolveOptions): Promise<ResolveSuccess>;
     pressKey(key: string): Promise<void>;
     scrollTo(ref: string, opts?: ResolveOptions): Promise<unknown>;

package/dist/src/browser/base-page.js

@@ -10,7 +10,7 @@
  */
 import { generateSnapshotJs, getFormStateJs } from './dom-snapshot.js';
 import { pressKeyJs, waitForTextJs, waitForCaptureJs, waitForSelectorJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
-import { resolveTargetJs, clickResolvedJs, typeResolvedJs, scrollResolvedJs, } from './target-resolver.js';
+import { resolveTargetJs, clickResolvedJs, typeResolvedJs, prepareNativeTypeResolvedJs, scrollResolvedJs, } from './target-resolver.js';
 import { TargetError } from './target-errors.js';
 import { CliError } from '../errors.js';
 import { formatSnapshot } from '../snapshotFormatter.js';
@@ -36,10 +36,32 @@ function previewText(text) {
     const preview = (text ?? '').replace(/\s+/g, ' ').trim().slice(0, 300);
     return preview ? `Response preview: ${preview}` : undefined;
 }
+function parseKeyChord(rawKey) {
+    const parts = rawKey.split('+').map(part => part.trim()).filter(Boolean);
+    if (parts.length <= 1)
+        return { key: rawKey, modifiers: [] };
+    const modifiers = [];
+    for (const token of parts.slice(0, -1)) {
+        const normalized = token.toLowerCase();
+        if (normalized === 'ctrl' || normalized === 'control')
+            modifiers.push('Ctrl');
+        else if (normalized === 'cmd' || normalized === 'command' || normalized === 'meta')
+            modifiers.push('Meta');
+        else if (normalized === 'option' || normalized === 'alt')
+            modifiers.push('Alt');
+        else if (normalized === 'shift')
+            modifiers.push('Shift');
+        else
+            return { key: rawKey, modifiers: [] };
+    }
+    const key = parts.at(-1);
+    return key ? { key, modifiers } : { key: rawKey, modifiers: [] };
+}
 export class BasePage {
     _lastUrl = null;
     /** Cached previous snapshot hashes for incremental diff marking */
     _prevSnapshotHashes = null;
+    _cdpTargetMarkerSeq = 0;
     /**
      * Safely evaluate JS with pre-serialized arguments.
      * Each key in `args` becomes a `const` declaration with JSON-serialized value,
@@ -133,8 +155,9 @@ export class BasePage {
     async click(ref, opts = {}) {
         // Phase 1: Resolve target with fingerprint verification
         const resolved = await runResolve(this, ref, opts);
+        const nativeScrolled = await this.tryCdpOnResolvedElement('DOM.scrollIntoViewIfNeeded');
         // Phase 2: Execute click on resolved element
-        const result = await this.evaluate(clickResolvedJs());
+        const result = await this.evaluate(clickResolvedJs({ skipScroll: nativeScrolled }));
         if (typeof result === 'string' || result == null)
             return resolved;
         if (result.status === 'clicked')
@@ -147,21 +170,149 @@ export class BasePage {
         }
         throw new Error(`Click failed: ${result.error ?? 'JS click and CDP fallback both failed'}`);
     }
-    /** Override in subclasses with CDP native click support */
-    async tryNativeClick(_x, _y) {
-        return false;
+    /** Uses native CDP click support when the concrete page exposes it. */
+    async tryNativeClick(x, y) {
+        const nativeClick = this.nativeClick;
+        if (typeof nativeClick !== 'function')
+            return false;
+        try {
+            await nativeClick.call(this, x, y);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Uses native CDP text insertion when the concrete page exposes it. */
+    async tryNativeType(text) {
+        const nativeType = this.nativeType;
+        if (typeof nativeType === 'function') {
+            try {
+                await nativeType.call(this, text);
+                return true;
+            }
+            catch {
+                // Fall through to the older dedicated insertText primitive if present.
+            }
+        }
+        const insertText = this.insertText;
+        if (typeof insertText !== 'function')
+            return false;
+        try {
+            await insertText.call(this, text);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Uses native CDP key events when the concrete page exposes them. */
+    async tryNativeKeyPress(key, modifiers) {
+        const nativeKeyPress = this.nativeKeyPress;
+        if (typeof nativeKeyPress !== 'function')
+            return false;
+        try {
+            await nativeKeyPress.call(this, key, modifiers);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Run a DOM-domain CDP command against `window.__resolved`.
+     *
+     * CDP DOM.focus / DOM.scrollIntoViewIfNeeded need a nodeId, while our
+     * resolver stores the live Element in page JS. Bridge the two worlds with a
+     * short-lived marker attribute, then query it through CDP.
+     */
+    async tryCdpOnResolvedElement(method) {
+        const cdp = this.cdp;
+        if (typeof cdp !== 'function')
+            return false;
+        const markerAttr = 'data-opencli-cdp-target';
+        const markerValue = `${Date.now().toString(36)}-${++this._cdpTargetMarkerSeq}`;
+        const selector = `[${markerAttr}="${markerValue}"]`;
+        let marked = false;
+        try {
+            const marker = await this.evaluateWithArgs(`
+        (() => {
+          const el = window.__resolved;
+          if (!el || el.nodeType !== 1 || typeof el.setAttribute !== 'function') {
+            return { ok: false };
+          }
+          el.setAttribute(markerAttr, markerValue);
+          return { ok: true };
+        })()
+      `, { markerAttr, markerValue });
+            marked = marker?.ok === true;
+            if (!marked)
+                return false;
+            await cdp.call(this, 'DOM.enable', {}).catch(() => undefined);
+            const doc = await cdp.call(this, 'DOM.getDocument', {});
+            const rootNodeId = doc?.root?.nodeId;
+            if (typeof rootNodeId !== 'number')
+                return false;
+            const query = await cdp.call(this, 'DOM.querySelector', {
+                nodeId: rootNodeId,
+                selector,
+            });
+            const nodeId = query?.nodeId;
+            if (typeof nodeId !== 'number' || nodeId <= 0)
+                return false;
+            await cdp.call(this, method, { nodeId });
+            return true;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            if (marked) {
+                await this.evaluateWithArgs(`
+          (() => {
+            for (const el of document.querySelectorAll(selector)) {
+              el.removeAttribute(markerAttr);
+            }
+          })()
+        `, { selector, markerAttr }).catch(() => undefined);
+            }
+        }
     }
     async typeText(ref, text, opts = {}) {
         const resolved = await runResolve(this, ref, opts);
-        await this.evaluate(typeResolvedJs(text));
+        let typed = false;
+        let nativeScrolled = false;
+        let nativeFocused = false;
+        if (typeof this.nativeType === 'function' || typeof this.insertText === 'function') {
+            try {
+                nativeScrolled = await this.tryCdpOnResolvedElement('DOM.scrollIntoViewIfNeeded');
+                nativeFocused = await this.tryCdpOnResolvedElement('DOM.focus');
+                const preparation = await this.evaluate(prepareNativeTypeResolvedJs({
+                    skipScroll: nativeScrolled,
+                    skipFocus: nativeFocused,
+                }));
+                typed = preparation?.ok === true && await this.tryNativeType(text);
+            }
+            catch {
+                // Native input is a reliability upgrade, not the only path. Preserve
+                // the existing DOM setter fallback if preparation fails.
+            }
+        }
+        if (!typed) {
+            await this.evaluate(typeResolvedJs(text));
+        }
         return resolved;
     }
     async pressKey(key) {
-        await this.evaluate(pressKeyJs(key));
+        const parsed = parseKeyChord(key);
+        if (!await this.tryNativeKeyPress(parsed.key, parsed.modifiers)) {
+            await this.evaluate(pressKeyJs(parsed.key, parsed.modifiers));
+        }
     }
     async scrollTo(ref, opts = {}) {
         const resolved = await runResolve(this, ref, opts);
-        const result = (await this.evaluate(scrollResolvedJs()));
+        const nativeScrolled = await this.tryCdpOnResolvedElement('DOM.scrollIntoViewIfNeeded');
+        const result = (await this.evaluate(scrollResolvedJs({ skipScroll: nativeScrolled })));
         // Fold match_level into the scroll payload so the user-facing envelope
         // carries it the same way click / type do.
         if (result && typeof result === 'object') {

package/dist/src/browser/base-page.test.js

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { CliError } from '../errors.js';
 import { BasePage } from './base-page.js';
 class TestPage extends BasePage {
@@ -15,6 +15,31 @@ class TestPage extends BasePage {
     async tabs() { return []; }
     async selectTab() { }
 }
+class ActionPage extends BasePage {
+    results = [];
+    withArgsResults = [];
+    scripts = [];
+    withArgs = [];
+    nativeType;
+    insertText;
+    nativeKeyPress;
+    cdp;
+    async goto() { }
+    async evaluate(js) {
+        this.scripts.push(js);
+        return this.results.shift() ?? null;
+    }
+    async evaluateWithArgs(js, args) {
+        this.scripts.push(js);
+        this.withArgs.push(args);
+        return this.withArgsResults.shift() ?? null;
+    }
+    async getCookies() { return []; }
+    async screenshot() { return ''; }
+    async tabs() { return []; }
+    async selectTab() { }
+}
+const resolveOk = { ok: true, matches_n: 1, match_level: 'exact' };
 describe('BasePage.fetchJson', () => {
     it('passes a narrow browser-context JSON request and parses the response in Node', async () => {
         const page = new TestPage();
@@ -72,3 +97,80 @@ describe('BasePage.fetchJson', () => {
         });
     });
 });
+describe('BasePage native input routing', () => {
+    it('types rich-editor text via native Input.insertText when available', async () => {
+        const page = new ActionPage();
+        page.nativeType = vi.fn().mockResolvedValue(undefined);
+        page.results = [resolveOk, { ok: true, mode: 'contenteditable' }];
+        await expect(page.typeText('#editor', 'hello')).resolves.toEqual({ matches_n: 1, match_level: 'exact' });
+        expect(page.nativeType).toHaveBeenCalledWith('hello');
+        expect(page.scripts).toHaveLength(2);
+        expect(page.scripts[1]).toContain('nearestContentEditableHost');
+        expect(page.scripts.join('\n')).not.toContain("return 'typed'");
+    });
+    it('uses CDP DOM focus and scroll before native text insertion when available', async () => {
+        const page = new ActionPage();
+        page.nativeType = vi.fn().mockResolvedValue(undefined);
+        page.cdp = vi.fn()
+            .mockResolvedValueOnce({})
+            .mockResolvedValueOnce({ root: { nodeId: 1 } })
+            .mockResolvedValueOnce({ nodeId: 7 })
+            .mockResolvedValueOnce({})
+            .mockResolvedValueOnce({})
+            .mockResolvedValueOnce({ root: { nodeId: 1 } })
+            .mockResolvedValueOnce({ nodeId: 7 })
+            .mockResolvedValueOnce({});
+        page.results = [resolveOk, { ok: true, mode: 'input' }];
+        page.withArgsResults = [{ ok: true }, undefined, { ok: true }, undefined];
+        await page.typeText('#q', 'hello');
+        expect(page.cdp).toHaveBeenCalledWith('DOM.scrollIntoViewIfNeeded', { nodeId: 7 });
+        expect(page.cdp).toHaveBeenCalledWith('DOM.focus', { nodeId: 7 });
+        expect(page.nativeType).toHaveBeenCalledWith('hello');
+        expect(page.scripts.at(-1)).toContain('if (false) el.scrollIntoView');
+        expect(page.scripts.at(-1)).toContain('if (false) {');
+    });
+    it('keeps the DOM setter fallback when native text insertion is unavailable', async () => {
+        const page = new ActionPage();
+        page.results = [resolveOk, 'typed'];
+        await page.typeText('#q', 'hello');
+        expect(page.scripts).toHaveLength(2);
+        expect(page.scripts[1]).toContain('document.execCommand');
+        expect(page.scripts[1]).toContain("return 'typed'");
+    });
+    it('falls back to DOM typing if native text insertion fails', async () => {
+        const page = new ActionPage();
+        page.nativeType = vi.fn().mockRejectedValue(new Error('native failed'));
+        page.results = [resolveOk, { ok: true, mode: 'input' }, 'typed'];
+        await page.typeText('#q', 'hello');
+        expect(page.nativeType).toHaveBeenCalledWith('hello');
+        expect(page.scripts).toHaveLength(3);
+        expect(page.scripts[2]).toContain("return 'typed'");
+    });
+    it('uses CDP DOM scrollIntoViewIfNeeded before JS click when available', async () => {
+        const page = new ActionPage();
+        page.cdp = vi.fn()
+            .mockResolvedValueOnce({})
+            .mockResolvedValueOnce({ root: { nodeId: 1 } })
+            .mockResolvedValueOnce({ nodeId: 9 })
+            .mockResolvedValueOnce({});
+        page.results = [resolveOk, { status: 'clicked', x: 1, y: 2 }];
+        page.withArgsResults = [{ ok: true }, undefined];
+        await page.click('#save');
+        expect(page.cdp).toHaveBeenCalledWith('DOM.scrollIntoViewIfNeeded', { nodeId: 9 });
+        expect(page.scripts.at(-1)).toContain('if (false) el.scrollIntoView');
+    });
+    it('presses key chords through native CDP key events when available', async () => {
+        const page = new ActionPage();
+        page.nativeKeyPress = vi.fn().mockResolvedValue(undefined);
+        await page.pressKey('Control+a');
+        expect(page.nativeKeyPress).toHaveBeenCalledWith('a', ['Ctrl']);
+        expect(page.scripts).toHaveLength(0);
+    });
+    it('falls back to synthetic keyboard events with parsed modifiers', async () => {
+        const page = new ActionPage();
+        await page.pressKey('Meta+N');
+        expect(page.scripts).toHaveLength(1);
+        expect(page.scripts[0]).toContain('key: "N"');
+        expect(page.scripts[0]).toContain('metaKey: true');
+    });
+});

package/dist/src/browser/cdp.js

@@ -317,6 +317,60 @@ class CDPPage extends BasePage {
     async selectTab(_target) {
         // Not supported in direct CDP mode
     }
+    async cdp(method, params = {}) {
+        return this.bridge.send(method, params);
+    }
+    async handleJavaScriptDialog(accept, promptText) {
+        await this.cdp('Page.handleJavaScriptDialog', {
+            accept,
+            ...(promptText !== undefined && { promptText }),
+        });
+    }
+    async nativeClick(x, y) {
+        await this.cdp('Input.dispatchMouseEvent', {
+            type: 'mousePressed',
+            x,
+            y,
+            button: 'left',
+            clickCount: 1,
+        });
+        await this.cdp('Input.dispatchMouseEvent', {
+            type: 'mouseReleased',
+            x,
+            y,
+            button: 'left',
+            clickCount: 1,
+        });
+    }
+    async nativeType(text) {
+        await this.cdp('Input.insertText', { text });
+    }
+    async insertText(text) {
+        await this.nativeType(text);
+    }
+    async nativeKeyPress(key, modifiers = []) {
+        let modifierFlags = 0;
+        for (const mod of modifiers) {
+            if (mod === 'Alt')
+                modifierFlags |= 1;
+            if (mod === 'Ctrl' || mod === 'Control')
+                modifierFlags |= 2;
+            if (mod === 'Meta')
+                modifierFlags |= 4;
+            if (mod === 'Shift')
+                modifierFlags |= 8;
+        }
+        await this.cdp('Input.dispatchKeyEvent', {
+            type: 'keyDown',
+            key,
+            modifiers: modifierFlags,
+        });
+        await this.cdp('Input.dispatchKeyEvent', {
+            type: 'keyUp',
+            key,
+            modifiers: modifierFlags,
+        });
+    }
 }
 function isCookie(value) {
     return isRecord(value)

package/dist/src/browser/cdp.test.js

@@ -49,4 +49,30 @@ describe('CDPBridge cookies', () => {
             { name: 'exact', value: '2', domain: 'example.com' },
         ]);
     });
+    it('exposes native input helpers on direct CDP pages', async () => {
+        vi.stubEnv('OPENCLI_CDP_ENDPOINT', 'ws://127.0.0.1:9222/devtools/page/1');
+        const bridge = new CDPBridge();
+        const send = vi.spyOn(bridge, 'send').mockResolvedValue({});
+        const page = await bridge.connect();
+        send.mockClear();
+        expect(page.nativeType).toBeTypeOf('function');
+        expect(page.nativeKeyPress).toBeTypeOf('function');
+        expect(page.nativeClick).toBeTypeOf('function');
+        expect(page.handleJavaScriptDialog).toBeTypeOf('function');
+        expect(page.cdp).toBeTypeOf('function');
+        await page.nativeType('hello');
+        await page.nativeKeyPress('a', ['Ctrl']);
+        await page.nativeClick(10, 20);
+        await page.handleJavaScriptDialog(true, 'ok');
+        await page.cdp('Page.getLayoutMetrics', {});
+        expect(send.mock.calls).toEqual([
+            ['Input.insertText', { text: 'hello' }],
+            ['Input.dispatchKeyEvent', { type: 'keyDown', key: 'a', modifiers: 2 }],
+            ['Input.dispatchKeyEvent', { type: 'keyUp', key: 'a', modifiers: 2 }],
+            ['Input.dispatchMouseEvent', { type: 'mousePressed', x: 10, y: 20, button: 'left', clickCount: 1 }],
+            ['Input.dispatchMouseEvent', { type: 'mouseReleased', x: 10, y: 20, button: 'left', clickCount: 1 }],
+            ['Page.handleJavaScriptDialog', { accept: true, promptText: 'ok' }],
+            ['Page.getLayoutMetrics', {}],
+        ]);
+    });
 });

package/dist/src/browser/dom-helpers.d.ts

@@ -11,7 +11,7 @@ export declare function clickJs(ref: string): string;
  *  Uses native setter for React compat + execCommand for contenteditable. */
 export declare function typeTextJs(ref: string, text: string): string;
 /** Generate JS to press a keyboard key */
-export declare function pressKeyJs(key: string): string;
+export declare function pressKeyJs(key: string, modifiers?: string[]): string;
 /** Generate JS to wait for text to appear in the page */
 export declare function waitForTextJs(text: string, timeoutMs: number): string;
 /** Generate JS for scroll */

package/dist/src/browser/dom-helpers.js

@@ -80,12 +80,24 @@ export function typeTextJs(ref, text) {
   `;
 }
 /** Generate JS to press a keyboard key */
-export function pressKeyJs(key) {
+export function pressKeyJs(key, modifiers = []) {
+    const hasCtrl = modifiers.includes('Ctrl') || modifiers.includes('Control');
+    const hasAlt = modifiers.includes('Alt');
+    const hasMeta = modifiers.includes('Meta');
+    const hasShift = modifiers.includes('Shift');
     return `
     (() => {
       const el = document.activeElement || document.body;
-      el.dispatchEvent(new KeyboardEvent('keydown', { key: ${JSON.stringify(key)}, bubbles: true }));
-      el.dispatchEvent(new KeyboardEvent('keyup', { key: ${JSON.stringify(key)}, bubbles: true }));
+      const init = {
+        key: ${JSON.stringify(key)},
+        bubbles: true,
+        ctrlKey: ${hasCtrl},
+        altKey: ${hasAlt},
+        metaKey: ${hasMeta},
+        shiftKey: ${hasShift},
+      };
+      el.dispatchEvent(new KeyboardEvent('keydown', init));
+      el.dispatchEvent(new KeyboardEvent('keyup', init));
       return 'pressed';
     })()
   `;

package/dist/src/browser/page.d.ts

@@ -68,6 +68,7 @@ export declare class Page extends BasePage {
     }>>;
     evaluateInFrame(js: string, frameIndex: number): Promise<unknown>;
     cdp(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    handleJavaScriptDialog(accept: boolean, promptText?: string): Promise<void>;
     /** CDP native click fallback — called when JS el.click() fails */
     protected tryNativeClick(x: number, y: number): Promise<boolean>;
     /** Precise click using DOM.getContentQuads/getBoxModel for inline elements */

package/dist/src/browser/page.js

@@ -283,6 +283,12 @@ export class Page extends BasePage {
             ...this._cmdOpts(),
         });
     }
+    async handleJavaScriptDialog(accept, promptText) {
+        await this.cdp('Page.handleJavaScriptDialog', {
+            accept,
+            ...(promptText !== undefined && { promptText }),
+        });
+    }
     /** CDP native click fallback — called when JS el.click() fails */
     async tryNativeClick(x, y) {
         try {
@@ -374,7 +380,7 @@ export class Page extends BasePage {
         for (const mod of modifiers) {
             if (mod === 'Alt')
                 modifierFlags |= 1;
-            if (mod === 'Ctrl')
+            if (mod === 'Ctrl' || mod === 'Control')
                 modifierFlags |= 2;
             if (mod === 'Meta')
                 modifierFlags |= 4;

package/dist/src/browser/page.test.js

@@ -102,6 +102,23 @@ describe('Page network capture compatibility', () => {
         expect(warnMock).toHaveBeenCalledTimes(1);
     });
 });
+describe('Page CDP helpers', () => {
+    beforeEach(() => {
+        sendCommandMock.mockReset();
+        sendCommandFullMock.mockReset();
+        warnMock.mockReset();
+    });
+    it('handles JavaScript dialogs through the CDP passthrough', async () => {
+        sendCommandMock.mockResolvedValueOnce({});
+        const page = new Page('browser:default');
+        await page.handleJavaScriptDialog(true, 'confirm');
+        expect(sendCommandMock).toHaveBeenCalledWith('cdp', expect.objectContaining({
+            workspace: 'browser:default',
+            cdpMethod: 'Page.handleJavaScriptDialog',
+            cdpParams: { accept: true, promptText: 'confirm' },
+        }));
+    });
+});
 describe('Page active target tracking', () => {
     beforeEach(() => {
         sendCommandMock.mockReset();

package/dist/src/browser/target-resolver.d.ts

@@ -72,16 +72,31 @@ export declare function resolveTargetJs(ref: string, opts?: ResolveOptions): str
  * Generate JS for click that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
  */
-export declare function clickResolvedJs(): string;
+export declare function clickResolvedJs(opts?: {
+    skipScroll?: boolean;
+}): string;
 /**
  * Generate JS for type that uses the unified resolver.
  */
 export declare function typeResolvedJs(text: string): string;
+/**
+ * Prepare the resolved element for native CDP Input.insertText.
+ *
+ * This preserves `browser type`'s existing "replace current text" semantics:
+ * focus the editable target, select its current contents, then let CDP insert
+ * real browser text input so rich editors can update their internal state.
+ */
+export declare function prepareNativeTypeResolvedJs(opts?: {
+    skipScroll?: boolean;
+    skipFocus?: boolean;
+}): string;
 /**
  * Generate JS for scrollTo that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
  */
-export declare function scrollResolvedJs(): string;
+export declare function scrollResolvedJs(opts?: {
+    skipScroll?: boolean;
+}): string;
 /**
  * Generate JS to get text content of resolved element.
  */