@blac/core 2.0.22 → 2.1.1

package/dist/StateContainerRegistry-BvSRfhKv.cjs

@@ -0,0 +1,866 @@
+//#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 p = prev;
+	const n = next;
+	let prevCount = 0;
+	for (const key in p) {
+		prevCount++;
+		if (!Object.is(p[key], n[key])) return false;
+	}
+	let nextCount = 0;
+	for (const _ in n) nextCount++;
+	return prevCount === nextCount;
+};
+const defaultConfig = {
+	equality: shallowEqualState,
+	maxInstancesPerType: 1e5,
+	maxRefsPerInstance: 1e5,
+	maxEmitsPerSecond: 1e3,
+	unownedSweepDelayMs: 5e3
+};
+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/constants.ts
+/** Static property names 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",
+	/**
+	* Explicit, minification-safe identity for a bloc class: `static blacName = '...'`.
+	* When unset, identity falls back to `constructor.name`.
+	*/
+	BLAC_NAME: "blacName"
+};
+const BLAC_ERROR_PREFIX = "[BlaC]";
+function readNodeEnv() {
+	try {
+		return process.env.NODE_ENV;
+	} catch {
+		return;
+	}
+}
+const nodeEnv = readNodeEnv();
+/**
+* True only when `process.env.NODE_ENV` is defined and not `'production'`.
+*
+* Dev-only checks (emit-rate breaker, deps collision scan, args-mismatch key)
+* cost real work per emit/acquire, so an environment that says nothing about
+* its mode — plain ESM in the browser, Deno, a bundle without a `process`
+* shim — is treated as production. Bundlers that define `process.env.NODE_ENV`
+* still constant-fold the read.
+*/
+const IS_DEV = nodeEnv !== void 0 && nodeEnv !== "production";
+//#endregion
+//#region src/utils/static-props.ts
+/**
+* Get a static property from a class constructor, walking the prototype
+* chain so subclasses inherit the value unless they define their own.
+*/
+function getStaticProp(Type, propName) {
+	return Type[propName];
+}
+/**
+* Get a static property declared directly on `Type`, ignoring the prototype
+* chain, so subclasses never inherit a base class's value.
+*/
+function getOwnStaticProp(Type, propName) {
+	return Object.hasOwn(Type, propName) ? Type[propName] : void 0;
+}
+/**
+* Whether a class is marked `keepAlive` (never auto-disposed at ref count 0).
+* Inherited: a subclass keeps a base class's `keepAlive` unless overridden.
+*/
+function isKeepAliveClass(Type) {
+	return getStaticProp(Type, BLAC_STATIC_PROPS.KEEP_ALIVE) === true;
+}
+/**
+* Whether a class is excluded from DevTools (avoids DevTools tracking itself
+* into an infinite loop). Inherited unless overridden by a subclass.
+*/
+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.
+* Inherited: a subclass keeps a base class's equality fn unless overridden.
+*/
+function getClassEquality(Type) {
+	const fn = getStaticProp(Type, BLAC_STATIC_PROPS.EQUALITY);
+	return typeof fn === "function" ? fn : void 0;
+}
+/**
+* Get a class's minification-safe identity name (`static blacName`), falling
+* back to `Type.name`. Own only: a subclass never inherits a base class's
+* explicit `blacName`, since that would collapse two distinct blocs onto one
+* identity.
+*/
+function getBlacName(Type) {
+	return getOwnStaticProp(Type, BLAC_STATIC_PROPS.BLAC_NAME) ?? Type.name;
+}
+/**
+* Get the per-class key function set via `@blac({ key })` or `static key = …`.
+* Own only: a subclass never inherits a base class's `key`, since a
+* different `Args` shape would derive the wrong instance key.
+*/
+function getClassKey(Type) {
+	const fn = getOwnStaticProp(Type, BLAC_STATIC_PROPS.KEY);
+	return typeof fn === "function" ? fn : void 0;
+}
+//#endregion
+//#region src/utils/structural-key.ts
+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`.
+* - JSON semantics otherwise: `{ a: undefined }` equals `{}`, and `NaN` and
+*   `Infinity` serialize as `null`.
+* - Object args are memoized by identity; callers on hot paths (`resolveKey`,
+*   `depend`) re-resolve the same args object on every call. Mutating an args
+*   object after first use therefore keeps its old key.
+*/
+const keyCache = /* @__PURE__ */ new WeakMap();
+function structuralKey(args) {
+	if (args === void 0 || args === null) return DEFAULT_STRUCTURAL_KEY;
+	if (typeof args === "object") {
+		const cached = keyCache.get(args);
+		if (cached !== void 0) return cached;
+		const key = serialize(args);
+		keyCache.set(args, key);
+		return key;
+	}
+	return serialize(args);
+}
+function serialize(args) {
+	return JSON.stringify(args, function(_k, v) {
+		if (typeof v === "function") throw new Error(`[blac] args must be serializable; put refs/callbacks in \`deps\` (found a function at key "${_k || "(root)"}")`);
+		if (v && typeof v === "object" && !Array.isArray(v)) {
+			if (IS_DEV && !isPlainObject(v)) throw new Error(`[blac] args must be plain data; put refs/instances in \`deps\` (found a ${v.constructor?.name ?? "non-plain object"} at key "${_k || "(root)"}")`);
+			return Object.keys(v).sort().reduce((o, k) => {
+				o[k] = v[k];
+				return o;
+			}, {});
+		}
+		return v;
+	});
+}
+function isPlainObject(value) {
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+//#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");
+/**
+* @internal Run `fn` with `state` temporarily reporting a render's tracking
+* proxy, so getters record the paths they read. Called by `@blac/react`'s
+* `buildTrackedProxy` — not public API. Getters run with `this` bound to the
+* real instance, so ES `#private` works in user blocs.
+*/
+const WITH_TRACKED_STATE = Symbol("blac.withTrackedState");
+/**
+* @internal Drive the activation lifecycle from the registry's 0↔1 ownership
+* transition. Owns the per-instance AbortController so `onActivate`'s signal
+* aborts on the matching deactivation and on dispose.
+*
+* Framework-only — `StateContainerRegistry` is the sole caller.
+*/
+const SET_ACTIVE = Symbol("blac.setActive");
+/**
+* @internal Insert an instance entry directly, bypassing acquire/release.
+* Called by the testing helpers — not public API.
+*/
+const INSERT_INSTANCE = Symbol("blac.insertInstance");
+//#endregion
+//#region src/core/StateContainerRegistry.ts
+const EMPTY_INSTANCES_MAP = /* @__PURE__ */ new Map();
+/**
+* Owns StateContainer instances: creation, ref tracking, disposal and
+* lifecycle events.
+*
+* @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);
+* });
+* ```
+*
+* `stateChanged` fires once per emit (microtask-deferred, not coalesced).
+* Plugins' `onStateChange` fires once per channel flush with coalesced
+* `prev`/`next` and a `PathSet`.
+*/
+var StateContainerRegistry = class {
+	get hasStateChangedListeners() {
+		return (this.listeners.get("stateChanged")?.size ?? 0) > 0;
+	}
+	constructor() {
+		this.instancesByConstructor = /* @__PURE__ */ new WeakMap();
+		this.types = /* @__PURE__ */ new Set();
+		this._dependentEdges = /* @__PURE__ */ new WeakMap();
+		this._entryByInstance = /* @__PURE__ */ new WeakMap();
+		this._entryById = /* @__PURE__ */ new Map();
+		this.listeners = /* @__PURE__ */ new Map();
+		this._pendingStateChanges = null;
+		this._autoRefIdCounter = 0;
+		this.on("disposed", (container) => this._handleDisposed(container));
+	}
+	/** Prune a tracked instance's entry and release its `depend()` edges. */
+	_handleDisposed(container) {
+		const Type = container.constructor;
+		if (!this._pruneEntry(Type, container)) return;
+		const edges = this._dependentEdges.get(container);
+		if (!edges) return;
+		this._dependentEdges.delete(container);
+		for (const [DepType, keys] of edges) for (const depKey of keys) this._releaseDependent(DepType, depKey, container);
+	}
+	/** The single dispose decision: no refs, no dependents, not keepAlive. */
+	_isUnowned(Type, entry) {
+		return this._hasNoOwners(entry) && !isKeepAliveClass(Type);
+	}
+	/** Ignores keepAlive: a keepAlive instance still deactivates. */
+	_hasNoOwners(entry) {
+		return entry.refs.size === 0 && (entry.dependents === void 0 || entry.dependents.size === 0);
+	}
+	/**
+	* Idempotent, so every acquire/release path calls it. The events fire after
+	* the instance's own `onActivate`/`onDeactivate`.
+	*/
+	_syncActivation(entry) {
+		const transition = entry.instance[SET_ACTIVE](!this._hasNoOwners(entry));
+		if (transition === "none") return;
+		if (transition === "deactivated") this.emit("deactivated", entry.instance);
+		else this.emit("activated", entry.instance, transition.signal);
+	}
+	_recordDependentEdge(dependent, Type, key) {
+		let byType = this._dependentEdges.get(dependent);
+		if (!byType) this._dependentEdges.set(dependent, byType = /* @__PURE__ */ new Map());
+		let keys = byType.get(Type);
+		if (!keys) byType.set(Type, keys = /* @__PURE__ */ new Set());
+		keys.add(key);
+	}
+	/** @returns true if this registry tracked `container`. */
+	_pruneEntry(Type, container) {
+		const entry = this._entryByInstance.get(container);
+		if (entry === void 0) return false;
+		this._entryByInstance.delete(container);
+		const instances = this.instancesByConstructor.get(Type);
+		if (instances?.get(entry.key) === entry) instances.delete(entry.key);
+		const id = container.$blac.id;
+		if (this._entryById.get(id) === entry) this._entryById.delete(id);
+		return true;
+	}
+	_indexEntry(entry) {
+		this._entryByInstance.set(entry.instance, entry);
+		this._entryById.set(entry.instance.$blac.id, entry);
+	}
+	/** Disposing here recurses through `disposed`, unwinding dep chains. */
+	_releaseDependent(Type, key, dependent) {
+		const entry = this.instancesByConstructor.get(Type)?.get(key);
+		if (!entry) return;
+		entry.dependents?.delete(dependent);
+		if (this._isUnowned(Type, entry)) {
+			if (!entry.instance.$blac.disposed) entry.instance.dispose();
+			return;
+		}
+		this._syncActivation(entry);
+	}
+	/**
+	* Register a StateContainer class with configuration
+	* @param constructor - The StateContainer class constructor
+	* @throws Error if type is already registered
+	*/
+	register(constructor) {
+		if (this.types.has(constructor)) throw new Error(`${BLAC_ERROR_PREFIX} Type "${getBlacName(constructor)}" is already registered`);
+		this.types.add(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) || EMPTY_INSTANCES_MAP;
+	}
+	/**
+	* Insert an entry, replacing the one at `instanceKey`. The instance is not
+	* configured here.
+	*
+	* @internal Used by testing helpers only.
+	*/
+	[INSERT_INSTANCE](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();
+		const entry = {
+			instance,
+			key: instanceKey,
+			refs
+		};
+		instances.set(instanceKey, entry);
+		this._indexEntry(entry);
+		this.types.add(Type);
+	}
+	/**
+	* The single source of keying, so `acquire` and `release` agree: explicit
+	* key \> `static key(args)` \> structural hash of args \> default key.
+	*
+	* @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;
+	}
+	assertInstanceLimit(Type, currentCount) {
+		const limit = getBlacConfig().maxInstancesPerType;
+		if (limit > 0 && currentCount >= limit) throw new Error(`${BLAC_ERROR_PREFIX} ${getBlacName(Type)} 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 })\`.`);
+	}
+	assertRefLimit(Type, resolvedKey, refCount) {
+		const limit = getBlacConfig().maxRefsPerInstance;
+		if (limit > 0 && refCount > limit) throw new Error(`${BLAC_ERROR_PREFIX} ${getBlacName(Type)} 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 })\`.`);
+	}
+	/**
+	* Get or create an instance and add a ref; `release()` it with the same
+	* refId.
+	*
+	* @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 - `canCreate` and `countRef` default to true; `refId` is
+	*   auto-generated when omitted; `dependent` is the `depend()`-owner, whose
+	*   edge is released on its disposal; `sweepIfUnowned` is for speculative
+	*   creates (see {@link _scheduleSweep}).
+	*/
+	acquire(Type, instanceKey, options = {}) {
+		const { canCreate = true, countRef = true } = options;
+		const args = options.args;
+		const resolvedKey = this.resolveKey(Type, instanceKey, 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 (IS_DEV && 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} ${getBlacName(Type)} 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++}`;
+				const count = entry.refs.get(refId) ?? 0;
+				if (count === 0) this.assertRefLimit(Type, resolvedKey, entry.refs.size + 1);
+				entry.refs.set(refId, count + 1);
+				this.emit("refAcquired", entry.instance, refId);
+			}
+			if (options.dependent) {
+				(entry.dependents ??= /* @__PURE__ */ new Set()).add(options.dependent);
+				this._recordDependentEdge(options.dependent, Type, resolvedKey);
+			}
+			this._syncActivation(entry);
+			if (options.sweepIfUnowned && entry.sweepTimer !== void 0) this._scheduleSweep(Type, entry);
+			return entry.instance;
+		}
+		if (!canCreate) throw new Error(`${BLAC_ERROR_PREFIX} ${getBlacName(Type)} instance "${resolvedKey}" not found and creation is disabled.`);
+		this.assertInstanceLimit(Type, instances.size);
+		const config = {
+			instanceId: resolvedKey,
+			args,
+			registry: this
+		};
+		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,
+			key: resolvedKey,
+			refs: initialRefs,
+			args
+		};
+		if (options.dependent) {
+			(newEntry.dependents ??= /* @__PURE__ */ new Set()).add(options.dependent);
+			this._recordDependentEdge(options.dependent, Type, resolvedKey);
+		}
+		instances.set(resolvedKey, newEntry);
+		this._indexEntry(newEntry);
+		this.types.add(Type);
+		if (initialRefId) this.emit("refAcquired", instance, initialRefId);
+		this._syncActivation(newEntry);
+		if (options.sweepIfUnowned && this._hasNoOwners(newEntry)) this._scheduleSweep(Type, newEntry);
+		return instance;
+	}
+	/**
+	* Dispose a speculative create (a render that never commits, SSR) that is
+	* still unowned after `unownedSweepDelayMs`. The delay must outlast a
+	* time-sliced render; a repeat speculative acquire restarts it. Opt-in, so a
+	* bare `ensure()` stays usable across an `await`.
+	*/
+	_scheduleSweep(Type, entry) {
+		clearTimeout(entry.sweepTimer);
+		entry.sweepTimer = setTimeout(() => {
+			entry.sweepTimer = void 0;
+			const instances = this.instancesByConstructor.get(Type);
+			if (instances?.get(entry.key) !== entry) return;
+			if (entry.instance.$blac.disposed) return;
+			if (!this._isUnowned(Type, entry)) return;
+			entry.instance.dispose();
+			instances.delete(entry.key);
+		}, getBlacConfig().unownedSweepDelayMs);
+	}
+	/**
+	* Get an existing instance without adding a ref.
+	*
+	* @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 = DEFAULT_STRUCTURAL_KEY) {
+		return this.acquire(Type, instanceKey, {
+			canCreate: false,
+			countRef: false
+		});
+	}
+	/**
+	* Like `borrow`, but returns the error instead of throwing.
+	*
+	* @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 = DEFAULT_STRUCTURAL_KEY) {
+		try {
+			return {
+				error: null,
+				instance: this.borrow(Type, instanceKey)
+			};
+		} catch (error) {
+			return {
+				error,
+				instance: null
+			};
+		}
+	}
+	/**
+	* Get or create an instance without adding a ref.
+	*
+	* @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
+		});
+	}
+	/**
+	* Remove a ref and dispose the instance once nothing owns it. Releasing a
+	* ref that isn't held is a no-op.
+	*
+	* @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 = DEFAULT_STRUCTURAL_KEY, forceDispose = false, refId) {
+		const instances = this.instancesByConstructor.get(Type);
+		const entry = instances?.get(instanceKey);
+		if (!instances || !entry) return;
+		if (forceDispose) {
+			if (!entry.instance.$blac.disposed) entry.instance.dispose();
+			instances.delete(instanceKey);
+			return;
+		}
+		const releasedRefId = refId ?? entry.refs.keys().next().value;
+		if (releasedRefId === void 0) return;
+		const count = entry.refs.get(releasedRefId) ?? 0;
+		if (count === 0) return;
+		if (count === 1) entry.refs.delete(releasedRefId);
+		else entry.refs.set(releasedRefId, count - 1);
+		this.emit("refReleased", entry.instance, releasedRefId);
+		if (this._isUnowned(Type, entry)) {
+			if (!entry.instance.$blac.disposed) entry.instance.dispose();
+			instances.delete(instanceKey);
+			return;
+		}
+		this._syncActivation(entry);
+	}
+	/** Live instances of `Type`. */
+	getAll(Type) {
+		const instances = this.getInstancesMap(Type);
+		const result = [];
+		for (const entry of instances.values()) if (!entry.instance.$blac.disposed) result.push(entry.instance);
+		return result;
+	}
+	/** Iterate live instances of `Type`; callback errors are logged. */
+	forEach(Type, callback) {
+		const instances = this.getInstancesMap(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 ${getBlacName(Type)}:`, error);
+			}
+		}
+	}
+	/** Dispose all instances of `Type`. */
+	clear(Type) {
+		const instances = this.instancesByConstructor.get(Type);
+		if (!instances) return;
+		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 = DEFAULT_STRUCTURAL_KEY) {
+		return this.getInstancesMap(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 = DEFAULT_STRUCTURAL_KEY) {
+		const entry = this.getInstancesMap(Type).get(instanceKey);
+		return entry ? Array.from(entry.refs.keys()) : [];
+	}
+	/** Ref ids by `$blac.id`, for `PluginContext.getRefIds`. */
+	getRefIdsById(instanceId) {
+		const entry = this._entryById.get(instanceId);
+		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 a live (not disposed) instance exists
+	*/
+	hasInstance(Type, instanceKey = DEFAULT_STRUCTURAL_KEY) {
+		const entry = this.getInstancesMap(Type).get(instanceKey);
+		return entry !== void 0 && !entry.instance.$blac.disposed;
+	}
+	/** Dispose every instance and forget all types (for testing). */
+	clearAll() {
+		for (const Type of this.types) this.clear(Type);
+		this.types.clear();
+	}
+	/** Instance counts, for debugging. */
+	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
+		};
+	}
+	/** All registered types (for plugins). */
+	getTypes() {
+		return Array.from(this.types);
+	}
+	/**
+	* Subscribe to a lifecycle event.
+	* @returns Unsubscribe function
+	*/
+	on(event, listener) {
+		let instance = this.listeners.get(event);
+		if (!instance) {
+			instance = /* @__PURE__ */ new Set();
+			this.listeners.set(event, instance);
+		}
+		instance.add(listener);
+		return () => {
+			this.listeners.get(event)?.delete(listener);
+		};
+	}
+	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);
+		}
+	}
+	/**
+	* Queue a microtask-deferred `stateChanged`.
+	* @internal - Called by StateContainer.applyState
+	*/
+	notifyStateChanged(container, previousState, newState) {
+		if (!this.hasStateChangedListeners) return;
+		if (!this._pendingStateChanges) {
+			this._pendingStateChanges = [];
+			queueMicrotask(() => this.flushStateChanged());
+		}
+		this._pendingStateChanges.push([
+			container,
+			previousState,
+			newState
+		]);
+	}
+	/**
+	* One event per emit, deliberately not coalesced: devtools and time-travel
+	* need every intermediate transition. Plugins get the coalesced lane.
+	*/
+	flushStateChanged() {
+		const pending = this._pendingStateChanges;
+		this._pendingStateChanges = null;
+		if (!pending) return;
+		for (const [container, prev, next] of pending) this.emit("stateChanged", container, prev, next);
+	}
+};
+/**
+* The global default registry.
+* @public
+*/
+const globalRegistry = new StateContainerRegistry();
+//#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, "INSERT_INSTANCE", {
+	enumerable: true,
+	get: function() {
+		return INSERT_INSTANCE;
+	}
+});
+Object.defineProperty(exports, "IS_DEV", {
+	enumerable: true,
+	get: function() {
+		return IS_DEV;
+	}
+});
+Object.defineProperty(exports, "ON_DISPOSE", {
+	enumerable: true,
+	get: function() {
+		return ON_DISPOSE;
+	}
+});
+Object.defineProperty(exports, "REMOVE_DEPS_OWNER", {
+	enumerable: true,
+	get: function() {
+		return REMOVE_DEPS_OWNER;
+	}
+});
+Object.defineProperty(exports, "SET_ACTIVE", {
+	enumerable: true,
+	get: function() {
+		return SET_ACTIVE;
+	}
+});
+Object.defineProperty(exports, "StateContainerRegistry", {
+	enumerable: true,
+	get: function() {
+		return StateContainerRegistry;
+	}
+});
+Object.defineProperty(exports, "WITH_TRACKED_STATE", {
+	enumerable: true,
+	get: function() {
+		return WITH_TRACKED_STATE;
+	}
+});
+Object.defineProperty(exports, "configureBlac", {
+	enumerable: true,
+	get: function() {
+		return configureBlac;
+	}
+});
+Object.defineProperty(exports, "getBlacConfig", {
+	enumerable: true,
+	get: function() {
+		return getBlacConfig;
+	}
+});
+Object.defineProperty(exports, "getBlacName", {
+	enumerable: true,
+	get: function() {
+		return getBlacName;
+	}
+});
+Object.defineProperty(exports, "getClassEquality", {
+	enumerable: true,
+	get: function() {
+		return getClassEquality;
+	}
+});
+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, "readNodeEnv", {
+	enumerable: true,
+	get: function() {
+		return readNodeEnv;
+	}
+});
+Object.defineProperty(exports, "resetBlacConfig", {
+	enumerable: true,
+	get: function() {
+		return resetBlacConfig;
+	}
+});
+Object.defineProperty(exports, "shallowEqualState", {
+	enumerable: true,
+	get: function() {
+		return shallowEqualState;
+	}
+});
+
+//# sourceMappingURL=StateContainerRegistry-BvSRfhKv.cjs.map