@gjsify/resolve-npm 0.4.35 → 0.4.37

package/lib/globals-map.mjs

@@ -215,3 +215,138 @@ export const GJS_GLOBALS_MAP = {
     location:             '@gjsify/dom-elements/register/location',
     navigator:            '@gjsify/dom-elements/register/navigator',
 };
+
+// ─── Browser target ────────────────────────────────────────────────────────
+//
+// `GJS_GLOBALS_MAP` is the GJS-target authority — every identifier needs a
+// `@gjsify/<X>/register` install path because GJS ships none of them natively.
+// The `--app browser` target inverts that: nearly every identifier in
+// `GJS_GLOBALS_GROUPS.web` and `.dom` is already on the browser's `globalThis`
+// (fetch, Headers, ReadableStream, Event, document, …). Only a handful of
+// Node-group identifiers (Buffer, process, setImmediate, clearImmediate)
+// need a polyfill register entry.
+//
+// The split below mirrors the T-Plan section 5b distinction:
+//   - `BROWSER_NATIVE_IDENTS` — identifier set that resolves to no-op
+//     register entries for `--app browser`. Used by both the audit-runtimes
+//     `BROWSER_NATIVE_RE_EXPORTS` probe (T-Plan 5b-i) and the future
+//     esbuild/rolldown `--globals` consumer to recognise that the identifier
+//     does NOT need an injected register module on the browser target.
+//   - `BROWSER_GLOBALS_MAP` — the strict subset of `GJS_GLOBALS_MAP` that
+//     still needs a polyfill register path on the browser target. Today only
+//     `Buffer` (`@gjsify/buffer/register`) and `process` (no `/register`
+//     subpath shipped yet — placeholder string mirrored from GJS map until
+//     `@gjsify/process` lands a browser-runnable register module).
+
+/**
+ * Identifiers that are natively present on a browser's `globalThis` and
+ * therefore need no `/register` injection when `--app browser` is targeting
+ * the bundle. Consumed by:
+ *
+ *   - `scripts/audit-runtimes.mjs` `BROWSER_NATIVE_RE_EXPORTS` probe
+ *     (T-Plan section 1b) to decide whether a `globals.mjs` re-export source
+ *     is recognisable as a browser-resolvable specifier.
+ *   - `@gjsify/cli` `--globals` flag indirection — future browser-target
+ *     consumer (T-Plan section 5b-iii `getGlobalsMapFor(target)`) maps these
+ *     to a no-op register entry instead of injecting a `/register` shim.
+ *
+ * Drawn from `GJS_GLOBALS_GROUPS.web` and `.dom` (every entry there is
+ * browser-native) plus a small set of shared identifiers from `.node`
+ * (`queueMicrotask`, `structuredClone`, `btoa`, `atob`, `URL`,
+ * `URLSearchParams`, and the unprefixed timer family).
+ */
+export const BROWSER_NATIVE_IDENTS = new Set([
+    // Web group — all browser-native
+    'fetch', 'Headers', 'Request', 'Response',
+    'FormData', 'Blob', 'File',
+    'ReadableStream', 'WritableStream', 'TransformStream',
+    'ReadableStreamBYOBReader', 'ReadableStreamBYOBRequest',
+    'ReadableByteStreamController', 'ReadableStreamDefaultController',
+    'ReadableStreamDefaultReader',
+    'TextEncoderStream', 'TextDecoderStream',
+    'ByteLengthQueuingStrategy', 'CountQueuingStrategy',
+    'CompressionStream', 'DecompressionStream',
+    'crypto',
+    'AbortController', 'AbortSignal',
+    'MessageChannel', 'MessagePort',
+    'Event', 'EventTarget', 'CustomEvent', 'MessageEvent',
+    'ErrorEvent', 'CloseEvent', 'ProgressEvent',
+    'UIEvent', 'MouseEvent', 'PointerEvent', 'KeyboardEvent',
+    'WheelEvent', 'FocusEvent',
+    'EventSource', 'WebSocket', 'WebAssembly',
+    'DOMException',
+    'performance', 'PerformanceObserver',
+    'XMLHttpRequest', 'XMLHttpRequestUpload',
+    'DOMParser',
+    'AudioContext', 'webkitAudioContext', 'Audio', 'HTMLAudioElement',
+    'GamepadEvent',
+    'MediaDevices',
+    'RTCPeerConnection', 'RTCSessionDescription', 'RTCIceCandidate',
+    'RTCPeerConnectionIceEvent', 'RTCDataChannel', 'RTCDataChannelEvent',
+    'RTCError', 'RTCErrorEvent',
+    'MediaStream', 'MediaStreamTrack', 'RTCTrackEvent',
+    // DOM group — all browser-native
+    'document', 'Image', 'HTMLCanvasElement', 'HTMLImageElement',
+    'HTMLElement', 'MutationObserver', 'ResizeObserver', 'IntersectionObserver',
+    'FontFace', 'matchMedia', 'location', 'navigator',
+    // Shared Node-group identifiers that are also browser-native
+    'queueMicrotask', 'structuredClone', 'btoa', 'atob',
+    'URL', 'URLSearchParams',
+    'setTimeout', 'setInterval', 'clearTimeout', 'clearInterval',
+]);
+
+/**
+ * Identifier → register-subpath map for the `--app browser` target. Strict
+ * subset of `GJS_GLOBALS_MAP`: only identifiers that do NOT exist natively
+ * on `globalThis` in a browser need a polyfill register injection.
+ *
+ * Today: `Buffer` (the sole Node-group identifier with a shipped
+ * `@gjsify/<X>/register` subpath that ALSO has a browser-runnable polyfill
+ * landed on `main`). `process`, `setImmediate`, and `clearImmediate` will
+ * join the map as `@gjsify/{process,timers}/register` granular subpaths
+ * land (browser polyfill wave 3-A onwards).
+ */
+export const BROWSER_GLOBALS_MAP = {
+    Buffer:          '@gjsify/buffer/register',
+};
+
+/**
+ * NativeScript globals map. NS' bundled V8 already provides every Web /
+ * Node-runtime global that `GJS_GLOBALS_MAP` covers — `fetch`, `URL`,
+ * `URLSearchParams`, `crypto` (incl. `crypto.getRandomValues`), `Promise`,
+ * `setTimeout` / `setInterval`, `console`, `TextEncoder` / `TextDecoder`,
+ * `atob` / `btoa`, `Blob`, `File`, `FormData`, `WebSocket`,
+ * `XMLHttpRequest`, `structuredClone`, etc. — so no register-subpath
+ * injection is needed for the default surface.
+ *
+ * `Buffer` is the one exception: NS does not ship `Buffer` as a global
+ * (it's a Node-specific concept). Apps that consume `node:buffer` get the
+ * polyfill via the alias layer; this map covers the bare `Buffer`
+ * free-identifier case (parallel to the BROWSER_GLOBALS_MAP entry).
+ *
+ * Per-pillar Welle-5 PRs will extend this map as packages declare
+ * `runtimes.nativescript = "polyfill"` and need a specific global stubbed.
+ */
+export const NATIVESCRIPT_GLOBALS_MAP = {
+    Buffer:          '@gjsify/buffer/register',
+};
+
+/**
+ * Helper for consumers (esbuild/rolldown plugins, future audit consumers)
+ * to fetch the right identifier → register-subpath map for a given build
+ * target. Centralises the per-target choice so a consumer with a `target`
+ * variable does not need to branch on the strings itself.
+ *
+ *   - `'gjs'`          → full `GJS_GLOBALS_MAP` (every identifier needs a register)
+ *   - `'node'`         → `{}` (every GJS-mapped identifier is Node-native)
+ *   - `'browser'`      → `BROWSER_GLOBALS_MAP` (subset that still needs a polyfill)
+ *   - `'nativescript'` → `NATIVESCRIPT_GLOBALS_MAP` (subset NS V8 doesn't ship)
+ *   - default          → `GJS_GLOBALS_MAP` (safer fallback for unknown targets)
+ */
+export function getGlobalsMapFor(target) {
+    if (target === 'gjs') return GJS_GLOBALS_MAP;
+    if (target === 'node') return {};
+    if (target === 'browser') return BROWSER_GLOBALS_MAP;
+    if (target === 'nativescript') return NATIVESCRIPT_GLOBALS_MAP;
+    return GJS_GLOBALS_MAP;
+}

package/lib/index.d.ts

@@ -8,7 +8,14 @@ export declare const EXTERNALS_NPM: string[];
 export declare const ALIASES_GENERAL_FOR_GJS: {[alias:string]: string}; 
 
 /** Record of Node.js modules (build in or not) and his replacement for Gjs */
-export declare const ALIASES_NODE_FOR_GJS: {[alias:string]: string}; 
+export declare const ALIASES_NODE_FOR_GJS: {[alias:string]: string};
+
+/**
+ * Record of Node.js modules (build in or not) and his replacement for `--app browser`.
+ * Unwired in this PR — exported for future consumption by browser.ts.
+ */
+export declare const ALIASES_NODE_FOR_BROWSER: {[alias:string]: string};
+export declare const ALIASES_NODE_FOR_NATIVESCRIPT: {[alias:string]: string};
 
 /** Record of Web modules and his replacement for Gjs */
 export declare const ALIASES_WEB_FOR_GJS: {[alias:string]: string}; 
@@ -46,11 +53,11 @@ export interface RuntimeTriplet {
  * by each workspace package's declared `gjsify.runtimes` triplet. See
  * `runtime-aliases.mjs` for the routing semantics.
  */
-export declare function getDerivedAliasesSync(target: 'gjs' | 'node' | 'browser'): {[alias: string]: string};
+export declare function getDerivedAliasesSync(target: 'gjs' | 'node' | 'browser' | 'nativescript'): {[alias: string]: string};
 
 /** Async variant of {@link getDerivedAliasesSync}. */
 export declare function getDerivedAliases(
-    target: 'gjs' | 'node' | 'browser',
+    target: 'gjs' | 'node' | 'browser' | 'nativescript',
 ): Promise<{[alias: string]: string}>;
 
 /** Reset the in-memory cache. Test-only. */

package/lib/index.mjs

@@ -179,6 +179,177 @@ export const ALIASES_NODE_FOR_GJS = {
     'isomorphic-ws': '@gjsify/websocket',
 }
 
+/**
+ * Record of Node.js modules (built-in or 3rd-party) and their `@gjsify/<X>`
+ * replacement for `--app browser` builds. Mirrors `ALIASES_NODE_FOR_GJS` in
+ * shape — bare bridge from the NPM-specifier namespace into `@gjsify/*` so the
+ * dynamic per-runtimes-triplet resolver (`getDerivedAliasesSync`) can finish
+ * 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.
+ *
+ * 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.
+ */
+export const ALIASES_NODE_FOR_BROWSER = {
+    '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',
+    'console':             '@gjsify/console',
+    'constants':           '@gjsify/constants',
+    'crypto':              '@gjsify/crypto',
+    'dgram':               '@gjsify/empty',
+    'diagnostics_channel': '@gjsify/diagnostics_channel',
+    'dns':                 '@gjsify/empty',
+    'dns/promises':        '@gjsify/empty',
+    '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',
+    'os':                  '@gjsify/os',
+    'path':                '@gjsify/path',
+    'path/posix':          '@gjsify/path/posix',
+    'path/win32':          '@gjsify/path/win32',
+    'perf_hooks':          '@gjsify/perf_hooks',
+    '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',
+    'stream':              '@gjsify/stream',
+    'stream/web':          '@gjsify/stream/web',
+    'stream/consumers':    '@gjsify/stream/consumers',
+    'stream/promises':     '@gjsify/stream/promises',
+    'string_decoder':      '@gjsify/string_decoder',
+    'sys':                 '@gjsify/sys',
+    'timers':              '@gjsify/timers',
+    'timers/promises':     '@gjsify/timers/promises',
+    'tls':                 '@gjsify/empty',
+    'tty':                 '@gjsify/empty',
+    'url':                 '@gjsify/url',
+    'util':                '@gjsify/util',
+    'util/types':          '@gjsify/util/types',
+    'v8':                  '@gjsify/empty',
+    'vm':                  '@gjsify/vm',
+    'wasi':                '@gjsify/empty',
+    'sqlite':              '@gjsify/empty',
+    'worker_threads':      '@gjsify/empty',
+    'zlib':                '@gjsify/zlib',
+
+    // Third-party
+    'node-fetch':          '@gjsify/empty',        // browser native fetch
+    'ws':                  '@gjsify/empty',        // browser native WebSocket
+    'isomorphic-ws':       '@gjsify/empty',
+}
+
+/**
+ * Bare Node-builtin specifier → polyfill / empty-stub mapping for `--app
+ * nativescript` builds. Mirrors `ALIASES_NODE_FOR_BROWSER` in shape, with
+ * different per-module decisions reflecting what makes sense on a mobile-V8
+ * runtime (NativeScript on iOS + Android):
+ *
+ * - **Server-only Node built-ins → `@gjsify/empty`.** There is no listening
+ *   socket / process model on a mobile-app runtime, so `child_process`,
+ *   `cluster`, `dgram`, `dns`, `inspector`, `net`, `tls`, `tty`, `http*`
+ *   resolve to an empty stub. NativeScript apps that need network I/O use
+ *   the runtime-native `fetch` / `XMLHttpRequest` / `WebSocket`.
+ * - **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).
+ * - **`ws` / `isomorphic-ws` → `@gjsify/empty`.** NS apps use `WebSocket`
+ *   from the global runtime, not the `ws` package.
+ *
+ * Entries here are PROVISIONAL — per-pillar Welle-5 PRs will refine them as
+ * each `@gjsify/<X>` package lands an explicit `nativescript` slot.
+ */
+export const ALIASES_NODE_FOR_NATIVESCRIPT = {
+    // Server-only Node built-ins → empty stub
+    'child_process':       '@gjsify/empty',
+    'cluster':             '@gjsify/empty',
+    'dgram':               '@gjsify/empty',
+    'dns':                 '@gjsify/empty',
+    'dns/promises':        '@gjsify/empty',
+    'inspector':           '@gjsify/empty',
+    'net':                 '@gjsify/empty',
+    'tls':                 '@gjsify/empty',
+    'tty':                 '@gjsify/empty',
+    'http':                '@gjsify/empty',
+    'https':               '@gjsify/empty',
+    'http2':               '@gjsify/empty',
+    'readline':            '@gjsify/empty',
+    'repl':                '@gjsify/empty',
+    'v8':                  '@gjsify/empty',
+    'vm':                  '@gjsify/empty',
+    'worker_threads':      '@gjsify/empty',
+    'perf_hooks':          '@gjsify/empty',
+    'diagnostics_channel': '@gjsify/empty',
+    'domain':              '@gjsify/empty',
+    'sqlite':              '@gjsify/empty',
+    'sys':                 '@gjsify/empty',
+    'zlib':                '@gjsify/empty',
+
+    // Mobile-tractable Node built-ins → @gjsify/<X>
+    'assert':              '@gjsify/assert',
+    'assert/strict':       '@gjsify/assert',
+    'async_hooks':         '@gjsify/async_hooks',
+    'buffer':              '@gjsify/buffer',
+    // `@gjsify/module` (not `@gjsify/empty`): provides the named exports
+    // `createRequire` / `builtinModules` / `isBuiltin`, so `import { createRequire }
+    // from 'module'` in deps (e.g. css-tree) resolves instead of failing the build.
+    'module':              '@gjsify/module',
+    'crypto':              '@gjsify/crypto',
+    'events':              '@gjsify/events',
+    'fs':                  '@gjsify/fs',
+    'fs/promises':         '@gjsify/fs/promises',
+    'os':                  '@gjsify/os',
+    'path':                '@gjsify/path',
+    'path/posix':          '@gjsify/path/posix',
+    'path/win32':          '@gjsify/path/win32',
+    'process':             '@gjsify/process',
+    'stream':              '@gjsify/stream',
+    'stream/promises':     '@gjsify/stream/promises',
+    'stream/web':          '@gjsify/stream/web',
+    'string_decoder':      '@gjsify/string_decoder',
+    'url':                 '@gjsify/url',
+    'util':                '@gjsify/util',
+    'util/types':          '@gjsify/util/types',
+    'querystring':         '@gjsify/querystring',
+    'console':             '@gjsify/console',
+    'timers':              '@gjsify/timers',
+    'timers/promises':     '@gjsify/timers/promises',
+
+    // Third-party
+    'node-fetch':          '@gjsify/empty',        // NS has native fetch
+    'ws':                  '@gjsify/empty',        // NS has its own WebSocket
+    'isomorphic-ws':       '@gjsify/empty',
+}
+
 /** Record of Web modules and his replacement for Gjs */
 export const ALIASES_WEB_FOR_GJS = {
     // Bare specifiers (named imports, pure — no side-effects after Stage 2)

package/lib/runtime-aliases.mjs

@@ -39,10 +39,17 @@ import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const VALID_SLOTS = new Set(['polyfill', 'native', 'partial', 'none']);
-const VALID_TARGETS = new Set(['gjs', 'node', 'browser']);
+const VALID_TARGETS = new Set(['gjs', 'node', 'browser', 'nativescript']);
 
 /** @typedef {'polyfill'|'native'|'partial'|'none'} Slot */
-/** @typedef {{gjs?:Slot, node?:Slot, browser?:Slot}} RuntimeTriplet */
+/**
+ * Per-package runtime slot declaration. Quadruplet (gjs / node / browser /
+ * nativescript). The legacy "triplet" name is kept on the typedef for
+ * minimal churn while NativeScript is being landed; the type is canonically
+ * a quadruplet from VALID_TARGETS' perspective.
+ *
+ * @typedef {{gjs?:Slot, node?:Slot, browser?:Slot, nativescript?:Slot}} RuntimeTriplet
+ */
 /** @typedef {{name:string, dir:string, runtimes:RuntimeTriplet, hasGlobals:boolean}} PackageRecord */
 
 let _cache = null;
@@ -313,7 +320,7 @@ function warnOnce(key, message) {
  * Given a package record + target runtime, resolve the alias target.
  *
  * @param {PackageRecord} rec
- * @param {'gjs'|'node'|'browser'} target
+ * @param {'gjs'|'node'|'browser'|'nativescript'} target
  * @returns {string|null} The alias target specifier, or null if no rewrite applies.
  */
 function resolveSlot(rec, target) {
@@ -365,7 +372,7 @@ function resolveSlot(rec, target) {
  * (callers should `{ ...derived, ...hardcoded }` to preserve current behavior
  * for packages opted out of the triplet model).
  *
- * @param {'gjs'|'node'|'browser'} target
+ * @param {'gjs'|'node'|'browser'|'nativescript'} target
  * @returns {Record<string,string>}
  */
 export function getDerivedAliasesSync(target) {
@@ -386,7 +393,7 @@ export function getDerivedAliasesSync(target) {
  * Async variant of {@link getDerivedAliasesSync} — preferred when callable from
  * an async config hook.
  *
- * @param {'gjs'|'node'|'browser'} target
+ * @param {'gjs'|'node'|'browser'|'nativescript'} target
  * @returns {Promise<Record<string,string>>}
  */
 export async function getDerivedAliases(target) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/resolve-npm",
-    "version": "0.4.35",
+    "version": "0.4.37",
     "description": "Resolve NPM package aliases",
     "type": "module",
     "main": "lib/index.mjs",
@@ -29,5 +29,15 @@
         "node",
         "npm",
         "alias"
-    ]
+    ],
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/infra/resolve-npm"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/infra/resolve-npm#readme"
 }