@blac/react 2.0.17 → 2.0.19

package/README.md

@@ -4,6 +4,12 @@ React bindings for BlaC — `useBloc` hook with proxy-based automatic re-render
 
 **[Documentation](https://blac-docs.pages.dev/react/getting-started)** · **[npm](https://www.npmjs.com/package/@blac/react)**
 
+> [!WARNING]
+> **BlaC v2 is in pre-release (beta).** While in beta, **breaking API changes may
+> ship in patch releases** without a major version bump. Pin an exact version and
+> check the changelog before upgrading. Strict semver resumes once v2 is officially
+> out of beta.
+
 ## Installation
 
 ```bash
@@ -38,6 +44,53 @@ function Counter() {
 }
 ```
 
+## Reactivity model
+
+BlaC follows one rule:
+
+> **A component becomes reactive only to the paths it reads during its own render.**
+
+`useBloc` returns a proxy that records which paths you read; the component
+re-renders only when one of *those* paths changes. Reads outside render — effects,
+event handlers, `setTimeout`, `await` — record nothing.
+
+### Props are snapshots — `untracked()`
+
+A tracking proxy stays bound to the component that *created* it. If a parent passes
+a proxied value to a child and the child reads from it, that read is attributed to
+the **parent** — so the parent over-subscribes and re-renders for paths only the
+child uses.
+
+Pass the value through `untracked()` to hand the child a detached snapshot instead:
+
+```tsx
+import { useBloc, untracked } from '@blac/react';
+
+function List() {
+  const [state] = useBloc(TodoBloc);
+  // The parent reads each id (for keys). Rows read `.label` etc. off the
+  // snapshot, which is detached — those reads are NOT attributed to List.
+  return (
+    <ul>
+      {state.items.map((item) => (
+        <Row key={item.id} item={untracked(item)} />
+      ))}
+    </ul>
+  );
+}
+```
+
+The trade-off is intentional and React-like: a component that receives an
+`untracked()` value is **not** reactive to it — a change triggers nothing, memo or
+not. If no component reads a path during its *own* render, a change to that path
+re-renders nothing. To react to data, a component must be a consumer itself (call
+its own `useBloc`). Nobody up the tree re-renders for a path unless they read it
+themselves.
+
+> Making this automatic — per-component read scoping so `untracked()` isn't needed
+> by hand — is a planned compiler/Babel plugin. See
+> [`plans/blac-ambient-tracking/design.md`](../../plans/blac-ambient-tracking/design.md).
+
 ## useBloc
 
 ```tsx
@@ -88,11 +141,11 @@ function UserCard({ userId }: { userId: string }) {
 - **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** — pass a per-mount `instanceId` (keyed by React's `useId()`) to give each mount its own instance, disposed on unmount:
+- **Per-component private instances** — embed a per-mount unique ID inside `args` (using React's `useId()`) to give each mount its own instance, disposed on unmount:
 
 ```tsx
-const instanceId = useId();
-const [state, cubit] = useBloc(FormCubit, { args: options, instanceId });
+const id = useId();
+const [state, cubit] = useBloc(FormCubit, { args: { ...options, _id: id } });
 ```
 
 ### `deps`: Non-Serializable Refs and Callbacks
@@ -204,24 +257,29 @@ const [state] = useBloc(CounterCubit, {
 
 ### Options
 
-| 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                                                   |
+| 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 |
+| `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.
+> Auto-tracking is always on when `select` is omitted — it is **not** a configurable option. `deps`, `autoInstance`, and `instanceId` are not `useBloc` options: wire deps from a mount effect (`APPLY_DEPS` / `REMOVE_DEPS_OWNER`); for per-mount private instances, embed a stable unique ID in `args` (e.g. `{ args: { _id: useId() } }`).
 
 ### Identity and Keying
 
 Instance identity is resolved in precedence order:
 
-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
+1. **`<BlocProvider>` context id** — inherited from an ancestor provider
+2. **`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`)
+3. **`'default'`** — singleton fallback
+
+For a per-mount private instance, embed a stable unique ID inside `args` so each mount hashes to a distinct key:
+
+```tsx
+const id = useId();
+useBloc(FormCubit, { args: { ...options, _id: id } });
+```
 
 Blocs declare explicit identity via a static class property:
 
@@ -237,24 +295,24 @@ class DocumentCubit extends Cubit<
 
 ### Instance Sharing and Lifecycle
 
-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:
+By default, all components using `useBloc(MyBloc)` with the same identity share one instance. For per-component private instances, embed a unique ID in `args` so each mount derives a distinct key:
 
 ```tsx
 // All users with userId=123 share one instance
 useBloc(UserCardCubit, { args: { userId: 123 } });
 
 // Each component mount gets its own instance, disposed on unmount
-const instanceId = useId();
-useBloc(FormCubit, { args: options, instanceId });
+const id = useId();
+useBloc(FormCubit, { args: { ...options, _id: id } });
 
-// Explicit id (escape hatch for non-derivable identity)
-useBloc(EditorCubit, { instanceId: 'editor-1' });
+// Explicit stable key (escape hatch for non-derivable identity)
+useBloc(EditorCubit, { args: { _id: 'editor-1' } });
 ```
 
 ### Breaking Changes (v2)
 
 - **`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`.
+- **`autoTrack`, `autoInstance`, `instanceId`, and `deps` are no longer `useBloc` options** — auto-tracking is always on (opt out per-consumer with `select`); per-mount private instances embed a unique ID in `args`; 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.
 

package/dist/index.cjs

@@ -112,6 +112,7 @@ function buildTrackedProxy(instance, trackedStateRef, onDepHandle) {
 //#endregion
 //#region src/useBloc.ts
 let nextConsumerId = 0;
+const ARGS_UNSET = Symbol("blac.argsKeyUnset");
 const primaryRefId = (consumerId) => `useBloc@${consumerId}`;
 const depRefId = (consumerId) => `useBloc@${consumerId}:dep`;
 /**
@@ -125,7 +126,7 @@ const depRefId = (consumerId) => `useBloc@${consumerId}:dep`;
 *   {@link trackRender} + the container's path-scoped `DirtyChannel`.
 * - **Manual select**: pass `options.select` to opt out of auto-tracking.
 *   The hook re-renders only when the returned array's elements change
-*   (per-index `Object.is`). This replaces the v1 `dependencies` option.
+*   (per-index `Object.is`).
 *
 * Lifecycle:
 * - The bloc is acquired from the registry on mount and released on
@@ -152,7 +153,7 @@ const depRefId = (consumerId) => `useBloc@${consumerId}:dep`;
 * const [state, bloc] = useBloc(MyBloc);
 * ```
 *
-* @example Manual select (replaces v1 `dependencies`)
+* @example Manual select
 * ```ts
 * const [state, bloc] = useBloc(MyBloc, {
 *   select: (state) => [state.count],
@@ -179,30 +180,48 @@ function useBloc(BlocClass, options) {
 	const ownArgs = options?.args;
 	const ownArgsRef = (0, react.useRef)(ownArgs);
 	ownArgsRef.current = ownArgs;
-	const ownArgsKey = ownArgs === void 0 ? void 0 : JSON.stringify(ownArgs);
+	const ownArgsKeyRef = (0, react.useRef)({
+		ref: ARGS_UNSET,
+		key: void 0
+	});
+	if (!Object.is(ownArgsKeyRef.current.ref, ownArgs)) ownArgsKeyRef.current = {
+		ref: ownArgs,
+		key: ownArgs === void 0 ? void 0 : JSON.stringify(ownArgs)
+	};
+	const ownArgsKey = ownArgsKeyRef.current.key;
 	const providerArgs = useProvidedArgs(BlocClass);
 	const providerArgsRef = (0, react.useRef)(providerArgs);
 	providerArgsRef.current = providerArgs;
-	const providerArgsKey = providerArgs === void 0 ? void 0 : JSON.stringify(providerArgs);
+	const providerArgsKeyRef = (0, react.useRef)({
+		ref: ARGS_UNSET,
+		key: void 0
+	});
+	if (!Object.is(providerArgsKeyRef.current.ref, providerArgs)) providerArgsKeyRef.current = {
+		ref: providerArgs,
+		key: providerArgs === void 0 ? void 0 : JSON.stringify(providerArgs)
+	};
+	const providerArgsKey = providerArgsKeyRef.current.key;
 	const trackedStateRef = (0, react.useRef)(null);
 	const sessionRef = (0, react.useRef)(/* @__PURE__ */ new Map());
 	const depSubsRef = (0, react.useRef)(/* @__PURE__ */ new Map());
 	const depWrapperCacheRef = (0, react.useRef)(/* @__PURE__ */ new Map());
+	const proxyCacheRef = (0, react.useRef)(new _dirtytalk_structural.ProxyCache());
+	const lastReconcileRef = (0, react.useRef)(null);
+	const [rebindNonce, bumpRebind] = (0, react.useReducer)((x) => x + 1, 0);
+	const ownedBlocRef = (0, react.useRef)(null);
 	const { bloc, instanceKey, trackedBloc } = (0, react.useMemo)(() => {
 		const effectiveArgs = ownArgsRef.current !== void 0 ? ownArgsRef.current : providerArgsRef.current;
 		const resolvedKey = (0, _blac_core.resolveInstanceKey)(BlocClass, effectiveArgs);
-		const refId = primaryRefId(consumerId);
 		const instance = (0, _blac_core.getRegistry)().acquire(BlocClass, resolvedKey, {
 			canCreate: true,
-			countRef: true,
-			refId,
+			countRef: false,
 			args: effectiveArgs
 		});
 		const onDepHandle = (handle) => {
 			const cache = depWrapperCacheRef.current;
 			const cached = cache.get(handle);
 			if (cached !== void 0) return cached;
-			const wrapper = makeDepWrapper(handle, consumerId, trackedStateRef, sessionRef, depSubsRef, onDepHandle);
+			const wrapper = makeDepWrapper(handle, consumerId, trackedStateRef, sessionRef, onDepHandle);
 			cache.set(handle, wrapper);
 			return wrapper;
 		};
@@ -215,47 +234,80 @@ function useBloc(BlocClass, options) {
 	}, [
 		BlocClass,
 		ownArgsKey,
-		providerArgsKey
+		providerArgsKey,
+		rebindNonce
 	]);
 	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);
+	const renderStateRef = (0, react.useRef)(void 0);
+	const prevBlocRef = (0, react.useRef)(null);
 	(0, react.useEffect)(() => {
 		const channel = bloc.channel;
-		if (selectRef.current !== void 0) return channel.subscribe(() => _dirtytalk_structural.ALL_PATHS, () => {
-			const select = selectRef.current;
-			if (!select) {
+		if (selectRef.current !== void 0) {
+			const unsub = channel.subscribe(() => _dirtytalk_structural.ALL_PATHS, () => {
+				const select = selectRef.current;
+				if (!select) {
+					force();
+					return;
+				}
+				const next = select(bloc.state, bloc);
+				const prev = lastSelectionRef.current;
+				if (prev !== null && shallowArrayEqual(prev, next)) return;
+				lastSelectionRef.current = next;
 				force();
-				return;
+			});
+			const select = selectRef.current;
+			if (select) {
+				const next = select(bloc.state, bloc);
+				const prev = lastSelectionRef.current;
+				if (prev === null || !shallowArrayEqual(prev, next)) {
+					lastSelectionRef.current = next;
+					force();
+				}
 			}
-			const next = select(bloc.state, bloc);
-			const prev = lastSelectionRef.current;
-			if (prev !== null && shallowArrayEqual(prev, next)) return;
-			lastSelectionRef.current = next;
-			force();
-		});
+			return unsub;
+		}
 		const unsub = channel.subscribe(() => expandedInterestRef.current, () => force());
 		bloc.registerConsumerPaths(consumerId, pathRef.current);
+		if (bloc.state !== renderStateRef.current) force();
 		return () => {
 			unsub();
 			bloc.unregisterConsumer(consumerId);
 		};
 	}, [bloc, consumerId]);
-	(0, react.useEffect)(() => {
-		onMountRef.current?.(bloc);
+	(0, react.useLayoutEffect)(() => {
+		const registry = (0, _blac_core.getRegistry)();
+		const live = registry.acquire(BlocClass, instanceKey, {
+			canCreate: true,
+			countRef: true,
+			refId: primaryRefId(consumerId)
+		});
+		ownedBlocRef.current = live;
+		onMountRef.current?.(live);
+		if (live !== bloc) bumpRebind();
 		return () => {
-			onUnmountRef.current?.(bloc);
-			(0, _blac_core.getRegistry)().release(BlocClass, instanceKey, false, primaryRefId(consumerId));
+			onUnmountRef.current?.(ownedBlocRef.current ?? bloc);
+			registry.release(BlocClass, instanceKey, false, primaryRefId(consumerId));
 		};
-	}, [bloc, instanceKey]);
+	}, [
+		BlocClass,
+		instanceKey,
+		consumerId
+	]);
 	const rawState = bloc.state;
+	renderStateRef.current = rawState;
+	if (prevBlocRef.current !== bloc) {
+		prevBlocRef.current = bloc;
+		lastSelectionRef.current = null;
+	}
 	let state;
 	if (selectRef.current !== void 0) {
 		state = rawState;
 		if (lastSelectionRef.current === null) lastSelectionRef.current = selectRef.current(rawState, bloc);
 	} else {
-		const tracked = (0, _dirtytalk_structural.trackRender)(rawState, bloc.interner);
+		const tracked = (0, _dirtytalk_structural.trackRender)(rawState, bloc.interner, proxyCacheRef.current);
 		state = tracked.value;
 		trackedStateRef.current = tracked.value;
 		pathRef.current = tracked.paths;
@@ -265,16 +317,33 @@ function useBloc(BlocClass, options) {
 			kind: "primary",
 			paths: tracked.paths
 		});
+		queueMicrotask(tracked.disarm);
 	}
 	(0, react.useLayoutEffect)(() => {
 		trackedStateRef.current = null;
-		if (selectRef.current !== void 0) return;
+		if (selectRef.current !== void 0) {
+			lastReconcileRef.current = null;
+			return;
+		}
 		const container = bloc;
 		const paths = pathRef.current;
+		const session = sessionRef.current;
+		const last = lastReconcileRef.current;
+		if (last !== null && last.primaryContainer === container && (0, _dirtytalk_structural.pathSetEquals)(last.primaryPaths, paths)) {
+			let unchanged = last.deps.size === session.size - 1;
+			if (unchanged) for (const [depContainer, entry] of session) {
+				if (entry.kind === "primary") continue;
+				const prevEntry = last.deps.get(depContainer);
+				if (prevEntry === void 0 || prevEntry.key !== entry.key || prevEntry.refId !== entry.refId || !Object.is(prevEntry.args, entry.args) || !(0, _dirtytalk_structural.pathSetEquals)(prevEntry.paths, entry.paths)) {
+					unchanged = false;
+					break;
+				}
+			}
+			if (unchanged) return;
+		}
 		container.registerConsumerPaths(consumerId, paths);
 		expandedInterestRef.current = expandWithAncestors(paths, container.interner);
 		const subs = depSubsRef.current;
-		const session = sessionRef.current;
 		for (const [depContainer, sub] of subs) if (!session.has(depContainer)) {
 			sub.unsubscribe();
 			depContainer.unregisterConsumer(consumerId);
@@ -290,6 +359,12 @@ function useBloc(BlocClass, options) {
 				existing.interestRef.current = interest;
 				continue;
 			}
+			(0, _blac_core.getRegistry)().acquire(entry.Type, entry.key, {
+				canCreate: true,
+				countRef: true,
+				refId: entry.refId,
+				args: entry.args
+			});
 			const interestRef = { current: interest };
 			const unsubscribe = depContainer.channel.subscribe(() => interestRef.current, () => force());
 			subs.set(depContainer, {
@@ -297,9 +372,25 @@ function useBloc(BlocClass, options) {
 				interestRef,
 				Type: entry.Type,
 				key: entry.key,
-				refId: entry.refId
+				refId: entry.refId,
+				args: entry.args
+			});
+		}
+		const depsSignature = /* @__PURE__ */ new Map();
+		for (const [depContainer, entry] of session) {
+			if (entry.kind === "primary") continue;
+			depsSignature.set(depContainer, {
+				paths: entry.paths,
+				key: entry.key,
+				refId: entry.refId,
+				args: entry.args
 			});
 		}
+		lastReconcileRef.current = {
+			primaryContainer: container,
+			primaryPaths: paths,
+			deps: depsSignature
+		};
 	});
 	(0, react.useEffect)(() => {
 		const subs = depSubsRef.current;
@@ -323,10 +414,11 @@ function useBloc(BlocClass, options) {
 * tracked getter's `this`. The wrapper exposes the same accessors as the core
 * handle and overrides `.track()`:
 *
-* - **Inside a render** (`trackedStateRef.current != null`): resolve the dep,
-*   take a refcount (once per consumer), `trackRender` its state, merge the
-*   recorded paths into the session entry, build/reuse a tracked proxy for the
-*   dep so its OWN getters track too, and return `[trackedValue, depProxy]`.
+* - **Inside a render** (`trackedStateRef.current != null`): resolve (ENSURE,
+*   no ref) the dep, `trackRender` its state, merge the recorded paths into the
+*   session entry, build/reuse a tracked proxy for the dep so its OWN getters
+*   track too, and return `[trackedValue, depProxy]`. The ownership ref is taken
+*   by the layout-effect reconcile pass, not here.
 * - **Outside a render**: degrade to live `[dep.state, dep]` — matches the core
 *   base impl, safe in event handlers/effects/methods.
 *
@@ -339,11 +431,12 @@ function useBloc(BlocClass, options) {
 * the dep already has a non-primary session entry this render, reuse its proxy
 * + union its paths instead of re-acquiring.
 */
-function makeDepWrapper(handle, consumerId, trackedStateRef, sessionRef, depSubsRef, onDepHandle) {
+function makeDepWrapper(handle, consumerId, trackedStateRef, sessionRef, onDepHandle) {
 	const brand = handle[_blac_core.DEP_BRAND];
 	const refId = depRefId(consumerId);
 	const registry = (0, _blac_core.getRegistry)();
 	const perDep = /* @__PURE__ */ new Map();
+	const proxyCache = new _dirtytalk_structural.ProxyCache();
 	const resolve = (options) => {
 		const args = options?.args ?? brand.defaultArgs;
 		const key = registry.resolveKey(brand.Type, void 0, args);
@@ -360,13 +453,7 @@ function makeDepWrapper(handle, consumerId, trackedStateRef, sessionRef, depSubs
 			if (trackedStateRef.current == null) return [dep.state, dep];
 			const session = sessionRef.current;
 			const existing = session.get(dep);
-			if (existing === void 0 && !depSubsRef.current.has(dep)) registry.acquire(brand.Type, key, {
-				canCreate: true,
-				countRef: true,
-				refId,
-				args
-			});
-			const tracked = (0, _dirtytalk_structural.trackRender)(dep.state, dep.interner);
+			const tracked = (0, _dirtytalk_structural.trackRender)(dep.state, dep.interner, proxyCache);
 			let cache = perDep.get(dep);
 			if (cache === void 0) {
 				const ref = { current: tracked.value };
@@ -382,7 +469,8 @@ function makeDepWrapper(handle, consumerId, trackedStateRef, sessionRef, depSubs
 				paths: tracked.paths,
 				Type: brand.Type,
 				key,
-				refId
+				refId,
+				args
 			});
 			return [tracked.value, cache.proxy];
 		}
@@ -461,6 +549,12 @@ function configureBlacReact(config) {
 //#endregion
 exports.BlocProvider = BlocProvider;
 exports.configureBlacReact = configureBlacReact;
+Object.defineProperty(exports, "untracked", {
+	enumerable: true,
+	get: function() {
+		return _dirtytalk_structural.untracked;
+	}
+});
 exports.useBloc = useBloc;
 exports.useProvidedArgs = useProvidedArgs;