@gjsify/rolldown-plugin-gjsify 0.22.0 → 0.24.1

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';

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,8 +10,11 @@
 // 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 { deepkitPlugin } from '@gjsify/rolldown-plugin-deepkit';
 import blueprintPlugin from '@gjsify/vite-plugin-blueprint';
 import { getAliasesForGjs } from '../utils/alias.js';
@@ -22,35 +25,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) => {
@@ -71,7 +77,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 ?? [];
@@ -196,6 +207,17 @@ export const setupForGjs = async (input) => {
                 ...flattenAliases(aliasMap),
             },
         }),
+        // 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
+        // platform sibling) and rewrites it to a virtual module returning
+        // `loadAddon('<abs .node>')` from `@gjsify/napi`. Placed AFTER aliasPlugin
+        // (so a user alias that pins an addon's native entry applies first) and
+        // BEFORE externalsPlugin (so the addon acquisition is claimed before the
+        // externals policy sees it). `@gjsify/napi` is BUNDLED, not external.
+        // Inert unless such a specifier is in the graph — every other id passes
+        // through. Always-on for `--app gjs`; never registered for node/browser/ns.
+        napiNodeAddonPlugin(),
         // Enforce the full `--app gjs` externals policy (gi:// prefix,
         // exact names, register-subpath force-inline) via resolveId —
         // the only form BOTH engines honour (the native engine drops
@@ -259,7 +281,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;
@@ -268,6 +290,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,6 +1,6 @@
-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 } from './node.js';
+export { setupForNode, enableGjsRegistersForNode, isGjsSourceBuild } from './node.js';
 export type { NodeBuildConfig, NodeFactoryInput } from './node.js';
 export { setupForBrowser } from './browser.js';
 export type { BrowserBuildConfig, BrowserFactoryInput } from './browser.js';

package/lib/app/index.js

@@ -1,4 +1,4 @@
-export { setupForGjs, isRegisterSubpath, createGjsExternalsPredicate } from './gjs.js';
-export { setupForNode, enableGjsRegistersForNode } from './node.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).

package/lib/app/node.d.ts

@@ -1,14 +1,16 @@
 import type { RolldownOptions, RolldownPluginOption } from 'rolldown';
 import type { PluginOptions } from '../types/plugin-options.js';
 /**
- * Reverse-bridge register routing: a node build with an EXPLICIT `--globals`
- * register-inject stub (`pluginOptions.autoGlobalsInject`, set by the CLI for
- * `--app node` when the user names globals — e.g. `--globals auto,dom`) is a
- * genuine GJS source that needs the REAL `@gjsify/*` register bodies (document,
- * HTMLCanvasElement, matchMedia, …) running over `@gjsify/node-gi`, not the
- * default `@gjsify/empty` stubs that keep cross-platform node bundles loadable
+ * Reverse-bridge register routing: a node build of a GENUINE GJS SOURCE needs
+ * the REAL `@gjsify/*` register bodies (document, HTMLCanvasElement, the `'2d'`
+ * context factory, matchMedia, …) running over `@gjsify/node-gi`, not the
+ * default `@gjsify/empty` stubs that keep CROSS-PLATFORM node bundles loadable
  * on plain Node.
  *
+ * Applied by `setupForNode` when `isGjsSourceBuild` is true — see the comment
+ * on that flag for why BOTH reverse-bridge signals qualify, not just the
+ * explicit `--globals` stub.
+ *
  * Two adjustments over the standard node alias map:
  *  1. every `<pkg>/register…` → `@gjsify/empty` entry is DROPPED so the
  *     register import resolves to its real body;
@@ -18,10 +20,42 @@ import type { PluginOptions } from '../types/plugin-options.js';
  *     specifiers resolve on node exactly as they do on gjs.
  *
  * Applied to the BASE map only — `pluginOptions.aliases` / user aliases still
- * override. Without the inject stub the map is untouched (the plain-Node
+ * override. On a non-reverse-bridge build the map is untouched (the plain-Node
  * loadability guarantee for cross-platform packages is not regressed).
  */
 export declare function enableGjsRegistersForNode(baseAliases: Record<string, string>): Record<string, string>;
+/**
+ * Is this `--app node` build a GENUINE GJS SOURCE going through the node-gi
+ * reverse bridge, rather than the node target of a cross-platform package?
+ *
+ * Two signals qualify, and BOTH must gate the same things:
+ *  - `nodeGiGlobalsInject` — the CLI's post-tree-shake detection found bare GJS
+ *    ambient globals (`print`/`imports`/`ARGV`/…) in the bundled output;
+ *  - `registerInject` (the `--globals` auto/explicit inject stub) — the user
+ *    asked for GJS registers on the node target explicitly.
+ *
+ * This predicate exists as ONE named function because the two consumers used to
+ * ask the question separately and disagree: `emitGirs` took the union while the
+ * register-alias lift took only the explicit stub. A reverse-bridge build then
+ * got its `@girs/*` routed through to `requireGi` while a `/register`
+ * side-effect import in the SAME graph was still emptied to `@gjsify/empty` —
+ * silently dropping `@gjsify/dom-elements/register/canvas`'s `'2d'` context
+ * factory, so `@gjsify/canvas2d`'s `Canvas2DBridge` never fired `onReady`.
+ *
+ * A build with NEITHER signal is byte-unchanged: the `@gjsify/empty` register
+ * routing and the `@girs/*` emptying both stay, so a cross-platform package's
+ * node bundle keeps loading on plain Node without node-gi installed.
+ *
+ * KNOWN NARROWNESS (pre-dates this predicate, tracked in STATUS.md): the
+ * `nodeGiGlobalsInject` detector keys on BARE ambient globals, so a genuine GJS
+ * source that uses `gi://` but logs via `console.log` and passes no `--globals`
+ * is not recognised — its `@girs/*` AND its registers are both emptied. The two
+ * are now at parity; widening the signal itself is the separate fix.
+ */
+export declare function isGjsSourceBuild(options: {
+    nodeGiGlobalsInject?: boolean;
+    registerInject?: string | undefined;
+}): boolean;
 export interface NodeBuildConfig {
     options: RolldownOptions;
     plugins: RolldownPluginOption[];

package/lib/app/node.js

@@ -50,14 +50,16 @@ const NODE_GI_BARE_MODULE_SPECIFIERS = Object.values(ALIASES_GJS_FOR_NODE);
 /** Matches a register subpath in an alias key: `<pkg>/register` or `<pkg>/register/<feature>`. */
 const REGISTER_SUBPATH_RE = /\/register(\/|$)/;
 /**
- * Reverse-bridge register routing: a node build with an EXPLICIT `--globals`
- * register-inject stub (`pluginOptions.autoGlobalsInject`, set by the CLI for
- * `--app node` when the user names globals — e.g. `--globals auto,dom`) is a
- * genuine GJS source that needs the REAL `@gjsify/*` register bodies (document,
- * HTMLCanvasElement, matchMedia, …) running over `@gjsify/node-gi`, not the
- * default `@gjsify/empty` stubs that keep cross-platform node bundles loadable
+ * Reverse-bridge register routing: a node build of a GENUINE GJS SOURCE needs
+ * the REAL `@gjsify/*` register bodies (document, HTMLCanvasElement, the `'2d'`
+ * context factory, matchMedia, …) running over `@gjsify/node-gi`, not the
+ * default `@gjsify/empty` stubs that keep CROSS-PLATFORM node bundles loadable
  * on plain Node.
  *
+ * Applied by `setupForNode` when `isGjsSourceBuild` is true — see the comment
+ * on that flag for why BOTH reverse-bridge signals qualify, not just the
+ * explicit `--globals` stub.
+ *
  * Two adjustments over the standard node alias map:
  *  1. every `<pkg>/register…` → `@gjsify/empty` entry is DROPPED so the
  *     register import resolves to its real body;
@@ -67,7 +69,7 @@ const REGISTER_SUBPATH_RE = /\/register(\/|$)/;
  *     specifiers resolve on node exactly as they do on gjs.
  *
  * Applied to the BASE map only — `pluginOptions.aliases` / user aliases still
- * override. Without the inject stub the map is untouched (the plain-Node
+ * override. On a non-reverse-bridge build the map is untouched (the plain-Node
  * loadability guarantee for cross-platform packages is not regressed).
  */
 export function enableGjsRegistersForNode(baseAliases) {
@@ -83,6 +85,37 @@ export function enableGjsRegistersForNode(baseAliases) {
     }
     return out;
 }
+/**
+ * Is this `--app node` build a GENUINE GJS SOURCE going through the node-gi
+ * reverse bridge, rather than the node target of a cross-platform package?
+ *
+ * Two signals qualify, and BOTH must gate the same things:
+ *  - `nodeGiGlobalsInject` — the CLI's post-tree-shake detection found bare GJS
+ *    ambient globals (`print`/`imports`/`ARGV`/…) in the bundled output;
+ *  - `registerInject` (the `--globals` auto/explicit inject stub) — the user
+ *    asked for GJS registers on the node target explicitly.
+ *
+ * This predicate exists as ONE named function because the two consumers used to
+ * ask the question separately and disagree: `emitGirs` took the union while the
+ * register-alias lift took only the explicit stub. A reverse-bridge build then
+ * got its `@girs/*` routed through to `requireGi` while a `/register`
+ * side-effect import in the SAME graph was still emptied to `@gjsify/empty` —
+ * silently dropping `@gjsify/dom-elements/register/canvas`'s `'2d'` context
+ * factory, so `@gjsify/canvas2d`'s `Canvas2DBridge` never fired `onReady`.
+ *
+ * A build with NEITHER signal is byte-unchanged: the `@gjsify/empty` register
+ * routing and the `@girs/*` emptying both stay, so a cross-platform package's
+ * node bundle keeps loading on plain Node without node-gi installed.
+ *
+ * KNOWN NARROWNESS (pre-dates this predicate, tracked in STATUS.md): the
+ * `nodeGiGlobalsInject` detector keys on BARE ambient globals, so a genuine GJS
+ * source that uses `gi://` but logs via `console.log` and passes no `--globals`
+ * is not recognised — its `@girs/*` AND its registers are both emptied. The two
+ * are now at parity; widening the signal itself is the separate fix.
+ */
+export function isGjsSourceBuild(options) {
+    return Boolean(options.nodeGiGlobalsInject || options.registerInject);
+}
 export const setupForNode = async (input) => {
     const userExternal = input.userExternal ?? [];
     // node-datachannel is a native C++ addon that cannot be bundled — its
@@ -151,9 +184,38 @@ export const setupForNode = async (input) => {
         sideEffectImports.push(registerInject);
     const virtualEntries = wrapInputWithSideEffects(entryPoints, sideEffectImports);
     const finalInput = virtualEntries.input;
+    /**
+     * Is this a GENUINE GJS SOURCE built via the node-gi reverse bridge (as
+     * opposed to a cross-platform package's plain-Node bundle)?
+     *
+     * TWO signals answer that ONE question and both must count:
+     *
+     *  - `nodeGiGlobalsInject` — the CLI detected BARE GJS ambient globals
+     *    (`print`/`imports`/`ARGV`) in the tree-shaken output. Only genuine GJS
+     *    source has those (the detector deliberately ignores the
+     *    `globalThis.imports` isomorphic-guard shape).
+     *  - `autoGlobalsInject` — the user named EXPLICIT `--globals` (e.g.
+     *    `--globals auto,dom`), i.e. asked for the DOM surface on Node.
+     *
+     * Both already gate `emptyGirs` below. The register routing used to consult
+     * ONLY the explicit stub, and that asymmetry was a
+     * bug: a reverse-bridge build got its `@girs/*` value imports routed
+     * through to `requireGi` while a `/register` side-effect import in the very
+     * same graph was still emptied to `@gjsify/empty`. It surfaced as
+     * `@gjsify/canvas2d`'s `Canvas2DBridge` silently losing the `'2d'` context
+     * factory (`@gjsify/dom-elements/register/canvas` → empty → `getContext('2d')`
+     * null → `onReady` never fires) on a plain `gjsify build … --app node`, with
+     * no `--globals` flag anywhere — guarded by the node-gi
+     * `test/canvas2d-bridge.test.mjs` golden.
+     *
+     * A build with NEITHER signal is byte-unchanged: the `@gjsify/empty`
+     * register routing stays, so a cross-platform package's node bundle keeps
+     * loading on plain Node without node-gi installed.
+     */
+    const gjsSourceBuild = isGjsSourceBuild({ ...input.pluginOptions, registerInject });
     const baseAliases = getAliasesForNode({ external });
     const aliasMap = {
-        ...(registerInject ? enableGjsRegistersForNode(baseAliases) : baseAliases),
+        ...(gjsSourceBuild ? enableGjsRegistersForNode(baseAliases) : baseAliases),
         ...input.pluginOptions.aliases,
         ...input.userAliases,
     };
@@ -252,10 +314,9 @@ export const setupForNode = async (input) => {
         // `emptyGirs` also lifts for the explicit-register reverse-bridge case:
         // the injected register bodies (dom-elements, canvas2d, …) are genuine
         // GJS code whose `@girs/*` value imports must route through to
-        // `requireGi`, exactly like the ambient-globals case.
-        gjsImportsEmptyPlugin({
-            emptyGirs: !(input.pluginOptions.nodeGiGlobalsInject || registerInject),
-        }),
+        // `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) }),
         // Blueprint (.blp → XML string): the reverse bridge runs REAL GTK on
         // Node, so a GJS app entry (composite-template windows) must build for

package/lib/index.d.ts

@@ -11,9 +11,13 @@ 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, 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';
 export * from './plugin.js';

package/lib/index.js

@@ -8,8 +8,10 @@ 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, 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.