@blac/core 2.0.0-rc.15 → 2.0.0-rc.17

package/dist/index.js

@@ -195,17 +195,17 @@ var PluginManager = class {
 	* Setup lifecycle hooks to notify plugins
 	*/
 	setupLifecycleHooks() {
-		this.registry.on("created", (instance) => {
-			this.notifyPlugins("onInstanceCreated", instance);
+		this.registry.on("created", (instance$1) => {
+			this.notifyPlugins("onInstanceCreated", instance$1);
 		});
-		this.registry.on("stateChanged", (instance, previousState, currentState, callstack) => {
-			this.notifyPlugins("onStateChanged", instance, previousState, currentState, callstack);
+		this.registry.on("stateChanged", (instance$1, previousState, currentState, callstack) => {
+			this.notifyPlugins("onStateChanged", instance$1, previousState, currentState, callstack);
 		});
 		this.registry.on("eventAdded", (vertex, event) => {
 			this.notifyPlugins("onEventAdded", vertex, event);
 		});
-		this.registry.on("disposed", (instance) => {
-			this.notifyPlugins("onInstanceDisposed", instance);
+		this.registry.on("disposed", (instance$1) => {
+			this.notifyPlugins("onInstanceDisposed", instance$1);
 		});
 	}
 	/**
@@ -227,23 +227,23 @@ var PluginManager = class {
 	*/
 	createPluginContext() {
 		return {
-			getInstanceMetadata: (instance) => {
+			getInstanceMetadata: (instance$1) => {
 				return {
-					id: instance.instanceId,
-					className: instance.constructor.name,
-					isDisposed: instance.isDisposed,
-					name: instance.name,
-					lastStateChangeTimestamp: instance.lastUpdateTimestamp,
-					createdAt: instance.createdAt,
-					state: instance.state,
-					isIsolated: instance.instanceId.startsWith("isolated-")
+					id: instance$1.instanceId,
+					className: instance$1.constructor.name,
+					isDisposed: instance$1.isDisposed,
+					name: instance$1.name,
+					lastStateChangeTimestamp: instance$1.lastUpdateTimestamp,
+					createdAt: instance$1.createdAt,
+					state: instance$1.state,
+					isIsolated: instance$1.instanceId.startsWith("isolated-")
 				};
 			},
-			getState: (instance) => {
-				return instance.state;
+			getState: (instance$1) => {
+				return instance$1.state;
 			},
 			queryInstances: (typeClass) => {
-				return typeClass.getAll();
+				return this.registry.getAll(typeClass);
 			},
 			getAllTypes: () => {
 				return this.registry.getTypes();
@@ -335,7 +335,7 @@ const getterExecutionContext = {
 	depth: 0,
 	visitedBlocs: /* @__PURE__ */ new Set()
 };
-const MAX_GETTER_DEPTH = BLAC_DEFAULTS.MAX_GETTER_DEPTH;
+const MAX_GETTER_DEPTH$1 = BLAC_DEFAULTS.MAX_GETTER_DEPTH;
 /**
 * @internal
 */
@@ -372,7 +372,7 @@ function isGetter(obj, prop) {
 /**
 * @internal
 */
-function createGetterTracker() {
+function createGetterState() {
 	return {
 		trackedValues: /* @__PURE__ */ new Map(),
 		currentlyAccessing: /* @__PURE__ */ new Set(),
@@ -423,8 +423,8 @@ function createBlocProxy(bloc) {
 				tracker.trackedValues.set(prop, cachedValue);
 				return cachedValue;
 			}
-			if (getterExecutionContext.depth >= MAX_GETTER_DEPTH) {
-				console.warn(`${BLAC_ERROR_PREFIX} Maximum getter depth (${MAX_GETTER_DEPTH}) exceeded. Possible circular dependency in getter "${String(prop)}" on ${target.constructor.name}. Returning undefined to prevent stack overflow.`);
+			if (getterExecutionContext.depth >= MAX_GETTER_DEPTH$1) {
+				console.warn(`${BLAC_ERROR_PREFIX} Maximum getter depth (${MAX_GETTER_DEPTH$1}) exceeded. Possible circular dependency in getter "${String(prop)}" on ${target.constructor.name}. Returning undefined to prevent stack overflow.`);
 				return;
 			}
 			if (getterExecutionContext.visitedBlocs.has(target)) {
@@ -500,7 +500,7 @@ function clearExternalDependencies(tracker) {
 /**
 * @internal
 */
-function resetGetterTracker(tracker) {
+function resetGetterState(tracker) {
 	tracker.trackedValues.clear();
 	tracker.currentlyAccessing.clear();
 	tracker.trackedGetters.clear();
@@ -510,6 +510,19 @@ function resetGetterTracker(tracker) {
 	tracker.externalDependencies.clear();
 }
 
+//#endregion
+//#region src/core/markers.ts
+/**
+* Marker symbols for identifying container types.
+* These are in a separate file to avoid circular dependencies.
+* @internal
+*/
+/**
+* Marker symbol to identify stateless containers at the type level.
+* Used by React hooks to prevent `useBloc` from accepting stateless containers.
+*/
+const STATELESS_MARKER = Symbol("STATELESS_CONTAINER");
+
 //#endregion
 //#region src/utils/static-props.ts
 /**
@@ -554,6 +567,15 @@ function isKeepAliveClass(Type) {
 function isExcludedFromDevTools(Type) {
 	return getStaticProp(Type, BLAC_STATIC_PROPS.EXCLUDE_FROM_DEVTOOLS) === true;
 }
+/**
+* Check if a class is a stateless container (StatelessCubit or StatelessVertex).
+* Stateless containers don't have state, emit, update, or subscribe methods.
+* @param Type - The class constructor to check
+* @returns true if the class is a stateless container
+*/
+function isStatelessClass(Type) {
+	return Type[STATELESS_MARKER] === true;
+}
 
 //#endregion
 //#region src/core/StateContainerRegistry.ts
@@ -564,7 +586,8 @@ function isExcludedFromDevTools(Type) {
 * @example
 * ```ts
 * const registry = new StateContainerRegistry();
-* const instance = registry.resolve(MyBloc);
+* const instance = registry.acquire(MyBloc);  // ownership, must release
+* const other = registry.ensure(OtherBloc);   // no ownership, bloc-to-bloc
 * registry.on('stateChanged', (container, prev, next) => {
 *   console.log('State changed:', prev, '->', next);
 * });
@@ -611,34 +634,35 @@ var StateContainerRegistry = class {
 	getInstancesMap(Type) {
 		return this.instancesByConstructor.get(Type) || /* @__PURE__ */ new Map();
 	}
-	trackExecutionContext(instance) {
+	trackExecutionContext(instance$1) {
 		const context = getGetterExecutionContext();
-		if (context.tracker && context.currentBloc && context.currentBloc !== instance) context.tracker.externalDependencies.add(instance);
+		if (context.tracker && context.currentBloc && context.currentBloc !== instance$1) context.tracker.externalDependencies.add(instance$1);
 	}
 	/**
-	* Resolve an instance with ref counting (ownership semantics).
+	* Acquire an instance with ref counting (ownership semantics).
 	* Creates a new instance if one doesn't exist, or returns existing and increments ref count.
+	* You must call `release()` when done to decrement the ref count.
 	* @param Type - The StateContainer class constructor
 	* @param instanceKey - Instance key (defaults to 'default')
-	* @param options - Resolution options
+	* @param options - Acquisition options
 	* @param options.canCreate - Whether to create new instance if not found (default: true)
 	* @param options.countRef - Whether to increment ref count (default: true)
 	* @param options.props - Props to pass to constructor if creating new instance
 	* @param options.trackExecutionContext - Whether to track cross-bloc dependency (default: false)
 	* @returns The state container instance
 	*/
-	resolve(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, options = {}) {
+	acquire(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, options = {}) {
 		const { canCreate = true, countRef = true, props, trackExecutionContext = false } = options;
 		const registryConfig = this.typeConfigs.get(Type.name);
 		const isolated = isIsolatedClass(Type) || registryConfig?.isolated === true;
 		const config = { instanceId: instanceKey };
 		if (isolated && !canCreate) throw new Error(`${BLAC_ERROR_PREFIX} Cannot get isolated instance "${instanceKey}" of ${Type.name} when creation is disabled.`);
 		if (isolated) {
-			const instance$1 = new Type(props);
-			instance$1.initConfig(config);
+			const instance$2 = new Type(props);
+			instance$2.initConfig(config);
 			this.registerType(Type);
-			if (trackExecutionContext) this.trackExecutionContext(instance$1);
-			return instance$1;
+			if (trackExecutionContext) this.trackExecutionContext(instance$2);
+			return instance$2;
 		}
 		const instances = this.ensureInstancesMap(Type);
 		const entry = instances.get(instanceKey);
@@ -648,42 +672,42 @@ var StateContainerRegistry = class {
 			return entry.instance;
 		}
 		if (!canCreate) throw new Error(`${BLAC_ERROR_PREFIX} ${Type.name} instance "${instanceKey}" not found and creation is disabled.`);
-		const instance = new Type(props);
-		instance.initConfig(config);
+		const instance$1 = new Type(props);
+		instance$1.initConfig(config);
 		instances.set(instanceKey, {
-			instance,
+			instance: instance$1,
 			refCount: 1
 		});
 		this.registerType(Type);
-		if (trackExecutionContext) this.trackExecutionContext(instance);
-		return instance;
+		if (trackExecutionContext) this.trackExecutionContext(instance$1);
+		return instance$1;
 	}
 	/**
-	* Get an existing instance without incrementing ref count (borrowing semantics).
+	* Borrow an existing instance without incrementing ref count (borrowing semantics).
 	* Tracks cross-bloc dependency for reactive updates.
 	* @param Type - The StateContainer class constructor
 	* @param instanceKey - Instance key (defaults to 'default')
 	* @returns The state container instance
 	* @throws Error if instance doesn't exist
 	*/
-	get(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
-		return this.resolve(Type, instanceKey, {
+	borrow(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		return this.acquire(Type, instanceKey, {
 			canCreate: false,
 			trackExecutionContext: true
 		});
 	}
 	/**
-	* Safely get an existing instance (borrowing semantics with error handling).
+	* Safely borrow an existing instance (borrowing semantics with error handling).
 	* Returns discriminated union for type-safe conditional access.
 	* @param Type - The StateContainer class constructor
 	* @param instanceKey - Instance key (defaults to 'default')
 	* @returns Discriminated union with either the instance or an error
 	*/
-	getSafe(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+	borrowSafe(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
 		try {
 			return {
 				error: null,
-				instance: this.get(Type, instanceKey)
+				instance: this.borrow(Type, instanceKey)
 			};
 		} catch (error$1) {
 			return {
@@ -693,7 +717,7 @@ var StateContainerRegistry = class {
 		}
 	}
 	/**
-	* Connect to an instance with borrowing semantics (for B2B communication).
+	* Ensure an instance exists without taking ownership (for bloc-to-bloc communication).
 	* Gets existing instance OR creates it if it doesn't exist, without incrementing ref count.
 	* Tracks cross-bloc dependency for reactive updates.
 	*
@@ -703,8 +727,8 @@ var StateContainerRegistry = class {
 	* @param instanceKey - Instance key (defaults to 'default')
 	* @returns The state container instance
 	*/
-	connect(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
-		return this.resolve(Type, instanceKey, {
+	ensure(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		return this.acquire(Type, instanceKey, {
 			canCreate: true,
 			countRef: false,
 			trackExecutionContext: true
@@ -753,9 +777,9 @@ var StateContainerRegistry = class {
 	forEach(Type, callback) {
 		const instances = this.ensureInstancesMap(Type);
 		for (const entry of instances.values()) {
-			const instance = entry.instance;
-			if (!instance.isDisposed) try {
-				callback(instance);
+			const instance$1 = entry.instance;
+			if (!instance$1.isDisposed) try {
+				callback(instance$1);
 			} catch (error$1) {
 				console.error(`${BLAC_ERROR_PREFIX} forEach callback error for ${Type.name}:`, error$1);
 			}
@@ -833,9 +857,9 @@ var StateContainerRegistry = class {
 	*/
 	on(event, listener) {
 		if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
-		const instance = this.listeners.get(event);
-		if (!instance) throw new Error(`${BLAC_ERROR_PREFIX} Failed to register listener for event '${event}'`);
-		instance.add(listener);
+		const instance$1 = this.listeners.get(event);
+		if (!instance$1) throw new Error(`${BLAC_ERROR_PREFIX} Failed to register listener for event '${event}'`);
+		instance$1.add(listener);
 		return () => {
 			this.listeners.get(event)?.delete(listener);
 		};
@@ -897,132 +921,7 @@ var StateContainer = class StateContainer {
 		this.__excludeFromDevTools = false;
 	}
 	static {
-		this._registry = globalRegistry;
-	}
-	/**
-	* Get the global StateContainerRegistry
-	* @returns The registry managing all state container instances
-	*/
-	static getRegistry() {
-		return StateContainer._registry;
-	}
-	/**
-	* Replace the global registry (clears existing instances)
-	* @param registry - The new registry to use
-	*/
-	static setRegistry(registry) {
-		StateContainer._registry.clearAll();
-		StateContainer._registry = registry;
-	}
-	/**
-	* Register this class with the global registry
-	* @param isolated - Whether instances should be isolated (component-scoped)
-	*/
-	static register(isolated = false) {
-		StateContainer._registry.register(this, isolated);
-	}
-	/**
-	* Resolve an instance with ref counting (ownership semantics).
-	* Creates a new instance if one doesn't exist, or returns existing and increments ref count.
-	* @template S - Optional state type override for generic StateContainers
-	* @template T - The StateContainer type (inferred from class)
-	* @param instanceKey - Optional instance key (defaults to 'default')
-	* @param options - Resolution options (canCreate, countRef, props, trackExecutionContext)
-	* @returns The state container instance
-	*/
-	static resolve(instanceKey, options) {
-		return StateContainer._registry.resolve(this, instanceKey, options);
-	}
-	/**
-	* Get an existing instance without incrementing ref count (borrowing semantics).
-	* @template S - Optional state type override for generic StateContainers
-	* @template T - The StateContainer type (inferred from class)
-	* @param instanceKey - Optional instance key (defaults to 'default')
-	* @returns The state container instance
-	* @throws Error if instance doesn't exist
-	*/
-	static get(instanceKey) {
-		return StateContainer._registry.get(this, instanceKey);
-	}
-	/**
-	* Safely get an existing instance with error handling.
-	* @template S - Optional state type override for generic StateContainers
-	* @template T - The StateContainer type (inferred from class)
-	* @param instanceKey - Optional instance key (defaults to 'default')
-	* @returns Discriminated union with either the instance or an error
-	*/
-	static getSafe(instanceKey) {
-		return StateContainer._registry.getSafe(this, instanceKey);
-	}
-	/**
-	* Connect to an instance for bloc-to-bloc communication (borrowing semantics).
-	* Gets or creates instance without incrementing ref count.
-	* Tracks cross-bloc dependency for reactive updates.
-	* @template S - Optional state type override for generic StateContainers
-	* @template T - The StateContainer type (inferred from class)
-	* @param instanceKey - Optional instance key (defaults to 'default')
-	* @returns The state container instance
-	*/
-	static connect(instanceKey) {
-		return StateContainer._registry.connect(this, instanceKey);
-	}
-	/**
-	* Release a reference to an instance.
-	* Decrements ref count and disposes when it reaches 0 (unless keepAlive).
-	* @param instanceKey - Optional instance key (defaults to 'default')
-	* @param forceDispose - Force immediate disposal regardless of ref count
-	*/
-	static release(instanceKey, forceDispose = false) {
-		StateContainer._registry.release(this, instanceKey, forceDispose);
-	}
-	/**
-	* Get all instances of this class
-	* @returns Array of all instances
-	*/
-	static getAll() {
-		return StateContainer._registry.getAll(this);
-	}
-	/**
-	* Iterate over all instances of this class
-	* @param callback - Function to call for each instance
-	*/
-	static forEach(callback) {
-		StateContainer._registry.forEach(this, callback);
-	}
-	/**
-	* Clear all instances of this class (disposes them)
-	*/
-	static clear() {
-		StateContainer._registry.clear(this);
-	}
-	/**
-	* Clear all instances from all registered types
-	*/
-	static clearAllInstances() {
-		StateContainer._registry.clearAll();
-	}
-	/**
-	* Get registry statistics for debugging
-	* @returns Object with registeredTypes, totalInstances, and typeBreakdown
-	*/
-	static getStats() {
-		return StateContainer._registry.getStats();
-	}
-	/**
-	* Get reference count for an instance
-	* @param instanceKey - Optional instance key (defaults to 'default')
-	* @returns Current ref count (0 if instance doesn't exist)
-	*/
-	static getRefCount(instanceKey) {
-		return StateContainer._registry.getRefCount(this, instanceKey);
-	}
-	/**
-	* Check if an instance exists
-	* @param instanceKey - Optional instance key (defaults to 'default')
-	* @returns true if instance exists
-	*/
-	static hasInstance(instanceKey) {
-		return StateContainer._registry.hasInstance(this, instanceKey);
+		this.enableStackTrace = true;
 	}
 	/** Current props value passed to this container */
 	get props() {
@@ -1062,7 +961,7 @@ var StateContainer = class StateContainer {
 		this.name = this.config.name || this.constructor.name;
 		this.debug = this.config.debug ?? false;
 		this.instanceId = generateSimpleId(this.constructor.name, this.config.instanceId);
-		StateContainer._registry.emit("created", this);
+		globalRegistry.emit("created", this);
 	}
 	/** Current state value */
 	get state() {
@@ -1093,7 +992,7 @@ var StateContainer = class StateContainer {
 		this.emitSystemEvent("dispose", void 0);
 		this.listeners.clear();
 		this.systemEventHandlers.clear();
-		StateContainer._registry.emit("disposed", this);
+		globalRegistry.emit("disposed", this);
 		if (this.debug) console.log(`[${this.name}] Disposed successfully`);
 	}
 	/**
@@ -1116,12 +1015,9 @@ var StateContainer = class StateContainer {
 			console.error(`[${this.name}] Error in listener:`, error$1);
 		}
 		const stackTrace = this.captureStackTrace();
-		StateContainer._registry.emit("stateChanged", this, previousState, newState, stackTrace);
+		globalRegistry.emit("stateChanged", this, previousState, newState, stackTrace);
 		this.lastUpdateTimestamp = Date.now();
 	}
-	static {
-		this.enableStackTrace = true;
-	}
 	captureStackTrace() {
 		if (!StateContainer.enableStackTrace || typeof process !== "undefined" && process.env?.NODE_ENV === "production") return "";
 		try {
@@ -1237,33 +1133,70 @@ var Cubit = class extends StateContainer {
 //#endregion
 //#region src/core/Vertex.ts
 /**
-* Event-driven state container that processes events to update state.
-* Use with event handlers registered via the on() method.
+* Event-driven state container using discriminated union events.
+* Extends StateContainer with event-based state transitions and
+* compile-time exhaustive checking for event handlers.
 *
-* @template S - State type
-* @template E - Event type (extends BaseEvent)
+* @template S - State type (must be an object)
+* @template E - Event union type (discriminated by 'type' property)
 * @template P - Props type (optional)
+*
+* @example
+* ```typescript
+* type CounterEvent =
+*   | { type: 'increment'; amount: number }
+*   | { type: 'decrement' }
+*   | { type: 'reset' };
+*
+* class CounterVertex extends Vertex<{ count: number }, CounterEvent> {
+*   constructor() {
+*     super({ count: 0 });
+*     this.createHandlers({
+*       increment: (event, emit) => {
+*         emit({ count: this.state.count + event.amount });
+*       },
+*       decrement: (_, emit) => {
+*         emit({ count: this.state.count - 1 });
+*       },
+*       reset: (_, emit) => {
+*         emit({ count: 0 });
+*       },
+*     });
+*   }
+*
+*   increment = (amount = 1) => this.add({ type: 'increment', amount });
+* }
+* ```
 */
 var Vertex = class extends StateContainer {
 	constructor(initialState) {
 		super(initialState);
-		this.eventHandlers = /* @__PURE__ */ new Map();
+		this.handlers = /* @__PURE__ */ new Map();
 		this.isProcessing = false;
 		this.eventQueue = [];
-		this.on = (EventClass, handler) => {
-			const className = EventClass.name;
-			const registrations = this.eventHandlers.get(className) || [];
-			registrations.push({
-				eventClass: EventClass,
-				handler
-			});
-			this.eventHandlers.set(className, registrations);
-		};
 		this.add = (event) => {
-			StateContainer._registry.emit("eventAdded", this, event);
-			this.processEvent(event);
+			const enrichedEvent = this.enrichEvent(event);
+			globalRegistry.emit("eventAdded", this, enrichedEvent);
+			this.processEvent(enrichedEvent);
+		};
+	}
+	/**
+	* Register all event handlers with exhaustive type checking.
+	* TypeScript will error if any event type from the union is missing.
+	*
+	* @param handlers - Map of event type to handler function
+	*/
+	createHandlers(handlers) {
+		for (const [eventType, handler] of Object.entries(handlers)) this.handlers.set(eventType, handler);
+	}
+	/** @internal */
+	enrichEvent(event) {
+		return {
+			...event,
+			timestamp: Date.now()
 		};
 	}
+	/** @internal */
 	processEvent(event) {
 		if (this.isProcessing) {
 			this.eventQueue.push(event);
@@ -1280,30 +1213,248 @@ var Vertex = class extends StateContainer {
 			this.isProcessing = false;
 		}
 	}
+	/** @internal */
 	handleEvent(event) {
-		const className = event.constructor.name;
-		const registrations = this.eventHandlers.get(className);
-		if (!registrations || registrations.length === 0) {
-			if (this.debug) console.warn(`No handler registered for event: ${className}`);
+		const handler = this.handlers.get(event.type);
+		if (!handler) {
+			if (this.debug) console.warn(`No handler registered for event type: ${event.type}`);
 			return;
 		}
 		const emitFn = (state) => {
 			this.emit(state);
 		};
-		for (const registration of registrations) try {
-			registration.handler(event, emitFn);
+		try {
+			handler(event, emitFn);
+		} catch (error$1) {
+			if (this.debug) console.error(`Error handling event ${event.type}:`, error$1);
+			this.onEventError(event, error$1);
+		}
+	}
+	/**
+	* Called when an error occurs during event processing.
+	* Override to implement custom error handling.
+	*
+	* @param _event - The event that caused the error
+	* @param _error - The error that occurred
+	*/
+	onEventError(_event, _error) {}
+};
+
+//#endregion
+//#region src/core/StatelessCubit.ts
+/**
+* A Cubit without state management capabilities.
+* Use this for action-only containers that don't need to manage or emit state.
+*
+* StatelessCubit:
+* - Has no `emit()`, `update()`, or `patch()` methods
+* - Has no accessible `state` property
+* - Cannot be subscribed to (throws error)
+* - Is rejected by `useBloc` hook (use `useBlocActions` instead)
+*
+* @template P - Props type (optional)
+*
+* @example
+* ```typescript
+* class AnalyticsService extends StatelessCubit {
+*   trackPageView(page: string) {
+*     analytics.track('page_view', { page });
+*   }
+*
+*   trackClick(element: string) {
+*     analytics.track('click', { element });
+*   }
+* }
+*
+* // In React component:
+* const analytics = useBlocActions(AnalyticsService);
+* analytics.trackPageView('/home');
+* ```
+*/
+var StatelessCubit = class extends Cubit {
+	static {
+		this[STATELESS_MARKER] = true;
+	}
+	constructor() {
+		super({});
+		this.patch = (_partial) => {
+			throw new Error(`${this.name} is a StatelessCubit and does not support patch(). Use a regular Cubit if you need state management.`);
+		};
+	}
+	/**
+	* State is not available on StatelessCubit.
+	* @throws Always throws an error when accessed.
+	*/
+	get state() {
+		throw new Error(`${this.name} is a StatelessCubit and does not have state. Use a regular Cubit if you need state management.`);
+	}
+	/**
+	* Subscriptions are not available on StatelessCubit.
+	* @throws Always throws an error when called.
+	*/
+	subscribe(_listener) {
+		throw new Error(`${this.name} is a StatelessCubit and does not support subscriptions. Use useBlocActions() instead of useBloc() in React.`);
+	}
+	/**
+	* emit() is not available on StatelessCubit.
+	* TypeScript will show an error if you try to call this method.
+	*/
+	emit(_newState) {
+		throw new Error(`${this.name} is a StatelessCubit and does not support emit(). Use a regular Cubit if you need state management.`);
+	}
+	/**
+	* update() is not available on StatelessCubit.
+	* TypeScript will show an error if you try to call this method.
+	*/
+	update(_updater) {
+		throw new Error(`${this.name} is a StatelessCubit and does not support update(). Use a regular Cubit if you need state management.`);
+	}
+};
+
+//#endregion
+//#region src/core/StatelessVertex.ts
+/**
+* An event-driven container without state management capabilities.
+* Use this for event processing that only produces side effects (logging, analytics, etc).
+*
+* StatelessVertex:
+* - Processes events via `add()` method
+* - Handlers receive only the event (no `emit` function)
+* - Has no accessible `state` property
+* - Cannot be subscribed to (throws error)
+* - Is rejected by `useBloc` hook (use `useBlocActions` instead)
+*
+* @template E - Event union type (discriminated by 'type' property)
+* @template P - Props type (optional)
+*
+* @example
+* ```typescript
+* type LogEvent =
+*   | { type: 'info'; message: string }
+*   | { type: 'error'; message: string; error: Error }
+*   | { type: 'warn'; message: string };
+*
+* class LoggingVertex extends StatelessVertex<LogEvent> {
+*   constructor() {
+*     super();
+*     this.createHandlers({
+*       info: (event) => console.log('[INFO]', event.message),
+*       error: (event) => console.error('[ERROR]', event.message, event.error),
+*       warn: (event) => console.warn('[WARN]', event.message),
+*     });
+*   }
+*
+*   info = (message: string) => this.add({ type: 'info', message });
+*   error = (message: string, error: Error) => this.add({ type: 'error', message, error });
+*   warn = (message: string) => this.add({ type: 'warn', message });
+* }
+*
+* // In React component:
+* const logger = useBlocActions(LoggingVertex);
+* logger.info('Page loaded');
+* ```
+*/
+var StatelessVertex = class extends StateContainer {
+	static {
+		this[STATELESS_MARKER] = true;
+	}
+	constructor() {
+		super({});
+		this.handlers = /* @__PURE__ */ new Map();
+		this.isProcessing = false;
+		this.eventQueue = [];
+		this.add = (event) => {
+			const enrichedEvent = this.enrichEvent(event);
+			globalRegistry.emit("eventAdded", this, enrichedEvent);
+			this.processEvent(enrichedEvent);
+		};
+	}
+	/**
+	* State is not available on StatelessVertex.
+	* @throws Always throws an error when accessed.
+	*/
+	get state() {
+		throw new Error(`${this.name} is a StatelessVertex and does not have state. Use a regular Vertex if you need state management.`);
+	}
+	/**
+	* Subscriptions are not available on StatelessVertex.
+	* @throws Always throws an error when called.
+	*/
+	subscribe(_listener) {
+		throw new Error(`${this.name} is a StatelessVertex and does not support subscriptions. Use useBlocActions() instead of useBloc() in React.`);
+	}
+	/**
+	* Register all event handlers with exhaustive type checking.
+	* TypeScript will error if any event type from the union is missing.
+	*
+	* Unlike regular Vertex, handlers do NOT receive an emit function
+	* since StatelessVertex cannot emit state.
+	*
+	* @param handlers - Map of event type to handler function
+	*/
+	createHandlers(handlers) {
+		for (const [eventType, handler] of Object.entries(handlers)) this.handlers.set(eventType, handler);
+	}
+	/** @internal */
+	enrichEvent(event) {
+		return {
+			...event,
+			timestamp: Date.now()
+		};
+	}
+	/** @internal */
+	processEvent(event) {
+		if (this.isProcessing) {
+			this.eventQueue.push(event);
+			return;
+		}
+		this.isProcessing = true;
+		try {
+			this.handleEvent(event);
+			while (this.eventQueue.length > 0) {
+				const nextEvent = this.eventQueue.shift();
+				this.handleEvent(nextEvent);
+			}
+		} finally {
+			this.isProcessing = false;
+		}
+	}
+	/** @internal */
+	handleEvent(event) {
+		const handler = this.handlers.get(event.type);
+		if (!handler) {
+			if (this.debug) console.warn(`No handler registered for event type: ${event.type}`);
+			return;
+		}
+		try {
+			handler(event);
 		} catch (error$1) {
-			if (this.debug) console.error(`Error handling event ${className}:`, error$1);
+			if (this.debug) console.error(`Error handling event ${event.type}:`, error$1);
 			this.onEventError(event, error$1);
 		}
 	}
 	/**
-	* Handle errors that occur during event processing.
-	* Override this method to implement custom error handling.
+	* Called when an error occurs during event processing.
+	* Override to implement custom error handling.
+	*
 	* @param _event - The event that caused the error
 	* @param _error - The error that occurred
 	*/
 	onEventError(_event, _error) {}
+	/**
+	* emit() is not available on StatelessVertex.
+	* @internal
+	*/
+	emit(_newState) {
+		throw new Error(`${this.name} is a StatelessVertex and does not support emit(). Use a regular Vertex if you need state management.`);
+	}
+	/**
+	* update() is not available on StatelessVertex.
+	* @internal
+	*/
+	update(_updater) {
+		throw new Error(`${this.name} is a StatelessVertex and does not support update(). Use a regular Vertex if you need state management.`);
+	}
 };
 
 //#endregion
@@ -1353,7 +1504,7 @@ function isProxyable(value) {
 *
 * @internal
 */
-function createProxyTrackerState() {
+function createProxyState() {
 	return {
 		trackedPaths: /* @__PURE__ */ new Set(),
 		isTracking: false,
@@ -1371,7 +1522,7 @@ function createProxyTrackerState() {
 *
 * @internal
 */
-function startProxyTracking(state) {
+function startProxy(state) {
 	state.isTracking = true;
 	state.trackedPaths.clear();
 }
@@ -1382,7 +1533,7 @@ function startProxyTracking(state) {
 *
 * @internal
 */
-function stopProxyTracking(state) {
+function stopProxy(state) {
 	state.isTracking = false;
 	return new Set(state.trackedPaths);
 }
@@ -1421,7 +1572,7 @@ function createArrayProxy(state, target, path, depth = 0) {
 			if (!isNaN(index) && index >= 0) fullPath = path ? `${path}[${index}]` : `[${index}]`;
 			else fullPath = path ? `${path}.${prop}` : prop;
 		} else return value;
-		if (isProxyable(value)) return createProxyInternal(state, value, fullPath, depth + 1);
+		if (isProxyable(value)) return createInternal(state, value, fullPath, depth + 1);
 		if (state.isTracking) state.trackedPaths.add(fullPath);
 		return value;
 	} });
@@ -1442,7 +1593,7 @@ function createArrayProxy(state, target, path, depth = 0) {
 *
 * @internal
 */
-function createProxyInternal(state, target, path = "", depth = 0) {
+function createInternal(state, target, path = "", depth = 0) {
 	if (!state.isTracking || !isProxyable(target)) return target;
 	if (depth >= state.maxDepth) return target;
 	if (state.proxyCache.has(target)) return state.proxyCache.get(target);
@@ -1463,7 +1614,7 @@ function createProxyInternal(state, target, path = "", depth = 0) {
 			if (typeof prop === "string" && state.isTracking) {
 				if (!prop.startsWith("_") && !prop.startsWith("$$")) state.trackedPaths.add(fullPath);
 			}
-			if (isProxyable(value)) return createProxyInternal(state, value, fullPath, depth + 1);
+			if (isProxyable(value)) return createInternal(state, value, fullPath, depth + 1);
 			return value;
 		},
 		has: (obj, prop) => {
@@ -1491,11 +1642,11 @@ function createProxyInternal(state, target, path = "", depth = 0) {
 *
 * @internal
 */
-function createProxyForTarget(state, target) {
+function createForTarget(state, target) {
 	if (state.lastProxiedState === target && state.lastProxy) return state.lastProxy;
 	state.proxyCache = /* @__PURE__ */ new WeakMap();
 	state.boundFunctionsCache = null;
-	const proxy = createProxyInternal(state, target, "", 0);
+	const proxy = createInternal(state, target, "", 0);
 	state.lastProxiedState = target;
 	state.lastProxy = proxy;
 	return proxy;
@@ -1636,9 +1787,9 @@ function optimizeTrackedPaths(paths) {
 /**
 * @internal
 */
-function createTrackerState() {
+function createDependencyState() {
 	return {
-		proxyTrackerState: createProxyTrackerState(),
+		proxyState: createProxyState(),
 		previousRenderPaths: /* @__PURE__ */ new Set(),
 		currentRenderPaths: /* @__PURE__ */ new Set(),
 		pathCache: /* @__PURE__ */ new Map(),
@@ -1649,21 +1800,21 @@ function createTrackerState() {
 /**
 * @internal
 */
-function startTracking(tracker) {
-	startProxyTracking(tracker.proxyTrackerState);
+function startDependency(tracker) {
+	startProxy(tracker.proxyState);
 }
 /**
 * @internal
 */
-function createProxy(tracker, state) {
-	return createProxyForTarget(tracker.proxyTrackerState, state);
+function createDependencyProxy(tracker, state) {
+	return createForTarget(tracker.proxyState, state);
 }
 /**
 * @internal
 */
-function captureTrackedPaths(tracker, state) {
+function capturePaths(tracker, state) {
 	tracker.previousRenderPaths = tracker.currentRenderPaths;
-	tracker.currentRenderPaths = optimizeTrackedPaths(stopProxyTracking(tracker.proxyTrackerState));
+	tracker.currentRenderPaths = optimizeTrackedPaths(stopProxy(tracker.proxyState));
 	if (tracker.previousRenderPaths.size === 0 && tracker.currentRenderPaths.size === 0) return;
 	const trackedPathsUnion = new Set(tracker.previousRenderPaths);
 	for (const path of tracker.currentRenderPaths) trackedPathsUnion.add(path);
@@ -1684,7 +1835,7 @@ function captureTrackedPaths(tracker, state) {
 /**
 * @internal
 */
-function hasChanges(tracker, state) {
+function hasDependencyChanges(tracker, state) {
 	if (tracker.pathCache.size === 0) return true;
 	tracker.lastCheckedValues.clear();
 	for (const [path, info$1] of tracker.pathCache.entries()) {
@@ -1702,7 +1853,294 @@ function hasChanges(tracker, state) {
 * @internal
 */
 function hasTrackedData(tracker) {
-	return tracker.proxyTrackerState.trackedPaths.size > 0 || tracker.pathCache.size > 0 || tracker.previousRenderPaths.size > 0;
+	return tracker.proxyState.trackedPaths.size > 0 || tracker.pathCache.size > 0 || tracker.previousRenderPaths.size > 0;
+}
+
+//#endregion
+//#region src/tracking/tracking-proxy.ts
+/**
+* Create a new tracking proxy state.
+*/
+function createState() {
+	return {
+		dependencyState: createDependencyState(),
+		getterState: createGetterState(),
+		dependencies: /* @__PURE__ */ new Set(),
+		isTracking: false
+	};
+}
+/**
+* Start tracking on a tracking proxy.
+*/
+function startTracking(tracker) {
+	tracker.isTracking = true;
+	tracker.dependencies.clear();
+	tracker.getterState.isTracking = true;
+	tracker.getterState.externalDependencies.clear();
+	startDependency(tracker.dependencyState);
+}
+/**
+* Stop tracking and collect all dependencies.
+*/
+function stopTracking(tracker, bloc) {
+	tracker.isTracking = false;
+	tracker.getterState.isTracking = false;
+	capturePaths(tracker.dependencyState, bloc.state);
+	commitTrackedGetters(tracker.getterState);
+	const allDeps = new Set(tracker.dependencies);
+	for (const dep of tracker.getterState.externalDependencies) allDeps.add(dep);
+	tracker.getterState.externalDependencies.clear();
+	return allDeps;
+}
+/**
+* Check if tracked state or getters have changed.
+*/
+function hasChanges(tracker, bloc) {
+	invalidateRenderCache(tracker.getterState);
+	const stateChanged = hasDependencyChanges(tracker.dependencyState, bloc.state);
+	const getterChanged = hasGetterChanges(bloc, tracker.getterState);
+	return stateChanged || getterChanged;
+}
+const MAX_GETTER_DEPTH = BLAC_DEFAULTS.MAX_GETTER_DEPTH;
+/**
+* Create a tracking proxy for a bloc instance.
+* Tracks both state property access and getter access.
+*/
+function createTrackingProxy(bloc, tracker) {
+	tracker.dependencies.add(bloc);
+	const stateProxyCache = /* @__PURE__ */ new WeakMap();
+	return new Proxy(bloc, { get(target, prop, receiver) {
+		if (prop === "state") {
+			if (!tracker.isTracking) return target.state;
+			const rawState = target.state;
+			if (rawState === null || typeof rawState !== "object") return rawState;
+			if (stateProxyCache.has(rawState)) return stateProxyCache.get(rawState);
+			const stateProxy = createDependencyProxy(tracker.dependencyState, rawState);
+			stateProxyCache.set(rawState, stateProxy);
+			return stateProxy;
+		}
+		if (typeof prop === "symbol") return Reflect.get(target, prop, receiver);
+		const value = Reflect.get(target, prop, receiver);
+		if (typeof value === "function") return value.bind(target);
+		if (tracker.isTracking && isGetter(target, prop)) {
+			tracker.getterState.currentlyAccessing.add(prop);
+			if (tracker.getterState.cacheValid && tracker.getterState.renderCache.has(prop)) {
+				const cachedValue = tracker.getterState.renderCache.get(prop);
+				tracker.getterState.trackedValues.set(prop, cachedValue);
+				return cachedValue;
+			}
+			const context = getGetterExecutionContext();
+			if (context.depth >= MAX_GETTER_DEPTH) {
+				console.warn(`${BLAC_ERROR_PREFIX} Maximum getter depth (${MAX_GETTER_DEPTH}) exceeded. Possible circular dependency in getter "${String(prop)}" on ${target.constructor.name}.`);
+				return;
+			}
+			if (context.visitedBlocs.has(target)) {
+				console.warn(`${BLAC_ERROR_PREFIX} Circular dependency detected: getter "${String(prop)}" on ${target.constructor.name}.`);
+				return;
+			}
+			const prevContext = {
+				tracker: context.tracker,
+				currentBloc: context.currentBloc,
+				depth: context.depth,
+				visitedBlocs: new Set(context.visitedBlocs)
+			};
+			context.tracker = tracker.getterState;
+			context.currentBloc = target;
+			context.depth++;
+			context.visitedBlocs.add(target);
+			try {
+				const getterValue = getDescriptor(target, prop).get.call(target);
+				tracker.getterState.trackedValues.set(prop, getterValue);
+				return getterValue;
+			} catch (error$1) {
+				tracker.getterState.currentlyAccessing.delete(prop);
+				throw error$1;
+			} finally {
+				context.tracker = prevContext.tracker;
+				context.currentBloc = prevContext.currentBloc;
+				context.depth = prevContext.depth;
+				context.visitedBlocs = prevContext.visitedBlocs;
+			}
+		}
+		return value;
+	} });
+}
+
+//#endregion
+//#region src/tracking/dependency-manager.ts
+/**
+* Manages subscriptions to state container dependencies.
+* Provides efficient sync mechanism to add/remove subscriptions
+* as dependencies change between callback invocations.
+*/
+var DependencyManager = class {
+	constructor() {
+		this.subscriptions = /* @__PURE__ */ new Map();
+		this.currentDeps = /* @__PURE__ */ new Set();
+	}
+	/**
+	* Sync subscriptions with a new set of dependencies.
+	* Adds subscriptions for new deps, removes subscriptions for stale deps.
+	*
+	* @param newDeps - The new set of dependencies to subscribe to
+	* @param onChange - Callback to invoke when any dependency changes
+	* @param exclude - Optional instance to exclude from subscriptions (e.g., primary bloc)
+	* @returns true if the dependency set changed, false if unchanged
+	*/
+	sync(newDeps, onChange, exclude) {
+		const filteredNewDeps = /* @__PURE__ */ new Set();
+		for (const dep of newDeps) if (dep !== exclude && !dep.isDisposed) filteredNewDeps.add(dep);
+		if (this.areSetsEqual(this.currentDeps, filteredNewDeps)) return false;
+		for (const dep of this.currentDeps) if (!filteredNewDeps.has(dep)) {
+			const unsub = this.subscriptions.get(dep);
+			if (unsub) {
+				unsub();
+				this.subscriptions.delete(dep);
+			}
+		}
+		for (const dep of filteredNewDeps) if (!this.currentDeps.has(dep) && !this.subscriptions.has(dep)) {
+			const unsub = dep.subscribe(onChange);
+			this.subscriptions.set(dep, unsub);
+		}
+		this.currentDeps = filteredNewDeps;
+		return true;
+	}
+	/**
+	* Add a single dependency subscription.
+	*/
+	add(dep, onChange) {
+		if (this.subscriptions.has(dep) || dep.isDisposed) return;
+		const unsub = dep.subscribe(onChange);
+		this.subscriptions.set(dep, unsub);
+		this.currentDeps.add(dep);
+	}
+	/**
+	* Check if a dependency is currently subscribed.
+	*/
+	has(dep) {
+		return this.currentDeps.has(dep);
+	}
+	/**
+	* Get the current set of dependencies.
+	*/
+	getDependencies() {
+		return new Set(this.currentDeps);
+	}
+	/**
+	* Clean up all active subscriptions.
+	*/
+	cleanup() {
+		for (const unsub of this.subscriptions.values()) unsub();
+		this.subscriptions.clear();
+		this.currentDeps.clear();
+	}
+	areSetsEqual(a, b) {
+		if (a.size !== b.size) return false;
+		for (const item of a) if (!b.has(item)) return false;
+		return true;
+	}
+};
+
+//#endregion
+//#region src/tracking/tracked.ts
+/**
+* Run a callback while tracking all bloc dependencies accessed.
+* Returns both the result and the set of discovered dependencies.
+*
+* @example
+* ```ts
+* const { result, dependencies } = tracked(() => {
+*   const user = ensure(UserBloc);
+*   return user.fullName; // getter that may access other blocs
+* });
+* // dependencies contains UserBloc + any blocs accessed in fullName getter
+* ```
+*/
+function tracked(callback, options) {
+	const tracker = createState();
+	startTracking(tracker);
+	let result;
+	try {
+		result = callback();
+	} finally {
+		stopTracking(tracker, { state: null });
+	}
+	const dependencies = new Set(tracker.dependencies);
+	for (const dep of tracker.getterState.externalDependencies) dependencies.add(dep);
+	if (options?.exclude) dependencies.delete(options.exclude);
+	return {
+		result,
+		dependencies
+	};
+}
+/**
+* Context for running tracked callbacks with bloc proxies.
+* Provides methods to create proxies and check for changes.
+*/
+var TrackedContext = class {
+	constructor() {
+		this.proxiedBlocs = /* @__PURE__ */ new WeakMap();
+		this.primaryBlocs = /* @__PURE__ */ new Set();
+		this.tracker = createState();
+	}
+	/**
+	* Get a tracking proxy for a bloc instance.
+	* The proxy will track state and getter accesses.
+	*/
+	proxy(bloc) {
+		const cached = this.proxiedBlocs.get(bloc);
+		if (cached) return cached;
+		const proxied = createTrackingProxy(bloc, this.tracker);
+		this.proxiedBlocs.set(bloc, proxied);
+		this.primaryBlocs.add(bloc);
+		return proxied;
+	}
+	/**
+	* Start tracking for a new callback execution.
+	*/
+	start() {
+		startTracking(this.tracker);
+	}
+	/**
+	* Stop tracking and get discovered dependencies.
+	* Excludes primary blocs (those explicitly proxied via proxy()).
+	*/
+	stop() {
+		const allDeps = /* @__PURE__ */ new Set();
+		for (const bloc of this.primaryBlocs) {
+			const deps = stopTracking(this.tracker, bloc);
+			for (const dep of deps) if (!this.primaryBlocs.has(dep)) allDeps.add(dep);
+		}
+		for (const dep of this.tracker.getterState.externalDependencies) if (!this.primaryBlocs.has(dep)) allDeps.add(dep);
+		return allDeps;
+	}
+	/**
+	* Check if any tracked state or getters have changed.
+	*/
+	changed() {
+		for (const bloc of this.primaryBlocs) if (hasChanges(this.tracker, bloc)) return true;
+		return false;
+	}
+	/**
+	* Get all primary blocs (those explicitly proxied).
+	*/
+	getPrimaryBlocs() {
+		return new Set(this.primaryBlocs);
+	}
+	/**
+	* Reset the context for reuse.
+	*/
+	reset() {
+		this.tracker = createState();
+		this.proxiedBlocs = /* @__PURE__ */ new WeakMap();
+		this.primaryBlocs.clear();
+	}
+};
+/**
+* Create a new tracked context for manual control over tracking.
+*/
+function createTrackedContext() {
+	return new TrackedContext();
 }
 
 //#endregion
@@ -1711,16 +2149,13 @@ function hasTrackedData(tracker) {
 * Manages subscriptions to external bloc dependencies for getter tracking.
 * When a getter accesses another bloc's state, this manager ensures
 * re-renders occur when those external dependencies change.
+*
+* @deprecated Use DependencyManager from tracking module instead.
+* This class is kept for backward compatibility.
 */
-var ExternalDependencyManager = class {
+var ExternalDepsManager = class {
 	constructor() {
-		this.subscriptions = [];
-		this.previousDeps = /* @__PURE__ */ new Set();
-	}
-	areDependenciesEqual(oldDeps, newDeps) {
-		if (oldDeps.size !== newDeps.size) return false;
-		for (const dep of newDeps) if (!oldDeps.has(dep)) return false;
-		return true;
+		this.manager = new DependencyManager();
 	}
 	/**
 	* Update subscriptions to external bloc dependencies.
@@ -1730,32 +2165,22 @@ var ExternalDependencyManager = class {
 	* @param onGetterChange - Callback to invoke when external dependency changes
 	* @returns true if subscriptions were updated, false if unchanged
 	*/
-	updateSubscriptions(getterTracker, rawInstance, onGetterChange) {
-		if (!getterTracker?.externalDependencies) return false;
-		const currentDeps = getterTracker.externalDependencies;
-		if (this.areDependenciesEqual(this.previousDeps, currentDeps)) {
-			clearExternalDependencies(getterTracker);
-			return false;
-		}
-		this.cleanup();
-		for (const externalBloc of currentDeps) {
-			if (externalBloc === rawInstance) continue;
-			const unsub = externalBloc.subscribe(() => {
-				invalidateRenderCache(getterTracker);
-				if (hasGetterChanges(rawInstance, getterTracker)) onGetterChange();
-			});
-			this.subscriptions.push(unsub);
-		}
-		this.previousDeps = new Set(currentDeps);
-		clearExternalDependencies(getterTracker);
-		return true;
+	updateSubscriptions(getterState, rawInstance, onGetterChange) {
+		if (!getterState?.externalDependencies) return false;
+		const currentDeps = getterState.externalDependencies;
+		const onExternalChange = () => {
+			invalidateRenderCache(getterState);
+			if (hasGetterChanges(rawInstance, getterState)) onGetterChange();
+		};
+		const changed = this.manager.sync(currentDeps, onExternalChange, rawInstance);
+		clearExternalDependencies(getterState);
+		return changed;
 	}
 	/**
 	* Clean up all active subscriptions
 	*/
 	cleanup() {
-		this.subscriptions.forEach((unsub) => unsub());
-		this.subscriptions = [];
+		this.manager.cleanup();
 	}
 };
 /**
@@ -1765,21 +2190,21 @@ var ExternalDependencyManager = class {
 * @param adapterState - The adapter state for tracking
 * @returns Subscribe function for use with useSyncExternalStore
 */
-function createAutoTrackSubscribe(instance, adapterState) {
+function autoTrackSubscribe(instance$1, adapterState) {
 	return (callback) => {
-		return instance.subscribe(() => {
-			const tracker = adapterState.tracker || (adapterState.tracker = createTrackerState());
-			const hasStateDeps = tracker.pathCache && tracker.pathCache.size > 0;
-			const hasGetterDeps = adapterState.getterTracker && adapterState.getterTracker.trackedGetters.size > 0;
-			const isPrimitiveState = instance.state !== null && typeof instance.state !== "object" && typeof instance.state !== "function";
+		return instance$1.subscribe(() => {
+			const depState = adapterState.dependencyState || (adapterState.dependencyState = createDependencyState());
+			const hasStateDeps = depState.pathCache && depState.pathCache.size > 0;
+			const hasGetterDeps = adapterState.getterState && adapterState.getterState.trackedGetters.size > 0;
+			const isPrimitiveState = instance$1.state !== null && typeof instance$1.state !== "object" && typeof instance$1.state !== "function";
 			if (!hasStateDeps && !hasGetterDeps && !isPrimitiveState) return;
-			let stateChanged = hasChanges(tracker, instance.state);
+			let stateChanged = hasDependencyChanges(depState, instance$1.state);
 			if (!hasStateDeps && hasGetterDeps) stateChanged = false;
 			if (stateChanged) {
 				callback();
 				return;
 			}
-			if (hasGetterChanges(instance, adapterState.getterTracker)) callback();
+			if (hasGetterChanges(instance$1, adapterState.getterState)) callback();
 		});
 	};
 }
@@ -1791,10 +2216,10 @@ function createAutoTrackSubscribe(instance, adapterState) {
 * @param config - Configuration with dependencies function
 * @returns Subscribe function for use with useSyncExternalStore
 */
-function createManualDepsSubscribe(instance, adapterState, config) {
+function manualDepsSubscribe(instance$1, adapterState, config) {
 	return (callback) => {
-		return instance.subscribe(() => {
-			const newDeps = config.dependencies(instance.state, instance);
+		return instance$1.subscribe(() => {
+			const newDeps = config.dependencies(instance$1.state, instance$1);
 			if (!adapterState.manualDepsCache || !shallowEqual(adapterState.manualDepsCache, newDeps)) {
 				adapterState.manualDepsCache = newDeps;
 				callback();
@@ -1808,8 +2233,8 @@ function createManualDepsSubscribe(instance, adapterState, config) {
 * @param instance - The state container instance
 * @returns Subscribe function for use with useSyncExternalStore
 */
-function createNoTrackSubscribe(instance) {
-	return (callback) => instance.subscribe(callback);
+function noTrackSubscribe(instance$1) {
+	return (callback) => instance$1.subscribe(callback);
 }
 /**
 * Create a snapshot function for auto-tracking mode.
@@ -1818,18 +2243,18 @@ function createNoTrackSubscribe(instance) {
 * @param adapterState - The adapter state for tracking
 * @returns Snapshot function for use with useSyncExternalStore
 */
-function createAutoTrackSnapshot(instance, adapterState) {
+function autoTrackSnapshot(instance$1, adapterState) {
 	return () => {
-		const tracker = adapterState.tracker || (adapterState.tracker = createTrackerState());
-		if (hasTrackedData(tracker)) captureTrackedPaths(tracker, instance.state);
-		if (adapterState.getterTracker) {
-			invalidateRenderCache(adapterState.getterTracker);
-			commitTrackedGetters(adapterState.getterTracker);
-			adapterState.getterTracker.isTracking = true;
-			setActiveTracker(instance, adapterState.getterTracker);
+		const depState = adapterState.dependencyState || (adapterState.dependencyState = createDependencyState());
+		if (hasTrackedData(depState)) capturePaths(depState, instance$1.state);
+		if (adapterState.getterState) {
+			invalidateRenderCache(adapterState.getterState);
+			commitTrackedGetters(adapterState.getterState);
+			adapterState.getterState.isTracking = true;
+			setActiveTracker(instance$1, adapterState.getterState);
 		}
-		startTracking(tracker);
-		return createProxy(tracker, instance.state);
+		startDependency(depState);
+		return createDependencyProxy(depState, instance$1.state);
 	};
 }
 /**
@@ -1840,10 +2265,10 @@ function createAutoTrackSnapshot(instance, adapterState) {
 * @param config - Configuration with dependencies function
 * @returns Snapshot function for use with useSyncExternalStore
 */
-function createManualDepsSnapshot(instance, adapterState, config) {
+function manualDepsSnapshot(instance$1, adapterState, config) {
 	return () => {
-		adapterState.manualDepsCache = config.dependencies(instance.state, instance);
-		return instance.state;
+		adapterState.manualDepsCache = config.dependencies(instance$1.state, instance$1);
+		return instance$1.state;
 	};
 }
 /**
@@ -1852,8 +2277,8 @@ function createManualDepsSnapshot(instance, adapterState, config) {
 * @param instance - The state container instance
 * @returns Snapshot function for use with useSyncExternalStore
 */
-function createNoTrackSnapshot(instance) {
-	return () => instance.state;
+function noTrackSnapshot(instance$1) {
+	return () => instance$1.state;
 }
 /**
 * Initialize adapter state for auto-tracking mode.
@@ -1861,12 +2286,12 @@ function createNoTrackSnapshot(instance) {
 * @param instance - The state container instance
 * @returns Initialized adapter state
 */
-function initAutoTrackState(instance) {
+function autoTrackInit(instance$1) {
 	return {
-		tracker: null,
+		dependencyState: null,
 		manualDepsCache: null,
-		getterTracker: createGetterTracker(),
-		proxiedBloc: createBlocProxy(instance)
+		getterState: createGetterState(),
+		proxiedBloc: createBlocProxy(instance$1)
 	};
 }
 /**
@@ -1875,12 +2300,12 @@ function initAutoTrackState(instance) {
 * @param instance - The state container instance
 * @returns Initialized adapter state
 */
-function initManualDepsState(instance) {
+function manualDepsInit(instance$1) {
 	return {
-		tracker: null,
+		dependencyState: null,
 		manualDepsCache: null,
-		getterTracker: null,
-		proxiedBloc: instance
+		getterState: null,
+		proxiedBloc: instance$1
 	};
 }
 /**
@@ -1889,12 +2314,12 @@ function initManualDepsState(instance) {
 * @param instance - The state container instance
 * @returns Initialized adapter state
 */
-function initNoTrackState(instance) {
+function noTrackInit(instance$1) {
 	return {
-		tracker: null,
+		dependencyState: null,
 		manualDepsCache: null,
-		getterTracker: null,
-		proxiedBloc: instance
+		getterState: null,
+		proxiedBloc: instance$1
 	};
 }
 /**
@@ -1904,8 +2329,8 @@ function initNoTrackState(instance) {
 * @param rawInstance - The raw bloc instance
 */
 function disableGetterTracking(adapterState, rawInstance) {
-	if (adapterState.getterTracker) {
-		adapterState.getterTracker.isTracking = false;
+	if (adapterState.getterState) {
+		adapterState.getterState.isTracking = false;
 		clearActiveTracker(rawInstance);
 	}
 }
@@ -2037,6 +2462,67 @@ function configureLogger(opts) {
 	defaultLogger = createLogger(currentConfig);
 }
 
+//#endregion
+//#region src/config.ts
+const defaultConfig = {
+	devMode: process.env.NODE_ENV !== "production",
+	logger: {
+		enabled: false,
+		level: LogLevel.INFO
+	}
+};
+let globalConfig = { ...defaultConfig };
+/**
+* Configure global defaults for @blac/core.
+*
+* @example
+* ```ts
+* import { configureBlac, LogLevel } from '@blac/core';
+*
+* configureBlac({
+*   devMode: true,
+*   logger: {
+*     enabled: true,
+*     level: LogLevel.DEBUG
+*   }
+* });
+* ```
+*
+* @param config - Partial configuration to merge with defaults
+*/
+function configureBlac(config) {
+	globalConfig = {
+		...globalConfig,
+		...config,
+		logger: {
+			...globalConfig.logger,
+			...config.logger
+		}
+	};
+	if (config.logger) configureLogger(config.logger);
+}
+/**
+* Get the current global configuration.
+* @internal
+*/
+function getBlacConfig() {
+	return globalConfig;
+}
+/**
+* Check if development mode is enabled.
+*/
+function isDevMode() {
+	return globalConfig.devMode;
+}
+/**
+* Reset configuration to defaults (useful for testing).
+* @internal
+*/
+function resetBlacConfig() {
+	globalConfig = { ...defaultConfig };
+	configureLogger(defaultConfig.logger);
+}
+
 //#endregion
 //#region src/decorators/blac.ts
 /**
@@ -2071,5 +2557,328 @@ function blac(options) {
 }
 
 //#endregion
-export { BLAC_DEFAULTS, BLAC_ERROR_PREFIX, BLAC_ID_PATTERNS, BLAC_STATIC_PROPS, Cubit, ExternalDependencyManager, LogLevel, PluginManager, StateContainer, StateContainerRegistry, Vertex, __resetIdCounters, blac, captureTrackedPaths, clearActiveTracker, clearExternalDependencies, commitTrackedGetters, configureLogger, createArrayProxy, createAutoTrackSnapshot, createAutoTrackSubscribe, createBlocProxy, createGetterTracker, createIdGenerator, createLogger, createManualDepsSnapshot, createManualDepsSubscribe, createNoTrackSnapshot, createNoTrackSubscribe, createPluginManager, createProxy, createProxyForTarget, createProxyInternal, createProxyTrackerState, createTrackerState, debug, disableGetterTracking, error, generateId, generateIsolatedKey, generateSimpleId, getActiveTracker, getDescriptor, getGetterExecutionContext, getPluginManager, getStaticProp, getValueAtPath, globalRegistry, hasChanges, hasGetterChanges, hasInitHook, hasTrackedData, info, initAutoTrackState, initManualDepsState, initNoTrackState, invalidateRenderCache, isExcludedFromDevTools, isGetter, isIsolatedClass, isIsolatedKey, isKeepAliveClass, isProxyable, parsePath, resetGetterTracker, setActiveTracker, shallowEqual, startProxyTracking, startTracking, stopProxyTracking, warn };
+//#region src/registry/acquire.ts
+function acquire(BlocClass, instanceKey, options) {
+	return globalRegistry.acquire(BlocClass, instanceKey, {
+		canCreate: true,
+		countRef: true,
+		props: options?.props
+	});
+}
+
+//#endregion
+//#region src/registry/borrow.ts
+function borrow(BlocClass, instanceKey) {
+	return globalRegistry.borrow(BlocClass, instanceKey);
+}
+function borrowSafe(BlocClass, instanceKey) {
+	return globalRegistry.borrowSafe(BlocClass, instanceKey);
+}
+
+//#endregion
+//#region src/registry/ensure.ts
+function ensure(BlocClass, instanceKey) {
+	return globalRegistry.ensure(BlocClass, instanceKey);
+}
+
+//#endregion
+//#region src/registry/release.ts
+function release(BlocClass, instanceKey, forceDispose = false) {
+	globalRegistry.release(BlocClass, instanceKey, forceDispose);
+}
+
+//#endregion
+//#region src/registry/queries.ts
+function hasInstance(BlocClass, instanceKey) {
+	return globalRegistry.hasInstance(BlocClass, instanceKey);
+}
+function getRefCount(BlocClass, instanceKey) {
+	return globalRegistry.getRefCount(BlocClass, instanceKey);
+}
+function getAll(BlocClass) {
+	return globalRegistry.getAll(BlocClass);
+}
+function forEach(BlocClass, callback) {
+	globalRegistry.forEach(BlocClass, callback);
+}
+
+//#endregion
+//#region src/registry/management.ts
+function clear(BlocClass) {
+	globalRegistry.clear(BlocClass);
+}
+function clearAll() {
+	globalRegistry.clearAll();
+}
+function register(BlocClass, isolated = false) {
+	globalRegistry.register(BlocClass, isolated);
+}
+
+//#endregion
+//#region src/registry/config.ts
+let _registry = globalRegistry;
+function getRegistry() {
+	return _registry;
+}
+function setRegistry(registry) {
+	_registry.clearAll();
+	_registry = registry;
+}
+function getStats() {
+	return _registry.getStats();
+}
+
+//#endregion
+//#region src/waitUntil/errors.ts
+var WaitUntilTimeoutError = class extends Error {
+	constructor(timeout) {
+		super(`waitUntil timed out after ${timeout}ms`);
+		this.name = "WaitUntilTimeoutError";
+	}
+};
+var WaitUntilAbortedError = class extends Error {
+	constructor() {
+		super("waitUntil was aborted");
+		this.name = "WaitUntilAbortedError";
+	}
+};
+var WaitUntilDisposedError = class extends Error {
+	constructor(blocName) {
+		super(`waitUntil failed: ${blocName} was disposed while waiting`);
+		this.name = "WaitUntilDisposedError";
+	}
+};
+
+//#endregion
+//#region src/waitUntil/waitUntil.ts
+function waitUntil(BlocClass, selectorOrPredicate, predicateOrOptions, maybeOptions) {
+	if (typeof predicateOrOptions !== "function") return waitUntilSimple(BlocClass, selectorOrPredicate, predicateOrOptions);
+	else return waitUntilSelector(BlocClass, selectorOrPredicate, predicateOrOptions, maybeOptions);
+}
+function waitUntilSimple(BlocClass, predicate, options) {
+	const { instanceId = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, timeout, signal } = options ?? {};
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new WaitUntilAbortedError());
+			return;
+		}
+		const bloc = ensure(BlocClass, instanceId);
+		if (bloc.isDisposed) {
+			reject(new WaitUntilDisposedError(BlocClass.name));
+			return;
+		}
+		const tracker = createState();
+		const proxiedBloc = createTrackingProxy(bloc, tracker);
+		const externalDepsManager = new DependencyManager();
+		const runPredicate = () => {
+			startTracking(tracker);
+			try {
+				return predicate(proxiedBloc);
+			} finally {
+				const deps = stopTracking(tracker, bloc);
+				for (const dep of tracker.getterState.externalDependencies) deps.add(dep);
+				deps.delete(bloc);
+				externalDepsManager.sync(deps, checkCondition, bloc);
+			}
+		};
+		if (runPredicate()) {
+			resolve(bloc);
+			return;
+		}
+		let unsubscribe = null;
+		let unsubscribeDispose = null;
+		let timeoutId = null;
+		let abortHandler = null;
+		const cleanup = () => {
+			unsubscribe?.();
+			unsubscribeDispose?.();
+			externalDepsManager.cleanup();
+			if (timeoutId) clearTimeout(timeoutId);
+			if (abortHandler && signal) signal.removeEventListener("abort", abortHandler);
+		};
+		function checkCondition() {
+			try {
+				if (runPredicate()) {
+					cleanup();
+					resolve(bloc);
+				}
+			} catch (error$1) {
+				cleanup();
+				reject(error$1);
+			}
+		}
+		unsubscribe = bloc.subscribe(checkCondition);
+		unsubscribeDispose = getRegistry().on("disposed", (instance$1) => {
+			if (instance$1 === bloc) {
+				cleanup();
+				reject(new WaitUntilDisposedError(BlocClass.name));
+			}
+		});
+		if (timeout !== void 0) timeoutId = setTimeout(() => {
+			cleanup();
+			reject(new WaitUntilTimeoutError(timeout));
+		}, timeout);
+		if (signal) {
+			abortHandler = () => {
+				cleanup();
+				reject(new WaitUntilAbortedError());
+			};
+			signal.addEventListener("abort", abortHandler);
+		}
+	});
+}
+function waitUntilSelector(BlocClass, selector, predicate, options) {
+	const { instanceId = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, timeout, signal } = options ?? {};
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new WaitUntilAbortedError());
+			return;
+		}
+		const bloc = ensure(BlocClass, instanceId);
+		if (bloc.isDisposed) {
+			reject(new WaitUntilDisposedError(BlocClass.name));
+			return;
+		}
+		const tracker = createState();
+		const proxiedBloc = createTrackingProxy(bloc, tracker);
+		const externalDepsManager = new DependencyManager();
+		const runSelector = () => {
+			startTracking(tracker);
+			try {
+				const value = selector(proxiedBloc);
+				return {
+					value,
+					matches: predicate(value)
+				};
+			} finally {
+				const deps = stopTracking(tracker, bloc);
+				for (const dep of tracker.getterState.externalDependencies) deps.add(dep);
+				deps.delete(bloc);
+				externalDepsManager.sync(deps, checkCondition, bloc);
+			}
+		};
+		const initial = runSelector();
+		if (initial.matches) {
+			resolve(initial.value);
+			return;
+		}
+		let unsubscribe = null;
+		let unsubscribeDispose = null;
+		let timeoutId = null;
+		let abortHandler = null;
+		const cleanup = () => {
+			unsubscribe?.();
+			unsubscribeDispose?.();
+			externalDepsManager.cleanup();
+			if (timeoutId) clearTimeout(timeoutId);
+			if (abortHandler && signal) signal.removeEventListener("abort", abortHandler);
+		};
+		function checkCondition() {
+			try {
+				const result = runSelector();
+				if (result.matches) {
+					cleanup();
+					resolve(result.value);
+				}
+			} catch (error$1) {
+				cleanup();
+				reject(error$1);
+			}
+		}
+		unsubscribe = bloc.subscribe(checkCondition);
+		unsubscribeDispose = getRegistry().on("disposed", (instance$1) => {
+			if (instance$1 === bloc) {
+				cleanup();
+				reject(new WaitUntilDisposedError(BlocClass.name));
+			}
+		});
+		if (timeout !== void 0) timeoutId = setTimeout(() => {
+			cleanup();
+			reject(new WaitUntilTimeoutError(timeout));
+		}, timeout);
+		if (signal) {
+			abortHandler = () => {
+				cleanup();
+				reject(new WaitUntilAbortedError());
+			};
+			signal.addEventListener("abort", abortHandler);
+		}
+	});
+}
+
+//#endregion
+//#region src/watch/watch.ts
+const STOP = Symbol("watch.STOP");
+const BLOC_REF_MARKER = Symbol("BlocRef");
+/**
+* Create a reference to a specific bloc instance.
+*
+* @example
+* ```ts
+* watch(instance(UserBloc, 'user-123'), (userBloc) => {
+*   console.log(userBloc.state.name);
+* });
+* ```
+*/
+function instance(BlocClass, instanceId) {
+	return {
+		[BLOC_REF_MARKER]: true,
+		blocClass: BlocClass,
+		instanceId
+	};
+}
+function isBlocRef(input) {
+	return typeof input === "object" && input !== null && BLOC_REF_MARKER in input;
+}
+function resolveBloc(input) {
+	if (isBlocRef(input)) return ensure(input.blocClass, input.instanceId);
+	return ensure(input, BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY);
+}
+function isArray(input) {
+	return Array.isArray(input);
+}
+function watchImpl(blocsOrBloc, callback) {
+	const isSingle = !isArray(blocsOrBloc);
+	const instances = (isSingle ? [blocsOrBloc] : blocsOrBloc).map(resolveBloc);
+	const tracker = createState();
+	const proxiedInstances = instances.map((inst) => createTrackingProxy(inst, tracker));
+	const externalDepsManager = new DependencyManager();
+	let disposed = false;
+	const primarySubscriptions = [];
+	const cleanup = () => {
+		if (disposed) return;
+		disposed = true;
+		primarySubscriptions.forEach((unsub) => unsub());
+		externalDepsManager.cleanup();
+	};
+	const runCallback = () => {
+		if (disposed) return;
+		startTracking(tracker);
+		let result;
+		try {
+			result = callback(isSingle ? proxiedInstances[0] : proxiedInstances);
+		} finally {
+			const externalDeps = /* @__PURE__ */ new Set();
+			for (const inst of instances) {
+				const deps = stopTracking(tracker, inst);
+				for (const dep of deps) externalDeps.add(dep);
+			}
+			for (const dep of tracker.getterState.externalDependencies) externalDeps.add(dep);
+			for (const inst of instances) externalDeps.delete(inst);
+			externalDepsManager.sync(externalDeps, runCallback);
+		}
+		if (result === STOP) cleanup();
+	};
+	const onChange = () => {
+		if (disposed) return;
+		runCallback();
+	};
+	for (const inst of instances) primarySubscriptions.push(inst.subscribe(onChange));
+	runCallback();
+	return cleanup;
+}
+const watch = Object.assign(watchImpl, { STOP });
+
+//#endregion
+export { BLAC_DEFAULTS, BLAC_ERROR_PREFIX, BLAC_ID_PATTERNS, BLAC_STATIC_PROPS, Cubit, DependencyManager, ExternalDepsManager, LogLevel, PluginManager, STATELESS_MARKER, StateContainer, StateContainerRegistry, StatelessCubit, StatelessVertex, TrackedContext, Vertex, WaitUntilAbortedError, WaitUntilDisposedError, WaitUntilTimeoutError, __resetIdCounters, acquire, autoTrackInit, autoTrackSnapshot, autoTrackSubscribe, blac, borrow, borrowSafe, capturePaths, clear, clearActiveTracker, clearAll, clearExternalDependencies, commitTrackedGetters, configureBlac, configureLogger, createArrayProxy, createBlocProxy, createDependencyProxy, createDependencyState, createForTarget, createGetterState, createIdGenerator, createInternal, createLogger, createPluginManager, createProxyState, createTrackedContext, createTrackingProxy, createState as createTrackingProxyState, debug, disableGetterTracking, ensure, error, forEach, generateId, generateIsolatedKey, generateSimpleId, getActiveTracker, getAll, getBlacConfig, getDescriptor, getGetterExecutionContext, getPluginManager, getRefCount, getRegistry, getStaticProp, getStats, getValueAtPath, globalRegistry, hasDependencyChanges, hasGetterChanges, hasInitHook, hasInstance, hasTrackedData, hasChanges as hasTrackingProxyChanges, info, instance, invalidateRenderCache, isDevMode, isExcludedFromDevTools, isGetter, isIsolatedClass, isIsolatedKey, isKeepAliveClass, isProxyable, isStatelessClass, manualDepsInit, manualDepsSnapshot, manualDepsSubscribe, noTrackInit, noTrackSnapshot, noTrackSubscribe, parsePath, register, release, resetBlacConfig, resetGetterState, setActiveTracker, setRegistry, shallowEqual, startDependency, startProxy, startTracking as startTrackingProxy, stopProxy, stopTracking as stopTrackingProxy, tracked, waitUntil, warn, watch };
 //# sourceMappingURL=index.js.map