@jackwener/opencli 1.7.4 → 1.7.6

package/clis/xiaoyuzhou/download.test.js

@@ -2,17 +2,19 @@ import path from 'node:path';
 import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '@jackwener/opencli/registry';
 
-const { mockFetchPageProps, mockHttpDownload, mockMkdirSync } = vi.hoisted(() => ({
-    mockFetchPageProps: vi.fn(),
+const { mockRequestJson, mockLoadCredentials, mockHttpDownload, mockMkdirSync } = vi.hoisted(() => ({
+    mockRequestJson: vi.fn(),
+    mockLoadCredentials: vi.fn(),
     mockHttpDownload: vi.fn(),
     mockMkdirSync: vi.fn(),
 }));
 
-vi.mock('./utils.js', async () => {
-    const actual = await vi.importActual('./utils.js');
+vi.mock('./auth.js', async () => {
+    const actual = await vi.importActual('./auth.js');
     return {
         ...actual,
-        fetchPageProps: mockFetchPageProps,
+        requestXiaoyuzhouJson: mockRequestJson,
+        loadXiaoyuzhouCredentials: mockLoadCredentials,
     };
 });
 
@@ -44,14 +46,17 @@ beforeAll(() => {
 
 describe('xiaoyuzhou download', () => {
     beforeEach(() => {
-        mockFetchPageProps.mockReset();
+        mockRequestJson.mockReset();
+        mockLoadCredentials.mockReset();
         mockHttpDownload.mockReset();
         mockMkdirSync.mockReset();
+        mockLoadCredentials.mockReturnValue({});
     });
 
     it('downloads audio from media.source.url into an episode subdirectory', async () => {
-        mockFetchPageProps.mockResolvedValue({
-            episode: {
+        mockRequestJson.mockResolvedValue({
+            credentials: {},
+            data: {
                 title: 'Hello World',
                 podcast: { title: 'OpenCLI FM' },
                 media: {
@@ -68,7 +73,10 @@ describe('xiaoyuzhou download', () => {
             output: '/tmp/xiaoyuzhou-test',
         });
 
-        expect(mockFetchPageProps).toHaveBeenCalledWith('/episode/ep123');
+        expect(mockRequestJson).toHaveBeenCalledWith('/v1/episode/get', {
+            query: { eid: 'ep123' },
+            credentials: {},
+        });
         expect(toPosixPath(mockMkdirSync.mock.calls[0][0])).toBe('/tmp/xiaoyuzhou-test/ep123');
         expect(mockMkdirSync.mock.calls[0][1]).toEqual({ recursive: true });
         expect(mockHttpDownload).toHaveBeenCalledWith('https://media.xyzcdn.net/audio/hello-world.mp3?sign=abc', expect.stringContaining('/tmp/xiaoyuzhou-test/ep123/ep123_Hello_World.mp3'), {
@@ -84,8 +92,9 @@ describe('xiaoyuzhou download', () => {
     });
 
     it('preserves non-mp3 extensions from media.source.url', async () => {
-        mockFetchPageProps.mockResolvedValue({
-            episode: {
+        mockRequestJson.mockResolvedValue({
+            credentials: {},
+            data: {
                 title: 'Lossless Episode',
                 podcast: { title: 'OpenCLI FM' },
                 media: {
@@ -107,8 +116,9 @@ describe('xiaoyuzhou download', () => {
     });
 
     it('throws when media.source.url is missing', async () => {
-        mockFetchPageProps.mockResolvedValue({
-            episode: {
+        mockRequestJson.mockResolvedValue({
+            credentials: {},
+            data: {
                 title: 'No Audio',
                 podcast: { title: 'OpenCLI FM' },
                 media: {},

package/clis/xiaoyuzhou/episode.js

@@ -1,18 +1,23 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
-import { fetchPageProps, formatDuration, formatDate } from './utils.js';
+import { loadXiaoyuzhouCredentials, requestXiaoyuzhouJson } from './auth.js';
+import { formatDuration, formatDate } from './utils.js';
 cli({
     site: 'xiaoyuzhou',
     name: 'episode',
     description: 'View details of a Xiaoyuzhou podcast episode',
     domain: 'www.xiaoyuzhoufm.com',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [{ name: 'id', positional: true, required: true, help: 'Episode ID (eid from podcast-episodes output)' }],
     columns: ['title', 'podcast', 'duration', 'plays', 'comments', 'likes', 'date'],
     func: async (_page, args) => {
-        const pageProps = await fetchPageProps(`/episode/${args.id}`);
-        const ep = pageProps.episode;
+        const credentials = loadXiaoyuzhouCredentials();
+        const response = await requestXiaoyuzhouJson('/v1/episode/get', {
+            query: { eid: args.id },
+            credentials,
+        });
+        const ep = response.data;
         if (!ep)
             throw new CliError('NOT_FOUND', 'Episode not found', 'Please check the ID');
         return [{

package/clis/xiaoyuzhou/podcast-episodes.js

@@ -1,30 +1,34 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
-import { fetchPageProps, formatDuration, formatDate } from './utils.js';
+import { loadXiaoyuzhouCredentials, requestXiaoyuzhouJson } from './auth.js';
+import { formatDuration, formatDate } from './utils.js';
 cli({
     site: 'xiaoyuzhou',
     name: 'podcast-episodes',
-    description: 'List recent episodes of a Xiaoyuzhou podcast (up to 15, SSR limit)',
+    description: 'List episodes of a Xiaoyuzhou podcast',
     domain: 'www.xiaoyuzhoufm.com',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [
         { name: 'id', positional: true, required: true, help: 'Podcast ID (from xiaoyuzhoufm.com URL)' },
-        { name: 'limit', type: 'int', default: 15, help: 'Max episodes to show (up to 15, SSR limit)' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max episodes to show' },
     ],
     columns: ['eid', 'title', 'duration', 'plays', 'date'],
     func: async (_page, args) => {
-        const pageProps = await fetchPageProps(`/podcast/${args.id}`);
-        const podcast = pageProps.podcast;
-        if (!podcast)
-            throw new CliError('NOT_FOUND', 'Podcast not found', 'Please check the ID');
-        const allEpisodes = podcast.episodes ?? [];
         const requestedLimit = Number(args.limit);
         if (!Number.isInteger(requestedLimit) || requestedLimit < 1) {
             throw new CliError('INVALID_ARGUMENT', 'limit must be a positive integer', 'Example: --limit 5');
         }
-        const limit = Math.min(requestedLimit, allEpisodes.length);
-        const episodes = allEpisodes.slice(0, limit);
+        const credentials = loadXiaoyuzhouCredentials();
+        const response = await requestXiaoyuzhouJson('/v1/podcast/listEpisode', {
+            method: 'POST',
+            body: { pid: args.id, limit: requestedLimit },
+            credentials,
+        });
+        const episodes = response.data ?? [];
+        if (!Array.isArray(episodes)) {
+            throw new CliError('PARSE_ERROR', 'Unexpected API response format', 'Expected an array of episodes');
+        }
         return episodes.map((ep) => ({
             eid: ep.eid,
             title: ep.title,

package/clis/xiaoyuzhou/podcast.js

@@ -1,18 +1,23 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
-import { fetchPageProps, formatDate } from './utils.js';
+import { loadXiaoyuzhouCredentials, requestXiaoyuzhouJson } from './auth.js';
+import { formatDate } from './utils.js';
 cli({
     site: 'xiaoyuzhou',
     name: 'podcast',
     description: 'View a Xiaoyuzhou podcast profile',
     domain: 'www.xiaoyuzhoufm.com',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [{ name: 'id', positional: true, required: true, help: 'Podcast ID (from xiaoyuzhoufm.com URL)' }],
     columns: ['title', 'author', 'description', 'subscribers', 'episodes', 'updated'],
     func: async (_page, args) => {
-        const pageProps = await fetchPageProps(`/podcast/${args.id}`);
-        const p = pageProps.podcast;
+        const credentials = loadXiaoyuzhouCredentials();
+        const response = await requestXiaoyuzhouJson('/v1/podcast/get', {
+            query: { pid: args.id },
+            credentials,
+        });
+        const p = response.data;
         if (!p)
             throw new CliError('NOT_FOUND', 'Podcast not found', 'Please check the ID');
         return [{

package/clis/xiaoyuzhou/utils.js

@@ -1,43 +1,3 @@
-/**
- * Shared Xiaoyuzhou utilities — page data extraction and formatting.
- *
- * Xiaoyuzhou (小宇宙) is a Next.js app that embeds full page data in
- * <script id="__NEXT_DATA__">. We fetch the HTML and extract that JSON
- * instead of using their authenticated API.
- */
-import { CliError } from '@jackwener/opencli/errors';
-/**
- * Fetch a Xiaoyuzhou page and extract __NEXT_DATA__.props.pageProps.
- * @param path - URL path, e.g. '/podcast/xxx' or '/episode/xxx'
- */
-export async function fetchPageProps(path) {
-    const url = `https://www.xiaoyuzhoufm.com${path}`;
-    // Node.js fetch sends UA "node" which gets blocked; use a browser-like UA
-    const resp = await fetch(url, {
-        headers: { 'User-Agent': 'Mozilla/5.0 (compatible; opencli)' },
-    });
-    if (!resp.ok) {
-        throw new CliError('FETCH_ERROR', `HTTP ${resp.status} for ${path}`, 'Please check the ID — you can find it in xiaoyuzhoufm.com URLs');
-    }
-    const html = await resp.text();
-    // [\s\S]*? for multiline safety (JSON may span lines)
-    const match = html.match(/<script id="__NEXT_DATA__"[^>]*>([\s\S]*?)<\/script>/);
-    if (!match) {
-        throw new CliError('PARSE_ERROR', 'Failed to extract __NEXT_DATA__', 'Page structure may have changed');
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(match[1]);
-    }
-    catch {
-        throw new CliError('PARSE_ERROR', 'Malformed __NEXT_DATA__ JSON', 'Page structure may have changed');
-    }
-    const pageProps = parsed.props?.pageProps;
-    if (!pageProps || Object.keys(pageProps).length === 0) {
-        throw new CliError('NOT_FOUND', 'Resource not found', 'Please check the ID — you can find it in xiaoyuzhoufm.com URLs');
-    }
-    return pageProps;
-}
 /** Format seconds to mm:ss (e.g. 3890 → "64:50"). Returns '-' for invalid input. */
 export function formatDuration(seconds) {
     if (!Number.isFinite(seconds) || seconds < 0)

package/clis/xiaoyuzhou/utils.test.js

@@ -1,5 +1,5 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { formatDuration, formatDate, fetchPageProps } from './utils.js';
+import { describe, it, expect } from 'vitest';
+import { formatDuration, formatDate } from './utils.js';
 describe('formatDuration', () => {
     it('formats typical duration', () => {
         expect(formatDuration(3890)).toBe('64:50');
@@ -8,13 +8,13 @@ describe('formatDuration', () => {
         expect(formatDuration(0)).toBe('0:00');
     });
     it('pads single-digit seconds', () => {
-        expect(formatDuration(65)).toBe('1:05');
+        expect(formatDuration(62)).toBe('1:02');
     });
-    it('formats exact minutes', () => {
-        expect(formatDuration(3600)).toBe('60:00');
+    it('handles exact minutes', () => {
+        expect(formatDuration(120)).toBe('2:00');
     });
-    it('rounds floating-point seconds', () => {
-        expect(formatDuration(3890.7)).toBe('64:51');
+    it('rounds fractional seconds', () => {
+        expect(formatDuration(65.7)).toBe('1:06');
     });
     it('returns dash for NaN', () => {
         expect(formatDuration(NaN)).toBe('-');
@@ -22,78 +22,18 @@ describe('formatDuration', () => {
     it('returns dash for negative', () => {
         expect(formatDuration(-1)).toBe('-');
     });
+    it('returns dash for Infinity', () => {
+        expect(formatDuration(Infinity)).toBe('-');
+    });
 });
 describe('formatDate', () => {
-    it('extracts YYYY-MM-DD from ISO string', () => {
-        expect(formatDate('2026-03-13T11:00:06.686Z')).toBe('2026-03-13');
-    });
-    it('handles date-only string', () => {
-        expect(formatDate('2025-01-01')).toBe('2025-01-01');
+    it('slices ISO string to date', () => {
+        expect(formatDate('2026-03-15T12:00:00Z')).toBe('2026-03-15');
     });
-    it('returns dash for undefined/empty', () => {
+    it('returns dash for empty string', () => {
         expect(formatDate('')).toBe('-');
-        expect(formatDate(undefined)).toBe('-');
-    });
-});
-describe('fetchPageProps', () => {
-    beforeEach(() => {
-        vi.restoreAllMocks();
-    });
-    it('extracts pageProps from valid HTML', async () => {
-        const mockHtml = `<html><script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{"podcast":{"title":"Test"}}}}</script></html>`;
-        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-            ok: true,
-            text: () => Promise.resolve(mockHtml),
-        }));
-        const result = await fetchPageProps('/podcast/abc123');
-        expect(result).toEqual({ podcast: { title: 'Test' } });
     });
-    it('throws on HTTP error', async () => {
-        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-            ok: false,
-            status: 404,
-            text: () => Promise.resolve('Not Found'),
-        }));
-        await expect(fetchPageProps('/podcast/invalid')).rejects.toThrow('HTTP 404');
-    });
-    it('throws when __NEXT_DATA__ is missing', async () => {
-        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-            ok: true,
-            text: () => Promise.resolve('<html><body>No data here</body></html>'),
-        }));
-        await expect(fetchPageProps('/podcast/abc')).rejects.toThrow('Failed to extract');
-    });
-    it('throws when pageProps is empty', async () => {
-        const mockHtml = `<script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{}}}</script>`;
-        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-            ok: true,
-            text: () => Promise.resolve(mockHtml),
-        }));
-        await expect(fetchPageProps('/podcast/abc')).rejects.toThrow('Resource not found');
-    });
-    it('throws on malformed JSON in __NEXT_DATA__', async () => {
-        const mockHtml = `<script id="__NEXT_DATA__" type="application/json">{broken json</script>`;
-        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-            ok: true,
-            text: () => Promise.resolve(mockHtml),
-        }));
-        await expect(fetchPageProps('/podcast/abc')).rejects.toThrow('Malformed __NEXT_DATA__');
-    });
-    it('handles multiline JSON in __NEXT_DATA__', async () => {
-        const mockHtml = `<script id="__NEXT_DATA__" type="application/json">
-{
-  "props": {
-    "pageProps": {
-      "episode": {"title": "Multiline Test"}
-    }
-  }
-}
-</script>`;
-        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-            ok: true,
-            text: () => Promise.resolve(mockHtml),
-        }));
-        const result = await fetchPageProps('/episode/abc');
-        expect(result).toEqual({ episode: { title: 'Multiline Test' } });
+    it('returns dash for undefined', () => {
+        expect(formatDate(undefined)).toBe('-');
     });
 });

package/clis/youtube/channel.js

@@ -115,6 +115,41 @@ cli({
           }
         }
 
+        // If Home tab has no videos, try Videos tab
+        if (recentVideos.length === 0) {
+          const videosTab = tabs.find(t => {
+            const tab = t.tabRenderer;
+            const url = tab?.endpoint?.commandMetadata?.webCommandMetadata?.url || '';
+            return tab?.tabIdentifier === 'VIDEOS'
+              || url.endsWith('/videos')
+              || tab?.title === 'Videos';
+          });
+          const videosTabParams = videosTab?.tabRenderer?.endpoint?.browseEndpoint?.params;
+          if (videosTabParams) {
+            const videosResp = await fetch('/youtubei/v1/browse?key=' + apiKey + '&prettyPrint=false', {
+              method: 'POST', credentials: 'include',
+              headers: {'Content-Type': 'application/json'},
+              body: JSON.stringify({context, browseId, params: videosTabParams})
+            });
+            if (videosResp.ok) {
+              const videosData = await videosResp.json();
+              const richGrid = videosData.contents?.twoColumnBrowseResultsRenderer?.tabs?.[0]?.tabRenderer?.content?.richGridRenderer?.contents || [];
+              for (const item of richGrid) {
+                if (recentVideos.length >= limit) break;
+                const v = item.richItemRenderer?.content?.videoRenderer;
+                if (v) {
+                  recentVideos.push({
+                    title: v.title?.runs?.[0]?.text || '',
+                    duration: v.lengthText?.simpleText || '',
+                    views: (v.shortViewCountText?.simpleText || '') + (v.publishedTimeText?.simpleText ? ' | ' + v.publishedTimeText.simpleText : ''),
+                    url: 'https://www.youtube.com/watch?v=' + v.videoId,
+                  });
+                }
+              }
+            }
+          }
+        }
+
         return {
           name: metadata.title || '',
           channelId: metadata.externalId || browseId,

package/clis/zsxq/dynamics.js

@@ -37,7 +37,7 @@ cli({
                 time: d.create_time || topic.create_time || '',
                 group: topic.group?.name || '',
                 author: getTopicAuthor(topic),
-                title: getTopicText(topic).slice(0, 120),
+                title: getTopicText(topic),
                 comments: topic.comments_count ?? 0,
                 likes: topic.likes_count ?? 0,
                 url: getTopicUrl(topic.topic_id),

package/clis/zsxq/utils.js

@@ -186,8 +186,11 @@ export function getTopicAuthor(topic) {
         '');
 }
 export function getTopicText(topic) {
+    const title = (topic.title || '').replace(/\s+/g, ' ').trim();
+    return title || getTopicContent(topic);
+}
+export function getTopicContent(topic) {
     const primary = [
-        topic.title,
         topic.talk?.text,
         topic.question?.text,
         topic.answer?.text,
@@ -218,8 +221,8 @@ export function toTopicRow(topic) {
         type: topic.type || '',
         group: topic.group?.name || '',
         author: getTopicAuthor(topic),
-        title: getTopicText(topic).slice(0, 120),
-        content: getTopicText(topic),
+        title: getTopicText(topic),
+        content: getTopicContent(topic),
         comments: topic.comments_count ?? comments.length ?? 0,
         likes: topic.likes_count ?? 0,
         readers: topic.readers_count ?? topic.reading_count ?? 0,

package/clis/zsxq/utils.test.js

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { getTopicText, toTopicRow } from './utils.js';
+
+describe('zsxq utils', () => {
+    it('keeps title and content separate when both fields exist', () => {
+        const topic = {
+            topic_id: '123',
+            title: 'A full title that should not be truncated',
+            talk: { text: 'This is the full body text.' },
+        };
+
+        expect(getTopicText(topic)).toBe('A full title that should not be truncated');
+        expect(toTopicRow(topic)).toMatchObject({
+            title: 'A full title that should not be truncated',
+            content: 'This is the full body text.',
+        });
+    });
+
+    it('falls back to body text for title when explicit title is absent', () => {
+        const topic = {
+            topic_id: '456',
+            talk: { text: 'Body-only topic text should still appear as the title preview.' },
+        };
+
+        expect(getTopicText(topic)).toBe('Body-only topic text should still appear as the title preview.');
+        expect(toTopicRow(topic)).toMatchObject({
+            title: 'Body-only topic text should still appear as the title preview.',
+            content: 'Body-only topic text should still appear as the title preview.',
+        });
+    });
+});

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

@@ -9,6 +9,16 @@
  * getCookies, screenshot, tabs, etc.
  */
 import type { BrowserCookie, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
+import { type ResolveOptions, type TargetMatchLevel } from './target-resolver.js';
+export interface ResolveSuccess {
+    matches_n: number;
+    /**
+     * Cascading stale-ref tier the resolver traversed. Callers surface this to
+     * agents so `stable` / `reidentified` hits are visibly distinct from a
+     * clean `exact` match — the page changed, the action still succeeded.
+     */
+    match_level: TargetMatchLevel;
+}
 export declare abstract class BasePage implements IPage {
     protected _lastUrl: string | null;
     /** Cached previous snapshot hashes for incremental diff marking */
@@ -33,13 +43,13 @@ export declare abstract class BasePage implements IPage {
     }): Promise<BrowserCookie[]>;
     abstract screenshot(options?: ScreenshotOptions): Promise<string>;
     abstract tabs(): Promise<unknown[]>;
-    abstract selectTab(index: number): Promise<void>;
-    click(ref: string): Promise<void>;
+    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>;
-    typeText(ref: string, text: string): Promise<void>;
+    typeText(ref: string, text: string, opts?: ResolveOptions): Promise<ResolveSuccess>;
     pressKey(key: string): Promise<void>;
-    scrollTo(ref: string): Promise<unknown>;
+    scrollTo(ref: string, opts?: ResolveOptions): Promise<unknown>;
     getFormState(): Promise<Record<string, unknown>>;
     scroll(direction?: string, amount?: number): Promise<void>;
     autoScroll(options?: {

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

@@ -10,8 +10,26 @@
  */
 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, scrollResolvedJs, } from './target-resolver.js';
 import { TargetError } from './target-errors.js';
+/**
+ * Execute `resolveTargetJs` once, throw structured `TargetError` on failure.
+ * Single helper so click/typeText/scrollTo share one resolution pathway,
+ * which is what the selector-first contract promises agents.
+ */
+async function runResolve(page, ref, opts = {}) {
+    const resolution = (await page.evaluate(resolveTargetJs(ref, opts)));
+    if (!resolution.ok) {
+        throw new TargetError({
+            code: resolution.code,
+            message: resolution.message,
+            hint: resolution.hint,
+            candidates: resolution.candidates,
+            matches_n: resolution.matches_n,
+        });
+    }
+    return { matches_n: resolution.matches_n, match_level: resolution.match_level };
+}
 import { formatSnapshot } from '../snapshotFormatter.js';
 export class BasePage {
     _lastUrl = null;
@@ -37,25 +55,20 @@ export class BasePage {
         return this.evaluate(`${declarations}\n${js}`);
     }
     // ── Shared DOM helper implementations ──
-    async click(ref) {
+    async click(ref, opts = {}) {
         // Phase 1: Resolve target with fingerprint verification
-        const resolution = await this.evaluate(resolveTargetJs(ref));
-        if (!resolution.ok) {
-            throw new TargetError(resolution);
-        }
+        const resolved = await runResolve(this, ref, opts);
         // Phase 2: Execute click on resolved element
         const result = await this.evaluate(clickResolvedJs());
-        // Backwards compat: old format returned 'clicked' string
         if (typeof result === 'string' || result == null)
-            return;
-        // JS click succeeded
+            return resolved;
         if (result.status === 'clicked')
-            return;
+            return resolved;
         // JS click failed — try CDP native click if coordinates available
         if (result.x != null && result.y != null) {
             const success = await this.tryNativeClick(result.x, result.y);
             if (success)
-                return;
+                return resolved;
         }
         throw new Error(`Click failed: ${result.error ?? 'JS click and CDP fallback both failed'}`);
     }
@@ -63,26 +76,23 @@ export class BasePage {
     async tryNativeClick(_x, _y) {
         return false;
     }
-    async typeText(ref, text) {
-        // Phase 1: Resolve target with fingerprint verification
-        const resolution = await this.evaluate(resolveTargetJs(ref));
-        if (!resolution.ok) {
-            throw new TargetError(resolution);
-        }
-        // Phase 2: Execute type on resolved element
+    async typeText(ref, text, opts = {}) {
+        const resolved = await runResolve(this, ref, opts);
         await this.evaluate(typeResolvedJs(text));
+        return resolved;
     }
     async pressKey(key) {
         await this.evaluate(pressKeyJs(key));
     }
-    async scrollTo(ref) {
-        // Phase 1: Resolve target with fingerprint verification
-        const resolution = await this.evaluate(resolveTargetJs(ref));
-        if (!resolution.ok) {
-            throw new TargetError(resolution);
+    async scrollTo(ref, opts = {}) {
+        const resolved = await runResolve(this, ref, opts);
+        const result = (await this.evaluate(scrollResolvedJs()));
+        // 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') {
+            return { ...result, matches_n: resolved.matches_n, match_level: resolved.match_level };
         }
-        // Phase 2: Scroll to resolved element
-        return this.evaluate(scrollResolvedJs());
+        return { matches_n: resolved.matches_n, match_level: resolved.match_level };
     }
     async getFormState() {
         return (await this.evaluate(getFormStateJs()));

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

@@ -15,6 +15,7 @@ export declare class BrowserBridge implements IBrowserFactory {
     connect(opts?: {
         timeout?: number;
         workspace?: string;
+        idleTimeout?: number;
     }): Promise<IPage>;
     close(): Promise<void>;
     private _ensureDaemon;

package/dist/src/browser/bridge.js

@@ -33,7 +33,7 @@ export class BrowserBridge {
         this._state = 'connecting';
         try {
             await this._ensureDaemon(opts.timeout);
-            this._page = new Page(opts.workspace);
+            this._page = new Page(opts.workspace, opts.idleTimeout);
             this._state = 'connected';
             return this._page;
         }

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

@@ -15,6 +15,7 @@ export interface CDPTarget {
     title?: string;
     webSocketDebuggerUrl?: string;
 }
+export declare const CDP_RESPONSE_BODY_CAPTURE_LIMIT: number;
 export declare class CDPBridge implements IBrowserFactory {
     private _ws;
     private _idCounter;

package/dist/src/browser/cdp.js

@@ -17,6 +17,12 @@ import { isRecord, saveBase64ToFile } from '../utils.js';
 import { getAllElectronApps } from '../electron-apps.js';
 import { BasePage } from './base-page.js';
 const CDP_SEND_TIMEOUT = 30_000;
+// Memory guard for in-process capture. The 4k cap we used to apply everywhere
+// silently truncated JSON so `JSON.parse` failed or gave partial objects — the
+// primary agent-facing bug. Now we keep the full body up to a large cap and
+// surface `responseBodyFullSize` + `responseBodyTruncated` so downstream layers
+// can tell the agent what happened instead of lying about the payload.
+export const CDP_RESPONSE_BODY_CAPTURE_LIMIT = 8 * 1024 * 1024;
 export class CDPBridge {
     _ws = null;
     _idCounter = 0;
@@ -240,9 +246,12 @@ class CDPPage extends BasePage {
                     const bodyFetch = this.bridge.send('Network.getResponseBody', { requestId: p.requestId }).then((result) => {
                         const r = result;
                         if (typeof r?.body === 'string') {
-                            this._networkEntries[idx].responsePreview = r.base64Encoded
-                                ? `base64:${r.body.slice(0, 4000)}`
-                                : r.body.slice(0, 4000);
+                            const fullSize = r.body.length;
+                            const truncated = fullSize > CDP_RESPONSE_BODY_CAPTURE_LIMIT;
+                            const body = truncated ? r.body.slice(0, CDP_RESPONSE_BODY_CAPTURE_LIMIT) : r.body;
+                            this._networkEntries[idx].responsePreview = r.base64Encoded ? `base64:${body}` : body;
+                            this._networkEntries[idx].responseBodyFullSize = fullSize;
+                            this._networkEntries[idx].responseBodyTruncated = truncated;
                         }
                     }).catch(() => {
                         // Body unavailable for some requests (e.g. uploads) — non-fatal
@@ -296,7 +305,7 @@ class CDPPage extends BasePage {
     async tabs() {
         return [];
     }
-    async selectTab(_index) {
+    async selectTab(_target) {
         // Not supported in direct CDP mode
     }
 }