dsh-browser-playwright-codex 0.7.2 → 0.7.5

package/lib/errors.js

@@ -19,3 +19,19 @@ export function launchFailed(cause) {
     const detail = cause instanceof Error ? cause.message : String(cause);
     return new BrowserError('BROWSER_LAUNCH_FAILED', 'failed to launch the browser: ' + detail);
 }
+/**
+ * "browser_evaluate is switched off". One wording, thrown by both layers that
+ * enforce it: the tool layer (before a browser is even launched) and the
+ * session itself (so a programmatic caller cannot go around the switch).
+ * @returns the denial, ready to throw.
+ */
+export function evaluateDisabled() {
+    return new BrowserError('EVALUATE_DISABLED', 'browser_evaluate is disabled; set allowEvaluate: true on the browser-tool plugin to enable arbitrary page JavaScript');
+}
+/**
+ * "browser_cdp is switched off". Same two-layer rule as {@link evaluateDisabled}.
+ * @returns the denial, ready to throw.
+ */
+export function cdpDisabled() {
+    return new BrowserError('CDP_DISABLED', 'browser_cdp is disabled; set allowCdp: true on the browser-tool plugin to enable raw CDP inspection commands');
+}

package/lib/index.d.ts

@@ -4,7 +4,7 @@
  * session-scoped browser contexts, screenshots as attachments.
  * @module dsh-browser-playwright-codex
  */
-export { BrowserError, launchFailed } from './errors.ts';
+export { BrowserError, cdpDisabled, evaluateDisabled, launchFailed } from './errors.ts';
 export type { BrowserErrorCode } from './errors.ts';
 export { ALWAYS_ON_SUFFIXES, ERROR_CODES, GATED_SUFFIXES, TOOL_SUFFIXES, registeredSuffixes, registeredToolNames, toolNames, } from './contract.ts';
 export type { ToolSuffix, ToolSurfaceConfig } from './contract.ts';
@@ -15,7 +15,9 @@ export type { SnapshotOptions, PageDataOptions } from './injected.ts';
 export { default as BrowserRuntime } from './service.ts';
 export type { BrowserRuntimeConfig } from './service.ts';
 export { PlaywrightProvider } from './provider.ts';
-export { assertAllowedUrl } from './url-policy.ts';
+export { assertAllowedUrl, isHostAllowed } from './url-policy.ts';
+export { installHostGuard } from './navigation-guard.ts';
+export type { BlockedRequest } from './navigation-guard.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';

package/lib/index.js

@@ -4,13 +4,14 @@
  * session-scoped browser contexts, screenshots as attachments.
  * @module dsh-browser-playwright-codex
  */
-export { BrowserError, launchFailed } from "./errors.js";
+export { BrowserError, cdpDisabled, evaluateDisabled, launchFailed } from "./errors.js";
 export { ALWAYS_ON_SUFFIXES, ERROR_CODES, GATED_SUFFIXES, TOOL_SUFFIXES, registeredSuffixes, registeredToolNames, toolNames, } from "./contract.js";
 export { CallId, toolCallId } from "./compat.js";
 export { SNAPSHOT_SCRIPT } from "./injected.js";
 export { default as BrowserRuntime } from "./service.js";
 export { PlaywrightProvider } from "./provider.js";
-export { assertAllowedUrl } from "./url-policy.js";
+export { assertAllowedUrl, isHostAllowed } from "./url-policy.js";
+export { installHostGuard } from "./navigation-guard.js";
 export { Config as PlaywrightConfigSchema } from "./config.js";
 // Single loader row (2026-10-19): the package root is the plugin. The three
 // sub-entries below stay importable, but the loader mounts this one.

package/lib/navigation-guard.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 白名单的网络层守卫：把「只能访问这些站点」变成**路上的一道闸**，而不是只在调用入口
+ * 打一次勾。
+ *
+ * 起因（2026-10-26 实测）：入口检查只覆盖 navigate / 点击带 href 的链接 / 切标签 / 开标签。
+ * 页面自己 `location.href = 'http://别的站点'`、meta refresh、302 跳转、表单提交，全都
+ * 绕过白名单——实测把名单设成 `127.0.0.1` 后，页面脚本一跳就落在了 `localhost` 上。
+ * 入口检查在这里永远追不上：那些导航不是插件发起的。
+ *
+ * 做法：接管这个 context 的每一条请求（context.route），按主机名判定。
+ *   - **文档请求**（导航、iframe）：不在名单里 → 掐断，并记下来。调用方在动作收尾时
+ *     用它把「我点了但页面没动」变成一条明确的 URL_NOT_ALLOWED，而不是一次静默。
+ *   - **数据请求**（xhr / fetch / eventsource）：不在名单里 → 掐断。页面脚本不该拿着
+ *     这个浏览器的身份去白名单外的站点取数据。
+ *   - 其余子资源（script / img / css / font / media）：放行。它们几乎是页面渲染的刚需
+ *     （CDN、头像、字体），且不带目标站点的凭据；拦掉只会让页面看起来是坏的。
+ *
+ * 只在配置了名单时才接管：空名单的语义是「任意站点」，此时接管路由纯属拖慢每一页
+ * （Playwright 的路由会关掉 HTTP 缓存）。
+ *
+ * @module dsh-browser-playwright-codex/navigation-guard
+ */
+import type { BrowserContext } from 'playwright-core';
+/** One request the guard refused, in the shape callers report it. */
+export interface BlockedRequest {
+    /** Full requested URL. */
+    url: string;
+    /** Hostname that was not in the allow-list. */
+    host: string;
+    /** Playwright resourceType: document, xhr, script, … */
+    resourceType: string;
+    /** True for a navigation-level block (a document request). */
+    document: boolean;
+    /** Epoch milliseconds. */
+    at: number;
+}
+/**
+ * Refuse every request to a host outside the allow-list for one context.
+ *
+ * Installed once per context, before the first navigation. When the configured
+ * list is empty nothing is installed: "any host" must not pay the routing cost.
+ * @param context - the context to guard.
+ * @param allowedDomains - reads the live allow-list.
+ * @param onBlocked - called for each refused request; the caller keeps the last
+ *   document-level block and turns it into an error for the action that caused it.
+ * @returns true when a guard was installed, false when the list is empty.
+ */
+export declare function installHostGuard(context: BrowserContext, allowedDomains: () => readonly string[], onBlocked: (blocked: BlockedRequest) => void): Promise<boolean>;

package/lib/navigation-guard.js

@@ -0,0 +1,48 @@
+import { isHostAllowed } from "./url-policy.js";
+/** Resource types that carry data off the page and are refused outside the allow-list. */
+const DATA_RESOURCE_TYPES = new Set(['xhr', 'fetch', 'eventsource']);
+/**
+ * Refuse every request to a host outside the allow-list for one context.
+ *
+ * Installed once per context, before the first navigation. When the configured
+ * list is empty nothing is installed: "any host" must not pay the routing cost.
+ * @param context - the context to guard.
+ * @param allowedDomains - reads the live allow-list.
+ * @param onBlocked - called for each refused request; the caller keeps the last
+ *   document-level block and turns it into an error for the action that caused it.
+ * @returns true when a guard was installed, false when the list is empty.
+ */
+export async function installHostGuard(context, allowedDomains, onBlocked) {
+    const domains = allowedDomains();
+    if (domains.length === 0)
+        return false;
+    await context.route('**/*', async (route) => {
+        const request = route.request();
+        let host;
+        try {
+            host = new URL(request.url()).hostname;
+        }
+        catch {
+            // Not a URL we can judge (data:, blob:, about:, chrome-extension: …).
+            // Neither a host nor a site the policy talks about: let the browser decide.
+            await route.continue().catch(() => { });
+            return;
+        }
+        if (isHostAllowed(host, allowedDomains())) {
+            await route.continue().catch(() => { });
+            return;
+        }
+        const resourceType = request.resourceType();
+        const document = resourceType === 'document';
+        // Sub-resources the page needs in order to render are left alone; only the
+        // request classes that move the user or move data are refused.
+        if (!document && !DATA_RESOURCE_TYPES.has(resourceType)) {
+            await route.continue().catch(() => { });
+            return;
+        }
+        if (document)
+            onBlocked({ url: request.url(), host, resourceType, document, at: Date.now() });
+        await route.abort('blockedbyclient').catch(() => { });
+    });
+    return true;
+}

package/lib/page-actions.js

@@ -121,6 +121,9 @@ export async function navigate(session, url, waitUntil, signal) {
         catch (error) {
             if (isAbortError(error) || signal?.aborted === true)
                 throw error;
+            // A redirect chain can leave the allow-list: the guard refuses the hop and
+            // Playwright reports a plain navigation failure. Name the real cause.
+            session.throwIfNavigationBlocked();
             throw asTimeoutError('navigation', error);
         }
         return session.settleAndSnapshot(page, true);
@@ -716,6 +719,7 @@ export async function back(session, signal) {
         catch (error) {
             if (isAbortError(error))
                 throw error;
+            session.throwIfNavigationBlocked();
             throw asTimeoutError('navigation', error);
         }
         return session.settleAndSnapshot(page, true);
@@ -730,6 +734,7 @@ export async function forward(session, signal) {
         catch (error) {
             if (isAbortError(error))
                 throw error;
+            session.throwIfNavigationBlocked();
             throw asTimeoutError('navigation', error);
         }
         return session.settleAndSnapshot(page, true);
@@ -776,6 +781,7 @@ export async function openTab(session, url, waitUntil, signal) {
         catch (error) {
             if (isAbortError(error))
                 throw error;
+            session.throwIfNavigationBlocked();
             throw asTimeoutError('navigation', error);
         }
         return session.settleAndSnapshot(page, true);

package/lib/page-snapshot.js

@@ -77,6 +77,11 @@ export async function settleAndSnapshot(session, page, navChanged) {
     });
     if (raced.blocked)
         return session.blockedSnapshot(page, raced.pending);
+    // A page can leave the allow-list without any entry-point check seeing it: the
+    // request-level guard catches self-started navigations, and this catches the
+    // redirect the browser followed on its own.
+    session.throwIfNavigationBlocked();
+    await session.assertCurrentUrlAllowed(page);
     return raced.value;
 }
 /**

package/lib/playwright.d.ts

@@ -11,6 +11,6 @@ export declare const inject: string[];
  */
 export { Config, type PageData, type PlaywrightConfig } from './config.ts';
 export { PlaywrightProvider } from './provider.ts';
-export { assertAllowedUrl } from './url-policy.ts';
+export { assertAllowedUrl, isHostAllowed } from './url-policy.ts';
 export { resolveSnapshotEngine } from './page-snapshot.ts';
 export declare function apply(ctx: Context, config: PlaywrightConfig): void;

package/lib/playwright.js

@@ -11,12 +11,14 @@
  *   page-snapshot.ts       capture, ref signatures, ref lookup
  *   page-diagnostics.ts    console messages, page errors, network records
  *   browser-lifecycle.ts   launching/reusing the persistent context, window state
+ *   window-focus.ts        is the window minimized / create a tab without raising it
+ *   navigation-guard.ts    the allow-list on the wire (refuses off-list requests)
  *   login-state.ts         exporting and restoring login state
  * @module dsh-browser-playwright-codex/playwright
  */
 import { PlaywrightProvider } from "./provider.js";
 import {} from "./config.js";
-import { subscribe as subscribeEnabled } from "./runtime-state.js";
+import { publishConfiguredHeadless, subscribe as subscribeEnabled } from "./runtime-state.js";
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'browser-playwright';
 /** The browser runtime this provider registers into. */
@@ -33,10 +35,11 @@ export const inject = ['browser'];
 // subpath stopped re-exporting it). The other names keep the pre-split public surface intact.
 export { Config } from "./config.js";
 export { PlaywrightProvider } from "./provider.js";
-export { assertAllowedUrl } from "./url-policy.js";
+export { assertAllowedUrl, isHostAllowed } from "./url-policy.js";
 export { resolveSnapshotEngine } from "./page-snapshot.js";
 export function apply(ctx, config) {
     const provider = new PlaywrightProvider(config);
+    publishConfiguredHeadless(config.launch.headless === true);
     ctx.browser.registerProvider(provider);
     // Runtime on/off switch: when disabled the UI (or a future hot reload)
     // flips the flag and the provider tears down every active window so the

package/lib/provider.d.ts

@@ -1,6 +1,7 @@
 import { type Browser, type BrowserContext, type Dialog, type Page } from 'playwright-core';
 import { PlaywrightSession } from './session.ts';
 import type { PlaywrightConfig } from './config.ts';
+import { type BlockedRequest } from './navigation-guard.ts';
 /**
  * Playwright-backed {@link BrowserProvider}: one shared browser, one context
  * per owner key, LRU eviction, idle disposal, ref-based snapshot interaction.
@@ -32,6 +33,8 @@ export declare class PlaywrightProvider {
     id: string;
     /** Legacy (persistent:false) shared browser instance. */
     browser: Browser | undefined;
+    /** Window mode the live process was launched with (undefined = nothing running). */
+    launchedHeadless: boolean | undefined;
     /** Persistent-mode shared profile-backed context (the personal window). */
     context: BrowserContext | undefined;
     entries: Map<string, OwnerEntry>;
@@ -48,6 +51,26 @@ export declare class PlaywrightProvider {
     /** Owner that raised the dialog currently parked on a page. */
     lastActor: string | undefined;
     lastStatePersist: number;
+    /**
+     * Launch in flight, so two sessions waking up at the same time share ONE
+     * launch instead of racing for the same profile directory.
+     *
+     * Measured 2026-10-26: two concurrent acquires both saw "no context yet" and
+     * both called launchPersistentContext. The second died on Chrome's profile
+     * singleton, the recovery path deleted the RUNNING browser's lock files, and
+     * the caller got "install a Chromium-family browser". The lock files being
+     * gone is what let a later launch start a second browser on the same profile
+     * and leave processes behind.
+     */
+    contextLaunch: Promise<BrowserContext> | undefined;
+    /** Same for the legacy shared-browser launch. */
+    browserLaunch: Promise<Browser> | undefined;
+    /**
+     * The last navigation the host guard refused. Read (and cleared) once by the
+     * action that caused it, so "I clicked and nothing happened" becomes a named
+     * URL_NOT_ALLOWED instead of a silent no-op.
+     */
+    blockedNavigation: BlockedRequest | undefined;
     constructor(config: PlaywrightConfig);
     available(): boolean;
     /** Pages already carrying the dialog guard (WeakSet: pages stay collectable). */
@@ -83,7 +106,27 @@ export declare class PlaywrightProvider {
     };
     /** One line describing a parked dialog for the tool result. */
     dialogNoteFor(pending: PendingDialogRecord): string;
+    /**
+     * Window mode to launch with: the user's switch wins over the configured
+     * default. Read on every launch, so a change lands on the next operation
+     * without touching a patch file.
+     */
+    desiredHeadless(): boolean;
+    /**
+     * Close a running process whose mode no longer matches. The next acquire
+     * relaunches with the new mode; login state is exported first, so only the
+     * tabs and unsaved page state are lost — never the login.
+     */
+    private relaunchIfModeChanged;
     acquire(owner: string): Promise<PlaywrightSession>;
+    /**
+     * Keep the number of tracked owner handles inside maxSessions in persistent
+     * mode. Handles share one window, so dropping the least recently used idle
+     * handle costs nothing the user can see; the owner gets a fresh handle on the
+     * same window next time. An owner with an operation in flight is never dropped.
+     * @param keep - the owner being acquired right now.
+     */
+    private evictIdleHandles;
     disposeOwner(owner: string): Promise<void>;
     dispose(): Promise<void>;
     /** Touch the entry's last-used clock and re-arm its idle timer. */
@@ -106,6 +149,19 @@ export declare class PlaywrightProvider {
     ensureContext(): Promise<BrowserContext>;
     /** Remove stale Chrome singleton lock files inside the profile directory. */
     clearChromeLocks(): Promise<void>;
+    /**
+     * Put the allow-list on the wire for one context: every navigation and every
+     * data request outside the list is refused from then on, whoever started it.
+     * See navigation-guard.ts for why the entry-point checks alone were not enough.
+     * @param context - freshly created context, before its first navigation.
+     */
+    installHostGuard(context: BrowserContext): Promise<void>;
+    /**
+     * Take the pending "a navigation was refused" record, if any. Consumed once:
+     * the next action must not inherit the previous action's refusal.
+     * @returns the refused navigation, or undefined.
+     */
+    takeBlockedNavigation(): BlockedRequest | undefined;
     /**
      * Collect the login-state fallback WITHOUT ever opening a page while the
      * window is put away.

package/lib/provider.js

@@ -10,15 +10,18 @@ import {} from 'playwright-core';
 import os from 'node:os';
 import path from 'node:path';
 import { PlaywrightSession } from "./session.js";
-import { getEnabled, publishConfiguredEngine, publishLoginSites } from "./runtime-state.js";
+import { getEffectiveHeadless, getEnabled, publishConfiguredEngine, publishLoginSites } from "./runtime-state.js";
 import { BrowserError } from "./errors.js";
 import { SNAPSHOT_SCRIPT } from "./injected.js";
 import { isWindowMinimized } from "./window-focus.js";
+import { installHostGuard } from "./navigation-guard.js";
 export class PlaywrightProvider {
     config;
     id = 'playwright';
     /** Legacy (persistent:false) shared browser instance. */
     browser;
+    /** Window mode the live process was launched with (undefined = nothing running). */
+    launchedHeadless = undefined;
     /** Persistent-mode shared profile-backed context (the personal window). */
     context;
     entries = new Map();
@@ -35,6 +38,26 @@ export class PlaywrightProvider {
     /** Owner that raised the dialog currently parked on a page. */
     lastActor;
     lastStatePersist = 0;
+    /**
+     * Launch in flight, so two sessions waking up at the same time share ONE
+     * launch instead of racing for the same profile directory.
+     *
+     * Measured 2026-10-26: two concurrent acquires both saw "no context yet" and
+     * both called launchPersistentContext. The second died on Chrome's profile
+     * singleton, the recovery path deleted the RUNNING browser's lock files, and
+     * the caller got "install a Chromium-family browser". The lock files being
+     * gone is what let a later launch start a second browser on the same profile
+     * and leave processes behind.
+     */
+    contextLaunch = undefined;
+    /** Same for the legacy shared-browser launch. */
+    browserLaunch = undefined;
+    /**
+     * The last navigation the host guard refused. Read (and cleared) once by the
+     * action that caused it, so "I clicked and nothing happened" becomes a named
+     * URL_NOT_ALLOWED instead of a silent no-op.
+     */
+    blockedNavigation = undefined;
     constructor(config) {
         this.config = config;
         // Tell the settings card which page-reading mode this deployment was
@@ -170,27 +193,61 @@ export class PlaywrightProvider {
             ' Answer it with browser_dialog({ accept }) — accept only if the user authorized exactly this action,' +
             ' otherwise dismiss; no other tool can act until it is answered.');
     }
+    /**
+     * Window mode to launch with: the user's switch wins over the configured
+     * default. Read on every launch, so a change lands on the next operation
+     * without touching a patch file.
+     */
+    desiredHeadless() {
+        return getEffectiveHeadless(this.config.launch.headless === true);
+    }
+    /**
+     * Close a running process whose mode no longer matches. The next acquire
+     * relaunches with the new mode; login state is exported first, so only the
+     * tabs and unsaved page state are lost — never the login.
+     */
+    async relaunchIfModeChanged() {
+        const desired = this.desiredHeadless();
+        if (this.launchedHeadless === undefined || this.launchedHeadless === desired)
+            return;
+        await this.dispose();
+    }
     async acquire(owner) {
         if (!getEnabled()) {
             throw new BrowserError('DISABLED', 'dsh-browser-playwright-codex is disabled; open Settings → Plugins → 浏览器 and turn it on to use the browser');
         }
         const existing = this.entries.get(owner);
         if (existing) {
-            existing.lastUsed = Date.now();
-            this.armIdle(existing);
-            return existing.session;
+            // A window-mode switch made while this owner is active must not hand back
+            // a session in the old mode: closing and relaunching here keeps the change
+            // one call away instead of "next restart".
+            if (this.launchedHeadless !== undefined && this.launchedHeadless !== this.desiredHeadless()) {
+                await this.dispose();
+            }
+            else {
+                existing.lastUsed = Date.now();
+                this.armIdle(existing);
+                return existing.session;
+            }
         }
         if (this.config.launch.persistent) {
+            await this.relaunchIfModeChanged();
             // Personal-browser mode: all owners drive one shared profile-backed
             // window (Codex-style). Entries are lightweight session handles on
             // the shared context; the last owner to leave closes the window.
             const context = await this.ensureContext();
+            // maxSessions applies here too, but as a cap on HANDLES: all of them
+            // drive the same window, so evicting one costs nothing visible and the
+            // owner simply gets a fresh handle (same page set, index back to 0) next
+            // time. Before this, the setting was inert in the default mode.
+            this.evictIdleHandles(owner);
             const session = new PlaywrightSession(this, owner, context);
             const entry = { context, session, lastUsed: Date.now(), pending: 0, timer: undefined };
             this.entries.set(owner, entry);
             this.armIdle(entry);
             return session;
         }
+        await this.relaunchIfModeChanged();
         const browser = await this.ensureBrowser();
         while (this.entries.size >= this.config.maxSessions) {
             const oldest = [...this.entries.entries()].sort((a, b) => a[1].lastUsed - b[1].lastUsed)[0];
@@ -203,10 +260,12 @@ export class PlaywrightProvider {
             // (system DPI respected) exactly like a hand-opened Chrome, instead
             // of Playwright forcing a fixed CSS viewport that overflows the
             // window on scaled displays. Headless keeps the fixed viewport.
-            ...(this.config.launch.headless ? { viewport: this.config.launch.viewport } : { viewport: null }),
+            ...(this.desiredHeadless() ? { viewport: this.config.launch.viewport } : { viewport: null }),
             ignoreHTTPSErrors: this.config.launch.ignoreHTTPSErrors,
         });
         context.on('page', (page) => this.armDialogGuard(page));
+        // Allow-list on the wire, not just at the entry points (navigation-guard.ts).
+        await this.installHostGuard(context);
         await context.addInitScript(SNAPSHOT_SCRIPT);
         const session = new PlaywrightSession(this, owner, context);
         const entry = { context, session, lastUsed: Date.now(), pending: 0, timer: undefined };
@@ -221,6 +280,30 @@ export class PlaywrightProvider {
         });
         return session;
     }
+    /**
+     * Keep the number of tracked owner handles inside maxSessions in persistent
+     * mode. Handles share one window, so dropping the least recently used idle
+     * handle costs nothing the user can see; the owner gets a fresh handle on the
+     * same window next time. An owner with an operation in flight is never dropped.
+     * @param keep - the owner being acquired right now.
+     */
+    evictIdleHandles(keep) {
+        const limit = this.config.maxSessions;
+        if (!Number.isFinite(limit) || limit <= 0)
+            return;
+        while (this.entries.size >= limit) {
+            const candidates = [...this.entries.entries()]
+                .filter(([key, entry]) => key !== keep && entry.pending === 0)
+                .sort((left, right) => left[1].lastUsed - right[1].lastUsed);
+            const oldest = candidates[0];
+            if (oldest === undefined)
+                return;
+            const [key, entry] = oldest;
+            if (entry.timer !== undefined)
+                clearTimeout(entry.timer);
+            this.entries.delete(key);
+        }
+    }
     async disposeOwner(owner) {
         const entry = this.entries.get(owner);
         if (entry === undefined)
@@ -234,6 +317,7 @@ export class PlaywrightProvider {
             if (this.entries.size === 0 && this.context !== undefined) {
                 const ctx = this.context;
                 this.context = undefined;
+                this.launchedHeadless = undefined;
                 await this.persistState(ctx);
                 await ctx.close().catch(() => { });
             }
@@ -242,6 +326,11 @@ export class PlaywrightProvider {
         await entry.context.close().catch(() => { });
     }
     async dispose() {
+        this.launchedHeadless = undefined;
+        // A launch still in flight must not re-create a context after disposal.
+        this.contextLaunch = undefined;
+        this.browserLaunch = undefined;
+        this.blockedNavigation = undefined;
         const owners = [...this.entries.keys()];
         for (const owner of owners)
             await this.disposeOwner(owner);
@@ -331,6 +420,29 @@ export class PlaywrightProvider {
     async clearChromeLocks() {
         return clearChromeLocks(this);
     }
+    /**
+     * Put the allow-list on the wire for one context: every navigation and every
+     * data request outside the list is refused from then on, whoever started it.
+     * See navigation-guard.ts for why the entry-point checks alone were not enough.
+     * @param context - freshly created context, before its first navigation.
+     */
+    async installHostGuard(context) {
+        this.blockedNavigation = undefined;
+        await installHostGuard(context, () => this.config.allowedDomains ?? [], (blocked) => {
+            if (blocked.document)
+                this.blockedNavigation = blocked;
+        });
+    }
+    /**
+     * Take the pending "a navigation was refused" record, if any. Consumed once:
+     * the next action must not inherit the previous action's refusal.
+     * @returns the refused navigation, or undefined.
+     */
+    takeBlockedNavigation() {
+        const blocked = this.blockedNavigation;
+        this.blockedNavigation = undefined;
+        return blocked;
+    }
     /**
      * Collect the login-state fallback WITHOUT ever opening a page while the
      * window is put away.

package/lib/runtime-state.d.ts

@@ -33,6 +33,26 @@ export declare function getEnabled(): boolean;
 export declare function setEnabled(next: boolean): boolean;
 /** Subscribe to enable-state transitions. Returns an unsubscribe function. */
 export declare function subscribe(fn: (enabled: boolean) => void): () => void;
+/**
+ * The window mode the user picked (true = headless), or undefined when they
+ * never picked one — the configured default then applies.
+ */
+export declare function getHeadless(): boolean | undefined;
+/** Persist the window-mode choice. Returns true when the value changed. */
+export declare function setHeadless(next: boolean): boolean;
+/** Publish the configured default (launch.headless) for display. */
+export declare function publishConfiguredHeadless(value: boolean): void;
+/** The configured default, when the provider has published it. */
+export declare function getConfiguredHeadless(): boolean | undefined;
+/**
+ * Effective window mode: the user's choice, else the configured default, else
+ * the shipped default (headful).
+ *
+ * @param configuredFallback - config default when the provider has not published one
+ */
+export declare function getEffectiveHeadless(configuredFallback?: boolean): boolean;
+/** Did the user pick the window mode themselves? (The card shows "你选的".) */
+export declare function isHeadlessUserChosen(): boolean;
 /**
  * The page-reading mode the user picked, or undefined when they never picked
  * one — the configured default then applies.

package/lib/runtime-state.js

@@ -12,6 +12,10 @@ function stateFile() {
 }
 let _enabled = true;
 let _engine = undefined;
+/** User's window-mode choice: true = headless, undefined = follow the config. */
+let _headless = undefined;
+/** Config default pushed in by the provider (display only). */
+let _configuredHeadless = undefined;
 /** Default pushed in by the provider that is actually loaded (display only). */
 let _configuredEngine = undefined;
 /** Effective tool gates, pushed in by the tool family when it is applied (display only). */
@@ -33,6 +37,9 @@ function load() {
             // unknown value means "follow the configured default" (undefined here).
             // Files written before this setting existed therefore stay valid.
             _engine = obj.engine === 'legacy' || obj.engine === 'aria' ? obj.engine : undefined;
+            // Same contract as engine: absent/unknown means "follow the configured
+            // default", so files written before this setting existed stay valid.
+            _headless = typeof obj.headless === 'boolean' ? obj.headless : undefined;
         }
     }
     catch {
@@ -60,6 +67,8 @@ function persist() {
         // Keep the historical shape until the user actually picks a page-reading
         // mode: an absent `engine` means "use the configured default".
         const payload = _engine === undefined ? { enabled: _enabled } : { enabled: _enabled, engine: _engine };
+        if (_headless !== undefined)
+            payload.headless = _headless;
         fs.writeFileSync(tmp, JSON.stringify(payload, null, 2));
         fs.renameSync(tmp, target);
     }
@@ -99,6 +108,50 @@ export function subscribe(fn) {
         _subscribers.delete(fn);
     };
 }
+/**
+ * The window mode the user picked (true = headless), or undefined when they
+ * never picked one — the configured default then applies.
+ */
+export function getHeadless() {
+    load();
+    return _headless;
+}
+/** Persist the window-mode choice. Returns true when the value changed. */
+export function setHeadless(next) {
+    load();
+    if (typeof next !== 'boolean')
+        return false;
+    if (_headless === next)
+        return false;
+    _headless = next;
+    persist();
+    return true;
+}
+/** Publish the configured default (launch.headless) for display. */
+export function publishConfiguredHeadless(value) {
+    _configuredHeadless = value === true;
+}
+/** The configured default, when the provider has published it. */
+export function getConfiguredHeadless() {
+    return _configuredHeadless;
+}
+/**
+ * Effective window mode: the user's choice, else the configured default, else
+ * the shipped default (headful).
+ *
+ * @param configuredFallback - config default when the provider has not published one
+ */
+export function getEffectiveHeadless(configuredFallback = false) {
+    load();
+    if (_headless !== undefined)
+        return _headless;
+    return _configuredHeadless !== undefined ? _configuredHeadless : configuredFallback === true;
+}
+/** Did the user pick the window mode themselves? (The card shows "你选的".) */
+export function isHeadlessUserChosen() {
+    load();
+    return _headless !== undefined;
+}
 /**
  * The page-reading mode the user picked, or undefined when they never picked
  * one — the configured default then applies.