@blac/react 2.0.13 → 2.0.15

package/README.md

@@ -50,6 +50,126 @@ const [state, bloc, ref] = useBloc(MyBloc, options?);
 - `bloc` — bloc instance for calling methods
 - `ref` — internal component ref (advanced usage)
 
+### The Three Input Lanes
+
+BlaC blocs receive external data through three distinct channels:
+
+| Lane | Purpose | Keying | Lifetime | Example |
+|---|---|---|---|---|
+| **`args`** | Typed creation data; derives instance identity | **Yes** (structural hash or `static key`) | Once at `init()` | `userId`, `endpoint` |
+| **`deps`** | Non-serializable refs, callbacks, handles | **Never** | Live, per-consumer merged | `ref`, `onComplete` callback, `emblaApi` |
+| **events** | Values that change over time or are late-bound | N/A | Called from effects | `cubit.slidesChanged(v)` from `useEffect` |
+
+### `args`: Typed Construction Data
+
+When a bloc declares `Args`, you must pass them at the call site. Args are fed to the bloc's `init(args)` method before the first state snapshot, and they derive the instance identity by default.
+
+```tsx
+import { Cubit } from '@blac/core';
+import { useBloc } from '@blac/react';
+
+class UserCardCubit extends Cubit<UserCardState, { userId: string }> {
+  // Constructor is zero-arg; framework calls init(args) before first snapshot
+  init(args: { userId: string }) {
+    this.userId = args.userId;
+    void this.loadUser(args.userId);
+  }
+}
+
+function UserCard({ userId }: { userId: string }) {
+  // args is required and type-checked when Args != void
+  const [state, cubit] = useBloc(UserCardCubit, { args: { userId } });
+  return <div>{state.user?.name}</div>;
+}
+```
+
+**Key properties:**
+- **Required when declared** — omitting `args` or passing the wrong shape is a type error.
+- **Drives identity** — different `args` ⇒ different instance. Same `args` ⇒ same instance (dev-warn if args mismatch on same-keyed second call).
+- **Serializable only** — non-serializable values (refs, callbacks) belong in the `deps` lane (below).
+- **Per-component private instances** — use with `autoInstance: true` to give each mount its own instance, disposed on unmount:
+
+```tsx
+const [state, cubit] = useBloc(FormCubit, { args: options, autoInstance: true });
+```
+
+### `deps`: Non-Serializable Refs and Callbacks
+
+Use `deps` to inject refs, stable callbacks, and long-lived controller handles. Unlike `args`, `deps` are:
+- **Never keying** — different refs don't fork the instance
+- **Per-consumer merged** — each component contributes its own slice
+- **Read lazily** — accessed via `this.deps.x` when needed, may be undefined
+- **Live** — can change over time
+
+```tsx
+const inputRef = useRef<HTMLInputElement>(null);
+const onComplete = useCallback(() => { /* ... */ }, []);
+
+const [state, cubit] = useBloc(FileUploadCubit, {
+  args: { endpoint },
+  deps: { inputRef, onComplete },
+});
+```
+
+The bloc reads them lazily and guards for absence:
+
+```ts
+class FileUploadCubit extends Cubit<UploadState, { endpoint: string }, {
+  inputRef?: RefObject<HTMLInputElement>;
+  onComplete?: () => void;
+}> {
+  async upload() {
+    this.deps.inputRef?.current?.click?.();
+    // ... perform upload ...
+    this.deps.onComplete?.();
+  }
+}
+```
+
+**Multi-consumer merge:** when multiple components provide the same cubit with different `deps`, their keys are shallow-merged:
+
+```tsx
+// Component A provides inputRef
+useBloc(FormCubit, { args: { formId }, deps: { inputRef } });
+
+// Component B provides onSubmit
+useBloc(FormCubit, { args: { formId }, deps: { onSubmit } });
+
+// cubit.deps === { inputRef, onSubmit } (merged from both)
+```
+
+**Avoid raw callbacks** — the callback staleness gotcha. Prefer:
+1. **Don't inject callbacks — invert** (best): expose state and let React call the fresh callback in its own effect.
+2. **Stabilize at source** — wrap in `useCallback`.
+3. **As an event** — push the callback via a bloc method called from your effect.
+
+### events: Methods Called from Effects
+
+For data that changes over the instance's life (a `slides` array, a `theme` selection), call an ordinary bloc method from an effect — not a provider-owned input. This keeps ownership explicit and eliminates render-time mutation.
+
+```ts
+class CarouselCubit extends Cubit<CarouselState> {
+  slidesChanged(slides: Slide[]) {
+    this.patch({ slides, total: slides.length });
+  }
+}
+```
+
+```tsx
+function Carousel({ slides }: { slides: Slide[] }) {
+  const [state, cubit] = useBloc(CarouselCubit, { args: { id } });
+
+  // ONE component owns syncing this live value
+  useEffect(() => {
+    cubit.slidesChanged(slides);
+  }, [cubit, slides]);
+
+  return /* ... */;
+}
+```
+
+**Convention:** *one component owns syncing any given live value.* Two components calling the same event from both their effects on the same shared instance is a design smell (and rare, because keyed `args` usually route multi-consumer cases to distinct instances).
+
 ### Tracking Modes
 
 **Auto-tracking (default):** Only re-renders when accessed properties change.
@@ -59,11 +179,11 @@ const [state] = useBloc(UserBloc);
 return <h1>{state.name}</h1>; // only re-renders when name changes
 ```
 
-**Manual dependencies:** Explicit dependency array (disables auto-tracking).
+**Manual dependencies (select):** Explicit dependency array (disables auto-tracking).
 
 ```tsx
 const [state] = useBloc(CounterCubit, {
-  dependencies: (state) => [state.count],
+  select: (state) => [state.count],
 });
 ```
 
@@ -77,21 +197,55 @@ const [state] = useBloc(MyBloc, { autoTrack: false });
 
 | Option         | Type                         | Description                                          |
 | -------------- | ---------------------------- | ---------------------------------------------------- |
+| `args`         | `Args` type                  | Required when bloc declares `Args != void`; forbidden when `void` |
+| `deps`         | `{ [key]: value }`           | Per-consumer slice of non-serializable handles |
 | `autoTrack`    | `boolean`                    | Enable proxy-based auto-tracking (default: `true`)   |
-| `dependencies` | `(state, bloc) => unknown[]` | Manual dependency selector                           |
-| `instanceId`   | `string \| number`           | Use a named instance instead of the shared singleton |
+| `select`       | `(state, bloc) => unknown[]` | Manual dependency selector (renamed from `dependencies`) |
+| `autoInstance` | `boolean`                    | Per-mount instance keyed by `useId()` instead of shared (default: `false`) |
+| `instanceId`   | `string \| number`           | Explicit identity key (overrides args-derived keying) |
 | `onMount`      | `(bloc) => void`             | Called when component mounts                         |
 | `onUnmount`    | `(bloc) => void`             | Called when component unmounts                       |
 
-### Instance Sharing
+### Identity and Keying
 
-By default, all components using `useBloc(MyBloc)` share the same instance. Use `instanceId` for separate instances:
+Instance identity is resolved in precedence order:
+
+1. **Explicit `instanceId`** — hard override if provided
+2. **`autoInstance: true`** — per-mount instance keyed by `useId()`
+3. **`static key(args)` → structural hash of `args`** — default when bloc declares `Args` (if `static key` is defined on the class, it takes precedence; otherwise a stable hash of all `args`)
+4. **`<BlocProvider>` context id** — inherited from parent provider
+5. **`'default'`** — singleton fallback
+
+Blocs declare explicit identity via a static class property:
+
+```ts
+class DocumentCubit extends Cubit<DocState, { docId: string; readonly: boolean }> {
+  static key = (args) => args.docId;
+  // Identity is docId; readonly config rides along but doesn't fork instances
+}
+```
+
+### Instance Sharing and Lifecycle
+
+By default, all components using `useBloc(MyBloc)` with the same identity share one instance. Use `autoInstance` for per-component private instances:
 
 ```tsx
-useBloc(EditorCubit, { instanceId: 'editor-1' }); // instance A
-useBloc(EditorCubit, { instanceId: 'editor-2' }); // instance B
+// All users with userId=123 share one instance
+useBloc(UserCardCubit, { args: { userId: 123 } });
+
+// Each component mount gets its own instance, disposed on unmount
+useBloc(FormCubit, { args: options, autoInstance: true });
+
+// Explicit id (escape hatch for non-derivable identity)
+useBloc(EditorCubit, { instanceId: 'editor-1' });
 ```
 
+### Breaking Changes (v2)
+
+- **`dependencies` option renamed to `select`** — avoids confusion with the new `deps` (non-serializable handles) lane.
+- **Zero-arg constructor + `init(args)` lifecycle** — all blocs now use `new Type()` with no constructor args. Blocs that declare `Args` receive them via `init(args)` called by the framework before the first state snapshot.
+- **`args` is required when declared, forbidden when void** — enforced by the type system; no runtime guard needed.
+
 ## Configuration
 
 ```tsx

package/dist/config.d.ts

@@ -1,24 +1,19 @@
 /**
- * Global configuration for @blac/react
+ * Global configuration for `@blac/react`.
+ *
+ * The hook's tracking model is fixed: when `useBloc` is called without a
+ * `select`, render-time auto-tracking is used (via
+ * `@dirtytalk/structural`'s `trackRender`). When `select` is provided,
+ * re-renders are driven by per-index `Object.is` over the returned array.
+ *
+ * Reserved for forwards-compatible knobs; currently empty.
  */
 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
- * });
- * ```
+ * Configure global defaults for `@blac/react` hooks.
  *
- * @param config - Partial configuration to merge with defaults
+ * @param config - Partial configuration to merge with current globals
  */
 export declare function configureBlacReact(config: Partial<BlacReactConfig>): void;
 /**

package/dist/index.cjs

@@ -1,30 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region \0rolldown/runtime.js
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-//#endregion
 let react = require("react");
-react = __toESM(react);
-let _blac_adapter = require("@blac/adapter");
 let _blac_core = require("@blac/core");
+let _dirtytalk_structural = require("@dirtytalk/structural");
 let react_jsx_runtime = require("react/jsx-runtime");
 //#region src/BlocProvider.tsx
 const InstanceIdContext = (0, react.createContext)(void 0);
@@ -56,185 +33,153 @@ function BlocProvider({ instanceId, children }) {
 function useInstanceIdFromContext() {
 	return (0, react.useContext)(InstanceIdContext);
 }
-let globalConfig = { autoTrack: true };
-/**
-* 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
-*/
-function configureBlacReact(config) {
-	globalConfig = {
-		...globalConfig,
-		...config
-	};
-}
-/**
-* Get the current global configuration.
-* @internal
-*/
-function getBlacReactConfig() {
-	return globalConfig;
-}
 //#endregion
 //#region src/useBloc.ts
 let nextConsumerId = 0;
-function getComponentName() {
-	try {
-		const owner = (react.default.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE ?? react.default.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED)?.ReactCurrentOwner?.current;
-		if (owner?.type) return owner.type.displayName || owner.type.name || void 0;
-	} catch {}
-}
-function determineTrackingMode(options) {
-	const globalConfig = getBlacReactConfig();
-	const autoTrackEnabled = options?.autoTrack !== void 0 ? options.autoTrack : globalConfig.autoTrack;
-	return {
-		useManualDeps: options?.dependencies !== void 0,
-		autoTrackEnabled
-	};
-}
 /**
-* React hook that connects a component to a state container with automatic re-render on state changes.
+* 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
+* Two tracking modes:
+* - **Auto-tracking** (default): the returned state value is a proxy that
+*   records read paths during render. The component re-renders when any
+*   recorded path changes. Backed by `@dirtytalk/structural`'s
+*   {@link trackRender} + the container's path-scoped `DirtyChannel`.
+* - **Manual select**: pass `options.select` to opt out of auto-tracking.
+*   The hook re-renders only when the returned array's elements change
+*   (per-index `Object.is`). This replaces the v1 `dependencies` option.
+*
+* Lifecycle:
+* - The bloc is acquired from the registry on mount and released on
+*   unmount. The instance key is the explicit `options.instanceId`, then
+*   the surrounding {@link BlocProvider} context, then the default key.
+* - `options.onMount` fires after the bloc is acquired; `options.onUnmount`
+*   fires *before* the registry releases its ref, so the bloc is still
+*   alive when the callback runs.
 *
 * @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]
+* @param options - Configuration options
+* @returns Tuple of `[state, bloc, ref]`
 *
 * @example Basic usage
 * ```ts
-* const [state, myBloc, ref] = useBloc(MyBloc);
+* const [state, bloc] = useBloc(MyBloc);
 * ```
 *
-* @example With manual dependencies
+* @example Manual select (replaces v1 `dependencies`)
 * ```ts
-* const [state, myBloc] = useBloc(MyBloc, {
-*   dependencies: (state) => [state.count]
+* const [state, bloc] = useBloc(MyBloc, {
+*   select: (state) => [state.count],
 * });
 * ```
 *
-* @example With named instance
+* @example Named instance
 * ```ts
-* const [state, myBloc] = useBloc(MyBloc, {
-*   instanceId: 'unique-id'
-* });
+* const [state, bloc] = useBloc(MyBloc, { instanceId: 'cart-42' });
 * ```
 */
 function useBloc(BlocClass, options) {
 	const componentRef = (0, react.useRef)({});
 	const consumerIdRef = (0, react.useRef)(null);
-	if (consumerIdRef.current === null) consumerIdRef.current = String(nextConsumerId++);
-	const componentNameRef = (0, react.useRef)(null);
-	if (componentNameRef.current === null) componentNameRef.current = getComponentName() || null;
-	const depsRef = (0, react.useRef)(options?.dependencies);
-	depsRef.current = options?.dependencies;
+	if (consumerIdRef.current === null) consumerIdRef.current = `useBloc-${nextConsumerId++}`;
+	const consumerId = consumerIdRef.current;
+	(0, react.useId)();
+	const selectRef = (0, react.useRef)(options?.select);
+	selectRef.current = options?.select;
 	const onMountRef = (0, react.useRef)(options?.onMount);
 	onMountRef.current = options?.onMount;
 	const onUnmountRef = (0, react.useRef)(options?.onUnmount);
 	onUnmountRef.current = options?.onUnmount;
-	const instanceId = options?.instanceId;
-	const autoTrack = options?.autoTrack;
-	const dependencies = options?.dependencies;
-	const autoInstanceId = react.default.useId();
-	const autoInstance = options?.autoInstance === true || (0, _blac_core.isIsolatedClass)(BlocClass);
+	const args = options?.args;
+	const argsRef = (0, react.useRef)(args);
+	argsRef.current = args;
+	const argsKey = args === void 0 ? void 0 : JSON.stringify(args);
+	const explicitInstanceId = options?.instanceId;
 	const ctxInstanceId = useInstanceIdFromContext();
-	const [bloc, subscribe, getSnapshot, instanceKey, adapterState, rawInstance] = (0, react.useMemo)(() => {
-		const instanceKey = instanceId !== void 0 ? String(instanceId) : autoInstance ? autoInstanceId : ctxInstanceId;
-		const instance = (0, _blac_adapter.acquire)(BlocClass, instanceKey, `useBloc@${componentNameRef.current ?? "Unknown"}-${consumerIdRef.current}`);
-		const { useManualDeps, autoTrackEnabled } = determineTrackingMode({
-			autoTrack,
-			dependencies
-		});
-		let subscribeFn;
-		let getSnapshotFn;
-		let adapterState;
-		if (useManualDeps && dependencies) {
-			adapterState = (0, _blac_adapter.manualDepsInit)(instance);
-			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);
-			getSnapshotFn = (0, _blac_adapter.noTrackSnapshot)(instance);
-		} else {
-			adapterState = (0, _blac_adapter.autoTrackInit)(instance);
-			subscribeFn = (0, _blac_adapter.autoTrackSubscribe)(instance, adapterState);
-			getSnapshotFn = (0, _blac_adapter.autoTrackSnapshot)(instance, adapterState);
-		}
-		return [
-			adapterState.proxiedBloc,
-			subscribeFn,
-			getSnapshotFn,
-			instanceKey,
-			adapterState,
-			instance
-		];
+	const { bloc, instanceKey } = (0, react.useMemo)(() => {
+		const resolvedKey = (0, _blac_core.resolveInstanceKey)(BlocClass, explicitInstanceId !== void 0 ? String(explicitInstanceId) : ctxInstanceId, argsRef.current);
+		return {
+			bloc: (0, _blac_core.acquire)(BlocClass, resolvedKey, `useBloc@${consumerId}`, argsRef.current),
+			instanceKey: resolvedKey
+		};
 	}, [
 		BlocClass,
-		instanceId,
-		autoInstance,
-		autoInstanceId,
-		ctxInstanceId
+		explicitInstanceId,
+		ctxInstanceId,
+		argsKey
 	]);
-	const state = (0, react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
-	const [, forceUpdate] = (0, react.useReducer)((x) => x + 1, 0);
-	const externalDepsManager = (0, react.useRef)(null);
-	if (externalDepsManager.current === null) externalDepsManager.current = new _blac_adapter.ExternalDepsManager();
+	const [, force] = (0, react.useReducer)((x) => x + 1, 0);
+	const pathRef = (0, react.useRef)((0, _dirtytalk_structural.emptyPathSet)());
+	const lastSelectionRef = (0, react.useRef)(null);
 	(0, react.useEffect)(() => {
-		const manager = externalDepsManager.current;
-		(0, _blac_adapter.disableGetterTracking)(adapterState, rawInstance);
-		manager.updateSubscriptions(adapterState.getterState, rawInstance, forceUpdate);
-	}, [
-		adapterState,
-		rawInstance,
-		forceUpdate
-	]);
+		const channel = bloc.channel;
+		if (selectRef.current !== void 0) return channel.subscribe(() => _dirtytalk_structural.ALL_PATHS, () => {
+			const select = selectRef.current;
+			if (!select) {
+				force();
+				return;
+			}
+			const next = select(bloc.state, bloc);
+			const prev = lastSelectionRef.current;
+			if (prev !== null && shallowArrayEqual(prev, next)) return;
+			lastSelectionRef.current = next;
+			force();
+		});
+		const unsub = channel.subscribe(() => pathRef.current, () => force());
+		bloc.registerConsumerPaths(consumerId, pathRef.current);
+		return () => {
+			unsub();
+			bloc.unregisterConsumer(consumerId);
+		};
+	}, [bloc, consumerId]);
 	(0, react.useEffect)(() => {
-		const manager = externalDepsManager.current;
-		const currentInstanceKey = instanceKey;
-		const currentRawInstance = rawInstance;
-		const currentBloc = bloc;
-		const devtools = typeof window !== "undefined" ? window.__BLAC_DEVTOOLS__ : void 0;
-		if (devtools?.registerConsumer && currentRawInstance) devtools.registerConsumer(currentRawInstance.instanceId, consumerIdRef.current, componentNameRef.current || "Unknown");
-		onMountRef.current?.(currentBloc);
+		onMountRef.current?.(bloc);
 		return () => {
-			if (devtools?.unregisterConsumer && currentRawInstance) devtools.unregisterConsumer(currentRawInstance.instanceId, consumerIdRef.current);
-			manager.cleanup();
-			onUnmountRef.current?.(currentBloc);
-			(0, _blac_adapter.release)(BlocClass, currentInstanceKey, false, `useBloc@${componentNameRef.current ?? "Unknown"}-${consumerIdRef.current}`);
+			onUnmountRef.current?.(bloc);
+			(0, _blac_core.release)(BlocClass, instanceKey, false, `useBloc@${consumerId}`);
 		};
-	}, [
-		bloc,
-		instanceKey,
-		rawInstance
-	]);
+	}, [bloc, instanceKey]);
+	const rawState = bloc.state;
+	let state;
+	if (selectRef.current !== void 0) {
+		state = rawState;
+		if (lastSelectionRef.current === null) lastSelectionRef.current = selectRef.current(rawState, bloc);
+	} else {
+		const tracked = (0, _dirtytalk_structural.trackRender)(rawState, bloc.interner);
+		state = tracked.value;
+		pathRef.current = tracked.paths;
+	}
+	(0, react.useLayoutEffect)(() => {
+		if (selectRef.current !== void 0) return;
+		bloc.registerConsumerPaths(consumerId, pathRef.current);
+	});
 	return [
 		state,
 		bloc,
 		componentRef
 	];
 }
+const shallowArrayEqual = (a, b) => {
+	if (a === b) return true;
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (!Object.is(a[i], b[i])) return false;
+	return true;
+};
+let globalConfig = {};
+/**
+* Configure global defaults for `@blac/react` hooks.
+*
+* @param config - Partial configuration to merge with current globals
+*/
+function configureBlacReact(config) {
+	globalConfig = {
+		...globalConfig,
+		...config
+	};
+}
 //#endregion
 exports.BlocProvider = BlocProvider;
-exports.__toESM = __toESM;
 exports.configureBlacReact = configureBlacReact;
 exports.useBloc = useBloc;
 exports.useInstanceIdFromContext = useInstanceIdFromContext;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["React","ExternalDepsManager"],"sources":["../src/BlocProvider.tsx","../src/config.ts","../src/useBloc.ts"],"sourcesContent":["import {\n  createContext,\n  useContext,\n  type ReactElement,\n  type ReactNode,\n} from 'react';\n\nconst InstanceIdContext = createContext<string | undefined>(undefined);\n\n/**\n * Props for {@link BlocProvider}.\n */\nexport interface BlocProviderProps {\n  /**\n   * Instance id that descendants' `useBloc(C)` calls will resolve to when no\n   * explicit `instanceId` is given.\n   */\n  instanceId: string | number;\n  children: ReactNode;\n}\n\n/**\n * Provides an `instanceId` to descendant `useBloc` calls via React context.\n *\n * Descendants calling `useBloc(C)` without an `instanceId` resolve to the id\n * supplied here. An explicit `instanceId` on the `useBloc` call still wins.\n * `autoInstance` / `static isolated = true` also override the context, because\n * those force a per-mount auto-key.\n *\n * @example\n * ```tsx\n * <BlocProvider instanceId=\"customer-42\">\n *   <CustomerView />\n * </BlocProvider>\n * ```\n */\nexport function BlocProvider({\n  instanceId,\n  children,\n}: BlocProviderProps): ReactElement {\n  return (\n    <InstanceIdContext.Provider value={String(instanceId)}>\n      {children}\n    </InstanceIdContext.Provider>\n  );\n}\n\n/**\n * Reads the nearest {@link BlocProvider} instance id, or `undefined` when\n * called outside a provider.\n */\nexport function useInstanceIdFromContext(): string | undefined {\n  return useContext(InstanceIdContext);\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 React, {\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 { isIsolatedClass } from '@blac/core';\nimport { useInstanceIdFromContext } from './BlocProvider';\nimport type { UseBlocOptions, UseBlocReturn, ComponentRef } from './types';\nimport { getBlacReactConfig } from './config';\n\nlet nextConsumerId = 0;\n\nfunction getComponentName(): string | undefined {\n  try {\n    const internals =\n      (React as any)\n        .__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE ??\n      (React as any).__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;\n    const owner = internals?.ReactCurrentOwner?.current;\n    if (owner?.type) {\n      return owner.type.displayName || owner.type.name || undefined;\n    }\n  } catch {\n    // ignore — React internals may not be available\n  }\n  return undefined;\n}\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\n  // Capture component name from React fiber during render (for devtools consumer tracking)\n  const consumerIdRef = useRef<string | null>(null);\n  if (consumerIdRef.current === null) {\n    consumerIdRef.current = String(nextConsumerId++);\n  }\n  const componentNameRef = useRef<string | null>(null);\n  if (componentNameRef.current === null) {\n    componentNameRef.current = getComponentName() || null;\n  }\n\n  const depsRef = useRef(options?.dependencies);\n  depsRef.current = options?.dependencies;\n  const onMountRef = useRef(options?.onMount);\n  onMountRef.current = options?.onMount;\n  const onUnmountRef = useRef(options?.onUnmount);\n  onUnmountRef.current = options?.onUnmount;\n  const instanceId = options?.instanceId;\n  const autoTrack = options?.autoTrack;\n  const dependencies = options?.dependencies;\n\n  // Auto-keyed per-mount instance: either declared on the class\n  // (`static isolated = true`) or opted into per call (`autoInstance: true`).\n  // `useId()` is always called to satisfy the rules of hooks.\n  const autoInstanceId = React.useId();\n  const autoInstance =\n    options?.autoInstance === true || isIsolatedClass(BlocClass);\n  // Resolve `instanceId` from a surrounding <BlocProvider> when not given\n  // explicitly and not auto-keyed.\n  const ctxInstanceId = useInstanceIdFromContext();\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\n          ? String(instanceId)\n          : autoInstance\n            ? autoInstanceId\n            : ctxInstanceId;\n\n      const refId = `useBloc@${componentNameRef.current ?? 'Unknown'}-${consumerIdRef.current}`;\n      const instance = acquire(BlocClass, instanceKey, refId) 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      // oxlint-disable-next-line react-hooks/exhaustive-deps\n    }, [BlocClass, instanceId, autoInstance, autoInstanceId, ctxInstanceId]);\n\n  const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  const [, forceUpdate] = useReducer((x: number) => x + 1, 0);\n\n  const externalDepsManager = useRef<ExternalDepsManager>(null);\n  if (externalDepsManager.current === null) {\n    (\n      externalDepsManager as React.MutableRefObject<ExternalDepsManager>\n    ).current = new ExternalDepsManager();\n  }\n\n  useEffect(() => {\n    const manager = externalDepsManager.current!;\n    disableGetterTracking(adapterState, rawInstance);\n    manager.updateSubscriptions(\n      adapterState.getterState,\n      rawInstance,\n      forceUpdate,\n    );\n  }, [adapterState, rawInstance, forceUpdate]);\n\n  useEffect(() => {\n    const manager = externalDepsManager.current!;\n    const currentInstanceKey = instanceKey;\n    const currentRawInstance = rawInstance;\n    const currentBloc = bloc;\n\n    // Register as consumer in devtools (if available)\n    const devtools =\n      typeof window !== 'undefined'\n        ? (window as any).__BLAC_DEVTOOLS__\n        : undefined;\n    if (devtools?.registerConsumer && currentRawInstance) {\n      devtools.registerConsumer(\n        (currentRawInstance as any).instanceId,\n        consumerIdRef.current,\n        componentNameRef.current || 'Unknown',\n      );\n    }\n\n    onMountRef.current?.(currentBloc as InstanceType<T>);\n\n    return () => {\n      if (devtools?.unregisterConsumer && currentRawInstance) {\n        devtools.unregisterConsumer(\n          (currentRawInstance as any).instanceId,\n          consumerIdRef.current,\n        );\n      }\n\n      manager.cleanup();\n\n      onUnmountRef.current?.(currentBloc as InstanceType<T>);\n\n      const refId = `useBloc@${componentNameRef.current ?? 'Unknown'}-${consumerIdRef.current}`;\n      release(BlocClass, currentInstanceKey, false, refId);\n    };\n    // oxlint-disable-next-line react-hooks/exhaustive-deps\n  }, [bloc, instanceKey, rawInstance]);\n\n  return [state, bloc, componentRef] as UseBlocReturn<T, ExtractState<T>>;\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.cjs","names":["ALL_PATHS"],"sources":["../src/BlocProvider.tsx","../src/useBloc.ts","../src/config.ts"],"sourcesContent":["import {\n  createContext,\n  useContext,\n  type ReactElement,\n  type ReactNode,\n} from 'react';\n\nconst InstanceIdContext = createContext<string | undefined>(undefined);\n\n/**\n * Props for {@link BlocProvider}.\n */\nexport interface BlocProviderProps {\n  /**\n   * Instance id that descendants' `useBloc(C)` calls will resolve to when no\n   * explicit `instanceId` is given.\n   */\n  instanceId: string | number;\n  children: ReactNode;\n}\n\n/**\n * Provides an `instanceId` to descendant `useBloc` calls via React context.\n *\n * Descendants calling `useBloc(C)` without an `instanceId` resolve to the id\n * supplied here. An explicit `instanceId` on the `useBloc` call still wins.\n * `autoInstance` / `static isolated = true` also override the context, because\n * those force a per-mount auto-key.\n *\n * @example\n * ```tsx\n * <BlocProvider instanceId=\"customer-42\">\n *   <CustomerView />\n * </BlocProvider>\n * ```\n */\nexport function BlocProvider({\n  instanceId,\n  children,\n}: BlocProviderProps): ReactElement {\n  return (\n    <InstanceIdContext.Provider value={String(instanceId)}>\n      {children}\n    </InstanceIdContext.Provider>\n  );\n}\n\n/**\n * Reads the nearest {@link BlocProvider} instance id, or `undefined` when\n * called outside a provider.\n */\nexport function useInstanceIdFromContext(): string | undefined {\n  return useContext(InstanceIdContext);\n}\n","import {\n  useEffect,\n  useId,\n  useLayoutEffect,\n  useMemo,\n  useReducer,\n  useRef,\n  type RefObject,\n} from 'react';\nimport {\n  acquire,\n  release,\n  resolveInstanceKey,\n  type ExtractArgs,\n  type ExtractState,\n  type InstanceState,\n  type StateContainer,\n  type StateContainerConstructor,\n} from '@blac/core';\nimport {\n  ALL_PATHS,\n  emptyPathSet,\n  trackRender,\n  type PathSet,\n} from '@dirtytalk/structural';\nimport { useInstanceIdFromContext } from './BlocProvider';\nimport type { ComponentRef, UseBlocOptions, UseBlocReturn } from './types';\n\nlet nextConsumerId = 0;\n\n/**\n * React hook that connects a component to a state container with automatic\n * re-render on state changes.\n *\n * Two tracking modes:\n * - **Auto-tracking** (default): the returned state value is a proxy that\n *   records read paths during render. The component re-renders when any\n *   recorded path changes. Backed by `@dirtytalk/structural`'s\n *   {@link trackRender} + the container's path-scoped `DirtyChannel`.\n * - **Manual select**: pass `options.select` to opt out of auto-tracking.\n *   The hook re-renders only when the returned array's elements change\n *   (per-index `Object.is`). This replaces the v1 `dependencies` option.\n *\n * Lifecycle:\n * - The bloc is acquired from the registry on mount and released on\n *   unmount. The instance key is the explicit `options.instanceId`, then\n *   the surrounding {@link BlocProvider} context, then the default key.\n * - `options.onMount` fires after the bloc is acquired; `options.onUnmount`\n *   fires *before* the registry releases its ref, so the bloc is still\n *   alive when the callback runs.\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\n * @returns Tuple of `[state, bloc, ref]`\n *\n * @example Basic usage\n * ```ts\n * const [state, bloc] = useBloc(MyBloc);\n * ```\n *\n * @example Manual select (replaces v1 `dependencies`)\n * ```ts\n * const [state, bloc] = useBloc(MyBloc, {\n *   select: (state) => [state.count],\n * });\n * ```\n *\n * @example Named instance\n * ```ts\n * const [state, bloc] = useBloc(MyBloc, { instanceId: 'cart-42' });\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\n  // Stable per-consumer id (for the structural container's consumer registry).\n  // Plain counter rather than `useId()` so we don't compete with internal hooks\n  // for SSR id slots.\n  const consumerIdRef = useRef<string | null>(null);\n  if (consumerIdRef.current === null) {\n    consumerIdRef.current = `useBloc-${nextConsumerId++}`;\n  }\n  const consumerId = consumerIdRef.current;\n  // Reserve a useId slot — kept for forwards compatibility and to match\n  // BlocProvider-driven SSR hydration alignment (no-op call).\n  useId();\n\n  // Refs that always carry the latest option callbacks, so the commit effect\n  // can read them without re-keying.\n  const selectRef = useRef(options?.select);\n  selectRef.current = options?.select;\n  const onMountRef = useRef(options?.onMount);\n  onMountRef.current = options?.onMount;\n  const onUnmountRef = useRef(options?.onUnmount);\n  onUnmountRef.current = options?.onUnmount;\n\n  // ---------------------------------------------------------------------------\n  // Identity resolution\n  //\n  // Args are user-supplied; callers commonly pass a fresh object literal each\n  // render. Memoising on `args` directly would bust every render. We compute a\n  // structural key (JSON.stringify) for the useMemo dep instead — undefined\n  // args (void-args blocs) collapse to an undefined key.\n  // ---------------------------------------------------------------------------\n  const args = (options as { args?: ExtractArgs<T> } | undefined)?.args;\n  const argsRef = useRef(args);\n  argsRef.current = args;\n  const argsKey = args === undefined ? undefined : JSON.stringify(args);\n\n  const explicitInstanceId = options?.instanceId;\n  const ctxInstanceId = useInstanceIdFromContext();\n\n  const { bloc, instanceKey } = useMemo<{\n    bloc: TBloc;\n    instanceKey: string;\n  }>(() => {\n    const explicitKey =\n      explicitInstanceId !== undefined\n        ? String(explicitInstanceId)\n        : ctxInstanceId;\n    const resolvedKey = resolveInstanceKey(\n      BlocClass,\n      explicitKey,\n      argsRef.current,\n    );\n    const refId = `useBloc@${consumerId}`;\n    const instance = acquire(\n      BlocClass,\n      resolvedKey,\n      refId,\n      argsRef.current,\n    ) as TBloc;\n    return { bloc: instance, instanceKey: resolvedKey };\n    // oxlint-disable-next-line react-hooks/exhaustive-deps\n  }, [BlocClass, explicitInstanceId, ctxInstanceId, argsKey]);\n\n  // ---------------------------------------------------------------------------\n  // Channel subscription\n  //\n  // We bypass `bloc.subscribe(listener)` (the legacy listener surface, which\n  // StateContainer overrides) and talk directly to `bloc.channel`. The channel\n  // is the StructuralContainer's path-scoped DirtyChannel; subscribing with a\n  // dynamic interest function lets us narrow wakeups per consumer.\n  // ---------------------------------------------------------------------------\n  const [, force] = useReducer((x: number) => x + 1, 0);\n  const pathRef = useRef<PathSet>(emptyPathSet());\n  // For select-mode: cache the last selected array so we can compare against\n  // the next one before forcing a re-render.\n  const lastSelectionRef = useRef<unknown[] | null>(null);\n\n  useEffect(() => {\n    // Subscribe via the channel directly. For auto-track we re-register the\n    // current path interest on each commit (below); for select-mode we use\n    // ALL_PATHS and compare selections in the callback.\n    const channel = (bloc as unknown as StateContainer).channel;\n    const isSelectMode = selectRef.current !== undefined;\n\n    if (isSelectMode) {\n      const unsub = channel.subscribe(\n        () => ALL_PATHS,\n        () => {\n          const select = selectRef.current;\n          if (!select) {\n            force();\n            return;\n          }\n          const next = select(\n            (bloc as unknown as StateContainer).state as ExtractState<T>,\n            bloc as InstanceState<T>,\n          );\n          const prev = lastSelectionRef.current;\n          if (prev !== null && shallowArrayEqual(prev, next)) return;\n          lastSelectionRef.current = next;\n          force();\n        },\n      );\n      return unsub;\n    }\n\n    // Auto-track mode: wake on any change that intersects the recorded paths.\n    // `() => pathRef.current` is called by the channel on every flush, so we\n    // always see the latest interest without re-subscribing.\n    const unsub = channel.subscribe(\n      () => pathRef.current,\n      () => force(),\n    );\n    // Also register the consumer paths with the container for skeleton\n    // recomputation, so the source-side diff can skip us when our paths don't\n    // intersect the change.\n    (bloc as unknown as StateContainer).registerConsumerPaths(\n      consumerId,\n      pathRef.current,\n    );\n    return () => {\n      unsub();\n      (bloc as unknown as StateContainer).unregisterConsumer(consumerId);\n    };\n  }, [bloc, consumerId]);\n\n  // ---------------------------------------------------------------------------\n  // Mount / unmount lifecycle.\n  //\n  // Order on unmount: onUnmount(bloc) -> release(...). The bloc must still be\n  // alive when onUnmount runs (release may dispose it).\n  // ---------------------------------------------------------------------------\n  useEffect(() => {\n    onMountRef.current?.(bloc as InstanceType<T>);\n    return () => {\n      onUnmountRef.current?.(bloc as InstanceType<T>);\n      const refId = `useBloc@${consumerId}`;\n      release(BlocClass, instanceKey, false, refId);\n    };\n    // oxlint-disable-next-line react-hooks/exhaustive-deps\n  }, [bloc, instanceKey]);\n\n  // ---------------------------------------------------------------------------\n  // Snapshot\n  //\n  // - Auto-track: wrap state in trackRender, record paths into pathRef, and\n  //   re-register with the container so the skeleton picks up new interest.\n  // - Select-mode: return state directly; the subscription callback compares\n  //   selections to decide whether to re-render.\n  // ---------------------------------------------------------------------------\n  const rawState = (bloc as unknown as StateContainer).state as ExtractState<T>;\n  let state: ExtractState<T>;\n  if (selectRef.current !== undefined) {\n    state = rawState;\n    // Seed the last selection on the first render so we don't fire an\n    // immediate \"different from null\" wakeup on the first emit.\n    if (lastSelectionRef.current === null) {\n      lastSelectionRef.current = selectRef.current(\n        rawState,\n        bloc as InstanceState<T>,\n      );\n    }\n  } else {\n    const tracked = trackRender(\n      rawState,\n      (bloc as unknown as StateContainer).interner,\n    );\n    state = tracked.value as ExtractState<T>;\n    pathRef.current = tracked.paths;\n    // NOTE: registerConsumerPaths is intentionally NOT called here. The\n    // proxy hasn't been accessed yet, so `tracked.paths` is an empty Set\n    // that the proxy will mutate during JSX evaluation. Registering at\n    // this point would store an empty interest with the container and\n    // freeze the skeleton at that snapshot — subsequent emits would\n    // diff against an empty skeleton and silently drop wakeups. The\n    // useLayoutEffect below registers the populated set after render.\n  }\n\n  // After the render commits the proxy has been touched and pathRef.current\n  // is the consumer's actual interest. Re-register with the container so the\n  // skeleton reflects the latest paths. useLayoutEffect runs before the\n  // browser paints (and before any emit triggered by another effect), so the\n  // skeleton is fresh by the time the next emit fires.\n  // oxlint-disable-next-line react-hooks/exhaustive-deps\n  useLayoutEffect(() => {\n    if (selectRef.current !== undefined) return;\n    (bloc as unknown as StateContainer).registerConsumerPaths(\n      consumerId,\n      pathRef.current,\n    );\n  });\n\n  return [\n    state,\n    bloc,\n    componentRef as RefObject<ComponentRef>,\n  ] as UseBlocReturn<T, ExtractState<T>>;\n}\n\nconst shallowArrayEqual = (a: unknown[], b: unknown[]): boolean => {\n  if (a === b) return true;\n  if (a.length !== b.length) return false;\n  for (let i = 0; i < a.length; i++) {\n    if (!Object.is(a[i], b[i])) return false;\n  }\n  return true;\n};\n","/**\n * Global configuration for `@blac/react`.\n *\n * The hook's tracking model is fixed: when `useBloc` is called without a\n * `select`, render-time auto-tracking is used (via\n * `@dirtytalk/structural`'s `trackRender`). When `select` is provided,\n * re-renders are driven by per-index `Object.is` over the returned array.\n *\n * Reserved for forwards-compatible knobs; currently empty.\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type\nexport interface BlacReactConfig {}\n\nconst defaultConfig: BlacReactConfig = {};\n\nlet globalConfig: BlacReactConfig = { ...defaultConfig };\n\n/**\n * Configure global defaults for `@blac/react` hooks.\n *\n * @param config - Partial configuration to merge with current globals\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"],"mappings":"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"}

package/dist/index.js

@@ -1,6 +1,6 @@
-import React, { createContext, useContext, useEffect, useMemo, useReducer, useRef, useSyncExternalStore } from "react";
-import { ExternalDepsManager, acquire, autoTrackInit, autoTrackSnapshot, autoTrackSubscribe, disableGetterTracking, manualDepsInit, manualDepsSnapshot, manualDepsSubscribe, noTrackInit, noTrackSnapshot, noTrackSubscribe, release } from "@blac/adapter";
-import { isIsolatedClass } from "@blac/core";
+import { createContext, useContext, useEffect, useId, useLayoutEffect, useMemo, useReducer, useRef } from "react";
+import { acquire, release, resolveInstanceKey } from "@blac/core";
+import { ALL_PATHS, emptyPathSet, trackRender } from "@dirtytalk/structural";
 import { jsx } from "react/jsx-runtime";
 //#region src/BlocProvider.tsx
 const InstanceIdContext = createContext(void 0);
@@ -32,182 +32,151 @@ function BlocProvider({ instanceId, children }) {
 function useInstanceIdFromContext() {
 	return useContext(InstanceIdContext);
 }
-let globalConfig = { autoTrack: true };
-/**
-* 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
-*/
-function configureBlacReact(config) {
-	globalConfig = {
-		...globalConfig,
-		...config
-	};
-}
-/**
-* Get the current global configuration.
-* @internal
-*/
-function getBlacReactConfig() {
-	return globalConfig;
-}
 //#endregion
 //#region src/useBloc.ts
 let nextConsumerId = 0;
-function getComponentName() {
-	try {
-		const owner = (React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE ?? React.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED)?.ReactCurrentOwner?.current;
-		if (owner?.type) return owner.type.displayName || owner.type.name || void 0;
-	} catch {}
-}
-function determineTrackingMode(options) {
-	const globalConfig = getBlacReactConfig();
-	const autoTrackEnabled = options?.autoTrack !== void 0 ? options.autoTrack : globalConfig.autoTrack;
-	return {
-		useManualDeps: options?.dependencies !== void 0,
-		autoTrackEnabled
-	};
-}
 /**
-* React hook that connects a component to a state container with automatic re-render on state changes.
+* React hook that connects a component to a state container with automatic
+* re-render on state changes.
+*
+* Two tracking modes:
+* - **Auto-tracking** (default): the returned state value is a proxy that
+*   records read paths during render. The component re-renders when any
+*   recorded path changes. Backed by `@dirtytalk/structural`'s
+*   {@link trackRender} + the container's path-scoped `DirtyChannel`.
+* - **Manual select**: pass `options.select` to opt out of auto-tracking.
+*   The hook re-renders only when the returned array's elements change
+*   (per-index `Object.is`). This replaces the v1 `dependencies` option.
 *
-* 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
+* Lifecycle:
+* - The bloc is acquired from the registry on mount and released on
+*   unmount. The instance key is the explicit `options.instanceId`, then
+*   the surrounding {@link BlocProvider} context, then the default key.
+* - `options.onMount` fires after the bloc is acquired; `options.onUnmount`
+*   fires *before* the registry releases its ref, so the bloc is still
+*   alive when the callback runs.
 *
 * @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]
+* @param options - Configuration options
+* @returns Tuple of `[state, bloc, ref]`
 *
 * @example Basic usage
 * ```ts
-* const [state, myBloc, ref] = useBloc(MyBloc);
+* const [state, bloc] = useBloc(MyBloc);
 * ```
 *
-* @example With manual dependencies
+* @example Manual select (replaces v1 `dependencies`)
 * ```ts
-* const [state, myBloc] = useBloc(MyBloc, {
-*   dependencies: (state) => [state.count]
+* const [state, bloc] = useBloc(MyBloc, {
+*   select: (state) => [state.count],
 * });
 * ```
 *
-* @example With named instance
+* @example Named instance
 * ```ts
-* const [state, myBloc] = useBloc(MyBloc, {
-*   instanceId: 'unique-id'
-* });
+* const [state, bloc] = useBloc(MyBloc, { instanceId: 'cart-42' });
 * ```
 */
 function useBloc(BlocClass, options) {
 	const componentRef = useRef({});
 	const consumerIdRef = useRef(null);
-	if (consumerIdRef.current === null) consumerIdRef.current = String(nextConsumerId++);
-	const componentNameRef = useRef(null);
-	if (componentNameRef.current === null) componentNameRef.current = getComponentName() || null;
-	const depsRef = useRef(options?.dependencies);
-	depsRef.current = options?.dependencies;
+	if (consumerIdRef.current === null) consumerIdRef.current = `useBloc-${nextConsumerId++}`;
+	const consumerId = consumerIdRef.current;
+	useId();
+	const selectRef = useRef(options?.select);
+	selectRef.current = options?.select;
 	const onMountRef = useRef(options?.onMount);
 	onMountRef.current = options?.onMount;
 	const onUnmountRef = useRef(options?.onUnmount);
 	onUnmountRef.current = options?.onUnmount;
-	const instanceId = options?.instanceId;
-	const autoTrack = options?.autoTrack;
-	const dependencies = options?.dependencies;
-	const autoInstanceId = React.useId();
-	const autoInstance = options?.autoInstance === true || isIsolatedClass(BlocClass);
+	const args = options?.args;
+	const argsRef = useRef(args);
+	argsRef.current = args;
+	const argsKey = args === void 0 ? void 0 : JSON.stringify(args);
+	const explicitInstanceId = options?.instanceId;
 	const ctxInstanceId = useInstanceIdFromContext();
-	const [bloc, subscribe, getSnapshot, instanceKey, adapterState, rawInstance] = useMemo(() => {
-		const instanceKey = instanceId !== void 0 ? String(instanceId) : autoInstance ? autoInstanceId : ctxInstanceId;
-		const instance = acquire(BlocClass, instanceKey, `useBloc@${componentNameRef.current ?? "Unknown"}-${consumerIdRef.current}`);
-		const { useManualDeps, autoTrackEnabled } = determineTrackingMode({
-			autoTrack,
-			dependencies
-		});
-		let subscribeFn;
-		let getSnapshotFn;
-		let adapterState;
-		if (useManualDeps && dependencies) {
-			adapterState = manualDepsInit(instance);
-			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);
-			getSnapshotFn = noTrackSnapshot(instance);
-		} else {
-			adapterState = autoTrackInit(instance);
-			subscribeFn = autoTrackSubscribe(instance, adapterState);
-			getSnapshotFn = autoTrackSnapshot(instance, adapterState);
-		}
-		return [
-			adapterState.proxiedBloc,
-			subscribeFn,
-			getSnapshotFn,
-			instanceKey,
-			adapterState,
-			instance
-		];
+	const { bloc, instanceKey } = useMemo(() => {
+		const resolvedKey = resolveInstanceKey(BlocClass, explicitInstanceId !== void 0 ? String(explicitInstanceId) : ctxInstanceId, argsRef.current);
+		return {
+			bloc: acquire(BlocClass, resolvedKey, `useBloc@${consumerId}`, argsRef.current),
+			instanceKey: resolvedKey
+		};
 	}, [
 		BlocClass,
-		instanceId,
-		autoInstance,
-		autoInstanceId,
-		ctxInstanceId
+		explicitInstanceId,
+		ctxInstanceId,
+		argsKey
 	]);
-	const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-	const [, forceUpdate] = useReducer((x) => x + 1, 0);
-	const externalDepsManager = useRef(null);
-	if (externalDepsManager.current === null) externalDepsManager.current = new ExternalDepsManager();
+	const [, force] = useReducer((x) => x + 1, 0);
+	const pathRef = useRef(emptyPathSet());
+	const lastSelectionRef = useRef(null);
 	useEffect(() => {
-		const manager = externalDepsManager.current;
-		disableGetterTracking(adapterState, rawInstance);
-		manager.updateSubscriptions(adapterState.getterState, rawInstance, forceUpdate);
-	}, [
-		adapterState,
-		rawInstance,
-		forceUpdate
-	]);
+		const channel = bloc.channel;
+		if (selectRef.current !== void 0) return channel.subscribe(() => ALL_PATHS, () => {
+			const select = selectRef.current;
+			if (!select) {
+				force();
+				return;
+			}
+			const next = select(bloc.state, bloc);
+			const prev = lastSelectionRef.current;
+			if (prev !== null && shallowArrayEqual(prev, next)) return;
+			lastSelectionRef.current = next;
+			force();
+		});
+		const unsub = channel.subscribe(() => pathRef.current, () => force());
+		bloc.registerConsumerPaths(consumerId, pathRef.current);
+		return () => {
+			unsub();
+			bloc.unregisterConsumer(consumerId);
+		};
+	}, [bloc, consumerId]);
 	useEffect(() => {
-		const manager = externalDepsManager.current;
-		const currentInstanceKey = instanceKey;
-		const currentRawInstance = rawInstance;
-		const currentBloc = bloc;
-		const devtools = typeof window !== "undefined" ? window.__BLAC_DEVTOOLS__ : void 0;
-		if (devtools?.registerConsumer && currentRawInstance) devtools.registerConsumer(currentRawInstance.instanceId, consumerIdRef.current, componentNameRef.current || "Unknown");
-		onMountRef.current?.(currentBloc);
+		onMountRef.current?.(bloc);
 		return () => {
-			if (devtools?.unregisterConsumer && currentRawInstance) devtools.unregisterConsumer(currentRawInstance.instanceId, consumerIdRef.current);
-			manager.cleanup();
-			onUnmountRef.current?.(currentBloc);
-			release(BlocClass, currentInstanceKey, false, `useBloc@${componentNameRef.current ?? "Unknown"}-${consumerIdRef.current}`);
+			onUnmountRef.current?.(bloc);
+			release(BlocClass, instanceKey, false, `useBloc@${consumerId}`);
 		};
-	}, [
-		bloc,
-		instanceKey,
-		rawInstance
-	]);
+	}, [bloc, instanceKey]);
+	const rawState = bloc.state;
+	let state;
+	if (selectRef.current !== void 0) {
+		state = rawState;
+		if (lastSelectionRef.current === null) lastSelectionRef.current = selectRef.current(rawState, bloc);
+	} else {
+		const tracked = trackRender(rawState, bloc.interner);
+		state = tracked.value;
+		pathRef.current = tracked.paths;
+	}
+	useLayoutEffect(() => {
+		if (selectRef.current !== void 0) return;
+		bloc.registerConsumerPaths(consumerId, pathRef.current);
+	});
 	return [
 		state,
 		bloc,
 		componentRef
 	];
 }
+const shallowArrayEqual = (a, b) => {
+	if (a === b) return true;
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (!Object.is(a[i], b[i])) return false;
+	return true;
+};
+let globalConfig = {};
+/**
+* Configure global defaults for `@blac/react` hooks.
+*
+* @param config - Partial configuration to merge with current globals
+*/
+function configureBlacReact(config) {
+	globalConfig = {
+		...globalConfig,
+		...config
+	};
+}
 //#endregion
 export { BlocProvider, configureBlacReact, useBloc, useInstanceIdFromContext };
 

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/BlocProvider.tsx","../src/config.ts","../src/useBloc.ts"],"sourcesContent":["import {\n  createContext,\n  useContext,\n  type ReactElement,\n  type ReactNode,\n} from 'react';\n\nconst InstanceIdContext = createContext<string | undefined>(undefined);\n\n/**\n * Props for {@link BlocProvider}.\n */\nexport interface BlocProviderProps {\n  /**\n   * Instance id that descendants' `useBloc(C)` calls will resolve to when no\n   * explicit `instanceId` is given.\n   */\n  instanceId: string | number;\n  children: ReactNode;\n}\n\n/**\n * Provides an `instanceId` to descendant `useBloc` calls via React context.\n *\n * Descendants calling `useBloc(C)` without an `instanceId` resolve to the id\n * supplied here. An explicit `instanceId` on the `useBloc` call still wins.\n * `autoInstance` / `static isolated = true` also override the context, because\n * those force a per-mount auto-key.\n *\n * @example\n * ```tsx\n * <BlocProvider instanceId=\"customer-42\">\n *   <CustomerView />\n * </BlocProvider>\n * ```\n */\nexport function BlocProvider({\n  instanceId,\n  children,\n}: BlocProviderProps): ReactElement {\n  return (\n    <InstanceIdContext.Provider value={String(instanceId)}>\n      {children}\n    </InstanceIdContext.Provider>\n  );\n}\n\n/**\n * Reads the nearest {@link BlocProvider} instance id, or `undefined` when\n * called outside a provider.\n */\nexport function useInstanceIdFromContext(): string | undefined {\n  return useContext(InstanceIdContext);\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 React, {\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 { isIsolatedClass } from '@blac/core';\nimport { useInstanceIdFromContext } from './BlocProvider';\nimport type { UseBlocOptions, UseBlocReturn, ComponentRef } from './types';\nimport { getBlacReactConfig } from './config';\n\nlet nextConsumerId = 0;\n\nfunction getComponentName(): string | undefined {\n  try {\n    const internals =\n      (React as any)\n        .__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE ??\n      (React as any).__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;\n    const owner = internals?.ReactCurrentOwner?.current;\n    if (owner?.type) {\n      return owner.type.displayName || owner.type.name || undefined;\n    }\n  } catch {\n    // ignore — React internals may not be available\n  }\n  return undefined;\n}\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\n  // Capture component name from React fiber during render (for devtools consumer tracking)\n  const consumerIdRef = useRef<string | null>(null);\n  if (consumerIdRef.current === null) {\n    consumerIdRef.current = String(nextConsumerId++);\n  }\n  const componentNameRef = useRef<string | null>(null);\n  if (componentNameRef.current === null) {\n    componentNameRef.current = getComponentName() || null;\n  }\n\n  const depsRef = useRef(options?.dependencies);\n  depsRef.current = options?.dependencies;\n  const onMountRef = useRef(options?.onMount);\n  onMountRef.current = options?.onMount;\n  const onUnmountRef = useRef(options?.onUnmount);\n  onUnmountRef.current = options?.onUnmount;\n  const instanceId = options?.instanceId;\n  const autoTrack = options?.autoTrack;\n  const dependencies = options?.dependencies;\n\n  // Auto-keyed per-mount instance: either declared on the class\n  // (`static isolated = true`) or opted into per call (`autoInstance: true`).\n  // `useId()` is always called to satisfy the rules of hooks.\n  const autoInstanceId = React.useId();\n  const autoInstance =\n    options?.autoInstance === true || isIsolatedClass(BlocClass);\n  // Resolve `instanceId` from a surrounding <BlocProvider> when not given\n  // explicitly and not auto-keyed.\n  const ctxInstanceId = useInstanceIdFromContext();\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\n          ? String(instanceId)\n          : autoInstance\n            ? autoInstanceId\n            : ctxInstanceId;\n\n      const refId = `useBloc@${componentNameRef.current ?? 'Unknown'}-${consumerIdRef.current}`;\n      const instance = acquire(BlocClass, instanceKey, refId) 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      // oxlint-disable-next-line react-hooks/exhaustive-deps\n    }, [BlocClass, instanceId, autoInstance, autoInstanceId, ctxInstanceId]);\n\n  const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  const [, forceUpdate] = useReducer((x: number) => x + 1, 0);\n\n  const externalDepsManager = useRef<ExternalDepsManager>(null);\n  if (externalDepsManager.current === null) {\n    (\n      externalDepsManager as React.MutableRefObject<ExternalDepsManager>\n    ).current = new ExternalDepsManager();\n  }\n\n  useEffect(() => {\n    const manager = externalDepsManager.current!;\n    disableGetterTracking(adapterState, rawInstance);\n    manager.updateSubscriptions(\n      adapterState.getterState,\n      rawInstance,\n      forceUpdate,\n    );\n  }, [adapterState, rawInstance, forceUpdate]);\n\n  useEffect(() => {\n    const manager = externalDepsManager.current!;\n    const currentInstanceKey = instanceKey;\n    const currentRawInstance = rawInstance;\n    const currentBloc = bloc;\n\n    // Register as consumer in devtools (if available)\n    const devtools =\n      typeof window !== 'undefined'\n        ? (window as any).__BLAC_DEVTOOLS__\n        : undefined;\n    if (devtools?.registerConsumer && currentRawInstance) {\n      devtools.registerConsumer(\n        (currentRawInstance as any).instanceId,\n        consumerIdRef.current,\n        componentNameRef.current || 'Unknown',\n      );\n    }\n\n    onMountRef.current?.(currentBloc as InstanceType<T>);\n\n    return () => {\n      if (devtools?.unregisterConsumer && currentRawInstance) {\n        devtools.unregisterConsumer(\n          (currentRawInstance as any).instanceId,\n          consumerIdRef.current,\n        );\n      }\n\n      manager.cleanup();\n\n      onUnmountRef.current?.(currentBloc as InstanceType<T>);\n\n      const refId = `useBloc@${componentNameRef.current ?? 'Unknown'}-${consumerIdRef.current}`;\n      release(BlocClass, currentInstanceKey, false, refId);\n    };\n    // oxlint-disable-next-line react-hooks/exhaustive-deps\n  }, [bloc, instanceKey, rawInstance]);\n\n  return [state, bloc, componentRef] as UseBlocReturn<T, ExtractState<T>>;\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/BlocProvider.tsx","../src/useBloc.ts","../src/config.ts"],"sourcesContent":["import {\n  createContext,\n  useContext,\n  type ReactElement,\n  type ReactNode,\n} from 'react';\n\nconst InstanceIdContext = createContext<string | undefined>(undefined);\n\n/**\n * Props for {@link BlocProvider}.\n */\nexport interface BlocProviderProps {\n  /**\n   * Instance id that descendants' `useBloc(C)` calls will resolve to when no\n   * explicit `instanceId` is given.\n   */\n  instanceId: string | number;\n  children: ReactNode;\n}\n\n/**\n * Provides an `instanceId` to descendant `useBloc` calls via React context.\n *\n * Descendants calling `useBloc(C)` without an `instanceId` resolve to the id\n * supplied here. An explicit `instanceId` on the `useBloc` call still wins.\n * `autoInstance` / `static isolated = true` also override the context, because\n * those force a per-mount auto-key.\n *\n * @example\n * ```tsx\n * <BlocProvider instanceId=\"customer-42\">\n *   <CustomerView />\n * </BlocProvider>\n * ```\n */\nexport function BlocProvider({\n  instanceId,\n  children,\n}: BlocProviderProps): ReactElement {\n  return (\n    <InstanceIdContext.Provider value={String(instanceId)}>\n      {children}\n    </InstanceIdContext.Provider>\n  );\n}\n\n/**\n * Reads the nearest {@link BlocProvider} instance id, or `undefined` when\n * called outside a provider.\n */\nexport function useInstanceIdFromContext(): string | undefined {\n  return useContext(InstanceIdContext);\n}\n","import {\n  useEffect,\n  useId,\n  useLayoutEffect,\n  useMemo,\n  useReducer,\n  useRef,\n  type RefObject,\n} from 'react';\nimport {\n  acquire,\n  release,\n  resolveInstanceKey,\n  type ExtractArgs,\n  type ExtractState,\n  type InstanceState,\n  type StateContainer,\n  type StateContainerConstructor,\n} from '@blac/core';\nimport {\n  ALL_PATHS,\n  emptyPathSet,\n  trackRender,\n  type PathSet,\n} from '@dirtytalk/structural';\nimport { useInstanceIdFromContext } from './BlocProvider';\nimport type { ComponentRef, UseBlocOptions, UseBlocReturn } from './types';\n\nlet nextConsumerId = 0;\n\n/**\n * React hook that connects a component to a state container with automatic\n * re-render on state changes.\n *\n * Two tracking modes:\n * - **Auto-tracking** (default): the returned state value is a proxy that\n *   records read paths during render. The component re-renders when any\n *   recorded path changes. Backed by `@dirtytalk/structural`'s\n *   {@link trackRender} + the container's path-scoped `DirtyChannel`.\n * - **Manual select**: pass `options.select` to opt out of auto-tracking.\n *   The hook re-renders only when the returned array's elements change\n *   (per-index `Object.is`). This replaces the v1 `dependencies` option.\n *\n * Lifecycle:\n * - The bloc is acquired from the registry on mount and released on\n *   unmount. The instance key is the explicit `options.instanceId`, then\n *   the surrounding {@link BlocProvider} context, then the default key.\n * - `options.onMount` fires after the bloc is acquired; `options.onUnmount`\n *   fires *before* the registry releases its ref, so the bloc is still\n *   alive when the callback runs.\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\n * @returns Tuple of `[state, bloc, ref]`\n *\n * @example Basic usage\n * ```ts\n * const [state, bloc] = useBloc(MyBloc);\n * ```\n *\n * @example Manual select (replaces v1 `dependencies`)\n * ```ts\n * const [state, bloc] = useBloc(MyBloc, {\n *   select: (state) => [state.count],\n * });\n * ```\n *\n * @example Named instance\n * ```ts\n * const [state, bloc] = useBloc(MyBloc, { instanceId: 'cart-42' });\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\n  // Stable per-consumer id (for the structural container's consumer registry).\n  // Plain counter rather than `useId()` so we don't compete with internal hooks\n  // for SSR id slots.\n  const consumerIdRef = useRef<string | null>(null);\n  if (consumerIdRef.current === null) {\n    consumerIdRef.current = `useBloc-${nextConsumerId++}`;\n  }\n  const consumerId = consumerIdRef.current;\n  // Reserve a useId slot — kept for forwards compatibility and to match\n  // BlocProvider-driven SSR hydration alignment (no-op call).\n  useId();\n\n  // Refs that always carry the latest option callbacks, so the commit effect\n  // can read them without re-keying.\n  const selectRef = useRef(options?.select);\n  selectRef.current = options?.select;\n  const onMountRef = useRef(options?.onMount);\n  onMountRef.current = options?.onMount;\n  const onUnmountRef = useRef(options?.onUnmount);\n  onUnmountRef.current = options?.onUnmount;\n\n  // ---------------------------------------------------------------------------\n  // Identity resolution\n  //\n  // Args are user-supplied; callers commonly pass a fresh object literal each\n  // render. Memoising on `args` directly would bust every render. We compute a\n  // structural key (JSON.stringify) for the useMemo dep instead — undefined\n  // args (void-args blocs) collapse to an undefined key.\n  // ---------------------------------------------------------------------------\n  const args = (options as { args?: ExtractArgs<T> } | undefined)?.args;\n  const argsRef = useRef(args);\n  argsRef.current = args;\n  const argsKey = args === undefined ? undefined : JSON.stringify(args);\n\n  const explicitInstanceId = options?.instanceId;\n  const ctxInstanceId = useInstanceIdFromContext();\n\n  const { bloc, instanceKey } = useMemo<{\n    bloc: TBloc;\n    instanceKey: string;\n  }>(() => {\n    const explicitKey =\n      explicitInstanceId !== undefined\n        ? String(explicitInstanceId)\n        : ctxInstanceId;\n    const resolvedKey = resolveInstanceKey(\n      BlocClass,\n      explicitKey,\n      argsRef.current,\n    );\n    const refId = `useBloc@${consumerId}`;\n    const instance = acquire(\n      BlocClass,\n      resolvedKey,\n      refId,\n      argsRef.current,\n    ) as TBloc;\n    return { bloc: instance, instanceKey: resolvedKey };\n    // oxlint-disable-next-line react-hooks/exhaustive-deps\n  }, [BlocClass, explicitInstanceId, ctxInstanceId, argsKey]);\n\n  // ---------------------------------------------------------------------------\n  // Channel subscription\n  //\n  // We bypass `bloc.subscribe(listener)` (the legacy listener surface, which\n  // StateContainer overrides) and talk directly to `bloc.channel`. The channel\n  // is the StructuralContainer's path-scoped DirtyChannel; subscribing with a\n  // dynamic interest function lets us narrow wakeups per consumer.\n  // ---------------------------------------------------------------------------\n  const [, force] = useReducer((x: number) => x + 1, 0);\n  const pathRef = useRef<PathSet>(emptyPathSet());\n  // For select-mode: cache the last selected array so we can compare against\n  // the next one before forcing a re-render.\n  const lastSelectionRef = useRef<unknown[] | null>(null);\n\n  useEffect(() => {\n    // Subscribe via the channel directly. For auto-track we re-register the\n    // current path interest on each commit (below); for select-mode we use\n    // ALL_PATHS and compare selections in the callback.\n    const channel = (bloc as unknown as StateContainer).channel;\n    const isSelectMode = selectRef.current !== undefined;\n\n    if (isSelectMode) {\n      const unsub = channel.subscribe(\n        () => ALL_PATHS,\n        () => {\n          const select = selectRef.current;\n          if (!select) {\n            force();\n            return;\n          }\n          const next = select(\n            (bloc as unknown as StateContainer).state as ExtractState<T>,\n            bloc as InstanceState<T>,\n          );\n          const prev = lastSelectionRef.current;\n          if (prev !== null && shallowArrayEqual(prev, next)) return;\n          lastSelectionRef.current = next;\n          force();\n        },\n      );\n      return unsub;\n    }\n\n    // Auto-track mode: wake on any change that intersects the recorded paths.\n    // `() => pathRef.current` is called by the channel on every flush, so we\n    // always see the latest interest without re-subscribing.\n    const unsub = channel.subscribe(\n      () => pathRef.current,\n      () => force(),\n    );\n    // Also register the consumer paths with the container for skeleton\n    // recomputation, so the source-side diff can skip us when our paths don't\n    // intersect the change.\n    (bloc as unknown as StateContainer).registerConsumerPaths(\n      consumerId,\n      pathRef.current,\n    );\n    return () => {\n      unsub();\n      (bloc as unknown as StateContainer).unregisterConsumer(consumerId);\n    };\n  }, [bloc, consumerId]);\n\n  // ---------------------------------------------------------------------------\n  // Mount / unmount lifecycle.\n  //\n  // Order on unmount: onUnmount(bloc) -> release(...). The bloc must still be\n  // alive when onUnmount runs (release may dispose it).\n  // ---------------------------------------------------------------------------\n  useEffect(() => {\n    onMountRef.current?.(bloc as InstanceType<T>);\n    return () => {\n      onUnmountRef.current?.(bloc as InstanceType<T>);\n      const refId = `useBloc@${consumerId}`;\n      release(BlocClass, instanceKey, false, refId);\n    };\n    // oxlint-disable-next-line react-hooks/exhaustive-deps\n  }, [bloc, instanceKey]);\n\n  // ---------------------------------------------------------------------------\n  // Snapshot\n  //\n  // - Auto-track: wrap state in trackRender, record paths into pathRef, and\n  //   re-register with the container so the skeleton picks up new interest.\n  // - Select-mode: return state directly; the subscription callback compares\n  //   selections to decide whether to re-render.\n  // ---------------------------------------------------------------------------\n  const rawState = (bloc as unknown as StateContainer).state as ExtractState<T>;\n  let state: ExtractState<T>;\n  if (selectRef.current !== undefined) {\n    state = rawState;\n    // Seed the last selection on the first render so we don't fire an\n    // immediate \"different from null\" wakeup on the first emit.\n    if (lastSelectionRef.current === null) {\n      lastSelectionRef.current = selectRef.current(\n        rawState,\n        bloc as InstanceState<T>,\n      );\n    }\n  } else {\n    const tracked = trackRender(\n      rawState,\n      (bloc as unknown as StateContainer).interner,\n    );\n    state = tracked.value as ExtractState<T>;\n    pathRef.current = tracked.paths;\n    // NOTE: registerConsumerPaths is intentionally NOT called here. The\n    // proxy hasn't been accessed yet, so `tracked.paths` is an empty Set\n    // that the proxy will mutate during JSX evaluation. Registering at\n    // this point would store an empty interest with the container and\n    // freeze the skeleton at that snapshot — subsequent emits would\n    // diff against an empty skeleton and silently drop wakeups. The\n    // useLayoutEffect below registers the populated set after render.\n  }\n\n  // After the render commits the proxy has been touched and pathRef.current\n  // is the consumer's actual interest. Re-register with the container so the\n  // skeleton reflects the latest paths. useLayoutEffect runs before the\n  // browser paints (and before any emit triggered by another effect), so the\n  // skeleton is fresh by the time the next emit fires.\n  // oxlint-disable-next-line react-hooks/exhaustive-deps\n  useLayoutEffect(() => {\n    if (selectRef.current !== undefined) return;\n    (bloc as unknown as StateContainer).registerConsumerPaths(\n      consumerId,\n      pathRef.current,\n    );\n  });\n\n  return [\n    state,\n    bloc,\n    componentRef as RefObject<ComponentRef>,\n  ] as UseBlocReturn<T, ExtractState<T>>;\n}\n\nconst shallowArrayEqual = (a: unknown[], b: unknown[]): boolean => {\n  if (a === b) return true;\n  if (a.length !== b.length) return false;\n  for (let i = 0; i < a.length; i++) {\n    if (!Object.is(a[i], b[i])) return false;\n  }\n  return true;\n};\n","/**\n * Global configuration for `@blac/react`.\n *\n * The hook's tracking model is fixed: when `useBloc` is called without a\n * `select`, render-time auto-tracking is used (via\n * `@dirtytalk/structural`'s `trackRender`). When `select` is provided,\n * re-renders are driven by per-index `Object.is` over the returned array.\n *\n * Reserved for forwards-compatible knobs; currently empty.\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type\nexport interface BlacReactConfig {}\n\nconst defaultConfig: BlacReactConfig = {};\n\nlet globalConfig: BlacReactConfig = { ...defaultConfig };\n\n/**\n * Configure global defaults for `@blac/react` hooks.\n *\n * @param config - Partial configuration to merge with current globals\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"],"mappings":"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"}

package/dist/testing.cjs

@@ -1,5 +1,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-require("./index.cjs");
 let _blac_core = require("@blac/core");
 let _blac_core_testing = require("@blac/core/testing");
 let _testing_library_react = require("@testing-library/react");

package/dist/testing.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"testing.cjs","names":["StateContainerRegistry"],"sources":["../src/testing.ts"],"sourcesContent":["import type { ReactElement } from 'react';\nimport type { RenderResult } from '@testing-library/react';\nimport type { StateContainerConstructor } from '@blac/core';\nimport { StateContainerRegistry, getRegistry, setRegistry } from '@blac/core';\nimport {\n  registerOverride,\n  createCubitStub,\n  type CubitStubOptions,\n} from '@blac/core/testing';\nimport { render } from '@testing-library/react';\n\ninterface RenderWithBlocOptions<\n  T extends StateContainerConstructor,\n> extends CubitStubOptions<T> {\n  bloc: T;\n  instanceKey?: string;\n}\n\nexport function renderWithBloc<T extends StateContainerConstructor>(\n  ui: ReactElement,\n  options: RenderWithBlocOptions<T>,\n): RenderResult & { bloc: InstanceType<T> } {\n  const { bloc: BlocClass, instanceKey, ...stubOptions } = options;\n\n  const previous = getRegistry();\n  const testRegistry = new StateContainerRegistry();\n  setRegistry(testRegistry);\n\n  const instance = createCubitStub(BlocClass, stubOptions);\n  registerOverride(BlocClass, instance, instanceKey);\n\n  let renderResult: RenderResult;\n  try {\n    renderResult = render(ui);\n  } catch (e) {\n    setRegistry(previous);\n    throw e;\n  }\n\n  const originalUnmount = renderResult.unmount;\n  renderResult.unmount = () => {\n    originalUnmount();\n    setRegistry(previous);\n  };\n\n  return {\n    ...renderResult,\n    bloc: instance,\n  };\n}\n\nexport function renderWithRegistry(\n  ui: ReactElement,\n  setup: (registry: StateContainerRegistry) => void,\n): RenderResult {\n  const previous = getRegistry();\n  const testRegistry = new StateContainerRegistry();\n  setRegistry(testRegistry);\n\n  try {\n    setup(testRegistry);\n  } catch (e) {\n    setRegistry(previous);\n    throw e;\n  }\n\n  let renderResult: RenderResult;\n  try {\n    renderResult = render(ui);\n  } catch (e) {\n    setRegistry(previous);\n    throw e;\n  }\n\n  const originalUnmount = renderResult.unmount;\n  renderResult.unmount = () => {\n    originalUnmount();\n    setRegistry(previous);\n  };\n\n  return renderResult;\n}\n"],"mappings":";;;;;;AAkBA,SAAgB,eACd,IACA,SAC0C;CAC1C,MAAM,EAAE,MAAM,WAAW,aAAa,GAAG,gBAAgB;CAEzD,MAAM,YAAA,GAAA,WAAA,cAAwB;AAE9B,EAAA,GAAA,WAAA,aADqB,IAAIA,WAAAA,wBAAwB,CACxB;CAEzB,MAAM,YAAA,GAAA,mBAAA,iBAA2B,WAAW,YAAY;AACxD,EAAA,GAAA,mBAAA,kBAAiB,WAAW,UAAU,YAAY;CAElD,IAAI;AACJ,KAAI;AACF,kBAAA,GAAA,uBAAA,QAAsB,GAAG;UAClB,GAAG;AACV,GAAA,GAAA,WAAA,aAAY,SAAS;AACrB,QAAM;;CAGR,MAAM,kBAAkB,aAAa;AACrC,cAAa,gBAAgB;AAC3B,mBAAiB;AACjB,GAAA,GAAA,WAAA,aAAY,SAAS;;AAGvB,QAAO;EACL,GAAG;EACH,MAAM;EACP;;AAGH,SAAgB,mBACd,IACA,OACc;CACd,MAAM,YAAA,GAAA,WAAA,cAAwB;CAC9B,MAAM,eAAe,IAAIA,WAAAA,wBAAwB;AACjD,EAAA,GAAA,WAAA,aAAY,aAAa;AAEzB,KAAI;AACF,QAAM,aAAa;UACZ,GAAG;AACV,GAAA,GAAA,WAAA,aAAY,SAAS;AACrB,QAAM;;CAGR,IAAI;AACJ,KAAI;AACF,kBAAA,GAAA,uBAAA,QAAsB,GAAG;UAClB,GAAG;AACV,GAAA,GAAA,WAAA,aAAY,SAAS;AACrB,QAAM;;CAGR,MAAM,kBAAkB,aAAa;AACrC,cAAa,gBAAgB;AAC3B,mBAAiB;AACjB,GAAA,GAAA,WAAA,aAAY,SAAS;;AAGvB,QAAO"}
+{"version":3,"file":"testing.cjs","names":["StateContainerRegistry"],"sources":["../src/testing.ts"],"sourcesContent":["import type { ReactElement } from 'react';\nimport type { RenderResult } from '@testing-library/react';\nimport type { StateContainerConstructor } from '@blac/core';\nimport { StateContainerRegistry, getRegistry, setRegistry } from '@blac/core';\nimport {\n  registerOverride,\n  createCubitStub,\n  type CubitStubOptions,\n} from '@blac/core/testing';\nimport { render } from '@testing-library/react';\n\ninterface RenderWithBlocOptions<\n  T extends StateContainerConstructor,\n> extends CubitStubOptions<T> {\n  bloc: T;\n  instanceKey?: string;\n}\n\nexport function renderWithBloc<T extends StateContainerConstructor>(\n  ui: ReactElement,\n  options: RenderWithBlocOptions<T>,\n): RenderResult & { bloc: InstanceType<T> } {\n  const { bloc: BlocClass, instanceKey, ...stubOptions } = options;\n\n  const previous = getRegistry();\n  const testRegistry = new StateContainerRegistry();\n  setRegistry(testRegistry);\n\n  const instance = createCubitStub(BlocClass, stubOptions);\n  registerOverride(BlocClass, instance, instanceKey);\n\n  let renderResult: RenderResult;\n  try {\n    renderResult = render(ui);\n  } catch (e) {\n    setRegistry(previous);\n    throw e;\n  }\n\n  const originalUnmount = renderResult.unmount;\n  renderResult.unmount = () => {\n    originalUnmount();\n    setRegistry(previous);\n  };\n\n  return {\n    ...renderResult,\n    bloc: instance,\n  };\n}\n\nexport function renderWithRegistry(\n  ui: ReactElement,\n  setup: (registry: StateContainerRegistry) => void,\n): RenderResult {\n  const previous = getRegistry();\n  const testRegistry = new StateContainerRegistry();\n  setRegistry(testRegistry);\n\n  try {\n    setup(testRegistry);\n  } catch (e) {\n    setRegistry(previous);\n    throw e;\n  }\n\n  let renderResult: RenderResult;\n  try {\n    renderResult = render(ui);\n  } catch (e) {\n    setRegistry(previous);\n    throw e;\n  }\n\n  const originalUnmount = renderResult.unmount;\n  renderResult.unmount = () => {\n    originalUnmount();\n    setRegistry(previous);\n  };\n\n  return renderResult;\n}\n"],"mappings":";;;;;AAkBA,SAAgB,eACd,IACA,SAC0C;CAC1C,MAAM,EAAE,MAAM,WAAW,aAAa,GAAG,gBAAgB;CAEzD,MAAM,YAAA,GAAA,WAAA,cAAwB;CAE9B,CAAA,GAAA,WAAA,aAAY,IADaA,WAAAA,wBACD,CAAC;CAEzB,MAAM,YAAA,GAAA,mBAAA,iBAA2B,WAAW,YAAY;CACxD,CAAA,GAAA,mBAAA,kBAAiB,WAAW,UAAU,YAAY;CAElD,IAAI;CACJ,IAAI;EACF,gBAAA,GAAA,uBAAA,QAAsB,GAAG;UAClB,GAAG;EACV,CAAA,GAAA,WAAA,aAAY,SAAS;EACrB,MAAM;;CAGR,MAAM,kBAAkB,aAAa;CACrC,aAAa,gBAAgB;EAC3B,iBAAiB;EACjB,CAAA,GAAA,WAAA,aAAY,SAAS;;CAGvB,OAAO;EACL,GAAG;EACH,MAAM;EACP;;AAGH,SAAgB,mBACd,IACA,OACc;CACd,MAAM,YAAA,GAAA,WAAA,cAAwB;CAC9B,MAAM,eAAe,IAAIA,WAAAA,wBAAwB;CACjD,CAAA,GAAA,WAAA,aAAY,aAAa;CAEzB,IAAI;EACF,MAAM,aAAa;UACZ,GAAG;EACV,CAAA,GAAA,WAAA,aAAY,SAAS;EACrB,MAAM;;CAGR,IAAI;CACJ,IAAI;EACF,gBAAA,GAAA,uBAAA,QAAsB,GAAG;UAClB,GAAG;EACV,CAAA,GAAA,WAAA,aAAY,SAAS;EACrB,MAAM;;CAGR,MAAM,kBAAkB,aAAa;CACrC,aAAa,gBAAgB;EAC3B,iBAAiB;EACjB,CAAA,GAAA,WAAA,aAAY,SAAS;;CAGvB,OAAO"}

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","names":[],"sources":["../src/testing.ts"],"sourcesContent":["import type { ReactElement } from 'react';\nimport type { RenderResult } from '@testing-library/react';\nimport type { StateContainerConstructor } from '@blac/core';\nimport { StateContainerRegistry, getRegistry, setRegistry } from '@blac/core';\nimport {\n  registerOverride,\n  createCubitStub,\n  type CubitStubOptions,\n} from '@blac/core/testing';\nimport { render } from '@testing-library/react';\n\ninterface RenderWithBlocOptions<\n  T extends StateContainerConstructor,\n> extends CubitStubOptions<T> {\n  bloc: T;\n  instanceKey?: string;\n}\n\nexport function renderWithBloc<T extends StateContainerConstructor>(\n  ui: ReactElement,\n  options: RenderWithBlocOptions<T>,\n): RenderResult & { bloc: InstanceType<T> } {\n  const { bloc: BlocClass, instanceKey, ...stubOptions } = options;\n\n  const previous = getRegistry();\n  const testRegistry = new StateContainerRegistry();\n  setRegistry(testRegistry);\n\n  const instance = createCubitStub(BlocClass, stubOptions);\n  registerOverride(BlocClass, instance, instanceKey);\n\n  let renderResult: RenderResult;\n  try {\n    renderResult = render(ui);\n  } catch (e) {\n    setRegistry(previous);\n    throw e;\n  }\n\n  const originalUnmount = renderResult.unmount;\n  renderResult.unmount = () => {\n    originalUnmount();\n    setRegistry(previous);\n  };\n\n  return {\n    ...renderResult,\n    bloc: instance,\n  };\n}\n\nexport function renderWithRegistry(\n  ui: ReactElement,\n  setup: (registry: StateContainerRegistry) => void,\n): RenderResult {\n  const previous = getRegistry();\n  const testRegistry = new StateContainerRegistry();\n  setRegistry(testRegistry);\n\n  try {\n    setup(testRegistry);\n  } catch (e) {\n    setRegistry(previous);\n    throw e;\n  }\n\n  let renderResult: RenderResult;\n  try {\n    renderResult = render(ui);\n  } catch (e) {\n    setRegistry(previous);\n    throw e;\n  }\n\n  const originalUnmount = renderResult.unmount;\n  renderResult.unmount = () => {\n    originalUnmount();\n    setRegistry(previous);\n  };\n\n  return renderResult;\n}\n"],"mappings":";;;;AAkBA,SAAgB,eACd,IACA,SAC0C;CAC1C,MAAM,EAAE,MAAM,WAAW,aAAa,GAAG,gBAAgB;CAEzD,MAAM,WAAW,aAAa;AAE9B,aADqB,IAAI,wBAAwB,CACxB;CAEzB,MAAM,WAAW,gBAAgB,WAAW,YAAY;AACxD,kBAAiB,WAAW,UAAU,YAAY;CAElD,IAAI;AACJ,KAAI;AACF,iBAAe,OAAO,GAAG;UAClB,GAAG;AACV,cAAY,SAAS;AACrB,QAAM;;CAGR,MAAM,kBAAkB,aAAa;AACrC,cAAa,gBAAgB;AAC3B,mBAAiB;AACjB,cAAY,SAAS;;AAGvB,QAAO;EACL,GAAG;EACH,MAAM;EACP;;AAGH,SAAgB,mBACd,IACA,OACc;CACd,MAAM,WAAW,aAAa;CAC9B,MAAM,eAAe,IAAI,wBAAwB;AACjD,aAAY,aAAa;AAEzB,KAAI;AACF,QAAM,aAAa;UACZ,GAAG;AACV,cAAY,SAAS;AACrB,QAAM;;CAGR,IAAI;AACJ,KAAI;AACF,iBAAe,OAAO,GAAG;UAClB,GAAG;AACV,cAAY,SAAS;AACrB,QAAM;;CAGR,MAAM,kBAAkB,aAAa;AACrC,cAAa,gBAAgB;AAC3B,mBAAiB;AACjB,cAAY,SAAS;;AAGvB,QAAO"}
+{"version":3,"file":"testing.js","names":[],"sources":["../src/testing.ts"],"sourcesContent":["import type { ReactElement } from 'react';\nimport type { RenderResult } from '@testing-library/react';\nimport type { StateContainerConstructor } from '@blac/core';\nimport { StateContainerRegistry, getRegistry, setRegistry } from '@blac/core';\nimport {\n  registerOverride,\n  createCubitStub,\n  type CubitStubOptions,\n} from '@blac/core/testing';\nimport { render } from '@testing-library/react';\n\ninterface RenderWithBlocOptions<\n  T extends StateContainerConstructor,\n> extends CubitStubOptions<T> {\n  bloc: T;\n  instanceKey?: string;\n}\n\nexport function renderWithBloc<T extends StateContainerConstructor>(\n  ui: ReactElement,\n  options: RenderWithBlocOptions<T>,\n): RenderResult & { bloc: InstanceType<T> } {\n  const { bloc: BlocClass, instanceKey, ...stubOptions } = options;\n\n  const previous = getRegistry();\n  const testRegistry = new StateContainerRegistry();\n  setRegistry(testRegistry);\n\n  const instance = createCubitStub(BlocClass, stubOptions);\n  registerOverride(BlocClass, instance, instanceKey);\n\n  let renderResult: RenderResult;\n  try {\n    renderResult = render(ui);\n  } catch (e) {\n    setRegistry(previous);\n    throw e;\n  }\n\n  const originalUnmount = renderResult.unmount;\n  renderResult.unmount = () => {\n    originalUnmount();\n    setRegistry(previous);\n  };\n\n  return {\n    ...renderResult,\n    bloc: instance,\n  };\n}\n\nexport function renderWithRegistry(\n  ui: ReactElement,\n  setup: (registry: StateContainerRegistry) => void,\n): RenderResult {\n  const previous = getRegistry();\n  const testRegistry = new StateContainerRegistry();\n  setRegistry(testRegistry);\n\n  try {\n    setup(testRegistry);\n  } catch (e) {\n    setRegistry(previous);\n    throw e;\n  }\n\n  let renderResult: RenderResult;\n  try {\n    renderResult = render(ui);\n  } catch (e) {\n    setRegistry(previous);\n    throw e;\n  }\n\n  const originalUnmount = renderResult.unmount;\n  renderResult.unmount = () => {\n    originalUnmount();\n    setRegistry(previous);\n  };\n\n  return renderResult;\n}\n"],"mappings":";;;;AAkBA,SAAgB,eACd,IACA,SAC0C;CAC1C,MAAM,EAAE,MAAM,WAAW,aAAa,GAAG,gBAAgB;CAEzD,MAAM,WAAW,aAAa;CAE9B,YAAY,IADa,wBACD,CAAC;CAEzB,MAAM,WAAW,gBAAgB,WAAW,YAAY;CACxD,iBAAiB,WAAW,UAAU,YAAY;CAElD,IAAI;CACJ,IAAI;EACF,eAAe,OAAO,GAAG;UAClB,GAAG;EACV,YAAY,SAAS;EACrB,MAAM;;CAGR,MAAM,kBAAkB,aAAa;CACrC,aAAa,gBAAgB;EAC3B,iBAAiB;EACjB,YAAY,SAAS;;CAGvB,OAAO;EACL,GAAG;EACH,MAAM;EACP;;AAGH,SAAgB,mBACd,IACA,OACc;CACd,MAAM,WAAW,aAAa;CAC9B,MAAM,eAAe,IAAI,wBAAwB;CACjD,YAAY,aAAa;CAEzB,IAAI;EACF,MAAM,aAAa;UACZ,GAAG;EACV,YAAY,SAAS;EACrB,MAAM;;CAGR,IAAI;CACJ,IAAI;EACF,eAAe,OAAO,GAAG;UAClB,GAAG;EACV,YAAY,SAAS;EACrB,MAAM;;CAGR,MAAM,kBAAkB,aAAa;CACrC,aAAa,gBAAgB;EAC3B,iBAAiB;EACjB,YAAY,SAAS;;CAGvB,OAAO"}

package/dist/types.d.ts

@@ -1,39 +1,63 @@
-import type { ExtractState, StateContainerConstructor } from '@blac/core';
-import { InstanceReadonlyState } from '@blac/core';
+import type { ExtractArgs, ExtractState, InstanceReadonlyState, StateContainerConstructor } from '@blac/core';
 import type { RefObject } from 'react';
 /**
- * Configuration options for useBloc hook
- * @template TBloc - The state container type
+ * Conditional `args` field: required when the bloc declares Args, forbidden
+ * (type `never`) when the bloc uses the default `void` Args.
  */
-export interface UseBlocOptions<TBloc extends StateContainerConstructor> {
-    /** Custom instance identifier */
+type ArgsOption<T extends StateContainerConstructor> = ExtractArgs<T> extends void ? {
+    args?: never;
+} : {
+    args: ExtractArgs<T>;
+};
+/**
+ * Configuration options for {@link useBloc}.
+ *
+ * @template TBloc - The state container constructor type
+ *
+ * @remarks
+ * The `dependencies` option from BlaC v1 has been removed — use `select`
+ * instead. Codemod: rename `dependencies` → `select`; the return value is
+ * still a tuple/array compared per-index via `Object.is`.
+ */
+export type UseBlocOptions<TBloc extends StateContainerConstructor> = ArgsOption<TBloc> & {
+    /**
+     * Per-consumer instance identifier. Overrides any `instanceId` provided
+     * by an ancestor {@link BlocProvider}.
+     */
     instanceId?: string | number;
     /**
-     * When true, this call site gets its own per-mount instance, auto-keyed via
-     * React's `useId()`. Equivalent to declaring `static isolated = true` on the
-     * bloc class. Ignored when an explicit `instanceId` is provided.
+     * Per-consumer re-render selector. When provided, the hook re-renders
+     * only when the returned array's elements change (Object.is per index).
+     * When omitted, auto-tracking is used: any state path read during the
+     * render is observed, and the hook re-renders when any of those paths
+     * change.
+     *
+     * Keep the selector referentially stable across renders (e.g. via
+     * `useCallback`) — passing a fresh function each render forces the
+     * subscription to re-key, which the underlying channel treats as a new
+     * consumer.
      */
-    autoInstance?: boolean;
-    /** 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 */
+    select?: (state: ExtractState<TBloc>, bloc: InstanceReadonlyState<TBloc>) => unknown[];
+    /** Callback invoked when this consumer mounts. */
     onMount?: (bloc: InstanceType<TBloc>) => void;
-    /** Callback invoked when bloc instance unmounts */
+    /**
+     * Callback invoked when this consumer unmounts. Fires *before* the
+     * registry releases its ref, so the bloc is still alive when this runs.
+     */
     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)
+ * Tuple return type from {@link useBloc}.
+ * - [0] Current state value
  * - [1] State container instance (bloc) for calling actions
  * - [2] Ref object for accessing component ref (advanced use cases)
  *
- * @template TBloc - The state container type
+ * @template TBloc - The state container constructor type
  */
 export type UseBlocReturn<TBloc extends StateContainerConstructor, S = ExtractState<TBloc>> = [S, InstanceReadonlyState<TBloc>, RefObject<ComponentRef>];
 /**
- * Internal ref structure for component-bloc binding
+ * Internal ref structure for component-bloc binding.
  * @internal
  */
 export type ComponentRef = Record<string, never>;
+export {};

package/dist/useBloc.d.ts

@@ -1,35 +1,46 @@
-import { type ExtractState, type StateContainerConstructor } from '@blac/adapter';
+import { type ExtractState, type StateContainerConstructor } from '@blac/core';
 import type { UseBlocOptions, UseBlocReturn } from './types';
 /**
- * React hook that connects a component to a state container with automatic re-render on state changes.
+ * 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
+ * Two tracking modes:
+ * - **Auto-tracking** (default): the returned state value is a proxy that
+ *   records read paths during render. The component re-renders when any
+ *   recorded path changes. Backed by `@dirtytalk/structural`'s
+ *   {@link trackRender} + the container's path-scoped `DirtyChannel`.
+ * - **Manual select**: pass `options.select` to opt out of auto-tracking.
+ *   The hook re-renders only when the returned array's elements change
+ *   (per-index `Object.is`). This replaces the v1 `dependencies` option.
+ *
+ * Lifecycle:
+ * - The bloc is acquired from the registry on mount and released on
+ *   unmount. The instance key is the explicit `options.instanceId`, then
+ *   the surrounding {@link BlocProvider} context, then the default key.
+ * - `options.onMount` fires after the bloc is acquired; `options.onUnmount`
+ *   fires *before* the registry releases its ref, so the bloc is still
+ *   alive when the callback runs.
  *
  * @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]
+ * @param options - Configuration options
+ * @returns Tuple of `[state, bloc, ref]`
  *
  * @example Basic usage
  * ```ts
- * const [state, myBloc, ref] = useBloc(MyBloc);
+ * const [state, bloc] = useBloc(MyBloc);
  * ```
  *
- * @example With manual dependencies
+ * @example Manual select (replaces v1 `dependencies`)
  * ```ts
- * const [state, myBloc] = useBloc(MyBloc, {
- *   dependencies: (state) => [state.count]
+ * const [state, bloc] = useBloc(MyBloc, {
+ *   select: (state) => [state.count],
  * });
  * ```
  *
- * @example With named instance
+ * @example Named instance
  * ```ts
- * const [state, myBloc] = useBloc(MyBloc, {
- *   instanceId: 'unique-id'
- * });
+ * const [state, bloc] = useBloc(MyBloc, { instanceId: 'cart-42' });
  * ```
  */
 export declare function useBloc<T extends StateContainerConstructor = StateContainerConstructor>(BlocClass: T, options?: UseBlocOptions<T>): UseBlocReturn<T, ExtractState<T>>;

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

@@ -7,4 +7,6 @@
  * @param providedId - User-provided instance ID (from options)
  * @returns Instance key string or undefined for default
  */
-export declare function generateInstanceKey(providedId?: string | number): string | undefined;
+export declare function generateInstanceKey(
+  providedId?: string | number,
+): string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blac/react",
-  "version": "2.0.13",
+  "version": "2.0.15",
   "license": "MIT",
   "author": "Brendan Mullins <jsnanigans@gmail.com>",
   "description": "React bindings for BlaC — useBloc hook with automatic re-render optimization",
@@ -65,13 +65,13 @@
     "bloc-pattern"
   ],
   "dependencies": {
-    "@blac/adapter": "^2.0.14"
+    "@dirtytalk/structural": "^0.0.3"
   },
   "peerDependencies": {
     "@testing-library/react": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "@types/react": "^18.0.0 || ^19.0.0",
     "react": "^18.0.0 || ^19.0.0",
-    "@blac/core": "^2.0.13"
+    "@blac/core": "^2.0.15"
   },
   "peerDependenciesMeta": {
     "@types/react": {
@@ -102,7 +102,7 @@
     "vite": "npm:@voidzero-dev/vite-plus-core@latest",
     "vitest": "npm:@voidzero-dev/vite-plus-test@latest",
     "vite-plus": "latest",
-    "@blac/core": "2.0.13"
+    "@blac/core": "2.0.15"
   },
   "scripts": {
     "dev": "vp pack --watch",