@blac/core 2.1.0 → 2.1.2

package/dist/{ensure-BSJHkUNX.js → ensure-BnVyd6s4.js}

@@ -1,5 +1,4 @@
-import { a as INIT_CONFIG, c as getClassEquality, i as APPLY_DEPS, m as getBlacConfig, o as ON_DISPOSE, s as REMOVE_DEPS_OWNER } from "./StateContainerRegistry-D8nu7Z0T.js";
-import { t as getRegistry } from "./config-DXI3kzmA.js";
+import { a as ON_DISPOSE, c as WITH_TRACKED_STATE, g as getBlacConfig, i as INIT_CONFIG, l as getBlacName, m as IS_DEV, n as globalRegistry, o as REMOVE_DEPS_OWNER, r as APPLY_DEPS, s as SET_ACTIVE, u as getClassEquality } from "./StateContainerRegistry-BH7aOMWV.js";
 import { ALL_PATHS, StructuralContainer } from "@dirtytalk/structural";
 //#region src/utils/idGenerator.ts
 /**
@@ -27,86 +26,133 @@ function generateSimpleId(prefix, affix) {
 	return `${prefix}:${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
 }
 //#endregion
+//#region src/registry/config.ts
+let _registry = globalRegistry;
+/**
+* @public
+*/
+function getRegistry() {
+	return _registry;
+}
+/**
+* @public
+*/
+function setRegistry(registry) {
+	_registry = registry;
+}
+/**
+* @public
+*/
+function getStats() {
+	return _registry.getStats();
+}
+//#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.
+* `$blac` meta namespace for `StateContainer`.
+*
+* `BlacMeta` and `BlacHydration` are classes whose accessors live on the
+* prototype and read the container through one `#private` back-reference, so
+* a container allocates a single small object here instead of a literal with
+* seven closures. Members are therefore not own-enumerable: `Object.keys` and
+* `JSON.stringify` see an empty object. Read the fields by name.
+*/
+/**
+* Non-enumerable brand carried on every `$blac` object. 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.
+* Hydration sub-surface of {@link BlacMeta}. Exposes the container's
+* hydration state machine — the `begin`/`apply`/`finish`/`fail`/`wait`
+* methods and the `status`/`error`/`isHydrated`/`changedWhileHydrating`
+* getters — namespaced under `$blac`.
+*/
+var BlacHydration = class {
+	#c;
+	/** @internal */
+	constructor(container) {
+		this.#c = container;
+		Object.freeze(this);
+	}
+	get status() {
+		return this.#c._hydrationStatus;
+	}
+	get error() {
+		return this.#c._hydrationError;
+	}
+	get isHydrated() {
+		return this.#c._hydrationStatus === "hydrated";
+	}
+	get changedWhileHydrating() {
+		return this.#c._changedWhileHydrating;
+	}
+	begin() {
+		this.#c._beginHydration();
+	}
+	apply(next) {
+		return this.#c._applyHydratedState(next);
+	}
+	finish() {
+		this.#c._finishHydration();
+	}
+	fail(error) {
+		this.#c._failHydration(error);
+	}
+	wait() {
+		return this.#c._waitForHydration();
+	}
+};
+/**
+* The reserved `$blac` instance member on every `StateContainer`. Gathers the
+* container's identity/lifecycle/hydration surface (`name`, `id`, `debug`,
+* `createdAt`, `disposed`, `dependencies`, and the hydration methods) under one
+* namespace, keeping the generic names free for userland blocs.
 *
-* The getters close over `container` (the real instance), never over a
-* `this`-receiver — this is what keeps `$blac` reads safe through
-* `buildTrackedProxy`.
+* Allocated once per container and frozen. Every accessor reads the
+* container's current `_`-private fields live — values are never snapshotted.
 */
-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);
-}
+var BlacMeta = class {
+	#c;
+	#hydration;
+	/** @internal Called from the `StateContainer` field initializer. */
+	constructor(container) {
+		this.#c = container;
+		Object.freeze(this);
+	}
+	get name() {
+		return this.#c._name;
+	}
+	get id() {
+		const c = this.#c;
+		return c._instanceId ??= generateSimpleId(getBlacName(c.constructor), "main");
+	}
+	get debug() {
+		return this.#c._debug;
+	}
+	get createdAt() {
+		return this.#c._createdAt;
+	}
+	get disposed() {
+		return this.#c._disposed;
+	}
+	get dependencies() {
+		return this.#c._dependencies ?? EMPTY_DEPS;
+	}
+	/** Built on first access; identity-stable afterwards. */
+	get hydration() {
+		return this.#hydration ??= new BlacHydration(this.#c);
+	}
+};
+Object.defineProperty(BlacMeta.prototype, META_BRAND, {
+	value: true,
+	enumerable: false,
+	writable: false,
+	configurable: false
+});
 //#endregion
 //#region src/core/StateContainer.ts
 /**
@@ -117,6 +163,8 @@ function createMeta(container) {
 * @internal — exported for `@blac/react`; not part of the public API.
 */
 const DEP_BRAND = Symbol("blac.depHandle");
+const EMPTY_RECORD = Object.freeze({});
+let deactivatedReason;
 /**
 * 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)
@@ -173,7 +221,7 @@ var StateContainer = class extends 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 (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`);
 		}
@@ -196,6 +244,34 @@ var StateContainer = class extends StructuralContainer {
 	[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.
+	*/
+	[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(deactivatedReason ??= new DOMException("The bloc was deactivated", "AbortError"));
+		this._activation = null;
+	}
 	reconcileDeps() {
 		const prev = this._deps;
 		const next = {};
@@ -207,6 +283,31 @@ var StateContainer = class extends StructuralContainer {
 		this._registry.emit("depsChanged", this, prev, next);
 	}
 	onDepsChanged(_next, _prev) {}
+	get state() {
+		return this._stateOverride ?? super.state;
+	}
+	/**
+	* @internal Run `fn` (with `this` = this instance, so a prototype getter can
+	* be passed directly) while `state` reports `tracked` and dep handles read
+	* off `this` route 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.
+	*/
+	[WITH_TRACKED_STATE](tracked, fn, onDepHandle) {
+		const prevState = this._stateOverride;
+		const prevHook = this._depHandleHook;
+		this._stateOverride = tracked;
+		this._depHandleHook = onDepHandle;
+		try {
+			return fn.call(this);
+		} finally {
+			this._stateOverride = prevState;
+			this._depHandleHook = prevHook;
+		}
+	}
 	get args() {
 		return this._config.args;
 	}
@@ -241,6 +342,8 @@ var StateContainer = class extends 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];
 			},
@@ -260,40 +363,46 @@ var StateContainer = class extends StructuralContainer {
 	constructor(initialState, options) {
 		super(initialState, options);
 		this._depsByOwner = null;
-		this._deps = {};
+		this._deps = EMPTY_RECORD;
 		this._disposed = false;
 		this._hydrationStatus = "idle";
 		this._changedWhileHydrating = false;
 		this._hydrationPromise = null;
 		this._hydrationPromiseSettled = false;
-		this._config = {};
+		this._config = EMPTY_RECORD;
 		this._initCalled = false;
+		this._activation = null;
 		this._emitWindowStart = 0;
 		this._emitCount = 0;
 		this._emitRateWarned = false;
-		this._systemEventHandlers = /* @__PURE__ */ new Map();
+		this._systemEventHandlers = null;
 		this._dependencies = null;
 		this._pendingChange = null;
 		this._bridgeUnsub = null;
 		this._registry = getRegistry();
 		this._equalityFn = getBlacConfig().equality;
-		this._name = this.constructor.name;
+		this._name = getBlacName(this.constructor);
 		this._debug = false;
-		this._instanceId = generateSimpleId(this.constructor.name, "main");
 		this._createdAt = Date.now();
-		this.$blac = createMeta(this);
+		this.$blac = new BlacMeta(this);
 		this.onSystemEvent = (event, handler) => {
-			let handlers = this._systemEventHandlers.get(event);
+			const all = this._systemEventHandlers ??= /* @__PURE__ */ new Map();
+			let handlers = all.get(event);
 			if (!handlers) {
 				handlers = /* @__PURE__ */ new Set();
-				this._systemEventHandlers.set(event, handlers);
+				all.set(event, handlers);
 			}
 			handlers.add(handler);
+			if (event === "stateChanged" && this._bridgeUnsub === null) this._bridgeUnsub = this.channel.subscribe(() => ALL_PATHS, () => this._drainPending());
 			return () => {
 				handlers?.delete(handler);
+				if (event === "stateChanged" && handlers?.size === 0) {
+					this._bridgeUnsub?.();
+					this._bridgeUnsub = null;
+					this._pendingChange = null;
+				}
 			};
 		};
-		this._bridgeUnsub = this.channel.subscribe(() => ALL_PATHS, () => this._drainPending());
 	}
 	/**
 	* Called once after construction with the args passed at acquire time, before the first
@@ -302,6 +411,24 @@ var StateContainer = class extends 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()`
@@ -309,17 +436,18 @@ var StateContainer = class extends StructuralContainer {
 	*/
 	[INIT_CONFIG](config) {
 		this._config = { ...config };
-		this._name = this._config.name || this.constructor.name;
+		const className = getBlacName(this.constructor);
+		this._name = this._config.name || className;
 		this._debug = this._config.debug ?? false;
-		this._instanceId = generateSimpleId(this.constructor.name, this._config.instanceId);
+		this._instanceId = generateSimpleId(className, 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") {
+		this._registry.emit("created", this);
+		if (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.`);
 		}
 	}
@@ -335,9 +463,11 @@ var StateContainer = class extends StructuralContainer {
 		this.emitSystemEvent("dispose", void 0);
 		this._bridgeUnsub?.();
 		this._bridgeUnsub = null;
-		this._systemEventHandlers.clear();
+		this._abortActivation();
+		this._systemEventHandlers = null;
 		this._pendingChange = null;
 		this._registry.emit("disposed", this);
+		super.dispose();
 		if (this._debug) console.log(`[${this._name}] Disposed successfully`);
 	}
 	emit(next) {
@@ -353,22 +483,17 @@ var StateContainer = class extends StructuralContainer {
 	* 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 (this._disposed) {
+			this._warnDisposedMutation("patch");
+			return;
 		}
-		if (allEqual) return;
-		if (process.env.NODE_ENV !== "production") this._checkEmitRate();
+		const prev = super.state;
 		super.patch(partial);
-		const next = this.state;
+		const next = super.state;
 		if (Object.is(prev, next)) return;
+		if (IS_DEV && !this._emitRateWarned) this._checkEmitRate();
 		if (this._hydrationStatus === "hydrating") this._changedWhileHydrating = true;
-		if (this._pendingChange) this._pendingChange.next = next;
+		if (this._bridgeUnsub !== null) if (this._pendingChange) this._pendingChange.next = next;
 		else this._pendingChange = {
 			prev,
 			next
@@ -376,13 +501,16 @@ var StateContainer = class extends 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}`);
-		const prev = this.state;
+		if (this._disposed) {
+			this._warnDisposedMutation("emit");
+			return;
+		}
+		const prev = super.state;
 		if (prev === next) return;
 		if (this._equalityFn(prev, next)) return;
-		if (process.env.NODE_ENV !== "production") this._checkEmitRate();
+		if (IS_DEV && !this._emitRateWarned) this._checkEmitRate();
 		if (this._hydrationStatus === "hydrating" && source !== "hydration") this._changedWhileHydrating = true;
-		if (this._pendingChange) this._pendingChange.next = next;
+		if (this._bridgeUnsub !== null) if (this._pendingChange) this._pendingChange.next = next;
 		else this._pendingChange = {
 			prev,
 			next
@@ -399,7 +527,7 @@ var StateContainer = class extends StructuralContainer {
 		const pending = this._pendingChange;
 		if (!pending) return;
 		this._pendingChange = null;
-		const handlers = this._systemEventHandlers.get("stateChanged");
+		const handlers = this._systemEventHandlers?.get("stateChanged");
 		if (handlers && handlers.size > 0) {
 			const payload = {
 				state: pending.next,
@@ -428,9 +556,15 @@ var StateContainer = class extends StructuralContainer {
 		this.ensureHydrationPromise();
 		this.setHydrationStatus("hydrating");
 	}
+	_warnDisposedMutation(op) {
+		if (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 (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;
 	}
@@ -492,7 +626,7 @@ var StateContainer = class extends StructuralContainer {
 		this._rejectHydrationPromise?.(error);
 	}
 	emitSystemEvent(event, payload) {
-		const handlers = this._systemEventHandlers.get(event);
+		const handlers = this._systemEventHandlers?.get(event);
 		if (!handlers) return;
 		for (const handler of handlers) try {
 			handler(payload);
@@ -508,7 +642,7 @@ var StateContainer = class extends StructuralContainer {
 	*/
 	_checkEmitRate() {
 		const limit = getBlacConfig().maxEmitsPerSecond;
-		if (!(limit > 0) || !Number.isFinite(limit) || this._emitRateWarned) return;
+		if (!(limit > 0) || !Number.isFinite(limit)) return;
 		const now = Date.now();
 		if (now - this._emitWindowStart >= 1e3) {
 			this._emitWindowStart = now;
@@ -525,19 +659,60 @@ var StateContainer = class extends 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
 /**
@@ -550,6 +725,6 @@ function ensure(BlocClass, opts) {
 	return registry.ensure(BlocClass, key, opts?.args);
 }
 //#endregion
-export { StateContainer as i, Cubit as n, DEP_BRAND as r, ensure as t };
+export { DEP_BRAND as a, getStats as c, Cubit as i, setRegistry as l, acquire as n, StateContainer as o, resolveInstanceKey as r, getRegistry as s, ensure as t };
 
-//# sourceMappingURL=ensure-BSJHkUNX.js.map
+//# sourceMappingURL=ensure-BnVyd6s4.js.map