@blac/core 2.0.19 → 2.1.0

package/dist/ensure-BEeY5Ab7.js

@@ -0,0 +1,673 @@
+import { a as INIT_CONFIG, c as getClassEquality, f as BLAC_ERROR_PREFIX, g as getBlacConfig, i as APPLY_DEPS, o as ON_DISPOSE, s as REMOVE_DEPS_OWNER } from "./StateContainerRegistry-DL5Ai7wh.js";
+import { t as getRegistry } from "./config-ZVy_yFZ3.js";
+import { ALL_PATHS, StructuralContainer } from "@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/events.ts
+/**
+* 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`.
+*/
+const busByRegistry = /* @__PURE__ */ new WeakMap();
+function defineEvent(name) {
+	return { name };
+}
+/**
+* @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.
+*/
+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(getRegistry(), token, handler);
+}
+/**
+* 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 (`void extends P ? [] : [P]`) means a `void`-payload
+* token needs no second argument, and a typed-payload token requires one.
+*/
+function emitEvent(token, ...payload) {
+	const handlers = busByRegistry.get(getRegistry())?.get(token);
+	if (!handlers) return;
+	const value = payload[0];
+	for (const handler of Array.from(handlers)) try {
+		handler(value);
+	} catch (error) {
+		console.error(`${BLAC_ERROR_PREFIX} event handler error for '${token.name}':`, error);
+	}
+}
+//#endregion
+//#region src/core/meta.ts
+/**
+* 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;
+		},
+		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 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.
+	*/
+	[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 (process.env.NODE_ENV !== "production") 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).
+	*/
+	[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.
+	*/
+	[ON_DISPOSE](handler) {
+		return this.onSystemEvent("dispose", handler);
+	}
+	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 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);
+			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,
+				args: effectiveArgs,
+				dependent: this
+			});
+		};
+		const handle = {
+			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._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 = getRegistry();
+		this._equalityFn = getBlacConfig().equality;
+		this._name = this.constructor.name;
+		this._debug = false;
+		this._instanceId = generateSimpleId(this.constructor.name, "main");
+		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);
+			}
+			const wasFirst = event === "stateChanged" && handlers.size === 0;
+			handlers.add(handler);
+			if (wasFirst) this._subscribeBridge();
+			let removed = false;
+			return () => {
+				if (removed) return;
+				removed = true;
+				handlers?.delete(handler);
+				if (event === "stateChanged" && (!handlers || 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(() => 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
+	* state snapshot is read by any consumer. Override to seed args-derived state (via
+	* this.emit(...)) or kick off loads.
+	*/
+	init(_args) {}
+	/**
+	* @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}.
+	*/
+	[INIT_CONFIG](config) {
+		this._config = { ...config };
+		this._name = this._config.name || this.constructor.name;
+		this._debug = this._config.debug ?? false;
+		this._instanceId = generateSimpleId(this.constructor.name, this._config.instanceId);
+		const perClass = getClassEquality(this.constructor);
+		this._equalityFn = perClass ?? getBlacConfig().equality;
+		this._registry.emit("created", this);
+		if (!this._initCalled) {
+			this._initCalled = true;
+			this.init(this._config.args);
+		}
+		if (process.env.NODE_ENV !== "production") {
+			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._systemEventHandlers.clear();
+		this._pendingChange = null;
+		this._registry.emit("disposed", this);
+		if (this._debug) console.log(`[${this._name}] Disposed successfully`);
+		super.dispose();
+	}
+	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) 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 (!hasKeys) return;
+		if (allEqual) return;
+		if (process.env.NODE_ENV !== "production") this._checkEmitRate();
+		super.patch(partial);
+		const next = this.state;
+		if (Object.is(prev, next)) return;
+		if (this._hydrationStatus === "hydrating") this._changedWhileHydrating = true;
+		if (this._hasStateChangedHandlers()) 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) throw new Error(`Cannot emit state from disposed container ${this._name}`);
+		const prev = this.state;
+		if (prev === next) return;
+		if (this._equalityFn(prev, next)) return;
+		if (process.env.NODE_ENV !== "production") this._checkEmitRate();
+		if (this._hydrationStatus === "hydrating" && source !== "hydration") this._changedWhileHydrating = true;
+		if (this._hasStateChangedHandlers()) 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");
+	}
+	_applyHydratedState(next) {
+		if (this._disposed) return false;
+		if (this._hydrationStatus !== "hydrating" || this._changedWhileHydrating) 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;
+		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);
+			}
+		}
+	}
+	/**
+	* 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 = 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>` 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.
+*
+* 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.
+*/
+var Cubit = class extends StateContainer {};
+//#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
+export { defineEvent as a, StateContainer as i, Cubit as n, emitEvent as o, DEP_BRAND as r, onEvent as s, ensure as t };
+
+//# sourceMappingURL=ensure-BEeY5Ab7.js.map