env-runner 0.2.2 → 0.3.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { EnvRunner, FetchHandler, NodeUpgradeContext, RPCOptions, RunnerMessageListener, RunnerRPCHooks, UpgradeContext, UpgradeHandler, WorkerAddress, WorkerHooks } from "./_chunks/types.mjs";
-import { BaseEnvRunner, EnvRunnerData, VirtualModuleSource, VirtualModules } from "./_chunks/common-base-runner.mjs";
+import { EnvRunner, FetchHandler, NodeUpgradeContext, RPCOptions, RunnerMessageListener, RunnerRPCHooks, UpgradeContext, UpgradeHandler, VirtualModule, VirtualModuleContent, VirtualModuleFormat, VirtualModuleSource, VirtualModuleUpdates, VirtualModules, WorkerAddress, WorkerHooks } from "./_chunks/types.mjs";
+import { BaseEnvRunner, EnvRunnerData } from "./_chunks/common-base-runner.mjs";
 import { RuntimeDep, resolveRuntimeDep } from "./_chunks/common-runtime-deps.mjs";
 import { DenoProcessEnvRunner } from "./_chunks/deno-process-runner.mjs";
 import { MiniflareEnvRunner, MiniflareEnvRunnerOptions, MiniflareExportInfo, TransformResult } from "./_chunks/miniflare-runner.mjs";
@@ -7,10 +7,7 @@ import { VercelEnvRunner } from "./_chunks/vercel-runner.mjs";
 import { NetlifyEnvRunner } from "./_chunks/netlify-runner.mjs";
 import { ServerOptions, ServerPlugin } from "srvx";
 import { Hooks } from "crossws";
-/**
- * Manages an active `EnvRunner` instance, proxying all calls to it.
- * Supports hot-reload, auto-restart on unexpected exit, and message queueing.
- */
+/** Proxies an active `EnvRunner` with hot-reload, auto-restart and message queueing. */
 export declare class RunnerManager implements EnvRunner, AsyncDisposable {
   private _runner;
   private _messageQueue;
@@ -27,30 +24,18 @@ export declare class RunnerManager implements EnvRunner, AsyncDisposable {
   get closed(): boolean;
   get address(): WorkerAddress | undefined;
   /**
-   * Replace the active runner with a new one. Closes the previous runner.
-   *
-   * When called without a runner, a fresh one is created via `_createRunner()`
-   * (only available on subclasses with a runner factory, e.g. `EnvServer`).
+   * Replace (and close) the active runner. Without an argument, subclasses with
+   * `_createRunner()` (e.g. `EnvServer`) create a fresh one.
    */
   reload(runner?: EnvRunner): Promise<void>;
   /** Create a fresh runner for argument-less `reload()`. Overridden by subclasses with a runner factory. */
   protected _createRunner(): EnvRunner | Promise<EnvRunner>;
   fetch: FetchHandler;
   protected _fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
-  /**
-   * Lazily satisfy a pending `invalidateModule()` with a single entry reload
-   * before serving — concurrent fetches share the same reload. A failed reload
-   * keeps the invalidation pending, so the next fetch retries.
-   */
+  /** Apply a pending invalidation with one shared reload; a failure retries on the next fetch. */
   private _flushInvalidation;
   upgrade: UpgradeHandler;
-  /**
-   * Create a runtime-native WebSocket reverse-proxy plugin for the public srvx
-   * server. Attach it via `serve({ plugins: [await manager.wsSrvxPlugin()] })`:
-   * on Node it proxies the raw upgrade socket to the worker, and on Bun/Deno it
-   * bridges the WebSocket with crossws. The plugin reads the active runner
-   * lazily, so it keeps working across hot-reloads.
-   */
+  /** WebSocket proxy plugin: `serve({ plugins: [await manager.wsSrvxPlugin()] })`. */
   wsSrvxPlugin(): Promise<ServerPlugin>;
   sendMessage(message: unknown): void;
   onMessage(listener: RunnerMessageListener): void;
@@ -61,10 +46,11 @@ export declare class RunnerManager implements EnvRunner, AsyncDisposable {
   }): Promise<T>;
   reloadModule(timeout?: number): Promise<void>;
   /**
-   * Invalidate a virtual module on the active runner and mark the manager
-   * dirty: the next `fetch()` reloads the entry automatically, so callers
-   * don't need to pair the call with an explicit `reloadModule()`.
+   * Set or remove (`null`) virtual modules of the active runner (waiting for it
+   * during a reload); the next `fetch()` reloads the entry automatically.
    */
+  updateVirtualModules(changes: VirtualModuleUpdates, timeout?: number): Promise<void>;
+  /** Invalidate a virtual module; the next `fetch()` reloads the entry automatically. */
   invalidateModule(specifier: string, timeout?: number): Promise<void>;
   close(): Promise<void>;
   [Symbol.asyncDispose](): Promise<void>;
@@ -75,7 +61,8 @@ export declare class RunnerManager implements EnvRunner, AsyncDisposable {
   private _internalListener;
   private _attach;
   private _detach;
-  private _waitForRunner;
+  /** The active runner, waiting for one during a reload. */
+  protected _waitForRunner(timeout?: number): Promise<EnvRunner | undefined>;
   private _flushQueue;
 }
 type RunnerName = "node-worker" | "node-process" | "bun-process" | "deno-process" | "self" | "miniflare" | "vercel" | "netlify";
@@ -85,11 +72,7 @@ interface LoadRunnerOptions {
   hooks?: WorkerHooks;
   data?: EnvRunnerData;
   execArgv?: string[];
-  /**
-   * Additional runner-specific options (passed through to the runner
-   * constructor) — e.g. `miniflare` (the imported `miniflare` package) for the
-   * `miniflare` runner, which this package never imports itself.
-   */
+  /** Runner-specific constructor options (e.g. `miniflare` for the `miniflare` runner). */
   [key: string]: unknown;
 }
 export declare function loadRunner(runner: RunnerName, opts: LoadRunnerOptions): Promise<EnvRunner>;
@@ -110,13 +93,7 @@ interface EnvServerOptions {
   watch?: boolean;
   /** Additional paths to watch (directories or files). */
   watchPaths?: string[];
-  /**
-   * Extra runner-specific constructor options, spread into the runner.
-   *
-   * Runners that build on external packages take them as explicit options —
-   * e.g. `{ miniflare }` for the `miniflare` runner (env-runner never imports
-   * those packages itself).
-   */
+  /** Runner-specific constructor options (e.g. `{ miniflare }`). */
   runnerOptions?: Record<string, unknown>;
 }
 export declare class EnvServer extends RunnerManager {
@@ -125,6 +102,7 @@ export declare class EnvServer extends RunnerManager {
   private _reloadTimeout;
   private _reloadListeners;
   private _startPromise;
+  private _virtual;
   runner: Awaited<ReturnType<typeof loadRunner>> | null;
   /** Register a listener called when the runner is reloaded due to a file change. */
   onReload(listener: () => void): void;
@@ -132,18 +110,18 @@ export declare class EnvServer extends RunnerManager {
   offReload(listener: () => void): void;
   constructor(opts: EnvServerOptions);
   /**
-   * Start the server by loading and attaching the runner.
-   *
-   * Idempotent — concurrent and repeated calls share one startup. Calling
-   * `start()` explicitly is optional: the first `fetch()` auto-starts the
-   * server. A failed start resets so a later call can retry.
+   * Load and attach the runner. Idempotent and optional (the first `fetch()`
+   * auto-starts); a failed start can be retried.
    */
   start(): Promise<this>;
+  /** Replace the active runner; without an argument, create one from the server options. */
+  reload(runner?: EnvRunner): Promise<void>;
   /**
-   * Replace the active runner. When called without an argument, a fresh
-   * runner is created from the server options.
+   * Also kept in the server's own map, so runners it creates later (`reload()`,
+   * watch mode) start with the changes. Without an active runner (before the
+   * first start), the changes are only recorded.
    */
-  reload(runner?: EnvRunner): Promise<void>;
+  updateVirtualModules(changes: VirtualModuleUpdates, timeout?: number): Promise<void>;
   close(): Promise<void>;
   /** Auto-start on first fetch so an explicit `start()` call is optional. */
   protected _fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
@@ -162,12 +140,8 @@ interface AppEntryIPC {
   onClose?: () => void | Promise<void>;
 }
 /**
- * User entry module shape. Besides `fetch` and the env-runner specific hooks
- * (`upgrade`, `websocket`, `ipc`), any srvx `ServerOptions` (e.g. `error`,
- * `maxRequestBodySize`, `trustProxy`, `node`/`bun`/`deno`) is forwarded to
- * `serve()` by the built-in workers. The listener-related keys in
- * {@link RESERVED_SERVER_OPTIONS} are owned by the worker (it sits behind the
- * runner's proxy) and are ignored if set.
+ * User entry module. Other srvx `ServerOptions` are forwarded to `serve()`,
+ * except {@link RESERVED_SERVER_OPTIONS}.
  */
 interface AppEntry extends Omit<ServerOptions, "fetch"> {
   fetch: ServerOptions["fetch"];
@@ -175,29 +149,17 @@ interface AppEntry extends Omit<ServerOptions, "fetch"> {
   websocket?: Partial<Hooks>;
   ipc?: AppEntryIPC;
 }
-/**
- * srvx options the built-in workers always control themselves: the worker
- * listens on a random loopback port behind the runner's proxy, so the entry
- * must not be able to relocate or TLS-terminate it.
- */
+/** Worker-owned srvx options: the worker listens on a random loopback port behind the proxy. */
 export declare const RESERVED_SERVER_OPTIONS: ["port", "hostname", "protocol", "tls", "silent", "manual", "gracefulShutdown"];
 /**
- * Listener/TLS keys inside the runtime-specific option objects. srvx spreads
- * `node`/`bun`/`deno` *after* its resolved port/host/tls, so these would
- * otherwise bypass {@link RESERVED_SERVER_OPTIONS}. `node.http2` is dropped
- * too: srvx requires a TLS certificate for it, which the worker never has.
+ * srvx spreads `node`/`bun`/`deno` after its resolved listener options, so
+ * these would bypass {@link RESERVED_SERVER_OPTIONS}. `node.http2` needs TLS.
  */
 export declare const RESERVED_RUNTIME_OPTIONS: {
   readonly node: readonly ["port", "host", "path", "http2", "cert", "key", "passphrase"];
   readonly bun: readonly ["port", "hostname", "unix", "tls"];
   readonly deno: readonly ["port", "hostname", "path", "cert", "key"];
 };
-/**
- * Build the srvx `serve()` options for a user entry: forwards every srvx
- * option exported by the entry, drops env-runner specific keys (`fetch`,
- * `upgrade`, `websocket`, `ipc`) and pins the worker-owned listener options
- * (top-level and nested in `node`/`bun`/`deno`). Callers add `fetch` (bound
- * lazily so module reloads swap the handler) and the crossws plugin themselves.
- */
+/** Callers add `fetch` (bound lazily so reloads swap it) and the crossws plugin. */
 export declare function toServerOptions(entry: AppEntry): Omit<ServerOptions, "fetch">;
-export { type AppEntry, type AppEntryIPC, type AppEntryIPCContext, BaseEnvRunner, DenoProcessEnvRunner, type EnvRunnerData as DenoProcessEnvRunnerData, type EnvRunner, type EnvRunnerData, type EnvServerOptions, type FetchHandler, type LoadRunnerOptions, MiniflareEnvRunner, type MiniflareEnvRunnerOptions, type MiniflareExportInfo, NetlifyEnvRunner, type NodeUpgradeContext, type RPCOptions, type RunnerMessageListener, type RunnerName, type RunnerRPCHooks, type RuntimeDep, type TransformResult, type UpgradeContext, type UpgradeHandler, VercelEnvRunner, type VirtualModuleSource, type VirtualModules, type WorkerAddress, type WorkerHooks, resolveRuntimeDep };
+export { type AppEntry, type AppEntryIPC, type AppEntryIPCContext, BaseEnvRunner, DenoProcessEnvRunner, type EnvRunnerData as DenoProcessEnvRunnerData, type EnvRunner, type EnvRunnerData, type EnvServerOptions, type FetchHandler, type LoadRunnerOptions, MiniflareEnvRunner, type MiniflareEnvRunnerOptions, type MiniflareExportInfo, NetlifyEnvRunner, type NodeUpgradeContext, type RPCOptions, type RunnerMessageListener, type RunnerName, type RunnerRPCHooks, type RuntimeDep, type TransformResult, type UpgradeContext, type UpgradeHandler, VercelEnvRunner, type VirtualModule, type VirtualModuleContent, type VirtualModuleFormat, type VirtualModuleSource, type VirtualModuleUpdates, type VirtualModules, type WorkerAddress, type WorkerHooks, resolveRuntimeDep };

package/dist/runners/bun-process/runner.mjs

@@ -1,8 +1,7 @@
 import { BaseEnvRunner } from "../../_chunks/common-base-runner.mjs";
-import { hostEnv } from "../../_chunks/common-host-env.mjs";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
-import { join } from "node:path";
 import { execSync, spawn } from "node:child_process";
 import { homedir } from "node:os";
 let _defaultEntry;
@@ -57,10 +56,7 @@ var BunProcessEnvRunner = class extends BaseEnvRunner {
 			this.close(`process entry not found in "${this._workerEntry}".`);
 			return;
 		}
-		const env = hostEnv({
-			ENV_RUNNER_NAME: this._name,
-			ENV_RUNNER_DATA: JSON.stringify(this._data || {})
-		});
+		const env = this._processEnv();
 		if (_isBun) this.#initBunProcess(execArgv, env);
 		else this.#initNodeProcess(execArgv, env);
 	}
@@ -78,7 +74,7 @@ var BunProcessEnvRunner = class extends BaseEnvRunner {
 				"pipe"
 			],
 			ipc: (message) => {
-				this._handleMessage(message);
+				this._handleProcessMessage(message);
 			}
 		});
 		const child = {
@@ -128,7 +124,7 @@ var BunProcessEnvRunner = class extends BaseEnvRunner {
 			}
 		});
 		child.on("message", (message) => {
-			this._handleMessage(message);
+			this._handleProcessMessage(message);
 		});
 		child.stdout?.pipe(process.stdout);
 		child.stderr?.pipe(process.stderr);

package/dist/runners/bun-process/worker.mjs

@@ -1,16 +1,16 @@
-import { handleInvalidateModule, isVirtualSpecifier, parseServerAddress, registerVirtualModules, reloadEntryModule, resolveEntry, toServerOptions } from "../../_chunks/common-worker-utils.mjs";
+import { formatInitError, handleUpdateVirtualModules, isVirtualEntry, parseServerAddress, registerVirtualModules, reloadEntryModule, resolveEntry, toServerOptions } from "../../_chunks/common-worker-utils.mjs";
+import { receiveProcessData } from "../../_chunks/common-process-data.mjs";
 import { serve } from "srvx";
 import { plugin } from "crossws/server";
 process.on("disconnect", () => process.exit(0));
-const data = JSON.parse(process.env.ENV_RUNNER_DATA || "{}");
+const data = await receiveProcessData();
 const sendMessage = (message) => process.send(message);
-const virtualEntry = isVirtualSpecifier(data.entry, data.virtual);
 let unregisterVirtualModules;
 let entry;
 let server;
 try {
 	unregisterVirtualModules = await registerVirtualModules(data.virtual);
-	entry = await resolveEntry(data.entry, virtualEntry);
+	entry = await resolveEntry(data.entry, isVirtualEntry(data.entry));
 	server = serve({
 		...toServerOptions(entry),
 		fetch: (request) => entry.fetch(request),
@@ -18,7 +18,7 @@ try {
 	});
 	await server.ready();
 } catch (error) {
-	const message = error?.message || String(error);
+	const message = formatInitError(error);
 	sendMessage({
 		event: "init-error",
 		error: message
@@ -45,7 +45,7 @@ process.on("message", async (message) => {
 	}
 	if (message?.event === "reload-module") {
 		try {
-			entry = await reloadEntryModule(data.entry, entry, sendMessage, virtualEntry);
+			entry = await reloadEntryModule(data.entry, entry, sendMessage, isVirtualEntry(data.entry));
 			process.send({ event: "module-reloaded" });
 		} catch (error) {
 			process.send({
@@ -55,8 +55,8 @@ process.on("message", async (message) => {
 		}
 		return;
 	}
-	if (message?.event === "invalidate-module") {
-		handleInvalidateModule(message, sendMessage);
+	if (message?.event === "update-virtual-modules") {
+		handleUpdateVirtualModules(message, sendMessage);
 		return;
 	}
 	if (message?.type === "ping") {

package/dist/runners/deno-process/worker.mjs

@@ -1,17 +1,16 @@
-import { handleInvalidateModule, isVirtualSpecifier, parseServerAddress, registerVirtualModules, reloadEntryModule, resolveEntry, toServerOptions } from "../../_chunks/common-worker-utils.mjs";
+import { formatInitError, handleUpdateVirtualModules, isVirtualEntry, parseServerAddress, registerVirtualModules, reloadEntryModule, resolveEntry, toServerOptions } from "../../_chunks/common-worker-utils.mjs";
+import { receiveProcessData } from "../../_chunks/common-process-data.mjs";
 import { serve } from "srvx";
 import { plugin } from "crossws/server";
-const data = JSON.parse(process.env.ENV_RUNNER_DATA || "{}");
-const _stdout = globalThis.Deno?.stdout ? { write: (s) => globalThis.Deno.stdout.writeSync(new TextEncoder().encode(s)) } : process.stdout;
-const sendMessage = (message) => _stdout.write(JSON.stringify(message) + "\n");
-const _stdin = globalThis.Deno?.stdin?.readable || process.stdin;
-const virtualEntry = isVirtualSpecifier(data.entry, data.virtual);
+process.on("disconnect", () => process.exit(0));
+const data = await receiveProcessData();
+const sendMessage = (message) => process.send(message);
 let unregisterVirtualModules;
 let entry;
 let server;
 try {
 	unregisterVirtualModules = await registerVirtualModules(data.virtual);
-	entry = await resolveEntry(data.entry, virtualEntry);
+	entry = await resolveEntry(data.entry, isVirtualEntry(data.entry));
 	server = serve({
 		...toServerOptions(entry),
 		fetch: (request) => entry.fetch(request),
@@ -19,7 +18,7 @@ try {
 	});
 	await server.ready();
 } catch (error) {
-	const message = error?.message || String(error);
+	const message = formatInitError(error);
 	sendMessage({
 		event: "init-error",
 		error: message
@@ -35,59 +34,38 @@ if (entry.upgrade) server.node?.server?.on("upgrade", (req, socket, head) => {
 	} });
 });
 if (entry.ipc) await entry.ipc.onOpen?.({ sendMessage });
-sendMessage({ address: parseServerAddress(server) });
-async function readMessages() {
-	const decoder = new TextDecoder();
-	let buffer = "";
-	for await (const chunk of _stdin) {
-		buffer += decoder.decode(chunk, { stream: true });
-		let newlineIdx;
-		while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
-			const line = buffer.slice(0, newlineIdx);
-			buffer = buffer.slice(newlineIdx + 1);
-			if (!line) continue;
-			let message;
-			try {
-				message = JSON.parse(line);
-			} catch {
-				continue;
-			}
-			await handleMessage(message);
-		}
-	}
-}
-async function handleMessage(message) {
+process.send({ address: parseServerAddress(server) });
+process.on("message", async (message) => {
 	if (message?.event === "shutdown") {
 		Promise.resolve(entry.ipc?.onClose?.()).then(() => server.close()).then(() => {
 			unregisterVirtualModules();
-			sendMessage({ event: "exit" });
+			process.send({ event: "exit" });
 		});
 		return;
 	}
 	if (message?.event === "reload-module") {
 		try {
-			entry = await reloadEntryModule(data.entry, entry, sendMessage, virtualEntry);
-			sendMessage({ event: "module-reloaded" });
+			entry = await reloadEntryModule(data.entry, entry, sendMessage, isVirtualEntry(data.entry));
+			process.send({ event: "module-reloaded" });
 		} catch (error) {
-			sendMessage({
+			process.send({
 				event: "module-reloaded",
 				error: error?.message || String(error)
 			});
 		}
 		return;
 	}
-	if (message?.event === "invalidate-module") {
-		handleInvalidateModule(message, sendMessage);
+	if (message?.event === "update-virtual-modules") {
+		handleUpdateVirtualModules(message, sendMessage);
 		return;
 	}
 	if (message?.type === "ping") {
-		sendMessage({
+		process.send({
 			type: "pong",
 			data: message.data
 		});
 		return;
 	}
 	entry.ipc?.onMessage?.(message);
-}
-readMessages().catch(() => {});
+});
 export {};

package/dist/runners/node-process/runner.mjs

@@ -1,5 +1,4 @@
 import { BaseEnvRunner } from "../../_chunks/common-base-runner.mjs";
-import { hostEnv } from "../../_chunks/common-host-env.mjs";
 import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
 import { fork } from "node:child_process";
@@ -36,10 +35,7 @@ var NodeProcessEnvRunner = class extends BaseEnvRunner {
 			return;
 		}
 		const child = fork(this._workerEntry, [], {
-			env: hostEnv({
-				ENV_RUNNER_NAME: this._name,
-				ENV_RUNNER_DATA: JSON.stringify(this._data || {})
-			}),
+			env: this._processEnv(),
 			stdio: [
 				"pipe",
 				"pipe",
@@ -57,7 +53,7 @@ var NodeProcessEnvRunner = class extends BaseEnvRunner {
 			this.close(error);
 		});
 		child.on("message", (message) => {
-			this._handleMessage(message);
+			this._handleProcessMessage(message);
 		});
 		child.stdout?.pipe(process.stdout);
 		child.stderr?.pipe(process.stderr);

package/dist/runners/node-process/worker.mjs

@@ -1,16 +1,16 @@
-import { handleInvalidateModule, isVirtualSpecifier, parseServerAddress, registerVirtualModules, reloadEntryModule, resolveEntry, toServerOptions } from "../../_chunks/common-worker-utils.mjs";
+import { formatInitError, handleUpdateVirtualModules, isVirtualEntry, parseServerAddress, registerVirtualModules, reloadEntryModule, resolveEntry, toServerOptions } from "../../_chunks/common-worker-utils.mjs";
+import { receiveProcessData } from "../../_chunks/common-process-data.mjs";
 import { serve } from "srvx";
 import { plugin } from "crossws/server";
 process.on("disconnect", () => process.exit(0));
-const data = JSON.parse(process.env.ENV_RUNNER_DATA || "{}");
+const data = await receiveProcessData();
 const sendMessage = (message) => process.send(message);
-const virtualEntry = isVirtualSpecifier(data.entry, data.virtual);
 let unregisterVirtualModules;
 let entry;
 let server;
 try {
 	unregisterVirtualModules = await registerVirtualModules(data.virtual);
-	entry = await resolveEntry(data.entry, virtualEntry);
+	entry = await resolveEntry(data.entry, isVirtualEntry(data.entry));
 	server = serve({
 		...toServerOptions(entry),
 		fetch: (request) => entry.fetch(request),
@@ -18,7 +18,7 @@ try {
 	});
 	await server.ready();
 } catch (error) {
-	const message = error?.message || String(error);
+	const message = formatInitError(error);
 	sendMessage({
 		event: "init-error",
 		error: message
@@ -45,7 +45,7 @@ process.on("message", async (message) => {
 	}
 	if (message?.event === "reload-module") {
 		try {
-			entry = await reloadEntryModule(data.entry, entry, sendMessage, virtualEntry);
+			entry = await reloadEntryModule(data.entry, entry, sendMessage, isVirtualEntry(data.entry));
 			process.send({ event: "module-reloaded" });
 		} catch (error) {
 			process.send({
@@ -55,8 +55,8 @@ process.on("message", async (message) => {
 		}
 		return;
 	}
-	if (message?.event === "invalidate-module") {
-		handleInvalidateModule(message, sendMessage);
+	if (message?.event === "update-virtual-modules") {
+		handleUpdateVirtualModules(message, sendMessage);
 		return;
 	}
 	if (message?.type === "ping") {

package/dist/runners/node-worker/worker.mjs

@@ -1,16 +1,15 @@
-import { handleInvalidateModule, isVirtualSpecifier, parseServerAddress, registerVirtualModules, reloadEntryModule, resolveEntry, toServerOptions } from "../../_chunks/common-worker-utils.mjs";
+import { formatInitError, handleUpdateVirtualModules, isVirtualEntry, parseServerAddress, registerVirtualModules, reloadEntryModule, resolveEntry, toServerOptions } from "../../_chunks/common-worker-utils.mjs";
 import { parentPort, workerData } from "node:worker_threads";
 import { serve } from "srvx";
 import { plugin } from "crossws/server";
 const data = workerData || {};
 const sendMessage = (message) => parentPort?.postMessage(message);
-const virtualEntry = isVirtualSpecifier(data.entry, data.virtual);
 let unregisterVirtualModules;
 let entry;
 let server;
 try {
 	unregisterVirtualModules = await registerVirtualModules(data.virtual);
-	entry = await resolveEntry(data.entry, virtualEntry);
+	entry = await resolveEntry(data.entry, isVirtualEntry(data.entry));
 	server = serve({
 		...toServerOptions(entry),
 		fetch: (request) => entry.fetch(request),
@@ -18,7 +17,7 @@ try {
 	});
 	await server.ready();
 } catch (error) {
-	const message = error?.message || String(error);
+	const message = formatInitError(error);
 	sendMessage({
 		event: "init-error",
 		error: message
@@ -45,7 +44,7 @@ parentPort?.on("message", async (message) => {
 	}
 	if (message?.event === "reload-module") {
 		try {
-			entry = await reloadEntryModule(data.entry, entry, sendMessage, virtualEntry);
+			entry = await reloadEntryModule(data.entry, entry, sendMessage, isVirtualEntry(data.entry));
 			parentPort?.postMessage({ event: "module-reloaded" });
 		} catch (error) {
 			parentPort?.postMessage({
@@ -55,8 +54,8 @@ parentPort?.on("message", async (message) => {
 		}
 		return;
 	}
-	if (message?.event === "invalidate-module") {
-		handleInvalidateModule(message, sendMessage);
+	if (message?.event === "update-virtual-modules") {
+		handleUpdateVirtualModules(message, sendMessage);
 		return;
 	}
 	if (message?.type === "ping") {

package/dist/runners/self/runner.d.mts

@@ -1,4 +1,4 @@
-import { WorkerHooks } from "../../_chunks/types.mjs";
+import { VirtualModuleUpdates, WorkerHooks } from "../../_chunks/types.mjs";
 import { BaseEnvRunner, EnvRunnerData } from "../../_chunks/common-base-runner.mjs";
 export declare class SelfEnvRunner extends BaseEnvRunner {
   #private;
@@ -16,6 +16,7 @@ export declare class SelfEnvRunner extends BaseEnvRunner {
     };
   }): Promise<void>;
   sendMessage(message: unknown): void;
+  updateVirtualModules(_changes: VirtualModuleUpdates): Promise<void>;
   invalidateModule(specifier: string): Promise<void>;
   reloadModule(): Promise<void>;
   protected _hasRuntime(): boolean;

package/dist/runners/self/runner.mjs

@@ -39,6 +39,9 @@ var SelfEnvRunner = class extends BaseEnvRunner {
 		}
 		this.#entry?.ipc?.onMessage?.(message);
 	}
+	async updateVirtualModules(_changes) {
+		throw new Error("Cannot update virtual modules: the self runner does not support virtual modules");
+	}
 	async invalidateModule(specifier) {
 		throw new Error(`Cannot invalidate "${specifier}": the self runner does not support virtual modules`);
 	}
@@ -79,8 +82,13 @@ var SelfEnvRunner = class extends BaseEnvRunner {
 			this.close("self runner requires data.entry");
 			return;
 		}
+		if (Object.keys(this._data?.virtual ?? {}).length > 0) {
+			this.close(/* @__PURE__ */ new Error("Cannot use data.virtual: the self runner does not support virtual modules"));
+			return;
+		}
 		this.#active = true;
 		resolveEntry(entryPath).then(async (entry) => {
+			if (this.closed) return;
 			this.#entry = entry;
 			await entry.ipc?.onOpen?.({ sendMessage: (message) => {
 				queueMicrotask(() => this._handleMessage(message));

package/dist/runners/vercel/queue-dev.d.mts

@@ -20,11 +20,7 @@ export type VercelQueueRetryDirective = {
 export type VercelQueueMessageHandler<T = unknown> = (message: T, metadata: VercelQueueMessageMetadata) => Promise<void> | void;
 /** Called when the message handler throws (`RetryHandler`). */
 export type VercelQueueRetryHandler = (error: unknown, metadata: VercelQueueMessageMetadata) => VercelQueueRetryDirective | void | undefined;
-/**
- * The `@vercel/queue` package, as imported by the consumer
- * (`import * as queue from "@vercel/queue"`). Structurally typed so the real
- * module namespace is assignable without env-runner depending on the package.
- */
+/** `@vercel/queue` namespace, structurally typed to avoid depending on the package. */
 export interface VercelQueueSdk {
   QueueClient: new (options?: any) => any;
   registerDevConsumer?: (options: {
@@ -39,20 +35,8 @@ export interface VercelQueueSdk {
 }
 export interface VercelQueueDevConsumer {
   /**
-   * The `@vercel/queue` package: the imported module, or a specifier for it.
-   *
-   * ```ts
-   * import * as sdk from "@vercel/queue";
-   * await registerVercelQueueConsumer({ sdk, topic: "orders", handler });
-   *
-   * // or, equivalently
-   * await registerVercelQueueConsumer({ sdk: "@vercel/queue", topic, handler });
-   * ```
-   *
-   * Passing it explicitly is preferred (`@vercel/queue` is not a dependency of
-   * `env-runner`). Bare specifiers resolve from the current working directory.
-   * When omitted, `@vercel/queue` is imported optionally and registration
-   * becomes a no-op if the package isn't installed.
+   * The `@vercel/queue` package (`import * as sdk from "@vercel/queue"`) or a
+   * specifier resolved from cwd. Omitted: imported optionally.
    */
   sdk?: RuntimeDep<VercelQueueSdk>;
   /** Topic name. Wildcard patterns (e.g. `"user-*"`) are supported. */
@@ -60,39 +44,19 @@ export interface VercelQueueDevConsumer {
   /** Function invoked with each delivered message. */
   handler: VercelQueueMessageHandler;
   /**
-   * Logical consumer identifier. Re-registering with the same group on the same
-   * topic replaces the previous handler (HMR-safe). Use distinct groups to fan
-   * a topic out to multiple coexisting handlers.
-   *
+   * Same group + topic replaces the handler; distinct groups coexist.
    * @default "env-runner-vercel-dev"
    */
   consumerGroup?: string;
-  /**
-   * Lock duration for in-flight messages. Forwarded to the SDK's
-   * `coreHandleCallback`.
-   */
+  /** Lock duration for in-flight messages (SDK `coreHandleCallback`). */
   visibilityTimeoutSeconds?: number;
-  /**
-   * Convenience: rescheduled re-delivery delay applied when the handler throws.
-   * Equivalent to `retry: () => ({ afterSeconds })`. Ignored if `retry` is set.
-   */
+  /** Re-delivery delay when the handler throws; shorthand for `retry` (which wins). */
   retryAfterSeconds?: number;
-  /**
-   * Full retry handler. Receives the thrown error and message metadata; return
-   * `{ afterSeconds }` to reschedule, `{ acknowledge: true }` to drop, or
-   * `undefined` to let the error propagate.
-   */
+  /** Return `{ afterSeconds }` to reschedule, `{ acknowledge: true }` to drop, or `undefined` to rethrow. */
   retry?: VercelQueueRetryHandler;
 }
 /**
- * Bind a handler to a topic. Resolves to an unregister function.
- *
- * A shared `QueueClient` is constructed from `sdk` on first use and reused for
- * later registrations with the same SDK. Re-registering with the same topic
- * replaces the handler (HMR-safe; the SDK keys consumers by `consumerGroup`,
- * so calling unregister on a replaced registration is a no-op).
- *
- * If no SDK is available, or it does not expose `registerDevConsumer`,
- * resolves to a no-op unregister and logs a one-time warning.
+ * Bind a handler to a topic; resolves to an unregister function (a no-op once
+ * replaced). Without a usable SDK, warns once and no-ops.
  */
 export declare function registerVercelQueueConsumer(consumer: VercelQueueDevConsumer): Promise<() => void>;

package/dist/vite.d.mts

@@ -12,17 +12,7 @@ export interface ViteTransport {
   }) => void;
   send: (payload: any) => void;
 }
-/**
- * Create a Vite `HotChannel` from an env-runner's RPC hooks.
- *
- * Use on the **host side** to bridge env-runner IPC → Vite's DevEnvironment transport.
- * Messages are namespaced by `envName` so multiple Vite environments can share one runner.
- */
+/** Host-side Vite `HotChannel`, namespaced by `envName` so environments can share a runner. */
 export declare function createViteHotChannel(hooks: RunnerRPCHooks, envName: string): ViteHotChannel;
-/**
- * Create a Vite `ModuleRunner` transport from worker-side IPC primitives.
- *
- * Use on the **worker side** to bridge worker IPC → Vite's `ModuleRunner` transport.
- * Filters messages by `envName` so multiple Vite environments can share one IPC channel.
- */
+/** Worker-side Vite `ModuleRunner` transport, filtered by `envName` to share one IPC channel. */
 export declare function createViteTransport(sendMessage: (data: any) => void, onMessage: (listener: (value: any) => void) => void, envName: string): ViteTransport;