@blac/core 2.0.0-rc-7 → 2.0.0-rc-8

package/src/Blac.ts

@@ -1,13 +1,18 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-// TODO: Remove this eslint disable once any types are properly replaced
-import { BlocBase, BlocInstanceId } from "./BlocBase";
+// TODO: The 'any' types in this file are necessary for proper type inference in complex generic scenarios.
+// Specifically:
+// 1. BlocConstructor<any> in Maps - allows any bloc type to be stored while maintaining type safety in usage
+// 2. Type assertions for _disposalState - private property access across inheritance hierarchy
+// 3. Constructor argument types - enables flexible bloc instantiation patterns
+// These 'any' usages are carefully controlled and don't compromise runtime type safety.
+import { BlocBase, BlocInstanceId } from './BlocBase';
 import {
-    BlocBaseAbstract,
-    BlocConstructor,
-    BlocHookDependencyArrayFn,
-    BlocState,
-    InferPropsFromGeneric
-} from "./types";
+  BlocBaseAbstract,
+  BlocConstructor,
+  BlocHookDependencyArrayFn,
+  BlocState,
+  InferPropsFromGeneric,
+} from './types';
 
 /**
  * Configuration options for the Blac instance
@@ -43,7 +48,9 @@ class SingletonBlacManager implements BlacInstanceManager {
 
   getInstance(): Blac {
     if (!SingletonBlacManager._instance) {
-      SingletonBlacManager._instance = new Blac({ __unsafe_ignore_singleton: true });
+      SingletonBlacManager._instance = new Blac({
+        __unsafe_ignore_singleton: true,
+      });
     }
     return SingletonBlacManager._instance;
   }
@@ -54,8 +61,10 @@ class SingletonBlacManager implements BlacInstanceManager {
 
   resetInstance(): void {
     const oldInstance = SingletonBlacManager._instance;
-    SingletonBlacManager._instance = new Blac({ __unsafe_ignore_singleton: true });
-    
+    SingletonBlacManager._instance = new Blac({
+      __unsafe_ignore_singleton: true,
+    });
+
     // Transfer any keep-alive blocs to the new instance
     if (oldInstance) {
       for (const bloc of oldInstance.keepAliveBlocs) {
@@ -82,7 +91,7 @@ export function setBlacInstanceManager(manager: BlacInstanceManager): void {
  * Main Blac class that manages the state management system.
  * Can work with singleton pattern or dependency injection.
  * Handles bloc lifecycle, and instance tracking.
- * 
+ *
  * Key responsibilities:
  * - Managing bloc instances (creation, disposal, lookup)
  * - Handling isolated and non-isolated blocs
@@ -101,6 +110,10 @@ export class Blac {
   /** Map storing all registered bloc instances by their class name and ID */
   blocInstanceMap: Map<string, BlocBase<unknown>> = new Map();
   /** Map storing isolated bloc instances grouped by their constructor */
+  // TODO: BlocConstructor<any> is required here for type inference to work correctly.
+  // Using BlocConstructor<BlocBase<unknown>> would break type inference when storing
+  // different bloc types in the same map. The 'any' allows proper polymorphic storage
+  // while maintaining type safety at usage sites through the BlocConstructor constraint.
   isolatedBlocMap: Map<BlocConstructor<any>, BlocBase<unknown>[]> = new Map();
   /** Map for O(1) lookup of isolated blocs by UID */
   private isolatedBlocIndex: Map<string, BlocBase<unknown>> = new Map();
@@ -125,15 +138,21 @@ export class Blac {
 
   /** Flag to enable/disable logging */
   static enableLog = false;
+  static logLevel: 'warn' | 'log' = 'warn';
 
   /**
    * Logs messages to console when logging is enabled
    * @param args - Arguments to log
    */
   log = (...args: unknown[]) => {
-    if (Blac.enableLog) console.warn(`☢️ [Blac ${this.createdAt.toString()}]`, ...args);
+    if (Blac.enableLog && Blac.logLevel === 'warn')
+      console.warn(`☢️ [Blac ${this.createdAt.toString()}]`, ...args);
+    if (Blac.enableLog && Blac.logLevel === 'log')
+      console.log(`☢️ [Blac ${this.createdAt.toString()}]`, ...args);
   };
-  static get log() { return Blac.instance.log; }
+  static get log() {
+    return Blac.instance.log;
+  }
 
   /**
    * Gets the current Blac instance
@@ -143,7 +162,6 @@ export class Blac {
     return instanceManager.getInstance();
   }
 
-
   /**
    * Logs a warning message
    * @param message - Warning message
@@ -151,10 +169,16 @@ export class Blac {
    */
   warn = (message: string, ...args: unknown[]) => {
     if (Blac.enableLog) {
-      console.warn(`🚨 [Blac ${String(Blac.instance.createdAt)}]`, message, ...args);
+      console.warn(
+        `🚨 [Blac ${String(Blac.instance.createdAt)}]`,
+        message,
+        ...args,
+      );
     }
   };
-  static get warn() { return Blac.instance.warn; }
+  static get warn() {
+    return Blac.instance.warn;
+  }
   /**
    * Logs an error message
    * @param message - Error message
@@ -162,17 +186,23 @@ export class Blac {
    */
   error = (message: string, ...args: unknown[]) => {
     if (Blac.enableLog) {
-      console.error(`🚨 [Blac ${String(Blac.instance.createdAt)}]`, message, ...args);
+      console.error(
+        `🚨 [Blac ${String(Blac.instance.createdAt)}]`,
+        message,
+        ...args,
+      );
     }
   };
-  static get error() { return Blac.instance.error; }
+  static get error() {
+    return Blac.instance.error;
+  }
 
   /**
    * Resets the Blac instance to a new one, disposing non-keepAlive blocs
    * from the old instance.
    */
   resetInstance = (): void => {
-    this.log("Reset Blac instance");
+    this.log('Reset Blac instance');
 
     // Create snapshots to avoid concurrent modification issues
     const oldBlocInstanceMap = new Map(this.blocInstanceMap);
@@ -181,6 +211,7 @@ export class Blac {
     // Dispose non-keepAlive blocs from the current instance
     // Use disposeBloc method to ensure proper cleanup
     oldBlocInstanceMap.forEach((bloc) => {
+      // TODO: Type assertion for private property access (see explanation above)
       if (!bloc._keepAlive && (bloc as any)._disposalState === 'active') {
         this.disposeBloc(bloc);
       }
@@ -188,6 +219,7 @@ export class Blac {
 
     oldIsolatedBlocMap.forEach((blocArray) => {
       blocArray.forEach((bloc) => {
+        // TODO: Type assertion for private property access (see explanation above)
         if (!bloc._keepAlive && (bloc as any)._disposalState === 'active') {
           this.disposeBloc(bloc);
         }
@@ -201,7 +233,7 @@ export class Blac {
 
     // Use instance manager to reset
     instanceManager.resetInstance();
-  }
+  };
   static resetInstance = (): void => {
     instanceManager.resetInstance();
   };
@@ -212,18 +244,26 @@ export class Blac {
    */
   disposeBloc = (bloc: BlocBase<unknown>): void => {
     // Check if bloc is already disposed to prevent double disposal
+    // TODO: Type assertion needed to access private _disposalState property from external class.
+    // This is safe because we know BlocBase has this property, but TypeScript can't verify
+    // private property access across class boundaries. Alternative would be to make
+    // _disposalState protected, but that would expose internal implementation details.
     if ((bloc as any)._disposalState !== 'active') {
-      this.log(`[${bloc._name}:${String(bloc._id)}] disposeBloc called on already disposed bloc`);
+      this.log(
+        `[${bloc._name}:${String(bloc._id)}] disposeBloc called on already disposed bloc`,
+      );
       return;
     }
 
     const base = bloc.constructor as unknown as BlocBaseAbstract;
     const key = this.createBlocInstanceMapKey(bloc._name, bloc._id);
-    this.log(`[${bloc._name}:${String(bloc._id)}] disposeBloc called. Isolated: ${String(base.isolated)}`);
+    this.log(
+      `[${bloc._name}:${String(bloc._id)}] disposeBloc called. Isolated: ${String(base.isolated)}`,
+    );
 
     // First dispose the bloc to prevent further operations
     bloc._dispose();
-    
+
     // Then clean up from registries
     if (base.isolated) {
       this.unregisterIsolatedBlocInstance(bloc);
@@ -231,10 +271,12 @@ export class Blac {
     } else {
       this.unregisterBlocInstance(bloc);
     }
-    
-    this.log('dispatched bloc', bloc)
+
+    this.log('dispatched bloc', bloc);
   };
-  static get disposeBloc() { return Blac.instance.disposeBloc; }
+  static get disposeBloc() {
+    return Blac.instance.disposeBloc;
+  }
 
   /**
    * Creates a unique key for a bloc instance in the map based on the bloc class name and instance ID
@@ -253,10 +295,10 @@ export class Blac {
   unregisterBlocInstance(bloc: BlocBase<unknown>): void {
     const key = this.createBlocInstanceMapKey(bloc._name, bloc._id);
     this.blocInstanceMap.delete(key);
-    
+
     // Clean up UID tracking
     this.uidRegistry.delete(bloc.uid);
-    
+
     // Remove from keep-alive set
     this.keepAliveBlocs.delete(bloc);
   }
@@ -268,10 +310,10 @@ export class Blac {
   registerBlocInstance(bloc: BlocBase<unknown>): void {
     const key = this.createBlocInstanceMapKey(bloc._name, bloc._id);
     this.blocInstanceMap.set(key, bloc);
-    
+
     // Track UID for cleanup
     this.uidRegistry.set(bloc.uid, bloc);
-    
+
     // Track keep-alive blocs
     if (bloc._keepAlive) {
       this.keepAliveBlocs.add(bloc);
@@ -293,7 +335,7 @@ export class Blac {
 
     const key = this.createBlocInstanceMapKey(blocClass.name, id);
     const found = this.blocInstanceMap.get(key) as InstanceType<B> | undefined;
-    return found
+    return found;
   }
 
   /**
@@ -308,13 +350,13 @@ export class Blac {
     } else {
       this.isolatedBlocMap.set(blocClass, [bloc]);
     }
-    
+
     // Add to isolated index for O(1) lookups
     this.isolatedBlocIndex.set(bloc.uid, bloc);
-    
+
     // Track UID for cleanup
     this.uidRegistry.set(bloc.uid, bloc);
-    
+
     // Track keep-alive blocs
     if (bloc._keepAlive) {
       this.keepAliveBlocs.add(bloc);
@@ -328,10 +370,10 @@ export class Blac {
   unregisterIsolatedBlocInstance(bloc: BlocBase<unknown>): void {
     const blocClass = bloc.constructor;
     const blocs = this.isolatedBlocMap.get(blocClass as BlocConstructor<any>);
-    
+
     // Ensure both data structures are synchronized
     let wasRemoved = false;
-    
+
     if (blocs) {
       const index = blocs.findIndex((b) => b.uid === bloc.uid);
       if (index !== -1) {
@@ -343,21 +385,21 @@ export class Blac {
         this.isolatedBlocMap.delete(blocClass as BlocConstructor<any>);
       }
     }
-    
+
     // Always try to remove from isolated index, even if not found in map
     const wasInIndex = this.isolatedBlocIndex.delete(bloc.uid);
-    
+
     // Clean up UID tracking
     this.uidRegistry.delete(bloc.uid);
-    
+
     // Remove from keep-alive set
     this.keepAliveBlocs.delete(bloc);
-    
+
     // Log inconsistency for debugging
     if (wasRemoved !== wasInIndex) {
       this.warn(
         `[Blac] Inconsistent state detected during isolated bloc cleanup for ${bloc._name}:${bloc.uid}. ` +
-        `Map removal: ${wasRemoved}, Index removal: ${wasInIndex}`
+          `Map removal: ${wasRemoved}, Index removal: ${wasInIndex}`,
       );
     }
   }
@@ -377,7 +419,9 @@ export class Blac {
       return undefined;
     }
     // Find the specific bloc by ID within the isolated array
-    const found = blocs.find((b) => b._id === id) as InstanceType<B> | undefined;
+    const found = blocs.find((b) => b._id === id) as
+      | InstanceType<B>
+      | undefined;
     return found;
   }
 
@@ -385,7 +429,7 @@ export class Blac {
    * Finds an isolated bloc instance by UID (O(1) lookup)
    */
   findIsolatedBlocInstanceByUid<B extends BlocBase<unknown>>(
-    uid: string
+    uid: string,
   ): B | undefined {
     return this.isolatedBlocIndex.get(uid) as B | undefined;
   }
@@ -421,29 +465,42 @@ export class Blac {
     return newBloc;
   }
 
-
   activateBloc = (bloc: BlocBase<unknown>): void => {
+    // Don't activate disposed blocs
+    if ((bloc as any)._disposalState !== 'active') {
+      this.log(
+        `[${bloc._name}:${String(bloc._id)}] activateBloc called on disposed bloc. Ignoring.`,
+      );
+      return;
+    }
+
     const base = bloc.constructor as unknown as BlocConstructor<BlocBase<any>>;
     const isIsolated = bloc.isIsolated;
 
-    let found = isIsolated ? this.findIsolatedBlocInstance(base, bloc._id) : this.findRegisteredBlocInstance(base, bloc._id);
+    let found = isIsolated
+      ? this.findIsolatedBlocInstance(base, bloc._id)
+      : this.findRegisteredBlocInstance(base, bloc._id);
     if (found) {
       return;
     }
 
-    this.log(`[${bloc._name}:${String(bloc._id)}] activateBloc called. Isolated: ${String(bloc.isIsolated)}`);
+    this.log(
+      `[${bloc._name}:${String(bloc._id)}] activateBloc called. Isolated: ${String(bloc.isIsolated)}`,
+    );
     if (bloc.isIsolated) {
       this.registerIsolatedBlocInstance(bloc);
     } else {
       this.registerBlocInstance(bloc);
     }
   };
-  static get activateBloc() { return Blac.instance.activateBloc; }
+  static get activateBloc() {
+    return Blac.instance.activateBloc;
+  }
 
   /**
    * Gets or creates a bloc instance based on the provided class and options.
    * If a bloc with the given ID exists, it will be returned. Otherwise, a new instance will be created.
-   * 
+   *
    * @param blocClass - The bloc class to get or create
    * @param options - Options including:
    *   - id: The instance ID (defaults to class name if not provided)
@@ -459,11 +516,9 @@ export class Blac {
     const base = blocClass as unknown as BlocBaseAbstract;
     const blocId = id ?? blocClass.name;
 
-
     if (base.isolated) {
-      const isolatedBloc = this.findIsolatedBlocInstance<B>(blocClass, blocId)
+      const isolatedBloc = this.findIsolatedBlocInstance<B>(blocClass, blocId);
       if (isolatedBloc) {
-        this.log(`[${blocClass.name}:${String(blocId)}] (getBloc) Found existing isolated instance.`, options);
         return isolatedBloc;
       } else {
         if (options.throwIfNotFound) {
@@ -471,10 +526,9 @@ export class Blac {
         }
       }
     } else {
-      const registeredBloc = this.findRegisteredBlocInstance(blocClass, blocId)
+      const registeredBloc = this.findRegisteredBlocInstance(blocClass, blocId);
       if (registeredBloc) {
-        this.log(`[${blocClass.name}:${String(blocId)}] (getBloc) Found existing registered instance.`, options);
-        return registeredBloc
+        return registeredBloc;
       } else {
         if (options.throwIfNotFound) {
           throw new Error(`Registered bloc ${blocClass.name} not found`);
@@ -482,20 +536,24 @@ export class Blac {
       }
     }
 
-    const bloc = this.createNewBlocInstance(
-      blocClass,
-      blocId,
+    const bloc = this.createNewBlocInstance(blocClass, blocId, options);
+    this.log(
+      `[${blocClass.name}:${String(blocId)}] (getBloc) No existing instance found. Creating new one.`,
       options,
+      bloc,
     );
-    this.log(`[${blocClass.name}:${String(blocId)}] (getBloc) No existing instance found. Creating new one.`, options, bloc);
-    
+
     if (!bloc) {
-      throw new Error(`[getBloc] Failed to create bloc instance for ${blocClass.name}. This should never happen.`);
+      throw new Error(
+        `[getBloc] Failed to create bloc instance for ${blocClass.name}. This should never happen.`,
+      );
     }
-    
+
     return bloc;
   };
-  static get getBloc() { return Blac.instance.getBloc; }
+  static get getBloc() {
+    return Blac.instance.getBloc;
+  }
 
   /**
    * Gets a bloc instance or throws an error if it doesn't exist
@@ -525,7 +583,9 @@ export class Blac {
     }
     throw new Error(`Bloc ${blocClass.name} not found`);
   };
-  static get getBlocOrThrow() { return Blac.instance.getBlocOrThrow; }
+  static get getBlocOrThrow() {
+    return Blac.instance.getBlocOrThrow;
+  }
 
   /**
    * Gets all instances of a specific bloc class
@@ -545,7 +605,8 @@ export class Blac {
 
     // Search non-isolated blocs
     this.blocInstanceMap.forEach((blocInstance) => {
-      if (blocInstance.constructor === blocClass) { // Strict constructor check
+      if (blocInstance.constructor === blocClass) {
+        // Strict constructor check
         results.push(blocInstance as InstanceType<B>);
       }
     });
@@ -554,7 +615,7 @@ export class Blac {
     if (options.searchIsolated !== false) {
       const isolatedBlocs = this.isolatedBlocMap.get(blocClass);
       if (isolatedBlocs) {
-        results.push(...isolatedBlocs.map(bloc => bloc as InstanceType<B>));
+        results.push(...isolatedBlocs.map((bloc) => bloc as InstanceType<B>));
       }
     }
 
@@ -566,19 +627,21 @@ export class Blac {
    * @param blocClass - The bloc class to dispose
    */
   disposeKeepAliveBlocs = <B extends BlocConstructor<any>>(
-    blocClass?: B
+    blocClass?: B,
   ): void => {
     const toDispose: BlocBase<unknown>[] = [];
-    
+
     for (const bloc of this.keepAliveBlocs) {
       if (!blocClass || bloc.constructor === blocClass) {
         toDispose.push(bloc);
       }
     }
-    
-    toDispose.forEach(bloc => bloc._dispose());
+
+    toDispose.forEach((bloc) => bloc._dispose());
   };
-  static get disposeKeepAliveBlocs() { return Blac.instance.disposeKeepAliveBlocs; }
+  static get disposeKeepAliveBlocs() {
+    return Blac.instance.disposeKeepAliveBlocs;
+  }
 
   /**
    * Disposes all blocs matching a pattern
@@ -586,14 +649,14 @@ export class Blac {
    */
   disposeBlocs = (predicate: (bloc: BlocBase<unknown>) => boolean): void => {
     const toDispose: BlocBase<unknown>[] = [];
-    
+
     // Check registered blocs
     for (const bloc of this.blocInstanceMap.values()) {
       if (predicate(bloc)) {
         toDispose.push(bloc);
       }
     }
-    
+
     // Check isolated blocs
     for (const blocs of this.isolatedBlocMap.values()) {
       for (const bloc of blocs) {
@@ -602,10 +665,12 @@ export class Blac {
         }
       }
     }
-    
-    toDispose.forEach(bloc => bloc._dispose());
+
+    toDispose.forEach((bloc) => bloc._dispose());
   };
-  static get disposeBlocs() { return Blac.instance.disposeBlocs; }
+  static get disposeBlocs() {
+    return Blac.instance.disposeBlocs;
+  }
 
   /**
    * Gets memory usage statistics for debugging
@@ -614,12 +679,17 @@ export class Blac {
     return {
       totalBlocs: this.uidRegistry.size,
       registeredBlocs: this.blocInstanceMap.size,
-      isolatedBlocs: Array.from(this.isolatedBlocMap.values()).reduce((sum, arr) => sum + arr.length, 0),
+      isolatedBlocs: Array.from(this.isolatedBlocMap.values()).reduce(
+        (sum, arr) => sum + arr.length,
+        0,
+      ),
       keepAliveBlocs: this.keepAliveBlocs.size,
       isolatedBlocTypes: this.isolatedBlocMap.size,
     };
   };
-  static get getMemoryStats() { return Blac.instance.getMemoryStats; }
+  static get getMemoryStats() {
+    return Blac.instance.getMemoryStats;
+  }
 
   /**
    * Validates consumer references and cleans up orphaned consumers
@@ -628,18 +698,30 @@ export class Blac {
     for (const bloc of this.uidRegistry.values()) {
       // Validate consumers using the bloc's own validation method
       bloc._validateConsumers();
-      
+
       // Check if bloc should be disposed after validation
-      if (bloc._consumers.size === 0 && !bloc._keepAlive && (bloc as any)._disposalState === 'active') {
+      // TODO: Type assertion for private property access (see explanation above)
+      if (
+        bloc._consumers.size === 0 &&
+        !bloc._keepAlive &&
+        (bloc as any)._disposalState === 'active'
+      ) {
         // Schedule disposal for blocs with no consumers
         setTimeout(() => {
           // Double-check conditions before disposal
-          if (bloc._consumers.size === 0 && !bloc._keepAlive && (bloc as any)._disposalState === 'active') {
+          // TODO: Type assertion for private property access (see explanation above)
+          if (
+            bloc._consumers.size === 0 &&
+            !bloc._keepAlive &&
+            (bloc as any)._disposalState === 'active'
+          ) {
             this.disposeBloc(bloc);
           }
         }, 1000); // Give a grace period
       }
     }
   };
-  static get validateConsumers() { return Blac.instance.validateConsumers; }
+  static get validateConsumers() {
+    return Blac.instance.validateConsumers;
+  }
 }

package/src/BlacObserver.ts

@@ -78,7 +78,11 @@ export class BlacObservable<S = unknown> {
 
     if (this.size === 0) {
       Blac.log('BlacObservable.unsubscribe: No observers left.', this.bloc);
-      // The bloc will handle its own disposal through consumer management
+      // Check if bloc should be disposed when both observers and consumers are gone
+      if (this.bloc._consumers.size === 0 && !this.bloc._keepAlive && (this.bloc as any)._disposalState === 'active') {
+        Blac.log(`[${this.bloc._name}:${this.bloc._id}] No observers or consumers left. Scheduling disposal.`);
+        (this.bloc as any)._scheduleDisposal();
+      }
     }
   }
 
@@ -94,30 +98,29 @@ export class BlacObservable<S = unknown> {
 
       if (observer.dependencyArray) {
         const lastDependencyCheck = observer.lastState;
-        const newDependencyCheck = observer.dependencyArray(newState);
+        const newDependencyCheck = observer.dependencyArray(newState, oldState);
 
-        // If this is the first time (no lastState), always update
+        // If this is the first time (no lastState), trigger initial render
         if (!lastDependencyCheck) {
           shouldUpdate = true;
         } else {
-          // Compare dependency arrays for changes
+          // Compare two-array dependency structure: [stateArray, classArray]
           if (lastDependencyCheck.length !== newDependencyCheck.length) {
             shouldUpdate = true;
           } else {
-            // Compare each part of the dependency arrays
-            for (let o = 0; o < newDependencyCheck.length; o++) {
-              const partNew = newDependencyCheck[o];
-              const partOld = lastDependencyCheck[o] || [];
+            // Compare each array (state and class dependencies)
+            for (let arrayIndex = 0; arrayIndex < newDependencyCheck.length; arrayIndex++) {
+              const lastArray = lastDependencyCheck[arrayIndex] || [];
+              const newArray = newDependencyCheck[arrayIndex] || [];
               
-              // If the part lengths are different, definitely update
-              if (partNew.length !== partOld.length) {
+              if (lastArray.length !== newArray.length) {
                 shouldUpdate = true;
                 break;
               }
               
-              // Compare each value in the parts
-              for (let i = 0; i < partNew.length; i++) {
-                if (!Object.is(partNew[i], partOld[i])) {
+              // Compare each dependency value using Object.is (same as React)
+              for (let i = 0; i < newArray.length; i++) {
+                if (!Object.is(lastArray[i], newArray[i])) {
                   shouldUpdate = true;
                   break;
                 }

package/src/Bloc.ts

@@ -15,7 +15,10 @@ export abstract class Bloc<
     // by the 'on' method's signature.
     readonly eventHandlers: Map<
         // Key: Constructor of a specific event E (where E extends A)
-        // Using 'any[]' for constructor arguments for broader compatibility.
+        // TODO: 'any[]' is required for constructor arguments to allow flexible event instantiation.
+        // Using specific parameter types would break type inference for events with different
+        // constructor signatures. The 'any[]' enables polymorphic event handling while
+        // maintaining type safety through the generic constraint 'E extends A'.
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         new (...args: any[]) => A,
         // Value: Handler function. 'event: A' is used here for the stored function type.
@@ -43,7 +46,8 @@ export abstract class Bloc<
      *                The 'event' parameter in the handler will be typed to the specific eventConstructor.
      */
     protected on<E extends A>(
-        // Using 'any[]' for constructor arguments for broader compatibility.
+        // TODO: 'any[]' is required for constructor arguments (see explanation above).
+        // This allows events with different constructor signatures to be handled uniformly.
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         eventConstructor: new (...args: any[]) => E, 
         handler: (event: E, emit: (newState: S) => void) => void | Promise<void>
@@ -107,6 +111,10 @@ export abstract class Bloc<
      */
     private async _processEvent(action: A): Promise<void> {
         // Using 'any[]' for constructor arguments for broader compatibility.
+        // TODO: Type assertion required to cast action.constructor to proper event constructor type.
+        // JavaScript's constructor property returns 'Function', but we need the specific event
+        // constructor type to look up handlers. This is safe because we validate the action
+        // extends the BlocEventConstraint interface.
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const eventConstructor = action.constructor as new (...args: any[]) => A;
         const handler = this.eventHandlers.get(eventConstructor);