@rollipop/rolldown 1.0.24 → 1.0.26

package/dist/experimental-index.d.mts

@@ -1,8 +1,7 @@
-import { $ as moduleRunnerTransform, A as BindingViteTransformPluginConfig, G as ResolverFactory, N as IsolatedDeclarationsOptions, P as IsolatedDeclarationsResult, Q as isolatedDeclarationSync, R as NapiResolveOptions, T as BindingViteManifestPluginConfig, W as ResolveResult, X as clearCacheById, Y as clearCache, Z as isolatedDeclaration, f as BindingRebuildStrategy, g as BindingRollipopReactRefreshWrapperPluginConfig, h as BindingRollipopReactNativeTransformResult, i as BindingClientHmrUpdate, n as BindingBundleAnalyzerPluginConfig, r as BindingBundleState, v as BindingTsconfigCompilerOptions, y as BindingTsconfigRawOptions } from "./shared/binding-FraDreAW.mjs";
-import { Bt as OutputOptions, F as BuiltinPlugin, Q as defineParallelPlugin, Wt as StringOrRegExp, Yt as RolldownOutput, Zt as freeExternalMemory, l as InputOptions, lt as NormalizedOutputOptions } from "./shared/define-config-oNOGrLUX.mjs";
-import { a as MinifyOptions$1, c as minifySync$1, d as parse$1, f as parseSync$1, i as transformSync$1, l as ParseResult$1, m as resolveTsconfig, n as TransformResult$1, o as MinifyResult$1, p as TsconfigCache$1, r as transform$1, s as minify$1, t as TransformOptions$1, u as ParserOptions$1 } from "./shared/transform-DmrnpNrQ.mjs";
-import { a as viteDynamicImportVarsPlugin, c as viteLoadFallbackPlugin, d as viteReporterPlugin, f as viteResolvePlugin, i as viteBuildImportAnalysisPlugin, l as viteModulePreloadPolyfillPlugin, n as isolatedDeclarationPlugin, o as viteImportGlobPlugin, p as viteWebWorkerPostPlugin, r as oxcRuntimePlugin, s as viteJsonPlugin, u as viteReactRefreshWrapperPlugin } from "./shared/constructors-CXtPAgZN.mjs";
-
+import { $ as isolatedDeclarationSync, E as BindingViteManifestPluginConfig, F as IsolatedDeclarationsResult, G as ResolveResult, K as ResolverFactory, P as IsolatedDeclarationsOptions, Q as isolatedDeclaration, X as clearCache, Z as clearCacheById, _ as BindingRollipopReactRefreshWrapperPluginConfig, b as BindingTsconfigRawOptions, et as moduleRunnerTransform, g as BindingRollipopReactNativeTransformResult, i as BindingClientHmrUpdate, j as BindingViteTransformPluginConfig, n as BindingBundleAnalyzerPluginConfig, p as BindingRebuildStrategy, r as BindingBundleState, u as BindingLazyChunkOutput, y as BindingTsconfigCompilerOptions, z as NapiResolveOptions } from "./shared/binding-We_IfeZk.mjs";
+import { $ as defineParallelPlugin, Gt as StringOrRegExp, I as BuiltinPlugin, Qt as freeExternalMemory, Vt as OutputOptions, Xt as RolldownOutput, l as InputOptions, ut as NormalizedOutputOptions } from "./shared/define-config-thpMQ05a.mjs";
+import { a as MinifyOptions$1, c as minifySync$1, d as parse$1, f as parseSync$1, i as transformSync$1, l as ParseResult$1, m as resolveTsconfig, n as TransformResult$1, o as MinifyResult$1, p as TsconfigCache$1, r as transform$1, s as minify$1, t as TransformOptions$1, u as ParserOptions$1 } from "./shared/transform-CsZGbS4Q.mjs";
+import { a as viteDynamicImportVarsPlugin, c as viteLoadFallbackPlugin, d as viteReporterPlugin, f as viteResolvePlugin, i as viteBuildImportAnalysisPlugin, l as viteModulePreloadPolyfillPlugin, n as isolatedDeclarationPlugin, o as viteImportGlobPlugin, p as viteWebWorkerPostPlugin, r as oxcRuntimePlugin, s as viteJsonPlugin, u as viteReactRefreshWrapperPlugin } from "./shared/constructors-BIHQ8UmW.mjs";
 //#region src/api/dev/dev-options.d.ts
 type DevOnHmrUpdates = (result: Error | {
   updates: BindingClientHmrUpdate[];
@@ -12,80 +11,87 @@ type DevOnOutput = (result: Error | RolldownOutput) => void | Promise<void>;
 type DevOnAdditionalAssets = (output: RolldownOutput) => void | Promise<void>;
 interface DevWatchOptions {
   /**
-  * If `true`, files are not written to disk.
-  * @default false
-  */
+   * If `false`, no file system watcher is started, so file changes are never
+   * picked up and no rebuild or HMR update is triggered on their own.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * If `true`, files are not written to disk.
+   * @default false
+   */
   skipWrite?: boolean;
   /**
-  * If `true`, use polling instead of native file system events for watching.
-  * @default false
-  */
+   * If `true`, use polling instead of native file system events for watching.
+   * @default false
+   */
   usePolling?: boolean;
   /**
-  * Poll interval in milliseconds (only used when usePolling is true).
-  * @default 100
-  */
+   * Poll interval in milliseconds (only used when usePolling is true).
+   * @default 100
+   */
   pollInterval?: number;
   /**
-  * If `true`, use debounced watcher. If `false`, use non-debounced watcher for immediate responses.
-  * @default true
-  */
+   * If `true`, use debounced watcher. If `false`, use non-debounced watcher for immediate responses.
+   * @default true
+   */
   useDebounce?: boolean;
   /**
-  * Debounce duration in milliseconds (only used when useDebounce is true).
-  * @default 10
-  */
+   * Debounce duration in milliseconds (only used when useDebounce is true).
+   * @default 10
+   */
   debounceDuration?: number;
   /**
-  * Whether to compare file contents for poll-based watchers (only used when usePolling is true).
-  * When enabled, poll watchers will check file contents to determine if they actually changed.
-  * @default false
-  */
+   * Whether to compare file contents for poll-based watchers (only used when usePolling is true).
+   * When enabled, poll watchers will check file contents to determine if they actually changed.
+   * @default false
+   */
   compareContentsForPolling?: boolean;
   /**
-  * Tick rate in milliseconds for debounced watchers (only used when useDebounce is true).
-  * Controls how frequently the debouncer checks for events to process.
-  * When not specified, the debouncer will auto-select an appropriate tick rate (1/4 of the debounce duration).
-  * @default undefined (auto-select)
-  */
+   * Tick rate in milliseconds for debounced watchers (only used when useDebounce is true).
+   * Controls how frequently the debouncer checks for events to process.
+   * When not specified, the debouncer will auto-select an appropriate tick rate (1/4 of the debounce duration).
+   * @default undefined (auto-select)
+   */
   debounceTickRate?: number;
   /**
-  * Filter to limit which discovered files are registered with the file watcher.
-  *
-  * Strings are treated as glob patterns.
-  *
-  * @default []
-  */
+   * Filter to limit which discovered files are registered with the file watcher.
+   *
+   * Strings are treated as glob patterns.
+   *
+   * @default []
+   */
   include?: StringOrRegExp | StringOrRegExp[];
   /**
-  * Filter to prevent discovered files from being registered with the file watcher.
-  *
-  * Strings are treated as glob patterns.
-  *
-  * @default []
-  */
+   * Filter to prevent discovered files from being registered with the file watcher.
+   *
+   * Strings are treated as glob patterns.
+   *
+   * @default []
+   */
   exclude?: StringOrRegExp | StringOrRegExp[];
 }
 interface DevOptions {
   onHmrUpdates?: DevOnHmrUpdates;
   onOutput?: DevOnOutput;
   /**
-  * Called with assets emitted while generating an HMR patch or compiling a
-  * lazy entry (e.g. an image newly imported by the changed/lazy module).
-  *
-  * These never go through {@link onOutput}, so a consumer that serves built
-  * files (e.g. Vite's bundled dev server) must register this to receive them
-  * and write them to its in-memory file store before the client requests them.
-  */
+   * Called with assets emitted while generating an HMR patch or compiling a
+   * lazy entry (e.g. an image newly imported by the changed/lazy module).
+   *
+   * These never go through {@link onOutput}, so a consumer that serves built
+   * files (e.g. Vite's bundled dev server) must register this to receive them
+   * and write them to its in-memory file store before the client requests them.
+   */
   onAdditionalAssets?: DevOnAdditionalAssets;
   /**
-  * Strategy for triggering rebuilds after HMR updates.
-  * - `'always'`: Always trigger a rebuild after HMR updates
-  * - `'auto'`: Trigger rebuild only if HMR updates contain full reload updates
-  * - `'never'`: Never trigger rebuild after HMR updates (default)
-  * @default 'auto'
-  */
-  rebuildStrategy?: "always" | "auto" | "never";
+   * Strategy for triggering rebuilds after HMR updates.
+   * - `'always'`: Always trigger a rebuild after HMR updates
+   * - `'never'`: Never trigger rebuild after HMR updates. The server no longer
+   *   decides full reloads, so there is no `'auto'` upgrade anymore; pull fresh
+   *   bundle output explicitly (e.g. `ensureLatestBuildOutput`) when needed.
+   * @default 'never'
+   */
+  rebuildStrategy?: "always" | "never";
   watch?: DevWatchOptions;
 }
 //#endregion
@@ -99,22 +105,31 @@ declare class DevEngine {
   getBundleState(): Promise<BindingBundleState>;
   ensureLatestBuildOutput(): Promise<void>;
   triggerFullBuild(): void;
-  invalidate(file: string, firstInvalidatedBy?: string): Promise<BindingClientHmrUpdate[]>;
-  registerModules(clientId: string, modules: string[]): Promise<void>;
+  /**
+   * Client-connect signal (the clientId hello): creates the per-client session
+   * with an empty ship map. Reconnects arrive as fresh clientIds.
+   */
+  registerClient(clientId: string): Promise<void>;
+  /**
+   * Delivery notification from the serving middleware: the response for
+   * `filename` completed, so record its modules as shipped to that client.
+   */
+  notifyPayloadDelivered(filename: string): Promise<void>;
   removeClient(clientId: string): Promise<void>;
   close(): Promise<void>;
   /**
-  * Compile a lazy entry module and return HMR-style patch code.
-  *
-  * This is called when a dynamically imported module is first requested at runtime.
-  * The module was previously stubbed with a proxy, and now we need to compile the
-  * actual module and its dependencies.
-  *
-  * @param moduleId - The absolute file path of the module to compile
-  * @param clientId - The client ID requesting this compilation
-  * @returns The compiled JavaScript code as a string (HMR patch format)
-  */
-  compileEntry(moduleId: string, clientId: string): Promise<string>;
+   * Compile a lazy entry module and return HMR-style patch code.
+   *
+   * This is called when a dynamically imported module is first requested at runtime.
+   * The module was previously stubbed with a proxy, and now we need to compile the
+   * actual module and its dependencies.
+   *
+   * @param moduleId - The absolute file path of the module to compile
+   * @param clientId - The client ID requesting this compilation
+   * @returns The compiled chunk: its code plus the filename whose delivery the
+   * serving middleware reports via {@link notifyPayloadDelivered}
+   */
+  compileEntry(moduleId: string, clientId: string): Promise<BindingLazyChunkOutput>;
 }
 //#endregion
 //#region src/api/dev/index.d.ts
@@ -122,20 +137,20 @@ declare const dev: typeof DevEngine.create;
 //#endregion
 //#region src/api/experimental.d.ts
 /**
-* This is an experimental API. Its behavior may change in the future.
-*
-* - Calling this API will only execute the `scan/build` stage of rolldown.
-* - `scan` will clean up all resources automatically, but if you want to ensure timely cleanup, you need to wait for the returned promise to resolve.
-*
-* @example To ensure cleanup of resources, use the returned promise to wait for the scan to complete.
-* ```ts
-* import { scan } from '@rollipop/rolldown/api/experimental';
-*
-* const cleanupPromise = await scan(...);
-* await cleanupPromise;
-* // Now all resources have been cleaned up.
-* ```
-*/
+ * This is an experimental API. Its behavior may change in the future.
+ *
+ * - Calling this API will only execute the `scan/build` stage of rolldown.
+ * - `scan` will clean up all resources automatically, but if you want to ensure timely cleanup, you need to wait for the returned promise to resolve.
+ *
+ * @example To ensure cleanup of resources, use the returned promise to wait for the scan to complete.
+ * ```ts
+ * import { scan } from '@rollipop/rolldown/api/experimental';
+ *
+ * const cleanupPromise = await scan(...);
+ * await cleanupPromise;
+ * // Now all resources have been cleaned up.
+ * ```
+ */
 declare const scan: (rawInputOptions: InputOptions, rawOutputOptions?: {}) => Promise<Promise<void>>;
 //#endregion
 //#region src/builtin-plugin/alias-plugin.d.ts
@@ -149,53 +164,53 @@ declare function viteAliasPlugin(config: ViteAliasPluginConfig): BuiltinPlugin;
 //#endregion
 //#region src/builtin-plugin/bundle-analyzer-plugin.d.ts
 /**
-* A plugin that analyzes bundle composition and generates detailed reports.
-*
-* The plugin outputs a file containing detailed information about:
-* - All chunks and their relationships
-* - Modules bundled in each chunk
-* - Import dependencies between chunks
-* - Reachable modules from each entry point
-*
-* @example
-* ```js
-* import { bundleAnalyzerPlugin } from '@rollipop/rolldown/experimental';
-*
-* export default {
-*   plugins: [
-*     bundleAnalyzerPlugin()
-*   ]
-* }
-* ```
-*
-* @example
-* **Custom filename**
-* ```js
-* import { bundleAnalyzerPlugin } from '@rollipop/rolldown/experimental';
-*
-* export default {
-*   plugins: [
-*     bundleAnalyzerPlugin({
-*       fileName: 'bundle-analysis.json'
-*     })
-*   ]
-* }
-* ```
-*
-* @example
-* **LLM-friendly markdown output**
-* ```js
-* import { bundleAnalyzerPlugin } from '@rollipop/rolldown/experimental';
-*
-* export default {
-*   plugins: [
-*     bundleAnalyzerPlugin({
-*       format: 'md'
-*     })
-*   ]
-* }
-* ```
-*/
+ * A plugin that analyzes bundle composition and generates detailed reports.
+ *
+ * The plugin outputs a file containing detailed information about:
+ * - All chunks and their relationships
+ * - Modules bundled in each chunk
+ * - Import dependencies between chunks
+ * - Reachable modules from each entry point
+ *
+ * @example
+ * ```js
+ * import { bundleAnalyzerPlugin } from '@rollipop/rolldown/experimental';
+ *
+ * export default {
+ *   plugins: [
+ *     bundleAnalyzerPlugin()
+ *   ]
+ * }
+ * ```
+ *
+ * @example
+ * **Custom filename**
+ * ```js
+ * import { bundleAnalyzerPlugin } from '@rollipop/rolldown/experimental';
+ *
+ * export default {
+ *   plugins: [
+ *     bundleAnalyzerPlugin({
+ *       fileName: 'bundle-analysis.json'
+ *     })
+ *   ]
+ * }
+ * ```
+ *
+ * @example
+ * **LLM-friendly markdown output**
+ * ```js
+ * import { bundleAnalyzerPlugin } from '@rollipop/rolldown/experimental';
+ *
+ * export default {
+ *   plugins: [
+ *     bundleAnalyzerPlugin({
+ *       format: 'md'
+ *     })
+ *   ]
+ * }
+ * ```
+ */
 declare function bundleAnalyzerPlugin(config?: BindingBundleAnalyzerPluginConfig): BuiltinPlugin;
 //#endregion
 //#region src/builtin-plugin/transform-plugin.d.ts
@@ -221,11 +236,11 @@ declare function rollipopReactRefreshWrapperPlugin(config: BindingRollipopReactR
 type RollipopReactNativeRuntimeTarget = "hermes" | "hermes-v1";
 type RollipopReactNativeModuleType = "unambiguous" | "commonjs";
 /**
-* `react-native-worklets` transform configuration. Field semantics mirror
-* the upstream Babel plugin's `WorkletsOptions`, minus the rolldown-managed
-* fields (`filename`, `cwd`). Pass `worklets: {}` to opt in with defaults;
-* omit the field entirely to skip the visitor.
-*/
+ * `react-native-worklets` transform configuration. Field semantics mirror
+ * the upstream Babel plugin's `WorkletsOptions`, minus the rolldown-managed
+ * fields (`filename`, `cwd`). Pass `worklets: {}` to opt in with defaults;
+ * omit the field entirely to skip the visitor.
+ */
 interface RollipopReactNativeWorkletsConfig {
   /** Identifiers treated as globals — never captured into worklet closures. */
   globals?: string[];
@@ -249,29 +264,29 @@ interface RollipopReactNativeWorkletsConfig {
   pluginVersion?: string;
 }
 /**
-* Flow handling configuration. Mirrors Babel's
-* `@babel/plugin-transform-flow-strip-types` semantics.
-*/
+ * Flow handling configuration. Mirrors Babel's
+ * `@babel/plugin-transform-flow-strip-types` semantics.
+ */
 interface RollipopReactNativeFlowConfig {
   /**
-  * When `true`, only files containing `@flow` or `@noflow` directive comments are parsed as Flow (Babel `requireDirective: true`).
-  * When `false` (default), every JS module is parsed as Flow regardless of directive — matches Metro / Babel default behavior.
-  */
+   * When `true`, only files containing `@flow` or `@noflow` directive comments are parsed as Flow (Babel `requireDirective: true`).
+   * When `false` (default), every JS module is parsed as Flow regardless of directive — matches Metro / Babel default behavior.
+   */
   requireDirective?: boolean;
 }
 /**
-* React (JSX) transform configuration. Mirrors Babel's
-* `@babel/plugin-transform-react-jsx`, minus dev-server-only knobs
-* (fast refresh) — those belong to a bundler, not a precompile/test path.
-*/
+ * React (JSX) transform configuration. Mirrors Babel's
+ * `@babel/plugin-transform-react-jsx`, minus dev-server-only knobs
+ * (fast refresh) — those belong to a bundler, not a precompile/test path.
+ */
 interface RollipopReactNativeReactConfig {
   /**
-  * JSX runtime.
-  * - `"Preserve"` (default): leave JSX untouched — downstream bundler owns it.
-  * - `"Automatic"`: compile to `_jsx` / `_jsxs` / `Fragment` imports from
-  *   `react/jsx-runtime` (or `react/jsx-dev-runtime` when `development`).
-  * - `"Classic"`: compile to `React.createElement` calls.
-  */
+   * JSX runtime.
+   * - `"Preserve"` (default): leave JSX untouched — downstream bundler owns it.
+   * - `"Automatic"`: compile to `_jsx` / `_jsxs` / `Fragment` imports from
+   *   `react/jsx-runtime` (or `react/jsx-dev-runtime` when `development`).
+   * - `"Classic"`: compile to `React.createElement` calls.
+   */
   runtime?: "Preserve" | "Automatic" | "Classic";
   /** Import source for the automatic runtime. Defaults to `"react"`. */
   importSource?: string;
@@ -282,31 +297,31 @@ interface RollipopReactNativeReactConfig {
   /** Throw on XML namespace prefixes (e.g. `<svg:path>`). */
   throwIfNamespace?: boolean;
   /**
-  * When `true`, emits the development runtime (`__source` / `__self` debug
-  * props for automatic, `react/jsx-dev-runtime` import).
-  */
+   * When `true`, emits the development runtime (`__source` / `__self` debug
+   * props for automatic, `react/jsx-dev-runtime` import).
+   */
   development?: boolean;
 }
 interface RollipopReactNativeModuleConfig {
   /**
-  * Module transform type.
-  * - `"unambiguous"` (default): preserve the input module shape.
-  * - `"commonjs"`: transform ESM syntax to CommonJS.
-  */
+   * Module transform type.
+   * - `"unambiguous"` (default): preserve the input module shape.
+   * - `"commonjs"`: transform ESM syntax to CommonJS.
+   */
   type?: RollipopReactNativeModuleType;
 }
 /**
-* SWC pipeline configuration — wasm plugins, helper emission, React transform.
-*/
+ * SWC pipeline configuration — wasm plugins, helper emission, React transform.
+ */
 interface RollipopReactNativeSwcConfig {
   /** SWC `.wasm` plugins to load. Each entry is `[pluginPath, pluginConfig]`. */
   plugins?: [string, Record<string, unknown>][];
   /**
-  * When `true`, runtime helpers are emitted as imports of `@swc/helpers` so
-  * a downstream bundler can deduplicate them. When `false` (default), helpers
-  * are inlined into each transformed file — preferred when feeding the
-  * output to a runtime (e.g. jest) without a bundle step in between.
-  */
+   * When `true`, runtime helpers are emitted as imports of `@swc/helpers` so
+   * a downstream bundler can deduplicate them. When `false` (default), helpers
+   * are inlined into each transformed file — preferred when feeding the
+   * output to a runtime (e.g. jest) without a bundle step in between.
+   */
   externalHelpers?: boolean;
   /** React (JSX) transform configuration. Skipped when `runtime` is `"Preserve"`. */
   react?: RollipopReactNativeReactConfig;
@@ -318,9 +333,9 @@ interface RollipopReactNativeSwcConfig {
 interface RollipopReactNativePluginConfig {
   runtimeTarget?: RollipopReactNativeRuntimeTarget;
   /**
-  * The name of the `env` to use when loading configs and plugins. Defaults
-  * to the value of `SWC_ENV`, or else `NODE_ENV`, or else `"development"`.
-  */
+   * The name of the `env` to use when loading configs and plugins. Defaults
+   * to the value of `SWC_ENV`, or else `NODE_ENV`, or else `"development"`.
+   */
   envName?: string;
   /** `react-native-worklets` transform. Visitor is skipped when omitted. */
   worklets?: RollipopReactNativeWorkletsConfig;
@@ -335,18 +350,18 @@ declare function rollipopReactNativePlugin(config?: RollipopReactNativePluginCon
 type RollipopReactNativeTransformerConfig = RollipopReactNativePluginConfig;
 type RollipopReactNativeTransformResult = BindingRollipopReactNativeTransformResult;
 /**
-* Standalone React Native SWC transform pipeline.
-*
-* Mirrors the behavior of {@link rollipopReactNativePlugin} but can be
-* invoked directly outside of a rolldown build (e.g. from Metro adapters,
-* test harnesses, or precompile steps). SWC `.wasm` plugins listed in the
-* config are read from disk and compiled exactly once at construction
-* time — call `transform` / `transformSync` repeatedly without reloading.
-*
-* All options pass through unchanged — `swc.externalHelpers` defaults to
-* `false` (helpers inlined) and `swc.react.runtime` to `"Preserve"`, both
-* matching the underlying Rust defaults. Set them explicitly when needed.
-*/
+ * Standalone React Native SWC transform pipeline.
+ *
+ * Mirrors the behavior of {@link rollipopReactNativePlugin} but can be
+ * invoked directly outside of a rolldown build (e.g. from Metro adapters,
+ * test harnesses, or precompile steps). SWC `.wasm` plugins listed in the
+ * config are read from disk and compiled exactly once at construction
+ * time — call `transform` / `transformSync` repeatedly without reloading.
+ *
+ * All options pass through unchanged — `swc.externalHelpers` defaults to
+ * `false` (helpers inlined) and `swc.react.runtime` to `"Preserve"`, both
+ * matching the underlying Rust defaults. Set them explicitly when needed.
+ */
 declare class RollipopReactNativeTransformer {
   private inner;
   constructor(config?: RollipopReactNativeTransformerConfig);
@@ -356,32 +371,32 @@ declare class RollipopReactNativeTransformer {
 //#endregion
 //#region src/experimental-index.d.ts
 /**
-* In-memory file system for browser builds.
-*
-* This is a re-export of the {@link https://github.com/streamich/memfs | memfs} package used by the WASI runtime.
-* It allows you to read and write files to a virtual filesystem when using rolldown in browser environments.
-*
-* - `fs`: A Node.js-compatible filesystem API (`IFs` from memfs)
-* - `volume`: The underlying `Volume` instance that stores the filesystem state
-*
-* Returns `undefined` in Node.js builds (only available in browser builds via `@rolldown/browser`).
-*
-* @example
-* ```typescript
-* import { memfs } from '@rollipop/rolldown/experimental';
-*
-* // Write files to virtual filesystem before bundling
-* memfs?.volume.fromJSON({
-*   '/src/index.js': 'export const foo = 42;',
-*   '/package.json': '{"name": "my-app"}'
-* });
-*
-* // Read files from the virtual filesystem
-* const content = memfs?.fs.readFileSync('/src/index.js', 'utf8');
-* ```
-*
-* @see {@link https://github.com/streamich/memfs} for more information on the memfs API.
-*/
+ * In-memory file system for browser builds.
+ *
+ * This is a re-export of the {@link https://github.com/streamich/memfs | memfs} package used by the WASI runtime.
+ * It allows you to read and write files to a virtual filesystem when using rolldown in browser environments.
+ *
+ * - `fs`: A Node.js-compatible filesystem API (`IFs` from memfs)
+ * - `volume`: The underlying `Volume` instance that stores the filesystem state
+ *
+ * Returns `undefined` in Node.js builds (only available in browser builds via `@rolldown/browser`).
+ *
+ * @example
+ * ```typescript
+ * import { memfs } from '@rollipop/rolldown/experimental';
+ *
+ * // Write files to virtual filesystem before bundling
+ * memfs?.volume.fromJSON({
+ *   '/src/index.js': 'export const foo = 42;',
+ *   '/package.json': '{"name": "my-app"}'
+ * });
+ *
+ * // Read files from the virtual filesystem
+ * const content = memfs?.fs.readFileSync('/src/index.js', 'utf8');
+ * ```
+ *
+ * @see {@link https://github.com/streamich/memfs} for more information on the memfs API.
+ */
 declare const memfs: {
   fs: any;
   volume: any;