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

package/dist/index.d.ts

@@ -1,20 +1,52 @@
 /* Excluded from this release type: __resetIdCounters */
 
+export declare function acquire<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string, options?: AcquireOptions<T>): InstanceType<T>;
+
+export declare interface AcquireOptions<T extends StateContainerConstructor> {
+    props?: ExtractProps<T>;
+}
+
 /**
  * Internal state for framework adapters, holding tracking and caching data.
  * @template TBloc - The state container type
  */
 export declare interface AdapterState<TBloc extends StateContainerConstructor> {
-    /** Proxy tracker for state property access tracking */
-    tracker: TrackerState<ExtractState<TBloc>> | null;
+    /** Dependency tracker for state property access tracking */
+    dependencyState: DependencyState<ExtractState<TBloc>> | null;
     /** Cached manual dependencies for comparison */
     manualDepsCache: unknown[] | null;
-    /** Getter tracker for computed property tracking */
-    getterTracker: GetterTrackerState | null;
+    /** Getter state for computed property tracking */
+    getterState: GetterState | null;
     /** Proxied bloc instance for auto-tracking */
     proxiedBloc: InstanceState<TBloc> | null;
 }
 
+/**
+ * Initialize adapter state for auto-tracking mode.
+ * Creates getter tracker and proxied bloc instance.
+ * @param instance - The state container instance
+ * @returns Initialized adapter state
+ */
+export declare function autoTrackInit<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
+
+/**
+ * Create a snapshot function for auto-tracking mode.
+ * Returns a proxied state that tracks property access.
+ * @param instance - The state container instance
+ * @param adapterState - The adapter state for tracking
+ * @returns Snapshot function for use with useSyncExternalStore
+ */
+export declare function autoTrackSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>, adapterState: AdapterState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+
+/**
+ * Create a subscribe function for auto-tracking mode.
+ * Only triggers callback when tracked properties change.
+ * @param instance - The state container instance
+ * @param adapterState - The adapter state for tracking
+ * @returns Subscribe function for use with useSyncExternalStore
+ */
+export declare function autoTrackSubscribe<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>, adapterState: AdapterState<TBloc>): SubscribeFunction;
+
 /**
  * Decorator to configure StateContainer classes.
  *
@@ -191,32 +223,56 @@ export declare interface BlacPluginWithInit extends BlacPlugin {
     onInstall(context: PluginContext): void;
 }
 
+declare const BLOC_REF_MARKER: unique symbol;
+
 /**
  * Constructor type for StateContainer classes with static registry methods.
  * Used for type-safe hook parameters.
  * @template TBloc - The StateContainer instance type
  */
 export declare type BlocConstructor<S extends object = any, T extends new (...args: any[]) => StateContainer<S, any> = new (...args: any[]) => StateContainer<S, any>> = (new (...args: any[]) => InstanceType<T>) & {
-    resolve(instanceKey?: string, ...args: any[]): InstanceType<T>;
-    get(instanceKey?: string, ...args: any[]): InstanceType<T> | null;
-    getSafe(instanceKey?: string, ...args: any[]): {
+    acquire(instanceKey?: string, ...args: any[]): InstanceType<T>;
+    borrow(instanceKey?: string, ...args: any[]): InstanceType<T> | null;
+    borrowSafe(instanceKey?: string, ...args: any[]): {
         error: Error;
         instance: null;
     } | {
         error: null;
         instance: InstanceType<T>;
     };
+    ensure(instanceKey?: string): InstanceType<T>;
     release(instanceKey?: string): void;
     isolated?: boolean;
     keepAlive?: boolean;
 };
 
+declare type BlocInput = StateContainerConstructor | BlocRef<StateContainerConstructor>;
+
 /**
  * Extract instance type from an abstract class constructor
  * @template T - The abstract class constructor type
  */
 export declare type BlocInstanceType<T extends abstract new (...args: any) => any> = T extends abstract new (...args: any) => infer R ? R : any;
 
+/**
+ * Reference to a specific bloc instance by class and instance ID.
+ */
+export declare interface BlocRef<T extends StateContainerConstructor> {
+    [BLOC_REF_MARKER]: true;
+    blocClass: T;
+    instanceId: string;
+}
+
+export declare function borrow<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): InstanceType<T>;
+
+export declare function borrowSafe<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): {
+    error: Error;
+    instance: null;
+} | {
+    error: null;
+    instance: InstanceType<T>;
+};
+
 /**
  * Utility type for creating branded/nominal types.
  * Prevents accidental type confusion between similar primitive types.
@@ -235,10 +291,14 @@ declare const brand: unique symbol;
  */
 export declare type BrandedId<B> = Brand<string, B>;
 
-/* Excluded from this release type: captureTrackedPaths */
+/* Excluded from this release type: capturePaths */
+
+export declare function clear<T extends StateContainerConstructor>(BlocClass: T): void;
 
 /* Excluded from this release type: clearActiveTracker */
 
+export declare function clearAll(): void;
+
 /* Excluded from this release type: clearExternalDependencies */
 
 /* Excluded from this release type: commitTrackedGetters */
@@ -277,27 +337,15 @@ export declare function configureLogger(opts: Partial<LogConfig>): void;
 
 /* Excluded from this release type: createArrayProxy */
 
-/**
- * Create a snapshot function for auto-tracking mode.
- * Returns a proxied state that tracks property access.
- * @param instance - The state container instance
- * @param adapterState - The adapter state for tracking
- * @returns Snapshot function for use with useSyncExternalStore
- */
-export declare function createAutoTrackSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>, adapterState: AdapterState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+/* Excluded from this release type: createBlocProxy */
 
-/**
- * Create a subscribe function for auto-tracking mode.
- * Only triggers callback when tracked properties change.
- * @param instance - The state container instance
- * @param adapterState - The adapter state for tracking
- * @returns Subscribe function for use with useSyncExternalStore
- */
-export declare function createAutoTrackSubscribe<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>, adapterState: AdapterState<TBloc>): SubscribeFunction;
+/* Excluded from this release type: createDependencyProxy */
 
-/* Excluded from this release type: createBlocProxy */
+/* Excluded from this release type: createDependencyState */
+
+/* Excluded from this release type: createForTarget */
 
-/* Excluded from this release type: createGetterTracker */
+/* Excluded from this release type: createGetterState */
 
 /**
  * Centralized ID Generation
@@ -324,6 +372,8 @@ export declare function createIdGenerator(prefix: string): {
     reset: () => void;
 };
 
+/* Excluded from this release type: createInternal */
+
 /**
  * Creates a logger instance with given configuration
  *
@@ -349,57 +399,29 @@ export declare function createLogger(config: LogConfig): {
 };
 
 /**
- * Create a snapshot function for manual dependency tracking mode.
- * Caches dependencies for comparison on next render.
- * @param instance - The state container instance
- * @param adapterState - The adapter state for caching
- * @param config - Configuration with dependencies function
- * @returns Snapshot function for use with useSyncExternalStore
+ * Create a plugin manager instance
+ * @param registry - The StateContainerRegistry to monitor for lifecycle events
+ * @returns A new PluginManager instance
  */
-export declare function createManualDepsSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+export declare function createPluginManager(registry: StateContainerRegistry): PluginManager;
 
-/**
- * Create a subscribe function for manual dependency tracking mode.
- * Only triggers callback when dependencies array changes.
- * @param instance - The state container instance
- * @param adapterState - The adapter state for caching
- * @param config - Configuration with dependencies function
- * @returns Subscribe function for use with useSyncExternalStore
- */
-export declare function createManualDepsSubscribe<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SubscribeFunction;
+/* Excluded from this release type: createProxyState */
 
 /**
- * Create a snapshot function for no-tracking mode.
- * Returns the raw state directly.
- * @param instance - The state container instance
- * @returns Snapshot function for use with useSyncExternalStore
+ * Create a new tracked context for manual control over tracking.
  */
-export declare function createNoTrackSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+export declare function createTrackedContext(): TrackedContext;
 
 /**
- * Create a subscribe function for no-tracking mode.
- * Triggers callback on every state change.
- * @param instance - The state container instance
- * @returns Subscribe function for use with useSyncExternalStore
+ * Create a tracking proxy for a bloc instance.
+ * Tracks both state property access and getter access.
  */
-export declare function createNoTrackSubscribe<TBloc extends StateContainerInstance>(instance: TBloc): SubscribeFunction;
+export declare function createTrackingProxy<T extends StateContainerInstance>(bloc: T, tracker: TrackingProxyState): T;
 
 /**
- * Create a plugin manager instance
- * @param registry - The StateContainerRegistry to monitor for lifecycle events
- * @returns A new PluginManager instance
+ * Create a new tracking proxy state.
  */
-export declare function createPluginManager(registry: StateContainerRegistry): PluginManager;
-
-/* Excluded from this release type: createProxy */
-
-/* Excluded from this release type: createProxyForTarget */
-
-/* Excluded from this release type: createProxyInternal */
-
-/* Excluded from this release type: createProxyTrackerState */
-
-/* Excluded from this release type: createTrackerState */
+export declare function createTrackingProxyState(): TrackingProxyState;
 
 /**
  * Simple state container with direct state emission.
@@ -434,6 +456,45 @@ export declare abstract class Cubit<S extends object = any, P = undefined> exten
  */
 export declare const debug: (context: string, message: string, data?: any) => void;
 
+/**
+ * Manages subscriptions to state container dependencies.
+ * Provides efficient sync mechanism to add/remove subscriptions
+ * as dependencies change between callback invocations.
+ */
+export declare class DependencyManager {
+    private subscriptions;
+    private currentDeps;
+    /**
+     * 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: Set<StateContainerInstance>, onChange: () => void, exclude?: StateContainerInstance): boolean;
+    /**
+     * Add a single dependency subscription.
+     */
+    add(dep: StateContainerInstance, onChange: () => void): void;
+    /**
+     * Check if a dependency is currently subscribed.
+     */
+    has(dep: StateContainerInstance): boolean;
+    /**
+     * Get the current set of dependencies.
+     */
+    getDependencies(): Set<StateContainerInstance>;
+    /**
+     * Clean up all active subscriptions.
+     */
+    cleanup(): void;
+    private areSetsEqual;
+}
+
+/* Excluded from this release type: DependencyState */
+
 /**
  * Disable getter tracking after render phase completes.
  * Clears the active tracker to prevent tracking outside of render.
@@ -457,6 +518,12 @@ export declare interface DiscriminatedEvent {
     readonly type: string;
 }
 
+/* Excluded from this release type: EmptyState */
+
+/* Excluded from this release type: EmptyState_2 */
+
+export declare function ensure<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): InstanceType<T>;
+
 /**
  * Log an error message (tree-shakeable export)
  * @param context - Context identifier (module or component name)
@@ -510,11 +577,12 @@ export declare type EventType<E extends DiscriminatedEvent> = E['type'];
  * 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.
  */
-export declare class ExternalDependencyManager {
-    private subscriptions;
-    private previousDeps;
-    private areDependenciesEqual;
+export declare class ExternalDepsManager {
+    private manager;
     /**
      * Update subscriptions to external bloc dependencies.
      * Creates subscriptions to blocs accessed via getters.
@@ -523,7 +591,7 @@ export declare class ExternalDependencyManager {
      * @param onGetterChange - Callback to invoke when external dependency changes
      * @returns true if subscriptions were updated, false if unchanged
      */
-    updateSubscriptions(getterTracker: GetterTrackerState | null, rawInstance: StateContainerInstance, onGetterChange: () => void): boolean;
+    updateSubscriptions(getterState: GetterState | null, rawInstance: StateContainerInstance, onGetterChange: () => void): boolean;
     /**
      * Clean up all active subscriptions
      */
@@ -552,6 +620,12 @@ export declare type ExtractEvent<E extends DiscriminatedEvent, T extends EventTy
     type: T;
 }>;
 
+declare type ExtractInstance<T> = T extends BlocRef<infer C> ? InstanceType<C> : T extends StateContainerConstructor ? InstanceType<T> : never;
+
+declare type ExtractInstances<T extends readonly BlocInput[]> = {
+    [K in keyof T]: ExtractInstance<T[K]>;
+};
+
 /**
  * Extract the props type from a StateContainer
  * @template T - The StateContainer type
@@ -564,8 +638,16 @@ export declare type ExtractProps<T> = T extends StateContainerConstructor<any, i
  */
 export declare type ExtractState<T> = T extends StateContainerConstructor<infer S, any> ? Readonly<S> : never;
 
+/**
+ * Constrain a type to extract state only from stateful containers.
+ * Returns `never` for stateless containers.
+ */
+export declare type ExtractStatefulState<T extends StateContainerConstructor> = IsStatelessContainer<T> extends true ? never : ExtractState<T>;
+
 export declare type ExtractStateMutable<T> = T extends StateContainerConstructor<infer S, any> ? S : never;
 
+export declare function forEach<T extends StateContainerConstructor>(BlocClass: T, callback: (instance: InstanceReadonlyState<T>) => void): void;
+
 /**
  * Generate ID with timestamp, counter, and random suffix (tree-shakeable)
  *
@@ -609,6 +691,8 @@ export declare function generateSimpleId(prefix: string, affix?: string): string
 
 /* Excluded from this release type: getActiveTracker */
 
+export declare function getAll<T extends StateContainerConstructor>(BlocClass: T): InstanceReadonlyState<T>[];
+
 /* Excluded from this release type: getBlacConfig */
 
 /* Excluded from this release type: getDescriptor */
@@ -620,6 +704,10 @@ export declare function generateSimpleId(prefix: string, affix?: string): string
  */
 export declare function getPluginManager(): any;
 
+export declare function getRefCount<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): number;
+
+export declare function getRegistry(): StateContainerRegistry;
+
 /**
  * Get a static property from a class constructor
  * Type-safe helper that avoids (Type as any) casts
@@ -631,14 +719,20 @@ export declare function getPluginManager(): any;
  */
 export declare function getStaticProp<V, T extends StateContainerConstructor = StateContainerConstructor>(Type: T, propName: string, defaultValue?: V): V | undefined;
 
+export declare function getStats(): {
+    registeredTypes: number;
+    totalInstances: number;
+    typeBreakdown: Record<string, number>;
+};
+
 declare interface GetterExecutionContext {
-    tracker: GetterTrackerState | null;
+    tracker: GetterState | null;
     currentBloc: StateContainerInstance | null;
     depth: number;
     visitedBlocs: Set<StateContainerInstance>;
 }
 
-/* Excluded from this release type: GetterTrackerState */
+/* Excluded from this release type: GetterState */
 
 /* Excluded from this release type: getValueAtPath */
 
@@ -647,7 +741,7 @@ declare interface GetterExecutionContext {
  */
 export declare const globalRegistry: StateContainerRegistry;
 
-/* Excluded from this release type: hasChanges */
+/* Excluded from this release type: hasDependencyChanges */
 
 /* Excluded from this release type: hasGetterChanges */
 
@@ -658,8 +752,15 @@ export declare const globalRegistry: StateContainerRegistry;
  */
 export declare function hasInitHook(plugin: BlacPlugin): plugin is BlacPluginWithInit;
 
+export declare function hasInstance<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): boolean;
+
 /* Excluded from this release type: hasTrackedData */
 
+/**
+ * Check if tracked state or getters have changed.
+ */
+export declare function hasTrackingProxyChanges(tracker: TrackingProxyState, bloc: StateContainerInstance): boolean;
+
 /**
  * Log an info message (tree-shakeable export)
  * @param context - Context identifier (module or component name)
@@ -669,28 +770,16 @@ export declare function hasInitHook(plugin: BlacPlugin): plugin is BlacPluginWit
 export declare const info: (context: string, message: string, data?: any) => void;
 
 /**
- * Initialize adapter state for auto-tracking mode.
- * Creates getter tracker and proxied bloc instance.
- * @param instance - The state container instance
- * @returns Initialized adapter state
- */
-export declare function initAutoTrackState<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
-
-/**
- * Initialize adapter state for manual dependency tracking mode.
- * No proxy is created; bloc is used directly.
- * @param instance - The state container instance
- * @returns Initialized adapter state
- */
-export declare function initManualDepsState<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
-
-/**
- * Initialize adapter state for no-tracking mode.
- * No tracking or proxy is created.
- * @param instance - The state container instance
- * @returns Initialized adapter state
+ * Create a reference to a specific bloc instance.
+ *
+ * @example
+ * ```ts
+ * watch(instance(UserBloc, 'user-123'), (userBloc) => {
+ *   console.log(userBloc.state.name);
+ * });
+ * ```
  */
-export declare function initNoTrackState<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
+export declare function instance<T extends StateContainerConstructor>(BlocClass: T, instanceId: string): BlocRef<T>;
 
 /**
  * Entry in the instance registry, tracking the instance and its reference count
@@ -786,6 +875,22 @@ export declare function isKeepAliveClass<T extends StateContainerConstructor>(Ty
 
 /* Excluded from this release type: isProxyable */
 
+/**
+ * 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
+ */
+export declare function isStatelessClass<T extends StateContainerConstructor>(Type: T): boolean;
+
+/**
+ * Check if a StateContainer constructor is a stateless container.
+ * Returns true for StatelessCubit and StatelessVertex classes.
+ */
+export declare type IsStatelessContainer<T> = T extends {
+    readonly [STATELESS_MARKER]: true;
+} ? true : false;
+
 /**
  * Lifecycle events emitted by the registry
  */
@@ -848,6 +953,58 @@ export declare interface ManualDepsConfig<TBloc extends StateContainerConstructo
     dependencies: (state: ExtractState<TBloc>, bloc: InstanceState<TBloc>) => any[];
 }
 
+/**
+ * Initialize adapter state for manual dependency tracking mode.
+ * No proxy is created; bloc is used directly.
+ * @param instance - The state container instance
+ * @returns Initialized adapter state
+ */
+export declare function manualDepsInit<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
+
+/**
+ * Create a snapshot function for manual dependency tracking mode.
+ * Caches dependencies for comparison on next render.
+ * @param instance - The state container instance
+ * @param adapterState - The adapter state for caching
+ * @param config - Configuration with dependencies function
+ * @returns Snapshot function for use with useSyncExternalStore
+ */
+export declare function manualDepsSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+
+/**
+ * Create a subscribe function for manual dependency tracking mode.
+ * Only triggers callback when dependencies array changes.
+ * @param instance - The state container instance
+ * @param adapterState - The adapter state for caching
+ * @param config - Configuration with dependencies function
+ * @returns Subscribe function for use with useSyncExternalStore
+ */
+export declare function manualDepsSubscribe<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SubscribeFunction;
+
+/**
+ * Initialize adapter state for no-tracking mode.
+ * No tracking or proxy is created.
+ * @param instance - The state container instance
+ * @returns Initialized adapter state
+ */
+export declare function noTrackInit<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
+
+/**
+ * Create a snapshot function for no-tracking mode.
+ * Returns the raw state directly.
+ * @param instance - The state container instance
+ * @returns Snapshot function for use with useSyncExternalStore
+ */
+export declare function noTrackSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+
+/**
+ * Create a subscribe function for no-tracking mode.
+ * Triggers callback on every state change.
+ * @param instance - The state container instance
+ * @returns Subscribe function for use with useSyncExternalStore
+ */
+export declare function noTrackSubscribe<TBloc extends StateContainerInstance>(instance: TBloc): SubscribeFunction;
+
 /* Excluded from this release type: parsePath */
 
 /* Excluded from this release type: PathInfo */
@@ -966,14 +1123,20 @@ export declare class PluginManager {
     private getCurrentEnvironment;
 }
 
-/* Excluded from this release type: ProxyTrackerState */
+/* Excluded from this release type: ProxyState */
+
+export declare function register<T extends StateContainerConstructor>(BlocClass: T, isolated?: boolean): void;
+
+export declare function release<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string, forceDispose?: boolean): void;
 
 /* Excluded from this release type: resetBlacConfig */
 
-/* Excluded from this release type: resetGetterTracker */
+/* Excluded from this release type: resetGetterState */
 
 /* Excluded from this release type: setActiveTracker */
 
+export declare function setRegistry(registry: StateContainerRegistry): void;
+
 /* Excluded from this release type: shallowEqual */
 
 /**
@@ -982,9 +1145,14 @@ export declare class PluginManager {
  */
 export declare type SnapshotFunction<TState> = () => TState;
 
-/* Excluded from this release type: startProxyTracking */
+/* Excluded from this release type: startDependency */
 
-/* Excluded from this release type: startTracking */
+/* Excluded from this release type: startProxy */
+
+/**
+ * Start tracking on a tracking proxy.
+ */
+export declare function startTrackingProxy(tracker: TrackingProxyState): void;
 
 /**
  * Abstract base class for all state containers in BlaC.
@@ -1007,117 +1175,8 @@ export declare type SnapshotFunction<TState> = () => TState;
  * ```
  */
 export declare abstract class StateContainer<S extends object = any, P = any> {
-    /* Excluded from this release type: __excludeFromDevTools */
-    /* Excluded from this release type: _registry */
-    /**
-     * Get the global StateContainerRegistry
-     * @returns The registry managing all state container instances
-     */
-    static getRegistry(): StateContainerRegistry;
-    /**
-     * Replace the global registry (clears existing instances)
-     * @param registry - The new registry to use
-     */
-    static setRegistry(registry: StateContainerRegistry): void;
-    /**
-     * Register this class with the global registry
-     * @param isolated - Whether instances should be isolated (component-scoped)
-     */
-    static register<T extends StateContainerConstructor>(this: T, isolated?: boolean): void;
-    /**
-     * 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<T extends StateContainerConstructor = StateContainerConstructor>(this: T, instanceKey?: string, options?: {
-        canCreate?: boolean;
-        countRef?: boolean;
-        props?: ExtractProps<T>;
-        trackExecutionContext?: boolean;
-    }): InstanceType<T>;
-    /**
-     * 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<T extends StateContainerConstructor<any> = StateContainerConstructor<any>>(this: T, instanceKey?: string): InstanceType<T>;
-    /**
-     * 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<T extends StateContainerConstructor<any> = StateContainerConstructor<any>>(this: T, instanceKey?: string): {
-        error: Error;
-        instance: null;
-    } | {
-        error: null;
-        instance: InstanceType<T>;
-    };
-    /**
-     * 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<T extends StateContainerConstructor<any> = StateContainerConstructor<any>>(this: T, instanceKey?: string): InstanceType<T>;
-    /**
-     * 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<T extends StateContainerConstructor = StateContainerConstructor>(this: T, instanceKey?: string, forceDispose?: boolean): void;
-    /**
-     * Get all instances of this class
-     * @returns Array of all instances
-     */
-    static getAll<T extends StateContainerConstructor = StateContainerConstructor>(this: T): InstanceReadonlyState<T>[];
-    /**
-     * Iterate over all instances of this class
-     * @param callback - Function to call for each instance
-     */
-    static forEach<T extends StateContainerConstructor = StateContainerConstructor>(this: T, callback: (instance: InstanceReadonlyState<T>) => void): void;
-    /**
-     * Clear all instances of this class (disposes them)
-     */
-    static clear<T extends StateContainerConstructor = StateContainerConstructor>(this: T): void;
-    /**
-     * Clear all instances from all registered types
-     */
-    static clearAllInstances(): void;
-    /**
-     * Get registry statistics for debugging
-     * @returns Object with registeredTypes, totalInstances, and typeBreakdown
-     */
-    static getStats(): {
-        registeredTypes: number;
-        totalInstances: number;
-        typeBreakdown: Record<string, number>;
-    };
-    /**
-     * 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<T extends StateContainerConstructor = StateContainerConstructor>(this: T, instanceKey?: string): number;
-    /**
-     * Check if an instance exists
-     * @param instanceKey - Optional instance key (defaults to 'default')
-     * @returns true if instance exists
-     */
-    static hasInstance<T extends StateContainerConstructor = StateContainerConstructor>(this: T, instanceKey?: string): boolean;
+    static __excludeFromDevTools: boolean;
+    static enableStackTrace: boolean;
     private _state;
     private readonly listeners;
     private _disposed;
@@ -1162,8 +1221,6 @@ export declare abstract class StateContainer<S extends object = any, P = any> {
      * @protected
      */
     protected emit(newState: S): void;
-    /** Whether to capture stack traces on state changes (disabled in production) */
-    static enableStackTrace: boolean;
     private captureStackTrace;
     private formatStackLine;
     private cleanFilePath;
@@ -1222,7 +1279,8 @@ export declare type StateContainerInstance<S extends object = any, P = any> = Om
  * @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);
  * });
@@ -1252,40 +1310,41 @@ export declare class StateContainerRegistry {
     getInstancesMap<T extends StateContainerConstructor>(Type: T): Map<string, InstanceEntry>;
     private trackExecutionContext;
     /**
-     * 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<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string, options?: {
+    acquire<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string, options?: {
         canCreate?: boolean;
         countRef?: boolean;
         props?: ExtractProps<T>;
         trackExecutionContext?: boolean;
     }): InstanceType<T>;
     /**
-     * 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<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
+    borrow<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
     /**
-     * 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<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): {
+    borrowSafe<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): {
         error: Error;
         instance: null;
     } | {
@@ -1293,7 +1352,7 @@ export declare class StateContainerRegistry {
         instance: InstanceType<T>;
     };
     /**
-     * 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.
      *
@@ -1303,7 +1362,7 @@ export declare class StateContainerRegistry {
      * @param instanceKey - Instance key (defaults to 'default')
      * @returns The state container instance
      */
-    connect<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
+    ensure<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
     /**
      * Release a reference to an instance.
      * Decrements ref count and disposes when it reaches 0 (unless keepAlive).
@@ -1375,9 +1434,195 @@ export declare class StateContainerRegistry {
     /* Excluded from this release type: emit */
 }
 
+/**
+ * Constrain a type to only accept stateful containers (not StatelessCubit/StatelessVertex).
+ * Use this to reject stateless containers at the type level.
+ */
+export declare type StatefulContainerOnly<T extends StateContainerConstructor> = IsStatelessContainer<T> extends true ? never : T;
+
+/**
+ * Marker symbol to identify stateless containers at the type level.
+ * Used by React hooks to prevent `useBloc` from accepting stateless containers.
+ */
+export declare const STATELESS_MARKER: unique symbol;
+
+/**
+ * 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');
+ * ```
+ */
+export declare abstract class StatelessCubit<P = undefined> extends Cubit<EmptyState, P> {
+    /* Excluded from this release type: [STATELESS_MARKER] */
+    constructor();
+    /**
+     * State is not available on StatelessCubit.
+     * @throws Always throws an error when accessed.
+     */
+    get state(): never;
+    /**
+     * Subscriptions are not available on StatelessCubit.
+     * @throws Always throws an error when called.
+     */
+    subscribe(_listener: (state: EmptyState) => void): never;
+    /**
+     * emit() is not available on StatelessCubit.
+     * TypeScript will show an error if you try to call this method.
+     */
+    emit(_newState: never): never;
+    /**
+     * update() is not available on StatelessCubit.
+     * TypeScript will show an error if you try to call this method.
+     */
+    update(_updater: never): never;
+    /**
+     * patch() is not available on StatelessCubit.
+     * @throws Error always - StatelessCubit does not support state changes
+     */
+    patch: (_partial: Partial<EmptyState>) => void;
+}
+
+/**
+ * Event handler for StatelessVertex that receives only the event (no emit function).
+ * Use for side-effect-only event processing.
+ */
+export declare type StatelessEventHandler<E extends DiscriminatedEvent> = (event: EventWithMetadata<E>) => void;
+
+/**
+ * Map of event types to their handlers for StatelessVertex.
+ * Enforces exhaustive handling of all event types in the union.
+ */
+export declare type StatelessEventHandlerMap<E extends DiscriminatedEvent> = {
+    [K in E['type']]: StatelessEventHandler<Extract<E, {
+        type: K;
+    }>>;
+};
+
+/**
+ * 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');
+ * ```
+ */
+export declare abstract class StatelessVertex<E extends DiscriminatedEvent = DiscriminatedEvent, P = undefined> extends StateContainer<EmptyState_2, P> {
+    /* Excluded from this release type: [STATELESS_MARKER] */
+    /* Excluded from this release type: handlers */
+    /* Excluded from this release type: isProcessing */
+    /* Excluded from this release type: eventQueue */
+    constructor();
+    /**
+     * State is not available on StatelessVertex.
+     * @throws Always throws an error when accessed.
+     */
+    get state(): never;
+    /**
+     * Subscriptions are not available on StatelessVertex.
+     * @throws Always throws an error when called.
+     */
+    subscribe(_listener: (state: EmptyState_2) => void): never;
+    /**
+     * 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
+     */
+    protected createHandlers(handlers: StatelessEventHandlerMap<E>): void;
+    /**
+     * Dispatch an event for processing.
+     * Events are processed synchronously; if called during processing,
+     * the event is queued and processed after the current event completes.
+     *
+     * @param event - The event to process (must match the event union type)
+     */
+    add: (event: E) => void;
+    /* Excluded from this release type: enrichEvent */
+    /* Excluded from this release type: processEvent */
+    /* Excluded from this release type: handleEvent */
+    /**
+     * 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
+     */
+    protected onEventError(_event: EventWithMetadata<E>, _error: Error): void;
+    /* Excluded from this release type: emit */
+    /* Excluded from this release type: update */
+}
+
 /* Excluded from this release type: StateListener */
 
-/* Excluded from this release type: stopProxyTracking */
+declare const STOP: unique symbol;
+
+/* Excluded from this release type: stopProxy */
+
+declare type StopSymbol = typeof STOP;
+
+/**
+ * Stop tracking and collect all dependencies.
+ */
+export declare function stopTrackingProxy(tracker: TrackingProxyState, bloc: StateContainerInstance): Set<StateContainerInstance>;
 
 /**
  * Function that subscribes to state changes and returns an unsubscribe function
@@ -1416,7 +1661,82 @@ export declare interface SystemEventPayloads<S, P> {
     dispose: void;
 }
 
-/* Excluded from this release type: TrackerState */
+/**
+ * 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
+ * ```
+ */
+export declare function tracked<T>(callback: () => T, options?: TrackedOptions): TrackedResult<T>;
+
+/**
+ * Context for running tracked callbacks with bloc proxies.
+ * Provides methods to create proxies and check for changes.
+ */
+export declare class TrackedContext {
+    private tracker;
+    private proxiedBlocs;
+    private primaryBlocs;
+    constructor();
+    /**
+     * Get a tracking proxy for a bloc instance.
+     * The proxy will track state and getter accesses.
+     */
+    proxy<T extends StateContainerInstance>(bloc: T): T;
+    /**
+     * Start tracking for a new callback execution.
+     */
+    start(): void;
+    /**
+     * Stop tracking and get discovered dependencies.
+     * Excludes primary blocs (those explicitly proxied via proxy()).
+     */
+    stop(): Set<StateContainerInstance>;
+    /**
+     * Check if any tracked state or getters have changed.
+     */
+    changed(): boolean;
+    /**
+     * Get all primary blocs (those explicitly proxied).
+     */
+    getPrimaryBlocs(): Set<StateContainerInstance>;
+    /**
+     * Reset the context for reuse.
+     */
+    reset(): void;
+}
+
+/**
+ * Options for the tracked() function.
+ */
+export declare interface TrackedOptions {
+    exclude?: StateContainerInstance;
+}
+
+/**
+ * Result of running a tracked callback.
+ */
+export declare interface TrackedResult<T> {
+    result: T;
+    dependencies: Set<StateContainerInstance>;
+}
+
+/**
+ * State for tracking both state property access and getter access.
+ */
+export declare interface TrackingProxyState {
+    dependencyState: DependencyState<any>;
+    getterState: GetterState;
+    dependencies: Set<StateContainerInstance>;
+    isTracking: boolean;
+}
 
 /**
  * Event-driven state container using discriminated union events.
@@ -1489,6 +1809,64 @@ export declare abstract class Vertex<S extends object = object, E extends Discri
 
 /* Excluded from this release type: VertexEventHandler */
 
+/**
+ * Wait until a condition is met on a bloc instance.
+ * Returns the bloc instance when the predicate returns true.
+ * Automatically tracks dependencies accessed in the predicate.
+ *
+ * @example
+ * ```ts
+ * // Wait for bloc state to be ready
+ * const userBloc = await waitUntil(UserBloc, (bloc) => bloc.state.isAuthenticated);
+ *
+ * // Wait using a getter
+ * const userBloc = await waitUntil(UserBloc, (bloc) => bloc.isReady);
+ * ```
+ */
+export declare function waitUntil<T extends StateContainerConstructor>(BlocClass: T, predicate: (bloc: InstanceType<T>) => boolean, options?: WaitUntilOptions): Promise<InstanceType<T>>;
+
+/**
+ * Wait until a condition is met on a selected value from a bloc.
+ * Returns the selected value when the predicate returns true.
+ * Automatically tracks dependencies accessed in selector and predicate.
+ *
+ * @example
+ * ```ts
+ * // Wait for layout to be set and get it directly
+ * const layout = await waitUntil(
+ *   LayoutBloc,
+ *   (bloc) => bloc.state.currentLayout,
+ *   (layout) => layout !== null
+ * );
+ *
+ * // Using a getter as selector
+ * const user = await waitUntil(
+ *   UserBloc,
+ *   (bloc) => bloc.currentUser,
+ *   (user) => user !== null
+ * );
+ * ```
+ */
+export declare function waitUntil<T extends StateContainerConstructor, TSelected>(BlocClass: T, selector: (bloc: InstanceType<T>) => TSelected, predicate: (selected: TSelected) => boolean, options?: WaitUntilOptions): Promise<TSelected>;
+
+export declare class WaitUntilAbortedError extends Error {
+    constructor();
+}
+
+export declare class WaitUntilDisposedError extends Error {
+    constructor(blocName: string);
+}
+
+export declare interface WaitUntilOptions {
+    instanceId?: string;
+    timeout?: number;
+    signal?: AbortSignal;
+}
+
+export declare class WaitUntilTimeoutError extends Error {
+    constructor(timeout: number);
+}
+
 /**
  * Log a warning message (tree-shakeable export)
  * @param context - Context identifier (module or component name)
@@ -1497,4 +1875,21 @@ export declare abstract class Vertex<S extends object = object, E extends Discri
  */
 export declare const warn: (context: string, message: string, data?: any) => void;
 
+export declare const watch: WatchFn;
+
+/**
+ * Combined watch function type.
+ */
+export declare interface WatchFn extends WatchSingleFn {
+    <T extends readonly BlocInput[]>(blocs: T, callback: (blocs: ExtractInstances<T>) => void | StopSymbol): () => void;
+}
+
+/**
+ * Watch function signature for single bloc.
+ */
+declare interface WatchSingleFn {
+    <T extends StateContainerConstructor>(bloc: T | BlocRef<T>, callback: (bloc: InstanceType<T>) => void | StopSymbol): () => void;
+    STOP: StopSymbol;
+}
+
 export { }