@blac/core 2.0.0 → 2.0.3

package/dist/index.d.ts

@@ -1,505 +1,794 @@
+export declare function acquire<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): InstanceType<T>;
+
 /**
- * Main Blac class that manages the state management system.
- * Implements a singleton pattern to ensure only one instance exists.
- * Handles bloc lifecycle, plugin management, and instance tracking.
+ * Decorator to configure StateContainer classes.
+ *
+ * @example Decorator syntax (requires experimentalDecorators or TC39 decorators)
+ * ```ts
+ * @blac({ isolated: true })
+ * class FormBloc extends Cubit<FormState> {}
+ *
+ * @blac({ keepAlive: true })
+ * class AuthBloc extends Cubit<AuthState> {}
+ *
+ * @blac({ excludeFromDevTools: true })
+ * class InternalBloc extends Cubit<InternalState> {}
+ * ```
  *
- * Key responsibilities:
- * - Managing bloc instances (creation, disposal, lookup)
- * - Handling isolated and non-isolated blocs
- * - Managing plugins and lifecycle events
- * - Providing logging and debugging capabilities
+ * @example Function syntax (no decorator support needed)
+ * ```ts
+ * const FormBloc = blac({ isolated: true })(
+ *   class extends Cubit<FormState> {}
+ * );
+ * ```
  */
-export declare class Blac {
-    /** The singleton instance of Blac */
-    static instance: Blac;
-    /** Timestamp when the instance was created */
-    createdAt: number;
-    static getAllBlocs: <B extends BlocConstructor<unknown>>(blocClass: B, options?: {
-        searchIsolated?: boolean;
-    }) => InstanceType<B>[];
-    static addPlugin: (plugin: BlacPlugin) => void;
-    /** Map storing all registered bloc instances by their class name and ID */
-    blocInstanceMap: Map<string, BlocBase<any>>;
-    /** Map storing isolated bloc instances grouped by their constructor */
-    isolatedBlocMap: Map<BlocConstructor<any>, BlocBase<any>[]>;
-    pluginList: BlacPlugin[];
-    /** Flag to control whether changes should be posted to document */
-    postChangesToDocument: boolean;
-    /**
-     * Creates a new Blac instance.
-     * @param options - Configuration options including singleton control
-     */
-    constructor(options?: {
-        __unsafe_ignore_singleton?: boolean;
-    });
-    /** Flag to enable/disable logging */
-    static enableLog: boolean;
-    /**
-     * Logs messages to console when logging is enabled
-     * @param args - Arguments to log
-     */
-    log: (...args: unknown[]) => void;
-    static log: (...args: unknown[]) => void;
-    /**
-     * Gets the singleton instance of Blac
-     * @returns The Blac instance
-     */
-    static getInstance(): Blac;
-    /**
-     * Logs a warning message
-     * @param message - Warning message
-     * @param args - Additional arguments
-     */
-    warn: (message: string, ...args: unknown[]) => void;
-    static warn: (message: string, ...args: unknown[]) => void;
+export declare function blac(options: BlacOptions): <T extends new (...args: any[]) => any>(target: T, _context?: ClassDecoratorContext) => T;
+
+/**
+ * Configuration options for the @blac decorator.
+ * Only one option can be specified at a time (union type).
+ */
+export declare type BlacOptions = 
+/** Mark bloc as isolated (each component gets its own instance) */
+    {
+    isolated: true;
+}
+/** Mark bloc to never be auto-disposed when ref count reaches 0 */
+| {
+    keepAlive: true;
+}
+/** Exclude bloc from DevTools tracking (prevents infinite loops) */
+| {
+    excludeFromDevTools: true;
+};
+
+/**
+ * Interface for plugins that extend BlaC functionality
+ */
+export declare interface BlacPlugin {
+    /** Unique plugin identifier */
+    readonly name: string;
+    /** Plugin version identifier */
+    readonly version: string;
     /**
-     * Logs an error message
-     * @param message - Error message
-     * @param args - Additional arguments
+     * Called when the plugin is installed (optional)
      */
-    error: (message: string, ...args: unknown[]) => void;
-    static error: (message: string, ...args: unknown[]) => void;
+    onInstall?(context: PluginContext): void;
     /**
-     * Resets the Blac instance to a new one, disposing non-keepAlive blocs
-     * from the old instance.
+     * Called when the plugin is uninstalled
      */
-    resetInstance: () => void;
-    static resetInstance: () => void;
+    onUninstall?(): void;
     /**
-     * Adds a plugin to the Blac instance
-     * @param plugin - The plugin to add
+     * Called when a state container instance is created
      */
-    addPlugin: (plugin: BlacPlugin) => void;
+    onInstanceCreated?(instance: StateContainer<any>, context: PluginContext): void;
     /**
-     * Dispatches a lifecycle event to all registered plugins
-     * @param event - The lifecycle event to dispatch
-     * @param bloc - The bloc instance involved in the event
-     * @param params - Additional parameters for the event
+     * Called when state changes in a container instance
      */
-    dispatchEventToPlugins: (event: BlacLifecycleEvent, bloc: BlocBase<any>, params?: unknown) => void;
+    onStateChanged?<S extends object = any>(instance: StateContainer<S>, previousState: S, currentState: S, callstack: string | undefined, context: PluginContext): void;
     /**
-     * Dispatches a lifecycle event and handles related cleanup actions.
-     * This method is responsible for:
-     * - Logging the event
-     * - Handling bloc disposal when needed
-     * - Managing bloc consumer cleanup
-     * - Forwarding the event to plugins
-     *
-     * @param event - The lifecycle event to dispatch
-     * @param bloc - The bloc instance involved in the event
-     * @param params - Additional parameters for the event
+     * Called when a state container instance is disposed
      */
-    dispatchEvent: (event: BlacLifecycleEvent, bloc: BlocBase<any>, params?: unknown) => void;
+    onInstanceDisposed?(instance: StateContainer<any>, context: PluginContext): void;
+}
+
+/**
+ * Plugin interface variant that requires mandatory onInstall hook
+ */
+export declare interface BlacPluginWithInit extends BlacPlugin {
     /**
-     * Disposes of a bloc instance by removing it from the appropriate registry
-     * @param bloc - The bloc instance to dispose
+     * Required initialization hook called when plugin is installed
      */
-    disposeBloc: (bloc: BlocBase<any>) => void;
+    onInstall(context: PluginContext): void;
+}
+
+declare const BLOC_REF_MARKER: unique symbol;
+
+/**
+ * Constructor type for StateContainer classes with static registry methods.
+ * Used for type-safe hook parameters.
+ * @template TBloc - The StateContainer instance type
+ */
+export declare type BlocConstructor<S extends object = any, T extends new (...args: any[]) => StateContainer<S> = new (...args: any[]) => StateContainer<S>> = (new (...args: any[]) => InstanceType<T>) & {
+    acquire(instanceKey?: string, ...args: any[]): InstanceType<T>;
+    borrow(instanceKey?: string, ...args: any[]): InstanceType<T> | null;
+    borrowSafe(instanceKey?: string, ...args: any[]): {
+        error: Error;
+        instance: null;
+    } | {
+        error: null;
+        instance: InstanceType<T>;
+    };
+    ensure(instanceKey?: string): InstanceType<T>;
+    release(instanceKey?: string): void;
+    isolated?: boolean;
+    keepAlive?: boolean;
+};
+
+declare type BlocInput = StateContainerConstructor | BlocRef<StateContainerConstructor>;
+
+/**
+ * Extract instance type from an abstract class constructor
+ * @template T - The abstract class constructor type
+ */
+export declare type BlocInstanceType<T extends abstract new (...args: any) => any> = T extends abstract new (...args: any) => infer R ? R : any;
+
+/**
+ * Reference to a specific bloc instance by class and instance ID.
+ */
+export declare interface BlocRef<T extends StateContainerConstructor> {
+    [BLOC_REF_MARKER]: true;
+    blocClass: T;
+    instanceId: string;
+}
+
+export declare function borrow<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): InstanceType<T>;
+
+export declare function borrowSafe<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): {
+    error: Error;
+    instance: null;
+} | {
+    error: null;
+    instance: InstanceType<T>;
+};
+
+/* Excluded from this release type: capturePaths */
+
+export declare function clear<T extends StateContainerConstructor>(BlocClass: T): void;
+
+/* Excluded from this release type: clearActiveTracker */
+
+export declare function clearAll(): void;
+
+/* Excluded from this release type: clearExternalDependencies */
+
+/* Excluded from this release type: commitTrackedGetters */
+
+/* Excluded from this release type: createBlocProxy */
+
+/* Excluded from this release type: createDependencyProxy */
+
+/* Excluded from this release type: createDependencyState */
+
+/* Excluded from this release type: createGetterState */
+
+/**
+ * Simple state container with direct state emission.
+ * Extends StateContainer with public methods for emitting and updating state.
+ *
+ * @template S - State type
+ */
+export declare abstract class Cubit<S extends object = any> extends StateContainer<S> {
+    constructor(initialState: S);
     /**
-     * Creates a unique key for a bloc instance in the map based on the bloc class name and instance ID
-     * @param blocClassName - The name of the bloc class
-     * @param id - The instance ID
-     * @returns A unique key string in the format "className:id"
+     * Replace state with a new value and notify all listeners
+     * @param newState - The new state value
      */
-    createBlocInstanceMapKey(blocClassName: string, id: BlocInstanceId): string;
+    emit(newState: S): void;
     /**
-     * Unregister a bloc instance from the main registry
-     * @param bloc - The bloc instance to unregister
+     * Transform current state using an updater function and emit the new state
+     * @param updater - Function that receives current state and returns new state
      */
-    unregisterBlocInstance(bloc: BlocBase<any>): void;
+    update(updater: (current: S) => S): void;
     /**
-     * Registers a bloc instance in the main registry
-     * @param bloc - The bloc instance to register
+     * Merge partial state changes into current state (only for object states)
      */
-    registerBlocInstance(bloc: BlocBase<any>): void;
+    patch: S extends object ? (partial: Partial<S>) => void : never;
+}
+
+/**
+ * Manages subscriptions to state container dependencies.
+ * Provides efficient sync mechanism to add/remove subscriptions
+ * as dependencies change between callback invocations.
+ */
+export declare class DependencyManager {
+    private subscriptions;
+    private currentDeps;
     /**
-     * Finds a registered bloc instance by its class and ID
-     * @param blocClass - The bloc class to search for
-     * @param id - The instance ID
-     * @returns The found bloc instance or undefined if not found
+     * Sync subscriptions with a new set of dependencies.
+     * Adds subscriptions for new deps, removes subscriptions for stale deps.
+     *
+     * @param newDeps - The new set of dependencies to subscribe to
+     * @param onChange - Callback to invoke when any dependency changes
+     * @param exclude - Optional instance to exclude from subscriptions (e.g., primary bloc)
+     * @returns true if the dependency set changed, false if unchanged
      */
-    findRegisteredBlocInstance<B extends BlocConstructor<unknown>>(blocClass: B, id: BlocInstanceId): InstanceType<B> | undefined;
+    sync(newDeps: Set<StateContainerInstance>, onChange: () => void, exclude?: StateContainerInstance): boolean;
     /**
-     * Registers an isolated bloc instance in the isolated registry
-     * @param bloc - The isolated bloc instance to register
+     * Add a single dependency subscription.
      */
-    registerIsolatedBlocInstance(bloc: BlocBase<any>): void;
+    add(dep: StateContainerInstance, onChange: () => void): void;
     /**
-     * Unregister an isolated bloc instance from the isolated registry
-     * @param bloc - The isolated bloc instance to unregister
+     * Check if a dependency is currently subscribed.
      */
-    unregisterIsolatedBlocInstance(bloc: BlocBase<any>): void;
+    has(dep: StateContainerInstance): boolean;
     /**
-     * Finds an isolated bloc instance by its class and ID
+     * Get the current set of dependencies.
      */
-    findIsolatedBlocInstance<B extends BlocConstructor<unknown>>(blocClass: B, id: BlocInstanceId): InstanceType<B> | undefined;
+    getDependencies(): Set<StateContainerInstance>;
     /**
-     * Creates a new bloc instance and registers it in the appropriate registry
-     * @param blocClass - The bloc class to instantiate
-     * @param id - The instance ID
-     * @param props - Properties to pass to the bloc constructor
-     * @param instanceRef - Optional reference string for the instance
-     * @returns The newly created bloc instance
+     * Clean up all active subscriptions.
      */
-    createNewBlocInstance<B extends BlocConstructor<BlocBase<any>>>(blocClass: B, id: BlocInstanceId, options?: GetBlocOptions<InstanceType<B>>): InstanceType<B>;
-    /**
-     * Gets or creates a bloc instance based on the provided class and options.
-     * If a bloc with the given ID exists, it will be returned. Otherwise, a new instance will be created.
-     *
-     * @param blocClass - The bloc class to get or create
-     * @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
-     * @returns The bloc instance
-     */
-    getBloc: <B extends BlocConstructor<BlocBase<any>>>(blocClass: B, options?: GetBlocOptions<InstanceType<B>>) => InstanceType<B>;
-    static 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<unknown>>(blocClass: B, options?: {
-        id?: BlocInstanceId;
-        props?: InferPropsFromGeneric<B>;
-        instanceRef?: string;
-    }) => InstanceType<B>;
-    static getBlocOrThrow: <B extends BlocConstructor<unknown>>(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
-     * @param options - Options including:
-     *   - searchIsolated: Whether to search in isolated blocs (defaults to bloc's isolated property)
-     * @returns Array of matching bloc instances
-     */
-    getAllBlocs: <B extends BlocConstructor<unknown>>(blocClass: B, options?: {
-        searchIsolated?: boolean;
-    }) => InstanceType<B>[];
+    cleanup(): void;
+    private areSetsEqual;
 }
 
-declare type BlacAddon = {
-    name: string;
-    onInit?: BlacAddonInit;
-    onEmit?: BlacAddonEmit;
+/* Excluded from this release type: DependencyState */
+
+export declare function ensure<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): InstanceType<T>;
+
+/**
+ * Extract constructor argument types from a class
+ * @template T - The class type
+ */
+export declare type ExtractConstructorArgs<T> = T extends new (...args: infer P) => any ? P : never[];
+
+declare type ExtractInstance<T> = T extends BlocRef<infer C> ? InstanceType<C> : T extends StateContainerConstructor ? InstanceType<T> : never;
+
+declare type ExtractInstances<T extends readonly BlocInput[]> = {
+    [K in keyof T]: ExtractInstance<T[K]>;
 };
 
-declare type BlacAddonEmit = (params: {
-    oldState: unknown;
-    newState: unknown;
-    cubit: BlocBase<any>;
-}) => void;
+/**
+ * Extract the state type from a StateContainer
+ * @template T - The StateContainer type
+ */
+export declare type ExtractState<T> = T extends StateContainerConstructor<infer S> ? Readonly<S> : never;
+
+export declare type ExtractStateMutable<T> = T extends StateContainerConstructor<infer S> ? S : never;
 
-declare type BlacAddonInit = (bloc: BlocBase<any>) => void;
+export declare function forEach<T extends StateContainerConstructor>(BlocClass: T, callback: (instance: InstanceReadonlyState<T>) => void): void;
 
 /**
- * Configuration options for the Blac instance
+ * Generate a unique isolated instance key
+ * Uses base36 encoding for compact, URL-safe identifiers
+ *
+ * Format: "isolated-{9-char-random-string}"
+ * Example: "isolated-k7x2m9p4q"
+ *
+ * @returns A unique isolated instance key
  */
-export declare interface BlacConfig {
-    /** Whether to expose the Blac instance globally */
-    exposeBlacInstance?: boolean;
+export declare function generateIsolatedKey(): string;
+
+export declare function getAll<T extends StateContainerConstructor>(BlocClass: T): InstanceReadonlyState<T>[];
+
+/**
+ * Get the global plugin manager
+ */
+export declare function getPluginManager(): any;
+
+export declare function getRefCount<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): number;
+
+/* Excluded from this release type: GetterState */
+
+/**
+ * Global default registry instance
+ */
+export declare const globalRegistry: StateContainerRegistry;
+
+/* Excluded from this release type: hasDependencyChanges */
+
+/* Excluded from this release type: hasGetterChanges */
+
+export declare function hasInstance<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): boolean;
+
+/* Excluded from this release type: hasTrackedData */
+
+/**
+ * Create a reference to a specific bloc instance.
+ *
+ * @example
+ * ```ts
+ * watch(instance(UserBloc, 'user-123'), (userBloc) => {
+ *   console.log(userBloc.state.name);
+ * });
+ * ```
+ */
+export declare function instance<T extends StateContainerConstructor>(BlocClass: T, instanceId: string): BlocRef<T>;
+
+/**
+ * Entry in the instance registry, tracking the instance and its reference count
+ * @template T - Instance type
+ */
+export declare interface InstanceEntry<T = any> {
+    /** The state container instance */
+    instance: T;
+    /** Number of active references to this instance */
+    refCount: number;
 }
 
 /**
- * Enum representing different lifecycle events that can occur in the Blac system.
- * These events are used to track the lifecycle of blocs and their consumers.
+ * Metadata information about a state container instance for debugging and inspection
  */
-export declare enum BlacLifecycleEvent {
-    BLOC_DISPOSED = "BLOC_DISPOSED",
-    BLOC_CREATED = "BLOC_CREATED",
-    LISTENER_REMOVED = "LISTENER_REMOVED",
-    LISTENER_ADDED = "LISTENER_ADDED",
-    STATE_CHANGED = "STATE_CHANGED",
-    BLOC_CONSUMER_REMOVED = "BLOC_CONSUMER_REMOVED",
-    BLOC_CONSUMER_ADDED = "BLOC_CONSUMER_ADDED"
+export declare interface InstanceMetadata {
+    /** Unique instance identifier */
+    id: string;
+    /** Name of the state container class */
+    className: string;
+    /** Whether the instance has been disposed */
+    isDisposed: boolean;
+    /** Display name for the instance */
+    name: string;
+    /** When state last changed (milliseconds) */
+    lastStateChangeTimestamp: number;
+    /** Current state value */
+    state: any;
+    /** Timestamp when instance was created (milliseconds) */
+    createdAt: number;
+    /** Whether this is an isolated (component-scoped) instance */
+    isIsolated: boolean;
+    /** Stack trace from when instance was created (for debugging) */
+    callstack?: string;
+    /** Previous state value */
+    previousState?: any;
+    /** Current state value */
+    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 */
+
 /**
- * A class that manages observers for a Bloc's state changes
- * @template S - The type of state being observed
+ * 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 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;
+export declare function isIsolatedClass<T extends StateContainerConstructor>(Type: T): boolean;
+
+/**
+ * Lifecycle events emitted by the registry
+ */
+export declare type LifecycleEvent = 'created' | 'stateChanged' | 'disposed';
+
+/**
+ * Listener function type for each lifecycle event
+ * @template E - The lifecycle event type
+ */
+export declare type LifecycleListener<E extends LifecycleEvent> = E extends 'created' ? (container: StateContainer<any>) => void : E extends 'stateChanged' ? (container: StateContainer<any>, previousState: any, currentState: any, callstack?: string) => void : E extends 'disposed' ? (container: StateContainer<any>) => void : never;
+
+/* Excluded from this release type: PathInfo */
+
+/**
+ * Configuration options for plugin installation
+ */
+export declare interface PluginConfig {
+    /** Enable or disable the plugin */
+    enabled?: boolean;
+    /** Environments where plugin runs */
+    environment?: 'development' | 'production' | 'test' | 'all';
+}
+
+/**
+ * Safe context API provided to plugins for accessing registry data
+ */
+export declare interface PluginContext {
     /**
-     * Gets the set of all observers
-     * @returns The Set of all BlacObserver instances
+     * Get metadata for a specific instance
      */
-    get observers(): Set<BlacObserver<S>>;
+    getInstanceMetadata(instance: StateContainer<any>): InstanceMetadata;
     /**
-     * Subscribes an observer to state changes
-     * @param observer - The observer to subscribe
-     * @returns A function that can be called to unsubscribe the observer
+     * Get current state from a container
      */
-    subscribe(observer: BlacObserver<S>): () => void;
+    getState<S extends object = any>(instance: StateContainer<S>): S;
     /**
-     * Unsubscribes an observer from state changes
-     * @param observer - The observer to unsubscribe
+     * Get all instances of a specific type
      */
-    unsubscribe(observer: BlacObserver<S>): void;
+    queryInstances<T extends StateContainer<any>>(typeClass: new (...args: any[]) => T): T[];
     /**
-     * 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
+     * Get all registered state container types
      */
-    notify(newState: S, oldState: S, action?: unknown): void;
+    getAllTypes(): Array<new (...args: any[]) => StateContainer<any>>;
     /**
-     * Disposes of all observers and clears the observer set
+     * Get registry statistics
      */
-    dispose(): void;
+    getStats(): {
+        registeredTypes: number;
+        totalInstances: number;
+        typeBreakdown: Record<string, number>;
+    };
 }
 
 /**
- * Represents an observer that can subscribe to state changes in a Bloc
- * @template S - The type of state being observed
+ * Manages plugin lifecycle for the BlaC state management system.
+ * Plugins receive notifications about state container lifecycle events.
+ *
+ * @example
+ * ```ts
+ * const manager = createPluginManager(registry);
+ * manager.install(myPlugin, { environment: 'development' });
+ * ```
  */
-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 interface BlacPlugin {
-    name: string;
-    onEvent(event: BlacLifecycleEvent, bloc: BlocBase<any>, params?: unknown): void;
-}
-
-export declare abstract class Bloc<S, // State type
-A extends object, // Base Action/Event type, constrained to object
-P = unknown> extends BlocBase<S, P> {
-    readonly eventHandlers: Map<new (...args: any[]) => A, (event: A, emit: (newState: S) => void) => void | Promise<void>>;
+export declare class PluginManager {
+    private plugins;
+    private registry;
     /**
-     * Registers an event handler for a specific event type.
-     * This method is typically called in the constructor of a derived Bloc class.
-     * @param eventConstructor The constructor of the event to handle (e.g., LoadDataEvent).
-     * @param handler A function that processes the event and can emit new states.
-     *                The 'event' parameter in the handler will be typed to the specific eventConstructor.
+     * Create a new PluginManager
+     * @param registry - The StateContainerRegistry to monitor for lifecycle events
      */
-    protected on<E extends A>(eventConstructor: new (...args: any[]) => E, handler: (event: E, emit: (newState: S) => void) => void | Promise<void>): void;
+    constructor(registry: StateContainerRegistry);
     /**
-     * Dispatches an action/event to the Bloc.
-     * If a handler is registered for this specific event type (via 'on'), it will be invoked.
-     * Asynchronous handlers are awaited.
-     * @param action The action/event instance to be processed.
+     * Install a plugin with optional configuration
+     * @param plugin - The plugin to install
+     * @param config - Optional plugin configuration
+     * @throws Error if plugin is already installed
      */
-    add: (action: A) => Promise<void>;
-}
-
-/**
- * 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)
- */
-export declare abstract class BlocBase<S, P = unknown> {
+    install(plugin: BlacPlugin, config?: PluginConfig): void;
     /**
-     * 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
+     * Uninstall a plugin by name
+     * @param pluginName - The name of the plugin to uninstall
+     * @throws Error if plugin is not installed
      */
-    static isolated: boolean;
-    get isIsolated(): boolean;
+    uninstall(pluginName: string): void;
     /**
-     * When true, the Bloc instance persists even when there are no active consumers.
-     * Useful for maintaining state between component unmount/remount cycles.
-     * @default false
+     * Get an installed plugin by name
+     * @param pluginName - The name of the plugin to retrieve
+     * @returns The plugin instance or undefined if not found
      */
-    static keepAlive: boolean;
-    get isKeepAlive(): boolean;
+    getPlugin(pluginName: string): BlacPlugin | undefined;
     /**
-     * Defines how dependencies are selected from the state for efficient updates.
-     * When provided, observers will only be notified when selected dependencies change.
+     * Get all installed plugins
+     * @returns Array of all installed plugins
      */
-    defaultDependencySelector: DependencySelector<S> | undefined;
-    /* Excluded from this release type: _addons */
-    /* Excluded from this release type: _isolated */
-    /* Excluded from this release type: _observer */
-    /* Excluded from this release type: _blac */
+    getAllPlugins(): BlacPlugin[];
     /**
-     * The unique identifier for this Bloc instance.
-     * Defaults to the class name, but can be customized.
+     * Check if a plugin is installed
+     * @param pluginName - The name of the plugin to check
+     * @returns true if the plugin is installed
      */
-    _id: BlocInstanceId;
-    /* Excluded from this release type: _instanceRef */
-    /* Excluded from this release type: _keepAlive */
+    hasPlugin(pluginName: string): boolean;
     /**
-     * @readonly
-     * Timestamp when this Bloc instance was created, useful for debugging and performance tracking.
+     * Uninstall all plugins
      */
-    readonly _createdAt: number;
-    /* Excluded from this release type: _state */
-    /* Excluded from this release type: _oldState */
+    clear(): void;
     /**
-     * Props passed during Bloc instance creation.
-     * Can be used to configure or parameterize the Bloc's behavior.
+     * Setup lifecycle hooks to notify plugins
      */
-    props: P | null;
+    private setupLifecycleHooks;
     /**
-     * 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
+     * Notify all plugins of a lifecycle event
      */
-    constructor(initialState: S);
+    private notifyPlugins;
+    /**
+     * Create plugin context with safe API access
+     */
+    private createPluginContext;
+    /**
+     * Check if plugin should be enabled based on environment
+     */
+    private shouldEnablePlugin;
     /**
-     * Returns the current state of the Bloc.
-     * Use this getter to access the state in a read-only manner.
-     */
-    get state(): S;
-    /* Excluded from this release type: _name */
-    /* Excluded from this release type: _updateId */
-    /* 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: _connectAddons */
-    lastUpdate: number;
-    /* Excluded from this release type: _pushState */
+     * Get current environment
+     */
+    private getCurrentEnvironment;
 }
 
-/**
- * Represents the abstract base types for Bloc and Cubit
- */
-export declare type BlocBaseAbstract = typeof Bloc<any, any, any> | typeof Cubit<any, any>;
+/* Excluded from this release type: ProxyState */
 
-/**
- * Represents a constructor type for a Bloc that takes no parameters
- * @template B - The type of the Bloc instance
- */
-export declare type BlocClassNoParams<B> = new (args: never[]) => B;
+export declare function release<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string, forceDispose?: boolean): void;
 
-/**
- * Represents a constructor type for a Bloc that can take any parameters
- * @template B - The type of the Bloc instance
- */
-export declare type BlocConstructor<B> = new (...args: any) => B;
-
-/**
- * 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;
-
-/**
- * Represents a function type for determining hook dependencies based on state changes
- * @template B - The BlocGeneric type
- */
-export declare type BlocHookDependencyArrayFn<S> = (newState: S, oldState: S) => unknown[][];
+/* Excluded from this release type: setActiveTracker */
 
-export declare type BlocInstanceId = string | number | undefined;
+/* Excluded from this release type: shallowEqual */
 
-/**
- * Extracts the state type from either a Bloc or Cubit
- * @template T - The Bloc or Cubit type to extract the state from
- */
-export declare type BlocState<T> = T extends BlocBase<infer S> ? S : never;
+/* Excluded from this release type: startDependency */
 
 /**
- * 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)
+ * Abstract base class for all state containers in BlaC.
+ * Provides lifecycle management, subscription handling, ref counting,
+ * and integration with the global registry.
+ *
+ * @template S - State type managed by this container
+ *
+ * @example
+ * ```ts
+ * class CounterBloc extends StateContainer<{ count: number }> {
+ *   constructor() {
+ *     super({ count: 0 });
+ *   }
+ *   increment() {
+ *     this.emit({ count: this.state.count + 1 });
+ *   }
+ * }
+ * ```
  */
-export declare abstract class Cubit<S, P = null> extends BlocBase<S, P> {
+export declare abstract class StateContainer<S extends object = any> {
+    static __excludeFromDevTools: boolean;
+    static enableStackTrace: boolean;
+    private _state;
+    private readonly listeners;
+    private _disposed;
+    private config;
+    private readonly systemEventHandlers;
+    /** Display name for this instance */
+    name: string;
+    /** Whether debug logging is enabled */
+    debug: boolean;
+    /** Unique identifier for this instance */
+    instanceId: string;
+    /** Timestamp when this instance was created */
+    createdAt: number;
+    constructor(initialState: 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),
-     * no update will occur.
-     * @param state - The new state to set
+     * Initialize configuration for this instance.
+     * Called by the registry after construction.
+     * @param config - Configuration options
      */
-    emit(state: S): void;
+    initConfig(config: StateContainerConfig): void;
+    /** Current state value */
+    get state(): Readonly<S>;
+    /** Whether this instance has been disposed */
+    get isDisposed(): boolean;
     /**
-     * Partially updates the current state by merging it with the provided state patch.
-     * This method is only applicable when the state is an object type.
-     *
-     * @param statePatch - A partial state object containing only the properties to update
-     * @param ignoreChangeCheck - If true, skips checking if the state has actually changed
-     * @throws {TypeError} If the state is not an object type
+     * Subscribe to state changes
+     * @param listener - Function called when state changes
+     * @returns Unsubscribe function
+     */
+    subscribe(listener: StateListener<S>): () => void;
+    /**
+     * Dispose this instance and clean up resources.
+     * Clears all listeners and emits the 'dispose' system event.
+     */
+    dispose(): void;
+    /**
+     * Emit a new state value and notify all listeners.
+     * @param newState - The new state value
+     * @protected
      */
-    patch(statePatch: S extends object ? Partial<S> : S, ignoreChangeCheck?: boolean): void;
+    protected emit(newState: S): void;
+    private captureStackTrace;
+    private formatStackLine;
+    private cleanFilePath;
+    /** Timestamp of the last state update */
+    lastUpdateTimestamp: number;
+    /**
+     * Update state using a transform function.
+     * @param updater - Function that receives current state and returns new state
+     * @protected
+     */
+    protected update(updater: (current: S) => S): void;
+    /**
+     * Subscribe to system lifecycle events.
+     * @param event - The event type to listen for
+     * @param handler - Handler function called when event occurs
+     * @returns Unsubscribe function
+     * @protected
+     */
+    protected onSystemEvent: <E extends SystemEvent>(event: E, handler: SystemEventHandler<S, E>) => (() => void);
+    private emitSystemEvent;
 }
 
-declare type DependencySelector<S> = (newState: S, oldState?: S) => unknown[][];
-
-export declare interface GetBlocOptions<B extends BlocBase<any>> {
-    id?: string;
-    dependencySelector?: BlocHookDependencyArrayFn<BlocState<B>>;
-    props?: InferPropsFromGeneric<B>;
-    onMount?: (bloc: B) => void;
-    instanceRef?: string;
+/**
+ * Configuration options for initializing a StateContainer instance
+ */
+export declare interface StateContainerConfig {
+    /** Display name for the instance (defaults to class name) */
+    name?: string;
+    /** Enable debug logging for this instance */
+    debug?: boolean;
+    /** Custom instance identifier */
+    instanceId?: string;
 }
 
 /**
- * Extracts the props type from either a Bloc or Cubit
- * @template T - The Bloc or Cubit type to extract the props from
+ * Constructor type for StateContainer classes
+ * @template S - State type managed by the container
  */
-export declare type InferPropsFromGeneric<T> = T extends Bloc<any, any, infer P> ? P : T extends Cubit<any, infer P> ? P : never;
+export declare type StateContainerConstructor<S extends object = any> = new (...args: any[]) => StateContainer<S>;
+
+export declare type StateContainerInstance<S extends object = any> = Omit<StateContainer<S>, 'state'> & {
+    state: Readonly<S>;
+};
 
 /**
- * Persist addon
+ * Central registry for managing StateContainer instances.
+ * Handles instance lifecycle, ref counting, and lifecycle event emission.
  *
- * @param options
- * @returns BlacAddon
+ * @example
+ * ```ts
+ * const registry = new StateContainerRegistry();
+ * const instance = registry.acquire(MyBloc);  // ownership, must release
+ * const other = registry.ensure(OtherBloc);   // no ownership, bloc-to-bloc
+ * registry.on('stateChanged', (container, prev, next) => {
+ *   console.log('State changed:', prev, '->', next);
+ * });
+ * ```
  */
-export declare function Persist(options?: {
+declare class StateContainerRegistry {
+    private readonly instancesByConstructor;
+    private readonly types;
+    private readonly typeConfigs;
+    private readonly listeners;
+    /**
+     * Register a type for lifecycle event tracking
+     * @param constructor - The StateContainer class constructor
+     */
+    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 StateContainerConstructor>(constructor: T, isolated?: boolean): void;
+    private ensureInstancesMap;
+    /**
+     * Get the instances Map for a specific class (public API for stats/debugging)
+     */
+    getInstancesMap<T extends StateContainerConstructor>(Type: T): Map<string, InstanceEntry>;
+    private trackExecutionContext;
+    /**
+     * Acquire an instance with ref counting (ownership semantics).
+     * Creates a new instance if one doesn't exist, or returns existing and increments ref count.
+     * You must call `release()` when done to decrement the ref count.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @param options - Acquisition options
+     * @param options.canCreate - Whether to create new instance if not found (default: true)
+     * @param options.countRef - Whether to increment ref count (default: true)
+     * @param options.trackExecutionContext - Whether to track cross-bloc dependency (default: false)
+     * @returns The state container instance
+     */
+    acquire<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string, options?: {
+        canCreate?: boolean;
+        countRef?: boolean;
+        trackExecutionContext?: boolean;
+    }): InstanceType<T>;
+    /**
+     * Borrow an existing instance without incrementing ref count (borrowing semantics).
+     * Tracks cross-bloc dependency for reactive updates.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns The state container instance
+     * @throws Error if instance doesn't exist
+     */
+    borrow<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
+    /**
+     * Safely borrow an existing instance (borrowing semantics with error handling).
+     * Returns discriminated union for type-safe conditional access.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns Discriminated union with either the instance or an error
+     */
+    borrowSafe<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): {
+        error: Error;
+        instance: null;
+    } | {
+        error: null;
+        instance: InstanceType<T>;
+    };
+    /**
+     * Ensure an instance exists without taking ownership (for bloc-to-bloc communication).
+     * Gets existing instance OR creates it if it doesn't exist, without incrementing ref count.
+     * Tracks cross-bloc dependency for reactive updates.
+     *
+     * 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 StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns The state container instance
+     */
+    ensure<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
+    /**
+     * Release a reference to an instance.
+     * Decrements ref count and disposes when it reaches 0 (unless keepAlive).
+     * @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 StateContainerConstructor>(Type: T, instanceKey?: string, forceDispose?: boolean): void;
     /**
-     * @default 'blac'
+     * Get all instances of a specific type.
+     * @param Type - The StateContainer class constructor
+     * @returns Array of all instances
      */
-    keyPrefix?: string;
+    getAll<T extends StateContainerConstructor>(Type: T): InstanceReadonlyState<T>[];
     /**
-     * @default the bloc's id
+     * 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
      */
-    keyName?: string;
+    forEach<T extends StateContainerConstructor>(Type: T, callback: (instance: InstanceReadonlyState<T>) => void): void;
     /**
-     * Used when the value is not found in storage
+     * Clear all instances of a specific type (disposes them).
+     * @param Type - The StateContainer class constructor
      */
-    defaultValue?: unknown;
+    clear<T extends StateContainerConstructor>(Type: T): void;
     /**
-     * @default 'localStorage'
-     * @see StorageType
+     * 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)
      */
-    storageType?: StorageType;
+    getRefCount<T extends StateContainerConstructor>(Type: T, instanceKey?: string): number;
     /**
-     * @default false
+     * Check if an instance exists.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns true if instance exists
      */
-    onError?: (e: unknown) => void;
-}): BlacAddon;
+    hasInstance<T extends StateContainerConstructor>(Type: T, instanceKey?: string): boolean;
+    /**
+     * Clear all instances from all types (for testing)
+     *
+     * Iterates all registered types and clears their instances.
+     * Also clears type tracking to reset the registry state.
+     */
+    clearAll(): void;
+    /**
+     * Get registry statistics for debugging.
+     * @returns Object with registeredTypes, totalInstances, and typeBreakdown
+     */
+    getStats(): {
+        registeredTypes: number;
+        totalInstances: number;
+        typeBreakdown: Record<string, number>;
+    };
+    /**
+     * Get all registered types (for plugin system).
+     * @returns Array of all registered StateContainer class constructors
+     */
+    getTypes(): StateContainerConstructor[];
+    /**
+     * Subscribe to lifecycle events
+     * @param event - The lifecycle event to listen for
+     * @param listener - The listener function to call when the event occurs
+     * @returns Unsubscribe function
+     */
+    on<E extends LifecycleEvent>(event: E, listener: LifecycleListener<E>): () => void;
+    /* Excluded from this release type: emit */
+}
+
+/* Excluded from this release type: StateListener */
+
+declare const STOP: unique symbol;
+
+declare type StopSymbol = typeof STOP;
 
-declare type StorageType = 'localStorage' | 'sessionStorage';
+/**
+ * System events emitted by StateContainer lifecycle
+ */
+export declare type SystemEvent = 'stateChanged' | 'dispose';
+
+/* Excluded from this release type: SystemEventHandler */
 
 /**
- * Extracts the state type from a BlocBase instance
- * @template B - The BlocBase type to extract the state from
+ * Payload types for each system event
+ * @template S - State type
  */
-export declare type ValueType<B extends BlocBase<any>> = B extends BlocBase<infer U> ? U : never;
+export declare interface SystemEventPayloads<S> {
+    /** Emitted when state changes via emit() or update() */
+    stateChanged: {
+        state: S;
+        previousState: S;
+    };
+    /** Emitted when the instance is disposed */
+    dispose: void;
+}
+
+export declare const watch: WatchFn;
+
+/**
+ * Combined watch function type.
+ */
+export declare interface WatchFn extends WatchSingleFn {
+    <T extends readonly BlocInput[]>(blocs: T, callback: (blocs: ExtractInstances<T>) => void | StopSymbol): () => void;
+}
+
+/**
+ * Watch function signature for single bloc.
+ */
+declare interface WatchSingleFn {
+    <T extends StateContainerConstructor>(bloc: T | BlocRef<T>, callback: (bloc: InstanceType<T>) => void | StopSymbol): () => void;
+    STOP: StopSymbol;
+}
 
 export { }