@gjsify/cli 0.3.13 → 0.3.14

package/lib/actions/build.d.ts

@@ -1,12 +1,11 @@
 import type { ConfigData } from "../types/index.js";
-import type { App } from "@gjsify/esbuild-plugin-gjsify";
-import { BuildOptions, BuildResult, Plugin } from "esbuild";
+import type { App } from "@gjsify/rolldown-plugin-gjsify";
+import type { RolldownOutput } from "rolldown";
 export declare class BuildAction {
     readonly configData: ConfigData;
     constructor(configData?: ConfigData);
-    getEsBuildDefaults(): BuildOptions;
     /** Library mode */
-    buildLibrary(): Promise<BuildResult<BuildOptions>[]>;
+    buildLibrary(): Promise<RolldownOutput[]>;
     /**
      * Parse the `--globals` value into { autoMode, extras }.
      * - `auto`             → { autoMode: true, extras: '' }
@@ -19,11 +18,11 @@ export declare class BuildAction {
     private parseGlobalsValue;
     /**
      * Resolve the `--globals` CLI list into a pre-computed inject stub path
-     * that the esbuild plugin will append to its `inject` list. Only runs
-     * for `--app gjs` — Node and browser builds rely on native globals.
+     * that the orchestrator appends to its input list. Only runs for
+     * `--app gjs` — Node and browser builds rely on native globals.
      *
      * Used only for the explicit-only path (no `auto` token in the value).
-     * The auto path is handled in `buildApp` via the two-pass build.
+     * The auto path is handled in `buildApp` via the iterative multi-pass build.
      */
     private resolveGlobalsInject;
     /**
@@ -32,91 +31,9 @@ export declare class BuildAction {
      */
     private applyShebang;
     /** Application mode */
-    buildApp(app?: App): Promise<BuildResult<{
-        format: "esm" | "cjs";
-        plugins: Plugin[];
-        bundle?: boolean;
-        splitting?: boolean;
-        preserveSymlinks?: boolean;
-        outfile?: string;
-        metafile?: boolean;
-        outdir?: string;
-        outbase?: string;
-        external?: string[];
-        packages?: "bundle" | "external";
-        alias?: Record<string, string>;
-        loader?: {
-            [ext: string]: import("esbuild").Loader;
-        };
-        resolveExtensions?: string[];
-        mainFields?: string[];
-        conditions?: string[];
-        write?: boolean;
-        allowOverwrite?: boolean;
-        tsconfig?: string;
-        outExtension?: {
-            [ext: string]: string;
-        };
-        publicPath?: string;
-        entryNames?: string;
-        chunkNames?: string;
-        assetNames?: string;
-        inject?: string[];
-        banner?: {
-            [type: string]: string;
-        };
-        footer?: {
-            [type: string]: string;
-        };
-        entryPoints?: (string | {
-            in: string;
-            out: string;
-        })[] | Record<string, string>;
-        stdin?: import("esbuild").StdinOptions;
-        absWorkingDir?: string;
-        nodePaths?: string[];
-        sourcemap?: boolean | "linked" | "inline" | "external" | "both";
-        legalComments?: "none" | "inline" | "eof" | "linked" | "external";
-        sourceRoot?: string;
-        sourcesContent?: boolean;
-        globalName?: string;
-        target?: string | string[];
-        supported?: Record<string, boolean>;
-        platform?: import("esbuild").Platform;
-        mangleProps?: RegExp;
-        reserveProps?: RegExp;
-        mangleQuoted?: boolean;
-        mangleCache?: Record<string, string | false>;
-        drop?: import("esbuild").Drop[];
-        dropLabels?: string[];
-        minify?: boolean;
-        minifyWhitespace?: boolean;
-        minifyIdentifiers?: boolean;
-        minifySyntax?: boolean;
-        lineLimit?: number;
-        charset?: import("esbuild").Charset;
-        treeShaking?: boolean;
-        ignoreAnnotations?: boolean;
-        jsx?: "transform" | "preserve" | "automatic";
-        jsxFactory?: string;
-        jsxFragment?: string;
-        jsxImportSource?: string;
-        jsxDev?: boolean;
-        jsxSideEffects?: boolean;
-        define?: {
-            [key: string]: string;
-        };
-        pure?: string[];
-        keepNames?: boolean;
-        absPaths?: import("esbuild").AbsPaths[];
-        color?: boolean;
-        logLevel?: import("esbuild").LogLevel;
-        logLimit?: number;
-        logOverride?: Record<string, import("esbuild").LogLevel>;
-        tsconfigRaw?: string | import("esbuild").TsconfigRaw;
-    }>[]>;
+    buildApp(app?: App): Promise<RolldownOutput[]>;
     start(buildType?: {
         library?: boolean;
         app?: App;
-    }): Promise<BuildResult<BuildOptions>[]>;
+    }): Promise<RolldownOutput[]>;
 }

package/lib/actions/build.js

@@ -1,10 +1,10 @@
-import { build } from "esbuild";
-import { gjsifyPlugin } from "@gjsify/esbuild-plugin-gjsify";
-import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, } from "@gjsify/esbuild-plugin-gjsify/globals";
-import { getBundleDir, rewriteContents } from "@gjsify/esbuild-plugin-gjsify";
-import { getPnpPlugin } from "@gjsify/resolve-npm/pnp-relay";
+import { rolldown } from "rolldown";
+import { gjsifyPlugin } from "@gjsify/rolldown-plugin-gjsify";
+import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, } from "@gjsify/rolldown-plugin-gjsify/globals";
+import { pnpPlugin } from "@gjsify/rolldown-plugin-pnp";
 import { dirname, extname } from "node:path";
 import { chmod, readFile, writeFile } from "node:fs/promises";
+import { normalizeBundlerOptions, mergeBundlerOptions } from "../utils/normalize-bundler-options.js";
 const GJS_SHEBANG = "#!/usr/bin/env -S gjs -m\n";
 /**
  * `true` when `path` points at a location that's unsafe to use as a build
@@ -26,104 +26,81 @@ function isUnsafeDefaultOutput(path) {
  * @gjsify/{node,web}-polyfills) are resolvable for external consumers without
  * each one having to be a direct devDep.
  *
- * Wires the @gjsify/esbuild-plugin-gjsify rewriter (`__filename`/`__dirname`
- * injection for CJS code in node_modules) into the pnp plugin's onLoad —
- * esbuild stops at the first matching onLoad, so the rewriter MUST run from
- * inside the pnp plugin's onLoad rather than as a separate registration.
+ * The path rewriter (`__filename`/`__dirname` + `import.meta.url` injection
+ * for node_modules code) is registered separately by the orchestrator —
+ * Rolldown's transform hooks all run sequentially, no shared `onLoad` race.
  */
 async function buildPnpPlugin() {
-    return getPnpPlugin({
-        issuerUrl: import.meta.url,
-        transformContentsFactory: (build) => {
-            const bundleDir = getBundleDir(build);
-            return (args, contents) => rewriteContents(args, contents, bundleDir);
-        },
-    });
+    return pnpPlugin({ issuerUrl: import.meta.url });
 }
 export class BuildAction {
     configData;
     constructor(configData = {}) {
         this.configData = configData;
     }
-    getEsBuildDefaults() {
-        const defaults = {
-            allowOverwrite: true,
-        };
-        return defaults;
-    }
     /** Library mode */
     async buildLibrary() {
-        let { verbose, library, esbuild, typescript, exclude } = this.configData;
-        library ||= {};
-        esbuild ||= {};
-        typescript ||= {};
-        const moduleOutdir = library?.module ? dirname(library.module) : undefined;
-        const mainOutdir = library?.main ? dirname(library.main) : undefined;
-        const moduleOutExt = library.module ? extname(library.module) : ".js";
-        const mainOutExt = library.main ? extname(library.main) : ".js";
+        const { verbose, library, typescript, exclude, aliases } = this.configData;
+        const lib = library ?? {};
+        const userBundler = normalizeBundlerOptions(this.configData);
+        const moduleOutdir = lib.module ? dirname(lib.module) : undefined;
+        const mainOutdir = lib.main ? dirname(lib.main) : undefined;
+        const moduleOutExt = lib.module ? extname(lib.module) : ".js";
+        const mainOutExt = lib.main ? extname(lib.main) : ".js";
         const multipleBuilds = moduleOutdir && mainOutdir && moduleOutdir !== mainOutdir;
-        const pnpPlugin = await buildPnpPlugin();
-        const pnpPlugins = pnpPlugin ? [pnpPlugin] : [];
+        const pnp = await buildPnpPlugin();
+        const pnpPlugins = pnp ? [pnp] : [];
         const results = [];
         if (multipleBuilds) {
             const moduleFormat = moduleOutdir.includes("/cjs") || moduleOutExt === ".cjs"
                 ? "cjs"
                 : "esm";
-            results.push(await build({
-                ...this.getEsBuildDefaults(),
-                ...esbuild,
-                format: moduleFormat,
-                outdir: moduleOutdir,
-                plugins: [
-                    ...pnpPlugins,
-                    gjsifyPlugin({
-                        debug: verbose,
-                        library: moduleFormat,
-                        exclude,
-                        reflection: typescript?.reflection,
-                        jsExtension: moduleOutExt,
-                    }),
-                ],
+            results.push(await runOneLibraryBuild({
+                pluginOpts: {
+                    debug: verbose,
+                    library: moduleFormat,
+                    exclude,
+                    reflection: typescript?.reflection,
+                    jsExtension: moduleOutExt,
+                },
+                userBundler,
+                output: { dir: moduleOutdir },
+                userAliases: aliases,
+                pnpPlugins,
             }));
             const mainFormat = mainOutdir.includes("/cjs") || mainOutExt === ".cjs" ? "cjs" : "esm";
-            results.push(await build({
-                ...this.getEsBuildDefaults(),
-                ...esbuild,
-                format: mainFormat,
-                outdir: mainOutdir,
-                plugins: [
-                    ...pnpPlugins,
-                    gjsifyPlugin({
-                        debug: verbose,
-                        library: mainFormat,
-                        exclude,
-                        reflection: typescript?.reflection,
-                        jsExtension: mainOutExt,
-                    }),
-                ],
+            results.push(await runOneLibraryBuild({
+                pluginOpts: {
+                    debug: verbose,
+                    library: mainFormat,
+                    exclude,
+                    reflection: typescript?.reflection,
+                    jsExtension: mainOutExt,
+                },
+                userBundler,
+                output: { dir: mainOutdir },
+                userAliases: aliases,
+                pnpPlugins,
             }));
         }
         else {
-            const outfilePath = esbuild?.outfile || library?.module || library?.main;
+            const outfilePath = userBundler.output?.file ?? lib.module ?? lib.main;
             const outExt = outfilePath ? extname(outfilePath) : ".js";
-            const outdir = esbuild?.outdir || (outfilePath ? dirname(outfilePath) : undefined);
-            const format = esbuild?.format ??
+            const outdir = userBundler.output?.dir ?? (outfilePath ? dirname(outfilePath) : undefined);
+            const format = userBundler.output?.format ??
                 (outdir?.includes("/cjs") || outExt === ".cjs" ? "cjs" : "esm");
-            results.push(await build({
-                ...this.getEsBuildDefaults(),
-                ...esbuild,
-                format,
-                outdir,
-                plugins: [
-                    ...pnpPlugins,
-                    gjsifyPlugin({
-                        debug: verbose,
-                        library: format,
-                        exclude,
-                        reflection: typescript?.reflection,
-                        jsExtension: outExt,
-                    }),
-                ],
+            results.push(await runOneLibraryBuild({
+                pluginOpts: {
+                    debug: verbose,
+                    library: format,
+                    exclude,
+                    reflection: typescript?.reflection,
+                    jsExtension: outExt,
+                },
+                userBundler,
+                output: { dir: outdir },
+                userAliases: aliases,
+                pnpPlugins,
             }));
         }
         return results;
@@ -152,11 +129,11 @@ export class BuildAction {
     }
     /**
      * Resolve the `--globals` CLI list into a pre-computed inject stub path
-     * that the esbuild plugin will append to its `inject` list. Only runs
-     * for `--app gjs` — Node and browser builds rely on native globals.
+     * that the orchestrator appends to its input list. Only runs for
+     * `--app gjs` — Node and browser builds rely on native globals.
      *
      * Used only for the explicit-only path (no `auto` token in the value).
-     * The auto path is handled in `buildApp` via the two-pass build.
+     * The auto path is handled in `buildApp` via the iterative multi-pass build.
      */
     async resolveGlobalsInject(app, globals, verbose) {
         if (app !== "gjs")
@@ -196,30 +173,34 @@ export class BuildAction {
     }
     /** Application mode */
     async buildApp(app = "gjs") {
-        const { verbose, esbuild, typescript, exclude, library: pgk, aliases, excludeGlobals, } = this.configData;
-        const format = esbuild?.format ??
-            (esbuild?.outfile?.endsWith(".cjs") ? "cjs" : "esm");
+        const { verbose, typescript, exclude, library: pkg, aliases, excludeGlobals, } = this.configData;
+        const userBundler = normalizeBundlerOptions(this.configData);
+        const formatRaw = userBundler.output?.format ??
+            (userBundler.output?.file?.endsWith(".cjs") ? "cjs" : "esm");
+        // The orchestrator only handles esm/cjs (iife is not a GJS / Node /
+        // browser-bundle target we support). Coerce.
+        const format = formatRaw === "iife" ? "esm" : formatRaw;
         // Set default outfile if no outdir is set
-        if (esbuild &&
-            !esbuild?.outfile &&
-            !esbuild?.outdir &&
-            (pgk?.main || pgk?.module)) {
-            const candidate = esbuild?.format === "cjs"
-                ? pgk.main || pgk.module
-                : pgk.module || pgk.main;
+        let outfile = userBundler.output?.file;
+        let outdir = userBundler.output?.dir;
+        if (!outfile && !outdir && (pkg?.main || pkg?.module)) {
+            const candidate = format === "cjs"
+                ? pkg.main ?? pkg.module
+                : pkg.module ?? pkg.main;
             if (candidate && isUnsafeDefaultOutput(candidate)) {
-                // `package.json#main`/`module` commonly points at a TypeScript
-                // source (e.g. `src/index.ts` for TS-direct workflows). Falling
-                // back to that value would have esbuild OVERWRITE the source.
-                // Surface a clear error and require an explicit outfile/outdir
-                // instead of silently destroying the user's code.
                 throw new Error(`gjsify build: refusing to default --outfile to ${candidate} ` +
                     `(would overwrite a TypeScript source file). Pass --outfile/--outdir ` +
-                    `explicitly, or set "gjsify.esbuild.outfile" in package.json.`);
+                    `explicitly, or set "gjsify.bundler.output.file" in package.json.`);
             }
-            esbuild.outfile = candidate;
+            outfile = candidate;
         }
         const { consoleShim, globals } = this.configData;
+        const userExternal = Array.isArray(userBundler.external)
+            ? userBundler.external
+            : undefined;
+        const userBanner = typeof userBundler.output?.banner === "string"
+            ? userBundler.output.banner
+            : undefined;
         const pluginOpts = {
             debug: verbose,
             app,
@@ -230,65 +211,83 @@ export class BuildAction {
             ...(aliases ? { aliases } : {}),
         };
         const { autoMode, extras } = this.parseGlobalsValue(globals);
-        const pnpPlugin = await buildPnpPlugin();
-        const pnpPlugins = pnpPlugin ? [pnpPlugin] : [];
+        const pnp = await buildPnpPlugin();
+        const pnpPlugins = pnp ? [pnp] : [];
         // --- Auto mode (with optional extras): iterative multi-pass build ---
-        // The extras token is used for cases where the detector cannot
-        // statically see a global (e.g. Excalibur indirects globalThis via
-        // BrowserComponent.nativeComponent). Common pattern: --globals auto,dom
         if (app === "gjs" && autoMode) {
+            const gjsifyPluginFactory = async (opts) => {
+                const cfg = await gjsifyPlugin({
+                    input: userBundler.input,
+                    output: { file: outfile, dir: outdir },
+                    userExternal,
+                    userBanner,
+                    userAliases: aliases,
+                    shebang: this.configData.shebang,
+                }, opts);
+                return cfg.plugins;
+            };
             const { injectPath } = await detectAutoGlobals({
-                ...this.getEsBuildDefaults(),
-                ...esbuild,
-                format,
+                input: userBundler.input,
                 plugins: pnpPlugins,
-            }, pluginOpts, verbose, { extraGlobalsList: extras, excludeGlobals });
-            const result = await build({
-                ...this.getEsBuildDefaults(),
-                ...esbuild,
+                external: userBundler.external,
+                transform: userBundler.transform,
                 format,
-                plugins: [
-                    ...pnpPlugins,
-                    gjsifyPlugin({
-                        ...pluginOpts,
-                        autoGlobalsInject: injectPath,
-                    }),
-                ],
-            });
-            if (app === "gjs" && this.configData.shebang) {
-                await this.applyShebang(esbuild?.outfile, verbose);
-            }
-            return [result];
+            }, pluginOpts, gjsifyPluginFactory, verbose, { extraGlobalsList: extras, excludeGlobals });
+            pluginOpts.autoGlobalsInject = injectPath;
+        }
+        else if (extras) {
+            pluginOpts.autoGlobalsInject = await this.resolveGlobalsInject(app, extras, verbose);
+        }
+        // Final build: orchestrator → rolldown → write
+        const cfg = await gjsifyPlugin({
+            input: userBundler.input,
+            output: { file: outfile, dir: outdir },
+            userExternal,
+            userBanner,
+            userAliases: aliases,
+            shebang: this.configData.shebang,
+        }, pluginOpts);
+        const merged = mergeBundlerOptions(cfg.options, userBundler);
+        const finalOpts = {
+            ...merged,
+            plugins: [...pnpPlugins, ...cfg.plugins],
+        };
+        const build = await rolldown(finalOpts);
+        let writeResult;
+        try {
+            writeResult = await build.write(finalOpts.output ?? {});
+        }
+        finally {
+            await build.close();
         }
-        // --- Explicit list (no `auto` token) or none mode ---
-        const autoGlobalsInject = extras
-            ? await this.resolveGlobalsInject(app, extras, verbose)
-            : undefined;
-        const result = await build({
-            ...this.getEsBuildDefaults(),
-            ...esbuild,
-            format,
-            plugins: [
-                ...pnpPlugins,
-                gjsifyPlugin({
-                    ...pluginOpts,
-                    autoGlobalsInject,
-                }),
-            ],
-        });
         if (app === "gjs" && this.configData.shebang) {
-            await this.applyShebang(esbuild?.outfile, verbose);
+            await this.applyShebang(outfile, verbose);
         }
-        return [result];
+        return [writeResult];
     }
     async start(buildType = { app: "gjs" }) {
-        const results = [];
         if (buildType.library) {
-            results.push(...(await this.buildLibrary()));
-        }
-        else {
-            results.push(...(await this.buildApp(buildType.app)));
+            return await this.buildLibrary();
         }
-        return results;
+        return await this.buildApp(buildType.app);
+    }
+}
+async function runOneLibraryBuild(args) {
+    const cfg = await gjsifyPlugin({
+        input: args.userBundler.input,
+        output: args.output,
+        userAliases: args.userAliases,
+    }, args.pluginOpts);
+    const merged = mergeBundlerOptions(cfg.options, args.userBundler);
+    const finalOpts = {
+        ...merged,
+        plugins: [...args.pnpPlugins, ...cfg.plugins],
+    };
+    const build = await rolldown(finalOpts);
+    try {
+        return await build.write(finalOpts.output ?? {});
+    }
+    finally {
+        await build.close();
     }
 }

package/lib/config.js

@@ -84,7 +84,7 @@ export class Config {
         if (fileResult?.config && isPlainObject(fileResult.config)) {
             merge(merged, fileResult.config);
         }
-        merged.esbuild ||= {};
+        merged.bundler ||= {};
         merged.library ||= {};
         merged.typescript ||= {};
         return {
@@ -155,16 +155,56 @@ export class Config {
         if (Object.keys(aliasMap).length) {
             configData.aliases = { ...(configData.aliases ?? {}), ...aliasMap };
         }
-        merge(configData.esbuild ??= {}, {
-            format: cliArgs.format,
-            minify: cliArgs.minify,
-            entryPoints: cliArgs.entryPoints,
-            outfile: cliArgs.outfile,
-            outdir: cliArgs.outdir,
-            logLevel: cliArgs.logLevel || 'warning',
-            ...(cliArgs.external?.length ? { external: cliArgs.external } : {}),
-            ...(Object.keys(defineMap).length ? { define: defineMap } : {}),
-        });
+        // Merge CLI flags into the Rolldown-shape `bundler` field. Mappings:
+        //   --entry-points  → bundler.input
+        //   --outfile       → bundler.output.file
+        //   --outdir        → bundler.output.dir
+        //   --format        → bundler.output.format
+        //   --minify        → bundler.output.minify
+        //   --log-level     → bundler.logLevel
+        //   --external      → bundler.external
+        //   --define        → bundler.transform.define
+        const bundler = (configData.bundler ??= {});
+        const output = (bundler.output ??= {});
+        const transform = (bundler.transform ??= {});
+        if (cliArgs.entryPoints?.length)
+            bundler.input = cliArgs.entryPoints;
+        if (cliArgs.outfile !== undefined)
+            output.file = cliArgs.outfile;
+        if (cliArgs.outdir !== undefined)
+            output.dir = cliArgs.outdir;
+        if (cliArgs.format !== undefined)
+            output.format = cliArgs.format;
+        if (cliArgs.minify !== undefined)
+            output.minify = cliArgs.minify;
+        if (cliArgs.logLevel) {
+            // Map esbuild log levels to Rolldown's narrower set:
+            //   esbuild   → rolldown
+            //   silent    → silent
+            //   error     → warn   (rolldown has no error-only)
+            //   warning   → warn
+            //   info      → info
+            //   debug     → debug
+            //   verbose   → debug  (rolldown has no verbose)
+            const map = {
+                silent: 'silent',
+                error: 'warn',
+                warning: 'warn',
+                warn: 'warn',
+                info: 'info',
+                debug: 'debug',
+                verbose: 'debug',
+            };
+            const level = map[cliArgs.logLevel] ?? 'warn';
+            bundler.logLevel = level;
+        }
+        if (cliArgs.external?.length) {
+            const userExternal = Array.isArray(bundler.external) ? bundler.external : [];
+            bundler.external = [...userExternal, ...cliArgs.external];
+        }
+        if (Object.keys(defineMap).length) {
+            transform.define = { ...(transform.define ?? {}), ...defineMap };
+        }
         if (configData.verbose)
             console.debug("configData", configData);
         return configData;

package/lib/types/cli-build-options.d.ts

@@ -1,4 +1,4 @@
-import type { App } from '@gjsify/esbuild-plugin-gjsify';
+import type { App } from '@gjsify/rolldown-plugin-gjsify';
 export interface CliBuildOptions {
     /**
      * This is an array of files that each serve as an input to the bundling algorithm.

package/lib/types/config-data.d.ts

@@ -1,9 +1,58 @@
-import type { BuildOptions as EsbuildOptions } from 'esbuild';
+import type { RolldownOptions, OutputOptions } from 'rolldown';
 import type { ConfigDataLibrary, ConfigDataTypescript } from './index.js';
+/**
+ * Subset of `RolldownOptions` accepted in `.gjsifyrc.js`. Mirrors the legacy
+ * `esbuild?: BuildOptions` field — a thin pass-through. The orchestrator
+ * applies platform defaults on top of these, so most projects only need
+ * `output.file` / `output.dir` here.
+ *
+ * `output` is constrained to a single `OutputOptions` object (Rolldown also
+ * accepts an array for multi-output builds, but the CLI surface targets the
+ * single-output use case).
+ */
+export type BundlerOptions = Omit<RolldownOptions, 'output'> & {
+    output?: OutputOptions;
+};
+/**
+ * Legacy `esbuild?: BuildOptions` shape — kept as a compatibility shim for
+ * one minor release. Setting it logs a deprecation warning; the supported
+ * subset of fields is mapped into `bundler` at config-load time.
+ *
+ * Drop in 0.5.0.
+ */
+export interface LegacyEsbuildOptions {
+    outfile?: string;
+    outdir?: string;
+    format?: 'esm' | 'cjs' | 'iife';
+    external?: string[];
+    define?: Record<string, string>;
+    inject?: string[];
+    banner?: {
+        js?: string;
+    };
+    target?: string | string[];
+    minify?: boolean;
+    sourcemap?: boolean | 'inline' | 'external' | 'both';
+    mainFields?: string[];
+    conditions?: string[];
+    platform?: 'browser' | 'node' | 'neutral';
+    loader?: Record<string, string>;
+}
 export interface ConfigData {
     /** Switch on the verbose mode */
     verbose?: boolean;
-    esbuild?: EsbuildOptions;
+    /**
+     * Bundler-level options forwarded to Rolldown. Replaces the legacy
+     * `esbuild` field. The orchestrator applies platform-specific defaults
+     * on top — most projects only need to set `output.file` / `output.dir`.
+     */
+    bundler?: BundlerOptions;
+    /**
+     * @deprecated Use `bundler` instead. Will be removed in 0.5.0. The shim
+     * maps the supported subset of esbuild fields into the equivalent
+     * Rolldown shape and logs a deprecation warning.
+     */
+    esbuild?: LegacyEsbuildOptions;
     library?: ConfigDataLibrary;
     typescript?: ConfigDataTypescript;
     /** An array of glob patterns to exclude matches and aliases */

package/lib/utils/normalize-bundler-options.d.ts

@@ -0,0 +1,17 @@
+import type { ConfigData, BundlerOptions } from '../types/config-data.js';
+export declare function normalizeBundlerOptions(configData: ConfigData): BundlerOptions;
+/**
+ * Shallow merge with deep-merge of `output`, `transform`, and `resolve`. The
+ * second argument wins on conflicts, matching `merge(target, ...sources)`
+ * semantics from `@gjsify/rolldown-plugin-gjsify/utils/merge`.
+ *
+ * `base` is typically the Rolldown-generic shape returned by the orchestrator;
+ * `overrides` is the user's `BundlerOptions` from `.gjsifyrc.js` plus CLI
+ * flag merges. Single-output assumption matches `BundlerOptions['output']`.
+ *
+ * The orchestrator-side `input` is authoritative — it's the post-glob-expansion
+ * value. Overriding it with the user's raw glob string would re-introduce
+ * unresolved glob patterns into the final Rolldown call. Same for `external`,
+ * which the orchestrator concatenates with platform defaults already.
+ */
+export declare function mergeBundlerOptions(base: BundlerOptions, overrides: BundlerOptions): BundlerOptions;