rolldown 1.0.0-beta.57 → 1.0.0-beta.59

package/dist/shared/{define-config-kYHtCO-M.d.mts → define-config-Cg9apQLa.d.mts}

@@ -1,5 +1,5 @@
-import { a as RollupLog, i as RollupError, n as LogLevelOption, o as RollupLogWithString, r as LogOrStringHandler, t as LogLevel } from "./logging-BpAvp7KV.mjs";
-import { A as BindingWatcherBundler, B as ParserOptions, F as JsxOptions, I as MinifyOptions$1, M as ExternalMemoryStatus, V as PreRenderedChunk, W as TransformOptions$1, a as BindingHookResolveIdExtraArgs, d as BindingTransformHookExtraArgs, j as BindingWatcherEvent, l as BindingRenderedChunk, s as BindingMagicString, t as BindingBuiltinPluginName } from "./binding-CDyF6W3D.mjs";
+import { a as RollupLog, i as RollupError, n as LogLevelOption, o as RollupLogWithString, r as LogOrStringHandler, t as LogLevel } from "./logging-B4x9qar8.mjs";
+import { A as BindingWatcherBundler, B as ParserOptions, F as JsxOptions, I as MinifyOptions$1, M as ExternalMemoryStatus, V as PreRenderedChunk, W as TransformOptions$1, a as BindingHookResolveIdExtraArgs, d as BindingTransformHookExtraArgs, j as BindingWatcherEvent, l as BindingRenderedChunk, s as BindingMagicString, t as BindingBuiltinPluginName } from "./binding-MAEzB4KA.mjs";
 import { TopLevelFilterExpression } from "@rolldown/pluginutils";
 import { Program } from "@oxc-project/types";
 
@@ -8,6 +8,7 @@ type SourcemapPathTransformOption = (relativeSourcePath: string, sourcemapPath:
 type SourcemapIgnoreListOption = (relativeSourcePath: string, sourcemapPath: string) => boolean;
 //#endregion
 //#region src/types/module-info.d.ts
+/** @category Plugin APIs */
 interface ModuleInfo extends ModuleOptions {
   /**
   *  Unsupported at rolldown
@@ -78,6 +79,7 @@ interface ExternalMemoryHandle {
 declare function freeExternalMemory(handle: ExternalMemoryHandle, keepDataAlive?: boolean): ExternalMemoryStatus;
 //#endregion
 //#region src/types/rolldown-output.d.ts
+/** @category Plugin APIs */
 interface OutputAsset extends ExternalMemoryHandle {
   type: "asset";
   fileName: string;
@@ -89,6 +91,7 @@ interface OutputAsset extends ExternalMemoryHandle {
   name: string | undefined;
   names: string[];
 }
+/** @category Plugin APIs */
 interface SourceMap {
   file: string;
   mappings: string;
@@ -101,11 +104,13 @@ interface SourceMap {
   toString(): string;
   toUrl(): string;
 }
+/** @category Plugin APIs */
 interface RenderedModule {
   readonly code: string | null;
   renderedLength: number;
   renderedExports: string[];
 }
+/** @category Plugin APIs */
 interface RenderedChunk extends Omit<BindingRenderedChunk, "modules"> {
   type: "chunk";
   modules: {
@@ -121,6 +126,7 @@ interface RenderedChunk extends Omit<BindingRenderedChunk, "modules"> {
   imports: Array<string>;
   dynamicImports: Array<string>;
 }
+/** @category Plugin APIs */
 interface OutputChunk extends ExternalMemoryHandle {
   type: "chunk";
   code: string;
@@ -140,6 +146,7 @@ interface OutputChunk extends ExternalMemoryHandle {
   sourcemapFileName: string | null;
   preliminaryFileName: string;
 }
+/** @category Programmatic APIs */
 interface RolldownOutput extends ExternalMemoryHandle {
   output: [OutputChunk, ...(OutputChunk | OutputAsset)[]];
 }
@@ -191,6 +198,7 @@ type ModuleFormat = "es" | "cjs" | "esm" | "module" | "commonjs" | "iife" | "umd
 type AddonFunction = (chunk: RenderedChunk) => string | Promise<string>;
 type ChunkFileNamesFunction = (chunkInfo: PreRenderedChunk) => string;
 type SanitizeFileNameFunction = (name: string) => string;
+/** @category Plugin APIs */
 interface PreRenderedAsset {
   type: "asset";
   name?: string;
@@ -329,6 +337,7 @@ interface OutputOptions {
   generatedCode?: Partial<GeneratedCodeOptions>;
   externalLiveBindings?: boolean;
   inlineDynamicImports?: boolean;
+  dynamicImportInCjs?: boolean;
   /**
   * - Type: `((moduleId: string, meta: { getModuleInfo: (moduleId: string) => ModuleInfo | null }) => string | NullValue)`
   * - Object form is not supported.
@@ -613,6 +622,7 @@ interface BuildOptions extends InputOptions {
   write?: boolean;
   output?: OutputOptions;
 }
+/** @category Programmatic APIs */
 declare function build(options: BuildOptions): Promise<RolldownOutput>;
 /**
 * Build multiple outputs __sequentially__.
@@ -620,6 +630,7 @@ declare function build(options: BuildOptions): Promise<RolldownOutput>;
 declare function build(options: BuildOptions[]): Promise<RolldownOutput[]>;
 //#endregion
 //#region src/api/rolldown/rolldown-build.d.ts
+/** @category Programmatic APIs */
 declare class RolldownBuild {
   #private;
   static asyncRuntimeShutdown: boolean;
@@ -636,9 +647,11 @@ declare class RolldownBuild {
 }
 //#endregion
 //#region src/api/rolldown/index.d.ts
+/** @category Programmatic APIs */
 declare const rolldown: (input: InputOptions) => Promise<RolldownBuild>;
 //#endregion
 //#region src/options/watch-options.d.ts
+/** @category Programmatic APIs */
 interface WatchOptions extends InputOptions {
   output?: OutputOptions | OutputOptions[];
 }
@@ -647,6 +660,7 @@ interface WatchOptions extends InputOptions {
 type WatcherEvent = "close" | "event" | "restart" | "change";
 type ChangeEvent$1 = "create" | "update" | "delete";
 type RolldownWatchBuild = BindingWatcherBundler;
+/** @category Programmatic APIs */
 type RolldownWatcherEvent = {
   code: "START";
 } | {
@@ -677,9 +691,11 @@ declare class WatcherEmitter {
   onEvent(event: BindingWatcherEvent): Promise<void>;
   close(): Promise<void>;
 }
+/** @category Programmatic APIs */
 type RolldownWatcher = WatcherEmitter;
 //#endregion
 //#region src/api/watch/index.d.ts
+/** @category Programmatic APIs */
 declare const watch: (input: WatchOptions | WatchOptions[]) => RolldownWatcher;
 //#endregion
 //#region src/log/log-handler.d.ts
@@ -690,7 +706,92 @@ type LoggingFunctionWithPosition = (log: RollupLog | string | (() => RollupLog |
 }) => void;
 type WarningHandlerWithDefault = (warning: RollupLog, defaultHandler: LoggingFunction) => void;
 //#endregion
+//#region src/options/generated/checks-options.d.ts
+interface ChecksOptions {
+  /**
+  * Whether to emit warning when detecting circular dependency
+  * @default false
+  * */
+  circularDependency?: boolean;
+  /**
+  * Whether to emit warning when detecting eval
+  * @default true
+  * */
+  eval?: boolean;
+  /**
+  * Whether to emit warning when detecting missing global name
+  * @default true
+  * */
+  missingGlobalName?: boolean;
+  /**
+  * Whether to emit warning when detecting missing name option for iife export
+  * @default true
+  * */
+  missingNameOptionForIifeExport?: boolean;
+  /**
+  * Whether to emit warning when detecting mixed exports
+  * @default true
+  * */
+  mixedExports?: boolean;
+  /**
+  * Whether to emit warning when detecting unresolved entry
+  * @default true
+  * */
+  unresolvedEntry?: boolean;
+  /**
+  * Whether to emit warning when detecting unresolved import
+  * @default true
+  * */
+  unresolvedImport?: boolean;
+  /**
+  * Whether to emit warning when detecting filename conflict
+  * @default true
+  * */
+  filenameConflict?: boolean;
+  /**
+  * Whether to emit warning when detecting common js variable in esm
+  * @default true
+  * */
+  commonJsVariableInEsm?: boolean;
+  /**
+  * Whether to emit warning when detecting import is undefined
+  * @default true
+  * */
+  importIsUndefined?: boolean;
+  /**
+  * Whether to emit warning when detecting empty import meta
+  * @default true
+  * */
+  emptyImportMeta?: boolean;
+  /**
+  * Whether to emit warning when detecting cannot call namespace
+  * @default true
+  * */
+  cannotCallNamespace?: boolean;
+  /**
+  * Whether to emit warning when detecting configuration field conflict
+  * @default true
+  * */
+  configurationFieldConflict?: boolean;
+  /**
+  * Whether to emit warning when detecting prefer builtin feature
+  * @default true
+  * */
+  preferBuiltinFeature?: boolean;
+  /**
+  * Whether to emit warning when detecting could not clean directory
+  * @default true
+  * */
+  couldNotCleanDirectory?: boolean;
+  /**
+  * Whether to emit warning when detecting plugin timings
+  * @default true
+  * */
+  pluginTimings?: boolean;
+}
+//#endregion
 //#region src/options/normalized-input-options.d.ts
+/** @category Plugin APIs */
 interface NormalizedInputOptions {
   input: string[] | Record<string, string>;
   cwd: string;
@@ -701,7 +802,9 @@ interface NormalizedInputOptions {
 //#endregion
 //#region src/options/normalized-output-options.d.ts
 type PathsFunction = (id: string) => string;
+/** @category Plugin APIs */
 type InternalModuleFormat = "es" | "cjs" | "iife" | "umd";
+/** @category Plugin APIs */
 interface NormalizedOutputOptions {
   name: string | undefined;
   file: string | undefined;
@@ -716,6 +819,7 @@ interface NormalizedOutputOptions {
   cssEntryFileNames: string | ChunkFileNamesFunction;
   cssChunkFileNames: string | ChunkFileNamesFunction;
   inlineDynamicImports: boolean;
+  dynamicImportInCjs: boolean;
   externalLiveBindings: boolean;
   banner: AddonFunction;
   footer: AddonFunction;
@@ -743,6 +847,7 @@ interface NormalizedOutputOptions {
 }
 //#endregion
 //#region src/plugin/fs.d.ts
+/** @category Plugin APIs */
 interface RolldownFsModule {
   appendFile(path: string, data: string | Uint8Array, options?: {
     encoding?: BufferEncoding | null;
@@ -785,13 +890,16 @@ interface RolldownFsModule {
     flag?: string | number;
   }): Promise<void>;
 }
+/** @category Plugin APIs */
 type BufferEncoding = "ascii" | "utf8" | "utf16le" | "ucs2" | "base64" | "base64url" | "latin1" | "binary" | "hex";
+/** @category Plugin APIs */
 interface RolldownDirectoryEntry {
   isFile(): boolean;
   isDirectory(): boolean;
   isSymbolicLink(): boolean;
   name: string;
 }
+/** @category Plugin APIs */
 interface RolldownFileStats {
   isFile(): boolean;
   isDirectory(): boolean;
@@ -804,6 +912,7 @@ interface RolldownFileStats {
 }
 //#endregion
 //#region src/plugin/hook-filter.d.ts
+/** @category Plugin APIs */
 type GeneralHookFilter<Value = StringOrRegExp> = MaybeArray<Value> | {
   include?: MaybeArray<Value>;
   exclude?: MaybeArray<Value>;
@@ -811,7 +920,9 @@ type GeneralHookFilter<Value = StringOrRegExp> = MaybeArray<Value> | {
 interface FormalModuleTypeFilter {
   include?: ModuleType[];
 }
+/** @category Plugin APIs */
 type ModuleTypeFilter = ModuleType[] | FormalModuleTypeFilter;
+/** @category Plugin APIs */
 interface HookFilter {
   /**
   * This filter is used to do a pre-test to determine whether the hook should be called.
@@ -852,11 +963,13 @@ interface HookFilter {
 type TUnionWithTopLevelFilterExpressionArray<T> = T | TopLevelFilterExpression[];
 //#endregion
 //#region src/plugin/minimal-plugin-context.d.ts
+/** @category Plugin APIs */
 interface PluginContextMeta {
   rollupVersion: string;
   rolldownVersion: string;
   watchMode: boolean;
 }
+/** @category Plugin APIs */
 interface MinimalPluginContext {
   readonly pluginName: string;
   error: (e: RollupError | string) => never;
@@ -868,16 +981,17 @@ interface MinimalPluginContext {
 //#endregion
 //#region src/plugin/parallel-plugin.d.ts
 type ParallelPlugin = {
-  /** @internal */
   _parallel: {
     fileUrl: string;
     options: unknown;
   };
 };
+/** @internal */
 type DefineParallelPluginResult<Options> = (options: Options) => ParallelPlugin;
 declare function defineParallelPlugin<Options>(pluginPath: string): DefineParallelPluginResult<Options>;
 //#endregion
 //#region src/plugin/plugin-context.d.ts
+/** @category Plugin APIs */
 interface EmittedAsset {
   type: "asset";
   name?: string;
@@ -901,13 +1015,16 @@ interface EmittedPrebuiltChunk {
   map?: SourceMap;
   sourcemapFileName?: string;
 }
+/** @category Plugin APIs */
 type EmittedFile = EmittedAsset | EmittedChunk | EmittedPrebuiltChunk;
 interface PluginContextResolveOptions {
   isEntry?: boolean;
   skipSelf?: boolean;
   custom?: CustomPluginOptions;
 }
+/** @category Plugin APIs */
 type GetModuleInfo = (moduleId: string) => ModuleInfo | null;
+/** @category Plugin APIs */
 interface PluginContext extends MinimalPluginContext {
   fs: RolldownFsModule;
   emitFile(file: EmittedFile): string;
@@ -924,6 +1041,7 @@ interface PluginContext extends MinimalPluginContext {
 }
 //#endregion
 //#region src/plugin/transform-plugin-context.d.ts
+/** @category Plugin APIs */
 interface TransformPluginContext extends PluginContext {
   debug: LoggingFunctionWithPosition;
   info: LoggingFunctionWithPosition;
@@ -942,17 +1060,132 @@ interface ModuleSideEffectsRule {
   sideEffects: boolean;
 }
 type ModuleSideEffectsOption = boolean | readonly string[] | ModuleSideEffectsRule[] | ((id: string, external: boolean) => boolean | undefined) | "no-external";
+/**
+* When passing an object, you can fine-tune the tree-shaking behavior.
+*/
 type TreeshakingOptions = {
+  /**
+  * **Values:**
+  *
+  * - **`true`**: All modules are assumed to have side effects and will be included in the bundle even if none of their exports are used.
+  * - **`false`**: No modules have side effects. This enables aggressive tree-shaking, removing any modules whose exports are not used.
+  * - **`string[]`**: Array of module IDs that have side effects. Only modules in this list will be preserved if unused; all others can be tree-shaken when their exports are unused.
+  * - **`'no-external'`**: Assumes no external modules have side effects while preserving the default behavior for local modules.
+  * - **`ModuleSideEffectsRule[]`**: Array of rules with `test`, `external`, and `sideEffects` properties for fine-grained control.
+  * - **`function`**: Function that receives `(id, external)` and returns whether the module has side effects.
+  *
+  * **Important:** Setting this to `false` or using an array/string assumes that your modules and their dependencies have no side effects other than their exports. Only use this if you're certain that removing unused modules won't break your application.
+  *
+  * > [!NOTE]
+  * > **Performance: Prefer `ModuleSideEffectsRule[]` over functions**
+  * >
+  * > When possible, use rule-based configuration instead of functions. Rules are processed entirely in Rust, while JavaScript functions require runtime calls between Rust and JavaScript, which can hurt CPU utilization during builds.
+  * >
+  * > **Functions should be a last resort**: Only use the function signature when your logic cannot be expressed with patterns or simple string matching.
+  * >
+  * > **Rule advantages**: `ModuleSideEffectsRule[]` provides better performance by avoiding Rust-JavaScript runtime calls, clearer intent, and easier maintenance.
+  *
+  * @example
+  * ```js
+  * // Assume no modules have side effects (aggressive tree-shaking)
+  * treeshake: {
+  *   moduleSideEffects: false
+  * }
+  *
+  * // Only specific modules have side effects (string array)
+  * treeshake: {
+  *   moduleSideEffects: [
+  *     'lodash',
+  *     'react-dom',
+  *   ]
+  * }
+  *
+  * // Use rules for pattern matching and granular control
+  * treeshake: {
+  *   moduleSideEffects: [
+  *     { test: /^node:/, sideEffects: true },
+  *     { test: /\.css$/, sideEffects: true },
+  *     { test: /some-package/, sideEffects: false, external: false },
+  *   ]
+  * }
+  *
+  * // Custom function to determine side effects
+  * treeshake: {
+  *   moduleSideEffects: (id, external) => {
+  *     if (external) return false; // external modules have no side effects
+  *     return id.includes('/side-effects/') || id.endsWith('.css');
+  *   }
+  * }
+  *
+  * // Assume no external modules have side effects
+  * treeshake: {
+  *   moduleSideEffects: 'no-external',
+  * }
+  * ```
+  *
+  * **Common Use Cases:**
+  * - **CSS files**: `{ test: /\.css$/, sideEffects: true }` - preserve CSS imports
+  * - **Polyfills**: Add specific polyfill modules to the array
+  * - **Plugins**: Modules that register themselves globally on import
+  * - **Library development**: Set to `false` for libraries where unused exports should be removed
+  * @default true
+  */
   moduleSideEffects?: ModuleSideEffectsOption;
+  /**
+  * Whether to respect `/*@__PURE__*\/` annotations and other tree-shaking hints in the code.
+  * @default true
+  */
   annotations?: boolean;
+  /**
+  * Array of function names that should be considered pure (no side effects) even if they can't be automatically detected as pure
+  *
+  * @example
+  * ```js
+  * treeshake: {
+  *   manualPureFunctions: ['console.log', 'debug.trace']
+  * }
+  * ```
+  * @default []
+  */
   manualPureFunctions?: readonly string[];
+  /**
+  * Whether to assume that accessing unknown global properties might have side effects.
+  * @default true
+  */
   unknownGlobalSideEffects?: boolean;
+  /**
+  * Whether to enable tree-shaking for CommonJS modules. When `true`, unused exports from CommonJS modules can be eliminated from the bundle, similar to ES modules. When disabled, CommonJS modules will always be included in their entirety.
+  *
+  * This option allows rolldown to analyze `exports.property` assignments in CommonJS modules and remove unused exports while preserving the module's side effects.
+  *
+  * @example
+  * ```js
+  * // source.js (CommonJS)
+  * exports.used = 'This will be kept';
+  * exports.unused = 'This will be tree-shaken away';
+  *
+  * // main.js
+  * import { used } from './source.js';
+  * // With commonjs: true, only the 'used' export is included in the bundle
+  * // With commonjs: false, both exports are included
+  * ```
+  * @default true
+  */
   commonjs?: boolean;
+  /**
+  * Controls whether reading properties from objects is considered to have side effects. Set to `always` for more conservative behavior.
+  * @default false
+  */
   propertyReadSideEffects?: false | "always";
+  /**
+  * Controls whether writing properties to objects is considered to have side effects. Set to `always` for conservative behavior.
+  * @default 'always'
+  */
   propertyWriteSideEffects?: false | "always";
 };
 //#endregion
 //#region src/types/output-bundle.d.ts
+/** @category Plugin APIs */
 interface OutputBundle {
   [fileName: string]: OutputAsset | OutputChunk;
 }
@@ -961,6 +1194,7 @@ interface OutputBundle {
 type RolldownOptionsFunction = (commandLineArguments: Record<string, any>) => MaybePromise<RolldownOptions | RolldownOptions[]>;
 //#endregion
 //#region src/types/sourcemap.d.ts
+/** @category Plugin APIs */
 interface ExistingRawSourceMap {
   file?: string | null;
   mappings: string;
@@ -974,6 +1208,7 @@ interface ExistingRawSourceMap {
 type SourceMapInput = ExistingRawSourceMap | string | null;
 //#endregion
 //#region src/version.d.ts
+/** @category Plugin APIs */
 declare const VERSION: string;
 //#endregion
 //#region src/builtin-plugin/utils.d.ts
@@ -999,7 +1234,7 @@ declare const ENUMERATED_PLUGIN_HOOK_NAMES: [...typeof ENUMERATED_INPUT_PLUGIN_H
 * }
 * ```
 */
-type DefinedHookNames = { readonly [K in typeof ENUMERATED_PLUGIN_HOOK_NAMES[number]]: K };
+type DefinedHookNames = { readonly [K in (typeof ENUMERATED_PLUGIN_HOOK_NAMES)[number]]: K };
 /**
 * Names of all defined hooks. It's like
 * ```js
@@ -1023,43 +1258,55 @@ declare function withFilter<A, T extends RolldownPluginOption<A>>(pluginOption:
 //#endregion
 //#region src/plugin/index.d.ts
 type ModuleSideEffects = boolean | "no-treeshake" | null;
+/** @category Plugin APIs */
 type ModuleType = "js" | "jsx" | "ts" | "tsx" | "json" | "text" | "base64" | "dataurl" | "binary" | "empty" | (string & {});
+/** @category Plugin APIs */
 type ImportKind = BindingHookResolveIdExtraArgs["kind"];
+/** @category Plugin APIs */
 interface CustomPluginOptions {
   [plugin: string]: any;
 }
+/** @category Plugin APIs */
 interface ModuleOptions {
   moduleSideEffects: ModuleSideEffects;
   meta: CustomPluginOptions;
   invalidate?: boolean;
   packageJsonPath?: string;
 }
+/** @category Plugin APIs */
 interface ResolvedId extends ModuleOptions {
   external: boolean | "absolute";
   id: string;
 }
+/** @category Plugin APIs */
 interface PartialResolvedId extends Partial<PartialNull<ModuleOptions>> {
   external?: boolean | "absolute" | "relative";
   id: string;
 }
+/** @category Plugin APIs */
 interface SourceDescription extends Partial<PartialNull<ModuleOptions>> {
   code: string;
   map?: SourceMapInput;
   moduleType?: ModuleType;
 }
+/** @category Plugin APIs */
 interface ResolveIdExtraOptions {
   custom?: CustomPluginOptions;
   isEntry: boolean;
   kind: BindingHookResolveIdExtraArgs["kind"];
 }
+/** @category Plugin APIs */
 type ResolveIdResult = string | NullValue | false | PartialResolvedId;
+/** @category Plugin APIs */
 type LoadResult = NullValue | string | SourceDescription;
+/** @category Plugin APIs */
 type TransformResult = NullValue | string | (Omit<SourceDescription, "code"> & {
   code?: string | BindingMagicString;
 });
 type RenderedChunkMeta = {
   chunks: Record<string, RenderedChunk>;
 };
+/** @category Plugin APIs */
 interface FunctionPluginHooks {
   [DEFINED_HOOK_NAMES.onLog]: (this: MinimalPluginContext, level: LogLevel, log: RollupLog) => NullValue | boolean;
   [DEFINED_HOOK_NAMES.options]: (this: MinimalPluginContext, options: InputOptions) => NullValue | InputOptions;
@@ -1099,16 +1346,20 @@ type PluginOrder = "pre" | "post" | null;
 type ObjectHookMeta = {
   order?: PluginOrder;
 };
+/** @category Plugin APIs */
 type ObjectHook<T, O = {}> = T | ({
   handler: T;
 } & ObjectHookMeta & O);
 type SyncPluginHooks = DefinedHookNames["augmentChunkHash" | "onLog" | "outputOptions"];
+/** @category Plugin APIs */
 type AsyncPluginHooks = Exclude<keyof FunctionPluginHooks, SyncPluginHooks>;
 type FirstPluginHooks = DefinedHookNames["load" | "resolveDynamicImport" | "resolveId"];
 type SequentialPluginHooks = DefinedHookNames["augmentChunkHash" | "generateBundle" | "onLog" | "options" | "outputOptions" | "renderChunk" | "transform"];
 type AddonHooks = DefinedHookNames["banner" | "footer" | "intro" | "outro"];
 type OutputPluginHooks = DefinedHookNames["augmentChunkHash" | "generateBundle" | "outputOptions" | "renderChunk" | "renderError" | "renderStart" | "writeBundle"];
+/** @internal */
 type ParallelPluginHooks = Exclude<keyof FunctionPluginHooks | AddonHooks, FirstPluginHooks | SequentialPluginHooks>;
+/** @category Plugin APIs */
 type HookFilterExtension<K$1 extends keyof FunctionPluginHooks> = K$1 extends "transform" ? {
   filter?: TUnionWithTopLevelFilterExpressionArray<HookFilter>;
 } : K$1 extends "load" ? {
@@ -1133,6 +1384,7 @@ type AddonHook = string | AddonHookFunction;
 interface OutputPlugin extends Partial<{ [K in keyof PluginHooks as K & OutputPluginHooks]: PluginHooks[K] }>, Partial<{ [K in AddonHooks]: ObjectHook<AddonHook> }> {
   name: string;
 }
+/** @category Plugin APIs */
 interface Plugin<A = any> extends OutputPlugin, Partial<PluginHooks> {
   api?: A;
 }
@@ -1145,90 +1397,6 @@ type RolldownOutputPluginOption = MaybePromise<NullValue<RolldownOutputPlugin> |
   name: string;
 } | false | RolldownOutputPluginOption[]>;
 //#endregion
-//#region src/options/generated/checks-options.d.ts
-interface ChecksOptions {
-  /**
-  * Whether to emit warning when detecting circular dependency
-  * @default false
-  */
-  circularDependency?: boolean;
-  /**
-  * Whether to emit warning when detecting eval
-  * @default true
-  */
-  eval?: boolean;
-  /**
-  * Whether to emit warning when detecting missing global name
-  * @default true
-  */
-  missingGlobalName?: boolean;
-  /**
-  * Whether to emit warning when detecting missing name option for iife export
-  * @default true
-  */
-  missingNameOptionForIifeExport?: boolean;
-  /**
-  * Whether to emit warning when detecting mixed exports
-  * @default true
-  */
-  mixedExports?: boolean;
-  /**
-  * Whether to emit warning when detecting unresolved entry
-  * @default true
-  */
-  unresolvedEntry?: boolean;
-  /**
-  * Whether to emit warning when detecting unresolved import
-  * @default true
-  */
-  unresolvedImport?: boolean;
-  /**
-  * Whether to emit warning when detecting filename conflict
-  * @default true
-  */
-  filenameConflict?: boolean;
-  /**
-  * Whether to emit warning when detecting common js variable in esm
-  * @default true
-  */
-  commonJsVariableInEsm?: boolean;
-  /**
-  * Whether to emit warning when detecting import is undefined
-  * @default true
-  */
-  importIsUndefined?: boolean;
-  /**
-  * Whether to emit warning when detecting empty import meta
-  * @default true
-  */
-  emptyImportMeta?: boolean;
-  /**
-  * Whether to emit warning when detecting cannot call namespace
-  * @default true
-  */
-  cannotCallNamespace?: boolean;
-  /**
-  * Whether to emit warning when detecting configuration field conflict
-  * @default true
-  */
-  configurationFieldConflict?: boolean;
-  /**
-  * Whether to emit warning when detecting prefer builtin feature
-  * @default true
-  */
-  preferBuiltinFeature?: boolean;
-  /**
-  * Whether to emit warning when detecting could not clean directory
-  * @default true
-  */
-  couldNotCleanDirectory?: boolean;
-  /**
-  * Whether to emit warning when detecting plugin timings
-  * @default true
-  */
-  pluginTimings?: boolean;
-}
-//#endregion
 //#region src/options/transform-options.d.ts
 interface TransformOptions extends Omit<TransformOptions$1, "sourceType" | "lang" | "cwd" | "sourcemap" | "define" | "inject" | "jsx"> {
   /**
@@ -1365,7 +1533,8 @@ type OptimizationOptions = {
   *
   * When enabled, constant values from imported modules will be inlined at their usage sites,
   * potentially reducing bundle size and improving runtime performance by eliminating variable lookups.
-  * **options**:
+  *
+  * **Options:**
   * - `true`: equivalent to `{ mode: 'all', pass: 1 }`, enabling constant inlining for all eligible constants with a single pass.
   * - `false`: Disable constant inlining
   * - `{ mode: 'smart' | 'all', pass?: number }`:
@@ -1379,7 +1548,7 @@ type OptimizationOptions = {
   *  - `mode: 'all'`: Inline all imported constants wherever they are used.
   *  - `pass`: Number of passes to perform for inlining constants.
   *
-  * **example**
+  * @example
   * ```js
   * // Input files:
   * // constants.js
@@ -1413,18 +1582,44 @@ type ChunkModulesOrder = "exec-order" | "module-id";
 type OnLogFunction = (level: LogLevel, log: RollupLog, defaultHandler: LogOrStringHandler) => void;
 type OnwarnFunction = (warning: RollupLog, defaultHandler: (warning: RollupLogWithString | (() => RollupLogWithString)) => void) => void;
 interface InputOptions {
+  /**
+  * Defines entries and location(s) of entry modules for the bundle. Relative paths are resolved based on the `cwd` option.
+  * {@include ./docs/input.md}
+  */
   input?: InputOption;
   plugins?: RolldownPluginOption;
+  /**
+  * Specifies which modules should be treated as external and not bundled. External modules will be left as import statements in the output.
+  * {@include ./docs/external.md}
+  */
   external?: ExternalOption;
   resolve?: {
     /**
+    * @example
+    * ```js
+    * resolve: {
+    *   alias: {
+    *     '@': '/src',
+    *     'utils': './src/utils',
+    *   }
+    * }
+    * ```
     * > [!WARNING]
     * > `resolve.alias` will not call `resolveId` hooks of other plugin.
     * > If you want to call `resolveId` hooks of other plugin, use `viteAliasPlugin` from `rolldown/experimental` instead.
     * > You could find more discussion in [this issue](https://github.com/rolldown/rolldown/issues/3615)
     */
     alias?: Record<string, string[] | string | false>;
+    /**
+    * Fields in package.json to check for aliased paths.
+    */
     aliasFields?: string[][];
+    /**
+    * Condition names to use when resolving exports in package.json. Defaults based on platform and import kind:
+    * - **Browser platform**: `["import", "browser", "default"]` for import statements, `["require", "browser", "default"]` for require() calls
+    * - **Node platform**: `["import", "node", "default"]` for import statements, `["require", "node", "default"]` for require() calls
+    * - **Neutral platform**: `["import", "default"]` for import statements, `["require", "default"]` for require() calls
+    */
     conditionNames?: string[];
     /**
     * Map of extensions to alternative extensions.
@@ -1433,17 +1628,46 @@ interface InputOptions {
     * You can achieve this by setting: `extensionAlias: { '.js': ['.ts', '.js'] }`.
     */
     extensionAlias?: Record<string, string[]>;
+    /**
+    * Fields in package.json to check for exports.
+    */
     exportsFields?: string[][];
+    /**
+    * Extensions to try when resolving files. These are tried in order from first to last.
+    * @default ['.tsx', '.ts', '.jsx', '.js', '.json']
+    */
     extensions?: string[];
+    /**
+    * Fields in package.json to check for entry points. Defaults based on platform:
+    * - **Node**: `['main', 'module']`
+    * - **Browser**: `['browser', 'module', 'main']`
+    * - **Neutral**: `[]` (relies on exports field)
+    */
     mainFields?: string[];
+    /**
+    * Filenames to try when resolving directories.
+    * @default ['index']
+    */
     mainFiles?: string[];
+    /**
+    * Directories to search for modules.
+    * @default ['node_modules']
+    */
     modules?: string[];
+    /**
+    * Whether to follow symlinks when resolving modules.
+    * @default true
+    */
     symlinks?: boolean;
     /**
     * @deprecated Use the top-level `tsconfig` option instead.
     */
     tsconfigFilename?: string;
   };
+  /**
+  * The working directory to use when resolving relative paths in the configuration.
+  * @default process.cwd()
+  */
   cwd?: string;
   /**
   * Expected platform where the code run.
@@ -1456,55 +1680,147 @@ interface InputOptions {
   * @default
   * - 'node' if the format is 'cjs'
   * - 'browser' for other formats
+  * {@include ./docs/platform.md}
   */
   platform?: "node" | "browser" | "neutral";
+  /**
+  * When `true`, creates shim variables for missing exports instead of throwing an error.
+  * @default false
+  * {@include ./docs/shim-missing-exports.md}
+  */
   shimMissingExports?: boolean;
+  /**
+  * Controls tree-shaking (dead code elimination). When `true`, unused code will be removed from the bundle to reduce bundle size.
+  * @default true
+  */
   treeshake?: boolean | TreeshakingOptions;
+  /**
+  * Controls the verbosity of console logging during the build.
+  * @default 'info'
+  */
   logLevel?: LogLevelOption;
+  /**
+  * Custom handler for logs. Called for each log message before it's written to the console.
+  */
   onLog?: OnLogFunction;
+  /**
+  * Custom handler for warnings during the build process.
+  * @deprecated
+  * :::: warning Deprecated
+  * This is a legacy API. Consider using `onLog` instead for better control over all log types.
+  * ::: details Migration to `onLog`
+  * To migrate from `onwarn` to `onLog`, check the `level` parameter to filter for
+  * warnings:
+  * ```js
+  * // Before: Using `onwarn`
+  * export default {
+  *   onwarn(warning, defaultHandler) {
+  *     // Suppress certain warnings
+  *     if (warning.code === 'CIRCULAR_DEPENDENCY') return;
+  *     // Handle other warnings with default behavior
+  *     defaultHandler(warning);
+  *   },
+  * };
+  * ```
+  * ```js
+  * // After: Using `onLog`
+  * export default {
+  *   onLog(level, log, defaultHandler) {
+  *     // Handle only warnings (same behavior as `onwarn`)
+  *     if (level === 'warn') {
+  *       // Suppress certain warnings
+  *       if (log.code === 'CIRCULAR_DEPENDENCY') return;
+  *       // Handle other warnings with default behavior
+  *       defaultHandler(level, log);
+  *     } else {
+  *       // Let other log levels pass through
+  *       defaultHandler(level, log);
+  *     }
+  *   },
+  * };
+  * ```
+  * :::
+  * ::::
+  */
   onwarn?: OnwarnFunction;
+  /**
+  * Maps file patterns to module types, controlling how files are processed. This is conceptually similar to esbuild's loader option, allowing you to specify how different file extensions should be handled.
+  */
   moduleTypes?: ModuleTypes;
+  /**
+  * Experimental features that may change in future releases and can introduce behavior change without a major version bump.
+  */
   experimental?: {
     /**
     * Lets modules be executed in the order they are declared.
     *
-    * - Type: `boolean`
-    * - Default: `false`
-    *
     * This is done by injecting runtime helpers to ensure that modules are executed in the order they are imported. External modules won't be affected.
     *
     * > [!WARNING]
     * > Enabling this option may negatively increase bundle size. It is recommended to use this option only when absolutely necessary.
+    * @default false
     */
     strictExecutionOrder?: boolean;
+    /**
+    * Disable live bindings for exported variables.
+    * @default false
+    */
     disableLiveBindings?: boolean;
+    /**
+    * Enable Vite compatible mode.
+    * @default false
+    */
     viteMode?: boolean;
+    /**
+    * When enabled, `new URL()` calls will be transformed to a stable asset URL which includes the updated name and content hash.
+    * It is necessary to pass `import.meta.url` as the second argument to the
+    * `new URL` constructor, otherwise no transform will be applied.
+    * :::warning
+    * JavaScript and TypeScript files referenced via `new URL('./file.js', import.meta.url)` or `new URL('./file.ts', import.meta.url)` will **not** be transformed or bundled. The file will be copied as-is, meaning TypeScript files remain untransformed and dependencies are not resolved.
+    *
+    * The expected behavior for JS/TS files is still being discussed and may
+    * change in future releases. See [#7258](https://github.com/rolldown/rolldown/issues/7258) for more context.
+    * :::
+    * @example
+    * ```js
+    * // main.js
+    * const url = new URL('./styles.css', import.meta.url);
+    * console.log(url);
+    *
+    * // Example output after bundling WITHOUT the option (default)
+    * const url = new URL('./styles.css', import.meta.url);
+    * console.log(url);
+    *
+    * // Example output after bundling WITH `experimental.resolveNewUrlToAsset` set to `true`
+    * const url = new URL('assets/styles-CjdrdY7X.css', import.meta.url);
+    * console.log(url);
+    * ```
+    * @default false
+    */
     resolveNewUrlToAsset?: boolean;
     devMode?: DevModeOptions;
     /**
-    * Control which order should use when rendering modules in chunk
-    *
-    * - Type: `'exec-order' | 'module-id'
-    * - Default: `'exec-order'`
+    * Control which order should use when rendering modules in chunk.
     *
+    * Available options:
     * - `exec-order`: Almost equivalent to the topological order of the module graph, but specially handling when module graph has cycle.
     * - `module-id`: This is more friendly for gzip compression, especially for some javascript static asset lib (e.g. icon library)
     * > [!NOTE]
     * > Try to sort the modules by their module id if possible(Since rolldown scope hoist all modules in the chunk, we only try to sort those modules by module id if we could ensure runtime behavior is correct after sorting).
+    * @default 'exec-order'
     */
     chunkModulesOrder?: ChunkModulesOrder;
     /**
     * Attach debug information to the output bundle.
     *
-    * - Type: `'none' | 'simple' | 'full'`
-    * - Default: `'simple'`
-    *
+    * Available modes:
     * - `none`: No debug information is attached.
     * - `simple`: Attach comments indicating which files the bundled code comes from. These comments could be removed by the minifier.
     * - `full`: Attach detailed debug information to the output bundle. These comments are using legal comment syntax, so they won't be removed by the minifier.
     *
     * > [!WARNING]
     * > You shouldn't use `full` in the production build.
+    * @default 'simple'
     */
     attachDebugInfo?: AttachDebugOptions;
     /**
@@ -1518,8 +1834,7 @@ interface InputOptions {
     * (default `"/"`) can be applied to all paths. The resulting JSON is a valid import map and can be
     * directly injected into HTML via `<script type="importmap">`.
     *
-    * Example configuration snippet:
-    *
+    * @example
     * ```js
     * {
     *   experimental: {
@@ -1551,31 +1866,38 @@ interface InputOptions {
     * }
     * ```
     *
-    * > [!NOTE]
+    * > [!TIP]
     * > If you want to learn more, you can check out the example here: [examples/chunk-import-map](https://github.com/rolldown/rolldown/tree/main/examples/chunk-import-map)
+    * @default false
     */
     chunkImportMap?: boolean | {
       baseUrl?: string;
       fileName?: string;
     };
+    /**
+    * Enable on-demand wrapping of modules.
+    * @default false
+    */
     onDemandWrapping?: boolean;
     /**
-    * Required to be used with `watch` mode.
+    * Enable incremental build support. Required to be used with `watch` mode.
+    * @default false
     */
     incrementalBuild?: boolean;
+    /**
+    * Enable high-resolution source maps for transform operations.
+    * @default false
+    */
     transformHiresSourcemap?: boolean | "boundary";
     /**
     * Use native Rust implementation of MagicString for source map generation.
     *
-    * - Type: `boolean`
-    * - Default: `false`
-    *
     * [MagicString](https://github.com/rich-harris/magic-string) is a JavaScript library commonly used by bundlers
     * for string manipulation and source map generation. When enabled, rolldown will use a native Rust
     * implementation of MagicString instead of the JavaScript version, providing significantly better performance
     * during source map generation and code transformation.
     *
-    * ## Benefits
+    * **Benefits**
     *
     * - **Improved Performance**: The native Rust implementation is typically faster than the JavaScript version,
     *   especially for large codebases with extensive source maps.
@@ -1584,8 +1906,7 @@ interface InputOptions {
     *   reduce overall build times when working with JavaScript transform hooks.
     * - **Better Integration**: Seamless integration with rolldown's native Rust architecture.
     *
-    * ## Example
-    *
+    * @example
     * ```js
     * export default {
     *   experimental: {
@@ -1601,8 +1922,22 @@ interface InputOptions {
     * > This is an experimental feature. While it aims to provide identical behavior to the JavaScript
     * > implementation, there may be edge cases. Please report any discrepancies you encounter.
     * > For a complete working example, see [examples/native-magic-string](https://github.com/rolldown/rolldown/tree/main/examples/native-magic-string)
+    * @default false
     */
     nativeMagicString?: boolean;
+    /**
+    * Control whether to optimize chunks by allowing entry chunks to have different exports than the underlying entry module.
+    * This optimization can reduce the number of generated chunks.
+    *
+    * When enabled, rolldown will try to insert common modules directly into existing chunks rather than creating
+    * separate chunks for them, which can result in fewer output files and better performance.
+    *
+    * This optimization is automatically disabled when any module uses top-level await (TLA) or contains TLA dependencies,
+    * as it could affect execution order guarantees.
+    *
+    * @default true
+    */
+    chunkOptimization?: boolean;
   };
   /**
   * Configure how the code is transformed. This process happens after the `transform` hook.
@@ -1623,33 +1958,52 @@ interface InputOptions {
   */
   transform?: TransformOptions;
   watch?: WatcherOptions | false;
+  /**
+  * Controls which warnings are emitted during the build process. Each option can be set to `true` (emit warning) or `false` (suppress warning).
+  */
   checks?: ChecksOptions;
   makeAbsoluteExternalsRelative?: MakeAbsoluteExternalsRelative;
-  debug?: {
+  devtools?: {
     sessionId?: string;
   };
+  /**
+  * Controls how entry chunk exports are preserved. This determines whether Rolldown needs to create facade chunks (additional wrapper chunks) to maintain the exact export signatures of entry modules, or whether it can combine entry modules with other chunks for optimization.
+  * @default 'strict'
+  * {@include ./docs/preserve-entry-signatures.md}
+  */
   preserveEntrySignatures?: false | "strict" | "allow-extension" | "exports-only";
+  /**
+  * Configure optimization features for the bundler.
+  */
   optimization?: OptimizationOptions;
+  /**
+  * The value of `this` at the top level of each output chunk. For IIFE and UMD formats, this defaults to `'window'` or `'global'` depending on the platform.
+  * @example
+  * **Set custom context**
+  * ```js
+  * export default {
+  *   context: 'globalThis',
+  *   output: {
+  *     format: 'iife',
+  *   },
+  * };
+  * ```
+  * **Use window for browser builds**
+  * ```js
+  * export default {
+  *   context: 'window',
+  *   platform: 'browser',
+  *   output: {
+  *     format: 'iife',
+  *   },
+  * };
+  * ```
+  * {@include ./docs/context.md}
+  */
   context?: string;
   /**
   * Configures TypeScript configuration file resolution and usage.
-  *
-  * ## Options
-  *
-  * - `true`: Auto-discovery mode (similar to Vite). For each module, both resolver and transformer
-  *   will find the nearest tsconfig.json. If the tsconfig has `references`, the file extension is
-  *   allowed, and the tsconfig's `include`/`exclude` patterns don't match the file, the referenced
-  *   tsconfigs will be searched for a match. Falls back to the original tsconfig if no match is found.
-  * - `string`: Path to a specific tsconfig.json file (relative to cwd or absolute path).
-  *
-  * ## What's used from tsconfig
-  *
-  * - **Resolver**: Uses `compilerOptions.paths` and `compilerOptions.baseUrl` for path mapping
-  * - **Transformer**: Uses select compiler options (jsx, decorators, typescript, etc.)
-  *
-  * > [!NOTE]
-  * > Priority: Top-level `transform` options always take precedence over tsconfig settings.
-  *
+  * {@include ./docs/tsconfig.md}
   * @default undefined (no tsconfig resolution)
   */
   tsconfig?: true | string;
@@ -1672,4 +2026,4 @@ declare function defineConfig(config: RolldownOptions[]): RolldownOptions[];
 declare function defineConfig(config: RolldownOptionsFunction): RolldownOptionsFunction;
 declare function defineConfig(config: ConfigExport): ConfigExport;
 //#endregion
-export { RolldownFsModule as $, BuiltinPlugin as A, RolldownOutput as At, EmittedPrebuiltChunk as B, ResolveIdResult as C, MaybePromise as Ct, SourceDescription as D, OutputChunk as Dt, RolldownPluginOption as E, OutputAsset as Et, OutputBundle as F, MinimalPluginContext as G, PluginContext as H, TreeshakingOptions as I, HookFilter as J, PluginContextMeta as K, TransformPluginContext as L, ExistingRawSourceMap as M, freeExternalMemory as Mt, SourceMapInput as N, ModuleInfo as Nt, TransformResult as O, RenderedChunk as Ot, RolldownOptionsFunction as P, SourcemapIgnoreListOption as Pt, RolldownFileStats as Q, EmittedAsset as R, ResolveIdExtraOptions as S, PreRenderedAsset as St, RolldownPlugin as T, StringOrRegExp as Tt, DefineParallelPluginResult as U, GetModuleInfo as V, defineParallelPlugin as W, BufferEncoding as X, ModuleTypeFilter as Y, RolldownDirectoryEntry as Z, ModuleType as _, GeneratedCodePreset as _t, InputOption as a, watch as at, PartialResolvedId as b, ModuleFormat as bt, OptimizationOptions as c, WatchOptions as ct, CustomPluginOptions as d, BuildOptions as dt, InternalModuleFormat as et, FunctionPluginHooks as f, build as ft, ModuleOptions as g, GeneratedCodeOptions as gt, LoadResult as h, ChunkingContext as ht, ExternalOption as i, WarningHandlerWithDefault as it, VERSION as j, SourceMap as jt, withFilter as k, RenderedModule as kt, WatcherOptions as l, rolldown as lt, ImportKind as m, ChunkFileNamesFunction as mt, ConfigExport as n, NormalizedInputOptions as nt, InputOptions as o, RolldownWatcher as ot, HookFilterExtension as p, AddonFunction as pt, GeneralHookFilter as q, RolldownOptions as r, LoggingFunction as rt, ModuleTypes as s, RolldownWatcherEvent as st, defineConfig as t, NormalizedOutputOptions as tt, AsyncPluginHooks as u, RolldownBuild as ut, ObjectHook as v, GlobalsFunction as vt, ResolvedId as w, PartialNull as wt, Plugin as x, OutputOptions as xt, ParallelPluginHooks as y, MinifyOptions as yt, EmittedFile as z };
+export { RolldownFsModule as $, BuiltinPlugin as A, RenderedModule as At, EmittedPrebuiltChunk as B, ResolveIdResult as C, PreRenderedAsset as Ct, SourceDescription as D, OutputAsset as Dt, RolldownPluginOption as E, StringOrRegExp as Et, OutputBundle as F, SourcemapIgnoreListOption as Ft, MinimalPluginContext as G, PluginContext as H, TreeshakingOptions as I, HookFilter as J, PluginContextMeta as K, TransformPluginContext as L, ExistingRawSourceMap as M, SourceMap as Mt, SourceMapInput as N, freeExternalMemory as Nt, TransformResult as O, OutputChunk as Ot, RolldownOptionsFunction as P, ModuleInfo as Pt, RolldownFileStats as Q, EmittedAsset as R, ResolveIdExtraOptions as S, OutputOptions as St, RolldownPlugin as T, PartialNull as Tt, DefineParallelPluginResult as U, GetModuleInfo as V, defineParallelPlugin as W, BufferEncoding as X, ModuleTypeFilter as Y, RolldownDirectoryEntry as Z, ModuleType as _, GeneratedCodeOptions as _t, InputOption as a, WarningHandlerWithDefault as at, PartialResolvedId as b, MinifyOptions as bt, OptimizationOptions as c, RolldownWatcherEvent as ct, CustomPluginOptions as d, RolldownBuild as dt, InternalModuleFormat as et, FunctionPluginHooks as f, BuildOptions as ft, ModuleOptions as g, ChunkingContext as gt, LoadResult as h, ChunkFileNamesFunction as ht, ExternalOption as i, LoggingFunction as it, VERSION as j, RolldownOutput as jt, withFilter as k, RenderedChunk as kt, WatcherOptions as l, WatchOptions as lt, ImportKind as m, AddonFunction as mt, ConfigExport as n, NormalizedInputOptions as nt, InputOptions as o, watch as ot, HookFilterExtension as p, build as pt, GeneralHookFilter as q, RolldownOptions as r, ChecksOptions as rt, ModuleTypes as s, RolldownWatcher as st, defineConfig as t, NormalizedOutputOptions as tt, AsyncPluginHooks as u, rolldown as ut, ObjectHook as v, GeneratedCodePreset as vt, ResolvedId as w, MaybePromise as wt, Plugin as x, ModuleFormat as xt, ParallelPluginHooks as y, GlobalsFunction as yt, EmittedFile as z };