@nubjs/loader 0.8.3 → 0.9.0-canary.20260909.509

package/loader-entry.mjs

@@ -87,13 +87,16 @@ function isOwnLoaderToken(value) {
 // delivery channel (execArgv or NODE_OPTIONS). Same two-channel scan as
 // preload-common's computeForeignAsyncLoaderFlagPresent, but value-aware so our
 // own token is excluded.
-function foreignAsyncLoaderPresent() {
+function foreignAsyncLoaderPresent(includeRequire = false) {
   const tokens = [];
+  const flags = ["--import", "--loader", "--experimental-loader", "--experimental_loader"];
+  if (includeRequire) flags.push("--require", "-r");
   const argv = Array.isArray(process.execArgv) ? process.execArgv : [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (typeof a !== "string") continue;
-    for (const flag of ["--import", "--loader", "--experimental-loader"]) {
+    if (includeRequire && a.startsWith("-r") && a.length > 2) tokens.push(a.slice(2));
+    for (const flag of flags) {
       if (a === flag) {
         if (typeof argv[i + 1] === "string") tokens.push(argv[i + 1]);
       } else if (a.startsWith(`${flag}=`)) {
@@ -103,7 +106,9 @@ function foreignAsyncLoaderPresent() {
   }
   const opts = process.env.NODE_OPTIONS;
   if (typeof opts === "string" && opts !== "") {
-    const re = /(?:^|\s)--(?:experimental-)?(?:import|loader)(?:=|\s)("[^"]*"|\S*)/g;
+    const re = includeRequire
+      ? /(?:^|\s)(?:--(?:(?:experimental[-_])?(?:import|loader)|require)(?:=|\s)|-r(?:\s|=)?)("[^"]*"|\S*)/g
+      : /(?:^|\s)--(?:experimental[-_])?(?:import|loader)(?:=|\s)("[^"]*"|\S*)/g;
     for (const match of opts.matchAll(re)) {
       tokens.push((match[1] || "").replace(/^"|"$/g, ""));
     }
@@ -153,11 +158,16 @@ export function arm({ esm = true, cjs = true } = {}) {
   // loader (tsx, ts-node, an OTel ESM attach) would crash resolution. Register
   // via the async path there instead so both loaders compose all-async — the same
   // tier decision the CLI preload makes, minus counting ourselves as foreign.
-  const forceAsync = common.nodeHookComposeBroken() && foreignAsyncLoaderPresent();
+  const foreignLoaderFlagPresent = foreignAsyncLoaderPresent();
+  const forceAsync = common.nodeHookComposeBroken() && foreignLoaderFlagPresent;
 
   if (wantEsm) {
     if (hasSyncHooks && !forceAsync) {
-      const { resolve, load } = common.makeHooks(core, watchReporting);
+      // The standalone --import is our own loader, not a foreign async hook.
+      // Earlier --require preloads may have registered hooks before our detectors
+      // were installed. Decline the cache repair for them too, without assuming
+      // their hooks are async when choosing the composition tier above.
+      const { resolve, load } = common.makeHooks(core, watchReporting, foreignAsyncLoaderPresent(true));
       module_.registerHooks({ resolve, load });
       armed.esmMode = "sync";
     } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubjs/loader",
-  "version": "0.8.3",
+  "version": "0.9.0-canary.20260909.509",
   "description": "Standalone TypeScript loader for Node.js from the Nub project — TypeScript, JSX, tsconfig paths, and data-format imports through a native transform, registered the way tsx and ts-node are",
   "license": "MIT",
   "repository": "https://github.com/nubjs/nub",
@@ -49,13 +49,13 @@
     "@oxc-project/runtime": "0.140.0"
   },
   "optionalDependencies": {
-    "@nubjs/loader-darwin-arm64": "0.8.3",
-    "@nubjs/loader-darwin-x64": "0.8.3",
-    "@nubjs/loader-linux-x64": "0.8.3",
-    "@nubjs/loader-linux-x64-musl": "0.8.3",
-    "@nubjs/loader-linux-arm64": "0.8.3",
-    "@nubjs/loader-linux-arm64-musl": "0.8.3",
-    "@nubjs/loader-win32-x64": "0.8.3",
-    "@nubjs/loader-win32-arm64": "0.8.3"
+    "@nubjs/loader-darwin-arm64": "0.9.0-canary.20260909.509",
+    "@nubjs/loader-darwin-x64": "0.9.0-canary.20260909.509",
+    "@nubjs/loader-linux-x64": "0.9.0-canary.20260909.509",
+    "@nubjs/loader-linux-x64-musl": "0.9.0-canary.20260909.509",
+    "@nubjs/loader-linux-arm64": "0.9.0-canary.20260909.509",
+    "@nubjs/loader-linux-arm64-musl": "0.9.0-canary.20260909.509",
+    "@nubjs/loader-win32-x64": "0.9.0-canary.20260909.509",
+    "@nubjs/loader-win32-arm64": "0.9.0-canary.20260909.509"
   }
 }

package/preload-async-hooks.mjs

@@ -30,6 +30,7 @@ import "./floor-builtin.mjs";
 import {
   TRANSPILE_EXTS, PLAIN_JS_EXTS, CLOBBER_MAP, dataExtsFor,
   extname, isFileUrl, resolveSpec, loadTranspile, maybeTranspilePlainJs, loadData, loadTextImport, isDependency,
+  noteRuntimeV8FlagSource, outerHookOwnsFormat,
 } from "./transform-core.mjs";
 import { createRequire, isBuiltin } from "node:module";
 import { existsSync } from "node:fs";
@@ -92,7 +93,14 @@ export async function resolve(specifier, context, nextResolve) {
 }
 
 // ── Load hook ───────────────────────────────────────────────────────
+// Every result passes through the runtime-V8-flag scan before Node compiles it —
+// see transform-core `noteRuntimeV8FlagSource`. Awaited here because the
+// `nextLoad` branch of loadInner hands back a promise on this tier.
 export async function load(url, context, nextLoad) {
+  return noteRuntimeV8FlagSource(await loadInner(url, context, nextLoad));
+}
+
+async function loadInner(url, context, nextLoad) {
   // Import Text (attribute-keyed): honor `with { type: "text" }` on ANY extension,
   // checked BEFORE extension dispatch so `import s from "./c.yaml" with {type:"text"}`
   // returns the raw text, not parsed YAML. shortCircuits, so Node never runs its own
@@ -106,6 +114,11 @@ export async function load(url, context, nextLoad) {
   // fast-tier hook.
   if (context?.importAttributes?.type === "text" && isFileUrl(url)) return loadTextImport(url);
   const ext = extname(url);
+  // A user loader above nub's assigned this TypeScript file a bare module format
+  // and will transform it itself from the raw source (tsx's pattern; see
+  // `outerHookOwnsFormat`). This tier has no registration counter like the fast
+  // tier's and needs none: nothing but such a hook produces the bare form here.
+  if (outerHookOwnsFormat(context?.format, ext) && !isDependency(url)) return nextLoad(url, context);
   // 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

package/preload-common.cjs

@@ -34,14 +34,47 @@ const { join, dirname, extname: pathExtname } = getBuiltin("node:path");
 // 16 + Turbopack build died on `--js-defer-import-eval`. V8 parses these flags at
 // startup, so dropping them here keeps the feature ON while restoring the execArgv a
 // plain-Node user would have seen. Only flags NUB injected are removed; a user's own
-// `v8Flags` stay visible, because those are the user's choice to reason about.
+// `v8Flags` stay visible, because those are the user's choice to reason about. (The
+// set is empty today — `--js-defer-import-eval` moved to a runtime flip, see
+// transform-core `noteRuntimeV8FlagSource` — but the hygiene stays for any future
+// argv-only row.)
+// The flags have to be hidden on two boundaries, and no single channel spans both.
+//
+// The ENV VAR crosses a PROCESS boundary: the Rust spawn layer sets it on a Node it
+// starts. Deleting it after use is what stops a descendant from hiding a flag its own
+// user passed, so that hygiene stays.
+//
+// WORKER ENVIRONMENT DATA crosses a THREAD boundary, which the env var cannot. Node
+// starts a worker from the process's REAL exec argv — flags and all — whatever the main
+// thread filtered, so the worker has to filter again, and this preload runs there to do
+// it. Three measured properties make this the right channel and an env copy the wrong
+// one (verified on 18.19 and 26.7): it survives `new Worker(…, { env: {} })`, which
+// REPLACES the environment outright and would otherwise strand that worker with the flags
+// visible; it is transitive to nested workers; and it does NOT cross a process boundary,
+// so a thread of this process is separated from a descendant structurally rather than by
+// guesswork.
+const ARGV_ONLY_FLAGS_KEY = "nub.argv-only-flags";
+// A compiled artifact whose sealed graph cannot reach Worker or worker_threads has
+// no second thread, so nothing can have written this channel and nobody can read
+// what we publish to it — only the env var below carries flags into such a process.
+// Asking anyway loads the builtin, and its subgraph is eight internal modules on
+// every run. This module's EVALUATION is part of the compile preamble's static
+// import graph, so no call-gating reaches that cost; the same signal and the same
+// deliberately over-detecting build-time scan gate the preamble's own Worker branch.
+// The record is published by the bootstrap's `--require`, ahead of any ESM here,
+// and is absent outside a compiled artifact — so this reads false there and the
+// load stays eager, which is the only behaviour an ordinary run ever had.
+const workerless = compileBootstrap?.needsWorker === false;
 try {
-  const injectedArgvFlags = process.env.__NUB_ARGV_ONLY_FLAGS;
+  const workerThreads = workerless ? null : getBuiltin("node:worker_threads");
+  const fromEnv = process.env.__NUB_ARGV_ONLY_FLAGS;
+  const injectedArgvFlags = fromEnv || workerThreads?.getEnvironmentData(ARGV_ONLY_FLAGS_KEY);
   if (injectedArgvFlags) {
-    // Delete rather than propagate: a descendant that nub augments gets its own
-    // signal, and one that nub does not never had the flags on argv anyway.
-    delete process.env.__NUB_ARGV_ONLY_FLAGS;
-    const injected = new Set(injectedArgvFlags.split(" ").filter(Boolean));
+    if (fromEnv) {
+      delete process.env.__NUB_ARGV_ONLY_FLAGS;
+      workerThreads?.setEnvironmentData(ARGV_ONLY_FLAGS_KEY, fromEnv);
+    }
+    const injected = new Set(String(injectedArgvFlags).split(" ").filter(Boolean));
     if (Array.isArray(process.execArgv)) {
       process.execArgv = process.execArgv.filter((arg) => !injected.has(arg));
     }
@@ -64,7 +97,15 @@ const VERSION_ENV = "__NUB_VERSION";
 // feature-matrix `import-text` bands cover every release that KNOWS the flag: on a
 // version nub steps aside on but does not inject for, the import falls through to
 // Node's default loader and dies with ERR_UNKNOWN_FILE_EXTENSION (#688).
-const NATIVE_IMPORT_TEXT = process.allowedNodeEnvironmentFlags.has("--experimental-import-text");
+// Read LAZILY. The first touch of `process.allowedNodeEnvironmentFlags` materialises
+// Node's entire accepted-flag set, and as a top-level const that cost 0.355 ms of
+// this module's evaluation (child CPU, 200 runs, against a 0.000 ms control) on
+// every nub process and inside every compiled artifact — where this module is a
+// static import of the preamble, so nothing call-gated can reach it. Both readers
+// sit inside the load hook's `type: "text"` arm, which most programs never take.
+let __nativeImportText;
+const nativeImportText = () =>
+  (__nativeImportText ??= process.allowedNodeEnvironmentFlags.has("--experimental-import-text"));
 
 // ── data: URL unknown-format fidelity helpers ───────────────────────
 // Mirror Node's internal/modules/esm/get_format.js so nub's sync registerHooks load
@@ -190,6 +231,10 @@ function installWatchReporting(core) {
 // `type` (transpile — there is no user hook to do it, and Node's strip-only mode
 // can't handle enums/namespaces). See makeHooks().load.
 let __userHooksRegistered = false;
+// Narrower: a user registration that brought a `load` hook, so it can transform
+// what nub hands back. A resolve-only user hook that labels a `.ts` file with a
+// bare `commonjs`/`module` still relies on nub as the transformer.
+let __userLoadHookRegistered = false;
 function installUserHookDetector() {
   if (typeof module_.registerHooks !== "function") return;
   const orig = module_.registerHooks;
@@ -197,7 +242,10 @@ function installUserHookDetector() {
   let seen = 0;
   const wrapped = function (...args) {
     // Call #1 is nub's own preload registration; #2+ are user hooks.
-    if (seen >= 1) __userHooksRegistered = true;
+    if (seen >= 1) {
+      __userHooksRegistered = true;
+      if (args[0] && typeof args[0].load === "function") __userLoadHookRegistered = true;
+    }
     seen += 1;
     return orig.apply(this, args);
   };
@@ -252,6 +300,7 @@ function cliAsyncLoaderPresent() {
         if (
           a === "--loader" || a.startsWith("--loader=") ||
           a === "--experimental-loader" || a.startsWith("--experimental-loader=") ||
+          a === "--experimental_loader" || a.startsWith("--experimental_loader=") ||
           a === "--import" || a.startsWith("--import=")
         ) { present = true; break; }
       }
@@ -275,9 +324,10 @@ function cliAsyncLoaderPresent() {
 // against a user async loader, and Node rejected the `commonjs-sync`+null-source pair
 // (#669). That helper also excludes nub's OWN preload chainer, which rides NODE_OPTIONS
 // as `--import`; a raw scan here would read it as a user loader and silently decline
-// the relabel for every chained project.
-function userAsyncLoaderActive() {
-  return __userAsyncLoaderRegistered || foreignAsyncLoaderFlagPresent();
+// the relabel for every chained project. The standalone loader supplies its
+// value-aware flag scan instead, excluding its own --import entrypoint too.
+function userAsyncLoaderActive(foreignLoaderFlagPresent) {
+  return __userAsyncLoaderRegistered || foreignLoaderFlagPresent;
 }
 
 // The Node band where the async `module.register` loader's `resolveSync`/`loadSync`
@@ -328,7 +378,7 @@ function computeForeignAsyncLoaderFlagPresent() {
   if (cliAsyncLoaderPresent()) return true; // execArgv channel
   const opts = process.env.NODE_OPTIONS;
   if (typeof opts !== "string" || opts === "") return false;
-  const re = /(?:^|\s)--(?:experimental-)?(?:import|loader)(?:=|\s)("[^"]*"|\S*)/g;
+  const re = /(?:^|\s)--(?:experimental[-_])?(?:import|loader)(?:=|\s)("[^"]*"|\S*)/g;
   for (const match of opts.matchAll(re)) {
     const value = (match[1] || "").replace(/^"|"$/g, "");
     if (!NUB_CHAIN_MARKER.test(value)) return true;
@@ -593,7 +643,7 @@ function restoreSchemeOnlyBuiltinURL(result) {
   }
 }
 
-function makeHooks(core, watchReporting) {
+function makeHooks(core, watchReporting, foreignLoaderFlagPresent = foreignAsyncLoaderFlagPresent()) {
   installUserHookDetector();
   installUserAsyncLoaderDetector();
 
@@ -655,14 +705,22 @@ function makeHooks(core, watchReporting) {
       const source = readFileSync(path);
       const pkgType = core.getPackageType(dirname(path));
       const format = core.moduleFormatFor(ext, pkgType, path, source.toString("utf8"));
-      if (format === "commonjs") return { format: "commonjs", source: null, shortCircuit: true };
-      return { format, source, shortCircuit: true };
+      if (format === "commonjs") return { format: "commonjs", source: null, responseURL: url, shortCircuit: true };
+      return { format, source, responseURL: url, shortCircuit: true };
     } catch {
       return null;
     }
   }
 
+  // Every load result passes through the runtime-V8-flag scan BEFORE Node compiles
+  // it, whichever branch of loadInner produced it — see transform-core
+  // `noteRuntimeV8FlagSource`. A no-op (one null check) unless the spawn layer armed
+  // a flag for this Node.
   function load(url, context, nextLoad) {
+    return core.noteRuntimeV8FlagSource(loadInner(url, context, nextLoad));
+  }
+
+  function loadInner(url, context, nextLoad) {
     const ext = core.extname(url);
 
     // Watch mode: surface this file's nearest config files (tsconfig.json,
@@ -679,7 +737,7 @@ function makeHooks(core, watchReporting) {
 
     // Import Text (attribute-keyed): honor `with { type: "text" }` on ANY extension,
     // ahead of extension dispatch so `import s from "./c.yaml" with {type:"text"}`
-    // returns raw text, not parsed YAML. Where Node knows the flag (NATIVE_IMPORT_TEXT
+    // returns raw text, not parsed YAML. Where Node knows the flag (`nativeImportText()`
     // — 24.19+ on the 24.x line, 26.5+ on 26.x) step aside and let Node's own
     // textStrategy own it — nub injects --experimental-import-text there, so the
     // additive "would plain Node + the flag do the same?" test holds and users get
@@ -700,8 +758,8 @@ function makeHooks(core, watchReporting) {
     // the unknown-data-URL-format trap below instead of Node's own text answer.
     // A non-`file:` URL on the polyfill tier falls through to `nextLoad` with
     // every other unclaimed URL.
-    if (context?.importAttributes?.type === "text" && (NATIVE_IMPORT_TEXT || core.isFileUrl(url))) {
-      return NATIVE_IMPORT_TEXT ? nextLoad(url, context) : core.loadTextImport(url);
+    if (context?.importAttributes?.type === "text" && (nativeImportText() || core.isFileUrl(url))) {
+      return nativeImportText() ? nextLoad(url, context) : core.loadTextImport(url);
     }
 
     // A USER resolve hook (a ts-node/tsx-style transpiler registered AFTER nub's
@@ -722,7 +780,22 @@ function makeHooks(core, watchReporting) {
     // user's outer hook, which does the real ESM->CJS conversion, matching Node.
     // Native 'module-typescript'/'commonjs-typescript' formats still fall through to
     // nub's transpile below, so normal augmentation is unchanged.
-    if (__userHooksRegistered && context && context.format === "typescript") {
+    //
+    // tsx 4.2x writes the bare `commonjs`/`module` form instead of 'typescript'
+    // (`outerHookOwnsFormat`), and the hook that wrote it must also be able to
+    // transform what it gets back: a user registration WITH a load hook
+    // (`__userLoadHookRegistered`), or a loader registered through
+    // `module.register` (`userAsyncLoaderActive`), which the registerHooks counter
+    // cannot see and which nub has no way to inspect. A resolve-only user hook
+    // that labels a `.ts` file keeps nub as its transformer. The 'typescript'
+    // branch keeps its own narrower gate: a non-transpiling async loader (a
+    // telemetry `--import`) must not turn a bare 'typescript' from Node's own
+    // CJS loader into a step-aside.
+    if (context && (
+      (__userHooksRegistered && context.format === "typescript") ||
+      ((__userLoadHookRegistered || userAsyncLoaderActive(foreignLoaderFlagPresent)) &&
+        core.outerHookOwnsFormat(context.format, ext) && !core.isDependency(url))
+    )) {
       return nextLoad(url, context);
     }
 
@@ -845,7 +918,7 @@ function makeHooks(core, watchReporting) {
       typeof url === "string" && url.startsWith("file:") &&
       Array.isArray(context && context.conditions) &&
       context.conditions.includes("import") &&
-      !__userHooksRegistered && !userAsyncLoaderActive()
+      !__userHooksRegistered && !userAsyncLoaderActive(foreignLoaderFlagPresent)
     ) {
       return { ...r, format: "commonjs-sync" };
     }
@@ -976,10 +1049,36 @@ function installCjsRequireHooks(core, withClassicTranspile) {
   // missing. An explicit `require("dep/x/sub.cjs")` is unaffected either way — an
   // exact path is found by stat, without consulting the extension list at all.
   const NUB_ADDED_EXTS = [".ts", ".cts", ".mts", ".tsx", ".jsx", ".cjs"];
+  // A `require.extensions` handler that is ALREADY registered for one of these
+  // when this runs belongs to a transpiler the user chose, and it stays in charge
+  // of that extension: nub's classic shim neither replaces it nor pre-judges its
+  // files as ES modules at resolve time. Every `--require` runs before any `--import`, so on
+  // the compat tier — where nub's own preload is an `--import` — tsx's
+  // `--require`d preflight installs its `.ts` handler FIRST; nub then overwrote
+  // it, and a file tsx would have compiled to CJS (mixed `import` + `require`,
+  // the shape its ESM hook hands to the CJS loader) died in nub's handler as
+  // "Cannot require() this file — it is an ES module". Node itself registers only
+  // `.js`/`.json`/`.node`, so nothing but a user transpiler holds one of these
+  // keys here.
+  const foreignExts = new Set(
+    [...core.TRANSPILE_EXTS, ...core.allDataExts(), ...NUB_ADDED_EXTS].filter((ext) =>
+      ext !== ".js" && ext !== ".json" && ext !== ".node" && Object.hasOwn(module_._extensions, ext)),
+  );
+  // Ownership of a key is decided per lookup, never frozen at start-up: user code
+  // may install or replace a handler after nub's preload (`--import tsx` runs
+  // after every `--require`), and from then on that key is the user's own
+  // widening of LOAD_AS_FILE, exactly as under plain Node plus their handler —
+  // `require("dep/sub")` finding a dependency's `sub.ts` through it is the answer
+  // to preserve. A key is nub's only while BOTH hold: nub introduced it (it was
+  // not in `foreignExts` — a user's `.cjs` handler that nub merely wraps still
+  // counts as theirs) and it still holds a function nub registered below
+  // (`nubHandlers`). Anything else is not nub's to strip, nor to pre-judge.
+  const nubHandlers = new Set();
+  const nubOwnsExt = (ext) => !foreignExts.has(ext) && nubHandlers.has(module_._extensions[ext]);
   const withoutNubAddedExtensions = (fn) => {
     const saved = [];
     for (const ext of NUB_ADDED_EXTS) {
-      if (Object.hasOwn(module_._extensions, ext)) {
+      if (nubOwnsExt(ext)) {
         saved.push([ext, module_._extensions[ext]]);
         delete module_._extensions[ext];
       }
@@ -992,7 +1091,7 @@ function installCjsRequireHooks(core, withClassicTranspile) {
   };
   const isDepAddedExtHit = (filename) =>
     typeof filename === "string" &&
-    NUB_ADDED_EXTS.includes(pathExtname(filename)) &&
+    nubOwnsExt(pathExtname(filename)) &&
     core.isDependency(pathToFileURL(filename).href);
 
   module_._resolveFilename = function (request, parent, isMain, options) {
@@ -1015,7 +1114,8 @@ function installCjsRequireHooks(core, withClassicTranspile) {
       // and 4 from `require.resolve` up to 22.14, but 22.15 and 22.16 pass 4 for both
       // while still lacking native TS — and the translator crash is present on
       // exactly those versions. A clean error beats an opaque crash, so this stays.
-      if (withClassicTranspile && core.requireTargetIsEsm(resolved, pathExtname(resolved))) {
+      if (withClassicTranspile && nubOwnsExt(pathExtname(resolved)) &&
+          core.requireTargetIsEsm(resolved, pathExtname(resolved))) {
         throw requireEsmError(resolved);
       }
       return resolved;
@@ -1144,6 +1244,7 @@ function installCjsRequireHooks(core, withClassicTranspile) {
     if (core.TRANSPILE_EXTS.has(ext)) return transpileExtension(mod, filename);
     return nativeJs.call(module_._extensions, mod, filename);
   };
+  nubHandlers.add(nubExtension);
 
   // Registered for every extension either path may claim, so the dispatcher is
   // reached at all; `nubExtension` then decides. Node's own `.js`/`.json`/`.node`
@@ -1164,7 +1265,7 @@ function installCjsRequireHooks(core, withClassicTranspile) {
   // resolution identical across tiers.
   const CODE_EXTS = new Set([".ts", ".cts", ".mts", ".tsx", ".jsx"]);
   for (const ext of new Set([...core.TRANSPILE_EXTS, ...core.allDataExts()])) {
-    if (ext === ".js" || ext === ".json" || ext === ".node") continue;
+    if (ext === ".js" || ext === ".json" || ext === ".node" || foreignExts.has(ext)) continue;
     Object.defineProperty(module_._extensions, ext, {
       value: nubExtension,
       enumerable: CODE_EXTS.has(ext),
@@ -1192,7 +1293,7 @@ function installCjsRequireHooks(core, withClassicTranspile) {
   // (`nativeJs` is captured above, before the TS handlers are registered.)
   for (const ext of [".js", ".cjs"]) {
     const origExtension = module_._extensions[ext] || nativeJs;
-    module_._extensions[ext] = (mod, filename) => {
+    const plainJsExtension = (mod, filename) => {
       // (0) The project pointed this extension at a data loader (`{".js":"text"}`),
       // which the ESM path honors. These two extensions are skipped by the
       // registration loop above because THIS wrapper owns them and runs after it,
@@ -1215,6 +1316,8 @@ function installCjsRequireHooks(core, withClassicTranspile) {
       }
       return origExtension.call(module_._extensions, mod, filename); // (3)
     };
+    module_._extensions[ext] = plainJsExtension;
+    nubHandlers.add(plainJsExtension);
   }
 }
 
@@ -1717,6 +1820,9 @@ module.exports = {
   preloadPolyfillPackages,
   installTemporalGlobal,
   installTemporalLazyGlobal,
+  // The compiled preamble's lazy Temporal getter (compile-lazy-temporal.cjs)
+  // installs the value on first access without reading the global back.
+  installTemporalValue,
   restoreCompileCacheEnv,
   installCompiledChildProcess,
   reenableUserCompileCache,

package/transform-core.mjs

@@ -207,6 +207,20 @@ export const TRANSPILE_EXTS = new Set([".ts", ".tsx", ".mts", ".cts", ".jsx"]);
 // `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"]);
+// A bare `commonjs`/`module` format on a file nub would transpile can only have
+// been assigned by a hook layered ABOVE nub's. Node's resolver labels a `.ts` file
+// `commonjs-typescript`/`module-typescript` (or `typescript` when the package has
+// no `type`) and leaves `.jsx` unlabelled, and nub's own resolve returns no format;
+// the bare form is what tsx's resolve hook writes (getFormatFromFileUrl), and its
+// load hook then expects the RAW source back from `nextLoad` so it can run its own
+// module-format transform — a mixed `import` + `require` file becomes CJS there,
+// where nub's syntax detection would make it ESM and `require` undefined. Both
+// tiers step aside on this signal, the fast tier only once the user registration
+// is known to carry a load hook (preload-common.cjs). Plain JS is excluded: Node
+// assigns those the bare form itself.
+export function outerHookOwnsFormat(format, ext) {
+  return (format === "commonjs" || format === "module") && TRANSPILE_EXTS.has(ext) && !PLAIN_JS_EXTS.has(ext);
+}
 // The data loaders nub SHIPS — a runtime feature, not a project setting, so they stay
 // in force inside node_modules too (see dataExtsFor).
 const BUILTIN_DATA_EXTS = { ".jsonc": "jsonc", ".json5": "json5", ".toml": "toml", ".yaml": "yaml", ".yml": "yaml", ".txt": "txt" };
@@ -785,16 +799,145 @@ export function maybeSweepCache() {
     .catch(() => {});
 }
 
+// ── Runtime V8 flags (`Mitigation::RuntimeV8Flag`) ──────────────────
+// A V8 syntax flag nub does NOT put on argv. The Rust spawn layer names it in
+// `__NUB_RUNTIME_V8_FLAGS` (`<node-version> <flag>…`, flags.rs RUNTIME_V8_FLAGS_ENV)
+// and both load hooks route every result through `noteRuntimeV8FlagSource`, which
+// turns the flag on with `v8.setFlagsFromString` the first time a source uses the
+// syntax. V8 consults such a flag per parse (`v8_flags.js_defer_import_eval` is read
+// in the parser alone, with an empty bootstrapper hook) and Node runs V8 with
+// `--no-freeze-flags-after-init`, so a flip made before the hook returns is in force
+// when Node compiles that module — verified on 26.4.0 and 26.7.0, identical deferral
+// to the argv flag.
+//
+// What it buys: a V8 flag that is non-default at STARTUP enters V8's flag hash, and
+// the code cache Node embeds for its own internals is keyed on that hash, so every
+// builtin compiled after startup (`node:http`, `crypto`, `zlib`, …) is rejected and
+// rebuilt from source — ~20 ms for a program loading those, measured on 26.7.0. The
+// flip charges that only to a program that actually uses the syntax, and only for
+// the internals loaded after it. The flag also never appears in `process.execArgv`,
+// where forwarding it into a Worker once killed a Next.js 16 + Turbopack build.
+//
+// Every Nub launch sets or removes the var, so a child that re-enters Nub carries its
+// own decision; it is NOT deleted here, so a process that makes no such decision — a
+// Worker, the `module.register` loader worker, a child spawned by absolute path —
+// starts from a copy of this env and gets the feature too. Two guards close the gaps
+// inheritance leaves: a polarity already on this process's own `process.execArgv`
+// wins, either sign (V8 has the flag, or the user negated it, and the parent's signal
+// must not override that); and the version stamp makes a descendant on a different
+// Node (an inherited-NODE_OPTIONS grandchild) ignore a set computed for another
+// binary, because a flag V8 does not know is an "Error: unrecognized flag" on stderr.
+// `v8_flags` is process-global, so one flip from any thread serves every isolate.
+// Node documents a post-init flag change as unsupported; for a flag the parser reads
+// as one bool at the `import` token, the exposure is a benign race with a worker
+// parsing concurrently, which sees the old value for that one parse.
+//
+// Detection is textual. The static form is always `import defer * as` — V8 allows
+// `defer` with a namespace import only — so the pattern requires the `*`, which
+// keeps prose that merely names the two words (a comment, a docs string) from
+// arming the flag. Whitespace or comments between the tokens still match. A false
+// positive that survives (the three tokens inside a string) only recreates the
+// state every program had when the flag rode argv. The dynamic form
+// `import.defer()` is NOT matched, on purpose: it aborts the process on every 26.x
+// measured (a V8 fatal in Node's phase wiring), so a program that uses only that
+// form keeps bare Node's catchable SyntaxError.
+const TOKEN_GAP = String.raw`(?:\s|/\*[\s\S]*?\*/|//[^\n]*\n)`;
+const IMPORT_DEFER_RE = new RegExp(String.raw`\bimport${TOKEN_GAP}+defer${TOKEN_GAP}*\*`);
+const RUNTIME_V8_FLAG_DETECTORS = {
+  "--js-defer-import-eval": sourceUsesImportDefer,
+};
+// Formats whose source Node compiles as an ES module. `import defer` is module-only
+// syntax, so a CommonJS, JSON or wasm result can never need the flip; a null format
+// is still undecided and is scanned.
+const ESM_FORMATS = new Set(["module", "module-typescript", "typescript"]);
+
+// The source as a string, or null when a byte-level scan for `needle` misses — so a
+// file that cannot match is never decoded.
+function sourceText(source, needle) {
+  if (typeof source === "string") return source.includes(needle) ? source : null;
+  let buf = null;
+  if (ArrayBuffer.isView(source)) {
+    buf = Buffer.from(source.buffer, source.byteOffset, source.byteLength);
+  } else if (source instanceof ArrayBuffer) {
+    buf = Buffer.from(source);
+  }
+  return buf !== null && buf.includes(needle) ? buf.toString("utf8") : null;
+}
+
+// Whether `source` (string, Buffer, TypedArray or ArrayBuffer) carries a static
+// `import defer` declaration.
+export function sourceUsesImportDefer(source) {
+  const text = sourceText(source, "defer");
+  return text !== null && IMPORT_DEFER_RE.test(text);
+}
+
+// `-e`/`-p` code never passes through a load hook, so it is scanned once at
+// arm time: the preload runs before Node compiles the eval string.
+function evalSourceFromExecArgv(execArgv) {
+  if (!Array.isArray(execArgv)) return null;
+  for (let i = 0; i < execArgv.length; i++) {
+    const arg = execArgv[i];
+    if (typeof arg !== "string") continue;
+    if (arg === "-e" || arg === "--eval" || arg === "-p" || arg === "--print" || arg === "-pe" || arg === "-ep") {
+      return i + 1 < execArgv.length && typeof execArgv[i + 1] === "string" ? execArgv[i + 1] : null;
+    }
+    if (arg.startsWith("--eval=") || arg.startsWith("--print=")) return arg.slice(arg.indexOf("=") + 1);
+  }
+  return null;
+}
+
+// Flags still to turn on, or null once nothing is armed — the hot path is one null
+// check per load.
+let pendingRuntimeV8Flags = null;
+
+function turnOnRuntimeV8Flag(flag) {
+  pendingRuntimeV8Flags.delete(flag);
+  if (pendingRuntimeV8Flags.size === 0) pendingRuntimeV8Flags = null;
+  try {
+    __getBuiltin("node:v8").setFlagsFromString(flag);
+  } catch {
+    // The module then fails exactly as it would on bare Node.
+  }
+}
+
+// Route a load result through the runtime-flag scan and hand it back unchanged.
+export function noteRuntimeV8FlagSource(result) {
+  if (pendingRuntimeV8Flags === null || result == null || result.source == null) return result;
+  if (result.format != null && !ESM_FORMATS.has(result.format)) return result;
+  for (const flag of [...pendingRuntimeV8Flags]) {
+    if (RUNTIME_V8_FLAG_DETECTORS[flag](result.source)) turnOnRuntimeV8Flag(flag);
+  }
+  return result;
+}
+
+{
+  const raw = process.env.__NUB_RUNTIME_V8_FLAGS;
+  if (raw) {
+    const [stampedVersion, ...flags] = raw.split(" ").filter(Boolean);
+    const execArgv = Array.isArray(process.execArgv) ? process.execArgv : [];
+    const armed = stampedVersion === process.versions.node
+      ? flags.filter((flag) =>
+          Object.hasOwn(RUNTIME_V8_FLAG_DETECTORS, flag) &&
+          !execArgv.includes(flag) && !execArgv.includes(`--no-${flag.slice(2)}`))
+      : [];
+    if (armed.length > 0) {
+      pendingRuntimeV8Flags = new Set(armed);
+      const evalSource = evalSourceFromExecArgv(execArgv);
+      if (evalSource !== null) noteRuntimeV8FlagSource({ format: "module", source: evalSource });
+    }
+  }
+}
+
 // ── Transpile ───────────────────────────────────────────────────────
 // Transpile a TS/JSX file to JS, returning `{ format, source, shortCircuit }` in
 // the shape both hook tiers hand back to Node. Format is detected (not derived
 // from extension alone), so a CommonJS-syntax `.ts` is reported `commonjs` — the
 // fix that makes `require()` of a TS file work on the compat tier, where Node's
 // CJS translator loads it via this hook and keys on the returned format.
-export function loadTranspile(url, ext) {
+export function loadTranspile(url, ext, source) {
   __ensureBuiltins();
   const filePath = fileURLToPath(url);
-  const source = readFileSync(filePath, "utf8");
+  source ??= readFileSync(filePath, "utf8");
   const dir = dirname(filePath);
   // The transform-relevant compilerOptions slice + the byte-for-byte cache-key
   // component (`tsconfigHash`) both come from the native tsconfig reader.
@@ -878,7 +1021,15 @@ export function loadTranspile(url, ext) {
     const details = result.errors.map((e) => e.codeframe || e.message).join("\n\n");
     throw new Error(`Transpile error in ${filePath}:\n${details}`);
   }
-  return { format: result.format, source: result.code, shortCircuit: true };
+  // `responseURL` is what an OUTER user hook keys on. Node's default load sets it
+  // to the file URL, and tsx's load hook takes its CommonJS branch only when the
+  // result `nextLoad` hands back carries a `file:` responseURL — without it, tsx
+  // re-transformed a `.ts` file nub had already emitted as CJS in its ESM branch,
+  // and `require` was undefined at run time (`tsx script.ts` under `nub run`).
+  // Node itself defaults a missing responseURL to the URL, so only a hook layered
+  // above nub's can observe the difference; every file-URL result nub
+  // short-circuits carries it for that reason.
+  return { format: result.format, source: result.code, responseURL: url, shortCircuit: true };
 }
 
 // Project-source plain JS (`.js`/`.mjs`/`.cjs`) gate. Returns a transpiled load
@@ -895,7 +1046,7 @@ export function loadTranspile(url, ext) {
 // sites (the byte-parity boundary). JSX-in-`.js` is out of scope for the syntax
 // gate (lang is "ts", which does not parse JSX); use `.jsx`, or say so explicitly
 // with a `loader` entry, which takes the unconditional path below instead.
-export function maybeTranspilePlainJs(url, ext) {
+export function maybeTranspilePlainJs(url, ext, source) {
   __ensureBuiltins();
   // An explicit `loader` entry pointing this extension at a code dialect moved it
   // into TRANSPILE_EXTS, which for every other member means "always compile". Only
@@ -906,11 +1057,10 @@ export function maybeTranspilePlainJs(url, ext) {
   // while the ESM path transpiles the same file on both tiers. The registration
   // loop deliberately skips `.js`/`.cjs` because this wrapper owns them, so there
   // is nothing else downstream to catch it.
-  if (TRANSPILE_EXTS.has(ext)) return loadTranspile(url, ext);
+  if (TRANSPILE_EXTS.has(ext)) return loadTranspile(url, ext, source);
   const filePath = fileURLToPath(url);
-  let source;
   try {
-    source = readFileSync(filePath, "utf8");
+    source ??= readFileSync(filePath, "utf8");
   } catch {
     // Unreadable here → let Node's loader surface its own error.
     return null;
@@ -921,10 +1071,10 @@ export function maybeTranspilePlainJs(url, ext) {
     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.
+  // source maps, the Stage-3 decorator guard, format detection, cache), reusing
+  // the bytes already inspected by the gate.
   try {
-    return loadTranspile(url, ext);
+    return loadTranspile(url, ext, source);
   } catch (err) {
     // #225: a plain-JS file the transformable verdict flagged (a `using` decl or
     // `v`-flag RegExp somewhere) but whose transform oxc then REJECTS — V8 tolerates
@@ -998,7 +1148,7 @@ export function loadData(url, ext) {
   const parsed = dataValue(url, ext);
 
   if (parsed == null) {
-    return { format: "module", source: "export default undefined;\n", shortCircuit: true };
+    return { format: "module", source: "export default undefined;\n", responseURL: url, shortCircuit: true };
   }
 
   // Default export only. Data modules deliberately do NOT emit per-key named
@@ -1008,7 +1158,7 @@ export function loadData(url, ext) {
   // default — `import cfg from "./c.yaml"; const { host } = cfg;` — which the
   // `@nubjs/types` `Record<string, unknown>` default type makes sound.
   const code = `export default ${JSON.stringify(parsed)};\n`;
-  return { format: "module", source: code, shortCircuit: true };
+  return { format: "module", source: code, responseURL: url, shortCircuit: true };
 }
 
 // Import Text: `import s from "./any.file" with { type: "text" }` → the raw file
@@ -1024,5 +1174,5 @@ export function loadData(url, ext) {
 const __textDecoder = new TextDecoder();
 export function loadTextImport(url) {
   const text = __textDecoder.decode(readFileSync(fileURLToPath(url)));
-  return { format: "module", source: `export default ${JSON.stringify(text)};\n`, shortCircuit: true };
+  return { format: "module", source: `export default ${JSON.stringify(text)};\n`, responseURL: url, shortCircuit: true };
 }