@gjsify/resolve-npm 0.18.0 → 0.20.0

package/lib/globals-map.mjs

@@ -216,6 +216,35 @@ export const GJS_GLOBALS_MAP = {
     navigator:            '@gjsify/dom-elements/register/navigator',
 };
 
+/**
+ * Reverse-bridge native-override identifiers.
+ *
+ * On a `--app node` reverse-bridge build (a genuine GJS app run on Node via
+ * `@gjsify/node-gi`, EXPLICIT `--globals` requested), the register bodies for
+ * these identifiers MUST win over the runtime-native globals the host ships —
+ * unlike the default existence-guard (`if (typeof globalThis.X === 'undefined')`),
+ * which is correct for a cross-platform package loaded on plain Node but wrong
+ * here, where the app expects GJS Web-API semantics.
+ *
+ * Only `fetch` and its constructors qualify today: Node/Bun/Deno ship a native
+ * global `fetch` (undici) that rejects the root-relative `/res/...` asset paths a
+ * browser/GJS app uses, while `@gjsify/fetch` rewrites them to `file://` against
+ * the program directory and drives Soup. Every OTHER Web/DOM global gjsify
+ * injects (`XMLHttpRequest`, `document`, `Image`, `AudioContext`, the event
+ * classes, …) is ABSENT on the host, so its guard already installs gjsify's
+ * version — no override needed. `WebAssembly`/`URL`/`crypto`/streams are host
+ * globals whose gjsify register deliberately DEFERS to the working native, so
+ * they must NOT be listed here.
+ *
+ * Consumed by the `--app node` register-inject machinery
+ * (`writeRegisterInjectFile`): the natives are cleared just before the injected
+ * register bodies run, but ONLY for identifiers whose register is actually
+ * injected (so no host global is deleted without a gjsify replacement).
+ */
+export const REVERSE_BRIDGE_NATIVE_OVERRIDE_IDENTS = [
+    'fetch', 'Headers', 'Request', 'Response',
+];
+
 /**
  * Register subpaths whose module imports a GObject-Introspection typelib
  * (`gi://…`) at load time, keyed by register-path PREFIX → the GI namespaces

package/lib/index.mjs

@@ -444,27 +444,28 @@ export const ALIASES_GENERAL_FOR_NODE = {
 /**
  * Record of GJS built-in module specifiers and their replacement for the
  * `--app node` target. These are the bare ESM module names a GJS source imports
- * (`import System from 'system'`, `import Gettext from 'gettext'`) — GJS exposes
- * them as built-in modules; Node has no equivalent, so on the node target they
- * route to the `@gjsify/node-gi` reverse-bridge shims, which are kept EXTERNAL
- * (resolved at runtime against the consumer's node_modules — see
- * `app/node.ts`'s external set), never bundled. This is the analogue of the
+ * (`import System from 'system'`, `import Gettext from 'gettext'`, `import cairo
+ * from 'cairo'`) — GJS exposes them as built-in modules; Node has no equivalent,
+ * so on the node target they route to the `@gjsify/node-gi` reverse-bridge shims,
+ * which are kept EXTERNAL (resolved at runtime against the consumer's node_modules
+ * — see `app/node.ts`'s external set), never bundled. This is the analogue of the
  * `gi://` rewrite + `@gjsify/node-gi/globals` injection, and like them it is
  * NODE-TARGET-ONLY: the gjs/browser/nativescript alias maps do not include this
- * record, so a bare `system` / `gettext` import keeps resolving natively (GJS
- * built-in / npm package) on every other target. The risk of hijacking a real
- * npm package literally named `system`/`gettext` is identical to (and bounded
- * the same way as) the `gi://` design: it only applies when building a GJS/GI
- * source for Node.
+ * record, so a bare `system` / `gettext` / `cairo` import keeps resolving natively
+ * (GJS built-in / npm package) on every other target. The risk of hijacking a real
+ * npm package literally named `system`/`gettext`/`cairo` is identical to (and
+ * bounded the same way as) the `gi://` design: it only applies when building a
+ * GJS/GI source for Node.
  *
- * `cairo` is intentionally NOT mapped — it needs a real Cairo binding (out of
- * scope here), so it falls through to the normal resolver (a `cairo` npm package
- * resolves as usual, an unresolvable bare `cairo` surfaces as a build error
- * rather than silently no-op'ing).
+ * `cairo` maps to `@gjsify/node-gi/cairo`, the native cairo binding (a FOREIGN
+ * struct in GObject-Introspection — an npm cairo package cannot stand in, since a
+ * GI function taking/returning a cairo_t must marshal through the SAME cairo module
+ * the engine's foreign-struct seam knows about).
  */
 const ALIASES_GJS_FOR_NODE = {
     'system': '@gjsify/node-gi/system',
     'gettext': '@gjsify/node-gi/gettext',
+    'cairo': '@gjsify/node-gi/cairo',
 }
 
 export { ALIASES_GJS_FOR_NODE };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/resolve-npm",
-    "version": "0.18.0",
+    "version": "0.20.0",
     "description": "Resolve NPM package aliases",
     "type": "module",
     "main": "lib/index.mjs",