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

package/dist/index.cjs

@@ -196,17 +196,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);
 		});
 	}
 	/**
@@ -228,23 +228,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();
@@ -336,7 +336,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
 */
@@ -373,7 +373,7 @@ function isGetter(obj, prop) {
 /**
 * @internal
 */
-function createGetterTracker() {
+function createGetterState() {
 	return {
 		trackedValues: /* @__PURE__ */ new Map(),
 		currentlyAccessing: /* @__PURE__ */ new Set(),
@@ -424,8 +424,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)) {
@@ -501,7 +501,7 @@ function clearExternalDependencies(tracker) {
 /**
 * @internal
 */
-function resetGetterTracker(tracker) {
+function resetGetterState(tracker) {
 	tracker.trackedValues.clear();
 	tracker.currentlyAccessing.clear();
 	tracker.trackedGetters.clear();
@@ -511,6 +511,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
 /**
@@ -555,6 +568,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
@@ -565,7 +587,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);
 * });
@@ -612,34 +635,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);
@@ -649,42 +673,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 {
@@ -694,7 +718,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.
 	*
@@ -704,8 +728,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
@@ -754,9 +778,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);
 			}
@@ -834,9 +858,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);
 		};
@@ -898,132 +922,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() {
@@ -1063,7 +962,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() {
@@ -1094,7 +993,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`);
 	}
 	/**
@@ -1117,12 +1016,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 {
@@ -1281,7 +1177,7 @@ var Vertex = class extends StateContainer {
 		this.eventQueue = [];
 		this.add = (event) => {
 			const enrichedEvent = this.enrichEvent(event);
-			StateContainer._registry.emit("eventAdded", this, enrichedEvent);
+			globalRegistry.emit("eventAdded", this, enrichedEvent);
 			this.processEvent(enrichedEvent);
 		};
 	}
@@ -1345,6 +1241,223 @@ var Vertex = class extends StateContainer {
 	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 ${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) {}
+	/**
+	* 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
 //#region src/plugin/BlacPlugin.ts
 /**
@@ -1392,7 +1505,7 @@ function isProxyable(value) {
 *
 * @internal
 */
-function createProxyTrackerState() {
+function createProxyState() {
 	return {
 		trackedPaths: /* @__PURE__ */ new Set(),
 		isTracking: false,
@@ -1410,7 +1523,7 @@ function createProxyTrackerState() {
 *
 * @internal
 */
-function startProxyTracking(state) {
+function startProxy(state) {
 	state.isTracking = true;
 	state.trackedPaths.clear();
 }
@@ -1421,7 +1534,7 @@ function startProxyTracking(state) {
 *
 * @internal
 */
-function stopProxyTracking(state) {
+function stopProxy(state) {
 	state.isTracking = false;
 	return new Set(state.trackedPaths);
 }
@@ -1460,7 +1573,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;
 	} });
@@ -1481,7 +1594,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);
@@ -1502,7 +1615,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) => {
@@ -1530,11 +1643,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;
@@ -1675,9 +1788,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(),
@@ -1688,21 +1801,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);
@@ -1723,7 +1836,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()) {
@@ -1741,7 +1854,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
@@ -1750,16 +2150,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.
@@ -1769,32 +2166,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();
 	}
 };
 /**
@@ -1804,21 +2191,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();
 		});
 	};
 }
@@ -1830,10 +2217,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();
@@ -1847,8 +2234,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.
@@ -1857,18 +2244,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);
 	};
 }
 /**
@@ -1879,10 +2266,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;
 	};
 }
 /**
@@ -1891,8 +2278,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.
@@ -1900,12 +2287,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)
 	};
 }
 /**
@@ -1914,12 +2301,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
 	};
 }
 /**
@@ -1928,12 +2315,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
 	};
 }
 /**
@@ -1943,8 +2330,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);
 	}
 }
@@ -2170,65 +2557,407 @@ function blac(options) {
 	};
 }
 
+//#endregion
+//#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
 exports.BLAC_DEFAULTS = BLAC_DEFAULTS;
 exports.BLAC_ERROR_PREFIX = BLAC_ERROR_PREFIX;
 exports.BLAC_ID_PATTERNS = BLAC_ID_PATTERNS;
 exports.BLAC_STATIC_PROPS = BLAC_STATIC_PROPS;
 exports.Cubit = Cubit;
-exports.ExternalDependencyManager = ExternalDependencyManager;
+exports.DependencyManager = DependencyManager;
+exports.ExternalDepsManager = ExternalDepsManager;
 exports.LogLevel = LogLevel;
 exports.PluginManager = PluginManager;
+exports.STATELESS_MARKER = STATELESS_MARKER;
 exports.StateContainer = StateContainer;
 exports.StateContainerRegistry = StateContainerRegistry;
+exports.StatelessCubit = StatelessCubit;
+exports.StatelessVertex = StatelessVertex;
+exports.TrackedContext = TrackedContext;
 exports.Vertex = Vertex;
+exports.WaitUntilAbortedError = WaitUntilAbortedError;
+exports.WaitUntilDisposedError = WaitUntilDisposedError;
+exports.WaitUntilTimeoutError = WaitUntilTimeoutError;
 exports.__resetIdCounters = __resetIdCounters;
+exports.acquire = acquire;
+exports.autoTrackInit = autoTrackInit;
+exports.autoTrackSnapshot = autoTrackSnapshot;
+exports.autoTrackSubscribe = autoTrackSubscribe;
 exports.blac = blac;
-exports.captureTrackedPaths = captureTrackedPaths;
+exports.borrow = borrow;
+exports.borrowSafe = borrowSafe;
+exports.capturePaths = capturePaths;
+exports.clear = clear;
 exports.clearActiveTracker = clearActiveTracker;
+exports.clearAll = clearAll;
 exports.clearExternalDependencies = clearExternalDependencies;
 exports.commitTrackedGetters = commitTrackedGetters;
 exports.configureBlac = configureBlac;
 exports.configureLogger = configureLogger;
 exports.createArrayProxy = createArrayProxy;
-exports.createAutoTrackSnapshot = createAutoTrackSnapshot;
-exports.createAutoTrackSubscribe = createAutoTrackSubscribe;
 exports.createBlocProxy = createBlocProxy;
-exports.createGetterTracker = createGetterTracker;
+exports.createDependencyProxy = createDependencyProxy;
+exports.createDependencyState = createDependencyState;
+exports.createForTarget = createForTarget;
+exports.createGetterState = createGetterState;
 exports.createIdGenerator = createIdGenerator;
+exports.createInternal = createInternal;
 exports.createLogger = createLogger;
-exports.createManualDepsSnapshot = createManualDepsSnapshot;
-exports.createManualDepsSubscribe = createManualDepsSubscribe;
-exports.createNoTrackSnapshot = createNoTrackSnapshot;
-exports.createNoTrackSubscribe = createNoTrackSubscribe;
 exports.createPluginManager = createPluginManager;
-exports.createProxy = createProxy;
-exports.createProxyForTarget = createProxyForTarget;
-exports.createProxyInternal = createProxyInternal;
-exports.createProxyTrackerState = createProxyTrackerState;
-exports.createTrackerState = createTrackerState;
+exports.createProxyState = createProxyState;
+exports.createTrackedContext = createTrackedContext;
+exports.createTrackingProxy = createTrackingProxy;
+exports.createTrackingProxyState = createState;
 exports.debug = debug;
 exports.disableGetterTracking = disableGetterTracking;
+exports.ensure = ensure;
 exports.error = error;
+exports.forEach = forEach;
 exports.generateId = generateId;
 exports.generateIsolatedKey = generateIsolatedKey;
 exports.generateSimpleId = generateSimpleId;
 exports.getActiveTracker = getActiveTracker;
+exports.getAll = getAll;
 exports.getBlacConfig = getBlacConfig;
 exports.getDescriptor = getDescriptor;
 exports.getGetterExecutionContext = getGetterExecutionContext;
 exports.getPluginManager = getPluginManager;
+exports.getRefCount = getRefCount;
+exports.getRegistry = getRegistry;
 exports.getStaticProp = getStaticProp;
+exports.getStats = getStats;
 exports.getValueAtPath = getValueAtPath;
 exports.globalRegistry = globalRegistry;
-exports.hasChanges = hasChanges;
+exports.hasDependencyChanges = hasDependencyChanges;
 exports.hasGetterChanges = hasGetterChanges;
 exports.hasInitHook = hasInitHook;
+exports.hasInstance = hasInstance;
 exports.hasTrackedData = hasTrackedData;
+exports.hasTrackingProxyChanges = hasChanges;
 exports.info = info;
-exports.initAutoTrackState = initAutoTrackState;
-exports.initManualDepsState = initManualDepsState;
-exports.initNoTrackState = initNoTrackState;
+exports.instance = instance;
 exports.invalidateRenderCache = invalidateRenderCache;
 exports.isDevMode = isDevMode;
 exports.isExcludedFromDevTools = isExcludedFromDevTools;
@@ -2237,13 +2966,28 @@ exports.isIsolatedClass = isIsolatedClass;
 exports.isIsolatedKey = isIsolatedKey;
 exports.isKeepAliveClass = isKeepAliveClass;
 exports.isProxyable = isProxyable;
+exports.isStatelessClass = isStatelessClass;
+exports.manualDepsInit = manualDepsInit;
+exports.manualDepsSnapshot = manualDepsSnapshot;
+exports.manualDepsSubscribe = manualDepsSubscribe;
+exports.noTrackInit = noTrackInit;
+exports.noTrackSnapshot = noTrackSnapshot;
+exports.noTrackSubscribe = noTrackSubscribe;
 exports.parsePath = parsePath;
+exports.register = register;
+exports.release = release;
 exports.resetBlacConfig = resetBlacConfig;
-exports.resetGetterTracker = resetGetterTracker;
+exports.resetGetterState = resetGetterState;
 exports.setActiveTracker = setActiveTracker;
+exports.setRegistry = setRegistry;
 exports.shallowEqual = shallowEqual;
-exports.startProxyTracking = startProxyTracking;
-exports.startTracking = startTracking;
-exports.stopProxyTracking = stopProxyTracking;
+exports.startDependency = startDependency;
+exports.startProxy = startProxy;
+exports.startTrackingProxy = startTracking;
+exports.stopProxy = stopProxy;
+exports.stopTrackingProxy = stopTracking;
+exports.tracked = tracked;
+exports.waitUntil = waitUntil;
 exports.warn = warn;
+exports.watch = watch;
 //# sourceMappingURL=index.cjs.map