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

package/dist/index.js

@@ -38,10 +38,8 @@ function createIdGenerator(prefix) {
 * @returns Branded ID string
 *
 * @example
-* ```ts
 * const id = generateId('sub');
 * // Returns: "sub:1698765432100_1_a3k9d7f2q"
-* ```
 */
 function generateId(prefix) {
 	const counter = (globalCounters.get(prefix) ?? 0) + 1;
@@ -96,12 +94,32 @@ function isIsolatedKey(key) {
 
 //#endregion
 //#region src/plugin/PluginManager.ts
+/**
+* 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' });
+* ```
+*/
 var PluginManager = class {
+	/**
+	* Create a new PluginManager
+	* @param registry - The StateContainerRegistry to monitor for lifecycle events
+	*/
 	constructor(registry) {
 		this.plugins = /* @__PURE__ */ new Map();
 		this.registry = registry;
 		this.setupLifecycleHooks();
 	}
+	/**
+	* 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, config = {}) {
 		const effectiveConfig = {
 			enabled: true,
@@ -128,6 +146,11 @@ var PluginManager = class {
 		}
 		console.log(`[BlaC] Plugin "${plugin.name}" v${plugin.version} installed`);
 	}
+	/**
+	* Uninstall a plugin by name
+	* @param pluginName - The name of the plugin to uninstall
+	* @throws Error if plugin is not installed
+	*/
 	uninstall(pluginName) {
 		const installed = this.plugins.get(pluginName);
 		if (!installed) throw new Error(`Plugin "${pluginName}" is not installed`);
@@ -139,15 +162,32 @@ var PluginManager = class {
 		this.plugins.delete(pluginName);
 		console.log(`[BlaC] Plugin "${pluginName}" uninstalled`);
 	}
+	/**
+	* 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) {
 		return this.plugins.get(pluginName)?.plugin;
 	}
+	/**
+	* Get all installed plugins
+	* @returns Array of all installed plugins
+	*/
 	getAllPlugins() {
 		return Array.from(this.plugins.values()).map((p) => p.plugin);
 	}
+	/**
+	* Check if a plugin is installed
+	* @param pluginName - The name of the plugin to check
+	* @returns true if the plugin is installed
+	*/
 	hasPlugin(pluginName) {
 		return this.plugins.has(pluginName);
 	}
+	/**
+	* Uninstall all plugins
+	*/
 	clear() {
 		for (const name of this.plugins.keys()) this.uninstall(name);
 	}
@@ -294,9 +334,15 @@ const getterExecutionContext = {
 	visitedBlocs: /* @__PURE__ */ new Set()
 };
 const MAX_GETTER_DEPTH = BLAC_DEFAULTS.MAX_GETTER_DEPTH;
+/**
+* @internal
+*/
 function getGetterExecutionContext() {
 	return getterExecutionContext;
 }
+/**
+* @internal
+*/
 function getDescriptor(obj, prop) {
 	const constructor = obj.constructor;
 	let constructorCache = descriptorCache.get(constructor);
@@ -315,9 +361,15 @@ function getDescriptor(obj, prop) {
 	constructorCache.set(prop, descriptor);
 	return descriptor;
 }
+/**
+* @internal
+*/
 function isGetter(obj, prop) {
 	return getDescriptor(obj, prop)?.get !== void 0;
 }
+/**
+* @internal
+*/
 function createGetterTracker() {
 	return {
 		trackedValues: /* @__PURE__ */ new Map(),
@@ -329,19 +381,34 @@ function createGetterTracker() {
 		externalDependencies: /* @__PURE__ */ new Set()
 	};
 }
+/**
+* @internal
+*/
 function setActiveTracker(bloc, tracker) {
 	activeTrackerMap.set(bloc, tracker);
 }
+/**
+* @internal
+*/
 function clearActiveTracker(bloc) {
 	activeTrackerMap.delete(bloc);
 }
+/**
+* @internal
+*/
 function getActiveTracker(bloc) {
 	return activeTrackerMap.get(bloc);
 }
+/**
+* @internal
+*/
 function commitTrackedGetters(tracker) {
 	if (tracker.currentlyAccessing.size > 0) tracker.trackedGetters = new Set(tracker.currentlyAccessing);
 	tracker.currentlyAccessing.clear();
 }
+/**
+* @internal
+*/
 function createBlocProxy(bloc) {
 	const cached = blocProxyCache.get(bloc);
 	if (cached) return cached;
@@ -391,6 +458,9 @@ function createBlocProxy(bloc) {
 	blocProxyCache.set(bloc, proxy);
 	return proxy;
 }
+/**
+* @internal
+*/
 function hasGetterChanges(bloc, tracker) {
 	if (!tracker || tracker.trackedGetters.size === 0) return false;
 	tracker.renderCache.clear();
@@ -413,12 +483,21 @@ function hasGetterChanges(bloc, tracker) {
 	tracker.cacheValid = true;
 	return hasAnyChange;
 }
+/**
+* @internal
+*/
 function invalidateRenderCache(tracker) {
 	tracker.cacheValid = false;
 }
+/**
+* @internal
+*/
 function clearExternalDependencies(tracker) {
 	tracker.externalDependencies.clear();
 }
+/**
+* @internal
+*/
 function resetGetterTracker(tracker) {
 	tracker.trackedValues.clear();
 	tracker.currentlyAccessing.clear();
@@ -470,6 +549,19 @@ function isExcludedFromDevTools(Type) {
 
 //#endregion
 //#region src/core/StateContainerRegistry.ts
+/**
+* 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);
+* });
+* ```
+*/
 var StateContainerRegistry = class {
 	constructor() {
 		this.instancesByConstructor = /* @__PURE__ */ new WeakMap();
@@ -477,9 +569,19 @@ var StateContainerRegistry = class {
 		this.typeConfigs = /* @__PURE__ */ new Map();
 		this.listeners = /* @__PURE__ */ new Map();
 	}
+	/**
+	* Register a type for lifecycle event tracking
+	* @param constructor - The StateContainer class constructor
+	*/
 	registerType(constructor) {
 		this.types.add(constructor);
 	}
+	/**
+	* 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(constructor, isolated = false) {
 		const className = constructor.name;
 		if (!isolated && isIsolatedClass(constructor)) isolated = true;
@@ -732,6 +834,26 @@ function getPluginManager() {
 
 //#endregion
 //#region src/core/StateContainer.ts
+/**
+* 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);
+*   }
+* }
+* ```
+*/
 var StateContainer = class StateContainer {
 	static {
 		this.__excludeFromDevTools = false;
@@ -739,52 +861,132 @@ var StateContainer = class StateContainer {
 	static {
 		this._registry = globalRegistry;
 	}
+	/**
+	* Get the global StateContainerRegistry
+	* @returns The registry managing all state container instances
+	*/
 	static getRegistry() {
 		return StateContainer._registry;
 	}
+	/**
+	* Replace the global registry (clears existing instances)
+	* @param registry - The new registry to use
+	*/
 	static setRegistry(registry) {
 		StateContainer._registry.clearAll();
 		StateContainer._registry = registry;
 	}
+	/**
+	* Register this class with the global registry
+	* @param isolated - Whether instances should be isolated (component-scoped)
+	*/
 	static register(isolated = false) {
 		StateContainer._registry.register(this, isolated);
 	}
+	/**
+	* Resolve an instance with ref counting (ownership semantics).
+	* Creates a new instance if one doesn't exist, or returns existing and increments ref count.
+	* @template S - Optional state type override for generic StateContainers
+	* @template T - The StateContainer type (inferred from class)
+	* @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(instanceKey, constructorArgs) {
 		return StateContainer._registry.resolve(this, instanceKey, constructorArgs);
 	}
+	/**
+	* Get an existing instance without incrementing ref count (borrowing semantics).
+	* @template S - Optional state type override for generic StateContainers
+	* @template T - The StateContainer type (inferred from class)
+	* @param instanceKey - Optional instance key (defaults to 'default')
+	* @returns The state container instance
+	* @throws Error if instance doesn't exist
+	*/
 	static get(instanceKey) {
 		return StateContainer._registry.get(this, instanceKey);
 	}
+	/**
+	* Safely get an existing instance with error handling.
+	* @template S - Optional state type override for generic StateContainers
+	* @template T - The StateContainer type (inferred from class)
+	* @param instanceKey - Optional instance key (defaults to 'default')
+	* @returns Discriminated union with either the instance or an error
+	*/
 	static getSafe(instanceKey) {
 		return StateContainer._registry.getSafe(this, instanceKey);
 	}
+	/**
+	* Connect to an instance for bloc-to-bloc communication (borrowing semantics).
+	* Gets or creates instance without incrementing ref count.
+	* @template S - Optional state type override for generic StateContainers
+	* @template T - The StateContainer type (inferred from class)
+	* @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(instanceKey, constructorArgs) {
 		return StateContainer._registry.connect(this, instanceKey, constructorArgs);
 	}
+	/**
+	* 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(instanceKey, forceDispose = false) {
 		StateContainer._registry.release(this, instanceKey, forceDispose);
 	}
+	/**
+	* Get all instances of this class
+	* @returns Array of all instances
+	*/
 	static getAll() {
 		return StateContainer._registry.getAll(this);
 	}
+	/**
+	* Iterate over all instances of this class
+	* @param callback - Function to call for each instance
+	*/
 	static forEach(callback) {
 		StateContainer._registry.forEach(this, callback);
 	}
+	/**
+	* Clear all instances of this class (disposes them)
+	*/
 	static clear() {
 		StateContainer._registry.clear(this);
 	}
+	/**
+	* Clear all instances from all registered types
+	*/
 	static clearAllInstances() {
 		StateContainer._registry.clearAll();
 	}
+	/**
+	* Get registry statistics for debugging
+	* @returns Object with registeredTypes, totalInstances, and typeBreakdown
+	*/
 	static getStats() {
 		return StateContainer._registry.getStats();
 	}
+	/**
+	* 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(instanceKey) {
 		return StateContainer._registry.getRefCount(this, instanceKey);
 	}
+	/**
+	* Check if an instance exists
+	* @param instanceKey - Optional instance key (defaults to 'default')
+	* @returns true if instance exists
+	*/
 	static hasInstance(instanceKey) {
 		return StateContainer._registry.hasInstance(this, instanceKey);
 	}
+	/** Current props value passed to this container */
 	get props() {
 		return this._props;
 	}
@@ -812,6 +1014,11 @@ var StateContainer = class StateContainer {
 		};
 		this._state = initialState;
 	}
+	/**
+	* Initialize configuration for this instance.
+	* Called by the registry after construction.
+	* @param config - Configuration options
+	*/
 	initConfig(config) {
 		this.config = { ...config };
 		this.name = this.config.name || this.constructor.name;
@@ -819,17 +1026,28 @@ var StateContainer = class StateContainer {
 		this.instanceId = generateSimpleId(this.constructor.name, this.config.instanceId);
 		StateContainer._registry.emit("created", this);
 	}
+	/** Current state value */
 	get state() {
 		return this._state;
 	}
+	/** Whether this instance has been disposed */
 	get isDisposed() {
 		return this._disposed;
 	}
+	/**
+	* Subscribe to state changes
+	* @param listener - Function called when state changes
+	* @returns Unsubscribe function
+	*/
 	subscribe(listener) {
 		if (this._disposed) throw new Error(`Cannot subscribe to disposed container ${this.name}`);
 		this.listeners.add(listener);
 		return () => this.listeners.delete(listener);
 	}
+	/**
+	* Dispose this instance and clean up resources.
+	* Clears all listeners and emits the 'dispose' system event.
+	*/
 	dispose() {
 		if (this._disposed) return;
 		if (this.debug) console.log(`[${this.name}] Disposing...`);
@@ -840,6 +1058,11 @@ var StateContainer = class StateContainer {
 		StateContainer._registry.emit("disposed", this);
 		if (this.debug) console.log(`[${this.name}] Disposed successfully`);
 	}
+	/**
+	* Emit a new state value and notify all listeners.
+	* @param newState - The new state value
+	* @protected
+	*/
 	emit(newState) {
 		if (this._disposed) throw new Error(`Cannot emit state from disposed container ${this.name}`);
 		if (this._state === newState) return;
@@ -899,6 +1122,11 @@ var StateContainer = class StateContainer {
 		if (segments.length > 3) path = segments.slice(-3).join("/");
 		return path;
 	}
+	/**
+	* Update state using a transform function.
+	* @param updater - Function that receives current state and returns new state
+	* @protected
+	*/
 	update(updater) {
 		if (this._disposed) throw new Error(`Cannot update state from disposed container ${this.name}`);
 		this.emit(updater(this._state));
@@ -912,6 +1140,11 @@ var StateContainer = class StateContainer {
 			console.error(`[${this.name}] Error in system event handler:`, error$1);
 		}
 	}
+	/**
+	* Update the props for this container.
+	* Emits the 'propsUpdated' system event.
+	* @param newProps - The new props value
+	*/
 	updateProps(newProps) {
 		if (this._disposed) throw new Error(`Cannot update props on disposed container ${this.name}`);
 		const previousProps = this._props;
@@ -929,6 +1162,13 @@ var StateContainer = class StateContainer {
 
 //#endregion
 //#region src/core/Cubit.ts
+/**
+* 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)
+*/
 var Cubit = class extends StateContainer {
 	constructor(initialState) {
 		super(initialState);
@@ -940,89 +1180,32 @@ var Cubit = class extends StateContainer {
 			}));
 		});
 	}
+	/**
+	* Replace state with a new value and notify all listeners
+	* @param newState - The new state value
+	*/
 	emit(newState) {
 		super["emit"](newState);
 	}
+	/**
+	* 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) {
 		super["update"](updater);
 	}
 };
-var CounterCubit = class extends Cubit {
-	constructor() {
-		super(0);
-		this.increment = () => {
-			this.emit(this.state + 1);
-		};
-		this.decrement = () => {
-			this.emit(this.state - 1);
-		};
-		this.reset = () => {
-			this.emit(0);
-		};
-		this.addAmount = (amount) => {
-			this.emit(this.state + amount);
-		};
-	}
-};
-var TodoCubit = class extends Cubit {
-	static {
-		this.keepAlive = true;
-	}
-	constructor() {
-		super({
-			todos: [],
-			filter: "all",
-			isLoading: false
-		});
-		this.nextId = 0;
-		this.addTodo = (text) => {
-			this.update((state) => ({
-				...state,
-				todos: [...state.todos, {
-					id: `todo-${Date.now()}-${this.nextId++}`,
-					text,
-					done: false
-				}]
-			}));
-		};
-		this.toggleTodo = (id) => {
-			this.update((state) => ({
-				...state,
-				todos: state.todos.map((todo) => todo.id === id ? {
-					...todo,
-					done: !todo.done
-				} : todo)
-			}));
-		};
-		this.removeTodo = (id) => {
-			this.update((state) => ({
-				...state,
-				todos: state.todos.filter((todo) => todo.id !== id)
-			}));
-		};
-		this.setFilter = (filter) => {
-			this.patch({ filter });
-		};
-		this.setLoading = (isLoading) => {
-			this.patch({ isLoading });
-		};
-	}
-	get visibleTodos() {
-		const todos = this.state.todos;
-		switch (this.state.filter) {
-			case "active": return todos.filter((t) => !t.done);
-			case "completed": return todos.filter((t) => t.done);
-			case "all":
-			default: return todos;
-		}
-	}
-	get activeTodoCount() {
-		return this.state.todos.filter((t) => !t.done).length;
-	}
-};
 
 //#endregion
 //#region src/core/Vertex.ts
+/**
+* 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)
+*/
 var Vertex = class extends StateContainer {
 	constructor(initialState) {
 		super(initialState);
@@ -1076,122 +1259,22 @@ var Vertex = class extends StateContainer {
 			this.onEventError(event, error$1);
 		}
 	}
+	/**
+	* 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
+	*/
 	onEventError(_event, _error) {}
 };
-/**
-* Example: Counter Events
-*/
-var IncrementEvent = class {
-	constructor(amount = 1) {
-		this.amount = amount;
-		this.type = "increment";
-		this.timestamp = Date.now();
-	}
-};
-var DecrementEvent = class {
-	constructor(amount = 1) {
-		this.amount = amount;
-		this.type = "decrement";
-		this.timestamp = Date.now();
-	}
-};
-var ResetEvent = class {
-	constructor() {
-		this.type = "reset";
-		this.timestamp = Date.now();
-	}
-};
-/**
-* Example: Counter Vertex
-* Demonstrates proper typing and event handling
-*/
-var CounterVertex = class extends Vertex {
-	constructor() {
-		super(0);
-		this.increment = (amount = 1) => {
-			this.add(new IncrementEvent(amount));
-		};
-		this.decrement = (amount = 1) => {
-			this.add(new DecrementEvent(amount));
-		};
-		this.reset = () => {
-			this.add(new ResetEvent());
-		};
-		this.on(IncrementEvent, (event, emit) => {
-			emit(this.state + event.amount);
-		});
-		this.on(DecrementEvent, (event, emit) => {
-			emit(this.state - event.amount);
-		});
-		this.on(ResetEvent, (_, emit) => {
-			emit(0);
-		});
-	}
-};
-var LoginEvent = class {
-	constructor(email, password) {
-		this.email = email;
-		this.password = password;
-		this.type = "login";
-		this.timestamp = Date.now();
-	}
-};
-var LogoutEvent = class {
-	constructor() {
-		this.type = "logout";
-		this.timestamp = Date.now();
-	}
-};
-var AuthVertex = class extends Vertex {
-	constructor() {
-		super({
-			isAuthenticated: false,
-			isLoading: false,
-			user: null,
-			error: null
-		});
-		this.login = (email, password) => {
-			this.add(new LoginEvent(email, password));
-		};
-		this.logout = () => {
-			this.add(new LogoutEvent());
-		};
-		this.on(LoginEvent, (event, emit) => {
-			emit({
-				...this.state,
-				isLoading: true,
-				error: null
-			});
-			if (event.email === "user@example.com" && event.password === "password") emit({
-				isAuthenticated: true,
-				isLoading: false,
-				user: {
-					id: "123",
-					name: "Test User",
-					email: "user@example.com"
-				},
-				error: null
-			});
-			else emit({
-				isAuthenticated: false,
-				isLoading: false,
-				user: null,
-				error: "Invalid credentials"
-			});
-		});
-		this.on(LogoutEvent, (_, emit) => {
-			emit({
-				isAuthenticated: false,
-				isLoading: false,
-				user: null,
-				error: null
-			});
-		});
-	}
-};
 
 //#endregion
 //#region src/plugin/BlacPlugin.ts
+/**
+* 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
+*/
 function hasInitHook(plugin) {
 	return typeof plugin.onInstall === "function";
 }
@@ -1204,12 +1287,16 @@ function hasInitHook(plugin) {
 * This module provides a functional approach to proxy-based dependency tracking.
 * Unlike the class-based ProxyTracker, this uses a state object pattern that's
 * easier to integrate with functional programming patterns and framework hooks.
+*
+* @internal
 */
 /**
 * Check if a value can be proxied
 *
 * Returns true for plain objects and arrays only.
 * Excludes built-in objects like Date, Map, Set, etc.
+*
+* @internal
 */
 function isProxyable(value) {
 	if (typeof value !== "object" || value === null) return false;
@@ -1225,6 +1312,8 @@ function isProxyable(value) {
 * const proxy = createProxyForTarget(state, myObject);
 * // ... use proxy ...
 * const paths = stopProxyTracking(state);
+*
+* @internal
 */
 function createProxyTrackerState() {
 	return {
@@ -1241,6 +1330,8 @@ function createProxyTrackerState() {
 * Start tracking property accesses
 *
 * Clears previous tracked paths and enables tracking mode.
+*
+* @internal
 */
 function startProxyTracking(state) {
 	state.isTracking = true;
@@ -1250,6 +1341,8 @@ function startProxyTracking(state) {
 * Stop tracking and return the tracked paths
 *
 * Returns a new Set containing all tracked paths.
+*
+* @internal
 */
 function stopProxyTracking(state) {
 	state.isTracking = false;
@@ -1262,6 +1355,8 @@ function stopProxyTracking(state) {
 * - Array element access (arr[0])
 * - Length access (arr.length)
 * - Array method calls (arr.map, arr.filter, etc.)
+*
+* @internal
 */
 function createArrayProxy(state, target, path, depth = 0) {
 	const proxy = new Proxy(target, { get: (arr, prop) => {
@@ -1306,6 +1401,8 @@ function createArrayProxy(state, target, path, depth = 0) {
 * - Nested property access (obj.nested.prop)
 * - 'in' operator usage ('prop' in obj)
 * - Object.keys, Object.entries, etc.
+*
+* @internal
 */
 function createProxyInternal(state, target, path = "", depth = 0) {
 	if (!state.isTracking || !isProxyable(target)) return target;
@@ -1353,6 +1450,8 @@ function createProxyInternal(state, target, path = "", depth = 0) {
 * Otherwise, creates a new proxy and caches it.
 *
 * This is the main entry point for creating tracked proxies.
+*
+* @internal
 */
 function createProxyForTarget(state, target) {
 	if (state.lastProxiedState === target && state.lastProxy) return state.lastProxy;
@@ -1371,16 +1470,22 @@ function createProxyForTarget(state, target) {
 *
 * Provides utilities for parsing property paths and extracting values
 * from nested objects using path strings.
+*
+* @internal
 */
 /**
 * Parse a property path string into an array of segments
 *
+* @internal
+*
 * Handles both dot notation (a.b.c) and bracket notation (a[0].b)
 *
 * @example
+* ```ts
 * parsePath('user.name') // ['user', 'name']
 * parsePath('items[0].name') // ['items', '0', 'name']
 * parsePath('data.users[2].address.city') // ['data', 'users', '2', 'address', 'city']
+* ```
 */
 function parsePath(path) {
 	const segments = [];
@@ -1408,10 +1513,14 @@ function parsePath(path) {
 * Get a value from an object using a path of segments
 *
 * @example
+* ```ts
 * const obj = { user: { name: 'Alice', age: 30 } }
 * getValueAtPath(obj, ['user', 'name']) // 'Alice'
 * getValueAtPath(obj, ['user', 'age']) // 30
 * getValueAtPath(obj, ['user', 'missing']) // undefined
+* ```
+*
+* @internal
 */
 function getValueAtPath(obj, segments) {
 	if (obj == null) return void 0;
@@ -1428,9 +1537,13 @@ function getValueAtPath(obj, segments) {
 * Compares two arrays element-by-element using Object.is
 *
 * @example
+* ```ts
 * shallowEqual([1, 2, 3], [1, 2, 3]) // true
 * shallowEqual([1, 2, 3], [1, 2, 4]) // false
 * shallowEqual([1, 2], [1, 2, 3]) // false
+* ```
+*
+* @internal
 */
 function shallowEqual(arr1, arr2) {
 	if (arr1.length !== arr2.length) return false;
@@ -1458,6 +1571,9 @@ function getArrayParentPath(path) {
 	if (arrayIndexMatch) return arrayIndexMatch[1];
 	return null;
 }
+/**
+* @internal
+*/
 function optimizeTrackedPaths(paths) {
 	if (paths.size === 0) return /* @__PURE__ */ new Set();
 	if (paths.size === 1) return new Set(paths);
@@ -1479,6 +1595,9 @@ function optimizeTrackedPaths(paths) {
 	for (const arrayParent of arrayParents) optimized.add(arrayParent);
 	return optimized;
 }
+/**
+* @internal
+*/
 function createTrackerState() {
 	return {
 		proxyTrackerState: createProxyTrackerState(),
@@ -1489,12 +1608,21 @@ function createTrackerState() {
 		lastCheckedValues: /* @__PURE__ */ new Map()
 	};
 }
+/**
+* @internal
+*/
 function startTracking(tracker) {
 	startProxyTracking(tracker.proxyTrackerState);
 }
+/**
+* @internal
+*/
 function createProxy(tracker, state) {
 	return createProxyForTarget(tracker.proxyTrackerState, state);
 }
+/**
+* @internal
+*/
 function captureTrackedPaths(tracker, state) {
 	tracker.previousRenderPaths = tracker.currentRenderPaths;
 	tracker.currentRenderPaths = optimizeTrackedPaths(stopProxyTracking(tracker.proxyTrackerState));
@@ -1515,6 +1643,9 @@ function captureTrackedPaths(tracker, state) {
 	}
 	tracker.lastCheckedValues.clear();
 }
+/**
+* @internal
+*/
 function hasChanges(tracker, state) {
 	if (tracker.pathCache.size === 0) return true;
 	tracker.lastCheckedValues.clear();
@@ -1529,12 +1660,20 @@ function hasChanges(tracker, state) {
 	tracker.lastCheckedState = state;
 	return false;
 }
+/**
+* @internal
+*/
 function hasTrackedData(tracker) {
 	return tracker.proxyTrackerState.trackedPaths.size > 0 || tracker.pathCache.size > 0 || tracker.previousRenderPaths.size > 0;
 }
 
 //#endregion
 //#region src/adapter/framework-adapter.ts
+/**
+* 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.
+*/
 var ExternalDependencyManager = class {
 	constructor() {
 		this.subscriptions = [];
@@ -1545,6 +1684,14 @@ var ExternalDependencyManager = class {
 		for (const dep of newDeps) if (!oldDeps.has(dep)) return false;
 		return true;
 	}
+	/**
+	* 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, rawInstance, onGetterChange) {
 		if (!getterTracker?.externalDependencies) return false;
 		const currentDeps = getterTracker.externalDependencies;
@@ -1565,11 +1712,21 @@ var ExternalDependencyManager = class {
 		clearExternalDependencies(getterTracker);
 		return true;
 	}
+	/**
+	* Clean up all active subscriptions
+	*/
 	cleanup() {
 		this.subscriptions.forEach((unsub) => unsub());
 		this.subscriptions = [];
 	}
 };
+/**
+* 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
+*/
 function createAutoTrackSubscribe(instance, adapterState) {
 	return (callback) => {
 		return instance.subscribe(() => {
@@ -1588,6 +1745,14 @@ function createAutoTrackSubscribe(instance, adapterState) {
 		});
 	};
 }
+/**
+* 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
+*/
 function createManualDepsSubscribe(instance, adapterState, config) {
 	return (callback) => {
 		return instance.subscribe(() => {
@@ -1599,9 +1764,22 @@ function createManualDepsSubscribe(instance, adapterState, config) {
 		});
 	};
 }
+/**
+* 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
+*/
 function createNoTrackSubscribe(instance) {
 	return (callback) => instance.subscribe(callback);
 }
+/**
+* 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
+*/
 function createAutoTrackSnapshot(instance, adapterState) {
 	return () => {
 		const tracker = adapterState.tracker || (adapterState.tracker = createTrackerState());
@@ -1616,15 +1794,35 @@ function createAutoTrackSnapshot(instance, adapterState) {
 		return createProxy(tracker, instance.state);
 	};
 }
+/**
+* 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
+*/
 function createManualDepsSnapshot(instance, adapterState, config) {
 	return () => {
 		adapterState.manualDepsCache = config.dependencies(instance.state, instance);
 		return instance.state;
 	};
 }
+/**
+* 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
+*/
 function createNoTrackSnapshot(instance) {
 	return () => instance.state;
 }
+/**
+* Initialize adapter state for auto-tracking mode.
+* Creates getter tracker and proxied bloc instance.
+* @param instance - The state container instance
+* @returns Initialized adapter state
+*/
 function initAutoTrackState(instance) {
 	return {
 		tracker: null,
@@ -1633,6 +1831,12 @@ function initAutoTrackState(instance) {
 		proxiedBloc: createBlocProxy(instance)
 	};
 }
+/**
+* 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
+*/
 function initManualDepsState(instance) {
 	return {
 		tracker: null,
@@ -1641,6 +1845,12 @@ function initManualDepsState(instance) {
 		proxiedBloc: instance
 	};
 }
+/**
+* Initialize adapter state for no-tracking mode.
+* No tracking or proxy is created.
+* @param instance - The state container instance
+* @returns Initialized adapter state
+*/
 function initNoTrackState(instance) {
 	return {
 		tracker: null,
@@ -1649,6 +1859,12 @@ function initNoTrackState(instance) {
 		proxiedBloc: instance
 	};
 }
+/**
+* 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
+*/
 function disableGetterTracking(adapterState, rawInstance) {
 	if (adapterState.getterTracker) {
 		adapterState.getterTracker.isTracking = false;
@@ -1658,10 +1874,17 @@ function disableGetterTracking(adapterState, rawInstance) {
 
 //#endregion
 //#region src/logging/Logger.ts
+/**
+* Log severity levels (lower number = higher severity)
+*/
 let LogLevel = /* @__PURE__ */ function(LogLevel$1) {
+	/** Critical errors that may cause application failure */
 	LogLevel$1[LogLevel$1["ERROR"] = 0] = "ERROR";
+	/** Warning conditions that should be addressed */
 	LogLevel$1[LogLevel$1["WARN"] = 1] = "WARN";
+	/** Informational messages about application state */
 	LogLevel$1[LogLevel$1["INFO"] = 2] = "INFO";
+	/** Detailed debugging information */
 	LogLevel$1[LogLevel$1["DEBUG"] = 3] = "DEBUG";
 	return LogLevel$1;
 }({});
@@ -1730,9 +1953,33 @@ let currentConfig = {
 	output: (entry) => console.log(JSON.stringify(entry))
 };
 let defaultLogger = createLogger(currentConfig);
+/**
+* Log a debug message (tree-shakeable export)
+* @param context - Context identifier (module or component name)
+* @param message - Log message
+* @param data - Optional structured data
+*/
 const debug = (context, message, data) => defaultLogger.debug(context, message, data);
+/**
+* Log an info message (tree-shakeable export)
+* @param context - Context identifier (module or component name)
+* @param message - Log message
+* @param data - Optional structured data
+*/
 const info = (context, message, data) => defaultLogger.info(context, message, data);
+/**
+* Log a warning message (tree-shakeable export)
+* @param context - Context identifier (module or component name)
+* @param message - Log message
+* @param data - Optional structured data
+*/
 const warn = (context, message, data) => defaultLogger.warn(context, message, data);
+/**
+* Log an error message (tree-shakeable export)
+* @param context - Context identifier (module or component name)
+* @param message - Log message
+* @param data - Optional structured data
+*/
 const error = (context, message, data) => defaultLogger.error(context, message, data);
 /**
 * Configuration function that recreates the default logger
@@ -1758,7 +2005,7 @@ function configureLogger(opts) {
 * Decorator to configure StateContainer classes.
 *
 * @example Decorator syntax (requires experimentalDecorators or TC39 decorators)
-* ```typescript
+* ```ts
 * @blac({ isolated: true })
 * class FormBloc extends Cubit<FormState> {}
 *
@@ -1770,7 +2017,7 @@ function configureLogger(opts) {
 * ```
 *
 * @example Function syntax (no decorator support needed)
-* ```typescript
+* ```ts
 * const FormBloc = blac({ isolated: true })(
 *   class extends Cubit<FormState> {}
 * );
@@ -1786,5 +2033,5 @@ function blac(options) {
 }
 
 //#endregion
-export { AuthVertex, BLAC_DEFAULTS, BLAC_ERROR_PREFIX, BLAC_ID_PATTERNS, BLAC_STATIC_PROPS, CounterCubit, CounterVertex, Cubit, DecrementEvent, ExternalDependencyManager, IncrementEvent, LogLevel, LoginEvent, LogoutEvent, PluginManager, ResetEvent, StateContainer, StateContainerRegistry, TodoCubit, Vertex, __resetIdCounters, blac, captureTrackedPaths, clearActiveTracker, clearExternalDependencies, commitTrackedGetters, configureLogger, createArrayProxy, createAutoTrackSnapshot, createAutoTrackSubscribe, createBlocProxy, createGetterTracker, createIdGenerator, createLogger, createManualDepsSnapshot, createManualDepsSubscribe, createNoTrackSnapshot, createNoTrackSubscribe, createPluginManager, createProxy, createProxyForTarget, createProxyInternal, createProxyTrackerState, createTrackerState, debug, disableGetterTracking, error, generateId, generateIsolatedKey, generateSimpleId, getActiveTracker, getDescriptor, getGetterExecutionContext, getPluginManager, getStaticProp, getValueAtPath, globalRegistry, hasChanges, hasGetterChanges, hasInitHook, hasTrackedData, info, initAutoTrackState, initManualDepsState, initNoTrackState, invalidateRenderCache, isExcludedFromDevTools, isGetter, isIsolatedClass, isIsolatedKey, isKeepAliveClass, isProxyable, parsePath, resetGetterTracker, setActiveTracker, shallowEqual, startProxyTracking, startTracking, stopProxyTracking, warn };
+export { BLAC_DEFAULTS, BLAC_ERROR_PREFIX, BLAC_ID_PATTERNS, BLAC_STATIC_PROPS, Cubit, ExternalDependencyManager, LogLevel, PluginManager, StateContainer, StateContainerRegistry, Vertex, __resetIdCounters, blac, captureTrackedPaths, clearActiveTracker, clearExternalDependencies, commitTrackedGetters, configureLogger, createArrayProxy, createAutoTrackSnapshot, createAutoTrackSubscribe, createBlocProxy, createGetterTracker, createIdGenerator, createLogger, createManualDepsSnapshot, createManualDepsSubscribe, createNoTrackSnapshot, createNoTrackSubscribe, createPluginManager, createProxy, createProxyForTarget, createProxyInternal, createProxyTrackerState, createTrackerState, debug, disableGetterTracking, error, generateId, generateIsolatedKey, generateSimpleId, getActiveTracker, getDescriptor, getGetterExecutionContext, getPluginManager, getStaticProp, getValueAtPath, globalRegistry, hasChanges, hasGetterChanges, hasInitHook, hasTrackedData, info, initAutoTrackState, initManualDepsState, initNoTrackState, invalidateRenderCache, isExcludedFromDevTools, isGetter, isIsolatedClass, isIsolatedKey, isKeepAliveClass, isProxyable, parsePath, resetGetterTracker, setActiveTracker, shallowEqual, startProxyTracking, startTracking, stopProxyTracking, warn };
 //# sourceMappingURL=index.js.map