@blac/core 2.1.0 → 2.1.1

package/dist/ensure-Bi_yXk6f.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-Bi_yXk6f.js","names":[],"sources":["../src/registry/acquire.ts","../src/registry/ensure.ts"],"sourcesContent":["import { getRegistry } from './config';\nimport type {\n  ExtractArgs,\n  StateContainerConstructor,\n} from '../types/utilities';\n\n/**\n * Acquire an instance with ref tracking (ownership semantics). Instance\n * identity is derived purely from `args` (via the class's `static key(args)`,\n * a structural hash of `args`, or the default sentinel when there are none).\n *\n * @param BlocClass - The StateContainer class constructor\n * @param opts - `args` derives the instance key; `refId` names the reference\n *   for debugging and is auto-generated when omitted.\n */\nexport function acquire<T extends StateContainerConstructor>(\n  BlocClass: T,\n  opts?: { args?: ExtractArgs<T>; refId?: string },\n): InstanceType<T> {\n  const registry = getRegistry();\n  const key = registry.resolveKey(BlocClass, undefined, opts?.args);\n  return registry.acquire(BlocClass, key, {\n    canCreate: true,\n    countRef: true,\n    refId: opts?.refId,\n    args: opts?.args,\n  });\n}\n\n/**\n * Resolve the storage key an instance would be acquired under, given its\n * construction `args`. This is the canonical key-computation path. Callers that\n * both acquire and release against the `@internal` registry tier (e.g.\n * `@blac/react` `useBloc`) must use this once and pass the same resolved key to\n * both, so the ref is dropped under the key it was taken.\n */\nexport function resolveInstanceKey<T extends StateContainerConstructor>(\n  BlocClass: T,\n  args?: ExtractArgs<T>,\n): string {\n  return getRegistry().resolveKey(BlocClass, undefined, args);\n}\n","import { getRegistry } from './config';\nimport type {\n  ExtractArgs,\n  StateContainerConstructor,\n} from '../types/utilities';\n\n/**\n * Ensure an instance exists without taking ownership (no ref added). Instance\n * identity is derived purely from `args`, matching `acquire`.\n */\nexport function ensure<T extends StateContainerConstructor>(\n  BlocClass: T,\n  opts?: { args?: ExtractArgs<T> },\n): InstanceType<T> {\n  const registry = getRegistry();\n  const key = registry.resolveKey(BlocClass, undefined, opts?.args);\n  return registry.ensure(BlocClass, key, opts?.args);\n}\n"],"mappings":";;;;;;;;;;;AAeA,SAAgB,QACd,WACA,MACiB;CACjB,MAAM,WAAW,YAAY;CAC7B,MAAM,MAAM,SAAS,WAAW,WAAW,KAAA,GAAW,MAAM,IAAI;CAChE,OAAO,SAAS,QAAQ,WAAW,KAAK;EACtC,WAAW;EACX,UAAU;EACV,OAAO,MAAM;EACb,MAAM,MAAM;CACd,CAAC;AACH;;;;;;;;AASA,SAAgB,mBACd,WACA,MACQ;CACR,OAAO,YAAY,EAAE,WAAW,WAAW,KAAA,GAAW,IAAI;AAC5D;;;;;;;AC/BA,SAAgB,OACd,WACA,MACiB;CACjB,MAAM,WAAW,YAAY;CAC7B,MAAM,MAAM,SAAS,WAAW,WAAW,KAAA,GAAW,MAAM,IAAI;CAChE,OAAO,SAAS,OAAO,WAAW,KAAK,MAAM,IAAI;AACnD"}

package/dist/{ensure-r1C_7K6_.cjs → ensure-BjhbDW8Z.cjs}

@@ -1,5 +1,4 @@
-const require_StateContainerRegistry = require("./StateContainerRegistry-G81GcCRm.cjs");
-const require_config = require("./config-C1T6Jw7n.cjs");
+const require_StateContainerRegistry = require("./StateContainerRegistry-141uHhtF.cjs");
 let _dirtytalk_structural = require("@dirtytalk/structural");
 //#region src/utils/idGenerator.ts
 /**
@@ -27,83 +26,38 @@ function generateSimpleId(prefix, affix) {
 	return `${prefix}:${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
 }
 //#endregion
-//#region src/events.ts
+//#region src/registry/config.ts
+let _registry = require_StateContainerRegistry.globalRegistry;
 /**
-* Subscriber storage, keyed by REGISTRY INSTANCE rather than a field on
-* `StateContainerRegistry`. This gives registry-swap isolation (a test's
-* `withTestRegistry`/`blacTestSetup` scope gets an independent subscriber
-* set) for free, through machinery that already exists, with zero new
-* public surface on `StateContainerRegistry`.
+* @public
 */
-const busByRegistry = /* @__PURE__ */ new WeakMap();
-function defineEvent(name) {
-	return { name };
+function getRegistry() {
+	return _registry;
 }
 /**
-* @internal Bus scoped to an explicit registry — used by `StateContainer#on`
-* so a container always listens on the bus of the registry it belongs to,
-* not the ambient one. Not part of the public API.
+* @public
 */
-function onEventFor(registry, token, handler) {
-	let bus = busByRegistry.get(registry);
-	if (!bus) {
-		bus = /* @__PURE__ */ new Map();
-		busByRegistry.set(registry, bus);
-	}
-	let handlers = bus.get(token);
-	if (!handlers) {
-		handlers = /* @__PURE__ */ new Set();
-		bus.set(token, handlers);
-	}
-	handlers.add(handler);
-	const tokenMap = bus;
-	const handlerSet = handlers;
-	let removed = false;
-	return () => {
-		if (removed) return;
-		removed = true;
-		handlerSet.delete(handler);
-		if (handlerSet.size === 0) tokenMap.delete(token);
-	};
-}
-/** Subscribe on the ambient registry (`getRegistry()`). */
-function onEvent(token, handler) {
-	return onEventFor(require_config.getRegistry(), token, handler);
+function setRegistry(registry) {
+	_registry = registry;
 }
 /**
-* Dispatch `token` to every current subscriber on the ambient registry, in
-* registration order.
-*
-* Cost is O(subscribers for this token) — a token with no subscribers (or no
-* bus yet on this registry) returns immediately, never touching live
-* instances.
-*
-* Dispatch iterates a SNAPSHOT of the handler `Set`, so it is safe for a
-* handler to synchronously call `emitEvent`/`onEvent` re-entrantly: a nested
-* `emitEvent` for the same token completes against its own snapshot, and a
-* handler registered via `onEvent` during dispatch is NOT invoked for the
-* in-flight emit (it only sees emits that start after it subscribed).
-*
-* The variadic tuple means a `void`-payload token needs no second argument,
-* and a typed-payload token requires one. It wraps both sides in a tuple
-* (`[P] extends [void]`, not `void extends P`) because the naive form is true
-* for every `P` that `void` is assignable to — `unknown`, `any`, `number |
-* void` — which collapsed the tuple to `[]` and made their payload
-* un-passable. `any` is special-cased first so it accepts either form.
+* @public
 */
-function emitEvent(token, ...payload) {
-	const handlers = busByRegistry.get(require_config.getRegistry())?.get(token);
-	if (!handlers) return;
-	const value = payload[0];
-	for (const handler of Array.from(handlers)) try {
-		handler(value);
-	} catch (error) {
-		console.error(`${require_StateContainerRegistry.BLAC_ERROR_PREFIX} event handler error for '${token.name}':`, error);
-	}
+function getStats() {
+	return _registry.getStats();
 }
 //#endregion
 //#region src/core/meta.ts
 /**
+* `$blac` meta namespace for `StateContainer`.
+*
+* Getters/methods here close over the *real* container instance captured at
+* `createMeta` time rather than reading a `this`-receiver. `buildTrackedProxy`
+* no longer uses a `this`-Proxy (getters run with `this` = the real instance),
+* so ES `#private` is safe here now; the closure style is kept because it also
+* keeps this own, frozen property independent of the proxy entirely.
+*/
+/**
 * Non-enumerable brand carried on every `$blac` object produced by
 * {@link createMeta}. Used by the clobber guard in `StateContainer` to detect
 * a subclass class-field shadowing the base's own `$blac` property, and by the
@@ -130,7 +84,7 @@ function createMeta(container) {
 			return c._name;
 		},
 		get id() {
-			return c._instanceId;
+			return c._instanceId ??= generateSimpleId(require_StateContainerRegistry.getBlacName(c.constructor), "main");
 		},
 		get debug() {
 			return c._debug;
@@ -248,7 +202,7 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 		const owners = this._depsByOwner ??= /* @__PURE__ */ new Map();
 		const prevSlice = owners.get(ownerId);
 		if (prevSlice && shallowEqualRecord(prevSlice, slice)) return;
-		if (process.env.NODE_ENV !== "production") for (const key of Object.keys(slice)) for (const [otherOwner, otherSlice] of owners) {
+		if (require_StateContainerRegistry.IS_DEV) for (const key of Object.keys(slice)) for (const [otherOwner, otherSlice] of owners) {
 			if (otherOwner === ownerId) continue;
 			if (key in otherSlice && otherSlice[key] !== slice[key]) console.warn(`[${this._name}] multiple owners writing dep \`${String(key)}\`; last write wins`);
 		}
@@ -271,6 +225,34 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 	[require_StateContainerRegistry.ON_DISPOSE](handler) {
 		return this.onSystemEvent("dispose", handler);
 	}
+	/**
+	* @internal Drive the 0↔1 ownership transition. Idempotent: repeated calls
+	* with the same value are no-ops, so the registry can call it from every
+	* acquire/release without tracking edges itself.
+	*
+	* Returns which real transition (if any) just happened, so the registry can
+	* emit the matching `activated`/`deactivated` plugin event without exposing
+	* `_activation` itself — `'none'` for an idempotent no-op call.
+	*/
+	[require_StateContainerRegistry.SET_ACTIVE](active) {
+		if (this._disposed) return "none";
+		if (active === (this._activation !== null)) return "none";
+		if (active) {
+			this._activation = new AbortController();
+			this.onActivate(this._activation.signal);
+			return {
+				kind: "activated",
+				signal: this._activation.signal
+			};
+		}
+		this._abortActivation();
+		this.onDeactivate();
+		return "deactivated";
+	}
+	_abortActivation() {
+		this._activation?.abort();
+		this._activation = null;
+	}
 	reconcileDeps() {
 		const prev = this._deps;
 		const next = {};
@@ -282,6 +264,30 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 		this._registry.emit("depsChanged", this, prev, next);
 	}
 	onDepsChanged(_next, _prev) {}
+	get state() {
+		return this._stateOverride ?? super.state;
+	}
+	/**
+	* @internal Run `fn` with `state` reporting `tracked`, and with dep handles
+	* read off `this` routed through `onDepHandle`. Restored in `finally`, and
+	* nestable — getters reading other getters stay in tracked context.
+	*
+	* The dep hook lives here rather than in the adapter's proxy because getters
+	* now run with `this` = the real instance (so ES `#private` works), which
+	* means a `this.someDep` read never passes through the proxy's trap.
+	*/
+	[require_StateContainerRegistry.WITH_TRACKED_STATE](tracked, fn, onDepHandle) {
+		const prevState = this._stateOverride;
+		const prevHook = this._depHandleHook;
+		this._stateOverride = tracked;
+		this._depHandleHook = onDepHandle;
+		try {
+			return fn();
+		} finally {
+			this._stateOverride = prevState;
+			this._depHandleHook = prevHook;
+		}
+	}
 	get args() {
 		return this._config.args;
 	}
@@ -307,13 +313,6 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 		const resolve = (args) => {
 			const effectiveArgs = args ?? defaultArgs;
 			const key = this._registry.resolveKey(Type, void 0, effectiveArgs);
-			const edges = this._depEdges ??= /* @__PURE__ */ new Map();
-			let resolvedKeys = edges.get(Type);
-			if (resolvedKeys === void 0) {
-				resolvedKeys = /* @__PURE__ */ new Set();
-				edges.set(Type, resolvedKeys);
-			}
-			resolvedKeys.add(key);
 			return this._registry.acquire(Type, key, {
 				canCreate: true,
 				countRef: false,
@@ -323,6 +322,8 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 		};
 		const handle = {
 			track: (options) => {
+				const wrapped = this._depHandleHook?.(handle);
+				if (wrapped !== void 0 && wrapped !== handle) return wrapped.track(options);
 				const instance = resolve(options?.args);
 				return [instance.state, instance];
 			},
@@ -350,19 +351,18 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 		this._hydrationPromiseSettled = false;
 		this._config = {};
 		this._initCalled = false;
+		this._activation = null;
 		this._emitWindowStart = 0;
 		this._emitCount = 0;
 		this._emitRateWarned = false;
 		this._systemEventHandlers = /* @__PURE__ */ new Map();
 		this._dependencies = null;
-		this._depEdges = null;
 		this._pendingChange = null;
 		this._bridgeUnsub = null;
-		this._registry = require_config.getRegistry();
+		this._registry = getRegistry();
 		this._equalityFn = require_StateContainerRegistry.getBlacConfig().equality;
-		this._name = this.constructor.name;
+		this._name = require_StateContainerRegistry.getBlacName(this.constructor);
 		this._debug = false;
-		this._instanceId = generateSimpleId(this.constructor.name, "main");
 		this._createdAt = Date.now();
 		this.$blac = createMeta(this);
 		this.onSystemEvent = (event, handler) => {
@@ -371,42 +371,17 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 				handlers = /* @__PURE__ */ new Set();
 				this._systemEventHandlers.set(event, handlers);
 			}
-			const wasFirst = event === "stateChanged" && handlers.size === 0;
 			handlers.add(handler);
-			if (wasFirst) this._subscribeBridge();
-			let removed = false;
+			if (event === "stateChanged" && this._bridgeUnsub === null) this._bridgeUnsub = this.channel.subscribe(() => _dirtytalk_structural.ALL_PATHS, () => this._drainPending());
 			return () => {
-				if (removed) return;
-				removed = true;
 				handlers?.delete(handler);
-				if (event === "stateChanged" && (!handlers || handlers.size === 0)) {
+				if (event === "stateChanged" && handlers?.size === 0) {
 					this._bridgeUnsub?.();
 					this._bridgeUnsub = null;
 					this._pendingChange = null;
 				}
 			};
 		};
-		this.on = (token, handler) => {
-			if (this._disposed) return () => {};
-			const unsub = onEventFor(this._registry, token, handler);
-			this.onSystemEvent("dispose", unsub);
-			return unsub;
-		};
-	}
-	/**
-	* @internal Subscribe the channel bridge that turns flushes into
-	* 'stateChanged' system events. Interest is ALL_PATHS so we wake on every
-	* flush. Coalesced via `_pendingChange`: if no emit happened (e.g. a no-op
-	* patch), the bridge sees null and skips. Lazy: only subscribed while at
-	* least one 'stateChanged' handler exists.
-	*/
-	_subscribeBridge() {
-		if (this._bridgeUnsub) return;
-		this._bridgeUnsub = this.channel.subscribe(() => _dirtytalk_structural.ALL_PATHS, () => this._drainPending());
-	}
-	_hasStateChangedHandlers() {
-		const handlers = this._systemEventHandlers.get("stateChanged");
-		return !!handlers && handlers.size > 0;
 	}
 	/**
 	* Called once after construction with the args passed at acquire time, before the first
@@ -415,6 +390,24 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 	*/
 	init(_args) {}
 	/**
+	* Called when this instance goes from unowned to owned (first ref or first
+	* `depend()` dependent). Override to start work that should only run while
+	* something is actually using the instance — fetches, timers, listeners.
+	*
+	* `signal` aborts on the matching {@link onDeactivate} and on dispose, so
+	* async work started here can be cancelled without extra bookkeeping.
+	*
+	* Runs before the first `useBlocDeps` slice is applied, so `this.deps` is
+	* empty on first activation — use `onDepsChanged` for deps-driven work.
+	*/
+	onActivate(_signal) {}
+	/**
+	* Called when this instance goes from owned back to unowned while surviving
+	* in the registry (i.e. `keepAlive`). A disposed instance does NOT get this
+	* callback — `dispose()` is the teardown path for that case.
+	*/
+	onDeactivate() {}
+	/**
 	* @internal Framework-only configuration entry point (registry + testing
 	* helpers). Writes the `_`-private identity fields directly, resolves
 	* per-class equality, emits the registry `created` event, and runs `init()`
@@ -422,17 +415,17 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 	*/
 	[require_StateContainerRegistry.INIT_CONFIG](config) {
 		this._config = { ...config };
-		this._name = this._config.name || this.constructor.name;
+		this._name = this._config.name || require_StateContainerRegistry.getBlacName(this.constructor);
 		this._debug = this._config.debug ?? false;
-		this._instanceId = generateSimpleId(this.constructor.name, this._config.instanceId);
+		this._instanceId = generateSimpleId(require_StateContainerRegistry.getBlacName(this.constructor), this._config.instanceId);
 		const perClass = require_StateContainerRegistry.getClassEquality(this.constructor);
 		this._equalityFn = perClass ?? require_StateContainerRegistry.getBlacConfig().equality;
-		this._registry.emit("created", this);
 		if (!this._initCalled) {
 			this._initCalled = true;
 			this.init(this._config.args);
 		}
-		if (process.env.NODE_ENV !== "production") {
+		this._registry.emit("created", this);
+		if (require_StateContainerRegistry.IS_DEV) {
 			if (!this.$blac?.[META_BRAND]) console.warn(`[blac] ${this.constructor.name} appears to declare its own \`$blac\` member, which shadows the reserved meta namespace. \`$blac\` is reserved by StateContainer — remove the subclass field.`);
 		}
 	}
@@ -448,11 +441,12 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 		this.emitSystemEvent("dispose", void 0);
 		this._bridgeUnsub?.();
 		this._bridgeUnsub = null;
+		this._abortActivation();
 		this._systemEventHandlers.clear();
 		this._pendingChange = null;
 		this._registry.emit("disposed", this);
-		if (this._debug) console.log(`[${this._name}] Disposed successfully`);
 		super.dispose();
+		if (this._debug) console.log(`[${this._name}] Disposed successfully`);
 	}
 	emit(next) {
 		this.applyState(next, "default");
@@ -467,25 +461,17 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 	* preserved.
 	*/
 	patch(partial) {
-		if (this._disposed) throw new Error(`Cannot emit state from disposed container ${this._name}`);
-		const prev = this.state;
-		let hasKeys = false;
-		let allEqual = true;
-		for (const key in partial) {
-			hasKeys = true;
-			if (!Object.is(prev[key], partial[key])) {
-				allEqual = false;
-				break;
-			}
+		if (this._disposed) {
+			this._warnDisposedMutation("patch");
+			return;
 		}
-		if (!hasKeys) return;
-		if (allEqual) return;
-		if (process.env.NODE_ENV !== "production") this._checkEmitRate();
+		const prev = this.state;
 		super.patch(partial);
 		const next = this.state;
 		if (Object.is(prev, next)) return;
+		if (require_StateContainerRegistry.IS_DEV) this._checkEmitRate();
 		if (this._hydrationStatus === "hydrating") this._changedWhileHydrating = true;
-		if (this._hasStateChangedHandlers()) if (this._pendingChange) this._pendingChange.next = next;
+		if (this._bridgeUnsub !== null) if (this._pendingChange) this._pendingChange.next = next;
 		else this._pendingChange = {
 			prev,
 			next
@@ -493,13 +479,16 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 		if (this._registry.hasStateChangedListeners) this._registry.notifyStateChanged(this, prev, next);
 	}
 	applyState(next, source) {
-		if (this._disposed) throw new Error(`Cannot emit state from disposed container ${this._name}`);
+		if (this._disposed) {
+			this._warnDisposedMutation("emit");
+			return;
+		}
 		const prev = this.state;
 		if (prev === next) return;
 		if (this._equalityFn(prev, next)) return;
-		if (process.env.NODE_ENV !== "production") this._checkEmitRate();
+		if (require_StateContainerRegistry.IS_DEV) this._checkEmitRate();
 		if (this._hydrationStatus === "hydrating" && source !== "hydration") this._changedWhileHydrating = true;
-		if (this._hasStateChangedHandlers()) if (this._pendingChange) this._pendingChange.next = next;
+		if (this._bridgeUnsub !== null) if (this._pendingChange) this._pendingChange.next = next;
 		else this._pendingChange = {
 			prev,
 			next
@@ -545,9 +534,15 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 		this.ensureHydrationPromise();
 		this.setHydrationStatus("hydrating");
 	}
+	_warnDisposedMutation(op) {
+		if (require_StateContainerRegistry.IS_DEV) console.warn(`[blac] ${this._name}: ${op}() after dispose ignored. This usually means an async method resolved after the last consumer unmounted. Guard with \`if (this.$blac.disposed) return\` after each \`await\`, or abort the work from \`onSystemEvent('dispose', ...)\`.`);
+	}
 	_applyHydratedState(next) {
 		if (this._disposed) return false;
-		if (this._hydrationStatus !== "hydrating" || this._changedWhileHydrating) return false;
+		if (this._hydrationStatus !== "hydrating" || this._changedWhileHydrating) {
+			if (require_StateContainerRegistry.IS_DEV && this._changedWhileHydrating) console.warn(`[blac] ${this._name}: persisted state discarded because the container emitted while hydrating.`);
+			return false;
+		}
 		this.applyState(next, "hydration");
 		return true;
 	}
@@ -611,15 +606,10 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 	emitSystemEvent(event, payload) {
 		const handlers = this._systemEventHandlers.get(event);
 		if (!handlers) return;
-		const size = handlers.size;
-		let count = 0;
-		for (const handler of handlers) {
-			if (++count > size) break;
-			try {
-				handler(payload);
-			} catch (error) {
-				console.error(`[${this._name}] Error in system event handler:`, error);
-			}
+		for (const handler of handlers) try {
+			handler(payload);
+		} catch (error) {
+			console.error(`[${this._name}] Error in system event handler:`, error);
 		}
 	}
 	/**
@@ -647,19 +637,60 @@ var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
 //#endregion
 //#region src/core/Cubit.ts
 /**
-* `Cubit<S>` is a `StateContainer<S>` with `emit` / `patch` exposed as
-* public mutation surface. Today it adds nothing structurally beyond
-* `StateContainer` — both are inherited from the underlying
-* `StructuralContainer<S>`. Kept as a real class (not a type alias) because
-* downstream code does `instance instanceof Cubit` checks.
+* `Cubit<S>` is a `StateContainer<S>` that exposes mutation publicly.
 *
-* The class body is intentionally empty: a no-op `emit` override would
-* still go through `applyState`, and `patch` is inherited from
-* `StructuralContainer` (path-diffed, microtask-flushed). A caller that
-* wants "skip if no real change" patch semantics can wrap `patch`
-* themselves or call `emit` after a manual equality check.
+* That is the whole difference, and it is a real one: on `StateContainer`
+* `emit` / `patch` / `update` are `protected`, so a container mutates itself
+* from its own methods and callers go through the API it chooses to publish.
+* `Cubit` re-declares the three as `public` for the cases where a caller
+* legitimately drives state from outside — test helpers, devtools
+* time-travel, benchmarks.
+*
+* Reach for `StateContainer` when business logic should live in the class,
+* and `Cubit` when the caller owns the transitions.
 */
-var Cubit = class extends StateContainer {};
+var Cubit = class extends StateContainer {
+	emit(next) {
+		super.emit(next);
+	}
+	patch(partial) {
+		super.patch(partial);
+	}
+	update(fn) {
+		super.update(fn);
+	}
+};
+//#endregion
+//#region src/registry/acquire.ts
+/**
+* Acquire an instance with ref tracking (ownership semantics). Instance
+* identity is derived purely from `args` (via the class's `static key(args)`,
+* a structural hash of `args`, or the default sentinel when there are none).
+*
+* @param BlocClass - The StateContainer class constructor
+* @param opts - `args` derives the instance key; `refId` names the reference
+*   for debugging and is auto-generated when omitted.
+*/
+function acquire(BlocClass, opts) {
+	const registry = getRegistry();
+	const key = registry.resolveKey(BlocClass, void 0, opts?.args);
+	return registry.acquire(BlocClass, key, {
+		canCreate: true,
+		countRef: true,
+		refId: opts?.refId,
+		args: opts?.args
+	});
+}
+/**
+* Resolve the storage key an instance would be acquired under, given its
+* construction `args`. This is the canonical key-computation path. Callers that
+* both acquire and release against the `@internal` registry tier (e.g.
+* `@blac/react` `useBloc`) must use this once and pass the same resolved key to
+* both, so the ref is dropped under the key it was taken.
+*/
+function resolveInstanceKey(BlocClass, args) {
+	return getRegistry().resolveKey(BlocClass, void 0, args);
+}
 //#endregion
 //#region src/registry/ensure.ts
 /**
@@ -667,7 +698,7 @@ var Cubit = class extends StateContainer {};
 * identity is derived purely from `args`, matching `acquire`.
 */
 function ensure(BlocClass, opts) {
-	const registry = require_config.getRegistry();
+	const registry = getRegistry();
 	const key = registry.resolveKey(BlocClass, void 0, opts?.args);
 	return registry.ensure(BlocClass, key, opts?.args);
 }
@@ -690,29 +721,41 @@ Object.defineProperty(exports, "StateContainer", {
 		return StateContainer;
 	}
 });
-Object.defineProperty(exports, "defineEvent", {
+Object.defineProperty(exports, "acquire", {
 	enumerable: true,
 	get: function() {
-		return defineEvent;
+		return acquire;
 	}
 });
-Object.defineProperty(exports, "emitEvent", {
+Object.defineProperty(exports, "ensure", {
 	enumerable: true,
 	get: function() {
-		return emitEvent;
+		return ensure;
 	}
 });
-Object.defineProperty(exports, "ensure", {
+Object.defineProperty(exports, "getRegistry", {
 	enumerable: true,
 	get: function() {
-		return ensure;
+		return getRegistry;
+	}
+});
+Object.defineProperty(exports, "getStats", {
+	enumerable: true,
+	get: function() {
+		return getStats;
+	}
+});
+Object.defineProperty(exports, "resolveInstanceKey", {
+	enumerable: true,
+	get: function() {
+		return resolveInstanceKey;
 	}
 });
-Object.defineProperty(exports, "onEvent", {
+Object.defineProperty(exports, "setRegistry", {
 	enumerable: true,
 	get: function() {
-		return onEvent;
+		return setRegistry;
 	}
 });
 
-//# sourceMappingURL=ensure-r1C_7K6_.cjs.map
+//# sourceMappingURL=ensure-BjhbDW8Z.cjs.map