@blac/react 2.0.6 → 2.0.8

package/README.md

@@ -1,9 +1,9 @@
 # @blac/react
 
-> ⚠️ **Warning:** This project is currently under active development. The API may change in future releases. Use with caution in production environments.
-
 React integration for BlaC with automatic re-render optimization.
 
+**[Full documentation](https://jsnanigans.github.io/blac/react/getting-started)**
+
 ## Installation
 
 ```bash
@@ -122,19 +122,6 @@ function B() {
 }
 ```
 
-### Isolated Instances
-
-```tsx
-import { Cubit, blac } from '@blac/core';
-
-@blac({ isolated: true })
-class FormCubit extends Cubit<FormState> {}
-
-function FormA() {
-  useBloc(FormCubit); // unique instance per component
-}
-```
-
 ### Named Instances
 
 ```tsx

package/dist/index.cjs

@@ -1,30 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let react = require("react");
 let _blac_adapter = require("@blac/adapter");
-//#region src/utils/instance-keys.ts
-/**
-* Instance key generation utilities for React integration
-*/
-/**
-* 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
-*/
-function generateInstanceKey(componentRef, isIsolated, providedId) {
-	if (providedId !== void 0) return typeof providedId === "number" ? String(providedId) : providedId;
-	if (isIsolated) {
-		if (!componentRef.__blocInstanceId) componentRef.__blocInstanceId = (0, _blac_adapter.generateIsolatedKey)();
-		return componentRef.__blocInstanceId;
-	}
-}
 let globalConfig = { autoTrack: true };
 /**
 * Configure global defaults for @blac/react hooks.
@@ -89,7 +65,7 @@ function determineTrackingMode(options) {
 * });
 * ```
 *
-* @example With isolated instance
+* @example With named instance
 * ```ts
 * const [state, myBloc] = useBloc(MyBloc, {
 *   instanceId: 'unique-id'
@@ -98,14 +74,13 @@ function determineTrackingMode(options) {
 */
 function useBloc(BlocClass, options) {
 	const componentRef = (0, react.useRef)({});
-	const isIsolated = (0, _blac_adapter.isIsolatedClass)(BlocClass);
 	const depsRef = (0, react.useRef)(options?.dependencies);
 	depsRef.current = options?.dependencies;
 	const instanceId = options?.instanceId;
 	const autoTrack = options?.autoTrack;
 	const dependencies = options?.dependencies;
 	const [bloc, subscribe, getSnapshot, instanceKey, adapterState, rawInstance] = (0, react.useMemo)(() => {
-		const instanceKey = generateInstanceKey(componentRef.current, isIsolated, instanceId);
+		const instanceKey = instanceId !== void 0 ? String(instanceId) : void 0;
 		const instance = (0, _blac_adapter.acquire)(BlocClass, instanceKey);
 		const { useManualDeps, autoTrackEnabled } = determineTrackingMode({
 			autoTrack,
@@ -131,20 +106,20 @@ function useBloc(BlocClass, options) {
 			subscribeFn = (0, _blac_adapter.autoTrackSubscribe)(instance, adapterState);
 			getSnapshotFn = (0, _blac_adapter.autoTrackSnapshot)(instance, adapterState);
 		}
+		const safeSubscribeFn = (callback) => {
+			if (instance.isDisposed) return () => {};
+			return subscribeFn(callback);
+		};
 		return [
 			adapterState.proxiedBloc,
-			subscribeFn,
+			safeSubscribeFn,
 			getSnapshotFn,
 			instanceKey,
 			adapterState,
 			instance
 		];
-	}, [
-		BlocClass,
-		isIsolated,
-		instanceId
-	]);
-	const state = (0, react.useSyncExternalStore)(subscribe, getSnapshot);
+	}, [BlocClass, instanceId]);
+	const state = (0, react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
 	const [, forceUpdate] = (0, react.useReducer)((x) => x + 1, 0);
 	const externalDepsManager = (0, react.useRef)(new _blac_adapter.ExternalDepsManager());
 	(0, react.useEffect)(() => {
@@ -159,7 +134,6 @@ function useBloc(BlocClass, options) {
 			manager.cleanup();
 			if (options?.onUnmount) options.onUnmount(bloc);
 			(0, _blac_adapter.release)(BlocClass, instanceKey);
-			if (isIsolated && !rawInstance.isDisposed) rawInstance.dispose();
 		};
 	}, []);
 	return [

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["ExternalDepsManager"],"sources":["../src/utils/instance-keys.ts","../src/config.ts","../src/useBloc.ts"],"sourcesContent":["/**\n * Instance key generation utilities for React integration\n */\n\nimport { generateIsolatedKey } from '@blac/adapter';\nimport type { ComponentRef } from '../types';\n\n/**\n * Generate an instance key for a bloc\n *\n * Logic:\n * - If user provides instanceId, use it (convert number to string)\n * - If isolated, generate or reuse a unique key for this component\n * - Otherwise, return undefined (use default key)\n *\n * @param componentRef - React component reference (persists across remounts)\n * @param isIsolated - Whether the bloc is isolated\n * @param providedId - User-provided instance ID (from options)\n * @returns Instance key string or undefined for default\n */\nexport function generateInstanceKey(\n  componentRef: ComponentRef,\n  isIsolated: boolean,\n  providedId?: string | number,\n): string | undefined {\n  // User explicitly provided an ID - use it\n  if (providedId !== undefined) {\n    return typeof providedId === 'number' ? String(providedId) : providedId;\n  }\n\n  // Isolated bloc - generate unique key per component\n  if (isIsolated) {\n    if (!componentRef.__blocInstanceId) {\n      componentRef.__blocInstanceId = generateIsolatedKey();\n    }\n    return componentRef.__blocInstanceId;\n  }\n\n  // Shared bloc - use default key (undefined)\n  return undefined;\n}\n","/**\n * Global configuration for @blac/react\n */\n\nexport interface BlacReactConfig {\n  /** Enable automatic property tracking via Proxy (default: true) */\n  autoTrack: boolean;\n}\n\nconst defaultConfig: BlacReactConfig = {\n  autoTrack: true,\n};\n\nlet globalConfig: BlacReactConfig = { ...defaultConfig };\n\n/**\n * Configure global defaults for @blac/react hooks.\n *\n * @example\n * ```ts\n * import { configureBlacReact } from '@blac/react';\n *\n * // Disable auto-tracking globally\n * configureBlacReact({\n *   autoTrack: false\n * });\n * ```\n *\n * @param config - Partial configuration to merge with defaults\n */\nexport function configureBlacReact(config: Partial<BlacReactConfig>): void {\n  globalConfig = { ...globalConfig, ...config };\n}\n\n/**\n * Get the current global configuration.\n * @internal\n */\nexport function getBlacReactConfig(): BlacReactConfig {\n  return globalConfig;\n}\n\n/**\n * Reset configuration to defaults (useful for testing).\n * @internal\n */\nexport function resetBlacReactConfig(): void {\n  globalConfig = { ...defaultConfig };\n}\n","import {\n  useMemo,\n  useSyncExternalStore,\n  useEffect,\n  useRef,\n  useReducer,\n} from 'react';\nimport {\n  type ExtractState,\n  type AdapterState,\n  ExternalDepsManager,\n  autoTrackSubscribe,\n  manualDepsSubscribe,\n  noTrackSubscribe,\n  autoTrackSnapshot,\n  manualDepsSnapshot,\n  noTrackSnapshot,\n  autoTrackInit,\n  manualDepsInit,\n  noTrackInit,\n  disableGetterTracking,\n  isIsolatedClass,\n  type StateContainerConstructor,\n  type InstanceState,\n  acquire,\n  release,\n} from '@blac/adapter';\nimport type { UseBlocOptions, UseBlocReturn, ComponentRef } from './types';\nimport { generateInstanceKey } from './utils/instance-keys';\nimport { getBlacReactConfig } from './config';\n\ninterface TrackingMode {\n  useManualDeps: boolean;\n  autoTrackEnabled: boolean;\n}\n\nfunction determineTrackingMode<TBloc extends StateContainerConstructor>(\n  options?: Pick<UseBlocOptions<TBloc>, 'autoTrack' | 'dependencies'>,\n): TrackingMode {\n  const globalConfig = getBlacReactConfig();\n  const autoTrackEnabled =\n    options?.autoTrack !== undefined\n      ? options.autoTrack\n      : globalConfig.autoTrack;\n\n  return {\n    useManualDeps: options?.dependencies !== undefined,\n    autoTrackEnabled,\n  };\n}\n\n/**\n * React hook that connects a component to a state container with automatic re-render on state changes.\n *\n * Supports three tracking modes:\n * - **Auto-tracking** (default): Automatically detects accessed state properties via Proxy\n * - **Manual dependencies**: Explicit dependency array like useEffect\n * - **No tracking**: Returns full state without optimization\n *\n * @template T - The state container constructor type (inferred from BlocClass)\n * @param BlocClass - The state container class to connect to\n * @param options - Configuration options for tracking mode and instance management\n * @returns Tuple with [state, bloc instance, ref]\n *\n * @example Basic usage\n * ```ts\n * const [state, myBloc, ref] = useBloc(MyBloc);\n * ```\n *\n * @example With manual dependencies\n * ```ts\n * const [state, myBloc] = useBloc(MyBloc, {\n *   dependencies: (state) => [state.count]\n * });\n * ```\n *\n * @example With isolated instance\n * ```ts\n * const [state, myBloc] = useBloc(MyBloc, {\n *   instanceId: 'unique-id'\n * });\n * ```\n */\nexport function useBloc<\n  T extends StateContainerConstructor = StateContainerConstructor,\n>(\n  BlocClass: T,\n  options?: UseBlocOptions<T>,\n): UseBlocReturn<T, ExtractState<T>> {\n  type TBloc = InstanceState<T>;\n\n  const componentRef = useRef<ComponentRef>({});\n  const isIsolated = isIsolatedClass(BlocClass);\n  const depsRef = useRef(options?.dependencies);\n  depsRef.current = options?.dependencies;\n  const instanceId = options?.instanceId;\n  const autoTrack = options?.autoTrack;\n  const dependencies = options?.dependencies;\n\n  const [bloc, subscribe, getSnapshot, instanceKey, adapterState, rawInstance] =\n    useMemo<\n      readonly [\n        TBloc,\n        (callback: () => void) => () => void,\n        () => ExtractState<T>,\n        string | undefined,\n        AdapterState<T>,\n        TBloc,\n      ]\n    >(() => {\n      const instanceKey = generateInstanceKey(\n        componentRef.current,\n        isIsolated,\n        instanceId,\n      );\n\n      const instance = acquire(BlocClass, instanceKey) as TBloc;\n\n      const { useManualDeps, autoTrackEnabled } = determineTrackingMode({\n        autoTrack,\n        dependencies,\n      });\n\n      let subscribeFn: (callback: () => void) => () => void;\n      let getSnapshotFn: () => ExtractState<T>;\n      let adapterState: AdapterState<T>;\n\n      if (useManualDeps && dependencies) {\n        adapterState = manualDepsInit(instance);\n        const stableConfig = {\n          dependencies: (state: ExtractState<T>, bloc: InstanceState<T>) => {\n            const deps = depsRef.current;\n            return deps ? deps(state, bloc) : [];\n          },\n        };\n        subscribeFn = manualDepsSubscribe(instance, adapterState, stableConfig);\n        getSnapshotFn = manualDepsSnapshot(\n          instance,\n          adapterState,\n          stableConfig,\n        );\n      } else if (!autoTrackEnabled) {\n        adapterState = noTrackInit(instance);\n        subscribeFn = noTrackSubscribe(instance);\n        getSnapshotFn = noTrackSnapshot(instance);\n      } else {\n        adapterState = autoTrackInit(instance);\n        subscribeFn = autoTrackSubscribe(instance, adapterState);\n        getSnapshotFn = autoTrackSnapshot(instance, adapterState);\n      }\n\n      return [\n        adapterState.proxiedBloc as TBloc,\n        subscribeFn,\n        getSnapshotFn,\n        instanceKey,\n        adapterState,\n        instance,\n      ];\n      // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [BlocClass, isIsolated, instanceId]);\n\n  const state = useSyncExternalStore(subscribe, getSnapshot);\n\n  const [, forceUpdate] = useReducer((x: number) => x + 1, 0);\n\n  const externalDepsManager = useRef(new ExternalDepsManager());\n\n  useEffect(() => {\n    const manager = externalDepsManager.current;\n    disableGetterTracking(adapterState, rawInstance);\n    manager.updateSubscriptions(\n      adapterState.getterState,\n      rawInstance,\n      forceUpdate,\n    );\n  });\n\n  useEffect(() => {\n    const manager = externalDepsManager.current;\n    if (options?.onMount) {\n      options.onMount(bloc as InstanceType<T>);\n    }\n\n    return () => {\n      manager.cleanup();\n\n      if (options?.onUnmount) {\n        options.onUnmount(bloc as InstanceType<T>);\n      }\n\n      release(BlocClass, instanceKey);\n\n      if (isIsolated && !rawInstance.isDisposed) {\n        rawInstance.dispose();\n      }\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  return [state, bloc, componentRef] as UseBlocReturn<T, ExtractState<T>>;\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.cjs","names":["ExternalDepsManager"],"sources":["../src/config.ts","../src/useBloc.ts"],"sourcesContent":["/**\n * Global configuration for @blac/react\n */\n\nexport interface BlacReactConfig {\n  /** Enable automatic property tracking via Proxy (default: true) */\n  autoTrack: boolean;\n}\n\nconst defaultConfig: BlacReactConfig = {\n  autoTrack: true,\n};\n\nlet globalConfig: BlacReactConfig = { ...defaultConfig };\n\n/**\n * Configure global defaults for @blac/react hooks.\n *\n * @example\n * ```ts\n * import { configureBlacReact } from '@blac/react';\n *\n * // Disable auto-tracking globally\n * configureBlacReact({\n *   autoTrack: false\n * });\n * ```\n *\n * @param config - Partial configuration to merge with defaults\n */\nexport function configureBlacReact(config: Partial<BlacReactConfig>): void {\n  globalConfig = { ...globalConfig, ...config };\n}\n\n/**\n * Get the current global configuration.\n * @internal\n */\nexport function getBlacReactConfig(): BlacReactConfig {\n  return globalConfig;\n}\n\n/**\n * Reset configuration to defaults (useful for testing).\n * @internal\n */\nexport function resetBlacReactConfig(): void {\n  globalConfig = { ...defaultConfig };\n}\n","import {\n  useMemo,\n  useSyncExternalStore,\n  useEffect,\n  useRef,\n  useReducer,\n} from 'react';\nimport {\n  type ExtractState,\n  type AdapterState,\n  ExternalDepsManager,\n  autoTrackSubscribe,\n  manualDepsSubscribe,\n  noTrackSubscribe,\n  autoTrackSnapshot,\n  manualDepsSnapshot,\n  noTrackSnapshot,\n  autoTrackInit,\n  manualDepsInit,\n  noTrackInit,\n  disableGetterTracking,\n  type StateContainerConstructor,\n  type InstanceState,\n  acquire,\n  release,\n} from '@blac/adapter';\nimport type { UseBlocOptions, UseBlocReturn, ComponentRef } from './types';\nimport { getBlacReactConfig } from './config';\n\ninterface TrackingMode {\n  useManualDeps: boolean;\n  autoTrackEnabled: boolean;\n}\n\nfunction determineTrackingMode<TBloc extends StateContainerConstructor>(\n  options?: Pick<UseBlocOptions<TBloc>, 'autoTrack' | 'dependencies'>,\n): TrackingMode {\n  const globalConfig = getBlacReactConfig();\n  const autoTrackEnabled =\n    options?.autoTrack !== undefined\n      ? options.autoTrack\n      : globalConfig.autoTrack;\n\n  return {\n    useManualDeps: options?.dependencies !== undefined,\n    autoTrackEnabled,\n  };\n}\n\n/**\n * React hook that connects a component to a state container with automatic re-render on state changes.\n *\n * Supports three tracking modes:\n * - **Auto-tracking** (default): Automatically detects accessed state properties via Proxy\n * - **Manual dependencies**: Explicit dependency array like useEffect\n * - **No tracking**: Returns full state without optimization\n *\n * @template T - The state container constructor type (inferred from BlocClass)\n * @param BlocClass - The state container class to connect to\n * @param options - Configuration options for tracking mode and instance management\n * @returns Tuple with [state, bloc instance, ref]\n *\n * @example Basic usage\n * ```ts\n * const [state, myBloc, ref] = useBloc(MyBloc);\n * ```\n *\n * @example With manual dependencies\n * ```ts\n * const [state, myBloc] = useBloc(MyBloc, {\n *   dependencies: (state) => [state.count]\n * });\n * ```\n *\n * @example With named instance\n * ```ts\n * const [state, myBloc] = useBloc(MyBloc, {\n *   instanceId: 'unique-id'\n * });\n * ```\n */\nexport function useBloc<\n  T extends StateContainerConstructor = StateContainerConstructor,\n>(\n  BlocClass: T,\n  options?: UseBlocOptions<T>,\n): UseBlocReturn<T, ExtractState<T>> {\n  type TBloc = InstanceState<T>;\n\n  const componentRef = useRef<ComponentRef>({});\n  const depsRef = useRef(options?.dependencies);\n  depsRef.current = options?.dependencies;\n  const instanceId = options?.instanceId;\n  const autoTrack = options?.autoTrack;\n  const dependencies = options?.dependencies;\n\n  const [bloc, subscribe, getSnapshot, instanceKey, adapterState, rawInstance] =\n    useMemo<\n      readonly [\n        TBloc,\n        (callback: () => void) => () => void,\n        () => ExtractState<T>,\n        string | undefined,\n        AdapterState<T>,\n        TBloc,\n      ]\n    >(() => {\n      const instanceKey =\n        instanceId !== undefined ? String(instanceId) : undefined;\n\n      const instance = acquire(BlocClass, instanceKey) as TBloc;\n\n      const { useManualDeps, autoTrackEnabled } = determineTrackingMode({\n        autoTrack,\n        dependencies,\n      });\n\n      let subscribeFn: (callback: () => void) => () => void;\n      let getSnapshotFn: () => ExtractState<T>;\n      let adapterState: AdapterState<T>;\n\n      if (useManualDeps && dependencies) {\n        adapterState = manualDepsInit(instance);\n        const stableConfig = {\n          dependencies: (state: ExtractState<T>, bloc: InstanceState<T>) => {\n            const deps = depsRef.current;\n            return deps ? deps(state, bloc) : [];\n          },\n        };\n        subscribeFn = manualDepsSubscribe(instance, adapterState, stableConfig);\n        getSnapshotFn = manualDepsSnapshot(\n          instance,\n          adapterState,\n          stableConfig,\n        );\n      } else if (!autoTrackEnabled) {\n        adapterState = noTrackInit(instance);\n        subscribeFn = noTrackSubscribe(instance);\n        getSnapshotFn = noTrackSnapshot(instance);\n      } else {\n        adapterState = autoTrackInit(instance);\n        subscribeFn = autoTrackSubscribe(instance, adapterState);\n        getSnapshotFn = autoTrackSnapshot(instance, adapterState);\n      }\n\n      const safeSubscribeFn = (callback: () => void) => {\n        if (instance.isDisposed) return () => {};\n        return subscribeFn(callback);\n      };\n\n      return [\n        adapterState.proxiedBloc as TBloc,\n        safeSubscribeFn,\n        getSnapshotFn,\n        instanceKey,\n        adapterState,\n        instance,\n      ];\n      // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [BlocClass, instanceId]);\n\n  const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  const [, forceUpdate] = useReducer((x: number) => x + 1, 0);\n\n  const externalDepsManager = useRef(new ExternalDepsManager());\n\n  useEffect(() => {\n    const manager = externalDepsManager.current;\n    disableGetterTracking(adapterState, rawInstance);\n    manager.updateSubscriptions(\n      adapterState.getterState,\n      rawInstance,\n      forceUpdate,\n    );\n  });\n\n  useEffect(() => {\n    const manager = externalDepsManager.current;\n    if (options?.onMount) {\n      options.onMount(bloc as InstanceType<T>);\n    }\n\n    return () => {\n      manager.cleanup();\n\n      if (options?.onUnmount) {\n        options.onUnmount(bloc as InstanceType<T>);\n      }\n\n      release(BlocClass, instanceKey);\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  return [state, bloc, componentRef] as UseBlocReturn<T, ExtractState<T>>;\n}\n"],"mappings":";;;AAaA,IAAI,eAAgC,EAHlC,WAAW,MAG2C;;;;;;;;;;;;;;;;AAiBxD,SAAgB,mBAAmB,QAAwC;AACzE,gBAAe;EAAE,GAAG;EAAc,GAAG;EAAQ;;;;;;AAO/C,SAAgB,qBAAsC;AACpD,QAAO;;;;ACLT,SAAS,sBACP,SACc;CACd,MAAM,eAAe,oBAAoB;CACzC,MAAM,mBACJ,SAAS,cAAc,KAAA,IACnB,QAAQ,YACR,aAAa;AAEnB,QAAO;EACL,eAAe,SAAS,iBAAiB,KAAA;EACzC;EACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCH,SAAgB,QAGd,WACA,SACmC;CAGnC,MAAM,gBAAA,GAAA,MAAA,QAAoC,EAAE,CAAC;CAC7C,MAAM,WAAA,GAAA,MAAA,QAAiB,SAAS,aAAa;AAC7C,SAAQ,UAAU,SAAS;CAC3B,MAAM,aAAa,SAAS;CAC5B,MAAM,YAAY,SAAS;CAC3B,MAAM,eAAe,SAAS;CAE9B,MAAM,CAAC,MAAM,WAAW,aAAa,aAAa,cAAc,gBAAA,GAAA,MAAA,eAUtD;EACN,MAAM,cACJ,eAAe,KAAA,IAAY,OAAO,WAAW,GAAG,KAAA;EAElD,MAAM,YAAA,GAAA,cAAA,SAAmB,WAAW,YAAY;EAEhD,MAAM,EAAE,eAAe,qBAAqB,sBAAsB;GAChE;GACA;GACD,CAAC;EAEF,IAAI;EACJ,IAAI;EACJ,IAAI;AAEJ,MAAI,iBAAiB,cAAc;AACjC,mBAAA,GAAA,cAAA,gBAA8B,SAAS;GACvC,MAAM,eAAe,EACnB,eAAe,OAAwB,SAA2B;IAChE,MAAM,OAAO,QAAQ;AACrB,WAAO,OAAO,KAAK,OAAO,KAAK,GAAG,EAAE;MAEvC;AACD,kBAAA,GAAA,cAAA,qBAAkC,UAAU,cAAc,aAAa;AACvE,oBAAA,GAAA,cAAA,oBACE,UACA,cACA,aACD;aACQ,CAAC,kBAAkB;AAC5B,mBAAA,GAAA,cAAA,aAA2B,SAAS;AACpC,kBAAA,GAAA,cAAA,kBAA+B,SAAS;AACxC,oBAAA,GAAA,cAAA,iBAAgC,SAAS;SACpC;AACL,mBAAA,GAAA,cAAA,eAA6B,SAAS;AACtC,kBAAA,GAAA,cAAA,oBAAiC,UAAU,aAAa;AACxD,oBAAA,GAAA,cAAA,mBAAkC,UAAU,aAAa;;EAG3D,MAAM,mBAAmB,aAAyB;AAChD,OAAI,SAAS,WAAY,cAAa;AACtC,UAAO,YAAY,SAAS;;AAG9B,SAAO;GACL,aAAa;GACb;GACA;GACA;GACA;GACA;GACD;IAEA,CAAC,WAAW,WAAW,CAAC;CAE7B,MAAM,SAAA,GAAA,MAAA,sBAA6B,WAAW,aAAa,YAAY;CAEvE,MAAM,GAAG,gBAAA,GAAA,MAAA,aAA2B,MAAc,IAAI,GAAG,EAAE;CAE3D,MAAM,uBAAA,GAAA,MAAA,QAA6B,IAAIA,cAAAA,qBAAqB,CAAC;AAE7D,EAAA,GAAA,MAAA,iBAAgB;EACd,MAAM,UAAU,oBAAoB;AACpC,GAAA,GAAA,cAAA,uBAAsB,cAAc,YAAY;AAChD,UAAQ,oBACN,aAAa,aACb,aACA,YACD;GACD;AAEF,EAAA,GAAA,MAAA,iBAAgB;EACd,MAAM,UAAU,oBAAoB;AACpC,MAAI,SAAS,QACX,SAAQ,QAAQ,KAAwB;AAG1C,eAAa;AACX,WAAQ,SAAS;AAEjB,OAAI,SAAS,UACX,SAAQ,UAAU,KAAwB;AAG5C,IAAA,GAAA,cAAA,SAAQ,WAAW,YAAY;;IAGhC,EAAE,CAAC;AAEN,QAAO;EAAC;EAAO;EAAM;EAAa"}

package/dist/index.js

@@ -1,29 +1,5 @@
 import { useEffect, useMemo, useReducer, useRef, useSyncExternalStore } from "react";
-import { ExternalDepsManager, acquire, autoTrackInit, autoTrackSnapshot, autoTrackSubscribe, disableGetterTracking, generateIsolatedKey, isIsolatedClass, manualDepsInit, manualDepsSnapshot, manualDepsSubscribe, noTrackInit, noTrackSnapshot, noTrackSubscribe, release } from "@blac/adapter";
-//#region src/utils/instance-keys.ts
-/**
-* Instance key generation utilities for React integration
-*/
-/**
-* 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
-*/
-function generateInstanceKey(componentRef, isIsolated, providedId) {
-	if (providedId !== void 0) return typeof providedId === "number" ? String(providedId) : providedId;
-	if (isIsolated) {
-		if (!componentRef.__blocInstanceId) componentRef.__blocInstanceId = generateIsolatedKey();
-		return componentRef.__blocInstanceId;
-	}
-}
+import { ExternalDepsManager, acquire, autoTrackInit, autoTrackSnapshot, autoTrackSubscribe, disableGetterTracking, manualDepsInit, manualDepsSnapshot, manualDepsSubscribe, noTrackInit, noTrackSnapshot, noTrackSubscribe, release } from "@blac/adapter";
 let globalConfig = { autoTrack: true };
 /**
 * Configure global defaults for @blac/react hooks.
@@ -88,7 +64,7 @@ function determineTrackingMode(options) {
 * });
 * ```
 *
-* @example With isolated instance
+* @example With named instance
 * ```ts
 * const [state, myBloc] = useBloc(MyBloc, {
 *   instanceId: 'unique-id'
@@ -97,14 +73,13 @@ function determineTrackingMode(options) {
 */
 function useBloc(BlocClass, options) {
 	const componentRef = useRef({});
-	const isIsolated = isIsolatedClass(BlocClass);
 	const depsRef = useRef(options?.dependencies);
 	depsRef.current = options?.dependencies;
 	const instanceId = options?.instanceId;
 	const autoTrack = options?.autoTrack;
 	const dependencies = options?.dependencies;
 	const [bloc, subscribe, getSnapshot, instanceKey, adapterState, rawInstance] = useMemo(() => {
-		const instanceKey = generateInstanceKey(componentRef.current, isIsolated, instanceId);
+		const instanceKey = instanceId !== void 0 ? String(instanceId) : void 0;
 		const instance = acquire(BlocClass, instanceKey);
 		const { useManualDeps, autoTrackEnabled } = determineTrackingMode({
 			autoTrack,
@@ -130,20 +105,20 @@ function useBloc(BlocClass, options) {
 			subscribeFn = autoTrackSubscribe(instance, adapterState);
 			getSnapshotFn = autoTrackSnapshot(instance, adapterState);
 		}
+		const safeSubscribeFn = (callback) => {
+			if (instance.isDisposed) return () => {};
+			return subscribeFn(callback);
+		};
 		return [
 			adapterState.proxiedBloc,
-			subscribeFn,
+			safeSubscribeFn,
 			getSnapshotFn,
 			instanceKey,
 			adapterState,
 			instance
 		];
-	}, [
-		BlocClass,
-		isIsolated,
-		instanceId
-	]);
-	const state = useSyncExternalStore(subscribe, getSnapshot);
+	}, [BlocClass, instanceId]);
+	const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 	const [, forceUpdate] = useReducer((x) => x + 1, 0);
 	const externalDepsManager = useRef(new ExternalDepsManager());
 	useEffect(() => {
@@ -158,7 +133,6 @@ function useBloc(BlocClass, options) {
 			manager.cleanup();
 			if (options?.onUnmount) options.onUnmount(bloc);
 			release(BlocClass, instanceKey);
-			if (isIsolated && !rawInstance.isDisposed) rawInstance.dispose();
 		};
 	}, []);
 	return [

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/utils/instance-keys.ts","../src/config.ts","../src/useBloc.ts"],"sourcesContent":["/**\n * Instance key generation utilities for React integration\n */\n\nimport { generateIsolatedKey } from '@blac/adapter';\nimport type { ComponentRef } from '../types';\n\n/**\n * Generate an instance key for a bloc\n *\n * Logic:\n * - If user provides instanceId, use it (convert number to string)\n * - If isolated, generate or reuse a unique key for this component\n * - Otherwise, return undefined (use default key)\n *\n * @param componentRef - React component reference (persists across remounts)\n * @param isIsolated - Whether the bloc is isolated\n * @param providedId - User-provided instance ID (from options)\n * @returns Instance key string or undefined for default\n */\nexport function generateInstanceKey(\n  componentRef: ComponentRef,\n  isIsolated: boolean,\n  providedId?: string | number,\n): string | undefined {\n  // User explicitly provided an ID - use it\n  if (providedId !== undefined) {\n    return typeof providedId === 'number' ? String(providedId) : providedId;\n  }\n\n  // Isolated bloc - generate unique key per component\n  if (isIsolated) {\n    if (!componentRef.__blocInstanceId) {\n      componentRef.__blocInstanceId = generateIsolatedKey();\n    }\n    return componentRef.__blocInstanceId;\n  }\n\n  // Shared bloc - use default key (undefined)\n  return undefined;\n}\n","/**\n * Global configuration for @blac/react\n */\n\nexport interface BlacReactConfig {\n  /** Enable automatic property tracking via Proxy (default: true) */\n  autoTrack: boolean;\n}\n\nconst defaultConfig: BlacReactConfig = {\n  autoTrack: true,\n};\n\nlet globalConfig: BlacReactConfig = { ...defaultConfig };\n\n/**\n * Configure global defaults for @blac/react hooks.\n *\n * @example\n * ```ts\n * import { configureBlacReact } from '@blac/react';\n *\n * // Disable auto-tracking globally\n * configureBlacReact({\n *   autoTrack: false\n * });\n * ```\n *\n * @param config - Partial configuration to merge with defaults\n */\nexport function configureBlacReact(config: Partial<BlacReactConfig>): void {\n  globalConfig = { ...globalConfig, ...config };\n}\n\n/**\n * Get the current global configuration.\n * @internal\n */\nexport function getBlacReactConfig(): BlacReactConfig {\n  return globalConfig;\n}\n\n/**\n * Reset configuration to defaults (useful for testing).\n * @internal\n */\nexport function resetBlacReactConfig(): void {\n  globalConfig = { ...defaultConfig };\n}\n","import {\n  useMemo,\n  useSyncExternalStore,\n  useEffect,\n  useRef,\n  useReducer,\n} from 'react';\nimport {\n  type ExtractState,\n  type AdapterState,\n  ExternalDepsManager,\n  autoTrackSubscribe,\n  manualDepsSubscribe,\n  noTrackSubscribe,\n  autoTrackSnapshot,\n  manualDepsSnapshot,\n  noTrackSnapshot,\n  autoTrackInit,\n  manualDepsInit,\n  noTrackInit,\n  disableGetterTracking,\n  isIsolatedClass,\n  type StateContainerConstructor,\n  type InstanceState,\n  acquire,\n  release,\n} from '@blac/adapter';\nimport type { UseBlocOptions, UseBlocReturn, ComponentRef } from './types';\nimport { generateInstanceKey } from './utils/instance-keys';\nimport { getBlacReactConfig } from './config';\n\ninterface TrackingMode {\n  useManualDeps: boolean;\n  autoTrackEnabled: boolean;\n}\n\nfunction determineTrackingMode<TBloc extends StateContainerConstructor>(\n  options?: Pick<UseBlocOptions<TBloc>, 'autoTrack' | 'dependencies'>,\n): TrackingMode {\n  const globalConfig = getBlacReactConfig();\n  const autoTrackEnabled =\n    options?.autoTrack !== undefined\n      ? options.autoTrack\n      : globalConfig.autoTrack;\n\n  return {\n    useManualDeps: options?.dependencies !== undefined,\n    autoTrackEnabled,\n  };\n}\n\n/**\n * React hook that connects a component to a state container with automatic re-render on state changes.\n *\n * Supports three tracking modes:\n * - **Auto-tracking** (default): Automatically detects accessed state properties via Proxy\n * - **Manual dependencies**: Explicit dependency array like useEffect\n * - **No tracking**: Returns full state without optimization\n *\n * @template T - The state container constructor type (inferred from BlocClass)\n * @param BlocClass - The state container class to connect to\n * @param options - Configuration options for tracking mode and instance management\n * @returns Tuple with [state, bloc instance, ref]\n *\n * @example Basic usage\n * ```ts\n * const [state, myBloc, ref] = useBloc(MyBloc);\n * ```\n *\n * @example With manual dependencies\n * ```ts\n * const [state, myBloc] = useBloc(MyBloc, {\n *   dependencies: (state) => [state.count]\n * });\n * ```\n *\n * @example With isolated instance\n * ```ts\n * const [state, myBloc] = useBloc(MyBloc, {\n *   instanceId: 'unique-id'\n * });\n * ```\n */\nexport function useBloc<\n  T extends StateContainerConstructor = StateContainerConstructor,\n>(\n  BlocClass: T,\n  options?: UseBlocOptions<T>,\n): UseBlocReturn<T, ExtractState<T>> {\n  type TBloc = InstanceState<T>;\n\n  const componentRef = useRef<ComponentRef>({});\n  const isIsolated = isIsolatedClass(BlocClass);\n  const depsRef = useRef(options?.dependencies);\n  depsRef.current = options?.dependencies;\n  const instanceId = options?.instanceId;\n  const autoTrack = options?.autoTrack;\n  const dependencies = options?.dependencies;\n\n  const [bloc, subscribe, getSnapshot, instanceKey, adapterState, rawInstance] =\n    useMemo<\n      readonly [\n        TBloc,\n        (callback: () => void) => () => void,\n        () => ExtractState<T>,\n        string | undefined,\n        AdapterState<T>,\n        TBloc,\n      ]\n    >(() => {\n      const instanceKey = generateInstanceKey(\n        componentRef.current,\n        isIsolated,\n        instanceId,\n      );\n\n      const instance = acquire(BlocClass, instanceKey) as TBloc;\n\n      const { useManualDeps, autoTrackEnabled } = determineTrackingMode({\n        autoTrack,\n        dependencies,\n      });\n\n      let subscribeFn: (callback: () => void) => () => void;\n      let getSnapshotFn: () => ExtractState<T>;\n      let adapterState: AdapterState<T>;\n\n      if (useManualDeps && dependencies) {\n        adapterState = manualDepsInit(instance);\n        const stableConfig = {\n          dependencies: (state: ExtractState<T>, bloc: InstanceState<T>) => {\n            const deps = depsRef.current;\n            return deps ? deps(state, bloc) : [];\n          },\n        };\n        subscribeFn = manualDepsSubscribe(instance, adapterState, stableConfig);\n        getSnapshotFn = manualDepsSnapshot(\n          instance,\n          adapterState,\n          stableConfig,\n        );\n      } else if (!autoTrackEnabled) {\n        adapterState = noTrackInit(instance);\n        subscribeFn = noTrackSubscribe(instance);\n        getSnapshotFn = noTrackSnapshot(instance);\n      } else {\n        adapterState = autoTrackInit(instance);\n        subscribeFn = autoTrackSubscribe(instance, adapterState);\n        getSnapshotFn = autoTrackSnapshot(instance, adapterState);\n      }\n\n      return [\n        adapterState.proxiedBloc as TBloc,\n        subscribeFn,\n        getSnapshotFn,\n        instanceKey,\n        adapterState,\n        instance,\n      ];\n      // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [BlocClass, isIsolated, instanceId]);\n\n  const state = useSyncExternalStore(subscribe, getSnapshot);\n\n  const [, forceUpdate] = useReducer((x: number) => x + 1, 0);\n\n  const externalDepsManager = useRef(new ExternalDepsManager());\n\n  useEffect(() => {\n    const manager = externalDepsManager.current;\n    disableGetterTracking(adapterState, rawInstance);\n    manager.updateSubscriptions(\n      adapterState.getterState,\n      rawInstance,\n      forceUpdate,\n    );\n  });\n\n  useEffect(() => {\n    const manager = externalDepsManager.current;\n    if (options?.onMount) {\n      options.onMount(bloc as InstanceType<T>);\n    }\n\n    return () => {\n      manager.cleanup();\n\n      if (options?.onUnmount) {\n        options.onUnmount(bloc as InstanceType<T>);\n      }\n\n      release(BlocClass, instanceKey);\n\n      if (isIsolated && !rawInstance.isDisposed) {\n        rawInstance.dispose();\n      }\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  return [state, bloc, componentRef] as UseBlocReturn<T, ExtractState<T>>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,oBACd,cACA,YACA,YACoB;AAEpB,KAAI,eAAe,KAAA,EACjB,QAAO,OAAO,eAAe,WAAW,OAAO,WAAW,GAAG;AAI/D,KAAI,YAAY;AACd,MAAI,CAAC,aAAa,iBAChB,cAAa,mBAAmB,qBAAqB;AAEvD,SAAO,aAAa;;;ACtBxB,IAAI,eAAgC,EAHlC,WAAW,MAG2C;;;;;;;;;;;;;;;;AAiBxD,SAAgB,mBAAmB,QAAwC;AACzE,gBAAe;EAAE,GAAG;EAAc,GAAG;EAAQ;;;;;;AAO/C,SAAgB,qBAAsC;AACpD,QAAO;;;;ACHT,SAAS,sBACP,SACc;CACd,MAAM,eAAe,oBAAoB;CACzC,MAAM,mBACJ,SAAS,cAAc,KAAA,IACnB,QAAQ,YACR,aAAa;AAEnB,QAAO;EACL,eAAe,SAAS,iBAAiB,KAAA;EACzC;EACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCH,SAAgB,QAGd,WACA,SACmC;CAGnC,MAAM,eAAe,OAAqB,EAAE,CAAC;CAC7C,MAAM,aAAa,gBAAgB,UAAU;CAC7C,MAAM,UAAU,OAAO,SAAS,aAAa;AAC7C,SAAQ,UAAU,SAAS;CAC3B,MAAM,aAAa,SAAS;CAC5B,MAAM,YAAY,SAAS;CAC3B,MAAM,eAAe,SAAS;CAE9B,MAAM,CAAC,MAAM,WAAW,aAAa,aAAa,cAAc,eAC9D,cASQ;EACN,MAAM,cAAc,oBAClB,aAAa,SACb,YACA,WACD;EAED,MAAM,WAAW,QAAQ,WAAW,YAAY;EAEhD,MAAM,EAAE,eAAe,qBAAqB,sBAAsB;GAChE;GACA;GACD,CAAC;EAEF,IAAI;EACJ,IAAI;EACJ,IAAI;AAEJ,MAAI,iBAAiB,cAAc;AACjC,kBAAe,eAAe,SAAS;GACvC,MAAM,eAAe,EACnB,eAAe,OAAwB,SAA2B;IAChE,MAAM,OAAO,QAAQ;AACrB,WAAO,OAAO,KAAK,OAAO,KAAK,GAAG,EAAE;MAEvC;AACD,iBAAc,oBAAoB,UAAU,cAAc,aAAa;AACvE,mBAAgB,mBACd,UACA,cACA,aACD;aACQ,CAAC,kBAAkB;AAC5B,kBAAe,YAAY,SAAS;AACpC,iBAAc,iBAAiB,SAAS;AACxC,mBAAgB,gBAAgB,SAAS;SACpC;AACL,kBAAe,cAAc,SAAS;AACtC,iBAAc,mBAAmB,UAAU,aAAa;AACxD,mBAAgB,kBAAkB,UAAU,aAAa;;AAG3D,SAAO;GACL,aAAa;GACb;GACA;GACA;GACA;GACA;GACD;IAEA;EAAC;EAAW;EAAY;EAAW,CAAC;CAEzC,MAAM,QAAQ,qBAAqB,WAAW,YAAY;CAE1D,MAAM,GAAG,eAAe,YAAY,MAAc,IAAI,GAAG,EAAE;CAE3D,MAAM,sBAAsB,OAAO,IAAI,qBAAqB,CAAC;AAE7D,iBAAgB;EACd,MAAM,UAAU,oBAAoB;AACpC,wBAAsB,cAAc,YAAY;AAChD,UAAQ,oBACN,aAAa,aACb,aACA,YACD;GACD;AAEF,iBAAgB;EACd,MAAM,UAAU,oBAAoB;AACpC,MAAI,SAAS,QACX,SAAQ,QAAQ,KAAwB;AAG1C,eAAa;AACX,WAAQ,SAAS;AAEjB,OAAI,SAAS,UACX,SAAQ,UAAU,KAAwB;AAG5C,WAAQ,WAAW,YAAY;AAE/B,OAAI,cAAc,CAAC,YAAY,WAC7B,aAAY,SAAS;;IAIxB,EAAE,CAAC;AAEN,QAAO;EAAC;EAAO;EAAM;EAAa"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/config.ts","../src/useBloc.ts"],"sourcesContent":["/**\n * Global configuration for @blac/react\n */\n\nexport interface BlacReactConfig {\n  /** Enable automatic property tracking via Proxy (default: true) */\n  autoTrack: boolean;\n}\n\nconst defaultConfig: BlacReactConfig = {\n  autoTrack: true,\n};\n\nlet globalConfig: BlacReactConfig = { ...defaultConfig };\n\n/**\n * Configure global defaults for @blac/react hooks.\n *\n * @example\n * ```ts\n * import { configureBlacReact } from '@blac/react';\n *\n * // Disable auto-tracking globally\n * configureBlacReact({\n *   autoTrack: false\n * });\n * ```\n *\n * @param config - Partial configuration to merge with defaults\n */\nexport function configureBlacReact(config: Partial<BlacReactConfig>): void {\n  globalConfig = { ...globalConfig, ...config };\n}\n\n/**\n * Get the current global configuration.\n * @internal\n */\nexport function getBlacReactConfig(): BlacReactConfig {\n  return globalConfig;\n}\n\n/**\n * Reset configuration to defaults (useful for testing).\n * @internal\n */\nexport function resetBlacReactConfig(): void {\n  globalConfig = { ...defaultConfig };\n}\n","import {\n  useMemo,\n  useSyncExternalStore,\n  useEffect,\n  useRef,\n  useReducer,\n} from 'react';\nimport {\n  type ExtractState,\n  type AdapterState,\n  ExternalDepsManager,\n  autoTrackSubscribe,\n  manualDepsSubscribe,\n  noTrackSubscribe,\n  autoTrackSnapshot,\n  manualDepsSnapshot,\n  noTrackSnapshot,\n  autoTrackInit,\n  manualDepsInit,\n  noTrackInit,\n  disableGetterTracking,\n  type StateContainerConstructor,\n  type InstanceState,\n  acquire,\n  release,\n} from '@blac/adapter';\nimport type { UseBlocOptions, UseBlocReturn, ComponentRef } from './types';\nimport { getBlacReactConfig } from './config';\n\ninterface TrackingMode {\n  useManualDeps: boolean;\n  autoTrackEnabled: boolean;\n}\n\nfunction determineTrackingMode<TBloc extends StateContainerConstructor>(\n  options?: Pick<UseBlocOptions<TBloc>, 'autoTrack' | 'dependencies'>,\n): TrackingMode {\n  const globalConfig = getBlacReactConfig();\n  const autoTrackEnabled =\n    options?.autoTrack !== undefined\n      ? options.autoTrack\n      : globalConfig.autoTrack;\n\n  return {\n    useManualDeps: options?.dependencies !== undefined,\n    autoTrackEnabled,\n  };\n}\n\n/**\n * React hook that connects a component to a state container with automatic re-render on state changes.\n *\n * Supports three tracking modes:\n * - **Auto-tracking** (default): Automatically detects accessed state properties via Proxy\n * - **Manual dependencies**: Explicit dependency array like useEffect\n * - **No tracking**: Returns full state without optimization\n *\n * @template T - The state container constructor type (inferred from BlocClass)\n * @param BlocClass - The state container class to connect to\n * @param options - Configuration options for tracking mode and instance management\n * @returns Tuple with [state, bloc instance, ref]\n *\n * @example Basic usage\n * ```ts\n * const [state, myBloc, ref] = useBloc(MyBloc);\n * ```\n *\n * @example With manual dependencies\n * ```ts\n * const [state, myBloc] = useBloc(MyBloc, {\n *   dependencies: (state) => [state.count]\n * });\n * ```\n *\n * @example With named instance\n * ```ts\n * const [state, myBloc] = useBloc(MyBloc, {\n *   instanceId: 'unique-id'\n * });\n * ```\n */\nexport function useBloc<\n  T extends StateContainerConstructor = StateContainerConstructor,\n>(\n  BlocClass: T,\n  options?: UseBlocOptions<T>,\n): UseBlocReturn<T, ExtractState<T>> {\n  type TBloc = InstanceState<T>;\n\n  const componentRef = useRef<ComponentRef>({});\n  const depsRef = useRef(options?.dependencies);\n  depsRef.current = options?.dependencies;\n  const instanceId = options?.instanceId;\n  const autoTrack = options?.autoTrack;\n  const dependencies = options?.dependencies;\n\n  const [bloc, subscribe, getSnapshot, instanceKey, adapterState, rawInstance] =\n    useMemo<\n      readonly [\n        TBloc,\n        (callback: () => void) => () => void,\n        () => ExtractState<T>,\n        string | undefined,\n        AdapterState<T>,\n        TBloc,\n      ]\n    >(() => {\n      const instanceKey =\n        instanceId !== undefined ? String(instanceId) : undefined;\n\n      const instance = acquire(BlocClass, instanceKey) as TBloc;\n\n      const { useManualDeps, autoTrackEnabled } = determineTrackingMode({\n        autoTrack,\n        dependencies,\n      });\n\n      let subscribeFn: (callback: () => void) => () => void;\n      let getSnapshotFn: () => ExtractState<T>;\n      let adapterState: AdapterState<T>;\n\n      if (useManualDeps && dependencies) {\n        adapterState = manualDepsInit(instance);\n        const stableConfig = {\n          dependencies: (state: ExtractState<T>, bloc: InstanceState<T>) => {\n            const deps = depsRef.current;\n            return deps ? deps(state, bloc) : [];\n          },\n        };\n        subscribeFn = manualDepsSubscribe(instance, adapterState, stableConfig);\n        getSnapshotFn = manualDepsSnapshot(\n          instance,\n          adapterState,\n          stableConfig,\n        );\n      } else if (!autoTrackEnabled) {\n        adapterState = noTrackInit(instance);\n        subscribeFn = noTrackSubscribe(instance);\n        getSnapshotFn = noTrackSnapshot(instance);\n      } else {\n        adapterState = autoTrackInit(instance);\n        subscribeFn = autoTrackSubscribe(instance, adapterState);\n        getSnapshotFn = autoTrackSnapshot(instance, adapterState);\n      }\n\n      const safeSubscribeFn = (callback: () => void) => {\n        if (instance.isDisposed) return () => {};\n        return subscribeFn(callback);\n      };\n\n      return [\n        adapterState.proxiedBloc as TBloc,\n        safeSubscribeFn,\n        getSnapshotFn,\n        instanceKey,\n        adapterState,\n        instance,\n      ];\n      // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [BlocClass, instanceId]);\n\n  const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  const [, forceUpdate] = useReducer((x: number) => x + 1, 0);\n\n  const externalDepsManager = useRef(new ExternalDepsManager());\n\n  useEffect(() => {\n    const manager = externalDepsManager.current;\n    disableGetterTracking(adapterState, rawInstance);\n    manager.updateSubscriptions(\n      adapterState.getterState,\n      rawInstance,\n      forceUpdate,\n    );\n  });\n\n  useEffect(() => {\n    const manager = externalDepsManager.current;\n    if (options?.onMount) {\n      options.onMount(bloc as InstanceType<T>);\n    }\n\n    return () => {\n      manager.cleanup();\n\n      if (options?.onUnmount) {\n        options.onUnmount(bloc as InstanceType<T>);\n      }\n\n      release(BlocClass, instanceKey);\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  return [state, bloc, componentRef] as UseBlocReturn<T, ExtractState<T>>;\n}\n"],"mappings":";;AAaA,IAAI,eAAgC,EAHlC,WAAW,MAG2C;;;;;;;;;;;;;;;;AAiBxD,SAAgB,mBAAmB,QAAwC;AACzE,gBAAe;EAAE,GAAG;EAAc,GAAG;EAAQ;;;;;;AAO/C,SAAgB,qBAAsC;AACpD,QAAO;;;;ACLT,SAAS,sBACP,SACc;CACd,MAAM,eAAe,oBAAoB;CACzC,MAAM,mBACJ,SAAS,cAAc,KAAA,IACnB,QAAQ,YACR,aAAa;AAEnB,QAAO;EACL,eAAe,SAAS,iBAAiB,KAAA;EACzC;EACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCH,SAAgB,QAGd,WACA,SACmC;CAGnC,MAAM,eAAe,OAAqB,EAAE,CAAC;CAC7C,MAAM,UAAU,OAAO,SAAS,aAAa;AAC7C,SAAQ,UAAU,SAAS;CAC3B,MAAM,aAAa,SAAS;CAC5B,MAAM,YAAY,SAAS;CAC3B,MAAM,eAAe,SAAS;CAE9B,MAAM,CAAC,MAAM,WAAW,aAAa,aAAa,cAAc,eAC9D,cASQ;EACN,MAAM,cACJ,eAAe,KAAA,IAAY,OAAO,WAAW,GAAG,KAAA;EAElD,MAAM,WAAW,QAAQ,WAAW,YAAY;EAEhD,MAAM,EAAE,eAAe,qBAAqB,sBAAsB;GAChE;GACA;GACD,CAAC;EAEF,IAAI;EACJ,IAAI;EACJ,IAAI;AAEJ,MAAI,iBAAiB,cAAc;AACjC,kBAAe,eAAe,SAAS;GACvC,MAAM,eAAe,EACnB,eAAe,OAAwB,SAA2B;IAChE,MAAM,OAAO,QAAQ;AACrB,WAAO,OAAO,KAAK,OAAO,KAAK,GAAG,EAAE;MAEvC;AACD,iBAAc,oBAAoB,UAAU,cAAc,aAAa;AACvE,mBAAgB,mBACd,UACA,cACA,aACD;aACQ,CAAC,kBAAkB;AAC5B,kBAAe,YAAY,SAAS;AACpC,iBAAc,iBAAiB,SAAS;AACxC,mBAAgB,gBAAgB,SAAS;SACpC;AACL,kBAAe,cAAc,SAAS;AACtC,iBAAc,mBAAmB,UAAU,aAAa;AACxD,mBAAgB,kBAAkB,UAAU,aAAa;;EAG3D,MAAM,mBAAmB,aAAyB;AAChD,OAAI,SAAS,WAAY,cAAa;AACtC,UAAO,YAAY,SAAS;;AAG9B,SAAO;GACL,aAAa;GACb;GACA;GACA;GACA;GACA;GACD;IAEA,CAAC,WAAW,WAAW,CAAC;CAE7B,MAAM,QAAQ,qBAAqB,WAAW,aAAa,YAAY;CAEvE,MAAM,GAAG,eAAe,YAAY,MAAc,IAAI,GAAG,EAAE;CAE3D,MAAM,sBAAsB,OAAO,IAAI,qBAAqB,CAAC;AAE7D,iBAAgB;EACd,MAAM,UAAU,oBAAoB;AACpC,wBAAsB,cAAc,YAAY;AAChD,UAAQ,oBACN,aAAa,aACb,aACA,YACD;GACD;AAEF,iBAAgB;EACd,MAAM,UAAU,oBAAoB;AACpC,MAAI,SAAS,QACX,SAAQ,QAAQ,KAAwB;AAG1C,eAAa;AACX,WAAQ,SAAS;AAEjB,OAAI,SAAS,UACX,SAAQ,UAAU,KAAwB;AAG5C,WAAQ,WAAW,YAAY;;IAGhC,EAAE,CAAC;AAEN,QAAO;EAAC;EAAO;EAAM;EAAa"}

package/dist/types.d.ts

@@ -6,7 +6,7 @@ import type { RefObject } from 'react';
  * @template TBloc - The state container type
  */
 export interface UseBlocOptions<TBloc extends StateContainerConstructor> {
-    /** Custom instance identifier for shared or isolated instances */
+    /** Custom instance identifier */
     instanceId?: string | number;
     /** Manual dependency array like useEffect (disables autoTrack) */
     dependencies?: (state: ExtractState<TBloc>, bloc: InstanceReadonlyState<TBloc>) => unknown[];
@@ -30,7 +30,4 @@ export type UseBlocReturn<TBloc extends StateContainerConstructor, S = ExtractSt
  * Internal ref structure for component-bloc binding
  * @internal
  */
-export type ComponentRef = {
-    /** Cached bloc instance ID for this component */
-    __blocInstanceId?: string;
-};
+export type ComponentRef = Record<string, never>;

package/dist/useBloc.d.ts

@@ -25,7 +25,7 @@ import type { UseBlocOptions, UseBlocReturn } from './types';
  * });
  * ```
  *
- * @example With isolated instance
+ * @example With named instance
  * ```ts
  * const [state, myBloc] = useBloc(MyBloc, {
  *   instanceId: 'unique-id'

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

@@ -1,18 +1,10 @@
 /**
  * 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;
+export declare function generateInstanceKey(providedId?: string | number): string | undefined;

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@blac/react",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "license": "MIT",
   "author": "Brendan Mullins <jsnanigans@gmail.com>",
+  "description": "React bindings for BlaC — useBloc hook with automatic re-render optimization",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jsnanigans/blac.git",
@@ -47,12 +48,12 @@
     "bloc-pattern"
   ],
   "dependencies": {
-    "@blac/adapter": "^2.0.6"
+    "@blac/adapter": "^2.0.8"
   },
   "peerDependencies": {
     "@types/react": "^18.0.0 || ^19.0.0",
     "react": "^18.0.0 || ^19.0.0",
-    "@blac/core": "^2.0.6"
+    "@blac/core": "^2.0.8"
   },
   "peerDependenciesMeta": {
     "@types/react": {
@@ -68,6 +69,7 @@
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
     "@types/react": "^19.1.9",
+    "@types/react-dom": "^19.1.7",
     "@vitejs/plugin-react": "^4.7.0",
     "@vitest/browser": "^3.2.4",
     "@vitest/coverage-v8": "^3.2.4",
@@ -76,14 +78,14 @@
     "happy-dom": "^18.0.1",
     "jsdom": "^26.1.0",
     "prettier": "^3.6.2",
+    "publint": "^0.3.12",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "tsdown": "^0.15.7",
     "typescript": "^5.9.2",
     "vite": "^7.1.10",
-    "publint": "^0.3.12",
     "vitest": "3.2.4",
-    "@blac/core": "2.0.6"
+    "@blac/core": "2.0.8"
   },
   "scripts": {
     "dev": "tsdown --watch",