@moostjs/vite 0.6.35 → 0.6.37

package/README.md

@@ -3,6 +3,7 @@
 Vite dev plugin for [Moost](https://moost.org). Enables hot module replacement for Moost HTTP applications during development, automatic adapter detection, and production build configuration.
 
 Supports two modes:
+
 - **Backend mode** (default) — Moost owns the server, Vite provides HMR and TypeScript transforms
 - **Middleware mode** — Vite serves the frontend (Vue, React, etc.), Moost handles API routes as middleware
 
@@ -217,6 +218,10 @@ ssr: {
 
 When you use an explicit `noExternal` list, the plugin automatically keeps the **moost/wooks runtime** (`moost`, `@moostjs/*`, `@wooksjs/*`, `wooks`) bundled alongside your listed packages, so there is always a single runtime instance. This avoids a subtle production-only failure: if any `noExternal` package imports `@wooksjs/*` (e.g. `@aooth/*` and other `.as`-shipping libs do), it would otherwise pull in a second copy while externalized `moost` uses the first — splitting the event context so `useRequest()` / `useHeaders()` / `useAuthorization()` read `undefined`. If you would rather externalize the runtime instead, list it under `ssr.external` (e.g. `['@wooksjs/event-http', '@wooksjs/event-core', 'wooks', ...]`) and add those packages as direct dependencies — the plugin detects an externalized runtime and leaves your all-external setup intact.
 
+The guard works in one direction only, and the runtime is not the only package that keeps module-level state — the `@atscript/*` family (`core`, `typescript`, `db` and its adapters, moost-db, the UI packages) relies on registries and class identity too. The mirror case is on you: a bundled shared package plus an external package that depends on it loads a second copy from `node_modules` and fails the same way — a lib calling wooks composables (`useRequest()`, `useHeaders()`, …) that wasn't in your `noExternal` list (or was put in `ssr.external`), or `@atscript/db-mysql` / `@atscript/db-sqlite` externalized while `@atscript/db` is bundled, where the adapter's `instanceof` check fails and it silently creates an empty table instead of the declared view. **A shared-state package is either entirely bundled or entirely external, together with everything that depends on it** — whatever `pnpm why @wooksjs/event-http` (or `pnpm why @atscript/db`) lists sits on the same side as the package itself. Never split.
+
+After the SSR build the plugin checks for exactly that: it compares the packages inlined into `dist/server` with the bare imports left in it and warns when any externalized package (or one of its transitive dependencies) depends on a bundled watched package — `moost` / `@moostjs/*` / `@wooksjs/*` / `wooks` / `@atscript/*` by default — naming the package and the fix. `ssrExternalCheck: { packages: ['some-registry-lib', '@acme/', /^my-lib-/] }` watches more (exact name, scope prefix, `RegExp`); `ssrExternalCheck: false` silences it. The symptoms of a split are `TypeError: Cannot read properties of undefined (reading 'headers')` (or any header name) from inside a composable, and an empty table where a managed view was declared — production only. Source-level tests share one module graph and cannot see it: verify on the installed build. Full explanation and a manual verification recipe: [SSR Bundle Size](https://moost.org/webapp/vite#ssr-bundle-size).
+
 ## SSR Local Fetch
 
 When `ssrFetch` is enabled (default: `true`), the plugin patches `globalThis.fetch` so that local paths are routed in-process through Moost instead of making a real HTTP request. This is useful for SSR where server-side code fetches from its own API:
@@ -244,25 +249,26 @@ The plugin injects a `__VITE_ID` decorator on `@Injectable` and `@Controller` cl
 
 ## Options
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `entry` | `string` | — | Application entry file (required) |
-| `port` | `number` | `3000` | Dev server port (backend mode only) |
-| `host` | `string` | `'localhost'` | Dev server host (backend mode only) |
-| `outDir` | `string` | `'dist'` | Build output directory (backend mode only) |
-| `format` | `'cjs' \| 'esm'` | `'esm'` | Output module format (backend mode only) |
-| `sourcemap` | `boolean` | `true` | Generate source maps (both modes; in middleware mode applies to the `dist/server` SSR build) |
-| `externals` | `boolean \| object` | `true` | Configure external dependencies (backend mode only) |
-| `onEject` | `function` | — | Hook to control DI instance ejection during HMR |
-| `ssrFetch` | `boolean` | `true` | Enable local fetch interception for SSR |
-| `middleware` | `boolean` | `false` | Run Moost as Connect middleware (Vite serves frontend) |
-| `prefix` | `string` | `'/api'` (prod server) | URL prefix filter for middleware mode (e.g. `'/api'`); the production server defaults to `'/api'` when omitted |
-| `ssrEntry` | `string` | — | Vue/React SSR entry module (e.g. `'/src/entry-server.ts'`) |
-| `ssrOutlet` | `string` | `'<!--ssr-outlet-->'` | HTML placeholder for SSR-rendered content |
-| `ssrState` | `string` | `'<!--ssr-state-->'` | HTML placeholder for SSR state transfer script |
-| `ssrHead` | `string` | `'<!--ssr-head-->'` | HTML placeholder for SSR-rendered `<head>` tags (place inside `<head>`) |
-| `serverEntry` | `string` | — | Custom production server entry file (e.g. `'./server.ts'`) |
-| `ssrExternal` | `string[]` | — | Packages to keep external in the SSR build (middleware mode, `vite build` only). Concatenated with `cfg.ssr.external`. See [SSR Bundle Size](#ssr-bundle-size). |
+| Option             | Type                                             | Default                | Description                                                                                                                                                                                                                                      |
+| ------------------ | ------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `entry`            | `string`                                         | —                      | Application entry file (required)                                                                                                                                                                                                                |
+| `port`             | `number`                                         | `3000`                 | Dev server port (backend mode only)                                                                                                                                                                                                              |
+| `host`             | `string`                                         | `'localhost'`          | Dev server host (backend mode only)                                                                                                                                                                                                              |
+| `outDir`           | `string`                                         | `'dist'`               | Build output directory (backend mode only)                                                                                                                                                                                                       |
+| `format`           | `'cjs' \| 'esm'`                                 | `'esm'`                | Output module format (backend mode only)                                                                                                                                                                                                         |
+| `sourcemap`        | `boolean`                                        | `true`                 | Generate source maps (both modes; in middleware mode applies to the `dist/server` SSR build)                                                                                                                                                     |
+| `externals`        | `boolean \| object`                              | `true`                 | Configure external dependencies (backend mode only)                                                                                                                                                                                              |
+| `onEject`          | `function`                                       | —                      | Hook to control DI instance ejection during HMR                                                                                                                                                                                                  |
+| `ssrFetch`         | `boolean`                                        | `true`                 | Enable local fetch interception for SSR                                                                                                                                                                                                          |
+| `middleware`       | `boolean`                                        | `false`                | Run Moost as Connect middleware (Vite serves frontend)                                                                                                                                                                                           |
+| `prefix`           | `string`                                         | `'/api'` (prod server) | URL prefix filter for middleware mode (e.g. `'/api'`); the production server defaults to `'/api'` when omitted                                                                                                                                   |
+| `ssrEntry`         | `string`                                         | —                      | Vue/React SSR entry module (e.g. `'/src/entry-server.ts'`)                                                                                                                                                                                       |
+| `ssrOutlet`        | `string`                                         | `'<!--ssr-outlet-->'`  | HTML placeholder for SSR-rendered content                                                                                                                                                                                                        |
+| `ssrState`         | `string`                                         | `'<!--ssr-state-->'`   | HTML placeholder for SSR state transfer script                                                                                                                                                                                                   |
+| `ssrHead`          | `string`                                         | `'<!--ssr-head-->'`    | HTML placeholder for SSR-rendered `<head>` tags (place inside `<head>`)                                                                                                                                                                          |
+| `serverEntry`      | `string`                                         | —                      | Custom production server entry file (e.g. `'./server.ts'`)                                                                                                                                                                                       |
+| `ssrExternal`      | `string[]`                                       | —                      | Packages to keep external in the SSR build (middleware mode, `vite build` only). Concatenated with `cfg.ssr.external`. See [SSR Bundle Size](#ssr-bundle-size).                                                                                  |
+| `ssrExternalCheck` | `boolean \| { packages?: (string \| RegExp)[] }` | `true`                 | Warn after the middleware-mode SSR build when an externalized package depends on a bundled shared-state package (`moost`, `@moostjs/*`, `wooks`, `@wooksjs/*`, `@atscript/*`); `packages` watches more. See [SSR Bundle Size](#ssr-bundle-size). |
 
 Options marked "backend mode only" are ignored when `middleware: true` — the user's `vite.config.ts` controls build/server configuration in middleware mode.
 

package/dist/index.cjs

@@ -249,19 +249,63 @@ function _define_property(obj, key, value) {
 * A reference to a shared LogsStorage instance that persists
 * across init cycles in dev mode.
 */ let logsStorage;
+/** Whether {@link patchMoostHandlerLogging} already installed its wrappers in this process. */ let installed = false;
 /**
-* Patches Moost’s .init() and .logMappedHandler() methods so that, during dev:
+* The slot {@link captureMoostInit} fills: receives every `init()` promise the
+* wrapper below produces. Unset in prod/test, where nothing consumes a capture.
+*/ let onInitCaptured;
+/**
+* Hands every `Moost.prototype.init()` promise to `onCapture`, letting a boot
+* await the app's **initialization** instead of only its module evaluation.
+*
+* The documented entry shape is `app.adapter(http).listen(port)` followed by an
+* **un-awaited** `app.init()`: the HTTP middleware is therefore captured *before*
+* init finishes, and nothing else observes a rejecting init — a bind error, a DI
+* audit error or a throwing `@MoostInit` hook would leave the dev server serving
+* a half-booted app (the routes bound before the failure answer 200, the rest
+* fall through to the SPA fallback) instead of the plugin's 502. That is also
+* why the plugin's `bootError` gate runs BEFORE the captured middleware, and why
+* the SSR fallback checks it too: `listen()` ran first and left both a middleware
+* and the local-fetch hook behind.
+*
+* Patches the plugin's **own** `moost` import, exactly like the handler logging
+* does: in dev the runtime is externalized, so the plugin and the app share one
+* native `moost` instance (the premise the DI eject in `restart-cleanup` rests on
+* too, and what `ssrExternalCheck` warns about when it stops holding). Unlike the
+* adapters there is nothing to re-establish per reload — a static import is never
+* re-evaluated — and unlike them it must NOT be pulled through the SSR module
+* runner: importing `moost` there registers it as the runner's first module and
+* makes subsequent hot updates re-evaluate the entry only, serving every one of
+* its dependencies (controllers included) from the stale cache.
+*
+* There is exactly ONE `init` wrapper per process (installed by
+* {@link patchMoostHandlerLogging}) and this only fills its slot, so the newest
+* plugin instance wins: Vite re-imports the config on every config-file
+* `server.restart()`, re-running the plugin factory, and a per-instance wrapper
+* would stack on the previous one and keep the dead instance's scope alive.
+*
+* @param onCapture receives each captured init promise (already marked handled).
+*/ function captureMoostInit(onCapture) {
+	onInitCaptured = onCapture;
+}
+/**
+* Patches Moost’s .init() and .logMappedHandler() methods — once per process —
+* so that, during dev:
 * - Only newly added handlers are logged normally.
 * - Removed handlers are logged/stroked out to indicate removal.
 * - Prevents repeated logs from flooding the console across multiple hot reloads.
+* - Every init() promise reaches the {@link captureMoostInit} slot, if filled.
 */ function patchMoostHandlerLogging() {
+	if (installed) return;
+	installed = true;
 	const origInit = moost.Moost.prototype.init;
+	const origLogMappedHandler = moost.Moost.prototype.logMappedHandler;
 	/**
-	* Monkey-patch Moost.init:
+	* The logging body of the patched Moost.init:
 	* 1. Start a new recording cycle in LogsStorage.
 	* 2. Call the real .init().
 	* 3. End the recording, logging any removed handlers.
-	*/ moost.Moost.prototype.init = async function init() {
+	*/ const initWithLogging = async function() {
 		if (!logsStorage) logsStorage = new LogsStorage();
 		logsStorage.startRecording();
 		await origInit.call(this);
@@ -269,7 +313,14 @@ function _define_property(obj, key, value) {
 			origLogMappedHandler.call(this, item.eventName, item.classConstructor, item.method, true, "❌ ");
 		});
 	};
-	const origLogMappedHandler = moost.Moost.prototype.logMappedHandler;
+	moost.Moost.prototype.init = function init() {
+		const promise = initWithLogging.call(this);
+		if (onInitCaptured) {
+			promise.catch(() => {});
+			onInitCaptured(promise);
+		}
+		return promise;
+	};
 	/**
 	* Monkey-patch Moost.logMappedHandler:
 	* If we haven’t seen this particular route+class+method combination
@@ -289,14 +340,23 @@ function _define_property(obj, key, value) {
 /**
 * Clean up Moost’s global containers and optionally remove specific instances from the registry.
 *
+* Every instance actually removed from a registry is **disposed** before the
+* caches are dropped: its `@MoostDispose` hooks (or `Symbol.asyncDispose` /
+* `Symbol.dispose`) are awaited, so a singleton owning a connection, consumer,
+* timer or file handle releases it instead of leaking one copy per reload. An
+* instance kept by an `onEject` veto is never disposed. A failing hook is
+* warned about and the reload continues.
+*
 * @param {Set<string>} [cleanupInstances] A set of module IDs to remove from the registry.
-*/ function moostRestartCleanup(adapters, onEject, cleanupInstances) {
+* @returns the instances that were ejected (and therefore disposed)
+*/ async function moostRestartCleanup(adapters, onEject, cleanupInstances) {
 	const logger = getLogger();
 	const infact = (0, moost.getMoostInfact)();
 	const { registry, scopes } = infact;
 	const registries = [registry, ...Object.values(scopes)];
 	infact._cleanup();
 	const mate = (0, moost.getMoostMate)();
+	/** Instances removed from a registry by this run — disposed below, before the caches drop. */ const ejected = [];
 	if (cleanupInstances) {
 		for (const reg of registries) {
 			for (const key of Object.getOwnPropertySymbols(reg)) {
@@ -305,6 +365,7 @@ function _define_property(obj, key, value) {
 				if (viteId && cleanupInstances.has(viteId)) {
 					logger.debug(`🔃 Replacing "${constructorName(instance)}"`);
 					delete reg[key];
+					ejected.push(instance);
 				}
 			}
 			for (const key of Object.getOwnPropertySymbols(reg)) {
@@ -312,25 +373,39 @@ function _define_property(obj, key, value) {
 				scanParams(instance, (type) => {
 					if ((type === moost.Moost || type instanceof moost.Moost || type.prototype instanceof moost.Moost) && (!onEject || onEject(instance, type))) {
 						delete reg[key];
+						ejected.push(instance);
 						logger.debug(`✖️  Ejecting "${constructorName(instance)}" (depends on re-instantiated "Moost")`);
 						return true;
 					}
 					for (const adapter of adapters) if (adapter.compare(type) && (!onEject || onEject(instance, type))) {
 						delete reg[key];
+						ejected.push(instance);
 						logger.debug(`✖️  Ejecting "${constructorName(instance)}" (depends on re-instantiated "${adapter.constructor.name}")`);
 						return true;
 					}
 				});
 			}
-			clearDependantRegistry(reg, onEject);
+			clearDependantRegistry(reg, onEject, ejected);
 		}
 		infact.registry = registry;
 		infact.scopes = scopes;
 	}
+	await disposeEjected(ejected);
 	(0, moost.getMoostMate)()._cleanup();
 	(0, moost.clearGlobalWooks)();
+	return ejected;
 }
-function clearDependantRegistry(registry, onEject) {
+/** Awaits the `@MoostDispose` hooks of the ejected instances; never throws. */ async function disposeEjected(ejected) {
+	if (ejected.length === 0) return;
+	const logger = getLogger();
+	const { disposed, errors } = await (0, moost.disposeInstances)(ejected, {
+		logger,
+		onError: "warn"
+	});
+	for (const instance of disposed) logger.debug(`♻️  Disposed "${constructorName(instance)}"`);
+	for (const e of errors) logger.warn(`⚠️  Dispose hook "${constructorName(e.instance)}.${String(e.method)}" failed — the reload continues`);
+}
+function clearDependantRegistry(registry, onEject, ejected) {
 	const logger = getLogger();
 	const objSet = /* @__PURE__ */ new Set();
 	let somethingIsDeleted = true;
@@ -342,7 +417,10 @@ function clearDependantRegistry(registry, onEject) {
 		}
 		for (const key of Object.getOwnPropertySymbols(registry)) {
 			const instance = registry[key];
-			if (checkAndEject(instance, objSet, onEject, registry, key, logger)) somethingIsDeleted = true;
+			if (checkAndEject(instance, objSet, onEject, registry, key, logger)) {
+				ejected.push(instance);
+				somethingIsDeleted = true;
+			}
 		}
 	}
 }
@@ -375,6 +453,173 @@ function constructorName(i) {
 	return Object.getPrototypeOf(i).constructor.name;
 }
 
+//#endregion
+//#region packages/vite/src/ssr-externals-check.ts
+/**
+* Packages that make up the moost/wooks runtime. They mint per-module Symbol
+* slot keys, so the whole set must resolve to a single module instance in the
+* production SSR graph. This is the scope of the single-instance *guard*
+* (force-bundling under an explicit `noExternal` list) — the build *check*
+* watches the wider {@link SHARED_STATE_PACKAGE_PATTERNS}.
+*/ const RUNTIME_PACKAGE_PATTERNS = [
+	/^moost($|\/)/,
+	/^@moostjs\//,
+	/^@wooksjs\//,
+	/^wooks($|\/)/
+];
+/**
+* Packages the build check watches by default: the moost/wooks runtime plus the
+* `@atscript/*` family. All of them keep module-level state — Symbol slot keys,
+* DI/model registries, class identity used by `instanceof` — so a second copy
+* loaded by Node breaks lookups that the bundled copy filled in.
+*
+* This is deliberately wider than {@link RUNTIME_PACKAGE_PATTERNS}: the guard
+* that force-bundles packages covers the runtime only, while the check merely
+* reports what the output shows.
+*/ const SHARED_STATE_PACKAGE_PATTERNS = [...RUNTIME_PACKAGE_PATTERNS, /^@atscript\//];
+function escapeRegExp(input) {
+	return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Build the watched-package patterns for the check: the defaults plus the
+* user's extras. A `RegExp` is used as is, a string ending with `/` matches a
+* scope/prefix (`'@acme/'` → every `@acme/*` package), any other string is an
+* exact package name.
+*/ function compilePackagePatterns(extra) {
+	const patterns = [...SHARED_STATE_PACKAGE_PATTERNS];
+	for (const item of extra ?? []) if (item instanceof RegExp) patterns.push(item);
+	else if (item.endsWith("/")) patterns.push(new RegExp(`^${escapeRegExp(item)}`));
+	else patterns.push(new RegExp(`^${escapeRegExp(item)}$`));
+	return patterns;
+}
+const BUILTINS = new Set(node_module.builtinModules);
+/** Bare npm package name of an import specifier (`vue/server-renderer` → `vue`). */ function npmPackageName(id) {
+	if (!id || id.startsWith(".") || id.startsWith("/") || id.startsWith("\0")) return;
+	if (id.startsWith("node:") || id.startsWith("data:") || id.startsWith("virtual:")) return;
+	const parts = id.split("/");
+	const name = id.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+	if (!name || id.startsWith("@") && parts.length < 2) return;
+	return BUILTINS.has(name) ? void 0 : name;
+}
+/**
+* Package names the bundler inlined into the output, derived from the module
+* ids of the emitted chunks. Ids under `node_modules` name their package after
+* the LAST `node_modules/` segment, which also yields the right name for pnpm
+* store paths (`…/node_modules/.pnpm/pkg@1.0.0/node_modules/pkg/index.mjs`).
+* Virtual ids and app sources (no `node_modules`) are ignored.
+*/ function bundledPackagesFromModuleIds(moduleIds) {
+	const packages = /* @__PURE__ */ new Set();
+	const marker = "/node_modules/";
+	for (const raw of moduleIds) {
+		if (!raw || raw.startsWith("\0")) continue;
+		const id = raw.replaceAll("\\", "/");
+		const at = id.lastIndexOf(marker);
+		if (at === -1) continue;
+		const name = npmPackageName(id.slice(at + 14));
+		if (name) packages.add(name);
+	}
+	return packages;
+}
+function readPkgJson(dir) {
+	try {
+		return JSON.parse((0, node_fs.readFileSync)((0, node_path.join)(dir, "package.json"), "utf8"));
+	} catch {
+		return;
+	}
+}
+/**
+* Locate `name`'s package directory the way Node would from `fromDir`:
+* `<fromDir>/node_modules/<name>`, then each ancestor's `node_modules`.
+* Returns the realpath so pnpm's symlinked layout resolves to the store entry,
+* whose own `node_modules` sibling holds the package's dependencies.
+*/ function findPackageDir(name, fromDir) {
+	let dir = fromDir;
+	for (;;) {
+		const candidate = (0, node_path.join)(dir, "node_modules", name);
+		if ((0, node_fs.existsSync)((0, node_path.join)(candidate, "package.json"))) try {
+			return (0, node_fs.realpathSync)(candidate);
+		} catch {
+			return candidate;
+		}
+		const parent = (0, node_path.dirname)(dir);
+		if (parent === dir) return;
+		dir = parent;
+	}
+}
+/** Deps of `pkg` that are watched packages AND were bundled into the output. */ function splitDepsOf(pkg, patterns, bundledPackages) {
+	const names = /* @__PURE__ */ new Set();
+	for (const group of [
+		pkg.dependencies,
+		pkg.peerDependencies,
+		pkg.optionalDependencies
+	]) for (const dep of Object.keys(group ?? {})) if (bundledPackages.has(dep) && patterns.some((re) => re.test(dep))) names.add(dep);
+	return [...names];
+}
+/** Upper bound on visited packages — keeps a pathological tree from stalling the build. */ const MAX_VISITED = 5e3;
+/**
+* Given the bare specifiers left in the SSR build output (i.e. the packages the
+* bundler externalized) and the package names it bundled, find every package
+* Node will load at runtime that depends on a bundled shared-state package.
+* Such a package resolves its own copy from `node_modules` while the bundled
+* copy lives inside `dist/server` — two instances, split module state.
+*
+* Walks the dependency tree beneath each external (Node loads a package's deps
+* from its own resolution root, so transitive consumers matter too), but never
+* descends into a bundled dep: the fix belongs to the external consumer.
+* Packages that are not installed are skipped silently.
+*/ function findSplitPackages(opts) {
+	const patterns = opts.patterns ?? SHARED_STATE_PACKAGE_PATTERNS;
+	const found = [];
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [];
+	for (const id of opts.externalIds) {
+		const name = npmPackageName(id);
+		if (name && !visited.has(`root:${name}`)) {
+			visited.add(`root:${name}`);
+			queue.push({
+				name,
+				fromDir: opts.root,
+				via: []
+			});
+		}
+	}
+	while (queue.length > 0 && visited.size < MAX_VISITED) {
+		const { name, fromDir, via } = queue.shift();
+		const dir = findPackageDir(name, fromDir);
+		if (!dir || visited.has(dir)) continue;
+		visited.add(dir);
+		const pkg = readPkgJson(dir);
+		if (!pkg) continue;
+		const splitDeps = splitDepsOf(pkg, patterns, opts.bundledPackages);
+		if (splitDeps.length > 0) found.push({
+			name,
+			via,
+			splitDeps
+		});
+		for (const dep of Object.keys(pkg.dependencies ?? {})) if (!opts.bundledPackages.has(dep)) queue.push({
+			name: dep,
+			fromDir: dir,
+			via: [...via, name]
+		});
+	}
+	return found;
+}
+/** Human-readable build warning for {@link findSplitPackages} results. */ function formatSplitPackagesWarning(splits) {
+	const lines = splits.map((s) => {
+		const chain = s.via.length > 0 ? ` (loaded via external ${s.via.join(" → ")})` : "";
+		const deps = s.splitDeps.map((d) => `${d} (bundled)`).join(", ");
+		return `  - ${s.name}${chain} depends on ${deps}`;
+	});
+	const direct = [...new Set(splits.map((s) => s.via.length > 0 ? s.via[0] : s.name))];
+	return [
+		"These externalized packages depend on packages that are bundled into dist/server, so Node will load a second copy of them from node_modules:",
+		...lines,
+		"Two copies of a package split its module state — event-context slots, DI registries and class identity (instanceof) stop matching across the boundary, in production only. Symptoms: \"Cannot read properties of undefined (reading 'headers')\" inside a wooks composable, or a database adapter creating an empty table where a managed view was declared.",
+		`Fix: keep each shared package and everything that depends on it on the same side — add ${direct.map((d) => `'${d}'`).join(", ")} to ssr.noExternal (or drop them from ssr.external / ssrExternal), or externalize the whole family (for example every @atscript/* package, or the whole moost/wooks runtime) via ssr.external.`,
+		"Set ssrExternalCheck: false in moostVite() to silence this check, or ssrExternalCheck: { packages: [...] } to watch more packages."
+	].join("\n");
+}
+
 //#endregion
 //#region packages/vite/src/moost-vite.ts
 /** Regex checks */ const REG_HAS_EXPORT_CLASS = /(^\s*@(Injectable|Controller)\()/m;
@@ -408,6 +653,22 @@ function generatedServerEntry(root) {
 	(0, node_fs.writeFileSync)(entryPath, DEFAULT_SERVER_ENTRY_CODE);
 	return entryPath;
 }
+/**
+* Read the emitted SSR bundle: the packages inlined into it (from every chunk's
+* module ids) and the bare specifiers it still imports (the externalized ones).
+*/ function scanSsrBundle(bundle) {
+	const externalIds = /* @__PURE__ */ new Set();
+	const moduleIds = [];
+	for (const chunk of Object.values(bundle)) {
+		if (chunk.type !== "chunk") continue;
+		moduleIds.push(...chunk.moduleIds ?? []);
+		for (const id of [...chunk.imports ?? [], ...chunk.dynamicImports ?? []]) if (!(id in bundle) && npmPackageName(id)) externalIds.add(id);
+	}
+	return {
+		externalIds,
+		bundledPackages: bundledPackagesFromModuleIds(moduleIds)
+	};
+}
 function moostVite(options) {
 	const isTest = process.env.NODE_ENV === "test";
 	const isProd = process.env.NODE_ENV === "production";
@@ -433,6 +694,11 @@ function moostVite(options) {
 	*/ let bootGeneration = 0;
 	let bootingGeneration = 0;
 	/** Whether the HTTP listen() patch has ever captured a middleware (i.e. this is an HTTP app). */ let httpCaptured = false;
+	/**
+	* The `app.init()` promises the current boot handed us (see `captureMoostInit`) —
+	* several when one entry boots several apps, none for a boot that never calls
+	* `init()`. Reset by `beginBoot()`, consumed by `settleBootInit()`.
+	*/ let bootInitPromises = [];
 	/** Module IDs awaiting DI cleanup — consumed in runReload; see ejectApp. */ let pendingCleanup = null;
 	/** In middleware mode: maps req → next() for the onNoMatch callback */ const pendingNextMap = /* @__PURE__ */ new WeakMap();
 	const adapters = isTest ? [] : [
@@ -502,6 +768,43 @@ function moostVite(options) {
 		reloadRequired = true;
 	};
 	patchMoostHandlerLogging();
+	if (!isTest && !isProd) captureMoostInit((promise) => {
+		if (bootingGeneration !== bootGeneration) {
+			logger.error(`⚠️  A stale Moost boot called init() (boot generation ${bootingGeneration}, latest ${bootGeneration}) — an HMR reload race; a follow-up reload will replace it.`);
+			return;
+		}
+		bootInitPromises.push(promise);
+	});
+	/** Marks the boot about to run as authoritative for the current generation. */ const beginBoot = () => {
+		bootingGeneration = bootGeneration;
+		bootInitPromises = [];
+	};
+	/**
+	* Finishes a boot: awaits the `init()` promise(s) the entry that just executed
+	* handed us, so the boot is only "done" once the app is fully initialized —
+	* every controller bound, every `@MoostInit` hook run (see `captureMoostInit`).
+	* Owns `bootError`: cleared on success, set and logged when an init rejected;
+	* returns whether the boot succeeded.
+	*/ const settleBootInit = async () => {
+		const initPromises = bootInitPromises;
+		bootInitPromises = [];
+		try {
+			await Promise.all(initPromises);
+			bootError = null;
+			return true;
+		} catch (error) {
+			bootError = error;
+			logger.error(`✖️  Moost app init failed: ${error.message}`);
+			return false;
+		}
+	};
+	/** Answers a request while `bootError` is set (see the gate in configureServer). */ const answerBootError = (res) => {
+		res.statusCode = 502;
+		res.setHeader("Content-Type", "text/plain");
+		res.end(`Moost app failed to load: ${bootError.message}`);
+	};
+	/** Set by the middleware-mode `config` hook: the consumer externalized the runtime themselves. */ let runtimeExternalized = false;
+	let resolvedConfig;
 	const pluginConfig = {
 		name: PLUGIN_NAME,
 		enforce: "pre",
@@ -534,14 +837,8 @@ function moostVite(options) {
 				let ssrNoExternal = userNoExternal === true ? true : userNoExternal !== void 0 ? [...Array.isArray(userNoExternal) ? userNoExternal : [userNoExternal], ourPlugin] : isBuild ? true : [ourPlugin];
 				const userExternal = cfg.ssr?.external;
 				const ssrExternal = isBuild ? [...Array.isArray(userExternal) ? userExternal : [], ...options.ssrExternal ?? []] : void 0;
-				const runtimeNoExternal = [
-					/^moost($|\/)/,
-					/^@moostjs\//,
-					/^@wooksjs\//,
-					/^wooks($|\/)/
-				];
-				const runtimeExternalized = (ssrExternal ?? []).some((e) => typeof e === "string" && runtimeNoExternal.some((re) => re.test(e)));
-				if (isBuild && Array.isArray(ssrNoExternal) && !runtimeExternalized) ssrNoExternal = [...ssrNoExternal, ...runtimeNoExternal];
+				runtimeExternalized = (ssrExternal ?? []).some((e) => typeof e === "string" && RUNTIME_PACKAGE_PATTERNS.some((re) => re.test(e)));
+				if (isBuild && Array.isArray(ssrNoExternal) && !runtimeExternalized) ssrNoExternal = [...ssrNoExternal, ...RUNTIME_PACKAGE_PATTERNS];
 				return {
 					...options.ssrEntry && { appType: "custom" },
 					ssr: {
@@ -619,6 +916,19 @@ function moostVite(options) {
 				ssrFetchForwarding: options.ssrFetchForwarding
 			};
 			config.__moostViteHttpRef = moostHttpRef;
+			resolvedConfig = config;
+		},
+		generateBundle(_outputOptions, bundle) {
+			const cfg = resolvedConfig;
+			if (!cfg || cfg.command !== "build" || !options.middleware || options.ssrExternalCheck === false || this.environment?.name !== "ssr") return;
+			const { externalIds, bundledPackages } = scanSsrBundle(bundle);
+			const splits = findSplitPackages({
+				root: cfg.root,
+				externalIds,
+				bundledPackages,
+				patterns: compilePackagePatterns(typeof options.ssrExternalCheck === "object" ? options.ssrExternalCheck.packages : void 0)
+			});
+			if (splits.length > 0) cfg.logger.warn(`\n[${PLUGIN_NAME}] ${formatSplitPackagesWarning(splits)}\n`);
 		},
 		async transform(code, id) {
 			if (!id.endsWith(".ts")) return null;
@@ -656,7 +966,7 @@ function moostVite(options) {
 			reloadRequired = false;
 			reloadPromise = null;
 			pendingCleanup = null;
-			bootingGeneration = bootGeneration;
+			beginBoot();
 			const runReload = () => {
 				reloadRequired = false;
 				console.log();
@@ -664,16 +974,15 @@ function moostVite(options) {
 				console.log();
 				return (async () => {
 					try {
-						bootingGeneration = bootGeneration;
+						beginBoot();
 						const cleanupInstances = pendingCleanup ?? void 0;
 						pendingCleanup = null;
-						moostRestartCleanup(adapters, options.onEject, cleanupInstances);
+						await moostRestartCleanup(adapters, options.onEject, cleanupInstances);
 						for (const adapter of adapters) if (adapter.detected) await adapter.init();
 						const entryModule = await getEntryModule(server.environments.ssr.moduleGraph);
 						if (entryModule?.transformResult) server.environments.ssr.moduleGraph.invalidateModule(entryModule);
 						await ssrImport(options.entry);
-						bootError = null;
-						if (httpCaptured && !moostMiddleware) logger.error(`⚠️  Moost app reloaded but no HTTP middleware was captured — the entry did not re-run listen().`);
+						if (await settleBootInit() && httpCaptured && !moostMiddleware) logger.error(`⚠️  Moost app reloaded but no HTTP middleware was captured — the entry did not re-run listen().`);
 					} catch (error) {
 						bootError = error;
 						logger.error(`✖️  Failed to reload Moost App: ${error.message}`);
@@ -690,11 +999,16 @@ function moostVite(options) {
 				}
 			};
 			for (const adapter of adapters) adapter.ssrLoadModule = ssrImport;
-			moostRestartCleanup(adapters, options.onEject);
+			await moostRestartCleanup(adapters, options.onEject);
 			await ssrImport(options.entry);
+			await settleBootInit();
 			server.middlewares.use(async (req, res, next) => {
 				await drainReload();
 				if (options.middleware && prefixes && !matchesPrefix(req.url || "", prefixes)) return next();
+				if (bootError) {
+					answerBootError(res);
+					return;
+				}
 				if (moostMiddleware) {
 					if (options.middleware) {
 						pendingNextMap.set(req, next);
@@ -703,12 +1017,6 @@ function moostVite(options) {
 					}
 					return moostMiddleware(req, res);
 				}
-				if (bootError) {
-					res.statusCode = 502;
-					res.setHeader("Content-Type", "text/plain");
-					res.end(`Moost app failed to load: ${bootError.message}`);
-					return;
-				}
 				next();
 			});
 		},
@@ -748,6 +1056,10 @@ function moostVite(options) {
 					const url = req.originalUrl || req.url || "/";
 					try {
 						await drainReload();
+						if (bootError) {
+							answerBootError(res);
+							return;
+						}
 						let template = await fs.readFile((0, node_path.resolve)(server.config.root, "index.html"), "utf8");
 						template = await server.transformIndexHtml(url, template);
 						const { render } = await server.ssrLoadModule(options.ssrEntry);

package/dist/index.d.ts

@@ -173,6 +173,33 @@ interface TMoostViteDevOptions {
      * instead of evaluated by Vite's ESM-only SSR module runner.
      */
     ssrExternal?: string[];
+    /**
+     * Verify the production SSR build for split shared-state packages.
+     *
+     * After the middleware-mode `vite build`, the plugin compares what ended up
+     * inside `dist/server` (the bundled packages) with the bare imports left in
+     * the output (the externalized ones) and walks the externals' dependency
+     * trees. When an external package depends on a bundled watched package, Node
+     * loads a second copy of it at runtime — event-context slots, DI registries
+     * and `instanceof` checks stop matching in production only — so the build
+     * prints a warning naming the package and the fix.
+     *
+     * Watched by default: `moost`, `@moostjs/*`, `wooks`, `@wooksjs/*` and
+     * `@atscript/*`. Pass `{ packages: [...] }` to watch more: an exact package
+     * name (`'lodash'`), a scope/prefix ending with `/` (`'@acme/'`), or a
+     * `RegExp`.
+     *
+     * Default: `true`. Set `false` to silence the check.
+     */
+    ssrExternalCheck?: boolean | TSSRExternalCheckOptions;
+}
+/** Extra packages the SSR split check should watch on top of its defaults. */
+interface TSSRExternalCheckOptions {
+    /**
+     * Package names (`'lodash'`), scope/prefix strings ending with `/`
+     * (`'@acme/'`) or `RegExp`s, added to the watched set.
+     */
+    packages?: (string | RegExp)[];
 }
 declare function moostVite(options: TMoostViteDevOptions): PluginOption;
 

package/dist/index.mjs

@@ -1,9 +1,9 @@
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { createServerModuleRunner } from "vite";
 import MagicString from "magic-string";
 import { builtinModules } from "node:module";
-import { Moost, clearGlobalWooks, createLogger, getMoostInfact, getMoostMate } from "moost";
+import { Moost, clearGlobalWooks, createLogger, disposeInstances, getMoostInfact, getMoostMate } from "moost";
 
 //#region packages/vite/src/utils.ts
 const PLUGIN_NAME = "moost-vite";
@@ -220,19 +220,63 @@ function _define_property(obj, key, value) {
 * A reference to a shared LogsStorage instance that persists
 * across init cycles in dev mode.
 */ let logsStorage;
+/** Whether {@link patchMoostHandlerLogging} already installed its wrappers in this process. */ let installed = false;
 /**
-* Patches Moost’s .init() and .logMappedHandler() methods so that, during dev:
+* The slot {@link captureMoostInit} fills: receives every `init()` promise the
+* wrapper below produces. Unset in prod/test, where nothing consumes a capture.
+*/ let onInitCaptured;
+/**
+* Hands every `Moost.prototype.init()` promise to `onCapture`, letting a boot
+* await the app's **initialization** instead of only its module evaluation.
+*
+* The documented entry shape is `app.adapter(http).listen(port)` followed by an
+* **un-awaited** `app.init()`: the HTTP middleware is therefore captured *before*
+* init finishes, and nothing else observes a rejecting init — a bind error, a DI
+* audit error or a throwing `@MoostInit` hook would leave the dev server serving
+* a half-booted app (the routes bound before the failure answer 200, the rest
+* fall through to the SPA fallback) instead of the plugin's 502. That is also
+* why the plugin's `bootError` gate runs BEFORE the captured middleware, and why
+* the SSR fallback checks it too: `listen()` ran first and left both a middleware
+* and the local-fetch hook behind.
+*
+* Patches the plugin's **own** `moost` import, exactly like the handler logging
+* does: in dev the runtime is externalized, so the plugin and the app share one
+* native `moost` instance (the premise the DI eject in `restart-cleanup` rests on
+* too, and what `ssrExternalCheck` warns about when it stops holding). Unlike the
+* adapters there is nothing to re-establish per reload — a static import is never
+* re-evaluated — and unlike them it must NOT be pulled through the SSR module
+* runner: importing `moost` there registers it as the runner's first module and
+* makes subsequent hot updates re-evaluate the entry only, serving every one of
+* its dependencies (controllers included) from the stale cache.
+*
+* There is exactly ONE `init` wrapper per process (installed by
+* {@link patchMoostHandlerLogging}) and this only fills its slot, so the newest
+* plugin instance wins: Vite re-imports the config on every config-file
+* `server.restart()`, re-running the plugin factory, and a per-instance wrapper
+* would stack on the previous one and keep the dead instance's scope alive.
+*
+* @param onCapture receives each captured init promise (already marked handled).
+*/ function captureMoostInit(onCapture) {
+	onInitCaptured = onCapture;
+}
+/**
+* Patches Moost’s .init() and .logMappedHandler() methods — once per process —
+* so that, during dev:
 * - Only newly added handlers are logged normally.
 * - Removed handlers are logged/stroked out to indicate removal.
 * - Prevents repeated logs from flooding the console across multiple hot reloads.
+* - Every init() promise reaches the {@link captureMoostInit} slot, if filled.
 */ function patchMoostHandlerLogging() {
+	if (installed) return;
+	installed = true;
 	const origInit = Moost.prototype.init;
+	const origLogMappedHandler = Moost.prototype.logMappedHandler;
 	/**
-	* Monkey-patch Moost.init:
+	* The logging body of the patched Moost.init:
 	* 1. Start a new recording cycle in LogsStorage.
 	* 2. Call the real .init().
 	* 3. End the recording, logging any removed handlers.
-	*/ Moost.prototype.init = async function init() {
+	*/ const initWithLogging = async function() {
 		if (!logsStorage) logsStorage = new LogsStorage();
 		logsStorage.startRecording();
 		await origInit.call(this);
@@ -240,7 +284,14 @@ function _define_property(obj, key, value) {
 			origLogMappedHandler.call(this, item.eventName, item.classConstructor, item.method, true, "❌ ");
 		});
 	};
-	const origLogMappedHandler = Moost.prototype.logMappedHandler;
+	Moost.prototype.init = function init() {
+		const promise = initWithLogging.call(this);
+		if (onInitCaptured) {
+			promise.catch(() => {});
+			onInitCaptured(promise);
+		}
+		return promise;
+	};
 	/**
 	* Monkey-patch Moost.logMappedHandler:
 	* If we haven’t seen this particular route+class+method combination
@@ -260,14 +311,23 @@ function _define_property(obj, key, value) {
 /**
 * Clean up Moost’s global containers and optionally remove specific instances from the registry.
 *
+* Every instance actually removed from a registry is **disposed** before the
+* caches are dropped: its `@MoostDispose` hooks (or `Symbol.asyncDispose` /
+* `Symbol.dispose`) are awaited, so a singleton owning a connection, consumer,
+* timer or file handle releases it instead of leaking one copy per reload. An
+* instance kept by an `onEject` veto is never disposed. A failing hook is
+* warned about and the reload continues.
+*
 * @param {Set<string>} [cleanupInstances] A set of module IDs to remove from the registry.
-*/ function moostRestartCleanup(adapters, onEject, cleanupInstances) {
+* @returns the instances that were ejected (and therefore disposed)
+*/ async function moostRestartCleanup(adapters, onEject, cleanupInstances) {
 	const logger = getLogger();
 	const infact = getMoostInfact();
 	const { registry, scopes } = infact;
 	const registries = [registry, ...Object.values(scopes)];
 	infact._cleanup();
 	const mate = getMoostMate();
+	/** Instances removed from a registry by this run — disposed below, before the caches drop. */ const ejected = [];
 	if (cleanupInstances) {
 		for (const reg of registries) {
 			for (const key of Object.getOwnPropertySymbols(reg)) {
@@ -276,6 +336,7 @@ function _define_property(obj, key, value) {
 				if (viteId && cleanupInstances.has(viteId)) {
 					logger.debug(`🔃 Replacing "${constructorName(instance)}"`);
 					delete reg[key];
+					ejected.push(instance);
 				}
 			}
 			for (const key of Object.getOwnPropertySymbols(reg)) {
@@ -283,25 +344,39 @@ function _define_property(obj, key, value) {
 				scanParams(instance, (type) => {
 					if ((type === Moost || type instanceof Moost || type.prototype instanceof Moost) && (!onEject || onEject(instance, type))) {
 						delete reg[key];
+						ejected.push(instance);
 						logger.debug(`✖️  Ejecting "${constructorName(instance)}" (depends on re-instantiated "Moost")`);
 						return true;
 					}
 					for (const adapter of adapters) if (adapter.compare(type) && (!onEject || onEject(instance, type))) {
 						delete reg[key];
+						ejected.push(instance);
 						logger.debug(`✖️  Ejecting "${constructorName(instance)}" (depends on re-instantiated "${adapter.constructor.name}")`);
 						return true;
 					}
 				});
 			}
-			clearDependantRegistry(reg, onEject);
+			clearDependantRegistry(reg, onEject, ejected);
 		}
 		infact.registry = registry;
 		infact.scopes = scopes;
 	}
+	await disposeEjected(ejected);
 	getMoostMate()._cleanup();
 	clearGlobalWooks();
+	return ejected;
 }
-function clearDependantRegistry(registry, onEject) {
+/** Awaits the `@MoostDispose` hooks of the ejected instances; never throws. */ async function disposeEjected(ejected) {
+	if (ejected.length === 0) return;
+	const logger = getLogger();
+	const { disposed, errors } = await disposeInstances(ejected, {
+		logger,
+		onError: "warn"
+	});
+	for (const instance of disposed) logger.debug(`♻️  Disposed "${constructorName(instance)}"`);
+	for (const e of errors) logger.warn(`⚠️  Dispose hook "${constructorName(e.instance)}.${String(e.method)}" failed — the reload continues`);
+}
+function clearDependantRegistry(registry, onEject, ejected) {
 	const logger = getLogger();
 	const objSet = /* @__PURE__ */ new Set();
 	let somethingIsDeleted = true;
@@ -313,7 +388,10 @@ function clearDependantRegistry(registry, onEject) {
 		}
 		for (const key of Object.getOwnPropertySymbols(registry)) {
 			const instance = registry[key];
-			if (checkAndEject(instance, objSet, onEject, registry, key, logger)) somethingIsDeleted = true;
+			if (checkAndEject(instance, objSet, onEject, registry, key, logger)) {
+				ejected.push(instance);
+				somethingIsDeleted = true;
+			}
 		}
 	}
 }
@@ -346,6 +424,173 @@ function constructorName(i) {
 	return Object.getPrototypeOf(i).constructor.name;
 }
 
+//#endregion
+//#region packages/vite/src/ssr-externals-check.ts
+/**
+* Packages that make up the moost/wooks runtime. They mint per-module Symbol
+* slot keys, so the whole set must resolve to a single module instance in the
+* production SSR graph. This is the scope of the single-instance *guard*
+* (force-bundling under an explicit `noExternal` list) — the build *check*
+* watches the wider {@link SHARED_STATE_PACKAGE_PATTERNS}.
+*/ const RUNTIME_PACKAGE_PATTERNS = [
+	/^moost($|\/)/,
+	/^@moostjs\//,
+	/^@wooksjs\//,
+	/^wooks($|\/)/
+];
+/**
+* Packages the build check watches by default: the moost/wooks runtime plus the
+* `@atscript/*` family. All of them keep module-level state — Symbol slot keys,
+* DI/model registries, class identity used by `instanceof` — so a second copy
+* loaded by Node breaks lookups that the bundled copy filled in.
+*
+* This is deliberately wider than {@link RUNTIME_PACKAGE_PATTERNS}: the guard
+* that force-bundles packages covers the runtime only, while the check merely
+* reports what the output shows.
+*/ const SHARED_STATE_PACKAGE_PATTERNS = [...RUNTIME_PACKAGE_PATTERNS, /^@atscript\//];
+function escapeRegExp(input) {
+	return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Build the watched-package patterns for the check: the defaults plus the
+* user's extras. A `RegExp` is used as is, a string ending with `/` matches a
+* scope/prefix (`'@acme/'` → every `@acme/*` package), any other string is an
+* exact package name.
+*/ function compilePackagePatterns(extra) {
+	const patterns = [...SHARED_STATE_PACKAGE_PATTERNS];
+	for (const item of extra ?? []) if (item instanceof RegExp) patterns.push(item);
+	else if (item.endsWith("/")) patterns.push(new RegExp(`^${escapeRegExp(item)}`));
+	else patterns.push(new RegExp(`^${escapeRegExp(item)}$`));
+	return patterns;
+}
+const BUILTINS = new Set(builtinModules);
+/** Bare npm package name of an import specifier (`vue/server-renderer` → `vue`). */ function npmPackageName(id) {
+	if (!id || id.startsWith(".") || id.startsWith("/") || id.startsWith("\0")) return;
+	if (id.startsWith("node:") || id.startsWith("data:") || id.startsWith("virtual:")) return;
+	const parts = id.split("/");
+	const name = id.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+	if (!name || id.startsWith("@") && parts.length < 2) return;
+	return BUILTINS.has(name) ? void 0 : name;
+}
+/**
+* Package names the bundler inlined into the output, derived from the module
+* ids of the emitted chunks. Ids under `node_modules` name their package after
+* the LAST `node_modules/` segment, which also yields the right name for pnpm
+* store paths (`…/node_modules/.pnpm/pkg@1.0.0/node_modules/pkg/index.mjs`).
+* Virtual ids and app sources (no `node_modules`) are ignored.
+*/ function bundledPackagesFromModuleIds(moduleIds) {
+	const packages = /* @__PURE__ */ new Set();
+	const marker = "/node_modules/";
+	for (const raw of moduleIds) {
+		if (!raw || raw.startsWith("\0")) continue;
+		const id = raw.replaceAll("\\", "/");
+		const at = id.lastIndexOf(marker);
+		if (at === -1) continue;
+		const name = npmPackageName(id.slice(at + 14));
+		if (name) packages.add(name);
+	}
+	return packages;
+}
+function readPkgJson(dir) {
+	try {
+		return JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+	} catch {
+		return;
+	}
+}
+/**
+* Locate `name`'s package directory the way Node would from `fromDir`:
+* `<fromDir>/node_modules/<name>`, then each ancestor's `node_modules`.
+* Returns the realpath so pnpm's symlinked layout resolves to the store entry,
+* whose own `node_modules` sibling holds the package's dependencies.
+*/ function findPackageDir(name, fromDir) {
+	let dir = fromDir;
+	for (;;) {
+		const candidate = join(dir, "node_modules", name);
+		if (existsSync(join(candidate, "package.json"))) try {
+			return realpathSync(candidate);
+		} catch {
+			return candidate;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return;
+		dir = parent;
+	}
+}
+/** Deps of `pkg` that are watched packages AND were bundled into the output. */ function splitDepsOf(pkg, patterns, bundledPackages) {
+	const names = /* @__PURE__ */ new Set();
+	for (const group of [
+		pkg.dependencies,
+		pkg.peerDependencies,
+		pkg.optionalDependencies
+	]) for (const dep of Object.keys(group ?? {})) if (bundledPackages.has(dep) && patterns.some((re) => re.test(dep))) names.add(dep);
+	return [...names];
+}
+/** Upper bound on visited packages — keeps a pathological tree from stalling the build. */ const MAX_VISITED = 5e3;
+/**
+* Given the bare specifiers left in the SSR build output (i.e. the packages the
+* bundler externalized) and the package names it bundled, find every package
+* Node will load at runtime that depends on a bundled shared-state package.
+* Such a package resolves its own copy from `node_modules` while the bundled
+* copy lives inside `dist/server` — two instances, split module state.
+*
+* Walks the dependency tree beneath each external (Node loads a package's deps
+* from its own resolution root, so transitive consumers matter too), but never
+* descends into a bundled dep: the fix belongs to the external consumer.
+* Packages that are not installed are skipped silently.
+*/ function findSplitPackages(opts) {
+	const patterns = opts.patterns ?? SHARED_STATE_PACKAGE_PATTERNS;
+	const found = [];
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [];
+	for (const id of opts.externalIds) {
+		const name = npmPackageName(id);
+		if (name && !visited.has(`root:${name}`)) {
+			visited.add(`root:${name}`);
+			queue.push({
+				name,
+				fromDir: opts.root,
+				via: []
+			});
+		}
+	}
+	while (queue.length > 0 && visited.size < MAX_VISITED) {
+		const { name, fromDir, via } = queue.shift();
+		const dir = findPackageDir(name, fromDir);
+		if (!dir || visited.has(dir)) continue;
+		visited.add(dir);
+		const pkg = readPkgJson(dir);
+		if (!pkg) continue;
+		const splitDeps = splitDepsOf(pkg, patterns, opts.bundledPackages);
+		if (splitDeps.length > 0) found.push({
+			name,
+			via,
+			splitDeps
+		});
+		for (const dep of Object.keys(pkg.dependencies ?? {})) if (!opts.bundledPackages.has(dep)) queue.push({
+			name: dep,
+			fromDir: dir,
+			via: [...via, name]
+		});
+	}
+	return found;
+}
+/** Human-readable build warning for {@link findSplitPackages} results. */ function formatSplitPackagesWarning(splits) {
+	const lines = splits.map((s) => {
+		const chain = s.via.length > 0 ? ` (loaded via external ${s.via.join(" → ")})` : "";
+		const deps = s.splitDeps.map((d) => `${d} (bundled)`).join(", ");
+		return `  - ${s.name}${chain} depends on ${deps}`;
+	});
+	const direct = [...new Set(splits.map((s) => s.via.length > 0 ? s.via[0] : s.name))];
+	return [
+		"These externalized packages depend on packages that are bundled into dist/server, so Node will load a second copy of them from node_modules:",
+		...lines,
+		"Two copies of a package split its module state — event-context slots, DI registries and class identity (instanceof) stop matching across the boundary, in production only. Symptoms: \"Cannot read properties of undefined (reading 'headers')\" inside a wooks composable, or a database adapter creating an empty table where a managed view was declared.",
+		`Fix: keep each shared package and everything that depends on it on the same side — add ${direct.map((d) => `'${d}'`).join(", ")} to ssr.noExternal (or drop them from ssr.external / ssrExternal), or externalize the whole family (for example every @atscript/* package, or the whole moost/wooks runtime) via ssr.external.`,
+		"Set ssrExternalCheck: false in moostVite() to silence this check, or ssrExternalCheck: { packages: [...] } to watch more packages."
+	].join("\n");
+}
+
 //#endregion
 //#region packages/vite/src/moost-vite.ts
 /** Regex checks */ const REG_HAS_EXPORT_CLASS = /(^\s*@(Injectable|Controller)\()/m;
@@ -379,6 +624,22 @@ function generatedServerEntry(root) {
 	writeFileSync(entryPath, DEFAULT_SERVER_ENTRY_CODE);
 	return entryPath;
 }
+/**
+* Read the emitted SSR bundle: the packages inlined into it (from every chunk's
+* module ids) and the bare specifiers it still imports (the externalized ones).
+*/ function scanSsrBundle(bundle) {
+	const externalIds = /* @__PURE__ */ new Set();
+	const moduleIds = [];
+	for (const chunk of Object.values(bundle)) {
+		if (chunk.type !== "chunk") continue;
+		moduleIds.push(...chunk.moduleIds ?? []);
+		for (const id of [...chunk.imports ?? [], ...chunk.dynamicImports ?? []]) if (!(id in bundle) && npmPackageName(id)) externalIds.add(id);
+	}
+	return {
+		externalIds,
+		bundledPackages: bundledPackagesFromModuleIds(moduleIds)
+	};
+}
 function moostVite(options) {
 	const externals = options.externals ?? true;
 	const prefixes = normalizePrefixes(options.prefix);
@@ -402,6 +663,11 @@ function moostVite(options) {
 	*/ let bootGeneration = 0;
 	let bootingGeneration = 0;
 	/** Whether the HTTP listen() patch has ever captured a middleware (i.e. this is an HTTP app). */ let httpCaptured = false;
+	/**
+	* The `app.init()` promises the current boot handed us (see `captureMoostInit`) —
+	* several when one entry boots several apps, none for a boot that never calls
+	* `init()`. Reset by `beginBoot()`, consumed by `settleBootInit()`.
+	*/ let bootInitPromises = [];
 	/** Module IDs awaiting DI cleanup — consumed in runReload; see ejectApp. */ let pendingCleanup = null;
 	/** In middleware mode: maps req → next() for the onNoMatch callback */ const pendingNextMap = /* @__PURE__ */ new WeakMap();
 	const adapters = [
@@ -471,6 +737,43 @@ function moostVite(options) {
 		reloadRequired = true;
 	};
 	patchMoostHandlerLogging();
+	captureMoostInit((promise) => {
+		if (bootingGeneration !== bootGeneration) {
+			logger.error(`⚠️  A stale Moost boot called init() (boot generation ${bootingGeneration}, latest ${bootGeneration}) — an HMR reload race; a follow-up reload will replace it.`);
+			return;
+		}
+		bootInitPromises.push(promise);
+	});
+	/** Marks the boot about to run as authoritative for the current generation. */ const beginBoot = () => {
+		bootingGeneration = bootGeneration;
+		bootInitPromises = [];
+	};
+	/**
+	* Finishes a boot: awaits the `init()` promise(s) the entry that just executed
+	* handed us, so the boot is only "done" once the app is fully initialized —
+	* every controller bound, every `@MoostInit` hook run (see `captureMoostInit`).
+	* Owns `bootError`: cleared on success, set and logged when an init rejected;
+	* returns whether the boot succeeded.
+	*/ const settleBootInit = async () => {
+		const initPromises = bootInitPromises;
+		bootInitPromises = [];
+		try {
+			await Promise.all(initPromises);
+			bootError = null;
+			return true;
+		} catch (error) {
+			bootError = error;
+			logger.error(`✖️  Moost app init failed: ${error.message}`);
+			return false;
+		}
+	};
+	/** Answers a request while `bootError` is set (see the gate in configureServer). */ const answerBootError = (res) => {
+		res.statusCode = 502;
+		res.setHeader("Content-Type", "text/plain");
+		res.end(`Moost app failed to load: ${bootError.message}`);
+	};
+	/** Set by the middleware-mode `config` hook: the consumer externalized the runtime themselves. */ let runtimeExternalized = false;
+	let resolvedConfig;
 	return [{
 		name: PLUGIN_NAME,
 		enforce: "pre",
@@ -503,14 +806,8 @@ function moostVite(options) {
 				let ssrNoExternal = userNoExternal === true ? true : userNoExternal !== void 0 ? [...Array.isArray(userNoExternal) ? userNoExternal : [userNoExternal], ourPlugin] : isBuild ? true : [ourPlugin];
 				const userExternal = cfg.ssr?.external;
 				const ssrExternal = isBuild ? [...Array.isArray(userExternal) ? userExternal : [], ...options.ssrExternal ?? []] : void 0;
-				const runtimeNoExternal = [
-					/^moost($|\/)/,
-					/^@moostjs\//,
-					/^@wooksjs\//,
-					/^wooks($|\/)/
-				];
-				const runtimeExternalized = (ssrExternal ?? []).some((e) => typeof e === "string" && runtimeNoExternal.some((re) => re.test(e)));
-				if (isBuild && Array.isArray(ssrNoExternal) && !runtimeExternalized) ssrNoExternal = [...ssrNoExternal, ...runtimeNoExternal];
+				runtimeExternalized = (ssrExternal ?? []).some((e) => typeof e === "string" && RUNTIME_PACKAGE_PATTERNS.some((re) => re.test(e)));
+				if (isBuild && Array.isArray(ssrNoExternal) && !runtimeExternalized) ssrNoExternal = [...ssrNoExternal, ...RUNTIME_PACKAGE_PATTERNS];
 				return {
 					...options.ssrEntry && { appType: "custom" },
 					ssr: {
@@ -588,6 +885,19 @@ function moostVite(options) {
 				ssrFetchForwarding: options.ssrFetchForwarding
 			};
 			config.__moostViteHttpRef = moostHttpRef;
+			resolvedConfig = config;
+		},
+		generateBundle(_outputOptions, bundle) {
+			const cfg = resolvedConfig;
+			if (!cfg || cfg.command !== "build" || !options.middleware || options.ssrExternalCheck === false || this.environment?.name !== "ssr") return;
+			const { externalIds, bundledPackages } = scanSsrBundle(bundle);
+			const splits = findSplitPackages({
+				root: cfg.root,
+				externalIds,
+				bundledPackages,
+				patterns: compilePackagePatterns(typeof options.ssrExternalCheck === "object" ? options.ssrExternalCheck.packages : void 0)
+			});
+			if (splits.length > 0) cfg.logger.warn(`\n[${PLUGIN_NAME}] ${formatSplitPackagesWarning(splits)}\n`);
 		},
 		async transform(code, id) {
 			if (!id.endsWith(".ts")) return null;
@@ -625,7 +935,7 @@ function moostVite(options) {
 			reloadRequired = false;
 			reloadPromise = null;
 			pendingCleanup = null;
-			bootingGeneration = bootGeneration;
+			beginBoot();
 			const runReload = () => {
 				reloadRequired = false;
 				console.log();
@@ -633,16 +943,15 @@ function moostVite(options) {
 				console.log();
 				return (async () => {
 					try {
-						bootingGeneration = bootGeneration;
+						beginBoot();
 						const cleanupInstances = pendingCleanup ?? void 0;
 						pendingCleanup = null;
-						moostRestartCleanup(adapters, options.onEject, cleanupInstances);
+						await moostRestartCleanup(adapters, options.onEject, cleanupInstances);
 						for (const adapter of adapters) if (adapter.detected) await adapter.init();
 						const entryModule = await getEntryModule(server.environments.ssr.moduleGraph);
 						if (entryModule?.transformResult) server.environments.ssr.moduleGraph.invalidateModule(entryModule);
 						await ssrImport(options.entry);
-						bootError = null;
-						if (httpCaptured && !moostMiddleware) logger.error(`⚠️  Moost app reloaded but no HTTP middleware was captured — the entry did not re-run listen().`);
+						if (await settleBootInit() && httpCaptured && !moostMiddleware) logger.error(`⚠️  Moost app reloaded but no HTTP middleware was captured — the entry did not re-run listen().`);
 					} catch (error) {
 						bootError = error;
 						logger.error(`✖️  Failed to reload Moost App: ${error.message}`);
@@ -659,11 +968,16 @@ function moostVite(options) {
 				}
 			};
 			for (const adapter of adapters) adapter.ssrLoadModule = ssrImport;
-			moostRestartCleanup(adapters, options.onEject);
+			await moostRestartCleanup(adapters, options.onEject);
 			await ssrImport(options.entry);
+			await settleBootInit();
 			server.middlewares.use(async (req, res, next) => {
 				await drainReload();
 				if (options.middleware && prefixes && !matchesPrefix(req.url || "", prefixes)) return next();
+				if (bootError) {
+					answerBootError(res);
+					return;
+				}
 				if (moostMiddleware) {
 					if (options.middleware) {
 						pendingNextMap.set(req, next);
@@ -672,12 +986,6 @@ function moostVite(options) {
 					}
 					return moostMiddleware(req, res);
 				}
-				if (bootError) {
-					res.statusCode = 502;
-					res.setHeader("Content-Type", "text/plain");
-					res.end(`Moost app failed to load: ${bootError.message}`);
-					return;
-				}
 				next();
 			});
 		},
@@ -709,6 +1017,10 @@ function moostVite(options) {
 					const url = req.originalUrl || req.url || "/";
 					try {
 						await drainReload();
+						if (bootError) {
+							answerBootError(res);
+							return;
+						}
 						let template = await fs.readFile(resolve(server.config.root, "index.html"), "utf8");
 						template = await server.transformIndexHtml(url, template);
 						const { render } = await server.ssrLoadModule(options.ssrEntry);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moostjs/vite",
-  "version": "0.6.35",
+  "version": "0.6.37",
   "description": "Vite Dev plugin for moostjs",
   "keywords": [
     "composables",
@@ -58,8 +58,8 @@
   "peerDependencies": {
     "sirv": "^3.0.0",
     "vite": "^8.0.0",
-    "@moostjs/event-http": "^0.6.35",
-    "moost": "^0.6.35"
+    "@moostjs/event-http": "^0.6.37",
+    "moost": "^0.6.37"
   },
   "peerDependenciesMeta": {
     "sirv": {