@nasti-toolchain/nasti 2.2.0 → 2.3.1

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,20 @@ 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;
+    /**
+     * 外部环境编译驱动标识。声明后由插件的 `createEnvironmentDriver` 提供实际实现，
+     * 可用于接入 Rspeedy 等不基于 Rolldown 的构建系统。
+     */
+    driver?: string;
     /** per-env 路径解析（client 默认含 'browser' condition；server 走 node conditions） */
     resolve?: ResolveConfig;
     /** per-env 构建覆盖（未设置的字段回退 top-level build） */
@@ -107,8 +118,12 @@ interface EnvironmentOptions {
 /** 解析后的环境配置 */
 interface ResolvedEnvironmentOptions {
     consumer: 'client' | 'server';
-    /** 非 client 环境的构建入口（绝对路径）；client 恒为 [] */
+    /** 环境构建入口（绝对路径）；client 未显式配置时为空并从 HTML 提取 */
     entry: string[];
+    /** HTML 入口绝对路径（仅 client consumer 有值） */
+    html?: string;
+    /** 外部环境编译驱动标识 */
+    driver?: string;
     resolve: Required<ResolveConfig>;
     build: Required<BuildConfig>;
 }
@@ -217,10 +232,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 +293,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) => void | Promise<void>;
     configureServer?: (server: DevServer) => void | (() => void) | Promise<void | (() => void)>;
     transformIndexHtml?: (html: string) => string | HtmlTagDescriptor[] | {
         html: string;
@@ -292,6 +323,50 @@ 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 EnvironmentBuildResult {
+    output: EnvironmentBuildOutput[];
+    entries?: Record<string, string>;
+    publicPath?: string;
+    manifest?: unknown;
+    stats?: unknown;
+}
+/** 外部环境驱动返回的开发服务信息。 */
+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 +378,8 @@ interface EnvironmentInstance {
     config: ResolvedConfig;
     options: ResolvedEnvironmentOptions;
     hot: HotChannel;
+    /** 声明 driver 后，由插件提供的外部环境编译驱动 */
+    driver?: EnvironmentDriver;
 }
 /**
  * renderChunk / augmentChunkHash 的 `this`：Rolldown 真实插件上下文的最小可用面。
@@ -368,7 +445,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 +478,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>;
@@ -482,6 +562,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.
  *
@@ -559,6 +646,8 @@ interface NastiEnvironmentInit {
     mode?: 'dev' | 'build';
     /** 环境的候选插件（init 时经 applyToEnvironment 过滤） */
     plugins?: NastiPlugin[];
+    /** 配置解析阶段创建的共享插件 API；通常自动从 ResolvedConfig 获取 */
+    pluginApi?: PluginApi;
 }
 declare class NastiEnvironment implements EnvironmentInstance {
     readonly name: string;
@@ -567,6 +656,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 +664,12 @@ declare class NastiEnvironment implements EnvironmentInstance {
     /** per-env 模块图（dev 管线使用） */
     moduleGraph: ModuleGraph;
     private candidatePlugins;
+    private pluginApi;
     private initialized;
     constructor(name: string, config: ResolvedConfig, init?: NastiEnvironmentInit);
     /** 过滤插件并建 per-env PluginContainer */
     init(): Promise<void>;
+    getDriverContext(): EnvironmentDriverContext;
     close(): Promise<void>;
 }
 /** 按 applyToEnvironment 过滤环境插件（未声明 = 应用于所有环境） */
@@ -585,14 +677,11 @@ 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>;
 }
 declare function build(inlineConfig?: NastiConfig): Promise<BuildResult>;
 
@@ -611,6 +700,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 +720,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 +788,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 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 };

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,20 @@ 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;
+    /**
+     * 外部环境编译驱动标识。声明后由插件的 `createEnvironmentDriver` 提供实际实现，
+     * 可用于接入 Rspeedy 等不基于 Rolldown 的构建系统。
+     */
+    driver?: string;
     /** per-env 路径解析（client 默认含 'browser' condition；server 走 node conditions） */
     resolve?: ResolveConfig;
     /** per-env 构建覆盖（未设置的字段回退 top-level build） */
@@ -107,8 +118,12 @@ interface EnvironmentOptions {
 /** 解析后的环境配置 */
 interface ResolvedEnvironmentOptions {
     consumer: 'client' | 'server';
-    /** 非 client 环境的构建入口（绝对路径）；client 恒为 [] */
+    /** 环境构建入口（绝对路径）；client 未显式配置时为空并从 HTML 提取 */
     entry: string[];
+    /** HTML 入口绝对路径（仅 client consumer 有值） */
+    html?: string;
+    /** 外部环境编译驱动标识 */
+    driver?: string;
     resolve: Required<ResolveConfig>;
     build: Required<BuildConfig>;
 }
@@ -217,10 +232,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 +293,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) => void | Promise<void>;
     configureServer?: (server: DevServer) => void | (() => void) | Promise<void | (() => void)>;
     transformIndexHtml?: (html: string) => string | HtmlTagDescriptor[] | {
         html: string;
@@ -292,6 +323,50 @@ 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 EnvironmentBuildResult {
+    output: EnvironmentBuildOutput[];
+    entries?: Record<string, string>;
+    publicPath?: string;
+    manifest?: unknown;
+    stats?: unknown;
+}
+/** 外部环境驱动返回的开发服务信息。 */
+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 +378,8 @@ interface EnvironmentInstance {
     config: ResolvedConfig;
     options: ResolvedEnvironmentOptions;
     hot: HotChannel;
+    /** 声明 driver 后，由插件提供的外部环境编译驱动 */
+    driver?: EnvironmentDriver;
 }
 /**
  * renderChunk / augmentChunkHash 的 `this`：Rolldown 真实插件上下文的最小可用面。
@@ -368,7 +445,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 +478,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>;
@@ -482,6 +562,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.
  *
@@ -559,6 +646,8 @@ interface NastiEnvironmentInit {
     mode?: 'dev' | 'build';
     /** 环境的候选插件（init 时经 applyToEnvironment 过滤） */
     plugins?: NastiPlugin[];
+    /** 配置解析阶段创建的共享插件 API；通常自动从 ResolvedConfig 获取 */
+    pluginApi?: PluginApi;
 }
 declare class NastiEnvironment implements EnvironmentInstance {
     readonly name: string;
@@ -567,6 +656,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 +664,12 @@ declare class NastiEnvironment implements EnvironmentInstance {
     /** per-env 模块图（dev 管线使用） */
     moduleGraph: ModuleGraph;
     private candidatePlugins;
+    private pluginApi;
     private initialized;
     constructor(name: string, config: ResolvedConfig, init?: NastiEnvironmentInit);
     /** 过滤插件并建 per-env PluginContainer */
     init(): Promise<void>;
+    getDriverContext(): EnvironmentDriverContext;
     close(): Promise<void>;
 }
 /** 按 applyToEnvironment 过滤环境插件（未声明 = 应用于所有环境） */
@@ -585,14 +677,11 @@ 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>;
 }
 declare function build(inlineConfig?: NastiConfig): Promise<BuildResult>;
 
@@ -611,6 +700,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 +720,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 +788,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 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 };