@blac/core 2.1.0 → 2.1.1

package/dist/StateContainerRegistry-CS18y4au.cjs

@@ -1,1163 +0,0 @@
-let _dirtytalk_structural = require("@dirtytalk/structural");
-//#region src/config.ts
-/**
-* Default equality: shallow per-key `Object.is` comparison.
-* Falls through to `false` for primitives/null so reference-only state still
-* behaves correctly.
-*/
-const shallowEqualState = (prev, next) => {
-	if (Object.is(prev, next)) return true;
-	if (typeof prev !== "object" || prev === null) return false;
-	if (typeof next !== "object" || next === null) return false;
-	const prevKeys = Object.keys(prev);
-	if (prevKeys.length !== Object.keys(next).length) return false;
-	for (let i = 0; i < prevKeys.length; i++) {
-		const key = prevKeys[i];
-		if (!Object.is(prev[key], next[key])) return false;
-	}
-	return true;
-};
-const defaultConfig = {
-	equality: shallowEqualState,
-	maxInstancesPerType: 1e5,
-	maxRefsPerInstance: 1e5,
-	maxEmitsPerSecond: 1e3
-};
-let globalConfig = { ...defaultConfig };
-/**
-* Configure global defaults for @blac/core.
-*
-* @example
-* ```ts
-* import { configureBlac, shallowEqualState } from '@blac/core';
-*
-* // Swap in a deep-equality check for all blocs
-* configureBlac({ equality: myDeepEqual });
-* ```
-*/
-function configureBlac(config) {
-	globalConfig = {
-		...globalConfig,
-		...config
-	};
-}
-/**
-* Get the current global configuration.
-* @internal
-*/
-function getBlacConfig() {
-	return globalConfig;
-}
-/**
-* Reset configuration to defaults (useful for testing).
-* @internal
-*/
-function resetBlacConfig() {
-	globalConfig = { ...defaultConfig };
-}
-//#endregion
-//#region src/plugin/PluginManager.ts
-/**
-* Manages plugin lifecycle for the BlaC state management system.
-*
-* The manager hooks into two surfaces:
-*
-* 1. **Registry lifecycle events** (`created`, `disposed`, `refAcquired`,
-*    `refReleased`, `depsChanged`) — synchronous, fired by the registry.
-*
-* 2. **Per-container channel flushes** — microtask-coalesced. For each
-*    container, the manager subscribes once at create-time with
-*    `ALL_PATHS` interest and stashes `prevState`. On every flush it
-*    captures the new state + the changed `PathSet` and dispatches
-*    `onStateChange(ctx, prev, next, paths)` to every enabled plugin.
-*
-* The `ALL_PATHS` subscription cost: plugins counted as a consumer with
-* `ALL_PATHS` interest will defeat the single-consumer-skip optimization
-* in `StructuralContainer`. This is the intended trade-off — devtools /
-* persist plugins genuinely want every change, and stateful plugins
-* (logging) can decode `paths` via `container.interner.lookup(id)` to log
-* only relevant fields. Plugins that want low overhead should remain
-* uninstalled or environment-gated.
-*
-* @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.lifecycleUnsubscribers = [];
-		this.containerBridges = /* @__PURE__ */ new WeakMap();
-		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 installContext = this.buildContext(void 0);
-		this.plugins.set(plugin.name, {
-			plugin,
-			config: effectiveConfig,
-			installContext
-		});
-		this.backfillPlugin(this.plugins.get(plugin.name));
-		if (plugin.onInstall) try {
-			plugin.onInstall(installContext);
-		} 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);
-	}
-	destroy() {
-		this.clear();
-		for (const unsub of this.lifecycleUnsubscribers) unsub();
-		this.lifecycleUnsubscribers = [];
-	}
-	/**
-	* Wire registry lifecycle events into plugin dispatch.
-	*
-	* `onStateChange` is NOT wired through `registry.on('stateChanged', …)` —
-	* that event lacks the `PathSet` payload. Instead, on each `created` we
-	* subscribe to the container's channel directly so we get
-	* `(paths)` and capture `(prev, next)` via the per-container snapshot.
-	*/
-	setupLifecycleHooks() {
-		this.lifecycleUnsubscribers = [
-			this.registry.on("created", (instance) => {
-				this.attachStateBridge(instance);
-				this.notifyPlugins("onCreated", instance);
-			}),
-			this.registry.on("disposed", (instance) => {
-				this.notifyPlugins("onDestroyed", instance);
-				this.detachStateBridge(instance);
-			}),
-			this.registry.on("refAcquired", (instance, refId) => {
-				this.notifyPlugins("onRefAcquired", instance, refId);
-			}),
-			this.registry.on("refReleased", (instance, refId) => {
-				this.notifyPlugins("onRefReleased", instance, refId);
-			}),
-			this.registry.on("depsChanged", (instance, previousDeps, currentDeps) => {
-				this.notifyPlugins("onDepsChanged", instance, previousDeps, currentDeps);
-			}),
-			this.registry.on("hydrationChanged", (instance, status, previousStatus) => {
-				this.notifyPlugins("onHydrationChange", instance, status, previousStatus);
-			})
-		];
-	}
-	/**
-	* Subscribe to the container's channel with `ALL_PATHS` interest, so we
-	* fire on every flush. Capture `prev` from the snapshot taken on the
-	* previous flush (or at create-time for the first flush) and pass the
-	* channel's `paths` argument straight through to plugins.
-	*
-	* Per-container bookkeeping is stored in a `WeakMap` keyed by the
-	* container itself, so a disposed/GC'd container drops cleanly.
-	*/
-	attachStateBridge(container) {
-		if (this.containerBridges.has(container)) return;
-		const bridge = {
-			unsub: () => {},
-			prevState: container.state
-		};
-		this.containerBridges.set(container, bridge);
-		bridge.unsub = container.channel.subscribe(() => _dirtytalk_structural.ALL_PATHS, (paths) => this.dispatchStateChange(container, paths));
-	}
-	detachStateBridge(container) {
-		const bridge = this.containerBridges.get(container);
-		if (!bridge) return;
-		bridge.unsub();
-		this.containerBridges.delete(container);
-	}
-	/**
-	* Backfill a newly-installed plugin with the app's existing instances.
-	*
-	* Iterates every registered `Type` and its live instances (`getAll`
-	* already skips disposed), attaching the state bridge (idempotent — see
-	* `attachStateBridge`) and, if the plugin implements `onCreated`, invoking
-	* it directly for each instance. Scoped to this single plugin only — the
-	* broadcast `notifyPlugins` would re-notify *every* plugin of *every*
-	* instance, which is wrong here.
-	*/
-	backfillPlugin(installed) {
-		const { plugin } = installed;
-		for (const Type of this.registry.getTypes()) for (const instance of this.registry.getAll(Type)) {
-			const container = instance;
-			this.attachStateBridge(container);
-			if (!plugin.onCreated) continue;
-			try {
-				plugin.onCreated(this.buildContext(container));
-			} catch (error) {
-				console.error(`[BlaC] Error in plugin "${plugin.name}" onCreated (backfill):`, error);
-			}
-		}
-	}
-	/**
-	* Channel-flush callback. Snapshots `next`, hands `(prev, next, paths)`
-	* to every enabled plugin's `onStateChange`, then updates `prevState`
-	* for the next flush.
-	*
-	* Note: `prev` is captured once and reused across plugins — every
-	* plugin sees the same `prev`/`next`/`paths` regardless of dispatch
-	* order, matching the "snapshot prev once per flush" invariant.
-	*/
-	dispatchStateChange(container, paths) {
-		const bridge = this.containerBridges.get(container);
-		if (!bridge) return;
-		const prev = bridge.prevState;
-		const next = container.state;
-		bridge.prevState = next;
-		let ctx;
-		for (const { plugin, config } of this.plugins.values()) {
-			if (!config.enabled) continue;
-			const hook = plugin.onStateChange;
-			if (typeof hook !== "function") continue;
-			try {
-				ctx ??= this.buildContext(container);
-				hook.call(plugin, ctx, prev, next, paths);
-			} catch (error) {
-				console.error(`[BlaC] Error in plugin "${plugin.name}" onStateChange:`, error);
-			}
-		}
-	}
-	/**
-	* Notify all plugins of a lifecycle event.
-	*
-	* Builds a fresh `PluginContext` per dispatch (instance becomes
-	* `ctx.container`), so plugins can reach the focal bloc through
-	* `ctx.container`. The context is built lazily on the first matching
-	* hook and reused for every other plugin in this dispatch — zero
-	* builds if no enabled plugin implements `hookName`.
-	*/
-	notifyPlugins(hookName, instance, ...extraArgs) {
-		let ctx;
-		for (const { plugin, config } of this.plugins.values()) {
-			if (!config.enabled) continue;
-			const hook = plugin[hookName];
-			if (typeof hook !== "function") continue;
-			try {
-				ctx ??= this.buildContext(instance);
-				hook.call(plugin, ctx, ...extraArgs);
-			} catch (error) {
-				console.error(`[BlaC] Error in plugin "${plugin.name}" ${hookName}:`, error);
-			}
-		}
-	}
-	/**
-	* Build a `PluginContext` for a given focal container. The context is
-	* cheap to build — its methods close over `this.registry` directly —
-	* so we create one per dispatch rather than caching per container.
-	* This sidesteps the lifetime question of "when do we evict a cached
-	* context?" and keeps `paths`-vs-`container` lifetimes cleanly
-	* separated.
-	*/
-	buildContext(container) {
-		const registry = this.registry;
-		return {
-			container,
-			getInstanceMetadata: (instance) => {
-				return {
-					id: instance.$blac.id,
-					className: instance.constructor.name,
-					isDisposed: instance.$blac.disposed,
-					name: instance.$blac.name,
-					createdAt: instance.$blac.createdAt,
-					state: instance.state,
-					hydrationStatus: instance.$blac.hydration.status,
-					isHydrated: instance.$blac.hydration.isHydrated,
-					hydrationError: instance.$blac.hydration.error,
-					changedWhileHydrating: instance.$blac.hydration.changedWhileHydrating,
-					args: instance.args
-				};
-			},
-			getState: (instance) => {
-				return instance.state;
-			},
-			getHydrationStatus: (instance) => {
-				return instance.$blac.hydration.status;
-			},
-			startHydration: (instance) => {
-				instance.$blac.hydration.begin();
-			},
-			applyHydratedState: (instance, state) => {
-				return instance.$blac.hydration.apply(state);
-			},
-			finishHydration: (instance) => {
-				instance.$blac.hydration.finish();
-			},
-			failHydration: (instance, error) => {
-				instance.$blac.hydration.fail(error);
-			},
-			waitForHydration: (instance) => {
-				return instance.$blac.hydration.wait();
-			},
-			queryInstances: (typeClass) => {
-				return registry.getAll(typeClass);
-			},
-			getAllTypes: () => {
-				return registry.getTypes();
-			},
-			getStats: () => {
-				return registry.getStats();
-			},
-			getRefIds: (instanceId) => {
-				for (const Type of registry.getTypes()) {
-					const map = registry.getInstancesMap(Type);
-					for (const [, entry] of map) if (entry.instance.$blac.id === 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
-*/
-function createPluginManager(registry) {
-	return new PluginManager(registry);
-}
-//#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 for shared instances
-	*/
-	DEFAULT_INSTANCE_KEY: "default",
-	/**
-	* Maximum getter nesting depth (prevents infinite recursion)
-	*/
-	MAX_GETTER_DEPTH: 10
-};
-/**
-* Static property names for StateContainer classes
-* Used for feature flags and configuration on bloc classes
-*/
-const BLAC_STATIC_PROPS = {
-	/**
-	* Mark a bloc to never be auto-disposed (kept alive permanently)
-	*/
-	KEEP_ALIVE: "keepAlive",
-	/**
-	* Exclude a bloc from DevTools reporting (prevents infinite loops)
-	*/
-	EXCLUDE_FROM_DEVTOOLS: "__excludeFromDevTools",
-	/**
-	* Per-class equality function used to short-circuit `emit`/`patch` when the
-	* new state is structurally equal to the previous state. Falls back to the
-	* global `configureBlac({ equality })` value when unset.
-	*/
-	EQUALITY: "__equality",
-	/**
-	* Per-class key function: `static key = (args) => string`.
-	* When set, the registry calls `Type.key(args)` to derive the instance key
-	* instead of using a structural hash of `args`. Allows blocs to ignore
-	* non-identity fields (e.g., `readonly` flags) while still keying by id.
-	*/
-	KEY: "key"
-};
-/**
-* Standard error message prefix
-*/
-const BLAC_ERROR_PREFIX = "[BlaC]";
-//#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 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;
-}
-/**
-* Check if a class should be excluded from DevTools.
-* Used to prevent infinite loops when DevTools tracks itself.
-* @param Type - The class constructor to check
-* @returns true if the class has `static __excludeFromDevTools = true`
-*/
-function isExcludedFromDevTools(Type) {
-	return getStaticProp(Type, BLAC_STATIC_PROPS.EXCLUDE_FROM_DEVTOOLS) === true;
-}
-/**
-* Get the per-class equality function set via `@blac({ equality })`, if any.
-* @param Type - The class constructor to check
-* @returns the equality function or `undefined`
-*/
-function getClassEquality(Type) {
-	const fn = getStaticProp(Type, BLAC_STATIC_PROPS.EQUALITY);
-	return typeof fn === "function" ? fn : void 0;
-}
-/**
-* Get the per-class key function set via `@blac({ key })` or `static key = …`, if any.
-* Used by the registry to derive a stable instance key from `args`.
-* @param Type - The class constructor to check
-* @returns the key function or `undefined`
-*/
-function getClassKey(Type) {
-	const fn = getStaticProp(Type, BLAC_STATIC_PROPS.KEY, void 0);
-	return typeof fn === "function" ? fn : void 0;
-}
-//#endregion
-//#region src/utils/structural-key.ts
-/**
-* Deterministic, order-independent hash of serializable args.
-* Sorts object keys so {a,b} === {b,a}.
-* Throws (dev) if it encounters a function or non-plain object — those belong in `deps`.
-*/
-const DEFAULT_STRUCTURAL_KEY = "default";
-/**
-* Produce a stable string key for serializable args.
-* - `undefined` / `void` args → `'default'` sentinel (no-args blocs stay on the default key).
-* - Object keys are sorted for order-independence.
-* - Arrays keep their insertion order.
-* - Functions throw — they must be passed via `deps`, not `args`.
-*/
-function structuralKey(args) {
-	if (args === void 0 || args === null) return DEFAULT_STRUCTURAL_KEY;
-	return JSON.stringify(args, function(_k, v) {
-		if (typeof v === "function") throw new Error("[blac] args must be serializable; put refs/callbacks in `deps`");
-		if (v && typeof v === "object" && !Array.isArray(v)) return Object.keys(v).sort().reduce((o, k) => {
-			o[k] = v[k];
-			return o;
-		}, {});
-		return v;
-	});
-}
-//#endregion
-//#region src/core/symbols.ts
-/**
-* @internal Apply one owner's (consumer's) deps slice to an instance.
-* Called by framework adapters (e.g. @blac/react useBloc) — not public API.
-*/
-const APPLY_DEPS = Symbol("blac.applyDeps");
-/**
-* @internal Withdraw one owner's entire deps slice (consumer unmounted).
-* Called by framework adapters — not public API.
-*/
-const REMOVE_DEPS_OWNER = Symbol("blac.removeDepsOwner");
-/**
-* @internal Subscribe to this specific instance's own disposal, bypassing
-* the global registry `'disposed'` event. Called by `watch()` — not public
-* API.
-*/
-const ON_DISPOSE = Symbol("blac.onDispose");
-/**
-* @internal Symbol-keyed configuration entry point on `StateContainer`.
-* Writes the instance's identity fields (`_name`/`_debug`/`_instanceId`),
-* resolves per-class equality, emits the registry `created` event, and runs
-* `init()` once.
-*
-* Framework-only — the registry (`StateContainerRegistry.ensure`) and testing
-* helpers are the sole callers, mirroring the `APPLY_DEPS` precedent.
-*/
-const INIT_CONFIG = Symbol("blac.initConfig");
-//#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);
-* });
-* ```
-*/
-var StateContainerRegistry = class {
-	get hasStateChangedListeners() {
-		return this._stateChangedListenerCount > 0;
-	}
-	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;
-		this.on("disposed", (container) => this._handleDisposed(container));
-	}
-	/**
-	* Registry-internal reaction to any instance's `disposed` lifecycle event.
-	* If the disposing container is itself tracked in this registry (i.e. it
-	* was `acquire()`/`ensure()`'d, not a bare `new`), prune its Map entry and
-	* release its dependent edges on whatever it `depend()`'d on.
-	*/
-	_handleDisposed(container) {
-		const Type = container.constructor;
-		if (!this._pruneEntry(Type, container)) return;
-		for (const [DepType, depKey] of container.$blac.dependencies) this._releaseDependent(DepType, depKey, container);
-	}
-	/**
-	* Remove the Map entry for `container`, if this registry is tracking it.
-	* @returns true if an entry was found and removed
-	*/
-	_pruneEntry(Type, container) {
-		const instances = this.instancesByConstructor.get(Type);
-		if (!instances) return false;
-		for (const [key, entry] of instances) if (entry.instance === container) {
-			instances.delete(key);
-			return true;
-		}
-		return false;
-	}
-	/**
-	* Drop `dependent`'s edge on the `Type`/`key` entry (a `depend()`-resolved
-	* instance). When that leaves the entry with no dependents AND no public
-	* refs AND it isn't keepAlive, dispose it — this recurses into the same
-	* `disposed` listener, so dep-of-dep chains unwind naturally.
-	*/
-	_releaseDependent(Type, key, dependent) {
-		const entry = this.instancesByConstructor.get(Type)?.get(key);
-		if (!entry) return;
-		entry.dependents?.delete(dependent);
-		if ((!entry.dependents || entry.dependents.size === 0) && entry.refs.size === 0 && !isKeepAliveClass(Type) && !entry.instance.$blac.disposed) entry.instance.dispose();
-	}
-	/**
-	* 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();
-	}
-	/**
-	* Directly insert an instance entry into the registry without going through
-	* acquire/release. Creates the internal WeakMap bucket for the constructor if
-	* it does not exist yet. Replaces any existing entry for the same key.
-	*
-	* The provided instance is NOT configured or disposed here — callers are
-	* responsible for any initConfig / dispose calls. Intended for testing
-	* helpers that create stubs outside the normal acquisition path.
-	*
-	* @internal Used by testing helpers only.
-	*/
-	insertInstance(Type, instanceKey, instance, refs = /* @__PURE__ */ new Map()) {
-		const instances = this.ensureInstancesMap(Type);
-		const existingEntry = instances.get(instanceKey);
-		if (existingEntry && existingEntry.instance !== instance && !existingEntry.instance.$blac.disposed) existingEntry.instance.dispose();
-		instances.set(instanceKey, {
-			instance,
-			refs
-		});
-	}
-	/**
-	* Resolve the storage key for an instance. This is the single source of truth
-	* for keying — `acquire` and `release` MUST agree, otherwise a ref taken under
-	* an args-derived key is never dropped (instance leaks).
-	*
-	* Resolution order (explicit beats derived):
-	* explicit key > `static key(args)` > structural hash of args > default sentinel.
-	*
-	* @param Type - The StateContainer class constructor
-	* @param instanceKey - Explicit key, or undefined to derive from args
-	* @param args - Construction args used for structural/`static key` derivation
-	*/
-	resolveKey(Type, instanceKey, args) {
-		if (instanceKey !== void 0) return instanceKey;
-		const keyFn = getClassKey(Type);
-		if (keyFn) return keyFn(args);
-		if (args !== void 0) return structuralKey(args);
-		return DEFAULT_STRUCTURAL_KEY;
-	}
-	/**
-	* Circuit breaker for runaway instance creation. Throws when a single
-	* constructor would exceed `maxInstancesPerType` live instances — almost
-	* always an unstable instance key (e.g. a new object/array passed as `args`
-	* every render, or a missing `static key`) leaking an instance per render.
-	*/
-	assertInstanceLimit(Type, currentCount) {
-		const limit = getBlacConfig().maxInstancesPerType;
-		if (limit > 0 && currentCount >= limit) throw new Error(`${BLAC_ERROR_PREFIX} ${Type.name} exceeded the maximum of ${limit} live instances. This usually means the instance key is unstable — e.g. \`args\` that change identity every render, or a missing \`static key\` — so a new instance is created and never disposed (memory leak). Stabilize the key, add a \`static key(args)\`, or raise \`configureBlac({ maxInstancesPerType })\`.`);
-	}
-	/**
-	* Circuit breaker for runaway reference growth. Throws when one instance
-	* accumulates more than `maxRefsPerInstance` distinct live refs — almost
-	* always consumer cleanup (e.g. `useBloc`'s unmount `release`) never firing.
-	*/
-	assertRefLimit(Type, resolvedKey, refCount) {
-		const limit = getBlacConfig().maxRefsPerInstance;
-		if (limit > 0 && refCount > limit) throw new Error(`${BLAC_ERROR_PREFIX} ${Type.name} instance "${resolvedKey}" exceeded the maximum of ${limit} live references. This usually means references are acquired without a matching release (e.g. a consumer that never unmounts/cleans up), leaking refs that keep the instance alive forever. Ensure every acquire is paired with a release, or raise \`configureBlac({ maxRefsPerInstance })\`.`);
-	}
-	/**
-	* 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.
-	*
-	* @internal Internal key tier. Public callers use the args-based `acquire`
-	*   wrapper; `useBloc` and `watch` address a pre-resolved key here.
-	* @param Type - The StateContainer class constructor
-	* @param instanceKey - Pre-resolved 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
-	* @param options.dependent - The `depend()`-owner resolving this instance, if any;
-	*   recorded so its dependent edge can be released on the owner's disposal.
-	* @returns The state container instance
-	*/
-	acquire(Type, instanceKey, options = {}) {
-		const { canCreate = true, countRef = true } = options;
-		const args = options.args;
-		const resolvedKey = this.resolveKey(Type, instanceKey, args);
-		const config = {
-			instanceId: resolvedKey,
-			args
-		};
-		const instances = this.ensureInstancesMap(Type);
-		let entry = instances.get(resolvedKey);
-		if (entry?.instance.$blac.disposed) {
-			instances.delete(resolvedKey);
-			entry = void 0;
-		}
-		if (entry) {
-			if (process.env.NODE_ENV !== "production" && args !== void 0 && entry.args !== void 0) {
-				const incomingKey = structuralKey(args);
-				const storedKey = entry.argsKey ??= structuralKey(entry.args);
-				if (incomingKey !== storedKey) console.warn(`${BLAC_ERROR_PREFIX} ${Type.name} instance key "${resolvedKey}" was acquired with different args. Existing args: ${storedKey}, new args: ${incomingKey}. The existing instance will be reused. If distinct args should produce distinct instances, either remove the explicit instanceKey or provide a \`static key\` function that reflects the difference.`);
-			}
-			if (countRef) {
-				const refId = options.refId ?? `_auto_${this._autoRefIdCounter++}`;
-				entry.refs.set(refId, (entry.refs.get(refId) ?? 0) + 1);
-				this.assertRefLimit(Type, resolvedKey, entry.refs.size);
-				this.emit("refAcquired", entry.instance, refId);
-			}
-			if (options.dependent) (entry.dependents ??= /* @__PURE__ */ new Set()).add(options.dependent);
-			return entry.instance;
-		}
-		if (!canCreate) throw new Error(`${BLAC_ERROR_PREFIX} ${Type.name} instance "${resolvedKey}" not found and creation is disabled.`);
-		this.assertInstanceLimit(Type, instances.size);
-		const instance = new Type();
-		instance[INIT_CONFIG](config);
-		const initialRefs = /* @__PURE__ */ new Map();
-		let initialRefId;
-		if (countRef) {
-			initialRefId = options.refId ?? `_auto_${this._autoRefIdCounter++}`;
-			initialRefs.set(initialRefId, 1);
-		}
-		const newEntry = {
-			instance,
-			refs: initialRefs,
-			args
-		};
-		if (options.dependent) (newEntry.dependents ??= /* @__PURE__ */ new Set()).add(options.dependent);
-		instances.set(resolvedKey, newEntry);
-		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.
-	*
-	* @internal Internal key tier; public callers use the args-based `borrow`.
-	* @param Type - The StateContainer class constructor
-	* @param instanceKey - Pre-resolved 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.
-	*
-	* @internal Internal key tier; public callers use the args-based `borrowSafe`.
-	* @param Type - The StateContainer class constructor
-	* @param instanceKey - Pre-resolved 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).
-	*
-	* @internal Internal key tier; public callers use the args-based `ensure`.
-	* @param Type - The StateContainer class constructor
-	* @param instanceKey - Pre-resolved instance key, or undefined to derive from `args`
-	*   (`static key(args)` / structural hash), matching `acquire`.
-	* @param args - Construction args; used for keying when no explicit key is given
-	* @returns The state container instance
-	*/
-	ensure(Type, instanceKey, args) {
-		return this.acquire(Type, instanceKey, {
-			canCreate: true,
-			countRef: false,
-			args
-		});
-	}
-	/**
-	* 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).
-	*
-	* @internal Internal key tier; public callers use the args-based `release`.
-	* @param Type - The StateContainer class constructor
-	* @param instanceKey - Pre-resolved 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.$blac.disposed) 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) ?? 0;
-				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.$blac.disposed) 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()) if (!entry.instance.$blac.disposed) 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.$blac.disposed) 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.$blac.disposed) entry.instance.dispose();
-		instances.clear();
-	}
-	/**
-	* Get reference count for an instance (number of active refs).
-	*
-	* @internal Internal key tier; public callers use the args-based `getRefCount`.
-	* @param Type - The StateContainer class constructor
-	* @param instanceKey - Pre-resolved 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.
-	*
-	* @internal Internal key tier; public callers use the args-based `getRefIds`.
-	* @param Type - The StateContainer class constructor
-	* @param instanceKey - Pre-resolved 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.
-	*
-	* @internal Internal key tier; public callers use the args-based `hasInstance`.
-	* @param Type - The StateContainer class constructor
-	* @param instanceKey - Pre-resolved 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(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
-*/
-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
-Object.defineProperty(exports, "APPLY_DEPS", {
-	enumerable: true,
-	get: function() {
-		return APPLY_DEPS;
-	}
-});
-Object.defineProperty(exports, "BLAC_STATIC_PROPS", {
-	enumerable: true,
-	get: function() {
-		return BLAC_STATIC_PROPS;
-	}
-});
-Object.defineProperty(exports, "INIT_CONFIG", {
-	enumerable: true,
-	get: function() {
-		return INIT_CONFIG;
-	}
-});
-Object.defineProperty(exports, "ON_DISPOSE", {
-	enumerable: true,
-	get: function() {
-		return ON_DISPOSE;
-	}
-});
-Object.defineProperty(exports, "PluginManager", {
-	enumerable: true,
-	get: function() {
-		return PluginManager;
-	}
-});
-Object.defineProperty(exports, "REMOVE_DEPS_OWNER", {
-	enumerable: true,
-	get: function() {
-		return REMOVE_DEPS_OWNER;
-	}
-});
-Object.defineProperty(exports, "StateContainerRegistry", {
-	enumerable: true,
-	get: function() {
-		return StateContainerRegistry;
-	}
-});
-Object.defineProperty(exports, "configureBlac", {
-	enumerable: true,
-	get: function() {
-		return configureBlac;
-	}
-});
-Object.defineProperty(exports, "getBlacConfig", {
-	enumerable: true,
-	get: function() {
-		return getBlacConfig;
-	}
-});
-Object.defineProperty(exports, "getClassEquality", {
-	enumerable: true,
-	get: function() {
-		return getClassEquality;
-	}
-});
-Object.defineProperty(exports, "getPluginManager", {
-	enumerable: true,
-	get: function() {
-		return getPluginManager;
-	}
-});
-Object.defineProperty(exports, "globalRegistry", {
-	enumerable: true,
-	get: function() {
-		return globalRegistry;
-	}
-});
-Object.defineProperty(exports, "isExcludedFromDevTools", {
-	enumerable: true,
-	get: function() {
-		return isExcludedFromDevTools;
-	}
-});
-Object.defineProperty(exports, "isKeepAliveClass", {
-	enumerable: true,
-	get: function() {
-		return isKeepAliveClass;
-	}
-});
-Object.defineProperty(exports, "resetBlacConfig", {
-	enumerable: true,
-	get: function() {
-		return resetBlacConfig;
-	}
-});
-Object.defineProperty(exports, "shallowEqualState", {
-	enumerable: true,
-	get: function() {
-		return shallowEqualState;
-	}
-});
-
-//# sourceMappingURL=StateContainerRegistry-CS18y4au.cjs.map