@blac/core 2.0.0-rc.6 → 2.0.0-rc.9

package/dist/index.js

@@ -15,15 +15,15 @@ const globalCounters = /* @__PURE__ */ new Map();
 * @example
 * ```ts
 * const generator = createIdGenerator('sub');
-* const id1 = generator.next(); // "sub_1698765432100_1_a3k9d7f2q"
-* const id2 = generator.next(); // "sub_1698765432101_2_b4n8e9g3r"
+* const id1 = generator.next(); // "sub:1698765432100_1_a3k9d7f2q"
+* const id2 = generator.next(); // "sub:1698765432101_2_b4n8e9g3r"
 * ```
 */
 function createIdGenerator(prefix) {
 	let counter = 0;
 	return {
-		next: () => `${prefix}_${Date.now()}_${++counter}_${Math.random().toString(36).substring(2, 11)}`,
-		nextSimple: () => `${prefix}_${++counter}`,
+		next: () => `${prefix}:${Date.now()}_${++counter}_${Math.random().toString(36).substring(2, 11)}`,
+		nextSimple: () => `${prefix}:${++counter}`,
 		reset: () => {
 			counter = 0;
 		}
@@ -32,7 +32,7 @@ function createIdGenerator(prefix) {
 /**
 * Generate ID with timestamp, counter, and random suffix (tree-shakeable)
 *
-* Format: `${prefix}_${timestamp}_${counter}_${random}`
+* Format: `${prefix}:${timestamp}_${counter}_${random}`
 *
 * @param prefix - Prefix for the ID (e.g., 'sub', 'consumer', 'stage')
 * @returns Branded ID string
@@ -40,18 +40,18 @@ function createIdGenerator(prefix) {
 * @example
 * ```ts
 * const id = generateId('sub');
-* // Returns: "sub_1698765432100_1_a3k9d7f2q"
+* // Returns: "sub:1698765432100_1_a3k9d7f2q"
 * ```
 */
 function generateId(prefix) {
 	const counter = (globalCounters.get(prefix) ?? 0) + 1;
 	globalCounters.set(prefix, counter);
-	return `${prefix}_${Date.now()}_${counter}_${Math.random().toString(36).substring(2, 11)}`;
+	return `${prefix}:${Date.now()}_${counter}_${Math.random().toString(36).substring(2, 11)}`;
 }
 /**
 * Generate simple ID with timestamp and random (no counter tracking)
 *
-* Format: `${prefix}_${timestamp}_${random}`
+* Format: `${prefix}:${timestamp}_${random}`
 *
 * @param prefix - Prefix for the ID
 * @returns Branded ID string
@@ -59,11 +59,12 @@ function generateId(prefix) {
 * @example
 * ```ts
 * const id = generateSimpleId('CounterBloc');
-* // Returns: "CounterBloc_1698765432100_a3k9d7f2q"
+* // Returns: "CounterBloc:1698765432100_a3k9d7f2q"
 * ```
 */
-function generateSimpleId(prefix) {
-	return `${prefix}_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+function generateSimpleId(prefix, affix) {
+	if (affix) return `${prefix}:${affix}`;
+	return `${prefix}:${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
 }
 /**
 * Reset all counters for testing purposes
@@ -72,129 +73,656 @@ function generateSimpleId(prefix) {
 function __resetIdCounters() {
 	globalCounters.clear();
 }
+/**
+* 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
+*/
+function generateIsolatedKey() {
+	return `isolated-${Math.random().toString(36).slice(2, 11)}`;
+}
+/**
+* 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
+*/
+function isIsolatedKey(key) {
+	return key.startsWith("isolated-");
+}
+
+//#endregion
+//#region src/plugin/PluginManager.ts
+/**
+* Plugin manager for registering and coordinating plugins
+*/
+var PluginManager = class {
+	constructor(registry) {
+		this.plugins = /* @__PURE__ */ new Map();
+		this.registry = registry;
+		this.setupLifecycleHooks();
+	}
+	/**
+	* Install a plugin
+	*/
+	install(plugin, config = {}) {
+		const effectiveConfig = {
+			enabled: true,
+			environment: "all",
+			...config
+		};
+		if (!this.shouldEnablePlugin(effectiveConfig)) {
+			console.log(`[BlaC] Plugin "${plugin.name}" skipped (environment mismatch)`);
+			return;
+		}
+		if (this.plugins.has(plugin.name)) throw new Error(`Plugin "${plugin.name}" is already installed`);
+		const context = this.createPluginContext();
+		this.plugins.set(plugin.name, {
+			plugin,
+			config: effectiveConfig,
+			context
+		});
+		if (plugin.onInstall) try {
+			plugin.onInstall(context);
+		} catch (error$1) {
+			console.error(`[BlaC] Error installing plugin "${plugin.name}":`, error$1);
+			this.plugins.delete(plugin.name);
+			throw error$1;
+		}
+		console.log(`[BlaC] Plugin "${plugin.name}" v${plugin.version} installed`);
+	}
+	/**
+	* Uninstall a plugin
+	*/
+	uninstall(pluginName) {
+		const installed = this.plugins.get(pluginName);
+		if (!installed) throw new Error(`Plugin "${pluginName}" is not installed`);
+		if (installed.plugin.onUninstall) try {
+			installed.plugin.onUninstall();
+		} catch (error$1) {
+			console.error(`[BlaC] Error uninstalling plugin "${pluginName}":`, error$1);
+		}
+		this.plugins.delete(pluginName);
+		console.log(`[BlaC] Plugin "${pluginName}" uninstalled`);
+	}
+	/**
+	* Get installed plugin
+	*/
+	getPlugin(pluginName) {
+		return this.plugins.get(pluginName)?.plugin;
+	}
+	/**
+	* Get all installed plugins
+	*/
+	getAllPlugins() {
+		return Array.from(this.plugins.values()).map((p) => p.plugin);
+	}
+	/**
+	* Check if plugin is installed
+	*/
+	hasPlugin(pluginName) {
+		return this.plugins.has(pluginName);
+	}
+	/**
+	* Clear all plugins (for testing)
+	*/
+	clear() {
+		for (const name of this.plugins.keys()) this.uninstall(name);
+	}
+	/**
+	* Setup lifecycle hooks to notify plugins
+	*/
+	setupLifecycleHooks() {
+		this.registry.on("created", (instance) => {
+			this.notifyPlugins("onInstanceCreated", instance);
+		});
+		this.registry.on("stateChanged", (instance, previousState, currentState, callstack) => {
+			this.notifyPlugins("onStateChanged", instance, previousState, currentState, callstack);
+		});
+		this.registry.on("eventAdded", (vertex, event) => {
+			this.notifyPlugins("onEventAdded", vertex, event);
+		});
+		this.registry.on("disposed", (instance) => {
+			this.notifyPlugins("onInstanceDisposed", instance);
+		});
+	}
+	/**
+	* Notify all plugins of a lifecycle event
+	*/
+	notifyPlugins(hookName, ...args) {
+		for (const { plugin, config, context } of this.plugins.values()) {
+			if (!config.enabled) continue;
+			const hook = plugin[hookName];
+			if (typeof hook === "function") try {
+				hook.apply(plugin, [...args, context]);
+			} catch (error$1) {
+				console.error(`[BlaC] Error in plugin "${plugin.name}" ${hookName}:`, error$1);
+			}
+		}
+	}
+	/**
+	* Create plugin context with safe API access
+	*/
+	createPluginContext() {
+		return {
+			getInstanceMetadata: (instance) => {
+				return {
+					id: instance.instanceId,
+					className: instance.constructor.name,
+					isDisposed: instance.isDisposed,
+					name: instance.name,
+					lastStateChangeTimestamp: instance.lastUpdateTimestamp,
+					createdAt: instance.createdAt,
+					state: instance.state,
+					isIsolated: instance.instanceId.startsWith("isolated-")
+				};
+			},
+			getState: (instance) => {
+				return instance.state;
+			},
+			queryInstances: (typeClass) => {
+				return typeClass.getAll();
+			},
+			getAllTypes: () => {
+				return this.registry.getTypes();
+			},
+			getStats: () => {
+				return this.registry.getStats();
+			}
+		};
+	}
+	/**
+	* Check if plugin should be enabled based on environment
+	*/
+	shouldEnablePlugin(config) {
+		if (!config.enabled) return false;
+		if (config.environment === "all") return true;
+		return this.getCurrentEnvironment() === config.environment;
+	}
+	/**
+	* Get current environment
+	*/
+	getCurrentEnvironment() {
+		if (typeof process !== "undefined") {
+			if (process.env.NODE_ENV === "test") return "test";
+			if (process.env.NODE_ENV === "production") return "production";
+			return "development";
+		}
+		return "development";
+	}
+};
+/**
+* Create a plugin manager instance
+*/
+function createPluginManager(registry) {
+	return new PluginManager(registry);
+}
+
+//#endregion
+//#region src/constants.ts
+/**
+* Default configuration constants for BlaC
+*
+* Centralized location for all magic numbers and default values.
+*/
+/**
+* Default configuration constants for BlaC
+*/
+const BLAC_DEFAULTS = {
+	DEFAULT_INSTANCE_KEY: "default",
+	MAX_GETTER_DEPTH: 10,
+	CLEANUP_INTERVAL_MS: 3e4,
+	WEAKREF_CLEANUP_INTERVAL_MS: 1e4,
+	MAX_SUBSCRIPTIONS: 1e3,
+	MAX_SUBSCRIPTIONS_HIGH_PERF: 1e4,
+	PIPELINE_TIMEOUT_MS: 5e3,
+	CLEANUP_INTERVAL_HIGH_PERF_MS: 5e3,
+	MAX_PIPELINE_STAGES: 30
+};
+/**
+* Static property names for StateContainer classes
+* Used for feature flags and configuration on bloc classes
+*/
+const BLAC_STATIC_PROPS = {
+	ISOLATED: "isolated",
+	KEEP_ALIVE: "keepAlive",
+	EXCLUDE_FROM_DEVTOOLS: "__excludeFromDevTools"
+};
+/**
+* ID generation patterns and constants
+*/
+const BLAC_ID_PATTERNS = {
+	ISOLATED_PREFIX: "isolated-",
+	ID_LENGTH: 9
+};
+/**
+* Standard error message prefix
+*/
+const BLAC_ERROR_PREFIX = "[BlaC]";
+
+//#endregion
+//#region src/tracking/getter-tracker.ts
+const descriptorCache = /* @__PURE__ */ new WeakMap();
+const blocProxyCache = /* @__PURE__ */ new WeakMap();
+const activeTrackerMap = /* @__PURE__ */ new WeakMap();
+const getterExecutionContext = {
+	tracker: null,
+	currentBloc: null,
+	depth: 0,
+	visitedBlocs: /* @__PURE__ */ new Set()
+};
+const MAX_GETTER_DEPTH = BLAC_DEFAULTS.MAX_GETTER_DEPTH;
+function getGetterExecutionContext() {
+	return getterExecutionContext;
+}
+function getDescriptor(obj, prop) {
+	const constructor = obj.constructor;
+	let constructorCache = descriptorCache.get(constructor);
+	if (constructorCache?.has(prop)) return constructorCache.get(prop);
+	let current = obj;
+	let descriptor;
+	while (current && current !== Object.prototype) {
+		descriptor = Object.getOwnPropertyDescriptor(current, prop);
+		if (descriptor) break;
+		current = Object.getPrototypeOf(current);
+	}
+	if (!constructorCache) {
+		constructorCache = /* @__PURE__ */ new Map();
+		descriptorCache.set(constructor, constructorCache);
+	}
+	constructorCache.set(prop, descriptor);
+	return descriptor;
+}
+function isGetter(obj, prop) {
+	return getDescriptor(obj, prop)?.get !== void 0;
+}
+function createGetterTracker() {
+	return {
+		trackedValues: /* @__PURE__ */ new Map(),
+		currentlyAccessing: /* @__PURE__ */ new Set(),
+		trackedGetters: /* @__PURE__ */ new Set(),
+		isTracking: false,
+		renderCache: /* @__PURE__ */ new Map(),
+		cacheValid: false,
+		externalDependencies: /* @__PURE__ */ new Set()
+	};
+}
+function setActiveTracker(bloc, tracker) {
+	activeTrackerMap.set(bloc, tracker);
+}
+function clearActiveTracker(bloc) {
+	activeTrackerMap.delete(bloc);
+}
+function getActiveTracker(bloc) {
+	return activeTrackerMap.get(bloc);
+}
+function commitTrackedGetters(tracker) {
+	if (tracker.currentlyAccessing.size > 0) tracker.trackedGetters = new Set(tracker.currentlyAccessing);
+	tracker.currentlyAccessing.clear();
+}
+function createBlocProxy(bloc) {
+	const cached = blocProxyCache.get(bloc);
+	if (cached) return cached;
+	const proxy = new Proxy(bloc, { get(target, prop, receiver) {
+		const tracker = activeTrackerMap.get(target);
+		if (tracker?.isTracking && isGetter(target, prop)) {
+			tracker.currentlyAccessing.add(prop);
+			if (tracker.cacheValid && tracker.renderCache.has(prop)) {
+				const cachedValue = tracker.renderCache.get(prop);
+				tracker.trackedValues.set(prop, cachedValue);
+				return cachedValue;
+			}
+			if (getterExecutionContext.depth >= MAX_GETTER_DEPTH) {
+				console.warn(`${BLAC_ERROR_PREFIX} Maximum getter depth (${MAX_GETTER_DEPTH}) exceeded. Possible circular dependency in getter "${String(prop)}" on ${target.constructor.name}. Returning undefined to prevent stack overflow.`);
+				return;
+			}
+			if (getterExecutionContext.visitedBlocs.has(target)) {
+				console.warn(`${BLAC_ERROR_PREFIX} Circular dependency detected: getter "${String(prop)}" on ${target.constructor.name} is calling back into itself. Returning undefined to prevent infinite recursion.`);
+				return;
+			}
+			const prevContext = {
+				tracker: getterExecutionContext.tracker,
+				currentBloc: getterExecutionContext.currentBloc,
+				depth: getterExecutionContext.depth,
+				visitedBlocs: new Set(getterExecutionContext.visitedBlocs)
+			};
+			getterExecutionContext.tracker = tracker;
+			getterExecutionContext.currentBloc = target;
+			getterExecutionContext.depth++;
+			getterExecutionContext.visitedBlocs.add(target);
+			try {
+				const value = getDescriptor(target, prop).get.call(target);
+				tracker.trackedValues.set(prop, value);
+				return value;
+			} catch (error$1) {
+				tracker.currentlyAccessing.delete(prop);
+				throw error$1;
+			} finally {
+				getterExecutionContext.tracker = prevContext.tracker;
+				getterExecutionContext.currentBloc = prevContext.currentBloc;
+				getterExecutionContext.depth = prevContext.depth;
+				getterExecutionContext.visitedBlocs = prevContext.visitedBlocs;
+			}
+		}
+		return Reflect.get(target, prop, receiver);
+	} });
+	blocProxyCache.set(bloc, proxy);
+	return proxy;
+}
+function hasGetterChanges(bloc, tracker) {
+	if (!tracker || tracker.trackedGetters.size === 0) return false;
+	tracker.renderCache.clear();
+	let hasAnyChange = false;
+	for (const prop of tracker.trackedGetters) try {
+		const descriptor = getDescriptor(bloc, prop);
+		if (!descriptor?.get) continue;
+		const newValue = descriptor.get.call(bloc);
+		const oldValue = tracker.trackedValues.get(prop);
+		tracker.renderCache.set(prop, newValue);
+		tracker.trackedValues.set(prop, newValue);
+		if (!Object.is(newValue, oldValue)) hasAnyChange = true;
+	} catch (error$1) {
+		console.warn(`${BLAC_ERROR_PREFIX} Getter "${String(prop)}" threw error during change detection. Stopping tracking for this getter.`, error$1);
+		tracker.trackedGetters.delete(prop);
+		tracker.trackedValues.delete(prop);
+		tracker.cacheValid = false;
+		return true;
+	}
+	tracker.cacheValid = true;
+	return hasAnyChange;
+}
+function invalidateRenderCache(tracker) {
+	tracker.cacheValid = false;
+}
+function clearExternalDependencies(tracker) {
+	tracker.externalDependencies.clear();
+}
+function resetGetterTracker(tracker) {
+	tracker.trackedValues.clear();
+	tracker.currentlyAccessing.clear();
+	tracker.trackedGetters.clear();
+	tracker.renderCache.clear();
+	tracker.cacheValid = false;
+	tracker.isTracking = false;
+	tracker.externalDependencies.clear();
+}
+
+//#endregion
+//#region src/utils/static-props.ts
+/**
+* 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
+*/
+function getStaticProp(Type, propName, defaultValue) {
+	return Type[propName] ?? defaultValue;
+}
+/**
+* Check if a class is marked as isolated
+* Isolated classes create separate instances per component
+*/
+function isIsolatedClass(Type) {
+	return getStaticProp(Type, BLAC_STATIC_PROPS.ISOLATED) === true;
+}
+/**
+* Check if a class is marked as keepAlive
+* KeepAlive classes are never auto-disposed when ref count reaches 0
+*/
+function isKeepAliveClass(Type) {
+	return getStaticProp(Type, BLAC_STATIC_PROPS.KEEP_ALIVE) === true;
+}
+/**
+* Check if a class should be excluded from DevTools
+* Used to prevent infinite loops when DevTools tracks itself
+*/
+function isExcludedFromDevTools(Type) {
+	return getStaticProp(Type, BLAC_STATIC_PROPS.EXCLUDE_FROM_DEVTOOLS) === true;
+}
 
 //#endregion
 //#region src/core/StateContainerRegistry.ts
 /**
-* Registry for managing StateContainer instances
+* Registry for coordinating StateContainer lifecycle and managing instances
+*
+* Centralizes all instance management using WeakMap to ensure proper isolation.
 */
 var StateContainerRegistry = class {
-	instances = /* @__PURE__ */ new Map();
-	types = /* @__PURE__ */ new Map();
-	listeners = /* @__PURE__ */ new Map();
+	constructor() {
+		this.instancesByConstructor = /* @__PURE__ */ new WeakMap();
+		this.types = /* @__PURE__ */ new Set();
+		this.typeConfigs = /* @__PURE__ */ new Map();
+		this.listeners = /* @__PURE__ */ new Map();
+	}
 	/**
-	* Register a type with isolation mode
+	* Register a type for tracking
+	* Called automatically on first instance creation
+	*/
+	registerType(constructor) {
+		this.types.add(constructor);
+	}
+	/**
+	* Register a type with isolation mode (explicit registration)
 	*/
 	register(constructor, isolated = false) {
 		const className = constructor.name;
-		if (!isolated && constructor.isolated === true) isolated = true;
-		if (this.types.has(className)) throw new Error(`Type "${className}" is already registered`);
-		this.types.set(className, { isolated });
+		if (!isolated && isIsolatedClass(constructor)) isolated = true;
+		if (this.typeConfigs.has(className)) throw new Error(`${BLAC_ERROR_PREFIX} Type "${className}" is already registered`);
+		this.typeConfigs.set(className, { isolated });
+		this.registerType(constructor);
 	}
 	/**
-	* Get or create a StateContainer instance
-	* For isolated: always creates new
-	* For shared: singleton per key
+	* Get the instances Map for a specific class
+	* Creates a new Map on first access.
 	*/
-	getOrCreate(constructor, key, ...args) {
-		const className = constructor.name;
-		let config = this.types.get(className);
-		if (!config) {
-			const isolated = constructor.isolated === true;
-			this.types.set(className, { isolated });
-			config = this.types.get(className);
+	ensureInstancesMap(Type) {
+		let instances = this.instancesByConstructor.get(Type);
+		if (!instances) {
+			instances = /* @__PURE__ */ new Map();
+			this.instancesByConstructor.set(Type, instances);
 		}
-		if (config.isolated) return new constructor(...args);
-		const instanceKey = `${className}:${key || "default"}`;
-		const existing = this.instances.get(instanceKey);
-		if (existing) {
-			existing.refCount++;
-			return existing.instance;
+		return instances;
+	}
+	/**
+	* Get the instances Map for a specific class (public API for stats/debugging)
+	*/
+	getInstancesMap(Type) {
+		return this.instancesByConstructor.get(Type) || /* @__PURE__ */ new Map();
+	}
+	/**
+	* Resolve an instance with ref counting (ownership semantics)
+	*/
+	resolve(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, constructorArgs) {
+		const registryConfig = this.typeConfigs.get(Type.name);
+		const isolated = isIsolatedClass(Type) || registryConfig?.isolated === true;
+		const config = { instanceId: instanceKey };
+		if (isolated) {
+			const instance$1 = new Type(constructorArgs);
+			instance$1.initConfig(config);
+			this.registerType(Type);
+			return instance$1;
 		}
-		const instance = new constructor(...args);
-		this.instances.set(instanceKey, {
+		const instances = this.ensureInstancesMap(Type);
+		const entry = instances.get(instanceKey);
+		if (entry) {
+			entry.refCount++;
+			return entry.instance;
+		}
+		const instance = new Type(constructorArgs);
+		instance.initConfig(config);
+		instances.set(instanceKey, {
 			instance,
 			refCount: 1
 		});
+		this.registerType(Type);
 		return instance;
 	}
 	/**
+	* Get an existing instance without ref counting (borrowing semantics)
+	* @throws Error if instance doesn't exist
+	*/
+	get(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		const entry = this.ensureInstancesMap(Type).get(instanceKey);
+		if (!entry) throw new Error(`${BLAC_ERROR_PREFIX} ${Type.name} instance "${instanceKey}" not found.\nUse .resolve() to create and claim ownership, or .getSafe() for conditional access.`);
+		const context = getGetterExecutionContext();
+		if (context.tracker && context.currentBloc && context.currentBloc !== entry.instance) context.tracker.externalDependencies.add(entry.instance);
+		return entry.instance;
+	}
+	/**
+	* Safely get an existing instance (borrowing semantics with error handling)
+	* Returns discriminated union for type-safe conditional access
+	*/
+	getSafe(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		const entry = this.ensureInstancesMap(Type).get(instanceKey);
+		if (!entry) return {
+			error: /* @__PURE__ */ new Error(`${BLAC_ERROR_PREFIX} ${Type.name} instance "${instanceKey}" not found`),
+			instance: null
+		};
+		const context = getGetterExecutionContext();
+		if (context.tracker && context.currentBloc && context.currentBloc !== entry.instance) context.tracker.externalDependencies.add(entry.instance);
+		return {
+			error: null,
+			instance: entry.instance
+		};
+	}
+	/**
+	* 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(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, constructorArgs) {
+		const registryConfig = this.typeConfigs.get(Type.name);
+		if (isIsolatedClass(Type) || registryConfig?.isolated === true) throw new Error(`${BLAC_ERROR_PREFIX} Cannot use .connect() with isolated bloc "${Type.name}".\nIsolated blocs are component-scoped. Use .resolve() in components instead.`);
+		const instances = this.ensureInstancesMap(Type);
+		let entry = instances.get(instanceKey);
+		if (!entry) {
+			const instance = new Type(constructorArgs);
+			const config = { instanceId: instanceKey };
+			instance.initConfig(config);
+			entry = {
+				instance,
+				refCount: 1
+			};
+			instances.set(instanceKey, entry);
+			this.registerType(Type);
+		}
+		const context = getGetterExecutionContext();
+		if (context.tracker && context.currentBloc && context.currentBloc !== entry.instance) context.tracker.externalDependencies.add(entry.instance);
+		return entry.instance;
+	}
+	/**
 	* Release a reference to an instance
-	* Disposes when ref count reaches zero (unless static keepAlive is true)
 	*/
-	release(constructor, key, forceDispose = false) {
-		const instanceKey = `${constructor.name}:${key || "default"}`;
-		const entry = this.instances.get(instanceKey);
+	release(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, forceDispose = false) {
+		const instances = this.ensureInstancesMap(Type);
+		const entry = instances.get(instanceKey);
 		if (!entry) return;
 		if (forceDispose) {
-			entry.instance.dispose();
-			this.instances.delete(instanceKey);
+			if (!entry.instance.isDisposed) entry.instance.dispose();
+			instances.delete(instanceKey);
 			return;
 		}
 		entry.refCount--;
-		const keepAlive = constructor.keepAlive === true;
+		const keepAlive = isKeepAliveClass(Type);
 		if (entry.refCount <= 0 && !keepAlive) {
-			entry.instance.dispose();
-			this.instances.delete(instanceKey);
+			if (!entry.instance.isDisposed) entry.instance.dispose();
+			instances.delete(instanceKey);
 		}
 	}
 	/**
-	* Get all instances of a type (shared only, isolated aren't tracked)
+	* Get all instances of a specific type
 	*/
-	getAll(constructor) {
-		const prefix = `${constructor.name}:`;
-		const results = [];
-		for (const [key, entry] of this.instances) if (key.startsWith(prefix)) results.push(entry.instance);
-		return results;
+	getAll(Type) {
+		const instances = this.ensureInstancesMap(Type);
+		const result = [];
+		for (const entry of instances.values()) result.push(entry.instance);
+		return result;
 	}
 	/**
-	* Clear all instances of a type
+	* Safely iterate over all instances of a type
 	*/
-	clear(constructor) {
-		const prefix = `${constructor.name}:`;
-		const toDelete = [];
-		for (const [key, entry] of this.instances) if (key.startsWith(prefix)) {
-			if (!entry.instance.isDisposed) entry.instance.dispose();
-			toDelete.push(key);
+	forEach(Type, callback) {
+		const instances = this.ensureInstancesMap(Type);
+		for (const entry of instances.values()) {
+			const instance = entry.instance;
+			if (!instance.isDisposed) try {
+				callback(instance);
+			} catch (error$1) {
+				console.error(`${BLAC_ERROR_PREFIX} forEach callback error for ${Type.name}:`, error$1);
+			}
 		}
-		for (const key of toDelete) this.instances.delete(key);
+	}
+	/**
+	* Clear all instances of a specific type
+	*/
+	clear(Type) {
+		const instances = this.ensureInstancesMap(Type);
+		for (const entry of instances.values()) if (!entry.instance.isDisposed) entry.instance.dispose();
+		instances.clear();
+	}
+	/**
+	* Get reference count for an instance
+	*/
+	getRefCount(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		return this.ensureInstancesMap(Type).get(instanceKey)?.refCount ?? 0;
+	}
+	/**
+	* Check if an instance exists
+	*/
+	hasInstance(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		return this.ensureInstancesMap(Type).has(instanceKey);
 	}
 	/**
 	* 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() {
-		for (const entry of this.instances.values()) if (!entry.instance.isDisposed) entry.instance.dispose();
-		this.instances.clear();
+		for (const Type of this.types) this.clear(Type);
 		this.types.clear();
+		this.typeConfigs.clear();
 	}
 	/**
 	* Get registry statistics (for debugging)
 	*/
 	getStats() {
 		const typeBreakdown = {};
-		for (const key of this.instances.keys()) {
-			const typeName = key.split(":")[0];
-			typeBreakdown[typeName] = (typeBreakdown[typeName] || 0) + 1;
+		let totalInstances = 0;
+		for (const Type of this.types) {
+			const typeName = Type.name;
+			const count = this.getInstancesMap(Type).size;
+			typeBreakdown[typeName] = count;
+			totalInstances += count;
 		}
 		return {
 			registeredTypes: this.types.size,
-			totalInstances: this.instances.size,
+			totalInstances,
 			typeBreakdown
 		};
 	}
 	/**
-	* Get reference count for an instance
-	*/
-	getRefCount(constructor, key) {
-		const instanceKey = `${constructor.name}:${key || "default"}`;
-		return this.instances.get(instanceKey)?.refCount ?? 0;
-	}
-	/**
-	* Check if an instance exists
+	* Get all registered types (for plugin system)
 	*/
-	hasInstance(constructor, key) {
-		const instanceKey = `${constructor.name}:${key || "default"}`;
-		return this.instances.has(instanceKey);
+	getTypes() {
+		return Array.from(this.types);
 	}
 	/**
 	* Subscribe to lifecycle events
@@ -219,7 +747,7 @@ var StateContainerRegistry = class {
 		for (const listener of listeners) try {
 			listener(...args);
 		} catch (error$1) {
-			console.error(`[BlaC] Listener error for '${event}':`, error$1);
+			console.error(`${BLAC_ERROR_PREFIX} Listener error for '${event}':`, error$1);
 		}
 	}
 };
@@ -227,18 +755,51 @@ var StateContainerRegistry = class {
 * Global default registry instance
 */
 const globalRegistry = new StateContainerRegistry();
+/**
+* Global plugin manager (initialized lazily)
+*/
+let _globalPluginManager = null;
+/**
+* Get the global plugin manager
+*/
+function getPluginManager() {
+	if (!_globalPluginManager) _globalPluginManager = createPluginManager(globalRegistry);
+	return _globalPluginManager;
+}
 
 //#endregion
 //#region src/core/StateContainer.ts
 /**
+* StateContainer - Clean, minimal state management container
+*
+* Responsibilities:
+* - State storage and updates
+* - Change notifications to subscribers
+* - Lifecycle management
+*/
+/**
 * Base abstract class for all state containers
 */
 var StateContainer = class StateContainer {
-	static _registry = globalRegistry;
+	static {
+		this.__excludeFromDevTools = false;
+	}
+	static {
+		this._registry = globalRegistry;
+	}
+	/**
+	* Get the global registry (mainly for testing)
+	*/
+	static getRegistry() {
+		return StateContainer._registry;
+	}
 	/**
 	* Set a custom registry (mainly for testing)
+	*
+	* Clears all instances before switching to ensure clean test isolation.
 	*/
 	static setRegistry(registry) {
+		StateContainer._registry.clearAll();
 		StateContainer._registry = registry;
 	}
 	/**
@@ -248,75 +809,123 @@ var StateContainer = class StateContainer {
 		StateContainer._registry.register(this, isolated);
 	}
 	/**
-	* Get or create an instance
-	* @param key - Optional instance key for shared instances
-	* @param args - Constructor arguments
+	* Resolve an instance with ref counting (ownership semantics)
+	*
+	* Delegates to the global registry for instance management.
+	*
+	* @param instanceKey - Optional instance key for shared instances
+	* @param constructorArgs - Constructor arguments
+	* @returns Instance with incremented ref count
+	*/
+	static resolve(instanceKey, constructorArgs) {
+		return StateContainer._registry.resolve(this, instanceKey, constructorArgs);
+	}
+	/**
+	* Get an existing instance without ref counting (borrowing semantics)
+	* Delegates to the global registry.
+	*/
+	static get(instanceKey) {
+		return StateContainer._registry.get(this, instanceKey);
+	}
+	/**
+	* Safely get an existing instance (borrowing semantics with error handling)
+	* Delegates to the global registry.
+	*/
+	static getSafe(instanceKey) {
+		return StateContainer._registry.getSafe(this, instanceKey);
+	}
+	/**
+	* 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).
+	*
+	* Delegates to the global registry.
+	*
+	* @param instanceKey - Optional instance key (defaults to 'default')
+	* @param constructorArgs - Constructor arguments (only used if creating new instance)
+	* @returns The bloc instance
 	*/
-	static getOrCreate(key, ...args) {
-		return StateContainer._registry.getOrCreate(this, key, ...args);
+	static connect(instanceKey, constructorArgs) {
+		return StateContainer._registry.connect(this, instanceKey, constructorArgs);
 	}
 	/**
 	* Release a reference to an instance
-	* @param key - Optional instance key
-	* @param forceDispose - Force dispose regardless of ref count or keepAlive
+	* Delegates to the global registry.
 	*/
-	static release(key, forceDispose = false) {
-		StateContainer._registry.release(this, key, forceDispose);
+	static release(instanceKey, forceDispose = false) {
+		StateContainer._registry.release(this, instanceKey, forceDispose);
 	}
 	/**
 	* Get all instances of this type
+	* Delegates to the global registry.
 	*/
 	static getAll() {
 		return StateContainer._registry.getAll(this);
 	}
 	/**
+	* Safely iterate over all instances of this type
+	* Delegates to the global registry.
+	*/
+	static forEach(callback) {
+		StateContainer._registry.forEach(this, callback);
+	}
+	/**
 	* Clear all instances of this type
+	* Delegates to the global registry.
 	*/
 	static clear() {
 		StateContainer._registry.clear(this);
 	}
 	/**
 	* Clear all instances from all types (for testing)
+	* Delegates to the global registry.
 	*/
 	static clearAllInstances() {
 		StateContainer._registry.clearAll();
 	}
 	/**
 	* Get registry statistics (for debugging)
+	* Delegates to the global registry.
 	*/
 	static getStats() {
 		return StateContainer._registry.getStats();
 	}
 	/**
 	* Get reference count for an instance
-	* @param key - Optional instance key
+	* Delegates to the global registry.
 	*/
-	static getRefCount(key) {
-		return StateContainer._registry.getRefCount(this, key);
+	static getRefCount(instanceKey) {
+		return StateContainer._registry.getRefCount(this, instanceKey);
 	}
 	/**
 	* Check if an instance exists
-	* @param key - Optional instance key
+	* Delegates to the global registry.
 	*/
-	static hasInstance(key) {
-		return StateContainer._registry.hasInstance(this, key);
+	static hasInstance(instanceKey) {
+		return StateContainer._registry.hasInstance(this, instanceKey);
 	}
-	_state;
-	listeners = /* @__PURE__ */ new Set();
-	_disposed = false;
-	config;
-	name;
-	debug;
-	instanceId;
 	/**
 	* Create a new StateContainer
 	*/
-	constructor(initialState, config = {}) {
+	constructor(initialState) {
+		this.listeners = /* @__PURE__ */ new Set();
+		this._disposed = false;
+		this.config = {};
+		this.name = this.constructor.name;
+		this.debug = false;
+		this.instanceId = generateSimpleId(this.constructor.name, "main");
+		this.createdAt = Date.now();
+		this.lastUpdateTimestamp = Date.now();
 		this._state = initialState;
-		this.config = config;
-		this.name = config.name || this.constructor.name;
-		this.debug = config.debug ?? false;
-		this.instanceId = config.instanceId || generateSimpleId(this.constructor.name);
+	}
+	initConfig(config) {
+		this.config = { ...config };
+		this.name = this.config.name || this.constructor.name;
+		this.debug = this.config.debug ?? false;
+		this.instanceId = generateSimpleId(this.constructor.name, this.config.instanceId);
 		StateContainer._registry.emit("created", this);
 	}
 	/**
@@ -366,7 +975,61 @@ var StateContainer = class StateContainer {
 		} catch (error$1) {
 			console.error(`[${this.name}] Error in listener:`, error$1);
 		}
-		StateContainer._registry.emit("stateChanged", this, previousState, newState);
+		const stackTrace = this.captureStackTrace();
+		StateContainer._registry.emit("stateChanged", this, previousState, newState, stackTrace);
+		this.lastUpdateTimestamp = Date.now();
+	}
+	static {
+		this.enableStackTrace = true;
+	}
+	/**
+	* Capture stack trace for debugging
+	* Can be overridden to disable in production
+	*/
+	captureStackTrace() {
+		if (!StateContainer.enableStackTrace || typeof process !== "undefined" && process.env?.NODE_ENV === "production") return "";
+		try {
+			const relevantLines = ((/* @__PURE__ */ new Error()).stack || "").split("\n").slice(1);
+			const formattedLines = [];
+			for (const line of relevantLines) {
+				if (!line.trim()) continue;
+				if (line.includes("StateContainer.emit") || line.includes("StateContainer.update") || line.includes("StateContainer.captureStackTrace") || line.includes("Cubit.patch") || line.includes("Vertex.")) continue;
+				if (line.includes("node_modules") || line.includes("react-dom") || line.includes("react_jsx") || line.includes(".vite/deps") || line.includes("executeDispatch") || line.includes("runWithFiber") || line.includes("invokeGuarded") || line.includes("callCallback") || line.includes("processDispatchQueue") || line.includes("dispatchEvent") || line.includes("batchedUpdates")) continue;
+				const formatted = this.formatStackLine(line);
+				if (formatted) formattedLines.push(formatted);
+			}
+			return formattedLines.join("\n");
+		} catch {
+			return "";
+		}
+	}
+	/**
+	* Format a single stack trace line for better readability
+	* Removes URL prefixes, query params, and cleans up the output
+	*/
+	formatStackLine(line) {
+		const match = line.match(/at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)/);
+		if (!match) {
+			const simpleMatch = line.match(/at\s+(.+?):(\d+):(\d+)/);
+			if (simpleMatch) {
+				const [, url$1, lineNum$1, col$1] = simpleMatch;
+				return `  at ${this.cleanFilePath(url$1)}:${lineNum$1}:${col$1}`;
+			}
+			return null;
+		}
+		const [, functionName, url, lineNum, col] = match;
+		return `  at ${functionName} (${this.cleanFilePath(url)}:${lineNum}:${col})`;
+	}
+	/**
+	* Clean up file path by removing URL prefixes and query params
+	*/
+	cleanFilePath(url) {
+		let path = url.replace(/http:\/\/localhost:\d+\/@fs/, "").replace(/http:\/\/localhost:\d+\//, "").replace(/\?t=\d+/, "").replace(/\?v=[a-f0-9]+/, "");
+		const projectMatch = path.match(/\/Projects\/blac\/(.+)/);
+		if (projectMatch) path = projectMatch[1];
+		const segments = path.split("/");
+		if (segments.length > 3) path = segments.slice(-3).join("/");
+		return path;
 	}
 	/**
 	* Update state using a function
@@ -380,6 +1043,12 @@ var StateContainer = class StateContainer {
 //#endregion
 //#region src/core/Cubit.ts
 /**
+* Cubit - Simple state container with direct state emission
+*
+* This validates that our StateContainer design can support
+* the simple Cubit pattern from the original BlaC.
+*/
+/**
 * Cubit is a simple state container that allows direct state emission
 *
 * Unlike StateContainer (where emit is protected), Cubit exposes emit and update
@@ -389,10 +1058,16 @@ var Cubit = class extends StateContainer {
 	/**
 	* Create a new Cubit
 	* @param initialState Initial state value
-	* @param config Configuration options
 	*/
-	constructor(initialState, config) {
-		super(initialState, config);
+	constructor(initialState) {
+		super(initialState);
+		this.patch = ((partial) => {
+			if (typeof this.state !== "object" || this.state === null) throw new Error("patch() is only available for object state types");
+			this.update((current) => ({
+				...current,
+				...partial
+			}));
+		});
 	}
 	/**
 	* Emit a new state (public override of protected parent method)
@@ -406,89 +1081,70 @@ var Cubit = class extends StateContainer {
 	update(updater) {
 		super["update"](updater);
 	}
-	/**
-	* Patch state with partial updates (shallow merge)
-	* Only available when state is an object type
-	* Arrow function to maintain correct 'this' binding in React
-	*
-	* @example
-	* ```typescript
-	* // Update single field
-	* this.patch({ count: 5 });
-	*
-	* // Update multiple fields
-	* this.patch({ count: 5, name: 'Updated' });
-	* ```
-	*/
-	patch = ((partial) => {
-		if (typeof this.state !== "object" || this.state === null) throw new Error("patch() is only available for object state types");
-		this.update((current) => ({
-			...current,
-			...partial
-		}));
-	});
 };
 /**
 * Example: Counter Cubit
 */
 var CounterCubit = class extends Cubit {
 	constructor() {
-		super(0, { name: "CounterCubit" });
+		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);
+		};
 	}
-	increment = () => {
-		this.emit(this.state + 1);
-	};
-	decrement = () => {
-		this.emit(this.state - 1);
-	};
-	reset = () => {
-		this.emit(0);
-	};
-	addAmount = (amount) => {
-		this.emit(this.state + amount);
-	};
 };
 var TodoCubit = class extends Cubit {
-	static keepAlive = true;
-	nextId = 0;
+	static {
+		this.keepAlive = true;
+	}
 	constructor() {
 		super({
 			todos: [],
 			filter: "all",
 			isLoading: false
-		}, { name: "TodoCubit" });
-	}
-	addTodo = (text) => {
-		this.update((state) => ({
-			...state,
-			todos: [...state.todos, {
-				id: `todo-${Date.now()}-${this.nextId++}`,
-				text,
-				done: false
-			}]
-		}));
-	};
-	toggleTodo = (id) => {
-		this.update((state) => ({
-			...state,
-			todos: state.todos.map((todo) => todo.id === id ? {
-				...todo,
-				done: !todo.done
-			} : todo)
-		}));
-	};
-	removeTodo = (id) => {
-		this.update((state) => ({
-			...state,
-			todos: state.todos.filter((todo) => todo.id !== id)
-		}));
-	};
-	setFilter = (filter) => {
-		this.patch({ filter });
-	};
-	setLoading = (isLoading) => {
-		this.patch({ isLoading });
-	};
+		});
+		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) {
@@ -506,45 +1162,42 @@ var TodoCubit = class extends Cubit {
 //#endregion
 //#region src/core/Vertex.ts
 /**
+* Vertex - Event-driven state container (Bloc pattern)
+*
+* Simplified version that includes its own event handling,
+* since events are only needed for the Vertex pattern.
+*/
+/**
 * Vertex is an event-driven state container (Bloc pattern)
 *
 * Includes its own simple event system since events are only needed
 * for the Vertex pattern, not for the base StateContainer.
 */
 var Vertex = class extends StateContainer {
-	eventHandlers = /* @__PURE__ */ new Map();
-	isProcessing = false;
-	eventQueue = [];
 	/**
 	* Create a new Vertex
 	* @param initialState Initial state value
-	* @param config Configuration options
 	*/
-	constructor(initialState, config) {
-		super(initialState, config);
+	constructor(initialState) {
+		super(initialState);
+		this.eventHandlers = /* @__PURE__ */ new Map();
+		this.isProcessing = false;
+		this.eventQueue = [];
+		this.on = (EventClass, handler) => {
+			const className = EventClass.name;
+			const registrations = this.eventHandlers.get(className) || [];
+			registrations.push({
+				eventClass: EventClass,
+				handler
+			});
+			this.eventHandlers.set(className, registrations);
+		};
+		this.add = (event) => {
+			StateContainer._registry.emit("eventAdded", this, event);
+			this.processEvent(event);
+		};
 	}
 	/**
-	* Register an event handler
-	* Arrow function to maintain correct 'this' binding
-	*/
-	on = (EventClass, handler) => {
-		const className = EventClass.name;
-		const registrations = this.eventHandlers.get(className) || [];
-		registrations.push({
-			eventClass: EventClass,
-			handler
-		});
-		this.eventHandlers.set(className, registrations);
-	};
-	/**
-	* Add an event to be processed
-	* Arrow function to maintain correct 'this' binding in React
-	*/
-	add = (event) => {
-		StateContainer._registry.emit("eventAdded", this, event);
-		this.processEvent(event);
-	};
-	/**
 	* Process an event (synchronously)
 	*/
 	processEvent(event) {
@@ -586,28 +1239,30 @@ var Vertex = class extends StateContainer {
 	/**
 	* Hook for handling event processing errors
 	*/
-	onEventError(event, error$1) {}
+	onEventError(_event, _error) {}
 };
 /**
 * Example: Counter Events
 */
 var IncrementEvent = class {
-	type = "increment";
-	timestamp = Date.now();
 	constructor(amount = 1) {
 		this.amount = amount;
+		this.type = "increment";
+		this.timestamp = Date.now();
 	}
 };
 var DecrementEvent = class {
-	type = "decrement";
-	timestamp = Date.now();
 	constructor(amount = 1) {
 		this.amount = amount;
+		this.type = "decrement";
+		this.timestamp = Date.now();
 	}
 };
 var ResetEvent = class {
-	type = "reset";
-	timestamp = Date.now();
+	constructor() {
+		this.type = "reset";
+		this.timestamp = Date.now();
+	}
 };
 /**
 * Example: Counter Vertex
@@ -616,6 +1271,15 @@ var ResetEvent = class {
 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);
 		});
@@ -626,27 +1290,20 @@ var CounterVertex = class extends Vertex {
 			emit(0);
 		});
 	}
-	increment = (amount = 1) => {
-		this.add(new IncrementEvent(amount));
-	};
-	decrement = (amount = 1) => {
-		this.add(new DecrementEvent(amount));
-	};
-	reset = () => {
-		this.add(new ResetEvent());
-	};
 };
 var LoginEvent = class {
-	type = "login";
-	timestamp = Date.now();
 	constructor(email, password) {
 		this.email = email;
 		this.password = password;
+		this.type = "login";
+		this.timestamp = Date.now();
 	}
 };
 var LogoutEvent = class {
-	type = "logout";
-	timestamp = Date.now();
+	constructor() {
+		this.type = "logout";
+		this.timestamp = Date.now();
+	}
 };
 var AuthVertex = class extends Vertex {
 	constructor() {
@@ -656,6 +1313,12 @@ var AuthVertex = class extends Vertex {
 			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,
@@ -688,14 +1351,17 @@ var AuthVertex = class extends Vertex {
 			});
 		});
 	}
-	login = (email, password) => {
-		this.add(new LoginEvent(email, password));
-	};
-	logout = () => {
-		this.add(new LogoutEvent());
-	};
 };
 
+//#endregion
+//#region src/plugin/BlacPlugin.ts
+/**
+* Type guard for plugins with init
+*/
+function hasInitHook(plugin) {
+	return typeof plugin.onInstall === "function";
+}
+
 //#endregion
 //#region src/tracking/proxy-tracker.ts
 /**
@@ -706,18 +1372,6 @@ var AuthVertex = class extends Vertex {
 * easier to integrate with functional programming patterns and framework hooks.
 */
 /**
-* Array methods that should trigger tracking of the entire array
-*/
-const ARRAY_METHODS = new Set([
-	"map",
-	"filter",
-	"forEach",
-	"find",
-	"some",
-	"every",
-	"reduce"
-]);
-/**
 * Check if a value can be proxied
 *
 * Returns true for plain objects and arrays only.
@@ -780,9 +1434,6 @@ function createArrayProxy(state, target, path, depth = 0) {
 		if (typeof prop === "symbol") return Reflect.get(arr, prop);
 		const value = Reflect.get(arr, prop);
 		if (typeof value === "function") {
-			if (ARRAY_METHODS.has(prop)) {
-				if (state.isTracking && path) state.trackedPaths.add(path);
-			}
 			if (!state.boundFunctionsCache) state.boundFunctionsCache = /* @__PURE__ */ new WeakMap();
 			const cached = state.boundFunctionsCache.get(value);
 			if (cached) return cached;
@@ -790,9 +1441,15 @@ function createArrayProxy(state, target, path, depth = 0) {
 			state.boundFunctionsCache.set(value, bound);
 			return bound;
 		}
+		if (prop === "length") {
+			if (state.isTracking) {
+				const fullPath$1 = path ? `${path}.length` : "length";
+				state.trackedPaths.add(fullPath$1);
+			}
+			return value;
+		}
 		let fullPath;
-		if (prop === "length") fullPath = path ? `${path}.length` : "length";
-		else if (typeof prop === "string") {
+		if (typeof prop === "string") {
 			const index = Number(prop);
 			if (!isNaN(index) && index >= 0) fullPath = path ? `${path}[${index}]` : `[${index}]`;
 			else fullPath = path ? `${path}.${prop}` : prop;
@@ -834,10 +1491,10 @@ function createProxyInternal(state, target, path = "", depth = 0) {
 				return bound;
 			}
 			const fullPath = path ? `${path}.${String(prop)}` : String(prop);
-			if (isProxyable(value)) return createProxyInternal(state, value, fullPath, depth + 1);
 			if (typeof prop === "string" && state.isTracking) {
 				if (!prop.startsWith("_") && !prop.startsWith("$$")) state.trackedPaths.add(fullPath);
 			}
+			if (isProxyable(value)) return createProxyInternal(state, value, fullPath, depth + 1);
 			return value;
 		},
 		has: (obj, prop) => {
@@ -949,13 +1606,45 @@ function shallowEqual(arr1, arr2) {
 
 //#endregion
 //#region src/tracking/dependency-tracker.ts
+function isChildPath(child, parent) {
+	if (child === parent) return false;
+	return child.startsWith(parent + ".") || child.startsWith(parent + "[");
+}
 /**
-* How often to clean up unused paths from the cache
-*/
-const CLEANUP_INTERVAL = 10;
-/**
-* Create a new tracker state
+* Extract the parent array path from an array child path
+* Examples:
+*   'messages.length' -> 'messages'
+*   'messages[0]' -> 'messages'
+*   'messages[0].text' -> 'messages'
+*   'data.items[0]' -> 'data.items'
 */
+function getArrayParentPath(path) {
+	if (path.endsWith(".length")) return path.slice(0, -7);
+	const arrayIndexMatch = path.match(/^(.+?)\[\d+\]/);
+	if (arrayIndexMatch) return arrayIndexMatch[1];
+	return null;
+}
+function optimizeTrackedPaths(paths) {
+	if (paths.size === 0) return /* @__PURE__ */ new Set();
+	if (paths.size === 1) return new Set(paths);
+	const sortedPaths = Array.from(paths).sort((a, b) => b.length - a.length);
+	const optimized = /* @__PURE__ */ new Set();
+	for (const path of sortedPaths) {
+		let hasMoreSpecificChild = false;
+		for (const optimizedPath of optimized) if (isChildPath(optimizedPath, path)) {
+			hasMoreSpecificChild = true;
+			break;
+		}
+		if (!hasMoreSpecificChild) optimized.add(path);
+	}
+	const arrayParents = /* @__PURE__ */ new Set();
+	for (const path of optimized) {
+		const arrayParent = getArrayParentPath(path);
+		if (arrayParent) arrayParents.add(arrayParent);
+	}
+	for (const arrayParent of arrayParents) optimized.add(arrayParent);
+	return optimized;
+}
 function createTrackerState() {
 	return {
 		proxyTrackerState: createProxyTrackerState(),
@@ -963,31 +1652,18 @@ function createTrackerState() {
 		currentRenderPaths: /* @__PURE__ */ new Set(),
 		pathCache: /* @__PURE__ */ new Map(),
 		lastCheckedState: null,
-		lastCheckedValues: /* @__PURE__ */ new Map(),
-		cleanupCounter: 0
+		lastCheckedValues: /* @__PURE__ */ new Map()
 	};
 }
-/**
-* Start tracking property accesses
-*/
 function startTracking(tracker) {
 	startProxyTracking(tracker.proxyTrackerState);
 }
-/**
-* Create a proxy for the given state
-*/
 function createProxy(tracker, state) {
 	return createProxyForTarget(tracker.proxyTrackerState, state);
 }
-/**
-* Capture the paths that were tracked during a render
-*
-* This should be called after each render to record which paths were accessed.
-* It also performs periodic cleanup of unused paths to prevent memory leaks.
-*/
 function captureTrackedPaths(tracker, state) {
 	tracker.previousRenderPaths = tracker.currentRenderPaths;
-	tracker.currentRenderPaths = stopProxyTracking(tracker.proxyTrackerState);
+	tracker.currentRenderPaths = optimizeTrackedPaths(stopProxyTracking(tracker.proxyTrackerState));
 	if (tracker.previousRenderPaths.size === 0 && tracker.currentRenderPaths.size === 0) return;
 	const trackedPathsUnion = new Set(tracker.previousRenderPaths);
 	for (const path of tracker.currentRenderPaths) trackedPathsUnion.add(path);
@@ -1003,19 +1679,8 @@ function captureTrackedPaths(tracker, state) {
 		const info$1 = tracker.pathCache.get(path);
 		info$1.value = canReuseCache && tracker.lastCheckedValues.has(path) ? tracker.lastCheckedValues.get(path) : getValueAtPath(state, info$1.segments);
 	}
-	tracker.cleanupCounter++;
-	if (tracker.cleanupCounter >= CLEANUP_INTERVAL) {
-		tracker.cleanupCounter = 0;
-		for (const path of tracker.pathCache.keys()) if (!trackedPathsUnion.has(path)) tracker.pathCache.delete(path);
-	}
 	tracker.lastCheckedValues.clear();
 }
-/**
-* Check if any tracked paths have changed
-*
-* This is called when state changes to determine if a re-render is needed.
-* Returns true if any tracked path has a different value than before.
-*/
 function hasChanges(tracker, state) {
 	if (tracker.pathCache.size === 0) return true;
 	tracker.lastCheckedValues.clear();
@@ -1030,15 +1695,180 @@ function hasChanges(tracker, state) {
 	tracker.lastCheckedState = state;
 	return false;
 }
-/**
-* Check if tracker has any tracked data
-*
-* Returns true if there are any tracked paths or cached paths.
-*/
 function hasTrackedData(tracker) {
 	return tracker.proxyTrackerState.trackedPaths.size > 0 || tracker.pathCache.size > 0 || tracker.previousRenderPaths.size > 0;
 }
 
+//#endregion
+//#region src/adapter/framework-adapter.ts
+/**
+* External dependency manager
+* Handles subscriptions to external blocs accessed in getters
+*/
+var ExternalDependencyManager = class {
+	constructor() {
+		this.subscriptions = [];
+		this.previousDeps = /* @__PURE__ */ new Set();
+	}
+	/**
+	* Check if dependencies have changed
+	*/
+	areDependenciesEqual(oldDeps, newDeps) {
+		if (oldDeps.size !== newDeps.size) return false;
+		for (const dep of newDeps) if (!oldDeps.has(dep)) return false;
+		return true;
+	}
+	/**
+	* Update external subscriptions
+	* @param getterTracker - The getter tracker state
+	* @param rawInstance - The raw bloc instance (exclude from subscriptions)
+	* @param onGetterChange - Callback when external getter changes
+	* @returns Whether subscriptions were updated
+	*/
+	updateSubscriptions(getterTracker, rawInstance, onGetterChange) {
+		if (!getterTracker?.externalDependencies) return false;
+		const currentDeps = getterTracker.externalDependencies;
+		if (this.areDependenciesEqual(this.previousDeps, currentDeps)) {
+			clearExternalDependencies(getterTracker);
+			return false;
+		}
+		this.cleanup();
+		for (const externalBloc of currentDeps) {
+			if (externalBloc === rawInstance) continue;
+			const unsub = externalBloc.subscribe(() => {
+				invalidateRenderCache(getterTracker);
+				if (hasGetterChanges(rawInstance, getterTracker)) onGetterChange();
+			});
+			this.subscriptions.push(unsub);
+		}
+		this.previousDeps = new Set(currentDeps);
+		clearExternalDependencies(getterTracker);
+		return true;
+	}
+	/**
+	* Cleanup all subscriptions
+	*/
+	cleanup() {
+		this.subscriptions.forEach((unsub) => unsub());
+		this.subscriptions = [];
+	}
+};
+/**
+* Create a subscription function for auto-tracking mode
+*/
+function createAutoTrackSubscribe(instance, adapterState) {
+	return (callback) => {
+		return instance.subscribe(() => {
+			const tracker = adapterState.tracker || (adapterState.tracker = createTrackerState());
+			const hasStateDeps = tracker.pathCache && tracker.pathCache.size > 0;
+			const hasGetterDeps = adapterState.getterTracker && adapterState.getterTracker.trackedGetters.size > 0;
+			const isPrimitiveState = instance.state !== null && typeof instance.state !== "object" && typeof instance.state !== "function";
+			if (!hasStateDeps && !hasGetterDeps && !isPrimitiveState) return;
+			let stateChanged = hasChanges(tracker, instance.state);
+			if (!hasStateDeps && hasGetterDeps) stateChanged = false;
+			if (stateChanged) {
+				callback();
+				return;
+			}
+			if (hasGetterChanges(instance, adapterState.getterTracker)) callback();
+		});
+	};
+}
+/**
+* Create a subscription function for manual dependencies mode
+*/
+function createManualDepsSubscribe(instance, adapterState, config) {
+	return (callback) => {
+		return instance.subscribe(() => {
+			const newDeps = config.dependencies(instance.state, instance);
+			if (!adapterState.manualDepsCache || !shallowEqual(adapterState.manualDepsCache, newDeps)) {
+				adapterState.manualDepsCache = newDeps;
+				callback();
+			}
+		});
+	};
+}
+/**
+* Create a subscription function for no-tracking mode
+*/
+function createNoTrackSubscribe(instance) {
+	return (callback) => instance.subscribe(callback);
+}
+/**
+* Create a snapshot function for auto-tracking mode
+*/
+function createAutoTrackSnapshot(instance, adapterState) {
+	return () => {
+		const tracker = adapterState.tracker || (adapterState.tracker = createTrackerState());
+		if (hasTrackedData(tracker)) captureTrackedPaths(tracker, instance.state);
+		if (adapterState.getterTracker) {
+			invalidateRenderCache(adapterState.getterTracker);
+			commitTrackedGetters(adapterState.getterTracker);
+			adapterState.getterTracker.isTracking = true;
+			setActiveTracker(instance, adapterState.getterTracker);
+		}
+		startTracking(tracker);
+		return createProxy(tracker, instance.state);
+	};
+}
+/**
+* Create a snapshot function for manual dependencies mode
+*/
+function createManualDepsSnapshot(instance, adapterState, config) {
+	return () => {
+		adapterState.manualDepsCache = config.dependencies(instance.state, instance);
+		return instance.state;
+	};
+}
+/**
+* Create a snapshot function for no-tracking mode
+*/
+function createNoTrackSnapshot(instance) {
+	return () => instance.state;
+}
+/**
+* Initialize adapter state for auto-tracking mode
+*/
+function initAutoTrackState(instance) {
+	return {
+		tracker: null,
+		manualDepsCache: null,
+		getterTracker: createGetterTracker(),
+		proxiedBloc: createBlocProxy(instance)
+	};
+}
+/**
+* Initialize adapter state for manual dependencies mode
+*/
+function initManualDepsState(instance) {
+	return {
+		tracker: null,
+		manualDepsCache: null,
+		getterTracker: null,
+		proxiedBloc: instance
+	};
+}
+/**
+* Initialize adapter state for no-tracking mode
+*/
+function initNoTrackState(instance) {
+	return {
+		tracker: null,
+		manualDepsCache: null,
+		getterTracker: null,
+		proxiedBloc: instance
+	};
+}
+/**
+* Disable getter tracking (call after render completes)
+*/
+function disableGetterTracking(adapterState, rawInstance) {
+	if (adapterState.getterTracker) {
+		adapterState.getterTracker.isTracking = false;
+		clearActiveTracker(rawInstance);
+	}
+}
+
 //#endregion
 //#region src/logging/Logger.ts
 let LogLevel = /* @__PURE__ */ function(LogLevel$1) {
@@ -1136,209 +1966,5 @@ function configureLogger(opts) {
 }
 
 //#endregion
-//#region src/proxy/ProxyTracker.ts
-/**
-* Check if a value is an object that can be proxied
-*/
-function isProxyable$1(value) {
-	return value !== null && typeof value === "object" && !(value instanceof Date) && !(value instanceof RegExp) && !(value instanceof Map) && !(value instanceof Set) && !(value instanceof WeakMap) && !(value instanceof WeakSet) && !(value instanceof Promise);
-}
-/**
-* Tracks property access on state objects
-*/
-var ProxyTracker = class {
-	trackedPaths = /* @__PURE__ */ new Set();
-	isTracking = false;
-	proxyCache = /* @__PURE__ */ new WeakMap();
-	maxDepth = 10;
-	/**
-	* Create a proxy that tracks property access
-	*/
-	createProxy(target, path = "", depth = 0) {
-		if (!this.isTracking || !isProxyable$1(target)) return target;
-		if (depth >= this.maxDepth) return target;
-		if (this.proxyCache.has(target)) return this.proxyCache.get(target);
-		if (Array.isArray(target)) return this.createArrayProxy(target, path, depth);
-		const proxy = new Proxy(target, {
-			get: (obj, prop) => {
-				const value = Reflect.get(obj, prop);
-				if (typeof value === "function") return value.bind(obj);
-				const fullPath = path ? `${path}.${String(prop)}` : String(prop);
-				if (isProxyable$1(value)) return this.createProxy(value, fullPath, depth + 1);
-				if (typeof prop === "string" && this.isTracking) {
-					if (!prop.startsWith("_") && !prop.startsWith("$$")) {
-						this.trackedPaths.add(fullPath);
-						debug("ProxyTracker", "Tracked property access", {
-							path: fullPath,
-							valueType: typeof value
-						});
-					}
-				}
-				return value;
-			},
-			has: (obj, prop) => {
-				if (typeof prop === "string" && this.isTracking) {
-					const fullPath = path ? `${path}.${prop}` : prop;
-					this.trackedPaths.add(fullPath);
-					debug("ProxyTracker", "Tracked \"in\" operator access", { path: fullPath });
-				}
-				return Reflect.has(obj, prop);
-			},
-			ownKeys: (obj) => {
-				if (this.isTracking && path) {
-					this.trackedPaths.add(path);
-					debug("ProxyTracker", "Tracked object keys iteration", { path });
-				}
-				return Reflect.ownKeys(obj);
-			}
-		});
-		this.proxyCache.set(target, proxy);
-		return proxy;
-	}
-	/**
-	* Create a proxy for arrays with special handling
-	*/
-	createArrayProxy(target, path, depth = 0) {
-		const proxy = new Proxy(target, { get: (arr, prop) => {
-			const value = Reflect.get(arr, prop);
-			if (typeof value === "function") {
-				if ([
-					"map",
-					"filter",
-					"forEach",
-					"find",
-					"some",
-					"every",
-					"reduce"
-				].includes(String(prop))) {
-					if (this.isTracking && path) {
-						this.trackedPaths.add(path);
-						debug("ProxyTracker", "Tracked array method access", {
-							path,
-							method: String(prop)
-						});
-					}
-				}
-				return value.bind(arr);
-			}
-			let fullPath;
-			if (prop === "length") fullPath = path ? `${path}.length` : "length";
-			else if (typeof prop === "string") {
-				const index = Number(prop);
-				if (!isNaN(index) && index >= 0) fullPath = path ? `${path}[${index}]` : `[${index}]`;
-				else fullPath = path ? `${path}.${prop}` : prop;
-			} else return value;
-			if (isProxyable$1(value)) return this.createProxy(value, fullPath, depth + 1);
-			if (this.isTracking) {
-				this.trackedPaths.add(fullPath);
-				debug("ProxyTracker", "Tracked array property access", {
-					path: fullPath,
-					valueType: typeof value
-				});
-			}
-			return value;
-		} });
-		this.proxyCache.set(target, proxy);
-		return proxy;
-	}
-	/**
-	* Start tracking property access
-	*/
-	startTracking() {
-		this.isTracking = true;
-		this.trackedPaths.clear();
-		debug("ProxyTracker", "Started tracking");
-	}
-	/**
-	* Stop tracking and return tracked paths
-	*/
-	stopTracking() {
-		this.isTracking = false;
-		debug("ProxyTracker", "Stopped tracking", {
-			pathCount: this.trackedPaths.size,
-			paths: Array.from(this.trackedPaths)
-		});
-		return new Set(this.trackedPaths);
-	}
-	/**
-	* Get currently tracked paths
-	*/
-	getTrackedPaths() {
-		return new Set(this.trackedPaths);
-	}
-	/**
-	* Check if currently tracking
-	*/
-	isCurrentlyTracking() {
-		return this.isTracking;
-	}
-	/**
-	* Clear proxy cache (useful for memory management)
-	*/
-	clearCache() {
-		this.proxyCache = /* @__PURE__ */ new WeakMap();
-	}
-	/**
-	* Set maximum tracking depth
-	*/
-	setMaxDepth(depth) {
-		this.maxDepth = Math.max(1, depth);
-	}
-	/**
-	* Add a path manually (useful for forcing dependencies)
-	*/
-	addPath(path) {
-		this.trackedPaths.add(path);
-	}
-	/**
-	* Remove a path manually
-	*/
-	removePath(path) {
-		this.trackedPaths.delete(path);
-	}
-	/**
-	* Clear all tracked paths
-	*/
-	clearPaths() {
-		this.trackedPaths.clear();
-	}
-};
-/**
-* Global proxy tracker instance for convenience
-*/
-const globalProxyTracker = new ProxyTracker();
-/**
-* Utility function to track property access in a callback
-*/
-function trackAccess(state, callback) {
-	const tracker = new ProxyTracker();
-	tracker.startTracking();
-	return {
-		result: callback(tracker.createProxy(state)),
-		trackedPaths: tracker.stopTracking()
-	};
-}
-
-//#endregion
-//#region src/constants.ts
-/**
-* Default configuration constants for BlaC
-*
-* Centralized location for all magic numbers and default values.
-*/
-/**
-* Default configuration constants for BlaC
-*/
-const BLAC_DEFAULTS = {
-	CLEANUP_INTERVAL_MS: 3e4,
-	WEAKREF_CLEANUP_INTERVAL_MS: 1e4,
-	MAX_SUBSCRIPTIONS: 1e3,
-	MAX_SUBSCRIPTIONS_HIGH_PERF: 1e4,
-	PIPELINE_TIMEOUT_MS: 5e3,
-	CLEANUP_INTERVAL_HIGH_PERF_MS: 5e3,
-	MAX_PIPELINE_STAGES: 30
-};
-
-//#endregion
-export { AuthVertex, BLAC_DEFAULTS, CounterCubit, CounterVertex, Cubit, DecrementEvent, IncrementEvent, LogLevel, LoginEvent, LogoutEvent, ProxyTracker, ResetEvent, StateContainer, StateContainerRegistry, TodoCubit, Vertex, __resetIdCounters, captureTrackedPaths, configureLogger, createArrayProxy, createIdGenerator, createLogger, createProxy, createProxyForTarget, createProxyInternal, createProxyTrackerState, createTrackerState, debug, error, generateId, generateSimpleId, getValueAtPath, globalProxyTracker, globalRegistry, hasChanges, hasTrackedData, info, isProxyable, parsePath, shallowEqual, startProxyTracking, startTracking, stopProxyTracking, trackAccess, warn };
+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, 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