@jackwener/opencli 1.7.12 → 1.7.14

package/clis/yuanbao/shared.js

@@ -1,7 +1,12 @@
-import { AuthRequiredError } from '@jackwener/opencli/errors';
+import { ArgumentError, AuthRequiredError } from '@jackwener/opencli/errors';
+
 export const YUANBAO_DOMAIN = 'yuanbao.tencent.com';
 export const YUANBAO_URL = 'https://yuanbao.tencent.com/';
 const SESSION_HINT = 'Likely login/auth/challenge/session issue in the existing yuanbao.tencent.com browser session.';
+
+const AGENT_ID_RE = /^[A-Za-z0-9_-]{4,40}$/;
+const CONV_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
 /**
  * Reusable visibility check for injected browser scripts.
  * Embed in page.evaluate strings via `${IS_VISIBLE_JS}`.
@@ -15,27 +20,36 @@ export const IS_VISIBLE_JS = `const isVisible = (node) => {
     && style.display !== 'none'
     && style.visibility !== 'hidden';
 };`;
+
 export function authRequired(message) {
     return new AuthRequiredError(YUANBAO_DOMAIN, `${message} ${SESSION_HINT}`);
 }
+
+export function normalizeBooleanFlag(value, fallback = false) {
+    if (typeof value === 'boolean') return value;
+    if (value == null || value === '') return fallback;
+    const normalized = String(value).trim().toLowerCase();
+    return normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on';
+}
+
 export async function isOnYuanbao(page) {
     const url = await page.evaluate('window.location.href').catch(() => '');
-    if (typeof url !== 'string' || !url)
-        return false;
+    if (typeof url !== 'string' || !url) return false;
     try {
         const hostname = new URL(url).hostname;
         return hostname === YUANBAO_DOMAIN || hostname.endsWith(`.${YUANBAO_DOMAIN}`);
-    }
-    catch {
+    } catch {
         return false;
     }
 }
+
 export async function ensureYuanbaoPage(page) {
     if (!(await isOnYuanbao(page))) {
         await page.goto(YUANBAO_URL, { waitUntil: 'load', settleMs: 2500 });
         await page.wait(1);
     }
 }
+
 export async function hasLoginGate(page) {
     const result = await page.evaluate(`(() => {
     const bodyText = document.body.innerText || '';
@@ -47,3 +61,281 @@ export async function hasLoginGate(page) {
   })()`);
     return Boolean(result);
 }
+
+export async function isLoggedIn(page) {
+    return !(await hasLoginGate(page));
+}
+
+/**
+ * Extract Yuanbao session identity from a raw input.
+ *
+ * Yuanbao chat URLs are `/chat/<agentId>/<convId>`. Both parts are required
+ * to navigate — there is no stable default agentId we can fall back to. So we
+ * only accept inputs that resolve a complete `{agentId, convId}` pair:
+ *   - full `https://yuanbao.tencent.com/chat/<agentId>/<convId>` URL
+ *   - bare slash form `<agentId>/<convId>`
+ *
+ * A bare convId UUID is rejected with an actionable message — opening the
+ * wrong agent silently is a much worse failure mode than throwing.
+ *
+ * The trailing `(?:[/?#]|$)` boundary in the URL regex prevents over-long
+ * suffixes (e.g. `<id>extra`) from silently truncating to a valid-looking ID.
+ */
+export function parseYuanbaoSessionId(input) {
+    const raw = String(input ?? '').trim();
+    if (!raw) {
+        throw new ArgumentError(
+            'id',
+            'must be a non-empty Yuanbao chat URL or "<agentId>/<convId>" pair',
+        );
+    }
+    const urlMatch = raw.match(/yuanbao\.tencent\.com\/chat\/([A-Za-z0-9_-]+)\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?:[/?#]|$)/i);
+    if (urlMatch) {
+        const [, agentId, convId] = urlMatch;
+        if (!AGENT_ID_RE.test(agentId) || !CONV_ID_RE.test(convId)) {
+            throw new ArgumentError(
+                'id',
+                `not a valid Yuanbao chat URL (got "${input}"); expected https://yuanbao.tencent.com/chat/<agentId>/<convId>`,
+            );
+        }
+        return { agentId, convId: convId.toLowerCase() };
+    }
+    const slashMatch = raw.match(/^([A-Za-z0-9_-]+)\/([0-9a-f-]{36})$/i);
+    if (slashMatch) {
+        const [, agentId, convId] = slashMatch;
+        if (!AGENT_ID_RE.test(agentId) || !CONV_ID_RE.test(convId)) {
+            throw new ArgumentError(
+                'id',
+                `not a valid Yuanbao "<agentId>/<convId>" pair (got "${input}"); agentId must be 4-40 word chars, convId must be a UUID`,
+            );
+        }
+        return { agentId, convId: convId.toLowerCase() };
+    }
+    throw new ArgumentError(
+        'id',
+        `not a valid Yuanbao session reference (got "${input}"); pass either a full https://yuanbao.tencent.com/chat/<agentId>/<convId> URL or a bare "<agentId>/<convId>" pair. A UUID alone is not enough — Yuanbao requires the agentId.`,
+    );
+}
+
+export async function getCurrentYuanbaoSessionId(page) {
+    const url = await page.evaluate('window.location.href').catch(() => '');
+    if (typeof url !== 'string') return null;
+    const match = url.match(/yuanbao\.tencent\.com\/chat\/([A-Za-z0-9_-]+)\/([0-9a-f-]{36})(?:[/?#]|$)/i);
+    if (!match) return null;
+    const [, agentId, convId] = match;
+    if (!AGENT_ID_RE.test(agentId) || !CONV_ID_RE.test(convId)) return null;
+    return { agentId, convId: convId.toLowerCase() };
+}
+
+export async function getYuanbaoModelLabel(page) {
+    const result = await page.evaluate(`(() => {
+    const btn = document.querySelector('[dt-button-id="model_switch"]');
+    if (!(btn instanceof HTMLElement)) return null;
+    const label = (btn.querySelector('.t-button__text')?.textContent || btn.textContent || '').trim();
+    const modelId = btn.getAttribute('dt-model-id') || '';
+    return { label, modelId };
+  })()`);
+    if (!result || typeof result !== 'object') return { label: null, modelId: null };
+    return {
+        label: typeof result.label === 'string' && result.label ? result.label : null,
+        modelId: typeof result.modelId === 'string' && result.modelId ? result.modelId : null,
+    };
+}
+
+/**
+ * Read the current conversation transcript as `{id, role, text, html}` rows.
+ *
+ * Each `.agent-chat__list__item` carries `data-conv-id` (`<convId>_<idx>`),
+ * `data-conv-speaker` (`human`/`ai`), and `data-conv-idx`. We use those as the
+ * stable per-turn identity so polling/dedup logic in `ask` stays correct after
+ * future re-renders.
+ *
+ * Image-only assistant turns may have empty visible text; we keep them when
+ * `html` is non-empty so callers can render images downstream.
+ */
+export async function getYuanbaoMessageBubbles(page) {
+    const result = await page.evaluate(`(() => {
+    ${IS_VISIBLE_JS}
+    const items = Array.from(document.querySelectorAll('.agent-chat__list__item--human, .agent-chat__list__item--ai'))
+      .filter((node) => isVisible(node));
+    return items.map((node, positional) => {
+      const isAi = node.classList.contains('agent-chat__list__item--ai');
+      const role = isAi ? 'Assistant' : 'User';
+      const id = node.getAttribute('data-conv-id') || ('pos-' + positional + (isAi ? '-ai' : '-human'));
+      const idx = Number(node.getAttribute('data-conv-idx') || positional + 1);
+      const contentNode = isAi
+        ? (node.querySelector('.hyc-content-md-done')
+          || node.querySelector('.hyc-content-md')
+          || node.querySelector('.agent-chat__speech-text')
+          || node.querySelector('.agent-chat__bubble__content'))
+        : (node.querySelector('.hyc-component-text .hyc-content-text')
+          || node.querySelector('.hyc-content-text')
+          || node.querySelector('.agent-chat__bubble__content'));
+      const html = contentNode instanceof HTMLElement ? (contentNode.innerHTML || '') : '';
+      const rawText = contentNode instanceof HTMLElement
+        ? (contentNode.innerText || contentNode.textContent || '')
+        : ((node.innerText || node.textContent) || '');
+      return {
+        id,
+        idx,
+        role,
+        text: String(rawText || '').replace(/\\u00a0/g, ' ').trim(),
+        html,
+      };
+    });
+  })()`);
+    if (!Array.isArray(result)) return [];
+    return result
+        .map((item) => ({
+            id: String(item?.id || ''),
+            idx: Number.isInteger(item?.idx) ? item.idx : 0,
+            role: item?.role === 'Assistant' ? 'Assistant' : 'User',
+            text: String(item?.text || '').trim(),
+            html: String(item?.html || ''),
+        }))
+        .filter((item) => item.id && (item.text || item.html));
+}
+
+/**
+ * Enumerate sidebar conversation entries.
+ *
+ * Each `.yb-recent-conv-list__item` exposes:
+ *   - `dt-cid`     — conversation UUID
+ *   - `dt-agent-id`— agent slug
+ *   - `[data-item-name]` — display title
+ *
+ * We do NOT trigger sidebar virtual scroll here — Yuanbao loads the visible
+ * window only, so callers requesting a higher `limit` than the rendered count
+ * get whatever is currently rendered. That matches Yuanbao's own UX.
+ */
+export async function getYuanbaoSessionList(page, limit) {
+    const cap = Number(limit ?? 20);
+    if (!Number.isInteger(cap) || cap <= 0) {
+        throw new ArgumentError('limit', 'must be a positive integer');
+    }
+    const result = await page.evaluate(`(() => {
+    ${IS_VISIBLE_JS}
+    const nodes = Array.from(document.querySelectorAll('.yb-recent-conv-list__item'))
+      .filter((node) => isVisible(node));
+    return nodes.map((node) => {
+      const cid = node.getAttribute('dt-cid') || '';
+      const agentId = node.getAttribute('dt-agent-id') || '';
+      const titleEl = node.querySelector('[data-item-name]');
+      const title = (titleEl?.getAttribute('data-item-name') || titleEl?.textContent || '').trim();
+      return { cid, agentId, title };
+    });
+  })()`);
+    if (!Array.isArray(result)) return [];
+    return result
+        .map((item) => ({
+            cid: String(item?.cid || '').toLowerCase(),
+            agentId: String(item?.agentId || ''),
+            title: String(item?.title || '').trim(),
+        }))
+        .filter((item) => CONV_ID_RE.test(item.cid) && AGENT_ID_RE.test(item.agentId))
+        .slice(0, cap);
+}
+
+export async function startNewYuanbaoChat(page) {
+    await ensureYuanbaoPage(page);
+    if (await hasLoginGate(page)) return 'blocked';
+    const beforeUrl = await page.evaluate('window.location.href').catch(() => '');
+    const action = await page.evaluate(`(() => {
+    ${IS_VISIBLE_JS}
+    const trigger = Array.from(document.querySelectorAll('.yb-common-nav__trigger[data-desc="new-chat"], [dt-button-id="new_temp_chat"]'))
+      .find((node) => isVisible(node));
+    if (trigger instanceof HTMLElement) {
+      trigger.click();
+      return 'clicked';
+    }
+    return 'navigate';
+  })()`);
+    if (action === 'navigate') {
+        await page.goto(YUANBAO_URL, { waitUntil: 'load', settleMs: 2500 });
+        await page.wait(1);
+        return (await hasLoginGate(page)) ? 'blocked' : 'navigate';
+    }
+    await page.wait(1);
+    if (await hasLoginGate(page)) return 'blocked';
+    const afterUrl = await page.evaluate('window.location.href').catch(() => '');
+    if (typeof afterUrl === 'string' && typeof beforeUrl === 'string' && afterUrl !== beforeUrl) {
+        return 'clicked';
+    }
+    // Click had no observable effect — fall back to homepage navigation.
+    await page.goto(YUANBAO_URL, { waitUntil: 'load', settleMs: 2500 });
+    await page.wait(1);
+    return 'navigate';
+}
+
+/**
+ * Drive the Quill composer to insert `prompt` and click the send button.
+ *
+ * Yuanbao toggles the send button between `style__send-btn___*` (enabled) and
+ * `style__send-btn--disabled___*` based on a debounced React re-render after
+ * the composer's input event. A naive 200ms wait races that re-render — the
+ * button is still `--disabled` at click time, the click is a no-op, and
+ * Enter-key fallback in Quill does not always submit. We poll the
+ * disabled-state for up to ~3s and only fall back to Enter when the React
+ * update never arrives.
+ *
+ * Returns `{ok: true, action}` or `{ok: false, reason, detail?}`.
+ */
+export async function sendYuanbaoMessage(page, prompt) {
+    return await page.evaluate(`(async () => {
+    const waitFor = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+    ${IS_VISIBLE_JS}
+
+    const composer = Array.from(document.querySelectorAll('.ql-editor[contenteditable="true"], .ql-editor, [contenteditable="true"]'))
+      .find(isVisible);
+
+    if (!(composer instanceof HTMLElement)) {
+      return {
+        ok: false,
+        reason: 'Yuanbao composer was not found.',
+      };
+    }
+
+    try {
+      composer.focus();
+      const selection = window.getSelection();
+      const range = document.createRange();
+      range.selectNodeContents(composer);
+      range.collapse(false);
+      selection?.removeAllRanges();
+      selection?.addRange(range);
+      composer.textContent = '';
+      document.execCommand('insertText', false, ${JSON.stringify(prompt)});
+      composer.dispatchEvent(new InputEvent('input', { bubbles: true, data: ${JSON.stringify(prompt)}, inputType: 'insertText' }));
+    } catch (error) {
+      return {
+        ok: false,
+        reason: 'Failed to insert the prompt into the Yuanbao composer.',
+        detail: error instanceof Error ? error.message : String(error),
+      };
+    }
+
+    const findEnabledSubmit = () => Array.from(document.querySelectorAll('a[class*="send-btn"], button[class*="send-btn"]'))
+      .find((node) => {
+        if (!(node instanceof HTMLElement) || !isVisible(node)) return false;
+        const className = typeof node.className === 'string' ? node.className : '';
+        return !className.includes('send-btn--disabled') && !className.includes('disabled');
+      });
+
+    let submit = null;
+    const deadline = Date.now() + 3_000;
+    while (Date.now() < deadline) {
+      submit = findEnabledSubmit();
+      if (submit) break;
+      await waitFor(150);
+    }
+
+    if (submit instanceof HTMLElement) {
+      submit.click();
+      return { ok: true, action: 'click' };
+    }
+
+    composer.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', code: 'Enter', keyCode: 13, bubbles: true }));
+    composer.dispatchEvent(new KeyboardEvent('keyup', { key: 'Enter', code: 'Enter', keyCode: 13, bubbles: true }));
+    return { ok: true, action: 'enter' };
+  })()`);
+}

package/clis/yuanbao/shared.test.js

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+import { ArgumentError } from '@jackwener/opencli/errors';
+import { normalizeBooleanFlag, parseYuanbaoSessionId } from './shared.js';
+
+describe('yuanbao parseYuanbaoSessionId', () => {
+    const agentId = 'naQivTmsDa';
+    const convId = 'b1118732-15ca-42cc-bc9a-e40090ccfb8c';
+
+    it('extracts agent + conv from a full chat URL', () => {
+        expect(parseYuanbaoSessionId(`https://yuanbao.tencent.com/chat/${agentId}/${convId}`))
+            .toEqual({ agentId, convId });
+    });
+
+    it('extracts agent + conv from URL with query string or fragment', () => {
+        expect(parseYuanbaoSessionId(`https://yuanbao.tencent.com/chat/${agentId}/${convId}?ref=share`))
+            .toEqual({ agentId, convId });
+        expect(parseYuanbaoSessionId(`https://yuanbao.tencent.com/chat/${agentId}/${convId}#anchor`))
+            .toEqual({ agentId, convId });
+    });
+
+    it('lowercases the conv UUID', () => {
+        expect(parseYuanbaoSessionId(`https://yuanbao.tencent.com/chat/${agentId}/${convId.toUpperCase()}`))
+            .toEqual({ agentId, convId });
+    });
+
+    it('accepts a bare "<agentId>/<convId>" pair', () => {
+        expect(parseYuanbaoSessionId(`${agentId}/${convId}`)).toEqual({ agentId, convId });
+    });
+
+    it('throws on empty / blank input', () => {
+        expect(() => parseYuanbaoSessionId('')).toThrow(ArgumentError);
+        expect(() => parseYuanbaoSessionId('   ')).toThrow(ArgumentError);
+        expect(() => parseYuanbaoSessionId(null)).toThrow(ArgumentError);
+        expect(() => parseYuanbaoSessionId(undefined)).toThrow(ArgumentError);
+    });
+
+    it('rejects a bare conv UUID (Yuanbao requires the agent slug)', () => {
+        expect(() => parseYuanbaoSessionId(convId)).toThrow(ArgumentError);
+    });
+
+    it('rejects a URL with a 37+ char conv tail (no silent truncation)', () => {
+        // Boundary regression: without `(?:[/?#]|$)` the regex would happily
+        // match the first 36 chars and silently open a different conversation.
+        expect(() => parseYuanbaoSessionId(`https://yuanbao.tencent.com/chat/${agentId}/${convId}extra`))
+            .toThrow(ArgumentError);
+        expect(() => parseYuanbaoSessionId(`https://yuanbao.tencent.com/chat/${agentId}/${convId}0000`))
+            .toThrow(ArgumentError);
+    });
+
+    it('rejects malformed shapes with actionable messages', () => {
+        expect(() => parseYuanbaoSessionId('abc')).toThrow(ArgumentError);
+        expect(() => parseYuanbaoSessionId('https://yuanbao.tencent.com/somewhere/else')).toThrow(ArgumentError);
+        // agent slug too short to be valid
+        expect(() => parseYuanbaoSessionId(`abc/${convId}`)).toThrow(ArgumentError);
+        // conv part not a UUID
+        expect(() => parseYuanbaoSessionId(`${agentId}/not-a-uuid-at-all`)).toThrow(ArgumentError);
+    });
+});
+
+describe('yuanbao normalizeBooleanFlag', () => {
+    it('passes through real booleans', () => {
+        expect(normalizeBooleanFlag(true, false)).toBe(true);
+        expect(normalizeBooleanFlag(false, true)).toBe(false);
+    });
+
+    it('returns fallback for null/empty', () => {
+        expect(normalizeBooleanFlag(undefined, true)).toBe(true);
+        expect(normalizeBooleanFlag(null, false)).toBe(false);
+        expect(normalizeBooleanFlag('', true)).toBe(true);
+    });
+
+    it('parses common truthy / falsy strings', () => {
+        for (const v of ['true', 'TRUE', '1', 'yes', 'on']) {
+            expect(normalizeBooleanFlag(v, false)).toBe(true);
+        }
+        for (const v of ['false', '0', 'no', 'off', 'unknown']) {
+            expect(normalizeBooleanFlag(v, true)).toBe(false);
+        }
+    });
+});

package/clis/yuanbao/status.js

@@ -0,0 +1,44 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    YUANBAO_DOMAIN,
+    ensureYuanbaoPage,
+    isLoggedIn,
+    getCurrentYuanbaoSessionId,
+    getYuanbaoModelLabel,
+} from './shared.js';
+
+cli({
+    site: 'yuanbao',
+    name: 'status',
+    access: 'read',
+    description: 'Check Yuanbao page availability, login state, current session and model',
+    domain: YUANBAO_DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    browserSession: { reuse: 'site' },
+    navigateBefore: false,
+    args: [],
+    columns: ['Status', 'Login', 'Model', 'ModelId', 'AgentId', 'SessionId', 'Url'],
+    func: async (page) => {
+        await ensureYuanbaoPage(page);
+        await page.wait(1.5);
+        const [loggedIn, session, model, url] = await Promise.all([
+            isLoggedIn(page),
+            getCurrentYuanbaoSessionId(page),
+            getYuanbaoModelLabel(page),
+            page.evaluate('window.location.href').catch(() => ''),
+        ]);
+        // Surface unknown values as `null` (typed unknown) rather than '-' / ''
+        // sentinels — sentinels look like real labels and silently break filters
+        // built on these columns.
+        return [{
+            Status: 'Connected',
+            Login: loggedIn ? 'Yes' : 'No (login gate)',
+            Model: model.label,
+            ModelId: model.modelId,
+            AgentId: session?.agentId ?? null,
+            SessionId: session?.convId ?? null,
+            Url: typeof url === 'string' ? url : '',
+        }];
+    },
+});

package/clis/zlibrary/commands.test.js

@@ -7,18 +7,8 @@ import {
 } from './utils.js';
 import './search.js';
 import './info.js';
+import { createPageMock } from '../test-utils.js';
 
-function createPageMock(evaluateResults = []) {
-  const evaluate = vi.fn();
-  for (const result of evaluateResults) {
-    evaluate.mockResolvedValueOnce(result);
-  }
-  return {
-    goto: vi.fn().mockResolvedValue(undefined),
-    wait: vi.fn().mockResolvedValue(undefined),
-    evaluate,
-  };
-}
 
 describe('zlibrary commands', () => {
   it('registers search and info commands', () => {

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

@@ -19,6 +19,14 @@ export interface ResolveSuccess {
      */
     match_level: TargetMatchLevel;
 }
+export interface FillTextResult extends ResolveSuccess {
+    filled: boolean;
+    verified: boolean;
+    expected: string;
+    actual: string;
+    length: number;
+    mode?: 'input' | 'textarea' | 'contenteditable';
+}
 export declare abstract class BasePage implements IPage {
     protected _lastUrl: string | null;
     /** Cached previous snapshot hashes for incremental diff marking */
@@ -63,6 +71,7 @@ export declare abstract class BasePage implements IPage {
      */
     protected tryCdpOnResolvedElement(method: 'DOM.focus' | 'DOM.scrollIntoViewIfNeeded'): Promise<boolean>;
     typeText(ref: string, text: string, opts?: ResolveOptions): Promise<ResolveSuccess>;
+    fillText(ref: string, text: string, opts?: ResolveOptions): Promise<FillTextResult>;
     pressKey(key: string): Promise<void>;
     scrollTo(ref: string, opts?: ResolveOptions): Promise<unknown>;
     getFormState(): Promise<Record<string, 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, prepareNativeTypeResolvedJs, scrollResolvedJs, } from './target-resolver.js';
+import { resolveTargetJs, clickResolvedJs, typeResolvedJs, prepareNativeTypeResolvedJs, verifyFilledResolvedJs, scrollResolvedJs, } from './target-resolver.js';
 import { TargetError } from './target-errors.js';
 import { CliError } from '../errors.js';
 import { formatSnapshot } from '../snapshotFormatter.js';
@@ -303,6 +303,49 @@ export class BasePage {
         }
         return resolved;
     }
+    async fillText(ref, text, opts = {}) {
+        const resolved = await runResolve(this, ref, opts);
+        let nativeScrolled = false;
+        let nativeFocused = false;
+        try {
+            nativeScrolled = await this.tryCdpOnResolvedElement('DOM.scrollIntoViewIfNeeded');
+            nativeFocused = await this.tryCdpOnResolvedElement('DOM.focus');
+        }
+        catch {
+            // CDP focus/scroll is best-effort; DOM preparation below remains authoritative.
+        }
+        const preparation = await this.evaluate(prepareNativeTypeResolvedJs({
+            skipScroll: nativeScrolled,
+            skipFocus: nativeFocused,
+        }));
+        if (preparation?.ok !== true) {
+            throw new TargetError({
+                code: 'not_editable',
+                message: `Target "${ref}" is not a fillable input, textarea, or contenteditable element.`,
+                hint: 'Use `opencli browser state` to pick an editable target, or use `browser type` for keyboard-like interactions.',
+            });
+        }
+        const usedNativeInput = await this.tryNativeType(text);
+        if (!usedNativeInput) {
+            await this.evaluate(typeResolvedJs(text));
+        }
+        let verification = await this.evaluate(verifyFilledResolvedJs(text));
+        if (usedNativeInput && verification?.ok !== true) {
+            await this.evaluate(typeResolvedJs(text));
+            verification = await this.evaluate(verifyFilledResolvedJs(text));
+        }
+        const actual = verification && 'actual' in verification ? verification.actual : '';
+        const mode = verification && 'mode' in verification ? verification.mode : undefined;
+        return {
+            ...resolved,
+            filled: true,
+            verified: verification?.ok === true,
+            expected: text,
+            actual,
+            length: actual.length,
+            ...(mode ? { mode } : {}),
+        };
+    }
     async pressKey(key) {
         const parsed = parseKeyChord(key);
         if (!await this.tryNativeKeyPress(parsed.key, parsed.modifiers)) {

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

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
 import { CliError } from '../errors.js';
 import { BasePage } from './base-page.js';
+import { TargetError } from './target-errors.js';
 class TestPage extends BasePage {
     result;
     args;
@@ -146,6 +147,71 @@ describe('BasePage native input routing', () => {
         expect(page.scripts).toHaveLength(3);
         expect(page.scripts[2]).toContain("return 'typed'");
     });
+    it('fills text through the native input path and verifies the exact value', async () => {
+        const page = new ActionPage();
+        page.nativeType = vi.fn().mockResolvedValue(undefined);
+        page.results = [
+            resolveOk,
+            { ok: true, mode: 'textarea' },
+            { ok: true, actual: 'line1\\n/ / raw', expected: 'line1\\n/ / raw', length: 14, mode: 'textarea' },
+        ];
+        await expect(page.fillText('#message', 'line1\\n/ / raw')).resolves.toEqual({
+            filled: true,
+            verified: true,
+            expected: 'line1\\n/ / raw',
+            actual: 'line1\\n/ / raw',
+            length: 14,
+            matches_n: 1,
+            match_level: 'exact',
+            mode: 'textarea',
+        });
+        expect(page.nativeType).toHaveBeenCalledWith('line1\\n/ / raw');
+        expect(page.scripts).toHaveLength(3);
+        expect(page.scripts[2]).toContain('actual ===');
+    });
+    it('falls back to the DOM setter when native fill insertion is unavailable', async () => {
+        const page = new ActionPage();
+        page.results = [
+            resolveOk,
+            { ok: true, mode: 'input' },
+            'typed',
+            { ok: true, actual: 'hello', expected: 'hello', length: 5, mode: 'input' },
+        ];
+        await expect(page.fillText('#q', 'hello')).resolves.toEqual(expect.objectContaining({
+            filled: true,
+            verified: true,
+            actual: 'hello',
+            mode: 'input',
+        }));
+        expect(page.scripts).toHaveLength(4);
+        expect(page.scripts[2]).toContain("return 'typed'");
+    });
+    it('falls back to DOM fill if native insertion does not verify', async () => {
+        const page = new ActionPage();
+        page.nativeType = vi.fn().mockResolvedValue(undefined);
+        page.results = [
+            resolveOk,
+            { ok: true, mode: 'input' },
+            { ok: false, actual: '', expected: 'hello', length: 0, mode: 'input' },
+            'typed',
+            { ok: true, actual: 'hello', expected: 'hello', length: 5, mode: 'input' },
+        ];
+        await expect(page.fillText('#q', 'hello')).resolves.toEqual(expect.objectContaining({
+            filled: true,
+            verified: true,
+            actual: 'hello',
+        }));
+        expect(page.nativeType).toHaveBeenCalledWith('hello');
+        expect(page.scripts).toHaveLength(5);
+        expect(page.scripts[3]).toContain("return 'typed'");
+    });
+    it('throws a structured not_editable error for non-fillable targets', async () => {
+        const page = new ActionPage();
+        page.results = [resolveOk, { ok: false, reason: 'not_editable', tag: 'button' }];
+        const err = await page.fillText('button', 'hello').catch((error) => error);
+        expect(err).toBeInstanceOf(TargetError);
+        expect(err.code).toBe('not_editable');
+    });
     it('uses CDP DOM scrollIntoViewIfNeeded before JS click when available', async () => {
         const page = new ActionPage();
         page.cdp = vi.fn()