@nubjs/nub-darwin-x64 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubjs/nub-darwin-x64",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Nub binary for darwin-x64",
   "license": "MIT",
   "repository": "https://github.com/nubjs/nub",

package/runtime/navigator-locks.mjs

@@ -1,10 +1,21 @@
-// Web Locks API polyfill for Node 22.x (native on Node 24.5+).
-// Single-process only — locks don't coordinate across workers.
+// Web Locks API polyfill for Node < 24.5 (native on Node 24.5+, #58666).
+// Single-process only — locks don't coordinate across worker threads (a deliberate
+// scope: the common in-process serialization use is covered; cross-thread coordination
+// would need a SharedArrayBuffer waitlist and is out of scope until there's demand).
+//
+// Spec: https://w3c.github.io/web-locks/. Modeled to match Node's own
+// internal/locks.js (the native impl on 24.5+) so behavior is identical across the
+// version boundary — including `steal`, AbortSignal integration, and the option/name
+// validation that the WPT web-locks suite exercises. Requires a `navigator` object to
+// host `navigator.locks`; navigator-shim.mjs backfills that on Node < 21 and MUST run
+// first.
 
 if (typeof globalThis.navigator === "object" && typeof globalThis.navigator.locks === "undefined") {
-  // Track held locks: name → { mode, count } where count > 1 means shared holders
-  const held = new Map();
-  const queue = new Map();
+  const AbortSig = globalThis.AbortSignal;
+
+  const abortError = (msg) => new DOMException(msg || "The operation was aborted", "AbortError");
+  const stolenError = () => abortError("The lock was stolen by another request");
+  const notSupported = (msg) => new DOMException(msg, "NotSupportedError");
 
   class Lock {
     #name;
@@ -17,113 +28,209 @@ if (typeof globalThis.navigator === "object" && typeof globalThis.navigator.lock
     get mode() { return this.#mode; }
   }
 
+  // held: name → { mode, holders:Set<Holder> }. A shared grant has N holders sharing
+  // one record; an exclusive grant has exactly one. queue: name → Array<Waiter> (FIFO).
+  const held = new Map();
+  const queue = new Map();
+
   function canAcquire(name, mode) {
-    const current = held.get(name);
-    if (!current) return true;
-    if (mode === "shared" && current.mode === "shared") return true;
-    return false;
+    const rec = held.get(name);
+    if (!rec) return true;
+    return mode === "shared" && rec.mode === "shared";
   }
 
-  function acquire(name, mode) {
-    const current = held.get(name);
-    if (current && mode === "shared" && current.mode === "shared") {
-      current.count++;
-    } else {
-      held.set(name, { mode, count: 1 });
-    }
+  // A FRESH request may be granted immediately only when no waiters are already
+  // queued for the name — otherwise it must queue behind them. This is the
+  // reader/writer FAIRNESS rule: a new shared request must NOT barge ahead of a
+  // pending exclusive request and join the current shared holders, which would
+  // starve the writer (WPT mode-mixed "An exclusive lock between shared locks").
+  // drainQueue, which only ever grants from the FRONT of the queue, keeps using
+  // canAcquire directly.
+  function canGrantNow(name, mode) {
+    const q = queue.get(name);
+    if (q && q.length > 0) return false;
+    return canAcquire(name, mode);
   }
 
-  function release(name) {
-    const current = held.get(name);
-    if (!current) return;
-    current.count--;
-    if (current.count <= 0) {
-      held.delete(name);
-      drainQueue(name);
-    }
+  function addHolder(name, mode, holder) {
+    const rec = held.get(name);
+    if (rec) rec.holders.add(holder);
+    else held.set(name, { mode, holders: new Set([holder]) });
+  }
+
+  function removeHolder(name, holder) {
+    const rec = held.get(name);
+    if (!rec) return;
+    rec.holders.delete(holder);
+    if (rec.holders.size === 0) held.delete(name);
   }
 
+  function enqueue(name, waiter) {
+    let q = queue.get(name);
+    if (!q) queue.set(name, (q = []));
+    q.push(waiter);
+  }
+
+  // Grant as many head-of-queue waiters as the current held state allows: a head
+  // exclusive takes the lock alone; a run of head shared waiters is all granted.
   function drainQueue(name) {
     const q = queue.get(name);
     if (!q || q.length === 0) return;
+    while (q.length > 0) {
+      const first = q[0];
+      if (!canAcquire(name, first.mode)) break;
+      q.shift();
+      first.grant(); // synchronously addHolders, so canAcquire reflects it next iter
+      if (first.mode === "exclusive") break;
+    }
+    if (q.length === 0) queue.delete(name);
+  }
 
-    // Try to grant as many queued requests as possible.
-    // If the first queued is shared, grant all consecutive shared requests.
-    // If the first queued is exclusive, grant only that one.
-    const first = q[0];
-    if (canAcquire(name, first.mode)) {
-      if (first.mode === "exclusive") {
-        q.shift();
-        first.resolve();
-      } else {
-        // Grant all consecutive shared requests.
-        while (q.length > 0 && q[0].mode === "shared") {
-          const req = q.shift();
-          req.resolve();
-        }
-      }
+  // Run `cb(lock)` as a holder of (name, mode); return the promise that settles when
+  // the holder releases (cb's result/throw) — or rejects early if a steal BREAKS it.
+  // The callback is invoked one microtask later (matching Node), so a synchronously
+  // signaled abort is observed before the callback runs.
+  function runHolder(name, mode, cb) {
+    const lock = new Lock(name, mode);
+    let broken = false;
+    let rejectReleased;
+    const holder = {
+      mode,
+      break(reason) {
+        if (broken) return;
+        broken = true;
+        // Remove WITHOUT draining — the stealer takes the lock next; queued waiters
+        // stay pending until the steal's own holder releases.
+        removeHolder(name, holder);
+        rejectReleased(reason);
+      },
+    };
+    addHolder(name, mode, holder);
+    return new Promise((resolve, reject) => {
+      rejectReleased = reject;
+      Promise.resolve()
+        .then(() => cb(lock))
+        .then(
+          (value) => { if (!broken) { removeHolder(name, holder); resolve(value); drainQueue(name); } },
+          (err) => { if (!broken) { removeHolder(name, holder); reject(err); drainQueue(name); } },
+        );
+    });
+  }
+
+  // The lock engine: returns the `released` promise. `cb` receives the granted Lock
+  // (or null on an ifAvailable miss). Mirrors the grant/steal/ifAvailable/queue shape
+  // of Node's internalBinding('locks').request.
+  function engineRequest(name, mode, steal, ifAvailable, cb) {
+    if (steal) {
+      const rec = held.get(name);
+      if (rec) for (const h of [...rec.holders]) h.break(stolenError());
+      return runHolder(name, "exclusive", cb);
+    }
+    if (canGrantNow(name, mode)) {
+      return runHolder(name, mode, cb);
     }
+    if (ifAvailable) {
+      return Promise.resolve().then(() => cb(null));
+    }
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        mode,
+        settled: false,
+        grant() {
+          if (waiter.settled) return;
+          waiter.settled = true;
+          runHolder(name, mode, cb).then(resolve, reject);
+        },
+      };
+      enqueue(name, waiter);
+    });
   }
 
   class LockManager {
-    async request(name, optionsOrCallback, callback) {
-      let options = {};
-      if (typeof optionsOrCallback === "function") {
-        callback = optionsOrCallback;
-      } else {
-        options = optionsOrCallback || {};
+    async request(name, optionsOrCallback, maybeCallback) {
+      let options = optionsOrCallback;
+      let callback = maybeCallback;
+      if (callback === undefined) {
+        callback = options;
+        options = undefined;
+      }
+
+      // WebIDL DOMString coercion (throws TypeError on a Symbol, like the binding).
+      name = `${name}`;
+      if (typeof callback !== "function") {
+        throw new TypeError("Failed to execute 'request' on 'LockManager': parameter 2 is not a function.");
       }
+      if (options === undefined || typeof options === "function") options = {};
 
-      const mode = options.mode || "exclusive";
-      const ifAvailable = options.ifAvailable || false;
+      const mode = options.mode === undefined ? "exclusive" : options.mode;
+      if (mode !== "exclusive" && mode !== "shared") {
+        throw new TypeError(`Failed to execute 'request' on 'LockManager': '${mode}' is not a valid value for enumeration LockMode.`);
+      }
+      const ifAvailable = !!options.ifAvailable;
+      const steal = !!options.steal;
       const signal = options.signal;
+      if (signal !== undefined && signal !== null && !(AbortSig && signal instanceof AbortSig)) {
+        throw new TypeError("Failed to execute 'request' on 'LockManager': member signal is not of type AbortSignal.");
+      }
 
-      if (signal?.aborted) {
-        throw signal.reason || new DOMException("Lock request aborted", "AbortError");
+      // Already-aborted signal rejects with its reason BEFORE the option-combo checks
+      // (matching Node's signal.throwIfAborted() ordering).
+      if (signal && signal.aborted) {
+        throw signal.reason || abortError();
+      }
+      if (name[0] === "-") {
+        throw notSupported("Lock name may not start with hyphen '-'");
+      }
+      if (ifAvailable && steal) {
+        throw notSupported("ifAvailable and steal options cannot be used together");
+      }
+      if (mode !== "exclusive" && steal) {
+        throw notSupported("mode must be 'exclusive' when using the steal option");
+      }
+      if (signal && (steal || ifAvailable)) {
+        throw notSupported("signal cannot be used with the steal or ifAvailable options");
       }
 
-      if (!canAcquire(name, mode)) {
-        if (ifAvailable) {
-          return callback(null);
-        }
-        await new Promise((resolve, reject) => {
-          if (!queue.has(name)) queue.set(name, []);
-          queue.get(name).push({ resolve, reject, mode });
-          if (signal) {
-            signal.addEventListener("abort", () => {
-              const q = queue.get(name) || [];
-              const idx = q.findIndex((e) => e.resolve === resolve);
-              if (idx !== -1) q.splice(idx, 1);
-              reject(signal.reason || new DOMException("Lock request aborted", "AbortError"));
-            }, { once: true });
-          }
+      // Signal path: the callback is deferred and skipped if the signal aborts before
+      // it runs; the abort rejects the OUTER promise iff the callback hasn't entered
+      // (lockGranted false). Verbatim shape of Node's internal/locks.js so a queued
+      // abort releases the slot (callback skipped) and the next waiter is granted.
+      if (signal) {
+        return new Promise((resolve, reject) => {
+          let lockGranted = false;
+          const onAbort = () => {
+            if (!lockGranted) reject(signal.reason || abortError());
+          };
+          signal.addEventListener("abort", onAbort, { once: true });
+          const wrapped = (lock) =>
+            Promise.resolve().then(() => {
+              if (signal.aborted) return undefined;
+              lockGranted = true;
+              return callback(lock);
+            });
+          const released = engineRequest(name, mode, false, false, wrapped);
+          released.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
         });
       }
 
-      acquire(name, mode);
-      const lock = new Lock(name, mode);
-
-      try {
-        return await callback(lock);
-      } finally {
-        release(name);
-      }
+      return engineRequest(name, mode, steal, ifAvailable, (lock) => callback(lock));
     }
 
     async query() {
-      const heldLocks = [];
-      for (const [name, info] of held) {
-        for (let i = 0; i < info.count; i++) {
-          heldLocks.push({ name, mode: info.mode, clientId: "" });
-        }
+      // clientId is per-realm and opaque: `node-<pid>-0` (single-process; this polyfill
+      // does not coordinate across worker threads, so the threadId slot is always 0 —
+      // and we avoid importing node:worker_threads to keep this module builtin-free for a
+      // cheap bootstrap). The cross-context distinct-id WPT cases are browser-specific.
+      const clientId = `node-${process.pid}-0`;
+      const heldOut = [];
+      for (const [name, rec] of held) {
+        for (let i = 0; i < rec.holders.size; i++) heldOut.push({ name, mode: rec.mode, clientId });
       }
       const pending = [];
       for (const [name, q] of queue) {
-        for (const req of q) {
-          pending.push({ name, mode: req.mode, clientId: "" });
-        }
+        for (const w of q) if (!w.settled) pending.push({ name, mode: w.mode, clientId });
       }
-      return { held: heldLocks, pending };
+      return { held: heldOut, pending };
     }
   }
 

package/runtime/navigator-shim.mjs

@@ -0,0 +1,144 @@
+// `navigator` global backfill for Node < 21 (where the global is wholly absent).
+//
+// Node ships `globalThis.navigator` from 21.0.0. Below that it is `undefined`, so
+// any web-platform API hosted ON navigator — chiefly `navigator.locks` (Web Locks,
+// see navigator-locks.mjs) — has no object to attach to and silently does nothing.
+// nub's floor is 18.19, so to make those APIs reach the floor we synthesize the
+// `navigator` object Node 21+ would provide. Companion to navigator-locks.mjs:
+// this MUST run BEFORE it so locks has a host on 18.19–20.x.
+//
+// Shape mirrors Node's internal/navigator.js: a `Navigator` instance with the
+// enumerable prototype getters `hardwareConcurrency`, `language`, `languages`,
+// `userAgent`, `platform` (locks is added separately by navigator-locks.mjs). The
+// userAgent is `Node.js/<major>` — NEVER `Nub/…`: the user is running Node, nub is
+// the augmenter, and a `Nub/` UA would be a brand-boundary leak.
+//
+// VERSION-GATE, not a global read: installNavigatorShim() returns early on Node >= 21
+// from `process.versions.node` WITHOUT ever touching `globalThis.navigator`. That
+// matters because on Node 24.5+ the native `navigator` is a lazy getter whose first
+// access realizes ~30 internal/stream/worker-io builtins — a cold-start regression
+// (test-bootstrap-modules). The shim must never trigger that; the version check makes
+// the fast tier (>= 22.15, navigator always present) a free no-op.
+//
+// node: builtins (node:os) are fetched via `process.getBuiltinModule` when present,
+// else via a createRequire THREADED IN through `setBootstrapCreateRequire` — the same
+// brand-safe, off-the-user-loader-chain pattern worker-polyfill.mjs uses. The narrow
+// floor (18.19.x, 20.11–20.15) lacks `process.getBuiltinModule`, and the shim only
+// touches os lazily (the `hardwareConcurrency` getter), so the threaded require is
+// needed exactly there. `os` is never loaded on Node >= 21 (the early return).
+
+let _bootstrapCreateRequire = null;
+export function setBootstrapCreateRequire(fn) {
+  _bootstrapCreateRequire = fn;
+}
+
+function __getBuiltin(id) {
+  if (typeof process.getBuiltinModule === "function") return process.getBuiltinModule(id);
+  if (_bootstrapCreateRequire) return _bootstrapCreateRequire(import.meta.url)(id);
+  // Last-resort: a bare specifier require off this module's own createRequire is
+  // unavailable in ESM without node:module, which is exactly what the threading
+  // avoids importing statically. If neither path is wired, surface a clear error.
+  throw new Error("navigator-shim: no builtin accessor for " + id);
+}
+
+function deriveLanguage() {
+  // Approximate Node's ICU default locale from the POSIX locale env, falling back
+  // to "en-US" (Node's own fallback). `en_US.UTF-8` → `en-US`.
+  const raw =
+    process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || "";
+  const base = raw.split(".")[0].split("@")[0].replace("_", "-");
+  return base && base !== "C" && base !== "POSIX" ? base : "en-US";
+}
+
+function navigatorPlatform(platform, arch) {
+  // Mirror node/lib/internal/navigator.js getNavigatorPlatform.
+  if (platform === "darwin") return "MacIntel";
+  if (platform === "win32") return "Win32";
+  if (platform === "linux") {
+    if (arch === "ia32") return "Linux i686";
+    if (arch === "x64") return "Linux x86_64";
+    return `Linux ${arch}`;
+  }
+  if (platform === "freebsd") return arch === "ia32" ? "FreeBSD i386" : arch === "x64" ? "FreeBSD amd64" : `FreeBSD ${arch}`;
+  if (platform === "openbsd") return arch === "ia32" ? "OpenBSD i386" : arch === "x64" ? "OpenBSD amd64" : `OpenBSD ${arch}`;
+  if (platform === "sunos") return arch === "ia32" ? "SunOS i86pc" : `SunOS ${arch}`;
+  if (platform === "aix") return "AIX";
+  return `${platform[0].toUpperCase()}${platform.slice(1)} ${arch}`;
+}
+
+// Build the Navigator class lazily (only when actually backfilling) so loading this
+// module on the fast tier costs nothing beyond the early-return check.
+function makeNavigator() {
+  let _hw, _lang, _langs, _ua, _plat;
+  class Navigator {
+    get hardwareConcurrency() {
+      // os.availableParallelism honors cgroup CPU limits (Node 18.14+/19.4+; present
+      // on the 18.19 floor); fall back to cpus().length on the off chance it's absent.
+      if (_hw === undefined) {
+        const os = __getBuiltin("node:os");
+        _hw = typeof os.availableParallelism === "function" ? os.availableParallelism() : os.cpus().length;
+      }
+      return _hw;
+    }
+    get language() {
+      return (_lang ??= deriveLanguage());
+    }
+    get languages() {
+      return (_langs ??= Object.freeze([this.language]));
+    }
+    get userAgent() {
+      // `Node.js/<major>` — match Node exactly; never a nub-branded UA.
+      return (_ua ??= `Node.js/${process.versions.node.split(".")[0]}`);
+    }
+    get platform() {
+      return (_plat ??= navigatorPlatform(process.platform, process.arch));
+    }
+  }
+  // Match Node's instance shape: the property getters live on the prototype and are
+  // ENUMERABLE (Node sets them with kEnumerableProperty), so `for (const k in
+  // navigator)` walks them while `Object.keys(navigator)` (own enumerable) is empty.
+  // Class-body getters default to enumerable:false, so flip them in place.
+  for (const k of ["hardwareConcurrency", "language", "languages", "userAgent", "platform"]) {
+    Object.defineProperty(Navigator.prototype, k, { enumerable: true });
+  }
+  return { Navigator, instance: new Navigator() };
+}
+
+// Install the navigator backfill if and only if the running Node lacks the global
+// (i.e. Node < 21). Idempotent and side-effect-free on Node >= 21.
+export function installNavigatorShim() {
+  const major = parseInt(process.versions.node.split(".")[0], 10);
+  // Node 21+ ships navigator natively — never read the (possibly lazy) global here.
+  if (major >= 21) return;
+  // Defensive idempotency for the < 21 path (navigator is genuinely undefined there,
+  // so this read can't trigger a lazy realization).
+  if (typeof globalThis.navigator !== "undefined") return;
+
+  const { Navigator, instance } = makeNavigator();
+
+  // The binding on globalThis is NON-ENUMERABLE (invisible to Object.keys(globalThis)
+  // / for-in) — nub's additive-global contract, matching how reportError and Worker
+  // are installed. Configurable + writable so user code may still override it.
+  Object.defineProperty(globalThis, "navigator", {
+    value: instance,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+  // Node also exposes the `Navigator` constructor globally; mirror it (non-enumerable).
+  if (typeof globalThis.Navigator === "undefined") {
+    Object.defineProperty(globalThis, "Navigator", {
+      value: Navigator,
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  }
+}
+
+// Fast tier / modern compat (getBuiltinModule present, Node >= 20.16): install eagerly
+// at module eval — a guaranteed no-op above Node 21 thanks to the version gate, and
+// correct on a 20.16–20.x compat run where navigator is still absent. On the narrow
+// floor below getBuiltinModule the compat entry calls setBootstrapCreateRequire(...)
+// + installNavigatorShim() explicitly (mirroring worker-polyfill's wiring).
+if (typeof process.getBuiltinModule === "function") installNavigatorShim();

package/runtime/polyfills.cjs

@@ -84,6 +84,74 @@ function installSyncPolyfills(preloaded) {
     });
   }
 
+  // ── File (global on Node 20+, missing on the 18.x compat floor) ─────
+  // Node exposes the WHATWG `File` as a global from Node 20; on 18.13–18.x it
+  // exists only as `node:buffer`'s `File` export. Backfill the global from there
+  // so worker/messaging code that constructs `new File(...)` works down to the
+  // floor (polyfill-all-the-way-down). Identity is preserved (same constructor as
+  // `node:buffer`), so `instanceof` and undici's webidl brand checks hold. Blob is
+  // already global on 18.x, but the same backfill guards it for completeness.
+  // Non-enumerable to match Node's own global descriptors (the additive contract:
+  // invisible to global enumeration).
+  //
+  // Node 18 emits a one-time `ExperimentalWarning: buffer.File …` on the FIRST
+  // `new File(...)` (the constructor, NOT the property read). Without nub the floor
+  // simply has no `File` global, so backfilling it would newly surface that warning
+  // when user code first constructs a File. To keep the floor backfill silent we
+  // force one throwaway construction INSIDE a suppression window: that consumes
+  // Node's once-per-feature guard (the warning is dropped here) so the user's later
+  // `new File(...)` is silent.
+  if (typeof globalThis.File === "undefined" || typeof globalThis.Blob === "undefined") {
+    const origEmitWarning = process.emitWarning;
+    process.emitWarning = function (warning, ...rest) {
+      const opt = rest[0];
+      const type = opt && typeof opt === "object" ? opt.type : opt;
+      const msg = typeof warning === "string" ? warning : (warning && warning.message) || "";
+      if (type === "ExperimentalWarning" && /buffer\.(File|Blob)/.test(msg)) return;
+      return origEmitWarning.call(this, warning, ...rest);
+    };
+    try {
+      const buffer = require("node:buffer");
+      const sampleArgs = { File: [[], ""], Blob: [[]] };
+      for (const name of ["File", "Blob"]) {
+        const Ctor = buffer[name];
+        if (typeof globalThis[name] === "undefined" && typeof Ctor === "function") {
+          Object.defineProperty(globalThis, name, {
+            value: Ctor,
+            enumerable: false,
+            writable: true,
+            configurable: true,
+          });
+          // Trip (and suppress) the experimental-feature warning now, so user code
+          // never sees it.
+          try { new Ctor(...sampleArgs[name]); } catch { /* construction shape varies; the warning fires regardless */ }
+        }
+      }
+    } finally {
+      process.emitWarning = origEmitWarning;
+    }
+  }
+
+  // ── MessageEvent.ports → frozen array (WHATWG read-only requirement) ─
+  // The spec mandates `MessageEvent.ports` be a read-only (frozen) array; Node's
+  // native MessageEvent returns a mutable array. Wrap the configurable prototype
+  // getter so every read yields a frozen array, for both a native MessageChannel's
+  // delivery and nub's worker-side MessageEvents. Idempotent (the wrapper is marked
+  // so a re-run in the same realm doesn't double-wrap).
+  if (typeof globalThis.MessageEvent === "function") {
+    const proto = globalThis.MessageEvent.prototype;
+    const desc = Object.getOwnPropertyDescriptor(proto, "ports");
+    if (desc && typeof desc.get === "function" && desc.configurable && !desc.get.__nubFreezesPorts) {
+      const origGet = desc.get;
+      const get = function () {
+        const ports = origGet.call(this);
+        return Array.isArray(ports) ? Object.freeze(ports) : ports;
+      };
+      get.__nubFreezesPorts = true;
+      Object.defineProperty(proto, "ports", { ...desc, get });
+    }
+  }
+
   // ── URLPattern (native on Node 24+, missing on 22.x) ───────────────
   if (typeof globalThis.URLPattern === "undefined") {
     const mod = preloaded.urlpattern;

package/runtime/preload-async-hooks.mjs

@@ -28,8 +28,8 @@
 // loader worker, not a user realm, so it installs no browser globals.)
 import "./floor-builtin.mjs";
 import {
-  TRANSPILE_EXTS, DATA_EXTS,
-  extname, resolveSpec, loadTranspile, loadData,
+  TRANSPILE_EXTS, PLAIN_JS_EXTS, DATA_EXTS,
+  extname, resolveSpec, loadTranspile, maybeTranspilePlainJs, loadData, isNodeModules,
 } from "./transform-core.mjs";
 import { createRequire, isBuiltin } from "node:module";
 import { existsSync } from "node:fs";
@@ -85,13 +85,26 @@ export async function resolve(specifier, context, nextResolve) {
 // ── Load hook ───────────────────────────────────────────────────────
 export async function load(url, context, nextLoad) {
   const ext = extname(url);
-  if (TRANSPILE_EXTS.has(ext)) {
+  // node_modules deps are NEVER transpiled (the byte-parity boundary). This guard is
+  // make-or-break now that TRANSPILE_EXTS includes `.js`/`.mjs`/`.cjs`: without it,
+  // the compat tier would route every dependency `.js` through oxc. (loadTranspile's
+  // own skip-gate handles the project-source no-op case; this keeps deps off the
+  // pipeline entirely.) Mirrors the fast-tier sync hook's `!isNodeModules` gate.
+  if (TRANSPILE_EXTS.has(ext) && !isNodeModules(url)) {
     // Module-format + decorator detection inside loadTranspile is a synchronous
     // native call (nub's addon), available on every supported Node — no parser
     // warm-up needed (the old `await ensureParser()` for the ESM-only oxc-parser
     // is gone with the package).
     return loadTranspile(url, ext);
   }
+  // Project-source plain JS: transpile ONLY when it carries transformable syntax. A
+  // no-op plain-JS file returns null and falls through to `nextLoad` — Node's own
+  // loader handles it byte-identically, preserving every native CJS/ESM behavior.
+  // node_modules excluded (the byte-parity boundary).
+  if (PLAIN_JS_EXTS.has(ext) && !isNodeModules(url)) {
+    const r = maybeTranspilePlainJs(url, ext);
+    if (r) return r;
+  }
   if (ext in DATA_EXTS) return loadData(url, ext);
   return nextLoad(url, context);
 }

package/runtime/preload-common.cjs

@@ -373,6 +373,13 @@ function makeHooks(core, watchReporting) {
       if (core.TRANSPILE_EXTS.has(ext) && !core.isNodeModules(url)) {
         return core.loadTranspile(url, ext);
       }
+      // Plain JS: transpile only when transformable; else fall through to the raw-
+      // source path below (which hands CJS back as `source:null` → Node's native
+      // CJS loader), byte-identical to a non-intercepted file.
+      if (core.PLAIN_JS_EXTS.has(ext) && !core.isNodeModules(url)) {
+        const r = core.maybeTranspilePlainJs(url, ext);
+        if (r) return r;
+      }
       if (ext in core.DATA_EXTS) return core.loadData(url, ext);
       const { readFileSync } = require("node:fs");
       const source = readFileSync(path);
@@ -432,6 +439,15 @@ function makeHooks(core, watchReporting) {
     if (core.TRANSPILE_EXTS.has(ext) && !core.isNodeModules(url)) {
       return core.loadTranspile(url, ext);
     }
+    // Project-source plain JS (`.js`/`.mjs`/`.cjs`): transpile ONLY when it carries
+    // transformable syntax. A no-op plain-JS file returns null here and falls through
+    // to Node's native loader (the `nextLoad`/relabel path below) BYTE-FOR-BYTE — it
+    // is never intercepted, so native CJS/ESM behavior (the relabel, require.cache,
+    // the require-of-ESM-syntax-`.cjs` error) is preserved. node_modules excluded.
+    if (core.PLAIN_JS_EXTS.has(ext) && !core.isNodeModules(url)) {
+      const r = core.maybeTranspilePlainJs(url, ext);
+      if (r) return r;
+    }
     if (ext in core.DATA_EXTS) return core.loadData(url, ext);
 
     // Fidelity: a `data:` URL whose MIME maps to no module format (e.g.
@@ -673,6 +689,39 @@ function installCjsRequireHooks(core, withClassicTranspile) {
   for (const ext of [".ts", ".cts", ".mts", ".tsx", ".jsx"]) {
     module_._extensions[ext] = transpileExtension;
   }
+
+  // Project-source plain JS (`.js`/`.cjs`) routes through the SAME pipeline so
+  // `using`/`v`-flag-RegExp/decorators lower uniformly on the classic require tier —
+  // but ONLY when the file carries transformable syntax. THREE cases, each preserving
+  // Node's native behavior where it must:
+  //   (1) node_modules dep → native handler (deps are NEVER transpiled). Node has no
+  //       own `_extensions['.cjs']` (only `.js`/`.json`/`.node`), and compiles `.cjs`
+  //       through the same CJS path as `.js`, so the `.cjs` bail falls back to the
+  //       `.js` handler (`|| nativeJs`) — without it a node_modules `.cjs` require
+  //       would call `undefined` and crash.
+  //   (2) project file with transformable syntax → transpile (lower it).
+  //   (3) project file with NOTHING to lower → the ORIGINAL native handler, raw bytes
+  //       compiled exactly as Node would. We never serve our own source for a no-op
+  //       file, so require.cache / the require-of-ESM-syntax-`.cjs` SyntaxError / every
+  //       native CJS behavior is byte-identical.
+  // `.mjs` is ESM-only; Node registers no require.extensions handler for it, so a
+  // `require()` of `.mjs` throws ERR_REQUIRE_ESM as before — we don't override it.
+  const nativeJs = module_._extensions[".js"];
+  for (const ext of [".js", ".cjs"]) {
+    const origExtension = module_._extensions[ext] || nativeJs;
+    module_._extensions[ext] = (mod, filename) => {
+      if (core.isNodeModules(pathToFileURL(filename).href)) {
+        return origExtension.call(module_._extensions, mod, filename); // (1)
+      }
+      const r = core.maybeTranspilePlainJs(pathToFileURL(filename).href, pathExtname(filename));
+      if (r) {
+        if (r.format === "module") throw requireEsmError(filename); // (2)
+        mod._compile(r.source, filename);
+        return;
+      }
+      return origExtension.call(module_._extensions, mod, filename); // (3)
+    };
+  }
 }
 
 // ── Clobbered-polyfill preloading + Temporal lazy global ────────────

package/runtime/preload.cjs

@@ -209,6 +209,21 @@ function installLazyEsmPolyfills() {
     }
   };
 
+  // navigator backfill, ordered BEFORE the navigator.locks installs below so locks
+  // always has a host. The fast tier floor is 22.15 (navigator is always native, >= 21),
+  // so installNavigatorShim() version-checks and returns WITHOUT reading globalThis
+  // .navigator — never triggering the 24.5+ lazy-navigator realization. It does real
+  // work only if this preload is ever reached on Node < 21; on the fast floor it is a
+  // cheap no-op, wired for symmetry with the compat tier. See navigator-shim.mjs.
+  try {
+    __require("./navigator-shim.mjs").installNavigatorShim();
+  } catch (err) {
+    // require(esm) disabled (--no-experimental-require-module): navigator is native at
+    // the fast floor, so skipping the no-op shim is harmless. Any OTHER error is a real
+    // fault in the module — surface it rather than swallow it.
+    if (!err || err.code !== "ERR_REQUIRE_ESM") throw err;
+  }
+
   if (inWorkerThread) {
     // Worker-side scope bootstrap must be present synchronously where possible.
     loadEsmSideEffect("./worker-polyfill.mjs");

package/runtime/preload.mjs

@@ -112,6 +112,14 @@ if (__isFastTier) {
 // modules is unreliable, so they load via dynamic `import()` here.
 const __preloadedPolyfills = common.preloadPolyfillPackages(__require);
 installSyncPolyfills(__preloadedPolyfills);
+// navigator backfill (Node < 21: the `navigator` global is wholly absent). MUST run
+// BEFORE navigator-locks so Web Locks has a host on the 18.19–20.x floor. On Node >= 21
+// it is a no-op (navigator is native). Thread the floor's createRequire so the shim can
+// fetch node:os where process.getBuiltinModule is absent (the narrow floor). See
+// navigator-shim.mjs.
+const __navShim = await import("./navigator-shim.mjs");
+__navShim.setBootstrapCreateRequire(floorCreateRequire);
+__navShim.installNavigatorShim();
 if (typeof globalThis.navigator?.locks === "undefined") {
   await import("./navigator-locks.mjs");
 }

package/runtime/transform-core.mjs

@@ -156,7 +156,21 @@ if (typeof process.getBuiltinModule === "function") __ensureBuiltins();
 // natively now, and this file no longer needs to read version.mjs.
 
 // ── Constants ───────────────────────────────────────────────────────
+// TS/JSX exts ALWAYS transform (type-stripping is required), so they live in
+// TRANSPILE_EXTS — the set every dispatch site checks to route a file to
+// loadTranspile. Plain JS (.js/.mjs/.cjs) is DELIBERATELY NOT here: a plain-JS file
+// is transpiled ONLY when it carries transformable syntax (`using`/`await using`,
+// `v`-flag RegExp, decorators), and a no-op plain-JS file must take Node's OWN load
+// path BYTE-FOR-BYTE — putting it in TRANSPILE_EXTS would route every `.js`/`.cjs`
+// through nub's hook and change native CJS/ESM behavior (the `commonjs-sync` relabel,
+// require.cache, the require-of-ESM-syntax-.cjs error). So plain JS is handled by a
+// SEPARATE narrow path (`maybeTranspilePlainJs`) that fires only for transformable
+// files and is a no-op (returns null) otherwise — see PLAIN_JS_EXTS below.
 export const TRANSPILE_EXTS = new Set([".ts", ".tsx", ".mts", ".cts", ".jsx"]);
+// Project-source plain JS. Routed to the transpiler ONLY when transformable (the
+// `maybeTranspilePlainJs` gate); a no-op plain-JS file falls through to Node's
+// native loader untouched, byte-identical. node_modules is excluded at the gate.
+export const PLAIN_JS_EXTS = new Set([".js", ".mjs", ".cjs"]);
 export const DATA_EXTS = { ".jsonc": "jsonc", ".json5": "json5", ".toml": "toml", ".yaml": "yaml", ".yml": "yaml", ".txt": "txt" };
 export const TS_PARENT_EXTS = new Set([".ts", ".tsx", ".mts", ".cts"]);
 
@@ -328,7 +342,7 @@ export function resolveSpec(specifier, parentURL) {
   // from a nub-dependency ESM entry) delegated to a strict user loader is exactly
   // the R11 leak. See isNubInternalParent.
   if (isNubInternalParent(parentURL)) {
-    if (specifier.startsWith("node:") || module.builtinModules.includes(specifier)) {
+    if (specifier.startsWith("node:") || module.isBuiltin(specifier)) {
       const url = specifier.startsWith("node:") ? specifier : `node:${specifier}`;
       return { url, shortCircuit: true };
     }
@@ -349,7 +363,7 @@ export function resolveSpec(specifier, parentURL) {
 
   // node: and data: protocols, and bare Node built-ins, are never ours.
   if (specifier.startsWith("node:") || specifier.startsWith("data:")) return null;
-  if (module.builtinModules.includes(specifier)) return null;
+  if (module.isBuiltin(specifier)) return null;
 
   // 1. Built-in modules provided by Nub.
   if (BUILTIN_MODULES.has(specifier)) {
@@ -392,7 +406,7 @@ export function resolveSpec(specifier, parentURL) {
 // file's absolute path (from the CJS parent Module), or null for the entry.
 export function resolveCjsPath(request, parentPath) {
   if (request.startsWith("node:") || request.startsWith("data:") ||
-      module.builtinModules.includes(request)) {
+      module.isBuiltin(request)) {
     return null;
   }
   // The SAME native additive resolver as resolveSpec, returning an absolute path
@@ -435,13 +449,15 @@ function detectModuleInfo(filePath, source, lang) {
   // Addon missing (should never happen in a real install): default to ESM for
   // format (the common case) and "no decorators" for the guard — the same fallback
   // the old oxc-parser-unavailable branches used.
-  if (!nubNative) return { hasValueEsmSyntax: true, hasDecorators: false };
+  if (!nubNative) return { hasValueEsmSyntax: true, hasDecorators: false, transformableSyntax: false };
   try {
     return nubNative.detectModuleInfo(filePath, source, lang);
   } catch {
     // Unparseable → CJS for format + no decorators (the transpile/V8 surfaces the
-    // real error), matching the old per-call catch blocks.
-    return { hasValueEsmSyntax: false, hasDecorators: false };
+    // real error), matching the old per-call catch blocks. `transformableSyntax:
+    // false` is the SAFE plain-JS default — the verbatim path hands the raw bytes
+    // back, so V8 surfaces the real syntax error exactly where Node would.
+    return { hasValueEsmSyntax: false, hasDecorators: false, transformableSyntax: false };
   }
 }
 
@@ -450,13 +466,28 @@ function detectModuleInfo(filePath, source, lang) {
 // `type` is authoritative; otherwise (ambiguous) we detect from source syntax —
 // full Node parity (`--experimental-detect-module`), so a CJS-syntax `.ts` with
 // no `type` runs as CJS on nub exactly as on Node. See wiki/runtime/module-format.md.
+// `.mjs`→module / `.cjs`→commonjs are explicit (mirroring `.mts`/`.cts`), so the
+// plain-JS gate gets the right format without a needless detect.
 export function moduleFormatFor(ext, pkgType, filePath, source) {
-  if (ext === ".mts") return "module";
-  if (ext === ".cts") return "commonjs";
-  if (pkgType === "module") return "module";
-  if (pkgType === "commonjs") return "commonjs";
+  return moduleFormatWithInfo(ext, pkgType, filePath, source).format;
+}
+
+// Same format decision as moduleFormatFor, but ALSO returns the `ModuleInfo`
+// (`detectModuleInfo`) result when a parse was needed — `{ format, info }`, with
+// `info` null on the no-parse short-circuits (`.mts`/`.mjs`/`.cts`/`.cjs`, explicit
+// `type`). loadTranspile uses this so its ONE parse serves BOTH readers — the
+// format decision (`hasValueEsmSyntax`) and the Stage-3 decorator guard
+// (`hasDecorators`) — instead of `moduleFormatFor` + `hasDecoratorSyntax` each
+// parsing the same source. On a short-circuit (`info` null) no parse happened, so
+// the decorator guard runs its own single parse: still ≤1 detect per file.
+function moduleFormatWithInfo(ext, pkgType, filePath, source) {
+  if (ext === ".mts" || ext === ".mjs") return { format: "module", info: null };
+  if (ext === ".cts" || ext === ".cjs") return { format: "commonjs", info: null };
+  if (pkgType === "module") return { format: "module", info: null };
+  if (pkgType === "commonjs") return { format: "commonjs", info: null };
   const lang = ext === ".tsx" ? "tsx" : ext === ".jsx" ? "jsx" : "ts";
-  return detectModuleInfo(filePath, source, lang).hasValueEsmSyntax ? "module" : "commonjs";
+  const info = detectModuleInfo(filePath, source, lang);
+  return { format: info.hasValueEsmSyntax ? "module" : "commonjs", info };
 }
 
 // The Stage-3-decorator rejection diagnostic. oxc does not lower TC39 Stage 3
@@ -568,9 +599,13 @@ export function loadTranspile(url, ext) {
   // (.ts/.tsx/.jsx); .mts/.cts are explicit so its lookup is skipped. The chosen
   // format is folded into the cache key (and the entry's leading byte) by native.
   const pkgType = ext === ".mts" || ext === ".cts" ? undefined : getPackageType(dir);
-  const format = moduleFormatFor(ext, pkgType, filePath, source);
+  // ONE detectModuleInfo parse for both the format decision and the decorator
+  // guard below: `moduleInfo` is the parsed ModuleInfo when the format needed a
+  // parse (ambiguous ext, no explicit `type`), else null (a no-parse short-circuit).
+  const { format, info: moduleInfo } = moduleFormatWithInfo(ext, pkgType, filePath, source);
 
   const lang = ext === ".tsx" ? "tsx" : ext === ".jsx" ? "jsx" : "ts";
+
   const opts = {
     lang,
     sourceType: format === "commonjs" ? "commonjs" : "module",
@@ -604,9 +639,12 @@ export function loadTranspile(url, ext) {
   // SyntaxError. When legacy mode is off and decorator syntax is present, reject
   // with the documented Option-A diagnostic instead. (Cheap `source.includes("@")`
   // pre-filter keeps decorator-free files off the native parser; runs BEFORE the
-  // cache so the diagnostic surfaces even on what would be a warm hit.)
+  // cache so the diagnostic surfaces even on what would be a warm hit.) Reuse the
+  // `hasDecorators` flag from the format parse above when it ran (`moduleInfo`
+  // non-null), so the ambiguous-ext + `@` path detects ONCE; on a no-parse
+  // short-circuit (`.mts`/`.cts`/explicit `type`) it does its own single parse.
   if (co?.experimentalDecorators !== true && source.includes("@") &&
-      hasDecoratorSyntax(filePath, source, lang)) {
+      (moduleInfo ? moduleInfo.hasDecorators : hasDecoratorSyntax(filePath, source, lang))) {
     throw stage3DecoratorError(filePath);
   }
 
@@ -626,6 +664,40 @@ export function loadTranspile(url, ext) {
   return { format: result.format, source: result.code, shortCircuit: true };
 }
 
+// Project-source plain JS (`.js`/`.mjs`/`.cjs`) gate. Returns a transpiled load
+// result ONLY when the file carries syntax oxc lowers at nub's es2022 target
+// (`using`/`await using`, a `v`-flag RegExp, or decorators); otherwise returns
+// `null`, meaning "this file needs no transform — handle it with Node's OWN loader,
+// exactly as a non-listed extension." This is why `.js`/`.mjs`/`.cjs` are NOT in
+// TRANSPILE_EXTS: a no-op plain-JS file must take Node's native load path
+// byte-for-byte (preserving the `commonjs-sync` relabel, require.cache, the
+// require-of-ESM-syntax-`.cjs` error — all of which intercepting the file would
+// break), and oxc would reformat it (quotes/semicolons/whitespace + a sourcemap
+// footer) if we ran it through anyway. The verdict rides ONE parse (the same one
+// `detectModuleInfo` does for format detection). node_modules is gated at the call
+// sites (the byte-parity boundary). JSX-in-`.js` is out of scope (lang is "ts",
+// which does not parse JSX); use `.jsx`.
+export function maybeTranspilePlainJs(url, ext) {
+  __ensureBuiltins();
+  const filePath = fileURLToPath(url);
+  let source;
+  try {
+    source = readFileSync(filePath, "utf8");
+  } catch {
+    // Unreadable here → let Node's loader surface its own error.
+    return null;
+  }
+  // lang "ts" parses all JS (a TS superset) but NOT JSX — JSX-in-.js is out of scope.
+  const info = detectModuleInfo(filePath, source, "ts");
+  if (!info.transformableSyntax && !info.hasDecorators) {
+    return null; // no-op: Node's native loader handles it, byte-identical.
+  }
+  // Transformable: run the SAME pipeline as TS/JSX (target es2022 lowering, tsconfig,
+  // source maps, the Stage-3 decorator guard, format detection, cache). loadTranspile
+  // re-reads + re-parses, but only for the rare file that actually needs lowering.
+  return loadTranspile(url, ext);
+}
+
 // ── Data-format imports ─────────────────────────────────────────────
 function lazyRequire(pkg) {
   try { return __require(pkg); } catch {

package/runtime/version.mjs

@@ -9,4 +9,4 @@
 // previously lived as a literal inside preload.mjs, which `make version` patched,
 // while the worker carried a hand-maintained "…-compat" copy that `make version`
 // never touched — a latent staleness bug this module closes.)
-export const NUB_VERSION = "0.2.1";
+export const NUB_VERSION = "0.2.2";