@gjsify/rolldown-plugin-gjsify 0.23.0 → 0.24.2

package/lib/app/browser.js

@@ -4,10 +4,14 @@
 // (they appear transitively via `@gjsify/unit` and similar packages with
 // GJS-specific code paths). Bare Node specifiers + their `node:*` prefix
 // variants are routed to `@gjsify/<X>` via the curated
-// `ALIASES_NODE_FOR_BROWSER` table — the dynamic per-runtimes-triplet
-// resolver (`getDerivedAliasesSync`) finishes the routing in a second pass
-// (`@gjsify/<X>` → `@gjsify/<X>/globals` / `@gjsify/empty` depending on the
-// slot declaration).
+// `ALIASES_NODE_FOR_BROWSER` table, whose VALUES already carry the
+// per-runtimes-triplet slot routing (`@gjsify/<X>` → `@gjsify/<X>/browser` /
+// `/globals` / `@gjsify/empty`): that table is exported through
+// `withDerivedSlotRouting` in `@gjsify/resolve-npm`. Composition happens THERE,
+// not as a resolver second pass here — `aliasPlugin` resolves an alias target
+// in exactly one hop, because the map it receives is merged flat across tiers
+// and a chain would re-route user `--alias` targets too (full argument in
+// `withDerivedSlotRouting`'s doc comment and `plugins/alias.ts`).
 import { aliasPlugin } from '../plugins/alias.js';
 import { deepkitPlugin } from '@gjsify/rolldown-plugin-deepkit';
 import blueprintPlugin from '@gjsify/vite-plugin-blueprint';
@@ -15,6 +19,7 @@ import { ALIASES_NODE_FOR_BROWSER, getDerivedAliasesSync } from '@gjsify/resolve
 import { globToEntryPoints } from '../utils/entry-points.js';
 import { gjsImportsEmptyPlugin } from '../plugins/gjs-imports-empty.js';
 import { cssAsStringPlugin } from '../plugins/css-as-string.js';
+import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
 export const setupForBrowser = async (input) => {
     const userExternal = input.userExternal ?? [];
     const external = [...userExternal];
@@ -77,12 +82,26 @@ export const setupForBrowser = async (input) => {
         },
         treeshake: true,
     };
+    // The substitution table exactly as `aliasPlugin` receives it — shared with
+    // the unresolved-workspace-import guard below so the guard reports the same
+    // promise the alias layer made.
+    const aliasEntries = flattenAliases(aliasMap);
     const plugins = [
         gjsImportsEmptyPlugin(),
-        aliasPlugin({ entries: flattenAliases(aliasMap) }),
+        aliasPlugin({ entries: aliasEntries }),
         blueprintPlugin(),
         deepkitPlugin({ reflection: input.pluginOptions.reflection }),
         cssAsStringPlugin(),
+        // `order: 'post'` — see app/gjs.ts. The browser target's whole job is to
+        // replace Node builtins with their `@gjsify/*` browser entries; when one
+        // of those cannot be resolved, Rolldown externalises the ORIGINAL bare
+        // specifier and a browser cannot resolve it at all. There is no
+        // `node:`-shaped emit-time symptom here, so this guard is the only signal.
+        unresolvedWorkspaceImportPlugin({
+            target: 'browser',
+            aliases: aliasEntries,
+            isExternal: (id) => external.includes(id),
+        }),
     ];
     return { options, plugins };
 };

package/lib/app/gjs.d.ts

@@ -55,6 +55,30 @@ export declare const setupForGjs: (input: GjsFactoryInput) => Promise<GjsBuildCo
  * in `auto-globals.spec.ts` — canonical contract, change-detector status.
  */
 export declare function createGjsExternalsPredicate(userExternal?: string[]): (id: string) => boolean;
+/**
+ * Recognize the shims this plugin INJECTS into a `--app gjs` bundle
+ * (`shims/module-resolve`, `shims/console-gjs`, `shims/unicorn-magic`, …), in
+ * both bare-specifier and resolved-disk-path form.
+ *
+ * They must be force-inlined for exactly the reason `/register` subpaths are,
+ * and the failure is the same one: GJS has no `require` and its ESM loader has
+ * neither a node_modules walker nor `exports`-map support, so an EXTERNALIZED
+ * shim aborts the program at load:
+ *
+ *   Error: Calling `require` for
+ *   "@gjsify/rolldown-plugin-gjsify/shims/module-resolve" in an environment
+ *   that doesn't expose the `require` function
+ *
+ * The shim is not optional — the bundler injected it because the bundle needs
+ * it — so externalizing it can only ever produce an unloadable artifact. The
+ * carve-out short-circuits BEFORE the user-external check so `bundler.external`
+ * cannot override it, and it matches by SHAPE rather than an explicit list, so
+ * a shim added later is covered without touching this predicate.
+ *
+ * Scope is deliberately narrow: only OUR shim directory. A consumer package
+ * that happens to have a `shims/` folder is unaffected.
+ */
+export declare function isGjsifyShim(id: string): boolean;
 /**
  * Recognize the `/register` and `/register/<feature>` subpath shapes that
  * `--globals auto` injects into the bundle as side-effect imports.

package/lib/app/gjs.js

@@ -10,9 +10,12 @@
 // handled separately by `setupLib`.
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { aliasPlugin } from '../plugins/alias.js';
 import { externalsPlugin } from '../plugins/externals.js';
 import { napiNodeAddonPlugin } from '../plugins/napi-node-addon.js';
+import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
 import { deepkitPlugin } from '@gjsify/rolldown-plugin-deepkit';
 import blueprintPlugin from '@gjsify/vite-plugin-blueprint';
 import { getAliasesForGjs } from '../utils/alias.js';
@@ -23,35 +26,38 @@ import { cssAsStringPlugin } from '../plugins/css-as-string.js';
 import { shebangPlugin, resolveShebangLine, inputShebangStripPlugin } from '../plugins/shebang.js';
 import { wrapInputWithSideEffects } from '../utils/entry-wrapper.js';
 const _shimDir = dirname(fileURLToPath(import.meta.url));
+/**
+ * Resolve one of this package's bundled shims to an absolute path.
+ *
+ * `createRequire` is a NAMED IMPORT from `node:module`, never a bare
+ * `require(...)` — this source is ESM (see AGENTS.md "Our source is ESM —
+ * no bare `require`"). It is used here for its RESOLVER, which is
+ * `exports`-map aware, and only to answer "where does this subpath live";
+ * nothing is loaded through it.
+ */
 function resolveShim(shimName) {
     // Preferred: relative to this module's directory. Works under the
     // normal Node consumer flow where `_shimDir` = `<pkg>/lib/app/`.
     const relative = resolve(_shimDir, `../shims/${shimName}.js`);
-    let fs = null;
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        fs = require('node:fs');
-    }
-    catch {
-        return relative;
-    }
-    if (fs.existsSync(relative))
+    if (existsSync(relative))
         return relative;
     // Fallback: when the orchestrator is bundled into a single .mjs
     // (GJS-CLI self-host loop) `_shimDir` collapses to the bundle's
-    // own directory and the relative lookup misses. createRequire's
-    // resolver is `exports`-map-aware (Phase C), so the published
-    // subpath export `./shims/<name>` works under both Node and GJS
-    // without further walking. Each shim MUST be a `./shims/<name>`
-    // subpath export in package.json for this fallback to resolve.
+    // own directory and the relative lookup misses. The published subpath
+    // export `./shims/<name>` resolves under both Node and GJS without
+    // further walking. Each shim MUST be a `./shims/<name>` subpath export
+    // in package.json for this fallback to resolve.
     try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const Module = require('node:module');
-        const require_ = Module.createRequire(import.meta.url);
-        return require_.resolve(`@gjsify/rolldown-plugin-gjsify/shims/${shimName}`);
+        return createRequire(import.meta.url).resolve(`@gjsify/rolldown-plugin-gjsify/shims/${shimName}`);
     }
-    catch {
-        return relative;
+    catch (cause) {
+        // Both lookups failed — the shim is genuinely absent. Returning the
+        // unverified `relative` here would hand a non-existent path to the
+        // alias map, and the failure would resurface much later as an
+        // unrelated "could not resolve" naming a path nobody wrote. Name the
+        // actual problem, at the site that knows what it was looking for.
+        throw new Error(`@gjsify/rolldown-plugin-gjsify: cannot locate the "${shimName}" shim. ` +
+            `Tried ${relative} and the "./shims/${shimName}" subpath export.`, { cause });
     }
 }
 export const setupForGjs = async (input) => {
@@ -72,7 +78,12 @@ export const setupForGjs = async (input) => {
     //
     // `exactExternal` filters out register subpaths so a user external
     // entry can never override the force-inline carve-out below.
-    const exactExternal = ['cairo', 'gettext', 'system', ...userExternal.filter((id) => !isRegisterSubpath(id))];
+    const exactExternal = [
+        'cairo',
+        'gettext',
+        'system',
+        ...userExternal.filter((id) => !isRegisterSubpath(id) && !isGjsifyShim(id)),
+    ];
     const external = createGjsExternalsPredicate(userExternal);
     const format = input.pluginOptions.format ?? 'esm';
     const exclude = input.pluginOptions.exclude ?? [];
@@ -178,6 +189,13 @@ export const setupForGjs = async (input) => {
         treeshake: true,
     };
     const bundleDir = getBundleDirFromOutput(input.output);
+    // The substitution table exactly as `aliasPlugin` receives it — shared with
+    // the unresolved-workspace-import guard below so the guard reports the same
+    // promise the alias layer made.
+    const aliasEntries = {
+        'random-access-file': 'random-access-file/index.js',
+        ...flattenAliases(aliasMap),
+    };
     const plugins = [
         // Virtual-entry plugin runs FIRST so its resolveId/load match the
         // synthetic input ids that `wrapInputWithSideEffects` produces.
@@ -191,12 +209,7 @@ export const setupForGjs = async (input) => {
         // random-access-file's 'browser' field maps to a throwing stub; force
         // the fs-backed Node entry. Implemented via the gjsify alias plugin
         // as a direct entry-table override.
-        aliasPlugin({
-            entries: {
-                'random-access-file': 'random-access-file/index.js',
-                ...flattenAliases(aliasMap),
-            },
-        }),
+        aliasPlugin({ entries: aliasEntries }),
         // Transparent N-API `.node`-addon loader — the forward mirror of
         // `gjsGiNodePlugin`. Its `order:'pre'` resolveId claims a native-addon
         // acquisition (`bindings`/`node-gyp-build`/a direct `.node`/a napi-rs
@@ -229,6 +242,14 @@ export const setupForGjs = async (input) => {
             const line = resolveShebangLine(input.shebang);
             return shebangPlugin({ enabled: line !== null, line: line ?? undefined });
         })(),
+        // LAST claim on an id nothing else wanted (`order: 'post'`): a
+        // `@gjsify/*` substitution that cannot be resolved is a build ERROR, not
+        // a silent external. Without it Rolldown externalises the ORIGINAL
+        // specifier, exits 0, and writes a bundle stock GJS aborts on at load
+        // (`ImportError: Unsupported URI scheme for importing: node`) — the
+        // failure `utils/gjs-bundle-guard.ts` catches at emit time, caught here
+        // at its source instead, with the importer and the cause named.
+        unresolvedWorkspaceImportPlugin({ target: 'gjs', aliases: aliasEntries, isExternal: external }),
     ];
     return { options, plugins };
 };
@@ -271,7 +292,7 @@ function flattenAliases(map) {
 export function createGjsExternalsPredicate(userExternal = []) {
     const exact = ['cairo', 'gettext', 'system', ...userExternal];
     return (id) => {
-        if (isRegisterSubpath(id))
+        if (isRegisterSubpath(id) || isGjsifyShim(id))
             return false;
         if (id.startsWith('gi://'))
             return true;
@@ -280,6 +301,36 @@ export function createGjsExternalsPredicate(userExternal = []) {
         return false;
     };
 }
+/**
+ * Recognize the shims this plugin INJECTS into a `--app gjs` bundle
+ * (`shims/module-resolve`, `shims/console-gjs`, `shims/unicorn-magic`, …), in
+ * both bare-specifier and resolved-disk-path form.
+ *
+ * They must be force-inlined for exactly the reason `/register` subpaths are,
+ * and the failure is the same one: GJS has no `require` and its ESM loader has
+ * neither a node_modules walker nor `exports`-map support, so an EXTERNALIZED
+ * shim aborts the program at load:
+ *
+ *   Error: Calling `require` for
+ *   "@gjsify/rolldown-plugin-gjsify/shims/module-resolve" in an environment
+ *   that doesn't expose the `require` function
+ *
+ * The shim is not optional — the bundler injected it because the bundle needs
+ * it — so externalizing it can only ever produce an unloadable artifact. The
+ * carve-out short-circuits BEFORE the user-external check so `bundler.external`
+ * cannot override it, and it matches by SHAPE rather than an explicit list, so
+ * a shim added later is covered without touching this predicate.
+ *
+ * Scope is deliberately narrow: only OUR shim directory. A consumer package
+ * that happens to have a `shims/` folder is unaffected.
+ */
+export function isGjsifyShim(id) {
+    // Bare/fully-qualified: `@gjsify/rolldown-plugin-gjsify/shims/<name>`.
+    if (/@gjsify\/rolldown-plugin-gjsify\/shims\/[^?]+$/.test(id))
+        return true;
+    // Resolved disk path: `…/rolldown-plugin-gjsify/{lib,src}/shims/<name>.js`.
+    return /[\\/]rolldown-plugin-gjsify[\\/](?:lib|src)[\\/]shims[\\/]/.test(id);
+}
 /**
  * Recognize the `/register` and `/register/<feature>` subpath shapes that
  * `--globals auto` injects into the bundle as side-effect imports.

package/lib/app/index.d.ts

@@ -1,4 +1,4 @@
-export { setupForGjs, isRegisterSubpath, createGjsExternalsPredicate } from './gjs.js';
+export { setupForGjs, isRegisterSubpath, isGjsifyShim, createGjsExternalsPredicate } from './gjs.js';
 export type { GjsBuildConfig, GjsFactoryInput } from './gjs.js';
 export { setupForNode, enableGjsRegistersForNode, isGjsSourceBuild } from './node.js';
 export type { NodeBuildConfig, NodeFactoryInput } from './node.js';

package/lib/app/index.js

@@ -1,4 +1,4 @@
-export { setupForGjs, isRegisterSubpath, createGjsExternalsPredicate } from './gjs.js';
+export { setupForGjs, isRegisterSubpath, isGjsifyShim, createGjsExternalsPredicate } from './gjs.js';
 export { setupForNode, enableGjsRegistersForNode, isGjsSourceBuild } from './node.js';
 export { setupForBrowser } from './browser.js';
 export { setupForNativescript } from './nativescript.js';

package/lib/app/nativescript.js

@@ -16,10 +16,21 @@
 // GJS-specific code paths that never execute on NS.
 //
 // Bare Node specifiers + their `node:*` prefix variants are routed to
-// `@gjsify/<X>` via the curated `ALIASES_NODE_FOR_NATIVESCRIPT` table — the
-// dynamic per-runtimes-triplet resolver (`getDerivedAliasesSync`) finishes
-// the routing in a second pass (`@gjsify/<X>` → `@gjsify/<X>/globals` /
-// `@gjsify/empty` depending on the slot declaration).
+// `@gjsify/<X>` via the curated `ALIASES_NODE_FOR_NATIVESCRIPT` table. Unlike
+// the browser table, this one is NOT passed through `withDerivedSlotRouting`:
+// slot routing would only change 4 of its 122 entries and all four are
+// regressions — `fs`/`fs/promises` (+ their `node:` forms) deliberately point
+// at `@gjsify/native-fs-bridge`, which declares `nativescript: "native"` in the
+// "this package IS the native implementation" sense and therefore routes to a
+// `globals.mjs` it does not ship → `@gjsify/empty`. The slot vocabulary's
+// `native` means "the RUNTIME provides this, use its value", so the bridge
+// packages are mis-declared; that is tracked in STATUS.md and must be settled
+// before this table is composed. A direct `import … from
+// '@gjsify/native-fs-bridge'` already hits the derived map (plain key hit) and
+// is emptied TODAY — same root cause, listed in the same TODO.
+//
+// Derived `@gjsify/<X>` entries are merged into the map below, so an import by
+// PACKAGE NAME still routes per its declared slot in a single hop.
 //
 // No `cssAsStringPlugin` (NativeScript ships its own CSS pipeline as part
 // of `@nativescript/core`) and no `blueprintPlugin` (Blueprint is GTK-only).
@@ -29,6 +40,7 @@ import { ALIASES_NODE_FOR_NATIVESCRIPT, getDerivedAliasesSync } from '@gjsify/re
 import { globToEntryPoints } from '../utils/entry-points.js';
 import { gjsImportsEmptyPlugin } from '../plugins/gjs-imports-empty.js';
 import { platformResolvePlugin, detectNativescriptPlatform, nativescriptPlatformDefines, } from '../plugins/platform-resolve.js';
+import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
 export const setupForNativescript = async (input) => {
     const userExternal = input.userExternal ?? [];
     const external = [...userExternal];
@@ -105,18 +117,32 @@ export const setupForNativescript = async (input) => {
         },
         treeshake: true,
     };
+    // The substitution table exactly as `aliasPlugin` receives it — shared with
+    // the unresolved-workspace-import guard below so the guard reports the same
+    // promise the alias layer made.
+    const aliasEntries = flattenAliases(aliasMap);
     const plugins = [
         gjsImportsEmptyPlugin(),
         // Platform-specific source variants (`*.android` / `*.ios` /
         // `*.native`) win over the base file — resolved BEFORE the Node-builtin
         // alias routing so a platform fork of a portable module is honored.
         platformResolvePlugin({ platform }),
-        aliasPlugin({ entries: flattenAliases(aliasMap) }),
+        aliasPlugin({ entries: aliasEntries }),
         // NO blueprintPlugin — Blueprint is a GTK-specific UI DSL
         // NO cssAsStringPlugin — NS ships its own CSS pipeline via
         // @nativescript/core; .css imports are handled by the consuming
         // @nativescript/webpack or @nativescript/vite build
         deepkitPlugin({ reflection: input.pluginOptions.reflection }),
+        // `order: 'post'` — see app/gjs.ts. Native-bridge identifiers
+        // (`java.*`, `NS*`, …) are ambient GLOBALS on this target, never
+        // imports, so they never reach this hook; only a `@gjsify/*` edge does,
+        // and on NS as everywhere else an unresolvable one is a broken bundle
+        // rather than something the runtime will provide.
+        unresolvedWorkspaceImportPlugin({
+            target: 'nativescript',
+            aliases: aliasEntries,
+            isExternal: (id) => external.includes(id),
+        }),
     ];
     return { options, plugins };
 };

package/lib/app/node.js

@@ -14,6 +14,7 @@ import { nodeModulesPathRewritePlugin, getBundleDirFromOutput } from '../plugins
 import { cssAsStringPlugin } from '../plugins/css-as-string.js';
 import { gjsImportsEmptyPlugin } from '../plugins/gjs-imports-empty.js';
 import { gjsGiNodePlugin, gjsBuiltinModulesNodePlugin } from '../plugins/gjs-gi-node.js';
+import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
 import { wrapInputWithSideEffects } from '../utils/entry-wrapper.js';
 /**
  * Side-effect specifier the node target injects when GJS ambient globals
@@ -219,6 +220,10 @@ export const setupForNode = async (input) => {
         ...input.pluginOptions.aliases,
         ...input.userAliases,
     };
+    // The substitution table exactly as `aliasPlugin` receives it — shared with
+    // the unresolved-workspace-import guard below so the guard reports the same
+    // promise the alias layer made.
+    const aliasEntries = flattenAliases(aliasMap);
     const bundleDir = getBundleDirFromOutput(input.output);
     // Rolldown's CJS interop wraps bundled CJS via `__commonJSMin` and
     // routes external Node-builtin `require()` through `__require` —
@@ -317,7 +322,7 @@ export const setupForNode = async (input) => {
         // `requireGi`, exactly like the ambient-globals case. Same predicate as
         // the register-alias lift above — one question, one flag.
         gjsImportsEmptyPlugin({ emptyGirs: !gjsSourceBuild }),
-        aliasPlugin({ entries: flattenAliases(aliasMap) }),
+        aliasPlugin({ entries: aliasEntries }),
         // Blueprint (.blp → XML string): the reverse bridge runs REAL GTK on
         // Node, so a GJS app entry (composite-template windows) must build for
         // `--app node` too. Only claims `.blp` files — inert for plain-Node
@@ -334,6 +339,13 @@ export const setupForNode = async (input) => {
         // symptom). A plain-Node bundle (no node-gi) keeps the CSS pristine.
         cssAsStringPlugin(input.pluginOptions.nodeGiGlobalsInject ? { targets: { firefox: 60 << 16 } } : {}),
         nodeModulesPathRewritePlugin({ bundleDir }),
+        // `order: 'post'` — fires only for ids nothing above claimed, i.e. the
+        // ones headed for Rolldown's unresolved-import → external fallback. The
+        // node target has no `node:`-shaped symptom for the emit-time guard to
+        // detect (its `node:` builtins ARE external by policy), so this is the
+        // ONLY thing standing between an unbuilt `@gjsify/*` workspace edge and
+        // a bundle that re-imports the bare specifier at runtime.
+        unresolvedWorkspaceImportPlugin({ target: 'node', aliases: aliasEntries, isExternal: external }),
     ];
     return { options, plugins };
 };

package/lib/index.d.ts

@@ -11,10 +11,14 @@ export { textLoaderPlugin } from './plugins/text-loader.js';
 export type { TextLoaderPluginOptions, LoaderKind } from './plugins/text-loader.js';
 export { shebangPlugin, GJS_SHEBANG, NODE_SHEBANG, expandEnvTemplate, resolveShebangLine } from './plugins/shebang.js';
 export type { ShebangPluginOptions } from './plugins/shebang.js';
+export { aliasPlugin } from './plugins/alias.js';
+export type { AliasPluginOptions } from './plugins/alias.js';
 export { gjsImportsEmptyPlugin } from './plugins/gjs-imports-empty.js';
 export { externalsPlugin } from './plugins/externals.js';
 export type { ExternalsPredicate, ExternalsPluginOptions } from './plugins/externals.js';
-export { napiNodeAddonPlugin, resolveAddonPath, nearestPackageRoot, classifySpecifier, directNodeShim, nodeGypBuildShim, bindingsShim, napiRsShim, isNapiRsPackageJson, detectNapiRsEntry, AddonNotBuiltError, } from './plugins/napi-node-addon.js';
+export { unresolvedWorkspaceImportPlugin, classifyImport, isWorkspaceSpecifier, formatUnresolvedWorkspaceImport, buildReverseAliasIndex, UnresolvedWorkspaceImportError, } from './plugins/unresolved-workspace-import.js';
+export type { WorkspaceImportGuardOptions, WorkspaceImportGuardTarget, ImportVerdict, ClassifyImportInput, UnresolvedWorkspaceImportDetails, } from './plugins/unresolved-workspace-import.js';
+export { napiNodeAddonPlugin, resolveAddonPath, nearestPackageRoot, classifySpecifier, directNodeShim, nodeGypBuildShim, bindingsShim, napiRsShim, ADDON_FILTER_RE, isNapiRsPackageJson, isNapiRsSibling, detectNapiRsEntry, AddonNotBuiltError, } from './plugins/napi-node-addon.js';
 export type { NapiNodeAddonPluginOptions, AddonPackageJson } from './plugins/napi-node-addon.js';
 export { platformResolvePlugin, detectNativescriptPlatform, nativescriptPlatformDefines, } from './plugins/platform-resolve.js';
 export type { PlatformResolvePluginOptions, NativescriptPlatform } from './plugins/platform-resolve.js';

package/lib/index.js

@@ -8,9 +8,11 @@ export { processStubPlugin, GJS_PROCESS_STUB, composeBanner } from './plugins/pr
 export { cssAsStringPlugin } from './plugins/css-as-string.js';
 export { textLoaderPlugin } from './plugins/text-loader.js';
 export { shebangPlugin, GJS_SHEBANG, NODE_SHEBANG, expandEnvTemplate, resolveShebangLine } from './plugins/shebang.js';
+export { aliasPlugin } from './plugins/alias.js';
 export { gjsImportsEmptyPlugin } from './plugins/gjs-imports-empty.js';
 export { externalsPlugin } from './plugins/externals.js';
-export { napiNodeAddonPlugin, resolveAddonPath, nearestPackageRoot, classifySpecifier, directNodeShim, nodeGypBuildShim, bindingsShim, napiRsShim, isNapiRsPackageJson, detectNapiRsEntry, AddonNotBuiltError, } from './plugins/napi-node-addon.js';
+export { unresolvedWorkspaceImportPlugin, classifyImport, isWorkspaceSpecifier, formatUnresolvedWorkspaceImport, buildReverseAliasIndex, UnresolvedWorkspaceImportError, } from './plugins/unresolved-workspace-import.js';
+export { napiNodeAddonPlugin, resolveAddonPath, nearestPackageRoot, classifySpecifier, directNodeShim, nodeGypBuildShim, bindingsShim, napiRsShim, ADDON_FILTER_RE, isNapiRsPackageJson, isNapiRsSibling, detectNapiRsEntry, AddonNotBuiltError, } from './plugins/napi-node-addon.js';
 export { platformResolvePlugin, detectNativescriptPlatform, nativescriptPlatformDefines, } from './plugins/platform-resolve.js';
 export * from './plugin.js';
 import { gjsifyPlugin } from './plugin.js';

package/lib/plugins/alias.js

@@ -20,6 +20,38 @@
 // resolve through the "import" condition (Rolldown's default), bypassing the
 // `cjs-compat.cjs` shim that unwraps named-export ESM modules to their
 // constructor — breaking `util.inherits(Child, Stream)` patterns.
+//
+// ── Two invariants this plugin holds ────────────────────────────────────────
+//
+// 1. **Gjsify-generated modules are NOT aliased.** An import whose importer is
+//    a `\0gjsify-*` virtual module (`isGjsifyVirtualModuleId`) is left alone.
+//    We wrote that module's source; it names the RUNTIME module it needs and
+//    must get exactly that. The motivating failure: `gjsGiNodePlugin`'s
+//    `import { createRequire } from 'node:module'` was rewritten onto the
+//    `@gjsify/module` polyfill by the consumer harness's
+//    `--alias node:module=@gjsify/module`, so the bundle called the polyfill's
+//    `createRequire` at top level before its GLib proxy existed
+//    (`TypeError: … reading 'filename_from_uri'`) — and the polyfill's own
+//    Gio-backed loader can only reach GLib THROUGH the module it was being
+//    asked to load. The guard is importer-based rather than a per-specifier
+//    carve-out so it covers every current and future virtual module (entry
+//    wrapper, gi-node, napi-addon, gjs-imports-empty).
+//
+// 2. **An alias target is TERMINAL — exactly one hop, never a chain.** The
+//    `entries` map handed in is already MERGED across tiers (derived slot
+//    routing → curated `ALIASES_*` tables → per-target overrides → user
+//    `--alias`, later wins, see `app/*.ts`), so the tier a value came from is
+//    no longer recoverable here. Re-feeding a target through the table would
+//    therefore apply slot routing to USER aliases too, which is precisely what
+//    must not happen: `scripts/node-gi-consumer-harness.mjs` builds
+//    `--alias node:<x>=@gjsify/<x>` to put the POLYFILL under test behind a
+//    Node builtin, and 34 of those polyfills declare `runtimes.node: "native"`
+//    — a second hop would silently route them back to `@gjsify/<x>/globals`
+//    (i.e. Node's own builtin) and the suite would measure nothing. The
+//    "second pass" of the slot-routing model is a COMPOSITION concern, and it
+//    is resolved where the tiers are still distinguishable — see
+//    `withDerivedSlotRouting` in `@gjsify/resolve-npm`.
+import { isGjsifyVirtualModuleId } from '../utils/virtual-module-id.js';
 export function aliasPlugin(options) {
     const entries = options.entries;
     return {
@@ -27,6 +59,10 @@ export function aliasPlugin(options) {
         resolveId: {
             order: 'pre',
             async handler(source, importer, extraOptions) {
+                // Invariant 1 — never rewrite an import that WE generated.
+                if (isGjsifyVirtualModuleId(importer)) {
+                    return null;
+                }
                 if (!Object.prototype.hasOwnProperty.call(entries, source)) {
                     return null;
                 }

package/lib/plugins/css-as-string.js

@@ -121,7 +121,32 @@ async function tryLoadNativeBundler() {
     }
 }
 async function loadNpmBundler() {
-    const { bundleAsync } = await import('lightningcss');
+    // INDIRECT specifier, for the same reason `tryLoadNativeBundler` uses one:
+    // keep this acquisition out of the BUILD graph so it is resolved at
+    // runtime only. npm `lightningcss` is a napi-rs package, and a static
+    // `import('lightningcss')` here put its generated loader into the module
+    // graph of every `--app gjs` bundle — including the CLI's own committed
+    // `dist/cli.gjs.mjs`.
+    //
+    // That is what made the committed bundle ENVIRONMENT-DEPENDENT. With
+    // `@gjsify/napi` resolvable, `napiNodeAddonPlugin` rewrites the loader to a
+    // `loadAddon()` shim and inlines it; without it the plugin declines and the
+    // import stays external. Two different module graphs, so the minifier
+    // assigns different variable names, so the artifact stops reproducing from
+    // its own source (`verify-committed-bundles` red, first difference at byte
+    // 275: `r=` vs `a=` for `globalThis.imports.gi.GLib`). A toolchain artifact
+    // must not depend on whether an optional package happened to be installed
+    // when it was built.
+    //
+    // Nothing is lost under GJS: the documented GJS backend is
+    // `@gjsify/lightningcss-native` (above), and this npm fallback was never
+    // actually usable there — its `.node` cannot load under GJS without a
+    // build-time rewrite, and the only arches where that rewrite is possible
+    // (`@gjsify/napi`: linux-x64, darwin-arm64) are arches where the native
+    // bridge exists anyway. On Node this is unchanged: `lightningcss` is a real
+    // `dependency` of this package, so the runtime resolve finds it.
+    const specifier = 'lightningcss';
+    const { bundleAsync } = (await import(/* @vite-ignore */ specifier));
     return async (filename, targets) => {
         const result = await bundleAsync({
             filename,

package/lib/plugins/gjs-gi-node.js

@@ -27,7 +27,11 @@
 // Portability note (same as `gjs-imports-empty.ts`): the `filter` is a Rolldown
 // fast-path; the internal guard in the handler is the load-bearing check so the
 // plugin is correct even when the filter does not pre-filter (e.g. under Vite).
-const GI_NODE_VIRTUAL_PREFIX = '\0gjsify-gi-node:';
+import { GJSIFY_VIRTUAL_PREFIX } from '../utils/virtual-module-id.js';
+// Derived from the shared prefix so `isGjsifyVirtualModuleId` recognises these
+// ids — that is what keeps the `node:module` import below bound to the RUNTIME's
+// `createRequire` even when the build carries a user `--alias node:module=…`.
+const GI_NODE_VIRTUAL_PREFIX = `${GJSIFY_VIRTUAL_PREFIX}gi-node:`;
 /** Parse a `gi://Ns?version=X` specifier into its namespace + optional version. */
 export function parseGiSpecifier(source) {
     if (!source.startsWith('gi://'))

package/lib/plugins/gjs-imports-empty.js

@@ -31,7 +31,8 @@
 // dev server) the handler may receive ALL ids. The internal guard below makes
 // the plugin correct regardless of whether the filter pre-filtered — it is
 // the load-bearing check; the `filter` is a defense-in-depth optimization.
-const GJSIMPORTS_VIRTUAL_ID = '\0gjsify-empty-gjs-import';
+import { GJSIFY_VIRTUAL_PREFIX } from '../utils/virtual-module-id.js';
+const GJSIMPORTS_VIRTUAL_ID = `${GJSIFY_VIRTUAL_PREFIX}empty-gjs-import`;
 export function gjsImportsEmptyPlugin(options = {}) {
     const emptyGirs = options.emptyGirs ?? true;
     // When `@girs/*` is carved out, only `gi://*` reaches the empty redirect.

package/lib/plugins/napi-node-addon.d.ts

@@ -1,4 +1,13 @@
 import type { Plugin } from 'rolldown';
+/**
+ * Fast-path filter (superset of what `claimSpecifier` claims). Handler re-checks.
+ *
+ * Exported so `napi-node-addon.spec.ts` can assert its Rust-compatibility (see
+ * {@link BARE_SPECIFIER_RE}) — a JS-only construct here disables the plugin
+ * entirely under `@gjsify/rolldown-native`, and no build-level test would see
+ * it, because every addon gate drives the Node CLI entry.
+ */
+export declare const ADDON_FILTER_RE: RegExp;
 /** Options for {@link napiNodeAddonPlugin}. */
 export interface NapiNodeAddonPluginOptions {
     /**
@@ -54,6 +63,8 @@ export declare function classifySpecifier(source: string): {
 export interface AddonPackageJson {
     name?: string;
     main?: string;
+    module?: string;
+    exports?: unknown;
     browser?: string;
     napi?: unknown;
     optionalDependencies?: Record<string, string>;
@@ -65,11 +76,13 @@ export interface AddonPackageJson {
  *   (a) a top-level `napi` config OBJECT (`{ binaryName, targets, … }`) — the
  *       napi-rs CLI's own build block. An ordinary npm package never declares a
  *       `napi` object at the manifest root.
- *   (b) at least one `optionalDependencies` entry named `<self>-<triple>` — the
- *       napi-rs prebuilt-binary convention (`@node-rs/argon2` ships
- *       `@node-rs/argon2-linux-x64-gnu`, …). The key MUST start with the
- *       package's own name plus `-` AND end in a platform triple, so a normal
- *       optional dep (`fsevents`) can't match.
+ *   (b) at least one `optionalDependencies` entry that is a platform SIBLING
+ *       (see {@link isNapiRsSibling}) — the napi-rs prebuilt-binary convention,
+ *       under either naming scheme: `<self>-<triple>` (`@node-rs/argon2` ships
+ *       `@node-rs/argon2-linux-x64-gnu`) or `<napi.packageName>-<triple>`
+ *       (`rolldown` ships `@rolldown/binding-linux-x64-gnu`). The key MUST
+ *       carry a known prefix AND end in a platform triple, so a normal optional
+ *       dep (`fsevents`) can't match.
  *
  * Neither fires on a normal package, so pairing this with the "resolved file IS
  * the package's own native main entry" check (see {@link detectNapiRsEntry})
@@ -88,6 +101,13 @@ export declare function detectNapiRsEntry(entryFile: string): {
     pkgRoot: string;
     pkg: AddonPackageJson;
 } | null;
+/**
+ * Is `dep` a platform sibling of `pkg` — `<prefix>-<triple>` for one of the
+ * prefixes above? Both halves must hold: a bare prefix match would claim an
+ * ordinary dependency, and a bare triple match would claim an unrelated
+ * package's binaries. Exported for the unit tests.
+ */
+export declare function isNapiRsSibling(pkg: AddonPackageJson, dep: string): boolean;
 /**
  * Transparent `.node`-addon loader for `gjsify build --app gjs`.
  *