@mearl/preset 0.0.0-stage → 3.0.0-beta.0

package/dist/installation.js

@@ -0,0 +1,116 @@
+function record(value, allowed) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !allowed.includes(key))) {
+        throw new Error('Invalid installation configuration');
+    }
+    return value;
+}
+function httpsUrl(value) {
+    if (typeof value !== 'string' || value.length > 4096)
+        throw new Error('Invalid installation URL');
+    const url = new URL(value);
+    if (url.protocol !== 'https:' || url.username || url.password || url.hash)
+        throw new Error('Invalid installation URL');
+    return url;
+}
+/** 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']);
+    if (input.schemaVersion !== 1)
+        throw new Error('Invalid installation schema');
+    const result = { schemaVersion: 1 };
+    if (input.guide !== undefined) {
+        const guide = record(input.guide, ['url', 'registry']);
+        const url = httpsUrl(guide.url);
+        const registry = httpsUrl(guide.registry);
+        if (url.origin === publicOrigin || registry.origin === publicOrigin || registry.search || !registry.pathname.endsWith('/'))
+            throw new Error('Invalid registry URL');
+        result.guide = { url: url.href, registry: registry.href };
+    }
+    if (input.presets !== undefined) {
+        if (!result.guide || !input.presets || typeof input.presets !== 'object' || Array.isArray(input.presets))
+            throw new Error('A preset catalog requires its guide');
+        const entries = Object.entries(input.presets);
+        if (entries.length > 32)
+            throw new Error('Installation catalog exceeds 32 presets');
+        result.presets = Object.fromEntries(entries.map(([id, value]) => {
+            if (!/^[a-z][a-z0-9-]{0,79}$/.test(id))
+                throw new Error('Invalid installation preset ID');
+            const entry = record(value, ['label', 'source', 'origins']);
+            if (typeof entry.label !== 'string' || !entry.label.trim() || entry.label.length > 120 || /[\u0000-\u001f\u007f]/.test(entry.label))
+                throw new Error('Invalid preset label');
+            const source = httpsUrl(entry.source).href;
+            if (!Array.isArray(entry.origins) || entry.origins.length > 64)
+                throw new Error('Expected preset permission origins');
+            const origins = [...new Set([`${new URL(source).origin}/*`, ...entry.origins.map(validateInstallationOrigin)])];
+            if (origins.length > 64)
+                throw new Error('Installation permission origins exceed 64 scopes');
+            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. */
+export function validateInstallationOrigin(value) {
+    if (typeof value !== 'string' || value.length > 4096 || !/^(https?|\*):\/\//.test(value) || !value.endsWith('/*'))
+        throw new Error('Invalid installation permission origin');
+    const scheme = value.slice(0, value.indexOf(':'));
+    const wildcard = /^(?:https?|\*):\/\/\*\./.test(value);
+    const normalized = value.replace(/^\*:/, 'https:').replace(/^(https?:\/\/)\*\./, '$1');
+    const url = new URL(normalized);
+    if (url.username || url.password || url.hash || url.hostname.includes('*') || url.pathname !== '/*' || url.search || !url.hostname || (wildcard && !url.hostname.includes('.')))
+        throw new Error('Invalid installation permission origin');
+    return `${scheme}://${wildcard ? '*.' : ''}${url.host}/*`;
+}
+/** Match both scheme and host against a catalog scope before loading a resource. */
+export function matchesInstallationOrigin(scope, target) {
+    const value = validateInstallationOrigin(scope);
+    const scheme = value.slice(0, value.indexOf(':'));
+    if (scheme === '*' ? !['http:', 'https:'].includes(target.protocol) : `${scheme}:` !== target.protocol)
+        return false;
+    const wildcard = /^(?:https?|\*):\/\/\*\./.test(value);
+    const origin = new URL(value.replace(/^\*:/, 'https:').replace(/^(https?:\/\/)\*\./, '$1'));
+    return (!origin.port || origin.port === target.port) && (target.hostname === origin.hostname || wildcard && target.hostname.endsWith(`.${origin.hostname}`));
+}
+export const INSTALLATION_CONFIG_MAX_BYTES = 65_536;
+export async function readInstallationJson(response, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > INSTALLATION_CONFIG_MAX_BYTES)
+        throw new Error('Invalid installation response size limit');
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('Missing installation response');
+    const chunks = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            length += value.byteLength;
+            if (length > maxBytes)
+                throw new Error('Installation response is too large');
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+}
+export async function loadInstallationConfig(url, publicOrigin, signal) {
+    const response = await fetch(url, { cache: 'no-store', credentials: 'omit', redirect: 'error', signal });
+    if (!response.ok || !response.headers.get('content-type')?.includes('application/json'))
+        throw new Error('Installation configuration unavailable');
+    return parseInstallationConfig(await readInstallationJson(response, INSTALLATION_CONFIG_MAX_BYTES), publicOrigin);
+}

package/dist/manifest.d.ts

@@ -0,0 +1,9 @@
+import type { JsonObject, PresetManifest } from './types.js';
+export declare class PresetError extends Error {
+    readonly code: 'PRESET_INVALID' | 'PRESET_CYCLE' | 'PRESET_INCOMPATIBLE' | 'PRESET_DEPENDENCY';
+    constructor(code: 'PRESET_INVALID' | 'PRESET_CYCLE' | 'PRESET_INCOMPATIBLE' | 'PRESET_DEPENDENCY', message: string);
+}
+export declare function isJsonObject(value: unknown): value is Record<string, unknown>;
+/** Validates and clones JSON configuration without executing or evaluating it. */
+export declare function clonePresetDefaults(value: unknown): JsonObject;
+export declare function validatePreset(value: unknown): PresetManifest;

package/dist/manifest.js

@@ -0,0 +1,145 @@
+import { valid, validRange } from 'semver';
+export class PresetError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.name = 'PresetError';
+    }
+}
+const unsafeKeys = new Set(['__proto__', 'constructor', 'prototype']);
+const componentId = /^[a-z][a-z0-9-]{0,79}$/;
+function invalid(path, reason) {
+    throw new PresetError('PRESET_INVALID', `${path}: ${reason}`);
+}
+export function isJsonObject(value) {
+    return value !== null && typeof value === 'object' &&
+        !Array.isArray(value) &&
+        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+function object(value, path) {
+    if (!isJsonObject(value))
+        invalid(path, 'expected a plain object');
+    for (const key of Object.keys(value))
+        if (unsafeKeys.has(key))
+            invalid(path, `unsafe key ${key}`);
+}
+function fields(value, path, names) {
+    object(value, path);
+    for (const key of Object.keys(value)) {
+        if (!names.includes(key))
+            invalid(`${path}.${key}`, 'unknown field');
+    }
+}
+function text(value, path) {
+    if (typeof value !== 'string' || !value.trim() || value !== value.trim()) {
+        invalid(path, 'expected a non-empty trimmed string');
+    }
+}
+function id(value, path) {
+    if (typeof value !== 'string' || !componentId.test(value))
+        invalid(path, 'invalid ID');
+}
+function range(value, path) {
+    text(value, path);
+    if (validRange(value) === null)
+        invalid(path, 'invalid version range');
+}
+function stringArray(value, path) {
+    if (!Array.isArray(value))
+        invalid(path, 'expected an array');
+    for (const [index, item] of value.entries())
+        text(item, `${path}[${index}]`);
+    if (new Set(value).size !== value.length)
+        invalid(path, 'duplicate values');
+}
+function json(value, path, depth = 0) {
+    if (depth > 32)
+        invalid(path, 'JSON nesting exceeds 32 levels');
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value))
+        return Array.from(value, (item, index) => json(item, `${path}[${index}]`, depth + 1));
+    object(value, path);
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, json(item, `${path}.${key}`, depth + 1)]));
+}
+/** Validates and clones JSON configuration without executing or evaluating it. */
+export function clonePresetDefaults(value) {
+    object(value, 'defaults');
+    return json(value, 'defaults');
+}
+function component(value, path) {
+    fields(value, path, ['source', 'version', 'enabled', 'runtimes', 'dependsOn']);
+    if ('source' in value)
+        text(value.source, `${path}.source`);
+    if ('version' in value)
+        range(value.version, `${path}.version`);
+    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 ('dependsOn' in value) {
+        stringArray(value.dependsOn, `${path}.dependsOn`);
+        for (const item of value.dependsOn)
+            id(item, `${path}.dependsOn`);
+    }
+    return json(value, path);
+}
+export function validatePreset(value) {
+    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');
+    text(value.version, 'version');
+    if (valid(value.version) !== value.version)
+        invalid('version', 'expected an exact semantic version');
+    const result = { schemaVersion: 1, id: value.id, version: value.version };
+    if ('extends' in value) {
+        fields(value.extends, 'extends', ['source', 'version']);
+        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 }) };
+    }
+    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 }) };
+    }
+    for (const kind of ['packages', 'skills', 'providers']) {
+        if (!(kind in value))
+            continue;
+        const declarations = value[kind];
+        object(declarations, kind);
+        result[kind] = Object.fromEntries(Object.entries(declarations).map(([key, item]) => {
+            id(key, `${kind}.${key}`);
+            return [key, component(item, `${kind}.${key}`)];
+        }));
+    }
+    if ('appProfiles' in value) {
+        object(value.appProfiles, 'appProfiles');
+        result.appProfiles = Object.fromEntries(Object.entries(value.appProfiles).map(([key, target]) => {
+            id(key, `appProfiles.${key}`);
+            text(target, `appProfiles.${key}`);
+            return [key, target];
+        }));
+    }
+    if ('defaults' in value)
+        result.defaults = clonePresetDefaults(value.defaults);
+    if ('permissions' in value) {
+        fields(value.permissions, 'permissions', ['origins']);
+        if ('origins' in value.permissions)
+            stringArray(value.permissions.origins, 'permissions.origins');
+        result.permissions = { origins: [...(value.permissions.origins ?? [])] };
+    }
+    if (JSON.stringify(result).length > 262_144)
+        invalid('preset', 'manifest exceeds 256 Ki UTF-16 code units');
+    return result;
+}

package/dist/nodeSnapshot.d.ts

@@ -0,0 +1,38 @@
+import type { JsonObject } from './types.js';
+export interface NodeCapabilitySelection {
+    schemaVersion: 1;
+    modules: Record<string, {
+        sha256: string;
+        byteLength: number;
+        config?: JsonObject;
+    }>;
+    bindings: Record<string, {
+        module: string;
+        handler: string;
+    }>;
+}
+export interface NodeCapabilitySnapshot extends NodeCapabilitySelection {
+    revision: string;
+}
+export interface NodeCapabilityActivation extends NodeCapabilitySnapshot {
+    installationRevision?: string;
+}
+export declare const MAX_NODE_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>;
+/** Preset defaults are inherited; explicit host configuration stays a separate override. */
+export declare function resolvePresetModuleConfig(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>;
+/** The installer receipt and Node selection share one atomic filesystem pointer. */
+export declare function verifyNodeCapabilityActivation(input: NodeCapabilityActivation): Promise<NodeCapabilityActivation>;
+export declare function prepareNodeBundleSnapshot(bundles: import('./bundle.js').PreparedBundle[], host: string, mearlApiVersion: string, config?: Record<string, JsonObject>): Promise<{
+    snapshot: NodeCapabilitySnapshot;
+    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;
+    resources: Record<string, Uint8Array>;
+}>;

package/dist/nodeSnapshot.js

@@ -0,0 +1,136 @@
+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;
+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');
+}
+/** Explicit module configuration survives periods where a preset disables its module. */
+export function validateNodeModuleConfig(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');
+    for (const [id, config] of Object.entries(configs))
+        if (!identifier.test(id) || !isJsonObject(config))
+            invalid('Node 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 = {}) {
+    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)));
+}
+/** Exact content and bindings are selected together; filesystem and code loading belong to hosts. */
+export async function prepareNodeCapabilitySnapshot(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');
+    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');
+    const modules = {};
+    let total = 0;
+    for (const id of Object.keys(value.modules).sort()) {
+        if (!identifier.test(id))
+            invalid('Invalid Node 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');
+        if (entry.config !== undefined && !isJsonObject(entry.config))
+            invalid('Node 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');
+        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');
+        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');
+        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');
+    return { ...selection, revision: await bundleDigest(new TextEncoder().encode(JSON.stringify(selection))) };
+}
+export async function verifyNodeCapabilitySnapshot(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');
+    const { revision, ...selection } = value;
+    const prepared = await prepareNodeCapabilitySnapshot(selection);
+    if (prepared.revision !== revision)
+        throw new BundleError('BUNDLE_INTEGRITY', 'Node capability selection revision does not match');
+    return prepared;
+}
+/** The installer receipt and Node selection share one atomic filesystem pointer. */
+export async function verifyNodeCapabilityActivation(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);
+    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);
+    const modules = {};
+    const bindings = {};
+    const resources = {};
+    const pending = [];
+    let total = 0;
+    for (const bundle of bundles) {
+        const manifest = validateBundleManifest(bundle.manifest, mearlApiVersion);
+        const runtime = manifest.contributions?.[kind]?.[host];
+        if (!runtime)
+            continue;
+        if (Object.hasOwn(modules, manifest.id))
+            invalid('Duplicate Node module ID');
+        const metadata = manifest.resources[runtime.entry];
+        if (!Object.hasOwn(bundle.resources, runtime.entry))
+            invalid('Node 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');
+        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]) } : {}) };
+        for (const [name, handler] of Object.entries(runtime.bindings)) {
+            if (Object.hasOwn(bindings, name))
+                invalid('Node hook has multiple providers');
+            bindings[name] = { module: manifest.id, handler };
+        }
+    }
+    // Capture the complete accepted batch before the first asynchronous digest.
+    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}`);
+        resources[resource.sha256] = resource.bytes;
+    }
+    return { snapshot: await prepareNodeCapabilitySnapshot({ schemaVersion: 1, modules, bindings }), resources };
+}
+export function prepareNodeBundleSnapshot(bundles, host, mearlApiVersion, config = {}) {
+    return prepareRuntimeBundleSnapshot(bundles, 'nodeRuntimes', host, mearlApiVersion, config);
+}
+/** Browser factories use the same exact module/configuration selection without a Node loader. */
+export function prepareBrowserBundleSnapshot(bundles, host, mearlApiVersion, config = {}) {
+    return prepareRuntimeBundleSnapshot(bundles, 'browserRuntimes', host, mearlApiVersion, config);
+}

package/dist/pageRuntime.d.ts

@@ -0,0 +1,19 @@
+/** A content-addressed MAIN world installer, delivered through a prepared debugger bootstrap. */
+export interface PageRuntimeBinding {
+    id: string;
+    sha256: string;
+}
+export interface PageRuntimeConfig {
+    pageRuntime?: PageRuntimeBinding;
+}
+type Installer = (config: PageRuntimeConfig) => void;
+interface PageRuntimeHost {
+    install<Config extends PageRuntimeConfig>(config: Config, fallback?: (config: Config) => void): void;
+    register(sha256: string, installer: Installer): void;
+}
+/** Self-contained because the debugger serializes this function into each document. */
+export declare function installPageRuntimeHost(): PageRuntimeHost;
+/** The returned source is executed only in the controlled page, never in the extension host. */
+export declare function buildPageRuntimeRegistrationSource(binding: PageRuntimeBinding, source: string, installerGlobal: string): string;
+export declare function buildPageRuntimeCallSource(configExpression: string): string;
+export {};

package/dist/pageRuntime.js

@@ -0,0 +1,47 @@
+/** Self-contained because the debugger serializes this function into each document. */
+export function installPageRuntimeHost() {
+    const root = window;
+    if (root.__mearlPageRuntimeHost__)
+        return root.__mearlPageRuntimeHost__;
+    const installers = new Map();
+    const pending = new Map();
+    const host = {
+        install(config, fallback) {
+            const binding = config.pageRuntime;
+            if (!binding) {
+                fallback?.(config);
+                return;
+            }
+            const installer = installers.get(binding.sha256);
+            if (installer) {
+                installer(config);
+                return;
+            }
+            const waiting = pending.get(binding.sha256) ?? [];
+            waiting.push(config);
+            pending.set(binding.sha256, waiting);
+        },
+        register(sha256, installer) {
+            if (typeof installer !== 'function')
+                throw new Error('A page runtime must export an install function');
+            if (installers.has(sha256))
+                return;
+            installers.set(sha256, installer);
+            const waiting = pending.get(sha256) ?? [];
+            pending.delete(sha256);
+            for (const config of waiting)
+                installer(config);
+        },
+    };
+    Object.defineProperty(root, '__mearlPageRuntimeHost__', { configurable: true, value: host });
+    return host;
+}
+/** The returned source is executed only in the controlled page, never in the extension host. */
+export function buildPageRuntimeRegistrationSource(binding, source, installerGlobal) {
+    if (!/^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/.test(binding.id) || !/^[a-f0-9]{64}$/.test(binding.sha256) || !source.trim())
+        throw new Error('Invalid page runtime binding');
+    return `;(() => { const host=(${installPageRuntimeHost.toString()})(); const module={exports:{}};\n(function(module,exports){\n${source}\n})(module,module.exports);\nhost.register(${JSON.stringify(binding.sha256)},module.exports.install); Object.defineProperty(window,${JSON.stringify(installerGlobal)},{configurable:true,value:config=>host.install(config)}); })();`;
+}
+export function buildPageRuntimeCallSource(configExpression) {
+    return `(${installPageRuntimeHost.toString()})().install(${configExpression});`;
+}

package/dist/prepare.d.ts

@@ -0,0 +1,34 @@
+import { type BundleLoader, type PreparedBundle } from './bundle.js';
+import type { PresetManifest, PresetRuntime, ResolvedComponent, ResolvedPreset } from './types.js';
+export interface PreparePresetOptions {
+    load: BundleLoader;
+    mearlApiVersion: string;
+    signal?: AbortSignal;
+    /** One budget covers inheritance manifests, package manifests and resource bytes. */
+    maxDownloadBytes?: number;
+}
+export interface PresetGraphSnapshot {
+    source: string;
+    manifests: Record<string, PresetManifest>;
+    bundleRevisions: Record<string, string>;
+    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]>;
+/** 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[];
+}>;
+/** The exact graph is checked offline; installed resources are verified by the target store. */
+export declare function verifyPresetGraph(value: PresetGraphSnapshot & {
+    schemaVersion?: 1;
+}, mearlApiVersion: string, runtimes: PresetRuntime[], full: boolean): Promise<{
+    snapshot: PresetGraphSnapshot & {
+        schemaVersion?: 1;
+    };
+    preset: ResolvedPreset;
+}>;