@mearl/browser-core 3.0.0-beta.9 → 3.0.0

package/README.en.md

@@ -0,0 +1,13 @@
+# @mearl/browser-core
+
+[简体中文](README.md) | [English](README.en.md)
+
+Page control logic and protocols shared by browsers and Node: DOM/AX snapshots, action observation, input, scrolling, navigation, request serialization, capture cursors, device simulation, generic device appearance, Cookie/domain permissions, and plugin task, page, and state contracts. Modules have no browser extension or native process installation side effects.
+
+The core includes no preset App identities. The host validates profile IDs against its active capability catalog. App profile schemas, explicit options, revisions, and page runtime bindings are data contracts; independent capability packages supply complete bridge implementations.
+
+The built-in installer at `@mearl/browser-core/appProfileRuntime` synchronizes only UA, navigator.appVersion, navigator.platform, and touch points. It does not install App bridges, business globals, container stacks, or authorization handlers. With a pageRuntime binding, the host must prepare the exact code from the installed capability package and execute it through the page runtime dispatcher; the base installer cannot substitute for this. See [browser bundles](../../docs/browser-bundles.en.md#page-runtimes) for resource preparation and dispatch.
+
+The default proxy authorization addresses are localhost and 127.0.0.1. Hosts obtain permission for other sites and pass them in the authorization list. The core includes Aplus/RUM/ARMS event parsers; additional parsers register through capability packages.
+
+Agent contracts are defined in agentChat.ts, agentSkills.ts, and pluginModels.ts and exported through the corresponding subpaths. agent-runtime uses these contracts to avoid duplicate definitions. Serializable page functions remain self-contained for shared use by the Extension and CDP.

package/README.md

@@ -1,8 +1,10 @@
 # @mearl/browser-core
 
+[简体中文](README.md) | [English](README.en.md)
+
 浏览器与 Node 可共享的页面控制逻辑和协议：DOM/AX 快照、动作观察、输入、滚动、导航、请求序列化、捕获游标、设备模拟、通用设备外观、Cookie/域名权限和插件任务、页面、状态合同。模块没有浏览器扩展或本机进程的安装副作用。
 
-核心不预置 App 身份；档案 ID 由宿主的已激活能力目录校验。App 档案 schema、显式选项、revision 和页面运行时绑定是数据合同，完整桥实现由独立能力包提供。
+核心不预置 App 身份；端模拟 ID 由宿主的已激活能力目录校验。端模拟配置 schema、显式选项、revision 和页面运行时绑定是数据合同，完整桥实现由独立能力包提供。
 
 `@mearl/browser-core/appProfileRuntime` 的内置安装器只同步 UA、navigator.appVersion、navigator.platform 和触摸点，不安装 App 桥、业务全局变量、容器栈或授权处理。有 pageRuntime 绑定时，宿主必须先从已安装的能力包准备确切代码，再通过页面运行时派发器执行；不能调用基础安装器代替。资源准备和派发见 [能力包](../../docs/browser-bundles.md#页面运行时)。
 

package/dist/agentChat.d.ts

@@ -1,5 +1,7 @@
 export type AgentChatEventKind = 'lifecycle' | 'notification' | 'request' | 'error';
 export type AgentChatSessionStatus = 'idle' | 'running' | 'waiting' | 'error';
+export declare function isQoderAuthenticationError(message: unknown): boolean;
+export declare function isQoderMissingSessionError(message: unknown): boolean;
 export type AgentChatCapabilitySupport = boolean | 'runtime';
 export declare const AGENT_CHAT_MAX_PAGE_URL_CHARS = 16384;
 export declare const AGENT_CHAT_MAX_PAGE_TITLE_CHARS = 2048;
@@ -28,7 +30,8 @@ export interface AgentChatProviderDescriptor {
     };
     error?: string;
     setup?: {
-        installCommand: string;
+        installCommand?: string;
+        canInstall?: boolean;
         loginCommand?: string;
         docsUrl?: string;
     };
@@ -91,6 +94,7 @@ export interface AgentChatSendOptions {
     message: string;
     images?: AgentChatImageInput[];
     displayMessage?: string;
+    hasAdditionalContext?: boolean;
     clientMessageId?: string;
 }
 export interface AgentChatRunOptions {
@@ -157,6 +161,9 @@ export interface AgentChatStatus {
     sessions: AgentChatSession[];
 }
 export interface AgentChatKnownEventParams {
+    'session/reconnected': {
+        providerSessionId: string;
+    };
     'turn/started': {
         turn: {
             id: string;

package/dist/agentChat.js

@@ -1,3 +1,10 @@
+export function isQoderAuthenticationError(message) {
+    return (typeof message === 'string' &&
+        /^(?:Authentication (?:is )?required|Unauthenticated|Sign-in required)(?:[:.\s]|$)/i.test(message));
+}
+export function isQoderMissingSessionError(message) {
+    return typeof message === 'string' && /^(?:Invalid params:\s*)?Invalid session identifier\b/i.test(message);
+}
 export const AGENT_CHAT_MAX_PAGE_URL_CHARS = 16_384;
 export const AGENT_CHAT_MAX_PAGE_TITLE_CHARS = 2_048;
 export const AGENT_CHAT_MAX_TOOLBOX_CONTEXT_CHARS = 65_536;
@@ -123,6 +130,7 @@ function readAgentChatRequestParams(params) {
     return { ...params, requestId: params.requestId };
 }
 const AGENT_CHAT_EVENT_PARAM_READERS = {
+    'session/reconnected': params => typeof params.providerSessionId === 'string' ? { providerSessionId: params.providerSessionId } : null,
     'turn/started': readAgentChatTurnParams,
     'turn/completed': readAgentChatTurnParams,
     'session/model/updated': readAgentChatModelParams,

package/dist/agentServiceProtocol.d.ts

@@ -11,6 +11,18 @@ export interface AgentServiceActionMap {
         request: undefined;
         response: AgentChatStatus;
     };
+    agent_chat_install_provider: {
+        request: {
+            providerId: string;
+        };
+        response: AgentChatStatus;
+    };
+    agent_chat_login_qoder: {
+        request: undefined;
+        response: {
+            url: string | null;
+        };
+    };
     agent_chat_prepare: {
         request: AgentChatPrepareOptions;
         response: {
@@ -51,6 +63,14 @@ export interface AgentServiceActionMap {
         request: AgentChatEventsOptions;
         response: AgentChatEventsResult;
     };
+    agent_chat_read_visualization: {
+        request: {
+            path: string;
+        };
+        response: {
+            html: string;
+        };
+    };
     agent_chat_refresh: {
         request: AgentChatEventsOptions;
         response: AgentChatRefreshResult;
@@ -112,6 +132,8 @@ export type AgentServiceHandlerMap = {
 export declare const AGENT_SERVICE_ACTIONS: {
     readonly agent_chat_pick_directory: true;
     readonly agent_chat_status: true;
+    readonly agent_chat_install_provider: true;
+    readonly agent_chat_login_qoder: true;
     readonly agent_chat_prepare: true;
     readonly agent_chat_list_sessions: true;
     readonly agent_chat_start: true;
@@ -120,6 +142,7 @@ export declare const AGENT_SERVICE_ACTIONS: {
     readonly agent_chat_interrupt: true;
     readonly agent_chat_close: true;
     readonly agent_chat_events: true;
+    readonly agent_chat_read_visualization: true;
     readonly agent_chat_refresh: true;
     readonly agent_chat_open_app: true;
     readonly agent_chat_open_workspace: true;

package/dist/agentServiceProtocol.js

@@ -1,6 +1,8 @@
 export const AGENT_SERVICE_ACTIONS = {
     agent_chat_pick_directory: true,
     agent_chat_status: true,
+    agent_chat_install_provider: true,
+    agent_chat_login_qoder: true,
     agent_chat_prepare: true,
     agent_chat_list_sessions: true,
     agent_chat_start: true,
@@ -9,6 +11,7 @@ export const AGENT_SERVICE_ACTIONS = {
     agent_chat_interrupt: true,
     agent_chat_close: true,
     agent_chat_events: true,
+    agent_chat_read_visualization: true,
     agent_chat_refresh: true,
     agent_chat_open_app: true,
     agent_chat_open_workspace: true,

package/dist/appProfileDefinition.d.ts

@@ -66,9 +66,11 @@ export interface AppProfileUsage {
         url: string;
     }>;
 }
-/** 单容器档案（纯数据） */
+/** 单个 App 容器的声明式端模拟配置。 */
 export interface AppProfileDefinition {
     name: string;
+    /** Preferred App ID when the capability is installed outside a Preset. */
+    defaultAppId?: string;
     usage?: AppProfileUsage;
     /** Content-addressed installer supplied by the selected browser capability package. */
     pageRuntime?: {

package/dist/appProfileDefinition.js

@@ -83,6 +83,7 @@ export function validateAppProfileDefinition(value) {
         'schemes',
     ];
     const optional = [
+        'defaultAppId',
         'usage',
         'actionIcon',
         'labels',
@@ -114,6 +115,10 @@ export function validateAppProfileDefinition(value) {
             invalid(key);
     if (!/^[a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)?$/.test(value.name))
         invalid('name');
+    if (value.defaultAppId !== undefined &&
+        (typeof value.defaultAppId !== 'string' || !/^[a-z][a-z0-9-]{0,79}$/.test(value.defaultAppId) ||
+            ['constructor', 'prototype'].includes(value.defaultAppId)))
+        invalid('defaultAppId');
     if (value.usage !== undefined) {
         const usage = value.usage;
         fields(usage, [], ['description', 'limitations', 'skills', 'documentation'], 'usage');

package/dist/browserActionProtocol.d.ts

@@ -464,9 +464,9 @@ export interface BrowserEmulationOptions {
     userAgent?: string;
     orientation?: 'portrait' | 'landscape';
     touch?: boolean;
-    /** 在 iframe WebView 外渲染设备系统栏；默认 false，保持纯 CDP 设备模拟。 */
+    /** 在 iframe WebView 外渲染顶部状态栏和底部操作区；默认 false。 */
     deviceShell?: boolean;
-    /** App 容器横屏时将根页面与业务页面分置左右 WebView；仅与 deviceShell、App 档案同时生效。 */
+    /** App 容器横屏时将根页面与业务页面分置左右 WebView，需要同时开启 deviceShell 和端模拟。 */
     splitScreen?: boolean;
 }
 /** Provider-defined behavior ID; core does not execute or enumerate business behaviors. */
@@ -478,7 +478,7 @@ export interface AppBridgeMethodConfig {
     noop?: boolean;
     silent?: boolean;
 }
-/** 追加或覆盖 App 档案中的桥方法。配置保持 JSON 可序列化，不执行配置提供的代码。 */
+/** 追加或覆盖端模拟配置中的桥方法。配置保持 JSON 可序列化。 */
 export interface AppBridgeConfig {
     methods: Record<string, AppBridgeMethodConfig>;
 }
@@ -499,13 +499,13 @@ export interface TabOpenParams {
     emulation?: BrowserEmulationOptions;
     group?: string;
     /**
-     * 客户端容器模拟档案名（由已安装能力目录提供）。只注入容器 UA、环境变量、JSBridge 与桥协议；
-     * 设备视口和 iframe 系统外壳由 emulation.deviceShell 独立控制。可用档案通过 get_capabilities 查询。
+     * 端模拟配置 ID，通过 get_capabilities 查询。该配置提供容器 UA、环境变量、JSBridge 和桥协议。
+     * 设备视口由 emulation 配置，系统栏由 emulation.deviceShell 控制。
      */
     appProfile?: AppProfileName;
     /** 与 appProfile 配合使用；容器系统，默认 ios */
     os?: 'ios' | 'android';
-    /** 与 appProfile 配合使用；按方法覆盖档案内置桥配置 */
+    /** 与 appProfile 配合使用，按方法覆盖端模拟的内置桥配置。 */
     bridgeConfig?: AppBridgeConfig;
 }
 export type TabGroupParams = {
@@ -526,18 +526,18 @@ export interface SetAppProfileParams {
     tabId: number;
     /** false 时清除该 tab 的容器模拟并刷新 */
     enabled: boolean;
-    /** 容器档案名（enabled=true 时必填） */
+    /** 端模拟配置 ID（enabled=true 时必填）。 */
     profile?: AppProfileName;
     /** Immediately use the latest installed definition while preserving explicit options. */
     refreshDefinition?: boolean;
-    /** 固定当前档案定义；默认在下次文档导航时自动采用可用更新。 */
+    /** 固定当前端模拟配置。默认在下次文档导航时自动采用可用更新。 */
     lockDefinition?: boolean;
     os?: 'ios' | 'android';
     appVersion?: string;
     /** 端定义支持的语言选项。 */
     language?: string;
     deviceModel?: string;
-    /** 按方法覆盖档案内置桥配置，仅支持受控行为、固定 JSON 回包和成功空实现 */
+    /** 按方法覆盖端模拟的内置桥配置，仅支持受控行为、固定 JSON 回包和成功空实现。 */
     bridgeConfig?: AppBridgeConfig;
     /**
      * 可选已安装的网络控件选择；null 清除，省略时保持当前设置。
@@ -545,7 +545,7 @@ export interface SetAppProfileParams {
      */
     networkControl?: NetworkControlSelection | null;
     /**
-     * 可选设备联动参数。传入时显式字段覆盖档案推荐设备，空对象使用推荐设备且默认开启
+     * 可选设备联动参数。传入时显式字段覆盖端模拟的推荐设备，空对象使用推荐设备且默认开启
      * deviceShell；省略时不设置或清除该 tab 的设备状态。
      */
     emulation?: BrowserEmulationOptions;
@@ -580,7 +580,7 @@ export interface PageClickParams {
     };
     /** CSS/text 查询的目标 frame；省略时容器模式自动使用当前业务 frame。 */
     frameId?: string;
-    /** point 的坐标空间；默认 outer-viewport 以保持兼容。 */
+    /** point 的坐标空间；手机壳预览默认 active-frame，其他页面默认 outer-viewport。 */
     coordinateSpace?: 'outer-viewport' | 'active-frame';
     role?: string;
     exact?: boolean;

package/dist/deviceEmulation.d.ts

@@ -8,6 +8,7 @@
  * 两条路径共享 preset 表 / 默认值推导 / 入参校验，确保对外行为完全一致。
  */
 import type { BrowserDevicePresetName, BrowserEmulationOptions } from './browserActionProtocol.js';
+import type { DeviceChromeViewConfig } from './deviceChromeView.js';
 export interface DevicePreset {
     width: number;
     height: number;
@@ -43,6 +44,11 @@ export type DeviceCutout = 'none' | 'dynamic-island' | 'notch' | 'side-camera';
 export interface DeviceAppearance {
     cutout: DeviceCutout;
 }
+export interface ResolvedDeviceChromeConfig extends DeviceChromeViewConfig {
+    safeAreaInsets: SafeAreaInsets;
+}
+/** Shared system-bar geometry for H5 containers and local mini-programs. */
+export declare function getDeviceChromeViewConfig(emulation: ResolvedEmulationConfig): ResolvedDeviceChromeConfig;
 /** Duo 除内屏竖屏外使用纵向系统栏，业务 WebView 避让屏幕右边缘。 */
 export declare function getDeviceSideBarWidth(preset: BrowserDevicePresetName | undefined, orientation: 'portrait' | 'landscape'): number;
 export declare const DEVICE_PRESETS: Record<BrowserDevicePresetName, DevicePreset>;

package/dist/deviceEmulation.js

@@ -7,6 +7,19 @@
  *
  * 两条路径共享 preset 表 / 默认值推导 / 入参校验，确保对外行为完全一致。
  */
+/** Shared system-bar geometry for H5 containers and local mini-programs. */
+export function getDeviceChromeViewConfig(emulation) {
+    const platform = emulation.platform === 'Android' || emulation.platform === 'OpenHarmony' ? 'android' : 'ios';
+    const sideBarWidth = getDeviceSideBarWidth(emulation.presetName, emulation.orientation);
+    return {
+        platform,
+        statusBarHeight: sideBarWidth ? 0 : emulation.orientation === 'landscape' ? 24 : emulation.safeAreaInsets.top,
+        bottomBarHeight: emulation.safeAreaInsets.bottom,
+        ...(sideBarWidth ? { sideBarWidth } : {}),
+        safeAreaInsets: { ...emulation.safeAreaInsets },
+        cutout: platform === 'ios' ? emulation.appearance.cutout : 'none',
+    };
+}
 const IPHONE_DUO_SIDE_BAR_WIDTH = 84;
 /** Duo 除内屏竖屏外使用纵向系统栏，业务 WebView 避让屏幕右边缘。 */
 export function getDeviceSideBarWidth(preset, orientation) {

package/dist/extensionServiceProtocol.d.ts

@@ -180,6 +180,12 @@ export interface HostToExtensionActionMap {
         request: Record<string, unknown>;
         response: unknown;
     };
+    __profile_install: {
+        request: {
+            source: string;
+        };
+        response: unknown;
+    };
     __preset_browser: {
         request: {
             operation: 'sync';
@@ -257,6 +263,7 @@ export interface HostToExtensionActionMap {
 export declare const HOST_TO_EXTENSION_ACTIONS: {
     readonly __browser_enhancement: true;
     readonly __preset_installation: true;
+    readonly __profile_install: true;
     readonly __preset_browser: true;
     readonly __export_cookies: true;
     readonly __capture_download: true;

package/dist/extensionServiceProtocol.js

@@ -30,6 +30,7 @@ export function isExtensionUiServiceAction(value) {
 export const HOST_TO_EXTENSION_ACTIONS = {
     __browser_enhancement: true,
     __preset_installation: true,
+    __profile_install: true,
     __preset_browser: true,
     __export_cookies: true,
     __capture_download: true,
@@ -90,6 +91,13 @@ export function getExtensionServiceTimeout(action, data = {}) {
         return 40000;
     if (action === 'agent_chat_pick_directory')
         return 300000;
+    if (action === 'agent_chat_install_provider')
+        return 420000;
+    if (action === 'agent_chat_login_qoder')
+        return 60000;
+    // Installation can prepare a plugin's runtime after the Skill manager returns.
+    if (action === 'agent_skills_install' || action === 'agent_skills_update')
+        return 600000;
     if (action.startsWith('agent_skills_'))
         return 130000;
     if ([

package/dist/pluginPageHost.js

@@ -125,8 +125,9 @@ export class PluginPageRuntimeHost {
         if (expectedDocumentId !== undefined && typeof expectedDocumentId !== 'string')
             throw new Error('Invalid plugin page document identity');
         const target = await this.adapter.resolve(Number(tabId), frame, expectedDocumentId);
-        if (!['http:', 'https:'].includes(new URL(target.url).protocol))
-            throw new Error('Plugin pages require an HTTP(S) document');
+        const url = new URL(target.url);
+        if (!['http:', 'https:'].includes(url.protocol) && (url.protocol !== 'file:' || url.hostname || frame !== 'main'))
+            throw new Error('Plugin pages require an HTTP(S) document or a main-frame local preview');
         return { ...target, browserSessionId: this.sessionId };
     }
     async current(record) {
@@ -650,7 +651,7 @@ export class PluginPageRuntimeHost {
             if (!Array.isArray(matches) ||
                 !matches.length ||
                 matches.length > 64 ||
-                !matches.every(isPluginPageMatchPattern) ||
+                !matches.every(match => isPluginPageMatchPattern(match) && !(match.startsWith('file:') && match.includes('*'))) ||
                 !Array.isArray(data.allowedMatches) ||
                 !data.allowedMatches.every(isPluginPageMatchPattern))
                 throw new Error('Invalid page activation URL matches');

package/dist/pluginPages.d.ts

@@ -13,6 +13,7 @@ export interface PluginPageEventBinding {
     policy?: 'serial' | 'latest' | 'parallel';
     concurrency?: number;
     maxPending?: number;
+    executionTimeoutMs?: number;
 }
 export interface PluginPageRuntime {
     version: 1;

package/dist/pluginPages.js

@@ -20,8 +20,9 @@ export function pluginPageUnavailable(error) {
     });
 }
 const pattern = /^(https?|\*):\/\/(\*|\*\.[a-z0-9.-]+|[a-z0-9.-]+|localhost)(:\d+)?(\/[^#]*)$/i;
+const localPattern = /^file:\/\/\/(?:[^/*?#\\]+\/)+(?:\*|[^/*?#\\]+)\.html$/;
 export function isPluginPageMatchPattern(value) {
-    return typeof value === 'string' && value.length <= 2048 && pattern.test(value);
+    return typeof value === 'string' && value.length <= 2048 && (pattern.test(value) || localPattern.test(value));
 }
 export function matchesPluginPageURL(matches, value) {
     let url;
@@ -31,6 +32,14 @@ export function matchesPluginPageURL(matches, value) {
     catch {
         return false;
     }
+    if (url.protocol === 'file:') {
+        if (url.hostname || !url.pathname.endsWith('.html'))
+            return false;
+        url.search = '';
+        url.hash = '';
+        return matches.some(item => localPattern.test(item) && (item === url.href ||
+            (item.endsWith('/*.html') && item.slice(0, item.lastIndexOf('/') + 1) === url.href.slice(0, url.href.lastIndexOf('/') + 1))));
+    }
     if (!['http:', 'https:'].includes(url.protocol))
         return false;
     return matches.some(item => {

package/dist/proxyPermissions.js

@@ -94,6 +94,7 @@ export const ACTIONS_SKIP_DOMAIN_CHECK = new Set([
     '__toolbox_open',
     '__extension_reload',
     '__preset_browser',
+    '__profile_install',
     // tab_list is a read-only enumeration; sensitive operations on specific
     // tabs (page_eval, send_request, etc.) are still individually checked.
     'tab_list',

package/dist/rootWebViewDocument.js

@@ -13,6 +13,41 @@ export function installRootWebViewDocumentTransport() {
             // 无效交付地址保留原路径，不导航到未经校验的地址。
         }
     }
+    if (!browser.__mearlRootDocumentUrl__ &&
+        browser.parent === browser.top &&
+        browser.parent !== browser) {
+        const frame = browser.frameElement;
+        const syncShellUrl = () => {
+            if (location.pathname.startsWith(prefix))
+                return false;
+            try {
+                const shell = browser.parent;
+                if (shell.location.origin !== location.origin || shell.location.href === location.href)
+                    return false;
+                // The iframe navigation already owns the history entry. Mirror its URL without adding another.
+                shell.history.replaceState(shell.history.state, '', location.href);
+                return true;
+            }
+            catch {
+                // The shell may be navigating or have an inaccessible origin.
+                return false;
+            }
+        };
+        if (frame?.hasAttribute('data-mearl-root-webview')) {
+            const animationId = 'mearl-root-webview-enter';
+            frame.getAnimations().find(animation => animation.id === animationId)?.cancel();
+            if (syncShellUrl() && !browser.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+                frame.animate([{ opacity: 0.75 }, { opacity: 1 }], {
+                    duration: 160,
+                    easing: 'ease-out',
+                }).id = animationId;
+            }
+            browser.addEventListener('pageshow', event => {
+                if (event.persisted)
+                    syncShellUrl();
+            });
+        }
+    }
     browser.__mearlRootDocumentUrl__ = (url) => {
         const navigation = performance.getEntriesByType('navigation')[0];
         const token = navigation?.serverTiming?.find(entry => entry.name === 'mearl-document')?.description;

package/dist/rootWebViewNavigation.d.ts

@@ -29,10 +29,12 @@ export interface WebViewDocumentResponse {
 }
 export interface RootWebViewNavigationOptions {
     client: WebViewNavigationClient;
-    shellHeaders(): Promise<Array<{
+    shellHeaders(forDocument: boolean): Promise<Array<{
         name: string;
         value: string;
     }> | undefined>;
+    /** The host supports loading same-origin documents directly in the root frame. */
+    keepSameOriginNavigation?: boolean;
     /** 开发代理把业务路径保存在外层 origin 中，不迁移该 origin。 */
     preserveOrigin?(current: URL, destination: URL): Promise<boolean> | boolean;
 }
@@ -40,6 +42,7 @@ export interface WebViewFrameTree {
     frame: {
         id: string;
         url: string;
+        urlFragment?: string;
         name?: string;
         parentId?: string;
     };
@@ -52,13 +55,17 @@ export interface WebViewFrameEvent {
     reason?: string;
 }
 /**
- * 真实导航在顶层完成网络请求，HTML 响应一次性交给根 WebView。内部交付地址避免
- * 重放一次性登录回调；非 HTML 和下载响应保持浏览器语义，不提交空容器。
+ * 根 WebView 在现有外壳内完成同源导航。顶层导航的 HTML 响应通过内部地址
+ * 一次性交付给根 WebView，避免重放登录回调；非 HTML 和下载保持浏览器语义。
  */
 export declare function createRootWebViewNavigation(options: RootWebViewNavigationOptions): {
+    isSameOriginRootNavigation: (params: WebViewNavigationRequest) => boolean;
+    preserveNavigationSource: ({ request }: WebViewNavigationRequest) => (() => void);
+    allowLocalReload(frameId: string, url: string): () => void;
     dispose(): void;
     initialize(tree: WebViewFrameTree): void;
-    handleFrameEvent(method: string, params: WebViewFrameEvent): void;
+    /** Returns the committed business URL when the root navigates within the current shell. */
+    handleFrameEvent(method: string, params: WebViewFrameEvent): string | undefined;
     /** Mock 与真实响应共用交付入口，保持浏览器 URL 和一次性文档语义一致。 */
     fulfillResponse(params: WebViewNavigationRequest, response: WebViewDocumentResponse, requestClient?: WebViewNavigationClient): Promise<boolean>;
     handle(params: WebViewNavigationRequest, requestClient?: WebViewNavigationClient): Promise<boolean>;

package/dist/rootWebViewNavigation.js

@@ -49,13 +49,15 @@ async function readDocumentBody(client, requestId) {
     }
 }
 /**
- * 真实导航在顶层完成网络请求，HTML 响应一次性交给根 WebView。内部交付地址避免
- * 重放一次性登录回调；非 HTML 和下载响应保持浏览器语义，不提交空容器。
+ * 根 WebView 在现有外壳内完成同源导航。顶层导航的 HTML 响应通过内部地址
+ * 一次性交付给根 WebView，避免重放登录回调；非 HTML 和下载保持浏览器语义。
  */
 export function createRootWebViewNavigation(options) {
     let handoff;
+    let localReload;
     let mainFrame;
     let rootFrameId;
+    let committedRoot;
     const directChildFrames = new Set();
     let navigationHops = 0;
     let document;
@@ -67,6 +69,27 @@ export function createRootWebViewNavigation(options) {
         clearTimeout(expiry);
         expiry = undefined;
     };
+    const isSameOriginRootNavigation = (params) => {
+        if (!options.keepSameOriginNavigation || !mainFrame || !committedRoot ||
+            params.frameId !== committedRoot.id ||
+            params.resourceType !== 'Document' || params.request.method !== 'GET' ||
+            params.responseStatusCode != null || params.responseErrorReason != null ||
+            !/^https?:/.test(params.request.url) || !/^https?:/.test(mainFrame.url))
+            return false;
+        const destination = new URL(params.request.url);
+        return !destination.pathname.startsWith(DOCUMENT_PREFIX) &&
+            !(localReload && localReload.frameId === params.frameId && localReload.url === destination.href) &&
+            destination.origin === committedRoot.origin && destination.origin === new URL(mainFrame.url).origin;
+    };
+    const preserveNavigationSource = ({ request }) => {
+        const source = {
+            url: new URL(request.url).href,
+            headers: Object.fromEntries(Object.entries(request.headers ?? {}).filter(([name]) => /^(referer|origin)$/i.test(name))),
+        };
+        handoff = source;
+        return () => { if (handoff === source)
+            handoff = undefined; };
+    };
     const deliverDocument = async (params, requestClient, headers, readBody) => {
         const destination = new URL(params.request.url);
         const originalHeaders = params.responseHeaders ?? [];
@@ -127,35 +150,62 @@ export function createRootWebViewNavigation(options) {
         return true;
     };
     return {
+        isSameOriginRootNavigation,
+        preserveNavigationSource,
+        allowLocalReload(frameId, url) {
+            const destination = new URL(url);
+            destination.hash = '';
+            const reload = { frameId, url: destination.href };
+            localReload = reload;
+            return () => { if (localReload === reload)
+                localReload = undefined; };
+        },
         dispose() {
             disposed = true;
             deliveryGeneration += 1;
             clearDocument();
             handoff = undefined;
+            localReload = undefined;
             directChildFrames.clear();
         },
         initialize(tree) {
             mainFrame = tree.frame;
-            rootFrameId = tree.childFrames?.find(child => child.frame.name === '__mearl_root__')?.frame
-                .id;
+            const root = tree.childFrames?.find(child => child.frame.name === '__mearl_root__')?.frame;
+            rootFrameId = root?.id;
+            committedRoot = root && /^https?:/.test(root.url)
+                ? { id: root.id, origin: new URL(root.url).origin }
+                : undefined;
             directChildFrames.clear();
             for (const child of tree.childFrames ?? [])
                 directChildFrames.add(child.frame.id);
         },
+        /** Returns the committed business URL when the root navigates within the current shell. */
         handleFrameEvent(method, params) {
             if (method === 'Page.frameNavigated' && params.frame) {
                 const frame = params.frame;
                 if (!frame.parentId) {
                     mainFrame = frame;
                     rootFrameId = undefined;
+                    committedRoot = undefined;
                     directChildFrames.clear();
                 }
-                else if (frame.parentId === mainFrame?.id) {
+                else if (mainFrame && frame.parentId === mainFrame.id) {
                     directChildFrames.add(frame.id);
-                    if (frame.name === '__mearl_root__') {
+                    if (frame.id === rootFrameId || frame.name === '__mearl_root__') {
                         rootFrameId = frame.id;
-                        if (/^https?:/.test(frame.url))
+                        if (/^https?:/.test(frame.url)) {
                             navigationHops = 0;
+                            const hasPreviousDocument = committedRoot?.id === frame.id;
+                            const destination = new URL(frame.url);
+                            committedRoot = { id: frame.id, origin: destination.origin };
+                            if (hasPreviousDocument && !destination.pathname.startsWith(DOCUMENT_PREFIX) &&
+                                /^https?:/.test(mainFrame.url) &&
+                                destination.origin === new URL(mainFrame.url).origin) {
+                                if (frame.urlFragment !== undefined)
+                                    destination.hash = frame.urlFragment;
+                                return destination.href;
+                            }
+                        }
                     }
                 }
             }
@@ -164,10 +214,14 @@ export function createRootWebViewNavigation(options) {
                 params.frameId) {
                 directChildFrames.add(params.frameId);
             }
-            else if (method === 'Page.frameDetached' && params.reason !== 'swap' && params.frameId) {
-                directChildFrames.delete(params.frameId);
-                if (params.frameId === rootFrameId)
-                    rootFrameId = undefined;
+            else if (method === 'Page.frameDetached' && params.frameId) {
+                if (params.frameId === committedRoot?.id)
+                    committedRoot = undefined;
+                if (params.reason !== 'swap') {
+                    directChildFrames.delete(params.frameId);
+                    if (params.frameId === rootFrameId)
+                        rootFrameId = undefined;
+                }
             }
         },
         /** Mock 与真实响应共用交付入口，保持浏览器 URL 和一次性文档语义一致。 */
@@ -178,7 +232,7 @@ export function createRootWebViewNavigation(options) {
                 params.frameId !== mainFrame.id ||
                 !/^https?:/.test(params.request.url))
                 return false;
-            const headers = await options.shellHeaders();
+            const headers = await options.shellHeaders(true);
             if (!headers || disposed)
                 return false;
             return deliverDocument({
@@ -226,9 +280,14 @@ export function createRootWebViewNavigation(options) {
                 }
                 return true;
             }
+            if (!responseStage && params.request.method === 'GET' &&
+                params.frameId === localReload?.frameId && destination.href === localReload.url) {
+                localReload = undefined;
+                return false;
+            }
             if (!mainFrame)
                 return false;
-            const headers = await options.shellHeaders();
+            const headers = await options.shellHeaders(responseStage && params.frameId === mainFrame.id);
             if (!headers || disposed)
                 return false;
             if (params.frameId === mainFrame.id) {
@@ -255,6 +314,7 @@ export function createRootWebViewNavigation(options) {
                 return false;
             const current = new URL(mainFrame.url);
             if (!/^https?:$/.test(current.protocol) ||
+                isSameOriginRootNavigation(params) ||
                 (await options.preserveOrigin?.(current, destination)))
                 return false;
             if (navigationHops >= 20)
@@ -265,17 +325,14 @@ export function createRootWebViewNavigation(options) {
                 responseHeaders: [{ name: 'Cache-Control', value: 'no-store' }],
             });
             navigationHops += 1;
-            handoff = {
-                url: destination.href,
-                headers: Object.fromEntries(Object.entries(params.request.headers ?? {}).filter(([name]) => /^(referer|origin)$/i.test(name))),
-            };
+            const clearSource = preserveNavigationSource(params);
             try {
                 await options.client.sendCommand('Page.navigate', {
                     url: destination.href + (params.request.urlFragment ?? ''),
                 });
             }
             catch {
-                handoff = undefined;
+                clearSource();
             }
             return true;
         },

package/dist/toolbox.d.ts

@@ -39,6 +39,7 @@ export interface ToolboxSandboxPage {
 export interface ToolboxAgentConfig {
     enabled: true;
     layout?: 'drawer' | 'workspace';
+    pageElementActions?: boolean;
 }
 export interface ToolboxSkillUpdate {
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/browser-core",
-  "version": "3.0.0-beta.9",
+  "version": "3.0.0",
   "description": "Shared pure-logic utilities for Mearl — usable in both browser extension and Node.js environments",
   "type": "module",
   "main": "dist/index.js",
@@ -48,6 +48,7 @@
     }
   },
   "files": [
+    "README.en.md",
     "dist",
     "!dist/**/*.map"
   ],