@gjsify/rolldown-plugin-gjsify 0.17.0 → 0.19.0

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

package/lib/app/node.d.ts

@@ -1,5 +1,27 @@
 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
+ * on plain Node.
+ *
+ * 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;
+ *  2. the gjs target's bare→scoped register routes (`fetch/register/fetch` →
+ *     `@gjsify/fetch/register/fetch`, `xmlhttprequest/register` →
+ *     `@gjsify/fetch/register/xhr`, …) are merged in so the inject stub's bare
+ *     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
+ * loadability guarantee for cross-platform packages is not regressed).
+ */
+export declare function enableGjsRegistersForNode(baseAliases: Record<string, string>): Record<string, string>;
 export interface NodeBuildConfig {
     options: RolldownOptions;
     plugins: RolldownPluginOption[];

package/lib/app/node.js

@@ -5,8 +5,9 @@
 // translates to Rolldown's `output.banner` directly — Rolldown itself does
 // not synthesise a `require()` shim for ESM consumers of bundled CJS code.
 import { aliasPlugin } from '../plugins/alias.js';
+import blueprintPlugin from '@gjsify/vite-plugin-blueprint';
 import { deepkitPlugin } from '@gjsify/rolldown-plugin-deepkit';
-import { EXTERNALS_NODE, ALIASES_GJS_FOR_NODE } from '@gjsify/resolve-npm';
+import { EXTERNALS_NODE, ALIASES_GJS_FOR_NODE, ALIASES_WEB_FOR_GJS } from '@gjsify/resolve-npm';
 import { getAliasesForNode } from '../utils/alias.js';
 import { globToEntryPoints } from '../utils/entry-points.js';
 import { nodeModulesPathRewritePlugin, getBundleDirFromOutput } from '../plugins/rewrite-node-modules-paths.js';
@@ -22,13 +23,66 @@ import { wrapInputWithSideEffects } from '../utils/entry-wrapper.js';
  */
 const NODE_GI_GLOBALS_SPECIFIER = '@gjsify/node-gi/globals';
 /**
- * The node-gi standalone GJS built-in modules. The bare `system` / `gettext`
- * specifiers a GJS source imports are aliased to these (via `ALIASES_GJS_FOR_NODE`,
- * applied node-target-only) and, like `@gjsify/node-gi/gi`, kept EXTERNAL — they
- * load the native node-gi backend and must resolve at runtime against the
- * consumer's node_modules, never be bundled.
+ * The node-gi standalone GJS built-in modules. The bare `system` / `gettext` /
+ * `cairo` specifiers a GJS source imports are aliased to these (via
+ * `ALIASES_GJS_FOR_NODE`, applied node-target-only by `gjsBuiltinModulesNodePlugin`)
+ * and, like `@gjsify/node-gi/gi`, kept EXTERNAL — they load the native node-gi
+ * backend and must resolve at runtime against the consumer's node_modules, never
+ * be bundled.
+ *
+ * DERIVED from `ALIASES_GJS_FOR_NODE`'s VALUES so this set can never drift from
+ * the alias map again — a new bare built-in added there is externalised
+ * automatically. That completeness is LOAD-BEARING under `@gjsify/rolldown-native`
+ * (the GJS bundler engine): its JSON options boundary silently DROPS the resolveId
+ * `{ external: true }` flag that `gjsBuiltinModulesNodePlugin` returns (only the
+ * plain `external` string array survives serialization — the same reason
+ * `app/gjs.ts` routes its externals through a resolveId hook AND filters the array).
+ * So the rewritten `@gjsify/node-gi/<mod>` target stays external ONLY if it is in
+ * this array. `@gjsify/node-gi/cairo` was previously MISSING here (only `system` +
+ * `gettext` were listed), so under the GJS bundler `cairo` was left as a bare,
+ * unresolvable specifier — breaking every Cairo/PangoCairo consumer
+ * (`@gjsify/canvas2d-core`) built via the reverse bridge. Under npm `rolldown`
+ * (Node) the resolveId `external` flag IS honoured, so the gap was invisible until
+ * a Cairo consumer was built on the GJS bundler. e2e: `tests/e2e/node-gi-build`;
+ * unit: `packages/infra/cli/src/node-gi-externals.spec.ts`.
  */
-const NODE_GI_BARE_MODULE_SPECIFIERS = ['@gjsify/node-gi/system', '@gjsify/node-gi/gettext'];
+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
+ * on plain Node.
+ *
+ * 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;
+ *  2. the gjs target's bare→scoped register routes (`fetch/register/fetch` →
+ *     `@gjsify/fetch/register/fetch`, `xmlhttprequest/register` →
+ *     `@gjsify/fetch/register/xhr`, …) are merged in so the inject stub's bare
+ *     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
+ * loadability guarantee for cross-platform packages is not regressed).
+ */
+export function enableGjsRegistersForNode(baseAliases) {
+    const out = {};
+    for (const [key, value] of Object.entries(baseAliases)) {
+        if (value === '@gjsify/empty' && REGISTER_SUBPATH_RE.test(key))
+            continue;
+        out[key] = value;
+    }
+    for (const [key, value] of Object.entries(ALIASES_WEB_FOR_GJS)) {
+        if (REGISTER_SUBPATH_RE.test(key))
+            out[key] = value;
+    }
+    return out;
+}
 export const setupForNode = async (input) => {
     const userExternal = input.userExternal ?? [];
     // node-datachannel is a native C++ addon that cannot be bundled — its
@@ -89,10 +143,17 @@ export const setupForNode = async (input) => {
     const sideEffectImports = [];
     if (input.pluginOptions.nodeGiGlobalsInject)
         sideEffectImports.push(NODE_GI_GLOBALS_SPECIFIER);
+    // The explicit `--globals` register-inject stub (reverse bridge, see
+    // enableGjsRegistersForNode). Ordered AFTER the ambient-globals shim so
+    // registers may rely on `print`/`imports` being installed.
+    const registerInject = input.pluginOptions.autoGlobalsInject;
+    if (registerInject)
+        sideEffectImports.push(registerInject);
     const virtualEntries = wrapInputWithSideEffects(entryPoints, sideEffectImports);
     const finalInput = virtualEntries.input;
+    const baseAliases = getAliasesForNode({ external });
     const aliasMap = {
-        ...getAliasesForNode({ external }),
+        ...(registerInject ? enableGjsRegistersForNode(baseAliases) : baseAliases),
         ...input.pluginOptions.aliases,
         ...input.userAliases,
     };
@@ -163,10 +224,13 @@ export const setupForNode = async (input) => {
         // runtime, so a real GJS/GI source builds + runs on Node. It returns
         // null for `@girs/*`.
         gjsGiNodePlugin(),
-        // Bare GJS built-in modules (`system`/`gettext`): claimed BEFORE the
-        // aliasPlugin so they resolve to the EXTERNAL `@gjsify/node-gi/<mod>`
+        // Bare GJS built-in modules (`system`/`gettext`/`cairo`): claimed BEFORE
+        // the aliasPlugin so they resolve to the EXTERNAL `@gjsify/node-gi/<mod>`
         // shims without a disk resolution (works without node-gi installed,
-        // like gi://). Node-target-only — never active on gjs/browser/ns.
+        // like gi://). Node-target-only — never active on gjs/browser/ns. The
+        // externalisation itself rides `NODE_GI_BARE_MODULE_SPECIFIERS` in the
+        // `exactExternal` array (the resolveId `external` flag is dropped under
+        // @gjsify/rolldown-native — see that const's doc-comment).
         gjsBuiltinModulesNodePlugin(ALIASES_GJS_FOR_NODE),
         // gjsImportsEmptyPlugin then decides the fate of `@girs/*` before
         // `aliasPlugin` and the default resolver. Same composition order as
@@ -185,8 +249,19 @@ export const setupForNode = async (input) => {
         //     from the @girs package's own `gi://` specifier). `gi://*` is
         //     already claimed by gjsGiNodePlugin, so this plugin's `gi://`
         //     branch is dead on the node target either way.
-        gjsImportsEmptyPlugin({ emptyGirs: !input.pluginOptions.nodeGiGlobalsInject }),
+        // `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),
+        }),
         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
+        // `--app node` too. Only claims `.blp` files — inert for plain-Node
+        // bundles. Same plugin the gjs/browser targets compose.
+        blueprintPlugin(),
         deepkitPlugin({ reflection: input.pluginOptions.reflection }),
         cssAsStringPlugin(),
         nodeModulesPathRewritePlugin({ bundleDir }),

package/lib/plugins/gjs-gi-node.d.ts

@@ -9,14 +9,21 @@ export declare function giNodeShimSource(namespace: string, version?: string): s
 export declare function gjsGiNodePlugin(): Plugin;
 /**
  * For `--app node`: rewrite the bare GJS built-in module specifiers (`system`,
- * `gettext`) to their `@gjsify/node-gi` reverse-bridge shims, kept EXTERNAL.
+ * `gettext`, `cairo`) to their `@gjsify/node-gi` reverse-bridge shims, kept
+ * EXTERNAL.
  *
- * GJS exposes `system`/`gettext` as built-in ESM modules
+ * GJS exposes `system`/`gettext`/`cairo` as built-in ESM modules
  * (`import System from 'system'`); Node has no equivalent. This resolves the
- * bare specifier to `@gjsify/node-gi/system` / `@gjsify/node-gi/gettext` and
- * marks it external so it is NOT bundled — resolved at runtime against the
- * consumer's node_modules, exactly like `@gjsify/node-gi/gi` (the `gi://`
- * rewrite) and `@gjsify/node-gi/globals`.
+ * bare specifier to `@gjsify/node-gi/system` / `@gjsify/node-gi/gettext` /
+ * `@gjsify/node-gi/cairo` and marks it external so it is NOT bundled — resolved
+ * at runtime against the consumer's node_modules, exactly like
+ * `@gjsify/node-gi/gi` (the `gi://` rewrite) and `@gjsify/node-gi/globals`.
+ *
+ * NOTE: the `{ external: true }` flag returned here is honoured by npm `rolldown`
+ * but DROPPED by `@gjsify/rolldown-native` at its JSON options boundary, so
+ * `app/node.ts` ALSO lists these targets in its `exactExternal` string array
+ * (`NODE_GI_BARE_MODULE_SPECIFIERS`, derived from `ALIASES_GJS_FOR_NODE`) — the
+ * array is what actually keeps them external under the GJS bundler engine.
  *
  * Returning `{ external: true }` from `resolveId` is the form honoured by BOTH
  * bundler engines (npm rolldown on Node AND `@gjsify/rolldown-native` on GJS,

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

@@ -96,14 +96,21 @@ export function gjsGiNodePlugin() {
 }
 /**
  * For `--app node`: rewrite the bare GJS built-in module specifiers (`system`,
- * `gettext`) to their `@gjsify/node-gi` reverse-bridge shims, kept EXTERNAL.
+ * `gettext`, `cairo`) to their `@gjsify/node-gi` reverse-bridge shims, kept
+ * EXTERNAL.
  *
- * GJS exposes `system`/`gettext` as built-in ESM modules
+ * GJS exposes `system`/`gettext`/`cairo` as built-in ESM modules
  * (`import System from 'system'`); Node has no equivalent. This resolves the
- * bare specifier to `@gjsify/node-gi/system` / `@gjsify/node-gi/gettext` and
- * marks it external so it is NOT bundled — resolved at runtime against the
- * consumer's node_modules, exactly like `@gjsify/node-gi/gi` (the `gi://`
- * rewrite) and `@gjsify/node-gi/globals`.
+ * bare specifier to `@gjsify/node-gi/system` / `@gjsify/node-gi/gettext` /
+ * `@gjsify/node-gi/cairo` and marks it external so it is NOT bundled — resolved
+ * at runtime against the consumer's node_modules, exactly like
+ * `@gjsify/node-gi/gi` (the `gi://` rewrite) and `@gjsify/node-gi/globals`.
+ *
+ * NOTE: the `{ external: true }` flag returned here is honoured by npm `rolldown`
+ * but DROPPED by `@gjsify/rolldown-native` at its JSON options boundary, so
+ * `app/node.ts` ALSO lists these targets in its `exactExternal` string array
+ * (`NODE_GI_BARE_MODULE_SPECIFIERS`, derived from `ALIASES_GJS_FOR_NODE`) — the
+ * array is what actually keeps them external under the GJS bundler engine.
  *
  * Returning `{ external: true }` from `resolveId` is the form honoured by BOTH
  * bundler engines (npm rolldown on Node AND `@gjsify/rolldown-native` on GJS,

package/lib/utils/runtime.d.ts

@@ -1,18 +1,71 @@
+/**
+ * `true` when running under Bun.
+ *
+ * Bun exposes a `globalThis.Bun` object no other runtime provides. Probed
+ * FIRST in {@link hostRuntime} because Bun also fakes `process.versions.node`
+ * for npm compatibility — a bare `process.versions.node` read is a false Node
+ * positive there.
+ */
+export declare function isBun(): boolean;
+/**
+ * `true` when running under Deno.
+ *
+ * Deno exposes a `globalThis.Deno` object no other runtime provides. Like Bun,
+ * Deno also fakes `process.versions.node`, so it must be probed before the Node
+ * fallback.
+ */
+export declare function isDeno(): boolean;
 /**
  * `true` when running under GJS (GNOME JavaScript / SpiderMonkey).
  *
  * Detected via the GObject-Introspection bridge `globalThis.imports.gi`, which
- * only exists under GJS — Node and browsers never expose it. This is the
- * canonical gjsify host probe; prefer it over re-inlining the `imports.gi`
+ * only exists under GJS — Node, Bun, Deno and browsers never expose it. This is
+ * the canonical gjsify host probe; prefer it over re-inlining the `imports.gi`
  * check.
  */
 export declare function isGjs(): boolean;
 /**
- * `true` when running under Node.js.
+ * The JS runtime hosting the gjsify tooling: `gjs`, `node`, `bun` or `deno`.
+ *
+ * The single source of truth for host-derived defaults (the default `--app`
+ * build target and the default `--runtime` in `run`/`showcase`/`storybook`).
  *
- * GJS is checked FIRST and short-circuits to `false`: `@gjsify/process` sets
- * `process.versions.node` (for npm-package compatibility), so a bare
- * `process.versions.node` probe is a false Node positive under GJS. Guarding
- * with `isGjs()` keeps the two host predicates mutually exclusive.
+ * Probe order mirrors `packages/node-gi/node-gi/index.js`: **Bun and Deno
+ * first** because both fake `process.versions.node` for npm compatibility (so a
+ * `process.versions.node` read is a false Node positive there), then GJS (its
+ * `@gjsify/process` shim likewise fakes `process.versions.node`), then real
+ * Node. Falls back to `node` when nothing matches (e.g. an exotic host) — the
+ * gjsify tooling only runs on these four.
+ */
+export declare function hostRuntime(): 'gjs' | 'node' | 'bun' | 'deno';
+/**
+ * `true` when running under Node.js — and NOT Bun or Deno.
+ *
+ * Bun and Deno both set `process.versions.node` for npm compatibility, so a
+ * bare `process.versions.node` probe is a false Node positive on either — the
+ * historical bug this guard fixes. GJS (via `@gjsify/process`) does the same.
+ * Guarding on all three keeps the four host predicates mutually exclusive: a
+ * host is exactly one of gjs / node / bun / deno.
  */
 export declare function isNode(): boolean;
+/**
+ * The raw GJS runtime version from `imports.system.version` (e.g. `18800` for
+ * GJS 1.88.0), or `undefined` when not running under GJS.
+ *
+ * A distinct probe from {@link isGjs}: use it where the caller needs the numeric
+ * version (to format a banner) OR an early GJS short-circuit that must not rely
+ * on `@gjsify/process`'s faked `process.versions.node`.
+ */
+export declare function gjsSystemVersion(): number | undefined;
+/**
+ * Force a hard exit under GJS via `imports.system.exit(code)`.
+ *
+ * GJS has no atexit hook and would exit 0 at natural shutdown, so a non-zero
+ * `process.exitCode` alone does not stick — the CLI must call `system.exit`
+ * explicitly there. Node never exposes `imports`, so this is a no-op returning
+ * `false`, letting callers fall back to `process.exit`/`process.exitCode`.
+ *
+ * @returns `true` when the GJS exit was invoked (running under GJS); `false` on
+ *          Node (the caller owns the Node exit path).
+ */
+export declare function gjsExit(code: number): boolean;

package/lib/utils/runtime.js

@@ -12,28 +12,102 @@
 // so it stays loadable on every host and so consumers can import it via the
 // `@gjsify/rolldown-plugin-gjsify/runtime` subpath without pulling the rest of
 // the plugin (which transitively loads blueprint-compiler, deepkit, etc.).
+/**
+ * `true` when running under Bun.
+ *
+ * Bun exposes a `globalThis.Bun` object no other runtime provides. Probed
+ * FIRST in {@link hostRuntime} because Bun also fakes `process.versions.node`
+ * for npm compatibility — a bare `process.versions.node` read is a false Node
+ * positive there.
+ */
+export function isBun() {
+    return typeof globalThis.Bun !== 'undefined';
+}
+/**
+ * `true` when running under Deno.
+ *
+ * Deno exposes a `globalThis.Deno` object no other runtime provides. Like Bun,
+ * Deno also fakes `process.versions.node`, so it must be probed before the Node
+ * fallback.
+ */
+export function isDeno() {
+    return typeof globalThis.Deno !== 'undefined';
+}
 /**
  * `true` when running under GJS (GNOME JavaScript / SpiderMonkey).
  *
  * Detected via the GObject-Introspection bridge `globalThis.imports.gi`, which
- * only exists under GJS — Node and browsers never expose it. This is the
- * canonical gjsify host probe; prefer it over re-inlining the `imports.gi`
+ * only exists under GJS — Node, Bun, Deno and browsers never expose it. This is
+ * the canonical gjsify host probe; prefer it over re-inlining the `imports.gi`
  * check.
  */
 export function isGjs() {
     return typeof globalThis.imports?.gi !== 'undefined';
 }
 /**
- * `true` when running under Node.js.
+ * The JS runtime hosting the gjsify tooling: `gjs`, `node`, `bun` or `deno`.
+ *
+ * The single source of truth for host-derived defaults (the default `--app`
+ * build target and the default `--runtime` in `run`/`showcase`/`storybook`).
  *
- * GJS is checked FIRST and short-circuits to `false`: `@gjsify/process` sets
- * `process.versions.node` (for npm-package compatibility), so a bare
- * `process.versions.node` probe is a false Node positive under GJS. Guarding
- * with `isGjs()` keeps the two host predicates mutually exclusive.
+ * Probe order mirrors `packages/node-gi/node-gi/index.js`: **Bun and Deno
+ * first** because both fake `process.versions.node` for npm compatibility (so a
+ * `process.versions.node` read is a false Node positive there), then GJS (its
+ * `@gjsify/process` shim likewise fakes `process.versions.node`), then real
+ * Node. Falls back to `node` when nothing matches (e.g. an exotic host) — the
+ * gjsify tooling only runs on these four.
  */
-export function isNode() {
+export function hostRuntime() {
+    if (isBun())
+        return 'bun';
+    if (isDeno())
+        return 'deno';
     if (isGjs())
+        return 'gjs';
+    return 'node';
+}
+/**
+ * `true` when running under Node.js — and NOT Bun or Deno.
+ *
+ * Bun and Deno both set `process.versions.node` for npm compatibility, so a
+ * bare `process.versions.node` probe is a false Node positive on either — the
+ * historical bug this guard fixes. GJS (via `@gjsify/process`) does the same.
+ * Guarding on all three keeps the four host predicates mutually exclusive: a
+ * host is exactly one of gjs / node / bun / deno.
+ */
+export function isNode() {
+    if (isBun() || isDeno() || isGjs())
         return false;
     const proc = globalThis.process;
     return typeof proc?.versions?.node === 'string';
 }
+/**
+ * The raw GJS runtime version from `imports.system.version` (e.g. `18800` for
+ * GJS 1.88.0), or `undefined` when not running under GJS.
+ *
+ * A distinct probe from {@link isGjs}: use it where the caller needs the numeric
+ * version (to format a banner) OR an early GJS short-circuit that must not rely
+ * on `@gjsify/process`'s faked `process.versions.node`.
+ */
+export function gjsSystemVersion() {
+    return globalThis.imports?.system?.version;
+}
+/**
+ * Force a hard exit under GJS via `imports.system.exit(code)`.
+ *
+ * GJS has no atexit hook and would exit 0 at natural shutdown, so a non-zero
+ * `process.exitCode` alone does not stick — the CLI must call `system.exit`
+ * explicitly there. Node never exposes `imports`, so this is a no-op returning
+ * `false`, letting callers fall back to `process.exit`/`process.exitCode`.
+ *
+ * @returns `true` when the GJS exit was invoked (running under GJS); `false` on
+ *          Node (the caller owns the Node exit path).
+ */
+export function gjsExit(code) {
+    const sys = globalThis.imports?.system;
+    if (sys?.exit) {
+        sys.exit(code);
+        return true;
+    }
+    return false;
+}

package/lib/utils/scan-globals.d.ts

@@ -46,6 +46,19 @@ export declare function isRegisterPathResolvable(registerPath: string, fromDir:
  * the gap visible so the developer can add the dep explicitly.
  */
 export declare function filterResolvableRegisterPaths(registerPaths: Set<string>, fromDir: string): Set<string>;
+/** Options for {@link writeRegisterInjectFile}. */
+export interface WriteRegisterInjectOptions {
+    /**
+     * Reverse-bridge (`--app node`) force-override: before the injected register
+     * bodies run, clear the runtime-native web globals gjsify must OWN on the
+     * reverse bridge (the `REVERSE_BRIDGE_NATIVE_OVERRIDE_IDENTS` set — today the
+     * `fetch` family). A native is cleared ONLY when its register is actually in
+     * `registerPaths`, so no host global is deleted without a gjsify replacement.
+     * No-op (and byte-unchanged output) for the GJS target or when none of the
+     * override identifiers are injected.
+     */
+    reverseBridgeOverride?: boolean;
+}
 /**
  * Write a stub ESM file with `import` statements for the given register
  * paths and return its absolute path, suitable for passing to esbuild's
@@ -56,5 +69,13 @@ export declare function filterResolvableRegisterPaths(registerPaths: Set<string>
  *
  * The file name is hashed by content so repeated builds with the same
  * set reuse the same file (no churn, idempotent on disk).
+ *
+ * On the reverse bridge (`options.reverseBridgeOverride`, `--app node`) the stub
+ * is prefixed with a side-effect import of a generated clear-natives module —
+ * imported FIRST so, by ESM depth-first source-order evaluation, the native
+ * `fetch`/`Headers`/`Request`/`Response` are deleted BEFORE the register bodies
+ * run and reinstall gjsify's versions over them. Kept in a separate module
+ * (not a leading statement) because ESM hoists the register `import`s above any
+ * statement in the same module.
  */
-export declare function writeRegisterInjectFile(registerPaths: Set<string>, cwd?: string): Promise<string | null>;
+export declare function writeRegisterInjectFile(registerPaths: Set<string>, cwd?: string, options?: WriteRegisterInjectOptions): Promise<string | null>;

package/lib/utils/scan-globals.js

@@ -14,10 +14,11 @@ import { writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
-import { GJS_GLOBALS_MAP, GJS_GLOBALS_GROUPS } from '@gjsify/resolve-npm/globals-map';
+import { GJS_GLOBALS_MAP, GJS_GLOBALS_GROUPS, REVERSE_BRIDGE_NATIVE_OVERRIDE_IDENTS } from '@gjsify/resolve-npm/globals-map';
 import { ALIASES_WEB_FOR_GJS } from '@gjsify/resolve-npm';
 const GLOBALS_MAP = GJS_GLOBALS_MAP;
 const GLOBALS_GROUPS = GJS_GLOBALS_GROUPS;
+const NATIVE_OVERRIDE_IDENTS = REVERSE_BRIDGE_NATIVE_OVERRIDE_IDENTS;
 /**
  * Resolve a `--globals` CLI argument into the set of `/register` subpaths
  * that must be injected into the build.
@@ -166,6 +167,21 @@ export function filterResolvableRegisterPaths(registerPaths, fromDir) {
     }
     return out;
 }
+/**
+ * Identifiers whose native global must be cleared before the injected registers
+ * run, given the set of register paths being injected. Only identifiers whose
+ * register is actually present are returned — clearing a native without a
+ * gjsify replacement in the same build would leave a hole.
+ */
+function nativeOverrideIdentsFor(registerPaths) {
+    const out = [];
+    for (const id of NATIVE_OVERRIDE_IDENTS) {
+        const registerPath = GLOBALS_MAP[id];
+        if (registerPath && registerPaths.has(registerPath))
+            out.push(id);
+    }
+    return out;
+}
 /**
  * Write a stub ESM file with `import` statements for the given register
  * paths and return its absolute path, suitable for passing to esbuild's
@@ -176,15 +192,37 @@ export function filterResolvableRegisterPaths(registerPaths, fromDir) {
  *
  * The file name is hashed by content so repeated builds with the same
  * set reuse the same file (no churn, idempotent on disk).
+ *
+ * On the reverse bridge (`options.reverseBridgeOverride`, `--app node`) the stub
+ * is prefixed with a side-effect import of a generated clear-natives module —
+ * imported FIRST so, by ESM depth-first source-order evaluation, the native
+ * `fetch`/`Headers`/`Request`/`Response` are deleted BEFORE the register bodies
+ * run and reinstall gjsify's versions over them. Kept in a separate module
+ * (not a leading statement) because ESM hoists the register `import`s above any
+ * statement in the same module.
  */
-export async function writeRegisterInjectFile(registerPaths, cwd = process.cwd()) {
+export async function writeRegisterInjectFile(registerPaths, cwd = process.cwd(), options = {}) {
     if (registerPaths.size === 0)
         return null;
-    const sorted = [...registerPaths].sort();
-    const content = sorted.map((p) => `import '${p}';`).join('\n') + '\n';
-    const hash = createHash('sha1').update(content).digest('hex').slice(0, 10);
     const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify');
     await mkdir(cacheDir, { recursive: true });
+    const sorted = [...registerPaths].sort();
+    const lines = [];
+    const overrideIdents = options.reverseBridgeOverride ? nativeOverrideIdentsFor(registerPaths) : [];
+    if (overrideIdents.length > 0) {
+        const list = JSON.stringify(overrideIdents.sort());
+        const clearContent = '// gjsify --app node reverse-bridge: clear runtime-native web globals so the\n' +
+            '// injected @gjsify/* register bodies install their GJS-semantics versions.\n' +
+            `for (const __k of ${list}) { try { delete globalThis[__k]; } catch {} }\n`;
+        const clearHash = createHash('sha1').update(clearContent).digest('hex').slice(0, 10);
+        const clearName = `auto-globals-override-${clearHash}.mjs`;
+        await writeFile(join(cacheDir, clearName), clearContent, 'utf-8');
+        lines.push(`import './${clearName}';`);
+    }
+    for (const p of sorted)
+        lines.push(`import '${p}';`);
+    const content = lines.join('\n') + '\n';
+    const hash = createHash('sha1').update(content).digest('hex').slice(0, 10);
     const path = join(cacheDir, `auto-globals-${hash}.mjs`);
     await writeFile(path, content, 'utf-8');
     return path;

package/package.json

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