@blac/core 2.0.3 → 2.0.5

package/dist/index.cjs

@@ -1,9 +1,3 @@
-const require_StateContainerRegistry = require('./StateContainerRegistry.cjs');
-const require_tracking_proxy = require('./tracking-proxy.cjs');
-const require_management = require('./management.cjs');
-const require_watch = require('./watch.cjs');
-const require_dependency_manager = require('./dependency-manager.cjs');
-require('./tracking.cjs');
 
 //#region src/utils/idGenerator.ts
 /**
@@ -37,8 +31,576 @@ function generateIsolatedKey() {
 	return `isolated-${Math.random().toString(36).slice(2, 11)}`;
 }
 
+//#endregion
+//#region src/constants.ts
+/**
+* Default configuration constants for BlaC
+*
+* Centralized location for all magic numbers and default values.
+*/
+/**
+* Default configuration constants for BlaC
+*/
+const BLAC_DEFAULTS = {
+	DEFAULT_INSTANCE_KEY: "default",
+	MAX_GETTER_DEPTH: 10,
+	CLEANUP_INTERVAL_MS: 3e4,
+	WEAKREF_CLEANUP_INTERVAL_MS: 1e4,
+	MAX_SUBSCRIPTIONS: 1e3,
+	MAX_SUBSCRIPTIONS_HIGH_PERF: 1e4,
+	PIPELINE_TIMEOUT_MS: 5e3,
+	CLEANUP_INTERVAL_HIGH_PERF_MS: 5e3,
+	MAX_PIPELINE_STAGES: 30
+};
+/**
+* Static property names for StateContainer classes
+* Used for feature flags and configuration on bloc classes
+*/
+const BLAC_STATIC_PROPS = {
+	ISOLATED: "isolated",
+	KEEP_ALIVE: "keepAlive",
+	EXCLUDE_FROM_DEVTOOLS: "__excludeFromDevTools"
+};
+/**
+* Standard error message prefix
+*/
+const BLAC_ERROR_PREFIX = "[BlaC]";
+
+//#endregion
+//#region src/plugin/PluginManager.ts
+/**
+* Manages plugin lifecycle for the BlaC state management system.
+* Plugins receive notifications about state container lifecycle events.
+*
+* @example
+* ```ts
+* const manager = createPluginManager(registry);
+* manager.install(myPlugin, { environment: 'development' });
+* ```
+*/
+var PluginManager = class {
+	/**
+	* Create a new PluginManager
+	* @param registry - The StateContainerRegistry to monitor for lifecycle events
+	*/
+	constructor(registry) {
+		this.plugins = /* @__PURE__ */ new Map();
+		this.registry = registry;
+		this.setupLifecycleHooks();
+	}
+	/**
+	* Install a plugin with optional configuration
+	* @param plugin - The plugin to install
+	* @param config - Optional plugin configuration
+	* @throws Error if plugin is already installed
+	*/
+	install(plugin, config = {}) {
+		const effectiveConfig = {
+			enabled: true,
+			environment: "all",
+			...config
+		};
+		if (!this.shouldEnablePlugin(effectiveConfig)) {
+			console.log(`[BlaC] Plugin "${plugin.name}" skipped (environment mismatch)`);
+			return;
+		}
+		if (this.plugins.has(plugin.name)) throw new Error(`Plugin "${plugin.name}" is already installed`);
+		const context = this.createPluginContext();
+		this.plugins.set(plugin.name, {
+			plugin,
+			config: effectiveConfig,
+			context
+		});
+		if (plugin.onInstall) try {
+			plugin.onInstall(context);
+		} catch (error) {
+			console.error(`[BlaC] Error installing plugin "${plugin.name}":`, error);
+			this.plugins.delete(plugin.name);
+			throw error;
+		}
+		console.log(`[BlaC] Plugin "${plugin.name}" v${plugin.version} installed`);
+	}
+	/**
+	* Uninstall a plugin by name
+	* @param pluginName - The name of the plugin to uninstall
+	* @throws Error if plugin is not installed
+	*/
+	uninstall(pluginName) {
+		const installed = this.plugins.get(pluginName);
+		if (!installed) throw new Error(`Plugin "${pluginName}" is not installed`);
+		if (installed.plugin.onUninstall) try {
+			installed.plugin.onUninstall();
+		} catch (error) {
+			console.error(`[BlaC] Error uninstalling plugin "${pluginName}":`, error);
+		}
+		this.plugins.delete(pluginName);
+		console.log(`[BlaC] Plugin "${pluginName}" uninstalled`);
+	}
+	/**
+	* Get an installed plugin by name
+	* @param pluginName - The name of the plugin to retrieve
+	* @returns The plugin instance or undefined if not found
+	*/
+	getPlugin(pluginName) {
+		return this.plugins.get(pluginName)?.plugin;
+	}
+	/**
+	* Get all installed plugins
+	* @returns Array of all installed plugins
+	*/
+	getAllPlugins() {
+		return Array.from(this.plugins.values()).map((p) => p.plugin);
+	}
+	/**
+	* Check if a plugin is installed
+	* @param pluginName - The name of the plugin to check
+	* @returns true if the plugin is installed
+	*/
+	hasPlugin(pluginName) {
+		return this.plugins.has(pluginName);
+	}
+	/**
+	* Uninstall all plugins
+	*/
+	clear() {
+		for (const name of this.plugins.keys()) this.uninstall(name);
+	}
+	/**
+	* Setup lifecycle hooks to notify plugins
+	*/
+	setupLifecycleHooks() {
+		this.registry.on("created", (instance) => {
+			this.notifyPlugins("onInstanceCreated", instance);
+		});
+		this.registry.on("stateChanged", (instance, previousState, currentState, callstack) => {
+			this.notifyPlugins("onStateChanged", instance, previousState, currentState, callstack);
+		});
+		this.registry.on("disposed", (instance) => {
+			this.notifyPlugins("onInstanceDisposed", instance);
+		});
+	}
+	/**
+	* Notify all plugins of a lifecycle event
+	*/
+	notifyPlugins(hookName, ...args) {
+		for (const { plugin, config, context } of this.plugins.values()) {
+			if (!config.enabled) continue;
+			const hook = plugin[hookName];
+			if (typeof hook === "function") try {
+				hook.apply(plugin, [...args, context]);
+			} catch (error) {
+				console.error(`[BlaC] Error in plugin "${plugin.name}" ${hookName}:`, error);
+			}
+		}
+	}
+	/**
+	* Create plugin context with safe API access
+	*/
+	createPluginContext() {
+		return {
+			getInstanceMetadata: (instance) => {
+				return {
+					id: instance.instanceId,
+					className: instance.constructor.name,
+					isDisposed: instance.isDisposed,
+					name: instance.name,
+					lastStateChangeTimestamp: instance.lastUpdateTimestamp,
+					createdAt: instance.createdAt,
+					state: instance.state,
+					isIsolated: instance.instanceId.startsWith("isolated-")
+				};
+			},
+			getState: (instance) => {
+				return instance.state;
+			},
+			queryInstances: (typeClass) => {
+				return this.registry.getAll(typeClass);
+			},
+			getAllTypes: () => {
+				return this.registry.getTypes();
+			},
+			getStats: () => {
+				return this.registry.getStats();
+			}
+		};
+	}
+	/**
+	* Check if plugin should be enabled based on environment
+	*/
+	shouldEnablePlugin(config) {
+		if (!config.enabled) return false;
+		if (config.environment === "all") return true;
+		return this.getCurrentEnvironment() === config.environment;
+	}
+	/**
+	* Get current environment
+	*/
+	getCurrentEnvironment() {
+		if (typeof process !== "undefined") {
+			if (process.env.NODE_ENV === "test") return "test";
+			if (process.env.NODE_ENV === "production") return "production";
+			return "development";
+		}
+		return "development";
+	}
+};
+/**
+* Create a plugin manager instance
+* @param registry - The StateContainerRegistry to monitor for lifecycle events
+* @returns A new PluginManager instance
+*/
+function createPluginManager(registry) {
+	return new PluginManager(registry);
+}
+
+//#endregion
+//#region src/utils/static-props.ts
+/**
+* Utility functions for accessing static properties on StateContainer classes
+*/
+/**
+* Get a static property from a class constructor
+* Type-safe helper that avoids (Type as any) casts
+*
+* @param Type - The class constructor
+* @param propName - The property name to access
+* @param defaultValue - Optional default value if property is undefined
+* @returns The property value or default
+*/
+function getStaticProp(Type, propName, defaultValue) {
+	return Type[propName] ?? defaultValue;
+}
+/**
+* Check if a class is marked as isolated.
+* Isolated classes create separate instances per component.
+* @param Type - The class constructor to check
+* @returns true if the class has `static isolated = true`
+*/
+function isIsolatedClass(Type) {
+	return getStaticProp(Type, BLAC_STATIC_PROPS.ISOLATED) === true;
+}
+/**
+* Check if a class is marked as keepAlive.
+* KeepAlive classes are never auto-disposed when ref count reaches 0.
+* @param Type - The class constructor to check
+* @returns true if the class has `static keepAlive = true`
+*/
+function isKeepAliveClass(Type) {
+	return getStaticProp(Type, BLAC_STATIC_PROPS.KEEP_ALIVE) === true;
+}
+
+//#endregion
+//#region src/core/StateContainerRegistry.ts
+/**
+* Central registry for managing StateContainer instances.
+* Handles instance lifecycle, ref counting, and lifecycle event emission.
+*
+* @example
+* ```ts
+* const registry = new StateContainerRegistry();
+* const instance = registry.acquire(MyBloc);  // ownership, must release
+* const other = registry.ensure(OtherBloc);   // no ownership, bloc-to-bloc
+* registry.on('stateChanged', (container, prev, next) => {
+*   console.log('State changed:', prev, '->', next);
+* });
+* ```
+*/
+var StateContainerRegistry = class {
+	constructor() {
+		this.instancesByConstructor = /* @__PURE__ */ new WeakMap();
+		this.types = /* @__PURE__ */ new Set();
+		this.typeConfigs = /* @__PURE__ */ new Map();
+		this.listeners = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Register a type for lifecycle event tracking
+	* @param constructor - The StateContainer class constructor
+	*/
+	registerType(constructor) {
+		this.types.add(constructor);
+	}
+	/**
+	* Register a StateContainer class with configuration
+	* @param constructor - The StateContainer class constructor
+	* @param isolated - Whether instances should be isolated (component-scoped)
+	* @throws Error if type is already registered
+	*/
+	register(constructor, isolated = false) {
+		const className = constructor.name;
+		if (!isolated && isIsolatedClass(constructor)) isolated = true;
+		if (this.typeConfigs.has(className)) throw new Error(`${BLAC_ERROR_PREFIX} Type "${className}" is already registered`);
+		this.typeConfigs.set(className, { isolated });
+		this.registerType(constructor);
+	}
+	ensureInstancesMap(Type) {
+		let instances = this.instancesByConstructor.get(Type);
+		if (!instances) {
+			instances = /* @__PURE__ */ new Map();
+			this.instancesByConstructor.set(Type, instances);
+		}
+		return instances;
+	}
+	/**
+	* Get the instances Map for a specific class (public API for stats/debugging)
+	*/
+	getInstancesMap(Type) {
+		return this.instancesByConstructor.get(Type) || /* @__PURE__ */ new Map();
+	}
+	/**
+	* Acquire an instance with ref counting (ownership semantics).
+	* Creates a new instance if one doesn't exist, or returns existing and increments ref count.
+	* You must call `release()` when done to decrement the ref count.
+	* @param Type - The StateContainer class constructor
+	* @param instanceKey - Instance key (defaults to 'default')
+	* @param options - Acquisition options
+	* @param options.canCreate - Whether to create new instance if not found (default: true)
+	* @param options.countRef - Whether to increment ref count (default: true)
+	* @returns The state container instance
+	*/
+	acquire(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, options = {}) {
+		const { canCreate = true, countRef = true } = options;
+		const registryConfig = this.typeConfigs.get(Type.name);
+		const isolated = isIsolatedClass(Type) || registryConfig?.isolated === true;
+		const config = { instanceId: instanceKey };
+		if (isolated && !canCreate) throw new Error(`${BLAC_ERROR_PREFIX} Cannot get isolated instance "${instanceKey}" of ${Type.name} when creation is disabled.`);
+		if (isolated) {
+			const instance = new Type();
+			instance.initConfig(config);
+			this.registerType(Type);
+			return instance;
+		}
+		const instances = this.ensureInstancesMap(Type);
+		let entry = instances.get(instanceKey);
+		if (entry?.instance.isDisposed) {
+			instances.delete(instanceKey);
+			entry = void 0;
+		}
+		if (entry && countRef) entry.refCount++;
+		if (entry) return entry.instance;
+		if (!canCreate) throw new Error(`${BLAC_ERROR_PREFIX} ${Type.name} instance "${instanceKey}" not found and creation is disabled.`);
+		const instance = new Type();
+		instance.initConfig(config);
+		instances.set(instanceKey, {
+			instance,
+			refCount: 1
+		});
+		this.registerType(Type);
+		return instance;
+	}
+	/**
+	* Borrow an existing instance without incrementing ref count (borrowing semantics).
+	* Tracks cross-bloc dependency for reactive updates.
+	* @param Type - The StateContainer class constructor
+	* @param instanceKey - Instance key (defaults to 'default')
+	* @returns The state container instance
+	* @throws Error if instance doesn't exist
+	*/
+	borrow(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		return this.acquire(Type, instanceKey, {
+			canCreate: false,
+			countRef: false
+		});
+	}
+	/**
+	* Safely borrow an existing instance (borrowing semantics with error handling).
+	* Returns discriminated union for type-safe conditional access.
+	* @param Type - The StateContainer class constructor
+	* @param instanceKey - Instance key (defaults to 'default')
+	* @returns Discriminated union with either the instance or an error
+	*/
+	borrowSafe(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		try {
+			return {
+				error: null,
+				instance: this.borrow(Type, instanceKey)
+			};
+		} catch (error) {
+			return {
+				error,
+				instance: null
+			};
+		}
+	}
+	/**
+	* Ensure an instance exists without taking ownership (for bloc-to-bloc communication).
+	* Gets existing instance OR creates it if it doesn't exist, without incrementing ref count.
+	* Tracks cross-bloc dependency for reactive updates.
+	*
+	* Use this in bloc-to-bloc communication when you need to ensure an instance exists
+	* but don't want to claim ownership (no ref count increment).
+	* @param Type - The StateContainer class constructor
+	* @param instanceKey - Instance key (defaults to 'default')
+	* @returns The state container instance
+	*/
+	ensure(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		return this.acquire(Type, instanceKey, {
+			canCreate: true,
+			countRef: false
+		});
+	}
+	/**
+	* Release a reference to an instance.
+	* Decrements ref count and disposes when it reaches 0 (unless keepAlive).
+	* @param Type - The StateContainer class constructor
+	* @param instanceKey - Instance key (defaults to 'default')
+	* @param forceDispose - Force immediate disposal regardless of ref count
+	*/
+	release(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, forceDispose = false) {
+		const instances = this.ensureInstancesMap(Type);
+		const entry = instances.get(instanceKey);
+		if (!entry) return;
+		if (forceDispose) {
+			if (!entry.instance.isDisposed) entry.instance.dispose();
+			instances.delete(instanceKey);
+			return;
+		}
+		entry.refCount--;
+		const keepAlive = isKeepAliveClass(Type);
+		if (entry.refCount <= 0 && !keepAlive) {
+			if (!entry.instance.isDisposed) entry.instance.dispose();
+			instances.delete(instanceKey);
+		}
+	}
+	/**
+	* Get all instances of a specific type.
+	* @param Type - The StateContainer class constructor
+	* @returns Array of all instances
+	*/
+	getAll(Type) {
+		const instances = this.ensureInstancesMap(Type);
+		const result = [];
+		for (const entry of instances.values()) result.push(entry.instance);
+		return result;
+	}
+	/**
+	* Safely iterate over all instances of a type.
+	* Skips disposed instances and catches callback errors.
+	* @param Type - The StateContainer class constructor
+	* @param callback - Function to call for each instance
+	*/
+	forEach(Type, callback) {
+		const instances = this.ensureInstancesMap(Type);
+		for (const entry of instances.values()) {
+			const instance = entry.instance;
+			if (!instance.isDisposed) try {
+				callback(instance);
+			} catch (error) {
+				console.error(`${BLAC_ERROR_PREFIX} forEach callback error for ${Type.name}:`, error);
+			}
+		}
+	}
+	/**
+	* Clear all instances of a specific type (disposes them).
+	* @param Type - The StateContainer class constructor
+	*/
+	clear(Type) {
+		const instances = this.ensureInstancesMap(Type);
+		for (const entry of instances.values()) if (!entry.instance.isDisposed) entry.instance.dispose();
+		instances.clear();
+	}
+	/**
+	* Get reference count for an instance.
+	* @param Type - The StateContainer class constructor
+	* @param instanceKey - Instance key (defaults to 'default')
+	* @returns Current ref count (0 if instance doesn't exist)
+	*/
+	getRefCount(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		return this.ensureInstancesMap(Type).get(instanceKey)?.refCount ?? 0;
+	}
+	/**
+	* Check if an instance exists.
+	* @param Type - The StateContainer class constructor
+	* @param instanceKey - Instance key (defaults to 'default')
+	* @returns true if instance exists
+	*/
+	hasInstance(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		return this.ensureInstancesMap(Type).has(instanceKey);
+	}
+	/**
+	* Clear all instances from all types (for testing)
+	*
+	* Iterates all registered types and clears their instances.
+	* Also clears type tracking to reset the registry state.
+	*/
+	clearAll() {
+		for (const Type of this.types) this.clear(Type);
+		this.types.clear();
+		this.typeConfigs.clear();
+	}
+	/**
+	* Get registry statistics for debugging.
+	* @returns Object with registeredTypes, totalInstances, and typeBreakdown
+	*/
+	getStats() {
+		const typeBreakdown = {};
+		let totalInstances = 0;
+		for (const Type of this.types) {
+			const typeName = Type.name;
+			const count = this.getInstancesMap(Type).size;
+			typeBreakdown[typeName] = count;
+			totalInstances += count;
+		}
+		return {
+			registeredTypes: this.types.size,
+			totalInstances,
+			typeBreakdown
+		};
+	}
+	/**
+	* Get all registered types (for plugin system).
+	* @returns Array of all registered StateContainer class constructors
+	*/
+	getTypes() {
+		return Array.from(this.types);
+	}
+	/**
+	* Subscribe to lifecycle events
+	* @param event - The lifecycle event to listen for
+	* @param listener - The listener function to call when the event occurs
+	* @returns Unsubscribe function
+	*/
+	on(event, listener) {
+		if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
+		const instance = this.listeners.get(event);
+		if (!instance) throw new Error(`${BLAC_ERROR_PREFIX} Failed to register listener for event '${event}'`);
+		instance.add(listener);
+		return () => {
+			this.listeners.get(event)?.delete(listener);
+		};
+	}
+	/**
+	* Emit lifecycle event to all listeners
+	* @internal - Called by StateContainer lifecycle methods
+	*/
+	emit(event, ...args) {
+		const listeners = this.listeners.get(event);
+		if (!listeners || listeners.size === 0) return;
+		for (const listener of listeners) try {
+			listener(...args);
+		} catch (error) {
+			console.error(`${BLAC_ERROR_PREFIX} Listener error for '${event}':`, error);
+		}
+	}
+};
+/**
+* Global default registry instance
+*/
+const globalRegistry = new StateContainerRegistry();
+/**
+* Global plugin manager (initialized lazily)
+*/
+let _globalPluginManager = null;
+/**
+* Get the global plugin manager
+*/
+function getPluginManager() {
+	if (!_globalPluginManager) _globalPluginManager = createPluginManager(globalRegistry);
+	return _globalPluginManager;
+}
+
 //#endregion
 //#region src/core/StateContainer.ts
+const EMPTY_DEPS = /* @__PURE__ */ new Map();
 /**
 * Abstract base class for all state containers in BlaC.
 * Provides lifecycle management, subscription handling, ref counting,
@@ -65,6 +627,14 @@ var StateContainer = class StateContainer {
 	static {
 		this.enableStackTrace = true;
 	}
+	get dependencies() {
+		return this._dependencies ?? EMPTY_DEPS;
+	}
+	depend(Type, instanceKey) {
+		if (!this._dependencies) this._dependencies = /* @__PURE__ */ new Map();
+		this._dependencies.set(Type, instanceKey ?? BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY);
+		return () => globalRegistry.ensure(Type, instanceKey);
+	}
 	constructor(initialState) {
 		this.listeners = /* @__PURE__ */ new Set();
 		this._disposed = false;
@@ -74,6 +644,7 @@ var StateContainer = class StateContainer {
 		this.debug = false;
 		this.instanceId = generateSimpleId(this.constructor.name, "main");
 		this.createdAt = Date.now();
+		this._dependencies = null;
 		this.lastUpdateTimestamp = Date.now();
 		this.onSystemEvent = (event, handler) => {
 			let handlers = this.systemEventHandlers.get(event);
@@ -98,7 +669,7 @@ var StateContainer = class StateContainer {
 		this.name = this.config.name || this.constructor.name;
 		this.debug = this.config.debug ?? false;
 		this.instanceId = generateSimpleId(this.constructor.name, this.config.instanceId);
-		require_StateContainerRegistry.globalRegistry.emit("created", this);
+		globalRegistry.emit("created", this);
 	}
 	/** Current state value */
 	get state() {
@@ -129,7 +700,7 @@ var StateContainer = class StateContainer {
 		this.emitSystemEvent("dispose", void 0);
 		this.listeners.clear();
 		this.systemEventHandlers.clear();
-		require_StateContainerRegistry.globalRegistry.emit("disposed", this);
+		globalRegistry.emit("disposed", this);
 		if (this.debug) console.log(`[${this.name}] Disposed successfully`);
 	}
 	/**
@@ -152,7 +723,7 @@ var StateContainer = class StateContainer {
 			console.error(`[${this.name}] Error in listener:`, error);
 		}
 		const stackTrace = this.captureStackTrace();
-		require_StateContainerRegistry.globalRegistry.emit("stateChanged", this, previousState, newState, stackTrace);
+		globalRegistry.emit("stateChanged", this, previousState, newState, stackTrace);
 		this.lastUpdateTimestamp = Date.now();
 	}
 	captureStackTrace() {
@@ -226,8 +797,14 @@ var Cubit = class extends StateContainer {
 		super(initialState);
 		this.patch = ((partial) => {
 			if (typeof this.state !== "object" || this.state === null) throw new Error("patch() is only available for object state types");
-			this.update((current) => ({
-				...current,
+			const current = this.state;
+			let hasChanges = false;
+			for (const key in partial) if (!Object.is(current[key], partial[key])) {
+				hasChanges = true;
+				break;
+			}
+			if (hasChanges) this.update((c) => ({
+				...c,
 				...partial
 			}));
 		});
@@ -251,7 +828,7 @@ var Cubit = class extends StateContainer {
 //#endregion
 //#region src/registry/acquire.ts
 function acquire(BlocClass, instanceKey) {
-	return require_StateContainerRegistry.globalRegistry.acquire(BlocClass, instanceKey, {
+	return globalRegistry.acquire(BlocClass, instanceKey, {
 		canCreate: true,
 		countRef: true
 	});
@@ -260,16 +837,63 @@ function acquire(BlocClass, instanceKey) {
 //#endregion
 //#region src/registry/borrow.ts
 function borrow(BlocClass, instanceKey) {
-	return require_StateContainerRegistry.globalRegistry.borrow(BlocClass, instanceKey);
+	return globalRegistry.borrow(BlocClass, instanceKey);
 }
 function borrowSafe(BlocClass, instanceKey) {
-	return require_StateContainerRegistry.globalRegistry.borrowSafe(BlocClass, instanceKey);
+	return globalRegistry.borrowSafe(BlocClass, instanceKey);
+}
+
+//#endregion
+//#region src/registry/ensure.ts
+function ensure(BlocClass, instanceKey) {
+	return globalRegistry.ensure(BlocClass, instanceKey);
 }
 
 //#endregion
 //#region src/registry/release.ts
 function release(BlocClass, instanceKey, forceDispose = false) {
-	require_StateContainerRegistry.globalRegistry.release(BlocClass, instanceKey, forceDispose);
+	globalRegistry.release(BlocClass, instanceKey, forceDispose);
+}
+
+//#endregion
+//#region src/registry/queries.ts
+function hasInstance(BlocClass, instanceKey) {
+	return globalRegistry.hasInstance(BlocClass, instanceKey);
+}
+function getRefCount(BlocClass, instanceKey) {
+	return globalRegistry.getRefCount(BlocClass, instanceKey);
+}
+function getAll(BlocClass) {
+	return globalRegistry.getAll(BlocClass);
+}
+function forEach(BlocClass, callback) {
+	globalRegistry.forEach(BlocClass, callback);
+}
+
+//#endregion
+//#region src/registry/management.ts
+function clear(BlocClass) {
+	globalRegistry.clear(BlocClass);
+}
+function clearAll() {
+	globalRegistry.clearAll();
+}
+function register(BlocClass, isolated = false) {
+	globalRegistry.register(BlocClass, isolated);
+}
+
+//#endregion
+//#region src/registry/config.ts
+let _registry = globalRegistry;
+function getRegistry() {
+	return _registry;
+}
+function setRegistry(registry) {
+	_registry.clearAll();
+	_registry = registry;
+}
+function getStats() {
+	return _registry.getStats();
 }
 
 //#endregion
@@ -298,49 +922,887 @@ function release(BlocClass, instanceKey, forceDispose = false) {
 */
 function blac(options) {
 	return function(target, _context) {
-		if ("isolated" in options && options.isolated) target[require_tracking_proxy.BLAC_STATIC_PROPS.ISOLATED] = true;
-		if ("keepAlive" in options && options.keepAlive) target[require_tracking_proxy.BLAC_STATIC_PROPS.KEEP_ALIVE] = true;
-		if ("excludeFromDevTools" in options && options.excludeFromDevTools) target[require_tracking_proxy.BLAC_STATIC_PROPS.EXCLUDE_FROM_DEVTOOLS] = true;
+		if ("isolated" in options && options.isolated) target[BLAC_STATIC_PROPS.ISOLATED] = true;
+		if ("keepAlive" in options && options.keepAlive) target[BLAC_STATIC_PROPS.KEEP_ALIVE] = true;
+		if ("excludeFromDevTools" in options && options.excludeFromDevTools) target[BLAC_STATIC_PROPS.EXCLUDE_FROM_DEVTOOLS] = true;
 		return target;
 	};
 }
 
+//#endregion
+//#region src/tracking/path-utils.ts
+/**
+* Path utilities for dependency tracking
+*
+* Provides utilities for parsing property paths and extracting values
+* from nested objects using path strings.
+*
+* @internal
+*/
+/**
+* Parse a property path string into an array of segments
+*
+* @internal
+*
+* Handles both dot notation (a.b.c) and bracket notation (a[0].b)
+*
+* @example
+* ```ts
+* parsePath('user.name') // ['user', 'name']
+* parsePath('items[0].name') // ['items', '0', 'name']
+* parsePath('data.users[2].address.city') // ['data', 'users', '2', 'address', 'city']
+* ```
+*/
+function parsePath(path) {
+	const segments = [];
+	let current = "";
+	let i = 0;
+	while (i < path.length) {
+		const char = path[i];
+		if (char === ".") {
+			if (current) segments.push(current);
+			current = "";
+		} else if (char === "[") {
+			if (current) segments.push(current);
+			current = "";
+			i++;
+			while (i < path.length && path[i] !== "]") current += path[i++];
+			if (current) segments.push(current);
+			current = "";
+		} else current += char;
+		i++;
+	}
+	if (current) segments.push(current);
+	return segments;
+}
+/**
+* Get a value from an object using a path of segments
+*
+* @example
+* ```ts
+* const obj = { user: { name: 'Alice', age: 30 } }
+* getValueAtPath(obj, ['user', 'name']) // 'Alice'
+* getValueAtPath(obj, ['user', 'age']) // 30
+* getValueAtPath(obj, ['user', 'missing']) // undefined
+* ```
+*
+* @internal
+*/
+function getValueAtPath(obj, segments) {
+	if (obj == null) return void 0;
+	let current = obj;
+	for (let i = 0; i < segments.length; i++) {
+		current = current[segments[i]];
+		if (current == null) return void 0;
+	}
+	return current;
+}
+/**
+* Shallow equality comparison for arrays
+*
+* Compares two arrays element-by-element using Object.is
+*
+* @example
+* ```ts
+* shallowEqual([1, 2, 3], [1, 2, 3]) // true
+* shallowEqual([1, 2, 3], [1, 2, 4]) // false
+* shallowEqual([1, 2], [1, 2, 3]) // false
+* ```
+*
+* @internal
+*/
+function shallowEqual(arr1, arr2) {
+	if (arr1.length !== arr2.length) return false;
+	for (let i = 0; i < arr1.length; i++) if (!Object.is(arr1[i], arr2[i])) return false;
+	return true;
+}
+
+//#endregion
+//#region src/tracking/tracking-proxy.ts
+/**
+* Consolidated Tracking System
+*
+* This module provides all dependency and getter tracking functionality:
+* - Proxy creation for automatic property access tracking
+* - Dependency path tracking and change detection
+* - Getter execution tracking for computed properties
+* - Combined tracking proxy for watch/waitUntil use cases
+*/
+/**
+* Check if a value can be proxied
+* Returns true for plain objects and arrays only.
+* @internal
+*/
+function isProxyable(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === Array.prototype;
+}
+/**
+* Create a new proxy tracker state
+* @internal
+*/
+function createProxyState() {
+	return {
+		trackedPaths: /* @__PURE__ */ new Set(),
+		isTracking: false,
+		proxyCache: /* @__PURE__ */ new WeakMap(),
+		boundFunctionsCache: null,
+		lastProxiedState: null,
+		lastProxy: null,
+		maxDepth: 10
+	};
+}
+/**
+* Start tracking property accesses
+* @internal
+*/
+function startProxy(state) {
+	state.isTracking = true;
+	state.trackedPaths.clear();
+}
+/**
+* Stop tracking and return the tracked paths
+* @internal
+*/
+function stopProxy(state) {
+	state.isTracking = false;
+	return new Set(state.trackedPaths);
+}
+/**
+* Create a proxy for an array with property access tracking
+* @internal
+*/
+function createArrayProxy(state, target, path, depth = 0) {
+	const proxy = new Proxy(target, { get: (arr, prop) => {
+		if (typeof prop === "symbol") return Reflect.get(arr, prop);
+		const value = Reflect.get(arr, prop);
+		if (typeof value === "function") {
+			if (!state.boundFunctionsCache) state.boundFunctionsCache = /* @__PURE__ */ new WeakMap();
+			const cached = state.boundFunctionsCache.get(value);
+			if (cached) return cached;
+			const bound = value.bind(arr);
+			state.boundFunctionsCache.set(value, bound);
+			return bound;
+		}
+		if (prop === "length") {
+			if (state.isTracking) {
+				const fullPath = path ? `${path}.length` : "length";
+				state.trackedPaths.add(fullPath);
+			}
+			return value;
+		}
+		let fullPath;
+		if (typeof prop === "string") {
+			const index = Number(prop);
+			if (!isNaN(index) && index >= 0) fullPath = path ? `${path}[${index}]` : `[${index}]`;
+			else fullPath = path ? `${path}.${prop}` : prop;
+		} else return value;
+		if (isProxyable(value)) return createInternal(state, value, fullPath, depth + 1);
+		if (state.isTracking) state.trackedPaths.add(fullPath);
+		return value;
+	} });
+	state.proxyCache.set(target, proxy);
+	return proxy;
+}
+/**
+* Create a proxy for an object with property access tracking
+* @internal
+*/
+function createInternal(state, target, path = "", depth = 0) {
+	if (!state.isTracking || !isProxyable(target)) return target;
+	if (depth >= state.maxDepth) return target;
+	if (state.proxyCache.has(target)) return state.proxyCache.get(target);
+	if (Array.isArray(target)) return createArrayProxy(state, target, path, depth);
+	const proxy = new Proxy(target, {
+		get: (obj, prop) => {
+			if (typeof prop === "symbol") return Reflect.get(obj, prop);
+			const value = Reflect.get(obj, prop);
+			if (typeof value === "function") {
+				if (!state.boundFunctionsCache) state.boundFunctionsCache = /* @__PURE__ */ new WeakMap();
+				const cached = state.boundFunctionsCache.get(value);
+				if (cached) return cached;
+				const bound = value.bind(obj);
+				state.boundFunctionsCache.set(value, bound);
+				return bound;
+			}
+			const fullPath = path ? `${path}.${String(prop)}` : String(prop);
+			if (typeof prop === "string" && state.isTracking) {
+				if (!prop.startsWith("_") && !prop.startsWith("$$")) state.trackedPaths.add(fullPath);
+			}
+			if (isProxyable(value)) return createInternal(state, value, fullPath, depth + 1);
+			return value;
+		},
+		has: (obj, prop) => {
+			if (typeof prop === "string" && state.isTracking) {
+				const fullPath = path ? `${path}.${prop}` : prop;
+				state.trackedPaths.add(fullPath);
+			}
+			return Reflect.has(obj, prop);
+		},
+		ownKeys: (obj) => {
+			if (state.isTracking && path) state.trackedPaths.add(path);
+			return Reflect.ownKeys(obj);
+		}
+	});
+	state.proxyCache.set(target, proxy);
+	return proxy;
+}
+/**
+* Create a proxy for a target with caching
+* @internal
+*/
+function createForTarget(state, target) {
+	if (state.lastProxiedState === target && state.lastProxy) return state.lastProxy;
+	state.proxyCache = /* @__PURE__ */ new WeakMap();
+	state.boundFunctionsCache = null;
+	const proxy = createInternal(state, target, "", 0);
+	state.lastProxiedState = target;
+	state.lastProxy = proxy;
+	return proxy;
+}
+function isChildPath(child, parent) {
+	if (child === parent) return false;
+	return child.startsWith(parent + ".") || child.startsWith(parent + "[");
+}
+function getArrayParentPath(path) {
+	if (path.endsWith(".length")) return path.slice(0, -7);
+	const arrayIndexMatch = path.match(/^(.+?)\[\d+\]/);
+	if (arrayIndexMatch) return arrayIndexMatch[1];
+	return null;
+}
+/**
+* @internal
+*/
+function optimizeTrackedPaths(paths) {
+	if (paths.size === 0) return /* @__PURE__ */ new Set();
+	if (paths.size === 1) return new Set(paths);
+	const sortedPaths = Array.from(paths).sort((a, b) => b.length - a.length);
+	const optimized = /* @__PURE__ */ new Set();
+	for (const path of sortedPaths) {
+		let hasMoreSpecificChild = false;
+		for (const optimizedPath of optimized) if (isChildPath(optimizedPath, path)) {
+			hasMoreSpecificChild = true;
+			break;
+		}
+		if (!hasMoreSpecificChild) optimized.add(path);
+	}
+	const arrayParents = /* @__PURE__ */ new Set();
+	for (const path of optimized) {
+		const arrayParent = getArrayParentPath(path);
+		if (arrayParent) arrayParents.add(arrayParent);
+	}
+	for (const arrayParent of arrayParents) optimized.add(arrayParent);
+	return optimized;
+}
+/**
+* @internal
+*/
+function createDependencyState() {
+	return {
+		proxyState: createProxyState(),
+		previousRenderPaths: /* @__PURE__ */ new Set(),
+		currentRenderPaths: /* @__PURE__ */ new Set(),
+		pathCache: /* @__PURE__ */ new Map(),
+		lastCheckedState: null,
+		lastCheckedValues: /* @__PURE__ */ new Map()
+	};
+}
+/**
+* @internal
+*/
+function startDependency(tracker) {
+	startProxy(tracker.proxyState);
+}
+/**
+* @internal
+*/
+function createDependencyProxy(tracker, state) {
+	return createForTarget(tracker.proxyState, state);
+}
+/**
+* @internal
+*/
+function capturePaths(tracker, state) {
+	tracker.previousRenderPaths = tracker.currentRenderPaths;
+	tracker.currentRenderPaths = optimizeTrackedPaths(stopProxy(tracker.proxyState));
+	if (tracker.previousRenderPaths.size === 0 && tracker.currentRenderPaths.size === 0) return;
+	const trackedPathsUnion = new Set(tracker.previousRenderPaths);
+	for (const path of tracker.currentRenderPaths) trackedPathsUnion.add(path);
+	const canReuseCache = tracker.lastCheckedState === state;
+	for (const path of trackedPathsUnion) if (!tracker.pathCache.has(path)) {
+		const segments = parsePath(path);
+		const value = canReuseCache && tracker.lastCheckedValues.has(path) ? tracker.lastCheckedValues.get(path) : getValueAtPath(state, segments);
+		tracker.pathCache.set(path, {
+			segments,
+			value
+		});
+	} else {
+		const info = tracker.pathCache.get(path);
+		info.value = canReuseCache && tracker.lastCheckedValues.has(path) ? tracker.lastCheckedValues.get(path) : getValueAtPath(state, info.segments);
+	}
+	tracker.lastCheckedValues.clear();
+}
+/**
+* @internal
+*/
+function hasDependencyChanges(tracker, state) {
+	if (tracker.pathCache.size === 0) return true;
+	tracker.lastCheckedValues.clear();
+	for (const [path, info] of tracker.pathCache.entries()) {
+		const currentValue = getValueAtPath(state, info.segments);
+		tracker.lastCheckedValues.set(path, currentValue);
+		if (!Object.is(currentValue, info.value)) {
+			tracker.lastCheckedState = state;
+			return true;
+		}
+	}
+	tracker.lastCheckedState = state;
+	return false;
+}
+/**
+* @internal
+*/
+function hasTrackedData(tracker) {
+	return tracker.proxyState.trackedPaths.size > 0 || tracker.pathCache.size > 0 || tracker.previousRenderPaths.size > 0;
+}
+const descriptorCache = /* @__PURE__ */ new WeakMap();
+const blocProxyCache = /* @__PURE__ */ new WeakMap();
+const activeTrackerMap = /* @__PURE__ */ new WeakMap();
+const MAX_GETTER_DEPTH = BLAC_DEFAULTS.MAX_GETTER_DEPTH;
+/**
+* @internal
+*/
+function getDescriptor(obj, prop) {
+	const constructor = obj.constructor;
+	let constructorCache = descriptorCache.get(constructor);
+	if (constructorCache?.has(prop)) return constructorCache.get(prop);
+	let current = obj;
+	let descriptor;
+	while (current && current !== Object.prototype) {
+		descriptor = Object.getOwnPropertyDescriptor(current, prop);
+		if (descriptor) break;
+		current = Object.getPrototypeOf(current);
+	}
+	if (!constructorCache) {
+		constructorCache = /* @__PURE__ */ new Map();
+		descriptorCache.set(constructor, constructorCache);
+	}
+	constructorCache.set(prop, descriptor);
+	return descriptor;
+}
+/**
+* @internal
+*/
+function isGetter(obj, prop) {
+	return getDescriptor(obj, prop)?.get !== void 0;
+}
+/**
+* @internal
+*/
+function createGetterState() {
+	return {
+		trackedValues: /* @__PURE__ */ new Map(),
+		currentlyAccessing: /* @__PURE__ */ new Set(),
+		trackedGetters: /* @__PURE__ */ new Set(),
+		isTracking: false,
+		renderCache: /* @__PURE__ */ new Map(),
+		cacheValid: false,
+		depth: 0,
+		visitedBlocs: /* @__PURE__ */ new Set()
+	};
+}
+/**
+* @internal
+*/
+function setActiveTracker(bloc, tracker) {
+	activeTrackerMap.set(bloc, tracker);
+}
+/**
+* @internal
+*/
+function clearActiveTracker(bloc) {
+	activeTrackerMap.delete(bloc);
+}
+/**
+* @internal
+*/
+function commitTrackedGetters(tracker) {
+	if (tracker.currentlyAccessing.size > 0) tracker.trackedGetters = new Set(tracker.currentlyAccessing);
+	tracker.currentlyAccessing.clear();
+}
+/**
+* Execute a tracked getter with depth/circular dependency checks and context management.
+* @internal
+*/
+function executeTrackedGetter(target, prop, tracker) {
+	tracker.currentlyAccessing.add(prop);
+	if (tracker.cacheValid && tracker.renderCache.has(prop)) {
+		const cachedValue = tracker.renderCache.get(prop);
+		tracker.trackedValues.set(prop, cachedValue);
+		return cachedValue;
+	}
+	if (tracker.depth >= MAX_GETTER_DEPTH) {
+		console.warn(`${BLAC_ERROR_PREFIX} Maximum getter depth (${MAX_GETTER_DEPTH}) exceeded. Possible circular dependency in getter "${String(prop)}" on ${target.constructor.name}.`);
+		return;
+	}
+	if (tracker.visitedBlocs.has(target)) {
+		console.warn(`${BLAC_ERROR_PREFIX} Circular dependency detected: getter "${String(prop)}" on ${target.constructor.name}.`);
+		return;
+	}
+	const prevDepth = tracker.depth;
+	const prevVisited = new Set(tracker.visitedBlocs);
+	tracker.depth++;
+	tracker.visitedBlocs.add(target);
+	try {
+		const value = getDescriptor(target, prop).get.call(target);
+		tracker.trackedValues.set(prop, value);
+		return value;
+	} catch (error) {
+		tracker.currentlyAccessing.delete(prop);
+		throw error;
+	} finally {
+		tracker.depth = prevDepth;
+		tracker.visitedBlocs = prevVisited;
+	}
+}
+/**
+* @internal
+*/
+function createBlocProxy(bloc) {
+	const cached = blocProxyCache.get(bloc);
+	if (cached) return cached;
+	const proxy = new Proxy(bloc, { get(target, prop, receiver) {
+		const tracker = activeTrackerMap.get(target);
+		if (tracker?.isTracking && isGetter(target, prop)) return executeTrackedGetter(target, prop, tracker);
+		return Reflect.get(target, prop, receiver);
+	} });
+	blocProxyCache.set(bloc, proxy);
+	return proxy;
+}
+/**
+* @internal
+*/
+function hasGetterChanges(bloc, tracker) {
+	if (!tracker || tracker.trackedGetters.size === 0) return false;
+	tracker.renderCache.clear();
+	let hasAnyChange = false;
+	for (const prop of tracker.trackedGetters) try {
+		const descriptor = getDescriptor(bloc, prop);
+		if (!descriptor?.get) continue;
+		const newValue = descriptor.get.call(bloc);
+		const oldValue = tracker.trackedValues.get(prop);
+		tracker.renderCache.set(prop, newValue);
+		tracker.trackedValues.set(prop, newValue);
+		if (!Object.is(newValue, oldValue)) hasAnyChange = true;
+	} catch (error) {
+		console.warn(`${BLAC_ERROR_PREFIX} Getter "${String(prop)}" threw error during change detection. Stopping tracking for this getter.`, error);
+		tracker.trackedGetters.delete(prop);
+		tracker.trackedValues.delete(prop);
+		tracker.cacheValid = false;
+		return true;
+	}
+	tracker.cacheValid = true;
+	return hasAnyChange;
+}
+/**
+* @internal
+*/
+function invalidateRenderCache(tracker) {
+	tracker.cacheValid = false;
+}
+/**
+* Create a new tracking proxy state.
+*/
+function createState() {
+	return {
+		dependencyState: createDependencyState(),
+		getterState: createGetterState(),
+		dependencies: /* @__PURE__ */ new Set(),
+		isTracking: false
+	};
+}
+/**
+* Start tracking on a tracking proxy.
+*/
+function startTracking(tracker) {
+	tracker.isTracking = true;
+	tracker.dependencies.clear();
+	tracker.getterState.isTracking = true;
+	startDependency(tracker.dependencyState);
+}
+/**
+* Stop tracking and collect all dependencies.
+*/
+function stopTracking(tracker, bloc) {
+	tracker.isTracking = false;
+	tracker.getterState.isTracking = false;
+	capturePaths(tracker.dependencyState, bloc.state);
+	commitTrackedGetters(tracker.getterState);
+	return new Set(tracker.dependencies);
+}
+/**
+* Check if tracked state or getters have changed.
+*/
+function hasChanges(tracker, bloc) {
+	invalidateRenderCache(tracker.getterState);
+	const stateChanged = hasDependencyChanges(tracker.dependencyState, bloc.state);
+	const getterChanged = hasGetterChanges(bloc, tracker.getterState);
+	return stateChanged || getterChanged;
+}
+/**
+* Create a tracking proxy for a bloc instance.
+* Tracks both state property access and getter access.
+*/
+function createTrackingProxy(bloc, tracker) {
+	tracker.dependencies.add(bloc);
+	const stateProxyCache = /* @__PURE__ */ new WeakMap();
+	return new Proxy(bloc, { get(target, prop, receiver) {
+		if (prop === "state") {
+			if (!tracker.isTracking) return target.state;
+			const rawState = target.state;
+			if (rawState === null || typeof rawState !== "object") return rawState;
+			if (stateProxyCache.has(rawState)) return stateProxyCache.get(rawState);
+			const stateProxy = createDependencyProxy(tracker.dependencyState, rawState);
+			stateProxyCache.set(rawState, stateProxy);
+			return stateProxy;
+		}
+		if (typeof prop === "symbol") return Reflect.get(target, prop, receiver);
+		const value = Reflect.get(target, prop, receiver);
+		if (typeof value === "function") return value.bind(target);
+		if (tracker.isTracking && isGetter(target, prop)) return executeTrackedGetter(target, prop, tracker.getterState);
+		return value;
+	} });
+}
+
+//#endregion
+//#region src/tracking/dependency-manager.ts
+/**
+* Manages subscriptions to state container dependencies.
+* Provides efficient sync mechanism to add/remove subscriptions
+* as dependencies change between callback invocations.
+*/
+var DependencyManager = class {
+	constructor() {
+		this.subscriptions = /* @__PURE__ */ new Map();
+		this.currentDeps = /* @__PURE__ */ new Set();
+	}
+	/**
+	* Sync subscriptions with a new set of dependencies.
+	* Adds subscriptions for new deps, removes subscriptions for stale deps.
+	*
+	* @param newDeps - The new set of dependencies to subscribe to
+	* @param onChange - Callback to invoke when any dependency changes
+	* @param exclude - Optional instance to exclude from subscriptions (e.g., primary bloc)
+	* @returns true if the dependency set changed, false if unchanged
+	*/
+	sync(newDeps, onChange, exclude) {
+		const filteredNewDeps = /* @__PURE__ */ new Set();
+		for (const dep of newDeps) if (dep !== exclude && !dep.isDisposed) filteredNewDeps.add(dep);
+		if (this.areSetsEqual(this.currentDeps, filteredNewDeps)) return false;
+		for (const dep of this.currentDeps) if (!filteredNewDeps.has(dep)) {
+			const unsub = this.subscriptions.get(dep);
+			if (unsub) {
+				unsub();
+				this.subscriptions.delete(dep);
+			}
+		}
+		for (const dep of filteredNewDeps) if (!this.currentDeps.has(dep) && !this.subscriptions.has(dep)) {
+			const unsub = dep.subscribe(onChange);
+			this.subscriptions.set(dep, unsub);
+		}
+		this.currentDeps = filteredNewDeps;
+		return true;
+	}
+	/**
+	* Add a single dependency subscription.
+	*/
+	add(dep, onChange) {
+		if (this.subscriptions.has(dep) || dep.isDisposed) return;
+		const unsub = dep.subscribe(onChange);
+		this.subscriptions.set(dep, unsub);
+		this.currentDeps.add(dep);
+	}
+	/**
+	* Check if a dependency is currently subscribed.
+	*/
+	has(dep) {
+		return this.currentDeps.has(dep);
+	}
+	/**
+	* Get the current set of dependencies.
+	*/
+	getDependencies() {
+		return new Set(this.currentDeps);
+	}
+	/**
+	* Clean up all active subscriptions.
+	*/
+	cleanup() {
+		for (const unsub of this.subscriptions.values()) unsub();
+		this.subscriptions.clear();
+		this.currentDeps.clear();
+	}
+	areSetsEqual(a, b) {
+		if (a.size !== b.size) return false;
+		for (const item of a) if (!b.has(item)) return false;
+		return true;
+	}
+};
+
+//#endregion
+//#region src/tracking/resolve-dependencies.ts
+/**
+* Resolve all transitive dependencies of a bloc via BFS over `dependencies` maps.
+* Uses cycle detection to avoid infinite loops.
+* @internal
+*/
+function resolveDependencies(bloc) {
+	const result = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [bloc];
+	while (queue.length > 0) {
+		const current = queue.shift();
+		for (const [Type, key] of current.dependencies) {
+			if (visited.has(Type)) continue;
+			visited.add(Type);
+			const dep = globalRegistry.ensure(Type, key);
+			result.add(dep);
+			if (dep.dependencies.size > 0) queue.push(dep);
+		}
+	}
+	result.delete(bloc);
+	return result;
+}
+
+//#endregion
+//#region src/watch/watch.ts
+const STOP = Symbol("watch.STOP");
+const BLOC_REF_MARKER = Symbol("BlocRef");
+/**
+* Create a reference to a specific bloc instance.
+*
+* @example
+* ```ts
+* watch(instance(UserBloc, 'user-123'), (userBloc) => {
+*   console.log(userBloc.state.name);
+* });
+* ```
+*/
+function instance(BlocClass, instanceId) {
+	return {
+		[BLOC_REF_MARKER]: true,
+		blocClass: BlocClass,
+		instanceId
+	};
+}
+function isBlocRef(input) {
+	return typeof input === "object" && input !== null && BLOC_REF_MARKER in input;
+}
+function resolveBloc(input) {
+	if (isBlocRef(input)) return ensure(input.blocClass, input.instanceId);
+	return ensure(input, BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY);
+}
+function isArray(input) {
+	return Array.isArray(input);
+}
+function watchImpl(blocsOrBloc, callback) {
+	const isSingle = !isArray(blocsOrBloc);
+	const instances = (isSingle ? [blocsOrBloc] : blocsOrBloc).map(resolveBloc);
+	const tracker = createState();
+	const proxiedInstances = instances.map((inst) => createTrackingProxy(inst, tracker));
+	const externalDepsManager = new DependencyManager();
+	let disposed = false;
+	const primarySubscriptions = [];
+	const cleanup = () => {
+		if (disposed) return;
+		disposed = true;
+		primarySubscriptions.forEach((unsub) => unsub());
+		externalDepsManager.cleanup();
+	};
+	const runCallback = () => {
+		if (disposed) return;
+		startTracking(tracker);
+		let result;
+		try {
+			result = callback(isSingle ? proxiedInstances[0] : proxiedInstances);
+		} finally {
+			const externalDeps = /* @__PURE__ */ new Set();
+			for (const inst of instances) {
+				const deps = stopTracking(tracker, inst);
+				for (const dep of deps) externalDeps.add(dep);
+				for (const dep of resolveDependencies(inst)) externalDeps.add(dep);
+			}
+			for (const inst of instances) externalDeps.delete(inst);
+			externalDepsManager.sync(externalDeps, runCallback);
+		}
+		if (result === STOP) cleanup();
+	};
+	const onChange = () => {
+		if (disposed) return;
+		runCallback();
+	};
+	for (const inst of instances) primarySubscriptions.push(inst.subscribe(onChange));
+	runCallback();
+	return cleanup;
+}
+const watch = Object.assign(watchImpl, { STOP });
+
+//#endregion
+//#region src/tracking/tracked.ts
+/**
+* Run a callback while tracking all bloc dependencies accessed.
+* Returns both the result and the set of discovered dependencies.
+*
+* @example
+* ```ts
+* const { result, dependencies } = tracked(() => {
+*   const user = ensure(UserBloc);
+*   return user.fullName; // getter that may access other blocs
+* });
+* // dependencies contains UserBloc + any blocs accessed in fullName getter
+* ```
+*/
+function tracked(callback, options) {
+	const tracker = createState();
+	startTracking(tracker);
+	let result;
+	try {
+		result = callback();
+	} finally {
+		stopTracking(tracker, { state: null });
+	}
+	const dependencies = new Set(tracker.dependencies);
+	if (options?.exclude) dependencies.delete(options.exclude);
+	return {
+		result,
+		dependencies
+	};
+}
+/**
+* Context for running tracked callbacks with bloc proxies.
+* Provides methods to create proxies and check for changes.
+*/
+var TrackedContext = class {
+	constructor() {
+		this.proxiedBlocs = /* @__PURE__ */ new WeakMap();
+		this.primaryBlocs = /* @__PURE__ */ new Set();
+		this.tracker = createState();
+	}
+	/**
+	* Get a tracking proxy for a bloc instance.
+	* The proxy will track state and getter accesses.
+	*/
+	proxy(bloc) {
+		const cached = this.proxiedBlocs.get(bloc);
+		if (cached) return cached;
+		const proxied = createTrackingProxy(bloc, this.tracker);
+		this.proxiedBlocs.set(bloc, proxied);
+		this.primaryBlocs.add(bloc);
+		return proxied;
+	}
+	/**
+	* Start tracking for a new callback execution.
+	*/
+	start() {
+		startTracking(this.tracker);
+	}
+	/**
+	* Stop tracking and get discovered dependencies.
+	* Excludes primary blocs (those explicitly proxied via proxy()).
+	*/
+	stop() {
+		const allDeps = /* @__PURE__ */ new Set();
+		for (const bloc of this.primaryBlocs) {
+			const deps = stopTracking(this.tracker, bloc);
+			for (const dep of deps) if (!this.primaryBlocs.has(dep)) allDeps.add(dep);
+		}
+		return allDeps;
+	}
+	/**
+	* Check if any tracked state or getters have changed.
+	*/
+	changed() {
+		for (const bloc of this.primaryBlocs) if (hasChanges(this.tracker, bloc)) return true;
+		return false;
+	}
+	/**
+	* Get all primary blocs (those explicitly proxied).
+	*/
+	getPrimaryBlocs() {
+		return new Set(this.primaryBlocs);
+	}
+	/**
+	* Reset the context for reuse.
+	*/
+	reset() {
+		this.tracker = createState();
+		this.proxiedBlocs = /* @__PURE__ */ new WeakMap();
+		this.primaryBlocs.clear();
+	}
+};
+/**
+* Create a new tracked context for manual control over tracking.
+*/
+function createTrackedContext() {
+	return new TrackedContext();
+}
+
+//#endregion
+//#region src/types/branded.ts
+/**
+* Create a branded InstanceId from a string
+* @param id - The string ID to brand
+* @returns Branded InstanceId
+*/
+function instanceId(id) {
+	return id;
+}
+
 //#endregion
 exports.Cubit = Cubit;
-exports.DependencyManager = require_dependency_manager.DependencyManager;
-exports.PluginManager = require_StateContainerRegistry.PluginManager;
+exports.DependencyManager = DependencyManager;
+exports.PluginManager = PluginManager;
 exports.StateContainer = StateContainer;
+exports.TrackedContext = TrackedContext;
 exports.acquire = acquire;
 exports.blac = blac;
 exports.borrow = borrow;
 exports.borrowSafe = borrowSafe;
-exports.capturePaths = require_tracking_proxy.capturePaths;
-exports.clear = require_management.clear;
-exports.clearActiveTracker = require_tracking_proxy.clearActiveTracker;
-exports.clearAll = require_management.clearAll;
-exports.clearExternalDependencies = require_tracking_proxy.clearExternalDependencies;
-exports.commitTrackedGetters = require_tracking_proxy.commitTrackedGetters;
-exports.createBlocProxy = require_tracking_proxy.createBlocProxy;
-exports.createDependencyProxy = require_tracking_proxy.createDependencyProxy;
-exports.createDependencyState = require_tracking_proxy.createDependencyState;
-exports.createGetterState = require_tracking_proxy.createGetterState;
-exports.ensure = require_watch.ensure;
-exports.forEach = require_management.forEach;
+exports.capturePaths = capturePaths;
+exports.clear = clear;
+exports.clearActiveTracker = clearActiveTracker;
+exports.clearAll = clearAll;
+exports.commitTrackedGetters = commitTrackedGetters;
+exports.createBlocProxy = createBlocProxy;
+exports.createDependencyProxy = createDependencyProxy;
+exports.createDependencyState = createDependencyState;
+exports.createGetterState = createGetterState;
+exports.createTrackedContext = createTrackedContext;
+exports.ensure = ensure;
+exports.forEach = forEach;
 exports.generateIsolatedKey = generateIsolatedKey;
-exports.getAll = require_management.getAll;
-exports.getPluginManager = require_StateContainerRegistry.getPluginManager;
-exports.getRefCount = require_management.getRefCount;
-exports.globalRegistry = require_StateContainerRegistry.globalRegistry;
-exports.hasDependencyChanges = require_tracking_proxy.hasDependencyChanges;
-exports.hasGetterChanges = require_tracking_proxy.hasGetterChanges;
-exports.hasInstance = require_management.hasInstance;
-exports.hasTrackedData = require_tracking_proxy.hasTrackedData;
-exports.instance = require_watch.instance;
-exports.invalidateRenderCache = require_tracking_proxy.invalidateRenderCache;
-exports.isIsolatedClass = require_StateContainerRegistry.isIsolatedClass;
+exports.getAll = getAll;
+exports.getPluginManager = getPluginManager;
+exports.getRefCount = getRefCount;
+exports.getRegistry = getRegistry;
+exports.getStats = getStats;
+exports.globalRegistry = globalRegistry;
+exports.hasDependencyChanges = hasDependencyChanges;
+exports.hasGetterChanges = hasGetterChanges;
+exports.hasInstance = hasInstance;
+exports.hasTrackedData = hasTrackedData;
+exports.instance = instance;
+exports.instanceId = instanceId;
+exports.invalidateRenderCache = invalidateRenderCache;
+exports.isIsolatedClass = isIsolatedClass;
+exports.register = register;
 exports.release = release;
-exports.setActiveTracker = require_tracking_proxy.setActiveTracker;
-exports.shallowEqual = require_tracking_proxy.shallowEqual;
-exports.startDependency = require_tracking_proxy.startDependency;
-exports.watch = require_watch.watch;
+exports.resolveDependencies = resolveDependencies;
+exports.setActiveTracker = setActiveTracker;
+exports.setRegistry = setRegistry;
+exports.shallowEqual = shallowEqual;
+exports.startDependency = startDependency;
+exports.tracked = tracked;
+exports.watch = watch;
 //# sourceMappingURL=index.cjs.map