@gjsify/rolldown-plugin-gjsify 0.22.0 → 0.23.0

package/lib/app/gjs.js

@@ -12,6 +12,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 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';
@@ -196,6 +197,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

package/lib/app/index.d.ts

@@ -1,6 +1,6 @@
 export { setupForGjs, isRegisterSubpath, 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 { setupForNode, enableGjsRegistersForNode, isGjsSourceBuild } from './node.js';
 export { setupForBrowser } from './browser.js';
 export { setupForNativescript } from './nativescript.js';

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

@@ -14,6 +14,8 @@ export type { ShebangPluginOptions } from './plugins/shebang.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 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

@@ -10,6 +10,7 @@ export { textLoaderPlugin } from './plugins/text-loader.js';
 export { shebangPlugin, GJS_SHEBANG, NODE_SHEBANG, expandEnvTemplate, resolveShebangLine } from './plugins/shebang.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 { platformResolvePlugin, detectNativescriptPlatform, nativescriptPlatformDefines, } from './plugins/platform-resolve.js';
 export * from './plugin.js';
 import { gjsifyPlugin } from './plugin.js';

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

@@ -0,0 +1,100 @@
+import type { Plugin } from 'rolldown';
+/** Options for {@link napiNodeAddonPlugin}. */
+export interface NapiNodeAddonPluginOptions {
+    /**
+     * Emit a one-line warning when a native addon is intercepted but
+     * `@gjsify/napi` is not resolvable in the consumer graph. Default `true`.
+     */
+    warnOnMissingNapi?: boolean;
+}
+/** A native addon package root has no resolvable compiled `.node`. */
+export declare class AddonNotBuiltError extends Error {
+    constructor(pkgRoot: string);
+}
+/**
+ * Locate the compiled `.node` for an addon package root, matching
+ * node-gyp-build's probe order: `build/Release` → `build/Debug` →
+ * `prebuilds/<platform>-<arch>/<best tag>`. Throws {@link AddonNotBuiltError}
+ * when nothing is found.
+ *
+ * @param pkgRoot Absolute path to the addon package root (dir with package.json).
+ * @param opts.warn Optional sink for a non-fatal warning (ambiguous build dir).
+ */
+export declare function resolveAddonPath(pkgRoot: string, opts?: {
+    warn?: (msg: string) => void;
+}): string;
+/**
+ * Walk up from an importer file to the nearest `package.json` directory (the
+ * addon package root). Returns null when none is found (should not happen for a
+ * real node_modules dep).
+ */
+export declare function nearestPackageRoot(importerFile: string): string | null;
+/** Direct `.node` import → the addon's exports (ESM default). */
+export declare function directNodeShim(addonPath: string): string;
+/** `node-gyp-build` replacement — a callable `load(dir)` carrying `.path()`. */
+export declare function nodeGypBuildShim(addonPath: string): string;
+/** `bindings` replacement — a callable `bindings(name)` returning the addon. */
+export declare function bindingsShim(addonPath: string): string;
+/** napi-rs sibling → the raw native exports as the module value. */
+export declare function napiRsShim(addonPath: string): string;
+/**
+ * Classify a specifier for interception. Pure decision logic (no filesystem
+ * probing beyond what `resolveAddonPath` does via the importer) — exported for
+ * the unit tests. Returns the shim kind + the package root to probe, or the
+ * literal `.node` path for the direct case.
+ */
+export declare function classifySpecifier(source: string): {
+    kind: 'node-gyp-build' | 'bindings';
+} | {
+    kind: 'direct-node';
+} | {
+    kind: 'napi-rs-candidate';
+} | null;
+/** Minimal package.json shape read for napi-rs detection. */
+export interface AddonPackageJson {
+    name?: string;
+    main?: string;
+    browser?: string;
+    napi?: unknown;
+    optionalDependencies?: Record<string, string>;
+}
+/**
+ * A package.json describes a napi-rs generated-loader package when EITHER
+ * signal holds — both are package.json-level (not source sniffing):
+ *
+ *   (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.
+ *
+ * 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})
+ * makes entry-replacement safe. Exported for the unit tests.
+ */
+export declare function isNapiRsPackageJson(pkg: AddonPackageJson): boolean;
+/**
+ * Decide whether an absolute file path is the NATIVE generated-loader entry of a
+ * napi-rs package. Returns the package root + parsed manifest when it is, else
+ * null. "Native entry" = the package's `main` (default `index.js`) — NOT its
+ * `browser`/wasm fallback and NOT a deep file — so we only ever replace the one
+ * generated loader, never an unrelated module. Filesystem-based (reads the
+ * nearest package.json); the plugin memoizes calls. Exported for the unit tests.
+ */
+export declare function detectNapiRsEntry(entryFile: string): {
+    pkgRoot: string;
+    pkg: AddonPackageJson;
+} | null;
+/**
+ * Transparent `.node`-addon loader for `gjsify build --app gjs`.
+ *
+ * resolveId (`order: 'pre'`, importer-aware) intercepts a native-addon
+ * acquisition and rewrites it to a virtual module whose value is
+ * `loadAddon('<abs .node>')`. Inert unless such a specifier is in the graph —
+ * every other id returns null. Register ONLY for `--app gjs` (the C-ABI runs
+ * under `@gjsify/napi`); never for node/browser/nativescript.
+ */
+export declare function napiNodeAddonPlugin(options?: NapiNodeAddonPluginOptions): Plugin;

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

@@ -0,0 +1,631 @@
+// For `--app gjs`: transparently route a compiled N-API `.node` addon through
+// `@gjsify/napi`'s `loadAddon()` so `import Database from 'better-sqlite3'` /
+// `require('bufferutil')` "just works" in a GJS build — no per-project shim, no
+// hand-pinned addon path.
+//
+// This is the FORWARD MIRROR of `gjsGiNodePlugin` (`gjs-gi-node.ts`): that
+// plugin rewrites `gi://Ns` → `requireGi` for `--app node` (run GObject code on
+// Node); this one rewrites a native-addon acquisition → `loadAddon` for
+// `--app gjs` (run Node's `.node` addons on GJS). Both intercept the ONE
+// specifier a bundler can see and replace it with a virtual module whose value
+// is the runtime bridge.
+//
+// The problem is always the same: the compiled `.node` is acquired with a
+// DYNAMIC `require(<computed path>)` no bundler can rewrite. So we intercept the
+// well-known helper the addon uses and replace it with a virtual module that
+// returns `loadAddon('<abs .node>')`. Handled conventions (keyed by the import
+// a bundler DOES see):
+//
+//   - direct `.node`     — a `source` (or a `@scope/pkg-<triple>` sibling that
+//                          resolves to a `.node`) ending in `.node`.
+//   - `node-gyp-build`   — prebuildify layout (bufferutil, utf-8-validate, …).
+//                          Default export is a `load(dir)` function.
+//   - `bindings`         — node-bindings layout (better-sqlite3, node-sqlite3).
+//                          Default export is a `bindings(name)` function.
+//   - napi-rs sibling    — `@scope/pkg-<triple>` platform package (or local
+//                          `pkg.<triple>.node` fallback), whose exports ARE the
+//                          addon API.
+//   - napi-rs ENTRY      — the napi-rs GENERATED loader index
+//                          (`@node-rs/argon2/index.js`), detected by a
+//                          package.json signal and replaced WHOLESALE.
+//
+// napi-rs GENERATED-LOADER ENTRY replacement: a napi-rs generated index
+// (`@node-rs/argon2/index.js`) wraps its acquisition in a
+// `require('node:module')` + `createRequire(__filename)` + runtime
+// `existsSync`/`process` branch chain whose CJS body does NOT survive `--app gjs`
+// bundling (the top-level `require = createRequire(...)` reassignment throws
+// `ReferenceError: require`). The sibling/direct interceptions above correctly
+// 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 +
+// 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
+// than emit a shim over a missing file. The C/C++ path (node-gyp-build +
+// bindings) and napi-rs are all proven byte-identical in the transparent gate.
+//
+// The addon's compiled `.node` is located by `resolveAddonPath()`, which
+// replicates node-gyp-build's OWN selection algorithm (build/Release →
+// build/Debug → prebuilds/<platform>-<arch>/<best tag>) so the GJS build routes
+// the SAME binary Node would load.
+//
+// KEY: the shims import `@gjsify/napi` by BARE SPECIFIER (`require('@gjsify/napi')`).
+// `@gjsify/napi`'s L1 is a `gjs:polyfill` package reading `imports.gi`; it
+// bundles normally, and its native typelib is auto-added to `GI_TYPELIB_PATH` by
+// the CLI's `detectNativePackages` (because it declares `gjsify.prebuilds`). The
+// callable-helper shims (`node-gyp-build`/`bindings`) stay CJS
+// (`module.exports = fn`) so the consumer's `require('node-gyp-build')(dir)`
+// call site keeps working through gjsify's cjs-compat interop — a callable, not
+// an ESM namespace.
+//
+// Portability note (same as `gjs-gi-node.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.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+const NAPI_ADDON_VIRTUAL_PREFIX = '\0gjsify-napi-addon:';
+/** Bare specifier the shims import — resolved + bundled from the consumer graph. */
+const NAPI_BARE_SPECIFIER = '@gjsify/napi';
+/**
+ * Platform-triple tail of a napi-rs sibling platform package
+ * (`@node-rs/argon2-linux-x64-gnu`) or its local fallback
+ * (`argon2.linux-x64-gnu.node`). Deliberately narrow — an interception on a
+ * false match is self-correcting (it only fires when the specifier ALSO
+ * resolves to a real `.node`), but keeping the shape tight avoids needless
+ * `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([
+    /\.node$/.source, // direct .node
+    /^node-gyp-build(?:\/index\.js)?$/.source, // node-gyp-build helper
+    /^bindings(?:\/bindings\.js)?$/.source, // bindings helper
+    NAPI_RS_TRIPLE_RE.source, // napi-rs platform sibling
+    // napi-rs generated-loader ENTRY: the conventional package-root
+    // `index.{js,cjs,mjs}` a napi-rs build emits. Narrow on purpose (only
+    // `index.*`, not every `.js`) — the handler's `detectNapiRsEntry` gate
+    // (package.json signal + native-main match) is the load-bearing check.
+    /[/\\]index\.[cm]?js$/.source,
+].join('|'));
+function isMusl(platform) {
+    // Match node-gyp-build's isAlpine() probe.
+    return platform === 'linux' && existsSync('/etc/alpine-release');
+}
+function hostTarget() {
+    const platform = process.env.npm_config_platform || process.platform;
+    const arch = process.env.npm_config_arch || process.arch;
+    const abi = process.versions ? process.versions.modules : undefined;
+    const uv = ((process.versions && process.versions.uv) || '').split('.')[0] || '';
+    const armv = process.env.ARM_VERSION || (arch === 'arm64' ? '8' : '') || '';
+    const libc = process.env.LIBC === 'musl' || isMusl(platform) ? 'musl' : 'glibc';
+    return { platform, arch, libc, abi, uv, armv, runtime: 'node' };
+}
+function readdirSafe(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** First `*.node` in `dir` (sorted for determinism), or null. */
+function firstNodeFile(dir) {
+    const all = readdirSafe(dir)
+        .filter((n) => n.endsWith('.node'))
+        .sort();
+    if (all.length === 0)
+        return null;
+    return { file: all[0], all };
+}
+function parseTuple(name) {
+    const arr = name.split('-');
+    if (arr.length !== 2)
+        return null;
+    const platform = arr[0];
+    const architectures = arr[1].split('+');
+    if (!platform || architectures.length === 0 || !architectures.every(Boolean))
+        return null;
+    return { name, platform, architectures };
+}
+function parseTags(file) {
+    const arr = file.split('.');
+    const extension = arr.pop();
+    const tags = { file, specificity: 0 };
+    if (extension !== 'node')
+        return null;
+    for (const tag of arr) {
+        if (tag === 'node' || tag === 'electron' || tag === 'node-webkit') {
+            tags.runtime = tag;
+        }
+        else if (tag === 'napi') {
+            tags.napi = true;
+        }
+        else if (tag.slice(0, 3) === 'abi') {
+            tags.abi = tag.slice(3);
+        }
+        else if (tag.slice(0, 2) === 'uv') {
+            tags.uv = tag.slice(2);
+        }
+        else if (tag.slice(0, 4) === 'armv') {
+            tags.armv = tag.slice(4);
+        }
+        else if (tag === 'glibc' || tag === 'musl') {
+            tags.libc = tag;
+        }
+        else {
+            continue;
+        }
+        tags.specificity++;
+    }
+    return tags;
+}
+function runtimeAgnostic(tags) {
+    return tags.runtime === 'node' && tags.napi === true;
+}
+/**
+ * Resolve the best `prebuilds/<platform>-<arch>/<file>.node` for `pkgRoot`,
+ * ported from node-gyp-build's `resolve(dir)` — tolerant of a missing `abi`.
+ */
+function resolvePrebuild(pkgRoot, host) {
+    const prebuildsDir = join(pkgRoot, 'prebuilds');
+    const tuple = readdirSafe(prebuildsDir)
+        .map(parseTuple)
+        .filter((t) => t !== null && t.platform === host.platform && t.architectures.includes(host.arch))
+        // Prefer single-arch prebuilds over multi-arch (compareTuples).
+        .sort((a, b) => a.architectures.length - b.architectures.length)[0];
+    if (!tuple)
+        return null;
+    const tupleDir = join(prebuildsDir, tuple.name);
+    const winner = readdirSafe(tupleDir)
+        .map(parseTags)
+        .filter((t) => {
+        if (t === null)
+            return false;
+        if (t.runtime && t.runtime !== host.runtime && !runtimeAgnostic(t))
+            return false;
+        // abi undefined (GJS host): reject an abi-pinned, non-napi prebuild —
+        // only runtime-agnostic napi prebuilds legitimately match.
+        if (t.abi && t.abi !== host.abi && !t.napi)
+            return false;
+        if (t.uv && t.uv !== host.uv)
+            return false;
+        if (t.armv && t.armv !== host.armv)
+            return false;
+        if (t.libc && t.libc !== host.libc)
+            return false;
+        return true;
+    })
+        // compareTags: matching runtime first, abi over napi, then specificity.
+        .sort((a, b) => {
+        if (a.runtime !== b.runtime)
+            return a.runtime === host.runtime ? -1 : 1;
+        if (a.abi !== b.abi)
+            return a.abi ? -1 : 1;
+        if (a.specificity !== b.specificity)
+            return a.specificity > b.specificity ? -1 : 1;
+        return 0;
+    })[0];
+    return winner ? join(tupleDir, winner.file) : null;
+}
+/** A native addon package root has no resolvable compiled `.node`. */
+export class AddonNotBuiltError extends Error {
+    constructor(pkgRoot) {
+        super(`[gjsify-napi-addon] no compiled .node found for '${pkgRoot}'. Build it ` +
+            `(node-gyp / prebuildify) or install a prebuild before bundling for --app gjs.`);
+        this.name = 'AddonNotBuiltError';
+    }
+}
+/**
+ * Locate the compiled `.node` for an addon package root, matching
+ * node-gyp-build's probe order: `build/Release` → `build/Debug` →
+ * `prebuilds/<platform>-<arch>/<best tag>`. Throws {@link AddonNotBuiltError}
+ * when nothing is found.
+ *
+ * @param pkgRoot Absolute path to the addon package root (dir with package.json).
+ * @param opts.warn Optional sink for a non-fatal warning (ambiguous build dir).
+ */
+export function resolveAddonPath(pkgRoot, opts) {
+    const host = hostTarget();
+    for (const flavor of ['Release', 'Debug']) {
+        const dir = join(pkgRoot, 'build', flavor);
+        const hit = firstNodeFile(dir);
+        if (hit) {
+            if (hit.all.length > 1 && opts?.warn) {
+                opts.warn(`[gjsify-napi-addon] ${hit.all.length} .node files in ${dir} ` +
+                    `(${hit.all.join(', ')}); picking '${hit.file}'. If wrong, import the ` +
+                    `.node directly.`);
+            }
+            return join(dir, hit.file);
+        }
+    }
+    const prebuild = resolvePrebuild(pkgRoot, host);
+    if (prebuild)
+        return prebuild;
+    throw new AddonNotBuiltError(pkgRoot);
+}
+/**
+ * Walk up from an importer file to the nearest `package.json` directory (the
+ * addon package root). Returns null when none is found (should not happen for a
+ * real node_modules dep).
+ */
+export function nearestPackageRoot(importerFile) {
+    let dir = isAbsolute(importerFile) ? dirname(importerFile) : dirname(resolve(importerFile));
+    // Guard against an infinite loop at the filesystem root.
+    for (let i = 0; i < 64; i++) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Shim generators — the virtual-module bodies. All import `@gjsify/napi` by BARE
+// specifier. The callable-helper shims are CJS (`module.exports = fn`) so the
+// consumer's `require('node-gyp-build')(dir)` / `require('bindings')(name)` stays
+// callable through cjs-compat interop.
+// ---------------------------------------------------------------------------
+/** Direct `.node` import → the addon's exports (ESM default). */
+export function directNodeShim(addonPath) {
+    return (`import { loadAddon } from ${JSON.stringify(NAPI_BARE_SPECIFIER)};\n` +
+        `export default loadAddon(${JSON.stringify(addonPath)});\n`);
+}
+/** `node-gyp-build` replacement — a callable `load(dir)` carrying `.path()`. */
+export function nodeGypBuildShim(addonPath) {
+    return (`const { loadAddon } = require(${JSON.stringify(NAPI_BARE_SPECIFIER)});\n` +
+        `function load() { return loadAddon(${JSON.stringify(addonPath)}); }\n` +
+        `load.path = function () { return ${JSON.stringify(addonPath)}; };\n` +
+        `load.resolve = load.path;\n` +
+        `module.exports = load;\n`);
+}
+/** `bindings` replacement — a callable `bindings(name)` returning the addon. */
+export function bindingsShim(addonPath) {
+    return (`const { loadAddon } = require(${JSON.stringify(NAPI_BARE_SPECIFIER)});\n` +
+        `function bindings() { return loadAddon(${JSON.stringify(addonPath)}); }\n` +
+        `module.exports = bindings;\n`);
+}
+/** napi-rs sibling → the raw native exports as the module value. */
+export function napiRsShim(addonPath) {
+    return (`const { loadAddon } = require(${JSON.stringify(NAPI_BARE_SPECIFIER)});\n` +
+        `module.exports = loadAddon(${JSON.stringify(addonPath)});\n`);
+}
+function shimFor(kind, addonPath) {
+    switch (kind) {
+        case 'direct':
+            return directNodeShim(addonPath);
+        case 'node-gyp-build':
+            return nodeGypBuildShim(addonPath);
+        case 'bindings':
+            return bindingsShim(addonPath);
+        case 'napi-rs':
+        case 'napi-rs-entry':
+            // Both hand back the raw native exports as the module value. The
+            // `napi-rs-entry` kind replaces the whole GENERATED loader; `napi-rs`
+            // replaces a directly-imported platform sibling. Same body.
+            return napiRsShim(addonPath);
+    }
+}
+function encodeVirtual(kind, addonPath) {
+    return `${NAPI_ADDON_VIRTUAL_PREFIX}${kind}:${addonPath}`;
+}
+function decodeVirtual(id) {
+    if (!id.startsWith(NAPI_ADDON_VIRTUAL_PREFIX))
+        return null;
+    const rest = id.slice(NAPI_ADDON_VIRTUAL_PREFIX.length);
+    const sep = rest.indexOf(':');
+    if (sep === -1)
+        return null;
+    const kind = rest.slice(0, sep);
+    const addonPath = rest.slice(sep + 1);
+    return { kind, addonPath };
+}
+/**
+ * Classify a specifier for interception. Pure decision logic (no filesystem
+ * probing beyond what `resolveAddonPath` does via the importer) — exported for
+ * the unit tests. Returns the shim kind + the package root to probe, or the
+ * literal `.node` path for the direct case.
+ */
+export function classifySpecifier(source) {
+    if (source === 'node-gyp-build' || source === 'node-gyp-build/index.js')
+        return { kind: 'node-gyp-build' };
+    if (source === 'bindings' || source === 'bindings/bindings.js')
+        return { kind: 'bindings' };
+    if (source.endsWith('.node'))
+        return { kind: 'direct-node' };
+    // A napi-rs platform sibling (`@scope/pkg-<triple>`) — only a CANDIDATE; the
+    // handler confirms by resolving it to a real `.node`.
+    const last = source.split('/').pop() ?? source;
+    if (!source.startsWith('.') && NAPI_RS_TRIPLE_RE.test(last))
+        return { kind: 'napi-rs-candidate' };
+    return null;
+}
+/**
+ * A package.json describes a napi-rs generated-loader package when EITHER
+ * signal holds — both are package.json-level (not source sniffing):
+ *
+ *   (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.
+ *
+ * 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})
+ * makes entry-replacement safe. Exported for the unit tests.
+ */
+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) {
+        for (const dep of Object.keys(opt)) {
+            if (dep.startsWith(`${self}-`) && NAPI_RS_TRIPLE_RE.test(dep))
+                return true;
+        }
+    }
+    return false;
+}
+function readPackageJsonSafe(pkgRoot) {
+    try {
+        return JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decide whether an absolute file path is the NATIVE generated-loader entry of a
+ * napi-rs package. Returns the package root + parsed manifest when it is, else
+ * null. "Native entry" = the package's `main` (default `index.js`) — NOT its
+ * `browser`/wasm fallback and NOT a deep file — so we only ever replace the one
+ * generated loader, never an unrelated module. Filesystem-based (reads the
+ * nearest package.json); the plugin memoizes calls. Exported for the unit tests.
+ */
+export function detectNapiRsEntry(entryFile) {
+    if (!isAbsolute(entryFile) || !/\.[cm]?js$/.test(entryFile))
+        return null;
+    const pkgRoot = nearestPackageRoot(entryFile);
+    if (pkgRoot === null)
+        return null;
+    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)
+        return null;
+    return { pkgRoot, pkg };
+}
+/** napi-rs binaryName (from `napi.binaryName`/`napi.name`, else the unscoped pkg name). */
+function napiBinaryName(pkg) {
+    const napi = pkg.napi;
+    if (napi && typeof napi === 'object') {
+        const cfg = napi;
+        const bn = typeof cfg.binaryName === 'string' ? cfg.binaryName : cfg.name;
+        if (typeof bn === 'string' && bn)
+            return bn;
+    }
+    if (typeof pkg.name === 'string' && pkg.name)
+        return pkg.name.replace(/^@[^/]+\//, '');
+    return null;
+}
+/**
+ * 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.
+ */
+function hostNapiRsTriple() {
+    const platform = process.platform;
+    const arch = process.arch;
+    const archTok = {
+        x64: 'x64',
+        arm64: 'arm64',
+        arm: 'arm',
+        ia32: 'ia32',
+        ppc64: 'ppc64',
+        s390x: 's390x',
+        riscv64: 'riscv64',
+    };
+    const a = archTok[arch];
+    if (!a)
+        return null;
+    switch (platform) {
+        case 'linux': {
+            if (arch === 'arm')
+                return 'linux-arm-gnueabihf';
+            const libc = process.env.LIBC === 'musl' || isMusl('linux') ? 'musl' : 'gnu';
+            return `linux-${a}-${libc}`;
+        }
+        case 'darwin':
+            return `darwin-${a}`;
+        case 'win32':
+            return `win32-${a}-msvc`;
+        case 'freebsd':
+            return `freebsd-${a}`;
+        case 'android':
+            return arch === 'arm' ? 'android-arm-eabi' : `android-${a}`;
+        default:
+            return null;
+    }
+}
+/** Decode a napi virtual id back to its raw `.node` path (safety net for a resolve hit). */
+function rawAddonPath(id) {
+    const decoded = decodeVirtual(id);
+    return decoded ? decoded.addonPath : id;
+}
+/**
+ * Resolve the current-platform compiled `.node` for a napi-rs generated-loader
+ * package: the current-triple sibling package (`@scope/pkg-<triple>`, whose own
+ * `main` IS the `.node` — npm installs ONLY the host's optionalDependency, so
+ * the one that resolves is the host's), then a local `pkg.<triple>.node`. Reuses
+ * the plugin's `ctx.resolve` sibling-resolution path (`skipSelf` so this
+ * plugin's own napi-rs-candidate interception is bypassed → a raw `.node` id).
+ * Returns null when no current-platform binary is present — the caller then
+ * 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;
+        }
+    }
+    // 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))
+            return local;
+    }
+    return null;
+}
+/** Emit a non-fatal warning through the context, if it supports it. */
+function warnSafe(ctx, msg) {
+    if (typeof ctx.warn === 'function')
+        ctx.warn(msg);
+}
+/**
+ * Resolve a direct `.node` specifier to an EXISTING absolute path
+ * (relative/bare/abs), or null when it does not resolve to a real file. Null is
+ * load-bearing: a napi-rs generated loader statically references a local
+ * `./pkg.<triple>.node` fallback that is absent when the binary ships in the
+ * sibling platform package — that dead branch must fall through to normal
+ * (external) resolution, NOT be rewritten to a shim over a missing file.
+ */
+async function resolveNodeFile(ctx, source, importer) {
+    if (isAbsolute(source))
+        return existsSync(source) ? source : null;
+    if (importer !== undefined) {
+        // Importer-relative path math first (a plain `./foo.node`), then the full
+        // resolver chain (a bare `pkg/foo.node`). Only claim an EXISTING file.
+        const rel = resolve(dirname(importer), source);
+        if (existsSync(rel))
+            return rel;
+        const resolved = await ctx.resolve(source, importer, { skipSelf: true });
+        if (resolved && resolved.id.endsWith('.node') && existsSync(resolved.id))
+            return resolved.id;
+        return null;
+    }
+    return null;
+}
+/**
+ * Transparent `.node`-addon loader for `gjsify build --app gjs`.
+ *
+ * resolveId (`order: 'pre'`, importer-aware) intercepts a native-addon
+ * acquisition and rewrites it to a virtual module whose value is
+ * `loadAddon('<abs .node>')`. Inert unless such a specifier is in the graph —
+ * every other id returns null. Register ONLY for `--app gjs` (the C-ABI runs
+ * under `@gjsify/napi`); never for node/browser/nativescript.
+ */
+export function napiNodeAddonPlugin(options = {}) {
+    const warnOnMissingNapi = options.warnOnMissingNapi !== false;
+    let missingNapiChecked = false;
+    // Memoize napi-rs entry detection per resolved file — the `index.*` filter
+    // fires the handler for every package's index entry across every build pass;
+    // this bounds the package.json reads to one per unique entry file.
+    const napiEntryCache = new Map();
+    function detectNapiRsEntryCached(entryFile) {
+        const cached = napiEntryCache.get(entryFile);
+        if (cached !== undefined)
+            return cached;
+        const info = detectNapiRsEntry(entryFile);
+        napiEntryCache.set(entryFile, info);
+        return info;
+    }
+    async function warnIfNapiMissing(ctx, importer) {
+        if (!warnOnMissingNapi || missingNapiChecked)
+            return;
+        missingNapiChecked = true; // check once per build — interception is rare
+        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}`);
+            }
+        }
+        catch {
+            /* best-effort probe */
+        }
+    }
+    return {
+        name: 'gjsify-napi-node-addon',
+        resolveId: {
+            order: 'pre',
+            filter: { id: ADDON_FILTER_RE },
+            async handler(source, importer) {
+                const ctx = this;
+                const cls = classifySpecifier(source);
+                if (cls !== null) {
+                    // Direct `.node` — resolve the file path itself.
+                    if (cls.kind === 'direct-node') {
+                        const abs = await resolveNodeFile(ctx, source, importer);
+                        if (abs === null)
+                            return null; // unresolvable — let the default chain error
+                        await warnIfNapiMissing(ctx, importer);
+                        return { id: encodeVirtual('direct', abs) };
+                    }
+                    // napi-rs platform sibling — confirm it resolves to a `.node`.
+                    if (cls.kind === 'napi-rs-candidate') {
+                        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);
+                        return { id: encodeVirtual('napi-rs', resolved.id) };
+                    }
+                    // node-gyp-build / bindings — probe the importer's package root.
+                    if (importer === undefined)
+                        return null;
+                    const pkgRoot = nearestPackageRoot(importer);
+                    if (pkgRoot === null)
+                        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
+                // whole module only when the resolved file IS the native `main`
+                // 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);
+                if (entry !== null) {
+                    const addonPath = await resolveNapiRsEntryAddon(ctx, entry.pkgRoot, entry.pkg, source);
+                    if (addonPath !== null) {
+                        await warnIfNapiMissing(ctx, importer);
+                        return { id: encodeVirtual('napi-rs-entry', addonPath) };
+                    }
+                }
+                return null;
+            },
+        },
+        load(id) {
+            const decoded = decodeVirtual(id);
+            if (decoded === null)
+                return null;
+            return { code: shimFor(decoded.kind, decoded.addonPath), moduleSideEffects: false };
+        },
+    };
+}

package/lib/plugins/process-stub.js

@@ -1,7 +1,18 @@
 import { BUNDLE_URL_BANNER } from './bundle-url-banner.js';
 import { GJS_WELLKNOWN_SYMBOLS_STUB } from './wellknown-symbols-banner.js';
+// Every GJS ambient global is reached through `globalThis.` — NEVER as a bare
+// identifier. The banner shares the module's top-level scope with the bundled
+// code, so a bare `imports` binds to any top-level `const imports` a bundled
+// module declares — and since the banner runs at byte 1, that binding is still
+// in its temporal dead zone: `ReferenceError: can't access lexical declaration
+// 'imports' before initialization`, thrown at load, before a single line of
+// program code runs. `@girs/gjs`'s `gjs.js` declares exactly that
+// (`const imports = globalThis.imports || {}`), so the failure is real and
+// arrives whenever tree-shaking happens to retain that module. It was found
+// via `@gjsify/web-streams`, whose GJS test leg died the moment `@gjsify/utils`
+// became more shakeable — but nothing about it is specific to either package.
 export const GJS_PROCESS_STUB = 'if(typeof globalThis.process==="undefined"){' +
-    'const _s=imports.system,_G=imports.gi.GLib;' +
+    'const _s=globalThis.imports.system,_G=globalThis.imports.gi.GLib;' +
     // process.hrtime needs a `.bigint` property attached to the function
     // itself (Node API shape: `process.hrtime.bigint()` — used by execa,
     // perf-tracking libs, …). Build it as a named local so we can
@@ -21,7 +32,7 @@ export const GJS_PROCESS_STUB = 'if(typeof globalThis.process==="undefined"){' +
     'versions:{},config:{},' +
     'cwd(){return _G.get_current_dir()||"/"},' +
     'exit(c){_s.exit(c??0)},' +
-    'stderr:{write(s){printerr(s)}},stdout:{write(s){print(s)}},stdin:null,' +
+    'stderr:{write(s){globalThis.printerr(s)}},stdout:{write(s){globalThis.print(s)}},stdin:null,' +
     'exitCode:undefined,' +
     'nextTick(fn,...a){Promise.resolve().then(()=>fn(...a))},' +
     'hrtime:_h,' +

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/rolldown-plugin-gjsify",
-    "version": "0.22.0",
+    "version": "0.23.0",
     "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.22.0",
-        "@gjsify/resolve-npm": "^0.22.0",
-        "@gjsify/rolldown-plugin-deepkit": "^0.22.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.22.0",
-        "@gjsify/vite-plugin-blueprint": "^0.22.0",
+        "@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",
         "@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.22.0",
+        "@gjsify/lightningcss-native": "^0.23.0",
         "rolldown": "^1.1.4"
     },
     "peerDependenciesMeta": {