@gjsify/resolve-npm 0.21.0 → 0.23.0

package/lib/globals-map.mjs

@@ -214,6 +214,23 @@ export const GJS_GLOBALS_MAP = {
     matchMedia:           '@gjsify/dom-elements/register/match-media',
     location:             '@gjsify/dom-elements/register/location',
     navigator:            '@gjsify/dom-elements/register/navigator',
+
+    // --- Canvas 2D + IFrame + WebGL (GTK/WebKit-backed DOM classes) --------
+    //
+    // These live in `packages/framework/*` rather than a Web/DOM pillar because
+    // their implementations are GTK/Cairo-, WebKit- and Gwebgl/GLArea-bound
+    // (ADR 0012). They are DELIBERATELY NOT members of `GJS_GLOBALS_GROUPS.dom`:
+    // that group is the coarse `--globals auto,dom` safety net, and pulling
+    // these into it would make every `auto,dom` build hard-require
+    // `@gjsify/canvas2d` / `@gjsify/iframe` / `@gjsify/webgl` (and, for the
+    // second, WebKitGTK) as an installed dependency. Auto-detection injects them
+    // only when the identifier is actually referenced in the bundled,
+    // tree-shaken output.
+    ImageData:            '@gjsify/canvas2d/register',
+    Path2D:               '@gjsify/canvas2d/register',
+    HTMLIFrameElement:    '@gjsify/iframe/register',
+    WebGLRenderingContext:  '@gjsify/webgl/register',
+    WebGL2RenderingContext: '@gjsify/webgl/register',
 };
 
 /**
@@ -268,6 +285,19 @@ export const GJS_GI_BACKED_REGISTERS = {
     '@gjsify/webaudio/register':     ['Gst', 'GstApp'],
     '@gjsify/webrtc/register':       ['Gst', 'GstWebRTC', 'GstSdp'],
     '@gjsify/gamepad/register':      ['Manette'],
+    // Imports `@gjsify/dom-elements/register/canvas` (Gdk/GdkPixbuf/Pango/
+    // PangoCairo) plus `@gjsify/canvas2d-core`, which uses the `cairo` foreign
+    // struct module.
+    '@gjsify/canvas2d/register':     ['Gdk', 'GdkPixbuf', 'Pango', 'PangoCairo'],
+    '@gjsify/iframe/register':       ['WebKit'],
+    // The WebGL context classes reach the GL driver through the `gwebgl` Vala
+    // bridge shipped as this package's own prebuild, and decode `texImage2D`
+    // sources via GdkPixbuf. Gtk/Gdk are NOT listed: they are pulled by
+    // `webgl-bridge.ts` (the `Gtk.GLArea` widget), which the register does not
+    // import — its chain is the two context classes only. As with the entries
+    // above, the always-present base namespaces (GLib) are omitted; only the
+    // ones whose absence breaks a GTK-less host are worth naming.
+    '@gjsify/webgl/register':        ['GdkPixbuf', 'Gwebgl'],
 };
 
 // ─── Browser target ────────────────────────────────────────────────────────

package/lib/index.mjs

@@ -11,6 +11,68 @@ export {
     resetRuntimeAliasesCache,
 } from './runtime-aliases.mjs';
 
+import { getDerivedAliasesSync as _getDerivedAliasesSync } from './runtime-aliases.mjs';
+
+/**
+ * Wrap a bare-specifier alias table so its `@gjsify/<X>` VALUES are passed
+ * through the derived per-target slot routing before the caller sees them.
+ *
+ * ## Why this exists (ADR 0014)
+ *
+ * The alias layer was designed as a TWO-PASS chain, and `app/browser.ts` says
+ * so in its own comment: the curated table maps a bare specifier
+ * (`os`, `node:os`) to `@gjsify/<X>`, and "the dynamic per-runtimes-triplet
+ * resolver (`getDerivedAliasesSync`) finishes the routing in a second pass".
+ *
+ * That second pass never fires for a bare specifier. `aliasPlugin` resolves a
+ * hit via `this.resolve(target, importer, { skipSelf: true })`, and `skipSelf`
+ * deliberately excludes the gjsify alias plugin from the nested resolution —
+ * so `os` → `@gjsify/os` lands on the package ROOT and the derived entry
+ * `@gjsify/os` → `@gjsify/os/browser` is never consulted. A direct
+ * `import … from '@gjsify/os'` in source DOES route (single hop, verified);
+ * a browser bundle importing bare `os` does not. Since every browser bundle
+ * reaches these packages through the bare/`node:` form, the platform-entry
+ * routing of ADR 0014 would have been inert without this.
+ *
+ * Composing the two maps here — at the point the bare table is materialised —
+ * collapses the chain to a single hop, keeps the curated table itself a pure
+ * bare-name → package statement (no slot policy duplicated into it), and needs
+ * no change in the bundler plugins.
+ *
+ * Evaluated LAZILY (on property read) and cached: `getDerivedAliasesSync` walks
+ * the workspace, and importing `@gjsify/resolve-npm` must not pay for a
+ * filesystem scan that a `--app gjs` build never needs. The trap set covers
+ * everything a consumer does with these tables — `Object.entries`, spread and
+ * direct indexing.
+ *
+ * @param {Record<string,string>} table
+ * @param {'gjs'|'node'|'browser'|'nativescript'} target
+ * @returns {Record<string,string>}
+ */
+function withDerivedSlotRouting(table, target) {
+    /** @type {Record<string,string>|null} */
+    let routed = null;
+    const materialise = () => {
+        if (routed) return routed;
+        const derived = _getDerivedAliasesSync(target);
+        /** @type {Record<string,string>} */
+        const out = {};
+        for (const [bare, pkg] of Object.entries(table)) {
+            out[bare] = Object.prototype.hasOwnProperty.call(derived, pkg) ? derived[pkg] : pkg;
+        }
+        routed = out;
+        return routed;
+    };
+    return new Proxy(table, {
+        get: (_t, prop) =>
+            typeof prop === 'string' ? materialise()[prop] : Reflect.get(table, prop),
+        has: (_t, prop) => Reflect.has(materialise(), prop),
+        ownKeys: () => Reflect.ownKeys(materialise()),
+        getOwnPropertyDescriptor: (_t, prop) =>
+            Reflect.getOwnPropertyDescriptor(materialise(), prop),
+    });
+}
+
 /** Array of Node.js build in module names */
 export const EXTERNALS_NODE = [
     'assert',
@@ -202,7 +264,7 @@ export const ALIASES_NODE_FOR_GJS = {
  * baubable `@gjsify/{process,buffer,stream,...}` builds. Adopt only when the
  * per-package browser slots are R1-validated.
  */
-export const ALIASES_NODE_FOR_BROWSER = {
+const ALIASES_NODE_FOR_BROWSER_TABLE = {
     'assert':              '@gjsify/assert',
     'assert/strict':       '@gjsify/assert/strict',
     'async_hooks':         '@gjsify/async_hooks',
@@ -263,6 +325,18 @@ export const ALIASES_NODE_FOR_BROWSER = {
     'isomorphic-ws':       '@gjsify/empty',
 }
 
+/**
+ * Bare Node-builtin specifier → polyfill / empty-stub mapping for `--app
+ * browser`, with ADR-0014 platform-entry routing already applied to the values
+ * (`os` → `@gjsify/os/browser` when that package's browser slot is `polyfill`
+ * and it exports a `./browser` subpath). See `withDerivedSlotRouting` above for
+ * why the two-pass chain has to be collapsed here.
+ */
+export const ALIASES_NODE_FOR_BROWSER = withDerivedSlotRouting(
+    ALIASES_NODE_FOR_BROWSER_TABLE,
+    'browser',
+);
+
 /**
  * Bare Node-builtin specifier → polyfill / empty-stub mapping for `--app
  * nativescript` builds. Mirrors `ALIASES_NODE_FOR_BROWSER` in shape, with
@@ -559,6 +633,14 @@ export const ALIASES_WEB_FOR_NODE = {
     '@gjsify/dom-elements/register/match-media': '@gjsify/empty',
     '@gjsify/dom-elements/register/location': '@gjsify/empty',
     '@gjsify/dom-elements/register/navigator': '@gjsify/empty',
+    // Canvas 2D + IFrame + WebGL registers (GTK/Cairo-, WebKit- and
+    // Gwebgl/GLArea-backed, ADR 0012) — no-op on Node, exactly like the
+    // dom-elements registers above. Only the `@gjsify/*`-qualified form is
+    // mirrored: per ADR 0012 no bare-specifier `/register` alias is invented for
+    // a framework package.
+    '@gjsify/canvas2d/register': '@gjsify/empty',
+    '@gjsify/iframe/register': '@gjsify/empty',
+    '@gjsify/webgl/register': '@gjsify/empty',
     '@gjsify/buffer/register': '@gjsify/empty',
 
     // xmlhttprequest + DOMParser — no-op on Node

package/lib/register-globals-closure.mjs

@@ -33,6 +33,32 @@ export const REGISTER_GLOBALS_CLOSURE = {
         "setTimeout",
         "structuredClone"
     ],
+    "@gjsify/canvas2d/register": [
+        "AbortController",
+        "AbortSignal",
+        "Blob",
+        "Buffer",
+        "ByteLengthQueuingStrategy",
+        "CountQueuingStrategy",
+        "DOMException",
+        "File",
+        "HTMLCanvasElement",
+        "Path2D",
+        "ReadableStream",
+        "TextDecoderStream",
+        "TextEncoderStream",
+        "TransformStream",
+        "WritableStream",
+        "atob",
+        "btoa",
+        "clearTimeout",
+        "document",
+        "performance",
+        "process",
+        "queueMicrotask",
+        "setTimeout",
+        "structuredClone"
+    ],
     "@gjsify/dom-elements/register/canvas": [
         "AbortController",
         "AbortSignal",
@@ -43,6 +69,7 @@ export const REGISTER_GLOBALS_CLOSURE = {
         "DOMException",
         "File",
         "HTMLCanvasElement",
+        "Path2D",
         "ReadableStream",
         "TextDecoderStream",
         "TextEncoderStream",
@@ -68,6 +95,7 @@ export const REGISTER_GLOBALS_CLOSURE = {
         "DOMException",
         "File",
         "HTMLCanvasElement",
+        "Path2D",
         "ReadableStream",
         "TextDecoderStream",
         "TextEncoderStream",
@@ -115,6 +143,7 @@ export const REGISTER_GLOBALS_CLOSURE = {
         "DOMException",
         "File",
         "HTMLCanvasElement",
+        "Path2D",
         "ReadableStream",
         "TextDecoderStream",
         "TextEncoderStream",
@@ -262,6 +291,33 @@ export const REGISTER_GLOBALS_CLOSURE = {
         "setTimeout",
         "structuredClone"
     ],
+    "@gjsify/iframe/register": [
+        "AbortController",
+        "AbortSignal",
+        "Blob",
+        "Buffer",
+        "ByteLengthQueuingStrategy",
+        "CountQueuingStrategy",
+        "DOMException",
+        "File",
+        "HTMLCanvasElement",
+        "HTMLIFrameElement",
+        "Path2D",
+        "ReadableStream",
+        "TextDecoderStream",
+        "TextEncoderStream",
+        "TransformStream",
+        "WritableStream",
+        "atob",
+        "btoa",
+        "clearTimeout",
+        "document",
+        "performance",
+        "process",
+        "queueMicrotask",
+        "setTimeout",
+        "structuredClone"
+    ],
     "@gjsify/node-globals/register/buffer": [
         "AbortController",
         "AbortSignal",
@@ -489,6 +545,33 @@ export const REGISTER_GLOBALS_CLOSURE = {
         "setTimeout",
         "structuredClone"
     ],
+    "@gjsify/webgl/register": [
+        "AbortController",
+        "AbortSignal",
+        "Blob",
+        "Buffer",
+        "ByteLengthQueuingStrategy",
+        "CountQueuingStrategy",
+        "DOMException",
+        "File",
+        "HTMLCanvasElement",
+        "Path2D",
+        "ReadableStream",
+        "TextDecoderStream",
+        "TextEncoderStream",
+        "TransformStream",
+        "WebGL2RenderingContext",
+        "WritableStream",
+        "atob",
+        "btoa",
+        "clearTimeout",
+        "document",
+        "performance",
+        "process",
+        "queueMicrotask",
+        "setTimeout",
+        "structuredClone"
+    ],
     "@gjsify/webrtc/register/data-channel": [
         "AbortController",
         "AbortSignal",
@@ -831,11 +914,8 @@ export const REGISTER_GLOBALS_CLOSURE = {
         "CountQueuingStrategy",
         "DOMException",
         "DecompressionStream",
-        "Event",
-        "EventTarget",
         "File",
         "Headers",
-        "ProgressEvent",
         "ReadableStream",
         "Request",
         "Response",

package/lib/runtime-aliases.mjs

@@ -16,7 +16,9 @@
 // The bundler's alias resolver consults this triplet when routing bare
 // `@gjsify/<X>` specifiers per `--app <target>`:
 //
-//   slot=polyfill → keep as-is (`@gjsify/<X>` — our impl ships)
+//   slot=polyfill → `@gjsify/<X>/<target>` when the package's `exports` map
+//                   declares that platform-entry subpath (ADR 0014), else keep
+//                   as-is (`@gjsify/<X>` — the shared impl ships)
 //   slot=native   → redirect to `@gjsify/<X>/globals` (re-exports native value)
 //   slot=partial  → keep as-is (our impl, gracefully degrades at runtime)
 //   slot=none     → no rewrite (the package's polyfill resolves normally;
@@ -32,6 +34,30 @@
 // When a slot=native package is missing the corresponding `globals.mjs`
 // re-export file, the resolver emits a warn-once log and falls back to
 // `@gjsify/empty` (the current behavior) — surfacing the gap is desirable.
+//
+// ── Platform-entry routing (ADR 0014) ──────────────────────────────────────
+//
+// `polyfill` is the STRONG promise: "our implementation fully covers this API
+// on this runtime". A package can only keep that promise off GJS if the code
+// the target actually resolves is free of GLib/Gio. Several packages already
+// ship a real per-target implementation (`src/browser.ts` → the `./browser`
+// export subpath) but nothing ever routed to it: the root `.` export has no
+// `"browser"` condition and the alias layer kept `polyfill` as a no-op, so the
+// GJS body was bundled for the browser and every GLib call TypeError'd against
+// the `{}` that `gjsImportsEmptyPlugin` substitutes for `@girs/*`.
+//
+// So: on a NON-gjs target, `slot=polyfill` routes to `@gjsify/<X>/<target>`
+// whenever the package's `exports` map declares that subpath. The `gjs` target
+// is never rerouted (`src/index.ts` IS the GJS implementation).
+//
+// `partial` deliberately does NOT route. `partial` is the weak promise ("works
+// here, degrades") and the shared body's degradation IS its contract; the
+// `partial` packages' platform entries are also not yet at export parity with
+// their root entry (`@gjsify/fs`'s `src/browser.ts` is missing 34 value
+// exports), so routing them would turn a call-time degradation into a
+// build-time MISSING_EXPORT. Reaching parity is exactly the work that promotes
+// a package from `partial` to `polyfill`; `scripts/audit-runtimes.mjs`
+// (`platform-entry-parity` probe) gates that promotion.
 
 import { readdir, readFile } from 'node:fs/promises';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
@@ -41,6 +67,28 @@ import { fileURLToPath } from 'node:url';
 const VALID_SLOTS = new Set(['polyfill', 'native', 'partial', 'none']);
 const VALID_TARGETS = new Set(['gjs', 'node', 'browser', 'nativescript']);
 
+/**
+ * Collect the target names for which `exports` declares a `./<target>`
+ * platform-entry subpath. Shared by the sync + async package ingesters so the
+ * two paths cannot drift.
+ *
+ * @param {unknown} exportsField
+ * @returns {Set<string>}
+ */
+function collectPlatformEntries(exportsField) {
+    /** @type {Set<string>} */
+    const found = new Set();
+    if (!exportsField || typeof exportsField !== 'object') return found;
+    for (const target of VALID_TARGETS) {
+        // The `gjs` target is never a platform entry — `.` IS the GJS impl.
+        if (target === 'gjs') continue;
+        if (Object.prototype.hasOwnProperty.call(exportsField, `./${target}`)) {
+            found.add(target);
+        }
+    }
+    return found;
+}
+
 /** @typedef {'polyfill'|'native'|'partial'|'none'} Slot */
 /**
  * Per-package runtime slot declaration. Quadruplet (gjs / node / browser /
@@ -50,7 +98,14 @@ const VALID_TARGETS = new Set(['gjs', 'node', 'browser', 'nativescript']);
  *
  * @typedef {{gjs?:Slot, node?:Slot, browser?:Slot, nativescript?:Slot}} RuntimeTriplet
  */
-/** @typedef {{name:string, dir:string, runtimes:RuntimeTriplet, hasGlobals:boolean}} PackageRecord */
+/**
+ * @typedef {{name:string, dir:string, runtimes:RuntimeTriplet, hasGlobals:boolean,
+ *            platformEntries:Set<string>}} PackageRecord
+ *
+ * `platformEntries` holds the target names (`browser` / `nativescript` / …)
+ * for which the package's `exports` map declares a `./<target>` subpath — the
+ * per-runtime implementation entry that `slot=polyfill` routes to (ADR 0014).
+ */
 
 let _cache = null;
 const _warned = new Set();
@@ -145,7 +200,8 @@ async function ingestPackageDir(dir, out) {
                 }
             }
             const hasGlobals = existsSync(join(dir, 'globals.mjs'));
-            out.set(name, { name, dir, runtimes: triplet, hasGlobals });
+            const platformEntries = collectPlatformEntries(json?.exports);
+            out.set(name, { name, dir, runtimes: triplet, hasGlobals, platformEntries });
         }
     } catch {
         // Ignore unreadable / invalid package.json
@@ -180,7 +236,8 @@ function ingestPackageDirSync(dir, out) {
                 }
             }
             const hasGlobals = existsSync(join(dir, 'globals.mjs'));
-            out.set(name, { name, dir, runtimes: triplet, hasGlobals });
+            const platformEntries = collectPlatformEntries(json?.exports);
+            out.set(name, { name, dir, runtimes: triplet, hasGlobals, platformEntries });
         }
     } catch {
         // Ignore unreadable / invalid package.json
@@ -328,8 +385,21 @@ function resolveSlot(rec, target) {
     if (!slot) return null; // Slot undeclared → no opinion, leave to hardcoded maps.
     switch (slot) {
         case 'polyfill':
+            // ADR 0014 — platform-entry routing. `polyfill` promises a FULL
+            // implementation on this runtime; when the package ships a
+            // per-target entry (`exports["./<target>"]`), that entry IS the
+            // implementation for the target and the shared `.` body (which on
+            // most packages is the GLib/Gio-backed GJS impl) must not be
+            // bundled. Never applies to `gjs` — `.` is the GJS impl.
+            if (target !== 'gjs' && rec.platformEntries?.has(target)) {
+                return `${rec.name}/${target}`;
+            }
+            // No platform entry → the shared body is the implementation.
+            return null;
         case 'partial':
             // Keep as-is — bundler resolves `@gjsify/<X>` to its `lib/esm/index.js`.
+            // `partial` does NOT route to a platform entry even when one exists;
+            // see the header note (parity is the promotion gate to `polyfill`).
             return null;
         case 'native':
             if (rec.hasGlobals) {

package/package.json

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