@blac/core 2.1.0 → 2.1.1

package/dist/{StateContainerRegistry-D9BIRjwv.cjs → StateContainerRegistry-MkT0W4C2.cjs}

@@ -1,4 +1,3 @@
-let _dirtytalk_structural = require("@dirtytalk/structural");
 //#region src/config.ts
 /**
 * Default equality: shallow per-key `Object.is` comparison.
@@ -9,23 +8,26 @@ 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 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: 1e3,
-	maxRefsPerInstance: 1e3,
-	maxEmitsPerSecond: 100
+	maxInstancesPerType: 1e5,
+	maxRefsPerInstance: 1e5,
+	maxEmitsPerSecond: 1e3
 };
 let globalConfig = { ...defaultConfig };
 /**
-* Configure global defaults for @blac/core.
+* Configure global defaults for `@blac/core`.
 *
 * @example
 * ```ts
@@ -56,325 +58,6 @@ 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
-		});
-		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);
-	}
-	/**
-	* 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;
-		for (const { plugin, config } of this.plugins.values()) {
-			if (!config.enabled) continue;
-			const hook = plugin.onStateChange;
-			if (typeof hook !== "function") continue;
-			try {
-				hook.call(plugin, this.buildContext(container), 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`.
-	*/
-	notifyPlugins(hookName, instance, ...extraArgs) {
-		for (const { plugin, config } of this.plugins.values()) {
-			if (!config.enabled) continue;
-			const hook = plugin[hookName];
-			if (typeof hook !== "function") continue;
-			try {
-				hook.call(plugin, this.buildContext(instance), ...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
@@ -382,19 +65,6 @@ function createPluginManager(registry) {
 * 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
 */
@@ -419,19 +89,42 @@ const BLAC_STATIC_PROPS = {
 	* 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"
+	KEY: "key",
+	/**
+	* Explicit, minification-safe identity for a bloc class: `static blacName = '...'`.
+	* When unset, identity falls back to `constructor.name`.
+	*/
+	BLAC_NAME: "blacName"
 };
 /**
 * Standard error message prefix
 */
 const BLAC_ERROR_PREFIX = "[BlaC]";
+/**
+* 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 nodeEnv = (() => {
+	try {
+		return process.env.NODE_ENV;
+	} catch {
+		return;
+	}
+})();
+const IS_DEV = nodeEnv !== void 0 && nodeEnv !== "production";
 //#endregion
 //#region src/utils/static-props.ts
 /**
 * Utility functions for accessing static properties on StateContainer classes
 */
 /**
-* Get a static property from a class constructor
+* Get a static property from a class constructor, walking the prototype
+* chain so subclasses inherit the value unless they define their own.
 * Type-safe helper that avoids (Type as any) casts
 *
 * @param Type - The class constructor
@@ -443,8 +136,20 @@ function getStaticProp(Type, propName, defaultValue) {
 	return Type[propName] ?? defaultValue;
 }
 /**
+* Get a static property declared directly on `Type`, ignoring the prototype
+* chain, so subclasses never inherit a base class's value.
+*
+* @param Type - The class constructor
+* @param propName - The property name to access
+* @returns The own property value or `undefined`
+*/
+function getOwnStaticProp(Type, propName) {
+	return Object.hasOwn(Type, propName) ? Type[propName] : void 0;
+}
+/**
 * Check if a class is marked as keepAlive.
 * KeepAlive classes are never auto-disposed when ref count reaches 0.
+* Inherited: a subclass keeps a base class's `keepAlive` unless overridden.
 * @param Type - The class constructor to check
 * @returns true if the class has `static keepAlive = true`
 */
@@ -454,6 +159,7 @@ function isKeepAliveClass(Type) {
 /**
 * Check if a class should be excluded from DevTools.
 * Used to prevent infinite loops when DevTools tracks itself.
+* Inherited: a subclass keeps a base class's exclusion unless overridden.
 * @param Type - The class constructor to check
 * @returns true if the class has `static __excludeFromDevTools = true`
 */
@@ -462,6 +168,7 @@ function isExcludedFromDevTools(Type) {
 }
 /**
 * Get the per-class equality function set via `@blac({ equality })`, if any.
+* Inherited: a subclass keeps a base class's equality fn unless overridden.
 * @param Type - The class constructor to check
 * @returns the equality function or `undefined`
 */
@@ -470,13 +177,26 @@ function getClassEquality(Type) {
 	return typeof fn === "function" ? fn : void 0;
 }
 /**
+* Get a class's minification-safe identity name.
+* Own only: a subclass never inherits a base class's explicit `blacName`,
+* since that would collapse two distinct blocs onto one identity.
+* Falls back to `Type.name` (the runtime `constructor.name`) when unset.
+* @param Type - The class constructor to check
+* @returns the explicit `static blacName` or `Type.name`
+*/
+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 = …`, if any.
 * Used by the registry to derive a stable instance key from `args`.
+* Own only: a subclass never inherits a base class's `key`, since a
+* different `Args` shape would derive the wrong instance key.
 * @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);
+	const fn = getOwnStaticProp(Type, BLAC_STATIC_PROPS.KEY);
 	return typeof fn === "function" ? fn : void 0;
 }
 //#endregion
@@ -493,11 +213,24 @@ const DEFAULT_STRUCTURAL_KEY = "default";
 * - Object keys are sorted for order-independence.
 * - Arrays keep their insertion order.
 * - Functions throw — they must be passed via `deps`, not `args`.
+* - Object args are memoized by identity; callers on hot paths (`resolveKey`,
+*   `depend`) re-resolve the same args object on every call.
 */
+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`");
+		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)) return Object.keys(v).sort().reduce((o, k) => {
 			o[k] = v[k];
 			return o;
@@ -509,7 +242,7 @@ function structuralKey(args) {
 //#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.
+* Called by framework adapters (e.g. `@blac/react` useBloc) — not public API.
 */
 const APPLY_DEPS = Symbol("blac.applyDeps");
 /**
@@ -518,6 +251,12 @@ const APPLY_DEPS = Symbol("blac.applyDeps");
 */
 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
@@ -527,8 +266,27 @@ const REMOVE_DEPS_OWNER = Symbol("blac.removeDepsOwner");
 * 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.
+*
+* Replaces the old `this`-Proxy receiver: getters now 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");
 //#endregion
 //#region src/core/StateContainerRegistry.ts
+/** Shared, read-only Map returned by `getInstancesMap` for unregistered types. */
+const EMPTY_INSTANCES_MAP = /* @__PURE__ */ new Map();
 /**
 * Central registry for managing StateContainer instances.
 * Handles instance lifecycle, named ref tracking, and lifecycle event emission.
@@ -542,19 +300,114 @@ const INIT_CONFIG = Symbol("blac.initConfig");
 *   console.log('State changed:', prev, '->', next);
 * });
 * ```
+*
+* `stateChanged` fires once per emit (microtask-deferred but uncoalesced), so
+* listeners see every intermediate transition. Plugins' `onStateChange` fires
+* once per channel flush with coalesced `prev`/`next` and a `PathSet`. Pick
+* the transition log for devtools/time-travel, the plugin hook for
+* change-driven work.
 */
 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._dependentEdges = /* @__PURE__ */ new WeakMap();
+		this._entryById = /* @__PURE__ */ new Map();
 		this.listeners = /* @__PURE__ */ new Map();
 		this._stateChangedListenerCount = 0;
 		this._pendingStateChanges = null;
 		this._autoRefIdCounter = 0;
+		this.on("disposed", (container) => this._handleDisposed(container));
 	}
-	get hasStateChangedListeners() {
-		return this._stateChangedListenerCount > 0;
+	/**
+	* 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;
+		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);
+	}
+	/**
+	* An entry may be disposed only when nothing owns it: no public refs, no
+	* `depend()` dependents, and not keepAlive. Every dispose decision goes
+	* through here so `release()` and `_releaseDependent` cannot disagree.
+	*/
+	_isUnowned(Type, entry) {
+		return this._hasNoOwners(entry) && !isKeepAliveClass(Type);
+	}
+	/**
+	* Pure ownership: refs plus `depend()` dependents, with no keepAlive term.
+	* `_isUnowned` is "may be disposed"; this is "nothing is using it", which is
+	* what the activation lifecycle keys off — a keepAlive instance still
+	* deactivates when its last owner goes.
+	*/
+	_hasNoOwners(entry) {
+		return entry.refs.size === 0 && (entry.dependents === void 0 || entry.dependents.size === 0);
+	}
+	/**
+	* Single funnel for the 0↔1 ownership transition. `SET_ACTIVE` is idempotent,
+	* so every acquire/release path can call this unconditionally rather than
+	* each computing the edge itself. Emits `activated`/`deactivated` for
+	* plugins to observe the same transition `onActivate`/`onDeactivate` expose
+	* to bloc authors — after `SET_ACTIVE` has already run the instance's own
+	* hook, so plugins always see a container that has finished reacting.
+	*/
+	_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);
+	}
+	/**
+	* Record that `dependent` resolved `Type` at `key`, so the edge can be
+	* released on the owner's disposal. Keyed per resolved key, not per type:
+	* one `depend()` handle resolves a distinct key for every `args` it is
+	* called with, and all of them must be swept.
+	*/
+	_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);
+	}
+	/**
+	* 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 id = container._instanceId;
+		if (id === void 0) return false;
+		const entry = this._entryById.get(id);
+		if (entry === void 0 || entry.instance !== container) return false;
+		this.instancesByConstructor.get(Type)?.delete(entry.key);
+		this._entryById.delete(id);
+		return true;
+	}
+	/**
+	* 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 (this._isUnowned(Type, entry)) {
+			if (!entry.instance.$blac.disposed) entry.instance.dispose();
+			return;
+		}
+		this._syncActivation(entry);
 	}
 	/**
 	* Register a type for lifecycle event tracking
@@ -569,9 +422,7 @@ var StateContainerRegistry = class {
 	* @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);
+		if (this.types.has(constructor)) throw new Error(`${BLAC_ERROR_PREFIX} Type "${getBlacName(constructor)}" is already registered`);
 		this.registerType(constructor);
 	}
 	ensureInstancesMap(Type) {
@@ -586,7 +437,7 @@ var StateContainerRegistry = class {
 	* Get the instances Map for a specific class (public API for stats/debugging)
 	*/
 	getInstancesMap(Type) {
-		return this.instancesByConstructor.get(Type) || /* @__PURE__ */ new Map();
+		return this.instancesByConstructor.get(Type) || EMPTY_INSTANCES_MAP;
 	}
 	/**
 	* Directly insert an instance entry into the registry without going through
@@ -603,10 +454,13 @@ var StateContainerRegistry = class {
 		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, {
+		const entry = {
 			instance,
+			key: instanceKey,
 			refs
-		});
+		};
+		instances.set(instanceKey, entry);
+		this._entryById.set(instance.$blac.id, entry);
 	}
 	/**
 	* Resolve the storage key for an instance. This is the single source of truth
@@ -614,7 +468,7 @@ var StateContainerRegistry = class {
 	* 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.
+	* 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
@@ -655,20 +509,19 @@ var StateContainerRegistry = class {
 	*   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 - Acquisition options: `canCreate` (create when absent,
+	*   default true), `countRef` (add a reference, default true), `refId`
+	*   (named reference for debugging, auto-generated when omitted),
+	*   `dependent` — the `depend()`-owner resolving this instance, recorded so
+	*   its dependent edge is released on the owner's disposal — and
+	*   `sweepIfUnowned`, for callers that create speculatively and claim
+	*   ownership later (see {@link _scheduleSweep}).
 	* @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) {
@@ -676,9 +529,9 @@ var StateContainerRegistry = class {
 			entry = void 0;
 		}
 		if (entry) {
-			if (process.env.NODE_ENV !== "production" && args !== void 0 && entry.args !== void 0) {
+			if (IS_DEV && args !== void 0 && entry.args !== void 0) {
 				const incomingKey = structuralKey(args);
-				const storedKey = structuralKey(entry.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) {
@@ -687,10 +540,19 @@ var StateContainerRegistry = class {
 				this.assertRefLimit(Type, resolvedKey, entry.refs.size);
 				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);
 			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 config = {
+			instanceId: resolvedKey,
+			args
+		};
 		const instance = new Type();
 		instance[INIT_CONFIG](config);
 		const initialRefs = /* @__PURE__ */ new Map();
@@ -699,16 +561,45 @@ var StateContainerRegistry = class {
 			initialRefId = options.refId ?? `_auto_${this._autoRefIdCounter++}`;
 			initialRefs.set(initialRefId, 1);
 		}
-		instances.set(resolvedKey, {
+		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._entryById.set(instance.$blac.id, newEntry);
 		this.registerType(Type);
 		if (initialRefId) this.emit("refAcquired", instance, initialRefId);
+		this._syncActivation(newEntry);
+		if (options.sweepIfUnowned && this._hasNoOwners(newEntry)) this._scheduleSweep(Type, newEntry);
 		return instance;
 	}
 	/**
+	* Speculative creates (`useBloc`'s render-time create) leak forever when the
+	* render is discarded or never commits — SSR has no commit at all, so nothing
+	* ever claims ownership. Sweep at the end of the microtask unless the entry
+	* gained an owner or is keepAlive.
+	*
+	* Opt-in, not automatic: a bare `ensure()` hands the instance to a caller
+	* that legitimately holds it without a ref, and sweeping those would make
+	* `ensure` unusable across an `await`.
+	*/
+	_scheduleSweep(Type, entry) {
+		queueMicrotask(() => {
+			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);
+		});
+	}
+	/**
 	* Borrow an existing instance without adding a ref (borrowing semantics).
 	* Tracks cross-bloc dependency for reactive updates.
 	*
@@ -718,7 +609,7 @@ var StateContainerRegistry = class {
 	* @returns The state container instance
 	* @throws Error if instance doesn't exist
 	*/
-	borrow(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+	borrow(Type, instanceKey = DEFAULT_STRUCTURAL_KEY) {
 		return this.acquire(Type, instanceKey, {
 			canCreate: false,
 			countRef: false
@@ -733,7 +624,7 @@ var StateContainerRegistry = class {
 	* @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) {
+	borrowSafe(Type, instanceKey = DEFAULT_STRUCTURAL_KEY) {
 		try {
 			return {
 				error: null,
@@ -779,7 +670,7 @@ var StateContainerRegistry = class {
 	* @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) {
+	release(Type, instanceKey = DEFAULT_STRUCTURAL_KEY, forceDispose = false, refId) {
 		const instances = this.ensureInstancesMap(Type);
 		const entry = instances.get(instanceKey);
 		if (!entry) return;
@@ -804,20 +695,12 @@ var StateContainerRegistry = class {
 			}
 		}
 		if (releasedRefId) this.emit("refReleased", entry.instance, releasedRefId);
-		const keepAlive = isKeepAliveClass(Type);
-		if (entry.refs.size === 0 && !keepAlive) {
-			const deps = entry.instance.$blac.dependencies;
+		if (this._isUnowned(Type, entry)) {
 			if (!entry.instance.$blac.disposed) entry.instance.dispose();
 			instances.delete(instanceKey);
-			for (const [DepType, depKey] of deps) {
-				const depInstances = this.ensureInstancesMap(DepType);
-				const depEntry = depInstances.get(depKey);
-				if (depEntry && depEntry.refs.size === 0 && !isKeepAliveClass(DepType) && !depEntry.instance.$blac.disposed) {
-					depEntry.instance.dispose();
-					depInstances.delete(depKey);
-				}
-			}
+			return;
 		}
+		this._syncActivation(entry);
 	}
 	/**
 	* Get all instances of a specific type.
@@ -827,7 +710,7 @@ var StateContainerRegistry = class {
 	getAll(Type) {
 		const instances = this.ensureInstancesMap(Type);
 		const result = [];
-		for (const entry of instances.values()) result.push(entry.instance);
+		for (const entry of instances.values()) if (!entry.instance.$blac.disposed) result.push(entry.instance);
 		return result;
 	}
 	/**
@@ -864,7 +747,7 @@ var StateContainerRegistry = class {
 	* @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) {
+	getRefCount(Type, instanceKey = DEFAULT_STRUCTURAL_KEY) {
 		return this.ensureInstancesMap(Type).get(instanceKey)?.refs.size ?? 0;
 	}
 	/**
@@ -875,13 +758,23 @@ var StateContainerRegistry = class {
 	* @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) {
+	getRefIds(Type, instanceKey = DEFAULT_STRUCTURAL_KEY) {
 		const instances = this.instancesByConstructor.get(Type);
 		if (!instances) return [];
 		const entry = instances.get(instanceKey);
 		return entry ? Array.from(entry.refs.keys()) : [];
 	}
 	/**
+	* Get all active reference IDs for an instance by its `$blac.id`, without
+	* needing the owning Type. Used by `PluginContext.getRefIds`.
+	* @param instanceId - The instance's `$blac.id`
+	* @returns Array of ref ID strings (empty if instance doesn't exist)
+	*/
+	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`.
@@ -889,7 +782,7 @@ var StateContainerRegistry = class {
 	* @param instanceKey - Pre-resolved instance key (defaults to 'default')
 	* @returns true if instance exists
 	*/
-	hasInstance(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+	hasInstance(Type, instanceKey = DEFAULT_STRUCTURAL_KEY) {
 		return this.ensureInstancesMap(Type).has(instanceKey);
 	}
 	/**
@@ -901,7 +794,6 @@ var StateContainerRegistry = class {
 	clearAll() {
 		for (const Type of this.types) this.clear(Type);
 		this.types.clear();
-		this.registeredTypeNames.clear();
 	}
 	/**
 	* Get registry statistics for debugging.
@@ -936,9 +828,11 @@ var StateContainerRegistry = class {
 	* @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}'`);
+		let instance = this.listeners.get(event);
+		if (!instance) {
+			instance = /* @__PURE__ */ new Set();
+			this.listeners.set(event, instance);
+		}
 		instance.add(listener);
 		if (event === "stateChanged") this._stateChangedListenerCount++;
 		return () => {
@@ -971,6 +865,15 @@ var StateContainerRegistry = class {
 			newState
 		]);
 	}
+	/**
+	* Deliver one event per emit, in order — deliberately NOT coalesced.
+	*
+	* This is a transition log: devtools, time-travel debugging and perf
+	* monitoring need every intermediate `prev`/`next`, which coalescing would
+	* destroy. The plugin `onStateChange` bridge is the coalesced, `PathSet`-
+	* carrying lane (see `PluginManager.setupLifecycleHooks`); the two differ on
+	* purpose, so a listener picks the lane that matches what it needs.
+	*/
 	flushStateChanged() {
 		const pending = this._pendingStateChanges;
 		this._pendingStateChanges = null;
@@ -980,19 +883,9 @@ var StateContainerRegistry = class {
 };
 /**
 * Global default registry instance
+* @public
 */
 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,
@@ -1012,10 +905,16 @@ Object.defineProperty(exports, "INIT_CONFIG", {
 		return INIT_CONFIG;
 	}
 });
-Object.defineProperty(exports, "PluginManager", {
+Object.defineProperty(exports, "IS_DEV", {
+	enumerable: true,
+	get: function() {
+		return IS_DEV;
+	}
+});
+Object.defineProperty(exports, "ON_DISPOSE", {
 	enumerable: true,
 	get: function() {
-		return PluginManager;
+		return ON_DISPOSE;
 	}
 });
 Object.defineProperty(exports, "REMOVE_DEPS_OWNER", {
@@ -1024,12 +923,24 @@ Object.defineProperty(exports, "REMOVE_DEPS_OWNER", {
 		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() {
@@ -1042,16 +953,16 @@ Object.defineProperty(exports, "getBlacConfig", {
 		return getBlacConfig;
 	}
 });
-Object.defineProperty(exports, "getClassEquality", {
+Object.defineProperty(exports, "getBlacName", {
 	enumerable: true,
 	get: function() {
-		return getClassEquality;
+		return getBlacName;
 	}
 });
-Object.defineProperty(exports, "getPluginManager", {
+Object.defineProperty(exports, "getClassEquality", {
 	enumerable: true,
 	get: function() {
-		return getPluginManager;
+		return getClassEquality;
 	}
 });
 Object.defineProperty(exports, "globalRegistry", {
@@ -1085,4 +996,4 @@ Object.defineProperty(exports, "shallowEqualState", {
 	}
 });
 
-//# sourceMappingURL=StateContainerRegistry-D9BIRjwv.cjs.map
+//# sourceMappingURL=StateContainerRegistry-MkT0W4C2.cjs.map