alloy-di 1.2.2 → 1.3.0

package/dist/lib/container.d.ts

@@ -89,8 +89,12 @@ declare class Container {
    */
   private resolveParam;
   /**
-   * Execute a lazy importer with optional retry/backoff semantics.
-   * Implements exponential backoff for transient network failures.
+   * Execute a lazy importer with optional retry/backoff semantics, then
+   * validate that the imported value is a constructor.
+   *
+   * Only the dynamic import itself is retried; a successful import that does
+   * not yield a constructor is deterministic and fails immediately without
+   * backoff or re-wrapping.
    *
    * @param lazyDep - Lazy dependency wrapper with importer function and retry config
    * @param target - Service being resolved (for error messages)
@@ -99,6 +103,10 @@ declare class Container {
    * @throws Error if all retry attempts exhausted or import returns non-constructor
    */
   private importWithRetry;
+  /**
+   * Run a lazy importer, retrying failed imports with exponential backoff.
+   */
+  private runImporterWithRetry;
   /**
    * Resolve a token dependency via registered value providers.
    */

package/dist/lib/container.js

@@ -184,8 +184,12 @@ var Container = class {
 		return classification;
 	}
 	/**
-	* Execute a lazy importer with optional retry/backoff semantics.
-	* Implements exponential backoff for transient network failures.
+	* Execute a lazy importer with optional retry/backoff semantics, then
+	* validate that the imported value is a constructor.
+	*
+	* Only the dynamic import itself is retried; a successful import that does
+	* not yield a constructor is deterministic and fails immediately without
+	* backoff or re-wrapping.
 	*
 	* @param lazyDep - Lazy dependency wrapper with importer function and retry config
 	* @param target - Service being resolved (for error messages)
@@ -194,23 +198,28 @@ var Container = class {
 	* @throws Error if all retry attempts exhausted or import returns non-constructor
 	*/
 	async importWithRetry(lazyDep, target, resolutionStack) {
-		const runImport = async () => await lazyDep.importer();
+		const module = await this.runImporterWithRetry(lazyDep, target, resolutionStack);
+		const depClass = typeof module === "object" && module !== null && "default" in module ? module.default : module;
+		if (!isConstructor(depClass)) {
+			const stackPath = this.formatStackPath(target, resolutionStack);
+			throw new DependencyResolutionError(`Lazy importer did not return a class for dependency while resolving ${target.name}. Resolution stack: ${stackPath}. Received type: ${typeof depClass}`, {
+				target,
+				resolutionStack,
+				failedDependency: depClass
+			});
+		}
+		return depClass;
+	}
+	/**
+	* Run a lazy importer, retrying failed imports with exponential backoff.
+	*/
+	async runImporterWithRetry(lazyDep, target, resolutionStack) {
 		const retries = lazyDep.retry?.retries ?? 0;
 		const baseDelay = lazyDep.retry?.backoffMs ?? 0;
 		const factor = lazyDep.retry?.factor ?? 2;
 		let attempt = 0;
 		while (true) try {
-			const module = await runImport();
-			const depClass = typeof module === "object" && module !== null && "default" in module ? module.default : module;
-			if (!isConstructor(depClass)) {
-				const stackPath = this.formatStackPath(target, resolutionStack);
-				throw new DependencyResolutionError(`Lazy importer did not return a class for dependency while resolving ${target.name}. Resolution stack: ${stackPath}. Received type: ${typeof depClass}`, {
-					target,
-					resolutionStack,
-					failedDependency: depClass
-				});
-			}
-			return depClass;
+			return await lazyDep.importer();
 		} catch (err) {
 			if (attempt >= retries) {
 				const stackPath = this.formatStackPath(target, resolutionStack);
@@ -251,10 +260,14 @@ var Container = class {
 		const cached = this.metadataCache.get(target);
 		if (cached) return cached;
 		const registryEntry = dependenciesRegistry.get(target);
+		if (!registryEntry) return {
+			scope: ServiceScope.TRANSIENT,
+			dependencies: []
+		};
 		const metadata = {
-			scope: registryEntry?.scope ?? ServiceScope.TRANSIENT,
-			dependencies: (registryEntry?.dependencies ?? (() => []))(),
-			factory: registryEntry?.factory
+			scope: registryEntry.scope ?? ServiceScope.TRANSIENT,
+			dependencies: (registryEntry.dependencies ?? (() => []))(),
+			factory: registryEntry.factory
 		};
 		this.metadataCache.set(target, metadata);
 		return metadata;

package/dist/lib/decorators.js

@@ -65,11 +65,44 @@ function createDecoratorWithoutDeps(scope) {
 function isDependenciesArg(value) {
 	return typeof value === "function" || Array.isArray(value);
 }
+/**
+* Detect a class constructor passed where dependency metadata was expected.
+*
+* Class constructors have a non-writable `prototype`; dependency thunks
+* (arrow functions or plain functions) either lack a `prototype` descriptor
+* or have a writable one.
+*
+* @param value - The argument supplied to `@Injectable`/`@Singleton`.
+* @returns True if the value is a class constructor.
+* @internal
+*/
+function isClassConstructor(value) {
+	if (typeof value !== "function") return false;
+	const prototypeDescriptor = Object.getOwnPropertyDescriptor(value, "prototype");
+	return prototypeDescriptor !== void 0 && !prototypeDescriptor.writable;
+}
+/**
+* Reject the bare-decorator misuse `@Injectable` / `@Singleton` (no parens).
+*
+* Applied bare, the decorator factory itself receives the class, mistakes it
+* for a dependencies thunk, and returns a decorator function — which legacy
+* decorator semantics then substitute for the class. Throwing here turns that
+* silent class replacement into an immediate, actionable error.
+*
+* @param value - The first argument received by the decorator factory.
+* @param decoratorName - Public decorator name for the error message.
+* @internal
+*/
+function assertNotBareDecorator(value, decoratorName) {
+	if (isClassConstructor(value)) throw new TypeError(`@${decoratorName} must be called — use @${decoratorName}() instead of @${decoratorName}`);
+}
 function Injectable(depsOrScope, scopeOverride) {
+	assertNotBareDecorator(depsOrScope, "Injectable");
 	if (isDependenciesArg(depsOrScope)) return createDecoratorWithDeps(scopeOverride ?? ServiceScope.TRANSIENT, depsOrScope);
 	return createDecoratorWithoutDeps((typeof depsOrScope === "string" ? depsOrScope : void 0) ?? scopeOverride ?? ServiceScope.TRANSIENT);
 }
 function Singleton(dependencies) {
+	assertNotBareDecorator(dependencies, "Singleton");
 	if (isDependenciesArg(dependencies)) return createDecoratorWithDeps(ServiceScope.SINGLETON, dependencies);
 	return createDecoratorWithoutDeps(ServiceScope.SINGLETON);
 }

package/dist/lib/env-detection.d.ts

@@ -0,0 +1,24 @@
+//#region src/lib/env-detection.d.ts
+type ImportMetaEnvShape = {
+  MODE?: string;
+  PROD?: boolean;
+  NODE_ENV?: string;
+  [key: string]: unknown;
+};
+type EnvDetectionOverrides = {
+  /**
+   * Explicit import.meta.env replacement. Use `null` to force "no env" behavior.
+   */
+  importMetaEnv?: ImportMetaEnvShape | null;
+  /**
+   * Explicit NODE_ENV replacement. Use `null` to ignore process.env.
+   */
+  nodeEnv?: string | null;
+  /**
+   * Short-circuit the entire detection logic with a predetermined boolean.
+   */
+  isDev?: boolean;
+};
+declare function setEnvDetectionOverrides(overrides: EnvDetectionOverrides | undefined): void;
+//#endregion
+export { EnvDetectionOverrides, setEnvDetectionOverrides };

package/dist/lib/env-detection.js

@@ -2,11 +2,20 @@
 function isRecord(value) {
 	return typeof value === "object" && value !== null;
 }
+/**
+* Build-time-injected detection overrides.
+*
+* The Vite plugin emits a `setEnvDetectionOverrides({ isDev: ... })` call
+* into the generated container module so detection in plugin-driven setups
+* uses the bundler's authoritative mode instead of runtime sniffing.
+*/
+let injectedOverrides;
+function setEnvDetectionOverrides(overrides) {
+	injectedOverrides = overrides;
+}
 function readImportMetaEnvFromRuntime() {
 	if (typeof import.meta === "undefined") return;
-	const candidate = import.meta;
-	if (!isRecord(candidate) || !("env" in candidate)) return;
-	const envValue = candidate.env;
+	const envValue = import.meta.env;
 	if (!isRecord(envValue)) return;
 	const env = {};
 	if (typeof envValue.MODE === "string") env.MODE = envValue.MODE;
@@ -15,8 +24,11 @@ function readImportMetaEnvFromRuntime() {
 	return env;
 }
 function readProcessNodeEnv() {
-	if (typeof process === "undefined") return;
-	return "development";
+	try {
+		return "development";
+	} catch {
+		return;
+	}
 }
 function getImportMetaEnv(overrides) {
 	if (overrides?.importMetaEnv === null) return;
@@ -29,14 +41,15 @@ function getNodeEnv(overrides) {
 	return readProcessNodeEnv();
 }
 function isDevEnvironment(overrides) {
-	if (typeof overrides?.isDev === "boolean") return overrides.isDev;
-	const nodeEnv = getNodeEnv(overrides);
+	const effective = overrides ?? injectedOverrides;
+	if (typeof effective?.isDev === "boolean") return effective.isDev;
+	const nodeEnv = getNodeEnv(effective);
 	if (typeof nodeEnv === "string") return nodeEnv !== "production";
-	const importMetaEnv = getImportMetaEnv(overrides);
+	const importMetaEnv = getImportMetaEnv(effective);
 	if (typeof importMetaEnv?.PROD === "boolean") return !importMetaEnv.PROD;
 	if (typeof importMetaEnv?.MODE === "string") return importMetaEnv.MODE !== "production";
 	if (typeof importMetaEnv?.NODE_ENV === "string") return importMetaEnv.NODE_ENV !== "production";
 	return true;
 }
 //#endregion
-export { isDevEnvironment };
+export { isDevEnvironment, setEnvDetectionOverrides };

package/dist/lib/service-identifiers.d.ts

@@ -13,8 +13,11 @@ type ServiceIdentifier<T = unknown> = symbol & {
 /**
  * Associates a constructor with a stable identifier. When an explicit identifier
  * is provided (e.g., by generated metadata), it becomes canonical for the
- * constructor. Attempting to reuse an identifier with a different constructor
- * throws to surface manifest/config mismatches early.
+ * constructor when the constructor is first registered. If the constructor was
+ * already assigned an auto-generated identifier, later explicit identifiers are
+ * recorded as aliases so both symbols resolve to the same constructor.
+ * Attempting to reuse an identifier with a different constructor throws to
+ * surface manifest/config mismatches early.
  */
 declare function registerServiceIdentifier<T>(ctor: Constructor, explicitIdentifier?: ServiceIdentifier<T>): ServiceIdentifier<T>;
 /**

package/dist/lib/service-identifiers.js

@@ -11,8 +11,11 @@ function createServiceIdentifier(ctor) {
 /**
 * Associates a constructor with a stable identifier. When an explicit identifier
 * is provided (e.g., by generated metadata), it becomes canonical for the
-* constructor. Attempting to reuse an identifier with a different constructor
-* throws to surface manifest/config mismatches early.
+* constructor when the constructor is first registered. If the constructor was
+* already assigned an auto-generated identifier, later explicit identifiers are
+* recorded as aliases so both symbols resolve to the same constructor.
+* Attempting to reuse an identifier with a different constructor throws to
+* surface manifest/config mismatches early.
 */
 function registerServiceIdentifier(ctor, explicitIdentifier) {
 	const current = ctorToIdentifier.get(ctor);
@@ -20,6 +23,7 @@ function registerServiceIdentifier(ctor, explicitIdentifier) {
 		if (explicitIdentifier && explicitIdentifier !== current) {
 			const owner = identifierToCtor.get(explicitIdentifier);
 			if (owner && owner !== ctor) throw new Error("Attempted to reassign an existing ServiceIdentifier to a different constructor.");
+			identifierToCtor.set(explicitIdentifier, ctor);
 		}
 		return current;
 	}

package/dist/plugins/core/codegen.js

@@ -1,6 +1,7 @@
 import { createClassKey, createSymbolKey, hashString, normalizeImportPath } from "./utils.js";
 import { IdentifierResolver } from "./identifier-resolver.js";
 import path from "node:path";
+import ts from "typescript";
 //#region src/plugins/core/codegen.ts
 function escapeSingleQuotes(value) {
 	return value.replaceAll("'", "\\'");
@@ -18,49 +19,152 @@ function createSymbolDescription(meta) {
 	return createSymbolKey(meta.filePath, meta.className);
 }
 /**
+* Allocates module-local names from a single shared pool so the generated
+* module's independent naming domains (runtime helpers, service imports,
+* factory-lazy stubs, dependency imports, identifier consts, generated
+* locals) can never collide.
+*/
+function createNamePool(reservedNames) {
+	const used = new Set(reservedNames);
+	return { claim(base) {
+		let candidate = base;
+		let suffix = 1;
+		while (used.has(candidate)) {
+			candidate = `${base}_${suffix}`;
+			suffix++;
+		}
+		used.add(candidate);
+		return candidate;
+	} };
+}
+function stripModuleExtension(importPath) {
+	return importPath.replace(/\.[cm]?[jt]sx?$/i, "");
+}
+/**
+* Identity of an imported binding: the module (extension-insensitive, since
+* references may resolve extensionless while service paths keep theirs) plus
+* the export name.
+*/
+function createBindingKey(importPath, exportName) {
+	return `${stripModuleExtension(importPath)}::${exportName}`;
+}
+/** Resolves a referenced import's specifier to a normalized module path. */
+function resolveReferencePath(ref, meta) {
+	return normalizeImportPath(ref.path.startsWith(".") ? path.resolve(path.dirname(meta.filePath), ref.path) : ref.path);
+}
+function resolveDependencyImport(ref, normalizedPath, pool, serviceBindings, runtimeImports) {
+	if (normalizedPath === "alloy-di/runtime" && ref.originalName && ref.name === ref.originalName && runtimeImports.has(ref.originalName)) return {
+		localName: ref.originalName,
+		importPath: normalizedPath,
+		originalName: ref.originalName,
+		reusesExistingBinding: true
+	};
+	const serviceLocalName = serviceBindings.get(createBindingKey(normalizedPath, ref.originalName ?? "default"));
+	if (serviceLocalName) return {
+		localName: serviceLocalName,
+		importPath: normalizedPath,
+		originalName: ref.originalName,
+		reusesExistingBinding: true
+	};
+	return {
+		localName: pool.claim(ref.name),
+		importPath: normalizedPath,
+		originalName: ref.originalName
+	};
+}
+/**
 * Analyzes dependencies across all discovered services and resolves imports.
-* Deduplicates imports and handles naming collisions by generating unique local names.
+* Deduplicates imports by binding identity, reuses bindings the module
+* already declares (runtime helpers, service imports, factory-lazy stubs),
+* and claims fresh local names from the shared pool otherwise.
 */
-function resolveDependencyImports(metas) {
+function resolveDependencyImports(metas, pool, serviceBindings, runtimeImports) {
 	const importMap = /* @__PURE__ */ new Map();
-	const nameCounts = /* @__PURE__ */ new Map();
-	const getUniqueName = (name) => {
-		const count = nameCounts.get(name) ?? 0;
-		nameCounts.set(name, count + 1);
-		return count === 0 ? name : `${name}_${count}`;
-	};
-	for (const meta of metas) {
-		if (!meta.referencedImports?.length) continue;
-		for (const ref of meta.referencedImports) {
-			if (ref.isTypeOnly) continue;
-			const normalizedPath = normalizeImportPath(ref.path.startsWith(".") ? path.resolve(path.dirname(meta.filePath), ref.path) : ref.path);
-			const key = `${normalizedPath}::${ref.originalName ?? "default"}`;
-			if (importMap.has(key)) continue;
-			importMap.set(key, {
-				localName: getUniqueName(ref.name),
-				importPath: normalizedPath,
-				originalName: ref.originalName
-			});
-		}
+	for (const meta of metas) for (const ref of meta.referencedImports ?? []) {
+		if (ref.isTypeOnly) continue;
+		const normalizedPath = resolveReferencePath(ref, meta);
+		const key = createBindingKey(normalizedPath, ref.originalName ?? "default");
+		if (importMap.has(key)) continue;
+		importMap.set(key, resolveDependencyImport(ref, normalizedPath, pool, serviceBindings, runtimeImports));
 	}
 	return {
 		dependencyImports: Array.from(importMap.values()),
 		importMap
 	};
 }
+/**
+* True when an identifier occupies a name position rather than referencing a
+* binding: property-access names (`ns.Api`), object keys — including method
+* and accessor keys (`{ Api() {} }`, `{ get Api() {} }`) — class member
+* names, qualified names, and destructuring property names.
+*/
+function isNonReferencePosition(node) {
+	const parent = node.parent;
+	if (ts.isPropertyAccessExpression(parent)) return parent.name === node;
+	if (ts.isQualifiedName(parent)) return parent.right === node;
+	if (ts.isBindingElement(parent)) return parent.propertyName === node;
+	if (ts.isPropertyAssignment(parent) || ts.isMethodDeclaration(parent) || ts.isGetAccessorDeclaration(parent) || ts.isSetAccessorDeclaration(parent) || ts.isPropertyDeclaration(parent) || ts.isMethodSignature(parent) || ts.isPropertySignature(parent)) return parent.name === node;
+	return false;
+}
+/**
+* Decide how to rewrite one identifier node, or skip it.
+*
+* Only binding references are rewritten: name positions and string/comment
+* content keep their text. Shorthand properties expand
+* (`{ Api }` -> `{ Api: Api_1 }`) so the key survives the rename.
+*/
+function createIdentifierEdit(node, source, replacement) {
+	const parent = node.parent;
+	if (isNonReferencePosition(node)) return;
+	const start = node.getStart(source);
+	if (ts.isShorthandPropertyAssignment(parent) && parent.name === node) return {
+		start,
+		end: node.end,
+		text: `${node.text}: ${replacement}`
+	};
+	return {
+		start,
+		end: node.end,
+		text: replacement
+	};
+}
+/**
+* Rewrite identifier references inside a reconstructed dependency expression.
+*
+* The expression is parsed and identifier nodes are replaced by position, so
+* `$`-prefixed names rewrite correctly and occurrences inside string literals
+* (e.g. lazy `import('/src/Api')` specifiers) and comments are untouched —
+* the previous `\b`-regex text replacement got both wrong.
+*/
+function rewriteReferencedIdentifiers(expression, referenced, rewriter) {
+	const wrapped = `(${expression});`;
+	const source = ts.createSourceFile("alloy-dependency-expression.ts", wrapped, ts.ScriptTarget.ESNext, true);
+	const edits = [];
+	const visit = (node) => {
+		if (ts.isIdentifier(node) && referenced.has(node.text)) {
+			const replacement = rewriter(node.text);
+			if (replacement && replacement !== node.text) {
+				const edit = createIdentifierEdit(node, source, replacement);
+				if (edit) edits.push(edit);
+			}
+		}
+		ts.forEachChild(node, visit);
+	};
+	visit(source);
+	let result = wrapped;
+	for (const edit of edits.toSorted((a, b) => b.start - a.start)) result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
+	return result.slice(1, -2);
+}
 function reconstructDependencyExpression(dep, rewriter, contextDir) {
 	let expr = dep.expression;
-	for (const ident of dep.referencedIdentifiers) {
-		const replacement = rewriter(ident);
-		if (replacement && replacement !== ident) expr = expr.replaceAll(new RegExp(`\\b${ident}\\b`, "g"), replacement);
-	}
+	if (dep.referencedIdentifiers.length > 0) expr = rewriteReferencedIdentifiers(expr, new Set(dep.referencedIdentifiers), rewriter);
 	if (dep.isLazy) expr = expr.replaceAll(/import\s*\(\s*(['"])(.+?)\1\s*\)/g, (match, quote, importPath) => {
 		if (importPath.startsWith(".")) return `import(${quote}${normalizeImportPath(path.resolve(contextDir, importPath))}${quote})`;
 		return match;
 	});
 	return expr;
 }
-function reconstructOptionsText(meta, importMap) {
+function reconstructOptionsText(meta, importMap, serviceRenames) {
 	const { scope, dependencies, factory } = meta.metadata;
 	const parts = [];
 	if (factory) {
@@ -73,12 +177,11 @@ function reconstructOptionsText(meta, importMap) {
 			return reconstructDependencyExpression(dep, (ident) => {
 				const ref = meta.referencedImports?.find((r) => r.name === ident && !r.isTypeOnly);
 				if (ref) {
-					const dir = path.dirname(meta.filePath);
-					const key = `${normalizeImportPath(ref.path.startsWith(".") ? path.resolve(dir, ref.path) : ref.path)}::${ref.originalName ?? "default"}`;
+					const key = createBindingKey(resolveReferencePath(ref, meta), ref.originalName ?? "default");
 					const resolved = importMap.get(key);
 					return resolved ? resolved.localName : ident;
 				}
-				return ident;
+				return serviceRenames.get(ident) ?? ident;
 			}, path.dirname(meta.filePath));
 		});
 		parts.push(`dependencies: () => [${depExprs.join(", ")}]`);
@@ -86,13 +189,38 @@ function reconstructOptionsText(meta, importMap) {
 	if (parts.length === 0) return "{}";
 	return `{ ${parts.join(", ")} }`;
 }
-function buildImportsAndRegistrations(metas, lazyReferencedClassKeys, hasProviderModules) {
+function buildImportsAndRegistrations(metas, lazyReferencedClassKeys, providerModulePaths, options) {
+	const hasProviderModules = providerModulePaths.length > 0;
 	const activeMetas = filterActiveMetas(metas, lazyReferencedClassKeys);
-	const { dependencyImports, importMap } = resolveDependencyImports(activeMetas);
-	const resolvedRegistrations = enrichRegistrations(activeMetas, new IdentifierResolver(activeMetas), importMap);
-	const runtimeImports = computeRuntimeImports(resolvedRegistrations, hasProviderModules);
+	const resolver = new IdentifierResolver(activeMetas);
+	const runtimeImports = computeRuntimeImports(activeMetas, hasProviderModules, options?.isDev !== void 0);
+	const pool = createNamePool([
+		...runtimeImports,
+		"registrations",
+		"container",
+		"providerDefinitions",
+		...providerModulePaths.map((_, idx) => `providers_${idx}`)
+	]);
+	const serviceNames = /* @__PURE__ */ new Map();
+	const serviceRenames = /* @__PURE__ */ new Map();
+	const serviceBindings = /* @__PURE__ */ new Map();
+	for (const meta of activeMetas) {
+		const baseName = resolver.resolve(meta.className, meta.filePath);
+		const name = pool.claim(baseName);
+		serviceNames.set(meta, name);
+		if (name !== baseName) serviceRenames.set(baseName, name);
+		serviceBindings.set(createBindingKey(getServiceImportPath(meta), meta.className), name);
+	}
+	const { dependencyImports, importMap } = resolveDependencyImports(activeMetas, pool, serviceBindings, runtimeImports);
+	const resolvedRegistrations = enrichRegistrations(activeMetas, {
+		resolver,
+		serviceNames,
+		serviceRenames,
+		importMap,
+		pool
+	});
 	const runtimeImportStatement = formatRuntimeImportStatement(runtimeImports);
-	const stubsBlock = createStubBlock(dependencyImports, resolvedRegistrations, runtimeImports);
+	const stubsBlock = createStubBlock(dependencyImports, resolvedRegistrations);
 	return {
 		runtimeImportStatement,
 		registrationsBlock: createRegistrationsBlock(buildRegistrationEntries(resolvedRegistrations)),
@@ -103,13 +231,14 @@ function buildImportsAndRegistrations(metas, lazyReferencedClassKeys, hasProvide
 function filterActiveMetas(metas, lazyReferencedClassKeys) {
 	return metas.filter((meta) => !lazyReferencedClassKeys.has(createClassKey(meta.filePath, meta.className)));
 }
-function enrichRegistrations(activeMetas, resolver, importMap) {
+function enrichRegistrations(activeMetas, naming) {
+	const { resolver, serviceNames, serviceRenames, importMap, pool } = naming;
 	return activeMetas.map((meta) => {
-		const importName = resolver.resolve(meta.className, meta.filePath);
-		const identifierConst = `${importName}Identifier`;
+		const importName = serviceNames.get(meta) ?? meta.className;
+		const identifierConst = pool.claim(`${importName}Identifier`);
 		const exportKey = createIdentifierExportKey(meta, resolver);
 		const symbolDescription = meta.identifierKey ?? createSymbolDescription(meta);
-		const optionsText = reconstructOptionsText(meta, importMap);
+		const optionsText = reconstructOptionsText(meta, importMap, serviceRenames);
 		return {
 			...meta,
 			importName,
@@ -121,34 +250,30 @@ function enrichRegistrations(activeMetas, resolver, importMap) {
 		};
 	});
 }
-function computeRuntimeImports(registrations, hasProviderModules) {
+function computeRuntimeImports(activeMetas, hasProviderModules, hasEnvOverrides = false) {
 	const imports = new Set(["Container", "dependenciesRegistry"]);
-	const needsLazyImport = registrations.some((m) => m.metadata.dependencies.some((d) => d.isLazy) || !!m.metadata.factory);
+	if (hasEnvOverrides) imports.add("setEnvDetectionOverrides");
+	const needsLazyImport = activeMetas.some((m) => m.metadata.dependencies.some((d) => d.isLazy) || !!m.metadata.factory);
 	if (hasProviderModules) imports.add("applyProviders");
 	if (needsLazyImport) imports.add("Lazy");
-	if (registrations.length) imports.add("registerServiceIdentifier");
+	if (activeMetas.length) imports.add("registerServiceIdentifier");
 	return imports;
 }
 function formatRuntimeImportStatement(imports) {
 	return `\nimport { ${Array.from(imports).join(", ")} } from 'alloy-di/runtime';\n`;
 }
-function createStubBlock(dependencyImports, registrations, runtimeImports) {
+function createStubBlock(dependencyImports, registrations) {
 	const statements = [];
-	const importedNames = new Set(runtimeImports);
 	for (const dep of dependencyImports) {
-		if (dep.importPath === "alloy-di/runtime" && dep.originalName && dep.localName === dep.originalName && runtimeImports.has(dep.originalName)) continue;
-		if (importedNames.has(dep.localName)) continue;
+		if (dep.reusesExistingBinding) continue;
 		statements.push(createDependencyImportStatement(dep));
-		importedNames.add(dep.localName);
 	}
 	for (const meta of registrations) {
 		if (meta.isFactoryLazy) {
 			statements.push(`class ${meta.importName} {}`);
 			continue;
 		}
-		if (importedNames.has(meta.importName)) continue;
 		statements.push(createServiceImportStatement(meta));
-		importedNames.add(meta.importName);
 	}
 	return statements.length ? `${statements.join("\n")}\n` : "";
 }
@@ -158,8 +283,11 @@ function createDependencyImportStatement(dep) {
 	if (dep.originalName && dep.originalName !== dep.localName) return `import { ${dep.originalName} as ${dep.localName} } from '${dep.importPath}';`;
 	return `import { ${dep.localName} } from '${dep.importPath}';`;
 }
+function getServiceImportPath(meta) {
+	return !/^(\/|[A-Za-z]:\\|\.|~)/.test(meta.filePath) && !meta.filePath.includes("\\") ? meta.filePath : normalizeImportPath(meta.filePath);
+}
 function createServiceImportStatement(meta) {
-	const importPath = !/^(\/|[A-Za-z]:\\|\.|~)/.test(meta.filePath) && !meta.filePath.includes("\\") ? meta.filePath : normalizeImportPath(meta.filePath);
+	const importPath = getServiceImportPath(meta);
 	if (meta.importName === meta.className) return `import { ${meta.className} } from '${importPath}';`;
 	return `import { ${meta.className} as ${meta.importName} } from '${importPath}';`;
 }
@@ -191,9 +319,10 @@ function createIdentifierExports(registrations) {
 * @param lazyReferencedClassKeys - Set of service keys that are referenced ONLY lazily (and thus should not be imported/registered eagerly in this bundle).
 * @param providerModulePaths - List of provider modules to import and apply.
 */
-function generateContainerModule(metas, lazyReferencedClassKeys, providerModulePaths) {
+function generateContainerModule(metas, lazyReferencedClassKeys, providerModulePaths, options) {
 	const hasProviderModules = providerModulePaths.length > 0;
-	const { runtimeImportStatement, registrationsBlock, stubsBlock, identifierExportBlock } = buildImportsAndRegistrations(metas, lazyReferencedClassKeys, hasProviderModules);
+	const { runtimeImportStatement, registrationsBlock, stubsBlock, identifierExportBlock } = buildImportsAndRegistrations(metas, lazyReferencedClassKeys, providerModulePaths, options);
+	const envOverridesBlock = options?.isDev === void 0 ? "" : `\nsetEnvDetectionOverrides({ isDev: ${options.isDev} });\n`;
 	let providerImportBlock = "";
 	let providerInvocationBlock = "";
 	if (hasProviderModules) {
@@ -202,7 +331,7 @@ function generateContainerModule(metas, lazyReferencedClassKeys, providerModuleP
 		providerInvocationBlock = `\nconst providerDefinitions = [${aliasNames.join(", ")}];\nfor (const definition of providerDefinitions) {\n  applyProviders(container, definition);\n}\n`;
 	}
 	return `
-${runtimeImportStatement}${stubsBlock}
+${runtimeImportStatement}${envOverridesBlock}${stubsBlock}
 ${providerImportBlock}
 ${registrationsBlock}
 
@@ -215,6 +344,11 @@ ${providerInvocationBlock}${identifierExportBlock}
 export default container;
 `;
 }
+const GENERATED_FILE_NOTICE = "This file was auto-generated by Alloy. Manual changes will be overwritten.";
+const GENERATED_FILE_HEADER = `/**
+ * ${GENERATED_FILE_NOTICE}
+ */
+`;
 /**
 * Generates the TypeScript declaration definition (`.d.ts`) for the virtual container module.
 * It exports the `ServiceIdentifiers` interface matching the runtime exports.
@@ -224,17 +358,22 @@ export default container;
 */
 function generateContainerTypeDefinition(metas, pathResolver) {
 	const resolver = new IdentifierResolver(metas);
+	const pool = createNamePool([
+		"Container",
+		"ServiceIdentifier",
+		"container"
+	]);
 	const imports = [];
 	const interfaceMembers = [];
 	for (const meta of metas) {
-		const importName = resolver.resolve(meta.className, meta.filePath);
+		const importName = pool.claim(resolver.resolve(meta.className, meta.filePath));
 		const importPath = pathResolver(meta.filePath);
 		if (importName === meta.className) imports.push(`import { ${meta.className} } from '${importPath}';`);
 		else imports.push(`import { ${meta.className} as ${importName} } from '${importPath}';`);
 		const exportKey = createIdentifierExportKey(meta, resolver);
 		interfaceMembers.push(`${exportKey}: ServiceIdentifier<${importName}>;`);
 	}
-	return `
+	return `${GENERATED_FILE_HEADER}
 declare module "virtual:alloy-container" {
   import { Container, ServiceIdentifier } from "alloy-di/runtime";
   ${imports.length ? imports.join("\n") + "\n" : ""}
@@ -258,7 +397,7 @@ declare module "virtual:alloy-container" {
 * @param manifests - List of loaded manifest info (packageName and services).
 */
 function generateManifestTypeDefinition(manifests) {
-	return manifests.map((m) => {
+	return GENERATED_FILE_HEADER + manifests.map((m) => {
 		const serviceIdentifiers = m.services.map((s) => `  export const ${s.exportName}Identifier: ServiceIdentifier;`).join("\n");
 		return `
 declare module "${m.packageName}/manifest" {
@@ -349,4 +488,4 @@ ${serviceIdentifiers}
 	}).join("\n");
 }
 //#endregion
-export { generateContainerModule, generateContainerTypeDefinition, generateManifestTypeDefinition };
+export { GENERATED_FILE_NOTICE, generateContainerModule, generateContainerTypeDefinition, generateManifestTypeDefinition };

package/dist/plugins/{vite-plugin → core}/container-loader.js

@@ -1,14 +1,18 @@
-import { normalizeImportPath } from "../core/utils.js";
-import { IdentifierResolver } from "../core/identifier-resolver.js";
-import { generateContainerModule, generateContainerTypeDefinition, generateManifestTypeDefinition } from "../core/codegen.js";
+import { normalizeImportPath, writeFileIfChanged } from "./utils.js";
+import { IdentifierResolver } from "./identifier-resolver.js";
+import { GENERATED_FILE_NOTICE, generateContainerModule, generateContainerTypeDefinition, generateManifestTypeDefinition } from "./codegen.js";
 import { augmentFactoryLazyServices, collectEagerReferencedNames, findDuplicateManifestServices, groupMetasByName, readManifests, reconcileLazySet, toMetaFromManifest } from "./manifest-utils.js";
 import { generateMermaidDiagram } from "./visualizer.js";
 import { ensureDirectoryForFile } from "./visualization-utils.js";
 import path from "node:path";
 import fs from "node:fs";
-//#region src/plugins/vite-plugin/container-loader.ts
+//#region src/plugins/core/container-loader.ts
 async function loadVirtualContainerModule(options) {
-	const metas = options.localMetas;
+	const metas = options.localMetas.map((meta) => ({
+		...meta,
+		metadata: { ...meta.metadata }
+	}));
+	const lazyClassKeys = new Set(options.lazyReferencedClassKeys);
 	assignIdentifierKeys(metas, options.packageName, options.resolvedRoot);
 	const manifestData = await readManifests(options.manifests);
 	const manifestServices = manifestData.services;
@@ -24,14 +28,13 @@ async function loadVirtualContainerModule(options) {
 	}))];
 	const resolver = new IdentifierResolver(combinedMetas);
 	const metasByName = groupMetasByName(combinedMetas);
-	for (const svc of manifestServices) metas.push(toMetaFromManifest(svc, metasByName, resolver, options.lazyReferencedClassKeys));
+	for (const svc of manifestServices) metas.push(toMetaFromManifest(svc, metasByName, resolver, lazyClassKeys));
 	const providerImports = Array.from(new Set([...options.providerImportPaths, ...manifestData.providers]));
-	const eagerReferencedNames = collectEagerReferencedNames(metas);
-	reconcileLazySet(metas, options.lazyReferencedClassKeys, eagerReferencedNames);
+	reconcileLazySet(metas, lazyClassKeys, collectEagerReferencedNames(metas));
 	augmentFactoryLazyServices(metas, options.lazyServiceKeys);
-	const code = generateContainerModule(metas, new Set(options.lazyReferencedClassKeys), providerImports);
+	const code = generateContainerModule(metas, lazyClassKeys, providerImports, { isDev: options.isDevMode });
 	writeTypeDefinitions(metas, loadedManifests, options.resolvedRoot, options.containerDeclarationDir);
-	writeVisualizationArtifact(metas, options.lazyReferencedClassKeys, options.resolvedVisualization);
+	writeVisualizationArtifact(metas, lazyClassKeys, options.resolvedVisualization);
 	return {
 		code,
 		moduleType: "js"
@@ -63,13 +66,13 @@ function writeTypeDefinitions(metas, loadedManifests, resolvedRoot, containerDec
 	const dtsDir = path.resolve(resolvedRoot, containerDeclarationDir ?? "./src");
 	const dtsContent = generateContainerTypeDefinition(metas, (filePath) => resolveDeclarationImportPath(dtsDir, filePath));
 	if (!fs.existsSync(dtsDir)) fs.mkdirSync(dtsDir, { recursive: true });
-	fs.writeFileSync(path.join(dtsDir, "alloy-container.d.ts"), dtsContent);
+	writeFileIfChanged(path.join(dtsDir, "alloy-container.d.ts"), dtsContent);
 	if (loadedManifests.length === 0) return;
 	const manifestsDts = generateManifestTypeDefinition(loadedManifests.map((m) => ({
 		packageName: m.packageName,
 		services: m.services
 	})));
-	fs.writeFileSync(path.join(dtsDir, "alloy-manifests.d.ts"), manifestsDts);
+	writeFileIfChanged(path.join(dtsDir, "alloy-manifests.d.ts"), manifestsDts);
 }
 function resolveDeclarationImportPath(dtsDir, filePath) {
 	if (!path.isAbsolute(filePath)) return filePath;
@@ -86,7 +89,7 @@ function writeVisualizationArtifact(metas, lazyReferencedClassKeys, resolvedVisu
 		options: resolvedVisualization.mermaidOptions
 	});
 	ensureDirectoryForFile(resolvedVisualization.outputPath);
-	fs.writeFileSync(resolvedVisualization.outputPath, `${artifact.diagram}\n`);
+	writeFileIfChanged(resolvedVisualization.outputPath, `%% ${GENERATED_FILE_NOTICE}\n${artifact.diagram}\n`);
 }
 //#endregion
 export { loadVirtualContainerModule };

package/dist/plugins/{vite-plugin → core}/discovery-runtime.js

@@ -1,6 +1,6 @@
-import { createClassKey } from "../core/utils.js";
-import { createDiscoveryStore } from "../core/discovery-store.js";
-//#region src/plugins/vite-plugin/discovery-runtime.ts
+import { createClassKey } from "./utils.js";
+import { createDiscoveryStore } from "./discovery-store.js";
+//#region src/plugins/core/discovery-runtime.ts
 /** Files the discovery scanner processes (mirrors the transform hook filter). */
 function isDiscoverableFile(file) {
 	return /\.tsx?$/i.test(file) && !/\.d\.ts$/i.test(file) && !file.includes("node_modules");
@@ -62,15 +62,5 @@ function createDiscoveryRuntime() {
 		}
 	};
 }
-/**
-* Invalidate the generated container module in every environment's module
-* graph so its `load` hook re-runs and regenerates from current discovery.
-*/
-function invalidateContainerModule(server, resolvedVirtualModuleId) {
-	for (const environment of Object.values(server.environments)) {
-		const mod = environment.moduleGraph.getModuleById(resolvedVirtualModuleId);
-		if (mod) environment.moduleGraph.invalidateModule(mod);
-	}
-}
 //#endregion
-export { createDiscoveryRuntime, invalidateContainerModule, isDiscoverableFile };
+export { createDiscoveryRuntime, isDiscoverableFile };

package/dist/plugins/core/discovery-store.js

@@ -1,10 +1,14 @@
 import { scanSource } from "./scanner.js";
+import crypto from "node:crypto";
 //#region src/plugins/core/discovery-store.ts
 /**
 * Maintains a per-file cache of discovered DI metadata, lazy references, and
 * optionally source snapshots to drive incremental recompilation inside the
 * Alloy discovery pipeline.
 */
+function hashContent(code) {
+	return crypto.createHash("sha1").update(code).digest("hex");
+}
 /**
 * Creates a file-scoped discovery store that caches scanner output and
 * optionally the original source for diagnostics or incremental rebuilds.
@@ -15,6 +19,7 @@ import { scanSource } from "./scanner.js";
 function createDiscoveryStore(options = {}) {
 	const fileMetas = /* @__PURE__ */ new Map();
 	const fileLazyRefs = /* @__PURE__ */ new Map();
+	const fileContentHashes = /* @__PURE__ */ new Map();
 	const fileSources = options.trackSources ? /* @__PURE__ */ new Map() : void 0;
 	/**
 	* Scan and cache the latest metadata for a file, returning both the fresh
@@ -26,6 +31,14 @@ function createDiscoveryStore(options = {}) {
 	function updateFile(id, code) {
 		const previousMetas = fileMetas.get(id);
 		const previousLazyClassKeys = fileLazyRefs.get(id);
+		const contentHash = hashContent(code);
+		if (fileContentHashes.get(id) === contentHash) return {
+			metas: previousMetas ?? [],
+			lazyClassKeys: new Set(previousLazyClassKeys),
+			previousMetas,
+			previousLazyClassKeys
+		};
+		fileContentHashes.set(id, contentHash);
 		if (fileSources) fileSources.set(id, code);
 		const { metas, lazyClassKeys } = scanSource(code, id);
 		if (metas.length) fileMetas.set(id, metas);
@@ -49,6 +62,7 @@ function createDiscoveryStore(options = {}) {
 		const previousLazyClassKeys = fileLazyRefs.get(id);
 		fileMetas.delete(id);
 		fileLazyRefs.delete(id);
+		fileContentHashes.delete(id);
 		if (fileSources) fileSources.delete(id);
 		return {
 			previousMetas,
@@ -61,6 +75,7 @@ function createDiscoveryStore(options = {}) {
 	function clear() {
 		fileMetas.clear();
 		fileLazyRefs.clear();
+		fileContentHashes.clear();
 		fileSources?.clear();
 	}
 	return {

package/dist/plugins/{vite-plugin → core}/manifest-utils.js

@@ -1,6 +1,6 @@
-import { createClassKey, createSymbolKey, normalizeImportPath } from "../core/utils.js";
+import { createClassKey, createSymbolKey, normalizeImportPath } from "./utils.js";
 import { z } from "zod";
-//#region src/plugins/vite-plugin/manifest-utils.ts
+//#region src/plugins/core/manifest-utils.ts
 /**
 * Reads a list of manifest objects and returns aggregated service + provider module specifiers.
 *
@@ -83,9 +83,16 @@ async function readManifests(inputs) {
 function readManifestByVersion(manifest) {
 	return (manifest.schemaVersion ?? 1) === 2 ? readManifestV2(manifest) : readManifestV1(manifest);
 }
+function warnInvalidManifest(manifest, error) {
+	const packageName = typeof manifest.packageName === "string" && manifest.packageName ? manifest.packageName : "<unknown package>";
+	console.warn(`[alloy] Ignoring invalid manifest "${packageName}" — its services and providers will not be registered:\n${z.prettifyError(error)}`);
+}
 function readManifestV1(manifest) {
 	const parsed = manifestSchemaV1.safeParse(manifest);
-	if (!parsed.success) return null;
+	if (!parsed.success) {
+		warnInvalidManifest(manifest, parsed.error);
+		return null;
+	}
 	return {
 		schemaVersion: 1,
 		packageName: parsed.data.packageName,
@@ -98,7 +105,10 @@ function readManifestV1(manifest) {
 }
 function readManifestV2(manifest) {
 	const parsed = manifestSchemaV2.safeParse(manifest);
-	if (!parsed.success) return null;
+	if (!parsed.success) {
+		warnInvalidManifest(manifest, parsed.error);
+		return null;
+	}
 	return {
 		schemaVersion: 2,
 		packageName: parsed.data.packageName,

package/dist/plugins/core/scanner.js

@@ -36,7 +36,19 @@ function collectFileImports(sourceFile) {
 	}
 	return imports;
 }
+/**
+* Cheap pre-filter that avoids the TS parse for files that cannot contribute
+* discovery results: decorators require an `@` and lazy references require
+* the `Lazy` identifier.
+*/
+function mayContainDiscoverableSyntax(code) {
+	return code.includes("@") || code.includes("Lazy");
+}
 function scanSource(code, id) {
+	if (!mayContainDiscoverableSyntax(code)) return {
+		metas: [],
+		lazyClassKeys: /* @__PURE__ */ new Set()
+	};
 	const sourceFile = ts.createSourceFile(id, code, ts.ScriptTarget.ESNext, true);
 	const discovered = /* @__PURE__ */ new Map();
 	const lazyRefs = /* @__PURE__ */ new Set();
@@ -80,7 +92,10 @@ function findServiceDecorator(node, sourceFile, fileImports, id, resolutionCache
 	const decorators = ts.getDecorators ? ts.getDecorators(node) : void 0;
 	if (!decorators?.length) return;
 	for (const decorator of decorators) {
-		if (!ts.isCallExpression(decorator.expression)) continue;
+		if (!ts.isCallExpression(decorator.expression)) {
+			warnOnBareAlloyDecorator(decorator, sourceFile, fileImports, id, resolutionCache);
+			continue;
+		}
 		const decoratorName = resolveDecoratorName(decorator.expression.expression, fileImports, id, new Set([id]), resolutionCache);
 		if (decoratorName) return {
 			decoratorCall: decorator.expression,
@@ -88,6 +103,20 @@ function findServiceDecorator(node, sourceFile, fileImports, id, resolutionCache
 		};
 	}
 }
+/**
+* Warn when an alloy decorator is applied bare (`@Injectable` instead of
+* `@Injectable()`). The scanner only registers call-expression decorators, so
+* the service would silently vanish from the container — and at runtime the
+* factory throws. Surfacing the location here makes the misuse findable at
+* build time.
+*/
+function warnOnBareAlloyDecorator(decorator, sourceFile, fileImports, id, resolutionCache) {
+	if (!ts.isIdentifier(decorator.expression) && !ts.isPropertyAccessExpression(decorator.expression)) return;
+	if (!resolveDecoratorName(decorator.expression, fileImports, id, new Set([id]), resolutionCache)) return;
+	const { line } = sourceFile.getLineAndCharacterOfPosition(decorator.getStart(sourceFile));
+	const appliedText = decorator.expression.getText(sourceFile);
+	console.warn(`[alloy] ${id}:${line + 1} applies @${appliedText} without calling it — use @${appliedText}(). The class will not be registered.`);
+}
 function resolveDecoratorName(expression, fileImports, id, visitedModules, resolutionCache) {
 	if (ts.isIdentifier(expression)) {
 		const importInfo = fileImports.get(expression.text);
@@ -104,11 +133,11 @@ function resolveImportedDecorator(importPath, requestedName, fromId, visitedModu
 	if (importPath === ALLOY_RUNTIME_MODULE) return isAlloyDecoratorName(requestedName) ? requestedName : void 0;
 	if (!importPath.startsWith(".")) return;
 	for (const candidate of resolveModuleSpecifierCandidates(fromId, importPath)) {
-		if (visitedModules.has(candidate) || !fs.existsSync(candidate)) continue;
 		const cacheKey = `${candidate}:${requestedName}`;
 		const cached = resolutionCache.get(cacheKey);
 		if (cached) return cached;
 		if (cached === null) continue;
+		if (visitedModules.has(candidate) || !fs.existsSync(candidate)) continue;
 		visitedModules.add(candidate);
 		try {
 			const source = fs.readFileSync(candidate, "utf8");

package/dist/plugins/core/utils.js

@@ -18,7 +18,7 @@ function ensureLeadingSlash(value) {
 }
 function hashString(value) {
 	let hash = 0;
-	for (let i = 0; i < value.length; i++) hash = Math.trunc(hash * 31 + value.charCodeAt(i));
+	for (let i = 0; i < value.length; i++) hash = hash * 31 + value.charCodeAt(i) | 0;
 	return Math.abs(hash).toString(36);
 }
 function createClassKey(filePath, className) {
@@ -30,14 +30,51 @@ function createAliasName(className, filePath) {
 function createSymbolKey(filePath, className) {
 	return `alloy:${normalizeImportPath(filePath)}#${className}`;
 }
-function walkSync(dir, fileList = []) {
-	if (!fs.existsSync(dir)) return fileList;
-	fs.readdirSync(dir).forEach((file) => {
-		const filePath = path.join(dir, file);
-		if (fs.statSync(filePath).isDirectory()) walkSync(filePath, fileList);
-		else fileList.push(filePath);
-	});
+const lastWrittenContent = /* @__PURE__ */ new Map();
+/**
+* Write a generated artifact only when its content actually changed.
+*
+* @returns true when the file was written, false when it already matched.
+*/
+function writeFileIfChanged(filePath, content) {
+	if (lastWrittenContent.get(filePath) === content) return false;
+	try {
+		if (fs.readFileSync(filePath, "utf-8") === content) {
+			lastWrittenContent.set(filePath, content);
+			return false;
+		}
+	} catch {}
+	fs.writeFileSync(filePath, content);
+	lastWrittenContent.set(filePath, content);
+	return true;
+}
+function walkSync(dir, fileList = [], visitedDirs) {
+	const visited = visitedDirs ?? /* @__PURE__ */ new Set();
+	let realDir;
+	try {
+		realDir = fs.realpathSync(dir);
+	} catch {
+		return fileList;
+	}
+	if (visited.has(realDir)) return fileList;
+	visited.add(realDir);
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name.startsWith(".")) continue;
+		const filePath = path.join(dir, entry.name);
+		if (entry.isDirectory()) walkSync(filePath, fileList, visited);
+		else if (entry.isFile()) fileList.push(filePath);
+		else if (entry.isSymbolicLink()) {
+			let stat;
+			try {
+				stat = fs.statSync(filePath);
+			} catch {
+				continue;
+			}
+			if (stat.isDirectory()) walkSync(filePath, fileList, visited);
+			else if (stat.isFile()) fileList.push(filePath);
+		}
+	}
 	return fileList;
 }
 //#endregion
-export { createAliasName, createClassKey, createSymbolKey, hashString, normalizeImportPath, walkSync };
+export { createAliasName, createClassKey, createSymbolKey, hashString, normalizeImportPath, walkSync, writeFileIfChanged };

package/dist/plugins/{vite-plugin → core}/visualization-utils.d.ts

@@ -1,6 +1,6 @@
 import { MermaidDiagramOptions } from "./visualizer.js";
 
-//#region src/plugins/vite-plugin/visualization-utils.d.ts
+//#region src/plugins/core/visualization-utils.d.ts
 interface AlloyMermaidVisualizerOptions extends MermaidDiagramOptions {
   outputPath?: string;
 }

package/dist/plugins/{vite-plugin → core}/visualization-utils.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import fs from "node:fs";
-//#region src/plugins/vite-plugin/visualization-utils.ts
+//#region src/plugins/core/visualization-utils.ts
 const DEFAULT_MERMAID_FILENAME = "alloy-di.mmd";
 function resolveVisualizationOptions(input, projectRoot) {
 	if (!input) return null;

package/dist/plugins/{vite-plugin → core}/visualizer.d.ts

@@ -1,6 +1,6 @@
 import { ServiceScope } from "../../lib/scope.js";
 
-//#region src/plugins/vite-plugin/visualizer.d.ts
+//#region src/plugins/core/visualizer.d.ts
 interface MermaidDiagramOptions {
   direction?: "LR" | "TB" | "BT" | "RL";
   includeLegend?: boolean;

package/dist/plugins/{vite-plugin → core}/visualizer.js

@@ -1,22 +1,22 @@
-import { createClassKey, createSymbolKey, hashString, normalizeImportPath } from "../core/utils.js";
+import { createClassKey, createSymbolKey, hashString, normalizeImportPath } from "./utils.js";
 import path from "node:path";
-//#region src/plugins/vite-plugin/visualizer.ts
+//#region src/plugins/core/visualizer.ts
 const DEFAULT_SCOPE_COLORS = {
-	singleton: "#f6c14a",
-	transient: "#58a6ff"
+	singleton: "#3b6ea5",
+	transient: "#2a7d73"
 };
 const DEFAULT_OPTIONS = {
 	direction: "LR",
 	includeLegend: true,
 	scopeColors: DEFAULT_SCOPE_COLORS,
-	lazyNodeFill: "#e8def8",
-	factoryNodeFill: "#ffe0b2",
-	tokenNodeFill: "#d1d5db",
-	nodeStrokeColor: "#1f2937",
-	nodeTextColor: "#111827",
-	lazyEdgeColor: "#a855f7",
-	eagerEdgeColor: "#6b7280",
-	factoryEdgeColor: "#ef6c00"
+	lazyNodeFill: "#6c5cb8",
+	factoryNodeFill: "#9c6516",
+	tokenNodeFill: "#4b5c6b",
+	nodeStrokeColor: "#5a7488",
+	nodeTextColor: "#ffffff",
+	lazyEdgeColor: "#9385d6",
+	eagerEdgeColor: "#7c93a6",
+	factoryEdgeColor: "#c2922e"
 };
 const RESERVED_IDENTIFIERS = new Set([
 	"Lazy",
@@ -95,7 +95,7 @@ function generateMermaidDiagram({ metas, lazyClassKeys, options }) {
 				edges.push({
 					from: sourceNode,
 					to: target,
-					label: describeEdge(sourceNode, target, dep.isLazy),
+					label: describeEdge(sourceNode, target),
 					isLazy: dep.isLazy,
 					stroke: selectEdgeColor(dep.isLazy, target, mergedOptions)
 				});
@@ -106,6 +106,7 @@ function generateMermaidDiagram({ metas, lazyClassKeys, options }) {
 	if (mergedOptions.includeLegend) {
 		lines.push(`  %% Legend: singleton=${mergedOptions.scopeColors.singleton}, transient=${mergedOptions.scopeColors.transient}, lazy-only=${mergedOptions.lazyNodeFill}, factory=${mergedOptions.factoryNodeFill}, token=${mergedOptions.tokenNodeFill}`);
 		lines.push(`  %% Edge colors: eager=${mergedOptions.eagerEdgeColor}, lazy=${mergedOptions.lazyEdgeColor}, factory=${mergedOptions.factoryEdgeColor}`);
+		lines.push(`  %% Edge labels: Si=singleton, Tr=transient, Tk=token; solid=eager, dotted=lazy`);
 	}
 	const allNodes = [...serviceNodes, ...Array.from(tokenNodes.values())];
 	for (const node of allNodes) {
@@ -155,11 +156,18 @@ function sanitizeMermaidId(source, fallbackIndex) {
 function escapeMermaidLabel(label) {
 	return label.replaceAll("\"", "\\\"").replaceAll("|", "/");
 }
+/** Single-token code for a node's scope/kind: Si, Tr, or Tk (token). */
+function scopeCode(node) {
+	if (node.type === "token") return "Tk";
+	return node.scope === "transient" ? "Tr" : "Si";
+}
 /**
-* Builds a human-readable label describing the nature of an edge between two nodes.
+* Builds a compact edge label as a `source→target` scope transition (e.g.
+* `Si→Tr`). Eager/lazy is conveyed by the arrow style and the target kind by
+* node color, so they are intentionally omitted from the text. See the legend.
 */
-function describeEdge(from, to, depIsLazy) {
-	return `${depIsLazy ? "Lazy" : "Eager"} · ${from.scope ?? "unknown"}→${to.type === "token" ? "token" : to.scope ?? "unknown"} · ${to.type === "token" ? "Token" : to.hasFactory ? "Factory" : "Class"}`;
+function describeEdge(from, to) {
+	return `${scopeCode(from)}→${scopeCode(to)}`;
 }
 /**
 * Determines the fill color for a node based on its type, scope, and lazy/factory flags.

package/dist/plugins/vite-plugin/index.d.ts

@@ -1,6 +1,6 @@
 import { ServiceIdentifier } from "../../lib/service-identifiers.js";
 import { AlloyManifest } from "../core/types.js";
-import { AlloyMermaidVisualizerOptions, AlloyVisualizationOptions } from "./visualization-utils.js";
+import { AlloyMermaidVisualizerOptions, AlloyVisualizationOptions } from "../core/visualization-utils.js";
 import { Plugin } from "vite";
 
 //#region src/plugins/vite-plugin/index.d.ts

package/dist/plugins/vite-plugin/index.js

@@ -1,7 +1,8 @@
 import { normalizeImportPath, walkSync } from "../core/utils.js";
-import { resolveVisualizationOptions } from "./visualization-utils.js";
-import { loadVirtualContainerModule } from "./container-loader.js";
-import { createDiscoveryRuntime, invalidateContainerModule, isDiscoverableFile } from "./discovery-runtime.js";
+import { resolveVisualizationOptions } from "../core/visualization-utils.js";
+import { loadVirtualContainerModule } from "../core/container-loader.js";
+import { createDiscoveryRuntime, isDiscoverableFile } from "../core/discovery-runtime.js";
+import { invalidateContainerModule } from "./module-invalidation.js";
 import path from "node:path";
 import fs from "node:fs";
 //#region src/plugins/vite-plugin/index.ts
@@ -22,6 +23,7 @@ function alloy(options = {}) {
 	let resolvedRoot = process.cwd();
 	let packageName = "UNKNOWN_PACKAGE";
 	let resolvedVisualization = null;
+	let isDevMode;
 	const lazyServiceKeys = new Set((options.lazyServices ?? []).map(toLazyServiceKey));
 	const discoveryRuntime = createDiscoveryRuntime();
 	return {
@@ -29,6 +31,7 @@ function alloy(options = {}) {
 		enforce: "pre",
 		configResolved(config) {
 			resolvedRoot = config.root ?? process.cwd();
+			isDevMode = !config.isProduction;
 			try {
 				const pkgPath = path.resolve(resolvedRoot, "package.json");
 				const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
@@ -102,7 +105,8 @@ function alloy(options = {}) {
 					packageName,
 					resolvedRoot,
 					containerDeclarationDir: options.containerDeclarationDir,
-					resolvedVisualization
+					resolvedVisualization,
+					isDevMode
 				});
 			}
 		}

package/dist/plugins/vite-plugin/module-invalidation.js

@@ -0,0 +1,13 @@
+//#region src/plugins/vite-plugin/module-invalidation.ts
+/**
+* Invalidate the generated container module in every environment's module
+* graph so its `load` hook re-runs and regenerates from current discovery.
+*/
+function invalidateContainerModule(server, resolvedVirtualModuleId) {
+	for (const environment of Object.values(server.environments)) {
+		const mod = environment.moduleGraph.getModuleById(resolvedVirtualModuleId);
+		if (mod) environment.moduleGraph.invalidateModule(mod);
+	}
+}
+//#endregion
+export { invalidateContainerModule };

package/dist/runtime.d.ts

@@ -1,7 +1,8 @@
 import { Newable, Token, createToken } from "./lib/types.js";
 import { ServiceIdentifier, clearServiceIdentifierRegistry, getConstructorByIdentifier, getServiceIdentifier, registerServiceIdentifier } from "./lib/service-identifiers.js";
 import { Container } from "./lib/container.js";
+import { EnvDetectionOverrides, setEnvDetectionOverrides } from "./lib/env-detection.js";
 import { LAZY_IDENTIFIER, Lazy } from "./lib/lazy.js";
 import { Injectable, Singleton, assertDeps, dependenciesRegistry, deps } from "./lib/decorators.js";
 import { ProviderDefinitions, applyProviders, asClass, asLazyClass, asValue, defineProviders, lifecycle } from "./lib/providers.js";
-export { Container, Injectable, LAZY_IDENTIFIER, Lazy, type Lazy as LazyInterface, type Newable, type ProviderDefinitions, type ServiceIdentifier, Singleton, type Token, applyProviders, asClass, asLazyClass, asValue, assertDeps, clearServiceIdentifierRegistry, createToken, defineProviders, dependenciesRegistry, deps, getConstructorByIdentifier, getServiceIdentifier, lifecycle, registerServiceIdentifier };
+export { Container, type EnvDetectionOverrides, Injectable, LAZY_IDENTIFIER, Lazy, type Lazy as LazyInterface, type Newable, type ProviderDefinitions, type ServiceIdentifier, Singleton, type Token, applyProviders, asClass, asLazyClass, asValue, assertDeps, clearServiceIdentifierRegistry, createToken, defineProviders, dependenciesRegistry, deps, getConstructorByIdentifier, getServiceIdentifier, lifecycle, registerServiceIdentifier, setEnvDetectionOverrides };

package/dist/runtime.js

@@ -2,6 +2,7 @@ import { createToken } from "./lib/types.js";
 import { LAZY_IDENTIFIER, Lazy } from "./lib/lazy.js";
 import { Injectable, Singleton, assertDeps, dependenciesRegistry, deps } from "./lib/decorators.js";
 import { clearServiceIdentifierRegistry, getConstructorByIdentifier, getServiceIdentifier, registerServiceIdentifier } from "./lib/service-identifiers.js";
+import { setEnvDetectionOverrides } from "./lib/env-detection.js";
 import { Container } from "./lib/container.js";
 import { applyProviders, asClass, asLazyClass, asValue, defineProviders, lifecycle } from "./lib/providers.js";
-export { Container, Injectable, LAZY_IDENTIFIER, Lazy, Singleton, applyProviders, asClass, asLazyClass, asValue, assertDeps, clearServiceIdentifierRegistry, createToken, defineProviders, dependenciesRegistry, deps, getConstructorByIdentifier, getServiceIdentifier, lifecycle, registerServiceIdentifier };
+export { Container, Injectable, LAZY_IDENTIFIER, Lazy, Singleton, applyProviders, asClass, asLazyClass, asValue, assertDeps, clearServiceIdentifierRegistry, createToken, defineProviders, dependenciesRegistry, deps, getConstructorByIdentifier, getServiceIdentifier, lifecycle, registerServiceIdentifier, setEnvDetectionOverrides };

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/entry-points.test.ts","../src/rollup.ts","../src/runtime.ts","../src/test.ts","../src/vite.ts","../src/lib/container.identifiers.test.ts","../src/lib/container.internals.test.ts","../src/lib/container.test.ts","../src/lib/container.testing-features.test.ts","../src/lib/container.ts","../src/lib/decorators.runtime.test.ts","../src/lib/decorators.test-d.ts","../src/lib/decorators.ts","../src/lib/dependency-error.ts","../src/lib/env-detection.test.ts","../src/lib/env-detection.ts","../src/lib/lazy-retry.test.ts","../src/lib/lazy.ts","../src/lib/providers.test.ts","../src/lib/providers.ts","../src/lib/scope.ts","../src/lib/service-identifiers.test.ts","../src/lib/service-identifiers.ts","../src/lib/tokens.test.ts","../src/lib/types.ts","../src/lib/testing/mocking.test.ts","../src/lib/testing/mocking.ts","../src/lib/testing/registry.test.ts","../src/lib/testing/registry.ts","../src/plugins/core/codegen.test.ts","../src/plugins/core/codegen.ts","../src/plugins/core/decorators.helpers.test.ts","../src/plugins/core/decorators.ts","../src/plugins/core/discovery-store.ts","../src/plugins/core/identifier-resolver.test.ts","../src/plugins/core/identifier-resolver.ts","../src/plugins/core/lazy-utils.ts","../src/plugins/core/lazy.helpers.test.ts","../src/plugins/core/lazy.ts","../src/plugins/core/scanner.test.ts","../src/plugins/core/scanner.ts","../src/plugins/core/types.ts","../src/plugins/core/utils.ts","../src/plugins/rollup-plugin/build-utils.ts","../src/plugins/rollup-plugin/index.ts","../src/plugins/rollup-plugin/rollup-plugin.test.ts","../src/plugins/vite-plugin/codegen.specifier.test.ts","../src/plugins/vite-plugin/container-loader.ts","../src/plugins/vite-plugin/discovery-runtime.ts","../src/plugins/vite-plugin/duplicate-registrations.test.ts","../src/plugins/vite-plugin/fixture-subpaths.test.ts","../src/plugins/vite-plugin/index.ts","../src/plugins/vite-plugin/lazy-services.test.ts","../src/plugins/vite-plugin/lifecycle-and-hmr.test.ts","../src/plugins/vite-plugin/manifest-utils.ts","../src/plugins/vite-plugin/manifest-utils.validation.test.ts","../src/plugins/vite-plugin/module-generation.test.ts","../src/plugins/vite-plugin/test-utils.ts","../src/plugins/vite-plugin/transform-guards.test.ts","../src/plugins/vite-plugin/visualization-option.test.ts","../src/plugins/vite-plugin/visualization-utils.ts","../src/plugins/vite-plugin/visualizer.test.ts","../src/plugins/vite-plugin/visualizer.ts"],"version":"6.0.3"}
+{"root":["../src/entry-points.test.ts","../src/fixture-subpaths.test.ts","../src/rollup.ts","../src/runtime.ts","../src/test.ts","../src/vite.ts","../src/lib/container.identifiers.test.ts","../src/lib/container.internals.test.ts","../src/lib/container.test.ts","../src/lib/container.testing-features.test.ts","../src/lib/container.ts","../src/lib/decorators.runtime.test.ts","../src/lib/decorators.test-d.ts","../src/lib/decorators.ts","../src/lib/dependency-error.ts","../src/lib/env-detection.test.ts","../src/lib/env-detection.ts","../src/lib/lazy-retry.test.ts","../src/lib/lazy.ts","../src/lib/providers.test.ts","../src/lib/providers.ts","../src/lib/scope.ts","../src/lib/service-identifiers.test.ts","../src/lib/service-identifiers.ts","../src/lib/tokens.test.ts","../src/lib/types.ts","../src/lib/testing/mocking.test.ts","../src/lib/testing/mocking.ts","../src/lib/testing/registry.test.ts","../src/lib/testing/registry.ts","../src/plugins/core/codegen.test.ts","../src/plugins/core/codegen.ts","../src/plugins/core/container-loader.test.ts","../src/plugins/core/container-loader.ts","../src/plugins/core/decorators.helpers.test.ts","../src/plugins/core/decorators.ts","../src/plugins/core/discovery-runtime.ts","../src/plugins/core/discovery-store.test.ts","../src/plugins/core/discovery-store.ts","../src/plugins/core/identifier-resolver.test.ts","../src/plugins/core/identifier-resolver.ts","../src/plugins/core/lazy-utils.ts","../src/plugins/core/lazy.helpers.test.ts","../src/plugins/core/lazy.ts","../src/plugins/core/manifest-utils.ts","../src/plugins/core/manifest-utils.validation.test.ts","../src/plugins/core/scanner.test.ts","../src/plugins/core/scanner.ts","../src/plugins/core/types.ts","../src/plugins/core/utils.ts","../src/plugins/core/utils.walk.test.ts","../src/plugins/core/utils.write.test.ts","../src/plugins/core/visualization-utils.ts","../src/plugins/core/visualizer.test.ts","../src/plugins/core/visualizer.ts","../src/plugins/rollup-plugin/build-utils.ts","../src/plugins/rollup-plugin/index.ts","../src/plugins/rollup-plugin/rollup-plugin.test.ts","../src/plugins/vite-plugin/duplicate-registrations.test.ts","../src/plugins/vite-plugin/index.ts","../src/plugins/vite-plugin/lazy-services.test.ts","../src/plugins/vite-plugin/lifecycle-and-hmr.test.ts","../src/plugins/vite-plugin/module-generation.test.ts","../src/plugins/vite-plugin/module-invalidation.ts","../src/plugins/vite-plugin/test-utils.ts","../src/plugins/vite-plugin/transform-guards.test.ts","../src/plugins/vite-plugin/visualization-option.test.ts"],"version":"6.0.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alloy-di",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "A compile-time dependency injection plugin for Vite",
   "keywords": [
     "dependency-injection",