dsh-browser-playwright-codex 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 Bilingual by intent: the version headings and the summary of each release are given in both
 languages, the individual entries follow the language the surrounding code and docs use.
 
+## 0.5.3
+
+一句话摘要：**源码按职责拆开、可维护性大幅提升，并修掉拆分过程中暴露的三处隐患** —— 对用户可见的行为零变化：工具面、配置接口、出厂默认值全部不动。本版同时修掉中文说明里一处会让人误判权限状态的过期说法。
+
+### Changed
+
+- 源码按职责拆开：`playwright.ts` **2,727 → 55 行**，只剩注册入口 `apply()` 与一张给来访者的模块地图；对外零变化（loader 三行、`package.json` exports、`lib/` 入口、工具面全都不动）。做法是"纯搬运、一次一个接缝"：每步 `npm test` + `npm run verify` + 解析一致性脚本全绿才提交，任何一步不绿就当场回退（过程中真回退过一次：拆 `tool.ts` 时用启发式切错边界，回退后改用 TypeScript 解析器取精确范围）。
+  - `provider.ts`（370 行）：profile/context 生命周期、会话注册、空闲回收、弹窗登记、标签记账。
+  - `session.ts`（668）：会话骨架 —— 持有 page/context，处理弹窗、截图、页面数据、evaluate/CDP，并把动作/快照/诊断转发给对应模块。
+  - `page-actions.ts`（786）：可点击性检查、点击（几何阶梯 + Playwright 兜底）、填充与写后核对、按键、悬停、滚动、前进后退、标签切换。
+  - `page-snapshot.ts`（335）：等页面稳定、兼容/智能两种采集、ref 签名与差异、ref 解析与存活校验。
+  - `page-diagnostics.ts`（198）：控制台消息、页面错误、网络请求的有界记录 + 失败原因归类。
+  - `page-probes.ts`（288）：会被序列化进浏览器的页内函数（铁律：必须自包含）。
+  - `window-focus.ts`（56）：承载窗口是否最小化、后台建标签 —— 只为了让窗口/标签不打扰用户。
+  - `browser-lifecycle.ts`（183）：启动/复用持久化 context、清理 Chrome 锁、启动与 profile 参数。
+  - `login-state.ts`（90）：登录态导出/恢复（窗口最小化读不到状态时只取 cookies）。
+  - `config.ts` / `url-policy.ts` / `challenge.ts` / `extract.ts` / `tool-types.ts` / `tool-schemas.ts` / `tool-render.ts`：配置与常量、URL 策略、人机验证识别、提取工具辅助、工具面类型/schema/渲染。
+- 12 个模块的文件说明与内容对齐（此前 6 处内容变了没改、5 处还留着拆分当天的占位文案）。
+
+### Fixed
+
+- **入口子路径恢复 `Config` 导出**（`./playwright`）：拆分时 schema 被搬进 `config.ts` 而入口忘了转出 —— Cordis 因此不会补默认值，而配置块里没有 `snapshot`，provider 又直接读 `config.snapshot.engine`，**下次重启就起不来**。该回归只存在于 main、从未随版本发布。现已补上入口契约测试：从 `src` 与 `lib` 两条路检查导出、校验 schema 补出默认值、复现"不含 `snapshot` 的 profile 配置"这一故障场景，并断言 `lib/` 与 `src/` 行为一致（防漂移）。
+- **页内探测守卫覆盖不到 `hitTest`**：它原本是 `resolveClickPoint` 里的嵌套命名函数（同样会被 `keepNames` 改写成 `__name`），现已搬进 `page-probes.ts`；守卫从"手写 4 个函数"改成**枚举该模块所有函数导出**（并断言至少 5 个，避免空跑）。
+- **中文说明写明两个闸门出厂关闭**：原文写"本包自带的 bundle 层是… `allowEvaluate`/`allowCdp` 打开"，与出厂 `false`/`false` 矛盾，读者会以为"页面任意 JS / 原始 CDP"默认可用。现在写明出厂关闭并指向 §4.6。
+- **文档守卫补洞**：原规则要求行内出现 `: true|false`，而措辞检查写在这个提前返回**之后** → "…`allowCdp` 打开"这类写法永远走不进检查。现改为两条带邻近性的规则；负向自检三种坏写法全部被抓住，且 `SECURITY.md` 里那句合法表述不被误报。
+- **新增两条守卫**：模块文件说明不得留下拆分脚本的占位文案；页内函数必须自包含（第 5 个函数 `hitTest` 因此归位）。
+- **测试的导航预算 2500ms → 15s**：冷启动的 windows runner 连加载本机 fixture 页都超时（`page.goto: Timeout 2500ms exceeded`），一次挂掉 4 条与超时无关的用例；没有任何测试断言导航超时行为，journeys 另有 25s 兜底。
+- **拆分过程中暴露的 3 处隐患**：`WeakMap<Request>` 实际落在浏览器内置的 DOM `Request`（两个类型身份）、`provider.ts` ⇄ `session.ts` 的**运行时**循环依赖（多个测试文件直接加载失败，用例从 119 掉到 46）、测试与脚本仍在旧路径引用搬走的符号。
+- 清掉搬迁后残留的未使用 import/参数（以 `tsc --noUnusedLocals --noUnusedParameters` 为裁判，28 处 → 0）。
+
 ## 0.5.2
 
 一句话摘要：**查出 Windows CI 抖动的真正根因并修掉**—— 测试用的转译器 tsx/esbuild 会开启 `keepNames`，把"要送进浏览器执行"的页内函数里的**命名内部函数**改写成 `__name(fn, "名字")`，而 `__name` 只存在于模块作用域、页面里没有 → 探测每次抛 `ReferenceError`，且被 `catch` 吞成无声的 `unreachable`。后果是**几何点击路径从来没工作过**：所有点击都退化成 Playwright 兜底点击（上限 3 秒），慢速 Windows runner 一超时，就把几何路径那句**误导性**的错误抛了出来。

package/lib/browser-lifecycle.d.ts

@@ -0,0 +1,12 @@
+import type { PlaywrightProvider } from './provider.ts';
+/**
+ * Ensure the shared persistent context is alive (persistent mode). A
+ * profile-backed window is launched once and reused until closed by the
+ * last owner, idle disposal, or an external close; login state lives in
+ * the profile plus the exported state file, so reopening is seamless.
+ */
+export declare function ensureContext(provider: PlaywrightProvider): Promise<import("playwright-core").BrowserContext>;
+/** Remove stale Chrome singleton lock files inside the profile directory. */
+export declare function clearChromeLocks(provider: PlaywrightProvider): Promise<void>;
+/** Launch the browser once, probing the configured or auto-detected channel. */
+export declare function ensureBrowser(provider: PlaywrightProvider): Promise<import("playwright-core").Browser>;

package/lib/browser-lifecycle.js

@@ -0,0 +1,186 @@
+/**
+ * 浏览器的生命：启动/复用持久化 context、清理 Chrome 锁、以及启动与 profile 相关参数。
+ * 窗口**焦点**行为（承载窗口是否最小化、要不要在后台建标签）在 window-focus.ts。
+ * @module dsh-browser-playwright-codex/browser-lifecycle
+ */
+import { chromium } from 'playwright-core';
+import path from 'node:path';
+import fs from 'node:fs';
+import { AUTO_CHANNELS, HUMANIZED_LAUNCH } from "./config.js";
+import { SNAPSHOT_SCRIPT } from "./injected.js";
+import { BrowserError, launchFailed } from "./errors.js";
+/**
+ * Ensure the shared persistent context is alive (persistent mode). A
+ * profile-backed window is launched once and reused until closed by the
+ * last owner, idle disposal, or an external close; login state lives in
+ * the profile plus the exported state file, so reopening is seamless.
+ */
+export async function ensureContext(provider) {
+    if (provider.context !== undefined) {
+        try {
+            const browser = provider.context.browser();
+            if (browser !== null && browser.isConnected())
+                return provider.context;
+        }
+        catch {
+            /* context died underneath us: relaunch */
+        }
+        provider.context = undefined;
+    }
+    fs.mkdirSync(provider.profileDir, { recursive: true });
+    const { executablePath, channel, headless } = provider.config.launch;
+    const headful = !headless;
+    const attempts = [];
+    const baseOptions = {
+        headless,
+        // Headful windows must render like a normal Chrome the user opened
+        // by hand: the page viewport equals the real window size and the
+        // system DPI scaling (e.g. 150%) is honoured. Playwright's default
+        // is the opposite — it pins every page to a fixed CSS viewport at
+        // deviceScaleFactor 1 via Emulation.setDeviceMetricsOverride, which
+        // on scaled displays overflows the window: content looks zoomed in
+        // and clipped. viewport: null disables that override entirely.
+        // Headless mode keeps the fixed viewport (no window to track).
+        ...(headless ? { viewport: provider.config.launch.viewport } : { viewport: null }),
+        ignoreHTTPSErrors: provider.config.launch.ignoreHTTPSErrors,
+        ...HUMANIZED_LAUNCH,
+        args: [
+            '--no-first-run',
+            '--no-default-browser-check',
+            // Open maximised like a human would, so the first paint fills
+            // the screen instead of a small default window.
+            ...(headful ? ['--start-maximized'] : []),
+            ...HUMANIZED_LAUNCH.args,
+        ],
+    };
+    const start = async (extra) => {
+        try {
+            provider.context = await chromium.launchPersistentContext(provider.profileDir, { ...baseOptions, ...extra });
+        }
+        catch (error) {
+            // A stale Chrome singleton lock from a dirty shutdown breaks a
+            // relaunch into the same profile; clear the lock files and
+            // retry once before surfacing the failure.
+            if (error instanceof Error && /user data directory|SingletonLock|ProcessSingleton/i.test(error.message)) {
+                await provider.clearChromeLocks();
+                provider.context = await chromium.launchPersistentContext(provider.profileDir, { ...baseOptions, ...extra });
+            }
+            else {
+                throw error;
+            }
+        }
+        const ctx = provider.context;
+        // External close (user closed the window, crash): forget every
+        // session handle bound to this context; the next acquire relaunches.
+        void ctx.on('close', () => {
+            if (provider.context !== ctx)
+                return;
+            provider.context = undefined;
+            for (const [key, entry] of [...provider.entries]) {
+                if (entry.context !== ctx)
+                    continue;
+                if (entry.timer !== undefined)
+                    clearTimeout(entry.timer);
+                provider.entries.delete(key);
+            }
+        });
+        ctx.on('page', (page) => provider.armDialogGuard(page));
+        try {
+            await provider.restoreState(ctx);
+        }
+        catch {
+            /* malformed state file must not block startup */
+        }
+        await ctx.addInitScript(SNAPSHOT_SCRIPT);
+        // The initial blank page predates addInitScript: reload so the
+        // snapshot engine and restored localStorage apply on first use.
+        for (const page of ctx.pages()) {
+            await page.reload({ waitUntil: 'domcontentloaded' }).catch(() => { });
+        }
+        return ctx;
+    };
+    if (executablePath !== undefined) {
+        try {
+            return await start({ executablePath });
+        }
+        catch (error) {
+            provider.launchError = error;
+            attempts.push('executablePath ' + executablePath);
+        }
+    }
+    else {
+        const channels = channel !== undefined && channel !== '' ? [channel] : [...AUTO_CHANNELS];
+        for (const candidate of channels) {
+            try {
+                return await start({ channel: candidate });
+            }
+            catch (error) {
+                provider.launchError = error;
+                attempts.push('channel ' + candidate);
+            }
+        }
+    }
+    const hint = 'Tried: ' +
+        attempts.join(', ') +
+        '. ' +
+        'Install a Chromium-family browser, or run: npx playwright-core install chromium ' +
+        '(in restricted networks set PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright), ' +
+        'or configure launch.channel / launch.executablePath.';
+    if (provider.launchError instanceof Error &&
+        /executable doesn't exist|not found/i.test(provider.launchError.message)) {
+        throw new BrowserError('NO_BROWSER', hint);
+    }
+    throw launchFailed(provider.launchError);
+}
+/** Remove stale Chrome singleton lock files inside the profile directory. */
+export async function clearChromeLocks(provider) {
+    for (const lock of ['SingletonLock', 'SingletonCookie', 'SingletonSocket']) {
+        try {
+            fs.rmSync(path.join(provider.profileDir, lock), { force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+/** Launch the browser once, probing the configured or auto-detected channel. */
+export async function ensureBrowser(provider) {
+    if (provider.browser !== undefined)
+        return provider.browser;
+    const { executablePath, channel, headless } = provider.config.launch;
+    const attempts = [];
+    if (executablePath !== undefined) {
+        try {
+            provider.browser = await chromium.launch({ executablePath, headless, ...HUMANIZED_LAUNCH });
+            return provider.browser;
+        }
+        catch (error) {
+            provider.launchError = error;
+            attempts.push('executablePath ' + executablePath);
+        }
+    }
+    else {
+        const channels = channel !== undefined && channel !== '' ? [channel] : [...AUTO_CHANNELS];
+        for (const candidate of channels) {
+            try {
+                provider.browser = await chromium.launch({ channel: candidate, headless, ...HUMANIZED_LAUNCH });
+                return provider.browser;
+            }
+            catch (error) {
+                provider.launchError = error;
+                attempts.push('channel ' + candidate);
+            }
+        }
+    }
+    const hint = 'Tried: ' +
+        attempts.join(', ') +
+        '. ' +
+        'Install a Chromium-family browser, or run: npx playwright-core install chromium ' +
+        '(in restricted networks set PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright), ' +
+        'or configure launch.channel / launch.executablePath.';
+    if (provider.launchError instanceof Error &&
+        /executable doesn't exist|not found/i.test(provider.launchError.message)) {
+        throw new BrowserError('NO_BROWSER', hint);
+    }
+    throw launchFailed(provider.launchError);
+}

package/lib/challenge.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 人机验证页识别：从快照里判断是否撞上 Cloudflare 之类的挑战页，并给出对应的提示文案。
+ * @module dsh-browser-playwright-codex/challenge
+ */
+import type { ChallengeMatch, ChallengeSnapshot } from './tool-types.ts';
+/**
+ * Detect anti-bot / human-verification challenge pages (Cloudflare
+ * interstitial, Turnstile, reCAPTCHA-style) from a snapshot's title, url and
+ * visible text. We do NOT try to solve them: the correct move for an agent is
+ * to hand the challenge to the human who can see the open window. Returns the
+ * engine name when matched, else null. Matching is conservative to avoid
+ * false positives on ordinary pages.
+ */
+export declare function detectChallenge(snapshot: ChallengeSnapshot): ChallengeMatch | null;
+/**
+ * Instruction appended above a snapshot when the page is an anti-bot
+ * challenge. The browser window is visible on the user's desktop: the agent
+ * should pause and ask the user to complete it by hand, then re-snapshot.
+ */
+export declare const CHALLENGE_NOTE = "[human verification] The page triggered an anti-bot challenge; it is NOT solvable by automation and must NOT be retried blindly. The browser window is open on the user's desktop \u2014 tell the user a verification appeared, wait for them to finish it (a few seconds), then call browser_snapshot again. The clearance cookie is saved to the profile automatically and keeps working for the session.";

package/lib/challenge.js

@@ -0,0 +1,40 @@
+/**
+ * Detect anti-bot / human-verification challenge pages (Cloudflare
+ * interstitial, Turnstile, reCAPTCHA-style) from a snapshot's title, url and
+ * visible text. We do NOT try to solve them: the correct move for an agent is
+ * to hand the challenge to the human who can see the open window. Returns the
+ * engine name when matched, else null. Matching is conservative to avoid
+ * false positives on ordinary pages.
+ */
+export function detectChallenge(snapshot) {
+    const title = snapshot.title ?? '';
+    const url = snapshot.url ?? '';
+    const parts = [];
+    const walk = (nodes, depth) => {
+        for (const node of nodes) {
+            if (parts.length >= 60)
+                return;
+            if (node.name !== undefined && node.name !== '')
+                parts.push(node.name);
+            if (depth < 2 && node.children !== undefined && node.children.length > 0)
+                walk(node.children, depth + 1);
+        }
+    };
+    walk(snapshot.nodes ?? [], 0);
+    const text = [title, url, ...parts].join(' | ').slice(0, 900);
+    const saidCaptcha = parts.some((name) => /(captcha|turnstile|recaptcha|hcaptcha)/i.test(name));
+    if (/just a moment|attention required|checking (your )?browser|cf-chl-|请稍候|验证你的浏览器/i.test(text))
+        return { engine: 'Cloudflare', hint: 'Cloudflare is challenging the browser before letting the page load' };
+    if (/verify (you are|you're|that you are) (a )?human|人机验证|验证您(是|为)人类/i.test(text))
+        return { engine: 'human-verification', hint: 'the page is asking to verify a human visitor' };
+    if (/(captcha|turnstile|recaptcha|hcaptcha)/i.test(text) &&
+        (saidCaptcha || /(captcha|turnstile|recaptcha)/i.test(title)))
+        return { engine: 'captcha', hint: 'the page embedded a captcha-style challenge' };
+    return null;
+}
+/**
+ * Instruction appended above a snapshot when the page is an anti-bot
+ * challenge. The browser window is visible on the user's desktop: the agent
+ * should pause and ask the user to complete it by hand, then re-snapshot.
+ */
+export const CHALLENGE_NOTE = "[human verification] The page triggered an anti-bot challenge; it is NOT solvable by automation and must NOT be retried blindly. The browser window is open on the user's desktop — tell the user a verification appeared, wait for them to finish it (a few seconds), then call browser_snapshot again. The clearance cookie is saved to the profile automatically and keeps working for the session.";

package/lib/config.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 插件配置与常量：schema、启动参数、通道白名单、ref 形态。
+ * @module dsh-browser-playwright-codex/config
+ */
+import z from '@deepseek-ai/schemastery';
+/** Schemastery validation for {@link PlaywrightConfig}. */
+/** Launch configuration for the Playwright provider. */
+export interface PlaywrightConfig {
+    launch: {
+        /** Absolute path to a Chromium-family binary; takes precedence over channel. */
+        executablePath?: string;
+        /** Browser channel: chromium, chrome, msedge. Omitted = auto-detect in that order. */
+        channel?: string;
+        /** Run headful so the user can watch and rescue the browser by hand. */
+        headless: boolean;
+        /** Persistent mode: one shared profile-backed window whose login survives. */
+        persistent: boolean;
+        /** Profile directory for persistent mode; empty means ~/.dsh/browser-profiles/playwright. */
+        profileDir: string;
+        viewport: {
+            width: number;
+            height: number;
+        };
+        /** Per-action navigation/click timeout in milliseconds. */
+        navigationTimeoutMs: number;
+        /** Ignore HTTPS certificate errors. */
+        ignoreHTTPSErrors: boolean;
+    };
+    /** Host suffixes the browser may visit. Empty = any http(s) host. */
+    allowedDomains?: string[];
+    /** Close an idle session's browser context after this many milliseconds. 0 disables. */
+    idleTimeoutMs: number;
+    /** Maximum concurrent browser contexts; acquiring beyond it evicts the least recently used. */
+    maxSessions: number;
+    snapshot: {
+        /** 'legacy' keeps the injected DOM walker; 'aria' uses the official ariaSnapshot(mode:'ai') engine. */
+        engine: 'legacy' | 'aria';
+        maxNodes: number;
+        maxNameLength: number;
+        maxTextLength: number;
+        /** Incremental ref-diff mode; false = always full snapshots (zero behavioral change). */
+        diff: boolean;
+    };
+}
+/** Bounded page data the extraction consumer feeds to a model. */
+export interface PageData {
+    readonly url: string;
+    readonly title: string;
+    readonly text: string;
+    readonly truncated: boolean;
+    readonly links: readonly {
+        readonly text: string;
+        readonly href: string;
+    }[];
+    readonly inputs: readonly {
+        readonly tag: string;
+        readonly type: string;
+        readonly name: string;
+        readonly value: string;
+        readonly label: string;
+        readonly checked: boolean | null;
+    }[];
+}
+/** Schemastery validation for {@link PlaywrightConfig}. */
+export declare const Config: z<PlaywrightConfig>;
+/** Channels probed in order when none is configured. */
+export declare const AUTO_CHANNELS: string[];
+/**
+ * Launch flags that strip Playwright's obvious automation markers (anti-bot
+ * detection layer L1). --enable-automation is what sets navigator.webdriver
+ * and the "controlled by automated test software" infobar; dropping it plus
+ * --disable-blink-features=AutomationControlled makes the browser present as
+ * a plain real Chrome, which it is. No fingerprint spoofing is added: real
+ * Chrome's own values are consistent by construction (spoofing would invent
+ * a device that never existed and draw MORE suspicion).
+ */
+export declare const HUMANIZED_LAUNCH: {
+    ignoreDefaultArgs: string[];
+    args: string[];
+};
+export declare const REF_PATTERN: RegExp;

package/lib/config.js

@@ -0,0 +1,61 @@
+/**
+ * 插件配置与常量：schema、启动参数、通道白名单、ref 形态。
+ * @module dsh-browser-playwright-codex/config
+ */
+import z from '@deepseek-ai/schemastery';
+/** Schemastery validation for {@link PlaywrightConfig}. */
+export const Config = z.object({
+    launch: z.object({
+        executablePath: z.string(),
+        channel: z.string(),
+        // Visible window by default: the agent drives a browser the user can
+        // watch and rescue by hand (login, captcha, dialogs).
+        headless: z.boolean().default(false),
+        // Persistent context mode: one shared profile-backed window whose
+        // login state survives close/reopen. false = legacy launch() mode.
+        persistent: z.boolean().default(true),
+        // Profile directory for persistent mode. Empty = ~/.dsh/browser-profiles/playwright.
+        profileDir: z.string().default(''),
+        // Headless only: a headful window must behave like a normal Chrome the
+        // user opened by hand, so the fixed CSS viewport is ignored there (see
+        // ensureContext) and the page tracks the real window size instead.
+        viewport: z
+            .object({ width: z.number().default(1280), height: z.number().default(800) })
+            .default({ width: 1280, height: 800 }),
+        navigationTimeoutMs: z.number().default(30000),
+        ignoreHTTPSErrors: z.boolean().default(false),
+    }),
+    allowedDomains: z.array(z.string()),
+    idleTimeoutMs: z.number().default(600000),
+    maxSessions: z.number().default(8),
+    snapshot: z
+        .object({
+        // 'legacy' keeps the injected DOM walker as the default: existing
+        // tests, verify and every consumer see byte-identical snapshots until
+        // a caller opts into the aria engine.
+        engine: z.union([z.const('legacy'), z.const('aria')]).default('legacy'),
+        maxNodes: z.number().default(500),
+        maxNameLength: z.number().default(120),
+        maxTextLength: z.number().default(300),
+        // diff=false keeps every return path a full snapshot: zero behavioral
+        // change unless a caller explicitly turns the incremental mode on.
+        diff: z.boolean().default(false),
+    })
+        .default({ engine: 'legacy', maxNodes: 500, maxNameLength: 120, maxTextLength: 300, diff: false }),
+});
+/** Channels probed in order when none is configured. */
+export const AUTO_CHANNELS = ['chromium', 'chrome', 'msedge', 'edge'];
+/**
+ * Launch flags that strip Playwright's obvious automation markers (anti-bot
+ * detection layer L1). --enable-automation is what sets navigator.webdriver
+ * and the "controlled by automated test software" infobar; dropping it plus
+ * --disable-blink-features=AutomationControlled makes the browser present as
+ * a plain real Chrome, which it is. No fingerprint spoofing is added: real
+ * Chrome's own values are consistent by construction (spoofing would invent
+ * a device that never existed and draw MORE suspicion).
+ */
+export const HUMANIZED_LAUNCH = {
+    ignoreDefaultArgs: ['--enable-automation'],
+    args: ['--disable-blink-features=AutomationControlled'],
+};
+export const REF_PATTERN = /^e[0-9]+$/;

package/lib/extract.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 提取工具的辅助：容错地解析模型返回的 JSON，以及为提取请求拼装提示词。
+ * @module dsh-browser-playwright-codex/extract
+ */
+import type { JsonValue } from './tool-types.ts';
+/** Strip markdown fences and whitespace, then parse one JSON document. */
+export declare function parseJsonText(raw: string): JsonValue;
+/**
+ * Prompt template for structured page extraction. `maxInputChars` bounds the page
+ * data handed to the auxiliary model — that model is billed on this prompt, so an
+ * unbounded page is a tax on every extraction.
+ */
+export declare function extractionPrompt(instruction: string, data: unknown, maxInputChars: number): string;

package/lib/extract.js

@@ -0,0 +1,34 @@
+/** Strip markdown fences and whitespace, then parse one JSON document. */
+export function parseJsonText(raw) {
+    let text = raw.trim();
+    const fenced = /^\s*```(?:json)?\s*([\s\S]*?)```\s*$/.exec(text);
+    if (fenced !== null) {
+        const inner = fenced[1];
+        if (inner !== undefined)
+            text = inner.trim();
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error('browser_extract: the model output is not valid JSON: ' + text.slice(0, 500));
+    }
+}
+/**
+ * Prompt template for structured page extraction. `maxInputChars` bounds the page
+ * data handed to the auxiliary model — that model is billed on this prompt, so an
+ * unbounded page is a tax on every extraction.
+ */
+export function extractionPrompt(instruction, data, maxInputChars) {
+    const page = JSON.stringify(data);
+    const bounded = page.length > maxInputChars
+        ? page.slice(0, maxInputChars) + ' [page data truncated at ' + String(maxInputChars) + ' characters]'
+        : page;
+    return ('Extract the following from the page data according to the instruction. ' +
+        'Answer with ONLY one valid JSON value (object, array, or scalar), no prose, no markdown fences.\n\n' +
+        'Instruction: ' +
+        instruction +
+        '\n\n' +
+        'Page data (JSON):\n' +
+        bounded);
+}

package/lib/index.d.ts

@@ -14,7 +14,9 @@ export { SNAPSHOT_SCRIPT } from './injected.ts';
 export type { SnapshotOptions, PageDataOptions } from './injected.ts';
 export { default as BrowserRuntime } from './service.ts';
 export type { BrowserRuntimeConfig } from './service.ts';
-export { PlaywrightProvider, assertAllowedUrl, Config as PlaywrightConfigSchema } from './playwright.ts';
-export type { PlaywrightConfig, PageData } from './playwright.ts';
+export { PlaywrightProvider } from './provider.ts';
+export { assertAllowedUrl } from './url-policy.ts';
+export { Config as PlaywrightConfigSchema } from './config.ts';
+export type { PlaywrightConfig, PageData } from './config.ts';
 export type { BrowserNode, BrowserProvider, BrowserSession, BrowserSnapshot, LoadState, ScreenshotCapture, TabInfo, } from './types.ts';
 export type { ToolConfig } from './tool.ts';

package/lib/index.js

@@ -9,4 +9,6 @@ export { ALWAYS_ON_SUFFIXES, ERROR_CODES, GATED_SUFFIXES, TOOL_SUFFIXES, registe
 export { CallId, toolCallId } from "./compat.js";
 export { SNAPSHOT_SCRIPT } from "./injected.js";
 export { default as BrowserRuntime } from "./service.js";
-export { PlaywrightProvider, assertAllowedUrl, Config as PlaywrightConfigSchema } from "./playwright.js";
+export { PlaywrightProvider } from "./provider.js";
+export { assertAllowedUrl } from "./url-policy.js";
+export { Config as PlaywrightConfigSchema } from "./config.js";

package/lib/login-state.d.ts

@@ -0,0 +1,10 @@
+import type { BrowserContext } from 'playwright-core';
+import type { PlaywrightProvider } from './provider.ts';
+/** Export the login-state fallback to the state file (session-cookie fallback). */
+export declare function persistState(provider: PlaywrightProvider, context: BrowserContext): Promise<void>;
+/**
+ * Re-inject a previously exported state. Durable cookies already live in
+ * the profile; this covers session cookies the browser drops on close and
+ * localStorage entries, so logins survive window close/reopen.
+ */
+export declare function restoreState(provider: PlaywrightProvider, context: BrowserContext): Promise<void>;

package/lib/login-state.js

@@ -0,0 +1,83 @@
+/**
+ * 登录态持久化：把 profile 的 cookies+localStorage 导出到状态文件、并在重开时恢复；
+ * 窗口最小化或读不到窗口状态时只取 cookies。
+ * @module dsh-browser-playwright-codex/login-state
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Export the login-state fallback to the state file (session-cookie fallback). */
+export async function persistState(provider, context) {
+    if (provider.stateFile === undefined || context === undefined)
+        return;
+    try {
+        const state = await provider.collectLoginState(context);
+        const tmp = provider.stateFile + '.tmp';
+        fs.mkdirSync(path.dirname(provider.stateFile), { recursive: true });
+        fs.writeFileSync(tmp, JSON.stringify(state));
+        fs.renameSync(tmp, provider.stateFile);
+        provider.lastStatePersist = Date.now();
+    }
+    catch {
+        /* best-effort: the profile itself already holds durable cookies */
+    }
+}
+/**
+ * Re-inject a previously exported state. Durable cookies already live in
+ * the profile; this covers session cookies the browser drops on close and
+ * localStorage entries, so logins survive window close/reopen.
+ */
+export async function restoreState(provider, context) {
+    if (provider.stateFile === undefined)
+        return;
+    let state;
+    try {
+        state = JSON.parse(fs.readFileSync(provider.stateFile, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    if (state === null || typeof state !== 'object')
+        return;
+    const cookies = Array.isArray(state.cookies)
+        ? state.cookies.filter((c) => c !== null &&
+            typeof c === 'object' &&
+            typeof c.name === 'string' &&
+            c.value !== undefined &&
+            typeof c.domain === 'string')
+        : [];
+    if (cookies.length > 0) {
+        await context.addCookies(cookies.map((c) => ({
+            name: c.name,
+            value: c.value,
+            domain: c.domain,
+            path: typeof c.path === 'string' && c.path !== '' ? c.path : '/',
+            ...(typeof c.expires === 'number' && c.expires > 0 ? { expires: c.expires } : {}),
+            ...(typeof c.httpOnly === 'boolean' ? { httpOnly: c.httpOnly } : {}),
+            ...(typeof c.secure === 'boolean' ? { secure: c.secure } : {}),
+            ...(typeof c.sameSite === 'string' ? { sameSite: c.sameSite } : {}),
+        })));
+    }
+    const origins = Array.isArray(state.origins)
+        ? state.origins.filter((o) => o !== null &&
+            typeof o === 'object' &&
+            typeof o.origin === 'string' &&
+            Array.isArray(o.localStorage) &&
+            o.localStorage.length > 0)
+        : [];
+    if (origins.length > 0) {
+        await context.addInitScript(({ rows }) => {
+            for (const o of rows) {
+                if (location.origin !== o.origin)
+                    continue;
+                for (const kv of o.localStorage) {
+                    try {
+                        localStorage.setItem(kv.name, kv.value);
+                    }
+                    catch {
+                        /* quota / privacy mode */
+                    }
+                }
+            }
+        }, { rows: origins });
+    }
+}