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

package/dist/index.d.ts

@@ -1,154 +1,12 @@
-import { RefObject } from "react";
-import { AnyObject, BlocConstructor, ExtractState, StateContainer } from "@blac/core";
-
-//#region src/types.d.ts
-
 /**
- * Configuration options for the useBloc hook
+ * React Integration
  *
- * @template TBloc - The StateContainer type
- *
- * @example
- * ```tsx
- * const [state, bloc] = useBloc(CounterBloc, {
- *   staticProps: { initialCount: 0 },
- *   dependencies: (state) => [state.count],
- *   onMount: (bloc) => console.log('Mounted'),
- * });
- * ```
- */
-interface UseBlocOptions<TBloc extends StateContainer<AnyObject>> {
-  /**
-   * Static props to pass to the Bloc constructor
-   * Type should match the constructor's first parameter
-   */
-  staticProps?: AnyObject;
-  /**
-   * Custom instance ID for shared blocs
-   * - For isolated blocs, each useBloc call gets its own instance
-   * - For shared blocs, the same instanceId will share the same bloc instance
-   */
-  instanceId?: string;
-  /**
-   * Manual dependency tracking function
-   * - When provided, automatic proxy tracking is disabled
-   * - Component only re-renders when the returned values change (shallow equality)
-   *
-   * @param state - Current state of the bloc
-   * @param bloc - The bloc instance
-   * @returns Array of values to track
-   */
-  dependencies?: (state: ExtractState<TBloc>, bloc: TBloc) => unknown[];
-  /**
-   * Control automatic dependency tracking (default: true)
-   * - true: Automatically track accessed properties via Proxy
-   * - false: Disable tracking, all state changes trigger re-render
-   * - Ignored when `dependencies` option is provided
-   *
-   * @default true
-   */
-  autoTrack?: boolean;
-  /**
-   * Callback invoked when the component mounts
-   *
-   * @param bloc - The bloc instance
-   */
-  onMount?: (bloc: TBloc) => void;
-  /**
-   * Callback invoked when the component unmounts
-   *
-   * @param bloc - The bloc instance
-   */
-  onUnmount?: (bloc: TBloc) => void;
-}
-/**
- * Return type of the useBloc hook
- *
- * @template TBloc - The StateContainer type
- *
- * @returns A tuple containing:
- * - [0]: The current state (may be a Proxy for tracking)
- * - [1]: The bloc instance with methods
- * - [2]: Component ref (internal use only)
- */
-type UseBlocReturn<TBloc extends StateContainer<AnyObject>> = [ExtractState<TBloc>, TBloc, RefObject<ComponentRef>];
-/**
- * @internal
- * Component reference object for internal tracking
- * Used to persist instance IDs across React Strict Mode remounts
- */
-type ComponentRef = {
-  __blocInstanceId?: string;
-  __bridge?: any;
-};
-//#endregion
-//#region src/useBloc.d.ts
-/**
- * Lifecycle: INITIAL MOUNT
- * 1. useMemo runs once - creates bloc, subscribeFn, getSnapshotFn
- * 2. useSyncExternalStore calls getSnapshotFn (1st time) - lazy creates tracker, starts tracking, returns proxy
- * 3. Component renders - proxy tracks property accesses
- * 4. useSyncExternalStore calls getSnapshotFn (2nd time) - captures tracked paths, starts new tracking, returns proxy
- * 5. useSyncExternalStore calls subscribeFn - sets up state change listener
- *
- * Lifecycle: STATE CHANGE
- * 1. Bloc state changes
- * 2. subscribeFn callback checks hasChanges() - only re-renders if tracked paths changed
- * 3. If re-render: getSnapshotFn captures previous paths, starts tracking, returns proxy
- *
- * Lifecycle: RE-RENDER (parent re-render)
- * 1. useMemo returns cached values (same bloc, subscribeFn, getSnapshotFn)
- * 2. useSyncExternalStore calls getSnapshotFn - captures paths, starts tracking, returns proxy
- */
-declare function useBloc<TBloc extends StateContainer<AnyObject>>(BlocClass: BlocConstructor<TBloc>, options?: UseBlocOptions<TBloc>): UseBlocReturn<TBloc>;
-//#endregion
-//#region src/useBlocActions.d.ts
-/**
- * Configuration options for the useBlocActions hook
- *
- * @template TBloc - The StateContainer type
- */
-interface UseBlocActionsOptions<TBloc extends StateContainer<AnyObject>> {
-  /**
-   * Static props to pass to the Bloc constructor
-   * Type should match the constructor's first parameter
-   */
-  staticProps?: AnyObject;
-  /**
-   * Custom instance ID for shared blocs
-   * - For isolated blocs, each useBlocActions call gets its own instance
-   * - For shared blocs, the same instanceId will share the same bloc instance
-   */
-  instanceId?: string;
-  /**
-   * Callback invoked when the component mounts
-   *
-   * @param bloc - The bloc instance
-   */
-  onMount?: (bloc: TBloc) => void;
-  /**
-   * Callback invoked when the component unmounts
-   *
-   * @param bloc - The bloc instance
-   */
-  onUnmount?: (bloc: TBloc) => void;
-}
-/**
- * React hook for accessing bloc instance without state subscription.
- * Use this when you only need to call bloc methods/actions without reading state.
- *
- * Benefits over useBloc:
- * - No state subscription overhead
- * - No proxy tracking
- * - Component never re-renders due to bloc state changes
- * - Lighter weight for action-only components
- *
- * @template TBloc - The StateContainer type
- * @param BlocClass - The bloc class constructor
- * @param options - Optional configuration
- * @returns The bloc instance
+ * Clean integration between React and StateContainer architecture.
+ * Constructor-based API with automatic type inference.
+ * Supports concurrent (useSyncExternalStore) mode for optimal performance.
  */
-declare function useBlocActions<TBloc extends StateContainer<AnyObject>>(BlocClass: BlocConstructor<TBloc>, options?: UseBlocActionsOptions<TBloc>): TBloc;
-//#endregion
-export { type UseBlocActionsOptions, type UseBlocOptions, type UseBlocReturn, useBloc, useBlocActions };
+export { useBloc } from './useBloc';
+export { useBlocActions } from './useBlocActions';
+export type { UseBlocOptions, UseBlocReturn } from './types';
+export type { UseBlocActionsOptions } from './useBlocActions';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,172 +1,33 @@
-import { useEffect, useMemo, useRef, useSyncExternalStore } from "react";
-import { captureTrackedPaths, createProxy, createTrackerState, hasChanges, hasTrackedData, shallowEqual, startTracking } from "@blac/core";
+import { useEffect, useMemo, useReducer, useRef, useSyncExternalStore } from "react";
+import { ExternalDependencyManager, createAutoTrackSnapshot, createAutoTrackSubscribe, createManualDepsSnapshot, createManualDepsSubscribe, createNoTrackSnapshot, createNoTrackSubscribe, disableGetterTracking, generateIsolatedKey, initAutoTrackState, initManualDepsState, initNoTrackState, isIsolatedClass } from "@blac/core";
 
-//#region src/useBloc.ts
-/**
-* Cache for property descriptors to avoid repeated prototype chain walks
-* Maps from object constructor to a map of property name to descriptor
-*/
-const descriptorCache = /* @__PURE__ */ new WeakMap();
-/**
-* Cache for proxied blocs to ensure same proxy is returned for same bloc instance
-* This is important for identity checks (e.g., bloc1 === bloc2) across components
-* using the same shared bloc instance.
-*/
-const blocProxyCache = /* @__PURE__ */ new WeakMap();
-/**
-* Map to store the currently active tracker during render.
-* This allows the cached proxy to know which component's tracker to use.
-* Set before render, cleared after render.
-*/
-const activeTrackerMap = /* @__PURE__ */ new WeakMap();
-/**
-* Get property descriptor for a given property, with caching
-*
-* @remarks
-* Walks up the prototype chain once per class to find the descriptor,
-* then caches the result for performance. This is critical because
-* we need to distinguish getters from methods and properties.
-*
-* @param obj - The object to get the descriptor from
-* @param prop - The property name or symbol
-* @returns The property descriptor if found, undefined otherwise
-*/
-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;
-}
-/**
-* Check if a property is a getter (has a getter descriptor)
-*
-* @param obj - The object to check
-* @param prop - The property name or symbol
-* @returns True if the property is a getter, false otherwise
-*/
-function isGetter(obj, prop) {
-	return getDescriptor(obj, prop)?.get !== void 0;
-}
-/**
-* Create a new getter tracking state
-*
-* @returns A new GetterTrackingState initialized with empty collections
-*/
-function createGetterTracker() {
-	return {
-		trackedValues: /* @__PURE__ */ new Map(),
-		currentlyAccessing: /* @__PURE__ */ new Set(),
-		trackedGetters: /* @__PURE__ */ new Set(),
-		isTracking: false,
-		renderCache: /* @__PURE__ */ new Map(),
-		cacheValid: false
-	};
-}
+//#region src/utils/instance-keys.ts
 /**
-* Create a proxy that intercepts getter access on a bloc instance
-*
-* @remarks
-* This proxy wraps the bloc instance to track which getters are accessed
-* during component render. When tracking is enabled (during render phase),
-* it records accessed getters and stores their computed values for later
-* comparison.
-*
-* IMPORTANT: This function caches proxies per bloc instance. Multiple components
-* sharing the same bloc will get the same proxy instance. Each component sets
-* its tracker in activeTrackerMap before render, and the proxy looks it up.
-*
-* @param bloc - The bloc instance to wrap
-* @returns A proxied bloc that tracks getter access
+* Instance key generation utilities for React integration
 */
-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;
-			}
-			const value = getDescriptor(target, prop).get.call(target);
-			tracker.trackedValues.set(prop, value);
-			return value;
-		}
-		return Reflect.get(target, prop, receiver);
-	} });
-	blocProxyCache.set(bloc, proxy);
-	return proxy;
-}
 /**
-* Check if any tracked getters have changed values
+* Generate an instance key for a bloc
 *
-* @remarks
-* Re-computes all getters that were accessed during the last render and
-* compares their new values with stored values using Object.is() (reference
-* equality).
+* Logic:
+* - If user provides instanceId, use it (convert number to string)
+* - If isolated, generate or reuse a unique key for this component
+* - Otherwise, return undefined (use default key)
 *
-* OPTIMIZATION: Render cache population
-* - Computes ALL tracked getters (no early exit) to populate the render cache
-* - This ensures each getter is computed only once per render cycle
-* - If we're going to re-render, getters accessed during render will use cached values
-* - Cache is populated even if no changes detected (useful for parent-triggered re-renders)
-* - Trade-off: Give up early exit to ensure full cache population
-*
-* Error handling: If a getter throws during re-computation, we log a warning,
-* stop tracking that specific getter, and treat it as "changed" to trigger
-* a re-render. This prevents the tracking system from breaking while still
-* allowing React's error boundary to handle the error on the next render.
-*
-* @param bloc - The bloc instance
-* @param tracker - The getter tracking state
-* @returns True if any tracked getter value changed, false otherwise
+* @param componentRef - React component reference (persists across remounts)
+* @param isIsolated - Whether the bloc is isolated
+* @param providedId - User-provided instance ID (from options)
+* @returns Instance key string or undefined for default
 */
-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) {
-		console.warn(`[useBloc] Getter "${String(prop)}" threw error during change detection. Stopping tracking for this getter.`, error);
-		tracker.trackedGetters.delete(prop);
-		tracker.trackedValues.delete(prop);
-		tracker.cacheValid = false;
-		return true;
-	}
-	tracker.cacheValid = true;
-	return hasAnyChange;
-}
-/**
-* Generates instance ID for isolated blocs
-*/
-function generateInstanceId$1(componentRef, isIsolated, providedId) {
-	if (providedId) return providedId;
+function generateInstanceKey(componentRef, isIsolated, providedId) {
+	if (providedId !== void 0) return typeof providedId === "number" ? String(providedId) : providedId;
 	if (isIsolated) {
-		if (!componentRef.__blocInstanceId) componentRef.__blocInstanceId = `isolated-${Math.random().toString(36).slice(2, 11)}`;
+		if (!componentRef.__blocInstanceId) componentRef.__blocInstanceId = generateIsolatedKey();
 		return componentRef.__blocInstanceId;
 	}
 }
+
+//#endregion
+//#region src/useBloc.ts
 function determineTrackingMode(options) {
 	return {
 		useManualDeps: options?.dependencies !== void 0,
@@ -174,75 +35,6 @@ function determineTrackingMode(options) {
 	};
 }
 /**
-* Factory: Creates subscribe function for automatic proxy tracking mode
-*/
-function createAutoTrackSubscribe(instance, hookState) {
-	return (callback) => {
-		return instance.subscribe(() => {
-			const tracker = hookState.tracker || (hookState.tracker = createTrackerState());
-			let stateChanged = hasChanges(tracker, instance.state);
-			if (tracker.pathCache.size === 0 && hookState.getterTracker && hookState.getterTracker.trackedGetters.size > 0) stateChanged = false;
-			if (stateChanged) {
-				callback();
-				return;
-			}
-			if (hasGetterChanges(instance, hookState.getterTracker)) callback();
-		});
-	};
-}
-/**
-* Factory: Creates subscribe function for manual dependencies mode
-*/
-function createManualDepsSubscribe(instance, hookState, options) {
-	return (callback) => {
-		return instance.subscribe(() => {
-			const newDeps = options.dependencies(instance.state, instance);
-			if (!hookState.manualDepsCache || !shallowEqual(hookState.manualDepsCache, newDeps)) {
-				hookState.manualDepsCache = newDeps;
-				callback();
-			}
-		});
-	};
-}
-/**
-* Factory: Creates subscribe function for no-tracking mode
-*/
-function createNoTrackSubscribe(instance) {
-	return (callback) => instance.subscribe(callback);
-}
-/**
-* Factory: Creates getSnapshot function for automatic proxy tracking mode
-*/
-function createAutoTrackSnapshot(instance, hookState) {
-	return () => {
-		const tracker = hookState.tracker || (hookState.tracker = createTrackerState());
-		if (hasTrackedData(tracker)) captureTrackedPaths(tracker, instance.state);
-		if (hookState.getterTracker) {
-			if (hookState.getterTracker.currentlyAccessing.size > 0) hookState.getterTracker.trackedGetters = new Set(hookState.getterTracker.currentlyAccessing);
-			hookState.getterTracker.currentlyAccessing.clear();
-			hookState.getterTracker.isTracking = true;
-			activeTrackerMap.set(instance, hookState.getterTracker);
-		}
-		startTracking(tracker);
-		return createProxy(tracker, instance.state);
-	};
-}
-/**
-* Factory: Creates getSnapshot function for manual dependencies mode
-*/
-function createManualDepsSnapshot(instance, hookState, options) {
-	return () => {
-		hookState.manualDepsCache = options.dependencies(instance.state, instance);
-		return instance.state;
-	};
-}
-/**
-* Factory: Creates getSnapshot function for no-tracking mode
-*/
-function createNoTrackSnapshot(instance) {
-	return () => instance.state;
-}
-/**
 * Lifecycle: INITIAL MOUNT
 * 1. useMemo runs once - creates bloc, subscribeFn, getSnapshotFn
 * 2. useSyncExternalStore calls getSnapshotFn (1st time) - lazy creates tracker, starts tracking, returns proxy
@@ -261,57 +53,51 @@ function createNoTrackSnapshot(instance) {
 */
 function useBloc(BlocClass, options) {
 	const componentRef = useRef({});
-	const [bloc, subscribe, getSnapshot, instanceKey, hookState, rawInstance] = useMemo(() => {
-		const isIsolated = BlocClass.isolated === true;
-		const Constructor = BlocClass;
-		const instanceId = generateInstanceId$1(componentRef.current, isIsolated, options?.instanceId);
-		const instance = Constructor.getOrCreate(instanceId, options?.staticProps);
+	const Constructor = BlocClass;
+	const isIsolated = isIsolatedClass(BlocClass);
+	const [bloc, subscribe, getSnapshot, instanceKey, adapterState, rawInstance] = useMemo(() => {
+		const instanceKey$1 = generateInstanceKey(componentRef.current, isIsolated, options?.instanceId);
+		const instance = BlocClass.resolve(instanceKey$1, options?.staticProps);
 		const { useManualDeps, autoTrackEnabled } = determineTrackingMode(options);
-		const hookState$1 = {
-			tracker: null,
-			manualDepsCache: null,
-			getterTracker: null,
-			proxiedBloc: null
-		};
 		let subscribeFn;
 		let getSnapshotFn;
-		if (useManualDeps) {
-			subscribeFn = createManualDepsSubscribe(instance, hookState$1, options);
-			getSnapshotFn = createManualDepsSnapshot(instance, hookState$1, options);
-			hookState$1.proxiedBloc = instance;
+		let adapterState$1;
+		if (useManualDeps && options?.dependencies) {
+			adapterState$1 = initManualDepsState(instance);
+			subscribeFn = createManualDepsSubscribe(instance, adapterState$1, { dependencies: options.dependencies });
+			getSnapshotFn = createManualDepsSnapshot(instance, adapterState$1, { dependencies: options.dependencies });
 		} else if (!autoTrackEnabled) {
+			adapterState$1 = initNoTrackState(instance);
 			subscribeFn = createNoTrackSubscribe(instance);
 			getSnapshotFn = createNoTrackSnapshot(instance);
-			hookState$1.proxiedBloc = instance;
 		} else {
-			subscribeFn = createAutoTrackSubscribe(instance, hookState$1);
-			getSnapshotFn = createAutoTrackSnapshot(instance, hookState$1);
-			hookState$1.getterTracker = createGetterTracker();
-			hookState$1.proxiedBloc = createBlocProxy(instance);
+			adapterState$1 = initAutoTrackState(instance);
+			subscribeFn = createAutoTrackSubscribe(instance, adapterState$1);
+			getSnapshotFn = createAutoTrackSnapshot(instance, adapterState$1);
 		}
 		return [
-			hookState$1.proxiedBloc,
+			adapterState$1.proxiedBloc,
 			subscribeFn,
 			getSnapshotFn,
-			instanceId,
-			hookState$1,
+			instanceKey$1,
+			adapterState$1,
 			instance
 		];
-	}, [BlocClass]);
+	}, [BlocClass, options?.instanceId]);
 	const state = useSyncExternalStore(subscribe, getSnapshot);
+	const [, forceUpdate] = useReducer((x) => x + 1, 0);
+	const externalDepsManager = useRef(new ExternalDependencyManager());
 	useEffect(() => {
-		if (hookState.getterTracker) {
-			hookState.getterTracker.isTracking = false;
-			hookState.getterTracker.cacheValid = false;
-			activeTrackerMap.delete(rawInstance);
-		}
+		disableGetterTracking(adapterState, rawInstance);
+		externalDepsManager.current.updateSubscriptions(adapterState.getterTracker, rawInstance, forceUpdate);
 	});
 	useEffect(() => {
 		if (options?.onMount) options.onMount(bloc);
 		return () => {
+			externalDepsManager.current.cleanup();
 			if (options?.onUnmount) options.onUnmount(bloc);
-			BlocClass.release(instanceKey);
-			if (BlocClass.isolated === true && !rawInstance.isDisposed) rawInstance.dispose();
+			Constructor.release(instanceKey);
+			if (isIsolated && !rawInstance.isDisposed) rawInstance.dispose();
 		};
 	}, []);
 	return [
@@ -323,45 +109,20 @@ function useBloc(BlocClass, options) {
 
 //#endregion
 //#region src/useBlocActions.ts
-/**
-* Generates instance ID for isolated blocs
-*/
-function generateInstanceId(componentRef, isIsolated, providedId) {
-	if (providedId) return providedId;
-	if (isIsolated) {
-		if (!componentRef.__blocInstanceId) componentRef.__blocInstanceId = `isolated-${Math.random().toString(36).slice(2, 11)}`;
-		return componentRef.__blocInstanceId;
-	}
-}
-/**
-* React hook for accessing bloc instance without state subscription.
-* Use this when you only need to call bloc methods/actions without reading state.
-*
-* Benefits over useBloc:
-* - No state subscription overhead
-* - No proxy tracking
-* - Component never re-renders due to bloc state changes
-* - Lighter weight for action-only components
-*
-* @template TBloc - The StateContainer type
-* @param BlocClass - The bloc class constructor
-* @param options - Optional configuration
-* @returns The bloc instance
-*/
 function useBlocActions(BlocClass, options) {
 	const componentRef = useRef({});
 	const [bloc, instanceKey] = useMemo(() => {
-		const isIsolated = BlocClass.isolated === true;
+		const isIsolated = isIsolatedClass(BlocClass);
 		const Constructor = BlocClass;
-		const instanceId = generateInstanceId(componentRef.current, isIsolated, options?.instanceId);
-		return [Constructor.getOrCreate(instanceId, options?.staticProps), instanceId];
+		const instanceKey$1 = generateInstanceKey(componentRef.current, isIsolated, options?.instanceId);
+		return [options?.staticProps ? Constructor.resolve(instanceKey$1, options.staticProps) : Constructor.resolve(instanceKey$1), instanceKey$1];
 	}, [BlocClass]);
 	useEffect(() => {
 		if (options?.onMount) options.onMount(bloc);
 		return () => {
 			if (options?.onUnmount) options.onUnmount(bloc);
 			BlocClass.release(instanceKey);
-			if (BlocClass.isolated === true && !bloc.isDisposed) bloc.dispose();
+			if (isIsolatedClass(BlocClass) && !bloc.isDisposed) bloc.dispose();
 		};
 	}, []);
 	return bloc;

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+import type { ExtractState } from '@blac/core';
+import type { RefObject } from 'react';
+export interface UseBlocOptions<TBloc> {
+    staticProps?: any;
+    instanceId?: string | number;
+    dependencies?: (state: ExtractState<TBloc>, bloc: TBloc) => unknown[];
+    autoTrack?: boolean;
+    disableGetterCache?: boolean;
+    onMount?: (bloc: TBloc) => void;
+    onUnmount?: (bloc: TBloc) => void;
+}
+export interface UseBlocOptionsWithDependencies<TBloc> extends UseBlocOptions<TBloc> {
+    dependencies: (state: ExtractState<TBloc>, bloc: TBloc) => unknown[];
+    autoTrack?: never;
+}
+export type UseBlocReturn<TBloc> = [
+    ExtractState<TBloc>,
+    TBloc,
+    RefObject<ComponentRef>
+];
+export type ComponentRef = {
+    __blocInstanceId?: string;
+    __bridge?: any;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/useBloc.d.ts

@@ -0,0 +1,21 @@
+import { type BlocConstructor, StateContainer } from '@blac/core';
+import type { UseBlocOptions, UseBlocReturn } from './types';
+/**
+ * Lifecycle: INITIAL MOUNT
+ * 1. useMemo runs once - creates bloc, subscribeFn, getSnapshotFn
+ * 2. useSyncExternalStore calls getSnapshotFn (1st time) - lazy creates tracker, starts tracking, returns proxy
+ * 3. Component renders - proxy tracks property accesses
+ * 4. useSyncExternalStore calls getSnapshotFn (2nd time) - captures tracked paths, starts new tracking, returns proxy
+ * 5. useSyncExternalStore calls subscribeFn - sets up state change listener
+ *
+ * Lifecycle: STATE CHANGE
+ * 1. Bloc state changes
+ * 2. subscribeFn callback checks hasChanges() - only re-renders if tracked paths changed
+ * 3. If re-render: getSnapshotFn captures previous paths, starts tracking, returns proxy
+ *
+ * Lifecycle: RE-RENDER (parent re-render)
+ * 1. useMemo returns cached values (same bloc, subscribeFn, getSnapshotFn)
+ * 2. useSyncExternalStore calls getSnapshotFn - captures paths, starts tracking, returns proxy
+ */
+export declare function useBloc<T extends new (...args: any[]) => StateContainer<any>>(BlocClass: T & BlocConstructor<InstanceType<T>>, options?: UseBlocOptions<InstanceType<T>>): UseBlocReturn<InstanceType<T>>;
+//# sourceMappingURL=useBloc.d.ts.map

package/dist/useBlocActions.d.ts

@@ -0,0 +1,9 @@
+import { type BlocConstructor, StateContainer } from '@blac/core';
+export interface UseBlocActionsOptions<TBloc> {
+    staticProps?: any;
+    instanceId?: string | number;
+    onMount?: (bloc: TBloc) => void;
+    onUnmount?: (bloc: TBloc) => void;
+}
+export declare function useBlocActions<T extends new (...args: any[]) => StateContainer<any>>(BlocClass: T & BlocConstructor<InstanceType<T>>, options?: UseBlocActionsOptions<InstanceType<T>>): InstanceType<T>;
+//# sourceMappingURL=useBlocActions.d.ts.map

package/dist/utils/instance-keys.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Instance key generation utilities for React integration
+ */
+import type { ComponentRef } from '../types';
+/**
+ * Generate an instance key for a bloc
+ *
+ * Logic:
+ * - If user provides instanceId, use it (convert number to string)
+ * - If isolated, generate or reuse a unique key for this component
+ * - Otherwise, return undefined (use default key)
+ *
+ * @param componentRef - React component reference (persists across remounts)
+ * @param isIsolated - Whether the bloc is isolated
+ * @param providedId - User-provided instance ID (from options)
+ * @returns Instance key string or undefined for default
+ */
+export declare function generateInstanceKey(componentRef: ComponentRef, isIsolated: boolean, providedId?: string | number): string | undefined;
+//# sourceMappingURL=instance-keys.d.ts.map