@gjsify/rolldown-plugin-gjsify 0.3.14

package/src/index.ts

@@ -0,0 +1,32 @@
+// Public re-exports for `@gjsify/rolldown-plugin-gjsify`.
+
+export * from './types/index.js';
+export * from './utils/index.js';
+export * from './app/index.js';
+export * from './library/index.js';
+
+export {
+    REWRITE_FILTER,
+    getBundleDirFromOutput,
+    rewriteContents,
+    shouldRewrite,
+    nodeModulesPathRewritePlugin,
+} from './plugins/rewrite-node-modules-paths.js';
+export type {
+    NodeModulesPathRewriteOptions,
+    RewriteResult,
+} from './plugins/rewrite-node-modules-paths.js';
+
+export { processStubPlugin, GJS_PROCESS_STUB, composeBanner } from './plugins/process-stub.js';
+export type { ProcessStubPluginOptions } from './plugins/process-stub.js';
+export { cssAsStringPlugin } from './plugins/css-as-string.js';
+export { shebangPlugin, GJS_SHEBANG } from './plugins/shebang.js';
+export type { ShebangPluginOptions } from './plugins/shebang.js';
+export { gjsImportsEmptyPlugin } from './plugins/gjs-imports-empty.js';
+
+export * from './plugin.js';
+import { gjsifyPlugin } from './plugin.js';
+export { gjsifyPlugin };
+export default gjsifyPlugin;
+
+export * from '@gjsify/resolve-npm';

package/src/library/index.ts

@@ -0,0 +1,2 @@
+export { setupLib } from './lib.js';
+export type { LibBuildConfig, LibFactoryInput } from './lib.js';

package/src/library/lib.ts

@@ -0,0 +1,142 @@
+// Library mode — multi-entry, unbundled output for republication on npm.
+//
+// Equivalent to esbuild's `bundle: false`: every input file is emitted
+// 1:1 with its imports preserved as-is (resolved by Rolldown). The user
+// alias map is applied so `node:fs` → `fs/promises` style remappings still
+// work, and the JS extension table mirrors the esbuild predecessor.
+//
+// Targeting `esnext` and `platform: 'neutral'` matches the original
+// library config: consumers downstream (downstream apps using `gjsify
+// build --app gjs|node|browser`) re-bundle and apply their own target
+// lowering. Library output stays maximally portable.
+
+import { aliasPlugin } from '../plugins/alias.js';
+import { cssAsStringPlugin } from '../plugins/css-as-string.js';
+import type { RolldownOptions, RolldownPluginOption } from 'rolldown';
+
+import type { PluginOptions } from '../types/plugin-options.js';
+import { globToEntryPoints } from '../utils/entry-points.js';
+
+export interface LibBuildConfig {
+    options: RolldownOptions;
+    plugins: RolldownPluginOption[];
+}
+
+export interface LibFactoryInput {
+    input?: RolldownOptions['input'];
+    output: { file?: string; dir?: string };
+    userAliases?: Record<string, string>;
+    pluginOptions: PluginOptions;
+}
+
+export const setupLib = async (input: LibFactoryInput): Promise<LibBuildConfig> => {
+    // Derive output format from `library: 'esm' | 'cjs'` when the caller
+    // didn't pass `format` explicitly. The library type and the emitted
+    // module format are inseparable: a CJS-library build that emits ESM
+    // (or vice versa) is broken by definition.
+    const format = input.pluginOptions.format ?? input.pluginOptions.library ?? 'esm';
+
+    const exclude = input.pluginOptions.exclude ?? [];
+    const entryPoints = await globToEntryPoints(input.input, exclude);
+
+    // Derive `preserveModulesRoot` from the common ancestor of every
+    // resolved entry. Workspaces use various roots (`src/`, `src/ts/`,
+    // `lib/`); without stripping the right one, Rolldown emits paths
+    // like `lib/esm/<root>/<file>.js` instead of `lib/esm/<file>.js`,
+    // which doesn't match the package.json `exports` map.
+    const preserveModulesRoot = computeCommonRoot(entryPoints);
+
+    const aliasMap = {
+        ...(input.pluginOptions.aliases ?? {}),
+        ...(input.userAliases ?? {}),
+    };
+
+    // Library mode keeps all third-party / workspace imports as-is so the
+    // emitted package re-exports its dep tree by reference. Rolldown's
+    // default behaviour would inline workspace packages into the output
+    // directory; we mark anything not starting with `./` or `/` as external.
+    const external = (id: string): boolean => {
+        if (id.startsWith('./') || id.startsWith('../') || id.startsWith('/')) return false;
+        return true;
+    };
+
+    const options: RolldownOptions = {
+        input: entryPoints,
+        platform: 'neutral',
+        external,
+        resolve: {
+            mainFields: format === 'esm' ? ['module', 'main'] : ['main'],
+            conditionNames: format === 'esm' ? ['module', 'import'] : ['require'],
+        },
+        transform: { target: 'esnext' },
+        output: {
+            ...input.output,
+            format,
+            // Library mode = preserve module structure (multi-file output,
+            // imports resolved but not bundled).
+            preserveModules: true,
+            // Strip the source root from the emitted paths. Without this,
+            // Rolldown keeps the full project-relative path. The root is
+            // computed from the common ancestor of resolved entries.
+            preserveModulesRoot,
+            minify: false,
+            sourcemap: false,
+        },
+        treeshake: false,
+    };
+
+    const plugins: RolldownPluginOption[] = [
+        aliasPlugin({ entries: flattenAliases(aliasMap) }),
+        // Rolldown removed experimental CSS bundling — `.css` files would
+        // error at the bundler level. Library-mode packages that bundle
+        // CSS as a string (e.g. `@gjsify/adwaita-fonts/index.css`) need
+        // the same `load` hook the app factories install. The result is a
+        // tiny JS module re-exporting the CSS source, which preserveModules
+        // emits 1:1.
+        cssAsStringPlugin(),
+    ];
+
+    return { options, plugins };
+};
+
+/**
+ * Compute the common-ancestor directory of a set of entry paths so
+ * Rolldown's `preserveModulesRoot` strips the right prefix from emitted
+ * file paths. Falls back to `'src'` when there are no entries or the
+ * entries don't share a meaningful prefix.
+ */
+function computeCommonRoot(
+    entries: ReturnType<typeof globToEntryPoints> extends Promise<infer T> ? T : never,
+): string {
+    const paths: string[] = entries === undefined
+        ? []
+        : typeof entries === 'string'
+            ? [entries]
+            : Array.isArray(entries)
+                ? entries
+                : Object.values(entries);
+    if (paths.length === 0) return 'src';
+
+    const split = paths.map((p) => p.split('/').filter(Boolean));
+    const head = split[0];
+    let i = 0;
+    for (; i < head.length; i++) {
+        const seg = head[i];
+        if (!split.every((parts) => parts[i] === seg)) break;
+    }
+    if (i === 0) return 'src';
+    // Drop the basename if the common prefix points at a single file.
+    const commonParts = head.slice(0, i);
+    // Heuristic: treat the prefix as a directory when at least one path
+    // has more segments after it.
+    const hasMoreAfter = split.some((parts) => parts.length > i);
+    return hasMoreAfter ? commonParts.join('/') : commonParts.slice(0, -1).join('/') || 'src';
+}
+
+function flattenAliases(map: Record<string, string>): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const [from, to] of Object.entries(map)) {
+        if (to) out[from] = to;
+    }
+    return out;
+}

package/src/plugin.ts

@@ -0,0 +1,91 @@
+// `gjsifyPlugin` — orchestrator entry point.
+//
+// Picks the platform-specific factory based on `pluginOptions.app`
+// (or `library` for library mode) and returns the resolved Rolldown
+// configuration. Unlike the esbuild predecessor, this is NOT a single
+// `Plugin` object — it returns a *config bundle* the caller composes into
+// `rolldown(opts)`, because Rolldown does not have esbuild's `setup(build)`
+// hook through which a single plugin can mutate `build.initialOptions`.
+//
+// The CLI consumer (`@gjsify/cli`) calls `gjsifyPlugin(...)` to get back
+// `{ options, plugins }`, then calls `rolldown({ ...options, plugins:
+// [...userPlugins, ...plugins] })`.
+
+import type { RolldownOptions, RolldownPluginOption } from 'rolldown';
+import type { PluginOptions } from './types/plugin-options.js';
+import { setupForGjs, setupForNode, setupForBrowser } from './app/index.js';
+import { setupLib } from './library/index.js';
+
+export interface GjsifyConfig {
+    options: RolldownOptions;
+    plugins: RolldownPluginOption[];
+}
+
+export interface GjsifyPluginInput {
+    input?: RolldownOptions['input'];
+    output: { file?: string; dir?: string };
+    userExternal?: string[];
+    userBanner?: string;
+    userAliases?: Record<string, string>;
+    /** Whether to prepend `#!/usr/bin/env -S gjs -m` to the GJS bundle. */
+    shebang?: boolean;
+}
+
+/**
+ * Build the Rolldown configuration template + plugin array for the given
+ * pluginOptions. The caller composes the returned `options.plugins` with
+ * its own user plugins and passes the merged options to `rolldown(...)`.
+ */
+export const gjsifyPlugin = async (
+    input: GjsifyPluginInput,
+    pluginOptions: PluginOptions = {},
+): Promise<GjsifyConfig> => {
+    if (pluginOptions.library) {
+        switch (pluginOptions.library) {
+            case 'esm':
+            case 'cjs':
+                return await setupLib({
+                    input: input.input,
+                    output: input.output,
+                    userAliases: input.userAliases,
+                    pluginOptions,
+                });
+            default:
+                throw new TypeError('Unknown library type: ' + pluginOptions.library);
+        }
+    }
+
+    const app = pluginOptions.app ?? 'gjs';
+    switch (app) {
+        case 'gjs':
+            return await setupForGjs({
+                input: input.input,
+                output: input.output,
+                userExternal: input.userExternal,
+                userBanner: input.userBanner,
+                userAliases: input.userAliases,
+                shebang: input.shebang,
+                pluginOptions,
+            });
+        case 'node':
+            return await setupForNode({
+                input: input.input,
+                output: input.output,
+                userExternal: input.userExternal,
+                userAliases: input.userAliases,
+                pluginOptions,
+            });
+        case 'browser':
+            return await setupForBrowser({
+                input: input.input,
+                output: input.output,
+                userExternal: input.userExternal,
+                userAliases: input.userAliases,
+                pluginOptions,
+            });
+        default:
+            throw new TypeError('Unknown app platform: ' + app);
+    }
+};
+
+export default gjsifyPlugin;

package/src/plugins/alias.ts

@@ -0,0 +1,53 @@
+// Custom alias plugin — `@rollup/plugin-alias` returns the rewritten
+// specifier as the resolved id, then leaves Rolldown's default resolver to
+// load it. That fails for workspace package targets (`@gjsify/crypto` etc.)
+// when the importer's package.json doesn't list them as direct deps —
+// Rolldown rejects packages that aren't declared in the importer's manifest
+// even when they exist in a hoisted workspace `node_modules`.
+//
+// This plugin instead calls `this.resolve(target, importer, { skipSelf: true })`
+// which goes through the full plugin chain (including any subsequent resolvers)
+// and resolves to a real file path the default loader can read.
+//
+// Behaviour preserved from the esbuild predecessor's `aliasPlugin`:
+//   - exact string match (no prefix-aware semantics needed at this layer)
+//   - `node:<name>` specifiers map to the same target as `<name>`
+//     (handled in the alias-builder helpers, not here).
+
+import type { Plugin } from 'rolldown';
+
+export interface AliasPluginOptions {
+    entries: Record<string, string>;
+}
+
+export function aliasPlugin(options: AliasPluginOptions): Plugin {
+    const entries = options.entries;
+    const keys = Object.keys(entries);
+
+    return {
+        name: 'gjsify-alias',
+        resolveId: {
+            order: 'pre' as const,
+            async handler(source, importer) {
+                if (!Object.prototype.hasOwnProperty.call(entries, source)) {
+                    return null;
+                }
+                const target = entries[source];
+                // Self-reference guard: if a user maps a specifier to itself
+                // (rare but legal), skip to avoid infinite loops.
+                if (target === source) return null;
+
+                const resolved = await this.resolve(target, importer, {
+                    skipSelf: true,
+                });
+                if (resolved !== null) {
+                    return resolved;
+                }
+                // Fall through to other resolvers if we couldn't load it
+                // ourselves. `null` from a `pre`-order resolveId lets the
+                // default chain continue.
+                return null;
+            },
+        },
+    };
+}

package/src/plugins/css-as-string.ts

@@ -0,0 +1,37 @@
+// Wrap `.css` imports as JS string default exports.
+//
+// Rolldown's experimental CSS bundling was removed (see
+// https://github.com/rolldown/rolldown/issues/4271) — when the bundler
+// sees a `.css` extension it errors out unless something else loads the
+// file first. We hook into `load` (with a path filter) BEFORE Rolldown's
+// CSS classification fires and emit a JS module whose default export is
+// the CSS source as a string. Consumers can then do:
+//
+//   import css from './app.css';
+//   provider.load_from_string(css);
+//
+// — the canonical pattern for `Gtk.CssProvider` under GJS.
+//
+// `@import` resolution is left to the user / CSS preprocessor. For simple
+// app CSS this is fine; for @import-heavy CSS, run a preprocessor (e.g.
+// sass / postcss) ahead of `gjsify build` so the input file is already
+// flat.
+
+import { readFile } from 'node:fs/promises';
+import type { Plugin } from 'rolldown';
+
+export function cssAsStringPlugin(): Plugin {
+    return {
+        name: 'gjsify-css-as-string',
+        load: {
+            filter: { id: /\.css$/ },
+            async handler(id: string) {
+                const code = await readFile(id, 'utf8');
+                return {
+                    code: `export default ${JSON.stringify(code)};`,
+                    moduleType: 'js' as const,
+                };
+            },
+        },
+    };
+}

package/src/plugins/gjs-imports-empty.ts

@@ -0,0 +1,29 @@
+// For `--app browser`: redirect `@girs/*` and `gi://*` imports to an empty
+// module. These are GJS-specific (GObject introspection bindings / GI
+// protocol) with no browser equivalent. They appear transitively via
+// `@gjsify/unit` and similar packages that have GJS-specific code paths.
+//
+// Marking them external would leave bare specifiers in the bundle that the
+// browser cannot resolve at runtime; instead we resolve them to a virtual
+// empty ESM module so the bundle is self-contained.
+
+import type { Plugin } from 'rolldown';
+
+const GJSIMPORTS_VIRTUAL_ID = '\0gjsify-empty-gjs-import';
+
+export function gjsImportsEmptyPlugin(): Plugin {
+    return {
+        name: 'gjsify-gjs-imports-empty',
+        resolveId: {
+            order: 'pre' as const,
+            filter: { id: /^(@girs\/|gi:\/\/)/ },
+            handler(_source) {
+                return { id: GJSIMPORTS_VIRTUAL_ID };
+            },
+        },
+        load(id) {
+            if (id !== GJSIMPORTS_VIRTUAL_ID) return null;
+            return { code: 'export {}; export default {};', moduleSideEffects: false };
+        },
+    };
+}

package/src/plugins/process-stub.ts

@@ -0,0 +1,91 @@
+// Synchronous `globalThis.process` stub injected as a GJS bundle banner.
+//
+// Some npm packages (glob, path-scurry, readable-stream, …) access
+// `globalThis.process.platform` at their top-level during lazy `__esm`
+// initialisation — BEFORE any `import`-triggered side effects fire. A
+// banner runs before everything, including bundler helpers and all
+// bundled module code, making it the only reliable injection point for
+// a synchronous global that must exist from byte 1 of execution.
+//
+// Only installed if `process` is absent; the full @gjsify/process
+// implementation (with EventEmitter, real streams, etc.) is wired up
+// later via `--globals auto` (which injects @gjsify/node-globals/register/process).
+//
+// Kept as a single line: the banner runs before any source-map-aware
+// machinery, so newlines here would shift every line number by one. Single
+// line = zero source-map drift for the actual bundle code below.
+import type { Plugin } from 'rolldown';
+
+export const GJS_PROCESS_STUB =
+    'if(typeof globalThis.process==="undefined"){' +
+        'const _s=imports.system,_G=imports.gi.GLib;' +
+        'globalThis.process={' +
+            'platform:"linux",arch:"x64",version:"v20.0.0",' +
+            'env:new Proxy({},{' +
+                'get(_,p){return typeof p==="string"?(_G.getenv(p)??undefined):undefined},' +
+                'set(_,p,v){if(typeof p==="string")_G.setenv(p,String(v),true);return true},' +
+                'has(_,p){return typeof p==="string"&&_G.getenv(p)!==null},' +
+                'deleteProperty(_,p){if(typeof p==="string")_G.unsetenv(p);return true},' +
+                'ownKeys(){return _G.listenv()??[]},' +
+                'getOwnPropertyDescriptor(_,p){const v=_G.getenv(p);return v!==null?{value:v,writable:true,enumerable:true,configurable:true}:undefined}' +
+            '}),' +
+            'argv:_s?.programArgs?["gjs",_s.programInvocationName||"",..._s.programArgs]:["gjs"],' +
+            'versions:{},config:{},' +
+            'cwd(){return _G.get_current_dir()||"/"},' +
+            'exit(c){_s.exit(c??0)},' +
+            'stderr:{write(s){printerr(s)}},stdout:{write(s){print(s)}},stdin:null,' +
+            'exitCode:undefined,' +
+            'nextTick(fn,...a){Promise.resolve().then(()=>fn(...a))},' +
+            'hrtime(t){return t?[0,0]:[0,0]},' +
+        '};' +
+    '}';
+
+/**
+ * Compose the GJS process stub with the user-supplied banner so the result
+ * is valid syntax for `gjs -m`. A leading `#!shebang` line in the user
+ * banner is hoisted to byte 0 of the output. Any `#` character that appears
+ * anywhere except byte 0 is a fatal SyntaxError under SpiderMonkey 128+ —
+ * putting our process stub before the user's shebang would break the bundle.
+ *
+ * Output shape:
+ *   [#!shebang\n][<process-stub>\n<rest-of-user-banner>]
+ *
+ * Either side of the bracket may be empty; the result is always concatenated
+ * without leading whitespace.
+ */
+export function composeBanner(stub: string, userBanner: string): string {
+    if (!userBanner) return stub;
+    const shebangMatch = userBanner.match(/^#![^\n]*\n/);
+    if (!shebangMatch) {
+        return stub + '\n' + userBanner;
+    }
+    const shebang = shebangMatch[0];
+    const rest = userBanner.slice(shebang.length);
+    return shebang + stub + (rest ? '\n' + rest : '');
+}
+
+/**
+ * Build a Rolldown plugin that injects the GJS process stub as a chunk
+ * banner. Runs with `enforce: 'post'`-equivalent ordering so the stub
+ * lands *after* any user `output.banner` value, except when the user
+ * banner starts with a `#!shebang` line — which is hoisted to byte 0
+ * by `composeBanner`.
+ */
+export interface ProcessStubPluginOptions {
+    /** User-supplied banner string. May contain a leading `#!shebang`. */
+    userBanner?: string;
+}
+
+export function processStubPlugin(options: ProcessStubPluginOptions = {}): Plugin {
+    const banner = composeBanner(GJS_PROCESS_STUB, options.userBanner ?? '');
+    return {
+        name: 'gjsify-process-stub',
+        renderChunk: {
+            order: 'post' as const,
+            handler(code, chunk) {
+                if (!chunk.isEntry) return null;
+                return { code: banner + '\n' + code, map: null };
+            },
+        },
+    };
+}

package/src/plugins/rewrite-node-modules-paths.ts

@@ -0,0 +1,169 @@
+// Per-source rewriter for node_modules files that reference
+// `import.meta.url`, `__dirname`, or `__filename`. Mirrors the esbuild
+// predecessor's logic — body is identical because the rewrite is purely
+// a string transform on already-loaded source. The only delta is the
+// host: a Rolldown `transform(code, id)` plugin instead of an esbuild
+// `onLoad` registered inside the PnP plugin.
+//
+// Why a separate plugin and not nested in the PnP loader, like esbuild?
+// Rolldown / Rollup's `transform` hooks all run in sequence on every
+// loaded module — there is no first-onLoad-wins race. So the PnP loader
+// (`@gjsify/rolldown-plugin-pnp`) is solely responsible for reading
+// zip-resident bytes; this plugin runs as a separate `transform` step
+// after the bytes have been loaded, regardless of which loader produced
+// them. No more F5-bug folklore.
+
+import { dirname, join, relative, resolve } from 'node:path';
+import type { Plugin } from 'rolldown';
+
+import { inlineStaticReads } from '../utils/inline-static-reads.js';
+
+export const REWRITE_FILTER = /\.(m?js|cjs|[cm]?tsx?)$/;
+const DIRNAME_DECL_RE = /(?:var|let|const)\s+__dirname\b|export\s+(?:var|let|const)\s+__dirname\b/;
+const FILENAME_DECL_RE = /(?:var|let|const)\s+__filename\b|export\s+(?:var|let|const)\s+__filename\b/;
+
+/** True when the rewriter wants to look at this path — node_modules + supported ext. */
+export function shouldRewrite(path: string): boolean {
+    return path.includes('node_modules') && REWRITE_FILTER.test(path);
+}
+
+/**
+ * Compute the directory the bundle's outfile lives in.
+ *
+ * For `import.meta.url` rewriting we emit a relative URL whose base is the
+ * bundle's `import.meta.url` — so we need to know where the bundle will be
+ * written. Both `output.file` and `output.dir` are accepted.
+ */
+export function getBundleDirFromOutput(opts: { file?: string; dir?: string }): string {
+    const outFile = opts.file ?? join(opts.dir ?? '.', 'bundle.mjs');
+    return dirname(resolve(outFile));
+}
+
+/** Pick the per-file loader Rolldown should re-parse with. */
+function moduleTypeForPath(path: string): 'ts' | 'js' {
+    const ext = path.split('.').pop() ?? 'js';
+    return ['ts', 'mts', 'cts', 'tsx'].includes(ext) ? 'ts' : 'js';
+}
+
+interface PreambleArgs {
+    needDirname: boolean;
+    needFilename: boolean;
+    dirnameDeclared: boolean;
+    filenameDeclared: boolean;
+    /** kind of rewrite: 'esm-relative' | 'esm-zip' | 'cjs-absolute' */
+    kind: 'esm-relative' | 'esm-zip' | 'cjs-absolute';
+    sourcePath: string;
+    sourceDir: string;
+    relDirWithSlash: string;
+    relPath: string;
+}
+
+function buildDirFilenamePreamble(args: PreambleArgs): string[] {
+    const lines: string[] = [];
+    if (args.needDirname && !args.dirnameDeclared) {
+        if (args.kind === 'esm-zip') {
+            lines.push(`var __dirname = new URL(".", import.meta.url).pathname.replace(/\\/$/, "");`);
+        } else if (args.kind === 'esm-relative') {
+            lines.push(`var __dirname = new URL(${JSON.stringify(args.relDirWithSlash)}, import.meta.url).pathname.replace(/\\/$/, "");`);
+        } else {
+            lines.push(`var __dirname = ${JSON.stringify(args.sourceDir)};`);
+        }
+    }
+    if (args.needFilename && !args.filenameDeclared) {
+        if (args.kind === 'esm-zip') {
+            lines.push(`var __filename = new URL(import.meta.url).pathname;`);
+        } else if (args.kind === 'esm-relative') {
+            lines.push(`var __filename = new URL(${JSON.stringify(args.relPath)}, import.meta.url).pathname;`);
+        } else {
+            lines.push(`var __filename = ${JSON.stringify(args.sourcePath)};`);
+        }
+    }
+    return lines;
+}
+
+export interface RewriteResult {
+    code: string;
+    moduleType?: 'ts' | 'js';
+    map?: null;
+}
+
+/**
+ * Pure rewriter — same body as the esbuild predecessor. Returns the rewritten
+ * code (and module type for re-parsing) or `null` if the file doesn't reference
+ * any of the patterns we care about.
+ */
+export function rewriteContents(
+    args: { path: string },
+    srcInput: string,
+    bundleDir: string,
+): RewriteResult | null {
+    if (!shouldRewrite(args.path)) return null;
+
+    // Step 1: inline statically-resolvable filesystem reads.
+    const inlined = inlineStaticReads(srcInput, args.path);
+    const src = inlined.contents;
+
+    const hasMetaUrl = src.includes('import.meta.url');
+    const hasDirname = src.includes('__dirname');
+    const hasFilename = src.includes('__filename');
+
+    if (!hasMetaUrl && !hasDirname && !hasFilename) {
+        if (inlined.inlined === 0) return null;
+        return { code: src, moduleType: moduleTypeForPath(args.path) };
+    }
+
+    // Step 2: classify rewrite kind.
+    const dir = dirname(args.path);
+    const relPath = hasMetaUrl ? relative(bundleDir, args.path) : '';
+    const isZipResident = hasMetaUrl && relPath.includes('.zip/');
+    const kind: 'esm-relative' | 'esm-zip' | 'cjs-absolute' =
+        !hasMetaUrl ? 'cjs-absolute' : isZipResident ? 'esm-zip' : 'esm-relative';
+
+    const preamble = buildDirFilenamePreamble({
+        needDirname: hasDirname,
+        needFilename: hasFilename,
+        dirnameDeclared: DIRNAME_DECL_RE.test(src),
+        filenameDeclared: FILENAME_DECL_RE.test(src),
+        kind,
+        sourcePath: args.path,
+        sourceDir: dir,
+        relPath,
+        relDirWithSlash: (relative(bundleDir, dir) || '.') + '/',
+    });
+
+    // Step 3: rewrite import.meta.url for the regular esm-relative case.
+    let code = src;
+    if (kind === 'esm-relative') {
+        const runtimeFileUrl = `new URL(${JSON.stringify(relPath)}, import.meta.url)`;
+        code = code.replace(/\bimport\.meta\.url\b/g, `${runtimeFileUrl}.href`);
+    }
+    if (preamble.length > 0) code = preamble.join('\n') + '\n' + code;
+
+    return { code, moduleType: moduleTypeForPath(args.path) };
+}
+
+export interface NodeModulesPathRewriteOptions {
+    /** Bundle output directory, derived from `output.file` / `output.dir`. */
+    bundleDir: string;
+}
+
+/**
+ * Build a Rolldown plugin that runs the path rewriter as a `transform(code, id)`
+ * hook with `order: 'post'` — runs after the deepkit/blueprint/css pre-transforms
+ * but still during module loading, before chunking.
+ */
+export function nodeModulesPathRewritePlugin(options: NodeModulesPathRewriteOptions): Plugin {
+    return {
+        name: 'gjsify-node-modules-path-rewrite',
+        transform: {
+            order: 'post' as const,
+            filter: { id: REWRITE_FILTER },
+            handler(code: string, id: string) {
+                if (!id.includes('node_modules')) return null;
+                const result = rewriteContents({ path: id }, code, options.bundleDir);
+                if (!result) return null;
+                return { code: result.code, map: null };
+            },
+        },
+    };
+}