@jackwener/opencli 1.7.9 → 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

@@ -8692,6 +8692,59 @@
     "modulePath": "imdb/trending.js",
     "sourceFile": "imdb/trending.js"
   },
+  {
+    "site": "instagram",
+    "name": "collection-create",
+    "description": "Create a new Instagram saved-posts collection (folder)",
+    "domain": "www.instagram.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "name",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "Name of the collection to create"
+      }
+    ],
+    "columns": [
+      "status",
+      "collectionId",
+      "collectionName",
+      "mediaCount"
+    ],
+    "type": "js",
+    "modulePath": "instagram/collection-create.js",
+    "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",
@@ -9078,7 +9131,7 @@
   {
     "site": "instagram",
     "name": "saved",
-    "description": "Get your saved Instagram posts",
+    "description": "Get your saved Instagram posts (optionally from a specific collection)",
     "domain": "www.instagram.com",
     "strategy": "cookie",
     "browser": true,
@@ -9089,6 +9142,12 @@
         "default": 20,
         "required": false,
         "help": "Number of saved posts"
+      },
+      {
+        "name": "collection",
+        "type": "str",
+        "required": false,
+        "help": "Collection name (case-insensitive). Omit for the default \"All posts\" feed."
       }
     ],
     "columns": [

package/clis/instagram/collection-create.js

@@ -0,0 +1,57 @@
+import { cli } from '@jackwener/opencli/registry';
+cli({
+    site: 'instagram',
+    name: 'collection-create',
+    description: 'Create a new Instagram saved-posts collection (folder)',
+    domain: 'www.instagram.com',
+    args: [
+        {
+            name: 'name',
+            required: true,
+            positional: true,
+            help: 'Name of the collection to create',
+        },
+    ],
+    columns: ['status', 'collectionId', 'collectionName', 'mediaCount'],
+    pipeline: [
+        { navigate: 'https://www.instagram.com' },
+        { evaluate: `(async () => {
+  const name = \${{ args.name | json }};
+  if (!name || !String(name).trim()) {
+    throw new Error('Collection name cannot be empty');
+  }
+  const trimmed = String(name).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 fd = new FormData();
+  fd.append('name', trimmed);
+  fd.append('module_name', 'collection_create');
+  const res = await fetch('https://www.instagram.com/api/v1/collections/create/', {
+    method: 'POST',
+    credentials: 'include',
+    headers: {
+      'X-IG-App-ID': '936619743392459',
+      'X-CSRFToken': csrf,
+    },
+    body: fd,
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error('Failed to create collection: HTTP ' + res.status + (body ? ' - ' + body.slice(0, 200) : ''));
+  }
+  const d = await res.json();
+  if (d?.status && d.status !== 'ok') {
+    throw new Error('Instagram returned non-ok status: ' + JSON.stringify(d).slice(0, 300));
+  }
+  return [{
+    status: 'Created',
+    collectionId: String(d?.collection_id ?? ''),
+    collectionName: String(d?.collection_name ?? trimmed),
+    mediaCount: d?.collection_media_count ?? 0,
+  }];
+})()
+` },
+    ],
+});

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/clis/instagram/saved.js

@@ -2,23 +2,37 @@ import { cli } from '@jackwener/opencli/registry';
 cli({
     site: 'instagram',
     name: 'saved',
-    description: 'Get your saved Instagram posts',
+    description: 'Get your saved Instagram posts (optionally from a specific collection)',
     domain: 'www.instagram.com',
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Number of saved posts' },
+        { name: 'collection', help: 'Collection name (case-insensitive). Omit for the default "All posts" feed.' },
     ],
     columns: ['index', 'user', 'caption', 'likes', 'comments', 'type'],
     pipeline: [
         { navigate: 'https://www.instagram.com' },
         { evaluate: `(async () => {
   const limit = \${{ args.limit }};
-  const res = await fetch(
-    'https://www.instagram.com/api/v1/feed/saved/posts/',
-    {
-      credentials: 'include',
-      headers: { 'X-IG-App-ID': '936619743392459' }
+  const collectionArg = \${{ args.collection | json }};
+  const headers = { 'X-IG-App-ID': '936619743392459' };
+  const opts = { credentials: 'include', headers };
+
+  let endpoint = 'https://www.instagram.com/api/v1/feed/saved/posts/';
+  if (collectionArg && String(collectionArg).trim()) {
+    const wanted = String(collectionArg).trim().toLowerCase();
+    const listRes = await fetch('https://www.instagram.com/api/v1/collections/list/?collection_types=%5B%22MEDIA%22%2C%22ALL_MEDIA_AUTO_COLLECTION%22%5D', opts);
+    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 match = collections.find((c) => String(c?.collection_name || '').trim().toLowerCase() === wanted);
+    if (!match) {
+      const names = collections.map((c) => c?.collection_name).filter(Boolean);
+      throw new Error('Collection not found: ' + collectionArg + '. Available: ' + (names.length ? names.join(', ') : '(none)'));
     }
-  );
+    endpoint = 'https://www.instagram.com/api/v1/feed/collection/' + encodeURIComponent(match.collection_id) + '/posts/';
+  }
+
+  const res = await fetch(endpoint, opts);
   if (!res.ok) throw new Error('HTTP ' + res.status + ' - make sure you are logged in to Instagram');
   const data = await res.json();
   return (data?.items || []).slice(0, limit).map((item, i) => {

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);