@blac/react 2.0.19 → 2.0.21

package/README.md

@@ -51,12 +51,12 @@ 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,
+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 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.
@@ -82,14 +82,13 @@ function List() {
 
 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
+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).
+> by hand — is a planned compiler/Babel plugin.
 
 ## useBloc
 
@@ -123,9 +122,14 @@ import { useBloc } from '@blac/react';
 
 class UserCardCubit extends Cubit<UserCardState, { userId: string }> {
   // Constructor is zero-arg; framework calls init(args) before first snapshot
-  init(args: { userId: string }) {
+  protected init(args: { userId: string }) {
     this.userId = args.userId;
-    void this.loadUser(args.userId);
+  }
+
+  // Side effects (fetch/subscribe/timer) belong in onActivate, not init —
+  // see "Activation: onActivate / onDeactivate" below.
+  protected onActivate(signal: AbortSignal) {
+    void this.loadUser(this.userId);
   }
 }
 
@@ -157,21 +161,16 @@ Use `deps` to inject refs, stable callbacks, and long-lived controller handles.
 - **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):
+`deps` is **not** a `useBloc` option. A component contributes its slice by calling `useBlocDeps`:
 
 ```tsx
-import { useEffect, useId, useRef } from 'react';
-import { APPLY_DEPS, REMOVE_DEPS_OWNER } from '@blac/core';
-import { useBloc } from '@blac/react';
+import { useRef } from 'react';
+import { useBloc, useBlocDeps } from '@blac/react';
 
 const inputRef = useRef<HTMLInputElement>(null);
-const ownerId = useId();
 const [state, cubit] = useBloc(FileUploadCubit, { args: { endpoint } });
 
-useEffect(() => {
-  cubit[APPLY_DEPS](ownerId, { inputRef });
-  return () => cubit[REMOVE_DEPS_OWNER](ownerId);
-}, [cubit, inputRef, ownerId]);
+useBlocDeps(cubit, { inputRef });
 ```
 
 The bloc reads them lazily and guards for absence:
@@ -197,14 +196,16 @@ class FileUploadCubit extends Cubit<
 
 ```tsx
 // Component A owns inputRef
-cubitA[APPLY_DEPS](ownerIdA, { inputRef });
+useBlocDeps(cubit, { inputRef });
 
 // Component B owns onSubmit
-cubitB[APPLY_DEPS](ownerIdB, { onSubmit });
+useBlocDeps(cubit, { onSubmit });
 
 // cubit.deps === { inputRef, onSubmit } (merged from both consumers)
 ```
 
+Each calling component is its own owner; unmounting one withdraws only its own keys — dropped keys reconcile to `undefined` rather than being deleted from the object. No dependency array is needed: `useBlocDeps` applies on every commit and the core shallow-compares, so an unchanged slice is a no-op. Still pass identity-stable values (`useMemo` / `useCallback`), since a new function identity counts as a change.
+
 **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.
@@ -264,7 +265,7 @@ const [state] = useBloc(CounterCubit, {
 | `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`, `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() } }`).
+> 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 with `useBlocDeps(bloc, slice)`; for per-mount private instances, embed a stable unique ID in `args` (e.g. `{ args: { _id: useId() } }`).
 
 ### Identity and Keying
 
@@ -309,22 +310,33 @@ useBloc(FormCubit, { args: { ...options, _id: id } });
 useBloc(EditorCubit, { args: { _id: 'editor-1' } });
 ```
 
+### Activation: `onActivate` / `onDeactivate`
+
+`init(args)` stays the place to seed synchronous state — it is not deprecated and keeps working exactly as above. For side effects (fetch, subscribe, start a timer), use `onActivate(signal: AbortSignal)` instead: it fires on the instance's 0→1 ownership transition — i.e. only once something actually owns the instance — and gives you an `AbortSignal` that's aborted when the matching `onDeactivate()` fires on the 1→0 transition.
+
+```ts
+class UserCardCubit extends Cubit<UserCardState, { userId: string }> {
+  protected init(args: { userId: string }) {
+    this.userId = args.userId;
+  }
+
+  protected onActivate(signal: AbortSignal) {
+    fetch(`/api/users/${this.userId}`, { signal })
+      .then((r) => r.json())
+      .then((user) => this.patch({ user }));
+  }
+}
+```
+
+> **Ordering with `useBlocDeps`:** `onActivate` fires in a layout effect, before the first `useBlocDeps` slice is applied. A bloc reading `this.deps.x` inside `onActivate` sees `undefined` on first activation — this matches today's `init()` timing, so it isn't a regression, but it means `onActivate` is the wrong hook for deps-driven work. Use `onDepsChanged` for that instead.
+
 ### Breaking Changes (v2)
 
 - **`dependencies` option renamed to `select`** — avoids confusion with the `deps` (non-serializable handles) lane.
-- **`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`.
+- **`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 with `useBlocDeps(bloc, slice)`.
 - **Zero-arg constructor + `init(args)` lifecycle** — all blocs now use `new Type()` with no constructor args. Blocs that declare `Args` receive them via `init(args)` called by the framework before the first state snapshot.
 - **`args` is required when declared, forbidden when void** — enforced by the type system; no runtime guard needed.
 
-## Configuration
-
-```tsx
-import { configureBlacReact } from '@blac/react';
-
-// Configuration is currently empty; the tracking model is fixed and not configurable.
-configureBlacReact({});
-```
-
 ## Testing
 
 ```tsx

package/dist/BlocProvider.d.cts

@@ -0,0 +1,54 @@
+import { type ReactElement, type ReactNode } from 'react';
+import type { ExtractArgs, StateContainerConstructor } from '@blac/core';
+/**
+ * Props for {@link BlocProvider}.
+ * @public
+ */
+export interface BlocProviderProps<T extends StateContainerConstructor> {
+    /**
+     * The bloc class whose args are being provided to descendants.
+     */
+    bloc: T;
+    /**
+     * Args that descendant `useBloc(bloc)` calls will resolve to when no
+     * own `args` are given.
+     */
+    args: ExtractArgs<T>;
+    children: ReactNode;
+}
+/**
+ * Provides args to descendant `useBloc` calls for a specific bloc class via
+ * React context.
+ *
+ * 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 bloc={UserBloc} args={{ userId: 'alice' }}>
+ *   <UserProfile />
+ * </BlocProvider>
+ * ```
+ *
+ * @example Per-mount private instance
+ * ```tsx
+ * const id = useId();
+ * <BlocProvider bloc={CartBloc} args={{ _id: id }}>
+ *   <CartWidget />
+ * </BlocProvider>
+ * ```
+ * @public
+ */
+export declare function BlocProvider<T extends StateContainerConstructor>({ bloc, args, children, }: BlocProviderProps<T>): ReactElement;
+/**
+ * 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.
+ * @public
+ */
+export declare function useProvidedArgs<T extends StateContainerConstructor>(BlocClass: T): ExtractArgs<T> | undefined;

package/dist/BlocProvider.d.ts

@@ -2,6 +2,7 @@ import { type ReactElement, type ReactNode } from 'react';
 import type { ExtractArgs, StateContainerConstructor } from '@blac/core';
 /**
  * Props for {@link BlocProvider}.
+ * @public
  */
 export interface BlocProviderProps<T extends StateContainerConstructor> {
     /**
@@ -40,6 +41,7 @@ export interface BlocProviderProps<T extends StateContainerConstructor> {
  *   <CartWidget />
  * </BlocProvider>
  * ```
+ * @public
  */
 export declare function BlocProvider<T extends StateContainerConstructor>({ bloc, args, children, }: BlocProviderProps<T>): ReactElement;
 /**
@@ -47,5 +49,6 @@ export declare function BlocProvider<T extends StateContainerConstructor>({ bloc
  * bloc class, or `undefined` when called outside a matching provider.
  *
  * Used by `useBloc` to inherit provider args when no own `args` are given.
+ * @public
  */
 export declare function useProvidedArgs<T extends StateContainerConstructor>(BlocClass: T): ExtractArgs<T> | undefined;

package/dist/RegistryProvider.d.cts

@@ -0,0 +1,31 @@
+import { type ReactElement, type ReactNode } from 'react';
+import type { StateContainerRegistry } from '@blac/core';
+/**
+ * Internal context value: a registry to use in place of the module-global
+ * default (`getRegistry()`), or `null` when no provider is present.
+ */
+export declare const RegistryContext: import("react").Context<StateContainerRegistry | null>;
+/**
+ * Props for {@link RegistryProvider}.
+ * @public
+ */
+export interface RegistryProviderProps {
+    registry: StateContainerRegistry;
+    children: ReactNode;
+}
+/**
+ * Scopes descendant `useBloc` calls to a specific registry instead of the
+ * module-global default.
+ *
+ * Useful for test isolation, SSR isolation, and micro-frontends that must
+ * not share bloc instances with the host page.
+ *
+ * @example
+ * ```tsx
+ * <RegistryProvider registry={new StateContainerRegistry()}>
+ *   <App />
+ * </RegistryProvider>
+ * ```
+ * @public
+ */
+export declare function RegistryProvider({ registry, children, }: RegistryProviderProps): ReactElement;

package/dist/RegistryProvider.d.ts

@@ -0,0 +1,31 @@
+import { type ReactElement, type ReactNode } from 'react';
+import type { StateContainerRegistry } from '@blac/core';
+/**
+ * Internal context value: a registry to use in place of the module-global
+ * default (`getRegistry()`), or `null` when no provider is present.
+ */
+export declare const RegistryContext: import("react").Context<StateContainerRegistry | null>;
+/**
+ * Props for {@link RegistryProvider}.
+ * @public
+ */
+export interface RegistryProviderProps {
+    registry: StateContainerRegistry;
+    children: ReactNode;
+}
+/**
+ * Scopes descendant `useBloc` calls to a specific registry instead of the
+ * module-global default.
+ *
+ * Useful for test isolation, SSR isolation, and micro-frontends that must
+ * not share bloc instances with the host page.
+ *
+ * @example
+ * ```tsx
+ * <RegistryProvider registry={new StateContainerRegistry()}>
+ *   <App />
+ * </RegistryProvider>
+ * ```
+ * @public
+ */
+export declare function RegistryProvider({ registry, children, }: RegistryProviderProps): ReactElement;

package/dist/buildTrackedProxy.d.cts

@@ -0,0 +1,22 @@
+/**
+ * Build a per-consumer proxy for a bloc instance.
+ *
+ * Getters run with `this` bound to the **real instance**, not a proxy, so ES
+ * `#private` fields and methods work in user blocs. Path recording is done by
+ * `[WITH_TRACKED_STATE]`, which makes the instance's own `state` getter report
+ * the render's tracking proxy for the duration of the call; nested getter
+ * chains stay tracked because the override is still set.
+ *
+ * One allocation per bloc acquisition (inside `useMemo`), so the proxy is
+ * stable across renders.
+ *
+ * @param onDepHandle - Optional callback invoked when a read returns a branded
+ *   dep handle. Receives the original handle and returns the value to expose in
+ *   its place (the session-bound wrapper). The callback is responsible for
+ *   caching wrappers per handle to avoid re-allocation.
+ */
+export declare function buildTrackedProxy<T extends object>(instance: T, trackedStateRef: {
+    current: unknown;
+}, onDepHandle?: (handle: object) => unknown): {
+    proxy: T;
+};

package/dist/buildTrackedProxy.d.ts

@@ -1,31 +1,22 @@
 /**
- * Build a per-consumer proxy pair for a bloc instance.
+ * Build a per-consumer proxy for a bloc instance.
  *
- * Returns two proxies:
- * - `proxy` — the stable outer proxy returned to the consumer. Getter
- *   properties are invoked with `thisProxy` as `this` so that `this.state`
- *   reads inside getters are redirected to the current render's tracking
- *   proxy. Non-getter properties fall through to the live instance.
- * - `thisProxy` — the inner `this`-proxy used as the receiver for getter
- *   calls. Intercepts `state` to return `trackedStateRef.current` when a
- *   tracking context is active; otherwise falls through to the live value.
- *   When `onDepHandle` is supplied, a read off `this` whose value carries the
- *   `DEP_BRAND` symbol (i.e. a `depend()` handle) is routed through
- *   `onDepHandle`, which returns a per-consumer wrapper whose `.track()` opts
- *   the consumer into cross-bloc reactivity. Core stays decoupled — detection
- *   is purely by the `DEP_BRAND` symbol.
+ * Getters run with `this` bound to the **real instance**, not a proxy, so ES
+ * `#private` fields and methods work in user blocs. Path recording is done by
+ * `[WITH_TRACKED_STATE]`, which makes the instance's own `state` getter report
+ * the render's tracking proxy for the duration of the call; nested getter
+ * chains stay tracked because the override is still set.
  *
- * Both allocations happen exactly once per bloc acquisition (inside `useMemo`)
- * so the proxies are stable across renders.
+ * One allocation per bloc acquisition (inside `useMemo`), so the proxy is
+ * stable across renders.
  *
- * @param onDepHandle - Optional callback invoked when a getter reads a branded
- *   dep handle off `this`. Receives the original handle and returns the value
- *   to expose in its place (the session-bound wrapper). The callback is
- *   responsible for caching wrappers per handle to avoid re-allocation.
+ * @param onDepHandle - Optional callback invoked when a read returns a branded
+ *   dep handle. Receives the original handle and returns the value to expose in
+ *   its place (the session-bound wrapper). The callback is responsible for
+ *   caching wrappers per handle to avoid re-allocation.
  */
 export declare function buildTrackedProxy<T extends object>(instance: T, trackedStateRef: {
     current: unknown;
 }, onDepHandle?: (handle: object) => unknown): {
     proxy: T;
-    thisProxy: T;
 };

package/dist/config.d.cts

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

package/dist/config.d.ts

@@ -7,6 +7,8 @@
  * re-renders are driven by per-index `Object.is` over the returned array.
  *
  * Reserved for forwards-compatible knobs; currently empty.
+ *
+ * @public
  */
 export interface BlacReactConfig {
 }
@@ -14,6 +16,7 @@ export interface BlacReactConfig {
  * Configure global defaults for `@blac/react` hooks.
  *
  * @param config - Partial configuration to merge with current globals
+ * @public
  */
 export declare function configureBlacReact(config: Partial<BlacReactConfig>): void;
 /**