@nubjs/loader 0.0.0 → 0.8.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nub contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,48 @@
-Placeholder — the Nub loader ships here with the next Nub release. See https://github.com/nubjs/nub.
+# @nubjs/loader
+
+Standalone TypeScript loader for Node.js, from the [Nub](https://nubjs.com) project. Register it the way tsx or ts-node is registered, and TypeScript works in `import`, in `require()`, and in worker threads — powered by the same native oxc-based transform the Nub CLI uses.
+
+```sh
+npm install --save-dev @nubjs/loader
+node --import @nubjs/loader app.ts
+```
+
+Any way Node accepts a preload works:
+
+```sh
+node --import @nubjs/loader app.ts          # one run
+NODE_OPTIONS="--import @nubjs/loader" vitest # tools that spawn node themselves
+node --require @nubjs/loader app.ts          # CommonJS delivery (see below)
+```
+
+## What it does
+
+- Transpiles `.ts` / `.tsx` / `.mts` / `.cts` / `.jsx` on the fly — full TypeScript, including enums, namespaces, and legacy decorators, not just type stripping.
+- Resolves TypeScript conventions: tsconfig `paths` and `baseUrl`, extensionless imports, the `.js` → `.ts` emit-convention swap, directory index files.
+- Augments CommonJS `require()` with the same resolution and transpile, not only `import`.
+- Loads data formats as modules: `.yaml`, `.toml`, `.json5`, `.jsonc`, `.txt`, and `with { type: "text" }` imports.
+- Lowers `using` / `await using` and other syntax newer than the running Node.
+- Inline source maps, on for every transpiled file.
+- Applies inside worker threads automatically (Node inherits the preload).
+
+Dependencies under `node_modules` are never transpiled, and files Node handles natively load byte-for-byte unchanged — the loader adds behavior, it does not modify Node's.
+
+## Entry points
+
+```sh
+node --import @nubjs/loader app.ts        # ESM hooks + CommonJS require() augmentation
+node --require @nubjs/loader app.ts       # same, delivered as a CommonJS preload (Node 20.19+)
+node --import @nubjs/loader/esm app.ts    # ESM hooks only
+```
+
+Module formats follow Node's own rules: a `.cts` file is CommonJS and a `.mts` file is an ES module, and the loader transpiles types and syntax without converting one format into the other.
+
+## Node support
+
+Node 18.19 and newer. On Node 22.15+ hooks register synchronously in-thread (`module.registerHooks`); older versions run them in Node's loader worker (`module.register`). The `--require` delivery needs `require(esm)` (Node 20.19+ / 22.12+); below that use `--import`.
+
+## Relationship to the Nub CLI
+
+The [`@nubjs/nub`](https://www.npmjs.com/package/@nubjs/nub) CLI is a complete TypeScript-first toolchain — runner, package manager, Node version management — and does everything this loader does without any flags. This package is the loader alone, for cases where the `node` invocation itself is fixed: existing tooling, test runners, other CLIs that spawn `node`.
+
+Platform binaries ship as `optionalDependencies` (`@nubjs/loader-*`) for macOS, Linux (glibc and musl), and Windows, on x64 and arm64.

package/cache-evict.mjs

@@ -0,0 +1,180 @@
+// Bounded-size eviction for the transpile cache (A16). Kept in its own module
+// so it loads lazily — only when a sweep is actually due (see preload.mjs's
+// throttled maybeSweepCache) — and so it can be tested in isolation.
+//
+// LRU by mtime: when the cache exceeds `maxBytes`, delete oldest-written entries
+// until at or below `lowWater`. Entries are content-addressed, so evicting one
+// only costs a re-transpile on next use. mtime reflects write time, not last
+// read — true read-LRU would need an mtime touch on every cache hit, defeating
+// the read-only fast path; oldest-written is the right, cheap proxy for a cache
+// whose entries are written once per source version.
+
+// NO STATIC `node:` IMPORTS. This module is reached by an UNAWAITED dynamic
+// `import()` from the deferred sweep, so its import graph is in flight while the
+// user's entry is still loading. On Node 20.10–20.18 a PENDING builtin job in the
+// ESM loadCache makes a transpiled CommonJS entry's synchronous `require()` of the
+// same builtin take the ESM translator's sync path (getModuleJobSync → runSync) and
+// trip `assert(this.module instanceof ModuleWrap)` — ERR_INTERNAL_ASSERTION, ~25% of
+// runs (#706). Fetching the builtins synchronously never enters the ESM loader, so
+// no job exists for user code to collide with.
+let readdirSync, rmdirSync, statSync, unlinkSync, join;
+let _getBuiltin = null;
+
+/**
+ * Thread in a synchronous builtin getter. Required below Node 22.3, where
+ * `process.getBuiltinModule` does not exist — transform-core hands over the same
+ * getter it uses itself (createRequire-backed on the floor).
+ */
+export function setBuiltinGetter(fn) {
+  _getBuiltin = fn;
+}
+
+function ensureBuiltins() {
+  if (readdirSync) return;
+  const get = _getBuiltin || ((id) => process.getBuiltinModule(id));
+  ({ readdirSync, rmdirSync, statSync, unlinkSync } = get("node:fs"));
+  ({ join } = get("node:path"));
+}
+
+// A valid cache entry is a 64-char lowercase-hex sha256 (see cacheKey in
+// preload.mjs). Everything else — the `.sweep` sentinel, `*.tmp` in-flight
+// writes from cacheSet — is skipped: never counted toward the cap, never
+// evicted.
+const ENTRY_RE = /^[0-9a-f]{64}$/;
+
+// What one entry actually costs the filesystem. `stat.size` is the LOGICAL
+// length, but the disk hands out whole blocks, and this cache is mostly small
+// files — measured on a real 32k-entry cache: 45% of entries sat under one 4 KiB
+// block, so 492.6 MB of logical bytes occupied 571.0 MB of disk, and a nominal
+// 512 MiB cap silently permitted ~594 MB. `blocks` is POSIX (512-byte units);
+// Windows does not report it, so fall back to the logical size there.
+function diskBytes(s) {
+  return typeof s.blocks === "number" && s.blocks > 0 ? s.blocks * 512 : s.size;
+}
+
+/**
+ * Evict oldest entries from `dir` until total entry bytes ≤ `lowWater`, if they
+ * exceed `maxBytes`. Sizes are the entries' real on-disk footprint, so the cap
+ * bounds what the user's disk actually loses. Returns `{ scanned, deleted, freed }`.
+ * Best-effort: a stat or unlink that fails (concurrent reader/evictor, Windows
+ * open handle) is skipped, and the next sweep retries. Never throws.
+ */
+export function sweepCache(dir, maxBytes, lowWater = Math.floor(maxBytes * 0.75)) {
+  ensureBuiltins();
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return { scanned: 0, deleted: 0, freed: 0 };
+  }
+
+  const entries = [];
+  let total = 0;
+  for (const name of names) {
+    if (!ENTRY_RE.test(name)) continue;
+    const path = join(dir, name);
+    const s = statSync(path, { throwIfNoEntry: false });
+    if (!s || !s.isFile()) continue;
+    const size = diskBytes(s);
+    entries.push({ path, size, mtime: s.mtimeMs });
+    total += size;
+  }
+
+  if (total <= maxBytes) {
+    return { scanned: entries.length, deleted: 0, freed: 0 };
+  }
+
+  // Oldest first; delete down to the low-water mark so we don't sweep again on
+  // the very next write.
+  entries.sort((a, b) => a.mtime - b.mtime);
+  let deleted = 0;
+  let freed = 0;
+  for (const e of entries) {
+    if (total <= lowWater) break;
+    try {
+      unlinkSync(e.path);
+      total -= e.size;
+      freed += e.size;
+      deleted++;
+    } catch {
+      // Already removed by a concurrent sweep, or held open (Windows): skip.
+      // `total` is unchanged so we keep trying to reach lowWater via other
+      // entries; the loop is bounded by `entries`, so it still terminates.
+    }
+  }
+  return { scanned: entries.length, deleted, freed };
+}
+
+/**
+ * Evict from nub's OWN default V8 compile-cache dir. The layout there is Node's,
+ * not ours — `<dir>/<version>-<arch>-<hash>-<uid>/<entry>` — so this walks one
+ * level down, treats every regular file as an entry (V8 picks the names; there
+ * is no pattern of ours to match), and prunes a version directory once eviction
+ * has emptied it. Those version directories are the quiet half of the problem:
+ * one accumulates per Node build ever run under nub and nothing removed it, so a
+ * working machine had 96 of them totalling 6.9 GB across ~594k files.
+ *
+ * Deleting a live entry is safe: a missing or unreadable code-cache entry only
+ * makes V8 recompile that module. Same oldest-first, delete-to-`lowWater` policy
+ * and the same never-throws contract as `sweepCache`.
+ */
+export function sweepCompileCache(dir, maxBytes, lowWater = Math.floor(maxBytes * 0.75)) {
+  ensureBuiltins();
+  let versionDirs;
+  try {
+    versionDirs = readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory());
+  } catch {
+    return { scanned: 0, deleted: 0, freed: 0 };
+  }
+
+  const entries = [];
+  let total = 0;
+  for (const vd of versionDirs) {
+    const vpath = join(dir, vd.name);
+    let names;
+    try {
+      names = readdirSync(vpath);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      const path = join(vpath, name);
+      const s = statSync(path, { throwIfNoEntry: false });
+      if (!s || !s.isFile()) continue;
+      const size = diskBytes(s);
+      entries.push({ path, size, mtime: s.mtimeMs });
+      total += size;
+    }
+  }
+
+  if (total <= maxBytes) {
+    return { scanned: entries.length, deleted: 0, freed: 0 };
+  }
+
+  entries.sort((a, b) => a.mtime - b.mtime);
+  let deleted = 0;
+  let freed = 0;
+  for (const e of entries) {
+    if (total <= lowWater) break;
+    try {
+      unlinkSync(e.path);
+      total -= e.size;
+      freed += e.size;
+      deleted++;
+    } catch {
+      // Concurrent sweep or an open handle (Windows): skip, retried next sweep.
+    }
+  }
+
+  // `rmdir` refuses a non-empty directory, so this can only ever remove one the
+  // eviction above actually emptied — never a version dir still holding entries.
+  for (const vd of versionDirs) {
+    try {
+      rmdirSync(join(dir, vd.name));
+    } catch {
+      // Still populated, or in use by a concurrent run.
+    }
+  }
+
+  return { scanned: entries.length, deleted, freed };
+}

package/floor-builtin.mjs

@@ -0,0 +1,57 @@
+// Compat-tier floor bootstrap: threads `node:module`'s `createRequire` into the
+// modules that fetch their `node:` builtins via `process.getBuiltinModule`
+// (transform-core.mjs, worker-polyfill.mjs) on the narrow FLOOR where that API is
+// absent — WITHOUT any globalThis surface.
+//
+// WHY those modules can't fetch the builtin themselves: both are loaded on the fast
+// tier via Node's `require(esm)`, which instantiates an ES module by walking its
+// STATIC IMPORT graph through whatever ESM loader chain is registered — including the
+// USER's `--experimental-loader` / `module.register` hooks. A static `import {
+// createRequire } from "node:module"` in either file therefore routed the builtin
+// through the user chain, and a user resolve/load hook that rejects or rewrites
+// `node:module` exploded nub's own load (observed against es-module/test-esm-example-
+// loader and the loader-chaining corpus). So they fetch builtins via
+// `process.getBuiltinModule` (synchronous, OFF the loader chain, no static import).
+//
+// `process.getBuiltinModule` only exists from Node 22.3 / 20.16 / 18.20.4. On the
+// narrow FLOOR below that (18.19.x, 20.11–20.15, 22.0–22.2) it is `undefined`, so the
+// floor needs another way to reach `node:module`'s `createRequire`. This file is that
+// fallback: it holds the LONE static `import { createRequire } from "node:module"`
+// and hands the value to transform-core / worker-polyfill through their module-scoped
+// SETTERS (no globalThis surface — a `globalThis.__nub*` sentinel is the same brand
+// leak as a NUB_* env var, enumerable in user code AND worker realms, so it is
+// forbidden; this threading honors the same enumeration-invisibility contract every
+// other nub polyfill keeps).
+//
+// WHY THIS IS LEAK-SAFE WHERE the static import in transform-core/worker-polyfill WAS
+// NOT: this module is imported ONLY by the compat-tier entries (preload.mjs and
+// preload-async-hooks.mjs), AHEAD of transform-core/worker-polyfill in their source
+// order. The FAST tier (preload.cjs) loads those via `require(esm)` directly and never
+// touches preload.mjs / preload-async-hooks.mjs — so this file's static `node:module`
+// import never enters the fast-tier `require(esm)` graph, and the user loader chain
+// can never observe it. On the compat tier the loader hooks run in nub's OWN worker
+// (preload-async-hooks) or on the main thread before any user `--loader` could
+// intercept a bare `node:` builtin, both off the user chain — so the static import is
+// harmless exactly where it's reachable.
+//
+// IMPORT ORDERING (load-bearing): the compat entries import this file BEFORE
+// transform-core/worker-polyfill, but ES modules evaluate the importEE before the
+// importer's body — so transform-core's body has ALREADY run by the time the setter
+// calls below fire (during THIS module's evaluation). That is fine: transform-core
+// acquires its floor builtins lazily and `setBootstrapCreateRequire` triggers that
+// acquisition immediately, so every binding is ready before the entry body and long
+// before any hook fires. On Node WITH getBuiltinModule this file is a near no-op (the
+// setters are called but those modules never consult `_bootstrapCreateRequire`).
+import { createRequire } from "node:module";
+import { setBootstrapCreateRequire as setTransformCoreCreateRequire } from "./transform-core.mjs";
+
+// The floor's `createRequire`, exported so the compat entries (and any future floor
+// consumer) can thread it elsewhere without re-importing `node:module` into their own
+// static graph.
+export { createRequire };
+
+// Thread it into transform-core unconditionally (the setter no-ops the floor branch
+// on Node WITH getBuiltinModule). worker-polyfill's setter is wired by the entries
+// themselves, AFTER they import worker-polyfill, since worker-polyfill is loaded later
+// in the entry's flow (via dynamic import) than this static import runs.
+setTransformCoreCreateRequire(createRequire);

package/loader-addon-env.mjs

@@ -0,0 +1,24 @@
+// Standalone-loader addon plumbing — MUST evaluate before transform-core.mjs.
+//
+// transform-core loads the `nub-native` N-API addon at its own module evaluation
+// (fast tier: eagerly, the moment the module body runs), probing a sibling
+// `./addons/nub-native.node` first. Under the nub CLI that sibling always exists
+// (the extracted runtime dir); in the standalone loader package the addon rides a
+// per-platform npm package instead, so this module resolves it and hands the
+// absolute path over via the internal `__NUB_ADDON_PATH` plumbing var — see
+// ensureAddonEnv in loader-platform.cjs for the probe-order and worker-thread
+// rationale.
+//
+// Why a separate side-effect module: ESM evaluates imports in source order, so the
+// entry importing THIS file before transform-core is what guarantees the env var is
+// set in time (the same ordering trick compile-cache-restore.mjs uses for
+// NODE_COMPILE_CACHE). The createRequire import MUST come from `node:module`
+// directly, NOT from floor-builtin.mjs: floor-builtin statically imports
+// transform-core (to thread the floor's createRequire into it), so reaching
+// createRequire through it would evaluate transform-core — and run its addon
+// probe — before this module's body sets the env var. That ordering bug shipped
+// in the first cut and only the dev tree's sibling addons/ dir masked it.
+import { createRequire } from "node:module";
+
+const __require = createRequire(import.meta.url);
+__require("./loader-platform.cjs").ensureAddonEnv(__require);

package/loader-entry.mjs

@@ -0,0 +1,197 @@
+// Standalone Nub loader — the arming logic behind `node --import <pkg>` /
+// `node --require <pkg>`, consumed the way tsx/ts-node are. Slim by design: it
+// arms ONLY the resolve + transpile surface (TS/JSX/`using`-lowering, tsconfig
+// `paths`, extension probing, data-format imports) from the shared
+// transform-core / preload-common machinery, and none of the CLI runtime's
+// process augmentation — no polyfills, no Temporal/Worker/navigator globals, no
+// watch IPC, no user preload chain, no version marker. A file that runs under
+// `node --import <pkg>` must behave identically minus TS-just-works.
+//
+// Import order is load-bearing (ESM evaluates imports in source order):
+//   1. loader-addon-env.mjs — resolves the per-platform addon package and sets
+//      the internal `__NUB_ADDON_PATH` plumbing var BEFORE transform-core's
+//      module body probes for the addon.
+//   2. floor-builtin.mjs — threads `createRequire` into transform-core on the
+//      narrow pre-`process.getBuiltinModule` floor (18.19.x, 20.11–20.15,
+//      22.0–22.2); a no-op elsewhere.
+//   3. transform-core.mjs — the tier-agnostic resolve+transpile core, shared
+//      verbatim with the nub CLI. It has ZERO static imports by construction, so
+//      routing it through a user's loader chain leaks nothing (R11).
+import "./loader-addon-env.mjs";
+import { createRequire } from "./floor-builtin.mjs";
+import * as core from "./transform-core.mjs";
+
+const __require = createRequire(import.meta.url);
+const module_ = __require("node:module");
+const { fileURLToPath } = __require("node:url");
+const { dirname, isAbsolute, resolve: resolvePath, sep } = __require("node:path");
+const common = __require("./preload-common.cjs");
+
+// One arming record per module instance (= per realm: the main thread and each
+// user worker thread evaluate this module separately via inherited execArgv).
+// `esmMode` records which hook surface the ESM side took, because the CJS side's
+// classic-transpile decision depends on it.
+const armed = { esm: false, cjs: false, esmMode: null };
+
+const OWN_DIR = dirname(fileURLToPath(import.meta.url)) + sep;
+
+// The loader package's own published name, for recognizing our own `--import`
+// token in the foreign-loader scan. In the published package this file sits next
+// to package.json; in the dev tree (runtime/) there is none, and path-prefix
+// matching covers that case.
+const OWN_PKG_NAME = (() => {
+  try {
+    const raw = __require("node:fs").readFileSync(
+      fileURLToPath(new URL("./package.json", import.meta.url)),
+      "utf8",
+    );
+    const name = JSON.parse(raw).name;
+    return typeof name === "string" && name.length > 0 ? name : null;
+  } catch {
+    return null;
+  }
+})();
+
+// nub's own preload chainer rides `--import` too; same marker preload-common uses.
+const NUB_CHAIN_MARKER = /[\\/]\.nub[\\/]preload-chain\./;
+
+// Is this `--import`/`--loader` value one of OUR OWN entrypoints (or nub's
+// chainer), as opposed to a genuinely foreign async loader (tsx, ts-node, an OTel
+// attach)? The distinction preload-common's own scan does not need to make — the
+// CLI's fast tier is delivered by `--require`, so for it ANY `--import` is
+// foreign — but the standalone loader IS an `--import`, so a value-blind scan
+// would classify the loader itself as foreign and force the async tier on every
+// run in the broken-compose band.
+function isOwnLoaderToken(value) {
+  if (!value) return false;
+  if (NUB_CHAIN_MARKER.test(value)) return true;
+  if (OWN_PKG_NAME && (value === OWN_PKG_NAME || value.startsWith(`${OWN_PKG_NAME}/`))) {
+    return true;
+  }
+  try {
+    const p = value.startsWith("file:") ? fileURLToPath(value) : value;
+    if (isAbsolute(p) && (resolvePath(p) + sep).startsWith(OWN_DIR)) return true;
+    // A relative dev-tree form (`--import ./runtime/loader-register.mjs`)
+    // resolves from the CWD, matching how Node resolved it.
+    if (p.startsWith(".") && (resolvePath(process.cwd(), p) + sep).startsWith(OWN_DIR)) {
+      return true;
+    }
+  } catch {
+    // Unparseable value — treat as foreign; over-selection of the async tier is
+    // safe (it is always correct, just slower to start).
+  }
+  return false;
+}
+
+// A foreign async ESM loader riding THIS process's startup flags, via either
+// 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() {
+  const tokens = [];
+  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 (a === flag) {
+        if (typeof argv[i + 1] === "string") tokens.push(argv[i + 1]);
+      } else if (a.startsWith(`${flag}=`)) {
+        tokens.push(a.slice(flag.length + 1));
+      }
+    }
+  }
+  const opts = process.env.NODE_OPTIONS;
+  if (typeof opts === "string" && opts !== "") {
+    const re = /(?:^|\s)--(?:experimental-)?(?:import|loader)(?:=|\s)("[^"]*"|\S*)/g;
+    for (const match of opts.matchAll(re)) {
+      tokens.push((match[1] || "").replace(/^"|"$/g, ""));
+    }
+  }
+  return tokens.some((t) => t && !isOwnLoaderToken(t));
+}
+
+// Arm the loader. `esm` = the ESM hook surface (module.registerHooks on the fast
+// tier, the module.register loader worker on the compat tier); `cjs` = the
+// CommonJS require() surface (Module._resolveFilename + the classic transpile
+// shim where the tier needs it). Idempotent per surface, so `--import <pkg>` plus
+// `--require <pkg>/cjs` in one invocation arms each exactly once.
+export function arm({ esm = true, cjs = true } = {}) {
+  // Electron: the sync load hook deadlocks Electron's main-process module
+  // bootstrap, and its app JS is pre-bundled (the bundler owns TS) — same bail,
+  // same reason as the CLI preload (issue #246).
+  if (process.versions.electron) return;
+
+  const wantEsm = esm && !armed.esm;
+  const wantCjs = cjs && !armed.cjs;
+  if (!wantEsm && !wantCjs) return;
+
+  const [major = 0, minor = 0] = process.versions.node
+    .split(".")
+    .map((n) => parseInt(n, 10));
+  if (major < 18 || (major === 18 && minor < 19)) {
+    process.stderr.write(
+      `The Nub loader requires Node 18.19 or newer; got ${process.versions.node}. Hooks are inactive.\n`,
+    );
+    return;
+  }
+
+  // The loader ships no polyfill packages, so the clobber map's synthetic
+  // modules (re-exports of globals the CLI runtime installs) would hand users
+  // `undefined`. A user who installed @js-temporal/polyfill or urlpattern-polyfill
+  // themselves must get the real package — clear the map before any hook runs.
+  core.CLOBBER_MAP.clear();
+
+  // No-op unless the nub CLI's watch mode spawned this process (it sets
+  // WATCH_REPORT_DEPENDENCIES); wiring it keeps `nub watch` restarts correct when
+  // the loader runs under it.
+  const watchReporting = common.installWatchReporting(core);
+
+  const hasSyncHooks = typeof module_.registerHooks === "function";
+  // On 22.15.0–24.11.0 an async `module.register` loader's resolveSync/loadSync
+  // are unimplemented stubs, so nub's sync hooks composing with a foreign async
+  // 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();
+
+  if (wantEsm) {
+    if (hasSyncHooks && !forceAsync) {
+      const { resolve, load } = common.makeHooks(core, watchReporting);
+      module_.registerHooks({ resolve, load });
+      armed.esmMode = "sync";
+    } else {
+      // Compat tier (18.19–22.14, 23.0–23.4) or forced-async composition: hooks
+      // run in a dedicated loader worker. It imports transform-core statically in
+      // its own thread and finds the addon via the inherited __NUB_ADDON_PATH.
+      // The data payload carries the clobber-map clear into that thread's OWN
+      // transform-core instance — the clear() above only reaches this realm's.
+      common.registerLoaderWorker("./preload-async-hooks.mjs", import.meta.url, {
+        data: { standaloneLoader: true },
+      });
+      armed.esmMode = "worker";
+    }
+    armed.esm = true;
+  }
+
+  if (wantCjs) {
+    // Classic require.extensions transpile is needed only where the sync
+    // registerHooks load hook does not already transpile require()'d TS: on the
+    // sync tier it does (and the classic shim would shadow native require(esm),
+    // throwing bogus ERR_REQUIRE_ESM on ESM `.ts` — see preload.cjs); elsewhere
+    // install it unless Node has native TypeScript (mirrors preload.mjs).
+    const classic = armed.esmMode === "sync" ? false : !process.features?.typescript;
+    common.installCjsRequireHooks(core, classic);
+    armed.cjs = true;
+  }
+
+  // Bounded transpile-cache eviction, same cheap-probe shape as the CLI entries:
+  // schedule the deferred sweep only on the once-a-day run where one is due.
+  if (core.sweepDue()) {
+    setImmediate(() => {
+      try {
+        core.maybeSweepCache();
+      } catch {}
+    });
+  }
+}

package/loader-esm.mjs

@@ -0,0 +1,6 @@
+// `node --import <pkg>/esm` — arms the ESM hook surface only (tsx/esm's shape).
+// `import` of TS/JSX/data formats works; a bare `require()` of the same files is
+// left to Node.
+import { arm } from "./loader-entry.mjs";
+
+arm({ esm: true, cjs: false });

package/loader-platform.cjs

@@ -0,0 +1,109 @@
+"use strict";
+// Standalone-loader addon location: platform → `@nubjs/loader-<platform>` package
+// selection, plus the resolver that turns the selected package into an absolute
+// `nub-native.node` path. Mirrors npm/nub/platform.js (same musl detection, same
+// platform matrix) but for the loader's per-platform addon packages, which carry
+// the ~6 MB N-API addon instead of the full CLI binary. CommonJS so both the ESM
+// side-effect module (loader-addon-env.mjs) and any CJS entry can share it.
+
+const PLATFORMS = {
+  "darwin-arm64": "@nubjs/loader-darwin-arm64",
+  "darwin-x64": "@nubjs/loader-darwin-x64",
+  "linux-x64": "@nubjs/loader-linux-x64",
+  "linux-x64-musl": "@nubjs/loader-linux-x64-musl",
+  "linux-arm64": "@nubjs/loader-linux-arm64",
+  "linux-arm64-musl": "@nubjs/loader-linux-arm64-musl",
+  "win32-x64": "@nubjs/loader-win32-x64",
+  "win32-arm64": "@nubjs/loader-win32-arm64",
+};
+
+// True on a musl Linux (Alpine, etc.). Primary signal: Node's own diagnostic
+// report — `header.glibcVersionRuntime` is present on glibc and absent on musl.
+// Fallback: `ldd --version`, whose merged output contains "musl" there (the
+// stderr-only read shipped wrong once in npm/nub — check the merged output).
+function isMusl() {
+  if (process.platform !== "linux") return false;
+  try {
+    const report = process.report.getReport();
+    const header = (typeof report === "string" ? JSON.parse(report) : report).header;
+    if (header && "glibcVersionRuntime" in header) {
+      return !header.glibcVersionRuntime;
+    }
+  } catch {
+    // process.report unavailable — fall through to ldd.
+  }
+  try {
+    const out = require("child_process").execSync("ldd --version 2>&1", { encoding: "utf8" });
+    return out.includes("musl");
+  } catch (e) {
+    const out = `${(e && e.stdout) || ""}${(e && e.stderr) || ""}`;
+    return out.includes("musl");
+  }
+}
+
+function platformKey() {
+  const base = `${process.platform}-${process.arch}`;
+  return isMusl() ? `${base}-musl` : base;
+}
+
+// Absolute path to this platform's `nub-native.node`, resolved from the loader
+// package's own dependency tree via the caller-supplied `require` (created from a
+// file inside the package, so the node_modules walk starts next to the platform
+// packages regardless of hoisting). Returns null when the platform package is not
+// installed — an unsupported platform, or optionalDependencies pruned.
+function resolveAddonPath(requireFromPackage) {
+  const pkg = PLATFORMS[platformKey()];
+  if (!pkg) return null;
+  try {
+    return requireFromPackage.resolve(`${pkg}/nub-native.node`);
+  } catch {
+    return null;
+  }
+}
+
+// Make the addon reachable for every transform-core instance in this process tree
+// by setting the internal `__NUB_ADDON_PATH` plumbing var (probed LAST by
+// transform-core, after its relative candidates, so a nested nub CLI always wins
+// with its own bundled addon). Worker threads inherit process.env, which is what
+// carries the path into the compat tier's loader worker. A sibling
+// `addons/nub-native.node` (the dev tree, or a bundled layout) means the relative
+// probe wins anyway and no env is needed. Idempotent; safe to call from both the
+// ESM side-effect module and the CJS `--require` fallback.
+function ensureAddonEnv(requireFromPackage) {
+  try {
+    const { statSync } = require("node:fs");
+    const sibling = require("node:path").join(__dirname, "addons", "nub-native.node");
+    const s = statSync(sibling, { throwIfNoEntry: false });
+    if (s !== undefined && s.isFile()) return true;
+  } catch {
+    // fall through to the platform-package probe
+  }
+  // OVERWRITE an inherited value with our own resolution, never trust it first:
+  // the env var survives into child processes, and a nested process running a
+  // DIFFERENT version of this package must bind the addon shipped alongside its
+  // own JS, not the parent's — version-skewed addon and JS is the failure mode
+  // this file exists to avoid. The inherited value is used only as a last
+  // resort, when this package's own platform dependency is missing.
+  const resolved = resolveAddonPath(requireFromPackage);
+  if (resolved) {
+    process.env.__NUB_ADDON_PATH = resolved;
+    return true;
+  }
+  if (process.env.__NUB_ADDON_PATH) {
+    // Wrong-but-working is the one shape that must not be silent: the inherited
+    // addon may be a different version than this package's JS.
+    process.stderr.write(
+      `The Nub loader could not resolve its own native addon and is falling back to` +
+        ` an inherited one (${process.env.__NUB_ADDON_PATH}), which may be a different version.\n`,
+    );
+    return true;
+  }
+  process.stderr.write(
+    `The Nub loader could not find its native addon for ${process.platform}-${process.arch}` +
+      ` — the platform package may be missing (optionalDependencies pruned, or an` +
+      ` unsupported platform). TypeScript transpilation is inactive.\n`,
+  );
+  return false;
+}
+
+module.exports = { PLATFORMS, platformKey, resolveAddonPath, ensureAddonEnv };