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

package/dist/index.d.cts

@@ -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>> {
+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>> {
     /** 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,7 +199,7 @@ export declare interface BlacPluginWithInit extends BlacPlugin {
  * Used for type-safe hook parameters.
  * @template TBloc - The StateContainer instance type
  */
-export declare type BlocConstructor<S = any, T extends new (...args: any[]) => StateContainer<S, any> = new (...args: any[]) => StateContainer<S, any>> = (new (...args: any[]) => InstanceType<T>) & {
+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[]): {
@@ -267,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.
@@ -276,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 */
 
@@ -339,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<StateContainerConstructor>>;
+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.
@@ -349,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.
@@ -357,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.
@@ -365,7 +365,7 @@ 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
@@ -391,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
@@ -423,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)
@@ -465,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
      */
@@ -488,7 +488,9 @@ export declare type ExtractProps<T> = T extends StateContainerConstructor<any, i
  * Extract the state type from a StateContainer
  * @template T - The StateContainer type
  */
-export declare type ExtractState<T> = T extends StateContainerConstructor<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)
@@ -555,9 +557,9 @@ export declare function getStaticProp<V, T extends StateContainerConstructor = S
 
 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 */
@@ -596,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.
@@ -604,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.
@@ -612,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
@@ -658,6 +660,14 @@ 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 */
 
 /**
@@ -752,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>> {
+export declare interface ManualDepsConfig<TBloc extends StateContainerConstructor> {
     /** Function that returns dependency array from state and bloc */
-    dependencies: (state: any, bloc: TBloc) => any[];
+    dependencies: (state: ExtractState<TBloc>, bloc: InstanceState<TBloc>) => any[];
 }
 
 /* Excluded from this release type: parsePath */
@@ -782,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
      */
@@ -903,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 = any, P = any> {
+export declare abstract class StateContainer<S extends object = any, P = any> {
     /* Excluded from this release type: __excludeFromDevTools */
     /* Excluded from this release type: _registry */
     /**
@@ -990,12 +1000,12 @@ export declare abstract class StateContainer<S = any, P = any> {
      * Get all instances of this class
      * @returns Array of all instances
      */
-    static getAll<T extends StateContainerConstructor = StateContainerConstructor>(this: T): InstanceType<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 StateContainerConstructor = StateContainerConstructor>(this: T, callback: (instance: InstanceType<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)
      */
@@ -1049,7 +1059,7 @@ export declare abstract class StateContainer<S = any, P = any> {
      */
     initConfig(config: StateContainerConfig): void;
     /** Current state value */
-    get state(): S;
+    get state(): Readonly<S>;
     /** Whether this instance has been disposed */
     get isDisposed(): boolean;
     /**
@@ -1116,7 +1126,11 @@ export declare interface StateContainerConfig {
  * @template S - State type managed by the container
  * @template P - Props type passed to the container
  */
-export declare type StateContainerConstructor<S = any, P = any> = new (...args: any[]) => StateContainer<S, P>;
+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.
@@ -1220,14 +1234,14 @@ export declare class StateContainerRegistry {
      * @param Type - The StateContainer class constructor
      * @returns Array of all instances
      */
-    getAll<T extends StateContainerConstructor>(Type: T): InstanceType<T>[];
+    getAll<T extends StateContainerConstructor>(Type: T): InstanceReadonlyState<T>[];
     /**
      * 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 StateContainerConstructor>(Type: T, callback: (instance: InstanceType<T>) => void): void;
+    forEach<T extends StateContainerConstructor>(Type: T, callback: (instance: InstanceReadonlyState<T>) => void): void;
     /**
      * Clear all instances of a specific type (disposes them).
      * @param Type - The StateContainer class constructor
@@ -1329,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;

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>> {
+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>> {
     /** 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,7 +199,7 @@ export declare interface BlacPluginWithInit extends BlacPlugin {
  * Used for type-safe hook parameters.
  * @template TBloc - The StateContainer instance type
  */
-export declare type BlocConstructor<S = any, T extends new (...args: any[]) => StateContainer<S, any> = new (...args: any[]) => StateContainer<S, any>> = (new (...args: any[]) => InstanceType<T>) & {
+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[]): {
@@ -267,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.
@@ -276,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 */
 
@@ -339,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<StateContainerConstructor>>;
+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.
@@ -349,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.
@@ -357,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.
@@ -365,7 +365,7 @@ 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
@@ -391,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
@@ -423,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)
@@ -465,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
      */
@@ -488,7 +488,9 @@ export declare type ExtractProps<T> = T extends StateContainerConstructor<any, i
  * Extract the state type from a StateContainer
  * @template T - The StateContainer type
  */
-export declare type ExtractState<T> = T extends StateContainerConstructor<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)
@@ -555,9 +557,9 @@ export declare function getStaticProp<V, T extends StateContainerConstructor = S
 
 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 */
@@ -596,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.
@@ -604,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.
@@ -612,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
@@ -658,6 +660,14 @@ 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 */
 
 /**
@@ -752,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>> {
+export declare interface ManualDepsConfig<TBloc extends StateContainerConstructor> {
     /** Function that returns dependency array from state and bloc */
-    dependencies: (state: any, bloc: TBloc) => any[];
+    dependencies: (state: ExtractState<TBloc>, bloc: InstanceState<TBloc>) => any[];
 }
 
 /* Excluded from this release type: parsePath */
@@ -782,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
      */
@@ -903,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 = any, P = any> {
+export declare abstract class StateContainer<S extends object = any, P = any> {
     /* Excluded from this release type: __excludeFromDevTools */
     /* Excluded from this release type: _registry */
     /**
@@ -990,12 +1000,12 @@ export declare abstract class StateContainer<S = any, P = any> {
      * Get all instances of this class
      * @returns Array of all instances
      */
-    static getAll<T extends StateContainerConstructor = StateContainerConstructor>(this: T): InstanceType<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 StateContainerConstructor = StateContainerConstructor>(this: T, callback: (instance: InstanceType<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)
      */
@@ -1049,7 +1059,7 @@ export declare abstract class StateContainer<S = any, P = any> {
      */
     initConfig(config: StateContainerConfig): void;
     /** Current state value */
-    get state(): S;
+    get state(): Readonly<S>;
     /** Whether this instance has been disposed */
     get isDisposed(): boolean;
     /**
@@ -1116,7 +1126,11 @@ export declare interface StateContainerConfig {
  * @template S - State type managed by the container
  * @template P - Props type passed to the container
  */
-export declare type StateContainerConstructor<S = any, P = any> = new (...args: any[]) => StateContainer<S, P>;
+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.
@@ -1220,14 +1234,14 @@ export declare class StateContainerRegistry {
      * @param Type - The StateContainer class constructor
      * @returns Array of all instances
      */
-    getAll<T extends StateContainerConstructor>(Type: T): InstanceType<T>[];
+    getAll<T extends StateContainerConstructor>(Type: T): InstanceReadonlyState<T>[];
     /**
      * 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 StateContainerConstructor>(Type: T, callback: (instance: InstanceType<T>) => void): void;
+    forEach<T extends StateContainerConstructor>(Type: T, callback: (instance: InstanceReadonlyState<T>) => void): void;
     /**
      * Clear all instances of a specific type (disposes them).
      * @param Type - The StateContainer class constructor
@@ -1329,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;

package/dist/index.js

@@ -833,7 +833,9 @@ var StateContainerRegistry = class {
 	*/
 	on(event, listener) {
 		if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
-		this.listeners.get(event).add(listener);
+		const instance = this.listeners.get(event);
+		if (!instance) throw new Error(`${BLAC_ERROR_PREFIX} Failed to register listener for event '${event}'`);
+		instance.add(listener);
 		return () => {
 			this.listeners.get(event)?.delete(listener);
 		};
@@ -880,12 +882,12 @@ function getPluginManager() {
 *
 * @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 });
 *   }
 * }
 * ```