@blac/core 2.0.13 → 2.0.15

package/dist/StateContainerRegistry-CTOXUf75.cjs

@@ -1,687 +1,742 @@
 //#region src/constants.ts
 /**
-* Default configuration constants for BlaC
-*
-* Centralized location for all magic numbers and default values.
-*/
+ * Default configuration constants for BlaC
+ *
+ * Centralized location for all magic numbers and default values.
+ */
 /**
-* Default configuration constants for BlaC
-*/
+ * 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
+  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
-*/
+ * Static property names for StateContainer classes
+ * Used for feature flags and configuration on bloc classes
+ */
 const BLAC_STATIC_PROPS = {
-	KEEP_ALIVE: "keepAlive",
-	EXCLUDE_FROM_DEVTOOLS: "__excludeFromDevTools"
+  KEEP_ALIVE: 'keepAlive',
+  EXCLUDE_FROM_DEVTOOLS: '__excludeFromDevTools',
 };
 /**
-* Standard error message prefix
-*/
-const BLAC_ERROR_PREFIX = "[BlaC]";
+ * 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' });
-* ```
-*/
+ * 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) => {
-			this.notifyPlugins("onStateChanged", instance, previousState, currentState);
-		});
-		this.registry.on("disposed", (instance) => {
-			this.notifyPlugins("onInstanceDisposed", instance);
-		});
-		this.registry.on("refAcquired", (instance, refId) => {
-			this.notifyPlugins("onRefAcquired", instance, refId);
-		});
-		this.registry.on("refReleased", (instance, refId) => {
-			this.notifyPlugins("onRefReleased", instance, refId);
-		});
-	}
-	/**
-	* 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,
-					createdAt: instance.createdAt,
-					state: instance.state,
-					hydrationStatus: instance.hydrationStatus,
-					isHydrated: instance.isHydrated,
-					hydrationError: instance.hydrationError,
-					changedWhileHydrating: instance.changedWhileHydrating
-				};
-			},
-			getState: (instance) => {
-				return instance.state;
-			},
-			getHydrationStatus: (instance) => {
-				return instance.hydrationStatus;
-			},
-			startHydration: (instance) => {
-				instance.beginHydration();
-			},
-			applyHydratedState: (instance, state) => {
-				return instance.applyHydratedState(state);
-			},
-			finishHydration: (instance) => {
-				instance.finishHydration();
-			},
-			failHydration: (instance, error) => {
-				instance.failHydration(error);
-			},
-			waitForHydration: (instance) => {
-				return instance.waitForHydration();
-			},
-			queryInstances: (typeClass) => {
-				return this.registry.getAll(typeClass);
-			},
-			getAllTypes: () => {
-				return this.registry.getTypes();
-			},
-			getStats: () => {
-				return this.registry.getStats();
-			},
-			getRefIds: (instanceId) => {
-				for (const Type of this.registry.getTypes()) {
-					const map = this.registry.getInstancesMap(Type);
-					for (const [, entry] of map) if (entry.instance.instanceId === instanceId) return Array.from(entry.refs.keys());
-				}
-				return [];
-			}
-		};
-	}
-	/**
-	* 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 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) => {
+        this.notifyPlugins(
+          'onStateChanged',
+          instance,
+          previousState,
+          currentState,
+        );
+      },
+    );
+    this.registry.on('disposed', (instance) => {
+      this.notifyPlugins('onInstanceDisposed', instance);
+    });
+    this.registry.on('refAcquired', (instance, refId) => {
+      this.notifyPlugins('onRefAcquired', instance, refId);
+    });
+    this.registry.on('refReleased', (instance, refId) => {
+      this.notifyPlugins('onRefReleased', instance, refId);
+    });
+  }
+  /**
+   * 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,
+          createdAt: instance.createdAt,
+          state: instance.state,
+          hydrationStatus: instance.hydrationStatus,
+          isHydrated: instance.isHydrated,
+          hydrationError: instance.hydrationError,
+          changedWhileHydrating: instance.changedWhileHydrating,
+        };
+      },
+      getState: (instance) => {
+        return instance.state;
+      },
+      getHydrationStatus: (instance) => {
+        return instance.hydrationStatus;
+      },
+      startHydration: (instance) => {
+        instance.beginHydration();
+      },
+      applyHydratedState: (instance, state) => {
+        return instance.applyHydratedState(state);
+      },
+      finishHydration: (instance) => {
+        instance.finishHydration();
+      },
+      failHydration: (instance, error) => {
+        instance.failHydration(error);
+      },
+      waitForHydration: (instance) => {
+        return instance.waitForHydration();
+      },
+      queryInstances: (typeClass) => {
+        return this.registry.getAll(typeClass);
+      },
+      getAllTypes: () => {
+        return this.registry.getTypes();
+      },
+      getStats: () => {
+        return this.registry.getStats();
+      },
+      getRefIds: (instanceId) => {
+        for (const Type of this.registry.getTypes()) {
+          const map = this.registry.getInstancesMap(Type);
+          for (const [, entry] of map)
+            if (entry.instance.instanceId === instanceId)
+              return Array.from(entry.refs.keys());
+        }
+        return [];
+      },
+    };
+  }
+  /**
+   * 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
-*/
+ * 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);
+  return new PluginManager(registry);
 }
 //#endregion
 //#region src/utils/static-props.ts
 /**
-* Utility functions for accessing static properties on StateContainer classes
-*/
+ * 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
-*/
+ * 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;
+  return Type[propName] ?? defaultValue;
 }
 /**
-* 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`
-*/
+ * 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;
+  return getStaticProp(Type, BLAC_STATIC_PROPS.KEEP_ALIVE) === true;
 }
 //#endregion
 //#region src/core/StateContainerRegistry.ts
 /**
-* Central registry for managing StateContainer instances.
-* Handles instance lifecycle, named ref tracking, 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);
-* });
-* ```
-*/
+ * Central registry for managing StateContainer instances.
+ * Handles instance lifecycle, named ref tracking, 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.registeredTypeNames = /* @__PURE__ */ new Set();
-		this.listeners = /* @__PURE__ */ new Map();
-		this._stateChangedListenerCount = 0;
-		this._pendingStateChanges = null;
-		this._autoRefIdCounter = 0;
-	}
-	/**
-	* 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
-	* @throws Error if type is already registered
-	*/
-	register(constructor) {
-		const className = constructor.name;
-		if (this.registeredTypeNames.has(className)) throw new Error(`${BLAC_ERROR_PREFIX} Type "${className}" is already registered`);
-		this.registeredTypeNames.add(className);
-		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 tracking (ownership semantics).
-	* Creates a new instance if one doesn't exist, or returns existing and adds a ref.
-	* You must call `release()` with the same refId when done.
-	* @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 add a reference (default: true)
-	* @param options.refId - Named reference ID for debugging; auto-generated if omitted
-	* @returns The state container instance
-	*/
-	acquire(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, options = {}) {
-		const { canCreate = true, countRef = true } = options;
-		const config = { instanceId: instanceKey };
-		const instances = this.ensureInstancesMap(Type);
-		let entry = instances.get(instanceKey);
-		if (entry?.instance.isDisposed) {
-			instances.delete(instanceKey);
-			entry = void 0;
-		}
-		if (entry && countRef) {
-			const refId = options.refId ?? `_auto_${this._autoRefIdCounter++}`;
-			entry.refs.set(refId, (entry.refs.get(refId) ?? 0) + 1);
-			this.emit("refAcquired", entry.instance, refId);
-		}
-		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);
-		const initialRefs = /* @__PURE__ */ new Map();
-		let initialRefId;
-		if (countRef) {
-			initialRefId = options.refId ?? `_auto_${this._autoRefIdCounter++}`;
-			initialRefs.set(initialRefId, 1);
-		}
-		instances.set(instanceKey, {
-			instance,
-			refs: initialRefs
-		});
-		this.registerType(Type);
-		if (initialRefId) this.emit("refAcquired", instance, initialRefId);
-		return instance;
-	}
-	/**
-	* Borrow an existing instance without adding a ref (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 adding a ref.
-	* 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 added).
-	* @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.
-	* Removes the ref and disposes when refs is empty (unless keepAlive).
-	* Releasing an already-removed refId is a no-op (idempotent).
-	* @param Type - The StateContainer class constructor
-	* @param instanceKey - Instance key (defaults to 'default')
-	* @param forceDispose - Force immediate disposal regardless of refs
-	* @param refId - The specific ref to remove; removes one arbitrary ref if omitted
-	*/
-	release(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, forceDispose = false, refId) {
-		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;
-		}
-		let releasedRefId;
-		if (refId !== void 0) {
-			const count = entry.refs.get(refId) ?? 0;
-			if (count <= 1) entry.refs.delete(refId);
-			else entry.refs.set(refId, count - 1);
-			releasedRefId = refId;
-		} else {
-			const firstKey = entry.refs.keys().next().value;
-			if (firstKey !== void 0) {
-				const count = entry.refs.get(firstKey);
-				if (count <= 1) entry.refs.delete(firstKey);
-				else entry.refs.set(firstKey, count - 1);
-				releasedRefId = firstKey;
-			}
-		}
-		if (releasedRefId) this.emit("refReleased", entry.instance, releasedRefId);
-		const keepAlive = isKeepAliveClass(Type);
-		if (entry.refs.size === 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 (number of active refs).
-	* @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)?.refs.size ?? 0;
-	}
-	/**
-	* Get all active reference IDs for an instance.
-	* @param Type - The StateContainer class constructor
-	* @param instanceKey - Instance key (defaults to 'default')
-	* @returns Array of ref ID strings (empty if instance doesn't exist)
-	*/
-	getRefIds(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
-		const instances = this.instancesByConstructor.get(Type);
-		if (!instances) return [];
-		const entry = instances.get(instanceKey);
-		return entry ? Array.from(entry.refs.keys()) : [];
-	}
-	/**
-	* 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.registeredTypeNames.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);
-		if (event === "stateChanged") this._stateChangedListenerCount++;
-		return () => {
-			if (this.listeners.get(event)?.delete(listener) && event === "stateChanged") this._stateChangedListenerCount--;
-		};
-	}
-	/**
-	* 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);
-		}
-	}
-	/**
-	* Schedule a deferred stateChanged notification via microtask.
-	* Skips entirely when no stateChanged listeners are registered.
-	* @internal - Called by StateContainer.applyState
-	*/
-	notifyStateChanged(container, previousState, newState) {
-		if (this._stateChangedListenerCount === 0) return;
-		if (!this._pendingStateChanges) {
-			this._pendingStateChanges = [];
-			queueMicrotask(() => this.flushStateChanged());
-		}
-		this._pendingStateChanges.push([
-			container,
-			previousState,
-			newState
-		]);
-	}
-	flushStateChanged() {
-		const pending = this._pendingStateChanges;
-		this._pendingStateChanges = null;
-		if (!pending) return;
-		for (const [container, prev, next] of pending) this.emit("stateChanged", container, prev, next);
-	}
+  constructor() {
+    this.instancesByConstructor = /* @__PURE__ */ new WeakMap();
+    this.types = /* @__PURE__ */ new Set();
+    this.registeredTypeNames = /* @__PURE__ */ new Set();
+    this.listeners = /* @__PURE__ */ new Map();
+    this._stateChangedListenerCount = 0;
+    this._pendingStateChanges = null;
+    this._autoRefIdCounter = 0;
+  }
+  /**
+   * 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
+   * @throws Error if type is already registered
+   */
+  register(constructor) {
+    const className = constructor.name;
+    if (this.registeredTypeNames.has(className))
+      throw new Error(
+        `${BLAC_ERROR_PREFIX} Type "${className}" is already registered`,
+      );
+    this.registeredTypeNames.add(className);
+    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 tracking (ownership semantics).
+   * Creates a new instance if one doesn't exist, or returns existing and adds a ref.
+   * You must call `release()` with the same refId when done.
+   * @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 add a reference (default: true)
+   * @param options.refId - Named reference ID for debugging; auto-generated if omitted
+   * @returns The state container instance
+   */
+  acquire(
+    Type,
+    instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY,
+    options = {},
+  ) {
+    const { canCreate = true, countRef = true } = options;
+    const config = { instanceId: instanceKey };
+    const instances = this.ensureInstancesMap(Type);
+    let entry = instances.get(instanceKey);
+    if (entry?.instance.isDisposed) {
+      instances.delete(instanceKey);
+      entry = void 0;
+    }
+    if (entry && countRef) {
+      const refId = options.refId ?? `_auto_${this._autoRefIdCounter++}`;
+      entry.refs.set(refId, (entry.refs.get(refId) ?? 0) + 1);
+      this.emit('refAcquired', entry.instance, refId);
+    }
+    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);
+    const initialRefs = /* @__PURE__ */ new Map();
+    let initialRefId;
+    if (countRef) {
+      initialRefId = options.refId ?? `_auto_${this._autoRefIdCounter++}`;
+      initialRefs.set(initialRefId, 1);
+    }
+    instances.set(instanceKey, {
+      instance,
+      refs: initialRefs,
+    });
+    this.registerType(Type);
+    if (initialRefId) this.emit('refAcquired', instance, initialRefId);
+    return instance;
+  }
+  /**
+   * Borrow an existing instance without adding a ref (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 adding a ref.
+   * 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 added).
+   * @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.
+   * Removes the ref and disposes when refs is empty (unless keepAlive).
+   * Releasing an already-removed refId is a no-op (idempotent).
+   * @param Type - The StateContainer class constructor
+   * @param instanceKey - Instance key (defaults to 'default')
+   * @param forceDispose - Force immediate disposal regardless of refs
+   * @param refId - The specific ref to remove; removes one arbitrary ref if omitted
+   */
+  release(
+    Type,
+    instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY,
+    forceDispose = false,
+    refId,
+  ) {
+    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;
+    }
+    let releasedRefId;
+    if (refId !== void 0) {
+      const count = entry.refs.get(refId) ?? 0;
+      if (count <= 1) entry.refs.delete(refId);
+      else entry.refs.set(refId, count - 1);
+      releasedRefId = refId;
+    } else {
+      const firstKey = entry.refs.keys().next().value;
+      if (firstKey !== void 0) {
+        const count = entry.refs.get(firstKey);
+        if (count <= 1) entry.refs.delete(firstKey);
+        else entry.refs.set(firstKey, count - 1);
+        releasedRefId = firstKey;
+      }
+    }
+    if (releasedRefId) this.emit('refReleased', entry.instance, releasedRefId);
+    const keepAlive = isKeepAliveClass(Type);
+    if (entry.refs.size === 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 (number of active refs).
+   * @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)?.refs.size ?? 0;
+  }
+  /**
+   * Get all active reference IDs for an instance.
+   * @param Type - The StateContainer class constructor
+   * @param instanceKey - Instance key (defaults to 'default')
+   * @returns Array of ref ID strings (empty if instance doesn't exist)
+   */
+  getRefIds(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+    const instances = this.instancesByConstructor.get(Type);
+    if (!instances) return [];
+    const entry = instances.get(instanceKey);
+    return entry ? Array.from(entry.refs.keys()) : [];
+  }
+  /**
+   * 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.registeredTypeNames.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);
+    if (event === 'stateChanged') this._stateChangedListenerCount++;
+    return () => {
+      if (
+        this.listeners.get(event)?.delete(listener) &&
+        event === 'stateChanged'
+      )
+        this._stateChangedListenerCount--;
+    };
+  }
+  /**
+   * 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,
+        );
+      }
+  }
+  /**
+   * Schedule a deferred stateChanged notification via microtask.
+   * Skips entirely when no stateChanged listeners are registered.
+   * @internal - Called by StateContainer.applyState
+   */
+  notifyStateChanged(container, previousState, newState) {
+    if (this._stateChangedListenerCount === 0) return;
+    if (!this._pendingStateChanges) {
+      this._pendingStateChanges = [];
+      queueMicrotask(() => this.flushStateChanged());
+    }
+    this._pendingStateChanges.push([container, previousState, newState]);
+  }
+  flushStateChanged() {
+    const pending = this._pendingStateChanges;
+    this._pendingStateChanges = null;
+    if (!pending) return;
+    for (const [container, prev, next] of pending)
+      this.emit('stateChanged', container, prev, next);
+  }
 };
 /**
-* Global default registry instance
-*/
+ * Global default registry instance
+ */
 const globalRegistry = new StateContainerRegistry();
 /**
-* Global plugin manager (initialized lazily)
-*/
+ * Global plugin manager (initialized lazily)
+ */
 let _globalPluginManager = null;
 /**
-* Get the global plugin manager
-*/
+ * Get the global plugin manager
+ */
 function getPluginManager() {
-	if (!_globalPluginManager) _globalPluginManager = createPluginManager(globalRegistry);
-	return _globalPluginManager;
+  if (!_globalPluginManager)
+    _globalPluginManager = createPluginManager(globalRegistry);
+  return _globalPluginManager;
 }
 //#endregion
-Object.defineProperty(exports, "BLAC_DEFAULTS", {
-	enumerable: true,
-	get: function() {
-		return BLAC_DEFAULTS;
-	}
+Object.defineProperty(exports, 'BLAC_DEFAULTS', {
+  enumerable: true,
+  get: function () {
+    return BLAC_DEFAULTS;
+  },
 });
-Object.defineProperty(exports, "BLAC_ERROR_PREFIX", {
-	enumerable: true,
-	get: function() {
-		return BLAC_ERROR_PREFIX;
-	}
+Object.defineProperty(exports, 'BLAC_ERROR_PREFIX', {
+  enumerable: true,
+  get: function () {
+    return BLAC_ERROR_PREFIX;
+  },
 });
-Object.defineProperty(exports, "BLAC_STATIC_PROPS", {
-	enumerable: true,
-	get: function() {
-		return BLAC_STATIC_PROPS;
-	}
+Object.defineProperty(exports, 'BLAC_STATIC_PROPS', {
+  enumerable: true,
+  get: function () {
+    return BLAC_STATIC_PROPS;
+  },
 });
-Object.defineProperty(exports, "PluginManager", {
-	enumerable: true,
-	get: function() {
-		return PluginManager;
-	}
+Object.defineProperty(exports, 'PluginManager', {
+  enumerable: true,
+  get: function () {
+    return PluginManager;
+  },
 });
-Object.defineProperty(exports, "StateContainerRegistry", {
-	enumerable: true,
-	get: function() {
-		return StateContainerRegistry;
-	}
+Object.defineProperty(exports, 'StateContainerRegistry', {
+  enumerable: true,
+  get: function () {
+    return StateContainerRegistry;
+  },
 });
-Object.defineProperty(exports, "getPluginManager", {
-	enumerable: true,
-	get: function() {
-		return getPluginManager;
-	}
+Object.defineProperty(exports, 'getPluginManager', {
+  enumerable: true,
+  get: function () {
+    return getPluginManager;
+  },
 });
-Object.defineProperty(exports, "globalRegistry", {
-	enumerable: true,
-	get: function() {
-		return globalRegistry;
-	}
+Object.defineProperty(exports, 'globalRegistry', {
+  enumerable: true,
+  get: function () {
+    return globalRegistry;
+  },
 });
 
-//# sourceMappingURL=StateContainerRegistry-CTOXUf75.cjs.map
+//# sourceMappingURL=StateContainerRegistry-CTOXUf75.cjs.map