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

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * Internal state for framework adapters, holding tracking and caching data.
  * @template TBloc - The state container type
  */
-export declare interface AdapterState<TBloc extends StateContainer<any, any>> {
+export declare interface AdapterState<TBloc extends StateContainerConstructor> {
     /** Proxy tracker for state property access tracking */
     tracker: TrackerState<ExtractState<TBloc>> | null;
     /** Cached manual dependencies for comparison */
@@ -12,7 +12,7 @@ export declare interface AdapterState<TBloc extends StateContainer<any, any>> {
     /** Getter tracker for computed property tracking */
     getterTracker: GetterTrackerState | null;
     /** Proxied bloc instance for auto-tracking */
-    proxiedBloc: TBloc | null;
+    proxiedBloc: InstanceState<TBloc> | null;
 }
 
 /**
@@ -173,7 +173,7 @@ export declare interface BlacPlugin {
     /**
      * Called when state changes in a container instance
      */
-    onStateChanged?<S>(instance: StateContainer<S>, previousState: S, currentState: S, callstack: string | undefined, context: PluginContext): void;
+    onStateChanged?<S extends object = any>(instance: StateContainer<S>, previousState: S, currentState: S, callstack: string | undefined, context: PluginContext): void;
     /**
      * Called when an event is added to a Vertex instance
      */
@@ -199,21 +199,27 @@ export declare interface BlacPluginWithInit extends BlacPlugin {
  * Used for type-safe hook parameters.
  * @template TBloc - The StateContainer instance type
  */
-export declare type BlocConstructor<TBloc extends StateContainer<any, any>> = (new (...args: any[]) => TBloc) & {
-    resolve<S = never>(instanceKey?: string, ...args: any[]): StateOverride<TBloc, S>;
-    get<S = never>(instanceKey?: string): StateOverride<TBloc, S>;
-    getSafe<S = never>(instanceKey?: string): {
+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[]): {
         error: Error;
         instance: null;
     } | {
         error: null;
-        instance: StateOverride<TBloc, S>;
+        instance: InstanceType<T>;
     };
     release(instanceKey?: string): void;
     isolated?: boolean;
     keepAlive?: boolean;
 };
 
+/**
+ * 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;
+
 /**
  * Utility type for creating branded/nominal types.
  * Prevents accidental type confusion between similar primitive types.
@@ -261,7 +267,7 @@ export declare function configureLogger(opts: Partial<LogConfig>): void;
  * @param adapterState - The adapter state for tracking
  * @returns Snapshot function for use with useSyncExternalStore
  */
-export declare function createAutoTrackSnapshot<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+export declare function createAutoTrackSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>, adapterState: AdapterState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
 
 /**
  * Create a subscribe function for auto-tracking mode.
@@ -270,7 +276,7 @@ export declare function createAutoTrackSnapshot<TBloc extends StateContainer<any
  * @param adapterState - The adapter state for tracking
  * @returns Subscribe function for use with useSyncExternalStore
  */
-export declare function createAutoTrackSubscribe<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>): SubscribeFunction;
+export declare function createAutoTrackSubscribe<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>, adapterState: AdapterState<TBloc>): SubscribeFunction;
 
 /* Excluded from this release type: createBlocProxy */
 
@@ -333,7 +339,7 @@ export declare function createLogger(config: LogConfig): {
  * @param config - Configuration with dependencies function
  * @returns Snapshot function for use with useSyncExternalStore
  */
-export declare function createManualDepsSnapshot<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+export declare function createManualDepsSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
 
 /**
  * Create a subscribe function for manual dependency tracking mode.
@@ -343,7 +349,7 @@ export declare function createManualDepsSnapshot<TBloc extends StateContainer<an
  * @param config - Configuration with dependencies function
  * @returns Subscribe function for use with useSyncExternalStore
  */
-export declare function createManualDepsSubscribe<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SubscribeFunction;
+export declare function createManualDepsSubscribe<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SubscribeFunction;
 
 /**
  * Create a snapshot function for no-tracking mode.
@@ -351,7 +357,7 @@ export declare function createManualDepsSubscribe<TBloc extends StateContainer<a
  * @param instance - The state container instance
  * @returns Snapshot function for use with useSyncExternalStore
  */
-export declare function createNoTrackSnapshot<TBloc extends StateContainer<any, any>>(instance: TBloc): SnapshotFunction<ExtractState<TBloc>>;
+export declare function createNoTrackSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
 
 /**
  * Create a subscribe function for no-tracking mode.
@@ -359,10 +365,12 @@ export declare function createNoTrackSnapshot<TBloc extends StateContainer<any,
  * @param instance - The state container instance
  * @returns Subscribe function for use with useSyncExternalStore
  */
-export declare function createNoTrackSubscribe<TBloc extends StateContainer<any, any>>(instance: TBloc): SubscribeFunction;
+export declare function createNoTrackSubscribe<TBloc extends StateContainerInstance>(instance: TBloc): SubscribeFunction;
 
 /**
  * Create a plugin manager instance
+ * @param registry - The StateContainerRegistry to monitor for lifecycle events
+ * @returns A new PluginManager instance
  */
 export declare function createPluginManager(registry: StateContainerRegistry): PluginManager;
 
@@ -383,7 +391,7 @@ export declare function createPluginManager(registry: StateContainerRegistry): P
  * @template S - State type
  * @template P - Props type (optional)
  */
-export declare abstract class Cubit<S, P = undefined> extends StateContainer<S, P> {
+export declare abstract class Cubit<S extends object = any, P = undefined> extends StateContainer<S, P> {
     constructor(initialState: S);
     /**
      * Replace state with a new value and notify all listeners
@@ -415,7 +423,7 @@ export declare const debug: (context: string, message: string, data?: any) => vo
  * @param adapterState - The adapter state
  * @param rawInstance - The raw bloc instance
  */
-export declare function disableGetterTracking<TBloc extends StateContainer<any, any>>(adapterState: AdapterState<TBloc>, rawInstance: TBloc): void;
+export declare function disableGetterTracking<TBloc extends StateContainerConstructor>(adapterState: AdapterState<TBloc>, rawInstance: InstanceState<TBloc>): void;
 
 /**
  * Log an error message (tree-shakeable export)
@@ -457,7 +465,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: StateContainer<any, any>, onGetterChange: () => void): boolean;
+    updateSubscriptions(getterTracker: GetterTrackerState | null, rawInstance: StateContainerInstance, onGetterChange: () => void): boolean;
     /**
      * Clean up all active subscriptions
      */
@@ -474,13 +482,15 @@ export declare type ExtractConstructorArgs<T> = T extends new (...args: infer P)
  * Extract the props type from a StateContainer
  * @template T - The StateContainer type
  */
-export declare type ExtractProps<T> = T extends StateContainer<any, infer P> ? P : undefined;
+export declare type ExtractProps<T> = T extends StateContainerConstructor<any, infer P> ? P : undefined;
 
 /**
  * Extract the state type from a StateContainer
  * @template T - The StateContainer type
  */
-export declare type ExtractState<T> = T extends StateContainer<infer S, any> ? S : never;
+export declare type ExtractState<T> = T extends StateContainerConstructor<infer S, any> ? Readonly<S> : never;
+
+export declare type ExtractStateMutable<T> = T extends StateContainerConstructor<infer S, any> ? S : never;
 
 /**
  * Generate ID with timestamp, counter, and random suffix (tree-shakeable)
@@ -534,9 +544,6 @@ export declare function generateSimpleId(prefix: string, affix?: string): string
  */
 export declare function getPluginManager(): any;
 
-/**
- * Utility functions for accessing static properties on StateContainer classes
- */
 /**
  * Get a static property from a class constructor
  * Type-safe helper that avoids (Type as any) casts
@@ -546,13 +553,13 @@ export declare function getPluginManager(): any;
  * @param defaultValue - Optional default value if property is undefined
  * @returns The property value or default
  */
-export declare function getStaticProp<T>(Type: new (...args: any[]) => any, propName: string, defaultValue?: T): T | undefined;
+export declare function getStaticProp<V, T extends StateContainerConstructor = StateContainerConstructor>(Type: T, propName: string, defaultValue?: V): V | undefined;
 
 declare interface GetterExecutionContext {
     tracker: GetterTrackerState | null;
-    currentBloc: StateContainer<any> | null;
+    currentBloc: StateContainerInstance | null;
     depth: number;
-    visitedBlocs: Set<StateContainer<any>>;
+    visitedBlocs: Set<StateContainerInstance>;
 }
 
 /* Excluded from this release type: GetterTrackerState */
@@ -591,7 +598,7 @@ export declare const info: (context: string, message: string, data?: any) => voi
  * @param instance - The state container instance
  * @returns Initialized adapter state
  */
-export declare function initAutoTrackState<TBloc extends StateContainer<any, any>>(instance: TBloc): AdapterState<TBloc>;
+export declare function initAutoTrackState<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
 
 /**
  * Initialize adapter state for manual dependency tracking mode.
@@ -599,7 +606,7 @@ export declare function initAutoTrackState<TBloc extends StateContainer<any, any
  * @param instance - The state container instance
  * @returns Initialized adapter state
  */
-export declare function initManualDepsState<TBloc extends StateContainer<any, any>>(instance: TBloc): AdapterState<TBloc>;
+export declare function initManualDepsState<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
 
 /**
  * Initialize adapter state for no-tracking mode.
@@ -607,7 +614,7 @@ export declare function initManualDepsState<TBloc extends StateContainer<any, an
  * @param instance - The state container instance
  * @returns Initialized adapter state
  */
-export declare function initNoTrackState<TBloc extends StateContainer<any, any>>(instance: TBloc): AdapterState<TBloc>;
+export declare function initNoTrackState<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
 
 /**
  * Entry in the instance registry, tracking the instance and its reference count
@@ -653,21 +660,33 @@ export declare interface InstanceMetadata {
     currentState?: any;
 }
 
+export declare type InstanceReadonlyState<T extends StateContainerConstructor = any> = Omit<InstanceType<T>, 'state'> & {
+    state: ExtractState<T>;
+};
+
+export declare type InstanceState<T extends StateContainerConstructor = any> = Omit<InstanceType<T>, 'state'> & {
+    state: ExtractStateMutable<T>;
+};
+
 /* Excluded from this release type: invalidateRenderCache */
 
 /**
- * Check if a class should be excluded from DevTools
- * Used to prevent infinite loops when DevTools tracks itself
+ * Check if a class should be excluded from DevTools.
+ * Used to prevent infinite loops when DevTools tracks itself.
+ * @param Type - The class constructor to check
+ * @returns true if the class has `static __excludeFromDevTools = true`
  */
-export declare function isExcludedFromDevTools(Type: new (...args: any[]) => any): boolean;
+export declare function isExcludedFromDevTools<T extends StateContainerConstructor>(Type: T): boolean;
 
 /* Excluded from this release type: isGetter */
 
 /**
- * Check if a class is marked as isolated
- * Isolated classes create separate instances per component
+ * Check if a class is marked as isolated.
+ * Isolated classes create separate instances per component.
+ * @param Type - The class constructor to check
+ * @returns true if the class has `static isolated = true`
  */
-export declare function isIsolatedClass(Type: new (...args: any[]) => any): boolean;
+export declare function isIsolatedClass<T extends StateContainerConstructor>(Type: T): boolean;
 
 /**
  * Check if a key is an isolated instance key
@@ -677,10 +696,12 @@ export declare function isIsolatedClass(Type: new (...args: any[]) => any): bool
 export declare function isIsolatedKey(key: string): boolean;
 
 /**
- * Check if a class is marked as keepAlive
- * KeepAlive classes are never auto-disposed when ref count reaches 0
+ * Check if a class is marked as keepAlive.
+ * KeepAlive classes are never auto-disposed when ref count reaches 0.
+ * @param Type - The class constructor to check
+ * @returns true if the class has `static keepAlive = true`
  */
-export declare function isKeepAliveClass(Type: new (...args: any[]) => any): boolean;
+export declare function isKeepAliveClass<T extends StateContainerConstructor>(Type: T): boolean;
 
 /* Excluded from this release type: isProxyable */
 
@@ -741,9 +762,9 @@ export declare enum LogLevel {
  * Configuration for manual dependency tracking mode
  * @template TBloc - The state container type
  */
-export declare interface ManualDepsConfig<TBloc extends StateContainer<any, any>> {
+export declare interface ManualDepsConfig<TBloc extends StateContainerConstructor> {
     /** Function that returns dependency array from state and bloc */
-    dependencies: (state: any, bloc: TBloc) => unknown[];
+    dependencies: (state: ExtractState<TBloc>, bloc: InstanceState<TBloc>) => any[];
 }
 
 /* Excluded from this release type: parsePath */
@@ -771,7 +792,7 @@ export declare interface PluginContext {
     /**
      * Get current state from a container
      */
-    getState<S>(instance: StateContainer<S>): S;
+    getState<S extends object = any>(instance: StateContainer<S>): S;
     /**
      * Get all instances of a specific type
      */
@@ -892,17 +913,17 @@ export declare type SnapshotFunction<TState> = () => TState;
  *
  * @example
  * ```ts
- * class CounterBloc extends StateContainer<number> {
+ * class CounterBloc extends StateContainer<{ count: number }> {
  *   constructor() {
- *     super(0);
+ *     super({ count: 0 });
  *   }
  *   increment() {
- *     this.emit(this.state + 1);
+ *     this.emit({ count: this.state.count + 1 });
  *   }
  * }
  * ```
  */
-export declare abstract class StateContainer<S, P = undefined> {
+export declare abstract class StateContainer<S extends object = any, P = any> {
     /* Excluded from this release type: __excludeFromDevTools */
     /* Excluded from this release type: _registry */
     /**
@@ -919,17 +940,22 @@ export declare abstract class StateContainer<S, P = undefined> {
      * Register this class with the global registry
      * @param isolated - Whether instances should be isolated (component-scoped)
      */
-    static register<T extends StateContainer<any>>(this: new (...args: any[]) => T, isolated?: boolean): void;
+    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 constructorArgs - Arguments to pass to constructor if creating new instance
+     * @param options - Resolution options (canCreate, countRef, props, trackExecutionContext)
      * @returns The state container instance
      */
-    static resolve<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): StateOverride<T, S>;
+    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
@@ -938,7 +964,7 @@ export declare abstract class StateContainer<S, P = undefined> {
      * @returns The state container instance
      * @throws Error if instance doesn't exist
      */
-    static get<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): StateOverride<T, S>;
+    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
@@ -946,44 +972,44 @@ export declare abstract class StateContainer<S, P = undefined> {
      * @param instanceKey - Optional instance key (defaults to 'default')
      * @returns Discriminated union with either the instance or an error
      */
-    static getSafe<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): {
+    static getSafe<T extends StateContainerConstructor<any> = StateContainerConstructor<any>>(this: T, instanceKey?: string): {
         error: Error;
         instance: null;
     } | {
         error: null;
-        instance: StateOverride<T, S>;
+        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')
-     * @param constructorArgs - Arguments to pass to constructor if creating new instance
      * @returns The state container instance
      */
-    static connect<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): StateOverride<T, S>;
+    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 StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
+    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 StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T): T[];
+    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 StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, callback: (instance: T) => void): void;
+    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 StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T): void;
+    static clear<T extends StateContainerConstructor = StateContainerConstructor>(this: T): void;
     /**
      * Clear all instances from all registered types
      */
@@ -1002,13 +1028,13 @@ export declare abstract class StateContainer<S, P = undefined> {
      * @param instanceKey - Optional instance key (defaults to 'default')
      * @returns Current ref count (0 if instance doesn't exist)
      */
-    static getRefCount<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): number;
+    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 StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): boolean;
+    static hasInstance<T extends StateContainerConstructor = StateContainerConstructor>(this: T, instanceKey?: string): boolean;
     private _state;
     private readonly listeners;
     private _disposed;
@@ -1033,7 +1059,7 @@ export declare abstract class StateContainer<S, P = undefined> {
      */
     initConfig(config: StateContainerConfig): void;
     /** Current state value */
-    get state(): S;
+    get state(): Readonly<S>;
     /** Whether this instance has been disposed */
     get isDisposed(): boolean;
     /**
@@ -1095,6 +1121,17 @@ export declare interface StateContainerConfig {
     instanceId?: string;
 }
 
+/**
+ * Constructor type for StateContainer classes
+ * @template S - State type managed by the container
+ * @template P - Props type passed to the container
+ */
+export declare type StateContainerConstructor<S extends object = any, P = any> = new (...args: any[]) => StateContainer<S, P>;
+
+export declare type StateContainerInstance<S extends object = any, P = any> = Omit<StateContainer<S, P>, 'state'> & {
+    state: Readonly<S>;
+};
+
 /**
  * Central registry for managing StateContainer instances.
  * Handles instance lifecycle, ref counting, and lifecycle event emission.
@@ -1117,77 +1154,113 @@ export declare class StateContainerRegistry {
      * Register a type for lifecycle event tracking
      * @param constructor - The StateContainer class constructor
      */
-    registerType<T extends StateContainer<any>>(constructor: new (...args: any[]) => T): void;
+    registerType<T extends StateContainerConstructor>(constructor: T): void;
     /**
      * Register a StateContainer class with configuration
      * @param constructor - The StateContainer class constructor
      * @param isolated - Whether instances should be isolated (component-scoped)
      * @throws Error if type is already registered
      */
-    register<T extends StateContainer<any>>(constructor: new (...args: any[]) => T, isolated?: boolean): void;
+    register<T extends StateContainerConstructor>(constructor: T, isolated?: boolean): void;
     private ensureInstancesMap;
     /**
      * Get the instances Map for a specific class (public API for stats/debugging)
      */
-    getInstancesMap<T extends StateContainer<any>>(Type: new (...args: any[]) => T): Map<string, InstanceEntry>;
+    getInstancesMap<T extends StateContainerConstructor>(Type: T): Map<string, InstanceEntry>;
+    private trackExecutionContext;
     /**
-     * Resolve an instance with ref counting (ownership semantics)
+     * Resolve an instance with ref counting (ownership semantics).
+     * Creates a new instance if one doesn't exist, or returns existing and increments ref count.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @param options - Resolution 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 StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    resolve<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 ref counting (borrowing semantics)
+     * Get 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 StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): T;
+    get<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
     /**
-     * Safely get an existing instance (borrowing semantics with error handling)
-     * Returns discriminated union for type-safe conditional access
+     * Safely get 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 StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): {
+    getSafe<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): {
         error: Error;
         instance: null;
     } | {
         error: null;
-        instance: T;
+        instance: InstanceType<T>;
     };
     /**
-     * Connect to an instance with borrowing semantics (for B2B communication)
+     * Connect to an instance with borrowing semantics (for B2B communication).
      * Gets existing instance OR creates it if it doesn't exist, without incrementing ref count.
      * Tracks cross-bloc dependency for reactive updates.
      *
      * Use this in bloc-to-bloc communication when you need to ensure an instance exists
      * but don't want to claim ownership (no ref count increment).
-     *
-     * @param Type - The bloc class constructor
-     * @param instanceKey - Optional instance key (defaults to 'default')
-     * @param constructorArgs - Constructor arguments (only used if creating new instance)
-     * @returns The bloc instance
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns The state container instance
      */
-    connect<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    connect<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
     /**
-     * Release a reference to an instance
+     * Release a reference to an instance.
+     * Decrements ref count and disposes when it reaches 0 (unless keepAlive).
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @param forceDispose - Force immediate disposal regardless of ref count
      */
-    release<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
+    release<T extends StateContainerConstructor>(Type: T, instanceKey?: string, forceDispose?: boolean): void;
     /**
-     * Get all instances of a specific type
+     * Get all instances of a specific type.
+     * @param Type - The StateContainer class constructor
+     * @returns Array of all instances
      */
-    getAll<T extends StateContainer<any>>(Type: new (...args: any[]) => T): T[];
+    getAll<T extends StateContainerConstructor>(Type: T): InstanceReadonlyState<T>[];
     /**
-     * Safely iterate over all instances of a type
+     * Safely iterate over all instances of a type.
+     * Skips disposed instances and catches callback errors.
+     * @param Type - The StateContainer class constructor
+     * @param callback - Function to call for each instance
      */
-    forEach<T extends StateContainer<any>>(Type: new (...args: any[]) => T, callback: (instance: T) => void): void;
+    forEach<T extends StateContainerConstructor>(Type: T, callback: (instance: InstanceReadonlyState<T>) => void): void;
     /**
-     * Clear all instances of a specific type
+     * Clear all instances of a specific type (disposes them).
+     * @param Type - The StateContainer class constructor
      */
-    clear<T extends StateContainer<any>>(Type: new (...args: any[]) => T): void;
+    clear<T extends StateContainerConstructor>(Type: T): void;
     /**
-     * Get reference count for an instance
+     * Get reference count for an instance.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns Current ref count (0 if instance doesn't exist)
      */
-    getRefCount<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): number;
+    getRefCount<T extends StateContainerConstructor>(Type: T, instanceKey?: string): number;
     /**
-     * Check if an instance exists
+     * Check if an instance exists.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns true if instance exists
      */
-    hasInstance<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): boolean;
+    hasInstance<T extends StateContainerConstructor>(Type: T, instanceKey?: string): boolean;
     /**
      * Clear all instances from all types (for testing)
      *
@@ -1196,7 +1269,8 @@ export declare class StateContainerRegistry {
      */
     clearAll(): void;
     /**
-     * Get registry statistics (for debugging)
+     * Get registry statistics for debugging.
+     * @returns Object with registeredTypes, totalInstances, and typeBreakdown
      */
     getStats(): {
         registeredTypes: number;
@@ -1204,9 +1278,10 @@ export declare class StateContainerRegistry {
         typeBreakdown: Record<string, number>;
     };
     /**
-     * Get all registered types (for plugin system)
+     * Get all registered types (for plugin system).
+     * @returns Array of all registered StateContainer class constructors
      */
-    getTypes(): Array<new (...args: any[]) => StateContainer<any>>;
+    getTypes(): StateContainerConstructor[];
     /**
      * Subscribe to lifecycle events
      * @param event - The lifecycle event to listen for
@@ -1219,25 +1294,6 @@ export declare class StateContainerRegistry {
 
 /* Excluded from this release type: StateListener */
 
-/**
- * Conditionally override the state type of a StateContainer.
- * When S is `never`, returns T unchanged (inferred state type).
- * When S is provided, replaces the state type while preserving all other properties.
- *
- * @template T - The StateContainer type
- * @template S - The state type override (defaults to never)
- *
- * @example
- * // Without override - returns original type
- * type Result1 = StateOverride<MyBloc>; // MyBloc
- *
- * // With override - replaces state type
- * type Result2 = StateOverride<MyBloc, CustomState>; // Omit<MyBloc, 'state'> & { readonly state: CustomState }
- */
-export declare type StateOverride<T extends StateContainer<any, any>, S = never> = [S] extends [never] ? T : Omit<T, 'state'> & {
-    readonly state: S;
-};
-
 /* Excluded from this release type: stopProxyTracking */
 
 /**
@@ -1287,7 +1343,7 @@ export declare interface SystemEventPayloads<S, P> {
  * @template E - Event type (extends BaseEvent)
  * @template P - Props type (optional)
  */
-export declare abstract class Vertex<S, E extends BaseEvent = BaseEvent, P = undefined> extends StateContainer<S, P> {
+export declare abstract class Vertex<S extends object = any, E extends BaseEvent = BaseEvent, P = undefined> extends StateContainer<S, P> {
     private eventHandlers;
     private isProcessing;
     private eventQueue;