@gjsify/rolldown-plugin-gjsify 0.4.25 → 0.4.26

package/lib/app/gjs.js

@@ -190,8 +190,8 @@ export const setupForGjs = async (input) => {
         // `firefox: 60 << 16` makes lightningcss flatten the source
         // into the subset GTK4 understands.
         cssAsStringPlugin({ targets: { firefox: 60 << 16 } }),
-        nodeModulesPathRewritePlugin({ bundleDir }),
-        processStubPlugin({ userBanner: input.userBanner }),
+        nodeModulesPathRewritePlugin({ bundleDir, runtimeResolve: format === 'esm' }),
+        processStubPlugin({ userBanner: input.userBanner, captureBundleUrl: format === 'esm' }),
         // resolveShebangLine returns null when disabled (false/undefined) and
         // the resolved line otherwise — also handles `${env:…}` expansion.
         (() => {

package/lib/plugins/bundle-url-banner.d.ts

@@ -0,0 +1 @@
+export declare const BUNDLE_URL_BANNER = "globalThis.__gjsifyBundleUrl??=import.meta.url;";

package/lib/plugins/bundle-url-banner.js

@@ -0,0 +1,13 @@
+// One-line banner that captures the bundle's own module URL into a global,
+// read by the module-resolve shim (shims/module-resolve.ts) as its
+// `createRequire` anchor.
+//
+// It must run at the top of the entry chunk — the single point where
+// `import.meta.url` is unambiguously the bundle's own URL, BEFORE the
+// node-modules path rewriter (rewrite-node-modules-paths.ts) could have
+// rewritten any per-module `import.meta.url`. `??=` keeps it idempotent and
+// cheap (a second entry in the same realm is a no-op).
+//
+// ESM-only — uses `import.meta.url`. Orchestrators gate its inclusion on
+// `format === 'esm'`, matching the `runtimeResolve` gate on the rewriter.
+export const BUNDLE_URL_BANNER = 'globalThis.__gjsifyBundleUrl??=import.meta.url;';

package/lib/plugins/process-stub.d.ts

@@ -24,5 +24,10 @@ export declare function composeBanner(stub: string, userBanner: string): string;
 export interface ProcessStubPluginOptions {
     /** User-supplied banner string. May contain a leading `#!shebang`. */
     userBanner?: string;
+    /**
+     * Prepend the bundle-URL anchor banner (read by the module-resolve shim).
+     * ESM-only — set by the orchestrator when `format === 'esm'`.
+     */
+    captureBundleUrl?: boolean;
 }
 export declare function processStubPlugin(options?: ProcessStubPluginOptions): Plugin;

package/lib/plugins/process-stub.js

@@ -1,3 +1,4 @@
+import { BUNDLE_URL_BANNER } from './bundle-url-banner.js';
 export const GJS_PROCESS_STUB = 'if(typeof globalThis.process==="undefined"){' +
     'const _s=imports.system,_G=imports.gi.GLib;' +
     // process.hrtime needs a `.bigint` property attached to the function
@@ -50,7 +51,10 @@ export function composeBanner(stub, userBanner) {
     return shebang + stub + (rest ? '\n' + rest : '');
 }
 export function processStubPlugin(options = {}) {
-    const banner = composeBanner(GJS_PROCESS_STUB, options.userBanner ?? '');
+    // The anchor capture must precede the process stub so it runs at the very
+    // top of the chunk (where `import.meta.url` is the bundle's own URL).
+    const stub = (options.captureBundleUrl ? BUNDLE_URL_BANNER : '') + GJS_PROCESS_STUB;
+    const banner = composeBanner(stub, options.userBanner ?? '');
     return {
         name: 'gjsify-process-stub',
         renderChunk: {

package/lib/plugins/rewrite-node-modules-paths.d.ts

@@ -3,36 +3,52 @@ export declare const REWRITE_FILTER: RegExp;
 /** True when the rewriter wants to look at this path — node_modules + supported ext. */
 export declare function shouldRewrite(path: string): boolean;
 /**
- * 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.
+ * Compute the directory the bundle's outfile lives in (used for the zip-resident
+ * check and the legacy relative paths). Both `output.file` and `output.dir` are
+ * accepted.
  */
 export declare function getBundleDirFromOutput(opts: {
     file?: string;
     dir?: string;
 }): string;
+/**
+ * The package-qualified spec for a node_modules file: everything after the LAST
+ * `node_modules/` segment. This is what the runtime resolver feeds to
+ * `createRequire(...).resolve` (via the package root).
+ *
+ *   ".../node_modules/typedoc/dist/lib/app.js"   → "typedoc/dist/lib/app.js"
+ *   ".../node_modules/@scope/name/sub.js"        → "@scope/name/sub.js"
+ *   ".../node_modules/a/node_modules/b/file.js"  → "b/file.js"
+ */
+export declare function extractPackageSpec(path: string): string;
 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.
+ * Pure rewriter. Returns the rewritten code (and module type for re-parsing) or
+ * `null` if the file references none of the patterns we care about.
+ *
+ * @param runtimeResolve  When true (ESM output, banner present), on-disk ESM
+ *   files resolve their location at runtime (case 1). When false, they fall back
+ *   to the legacy build-relative rewrite (case 2).
  */
 export declare function rewriteContents(args: {
     path: string;
-}, srcInput: string, bundleDir: string): RewriteResult | null;
+}, srcInput: string, bundleDir: string, runtimeResolve: boolean): RewriteResult | null;
 export interface NodeModulesPathRewriteOptions {
     /** Bundle output directory, derived from `output.file` / `output.dir`. */
     bundleDir: string;
+    /**
+     * Use runtime resolution for on-disk ESM files (case 1). Requires the
+     * bundle-URL banner — set by the orchestrator only for `format === 'esm'`.
+     * Defaults to false (legacy build-relative behavior).
+     */
+    runtimeResolve?: boolean;
 }
 /**
  * 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.
+ * hook with `order: 'post'`.
  */
 export declare function nodeModulesPathRewritePlugin(options: NodeModulesPathRewriteOptions): Plugin;

package/lib/plugins/rewrite-node-modules-paths.js

@@ -1,119 +1,215 @@
-// 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.
+// Per-source rewriter for `node_modules` files that reference `import.meta.url`,
+// `__dirname`, or `__filename`. These tokens normally point at the file's own
+// on-disk location; once the file is bundled, the bundler must rewrite them so
+// runtime data-file reads (a dep loading its own i18n JSON, `package.json`,
+// templates, …) still resolve.
 //
-// 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.
+// Cases, each with its own strategy:
+//
+//   1. on-disk ESM, runtime-resolve (`import.meta.url` present, not zip-resident,
+//      `format === 'esm'`)
+//      → rewrite to RUNTIME resolution via the `module-resolve` shim. The shim
+//        resolves the file's `<pkg>/<subpath>` from the bundle's actual location
+//        at run time, so the bundle works wherever it ends up — crucially, after
+//        being PUBLISHED in an npm package (where it sits at a different
+//        `node_modules` depth than at build time). See module-resolve.ts. Relies
+//        on the bundle-URL banner (bundle-url-banner.ts) having captured the
+//        anchor, hence the `runtimeResolve` gate.
+//
+//   2. on-disk ESM, legacy (same, but a non-ESM output format where the banner
+//      can't run)
+//      → the original behavior: rewrite to a path relative to the bundle's BUILD
+//        location. Correct only while bundle ↔ node_modules keep their build-time
+//        arrangement; preserved unchanged for the rare `--format iife|cjs` app
+//        build that can't host the `import.meta.url` anchor banner.
+//
+//   3. PnP zip-resident (`import.meta.url`, path inside a `.zip/`)
+//      → the file lives inside a Yarn-PnP zip; `import.meta.url` stays the
+//        bundle's own URL and `__dirname`/`__filename` derive from it.
+//
+//   4. CJS (`__dirname`/`__filename` only, no `import.meta.url`)
+//      → declare them from the file's absolute build path. NOTE: still
+//        build-location-coupled and shares the "breaks when published" class of
+//        bug case (1) fixes; injecting an ESM import into a CJS module is unsafe,
+//        so a CJS-safe runtime-resolve is tracked as a follow-up. ESM deps (the
+//        common data-reader shape, e.g. typedoc) take path (1).
+//
+// Hosting: a Rolldown `transform(code, id)` hook with `order: 'post'` — runs
+// after deepkit/blueprint/css pre-transforms but still during module loading,
+// before chunking.
 import { dirname, join, relative, resolve } from 'node:path';
 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/;
+// Bare specifier of the runtime module-path resolver shim (see module-resolve.ts).
+// No `.js` — must match the package's `exports` subpath key (exports maps are
+// exact-match), mirroring the `./shims/console-gjs` convention.
+const MODULE_RESOLVE_SHIM = '@gjsify/rolldown-plugin-gjsify/shims/module-resolve';
+// Our own shims (module-resolve, console-gjs) get bundled into user output, so
+// they live in `node_modules/@gjsify/rolldown-plugin-gjsify/{lib,src}/shims/`
+// when consumed — but they must NEVER be rewritten. In particular the
+// module-resolve shim DECLARES `__gjsifyModule*` and its comments mention
+// `import.meta.url`; the naive token check below would otherwise treat that as
+// a rewrite target and prepend a self-import that collides with its exports.
+const GJSIFY_SHIM_RE = /[\\/]rolldown-plugin-gjsify[\\/](?:lib|src)[\\/]shims[\\/]/;
 /** True when the rewriter wants to look at this path — node_modules + supported ext. */
 export function shouldRewrite(path) {
-    return path.includes('node_modules') && REWRITE_FILTER.test(path);
+    if (!path.includes('node_modules') || !REWRITE_FILTER.test(path))
+        return false;
+    if (GJSIFY_SHIM_RE.test(path))
+        return false;
+    return true;
 }
 /**
- * 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.
+ * Compute the directory the bundle's outfile lives in (used for the zip-resident
+ * check and the legacy relative paths). Both `output.file` and `output.dir` are
+ * accepted.
  */
 export function getBundleDirFromOutput(opts) {
     const outFile = opts.file ?? join(opts.dir ?? '.', 'bundle.mjs');
     return dirname(resolve(outFile));
 }
-/** Pick the per-file loader Rolldown should re-parse with. */
+/** Pick the per-file loader Rolldown should re-parse the rewritten code with. */
 function moduleTypeForPath(path) {
     const ext = path.split('.').pop() ?? 'js';
     return ['ts', 'mts', 'cts', 'tsx'].includes(ext) ? 'ts' : 'js';
 }
-function buildDirFilenamePreamble(args) {
-    const lines = [];
-    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)};`);
-        }
+/**
+ * The package-qualified spec for a node_modules file: everything after the LAST
+ * `node_modules/` segment. This is what the runtime resolver feeds to
+ * `createRequire(...).resolve` (via the package root).
+ *
+ *   ".../node_modules/typedoc/dist/lib/app.js"   → "typedoc/dist/lib/app.js"
+ *   ".../node_modules/@scope/name/sub.js"        → "@scope/name/sub.js"
+ *   ".../node_modules/a/node_modules/b/file.js"  → "b/file.js"
+ */
+export function extractPackageSpec(path) {
+    const marker = 'node_modules/';
+    const idx = path.lastIndexOf(marker);
+    return idx < 0 ? path : path.slice(idx + marker.length);
+}
+/** Whether the file needs a `var __dirname`/`__filename` declaration injected. */
+function needsDirnameDecl(src, flags) {
+    return flags.hasDirname && !DIRNAME_DECL_RE.test(src);
+}
+function needsFilenameDecl(src, flags) {
+    return flags.hasFilename && !FILENAME_DECL_RE.test(src);
+}
+/** Prepend preamble + (optional) shim import to the source. */
+function withPreamble(src, lines, importHeader) {
+    const parts = importHeader ? [importHeader, ...lines, src] : [...lines, src];
+    return parts.join('\n');
+}
+/**
+ * Case 1 — on-disk ESM, runtime-resolve. Rewrite the file to resolve its own
+ * location at runtime via the module-resolve shim — location-independent, so it
+ * survives being published/relocated. The fix for the "works in the workspace,
+ * crashes once installed" class of bug.
+ */
+function rewriteOnDiskEsm(src, path, flags) {
+    const spec = JSON.stringify(extractPackageSpec(path));
+    // Collect only the named imports we actually use — tree-shaking has nothing
+    // to prune and the import line stays honest.
+    const used = ['__gjsifyModuleUrl'];
+    const preamble = [];
+    if (needsDirnameDecl(src, flags)) {
+        preamble.push(`var __dirname = __gjsifyModuleDir(${spec});`);
+        used.push('__gjsifyModuleDir');
     }
-    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)};`);
-        }
+    if (needsFilenameDecl(src, flags)) {
+        preamble.push(`var __filename = __gjsifyModuleFile(${spec});`);
+        used.push('__gjsifyModuleFile');
+    }
+    const code = src.replace(/\bimport\.meta\.url\b/g, `__gjsifyModuleUrl(${spec})`);
+    const header = `import { ${used.join(', ')} } from ${JSON.stringify(MODULE_RESOLVE_SHIM)};`;
+    return { code: withPreamble(code, preamble, header), moduleType: moduleTypeForPath(path) };
+}
+/**
+ * Case 2 — on-disk ESM, legacy. Original build-relative behavior, kept for the
+ * rare non-ESM output format that can't host the bundle-URL anchor banner.
+ */
+function rewriteOnDiskEsmLegacy(src, path, bundleDir, flags) {
+    const relPath = relative(bundleDir, path);
+    const relDirWithSlash = (relative(bundleDir, dirname(path)) || '.') + '/';
+    const preamble = [];
+    if (needsDirnameDecl(src, flags)) {
+        preamble.push(`var __dirname = new URL(${JSON.stringify(relDirWithSlash)}, import.meta.url).pathname.replace(/\\/$/, "");`);
     }
-    return lines;
+    if (needsFilenameDecl(src, flags)) {
+        preamble.push(`var __filename = new URL(${JSON.stringify(relPath)}, import.meta.url).pathname;`);
+    }
+    const code = src.replace(/\bimport\.meta\.url\b/g, `new URL(${JSON.stringify(relPath)}, import.meta.url).href`);
+    return { code: withPreamble(code, preamble), moduleType: moduleTypeForPath(path) };
 }
 /**
- * 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.
+ * Case 3 — PnP zip-resident. Keep `import.meta.url` as the bundle's own URL and
+ * derive `__dirname`/`__filename` from it.
  */
-export function rewriteContents(args, srcInput, bundleDir) {
+function rewriteZipResident(src, path, flags) {
+    const preamble = [];
+    if (needsDirnameDecl(src, flags)) {
+        preamble.push(`var __dirname = new URL(".", import.meta.url).pathname.replace(/\\/$/, "");`);
+    }
+    if (needsFilenameDecl(src, flags)) {
+        preamble.push(`var __filename = new URL(import.meta.url).pathname;`);
+    }
+    return { code: withPreamble(src, preamble), moduleType: moduleTypeForPath(path) };
+}
+/**
+ * Case 4 — CJS (no `import.meta.url`). Declare `__dirname`/`__filename` from the
+ * absolute build path. Build-location-coupled — see file header note.
+ */
+function rewriteCjsAbsolute(src, path, flags) {
+    const preamble = [];
+    if (needsDirnameDecl(src, flags)) {
+        preamble.push(`var __dirname = ${JSON.stringify(dirname(path))};`);
+    }
+    if (needsFilenameDecl(src, flags)) {
+        preamble.push(`var __filename = ${JSON.stringify(path)};`);
+    }
+    return { code: withPreamble(src, preamble), moduleType: moduleTypeForPath(path) };
+}
+/**
+ * Pure rewriter. Returns the rewritten code (and module type for re-parsing) or
+ * `null` if the file references none of the patterns we care about.
+ *
+ * @param runtimeResolve  When true (ESM output, banner present), on-disk ESM
+ *   files resolve their location at runtime (case 1). When false, they fall back
+ *   to the legacy build-relative rewrite (case 2).
+ */
+export function rewriteContents(args, srcInput, bundleDir, runtimeResolve) {
     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) };
+    const flags = {
+        hasMetaUrl: src.includes('import.meta.url'),
+        hasDirname: src.includes('__dirname'),
+        hasFilename: src.includes('__filename'),
+    };
+    if (!flags.hasMetaUrl && !flags.hasDirname && !flags.hasFilename) {
+        // No tokens to rewrite — emit only if inlining changed something.
+        return inlined.inlined > 0 ? { code: src, moduleType: moduleTypeForPath(args.path) } : null;
     }
-    // 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 = !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`);
+    // Step 2: dispatch by case (see file header).
+    if (flags.hasMetaUrl) {
+        if (relative(bundleDir, args.path).includes('.zip/')) {
+            return rewriteZipResident(src, args.path, flags);
+        }
+        return runtimeResolve
+            ? rewriteOnDiskEsm(src, args.path, flags)
+            : rewriteOnDiskEsmLegacy(src, args.path, bundleDir, flags);
     }
-    if (preamble.length > 0)
-        code = preamble.join('\n') + '\n' + code;
-    return { code, moduleType: moduleTypeForPath(args.path) };
+    return rewriteCjsAbsolute(src, args.path, flags);
 }
 /**
  * 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.
+ * hook with `order: 'post'`.
  */
 export function nodeModulesPathRewritePlugin(options) {
+    const runtimeResolve = options.runtimeResolve ?? false;
     return {
         name: 'gjsify-node-modules-path-rewrite',
         transform: {
@@ -122,7 +218,7 @@ export function nodeModulesPathRewritePlugin(options) {
             handler(code, id) {
                 if (!id.includes('node_modules'))
                     return null;
-                const result = rewriteContents({ path: id }, code, options.bundleDir);
+                const result = rewriteContents({ path: id }, code, options.bundleDir, runtimeResolve);
                 if (!result)
                     return null;
                 return { code: result.code, map: null };

package/lib/shims/module-resolve.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Split a bundled-file spec into its package name and the path within the
+ * package. Handles scoped names:
+ *   "typedoc/dist/lib/app.js"   → { pkg: "typedoc",        subpath: "dist/lib/app.js" }
+ *   "@scope/name/sub/file.js"   → { pkg: "@scope/name",    subpath: "sub/file.js" }
+ *   "typedoc"                   → { pkg: "typedoc",        subpath: "" }
+ */
+export declare function splitPackageSpec(spec: string): {
+    pkg: string;
+    subpath: string;
+};
+/** Absolute path of the bundled dep file `<pkg>/<subpath>` at runtime. */
+export declare function __gjsifyModuleFile(spec: string): string;
+/** `file://` URL of `<pkg>/<subpath>` — replaces a rewritten `import.meta.url`. */
+export declare function __gjsifyModuleUrl(spec: string): string;
+/** Directory of `<pkg>/<subpath>` — replaces a rewritten `__dirname`. */
+export declare function __gjsifyModuleDir(spec: string): string;

package/lib/shims/module-resolve.js

@@ -0,0 +1,140 @@
+// Runtime resolver for the on-disk location of a bundled `node_modules` file.
+//
+// Why this exists
+// ---------------
+// `rewrite-node-modules-paths.ts` rewrites a bundled module's `import.meta.url`
+// / `__dirname` / `__filename` so that dynamic data-file reads (a dep loading
+// its own i18n JSON, `package.json`, templates, …) still find those files on
+// disk after bundling. The naive rewrite baked a path relative to the bundle's
+// BUILD location, which is only correct while the bundle and `node_modules/`
+// keep the arrangement they had at build time. Once the bundle is PUBLISHED in
+// an npm package and installed at `node_modules/<pkg>/bin/<bundle>`, that baked
+// path lands one `node_modules` level too deep → ENOENT at runtime.
+//
+// Instead we resolve the dep at RUNTIME from the bundle's actual location, so
+// it works wherever the bundle ends up.
+//
+// Three correctness constraints shape the implementation:
+//
+//  1. *Location anchor.* The resolver must anchor at the BUNDLE's URL, not its
+//     own. When a consumer bundles this shim it lives under
+//     `node_modules/@gjsify/rolldown-plugin-gjsify/...`, so the path rewriter
+//     would rewrite this file's own `import.meta.url` too. We therefore take no
+//     `import.meta.url` here and read the anchor from `globalThis.
+//     __gjsifyBundleUrl`, captured by a one-line banner at byte 0 of the bundle —
+//     the single point where `import.meta.url` is unambiguously the bundle's URL.
+//
+//  2. *exports-map safety.* `createRequire(...).resolve("<pkg>/<deep/path>")` is
+//     rejected by strict `"exports"` maps under Node's native `createRequire`
+//     (the `--app node` target), and `@gjsify/module` is exports-aware too. So
+//     we never resolve the deep path directly: we resolve the PACKAGE ROOT and
+//     join the subpath literally, which no `exports` map can block.
+//
+//  3. *Lazy / self-contained safety.* `import.meta.url` is normally a passive
+//     string — the extremely common `createRequire(import.meta.url)` pattern
+//     does NOT require the URL to point at an existing file (createRequire only
+//     resolves later, lazily). A self-contained bootstrap bundle (e.g. gjsify's
+//     own committed `cli.gjs.mjs`, which runs to CREATE `node_modules` before it
+//     exists) bundles its deps' code but has no `node_modules` at runtime. So
+//     resolution must never THROW: when a dep can't be resolved we fall back to
+//     the bundle's own location, keeping `createRequire(import.meta.url)` /
+//     `new URL(rel, import.meta.url)` valid (lazy) instead of crashing — exactly
+//     the pre-fix semantics for that case.
+//
+// @ts-ignore — `node:{module,url,path}` are resolved by the consumer's
+// `gjsify build` run (aliased to `@gjsify/{module,url,path}`), not by tsc here.
+import { createRequire } from 'node:module';
+// @ts-ignore — see above.
+import { pathToFileURL, fileURLToPath } from 'node:url';
+// @ts-ignore — see above.
+import { dirname, join } from 'node:path';
+/**
+ * Split a bundled-file spec into its package name and the path within the
+ * package. Handles scoped names:
+ *   "typedoc/dist/lib/app.js"   → { pkg: "typedoc",        subpath: "dist/lib/app.js" }
+ *   "@scope/name/sub/file.js"   → { pkg: "@scope/name",    subpath: "sub/file.js" }
+ *   "typedoc"                   → { pkg: "typedoc",        subpath: "" }
+ */
+export function splitPackageSpec(spec) {
+    const parts = spec.split('/');
+    const segments = spec.startsWith('@') ? 2 : 1;
+    return {
+        pkg: parts.slice(0, segments).join('/'),
+        subpath: parts.slice(segments).join('/'),
+    };
+}
+/** The bundle's own URL (set by the byte-0 banner). Throws only if the banner didn't run. */
+function bundleAnchorUrl() {
+    const anchor = globalThis.__gjsifyBundleUrl;
+    if (!anchor) {
+        throw new Error('gjsify: __gjsifyBundleUrl is not set — the bundle-URL banner did not run. ' +
+            'The module-resolve shim is only valid in single-file app builds (gjsify build --app gjs|node).');
+    }
+    return anchor;
+}
+// `createRequire` anchored at the bundle URL — built lazily so the banner is
+// guaranteed to have run, and so a build that never hits a rewritten read pays
+// nothing.
+let _resolve = null;
+function bundleResolve() {
+    if (!_resolve)
+        _resolve = createRequire(bundleAnchorUrl()).resolve;
+    return _resolve;
+}
+/**
+ * Find the on-disk root directory of `pkg`, exports-map-agnostic.
+ *
+ * `package.json` is resolvable for nearly every package and points straight at
+ * the root. When a strict `exports` map blocks it, fall back to the package's
+ * main entry (always an export) and derive the root from the
+ * `node_modules/<pkg>` boundary in its path. Throws when `pkg` is not installed.
+ */
+function resolvePackageRoot(pkg) {
+    const resolve = bundleResolve();
+    try {
+        return dirname(resolve(`${pkg}/package.json`));
+    }
+    catch {
+        const main = resolve(pkg);
+        const marker = `/node_modules/${pkg}/`;
+        const idx = main.lastIndexOf(marker);
+        return idx >= 0 ? main.slice(0, idx + marker.length - 1) : dirname(main);
+    }
+}
+// Per-spec memo — resolution walks the filesystem and bundled deps read their
+// data files repeatedly (per-locale i18n lookups, etc.).
+const _cache = new Map();
+/**
+ * Absolute on-disk path for a bundled dep file `<pkg>/<subpath>`, or — when the
+ * dep can't be resolved at runtime (no `node_modules`, e.g. a self-contained
+ * bootstrap bundle) — the bundle's own path as a non-throwing fallback. See
+ * constraint 3 in the file header.
+ */
+function resolveFile(spec) {
+    const cached = _cache.get(spec);
+    if (cached !== undefined)
+        return cached;
+    let abs;
+    try {
+        const { pkg, subpath } = splitPackageSpec(spec);
+        const root = resolvePackageRoot(pkg);
+        abs = subpath ? join(root, subpath) : root;
+    }
+    catch {
+        abs = fileURLToPath(bundleAnchorUrl());
+    }
+    _cache.set(spec, abs);
+    return abs;
+}
+/** Absolute path of the bundled dep file `<pkg>/<subpath>` at runtime. */
+export function __gjsifyModuleFile(spec) {
+    return resolveFile(spec);
+}
+/** `file://` URL of `<pkg>/<subpath>` — replaces a rewritten `import.meta.url`. */
+export function __gjsifyModuleUrl(spec) {
+    return pathToFileURL(resolveFile(spec)).href;
+}
+/** Directory of `<pkg>/<subpath>` — replaces a rewritten `__dirname`. */
+export function __gjsifyModuleDir(spec) {
+    return dirname(resolveFile(spec));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/rolldown-plugin-gjsify",
-    "version": "0.4.25",
+    "version": "0.4.26",
     "description": "Rolldown / Rollup / Vite plugin orchestrator for GJS, Node, and Browser targets",
     "type": "module",
     "main": "lib/index.js",
@@ -17,6 +17,9 @@
         },
         "./shims/console-gjs": {
             "default": "./lib/shims/console-gjs.js"
+        },
+        "./shims/module-resolve": {
+            "default": "./lib/shims/module-resolve.js"
         }
     },
     "files": [
@@ -45,11 +48,11 @@
     ],
     "license": "MIT",
     "dependencies": {
-        "@gjsify/console": "^0.4.25",
-        "@gjsify/resolve-npm": "^0.4.25",
-        "@gjsify/rolldown-plugin-deepkit": "^0.4.25",
-        "@gjsify/rolldown-plugin-pnp": "^0.4.25",
-        "@gjsify/vite-plugin-blueprint": "^0.4.25",
+        "@gjsify/console": "^0.4.26",
+        "@gjsify/resolve-npm": "^0.4.26",
+        "@gjsify/rolldown-plugin-deepkit": "^0.4.26",
+        "@gjsify/rolldown-plugin-pnp": "^0.4.26",
+        "@gjsify/vite-plugin-blueprint": "^0.4.26",
         "@rollup/pluginutils": "^5.3.0",
         "acorn": "^8.16.0",
         "acorn-walk": "^8.3.5",
@@ -57,7 +60,7 @@
         "lightningcss": "^1.32.0"
     },
     "peerDependencies": {
-        "@gjsify/lightningcss-native": "^0.4.25",
+        "@gjsify/lightningcss-native": "^0.4.26",
         "rolldown": "^1.0.0-rc.18"
     },
     "peerDependenciesMeta": {