@blac/core 2.0.0-rc-11 → 2.0.0-rc-14

package/dist/index.d.ts

@@ -1,7 +1,21 @@
+/**
+ * Adapter metadata provided to plugins
+ */
+export declare interface AdapterMetadata {
+    componentName?: string;
+    blocInstance: BlocBase<any>;
+    renderCount: number;
+    trackedPaths?: string[];
+    isUsingDependencies?: boolean;
+    lastState?: any;
+    lastDependencyValues?: any[];
+    currentDependencyValues?: any[];
+}
+
 export declare interface AdapterOptions<B extends BlocBase<any>> {
-    id?: string;
+    instanceId?: string;
     dependencies?: (bloc: B) => unknown[];
-    props?: any;
+    staticProps?: any;
     onMount?: (bloc: B) => void;
     onUnmount?: (bloc: B) => void;
 }
@@ -20,6 +34,7 @@ export declare class Blac {
     static get instance(): Blac;
     /** Timestamp when the instance was created */
     createdAt: number;
+    private errorManager;
     static get getAllBlocs(): <B extends BlocConstructor<any>>(blocClass: B, options?: {
         searchIsolated?: boolean;
     }) => InstanceType<B>[];
@@ -45,6 +60,8 @@ export declare class Blac {
     keepAliveBlocs: Set<BlocBase<unknown>>;
     /** Flag to control whether changes should be posted to document */
     postChangesToDocument: boolean;
+    /** System plugin registry */
+    readonly plugins: SystemPluginRegistry;
     /**
      * Creates a new Blac instance.
      * @param options - Configuration options including singleton control
@@ -159,24 +176,6 @@ export declare class Blac {
      */
     getBloc: <B extends BlocConstructor<BlocBase<any>>>(blocClass: B, options?: GetBlocOptions<InstanceType<B>>) => InstanceType<B>;
     static get getBloc(): <B extends BlocConstructor<BlocBase<any>>>(blocClass: B, options?: GetBlocOptions<InstanceType<B>>) => InstanceType<B>;
-    /**
-     * Gets a bloc instance or throws an error if it doesn't exist
-     * @param blocClass - The bloc class to get
-     * @param options - Options including:
-     *   - id: The instance ID (defaults to class name if not provided)
-     *   - props: Properties to pass to the bloc constructor
-     *   - instanceRef: Optional reference string for the instance
-     */
-    getBlocOrThrow: <B extends BlocConstructor<any>>(blocClass: B, options?: {
-        id?: BlocInstanceId;
-        props?: InferPropsFromGeneric<B>;
-        instanceRef?: string;
-    }) => InstanceType<B>;
-    static get getBlocOrThrow(): <B extends BlocConstructor<any>>(blocClass: B, options?: {
-        id?: BlocInstanceId;
-        props?: InferPropsFromGeneric<B> | undefined;
-        instanceRef?: string;
-    }) => InstanceType<B>;
     /**
      * Gets all instances of a specific bloc class
      * @param blocClass - The bloc class to search for
@@ -217,10 +216,18 @@ export declare class Blac {
         isolatedBlocTypes: number;
     };
     /**
-     * Validates consumer references and cleans up orphaned consumers
+     * Validates subscription references and cleans up orphaned blocs
      */
     validateConsumers: () => void;
     static get validateConsumers(): () => void;
+    /**
+     * Bootstrap the Blac instance and all plugins
+     */
+    bootstrap(): void;
+    /**
+     * Shutdown the Blac instance and all plugins
+     */
+    shutdown(): void;
 }
 
 /**
@@ -234,15 +241,24 @@ export declare class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
         current: object;
     };
     blocInstance: InstanceType<B>;
-    private consumerTracker;
-    private static propsOwners;
-    private lastProps?;
     unmountTime: number;
     mountTime: number;
+    private subscriptionId?;
+    private unsubscribe?;
     private dependencyValues?;
     private isUsingDependencies;
+    private trackedPaths;
+    private pendingTrackedPaths;
+    private cachedStateProxy?;
+    private cachedBlocProxy?;
+    private lastProxiedState?;
     private hasMounted;
     private mountCount;
+    private lastState?;
+    private lastDependencyValues?;
+    private componentName?;
+    private renderCount;
+    private lastDependenciesFn?;
     options?: AdapterOptions<InstanceType<B>>;
     constructor(instanceProps: {
         componentRef: {
@@ -251,35 +267,35 @@ export declare class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
         blocConstructor: B;
     }, options?: typeof BlacAdapter.options);
     trackAccess(consumerRef: object, type: 'state' | 'class', path: string, value?: any): void;
-    getConsumerDependencies(consumerRef: object): DependencyArray | null;
-    shouldNotifyConsumer(consumerRef: object, changedPaths: Set<string>): boolean;
-    updateLastNotified(consumerRef: object): void;
-    resetConsumerTracking(): void;
+    updateBlocInstance(): InstanceType<B>;
+    createSubscription: (options: {
+        onChange: () => void;
+    }) => () => void;
+    hasDependencyValuesChanged: (oldValues: unknown[] | undefined, newValues: unknown[]) => boolean;
+    getStateProxy: () => BlocState<InstanceType<B>>;
+    getBlocProxy: () => InstanceType<B>;
     createStateProxy: <T extends object>(props: {
         target: T;
     }) => T;
     createClassProxy: <T extends object>(props: {
         target: T;
     }) => T;
-    updateBlocInstance(): InstanceType<B>;
-    createSubscription: (options: {
-        onChange: () => void;
-    }) => () => void;
     mount: () => void;
     unmount: () => void;
-    getProxyState: (state: BlocState<InstanceType<B>>) => BlocState<InstanceType<B>>;
-    getProxyBlocInstance: () => InstanceType<B>;
-    get calledOnMount(): boolean;
-    updateProps(props: any): void;
-    private hasDependencyValuesChanged;
+    resetTracking(): void;
+    setComponentName(name: string): void;
+    notifyRender(): void;
+    private getAdapterMetadata;
+    private getValueAtPath;
+    private getStateChangedPaths;
+    private getDeepChangedPaths;
+    getLastRerenderReason(): any;
 }
 
 /**
  * Configuration options for the Blac instance
  */
 export declare interface BlacConfig {
-    /** Whether to expose the Blac instance globally */
-    exposeBlacInstance?: boolean;
     /**
      * Whether to enable proxy dependency tracking for automatic re-render optimization.
      * When false, state changes always cause re-renders unless dependencies are manually specified.
@@ -288,6 +304,24 @@ export declare interface BlacConfig {
     proxyDependencyTracking?: boolean;
 }
 
+export declare class BlacError extends Error {
+    readonly category: ErrorCategory;
+    readonly severity: ErrorSeverity;
+    readonly context?: BlacErrorContext | undefined;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, category: ErrorCategory, severity: ErrorSeverity, context?: BlacErrorContext | undefined, cause?: unknown | undefined);
+    toString(): string;
+}
+
+export declare type BlacErrorContext = {
+    blocName?: string;
+    blocId?: string;
+    consumerId?: string;
+    pluginName?: string;
+    operation?: string;
+    metadata?: Record<string, unknown>;
+};
+
 /**
  * Interface for Blac instance management
  */
@@ -298,72 +332,27 @@ export declare interface BlacInstanceManager {
 }
 
 /**
- * A class that manages observers for a Bloc's state changes
- * @template S - The type of state being observed
+ * System-wide plugin that observes all blocs
  */
-export declare class BlacObservable<S = unknown> {
-    /** The Bloc instance this observable is associated with */
-    bloc: BlocBase<S>;
-    /**
-     * Creates a new BlacObservable instance
-     * @param bloc - The Bloc instance to observe
-     */
-    constructor(bloc: BlocBase<S>);
-    private _observers;
-    /**
-     * Gets the number of active observers
-     * @returns The number of observers currently subscribed
-     */
-    get size(): number;
-    /**
-     * Gets the set of all observers
-     * @returns The Set of all BlacObserver instances
-     */
-    get observers(): Set<BlacObserver<S>>;
-    /**
-     * Subscribes an observer to state changes
-     * @param observer - The observer to subscribe
-     * @returns A function that can be called to unsubscribe the observer
-     */
-    subscribe(observer: BlacObserver<S>): () => void;
-    /**
-     * Unsubscribes an observer from state changes
-     * @param observer - The observer to unsubscribe
-     */
-    unsubscribe(observer: BlacObserver<S>): void;
-    /**
-     * Notifies all observers of a state change
-     * @param newState - The new state value
-     * @param oldState - The previous state value
-     * @param action - Optional action that triggered the state change
-     */
-    notify(newState: S, oldState: S, action?: unknown): void;
-    /**
-     * Clears the observer set
-     */
-    clear(): void;
+export declare interface BlacPlugin extends Plugin_2 {
+    beforeBootstrap?(): void;
+    afterBootstrap?(): void;
+    beforeShutdown?(): void;
+    afterShutdown?(): void;
+    onBlocCreated?(bloc: BlocBase<any>): void;
+    onBlocDisposed?(bloc: BlocBase<any>): void;
+    onStateChanged?(bloc: BlocBase<any>, previousState: any, currentState: any): void;
+    onEventAdded?(bloc: Bloc<any, any>, event: any): void;
+    onError?(error: Error, bloc: BlocBase<unknown>, context: ErrorContext): void;
+    onAdapterCreated?(adapter: any, metadata: AdapterMetadata): void;
+    onAdapterMount?(adapter: any, metadata: AdapterMetadata): void;
+    onAdapterUnmount?(adapter: any, metadata: AdapterMetadata): void;
+    onAdapterRender?(adapter: any, metadata: AdapterMetadata): void;
+    onAdapterDisposed?(adapter: any, metadata: AdapterMetadata): void;
 }
 
-/**
- * Represents an observer that can subscribe to state changes in a Bloc
- * @template S - The type of state being observed
- */
-export declare type BlacObserver<S> = {
-    /** Function to be called when state changes */
-    fn: (newState: S, oldState: S, action?: unknown) => void | Promise<void>;
-    /** Optional function to determine if the observer should be notified of state changes */
-    dependencyArray?: BlocHookDependencyArrayFn<S>;
-    /** Dispose function for the observer */
-    dispose?: () => void;
-    /** Cached state values used for dependency comparison */
-    lastState?: unknown[];
-    /** Unique identifier for the observer */
-    id: string;
-};
-
 export declare abstract class Bloc<S, // State type
-A extends BlocEventConstraint = BlocEventConstraint, // Base Action/Event type with proper constraints
-P = unknown> extends BlocBase<S, P> {
+A extends BlocEventConstraint = BlocEventConstraint> extends BlocBase<S> {
     readonly eventHandlers: Map<new (...args: any[]) => A, (event: A, emit: (newState: S) => void) => void | Promise<void>>;
     /* Excluded from this release type: _eventQueue */
     /* Excluded from this release type: _isProcessingEvent */
@@ -386,104 +375,113 @@ P = unknown> extends BlocBase<S, P> {
 }
 
 /**
- * Base class for both Blocs and Cubits that provides core state management functionality.
- * Handles state transitions, observer notifications, lifecycle management, and addon integration.
- *
- * @abstract This class should be extended, not instantiated directly
- * @template S The type of state managed by this Bloc
- * @template P The type of props that can be passed during instance creation (optional)
+ * Base class for both Blocs and Cubits using unified subscription model.
  */
-export declare abstract class BlocBase<S, P = unknown> {
+export declare abstract class BlocBase<S> {
     uid: string;
-    /**
-     * When true, every consumer will receive its own unique instance of this Bloc.
-     * Use this when state should not be shared between components.
-     * @default false
-     */
+    blacInstance?: Blac;
     static isolated: boolean;
     get isIsolated(): boolean;
-    /**
-     * When true, the Bloc instance persists even when there are no active consumers.
-     * Useful for maintaining state between component unmount/remount cycles.
-     * @default false
-     */
     static keepAlive: boolean;
     get isKeepAlive(): boolean;
+    _isolated: boolean;
+    _id: BlocInstanceId;
+    _instanceRef?: string;
+    _name: string;
     /**
-     * Defines how dependencies are selected from the state for efficient updates.
-     * When provided, observers will only be notified when selected dependencies change.
+     * Unified subscription manager for all state notifications
      */
-    defaultDependencySelector: DependencySelector<S> | undefined;
-    /* Excluded from this release type: _isolated */
-    /* Excluded from this release type: _observer */
+    _subscriptionManager: SubscriptionManager<S>;
+    _state: S;
+    private _lifecycleManager;
+    private _batchingManager;
+    _keepAlive: boolean;
+    lastUpdate?: number;
+    _plugins: BlocPluginRegistry<S, any>;
+    onDispose?: () => void;
     /**
-     * The unique identifier for this Bloc instance.
-     * Defaults to the class name, but can be customized.
+     * Creates a new BlocBase instance with unified subscription management
      */
-    _id: BlocInstanceId;
-    /* Excluded from this release type: _instanceRef */
-    /* Excluded from this release type: _keepAlive */
+    constructor(initialState: S);
     /**
-     * @readonly
-     * Timestamp when this Bloc instance was created, useful for debugging and performance tracking.
+     * Returns the current state
      */
-    readonly _createdAt: number;
-    /* Excluded from this release type: _disposalState */
-    /* Excluded from this release type: _disposalRequestTime */
-    /* Excluded from this release type: _state */
-    /* Excluded from this release type: _oldState */
+    get state(): S;
     /**
-     * Props passed during Bloc instance creation.
-     * Can be used to configure or parameterize the Bloc's behavior.
+     * Subscribe to all state changes
      */
-    props: P | null;
-    /* Excluded from this release type: _batchingLock */
-    /* Excluded from this release type: _pendingUpdates */
-    /* Excluded from this release type: _consumerRefs */
-    /* Excluded from this release type: _validateConsumers */
+    subscribe(callback: (state: S) => void): () => void;
     /**
-     * Creates a new BlocBase instance with the given initial state.
-     * Sets up the observer, registers with the Blac manager, and initializes addons.
-     *
-     * @param initialState The initial state value for this Bloc
+     * Subscribe with a selector for optimized updates
      */
-    constructor(initialState: S);
+    subscribeWithSelector<T>(selector: (state: S) => T, callback: (value: T) => void, equalityFn?: (a: T, b: T) => boolean): () => void;
     /**
-     * Returns the current state of the Bloc.
-     * Use this getter to access the state in a read-only manner.
-     * Returns the state even during transitional lifecycle states for React compatibility.
+     * Subscribe with React component reference for automatic cleanup
      */
-    get state(): S;
+    subscribeComponent(componentRef: WeakRef<object>, callback: () => void): () => void;
+    /**
+     * Get current subscription count
+     */
+    get subscriptionCount(): number;
+    /**
+     * Track property access for a subscription
+     */
+    trackAccess(subscriptionId: string, path: string, value?: unknown): void;
+    /**
+     * Emit a new state
+     */
+    protected emit(newState: S, action?: unknown): void;
+    /**
+     * Internal state push method used by Bloc
+     */
+    _pushState(newState: S, oldState: S, action?: unknown): void;
+    _batchUpdates(callback: () => void): void;
     /**
-     * Returns whether this Bloc instance has been disposed.
-     * @returns true if the bloc is in DISPOSED state
+     * Add a plugin
+     */
+    addPlugin(plugin: BlocPlugin<S, any>): void;
+    /**
+     * Remove a plugin
+     */
+    removePlugin(plugin: BlocPlugin<S, any>): void;
+    /**
+     * Get all plugins
+     */
+    get plugins(): ReadonlyArray<BlocPlugin<S, any>>;
+    /**
+     * Disposal management
      */
     get isDisposed(): boolean;
-    /* Excluded from this release type: _name */
-    /* Excluded from this release type: _updateId */
-    /* Excluded from this release type: _atomicStateTransition */
-    /* Excluded from this release type: _dispose */
-    /* Excluded from this release type: onDispose */
-    /* Excluded from this release type: _consumers */
-    /* Excluded from this release type: _addConsumer */
-    /* Excluded from this release type: _removeConsumer */
-    /* Excluded from this release type: _disposalHandler */
-    /* Excluded from this release type: _setDisposalHandler */
-    /* Excluded from this release type: _scheduleDisposal */
-    lastUpdate: number;
-    /* Excluded from this release type: _batchingEnabled */
-    /* Excluded from this release type: _pushState */
     /**
-     * Enables batching for multiple state updates
-     * @param batchFn Function to execute with batching enabled
+     * Atomic state transition for disposal
+     */
+    _atomicStateTransition(expectedState: BlocLifecycleState, newState: BlocLifecycleState): StateTransitionResult;
+    /**
+     * Dispose the bloc and clean up resources
+     */
+    dispose(): Promise<void>;
+    /**
+     * Schedule disposal when no subscriptions remain
      */
-    batch: <T>(batchFn: () => T) => T;
+    _scheduleDisposal(): void;
+    /**
+     * Set disposal handler
+     */
+    setDisposalHandler(handler: (bloc: BlocBase<unknown>) => void): void;
+    /**
+     * Check if disposal should be scheduled (called by subscription manager)
+     */
+    checkDisposal(): void;
+    /**
+     * Cancel disposal if bloc is in disposal_requested state
+     */
+    _cancelDisposalIfRequested(): void;
 }
 
 /**
  * Represents the abstract base types for Bloc and Cubit
  */
-export declare type BlocBaseAbstract = typeof Bloc<any, any, any> | typeof Cubit<any, any>;
+export declare type BlocBaseAbstract = typeof Bloc<any, any> | typeof Cubit<any>;
 
 /**
  * Represents a constructor type for a Bloc that takes no parameters
@@ -500,11 +498,7 @@ export declare type BlocConstructor<B> = (new (...args: any) => B) & {
     keepAlive?: boolean;
 };
 
-/**
- * Extracts the constructor parameters type from a BlocBase
- * @template B - The BlocBase type to extract the constructor parameters from
- */
-export declare type BlocConstructorParameters<B extends BlocBase<any>> = BlocConstructor<B> extends new (...args: infer P) => B ? P : never;
+export declare type BlocConstructorParams<B extends BlocConstructor<BlocBase<any>>> = ConstructorParameters<B>[0];
 
 /**
  * Error boundary interface for Bloc error handling
@@ -536,9 +530,45 @@ export declare type BlocHookDependencyArrayFn<S, I = any> = (currentState: S, pr
 
 export declare type BlocInstanceId = string | number | undefined;
 
+/**
+ * Manages the lifecycle state transitions for Bloc instances.
+ * Ensures atomic state transitions to prevent race conditions during disposal.
+ */
+export declare class BlocLifecycleManager {
+    private disposalState;
+    private disposalLock;
+    private disposalTimer?;
+    private disposalHandler?;
+    get currentState(): BlocLifecycleState;
+    get isDisposed(): boolean;
+    /**
+     * Atomic state transition for disposal
+     */
+    atomicStateTransition(expectedState: BlocLifecycleState, newState: BlocLifecycleState): StateTransitionResult;
+    /**
+     * Schedule disposal after a delay
+     */
+    scheduleDisposal(delay: number, canDispose: () => boolean, onDispose: () => void): void;
+    /**
+     * Cancel disposal if in disposal requested state
+     */
+    cancelDisposal(): boolean;
+    /**
+     * Set disposal handler
+     */
+    setDisposalHandler(handler: (bloc: unknown) => void): void;
+    /**
+     * Get disposal handler
+     */
+    getDisposalHandler(): ((bloc: unknown) => void) | undefined;
+    /**
+     * Clear disposal timer
+     */
+    clearDisposalTimer(): void;
+}
+
 /**
  * Enum representing the lifecycle states of a Bloc instance
- * Used for atomic state transitions to prevent race conditions
  */
 export declare enum BlocLifecycleState {
     ACTIVE = "active",
@@ -547,6 +577,76 @@ export declare enum BlocLifecycleState {
     DISPOSED = "disposed"
 }
 
+/**
+ * Bloc-specific plugin that can transform behavior
+ */
+export declare interface BlocPlugin<TState = any, TEvent = never> extends Plugin_2 {
+    transformState?(previousState: TState, nextState: TState): TState;
+    transformEvent?(event: TEvent): TEvent | null;
+    onAttach?(bloc: BlocBase<TState>): void;
+    onDetach?(): void;
+    onStateChange?(previousState: TState, currentState: TState): void;
+    onEvent?(event: TEvent): void;
+    onError?(error: Error, context: ErrorContext): void;
+}
+
+/**
+ * Registry for bloc-specific plugins
+ */
+export declare class BlocPluginRegistry<TState, TEvent = never> implements PluginRegistry<BlocPlugin<TState, TEvent>> {
+    private plugins;
+    private executionOrder;
+    private attached;
+    /**
+     * Add a bloc plugin
+     */
+    add(plugin: BlocPlugin<TState, TEvent>): void;
+    /**
+     * Remove a bloc plugin
+     */
+    remove(pluginName: string): boolean;
+    /**
+     * Get a plugin by name
+     */
+    get(pluginName: string): BlocPlugin<TState, TEvent> | undefined;
+    /**
+     * Get all plugins in execution order
+     */
+    getAll(): ReadonlyArray<BlocPlugin<TState, TEvent>>;
+    /**
+     * Clear all plugins
+     */
+    clear(): void;
+    /**
+     * Attach all plugins to a bloc
+     */
+    attach(bloc: any): void;
+    /**
+     * Transform state through all plugins
+     */
+    transformState(previousState: TState, nextState: TState): TState;
+    /**
+     * Transform event through all plugins
+     */
+    transformEvent(event: TEvent): TEvent | null;
+    /**
+     * Notify plugins of state change
+     */
+    notifyStateChange(previousState: TState, currentState: TState): void;
+    /**
+     * Notify plugins of event
+     */
+    notifyEvent(event: TEvent): void;
+    /**
+     * Notify plugins of error
+     */
+    notifyError(error: Error, context: ErrorContext): void;
+    private validateCapabilities;
+    private canReadState;
+    private canTransformState;
+    private canInterceptEvents;
+}
+
 /**
  * Extracts the state type from either a Bloc or Cubit
  * @template T - The Bloc or Cubit type to extract the state from
@@ -580,61 +680,26 @@ export declare class BlocTest {
     static expectStates<T extends BlocBase<S>, S>(bloc: T, expectedStates: S[], timeout?: number): Promise<void>;
 }
 
-export declare interface ConsumerInfo {
-    id: string;
-    lastNotified: number;
-    hasRendered: boolean;
-    stateAccesses: Set<string>;
-    classAccesses: Set<string>;
-    stateValues: Map<string, TrackedValue>;
-    classValues: Map<string, TrackedValue>;
-    accessCount: number;
-    lastAccessTime: number;
-    firstAccessTime: number;
-}
-
-/**
- * ConsumerTracker manages both consumer registration and dependency tracking.
- * It uses a WeakMap for automatic garbage collection when consumers are no longer referenced.
- */
-export declare class ConsumerTracker {
-    private consumers;
-    private registrationCount;
-    private activeConsumers;
-    register(consumerRef: object, consumerId: string): void;
-    unregister(consumerRef: object): void;
-    trackAccess(consumerRef: object, type: 'state' | 'class', path: string, value?: any): void;
-    resetTracking(consumerRef: object): void;
-    getDependencies(consumerRef: object): DependencyArray | null;
-    hasValuesChanged(consumerRef: object, newState: any, newBlocInstance: any): boolean;
-    shouldNotifyConsumer(consumerRef: object, changedPaths: Set<string>): boolean;
-    updateLastNotified(consumerRef: object): void;
-    getConsumerInfo(consumerRef: object): ConsumerInfo | undefined;
-    setHasRendered(consumerRef: object, hasRendered: boolean): void;
-    hasConsumer(consumerRef: object): boolean;
-    getStats(): {
-        totalRegistrations: number;
-        activeConsumers: number;
-    };
-    private getValueAtPath;
-}
-
-declare interface ConsumerTracker_2 {
+declare interface ConsumerTracker {
     trackAccess: (consumerRef: object, type: 'state' | 'class', path: string, value?: any) => void;
 }
 
+/**
+ * Creates a proxy for bloc instances that tracks getter access
+ */
+export declare const createBlocProxy: <T extends object>(target: T, consumerRef: object, consumerTracker: ConsumerTracker) => T;
+
+/**
+ * Creates a proxy for state objects that tracks property access
+ */
+export declare const createStateProxy: <T extends object>(target: T, consumerRef: object, consumerTracker: ConsumerTracker, path?: string) => T;
+
 /**
  * A Cubit is a simpler version of a Bloc that doesn't handle events.
  * It manages state and provides methods to update it.
  * @template S - The type of state this Cubit manages
- * @template P - The type of parameters (optional, defaults to null)
  */
-export declare abstract class Cubit<S, P = null> extends BlocBase<S, P> {
-    /* Excluded from this release type: _updateProps */
-    /**
-     * Optional override for props handling
-     */
-    protected onPropsChanged?(oldProps: P | undefined, newProps: P): void;
+export declare abstract class Cubit<S> extends BlocBase<S> {
     /**
      * Updates the current state and notifies all observers of the change.
      * If the new state is identical to the current state (using Object.is),
@@ -653,12 +718,89 @@ export declare abstract class Cubit<S, P = null> extends BlocBase<S, P> {
     patch(statePatch: S extends object ? Partial<S> : S, ignoreChangeCheck?: boolean): void;
 }
 
-export declare interface DependencyArray {
-    statePaths: string[];
-    classPaths: string[];
+export declare const DefaultErrorStrategy: ErrorHandlingStrategy;
+
+export declare enum ErrorCategory {
+    LIFECYCLE = "LIFECYCLE",
+    STATE = "STATE",
+    PLUGIN = "PLUGIN",
+    VALIDATION = "VALIDATION",
+    DISPOSAL = "DISPOSAL",
+    CONSUMER = "CONSUMER"
+}
+
+/**
+ * Error context provided to error handlers
+ */
+export declare interface ErrorContext {
+    readonly phase: 'initialization' | 'state-change' | 'event-processing' | 'disposal';
+    readonly operation: string;
+    readonly metadata?: Record<string, unknown>;
 }
 
-declare type DependencySelector<S> = (currentState: S, previousState: S | undefined, instance: any) => unknown[];
+export declare type ErrorHandler = (error: BlacError) => void;
+
+export declare type ErrorHandlingStrategy = {
+    shouldPropagate: (error: BlacError) => boolean;
+    shouldLog: (error: BlacError) => boolean;
+    handle: (error: BlacError) => void;
+};
+
+/**
+ * Centralized error management system for BlaC framework.
+ * Handles error processing, logging, and propagation strategies.
+ */
+export declare class ErrorManager {
+    private static instance;
+    private handlers;
+    private strategy;
+    /**
+     * Get the singleton instance of ErrorManager
+     */
+    static getInstance(): ErrorManager;
+    /**
+     * Set a custom error handling strategy
+     */
+    setStrategy(strategy: ErrorHandlingStrategy): void;
+    /**
+     * Add a custom error handler that will be called for all errors
+     */
+    addHandler(handler: ErrorHandler): void;
+    /**
+     * Remove a previously added error handler
+     */
+    removeHandler(handler: ErrorHandler): void;
+    /**
+     * Process an error through all handlers and apply the configured strategy
+     */
+    handle(error: BlacError): void;
+    /**
+     * Convenience method for wrapping operations with error handling
+     */
+    wrap<T>(operation: () => T, errorFactory: (error: unknown) => BlacError): T;
+    /**
+     * Async version of wrap
+     */
+    wrapAsync<T>(operation: () => Promise<T>, errorFactory: (error: unknown) => BlacError): Promise<T>;
+}
+
+export declare enum ErrorSeverity {
+    FATAL = "FATAL",// System cannot continue
+    ERROR = "ERROR",// Operation failed but system continues
+    WARNING = "WARNING",// Potential issue but operation succeeded
+    INFO = "INFO"
+}
+
+/**
+ * Generates a deterministic instance ID from static props by extracting primitive values
+ *
+ * Rules:
+ * 1. Only considers primitive types: string, number, boolean, null, undefined
+ * 2. Ignores complex types: objects, arrays, functions, symbols
+ * 3. Sorts keys alphabetically for deterministic output
+ * 4. Returns undefined if no primitives found (caller should use default ID)
+ */
+export declare function generateInstanceIdFromProps(props: unknown): string | undefined;
 
 /**
  * Cross-platform UUID v4 generator that works in all environments including React Native/Hermes
@@ -673,7 +815,7 @@ export declare function generateUUID(): string;
 export declare interface GetBlocOptions<B extends BlocBase<unknown>> {
     id?: string;
     selector?: BlocHookDependencyArrayFn<BlocState<B>>;
-    props?: InferPropsFromGeneric<B>;
+    constructorParams?: ConstructorParameters<BlocConstructor<B>>[];
     onMount?: (bloc: B) => void;
     instanceRef?: string;
     throwIfNotFound?: boolean;
@@ -682,10 +824,27 @@ export declare interface GetBlocOptions<B extends BlocBase<unknown>> {
 }
 
 /**
- * Extracts the props type from either a Bloc or Cubit
- * @template T - The Bloc or Cubit type to extract the props from
+ * Standard error handling helper for BlaC
+ *
+ * Usage:
+ * - For fatal errors that should propagate: handleError.fatal(...)
+ * - For recoverable errors: handleError.error(...)
+ * - For warnings: handleError.warn(...)
  */
-export declare type InferPropsFromGeneric<T> = T extends Bloc<any, any, infer P> ? P : T extends Cubit<any, infer P> ? P : never;
+export declare const handleError: {
+    fatal: (message: string, category: ErrorCategory, context?: BlacErrorContext, cause?: unknown) => never;
+    error: (message: string, category: ErrorCategory, context?: BlacErrorContext, cause?: unknown) => void;
+    warn: (message: string, category: ErrorCategory, context?: BlacErrorContext, cause?: unknown) => void;
+    info: (message: string, category: ErrorCategory, context?: BlacErrorContext) => void;
+    /**
+     * Wraps a function to catch and handle errors
+     */
+    wrap: <T>(fn: () => T, category: ErrorCategory, context?: BlacErrorContext, severity?: ErrorSeverity) => T | undefined;
+    /**
+     * Wraps an async function to catch and handle errors
+     */
+    wrapAsync: <T>(fn: () => Promise<T>, category: ErrorCategory, context?: BlacErrorContext, severity?: ErrorSeverity) => Promise<T | undefined>;
+};
 
 /**
  * Memory leak detector for tests
@@ -743,35 +902,96 @@ export declare class MockCubit<S> extends Cubit<S> {
     clearStateHistory(): void;
 }
 
+/**
+ * Base interface for all plugins
+ */
+declare interface Plugin_2 {
+    readonly name: string;
+    readonly version: string;
+    readonly capabilities?: PluginCapabilities;
+}
+export { Plugin_2 as Plugin }
+
+/**
+ * Plugin capabilities for security model
+ */
+export declare interface PluginCapabilities {
+    readonly readState: boolean;
+    readonly transformState: boolean;
+    readonly interceptEvents: boolean;
+    readonly persistData: boolean;
+    readonly accessMetadata: boolean;
+}
+
+/**
+ * Plugin execution context for performance monitoring
+ */
+export declare interface PluginExecutionContext {
+    readonly pluginName: string;
+    readonly hookName: string;
+    readonly startTime: number;
+    readonly blocName?: string;
+    readonly blocId?: string;
+}
+
+/**
+ * Plugin metrics for monitoring
+ */
+export declare interface PluginMetrics {
+    readonly executionTime: number;
+    readonly executionCount: number;
+    readonly errorCount: number;
+    readonly lastError?: Error;
+    readonly lastExecutionTime?: number;
+}
+
+/**
+ * Plugin registry interface
+ */
+export declare interface PluginRegistry<T extends Plugin_2> {
+    add(plugin: T): void;
+    remove(pluginName: string): boolean;
+    get(pluginName: string): T | undefined;
+    getAll(): ReadonlyArray<T>;
+    clear(): void;
+}
+
+/**
+ * Event fired when props are updated on a Bloc or Cubit instance.
+ * This is primarily used internally by the framework to notify
+ * about prop changes in React components.
+ * @template P - The type of props being updated
+ */
 export declare class PropsUpdated<P = any> {
     readonly props: P;
     constructor(props: P);
 }
 
-export declare class ProxyFactory {
-    static createStateProxy<T extends object>(options: {
-        target: T;
+export declare const ProxyFactory: {
+    createStateProxy: (options: {
+        target: any;
         consumerRef: object;
-        consumerTracker: ConsumerTracker_2;
+        consumerTracker: ConsumerTracker;
         path?: string;
-    }): T;
-    static createClassProxy<T extends object>(options: {
-        target: T;
+    }) => any;
+    createClassProxy: (options: {
+        target: any;
         consumerRef: object;
-        consumerTracker: ConsumerTracker_2;
-    }): T;
-    static getProxyState<B extends BlocBase<any>>(options: {
-        state: BlocState<B>;
+        consumerTracker: ConsumerTracker;
+    }) => any;
+    getProxyState: <B extends BlocBase<any>>(options: {
+        state: any;
         consumerRef: object;
-        consumerTracker: ConsumerTracker_2;
-    }): BlocState<B>;
-    static getProxyBlocInstance<B extends BlocBase<any>>(options: {
+        consumerTracker: ConsumerTracker;
+    }) => any;
+    getProxyBlocInstance: <B extends BlocBase<any>>(options: {
         blocInstance: B;
         consumerRef: object;
-        consumerTracker: ConsumerTracker_2;
-    }): B;
-    static getStats(): {
-        totalProxies: number;
+        consumerTracker: ConsumerTracker;
+    }) => B;
+    getStats: () => {
+        propertyAccesses: number;
+        nestedProxiesCreated: number;
         cacheEfficiency: string;
         lifetime: string;
         proxiesPerSecond: string;
@@ -779,12 +999,71 @@ export declare class ProxyFactory {
         classProxiesCreated: number;
         cacheHits: number;
         cacheMisses: number;
-        propertyAccesses: number;
-        nestedProxiesCreated: number;
         totalProxiesCreated: number;
-        createdAt: number;
     };
-    static resetStats(): void;
+    resetStats: () => void;
+};
+
+export declare interface RerenderInfo {
+    componentName: string;
+    blocName: string;
+    blocId: string;
+    renderCount: number;
+    reason: RerenderReason;
+    timestamp: number;
+    duration?: number;
+    stackTrace?: string;
+}
+
+/**
+ * Utility class for logging component rerenders with detailed debugging information
+ */
+export declare class RerenderLogger {
+    private static componentRenderCounts;
+    private static lastRenderTimestamps;
+    private static groupedLogs;
+    private static groupTimeouts;
+    /**
+     * Log a component rerender with detailed information
+     */
+    static logRerender(info: RerenderInfo): void;
+    /**
+     * Parse the logging configuration
+     */
+    private static parseConfig;
+    /**
+     * Log immediately without grouping
+     */
+    private static logImmediate;
+    /**
+     * Log with grouping (batch multiple rerenders)
+     */
+    private static logGrouped;
+    /**
+     * Format the log message based on level
+     */
+    private static formatMessage;
+    /**
+     * Get emoji for reason type
+     */
+    private static getReasonEmoji;
+    /**
+     * Clear all tracking data
+     */
+    static clear(): void;
+    /**
+     * Get render count for a component
+     */
+    static getRenderCount(componentName: string, blocId: string): number;
+}
+
+export declare interface RerenderReason {
+    type: 'state-change' | 'dependency-change' | 'mount' | 'props-change' | 'unknown';
+    changedPaths?: string[];
+    oldValues?: Record<string, any>;
+    newValues?: Record<string, any>;
+    dependencies?: string[];
+    description?: string;
 }
 
 /**
@@ -801,18 +1080,218 @@ export declare function setBlacInstanceManager(manager: BlacInstanceManager): vo
  */
 export declare function shallowEqual(a: any, b: any): boolean;
 
-/**
- * Result of an atomic state transition operation
- */
 export declare interface StateTransitionResult {
     success: boolean;
     currentState: BlocLifecycleState;
     previousState: BlocLifecycleState;
 }
 
-export declare interface TrackedValue {
-    value: any;
-    lastAccessTime: number;
+/**
+ * Unified subscription interface that replaces the dual consumer/observer system
+ */
+export declare interface Subscription<S = unknown> {
+    /** Unique identifier for the subscription */
+    id: string;
+    /** Type of subscription for backward compatibility */
+    type: 'consumer' | 'observer';
+    /** Optional selector function to derive values from state */
+    selector?: (state: S, bloc?: BlocBase<S>) => unknown;
+    /** Custom equality function for selector results (defaults to Object.is) */
+    equalityFn?: (prev: unknown, next: unknown) => boolean;
+    /** Notification callback when state changes */
+    notify: (value: unknown, oldValue?: unknown, action?: unknown) => void;
+    /** Priority for notification order (higher = earlier) */
+    priority?: number;
+    /** WeakRef to the subscriber for automatic cleanup (React components) */
+    weakRef?: WeakRef<object>;
+    /** Last computed selector value for comparison */
+    lastValue?: unknown;
+    /** Tracked state path dependencies */
+    dependencies?: Set<string>;
+    /** Metadata for tracking and debugging */
+    metadata?: SubscriptionMetadata;
+}
+
+/**
+ * Unified subscription manager that replaces the dual consumer/observer system.
+ * Handles all state change subscriptions with a single, consistent interface.
+ */
+export declare class SubscriptionManager<S = unknown> {
+    private bloc;
+    private subscriptions;
+    private pathToSubscriptions;
+    private weakRefCleanupScheduled;
+    private totalNotifications;
+    constructor(bloc: BlocBase<S>);
+    /**
+     * Subscribe to state changes
+     */
+    subscribe(options: SubscriptionOptions<S>): () => void;
+    /**
+     * Unsubscribe by ID
+     */
+    unsubscribe(id: string): void;
+    /**
+     * Notify all subscriptions of state change
+     */
+    notify(newState: S, oldState: S, action?: unknown): void;
+    /**
+     * Track a path access for a subscription
+     */
+    trackAccess(subscriptionId: string, path: string, value?: unknown): void;
+    /**
+     * Get the paths that changed between two states
+     */
+    private getChangedPaths;
+    /**
+     * Check if a subscription should be notified based on changed paths
+     */
+    shouldNotifyForPaths(subscriptionId: string, changedPaths: Set<string>): boolean;
+    /**
+     * Get statistics about subscriptions
+     */
+    getStats(): SubscriptionManagerStats;
+    /**
+     * Clear all subscriptions
+     */
+    clear(): void;
+    /**
+     * Get subscription by ID
+     */
+    getSubscription(id: string): Subscription<S> | undefined;
+    /**
+     * Check if there are any active subscriptions
+     */
+    get hasSubscriptions(): boolean;
+    /**
+     * Get count of active subscriptions
+     */
+    get size(): number;
+    /**
+     * Clean up subscriptions with dead weak references
+     */
+    private cleanupDeadReferences;
+    /**
+     * Schedule weak reference cleanup for next tick
+     */
+    private scheduleWeakRefCleanup;
+}
+
+export declare interface SubscriptionManagerStats {
+    /** Total number of active subscriptions */
+    activeSubscriptions: number;
+    /** Number of consumer subscriptions */
+    consumerCount: number;
+    /** Number of observer subscriptions */
+    observerCount: number;
+    /** Total notifications sent */
+    totalNotifications: number;
+    /** Number of tracked dependencies */
+    trackedDependencies: number;
+}
+
+export declare interface SubscriptionMetadata {
+    /** Timestamp of last notification */
+    lastNotified?: number;
+    /** Whether the subscriber has rendered (React-specific) */
+    hasRendered?: boolean;
+    /** Number of times this subscription accessed state */
+    accessCount?: number;
+    /** First access timestamp */
+    firstAccessTime?: number;
+    /** Last access timestamp */
+    lastAccessTime?: number;
+}
+
+export declare interface SubscriptionOptions<S> {
+    /** Type of subscription */
+    type: 'consumer' | 'observer';
+    /** Optional selector function */
+    selector?: (state: S, bloc?: BlocBase<S>) => unknown;
+    /** Custom equality function */
+    equalityFn?: (prev: unknown, next: unknown) => boolean;
+    /** Notification callback */
+    notify: (value: unknown, oldValue?: unknown, action?: unknown) => void;
+    /** Priority for notifications */
+    priority?: number;
+    /** WeakRef to subscriber */
+    weakRef?: WeakRef<object>;
+}
+
+/**
+ * Registry for system-wide plugins
+ */
+export declare class SystemPluginRegistry implements PluginRegistry<BlacPlugin> {
+    private plugins;
+    private metrics;
+    private executionOrder;
+    /**
+     * Add a system plugin
+     */
+    add(plugin: BlacPlugin): void;
+    /**
+     * Remove a system plugin
+     */
+    remove(pluginName: string): boolean;
+    /**
+     * Get a plugin by name
+     */
+    get(pluginName: string): BlacPlugin | undefined;
+    /**
+     * Get all plugins in execution order
+     */
+    getAll(): ReadonlyArray<BlacPlugin>;
+    /**
+     * Clear all plugins
+     */
+    clear(): void;
+    /**
+     * Execute a hook on all plugins
+     */
+    executeHook(hookName: keyof BlacPlugin, args: unknown[], errorHandler?: (error: Error, plugin: BlacPlugin) => void): void;
+    /**
+     * Bootstrap all plugins
+     */
+    bootstrap(): void;
+    /**
+     * Shutdown all plugins
+     */
+    shutdown(): void;
+    /**
+     * Notify plugins of bloc creation
+     */
+    notifyBlocCreated(bloc: BlocBase<any>): void;
+    /**
+     * Notify plugins of bloc disposal
+     */
+    notifyBlocDisposed(bloc: BlocBase<any>): void;
+    /**
+     * Notify plugins of state change
+     */
+    notifyStateChanged(bloc: BlocBase<any>, previousState: any, currentState: any): void;
+    /**
+     * Notify plugins of event addition
+     */
+    notifyEventAdded(bloc: Bloc<any, any>, event: any): void;
+    /**
+     * Notify plugins of errors
+     */
+    notifyError(error: Error, bloc: BlocBase<unknown>, context: ErrorContext): void;
+    /**
+     * Notify plugins of adapter lifecycle events
+     */
+    notifyAdapterCreated(adapter: any, metadata: AdapterMetadata): void;
+    notifyAdapterMount(adapter: any, metadata: AdapterMetadata): void;
+    notifyAdapterUnmount(adapter: any, metadata: AdapterMetadata): void;
+    notifyAdapterRender(adapter: any, metadata: AdapterMetadata): void;
+    notifyAdapterDisposed(adapter: any, metadata: AdapterMetadata): void;
+    /**
+     * Get metrics for a plugin
+     */
+    getMetrics(pluginName: string): Map<string, PluginMetrics> | undefined;
+    private initializeMetrics;
+    private recordSuccess;
+    private recordError;
 }
 
 /**