@mearl/app-profiles 0.0.0-stage → 3.0.0-beta.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @mearl/app-profiles
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+内置飞猪、淘宝、微信、支付宝的基础 UA/版本档案。四份档案保留当前 UA 格式和版本替换，不内置桥对象、App 设置、scheme 路由、业务响应和完整容器实现。
+
+```ts
+import { resolveAppProfile } from '@mearl/app-profiles';
+const profile = resolveAppProfile('taobao', { os: 'android', appVersion: '10.65.0' });
+console.log(profile.ua);
+```
+
+宿主可以向 resolveAppProfile 或 resolveAppProfileDefinition 提供已校验的动态定义；编译器保留桥、设置及 pageRuntime 描述，不执行能力代码。定义与选项被复制并绑定 revision，插件升级不直接改写活动文档。
+
+resolveAppProfileUpdate、rebuildAppProfileConfig 和 updateAppProfileSetting 保持显式选项、设备外观及方法覆盖的优先级。preset 默认值由宿主传入，用户已有选择继续优先；能力包安装成功不等于默认配置已经应用。
+
+完整 App 行为由能力包声明并安装到受控页面；真实设备授权仍由相应宿主能力执行。本包与基础运行时的迁入没有切换当前产品的实现来源，完整产品验收进度见 [迁移说明](../../docs/migration.md)。

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './profiles.js';
+export * from './settings.js';
+export * from './updates.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './profiles.js';
+export * from './settings.js';
+export * from './updates.js';

package/dist/metadata.d.ts

@@ -0,0 +1,2 @@
+import type { BuiltinAppProfileName } from '@mearl/browser-core';
+export declare const BUILTIN_APP_PROFILE_LABELS: Record<BuiltinAppProfileName, string>;

package/dist/metadata.js

@@ -0,0 +1,3 @@
+export const BUILTIN_APP_PROFILE_LABELS = {
+    fliggy: '飞猪', taobao: '手机淘宝', wechat: '微信', alipay: '支付宝',
+};

package/dist/profiles.d.ts

@@ -0,0 +1,41 @@
+import { type AppProfileCatalogEntry, type AppProfileDefinition, type AppProfileOptions, type BuiltinAppProfileName, type AppBridgeConfig, type AppProfileName, type BridgeActionMap, type BrowserDevicePresetName, type InjectedAppProfileConfig } from '@mearl/browser-core';
+export type { AppProfileName };
+export type AppProfileOs = 'ios' | 'android';
+export type AppProfile = AppProfileDefinition;
+/** 校验并复制用户提供的声明式桥配置。 */
+export declare function validateAppBridgeConfig(value: unknown): AppBridgeConfig;
+/** 后传配置按方法覆盖前传配置，供扩展本地配置与单次 Agent 参数组合。 */
+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>;
+export interface ResolveAppProfileOptions extends AppProfileOptions {
+    os?: AppProfileOs;
+    appVersion?: string;
+    language?: string;
+    /** App 读取到的机型名；不影响所选设备的物理外观。 */
+    deviceModel?: string;
+    /** App 系统栏与安全区使用的设备 preset，默认跟随 os 的推荐设备。 */
+    devicePreset?: BrowserDevicePresetName;
+    orientation?: 'portrait' | 'landscape';
+    /** 按方法覆盖档案内置桥配置 */
+    bridgeConfig?: AppBridgeConfig;
+}
+/** resolve 结果：UA + 注入配置 + 推荐设备模拟 preset */
+export interface ResolvedAppProfile {
+    profile: AppProfileName;
+    label: string;
+    ua: string;
+    injected: InjectedAppProfileConfig;
+    /** 推荐配合的视口 preset（browser-core DEVICE_PRESETS 键名） */
+    recommendedPreset: BrowserDevicePresetName;
+}
+/** 构造容器 UA。os 默认 ios；uaTokens 中的 {v} 替换为 appVersion */
+export declare function buildAppProfileUa(profile: AppProfile, options?: ResolveAppProfileOptions): string;
+/**
+ * 解析容器档案为可下发配置。
+ * @throws profile 名不存在时抛错，错误信息列出全部可用档案
+ */
+export declare function listBuiltinAppProfiles(): AppProfileCatalogEntry[];
+export declare function resolveAppProfile(name: string, options?: ResolveAppProfileOptions, pinnedDefinition?: AppProfileDefinition): ResolvedAppProfile;
+export declare function resolveAppProfileDefinition(definition: AppProfileDefinition, options?: ResolveAppProfileOptions): ResolvedAppProfile;

package/dist/profiles.js

@@ -0,0 +1,358 @@
+import { DEVICE_PRESETS, APP_BRIDGE_BEHAVIORS, appProfileRevision, validateAppProfileDefinition, resolveEmulationConfig, } from '@mearl/browser-core';
+import { BUILTIN_APP_PROFILE_LABELS } from './metadata.js';
+function emptyActions() {
+    return {
+        open: [],
+        close: [],
+        title: [],
+        navigationBar: [],
+        statusBar: [],
+        systemInfo: [],
+        mtop: [],
+        kvGet: [],
+        kvSet: [],
+        kvDelete: [],
+        pageContext: [],
+        responses: {},
+        behaviors: {},
+        noop: [],
+        silent: [],
+    };
+}
+function mergeActions(...maps) {
+    const out = emptyActions();
+    for (const m of maps) {
+        out.open.push(...m.open);
+        out.close.push(...m.close);
+        out.title.push(...m.title);
+        out.navigationBar.push(...(m.navigationBar ?? []));
+        out.statusBar.push(...(m.statusBar ?? []));
+        out.systemInfo.push(...m.systemInfo);
+        out.mtop.push(...m.mtop);
+        out.kvGet.push(...(m.kvGet ?? []));
+        out.kvSet.push(...(m.kvSet ?? []));
+        out.kvDelete.push(...(m.kvDelete ?? []));
+        out.pageContext.push(...(m.pageContext ?? []));
+        Object.assign(out.responses, m.responses ?? {});
+        Object.assign(out.behaviors, m.behaviors ?? {});
+        out.noop.push(...m.noop);
+        out.silent.push(...(m.silent ?? []));
+    }
+    return out;
+}
+const APP_BRIDGE_BEHAVIOR_SET = new Set(APP_BRIDGE_BEHAVIORS);
+const BRIDGE_ACTION_ARRAY_KEYS = [
+    'open',
+    'close',
+    'title',
+    'navigationBar',
+    'statusBar',
+    'systemInfo',
+    'mtop',
+    'kvGet',
+    'kvSet',
+    'kvDelete',
+    'pageContext',
+    'noop',
+];
+function isJsonValue(value, seen = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value !== 'object')
+        return false;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    const valid = Array.isArray(value)
+        ? value.every(item => isJsonValue(item, seen))
+        : Object.values(value).every(item => isJsonValue(item, seen));
+    seen.delete(value);
+    return valid;
+}
+/** 校验并复制用户提供的声明式桥配置。 */
+export function validateAppBridgeConfig(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('bridgeConfig must be an object');
+    }
+    const root = value;
+    if (Object.keys(root).some(key => key !== 'methods')) {
+        throw new Error('bridgeConfig only supports the "methods" field');
+    }
+    if (!root.methods || typeof root.methods !== 'object' || Array.isArray(root.methods)) {
+        throw new Error('bridgeConfig.methods must be an object');
+    }
+    const entries = Object.entries(root.methods);
+    if (entries.length > 200)
+        throw new Error('bridgeConfig supports at most 200 methods');
+    const methods = {};
+    for (const [method, rawConfig] of entries) {
+        if (!method.trim() || method.length > 200) {
+            throw new Error('bridgeConfig method names must contain 1-200 characters');
+        }
+        if (method === '__proto__' || method === 'prototype' || method === 'constructor') {
+            throw new Error(`bridgeConfig method name "${method}" is reserved`);
+        }
+        if (!rawConfig || typeof rawConfig !== 'object' || Array.isArray(rawConfig)) {
+            throw new Error(`bridgeConfig.methods.${method} must be an object`);
+        }
+        const methodConfig = rawConfig;
+        const supportedKeys = new Set(['behavior', 'response', 'noop', 'silent']);
+        if (Object.keys(methodConfig).some(key => !supportedKeys.has(key))) {
+            throw new Error(`bridgeConfig.methods.${method} contains an unsupported field`);
+        }
+        if ('behavior' in methodConfig && typeof methodConfig.behavior !== 'string') {
+            throw new Error(`bridgeConfig.methods.${method}.behavior must be a string`);
+        }
+        const hasBehavior = typeof methodConfig.behavior === 'string';
+        const hasResponse = Object.prototype.hasOwnProperty.call(methodConfig, 'response');
+        const hasNoop = methodConfig.noop === true;
+        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)) {
+            throw new Error(`bridgeConfig.methods.${method} has an unsupported behavior`);
+        }
+        if (hasResponse && !isJsonValue(methodConfig.response)) {
+            throw new Error(`bridgeConfig.methods.${method}.response must be valid JSON data`);
+        }
+        if ('noop' in methodConfig && methodConfig.noop !== true) {
+            throw new Error(`bridgeConfig.methods.${method}.noop must be true when provided`);
+        }
+        if ('silent' in methodConfig && typeof methodConfig.silent !== 'boolean') {
+            throw new Error(`bridgeConfig.methods.${method}.silent must be a boolean`);
+        }
+        methods[method] = {
+            ...(hasBehavior && { behavior: methodConfig.behavior }),
+            ...(hasResponse && { response: JSON.parse(JSON.stringify(methodConfig.response)) }),
+            ...(hasNoop && { noop: true }),
+            ...(methodConfig.silent === true && { silent: true }),
+        };
+    }
+    const normalized = { methods };
+    if (JSON.stringify(normalized).length > 65_536) {
+        throw new Error('bridgeConfig must not exceed 64 KiB');
+    }
+    return normalized;
+}
+/** 后传配置按方法覆盖前传配置，供扩展本地配置与单次 Agent 参数组合。 */
+export function mergeAppBridgeConfigs(...configs) {
+    const present = configs.filter((config) => config !== undefined);
+    if (present.length === 0)
+        return undefined;
+    const methods = {};
+    for (const config of present)
+        Object.assign(methods, validateAppBridgeConfig(config).methods);
+    return validateAppBridgeConfig({ methods });
+}
+/** 将声明式方法覆盖编译进运行时动作表，不修改档案的静态数据。 */
+export function applyAppBridgeConfig(actions, config) {
+    const out = mergeActions(actions);
+    if (!config)
+        return out;
+    const { methods } = validateAppBridgeConfig(config);
+    for (const [method, methodConfig] of Object.entries(methods)) {
+        for (const key of BRIDGE_ACTION_ARRAY_KEYS) {
+            const values = out[key];
+            if (values)
+                out[key] = values.filter(value => value !== method);
+        }
+        out.silent = (out.silent ?? []).filter(value => value !== method);
+        delete out.responses?.[method];
+        delete out.behaviors?.[method];
+        if (methodConfig.behavior)
+            out.behaviors[method] = methodConfig.behavior;
+        else if (Object.prototype.hasOwnProperty.call(methodConfig, 'response')) {
+            out.responses[method] = methodConfig.response;
+        }
+        else if (methodConfig.noop)
+            out.noop.push(method);
+        if (methodConfig.silent)
+            out.silent.push(method);
+    }
+    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' } },
+};
+/** 构造容器 UA。os 默认 ios；uaTokens 中的 {v} 替换为 appVersion */
+export function buildAppProfileUa(profile, options = {}) {
+    const os = options.os ??
+        (options.devicePreset ? DEVICE_PRESETS[options.devicePreset]?.appProfileOs : undefined) ??
+        'ios';
+    const version = options.appVersion ?? profile.defaultAppVersion;
+    const deviceModel = options.deviceModel ??
+        (options.devicePreset ? DEVICE_PRESETS[options.devicePreset]?.appProfileModel : undefined) ??
+        'Pixel 11';
+    if (profile.uaTemplate) {
+        return profile.uaTemplate[os]
+            .replaceAll('{v}', version)
+            .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}`;
+}
+/**
+ * 解析容器档案为可下发配置。
+ * @throws profile 名不存在时抛错，错误信息列出全部可用档案
+ */
+export function listBuiltinAppProfiles() {
+    return Object.values(APP_PROFILES).map(definition => ({
+        id: definition.name,
+        label: definition.label,
+        source: 'builtin',
+        revision: appProfileRevision(definition),
+        definition,
+    }));
+}
+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(', ')}`);
+    }
+    return resolveAppProfileDefinition(definition, options);
+}
+export function resolveAppProfileDefinition(definition, options = {}) {
+    const profile = validateAppProfileDefinition(definition);
+    if (options.lockDefinition !== undefined && typeof options.lockDefinition !== 'boolean')
+        throw new Error('lockDefinition must be a boolean');
+    if (options.os !== undefined && options.os !== 'ios' && options.os !== 'android')
+        throw new Error('Invalid app profile OS');
+    if (options.orientation !== undefined &&
+        options.orientation !== 'portrait' &&
+        options.orientation !== 'landscape')
+        throw new Error('Invalid app profile orientation');
+    if (options.devicePreset !== undefined && !Object.hasOwn(DEVICE_PRESETS, options.devicePreset))
+        throw new Error('Invalid app profile device preset');
+    for (const [key, maximum] of [
+        ['appVersion', 100],
+        ['deviceModel', 200],
+        ['language', 100],
+    ]) {
+        const value = options[key];
+        if (value !== undefined &&
+            (typeof value !== 'string' || !value || value.length > maximum || /[\r\n]/.test(value)))
+            throw new Error(`Invalid app profile ${key}`);
+    }
+    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(', ')}.`);
+    }
+    const os = options.os ??
+        (options.devicePreset ? DEVICE_PRESETS[options.devicePreset]?.appProfileOs : undefined) ??
+        'ios';
+    const version = options.appVersion ?? profile.defaultAppVersion;
+    const recommendedPreset = os === 'android' ? 'pixel-11' : 'iphone-17-pro';
+    const devicePreset = options.devicePreset ?? recommendedPreset;
+    const emulation = resolveEmulationConfig({
+        enabled: true,
+        preset: devicePreset,
+        orientation: options.orientation,
+    });
+    const deviceModel = options.deviceModel ?? DEVICE_PRESETS[devicePreset].appProfileModel;
+    const globals = profile.pageRuntime || profile.bridges.length > 0 || Object.keys(profile.globals).length > 0 ? {
+        ...profile.globals,
+        __APP_NAME__: profile.appName,
+        __APP_VERSION__: version,
+        __FLI_DEVICE_MODEL__: deviceModel,
+        __DEVICE_MODEL__: deviceModel,
+    } : {};
+    const ua = buildAppProfileUa(profile, { ...options, os, deviceModel });
+    return {
+        profile: profile.name,
+        label: profile.label,
+        ua,
+        injected: {
+            ...(profile.pageRuntime && { pageRuntime: profile.pageRuntime }),
+            binding: {
+                version: 1,
+                revision: appProfileRevision(profile),
+                definition: profile,
+                options: JSON.parse(JSON.stringify({ ...options, os, appVersion: version, deviceModel, devicePreset })),
+                explicitOptions: JSON.parse(JSON.stringify(Object.fromEntries(Object.entries(options).filter(([key]) => key !== 'bridgeConfig')))),
+            },
+            policies: profile.policies ?? {},
+            settings: profile.settings ?? [],
+            profile: profile.name,
+            label: profile.label,
+            globals,
+            bridges: profile.bridges,
+            activeEvents: profile.activeEvents,
+            maxTouchPoints: 5,
+            statusBarHeight: emulation.safeAreaInsets.top,
+            safeAreaInsets: emulation.safeAreaInsets,
+            deviceAppearance: {
+                preset: devicePreset,
+                orientation: emulation.orientation,
+                cutout: emulation.appearance.cutout,
+            },
+            language: options.language ?? profile.policies?.defaultLanguage ?? 'zh-Hans',
+            // UA 随注入配置一起下发，供 DNR、页内运行时和动态 WebView 导航前刷新使用
+            userAgent: ua,
+            navigatorPlatform: os === 'android' ? 'Linux armv8l' : 'iPhone',
+            // systemInfo 使用产品系统版本；Safari UA 中的系统 token 可能是兼容性固定值。
+            platform: os === 'android' ? 'Android' : 'iOS',
+            systemVersion: os === 'android' ? '17' : '26.0',
+            clientType: os === 'android' ? 'android' : 'iphone',
+            actions: applyAppBridgeConfig(profile.actions, options.bridgeConfig),
+            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 }),
+            simulateSystemBars: false,
+            externalDeviceChrome: false,
+            rootContainer: {
+                enabled: false,
+                ...(profile.rootContainer?.statusBarHeightCookie && {
+                    initialCookies: [
+                        {
+                            ...profile.rootContainer.statusBarHeightCookie,
+                            value: String(emulation.safeAreaInsets.top),
+                        },
+                    ],
+                }),
+            },
+            titleBar: {
+                navigationBarHeight: os === 'android' ? 48 : 44,
+                backgroundColor: '#ffffff',
+                textColor: '#0f131a',
+                ...(profile.titleBarHiddenPathnames && {
+                    hiddenPathnames: profile.titleBarHiddenPathnames,
+                }),
+                ...(profile.statusBarBackgroundColors && {
+                    statusBarBackgroundColors: profile.statusBarBackgroundColors,
+                }),
+                ...(profile.titleBarHostStyles && { hostStyles: profile.titleBarHostStyles }),
+            },
+        },
+        recommendedPreset,
+    };
+}

package/dist/settings.d.ts

@@ -0,0 +1,9 @@
+import type { AppProfileOptions, AppProfileSetting, InjectedAppProfileConfig } from '@mearl/browser-core';
+export declare function readAppProfileSetting(config: InjectedAppProfileConfig, setting: AppProfileSetting): unknown;
+/** Settings write canonical options or method overrides; presentation state is derived. */
+export declare function updateAppProfileSetting(config: InjectedAppProfileConfig, id: string, value: unknown): {
+    config: InjectedAppProfileConfig;
+    options: AppProfileOptions;
+    responses?: Record<string, unknown>;
+    reload: boolean;
+};

package/dist/settings.js

@@ -0,0 +1,50 @@
+import { rebuildAppProfileConfig } from './updates.js';
+export function readAppProfileSetting(config, setting) {
+    if ('option' in setting.target)
+        return config.language;
+    const response = config.actions.responses?.[setting.target.method];
+    if (setting.target.field) {
+        return response && typeof response === 'object' && !Array.isArray(response)
+            ? response[setting.target.field]
+            : undefined;
+    }
+    return response;
+}
+/** Settings write canonical options or method overrides; presentation state is derived. */
+export function updateAppProfileSetting(config, id, value) {
+    const binding = config.binding;
+    const setting = binding?.definition.settings?.find(item => item.id === id);
+    if (!binding || !setting)
+        throw new Error('App profile setting is unavailable');
+    if ((setting.type === 'boolean' && typeof value !== 'boolean') ||
+        (setting.type === 'number' &&
+            (typeof value !== 'number' ||
+                !Number.isFinite(value) ||
+                (setting.minimum !== undefined && value < setting.minimum) ||
+                (setting.maximum !== undefined && value > setting.maximum))) ||
+        (['text', 'select'].includes(setting.type) && typeof value !== 'string') ||
+        (setting.type === 'select' && !setting.choices?.some(choice => choice.value === value))) {
+        throw new Error('Invalid app profile setting value');
+    }
+    if (JSON.stringify(value)?.length > 16_384 || value === undefined)
+        throw new Error('Invalid app profile setting value');
+    if ('option' in setting.target) {
+        const next = rebuildAppProfileConfig(config, { language: String(value) });
+        return { config: next, options: next.binding.options, reload: true };
+    }
+    const { method, field } = setting.target;
+    const old = config.actions.responses?.[method];
+    const response = field
+        ? { ...(old && typeof old === 'object' && !Array.isArray(old) ? old : {}), [field]: value }
+        : value;
+    const patch = {
+        methods: { [method]: { response, silent: config.actions.silent?.includes(method) === true } },
+    };
+    const next = rebuildAppProfileConfig(config, { bridgeConfig: patch });
+    return {
+        config: next,
+        options: next.binding.options,
+        responses: { [method]: response },
+        reload: false,
+    };
+}

package/dist/updates.d.ts

@@ -0,0 +1,16 @@
+import type { AppProfileDefinition, AppProfileOptions, InjectedAppProfileConfig } from '@mearl/browser-core';
+/** Definition lookup must not keep a navigation paused when the host or a plugin is unavailable. */
+export declare function findAppProfileDefinitionUpdate(current: InjectedAppProfileConfig, load: () => Promise<AppProfileDefinition>, timeoutMs?: number): Promise<AppProfileDefinition | undefined>;
+/** Host command envelopes never become part of a serialized profile binding. */
+export declare function mergeAppProfileOptions(...sources: Array<AppProfileOptions | undefined>): AppProfileOptions;
+export declare function getAppProfileExplicitOptions(config: InjectedAppProfileConfig): AppProfileOptions;
+/** Both hosts use the same precedence for saved choices, active choices and command overrides. */
+export declare function resolveAppProfileUpdate(name: string, { current, definition, defaults, options, deviceOptions, }?: {
+    current?: InjectedAppProfileConfig;
+    definition?: AppProfileDefinition;
+    defaults?: AppProfileOptions;
+    options?: AppProfileOptions;
+    deviceOptions?: AppProfileOptions;
+}): import("./profiles.js").ResolvedAppProfile;
+/** Recompile profile-owned fields while retaining the independently managed device layout. */
+export declare function rebuildAppProfileConfig(current: InjectedAppProfileConfig, options?: AppProfileOptions, definition?: AppProfileDefinition | undefined): InjectedAppProfileConfig;

package/dist/updates.js

@@ -0,0 +1,102 @@
+import { appProfileRevision } from '@mearl/browser-core';
+import { mergeAppBridgeConfigs, resolveAppProfile } from './profiles.js';
+const OPTION_KEYS = [
+    'os',
+    'appVersion',
+    'language',
+    'deviceModel',
+    'devicePreset',
+    'orientation',
+    'lockDefinition',
+];
+/** Definition lookup must not keep a navigation paused when the host or a plugin is unavailable. */
+export async function findAppProfileDefinitionUpdate(current, load, timeoutMs = 1500) {
+    if (!current.binding || current.binding.options.lockDefinition)
+        return undefined;
+    let timer;
+    try {
+        const definition = await Promise.race([
+            load(),
+            new Promise(resolve => {
+                timer = setTimeout(() => resolve(undefined), timeoutMs);
+            }),
+        ]);
+        // Removing a code provider does not replace a pinned full environment with a UA-only fallback.
+        if (current.binding.definition.pageRuntime && definition && !definition.pageRuntime)
+            return undefined;
+        return definition &&
+            definition.name === current.profile &&
+            appProfileRevision(definition) !== current.binding.revision
+            ? definition
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Host command envelopes never become part of a serialized profile binding. */
+export function mergeAppProfileOptions(...sources) {
+    const result = {};
+    for (const source of sources) {
+        if (!source)
+            continue;
+        for (const key of OPTION_KEYS) {
+            if (source[key] !== undefined)
+                Object.assign(result, { [key]: source[key] });
+        }
+        if (source.bridgeConfig !== undefined)
+            result.bridgeConfig = mergeAppBridgeConfigs(result.bridgeConfig, source.bridgeConfig);
+    }
+    return result;
+}
+export function getAppProfileExplicitOptions(config) {
+    return mergeAppProfileOptions(config.binding?.explicitOptions, {
+        bridgeConfig: config.binding?.options.bridgeConfig,
+    });
+}
+/** Both hosts use the same precedence for saved choices, active choices and command overrides. */
+export function resolveAppProfileUpdate(name, { current, definition, defaults, options, deviceOptions, } = {}) {
+    const active = current?.profile === name ? current : undefined;
+    const explicit = mergeAppProfileOptions(defaults, active ? getAppProfileExplicitOptions(active) : undefined, options);
+    const previousDevice = active?.binding?.options;
+    const effective = mergeAppProfileOptions(previousDevice && {
+        os: previousDevice.os,
+        deviceModel: previousDevice.deviceModel,
+        devicePreset: previousDevice.devicePreset,
+        orientation: previousDevice.orientation,
+    }, explicit, deviceOptions);
+    const resolved = resolveAppProfile(name, effective, definition ?? active?.binding?.definition);
+    resolved.injected.binding.explicitOptions = Object.fromEntries(Object.entries(explicit).filter(([key]) => key !== 'bridgeConfig'));
+    if (active?.hostCapabilities && (definition === undefined || definition === active.binding?.definition))
+        resolved.injected.hostCapabilities = structuredClone(active.hostCapabilities);
+    return resolved;
+}
+/** Recompile profile-owned fields while retaining the independently managed device layout. */
+export function rebuildAppProfileConfig(current, options = {}, definition = current.binding?.definition) {
+    const next = resolveAppProfileUpdate(current.profile, { current, definition, options }).injected;
+    return {
+        ...next,
+        animationMs: current.animationMs,
+        statusBarHeight: current.statusBarHeight,
+        safeAreaInsets: current.safeAreaInsets,
+        deviceAppearance: current.deviceAppearance,
+        simulateSystemBars: current.simulateSystemBars,
+        externalDeviceChrome: current.externalDeviceChrome,
+        rootContainer: {
+            ...next.rootContainer,
+            ...(next.rootContainer?.initialCookies && {
+                initialCookies: next.rootContainer.initialCookies.map(cookie => ({
+                    ...cookie,
+                    value: String(current.statusBarHeight),
+                })),
+            }),
+            enabled: current.rootContainer?.enabled ?? false,
+            ...(current.rootContainer?.splitScreen !== undefined && {
+                splitScreen: current.rootContainer.splitScreen,
+            }),
+        },
+    };
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@mearl/app-profiles",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "3.0.0-beta.1",
+  "description": "Basic App user agents and declarative profile compilation",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./metadata": {
+      "types": "./dist/metadata.d.ts",
+      "import": "./dist/metadata.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "keywords": [
+    "mearl"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@mearl/browser-core": "3.0.0-beta.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/F-loat/mearl.git",
+    "directory": "packages/app-profiles"
+  },
+  "scripts": {
+    "build": "rm -rf dist/ && tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }