@blac/core 2.0.16 → 2.0.18

package/dist/ensure-BfYnvAsI.js

@@ -0,0 +1,709 @@
+import { a as EMIT, c as getClassEquality, i as APPLY_DEPS, m as getBlacConfig, o as INIT_CONFIG, s as REMOVE_DEPS_OWNER } from "./StateContainerRegistry-4Ljd9EJx.js";
+import { t as getRegistry } from "./config-COT4Xkbc.js";
+import { ALL_PATHS, StructuralContainer } from "@dirtytalk/structural";
+//#region src/utils/idGenerator.ts
+/**
+* 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/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$1 = /* @__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$1;
+		},
+		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");
+const EMPTY_DEPS = /* @__PURE__ */ new Map();
+const warnedMembers = /* @__PURE__ */ new WeakMap();
+function warnDeprecated(ctor, member, replacement) {
+	if (process.env.NODE_ENV === "test" || process.env.NODE_ENV === "production") return;
+	let seen = warnedMembers.get(ctor);
+	if (!seen) {
+		seen = /* @__PURE__ */ new Set();
+		warnedMembers.set(ctor, seen);
+	}
+	if (seen.has(member)) return;
+	seen.add(member);
+	console.warn(`[blac] \`StateContainer#${member}\` is deprecated; use \`${replacement}\` instead. (${ctor.name}; this warning fires once per class.)`);
+}
+/**
+* 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 (`name`, `instanceId`, `createdAt`, `debug`)
+*   - lifecycle (`dispose`, `isDisposed`, `onSystemEvent`)
+*   - hydration (`beginHydration` / `applyHydratedState` / `finishHydration` / `failHydration` / `waitForHydration`)
+*   - cross-bloc deps (`depend()`, `dependencies` getter)
+*   - per-consumer deps slices (`APPLY_DEPS` / `REMOVE_DEPS_OWNER` / `onDepsChanged`)
+*   - registry integration (config-driven equality, emit-rate circuit breaker)
+*
+* Subscribers can attach via:
+*   - `subscribe(listener)` — legacy state listener (back-compat); fires on
+*     every flush with the latest state.
+*   - `onSystemEvent('stateChanged' | 'dispose' | 'hydrationChanged', cb)` —
+*     coarse lifecycle events.
+*   - `this.channel.subscribe(interest, cb)` — path-scoped (new code).
+*/
+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();
+	}
+	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) {}
+	/**
+	* @deprecated Use `$blac.name`. Setter kept until M5 (`[INIT_CONFIG]` and
+	* legacy `initConfig` historically wrote `name`).
+	*/
+	get name() {
+		warnDeprecated(this.constructor, "name", "$blac.name");
+		return this._name;
+	}
+	set name(value) {
+		warnDeprecated(this.constructor, "name", "$blac.name");
+		this._name = value;
+	}
+	/**
+	* @deprecated Use `$blac.debug`. Setter kept until M5.
+	*/
+	get debug() {
+		warnDeprecated(this.constructor, "debug", "$blac.debug");
+		return this._debug;
+	}
+	set debug(value) {
+		warnDeprecated(this.constructor, "debug", "$blac.debug");
+		this._debug = value;
+	}
+	/**
+	* @deprecated Use `$blac.id`. Setter kept until M5.
+	*/
+	get instanceId() {
+		warnDeprecated(this.constructor, "instanceId", "$blac.id");
+		return this._instanceId;
+	}
+	set instanceId(value) {
+		warnDeprecated(this.constructor, "instanceId", "$blac.id");
+		this._instanceId = value;
+	}
+	/**
+	* @deprecated Use `$blac.createdAt`.
+	*/
+	get createdAt() {
+		warnDeprecated(this.constructor, "createdAt", "$blac.createdAt");
+		return this._createdAt;
+	}
+	/**
+	* @deprecated Use `$blac.dependencies`.
+	*/
+	get dependencies() {
+		warnDeprecated(this.constructor, "dependencies", "$blac.dependencies");
+		return this._dependencies ?? EMPTY_DEPS;
+	}
+	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.ensure(Type, key, effectiveArgs);
+		};
+		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._listeners = /* @__PURE__ */ new Set();
+		this._systemEventHandlers = /* @__PURE__ */ new Map();
+		this._dependencies = 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);
+			}
+			handlers.add(handler);
+			return () => {
+				handlers?.delete(handler);
+			};
+		};
+		this._bridgeUnsub = this.channel.subscribe(() => ALL_PATHS, () => this._drainPending());
+	}
+	/**
+	* 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 (NOT through the
+	* deprecated setters, so it never trips a deprecation warning), 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.`);
+		}
+	}
+	/**
+	* @deprecated Use `[INIT_CONFIG]` (the symbol from `@blac/core`). Kept as a
+	* delegate until M5.
+	*/
+	initConfig(config) {
+		warnDeprecated(this.constructor, "initConfig", "[INIT_CONFIG]");
+		this[INIT_CONFIG](config);
+	}
+	/**
+	* @deprecated Use `$blac.disposed`.
+	*/
+	get isDisposed() {
+		warnDeprecated(this.constructor, "isDisposed", "$blac.disposed");
+		return this._disposed;
+	}
+	/**
+	* @deprecated Use `$blac.hydration.status`.
+	*/
+	get hydrationStatus() {
+		warnDeprecated(this.constructor, "hydrationStatus", "$blac.hydration.status");
+		return this._hydrationStatus;
+	}
+	/**
+	* @deprecated Use `$blac.hydration.error`.
+	*/
+	get hydrationError() {
+		warnDeprecated(this.constructor, "hydrationError", "$blac.hydration.error");
+		return this._hydrationError;
+	}
+	/**
+	* @deprecated Use `$blac.hydration.isHydrated`.
+	*/
+	get isHydrated() {
+		warnDeprecated(this.constructor, "isHydrated", "$blac.hydration.isHydrated");
+		return this._hydrationStatus === "hydrated";
+	}
+	/**
+	* @deprecated Use `$blac.hydration.changedWhileHydrating`.
+	*/
+	get changedWhileHydrating() {
+		warnDeprecated(this.constructor, "changedWhileHydrating", "$blac.hydration.changedWhileHydrating");
+		return this._changedWhileHydrating;
+	}
+	subscribe(listener) {
+		if (this._disposed) throw new Error(`Cannot subscribe to disposed container ${this._name}`);
+		this._listeners.add(listener);
+		return () => {
+			this._listeners.delete(listener);
+		};
+	}
+	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._listeners.clear();
+		this._systemEventHandlers.clear();
+		this._pendingChange = null;
+		this._registry.emit("disposed", this);
+		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 legacy
+	* listeners and `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 partialKeys = Object.keys(partial);
+		if (partialKeys.length === 0) return;
+		const prev = this.state;
+		let allEqual = true;
+		for (const key of partialKeys) if (!Object.is(prev[key], partial[key])) {
+			allEqual = false;
+			break;
+		}
+		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._pendingChange) this._pendingChange.next = next;
+		else this._pendingChange = {
+			prev,
+			next
+		};
+		if (this._registry.hasStateChangedListeners) this._registry.notifyStateChanged(this, prev, next);
+	}
+	/**
+	* @internal @deprecated Symbol-keyed alias for `emit`. Kept only so legacy
+	* in-package tests that index with `[EMIT]` typecheck/run unchanged. C5
+	* removes this along with the `EMIT` symbol.
+	*/
+	[EMIT](next) {
+		this.applyState(next, "default");
+	}
+	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._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 legacy listeners and 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);
+				}
+			}
+		}
+		if (this._listeners.size > 0) {
+			const current = this.state;
+			let count = 0;
+			const size = this._listeners.size;
+			for (const listener of this._listeners) {
+				if (++count > size) break;
+				try {
+					listener(current);
+				} catch (error) {
+					console.error(`[${this._name}] Error in listener:`, 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();
+	}
+	/**
+	* @deprecated Use `$blac.hydration.begin()`.
+	*/
+	beginHydration() {
+		warnDeprecated(this.constructor, "beginHydration", "$blac.hydration.begin()");
+		this._beginHydration();
+	}
+	/**
+	* @deprecated Use `$blac.hydration.apply()`.
+	*/
+	applyHydratedState(next) {
+		warnDeprecated(this.constructor, "applyHydratedState", "$blac.hydration.apply()");
+		return this._applyHydratedState(next);
+	}
+	/**
+	* @deprecated Use `$blac.hydration.finish()`.
+	*/
+	finishHydration() {
+		warnDeprecated(this.constructor, "finishHydration", "$blac.hydration.finish()");
+		this._finishHydration();
+	}
+	/**
+	* @deprecated Use `$blac.hydration.fail()`.
+	*/
+	failHydration(error) {
+		warnDeprecated(this.constructor, "failHydration", "$blac.hydration.fail()");
+		this._failHydration(error);
+	}
+	/**
+	* @deprecated Use `$blac.hydration.wait()`.
+	*/
+	waitForHydration() {
+		warnDeprecated(this.constructor, "waitForHydration", "$blac.hydration.wait()");
+		return this._waitForHydration();
+	}
+	setHydrationStatus(status, error) {
+		const previousStatus = this._hydrationStatus;
+		this._hydrationStatus = status;
+		this._hydrationError = error;
+		this.emitSystemEvent("hydrationChanged", {
+			status,
+			previousStatus,
+			error,
+			changedWhileHydrating: this._changedWhileHydrating
+		});
+	}
+	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 = 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 (see A2 audit).
+*
+* 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). If a caller
+* needs the old "skip if no real change" patch semantics, they 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 { StateContainer as i, Cubit as n, DEP_BRAND as r, ensure as t };
+
+//# sourceMappingURL=ensure-BfYnvAsI.js.map