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

package/dist/prepare.js

@@ -0,0 +1,112 @@
+import { BundleError, MAX_BROWSER_STORAGE_BYTES, bundleDigest, bundleSourceUrl, prepareBundle } from './bundle.js';
+import { clonePresetDefaults, validatePreset } from './manifest.js';
+import { resolvePreset } from './resolve.js';
+export async function presetSnapshotRevision(value) {
+    return bundleDigest(new TextEncoder().encode(JSON.stringify(value)));
+}
+/** 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 ids = new Set(entries.map(([id]) => id));
+        for (const [id, entry] of entries) {
+            if (entry.dependsOn?.some(dependency => !ids.has(dependency))) {
+                throw new BundleError('BUNDLE_INCOMPATIBLE', `${runtime === 'browser' ? 'Browser' : 'Node'} package ${id} requires a package unavailable in ${runtime}`);
+            }
+        }
+        if (runtime === 'browser') {
+            for (const target of Object.values(preset.appProfiles)) {
+                if (!/^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/.test(target) || !ids.has(target.split('/')[0])) {
+                    throw new BundleError('BUNDLE_INVALID', 'App implementations must belong to an enabled browser package');
+                }
+            }
+        }
+    }
+    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;
+}
+/** Shared preparation performs no installation, code execution or permission changes. */
+export async function preparePresetPackages(source, options, runtimes) {
+    source = bundleSourceUrl(source);
+    let remaining = options.maxDownloadBytes ?? MAX_BROWSER_STORAGE_BYTES;
+    if (!Number.isSafeInteger(remaining) || remaining <= 0 || remaining > MAX_BROWSER_STORAGE_BYTES)
+        throw new BundleError('BUNDLE_QUOTA', 'Invalid preset download budget');
+    const load = async (url, request) => {
+        if (remaining <= 0)
+            throw new BundleError('BUNDLE_QUOTA', 'Preset downloads exceed the shared budget');
+        const limit = Math.min(request.maxBytes, remaining);
+        const bytes = await options.load(url, { ...request, maxBytes: limit });
+        if (bytes.byteLength > limit)
+            throw new BundleError('BUNDLE_QUOTA', 'Preset download exceeds its size limit');
+        remaining -= bytes.byteLength;
+        return bytes;
+    };
+    const manifests = {};
+    const preset = await resolvePreset(source, {
+        mearlApiVersion: options.mearlApiVersion,
+        signal: options.signal,
+        load: async (url) => {
+            const bytes = Uint8Array.from(await load(url, { maxBytes: 262_144, signal: options.signal }));
+            let manifest;
+            try {
+                manifest = validatePreset(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)));
+            }
+            catch (error) {
+                throw new BundleError('BUNDLE_INVALID', error instanceof Error ? error.message : 'Invalid preset manifest');
+            }
+            manifests[url] = manifest;
+            return manifest;
+        },
+    });
+    const entries = presetPackages(preset, runtimes);
+    const bundles = [];
+    for (const [id, entry] of entries) {
+        bundles.push(await prepareBundle(entry.source, { ...options, load, expectedId: id, version: entry.version }));
+    }
+    options.signal?.throwIfAborted();
+    return { source, manifests, preset, bundles };
+}
+/** 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'] : [])];
+    if (Object.keys(json).some(key => !allowed.includes(key)) || (full && json.schemaVersion !== 1) ||
+        typeof json.source !== 'string' || typeof json.revision !== 'string' || !/^[a-f0-9]{64}$/.test(json.revision)) {
+        throw new BundleError('BUNDLE_INTEGRITY', 'Invalid stored preset identity');
+    }
+    const source = bundleSourceUrl(json.source);
+    const manifests = clonePresetDefaults(json.manifests);
+    if (Object.keys(manifests).length > 32)
+        throw new BundleError('BUNDLE_QUOTA', 'Stored preset inheritance exceeds 32 manifests');
+    const bundleRevisions = clonePresetDefaults(json.bundleRevisions);
+    if (Object.keys(bundleRevisions).length > 64 || Object.values(bundleRevisions).some(revision => typeof revision !== 'string' || !/^[a-f0-9]{64}$/.test(revision))) {
+        throw new BundleError('BUNDLE_INTEGRITY', 'Invalid stored package revisions');
+    }
+    const validated = {};
+    for (const [url, manifest] of Object.entries(manifests)) {
+        if (url !== bundleSourceUrl(url))
+            throw new BundleError('BUNDLE_INTEGRITY', 'Invalid stored preset source');
+        validated[url] = validatePreset(manifest);
+    }
+    const data = { ...(full ? { schemaVersion: 1 } : {}), source, manifests: validated, bundleRevisions };
+    if (await presetSnapshotRevision(data) !== json.revision)
+        throw new BundleError('BUNDLE_INTEGRITY', 'Stored preset revision does not match');
+    const preset = await resolvePreset(source, {
+        mearlApiVersion,
+        load: async (url) => {
+            if (!Object.hasOwn(validated, url))
+                throw new BundleError('BUNDLE_INTEGRITY', 'Stored parent preset is missing');
+            return validated[url];
+        },
+    });
+    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');
+    }
+    return { snapshot: { ...data, revision: json.revision }, preset };
+}

package/dist/preset.d.ts

@@ -0,0 +1,24 @@
+import { type PreparedBrowserPreset } from './browserPreset.js';
+import { type PreparePresetOptions, type PresetGraphSnapshot } from './prepare.js';
+import type { PreparedBundle } from './bundle.js';
+import type { ResolvedPreset } from './types.js';
+/** Whole-preset identity includes both execution locations and the captured inheritance graph. */
+export interface PresetSnapshot extends PresetGraphSnapshot {
+    schemaVersion: 1;
+}
+export interface PreparedPreset {
+    snapshot: PresetSnapshot;
+    preset: ResolvedPreset;
+    /** Each package is downloaded once, including packages used by both runtimes. */
+    bundles: PreparedBundle[];
+    /** Compatible with the browser's existing atomic activation and offline restore contract. */
+    browser: PreparedBrowserPreset;
+}
+export declare function preparePreset(source: string, options: PreparePresetOptions): Promise<PreparedPreset>;
+/** Verifies the lock graph without fetching sources or executing capability factories. */
+export declare function verifyPreset(value: PresetSnapshot, mearlApiVersion: string): Promise<{
+    snapshot: PresetSnapshot;
+    preset: ResolvedPreset;
+}>;
+/** Captures and validates the entire accepted batch before an installation host persists it. */
+export declare function verifyPreparedPreset(value: Pick<PreparedPreset, 'snapshot' | 'bundles'>, mearlApiVersion: string): Promise<PreparedPreset>;

package/dist/preset.js

@@ -0,0 +1,53 @@
+import { browserPresetSnapshot } from './browserPreset.js';
+import { preparePresetPackages, presetSnapshotRevision, verifyPresetGraph } from './prepare.js';
+import { satisfies } from 'semver';
+import { BundleError, MAX_BROWSER_STORAGE_BYTES, verifyBundle } from './bundle.js';
+export async function preparePreset(source, options) {
+    const prepared = await preparePresetPackages(source, options, ['browser', 'node']);
+    const data = {
+        schemaVersion: 1,
+        source: prepared.source,
+        manifests: prepared.manifests,
+        bundleRevisions: Object.fromEntries(prepared.bundles.map(bundle => [bundle.manifest.id, bundle.revision])),
+    };
+    const snapshot = { ...data, revision: await presetSnapshotRevision(data) };
+    const browser = await browserPresetSnapshot(prepared.source, prepared.manifests, prepared.preset, prepared.bundles);
+    options.signal?.throwIfAborted();
+    return { snapshot, preset: prepared.preset, bundles: prepared.bundles, browser };
+}
+/** Verifies the lock graph without fetching sources or executing capability factories. */
+export async function verifyPreset(value, mearlApiVersion) {
+    const result = await verifyPresetGraph(value, mearlApiVersion, ['browser', 'node'], true);
+    return { ...result, snapshot: result.snapshot };
+}
+/** Captures and validates the entire accepted batch before an installation host persists it. */
+export async function verifyPreparedPreset(value, mearlApiVersion) {
+    if (!Array.isArray(value.bundles) || value.bundles.length > 64)
+        throw new BundleError('BUNDLE_QUOTA', 'Preset package count exceeds 64');
+    let total = 0;
+    for (const bundle of value.bundles) {
+        if (!bundle?.resources || typeof bundle.resources !== 'object' || Array.isArray(bundle.resources))
+            throw new BundleError('BUNDLE_INVALID', 'Expected package resource buffers');
+        const resources = Object.values(bundle.resources);
+        if (resources.length > 64)
+            throw new BundleError('BUNDLE_QUOTA', 'Preset package resource count exceeds 64');
+        for (const bytes of resources) {
+            if (!(bytes instanceof Uint8Array))
+                throw new BundleError('BUNDLE_INVALID', 'Expected package resource buffers');
+            total += bytes.byteLength;
+            if (total > MAX_BROWSER_STORAGE_BYTES)
+                throw new BundleError('BUNDLE_QUOTA', 'Preset packages exceed the storage budget');
+        }
+    }
+    const [graph, bundles] = await Promise.all([
+        verifyPreset(value.snapshot, mearlApiVersion),
+        Promise.all(value.bundles.map(bundle => verifyBundle(bundle, mearlApiVersion))),
+    ]);
+    const { snapshot, preset } = graph;
+    if (bundles.length !== Object.keys(snapshot.bundleRevisions).length || new Set(bundles.map(bundle => bundle.manifest.id)).size !== bundles.length || bundles.some(bundle => {
+        const entry = preset.packages[bundle.manifest.id];
+        return snapshot.bundleRevisions[bundle.manifest.id] !== bundle.revision || entry?.source !== bundle.source || (entry.version && !satisfies(bundle.manifest.version, entry.version));
+    }))
+        throw new BundleError('BUNDLE_INTEGRITY', 'Preset installation requires every exact package');
+    return { snapshot, preset, bundles, browser: await browserPresetSnapshot(snapshot.source, snapshot.manifests, preset, bundles) };
+}

package/dist/requestUi.d.ts

@@ -0,0 +1,59 @@
+import { type PreparedBundle } from './bundle.js';
+export interface BrowserUiText {
+    en: string;
+    zh_CN?: string;
+}
+/** Existing request detail, login and service-toggle positions use host-rendered controls. */
+export interface BrowserRequestUi {
+    schemaVersion: 1;
+    service: string;
+    setting: {
+        key: string;
+        label: BrowserUiText;
+    };
+    apiLink: {
+        url: string;
+        query: Record<string, string>;
+        apiParameter: string;
+        versionParameter: string;
+        title: BrowserUiText;
+    };
+    login: {
+        url: string;
+        title: BrowserUiText;
+        requiredMessage: BrowserUiText;
+        errorIncludes: string[];
+    };
+    save?: {
+        hook: string;
+        setting: string;
+    };
+    details: {
+        hook: string;
+        toggleLabel: BrowserUiText;
+        interfaceLabel: BrowserUiText;
+        maintainerLabel: BrowserUiText;
+        viewTitle: BrowserUiText;
+        notFound: BrowserUiText;
+    };
+}
+export interface BrowserRequestDetail {
+    displayValue: string;
+    jumpUrl: string;
+    maintainerDisplayValue?: string;
+    maintainerTitle?: string;
+}
+export interface SelectedBrowserRequestUi {
+    bundleId: string;
+    revision: string;
+    definition: BrowserRequestUi;
+}
+export declare function validateBrowserUiText(value: unknown): void;
+export declare function browserUiHttpUrl(value: unknown): 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;
+export declare function browserUiText(value: BrowserUiText, locale: string): string;
+export declare function browserRequestUiLink(value: BrowserRequestUi, api: string, version: string): string;
+export declare function browserRequestLoginError(value: BrowserRequestUi, message: string): boolean;
+export declare function validateBrowserRequestDetail(input: unknown): BrowserRequestDetail;

package/dist/requestUi.js

@@ -0,0 +1,102 @@
+import { BundleError, MAX_REQUEST_UI_BYTES, readBundleJson, validateBundleManifest } from './bundle.js';
+import { clonePresetDefaults, isJsonObject } from './manifest.js';
+function invalid(message) { throw new BundleError('BUNDLE_INVALID', message); }
+function fields(value, names) {
+    if (!isJsonObject(value) || Object.keys(value).some(key => !names.includes(key)))
+        invalid('Invalid request UI structure');
+}
+export function validateBrowserUiText(value) {
+    fields(value, ['en', 'zh_CN']);
+    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) {
+    if (typeof value !== 'string' || value.length > 4096)
+        invalid('Invalid request UI URL');
+    let url;
+    try {
+        url = new URL(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)))
+        invalid('Request UI requires credential-free HTTPS or loopback URLs');
+    return url.href;
+}
+export function validateBrowserRequestUi(input) {
+    const value = clonePresetDefaults(input);
+    fields(value, ['schemaVersion', 'service', 'setting', 'apiLink', 'login', 'details', 'save']);
+    if (value.schemaVersion !== 1 || typeof value.service !== 'string' || !/^[a-z][a-z0-9-]{0,79}$/.test(value.service))
+        invalid('Invalid request UI identity');
+    fields(value.setting, ['key', 'label']);
+    if (typeof value.setting.key !== 'string' || !/^[a-z][a-zA-Z0-9_-]{0,72}Enabled$/.test(value.setting.key) || ['agentEnabled', 'sseMonitoringEnabled', 'agentFloatingButtonEnabled'].includes(value.setting.key))
+        invalid('Invalid request UI setting');
+    validateBrowserUiText(value.setting.label);
+    fields(value.apiLink, ['url', 'query', 'apiParameter', 'versionParameter', 'title']);
+    value.apiLink.url = browserUiHttpUrl(value.apiLink.url);
+    if (new URL(value.apiLink.url).search || !isJsonObject(value.apiLink.query) || Object.keys(value.apiLink.query).length > 16 || Object.entries(value.apiLink.query).some(([key, entry]) => !key || key.length > 128 || typeof entry !== 'string' || entry.length > 2048))
+        invalid('Invalid request UI link parameters');
+    const parameters = [value.apiLink.apiParameter, value.apiLink.versionParameter];
+    const query = value.apiLink.query;
+    if (parameters.some(key => typeof key !== 'string' || !key || key.length > 128 || Object.hasOwn(query, key)) || parameters[0] === parameters[1])
+        invalid('Request UI link parameters must be distinct');
+    validateBrowserUiText(value.apiLink.title);
+    fields(value.login, ['url', 'title', 'requiredMessage', 'errorIncludes']);
+    value.login.url = browserUiHttpUrl(value.login.url);
+    validateBrowserUiText(value.login.title);
+    validateBrowserUiText(value.login.requiredMessage);
+    if (!Array.isArray(value.login.errorIncludes) || value.login.errorIncludes.length > 16 || value.login.errorIncludes.some(entry => typeof entry !== 'string' || !entry.trim() || entry.length > 256))
+        invalid('Invalid request UI login errors');
+    fields(value.details, ['hook', 'toggleLabel', 'interfaceLabel', 'maintainerLabel', 'viewTitle', 'notFound']);
+    if (typeof value.details.hook !== 'string' || !/^[a-z][a-zA-Z0-9_.-]{0,127}$/.test(value.details.hook))
+        invalid('Invalid request UI detail hook');
+    for (const name of ['toggleLabel', 'interfaceLabel', 'maintainerLabel', 'viewTitle', 'notFound'])
+        validateBrowserUiText(value.details[name]);
+    if (value.save !== undefined) {
+        fields(value.save, ['hook', 'setting']);
+        if (typeof value.save.hook !== 'string' || !/^[a-z][a-zA-Z0-9_.-]{0,127}$/.test(value.save.hook))
+            invalid('Invalid request save hook');
+        if (typeof value.save.setting !== 'string' || !/^[a-z][a-zA-Z0-9_-]{0,72}Enabled$/.test(value.save.setting) || ['agentEnabled', 'sseMonitoringEnabled', 'agentFloatingButtonEnabled'].includes(value.save.setting))
+            invalid('Invalid request save setting');
+    }
+    if (new TextEncoder().encode(JSON.stringify(value)).byteLength > MAX_REQUEST_UI_BYTES)
+        throw new BundleError('BUNDLE_QUOTA', 'Request UI exceeds 64 KiB');
+    return value;
+}
+/** Contribution validation is pure; factories and UI side effects belong to the host. */
+export function selectBrowserRequestUi(bundles, apiVersion) {
+    let selected;
+    for (const bundle of bundles) {
+        const manifest = validateBundleManifest(bundle.manifest, apiVersion);
+        if (!manifest.contributions?.requestUi)
+            continue;
+        if (selected)
+            invalid('Request UI has multiple providers');
+        const definition = validateBrowserRequestUi(readBundleJson(bundle, manifest.contributions.requestUi));
+        const bindings = manifest.contributions.browserRuntimes?.extension?.bindings ?? {};
+        if ([definition.details.hook, ...(definition.save ? [definition.save.hook] : [])].some(hook => !Object.hasOwn(bindings, hook)))
+            invalid('Request UI hook must belong to its own browser runtime');
+        selected = { bundleId: manifest.id, revision: bundle.revision, definition };
+    }
+    return selected;
+}
+export function browserUiText(value, locale) {
+    return /^zh(?:[-_]CN)?$/i.test(locale) && value.zh_CN ? value.zh_CN : value.en;
+}
+export function browserRequestUiLink(value, api, version) {
+    const entries = [...Object.entries(value.apiLink.query), [value.apiLink.apiParameter, api], [value.apiLink.versionParameter, version]];
+    return value.apiLink.url + '?' + entries.map(([key, entry]) => `${encodeURIComponent(key)}=${encodeURIComponent(entry)}`).join('&');
+}
+export function browserRequestLoginError(value, message) {
+    const lower = message.toLowerCase();
+    return value.login.errorIncludes.some(fragment => lower.includes(fragment.toLowerCase()));
+}
+export function validateBrowserRequestDetail(input) {
+    const value = clonePresetDefaults(input);
+    fields(value, ['displayValue', 'jumpUrl', 'maintainerDisplayValue', 'maintainerTitle']);
+    if (typeof value.displayValue !== 'string' || !value.displayValue || value.displayValue.length > 16384 || ['maintainerDisplayValue', 'maintainerTitle'].some(key => value[key] !== undefined && (typeof value[key] !== 'string' || value[key].length > 16384)))
+        invalid('Invalid request detail value');
+    value.jumpUrl = browserUiHttpUrl(value.jumpUrl);
+    return value;
+}

package/dist/resolve.d.ts

@@ -0,0 +1,5 @@
+import type { JsonObject, ResolvePresetOptions, ResolvedPreset } from './types.js';
+/** Objects merge recursively; arrays, scalars and explicit null replace the previous value. */
+export declare function mergePresetDefaults(base: JsonObject, overrides: JsonObject): JsonObject;
+/** Pure resolution: transport and installation are supplied by the browser or Node host. */
+export declare function resolvePreset(source: string, options: ResolvePresetOptions): Promise<ResolvedPreset>;

package/dist/resolve.js

@@ -0,0 +1,134 @@
+import { satisfies, valid } from 'semver';
+import { clonePresetDefaults, isJsonObject, PresetError, validatePreset } from './manifest.js';
+const kinds = ['packages', 'skills', 'providers'];
+/** Objects merge recursively; arrays, scalars and explicit null replace the previous value. */
+export function mergePresetDefaults(base, overrides) {
+    const result = clonePresetDefaults(base);
+    for (const [key, value] of Object.entries(clonePresetDefaults(overrides))) {
+        result[key] = isJsonObject(value) && isJsonObject(result[key])
+            ? mergePresetDefaults(result[key], value)
+            : value;
+    }
+    return result;
+}
+function sourceUrl(source, parent) {
+    try {
+        const url = parent ? new URL(source, parent) : new URL(source);
+        if (!['https:', 'http:', 'file:'].includes(url.protocol) || url.username || url.password) {
+            throw new Error('unsupported source');
+        }
+        // URL fragments do not identify a different manifest for transport or cycle detection.
+        url.hash = '';
+        return url.href;
+    }
+    catch {
+        throw new PresetError('PRESET_INVALID', 'Expected an absolute HTTP(S)/file source URL without embedded credentials');
+    }
+}
+/** Install sources retain the selected tool's repository, package and ref syntax. */
+function componentSource(kind, source, parent) {
+    if (kind === 'packages')
+        return sourceUrl(source, parent);
+    if (source.length > 8192 || /^[\s-]/.test(source) || /[\0-\x1f\x7f]/.test(source))
+        throw new PresetError('PRESET_INVALID', 'Invalid component install source');
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(source)) {
+        try {
+            if (new URL(source).password)
+                throw new Error('embedded credentials');
+        }
+        catch {
+            throw new PresetError('PRESET_INVALID', 'Invalid component install URL');
+        }
+    }
+    if (/^(?:https?:|file:|\.{1,2}\/|\/)/i.test(source)) {
+        try {
+            const url = new URL(source, parent);
+            if (url.username || url.password)
+                throw new Error('embedded credentials');
+            return url.href;
+        }
+        catch {
+            throw new PresetError('PRESET_INVALID', 'Invalid component install URL');
+        }
+    }
+    return source;
+}
+function validateDependencies(kind, entries) {
+    const active = new Set();
+    const done = new Set();
+    const visit = (id) => {
+        if (done.has(id))
+            return;
+        if (active.has(id))
+            throw new PresetError('PRESET_DEPENDENCY', `${kind}: dependency cycle at ${id}`);
+        const entry = entries[id];
+        if (!entry || entry.enabled === false)
+            throw new PresetError('PRESET_DEPENDENCY', `${kind}: missing or disabled dependency ${id}`);
+        if (!entry.source)
+            throw new PresetError('PRESET_INVALID', `${kind}.${id}: enabled component requires a source`);
+        active.add(id);
+        for (const dependency of entry.dependsOn ?? [])
+            visit(dependency);
+        active.delete(id);
+        done.add(id);
+    };
+    for (const [id, entry] of Object.entries(entries))
+        if (entry.enabled !== false)
+            visit(id);
+}
+/** Pure resolution: transport and installation are supplied by the browser or Node host. */
+export async function resolvePreset(source, options) {
+    if (valid(options.mearlApiVersion) !== options.mearlApiVersion) {
+        throw new PresetError('PRESET_INVALID', 'mearlApiVersion requires an exact semantic version');
+    }
+    const active = new Set();
+    const load = async (url) => {
+        options.signal?.throwIfAborted();
+        if (active.has(url))
+            throw new PresetError('PRESET_CYCLE', `Inheritance cycle at ${url}`);
+        if (active.size >= 32)
+            throw new PresetError('PRESET_INVALID', 'Inheritance exceeds 32 presets');
+        active.add(url);
+        const manifest = validatePreset(await options.load(url));
+        options.signal?.throwIfAborted();
+        if (manifest.requires?.mearlApi && !satisfies(options.mearlApiVersion, manifest.requires.mearlApi)) {
+            throw new PresetError('PRESET_INCOMPATIBLE', `${manifest.id} requires Mearl API ${manifest.requires.mearlApi}`);
+        }
+        let parent;
+        if (manifest.extends) {
+            parent = await load(sourceUrl(manifest.extends.source, url));
+            if (manifest.extends.version && !satisfies(parent.version, manifest.extends.version)) {
+                throw new PresetError('PRESET_INCOMPATIBLE', `${manifest.id} requires parent ${manifest.extends.version}; received ${parent.version}`);
+            }
+        }
+        const result = {
+            id: manifest.id,
+            version: manifest.version,
+            chain: [...(parent?.chain ?? []), { source: url, id: manifest.id, version: manifest.version }],
+            packages: { ...parent?.packages },
+            skills: { ...parent?.skills },
+            providers: { ...parent?.providers },
+            appProfiles: { ...parent?.appProfiles, ...manifest.appProfiles },
+            defaults: mergePresetDefaults(parent?.defaults ?? {}, manifest.defaults ?? {}),
+            permissions: { origins: [...new Set([...(parent?.permissions.origins ?? []), ...(manifest.permissions?.origins ?? [])])] },
+        };
+        for (const kind of kinds) {
+            for (const [id, patch] of Object.entries(manifest[kind] ?? {})) {
+                result[kind][id] = {
+                    ...result[kind][id],
+                    ...patch,
+                    ...(patch.source === undefined ? {} : { source: componentSource(kind, patch.source, url) }),
+                    declaredBy: url,
+                };
+            }
+        }
+        active.delete(url);
+        return result;
+    };
+    const result = await load(sourceUrl(source));
+    // 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]);
+    options.signal?.throwIfAborted();
+    return result;
+}

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export type PresetRuntime = 'browser' | 'node';
+/** A child declaration patches its parent's entry with the same stable ID. */
+export interface PresetComponent {
+    /** Bundle URL for packages; installer-specific source for skills and providers. */
+    source?: string;
+    version?: string;
+    enabled?: boolean;
+    runtimes?: PresetRuntime[];
+    dependsOn?: string[];
+}
+export interface PresetReference {
+    source: string;
+    version?: string;
+}
+export interface PresetManifest {
+    schemaVersion: 1;
+    id: string;
+    version: string;
+    extends?: PresetReference;
+    requires?: {
+        mearlApi?: string;
+    };
+    packages?: Record<string, PresetComponent>;
+    skills?: Record<string, PresetComponent>;
+    providers?: Record<string, PresetComponent>;
+    appProfiles?: Record<string, string>;
+    defaults?: JsonObject;
+    permissions?: {
+        origins?: string[];
+    };
+}
+export type PresetComponentKind = 'packages' | 'skills' | 'providers';
+export interface ResolvedComponent extends PresetComponent {
+    /** Preset URL that most recently declared this entry. */
+    declaredBy: string;
+}
+export interface ResolvedPreset {
+    id: string;
+    version: string;
+    /** Parent-first order; every source and exact preset version is retained. */
+    chain: Array<{
+        source: string;
+        id: string;
+        version: string;
+    }>;
+    packages: Record<string, ResolvedComponent>;
+    skills: Record<string, ResolvedComponent>;
+    providers: Record<string, ResolvedComponent>;
+    appProfiles: Record<string, string>;
+    defaults: JsonObject;
+    /** Required origins only. Actual browser grants belong to the installer. */
+    permissions: {
+        origins: string[];
+    };
+}
+export interface ResolvePresetOptions {
+    mearlApiVersion: string;
+    /** Receives canonical absolute URLs; owns transport, credentials and source trust. */
+    load(source: string): Promise<unknown>;
+    signal?: AbortSignal;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@mearl/preset",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "3.0.0-beta.0",
+  "description": "Browser-compatible preset validation, inheritance and capability resolution for Mearl",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./bundles": {
+      "types": "./dist/bundles.d.ts",
+      "import": "./dist/bundles.js"
+    },
+    "./installation": {
+      "types": "./dist/installation.d.ts",
+      "import": "./dist/installation.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "dependencies": {
+    "semver": "^7.8.5"
+  },
+  "devDependencies": {
+    "@types/semver": "^7.7.1"
+  },
+  "scripts": {
+    "build": "rm -rf dist/ && tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }