@mearl/preset 3.0.0-beta.9 → 3.0.1

package/README.en.md

@@ -0,0 +1,110 @@
+# @mearl/preset
+
+[简体中文](README.md) | [English](README.en.md)
+
+Use a Preset to distribute a configured set of Mearl capabilities, Skills, and Providers. This package resolves the manifest and prepares the resources that browser and Node hosts use.
+
+See the [capability model](../../docs/capability-model.en.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.
+
+See [browser bundles](../../docs/browser-bundles.en.md) for preparation and local storage, and [browser Presets](../../docs/browser-presets.en.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.en.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.en.md).
+
+`@mearl/preset/pageRuntime` provides the page runtime host and source generation functions for standalone page injection scripts.
+
+```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);
+```
+
+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.
+
+See [Node capabilities](../../docs/node-capabilities.en.md) for module snapshots and host loading contracts.
+
+## Manifest
+
+```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/*"] }
+}
+```
+
+- 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.en.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.md

@@ -1,5 +1,9 @@
 # @mearl/preset
 
+[简体中文](README.md) | [English](README.en.md)
+
+用 Preset 将一组配置好的 Mearl 能力、Skills 和 Providers 一起分发。本包负责解析清单，并为浏览器与 Node 宿主准备资源。
+
 3.x 的声明、配置、能力目录及对象存储设计见 [能力包模型](../../docs/capability-model.md)。包支持的位置从贡献推导，Preset 的可选 `targets` 仅选择启用子集；操作和登录定义归包，配置覆盖归 Preset 与用户。
 
 浏览器包的准备与本地存储见 [能力包](../../docs/browser-bundles.md)，整套原子激活与 App 实现映射见 [浏览器 Preset](../../docs/browser-presets.md)。这两类能力通过 `@mearl/preset/bundles` 导出。
@@ -8,6 +12,8 @@
 
 主入口在浏览器和 Node 中共享 preset 清单校验与继承解析，没有文件系统、网络、凭据或浏览器权限副作用；清单加载由调用方提供。可选子入口 `@mearl/preset/bundles` 提供资源校验、受限下载和显式调用的浏览器本地存储，见 [能力包说明](../../docs/browser-bundles.md)。
 
+`@mearl/preset/pageRuntime` 为独立的页面注入脚本提供页面运行时宿主及注入源码生成函数。
+
 ```ts
 import { resolvePreset, mergePresetDefaults } from '@mearl/preset';
 
@@ -54,7 +60,7 @@ Node 模块快照与宿主加载合同见 [Node 能力包](../../docs/node-capab
 - Skill 可声明 `migrateFrom` 旧来源列表（最多 16 项），相对地址按声明清单解析；子级整体覆盖，空数组清除。安装器仅在来源收据匹配旧来源、Skill 身份有效且所有关联插件均由 setup 托管时迁移。手动注册、共享的手动别名或其他来源保留并报告冲突；来源匹配仍严格检查 ref。
 - defaults 递归合并对象，数组、标量和 null 替换；用户覆盖单独保存，在解析结果上应用。
 - 权限汇总去重，结果仅表示需求；必须由浏览器安装器另行取得实际授权。
-- appProfiles 是 App ID 到实现标识的覆盖映射。具体档案是否存在、所需包是否可执行，由后续能力目录校验，解析器不宣称已验证模拟效果。
+- appProfiles 是 App ID 到实现标识的覆盖映射。具体端模拟配置是否存在、所需包是否可执行，由后续能力目录校验，解析器不宣称已验证模拟效果。
 - 结果保留父级到子级的确切版本链和各组件最近声明来源，加载失败不会生成部分成功的结果。
 - 拒绝未知字段、非 JSON 配置和原型污染键。清单总量不超过 256 Ki UTF-16 code units，defaults 最大嵌套 32 层。
 

package/dist/browserPreset.js

@@ -1,19 +1,32 @@
 import { selectBrowserControl } from './browserControls.js';
 import { BundleError, MAX_BROWSER_STORAGE_BYTES, verifyBundle } from './bundle.js';
-import { satisfies } from 'semver';
-import { preparePresetPackages, presetPackages, presetSnapshotRevision, verifyPresetGraph, verifyPackageTargets } from './prepare.js';
+import satisfies from 'semver/functions/satisfies.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.targets?.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));
     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 };
+    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) {
     const prepared = await preparePresetPackages(source, options, ['browser']);
@@ -29,7 +42,9 @@ export async function verifyPreparedBrowserPreset(value, mearlApiVersion) {
         throw new BundleError('BUNDLE_QUOTA', 'Browser preset package count exceeds 64');
     let total = 0;
     for (const bundle of value.bundles) {
-        if (!bundle?.resources || typeof bundle.resources !== 'object' || Array.isArray(bundle.resources))
+        if (!bundle?.resources ||
+            typeof bundle.resources !== 'object' ||
+            Array.isArray(bundle.resources))
             throw new BundleError('BUNDLE_INVALID', 'Expected package resource buffers');
         const resources = Object.values(bundle.resources);
         if (resources.length > 64)
@@ -46,10 +61,14 @@ export async function verifyPreparedBrowserPreset(value, mearlApiVersion) {
         verifyBrowserPreset(value.snapshot, mearlApiVersion),
         Promise.all(value.bundles.map(bundle => verifyBundle(bundle, mearlApiVersion))),
     ]);
-    if (bundles.length !== Object.keys(graph.snapshot.bundleRevisions).length || new Set(bundles.map(bundle => bundle.manifest.id)).size !== bundles.length || bundles.some(bundle => {
-        const entry = graph.preset.packages[bundle.manifest.id];
-        return graph.snapshot.bundleRevisions[bundle.manifest.id] !== bundle.revision || entry?.source !== bundle.source || (entry.version && !satisfies(bundle.manifest.version, entry.version));
-    }))
+    if (bundles.length !== Object.keys(graph.snapshot.bundleRevisions).length ||
+        new Set(bundles.map(bundle => bundle.manifest.id)).size !== bundles.length ||
+        bundles.some(bundle => {
+            const entry = graph.preset.packages[bundle.manifest.id];
+            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);

package/dist/bundle.d.ts

@@ -48,7 +48,7 @@ export type BundleLoader = (source: string, options: BundleLoadOptions) => Promi
 export interface PrepareBundleOptions {
     load: BundleLoader;
     mearlApiVersion: string;
-    expectedId: string;
+    expectedId?: string;
     version?: string;
     signal?: AbortSignal;
 }
@@ -58,5 +58,7 @@ export declare function bundleDigest(bytes: Uint8Array): Promise<string>;
 export declare function readBundleJson(bundle: PreparedBundle, name: string): unknown;
 export declare function readBundleText(bundle: PreparedBundle, name: string): string;
 export declare function prepareBundle(source: string, options: PrepareBundleOptions): Promise<PreparedBundle>;
+/** Loads the resources declared by a validated manifest at its canonical source. */
+export declare function loadBundleResources(source: string, manifest: BundleManifest, options: Pick<PrepareBundleOptions, 'load' | 'signal'>): Promise<PreparedBundle>;
 /** Revalidates persisted snapshots without network access and returns independent resource buffers. */
 export declare function verifyBundle(bundle: PreparedBundle, mearlApiVersion: string): Promise<PreparedBundle>;

package/dist/bundle.js

@@ -1,4 +1,6 @@
-import { satisfies, valid, validRange } from 'semver';
+import satisfies from 'semver/functions/satisfies.js';
+import valid from 'semver/functions/valid.js';
+import validRange from 'semver/ranges/valid.js';
 import { clonePresetDefaults } from './manifest.js';
 import { validateBrowserControl } from './browserControls.js';
 export const MAX_BUNDLE_BYTES = 16 * 1024 * 1024;
@@ -18,7 +20,9 @@ function invalid(message) {
     throw new BundleError('BUNDLE_INVALID', message);
 }
 function fields(value, names) {
-    if (!value || typeof value !== 'object' || Array.isArray(value) ||
+    if (!value ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
         Object.keys(value).some(key => !names.includes(key)))
         invalid('Unexpected manifest structure');
 }
@@ -48,10 +52,20 @@ export function validateBundleManifest(value, mearlApiVersion) {
     catch {
         invalid('Expected a JSON manifest');
     }
-    fields(json, ['schemaVersion', 'id', 'version', 'requires', 'defaults', '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))
+    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)
         invalid('Expected an exact bundle version');
@@ -74,45 +88,77 @@ export function validateBundleManifest(value, mearlApiVersion) {
     for (const [name, resource] of resources) {
         path(name);
         fields(resource, ['sha256', 'byteLength']);
-        if (typeof resource.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(resource.sha256) ||
-            typeof resource.byteLength !== 'number' || !Number.isSafeInteger(resource.byteLength) || resource.byteLength < 0)
+        if (typeof resource.sha256 !== 'string' ||
+            !/^[a-f0-9]{64}$/.test(resource.sha256) ||
+            typeof resource.byteLength !== 'number' ||
+            !Number.isSafeInteger(resource.byteLength) ||
+            resource.byteLength < 0)
             invalid('Invalid resource metadata');
         total += resource.byteLength;
         if (total > MAX_BUNDLE_BYTES)
             throw new BundleError('BUNDLE_QUOTA', 'Bundle resources exceed 16 MiB');
     }
     if (json.contributions !== undefined) {
-        fields(json.contributions, ['appProfiles', 'pageRuntimes', 'nodeRuntimes', 'browserRuntimes', 'extension', 'requestUi', 'browserViews', 'browserControls']);
+        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)))
+        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)
+        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)))
+        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)
+        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)))
+        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)
+        if (typeof json.contributions.requestUi === 'string' &&
+            json.resources[json.contributions.requestUi].byteLength >
+                MAX_REQUEST_UI_BYTES)
             throw new BundleError('BUNDLE_QUOTA', 'Request UI exceeds 64 KiB');
         if (json.contributions.browserViews !== undefined) {
-            fields(json.contributions.browserViews, ['requestImport', 'requestCases', 'captureLauncher', 'captureController']);
+            fields(json.contributions.browserViews, [
+                'requestImport',
+                'requestCases',
+                'captureLauncher',
+                'captureController',
+            ]);
             for (const resource of Object.values(json.contributions.browserViews)) {
                 if (typeof resource !== 'string' || !Object.hasOwn(json.resources, resource))
                     invalid('Browser views must reference declared resources');
-                if (json.resources[resource].byteLength > MAX_REQUEST_UI_BYTES)
+                if (json.resources[resource].byteLength >
+                    MAX_REQUEST_UI_BYTES)
                     throw new BundleError('BUNDLE_QUOTA', 'Browser view definition exceeds 64 KiB');
             }
         }
         const profiles = json.contributions.appProfiles === undefined ? [] : json.contributions.appProfiles;
-        if (!Array.isArray(profiles) || profiles.some(name => typeof name !== 'string' || !Object.hasOwn(json.resources, name)) ||
+        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');
         const runtimes = json.contributions.pageRuntimes;
         if (runtimes !== undefined) {
-            if (!runtimes || typeof runtimes !== 'object' || Array.isArray(runtimes) || Object.entries(runtimes).some(([id, name]) => !/^[a-z][a-z0-9-]{0,79}$/.test(id) || typeof name !== 'string' || !Object.hasOwn(json.resources, name)))
+            if (!runtimes ||
+                typeof runtimes !== 'object' ||
+                Array.isArray(runtimes) ||
+                Object.entries(runtimes).some(([id, name]) => !/^[a-z][a-z0-9-]{0,79}$/.test(id) ||
+                    typeof name !== 'string' ||
+                    !Object.hasOwn(json.resources, name)))
                 invalid('Page runtimes must reference declared resources');
             for (const name of Object.values(runtimes)) {
                 const resource = json.resources[name];
@@ -125,15 +171,26 @@ export function validateBundleManifest(value, mearlApiVersion) {
             const label = kind === 'nodeRuntimes' ? 'Node' : 'Browser';
             if (runtimes === undefined)
                 continue;
-            if (!runtimes || typeof runtimes !== 'object' || Array.isArray(runtimes) || Object.keys(runtimes).length > 16)
+            if (!runtimes ||
+                typeof runtimes !== 'object' ||
+                Array.isArray(runtimes) ||
+                Object.keys(runtimes).length > 16)
                 invalid(`Invalid ${label} runtime declarations`);
             for (const [host, declaration] of Object.entries(runtimes)) {
                 if (!/^[a-z][a-z0-9-]{0,79}$/.test(host))
                     invalid(`Invalid ${label} runtime host`);
                 fields(declaration, ['entry', 'bindings']);
-                if (typeof declaration.entry !== 'string' || !Object.hasOwn(json.resources, declaration.entry) || !declaration.entry.endsWith('.cjs'))
+                if (typeof declaration.entry !== 'string' ||
+                    !Object.hasOwn(json.resources, declaration.entry) ||
+                    !declaration.entry.endsWith('.cjs'))
                     invalid(`${label} runtime entry must reference a declared CommonJS resource`);
-                if (!declaration.bindings || typeof declaration.bindings !== 'object' || Array.isArray(declaration.bindings) || Object.keys(declaration.bindings).length > 256 || Object.entries(declaration.bindings).some(([hook, handler]) => !/^[a-z][a-zA-Z0-9_.-]{0,127}$/.test(hook) || typeof handler !== 'string' || !/^[a-z][a-zA-Z0-9_.-]{0,127}$/.test(handler)))
+                if (!declaration.bindings ||
+                    typeof declaration.bindings !== 'object' ||
+                    Array.isArray(declaration.bindings) ||
+                    Object.keys(declaration.bindings).length > 256 ||
+                    Object.entries(declaration.bindings).some(([hook, handler]) => !/^[a-z][a-zA-Z0-9_.-]{0,127}$/.test(hook) ||
+                        typeof handler !== 'string' ||
+                        !/^[a-z][a-zA-Z0-9_.-]{0,127}$/.test(handler)))
                     invalid(`Invalid ${label} runtime bindings`);
             }
         }
@@ -143,7 +200,12 @@ export function validateBundleManifest(value, mearlApiVersion) {
     return json;
 }
 export async function bundleDigest(bytes) {
-    const digest = await crypto.subtle.digest('SHA-256', Uint8Array.from(bytes).buffer);
+    const buffer = bytes.buffer;
+    // WebCrypto snapshots fixed, non-shared input views before hashing asynchronously.
+    const data = buffer instanceof ArrayBuffer && !('resizable' in buffer && buffer.resizable)
+        ? new Uint8Array(buffer, bytes.byteOffset, bytes.byteLength)
+        : Uint8Array.from(bytes);
+    const digest = await crypto.subtle.digest('SHA-256', data);
     return Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('');
 }
 async function manifestRevision(source, manifest) {
@@ -172,7 +234,8 @@ export function readBundleText(bundle, name) {
 export async function prepareBundle(source, options) {
     options.signal?.throwIfAborted();
     source = bundleSourceUrl(source);
-    if (options.version !== undefined && (!options.version.trim() || validRange(options.version) === null))
+    if (options.version !== undefined &&
+        (!options.version.trim() || validRange(options.version) === null))
         invalid('Invalid requested bundle version');
     const bytes = Uint8Array.from(await options.load(source, { maxBytes: MAX_BUNDLE_MANIFEST_BYTES, signal: options.signal }));
     options.signal?.throwIfAborted();
@@ -186,22 +249,35 @@ export async function prepareBundle(source, options) {
         invalid('Expected a UTF-8 JSON manifest');
     }
     const manifest = validateBundleManifest(value, options.mearlApiVersion);
-    if (manifest.id !== options.expectedId)
+    if (options.expectedId !== undefined && manifest.id !== options.expectedId)
         invalid('Bundle identity does not match the requested package');
     if (options.version && !satisfies(manifest.version, options.version))
         throw new BundleError('BUNDLE_INCOMPATIBLE', 'Bundle version does not satisfy the requested range');
+    return loadBundleResources(source, manifest, options);
+}
+/** Loads the resources declared by a validated manifest at its canonical source. */
+export async function loadBundleResources(source, manifest, options) {
     const resources = {};
     for (const [name, expected] of Object.entries(manifest.resources)) {
         options.signal?.throwIfAborted();
-        const resource = Uint8Array.from(await options.load(new URL(name, source).href, { maxBytes: expected.byteLength, signal: options.signal }));
+        const resource = Uint8Array.from(await options.load(new URL(name, source).href, {
+            maxBytes: expected.byteLength,
+            signal: options.signal,
+        }));
         options.signal?.throwIfAborted();
-        if (resource.byteLength !== expected.byteLength || await bundleDigest(resource) !== expected.sha256) {
+        if (resource.byteLength !== expected.byteLength ||
+            (await bundleDigest(resource)) !== expected.sha256) {
             throw new BundleError('BUNDLE_INTEGRITY', `Resource integrity check failed: ${name}`);
         }
         resources[name] = resource;
     }
     options.signal?.throwIfAborted();
-    const prepared = { 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;
@@ -211,7 +287,8 @@ export async function verifyBundle(bundle, mearlApiVersion) {
     const source = bundleSourceUrl(bundle.source);
     const manifest = validateBundleManifest(bundle.manifest, mearlApiVersion);
     const revision = bundle.revision;
-    if (!bundle.resources || typeof bundle.resources !== 'object' ||
+    if (!bundle.resources ||
+        typeof bundle.resources !== 'object' ||
         Object.keys(bundle.resources).length !== Object.keys(manifest.resources).length)
         invalid('Stored resource set does not match the manifest');
     const resources = {};
@@ -225,10 +302,10 @@ export async function verifyBundle(bundle, mearlApiVersion) {
         }
         resources[name] = bytes;
     }
-    if (await manifestRevision(source, manifest) !== revision)
+    if ((await manifestRevision(source, manifest)) !== revision)
         throw new BundleError('BUNDLE_INTEGRITY', 'Stored manifest revision does not match');
     for (const [name, expected] of Object.entries(manifest.resources)) {
-        if (await bundleDigest(resources[name]) !== expected.sha256)
+        if ((await bundleDigest(resources[name])) !== expected.sha256)
             throw new BundleError('BUNDLE_INTEGRITY', `Stored resource integrity check failed: ${name}`);
     }
     const prepared = { source, manifest, revision, resources };

package/dist/bundleStore.js

@@ -292,9 +292,9 @@ export class BrowserBundleStore {
     /** Pins the verified selection while reading its package from the same IndexedDB snapshot. */
     async profileBinding(name) {
         const activation = await this.activePreset();
-        const target = activation?.preset.appProfiles[name];
-        if (!activation || !target)
+        if (!activation || !Object.hasOwn(activation.preset.appProfiles, name))
             return undefined;
+        const target = activation.preset.appProfiles[name];
         const id = target.split('/')[0];
         const database = await this.open();
         let objects = new Map();

package/dist/bundles.d.ts

@@ -3,6 +3,7 @@ export type { BundleManifest, PreparedBundle, BundleLoader, BundleLoadOptions, P
 export { selectExtensionContributions, validateExtensionContributions } from './extensionContributions.js';
 export type { ExtensionContributions } from './extensionContributions.js';
 export { createBundleFetchLoader } from './bundleFetch.js';
+export { parseProfileSource, resolveProfileSource } from './profileSource.js';
 export { BrowserBundleStore } from './bundleStore.js';
 export type { BrowserPresetInstallation } from './bundleStore.js';
 export { prepareBrowserPreset, presetRequiresBrowser, verifyBrowserPreset, verifyPreparedBrowserPreset } from './browserPreset.js';

package/dist/bundles.js

@@ -1,6 +1,7 @@
 export { BundleError, MAX_BUNDLE_BYTES, MAX_BUNDLE_MANIFEST_BYTES, MAX_BROWSER_STORAGE_BYTES, MAX_PAGE_RUNTIME_BYTES, MAX_REQUEST_UI_BYTES, bundleDigest, bundleSourceUrl, prepareBundle, readBundleJson, readBundleText, validateBundleManifest, verifyBundle, } from './bundle.js';
 export { selectExtensionContributions, validateExtensionContributions } from './extensionContributions.js';
 export { createBundleFetchLoader } from './bundleFetch.js';
+export { parseProfileSource, resolveProfileSource } from './profileSource.js';
 export { BrowserBundleStore } from './bundleStore.js';
 export { prepareBrowserPreset, presetRequiresBrowser, verifyBrowserPreset, verifyPreparedBrowserPreset } from './browserPreset.js';
 export { preparePreset, verifyPreset, verifyPreparedPreset } from './preset.js';

package/dist/management.js

@@ -1,19 +1,32 @@
-import { valid, validRange, satisfies, subset } from 'semver';
+import satisfies from 'semver/functions/satisfies.js';
+import valid from 'semver/functions/valid.js';
+import subset from 'semver/ranges/subset.js';
+import validRange from 'semver/ranges/valid.js';
 import { isJsonObject, PresetError } from './manifest.js';
 /** Declarative installation guidance; never accepts commands, arguments or executable hooks. */
 export function parseSetupManagement(value) {
     if (value === undefined)
         return;
-    const invalid = () => { throw new PresetError('PRESET_INVALID', 'Invalid defaults.management.setup declaration'); };
-    if (!isJsonObject(value) || Object.keys(value).some(key => key !== 'setup') || !isJsonObject(value.setup))
+    const invalid = () => {
+        throw new PresetError('PRESET_INVALID', 'Invalid defaults.management.setup declaration');
+    };
+    if (!isJsonObject(value) ||
+        Object.keys(value).some(key => key !== 'setup') ||
+        !isJsonObject(value.setup))
         return invalid();
     const setup = value.setup;
     if (Object.keys(setup).some(key => !['package', 'version', 'registry', 'runtime'].includes(key)) ||
-        typeof setup.package !== 'string' || setup.package.length > 214 || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(setup.package) ||
-        typeof setup.version !== 'string' || setup.version.length > 64 || !(valid(setup.version) === setup.version || /^[a-z][a-z0-9.-]*$/.test(setup.version)))
+        typeof setup.package !== 'string' ||
+        setup.package.length > 214 ||
+        !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(setup.package) ||
+        typeof setup.version !== 'string' ||
+        setup.version.length > 64 ||
+        !(valid(setup.version) === setup.version || /^[a-z][a-z0-9.-]*$/.test(setup.version)))
         return invalid();
     if (setup.registry !== undefined) {
-        if (typeof setup.registry !== 'string' || setup.registry.length > 2048 || !/^https:\/\/[a-zA-Z0-9./:_-]+$/.test(setup.registry))
+        if (typeof setup.registry !== 'string' ||
+            setup.registry.length > 2048 ||
+            !/^https:\/\/[a-zA-Z0-9./:_-]+$/.test(setup.registry))
             return invalid();
         try {
             const url = new URL(setup.registry);
@@ -24,7 +37,8 @@ export function parseSetupManagement(value) {
             return invalid();
         }
     }
-    if (setup.runtime !== undefined && (typeof setup.runtime !== 'string' || setup.runtime.length > 128 || !validRange(setup.runtime)))
+    if (setup.runtime !== undefined &&
+        (typeof setup.runtime !== 'string' || setup.runtime.length > 128 || !validRange(setup.runtime)))
         return invalid();
     return { ...setup };
 }
@@ -32,5 +46,7 @@ export function setupManagementCommand(setup) {
     return `npx${setup.registry ? ` --registry=${setup.registry}` : ''} ${setup.package}@${setup.version}`;
 }
 export function setupRuntimeCompatible(setup, version, targetLine) {
-    return !setup.runtime || (satisfies(version, setup.runtime, { includePrerelease: true }) && (!targetLine || subset(targetLine, setup.runtime, { includePrerelease: true })));
+    return (!setup.runtime ||
+        (satisfies(version, setup.runtime, { includePrerelease: true }) &&
+            (!targetLine || subset(targetLine, setup.runtime, { includePrerelease: true }))));
 }

package/dist/manifest.js

@@ -1,5 +1,6 @@
 import { validateInstallationOrigin } from './installation.js';
-import { valid, validRange } from 'semver';
+import valid from 'semver/functions/valid.js';
+import validRange from 'semver/ranges/valid.js';
 export class PresetError extends Error {
     code;
     constructor(code, message) {
@@ -14,9 +15,10 @@ function invalid(path, reason) {
     throw new PresetError('PRESET_INVALID', `${path}: ${reason}`);
 }
 export function isJsonObject(value) {
-    return value !== null && typeof value === 'object' &&
+    return (value !== null &&
+        typeof value === 'object' &&
         !Array.isArray(value) &&
-        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
 }
 function object(value, path) {
     if (!isJsonObject(value))
@@ -88,7 +90,8 @@ function component(value, path, kind) {
         invalid(`${path}.enabled`, 'expected a boolean');
     if ('targets' in value) {
         stringArray(value.targets, `${path}.targets`);
-        if (value.targets.length === 0 || value.targets.some(item => item !== 'browser' && item !== 'node')) {
+        if (value.targets.length === 0 ||
+            value.targets.some(item => item !== 'browser' && item !== 'node')) {
             invalid(`${path}.targets`, 'expected browser and/or node');
         }
     }
@@ -100,7 +103,19 @@ function component(value, path, kind) {
     return json(value, path);
 }
 export function validatePreset(value) {
-    fields(value, 'preset', ['schemaVersion', 'id', 'version', 'extends', 'requires', 'packages', 'skills', 'providers', 'appProfiles', 'defaults', 'permissions']);
+    fields(value, 'preset', [
+        'schemaVersion',
+        'id',
+        'version',
+        'extends',
+        'requires',
+        'packages',
+        'skills',
+        'providers',
+        'appProfiles',
+        'defaults',
+        'permissions',
+    ]);
     if (value.schemaVersion !== 1)
         invalid('schemaVersion', 'only version 1 is supported');
     id(value.id, 'id');
@@ -113,13 +128,20 @@ export function validatePreset(value) {
         text(value.extends.source, 'extends.source');
         if ('version' in value.extends)
             range(value.extends.version, 'extends.version');
-        result.extends = { source: value.extends.source, ...(value.extends.version === undefined ? {} : { version: value.extends.version }) };
+        result.extends = {
+            source: value.extends.source,
+            ...(value.extends.version === undefined ? {} : { version: value.extends.version }),
+        };
     }
     if ('requires' in value) {
         fields(value.requires, 'requires', ['mearlApi']);
         if ('mearlApi' in value.requires)
             range(value.requires.mearlApi, 'requires.mearlApi');
-        result.requires = { ...(value.requires.mearlApi === undefined ? {} : { mearlApi: value.requires.mearlApi }) };
+        result.requires = {
+            ...(value.requires.mearlApi === undefined
+                ? {}
+                : { mearlApi: value.requires.mearlApi }),
+        };
     }
     for (const kind of ['packages', 'skills', 'providers']) {
         if (!(kind in value))
@@ -148,14 +170,18 @@ export function validatePreset(value) {
         const origins = value.permissions.origins ?? [];
         if (origins.length > 64)
             invalid('permissions.origins', 'exceeds 64 scopes');
-        result.permissions = { origins: [...new Set(origins.map((origin, index) => {
+        result.permissions = {
+            origins: [
+                ...new Set(origins.map((origin, index) => {
                     try {
                         return validateInstallationOrigin(origin);
                     }
                     catch {
                         return invalid(`permissions.origins[${index}]`, 'expected an explicit HTTP host scope');
                     }
-                }))] };
+                })),
+            ],
+        };
     }
     if (JSON.stringify(result).length > 262_144)
         invalid('preset', 'manifest exceeds 256 Ki UTF-16 code units');

package/dist/prepare.js

@@ -1,5 +1,5 @@
-import { BundleError, MAX_BROWSER_STORAGE_BYTES, MAX_BUNDLE_MANIFEST_BYTES, bundleDigest, bundleSourceUrl, prepareBundle, validateBundleManifest } from './bundle.js';
-import { satisfies } from 'semver';
+import { BundleError, MAX_BROWSER_STORAGE_BYTES, MAX_BUNDLE_MANIFEST_BYTES, bundleDigest, bundleSourceUrl, loadBundleResources, validateBundleManifest, } from './bundle.js';
+import satisfies from 'semver/functions/satisfies.js';
 import { clonePresetDefaults, validatePreset } from './manifest.js';
 import { resolvePreset } from './resolve.js';
 export async function presetSnapshotRevision(value) {
@@ -7,7 +7,8 @@ export async function presetSnapshotRevision(value) {
 }
 /** Select candidates without assuming that inferred locations have been discovered. */
 function selectPresetPackages(preset, runtimes) {
-    const entries = Object.entries(preset.packages).filter(([, entry]) => entry.enabled !== false && (entry.targets ?? ['browser', 'node']).some(runtime => runtimes.includes(runtime)));
+    const entries = Object.entries(preset.packages).filter(([, entry]) => entry.enabled !== false &&
+        (entry.targets ?? ['browser', 'node']).some(runtime => runtimes.includes(runtime)));
     if (entries.length > 64)
         throw new BundleError('BUNDLE_QUOTA', 'A preset can activate at most 64 packages');
     return entries;
@@ -35,7 +36,14 @@ export function presetPackages(preset, runtimes) {
 export function bundleTargets(bundle) {
     const contributions = bundle.manifest.contributions;
     const targets = [];
-    if (contributions && (Object.keys(contributions.browserRuntimes ?? {}).length || Object.keys(contributions.pageRuntimes ?? {}).length || contributions.appProfiles?.length || contributions.extension || contributions.requestUi || contributions.browserViews || contributions.browserControls))
+    if (contributions &&
+        (Object.keys(contributions.browserRuntimes ?? {}).length ||
+            Object.keys(contributions.pageRuntimes ?? {}).length ||
+            contributions.appProfiles?.length ||
+            contributions.extension ||
+            contributions.requestUi ||
+            contributions.browserViews ||
+            contributions.browserControls))
         targets.push('browser');
     if (Object.keys(contributions?.nodeRuntimes ?? {}).length)
         targets.push('node');
@@ -49,7 +57,12 @@ export function applyPackageTargets(preset, targets) {
     const packages = { ...preset.packages };
     for (const [id, entry] of enabled) {
         const selected = targets[id];
-        if (!Array.isArray(selected) || !selected.length || selected.length > 2 || new Set(selected).size !== selected.length || selected.some(target => target !== 'browser' && target !== 'node') || entry.targets && JSON.stringify(entry.targets) !== JSON.stringify(selected))
+        if (!Array.isArray(selected) ||
+            !selected.length ||
+            selected.length > 2 ||
+            new Set(selected).size !== selected.length ||
+            selected.some(target => target !== 'browser' && target !== 'node') ||
+            (entry.targets && JSON.stringify(entry.targets) !== JSON.stringify(selected)))
             throw new BundleError('BUNDLE_INTEGRITY', 'Invalid package target selection');
         packages[id] = { ...entry, targets: [...selected] };
     }
@@ -96,10 +109,14 @@ export async function preparePresetPackages(source, options, runtimes) {
         },
     });
     const targetsKnown = Object.values(preset.packages).every(entry => entry.enabled === false || Boolean(entry.targets?.length));
-    const entries = targetsKnown ? presetPackages(preset, runtimes) : selectPresetPackages(preset, runtimes);
+    const entries = targetsKnown
+        ? presetPackages(preset, runtimes)
+        : selectPresetPackages(preset, runtimes);
     const bundles = [];
     const pending = [];
-    const packageTargets = Object.fromEntries(Object.entries(preset.packages).filter(([, entry]) => entry.enabled !== false).map(([id, entry]) => [id, entry.targets ?? []]));
+    const packageTargets = Object.fromEntries(Object.entries(preset.packages)
+        .filter(([, entry]) => entry.enabled !== false)
+        .map(([id, entry]) => [id, entry.targets ?? []]));
     for (const [id, entry] of entries) {
         const manifestSource = bundleSourceUrl(entry.source);
         const bytes = Uint8Array.from(await load(manifestSource, { maxBytes: MAX_BUNDLE_MANIFEST_BYTES, signal: options.signal }));
@@ -121,25 +138,38 @@ export async function preparePresetPackages(source, options, runtimes) {
         if (targets.some(target => !available.includes(target)))
             throw new BundleError('BUNDLE_INCOMPATIBLE', 'Package does not support the selected target');
         packageTargets[id] = targets;
-        pending.push({ id, entry, source: manifestSource, bytes });
+        pending.push({ source: manifestSource, manifest, bytes });
     }
     preset = applyPackageTargets(preset, packageTargets);
     const selected = new Set(presetPackages(preset, runtimes).map(([id]) => id));
-    for (const candidate of pending) {
-        if (!selected.has(candidate.id))
+    for (const { source: manifestSource, manifest, bytes } of pending) {
+        if (!selected.has(manifest.id))
             continue;
-        bundles.push(await prepareBundle(candidate.source, { ...options, load: (url, request) => url === candidate.source ? Promise.resolve(candidate.bytes) : load(url, request), expectedId: candidate.id, version: candidate.entry.version }));
+        bundles.push(await loadBundleResources(manifestSource, manifest, {
+            // A resource at the manifest URL belongs to the same captured response.
+            load: (url, request) => url === manifestSource ? Promise.resolve(bytes) : load(url, request),
+            signal: options.signal,
+        }));
     }
-    verifyPackageTargets(preset, bundles);
     options.signal?.throwIfAborted();
-    return { source, manifests, preset, bundles: bundles.filter(bundle => selected.has(bundle.manifest.id)), packageTargets };
+    return { source, manifests, preset, bundles, packageTargets };
 }
 /** The exact graph is checked offline; installed resources are verified by the target store. */
 export async function verifyPresetGraph(value, mearlApiVersion, runtimes, full) {
     const json = clonePresetDefaults(value);
-    const allowed = ['source', 'manifests', 'bundleRevisions', 'packageTargets', 'revision', ...(full ? ['schemaVersion'] : [])];
-    if (Object.keys(json).some(key => !allowed.includes(key)) || (full && json.schemaVersion !== 1) ||
-        typeof json.source !== 'string' || typeof json.revision !== 'string' || !/^[a-f0-9]{64}$/.test(json.revision)) {
+    const allowed = [
+        'source',
+        'manifests',
+        'bundleRevisions',
+        'packageTargets',
+        'revision',
+        ...(full ? ['schemaVersion'] : []),
+    ];
+    if (Object.keys(json).some(key => !allowed.includes(key)) ||
+        (full && json.schemaVersion !== 1) ||
+        typeof json.source !== 'string' ||
+        typeof json.revision !== 'string' ||
+        !/^[a-f0-9]{64}$/.test(json.revision)) {
         throw new BundleError('BUNDLE_INTEGRITY', 'Invalid stored preset identity');
     }
     const source = bundleSourceUrl(json.source);
@@ -147,7 +177,8 @@ export async function verifyPresetGraph(value, mearlApiVersion, runtimes, full)
     if (Object.keys(manifests).length > 32)
         throw new BundleError('BUNDLE_QUOTA', 'Stored preset inheritance exceeds 32 manifests');
     const bundleRevisions = clonePresetDefaults(json.bundleRevisions);
-    if (Object.keys(bundleRevisions).length > 64 || Object.values(bundleRevisions).some(revision => typeof revision !== 'string' || !/^[a-f0-9]{64}$/.test(revision))) {
+    if (Object.keys(bundleRevisions).length > 64 ||
+        Object.values(bundleRevisions).some(revision => typeof revision !== 'string' || !/^[a-f0-9]{64}$/.test(revision))) {
         throw new BundleError('BUNDLE_INTEGRITY', 'Invalid stored package revisions');
     }
     const validated = {};
@@ -157,8 +188,14 @@ export async function verifyPresetGraph(value, mearlApiVersion, runtimes, full)
         validated[url] = validatePreset(manifest);
     }
     const packageTargets = clonePresetDefaults(json.packageTargets);
-    const data = { ...(full ? { schemaVersion: 1 } : {}), source, manifests: validated, bundleRevisions, packageTargets };
-    if (await presetSnapshotRevision(data) !== json.revision)
+    const data = {
+        ...(full ? { schemaVersion: 1 } : {}),
+        source,
+        manifests: validated,
+        bundleRevisions,
+        packageTargets,
+    };
+    if ((await presetSnapshotRevision(data)) !== json.revision)
         throw new BundleError('BUNDLE_INTEGRITY', 'Stored preset revision does not match');
     let preset = await resolvePreset(source, {
         mearlApiVersion,
@@ -170,7 +207,9 @@ export async function verifyPresetGraph(value, mearlApiVersion, runtimes, full)
     });
     preset = applyPackageTargets(preset, packageTargets);
     const entries = presetPackages(preset, runtimes);
-    if (preset.chain.length !== Object.keys(validated).length || entries.length !== Object.keys(bundleRevisions).length || entries.some(([id]) => !Object.hasOwn(bundleRevisions, id))) {
+    if (preset.chain.length !== Object.keys(validated).length ||
+        entries.length !== Object.keys(bundleRevisions).length ||
+        entries.some(([id]) => !Object.hasOwn(bundleRevisions, id))) {
         throw new BundleError('BUNDLE_INTEGRITY', 'Stored preset package graph does not match');
     }
     return { snapshot: { ...data, revision: json.revision }, preset };

package/dist/preset.js

@@ -1,6 +1,6 @@
 import { browserPresetSnapshot } from './browserPreset.js';
-import { preparePresetPackages, presetSnapshotRevision, verifyPresetGraph, verifyPackageTargets } from './prepare.js';
-import { satisfies } from 'semver';
+import { preparePresetPackages, presetSnapshotRevision, verifyPresetGraph, verifyPackageTargets, } from './prepare.js';
+import satisfies from 'semver/functions/satisfies.js';
 import { BundleError, MAX_BROWSER_STORAGE_BYTES, verifyBundle } from './bundle.js';
 export async function preparePreset(source, options) {
     const prepared = await preparePresetPackages(source, options, ['browser', 'node']);
@@ -27,7 +27,9 @@ export async function verifyPreparedPreset(value, mearlApiVersion) {
         throw new BundleError('BUNDLE_QUOTA', 'Preset package count exceeds 64');
     let total = 0;
     for (const bundle of value.bundles) {
-        if (!bundle?.resources || typeof bundle.resources !== 'object' || Array.isArray(bundle.resources))
+        if (!bundle?.resources ||
+            typeof bundle.resources !== 'object' ||
+            Array.isArray(bundle.resources))
             throw new BundleError('BUNDLE_INVALID', 'Expected package resource buffers');
         const resources = Object.values(bundle.resources);
         if (resources.length > 64)
@@ -46,10 +48,19 @@ export async function verifyPreparedPreset(value, mearlApiVersion) {
     ]);
     const { snapshot, preset } = graph;
     verifyPackageTargets(preset, bundles);
-    if (bundles.length !== Object.keys(snapshot.bundleRevisions).length || new Set(bundles.map(bundle => bundle.manifest.id)).size !== bundles.length || bundles.some(bundle => {
-        const entry = preset.packages[bundle.manifest.id];
-        return snapshot.bundleRevisions[bundle.manifest.id] !== bundle.revision || entry?.source !== bundle.source || (entry.version && !satisfies(bundle.manifest.version, entry.version));
-    }))
+    if (bundles.length !== Object.keys(snapshot.bundleRevisions).length ||
+        new Set(bundles.map(bundle => bundle.manifest.id)).size !== bundles.length ||
+        bundles.some(bundle => {
+            const entry = preset.packages[bundle.manifest.id];
+            return (snapshot.bundleRevisions[bundle.manifest.id] !== bundle.revision ||
+                entry?.source !== bundle.source ||
+                (entry.version && !satisfies(bundle.manifest.version, entry.version)));
+        }))
         throw new BundleError('BUNDLE_INTEGRITY', 'Preset installation requires every exact package');
-    return { snapshot, preset, bundles, browser: await browserPresetSnapshot(snapshot.source, snapshot.manifests, preset, bundles) };
+    return {
+        snapshot,
+        preset,
+        bundles,
+        browser: await browserPresetSnapshot(snapshot.source, snapshot.manifests, preset, bundles),
+    };
 }

package/dist/profileSource.d.ts

@@ -0,0 +1,9 @@
+export declare function parseProfileSource(input: string): {
+    origin: string;
+    url: string;
+    github?: {
+        repository: string;
+        ref: string;
+    };
+};
+export declare function resolveProfileSource(input: string, fetcher?: typeof fetch): Promise<string>;

package/dist/profileSource.js

@@ -0,0 +1,44 @@
+import { BundleError } from './bundle.js';
+import { createBundleFetchLoader } from './bundleFetch.js';
+const githubReference = /^([A-Za-z0-9-]+)\/([A-Za-z0-9_.-]+)(?:@([A-Za-z0-9._/-]+))?$/;
+export function parseProfileSource(input) {
+    if (typeof input !== 'string' || input.length > 2048)
+        throw new BundleError('BUNDLE_INVALID', 'Invalid App profile source');
+    const match = githubReference.exec(input.trim());
+    if (match && match[2] !== '.' && match[2] !== '..') {
+        return {
+            origin: 'https://raw.githubusercontent.com',
+            url: input.trim(),
+            github: { repository: `${match[1]}/${match[2]}`, ref: match[3] ?? 'HEAD' },
+        };
+    }
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new BundleError('BUNDLE_INVALID', 'Use a GitHub owner/repo or an HTTPS bundle manifest URL');
+    }
+    if (url.protocol !== 'https:' || url.username || url.password || url.hash) {
+        throw new BundleError('BUNDLE_INVALID', 'App profile bundle URLs require HTTPS without credentials or a fragment');
+    }
+    return { origin: url.origin, url: url.href };
+}
+export async function resolveProfileSource(input, fetcher = fetch) {
+    const { url, github } = parseProfileSource(input);
+    if (!github)
+        return url;
+    const { repository, ref } = github;
+    let sha = ref;
+    if (!/^[a-f0-9]{40}$/.test(sha)) {
+        const load = createBundleFetchLoader({ fetch: fetcher });
+        const bytes = await load(`https://api.github.com/repos/${repository}/commits/${encodeURIComponent(ref)}`, {
+            maxBytes: 2 * 1024 * 1024,
+            signal: AbortSignal.timeout(10000),
+        });
+        sha = JSON.parse(new TextDecoder().decode(bytes)).sha;
+        if (typeof sha !== 'string' || !/^[a-f0-9]{40}$/.test(sha))
+            throw new BundleError('BUNDLE_INVALID', 'GitHub did not return a commit ID');
+    }
+    return `https://raw.githubusercontent.com/${repository}/${sha}/bundle.json`;
+}

package/dist/resolve.js

@@ -1,15 +1,17 @@
 import { parseToolboxCatalogs } from './toolboxCatalogs.js';
 import { parseSetupManagement } from './management.js';
-import { satisfies, valid } from 'semver';
+import satisfies from 'semver/functions/satisfies.js';
+import valid from 'semver/functions/valid.js';
 import { clonePresetDefaults, isJsonObject, PresetError, validatePreset } from './manifest.js';
 const kinds = ['packages', 'skills', 'providers'];
 /** Objects merge recursively; arrays, scalars and explicit null replace the previous value. */
 export function mergePresetDefaults(base, overrides) {
     const result = clonePresetDefaults(base);
     for (const [key, value] of Object.entries(clonePresetDefaults(overrides))) {
-        result[key] = isJsonObject(value) && isJsonObject(result[key])
-            ? mergePresetDefaults(result[key], value)
-            : value;
+        result[key] =
+            isJsonObject(value) && isJsonObject(result[key])
+                ? mergePresetDefaults(result[key], value)
+                : value;
     }
     return result;
 }
@@ -93,7 +95,8 @@ export async function resolvePreset(source, options) {
         active.add(url);
         const manifest = validatePreset(await options.load(url));
         options.signal?.throwIfAborted();
-        if (manifest.requires?.mearlApi && !satisfies(options.mearlApiVersion, manifest.requires.mearlApi)) {
+        if (manifest.requires?.mearlApi &&
+            !satisfies(options.mearlApiVersion, manifest.requires.mearlApi)) {
             throw new PresetError('PRESET_INCOMPATIBLE', `${manifest.id} requires Mearl API ${manifest.requires.mearlApi}`);
         }
         let parent;
@@ -106,21 +109,35 @@ export async function resolvePreset(source, options) {
         const result = {
             id: manifest.id,
             version: manifest.version,
-            chain: [...(parent?.chain ?? []), { source: url, id: manifest.id, version: manifest.version }],
+            chain: [
+                ...(parent?.chain ?? []),
+                { source: url, id: manifest.id, version: manifest.version },
+            ],
             packages: { ...parent?.packages },
             skills: { ...parent?.skills },
             providers: { ...parent?.providers },
             appProfiles: { ...parent?.appProfiles, ...manifest.appProfiles },
             defaults: mergePresetDefaults(parent?.defaults ?? {}, manifest.defaults ?? {}),
-            permissions: { origins: [...new Set([...(parent?.permissions.origins ?? []), ...(manifest.permissions?.origins ?? [])])] },
+            permissions: {
+                origins: [
+                    ...new Set([
+                        ...(parent?.permissions.origins ?? []),
+                        ...(manifest.permissions?.origins ?? []),
+                    ]),
+                ],
+            },
         };
         for (const kind of kinds) {
             for (const [id, patch] of Object.entries(manifest[kind] ?? {})) {
                 result[kind][id] = {
                     ...result[kind][id],
                     ...patch,
-                    ...(patch.source === undefined ? {} : { source: componentSource(kind, patch.source, url) }),
-                    ...(patch.migrateFrom === undefined ? {} : { migrateFrom: patch.migrateFrom.map(source => componentSource(kind, source, url)) }),
+                    ...(patch.source === undefined
+                        ? {}
+                        : { source: componentSource(kind, patch.source, url) }),
+                    ...(patch.migrateFrom === undefined
+                        ? {}
+                        : { migrateFrom: patch.migrateFrom.map(source => componentSource(kind, source, url)) }),
                     declaredBy: url,
                 };
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/preset",
-  "version": "3.0.0-beta.9",
+  "version": "3.0.1",
   "description": "Browser-compatible preset validation, inheritance and capability resolution for Mearl",
   "type": "module",
   "license": "Apache-2.0",
@@ -19,6 +19,10 @@
       "types": "./dist/installation.d.ts",
       "import": "./dist/installation.js"
     },
+    "./pageRuntime": {
+      "types": "./dist/pageRuntime.d.ts",
+      "import": "./dist/pageRuntime.js"
+    },
     "./installation-site.json": "./installation-site.json",
     "./networkRoutes": {
       "types": "./dist/networkRoutes.d.ts",
@@ -26,6 +30,7 @@
     }
   },
   "files": [
+    "README.en.md",
     "dist",
     "!dist/**/*.map",
     "installation-site.json"