@blac/react 2.0.4 → 2.0.6

package/README.md

@@ -2,7 +2,7 @@
 
 > ⚠️ **Warning:** This project is currently under active development. The API may change in future releases. Use with caution in production environments.
 
-React integration for the BlaC state management library with automatic re-render optimization.
+React integration for BlaC with automatic re-render optimization.
 
 ## Installation
 
@@ -42,9 +42,7 @@ function Counter() {
 }
 ```
 
-## Hooks
-
-### useBloc
+## useBloc
 
 Connects a component to a state container with automatic re-renders on state changes.
 
@@ -54,29 +52,26 @@ const [state, bloc, ref] = useBloc(MyBloc);
 
 **Returns:** `[state, bloc, ref]`
 
-- `state` - Current state (reactive)
-- `bloc` - The bloc instance for calling methods
-- `ref` - Component reference for isolated instances
+- `state` - Current state snapshot
+- `bloc` - Bloc instance (proxied for tracking; call methods on it)
+- `ref` - Internal component ref (advanced usage)
 
-#### Tracking Modes
+### Tracking Modes
 
-**Auto-tracking (default):** Automatically detects which properties you access and only re-renders when those change.
+**Auto-tracking (default):** Tracks accessed properties and getters.
 
 ```tsx
 function UserProfile() {
-  const [state, user] = useBloc(UserBloc);
-
-  // Only re-renders when state.name changes
-  // (state.email changes won't cause re-render)
+  const [state] = useBloc(UserBloc);
   return <h1>{state.name}</h1>;
 }
 ```
 
-**Manual dependencies:** Explicit dependency array like `useEffect`.
+**Manual dependencies:** Provide a dependency selector (disables auto-tracking).
 
 ```tsx
 function Counter() {
-  const [state] = useBloc(CounterBloc, {
+  const [state] = useBloc(CounterCubit, {
     dependencies: (state) => [state.count],
   });
 
@@ -84,187 +79,85 @@ function Counter() {
 }
 ```
 
-**No tracking:** Returns full state, re-renders on any change.
+**No tracking:** Re-render on any state change.
 
 ```tsx
 function FullState() {
   const [state] = useBloc(MyBloc, { autoTrack: false });
-
   return <pre>{JSON.stringify(state)}</pre>;
 }
 ```
 
-#### Options
+### Options
 
 ```tsx
 useBloc(MyBloc, {
-  // Tracking mode
-  autoTrack: true, // Enable/disable auto-tracking (default: true)
-  dependencies: (state) => [state.prop], // Manual dependencies
-
-  // Instance management
-  instanceId: 'unique-id', // Custom instance identifier
-
-  // Lifecycle callbacks
+  autoTrack: true,
+  dependencies: (state, bloc) => [state.count, bloc],
+  instanceId: 'editor-1',
   onMount: (bloc) => console.log('Mounted', bloc),
   onUnmount: (bloc) => console.log('Unmounted', bloc),
 });
 ```
 
-### useBlocActions
-
-Connects to a state container without subscribing to state changes. Use for calling actions without re-renders, or for stateless containers.
-
-```tsx
-const bloc = useBlocActions(MyBloc);
-```
-
-**Use cases:**
-
-```tsx
-// Stateless services (analytics, navigation, etc.)
-function TrackButton() {
-  const analytics = useBlocActions(AnalyticsService);
-
-  return (
-    <button onClick={() => analytics.trackClick('button')}>Click me</button>
-  );
-}
-
-// Actions-only (no state subscription)
-function IncrementButton() {
-  const counter = useBlocActions(CounterCubit);
-
-  return <button onClick={counter.increment}>+</button>;
-}
-```
-
-#### Options
-
-```tsx
-useBlocActions(MyBloc, {
-  instanceId: 'unique-id', // Custom instance identifier
-  onMount: (bloc) => bloc.initialize(),
-  onUnmount: (bloc) => bloc.cleanup(),
-});
-```
+| Option         | Type                         | Description                          |
+| -------------- | ---------------------------- | ------------------------------------ |
+| `autoTrack`    | `boolean`                    | Enable auto-tracking (default: true) |
+| `dependencies` | `(state, bloc) => unknown[]` | Manual dependency selector           |
+| `instanceId`   | `string \| number`           | Custom instance identifier           |
+| `onMount`      | `(bloc) => void`             | Called when component mounts         |
+| `onUnmount`    | `(bloc) => void`             | Called when component unmounts       |
 
 ## Instance Management
 
 ### Shared Instances (Default)
 
-By default, all components using the same bloc class share one instance:
-
 ```tsx
-function ComponentA() {
-  const [state] = useBloc(CounterCubit);
-  // Uses shared instance
+function A() {
+  useBloc(CounterCubit); // shared instance
 }
 
-function ComponentB() {
-  const [state] = useBloc(CounterCubit);
-  // Uses same shared instance
+function B() {
+  useBloc(CounterCubit); // same shared instance
 }
 ```
 
 ### Isolated Instances
 
-For component-scoped state, use the `@blac({ isolated: true })` decorator:
-
 ```tsx
 import { Cubit, blac } from '@blac/core';
 
 @blac({ isolated: true })
-class FormCubit extends Cubit<FormState> {
-  // ...
-}
+class FormCubit extends Cubit<FormState> {}
 
 function FormA() {
-  const [state] = useBloc(FormCubit);
-  // Gets its own instance
-}
-
-function FormB() {
-  const [state] = useBloc(FormCubit);
-  // Gets a different instance
+  useBloc(FormCubit); // unique instance per component
 }
 ```
 
 ### Named Instances
 
-Share instances across specific components with `instanceId`:
-
 ```tsx
-function EditorA() {
-  const [state] = useBloc(EditorCubit, { instanceId: 'editor-1' });
-}
-
-function EditorB() {
-  const [state] = useBloc(EditorCubit, { instanceId: 'editor-1' });
-  // Same instance as EditorA
-}
-
-function EditorC() {
-  const [state] = useBloc(EditorCubit, { instanceId: 'editor-2' });
-  // Different instance
-}
+useBloc(EditorCubit, { instanceId: 'editor-1' });
+useBloc(EditorCubit, { instanceId: 'editor-1' }); // same instance
+useBloc(EditorCubit, { instanceId: 'editor-2' }); // different instance
 ```
 
 ## Configuration
 
-Configure global behavior:
+Configure global defaults:
 
 ```tsx
 import { configureBlacReact } from '@blac/react';
 
 configureBlacReact({
-  autoTrack: true, // Enable auto-tracking by default (default: true)
+  autoTrack: true,
 });
 ```
 
-## API Reference
-
-### useBloc
-
-```tsx
-function useBloc<T extends StateContainerConstructor>(
-  BlocClass: T,
-  options?: UseBlocOptions<T>,
-): [ExtractState<T>, InstanceType<T>, ComponentRef];
-```
-
-### useBlocActions
-
-```tsx
-function useBlocActions<T extends StateContainerConstructor>(
-  BlocClass: T,
-  options?: UseBlocActionsOptions<InstanceType<T>>,
-): InstanceType<T>;
-```
-
-### UseBlocOptions
-
-| Option         | Type               | Description                          |
-| -------------- | ------------------ | ------------------------------------ |
-| `autoTrack`    | `boolean`          | Enable auto-tracking (default: true) |
-| `dependencies` | `(state) => any[]` | Manual dependency selector           |
-| `instanceId`   | `string \| number` | Custom instance identifier           |
-| `onMount`      | `(bloc) => void`   | Called when component mounts         |
-| `onUnmount`    | `(bloc) => void`   | Called when component unmounts       |
-
-### UseBlocActionsOptions
-
-| Option       | Type               | Description                    |
-| ------------ | ------------------ | ------------------------------ |
-| `instanceId` | `string \| number` | Custom instance identifier     |
-| `onMount`    | `(bloc) => void`   | Called when component mounts   |
-| `onUnmount`  | `(bloc) => void`   | Called when component unmounts |
-
 ## Compatibility
 
-- React 18.0+ or React 19.0+
-- Works with React Compiler
-- Supports concurrent rendering via `useSyncExternalStore`
+- React 18+ (uses `useSyncExternalStore`)
 
 ## License
 

package/dist/config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Global configuration for @blac/react
+ */
+export interface BlacReactConfig {
+    /** Enable automatic property tracking via Proxy (default: true) */
+    autoTrack: boolean;
+}
+/**
+ * Configure global defaults for @blac/react hooks.
+ *
+ * @example
+ * ```ts
+ * import { configureBlacReact } from '@blac/react';
+ *
+ * // Disable auto-tracking globally
+ * configureBlacReact({
+ *   autoTrack: false
+ * });
+ * ```
+ *
+ * @param config - Partial configuration to merge with defaults
+ */
+export declare function configureBlacReact(config: Partial<BlacReactConfig>): void;
+/**
+ * Get the current global configuration.
+ * @internal
+ */
+export declare function getBlacReactConfig(): BlacReactConfig;
+/**
+ * Reset configuration to defaults (useful for testing).
+ * @internal
+ */
+export declare function resetBlacReactConfig(): void;

package/dist/index.cjs

@@ -1,6 +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
@@ -25,11 +25,7 @@ function generateInstanceKey(componentRef, isIsolated, providedId) {
 		return componentRef.__blocInstanceId;
 	}
 }
-
-//#endregion
-//#region src/config.ts
-const defaultConfig = { autoTrack: true };
-let globalConfig = { ...defaultConfig };
+let globalConfig = { autoTrack: true };
 /**
 * Configure global defaults for @blac/react hooks.
 *
@@ -58,7 +54,6 @@ function configureBlacReact(config) {
 function getBlacReactConfig() {
 	return globalConfig;
 }
-
 //#endregion
 //#region src/useBloc.ts
 function determineTrackingMode(options) {
@@ -104,17 +99,29 @@ 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, options?.instanceId);
+		const instanceKey = generateInstanceKey(componentRef.current, isIsolated, instanceId);
 		const instance = (0, _blac_adapter.acquire)(BlocClass, instanceKey);
-		const { useManualDeps, autoTrackEnabled } = determineTrackingMode(options);
+		const { useManualDeps, autoTrackEnabled } = determineTrackingMode({
+			autoTrack,
+			dependencies
+		});
 		let subscribeFn;
 		let getSnapshotFn;
 		let adapterState;
-		if (useManualDeps && options?.dependencies) {
+		if (useManualDeps && dependencies) {
 			adapterState = (0, _blac_adapter.manualDepsInit)(instance);
-			subscribeFn = (0, _blac_adapter.manualDepsSubscribe)(instance, adapterState, { dependencies: options.dependencies });
-			getSnapshotFn = (0, _blac_adapter.manualDepsSnapshot)(instance, adapterState, { dependencies: options.dependencies });
+			const stableConfig = { dependencies: (state, bloc) => {
+				const deps = depsRef.current;
+				return deps ? deps(state, bloc) : [];
+			} };
+			subscribeFn = (0, _blac_adapter.manualDepsSubscribe)(instance, adapterState, stableConfig);
+			getSnapshotFn = (0, _blac_adapter.manualDepsSnapshot)(instance, adapterState, stableConfig);
 		} else if (!autoTrackEnabled) {
 			adapterState = (0, _blac_adapter.noTrackInit)(instance);
 			subscribeFn = (0, _blac_adapter.noTrackSubscribe)(instance);
@@ -135,19 +142,21 @@ function useBloc(BlocClass, options) {
 	}, [
 		BlocClass,
 		isIsolated,
-		options?.instanceId
+		instanceId
 	]);
 	const state = (0, react.useSyncExternalStore)(subscribe, getSnapshot);
 	const [, forceUpdate] = (0, react.useReducer)((x) => x + 1, 0);
 	const externalDepsManager = (0, react.useRef)(new _blac_adapter.ExternalDepsManager());
 	(0, react.useEffect)(() => {
+		const manager = externalDepsManager.current;
 		(0, _blac_adapter.disableGetterTracking)(adapterState, rawInstance);
-		externalDepsManager.current.updateSubscriptions(adapterState.getterState, rawInstance, forceUpdate);
+		manager.updateSubscriptions(adapterState.getterState, rawInstance, forceUpdate);
 	});
 	(0, react.useEffect)(() => {
+		const manager = externalDepsManager.current;
 		if (options?.onMount) options.onMount(bloc);
 		return () => {
-			externalDepsManager.current.cleanup();
+			manager.cleanup();
 			if (options?.onUnmount) options.onUnmount(bloc);
 			(0, _blac_adapter.release)(BlocClass, instanceKey);
 			if (isIsolated && !rawInstance.isDisposed) rawInstance.dispose();
@@ -159,8 +168,8 @@ function useBloc(BlocClass, options) {
 		componentRef
 	];
 }
-
 //#endregion
 exports.configureBlacReact = configureBlacReact;
 exports.useBloc = useBloc;
+
 //# sourceMappingURL=index.cjs.map

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?: UseBlocOptions<TBloc>,\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\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        options?.instanceId,\n      );\n\n      const instance = acquire(BlocClass, instanceKey) as TBloc;\n\n      const { useManualDeps, autoTrackEnabled } =\n        determineTrackingMode(options);\n\n      let subscribeFn: (callback: () => void) => () => void;\n      let getSnapshotFn: () => ExtractState<T>;\n      let adapterState: AdapterState<T>;\n\n      if (useManualDeps && options?.dependencies) {\n        adapterState = manualDepsInit(instance);\n        subscribeFn = manualDepsSubscribe(instance, adapterState, {\n          dependencies: options.dependencies,\n        });\n        getSnapshotFn = manualDepsSnapshot(instance, adapterState, {\n          dependencies: options.dependencies,\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    }, [BlocClass, isIsolated, options?.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    disableGetterTracking(adapterState, rawInstance);\n    externalDepsManager.current.updateSubscriptions(\n      adapterState.getterState,\n      rawInstance,\n      forceUpdate,\n    );\n  });\n\n  useEffect(() => {\n    if (options?.onMount) {\n      options.onMount(bloc as InstanceType<T>);\n    }\n\n    return () => {\n      externalDepsManager.current.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,OACjB,QAAO,OAAO,eAAe,WAAW,OAAO,WAAW,GAAG;AAI/D,KAAI,YAAY;AACd,MAAI,CAAC,aAAa,iBAChB,cAAa,2DAAwC;AAEvD,SAAO,aAAa;;;;;;AC1BxB,MAAM,gBAAiC,EACrC,WAAW,MACZ;AAED,IAAI,eAAgC,EAAE,GAAG,eAAe;;;;;;;;;;;;;;;;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,SACnB,QAAQ,YACR,aAAa;AAEnB,QAAO;EACL,eAAe,SAAS,iBAAiB;EACzC;EACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCH,SAAgB,QAGd,WACA,SACmC;CAGnC,MAAM,iCAAoC,EAAE,CAAC;CAC7C,MAAM,gDAA6B,UAAU;CAE7C,MAAM,CAAC,MAAM,WAAW,aAAa,aAAa,cAAc,wCAUtD;EACN,MAAM,cAAc,oBAClB,aAAa,SACb,YACA,SAAS,WACV;EAED,MAAM,sCAAmB,WAAW,YAAY;EAEhD,MAAM,EAAE,eAAe,qBACrB,sBAAsB,QAAQ;EAEhC,IAAI;EACJ,IAAI;EACJ,IAAI;AAEJ,MAAI,iBAAiB,SAAS,cAAc;AAC1C,oDAA8B,SAAS;AACvC,wDAAkC,UAAU,cAAc,EACxD,cAAc,QAAQ,cACvB,CAAC;AACF,yDAAmC,UAAU,cAAc,EACzD,cAAc,QAAQ,cACvB,CAAC;aACO,CAAC,kBAAkB;AAC5B,iDAA2B,SAAS;AACpC,qDAA+B,SAAS;AACxC,sDAAgC,SAAS;SACpC;AACL,mDAA6B,SAAS;AACtC,uDAAiC,UAAU,aAAa;AACxD,wDAAkC,UAAU,aAAa;;AAG3D,SAAO;GACL,aAAa;GACb;GACA;GACA;GACA;GACA;GACD;IACA;EAAC;EAAW;EAAY,SAAS;EAAW,CAAC;CAElD,MAAM,wCAA6B,WAAW,YAAY;CAE1D,MAAM,GAAG,sCAA2B,MAAc,IAAI,GAAG,EAAE;CAE3D,MAAM,wCAA6B,IAAIA,mCAAqB,CAAC;AAE7D,4BAAgB;AACd,2CAAsB,cAAc,YAAY;AAChD,sBAAoB,QAAQ,oBAC1B,aAAa,aACb,aACA,YACD;GACD;AAEF,4BAAgB;AACd,MAAI,SAAS,QACX,SAAQ,QAAQ,KAAwB;AAG1C,eAAa;AACX,uBAAoB,QAAQ,SAAS;AAErC,OAAI,SAAS,UACX,SAAQ,UAAU,KAAwB;AAG5C,8BAAQ,WAAW,YAAY;AAE/B,OAAI,cAAc,CAAC,YAAY,WAC7B,aAAY,SAAS;;IAIxB,EAAE,CAAC;AAEN,QAAO;EAAC;EAAO;EAAM;EAAa"}
+{"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":";;;;;;;;;;;;;;;;;;;;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,oBAAA,GAAA,cAAA,sBAAwC;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,gBAAA,GAAA,MAAA,QAAoC,EAAE,CAAC;CAC7C,MAAM,cAAA,GAAA,cAAA,iBAA6B,UAAU;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,cAAc,oBAClB,aAAa,SACb,YACA,WACD;EAED,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;;AAG3D,SAAO;GACL,aAAa;GACb;GACA;GACA;GACA;GACA;GACD;IAEA;EAAC;EAAW;EAAY;EAAW,CAAC;CAEzC,MAAM,SAAA,GAAA,MAAA,sBAA6B,WAAW,YAAY;CAE1D,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;AAE/B,OAAI,cAAc,CAAC,YAAY,WAC7B,aAAY,SAAS;;IAIxB,EAAE,CAAC;AAEN,QAAO;EAAC;EAAO;EAAM;EAAa"}

package/dist/index.d.cts

@@ -1,96 +1,11 @@
-import type { ExtractState } from '@blac/core';
-import { ExtractState as ExtractState_2 } from '@blac/adapter';
-import { InstanceReadonlyState } from '@blac/core';
-import type { RefObject } from 'react';
-import { StateContainerConstructor } from '@blac/adapter';
-import type { StateContainerConstructor as StateContainerConstructor_2 } from '@blac/core';
-
-/**
- * Global configuration for @blac/react
- */
-export declare interface BlacReactConfig {
-    /** Enable automatic property tracking via Proxy (default: true) */
-    autoTrack: boolean;
-}
-
-/* Excluded from this release type: ComponentRef */
-
-/**
- * Configure global defaults for @blac/react hooks.
- *
- * @example
- * ```ts
- * import { configureBlacReact } from '@blac/react';
- *
- * // Disable auto-tracking globally
- * configureBlacReact({
- *   autoTrack: false
- * });
- * ```
- *
- * @param config - Partial configuration to merge with defaults
- */
-export declare function configureBlacReact(config: Partial<BlacReactConfig>): void;
-
-/**
- * React hook that connects a component to a state container with automatic re-render on state changes.
- *
- * Supports three tracking modes:
- * - **Auto-tracking** (default): Automatically detects accessed state properties via Proxy
- * - **Manual dependencies**: Explicit dependency array like useEffect
- * - **No tracking**: Returns full state without optimization
- *
- * @template T - The state container constructor type (inferred from BlocClass)
- * @param BlocClass - The state container class to connect to
- * @param options - Configuration options for tracking mode and instance management
- * @returns Tuple with [state, bloc instance, ref]
- *
- * @example Basic usage
- * ```ts
- * const [state, myBloc, ref] = useBloc(MyBloc);
- * ```
- *
- * @example With manual dependencies
- * ```ts
- * const [state, myBloc] = useBloc(MyBloc, {
- *   dependencies: (state) => [state.count]
- * });
- * ```
- *
- * @example With isolated instance
- * ```ts
- * const [state, myBloc] = useBloc(MyBloc, {
- *   instanceId: 'unique-id'
- * });
- * ```
- */
-export declare function useBloc<T extends StateContainerConstructor = StateContainerConstructor>(BlocClass: T, options?: UseBlocOptions<T>): UseBlocReturn<T, ExtractState_2<T>>;
-
-/**
- * Configuration options for useBloc hook
- * @template TBloc - The state container type
- */
-export declare interface UseBlocOptions<TBloc extends StateContainerConstructor_2> {
-    /** Custom instance identifier for shared or isolated instances */
-    instanceId?: string | number;
-    /** Manual dependency array like useEffect (disables autoTrack) */
-    dependencies?: (state: ExtractState<TBloc>, bloc: InstanceReadonlyState<TBloc>) => unknown[];
-    /** Enable automatic property tracking via Proxy (default: true) */
-    autoTrack?: boolean;
-    /** Callback invoked when bloc instance mounts */
-    onMount?: (bloc: InstanceType<TBloc>) => void;
-    /** Callback invoked when bloc instance unmounts */
-    onUnmount?: (bloc: InstanceType<TBloc>) => void;
-}
-
-/**
- * Tuple return type from useBloc hook containing state, bloc instance, and ref
- * - [0] Current state value (with optional state type override)
- * - [1] State container instance (bloc) for calling actions
- * - [2] Ref object for accessing component ref (advanced use cases)
- *
- * @template TBloc - The state container type
- */
-export declare type UseBlocReturn<TBloc extends StateContainerConstructor_2, S = ExtractState<TBloc>> = [S, InstanceReadonlyState<TBloc>, RefObject<ComponentRef>];
-
-export { }
+/**
+ * React Integration
+ *
+ * Clean integration between React and StateContainer architecture.
+ * Constructor-based API with automatic type inference.
+ * Supports concurrent (useSyncExternalStore) mode for optimal performance.
+ */
+export { useBloc } from './useBloc';
+export { configureBlacReact } from './config';
+export type { BlacReactConfig } from './config';
+export type { UseBlocOptions, UseBlocReturn } from './types';

package/dist/index.d.ts

@@ -1,96 +1,11 @@
-import type { ExtractState } from '@blac/core';
-import { ExtractState as ExtractState_2 } from '@blac/adapter';
-import { InstanceReadonlyState } from '@blac/core';
-import type { RefObject } from 'react';
-import { StateContainerConstructor } from '@blac/adapter';
-import type { StateContainerConstructor as StateContainerConstructor_2 } from '@blac/core';
-
-/**
- * Global configuration for @blac/react
- */
-export declare interface BlacReactConfig {
-    /** Enable automatic property tracking via Proxy (default: true) */
-    autoTrack: boolean;
-}
-
-/* Excluded from this release type: ComponentRef */
-
-/**
- * Configure global defaults for @blac/react hooks.
- *
- * @example
- * ```ts
- * import { configureBlacReact } from '@blac/react';
- *
- * // Disable auto-tracking globally
- * configureBlacReact({
- *   autoTrack: false
- * });
- * ```
- *
- * @param config - Partial configuration to merge with defaults
- */
-export declare function configureBlacReact(config: Partial<BlacReactConfig>): void;
-
-/**
- * React hook that connects a component to a state container with automatic re-render on state changes.
- *
- * Supports three tracking modes:
- * - **Auto-tracking** (default): Automatically detects accessed state properties via Proxy
- * - **Manual dependencies**: Explicit dependency array like useEffect
- * - **No tracking**: Returns full state without optimization
- *
- * @template T - The state container constructor type (inferred from BlocClass)
- * @param BlocClass - The state container class to connect to
- * @param options - Configuration options for tracking mode and instance management
- * @returns Tuple with [state, bloc instance, ref]
- *
- * @example Basic usage
- * ```ts
- * const [state, myBloc, ref] = useBloc(MyBloc);
- * ```
- *
- * @example With manual dependencies
- * ```ts
- * const [state, myBloc] = useBloc(MyBloc, {
- *   dependencies: (state) => [state.count]
- * });
- * ```
- *
- * @example With isolated instance
- * ```ts
- * const [state, myBloc] = useBloc(MyBloc, {
- *   instanceId: 'unique-id'
- * });
- * ```
- */
-export declare function useBloc<T extends StateContainerConstructor = StateContainerConstructor>(BlocClass: T, options?: UseBlocOptions<T>): UseBlocReturn<T, ExtractState_2<T>>;
-
-/**
- * Configuration options for useBloc hook
- * @template TBloc - The state container type
- */
-export declare interface UseBlocOptions<TBloc extends StateContainerConstructor_2> {
-    /** Custom instance identifier for shared or isolated instances */
-    instanceId?: string | number;
-    /** Manual dependency array like useEffect (disables autoTrack) */
-    dependencies?: (state: ExtractState<TBloc>, bloc: InstanceReadonlyState<TBloc>) => unknown[];
-    /** Enable automatic property tracking via Proxy (default: true) */
-    autoTrack?: boolean;
-    /** Callback invoked when bloc instance mounts */
-    onMount?: (bloc: InstanceType<TBloc>) => void;
-    /** Callback invoked when bloc instance unmounts */
-    onUnmount?: (bloc: InstanceType<TBloc>) => void;
-}
-
-/**
- * Tuple return type from useBloc hook containing state, bloc instance, and ref
- * - [0] Current state value (with optional state type override)
- * - [1] State container instance (bloc) for calling actions
- * - [2] Ref object for accessing component ref (advanced use cases)
- *
- * @template TBloc - The state container type
- */
-export declare type UseBlocReturn<TBloc extends StateContainerConstructor_2, S = ExtractState<TBloc>> = [S, InstanceReadonlyState<TBloc>, RefObject<ComponentRef>];
-
-export { }
+/**
+ * React Integration
+ *
+ * Clean integration between React and StateContainer architecture.
+ * Constructor-based API with automatic type inference.
+ * Supports concurrent (useSyncExternalStore) mode for optimal performance.
+ */
+export { useBloc } from './useBloc';
+export { configureBlacReact } from './config';
+export type { BlacReactConfig } from './config';
+export type { UseBlocOptions, UseBlocReturn } from './types';

package/dist/index.js

@@ -1,6 +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
@@ -25,11 +24,7 @@ function generateInstanceKey(componentRef, isIsolated, providedId) {
 		return componentRef.__blocInstanceId;
 	}
 }
-
-//#endregion
-//#region src/config.ts
-const defaultConfig = { autoTrack: true };
-let globalConfig = { ...defaultConfig };
+let globalConfig = { autoTrack: true };
 /**
 * Configure global defaults for @blac/react hooks.
 *
@@ -58,7 +53,6 @@ function configureBlacReact(config) {
 function getBlacReactConfig() {
 	return globalConfig;
 }
-
 //#endregion
 //#region src/useBloc.ts
 function determineTrackingMode(options) {
@@ -104,17 +98,29 @@ 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, options?.instanceId);
+		const instanceKey = generateInstanceKey(componentRef.current, isIsolated, instanceId);
 		const instance = acquire(BlocClass, instanceKey);
-		const { useManualDeps, autoTrackEnabled } = determineTrackingMode(options);
+		const { useManualDeps, autoTrackEnabled } = determineTrackingMode({
+			autoTrack,
+			dependencies
+		});
 		let subscribeFn;
 		let getSnapshotFn;
 		let adapterState;
-		if (useManualDeps && options?.dependencies) {
+		if (useManualDeps && dependencies) {
 			adapterState = manualDepsInit(instance);
-			subscribeFn = manualDepsSubscribe(instance, adapterState, { dependencies: options.dependencies });
-			getSnapshotFn = manualDepsSnapshot(instance, adapterState, { dependencies: options.dependencies });
+			const stableConfig = { dependencies: (state, bloc) => {
+				const deps = depsRef.current;
+				return deps ? deps(state, bloc) : [];
+			} };
+			subscribeFn = manualDepsSubscribe(instance, adapterState, stableConfig);
+			getSnapshotFn = manualDepsSnapshot(instance, adapterState, stableConfig);
 		} else if (!autoTrackEnabled) {
 			adapterState = noTrackInit(instance);
 			subscribeFn = noTrackSubscribe(instance);
@@ -135,19 +141,21 @@ function useBloc(BlocClass, options) {
 	}, [
 		BlocClass,
 		isIsolated,
-		options?.instanceId
+		instanceId
 	]);
 	const state = useSyncExternalStore(subscribe, getSnapshot);
 	const [, forceUpdate] = useReducer((x) => x + 1, 0);
 	const externalDepsManager = useRef(new ExternalDepsManager());
 	useEffect(() => {
+		const manager = externalDepsManager.current;
 		disableGetterTracking(adapterState, rawInstance);
-		externalDepsManager.current.updateSubscriptions(adapterState.getterState, rawInstance, forceUpdate);
+		manager.updateSubscriptions(adapterState.getterState, rawInstance, forceUpdate);
 	});
 	useEffect(() => {
+		const manager = externalDepsManager.current;
 		if (options?.onMount) options.onMount(bloc);
 		return () => {
-			externalDepsManager.current.cleanup();
+			manager.cleanup();
 			if (options?.onUnmount) options.onUnmount(bloc);
 			release(BlocClass, instanceKey);
 			if (isIsolated && !rawInstance.isDisposed) rawInstance.dispose();
@@ -159,7 +167,7 @@ function useBloc(BlocClass, options) {
 		componentRef
 	];
 }
-
 //#endregion
 export { configureBlacReact, useBloc };
+
 //# sourceMappingURL=index.js.map

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?: UseBlocOptions<TBloc>,\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\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        options?.instanceId,\n      );\n\n      const instance = acquire(BlocClass, instanceKey) as TBloc;\n\n      const { useManualDeps, autoTrackEnabled } =\n        determineTrackingMode(options);\n\n      let subscribeFn: (callback: () => void) => () => void;\n      let getSnapshotFn: () => ExtractState<T>;\n      let adapterState: AdapterState<T>;\n\n      if (useManualDeps && options?.dependencies) {\n        adapterState = manualDepsInit(instance);\n        subscribeFn = manualDepsSubscribe(instance, adapterState, {\n          dependencies: options.dependencies,\n        });\n        getSnapshotFn = manualDepsSnapshot(instance, adapterState, {\n          dependencies: options.dependencies,\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    }, [BlocClass, isIsolated, options?.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    disableGetterTracking(adapterState, rawInstance);\n    externalDepsManager.current.updateSubscriptions(\n      adapterState.getterState,\n      rawInstance,\n      forceUpdate,\n    );\n  });\n\n  useEffect(() => {\n    if (options?.onMount) {\n      options.onMount(bloc as InstanceType<T>);\n    }\n\n    return () => {\n      externalDepsManager.current.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,OACjB,QAAO,OAAO,eAAe,WAAW,OAAO,WAAW,GAAG;AAI/D,KAAI,YAAY;AACd,MAAI,CAAC,aAAa,iBAChB,cAAa,mBAAmB,qBAAqB;AAEvD,SAAO,aAAa;;;;;;AC1BxB,MAAM,gBAAiC,EACrC,WAAW,MACZ;AAED,IAAI,eAAgC,EAAE,GAAG,eAAe;;;;;;;;;;;;;;;;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,SACnB,QAAQ,YACR,aAAa;AAEnB,QAAO;EACL,eAAe,SAAS,iBAAiB;EACzC;EACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCH,SAAgB,QAGd,WACA,SACmC;CAGnC,MAAM,eAAe,OAAqB,EAAE,CAAC;CAC7C,MAAM,aAAa,gBAAgB,UAAU;CAE7C,MAAM,CAAC,MAAM,WAAW,aAAa,aAAa,cAAc,eAC9D,cASQ;EACN,MAAM,cAAc,oBAClB,aAAa,SACb,YACA,SAAS,WACV;EAED,MAAM,WAAW,QAAQ,WAAW,YAAY;EAEhD,MAAM,EAAE,eAAe,qBACrB,sBAAsB,QAAQ;EAEhC,IAAI;EACJ,IAAI;EACJ,IAAI;AAEJ,MAAI,iBAAiB,SAAS,cAAc;AAC1C,kBAAe,eAAe,SAAS;AACvC,iBAAc,oBAAoB,UAAU,cAAc,EACxD,cAAc,QAAQ,cACvB,CAAC;AACF,mBAAgB,mBAAmB,UAAU,cAAc,EACzD,cAAc,QAAQ,cACvB,CAAC;aACO,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;IACA;EAAC;EAAW;EAAY,SAAS;EAAW,CAAC;CAElD,MAAM,QAAQ,qBAAqB,WAAW,YAAY;CAE1D,MAAM,GAAG,eAAe,YAAY,MAAc,IAAI,GAAG,EAAE;CAE3D,MAAM,sBAAsB,OAAO,IAAI,qBAAqB,CAAC;AAE7D,iBAAgB;AACd,wBAAsB,cAAc,YAAY;AAChD,sBAAoB,QAAQ,oBAC1B,aAAa,aACb,aACA,YACD;GACD;AAEF,iBAAgB;AACd,MAAI,SAAS,QACX,SAAQ,QAAQ,KAAwB;AAG1C,eAAa;AACX,uBAAoB,QAAQ,SAAS;AAErC,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/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"}

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+import type { ExtractState, StateContainerConstructor } from '@blac/core';
+import { InstanceReadonlyState } from '@blac/core';
+import type { RefObject } from 'react';
+/**
+ * Configuration options for useBloc hook
+ * @template TBloc - The state container type
+ */
+export interface UseBlocOptions<TBloc extends StateContainerConstructor> {
+    /** Custom instance identifier for shared or isolated instances */
+    instanceId?: string | number;
+    /** Manual dependency array like useEffect (disables autoTrack) */
+    dependencies?: (state: ExtractState<TBloc>, bloc: InstanceReadonlyState<TBloc>) => unknown[];
+    /** Enable automatic property tracking via Proxy (default: true) */
+    autoTrack?: boolean;
+    /** Callback invoked when bloc instance mounts */
+    onMount?: (bloc: InstanceType<TBloc>) => void;
+    /** Callback invoked when bloc instance unmounts */
+    onUnmount?: (bloc: InstanceType<TBloc>) => void;
+}
+/**
+ * Tuple return type from useBloc hook containing state, bloc instance, and ref
+ * - [0] Current state value (with optional state type override)
+ * - [1] State container instance (bloc) for calling actions
+ * - [2] Ref object for accessing component ref (advanced use cases)
+ *
+ * @template TBloc - The state container type
+ */
+export type UseBlocReturn<TBloc extends StateContainerConstructor, S = ExtractState<TBloc>> = [S, InstanceReadonlyState<TBloc>, RefObject<ComponentRef>];
+/**
+ * Internal ref structure for component-bloc binding
+ * @internal
+ */
+export type ComponentRef = {
+    /** Cached bloc instance ID for this component */
+    __blocInstanceId?: string;
+};

package/dist/useBloc.d.ts

@@ -0,0 +1,35 @@
+import { type ExtractState, type StateContainerConstructor } from '@blac/adapter';
+import type { UseBlocOptions, UseBlocReturn } from './types';
+/**
+ * React hook that connects a component to a state container with automatic re-render on state changes.
+ *
+ * Supports three tracking modes:
+ * - **Auto-tracking** (default): Automatically detects accessed state properties via Proxy
+ * - **Manual dependencies**: Explicit dependency array like useEffect
+ * - **No tracking**: Returns full state without optimization
+ *
+ * @template T - The state container constructor type (inferred from BlocClass)
+ * @param BlocClass - The state container class to connect to
+ * @param options - Configuration options for tracking mode and instance management
+ * @returns Tuple with [state, bloc instance, ref]
+ *
+ * @example Basic usage
+ * ```ts
+ * const [state, myBloc, ref] = useBloc(MyBloc);
+ * ```
+ *
+ * @example With manual dependencies
+ * ```ts
+ * const [state, myBloc] = useBloc(MyBloc, {
+ *   dependencies: (state) => [state.count]
+ * });
+ * ```
+ *
+ * @example With isolated instance
+ * ```ts
+ * const [state, myBloc] = useBloc(MyBloc, {
+ *   instanceId: 'unique-id'
+ * });
+ * ```
+ */
+export declare function useBloc<T extends StateContainerConstructor = StateContainerConstructor>(BlocClass: T, options?: UseBlocOptions<T>): UseBlocReturn<T, ExtractState<T>>;

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

@@ -0,0 +1,18 @@
+/**
+ * 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blac/react",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "license": "MIT",
   "author": "Brendan Mullins <jsnanigans@gmail.com>",
   "repository": {
@@ -12,6 +12,7 @@
   "bugs": {
     "url": "https://github.com/jsnanigans/blac/issues"
   },
+  "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -28,14 +29,13 @@
     }
   },
   "files": [
-    "dist/index.js",
-    "dist/index.cjs",
-    "dist/index.d.ts",
-    "dist/index.d.cts",
-    "dist/*.map",
+    "dist",
     "README.md",
     "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "sideEffects": false,
   "keywords": [
     "react",
@@ -47,11 +47,12 @@
     "bloc-pattern"
   ],
   "dependencies": {
-    "@blac/adapter": "2.0.4"
+    "@blac/adapter": "^2.0.6"
   },
   "peerDependencies": {
     "@types/react": "^18.0.0 || ^19.0.0",
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "@blac/core": "^2.0.6"
   },
   "peerDependenciesMeta": {
     "@types/react": {
@@ -79,15 +80,14 @@
     "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.4"
+    "@blac/core": "2.0.6"
   },
   "scripts": {
     "dev": "tsdown --watch",
-    "build": "pnpm build:js && pnpm build:types && pnpm build:dts",
-    "build:js": "tsdown",
-    "build:types": "tsc -p tsconfig.build.json",
-    "build:dts": "api-extractor run --local && cp dist/index.d.ts dist/index.d.cts && rm -rf dist/.types",
+    "build": "tsdown && tsc -p tsconfig.build.json && cp dist/index.d.ts dist/index.d.cts",
     "clean": "rm -rf dist",
     "format": "prettier --write \".\"",
     "lint": "eslint src --ext .ts,.tsx",
@@ -99,6 +99,7 @@
     "test:compiler": "vitest run --config vitest.config.compiler.ts",
     "test:watch:compiler": "vitest --watch --config vitest.config.compiler.ts",
     "test:both": "pnpm test && echo '\n\n=== Running tests WITH React Compiler ===\n' && pnpm test:compiler",
+    "verify": "node ../../scripts/run-workspace-bin.mjs publint",
     "typecheck": "tsc --noEmit",
     "deploy": "pnpm publish --access public"
   }