@mearl/preset 3.0.0-beta.1 → 3.0.0-beta.10

package/README.md

@@ -1,10 +1,14 @@
 # @mearl/preset
 
-浏览器包的准备与本地存储见 [能力包](../../docs/browser-bundles.md)，整套原子激活与 App 实现映射见 [浏览器 Preset](../../docs/browser-presets.md)。这两类能力通过 `@mearl/preset/bundles` 导出。
+[English](README.md) | [简体中文](README.zh-CN.md)
 
-浏览器和 Node 共用一次继承解析及资源下载，见 [整套资源准备](../../docs/preset-preparation.md)。`preparePreset` 返回完整确切图与兼容的浏览器投影；Node 模块选择直接复用同批字节，准备过程不执行代码或安装外部环境。
+See the [capability model](../../docs/capability-model.md) for 3.x declarations, configuration, catalogs, and object storage. Contributions infer supported targets; optional Preset `targets` selects a subset. Operations and logins belong to packages; configuration overrides belong to Presets and users.
 
-主入口在浏览器和 Node 中共享 preset 清单校验与继承解析，没有文件系统、网络、凭据或浏览器权限副作用；清单加载由调用方提供。可选子入口 `@mearl/preset/bundles` 提供资源校验、受限下载和显式调用的浏览器本地存储，见 [能力包说明](../../docs/browser-bundles.md)。
+See [browser bundles](../../docs/browser-bundles.md) for preparation and local storage, and [browser Presets](../../docs/browser-presets.md) for atomic activation and App implementation mappings. Both are exported through `@mearl/preset/bundles`.
+
+Browser and Node share one inheritance resolution and resource download; see [complete resource preparation](../../docs/preset-preparation.md). `preparePreset` returns the full exact graph and a compatible browser projection. Node module selection reuses the same bytes. Preparation executes no code and installs no external environment.
+
+The main entry shares preset validation and inheritance resolution across browsers and Node, without filesystem, network, credential, or browser permission side effects. Callers supply manifest loading. Optional `@mearl/preset/bundles` provides resource validation, bounded downloads, and explicitly invoked browser-local storage; see [browser bundles](../../docs/browser-bundles.md).
 
 ```ts
 import { resolvePreset, mergePresetDefaults } from '@mearl/preset';
@@ -21,11 +25,11 @@ const preset = await resolvePreset('https://example.com/presets/team.json', {
 const effectiveSettings = mergePresetDefaults(preset.defaults, userSettings);
 ```
 
-加载器负责检查来源、响应大小、重定向、认证和取消请求；上例仅演示合同。浏览器加载器应根据产品来源策略限制 URL，解析器不会把 HTTP(S)/file 形式的 URL 自动视为可信。
+Loaders check source policy, response size, redirects, authentication, and cancellation; the example only demonstrates the contract. Browser loaders should restrict URLs according to product source policies. The resolver does not automatically trust HTTP(S)/file URLs.
 
-Node 模块快照与宿主加载合同见 [Node 能力包](../../docs/node-capabilities.md)。
+See [Node capabilities](../../docs/node-capabilities.md) for module snapshots and host loading contracts.
 
-## 清单
+## Manifest
 
 ```json
 {
@@ -35,7 +39,7 @@ Node 模块快照与宿主加载合同见 [Node 能力包](../../docs/node-capab
   "extends": { "source": "../base/preset.json", "version": "^1" },
   "requires": { "mearlApi": "^1" },
   "packages": {
-    "capture": { "source": "./capture/package.json", "runtimes": ["browser"] },
+    "capture": { "source": "./capture/package.json", "targets": ["browser"] },
     "unused": { "enabled": false }
   },
   "skills": {},
@@ -45,14 +49,58 @@ Node 模块快照与宿主加载合同见 [Node 能力包](../../docs/node-capab
 }
 ```
 
-- 单继承，最多 32 层；拒绝循环和不满足的父版本/API 要求。`version` 是确切 semver，组件 `version` 是版本要求，具体安装版本留给安装器解析。
-- packages、skills、providers 按 ID 合并，子级字段覆盖同 ID 声明；数组整体替换。启用项最终必须存在 source，`enabled:false` 保留停用声明。
-- 组件 `dependsOn` 引用同类组件 ID；检查最终继承图中的缺失、停用和循环依赖。它不表示 runtime 兼容或安装已完成。
-- source 相对声明它的清单解析；子级只修改版本时不会改变继承 source 的基准 URL。
-- defaults 递归合并对象，数组、标量和 null 替换；用户覆盖单独保存，在解析结果上应用。
-- 权限汇总去重，结果仅表示需求；必须由浏览器安装器另行取得实际授权。
-- appProfiles 是 App ID 到实现标识的覆盖映射。具体档案是否存在、所需包是否可执行，由后续能力目录校验，解析器不宣称已验证模拟效果。
-- 结果保留父级到子级的确切版本链和各组件最近声明来源，加载失败不会生成部分成功的结果。
-- 拒绝未知字段、非 JSON 配置和原型污染键。清单总量不超过 256 Ki UTF-16 code units，defaults 最大嵌套 32 层。
-
-本包尚不包含完整 preset 安装器、preset 锁文件持久化或 UI。浏览器宿主和 setup 需要复用同一解析结果接续资源准备、权限、注册与激活；能力包本地存储只负责已校验快照的事务替换。
+- Single inheritance, at most 32 levels; cycles and unmet parent version/API requirements are rejected. `version` is exact semver; component `version` is a version requirement, with concrete installation versions resolved by installers.
+- packages, skills, and providers merge by ID; child fields override the same ID, while arrays replace entirely. Enabled entries must ultimately have a source; `enabled:false` retains a disabled declaration.
+- Component `dependsOn` references IDs of the same component type. The final inherited graph checks missing, disabled, and cyclic dependencies. This does not establish runtime compatibility or completed installation.
+- source resolves relative to the declaring manifest. A child changing only the version does not alter an inherited source's base URL.
+- Skills may declare up to 16 previous sources in `migrateFrom`, resolved relative to the declaring manifest. Children replace the whole list; an empty array clears it. Installers migrate only with a matching source receipt, valid Skill identity, and setup ownership of all associated plugins. Manual registrations, shared manual aliases, and other sources remain and report conflicts. Source matching still checks refs strictly.
+- defaults recursively merges objects; arrays, scalars, and null replace values. User overrides are saved separately and applied to the resolved result.
+- Permissions are aggregated and deduplicated as requirements only; browser installers obtain actual authorization separately.
+- appProfiles maps App IDs to implementation identifiers. Later capability catalogs verify profile existence and package executability; the resolver does not claim simulation validation.
+- Results retain the exact parent-to-child version chain and each component's latest declaration source. Loading failures do not produce partial success.
+- Unknown fields, non-JSON configuration, and prototype-pollution keys are rejected. Total manifests are limited to 256 Ki UTF-16 code units; defaults nesting to 32 levels.
+
+This package owns generic manifest parsing, validation, and resource graphs, without installation or UI. Browser hosts and setup own full installation, preset lock persistence, permissions, registration, and activation; see the [installation host](../../docs/preset-installation.md). Bundle-local storage transactionally replaces validated snapshots.
+
+The Skill manager's optional `readSources(scope, cwd)` returns manager-verified source receipts matching setup's `TrackedSkillSource`. CLI and Native installation status share this reader. Managers persist, validate, and invalidate their supplementary records; public hosts still verify sources, refs, manifest identity, and managed ownership. Without it, the standard Skills lockfile is read.
+
+## Tool catalogs
+
+Presets can register additional installable tool catalogs through `defaults.extension.toolCatalogs`:
+
+```json
+{
+  "defaults": {
+    "extension": {
+      "toolCatalogs": {
+        "team": {
+          "url": "https://tools.example.com/toolbox.json",
+          "label": "Team"
+        }
+      }
+    }
+  }
+}
+```
+
+Use absolute HTTPS URLs (loopback HTTP is allowed for local development), with at most 16 catalogs. Use stable IDs; child presets can override only `url` or `label`, or disable a parent catalog with `enabled: false`. The official catalog always remains first; `official` is reserved. Declare cross-origin domains in `permissions.origins` and obtain access through the existing authorization flow.
+
+Catalog JSON shares the official structure, limited to 256 entries and 256 KiB:
+
+```json
+{
+  "tools": [{
+    "id": "plugin:team-tool",
+    "plugin": "team-tool",
+    "repository": "example/skills",
+    "skill": "team-tool",
+    "title": "Team tool",
+    "description": "A tool for the team",
+    "icon": "wrench"
+  }]
+}
+```
+
+`repository` also supports HTTPS/SSH Git sources and pinned refs such as `git@code.example.com:team/skills.git#release/v3`, passed unchanged to the preset-selected Skills manager. Manifests reject shell arguments, credentials, and local paths, and execute no embedded code. Listing tools does not install them.
+
+Sources load concurrently and cache independently. Retry refreshes the current catalog; failure retains its cache without blocking other sources. Identical plugin IDs and sources deduplicate. Conflicting repositories or Skills for one ID retain the higher-priority catalog and report a conflict. Lower-priority install buttons wait for earlier catalogs to finish checking, so load order cannot change installation targets. Replaced or disabled catalogs and late responses do not remain in the current list.

package/README.zh-CN.md

@@ -0,0 +1,106 @@
+# @mearl/preset
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+3.x 的声明、配置、能力目录及对象存储设计见 [能力包模型](../../docs/capability-model.zh-CN.md)。包支持的位置从贡献推导，Preset 的可选 `targets` 仅选择启用子集；操作和登录定义归包，配置覆盖归 Preset 与用户。
+
+浏览器包的准备与本地存储见 [能力包](../../docs/browser-bundles.zh-CN.md)，整套原子激活与 App 实现映射见 [浏览器 Preset](../../docs/browser-presets.zh-CN.md)。这两类能力通过 `@mearl/preset/bundles` 导出。
+
+浏览器和 Node 共用一次继承解析及资源下载，见 [整套资源准备](../../docs/preset-preparation.zh-CN.md)。`preparePreset` 返回完整确切图与兼容的浏览器投影；Node 模块选择直接复用同批字节，准备过程不执行代码或安装外部环境。
+
+主入口在浏览器和 Node 中共享 preset 清单校验与继承解析，没有文件系统、网络、凭据或浏览器权限副作用；清单加载由调用方提供。可选子入口 `@mearl/preset/bundles` 提供资源校验、受限下载和显式调用的浏览器本地存储，见 [能力包说明](../../docs/browser-bundles.zh-CN.md)。
+
+```ts
+import { resolvePreset, mergePresetDefaults } from '@mearl/preset';
+
+const preset = await resolvePreset('https://example.com/presets/team.json', {
+  mearlApiVersion: '1.0.0',
+  async load(source) {
+    const response = await fetch(source);
+    if (!response.ok) throw new Error(`Preset load failed: ${response.status}`);
+    return response.json();
+  },
+});
+
+const effectiveSettings = mergePresetDefaults(preset.defaults, userSettings);
+```
+
+加载器负责检查来源、响应大小、重定向、认证和取消请求；上例仅演示合同。浏览器加载器应根据产品来源策略限制 URL，解析器不会把 HTTP(S)/file 形式的 URL 自动视为可信。
+
+Node 模块快照与宿主加载合同见 [Node 能力包](../../docs/node-capabilities.zh-CN.md)。
+
+## 清单
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "team",
+  "version": "1.0.0",
+  "extends": { "source": "../base/preset.json", "version": "^1" },
+  "requires": { "mearlApi": "^1" },
+  "packages": {
+    "capture": { "source": "./capture/package.json", "targets": ["browser"] },
+    "unused": { "enabled": false }
+  },
+  "skills": {},
+  "providers": {},
+  "defaults": { "simulation": { "app": "sample" } },
+  "permissions": { "origins": ["https://*.example.com/*"] }
+}
+```
+
+- 单继承，最多 32 层；拒绝循环和不满足的父版本/API 要求。`version` 是确切 semver，组件 `version` 是版本要求，具体安装版本留给安装器解析。
+- packages、skills、providers 按 ID 合并，子级字段覆盖同 ID 声明；数组整体替换。启用项最终必须存在 source，`enabled:false` 保留停用声明。
+- 组件 `dependsOn` 引用同类组件 ID；检查最终继承图中的缺失、停用和循环依赖。它不表示 runtime 兼容或安装已完成。
+- source 相对声明它的清单解析；子级只修改版本时不会改变继承 source 的基准 URL。
+- Skill 可声明 `migrateFrom` 旧来源列表（最多 16 项），相对地址按声明清单解析；子级整体覆盖，空数组清除。安装器仅在来源收据匹配旧来源、Skill 身份有效且所有关联插件均由 setup 托管时迁移。手动注册、共享的手动别名或其他来源保留并报告冲突；来源匹配仍严格检查 ref。
+- defaults 递归合并对象，数组、标量和 null 替换；用户覆盖单独保存，在解析结果上应用。
+- 权限汇总去重，结果仅表示需求；必须由浏览器安装器另行取得实际授权。
+- appProfiles 是 App ID 到实现标识的覆盖映射。具体档案是否存在、所需包是否可执行，由后续能力目录校验，解析器不宣称已验证模拟效果。
+- 结果保留父级到子级的确切版本链和各组件最近声明来源，加载失败不会生成部分成功的结果。
+- 拒绝未知字段、非 JSON 配置和原型污染键。清单总量不超过 256 Ki UTF-16 code units，defaults 最大嵌套 32 层。
+
+本包负责通用清单解析、校验和资源图，不执行安装或展示 UI。完整安装器、preset 锁文件持久化、权限、注册与激活由浏览器宿主及 setup 提供，见 [安装宿主](../../docs/preset-installation.zh-CN.md)；能力包本地存储负责已校验快照的事务替换。
+
+Skill manager 的可选 `readSources(scope, cwd)` 返回该管理器核验过的来源收据，结构与 setup 的 `TrackedSkillSource` 一致。CLI 与 Native 安装状态共用该读取接口；管理器负责持久化、校验和失效自身补充记录，公共宿主继续核对来源、ref、清单身份与托管归属。未提供时读取标准 Skills 锁文件。
+
+## 工具目录
+
+Preset 可通过 `defaults.extension.toolCatalogs` 注册额外的可安装工具目录：
+
+```json
+{
+  "defaults": {
+    "extension": {
+      "toolCatalogs": {
+        "team": {
+          "url": "https://tools.example.com/toolbox.json",
+          "label": "Team"
+        }
+      }
+    }
+  }
+}
+```
+
+目录使用绝对 HTTPS URL（本机开发允许 loopback HTTP），最多 16 个。使用稳定的目录 ID，子 preset 可只覆盖 `url` 或 `label`，或设置 `enabled: false` 禁用父级目录。官方目录始终保留且优先，不能使用保留 ID `official`。需要跨域访问时在 preset 的 `permissions.origins` 声明相应域名，由现有授权流程取得权限。
+
+目录 JSON 与官方目录使用同一结构，最多 256 项、256 KiB：
+
+```json
+{
+  "tools": [{
+    "id": "plugin:team-tool",
+    "plugin": "team-tool",
+    "repository": "example/skills",
+    "skill": "team-tool",
+    "title": "Team tool",
+    "description": "A tool for the team",
+    "icon": "wrench"
+  }]
+}
+```
+
+`repository` 也支持 HTTPS/SSH Git 来源和固定 ref（例如 `git@code.example.com:team/skills.git#release/v3`），安装时原样交给 preset 选择的 Skills 管理器。清单不接受 shell 参数、凭据或本地文件路径，也不执行其中的代码；列出工具不会自动安装。
+
+各来源并发读取、独立缓存，重试时刷新当前目录；失败时保留该来源已有缓存，其他来源仍可使用。相同插件 ID 与安装来源去重；同 ID 指向不同仓库或 Skill 时保留优先目录并提示冲突。较低优先目录的安装按钮会等待前面的目录完成检查，避免加载顺序改变安装目标。更换或禁用目录后，旧来源和迟到响应不会留在当前列表。

package/dist/browserControls.d.ts

@@ -0,0 +1,29 @@
+import { type PreparedBundle } from './bundle.js';
+import { type BrowserUiText } from './requestUi.js';
+import { type NetworkRoutePlan } from './networkRoutes.js';
+export interface BrowserSegmentedControl {
+    schemaVersion: 1;
+    id: string;
+    kind: 'segmented';
+    label: BrowserUiText;
+    description: BrowserUiText;
+    defaultValue: string;
+    aliases?: string[];
+    messages: {
+        changed: BrowserUiText;
+        failed: BrowserUiText;
+    };
+    options: Array<{
+        value: string;
+        label: BrowserUiText;
+        networkRoutes: NetworkRoutePlan;
+    }>;
+}
+export interface SelectedBrowserControl {
+    bundleId: string;
+    revision: string;
+    definition: BrowserSegmentedControl;
+}
+export declare function validateBrowserControl(input: unknown): BrowserSegmentedControl;
+/** The network-route surface has one owner, so competing packages cannot silently overwrite it. */
+export declare function selectBrowserControl(bundles: PreparedBundle[]): SelectedBrowserControl | undefined;

package/dist/browserControls.js

@@ -0,0 +1,54 @@
+import { BundleError, readBundleJson } from './bundle.js';
+import { validateBrowserUiText } from './requestUi.js';
+import { parseNetworkRoutePlan } from './networkRoutes.js';
+const id = /^[a-z][a-zA-Z0-9_.-]{0,79}$/;
+function fields(value, names) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !names.includes(key)))
+        throw new BundleError('BUNDLE_INVALID', 'Invalid browser control');
+}
+export function validateBrowserControl(input) {
+    fields(input, ['schemaVersion', 'id', 'kind', 'label', 'description', 'defaultValue', 'aliases', 'messages', 'options']);
+    if (input.schemaVersion !== 1 || input.kind !== 'segmented' || typeof input.id !== 'string' || !id.test(input.id) || typeof input.defaultValue !== 'string' || !id.test(input.defaultValue))
+        throw new BundleError('BUNDLE_INVALID', 'Invalid segmented control');
+    validateBrowserUiText(input.label);
+    validateBrowserUiText(input.description);
+    fields(input.messages, ['changed', 'failed']);
+    validateBrowserUiText(input.messages.changed);
+    validateBrowserUiText(input.messages.failed);
+    if (input.aliases !== undefined && (!Array.isArray(input.aliases) || input.aliases.length > 8 || new Set(input.aliases).size !== input.aliases.length || input.aliases.some(alias => typeof alias !== 'string' || !id.test(alias))))
+        throw new BundleError('BUNDLE_INVALID', 'Invalid browser control aliases');
+    if (!Array.isArray(input.options) || input.options.length < 2 || input.options.length > 8)
+        throw new BundleError('BUNDLE_INVALID', 'Invalid browser control options');
+    const values = new Set();
+    const options = input.options.map(option => {
+        fields(option, ['value', 'label', 'networkRoutes']);
+        if (typeof option.value !== 'string' || !id.test(option.value) || values.has(option.value))
+            throw new BundleError('BUNDLE_INVALID', 'Invalid browser control option');
+        values.add(option.value);
+        validateBrowserUiText(option.label);
+        try {
+            return { value: option.value, label: structuredClone(option.label), networkRoutes: parseNetworkRoutePlan(option.networkRoutes) };
+        }
+        catch {
+            throw new BundleError('BUNDLE_INVALID', 'Invalid control network route plan');
+        }
+    });
+    if (!values.has(input.defaultValue) || options.find(option => option.value === input.defaultValue).networkRoutes.routes.length)
+        throw new BundleError('BUNDLE_INVALID', 'The default option must clear network routes');
+    if (new TextEncoder().encode(JSON.stringify(input)).byteLength > 65536)
+        throw new BundleError('BUNDLE_QUOTA', 'Browser control exceeds 64 KiB');
+    return { schemaVersion: 1, id: input.id, kind: 'segmented', label: structuredClone(input.label), description: structuredClone(input.description), defaultValue: input.defaultValue, messages: structuredClone(input.messages), options, ...(input.aliases ? { aliases: [...input.aliases] } : {}) };
+}
+/** The network-route surface has one owner, so competing packages cannot silently overwrite it. */
+export function selectBrowserControl(bundles) {
+    let selected;
+    for (const bundle of bundles) {
+        const resource = bundle.manifest.contributions?.browserControls;
+        if (!resource)
+            continue;
+        if (selected)
+            throw new BundleError('BUNDLE_CONFLICT', 'Browser network control has multiple providers');
+        selected = { bundleId: bundle.manifest.id, revision: bundle.revision, definition: validateBrowserControl(readBundleJson(bundle, resource)) };
+    }
+    return selected;
+}

package/dist/browserPreset.js

@@ -1,15 +1,18 @@
+import { selectBrowserControl } from './browserControls.js';
 import { BundleError, MAX_BROWSER_STORAGE_BYTES, verifyBundle } from './bundle.js';
 import { satisfies } from 'semver';
-import { preparePresetPackages, presetPackages, presetSnapshotRevision, verifyPresetGraph } from './prepare.js';
+import { preparePresetPackages, presetPackages, presetSnapshotRevision, verifyPresetGraph, verifyPackageTargets } from './prepare.js';
 /** Core browser defaults also need synchronization when no browser package is declared. */
 export function presetRequiresBrowser(preset) {
-    return Object.values(preset.packages).some(entry => entry.enabled !== false && entry.runtimes?.includes('browser')) || Object.keys(preset.appProfiles).length > 0 || Object.keys(preset.defaults).some(key => key === 'simulation' || key === 'extension' || key === 'services');
+    return Object.values(preset.packages).some(entry => entry.enabled !== false && entry.targets?.includes('browser')) || Object.keys(preset.appProfiles).length > 0 || Object.keys(preset.defaults).some(key => key === 'simulation' || key === 'extension' || key === 'services');
 }
 /** Browser selection can be derived from the same accepted batch without another download. */
 export async function browserPresetSnapshot(source, manifests, preset, bundles) {
     const ids = new Set(presetPackages(preset, ['browser']).map(([id]) => id));
     const selected = bundles.filter(bundle => ids.has(bundle.manifest.id));
-    const data = { source, manifests, bundleRevisions: Object.fromEntries(selected.map(bundle => [bundle.manifest.id, bundle.revision])) };
+    selectBrowserControl(selected);
+    const packageTargets = Object.fromEntries(Object.entries(preset.packages).filter(([, entry]) => entry.enabled !== false).map(([id, entry]) => [id, entry.targets]));
+    const data = { source, manifests, bundleRevisions: Object.fromEntries(selected.map(bundle => [bundle.manifest.id, bundle.revision])), packageTargets };
     return { snapshot: { ...data, revision: await presetSnapshotRevision(data) }, preset, bundles: selected };
 }
 export async function prepareBrowserPreset(source, options) {
@@ -48,5 +51,7 @@ export async function verifyPreparedBrowserPreset(value, mearlApiVersion) {
         return graph.snapshot.bundleRevisions[bundle.manifest.id] !== bundle.revision || entry?.source !== bundle.source || (entry.version && !satisfies(bundle.manifest.version, entry.version));
     }))
         throw new BundleError('BUNDLE_INTEGRITY', 'Browser activation requires every exact package');
+    selectBrowserControl(bundles);
+    verifyPackageTargets(graph.preset, bundles);
     return { ...graph, bundles };
 }

package/dist/browserViews.d.ts

@@ -16,7 +16,7 @@ export interface BrowserViewDefinition {
     entry: string;
     actions: Record<string, BrowserViewAction>;
     preferences?: Record<string, {
-        legacyKey?: string;
+        shared?: 'editor.highlight' | 'json.viewMode' | 'json.shortcuts' | 'code.shortcuts';
         area?: 'local' | 'session';
     }>;
     transports?: Record<string, BrowserViewTransport>;

package/dist/browserViews.js

@@ -30,13 +30,13 @@ export function validateBrowserView(input) {
     if (value.preferences !== undefined) {
         const aliases = new Set();
         for (const [, preference] of entries(value.preferences, 32)) {
-            fields(preference, ['legacyKey', 'area']);
+            fields(preference, ['shared', 'area']);
             if (preference.area !== undefined && preference.area !== 'local' && preference.area !== 'session')
                 invalid('Invalid browser view preference area');
-            if (preference.legacyKey !== undefined) {
-                if (typeof preference.legacyKey !== 'string' || !/^[a-z][a-zA-Z0-9:_.-]{0,127}$/.test(preference.legacyKey) || aliases.has(preference.legacyKey))
+            if (preference.shared !== undefined) {
+                if (typeof preference.shared !== 'string' || !['editor.highlight', 'json.viewMode', 'json.shortcuts', 'code.shortcuts'].includes(preference.shared) || aliases.has(preference.shared))
                     invalid('Invalid browser view preference alias');
-                aliases.add(preference.legacyKey);
+                aliases.add(preference.shared);
             }
         }
     }
@@ -200,5 +200,5 @@ export function buildBrowserViewPage(html) {
     if (typeof html !== 'string' || !html.trim())
         invalid('Browser view entry must not be empty');
     const policy = "default-src 'none'; script-src 'unsafe-inline' 'unsafe-eval'; style-src 'unsafe-inline'; img-src data: blob:; font-src data:; connect-src 'none'; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";
-    return `<!doctype html><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="${policy}"><script>(${installBrowserViewBridge.toString()})();</script>${html}`;
+    return `<!doctype html><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="${policy}"><script>(${installBrowserViewBridge.toString()})();</script>${html}<style data-mearl-view-surface>html,body{background:transparent!important}</style>`;
 }

package/dist/bundle.d.ts

@@ -14,17 +14,20 @@ export interface BundleManifest {
     requires?: {
         mearlApi: string;
     };
+    defaults?: import('./types.js').JsonObject;
     resources: Record<string, {
         sha256: string;
         byteLength: number;
     }>;
     contributions?: {
-        appProfiles: string[];
+        appProfiles?: string[];
         pageRuntimes?: Record<string, string>;
         nodeRuntimes?: Record<string, CapabilityRuntimeDeclaration>;
         browserRuntimes?: Record<string, CapabilityRuntimeDeclaration>;
+        extension?: string;
         requestUi?: string;
         browserViews?: Record<string, string>;
+        browserControls?: string;
     };
 }
 export interface CapabilityRuntimeDeclaration {

package/dist/bundle.js

@@ -1,5 +1,6 @@
 import { satisfies, valid, validRange } from 'semver';
 import { clonePresetDefaults } from './manifest.js';
+import { validateBrowserControl } from './browserControls.js';
 export const MAX_BUNDLE_BYTES = 16 * 1024 * 1024;
 export const MAX_BUNDLE_MANIFEST_BYTES = 64 * 1024;
 export const MAX_BROWSER_STORAGE_BYTES = 64 * 1024 * 1024;
@@ -47,7 +48,9 @@ export function validateBundleManifest(value, mearlApiVersion) {
     catch {
         invalid('Expected a JSON manifest');
     }
-    fields(json, ['schemaVersion', 'id', 'version', 'requires', 'resources', 'contributions']);
+    fields(json, ['schemaVersion', 'id', 'version', 'requires', 'defaults', 'resources', 'contributions']);
+    if (json.defaults !== undefined)
+        json.defaults = clonePresetDefaults(json.defaults);
     if (json.schemaVersion !== 1 || typeof json.id !== 'string' || !/^[a-z][a-z0-9-]{0,79}$/.test(json.id))
         invalid('Invalid bundle identity');
     if (typeof json.version !== 'string' || valid(json.version) !== json.version)
@@ -79,7 +82,17 @@ export function validateBundleManifest(value, mearlApiVersion) {
             throw new BundleError('BUNDLE_QUOTA', 'Bundle resources exceed 16 MiB');
     }
     if (json.contributions !== undefined) {
-        fields(json.contributions, ['appProfiles', 'pageRuntimes', 'nodeRuntimes', 'browserRuntimes', 'requestUi', 'browserViews']);
+        fields(json.contributions, ['appProfiles', 'pageRuntimes', 'nodeRuntimes', 'browserRuntimes', 'extension', 'requestUi', 'browserViews', 'browserControls']);
+        const extension = json.contributions.extension;
+        if (extension !== undefined && (typeof extension !== 'string' || !Object.hasOwn(json.resources, extension)))
+            invalid('Extension contributions must reference a declared resource');
+        if (typeof extension === 'string' && json.resources[extension].byteLength > MAX_REQUEST_UI_BYTES)
+            throw new BundleError('BUNDLE_QUOTA', 'Extension contributions exceed 64 KiB');
+        const controls = json.contributions.browserControls;
+        if (controls !== undefined && (typeof controls !== 'string' || !Object.hasOwn(json.resources, controls)))
+            invalid('Browser controls must reference a declared resource');
+        if (typeof controls === 'string' && json.resources[controls].byteLength > MAX_REQUEST_UI_BYTES)
+            throw new BundleError('BUNDLE_QUOTA', 'Browser controls exceed 64 KiB');
         if (json.contributions.requestUi !== undefined && (typeof json.contributions.requestUi !== 'string' || !Object.hasOwn(json.resources, json.contributions.requestUi)))
             invalid('Request UI must reference a declared resource');
         if (typeof json.contributions.requestUi === 'string' && json.resources[json.contributions.requestUi].byteLength > MAX_REQUEST_UI_BYTES)
@@ -93,7 +106,7 @@ export function validateBundleManifest(value, mearlApiVersion) {
                     throw new BundleError('BUNDLE_QUOTA', 'Browser view definition exceeds 64 KiB');
             }
         }
-        const profiles = json.contributions.appProfiles;
+        const profiles = json.contributions.appProfiles === undefined ? [] : json.contributions.appProfiles;
         if (!Array.isArray(profiles) || profiles.some(name => typeof name !== 'string' || !Object.hasOwn(json.resources, name)) ||
             new Set(profiles).size !== profiles.length)
             invalid('App profiles must reference distinct declared resources');
@@ -188,7 +201,10 @@ export async function prepareBundle(source, options) {
         resources[name] = resource;
     }
     options.signal?.throwIfAborted();
-    return { source, manifest, revision: await manifestRevision(source, manifest), resources };
+    const prepared = { source, manifest, revision: await manifestRevision(source, manifest), resources };
+    if (manifest.contributions?.browserControls)
+        validateBrowserControl(readBundleJson(prepared, manifest.contributions.browserControls));
+    return prepared;
 }
 /** Revalidates persisted snapshots without network access and returns independent resource buffers. */
 export async function verifyBundle(bundle, mearlApiVersion) {
@@ -215,5 +231,8 @@ export async function verifyBundle(bundle, mearlApiVersion) {
         if (await bundleDigest(resources[name]) !== expected.sha256)
             throw new BundleError('BUNDLE_INTEGRITY', `Stored resource integrity check failed: ${name}`);
     }
-    return { source, manifest, revision, resources };
+    const prepared = { source, manifest, revision, resources };
+    if (manifest.contributions?.browserControls)
+        validateBrowserControl(readBundleJson(prepared, manifest.contributions.browserControls));
+    return prepared;
 }