@nubjs/nub-win32-arm64 0.0.4 → 0.0.7

package/runtime/preload.mjs

@@ -1,363 +1,317 @@
+// Nub fast-path preload — Node 22.15+ (sync `module.registerHooks`).
+//
+// This file is the main-thread `--import` preload for ALL tiers. It owns only
+// the tier-specific wiring; every resolution + transpile primitive lives in
+// runtime/transform-core.mjs (shared verbatim with the compat-tier loader
+// worker, so the two can never drift). What stays here:
+//   - watch-mode dependency IPC (main-thread only),
+//   - the thin resolve/load hooks that delegate to the core,
+//   - the main-thread CommonJS `require()` shim (Module._resolveFilename +
+//     require.extensions), installed on BOTH tiers — `module.register` hooks ESM
+//     but not require, and `module.registerHooks`' require coverage is incomplete
+//     before ~Node 24 (e.g. require-from-`.cts` on 22.15),
+//   - clobbered-polyfill preloading + the Temporal lazy global,
+//   - tier dispatch (registerHooks vs register).
+
 import module from "node:module";
-import { readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
+import { readdirSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
-import { createHash } from "node:crypto";
 import { join, dirname, resolve as pathResolve, extname as pathExtname } from "node:path";
-import { transformSync } from "oxc-transform";
-import { getTsconfig, createPathsMatcher } from "get-tsconfig";
+import {
+  TRANSPILE_EXTS, DATA_EXTS, TS_PARENT_EXTS,
+  extname, isNodeModules, getTsconfigForDir, getPackageType,
+  resolveSpec, resolveCjsPath, requireTargetIsEsm, loadTranspile, loadData,
+  maybeSweepCache, setWatchHooks, ensureParser,
+} from "./transform-core.mjs";
 
 const __require = createRequire(import.meta.url);
 
-// ── Constants ───────────────────────────────────────────────────────
-const TRANSPILE_EXTS = new Set([".ts", ".tsx", ".mts", ".cts", ".jsx"]);
-const DATA_EXTS = { ".jsonc": "jsonc", ".json5": "json5", ".toml": "toml", ".yaml": "yaml", ".yml": "yaml", ".txt": "txt" };
-const TS_PARENT_EXTS = new Set([".ts", ".tsx", ".mts", ".cts"]);
-
-// Nub's N-API addon for data-format parsing (Rust-native YAML/TOML/JSON5/JSONC).
-let nubNative = null;
-for (const rel of ["./addons/nub-native.node", "../runtime/addons/nub-native.node"]) {
-  try { nubNative = __require(fileURLToPath(new URL(rel, import.meta.url))); break; } catch {}
-}
-
-// Packages resolved from Nub's distribution, not the user's.
-const VENDORED_PACKAGES = new Set(["@oxc-project/runtime"]);
-
-// Built-in modules provided by Nub (resolved to files in this distribution).
-// connect() sockets deferred per design decision — "sockets" specifier not clobbered.
-const BUILTIN_MODULES = new Map();
-
-// Package clobbering: specifiers that resolve to a synthetic module
-// re-exporting the native global instead of the userland package.
-const CLOBBER_MAP = new Map([
-  ["@js-temporal/polyfill", () => `const T = globalThis.Temporal; export default T; export const Temporal = T;`],
-  ["urlpattern-polyfill", () => `export const URLPattern = globalThis.URLPattern;`],
-  ["abort-controller", () => `export const AbortController = globalThis.AbortController; export const AbortSignal = globalThis.AbortSignal; export default globalThis.AbortController;`],
-]);
-
-// ── tsconfig cache ──────────────────────────────────────────────────
-const tsconfigCache = new Map();
-
-function getTsconfigForDir(dir) {
-  if (tsconfigCache.has(dir)) return tsconfigCache.get(dir);
-  const result = getTsconfig(dir);
-  const matcher = result ? createPathsMatcher(result) : null;
-  const entry = { tsconfig: result, matcher };
-  tsconfigCache.set(dir, entry);
-  return entry;
+// ── Watch-mode dependency reporting ─────────────────────────────────
+// Under `nub watch`, Node's FilesWatcher only watches files in the import graph;
+// config files (tsconfig.json, package.json) and `.env*` are NOT in any graph,
+// so an edit to them otherwise goes stale. Node accepts incremental
+// `process.send({'watch:require': [...]})` over its WATCH_REPORT_DEPENDENCIES
+// IPC at ANY point in the child's life (it adds each path to the watch set), so
+// we report config paths AS the core loader discovers them. The reporters are
+// injected into the core via setWatchHooks (below) so getTsconfigForDir /
+// getPackageType self-report. The flush is coalesced via setImmediate.
+const WATCH_REPORTING = process.env.WATCH_REPORT_DEPENDENCIES === "1" && typeof process.send === "function";
+const watchReported = new Set();
+const watchPending = [];
+let watchFlushScheduled = false;
+function flushWatchDeps() {
+  watchFlushScheduled = false;
+  if (watchPending.length === 0) return;
+  const batch = watchPending.splice(0, watchPending.length);
+  try { process.send({ "watch:require": batch }); } catch {}
 }
-
-// ── Transpile cache ─────────────────────────────────────────────────
-const NUB_VERSION = "0.1.0";
-const CACHE_DISABLED = process.permission?.has !== undefined;
-let cacheDir = null;
-
-if (!CACHE_DISABLED) {
-  const base = process.env.XDG_CACHE_HOME || (process.env.HOME ? join(process.env.HOME, ".cache") : null);
-  if (base) {
-    cacheDir = join(base, "nub", "transpile");
-    try { mkdirSync(cacheDir, { recursive: true }); } catch { cacheDir = null; }
+function reportWatchDep(path) {
+  if (!WATCH_REPORTING || !path || watchReported.has(path)) return;
+  watchReported.add(path);
+  watchPending.push(path);
+  if (!watchFlushScheduled) {
+    watchFlushScheduled = true;
+    // A scheduled immediate is drained before the loop would exit, so even a
+    // script that finishes synchronously flushes its deps. (Don't unref: an
+    // unref'd immediate is skipped on a synchronous exit, dropping the report.)
+    setImmediate(flushWatchDeps);
   }
 }
-
-function cacheKey(source) {
-  return createHash("sha256").update(NUB_VERSION).update("\0").update(source).digest("hex");
-}
-function cacheGet(key) {
-  if (!cacheDir) return null;
-  const path = join(cacheDir, key);
-  const s = statSync(path, { throwIfNoEntry: false });
-  if (!s || !s.isFile()) return null;
-  return readFileSync(path, "utf8");
-}
-function cacheSet(key, value) {
-  if (!cacheDir) return;
-  try { writeFileSync(join(cacheDir, key), value); } catch {}
-}
-
-// ── Helpers ─────────────────────────────────────────────────────────
-function extname(url) {
-  const path = url.includes("?") ? url.slice(0, url.indexOf("?")) : url;
-  const dot = path.lastIndexOf(".");
-  return dot === -1 ? "" : path.slice(dot);
-}
-
-function isNodeModules(url) {
-  return url.includes("/node_modules/") || url.includes("\\node_modules\\");
-}
-
-function fileExists(filePath) {
-  const s = statSync(filePath, { throwIfNoEntry: false });
-  return s !== undefined && s.isFile();
-}
-
-function dirExists(filePath) {
-  const s = statSync(filePath, { throwIfNoEntry: false });
-  return s !== undefined && s.isDirectory();
-}
-
-function safeRequireResolve(specifier) {
-  try { return __require.resolve(specifier); } catch { return null; }
+// Report a directory's `.env*` files (the natural watch targets). Scanned once
+// per directory, lazily.
+const watchEnvScannedDirs = new Set();
+function reportEnvFilesIn(dir) {
+  if (!WATCH_REPORTING || watchEnvScannedDirs.has(dir)) return;
+  watchEnvScannedDirs.add(dir);
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+  for (const name of entries) {
+    if (name === ".env" || name.startsWith(".env.")) reportWatchDep(join(dir, name));
+  }
 }
+setWatchHooks({ reportDep: reportWatchDep, reportEnvDir: reportEnvFilesIn });
 
-function barePkg(specifier) {
-  return specifier.startsWith("@")
-    ? specifier.split("/").slice(0, 2).join("/")
-    : specifier.split("/")[0];
-}
+// Best-effort bounded-cache eviction (main thread only; the core guards on it).
+maybeSweepCache();
 
 // ── Resolve hook ────────────────────────────────────────────────────
 function resolve(specifier, context, nextResolve) {
-  // Skip node: and data: protocols.
-  if (specifier.startsWith("node:") || specifier.startsWith("data:")) {
-    return nextResolve(specifier, context);
-  }
-
-  // Skip Node built-in module names (without node: prefix).
-  if (module.builtinModules.includes(specifier)) {
-    return nextResolve(specifier, context);
-  }
-
-  // 1. Built-in modules provided by Nub.
-  if (BUILTIN_MODULES.has(specifier)) {
-    return { url: BUILTIN_MODULES.get(specifier), shortCircuit: true };
-  }
-
-  // 2. Vendored packages (e.g. @oxc-project/runtime).
-  const bare = barePkg(specifier);
-  if (VENDORED_PACKAGES.has(bare)) {
-    const resolved = safeRequireResolve(specifier);
-    if (resolved) return { url: pathToFileURL(resolved).href, shortCircuit: true };
-  }
-
-  // 2. Package clobbering.
-  if (CLOBBER_MAP.has(bare) && !isNodeModules(context.parentURL || "")) {
-    return { url: `data:text/javascript,${encodeURIComponent(CLOBBER_MAP.get(bare)())}`, shortCircuit: true };
-  }
-
-  // 3. tsconfig-paths (only for bare/aliased specifiers, not relative).
-  const parentURL = String(context.parentURL || "");
-  const parentExt = extname(parentURL);
-  if (!specifier.startsWith(".") && !specifier.startsWith("/") && !specifier.startsWith("file:") && !isNodeModules(parentURL)) {
-    const parentDir = parentURL.startsWith("file:") ? dirname(fileURLToPath(parentURL)) : process.cwd();
-    const { matcher } = getTsconfigForDir(parentDir);
-    if (matcher) {
-      const mapped = matcher(specifier);
-      if (mapped && mapped.length > 0) {
-        for (const candidate of mapped) {
-          const resolved = tryResolveFile(candidate, parentExt);
-          if (resolved) {
-            return { url: pathToFileURL(resolved).href, shortCircuit: true };
-          }
-        }
-      }
-    }
-  }
-
-  // 4. Extensionless probing (only when parent is a TS file).
-  if (TS_PARENT_EXTS.has(parentExt) && (specifier.startsWith("./") || specifier.startsWith("../"))) {
-    const parentDir = dirname(fileURLToPath(parentURL));
-    const target = pathResolve(parentDir, specifier);
-    const resolved = tryResolveFile(target, parentExt);
-    if (resolved) {
-      return { url: pathToFileURL(resolved).href, shortCircuit: true };
-    }
-  }
-
-  return nextResolve(specifier, context);
-}
-
-// Try to resolve a file path with extensionless probing + .js→.ts swap.
-function tryResolveFile(target, parentExt) {
-  // If the target already has an extension and exists, use it.
-  const existingExt = pathExtname(target);
-  if (existingExt && fileExists(target)) return target;
-
-  // .js → .ts swap (tsc emit convention reversal).
-  if (existingExt === ".js") {
-    const tsSwap = target.slice(0, -3) + ".ts";
-    if (fileExists(tsSwap)) return tsSwap;
-    const tsxSwap = target.slice(0, -3) + ".tsx";
-    if (fileExists(tsxSwap)) return tsxSwap;
-  }
-  if (existingExt === ".jsx") {
-    const tsxSwap = target.slice(0, -4) + ".tsx";
-    if (fileExists(tsxSwap)) return tsxSwap;
-  }
-  // .mjs → .mts swap (Bun does this).
-  if (existingExt === ".mjs") {
-    const mtsSwap = target.slice(0, -4) + ".mts";
-    if (fileExists(mtsSwap)) return mtsSwap;
-  }
-
-  // Extensionless: probe in parent-ext-aware order.
-  if (!existingExt) {
-    const probeOrder = getProbeOrder(parentExt);
-    for (const ext of probeOrder) {
-      if (fileExists(target + ext)) return target + ext;
-    }
-    // Directory index probing.
-    if (dirExists(target)) {
-      for (const ext of probeOrder) {
-        const idx = join(target, "index" + ext);
-        if (fileExists(idx)) return idx;
-      }
-    }
-  }
-
-  return null;
-}
-
-function getProbeOrder(parentExt) {
-  switch (parentExt) {
-    case ".tsx": return [".tsx", ".ts", ".jsx", ".js", ".json"];
-    case ".mts": return [".mts", ".mjs"];
-    case ".cts": return [".cts", ".cjs"];
-    default:     return [".ts", ".tsx", ".js", ".jsx", ".json"];
-  }
+  const r = resolveSpec(specifier, context.parentURL);
+  return r ?? nextResolve(specifier, context);
 }
 
 // ── Load hook ───────────────────────────────────────────────────────
 function load(url, context, nextLoad) {
   const ext = extname(url);
 
+  // Watch mode: surface this file's nearest config files (tsconfig.json,
+  // package.json) + sibling `.env*` so edits to them restart the run. Done for
+  // every user file (not just transpiled ones) — getTsconfigForDir/getPackageType
+  // self-report via the injected watch hooks.
+  if (WATCH_REPORTING && url.startsWith("file:") && !isNodeModules(url)) {
+    try {
+      const dir = dirname(fileURLToPath(url));
+      getTsconfigForDir(dir);
+      getPackageType(dir);
+    } catch {}
+  }
+
   if (TRANSPILE_EXTS.has(ext)) return loadTranspile(url, ext);
   if (ext in DATA_EXTS) return loadData(url, ext);
 
   return nextLoad(url, context);
 }
 
-function loadTranspile(url, ext) {
-  const filePath = fileURLToPath(url);
-  const source = readFileSync(filePath, "utf8");
-  const dir = dirname(filePath);
-  const { tsconfig } = getTsconfigForDir(dir);
-  const co = tsconfig?.config?.compilerOptions;
-
-  // Cache key includes tsconfig compilerOptions so tsconfig changes invalidate.
-  const tsconfigHash = co ? JSON.stringify(co) : "";
-  const key = cacheKey(source + "\0" + ext + "\0" + tsconfigHash);
-  const cached = cacheGet(key);
-  if (cached) {
-    return { format: ext === ".cts" ? "commonjs" : "module", source: cached, shortCircuit: true };
-  }
-
-  const lang = ext === ".tsx" ? "tsx" : ext === ".jsx" ? "jsx" : "ts";
-  const opts = {
-    lang,
-    sourceType: ext === ".cts" ? "commonjs" : "module",
-    sourcemap: true,
-    typescript: {},
-    decorator: co?.experimentalDecorators !== false
-      ? { legacy: true, emitDecoratorMetadata: co?.emitDecoratorMetadata !== false }
-      : undefined,
-  };
-  if (ext === ".tsx" || ext === ".jsx") {
-    opts.jsx = {
-      runtime: co?.jsx === "react" ? "classic" : "automatic",
-      importSource: co?.jsxImportSource || "react",
-    };
-    if (co?.jsxFactory) opts.jsx.pragma = co.jsxFactory;
-    if (co?.jsxFragmentFactory) opts.jsx.pragmaFrag = co.jsxFragmentFactory;
-  }
-
-  const result = transformSync(filePath, source, opts);
-  if (result.errors.length > 0) {
-    const details = result.errors.map((e) => e.codeframe || e.message).join("\n\n");
-    throw new Error(`Transpile error in ${filePath}:\n${details}`);
-  }
-
-  let code = result.code;
-  if (result.map) {
-    const map = typeof result.map === "string" ? JSON.parse(result.map) : result.map;
-    map.sourcesContent = [source];
-    code += `\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(JSON.stringify(map)).toString("base64")}\n`;
-  }
-
-  cacheSet(key, code);
-  return { format: ext === ".cts" ? "commonjs" : "module", source: code, shortCircuit: true };
+// ── CommonJS require() augmentation (BOTH tiers) ────────────────────
+// `module.registerHooks`' CJS-`require()` coverage is INCOMPLETE before ~Node 24:
+// on Node 22.15 a `require()` from a `.cts` parent (which Node loads via the ESM
+// translator's special-require) hits native Module._resolveFilename with no
+// tsconfig/extensionless handling — a `require('@alias')` or `require('./x')` of a
+// `.ts` target throws MODULE_NOT_FOUND, while the same code works on Node 26 (where
+// registerHooks does cover it) and on the fast `import` path. On the compat tier
+// (18.19–22.14) the only hook surface is `module.register`, which intercepts the
+// ESM loader ONLY — so `require()` is entirely unaugmented there. Both gaps have
+// the same closure: install this main-thread CJS shim, reusing the core's canonical
+// resolveCjsPath / loadTranspile (no drift). It tries nub's resolution first and
+// FALLS THROUGH to native on a miss, so it is a safe no-op on the versions where
+// registerHooks already covers require (Node 24+/26). Mechanism stays within the
+// augmenter rules: exactly what `--require`-installing the ts-node / tsx CJS shim
+// has always done. So it runs on the fast tier too — registerHooks is necessary
+// but, below ~Node 24, not sufficient for require().
+// This error is surfaced ONLY on Node versions without native require(esm)
+// (< 20.19 / 22.0–22.11), where require() of an ES module genuinely cannot work.
+// On every require(esm)-capable Node, Node loads the ES module itself and this is
+// never reached. The message is user-facing: no internal mechanism names.
+function requireEsmError(filename) {
+  const err = new Error(
+    `Cannot require() this file — it is an ES module.\n` +
+    `  ${filename}\n` +
+    `It uses \`import\`/\`export\`, so it loads as an ES module, and this version of ` +
+    `Node can't require() an ES module. Load it with \`import(...)\` instead, rename ` +
+    `it to .cts for a CommonJS module, or upgrade Node.`,
+  );
+  err.code = "ERR_REQUIRE_ESM";
+  return err;
 }
 
-function loadData(url, ext) {
-  const filePath = fileURLToPath(url);
-  const raw = readFileSync(filePath, "utf8");
-  const kind = DATA_EXTS[ext];
-
-  if (kind === "txt") {
-    return { format: "module", source: `export default ${JSON.stringify(raw)};\n`, shortCircuit: true };
-  }
-
-  let parsed;
-  if (nubNative) {
-    if (kind === "yaml") parsed = nubNative.parseYaml(raw);
-    else if (kind === "toml") parsed = nubNative.parseToml(raw);
-    else if (kind === "json5") parsed = nubNative.parseJson5(raw);
-    else if (kind === "jsonc") parsed = nubNative.parseJsonc(raw);
-  } else {
-    if (kind === "yaml") parsed = lazyRequire("yaml").parse(raw);
-    else if (kind === "toml") parsed = lazyRequire("@iarna/toml").parse(raw);
-    else if (kind === "json5") parsed = lazyRequire("json5").parse(raw);
-    else if (kind === "jsonc") parsed = JSON.parse(stripJsonComments(raw));
-  }
-
-  if (parsed == null) {
-    return { format: "module", source: "export default undefined;\n", shortCircuit: true };
-  }
-
-  let code = `const _data = ${JSON.stringify(parsed)};\nexport default _data;\n`;
-  if (typeof parsed === "object" && !Array.isArray(parsed)) {
-    for (const key of Object.keys(parsed)) {
-      if (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)) {
-        code += `export const ${key} = _data[${JSON.stringify(key)}];\n`;
+// `withClassicTranspile` — also install the `require.extensions` (classic CommonJS
+// loader) transpile hook. This is needed ONLY on Node WITHOUT native require(esm)
+// (< 20.19 / 22.0–22.11): there, `module.register`'s ESM-loader hooks can't reach a
+// `require()`, AND an ES module simply can't be require()d, so we transpile CJS
+// content classically and surface a clean error for ESM content. On require(esm)-
+// capable Node we DON'T install it — registering `require.extensions['.ts']` would
+// shadow Node's own native require(esm) of ES-module `.ts` files (breaking
+// `require("./esm.ts")`), and the resolve shim below plus the tier's load hook
+// already cover resolution + transpile.
+function installCjsRequireHooks(withClassicTranspile) {
+  // Module._resolveFilename: try nub's resolution first (tsconfig paths,
+  // extensionless .ts, .js→.ts). If the target is an ES-module TS file AND this
+  // Node can't require(esm), throw a clean error HERE — before Node's special-
+  // require (used for require() from a CJS module loaded via the ESM translator)
+  // crashes with an opaque `cjsCache.get(...)` TypeError. On require(esm)-capable
+  // Node, return the path and let Node load the ES module itself. On miss/own
+  // error, fall through to Node (augmentation never masks Node's diagnostics).
+  const origResolveFilename = module._resolveFilename;
+  module._resolveFilename = function (request, parent, isMain, options) {
+    let resolved = null;
+    try {
+      const parentPath = parent && typeof parent.filename === "string" ? parent.filename : null;
+      resolved = resolveCjsPath(request, parentPath);
+    } catch { /* fall through to Node */ }
+    if (resolved) {
+      if (withClassicTranspile && requireTargetIsEsm(resolved, pathExtname(resolved))) {
+        throw requireEsmError(resolved);
       }
+      return resolved;
     }
-  }
-  return { format: "module", source: code, shortCircuit: true };
-}
-
-function lazyRequire(pkg) {
-  try { return __require(pkg); } catch {
-    throw new Error(`Nub: importing this file requires the "${pkg}" package.\nInstall it: npm install ${pkg}`);
-  }
-}
+    return origResolveFilename.call(this, request, parent, isMain, options);
+  };
 
-function stripJsonComments(text) {
-  let result = "", i = 0, inString = false, escape = false;
-  while (i < text.length) {
-    const ch = text[i];
-    if (escape) { result += ch; escape = false; i++; continue; }
-    if (inString) { if (ch === "\\") escape = true; if (ch === '"') inString = false; result += ch; i++; continue; }
-    if (ch === '"') { inString = true; result += ch; i++; continue; }
-    if (ch === "/" && text[i + 1] === "/") { while (i < text.length && text[i] !== "\n") i++; continue; }
-    if (ch === "/" && text[i + 1] === "*") { i += 2; while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++; i += 2; continue; }
-    result += ch; i++;
+  if (!withClassicTranspile) return;
+
+  // require.extensions: transpile via the SAME loadTranspile the load hook uses —
+  // target:'es2022' lowering (`using`), tsconfig, source maps, the Stage-3
+  // decorator guard, and module-format detection are all identical to the fast
+  // tier. The path is already a real TS file (Module._resolveFilename ran first).
+  // A module-format source can't be _compile'd as CJS — same clean error as above.
+  const transpileExtension = (mod, filename) => {
+    const { source, format } = loadTranspile(pathToFileURL(filename).href, pathExtname(filename));
+    if (format === "module") throw requireEsmError(filename);
+    mod._compile(source, filename);
+  };
+  for (const ext of [".ts", ".cts", ".mts", ".tsx", ".jsx"]) {
+    module._extensions[ext] = transpileExtension;
   }
-  return result;
 }
 
 // ── Pre-load clobbered polyfill packages BEFORE hooks register ──────
-// Packages in CLOBBER_MAP can't be imported after hooks register because
-// the resolve hook returns a synthetic module instead of the real package.
-// Load them here via CJS require (which isn't yet hooked) and stash them.
+// Packages in the core's CLOBBER_MAP can't be imported after hooks register
+// because the resolve hook returns a synthetic module instead of the real
+// package. Load them here via CJS require (not yet hooked) and stash them.
+// Temporal is the exception (A37): the polyfill is ~18ms to load and most scripts
+// never touch it, so we only RESOLVE its path now (cheap) and defer the load to a
+// lazy global getter (below). Requiring it later by absolute path bypasses the
+// CLOBBER_MAP resolve-hook entry, which keys on the "@js-temporal/polyfill"
+// specifier — not the resolved path.
 const __preloadedPolyfills = {};
-try { __preloadedPolyfills.temporal = __require("@js-temporal/polyfill"); } catch {}
-try { __preloadedPolyfills.urlpattern = __require("urlpattern-polyfill"); } catch {}
-
-// ── Register hooks ──────────────────────────────────────────────────
-module.registerHooks({ resolve, load });
+// Feature-detect before requiring (A39): URLPattern is native on Node 24+, so
+// skip loading the polyfill there. On 22.x it's absent → load it.
+if (typeof globalThis.URLPattern === "undefined") {
+  try { __preloadedPolyfills.urlpattern = __require("urlpattern-polyfill"); } catch {}
+}
+// Float16Array: native on Node 24+, absent on the 22.x floor.
+if (typeof globalThis.Float16Array === "undefined") {
+  try { __preloadedPolyfills.float16 = __require("@petamoriken/float16"); } catch {}
+}
+let __temporalPath;
+try { __temporalPath = __require.resolve("@js-temporal/polyfill"); } catch {}
+
+// ── Tier dispatch ───────────────────────────────────────────────────
+// Three tiers per wiki/research/supported-node-versions.md:
+//   - >= 22.15.0:         sync module.registerHooks (fast path, in-thread)
+//   - >= 18.19.0 < 22.15: async module.register (loader worker) + main-thread
+//                         CJS require() shim (module.register is ESM-only)
+//   - <  18.19.0:         unsupported (Rust spawn path hard-errors; defensive log)
+//
+// No user-visible distinction between the two augmentation tiers — both deliver
+// the identical feature surface, silently. The compat-mode notice was dropped
+// 2026-05-29 (it labeled a purely internal mechanism choice).
+const __nodeVersionParts = process.versions.node.split(".").map((n) => parseInt(n, 10));
+const __nodeMajor = __nodeVersionParts[0] || 0;
+const __nodeMinor = __nodeVersionParts[1] || 0;
+const __isAugmentedTier = __nodeMajor > 22 || (__nodeMajor === 22 && __nodeMinor >= 15);
+const __isCompatTier = !__isAugmentedTier && (__nodeMajor > 18 || (__nodeMajor === 18 && __nodeMinor >= 19));
+// Native TypeScript support (`process.features.typescript` is "strip"/"transform"
+// — Node 22.18+/24+). Where present, Node loads `.ts` from require() itself,
+// INCLUDING ES-module `.ts` via native require(esm); registering the classic
+// `require.extensions['.ts']` shim there would shadow that and break
+// `require("./esm.ts")`. Where absent (≤ 22.17 / the whole compat tier), Node can't
+// load a required `.ts` on its own, so the shim is required — it transpiles CJS
+// content and surfaces a clean error for ES-module content (which require() can't
+// load there anyway). Feature-detected, not version-gated.
+const __hasNativeTs = !!process.features?.typescript;
+
+if (__isAugmentedTier) {
+  // Fast path: sync, in-thread hooks. Same realm as user code; covers `import` and
+  // (Node 24+) `require`. registerHooks' require RESOLUTION is incomplete on
+  // 22.15–24, so also install the main-thread resolve shim. Install the classic
+  // require.extensions transpile shim only on 22.15–22.17 (no native `.ts`); on
+  // 22.18+/24+ skip it so Node's native require() of `.ts` — incl. ES modules —
+  // isn't shadowed (see installCjsRequireHooks).
+  module.registerHooks({ resolve, load });
+  installCjsRequireHooks(!__hasNativeTs);
+} else if (__isCompatTier) {
+  // Compat path: ESM `import` hooks run in a dedicated loader worker thread.
+  module.register("./preload-async-hooks.mjs", import.meta.url);
+  // The main-thread CommonJS require() shim's format detection is synchronous and
+  // reaches down to Node 18.19, where `require("oxc-parser")` (ESM-only) fails —
+  // so preload the parser via dynamic import now, while we can still await.
+  await ensureParser();
+  // module.register() is ESM-loader-only; augment CommonJS require() on the main
+  // thread too. The compat tier never has native `.ts`, so it always installs the
+  // classic transpile shim (CJS transpile + clean error for ES-module require()).
+  installCjsRequireHooks(!__hasNativeTs);
+} else {
+  // Defensive: Rust spawn path hard-errors on < 18.19 before reaching here. If
+  // invoked directly via `node --import`, emit a clear message and skip hook
+  // registration rather than throw (throwing breaks user-invoked --import flows).
+  process.stderr.write(
+    `Nub requires Node 18.19 or newer for runtime augmentation; got ${process.versions.node}. Preload is inactive.\n`,
+  );
+}
 
-// ── Polyfill preloads ───────────────────────────────────────────────
+// ── Polyfill preloads (tier-independent) ────────────────────────────
+// Polyfills install identically on both augmented and compat paths.
 globalThis.__nubPreloaded = __preloadedPolyfills;
 await import("./polyfills.mjs");
 delete globalThis.__nubPreloaded;
-delete globalThis.__nubRequire;
-delete globalThis.__nubRequire;
 
-// ── Watch-mode dependency reporting ─────────────────────────────────
-if (process.env.WATCH_REPORT_DEPENDENCIES === "1" && process.send) {
-  const deps = [];
-  for (const [, entry] of tsconfigCache) {
-    if (entry.tsconfig?.path) deps.push(entry.tsconfig.path);
-  }
-  if (deps.length > 0) process.send({ "watch:require": deps });
+// ── Temporal: lazy global (A37) ─────────────────────────────────────
+// Temporal ships in no supported Node, so nub always provides it — but the
+// polyfill is ~18ms to load and rarely used, so install a lazy getter that loads
+// it (by resolved path, bypassing the clobber) on first access. The CLOBBER
+// re-export of `import "@js-temporal/polyfill"` reads globalThis.Temporal, so a
+// user importing the package triggers this same one-time load. A plain assignment
+// (`globalThis.Temporal = …`) replaces the accessor with the value.
+if (typeof globalThis.Temporal === "undefined" && __temporalPath) {
+  const defineTemporal = (value) =>
+    Object.defineProperty(globalThis, "Temporal", {
+      value,
+      configurable: true,
+      writable: true,
+      enumerable: false,
+    });
+  Object.defineProperty(globalThis, "Temporal", {
+    configurable: true,
+    enumerable: false,
+    get() {
+      const polyfill = __require(__temporalPath);
+      // @js-temporal/polyfill exports `toTemporalInstant` as a function but does
+      // NOT auto-install it on Date.prototype (you assign it yourself). Install it
+      // here so that on the floor (no native Temporal) `date.toTemporalInstant()`
+      // AND the package clobber's re-export of `Date.prototype.toTemporalInstant`
+      // both work — matching native Node. Guarded so we never replace a native
+      // implementation on a runtime that ships Temporal.
+      if (
+        typeof Date.prototype.toTemporalInstant !== "function" &&
+        typeof polyfill.toTemporalInstant === "function"
+      ) {
+        Object.defineProperty(Date.prototype, "toTemporalInstant", {
+          value: polyfill.toTemporalInstant,
+          configurable: true,
+          writable: true,
+          enumerable: false,
+        });
+      }
+      const T = polyfill.Temporal;
+      defineTemporal(T);
+      return T;
+    },
+    set: defineTemporal,
+  });
 }
+
+// Watch-mode dependency reporting is incremental — see reportWatchDep + the
+// injected core hooks. Config deps are reported as the loader discovers each user
+// file, plus their `.env*` siblings.