@blac/core 2.0.0 → 2.0.1

package/dist/index.d.ts

@@ -1,505 +1,1895 @@
+/* Excluded from this release type: __resetIdCounters */
+
+export declare function acquire<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string, options?: AcquireOptions<T>): InstanceType<T>;
+
+export declare interface AcquireOptions<T extends StateContainerConstructor> {
+    props?: ExtractProps<T>;
+}
+
+/**
+ * Internal state for framework adapters, holding tracking and caching data.
+ * @template TBloc - The state container type
+ */
+export declare interface AdapterState<TBloc extends StateContainerConstructor> {
+    /** Dependency tracker for state property access tracking */
+    dependencyState: DependencyState<ExtractState<TBloc>> | null;
+    /** Cached manual dependencies for comparison */
+    manualDepsCache: unknown[] | null;
+    /** Getter state for computed property tracking */
+    getterState: GetterState | null;
+    /** Proxied bloc instance for auto-tracking */
+    proxiedBloc: InstanceState<TBloc> | null;
+}
+
+/**
+ * Initialize adapter state for auto-tracking mode.
+ * Creates getter tracker and proxied bloc instance.
+ * @param instance - The state container instance
+ * @returns Initialized adapter state
+ */
+export declare function autoTrackInit<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
+
+/**
+ * Create a snapshot function for auto-tracking mode.
+ * Returns a proxied state that tracks property access.
+ * @param instance - The state container instance
+ * @param adapterState - The adapter state for tracking
+ * @returns Snapshot function for use with useSyncExternalStore
+ */
+export declare function autoTrackSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>, adapterState: AdapterState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+
+/**
+ * Create a subscribe function for auto-tracking mode.
+ * Only triggers callback when tracked properties change.
+ * @param instance - The state container instance
+ * @param adapterState - The adapter state for tracking
+ * @returns Subscribe function for use with useSyncExternalStore
+ */
+export declare function autoTrackSubscribe<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>, adapterState: AdapterState<TBloc>): SubscribeFunction;
+
+/**
+ * Decorator to configure StateContainer classes.
+ *
+ * @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> {}
+ * ```
+ *
+ * @example Function syntax (no decorator support needed)
+ * ```ts
+ * const FormBloc = blac({ isolated: true })(
+ *   class extends Cubit<FormState> {}
+ * );
+ * ```
+ */
+export declare function blac(options: BlacOptions): <T extends new (...args: any[]) => any>(target: T, _context?: ClassDecoratorContext) => T;
+
+/**
+ * Default configuration constants for BlaC
+ */
+export declare const BLAC_DEFAULTS: {
+    /**
+     * Default instance key for shared instances
+     */
+    readonly DEFAULT_INSTANCE_KEY: "default";
+    /**
+     * Maximum getter nesting depth (prevents infinite recursion)
+     */
+    readonly MAX_GETTER_DEPTH: 10;
+    /**
+     * Default cleanup interval for subscriptions (30 seconds)
+     */
+    readonly CLEANUP_INTERVAL_MS: 30000;
+    /**
+     * Cleanup interval for weak reference stage (10 seconds)
+     */
+    readonly WEAKREF_CLEANUP_INTERVAL_MS: 10000;
+    /**
+     * Default maximum subscriptions per container
+     */
+    readonly MAX_SUBSCRIPTIONS: 1000;
+    /**
+     * Maximum subscriptions for high-performance mode
+     */
+    readonly MAX_SUBSCRIPTIONS_HIGH_PERF: 10000;
+    /**
+     * Default timeout for pipeline execution (5 seconds)
+     */
+    readonly PIPELINE_TIMEOUT_MS: 5000;
+    /**
+     * Cleanup interval for high-performance mode (5 seconds)
+     */
+    readonly CLEANUP_INTERVAL_HIGH_PERF_MS: 5000;
+    /**
+     * Maximum number of stages in a pipeline
+     */
+    readonly MAX_PIPELINE_STAGES: 30;
+};
+
+/**
+ * Standard error message prefix
+ */
+export declare const BLAC_ERROR_PREFIX: "[BlaC]";
+
+/**
+ * ID generation patterns and constants
+ */
+export declare const BLAC_ID_PATTERNS: {
+    /**
+     * Prefix for isolated instance keys
+     */
+    readonly ISOLATED_PREFIX: "isolated-";
+    /**
+     * Length of generated ID portion (9 characters from base36)
+     */
+    readonly ID_LENGTH: 9;
+};
+
+/**
+ * Static property names for StateContainer classes
+ * Used for feature flags and configuration on bloc classes
+ */
+export declare const BLAC_STATIC_PROPS: {
+    /**
+     * Mark a bloc as isolated (each component gets its own instance)
+     */
+    readonly ISOLATED: "isolated";
+    /**
+     * Mark a bloc to never be auto-disposed (kept alive permanently)
+     */
+    readonly KEEP_ALIVE: "keepAlive";
+    /**
+     * Exclude a bloc from DevTools reporting (prevents infinite loops)
+     */
+    readonly EXCLUDE_FROM_DEVTOOLS: "__excludeFromDevTools";
+};
+
+/**
+ * Global configuration for @blac/core
+ */
+export declare interface BlacConfig {
+    /** Enable development mode (enables additional warnings and checks) */
+    devMode: boolean;
+    /** Logger configuration */
+    logger: Partial<LogConfig>;
+}
+
+/**
+ * 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;
+    /**
+     * Called when the plugin is installed (optional)
+     */
+    onInstall?(context: PluginContext): void;
+    /**
+     * Called when the plugin is uninstalled
+     */
+    onUninstall?(): void;
+    /**
+     * Called when a state container instance is created
+     */
+    onInstanceCreated?(instance: StateContainer<any>, context: PluginContext): void;
+    /**
+     * Called when state changes in a container instance
+     */
+    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
+     */
+    onEventAdded?<E extends DiscriminatedEvent>(vertex: Vertex<any, E>, event: EventWithMetadata<E>, context: PluginContext): void;
+    /**
+     * Called when a state container instance is disposed
+     */
+    onInstanceDisposed?(instance: StateContainer<any>, context: PluginContext): void;
+}
+
+/**
+ * Plugin interface variant that requires mandatory onInstall hook
+ */
+export declare interface BlacPluginWithInit extends BlacPlugin {
+    /**
+     * Required initialization hook called when plugin is installed
+     */
+    onInstall(context: PluginContext): void;
+}
+
+declare const BLOC_REF_MARKER: unique symbol;
+
+/**
+ * Constructor type for StateContainer classes with static registry methods.
+ * Used for type-safe hook parameters.
+ * @template TBloc - The StateContainer instance type
+ */
+export declare type BlocConstructor<S extends object = any, T extends new (...args: any[]) => StateContainer<S, any> = new (...args: any[]) => StateContainer<S, any>> = (new (...args: any[]) => InstanceType<T>) & {
+    acquire(instanceKey?: string, ...args: any[]): InstanceType<T>;
+    borrow(instanceKey?: string, ...args: any[]): InstanceType<T> | null;
+    borrowSafe(instanceKey?: string, ...args: any[]): {
+        error: Error;
+        instance: null;
+    } | {
+        error: null;
+        instance: InstanceType<T>;
+    };
+    ensure(instanceKey?: string): InstanceType<T>;
+    release(instanceKey?: string): void;
+    isolated?: boolean;
+    keepAlive?: boolean;
+};
+
+declare type BlocInput = StateContainerConstructor | BlocRef<StateContainerConstructor>;
+
+/**
+ * Extract instance type from an abstract class constructor
+ * @template T - The abstract class constructor type
+ */
+export declare type BlocInstanceType<T extends abstract new (...args: any) => any> = T extends abstract new (...args: any) => infer R ? R : any;
+
+/**
+ * Reference to a specific bloc instance by class and instance ID.
+ */
+export declare interface BlocRef<T extends StateContainerConstructor> {
+    [BLOC_REF_MARKER]: true;
+    blocClass: T;
+    instanceId: string;
+}
+
+export declare function borrow<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): InstanceType<T>;
+
+export declare function borrowSafe<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): {
+    error: Error;
+    instance: null;
+} | {
+    error: null;
+    instance: InstanceType<T>;
+};
+
+/**
+ * Utility type for creating branded/nominal types.
+ * Prevents accidental type confusion between similar primitive types.
+ * @template T - The base type
+ * @template B - The brand identifier
+ */
+export declare type Brand<T, B> = T & {
+    [brand]: B;
+};
+
+declare const brand: unique symbol;
+
+/**
+ * Branded string type for type-safe IDs.
+ * @template B - The brand identifier
+ */
+export declare type BrandedId<B> = Brand<string, B>;
+
+/* 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 */
+
+/**
+ * Configure global defaults for @blac/core.
+ *
+ * @example
+ * ```ts
+ * import { configureBlac, LogLevel } from '@blac/core';
+ *
+ * configureBlac({
+ *   devMode: true,
+ *   logger: {
+ *     enabled: true,
+ *     level: LogLevel.DEBUG
+ *   }
+ * });
+ * ```
+ *
+ * @param config - Partial configuration to merge with defaults
+ */
+export declare function configureBlac(config: Partial<BlacConfig>): void;
+
+/**
+ * Configuration function that recreates the default logger
+ *
+ * @param opts - Partial logger configuration
+ *
+ * @example
+ * ```ts
+ * configureLogger({ enabled: true, level: LogLevel.DEBUG });
+ * ```
+ */
+export declare function configureLogger(opts: Partial<LogConfig>): void;
+
+/* Excluded from this release type: createArrayProxy */
+
+/* Excluded from this release type: createBlocProxy */
+
+/* Excluded from this release type: createDependencyProxy */
+
+/* Excluded from this release type: createDependencyState */
+
+/* Excluded from this release type: createForTarget */
+
+/* Excluded from this release type: createGetterState */
+
+/**
+ * Centralized ID Generation
+ *
+ * Provides consistent, collision-resistant ID generation for all BlaC subsystems.
+ * Uses timestamp + counter + random suffix for uniqueness.
+ */
+/**
+ * Creates an ID generator with isolated counter state
+ *
+ * @param prefix - Prefix for generated IDs
+ * @returns Object with next(), nextSimple(), and reset() methods
+ *
+ * @example
+ * ```ts
+ * const generator = createIdGenerator('sub');
+ * const id1 = generator.next(); // "sub:1698765432100_1_a3k9d7f2q"
+ * const id2 = generator.next(); // "sub:1698765432101_2_b4n8e9g3r"
+ * ```
+ */
+export declare function createIdGenerator(prefix: string): {
+    next: () => string;
+    nextSimple: () => string;
+    reset: () => void;
+};
+
+/* Excluded from this release type: createInternal */
+
+/**
+ * Creates a logger instance with given configuration
+ *
+ * @param config - Logger configuration
+ * @returns Logger instance with debug, info, warn, error, and configure methods
+ *
+ * @example
+ * ```ts
+ * const logger = createLogger({
+ *   enabled: true,
+ *   level: LogLevel.DEBUG,
+ *   output: (entry) => console.log(JSON.stringify(entry))
+ * });
+ * logger.debug('MyComponent', 'Rendering', { props: { foo: 'bar' } });
+ * ```
+ */
+export declare function createLogger(config: LogConfig): {
+    debug: (context: string, message: string, data?: any) => void;
+    info: (context: string, message: string, data?: any) => void;
+    warn: (context: string, message: string, data?: any) => void;
+    error: (context: string, message: string, data?: any) => void;
+    configure: (opts: Partial<LogConfig>) => void;
+};
+
+/**
+ * Create a plugin manager instance
+ * @param registry - The StateContainerRegistry to monitor for lifecycle events
+ * @returns A new PluginManager instance
+ */
+export declare function createPluginManager(registry: StateContainerRegistry): PluginManager;
+
+/* Excluded from this release type: createProxyState */
+
+/**
+ * Create a new tracked context for manual control over tracking.
+ */
+export declare function createTrackedContext(): TrackedContext;
+
+/**
+ * Create a tracking proxy for a bloc instance.
+ * Tracks both state property access and getter access.
+ */
+export declare function createTrackingProxy<T extends StateContainerInstance>(bloc: T, tracker: TrackingProxyState): T;
+
+/**
+ * Create a new tracking proxy state.
+ */
+export declare function createTrackingProxyState(): TrackingProxyState;
+
+/**
+ * Simple state container with direct state emission.
+ * Extends StateContainer with public methods for emitting and updating state.
+ *
+ * @template S - State type
+ * @template P - Props type (optional)
+ */
+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
+     * @param newState - The new state value
+     */
+    emit(newState: S): void;
+    /**
+     * Transform current state using an updater function and emit the new state
+     * @param updater - Function that receives current state and returns new state
+     */
+    update(updater: (current: S) => S): void;
+    /**
+     * Merge partial state changes into current state (only for object states)
+     */
+    patch: S extends object ? (partial: Partial<S>) => void : never;
+}
+
+/**
+ * Log a debug message (tree-shakeable export)
+ * @param context - Context identifier (module or component name)
+ * @param message - Log message
+ * @param data - Optional structured data
+ */
+export declare const debug: (context: string, message: string, data?: any) => void;
+
+/**
+ * Manages subscriptions to state container dependencies.
+ * Provides efficient sync mechanism to add/remove subscriptions
+ * as dependencies change between callback invocations.
+ */
+export declare class DependencyManager {
+    private subscriptions;
+    private currentDeps;
+    /**
+     * Sync subscriptions with a new set of dependencies.
+     * Adds subscriptions for new deps, removes subscriptions for stale deps.
+     *
+     * @param newDeps - The new set of dependencies to subscribe to
+     * @param onChange - Callback to invoke when any dependency changes
+     * @param exclude - Optional instance to exclude from subscriptions (e.g., primary bloc)
+     * @returns true if the dependency set changed, false if unchanged
+     */
+    sync(newDeps: Set<StateContainerInstance>, onChange: () => void, exclude?: StateContainerInstance): boolean;
+    /**
+     * Add a single dependency subscription.
+     */
+    add(dep: StateContainerInstance, onChange: () => void): void;
+    /**
+     * Check if a dependency is currently subscribed.
+     */
+    has(dep: StateContainerInstance): boolean;
+    /**
+     * Get the current set of dependencies.
+     */
+    getDependencies(): Set<StateContainerInstance>;
+    /**
+     * Clean up all active subscriptions.
+     */
+    cleanup(): void;
+    private areSetsEqual;
+}
+
+/* Excluded from this release type: DependencyState */
+
+/**
+ * Disable getter tracking after render phase completes.
+ * Clears the active tracker to prevent tracking outside of render.
+ * @param adapterState - The adapter state
+ * @param rawInstance - The raw bloc instance
+ */
+export declare function disableGetterTracking<TBloc extends StateContainerConstructor>(adapterState: AdapterState<TBloc>, rawInstance: InstanceState<TBloc>): void;
+
+/**
+ * Base type for discriminated union events.
+ * All events must have a `type` property as the discriminator.
+ *
+ * @example
+ * ```typescript
+ * type MyEvent =
+ *   | { type: 'increment'; amount: number }
+ *   | { type: 'decrement' };
+ * ```
+ */
+export declare interface DiscriminatedEvent {
+    readonly type: string;
+}
+
+/* Excluded from this release type: EmptyState */
+
+/* Excluded from this release type: EmptyState_2 */
+
+export declare function ensure<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): InstanceType<T>;
+
+/**
+ * Log an error message (tree-shakeable export)
+ * @param context - Context identifier (module or component name)
+ * @param message - Log message
+ * @param data - Optional structured data
+ */
+export declare const error: (context: string, message: string, data?: any) => void;
+
+/**
+ * Map of event handlers requiring exhaustive coverage.
+ * TypeScript enforces that every event type in the union has a handler.
+ *
+ * @template E - The discriminated event union type
+ * @template S - The state type
+ *
+ * @example
+ * ```typescript
+ * type CounterEvent =
+ *   | { type: 'increment'; amount: number }
+ *   | { type: 'reset' };
+ *
+ * // All event types must be handled:
+ * const handlers: EventHandlerMap<CounterEvent, { count: number }> = {
+ *   increment: (event, emit) => emit({ count: event.amount }),
+ *   reset: (_, emit) => emit({ count: 0 }),
+ * };
+ * ```
+ */
+export declare type EventHandlerMap<E extends DiscriminatedEvent, S extends object> = {
+    [K in EventType<E>]: VertexEventHandler<ExtractEvent<E, K>, S>;
+};
+
+/* Excluded from this release type: EventMetadata */
+
+/**
+ * Extract the `type` literal union from a discriminated event union.
+ *
+ * @template E - The discriminated event union type
+ *
+ * @example
+ * ```typescript
+ * type MyEvent = { type: 'a' } | { type: 'b' };
+ * type Types = EventType<MyEvent>; // 'a' | 'b'
+ * ```
+ */
+export declare type EventType<E extends DiscriminatedEvent> = E['type'];
+
+/* Excluded from this release type: EventWithMetadata */
+
+/**
+ * Manages subscriptions to external bloc dependencies for getter tracking.
+ * When a getter accesses another bloc's state, this manager ensures
+ * re-renders occur when those external dependencies change.
+ *
+ * @deprecated Use DependencyManager from tracking module instead.
+ * This class is kept for backward compatibility.
+ */
+export declare class ExternalDepsManager {
+    private manager;
+    /**
+     * Update subscriptions to external bloc dependencies.
+     * Creates subscriptions to blocs accessed via getters.
+     * @param getterTracker - The getter tracker state with external dependencies
+     * @param rawInstance - The primary bloc instance (excluded from subscriptions)
+     * @param onGetterChange - Callback to invoke when external dependency changes
+     * @returns true if subscriptions were updated, false if unchanged
+     */
+    updateSubscriptions(getterState: GetterState | null, rawInstance: StateContainerInstance, onGetterChange: () => void): boolean;
+    /**
+     * Clean up all active subscriptions
+     */
+    cleanup(): void;
+}
+
+/**
+ * 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[];
+
+/**
+ * Extract a specific event variant from a union by its type.
+ *
+ * @template E - The discriminated event union type
+ * @template T - The type literal to extract
+ *
+ * @example
+ * ```typescript
+ * type MyEvent = { type: 'a'; value: number } | { type: 'b' };
+ * type EventA = ExtractEvent<MyEvent, 'a'>; // { type: 'a'; value: number }
+ * ```
+ */
+export declare type ExtractEvent<E extends DiscriminatedEvent, T extends EventType<E>> = Extract<E, {
+    type: T;
+}>;
+
+declare type ExtractInstance<T> = T extends BlocRef<infer C> ? InstanceType<C> : T extends StateContainerConstructor ? InstanceType<T> : never;
+
+declare type ExtractInstances<T extends readonly BlocInput[]> = {
+    [K in keyof T]: ExtractInstance<T[K]>;
+};
+
+/**
+ * Extract the props type from a StateContainer
+ * @template T - The StateContainer type
+ */
+export declare type ExtractProps<T> = T extends StateContainerConstructor<any, infer P> ? P : undefined;
+
+/**
+ * Extract the state type from a StateContainer
+ * @template T - The StateContainer type
+ */
+export declare type ExtractState<T> = T extends StateContainerConstructor<infer S, any> ? Readonly<S> : never;
+
+/**
+ * Constrain a type to extract state only from stateful containers.
+ * Returns `never` for stateless containers.
+ */
+export declare type ExtractStatefulState<T extends StateContainerConstructor> = IsStatelessContainer<T> extends true ? never : ExtractState<T>;
+
+export declare type ExtractStateMutable<T> = T extends StateContainerConstructor<infer S, any> ? S : never;
+
+export declare function forEach<T extends StateContainerConstructor>(BlocClass: T, callback: (instance: InstanceReadonlyState<T>) => void): void;
+
+/**
+ * Generate ID with timestamp, counter, and random suffix (tree-shakeable)
+ *
+ * Format: `${prefix}:${timestamp}_${counter}_${random}`
+ *
+ * @param prefix - Prefix for the ID (e.g., 'sub', 'consumer', 'stage')
+ * @returns Branded ID string
+ *
+ * @example
+ * const id = generateId('sub');
+ * // Returns: "sub:1698765432100_1_a3k9d7f2q"
+ */
+export declare function generateId(prefix: string): string;
+
+/**
+ * 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 function generateIsolatedKey(): string;
+
+/**
+ * Generate simple ID with timestamp and random (no counter tracking)
+ *
+ * Format: `${prefix}:${timestamp}_${random}`
+ *
+ * @param prefix - Prefix for the ID
+ * @returns Branded ID string
+ *
+ * @example
+ * ```ts
+ * const id = generateSimpleId('CounterBloc');
+ * // Returns: "CounterBloc:1698765432100_a3k9d7f2q"
+ * ```
+ */
+export declare function generateSimpleId(prefix: string, affix?: string): string;
+
+/* Excluded from this release type: getActiveTracker */
+
+export declare function getAll<T extends StateContainerConstructor>(BlocClass: T): InstanceReadonlyState<T>[];
+
+/* Excluded from this release type: getBlacConfig */
+
+/* Excluded from this release type: getDescriptor */
+
+/* Excluded from this release type: getGetterExecutionContext */
+
+/**
+ * Get the global plugin manager
+ */
+export declare function getPluginManager(): any;
+
+export declare function getRefCount<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): number;
+
+export declare function getRegistry(): StateContainerRegistry;
+
+/**
+ * Get a static property from a class constructor
+ * Type-safe helper that avoids (Type as any) casts
+ *
+ * @param Type - The class constructor
+ * @param propName - The property name to access
+ * @param defaultValue - Optional default value if property is undefined
+ * @returns The property value or default
+ */
+export declare function getStaticProp<V, T extends StateContainerConstructor = StateContainerConstructor>(Type: T, propName: string, defaultValue?: V): V | undefined;
+
+export declare function getStats(): {
+    registeredTypes: number;
+    totalInstances: number;
+    typeBreakdown: Record<string, number>;
+};
+
+declare interface GetterExecutionContext {
+    tracker: GetterState | null;
+    currentBloc: StateContainerInstance | null;
+    depth: number;
+    visitedBlocs: Set<StateContainerInstance>;
+}
+
+/* Excluded from this release type: GetterState */
+
+/* Excluded from this release type: getValueAtPath */
+
+/**
+ * Global default registry instance
+ */
+export declare const globalRegistry: StateContainerRegistry;
+
+/* Excluded from this release type: hasDependencyChanges */
+
+/* Excluded from this release type: hasGetterChanges */
+
+/**
+ * Type guard to check if a plugin has a required onInstall hook
+ * @param plugin - The plugin to check
+ * @returns true if the plugin implements BlacPluginWithInit
+ */
+export declare function hasInitHook(plugin: BlacPlugin): plugin is BlacPluginWithInit;
+
+export declare function hasInstance<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): boolean;
+
+/* Excluded from this release type: hasTrackedData */
+
+/**
+ * Check if tracked state or getters have changed.
+ */
+export declare function hasTrackingProxyChanges(tracker: TrackingProxyState, bloc: StateContainerInstance): boolean;
+
+/**
+ * Log an info message (tree-shakeable export)
+ * @param context - Context identifier (module or component name)
+ * @param message - Log message
+ * @param data - Optional structured data
+ */
+export declare const info: (context: string, message: string, data?: any) => void;
+
+/**
+ * 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;
+}
+
+/**
+ * Branded string type for state container instance IDs
+ */
+export declare type InstanceId = Brand<string, 'InstanceId'>;
+
 /**
- * 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.
- *
- * Key responsibilities:
- * - Managing bloc instances (creation, disposal, lookup)
- * - Handling isolated and non-isolated blocs
- * - Managing plugins and lifecycle events
- * - Providing logging and debugging capabilities
+ * Metadata information about a state container instance for debugging and inspection
  */
-export declare class Blac {
-    /** The singleton instance of Blac */
-    static instance: Blac;
-    /** Timestamp when the instance was created */
+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;
-    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;
+    /** 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 */
+
+/**
+ * Check if development mode is enabled.
+ */
+export declare function isDevMode(): boolean;
+
+/**
+ * Check if a class should be excluded from DevTools.
+ * Used to prevent infinite loops when DevTools tracks itself.
+ * @param Type - The class constructor to check
+ * @returns true if the class has `static __excludeFromDevTools = true`
+ */
+export declare function isExcludedFromDevTools<T extends StateContainerConstructor>(Type: T): boolean;
+
+/* Excluded from this release type: isGetter */
+
+/**
+ * Check if a class is marked as isolated.
+ * Isolated classes create separate instances per component.
+ * @param Type - The class constructor to check
+ * @returns true if the class has `static isolated = true`
+ */
+export declare function isIsolatedClass<T extends StateContainerConstructor>(Type: T): boolean;
+
+/**
+ * Check if a key is an isolated instance key
+ * @param key - The instance key to check
+ * @returns true if the key is an isolated instance key
+ */
+export declare function isIsolatedKey(key: string): boolean;
+
+/**
+ * Check if a class is marked as keepAlive.
+ * KeepAlive classes are never auto-disposed when ref count reaches 0.
+ * @param Type - The class constructor to check
+ * @returns true if the class has `static keepAlive = true`
+ */
+export declare function isKeepAliveClass<T extends StateContainerConstructor>(Type: T): boolean;
+
+/* Excluded from this release type: isProxyable */
+
+/**
+ * Check if a class is a stateless container (StatelessCubit or StatelessVertex).
+ * Stateless containers don't have state, emit, update, or subscribe methods.
+ * @param Type - The class constructor to check
+ * @returns true if the class is a stateless container
+ */
+export declare function isStatelessClass<T extends StateContainerConstructor>(Type: T): boolean;
+
+/**
+ * Check if a StateContainer constructor is a stateless container.
+ * Returns true for StatelessCubit and StatelessVertex classes.
+ */
+export declare type IsStatelessContainer<T> = T extends {
+    readonly [STATELESS_MARKER]: true;
+} ? true : false;
+
+/**
+ * Lifecycle events emitted by the registry
+ */
+export declare type LifecycleEvent = 'created' | 'stateChanged' | 'eventAdded' | '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 'eventAdded' ? (container: Vertex<any, any>, event: any) => void : E extends 'disposed' ? (container: StateContainer<any>) => void : never;
+
+/**
+ * Configuration for the logger
+ */
+export declare interface LogConfig {
+    /** Whether logging is enabled */
+    enabled: boolean;
+    /** Minimum log level to output */
+    level: LogLevel;
+    /** Function called to output log entries */
+    output: (entry: LogEntry) => void;
+}
+
+/**
+ * Structure of a log entry passed to output handlers
+ */
+export declare interface LogEntry {
+    /** Log level as string (DEBUG, INFO, WARN, ERROR) */
+    level: string;
+    /** Context identifier (typically component or module name) */
+    context: string;
+    /** Log message */
+    message: string;
+    /** Optional structured data */
+    data?: any;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+}
+
+/**
+ * Log severity levels (lower number = higher severity)
+ */
+export declare enum LogLevel {
+    /** Critical errors that may cause application failure */
+    ERROR = 0,
+    /** Warning conditions that should be addressed */
+    WARN = 1,
+    /** Informational messages about application state */
+    INFO = 2,
+    /** Detailed debugging information */
+    DEBUG = 3
+}
+
+/**
+ * Configuration for manual dependency tracking mode
+ * @template TBloc - The state container type
+ */
+export declare interface ManualDepsConfig<TBloc extends StateContainerConstructor> {
+    /** Function that returns dependency array from state and bloc */
+    dependencies: (state: ExtractState<TBloc>, bloc: InstanceState<TBloc>) => any[];
+}
+
+/**
+ * Initialize adapter state for manual dependency tracking mode.
+ * No proxy is created; bloc is used directly.
+ * @param instance - The state container instance
+ * @returns Initialized adapter state
+ */
+export declare function manualDepsInit<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
+
+/**
+ * Create a snapshot function for manual dependency tracking mode.
+ * Caches dependencies for comparison on next render.
+ * @param instance - The state container instance
+ * @param adapterState - The adapter state for caching
+ * @param config - Configuration with dependencies function
+ * @returns Snapshot function for use with useSyncExternalStore
+ */
+export declare function manualDepsSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+
+/**
+ * Create a subscribe function for manual dependency tracking mode.
+ * Only triggers callback when dependencies array changes.
+ * @param instance - The state container instance
+ * @param adapterState - The adapter state for caching
+ * @param config - Configuration with dependencies function
+ * @returns Subscribe function for use with useSyncExternalStore
+ */
+export declare function manualDepsSubscribe<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SubscribeFunction;
+
+/**
+ * Initialize adapter state for no-tracking mode.
+ * No tracking or proxy is created.
+ * @param instance - The state container instance
+ * @returns Initialized adapter state
+ */
+export declare function noTrackInit<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
+
+/**
+ * Create a snapshot function for no-tracking mode.
+ * Returns the raw state directly.
+ * @param instance - The state container instance
+ * @returns Snapshot function for use with useSyncExternalStore
+ */
+export declare function noTrackSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+
+/**
+ * Create a subscribe function for no-tracking mode.
+ * Triggers callback on every state change.
+ * @param instance - The state container instance
+ * @returns Subscribe function for use with useSyncExternalStore
+ */
+export declare function noTrackSubscribe<TBloc extends StateContainerInstance>(instance: TBloc): SubscribeFunction;
+
+/* Excluded from this release type: parsePath */
+
+/* Excluded from this release type: PathInfo */
+
+/**
+ * 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 {
     /**
-     * Logs messages to console when logging is enabled
-     * @param args - Arguments to log
+     * Get metadata for a specific instance
      */
-    log: (...args: unknown[]) => void;
-    static log: (...args: unknown[]) => void;
+    getInstanceMetadata(instance: StateContainer<any>): InstanceMetadata;
     /**
-     * Gets the singleton instance of Blac
-     * @returns The Blac instance
+     * Get current state from a container
      */
-    static getInstance(): Blac;
+    getState<S extends object = any>(instance: StateContainer<S>): S;
     /**
-     * Logs a warning message
-     * @param message - Warning message
-     * @param args - Additional arguments
+     * Get all instances of a specific type
      */
-    warn: (message: string, ...args: unknown[]) => void;
-    static warn: (message: string, ...args: unknown[]) => void;
+    queryInstances<T extends StateContainer<any>>(typeClass: new (...args: any[]) => T): T[];
     /**
-     * Logs an error message
-     * @param message - Error message
-     * @param args - Additional arguments
+     * Get all registered state container types
      */
-    error: (message: string, ...args: unknown[]) => void;
-    static error: (message: string, ...args: unknown[]) => void;
+    getAllTypes(): Array<new (...args: any[]) => StateContainer<any>>;
     /**
-     * Resets the Blac instance to a new one, disposing non-keepAlive blocs
-     * from the old instance.
+     * Get registry statistics
      */
-    resetInstance: () => void;
-    static resetInstance: () => void;
+    getStats(): {
+        registeredTypes: number;
+        totalInstances: number;
+        typeBreakdown: Record<string, number>;
+    };
+}
+
+/**
+ * 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 class PluginManager {
+    private plugins;
+    private registry;
     /**
-     * Adds a plugin to the Blac instance
-     * @param plugin - The plugin to add
+     * Create a new PluginManager
+     * @param registry - The StateContainerRegistry to monitor for lifecycle events
      */
-    addPlugin: (plugin: BlacPlugin) => void;
+    constructor(registry: StateContainerRegistry);
     /**
-     * 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
+     * Install a plugin with optional configuration
+     * @param plugin - The plugin to install
+     * @param config - Optional plugin configuration
+     * @throws Error if plugin is already installed
      */
-    dispatchEventToPlugins: (event: BlacLifecycleEvent, bloc: BlocBase<any>, params?: unknown) => void;
+    install(plugin: BlacPlugin, config?: PluginConfig): 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
+     * Uninstall a plugin by name
+     * @param pluginName - The name of the plugin to uninstall
+     * @throws Error if plugin is not installed
      */
-    dispatchEvent: (event: BlacLifecycleEvent, bloc: BlocBase<any>, params?: unknown) => void;
+    uninstall(pluginName: string): void;
     /**
-     * Disposes of a bloc instance by removing it from the appropriate registry
-     * @param bloc - The bloc instance to dispose
+     * Get an installed plugin by name
+     * @param pluginName - The name of the plugin to retrieve
+     * @returns The plugin instance or undefined if not found
      */
-    disposeBloc: (bloc: BlocBase<any>) => void;
+    getPlugin(pluginName: string): BlacPlugin | undefined;
     /**
-     * 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"
+     * Get all installed plugins
+     * @returns Array of all installed plugins
      */
-    createBlocInstanceMapKey(blocClassName: string, id: BlocInstanceId): string;
+    getAllPlugins(): BlacPlugin[];
     /**
-     * Unregister a bloc instance from the main registry
-     * @param bloc - The bloc instance to unregister
+     * Check if a plugin is installed
+     * @param pluginName - The name of the plugin to check
+     * @returns true if the plugin is installed
      */
-    unregisterBlocInstance(bloc: BlocBase<any>): void;
+    hasPlugin(pluginName: string): boolean;
     /**
-     * Registers a bloc instance in the main registry
-     * @param bloc - The bloc instance to register
+     * Uninstall all plugins
      */
-    registerBlocInstance(bloc: BlocBase<any>): void;
+    clear(): void;
     /**
-     * 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
+     * Setup lifecycle hooks to notify plugins
      */
-    findRegisteredBlocInstance<B extends BlocConstructor<unknown>>(blocClass: B, id: BlocInstanceId): InstanceType<B> | undefined;
+    private setupLifecycleHooks;
     /**
-     * Registers an isolated bloc instance in the isolated registry
-     * @param bloc - The isolated bloc instance to register
+     * Notify all plugins of a lifecycle event
      */
-    registerIsolatedBlocInstance(bloc: BlocBase<any>): void;
+    private notifyPlugins;
     /**
-     * Unregister an isolated bloc instance from the isolated registry
-     * @param bloc - The isolated bloc instance to unregister
+     * Create plugin context with safe API access
      */
-    unregisterIsolatedBlocInstance(bloc: BlocBase<any>): void;
+    private createPluginContext;
     /**
-     * Finds an isolated bloc instance by its class and ID
+     * Check if plugin should be enabled based on environment
      */
-    findIsolatedBlocInstance<B extends BlocConstructor<unknown>>(blocClass: B, id: BlocInstanceId): InstanceType<B> | undefined;
+    private shouldEnablePlugin;
     /**
-     * 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
+     * Get current environment
      */
-    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>[];
-}
-
-declare type BlacAddon = {
-    name: string;
-    onInit?: BlacAddonInit;
-    onEmit?: BlacAddonEmit;
-};
+    private getCurrentEnvironment;
+}
+
+/* Excluded from this release type: ProxyState */
+
+export declare function register<T extends StateContainerConstructor>(BlocClass: T, isolated?: boolean): void;
 
-declare type BlacAddonEmit = (params: {
-    oldState: unknown;
-    newState: unknown;
-    cubit: BlocBase<any>;
-}) => void;
+export declare function release<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string, forceDispose?: boolean): void;
 
-declare type BlacAddonInit = (bloc: BlocBase<any>) => void;
+/* Excluded from this release type: resetBlacConfig */
+
+/* Excluded from this release type: resetGetterState */
+
+/* Excluded from this release type: setActiveTracker */
+
+export declare function setRegistry(registry: StateContainerRegistry): void;
+
+/* Excluded from this release type: shallowEqual */
 
 /**
- * Configuration options for the Blac instance
+ * Function that returns a snapshot of the current state
+ * @template TState - The state type
  */
-export declare interface BlacConfig {
-    /** Whether to expose the Blac instance globally */
-    exposeBlacInstance?: boolean;
-}
+export declare type SnapshotFunction<TState> = () => TState;
+
+/* Excluded from this release type: startDependency */
+
+/* Excluded from this release type: startProxy */
 
 /**
- * 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.
+ * Start tracking on a tracking proxy.
  */
-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 function startTrackingProxy(tracker: TrackingProxyState): void;
 
 /**
- * A class that manages observers for a Bloc's state changes
- * @template S - The type of state being observed
+ * 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
+ * @template P - Props type passed to the container (optional)
+ *
+ * @example
+ * ```ts
+ * class CounterBloc extends StateContainer<{ count: number }> {
+ *   constructor() {
+ *     super({ count: 0 });
+ *   }
+ *   increment() {
+ *     this.emit({ count: this.state.count + 1 });
+ *   }
+ * }
+ * ```
  */
-export declare class BlacObservable<S = unknown> {
-    /** The Bloc instance this observable is associated with */
-    bloc: BlocBase<S>;
+export declare abstract class StateContainer<S extends object = any, P = any> {
+    static __excludeFromDevTools: boolean;
+    static enableStackTrace: boolean;
+    private _state;
+    private readonly listeners;
+    private _disposed;
+    private config;
+    private _props;
+    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;
+    /** Current props value passed to this container */
+    get props(): P | undefined;
+    constructor(initialState: S);
     /**
-     * Creates a new BlacObservable instance
-     * @param bloc - The Bloc instance to observe
+     * Initialize configuration for this instance.
+     * Called by the registry after construction.
+     * @param config - Configuration options
      */
-    constructor(bloc: BlocBase<S>);
-    private _observers;
+    initConfig(config: StateContainerConfig): void;
+    /** Current state value */
+    get state(): Readonly<S>;
+    /** Whether this instance has been disposed */
+    get isDisposed(): boolean;
     /**
-     * Gets the number of active observers
-     * @returns The number of observers currently subscribed
+     * Subscribe to state changes
+     * @param listener - Function called when state changes
+     * @returns Unsubscribe function
      */
-    get size(): number;
+    subscribe(listener: StateListener<S>): () => void;
     /**
-     * Gets the set of all observers
-     * @returns The Set of all BlacObserver instances
+     * Dispose this instance and clean up resources.
+     * Clears all listeners and emits the 'dispose' system event.
      */
-    get observers(): Set<BlacObserver<S>>;
+    dispose(): void;
     /**
-     * Subscribes an observer to state changes
-     * @param observer - The observer to subscribe
-     * @returns A function that can be called to unsubscribe the observer
+     * Emit a new state value and notify all listeners.
+     * @param newState - The new state value
+     * @protected
      */
-    subscribe(observer: BlacObserver<S>): () => void;
+    protected emit(newState: S): void;
+    private captureStackTrace;
+    private formatStackLine;
+    private cleanFilePath;
+    /** Timestamp of the last state update */
+    lastUpdateTimestamp: number;
     /**
-     * Unsubscribes an observer from state changes
-     * @param observer - The observer to unsubscribe
+     * Update state using a transform function.
+     * @param updater - Function that receives current state and returns new state
+     * @protected
      */
-    unsubscribe(observer: BlacObserver<S>): void;
+    protected update(updater: (current: S) => 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
+     * 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
      */
-    notify(newState: S, oldState: S, action?: unknown): void;
+    protected onSystemEvent: <E extends SystemEvent>(event: E, handler: SystemEventHandler<S, P, E>) => (() => void);
+    private emitSystemEvent;
     /**
-     * Disposes of all observers and clears the observer set
+     * Update the props for this container.
+     * Emits the 'propsUpdated' system event.
+     * @param newProps - The new props value
      */
-    dispose(): void;
+    updateProps(newProps: P): void;
 }
 
 /**
- * Represents an observer that can subscribe to state changes in a Bloc
- * @template S - The type of state being observed
+ * Configuration options for initializing a StateContainer instance
  */
-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 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;
 }
 
-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>>;
+/**
+ * Constructor type for StateContainer classes
+ * @template S - State type managed by the container
+ * @template P - Props type passed to the container
+ */
+export declare type StateContainerConstructor<S extends object = any, P = any> = new (...args: any[]) => StateContainer<S, P>;
+
+export declare type StateContainerInstance<S extends object = any, P = any> = Omit<StateContainer<S, P>, 'state'> & {
+    state: Readonly<S>;
+};
+
+/**
+ * Central registry for managing StateContainer instances.
+ * Handles instance lifecycle, ref counting, and lifecycle event emission.
+ *
+ * @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 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.props - Props to pass to constructor if creating new instance
+     * @param options.trackExecutionContext - Whether to track cross-bloc dependency (default: false)
+     * @returns The state container instance
+     */
+    acquire<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string, options?: {
+        canCreate?: boolean;
+        countRef?: boolean;
+        props?: ExtractProps<T>;
+        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;
     /**
-     * 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.
+     * Get all instances of a specific type.
+     * @param Type - The StateContainer class constructor
+     * @returns Array of all instances
      */
-    protected on<E extends A>(eventConstructor: new (...args: any[]) => E, handler: (event: E, emit: (newState: S) => void) => void | Promise<void>): void;
+    getAll<T extends StateContainerConstructor>(Type: T): InstanceReadonlyState<T>[];
     /**
-     * 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.
+     * 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
      */
-    add: (action: A) => Promise<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
+     */
+    clear<T extends StateContainerConstructor>(Type: T): void;
+    /**
+     * Get reference count for an instance.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns Current ref count (0 if instance doesn't exist)
+     */
+    getRefCount<T extends StateContainerConstructor>(Type: T, instanceKey?: string): number;
+    /**
+     * Check if an instance exists.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns true if instance exists
+     */
+    hasInstance<T extends 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 */
 }
 
 /**
- * Base class for both Blocs and Cubits that provides core state management functionality.
- * Handles state transitions, observer notifications, lifecycle management, and addon integration.
+ * Constrain a type to only accept stateful containers (not StatelessCubit/StatelessVertex).
+ * Use this to reject stateless containers at the type level.
+ */
+export declare type StatefulContainerOnly<T extends StateContainerConstructor> = IsStatelessContainer<T> extends true ? never : T;
+
+/**
+ * Marker symbol to identify stateless containers at the type level.
+ * Used by React hooks to prevent `useBloc` from accepting stateless containers.
+ */
+export declare const STATELESS_MARKER: unique symbol;
+
+/**
+ * A Cubit without state management capabilities.
+ * Use this for action-only containers that don't need to manage or emit state.
+ *
+ * StatelessCubit:
+ * - Has no `emit()`, `update()`, or `patch()` methods
+ * - Has no accessible `state` property
+ * - Cannot be subscribed to (throws error)
+ * - Is rejected by `useBloc` hook (use `useBlocActions` instead)
+ *
+ * @template P - Props type (optional)
+ *
+ * @example
+ * ```typescript
+ * class AnalyticsService extends StatelessCubit {
+ *   trackPageView(page: string) {
+ *     analytics.track('page_view', { page });
+ *   }
  *
- * @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)
+ *   trackClick(element: string) {
+ *     analytics.track('click', { element });
+ *   }
+ * }
+ *
+ * // In React component:
+ * const analytics = useBlocActions(AnalyticsService);
+ * analytics.trackPageView('/home');
+ * ```
  */
-export declare abstract class BlocBase<S, P = unknown> {
+export declare abstract class StatelessCubit<P = undefined> extends Cubit<EmptyState, P> {
+    /* Excluded from this release type: [STATELESS_MARKER] */
+    constructor();
+    /**
+     * State is not available on StatelessCubit.
+     * @throws Always throws an error when accessed.
+     */
+    get state(): never;
     /**
-     * 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
+     * Subscriptions are not available on StatelessCubit.
+     * @throws Always throws an error when called.
      */
-    static isolated: boolean;
-    get isIsolated(): boolean;
+    subscribe(_listener: (state: EmptyState) => void): never;
     /**
-     * When true, the Bloc instance persists even when there are no active consumers.
-     * Useful for maintaining state between component unmount/remount cycles.
-     * @default false
+     * emit() is not available on StatelessCubit.
+     * TypeScript will show an error if you try to call this method.
      */
-    static keepAlive: boolean;
-    get isKeepAlive(): boolean;
+    emit(_newState: never): never;
     /**
-     * Defines how dependencies are selected from the state for efficient updates.
-     * When provided, observers will only be notified when selected dependencies change.
+     * update() is not available on StatelessCubit.
+     * TypeScript will show an error if you try to call this method.
      */
-    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 */
+    update(_updater: never): never;
     /**
-     * The unique identifier for this Bloc instance.
-     * Defaults to the class name, but can be customized.
+     * patch() is not available on StatelessCubit.
+     * @throws Error always - StatelessCubit does not support state changes
      */
-    _id: BlocInstanceId;
-    /* Excluded from this release type: _instanceRef */
-    /* Excluded from this release type: _keepAlive */
+    patch: (_partial: Partial<EmptyState>) => void;
+}
+
+/**
+ * Event handler for StatelessVertex that receives only the event (no emit function).
+ * Use for side-effect-only event processing.
+ */
+export declare type StatelessEventHandler<E extends DiscriminatedEvent> = (event: EventWithMetadata<E>) => void;
+
+/**
+ * Map of event types to their handlers for StatelessVertex.
+ * Enforces exhaustive handling of all event types in the union.
+ */
+export declare type StatelessEventHandlerMap<E extends DiscriminatedEvent> = {
+    [K in E['type']]: StatelessEventHandler<Extract<E, {
+        type: K;
+    }>>;
+};
+
+/**
+ * An event-driven container without state management capabilities.
+ * Use this for event processing that only produces side effects (logging, analytics, etc).
+ *
+ * StatelessVertex:
+ * - Processes events via `add()` method
+ * - Handlers receive only the event (no `emit` function)
+ * - Has no accessible `state` property
+ * - Cannot be subscribed to (throws error)
+ * - Is rejected by `useBloc` hook (use `useBlocActions` instead)
+ *
+ * @template E - Event union type (discriminated by 'type' property)
+ * @template P - Props type (optional)
+ *
+ * @example
+ * ```typescript
+ * type LogEvent =
+ *   | { type: 'info'; message: string }
+ *   | { type: 'error'; message: string; error: Error }
+ *   | { type: 'warn'; message: string };
+ *
+ * class LoggingVertex extends StatelessVertex<LogEvent> {
+ *   constructor() {
+ *     super();
+ *     this.createHandlers({
+ *       info: (event) => console.log('[INFO]', event.message),
+ *       error: (event) => console.error('[ERROR]', event.message, event.error),
+ *       warn: (event) => console.warn('[WARN]', event.message),
+ *     });
+ *   }
+ *
+ *   info = (message: string) => this.add({ type: 'info', message });
+ *   error = (message: string, error: Error) => this.add({ type: 'error', message, error });
+ *   warn = (message: string) => this.add({ type: 'warn', message });
+ * }
+ *
+ * // In React component:
+ * const logger = useBlocActions(LoggingVertex);
+ * logger.info('Page loaded');
+ * ```
+ */
+export declare abstract class StatelessVertex<E extends DiscriminatedEvent = DiscriminatedEvent, P = undefined> extends StateContainer<EmptyState_2, P> {
+    /* Excluded from this release type: [STATELESS_MARKER] */
+    /* Excluded from this release type: handlers */
+    /* Excluded from this release type: isProcessing */
+    /* Excluded from this release type: eventQueue */
+    constructor();
     /**
-     * @readonly
-     * Timestamp when this Bloc instance was created, useful for debugging and performance tracking.
+     * State is not available on StatelessVertex.
+     * @throws Always throws an error when accessed.
      */
-    readonly _createdAt: number;
-    /* Excluded from this release type: _state */
-    /* Excluded from this release type: _oldState */
+    get state(): never;
     /**
-     * Props passed during Bloc instance creation.
-     * Can be used to configure or parameterize the Bloc's behavior.
+     * Subscriptions are not available on StatelessVertex.
+     * @throws Always throws an error when called.
      */
-    props: P | null;
+    subscribe(_listener: (state: EmptyState_2) => void): never;
     /**
-     * Creates a new BlocBase instance with the given initial state.
-     * Sets up the observer, registers with the Blac manager, and initializes addons.
+     * Register all event handlers with exhaustive type checking.
+     * TypeScript will error if any event type from the union is missing.
      *
-     * @param initialState The initial state value for this Bloc
+     * Unlike regular Vertex, handlers do NOT receive an emit function
+     * since StatelessVertex cannot emit state.
+     *
+     * @param handlers - Map of event type to handler function
      */
-    constructor(initialState: S);
+    protected createHandlers(handlers: StatelessEventHandlerMap<E>): void;
+    /**
+     * Dispatch an event for processing.
+     * Events are processed synchronously; if called during processing,
+     * the event is queued and processed after the current event completes.
+     *
+     * @param event - The event to process (must match the event union type)
+     */
+    add: (event: E) => void;
+    /* Excluded from this release type: enrichEvent */
+    /* Excluded from this release type: processEvent */
+    /* Excluded from this release type: handleEvent */
     /**
-     * Returns the current state of the Bloc.
-     * Use this getter to access the state in a read-only manner.
+     * Called when an error occurs during event processing.
+     * Override to implement custom error handling.
+     *
+     * @param _event - The event that caused the error
+     * @param _error - The error that occurred
      */
-    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 */
+    protected onEventError(_event: EventWithMetadata<E>, _error: Error): void;
+    /* Excluded from this release type: emit */
+    /* Excluded from this release type: update */
 }
 
+/* Excluded from this release type: StateListener */
+
+declare const STOP: unique symbol;
+
+/* Excluded from this release type: stopProxy */
+
+declare type StopSymbol = typeof STOP;
+
 /**
- * Represents the abstract base types for Bloc and Cubit
+ * Stop tracking and collect all dependencies.
  */
-export declare type BlocBaseAbstract = typeof Bloc<any, any, any> | typeof Cubit<any, any>;
+export declare function stopTrackingProxy(tracker: TrackingProxyState, bloc: StateContainerInstance): Set<StateContainerInstance>;
 
 /**
- * Represents a constructor type for a Bloc that takes no parameters
- * @template B - The type of the Bloc instance
+ * Function that subscribes to state changes and returns an unsubscribe function
  */
-export declare type BlocClassNoParams<B> = new (args: never[]) => B;
+export declare type SubscribeFunction = (callback: SubscriptionCallback) => () => void;
 
 /**
- * Represents a constructor type for a Bloc that can take any parameters
- * @template B - The type of the Bloc instance
+ * Callback function invoked when subscribed state changes
  */
-export declare type BlocConstructor<B> = new (...args: any) => B;
+export declare type SubscriptionCallback = () => void;
 
 /**
- * Extracts the constructor parameters type from a BlocBase
- * @template B - The BlocBase type to extract the constructor parameters from
+ * System events emitted by StateContainer lifecycle
  */
-export declare type BlocConstructorParameters<B extends BlocBase<any>> = BlocConstructor<B> extends new (...args: infer P) => B ? P : never;
+export declare type SystemEvent = 'propsUpdated' | 'stateChanged' | 'dispose';
+
+/* Excluded from this release type: SystemEventHandler */
 
 /**
- * Represents a function type for determining hook dependencies based on state changes
- * @template B - The BlocGeneric type
+ * Payload types for each system event
+ * @template S - State type
+ * @template P - Props type
  */
-export declare type BlocHookDependencyArrayFn<S> = (newState: S, oldState: S) => unknown[][];
-
-export declare type BlocInstanceId = string | number | undefined;
+export declare interface SystemEventPayloads<S, P> {
+    /** Emitted when props are updated via updateProps() */
+    propsUpdated: {
+        props: P;
+        previousProps: P | undefined;
+    };
+    /** Emitted when state changes via emit() or update() */
+    stateChanged: {
+        state: S;
+        previousState: S;
+    };
+    /** Emitted when the instance is disposed */
+    dispose: void;
+}
 
 /**
- * Extracts the state type from either a Bloc or Cubit
- * @template T - The Bloc or Cubit type to extract the state from
+ * Run a callback while tracking all bloc dependencies accessed.
+ * Returns both the result and the set of discovered dependencies.
+ *
+ * @example
+ * ```ts
+ * const { result, dependencies } = tracked(() => {
+ *   const user = ensure(UserBloc);
+ *   return user.fullName; // getter that may access other blocs
+ * });
+ * // dependencies contains UserBloc + any blocs accessed in fullName getter
+ * ```
  */
-export declare type BlocState<T> = T extends BlocBase<infer S> ? S : never;
+export declare function tracked<T>(callback: () => T, options?: TrackedOptions): TrackedResult<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)
+ * Context for running tracked callbacks with bloc proxies.
+ * Provides methods to create proxies and check for changes.
  */
-export declare abstract class Cubit<S, P = null> extends BlocBase<S, P> {
+export declare class TrackedContext {
+    private tracker;
+    private proxiedBlocs;
+    private primaryBlocs;
+    constructor();
     /**
-     * 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
+     * Get a tracking proxy for a bloc instance.
+     * The proxy will track state and getter accesses.
      */
-    emit(state: S): void;
+    proxy<T extends StateContainerInstance>(bloc: T): T;
     /**
-     * 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
+     * Start tracking for a new callback execution.
+     */
+    start(): void;
+    /**
+     * Stop tracking and get discovered dependencies.
+     * Excludes primary blocs (those explicitly proxied via proxy()).
+     */
+    stop(): Set<StateContainerInstance>;
+    /**
+     * Check if any tracked state or getters have changed.
+     */
+    changed(): boolean;
+    /**
+     * Get all primary blocs (those explicitly proxied).
+     */
+    getPrimaryBlocs(): Set<StateContainerInstance>;
+    /**
+     * Reset the context for reuse.
      */
-    patch(statePatch: S extends object ? Partial<S> : S, ignoreChangeCheck?: boolean): void;
+    reset(): void;
 }
 
-declare type DependencySelector<S> = (newState: S, oldState?: S) => unknown[][];
+/**
+ * Options for the tracked() function.
+ */
+export declare interface TrackedOptions {
+    exclude?: StateContainerInstance;
+}
 
-export declare interface GetBlocOptions<B extends BlocBase<any>> {
-    id?: string;
-    dependencySelector?: BlocHookDependencyArrayFn<BlocState<B>>;
-    props?: InferPropsFromGeneric<B>;
-    onMount?: (bloc: B) => void;
-    instanceRef?: string;
+/**
+ * Result of running a tracked callback.
+ */
+export declare interface TrackedResult<T> {
+    result: T;
+    dependencies: Set<StateContainerInstance>;
 }
 
 /**
- * Extracts the props type from either a Bloc or Cubit
- * @template T - The Bloc or Cubit type to extract the props from
+ * State for tracking both state property access and getter access.
  */
-export declare type InferPropsFromGeneric<T> = T extends Bloc<any, any, infer P> ? P : T extends Cubit<any, infer P> ? P : never;
+export declare interface TrackingProxyState {
+    dependencyState: DependencyState<any>;
+    getterState: GetterState;
+    dependencies: Set<StateContainerInstance>;
+    isTracking: boolean;
+}
 
 /**
- * Persist addon
+ * Event-driven state container using discriminated union events.
+ * Extends StateContainer with event-based state transitions and
+ * compile-time exhaustive checking for event handlers.
+ *
+ * @template S - State type (must be an object)
+ * @template E - Event union type (discriminated by 'type' property)
+ * @template P - Props type (optional)
+ *
+ * @example
+ * ```typescript
+ * type CounterEvent =
+ *   | { type: 'increment'; amount: number }
+ *   | { type: 'decrement' }
+ *   | { type: 'reset' };
+ *
+ * class CounterVertex extends Vertex<{ count: number }, CounterEvent> {
+ *   constructor() {
+ *     super({ count: 0 });
+ *     this.createHandlers({
+ *       increment: (event, emit) => {
+ *         emit({ count: this.state.count + event.amount });
+ *       },
+ *       decrement: (_, emit) => {
+ *         emit({ count: this.state.count - 1 });
+ *       },
+ *       reset: (_, emit) => {
+ *         emit({ count: 0 });
+ *       },
+ *     });
+ *   }
  *
- * @param options
- * @returns BlacAddon
+ *   increment = (amount = 1) => this.add({ type: 'increment', amount });
+ * }
+ * ```
  */
-export declare function Persist(options?: {
-    /**
-     * @default 'blac'
-     */
-    keyPrefix?: string;
-    /**
-     * @default the bloc's id
-     */
-    keyName?: string;
+export declare abstract class Vertex<S extends object = object, E extends DiscriminatedEvent = DiscriminatedEvent, P = undefined> extends StateContainer<S, P> {
+    /* Excluded from this release type: handlers */
+    /* Excluded from this release type: isProcessing */
+    /* Excluded from this release type: eventQueue */
+    constructor(initialState: S);
     /**
-     * Used when the value is not found in storage
+     * Register all event handlers with exhaustive type checking.
+     * TypeScript will error if any event type from the union is missing.
+     *
+     * @param handlers - Map of event type to handler function
      */
-    defaultValue?: unknown;
+    protected createHandlers(handlers: EventHandlerMap<E, S>): void;
     /**
-     * @default 'localStorage'
-     * @see StorageType
+     * Dispatch an event for processing.
+     * Events are processed synchronously; if called during processing,
+     * the event is queued and processed after the current event completes.
+     *
+     * @param event - The event to process (must match the event union type)
      */
-    storageType?: StorageType;
+    add: (event: E) => void;
+    /* Excluded from this release type: enrichEvent */
+    /* Excluded from this release type: processEvent */
+    /* Excluded from this release type: handleEvent */
     /**
-     * @default false
+     * Called when an error occurs during event processing.
+     * Override to implement custom error handling.
+     *
+     * @param _event - The event that caused the error
+     * @param _error - The error that occurred
      */
-    onError?: (e: unknown) => void;
-}): BlacAddon;
+    protected onEventError(_event: EventWithMetadata<E>, _error: Error): void;
+}
+
+/* Excluded from this release type: VertexEventHandler */
+
+/**
+ * Wait until a condition is met on a bloc instance.
+ * Returns the bloc instance when the predicate returns true.
+ * Automatically tracks dependencies accessed in the predicate.
+ *
+ * @example
+ * ```ts
+ * // Wait for bloc state to be ready
+ * const userBloc = await waitUntil(UserBloc, (bloc) => bloc.state.isAuthenticated);
+ *
+ * // Wait using a getter
+ * const userBloc = await waitUntil(UserBloc, (bloc) => bloc.isReady);
+ * ```
+ */
+export declare function waitUntil<T extends StateContainerConstructor>(BlocClass: T, predicate: (bloc: InstanceType<T>) => boolean, options?: WaitUntilOptions): Promise<InstanceType<T>>;
+
+/**
+ * Wait until a condition is met on a selected value from a bloc.
+ * Returns the selected value when the predicate returns true.
+ * Automatically tracks dependencies accessed in selector and predicate.
+ *
+ * @example
+ * ```ts
+ * // Wait for layout to be set and get it directly
+ * const layout = await waitUntil(
+ *   LayoutBloc,
+ *   (bloc) => bloc.state.currentLayout,
+ *   (layout) => layout !== null
+ * );
+ *
+ * // Using a getter as selector
+ * const user = await waitUntil(
+ *   UserBloc,
+ *   (bloc) => bloc.currentUser,
+ *   (user) => user !== null
+ * );
+ * ```
+ */
+export declare function waitUntil<T extends StateContainerConstructor, TSelected>(BlocClass: T, selector: (bloc: InstanceType<T>) => TSelected, predicate: (selected: TSelected) => boolean, options?: WaitUntilOptions): Promise<TSelected>;
 
-declare type StorageType = 'localStorage' | 'sessionStorage';
+export declare class WaitUntilAbortedError extends Error {
+    constructor();
+}
+
+export declare class WaitUntilDisposedError extends Error {
+    constructor(blocName: string);
+}
+
+export declare interface WaitUntilOptions {
+    instanceId?: string;
+    timeout?: number;
+    signal?: AbortSignal;
+}
+
+export declare class WaitUntilTimeoutError extends Error {
+    constructor(timeout: number);
+}
+
+/**
+ * Log a warning message (tree-shakeable export)
+ * @param context - Context identifier (module or component name)
+ * @param message - Log message
+ * @param data - Optional structured data
+ */
+export declare const warn: (context: string, message: string, data?: any) => void;
+
+export declare const watch: WatchFn;
+
+/**
+ * Combined watch function type.
+ */
+export declare interface WatchFn extends WatchSingleFn {
+    <T extends readonly BlocInput[]>(blocs: T, callback: (blocs: ExtractInstances<T>) => void | StopSymbol): () => void;
+}
 
 /**
- * Extracts the state type from a BlocBase instance
- * @template B - The BlocBase type to extract the state from
+ * Watch function signature for single bloc.
  */
-export declare type ValueType<B extends BlocBase<any>> = B extends BlocBase<infer U> ? U : never;
+declare interface WatchSingleFn {
+    <T extends StateContainerConstructor>(bloc: T | BlocRef<T>, callback: (bloc: InstanceType<T>) => void | StopSymbol): () => void;
+    STOP: StopSymbol;
+}
 
 export { }