@nasti-toolchain/nasti 2.3.1 → 2.4.1

package/dist/index.d.cts

@@ -1,5 +1,6 @@
-import { InputOptions, OutputOptions, RenderedChunk } from 'rolldown';
+import { RenderedChunk, InputOptions, OutputOptions } from 'rolldown';
 import { IncomingMessage, ServerResponse } from 'node:http';
+import { SFCParseOptions, SFCScriptCompileOptions, SFCTemplateCompileOptions, SFCAsyncStyleCompileOptions } from '@vue/compiler-sfc';
 
 type LogType = 'error' | 'warn' | 'info';
 type LogLevel = LogType | 'silent';
@@ -82,7 +83,7 @@ interface ExperimentalOptions {
      * dev 用 Rolldown `dev()` 引擎整体打包 client 环境后从内存服务
      * （完整打包模式 / Full Bundle Mode）。HMR 由引擎的 patch 机制驱动，
      * 动态 import 走懒编译端点。依赖 rolldown 实验 API（无 semver 保护，
-     * 版本锁定 rc.13）。unbundled 管线保持默认。
+     * Nasti 会精确锁定经过验证的 Rolldown 版本）。unbundled 管线保持默认。
      * @experimental
      * @default false
      */
@@ -105,6 +106,11 @@ interface EnvironmentOptions {
      * Electron renderer 会把 `electron.renderer` 映射到这里。
      */
     html?: string;
+    /**
+     * 是否参与生产构建。默认 true；设为 false 可跳过默认 client，构建纯多环境应用。
+     * 仅影响 `nasti build`，不影响 dev server 中环境实例的可见性。
+     */
+    buildEnabled?: boolean;
     /**
      * 外部环境编译驱动标识。声明后由插件的 `createEnvironmentDriver` 提供实际实现，
      * 可用于接入 Rspeedy 等不基于 Rolldown 的构建系统。
@@ -114,10 +120,45 @@ interface EnvironmentOptions {
     resolve?: ResolveConfig;
     /** per-env 构建覆盖（未设置的字段回退 top-level build） */
     build?: BuildConfig;
+    /**
+     * Vue SFC 编译扩展点。每个环境可独立设置 compiler-sfc 选项与源码变换，
+     * 同一个 SFC 的虚拟模块 id / scope id 不包含环境名，因而在多图之间保持稳定。
+     */
+    vue?: VueEnvironmentOptions;
+}
+interface VueSfcTransformContext {
+    filename: string;
+    environmentName: string;
+    type: 'sfc' | 'template' | 'style';
+    index?: number;
+}
+type VueSfcSourceTransform = (source: string, context: VueSfcTransformContext) => string
+/**
+ * Object results may provide a source map from `code` back to `source`.
+ * Nasti composes it with compiler-sfc maps where that stage supports chaining.
+ */
+ | {
+    code: string;
+    map?: unknown;
+} | Promise<string | {
+    code: string;
+    map?: unknown;
+}>;
+/** 直接透传给 `@vue/compiler-sfc` 对应阶段的 per-environment 选项。 */
+interface VueEnvironmentOptions {
+    parse?: SFCParseOptions;
+    script?: Partial<SFCScriptCompileOptions>;
+    template?: Partial<SFCTemplateCompileOptions>;
+    style?: Partial<SFCAsyncStyleCompileOptions>;
+    transformSfc?: VueSfcSourceTransform;
+    transformTemplate?: VueSfcSourceTransform;
+    transformStyle?: VueSfcSourceTransform;
 }
 /** 解析后的环境配置 */
 interface ResolvedEnvironmentOptions {
     consumer: 'client' | 'server';
+    /** 是否参与生产构建 */
+    buildEnabled: boolean;
     /** 环境构建入口（绝对路径）；client 未显式配置时为空并从 HTML 提取 */
     entry: string[];
     /** HTML 入口绝对路径（仅 client consumer 有值） */
@@ -126,6 +167,7 @@ interface ResolvedEnvironmentOptions {
     driver?: string;
     resolve: Required<ResolveConfig>;
     build: Required<BuildConfig>;
+    vue: VueEnvironmentOptions;
 }
 /** Electron 目标专用配置，支持 Electron 41+ */
 interface ElectronConfig {
@@ -224,10 +266,21 @@ interface CssConfig {
     /** CSP nonce to add to inline <style> tags (dev only since 2.0 — build emits real .css files) */
     nonce?: string;
     /**
-     * @deprecated 2.0 起 build 始终抽取真实 .css 文件（per-chunk hash + <link> 注入），
-     * 该开关不再生效。控制拆分用 `build.cssCodeSplit`，控制压缩用 `build.cssMinify`。
+     * @deprecated 请改用 `css.emit` 控制是否写出 CSS 文件。控制拆分用
+     * `build.cssCodeSplit`，控制压缩用 `build.cssMinify`。
      */
     emitCssFile?: boolean;
+    /**
+     * 是否在浏览器运行时 / HTML 中注入 CSS。原生 client 环境可关闭注入，
+     * 同时继续保留 CSS 模块图与结构化元数据。
+     * @default true
+     */
+    inject?: boolean;
+    /**
+     * 是否写出 `.css` 文件。关闭后仍收集每个 chunk 的 CSS 所有权。
+     * @default true
+     */
+    emit?: boolean;
 }
 interface NastiPlugin {
     name: string;
@@ -302,7 +355,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;
@@ -312,6 +365,11 @@ interface NastiPlugin {
         tags: HtmlTagDescriptor[];
     }>;
     handleHotUpdate?: (ctx: HmrContext) => void | ModuleNode[] | Promise<void | ModuleNode[]>;
+    /**
+     * 一个文件在所有 dev client 环境完成失效、插件 HMR 钩子与重新转换后调用一次。
+     * 多运行时工具链可据此只重编码受影响的 native section。
+     */
+    handleHotUpdateApp?: (ctx: AppHmrContext) => void | Promise<void>;
 }
 interface PluginContext {
     resolve: (source: string, importer?: string) => Promise<ResolveIdResult>;
@@ -336,14 +394,83 @@ interface EnvironmentBuildOutput {
     type: string;
     code?: string;
     source?: Uint8Array | string;
+    map?: unknown;
+    name?: string;
+    names?: string[];
+    isEntry?: boolean;
+    isDynamicEntry?: boolean;
+    imports?: string[];
+    dynamicImports?: string[];
+    moduleIds?: string[];
 }
-/** 外部环境驱动返回的标准构建结果。 */
-interface EnvironmentBuildResult {
-    output: EnvironmentBuildOutput[];
+interface EnvironmentCssModule {
+    id: string;
+    source: string;
+    code: string;
+}
+interface EnvironmentCssChunk {
+    fileName: string;
+    moduleIds: string[];
+    cssFileNames: string[];
+}
+interface EnvironmentCssMetadata {
+    modules: Record<string, EnvironmentCssModule>;
+    chunks: Record<string, EnvironmentCssChunk>;
+}
+interface EnvironmentChunkMetadata {
+    fileName: string;
+    name: string;
+    isEntry: boolean;
+    isDynamicEntry: boolean;
+    imports: string[];
+    dynamicImports: string[];
+    moduleIds: string[];
+    css: string[];
+    assets: string[];
+}
+interface EnvironmentAssetMetadata {
+    fileName: string;
+    names: string[];
+    publicPath: string;
+}
+/** 单个环境附加到标准构建结果上的结构化元数据。 */
+interface EnvironmentBuildMetadata {
     entries?: Record<string, string>;
     publicPath?: string;
     manifest?: unknown;
     stats?: unknown;
+    chunks?: Record<string, EnvironmentChunkMetadata>;
+    assets?: Record<string, EnvironmentAssetMetadata>;
+    css?: EnvironmentCssMetadata;
+    sourceMaps?: Record<string, 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;
+    getChunk: (environmentName: string, fileName: string) => EnvironmentChunkMetadata | undefined;
+    getCss: (environmentName: string) => EnvironmentCssMetadata | undefined;
+    getSourceMap: (environmentName: string, fileName: string) => unknown;
+    resolvePublicPath: (environmentName: string, fileName: string) => string | undefined;
+    /** 将聚合产物安全地写入 top-level `build.outDir`，并纳入 BuildResult.appOutput。 */
+    emitFile: (file: AppBuildOutput) => string;
 }
 /** 外部环境驱动返回的开发服务信息。 */
 interface EnvironmentServeResult {
@@ -380,6 +507,24 @@ interface EnvironmentInstance {
     hot: HotChannel;
     /** 声明 driver 后，由插件提供的外部环境编译驱动 */
     driver?: EnvironmentDriver;
+    /** per-environment dev 模块图与插件列表。 */
+    moduleGraph: ModuleGraph$1;
+    plugins: NastiPlugin[];
+    /**
+     * 在该环境的独立 transform 管线中请求模块。仅 dev 环境在初始化后可用。
+     */
+    transformRequest: (url: string) => Promise<{
+        code: string;
+        map?: unknown;
+    } | null>;
+    /** 内置 CSS 管线登记模块；工具链通常读取 getCssModule(s)。 */
+    setCssModule: (module: EnvironmentCssModule) => void;
+    getCssModule: (id: string) => EnvironmentCssModule | undefined;
+    getCssModules: () => Readonly<Record<string, EnvironmentCssModule>>;
+    setAssetModule: (id: string, fileName: string) => void;
+    getAssetModules: () => Readonly<Record<string, string>>;
+    /** 由生产插件登记 entries / manifest / stats，构建完成后合并进环境结果。 */
+    setBuildMetadata: (metadata: EnvironmentBuildMetadata) => void;
 }
 /**
  * renderChunk / augmentChunkHash 的 `this`：Rolldown 真实插件上下文的最小可用面。
@@ -389,6 +534,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 +583,8 @@ interface ModuleNode {
     acceptedHmrDeps: Set<ModuleNode>;
     transformResult: TransformResult | null;
     lastHMRTimestamp: number;
+    /** 每次失效递增，防止较慢的旧转换覆盖较新的缓存。 */
+    invalidationVersion: number;
     isSelfAccepting: boolean;
     /** Environment API：节点所属环境名（per-env 模块图，默认 'client'） */
     environment?: string;
@@ -476,13 +625,14 @@ interface DevServer {
     moduleGraph: ModuleGraph$1;
     watcher: any;
     ws: WebSocketServer;
-    /** Environment API：per-env 环境实例（Phase 1 仅 client 有完整运行时） */
+    /** Environment API：每个 client-consumer 环境都有独立的 transform/HMR 管线。 */
     environments: Record<string, EnvironmentInstance>;
     /** 外部环境驱动启动后返回的服务 URL / middleware 信息 */
     environmentServices: Record<string, EnvironmentServeResult>;
     listen: (port?: number) => Promise<DevServer>;
     close: () => Promise<void>;
     transformRequest: (url: string) => Promise<TransformResult>;
+    transformEnvironmentRequest: (environmentName: string, url: string) => Promise<TransformResult>;
     /**
      * SSR：在 server consumer 环境（默认 `ssr`）中加载并执行模块，返回其导出。
      * Vite `server.ssrLoadModule` 的 back-compat shim（底层是 module runner +
@@ -496,7 +646,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 {
@@ -535,8 +690,29 @@ interface HmrContext {
     modules: ModuleNode[];
     read: () => string | Promise<string>;
     server: DevServer;
+    environment: EnvironmentInstance;
+}
+interface EnvironmentTransformedModule {
+    module: ModuleNode;
+    result: {
+        code: string;
+        map?: unknown;
+    } | null;
+}
+interface EnvironmentHotUpdateResult {
+    environment: EnvironmentInstance;
+    modules: ModuleNode[];
+    updates: HmrUpdate[];
+    transformed: EnvironmentTransformedModule[];
+    fullReload: boolean;
+}
+interface AppHmrContext {
+    file: string;
+    timestamp: number;
+    environments: Readonly<Record<string, EnvironmentHotUpdateResult>>;
+    server: DevServer;
 }
-type HmrPayload = {
+type HmrPayload = ({
     type: 'connected';
 } | {
     type: 'update';
@@ -553,6 +729,12 @@ type HmrPayload = {
         message: string;
         stack?: string;
     };
+} | {
+    type: 'custom';
+    event: string;
+    data?: unknown;
+}) & {
+    environment?: string;
 };
 interface HmrUpdate {
     type: 'js-update' | 'css-update';
@@ -610,9 +792,11 @@ declare class PluginContainer {
 }
 
 declare class ModuleGraph {
+    readonly environmentName: string;
     private urlToModuleMap;
     private idToModuleMap;
     private fileToModulesMap;
+    constructor(environmentName?: string);
     getModuleByUrl(url: string): ModuleNode | undefined;
     getModuleById(id: string): ModuleNode | undefined;
     getModulesByFile(file: string): Set<ModuleNode> | undefined;
@@ -630,8 +814,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 +859,30 @@ declare class NastiEnvironment implements EnvironmentInstance {
     moduleGraph: ModuleGraph;
     private candidatePlugins;
     private pluginApi;
+    private buildMetadata;
+    private cssModules;
+    private assetModules;
+    private transformRequestHandler?;
     private initialized;
     constructor(name: string, config: ResolvedConfig, init?: NastiEnvironmentInit);
     /** 过滤插件并建 per-env PluginContainer */
     init(): Promise<void>;
     getDriverContext(): EnvironmentDriverContext;
+    configureDevPipeline(transformRequest: (url: string) => Promise<{
+        code: string;
+        map?: unknown;
+    } | null>): void;
+    transformRequest(url: string): Promise<{
+        code: string;
+        map?: unknown;
+    } | null>;
+    setCssModule(module: EnvironmentCssModule): void;
+    getCssModule(id: string): EnvironmentCssModule | undefined;
+    getCssModules(): Readonly<Record<string, EnvironmentCssModule>>;
+    setAssetModule(id: string, fileName: string): void;
+    getAssetModules(): Readonly<Record<string, string>>;
+    setBuildMetadata(metadata: EnvironmentBuildMetadata): void;
+    getBuildMetadata(): EnvironmentBuildMetadata;
     close(): Promise<void>;
 }
 /** 按 applyToEnvironment 过滤环境插件（未声明 = 应用于所有环境） */
@@ -680,8 +893,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>;
 
@@ -752,13 +967,13 @@ interface MonacoEditorPluginOptions {
 }
 declare function monacoEditorPlugin(options?: MonacoEditorPluginOptions): NastiPlugin;
 
-/** 非 client 环境的占位通道（SSR/edge 在 Phase 2 接上真实 transport） */
+/** 非 client 环境的占位通道（SSR/edge 可由 runner/driver 接上真实 transport） */
 declare function createNoopHotChannel(): HotChannel;
 /**
- * client 环境的 ws 通道：包装 server/ws.ts 的 WebSocketServer。
- * 事件监听与 invoke 在现有 ws 协议上预留（custom event 协议 Phase 2 扩展）。
+ * client-consumer 环境的 ws 通道：包装 server/ws.ts 的 WebSocketServer。
+ * 事件监听与 invoke 在现有 ws 协议上预留，payload 以 environment 字段分流。
  */
-declare function createWsHotChannel(ws: WebSocketServer): HotChannel;
+declare function createWsHotChannel(ws: WebSocketServer, environmentName?: string): HotChannel;
 
 type NastiDebugScope = `nasti:${string}`;
 interface DebuggerOptions {
@@ -788,4 +1003,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 AppHmrContext, type BuildAppContext, type BuildConfig, type BuildResult, type DevServer, type ElectronConfig, type EnvironmentAssetMetadata, type EnvironmentBuildMetadata, type EnvironmentBuildOutput, type EnvironmentBuildResult, type EnvironmentChunkMetadata, type EnvironmentCssChunk, type EnvironmentCssMetadata, type EnvironmentCssModule, type EnvironmentDriver, type EnvironmentDriverContext, type EnvironmentDriverServeContext, type EnvironmentHotUpdateResult, type EnvironmentInstance, type EnvironmentOptions, type EnvironmentServeResult, type EnvironmentTransformedModule, type HmrPayload, type HmrUpdate, 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, type VueEnvironmentOptions, type VueSfcSourceTransform, type VueSfcTransformContext, build, buildElectron, buildEnvDefine, createDebugger, createElectronRendererConfig, createLogger, createNoopHotChannel, createServer, createWsHotChannel, defineConfig, detectFramework, electronPlugin, electronRendererDevPath, loadEnv, monacoEditorPlugin, printServerUrls, resolveConfig, resolveEnvironmentPlugins, ssrDefineOverrides, startElectronDev };