@jackwener/opencli 1.7.10 → 1.7.11

package/README.md

@@ -97,7 +97,7 @@ If you want to add your own commands, start with the [Extending OpenCLI guide](.
 |------|------------------|
 | Keep personal website commands in your own Git repo | `opencli plugin create` + `opencli plugin install file://...` |
 | Quickly draft a private local adapter | `opencli browser init <site>/<command>` in `~/.opencli/clis/` |
-| Modify an official adapter locally | `opencli adapter eject/status/reset` |
+| Modify an official adapter locally | `opencli adapter eject <site>` + `opencli adapter reset <site>` |
 | Publish or install third-party commands | `opencli plugin install github:user/repo` |
 | Wrap an existing local binary | `opencli external register <name>` |
 
@@ -174,7 +174,7 @@ When the site you need is not yet covered, use the `opencli-adapter-author` skil
 2. Discover the right endpoint — network inspection, initial state, bundle search, token trace, or interceptor fallback.
 3. Decide the auth strategy — `PUBLIC` / `COOKIE` / `HEADER` / `INTERCEPT`.
 4. Decode response fields and design output columns.
-5. `opencli browser init <site>/<name>` → write adapter → `opencli browser verify <site>/<name>`.
+5. `opencli browser analyze <url>` for one-shot recon, then `opencli browser init <site>/<name>` → write adapter → `opencli browser verify <site>/<name>`.
 6. Persist site knowledge to `~/.opencli/sites/<site>/` so the next adapter for the same site is faster.
 
 ### CLI Hub and desktop adapters
@@ -407,7 +407,7 @@ Before writing any adapter code, read the [`opencli-adapter-author` skill](./ski
 - Recon the site and pick a pattern (SPA / SSR / JSONP / Token / Streaming).
 - Discover the right endpoint via `opencli browser network`, `eval`, or the interceptor fallback.
 - Decide auth strategy (`PUBLIC` / `COOKIE` / `HEADER` / `INTERCEPT`).
-- Decode response fields, design columns, scaffold with `opencli browser init`.
+- Run `opencli browser analyze <url>` for one-shot recon, decode response fields, design columns, scaffold with `opencli browser init`.
 - Verify with `opencli browser verify <site>/<name>` before shipping.
 
 For long-lived personal commands that should live in your own Git repo, use a local plugin instead; see [Extending OpenCLI](./docs/guide/extending-opencli.md). Quick private adapters can still live at `~/.opencli/clis/<site>/<name>.js`. Site knowledge (endpoints, field maps, fixtures) accumulates in `~/.opencli/sites/<site>/` so the next adapter for the same site starts from context instead of zero.

package/README.zh-CN.md

@@ -81,7 +81,7 @@ opencli bilibili hot --limit 5
 |------|----------|
 | 把个人网站命令放在自己的 Git repo | `opencli plugin create` + `opencli plugin install file://...` |
 | 快速写一个本机私人 adapter | `opencli browser init <site>/<command>`，放在 `~/.opencli/clis/` |
-| 本地修改官方 adapter | `opencli adapter eject/status/reset` |
+| 本地修改官方 adapter | `opencli adapter eject <site>` + `opencli adapter reset <site>` |
 | 发布或安装第三方命令 | `opencli plugin install github:user/repo` |
 | 包装已有本机 binary | `opencli external register <name>` |
 
@@ -158,7 +158,7 @@ Agent 在内部自动处理所有 `opencli browser` 命令——你只需用自
 2. 发现目标 endpoint——network 精读、initial state、bundle 搜索、token 溯源，或 interceptor 兜底
 3. 定认证策略——`PUBLIC` / `COOKIE` / `HEADER` / `INTERCEPT`
 4. 字段解码 + 设计输出列
-5. `opencli browser init <site>/<name>` → 写适配器 → `opencli browser verify <site>/<name>`
+5. `opencli browser analyze <url>` 一步侦察，再 `opencli browser init <site>/<name>` → 写适配器 → `opencli browser verify <site>/<name>`
 6. 把站点知识沉到 `~/.opencli/sites/<site>/`，下次写同站点的其他命令直接吃缓存
 
 ### CLI 枢纽与桌面端适配器
@@ -505,7 +505,7 @@ opencli plugin uninstall my-tool                            # 卸载
 - 侦察站点，选定 pattern（SPA / SSR / JSONP / Token / Streaming）
 - 用 `opencli browser network`、`eval`、interceptor 等找到目标 endpoint
 - 定认证策略（`PUBLIC` / `COOKIE` / `HEADER` / `INTERCEPT`）
-- 字段解码、设计 columns、`opencli browser init` 生成骨架
+- 先用 `opencli browser analyze <url>` 一步侦察，再字段解码、设计 columns、`opencli browser init` 生成骨架
 - 交付前用 `opencli browser verify <site>/<name>` 验证
 
 在仓库外写的私有适配器放到 `~/.opencli/clis/<site>/<name>.js`；每个站点的 endpoint、字段映射、抓包样本会累积在 `~/.opencli/sites/<site>/`，下次写同站点的其他命令可以直接复用。

package/cli-manifest.json

@@ -8719,6 +8719,32 @@
     "sourceFile": "instagram/collection-create.js",
     "navigateBefore": "https://www.instagram.com"
   },
+  {
+    "site": "instagram",
+    "name": "collection-delete",
+    "description": "Delete an Instagram saved-posts collection (folder) by name or id",
+    "domain": "www.instagram.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "target",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "Collection name (case-insensitive) or numeric collection_id"
+      }
+    ],
+    "columns": [
+      "status",
+      "collectionId",
+      "collectionName"
+    ],
+    "type": "js",
+    "modulePath": "instagram/collection-delete.js",
+    "sourceFile": "instagram/collection-delete.js",
+    "navigateBefore": "https://www.instagram.com"
+  },
   {
     "site": "instagram",
     "name": "comment",

package/clis/instagram/collection-delete.js

@@ -0,0 +1,91 @@
+import { cli } from '@jackwener/opencli/registry';
+cli({
+    site: 'instagram',
+    name: 'collection-delete',
+    description: 'Delete an Instagram saved-posts collection (folder) by name or id',
+    domain: 'www.instagram.com',
+    args: [
+        {
+            name: 'target',
+            required: true,
+            positional: true,
+            help: 'Collection name (case-insensitive) or numeric collection_id',
+        },
+    ],
+    columns: ['status', 'collectionId', 'collectionName'],
+    pipeline: [
+        { navigate: 'https://www.instagram.com' },
+        { evaluate: `(async () => {
+  const target = \${{ args.target | json }};
+  if (!target || !String(target).trim()) {
+    throw new Error('Collection target (name or id) cannot be empty');
+  }
+  const raw = String(target).trim();
+  const csrf = document.cookie.match(/csrftoken=([^;]+)/)?.[1] || '';
+  if (!csrf) {
+    throw new Error('csrftoken cookie missing - make sure you are logged in to Instagram');
+  }
+  const headers = { 'X-IG-App-ID': '936619743392459' };
+
+  // Resolve name -> id via /collections/list/. Always go through this path so we can
+  // surface an explicit error on duplicate names or unknown names instead of relying
+  // on a 404.
+  const listRes = await fetch('https://www.instagram.com/api/v1/collections/list/?collection_types=%5B%22MEDIA%22%5D', {
+    credentials: 'include',
+    headers,
+  });
+  if (!listRes.ok) {
+    throw new Error('Failed to list collections: HTTP ' + listRes.status + ' - make sure you are logged in to Instagram');
+  }
+  const listData = await listRes.json();
+  const collections = listData?.items || [];
+  const isNumericId = /^\\d{6,}$/.test(raw);
+  let id = '';
+  let resolvedName = '';
+  if (isNumericId) {
+    const hit = collections.find((c) => String(c?.collection_id) === raw);
+    if (!hit) {
+      throw new Error('Collection id not found in your account: ' + raw);
+    }
+    id = String(hit.collection_id);
+    resolvedName = String(hit.collection_name || '');
+  } else {
+    const wanted = raw.toLowerCase();
+    const matches = collections.filter((c) => String(c?.collection_name || '').trim().toLowerCase() === wanted);
+    if (matches.length === 0) {
+      const names = collections.map((c) => c?.collection_name).filter(Boolean);
+      throw new Error('Collection not found: ' + raw + '. Available: ' + (names.length ? names.join(', ') : '(none)'));
+    }
+    if (matches.length > 1) {
+      const ids = matches.map((c) => c.collection_id).join(', ');
+      throw new Error('Multiple collections share the name "' + raw + '" (ids: ' + ids + '). Pass the numeric collection_id explicitly to disambiguate.');
+    }
+    id = String(matches[0].collection_id);
+    resolvedName = String(matches[0].collection_name || raw);
+  }
+
+  const fd = new FormData();
+  fd.append('module_name', 'collection_settings');
+  const res = await fetch('https://www.instagram.com/api/v1/collections/' + encodeURIComponent(id) + '/delete/', {
+    method: 'POST',
+    credentials: 'include',
+    headers: { ...headers, 'X-CSRFToken': csrf },
+    body: fd,
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error('Failed to delete collection: HTTP ' + res.status + (body ? ' - ' + body.slice(0, 200) : ''));
+  }
+  const d = await res.json().catch(() => ({}));
+  if (d?.status && d.status !== 'ok') {
+    throw new Error('Instagram returned non-ok status: ' + JSON.stringify(d).slice(0, 300));
+  }
+  return [{
+    status: 'Deleted',
+    collectionId: id,
+    collectionName: resolvedName,
+  }];
+})()
+` },
+    ],
+});

package/dist/src/adapter-shadow.d.ts

@@ -0,0 +1,11 @@
+export type AdapterShadow = {
+    name: string;
+    userPath: string;
+    builtinPath: string;
+};
+export type AdapterShadowOptions = {
+    userClisDir?: string;
+    builtinClisDir?: string;
+};
+export declare function findShadowedUserAdapters(opts?: AdapterShadowOptions): AdapterShadow[];
+export declare function formatAdapterShadowIssue(shadows: AdapterShadow[]): string;

package/dist/src/adapter-shadow.js

@@ -0,0 +1,72 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findPackageRoot, getCliManifestPath } from './package-paths.js';
+function defaultBuiltinClisDir() {
+    return path.join(findPackageRoot(fileURLToPath(import.meta.url)), 'clis');
+}
+function safeReaddir(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function loadBuiltinCommandFiles(builtinClisDir) {
+    try {
+        const raw = fs.readFileSync(getCliManifestPath(builtinClisDir), 'utf-8');
+        const entries = JSON.parse(raw);
+        const files = new Set();
+        for (const entry of entries) {
+            const rel = entry.sourceFile ?? entry.modulePath;
+            if (rel)
+                files.add(path.resolve(builtinClisDir, rel));
+        }
+        return files;
+    }
+    catch {
+        return new Set();
+    }
+}
+export function findShadowedUserAdapters(opts = {}) {
+    const userClisDir = opts.userClisDir ?? path.join(os.homedir(), '.opencli', 'clis');
+    const builtinClisDir = opts.builtinClisDir ?? defaultBuiltinClisDir();
+    const builtinCommandFiles = loadBuiltinCommandFiles(builtinClisDir);
+    const shadows = [];
+    for (const siteEntry of safeReaddir(userClisDir)) {
+        if (!siteEntry.isDirectory())
+            continue;
+        const site = siteEntry.name;
+        const userSiteDir = path.join(userClisDir, site);
+        const builtinSiteDir = path.join(builtinClisDir, site);
+        for (const commandEntry of safeReaddir(userSiteDir)) {
+            if (!commandEntry.isFile() || !commandEntry.name.endsWith('.js'))
+                continue;
+            const userPath = path.join(userSiteDir, commandEntry.name);
+            const builtinPath = path.join(builtinSiteDir, commandEntry.name);
+            const builtinResolved = path.resolve(builtinPath);
+            if (!builtinCommandFiles.has(builtinResolved))
+                continue;
+            shadows.push({
+                name: `${site}/${commandEntry.name.replace(/\.js$/, '')}`,
+                userPath,
+                builtinPath,
+            });
+        }
+    }
+    return shadows.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function formatAdapterShadowIssue(shadows) {
+    const visible = shadows.slice(0, 10);
+    const lines = ['Local adapter overrides shadow packaged adapters:'];
+    for (const shadow of visible) {
+        lines.push(`  ${shadow.name}: ${shadow.userPath} overrides ${shadow.builtinPath}`);
+    }
+    if (shadows.length > visible.length) {
+        lines.push(`  ... and ${shadows.length - visible.length} more`);
+    }
+    lines.push('Remove the local ~/.opencli/clis copy, or run opencli adapter reset <site>, when you want packaged updates.');
+    return lines.join('\n');
+}

package/dist/src/adapter-shadow.test.d.ts

@@ -0,0 +1 @@
+export {};

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/browser/base-page.d.ts

@@ -47,8 +47,12 @@ 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>;
     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,6 +36,27 @@ 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 */
@@ -147,17 +168,78 @@ 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;
+        }
     }
     async typeText(ref, text, opts = {}) {
         const resolved = await runResolve(this, ref, opts);
-        await this.evaluate(typeResolvedJs(text));
+        let typed = false;
+        if (typeof this.nativeType === 'function' || typeof this.insertText === 'function') {
+            try {
+                const preparation = await this.evaluate(prepareNativeTypeResolvedJs());
+                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);

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,23 @@ class TestPage extends BasePage {
     async tabs() { return []; }
     async selectTab() { }
 }
+class ActionPage extends BasePage {
+    results = [];
+    scripts = [];
+    nativeType;
+    insertText;
+    nativeKeyPress;
+    async goto() { }
+    async evaluate(js) {
+        this.scripts.push(js);
+        return this.results.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 +89,46 @@ 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('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('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,54 @@ class CDPPage extends BasePage {
     async selectTab(_target) {
         // Not supported in direct CDP mode
     }
+    async cdp(method, params = {}) {
+        return this.bridge.send(method, params);
+    }
+    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,27 @@ 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.cdp).toBeTypeOf('function');
+        await page.nativeType('hello');
+        await page.nativeKeyPress('a', ['Ctrl']);
+        await page.nativeClick(10, 20);
+        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.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';
     })()
   `;