@gjsify/rolldown-plugin-gjsify 0.23.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,6 +10,8 @@
 // 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';
@@ -23,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) => {
@@ -72,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 ?? [];
@@ -271,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;
@@ -280,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,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).

package/lib/index.d.ts

@@ -11,10 +11,12 @@ 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 { 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,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, isNapiRsPackageJson, detectNapiRsEntry, AddonNotBuiltError, } from './plugins/napi-node-addon.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`.
  *

package/lib/plugins/napi-node-addon.js

@@ -38,9 +38,12 @@
 // LOCATE the `.node` but cannot rescue that body. So when the entry of a napi-rs
 // package resolves, we replace the WHOLE module with
 // `module.exports = loadAddon('<abs platform .node>')` (the `napi-rs-entry`
-// kind) — the platform `.node` is the current-triple sibling package
-// (`@scope/pkg-<triple>`, only the host's optionalDependency is installed) or a
-// local `pkg.<triple>.node`. Detection is CONSERVATIVE (package.json signal +
+// kind) — the platform `.node` is the current-triple sibling package (only the
+// host's optionalDependency is installed) or a local `pkg.<triple>.node`. The
+// sibling is named `<self>-<triple>` OR `<napi.packageName>-<triple>`; both
+// schemes ship in the wild and `isNapiRsSibling` knows both, which is what
+// makes `rolldown`/`oxfmt`/`oxlint` (all `@<scope>/binding-<triple>`) reachable
+// and not just `lightningcss`/`@node-rs/*`. Detection is CONSERVATIVE (package.json signal +
 // the file must be the package's own native `main` entry + a real host `.node`
 // must resolve) so it never rewrites an unrelated package's entry; when no
 // current-platform `.node` resolves we fall through to normal resolution rather
@@ -66,7 +69,8 @@
 // plugin is correct even when the filter does not pre-filter.
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-const NAPI_ADDON_VIRTUAL_PREFIX = '\0gjsify-napi-addon:';
+import { GJSIFY_VIRTUAL_PREFIX } from '../utils/virtual-module-id.js';
+const NAPI_ADDON_VIRTUAL_PREFIX = `${GJSIFY_VIRTUAL_PREFIX}napi-addon:`;
 /** Bare specifier the shims import — resolved + bundled from the consumer graph. */
 const NAPI_BARE_SPECIFIER = '@gjsify/napi';
 /**
@@ -78,8 +82,41 @@ const NAPI_BARE_SPECIFIER = '@gjsify/napi';
  * `this.resolve` probes on ordinary deps.
  */
 const NAPI_RS_TRIPLE_RE = /-(?:linux|darwin|win32|freebsd|openbsd|sunos|android|aix)-(?:x64|arm64|arm|ia32|ppc64|s390x|riscv64|loong64)(?:-(?:gnu|musl|msvc|eabi|eabihf|androideabi|gnueabihf))?$/;
-/** Fast-path filter (superset of what `claimSpecifier` claims). Handler re-checks. */
-const ADDON_FILTER_RE = new RegExp([
+/**
+ * A BARE package specifier (`lightningcss`, `@rolldown/binding-…`) — no leading
+ * `.`/`/`/`\`, no protocol (`node:fs`, `gi://Gtk`, `data:…`, `C:\…`), not a
+ * `\0` virtual id.
+ *
+ * Needed because a napi-rs generated loader acquires its binary through a
+ * specifier the bundler CANNOT see: `require(`lightningcss-${parts.join('-')}`)`
+ * / `require(`../lightningcss.${parts.join('-')}.node`)` are template literals
+ * computed at runtime. So neither the sibling nor the direct-`.node`
+ * interception can fire, and the only lever is replacing the loader ENTRY —
+ * which the caller reaches by its BARE name. Matching only path-shaped ids (as
+ * before) meant `import { transform } from 'lightningcss'` was never even
+ * offered to the handler, and the addon gate had to hand-alias every bare
+ * specifier to its native entry to get coverage.
+ *
+ * PORTABILITY, and it is load-bearing: this source feeds `ADDON_FILTER_RE`,
+ * which `@gjsify/rolldown-native` hands to the Rust core as an `idFilter`
+ * STRING. Rust's `regex` crate has no lookaround and no `\0` escape, and it
+ * rejects the WHOLE combined filter rather than the offending branch — which
+ * silently disables every interception under the GJS engine while npm
+ * `rolldown` on Node keeps working. So: no `(?!…)`, and NUL is spelled `\x00`.
+ * The asymmetry is invisible to the addon gate, which drives the Node CLI
+ * entry, so only a real `--app gjs` build under `gjs` catches a regression here.
+ */
+// oxlint-disable-next-line no-control-regex -- the NUL is the point: it marks a bundler VIRTUAL id (`\0gjsify-…`), which is never a package specifier and must not be probed.
+const BARE_SPECIFIER_RE = /^[^.\\/:\s\x00][^:\s\x00]*$/;
+/**
+ * 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 const ADDON_FILTER_RE = new RegExp([
     /\.node$/.source, // direct .node
     /^node-gyp-build(?:\/index\.js)?$/.source, // node-gyp-build helper
     /^bindings(?:\/bindings\.js)?$/.source, // bindings helper
@@ -89,6 +126,9 @@ const ADDON_FILTER_RE = new RegExp([
     // `index.*`, not every `.js`) — the handler's `detectNapiRsEntry` gate
     // (package.json signal + native-main match) is the load-bearing check.
     /[/\\]index\.[cm]?js$/.source,
+    // A bare specifier, so the handler can resolve it and test the RESOLVED
+    // file. Broad by design; the handler's fast rejects keep it cheap.
+    BARE_SPECIFIER_RE.source,
 ].join('|'));
 function isMusl(platform) {
     // Match node-gyp-build's isAlpine() probe.
@@ -351,11 +391,13 @@ export function classifySpecifier(source) {
  *   (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})
@@ -364,11 +406,10 @@ export function classifySpecifier(source) {
 export function isNapiRsPackageJson(pkg) {
     if (pkg && typeof pkg.napi === 'object' && pkg.napi !== null)
         return true;
-    const self = pkg?.name;
     const opt = pkg?.optionalDependencies;
-    if (self && opt) {
+    if (opt) {
         for (const dep of Object.keys(opt)) {
-            if (dep.startsWith(`${self}-`) && NAPI_RS_TRIPLE_RE.test(dep))
+            if (isNapiRsSibling(pkg, dep))
                 return true;
         }
     }
@@ -399,13 +440,79 @@ export function detectNapiRsEntry(entryFile) {
     const pkg = readPackageJsonSafe(pkgRoot);
     if (pkg === null || !isNapiRsPackageJson(pkg))
         return null;
-    // The resolved file must be the package's OWN native main entry — reject a
-    // `browser`/wasm fallback or any deep module inside the package.
-    const mainEntry = resolve(pkgRoot, pkg.main ?? 'index.js');
-    if (resolve(entryFile) !== mainEntry)
+    // The resolved file must be one of the package's OWN native entry points —
+    // reject a `browser`/wasm fallback or any deep module inside the package.
+    const target = stripJsExt(resolve(entryFile));
+    const isNativeEntry = nativeEntrySpecs(pkg).some((spec) => stripJsExt(resolve(pkgRoot, spec)) === target);
+    if (!isNativeEntry)
         return null;
     return { pkgRoot, pkg };
 }
+/** Drop a trailing `.js` / `.mjs` / `.cjs` — see {@link nativeEntrySpecs}. */
+function stripJsExt(p) {
+    return p.replace(/\.[cm]?js$/, '');
+}
+/**
+ * Every path a napi-rs manifest names as its NATIVE entry — `main`, `module`,
+ * and the `exports["."]` target(s) — with the `browser` condition deliberately
+ * excluded (that is the wasm / pure-JS fallback, which must keep resolving
+ * normally: it needs no addon and works on GJS as-is).
+ *
+ * Both halves of this matter, and each was a real miss:
+ *
+ *   - `main` ALONE is not enough. A dual package declares the CJS twin in
+ *     `main` while a bundler resolves the ESM one — `lightningcss` says
+ *     `main: "node/index.js"` and ships `node/index.mjs` beside it, which is
+ *     what `--app gjs` actually loads. Comparing only against `main` rejected
+ *     the very file being bundled, so the rewrite silently never happened and
+ *     the generated loader's runtime `require(\`lightningcss-${…}\`)` shipped
+ *     into the bundle.
+ *   - Matching is therefore extension-INSENSITIVE (`stripJsExt`): the `.js` /
+ *     `.mjs` / `.cjs` twins of a declared entry are the same generated loader.
+ *     It stays narrow because the path itself must still be one the manifest
+ *     names — a deep module inside the package never matches.
+ *
+ * Defaults to `index.js` (node's own default `main`) when the manifest names
+ * nothing at all.
+ */
+function nativeEntrySpecs(pkg) {
+    const specs = [];
+    const add = (v) => {
+        if (typeof v === 'string' && v && !specs.includes(v))
+            specs.push(v);
+    };
+    add(pkg.main);
+    add(pkg.module);
+    // `exports["."]` is a string, or a condition object whose values are
+    // strings / nested condition objects. Walk it, skipping `browser`.
+    const walk = (node, depth) => {
+        if (typeof node === 'string')
+            return add(node);
+        if (depth > 4 || node === null || typeof node !== 'object' || Array.isArray(node))
+            return;
+        for (const [condition, value] of Object.entries(node)) {
+            if (condition === 'browser' || condition === 'types')
+                continue;
+            walk(value, depth + 1);
+        }
+    };
+    const exportsField = pkg.exports;
+    if (typeof exportsField === 'string') {
+        add(exportsField);
+    }
+    else if (exportsField !== null && typeof exportsField === 'object' && !Array.isArray(exportsField)) {
+        const map = exportsField;
+        // Two legal shapes: a SUBPATH map (keys start with `.`) — then only `.`
+        // is the package entry — or a bare CONDITION object, which IS the entry.
+        // Distinguishing them matters: walking a subpath map wholesale would
+        // make `./some-subpath` a candidate entry.
+        const isSubpathMap = Object.keys(map).some((k) => k.startsWith('.'));
+        walk(isSubpathMap ? map['.'] : map, 0);
+    }
+    if (specs.length === 0)
+        specs.push('index.js');
+    return specs;
+}
 /** napi-rs binaryName (from `napi.binaryName`/`napi.name`, else the unscoped pkg name). */
 function napiBinaryName(pkg) {
     const napi = pkg.napi;
@@ -419,13 +526,66 @@ function napiBinaryName(pkg) {
         return pkg.name.replace(/^@[^/]+\//, '');
     return null;
 }
+/**
+ * The name PREFIXES a napi-rs package's platform siblings can carry, most
+ * specific first. A sibling is always `<prefix>-<triple>`.
+ *
+ * Two conventions are in the wild, and only knowing both covers the toolchain
+ * this project builds on:
+ *
+ *   - `<self>-<triple>` — the sibling is named after the package itself
+ *     (`lightningcss` → `lightningcss-linux-x64-gnu`; `@node-rs/argon2` →
+ *     `@node-rs/argon2-linux-x64-gnu`). This was the only shape handled.
+ *   - `<napi.packageName>-<triple>` — napi-rs lets a package publish its
+ *     binaries under a SEPARATE scope, declared in the manifest's own napi
+ *     block. `rolldown` ships `@rolldown/binding-linux-x64-gnu`, `oxfmt`
+ *     ships `@oxfmt/binding-linux-x64-gnu`, `oxlint` ships
+ *     `@oxlint/binding-linux-x64-gnu` — none of which starts with the
+ *     package's own name, so the `<self>-` test missed every one of them.
+ *
+ * That gap is why the three packages at the centre of this build chain
+ * (bundler, formatter, linter) could not load transparently under GJS while
+ * `lightningcss` could: `isNapiRsPackageJson` recognises all four (they all
+ * carry a `napi` config object), so the ENTRY is detected — but with no
+ * sibling resolvable, `resolveNapiRsEntryAddon` returns null and the rewrite
+ * is skipped, leaving the generated loader's CJS body to ship into the bundle
+ * and throw. Conservative by construction either way: a prefix only matters
+ * when it also resolves to a real `.node`.
+ *
+ * `napi.packageName` is read defensively — an arbitrary manifest may put
+ * anything there, and a non-string must not poison the prefix list.
+ */
+function napiSiblingPrefixes(pkg) {
+    const prefixes = [];
+    const napi = pkg.napi;
+    if (napi && typeof napi === 'object') {
+        const { packageName } = napi;
+        if (typeof packageName === 'string' && packageName)
+            prefixes.push(packageName);
+    }
+    if (typeof pkg.name === 'string' && pkg.name && !prefixes.includes(pkg.name))
+        prefixes.push(pkg.name);
+    return prefixes;
+}
+/**
+ * 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 function isNapiRsSibling(pkg, dep) {
+    if (!NAPI_RS_TRIPLE_RE.test(dep))
+        return false;
+    return napiSiblingPrefixes(pkg).some((prefix) => dep.startsWith(`${prefix}-`));
+}
 /**
  * The napi-rs short platform triple for the CURRENT host (`linux-x64-gnu`,
  * `darwin-arm64`, `win32-x64-msvc`, …) — the tail napi-rs stamps into a sibling
  * package name (`@node-rs/argon2-linux-x64-gnu`) and a local binary
- * (`argon2.linux-x64-gnu.node`). Used ONLY for the deterministic local-file
- * fallback; the sibling path never needs it (npm installs only the matching
- * optionalDependency). Returns null for a host napi-rs doesn't name.
+ * (`argon2.linux-x64-gnu.node`). Selects BOTH the sibling package and the
+ * local-file fallback — see `resolveNapiRsEntryAddon` for why the sibling path
+ * cannot just take whatever resolves. Returns null for a host napi-rs doesn't
+ * name, and the caller then widens rather than guessing.
  */
 function hostNapiRsTriple() {
     const platform = process.platform;
@@ -477,24 +637,29 @@ function rawAddonPath(id) {
  * DOES NOT rewrite, so we never shim over a missing file.
  */
 async function resolveNapiRsEntryAddon(ctx, pkgRoot, pkg, importer) {
-    const self = pkg.name;
-    const opt = pkg.optionalDependencies ?? {};
-    if (self) {
-        for (const dep of Object.keys(opt)) {
-            if (!dep.startsWith(`${self}-`) || !NAPI_RS_TRIPLE_RE.test(dep))
-                continue;
-            const resolved = await ctx.resolve(dep, importer, { skipSelf: true });
-            if (!resolved)
-                continue;
-            const abs = rawAddonPath(resolved.id);
-            if (abs.endsWith('.node') && existsSync(abs))
-                return abs;
-        }
+    const siblings = Object.keys(pkg.optionalDependencies ?? {}).filter((dep) => isNapiRsSibling(pkg, dep));
+    const triple = hostNapiRsTriple();
+    // HOST TRIPLE FIRST, and alone whenever we can name it. The older code took
+    // the first sibling that resolved, on the premise that "npm installs only
+    // the host's optionalDependency, so the one that resolves is the host's".
+    // That premise does not hold here: `gjsify install` materialises EVERY
+    // platform package, so `lightningcss`'s `darwin-x64` sibling resolves on a
+    // Linux box and won — baking a Mach-O `.dylib`-bearing `.node` into a linux
+    // GJS bundle, which `loadAddon` can only fail on at runtime. Selecting by
+    // the host triple is also what node-gyp-build and napi-rs' own generated
+    // loaders do, so this matches the binary Node would have loaded.
+    const ordered = triple === null ? siblings : siblings.filter((dep) => dep.endsWith(`-${triple}`));
+    for (const dep of ordered) {
+        const resolved = await ctx.resolve(dep, importer, { skipSelf: true });
+        if (!resolved)
+            continue;
+        const abs = rawAddonPath(resolved.id);
+        if (abs.endsWith('.node') && existsSync(abs))
+            return abs;
     }
     // Local in-package binary (`<binaryName>.<host-triple>.node`) — deterministic
     // host-triple match so a wrong-platform local file is never picked.
     const binaryName = napiBinaryName(pkg);
-    const triple = hostNapiRsTriple();
     if (binaryName && triple) {
         const local = join(pkgRoot, `${binaryName}.${triple}.node`);
         if (existsSync(local))
@@ -555,28 +720,107 @@ export function napiNodeAddonPlugin(options = {}) {
         napiEntryCache.set(entryFile, info);
         return info;
     }
-    async function warnIfNapiMissing(ctx, importer) {
-        if (!warnOnMissingNapi || missingNapiChecked)
-            return;
-        missingNapiChecked = true; // check once per build — interception is rare
+    // Bare-specifier → entry-file resolution, memoized per (specifier, importer
+    // DIRECTORY) since that pair is what node resolution actually depends on.
+    // The widened filter offers every bare import here and almost none of them
+    // is a native addon, so this cache is what keeps the extra `ctx.resolve` to
+    // one per unique pair rather than one per import site.
+    const bareEntryCache = new Map();
+    /**
+     * The FILE a specifier denotes, for napi-rs entry detection:
+     *   - absolute path  → itself (an already-resolved or hand-aliased entry).
+     *   - bare specifier → resolved through the full chain (so aliases and
+     *     export conditions apply — under `--app gjs` that is what picks a
+     *     package's `browser`/wasm fallback over its native entry, and
+     *     `detectNapiRsEntry` then correctly declines to rewrite it).
+     *   - anything else (relative paths) → null, unchanged from before.
+     */
+    async function entryFileFor(ctx, source, importer) {
+        if (isAbsolute(source))
+            return source;
+        if (!BARE_SPECIFIER_RE.test(source))
+            return null;
+        // Never recurse through our own shims' import.
+        if (source === NAPI_BARE_SPECIFIER || source.startsWith(`${NAPI_BARE_SPECIFIER}/`))
+            return null;
+        const key = `${source}\0${importer === undefined ? '' : dirname(importer)}`;
+        const cached = bareEntryCache.get(key);
+        if (cached !== undefined)
+            return cached;
+        let file = null;
         try {
-            const found = await ctx.resolve(NAPI_BARE_SPECIFIER, importer, { skipSelf: true });
-            if (!found) {
-                warnSafe(ctx, `[gjsify-napi-addon] a native .node addon was intercepted but '${NAPI_BARE_SPECIFIER}' ` +
-                    `is not resolvable — the bundle will fail at load. Install it: gjsify install ${NAPI_BARE_SPECIFIER}`);
-            }
+            const resolved = await ctx.resolve(source, importer, { skipSelf: true });
+            // An external / virtual / unresolvable id is not a file on disk.
+            if (resolved && isAbsolute(resolved.id) && existsSync(resolved.id))
+                file = resolved.id;
         }
         catch {
-            /* best-effort probe */
+            /* resolution failure is not our error to raise — fall through */
         }
+        bareEntryCache.set(key, file);
+        return file;
+    }
+    /**
+     * Is `@gjsify/napi` resolvable from the consumer graph? This is the GATE on
+     * every rewrite, not a diagnostic — installing it (`gjsify install
+     * @gjsify/napi`) is what a project uses to opt into napi routing.
+     *
+     * It used to only WARN, and the warning said the quiet part out loud: "the
+     * bundle will fail at load". Emitting a knowingly-unloadable artifact is
+     * never better than declining to rewrite — the untouched module at least
+     * gets the default resolution, and a package with a JS/wasm fallback then
+     * works. Two concrete failures made this a gate rather than a nicety:
+     *
+     *   - The CLI's own `--app gjs` bundle reaches npm `lightningcss` through
+     *     `css-as-string`'s Node fallback branch (under GJS it deliberately
+     *     prefers `@gjsify/lightningcss-native`). Rewriting that branch put a
+     *     `require('@gjsify/napi')` into a bundle whose package does not depend
+     *     on `@gjsify/napi` at all.
+     *   - Worse, it made the COMMITTED bundle environment-dependent: with the
+     *     package present the shim inlines, without it the import goes external,
+     *     and the two module graphs minify to different variable names. That is
+     *     a `verify-committed-bundles` failure — the artifact stops reproducing
+     *     from its own source.
+     *
+     * Probed once per build (interception is rare) and cached, so the extra
+     * resolve costs nothing on the common path.
+     */
+    let napiAvailable = null;
+    async function ensureNapiAvailable(ctx, importer) {
+        if (napiAvailable !== null)
+            return napiAvailable;
+        let found = false;
+        try {
+            found = Boolean(await ctx.resolve(NAPI_BARE_SPECIFIER, importer, { skipSelf: true }));
+        }
+        catch {
+            /* best-effort probe — treat a resolver throw as "not available" */
+        }
+        napiAvailable = found;
+        if (!found && warnOnMissingNapi && !missingNapiChecked) {
+            missingNapiChecked = true;
+            warnSafe(ctx, `[gjsify-napi-addon] a native .node addon was found but '${NAPI_BARE_SPECIFIER}' is not ` +
+                `resolvable — leaving it to normal resolution. Install it to route the addon through ` +
+                `N-API on GJS: gjsify install ${NAPI_BARE_SPECIFIER}`);
+        }
+        return found;
     }
     return {
         name: 'gjsify-napi-node-addon',
         resolveId: {
             order: 'pre',
             filter: { id: ADDON_FILTER_RE },
-            async handler(source, importer) {
+            async handler(source, rawImporter) {
                 const ctx = this;
+                // The two engines disagree on "no importer": npm `rolldown`
+                // passes `undefined`, `@gjsify/rolldown-native` passes `null`
+                // (its hook payload round-trips through JSON, which has no
+                // `undefined`). Every guard below is written `=== undefined`,
+                // and `null` passes all of them — `dirname(null)` then threw
+                // `The "path" argument must be of type string. Received type
+                // object` and took the whole GJS build down as an
+                // UNHANDLEABLE_ERROR. Normalise once, at the boundary.
+                const importer = typeof rawImporter === 'string' ? rawImporter : undefined;
                 const cls = classifySpecifier(source);
                 if (cls !== null) {
                     // Direct `.node` — resolve the file path itself.
@@ -584,7 +828,8 @@ export function napiNodeAddonPlugin(options = {}) {
                         const abs = await resolveNodeFile(ctx, source, importer);
                         if (abs === null)
                             return null; // unresolvable — let the default chain error
-                        await warnIfNapiMissing(ctx, importer);
+                        if (!(await ensureNapiAvailable(ctx, importer)))
+                            return null;
                         return { id: encodeVirtual('direct', abs) };
                     }
                     // napi-rs platform sibling — confirm it resolves to a `.node`.
@@ -592,7 +837,8 @@ export function napiNodeAddonPlugin(options = {}) {
                         const resolved = await ctx.resolve(source, importer, { skipSelf: true });
                         if (!resolved || !resolved.id.endsWith('.node'))
                             return null; // not a native sibling
-                        await warnIfNapiMissing(ctx, importer);
+                        if (!(await ensureNapiAvailable(ctx, importer)))
+                            return null;
                         return { id: encodeVirtual('napi-rs', resolved.id) };
                     }
                     // node-gyp-build / bindings — probe the importer's package root.
@@ -601,8 +847,9 @@ export function napiNodeAddonPlugin(options = {}) {
                     const pkgRoot = nearestPackageRoot(importer);
                     if (pkgRoot === null)
                         return null;
+                    if (!(await ensureNapiAvailable(ctx, importer)))
+                        return null;
                     const addonPath = resolveAddonPath(pkgRoot, { warn: (m) => warnSafe(ctx, m) }); // throws → build error
-                    await warnIfNapiMissing(ctx, importer);
                     return { id: encodeVirtual(cls.kind, addonPath) };
                 }
                 // napi-rs GENERATED-LOADER ENTRY (`index.*` filter). Replace the
@@ -610,11 +857,21 @@ export function napiNodeAddonPlugin(options = {}) {
                 // of a napi-rs package (package.json signal) AND a current-platform
                 // `.node` resolves. Otherwise fall through (never a shim over a
                 // missing file, never an unrelated package's entry rewritten).
-                const entry = detectNapiRsEntryCached(source);
+                // The specifier may be the entry PATH (an internal import, or a
+                // caller that already aliased it) or the package's BARE name —
+                // the ordinary `import { transform } from 'lightningcss'`. For
+                // the bare form the entry file is only known after resolution,
+                // so resolve first and test the resolved id. `entryFileFor`
+                // memoizes both the resolve and the rejection.
+                const entryFile = await entryFileFor(ctx, source, importer);
+                if (entryFile === null)
+                    return null;
+                const entry = detectNapiRsEntryCached(entryFile);
                 if (entry !== null) {
-                    const addonPath = await resolveNapiRsEntryAddon(ctx, entry.pkgRoot, entry.pkg, source);
+                    const addonPath = await resolveNapiRsEntryAddon(ctx, entry.pkgRoot, entry.pkg, entryFile);
                     if (addonPath !== null) {
-                        await warnIfNapiMissing(ctx, importer);
+                        if (!(await ensureNapiAvailable(ctx, importer)))
+                            return null;
                         return { id: encodeVirtual('napi-rs-entry', addonPath) };
                     }
                 }

package/lib/utils/auto-globals.js

@@ -319,7 +319,12 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
                     ?.GJSIFY_DEBUG_AUTO_GLOBALS) {
                     const path = `/tmp/gjsify-auto-globals-failed-chunk-${i}.mjs`;
                     try {
-                        // eslint-disable-next-line @typescript-eslint/no-require-imports
+                        // Dynamic `import()` on purpose: this is a debug-only
+                        // branch and the module graph should not carry
+                        // `node:fs` for it. (It is NOT a `require` — it never
+                        // was; the rule-disable comment that used to sit here
+                        // named a rule that cannot apply to an import
+                        // expression.)
                         const fs = await import('node:fs');
                         fs.writeFileSync(path, code);
                         console.error(`[gjsify-auto-globals] parse failed on chunk #${i} — wrote ${path} for inspection`);

package/lib/utils/entry-wrapper.js

@@ -7,6 +7,7 @@
 // first, then re-exports the real entry. `\0`-prefixed ids are Rollup's
 // convention for synthetic modules — Rolldown treats them as not-from-disk and
 // skips the default loader.
+import { GJSIFY_VIRTUAL_PREFIX } from './virtual-module-id.js';
 /**
  * If there are side-effect imports to land alongside the user's entry, wrap each
  * entry in a virtual module that imports them first then re-exports the entry.
@@ -22,7 +23,7 @@ export function wrapInputWithSideEffects(input, sideEffects, opts = {}) {
         return { input, plugin: null };
     }
     const userEntries = new Map(); // virtualId → realPath
-    const PREFIX = '\0gjsify-entry:';
+    const PREFIX = `${GJSIFY_VIRTUAL_PREFIX}entry:`;
     function wrap(realPath) {
         const id = PREFIX + realPath;
         userEntries.set(id, realPath);

package/lib/utils/index.d.ts

@@ -6,3 +6,4 @@ export * from './merge.js';
 export { detectFreeGlobals } from './detect-free-globals.js';
 export { resolveGlobalsList, writeRegisterInjectFile } from './scan-globals.js';
 export { inlineStaticReads } from './inline-static-reads.js';
+export { GJSIFY_VIRTUAL_PREFIX, isGjsifyVirtualModuleId } from './virtual-module-id.js';

package/lib/utils/index.js

@@ -6,3 +6,4 @@ export * from './merge.js';
 export { detectFreeGlobals } from './detect-free-globals.js';
 export { resolveGlobalsList, writeRegisterInjectFile } from './scan-globals.js';
 export { inlineStaticReads } from './inline-static-reads.js';
+export { GJSIFY_VIRTUAL_PREFIX, isGjsifyVirtualModuleId } from './virtual-module-id.js';

package/lib/utils/virtual-module-id.d.ts

@@ -0,0 +1,14 @@
+/** Shared prefix of every gjsify-generated (synthetic) module id. */
+export declare const GJSIFY_VIRTUAL_PREFIX = "\0gjsify-";
+/**
+ * Is `id` a module gjsify's own plugins generated (as opposed to a user/npm
+ * source file)?
+ *
+ * Used by `aliasPlugin` to scope the alias tables to REAL source: generated
+ * module bodies name the runtime module they need explicitly and must not be
+ * re-pointed by a user alias or a slot-routing entry.
+ *
+ * @param id A Rolldown module id — typically a `resolveId` `importer`, which is
+ *   `undefined` for entry modules.
+ */
+export declare function isGjsifyVirtualModuleId(id: string | undefined | null): boolean;

package/lib/utils/virtual-module-id.js

@@ -0,0 +1,36 @@
+// The ONE prefix every synthetic module id emitted by a gjsify plugin carries.
+//
+// Rollup/Rolldown convention is that a `\0`-prefixed id is not-from-disk; every
+// gjsify plugin that emits one additionally namespaces it with `gjsify-`
+// (`\0gjsify-entry:`, `\0gjsify-gi-node:`, `\0gjsify-napi-addon:`,
+// `\0gjsify-empty-gjs-import`). Deriving those ids from THIS constant turns that
+// naming habit into an enforced invariant, which matters because the alias layer
+// keys off it: a module whose SOURCE we generated must bind to the RUNTIME's real
+// modules, never to whatever a user `--alias` retargets a specifier onto.
+//
+// Concretely (the bug that motivated this): `gjsGiNodePlugin`'s virtual module
+// emits `import { createRequire } from 'node:module'`. Under the node-gi consumer
+// harness — which builds `--alias node:module=@gjsify/module` to put the polyfill
+// UNDER TEST behind the specifier — that import was rewritten onto the polyfill
+// itself, so the bundle called `@gjsify/module`'s `createRequire` at top level
+// before its lazy GLib namespace proxy existed (`TypeError: Cannot read
+// properties of undefined (reading 'filename_from_uri')`), and past that hit a
+// genuine cycle: the polyfill's Gio-backed CJS loader needs GLib, and GLib is
+// reached through `@gjsify/node-gi/gi` — which is what the virtual module was
+// loading in the first place.
+/** Shared prefix of every gjsify-generated (synthetic) module id. */
+export const GJSIFY_VIRTUAL_PREFIX = '\0gjsify-';
+/**
+ * Is `id` a module gjsify's own plugins generated (as opposed to a user/npm
+ * source file)?
+ *
+ * Used by `aliasPlugin` to scope the alias tables to REAL source: generated
+ * module bodies name the runtime module they need explicitly and must not be
+ * re-pointed by a user alias or a slot-routing entry.
+ *
+ * @param id A Rolldown module id — typically a `resolveId` `importer`, which is
+ *   `undefined` for entry modules.
+ */
+export function isGjsifyVirtualModuleId(id) {
+    return typeof id === 'string' && id.startsWith(GJSIFY_VIRTUAL_PREFIX);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/rolldown-plugin-gjsify",
-    "version": "0.23.0",
+    "version": "0.24.1",
     "description": "Rolldown / Rollup / Vite plugin orchestrator for GJS, Node, and Browser targets",
     "type": "module",
     "main": "lib/index.js",
@@ -55,11 +55,11 @@
     ],
     "license": "MIT",
     "dependencies": {
-        "@gjsify/console": "^0.23.0",
-        "@gjsify/resolve-npm": "^0.23.0",
-        "@gjsify/rolldown-plugin-deepkit": "^0.23.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.23.0",
-        "@gjsify/vite-plugin-blueprint": "^0.23.0",
+        "@gjsify/console": "^0.24.1",
+        "@gjsify/resolve-npm": "^0.24.1",
+        "@gjsify/rolldown-plugin-deepkit": "^0.24.1",
+        "@gjsify/rolldown-plugin-pnp": "^0.24.1",
+        "@gjsify/vite-plugin-blueprint": "^0.24.1",
         "@rollup/pluginutils": "^5.4.0",
         "acorn": "^8.17.0",
         "acorn-walk": "^8.3.5",
@@ -68,7 +68,7 @@
         "sass": "^1.101.0"
     },
     "peerDependencies": {
-        "@gjsify/lightningcss-native": "^0.23.0",
+        "@gjsify/lightningcss-native": "^0.24.1",
         "rolldown": "^1.1.4"
     },
     "peerDependenciesMeta": {