@blac/react 2.0.14 → 2.0.16

package/README.md

@@ -10,7 +10,7 @@ React bindings for BlaC — `useBloc` hook with proxy-based automatic re-render
 pnpm add @blac/react @blac/core
 ```
 
-Requires React 18+ (`useSyncExternalStore`).
+Requires React 18+.
 
 ## Quick Start
 
@@ -54,11 +54,11 @@ const [state, bloc, ref] = useBloc(MyBloc, options?);
 
 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` |
+| 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
 
@@ -84,40 +84,54 @@ function UserCard({ userId }: { userId: string }) {
 ```
 
 **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:
+- **Per-component private instances** — pass a per-mount `instanceId` (keyed by React's `useId()`) to give each mount its own instance, disposed on unmount:
 
 ```tsx
-const [state, cubit] = useBloc(FormCubit, { args: options, autoInstance: true });
+const instanceId = useId();
+const [state, cubit] = useBloc(FormCubit, { args: options, instanceId });
 ```
 
 ### `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
 
+`deps` is **not** a `useBloc` option. A component contributes its slice from a **mount effect**, using `APPLY_DEPS` / `REMOVE_DEPS_OWNER` from `@blac/core` (marked `@internal` today; a friendlier wrapper may land later):
+
 ```tsx
+import { useEffect, useId, useRef } from 'react';
+import { APPLY_DEPS, REMOVE_DEPS_OWNER } from '@blac/core';
+import { useBloc } from '@blac/react';
+
 const inputRef = useRef<HTMLInputElement>(null);
-const onComplete = useCallback(() => { /* ... */ }, []);
+const ownerId = useId();
+const [state, cubit] = useBloc(FileUploadCubit, { args: { endpoint } });
 
-const [state, cubit] = useBloc(FileUploadCubit, {
-  args: { endpoint },
-  deps: { inputRef, onComplete },
-});
+useEffect(() => {
+  cubit[APPLY_DEPS](ownerId, { inputRef });
+  return () => cubit[REMOVE_DEPS_OWNER](ownerId);
+}, [cubit, inputRef, ownerId]);
 ```
 
 The bloc reads them lazily and guards for absence:
 
 ```ts
-class FileUploadCubit extends Cubit<UploadState, { endpoint: string }, {
-  inputRef?: RefObject<HTMLInputElement>;
-  onComplete?: () => void;
-}> {
+class FileUploadCubit extends Cubit<
+  UploadState,
+  { endpoint: string },
+  {
+    inputRef?: RefObject<HTMLInputElement>;
+    onComplete?: () => void;
+  }
+> {
   async upload() {
     this.deps.inputRef?.current?.click?.();
     // ... perform upload ...
@@ -129,16 +143,17 @@ class FileUploadCubit extends Cubit<UploadState, { endpoint: string }, {
 **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 A owns inputRef
+cubitA[APPLY_DEPS](ownerIdA, { inputRef });
 
-// Component B provides onSubmit
-useBloc(FormCubit, { args: { formId }, deps: { onSubmit } });
+// Component B owns onSubmit
+cubitB[APPLY_DEPS](ownerIdB, { onSubmit });
 
-// cubit.deps === { inputRef, onSubmit } (merged from both)
+// cubit.deps === { inputRef, onSubmit } (merged from both consumers)
 ```
 
 **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.
@@ -168,7 +183,7 @@ function Carousel({ slides }: { slides: Slide[] }) {
 }
 ```
 
-**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).
+**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
 
@@ -187,39 +202,34 @@ const [state] = useBloc(CounterCubit, {
 });
 ```
 
-**No tracking:** Re-renders on every state change.
-
-```tsx
-const [state] = useBloc(MyBloc, { autoTrack: false });
-```
-
 ### Options
 
-| 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`)   |
-| `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                       |
+| Option       | Type                         | Description                                                                      |
+| ------------ | ---------------------------- | -------------------------------------------------------------------------------- |
+| `args`       | `Args` type                  | Required when bloc declares `Args != void`; forbidden when `void`                |
+| `select`     | `(state, bloc) => unknown[]` | Manual dependency selector (renamed from `dependencies`); disables auto-tracking |
+| `instanceId` | `string \| number`           | Explicit identity key; pass `useId()` for a per-mount instance                   |
+| `onMount`    | `(bloc) => void`             | Called when component mounts                                                     |
+| `onUnmount`  | `(bloc) => void`             | Called when component unmounts                                                   |
+
+> Auto-tracking is always on when `select` is omitted — it is **not** a configurable option. `deps` and `autoInstance` are not `useBloc` options either: wire deps from a mount effect (`APPLY_DEPS` / `REMOVE_DEPS_OWNER`), and use `instanceId: useId()` for per-mount instances.
 
 ### Identity and Keying
 
 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
+1. **Explicit `instanceId`** — hard override (pass `useId()` for a per-mount private instance)
+2. **`<BlocProvider>` context id** — inherited from an ancestor provider
+3. **`static key(args)` → structural hash of `args`** — default when the bloc declares `Args` (`static key` wins if defined; otherwise a stable hash of all `args`)
+4. **`'default'`** — singleton fallback
 
 Blocs declare explicit identity via a static class property:
 
 ```ts
-class DocumentCubit extends Cubit<DocState, { docId: string; readonly: boolean }> {
+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
 }
@@ -227,14 +237,15 @@ class DocumentCubit extends Cubit<DocState, { docId: string; readonly: boolean }
 
 ### 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:
+By default, all components using `useBloc(MyBloc)` with the same identity share one instance. Pass a per-mount `instanceId` (via `useId()`) for per-component private instances:
 
 ```tsx
 // 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 });
+const instanceId = useId();
+useBloc(FormCubit, { args: options, instanceId });
 
 // Explicit id (escape hatch for non-derivable identity)
 useBloc(EditorCubit, { instanceId: 'editor-1' });
@@ -242,7 +253,8 @@ useBloc(EditorCubit, { instanceId: 'editor-1' });
 
 ### Breaking Changes (v2)
 
-- **`dependencies` option renamed to `select`** — avoids confusion with the new `deps` (non-serializable handles) lane.
+- **`dependencies` option renamed to `select`** — avoids confusion with the `deps` (non-serializable handles) lane.
+- **`autoTrack`, `autoInstance`, and `deps` are no longer `useBloc` options** — auto-tracking is always on (opt out per-consumer with `select`); per-mount instances use `instanceId: useId()`; deps are wired from a mount effect via `APPLY_DEPS` / `REMOVE_DEPS_OWNER`.
 - **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.
 
@@ -251,7 +263,8 @@ useBloc(EditorCubit, { instanceId: 'editor-1' });
 ```tsx
 import { configureBlacReact } from '@blac/react';
 
-configureBlacReact({ autoTrack: true });
+// Configuration is currently empty; the tracking model is fixed and not configurable.
+configureBlacReact({});
 ```
 
 ## Testing

package/dist/BlocProvider.d.ts

@@ -1,33 +1,51 @@
 import { type ReactElement, type ReactNode } from 'react';
+import type { ExtractArgs, StateContainerConstructor } from '@blac/core';
 /**
  * Props for {@link BlocProvider}.
  */
-export interface BlocProviderProps {
+export interface BlocProviderProps<T extends StateContainerConstructor> {
     /**
-     * Instance id that descendants' `useBloc(C)` calls will resolve to when no
-     * explicit `instanceId` is given.
+     * The bloc class whose args are being provided to descendants.
      */
-    instanceId: string | number;
+    bloc: T;
+    /**
+     * Args that descendant `useBloc(bloc)` calls will resolve to when no
+     * own `args` are given.
+     */
+    args: ExtractArgs<T>;
     children: ReactNode;
 }
 /**
- * Provides an `instanceId` to descendant `useBloc` calls via React context.
+ * Provides args to descendant `useBloc` calls for a specific bloc class via
+ * React context.
  *
- * Descendants calling `useBloc(C)` without an `instanceId` resolve to the id
- * supplied here. An explicit `instanceId` on the `useBloc` call still wins.
- * `autoInstance` / `static isolated = true` also override the context, because
- * those force a per-mount auto-key.
+ * Descendants calling `useBloc(Bloc)` without their own `args` resolve to the
+ * args supplied here. Own `args` on the `useBloc` call always win.
+ *
+ * Multiple `BlocProvider` wrappers for different bloc classes compose: each
+ * provider merges its entry into the inherited map, so nested providers for
+ * different blocs do not interfere.
  *
  * @example
  * ```tsx
- * <BlocProvider instanceId="customer-42">
- *   <CustomerView />
+ * <BlocProvider bloc={UserBloc} args={{ userId: 'alice' }}>
+ *   <UserProfile />
+ * </BlocProvider>
+ * ```
+ *
+ * @example Per-mount private instance
+ * ```tsx
+ * const id = useId();
+ * <BlocProvider bloc={CartBloc} args={{ _id: id }}>
+ *   <CartWidget />
  * </BlocProvider>
  * ```
  */
-export declare function BlocProvider({ instanceId, children, }: BlocProviderProps): ReactElement;
+export declare function BlocProvider<T extends StateContainerConstructor>({ bloc, args, children, }: BlocProviderProps<T>): ReactElement;
 /**
- * Reads the nearest {@link BlocProvider} instance id, or `undefined` when
- * called outside a provider.
+ * Returns the args provided by the nearest {@link BlocProvider} for the given
+ * bloc class, or `undefined` when called outside a matching provider.
+ *
+ * Used by `useBloc` to inherit provider args when no own `args` are given.
  */
-export declare function useInstanceIdFromContext(): string | undefined;
+export declare function useProvidedArgs<T extends StateContainerConstructor>(BlocClass: T): ExtractArgs<T> | undefined;

package/dist/index.cjs

@@ -4,34 +4,57 @@ 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);
+const ProvidedArgsContext = (0, react.createContext)(/* @__PURE__ */ new Map());
 /**
-* Provides an `instanceId` to descendant `useBloc` calls via React context.
+* Provides args to descendant `useBloc` calls for a specific bloc class via
+* React context.
 *
-* Descendants calling `useBloc(C)` without an `instanceId` resolve to the id
-* supplied here. An explicit `instanceId` on the `useBloc` call still wins.
-* `autoInstance` / `static isolated = true` also override the context, because
-* those force a per-mount auto-key.
+* Descendants calling `useBloc(Bloc)` without their own `args` resolve to the
+* args supplied here. Own `args` on the `useBloc` call always win.
+*
+* Multiple `BlocProvider` wrappers for different bloc classes compose: each
+* provider merges its entry into the inherited map, so nested providers for
+* different blocs do not interfere.
 *
 * @example
 * ```tsx
-* <BlocProvider instanceId="customer-42">
-*   <CustomerView />
+* <BlocProvider bloc={UserBloc} args={{ userId: 'alice' }}>
+*   <UserProfile />
+* </BlocProvider>
+* ```
+*
+* @example Per-mount private instance
+* ```tsx
+* const id = useId();
+* <BlocProvider bloc={CartBloc} args={{ _id: id }}>
+*   <CartWidget />
 * </BlocProvider>
 * ```
 */
-function BlocProvider({ instanceId, children }) {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(InstanceIdContext.Provider, {
-		value: String(instanceId),
+function BlocProvider({ bloc, args, children }) {
+	const parentMap = (0, react.useContext)(ProvidedArgsContext);
+	const mergedMap = (0, react.useMemo)(() => {
+		const next = new Map(parentMap);
+		next.set(bloc, args);
+		return next;
+	}, [
+		parentMap,
+		bloc,
+		args
+	]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ProvidedArgsContext.Provider, {
+		value: mergedMap,
 		children
 	});
 }
 /**
-* Reads the nearest {@link BlocProvider} instance id, or `undefined` when
-* called outside a provider.
+* Returns the args provided by the nearest {@link BlocProvider} for the given
+* bloc class, or `undefined` when called outside a matching provider.
+*
+* Used by `useBloc` to inherit provider args when no own `args` are given.
 */
-function useInstanceIdFromContext() {
-	return (0, react.useContext)(InstanceIdContext);
+function useProvidedArgs(BlocClass) {
+	return (0, react.useContext)(ProvidedArgsContext).get(BlocClass);
 }
 //#endregion
 //#region src/useBloc.ts
@@ -51,12 +74,19 @@ let nextConsumerId = 0;
 *
 * 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.
+*   unmount. The instance key is derived from `options.args` (own args),
+*   then the surrounding {@link BlocProvider} context args for this bloc,
+*   then the default key (no args).
 * - `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.
 *
+* Per-mount private instance:
+* ```ts
+* const id = useId();
+* const [state, bloc] = useBloc(MyBloc, { args: { _id: id } });
+* ```
+*
 * @template T - The state container constructor type (inferred from BlocClass)
 * @param BlocClass - The state container class to connect to
 * @param options - Configuration options
@@ -74,9 +104,9 @@ let nextConsumerId = 0;
 * });
 * ```
 *
-* @example Named instance
+* @example Args-based shared instance
 * ```ts
-* const [state, bloc] = useBloc(MyBloc, { instanceId: 'cart-42' });
+* const [state, bloc] = useBloc(UserBloc, { args: { userId: 'alice' } });
 * ```
 */
 function useBloc(BlocClass, options) {
@@ -91,26 +121,34 @@ function useBloc(BlocClass, options) {
 	onMountRef.current = options?.onMount;
 	const onUnmountRef = (0, react.useRef)(options?.onUnmount);
 	onUnmountRef.current = options?.onUnmount;
-	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 ownArgs = options?.args;
+	const ownArgsRef = (0, react.useRef)(ownArgs);
+	ownArgsRef.current = ownArgs;
+	const ownArgsKey = ownArgs === void 0 ? void 0 : JSON.stringify(ownArgs);
+	const providerArgs = useProvidedArgs(BlocClass);
+	const providerArgsRef = (0, react.useRef)(providerArgs);
+	providerArgsRef.current = providerArgs;
 	const { bloc, instanceKey } = (0, react.useMemo)(() => {
-		const resolvedKey = (0, _blac_core.resolveInstanceKey)(BlocClass, explicitInstanceId !== void 0 ? String(explicitInstanceId) : ctxInstanceId, argsRef.current);
+		const effectiveArgs = ownArgsRef.current !== void 0 ? ownArgsRef.current : providerArgsRef.current;
+		const resolvedKey = (0, _blac_core.resolveInstanceKey)(BlocClass, effectiveArgs);
+		const refId = `useBloc@${consumerId}`;
 		return {
-			bloc: (0, _blac_core.acquire)(BlocClass, resolvedKey, `useBloc@${consumerId}`, argsRef.current),
+			bloc: (0, _blac_core.getRegistry)().acquire(BlocClass, resolvedKey, {
+				canCreate: true,
+				countRef: true,
+				refId,
+				args: effectiveArgs
+			}),
 			instanceKey: resolvedKey
 		};
 	}, [
 		BlocClass,
-		explicitInstanceId,
-		ctxInstanceId,
-		argsKey
+		ownArgsKey,
+		providerArgs === void 0 ? void 0 : JSON.stringify(providerArgs)
 	]);
 	const [, force] = (0, react.useReducer)((x) => x + 1, 0);
 	const pathRef = (0, react.useRef)((0, _dirtytalk_structural.emptyPathSet)());
+	const expandedInterestRef = (0, react.useRef)((0, _dirtytalk_structural.emptyPathSet)());
 	const lastSelectionRef = (0, react.useRef)(null);
 	(0, react.useEffect)(() => {
 		const channel = bloc.channel;
@@ -126,7 +164,7 @@ function useBloc(BlocClass, options) {
 			lastSelectionRef.current = next;
 			force();
 		});
-		const unsub = channel.subscribe(() => pathRef.current, () => force());
+		const unsub = channel.subscribe(() => expandedInterestRef.current, () => force());
 		bloc.registerConsumerPaths(consumerId, pathRef.current);
 		return () => {
 			unsub();
@@ -137,7 +175,8 @@ function useBloc(BlocClass, options) {
 		onMountRef.current?.(bloc);
 		return () => {
 			onUnmountRef.current?.(bloc);
-			(0, _blac_core.release)(BlocClass, instanceKey, false, `useBloc@${consumerId}`);
+			const refId = `useBloc@${consumerId}`;
+			(0, _blac_core.getRegistry)().release(BlocClass, instanceKey, false, refId);
 		};
 	}, [bloc, instanceKey]);
 	const rawState = bloc.state;
@@ -152,7 +191,10 @@ function useBloc(BlocClass, options) {
 	}
 	(0, react.useLayoutEffect)(() => {
 		if (selectRef.current !== void 0) return;
-		bloc.registerConsumerPaths(consumerId, pathRef.current);
+		const container = bloc;
+		const paths = pathRef.current;
+		container.registerConsumerPaths(consumerId, paths);
+		expandedInterestRef.current = expandWithAncestors(paths, container.interner);
 	});
 	return [
 		state,
@@ -166,6 +208,37 @@ const shallowArrayEqual = (a, b) => {
 	for (let i = 0; i < a.length; i++) if (!Object.is(a[i], b[i])) return false;
 	return true;
 };
+/**
+* Expand a PathSet to include all ancestor paths of every tracked path.
+*
+* The auto-tracker records leaf paths (e.g. `'items.length'`), but
+* `StructuralContainer.patch` marks parent paths (e.g. `'items'`) since it
+* only walks the patch shape — not individual array elements or nested
+* descendants. Without ancestor expansion, a channel subscriber with interest
+* `{'items.length'}` would miss a `patch`-triggered `dirty={'items'}` because
+* `intersects({'items.length'}, {'items'}) = false`.
+*
+* Example: for leaf path `'a.b.c'`, adds `'a.b'` and `'a'` (but NOT `''`
+* root, since a root change would be captured by ALL_PATHS from the source
+* when there are ≤1 consumers, and adding `''` would make every field change
+* wake this consumer regardless of what it actually reads).
+*/
+function expandWithAncestors(paths, interner) {
+	if (paths === _dirtytalk_structural.ALL_PATHS) return _dirtytalk_structural.ALL_PATHS;
+	const leafPaths = paths;
+	if (leafPaths.size === 0) return paths;
+	const expanded = new Set(leafPaths);
+	for (const id of leafPaths) {
+		const str = interner.lookup(id);
+		let idx = str.lastIndexOf(".");
+		while (idx > 0) {
+			const ancestor = str.slice(0, idx);
+			expanded.add(interner.intern(ancestor));
+			idx = ancestor.lastIndexOf(".");
+		}
+	}
+	return expanded;
+}
 let globalConfig = {};
 /**
 * Configure global defaults for `@blac/react` hooks.
@@ -182,6 +255,6 @@ function configureBlacReact(config) {
 exports.BlocProvider = BlocProvider;
 exports.configureBlacReact = configureBlacReact;
 exports.useBloc = useBloc;
-exports.useInstanceIdFromContext = useInstanceIdFromContext;
+exports.useProvidedArgs = useProvidedArgs;
 
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"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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"}
+{"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  useMemo,\n  type ReactElement,\n  type ReactNode,\n} from 'react';\nimport type { ExtractArgs, StateContainerConstructor } from '@blac/core';\n\n/**\n * Internal context value: a Map from bloc constructor to the args object\n * provided by the nearest BlocProvider for that bloc class.\n *\n * Stored as a WeakMap-keyed record so nested providers for different blocs\n * compose without clobbering each other.\n */\ntype ProvidedArgsMap = Map<StateContainerConstructor, unknown>;\n\nconst ProvidedArgsContext = createContext<ProvidedArgsMap>(new Map());\n\n/**\n * Props for {@link BlocProvider}.\n */\nexport interface BlocProviderProps<T extends StateContainerConstructor> {\n  /**\n   * The bloc class whose args are being provided to descendants.\n   */\n  bloc: T;\n  /**\n   * Args that descendant `useBloc(bloc)` calls will resolve to when no\n   * own `args` are given.\n   */\n  args: ExtractArgs<T>;\n  children: ReactNode;\n}\n\n/**\n * Provides args to descendant `useBloc` calls for a specific bloc class via\n * React context.\n *\n * Descendants calling `useBloc(Bloc)` without their own `args` resolve to the\n * args supplied here. Own `args` on the `useBloc` call always win.\n *\n * Multiple `BlocProvider` wrappers for different bloc classes compose: each\n * provider merges its entry into the inherited map, so nested providers for\n * different blocs do not interfere.\n *\n * @example\n * ```tsx\n * <BlocProvider bloc={UserBloc} args={{ userId: 'alice' }}>\n *   <UserProfile />\n * </BlocProvider>\n * ```\n *\n * @example Per-mount private instance\n * ```tsx\n * const id = useId();\n * <BlocProvider bloc={CartBloc} args={{ _id: id }}>\n *   <CartWidget />\n * </BlocProvider>\n * ```\n */\nexport function BlocProvider<T extends StateContainerConstructor>({\n  bloc,\n  args,\n  children,\n}: BlocProviderProps<T>): ReactElement {\n  const parentMap = useContext(ProvidedArgsContext);\n\n  // Merge our entry into a new Map so sibling/parent providers for other blocs\n  // are preserved. Memoised on (parentMap, bloc, args) identity.\n  const mergedMap = useMemo(() => {\n    const next = new Map(parentMap);\n    next.set(bloc, args);\n    return next;\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [parentMap, bloc, args]);\n\n  return (\n    <ProvidedArgsContext.Provider value={mergedMap}>\n      {children}\n    </ProvidedArgsContext.Provider>\n  );\n}\n\n/**\n * Returns the args provided by the nearest {@link BlocProvider} for the given\n * bloc class, or `undefined` when called outside a matching provider.\n *\n * Used by `useBloc` to inherit provider args when no own `args` are given.\n */\nexport function useProvidedArgs<T extends StateContainerConstructor>(\n  BlocClass: T,\n): ExtractArgs<T> | undefined {\n  const map = useContext(ProvidedArgsContext);\n  return map.get(BlocClass) as ExtractArgs<T> | undefined;\n}\n","import {\n  useEffect,\n  useId,\n  useLayoutEffect,\n  useMemo,\n  useReducer,\n  useRef,\n  type RefObject,\n} from 'react';\nimport {\n  getRegistry,\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  PathInterner,\n  type PathSet,\n} from '@dirtytalk/structural';\nimport { useProvidedArgs } 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 derived from `options.args` (own args),\n *   then the surrounding {@link BlocProvider} context args for this bloc,\n *   then the default key (no args).\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 * Per-mount private instance:\n * ```ts\n * const id = useId();\n * const [state, bloc] = useBloc(MyBloc, { args: { _id: id } });\n * ```\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 Args-based shared instance\n * ```ts\n * const [state, bloc] = useBloc(UserBloc, { args: { userId: 'alice' } });\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  // Priority: own args > provider args (for this bloc class) > none.\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 ownArgs = (options as { args?: ExtractArgs<T> } | undefined)?.args;\n  const ownArgsRef = useRef(ownArgs);\n  ownArgsRef.current = ownArgs;\n  const ownArgsKey =\n    ownArgs === undefined ? undefined : JSON.stringify(ownArgs);\n\n  // Read provided args from the nearest BlocProvider for this bloc class.\n  const providerArgs = useProvidedArgs(BlocClass);\n  const providerArgsRef = useRef(providerArgs);\n  providerArgsRef.current = providerArgs;\n  const providerArgsKey =\n    providerArgs === undefined ? undefined : JSON.stringify(providerArgs);\n\n  const { bloc, instanceKey } = useMemo<{\n    bloc: TBloc;\n    instanceKey: string;\n  }>(() => {\n    // Own args win over provider args; provider args win over no args.\n    const effectiveArgs =\n      ownArgsRef.current !== undefined\n        ? ownArgsRef.current\n        : providerArgsRef.current;\n\n    const resolvedKey = resolveInstanceKey(BlocClass, effectiveArgs);\n    const refId = `useBloc@${consumerId}`;\n    const registry = getRegistry();\n    const instance = registry.acquire(BlocClass, resolvedKey, {\n      canCreate: true,\n      countRef: true,\n      refId,\n      args: effectiveArgs,\n    }) as TBloc;\n    return { bloc: instance, instanceKey: resolvedKey };\n    // oxlint-disable-next-line react-hooks/exhaustive-deps\n  }, [BlocClass, ownArgsKey, providerArgsKey]);\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  // Expanded interest: leaf paths PLUS their ancestor paths, so that when\n  // `patch` marks a parent (e.g. 'items') and the consumer tracked a child\n  // (e.g. 'items.length'), the intersection still fires. Updated in\n  // useLayoutEffect after each render once pathRef.current is populated.\n  const expandedInterestRef = 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: subscribe with the expanded interest (leaf paths + their\n    // ancestors). This ensures that when `patch` marks a parent path (e.g.\n    // 'items') and the consumer tracked a child (e.g. 'items.length'), the\n    // channel intersection still fires a re-render.\n    //\n    // `expandedInterestRef.current` is updated by the useLayoutEffect below\n    // after each render, so the interest is always fresh at flush time.\n    const unsub = channel.subscribe(\n      () => expandedInterestRef.current,\n      () => force(),\n    );\n    // Register the consumer's leaf 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      getRegistry().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, pathRef.current is the consumer's actual leaf\n  // interest (populated by the proxy during JSX evaluation). Re-register with\n  // the container so the skeleton reflects the latest paths, and expand the\n  // interest to include ancestor paths for the channel subscription.\n  //\n  // useLayoutEffect runs before the browser paints (and before any emit\n  // triggered by another effect), so the skeleton is fresh by the time the\n  // next emit fires.\n  // oxlint-disable-next-line react-hooks/exhaustive-deps\n  useLayoutEffect(() => {\n    if (selectRef.current !== undefined) return;\n    const container = bloc as unknown as StateContainer;\n    const paths = pathRef.current;\n    container.registerConsumerPaths(consumerId, paths);\n    // Expand interest to include ancestor paths so that `patch`-marked parent\n    // paths (e.g. 'items') wake a consumer that tracked a child (e.g.\n    // 'items.length').\n    expandedInterestRef.current = expandWithAncestors(\n      paths,\n      container.interner,\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/**\n * Expand a PathSet to include all ancestor paths of every tracked path.\n *\n * The auto-tracker records leaf paths (e.g. `'items.length'`), but\n * `StructuralContainer.patch` marks parent paths (e.g. `'items'`) since it\n * only walks the patch shape — not individual array elements or nested\n * descendants. Without ancestor expansion, a channel subscriber with interest\n * `{'items.length'}` would miss a `patch`-triggered `dirty={'items'}` because\n * `intersects({'items.length'}, {'items'}) = false`.\n *\n * Example: for leaf path `'a.b.c'`, adds `'a.b'` and `'a'` (but NOT `''`\n * root, since a root change would be captured by ALL_PATHS from the source\n * when there are ≤1 consumers, and adding `''` would make every field change\n * wake this consumer regardless of what it actually reads).\n */\nfunction expandWithAncestors(paths: PathSet, interner: PathInterner): PathSet {\n  if (paths === ALL_PATHS) return ALL_PATHS;\n  const leafPaths = paths as Set<number>;\n  if (leafPaths.size === 0) return paths;\n\n  const expanded = new Set<number>(leafPaths);\n  for (const id of leafPaths) {\n    const str = interner.lookup(id);\n    // Add all non-root ancestor segments: 'a.b.c' → add 'a.b', 'a'\n    let idx = str.lastIndexOf('.');\n    while (idx > 0) {\n      const ancestor = str.slice(0, idx);\n      expanded.add(interner.intern(ancestor));\n      idx = ancestor.lastIndexOf('.');\n    }\n  }\n  return expanded;\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.d.cts

@@ -3,10 +3,10 @@
  *
  * Clean integration between React and StateContainer architecture.
  * Constructor-based API with automatic type inference.
- * Supports concurrent (useSyncExternalStore) mode for optimal performance.
+ * Re-renders are driven by per-consumer, path-scoped channel subscriptions.
  */
 export { useBloc } from './useBloc';
 export { configureBlacReact } from './config';
 export type { BlacReactConfig } from './config';
 export type { UseBlocOptions, UseBlocReturn } from './types';
-export { BlocProvider, useInstanceIdFromContext, type BlocProviderProps, } from './BlocProvider';
+export { BlocProvider, useProvidedArgs, type BlocProviderProps, } from './BlocProvider';

package/dist/index.d.ts

@@ -3,10 +3,10 @@
  *
  * Clean integration between React and StateContainer architecture.
  * Constructor-based API with automatic type inference.
- * Supports concurrent (useSyncExternalStore) mode for optimal performance.
+ * Re-renders are driven by per-consumer, path-scoped channel subscriptions.
  */
 export { useBloc } from './useBloc';
 export { configureBlacReact } from './config';
 export type { BlacReactConfig } from './config';
 export type { UseBlocOptions, UseBlocReturn } from './types';
-export { BlocProvider, useInstanceIdFromContext, type BlocProviderProps, } from './BlocProvider';
+export { BlocProvider, useProvidedArgs, type BlocProviderProps, } from './BlocProvider';

package/dist/index.js

@@ -1,36 +1,59 @@
 import { createContext, useContext, useEffect, useId, useLayoutEffect, useMemo, useReducer, useRef } from "react";
-import { acquire, release, resolveInstanceKey } from "@blac/core";
+import { getRegistry, 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);
+const ProvidedArgsContext = createContext(/* @__PURE__ */ new Map());
 /**
-* Provides an `instanceId` to descendant `useBloc` calls via React context.
+* Provides args to descendant `useBloc` calls for a specific bloc class via
+* React context.
 *
-* Descendants calling `useBloc(C)` without an `instanceId` resolve to the id
-* supplied here. An explicit `instanceId` on the `useBloc` call still wins.
-* `autoInstance` / `static isolated = true` also override the context, because
-* those force a per-mount auto-key.
+* Descendants calling `useBloc(Bloc)` without their own `args` resolve to the
+* args supplied here. Own `args` on the `useBloc` call always win.
+*
+* Multiple `BlocProvider` wrappers for different bloc classes compose: each
+* provider merges its entry into the inherited map, so nested providers for
+* different blocs do not interfere.
 *
 * @example
 * ```tsx
-* <BlocProvider instanceId="customer-42">
-*   <CustomerView />
+* <BlocProvider bloc={UserBloc} args={{ userId: 'alice' }}>
+*   <UserProfile />
+* </BlocProvider>
+* ```
+*
+* @example Per-mount private instance
+* ```tsx
+* const id = useId();
+* <BlocProvider bloc={CartBloc} args={{ _id: id }}>
+*   <CartWidget />
 * </BlocProvider>
 * ```
 */
-function BlocProvider({ instanceId, children }) {
-	return /* @__PURE__ */ jsx(InstanceIdContext.Provider, {
-		value: String(instanceId),
+function BlocProvider({ bloc, args, children }) {
+	const parentMap = useContext(ProvidedArgsContext);
+	const mergedMap = useMemo(() => {
+		const next = new Map(parentMap);
+		next.set(bloc, args);
+		return next;
+	}, [
+		parentMap,
+		bloc,
+		args
+	]);
+	return /* @__PURE__ */ jsx(ProvidedArgsContext.Provider, {
+		value: mergedMap,
 		children
 	});
 }
 /**
-* Reads the nearest {@link BlocProvider} instance id, or `undefined` when
-* called outside a provider.
+* Returns the args provided by the nearest {@link BlocProvider} for the given
+* bloc class, or `undefined` when called outside a matching provider.
+*
+* Used by `useBloc` to inherit provider args when no own `args` are given.
 */
-function useInstanceIdFromContext() {
-	return useContext(InstanceIdContext);
+function useProvidedArgs(BlocClass) {
+	return useContext(ProvidedArgsContext).get(BlocClass);
 }
 //#endregion
 //#region src/useBloc.ts
@@ -50,12 +73,19 @@ let nextConsumerId = 0;
 *
 * 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.
+*   unmount. The instance key is derived from `options.args` (own args),
+*   then the surrounding {@link BlocProvider} context args for this bloc,
+*   then the default key (no args).
 * - `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.
 *
+* Per-mount private instance:
+* ```ts
+* const id = useId();
+* const [state, bloc] = useBloc(MyBloc, { args: { _id: id } });
+* ```
+*
 * @template T - The state container constructor type (inferred from BlocClass)
 * @param BlocClass - The state container class to connect to
 * @param options - Configuration options
@@ -73,9 +103,9 @@ let nextConsumerId = 0;
 * });
 * ```
 *
-* @example Named instance
+* @example Args-based shared instance
 * ```ts
-* const [state, bloc] = useBloc(MyBloc, { instanceId: 'cart-42' });
+* const [state, bloc] = useBloc(UserBloc, { args: { userId: 'alice' } });
 * ```
 */
 function useBloc(BlocClass, options) {
@@ -90,26 +120,34 @@ function useBloc(BlocClass, options) {
 	onMountRef.current = options?.onMount;
 	const onUnmountRef = useRef(options?.onUnmount);
 	onUnmountRef.current = options?.onUnmount;
-	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 ownArgs = options?.args;
+	const ownArgsRef = useRef(ownArgs);
+	ownArgsRef.current = ownArgs;
+	const ownArgsKey = ownArgs === void 0 ? void 0 : JSON.stringify(ownArgs);
+	const providerArgs = useProvidedArgs(BlocClass);
+	const providerArgsRef = useRef(providerArgs);
+	providerArgsRef.current = providerArgs;
 	const { bloc, instanceKey } = useMemo(() => {
-		const resolvedKey = resolveInstanceKey(BlocClass, explicitInstanceId !== void 0 ? String(explicitInstanceId) : ctxInstanceId, argsRef.current);
+		const effectiveArgs = ownArgsRef.current !== void 0 ? ownArgsRef.current : providerArgsRef.current;
+		const resolvedKey = resolveInstanceKey(BlocClass, effectiveArgs);
+		const refId = `useBloc@${consumerId}`;
 		return {
-			bloc: acquire(BlocClass, resolvedKey, `useBloc@${consumerId}`, argsRef.current),
+			bloc: getRegistry().acquire(BlocClass, resolvedKey, {
+				canCreate: true,
+				countRef: true,
+				refId,
+				args: effectiveArgs
+			}),
 			instanceKey: resolvedKey
 		};
 	}, [
 		BlocClass,
-		explicitInstanceId,
-		ctxInstanceId,
-		argsKey
+		ownArgsKey,
+		providerArgs === void 0 ? void 0 : JSON.stringify(providerArgs)
 	]);
 	const [, force] = useReducer((x) => x + 1, 0);
 	const pathRef = useRef(emptyPathSet());
+	const expandedInterestRef = useRef(emptyPathSet());
 	const lastSelectionRef = useRef(null);
 	useEffect(() => {
 		const channel = bloc.channel;
@@ -125,7 +163,7 @@ function useBloc(BlocClass, options) {
 			lastSelectionRef.current = next;
 			force();
 		});
-		const unsub = channel.subscribe(() => pathRef.current, () => force());
+		const unsub = channel.subscribe(() => expandedInterestRef.current, () => force());
 		bloc.registerConsumerPaths(consumerId, pathRef.current);
 		return () => {
 			unsub();
@@ -136,7 +174,8 @@ function useBloc(BlocClass, options) {
 		onMountRef.current?.(bloc);
 		return () => {
 			onUnmountRef.current?.(bloc);
-			release(BlocClass, instanceKey, false, `useBloc@${consumerId}`);
+			const refId = `useBloc@${consumerId}`;
+			getRegistry().release(BlocClass, instanceKey, false, refId);
 		};
 	}, [bloc, instanceKey]);
 	const rawState = bloc.state;
@@ -151,7 +190,10 @@ function useBloc(BlocClass, options) {
 	}
 	useLayoutEffect(() => {
 		if (selectRef.current !== void 0) return;
-		bloc.registerConsumerPaths(consumerId, pathRef.current);
+		const container = bloc;
+		const paths = pathRef.current;
+		container.registerConsumerPaths(consumerId, paths);
+		expandedInterestRef.current = expandWithAncestors(paths, container.interner);
 	});
 	return [
 		state,
@@ -165,6 +207,37 @@ const shallowArrayEqual = (a, b) => {
 	for (let i = 0; i < a.length; i++) if (!Object.is(a[i], b[i])) return false;
 	return true;
 };
+/**
+* Expand a PathSet to include all ancestor paths of every tracked path.
+*
+* The auto-tracker records leaf paths (e.g. `'items.length'`), but
+* `StructuralContainer.patch` marks parent paths (e.g. `'items'`) since it
+* only walks the patch shape — not individual array elements or nested
+* descendants. Without ancestor expansion, a channel subscriber with interest
+* `{'items.length'}` would miss a `patch`-triggered `dirty={'items'}` because
+* `intersects({'items.length'}, {'items'}) = false`.
+*
+* Example: for leaf path `'a.b.c'`, adds `'a.b'` and `'a'` (but NOT `''`
+* root, since a root change would be captured by ALL_PATHS from the source
+* when there are ≤1 consumers, and adding `''` would make every field change
+* wake this consumer regardless of what it actually reads).
+*/
+function expandWithAncestors(paths, interner) {
+	if (paths === ALL_PATHS) return ALL_PATHS;
+	const leafPaths = paths;
+	if (leafPaths.size === 0) return paths;
+	const expanded = new Set(leafPaths);
+	for (const id of leafPaths) {
+		const str = interner.lookup(id);
+		let idx = str.lastIndexOf(".");
+		while (idx > 0) {
+			const ancestor = str.slice(0, idx);
+			expanded.add(interner.intern(ancestor));
+			idx = ancestor.lastIndexOf(".");
+		}
+	}
+	return expanded;
+}
 let globalConfig = {};
 /**
 * Configure global defaults for `@blac/react` hooks.
@@ -178,6 +251,6 @@ function configureBlacReact(config) {
 	};
 }
 //#endregion
-export { BlocProvider, configureBlacReact, useBloc, useInstanceIdFromContext };
+export { BlocProvider, configureBlacReact, useBloc, useProvidedArgs };
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"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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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/BlocProvider.tsx","../src/useBloc.ts","../src/config.ts"],"sourcesContent":["import {\n  createContext,\n  useContext,\n  useMemo,\n  type ReactElement,\n  type ReactNode,\n} from 'react';\nimport type { ExtractArgs, StateContainerConstructor } from '@blac/core';\n\n/**\n * Internal context value: a Map from bloc constructor to the args object\n * provided by the nearest BlocProvider for that bloc class.\n *\n * Stored as a WeakMap-keyed record so nested providers for different blocs\n * compose without clobbering each other.\n */\ntype ProvidedArgsMap = Map<StateContainerConstructor, unknown>;\n\nconst ProvidedArgsContext = createContext<ProvidedArgsMap>(new Map());\n\n/**\n * Props for {@link BlocProvider}.\n */\nexport interface BlocProviderProps<T extends StateContainerConstructor> {\n  /**\n   * The bloc class whose args are being provided to descendants.\n   */\n  bloc: T;\n  /**\n   * Args that descendant `useBloc(bloc)` calls will resolve to when no\n   * own `args` are given.\n   */\n  args: ExtractArgs<T>;\n  children: ReactNode;\n}\n\n/**\n * Provides args to descendant `useBloc` calls for a specific bloc class via\n * React context.\n *\n * Descendants calling `useBloc(Bloc)` without their own `args` resolve to the\n * args supplied here. Own `args` on the `useBloc` call always win.\n *\n * Multiple `BlocProvider` wrappers for different bloc classes compose: each\n * provider merges its entry into the inherited map, so nested providers for\n * different blocs do not interfere.\n *\n * @example\n * ```tsx\n * <BlocProvider bloc={UserBloc} args={{ userId: 'alice' }}>\n *   <UserProfile />\n * </BlocProvider>\n * ```\n *\n * @example Per-mount private instance\n * ```tsx\n * const id = useId();\n * <BlocProvider bloc={CartBloc} args={{ _id: id }}>\n *   <CartWidget />\n * </BlocProvider>\n * ```\n */\nexport function BlocProvider<T extends StateContainerConstructor>({\n  bloc,\n  args,\n  children,\n}: BlocProviderProps<T>): ReactElement {\n  const parentMap = useContext(ProvidedArgsContext);\n\n  // Merge our entry into a new Map so sibling/parent providers for other blocs\n  // are preserved. Memoised on (parentMap, bloc, args) identity.\n  const mergedMap = useMemo(() => {\n    const next = new Map(parentMap);\n    next.set(bloc, args);\n    return next;\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [parentMap, bloc, args]);\n\n  return (\n    <ProvidedArgsContext.Provider value={mergedMap}>\n      {children}\n    </ProvidedArgsContext.Provider>\n  );\n}\n\n/**\n * Returns the args provided by the nearest {@link BlocProvider} for the given\n * bloc class, or `undefined` when called outside a matching provider.\n *\n * Used by `useBloc` to inherit provider args when no own `args` are given.\n */\nexport function useProvidedArgs<T extends StateContainerConstructor>(\n  BlocClass: T,\n): ExtractArgs<T> | undefined {\n  const map = useContext(ProvidedArgsContext);\n  return map.get(BlocClass) as ExtractArgs<T> | undefined;\n}\n","import {\n  useEffect,\n  useId,\n  useLayoutEffect,\n  useMemo,\n  useReducer,\n  useRef,\n  type RefObject,\n} from 'react';\nimport {\n  getRegistry,\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  PathInterner,\n  type PathSet,\n} from '@dirtytalk/structural';\nimport { useProvidedArgs } 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 derived from `options.args` (own args),\n *   then the surrounding {@link BlocProvider} context args for this bloc,\n *   then the default key (no args).\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 * Per-mount private instance:\n * ```ts\n * const id = useId();\n * const [state, bloc] = useBloc(MyBloc, { args: { _id: id } });\n * ```\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 Args-based shared instance\n * ```ts\n * const [state, bloc] = useBloc(UserBloc, { args: { userId: 'alice' } });\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  // Priority: own args > provider args (for this bloc class) > none.\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 ownArgs = (options as { args?: ExtractArgs<T> } | undefined)?.args;\n  const ownArgsRef = useRef(ownArgs);\n  ownArgsRef.current = ownArgs;\n  const ownArgsKey =\n    ownArgs === undefined ? undefined : JSON.stringify(ownArgs);\n\n  // Read provided args from the nearest BlocProvider for this bloc class.\n  const providerArgs = useProvidedArgs(BlocClass);\n  const providerArgsRef = useRef(providerArgs);\n  providerArgsRef.current = providerArgs;\n  const providerArgsKey =\n    providerArgs === undefined ? undefined : JSON.stringify(providerArgs);\n\n  const { bloc, instanceKey } = useMemo<{\n    bloc: TBloc;\n    instanceKey: string;\n  }>(() => {\n    // Own args win over provider args; provider args win over no args.\n    const effectiveArgs =\n      ownArgsRef.current !== undefined\n        ? ownArgsRef.current\n        : providerArgsRef.current;\n\n    const resolvedKey = resolveInstanceKey(BlocClass, effectiveArgs);\n    const refId = `useBloc@${consumerId}`;\n    const registry = getRegistry();\n    const instance = registry.acquire(BlocClass, resolvedKey, {\n      canCreate: true,\n      countRef: true,\n      refId,\n      args: effectiveArgs,\n    }) as TBloc;\n    return { bloc: instance, instanceKey: resolvedKey };\n    // oxlint-disable-next-line react-hooks/exhaustive-deps\n  }, [BlocClass, ownArgsKey, providerArgsKey]);\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  // Expanded interest: leaf paths PLUS their ancestor paths, so that when\n  // `patch` marks a parent (e.g. 'items') and the consumer tracked a child\n  // (e.g. 'items.length'), the intersection still fires. Updated in\n  // useLayoutEffect after each render once pathRef.current is populated.\n  const expandedInterestRef = 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: subscribe with the expanded interest (leaf paths + their\n    // ancestors). This ensures that when `patch` marks a parent path (e.g.\n    // 'items') and the consumer tracked a child (e.g. 'items.length'), the\n    // channel intersection still fires a re-render.\n    //\n    // `expandedInterestRef.current` is updated by the useLayoutEffect below\n    // after each render, so the interest is always fresh at flush time.\n    const unsub = channel.subscribe(\n      () => expandedInterestRef.current,\n      () => force(),\n    );\n    // Register the consumer's leaf 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      getRegistry().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, pathRef.current is the consumer's actual leaf\n  // interest (populated by the proxy during JSX evaluation). Re-register with\n  // the container so the skeleton reflects the latest paths, and expand the\n  // interest to include ancestor paths for the channel subscription.\n  //\n  // useLayoutEffect runs before the browser paints (and before any emit\n  // triggered by another effect), so the skeleton is fresh by the time the\n  // next emit fires.\n  // oxlint-disable-next-line react-hooks/exhaustive-deps\n  useLayoutEffect(() => {\n    if (selectRef.current !== undefined) return;\n    const container = bloc as unknown as StateContainer;\n    const paths = pathRef.current;\n    container.registerConsumerPaths(consumerId, paths);\n    // Expand interest to include ancestor paths so that `patch`-marked parent\n    // paths (e.g. 'items') wake a consumer that tracked a child (e.g.\n    // 'items.length').\n    expandedInterestRef.current = expandWithAncestors(\n      paths,\n      container.interner,\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/**\n * Expand a PathSet to include all ancestor paths of every tracked path.\n *\n * The auto-tracker records leaf paths (e.g. `'items.length'`), but\n * `StructuralContainer.patch` marks parent paths (e.g. `'items'`) since it\n * only walks the patch shape — not individual array elements or nested\n * descendants. Without ancestor expansion, a channel subscriber with interest\n * `{'items.length'}` would miss a `patch`-triggered `dirty={'items'}` because\n * `intersects({'items.length'}, {'items'}) = false`.\n *\n * Example: for leaf path `'a.b.c'`, adds `'a.b'` and `'a'` (but NOT `''`\n * root, since a root change would be captured by ALL_PATHS from the source\n * when there are ≤1 consumers, and adding `''` would make every field change\n * wake this consumer regardless of what it actually reads).\n */\nfunction expandWithAncestors(paths: PathSet, interner: PathInterner): PathSet {\n  if (paths === ALL_PATHS) return ALL_PATHS;\n  const leafPaths = paths as Set<number>;\n  if (leafPaths.size === 0) return paths;\n\n  const expanded = new Set<number>(leafPaths);\n  for (const id of leafPaths) {\n    const str = interner.lookup(id);\n    // Add all non-root ancestor segments: 'a.b.c' → add 'a.b', 'a'\n    let idx = str.lastIndexOf('.');\n    while (idx > 0) {\n      const ancestor = str.slice(0, idx);\n      expanded.add(interner.intern(ancestor));\n      idx = ancestor.lastIndexOf('.');\n    }\n  }\n  return expanded;\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

@@ -4,11 +4,14 @@ let _blac_core_testing = require("@blac/core/testing");
 let _testing_library_react = require("@testing-library/react");
 //#region src/testing.ts
 function renderWithBloc(ui, options) {
-	const { bloc: BlocClass, instanceKey, ...stubOptions } = options;
+	const { bloc: BlocClass, args, ...stubOptions } = options;
 	const previous = (0, _blac_core.getRegistry)();
 	(0, _blac_core.setRegistry)(new _blac_core.StateContainerRegistry());
-	const instance = (0, _blac_core_testing.createCubitStub)(BlocClass, stubOptions);
-	(0, _blac_core_testing.registerOverride)(BlocClass, instance, instanceKey);
+	const instance = (0, _blac_core_testing.createCubitStub)(BlocClass, {
+		...stubOptions,
+		args
+	});
+	(0, _blac_core_testing.registerOverride)(BlocClass, instance, args);
 	let renderResult;
 	try {
 		renderResult = (0, _testing_library_react.render)(ui);

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;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"}
+{"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 { ExtractArgs, 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  /** Args used to resolve which instance the stub is registered under. */\n  args?: ExtractArgs<T>;\n}\n\nexport function renderWithBloc<T extends StateContainerConstructor>(\n  ui: ReactElement,\n  options: RenderWithBlocOptions<T>,\n): RenderResult & { bloc: InstanceType<T> } {\n  const { bloc: BlocClass, args, ...stubOptions } = options;\n\n  const previous = getRegistry();\n  const testRegistry = new StateContainerRegistry();\n  setRegistry(testRegistry);\n\n  // Pass args explicitly so createCubitStub calls initConfig → init().\n  const instance = createCubitStub(BlocClass, { ...stubOptions, args } as any);\n  registerOverride(BlocClass, instance, args);\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":";;;;;AAmBA,SAAgB,eACd,IACA,SAC0C;CAC1C,MAAM,EAAE,MAAM,WAAW,MAAM,GAAG,gBAAgB;CAElD,MAAM,YAAA,GAAA,WAAA,aAAuB;CAE7B,CAAA,GAAA,WAAA,aAAY,IADaA,WAAAA,uBACF,CAAC;CAGxB,MAAM,YAAA,GAAA,mBAAA,iBAA2B,WAAW;EAAE,GAAG;EAAa;CAAK,CAAQ;CAC3E,CAAA,GAAA,mBAAA,kBAAiB,WAAW,UAAU,IAAI;CAE1C,IAAI;CACJ,IAAI;EACF,gBAAA,GAAA,uBAAA,QAAsB,EAAE;CAC1B,SAAS,GAAG;EACV,CAAA,GAAA,WAAA,aAAY,QAAQ;EACpB,MAAM;CACR;CAEA,MAAM,kBAAkB,aAAa;CACrC,aAAa,gBAAgB;EAC3B,gBAAgB;EAChB,CAAA,GAAA,WAAA,aAAY,QAAQ;CACtB;CAEA,OAAO;EACL,GAAG;EACH,MAAM;CACR;AACF;AAEA,SAAgB,mBACd,IACA,OACc;CACd,MAAM,YAAA,GAAA,WAAA,aAAuB;CAC7B,MAAM,eAAe,IAAIA,WAAAA,uBAAuB;CAChD,CAAA,GAAA,WAAA,aAAY,YAAY;CAExB,IAAI;EACF,MAAM,YAAY;CACpB,SAAS,GAAG;EACV,CAAA,GAAA,WAAA,aAAY,QAAQ;EACpB,MAAM;CACR;CAEA,IAAI;CACJ,IAAI;EACF,gBAAA,GAAA,uBAAA,QAAsB,EAAE;CAC1B,SAAS,GAAG;EACV,CAAA,GAAA,WAAA,aAAY,QAAQ;EACpB,MAAM;CACR;CAEA,MAAM,kBAAkB,aAAa;CACrC,aAAa,gBAAgB;EAC3B,gBAAgB;EAChB,CAAA,GAAA,WAAA,aAAY,QAAQ;CACtB;CAEA,OAAO;AACT"}

package/dist/testing.d.cts

@@ -1,11 +1,12 @@
 import type { ReactElement } from 'react';
 import type { RenderResult } from '@testing-library/react';
-import type { StateContainerConstructor } from '@blac/core';
+import type { ExtractArgs, StateContainerConstructor } from '@blac/core';
 import { StateContainerRegistry } from '@blac/core';
 import { type CubitStubOptions } from '@blac/core/testing';
 interface RenderWithBlocOptions<T extends StateContainerConstructor> extends CubitStubOptions<T> {
     bloc: T;
-    instanceKey?: string;
+    /** Args used to resolve which instance the stub is registered under. */
+    args?: ExtractArgs<T>;
 }
 export declare function renderWithBloc<T extends StateContainerConstructor>(ui: ReactElement, options: RenderWithBlocOptions<T>): RenderResult & {
     bloc: InstanceType<T>;

package/dist/testing.d.ts

@@ -1,11 +1,12 @@
 import type { ReactElement } from 'react';
 import type { RenderResult } from '@testing-library/react';
-import type { StateContainerConstructor } from '@blac/core';
+import type { ExtractArgs, StateContainerConstructor } from '@blac/core';
 import { StateContainerRegistry } from '@blac/core';
 import { type CubitStubOptions } from '@blac/core/testing';
 interface RenderWithBlocOptions<T extends StateContainerConstructor> extends CubitStubOptions<T> {
     bloc: T;
-    instanceKey?: string;
+    /** Args used to resolve which instance the stub is registered under. */
+    args?: ExtractArgs<T>;
 }
 export declare function renderWithBloc<T extends StateContainerConstructor>(ui: ReactElement, options: RenderWithBlocOptions<T>): RenderResult & {
     bloc: InstanceType<T>;

package/dist/testing.js

@@ -3,11 +3,14 @@ import { createCubitStub, registerOverride } from "@blac/core/testing";
 import { render } from "@testing-library/react";
 //#region src/testing.ts
 function renderWithBloc(ui, options) {
-	const { bloc: BlocClass, instanceKey, ...stubOptions } = options;
+	const { bloc: BlocClass, args, ...stubOptions } = options;
 	const previous = getRegistry();
 	setRegistry(new StateContainerRegistry());
-	const instance = createCubitStub(BlocClass, stubOptions);
-	registerOverride(BlocClass, instance, instanceKey);
+	const instance = createCubitStub(BlocClass, {
+		...stubOptions,
+		args
+	});
+	registerOverride(BlocClass, instance, args);
 	let renderResult;
 	try {
 		renderResult = render(ui);

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;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"}
+{"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 { ExtractArgs, 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  /** Args used to resolve which instance the stub is registered under. */\n  args?: ExtractArgs<T>;\n}\n\nexport function renderWithBloc<T extends StateContainerConstructor>(\n  ui: ReactElement,\n  options: RenderWithBlocOptions<T>,\n): RenderResult & { bloc: InstanceType<T> } {\n  const { bloc: BlocClass, args, ...stubOptions } = options;\n\n  const previous = getRegistry();\n  const testRegistry = new StateContainerRegistry();\n  setRegistry(testRegistry);\n\n  // Pass args explicitly so createCubitStub calls initConfig → init().\n  const instance = createCubitStub(BlocClass, { ...stubOptions, args } as any);\n  registerOverride(BlocClass, instance, args);\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":";;;;AAmBA,SAAgB,eACd,IACA,SAC0C;CAC1C,MAAM,EAAE,MAAM,WAAW,MAAM,GAAG,gBAAgB;CAElD,MAAM,WAAW,YAAY;CAE7B,YAAY,IADa,uBACF,CAAC;CAGxB,MAAM,WAAW,gBAAgB,WAAW;EAAE,GAAG;EAAa;CAAK,CAAQ;CAC3E,iBAAiB,WAAW,UAAU,IAAI;CAE1C,IAAI;CACJ,IAAI;EACF,eAAe,OAAO,EAAE;CAC1B,SAAS,GAAG;EACV,YAAY,QAAQ;EACpB,MAAM;CACR;CAEA,MAAM,kBAAkB,aAAa;CACrC,aAAa,gBAAgB;EAC3B,gBAAgB;EAChB,YAAY,QAAQ;CACtB;CAEA,OAAO;EACL,GAAG;EACH,MAAM;CACR;AACF;AAEA,SAAgB,mBACd,IACA,OACc;CACd,MAAM,WAAW,YAAY;CAC7B,MAAM,eAAe,IAAI,uBAAuB;CAChD,YAAY,YAAY;CAExB,IAAI;EACF,MAAM,YAAY;CACpB,SAAS,GAAG;EACV,YAAY,QAAQ;EACpB,MAAM;CACR;CAEA,IAAI;CACJ,IAAI;EACF,eAAe,OAAO,EAAE;CAC1B,SAAS,GAAG;EACV,YAAY,QAAQ;EACpB,MAAM;CACR;CAEA,MAAM,kBAAkB,aAAa;CACrC,aAAa,gBAAgB;EAC3B,gBAAgB;EAChB,YAAY,QAAQ;CACtB;CAEA,OAAO;AACT"}

package/dist/types.d.ts

@@ -1,13 +1,16 @@
 import type { ExtractArgs, ExtractState, InstanceReadonlyState, StateContainerConstructor } from '@blac/core';
 import type { RefObject } from 'react';
 /**
- * Conditional `args` field: required when the bloc declares Args, forbidden
- * (type `never`) when the bloc uses the default `void` Args.
+ * Conditional `args` field:
+ * - When the bloc uses the default `void` Args: args is forbidden (type `never`).
+ * - When the bloc declares Args: args is optional (may be inherited from a
+ *   `BlocProvider` ancestor at runtime; omitting it resolves to the provider
+ *   args or the default key).
  */
 type ArgsOption<T extends StateContainerConstructor> = ExtractArgs<T> extends void ? {
     args?: never;
 } : {
-    args: ExtractArgs<T>;
+    args?: ExtractArgs<T>;
 };
 /**
  * Configuration options for {@link useBloc}.
@@ -15,16 +18,15 @@ type ArgsOption<T extends StateContainerConstructor> = ExtractArgs<T> extends vo
  * @template TBloc - The state container constructor type
  *
  * @remarks
+ * Instance identity is derived entirely from `args`. For a per-mount private
+ * instance (like the old `instanceId: useId()` pattern) pass a stable unique
+ * object: `{ args: { _id: useId() } }`.
+ *
  * 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;
     /**
      * Per-consumer re-render selector. When provided, the hook re-renders
      * only when the returned array's elements change (Object.is per index).

package/dist/useBloc.d.ts

@@ -15,12 +15,19 @@ import type { UseBlocOptions, UseBlocReturn } from './types';
  *
  * 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.
+ *   unmount. The instance key is derived from `options.args` (own args),
+ *   then the surrounding {@link BlocProvider} context args for this bloc,
+ *   then the default key (no args).
  * - `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.
  *
+ * Per-mount private instance:
+ * ```ts
+ * const id = useId();
+ * const [state, bloc] = useBloc(MyBloc, { args: { _id: id } });
+ * ```
+ *
  * @template T - The state container constructor type (inferred from BlocClass)
  * @param BlocClass - The state container class to connect to
  * @param options - Configuration options
@@ -38,9 +45,9 @@ import type { UseBlocOptions, UseBlocReturn } from './types';
  * });
  * ```
  *
- * @example Named instance
+ * @example Args-based shared instance
  * ```ts
- * const [state, bloc] = useBloc(MyBloc, { instanceId: 'cart-42' });
+ * const [state, bloc] = useBloc(UserBloc, { args: { userId: 'alice' } });
  * ```
  */
 export declare function useBloc<T extends StateContainerConstructor = StateContainerConstructor>(BlocClass: T, options?: UseBlocOptions<T>): UseBlocReturn<T, ExtractState<T>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blac/react",
-  "version": "2.0.14",
+  "version": "2.0.16",
   "license": "MIT",
   "author": "Brendan Mullins <jsnanigans@gmail.com>",
   "description": "React bindings for BlaC — useBloc hook with automatic re-render optimization",
@@ -64,14 +64,27 @@
     "bloc",
     "bloc-pattern"
   ],
+  "size-limit": [
+    {
+      "name": "@blac/react (ESM, brotli, excl. peers)",
+      "path": "dist/index.js",
+      "limit": "3.5 kB",
+      "ignore": [
+        "react",
+        "react-dom",
+        "@blac/core",
+        "@types/react"
+      ]
+    }
+  ],
   "dependencies": {
-    "@dirtytalk/structural": "^0.0.2"
+    "@dirtytalk/structural": "^0.0.4"
   },
   "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.14"
+    "@blac/core": "^2.0.16"
   },
   "peerDependenciesMeta": {
     "@types/react": {
@@ -85,24 +98,26 @@
     }
   },
   "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.1.6",
+    "size-limit": "^11.1.6",
     "@testing-library/dom": "^10.4.1",
-    "@testing-library/jest-dom": "^6.6.4",
-    "@testing-library/react": "^16.3.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
-    "@types/react": "^19.1.9",
-    "@types/react-dom": "^19.1.7",
-    "@vitejs/plugin-react": "^4.7.0",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
     "babel-plugin-react-compiler": "^1.0.0",
-    "happy-dom": "^18.0.1",
-    "jsdom": "^26.1.0",
-    "publint": "^0.3.12",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
-    "typescript": "^5.9.2",
+    "happy-dom": "^20.9.0",
+    "jsdom": "^29.1.1",
+    "publint": "^0.3.21",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "typescript": "^6.0.3",
     "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+    "vite-plus": "^0.1.23",
     "vitest": "npm:@voidzero-dev/vite-plus-test@latest",
-    "vite-plus": "latest",
-    "@blac/core": "2.0.14"
+    "@blac/core": "2.0.16"
   },
   "scripts": {
     "dev": "vp pack --watch",
@@ -121,6 +136,7 @@
     "test:both": "pnpm test && echo '\n\n=== Running tests WITH React Compiler ===\n' && pnpm test:compiler",
     "verify": "node ../../scripts/run-workspace-bin.mjs publint",
     "typecheck": "tsc --noEmit",
+    "size": "size-limit",
     "deploy": "pnpm publish --access public"
   }
 }