@blac/core 2.0.0-rc.10 → 2.0.0-rc.11

package/dist/index.d.ts

@@ -1,21 +1,1298 @@
-export * from './core/StateContainer';
-export type { SystemEvent, SystemEventPayloads } from './core/StateContainer';
-export * from './core/StateContainerRegistry';
-export * from './core/Cubit';
-export * from './core/Vertex';
-export { globalRegistry, getPluginManager, } from './core/StateContainerRegistry';
-export type { LifecycleEvent, LifecycleListener, } from './core/StateContainerRegistry';
-export type { BlacPlugin, BlacPluginWithInit, PluginContext, PluginConfig, InstanceMetadata, } from './plugin/BlacPlugin';
-export { PluginManager, createPluginManager } from './plugin/PluginManager';
-export { hasInitHook } from './plugin/BlacPlugin';
-export * from './tracking';
-export * from './adapter';
-export type { Brand, BrandedId, InstanceId } from './types/branded';
-export type { BaseEvent } from './types/events';
-export * from './types/utilities';
-export { createLogger, configureLogger, debug, info, warn, error, LogLevel, type LogConfig, type LogEntry, } from './logging/Logger';
-export { BLAC_DEFAULTS, BLAC_STATIC_PROPS, BLAC_ID_PATTERNS, BLAC_ERROR_PREFIX, } from './constants';
-export { generateId, generateSimpleId, createIdGenerator, __resetIdCounters, generateIsolatedKey, isIsolatedKey, } from './utils/idGenerator';
-export { getStaticProp, isIsolatedClass, isKeepAliveClass, isExcludedFromDevTools, } from './utils/static-props';
-export { blac, type BlacOptions } from './decorators';
-//# sourceMappingURL=index.d.ts.map
+/* Excluded from this release type: __resetIdCounters */
+
+/**
+ * Internal state for framework adapters, holding tracking and caching data.
+ * @template TBloc - The state container type
+ */
+export declare interface AdapterState<TBloc extends StateContainer<any, any>> {
+    /** Proxy tracker for state property access tracking */
+    tracker: TrackerState<ExtractState<TBloc>> | null;
+    /** Cached manual dependencies for comparison */
+    manualDepsCache: unknown[] | null;
+    /** Getter tracker for computed property tracking */
+    getterTracker: GetterTrackerState | null;
+    /** Proxied bloc instance for auto-tracking */
+    proxiedBloc: TBloc | null;
+}
+
+/**
+ * Base event interface
+ * Used by Vertex for event-driven state management
+ */
+export declare interface BaseEvent {
+    /** Event type identifier (typically the class name) */
+    readonly type: string;
+    /** Unix timestamp when the event was created */
+    readonly timestamp: number;
+    /** Optional source identifier for debugging */
+    readonly source?: string;
+}
+
+/**
+ * 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";
+};
+
+/**
+ * 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>(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 BaseEvent>(vertex: Vertex<any, E>, event: 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;
+}
+
+/**
+ * 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<TBloc extends StateContainer<any, any>> = (new (...args: any[]) => TBloc) & {
+    resolve(instanceKey?: string, ...args: any[]): TBloc;
+    get(instanceKey?: string): TBloc;
+    getSafe(instanceKey?: string): {
+        error: Error;
+        instance: null;
+    } | {
+        error: null;
+        instance: TBloc;
+    };
+    release(instanceKey?: string): void;
+    isolated?: boolean;
+    keepAlive?: boolean;
+};
+
+/**
+ * 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: captureTrackedPaths */
+
+/* Excluded from this release type: clearActiveTracker */
+
+/* Excluded from this release type: clearExternalDependencies */
+
+/* Excluded from this release type: commitTrackedGetters */
+
+/**
+ * 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 */
+
+/**
+ * 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 createAutoTrackSnapshot<TBloc extends StateContainer<any, any>>(instance: 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 createAutoTrackSubscribe<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>): SubscribeFunction;
+
+/* Excluded from this release type: createBlocProxy */
+
+/* Excluded from this release type: createGetterTracker */
+
+/**
+ * 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;
+};
+
+/**
+ * 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 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 createManualDepsSnapshot<TBloc extends StateContainer<any, any>>(instance: 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 createManualDepsSubscribe<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SubscribeFunction;
+
+/**
+ * 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 createNoTrackSnapshot<TBloc extends StateContainer<any, any>>(instance: 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 createNoTrackSubscribe<TBloc extends StateContainer<any, any>>(instance: TBloc): SubscribeFunction;
+
+/**
+ * Create a plugin manager instance
+ */
+export declare function createPluginManager(registry: StateContainerRegistry): PluginManager;
+
+/* Excluded from this release type: createProxy */
+
+/* Excluded from this release type: createProxyForTarget */
+
+/* Excluded from this release type: createProxyInternal */
+
+/* Excluded from this release type: createProxyTrackerState */
+
+/* Excluded from this release type: createTrackerState */
+
+/**
+ * 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, 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;
+
+/**
+ * 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 StateContainer<any, any>>(adapterState: AdapterState<TBloc>, rawInstance: TBloc): void;
+
+/**
+ * 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;
+
+/**
+ * Constructor type for event classes
+ * @template T - Event type
+ */
+export declare type EventConstructor<T extends BaseEvent = BaseEvent> = new (...args: never[]) => T;
+
+/**
+ * Handler function for processing events in Vertex
+ * @template E - Event type
+ * @template S - State type
+ * @param event - The event being handled
+ * @param emit - Function to emit new state
+ */
+export declare type EventHandler<E extends BaseEvent, S> = (event: E, emit: (state: S) => void) => void;
+
+/**
+ * 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.
+ */
+export declare class ExternalDependencyManager {
+    private subscriptions;
+    private previousDeps;
+    private areDependenciesEqual;
+    /**
+     * 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(getterTracker: GetterTrackerState | null, rawInstance: StateContainer<any, any>, 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 the props type from a StateContainer
+ * @template T - The StateContainer type
+ */
+export declare type ExtractProps<T> = T extends StateContainer<any, infer P> ? P : undefined;
+
+/**
+ * Extract the state type from a StateContainer
+ * @template T - The StateContainer type
+ */
+export declare type ExtractState<T> = T extends StateContainer<infer S, any> ? S : never;
+
+/**
+ * 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 */
+
+/* Excluded from this release type: getDescriptor */
+
+/* Excluded from this release type: getGetterExecutionContext */
+
+/**
+ * Get the global plugin manager
+ */
+export declare function getPluginManager(): any;
+
+/**
+ * Utility functions for accessing static properties on StateContainer classes
+ */
+/**
+ * Get a static property from a class constructor
+ * Type-safe helper that avoids (Type as any) casts
+ *
+ * @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<T>(Type: new (...args: any[]) => any, propName: string, defaultValue?: T): T | undefined;
+
+declare interface GetterExecutionContext {
+    tracker: GetterTrackerState | null;
+    currentBloc: StateContainer<any> | null;
+    depth: number;
+    visitedBlocs: Set<StateContainer<any>>;
+}
+
+/* Excluded from this release type: GetterTrackerState */
+
+/* Excluded from this release type: getValueAtPath */
+
+/**
+ * Global default registry instance
+ */
+export declare const globalRegistry: StateContainerRegistry;
+
+/* Excluded from this release type: hasChanges */
+
+/* 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;
+
+/* Excluded from this release type: hasTrackedData */
+
+/**
+ * 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;
+
+/**
+ * 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 initAutoTrackState<TBloc extends StateContainer<any, any>>(instance: TBloc): AdapterState<TBloc>;
+
+/**
+ * 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 initManualDepsState<TBloc extends StateContainer<any, any>>(instance: TBloc): AdapterState<TBloc>;
+
+/**
+ * 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 initNoTrackState<TBloc extends StateContainer<any, any>>(instance: TBloc): AdapterState<TBloc>;
+
+/**
+ * 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'>;
+
+/**
+ * Metadata information about a state container instance for debugging and inspection
+ */
+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;
+}
+
+/* Excluded from this release type: invalidateRenderCache */
+
+/**
+ * Check if a class should be excluded from DevTools
+ * Used to prevent infinite loops when DevTools tracks itself
+ */
+export declare function isExcludedFromDevTools(Type: new (...args: any[]) => any): boolean;
+
+/* Excluded from this release type: isGetter */
+
+/**
+ * Check if a class is marked as isolated
+ * Isolated classes create separate instances per component
+ */
+export declare function isIsolatedClass(Type: new (...args: any[]) => any): 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
+ */
+export declare function isKeepAliveClass(Type: new (...args: any[]) => any): boolean;
+
+/* Excluded from this release type: isProxyable */
+
+/**
+ * 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 StateContainer<any, any>> {
+    /** Function that returns dependency array from state and bloc */
+    dependencies: (state: any, bloc: TBloc) => unknown[];
+}
+
+/* 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 {
+    /**
+     * Get metadata for a specific instance
+     */
+    getInstanceMetadata(instance: StateContainer<any>): InstanceMetadata;
+    /**
+     * Get current state from a container
+     */
+    getState<S>(instance: StateContainer<S>): S;
+    /**
+     * Get all instances of a specific type
+     */
+    queryInstances<T extends StateContainer<any>>(typeClass: new (...args: any[]) => T): T[];
+    /**
+     * Get all registered state container types
+     */
+    getAllTypes(): Array<new (...args: any[]) => StateContainer<any>>;
+    /**
+     * Get registry statistics
+     */
+    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;
+    /**
+     * Create a new PluginManager
+     * @param registry - The StateContainerRegistry to monitor for lifecycle events
+     */
+    constructor(registry: StateContainerRegistry);
+    /**
+     * Install a plugin with optional configuration
+     * @param plugin - The plugin to install
+     * @param config - Optional plugin configuration
+     * @throws Error if plugin is already installed
+     */
+    install(plugin: BlacPlugin, config?: PluginConfig): void;
+    /**
+     * Uninstall a plugin by name
+     * @param pluginName - The name of the plugin to uninstall
+     * @throws Error if plugin is not installed
+     */
+    uninstall(pluginName: string): void;
+    /**
+     * Get an installed plugin by name
+     * @param pluginName - The name of the plugin to retrieve
+     * @returns The plugin instance or undefined if not found
+     */
+    getPlugin(pluginName: string): BlacPlugin | undefined;
+    /**
+     * Get all installed plugins
+     * @returns Array of all installed plugins
+     */
+    getAllPlugins(): BlacPlugin[];
+    /**
+     * Check if a plugin is installed
+     * @param pluginName - The name of the plugin to check
+     * @returns true if the plugin is installed
+     */
+    hasPlugin(pluginName: string): boolean;
+    /**
+     * Uninstall all plugins
+     */
+    clear(): void;
+    /**
+     * Setup lifecycle hooks to notify plugins
+     */
+    private setupLifecycleHooks;
+    /**
+     * Notify all plugins of a lifecycle event
+     */
+    private notifyPlugins;
+    /**
+     * Create plugin context with safe API access
+     */
+    private createPluginContext;
+    /**
+     * Check if plugin should be enabled based on environment
+     */
+    private shouldEnablePlugin;
+    /**
+     * Get current environment
+     */
+    private getCurrentEnvironment;
+}
+
+/* Excluded from this release type: ProxyTrackerState */
+
+/* Excluded from this release type: resetGetterTracker */
+
+/* Excluded from this release type: setActiveTracker */
+
+/* Excluded from this release type: shallowEqual */
+
+/**
+ * Function that returns a snapshot of the current state
+ * @template TState - The state type
+ */
+export declare type SnapshotFunction<TState> = () => TState;
+
+/* Excluded from this release type: startProxyTracking */
+
+/* Excluded from this release type: startTracking */
+
+/**
+ * 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<number> {
+ *   constructor() {
+ *     super(0);
+ *   }
+ *   increment() {
+ *     this.emit(this.state + 1);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class StateContainer<S, P = undefined> {
+    /* Excluded from this release type: __excludeFromDevTools */
+    /* Excluded from this release type: _registry */
+    /**
+     * Get the global StateContainerRegistry
+     * @returns The registry managing all state container instances
+     */
+    static getRegistry(): StateContainerRegistry;
+    /**
+     * Replace the global registry (clears existing instances)
+     * @param registry - The new registry to use
+     */
+    static setRegistry(registry: StateContainerRegistry): void;
+    /**
+     * Register this class with the global registry
+     * @param isolated - Whether instances should be isolated (component-scoped)
+     */
+    static register<T extends StateContainer<any>>(this: new (...args: any[]) => T, isolated?: boolean): void;
+    /**
+     * Resolve an instance with ref counting (ownership semantics).
+     * Creates a new instance if one doesn't exist, or returns existing and increments ref count.
+     * @param instanceKey - Optional instance key (defaults to 'default')
+     * @param constructorArgs - Arguments to pass to constructor if creating new instance
+     * @returns The state container instance
+     */
+    static resolve<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    /**
+     * Get an existing instance without incrementing ref count (borrowing semantics).
+     * @param instanceKey - Optional instance key (defaults to 'default')
+     * @returns The state container instance
+     * @throws Error if instance doesn't exist
+     */
+    static get<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): T;
+    /**
+     * Safely get an existing instance with error handling.
+     * @param instanceKey - Optional instance key (defaults to 'default')
+     * @returns Discriminated union with either the instance or an error
+     */
+    static getSafe<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): {
+        error: Error;
+        instance: null;
+    } | {
+        error: null;
+        instance: T;
+    };
+    /**
+     * Connect to an instance for bloc-to-bloc communication (borrowing semantics).
+     * Gets or creates instance without incrementing ref count.
+     * @param instanceKey - Optional instance key (defaults to 'default')
+     * @param constructorArgs - Arguments to pass to constructor if creating new instance
+     * @returns The state container instance
+     */
+    static connect<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    /**
+     * Release a reference to an instance.
+     * Decrements ref count and disposes when it reaches 0 (unless keepAlive).
+     * @param instanceKey - Optional instance key (defaults to 'default')
+     * @param forceDispose - Force immediate disposal regardless of ref count
+     */
+    static release<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
+    /**
+     * Get all instances of this class
+     * @returns Array of all instances
+     */
+    static getAll<T extends StateContainer<any>>(this: new (...args: any[]) => T): T[];
+    /**
+     * Iterate over all instances of this class
+     * @param callback - Function to call for each instance
+     */
+    static forEach<T extends StateContainer<any>>(this: new (...args: any[]) => T, callback: (instance: T) => void): void;
+    /**
+     * Clear all instances of this class (disposes them)
+     */
+    static clear<T extends StateContainer<any>>(this: new (...args: any[]) => T): void;
+    /**
+     * Clear all instances from all registered types
+     */
+    static clearAllInstances(): void;
+    /**
+     * Get registry statistics for debugging
+     * @returns Object with registeredTypes, totalInstances, and typeBreakdown
+     */
+    static getStats(): {
+        registeredTypes: number;
+        totalInstances: number;
+        typeBreakdown: Record<string, number>;
+    };
+    /**
+     * Get reference count for an instance
+     * @param instanceKey - Optional instance key (defaults to 'default')
+     * @returns Current ref count (0 if instance doesn't exist)
+     */
+    static getRefCount<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): number;
+    /**
+     * Check if an instance exists
+     * @param instanceKey - Optional instance key (defaults to 'default')
+     * @returns true if instance exists
+     */
+    static hasInstance<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): 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);
+    /**
+     * Initialize configuration for this instance.
+     * Called by the registry after construction.
+     * @param config - Configuration options
+     */
+    initConfig(config: StateContainerConfig): void;
+    /** Current state value */
+    get state(): S;
+    /** Whether this instance has been disposed */
+    get isDisposed(): boolean;
+    /**
+     * 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
+     */
+    protected emit(newState: S): void;
+    /** Whether to capture stack traces on state changes (disabled in production) */
+    static enableStackTrace: boolean;
+    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, P, E>) => (() => void);
+    private emitSystemEvent;
+    /**
+     * Update the props for this container.
+     * Emits the 'propsUpdated' system event.
+     * @param newProps - The new props value
+     */
+    updateProps(newProps: P): void;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Central registry for managing StateContainer instances.
+ * Handles instance lifecycle, ref counting, and lifecycle event emission.
+ *
+ * @example
+ * ```ts
+ * const registry = new StateContainerRegistry();
+ * const instance = registry.resolve(MyBloc);
+ * 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 StateContainer<any>>(constructor: new (...args: any[]) => T): void;
+    /**
+     * Register a StateContainer class with configuration
+     * @param constructor - The StateContainer class constructor
+     * @param isolated - Whether instances should be isolated (component-scoped)
+     * @throws Error if type is already registered
+     */
+    register<T extends StateContainer<any>>(constructor: new (...args: any[]) => T, isolated?: boolean): void;
+    private ensureInstancesMap;
+    /**
+     * Get the instances Map for a specific class (public API for stats/debugging)
+     */
+    getInstancesMap<T extends StateContainer<any>>(Type: new (...args: any[]) => T): Map<string, InstanceEntry>;
+    /**
+     * Resolve an instance with ref counting (ownership semantics)
+     */
+    resolve<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    /**
+     * Get an existing instance without ref counting (borrowing semantics)
+     * @throws Error if instance doesn't exist
+     */
+    get<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): T;
+    /**
+     * Safely get an existing instance (borrowing semantics with error handling)
+     * Returns discriminated union for type-safe conditional access
+     */
+    getSafe<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): {
+        error: Error;
+        instance: null;
+    } | {
+        error: null;
+        instance: T;
+    };
+    /**
+     * Connect to an instance with borrowing semantics (for B2B communication)
+     * Gets existing instance OR creates it if it doesn't exist, without incrementing ref count.
+     * Tracks cross-bloc dependency for reactive updates.
+     *
+     * Use this in bloc-to-bloc communication when you need to ensure an instance exists
+     * but don't want to claim ownership (no ref count increment).
+     *
+     * @param Type - The bloc class constructor
+     * @param instanceKey - Optional instance key (defaults to 'default')
+     * @param constructorArgs - Constructor arguments (only used if creating new instance)
+     * @returns The bloc instance
+     */
+    connect<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    /**
+     * Release a reference to an instance
+     */
+    release<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
+    /**
+     * Get all instances of a specific type
+     */
+    getAll<T extends StateContainer<any>>(Type: new (...args: any[]) => T): T[];
+    /**
+     * Safely iterate over all instances of a type
+     */
+    forEach<T extends StateContainer<any>>(Type: new (...args: any[]) => T, callback: (instance: T) => void): void;
+    /**
+     * Clear all instances of a specific type
+     */
+    clear<T extends StateContainer<any>>(Type: new (...args: any[]) => T): void;
+    /**
+     * Get reference count for an instance
+     */
+    getRefCount<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): number;
+    /**
+     * Check if an instance exists
+     */
+    hasInstance<T extends StateContainer<any>>(Type: new (...args: any[]) => 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)
+     */
+    getStats(): {
+        registeredTypes: number;
+        totalInstances: number;
+        typeBreakdown: Record<string, number>;
+    };
+    /**
+     * Get all registered types (for plugin system)
+     */
+    getTypes(): Array<new (...args: any[]) => StateContainer<any>>;
+    /**
+     * 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 */
+
+/* Excluded from this release type: stopProxyTracking */
+
+/**
+ * Function that subscribes to state changes and returns an unsubscribe function
+ */
+export declare type SubscribeFunction = (callback: SubscriptionCallback) => () => void;
+
+/**
+ * Callback function invoked when subscribed state changes
+ */
+export declare type SubscriptionCallback = () => void;
+
+/**
+ * System events emitted by StateContainer lifecycle
+ */
+export declare type SystemEvent = 'propsUpdated' | 'stateChanged' | 'dispose';
+
+/* Excluded from this release type: SystemEventHandler */
+
+/**
+ * Payload types for each system event
+ * @template S - State type
+ * @template P - Props type
+ */
+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;
+}
+
+/* Excluded from this release type: TrackerState */
+
+/**
+ * Event-driven state container that processes events to update state.
+ * Use with event handlers registered via the on() method.
+ *
+ * @template S - State type
+ * @template E - Event type (extends BaseEvent)
+ * @template P - Props type (optional)
+ */
+export declare abstract class Vertex<S, E extends BaseEvent = BaseEvent, P = undefined> extends StateContainer<S, P> {
+    private eventHandlers;
+    private isProcessing;
+    private eventQueue;
+    constructor(initialState: S);
+    /**
+     * Register a handler for a specific event type
+     * @param EventClass - The event class constructor
+     * @param handler - Function to handle events of this type
+     */
+    protected on: <T extends E>(EventClass: EventConstructor<T>, handler: EventHandler<T, S>) => void;
+    /**
+     * Add an event to the event stream for processing
+     * @param event - The event to process
+     */
+    add: (event: E) => void;
+    private processEvent;
+    private handleEvent;
+    /**
+     * Handle errors that occur during event processing.
+     * Override this method to implement custom error handling.
+     * @param _event - The event that caused the error
+     * @param _error - The error that occurred
+     */
+    protected onEventError(_event: E, _error: Error): void;
+}
+
+/**
+ * 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 { }