@mearl/app-profiles 3.0.0-beta.1 → 3.0.0-beta.10

package/README.md

@@ -1,15 +1,38 @@
 # @mearl/app-profiles
 
-内置飞猪、淘宝、微信、支付宝的基础 UA/版本档案。四份档案保留当前 UA 格式和版本替换，不内置桥对象、App 设置、scheme 路由、业务响应和完整容器实现。
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+The core includes no built-in App profiles. Installed capability packages supply App UAs, versions, bridge objects, settings, scheme routes, business responses, and container implementations. This package validates and compiles declarative profiles and applies setting overrides.
 
 ```ts
-import { resolveAppProfile } from '@mearl/app-profiles';
-const profile = resolveAppProfile('taobao', { os: 'android', appVersion: '10.65.0' });
-console.log(profile.ua);
+import { resolveAppProfileDefinition, type AppProfile } from '@mearl/app-profiles';
+
+export function compileInstalledApp(definition: AppProfile) {
+  return resolveAppProfileDefinition(definition, { os: 'android' });
+}
 ```
 
-宿主可以向 resolveAppProfile 或 resolveAppProfileDefinition 提供已校验的动态定义；编译器保留桥、设置及 pageRuntime 描述，不执行能力代码。定义与选项被复制并绑定 revision，插件升级不直接改写活动文档。
+Hosts can pass validated dynamic definitions to resolveAppProfile or resolveAppProfileDefinition. The compiler preserves bridge, settings, and pageRuntime descriptors without executing capability code. Definitions and options are copied and bound to a revision; plugin upgrades do not directly alter active documents.
+
+resolveAppProfileUpdate, rebuildAppProfileConfig, and updateAppProfileSetting preserve the precedence of explicit options, device appearance, and method overrides. Hosts pass preset defaults; existing user selections take priority. Installing a capability package does not mean its default configuration has been applied.
+
+Capability packages declare App behavior and install it into controlled pages. Page code and host handlers are linked through the [capability model](../../docs/capability-model.md).
 
-resolveAppProfileUpdate、rebuildAppProfileConfig 和 updateAppProfileSetting 保持显式选项、设备外观及方法覆盖的优先级。preset 默认值由宿主传入，用户已有选择继续优先；能力包安装成功不等于默认配置已经应用。
+## Agent capability discovery
+
+`mearl get_capabilities`, SDK `getCapabilities()`, and MCP `browser_get_capabilities` query the target browser through the existing browser/session routing. By default they return actions, device presets, and App summaries. Pass `{ "app": "package/app" }` to expand bridge methods, adjustable settings, and default versions. A partial or unsupported catalog does not establish that an App is absent; entries with available=false cannot be enabled. Methods are grouped by declaration: responses are fixed replies, noop methods succeed without an implementation, and behaviors simulate behavior. None establishes that a real business operation is available.
+
+Each App definition may declare optional `usage` metadata. Browser bundles and Node/Skill plugins use the same format:
+
+```json
+{
+  "usage": {
+    "description": "WebView and bridge behavior simulation",
+    "limitations": ["Real device authorization requires the corresponding host capability"],
+    "skills": ["example-skill"],
+    "documentation": [{ "title": "Usage guide", "url": "https://example.com/docs" }]
+  }
+}
+```
 
-完整 App 行为由能力包声明并安装到受控页面；真实设备授权仍由相应宿主能力执行。本包与基础运行时的迁入没有切换当前产品的实现来源，完整产品验收进度见 [迁移说明](../../docs/migration.md)。
+usage is limited to 4 KiB; description to 512 characters; and limitations, skills, and documentation to 8 entries each. Documentation URLs must use HTTPS without credentials. Queries read installed metadata only: they do not refresh plugins, open documentation, install or load Skills, or expose bridge scripts, global variable values, or fixed response contents. Skill names are author-provided entry points and do not imply installation. Use set_app_profile/tab_open for general operations and consult companion instructions for specialized workflows.

package/README.zh-CN.md

@@ -0,0 +1,38 @@
+# @mearl/app-profiles
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+核心不内置 App 档案。App UA、版本、桥对象、设置、scheme 路由、业务响应和容器实现均由安装的能力包提供；本包负责声明式档案校验、编译与设置覆盖。
+
+```ts
+import { resolveAppProfileDefinition, type AppProfile } from '@mearl/app-profiles';
+
+export function compileInstalledApp(definition: AppProfile) {
+  return resolveAppProfileDefinition(definition, { os: 'android' });
+}
+```
+
+宿主可以向 resolveAppProfile 或 resolveAppProfileDefinition 提供已校验的动态定义；编译器保留桥、设置及 pageRuntime 描述，不执行能力代码。定义与选项被复制并绑定 revision，插件升级不直接改写活动文档。
+
+resolveAppProfileUpdate、rebuildAppProfileConfig 和 updateAppProfileSetting 保持显式选项、设备外观及方法覆盖的优先级。preset 默认值由宿主传入，用户已有选择继续优先；能力包安装成功不等于默认配置已经应用。
+
+App 行为由能力包声明并安装到受控页面；页面代码和宿主处理器通过 [能力包模型](../../docs/capability-model.zh-CN.md) 关联。
+
+## Agent 能力发现
+
+`mearl get_capabilities`、SDK `getCapabilities()`、MCP `browser_get_capabilities` 查询当前目标浏览器，沿用 browser/session 路由。默认返回动作、设备预设和 App 摘要；传 `{ "app": "package/app" }` 按需展开桥方法、可调设置和默认版本。目录为 partial 或 unsupported 时不能据此断言 App 未安装，available=false 的条目不可启用。方法按声明组分类：responses 为固定回包，noop 为成功空实现，behaviors 为模拟行为；这些都不证明真实业务操作可用。
+
+能力包可在每份 App 定义中声明可选 `usage`，浏览器包与 Node/Skill 插件共用同一格式：
+
+```json
+{
+  "usage": {
+    "description": "WebView 与桥接行为模拟",
+    "limitations": ["真实设备授权需要对应的宿主能力"],
+    "skills": ["example-skill"],
+    "documentation": [{ "title": "使用说明", "url": "https://example.com/docs" }]
+  }
+}
+```
+
+usage 最大 4 KiB；description 最多 512 字符，limitations/skills/documentation 各最多 8 项。文档只接受无凭据的 HTTPS URL。查询只读取已安装元数据，不执行插件刷新、不打开文档、不安装或加载 Skill，也不输出桥接脚本、全局变量值及固定回包内容。Skill 名称是作者提供的入口，不代表该 Skill 已安装；通用调用继续使用 set_app_profile/tab_open，特殊流程才读取配套说明。

package/dist/environment/app-device.d.ts

@@ -0,0 +1,24 @@
+import type { EnvironmentChange, EnvironmentSnapshot } from './changes.js';
+type Component = 'device' | 'app';
+type Values = {
+    device: unknown;
+    app: unknown;
+};
+export type AppDeviceChanges<T extends Values> = {
+    [K in Component]?: EnvironmentChange<T[K]>;
+};
+export type AppDeviceSnapshots<T extends Values> = {
+    [K in Component]: EnvironmentSnapshot<T[K]>;
+};
+export interface AppDeviceEnvironmentHost<T extends Values> {
+    /** Validate the composed physical environment as well as reading each component's intent. */
+    read(): Promise<AppDeviceSnapshots<T>>;
+    save(changes: AppDeviceChanges<T>): Promise<void>;
+    matchesRestored<K extends Component>(component: K, baseline: T[K], current: T[K]): boolean;
+}
+/** App and device share physical fields. A coordinated change keeps their original baselines. */
+export declare function changeAppDeviceEnvironment<T extends Values, R>(owner: string, components: readonly Component[], changes: AppDeviceChanges<T>, host: AppDeviceEnvironmentHost<T>, effect: () => Promise<R>, restore?: boolean): Promise<{
+    result?: R;
+    changes: AppDeviceChanges<T>;
+}>;
+export {};

package/dist/environment/app-device.js

@@ -0,0 +1,61 @@
+/** App and device share physical fields. A coordinated change keeps their original baselines. */
+export async function changeAppDeviceEnvironment(owner, components, changes, host, effect, restore = false) {
+    if (!owner)
+        throw new Error('Environment owner is required');
+    if (!components.length || new Set(components).size !== components.length || components.some(key => key !== 'device' && key !== 'app'))
+        throw new Error('Invalid App/device change components');
+    const selected = new Set(components.filter(key => !restore || changes[key]));
+    if (!selected.size)
+        return { changes };
+    const before = await host.read();
+    const next = structuredClone({ device: changes.device, app: changes.app });
+    for (const key of ['device', 'app']) {
+        const change = changes[key];
+        if (!change)
+            continue;
+        if (change.owner !== owner || change.component !== key)
+            throw new Error('ENVIRONMENT_OWNER_CONFLICT');
+        if (change.phase !== 'active' || !change.applied)
+            throw new Error('ENVIRONMENT_UNCONFIRMED');
+        if (change.applied.revision !== before[key].revision || change.applied.fingerprint !== before[key].fingerprint) {
+            next[key] = { ...change, phase: 'conflict' };
+            await host.save(next);
+            throw new Error(`ENVIRONMENT_STATE_CONFLICT: ${key} changed after this owner wrote it`);
+        }
+    }
+    const isChanging = (key) => selected.has(key);
+    const stage = (key) => {
+        const previous = changes[key];
+        if (previous || (!restore && isChanging(key)))
+            next[key] = {
+                owner, component: key,
+                baseline: previous?.baseline ?? structuredClone(before[key]),
+                ...(previous?.applied ? { applied: previous.applied } : {}),
+                phase: restore && isChanging(key) ? 'restoring' : 'pending',
+            };
+    };
+    stage('device');
+    stage('app');
+    // One host save covers every owned component affected by the shared UA/container transition.
+    await host.save(next);
+    const result = await effect();
+    const after = await host.read();
+    if (restore)
+        for (const key of selected) {
+            if (!host.matchesRestored(key, next[key].baseline.value, after[key].value))
+                throw new Error(`ENVIRONMENT_RESTORE_UNCONFIRMED: ${key}`);
+        }
+    const commit = (key) => {
+        const change = next[key];
+        if (!change)
+            return;
+        if (restore && isChanging(key))
+            delete next[key];
+        else
+            next[key] = { ...change, phase: 'active', applied: structuredClone(after[key]) };
+    };
+    commit('device');
+    commit('app');
+    await host.save(next);
+    return { result, changes: next };
+}

package/dist/environment/changes.d.ts

@@ -0,0 +1,28 @@
+export type EnvironmentComponent = 'device' | 'app' | 'timezone';
+/** Hosts supply a revision for coordinated writes and an observation for external drift. */
+export interface EnvironmentSnapshot<T> {
+    revision: number;
+    fingerprint: string;
+    value: T;
+}
+export interface EnvironmentChange<T> {
+    owner: string;
+    component: EnvironmentComponent;
+    baseline: EnvironmentSnapshot<T>;
+    applied?: EnvironmentSnapshot<T>;
+    phase: 'pending' | 'active' | 'restoring' | 'conflict' | 'restored';
+}
+/** Callers serialize this flow with their existing page/environment update queue. */
+export interface EnvironmentChangeHost<T> {
+    read(): Promise<EnvironmentSnapshot<T>>;
+    save(change: EnvironmentChange<T>): Promise<void>;
+    restore(baseline: T): Promise<void>;
+    matchesRestored(baseline: EnvironmentSnapshot<T>, current: EnvironmentSnapshot<T>): boolean;
+}
+/** Persist recovery information before the first effect; failed/unknown effects remain pending. */
+export declare function applyEnvironmentChange<T, R>(owner: string, component: EnvironmentComponent, previous: EnvironmentChange<T> | undefined, host: EnvironmentChangeHost<T>, apply: () => Promise<R>): Promise<R>;
+/** Restore only this component and only while both coordinated and observed state still match. */
+export declare function restoreEnvironmentChange<T>(owner: string, change: EnvironmentChange<T>, host: EnvironmentChangeHost<T>): Promise<{
+    restored: boolean;
+    reason?: 'changed' | 'unconfirmed';
+}>;

package/dist/environment/changes.js

@@ -0,0 +1,53 @@
+function matches(expected, current) {
+    return expected.revision === current.revision && expected.fingerprint === current.fingerprint;
+}
+async function assertCurrent(change, host) {
+    if (change.phase !== 'active' || !change.applied) {
+        throw new Error('ENVIRONMENT_UNCONFIRMED: reconcile the previous change before writing again');
+    }
+    if (!matches(change.applied, await host.read())) {
+        await host.save({ ...change, phase: 'conflict' });
+        throw new Error('ENVIRONMENT_STATE_CONFLICT: the environment changed after this owner wrote it');
+    }
+}
+/** Persist recovery information before the first effect; failed/unknown effects remain pending. */
+export async function applyEnvironmentChange(owner, component, previous, host, apply) {
+    if (!owner)
+        throw new Error('Environment owner is required');
+    if (previous) {
+        if (previous.owner !== owner || previous.component !== component)
+            throw new Error('ENVIRONMENT_OWNER_CONFLICT');
+        await assertCurrent(previous, host);
+    }
+    const change = {
+        owner,
+        component,
+        baseline: previous?.baseline ?? structuredClone(await host.read()),
+        phase: 'pending',
+    };
+    await host.save(change);
+    const result = await apply();
+    const applied = structuredClone(await host.read());
+    await host.save({ ...change, phase: 'active', applied });
+    return result;
+}
+/** Restore only this component and only while both coordinated and observed state still match. */
+export async function restoreEnvironmentChange(owner, change, host) {
+    if (change.owner !== owner)
+        throw new Error('ENVIRONMENT_OWNER_CONFLICT');
+    if (change.phase === 'restored')
+        return { restored: true };
+    if (change.phase !== 'active' || !change.applied)
+        return { restored: false, reason: 'unconfirmed' };
+    if (!matches(change.applied, await host.read())) {
+        await host.save({ ...change, phase: 'conflict' });
+        return { restored: false, reason: 'changed' };
+    }
+    const restoring = { ...change, phase: 'restoring' };
+    await host.save(restoring);
+    await host.restore(structuredClone(change.baseline.value));
+    if (!host.matchesRestored(change.baseline, await host.read()))
+        return { restored: false, reason: 'unconfirmed' };
+    await host.save({ ...restoring, phase: 'restored' });
+    return { restored: true };
+}

package/dist/environment/document.d.ts

@@ -0,0 +1,11 @@
+import type { InjectedAppProfileConfig } from '@mearl/browser-core';
+export interface AppProfileDocumentEnvironmentOptions {
+    /** Some hosts prepare globals before the separately installed page runtime. */
+    globals: 'always' | 'runtime';
+    safeAreaVariables?: boolean;
+    restoreHintName?: string;
+}
+/** Self-contained MAIN-world bootstrap; hosts own script registration and removal. */
+export declare function installAppProfileDocumentEnvironment(config: InjectedAppProfileConfig, options: AppProfileDocumentEnvironmentOptions): void;
+/** Self-contained document-start scheduling, including App containers that need a body. */
+export declare function installAppProfileWhenDocumentReady(install: () => void, waitForBody?: boolean): void;

package/dist/environment/document.js

@@ -0,0 +1,79 @@
+/** Self-contained MAIN-world bootstrap; hosts own script registration and removal. */
+export function installAppProfileDocumentEnvironment(config, options) {
+    const browser = globalThis;
+    const target = browser;
+    if (options.restoreHintName) {
+        try {
+            Object.defineProperty(target, options.restoreHintName, {
+                configurable: true, enumerable: false, writable: false, value: true,
+            });
+        }
+        catch {
+            target[options.restoreHintName] = true;
+        }
+    }
+    const includeGlobals = options.globals === 'always' || Boolean(config.pageRuntime);
+    for (const [key, value] of Object.entries(includeGlobals ? config.globals : {})) {
+        try {
+            target[key] = value;
+        }
+        catch { /* Frozen page globals keep their original values. */ }
+    }
+    const insets = config.safeAreaInsets ?? { top: config.statusBarHeight, right: 0, bottom: 0, left: 0 };
+    if (includeGlobals) {
+        target.__STATUS_BAR_HEIGHT__ = config.statusBarHeight;
+        target.__SAFE_AREA_INSET_BOTTOM__ = insets.bottom;
+    }
+    for (const [key, value] of [
+        ['userAgent', config.userAgent],
+        ['platform', config.navigatorPlatform],
+        ...(includeGlobals ? [['vendor', 'Apple Computer, Inc.']] : []),
+        ['appVersion', config.userAgent.replace(/^Mozilla\//, '')],
+        ['maxTouchPoints', config.maxTouchPoints],
+        ...(includeGlobals && config.policies?.navigatorLanguage === true ? [['language', config.language]] : []),
+    ]) {
+        try {
+            Object.defineProperty(browser.navigator, key, { configurable: true, get: () => value });
+        }
+        catch { /* Non-configurable native properties keep their original values. */ }
+    }
+    if (includeGlobals && config.policies?.navigatorLanguage === true) {
+        try {
+            Object.defineProperty(browser.navigator, 'languages', { configurable: true, get: () => [config.language] });
+        }
+        catch { /* Non-configurable native properties keep their original values. */ }
+    }
+    if (options.safeAreaVariables) {
+        const apply = () => {
+            const root = browser.document.documentElement;
+            if (!root)
+                return false;
+            root.style.setProperty('--safe-area-inset-top', `${insets.top}px`);
+            root.style.setProperty('--safe-area-inset-right', `${insets.right}px`);
+            root.style.setProperty('--safe-area-inset-bottom', `${insets.bottom}px`);
+            root.style.setProperty('--safe-area-inset-left', `${insets.left}px`);
+            return true;
+        };
+        if (!apply()) {
+            const observer = new browser.MutationObserver(() => { if (apply())
+                observer.disconnect(); });
+            observer.observe(browser.document, { childList: true });
+        }
+    }
+}
+/** Self-contained document-start scheduling, including App containers that need a body. */
+export function installAppProfileWhenDocumentReady(install, waitForBody = false) {
+    const browser = globalThis;
+    const ready = () => Boolean(browser.document.documentElement && (!waitForBody || browser.document.body));
+    if (ready()) {
+        install();
+        return;
+    }
+    const observer = new browser.MutationObserver(() => {
+        if (!ready())
+            return;
+        observer.disconnect();
+        install();
+    });
+    observer.observe(browser.document, { childList: true, subtree: waitForBody });
+}

package/dist/environment/identity.d.ts

@@ -0,0 +1,6 @@
+import { type DeviceEnvironmentObservation, type ResolvedEmulationConfig } from '@mearl/browser-core';
+/** App UA wins over device UA. Unspecified Client Hints retain the captured browser values. */
+export declare function resolveAppDeviceUserAgent(baseline: Pick<DeviceEnvironmentObservation, 'userAgent' | 'userAgentMetadata'>, device?: ResolvedEmulationConfig | null, appUserAgent?: string): {
+    userAgent: string;
+    userAgentMetadata: import("@mearl/browser-core").DeviceUserAgentMetadata | null;
+};

package/dist/environment/identity.js

@@ -0,0 +1,12 @@
+import { emptyDeviceUserAgentMetadata } from '@mearl/browser-core';
+/** App UA wins over device UA. Unspecified Client Hints retain the captured browser values. */
+export function resolveAppDeviceUserAgent(baseline, device, appUserAgent) {
+    const metadata = baseline.userAgentMetadata;
+    return {
+        userAgent: appUserAgent ?? device?.userAgent ?? baseline.userAgent,
+        userAgentMetadata: appUserAgent ? emptyDeviceUserAgentMetadata() : device && metadata ? {
+            ...structuredClone(metadata), mobile: device.mobile, platform: device.platform,
+            platformVersion: device.platformVersion, architecture: device.architecture, model: device.model,
+        } : structuredClone(metadata),
+    };
+}

package/dist/environment/relay.d.ts

@@ -0,0 +1,5 @@
+/** Self-contained MAIN-world transport; host services remain outside the page. */
+export declare function installAppProfileMessageRelay(bindingName: string, options?: {
+    markerName?: string;
+    supportedTypes?: readonly string[];
+}): void;

package/dist/environment/relay.js

@@ -0,0 +1,84 @@
+/** Self-contained MAIN-world transport; host services remain outside the page. */
+export function installAppProfileMessageRelay(bindingName, options = {}) {
+    const browser = globalThis;
+    const target = globalThis;
+    const markerName = options.markerName ?? '__mearlCdpAppProfileRelayInstalled__';
+    if (target[markerName])
+        return;
+    target[markerName] = true;
+    browser.addEventListener('message', event => {
+        if (event.source !== globalThis)
+            return;
+        const message = event.data;
+        if (!message || message.source !== 'mearl-app-bridge')
+            return;
+        const requestId = message.requestId;
+        if (typeof requestId !== 'number')
+            return;
+        if (message.type === 'settings' && globalThis.top !== globalThis)
+            return;
+        if (message.type === 'prepareWebView') {
+            browser.postMessage({
+                source: 'mearl-content',
+                type: 'APP_BRIDGE_PREPARE_WEBVIEW_RESPONSE',
+                requestId,
+                result: { success: true },
+            }, '*');
+            return;
+        }
+        if (message.type !== 'protocol' &&
+            message.type !== 'protocolStream' &&
+            message.type !== 'userInfo' &&
+            message.type !== 'authCode' &&
+            message.type !== 'authCodeCancel' &&
+            message.type !== 'settings' &&
+            message.type !== 'screenshot') {
+            return;
+        }
+        const replyFailure = (reason) => {
+            browser.console?.warn('[Mearl] App bridge relay unavailable:', reason);
+            if (message.type === 'protocolStream') {
+                browser.postMessage({
+                    source: 'mearl-content',
+                    type: 'APP_BRIDGE_PROTOCOL_STREAM_EVENT',
+                    requestId,
+                    eventType: 'onError',
+                    data: { error: reason },
+                }, '*');
+                return;
+            }
+            const responseTypes = {
+                protocol: 'APP_BRIDGE_PROTOCOL_RESPONSE',
+                userInfo: 'APP_BRIDGE_USER_INFO_RESPONSE',
+                authCode: 'APP_BRIDGE_AUTH_CODE_RESPONSE',
+                screenshot: 'APP_BRIDGE_SCREENSHOT_RESPONSE',
+                settings: 'APP_BRIDGE_SETTINGS_RESPONSE',
+            };
+            browser.postMessage({
+                source: 'mearl-content',
+                type: responseTypes[String(message.type)],
+                requestId,
+                result: { success: false, error: reason },
+            }, '*');
+        };
+        if (options.supportedTypes && !options.supportedTypes.includes(String(message.type))) {
+            replyFailure('this App bridge operation is not supported by the selected backend');
+            return;
+        }
+        const binding = target[bindingName];
+        if (typeof binding !== 'function') {
+            replyFailure('native relay binding is unavailable');
+            return;
+        }
+        try {
+            binding(JSON.stringify({
+                type: message.type,
+                requestId,
+                payload: message.payload,
+            }));
+        }
+        catch (error) {
+            replyFailure(error instanceof Error ? error.message : 'native relay call failed');
+        }
+    });
+}

package/dist/index.d.ts

@@ -1,3 +1,8 @@
 export * from './profiles.js';
 export * from './settings.js';
 export * from './updates.js';
+export * from './environment/changes.js';
+export * from './environment/document.js';
+export * from './environment/relay.js';
+export * from './environment/app-device.js';
+export * from './environment/identity.js';

package/dist/index.js

@@ -1,3 +1,8 @@
 export * from './profiles.js';
 export * from './settings.js';
 export * from './updates.js';
+export * from './environment/changes.js';
+export * from './environment/document.js';
+export * from './environment/relay.js';
+export * from './environment/app-device.js';
+export * from './environment/identity.js';

package/dist/metadata.d.ts

@@ -1,2 +1,2 @@
-import type { BuiltinAppProfileName } from '@mearl/browser-core';
-export declare const BUILTIN_APP_PROFILE_LABELS: Record<BuiltinAppProfileName, string>;
+/** App labels are supplied by installed capability definitions. */
+export declare const BUILTIN_APP_PROFILE_LABELS: Readonly<Record<string, string>>;

package/dist/metadata.js

@@ -1,3 +1,2 @@
-export const BUILTIN_APP_PROFILE_LABELS = {
-    fliggy: '飞猪', taobao: '手机淘宝', wechat: '微信', alipay: '支付宝',
-};
+/** App labels are supplied by installed capability definitions. */
+export const BUILTIN_APP_PROFILE_LABELS = Object.freeze({});

package/dist/profiles.d.ts

@@ -8,7 +8,9 @@ export declare function validateAppBridgeConfig(value: unknown): AppBridgeConfig
 export declare function mergeAppBridgeConfigs(...configs: Array<AppBridgeConfig | undefined>): AppBridgeConfig | undefined;
 /** 将声明式方法覆盖编译进运行时动作表，不修改档案的静态数据。 */
 export declare function applyAppBridgeConfig(actions: BridgeActionMap, config?: AppBridgeConfig): BridgeActionMap;
-export declare const APP_PROFILES: Record<BuiltinAppProfileName, AppProfile>;
+/** Built-ins provide UA/version identity; full environments come from capability packages. */
+/** Profiles are supplied by installed capabilities; the core has no App defaults. */
+export declare const APP_PROFILES: Readonly<Partial<Record<BuiltinAppProfileName, AppProfile>>>;
 export interface ResolveAppProfileOptions extends AppProfileOptions {
     os?: AppProfileOs;
     appVersion?: string;

package/dist/profiles.js

@@ -1,5 +1,4 @@
-import { DEVICE_PRESETS, APP_BRIDGE_BEHAVIORS, appProfileRevision, validateAppProfileDefinition, resolveEmulationConfig, } from '@mearl/browser-core';
-import { BUILTIN_APP_PROFILE_LABELS } from './metadata.js';
+import { DEVICE_PRESETS, isAppBridgeBehavior, appProfileRevision, validateAppProfileDefinition, resolveEmulationConfig, } from '@mearl/browser-core';
 function emptyActions() {
     return {
         open: [],
@@ -8,7 +7,7 @@ function emptyActions() {
         navigationBar: [],
         statusBar: [],
         systemInfo: [],
-        mtop: [],
+        protocol: [],
         kvGet: [],
         kvSet: [],
         kvDelete: [],
@@ -28,7 +27,7 @@ function mergeActions(...maps) {
         out.navigationBar.push(...(m.navigationBar ?? []));
         out.statusBar.push(...(m.statusBar ?? []));
         out.systemInfo.push(...m.systemInfo);
-        out.mtop.push(...m.mtop);
+        out.protocol.push(...m.protocol);
         out.kvGet.push(...(m.kvGet ?? []));
         out.kvSet.push(...(m.kvSet ?? []));
         out.kvDelete.push(...(m.kvDelete ?? []));
@@ -40,7 +39,6 @@ function mergeActions(...maps) {
     }
     return out;
 }
-const APP_BRIDGE_BEHAVIOR_SET = new Set(APP_BRIDGE_BEHAVIORS);
 const BRIDGE_ACTION_ARRAY_KEYS = [
     'open',
     'close',
@@ -48,7 +46,7 @@ const BRIDGE_ACTION_ARRAY_KEYS = [
     'navigationBar',
     'statusBar',
     'systemInfo',
-    'mtop',
+    'protocol',
     'kvGet',
     'kvSet',
     'kvDelete',
@@ -111,7 +109,7 @@ export function validateAppBridgeConfig(value) {
         if (Number(hasBehavior) + Number(hasResponse) + Number(hasNoop) !== 1) {
             throw new Error(`bridgeConfig.methods.${method} must define exactly one of behavior, response, or noop=true`);
         }
-        if (hasBehavior && !APP_BRIDGE_BEHAVIOR_SET.has(methodConfig.behavior)) {
+        if (hasBehavior && !isAppBridgeBehavior(methodConfig.behavior)) {
             throw new Error(`bridgeConfig.methods.${method} has an unsupported behavior`);
         }
         if (hasResponse && !isJsonValue(methodConfig.response)) {
@@ -174,16 +172,8 @@ export function applyAppBridgeConfig(actions, config) {
     return out;
 }
 /** Built-ins provide UA/version identity; full environments come from capability packages. */
-function basicProfile(name, appName, defaultAppVersion, uaTokens, uaFamily) {
-    return { name, label: BUILTIN_APP_PROFILE_LABELS[name], appName, defaultAppVersion, uaTokens,
-        ...(uaFamily && { uaFamily }), globals: {}, bridges: [], activeEvents: [], actions: emptyActions(), schemes: [] };
-}
-export const APP_PROFILES = {
-    fliggy: basicProfile('fliggy', 'LX', '10.0.9', ['AliTrip/{v}', 'WindVane/8.7.0']),
-    taobao: basicProfile('taobao', 'TB', '10.65.0', ['WindVane/8.7.0']),
-    wechat: basicProfile('wechat', 'WeChat', '8.0.58', [], 'wechatMiniProgram'),
-    alipay: { ...basicProfile('alipay', 'AP', '10.8.0', ['AlipayClient/{v}']), policies: { navigatorLanguage: true, defaultLanguage: 'zh-CN' } },
-};
+/** Profiles are supplied by installed capabilities; the core has no App defaults. */
+export const APP_PROFILES = Object.freeze({});
 /** 构造容器 UA。os 默认 ios；uaTokens 中的 {v} 替换为 appVersion */
 export function buildAppProfileUa(profile, options = {}) {
     const os = options.os ??
@@ -199,36 +189,21 @@ export function buildAppProfileUa(profile, options = {}) {
             .replaceAll('{deviceModel}', deviceModel)
             .replaceAll('{language}', options.language ?? profile.policies?.defaultLanguage ?? 'zh-Hans');
     }
-    if (profile.uaFamily === 'wechatMiniProgram') {
-        if (os === 'android') {
-            return `Mozilla/5.0 (Linux; Android 17; ${deviceModel}; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/152.0.0.0 Mobile MicroMessenger/${version} WeChat/arm64 NetType/WIFI Language/zh_CN miniProgram`;
-        }
-        return `Mozilla/5.0 (iPhone; CPU iPhone OS 18_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 MicroMessenger/${version} NetType/WIFI Language/zh_CN miniProgram`;
-    }
-    const tokens = profile.uaTokens.map(t => t.replaceAll('{v}', version)).filter(Boolean);
-    const tail = `${tokens.length > 0 ? ` ${tokens.join(' ')}` : ''}${profile.policies?.navigatorLanguage ? ` Language/${options.language ?? profile.policies.defaultLanguage ?? 'zh-CN'}` : ''}`;
-    if (os === 'android') {
-        return `Mozilla/5.0 (Linux; Android 17; ${deviceModel}) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/152.0.0.0 Mobile Safari/537.36 AliApp(${profile.appName}/${version})${tail}`;
-    }
-    return `Mozilla/5.0 (iPhone; CPU iPhone OS 18_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) AliApp(${profile.appName}/${version})${tail}`;
+    return os === 'android'
+        ? `Mozilla/5.0 (Linux; Android 17; ${deviceModel}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/152.0.0.0 Mobile Safari/537.36`
+        : 'Mozilla/5.0 (iPhone; CPU iPhone OS 18_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.6 Mobile/15E148 Safari/604.1';
 }
 /**
  * 解析容器档案为可下发配置。
  * @throws profile 名不存在时抛错，错误信息列出全部可用档案
  */
 export function listBuiltinAppProfiles() {
-    return Object.values(APP_PROFILES).map(definition => ({
-        id: definition.name,
-        label: definition.label,
-        source: 'builtin',
-        revision: appProfileRevision(definition),
-        definition,
-    }));
+    return [];
 }
 export function resolveAppProfile(name, options = {}, pinnedDefinition) {
     const definition = pinnedDefinition ?? APP_PROFILES[name];
     if (!definition || definition.name !== name) {
-        throw new Error(`Unknown app profile "${name}". Available: ${Object.keys(APP_PROFILES).join(', ')}`);
+        throw new Error(`Unknown app profile "${name}". Install an App simulation capability first.`);
     }
     return resolveAppProfileDefinition(definition, options);
 }
@@ -257,7 +232,7 @@ export function resolveAppProfileDefinition(definition, options = {}) {
     if (options.language !== undefined &&
         profile.policies?.languages &&
         !profile.policies.languages.includes(options.language)) {
-        throw new Error(`Unsupported ${profile.settingsGroup === 'alipay' ? 'Alipay' : profile.label} language. Use ${profile.policies.languages.join(', ')}.`);
+        throw new Error(`Unsupported ${profile.label} language. Use ${profile.policies.languages.join(', ')}.`);
     }
     const os = options.os ??
         (options.devicePreset ? DEVICE_PRESETS[options.devicePreset]?.appProfileOs : undefined) ??
@@ -272,10 +247,9 @@ export function resolveAppProfileDefinition(definition, options = {}) {
     });
     const deviceModel = options.deviceModel ?? DEVICE_PRESETS[devicePreset].appProfileModel;
     const globals = profile.pageRuntime || profile.bridges.length > 0 || Object.keys(profile.globals).length > 0 ? {
-        ...profile.globals,
+        ...Object.fromEntries(Object.entries(profile.globals).map(([key, value]) => [key, value.replaceAll('{deviceModel}', deviceModel).replaceAll('{v}', version)])),
         __APP_NAME__: profile.appName,
         __APP_VERSION__: version,
-        __FLI_DEVICE_MODEL__: deviceModel,
         __DEVICE_MODEL__: deviceModel,
     } : {};
     const ua = buildAppProfileUa(profile, { ...options, os, deviceModel });
@@ -294,6 +268,8 @@ export function resolveAppProfileDefinition(definition, options = {}) {
             },
             policies: profile.policies ?? {},
             settings: profile.settings ?? [],
+            settingsUi: profile.settingsUi,
+            settingsGroup: profile.settingsGroup,
             profile: profile.name,
             label: profile.label,
             globals,
@@ -319,14 +295,13 @@ export function resolveAppProfileDefinition(definition, options = {}) {
             schemes: profile.schemes,
             ...(profile.miniProgram && { miniProgram: profile.miniProgram }),
             ...(profile.imagePicker && { imagePicker: profile.imagePicker }),
-            ...(profile.geolocation && { geolocation: profile.geolocation }),
             ...(profile.overlay && { overlay: profile.overlay }),
             ...(profile.popBeforeOpenParam && { popBeforeOpenParam: profile.popBeforeOpenParam }),
             ...(profile.messageEvent && { messageEvent: profile.messageEvent }),
             ...(profile.nativeBack && { nativeBack: profile.nativeBack }),
             ...(profile.layerUrlProxy && { layerUrlProxy: profile.layerUrlProxy }),
             ...(profile.urlSyncHostSuffixes && { urlSyncHostSuffixes: profile.urlSyncHostSuffixes }),
-            ...(profile.forceH5Mtop && { forceH5Mtop: true }),
+            ...(profile.runtimeOptions && { runtimeOptions: JSON.parse(JSON.stringify(profile.runtimeOptions)) }),
             simulateSystemBars: false,
             externalDeviceChrome: false,
             rootContainer: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mearl/app-profiles",
-  "version": "3.0.0-beta.1",
-  "description": "Basic App user agents and declarative profile compilation",
+  "version": "3.0.0-beta.10",
+  "description": "Declarative App profile compilation for installed capabilities",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,14 +24,14 @@
   ],
   "license": "Apache-2.0",
   "dependencies": {
-    "@mearl/browser-core": "3.0.0-beta.1"
+    "@mearl/browser-core": "3.0.0-beta.10"
   },
   "devDependencies": {
     "typescript": "^5.8.3"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/F-loat/mearl.git",
+    "url": "git+https://github.com/mearlhq/mearl.git",
     "directory": "packages/app-profiles"
   },
   "scripts": {