@blac/core 2.0.21 → 2.0.22

package/dist/ensure-BjhbDW8Z.cjs

@@ -0,0 +1,761 @@
+const require_StateContainerRegistry = require("./StateContainerRegistry-141uHhtF.cjs");
+let _dirtytalk_structural = require("@dirtytalk/structural");
+//#region src/utils/idGenerator.ts
+/**
+* Centralized ID Generation
+*
+* Provides consistent, collision-resistant ID generation for all BlaC subsystems.
+* Uses timestamp + counter + random suffix for uniqueness.
+*/
+/**
+* Generate simple ID with timestamp and random (no counter tracking)
+*
+* Format: `${prefix}:${timestamp}_${random}`
+*
+* @param prefix - Prefix for the ID
+* @returns Branded ID string
+*
+* @example
+* ```ts
+* const id = generateSimpleId('CounterBloc');
+* // Returns: "CounterBloc:1698765432100_a3k9d7f2q"
+* ```
+*/
+function generateSimpleId(prefix, affix) {
+	if (affix) return `${prefix}:${affix}`;
+	return `${prefix}:${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+}
+//#endregion
+//#region src/registry/config.ts
+let _registry = require_StateContainerRegistry.globalRegistry;
+/**
+* @public
+*/
+function getRegistry() {
+	return _registry;
+}
+/**
+* @public
+*/
+function setRegistry(registry) {
+	_registry = registry;
+}
+/**
+* @public
+*/
+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
+* meta tests. Intentionally NOT re-exported from the package barrel.
+*/
+const META_BRAND = Symbol("blac.meta");
+const EMPTY_DEPS = /* @__PURE__ */ new Map();
+/**
+* Build the frozen, branded `$blac` meta object for a container.
+*
+* Called from a `StateContainer` field initializer (`$blac = createMeta(this)`).
+* Only the back-reference is captured at this point; every getter/method reads
+* the container's `_`-private fields lazily on access, so field-initializer
+* ordering relative to those private fields is irrelevant.
+*
+* The getters close over `container` (the real instance), never over a
+* `this`-receiver — this is what keeps `$blac` reads safe through
+* `buildTrackedProxy`.
+*/
+function createMeta(container) {
+	const c = container;
+	const meta = {
+		get name() {
+			return c._name;
+		},
+		get id() {
+			return c._instanceId ??= generateSimpleId(require_StateContainerRegistry.getBlacName(c.constructor), "main");
+		},
+		get debug() {
+			return c._debug;
+		},
+		get createdAt() {
+			return c._createdAt;
+		},
+		get disposed() {
+			return c._disposed;
+		},
+		get dependencies() {
+			return c._dependencies ?? EMPTY_DEPS;
+		},
+		hydration: Object.freeze({
+			get status() {
+				return c._hydrationStatus;
+			},
+			get error() {
+				return c._hydrationError;
+			},
+			get isHydrated() {
+				return c._hydrationStatus === "hydrated";
+			},
+			get changedWhileHydrating() {
+				return c._changedWhileHydrating;
+			},
+			begin() {
+				c._beginHydration();
+			},
+			apply(next) {
+				return c._applyHydratedState(next);
+			},
+			finish() {
+				c._finishHydration();
+			},
+			fail(error) {
+				c._failHydration(error);
+			},
+			wait() {
+				return c._waitForHydration();
+			}
+		})
+	};
+	Object.defineProperty(meta, META_BRAND, {
+		value: true,
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	return Object.freeze(meta);
+}
+//#endregion
+//#region src/core/StateContainer.ts
+/**
+* Brand symbol carried (non-enumerable) on every handle returned by
+* `depend()`. Framework adapters (`@blac/react`) use this to detect handles
+* inside a tracked-proxy and swap in a session-bound wrapper.
+*
+* @internal — exported for `@blac/react`; not part of the public API.
+*/
+const DEP_BRAND = Symbol("blac.depHandle");
+/**
+* Shallow per-key `Object.is` comparison of two plain records. Keys are
+* considered: a key present in one but not the other (regardless of value)
+* makes the records unequal. Used to detect real deps changes.
+*/
+function shallowEqualRecord(a, b) {
+	if (a === b) return true;
+	const aKeys = Object.keys(a);
+	if (aKeys.length !== Object.keys(b).length) return false;
+	for (const key of aKeys) {
+		if (!(key in b)) return false;
+		if (!Object.is(a[key], b[key])) return false;
+	}
+	return true;
+}
+/**
+* BlaC's lifecycle/identity/dependency layer on top of `StructuralContainer`.
+*
+* StructuralContainer provides:
+*   - `state` getter
+*   - `emit` / `patch` / `update` (path-tracked, microtask-flushed)
+*   - `channel` (the underlying `DirtyChannel`)
+*   - `registerConsumerPaths` / `unregisterConsumer` (for fine-grained consumers)
+*   - per-class `PathInterner`
+*
+* StateContainer layers on:
+*   - identity / lifecycle / hydration (exposed via `$blac: BlacMeta`)
+*   - cross-bloc deps (`depend()`, `$blac.dependencies`)
+*   - per-consumer deps slices (`APPLY_DEPS` / `REMOVE_DEPS_OWNER` / `onDepsChanged`)
+*   - registry integration (config-driven equality, emit-rate circuit breaker)
+*
+* Subscribers can attach via:
+*   - `onSystemEvent('stateChanged' | 'dispose' | 'hydrationChanged', cb)` —
+*     coarse lifecycle events.
+*   - `this.channel.subscribe(interest, cb)` — path-scoped.
+*/
+var StateContainer = class extends _dirtytalk_structural.StructuralContainer {
+	static {
+		this.__excludeFromDevTools = false;
+	}
+	get deps() {
+		return this._deps;
+	}
+	/**
+	* @internal Apply one owner's (consumer's) deps slice. Shallow-merges the
+	* slice, reconciles keys the owner dropped since its last apply (other
+	* owners' keys untouched), dev-warns on cross-owner key collisions, then
+	* recomputes the merged view and fires onDepsChanged if it changed.
+	*
+	* Idempotent: re-applying an identical slice for the same owner is a no-op.
+	*/
+	[require_StateContainerRegistry.APPLY_DEPS](ownerId, slice) {
+		if (this._disposed) return;
+		const owners = this._depsByOwner ??= /* @__PURE__ */ new Map();
+		const prevSlice = owners.get(ownerId);
+		if (prevSlice && shallowEqualRecord(prevSlice, slice)) return;
+		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`);
+		}
+		owners.set(ownerId, { ...slice });
+		this.reconcileDeps();
+	}
+	/**
+	* @internal Withdraw an owner's entire deps slice (consumer unmounted).
+	*/
+	[require_StateContainerRegistry.REMOVE_DEPS_OWNER](ownerId) {
+		if (this._disposed) return;
+		if (!this._depsByOwner?.delete(ownerId)) return;
+		this.reconcileDeps();
+	}
+	/**
+	* @internal Subscribe to this instance's own disposal. Delegates to the
+	* per-instance `'dispose'` system event — used by `watch()` in place of
+	* filtering the global registry `'disposed'` event.
+	*/
+	[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 = {};
+		if (this._depsByOwner) for (const slice of this._depsByOwner.values()) Object.assign(next, slice);
+		for (const key of Object.keys(prev)) if (!(key in next)) next[key] = void 0;
+		if (shallowEqualRecord(prev, next)) return;
+		this._deps = next;
+		this.onDepsChanged(next, prev);
+		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;
+	}
+	/**
+	* Declare a cross-bloc dependency. Returns a branded handle with two
+	* accessors — the dep instance is resolved against the registry on each call,
+	* which keeps the surface immune to dep-instance churn:
+	*
+	* - `handle.track(options?)` — reactive read. Returns `[state, instance]`.
+	*   Inside a getter reached through the React proxy this subscribes the
+	*   reading component to the dep's changes (base impl: live, no subscription).
+	* - `handle.untracked(options?)` — returns the live instance with no tracking,
+	*   for imperative method calls and one-off reads.
+	*
+	* `defaultArgs` resolves the dep instance when an accessor is called without
+	* its own `args`; per-call `options.args` overrides it and can derive from
+	* current state. This does NOT auto-resubscribe outside the React proxy;
+	* non-React consumers needing updates should subscribe explicitly.
+	*/
+	depend(Type, defaultArgs) {
+		if (!this._dependencies) this._dependencies = /* @__PURE__ */ new Map();
+		this._dependencies.set(Type, this._registry.resolveKey(Type, void 0, defaultArgs));
+		const resolve = (args) => {
+			const effectiveArgs = args ?? defaultArgs;
+			const key = this._registry.resolveKey(Type, void 0, effectiveArgs);
+			return this._registry.acquire(Type, key, {
+				canCreate: true,
+				countRef: false,
+				args: effectiveArgs,
+				dependent: this
+			});
+		};
+		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];
+			},
+			untracked: (options) => resolve(options?.args)
+		};
+		Object.defineProperty(handle, DEP_BRAND, {
+			value: {
+				Type,
+				defaultArgs
+			},
+			enumerable: false,
+			writable: false,
+			configurable: false
+		});
+		return handle;
+	}
+	constructor(initialState, options) {
+		super(initialState, options);
+		this._depsByOwner = null;
+		this._deps = {};
+		this._disposed = false;
+		this._hydrationStatus = "idle";
+		this._changedWhileHydrating = false;
+		this._hydrationPromise = null;
+		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._pendingChange = null;
+		this._bridgeUnsub = null;
+		this._registry = getRegistry();
+		this._equalityFn = require_StateContainerRegistry.getBlacConfig().equality;
+		this._name = require_StateContainerRegistry.getBlacName(this.constructor);
+		this._debug = false;
+		this._createdAt = Date.now();
+		this.$blac = createMeta(this);
+		this.onSystemEvent = (event, handler) => {
+			let handlers = this._systemEventHandlers.get(event);
+			if (!handlers) {
+				handlers = /* @__PURE__ */ new Set();
+				this._systemEventHandlers.set(event, handlers);
+			}
+			handlers.add(handler);
+			if (event === "stateChanged" && this._bridgeUnsub === null) this._bridgeUnsub = this.channel.subscribe(() => _dirtytalk_structural.ALL_PATHS, () => this._drainPending());
+			return () => {
+				handlers?.delete(handler);
+				if (event === "stateChanged" && handlers?.size === 0) {
+					this._bridgeUnsub?.();
+					this._bridgeUnsub = null;
+					this._pendingChange = null;
+				}
+			};
+		};
+	}
+	/**
+	* Called once after construction with the args passed at acquire time, before the first
+	* state snapshot is read by any consumer. Override to seed args-derived state (via
+	* this.emit(...)) or kick off loads.
+	*/
+	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()`
+	* once. See {@link INIT_CONFIG}.
+	*/
+	[require_StateContainerRegistry.INIT_CONFIG](config) {
+		this._config = { ...config };
+		this._name = this._config.name || require_StateContainerRegistry.getBlacName(this.constructor);
+		this._debug = this._config.debug ?? false;
+		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;
+		if (!this._initCalled) {
+			this._initCalled = true;
+			this.init(this._config.args);
+		}
+		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.`);
+		}
+	}
+	dispose() {
+		if (this._disposed) return;
+		if (this._debug) console.log(`[${this._name}] Disposing...`);
+		if (this._depsByOwner) {
+			this._depsByOwner.clear();
+			this.reconcileDeps();
+		}
+		this._disposed = true;
+		if (this._hydrationStatus === "hydrating") this._failHydration(/* @__PURE__ */ new Error(`Hydration cancelled because ${this._name} was disposed`));
+		this.emitSystemEvent("dispose", void 0);
+		this._bridgeUnsub?.();
+		this._bridgeUnsub = null;
+		this._abortActivation();
+		this._systemEventHandlers.clear();
+		this._pendingChange = null;
+		this._registry.emit("disposed", this);
+		super.dispose();
+		if (this._debug) console.log(`[${this._name}] Disposed successfully`);
+	}
+	emit(next) {
+		this.applyState(next, "default");
+	}
+	/**
+	* Override of `StructuralContainer.patch` that routes through the
+	* StateContainer concerns: disposed guard, dev-only emit-rate check,
+	* `_changedWhileHydrating` flag, pending-change capture (so `stateChanged`
+	* system events see the merged prev/next), and the registry-level
+	* `stateChanged` notification. We still call
+	* `super.patch` so path-marking semantics (the whole point of patch) are
+	* preserved.
+	*/
+	patch(partial) {
+		if (this._disposed) {
+			this._warnDisposedMutation("patch");
+			return;
+		}
+		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._bridgeUnsub !== null) if (this._pendingChange) this._pendingChange.next = next;
+		else this._pendingChange = {
+			prev,
+			next
+		};
+		if (this._registry.hasStateChangedListeners) this._registry.notifyStateChanged(this, prev, next);
+	}
+	applyState(next, source) {
+		if (this._disposed) {
+			this._warnDisposedMutation("emit");
+			return;
+		}
+		const prev = this.state;
+		if (prev === next) return;
+		if (this._equalityFn(prev, next)) return;
+		if (require_StateContainerRegistry.IS_DEV) this._checkEmitRate();
+		if (this._hydrationStatus === "hydrating" && source !== "hydration") this._changedWhileHydrating = true;
+		if (this._bridgeUnsub !== null) if (this._pendingChange) this._pendingChange.next = next;
+		else this._pendingChange = {
+			prev,
+			next
+		};
+		super.emit(next);
+		if (this._registry.hasStateChangedListeners) this._registry.notifyStateChanged(this, prev, next);
+	}
+	/**
+	* Called by the channel-bridge subscriber on each flush. Drains the
+	* pending change (if any) into the 'stateChanged' system event.
+	* No pending change == flush from a no-op patch == skip.
+	*/
+	_drainPending() {
+		const pending = this._pendingChange;
+		if (!pending) return;
+		this._pendingChange = null;
+		const handlers = this._systemEventHandlers.get("stateChanged");
+		if (handlers && handlers.size > 0) {
+			const payload = {
+				state: pending.next,
+				previousState: pending.prev
+			};
+			let count = 0;
+			const size = handlers.size;
+			for (const handler of handlers) {
+				if (++count > size) break;
+				try {
+					handler(payload);
+				} catch (error) {
+					console.error(`[${this._name}] Error in system event handler:`, error);
+				}
+			}
+		}
+	}
+	_beginHydration() {
+		if (this._disposed) throw new Error(`Cannot begin hydration for disposed container ${this._name}`);
+		this._changedWhileHydrating = false;
+		this._hydrationError = void 0;
+		this._hydrationPromise = null;
+		this._resolveHydrationPromise = void 0;
+		this._rejectHydrationPromise = void 0;
+		this._hydrationPromiseSettled = false;
+		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) {
+			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;
+	}
+	_finishHydration() {
+		if (this._hydrationStatus !== "hydrating") {
+			if (this._hydrationStatus === "hydrated") return;
+			if (this._hydrationStatus === "error") this.ensureHydrationPromise();
+		}
+		this.setHydrationStatus("hydrated");
+		this.resolveHydration();
+	}
+	_failHydration(error) {
+		const err = error instanceof Error ? error : /* @__PURE__ */ new Error(`Hydration failed: ${String(error)}`);
+		this._hydrationError = err;
+		this.setHydrationStatus("error", err);
+		this.rejectHydration(err);
+	}
+	_waitForHydration() {
+		if (this._hydrationStatus === "idle" || this._hydrationStatus === "hydrated") return Promise.resolve();
+		if (this._hydrationStatus === "error") return Promise.reject(this._hydrationError ?? /* @__PURE__ */ new Error(`Hydration failed for container ${this._name}`));
+		return this.ensureHydrationPromise();
+	}
+	setHydrationStatus(status, error) {
+		const previousStatus = this._hydrationStatus;
+		this._hydrationStatus = status;
+		this._hydrationError = error;
+		this.emitSystemEvent("hydrationChanged", {
+			status,
+			previousStatus,
+			error,
+			changedWhileHydrating: this._changedWhileHydrating
+		});
+		this._registry.emit("hydrationChanged", this, status, previousStatus);
+	}
+	ensureHydrationPromise() {
+		if (!this._hydrationPromise || this._hydrationPromiseSettled) {
+			this._hydrationPromiseSettled = false;
+			this._hydrationPromise = new Promise((resolve, reject) => {
+				this._resolveHydrationPromise = () => {
+					if (this._hydrationPromiseSettled) return;
+					this._hydrationPromiseSettled = true;
+					resolve();
+				};
+				this._rejectHydrationPromise = (error) => {
+					if (this._hydrationPromiseSettled) return;
+					this._hydrationPromiseSettled = true;
+					reject(error);
+				};
+			});
+			this._hydrationPromise.catch(() => {});
+		}
+		return this._hydrationPromise;
+	}
+	resolveHydration() {
+		this._resolveHydrationPromise?.();
+	}
+	rejectHydration(error) {
+		this.ensureHydrationPromise();
+		this._rejectHydrationPromise?.(error);
+	}
+	emitSystemEvent(event, payload) {
+		const handlers = this._systemEventHandlers.get(event);
+		if (!handlers) return;
+		for (const handler of handlers) try {
+			handler(payload);
+		} catch (error) {
+			console.error(`[${this._name}] Error in system event handler:`, error);
+		}
+	}
+	/**
+	* Dev-only soft circuit breaker. Counts real state changes in a rolling 1s
+	* window and warns once if the rate exceeds `maxEmitsPerSecond` — the
+	* signature of a runaway loop (RAF/animation or emit-on-every-commit) pushing
+	* high-frequency data through state, which freezes subscribers/plugins.
+	*/
+	_checkEmitRate() {
+		const limit = require_StateContainerRegistry.getBlacConfig().maxEmitsPerSecond;
+		if (!(limit > 0) || !Number.isFinite(limit) || this._emitRateWarned) return;
+		const now = Date.now();
+		if (now - this._emitWindowStart >= 1e3) {
+			this._emitWindowStart = now;
+			this._emitCount = 1;
+			return;
+		}
+		this._emitCount++;
+		if (this._emitCount > limit) {
+			this._emitRateWarned = true;
+			console.warn(`[${this._name}] emitted more than ${limit} state changes in under a second. This is usually a runaway loop pushing high-frequency data through state (e.g. \`emit\`/\`patch\` inside a requestAnimationFrame loop, or an effect that emits on every render). It can freeze the app by saturating subscribers and plugins (logging/devtools). Keep high-frequency work imperative and emit only coarse/throttled state, or raise \`configureBlac({ maxEmitsPerSecond })\`. (This warning fires once.)`);
+		}
+	}
+};
+//#endregion
+//#region src/core/Cubit.ts
+/**
+* `Cubit<S>` is a `StateContainer<S>` that exposes mutation publicly.
+*
+* 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 {
+	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
+/**
+* Ensure an instance exists without taking ownership (no ref added). Instance
+* identity is derived purely from `args`, matching `acquire`.
+*/
+function ensure(BlocClass, opts) {
+	const registry = getRegistry();
+	const key = registry.resolveKey(BlocClass, void 0, opts?.args);
+	return registry.ensure(BlocClass, key, opts?.args);
+}
+//#endregion
+Object.defineProperty(exports, "Cubit", {
+	enumerable: true,
+	get: function() {
+		return Cubit;
+	}
+});
+Object.defineProperty(exports, "DEP_BRAND", {
+	enumerable: true,
+	get: function() {
+		return DEP_BRAND;
+	}
+});
+Object.defineProperty(exports, "StateContainer", {
+	enumerable: true,
+	get: function() {
+		return StateContainer;
+	}
+});
+Object.defineProperty(exports, "acquire", {
+	enumerable: true,
+	get: function() {
+		return acquire;
+	}
+});
+Object.defineProperty(exports, "ensure", {
+	enumerable: true,
+	get: function() {
+		return ensure;
+	}
+});
+Object.defineProperty(exports, "getRegistry", {
+	enumerable: true,
+	get: function() {
+		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, "setRegistry", {
+	enumerable: true,
+	get: function() {
+		return setRegistry;
+	}
+});
+
+//# sourceMappingURL=ensure-BjhbDW8Z.cjs.map