@ttsc/unplugin 0.28.5 → 0.29.0

package/README.md

@@ -120,7 +120,7 @@ export default withTtsc(nextConfig);
 
 `withTtsc` covers both of Next.js's bundlers. It injects the webpack plugin and wires the Turbopack loader rules, with the options you pass reaching both, so the same config works whether Next runs on Turbopack (the default in current majors) or on webpack. Your own `webpack` hook and `turbopack` block are preserved: unrelated rules and settings survive, and a rule you already wired for this loader by hand is left alone rather than registered twice.
 
-That last part is decided by exact spelling. `withTtsc` declines to add its own rule when your glob is one it has measured against a real Turbopack build as naming every file with the extension — `*.ts`, `**/*.ts`, `{**/,}*.ts`, `*.tsx`, `**/*.tsx`, `*.{ts,tsx}`, `{*.ts,*.tsx}`, `**/*.{ts,tsx}`, `**/{*.ts,*.tsx}`, `**/**/*.{ts,tsx}`. Any other spelling keeps your rule and gains ours beside it, so a module may be transformed twice rather than not at all. The list is exact on purpose: treating an unmeasured glob as project-wide once left every module in a project with no `ttsc` rule at all, and a build that transforms twice is recoverable in a way a build that never transforms is not.
+That last part is decided by exact spelling. `withTtsc` declines to add its own rule when your glob is one it has measured against a real Turbopack build as naming every file with the extension: `*.ext`, `**/*.ext`, and `{**/,}*.ext` for each of `ts`, `tsx`, `mts`, and `cts`; plus the `*.{...}`, `{*.ext,...}`, `**/*.{...}`, `**/{*.ext,...}`, and `**/**/*.{...}` forms for every canonical combination of two or more extensions chosen from that same list. Any other spelling keeps your rule and gains ours beside it, so a module may be transformed twice rather than not at all. The list is exact on purpose: treating an unmeasured glob as project-wide once left every module in a project with no `ttsc` rule at all, and a build that transforms twice is recoverable in a way a build that never transforms is not.
 
 ### Turbopack
 
@@ -134,6 +134,8 @@ const nextConfig = {
     rules: {
       "*.ts": { loaders: ["@ttsc/unplugin/turbopack"] },
       "*.tsx": { loaders: ["@ttsc/unplugin/turbopack"] },
+      "*.mts": { loaders: ["@ttsc/unplugin/turbopack"] },
+      "*.cts": { loaders: ["@ttsc/unplugin/turbopack"] },
     },
   },
 };
@@ -181,9 +183,9 @@ import register from "@ttsc/unplugin/bun-register";
 register({ project: "tsconfig.build.json" });
 ```
 
-Importing the module registers it, so a bare `import "@ttsc/unplugin/bun-register"` is enough when the defaults are right. Registration is idempotent: a later explicit call updates the options rather than installing a second loader, because Bun uses the first matching `onLoad` hook and never falls through to an overlapping one.
+Importing the module registers it, so a bare `import "@ttsc/unplugin/bun-register"` is enough when the defaults are right. CommonJS and ESM loads in the same Bun process share that one registration. Calls made before the first transformable TypeScript load use last-call-wins and capture their options by value, which lets an immediate explicit call replace the preload defaults without installing a second loader. Entering the first such load locks the options synchronously for the module-loading session. A later call with the same structural value is idempotent, while a different value throws and requires restarting the Bun process.
 
-Under `Bun.build`, the adapter yields to the next loader for declarations, `node_modules`, source that `ttsc` leaves unchanged, and entries supplied through `Bun.build({ files })`. In-memory entries remain with Bun because ttsc transforms filesystem-backed project inputs. Bun's runtime `onLoad` contract does not accept an undefined result, so `Bun.plugin()` explicitly passes excluded and unchanged filesystem files through with their original source. `Bun.build` clears the project generation through its `onStart` lifecycle on every build. The runtime API has no corresponding hook, so one setup is treated as one immutable module-loading session: restart the Bun process after changing source, tsconfig, or plugin inputs.
+Under `Bun.build`, the adapter yields to the next loader for declarations, `node_modules`, source that `ttsc` leaves unchanged, and entries supplied through `Bun.build({ files })`. In-memory entries remain with Bun because ttsc transforms filesystem-backed project inputs. Bun's runtime `onLoad` contract does not accept an undefined result, so `Bun.plugin()` explicitly passes excluded and unchanged filesystem files through with their original source. Each `Bun.build` opens a delivery pass through `onStart`, then `onEnd` disposes the completed project generation and its filesystem trackers. The runtime API has neither lifecycle hook, so one setup is treated as one immutable module-loading session: restart the Bun process after changing source, tsconfig, or plugin inputs.
 
 ## Configuration
 
@@ -308,7 +310,7 @@ Each entrypoint supports ESM import and CJS require. In CommonJS configs, read t
 
 `@ttsc/unplugin/bun-register` is the Bun **runtime** entry rather than a bundler adapter, covered under [Bun](#bun) above. `@ttsc/unplugin/api` exposes the transform core itself (`transformTtsc`, `resolveOptions`, the cache lifecycle) for hosts that are not unplugin-shaped; `@ttsc/metro` is built on it.
 
-That entry point also exposes the project-membership rule — `readProjectMembershipPolicy`, `mergeMembershipPolicyOverlay`, `ITtscProjectMembershipPolicy`, `isProjectWalkPath` and the input-hash collectors — which decides which files can enter the compiled program and therefore which changes invalidate a cached compile. These exist so a host that keeps its own cache asks that question exactly the way the transform core asks it: `@ttsc/metro` folds them into Metro's static transformer key, and the two halves disagreeing about one project is the bug class they exist to prevent. They are shaped for that use rather than as a general-purpose configuration reader, and they move with the core rather than under a stability guarantee of their own. Build a host on them if you need it; pin your `@ttsc/unplugin` version if you do.
+That entry point also exposes the project-membership rule (`readProjectMembershipPolicy`, `mergeMembershipPolicyOverlay`, `ITtscProjectMembershipPolicy`, `isProjectWalkPath`, and the input-hash collectors), which decides which files can enter the compiled program and therefore which changes invalidate a cached compile. These exist so a host that keeps its own cache asks that question exactly the way the transform core asks it: `@ttsc/metro` folds them into Metro's static transformer key, and the two halves disagreeing about one project is the bug class they exist to prevent. They are shaped for that use rather than as a general-purpose configuration reader, and they move with the core rather than under a stability guarantee of their own. Build a host on them if you need it; pin your `@ttsc/unplugin` version if you do.
 
 ### Options
 
@@ -337,16 +339,16 @@ Not every Vite alias form can be forwarded, because a tsconfig `paths` map canno
 | `resolve.alias` form | Forwarded |
 | --- | --- |
 | `{ "@": "/src" }`, or the array form with a string `find` | yes |
-| array form with a `RegExp` `find`, such as `{ find: /^~/ }` | no — `paths` has no regular-expression form |
-| a string `find` containing `*` | no — a `paths` key already reads `*` as its own wildcard |
+| array form with a `RegExp` `find`, such as `{ find: /^~/ }` | no: `paths` has no regular-expression form |
+| a string `find` containing `*` | no: a `paths` key already reads `*` as its own wildcard |
 
-In both unforwarded cases the compile resolves that specifier through the tsconfig's `paths` alone, so declare it there if `ttsc` must resolve through it — a prefix `RegExp` such as `/^~/` is written as a `"~/*"` entry. Reducing simple prefix patterns automatically is deliberately not attempted: distinguishing `/^~/` from `/^@app/`, which also matches `@apple`, needs enough of a regular-expression engine that a wrong reduction becomes likely, and a mistranslated alias resolves imports to the wrong file without saying so.
+In both unforwarded cases the compile resolves that specifier through the tsconfig's `paths` alone, so declare it there if `ttsc` must resolve through it. A prefix `RegExp` such as `/^~/` is written as a `"~/*"` entry. Reducing simple prefix patterns automatically is deliberately not attempted: distinguishing `/^~/` from `/^@app/`, which also matches `@apple`, needs enough of a regular-expression engine that a wrong reduction becomes likely, and a mistranslated alias resolves imports to the wrong file without saying so.
 
 A `find` containing `*` is also reported once on stderr, naming the alias and the reason. A `RegExp` `find` is not, and the asymmetry is deliberate: Vite merges two `RegExp` aliases of its own into every resolved config, for `@vite/env` and `@vite/client`, so a report on that form would fire in every build of every project and name aliases you never wrote.
 
 ### Cache and Watch Invalidation
 
-Editing a type that only a generated validator depends on invalidates the module, in watch mode, in webpack's filesystem cache and in Turbopack's `fileDependencies`, even though the bundler erased the type-only import from its own graph. The adapter registers each transformed file's reference closure, the global-scope files, the configs and the resolution candidates with the bundler, plus whatever the plugins themselves report. The [setup guide](https://ttsc.dev/docs/setup/unplugin) describes how that set is derived and proven.
+Editing a type that only a generated validator depends on invalidates the module, in watch mode, in webpack's filesystem cache and in Turbopack's `fileDependencies`, even though the bundler erased the type-only import from its own graph. The adapter registers each transformed file's reference closure, the global-scope files, the configs, the importer resolution inputs and the universal automatic-type inputs with the bundler, plus whatever the plugins themselves report. The [setup guide](https://ttsc.dev/docs/setup/unplugin) describes how that set is derived and proven.
 
 One whole-project compile already contains every module's output, so the adapter compiles the project once and serves every module from that one result. Everything below is about when it may keep doing that.
 
@@ -354,14 +356,16 @@ One whole-project compile already contains every module's output, so the adapter
 
 A host with a build boundary opens a delivery pass there. The pass's first delivery proves the whole generation against the current filesystem once, and after that each module's first delivery in the pass is settled by the supplied source alone. `buildStart` repeats per rebuild under webpack, Rspack, Rollup, Rolldown, esbuild and `vite build --watch`, so a pass boundary means "each module is requested at most once from here", not "the compiled program is stale".
 
-Hosts with no build boundary (Metro workers, the Turbopack loader, and a watching Vite dev server, whose one `buildStart` spans later HMR edits) validate each generation hit against the inputs that can affect the module being asked for: its reference closure, the global-scope files, the configs, the resolution candidates, and the plugin dependencies. Sibling modules share one proof of the closure rather than repeating it per module.
+Hosts with no build boundary (Metro workers, the Turbopack loader, and a watching Vite dev server, whose one `buildStart` spans later HMR edits) validate each generation hit against the inputs that can affect the module being asked for: its reference closure, the global-scope files, the configs, importer resolution inputs, universal automatic-type inputs, and plugin dependencies. Sibling modules share one proof of the closure rather than repeating it per module.
 
-Project membership comes from the resolved configuration rather than from a list of directory names. `allowJs` and `resolveJsonModule` decide which file extensions can enter the program, so a bundle emitted beside your sources is not a membership change for a project that compiles no JavaScript. `outDir`, `declarationDir` and the plain entries of `exclude` name the directories the program does not contain, and those are not walked at all. Everywhere else, a directory takes part in membership only while it can hold a program input, so an output directory no configuration names still costs nothing as long as what it holds is not admissible, and the first source appearing in it is detected because the directory is walked and watched throughout. A project that does admit JavaScript should name its bundler's output directory in `exclude`, since otherwise an emitted `.js` there is a program input like any other. Emptying and recreating a directory the configuration names, which `emptyOutDir` and `output.clean` do on every build, costs nothing either.
+Project membership comes from the resolved configuration rather than from a list of directory names. `allowJs` and `resolveJsonModule` decide which file extensions can enter the program, so a bundle emitted beside your sources is not a membership change for a project that compiles no JavaScript. When no top-level `exclude` is declared, TypeScript uses `outDir` and `declarationDir` as implicit directory exclusions; an explicit `exclude`, including an empty array, replaces those defaults with its own entries. An adapter's `compilerOptions` replace or clear inherited `outDir` and `declarationDir` values before membership is derived, and `${configDir}` paths follow TypeScript's config-relative substitution. Everywhere else, a directory takes part in membership only while it can hold a program input, so an output directory no configuration names still costs nothing as long as what it holds is not admissible, and the first source appearing in it is detected because the directory is walked and watched throughout. A project that does admit JavaScript should name its bundler's output directory in `exclude`, since otherwise an emitted `.js` there is a program input like any other. Emptying and recreating a directory the effective exclusions name, which `emptyOutDir` and `output.clean` do on every build, costs nothing either.
 
 #### When it is discarded
 
 An input change or an explicit cache lifecycle reset permits a new generation. Opening a pass is not such a reset.
 
+Closing a webpack or Rspack compiler disposes its generation at the compiler's shutdown hook. esbuild disposes after a one-shot build or after the last overlapping build context closes; an older delayed disposal cannot clear a replacement build that has already reached `onStart`. These terminal boundaries release generation-owned filesystem trackers without discarding the generation on each rebuild.
+
 A compile that failed outright is retained for the rest of that pass, so its remaining modules replay the verdict instead of repeating an identical failing compile once per module, and the next pass attempts it again. A host with no pass boundary keeps evicting a failed compile on every delivery, so a transient toolchain failure never becomes permanent for a long-lived worker.
 
 #### What this changes for you
@@ -374,7 +378,7 @@ A Bun runtime plugin registration is one process-scoped module-loading session,
 
 A dev server started without a watcher (`server.watch: null`, which is what `vitest --run` configures) takes the pass lifecycle instead of per-delivery validation. Nothing can deliver a change event to such a session, so per-delivery validation there buys incoherence rather than freshness: modules delivered before an edit and after it would come from two different compilations of one program.
 
-Freshness proofs rest on filesystem timestamps, so two environments need care. A project on a network mount that accepts a watch and then reports nothing should be treated as one where notifications do not work. And a clock that jumps backwards, or a tree restored with stamps set into the future, defeats any stamp-based proof; a clock running at a constant offset does not, since it moves both sides of every comparison.
+Freshness proofs rest on filesystem observations, so two environments need care. A project on a network mount that accepts a watch and then reports nothing should be treated as one where notifications do not work. For metadata reuse, the adapter rewrites its own retained probe before validation and accepts only older stamps on the same reporting device. A clock rollback cannot strand historical proof because the previous reference is discarded before that write, and an unavailable or cross-volume probe keeps the byte comparison instead. A constant offset from the process clock is irrelevant because the process clock is never compared.
 
 The [setup guide](https://ttsc.dev/docs/setup/unplugin) describes how these proofs are built.
 

package/lib/api.js

@@ -2,6 +2,7 @@
 
 var index = require('./core/index.js');
 var transform = require('./core/transform.js');
+var projectDiscovery = require('./core/projectDiscovery.js');
 var tsconfigPaths = require('./core/tsconfigPaths.js');
 var options = require('./core/options.js');
 
@@ -11,13 +12,22 @@ exports.isTransformTarget = index.isTransformTarget;
 exports.sourceFilePattern = index.sourceFilePattern;
 exports.unplugin = index.default;
 exports.beginTtscTransformBuild = transform.beginTtscTransformBuild;
+exports.captureWatchInputBaseline = transform.captureWatchInputBaseline;
+exports.captureWatchInputFileBaseline = transform.captureWatchInputFileBaseline;
 exports.collectExternalInputHashes = transform.collectExternalInputHashes;
+exports.collectProjectInputHashSnapshot = transform.collectProjectInputHashSnapshot;
 exports.collectProjectInputHashes = transform.collectProjectInputHashes;
 exports.createTtscTransformCache = transform.createTtscTransformCache;
 exports.isProjectWalkPath = transform.isProjectWalkPath;
+exports.isWatchInputKeyBaseline = transform.isWatchInputKeyBaseline;
 exports.resetTtscTransformCache = transform.resetTtscTransformCache;
 exports.transformTtsc = transform.transformTtsc;
+exports.watchInputEvidenceMatchesBaseline = transform.watchInputEvidenceMatchesBaseline;
+exports.discoverNearestProjectTsconfig = projectDiscovery.discoverNearestProjectTsconfig;
+exports.findNearestProjectTsconfig = projectDiscovery.findNearestProjectTsconfig;
+exports.findProjectTsconfigs = projectDiscovery.findProjectTsconfigs;
 exports.mergeMembershipPolicyOverlay = tsconfigPaths.mergeMembershipPolicyOverlay;
 exports.readProjectMembershipPolicy = tsconfigPaths.readProjectMembershipPolicy;
+exports.readTsconfigSourceSnapshot = tsconfigPaths.readTsconfigSourceSnapshot;
 exports.resolveOptions = options.resolveOptions;
 //# sourceMappingURL=api.js.map

package/lib/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"api.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/lib/api.mjs

@@ -1,5 +1,6 @@
 export { isTransformTarget, sourceFilePattern, default as unplugin } from './core/index.mjs';
-export { beginTtscTransformBuild, collectExternalInputHashes, collectProjectInputHashes, createTtscTransformCache, isProjectWalkPath, resetTtscTransformCache, transformTtsc } from './core/transform.mjs';
-export { mergeMembershipPolicyOverlay, readProjectMembershipPolicy } from './core/tsconfigPaths.mjs';
+export { beginTtscTransformBuild, captureWatchInputBaseline, captureWatchInputFileBaseline, collectExternalInputHashes, collectProjectInputHashSnapshot, collectProjectInputHashes, createTtscTransformCache, isProjectWalkPath, isWatchInputKeyBaseline, resetTtscTransformCache, transformTtsc, watchInputEvidenceMatchesBaseline } from './core/transform.mjs';
+export { discoverNearestProjectTsconfig, findNearestProjectTsconfig, findProjectTsconfigs } from './core/projectDiscovery.mjs';
+export { mergeMembershipPolicyOverlay, readProjectMembershipPolicy, readTsconfigSourceSnapshot } from './core/tsconfigPaths.mjs';
 export { resolveOptions } from './core/options.mjs';
 //# sourceMappingURL=api.mjs.map

package/lib/api.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"api.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}
+{"version":3,"file":"api.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}

package/lib/bun-register.d.cts

@@ -11,14 +11,17 @@ import type { TtscUnpluginOptions } from "./core/options.cjs";
  * "@ttsc/unplugin/bun-register"`. Options are read from the nearest
  * `tsconfig.json`, identical to the bundler adapters.
  *
- * Registration is idempotent: the first call (implicit on import, or explicit)
- * registers the one loader with Bun; later calls only update the effective
- * options, so accessing the explicit API cannot install a second default loader
- * that shadows the caller's configuration. Repeated explicit calls are
- * last-write-wins for the effective options.
+ * The first call registers one loader. Calls before its first transformable
+ * TypeScript load use last-call-wins and capture options by value, so an
+ * explicit call right after importing this module replaces the preload defaults
+ * without installing a shadowing loader. Entering the first such load locks
+ * that snapshot synchronously. Later calls with a structurally identical value
+ * are idempotent; a different value throws rather than pretending a resolved
+ * loader changed configuration.
  *
- * @throws When called explicitly off the Bun runtime (`globalThis.Bun.plugin`
- *   is unavailable). The auto-registration below stays silent off Bun so the
+ * @throws When called explicitly off the Bun runtime, when options are not
+ *   structured-cloneable, or when a different option value is supplied after
+ *   the first load. The auto-registration below stays silent off Bun so the
  *   module is harmless to import from Node (tests, tooling).
  */
 export declare function register(options?: TtscUnpluginOptions): void;

package/lib/bun-register.d.mts

@@ -11,14 +11,17 @@ import type { TtscUnpluginOptions } from "./core/options.mjs";
  * "@ttsc/unplugin/bun-register"`. Options are read from the nearest
  * `tsconfig.json`, identical to the bundler adapters.
  *
- * Registration is idempotent: the first call (implicit on import, or explicit)
- * registers the one loader with Bun; later calls only update the effective
- * options, so accessing the explicit API cannot install a second default loader
- * that shadows the caller's configuration. Repeated explicit calls are
- * last-write-wins for the effective options.
+ * The first call registers one loader. Calls before its first transformable
+ * TypeScript load use last-call-wins and capture options by value, so an
+ * explicit call right after importing this module replaces the preload defaults
+ * without installing a shadowing loader. Entering the first such load locks
+ * that snapshot synchronously. Later calls with a structurally identical value
+ * are idempotent; a different value throws rather than pretending a resolved
+ * loader changed configuration.
  *
- * @throws When called explicitly off the Bun runtime (`globalThis.Bun.plugin`
- *   is unavailable). The auto-registration below stays silent off Bun so the
+ * @throws When called explicitly off the Bun runtime, when options are not
+ *   structured-cloneable, or when a different option value is supplied after
+ *   the first load. The auto-registration below stays silent off Bun so the
  *   module is harmless to import from Node (tests, tooling).
  */
 export declare function register(options?: TtscUnpluginOptions): void;

package/lib/bun-register.d.ts

@@ -11,14 +11,17 @@ import type { TtscUnpluginOptions } from "./core/options";
  * "@ttsc/unplugin/bun-register"`. Options are read from the nearest
  * `tsconfig.json`, identical to the bundler adapters.
  *
- * Registration is idempotent: the first call (implicit on import, or explicit)
- * registers the one loader with Bun; later calls only update the effective
- * options, so accessing the explicit API cannot install a second default loader
- * that shadows the caller's configuration. Repeated explicit calls are
- * last-write-wins for the effective options.
+ * The first call registers one loader. Calls before its first transformable
+ * TypeScript load use last-call-wins and capture options by value, so an
+ * explicit call right after importing this module replaces the preload defaults
+ * without installing a shadowing loader. Entering the first such load locks
+ * that snapshot synchronously. Later calls with a structurally identical value
+ * are idempotent; a different value throws rather than pretending a resolved
+ * loader changed configuration.
  *
- * @throws When called explicitly off the Bun runtime (`globalThis.Bun.plugin`
- *   is unavailable). The auto-registration below stays silent off Bun so the
+ * @throws When called explicitly off the Bun runtime, when options are not
+ *   structured-cloneable, or when a different option value is supplied after
+ *   the first load. The auto-registration below stays silent off Bun so the
  *   module is harmless to import from Node (tests, tooling).
  */
 export declare function register(options?: TtscUnpluginOptions): void;

package/lib/bun-register.js

@@ -2,22 +2,23 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var node_util = require('node:util');
 var bun = require('./bun.js');
 
 /**
- * Effective options for the single runtime loader.
+ * Pending and locked options for the single runtime loader.
  *
  * Bun uses the first matching `onLoad` hook and does not fall through to a
  * later overlapping plugin (oven-sh/bun#20583). Registering twice — once
  * implicitly on import, once explicitly — would let the default loader shadow
- * the configured one. Instead exactly one Bun plugin is registered; it resolves
- * these options lazily on first load (see {@link bun}'s provider form), so an
- * explicit `register(options)` made right after importing this module overrides
- * the preload defaults without a second shadowing registration.
+ * the configured one. Instead exactly one Bun plugin is registered. Calls made
+ * before its first load replace this detached snapshot; entering the first
+ * transformable load locks that value synchronously for the process's immutable
+ * module-loading session. State is keyed by the Bun runtime in a global weak
+ * map so loading both emitted module conditions cannot install two overlapping
+ * loaders.
  */
-let activeOptions;
-/** Whether the single runtime loader has already been registered with Bun. */
-let registered = false;
+const BUN_REGISTRATION_STATES = Symbol.for("@ttsc/unplugin/bun-register/states/v1");
 /**
  * Register the ttsc transform as a Bun **runtime** plugin.
  *
@@ -30,14 +31,17 @@ let registered = false;
  * "@ttsc/unplugin/bun-register"`. Options are read from the nearest
  * `tsconfig.json`, identical to the bundler adapters.
  *
- * Registration is idempotent: the first call (implicit on import, or explicit)
- * registers the one loader with Bun; later calls only update the effective
- * options, so accessing the explicit API cannot install a second default loader
- * that shadows the caller's configuration. Repeated explicit calls are
- * last-write-wins for the effective options.
+ * The first call registers one loader. Calls before its first transformable
+ * TypeScript load use last-call-wins and capture options by value, so an
+ * explicit call right after importing this module replaces the preload defaults
+ * without installing a shadowing loader. Entering the first such load locks
+ * that snapshot synchronously. Later calls with a structurally identical value
+ * are idempotent; a different value throws rather than pretending a resolved
+ * loader changed configuration.
  *
- * @throws When called explicitly off the Bun runtime (`globalThis.Bun.plugin`
- *   is unavailable). The auto-registration below stays silent off Bun so the
+ * @throws When called explicitly off the Bun runtime, when options are not
+ *   structured-cloneable, or when a different option value is supplied after
+ *   the first load. The auto-registration below stays silent off Bun so the
  *   module is harmless to import from Node (tests, tooling).
  */
 function register(options) {
@@ -47,15 +51,50 @@ function register(options) {
             "(globalThis.Bun.plugin is unavailable). Use a bundler adapter such as " +
             "@ttsc/unplugin/vite for non-Bun toolchains.");
     }
-    activeOptions = options;
-    if (registered) {
+    const state = registrationState(runtime);
+    const snapshot = snapshotOptions(options);
+    if (state.optionsLocked) {
+        if (node_util.isDeepStrictEqual(snapshot, state.lockedOptions)) {
+            return;
+        }
+        throw new Error("@ttsc/unplugin/bun-register options are locked because the runtime " +
+            "loader has started handling a TypeScript module. Restart the Bun " +
+            "process to use different compiler or plugin options.");
+    }
+    state.activeOptions = snapshot;
+    ensureRegistered(runtime, state);
+}
+/** Install the runtime's one loader without changing its pending options. */
+function ensureRegistered(runtime, state) {
+    if (state.registered)
         return;
+    state.registered = true;
+    try {
+        runtime.plugin(bun.default(() => lockOptions(state)));
+    }
+    catch (error) {
+        state.registered = false;
+        throw error;
+    }
+}
+/** Lock and return the detached option snapshot at first load-handler entry. */
+function lockOptions(state) {
+    if (!state.optionsLocked) {
+        state.lockedOptions = state.activeOptions;
+        state.optionsLocked = true;
+    }
+    return state.lockedOptions;
+}
+/** Detach JSON-shaped options from mutations made after `register` returns. */
+function snapshotOptions(options) {
+    if (options === undefined)
+        return undefined;
+    try {
+        return structuredClone(options);
+    }
+    catch (cause) {
+        throw new TypeError("@ttsc/unplugin/bun-register options must contain structured-cloneable values.", { cause });
     }
-    registered = true;
-    // Register a single loader whose options are read from `activeOptions` on
-    // first load, so an explicit call made after the import-time auto-register
-    // still wins.
-    runtime.plugin(bun.default(() => activeOptions));
 }
 function bunRuntime() {
     const runtime = globalThis.Bun;
@@ -63,11 +102,38 @@ function bunRuntime() {
         ? runtime
         : undefined;
 }
+/** Resolve the shared state owned by one concrete Bun runtime object. */
+function registrationState(runtime) {
+    const holder = globalThis;
+    let states = holder[BUN_REGISTRATION_STATES];
+    if (!(states instanceof WeakMap)) {
+        states = new WeakMap();
+        Object.defineProperty(holder, BUN_REGISTRATION_STATES, {
+            configurable: false,
+            enumerable: false,
+            value: states,
+            writable: false,
+        });
+    }
+    const registrations = states;
+    const existing = registrations.get(runtime);
+    if (existing !== undefined)
+        return existing;
+    const created = {
+        activeOptions: undefined,
+        lockedOptions: undefined,
+        optionsLocked: false,
+        registered: false,
+    };
+    registrations.set(runtime, created);
+    return created;
+}
 // Auto-register on import so a `bunfig.toml` `preload` entry — which only
 // imports the module — takes effect. Guarded so importing from Node (a stray
 // import, or a unit test) is a harmless no-op rather than a throw.
-if (bunRuntime() !== undefined) {
-    register();
+const runtime = bunRuntime();
+if (runtime !== undefined) {
+    ensureRegistered(runtime, registrationState(runtime));
 }
 
 exports.default = register;

package/lib/bun-register.js.map

@@ -1 +1 @@
-{"version":3,"file":"bun-register.js","sources":["../src/bun-register.ts"],"sourcesContent":[null],"names":["bun"],"mappings":";;;;;;AAcA;;;;;;;;;;AAUG;AACH,IAAI,aAA8C;AAClD;AACA,IAAI,UAAU,GAAG,KAAK;AAEtB;;;;;;;;;;;;;;;;;;;;;AAqBG;AACG,SAAU,QAAQ,CAAC,OAA6B,EAAA;AACpD,IAAA,MAAM,OAAO,GAAG,UAAU,EAAE;AAC5B,IAAA,IAAI,OAAO,KAAK,SAAS,EAAE;QACzB,MAAM,IAAI,KAAK,CACb,6DAA6D;YAC3D,wEAAwE;AACxE,YAAA,6CAA6C,CAChD;IACH;IACA,aAAa,GAAG,OAAO;IACvB,IAAI,UAAU,EAAE;QACd;IACF;IACA,UAAU,GAAG,IAAI;;;;IAIjB,OAAO,CAAC,MAAM,CAACA,WAAG,CAAC,MAAM,aAAa,CAAC,CAAC;AAC1C;AAEA,SAAS,UAAU,GAAA;AACjB,IAAA,MAAM,OAAO,GAAI,UAAyC,CAAC,GAAG;IAC9D,OAAO,OAAO,KAAK,SAAS,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK;AACxD,UAAE;UACA,SAAS;AACf;AAEA;AACA;AACA;AACA,IAAI,UAAU,EAAE,KAAK,SAAS,EAAE;AAC9B,IAAA,QAAQ,EAAE;AACZ;;;;;"}
+{"version":3,"file":"bun-register.js","sources":["../src/bun-register.ts"],"sourcesContent":[null],"names":["isDeepStrictEqual","bun"],"mappings":"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"}

package/lib/bun-register.mjs

@@ -1,19 +1,20 @@
+import { isDeepStrictEqual } from 'node:util';
 import bun from './bun.mjs';
 
 /**
- * Effective options for the single runtime loader.
+ * Pending and locked options for the single runtime loader.
  *
  * Bun uses the first matching `onLoad` hook and does not fall through to a
  * later overlapping plugin (oven-sh/bun#20583). Registering twice — once
  * implicitly on import, once explicitly — would let the default loader shadow
- * the configured one. Instead exactly one Bun plugin is registered; it resolves
- * these options lazily on first load (see {@link bun}'s provider form), so an
- * explicit `register(options)` made right after importing this module overrides
- * the preload defaults without a second shadowing registration.
+ * the configured one. Instead exactly one Bun plugin is registered. Calls made
+ * before its first load replace this detached snapshot; entering the first
+ * transformable load locks that value synchronously for the process's immutable
+ * module-loading session. State is keyed by the Bun runtime in a global weak
+ * map so loading both emitted module conditions cannot install two overlapping
+ * loaders.
  */
-let activeOptions;
-/** Whether the single runtime loader has already been registered with Bun. */
-let registered = false;
+const BUN_REGISTRATION_STATES = Symbol.for("@ttsc/unplugin/bun-register/states/v1");
 /**
  * Register the ttsc transform as a Bun **runtime** plugin.
  *
@@ -26,14 +27,17 @@ let registered = false;
  * "@ttsc/unplugin/bun-register"`. Options are read from the nearest
  * `tsconfig.json`, identical to the bundler adapters.
  *
- * Registration is idempotent: the first call (implicit on import, or explicit)
- * registers the one loader with Bun; later calls only update the effective
- * options, so accessing the explicit API cannot install a second default loader
- * that shadows the caller's configuration. Repeated explicit calls are
- * last-write-wins for the effective options.
+ * The first call registers one loader. Calls before its first transformable
+ * TypeScript load use last-call-wins and capture options by value, so an
+ * explicit call right after importing this module replaces the preload defaults
+ * without installing a shadowing loader. Entering the first such load locks
+ * that snapshot synchronously. Later calls with a structurally identical value
+ * are idempotent; a different value throws rather than pretending a resolved
+ * loader changed configuration.
  *
- * @throws When called explicitly off the Bun runtime (`globalThis.Bun.plugin`
- *   is unavailable). The auto-registration below stays silent off Bun so the
+ * @throws When called explicitly off the Bun runtime, when options are not
+ *   structured-cloneable, or when a different option value is supplied after
+ *   the first load. The auto-registration below stays silent off Bun so the
  *   module is harmless to import from Node (tests, tooling).
  */
 function register(options) {
@@ -43,15 +47,50 @@ function register(options) {
             "(globalThis.Bun.plugin is unavailable). Use a bundler adapter such as " +
             "@ttsc/unplugin/vite for non-Bun toolchains.");
     }
-    activeOptions = options;
-    if (registered) {
+    const state = registrationState(runtime);
+    const snapshot = snapshotOptions(options);
+    if (state.optionsLocked) {
+        if (isDeepStrictEqual(snapshot, state.lockedOptions)) {
+            return;
+        }
+        throw new Error("@ttsc/unplugin/bun-register options are locked because the runtime " +
+            "loader has started handling a TypeScript module. Restart the Bun " +
+            "process to use different compiler or plugin options.");
+    }
+    state.activeOptions = snapshot;
+    ensureRegistered(runtime, state);
+}
+/** Install the runtime's one loader without changing its pending options. */
+function ensureRegistered(runtime, state) {
+    if (state.registered)
         return;
+    state.registered = true;
+    try {
+        runtime.plugin(bun(() => lockOptions(state)));
+    }
+    catch (error) {
+        state.registered = false;
+        throw error;
+    }
+}
+/** Lock and return the detached option snapshot at first load-handler entry. */
+function lockOptions(state) {
+    if (!state.optionsLocked) {
+        state.lockedOptions = state.activeOptions;
+        state.optionsLocked = true;
+    }
+    return state.lockedOptions;
+}
+/** Detach JSON-shaped options from mutations made after `register` returns. */
+function snapshotOptions(options) {
+    if (options === undefined)
+        return undefined;
+    try {
+        return structuredClone(options);
+    }
+    catch (cause) {
+        throw new TypeError("@ttsc/unplugin/bun-register options must contain structured-cloneable values.", { cause });
     }
-    registered = true;
-    // Register a single loader whose options are read from `activeOptions` on
-    // first load, so an explicit call made after the import-time auto-register
-    // still wins.
-    runtime.plugin(bun(() => activeOptions));
 }
 function bunRuntime() {
     const runtime = globalThis.Bun;
@@ -59,11 +98,38 @@ function bunRuntime() {
         ? runtime
         : undefined;
 }
+/** Resolve the shared state owned by one concrete Bun runtime object. */
+function registrationState(runtime) {
+    const holder = globalThis;
+    let states = holder[BUN_REGISTRATION_STATES];
+    if (!(states instanceof WeakMap)) {
+        states = new WeakMap();
+        Object.defineProperty(holder, BUN_REGISTRATION_STATES, {
+            configurable: false,
+            enumerable: false,
+            value: states,
+            writable: false,
+        });
+    }
+    const registrations = states;
+    const existing = registrations.get(runtime);
+    if (existing !== undefined)
+        return existing;
+    const created = {
+        activeOptions: undefined,
+        lockedOptions: undefined,
+        optionsLocked: false,
+        registered: false,
+    };
+    registrations.set(runtime, created);
+    return created;
+}
 // Auto-register on import so a `bunfig.toml` `preload` entry — which only
 // imports the module — takes effect. Guarded so importing from Node (a stray
 // import, or a unit test) is a harmless no-op rather than a throw.
-if (bunRuntime() !== undefined) {
-    register();
+const runtime = bunRuntime();
+if (runtime !== undefined) {
+    ensureRegistered(runtime, registrationState(runtime));
 }
 
 export { register as default, register };

package/lib/bun-register.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"bun-register.mjs","sources":["../src/bun-register.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAcA;;;;;;;;;;AAUG;AACH,IAAI,aAA8C;AAClD;AACA,IAAI,UAAU,GAAG,KAAK;AAEtB;;;;;;;;;;;;;;;;;;;;;AAqBG;AACG,SAAU,QAAQ,CAAC,OAA6B,EAAA;AACpD,IAAA,MAAM,OAAO,GAAG,UAAU,EAAE;AAC5B,IAAA,IAAI,OAAO,KAAK,SAAS,EAAE;QACzB,MAAM,IAAI,KAAK,CACb,6DAA6D;YAC3D,wEAAwE;AACxE,YAAA,6CAA6C,CAChD;IACH;IACA,aAAa,GAAG,OAAO;IACvB,IAAI,UAAU,EAAE;QACd;IACF;IACA,UAAU,GAAG,IAAI;;;;IAIjB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,aAAa,CAAC,CAAC;AAC1C;AAEA,SAAS,UAAU,GAAA;AACjB,IAAA,MAAM,OAAO,GAAI,UAAyC,CAAC,GAAG;IAC9D,OAAO,OAAO,KAAK,SAAS,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK;AACxD,UAAE;UACA,SAAS;AACf;AAEA;AACA;AACA;AACA,IAAI,UAAU,EAAE,KAAK,SAAS,EAAE;AAC9B,IAAA,QAAQ,EAAE;AACZ;;;;"}
+{"version":3,"file":"bun-register.mjs","sources":["../src/bun-register.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/lib/bun.d.cts

@@ -20,19 +20,19 @@ export type BunLoader = "ts" | "tsx";
  *
  * The provider form exists for the runtime registration path (`bun-register`),
  * where a single Bun plugin is registered on import but its effective options
- * may be overridden by an explicit `register(options)` call made in the same
- * synchronous tick. Resolving through the provider on first load, rather than
- * at registration, lets that later call win without Bun ever seeing a second
- * shadowing loader.
+ * may be overridden by explicit `register(options)` calls made before the first
+ * transformable TypeScript load. Resolving through the provider on that first
+ * load, rather than at registration, lets the last pending call win without Bun
+ * ever seeing a second shadowing loader.
  */
 export type TtscBunOptions = TtscUnpluginOptions | (() => TtscUnpluginOptions | undefined);
 /**
  * Minimal subset of the Bun `BuildConfig` plugin build object.
  *
- * `onLoad` drives the source transform. Bun's bundler also exposes `onStart`,
- * which is used when available to forward the shared plugin's build lifecycle
- * and clear its per-build cache. The runtime plugin API omits that hook, so
- * plugin setup itself starts its one process-scoped module-loading session.
+ * `onLoad` drives the source transform. Bun's bundler also exposes `onStart`
+ * and `onEnd`, which bracket the shared plugin's build lifecycle. The runtime
+ * plugin API omits those hooks, so plugin setup itself starts its one
+ * process-scoped module-loading session.
  */
 export interface BunLikeBuild {
     /**
@@ -51,6 +51,8 @@ export interface BunLikeBuild {
      * Optional because `Bun.plugin()` runtime builders do not expose this hook.
      */
     onStart?(callback: () => void | Promise<void>): void;
+    /** Register a callback for deterministic bundler-session teardown. */
+    onEnd?(callback: () => void | Promise<void>): void;
     /**
      * Register a loader callback for files matching `filter`.
      *