@nasti-toolchain/nasti 2.3.1 → 2.4.0

package/dist/index.d.cts

@@ -105,6 +105,11 @@ interface EnvironmentOptions {
      * Electron renderer 会把 `electron.renderer` 映射到这里。
      */
     html?: string;
+    /**
+     * 是否参与生产构建。默认 true；设为 false 可跳过默认 client，构建纯多环境应用。
+     * 仅影响 `nasti build`，不影响 dev server 中环境实例的可见性。
+     */
+    buildEnabled?: boolean;
     /**
      * 外部环境编译驱动标识。声明后由插件的 `createEnvironmentDriver` 提供实际实现，
      * 可用于接入 Rspeedy 等不基于 Rolldown 的构建系统。
@@ -118,6 +123,8 @@ interface EnvironmentOptions {
 /** 解析后的环境配置 */
 interface ResolvedEnvironmentOptions {
     consumer: 'client' | 'server';
+    /** 是否参与生产构建 */
+    buildEnabled: boolean;
     /** 环境构建入口（绝对路径）；client 未显式配置时为空并从 HTML 提取 */
     entry: string[];
     /** HTML 入口绝对路径（仅 client consumer 有值） */
@@ -302,7 +309,7 @@ interface NastiPlugin {
      * 所有环境构建完成后的 app 级收尾钩子，用于跨环境聚合产物。
      * Vue Lynx 原生后端可在这里组合 background/main-thread bundle。
      */
-    afterBuildApp?: (results: Record<string, EnvironmentBuildResult>, api: PluginApi) => void | Promise<void>;
+    afterBuildApp?: (results: Record<string, EnvironmentBuildResult>, api: PluginApi, context: BuildAppContext) => void | Promise<void>;
     configureServer?: (server: DevServer) => void | (() => void) | Promise<void | (() => void)>;
     transformIndexHtml?: (html: string) => string | HtmlTagDescriptor[] | {
         html: string;
@@ -337,14 +344,37 @@ interface EnvironmentBuildOutput {
     code?: string;
     source?: Uint8Array | string;
 }
-/** 外部环境驱动返回的标准构建结果。 */
-interface EnvironmentBuildResult {
-    output: EnvironmentBuildOutput[];
+/** 单个环境附加到标准构建结果上的结构化元数据。 */
+interface EnvironmentBuildMetadata {
     entries?: Record<string, string>;
     publicPath?: string;
     manifest?: unknown;
     stats?: unknown;
 }
+/** 外部环境驱动或原生 Rolldown 环境返回的标准构建结果。 */
+interface EnvironmentBuildResult extends EnvironmentBuildMetadata {
+    output: EnvironmentBuildOutput[];
+}
+/** app 级 finalizer 写出的聚合产物。 */
+interface AppBuildOutput extends EnvironmentBuildOutput {
+    type: 'asset';
+    source: Uint8Array | string;
+}
+/**
+ * 所有环境完成后提供给 `afterBuildApp` 的只读查询与产物写出接口。
+ * Lynx 等多运行时工具链可用它聚合 background/main-thread 结果，而无需读取磁盘目录。
+ */
+interface BuildAppContext {
+    readonly config: ResolvedConfig;
+    readonly results: Readonly<Record<string, EnvironmentBuildResult>>;
+    readonly output: readonly AppBuildOutput[];
+    getResult: (environmentName: string) => EnvironmentBuildResult | undefined;
+    getArtifact: (environmentName: string, fileName: string) => EnvironmentBuildOutput | undefined;
+    getEntry: (environmentName: string, entryName: string) => EnvironmentBuildOutput | undefined;
+    getManifest: <T = unknown>(environmentName: string) => T | undefined;
+    /** 将聚合产物安全地写入 top-level `build.outDir`，并纳入 BuildResult.appOutput。 */
+    emitFile: (file: AppBuildOutput) => string;
+}
 /** 外部环境驱动返回的开发服务信息。 */
 interface EnvironmentServeResult {
     localUrls?: string[];
@@ -380,6 +410,8 @@ interface EnvironmentInstance {
     hot: HotChannel;
     /** 声明 driver 后，由插件提供的外部环境编译驱动 */
     driver?: EnvironmentDriver;
+    /** 由生产插件登记 entries / manifest / stats，构建完成后合并进环境结果。 */
+    setBuildMetadata: (metadata: EnvironmentBuildMetadata) => void;
 }
 /**
  * renderChunk / augmentChunkHash 的 `this`：Rolldown 真实插件上下文的最小可用面。
@@ -389,6 +421,8 @@ interface EnvironmentInstance {
 interface RenderChunkContext {
     emitFile: (file: EmittedFile) => string;
     getFileName: (referenceId: string) => string;
+    /** 当前生产钩子所属环境；BG/MT 同为 client consumer 时也可准确区分。 */
+    environment: EnvironmentInstance;
 }
 interface ResolveIdOptions {
     isEntry?: boolean;
@@ -436,6 +470,8 @@ interface ModuleNode {
     acceptedHmrDeps: Set<ModuleNode>;
     transformResult: TransformResult | null;
     lastHMRTimestamp: number;
+    /** 每次失效递增，防止较慢的旧转换覆盖较新的缓存。 */
+    invalidationVersion: number;
     isSelfAccepting: boolean;
     /** Environment API：节点所属环境名（per-env 模块图，默认 'client'） */
     environment?: string;
@@ -496,7 +532,12 @@ interface ModuleGraph$1 {
     getModuleById: (id: string) => ModuleNode | undefined;
     getModulesByFile: (file: string) => Set<ModuleNode> | undefined;
     ensureEntryFromUrl: (url: string) => Promise<ModuleNode>;
-    invalidateModule: (mod: ModuleNode) => void;
+    invalidateModule: (mod: ModuleNode, timestamp?: number) => void;
+    invalidateModuleAndImporters: (mod: ModuleNode, timestamp?: number) => void;
+    getHmrBoundaries: (mod: ModuleNode) => Array<{
+        boundary: ModuleNode;
+        acceptedVia: ModuleNode;
+    }>;
     invalidateAll: () => void;
 }
 interface WebSocketServer {
@@ -630,8 +671,18 @@ declare class ModuleGraph {
     setModuleId(mod: ModuleNode, id: string): void;
     /** 更新模块依赖关系 */
     updateModuleImports(mod: ModuleNode, importedIds: Set<string>): void;
+    /**
+     * 用一次转换得到的信息原子更新 import 与 HMR accept 关系。
+     * 依赖节点会在真正被浏览器请求前预先创建，这样入口模块先转换时也能建立完整图。
+     */
+    updateModuleInfo(mod: ModuleNode, importedUrls: Set<string>, acceptedUrls: Set<string>, isSelfAccepting: boolean, expectedInvalidationVersion?: number): Promise<Set<ModuleNode> | null>;
     /** 使模块的转换缓存失效 */
-    invalidateModule(mod: ModuleNode): void;
+    invalidateModule(mod: ModuleNode, timestamp?: number): void;
+    /**
+     * 仅失效到 HMR 边界：显式接受依赖的模块本身不会重执行；自接受模块需要失效，
+     * 但不再继续影响其 importer。这样既能传播依赖时间戳，也不会隐式重复副作用。
+     */
+    invalidateModuleAndImporters(mod: ModuleNode, timestamp?: number, seen?: Set<ModuleNode>): void;
     /** 使所有模块缓存失效 */
     invalidateAll(): void;
     /** 获取 HMR 传播边界 - 从变更模块向上遍历找到接受更新的边界 */
@@ -665,11 +716,14 @@ declare class NastiEnvironment implements EnvironmentInstance {
     moduleGraph: ModuleGraph;
     private candidatePlugins;
     private pluginApi;
+    private buildMetadata;
     private initialized;
     constructor(name: string, config: ResolvedConfig, init?: NastiEnvironmentInit);
     /** 过滤插件并建 per-env PluginContainer */
     init(): Promise<void>;
     getDriverContext(): EnvironmentDriverContext;
+    setBuildMetadata(metadata: EnvironmentBuildMetadata): void;
+    getBuildMetadata(): EnvironmentBuildMetadata;
     close(): Promise<void>;
 }
 /** 按 applyToEnvironment 过滤环境插件（未声明 = 应用于所有环境） */
@@ -680,8 +734,10 @@ interface BuildResult {
     output: EnvironmentBuildOutput[];
     /** 全部已构建环境的产物（2.0 多环境 builder） */
     environments?: Record<string, BuildResult['output']>;
-    /** 环境驱动返回的完整结果（entries / manifest / stats 等） */
+    /** 全部环境的完整结果（entries / manifest / stats 等） */
     environmentResults?: Record<string, EnvironmentBuildResult>;
+    /** app 级 finalizer 聚合写出的产物（如 `.lynx.bundle`） */
+    appOutput?: AppBuildOutput[];
 }
 declare function build(inlineConfig?: NastiConfig): Promise<BuildResult>;
 
@@ -788,4 +844,4 @@ declare function buildEnvDefine(env: EnvRecord, mode: string, overrides?: Record
 /** 按环境 consumer 派生 import.meta.env.SSR 的 define 覆盖 */
 declare function ssrDefineOverrides(consumer: 'client' | 'server'): Record<string, string>;
 
-export { type BuildConfig, type DevServer, type ElectronConfig, type EnvironmentBuildOutput, type EnvironmentBuildResult, type EnvironmentDriver, type EnvironmentDriverContext, type EnvironmentDriverServeContext, type EnvironmentInstance, type EnvironmentOptions, type EnvironmentServeResult, type HmrPayload, type HotChannel, type HotChannelClient, type HotChannelInvokeHandlers, type LogLevel, LogLevels, type LogOptions, type Logger, type ModuleNode, type MonacoCustomWorker, type MonacoEditorLanguageWorker, type MonacoEditorPluginOptions, type NastiConfig, NastiEnvironment, type NastiPlugin, type NastiRolldownOptions, type PluginApi, type PluginApiKey, type PluginContext, type RenderChunkContext, type ResolvedConfig, type ResolvedEnvironmentOptions, type TransformResult, build, buildElectron, buildEnvDefine, createDebugger, createElectronRendererConfig, createLogger, createNoopHotChannel, createServer, createWsHotChannel, defineConfig, detectFramework, electronPlugin, electronRendererDevPath, loadEnv, monacoEditorPlugin, printServerUrls, resolveConfig, resolveEnvironmentPlugins, ssrDefineOverrides, startElectronDev };
+export { type AppBuildOutput, type BuildAppContext, type BuildConfig, type BuildResult, type DevServer, type ElectronConfig, type EnvironmentBuildMetadata, type EnvironmentBuildOutput, type EnvironmentBuildResult, type EnvironmentDriver, type EnvironmentDriverContext, type EnvironmentDriverServeContext, type EnvironmentInstance, type EnvironmentOptions, type EnvironmentServeResult, type HmrPayload, type HotChannel, type HotChannelClient, type HotChannelInvokeHandlers, type LogLevel, LogLevels, type LogOptions, type Logger, type ModuleNode, type MonacoCustomWorker, type MonacoEditorLanguageWorker, type MonacoEditorPluginOptions, type NastiConfig, NastiEnvironment, type NastiPlugin, type NastiRolldownOptions, type PluginApi, type PluginApiKey, type PluginContext, type RenderChunkContext, type ResolvedConfig, type ResolvedEnvironmentOptions, type TransformResult, build, buildElectron, buildEnvDefine, createDebugger, createElectronRendererConfig, createLogger, createNoopHotChannel, createServer, createWsHotChannel, defineConfig, detectFramework, electronPlugin, electronRendererDevPath, loadEnv, monacoEditorPlugin, printServerUrls, resolveConfig, resolveEnvironmentPlugins, ssrDefineOverrides, startElectronDev };

package/dist/index.d.ts

@@ -105,6 +105,11 @@ interface EnvironmentOptions {
      * Electron renderer 会把 `electron.renderer` 映射到这里。
      */
     html?: string;
+    /**
+     * 是否参与生产构建。默认 true；设为 false 可跳过默认 client，构建纯多环境应用。
+     * 仅影响 `nasti build`，不影响 dev server 中环境实例的可见性。
+     */
+    buildEnabled?: boolean;
     /**
      * 外部环境编译驱动标识。声明后由插件的 `createEnvironmentDriver` 提供实际实现，
      * 可用于接入 Rspeedy 等不基于 Rolldown 的构建系统。
@@ -118,6 +123,8 @@ interface EnvironmentOptions {
 /** 解析后的环境配置 */
 interface ResolvedEnvironmentOptions {
     consumer: 'client' | 'server';
+    /** 是否参与生产构建 */
+    buildEnabled: boolean;
     /** 环境构建入口（绝对路径）；client 未显式配置时为空并从 HTML 提取 */
     entry: string[];
     /** HTML 入口绝对路径（仅 client consumer 有值） */
@@ -302,7 +309,7 @@ interface NastiPlugin {
      * 所有环境构建完成后的 app 级收尾钩子，用于跨环境聚合产物。
      * Vue Lynx 原生后端可在这里组合 background/main-thread bundle。
      */
-    afterBuildApp?: (results: Record<string, EnvironmentBuildResult>, api: PluginApi) => void | Promise<void>;
+    afterBuildApp?: (results: Record<string, EnvironmentBuildResult>, api: PluginApi, context: BuildAppContext) => void | Promise<void>;
     configureServer?: (server: DevServer) => void | (() => void) | Promise<void | (() => void)>;
     transformIndexHtml?: (html: string) => string | HtmlTagDescriptor[] | {
         html: string;
@@ -337,14 +344,37 @@ interface EnvironmentBuildOutput {
     code?: string;
     source?: Uint8Array | string;
 }
-/** 外部环境驱动返回的标准构建结果。 */
-interface EnvironmentBuildResult {
-    output: EnvironmentBuildOutput[];
+/** 单个环境附加到标准构建结果上的结构化元数据。 */
+interface EnvironmentBuildMetadata {
     entries?: Record<string, string>;
     publicPath?: string;
     manifest?: unknown;
     stats?: unknown;
 }
+/** 外部环境驱动或原生 Rolldown 环境返回的标准构建结果。 */
+interface EnvironmentBuildResult extends EnvironmentBuildMetadata {
+    output: EnvironmentBuildOutput[];
+}
+/** app 级 finalizer 写出的聚合产物。 */
+interface AppBuildOutput extends EnvironmentBuildOutput {
+    type: 'asset';
+    source: Uint8Array | string;
+}
+/**
+ * 所有环境完成后提供给 `afterBuildApp` 的只读查询与产物写出接口。
+ * Lynx 等多运行时工具链可用它聚合 background/main-thread 结果，而无需读取磁盘目录。
+ */
+interface BuildAppContext {
+    readonly config: ResolvedConfig;
+    readonly results: Readonly<Record<string, EnvironmentBuildResult>>;
+    readonly output: readonly AppBuildOutput[];
+    getResult: (environmentName: string) => EnvironmentBuildResult | undefined;
+    getArtifact: (environmentName: string, fileName: string) => EnvironmentBuildOutput | undefined;
+    getEntry: (environmentName: string, entryName: string) => EnvironmentBuildOutput | undefined;
+    getManifest: <T = unknown>(environmentName: string) => T | undefined;
+    /** 将聚合产物安全地写入 top-level `build.outDir`，并纳入 BuildResult.appOutput。 */
+    emitFile: (file: AppBuildOutput) => string;
+}
 /** 外部环境驱动返回的开发服务信息。 */
 interface EnvironmentServeResult {
     localUrls?: string[];
@@ -380,6 +410,8 @@ interface EnvironmentInstance {
     hot: HotChannel;
     /** 声明 driver 后，由插件提供的外部环境编译驱动 */
     driver?: EnvironmentDriver;
+    /** 由生产插件登记 entries / manifest / stats，构建完成后合并进环境结果。 */
+    setBuildMetadata: (metadata: EnvironmentBuildMetadata) => void;
 }
 /**
  * renderChunk / augmentChunkHash 的 `this`：Rolldown 真实插件上下文的最小可用面。
@@ -389,6 +421,8 @@ interface EnvironmentInstance {
 interface RenderChunkContext {
     emitFile: (file: EmittedFile) => string;
     getFileName: (referenceId: string) => string;
+    /** 当前生产钩子所属环境；BG/MT 同为 client consumer 时也可准确区分。 */
+    environment: EnvironmentInstance;
 }
 interface ResolveIdOptions {
     isEntry?: boolean;
@@ -436,6 +470,8 @@ interface ModuleNode {
     acceptedHmrDeps: Set<ModuleNode>;
     transformResult: TransformResult | null;
     lastHMRTimestamp: number;
+    /** 每次失效递增，防止较慢的旧转换覆盖较新的缓存。 */
+    invalidationVersion: number;
     isSelfAccepting: boolean;
     /** Environment API：节点所属环境名（per-env 模块图，默认 'client'） */
     environment?: string;
@@ -496,7 +532,12 @@ interface ModuleGraph$1 {
     getModuleById: (id: string) => ModuleNode | undefined;
     getModulesByFile: (file: string) => Set<ModuleNode> | undefined;
     ensureEntryFromUrl: (url: string) => Promise<ModuleNode>;
-    invalidateModule: (mod: ModuleNode) => void;
+    invalidateModule: (mod: ModuleNode, timestamp?: number) => void;
+    invalidateModuleAndImporters: (mod: ModuleNode, timestamp?: number) => void;
+    getHmrBoundaries: (mod: ModuleNode) => Array<{
+        boundary: ModuleNode;
+        acceptedVia: ModuleNode;
+    }>;
     invalidateAll: () => void;
 }
 interface WebSocketServer {
@@ -630,8 +671,18 @@ declare class ModuleGraph {
     setModuleId(mod: ModuleNode, id: string): void;
     /** 更新模块依赖关系 */
     updateModuleImports(mod: ModuleNode, importedIds: Set<string>): void;
+    /**
+     * 用一次转换得到的信息原子更新 import 与 HMR accept 关系。
+     * 依赖节点会在真正被浏览器请求前预先创建，这样入口模块先转换时也能建立完整图。
+     */
+    updateModuleInfo(mod: ModuleNode, importedUrls: Set<string>, acceptedUrls: Set<string>, isSelfAccepting: boolean, expectedInvalidationVersion?: number): Promise<Set<ModuleNode> | null>;
     /** 使模块的转换缓存失效 */
-    invalidateModule(mod: ModuleNode): void;
+    invalidateModule(mod: ModuleNode, timestamp?: number): void;
+    /**
+     * 仅失效到 HMR 边界：显式接受依赖的模块本身不会重执行；自接受模块需要失效，
+     * 但不再继续影响其 importer。这样既能传播依赖时间戳，也不会隐式重复副作用。
+     */
+    invalidateModuleAndImporters(mod: ModuleNode, timestamp?: number, seen?: Set<ModuleNode>): void;
     /** 使所有模块缓存失效 */
     invalidateAll(): void;
     /** 获取 HMR 传播边界 - 从变更模块向上遍历找到接受更新的边界 */
@@ -665,11 +716,14 @@ declare class NastiEnvironment implements EnvironmentInstance {
     moduleGraph: ModuleGraph;
     private candidatePlugins;
     private pluginApi;
+    private buildMetadata;
     private initialized;
     constructor(name: string, config: ResolvedConfig, init?: NastiEnvironmentInit);
     /** 过滤插件并建 per-env PluginContainer */
     init(): Promise<void>;
     getDriverContext(): EnvironmentDriverContext;
+    setBuildMetadata(metadata: EnvironmentBuildMetadata): void;
+    getBuildMetadata(): EnvironmentBuildMetadata;
     close(): Promise<void>;
 }
 /** 按 applyToEnvironment 过滤环境插件（未声明 = 应用于所有环境） */
@@ -680,8 +734,10 @@ interface BuildResult {
     output: EnvironmentBuildOutput[];
     /** 全部已构建环境的产物（2.0 多环境 builder） */
     environments?: Record<string, BuildResult['output']>;
-    /** 环境驱动返回的完整结果（entries / manifest / stats 等） */
+    /** 全部环境的完整结果（entries / manifest / stats 等） */
     environmentResults?: Record<string, EnvironmentBuildResult>;
+    /** app 级 finalizer 聚合写出的产物（如 `.lynx.bundle`） */
+    appOutput?: AppBuildOutput[];
 }
 declare function build(inlineConfig?: NastiConfig): Promise<BuildResult>;
 
@@ -788,4 +844,4 @@ declare function buildEnvDefine(env: EnvRecord, mode: string, overrides?: Record
 /** 按环境 consumer 派生 import.meta.env.SSR 的 define 覆盖 */
 declare function ssrDefineOverrides(consumer: 'client' | 'server'): Record<string, string>;
 
-export { type BuildConfig, type DevServer, type ElectronConfig, type EnvironmentBuildOutput, type EnvironmentBuildResult, type EnvironmentDriver, type EnvironmentDriverContext, type EnvironmentDriverServeContext, type EnvironmentInstance, type EnvironmentOptions, type EnvironmentServeResult, type HmrPayload, type HotChannel, type HotChannelClient, type HotChannelInvokeHandlers, type LogLevel, LogLevels, type LogOptions, type Logger, type ModuleNode, type MonacoCustomWorker, type MonacoEditorLanguageWorker, type MonacoEditorPluginOptions, type NastiConfig, NastiEnvironment, type NastiPlugin, type NastiRolldownOptions, type PluginApi, type PluginApiKey, type PluginContext, type RenderChunkContext, type ResolvedConfig, type ResolvedEnvironmentOptions, type TransformResult, build, buildElectron, buildEnvDefine, createDebugger, createElectronRendererConfig, createLogger, createNoopHotChannel, createServer, createWsHotChannel, defineConfig, detectFramework, electronPlugin, electronRendererDevPath, loadEnv, monacoEditorPlugin, printServerUrls, resolveConfig, resolveEnvironmentPlugins, ssrDefineOverrides, startElectronDev };
+export { type AppBuildOutput, type BuildAppContext, type BuildConfig, type BuildResult, type DevServer, type ElectronConfig, type EnvironmentBuildMetadata, type EnvironmentBuildOutput, type EnvironmentBuildResult, type EnvironmentDriver, type EnvironmentDriverContext, type EnvironmentDriverServeContext, type EnvironmentInstance, type EnvironmentOptions, type EnvironmentServeResult, type HmrPayload, type HotChannel, type HotChannelClient, type HotChannelInvokeHandlers, type LogLevel, LogLevels, type LogOptions, type Logger, type ModuleNode, type MonacoCustomWorker, type MonacoEditorLanguageWorker, type MonacoEditorPluginOptions, type NastiConfig, NastiEnvironment, type NastiPlugin, type NastiRolldownOptions, type PluginApi, type PluginApiKey, type PluginContext, type RenderChunkContext, type ResolvedConfig, type ResolvedEnvironmentOptions, type TransformResult, build, buildElectron, buildEnvDefine, createDebugger, createElectronRendererConfig, createLogger, createNoopHotChannel, createServer, createWsHotChannel, defineConfig, detectFramework, electronPlugin, electronRendererDevPath, loadEnv, monacoEditorPlugin, printServerUrls, resolveConfig, resolveEnvironmentPlugins, ssrDefineOverrides, startElectronDev };