@mearl/preset 3.0.0-beta.5 → 3.0.0-beta.8

package/dist/bundles.d.ts

@@ -1,5 +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 type { BundleManifest, PreparedBundle, BundleLoader, BundleLoadOptions, PrepareBundleOptions, CapabilityRuntimeDeclaration } from './bundle.js';
+export { selectExtensionContributions, validateExtensionContributions } from './extensionContributions.js';
+export type { ExtensionContributions } from './extensionContributions.js';
 export { createBundleFetchLoader } from './bundleFetch.js';
 export { BrowserBundleStore } from './bundleStore.js';
 export type { BrowserPresetInstallation } from './bundleStore.js';
@@ -12,7 +14,7 @@ export { installPageRuntimeHost, buildPageRuntimeRegistrationSource, buildPageRu
 export type { PageRuntimeBinding, PageRuntimeConfig } from './pageRuntime.js';
 export { receiveBrowserPreset, readPresetTransferResource, PRESET_TRANSFER_CHUNK_BYTES, MAX_PRESET_TRANSFER_HEADER_BYTES } from './browserTransfer.js';
 export type { BrowserPresetTransferHeader, PresetTransferRequest, PresetTransferTransport } from './browserTransfer.js';
-export { prepareBrowserBundleSnapshot } from './nodeSnapshot.js';
+export { prepareBrowserBundleSnapshot } from './capabilitySnapshot.js';
 export { buildBrowserCapabilityPage, buildBrowserPureCapabilityPage } from './browserSandbox.js';
 export type { BrowserCapabilityHost, BrowserCapabilityInvocation, BrowserCapabilityRequest, BrowserCapabilityResponse } from './browserSandbox.js';
 export { validateBrowserRequestUi, selectBrowserRequestUi, browserUiText, browserRequestUiLink, browserRequestLoginError, validateBrowserRequestDetail } from './requestUi.js';
@@ -20,3 +22,7 @@ export type { BrowserUiText, BrowserRequestUi, BrowserRequestDetail, SelectedBro
 export { validateBrowserView, selectBrowserView, buildBrowserViewPage } from './browserViews.js';
 export type { BrowserViewSlot, BrowserViewDefinition, BrowserViewAction, BrowserViewTransport, SelectedBrowserView, BrowserViewBootstrap } from './browserViews.js';
 export { browserTransportUrl, browserTransportPolicies } from './browserTransport.js';
+export { validateBrowserControl, selectBrowserControl } from './browserControls.js';
+export type { BrowserSegmentedControl, SelectedBrowserControl } from './browserControls.js';
+export { parseNetworkRoutePlan, encodeNetworkRoutePlan, decodeNetworkRoutePlan } from './networkRoutes.js';
+export type { NetworkHostRoute, NetworkRoutePlan } from './networkRoutes.js';

package/dist/bundles.js

@@ -1,12 +1,15 @@
 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 { BrowserBundleStore } from './bundleStore.js';
 export { prepareBrowserPreset, presetRequiresBrowser, verifyBrowserPreset, verifyPreparedBrowserPreset } from './browserPreset.js';
 export { preparePreset, verifyPreset, verifyPreparedPreset } from './preset.js';
 export { installPageRuntimeHost, buildPageRuntimeRegistrationSource, buildPageRuntimeCallSource } from './pageRuntime.js';
 export { receiveBrowserPreset, readPresetTransferResource, PRESET_TRANSFER_CHUNK_BYTES, MAX_PRESET_TRANSFER_HEADER_BYTES } from './browserTransfer.js';
-export { prepareBrowserBundleSnapshot } from './nodeSnapshot.js';
+export { prepareBrowserBundleSnapshot } from './capabilitySnapshot.js';
 export { buildBrowserCapabilityPage, buildBrowserPureCapabilityPage } from './browserSandbox.js';
 export { validateBrowserRequestUi, selectBrowserRequestUi, browserUiText, browserRequestUiLink, browserRequestLoginError, validateBrowserRequestDetail } from './requestUi.js';
 export { validateBrowserView, selectBrowserView, buildBrowserViewPage } from './browserViews.js';
 export { browserTransportUrl, browserTransportPolicies } from './browserTransport.js';
+export { validateBrowserControl, selectBrowserControl } from './browserControls.js';
+export { parseNetworkRoutePlan, encodeNetworkRoutePlan, decodeNetworkRoutePlan } from './networkRoutes.js';

package/dist/{nodeSnapshot.d.ts → capabilitySnapshot.d.ts}

@@ -1,5 +1,5 @@
 import type { JsonObject } from './types.js';
-export interface NodeCapabilitySelection {
+export interface CapabilitySelection {
     schemaVersion: 1;
     modules: Record<string, {
         sha256: string;
@@ -11,28 +11,28 @@ export interface NodeCapabilitySelection {
         handler: string;
     }>;
 }
-export interface NodeCapabilitySnapshot extends NodeCapabilitySelection {
+export interface CapabilitySnapshot extends CapabilitySelection {
     revision: string;
 }
-export interface NodeCapabilityActivation extends NodeCapabilitySnapshot {
+export interface CapabilityActivation extends CapabilitySnapshot {
     installationRevision?: string;
 }
-export declare const MAX_NODE_SELECTION_BYTES = 262144;
+export declare const MAX_CAPABILITY_SELECTION_BYTES = 262144;
 /** Explicit module configuration survives periods where a preset disables its module. */
-export declare function validateNodeModuleConfig(value: Record<string, JsonObject>): Record<string, JsonObject>;
+export declare function validateCapabilityConfig(value: Record<string, JsonObject>): Record<string, JsonObject>;
 /** Preset defaults are inherited; explicit host configuration stays a separate override. */
-export declare function resolvePresetModuleConfig(defaults: JsonObject, overrides?: Record<string, JsonObject>): Record<string, JsonObject>;
+export declare function resolveCapabilityConfig(defaults: JsonObject, overrides?: Record<string, JsonObject>): Record<string, JsonObject>;
 /** Exact content and bindings are selected together; filesystem and code loading belong to hosts. */
-export declare function prepareNodeCapabilitySnapshot(input: NodeCapabilitySelection): Promise<NodeCapabilitySnapshot>;
-export declare function verifyNodeCapabilitySnapshot(input: NodeCapabilitySnapshot): Promise<NodeCapabilitySnapshot>;
+export declare function prepareCapabilitySnapshot(input: CapabilitySelection): Promise<CapabilitySnapshot>;
+export declare function verifyCapabilitySnapshot(input: CapabilitySnapshot): Promise<CapabilitySnapshot>;
 /** The installer receipt and Node selection share one atomic filesystem pointer. */
-export declare function verifyNodeCapabilityActivation(input: NodeCapabilityActivation): Promise<NodeCapabilityActivation>;
+export declare function verifyCapabilityActivation(input: CapabilityActivation): Promise<CapabilityActivation>;
 export declare function prepareNodeBundleSnapshot(bundles: import('./bundle.js').PreparedBundle[], host: string, mearlApiVersion: string, config?: Record<string, JsonObject>): Promise<{
-    snapshot: NodeCapabilitySnapshot;
+    snapshot: CapabilitySnapshot;
     resources: Record<string, Uint8Array>;
 }>;
 /** Browser factories use the same exact module/configuration selection without a Node loader. */
 export declare function prepareBrowserBundleSnapshot(bundles: import('./bundle.js').PreparedBundle[], host: string, mearlApiVersion: string, config?: Record<string, JsonObject>): Promise<{
-    snapshot: NodeCapabilitySnapshot;
+    snapshot: CapabilitySnapshot;
     resources: Record<string, Uint8Array>;
 }>;

package/dist/{nodeSnapshot.js → capabilitySnapshot.js}

@@ -1,95 +1,95 @@
 import { BundleError, MAX_BROWSER_STORAGE_BYTES, MAX_BUNDLE_BYTES, bundleDigest, validateBundleManifest } from './bundle.js';
 import { clonePresetDefaults, isJsonObject } from './manifest.js';
 import { mergePresetDefaults } from './resolve.js';
-export const MAX_NODE_SELECTION_BYTES = 262_144;
+export const MAX_CAPABILITY_SELECTION_BYTES = 262_144;
 const identifier = /^[a-z][a-z0-9-]{0,79}$/;
 const hookName = /^[a-z][a-zA-Z0-9_.-]{0,127}$/;
 const digest = /^[a-f0-9]{64}$/;
 function invalid(message) { throw new BundleError('BUNDLE_INVALID', message); }
 function fields(value, allowed) {
     if (!isJsonObject(value) || Object.keys(value).some(key => !allowed.includes(key)))
-        invalid('Invalid Node capability selection structure');
+        invalid('Invalid Capability selection structure');
 }
 /** Explicit module configuration survives periods where a preset disables its module. */
-export function validateNodeModuleConfig(value) {
+export function validateCapabilityConfig(value) {
     const configs = clonePresetDefaults(value);
-    if (Object.keys(configs).length > 64 || new TextEncoder().encode(JSON.stringify(configs)).byteLength > MAX_NODE_SELECTION_BYTES)
-        throw new BundleError('BUNDLE_QUOTA', 'Node module configuration exceeds its limit');
+    if (Object.keys(configs).length > 64 || new TextEncoder().encode(JSON.stringify(configs)).byteLength > MAX_CAPABILITY_SELECTION_BYTES)
+        throw new BundleError('BUNDLE_QUOTA', 'Capability module configuration exceeds its limit');
     for (const [id, config] of Object.entries(configs))
         if (!identifier.test(id) || !isJsonObject(config))
-            invalid('Node module configuration must map IDs to JSON objects');
+            invalid('Capability module configuration must map IDs to JSON objects');
     return configs;
 }
 /** Preset defaults are inherited; explicit host configuration stays a separate override. */
-export function resolvePresetModuleConfig(defaults, overrides = {}) {
+export function resolveCapabilityConfig(defaults, overrides = {}) {
     const value = defaults.capabilities === undefined ? {} : defaults.capabilities;
     if (!isJsonObject(value))
         invalid('Capability defaults must map module IDs to configuration objects');
-    return validateNodeModuleConfig(mergePresetDefaults(validateNodeModuleConfig(value), validateNodeModuleConfig(overrides)));
+    return validateCapabilityConfig(mergePresetDefaults(validateCapabilityConfig(value), validateCapabilityConfig(overrides)));
 }
 /** Exact content and bindings are selected together; filesystem and code loading belong to hosts. */
-export async function prepareNodeCapabilitySnapshot(input) {
+export async function prepareCapabilitySnapshot(input) {
     const value = clonePresetDefaults(input);
     fields(value, ['schemaVersion', 'modules', 'bindings']);
     if (value.schemaVersion !== 1 || !isJsonObject(value.modules) || !isJsonObject(value.bindings))
-        invalid('Invalid Node capability selection');
+        invalid('Invalid Capability selection');
     if (Object.keys(value.modules).length > 64 || Object.keys(value.bindings).length > 256)
-        throw new BundleError('BUNDLE_QUOTA', 'Node capability selection exceeds the entry limit');
+        throw new BundleError('BUNDLE_QUOTA', 'Capability selection exceeds the entry limit');
     const modules = {};
     let total = 0;
     for (const id of Object.keys(value.modules).sort()) {
         if (!identifier.test(id))
-            invalid('Invalid Node module ID');
+            invalid('Invalid Capability module ID');
         const entry = value.modules[id];
         fields(entry, ['sha256', 'byteLength', 'config']);
         if (typeof entry.sha256 !== 'string' || !digest.test(entry.sha256) || typeof entry.byteLength !== 'number' || !Number.isSafeInteger(entry.byteLength) || entry.byteLength <= 0 || entry.byteLength > MAX_BUNDLE_BYTES)
-            invalid('Invalid Node module resource');
+            invalid('Invalid Capability module resource');
         if (entry.config !== undefined && !isJsonObject(entry.config))
-            invalid('Node module configuration must be a JSON object');
+            invalid('Capability module configuration must be a JSON object');
         total += entry.byteLength;
         if (total > MAX_BROWSER_STORAGE_BYTES)
-            throw new BundleError('BUNDLE_QUOTA', 'Node capability resources exceed 64 MiB');
+            throw new BundleError('BUNDLE_QUOTA', 'Capability resources exceed 64 MiB');
         modules[id] = { sha256: entry.sha256, byteLength: entry.byteLength, ...(entry.config === undefined ? {} : { config: clonePresetDefaults(entry.config) }) };
     }
     const bindings = {};
     for (const name of Object.keys(value.bindings).sort()) {
         if (!hookName.test(name))
-            invalid('Invalid Node hook name');
+            invalid('Invalid Capability hook name');
         const binding = value.bindings[name];
         fields(binding, ['module', 'handler']);
         if (typeof binding.module !== 'string' || !Object.hasOwn(modules, binding.module) || typeof binding.handler !== 'string' || !hookName.test(binding.handler))
-            invalid('Node hook must bind a declared module handler');
+            invalid('Capability hook must bind a declared module handler');
         bindings[name] = { module: binding.module, handler: binding.handler };
     }
     const selection = { schemaVersion: 1, modules, bindings };
-    if (new TextEncoder().encode(JSON.stringify(selection)).byteLength + 80 > MAX_NODE_SELECTION_BYTES)
-        throw new BundleError('BUNDLE_QUOTA', 'Node capability selection metadata exceeds 256 KiB');
+    if (new TextEncoder().encode(JSON.stringify(selection)).byteLength + 80 > MAX_CAPABILITY_SELECTION_BYTES)
+        throw new BundleError('BUNDLE_QUOTA', 'Capability selection metadata exceeds 256 KiB');
     return { ...selection, revision: await bundleDigest(new TextEncoder().encode(JSON.stringify(selection))) };
 }
-export async function verifyNodeCapabilitySnapshot(input) {
+export async function verifyCapabilitySnapshot(input) {
     const value = clonePresetDefaults(input);
     fields(value, ['schemaVersion', 'modules', 'bindings', 'revision']);
     if (typeof value.revision !== 'string' || !digest.test(value.revision))
-        invalid('Invalid Node capability revision');
+        invalid('Invalid Capability revision');
     const { revision, ...selection } = value;
-    const prepared = await prepareNodeCapabilitySnapshot(selection);
+    const prepared = await prepareCapabilitySnapshot(selection);
     if (prepared.revision !== revision)
-        throw new BundleError('BUNDLE_INTEGRITY', 'Node capability selection revision does not match');
+        throw new BundleError('BUNDLE_INTEGRITY', 'Capability selection revision does not match');
     return prepared;
 }
 /** The installer receipt and Node selection share one atomic filesystem pointer. */
-export async function verifyNodeCapabilityActivation(input) {
+export async function verifyCapabilityActivation(input) {
     const value = clonePresetDefaults(input);
     const { installationRevision, ...selection } = value;
     if (installationRevision !== undefined && (typeof installationRevision !== 'string' || !digest.test(installationRevision)))
         invalid('Invalid capability installation revision');
-    const snapshot = await verifyNodeCapabilitySnapshot(selection);
+    const snapshot = await verifyCapabilitySnapshot(selection);
     return { ...snapshot, ...(installationRevision === undefined ? {} : { installationRevision: installationRevision }) };
 }
 async function prepareRuntimeBundleSnapshot(bundles, kind, host, mearlApiVersion, config) {
     if (!identifier.test(host))
-        invalid('Invalid Node runtime host');
-    const configs = validateNodeModuleConfig(config);
+        invalid('Invalid capability runtime host');
+    const configs = validateCapabilityConfig(config);
     const modules = {};
     const bindings = {};
     const resources = {};
@@ -101,20 +101,21 @@ async function prepareRuntimeBundleSnapshot(bundles, kind, host, mearlApiVersion
         if (!runtime)
             continue;
         if (Object.hasOwn(modules, manifest.id))
-            invalid('Duplicate Node module ID');
+            invalid('Duplicate Capability module ID');
         const metadata = manifest.resources[runtime.entry];
         if (!Object.hasOwn(bundle.resources, runtime.entry))
-            invalid('Node module resource is missing');
+            invalid('Capability module resource is missing');
         total += metadata.byteLength;
         if (pending.length >= 64 || total > MAX_BROWSER_STORAGE_BYTES)
-            throw new BundleError('BUNDLE_QUOTA', 'Node capability resources exceed the selection limit');
+            throw new BundleError('BUNDLE_QUOTA', 'Capability resources exceed the selection limit');
         pending.push({ id: manifest.id, bytes: bundle.resources[runtime.entry], sha256: metadata.sha256 });
         if (pending[pending.length - 1].bytes.byteLength !== metadata.byteLength)
-            invalid('Node module length does not match');
-        modules[manifest.id] = { ...metadata, ...(configs[manifest.id] ? { config: clonePresetDefaults(configs[manifest.id]) } : {}) };
+            invalid('Capability module length does not match');
+        const effectiveConfig = mergePresetDefaults(manifest.defaults ?? {}, configs[manifest.id] ?? {});
+        modules[manifest.id] = { ...metadata, ...(Object.keys(effectiveConfig).length ? { config: effectiveConfig } : {}) };
         for (const [name, handler] of Object.entries(runtime.bindings)) {
             if (Object.hasOwn(bindings, name))
-                invalid('Node hook has multiple providers');
+                invalid('Capability hook has multiple providers');
             bindings[name] = { module: manifest.id, handler };
         }
     }
@@ -122,10 +123,10 @@ async function prepareRuntimeBundleSnapshot(bundles, kind, host, mearlApiVersion
     const captured = pending.map(resource => ({ ...resource, bytes: Uint8Array.from(resource.bytes) }));
     for (const resource of captured) {
         if (await bundleDigest(resource.bytes) !== resource.sha256)
-            throw new BundleError('BUNDLE_INTEGRITY', `Node module digest does not match: ${resource.id}`);
+            throw new BundleError('BUNDLE_INTEGRITY', `Capability module digest does not match: ${resource.id}`);
         resources[resource.sha256] = resource.bytes;
     }
-    return { snapshot: await prepareNodeCapabilitySnapshot({ schemaVersion: 1, modules, bindings }), resources };
+    return { snapshot: await prepareCapabilitySnapshot({ schemaVersion: 1, modules, bindings }), resources };
 }
 export function prepareNodeBundleSnapshot(bundles, host, mearlApiVersion, config = {}) {
     return prepareRuntimeBundleSnapshot(bundles, 'nodeRuntimes', host, mearlApiVersion, config);

package/dist/extensionContributions.d.ts

@@ -0,0 +1,29 @@
+import { type PreparedBundle } from './bundle.js';
+import { type BrowserUiText } from './requestUi.js';
+export interface ExtensionContributions {
+    schemaVersion: 1;
+    operations?: Record<string, {
+        hook: string;
+        setting?: string;
+    }>;
+    logins?: Record<string, {
+        url: string;
+        title: BrowserUiText;
+    }>;
+}
+export declare function validateExtensionContributions(input: unknown): ExtensionContributions;
+/** Definitions belong to packages; preset defaults cannot redirect their handlers. */
+export declare function selectExtensionContributions(bundles: PreparedBundle[]): {
+    operations: Record<string, {
+        hook: string;
+        setting?: string;
+    }>;
+    logins: Record<string, {
+        url: string;
+        title: BrowserUiText;
+    }>;
+    owners: Record<string, {
+        bundleId: string;
+        revision: string;
+    }>;
+};

package/dist/extensionContributions.js

@@ -0,0 +1,57 @@
+import { BundleError, readBundleJson } from './bundle.js';
+import { clonePresetDefaults, isJsonObject } from './manifest.js';
+import { browserUiHttpUrl, validateBrowserUiText } from './requestUi.js';
+export function validateExtensionContributions(input) {
+    const value = clonePresetDefaults(input);
+    if (value.schemaVersion !== 1 || Object.keys(value).some(key => !['schemaVersion', 'operations', 'logins'].includes(key)))
+        throw new BundleError('BUNDLE_INVALID', 'Invalid extension contributions');
+    for (const kind of ['operations', 'logins']) {
+        const entries = value[kind];
+        if (entries === undefined)
+            continue;
+        if (!isJsonObject(entries) || Object.keys(entries).length > 64)
+            throw new BundleError('BUNDLE_QUOTA', 'Extension contributions exceed 64 entries');
+        for (const [name, entry] of Object.entries(entries)) {
+            if (!/^[a-z][a-zA-Z0-9_.-]{0,95}$/.test(name) || !isJsonObject(entry))
+                throw new BundleError('BUNDLE_INVALID', 'Invalid extension contribution name');
+            if (kind === 'operations') {
+                if (Object.keys(entry).some(key => !['hook', 'setting'].includes(key)) || typeof entry.hook !== 'string' || !/^[a-z][a-zA-Z0-9_.-]{0,127}$/.test(entry.hook) || entry.setting !== undefined && (typeof entry.setting !== 'string' || !/^[a-z][a-zA-Z0-9]{0,95}Enabled$/.test(entry.setting) || ['agentEnabled', 'sseMonitoringEnabled', 'agentFloatingButtonEnabled'].includes(entry.setting)))
+                    throw new BundleError('BUNDLE_INVALID', 'Invalid extension operation');
+            }
+            else {
+                if (Object.keys(entry).some(key => !['url', 'title'].includes(key)))
+                    throw new BundleError('BUNDLE_INVALID', 'Invalid extension login');
+                entry.url = browserUiHttpUrl(entry.url, { allowFragment: true });
+                validateBrowserUiText(entry.title);
+            }
+        }
+    }
+    return value;
+}
+/** Definitions belong to packages; preset defaults cannot redirect their handlers. */
+export function selectExtensionContributions(bundles) {
+    const operations = {};
+    const logins = {};
+    const owners = {};
+    for (const bundle of bundles) {
+        const path = bundle.manifest.contributions?.extension;
+        if (!path)
+            continue;
+        const definition = validateExtensionContributions(readBundleJson(bundle, path));
+        const bindings = bundle.manifest.contributions?.browserRuntimes?.extension?.bindings ?? {};
+        for (const [name, operation] of Object.entries(definition.operations ?? {})) {
+            if (Object.hasOwn(operations, name))
+                throw new BundleError('BUNDLE_CONFLICT', `Multiple providers for extension operation: ${name}`);
+            if (!Object.hasOwn(bindings, operation.hook))
+                throw new BundleError('BUNDLE_INVALID', 'Extension operation must use its own runtime');
+            operations[name] = operation;
+            owners[name] = { bundleId: bundle.manifest.id, revision: bundle.revision };
+        }
+        for (const [name, login] of Object.entries(definition.logins ?? {})) {
+            if (Object.hasOwn(logins, name))
+                throw new BundleError('BUNDLE_CONFLICT', `Multiple providers for extension login: ${name}`);
+            logins[name] = login;
+        }
+    }
+    return { operations, logins, owners };
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { PresetError, validatePreset, clonePresetDefaults } from './manifest.js';
 export { mergePresetDefaults, resolvePreset } from './resolve.js';
 export type * from './types.js';
-export { prepareNodeBundleSnapshot, prepareNodeCapabilitySnapshot, verifyNodeCapabilitySnapshot, verifyNodeCapabilityActivation, validateNodeModuleConfig, resolvePresetModuleConfig, MAX_NODE_SELECTION_BYTES } from './nodeSnapshot.js';
-export type { NodeCapabilitySelection, NodeCapabilitySnapshot, NodeCapabilityActivation } from './nodeSnapshot.js';
+export { prepareNodeBundleSnapshot, prepareCapabilitySnapshot, verifyCapabilitySnapshot, verifyCapabilityActivation, validateCapabilityConfig, resolveCapabilityConfig, MAX_CAPABILITY_SELECTION_BYTES } from './capabilitySnapshot.js';
+export type { CapabilitySelection, CapabilitySnapshot, CapabilityActivation } from './capabilitySnapshot.js';
+export { parseToolboxCatalogs } from './toolboxCatalogs.js';
+export type { ToolboxCatalogConfig, ToolboxCatalogConfigs } from './toolboxCatalogs.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { PresetError, validatePreset, clonePresetDefaults } from './manifest.js';
 export { mergePresetDefaults, resolvePreset } from './resolve.js';
-export { prepareNodeBundleSnapshot, prepareNodeCapabilitySnapshot, verifyNodeCapabilitySnapshot, verifyNodeCapabilityActivation, validateNodeModuleConfig, resolvePresetModuleConfig, MAX_NODE_SELECTION_BYTES } from './nodeSnapshot.js';
+export { prepareNodeBundleSnapshot, prepareCapabilitySnapshot, verifyCapabilitySnapshot, verifyCapabilityActivation, validateCapabilityConfig, resolveCapabilityConfig, MAX_CAPABILITY_SELECTION_BYTES } from './capabilitySnapshot.js';
+export { parseToolboxCatalogs } from './toolboxCatalogs.js';

package/dist/manifest.js

@@ -72,7 +72,7 @@ export function clonePresetDefaults(value) {
     return json(value, 'defaults');
 }
 function component(value, path, kind) {
-    fields(value, path, ['source', 'version', 'enabled', 'runtimes', 'dependsOn', 'migrateFrom']);
+    fields(value, path, ['source', 'version', 'enabled', 'targets', 'dependsOn', 'migrateFrom']);
     if ('source' in value)
         text(value.source, `${path}.source`);
     if ('version' in value)
@@ -86,10 +86,10 @@ function component(value, path, kind) {
     }
     if ('enabled' in value && typeof value.enabled !== 'boolean')
         invalid(`${path}.enabled`, 'expected a boolean');
-    if ('runtimes' in value) {
-        stringArray(value.runtimes, `${path}.runtimes`);
-        if (value.runtimes.length === 0 || value.runtimes.some(item => item !== 'browser' && item !== 'node')) {
-            invalid(`${path}.runtimes`, 'expected browser and/or node');
+    if ('targets' in value) {
+        stringArray(value.targets, `${path}.targets`);
+        if (value.targets.length === 0 || value.targets.some(item => item !== 'browser' && item !== 'node')) {
+            invalid(`${path}.targets`, 'expected browser and/or node');
         }
     }
     if ('dependsOn' in value) {

package/dist/networkRoutes.d.ts

@@ -0,0 +1,12 @@
+export interface NetworkHostRoute {
+    id?: string;
+    fromHost: string;
+    toHost: string;
+}
+export interface NetworkRoutePlan {
+    routes: NetworkHostRoute[];
+}
+/** Shared by Node, the extension host and the self-contained document-start runtime. */
+export declare function parseNetworkRoutePlan(input: unknown): NetworkRoutePlan;
+export declare function encodeNetworkRoutePlan(input: NetworkRoutePlan): string;
+export declare function decodeNetworkRoutePlan(value: string): NetworkRoutePlan;

package/dist/networkRoutes.js

@@ -0,0 +1,32 @@
+/** Shared by Node, the extension host and the self-contained document-start runtime. */
+export function parseNetworkRoutePlan(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).join(',') !== 'routes')
+        throw new Error('Invalid network route plan');
+    const routes = input.routes;
+    if (!Array.isArray(routes) || routes.length > 32)
+        throw new Error('Invalid network routes');
+    const sources = new Set();
+    const ids = new Set();
+    const hostname = (value) => typeof value === 'string' && value.length <= 253 && value.includes('.') && value.split('.').every(label => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label));
+    for (const route of routes) {
+        if (!route || typeof route !== 'object' || Array.isArray(route) || Object.keys(route).some(key => !['id', 'fromHost', 'toHost'].includes(key)) || route.id !== undefined && (typeof route.id !== 'string' || !/^[a-z][a-zA-Z0-9_.-]{0,79}$/.test(route.id)) || !hostname(route.fromHost) || !hostname(route.toHost) || route.fromHost === route.toHost || sources.has(route.fromHost) || route.id !== undefined && ids.has(route.id))
+            throw new Error('Invalid or ambiguous network route');
+        sources.add(route.fromHost);
+        if (route.id)
+            ids.add(route.id);
+    }
+    if (routes.reduce((size, route) => size + route.toHost.length, 0) > 1024)
+        throw new Error('Network route plan is too large');
+    const plan = { routes: routes.map(({ id, fromHost, toHost }) => ({ ...(id ? { id } : {}), fromHost, toHost })) };
+    if (JSON.stringify(plan).length > 12288)
+        throw new Error('Network route header is too large');
+    return plan;
+}
+export function encodeNetworkRoutePlan(input) {
+    return btoa(JSON.stringify(parseNetworkRoutePlan(input)));
+}
+export function decodeNetworkRoutePlan(value) {
+    if (value.length > 16384)
+        throw new Error('Network route header is too large');
+    return parseNetworkRoutePlan(JSON.parse(atob(value)));
+}

package/dist/prepare.d.ts

@@ -11,17 +11,23 @@ export interface PresetGraphSnapshot {
     source: string;
     manifests: Record<string, PresetManifest>;
     bundleRevisions: Record<string, string>;
+    packageTargets: Record<string, PresetRuntime[]>;
     revision: string;
 }
 export declare function presetSnapshotRevision(value: object): Promise<string>;
 /** Each execution location must be able to satisfy its own package dependencies. */
 export declare function presetPackages(preset: ResolvedPreset, runtimes: PresetRuntime[]): Array<[string, ResolvedComponent]>;
+export declare function bundleTargets(bundle: Pick<PreparedBundle, 'manifest'>): PresetRuntime[];
+/** Resolved activation choices are derived data; source manifests remain unchanged. */
+export declare function applyPackageTargets(preset: ResolvedPreset, targets: Record<string, PresetRuntime[]>): ResolvedPreset;
+export declare function verifyPackageTargets(preset: ResolvedPreset, bundles: PreparedBundle[]): void;
 /** Shared preparation performs no installation, code execution or permission changes. */
 export declare function preparePresetPackages(source: string, options: PreparePresetOptions, runtimes: PresetRuntime[]): Promise<{
     source: string;
     manifests: Record<string, PresetManifest>;
     preset: ResolvedPreset;
     bundles: PreparedBundle[];
+    packageTargets: Record<string, PresetRuntime[]>;
 }>;
 /** The exact graph is checked offline; installed resources are verified by the target store. */
 export declare function verifyPresetGraph(value: PresetGraphSnapshot & {

package/dist/prepare.js

@@ -1,16 +1,21 @@
-import { BundleError, MAX_BROWSER_STORAGE_BYTES, bundleDigest, bundleSourceUrl, prepareBundle } from './bundle.js';
+import { BundleError, MAX_BROWSER_STORAGE_BYTES, MAX_BUNDLE_MANIFEST_BYTES, bundleDigest, bundleSourceUrl, prepareBundle, validateBundleManifest } from './bundle.js';
+import { satisfies } from 'semver';
 import { clonePresetDefaults, validatePreset } from './manifest.js';
 import { resolvePreset } from './resolve.js';
 export async function presetSnapshotRevision(value) {
     return bundleDigest(new TextEncoder().encode(JSON.stringify(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)));
+    if (entries.length > 64)
+        throw new BundleError('BUNDLE_QUOTA', 'A preset can activate at most 64 packages');
+    return entries;
+}
 /** Each execution location must be able to satisfy its own package dependencies. */
 export function presetPackages(preset, runtimes) {
-    if (runtimes.includes('node') && runtimes.includes('browser') && Object.values(preset.packages).some(entry => entry.enabled !== false && !entry.runtimes?.length)) {
-        throw new BundleError('BUNDLE_INCOMPATIBLE', 'Every enabled package must declare its browser and/or Node runtime');
-    }
     for (const runtime of runtimes) {
-        const entries = Object.entries(preset.packages).filter(([, entry]) => entry.enabled !== false && entry.runtimes?.includes(runtime));
+        const entries = Object.entries(preset.packages).filter(([, entry]) => entry.enabled !== false && (entry.targets ?? ['browser', 'node']).includes(runtime));
         const ids = new Set(entries.map(([id]) => id));
         for (const [id, entry] of entries) {
             if (entry.dependsOn?.some(dependency => !ids.has(dependency))) {
@@ -25,10 +30,37 @@ export function presetPackages(preset, runtimes) {
             }
         }
     }
-    const entries = Object.entries(preset.packages).filter(([, entry]) => entry.enabled !== false && entry.runtimes?.some(runtime => runtimes.includes(runtime)));
-    if (entries.length > 64)
-        throw new BundleError('BUNDLE_QUOTA', 'A preset can activate at most 64 packages');
-    return entries;
+    return selectPresetPackages(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))
+        targets.push('browser');
+    if (Object.keys(contributions?.nodeRuntimes ?? {}).length)
+        targets.push('node');
+    return targets.length ? targets : ['browser', 'node'];
+}
+/** Resolved activation choices are derived data; source manifests remain unchanged. */
+export function applyPackageTargets(preset, targets) {
+    const enabled = Object.entries(preset.packages).filter(([, entry]) => entry.enabled !== false);
+    if (enabled.length !== Object.keys(targets).length)
+        throw new BundleError('BUNDLE_INTEGRITY', 'Package target selection does not match the preset');
+    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))
+            throw new BundleError('BUNDLE_INTEGRITY', 'Invalid package target selection');
+        packages[id] = { ...entry, targets: [...selected] };
+    }
+    return { ...preset, packages };
+}
+export function verifyPackageTargets(preset, bundles) {
+    for (const bundle of bundles) {
+        const available = bundleTargets(bundle);
+        if (preset.packages[bundle.manifest.id]?.targets?.some(target => !available.includes(target)))
+            throw new BundleError('BUNDLE_INCOMPATIBLE', 'Package does not support the selected target');
+    }
 }
 /** Shared preparation performs no installation, code execution or permission changes. */
 export async function preparePresetPackages(source, options, runtimes) {
@@ -47,7 +79,7 @@ export async function preparePresetPackages(source, options, runtimes) {
         return bytes;
     };
     const manifests = {};
-    const preset = await resolvePreset(source, {
+    let preset = await resolvePreset(source, {
         mearlApiVersion: options.mearlApiVersion,
         signal: options.signal,
         load: async (url) => {
@@ -63,18 +95,49 @@ export async function preparePresetPackages(source, options, runtimes) {
             return manifest;
         },
     });
-    const entries = presetPackages(preset, 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 bundles = [];
+    const pending = [];
+    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) {
-        bundles.push(await prepareBundle(entry.source, { ...options, load, expectedId: id, version: entry.version }));
+        const manifestSource = bundleSourceUrl(entry.source);
+        const bytes = Uint8Array.from(await load(manifestSource, { maxBytes: MAX_BUNDLE_MANIFEST_BYTES, signal: options.signal }));
+        let manifest;
+        try {
+            manifest = validateBundleManifest(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)), options.mearlApiVersion);
+        }
+        catch (error) {
+            if (error instanceof BundleError)
+                throw error;
+            throw new BundleError('BUNDLE_INVALID', error instanceof Error ? error.message : 'Invalid package manifest');
+        }
+        if (manifest.id !== id)
+            throw new BundleError('BUNDLE_INVALID', 'Package identity does not match the preset');
+        if (entry.version && !satisfies(manifest.version, entry.version))
+            throw new BundleError('BUNDLE_INCOMPATIBLE', 'Package version does not satisfy the preset');
+        const available = bundleTargets({ manifest });
+        const targets = entry.targets ?? available;
+        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 });
+    }
+    preset = applyPackageTargets(preset, packageTargets);
+    const selected = new Set(presetPackages(preset, runtimes).map(([id]) => id));
+    for (const candidate of pending) {
+        if (!selected.has(candidate.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 }));
     }
+    verifyPackageTargets(preset, bundles);
     options.signal?.throwIfAborted();
-    return { source, manifests, preset, bundles };
+    return { source, manifests, preset, bundles: bundles.filter(bundle => selected.has(bundle.manifest.id)), 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', 'revision', ...(full ? ['schemaVersion'] : [])];
+    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');
@@ -93,10 +156,11 @@ export async function verifyPresetGraph(value, mearlApiVersion, runtimes, full)
             throw new BundleError('BUNDLE_INTEGRITY', 'Invalid stored preset source');
         validated[url] = validatePreset(manifest);
     }
-    const data = { ...(full ? { schemaVersion: 1 } : {}), source, manifests: validated, bundleRevisions };
+    const packageTargets = clonePresetDefaults(json.packageTargets);
+    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');
-    const preset = await resolvePreset(source, {
+    let preset = await resolvePreset(source, {
         mearlApiVersion,
         load: async (url) => {
             if (!Object.hasOwn(validated, url))
@@ -104,6 +168,7 @@ export async function verifyPresetGraph(value, mearlApiVersion, runtimes, full)
             return validated[url];
         },
     });
+    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))) {
         throw new BundleError('BUNDLE_INTEGRITY', 'Stored preset package graph does not match');