@gjsify/resolve-npm 0.22.0 → 0.24.1

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,87 @@ 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)
+ *
+ * A curated table maps a bare specifier (`os`, `node:os`) to `@gjsify/<X>`,
+ * while the derived per-runtimes-triplet map (`getDerivedAliasesSync`) maps
+ * `@gjsify/os` → `@gjsify/os/browser`. Applying the second to the values of
+ * the first is what makes ADR 0014's platform-entry routing reach a browser
+ * bundle at all: those bundles hit the packages through the bare/`node:` form,
+ * not by package name. (A direct `import … from '@gjsify/os'` routes on its own
+ * — it is a plain key hit in the merged map.)
+ *
+ * ## Why HERE and not as a second pass in `aliasPlugin`
+ *
+ * This looks like it wants to be a resolver chain — `os` → `@gjsify/os` →
+ * `@gjsify/os/browser` — but it must not be one. Slot routing may only be
+ * applied to values that CAME FROM a curated/derived table, and by the time
+ * `aliasPlugin` sees the map it has been merged flat across four tiers
+ * (derived → curated `ALIASES_*` → per-target overrides → user `--alias`,
+ * later wins — see `app/*.ts`). Tier information is gone, so a chain there
+ * would re-route USER aliases too:
+ *
+ *   - `scripts/node-gi-consumer-harness.mjs` builds `--alias node:<x>=@gjsify/<x>`
+ *     to put the POLYFILL under test behind a Node builtin. 34 of those
+ *     polyfills declare `runtimes.node: "native"`, so a second hop hands back
+ *     `@gjsify/<x>/globals` — Node's own builtin — and the suite measures
+ *     nothing while reporting green.
+ *   - Value-level chaining also has no notion of the documented KEY-level
+ *     "curated wins over derived" precedence. Measured on the composed maps:
+ *     `gjs` 0 of 114 entries would change, `node` 0 of 148 — and on
+ *     `nativescript` the only 4 changes are regressions (`fs` →
+ *     `@gjsify/native-fs-bridge` → `@gjsify/empty`, because a bridge package
+ *     that IS the native implementation declares `nativescript: "native"`,
+ *     which routes to a `globals.mjs` it does not ship).
+ *
+ * So composition happens at materialisation, where the tiers are still
+ * distinguishable, the curated table stays a pure bare-name → package
+ * statement (no slot policy duplicated into it), and `aliasPlugin` keeps its
+ * one-hop `skipSelf: true` contract. Composing a table is therefore an
+ * explicit, per-table decision; `ALIASES_NODE_FOR_NATIVESCRIPT` is
+ * deliberately NOT composed (see the STATUS.md TODO on the `native` slot's
+ * double meaning for the bridge packages).
+ *
+ * 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',
@@ -187,45 +268,93 @@ export const ALIASES_NODE_FOR_GJS = {
  * the routing in a second pass (`@gjsify/<X>` → `@gjsify/<X>/globals` or
  * `@gjsify/empty` depending on the slot declaration).
  *
- * `none`-slot entries are deliberately hardcoded to `@gjsify/empty` here
- * (e.g. `child_process`, `fs`, `net`, ...) rather than relying on the dynamic
- * runtime layer — bare `fs` / `net` / ... do NOT start with `@gjsify/` and
- * therefore never enter `getDerivedAliasesSync`. This table is the bridge.
+ * `none`-slot entries are deliberately hardcoded here rather than relying on the
+ * dynamic runtime layer — bare `fs` / `net` / ... do NOT start with `@gjsify/`
+ * and therefore never enter `getDerivedAliasesSync`. This table is the bridge.
+ *
+ * ## `@gjsify/empty` is a LAST resort, and every remaining one is classified
+ *
+ * A value of `@gjsify/empty` is an ANONYMOUS redirect: a shared
+ * `export default {}` that a dozen unrelated specifiers also resolve to. That
+ * makes it indistinguishable, in an emitted bundle, from an ACCIDENTAL alias —
+ * which is how `@gjsify/canvas2d`'s build could start emitting a stray
+ * `@gjsify/empty` import without anything noticing. It is also export-less, so
+ * `import { spawn } from 'child_process'` binds `undefined` and dies later at
+ * `spawn is not a function`, naming neither the module nor the platform.
  *
- * NOTE — UNWIRED IN THIS PR. The browser-app orchestrator
- * (`packages/infra/rolldown-plugin-gjsify/src/app/browser.ts`) does NOT
- * consume this map yet. PR-D (T-Plan Sektion 2b-ii + 2b-iii, Welle 3) flips
- * `browser.ts` to spread `ALIASES_NODE_FOR_BROWSER` (+ generated `node:*`
- * prefix-map) into its `aliasMap` UNDER `browserPolyfillAliases` and the user
- * aliases. Decoupled here so the table is exportable / reviewable in
- * isolation, while consumer wiring waits on the R1 wave delivering browser-
- * baubable `@gjsify/{process,buffer,stream,...}` builds. Adopt only when the
- * per-package browser slots are R1-validated.
+ * So a redirect is NAMED wherever a name exists, and each entry still pointing
+ * at `@gjsify/empty` carries an inline classification so the remaining work is
+ * visible rather than implied:
+ *
+ *   (A)  wireable now — the package declares a browser slot and ships the entry;
+ *        the value names that entry. No `(A)` entries remain except
+ *        `dns/promises`, which needs a `./browser/promises` subpath first.
+ *   (A') native-available — the browser HAS the API (`fetch`, `WebSocket`); the
+ *        honest target is a `/globals` re-export, not an empty module.
+ *   (B)  simulatable but unbuilt — a real Web analogue exists (`cluster` over
+ *        Web Workers, `dgram` over WebRTC data channels, `v8.serialize` over
+ *        `structuredClone`, `readline` over any stream). `@gjsify/empty` until
+ *        someone builds it.
+ *   (C)  impossible — no Web API can ever back it. These get a NAMED throwing
+ *        stub at `@gjsify/<X>/browser` (today: `child_process`, `net`, `tls`).
+ *        `http2` / `inspector` are also `(C)` but not yet written; `repl` /
+ *        `wasi` are `(C)` with no owning `@gjsify/*` package to host a stub.
+ *
+ * A `(C)` stub keeps its package's `runtimes.browser: "none"` declaration: the
+ * MODULE genuinely is not usable on the runtime. The stub does not make it
+ * usable, it makes the unusability legible — it exports the module's real named
+ * shape (so linking succeeds) and throws a structured `ENOTSUP` naming the
+ * module, the runtime and the calling site. Exports whose answer IS
+ * platform-independent (`net.isIP`, `tls.checkServerIdentity`) stay real; a
+ * blanket thrower would replace one lie with another.
+ *
+ * A `partial`-slot package names its `./browser` PLATFORM ENTRY here, not its
+ * package root. `withDerivedSlotRouting` only rewrites a value when the slot is
+ * `polyfill` (ADR 0014), so a curated value of `@gjsify/<X>` for a `partial`
+ * package would hand the bundler the GJS root body — whose `@girs/*` imports
+ * `gjsImportsEmptyPlugin` replaces with `{}`, producing the silent
+ * `GLib.Checksum is not a constructor` failure ADR 0014 exists to eliminate.
+ * `partial` must mean "degrades at call time", never "crashes at first use".
+ * Naming the subpath is safe precisely where the platform entry is already at
+ * VALUE-export parity with the root (else routing would trade a call-time
+ * degradation for a build-time MISSING_EXPORT) — which is why this is a
+ * per-package curated decision and NOT a blanket change to `resolveSlot`'s
+ * `partial` case. Machine-checked by `scripts/audit-runtimes.mjs`'
+ * `curated-alias-routing` invariant.
+ *
+ * WIRED. The browser-app orchestrator
+ * (`packages/infra/rolldown-plugin-gjsify/src/app/browser.ts`) spreads this map
+ * — plus a generated `node:*` prefix variant of every key — into its `aliasMap`
+ * between the derived slot routing and the per-target / user aliases. So every
+ * value here is a resolve target a `--app browser` build actually takes; a
+ * mistake in this table is a shipping bug, not a staged proposal. (The former
+ * "UNWIRED IN THIS PR" note dated from before that wiring landed and is what
+ * made the `crypto` / `zlib` root-body routing read as latent.)
  */
-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',
     'buffer':              '@gjsify/buffer',
-    'child_process':       '@gjsify/empty',        // none-slot — browser has no process model
-    'cluster':             '@gjsify/empty',
+    'child_process':       '@gjsify/child_process/browser', // none slot — NAMED throwing stub
+    'cluster':             '@gjsify/empty',        // (B) simulatable over Web Workers — unbuilt
     'console':             '@gjsify/console',
     'constants':           '@gjsify/constants',
-    'crypto':              '@gjsify/crypto',
-    'dgram':               '@gjsify/empty',
+    'crypto':              '@gjsify/crypto/browser',   // partial slot — name the platform entry
+    'dgram':               '@gjsify/empty',        // (B) simulatable over WebRTC data channels — unbuilt
     'diagnostics_channel': '@gjsify/diagnostics_channel',
-    'dns':                 '@gjsify/empty',
-    'dns/promises':        '@gjsify/empty',
+    'dns':                 '@gjsify/dns/browser',      // partial slot — name the platform entry
+    'dns/promises':        '@gjsify/empty',        // (A) blocked: no ./browser/promises subpath yet
     'domain':              '@gjsify/domain',
     'events':              '@gjsify/events',
-    'fs':                  '@gjsify/empty',        // phase 1: stub; later @gjsify/fs/browser
-    'fs/promises':         '@gjsify/empty',
-    'http':                '@gjsify/empty',        // browser fetch covers most cases
-    'http2':               '@gjsify/empty',
-    'https':               '@gjsify/empty',
-    'inspector':           '@gjsify/empty',
-    'module':              '@gjsify/empty',
-    'net':                 '@gjsify/empty',
+    'fs':                  '@gjsify/fs/browser',       // partial slot — name the platform entry
+    'fs/promises':         '@gjsify/fs/browser/promises',
+    'http':                '@gjsify/http/browser',     // partial slot — name the platform entry
+    'http2':               '@gjsify/empty',        // (C) impossible — needs a named throwing stub
+    'https':               '@gjsify/https/browser',    // partial slot — name the platform entry
+    'inspector':           '@gjsify/empty',        // (C) impossible — needs a named throwing stub
+    'module':              '@gjsify/module/browser',   // partial slot — name the platform entry
+    'net':                 '@gjsify/net/browser',      // none slot — NAMED throwing stub
     'os':                  '@gjsify/os',
     'path':                '@gjsify/path',
     'path/posix':          '@gjsify/path/posix',
@@ -234,9 +363,9 @@ export const ALIASES_NODE_FOR_BROWSER = {
     'process':             '@gjsify/process',      // PR-D: flips today's `@gjsify/empty`
     'punycode':            '@gjsify/punycode',
     'querystring':         '@gjsify/querystring',
-    'readline':            '@gjsify/empty',
-    'readline/promises':   '@gjsify/empty',
-    'repl':                '@gjsify/empty',
+    'readline':            '@gjsify/empty',        // (B) stream-generic; simulatable — unbuilt
+    'readline/promises':   '@gjsify/empty',        // (B) stream-generic; simulatable — unbuilt
+    'repl':                '@gjsify/empty',        // (C) impossible, and no @gjsify/repl package exists
     'stream':              '@gjsify/stream',
     'stream/web':          '@gjsify/stream/web',
     'stream/consumers':    '@gjsify/stream/consumers',
@@ -245,24 +374,36 @@ export const ALIASES_NODE_FOR_BROWSER = {
     'sys':                 '@gjsify/sys',
     'timers':              '@gjsify/timers',
     'timers/promises':     '@gjsify/timers/promises',
-    'tls':                 '@gjsify/empty',
-    'tty':                 '@gjsify/empty',
+    'tls':                 '@gjsify/tls/browser',      // none slot — NAMED throwing stub
+    'tty':                 '@gjsify/empty',        // (B) isatty()===false is honest — unbuilt
     'url':                 '@gjsify/url',
     'util':                '@gjsify/util',
     'util/types':          '@gjsify/util/types',
-    'v8':                  '@gjsify/empty',
+    'v8':                  '@gjsify/empty',        // (B) serialize/deserialize over structuredClone — unbuilt
     'vm':                  '@gjsify/vm',
-    'wasi':                '@gjsify/empty',
-    'sqlite':              '@gjsify/empty',
-    'worker_threads':      '@gjsify/empty',
-    'zlib':                '@gjsify/zlib',
+    'wasi':                '@gjsify/empty',        // (C) impossible, and no @gjsify/wasi package exists
+    'sqlite':              '@gjsify/sqlite/browser',   // partial slot — name the platform entry
+    'worker_threads':      '@gjsify/worker_threads/browser', // partial slot — name the platform entry
+    'zlib':                '@gjsify/zlib/browser',     // partial slot — name the platform entry
 
     // Third-party
-    'node-fetch':          '@gjsify/empty',        // browser native fetch
-    'ws':                  '@gjsify/empty',        // browser native WebSocket
-    'isomorphic-ws':       '@gjsify/empty',
+    'node-fetch':          '@gjsify/empty',        // (A') native-available: wants @gjsify/fetch/globals
+    'ws':                  '@gjsify/ws/browser',       // partial slot — name the platform entry
+    'isomorphic-ws':       '@gjsify/empty',        // (A') native-available: wants a WebSocket re-export
 }
 
+/**
+ * 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
@@ -277,11 +418,18 @@ export const ALIASES_NODE_FOR_BROWSER = {
  * - **Mobile-tractable Node built-ins → `@gjsify/<X>`.** `assert`,
  *   `async_hooks`, `buffer`, `crypto`, `events`, `fs`, `os`, `path`,
  *   `process`, `stream`, `string_decoder`, `url`, `util`, `querystring`
- *   route to their gjsify polyfills. The polyfills themselves may declare
- *   `runtimes.nativescript = "polyfill" | "partial" | "none"`; the
- *   triplet-driven `getDerivedAliasesSync('nativescript')` second pass
- *   reads the declaration and either keeps the resolution as-is (polyfill /
- *   partial) or redirects to `/globals` (native) or `@gjsify/empty` (none).
+ *   route to their gjsify polyfills. NOTE: unlike `ALIASES_NODE_FOR_BROWSER`,
+ *   this table is deliberately NOT wrapped in `withDerivedSlotRouting` — the
+ *   VALUES here are taken as final. Composing it today would only change 4 of
+ *   122 entries and all four are regressions: `fs`/`fs/promises` point at
+ *   `@gjsify/native-fs-bridge`, which declares `nativescript: "native"` meaning
+ *   "this package IS the native implementation", while the slot vocabulary's
+ *   `native` means "the RUNTIME provides it, route to `<pkg>/globals`" — a file
+ *   the bridge does not ship, so the composed value degrades to
+ *   `@gjsify/empty`. Settle the bridge packages' slot declarations first (see
+ *   STATUS.md `Open TODOs`), then compose. An import by PACKAGE NAME does route
+ *   per the declared slot (plain key hit in the merged map) — which is why the
+ *   bridges are ALREADY emptied on that path today, same TODO.
  * - **`ws` / `isomorphic-ws` → `@gjsify/empty`.** NS apps use `WebSocket`
  *   from the global runtime, not the `ws` package.
  *
@@ -559,6 +707,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.22.0",
+    "version": "0.24.1",
     "description": "Resolve NPM package aliases",
     "type": "module",
     "main": "lib/index.mjs",