@mearl/app-profiles 3.0.0-beta.5 → 3.0.0-beta.8

package/README.md

@@ -14,7 +14,7 @@ export function compileInstalledApp(definition: AppProfile) {
 
 resolveAppProfileUpdate、rebuildAppProfileConfig 和 updateAppProfileSetting 保持显式选项、设备外观及方法覆盖的优先级。preset 默认值由宿主传入，用户已有选择继续优先；能力包安装成功不等于默认配置已经应用。
 
-完整 App 行为由能力包声明并安装到受控页面；真实设备授权仍由相应宿主能力执行。拆分与验收进度见 [迁移说明](../../docs/migration.md)。
+App 行为由能力包声明并安装到受控页面；页面代码和宿主处理器通过 [能力包模型](../../docs/capability-model.md) 关联。
 
 ## Agent 能力发现
 

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/profiles.js

@@ -1,4 +1,4 @@
-import { DEVICE_PRESETS, APP_BRIDGE_BEHAVIORS, appProfileRevision, validateAppProfileDefinition, resolveEmulationConfig, } from '@mearl/browser-core';
+import { DEVICE_PRESETS, isAppBridgeBehavior, appProfileRevision, validateAppProfileDefinition, resolveEmulationConfig, } from '@mearl/browser-core';
 function emptyActions() {
     return {
         open: [],
@@ -7,7 +7,7 @@ function emptyActions() {
         navigationBar: [],
         statusBar: [],
         systemInfo: [],
-        mtop: [],
+        protocol: [],
         kvGet: [],
         kvSet: [],
         kvDelete: [],
@@ -27,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 ?? []));
@@ -39,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',
@@ -47,7 +46,7 @@ const BRIDGE_ACTION_ARRAY_KEYS = [
     'navigationBar',
     'statusBar',
     'systemInfo',
-    'mtop',
+    'protocol',
     'kvGet',
     'kvSet',
     'kvDelete',
@@ -110,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)) {
@@ -296,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,6 +1,6 @@
 {
   "name": "@mearl/app-profiles",
-  "version": "3.0.0-beta.5",
+  "version": "3.0.0-beta.8",
   "description": "Declarative App profile compilation for installed capabilities",
   "type": "module",
   "main": "dist/index.js",
@@ -24,14 +24,14 @@
   ],
   "license": "Apache-2.0",
   "dependencies": {
-    "@mearl/browser-core": "3.0.0-beta.5"
+    "@mearl/browser-core": "3.0.0-beta.8"
   },
   "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": {