@nasti-toolchain/nasti 2.2.0 → 2.4.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { InputOptions, OutputOptions, RenderedChunk } from 'rolldown';
+import { IncomingMessage, ServerResponse } from 'node:http';
 
 type LogType = 'error' | 'warn' | 'info';
 type LogLevel = LogType | 'silent';
@@ -95,10 +96,25 @@ interface EnvironmentOptions {
      */
     consumer?: 'client' | 'server';
     /**
-     * 该环境的构建入口（相对 root）。client 环境忽略此项（入口从 index.html
-     * 提取）；非 client 环境**只有声明了 entry 才会被 `nasti build` 构建**。
+     * 该环境的构建入口（相对 root）。client 默认从 HTML 提取；显式配置后可覆盖。
+     * 非 client 环境只有声明 entry 或 driver 才会被 `nasti build` 构建。
      */
     entry?: string | string[];
+    /**
+     * HTML 入口（相对 root），仅 client consumer 使用。默认 `index.html`。
+     * Electron renderer 会把 `electron.renderer` 映射到这里。
+     */
+    html?: string;
+    /**
+     * 是否参与生产构建。默认 true；设为 false 可跳过默认 client，构建纯多环境应用。
+     * 仅影响 `nasti build`，不影响 dev server 中环境实例的可见性。
+     */
+    buildEnabled?: boolean;
+    /**
+     * 外部环境编译驱动标识。声明后由插件的 `createEnvironmentDriver` 提供实际实现，
+     * 可用于接入 Rspeedy 等不基于 Rolldown 的构建系统。
+     */
+    driver?: string;
     /** per-env 路径解析（client 默认含 'browser' condition；server 走 node conditions） */
     resolve?: ResolveConfig;
     /** per-env 构建覆盖（未设置的字段回退 top-level build） */
@@ -107,8 +123,14 @@ interface EnvironmentOptions {
 /** 解析后的环境配置 */
 interface ResolvedEnvironmentOptions {
     consumer: 'client' | 'server';
-    /** 非 client 环境的构建入口（绝对路径）；client 恒为 [] */
+    /** 是否参与生产构建 */
+    buildEnabled: boolean;
+    /** 环境构建入口（绝对路径）；client 未显式配置时为空并从 HTML 提取 */
     entry: string[];
+    /** HTML 入口绝对路径（仅 client consumer 有值） */
+    html?: string;
+    /** 外部环境编译驱动标识 */
+    driver?: string;
     resolve: Required<ResolveConfig>;
     build: Required<BuildConfig>;
 }
@@ -217,10 +239,16 @@ interface CssConfig {
 interface NastiPlugin {
     name: string;
     enforce?: 'pre' | 'post';
+    /** 必须在当前插件 setup 前完成 setup 的插件名 */
+    pre?: string[];
+    /** 必须在当前插件 setup 后完成 setup 的插件名 */
+    post?: string[];
     apply?: 'build' | 'serve' | ((config: ResolvedConfig, env: {
         mode: string;
         command: string;
     }) => boolean);
+    /** 插件初始化与跨插件 API 注册；每次 resolveConfig 只执行一次 */
+    setup?: (api: PluginApi) => void | Promise<void>;
     buildStart?: (this: PluginContext) => void | Promise<void>;
     buildEnd?: (this: PluginContext, error?: Error) => void | Promise<void>;
     /**
@@ -272,6 +300,16 @@ interface NastiPlugin {
      * 插件管线。未声明时插件应用于所有环境（与 Vite 默认一致）。
      */
     applyToEnvironment?: (environment: EnvironmentInstance) => boolean;
+    /**
+     * 为声明了 `environment.options.driver` 的环境提供外部编译驱动。
+     * 一个环境只能被一个插件接管；返回多个驱动会报错。
+     */
+    createEnvironmentDriver?: (environment: EnvironmentInstance, api: PluginApi) => EnvironmentDriver | null | undefined | Promise<EnvironmentDriver | null | undefined>;
+    /**
+     * 所有环境构建完成后的 app 级收尾钩子，用于跨环境聚合产物。
+     * Vue Lynx 原生后端可在这里组合 background/main-thread bundle。
+     */
+    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;
@@ -292,6 +330,73 @@ interface PluginContext {
      */
     environment?: EnvironmentInstance;
 }
+type PluginApiKey = string | symbol;
+/** 插件 setup 与环境驱动共享的跨插件 API。 */
+interface PluginApi {
+    readonly config: ResolvedConfig;
+    readonly logger: Logger;
+    expose: <T>(key: PluginApiKey, value: T) => void;
+    useExposed: <T>(key: PluginApiKey) => T | undefined;
+}
+interface EnvironmentBuildOutput {
+    fileName: string;
+    type: string;
+    code?: string;
+    source?: Uint8Array | string;
+}
+/** 单个环境附加到标准构建结果上的结构化元数据。 */
+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[];
+    networkUrls?: string[];
+    middleware?: (request: IncomingMessage, response: ServerResponse, next: (error?: unknown) => void) => void;
+}
+interface EnvironmentDriverContext {
+    environment: EnvironmentInstance;
+    config: ResolvedConfig;
+    api: PluginApi;
+    logger: Logger;
+}
+interface EnvironmentDriverServeContext extends EnvironmentDriverContext {
+    server: DevServer;
+}
+interface EnvironmentDriver {
+    name: string;
+    build?: (context: EnvironmentDriverContext) => EnvironmentBuildResult | Promise<EnvironmentBuildResult>;
+    serve?: (context: EnvironmentDriverServeContext) => EnvironmentServeResult | void | Promise<EnvironmentServeResult | void>;
+    watchChange?: (file: string, event: 'add' | 'change' | 'unlink', context: EnvironmentDriverContext) => void | Promise<void>;
+    close?: (context: EnvironmentDriverContext) => void | Promise<void>;
+}
 /**
  * 环境实例的公共面（核心实现见 core/environment.ts 的 NastiEnvironment）。
  * 插件经 `this.environment` / `applyToEnvironment(env)` 感知环境。
@@ -303,6 +408,10 @@ interface EnvironmentInstance {
     config: ResolvedConfig;
     options: ResolvedEnvironmentOptions;
     hot: HotChannel;
+    /** 声明 driver 后，由插件提供的外部环境编译驱动 */
+    driver?: EnvironmentDriver;
+    /** 由生产插件登记 entries / manifest / stats，构建完成后合并进环境结果。 */
+    setBuildMetadata: (metadata: EnvironmentBuildMetadata) => void;
 }
 /**
  * renderChunk / augmentChunkHash 的 `this`：Rolldown 真实插件上下文的最小可用面。
@@ -312,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;
@@ -359,6 +470,8 @@ interface ModuleNode {
     acceptedHmrDeps: Set<ModuleNode>;
     transformResult: TransformResult | null;
     lastHMRTimestamp: number;
+    /** 每次失效递增，防止较慢的旧转换覆盖较新的缓存。 */
+    invalidationVersion: number;
     isSelfAccepting: boolean;
     /** Environment API：节点所属环境名（per-env 模块图，默认 'client'） */
     environment?: string;
@@ -368,7 +481,8 @@ interface ResolvedConfig {
     base: string;
     mode: 'development' | 'production';
     target: 'web' | 'electron';
-    framework: 'react' | 'vue' | 'auto';
+    /** `auto` 在配置解析阶段已收敛为具体框架 */
+    framework: 'react' | 'vue';
     command: 'build' | 'serve';
     resolve: Required<ResolveConfig>;
     plugins: NastiPlugin[];
@@ -400,6 +514,8 @@ interface DevServer {
     ws: WebSocketServer;
     /** Environment API：per-env 环境实例（Phase 1 仅 client 有完整运行时） */
     environments: Record<string, EnvironmentInstance>;
+    /** 外部环境驱动启动后返回的服务 URL / middleware 信息 */
+    environmentServices: Record<string, EnvironmentServeResult>;
     listen: (port?: number) => Promise<DevServer>;
     close: () => Promise<void>;
     transformRequest: (url: string) => Promise<TransformResult>;
@@ -416,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 {
@@ -482,6 +603,13 @@ interface HmrUpdate {
 }
 
 declare function defineConfig(config: NastiConfig): NastiConfig;
+/**
+ * 将 framework:auto 收敛为具体框架。
+ *
+ * 优先使用源码中的 .vue 文件消除同时安装 React/Vue 时的歧义，其次读取
+ * package.json dependencies，最后回退 React 以保持 1.x 默认行为。
+ */
+declare function detectFramework(root: string): 'react' | 'vue';
 /**
  * Resolve the final configuration by loading file-based config, merging with inline config, and applying plugin hooks.
  *
@@ -543,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 传播边界 - 从变更模块向上遍历找到接受更新的边界 */
@@ -559,6 +697,8 @@ interface NastiEnvironmentInit {
     mode?: 'dev' | 'build';
     /** 环境的候选插件（init 时经 applyToEnvironment 过滤） */
     plugins?: NastiPlugin[];
+    /** 配置解析阶段创建的共享插件 API；通常自动从 ResolvedConfig 获取 */
+    pluginApi?: PluginApi;
 }
 declare class NastiEnvironment implements EnvironmentInstance {
     readonly name: string;
@@ -567,6 +707,7 @@ declare class NastiEnvironment implements EnvironmentInstance {
     readonly config: ResolvedConfig;
     readonly options: ResolvedEnvironmentOptions;
     readonly hot: HotChannel;
+    driver?: EnvironmentDriver;
     /** applyToEnvironment 过滤后的插件（init() 后可用） */
     plugins: NastiPlugin[];
     /** per-env 插件容器（init() 后可用；dev 管线使用） */
@@ -574,10 +715,15 @@ declare class NastiEnvironment implements EnvironmentInstance {
     /** per-env 模块图（dev 管线使用） */
     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 过滤环境插件（未声明 = 应用于所有环境） */
@@ -585,14 +731,13 @@ declare function resolveEnvironmentPlugins(environment: EnvironmentInstance, plu
 
 interface BuildResult {
     /** client 环境的产物（back-compat：1.x 的 BuildResult 形态） */
-    output: Array<{
-        fileName: string;
-        type: string;
-        code?: string;
-        source?: Uint8Array | string;
-    }>;
+    output: EnvironmentBuildOutput[];
     /** 全部已构建环境的产物（2.0 多环境 builder） */
     environments?: Record<string, BuildResult['output']>;
+    /** 全部环境的完整结果（entries / manifest / stats 等） */
+    environmentResults?: Record<string, EnvironmentBuildResult>;
+    /** app 级 finalizer 聚合写出的产物（如 `.lynx.bundle`） */
+    appOutput?: AppBuildOutput[];
 }
 declare function build(inlineConfig?: NastiConfig): Promise<BuildResult>;
 
@@ -611,6 +756,13 @@ interface ElectronBuildResult {
  * @throws Error if the configured Electron main entry file does not exist
  */
 declare function buildElectron(inlineConfig?: NastiConfig): Promise<ElectronBuildResult>;
+/**
+ * 从 Electron 配置派生 renderer 的普通 Web 构建配置。
+ *
+ * renderer 使用指定 HTML 入口；本地文件加载场景默认把 `/` base 收敛为
+ * `./`，避免产物中的 `/assets/*` 被解析到文件系统根目录。
+ */
+declare function createElectronRendererConfig(config: ResolvedConfig, inlineConfig?: NastiConfig, overrides?: Pick<NastiConfig, 'build'>): NastiConfig;
 
 declare function createServer(inlineConfig?: NastiConfig): Promise<DevServer>;
 
@@ -624,6 +776,8 @@ interface ElectronDevOptions extends NastiConfig {
  * @param inlineConfig - Development options; when `inlineConfig.noSpawn` is `true`, only compiles main/preload into `.nasti/` and does not start the Electron process.
  */
 declare function startElectronDev(inlineConfig?: ElectronDevOptions): Promise<void>;
+/** 将 renderer HTML 路径转换为 Electron 开发服务器 URL path。 */
+declare function electronRendererDevPath(renderer: string): string;
 
 /**
  * Create a Vite/Rollup plugin that externalizes Electron and Node built-in imports according to the resolved config.
@@ -690,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 EnvironmentInstance, type EnvironmentOptions, 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 PluginContext, type RenderChunkContext, type ResolvedConfig, type ResolvedEnvironmentOptions, type TransformResult, build, buildElectron, buildEnvDefine, createDebugger, createLogger, createNoopHotChannel, createServer, createWsHotChannel, defineConfig, electronPlugin, 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

@@ -1,4 +1,5 @@
 import { InputOptions, OutputOptions, RenderedChunk } from 'rolldown';
+import { IncomingMessage, ServerResponse } from 'node:http';
 
 type LogType = 'error' | 'warn' | 'info';
 type LogLevel = LogType | 'silent';
@@ -95,10 +96,25 @@ interface EnvironmentOptions {
      */
     consumer?: 'client' | 'server';
     /**
-     * 该环境的构建入口（相对 root）。client 环境忽略此项（入口从 index.html
-     * 提取）；非 client 环境**只有声明了 entry 才会被 `nasti build` 构建**。
+     * 该环境的构建入口（相对 root）。client 默认从 HTML 提取；显式配置后可覆盖。
+     * 非 client 环境只有声明 entry 或 driver 才会被 `nasti build` 构建。
      */
     entry?: string | string[];
+    /**
+     * HTML 入口（相对 root），仅 client consumer 使用。默认 `index.html`。
+     * Electron renderer 会把 `electron.renderer` 映射到这里。
+     */
+    html?: string;
+    /**
+     * 是否参与生产构建。默认 true；设为 false 可跳过默认 client，构建纯多环境应用。
+     * 仅影响 `nasti build`，不影响 dev server 中环境实例的可见性。
+     */
+    buildEnabled?: boolean;
+    /**
+     * 外部环境编译驱动标识。声明后由插件的 `createEnvironmentDriver` 提供实际实现，
+     * 可用于接入 Rspeedy 等不基于 Rolldown 的构建系统。
+     */
+    driver?: string;
     /** per-env 路径解析（client 默认含 'browser' condition；server 走 node conditions） */
     resolve?: ResolveConfig;
     /** per-env 构建覆盖（未设置的字段回退 top-level build） */
@@ -107,8 +123,14 @@ interface EnvironmentOptions {
 /** 解析后的环境配置 */
 interface ResolvedEnvironmentOptions {
     consumer: 'client' | 'server';
-    /** 非 client 环境的构建入口（绝对路径）；client 恒为 [] */
+    /** 是否参与生产构建 */
+    buildEnabled: boolean;
+    /** 环境构建入口（绝对路径）；client 未显式配置时为空并从 HTML 提取 */
     entry: string[];
+    /** HTML 入口绝对路径（仅 client consumer 有值） */
+    html?: string;
+    /** 外部环境编译驱动标识 */
+    driver?: string;
     resolve: Required<ResolveConfig>;
     build: Required<BuildConfig>;
 }
@@ -217,10 +239,16 @@ interface CssConfig {
 interface NastiPlugin {
     name: string;
     enforce?: 'pre' | 'post';
+    /** 必须在当前插件 setup 前完成 setup 的插件名 */
+    pre?: string[];
+    /** 必须在当前插件 setup 后完成 setup 的插件名 */
+    post?: string[];
     apply?: 'build' | 'serve' | ((config: ResolvedConfig, env: {
         mode: string;
         command: string;
     }) => boolean);
+    /** 插件初始化与跨插件 API 注册；每次 resolveConfig 只执行一次 */
+    setup?: (api: PluginApi) => void | Promise<void>;
     buildStart?: (this: PluginContext) => void | Promise<void>;
     buildEnd?: (this: PluginContext, error?: Error) => void | Promise<void>;
     /**
@@ -272,6 +300,16 @@ interface NastiPlugin {
      * 插件管线。未声明时插件应用于所有环境（与 Vite 默认一致）。
      */
     applyToEnvironment?: (environment: EnvironmentInstance) => boolean;
+    /**
+     * 为声明了 `environment.options.driver` 的环境提供外部编译驱动。
+     * 一个环境只能被一个插件接管；返回多个驱动会报错。
+     */
+    createEnvironmentDriver?: (environment: EnvironmentInstance, api: PluginApi) => EnvironmentDriver | null | undefined | Promise<EnvironmentDriver | null | undefined>;
+    /**
+     * 所有环境构建完成后的 app 级收尾钩子，用于跨环境聚合产物。
+     * Vue Lynx 原生后端可在这里组合 background/main-thread bundle。
+     */
+    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;
@@ -292,6 +330,73 @@ interface PluginContext {
      */
     environment?: EnvironmentInstance;
 }
+type PluginApiKey = string | symbol;
+/** 插件 setup 与环境驱动共享的跨插件 API。 */
+interface PluginApi {
+    readonly config: ResolvedConfig;
+    readonly logger: Logger;
+    expose: <T>(key: PluginApiKey, value: T) => void;
+    useExposed: <T>(key: PluginApiKey) => T | undefined;
+}
+interface EnvironmentBuildOutput {
+    fileName: string;
+    type: string;
+    code?: string;
+    source?: Uint8Array | string;
+}
+/** 单个环境附加到标准构建结果上的结构化元数据。 */
+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[];
+    networkUrls?: string[];
+    middleware?: (request: IncomingMessage, response: ServerResponse, next: (error?: unknown) => void) => void;
+}
+interface EnvironmentDriverContext {
+    environment: EnvironmentInstance;
+    config: ResolvedConfig;
+    api: PluginApi;
+    logger: Logger;
+}
+interface EnvironmentDriverServeContext extends EnvironmentDriverContext {
+    server: DevServer;
+}
+interface EnvironmentDriver {
+    name: string;
+    build?: (context: EnvironmentDriverContext) => EnvironmentBuildResult | Promise<EnvironmentBuildResult>;
+    serve?: (context: EnvironmentDriverServeContext) => EnvironmentServeResult | void | Promise<EnvironmentServeResult | void>;
+    watchChange?: (file: string, event: 'add' | 'change' | 'unlink', context: EnvironmentDriverContext) => void | Promise<void>;
+    close?: (context: EnvironmentDriverContext) => void | Promise<void>;
+}
 /**
  * 环境实例的公共面（核心实现见 core/environment.ts 的 NastiEnvironment）。
  * 插件经 `this.environment` / `applyToEnvironment(env)` 感知环境。
@@ -303,6 +408,10 @@ interface EnvironmentInstance {
     config: ResolvedConfig;
     options: ResolvedEnvironmentOptions;
     hot: HotChannel;
+    /** 声明 driver 后，由插件提供的外部环境编译驱动 */
+    driver?: EnvironmentDriver;
+    /** 由生产插件登记 entries / manifest / stats，构建完成后合并进环境结果。 */
+    setBuildMetadata: (metadata: EnvironmentBuildMetadata) => void;
 }
 /**
  * renderChunk / augmentChunkHash 的 `this`：Rolldown 真实插件上下文的最小可用面。
@@ -312,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;
@@ -359,6 +470,8 @@ interface ModuleNode {
     acceptedHmrDeps: Set<ModuleNode>;
     transformResult: TransformResult | null;
     lastHMRTimestamp: number;
+    /** 每次失效递增，防止较慢的旧转换覆盖较新的缓存。 */
+    invalidationVersion: number;
     isSelfAccepting: boolean;
     /** Environment API：节点所属环境名（per-env 模块图，默认 'client'） */
     environment?: string;
@@ -368,7 +481,8 @@ interface ResolvedConfig {
     base: string;
     mode: 'development' | 'production';
     target: 'web' | 'electron';
-    framework: 'react' | 'vue' | 'auto';
+    /** `auto` 在配置解析阶段已收敛为具体框架 */
+    framework: 'react' | 'vue';
     command: 'build' | 'serve';
     resolve: Required<ResolveConfig>;
     plugins: NastiPlugin[];
@@ -400,6 +514,8 @@ interface DevServer {
     ws: WebSocketServer;
     /** Environment API：per-env 环境实例（Phase 1 仅 client 有完整运行时） */
     environments: Record<string, EnvironmentInstance>;
+    /** 外部环境驱动启动后返回的服务 URL / middleware 信息 */
+    environmentServices: Record<string, EnvironmentServeResult>;
     listen: (port?: number) => Promise<DevServer>;
     close: () => Promise<void>;
     transformRequest: (url: string) => Promise<TransformResult>;
@@ -416,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 {
@@ -482,6 +603,13 @@ interface HmrUpdate {
 }
 
 declare function defineConfig(config: NastiConfig): NastiConfig;
+/**
+ * 将 framework:auto 收敛为具体框架。
+ *
+ * 优先使用源码中的 .vue 文件消除同时安装 React/Vue 时的歧义，其次读取
+ * package.json dependencies，最后回退 React 以保持 1.x 默认行为。
+ */
+declare function detectFramework(root: string): 'react' | 'vue';
 /**
  * Resolve the final configuration by loading file-based config, merging with inline config, and applying plugin hooks.
  *
@@ -543,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 传播边界 - 从变更模块向上遍历找到接受更新的边界 */
@@ -559,6 +697,8 @@ interface NastiEnvironmentInit {
     mode?: 'dev' | 'build';
     /** 环境的候选插件（init 时经 applyToEnvironment 过滤） */
     plugins?: NastiPlugin[];
+    /** 配置解析阶段创建的共享插件 API；通常自动从 ResolvedConfig 获取 */
+    pluginApi?: PluginApi;
 }
 declare class NastiEnvironment implements EnvironmentInstance {
     readonly name: string;
@@ -567,6 +707,7 @@ declare class NastiEnvironment implements EnvironmentInstance {
     readonly config: ResolvedConfig;
     readonly options: ResolvedEnvironmentOptions;
     readonly hot: HotChannel;
+    driver?: EnvironmentDriver;
     /** applyToEnvironment 过滤后的插件（init() 后可用） */
     plugins: NastiPlugin[];
     /** per-env 插件容器（init() 后可用；dev 管线使用） */
@@ -574,10 +715,15 @@ declare class NastiEnvironment implements EnvironmentInstance {
     /** per-env 模块图（dev 管线使用） */
     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 过滤环境插件（未声明 = 应用于所有环境） */
@@ -585,14 +731,13 @@ declare function resolveEnvironmentPlugins(environment: EnvironmentInstance, plu
 
 interface BuildResult {
     /** client 环境的产物（back-compat：1.x 的 BuildResult 形态） */
-    output: Array<{
-        fileName: string;
-        type: string;
-        code?: string;
-        source?: Uint8Array | string;
-    }>;
+    output: EnvironmentBuildOutput[];
     /** 全部已构建环境的产物（2.0 多环境 builder） */
     environments?: Record<string, BuildResult['output']>;
+    /** 全部环境的完整结果（entries / manifest / stats 等） */
+    environmentResults?: Record<string, EnvironmentBuildResult>;
+    /** app 级 finalizer 聚合写出的产物（如 `.lynx.bundle`） */
+    appOutput?: AppBuildOutput[];
 }
 declare function build(inlineConfig?: NastiConfig): Promise<BuildResult>;
 
@@ -611,6 +756,13 @@ interface ElectronBuildResult {
  * @throws Error if the configured Electron main entry file does not exist
  */
 declare function buildElectron(inlineConfig?: NastiConfig): Promise<ElectronBuildResult>;
+/**
+ * 从 Electron 配置派生 renderer 的普通 Web 构建配置。
+ *
+ * renderer 使用指定 HTML 入口；本地文件加载场景默认把 `/` base 收敛为
+ * `./`，避免产物中的 `/assets/*` 被解析到文件系统根目录。
+ */
+declare function createElectronRendererConfig(config: ResolvedConfig, inlineConfig?: NastiConfig, overrides?: Pick<NastiConfig, 'build'>): NastiConfig;
 
 declare function createServer(inlineConfig?: NastiConfig): Promise<DevServer>;
 
@@ -624,6 +776,8 @@ interface ElectronDevOptions extends NastiConfig {
  * @param inlineConfig - Development options; when `inlineConfig.noSpawn` is `true`, only compiles main/preload into `.nasti/` and does not start the Electron process.
  */
 declare function startElectronDev(inlineConfig?: ElectronDevOptions): Promise<void>;
+/** 将 renderer HTML 路径转换为 Electron 开发服务器 URL path。 */
+declare function electronRendererDevPath(renderer: string): string;
 
 /**
  * Create a Vite/Rollup plugin that externalizes Electron and Node built-in imports according to the resolved config.
@@ -690,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 EnvironmentInstance, type EnvironmentOptions, 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 PluginContext, type RenderChunkContext, type ResolvedConfig, type ResolvedEnvironmentOptions, type TransformResult, build, buildElectron, buildEnvDefine, createDebugger, createLogger, createNoopHotChannel, createServer, createWsHotChannel, defineConfig, electronPlugin, 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 };