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

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,9 @@
 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 { parseSetupManagement, setupManagementCommand, setupRuntimeCompatible } from './management.js';
+export type { SetupManagement } from './management.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,5 @@
 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 { parseSetupManagement, setupManagementCommand, setupRuntimeCompatible } from './management.js';
+export { prepareNodeBundleSnapshot, prepareCapabilitySnapshot, verifyCapabilitySnapshot, verifyCapabilityActivation, validateCapabilityConfig, resolveCapabilityConfig, MAX_CAPABILITY_SELECTION_BYTES } from './capabilitySnapshot.js';
+export { parseToolboxCatalogs } from './toolboxCatalogs.js';

package/dist/installation.d.ts

@@ -11,7 +11,6 @@ export interface InstallationConfig {
     schemaVersion: 1;
     guide?: InstallationGuide;
     presets?: Record<string, InstallationPreset>;
-    legacyPreset?: string;
 }
 /** One validated catalog is used by the website and extension; parameters cannot add install sources. */
 export declare function parseInstallationConfig(value: unknown, publicOrigin: string): InstallationConfig;
@@ -22,3 +21,8 @@ export declare function matchesInstallationOrigin(scope: string, target: URL): b
 export declare const INSTALLATION_CONFIG_MAX_BYTES = 65536;
 export declare function readInstallationJson(response: Response, maxBytes: number): Promise<unknown>;
 export declare function loadInstallationConfig(url: string | URL, publicOrigin: string, signal?: AbortSignal): Promise<InstallationConfig>;
+export declare const PRESET_UPDATE_INTERVAL_MS: number;
+export declare const PRESET_UPDATE_RETRY_MS: number;
+export declare function trustedInstallationPreset(config: InstallationConfig, id: string | undefined, source: string | undefined): InstallationPreset | undefined;
+/** An exact scope can be covered by a broader catalog scope, never the reverse. */
+export declare function installationOriginCovered(origin: string, scopes: readonly string[]): boolean;

package/dist/installation.js

@@ -14,7 +14,7 @@ function httpsUrl(value) {
 }
 /** One validated catalog is used by the website and extension; parameters cannot add install sources. */
 export function parseInstallationConfig(value, publicOrigin) {
-    const input = record(value, ['schemaVersion', 'guide', 'presets', 'legacyPreset']);
+    const input = record(value, ['schemaVersion', 'guide', 'presets']);
     if (input.schemaVersion !== 1)
         throw new Error('Invalid installation schema');
     const result = { schemaVersion: 1 };
@@ -47,11 +47,6 @@ export function parseInstallationConfig(value, publicOrigin) {
             return [id, { label: entry.label, source, origins }];
         }));
     }
-    if (input.legacyPreset !== undefined) {
-        if (typeof input.legacyPreset !== 'string' || !Object.hasOwn(result.presets ?? {}, input.legacyPreset))
-            throw new Error('Invalid legacy installation preset');
-        result.legacyPreset = input.legacyPreset;
-    }
     return result;
 }
 /** Explicit host scopes retain their selected schemes; download sources remain HTTPS. */
@@ -114,3 +109,21 @@ export async function loadInstallationConfig(url, publicOrigin, signal) {
         throw new Error('Installation configuration unavailable');
     return parseInstallationConfig(await readInstallationJson(response, INSTALLATION_CONFIG_MAX_BYTES), publicOrigin);
 }
+export const PRESET_UPDATE_INTERVAL_MS = 12 * 60 * 60_000;
+export const PRESET_UPDATE_RETRY_MS = 60 * 60_000;
+export function trustedInstallationPreset(config, id, source) {
+    return id && source && Object.hasOwn(config.presets ?? {}, id) && config.presets[id].source === source ? config.presets[id] : undefined;
+}
+/** An exact scope can be covered by a broader catalog scope, never the reverse. */
+export function installationOriginCovered(origin, scopes) {
+    const target = validateInstallationOrigin(origin);
+    const wildcard = /^(?:https?|\*):\/\/\*\./.test(target);
+    const schemes = target.startsWith('*:') ? ['http:', 'https:'] : [target.slice(0, target.indexOf(':') + 1)];
+    return scopes.some(scope => {
+        const candidate = validateInstallationOrigin(scope);
+        if (wildcard && !/^(?:https?|\*):\/\/\*\./.test(candidate))
+            return false;
+        const base = target.replace(/^\*:/, 'https:').replace(/^(https?:\/\/)\*\./, '$1');
+        return schemes.every(scheme => { const url = new URL(base); url.protocol = scheme; return matchesInstallationOrigin(candidate, url); });
+    });
+}

package/dist/management.d.ts

@@ -0,0 +1,10 @@
+export interface SetupManagement {
+    package: string;
+    version: string;
+    registry?: string;
+    runtime?: string;
+}
+/** Declarative installation guidance; never accepts commands, arguments or executable hooks. */
+export declare function parseSetupManagement(value: unknown): SetupManagement | undefined;
+export declare function setupManagementCommand(setup: SetupManagement): string;
+export declare function setupRuntimeCompatible(setup: SetupManagement, version: string, targetLine?: string): boolean;

package/dist/management.js

@@ -0,0 +1,36 @@
+import { valid, validRange, satisfies, subset } from 'semver';
+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))
+        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)))
+        return invalid();
+    if (setup.registry !== undefined) {
+        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);
+            if (!url.hostname || url.username || url.password || url.search || url.hash)
+                return invalid();
+        }
+        catch {
+            return invalid();
+        }
+    }
+    if (setup.runtime !== undefined && (typeof setup.runtime !== 'string' || setup.runtime.length > 128 || !validRange(setup.runtime)))
+        return invalid();
+    return { ...setup };
+}
+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 })));
+}

package/dist/manifest.js

@@ -1,3 +1,4 @@
+import { validateInstallationOrigin } from './installation.js';
 import { valid, validRange } from 'semver';
 export class PresetError extends Error {
     code;
@@ -70,18 +71,25 @@ export function clonePresetDefaults(value) {
     object(value, 'defaults');
     return json(value, 'defaults');
 }
-function component(value, path) {
-    fields(value, path, ['source', 'version', 'enabled', 'runtimes', 'dependsOn']);
+function component(value, path, kind) {
+    fields(value, path, ['source', 'version', 'enabled', 'targets', 'dependsOn', 'migrateFrom']);
     if ('source' in value)
         text(value.source, `${path}.source`);
     if ('version' in value)
         range(value.version, `${path}.version`);
+    if ('migrateFrom' in value) {
+        if (kind !== 'skills')
+            invalid(`${path}.migrateFrom`, 'only Skills support source migration');
+        stringArray(value.migrateFrom, `${path}.migrateFrom`);
+        if (value.migrateFrom.length > 16)
+            invalid(`${path}.migrateFrom`, 'exceeds 16 sources');
+    }
     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) {
@@ -120,7 +128,7 @@ export function validatePreset(value) {
         object(declarations, kind);
         result[kind] = Object.fromEntries(Object.entries(declarations).map(([key, item]) => {
             id(key, `${kind}.${key}`);
-            return [key, component(item, `${kind}.${key}`)];
+            return [key, component(item, `${kind}.${key}`, kind)];
         }));
     }
     if ('appProfiles' in value) {
@@ -137,7 +145,17 @@ export function validatePreset(value) {
         fields(value.permissions, 'permissions', ['origins']);
         if ('origins' in value.permissions)
             stringArray(value.permissions.origins, 'permissions.origins');
-        result.permissions = { origins: [...(value.permissions.origins ?? [])] };
+        const origins = value.permissions.origins ?? [];
+        if (origins.length > 64)
+            invalid('permissions.origins', 'exceeds 64 scopes');
+        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/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');

package/dist/preset.js

@@ -1,5 +1,5 @@
 import { browserPresetSnapshot } from './browserPreset.js';
-import { preparePresetPackages, presetSnapshotRevision, verifyPresetGraph } from './prepare.js';
+import { preparePresetPackages, presetSnapshotRevision, verifyPresetGraph, verifyPackageTargets } from './prepare.js';
 import { satisfies } from 'semver';
 import { BundleError, MAX_BROWSER_STORAGE_BYTES, verifyBundle } from './bundle.js';
 export async function preparePreset(source, options) {
@@ -9,6 +9,7 @@ export async function preparePreset(source, options) {
         source: prepared.source,
         manifests: prepared.manifests,
         bundleRevisions: Object.fromEntries(prepared.bundles.map(bundle => [bundle.manifest.id, bundle.revision])),
+        packageTargets: prepared.packageTargets,
     };
     const snapshot = { ...data, revision: await presetSnapshotRevision(data) };
     const browser = await browserPresetSnapshot(prepared.source, prepared.manifests, prepared.preset, prepared.bundles);
@@ -44,6 +45,7 @@ export async function verifyPreparedPreset(value, mearlApiVersion) {
         Promise.all(value.bundles.map(bundle => verifyBundle(bundle, 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));

package/dist/requestUi.d.ts

@@ -49,7 +49,9 @@ export interface SelectedBrowserRequestUi {
     definition: BrowserRequestUi;
 }
 export declare function validateBrowserUiText(value: unknown): void;
-export declare function browserUiHttpUrl(value: unknown): string;
+export declare function browserUiHttpUrl(value: unknown, options?: {
+    allowFragment?: boolean;
+}): string;
 export declare function validateBrowserRequestUi(input: unknown): BrowserRequestUi;
 /** Contribution validation is pure; factories and UI side effects belong to the host. */
 export declare function selectBrowserRequestUi(bundles: PreparedBundle[], apiVersion: string): SelectedBrowserRequestUi | undefined;

package/dist/requestUi.js

@@ -10,7 +10,7 @@ export function validateBrowserUiText(value) {
     if (typeof value.en !== 'string' || !value.en.trim() || Object.values(value).some(entry => typeof entry !== 'string' || entry.length > 1024 || !entry.trim()))
         invalid('Request UI text requires bounded translations');
 }
-export function browserUiHttpUrl(value) {
+export function browserUiHttpUrl(value, options = {}) {
     if (typeof value !== 'string' || value.length > 4096)
         invalid('Invalid request UI URL');
     let url;
@@ -20,7 +20,7 @@ export function browserUiHttpUrl(value) {
     catch {
         invalid('Invalid request UI URL');
     }
-    if (url.username || url.password || url.hash || url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)))
+    if (url.username || url.password || !options.allowFragment && url.hash || url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)))
         invalid('Request UI requires credential-free HTTPS or loopback URLs');
     return url.href;
 }

package/dist/resolve.js

@@ -1,3 +1,5 @@
+import { parseToolboxCatalogs } from './toolboxCatalogs.js';
+import { parseSetupManagement } from './management.js';
 import { satisfies, valid } from 'semver';
 import { clonePresetDefaults, isJsonObject, PresetError, validatePreset } from './manifest.js';
 const kinds = ['packages', 'skills', 'providers'];
@@ -118,6 +120,7 @@ export async function resolvePreset(source, options) {
                     ...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)) }),
                     declaredBy: url,
                 };
             }
@@ -126,6 +129,10 @@ export async function resolvePreset(source, options) {
         return result;
     };
     const result = await load(sourceUrl(source));
+    parseSetupManagement(result.defaults.management);
+    const extension = result.defaults.extension;
+    if (isJsonObject(extension))
+        parseToolboxCatalogs(extension.toolCatalogs);
     // Dependency validity is checked on the final graph, so children may complete or disable parent entries.
     for (const kind of kinds)
         validateDependencies(kind, result[kind]);

package/dist/toolboxCatalogs.d.ts

@@ -0,0 +1,8 @@
+export interface ToolboxCatalogConfig {
+    url?: string;
+    label?: string;
+    enabled?: boolean;
+}
+export type ToolboxCatalogConfigs = Record<string, ToolboxCatalogConfig>;
+/** Stable keys let child presets patch or disable a parent directory through defaults merging. */
+export declare function parseToolboxCatalogs(input: unknown): ToolboxCatalogConfigs;

package/dist/toolboxCatalogs.js

@@ -0,0 +1,34 @@
+import { isJsonObject, PresetError } from './manifest.js';
+/** Stable keys let child presets patch or disable a parent directory through defaults merging. */
+export function parseToolboxCatalogs(input) {
+    if (input === undefined)
+        return {};
+    function invalid() { throw new PresetError('PRESET_INVALID', 'Invalid extension.toolCatalogs configuration'); }
+    if (!isJsonObject(input) || Object.keys(input).length > 16)
+        invalid();
+    return Object.fromEntries(Object.entries(input).map(([id, entry]) => {
+        if (!/^[a-z][a-z0-9-]{0,63}$/.test(id) || id === 'official' || !isJsonObject(entry) || Object.keys(entry).some(key => !['url', 'label', 'enabled'].includes(key)))
+            invalid();
+        if (entry.enabled !== undefined && typeof entry.enabled !== 'boolean')
+            invalid();
+        if (entry.label !== undefined && (typeof entry.label !== 'string' || !entry.label.trim() || entry.label.length > 120))
+            invalid();
+        let url;
+        if (entry.url !== undefined) {
+            if (typeof entry.url !== 'string' || entry.url.length > 2048)
+                invalid();
+            try {
+                const parsed = new URL(entry.url);
+                if (parsed.username || parsed.password || parsed.hash || !(parsed.protocol === 'https:' || parsed.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname)))
+                    invalid();
+                url = parsed.href;
+            }
+            catch {
+                invalid();
+            }
+        }
+        else if (entry.enabled !== false)
+            invalid();
+        return [id, { ...(url ? { url } : {}), ...(entry.label !== undefined ? { label: entry.label } : {}), ...(entry.enabled !== undefined ? { enabled: entry.enabled } : {}) }];
+    }));
+}

package/dist/types.d.ts

@@ -8,8 +8,11 @@ export interface PresetComponent {
     /** Bundle URL for packages; installer-specific source for skills and providers. */
     source?: string;
     version?: string;
+    /** Previous Skill sources eligible for migration only when setup owns the installation. */
+    migrateFrom?: string[];
     enabled?: boolean;
-    runtimes?: PresetRuntime[];
+    /** Optional activation subset; supported locations are defined by the package. */
+    targets?: PresetRuntime[];
     dependsOn?: string[];
 }
 export interface PresetReference {

package/installation-site.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://mearlhq.github.io/mearl/",
+  "extensionId": "aoehhjnofngknnjefamjbplchbolghkm"
+}