@zhin.js/runtime 1.0.2 → 1.0.4

package/lib/config-composer.js

@@ -149,6 +149,14 @@ async function readOwnSchema(node) {
     if (schema.type !== undefined && schema.type !== 'object') {
         throw new TypeError(`${file} root schema type must be object`);
     }
+    // A compositional root (anyOf/oneOf/allOf/$ref without properties) would
+    // validate but pickOwnFields only copies top-level properties, silently
+    // projecting an empty ConfigView. Reject it explicitly instead.
+    if (schema.properties === undefined
+        && (schema.anyOf !== undefined || schema.oneOf !== undefined
+            || schema.allOf !== undefined || schema.$ref !== undefined)) {
+        throw new TypeError(`${file} root schema must declare properties; composition keywords (anyOf/oneOf/allOf/$ref) are not supported`);
+    }
     return Object.freeze({
         type: 'object',
         additionalProperties: false,

package/lib/config-patch-planner.js

@@ -47,31 +47,67 @@ function applyPatch(document, patch) {
 function setValue(document, path, value) {
     let target = document;
     for (const [index, segment] of path.slice(0, -1).entries()) {
-        const existing = target[segment];
+        const existing = readChild(target, segment, path.slice(0, index + 1));
         if (existing === undefined) {
+            // Missing intermediates are always created as records; arrays only ever
+            // come from the existing document (numeric segments index into them).
             const created = {};
             target[segment] = created;
             target = created;
         }
         else {
-            target = requireRecord(existing, path.slice(0, index + 1));
+            target = requireContainer(existing, path.slice(0, index + 1));
         }
     }
-    target[lastSegment(path)] = value;
+    writeChild(target, lastSegment(path), value, path);
 }
 function removeValue(document, path) {
     let target = document;
     for (const [index, segment] of path.slice(0, -1).entries()) {
-        const existing = target[segment];
+        const existing = readChild(target, segment, path.slice(0, index + 1));
         if (existing === undefined)
             return;
-        target = requireRecord(existing, path.slice(0, index + 1));
+        target = requireContainer(existing, path.slice(0, index + 1));
     }
-    delete target[lastSegment(path)];
+    const segment = lastSegment(path);
+    if (Array.isArray(target)) {
+        target.splice(arrayIndex(segment, target, path), 1);
+        return;
+    }
+    delete target[segment];
 }
 function cloneDocument(value) {
     return requireRecord(structuredClone(value), []);
 }
+function readChild(container, segment, path) {
+    if (Array.isArray(container))
+        return container[arrayIndex(segment, container, path)];
+    return container[segment];
+}
+function writeChild(container, segment, value, path) {
+    if (Array.isArray(container)) {
+        container[arrayIndex(segment, container, path)] = value;
+        return;
+    }
+    container[segment] = value;
+}
+/** Resolves a numeric path segment against an array, rejecting non-numeric segments and out-of-bounds indexes. */
+function arrayIndex(segment, container, path) {
+    if (!/^(0|[1-9]\d*)$/.test(segment)) {
+        throw new ConfigPatchPathError(`Config path ${pointer(path)} requires an array index, got "${segment}"`);
+    }
+    const index = Number(segment);
+    if (index >= container.length) {
+        throw new ConfigPatchPathError(`Config path ${pointer(path)} is out of bounds (array length ${container.length})`);
+    }
+    return index;
+}
+function requireContainer(value, path) {
+    if (!value || typeof value !== 'object') {
+        throw new ConfigPatchPathError(`Config path ${pointer(path)} is not an object`);
+    }
+    return value;
+}
 function requireRecord(value, path) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
         throw new ConfigPatchPathError(`Config path ${pointer(path)} is not an object`);

package/lib/feature-projector.d.ts

@@ -1,15 +1,15 @@
-import { type Dispose, type GenerationHandoff, type SnapshotState } from '@zhin.js/plugin-runtime';
+import { type Dispose, type FeatureId, type GenerationHandoff, type SnapshotState } from '@zhin.js/plugin-runtime';
 import type { FeatureProvider } from '@zhin.js/feature-kit';
 export type ProjectionState = Omit<SnapshotState, 'projections'>;
 export interface ProjectedFeatures {
     readonly state: SnapshotState;
-    readonly disposers: readonly Dispose[];
+    readonly disposers: ReadonlyMap<FeatureId, Dispose>;
     readonly handoff?: GenerationHandoff;
 }
-/** Builds every Feature projection against one coherent candidate snapshot. */
+/** Builds selected Feature projections against one coherent candidate snapshot. */
 export declare class FeatureProjector {
     private readonly providers;
     constructor(providers: Iterable<FeatureProvider>);
-    project(generation: number, base: ProjectionState): Promise<ProjectedFeatures>;
+    project(generation: number, base: ProjectionState, retained?: ReadonlyMap<FeatureId, unknown>): Promise<ProjectedFeatures>;
 }
 export declare function composeGenerationHandoffs(...handoffs: readonly (GenerationHandoff | undefined)[]): GenerationHandoff | undefined;

package/lib/feature-projector.js

@@ -1,18 +1,19 @@
 import { DisposeStack, GenerationHandoffStack, createSnapshotView, } from '@zhin.js/plugin-runtime';
-/** Builds every Feature projection against one coherent candidate snapshot. */
+/** Builds selected Feature projections against one coherent candidate snapshot. */
 export class FeatureProjector {
     providers;
     constructor(providers) {
         this.providers = providers;
     }
-    async project(generation, base) {
-        const projections = new Map();
-        const disposers = [];
+    async project(generation, base, retained = new Map()) {
+        // Slot HMR seeds this map with the committed projections. Only providers
+        // passed to this projector replace their entry; every other Feature keeps
+        // its live instance and therefore keeps its external resources running.
+        const projections = new Map(retained);
+        const disposers = new Map();
         const handoffs = new GenerationHandoffStack();
         const state = { ...base, projections };
         try {
-            // A projection may capture its snapshot. Rebuilding every projection
-            // prevents unchanged Features from retaining an older generation.
             for (const provider of this.providers) {
                 const slots = [...base.capabilities.values()].filter((slot) => slot.feature === provider.id);
                 const projection = await provider.runtime.project(slots, {
@@ -20,18 +21,18 @@ export class FeatureProjector {
                 });
                 projections.set(provider.id, projection.value);
                 if (projection.dispose)
-                    disposers.push(projection.dispose);
+                    disposers.set(provider.id, projection.dispose);
                 if (projection.handoff)
                     handoffs.add(projection.handoff);
             }
             return {
                 state,
-                disposers: Object.freeze(disposers),
+                disposers,
                 handoff: handoffs.seal(),
             };
         }
         catch (error) {
-            await rollback(disposers, error);
+            await rollback(disposers.values(), error);
             throw error;
         }
     }

package/lib/generation-assets.d.ts

@@ -1,9 +1,9 @@
-import { type Dispose, type PluginId } from '@zhin.js/plugin-runtime';
+import { type Dispose, type FeatureId, type PluginId } from '@zhin.js/plugin-runtime';
 export declare class GenerationAssets {
     #private;
     private constructor();
-    static create(scopeDisposers: Iterable<readonly [PluginId, Dispose]>, projectionDisposers: Iterable<Dispose>): GenerationAssets;
-    fork(projectionDisposers: Iterable<Dispose>): GenerationAssets;
-    replaceScopes(scopeOrder: readonly PluginId[], replacements: ReadonlyMap<PluginId, Dispose>, projectionDisposers: Iterable<Dispose>): GenerationAssets;
+    static create(scopeDisposers: Iterable<readonly [PluginId, Dispose]>, projectionDisposers: ReadonlyMap<FeatureId, Dispose>): GenerationAssets;
+    replaceProjections(features: Iterable<FeatureId>, projectionDisposers: ReadonlyMap<FeatureId, Dispose>): GenerationAssets;
+    replaceScopes(scopeOrder: readonly PluginId[], replacements: ReadonlyMap<PluginId, Dispose>, projectionDisposers: ReadonlyMap<FeatureId, Dispose>): GenerationAssets;
     dispose(): Promise<void>;
 }

package/lib/generation-assets.js

@@ -1,9 +1,13 @@
 import { DisposeStack, SharedLifetime, } from '@zhin.js/plugin-runtime';
 export class GenerationAssets {
     #scopeLifetimes;
+    // Projection ownership is per Feature, so one command transaction can
+    // retire CommandIndex without releasing AdapterIndex and its endpoints.
+    #projectionLifetimes;
     #disposers = new DisposeStack();
-    constructor(scopeOrder, scopeLifetimes, projectionDisposers) {
+    constructor(scopeOrder, scopeLifetimes, projectionLifetimes) {
         this.#scopeLifetimes = scopeLifetimes;
+        this.#projectionLifetimes = projectionLifetimes;
         assertScopeOrder(scopeOrder, scopeLifetimes);
         // Scope order is parent-first. DisposeStack unwinds projections first,
         // then Plugin leases children-first, so no child observes a closed parent.
@@ -14,8 +18,10 @@ export class GenerationAssets {
             const lease = lifetime.acquire();
             this.#disposers.add(() => lease.release());
         }
-        for (const dispose of projectionDisposers)
-            this.#disposers.add(dispose);
+        for (const lifetime of projectionLifetimes.values()) {
+            const lease = lifetime.acquire();
+            this.#disposers.add(() => lease.release());
+        }
         this.#disposers.seal();
     }
     static create(scopeDisposers, projectionDisposers) {
@@ -25,10 +31,22 @@ export class GenerationAssets {
                 throw new Error(`Duplicate Plugin Scope: ${owner}`);
             lifetimes.set(owner, new SharedLifetime(dispose));
         }
-        return new GenerationAssets([...lifetimes.keys()], lifetimes, projectionDisposers);
+        const projectionLifetimes = new Map([...projectionDisposers].map(([feature, dispose]) => [
+            feature,
+            new SharedLifetime(dispose),
+        ]));
+        return new GenerationAssets([...lifetimes.keys()], lifetimes, projectionLifetimes);
     }
-    fork(projectionDisposers) {
-        return new GenerationAssets([...this.#scopeLifetimes.keys()], this.#scopeLifetimes, projectionDisposers);
+    replaceProjections(features, projectionDisposers) {
+        const lifetimes = new Map(this.#projectionLifetimes);
+        for (const feature of features) {
+            const dispose = projectionDisposers.get(feature);
+            if (dispose)
+                lifetimes.set(feature, new SharedLifetime(dispose));
+            else
+                lifetimes.delete(feature);
+        }
+        return new GenerationAssets([...this.#scopeLifetimes.keys()], this.#scopeLifetimes, lifetimes);
     }
     replaceScopes(scopeOrder, replacements, projectionDisposers) {
         const owners = new Set(scopeOrder);
@@ -46,7 +64,11 @@ export class GenerationAssets {
                 throw new Error(`Cannot retain unknown Plugin Scope: ${owner}`);
             lifetimes.set(owner, lifetime);
         }
-        return new GenerationAssets(scopeOrder, lifetimes, projectionDisposers);
+        const projectionLifetimes = new Map([...projectionDisposers].map(([feature, dispose]) => [
+            feature,
+            new SharedLifetime(dispose),
+        ]));
+        return new GenerationAssets(scopeOrder, lifetimes, projectionLifetimes);
     }
     dispose() {
         return this.#disposers.dispose();

package/lib/hmr-coordinator.d.ts

@@ -12,6 +12,8 @@ export interface HmrCoordinatorOptions {
     onRestartRequired(plan: ProcessInvalidationPlan): void | Promise<void>;
     onError(error: unknown): void | Promise<void>;
     onPlan?(plan: InvalidationPlan): void | Promise<void>;
+    /** Fires once after a generation transaction commits successfully. */
+    onReload?(plan: GenerationInvalidationPlan, durationMs: number): void | Promise<void>;
 }
 export declare class HmrCoordinator {
     #private;

package/lib/hmr-coordinator.js

@@ -71,12 +71,17 @@ export class HmrCoordinator {
                 }
                 if (plan.kind === 'none')
                     continue;
+                const startedAt = performance.now();
                 for (const source of plan.changed) {
                     await this.options.modules.invalidate?.(source);
                 }
                 const restart = await this.options.runtime.reload(plan);
                 if (restart)
                     await this.options.onRestartRequired(restart);
+                else {
+                    const durationMs = Number((performance.now() - startedAt).toFixed(1));
+                    await this.options.onReload?.(plan, durationMs);
+                }
             }
             this.#resolveWaiters();
         }

package/lib/index.d.ts

@@ -12,6 +12,7 @@ export * from './module-runtime.js';
 export * from './native-development-runtime.js';
 export * from './node-discovery-host.js';
 export * from './package-resolver.js';
+export * from './platform-features.js';
 export * from './primary-config.js';
 export * from './project-graph.js';
 export * from './process-restart.js';

package/lib/index.js

@@ -12,6 +12,7 @@ export * from './module-runtime.js';
 export * from './native-development-runtime.js';
 export * from './node-discovery-host.js';
 export * from './package-resolver.js';
+export * from './platform-features.js';
 export * from './primary-config.js';
 export * from './project-graph.js';
 export * from './process-restart.js';

package/lib/manifest.d.ts

@@ -12,6 +12,12 @@ export interface ZhinPluginManifest {
     readonly entry: string;
     readonly engine?: string;
     readonly runtime?: 'trusted' | 'isolated';
+    /**
+     * When true (default), Root plugins receive official Stable Features
+     * (`@zhin.js/adapter|command|component`) from the platform/CLI even if they
+     * are omitted from `features` / project dependencies. Set false to opt out.
+     */
+    readonly platformFeatures?: boolean;
     readonly features: readonly PackageReference[];
     readonly plugins: readonly ChildPluginReference[];
 }

package/lib/manifest.js

@@ -68,12 +68,14 @@ function parseZhinManifest(value, source, issues) {
     if (runtime !== undefined && runtime !== 'trusted' && runtime !== 'isolated') {
         issues.push(`${source}.runtime must be "trusted" or "isolated"`);
     }
+    const platformFeatures = optionalBoolean(record.platformFeatures, `${source}.platformFeatures`, issues);
     return Object.freeze({
         protocol: 1,
         type,
         entry,
         engine,
         runtime: runtime,
+        platformFeatures,
         features: parseReferences(record.features, `${source}.features`, issues, false),
         plugins: parseReferences(record.plugins, `${source}.plugins`, issues, true),
     });
@@ -94,10 +96,16 @@ function parseReferences(value, source, issues, child) {
             : undefined;
         if (!packageName || (child && !instanceKey))
             return [];
-        if (!isPackageName(packageName)) {
+        // 支持两种来源：npm 包名（package 依赖）或 ./ 相对路径（monorepo 本地插件目录）
+        const isLocalPath = packageName.startsWith('./');
+        if (!isLocalPath && !isPackageName(packageName)) {
             issues.push(`${itemSource}.package is not a valid package name`);
             return [];
         }
+        if (isLocalPath && packageName.split('/').includes('..')) {
+            issues.push(`${itemSource}.package must not escape the package root`);
+            return [];
+        }
         if (instanceKey && !/^[a-z0-9][a-z0-9-]*$/.test(instanceKey)) {
             issues.push(`${itemSource}.instanceKey is invalid`);
             return [];

package/lib/native-development-runtime.js

@@ -56,7 +56,12 @@ export class NativeDevelopmentModuleRuntime {
             return extname(normalized) !== '.md';
         if (root === 'tools' || root === 'mcp')
             return parts.length !== capability + 2;
-        return false;
+        if (isCapabilityEntry(parts.slice(capability + 1)))
+            return false;
+        // Support files inside capability directories (e.g. commands/_utils.ts)
+        // are not discovery entries: reloading the entry URL only bumps that
+        // entry's zhin-generation, so the importer closure keeps the old code.
+        return ['.js', '.json', '.ts'].includes(extname(normalized));
     }
     watch(listener) {
         this.#assertOpen();
@@ -124,7 +129,7 @@ class PortableSourceWatcher {
                 if (!name)
                     return;
                 const source = resolve(this.root, name.toString());
-                if (isWatchedSource(source))
+                if (isWatchedSource(source) && !isIgnoredSource(this.root, source))
                     this.listener(source);
             });
             this.#watcher.on('error', () => this.#startPolling());
@@ -181,6 +186,25 @@ function isWatchedSource(source) {
     const name = source.slice(source.lastIndexOf(sep) + 1);
     return watchedExtensions.has(extname(source)) || name.startsWith('.env');
 }
+/** Mirrors sourceSnapshot: any path segment matching an ignored directory opts out. */
+function isIgnoredSource(root, source) {
+    return relative(root, source).split(sep).some((segment) => ignoredDirectories.has(segment));
+}
+/**
+ * Discovery entries follow the typeScriptModules convention
+ * (feature-kit typescript-convention.ts): lowercase segment directories and
+ * lowercase .ts/.tsx module names only.
+ */
+function isCapabilityEntry(segments) {
+    const file = segments[segments.length - 1] ?? '';
+    return segments.slice(0, -1).every(isCapabilitySegment) && isCapabilityModule(file);
+}
+function isCapabilitySegment(value) {
+    return /^[a-z0-9][a-z0-9-]*$/u.test(value);
+}
+function isCapabilityModule(value) {
+    return /^[a-z0-9][a-z0-9-]*\.tsx?$/u.test(value);
+}
 function isExecutableSource(source) {
     return ['.cjs', '.js', '.mjs', '.ts', '.tsx'].includes(extname(source));
 }

package/lib/package-resolver.d.ts

@@ -3,11 +3,13 @@ export interface ResolvedPackage {
     readonly name: string;
     readonly root: string;
     readonly packageJson: PackageJson;
-    readonly source: 'workspace' | 'node_modules';
+    readonly source: 'workspace' | 'node_modules' | 'local';
 }
 export interface PackageResolver {
     root(root: string): Promise<ResolvedPackage>;
     resolve(request: string, from: ResolvedPackage): Promise<ResolvedPackage>;
+    /** Load a package from an absolute package root (skips dependency declaration checks). */
+    loadPackage?(packageRoot: string): Promise<ResolvedPackage>;
     workspacePackages(): readonly ResolvedPackage[];
 }
 export declare class PackageResolutionError extends Error {
@@ -18,6 +20,7 @@ export declare class NodePackageResolver implements PackageResolver {
     #private;
     static create(projectRoot: string): Promise<NodePackageResolver>;
     root(root: string): Promise<ResolvedPackage>;
+    loadPackage(packageRoot: string): Promise<ResolvedPackage>;
     workspacePackages(): readonly ResolvedPackage[];
     resolve(request: string, from: ResolvedPackage): Promise<ResolvedPackage>;
 }

package/lib/package-resolver.js

@@ -1,5 +1,5 @@
 import { access, readFile, readdir, realpath } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, extname, join, relative, resolve } from 'node:path';
 import { parsePackageJson } from './manifest.js';
 export class PackageResolutionError extends Error {
     request;
@@ -23,9 +23,8 @@ export class NodePackageResolver {
                 if (await exists(join(packageRoot, 'pnpm-workspace.yaml'))) {
                     throw new PackageResolutionError(`Nested workspace is not allowed: ${packageRoot}`);
                 }
-                if (directory === 'plugins' && await exists(join(packageRoot, 'plugins'))) {
-                    throw new PackageResolutionError(`Nested local Plugin directory is not allowed: ${join(packageRoot, 'plugins')}`);
-                }
+                // 注意：plugins/<x>/plugins/ 嵌套目录不再报错——顶层扫描只注册一层
+                // workspace 包；更深的本地插件经 manifest 的 './' 相对路径显式引用。
                 if (!await exists(join(packageRoot, 'package.json')))
                     continue;
                 const pkg = await resolver.#readPackage(packageRoot, 'workspace');
@@ -40,21 +39,31 @@ export class NodePackageResolver {
     async root(root) {
         return this.#readPackage(root, 'workspace');
     }
+    async loadPackage(packageRoot) {
+        return this.#readPackage(packageRoot, 'node_modules');
+    }
     workspacePackages() {
         return [...this.#workspaceByName.values()];
     }
     async resolve(request, from) {
+        // 解析管线（按序短路，任一步命中即返回）：
+        //
+        // 1. 本地路径（'./' 开头）：monorepo 本地插件目录，相对声明包根解析。
+        //    目录即声明——跳过依赖声明检查，也不入 node_modules。
+        if (request.startsWith('./'))
+            return this.#resolveLocal(request, from);
+        // 2. 声明检查（仅包名引用），按声明位置分级：
+        //    - dependencies / optionalDependencies：硬要求，引用必须能在此声明；
+        //    - peerDependencies：宽松声明——允许未安装，解析失败由引用方 optional 容错；
+        //    - 三者皆无：拒绝（zhin manifest 引用必须可追溯到包依赖声明）。
         const specification = declaredDependency(request, from.packageJson);
+        // 3. workspace byName：packages/* + plugins/* 顶层扫描结果优先命中。
+        //    'workspace:*' 未命中时继续走 node_modules——examples 等在扫描面之外，
+        //    但 pnpm 仍会把 workspace:* 链接进 node_modules。
         const workspace = this.#workspaceByName.get(request);
-        if (specification.startsWith('workspace:')) {
-            if (workspace)
-                return workspace;
-            // Examples live outside the monorepo packages/plugins scan roots; pnpm still
-            // links workspace:* into node_modules, so fall through before failing.
-        }
-        else if (workspace) {
+        if (workspace)
             return workspace;
-        }
+        // 4. node_modules 上溯：从声明包根逐级向上查找。
         let current = from.root;
         while (true) {
             const packageRoot = join(current, 'node_modules', ...request.split('/'));
@@ -70,6 +79,13 @@ export class NodePackageResolver {
             ? `Workspace dependency ${request} declared by ${from.name} is missing`
             : `Cannot resolve ${request} from ${from.name}`, request);
     }
+    async #resolveLocal(request, from) {
+        const packageRoot = join(from.root, request);
+        if (await exists(join(packageRoot, 'package.json'))) {
+            return this.#readPackage(packageRoot, 'local');
+        }
+        throw new PackageResolutionError(`Cannot resolve ${request} from ${from.name}`, request);
+    }
     async #readPackage(packageRoot, source) {
         const normalized = await realpath(resolve(packageRoot));
         const cached = this.#cache.get(normalized);
@@ -77,7 +93,17 @@ export class NodePackageResolver {
             return cached;
         const file = join(normalized, 'package.json');
         const content = await readFile(file, 'utf8');
-        const packageJson = parsePackageJson(JSON.parse(content), file);
+        const parsedPackageJson = parsePackageJson(JSON.parse(content), file);
+        const entry = await resolveRuntimeEntry(normalized, parsedPackageJson.zhin.entry, source);
+        const packageJson = entry === parsedPackageJson.zhin.entry
+            ? parsedPackageJson
+            : Object.freeze({
+                ...parsedPackageJson,
+                zhin: Object.freeze({
+                    ...parsedPackageJson.zhin,
+                    entry,
+                }),
+            });
         const result = Object.freeze({
             name: packageJson.name,
             root: normalized,
@@ -88,9 +114,31 @@ export class NodePackageResolver {
         return result;
     }
 }
+async function resolveRuntimeEntry(packageRoot, declaredEntry, source) {
+    const declared = resolve(packageRoot, declaredEntry);
+    const extension = extname(declared);
+    const base = declared.slice(0, -extension.length);
+    const sourceCandidates = extension === '.js'
+        ? [`${base}.ts`, `${base}.tsx`]
+        : [declared];
+    const javascriptCandidates = extension === '.ts' || extension === '.tsx'
+        ? [`${base}.js`, join(packageRoot, 'lib', `${base.slice(packageRoot.length + 1)}.js`)]
+        : [declared];
+    const candidates = source === 'node_modules'
+        ? [...javascriptCandidates, ...sourceCandidates]
+        : [...sourceCandidates, ...javascriptCandidates];
+    for (const candidate of new Set(candidates)) {
+        if (await exists(candidate))
+            return `./${relative(packageRoot, candidate).replaceAll('\\', '/')}`;
+    }
+    return declaredEntry;
+}
 function declaredDependency(request, pkg) {
     const specification = (pkg.dependencies?.[request]
-        ?? pkg.optionalDependencies?.[request]);
+        ?? pkg.optionalDependencies?.[request]
+        // peerDependencies 是宽松声明：允许未安装。未安装时 resolve 抛
+        // PackageResolutionError，由引用方的 optional 标记统一容错。
+        ?? pkg.peerDependencies?.[request]);
     if (!specification) {
         throw new PackageResolutionError(`${pkg.name} references ${request} in zhin manifest but does not declare it as a package dependency`, request);
     }

package/lib/platform-features.d.ts

@@ -0,0 +1,25 @@
+import type { ChildPluginReference, PackageReference } from './manifest.js';
+/**
+ * Package whose `zhin.features` define the Stable Feature composition
+ * (adapter / command / component / middleware).
+ *
+ * Root inherits these when it depends on `@zhin.js/core` directly, or on the
+ * `zhin.js` facade (which depends on `@zhin.js/core`).
+ */
+export declare const PLATFORM_FEATURE_CARRIER = "@zhin.js/core";
+/**
+ * Install facade that may declare default child plugins and re-exports core
+ * authoring surfaces.
+ */
+export declare const PLATFORM_FEATURE_FACADE = "zhin.js";
+/**
+ * Merge user-declared features with inherited platform features.
+ * User references for the same package win (pin / override).
+ */
+export declare function mergeFeatureReferences(declared: readonly PackageReference[], inherited: readonly PackageReference[]): readonly PackageReference[];
+/**
+ * Merge user-declared child plugins with facade defaults.
+ * User references for the same instanceKey win (pin / override).
+ */
+export declare function mergeChildPluginReferences(declared: readonly ChildPluginReference[], inherited: readonly ChildPluginReference[]): readonly ChildPluginReference[];
+export declare function declaredPackageDependency(dependencies: Readonly<Record<string, string>> | undefined, optionalDependencies: Readonly<Record<string, string>> | undefined, name: string): string | undefined;

package/lib/platform-features.js

@@ -0,0 +1,38 @@
+/**
+ * Package whose `zhin.features` define the Stable Feature composition
+ * (adapter / command / component / middleware).
+ *
+ * Root inherits these when it depends on `@zhin.js/core` directly, or on the
+ * `zhin.js` facade (which depends on `@zhin.js/core`).
+ */
+export const PLATFORM_FEATURE_CARRIER = '@zhin.js/core';
+/**
+ * Install facade that may declare default child plugins and re-exports core
+ * authoring surfaces.
+ */
+export const PLATFORM_FEATURE_FACADE = 'zhin.js';
+/**
+ * Merge user-declared features with inherited platform features.
+ * User references for the same package win (pin / override).
+ */
+export function mergeFeatureReferences(declared, inherited) {
+    const seen = new Set(declared.map((item) => item.package));
+    const extras = inherited.filter((item) => !seen.has(item.package));
+    if (extras.length === 0)
+        return declared;
+    return Object.freeze([...declared, ...extras]);
+}
+/**
+ * Merge user-declared child plugins with facade defaults.
+ * User references for the same instanceKey win (pin / override).
+ */
+export function mergeChildPluginReferences(declared, inherited) {
+    const seen = new Set(declared.map((item) => item.instanceKey));
+    const extras = inherited.filter((item) => !seen.has(item.instanceKey));
+    if (extras.length === 0)
+        return declared;
+    return Object.freeze([...declared, ...extras]);
+}
+export function declaredPackageDependency(dependencies, optionalDependencies, name) {
+    return dependencies?.[name] ?? optionalDependencies?.[name];
+}

package/lib/plugin-scope-assembler.d.ts

@@ -1,4 +1,4 @@
-import { DisposeStack, Scope, type Dispose, type GenerationHandoff, type GenerationHandoffRegistry, type PluginId, type PluginNodeSnapshot, type TokenId } from '@zhin.js/plugin-runtime';
+import { DisposeStack, Scope, type Dispose, type FeatureId, type GenerationHandoff, type GenerationHandoffRegistry, type PluginId, type PluginNodeSnapshot, type SetupCapabilityRegistration, type TokenId } from '@zhin.js/plugin-runtime';
 import { type RuntimeEnvironment } from './environment.js';
 import { type EnvironmentLayers } from './environment-store.js';
 import type { ModuleRuntime } from './module-runtime.js';
@@ -35,8 +35,10 @@ export declare class PluginScopeAssembler {
     readonly resources: Map<PluginId, ReadonlyMap<TokenId, unknown>>;
     constructor(modules: ModuleRuntime, configResolver: PluginConfigResolver, environment: RuntimeEnvironment, primaryConfigDocument: RuntimeConfigDocument, installResources?: RootResourceInstaller | undefined, environmentLayers?: EnvironmentLayers, seed?: PluginAssemblySeed, isolation?: IsolatedPluginRuntimePort | undefined);
     removeSubtrees(roots: readonly PluginId[]): void;
+    installSetupFeatureAliases(aliases: ReadonlyMap<string, FeatureId>): void;
     setupTree(node: PluginGraphNode): Promise<void>;
     synchronizeTree(node: PluginGraphNode): void;
     createdScopeDisposers(): readonly (readonly [PluginId, Dispose])[];
     generationHandoff(): GenerationHandoff | undefined;
+    setupCapabilities(): readonly Readonly<SetupCapabilityRegistration>[];
 }