# BlaC Documentation

Type-safe state management for React with automatic re-render optimization. Comprehensive guide covering core concepts, React integration, plugins, testing, and framework integrations.

---

# Async

> Model the loading lifecycle as state, guard against overlapping requests, and understand why BlaC does not integrate with React Suspense.

Source: /guide/async/

Most real blocs eventually have to fetch something. BlaC has no special async primitive — an async action is just a method that `await`s and emits as it goes. The work is in **modelling the loading lifecycle as state** so the UI can render it, and in guarding against races when requests overlap.

This page covers the canonical loading flow, derived loading flags, a reusable "loadable" surface, cancellation, and — importantly — what BlaC does _not_ do with React Suspense.

## Async actions on a Cubit

The core pattern: an async method moves state through `loading` -> `success`/`error`, with a request-id guard so a stale response can never overwrite a newer one.

Model the lifecycle as a **discriminated union** keyed on `status`. This makes illegal states unrepresentable — you can't have `data` and an `error` at the same time, and TypeScript narrows each branch for you in the view.

```ts twoslash
import { Cubit } from '@blac/core';

interface User {
  id: string;
  name: string;
}

declare const api: {
  fetchUser(id: string): Promise<User>;
};
// ---cut---
type UserState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; user: User }
  | { status: 'error'; message: string };

class UserCubit extends Cubit<UserState> {
  // Monotonic counter: every call gets a higher id than the last.
  private requestId = 0;

  constructor() {
    super({ status: 'idle' });
  }

  load = async (id: string) => {
    const reqId = ++this.requestId;
    this.emit({ status: 'loading' });

    try {
      const user = await api.fetchUser(id);
      // Latest-wins: a slower earlier request must not clobber a newer one.
      if (reqId !== this.requestId) return;
      this.emit({ status: 'success', user });
    } catch (e) {
      if (reqId !== this.requestId) return;
      this.emit({ status: 'error', message: String(e) });
    }
  };
}
```

Why `emit` and not `patch` here? Because the union has no shared shape — `loading` has no `user` key, `error` has no `user` key. `patch` deep-merges, which would leave a stale `user` lingering under an `error` status. `emit` replaces wholesale, so each branch is exactly the keys that branch declares. (See [Cubit](/core/cubit) for the replace-vs-merge rule.)

### The request-id guard

Two calls to `load('a')` then `load('b')` can resolve in either order — the network doesn't promise FIFO. Without the guard, a slow `'a'` response landing after `'b'` would overwrite the correct result with stale data.

The guard is three lines:

```ts twoslash
import { Cubit } from '@blac/core';
declare const api: { fetch(id: string): Promise<unknown> };
type S = { status: 'idle' | 'loading' };
class Demo extends Cubit<S> {
  private requestId = 0;
  // ---cut---
  load = async (id: string) => {
    const reqId = ++this.requestId; // claim the latest slot
    // ... await the request ...
    if (reqId !== this.requestId) return; // a newer call has started; bail
    // ... emit the result ...
  };
  // ---cut-after---
}
```

`++this.requestId` claims a fresh id and records it as the current one. Any in-flight call whose `reqId` no longer equals `this.requestId` knows a newer call has superseded it and silently returns before emitting. This is cheaper than wiring an `AbortController` and is enough whenever you only care about the _result_ of the newest request. When you also need to stop the actual network work, reach for [cancellation](#cancellation-and-cleanup).

:::tip[One counter per logical operation]
`requestId` guards a single operation. If a bloc has several independent async actions (`loadUser`, `loadOrders`), give each its own counter — a shared one would make a `loadOrders` call cancel an in-flight `loadUser`.
:::

<AsyncDemo client:visible />

## Reading async state in the view

Because the state is a discriminated union, the consumer switches on `status` and TypeScript narrows each branch. Auto-tracking records the read of `state.status` (and whatever else each branch touches), so the component re-renders exactly when those paths change.

```tsx
function UserCard({ id }: { id: string }) {
  const [state, user] = useBloc(UserCubit);

  switch (state.status) {
    case 'idle':
      return <button onClick={() => user.load(id)}>Load user</button>;
    case 'loading':
      return <p>Loading…</p>;
    case 'error':
      // `state` is narrowed: `state.message` is available here.
      return <p>Failed: {state.message}</p>;
    case 'success':
      // narrowed to the success branch: `state.user` exists.
      return <p>{state.user.name}</p>;
  }
}
```

## Derived loading flags with getters

A union `status` is the source of truth, but views often want a boolean like `isLoading` or a "can I retry?" flag. Derive these with getters rather than storing them — a stored boolean has to be kept in sync with `status` by hand and will eventually drift.

```ts twoslash
import { Cubit } from '@blac/core';
interface User {
  id: string;
  name: string;
}
type UserState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; user: User }
  | { status: 'error'; message: string };
// ---cut---
class UserCubit extends Cubit<UserState> {
  constructor() {
    super({ status: 'idle' });
  }

  get isLoading() {
    return this.state.status === 'loading';
  }

  get canRetry() {
    return this.state.status === 'idle' || this.state.status === 'error';
  }

  get user() {
    return this.state.status === 'success' ? this.state.user : null;
  }
}
```

:::tip[Loading getters track in render]
Reading `user.isLoading` directly in render is reactive: the returned bloc is proxied, and `this.state.status` inside the getter records through the current state proxy. Use `select: (_, bloc) => [bloc.isLoading]` only when you want the boolean result to be the re-render boundary. Full rule: [Dependency Tracking](/react/dependency-tracking) and [Performance](/react/performance#pattern-getters-as-computed-properties).
:::

## A reusable loadable surface

When several blocs each carry one async resource, the same four-branch union repeats. Factor it into a generic `Loadable<T>` type and a couple of helpers so each bloc stays terse and every consumer narrows the same way.

```ts twoslash
export type Loadable<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; message: string };

export const loading = (): Loadable<never> => ({ status: 'loading' });
export const success = <T>(data: T): Loadable<T> => ({
  status: 'success',
  data,
});
export const failure = (message: string): Loadable<never> => ({
  status: 'error',
  message,
});
```

A bloc whose entire state _is_ one loadable resource can extend `Cubit<Loadable<T>>` directly:

```ts twoslash
export type Loadable<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; message: string };
declare const loading: () => Loadable<never>;
declare const success: <T>(data: T) => Loadable<T>;
declare const failure: (message: string) => Loadable<never>;
declare const api: { fetchReport(): Promise<Report> };
interface Report {
  id: string;
}
// ---cut---
import { Cubit } from '@blac/core';

class ReportCubit extends Cubit<Loadable<Report>> {
  private requestId = 0;

  constructor() {
    super({ status: 'idle' });
  }

  load = async () => {
    const reqId = ++this.requestId;
    this.emit(loading());
    try {
      const data = await api.fetchReport();
      if (reqId !== this.requestId) return;
      this.emit(success(data));
    } catch (e) {
      if (reqId !== this.requestId) return;
      this.emit(failure(String(e)));
    }
  };
}
```

When the resource is one field among several (a list page with filters, say), nest the loadable on a key instead of making it the whole state, and use `patch` to update that one field — `patch` deep-merges, so the surrounding fields survive:

```ts twoslash
export type Loadable<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; message: string };
declare const loading: () => Loadable<never>;
declare const success: <T>(data: T) => Loadable<T>;
declare const api: { fetchItems(filter: string): Promise<Item[]> };
interface Item {
  id: string;
}
// ---cut---
import { Cubit } from '@blac/core';

interface ListState {
  filter: string;
  items: Loadable<Item[]>;
}

class ListCubit extends Cubit<ListState> {
  private requestId = 0;

  constructor() {
    super({ filter: 'all', items: { status: 'idle' } });
  }

  load = async () => {
    const reqId = ++this.requestId;
    // patch only the `items` field; `filter` is untouched.
    this.patch({ items: loading() });
    try {
      const data = await api.fetchItems(this.state.filter);
      if (reqId !== this.requestId) return;
      this.patch({ items: success(data) });
    } catch (e) {
      if (reqId !== this.requestId) return;
      this.patch({ items: { status: 'error', message: String(e) } });
    }
  };
}
```

## Suspense

BlaC does **not** integrate with React Suspense, and `useBloc` does **not** work with the `use()` hook for data fetching. This is by design, and it's worth being precise about why.

`useBloc` subscribes to the bloc's path-scoped channel and re-renders through a `useReducer` dispatch — React's ordinary update path. It does **not** use `useSyncExternalStore`, and it never throws a promise to a Suspense boundary or unwraps one via `use()`. There is no code path in `useBloc` that suspends a component. (Verified in [useBloc](/react/use-bloc); the hook reads state directly during render and forces an update on change.)

So you don't get a `<Suspense fallback={…}>` boundary catching a BlaC load for free. Instead, **model the loading state explicitly** — which is exactly what the `status` union and the loadable surface above are for. The "fallback" is just the `loading` branch of your switch:

```tsx
function ReportView() {
  const [state, report] = useBloc(ReportCubit, {
    onMount: (bloc) => bloc.load(), // kick off the fetch when the view appears
  });

  // This switch *is* your Suspense boundary, written out by hand.
  if (state.status === 'loading' || state.status === 'idle') {
    return <p>Loading…</p>;
  }
  if (state.status === 'error') {
    return (
      <div role="alert">
        {state.message} <button onClick={report.load}>Retry</button>
      </div>
    );
  }
  // narrowed to success: `state.data` is the Report.
  return <h1>{state.data.title}</h1>;
}
```

The upside of explicit modelling: error and retry are first-class states, not exceptions you have to catch at a boundary, and the loading UI lives next to the data it's loading. The cost is the `if` ladder — but with a discriminated union it's a few lines and fully type-checked.

:::note[Kicking off the load]
`onMount` fires after the bloc is acquired, so it's the natural place to start a fetch when the consuming component appears — see [useBloc](/react/use-bloc). For a load that should run once per _instance_ regardless of which component mounts first, start it from the bloc's `init` hook instead; see [Cubit](/core/cubit).
:::

## Cancellation and cleanup

The request-id guard stops a stale _result_ from being applied, but the underlying request keeps running. When you also want to abort the in-flight network work — to save bandwidth, or because the bloc is being torn down — pair the guard with an `AbortController`.

Pass the controller's `signal` to `fetch`, and abort the previous controller before starting a new request:

```ts twoslash
import { Cubit } from '@blac/core';
interface Results {
  hits: string[];
}
type SearchState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; results: Results }
  | { status: 'error'; message: string };
// ---cut---
class SearchCubit extends Cubit<SearchState> {
  private requestId = 0;
  private controller: AbortController | null = null;

  constructor() {
    super({ status: 'idle' });
  }

  search = async (query: string) => {
    const reqId = ++this.requestId;
    // Abort the previous in-flight request, if any.
    this.controller?.abort();
    const controller = new AbortController();
    this.controller = controller;

    this.emit({ status: 'loading' });

    try {
      const res = await fetch(`/api/search?q=${query}`, {
        signal: controller.signal,
      });
      const results = (await res.json()) as Results;
      if (reqId !== this.requestId) return;
      this.emit({ status: 'success', results });
    } catch (e) {
      // An abort surfaces as an AbortError; it isn't a real failure.
      if (e instanceof DOMException && e.name === 'AbortError') return;
      if (reqId !== this.requestId) return;
      this.emit({ status: 'error', message: String(e) });
    }
  };
}
```

Two guards now run together: `AbortController` stops the request (and makes `fetch` reject with an `AbortError` you ignore), while the `requestId` check still protects the emit in case a response was already in transit when the new call started.

### Aborting on disposal

A request in flight when the bloc is disposed will try to `emit` on a dead container, which throws. Wire `onSystemEvent('dispose', …)` to abort the controller so the request unwinds cleanly:

```ts twoslash
import { Cubit } from '@blac/core';
type SearchState = { status: 'idle' | 'loading' };
// ---cut---
class SearchCubit extends Cubit<SearchState> {
  private controller: AbortController | null = null;

  constructor() {
    super({ status: 'idle' });
    this.onSystemEvent('dispose', () => {
      this.controller?.abort();
    });
  }
}
```

`onSystemEvent('dispose', …)` fires when the instance is being torn down (its ref count hit zero, or it was cleared). Aborting there cancels the request, and the `AbortError` branch swallows the rejection — no emit reaches the disposed container. See [System Events](/core/system-events) for the full lifecycle.

:::tip[Guard `$blac.disposed` if you skip the abort]
If you don't use an `AbortController`, an async action that resumes after disposal can still hit a disposed bloc. Either check `this.$blac.disposed` before emitting, or — cleaner — abort on `dispose` as above so the request never resolves into an emit at all.
:::

## See also

- [Patterns & Recipes](/guide/patterns) — the request-id recipe in context, plus hydration-aware loading
- [Cubit](/core/cubit) — `emit` / `patch` / `update`, getters, and the `init` hook
- [useBloc](/react/use-bloc) — `onMount`, `select`, and why there's no `useSyncExternalStore`
- [System Events](/core/system-events) — the `dispose` and `hydrationChanged` lifecycle hooks
- [Best Practices](/guide/best-practices) — why an explicit `status` union beats scattered booleans

---

# Best Practices

> The opinionated do/don't principles for shaping state, choosing input lanes, modeling async work, and avoiding the habits that quietly cause bugs.

Source: /guide/best-practices/

This page is about judgment, not mechanics. It collects the opinionated do/don't principles that keep a BlaC codebase predictable as it grows: how to shape state, how to choose between the input lanes, how to model async work, and which habits quietly cause bugs.

If you want copy-paste recipes for these situations, see [Patterns & Recipes](/guide/patterns) — that page is the concrete how-to. This page is the _why_ behind the choices.

:::tip[How to read this page]
Each section states a principle, gives a one-line rationale, and shows a good-vs-bad pair. The [Anti-patterns](#anti-patterns) section at the end is a quick-reference of the mistakes, each with its fix.
:::

## Cubit vs Bloc: there is only Cubit

**Principle:** reach for `Cubit`. BlaC does not ship a separate `Bloc` class.

If you come from `flutter_bloc`, you may expect two base classes — a `Cubit` you call methods on, and an event-driven `Bloc` you dispatch events to. BlaC has one concrete base: [`Cubit`](/core/cubit), which extends the abstract `StateContainer`. You change state by calling methods that call `emit` / `update` / `patch`. There is no `add(event)` dispatch layer.

```ts
// Good — a method per intent, called directly
class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  increment = () => this.patch({ count: this.state.count + 1 });
  reset = () => this.emit({ count: 0 });
}
```

```ts
// Bad — there is no Bloc class to extend, and no event enum to dispatch
class CounterBloc extends Bloc<CounterState, CounterEvent> {
  /* does not exist */
}
```

If you genuinely want an event-sourced log (every intent recorded as a value before it is reduced), model it explicitly inside a Cubit — keep an `events: Event[]` array in state and a reducer method — rather than looking for a framework `Bloc`. For the lower-level engine that BlaC is built on, see [DirtyTalk](/dirtytalk/).

## State shape: flat, serializable, and free of derived values

**Principle:** state holds the _source of truth_; everything computable from it is a getter, not a stored field.

Two rules keep state honest:

1. **Prefer flat and serializable.** Deeply nested or non-serializable state (class instances, `Map`/`Set`/`Date`, DOM nodes, functions) is harder to diff, harder to persist, and is treated as an opaque leaf by auto-tracking — see [Dependency Tracking](/react/dependency-tracking). `patch` accepts a `DeepPartial<S>` so shallow shapes update cleanly. Deep nesting is supported, but flat shapes are easier to reason about; reach for nesting only when the domain truly is nested.
2. **Never store what you can derive.** A derived value stored in state is a second source of truth you must remember to keep in sync. Expose it as a getter instead — auto-tracking records the state paths the getter reads, and `select` is available when a consumer should wake only when the computed result changes.

```ts
// Good — totals are getters; state has one source of truth
interface CartState {
  items: { id: string; price: number; qty: number }[];
}

class CartCubit extends Cubit<CartState> {
  constructor() {
    super({ items: [] });
  }
  get subtotal() {
    return this.state.items.reduce((sum, i) => sum + i.price * i.qty, 0);
  }
  get itemCount() {
    return this.state.items.length;
  }
}
```

```ts twoslash
// Bad — subtotal/itemCount stored alongside items; every mutation must
// recompute them by hand, and one missed update silently desyncs the UI
interface CartState {
  items: { id: string; price: number; qty: number }[];
  subtotal: number; // derived — do not store
  itemCount: number; // derived — do not store
}
```

:::note[Why getters re-render correctly]
Auto-tracking records the _leaf paths_ a render reads. A getter that reads `this.state.items` is recorded as a dependency on `items`; when `items` changes the getter is re-evaluated and consumers re-render. A getter that no consumer reads costs nothing. See [Patterns & Recipes](/guide/patterns#getter-based-computed-values) for the recipe.
:::

## `args` vs `deps`: the decision rule

**Principle:** put **serializable identity in `args`** and **non-serializable handles in `deps`**. Every instance is keyed from its `args` — there is no separate key input.

This is the single most common source of confusion, so commit the rule to memory:

| You have…                                                                                 | Use                                         | Because                                                                                    |
| ----------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Serializable data that defines _which_ instance (a `userId`, an `endpoint`, a filter set) | **`args`**                                  | Args are hashed into the instance key — same args share one instance, different args fork. |
| A non-serializable handle (a `useRef`, a stable `useCallback`, an external API object)    | **`deps`**                                  | Deps never key identity and are merged per-consumer; the bloc reads them lazily.           |
| An opaque key that isn't real bloc data (a per-mount id, an externally-managed token)     | **a synthetic `args` field + `static key`** | Add the value to `args` (e.g. `_id`) and key on it; nothing else forks the instance.       |

The mechanics of all three live in [Passing Inputs to Blocs](/guide/inputs); this is just the judgment. Note that `deps` is **not** a `useBloc` option — a consumer contributes its slice from a mount effect via the `APPLY_DEPS` / `REMOVE_DEPS_OWNER` handles from `@blac/core` (the examples below import them); see [Wiring deps from a component](/guide/inputs#wiring-deps-from-a-component).

```tsx
// Good — userId is serializable identity (args); inputRef is a handle (deps).
// deps is NOT a useBloc option: wire it from a mount effect (post-commit).
const inputRef = useRef<HTMLInputElement>(null);
const ownerId = useId();
const [state, cubit] = useBloc(UserCardCubit, { args: { userId } });
useEffect(() => {
  cubit[APPLY_DEPS](ownerId, { inputRef });
  return () => cubit[REMOVE_DEPS_OWNER](ownerId);
}, [cubit, inputRef, ownerId]);
```

```tsx
// Bad — a ref in args destabilizes the instance key, forcing a brand-new
// instance on every render (refs are not serializable)
const [state, cubit] = useBloc(UserCardCubit, {
  args: { userId, inputRef }, // inputRef belongs in deps
});
```

:::caution[The inline-callback pitfall]
An inline callback (`onDone={() => save()}`) has a new function identity every render. If you capture it once in `deps`, the bloc holds the **first** closure forever and later calls fire stale logic. Prefer, best first:

1. **Callback inversion** — expose result state from the bloc and let the component invoke its own fresh callback in a `useEffect` (`useEffect(() => { if (doneId) onDone(doneId); }, [doneId, onDone])`).
2. **Stabilize with `useCallback`** before passing into `deps`.
3. **Push via a bloc method from an effect** (`useEffect(() => cubit.setOnDone(cb), [cb])`).

See the full treatment in [Passing Inputs to Blocs](/guide/inputs#the-callback-staleness-gotcha).
:::

### Per-component private instances

When a component needs its _own_ instance with its own lifecycle (disposed on unmount), add a per-mount unique value to `args` keyed by React's `useId()` and select it with `static key` — each mount gets a fresh private instance.

```ts
// Good — a synthetic `_id` keys the instance; endpoint rides along as config
class FileUploadCubit extends Cubit<
  UploadState,
  { endpoint: string; _id: string }
> {
  static key = (a: FileUploadCubit['args']) => a._id;
  constructor() {
    super({ status: 'idle', progress: 0 });
  }
  protected init(args: { endpoint: string; _id: string }) {
    this.endpoint = args.endpoint;
  }
}
```

```tsx
// Each FileUpload mount owns a private instance
const _id = useId();
const [state, upload] = useBloc(FileUploadCubit, { args: { endpoint, _id } });
```

:::tip[One source of per-mount identity]
`useId()` returns a stable-per-mount value, so keying on it gives each mount a private instance that lives and dies with it. For _named_ sections that should share an instance by name (e.g. `"billing"` vs `"shipping"` form sections), make that name a real `args` field and key on it the same way. See [Instance Management](/core/instance-management) for the registry mechanics.
:::

## Async, loading, and error state

**Principle:** model async outcomes as explicit state, guard against stale responses, and never block `init`.

### Make status a value, not a guess

Don't infer "loading" from `data === null`. Hold an explicit status so the UI can distinguish _never loaded_, _loading_, _error_, and _empty success_.

```ts
// Good — explicit, exhaustive status
interface FeedState {
  articles: Article[];
  status: 'idle' | 'loading' | 'error' | 'success';
  error: string | null;
}
```

```ts
// Bad — overloaded null forces the UI to guess
interface FeedState {
  articles: Article[] | null; // null = loading? error? empty? unknown.
}
```

### Guard against overlapping requests

Two in-flight loads can resolve out of order and clobber each other. A monotonic request id is simpler than `AbortController` and ignores stale responses:

```ts
class FeedCubit extends Cubit<FeedState> {
  private requestId = 0;
  constructor() {
    super({ articles: [], status: 'idle', error: null });
  }
  load = async (category: string) => {
    const id = ++this.requestId;
    this.patch({ status: 'loading', error: null });
    try {
      const articles = await api.fetch(category);
      if (id !== this.requestId) return; // a newer load superseded us
      this.emit({ articles, status: 'success', error: null });
    } catch (e) {
      if (id !== this.requestId) return;
      this.patch({ status: 'error', error: String(e) });
    }
  };
}
```

### Don't block in `init`

`init(args)` runs **once, synchronously, before the first state snapshot** — so consumers get correct initial state with no flash. That makes it the wrong place to `await`. Kick the async work off (fire-and-forget) from `init` and let the loading status carry the rest.

```ts
// Good — init seeds sync state and starts the load; it does not await
class UserCubit extends Cubit<UserState, { userId: string }> {
  protected init(args: { userId: string }) {
    void this.load(args.userId); // returns immediately; status shows 'loading'
  }
}
```

```ts
// Bad — init cannot be awaited by the framework; consumers render before
// this resolves, and an unawaited rejection is swallowed
class UserCubit extends Cubit<UserState, { userId: string }> {
  protected async init(args: { userId: string }) {
    this.emit(await api.fetchUser(args.userId)); // blocks nothing useful
  }
}
```

:::tip[Hydrating from storage]
If state arrives asynchronously from the persistence plugin, await `this.$blac.hydration.wait()` inside a fire-and-forget `init` before touching the network, so you don't overwrite restored values. See [Persistence](/plugins/persistence) and the [hydration-aware loading recipe](/guide/patterns#hydration-aware-loading).
:::

## Cross-bloc dependencies: `this.depend`, and avoid cycles

**Principle:** declare cross-bloc reads with `this.depend(Other)`; keep the dependency graph a DAG.

`this.depend(OtherCubit)` returns a handle that resolves the dependency from the registry on each call. Use `.untracked()` to _read_ another bloc's state inside a getter or to _call_ its methods, and `.track()` when the read should re-render the consumer (below).

```ts
// Good — CartCubit depends on ShippingCubit, one direction only
class CartCubit extends Cubit<CartState> {
  private shipping = this.depend(ShippingCubit);
  get total() {
    return this.subtotal + this.shipping.untracked().state.rate;
  }
}
```

```ts
// Bad — a cycle: Cart depends on Shipping AND Shipping depends on Cart.
// Reading total now risks infinite recursion, and disposal order is undefined.
class ShippingCubit extends Cubit<ShippingState> {
  private cart = this.depend(CartCubit); // closes the loop — don't
}
```

:::caution[Two gotchas with `depend`]

- **`depend` resolves via `ensure`, which does not hold a reference.** A depended-on bloc can be disposed out from under you if nothing else keeps it alive. For app-wide collaborators, mark the dependency `@blac({ keepAlive: true })`.
- **Reading a dependency's state in a constructor is unsafe** — it may not be initialized yet. Read it lazily inside a method or getter, where the getter resolves it on demand.
- **`.untracked()` reads and method calls do not subscribe you.** They give you access, not reactivity. Cross-bloc re-render tracking is opt-in via `.track()` (below); a plain `.untracked()` read only updates if the consumer also subscribes via `useBloc`.

See [Bloc Communication](/core/bloc-communication) for the full lifecycle picture.
:::

**Reach for `.track()` when the cross-bloc read needs to be reactive.** Plain `this.shipping.untracked().state.rate` is a live but _untracked_ read — the consumer only re-renders if it independently subscribes to the dependency. When a getter genuinely derives from another bloc and components should update on its changes, call `.track()` on the handle (`const [shipping] = this.shipping.track()`) instead of duplicating `useBloc(Other)` across every consumer. Keep `.untracked()` for one-off reads and method invocations where you don't want a subscription.

```ts
// Good — the derivation declares its own reactivity; consumers stay simple.
class CartCubit extends Cubit<CartState> {
  private shipping = this.depend(ShippingCubit);
  get total() {
    const [shipping] = this.shipping.track();
    return this.subtotal + shipping.rate;
  }
}
```

This keeps the dependency graph in the blocs (where it's testable) rather than scattering coordinating `useBloc` calls through the view. See [Auto-tracking with `.track()`](/core/bloc-communication#auto-tracking-with-track).

If you find two blocs reaching into each other, that is usually a sign the shared concern belongs in a third bloc both depend on, or that the two should be one. Cross-bloc coupling is a smell worth questioning, not a tool to reach for first.

## Keep components dumb

**Principle:** components read tracked state and call methods. They should not hold derived logic, mutate state, or own business rules.

A component's job is to render the current state and forward intent. Put the _what_ in the bloc (methods, getters) and leave the _how it looks_ in the component. This keeps logic testable without a DOM and keeps re-renders precise.

```tsx
// Good — reads a getter, calls a method; no logic in the view
function CartSummary() {
  const [, cart] = useBloc(CartCubit);
  return (
    <footer>
      <span>{cart.itemCount} items</span>
      <strong>${cart.total.toFixed(2)}</strong>
      <button onClick={cart.checkout}>Checkout</button>
    </footer>
  );
}
```

```tsx
// Bad — totals computed in the view (duplicating bloc logic), and the
// button mutates state through the bloc instance directly
function CartSummary() {
  const [state, cart] = useBloc(CartCubit);
  const total = state.items.reduce((s, i) => s + i.price * i.qty, 0); // belongs in a getter
  return (
    <footer>
      <strong>${total.toFixed(2)}</strong>
      <button onClick={() => (cart.state.items = [])}>Clear</button>{' '}
      {/* never mutate */}
    </footer>
  );
}
```

:::tip[Action-only components]
A component that only triggers actions and never displays state does not need a selector. Do not read from `state`, and auto-tracking records nothing to wake:

```tsx
function QuickAdd() {
  const [, todo] = useBloc(TodoCubit);
  return <button onClick={() => todo.addItem('New')}>Add</button>;
}
```

The deeper performance rationale lives in [Performance](/react/performance).
:::

## Testing mindset

**Principle:** test blocs as plain classes; test components against the registry. Isolate every test.

Because logic lives in the bloc and components stay dumb, most behavior is testable without React — instantiate the Cubit, call methods, assert on `state` and getters. Component tests then verify wiring against an isolated registry so instances never leak between tests.

```ts
// Good — pure bloc test, no DOM
const cart = new CartCubit();
cart.addItem({ id: 'a', price: 10, qty: 2 });
expect(cart.subtotal).toBe(20);
```

Design blocs to be easy to test: deterministic methods, injectable collaborators via `depend`, and no hidden global reads. The full toolkit (registry isolation, stubs, overrides, flushing async updates) is in [Testing Overview](/testing/overview).

## Anti-patterns

A quick-reference of habits to drop, each with the fix. Many of these have a symptom-first entry in [Troubleshooting](/guide/troubleshooting).

### Mutating state in place

Assigning to `this.state.x` (or pushing into an array on `this.state`) bypasses change detection — no diff is computed, no consumer wakes.

```ts
// Bad
this.state.items.push(item);

// Fix — produce a new value through a mutation method
this.patch({ items: [...this.state.items, item] });
```

### Storing derived state

A computed value duplicated into state is a second source of truth that drifts.

```ts
// Bad — total stored and hand-maintained
this.patch({ items: next, total: recompute(next) });

// Fix — expose a getter, store only the source
get total() { return this.state.items.reduce(/* ... */); }
```

### Threading identity outside `args`

When the distinguishing value is _meaningful data_ (a `userId`, a `docId`), it belongs in `args` — args both key the instance and seed `init()` in one step. Don't invent a parallel key channel.

```tsx
// Bad — passing userId as a bare positional/extra arg, separate from args
const [s] = useBloc(UserCardCubit, userId);

// Fix — args key the instance AND seed init() in one step
const [s] = useBloc(UserCardCubit, { args: { userId } });
```

For keys that aren't real bloc data — named sections (`"billing"` / `"shipping"`), externally-supplied ids, or a per-mount `useId()` — add the value as an `args` field and key on it with `static key`. There is no separate `instanceId` channel.

### Raw inline callbacks in `deps`

An inline arrow captured into `deps` freezes the first render's closure.

```tsx
// Bad — new identity each render contributed as a dep; bloc keeps the stale one
useEffect(() => {
  cubit[APPLY_DEPS](ownerId, { onDone: () => save(id) });
}, [cubit, ownerId, id]);

// Fix — invert: expose result state, call your own callback in an effect
const [{ doneId }] = useBloc(UploadCubit, { args });
useEffect(() => {
  if (doneId) onDone(doneId);
}, [doneId, onDone]);
```

### Non-serializable values in `args`

Refs, callbacks, class instances, and `Date`/`Map`/`Set` in `args` produce an unstable instance key — a new instance every render.

```tsx
// Bad — ref in args re-keys the instance on every render
useBloc(UploadCubit, { args: { endpoint, inputRef } });

// Fix — handles go in the deps lane, wired from an effect (not a useBloc option)
const [, cubit] = useBloc(UploadCubit, { args: { endpoint } });
useEffect(() => {
  cubit[APPLY_DEPS](ownerId, { inputRef });
  return () => cubit[REMOVE_DEPS_OWNER](ownerId);
}, [cubit, inputRef, ownerId]);
```

### Opting out of tracking when you don't need to

Reaching for `select` "to be safe" trades automatic, leaf-precise tracking for a hand-maintained dependency array you must keep in sync. Auto-tracking is the default for a reason.

```tsx
// Bad — manual select that you must remember to update when the view reads more
const [s] = useBloc(TodoCubit, { select: (s) => [s.items] });

// Fix — let auto-tracking record exactly what this render reads
const [s] = useBloc(TodoCubit);
```

Use `select` deliberately: to opt a writer-only component _out_ of all re-renders (`() => []`), or to narrow re-renders to a specific computed slice when profiling shows it matters — not as a default. A `select` function must also be referentially stable (wrap it in `useCallback`), or a fresh function each render re-keys the subscription.

## See also

- [Passing Inputs to Blocs](/guide/inputs) — the mechanics of `args` and `deps`
- [Patterns & Recipes](/guide/patterns) — concrete copy-paste recipes for these principles
- [Performance](/react/performance) — re-render mechanics and the cost model
- [Troubleshooting](/guide/troubleshooting) — symptom-first fixes for the anti-patterns above

---

# Coming from flutter_bloc

> How the flutter_bloc mental model maps onto BlaC, with concept mappings and a side-by-side counter port from Dart to TypeScript.

Source: /guide/coming-from-flutter-bloc/

BlaC is a direct descendant of flutter*bloc. The name is not a coincidence: \_Business Logic Components*
is the Flutter pattern, and BlaC carries the same core idea — a class owns a slice of logic and emits
state — from Dart into TypeScript. If you have shipped flutter_bloc apps, most of the mental model
travels straight across. What changes is idiomatic Dart vs idiomatic TypeScript, and the React binding
layer.

## Concept mapping

| flutter_bloc term    | BlaC term                                           | Notes                                                                 |
| -------------------- | --------------------------------------------------- | --------------------------------------------------------------------- |
| `Cubit<S>`           | `Cubit<S>`                                          | Same name, same idea: extend, set initial state, expose methods       |
| `Bloc<E, S>`         | `Cubit<S>` (no event class)                         | BlaC drops the `Bloc` event layer; methods _are_ the events           |
| `emit(state)`        | `this.emit(state)` / `this.patch` / `this.update`   | Same concept; BlaC adds `patch` (deep-merge) and `update` (derive)    |
| `BlocProvider`       | Registry (automatic)                                | No provider tree — instances are shared via a ref-counted registry    |
| `BlocBuilder`        | `useBloc` hook                                      | Returns `[state, bloc]`; re-renders are auto-tracked, not `buildWhen` |
| `BlocListener`       | `useBloc` + `onMount` / `watch`                     | Side-effects in an effect or a `watch` subscription outside React     |
| `BlocConsumer`       | `useBloc` (both roles in one hook)                  | State read + method call in the same component                        |
| `MultiBlocProvider`  | Nothing — just call multiple `useBloc` calls        | No setup needed; each hook acquires its own instance                  |
| `context.read<T>()`  | `useBloc(T)` (or `borrow` / `ensure` outside React) | Registry lookup by class, not Flutter `BuildContext`                  |
| `context.watch<T>()` | `useBloc(T)` (auto-tracks what you read)            | Every `useBloc` is implicitly a "watch"                               |
| `buildWhen`          | `select` option on `useBloc`                        | `select: (s, b) => [s.field]` — re-render only when array changes     |
| `RepositoryProvider` | `Cubit` with `@blac({ keepAlive: true })`           | Or pass a service as a constructor arg; no separate "repository" type |
| `HydratedBloc`       | Persistence plugin (`@blac/plugin-persist`)         | Uses IndexedDB by default; swap adapter for React Native / other      |

## The `Bloc` event layer does not exist in BlaC

flutter_bloc ships two classes: `Cubit` (methods you call) and `Bloc` (events you dispatch, handlers you
register). BlaC only has `Cubit`. If you used flutter's `Bloc` class, translate each `on<Event>` handler
to a method:

```dart
// flutter_bloc — Bloc variant
class CounterBloc extends Bloc<CounterEvent, int> {
  CounterBloc() : super(0) {
    on<IncrementEvent>((event, emit) => emit(state + 1));
    on<DecrementEvent>((event, emit) => emit(state - 1));
  }
}
```

```ts twoslash
import { Cubit } from '@blac/core';
// ---cut---
class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  increment = () => this.emit({ count: this.state.count + 1 });
  decrement = () => this.emit({ count: this.state.count - 1 });
}
```

The method _is_ the event. There is no event class, no dispatch, no `add()`. You call the method directly.
This is identical to flutter_bloc's `Cubit` half.

## Side-by-side port: a counter app

**flutter_bloc**

```dart
// cubit
class CounterCubit extends Cubit<int> {
  CounterCubit() : super(0);
  void increment() => emit(state + 1);
  void decrement() => emit(state - 1);
}

// widget tree
class CounterPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (_) => CounterCubit(),
      child: const CounterView(),
    );
  }
}

class CounterView extends StatelessWidget {
  const CounterView({super.key});

  @override
  Widget build(BuildContext context) {
    final count = context.watch<CounterCubit>().state;
    return Column(
      children: [
        Text('$count'),
        ElevatedButton(
          onPressed: () => context.read<CounterCubit>().increment(),
          child: const Text('+'),
        ),
        ElevatedButton(
          onPressed: () => context.read<CounterCubit>().decrement(),
          child: const Text('-'),
        ),
      ],
    );
  }
}
```

**BlaC**

```ts twoslash
import { Cubit } from '@blac/core';
// ---cut---
class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  increment = () => this.emit({ count: this.state.count + 1 });
  decrement = () => this.emit({ count: this.state.count - 1 });
}
```

```tsx
import { useBloc } from '@blac/react';

function Counter() {
  const [state, counter] = useBloc(CounterCubit);
  return (
    <div>
      <p>{state.count}</p>
      <button onClick={counter.increment}>+</button>
      <button onClick={counter.decrement}>-</button>
    </div>
  );
}
```

What changed:

- No `BlocProvider` wrapping the tree — the registry handles instance sharing.
- No `context.watch` / `context.read` split — `useBloc` is both.
- State is an object, not a raw int (TypeScript patterns favour typed objects).
- `buildWhen` is not needed; BlaC auto-tracks which fields the component reads.

## Provider tree → registry

In flutter_bloc you place a `BlocProvider` in the widget tree so descendants can look up the Cubit via
`context`. BlaC has no equivalent provider. The registry is a global singleton keyed on the class itself.
Two calls to `useBloc(CounterCubit)` always return the same instance, regardless of where in the React
tree they sit.

For scoped instances — an editor with per-document state — make the scoping value part of `args`
instead of using a wrapping provider:

```tsx
class EditorCubit extends Cubit<EditorState, { docId: string }> {
  static key = (a: EditorCubit['args']) => a.docId;
}

function Editor({ docId }: { docId: string }) {
  const [state, editor] = useBloc(EditorCubit, { args: { docId } });
  // ...
}
```

Each `docId` gets an independent `EditorCubit`. When all components using that `docId` unmount,
the instance is disposed automatically (same ref-counting lifecycle as flutter_bloc's `BlocProvider`
`create` + `close`).

## `BlocBuilder` → `useBloc`

flutter_bloc's `BlocBuilder` drives a rebuild with `buildWhen`; `BlocConsumer` adds a `listener` for
side effects. BlaC rolls both into one hook:

```dart
// flutter_bloc
BlocConsumer<WeatherCubit, WeatherState>(
  listenWhen: (prev, curr) => prev.status != curr.status,
  listener: (context, state) {
    if (state.status == WeatherStatus.failure) {
      ScaffoldMessenger.of(context).showSnackBar(/*...*/);
    }
  },
  buildWhen: (prev, curr) => prev.temperature != curr.temperature,
  builder: (context, state) => Text('${state.temperature}°'),
)
```

```tsx
import { useBloc } from '@blac/react';
import { useEffect } from 'react';

function WeatherDisplay() {
  const [state] = useBloc(WeatherCubit, {
    // re-render only when temperature changes
    select: (s) => [s.temperature],
    onMount: (bloc) => {
      // side effects on mount
    },
  });

  useEffect(() => {
    if (state.status === 'failure') {
      showSnackBar('Weather load failed');
    }
  }, [state.status]);

  return <p>{state.temperature}°</p>;
}
```

The `select` option replaces `buildWhen` (re-render when the returned array changes). Status side-effects
go in a plain `useEffect`. For global, non-React listeners, use `watch`:

```ts twoslash
import { Cubit } from '@blac/core';
import { watch } from '@blac/core';

class WeatherCubit extends Cubit<{ status: string; temperature: number }> {
  constructor() {
    super({ status: 'idle', temperature: 0 });
  }
}
// ---cut---
const unwatch = watch(WeatherCubit, (bloc) => {
  console.log('new temp:', bloc.state.temperature);
});
// call unwatch() to stop
```

## State shape: primitives vs objects

flutter_bloc commonly uses plain Dart primitives as state (`Cubit<int>`, `Cubit<bool>`) or sealed
classes. BlaC state is always an object literal in practice — TypeScript works best with typed record
shapes, and `patch` only makes sense on an object:

```ts twoslash
import { Cubit } from '@blac/core';
// ---cut---
// Prefer a typed object over a raw primitive
class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  increment = () => this.emit({ count: this.state.count + 1 });
}
```

For discriminated-union state (the Dart sealed-class pattern), use a TypeScript union type. The view
switches on `state.status` and TypeScript narrows each branch — same ergonomics as Dart `when`:

```ts twoslash
import { Cubit } from '@blac/core';

declare const api: {
  fetchUser(id: string): Promise<{ id: string; name: string }>;
};
// ---cut---
type UserState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; user: { id: string; name: string } }
  | { status: 'error'; message: string };

class UserCubit extends Cubit<UserState> {
  constructor() {
    super({ status: 'idle' });
  }

  load = async (id: string) => {
    this.emit({ status: 'loading' });
    try {
      const user = await api.fetchUser(id);
      this.emit({ status: 'success', user });
    } catch (e) {
      this.emit({ status: 'error', message: String(e) });
    }
  };
}
```

## Persistence: `HydratedBloc` → persist plugin

flutter_bloc ships `HydratedBloc`/`HydratedCubit` for local persistence. BlaC has a first-party plugin:

```ts
import { createIndexedDbPersistPlugin } from '@blac/plugin-persist';
import { getPluginManager } from '@blac/core';

const persist = createIndexedDbPersistPlugin();
getPluginManager().install(persist);
```

The persist plugin saves and restores state via IndexedDB. For React Native, swap the storage adapter
(the plugin ships an interface; pass an AsyncStorage-backed adapter). See [Persistence](/plugins/persistence).

## Mental-model shift

| flutter_bloc                           | BlaC                                                     |
| -------------------------------------- | -------------------------------------------------------- |
| Tree = provider scoping mechanism      | Registry = global, class-keyed, ref-counted              |
| `context` carries bloc references      | Import the class; the registry finds the instance        |
| `BlocBuilder` re-builds on `buildWhen` | `useBloc` re-renders on auto-tracked read paths          |
| `BlocListener` for side effects        | `useEffect` on state values, or `watch` outside React    |
| `close()` called by `BlocProvider`     | `release()` / ref-count-zero triggers automatic disposal |
| Event objects for `Bloc` class         | Method calls — no dispatch, no `add()`                   |

If you used `Cubit` in Flutter (not the full `Bloc` event layer), migrating to BlaC is mostly syntax
translation. If you used `Bloc` events, collapse each `on<Event>` handler into a method.

## See also

- [Core Concepts](/guide/concepts) — state containers, registry, dependency tracking
- [Comparison](/guide/comparison) — BlaC vs Zustand vs Jotai, including the flutter_bloc lineage
- [useBloc](/react/use-bloc) — full hook reference with `args`, `select`, `onMount`
- [Async](/guide/async) — async methods, status unions, cancellation
- [Persistence](/plugins/persistence) — the persist plugin and storage adapters

---

# Coming from Redux (Toolkit)

> How each Redux Toolkit primitive maps onto BlaC, with a full side-by-side todo-list port and notes on when to stay with Redux.

Source: /guide/coming-from-redux/

Redux and BlaC share the same design principle: a single source of truth per concern, immutable state
updates, and first-party DevTools support. The difference is in the mechanism. Redux routes every mutation
through a dispatcher and a reducer; BlaC routes it through a method on a class. The result is less
indirection, less boilerplate, and auto-tracked re-renders — but the tradeoff is giving up Redux's strict,
serializable action log.

If you use Redux Toolkit today, this page maps each RTK primitive to its BlaC equivalent and walks
through a full side-by-side port.

## Concept mapping

| Redux / RTK term                | BlaC term                                                       | Notes                                                                       |
| ------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `createSlice({ name, ... })`    | `class MyCubit extends Cubit<S>`                                | The class is the slice: state type, initial state, and mutations in one     |
| `initialState`                  | `super(initialState)` in the constructor                        | Passed to the parent class                                                  |
| `reducers: { action: fn }`      | Method on the class                                             | `action(payload)` is the combined action-creator + reducer                  |
| `createAsyncThunk`              | `async` method on the class                                     | No thunk factory; just `async method = async () => { ... }`                 |
| `extraReducers` / `builder`     | Additional methods or `onSystemEvent`                           | No separate builder step; add more methods to the class                     |
| `dispatch(action())`            | `cubit.method(args)` / `bloc.method(args)`                      | Call the method directly; no dispatcher                                     |
| `useSelector((s) => s.slice.x)` | `useBloc(MyCubit)` reading `state.x`                            | No selector written; the read during render _is_ the subscription           |
| `useDispatch()`                 | Second element of `useBloc` tuple                               | `const [state, cubit] = useBloc(MyCubit); cubit.method()`                   |
| `configureStore({ reducer })`   | Registry (automatic)                                            | No store setup; instances live in the global ref-counted registry           |
| `Provider` wrapping the app     | Nothing — registry is implicit                                  | No provider needed                                                          |
| `createEntityAdapter`           | Class with typed state + methods                                | Model a collection as `items: Record<id, T>` in the state object            |
| `RTK Query`                     | Async method + status union                                     | BlaC does not ship a query layer; see [Async](/guide/async) for the pattern |
| Redux DevTools                  | `@blac/devtools-connect` plugin                                 | First-party; inspects every Cubit, time-travel, state diff                  |
| Middleware                      | Plugins (`@blac/devtools-connect`, `@blac/plugin-persist`, ...) | Installed once globally; observe all Cubits                                 |

## The dispatch/reducer indirection does not exist in BlaC

RTK's slice defines reducers keyed by action type; `dispatch` routes incoming action objects to the
matching reducer. BlaC removes the intermediary. The action name _is_ the method name; the reducer _is_
the method body; and calling the method _is_ the dispatch. One step instead of three.

```ts
// RTK — three artifacts per mutation
const counterSlice = createSlice({
  name: 'counter',
  initialState: { value: 0 },
  reducers: {
    increment: (state) => {
      state.value += 1;
    }, // reducer
    incrementByAmount: (state, action) => {
      state.value += action.payload; // reducer + payload type
    },
  },
});
export const { increment, incrementByAmount } = counterSlice.actions; // action creators
export default counterSlice.reducer;
```

```ts twoslash
import { Cubit } from '@blac/core';
// ---cut---
// BlaC — one artifact
class CounterCubit extends Cubit<{ value: number }> {
  constructor() {
    super({ value: 0 });
  }
  increment = () => this.emit({ value: this.state.value + 1 });
  incrementByAmount = (amount: number) =>
    this.emit({ value: this.state.value + amount });
}
```

No separate file for actions. No `export const { ... }`. No `reducer` export to wire into a store.

## Immutable updates: Immer vs BlaC

RTK ships Immer so reducers can write `state.value += 1` (mutable syntax compiled to immutable
updates). BlaC state is always immutable: `emit(next)` and `update(fn)` replace the whole state
object, and `patch(partial)` deep-merges a partial. You never mutate `this.state` in place:

```ts twoslash
import { Cubit } from '@blac/core';

interface Item {
  id: string;
  name: string;
}
// ---cut---
// RTK would let you write: state.items.push(item)
// BlaC — always return a new value
class ListCubit extends Cubit<{ items: Item[] }> {
  constructor() {
    super({ items: [] });
  }

  add = (item: Item) => this.patch({ items: [...this.state.items, item] });

  remove = (id: string) =>
    this.patch({ items: this.state.items.filter((i) => i.id !== id) });
}
```

`patch` deep-merges, so you only mention the key you are changing. `emit` and `update` replace the
whole state — list every key, or spread the previous state.

## Side-by-side port: a todo list

**Redux Toolkit**

```ts
// slice
import { createSlice, PayloadAction } from '@reduxjs/toolkit';

interface TodoItem {
  id: number;
  text: string;
  completed: boolean;
}
interface TodoState {
  items: TodoItem[];
  nextId: number;
}

const todoSlice = createSlice({
  name: 'todos',
  initialState: { items: [], nextId: 1 } as TodoState,
  reducers: {
    addTodo: (state, action: PayloadAction<string>) => {
      state.items.push({
        id: state.nextId++,
        text: action.payload,
        completed: false,
      });
    },
    toggleTodo: (state, action: PayloadAction<number>) => {
      const todo = state.items.find((t) => t.id === action.payload);
      if (todo) todo.completed = !todo.completed;
    },
    removeTodo: (state, action: PayloadAction<number>) => {
      state.items = state.items.filter((t) => t.id !== action.payload);
    },
  },
});

export const { addTodo, toggleTodo, removeTodo } = todoSlice.actions;
export default todoSlice.reducer;
```

```tsx
// component
import { useSelector, useDispatch } from 'react-redux';

function TodoList() {
  const items = useSelector((s: RootState) => s.todos.items);
  const dispatch = useDispatch();
  return (
    <ul>
      {items.map((t) => (
        <li key={t.id}>
          <input
            type="checkbox"
            checked={t.completed}
            onChange={() => dispatch(toggleTodo(t.id))}
          />
          {t.text}
          <button onClick={() => dispatch(removeTodo(t.id))}>x</button>
        </li>
      ))}
    </ul>
  );
}
```

**BlaC**

```ts twoslash
import { Cubit } from '@blac/core';
// ---cut---
interface TodoItem {
  id: number;
  text: string;
  completed: boolean;
}

class TodoCubit extends Cubit<{ items: TodoItem[]; nextId: number }> {
  constructor() {
    super({ items: [], nextId: 1 });
  }

  addTodo = (text: string) => {
    const { items, nextId } = this.state;
    this.emit({
      items: [...items, { id: nextId, text, completed: false }],
      nextId: nextId + 1,
    });
  };

  toggleTodo = (id: number) =>
    this.patch({
      items: this.state.items.map((t) =>
        t.id === id ? { ...t, completed: !t.completed } : t,
      ),
    });

  removeTodo = (id: number) =>
    this.patch({ items: this.state.items.filter((t) => t.id !== id) });
}
```

```tsx
import { useBloc } from '@blac/react';

function TodoList() {
  const [state, todos] = useBloc(TodoCubit);
  return (
    <ul>
      {state.items.map((t) => (
        <li key={t.id}>
          <input
            type="checkbox"
            checked={t.completed}
            onChange={() => todos.toggleTodo(t.id)}
          />
          {t.text}
          <button onClick={() => todos.removeTodo(t.id)}>x</button>
        </li>
      ))}
    </ul>
  );
}
```

What changed:

- No `createSlice`, no `PayloadAction`, no action-creator exports.
- No `configureStore`, no `Provider`, no `RootState` type.
- `useSelector` + `useDispatch` collapse into a single `useBloc` call.
- Re-renders are auto-tracked: `TodoList` wakes only when `items` changes (not when `nextId` does).

## Async: `createAsyncThunk` → async method

RTK's thunk factory adds a lifecycle (`pending` / `fulfilled` / `rejected`) dispatched as separate
action objects. BlaC async is a plain `async` method that calls `emit` as it goes:

```ts
// RTK
export const fetchUser = createAsyncThunk('user/fetch', async (id: string) => {
  const response = await api.fetchUser(id);
  return response.data;
});

const userSlice = createSlice({
  name: 'user',
  initialState: { status: 'idle', user: null, error: null },
  reducers: {},
  extraReducers: (builder) => {
    builder
      .addCase(fetchUser.pending, (state) => {
        state.status = 'loading';
      })
      .addCase(fetchUser.fulfilled, (state, action) => {
        state.status = 'success';
        state.user = action.payload;
      })
      .addCase(fetchUser.rejected, (state, action) => {
        state.status = 'error';
        state.error = action.error.message ?? null;
      });
  },
});
```

```ts twoslash
import { Cubit } from '@blac/core';

interface User {
  id: string;
  name: string;
}
declare const api: { fetchUser(id: string): Promise<User> };
// ---cut---
type UserState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; user: User }
  | { status: 'error'; message: string };

class UserCubit extends Cubit<UserState> {
  private requestId = 0;

  constructor() {
    super({ status: 'idle' });
  }

  fetchUser = async (id: string) => {
    const reqId = ++this.requestId;
    this.emit({ status: 'loading' });
    try {
      const user = await api.fetchUser(id);
      if (reqId !== this.requestId) return;
      this.emit({ status: 'success', user });
    } catch (e) {
      if (reqId !== this.requestId) return;
      this.emit({ status: 'error', message: String(e) });
    }
  };
}
```

The `requestId` guard replaces RTK's thunk cancellation — a newer call wins and the older one drops
its result. No `AbortController` needed for this pattern, though BlaC supports it too.

## Selectors → auto-tracked reads

RTK encourages `createSelector` (Reselect) to derive and memoize values from the store:

```ts
// RTK + Reselect
export const selectTotal = createSelector(
  (s: RootState) => s.cart.items,
  (items) => items.reduce((sum, i) => sum + i.price * i.qty, 0),
);
```

BlaC derives values in a getter on the class. Auto-tracking records the getter's underlying reads, so
a component can read `cart.total` and stay subscribed to the source paths without a separate selector:

```ts twoslash
import { Cubit } from '@blac/core';

interface CartItem {
  id: string;
  price: number;
  qty: number;
}
// ---cut---
class CartCubit extends Cubit<{ items: CartItem[] }> {
  constructor() {
    super({ items: [] });
  }

  get total() {
    return this.state.items.reduce((sum, i) => sum + i.price * i.qty, 0);
  }
}
```

A component that reads `cart.total` during render re-renders when the getter's source paths change — no memoization layer, no Reselect import. Use `select` if the computed total itself should gate re-renders.

## DevTools

Redux DevTools is the standard time-travel inspector for Redux and RTK. BlaC ships `@blac/devtools-connect`
as a first-party plugin:

```ts
import { getPluginManager } from '@blac/core';
import { createDevToolsBrowserPlugin } from '@blac/devtools-connect';

getPluginManager().install(createDevToolsBrowserPlugin(), {
  environment: 'development',
});
```

The plugin shows every Cubit's state changes, diffs, and method calls in the same Redux DevTools panel.
State is diffed at the field level; you can step forward and backward through mutations.

## Store setup: `configureStore` → nothing

RTK requires a `configureStore` call to wire reducers, and a `Provider` at the tree root:

```tsx
// RTK setup
const store = configureStore({
  reducer: { counter: counterSlice.reducer, todos: todoSlice.reducer },
});

function App() {
  return (
    <Provider store={store}>
      <Counter />
      <TodoList />
    </Provider>
  );
}
```

BlaC has no equivalent. The registry is global, implicit, and automatic. Components call `useBloc` and
the registry creates instances on first use, shares them, and disposes them when the last consumer
unmounts. No bootstrap, no provider tree.

## When to stay with Redux

Redux's strict serializable action log is a genuine architectural choice, not just boilerplate. Reach
for it when:

- Your team needs a comprehensive audit trail of every state transition (e.g. regulated industries,
  complex undo/redo flows over many slices).
- You have large-team conventions and tooling already built around RTK (code generators, lint rules,
  saga/observable middleware).
- RTK Query is doing meaningful work for you (caching, deduplication, polling).

For most product apps where "I need shared, testable state logic" is the driver, BlaC removes the
ceremony without removing the testability or the DevTools story.

## Mental-model shift

| Redux / RTK                          | BlaC                                                     |
| ------------------------------------ | -------------------------------------------------------- |
| `createSlice` + `configureStore`     | `class MyCubit extends Cubit<S>` (no setup step)         |
| `dispatch(action(payload))`          | `cubit.method(payload)` — direct call                    |
| Reducer handles one action type      | Method _is_ the reducer                                  |
| `useSelector((s) => ...)` per hook   | Auto-tracked read during render — no selector written    |
| `useDispatch()` + action-creator     | Second element of `useBloc` tuple                        |
| `Provider` wraps the app             | No provider — registry is implicit                       |
| `createAsyncThunk` + `extraReducers` | `async method` with inline `emit` calls                  |
| Reselect / `createSelector`          | Getter on the class; no memoization layer needed         |
| Middleware chain                     | Plugin list installed once globally                      |
| Single global store                  | Many independent Cubits; each ref-counted, auto-disposed |

## See also

- [Comparison](/guide/comparison) — BlaC vs Zustand vs Jotai, with Redux in the honest-comparisons table
- [Core Concepts](/guide/concepts) — state containers, registry, dependency tracking
- [useBloc](/react/use-bloc) — full hook reference with `args`, `select`, `onMount`
- [Async](/guide/async) — async methods, status unions, cancellation, and why BlaC skips Suspense
- [DevTools](/plugins/devtools) — first-party BlaC DevTools plugin

---

# Coming from Zustand

> How Zustand's no-provider store maps onto BlaC, where logic lives, how re-renders are scoped, and a side-by-side bear-counter port.

Source: /guide/coming-from-zustand/

Zustand and BlaC share the same "no provider" philosophy and a minimal surface area. The divergence is in
_where logic lives_ (a closure vs a class), _how re-renders are scoped_ (an explicit selector vs
auto-tracked read paths), and _what you get for free as complexity grows_ (a flat store vs a typed unit
you can test in isolation).

If you are comfortable with Zustand but find yourself writing many selectors, leaking logic into
components, or struggling to test state mutations, BlaC is a natural next step.

## Concept mapping

| Zustand term                       | BlaC term                                                              | Notes                                                               |
| ---------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `create((set, get) => ...)`        | `class MyCubit extends Cubit<S>`                                       | Logic lives in the class body instead of a closure                  |
| `set(partial)`                     | `this.patch(partial)` / `this.emit(next)`                              | `patch` deep-merges; `emit` replaces                                |
| `get()`                            | `this.state`                                                           | Read current state from the instance property                       |
| `useStore(selector)`               | `useBloc(MyCubit)` + auto-tracked `state`                              | No selector needed; tracking is inferred from what the render reads |
| `useStore((s) => s.count)`         | `useBloc(MyCubit)` reading `state.count`                               | Reading `state.count` in render _is_ the subscription               |
| Middleware (`devtools`, `persist`) | First-party plugins (`@blac/devtools-connect`, `@blac/plugin-persist`) | Plugin API is explicit; installed once globally                     |
| `subscribeWithSelector`            | `watch(MyCubit, cb)`                                                   | Outside React; no middleware needed                                 |
| `createWithEqualityFn`             | `select` option on `useBloc`                                           | `select: (s, b) => [s.derived]` — re-render only when array changes |
| Slices pattern (`combine`)         | Separate `Cubit` per concern                                           | Each Cubit is already a self-contained slice                        |
| Immer middleware                   | `patch(partial)` (built-in deep-merge)                                 | Or use spread in `update` — no middleware required                  |

## The key model difference

Zustand stores logic in a `create()` closure. The object it returns is both the state and the actions —
a flat record with properties and function values mixed together. Re-render scoping requires an explicit
selector passed to every hook call.

BlaC separates the concerns: state is typed separately from the class body, methods are class methods,
and the hook returns a `[state, bloc]` tuple. Because the hook wraps `state` in a Proxy during render,
it records which paths the component reads — no selector needed.

## Side-by-side port: a bear counter

**Zustand**

```tsx
import { create } from 'zustand';

interface BearStore {
  bears: number;
  honey: number;
  increasePopulation: () => void;
  eatHoney: () => void;
  reset: () => void;
}

const useBearStore = create<BearStore>((set) => ({
  bears: 0,
  honey: 10,
  increasePopulation: () => set((s) => ({ bears: s.bears + 1 })),
  eatHoney: () => set((s) => ({ honey: Math.max(0, s.honey - 1) })),
  reset: () => set({ bears: 0, honey: 10 }),
}));

function BearCounter() {
  // explicit selector — component only re-renders when bears changes
  const bears = useBearStore((s) => s.bears);
  const increase = useBearStore((s) => s.increasePopulation);
  return <button onClick={increase}>Bears: {bears}</button>;
}

function HoneyJar() {
  const honey = useBearStore((s) => s.honey);
  const eat = useBearStore((s) => s.eatHoney);
  return <button onClick={eat}>Honey: {honey}</button>;
}
```

**BlaC**

```ts twoslash
import { Cubit } from '@blac/core';
// ---cut---
class BearCubit extends Cubit<{ bears: number; honey: number }> {
  constructor() {
    super({ bears: 0, honey: 10 });
  }

  increasePopulation = () => this.patch({ bears: this.state.bears + 1 });

  eatHoney = () => this.patch({ honey: Math.max(0, this.state.honey - 1) });

  reset = () => this.emit({ bears: 0, honey: 10 });
}
```

```tsx
import { useBloc } from '@blac/react';

function BearCounter() {
  // reading state.bears → component re-renders only when bears changes
  const [state, bear] = useBloc(BearCubit);
  return (
    <button onClick={bear.increasePopulation}>Bears: {state.bears}</button>
  );
}

function HoneyJar() {
  // reading state.honey → re-renders only when honey changes
  const [state, bear] = useBloc(BearCubit);
  return <button onClick={bear.eatHoney}>Honey: {state.honey}</button>;
}
```

`BearCounter` and `HoneyJar` re-render independently — each only wakes on the path it actually reads.
With Zustand you would write two `useStore((s) => s.x)` selectors by hand. With BlaC the read _is_ the
subscription; no selector required.

## Where logic grows

The flat closure model works well for small stores. As a slice accumulates validation, derived values,
and async flows, the Zustand pattern collapses everything into one growing object literal. The BlaC Cubit
keeps those concerns in class methods and getters:

**Zustand — a growing store**

```ts
const useCartStore = create<CartStore>((set, get) => ({
  items: [],
  addItem: (item) => set((s) => ({ items: [...s.items, item] })),
  removeItem: (id) =>
    set((s) => ({ items: s.items.filter((i) => i.id !== id) })),
  // getter-like value mixed into the store shape
  get total() {
    return get().items.reduce((sum, i) => sum + i.price * i.qty, 0);
  },
  checkout: async () => {
    const items = get().items;
    await api.checkout(items);
    set({ items: [] });
  },
}));
```

**BlaC — the same cart**

```ts twoslash
import { Cubit } from '@blac/core';

interface CartItem {
  id: string;
  price: number;
  qty: number;
}
declare const api: { checkout(items: CartItem[]): Promise<void> };
// ---cut---
class CartCubit extends Cubit<{ items: CartItem[] }> {
  constructor() {
    super({ items: [] });
  }

  addItem = (item: CartItem) =>
    this.patch({ items: [...this.state.items, item] });

  removeItem = (id: string) =>
    this.patch({ items: this.state.items.filter((i) => i.id !== id) });

  get total() {
    return this.state.items.reduce((sum, i) => sum + i.price * i.qty, 0);
  }

  checkout = async () => {
    await api.checkout(this.state.items);
    this.emit({ items: [] });
  };
}
```

The Cubit is testable without React or a mock store wrapper:

```ts twoslash
import { Cubit } from '@blac/core';

interface CartItem {
  id: string;
  price: number;
  qty: number;
}
class CartCubit extends Cubit<{ items: CartItem[] }> {
  constructor() {
    super({ items: [] });
  }
  addItem = (item: CartItem) =>
    this.patch({ items: [...this.state.items, item] });
  get total() {
    return this.state.items.reduce((sum, i) => sum + i.price * i.qty, 0);
  }
}
// ---cut---
const cart = new CartCubit();
cart.addItem({ id: 'a', price: 10, qty: 2 });
cart.addItem({ id: 'b', price: 5, qty: 1 });

console.log(cart.total); // 25
```

No `act()`, no render harness, no `getState()` reached through a store handle.

## Middleware → plugins

Zustand middleware wraps the store creator (devtools, persist, immer). BlaC uses a plugin system
installed once globally:

```ts
import { getPluginManager } from '@blac/core';
import { createDevToolsBrowserPlugin } from '@blac/devtools-connect';
import { createIndexedDbPersistPlugin } from '@blac/plugin-persist';
import { LoggingPlugin } from '@blac/logging-plugin';

getPluginManager().install(createDevToolsBrowserPlugin(), {
  environment: 'development',
});
getPluginManager().install(createIndexedDbPersistPlugin());
getPluginManager().install(new LoggingPlugin({ level: 'info' }), {
  environment: 'development',
});
```

No middleware composition, no `devtools(persist(immer(...)))` nesting. Plugins observe all Cubits
globally; you can opt individual Cubits out via `@blac({ excludeFromDevTools: true })`.

## Subscribing outside React

Zustand's `subscribeWithSelector` and its vanilla `store.subscribe` travel to BlaC's `watch`:

```ts twoslash
import { Cubit } from '@blac/core';
import { watch } from '@blac/core';

class BearCubit extends Cubit<{ bears: number; honey: number }> {
  constructor() {
    super({ bears: 0, honey: 10 });
  }
}
// ---cut---
const unwatch = watch(BearCubit, (bloc) => {
  document.title = `Bears: ${bloc.state.bears}`;
});

// later:
unwatch();
```

`watch` observes a Cubit's state from outside React. No store handle, no selector middleware needed.

## Slices → separate Cubits

The Zustand slices pattern (`combine`, `createSlice`) splits one large store into sections that are
merged back together. BlaC separates concerns at the class level — each Cubit is already an
independent slice. Cross-cubit access uses `this.depend()`:

```ts twoslash
import { Cubit } from '@blac/core';

class AuthCubit extends Cubit<{ user: string | null }> {
  constructor() {
    super({ user: null });
  }
}
// ---cut---
class CartCubit extends Cubit<{ items: string[] }> {
  private auth = this.depend(AuthCubit);

  constructor() {
    super({ items: [] });
  }

  checkout = async () => {
    const authState = this.auth.untracked().state;
    if (!authState.user) throw new Error('Not logged in');
    // ... proceed
  };
}
```

No slice merging, no shared-store handle. `depend` returns a handle that resolves the Cubit from the
registry, keeping the two slices decoupled.

## Re-render scoping: selector vs auto-track

The most common Zustand pattern is a per-hook selector:

```tsx
// Zustand — every subscription needs a selector
const count = useCounterStore((s) => s.count);
const name = useUserStore((s) => s.profile.name);
```

BlaC infers the subscription from the render read:

```tsx
// BlaC — read it, that's the subscription
const [counterState] = useBloc(CounterCubit);
const [userState] = useBloc(UserCubit);
// count = counterState.count, name = userState.profile.name
// no selectors written
```

When you do need finer control — a computed value, a cross-field condition — use the `select` option:

```tsx
const [state] = useBloc(CartCubit, {
  select: (s, cart) => [cart.total], // re-render only when total changes
});
```

## Mental-model shift

| Zustand                                     | BlaC                                                   |
| ------------------------------------------- | ------------------------------------------------------ |
| `create()` closure holds state + actions    | Class body holds state type + methods                  |
| Explicit selector per hook call             | Auto-tracked read paths; `select` for computed values  |
| Middleware stack (`devtools(persist(...))`) | Plugin list installed once globally                    |
| `subscribeWithSelector` for outside-React   | `watch(Class, cb)` — no middleware needed              |
| Slices merged via `combine`                 | Independent Cubits; cross-cubit via `depend()`         |
| Mutations tested via `getState()`           | Mutations tested by calling methods on `new MyCubit()` |
| `immer` middleware for nested merges        | `patch(partial)` built in                              |

## When to stay with Zustand

BlaC earns its weight when state accumulates logic worth testing, derived values, or async flows. If
your state is a handful of booleans in a flat object that never grows a method, Zustand's closure is
the lower-overhead choice. See [When to use BlaC](/guide/introduction#when-to-use-blac).

## See also

- [Comparison](/guide/comparison) — BlaC vs Zustand vs Jotai side by side, including when Zustand is the better fit
- [Core Concepts](/guide/concepts) — state containers, registry, dependency tracking
- [useBloc](/react/use-bloc) — full hook reference with `args`, `select`, `onMount`
- [Dependency Tracking](/react/dependency-tracking) — auto-tracking and `select` in depth
- [Patterns & Recipes](/guide/patterns) — cross-bloc deps, persistence, async

---

# Comparison

> An honest, side-by-side look at how BlaC compares to Zustand and Jotai, and when each is the better choice.

Source: /guide/comparison/

If you are evaluating BlaC against Zustand or Jotai, the first question is usually skeptical: _why a class?_ Hooks-first stores feel lighter, and "OOP for state" reads like a step backwards. This page makes the affirmative case first, then puts the three side by side honestly — including the cases where Zustand or Jotai is the better choice.

This is positioning, not a feature scoreboard. None of these libraries is wrong; they make different bets. The goal here is to make BlaC's bet legible so you can tell whether it is yours.

## Why a class is the unit of logic

The class is not ceremony for its own sake. Each thing it gives you is a direct answer to a recurring pain in store-closure or atom-graph designs.

**Logic is colocated with the state it mutates.** State shape, the methods that change it, derived values, and async flows live in one cohesive unit. A `CartCubit` holds `items` and _also_ holds `addItem`, `removeItem`, `checkout`, and `get total`. You do not chase a mutation across a reducer file, an action-creators file, and a selectors file — the concern is one class. When the cart's rules change, you edit one place.

**You can test it without React.** A Cubit has no dependency on React, the DOM, or hooks. You construct it, call methods, and assert on `state` and getters directly — a plain unit test, no render harness, no `act()`, no test renderer:

```ts
const cart = new CartCubit();
cart.addItem({ id: 'a', price: 10, qty: 2 });
expect(cart.total).toBe(20);
```

Store-closure designs can be tested headless too, but it is less direct: you reach through the store's `getState`/`setState` rather than calling a method on an object, and shared mutable module state between tests is easy to leak. A fresh `new CartCubit()` per test is the natural isolation boundary.

**Getters are derived state, for free.** A `get total()` recomputes from `items` on every read, so it can never drift from its source. The tracker records the getter's underlying reads, so a component that reads `cart.total` wakes when the source paths the getter touched change — no `useMemo`, no `reselect`, no memo input arrays to keep in sync. Use `select` when the computed result itself should gate re-renders. Derived state in an atom library is its own atom you compose and wire; here it is a method body.

**The lineage is `flutter_bloc`, deliberately.** "Business Logic Component" is the Flutter pattern: a class that owns a slice of logic and emits state. BlaC keeps the `Cubit` half of that lineage (methods you call, not events you dispatch — there is no `Bloc` event class; see [Best Practices](/guide/best-practices)) because the testability and colocation win travels straight across from Flutter to React.

**Re-renders are per consumer, automatically.** Each `useBloc` call site gets its own render-time proxy and its own recorded set of read paths. Two components reading the same instance subscribe to different fields and wake independently — without you writing a selector per subscription. The dependency declaration _is_ the JSX. The full mechanism is in [Mental Model](/guide/mental-model).

:::note[This is a real tradeoff]
A class is heavier than a `create((set) => ...)` closure or a one-line atom for trivial state. If your state is a single boolean or a counter that never grows logic, that weight is not buying you anything. BlaC earns its keep as a slice of state accumulates _mutations, derived values, and async_ — not at the first `useState`.
:::

## At a glance

A fixed rubric across the three. Read it as "how each library answers this question," not as winners and losers.

|                         | **BlaC**                                              | **Zustand**                                        | **Jotai**                                          |
| ----------------------- | ----------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------- |
| **State model**         | Class (`Cubit`) with methods + getters                | `create()` store closure with `set`/`get`          | Composable atoms (primitive + derived)             |
| **Render optimization** | Auto-tracked read paths, per consumer (no selector)   | Selector you pass to the hook (`useStore(s => …)`) | Per-atom subscription; granularity from atom split |
| **Boilerplate**         | Class + `super(initial)`; methods are intents         | Minimal; one closure                               | Minimal per atom; grows with atom count + wiring   |
| **Providers**           | None — global ref-counted registry                    | None by default (optional context store)           | `Provider` for scoping/SSR (optional at root)      |
| **TS inference**        | State flows from the class type param                 | Strong; sometimes needs a typed `create<T>()`      | Strong; derived-atom types inferred                |
| **Async**               | `async` methods on the class; explicit status state   | Async actions in the store closure                 | Async atoms (promise atoms, Suspense-friendly)     |
| **DevTools**            | First-party `@blac/devtools-connect` plugin           | Redux DevTools middleware                          | Jotai DevTools / Redux DevTools integration        |
| **SSR**                 | Per-request isolation via instance keys / registry    | Supported; hydrate store on the client             | Strong story via `Provider` + hydration            |
| **Framework-agnostic**  | Core is framework-agnostic; React adapter is separate | Core is framework-agnostic; vanilla + React        | React-centric (Jotai core targets React)           |
| **Bundle size**         | Measured: core ~6.88 kB, react ~2.6 kB (brotli)       | Tiny; see their published claims                   | Tiny core; grows with utility imports              |

Bundle-size detail is in [its own section below](#bundle-size) — only BlaC's number is measured here; the others are described qualitatively on purpose.

## Honest comparisons

BlaC borrows liberally and differs deliberately. Here is where it sits relative to tools you likely know — including Redux, MobX, and Context for completeness — and when one of them is the better fit.

| Library             | What BlaC borrows                                                                   | What BlaC does differently                                                                                                                                                                      | Reach for it instead when                                                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Redux (Toolkit)** | Single source of truth per concern; immutable updates; a devtools/time-travel story | No global reducer/action/dispatch indirection; logic is methods on a class, not reducers + action creators; auto-tracking replaces hand-written selectors                                       | You need a strict, serializable action log as the center of your architecture, or large-team conventions built around RTK                           |
| **Zustand**         | No-provider, hook-first store; minimal API                                          | State lives in a class with methods and getters (not a `create((set) => ...)` closure); re-render scope is per-read-path automatically, not a selector you pass to the hook                     | You want the smallest possible store with no class ceremony and are happy writing selectors per subscription                                        |
| **MobX**            | Read-to-subscribe transparent reactivity; derived values feel free                  | Reactivity is render-time path recording over **immutable** snapshots, not observable mutable objects with autorun; you replace state, you don't mutate it; no decorators required for tracking | You want deep observable graphs with `computed`/`reaction` and prefer mutate-in-place ergonomics                                                    |
| **React Context**   | Tree-free _consumption_ ergonomics (just call a hook)                               | Sharing is registry identity, not provider position; no subtree re-render on change; instances are ref-counted and disposable                                                                   | The value is genuinely tree-scoped config (theme, locale, a request) that should follow the component tree, change rarely, and never needs disposal |
| **Jotai / Recoil**  | Fine-grained, atom-like subscription granularity                                    | Granularity comes from _which paths you read in one state object_, not from composing many atoms; one cohesive class instead of a graph of atoms                                                | You think in independent composable atoms and want bottom-up derived-atom graphs                                                                    |

What to take from the table: BlaC's distinctive bet is **transparent reactivity (like MobX) over immutable snapshots (like Redux), with no provider and automatic lifecycle (unlike both)**. The granularity of an atom library without managing atoms; the testability of a class without the reducer boilerplate. If your problem is genuinely a serializable event log, a tree-scoped config value, or a handful of `useState` hooks, the honest answer is that one of those tools fits better — see the "when to use BlaC" framing in the [Introduction](/guide/introduction#when-to-use-blac).

## The same counter, three ways

A counter is too small to _need_ any of these libraries — that is exactly why it isolates the shape of each model. Watch where the logic lives and how a component subscribes.

**Zustand** — logic in a `create()` closure; the component passes a selector to scope its re-renders.

```tsx
import { create } from 'zustand';

const useCounter = create<{
  count: number;
  increment: () => void;
}>((set) => ({
  count: 0,
  increment: () => set((s) => ({ count: s.count + 1 })),
}));

function Counter() {
  const count = useCounter((s) => s.count);
  const increment = useCounter((s) => s.increment);
  return <button onClick={increment}>Count: {count}</button>;
}
```

**Jotai** — state and its updater are atoms; the component subscribes to the atom it reads.

```tsx
import { atom, useAtom } from 'jotai';

const countAtom = atom(0);

function Counter() {
  const [count, setCount] = useAtom(countAtom);
  return <button onClick={() => setCount((c) => c + 1)}>Count: {count}</button>;
}
```

**BlaC** — logic in a class; the component reads `state.count` and that read _is_ the subscription.

```ts twoslash
import { Cubit } from '@blac/core';
// ---cut---
class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  increment = () => this.emit({ count: this.state.count + 1 });
}
```

```tsx
import { useBloc } from '@blac/react';

function Counter() {
  const [state, counter] = useBloc(CounterCubit);
  return <button onClick={counter.increment}>Count: {state.count}</button>;
}
```

The three converge on roughly the same line count for a counter. The divergence shows up as logic grows: the Zustand closure and the Jotai atom set accumulate updaters and derived atoms inline, while the Cubit accumulates methods and getters as a typed unit you can test in isolation. The render-scoping line — `useCounter((s) => s.count)` vs `useAtom(countAtom)` vs an untouched `state.count` read — is the per-consumer-isolation difference made literal: BlaC infers it from the read, the other two make it explicit (a selector, or which atom you reach for).

## Which one to choose

**Choose BlaC when** state is _shared, complex, and worth testing without React_: validation, derived values, async flows, cross-bloc coordination. You want logic colocated in a typed unit, automatic per-read re-render scoping, and a ref-counted lifecycle with no providers — and you are comfortable with classes as the organizing idea.

**Choose Zustand when** you want the smallest possible store with no class ceremony, are happy writing a selector per subscription to scope re-renders, and your logic stays close to a flat closure. It is an excellent floor for "I just need a shared store."

**Choose Jotai when** you think bottom-up in independent, composable pieces — derived-atom graphs, fine-grained Suspense-friendly async, state that is naturally a web of small values rather than a few cohesive slices. Atoms shine when the composition _is_ the model.

If a piece of state lives in one component and never travels, none of the three earns its weight — reach for `useState`. See [When to use BlaC](/guide/introduction#when-to-use-blac).

## Bundle size

BlaC's footprint is **measured in CI with [size-limit](https://github.com/ai/size-limit)** on the published ESM build, brotli-compressed:

- **`@blac/core`** is about **6.88 kB** (brotli).
- **`@blac/react`** is about **2.6 kB** (brotli), excluding `react` / `react-dom` peers.

These are the real numbers from the size budget that gates every build, not estimates. A React app pulls in both, so the floor is roughly **9.5 kB** before your own code.

For Zustand and Jotai, consult their own published figures rather than any number quoted here. Both are deliberately small — Zustand advertises a tiny core, and Jotai's primitives are minimal — but a precise byte count depends on which utilities and middleware you import, your bundler, and your compression settings, so inventing exact competitor numbers would be dishonest. The fair summary: all three are small enough that bundle size is rarely the deciding factor between them. Pick on model fit, not bytes.

## See also

- [Mental Model](/guide/mental-model) — why auto-tracking, the registry, and immutable emit work the way they do
- [Introduction](/guide/introduction#when-to-use-blac) — what BlaC is and when it earns its weight
- [Best Practices](/guide/best-practices) — Cubit-vs-Bloc, state shape, and the input lanes
- [Dependency Tracking](/react/dependency-tracking) — auto-track vs `select` in practice

---

# Core Concepts

> A quick conceptual tour of state containers, the registry, instance modes, dependency tracking, and plugins.

Source: /guide/concepts/

This is the quick conceptual tour — one screen per idea, enough to start making good decisions about how to structure your state. For the deep "why it works this way" (the reactivity model, the per-consumer tracker, batching and ref-counting rationale, and honest comparisons to other libraries), read the [Mental Model](/guide/mental-model). For one-line definitions of every term, see the [Glossary](/guide/glossary).

## State Containers

A state container is a class that holds a typed state value and notifies listeners when it changes.

Think of it like a mini-store scoped to one concern. An `AuthCubit` holds auth state. A `CartCubit` holds cart state. Each is a self-contained unit with its own state type, methods, and lifecycle.

**Cubit** is the concrete class you'll extend. It gives you three ways to change state:

```ts
class AuthCubit extends Cubit<{ user: User | null; loading: boolean }> {
  constructor() {
    super({ user: null, loading: false }); // initial state
  }

  login = async (credentials: Credentials) => {
    this.patch({ loading: true }); // merge partial changes
    const user = await api.login(credentials);
    this.emit({ user, loading: false }); // replace entire state
  };

  logout = () => {
    this.update((s) => ({ ...s, user: null })); // derive from current
  };
}
```

State containers are framework-agnostic — they work without React. You can instantiate them in a test, call methods, and assert on `state` directly. No DOM, no hooks, no providers needed.

## Registry

The registry is a global singleton that manages state container instances. When you call `useBloc(CounterCubit)` in two different components, they both get the **same** `CounterCubit` instance. The registry makes this happen.

It maps each class (and optional instance key) to a single instance, plus a ref count tracking how many consumers are using it:

```text
Registry
├── CounterCubit (default)  →  instance, refCount: 2   ← two components
├── AuthCubit (default)     →  instance, refCount: 1
└── EditorCubit ("doc-42")  →  instance, refCount: 3
```

### Ref counting

Every `useBloc` call increments the ref count on mount and decrements it on unmount. When the count hits zero, the instance is **automatically disposed** — its resources are cleaned up and it's removed from the registry. This means you don't need to worry about memory leaks from forgotten state containers.

If you want an instance to survive even when nothing is using it, mark it with `@blac({ keepAlive: true })`.

### Registry functions

In React, `useBloc` handles the registry for you. Outside React (tests, scripts, server-side), you interact with it directly. The headline verbs:

| Function         | Creates? | Ref count | Use when                                        |
| ---------------- | -------- | --------- | ----------------------------------------------- |
| `acquire(Class)` | Yes      | +1        | You own this reference (must `release` later)   |
| `ensure(Class)`  | Yes      | No change | You need the instance but don't own a reference |
| `borrow(Class)`  | No       | No change | Instance must already exist (throws if not)     |
| `release(Class)` | No       | -1        | Done with your reference                        |

This is the quick version. The complete function table (including `borrowSafe`, `getRefCount`, `clear`, and the keying rules) lives in [Instance Management](/core/instance-management).

## Instance Modes

### Shared (default)

All calls to `useBloc(CounterCubit)` return the same instance. This is the common case for app-wide state like auth, theme, or cart.

### Named

Put the distinguishing value in `args` (and select it with `static key`) to get a distinct instance per key. Different args resolve to different instances.

```tsx
useBloc(EditorCubit, { args: { docId: 'doc-42' } });
```

### Keep alive

With `@blac({ keepAlive: true })`, the instance survives even when all components using it unmount. It persists for the lifetime of the app.

## Inputs: args and deps

Components rarely need a blank container — they need one seeded with data. BlaC keeps that data in two separate lanes so a shared instance with many consumers never races:

- **`args`** — serializable data that _identifies_ an instance (e.g. a document id). Same args resolve to the same instance; identity is derived from args alone.
- **`deps`** — non-serializable handles (callbacks, services) injected per consumer, never used for identity.

This is just the teaser; the full model, the precedence rules, and the failure modes live in [Inputs](/guide/inputs).

## Dependency Tracking

This is BlaC's key performance feature — the quick tour here, with the full mechanism and its edge cases in [Dependency Tracking](/react/dependency-tracking). When you call `useBloc`, the returned `state` is wrapped in a Proxy that records which properties your component actually reads during render:

```tsx
function UserName() {
  const [state] = useBloc(UserCubit);
  return <span>{state.name}</span>; // only 'name' is tracked
}
```

If `state.email` changes but `state.name` doesn't, this component **won't re-render**. This happens automatically — no selectors, no `useMemo`, no `React.memo`.

See it live: `CountReader` tracks `state.count`; `LabelReader` tracks `state.label`. Each component's render badge increments only when its own field changes.

<RenderCounterDemo client:visible />

The tracking also works for:

- Nested properties: `state.user.profile.name` (records the leaf path)
- Array access: `state.items.length`, `state.items[0]`

Getter reads participate too: the `bloc` returned by `useBloc` is proxied, so reading `bloc.total` during render records the `this.state` paths the getter touches. Use `select` when you want a getter's return value, rather than its source paths, to decide re-renders. See [Dependency Tracking](/react/dependency-tracking).

There are two tracking modes, chosen by whether you pass a `select` option — there is no separate on/off flag:

| Mode                        | How                                                      | Best for                                           |
| --------------------------- | -------------------------------------------------------- | -------------------------------------------------- |
| **Auto-tracking** (default) | Proxy records property access during render              | Most components                                    |
| **`select`** (manual)       | You return an array; re-render when it changes per-index | Complex conditions or computed values              |

A component that only calls methods and never displays state needs no special option: do not read from `state`, and auto-tracking records nothing to wake it. See [Dependency Tracking](/react/dependency-tracking) for the full story, including the conditional-read caveat.

## Plugins

Plugins observe lifecycle events across all state containers. They receive callbacks for instance creation, state changes, and disposal.

```ts
const plugin: BlacPlugin = {
  name: 'my-plugin',
  version: '1.0.0',
  onStateChange(ctx, prev, next, paths) { ... },
};

getPluginManager().install(plugin);
```

Official plugins: [Logging](/plugins/logging), [DevTools](/plugins/devtools), [Persistence](/plugins/persistence).

## Glossary

Every term used above — `StateContainer`, `Cubit`, registry, ref counting, auto-tracking, `args`/`deps`, hydration, `depend()`, and the rest — has a one-line definition in the [Glossary](/guide/glossary), each linking to its deep page.

## What's next?

- [Mental Model](/guide/mental-model) — The deep "why" behind everything on this page
- [Inputs](/guide/inputs) — args, deps, and instance identity in full
- [Patterns & Recipes](/guide/patterns) — Common patterns for structuring your app
- [Cubit](/core/cubit) — Full Cubit API reference
- [useBloc](/react/use-bloc) — Hook options and tracking modes

## See also

- [Mental Model](/guide/mental-model) — the deep version of this tour
- [Glossary](/guide/glossary) — definitions for every term here
- [Instance Management](/core/instance-management) — the complete registry function reference
- [Dependency Tracking](/react/dependency-tracking) — auto-tracking in depth

---

# Quick Start

> Install BlaC and build your first Cubit-powered React component.

Source: /guide/getting-started/

:::caution[Beta / pre-release]
BlaC v2 is in pre-release (beta). While in beta, **breaking API changes may ship in patch releases** without a major version bump — pin exact versions and check the changelog before upgrading. Strict semver resumes once v2 is officially out of beta.
:::

## Installation

<Tabs syncKey="pkg">
  <TabItem label="pnpm">

  ```bash
  pnpm add @blac/core @blac/react
  ```

  </TabItem>
  <TabItem label="npm">

  ```bash
  npm install @blac/core @blac/react
  ```

  </TabItem>
  <TabItem label="yarn">

  ```bash
  yarn add @blac/core @blac/react
  ```

  </TabItem>
</Tabs>

BlaC requires React 18+ and TypeScript is strongly recommended.

<details>
<summary>Recommended `tsconfig.json`</summary>

BlaC works with a standard strict React setup. The `@blac()` decorator (used for `keepAlive`, `static key`, and other options) works as either a legacy (`experimentalDecorators`) or a TC39/stage-3 decorator — enable decorator support in your tsconfig to use the `@blac(...)` syntax. Or skip decorators entirely with the functional form — `blac({ ... })(class extends Cubit { ... })` — which needs no extra compiler flags.

```jsonc
{
  "compilerOptions": {
    "target": "ESNext",
    "jsx": "react-jsx",
    "strict": true,
    "useDefineForClassFields": true,
    "experimentalDecorators": true, // only if you use @blac(...) decorator syntax
  },
}
```

</details>

## Step 1: Define a Cubit

A Cubit is a class that holds state and exposes methods to change it.

```ts twoslash
import { Cubit } from '@blac/core';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }

  increment = () => this.emit({ count: this.state.count + 1 });
  decrement = () => this.update((s) => ({ count: s.count - 1 }));
  reset = () => this.patch({ count: 0 });
}
```

Three ways to change state:

| Method           | What it does                                  | When to use                                      |
| ---------------- | --------------------------------------------- | ------------------------------------------------ |
| `emit(newState)` | Replace the entire state                      | You have the full new state ready                |
| `update(fn)`     | Derive new state from current                 | You need to read current state first             |
| `patch(partial)` | Deep-merge partial changes (`DeepPartial<S>`) | You want to update some fields and keep the rest |

:::caution[`emit` and `update` replace; only `patch` merges]
`emit(next)` and `update(fn)` set state to _exactly_ what you return — any key you forget to include is dropped. `patch(partial)` deep-merges, so the keys you omit survive. The `increment` above is fine because `count` is the only key; for multi-field state, either spread the previous state (`update((s) => ({ ...s, count: s.count + 1 }))`) or use `patch`.
:::

:::tip[Define methods as arrow-function fields]
Every method here is an arrow-function class field (`increment = () => …`), not a regular method. This binds `this` to the instance, so `counter.increment` keeps working when passed straight to `onClick`. A regular method (`increment() { … }`) loses `this` once detached from the instance.
:::

## Step 2: Use it in React

The `useBloc` hook connects your component to a Cubit.

```tsx
import { useBloc } from '@blac/react';

function Counter() {
  const [state, counter] = useBloc(CounterCubit);

  return (
    <div>
      <p>Count: {state.count}</p>
      <button onClick={counter.increment}>+</button>
      <button onClick={counter.decrement}>-</button>
      <button onClick={counter.reset}>Reset</button>
    </div>
  );
}
```

`useBloc` returns a tuple:

- `state` — the current state snapshot (tracked for re-renders)
- `counter` — the Cubit instance (call methods on it)

## Step 3: Share state across components

By default, every component that calls `useBloc(CounterCubit)` gets the **same instance**. State is automatically shared.

```tsx
function CounterDisplay() {
  const [state] = useBloc(CounterCubit);
  return <p>Count: {state.count}</p>;
}

function CounterControls() {
  const [, counter] = useBloc(CounterCubit);
  return <button onClick={counter.increment}>+</button>;
}

function App() {
  return (
    <>
      <CounterDisplay />
      <CounterControls />
    </>
  );
}
```

When `CounterControls` calls `increment`, `CounterDisplay` re-renders with the new count. No providers, no context, no prop drilling.

## Step 4: Add business logic

Keep logic in the class, not in the component.

```ts
class TodoCubit extends Cubit<{ items: string[]; input: string }> {
  constructor() {
    super({ items: [], input: '' });
  }

  setInput = (value: string) => this.patch({ input: value });

  addTodo = () => {
    const trimmed = this.state.input.trim();
    if (!trimmed) return;
    // emit/update REPLACE state, so list every key you want to keep.
    this.update((s) => ({ items: [...s.items, trimmed], input: '' }));
  };

  removeTodo = (index: number) => {
    // patch deep-merges, so we only mention the key we change.
    this.patch({ items: this.state.items.filter((_, i) => i !== index) });
  };

  get isEmpty() {
    return this.state.items.length === 0;
  }
}
```

Notice the two write styles: `addTodo` uses `update` and lists _both_ keys (replacing the whole state), while `removeTodo` uses `patch` and mentions _only_ `items` (merging into the rest). Both are correct — the difference is exactly the replace-vs-merge rule from Step 1.

Getters like `isEmpty` derive a value on every read, so they can never drift from `items`. When a component reads `todo.isEmpty` during render, auto-tracking records the getter's underlying `this.state.items.length` read through the proxy. Use `select` only when you want the getter's return value to be the explicit re-render boundary. The full rule is in [Dependency Tracking](/react/dependency-tracking). For async work (loading flags, fetches, request guards), see [Patterns & Recipes](/guide/patterns).

:::caution[Component not re-rendering?]
The two most common first-time causes:

1. **Reading raw state off the bloc instead of the `state` proxy.** Auto-tracking records reads on the destructured `state` value and on getters read from the returned `bloc` proxy during render. It does not track `counter.state.count`, because that reads raw state directly. Read through `state` in render, or expose a getter that reads `this.state`.
2. **Expecting `emit`/`update` to merge.** They _replace_ the whole state, so any key you omit is dropped. Use `patch` to merge, or spread the previous state.

The full symptom list is in [Troubleshooting & FAQ](/guide/troubleshooting).
:::

## Step 5: Fetch something

An async action is just a method that `await`s and emits as it goes. Model the lifecycle as a `status` union so the view can render loading and error states, and use a request-id guard so a slow response can never overwrite a newer one.

```ts twoslash
import { Cubit } from '@blac/core';

interface User {
  id: string;
  name: string;
}
declare const api: { fetchUser(id: string): Promise<User> };
// ---cut---
type UserState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; user: User }
  | { status: 'error'; message: string };

class UserCubit extends Cubit<UserState> {
  private requestId = 0;

  constructor() {
    super({ status: 'idle' });
  }

  load = async (id: string) => {
    const reqId = ++this.requestId; // claim the latest slot
    this.emit({ status: 'loading' });
    try {
      const user = await api.fetchUser(id);
      if (reqId !== this.requestId) return; // a newer call won; bail
      this.emit({ status: 'success', user });
    } catch (e) {
      if (reqId !== this.requestId) return;
      this.emit({ status: 'error', message: String(e) });
    }
  };
}
```

The view switches on `state.status` and TypeScript narrows each branch. Derived loading flags, the loadable surface, cancellation with `AbortController`, and why BlaC does _not_ use React Suspense are all in the [Async guide](/guide/async).

## What just happened?

When you call `useBloc(CounterCubit)`:

1. The **registry** checks if an instance of `CounterCubit` already exists
2. If not, it creates one and stores it. If yes, it returns the existing one
3. A **ref count** is incremented (tracking how many components use this instance)
4. The hook subscribes to state changes using **auto-tracking** — a Proxy wraps the state and records which properties your render function accesses
5. On re-render, only changes to those specific properties trigger an update
6. When the component unmounts, the ref count decrements. At zero, the instance is disposed

Each of these steps has a "why" worth understanding once your app grows — why a proxy beats selectors, why disposal is automatic, why updates batch on a microtask. That deep version lives in the [Mental Model](/guide/mental-model).

## What's next?

- [Core Concepts](/guide/concepts) — A quick tour of registry, tracking, and lifecycle
- [Mental Model](/guide/mental-model) — The deep version of "what just happened?"
- [Patterns & Recipes](/guide/patterns) — Async patterns, cross-bloc communication, persistence
- [Cubit](/core/cubit) — Full Cubit API
- [useBloc](/react/use-bloc) — Hook options and tracking modes

## See also

- [Core Concepts](/guide/concepts) — the quick conceptual tour
- [Cubit](/core/cubit) — `emit` / `update` / `patch` in full
- [useBloc](/react/use-bloc) — every hook option and both tracking modes
- [DevTools](/plugins/devtools) — inspect state and re-renders in real time

---

# Glossary

> A one-line definition for every term in the BlaC docs, grouped and alphabetized, with a link to the page that explains each in full.

Source: /guide/glossary/

A one-line definition for every term you will meet in the BlaC docs, with a link to the page that explains it in full. Terms are grouped into **Core model**, **Inputs &amp; identity**, **React binding**, **Lifecycle &amp; hydration**, and **Plugins &amp; observation**, then alphabetized within each group.

:::tip[Read this when terms collide]
A few names look alike and are easy to confuse: `select` (a re-render selector) vs `deps` (a handle lane); and `StateContainer` vs `Cubit` vs "bloc" vs "instance". The [Disambiguation](#disambiguation) section at the bottom untangles each cluster in one place.
:::

## Core model

| Term                    | Definition                                                                                                                                                                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **StateContainer**      | The abstract base class for all state holders. Holds state, exposes `emit`/`patch`/`update`, manages subscriptions, deps, and lifecycle. You rarely extend it directly. See [Cubit](/core/cubit).                                                |
| **Cubit**               | The concrete class you extend. It is `StateContainer` with an empty body, existing as a real class so `instanceof Cubit` works. Adds nothing structurally. See [Cubit](/core/cubit).                                                             |
| **bloc**                | Colloquial shorthand for _any_ state-container instance (`StateContainer` or `Cubit`). There is **no `Bloc` class** in BlaC. See [Concepts](/guide/concepts).                                                                                    |
| **instance**            | A single live object of a bloc class, identified by its instance key and shared by all consumers that resolve to that key. See [Instance management](/core/instance-management).                                                                 |
| **state**               | The single object a bloc holds (`S extends object`). Read via `bloc.state`; replaced or merged through `emit`/`patch`/`update`. See [Cubit](/core/cubit).                                                                                        |
| **emit**                | `emit(next)` replaces the whole state with `next`. Skipped when `next` is reference-equal or passes the configured equality fn. See [Cubit](/core/cubit).                                                                                        |
| **patch**               | `patch(partial)` deep-merges a `DeepPartial<S>` into state, marking only paths whose value actually changed. The equality fn does **not** apply to `patch`. See [Cubit](/core/cubit).                                                            |
| **update**              | `update(fn)` is sugar for `emit(fn(state))` — build the next state from the current one. See [Cubit](/core/cubit).                                                                                                                               |
| **init**                | `protected init(args)` — an override hook called **once** after construction, before the first snapshot. Seed args-derived state or kick off loads here. See [Patterns](/guide/patterns).                                                        |
| **registry**            | The global singleton that creates, keys, shares, ref-counts, and disposes instances. Resolved via `getRegistry()`. See [Instance management](/core/instance-management).                                                                         |
| **acquire / release**   | Registry verbs that take and give back a counted reference to an instance: `acquire` creates-or-reuses and bumps the ref count, `release` drops it (disposing at zero unless `keepAlive`). See [Instance management](/core/instance-management). |
| **ensure**              | Registry verb that creates-or-reuses an instance **without** taking a ref. Used by `watch` and `depend()`; the result is not kept alive by the caller. See [Instance management](/core/instance-management).                                     |
| **borrow / borrowSafe** | Registry reads that return an **existing** instance without creating one or counting a ref. `borrow` throws when missing; `borrowSafe` returns `{ error, instance }`. See [Instance management](/core/instance-management).                      |
| **ref counting**        | The mechanism behind sharing: each consumer holds one ref via `acquire`; when the last ref is released the instance is auto-disposed (unless `keepAlive`). See [Instance management](/core/instance-management).                                 |
| **instance key**        | The string that decides which instance a consumer gets. Resolved from `args`: own `args` (via `static key(args)`, else structural hash of `args`) &gt; `<BlocProvider>` context `args` &gt; `'default'`. See [Inputs](/guide/inputs).            |
| **structural key**      | A deterministic, order-independent JSON hash of `args` used to key instances when no explicit key is given. Throws (dev) if `args` contains a function. See [Inputs](/guide/inputs).                                                             |

## Inputs &amp; identity

| Term                    | Definition                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Args**                | Typed, **serializable** creation data (`Args` type param). Passed to `init(args)` once and used to key instance identity. Optional in `useBloc` when declared (inherits from `BlocProvider` or defaults to the default key), forbidden when `void`. See [Inputs](/guide/inputs).                                                                                                                                           |
| **Deps**                | Non-serializable handles (refs, stable callbacks) injected **per consumer** via the `Deps` type param. Merged into `bloc.deps`; **never** key identity. See [Inputs](/guide/inputs).                                                                                                                                                                                                                                       |
| **deps (runtime)**      | The merged, read-only view of all consumers' dep slices, exposed as `bloc.deps`. Changes fire [onDepsChanged](#onDepsChanged). Note: a `deps` _option_ on `useBloc` is **internal**, not part of the public hook surface. See [Inputs](/guide/inputs).                                                                                                                                                                     |
| **instanceId**          | **Never a `useBloc`/`BlocProvider` option, and no longer an instance property.** Instance identity comes entirely from `args` (via `static key` or structural hash). The resolved key is accessible as `bloc.$blac.id`; the `instanceId()` branded-type helper still exists for constructing typed `InstanceId` values. For a per-mount instance use `args: { _id: useId() }` + `static key`. See [Inputs](/guide/inputs). |
| **autoInstance**        | **Not a current option.** The shipping mechanism for a fresh per-mount instance is a synthetic `args` field — `args: { _id: useId() }` — plus a `static key` selecting it. The names `autoInstance`/`instanceId`-option survive only in stale comments; there is no `isolated`, `autoInstance`, or `instanceId` static prop or hook option. See [Instance management](/core/instance-management).                        |
| **static key**          | A class static `key = (args) => string` (settable directly or via `blac({ key })`) that derives the instance key from `args`. See [Inputs](/guide/inputs).                                                                                                                                                                                                                                                                 |
| **keepAlive**           | Set via `blac({ keepAlive: true })`; instances of the class are **never** auto-disposed at ref count zero (still disposable via `forceDispose`/`clear`). See [Configuration](/core/configuration).                                                                                                                                                                                                                         |
| **excludeFromDevTools** | Set via `blac({ excludeFromDevTools: true })`; the class is excluded from DevTools tracking. See [Configuration](/core/configuration).                                                                                                                                                                                                                                                                                     |
| **blac()**              | The decorator/function that sets exactly **one** class-level option: `keepAlive`, `excludeFromDevTools`, `equality`, or `key`. See [Configuration](/core/configuration).                                                                                                                                                                                                                                                   |

## React binding

| Term                     | Definition                                                                                                                                                                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **useBloc**              | The React hook: `useBloc(BlocClass, options?)` returns `[state, bloc, ref]`, acquiring on mount and releasing on unmount. See [useBloc](/react/use-bloc).                                                                                                                |
| **select**               | The `useBloc` option to **opt out** of auto-tracking: `select: (state, bloc) => unknown[]` re-renders only when the returned array changes per-index. Must be referentially stable. See [Dependency tracking](/react/dependency-tracking).                               |
| **auto-tracking**        | The default re-render strategy: when `select` is omitted, BlaC records which state leaves a render reads and re-renders only when one of them changes. Also called _dependency tracking_ (the feature/page name). See [Dependency tracking](/react/dependency-tracking). |
| **tracked proxy**        | The recording `Proxy` wrapper (`trackRender`) placed around `state` during render; reads on it log leaf paths used for auto-tracking. There is **no `@tracked` decorator** — tracking is automatic. See [Tracked](/core/tracked).                                        |
| **per-consumer tracker** | Each `useBloc` call gets its **own** proxy + recorded path set, so re-renders stay isolated between components reading the same instance. See [Dependency tracking](/react/dependency-tracking).                                                                         |
| **BlocProvider**         | A React component that supplies default `args` to descendant `useBloc` calls that omit their own. A call passing its own `args` still wins. See [useBloc](/react/use-bloc).                                                                                              |
| **ref (tuple element)**  | The third element of the `useBloc` tuple (`ComponentRef`); an advanced-use ref object rarely needed in app code. See [useBloc](/react/use-bloc).                                                                                                                         |

## Lifecycle &amp; hydration

| Term                               | Definition                                                                                                                                                                                                                                                                                               |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **system event**                   | A bloc lifecycle signal subscribed via `onSystemEvent(event, handler)`: one of `'stateChanged'`, `'dispose'`, or `'hydrationChanged'`. See [System events](/core/system-events).                                                                                                                         |
| **dispose**                        | Tearing down an instance: cancels hydration, fires the `'dispose'` system event, clears listeners, and removes it from the registry. Idempotent. See [System events](/core/system-events).                                                                                                               |
| **hydration**                      | Restoring previously persisted state into a bloc on startup, driven via `bloc.$blac.hydration` (`begin()` / `apply()` / `finish()` / `fail()`). Plugin authors drive it through `PluginContext` helpers (`ctx.startHydration`, `ctx.applyHydratedState`, etc.). See [Persistence](/plugins/persistence). |
| **hydrationStatus**                | The current hydration phase (`'idle' \| 'hydrating' \| 'hydrated' \| 'error'`), accessible as `bloc.$blac.hydration.status`. See [System events](/core/system-events).                                                                                                                                   |
| **waitForHydration**               | `bloc.$blac.hydration.wait()` returns a promise that resolves once hydration settles (idle/hydrated) or rejects on error. See [Persistence](/plugins/persistence).                                                                                                                                       |
| **depend / cross-bloc dependency** | `protected depend(Type, defaultArgs?): DepHandle<T>` records a dependency on another bloc and returns a **DepHandle**. Call `.track(options?)` to get `[state, instance]` (auto-subscribes in React render) or `.untracked(options?)` to get the instance with no subscription. No ref is taken. See [Bloc communication](/core/bloc-communication). |
| **onDepsChanged**                  | `protected onDepsChanged(next, prev)` — an override hook that fires whenever the merged per-consumer [deps](#deps-runtime) view changes (and once on dispose with all keys cleared). See [Inputs](/guide/inputs).                                                                                        |

## Plugins &amp; observation

| Term                    | Definition                                                                                                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **watch**               | `watch(blocOrRef, callback)` runs a callback once immediately and again on every change of the watched bloc(s), outside React. Return `watch.STOP` (or call the returned fn) to stop. See [watch](/core/watch).     |
| **instance() (helper)** | `instance(BlocClass, args)` builds a `BlocRef` so `watch` targets the instance keyed by those args rather than the default one. See [watch](/core/watch).                                                           |
| **subscribe**           | `bloc.subscribe(interest, cb)` — a path-scoped subscription that passes through to `bloc.channel.subscribe`. Prefer `watch` (non-React) or `useBloc` (React) for whole-state observation. See [watch](/core/watch). |
| **plugin**              | An observer (`BlacPlugin`) that hooks into container lifecycle (`onCreated`, `onStateChange`, `onDestroyed`, `onHydrationChange`, …) across all instances. See [Plugins](/core/plugins).                            |
| **PluginManager**       | The singleton (via `getPluginManager()`) that installs, uninstalls, and tracks plugins, gating each by `enabled` and `environment`. See [Plugins](/core/plugins).                                                   |
| **PluginContext**       | The per-dispatch context object passed to plugin hooks; exposes the focal `container`, metadata, state, hydration controls, and registry queries. See [Plugins](/core/plugins).                                     |
| **interner**            | The per-class `PathInterner` that maps state property paths to integer ids, making path comparison cheap. You rarely touch it directly. See [Tracked](/core/tracked).                                               |
| **PathSet**             | The set of changed paths marked during a flush — either a `Set<PathId>` or the `ALL_PATHS` sentinel that means "everything changed." See [Tracked](/core/tracked).                                                  |

## Disambiguation

These clusters cause the most confusion. Keep them straight:

<details>
<summary>select vs deps</summary>

- **`select`** — a `useBloc` option that **narrows re-renders**: `(state, bloc) => unknown[]`. Opting in disables auto-tracking for that consumer. See [Dependency tracking](/react/dependency-tracking).
- **`deps`** — the **non-serializable handle lane** (`Deps` type param + `bloc.deps` view). Nothing to do with re-rendering. See [Inputs](/guide/inputs).

</details>

<details>
<summary>StateContainer vs Cubit vs bloc vs instance</summary>

- **`StateContainer`** — the abstract base class (you rarely extend it).
- **`Cubit`** — the concrete class you extend; structurally identical to `StateContainer`.
- **bloc** — informal word for _any_ container instance. There is **no `Bloc` class**.
- **instance** — one concrete live object of a class, shared by ref count under an instance key.

See [Concepts](/guide/concepts).

</details>

<details>
<summary>auto-tracking vs dependency tracking vs proxy tracking</summary>

All three name the **same** mechanism: the render-time recording proxy that logs which state leaves a component reads, so re-renders fire only on relevant changes. The docs use **auto-tracking** for the behavior and **dependency tracking** for the feature/page. See [Dependency tracking](/react/dependency-tracking).

</details>

:::caution[No `Bloc` class, no `@tracked`, no `autoTrack`/`autoInstance`/`instanceId` options]
BlaC has **no `Bloc` class** (only `StateContainer` and `Cubit`), **no `@tracked` decorator**, and **no `autoTrack`, `autoInstance`, or `instanceId` hook options**. Tracking is automatic and unconditional unless you pass `select`; a fresh per-mount instance comes from `args: { _id: useId() }` + `static key`. The instance's own identity is at `bloc.$blac.id` (not a top-level `instanceId` property). If a doc or comment mentions top-level `instanceId`/`name`/`isDisposed` on the bloc instance, it is stale — those are now under `$blac`.
:::

## See also

- [Concepts](/guide/concepts) — the quick tour of the model behind these terms
- [Mental model](/guide/mental-model) — the deep "why it works this way"
- [Inputs](/guide/inputs) — `args`, `deps`, and instance identity in full
- [useBloc](/react/use-bloc) — the canonical `useBloc` options and identity precedence

---

# Passing Inputs to Blocs

> The three input lanes — args, deps, and events — and the identity model that makes shared bloc instances safe.

Source: /guide/inputs/

Blocs sometimes need external data — a user ID to load, an endpoint URL, a DOM ref for a canvas. Passing that data safely is trickier than it looks, because multiple components can share one instance and each wants to set something on it.

:::note[Why this needs its own model]
A naive answer is "pass one `props`-style object into the bloc." That breaks the moment two components share an instance: if both write the same input, whoever rendered last wins, and the value flickers on every render — an _override race_. The fix is to recognise that "inputs" is really **three different needs**, each with its own lifetime and its own answer. Sorting an input into the right lane is what makes shared instances safe.
:::

The three lanes — `args`, `deps`, and events — and the [identity model](#identity-model-and-precedence) below are the whole story. For the broader _why_ behind shared, ref-counted instances see the [Mental Model](/guide/mental-model), and for the judgment of _which lane to reach for_ see [Best Practices](/guide/best-practices).

## The three input lanes

| Lane       | Purpose                                     | Keys identity?                            | Lifetime                  | Example                                 |
| ---------- | ------------------------------------------- | ----------------------------------------- | ------------------------- | --------------------------------------- |
| **`args`** | Typed creation/config data                  | **Yes** (structural hash or `static key`) | Set once via `init(args)` | `userId`, `endpoint`, `filters`         |
| **`deps`** | Non-serializable handles                    | **Never**                                 | Live, per-consumer merged | `inputRef`, stable callback, `emblaApi` |
| **events** | Values that change over the instance's life | N/A                                       | Called from effects       | `cubit.slidesChanged(v)`                |

These map onto a familiar React split: `args` is like `defaultValue` (set at birth, identity-bearing), `events` is like `value`/`onChange` (a live channel owned by one component), and `deps` is the side channel for things that can't be serialized at all.

---

## `args`: construction data that keys the instance

When a bloc declares an `Args` type, `useBloc` requires you to pass `args`. They are:

- Forwarded to the bloc's `init(args)` method **once, synchronously, before the first state snapshot** — so initial state is correct on the first render, no flash.
- Used to **derive the instance key** — different args ⇒ different instance. Same args ⇒ same instance.
- A **type error** to omit when declared, or to pass when `Args` is `void`.

```ts
class UserCardCubit extends Cubit<UserCardState, { userId: string }> {
  protected init(args: { userId: string }) {
    // called once by the framework at creation, before the first snapshot
    void this.loadUser(args.userId);
  }
}
```

```tsx
// args is required and type-checked
const [state] = useBloc(UserCardCubit, { args: { userId } });
```

**Why this eliminates the override race:** each distinct `userId` produces a distinct instance. Multiple components rendering the same `userId` share one instance and their `args` are by definition identical. There is nothing to race over.

### Identity keying

By default, identity is the **structural hash of all args** (the same principle as `atomFamily` and TanStack Query's `queryKey`). This is safe because args must be JSON-serializable — no refs or callbacks can accidentally destabilize the hash.

Override identity with a `static key` on the class when only a subset of args should key the instance, or when you want a human-readable key:

```ts
class DocumentCubit extends Cubit<
  DocState,
  { docId: string; readonly: boolean }
> {
  static key = (args: DocumentCubit['args']) => args.docId;
  // `readonly` is config that rides along but does NOT fork instances
}
```

`static key` is declared **once on the class**, not repeated at every call site. It reads as a plain statement of what distinguishes one `DocumentCubit` from another.

You can also supply `static key` via the `blac()` decorator/config function:

```ts
const DocumentCubit = blac({ key: (args) => args.docId })(
  class extends Cubit<DocState, { docId: string; readonly: boolean }> { ... }
);
```

See [Configuration](/core/configuration) for the rest of the `blac()` options (`keepAlive`, `equality`, `excludeFromDevTools`) and [Glossary](/guide/glossary) for how `args` and `static key` relate.

### Per-component private instances

To give each mount its own instance — disposed on unmount, never shared — include a **per-mount unique value in `args`** and declare a `static key` that uses it. The idiomatic source of a stable-per-mount value is React's `useId()`:

```tsx
// private instance, own lifecycle, seeded with args
class FileUploadCubit extends Cubit<
  UploadState,
  { endpoint: string; _id: string }
> {
  static key = (a: FileUploadCubit['args']) => a._id;
}

const _id = useId();
const [state, cubit] = useBloc(FileUploadCubit, { args: { ...options, _id } });
```

Because `useId()` returns a different value per component instance (and the same value across that component's re-renders), the derived key is unique per mount, so each mount gets a private bloc that lives and dies with it. The other args (`endpoint`) still seed `init(args)` — they ride along without forking instances because only `_id` keys identity.

:::caution[No `instanceId` or `autoInstance` option]
You might reach for `useBloc(C, { args, instanceId })` or `useBloc(C, { args, autoInstance: true })`. **Neither option exists** — `useBloc` accepts only `args`, `select`, `onMount`, and `onUnmount`. The per-mount idiom is the synthetic-args `static key` shown above. See [useBloc](/react/use-bloc) for the complete option list.
:::

### Args must be serializable

Args participate in identity hashing. Refs, callbacks, DOM elements, and class instances cannot go in `args` — they belong in the `deps` lane (below). Passing non-serializable values produces an unstable hash (a new key every render) which will cause a new instance on every render.

<InputsDemo client:visible />

---

## `deps`: non-serializable handles

Some things are genuinely non-serializable: a `useRef` container, a `useCallback`-stabilized handler, an Embla API instance handed in from outside. These live in the bloc's third type parameter — its `Deps` — and obey these rules:

- **Never key identity** — different refs don't fork the instance.
- **Per-consumer merged** — each component contributes its own slice; the bloc sees the union.
- **Read lazily** — via `this.deps.x` at action time, may be `undefined`. Always guard.
- **Applied post-commit** — never during render; no mid-render mutation.

The bloc side is declarative: declare the `Deps` shape and read `this.deps.x` lazily.

```ts
import type { RefObject } from 'react';

class FileUploadCubit extends Cubit<
  UploadState,
  { endpoint: string }, // args → keys identity
  { inputRef?: RefObject<HTMLInputElement> } // deps → never keyed, read lazily
> {
  protected init(args: { endpoint: string }) {
    this.endpoint = args.endpoint;
  }

  openPicker() {
    this.deps.inputRef?.current?.click?.(); // guard for absence
  }
}
```

### Wiring deps from a component

:::caution[`deps` is not a `useBloc` option]
There is no `deps:` key on `useBloc`. A component contributes its slice by calling the bloc's deps methods from a **mount effect** (post-commit, as the rules require). Import the methods from `@blac/core`:
:::

```tsx
import { useEffect, useId, useRef } from 'react';
import { APPLY_DEPS, REMOVE_DEPS_OWNER } from '@blac/core';
import { useBloc } from '@blac/react';

function UploadButton({ endpoint }: { endpoint: string }) {
  const inputRef = useRef<HTMLInputElement>(null);
  const ownerId = useId(); // identifies THIS consumer's slice
  // same endpoint → same instance, regardless of which ref is passed
  const [state, cubit] = useBloc(FileUploadCubit, { args: { endpoint } });

  useEffect(() => {
    cubit[APPLY_DEPS](ownerId, { inputRef }); // contribute this consumer's slice
    return () => cubit[REMOVE_DEPS_OWNER](ownerId); // withdraw it on unmount
  }, [cubit, inputRef, ownerId]);

  return <button onClick={() => cubit.openPicker()}>Choose file</button>;
}
```

`ownerId` (a `useId()` value, stable per mount) tags the slice so the engine knows which consumer wrote it and can withdraw exactly that slice on unmount.

<details>
<summary>Why an effect, not a render-time call</summary>

Deps must be applied _after_ commit so a freshly mounted `ref.current` is populated and so mid-render mutation never happens. The effect runs post-commit; its cleanup runs before the consumer's `useBloc` releases its ref, so the slice is withdrawn while the bloc is still alive. `APPLY_DEPS`/`REMOVE_DEPS_OWNER` are marked `@internal` today (a friendlier wrapper may land later), but this is the supported path.

</details>

### Multi-consumer merge

Different components can contribute different slices of deps to the same instance. The rules are simple:

1. Each consumer's keys are shallow-merged into `bloc.deps`.
2. When a consumer unmounts, its keys are withdrawn; other consumers' keys are untouched.
3. If two consumers set the same key to different values, a dev warning fires and the last write wins — a design smell, since one key should have one owner.

```tsx
// Component A owns inputRef
cubit[APPLY_DEPS](ownerIdA, { inputRef });

// Component B owns onSubmit
cubit[APPLY_DEPS](ownerIdB, { onSubmit });

// bloc.deps === { inputRef, onSubmit } — assembled from both consumers
```

### `onDepsChanged` — reacting when a handle arrives

For handles that need to trigger initialization (a canvas, a rich-text-editor controller), implement `onDepsChanged` on the bloc. It fires after each deps merge, receives `(next, prev)`, and lets the bloc diff which handle changed:

```ts
class CanvasRendererCubit extends Cubit<
  RenderState,
  { sceneId: string },
  { canvas?: HTMLCanvasElement; controller?: RteController }
> {
  onDepsChanged(next: this['deps'], prev: this['deps']) {
    if (next.canvas && next.canvas !== prev.canvas) {
      this.initRenderer(next.canvas); // canvas arrived or changed → init GPU loop
    }
    if (!next.canvas && prev.canvas) {
      this.disposeRenderer(); // canvas unmounted → tear down
    }
    if (next.controller !== prev.controller) {
      this.bindController(next.controller);
    }
  }
}
```

This is the canonical pattern for "wait for a ref, then initialize." Blocs that don't declare `onDepsChanged` just read `this.deps.x` lazily when an action runs.

### The callback staleness gotcha

An inline callback (`onComplete={() => doThing()}`) gets a new function identity every render. If you capture it once in `deps`, the bloc holds the first closure forever.

Prefer these patterns, best first:

1. **Callback inversion (recommended):** expose state; let the component call its own fresh callback in a `useEffect`.

   ```tsx
   const [{ uploadedId }] = useBloc(FileUploadCubit, { args: { endpoint } });
   useEffect(() => {
     if (uploadedId) onComplete(uploadedId); // always the current closure
   }, [uploadedId, onComplete]);
   ```

2. **Stabilize with `useCallback`** before contributing it as a dep.

3. **Push via a bloc method from an effect** — `useEffect(() => cubit.setOnComplete(cb), [cb])`.

:::caution[Common mistakes]

- **Non-serializable value in `args`** — a ref, callback, DOM node, or class instance makes the structural hash unstable, so you get a _new instance every render_. Put it in deps instead. (The structural-key hasher throws in dev if it sees a function in `args`.)
- **Capturing an inline callback in deps** — `{ onComplete: () => doThing() }` freezes the first render's closure. Stabilize with `useCallback`, or invert the callback (option 1 above).
- **Two consumers writing the same deps key** — last write wins and the value flickers. Give each shared value exactly one owning component.
- **Reaching for `deps:`, `instanceId:`, or `autoInstance:` as `useBloc` options** — none exist. Wire deps from an effect; key per-mount instances with a synthetic `args` value + `static key` (e.g. `args: { _id: useId() }`).
  :::

---

## Events: live data from one owning effect

For values that **genuinely change** over a shared instance's life — a `slides` array, a selected `theme` — call an ordinary bloc method from a single effect. This is the XState/flutter_bloc model: no `inputs` slot, no new concept, just a method call after commit.

```ts
class CarouselCubit extends Cubit<CarouselState> {
  slidesChanged(slides: Slide[]) {
    this.patch({ slides, total: slides.length });
  }
}
```

```tsx
function Carousel({ slides }: { slides: Slide[] }) {
  const [state, cubit] = useBloc(CarouselCubit, { args: { id } });

  // ONE component owns syncing this live value
  useEffect(() => {
    cubit.slidesChanged(slides);
  }, [cubit, slides]);

  return /* ... */;
}
```

**Convention:** one component owns syncing any given live value. Two components both calling `cubit.slidesChanged` from their own effects on the same instance is a design smell (and rare — keyed `args` usually route such cases to distinct instances).

---

## Identity model and precedence

When `useBloc` resolves which instance to connect to, it consults sources in this order — **the first that yields a key wins**. This is the canonical ordering; [useBloc](/react/use-bloc) restates the same list.

| Priority | Source                           | Resolved key                                                                  |
| -------- | -------------------------------- | ----------------------------------------------------------------------------- |
| 1        | own `args` on the `useBloc` call | `static key(args)` if declared, else the structural hash of `args`            |
| 2        | `<BlocProvider>` context `args`  | same resolution applied to inherited args, when the call passes no own `args` |
| 3        | `'default'`                      | singleton fallback — no `args`, no `static key`, no provider                  |

`args`-derived identity is the **only** idiom for per-value instances. For an identity that can't be derived from real data — anonymous, opaque, externally managed, or deliberately per-mount — synthesize one by adding a value to `args` (e.g. `_id: useId()`) and keying on it with `static key`.

### Decision matrix

Two questions decide everything: **is this input identity (set once) or live (changes over the instance's life)?** and **is the instance private to one component or shared?**

|                              | Input defines identity / set once                                                                          | Input is live and changing                                                         |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Private to one component** | `useBloc(C, { args: { ...data, _id: useId() } })` + `static key` on `_id` — own instance, seeded from args | synthetic per-mount `args` + call `cubit.xChanged(v)` from that component's effect |
| **Shared across consumers**  | `useBloc(C, { args })` — args key the instance; override race impossible                                   | call `cubit.xChanged(v)` from the **one owning component's** effect                |

Non-serializable handles (refs, callbacks, controllers) sit _outside_ this matrix entirely — they go through the [deps lane](#deps-non-serializable-handles) and never touch identity.

---

## A note on naming

The `select` option (the per-consumer re-render selector) is unrelated to the `deps` lane on this page, despite both sounding "dependency"-ish. `select` opts a consumer _out_ of auto-tracking; `deps` feeds _non-serializable handles_ into the bloc. The names are deliberately distinct to keep the two concepts from colliding.

## See also

- [Best Practices](/guide/best-practices) — _which_ lane to choose, and the judgment behind it
- [Mental Model](/guide/mental-model) — _why_ instances are shared and ref-counted
- [useBloc](/react/use-bloc) — the complete option list and identity precedence (canonical)
- [Glossary](/guide/glossary) — definitions of `args`, `deps`, `static key`
- [Patterns & Recipes](/guide/patterns) — concrete copy-paste recipes
- [Cubit](/core/cubit) — `init(args)`, `onDepsChanged`, and the mutation API

---

# How BlaC Works Internally

> Rebuild BlaC's reactivity engine from the ground up in four stages — the dirty channel, the path interner, the recording proxy, the observed skeleton, and cross-bloc dependencies.

Source: /guide/internals/

This chapter rebuilds BlaC's reactivity engine from the ground up, one stage at a
time. By the end you will be able to point at every moving part — the dirty
channel, the path interner, the recording proxy, the observed skeleton, and the
cross-bloc dependency layer — and say exactly what it does and why it has to.

If you only want the rules for writing components, read
[Tracking](/core/tracked) and [Dependency Tracking](/react/dependency-tracking).
This page is for when you want the _machine_. It is grounded directly in the
source: the engine lives in `@dirtytalk/engine`, the path machinery in
`@dirtytalk/structural`, and BlaC's lifecycle layer in `@blac/core`'s
`StateContainer`. The companion design narrative is the
[Mental Model](/guide/mental-model); the distilled standalone version is
[`@dirtytalk/structural` Concepts](/dirtytalk/structural/concepts).

We build in four stages, each strictly on top of the last:

```
Stage 1   state + listeners        "something changed — wake everyone"
   │                                (DirtyChannel, coalesced flush)
   ▼
Stage 2   paths                     "what changed — as interned integers"
   │                                (PathInterner, PathSet, intersection)
   ▼
Stage 3   the skeleton             "who reads what — diff once, fan out cheap"
   │                                (trackRender proxy + observed skeleton)
   ▼
Stage 4   cross-bloc deps          "one bloc leans on another"
                                    (StateContainer.depend / registry)
```

---

## Stage 1 — State and listeners

Start with the smallest honest model: a value, a set of listeners, and a way to
say "I changed." Every reactive store has this core. The naive version notifies
every listener synchronously on every change.

BlaC's real notification core is `DirtyChannel<Region>` from `@dirtytalk/engine`,
but we approach it from the outside in. From the outside, that contract is what
`Cubit` exposes: a value behind
`state`, mutated by `emit` / `update`, with `watch` (or the lower-level
`channel.subscribe`) firing on every coalesced flush. This block type-checks
against the real `@blac/core` surface:

```ts twoslash
import { Cubit, watch, ensure } from '@blac/core';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  increment() {
    // Immutable replacement. Several synchronous emits coalesce into ONE flush.
    this.emit({ count: this.state.count + 1 });
  }
}

// watch wakes on every flush and hands you the instance with the latest state.
const stop = watch(CounterCubit, (counter) =>
  console.log('woke at', counter.state.count),
);
const c = ensure(CounterCubit);
c.increment();
c.increment(); // two emits, same tick → callback fires once with count: 2
stop();
```

Underneath, `watch` is a thin bridge over the real notification core:
`DirtyChannel<Region>` from `@dirtytalk/engine`. It is generic over a `Region` —
an opaque "what changed" value governed by a `Space<Region>` algebra
(`empty`, `isEmpty`, `union`, `intersects`). Two properties make it more than a
plain `EventEmitter`. Modeled with a trivial boolean `Region` where "dirty" is
just `true` (illustrative — `@dirtytalk/engine` is the engine package, not a
docs dependency, so this block is shown rather than type-checked):

```ts
import { DirtyChannel, SyncScheduler, type Space } from '@dirtytalk/engine';

// The simplest possible Region: a boolean. `true` = "something changed".
const BoolSpace: Space<boolean> = {
  empty: () => false,
  isEmpty: (r) => r === false,
  union: (a, b) => a || b,
  // Any non-empty dirty wakes any interested subscriber.
  intersects: (interest, dirty) => interest && dirty,
};

class Counter {
  private _state = 0;
  // SyncScheduler flushes inline (production uses MicrotaskScheduler).
  private channel = new DirtyChannel<boolean>(BoolSpace, new SyncScheduler());

  get state() {
    return this._state;
  }
  listen(cb: () => void) {
    return this.channel.subscribe(
      () => true, // interest: "I care about everything"
      () => cb(),
    );
  }
  increment() {
    this._state += 1;
    this.channel.mark(true); // "something changed"
  }
}
```

The two load-bearing properties of `DirtyChannel`:

1. **Marks accumulate, flushes coalesce.** `mark(region)` unions the region into
   an accumulator and asks the scheduler to flush once. Several synchronous
   `mark`s collapse into a single flush — so three `emit`s in one tick wake each
   listener at most once.
2. **Interests are thunks evaluated at flush time.** A subscriber registers
   `subscribe(() => interest, cb)`. On flush the channel evaluates the interest
   thunk, tests `space.intersects(interest, dirty)`, and calls `cb` only on a
   hit. (This is the seam Stage 2 and 3 exploit; here the region is just
   "everything.")

```
Stage 1: mark → flush → wake everyone

  increment()  increment()        (same tick)
       │            │
       ▼            ▼
   mark(true)   mark(true)         union → still `true`
       └─────┬──────┘
             ▼
        scheduler.request(flush)   coalesced: scheduled once
             │
             ▼
   flush: dirty = true ───────────► every subscriber whose
                                     interest intersects → cb()
```

This is everything a `Cubit` does at the listener level. The
`watch(BlocClass, cb)` helper is exactly this: it bridges every channel
flush to a callback that wakes on any change, regardless of what changed,
applied from outside React. The flush is microtask-coalesced, which is why
several synchronous `emit`s produce a single notification.

What's missing: "wake everyone" is wasteful. A container with twenty fields
wakes a listener that reads one of them on all twenty kinds of change. Stage 2
makes "what changed" precise.

---

## Stage 2 — Paths

Replace the boolean region with a **set of changed paths**. A path is a dotted
route to a leaf in the state tree: `user.name`, `items`, `user.address.city`. A
mutation marks the paths it touched; a listener declares the paths it reads; the
channel wakes a listener only when those two sets intersect.

Comparing and unioning dotted strings on every mutation would be wasteful, so
every path is **interned** into a small integer `PathId` once. `PathInterner`
(in `@dirtytalk/structural`, used internally by every BlaC container) is a
bidirectional `string ↔ PathId` table: `intern(path)` returns a stable id (the
next sequential integer, starting at `0`), idempotently; `lookup(id)` reverses
it.

```ts
import { PathInterner } from '@dirtytalk/structural';

const interner = new PathInterner();
interner.intern('user.name'); // 0
interner.intern('user.email'); // 1
interner.intern('user.name'); // 0 again — idempotent
interner.lookup(0); // 'user.name'
interner.size; // 2
```

Ids are only comparable inside one interner's namespace, so BlaC keeps **one
interner per container subclass**, keyed by constructor in a `WeakMap`
(`StructuralContainer.getInternerFor`). Every instance of one `Cubit` subclass
shares an interner, so their ids line up and can be unioned/intersected freely;
distinct subclasses get distinct interners even if their state shapes match. The
`WeakMap` lets the interner be collected once the class is gone.

A `PathSet` is the unit of both "interest" and "dirtiness." It is either a
concrete `Set<PathId>` or the `ALL_PATHS` sentinel (`"every possible path"`).
The set algebra is a `Space<PathSet>` — `PathSetSpace` — the same `Space`
contract from Stage 1, now over path sets instead of booleans:

```ts
import {
  PathInterner,
  PathSetSpace,
  ALL_PATHS,
  type PathSet,
} from '@dirtytalk/structural';

const interner = new PathInterner();
const name = interner.intern('user.name'); // 0
const email = interner.intern('user.email'); // 1

// A listener that reads user.name; a mutation that changed user.email.
const interest: PathSet = new Set([name]);
const dirty: PathSet = new Set([email]);

PathSetSpace.intersects(interest, dirty); // false → stays asleep
PathSetSpace.intersects(new Set([name]), new Set([name])); // true → wakes

// ALL_PATHS intersects any non-empty set (used for "wake everyone" signalling).
PathSetSpace.intersects(ALL_PATHS, dirty); // true
PathSetSpace.intersects(interest, ALL_PATHS); // true
// ...but an empty interest never wakes — "I care about nothing".
PathSetSpace.intersects(PathSetSpace.empty(), ALL_PATHS); // false
```

`ALL_PATHS` and the `PathSet` type are the only path primitives BlaC re-exports
from `@blac/core` (for plugins composing channel subscriptions); this
type-checked block uses them directly:

```ts twoslash
import { ALL_PATHS, type PathSet } from '@blac/core';

// A plugin or devtools panel can declare blanket interest in every change.
const blanketInterest: () => PathSet = () => ALL_PATHS;
void blanketInterest;
```

The channel is identical to Stage 1; only the `Region` changed from `boolean` to
`PathSet`. `intersects` does the discrimination: iterate the smaller set, look
up in the larger, return on the first hit. That is the entire per-listener cost
of a change — no tree walk.

Where do the changed paths come from? The mutators compute them:

- **`emit(next)`** installs a new immutable state, then diffs to find which
  observed paths changed value (Stage 3 covers the skeleton bound on that diff).
- **`patch(partial)`** deep-merges a `DeepPartial<S>` and marks paths via
  `changedPathsFromPatch`: it walks the patch shape, pulses each touched branch
  up (`{ user: { email } }` marks both `user` and `user.email`), but
  **value-filters** — a path is marked only if its value actually changed, and
  recursion prunes into unchanged branches (an unchanged subtree keeps its
  reference). So an over-spread patch that re-sets a whole parent when one field
  changed does not over-wake the siblings.
- **`update(fn)`** is sugar for `emit(fn(state))`.

From the public surface, the three mutators look like this — and all type-check:

```ts twoslash
import { Cubit } from '@blac/core';

interface UserState {
  user: { name: string; email: string };
  items: string[];
}

class UserCubit extends Cubit<UserState> {
  constructor() {
    super({ user: { name: 'Ada', email: 'ada@x.io' }, items: [] });
  }

  // patch: deep-merges; marks only paths whose value actually changed.
  // Here only `user.email` moves → `user.name` consumers stay asleep.
  setEmail(email: string) {
    this.patch({ user: { email } });
  }

  // update: sugar for emit(fn(state)); replace immutably.
  addItem(item: string) {
    this.update((s) => ({ ...s, items: [...s.items, item] }));
  }

  // emit: replace the whole state.
  reset() {
    this.emit({ user: { name: '', email: '' }, items: [] });
  }
}

void UserCubit;
```

```
Stage 2: paths as interned ids

  state = { user: { name, email }, items }

  intern:  user.name → 0   user.email → 1   items → 2

  emit changes user.email   ──►  dirty = { 1 }
                                    │
                   ┌────────────────┼────────────────┐
                   ▼                ▼                 ▼
            interest {0}      interest {1}      interest {2}
            (reads name)      (reads email)     (reads items)
            ∩ {1} = ∅         ∩ {1} = {1}       ∩ {1} = ∅
            asleep            WAKE              asleep
```

:::caution[In-place mutation is invisible]
Change detection rests on reference comparison (`Object.is`) and on unchanged
subtrees keeping their references. Mutating state in place —
`state.items.push(x)` — marks nothing and wakes nobody. Always replace
immutably: `patch({ ... })` or `update(s => ({ ...s, items: [...s.items, x] }))`.
:::

What's still missing: a listener must somehow _declare_ its path set. Writing it
by hand is a selector — the exact thing BlaC avoids. Stage 3 makes the read
itself the declaration.

---

## Stage 3 — The recording proxy and the observed skeleton

A consumer declares which paths it reads by _reading them_. `trackRender(state,
interner)` wraps state in a recording `Proxy` and returns
`{ value, paths }`: `value` is the proxy you read during render, `paths` is a
**live** `Set<PathId>` that grows as you touch properties off `value`.
`trackRender` is internal (`@dirtytalk/structural`); the React adapter calls it
for you on every render, so you never import it directly. Shown here to make the
mechanism concrete:

```ts
import { PathInterner, trackRender, type PathId } from '@dirtytalk/structural';

interface State {
  user: { name: string; email: string };
  items: number[];
}

const state: State = {
  user: { name: 'Ada', email: 'ada@x.io' },
  items: [1, 2, 3],
};
const interner = new PathInterner();

const { value, paths } = trackRender(state, interner);

// Simulate what a component's render does: read the fields it displays.
void value.user.name; // records `user.name`
void value.items; // records `items`

// `paths` now holds exactly the interned ids of what was read.
const read: PathId[] = [...(paths as Set<PathId>)].sort();
read.map((id) => interner.lookup(id)); // ['items', 'user.name']
```

The recording rules are deliberate, and each one earns its keep:

- **Leaf-only (maximal) recording.** Reading `user.name` records `user.name` and
  _drops_ the intermediate `user` from the set. So when an immutable update
  replaces the whole `user` object because a _sibling_ (`user.email`) changed, a
  consumer that only read `user.name` does **not** wake — its recorded leaf
  still resolves to the same value. Read the whole `user` object (no deeper key)
  and `user` stays your leaf, so any change inside it wakes you.
- **Own, non-symbol reads only.** Symbol keys (`Symbol.iterator`) and inherited
  prototype props never record. Re-reads are idempotent (it's a `Set`).
- **Nested plain objects/arrays return child proxies** recording into the same
  set, cached per target so `value.user === value.user` within one render.
- **Iteration coarsens.** `.map` / `.find` / `for..of` on an array record the
  _entry_ path (`items`) but not per-index paths (`items.0`) or `items.length`.
  Array methods are bound to the raw target so their internal reads bypass the
  proxy. Direct index access still records the leaf: `value.items[2]` records
  `items.2`.
- **Leaf collection types are not recursed.** `Map`, `Set`, `Date`, and class
  instances are returned raw (wrapping them would rebind receiver-checked
  built-ins like `Map.prototype.get`). A reference change to the whole value
  still wakes you, but an in-place `.set()` does not.

Now the payoff. With `N` consumers sharing a container, the naive way to find
who to wake is per-consumer diffing: `N` tree walks. BlaC does **one walk plus N
intersections** instead.

The trick is the **observed skeleton**: the union of every registered consumer's
path set. On a mutation, `emit` diffs `prev` vs `next` **only along the
skeleton** — it reads each skeleton path in both states and includes it iff the
value moved (`diffAlongSkeleton`, default `Object.is`). That one walk produces
the dirty set; then each consumer wakes via a cheap set intersection (Stage 2).
Again the helpers are internal — this is the mechanism `emit` runs for you:

```ts
import {
  PathInterner,
  diffAlongSkeleton,
  pathSetUnion,
  type PathSet,
} from '@dirtytalk/structural';

interface State {
  user: { name: string; email: string };
}
const interner = new PathInterner();

// Two consumers: one reads user.name, the other reads user.email.
const consumerA: PathSet = new Set([interner.intern('user.name')]);
const consumerB: PathSet = new Set([interner.intern('user.email')]);

// The skeleton is the union of all registered consumers' interests.
const skeleton = pathSetUnion(consumerA, consumerB);

const prev: State = { user: { name: 'Ada', email: 'ada@x.io' } };
const next: State = { user: { name: 'Ada', email: 'ada@new.io' } };

// ONE diff walk, bounded to the skeleton, finds what actually moved.
const dirty = diffAlongSkeleton(prev, next, skeleton, interner);
// dirty = { user.email } — only consumerB will wake on intersection.
[...(dirty as Set<number>)].map((id) => interner.lookup(id)); // ['user.email']
```

The registry maintaining the skeleton is in `StructuralContainer`:
`registerConsumerPaths(id, paths)` stores one consumer's set and recomputes the
skeleton as the union of all of them (with a fast-path skip when the set is
unchanged); `unregisterConsumer(id)` drops one and recomputes.

```
Stage 3: one walk, then N cheap intersections

  consumerA reads {user.name}    consumerB reads {user.email}
            \                       /
             \                     /
              ▼   union           ▼
        skeleton = {user.name, user.email}
                       │
   emit(next) ─► diffAlongSkeleton(prev, next, skeleton)   ◄── the ONE walk
                       │
                       ▼
                  dirty = {user.email}
                  ┌────────────┴────────────┐
                  ▼                          ▼
          A ∩ dirty = ∅              B ∩ dirty = {user.email}
          asleep                     WAKE
```

:::note[The single-consumer skip]
The skeleton diff only pays off with 2+ consumers to share the walk across. With
0 or 1 registered consumers, `emit`/`update` skip the diff entirely and mark
`ALL_PATHS` — the sole consumer (if any) wakes regardless. Fine-grained
isolation begins at two consumers. `patch` never takes this shortcut; it always
value-diffs the patch shape, so raw `subscribe` callers wake correctly too.
:::

### How React ties in

`useBloc` (and the standalone `useStructural`) needs **no selector** because the
JSX _is_ the interest declaration. Per render it:

- derives a stable consumer id from `useId()` and forces re-renders with a
  `useReducer` tick (no virtual DOM — React reconciles);
- calls `trackRender(container.state, container.interner)`, renders against the
  proxy, and stashes the now-populated `paths` in a ref;
- registers that set in a layout effect **after** render (never in the render
  body — at that point `paths` is still empty and would freeze an empty
  skeleton, silently dropping wakeups);
- subscribes `() => pathRef.current` to the channel, so the channel re-evaluates
  the live interest on every flush and re-renders only on intersection.

Conditional reads therefore reshape the skeleton automatically, render to
render. To opt out and gate re-renders by a derived value array instead, pass
`select` to `useBloc`.

---

## Stage 4 — Cross-bloc dependencies

The final layer: one bloc leaning on another. This lives in `@blac/core`'s
`StateContainer` (the class `Cubit` extends), not in the structural engine —
deps are about _identity and lifecycle_, not path diffing.

`this.depend(OtherBloc)` declares a dependency and returns a **DepHandle**.
Calling `.untracked()` or `.track()` on the handle resolves the dependency
against the registry, so the declaring bloc never holds a stale instance
reference across dep churn:

```ts twoslash
import { Cubit } from '@blac/core';

class AuthCubit extends Cubit<{ userId: string | null }> {
  constructor() {
    super({ userId: null });
  }
  login(userId: string) {
    this.emit({ userId });
  }
}

class DashboardCubit extends Cubit<{ ready: boolean }> {
  // `depend` returns a handle resolved against the registry per call.
  private auth = this.depend(AuthCubit);

  constructor() {
    super({ ready: false });
  }

  get currentUser(): string | null {
    return this.auth.untracked().state.userId; // resolve, then read
  }
}
```

Two design points fall out of the source:

- **`depend` does not auto-resubscribe.** It records the dependency (visible via
  the `dependencies` getter) and returns a handle. It deliberately does **not**
  bridge the dep's channel into this bloc — a naive auto-bridge would cycle on
  mutual deps. A consumer that needs reactive updates from a dep subscribes
  explicitly, which in React means a component `useBloc`s both blocs and the
  Stage-3 tracker handles each independently.
- **Per-consumer deps are a separate, owner-keyed mechanism.** The
  `APPLY_DEPS` / `REMOVE_DEPS_OWNER` symbols (internal, used by the React
  adapter) let each _consumer_ inject a slice of deps keyed by an owner id;
  `StateContainer` shallow-merges all live owners' slices, dev-warns on
  cross-owner key collisions (last write wins), and fires `onDepsChanged` only
  when the merged view actually changes. This is distinct from `depend`'s
  bloc-to-bloc resolution.

```
Stage 4: deps resolve through the registry (no auto-bridge)

   DashboardCubit                          registry
        │                                      │
        │  this.depend(AuthCubit)              │
        │  ── records dep, returns handle ──►  │
        │                                      │
        │ auth.untracked() ─ ensure(AuthCubit)►│ ── returns the live
        │                                      │    AuthCubit instance
        │  ◄──────────── instance ──────────── │
        ▼
   reads dep.state  (reactivity, if wanted, is the consumer's job
                     via Stages 1–3 on each bloc independently)
```

`StateContainer` adds the rest of the lifecycle around these four stages:
identity (`$blac.name`, `$blac.id`), disposal, hydration, an
`onSystemEvent('stateChanged' | 'dispose' | 'hydrationChanged', cb)` surface,
and a dev-only emit-rate circuit breaker that warns once when a runaway loop
pushes too many changes through state in a second. But the reactivity itself is
the four stages above: a coalescing channel, interned paths, a recording proxy
feeding an observed skeleton, and a registry resolving cross-bloc deps.

---

## Putting it together: one update, end to end

A single `emit` flows through all four stages:

1. A method calls `emit` / `update` / `patch`. `StateContainer` runs its guards
   (disposed, equality short-circuit, emit-rate check), captures the
   `prev`/`next` change, and delegates change-detection to
   `StructuralContainer`. (Stage 1 + 4 wrapper.)
2. The container installs the new immutable state and computes the dirty
   `PathSet` — `diffAlongSkeleton` against the observed skeleton for `emit`,
   `changedPathsFromPatch` for `patch` — then `channel.mark(dirty)`.
   (Stage 2 + 3.)
3. The `DirtyChannel` coalesces marks and schedules one flush per tick. (Stage 1.)
4. On flush, each subscriber's interest thunk is evaluated and intersected with
   the dirty set; only consumers with a non-empty intersection have their
   callback fired (React re-render, `watch` callback, plugin sink). (Stage 1 + 2.)
5. On the next render, the proxy re-records each consumer's interest from
   scratch, so conditional reads reshape the skeleton automatically. (Stage 3.)

The practical takeaway is the same sentence the whole machine exists to make
true, cheaply: **read exactly the state you render, keep state immutable, and
BlaC re-renders the minimum.**

## See also

- [Mental Model](/guide/mental-model) — the design narrative behind these stages.
- [Tracking](/core/tracked) — the React-time recording rules in reference form.
- [Dependency Tracking](/react/dependency-tracking) — `select` and what does/doesn't register.
- [`@dirtytalk/structural` Concepts](/dirtytalk/structural/concepts) — the standalone, engine-backed distillation.
- [System Events](/core/system-events) — `stateChanged` / `dispose` lifecycle hooks.

---

# What is BlaC?

> BlaC is a TypeScript state management library for React that separates business logic into class-based, auto-tracked state containers.

Source: /guide/introduction/

:::caution[Beta / pre-release]
BlaC v2 is in pre-release (beta). While in beta, **breaking API changes may ship in patch releases** without a major version bump — pin exact versions and check the changelog before upgrading. Strict semver resumes once v2 is officially out of beta.
:::

BlaC (Business Logic Components) is a TypeScript state management library for React. It separates business logic into class-based state containers — [Cubits](/guide/glossary#core-model) — that are type-safe, testable, and automatically optimized for minimal re-renders.

A first taste — the whole loop in one screen:

```tsx twoslash
import React from 'react';
import { Cubit } from '@blac/core';
import { useBloc } from '@blac/react';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  increment = () => this.emit({ count: this.state.count + 1 });
}

function Counter() {
  const [state, counter] = useBloc(CounterCubit);
  return <button onClick={counter.increment}>Count: {state.count}</button>;
}
```

No store setup, no provider, no reducer, no selector. The class holds the logic; the hook connects it; re-renders are tracked automatically.

That snippet isn't a screenshot — here it is running, the real `@blac/react` hook driving a real `Cubit`. The badge counts how many times the component has actually rendered:

<CounterDemo client:visible />

## Why BlaC?

Most state management libraries force you to choose between simplicity and power. Simple hooks-based solutions scatter logic across components. Powerful libraries require boilerplate, providers, and context wrappers.

BlaC takes a different approach:

- **State logic lives in classes, not components.** Define your state shape and mutations in a `Cubit` class. Components just read state and call methods.
- **No providers or context wrappers.** Import your class, call `useBloc(MyClass)`, and you're connected. The registry handles instance creation and sharing automatically.
- **Re-renders are precise by default.** Auto-tracking proxies detect which state properties your component reads during render. Only changes to those properties trigger re-renders.
- **Lifecycle is declarative.** Instances are shared by default. Use `args` (with a `static key`) for named per-component instances or `@blac({ keepAlive: true })` for persistent singletons.
- **Built for TypeScript.** State types flow from your class definition through the hook return value with zero type annotations needed.

Two components share one bloc — each reads a different field. Increment the count or edit the label: only the component reading the changed field re-renders.

<RenderCounterDemo client:visible />

:::note[How does this compare to Redux / Zustand / Jotai / MobX?]
The short version: BlaC keeps logic in classes (like flutter_bloc), shares instances through a ref-counted registry (no providers), and tracks re-renders with a render-time proxy (no selectors or `useMemo`). The honest, side-by-side comparison — including where those other libraries are the better fit — lives on the [Comparison](/guide/comparison) page.
:::

## Architecture

BlaC has two layers:

```text
┌─────────────────────────────┐
│  React        useBloc hook  │  Framework-specific binding,
│               BlocProvider  │  path-scoped channel subscriptions
├─────────────────────────────┤
│  Core         Cubit,        │  State containers, registry,
│               Registry,     │  plugins, watch, path-based
│               Plugins       │  dirty tracking
└─────────────────────────────┘
```

**Core** (`@blac/core`) provides state containers, a global registry with ref counting, a plugin system, and utilities like `watch`. Proxy-based dependency tracking is built in — no separate adapter package is needed.

**React** (`@blac/react`) provides the `useBloc` hook. It subscribes each component to the bloc's path-scoped channel and re-renders through React's normal update path when a tracked read path changes. The optional `BlocProvider` shown above scopes default `args` to a subtree — most apps never need it (see [useBloc](/react/use-bloc) for when it helps).

<details>
<summary>Under the hood: the DirtyTalk engine family</summary>

The "what changed, who cares, when do we tell them" machinery — path-based dirty tracking, the render-time proxy, microtask-batched flushing — lives in a lower-level, framework-agnostic family of packages called [DirtyTalk](/dirtytalk/). BlaC's `StateContainer` extends `@dirtytalk/structural`'s container; you never need to touch it directly, but it's there if you want to understand the foundation.

</details>

## When to use BlaC

BlaC works best when:

- You have **complex state logic** that benefits from being in a class (validation, derived state, async operations)
- Multiple components need to **share state** without prop drilling or context providers
- You want **testable business logic** that can run without React
- You value **TypeScript inference** and want the compiler to catch state errors

:::tip[When you probably don't need BlaC]
If a piece of state lives in exactly one component and never travels, `useState` is the right tool — reach for BlaC when state is _shared_, _complex_, or _worth testing without React_. BlaC adds value as state complexity grows, not at the first `useState`.
:::

## What's next?

- [Quick Start](/guide/getting-started) — Install BlaC and build your first component
- [Core Concepts](/guide/concepts) — A quick tour of the mental model
- [Mental Model](/guide/mental-model) — The deep "why it works this way," plus honest comparisons
- [Patterns & Recipes](/guide/patterns) — Common patterns for real apps
- [useBloc Hook](/react/use-bloc) — Full hook reference

## See also

- [Mental Model](/guide/mental-model) — how auto-tracking, the registry, and batching actually work
- [Quick Start](/guide/getting-started) — go from install to working component
- [Glossary](/guide/glossary) — one-line definitions for every term used here

---

# Mental Model

> The deep reasoning behind BlaC — the reactivity model, the per-consumer tracker, ref-counted lifecycle, and the full mount-to-unmount lifecycle.

Source: /guide/mental-model/

This is the page for understanding _why_ BlaC works the way it does. If you want a fast orientation — the names of things and a one-screen tour — read [Core Concepts](/guide/concepts) first; it is the quick tour. This page is the deep version: the reactivity model end to end, the design choices behind it, honest comparisons to other libraries, and the full data-flow lifecycle from mount to unmount.

Most of the surprising-at-first behavior in BlaC falls out of a single idea: **a component declares what it depends on by reading it, and BlaC wakes that component only when one of those exact reads would now produce a different value.** Everything else — proxies, path sets, ref counting, the registry — exists to make that one sentence true, cheaply, without you writing selectors.

## The reactivity model

### The problem auto-tracking solves

Connect a component to a shared store and the default behavior of most subscription models is: _the store changed, so re-render the subscriber._ That is correct but wasteful. A container with twenty fields will wake a component that reads one of them nineteen times for nothing.

The usual fixes push work onto you. Selectors (`useSelector(s => s.user.name)`) make you name your dependency by hand and keep it in sync as the component evolves. Memoized derivations (`useMemo`, `reselect`) make you declare input arrays. `React.memo` makes you reason about prop identity. All of these work; all of them are a second copy of "what this component reads" that can drift from the JSX, which is the real source of truth.

BlaC's answer: **the JSX is the dependency declaration.** You read `state.name` in render; that read _is_ the subscription. Nothing to keep in sync, because there is only one copy.

### Read → track → intersect-on-change → re-render

The mechanism is a loop with four stops. Walk it concretely with a `UserCubit` whose state is `{ name, email, address: { city } }`.

**1. Read.** The `state` you get back from `useBloc` is not the raw state object — it is a recording `Proxy`. Built each render by `trackRender(rawState, bloc.interner)`, it returns a proxy plus a live `Set` of the paths read through it.

```tsx
function UserName() {
  const [state] = useBloc(UserCubit);
  return <span>{state.name}</span>; // reads the path "name"
}
```

**2. Track.** Each property access on the proxy records the path it touched. The recording is **leaf-only**: reading `state.address.city` records exactly `address.city`, not `address`. Reading a deeper path drops its immediate parent from the set. This is what gives you sibling isolation — a component reading `address.city` is not woken when `address.zip` changes, even though both live under the same parent object that got replaced. After the render commits, BlaC registers the recorded set as this consumer's "interest" (in a `useLayoutEffect`, after the proxy has actually been read — never during render, when the set is still empty).

**3. Intersect on change.** When something calls `emit`, `patch`, or `update`, BlaC computes a **dirty set** — the paths whose values actually changed — and asks one question per consumer: _does this consumer's recorded interest intersect the dirty set?_ That is a cheap set-membership check, not a tree walk. The expensive part (figuring out what changed) happens **once per mutation**, not once per consumer.

**4. Re-render.** Only consumers whose interest intersects the dirty set re-render. `UserName` re-renders when `name` changes; it stays still when `email` or `address.city` change. On that re-render, step 1 runs again — so if a conditional branch now reads a different field, the tracked set reshapes itself automatically.

```text
   emit / patch / update
            │
            ▼
   ┌──────────────────┐
   │ compute dirty set │   one diff per mutation
   │ { "name" }        │   (not per consumer)
   └──────────────────┘
            │
   ┌────────┴─────────────────────────────┐
   │ for each consumer: interest ∩ dirty?  │   cheap set checks
   ├───────────────────────────────────────┤
   │ UserName     {name}        ∩ → wake    │
   │ UserEmail    {email}       ∩ → skip    │
   │ CityLabel    {address.city}∩ → skip    │
   └───────────────────────────────────────┘
```

The demo below puts this loop into motion. `CountReader` tracks only `state.count`; `LabelReader` tracks only `state.label`. The render badge on each component increments only when its tracked field changes — the other stays still.

<RenderCounterDemo client:visible />

### Each useBloc call gets its own tracker

There is **one proxy and one recorded path set per `useBloc` call site**, not one shared per bloc. Two components reading the same `UserCubit` get two independent trackers with two independent interest sets. That is the whole point: re-render isolation is per consumer, so `UserName` and `UserEmail` can subscribe to the same instance and wake on different changes.

:::caution[Per-consumer tracking, not a shared proxy]
The proxy and tracker are created per `useBloc` call and torn down with it. There is deliberately no global "proxy cache" keyed by bloc — a shared proxy would force a shared interest set and collapse the isolation. If you are reading the source: each consumer has its own `pathRef` and its own channel subscription whose interest is `() => pathRef.current`.
:::

### Why one diff, not N diffs

When many components share a container, computing "what changed" separately for each one re-does the same equality checks N times — quadratic in consumer count exactly when you have the most consumers. BlaC inverts it: maintain one **skeleton** (the union of every live consumer's interest), diff the change once bounded to that skeleton, then settle each consumer with a set intersection. One walk plus N cheap intersections.

This is not a BlaC-specific trick; it is the core algorithm of the [`@dirtytalk/structural`](/dirtytalk/structural/concepts) engine that BlaC's `StateContainer` extends. If you want the path-interning, skeleton, and proxy-recorder internals in full — including the exact recording rules for arrays, `Map`/`Set`/`Date`, and iteration — that page is the source of truth. The short version of the recording rules:

- **Leaf-only:** `a.b.c` records `a.b.c`, not `a.b`.
- **Iteration coarsens:** `.map`/`for..of`/`.find` over `state.items` records `items`, not per-index paths. Direct index access (`state.items[2].name`) records the leaf.
- **Leaf collection types are not recursed:** `Map`, `Set`, `Date`, and class instances are leaves — a change is seen only as a reference change at that value's own path.

### Two modes, chosen by presence of `select`

There is no `autoTrack` flag. A consumer is in one of two modes, decided purely by whether you pass a `select` callback:

| Mode                                       | How interest is set                                       | Re-renders when                                        |
| ------------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------ |
| **Auto-track** (default, `select` omitted) | Proxy records the paths you read in render                | A read path's value changes                            |
| **`select` provided**                      | You return an array; subscription interest is `ALL_PATHS` | The returned array differs per-index (via `Object.is`) |

`select` is the deliberate opt-out: you trade automatic per-path tracking for an explicit array, useful when you want to depend on a computed value or narrow a noisy read. It must be referentially stable (wrap it in `useCallback`) — a fresh function each render re-keys the subscription. See [Dependency Tracking](/react/dependency-tracking) for the decision guide and [useBloc](/react/use-bloc) for the full option list.

## Why these design choices

Each of BlaC's load-bearing decisions answers a specific failure mode of the alternatives.

### Classes for business logic

A Cubit is a class because business logic wants **encapsulation and methods**. State shape, the mutations that change it, derived values (getters), and async flows live in one cohesive unit:

```ts
class CartCubit extends Cubit<{ items: Item[] }> {
  constructor() {
    super({ items: [] });
  }
  add = (item: Item) => this.patch({ items: [...this.state.items, item] });
  get total() {
    return this.state.items.reduce((n, i) => n + i.price, 0);
  }
}
```

The payoff is testability: a Cubit has no dependency on React, the DOM, or hooks. You construct it, call methods, and assert on `state` directly. Compare this to logic spread across reducers, action creators, thunks, and selectors — three files for one concern. The class keeps the concern in one place, and `instanceof Cubit` works because `Cubit` is a real class (it extends `StateContainer`; there is **no** `Bloc` class).

### No context providers — a registry instead

The cost of React Context for shared state is structural: every shared value needs a provider somewhere above its consumers, providers nest, and a context change re-renders the whole subtree unless you split contexts by hand. BlaC removes the tree dependency entirely. A global **registry** maps each class (plus an optional instance key) to one instance:

```tsx
// no <CartProvider> anywhere — just import and use
const [state, cart] = useBloc(CartCubit);
```

Two components calling `useBloc(CartCubit)` get the same instance because the registry hands back the same object, regardless of where they sit in the tree. Sharing is by _identity in a registry_, not by _position under a provider_. You can still scope an instance to a subtree when you want to — distinct `args` (or a `BlocProvider` supplying default `args` to descendants) keys a distinct instance — but that is opt-in, not the price of admission.

### Ref-counted lifecycle — automatic disposal

If instances live in a global registry, who frees them? A naive global store leaks: instances accumulate and never die. BlaC solves this with **reference counting**. Every `useBloc` call increments a ref on mount and releases it on unmount. When the count hits zero, the instance is **automatically disposed** and dropped from the registry — and disposal cascades to `ensure`-created dependencies that now also have zero refs.

This is the lifecycle most context-free stores make you manage by hand. You only override it deliberately: `@blac({ keepAlive: true })` opts an instance out of auto-disposal so it survives at refcount zero (an app-wide singleton like auth or theme). Full registry-verb table lives in [Instance Management](/core/instance-management).

### The args / deps separation

Inputs to a bloc come in two flavors with opposite requirements, and conflating them causes subtle bugs:

- **`args`** is _serializable identity data_ — the user id whose data this bloc holds. It is forwarded to `init(args)` and used to compute the instance key, so two `useBloc(UserCubit, { args: { id: 7 } })` calls share one instance and a different id gets a different instance. Because it keys identity, `args` **must be serializable** (a function in `args` throws — put it in deps).
- **`deps`** is _non-serializable, per-consumer handles_ — callbacks, API clients, refs. These must **not** affect identity (a shared instance can't have one identity per callback), so they are merged per consumer rather than baked into the key.

Keeping these lanes separate is what lets a single shared instance accept per-consumer wiring without an override race (two consumers fighting over one value). The `args` lane is a first-class `useBloc` option and the sole source of instance identity; the `deps` runtime mechanism on `StateContainer` is currently internal and not exposed as a `useBloc` option in the React surface. The motivation and full mechanics live in [Inputs: args and deps](/guide/inputs).

### Immutable emit

Change detection in step 3 relies on reference comparison — a path is "dirty" when its value is no longer `Object.is`-equal to before, and an _unchanged_ subtree is recognized by keeping its reference. That contract only holds if state is replaced immutably. So every mutator (`emit`, `patch`, `update`) installs a **new** value; none mutates in place, and there is no primitive that does.

:::caution[In-place mutation is invisible]
`this.state.items.push(x)` wakes no one. The array reference did not change, so its path is not dirty. Always replace: `this.patch({ items: [...this.state.items, x] })` or `this.update(s => ({ ...s, items: [...s.items, x] }))`. This is the single most common cause of "my component isn't updating" — see [Troubleshooting](/guide/troubleshooting).
:::

A related consequence: mutations are **coalesced per microtask**. Several `emit`/`patch` calls in the same tick produce one flush — `prev` snapshotted at the first change, `next` at flush time — so consumers and plugins see one consistent transition instead of intermediate frames. This is a batching-for-consistency choice, not just performance: nobody observes a half-applied multi-field update.

## Honest comparisons

BlaC borrows liberally and differs deliberately. Its distinctive bet is **transparent reactivity (like MobX) over immutable snapshots (like Redux), with no provider and automatic lifecycle (unlike both)** — the granularity of an atom library without managing atoms, the testability of a class without the reducer boilerplate. And when your problem is genuinely a serializable event log, a tree-scoped config value, or a handful of `useState` hooks, the honest answer is that another tool fits better.

The full side-by-side — the rubric table, the Zustand/Jotai/BlaC counter written three ways, the "reach for it instead when" column for Redux, MobX, Context, and atoms, plus the decision guide — lives on the [Comparison](/guide/comparison) page, which is the canonical home for positioning.

## The full lifecycle: mount to unmount

Putting it together, here is what one `useBloc(UserCubit, { args: { id: 7 } })` call does across its life.

```text
MOUNT
  1. resolve instance key   static key(args)? → structural key from args
                            → provider context args → "default"
  2. acquire(UserCubit, { args, refId })
       ├─ exists?  → return it, refs[refId]++          (share)
       └─ new?     → new UserCubit(); registry configures instance;
                     init(args) runs once; refs = 1     (create)
  3. first render: trackRender wraps state → proxy + empty path set
  4. you read state.name in JSX → path "name" recorded
  5. useLayoutEffect: registerConsumerPaths(consumerId, { "name" })
  6. useEffect: subscribe(() => pathRef.current) to the channel
  7. onMount(bloc) fires

LIVE
  · a method calls emit/patch/update
  · changes coalesce within the microtask → one flush
  · dirty set computed once → intersected with each consumer's interest
  · matching consumers re-render → trackRender runs again →
    interest reshapes if reads changed
  · stateChanged / plugin onStateChange fire per flush

UNMOUNT
  8. onUnmount(bloc) fires      (bloc still alive here)
  9. release(UserCubit, { args, refId })  → refs[refId]--
 10. refs.size === 0 && !keepAlive?
       ├─ yes → dispose(): 'dispose' event, channel torn down,
       │         registry entry removed, cascade-dispose zero-ref deps
       └─ no  → instance stays (another consumer, or keepAlive)
 11. consumer's tracker + subscription torn down
```

Two details worth internalizing:

- **Acquire/release agree on the key.** The same resolved instance key is used for both, so the bloc you acquired is the bloc you release. Get the key wrong (e.g. a non-serializable value in `args` producing a new key every render) and you create-and-dispose a fresh instance per render — the classic "new instance every render" symptom.
- **`onUnmount` runs before `release`.** The bloc is still alive inside `onUnmount`, so you can read its final state there; only after does the ref drop and disposal possibly fire.

## See also

- [Core Concepts](/guide/concepts) — the quick tour this page goes deep on
- [Dependency Tracking](/react/dependency-tracking) — auto-track vs `select` in practice
- [Inputs: args and deps](/guide/inputs) — the input lanes and identity precedence
- [Structural: Concepts](/dirtytalk/structural/concepts) — the path-tracking engine BlaC is built on

---

# Patterns & Recipes

> Concrete, copy-pasteable patterns for async operations, named instances, cross-bloc communication, plugins, keep-alive, and getter-based computed values.

Source: /guide/patterns/

Common patterns for structuring BlaC applications. Each pattern is drawn from real examples in the codebase.

:::note[Recipes vs. principles]
This page is a **cookbook**: concrete, copy-pasteable solutions to recurring problems. For the _principles_ behind these choices — when to reach for one approach over another, and the smells to avoid — see [Best Practices](/guide/best-practices). Rule of thumb: come here when you know _what_ you want to build; go there when you're deciding _whether_ an approach is sound.
:::

## Async operations

### Loading / error / success

Model async state explicitly. Use a request ID to handle race conditions when multiple requests overlap.

```ts
interface FeedState {
  articles: Article[];
  status: 'idle' | 'loading' | 'error' | 'success';
  error: string | null;
}

class FeedCubit extends Cubit<FeedState> {
  private requestId = 0;

  constructor() {
    super({ articles: [], status: 'idle', error: null });
  }

  loadArticles = async (category: string) => {
    const id = ++this.requestId;
    this.patch({ status: 'loading', error: null });

    try {
      const articles = await api.fetchArticles(category);
      // Ignore stale responses
      if (id !== this.requestId) return;
      this.emit({ articles, status: 'success', error: null });
    } catch (e) {
      if (id !== this.requestId) return;
      this.patch({ status: 'error', error: String(e) });
    }
  };
}
```

The `requestId` pattern is simpler than AbortController for most cases. Each new call invalidates previous in-flight responses. Modelling async state as an explicit `status` enum (rather than scattered `isLoading`/`error` booleans) is a principle covered in [Best Practices](/guide/best-practices).

### Hydration-aware loading

When using the [persistence plugin](/plugins/persistence), state may arrive asynchronously from IndexedDB. Override `init` and `await this.$blac.hydration.wait()` before making API calls, so you don't overwrite restored values with a stale fetch:

```ts
class SettingsCubit extends Cubit<SettingsState> {
  constructor() {
    super({ theme: 'light', locale: 'en' });
  }

  protected override async init() {
    await this.$blac.hydration.wait();
    // Now this.state has restored values from IndexedDB
    await this.refreshFromServer();
  }
}
```

`init` is the framework's once-per-instance setup hook — a protected method called after construction, before the first state snapshot, with the bloc's `args`. `$blac.hydration.wait()` resolves once the persistence plugin finishes restoring (or immediately if nothing is persisted); see [system events](/core/system-events) for the `hydrationChanged` event that drives it.

## Action-only components

Components that only trigger actions and never display state do not need a selector. Just avoid reading from `state`: auto-tracking records an empty dependency set, so state changes have nothing to wake.

```tsx
function QuickAdd() {
  const [, todo] = useBloc(TodoCubit);

  return <button onClick={() => todo.addItem('New item')}>Add Item</button>;
}
```

This component renders once and never re-renders, regardless of state changes.

:::tip[Use `select` for derived dependencies]
Reach for `select` when a computed value or explicit dependency list should drive re-renders. Do not use it just to make an action-only component quiet. See [Performance](/react/performance) for the full reader/writer split rationale and [useBloc](/react/use-bloc) for `select` semantics.
:::

## Named instances

When you need multiple independent instances of the same Cubit class, make the distinguishing name an `args` field and key on it with `static key`. Each name gets its own instance with its own state and lifecycle.

```tsx
class FormCubit extends Cubit<FormState, { section: string }> {
  static key = (a: FormCubit['args']) => a.section;
}

function FormPage() {
  return (
    <>
      <FormSection section="billing" />
      <FormSection section="shipping" />
    </>
  );
}

function FormSection({ section }: { section: string }) {
  const [state, form] = useBloc(FormCubit, { args: { section } });
  // Each section has independent state
  return (
    <input
      value={state.email}
      onChange={(e) => form.setEmail(e.target.value)}
    />
  );
}
```

Named instances are ref-counted independently. When all components using `"billing"` unmount, that instance is disposed while `"shipping"` stays alive.

The name (`"billing"` / `"shipping"`) is just as much `args` data as a `userId` or `docId` would be — there is no separate key channel. See [Passing Inputs](/guide/inputs) for the full identity model.

## Persisting state outside React

Use [`watch`](/core/watch) to observe state changes from non-React code — saving to localStorage, syncing to a server, or feeding analytics. The callback receives the **bloc instance** (read its state via `bloc.state`), fires once immediately, then on every change:

```ts
import { watch } from '@blac/core';

watch(TodoCubit, (bloc) => {
  localStorage.setItem('todos', JSON.stringify(bloc.state.items));
});
```

`watch` resolves the instance via `ensure` (no ref count, so it does not keep the bloc alive) and observes all of its state.

To stop watching, either call the returned function or return `watch.STOP` from the callback:

```ts
const stop = watch(AuthCubit, (bloc) => {
  if (bloc.state.user) {
    analytics.identify(bloc.state.user.id);
    return watch.STOP; // one-shot
  }
});
```

## Cross-bloc communication

The recipes below are the common shapes; [Bloc Communication](/core/bloc-communication) is the full reference for `depend()` and its lifecycle caveats, and [Best Practices](/guide/best-practices) covers when cross-bloc coupling is a smell versus a clean dependency.

### Reading state from another bloc

Use `depend()` to declare a dependency. It returns a handle that resolves the instance from the registry on demand — `.untracked()` for a plain read.

```ts
class CartCubit extends Cubit<CartState> {
  private shipping = this.depend(ShippingCubit);

  get total() {
    const subtotal = this.state.items.reduce((sum, i) => sum + i.price, 0);
    return subtotal + this.shipping.untracked().state.rate;
  }
}
```

### Auto-tracking a dependency with `.track()`

A plain `.untracked()` read (`this.shipping.untracked().state.rate`) is _not_ reactive on its own — a component reading `cart.total` only re-renders on shipping changes if it _also_ calls `useBloc(ShippingCubit)`. Calling `.track()` on the handle removes that ceremony: the component reading the getter auto-subscribes to the dependency too.

```ts
class CartCubit extends Cubit<CartState> {
  private shipping = this.depend(ShippingCubit);

  get total() {
    const subtotal = this.state.items.reduce((sum, i) => sum + i.price, 0);
    const [shippingState] = this.shipping.track(); // opt in to cross-bloc reactivity
    return subtotal + shippingState.rate;
  }
}
```

```tsx
// The component subscribes to CartCubit only — yet re-renders when shipping changes too.
function CartTotal() {
  const [, cart] = useBloc(CartCubit);
  return <strong>${cart.total.toFixed(2)}</strong>;
}
```

`.track()` is render-aware (outside render it degrades to live values, no subscription), tracks the dependency's own getters transitively, and supports conditional and mutual dependencies. See [Auto-tracking with `.track()`](/core/bloc-communication#auto-tracking-with-track) for the full reference.

### Triggering side effects across blocs

Call methods on dependencies to coordinate behavior:

```ts
class ChannelCubit extends Cubit<ChannelState> {
  private notifications = this.depend(NotificationCubit);

  receiveMessage = (message: Message) => {
    this.patch({ messages: [...this.state.messages, message] });
    this.notifications.untracked().incrementUnread(this.state.channelId);
  };
}
```

### Lazy instance creation

When a dependency might not exist yet, use `borrowSafe` to check and `acquire` to create on demand:

```ts
import { borrowSafe, acquire } from '@blac/core';

class ChannelCubit extends Cubit<ChannelState> {
  private ensureUserCubit(userId: string) {
    const { error } = borrowSafe(UserCubit, { args: { userId } });
    if (!error) return;
    acquire(UserCubit, { args: { userId } }); // keyed by userId; init seeds state
  }

  receiveMessage = (message: Message) => {
    this.ensureUserCubit(message.userId);
    // ...
  };
}
```

## Saving state on disposal

Use `onSystemEvent('dispose')` to persist data when an instance is cleaned up:

```ts
class ChannelCubit extends Cubit<ChannelState> {
  constructor() {
    super({ channel: null, messages: [] });
    this.onSystemEvent('dispose', () => {
      if (this.state.channel) {
        persistenceService.save(this.state.channel.id, this.state.messages);
      }
    });
  }
}
```

## Custom plugins

Plugins observe lifecycle events across all state containers. Use them for cross-cutting concerns like analytics, logging, or monitoring. Every hook takes the `PluginContext` first; the bloc the event is about is `ctx.container`, and `prev`/`next` in `onStateChange` are the **state objects**, not the bloc:

```ts
const analyticsPlugin: BlacPlugin = {
  name: 'analytics',
  version: '1.0.0',

  onCreated(ctx) {
    analytics.track('bloc_created', { name: ctx.container?.name });
  },

  onStateChange(ctx, prev, next, paths) {
    analytics.track('state_changed', {
      name: ctx.container?.name,
      from: prev,
      to: next,
    });
  },

  onDestroyed(ctx) {
    analytics.track('bloc_disposed', { name: ctx.container?.name });
  },
};

getPluginManager().install(analyticsPlugin);
```

See [Plugin Authoring](/core/plugins) for the full hook reference, the `paths` parameter, and the `environment` option (skip a plugin outside `development`, for example).

## Keep-alive instances

For app-wide singletons that should never be disposed (auth, theme, feature flags), use `keepAlive`:

```ts
@blac({ keepAlive: true })
class ThemeCubit extends Cubit<{ mode: 'light' | 'dark' }> {
  constructor() {
    super({ mode: 'light' });
  }

  toggle = () => {
    this.patch({ mode: this.state.mode === 'light' ? 'dark' : 'light' });
  };
}
```

The instance is created on first use and stays alive for the entire app session, even if all components using it unmount. `keepAlive` only disables the _auto-dispose at refcount zero_; the instance is still disposable via `clear()` or a forced release. See [Configuration](/core/configuration) for the option and [Instance Management](/core/instance-management) for how ref-counting and auto-dispose interact.

## Per-component private instances

When a component needs its _own_ instance — never shared with siblings, disposed when it unmounts — add a per-mount unique value to `args` and key on it with `static key`. `useId()` is the idiomatic source of a stable-per-mount value:

```tsx
import { useId } from 'react';

class UploadCubit extends Cubit<UploadState, { _id: string }> {
  static key = (a: UploadCubit['args']) => a._id;
}

function UploadWidget() {
  const _id = useId(); // unique per mount, stable across this mount's renders
  const [state, upload] = useBloc(UploadCubit, { args: { _id } });

  return <progress value={state.progress} max={100} />;
}
```

Two `<UploadWidget />` siblings get two independent instances; each is disposed on its own unmount. This is the supported replacement for the removed `autoInstance`/`instanceId` options. Any real identity data goes in the same `args` object alongside `_id` — see [Passing Inputs](/guide/inputs).

## Getter-based computed values

Define getters on your Cubit for derived state instead of storing the computed value in state. In React render, getters auto-track: reading `todo.activeCount` records the `this.state` paths the getter touches through the returned bloc proxy. Use `select` when you want the getter's return value, rather than its source paths, to decide re-renders. See [Performance: getters as computed properties](/react/performance#pattern-getters-as-computed-properties).

```ts
class TodoCubit extends Cubit<TodoState> {
  get activeCount() {
    return this.state.items.filter((t) => !t.done).length;
  }

  get completedCount() {
    return this.state.items.filter((t) => t.done).length;
  }

  get filteredItems() {
    if (this.state.filter === 'all') return this.state.items;
    const isDone = this.state.filter === 'done';
    return this.state.items.filter((t) => t.done === isDone);
  }
}
```

```tsx
function TodoStats() {
  const [, todo] = useBloc(TodoCubit);
  return (
    <span>
      {todo.activeCount} active, {todo.completedCount} done
    </span>
  );
}

// Or use `select` so the getter results gate re-renders:
function TodoStatsSelected() {
  const [, todo] = useBloc(TodoCubit, {
    select: (_, bloc) => [bloc.activeCount, bloc.completedCount],
  });
  return (
    <span>
      {todo.activeCount} active, {todo.completedCount} done
    </span>
  );
}
```

:::tip[Derive, don't duplicate]
Storing `activeCount` _in state_ alongside `items` means every mutation has to remember to update both — they drift. A getter computes on read and can never go stale. Best Practices treats "derive with getters, don't store computed values" as a core principle.
:::

## More recipes

The patterns above cover the core primitives. The recipes below handle common
higher-level scenarios — each is a self-contained page with a twoslash-checked
Cubit block and a plain TSX component example:

- [Optimistic Update](/guide/recipes/optimistic-update) — apply a mutation immediately, roll back on error
- [Debounce](/guide/recipes/debounce) — collapse rapid input into a single deferred action
- [Undo / Redo](/guide/recipes/undo-redo) — past/future state stacks with a history cap
- [Pagination](/guide/recipes/pagination) — offset/page and cursor-based infinite scroll
- [WebSocket Subscription](/guide/recipes/websocket) — persistent server-pushed connections
- [Form Validation](/guide/recipes/form-validation) — touched map, getter-derived errors, async submit
- [Reset to Initial State](/guide/recipes/reset-to-initial) — one-call full or partial reset

## See also

- [Best Practices](/guide/best-practices) — the principles behind these recipes
- [Performance](/react/performance) — reader/writer splitting and proxy-cost mechanics
- [Bloc Communication](/core/bloc-communication) — full `depend()` reference and lifecycle caveats
- [Instance Management](/core/instance-management) — ref-counting, `keepAlive`, and auto-dispose
- [Passing Inputs](/guide/inputs) — `args`, `deps`, and per-mount instances
- [Cubit](/core/cubit) — `init`, `emit`/`patch`/`update`, and getters

---

# Debounce

> Collapse rapid user input into one deferred Cubit action by storing the debounce timer as a private field and clearing it on dispose.

Source: /guide/recipes/debounce/

**Use when:** you want to collapse rapid user input (search-as-you-type, resize,
window scroll) into one deferred action to avoid hammering the server or doing
expensive work on every keystroke.
**Don't use when:** the action must fire immediately on the first event and you
only want to throttle subsequent ones — use throttle instead.

## Pattern

Store the debounce timer as a private field on the Cubit and cancel it before
scheduling a new one. No external debounce library is needed.

```ts twoslash
import { Cubit } from '@blac/core';

interface SearchResult {
  id: string;
  title: string;
}

interface SearchState {
  query: string;
  results: SearchResult[];
  status: 'idle' | 'loading' | 'success' | 'error';
  error: string | null;
}

declare const api: {
  search(q: string): Promise<SearchResult[]>;
};
// ---cut---
class SearchCubit extends Cubit<SearchState> {
  // Timer handle for the pending debounced call.
  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
  private requestId = 0;

  constructor() {
    super({ query: '', results: [], status: 'idle', error: null });

    // Cancel any in-flight timer when the instance is disposed.
    this.onSystemEvent('dispose', () => {
      if (this.debounceTimer !== null) clearTimeout(this.debounceTimer);
    });
  }

  setQuery = (query: string) => {
    // Update the input field immediately so the UI feels responsive.
    this.patch({ query, status: 'idle' });

    // Cancel the previous pending search.
    if (this.debounceTimer !== null) clearTimeout(this.debounceTimer);

    if (!query.trim()) {
      this.patch({ results: [], status: 'idle' });
      return;
    }

    // Schedule the actual fetch after 300 ms of silence.
    this.debounceTimer = setTimeout(() => {
      void this.fetchResults(query);
    }, 300);
  };

  private fetchResults = async (query: string) => {
    const reqId = ++this.requestId;
    this.patch({ status: 'loading', error: null });

    try {
      const results = await api.search(query);
      if (reqId !== this.requestId) return; // superseded by a newer call
      this.patch({ results, status: 'success' });
    } catch (e) {
      if (reqId !== this.requestId) return;
      this.patch({ results: [], status: 'error', error: String(e) });
    }
  };
}
```

```tsx
function SearchBox() {
  const [state, search] = useBloc(SearchCubit);

  return (
    <div>
      <input
        value={state.query}
        onChange={(e) => search.setQuery(e.target.value)}
        placeholder="Search…"
      />
      {state.status === 'loading' && <p>Searching…</p>}
      <ul>
        {state.results.map((r) => (
          <li key={r.id}>{r.title}</li>
        ))}
      </ul>
    </div>
  );
}
```

:::caution[Cancel on dispose]
If the debounce timer fires after the Cubit is disposed, it will attempt to
`emit` on a dead container and throw. Always clear the timer in the `dispose`
system event, as shown above.
:::

:::tip[Combine with the request-id guard]
The timer collapses keystrokes, but two timers can still fire close together.
The `requestId` guard (shown in `fetchResults`) ensures only the last response
is applied. See [Async](/guide/async#the-request-id-guard) for the full pattern.
:::

## See also

- [Async](/guide/async) — request-id guard and cancellation with `AbortController`
- [System Events](/core/system-events) — `dispose` event for cleanup

---

# Form Validation

> Model form fields and a touched map in Cubit state, derive validation errors as a getter, and show errors only for touched fields.

Source: /guide/recipes/form-validation/

**Use when:** a form has non-trivial cross-field validation rules, async field-level
checks (e.g. "username already taken"), or multi-step workflows that share state
across steps.
**Don't use when:** a form is a simple uncontrolled HTML form or a library like
React Hook Form already owns it — adding a Cubit on top creates two sources of
truth.

## Pattern

Keep field values and a `touched` map in state. Derive validation errors as a
getter — they recompute on every read and can never go stale. Show errors only for
touched fields so the initial load is clean.

```ts twoslash
import { Cubit } from '@blac/core';

interface RegisterState {
  email: string;
  password: string;
  confirmPassword: string;
  touched: Partial<Record<'email' | 'password' | 'confirmPassword', boolean>>;
  submitStatus: 'idle' | 'loading' | 'success' | 'error';
  submitError: string | null;
}

declare const api: {
  register(email: string, password: string): Promise<void>;
};
// ---cut---
class RegisterCubit extends Cubit<RegisterState> {
  constructor() {
    super({
      email: '',
      password: '',
      confirmPassword: '',
      touched: {},
      submitStatus: 'idle',
      submitError: null,
    });
  }

  // ── field setters ──────────────────────────────────────────────────────

  setEmail = (email: string) => this.patch({ email });
  setPassword = (password: string) => this.patch({ password });
  setConfirmPassword = (confirmPassword: string) =>
    this.patch({ confirmPassword });

  /** Mark a field as interacted with so its error becomes visible. */
  touchField = (field: keyof RegisterState['touched']) => {
    this.patch({ touched: { ...this.state.touched, [field]: true } });
  };

  // ── derived validation ─────────────────────────────────────────────────

  /** All errors keyed by field name (always computed, never stored). */
  get errors(): Partial<
    Record<'email' | 'password' | 'confirmPassword', string>
  > {
    const { email, password, confirmPassword } = this.state;
    const errors: Partial<
      Record<'email' | 'password' | 'confirmPassword', string>
    > = {};

    if (!email.includes('@')) errors.email = 'Enter a valid email address.';
    if (password.length < 8)
      errors.password = 'Password must be ≥ 8 characters.';
    if (confirmPassword !== password)
      errors.confirmPassword = 'Passwords do not match.';

    return errors;
  }

  get isValid() {
    return Object.keys(this.errors).length === 0;
  }

  // ── submit ─────────────────────────────────────────────────────────────

  submit = async () => {
    // Touch all fields so every error surfaces on an attempted submit.
    this.patch({
      touched: { email: true, password: true, confirmPassword: true },
    });

    if (!this.isValid) return;

    this.patch({ submitStatus: 'loading', submitError: null });

    try {
      await api.register(this.state.email, this.state.password);
      this.patch({ submitStatus: 'success' });
    } catch (e) {
      // ⚠️ Do NOT include the raw password in any error log or analytics event.
      this.patch({ submitStatus: 'error', submitError: String(e) });
    }
  };
}
```

```tsx
function RegisterForm() {
  const [state, form] = useBloc(RegisterCubit);
  const errors = form.errors;
  const { touched } = state;

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        void form.submit();
      }}
    >
      <label>
        Email
        <input
          type="email"
          value={state.email}
          onChange={(e) => form.setEmail(e.target.value)}
          onBlur={() => form.touchField('email')}
        />
        {touched.email && errors.email && <span>{errors.email}</span>}
      </label>

      <label>
        Password
        <input
          type="password"
          value={state.password}
          onChange={(e) => form.setPassword(e.target.value)}
          onBlur={() => form.touchField('password')}
        />
        {touched.password && errors.password && <span>{errors.password}</span>}
      </label>

      <label>
        Confirm password
        <input
          type="password"
          value={state.confirmPassword}
          onChange={(e) => form.setConfirmPassword(e.target.value)}
          onBlur={() => form.touchField('confirmPassword')}
        />
        {touched.confirmPassword && errors.confirmPassword && (
          <span>{errors.confirmPassword}</span>
        )}
      </label>

      {state.submitError && <p role="alert">{state.submitError}</p>}

      <button type="submit" disabled={state.submitStatus === 'loading'}>
        {state.submitStatus === 'loading' ? 'Submitting…' : 'Register'}
      </button>
    </form>
  );
}
```

:::tip[Errors as a getter, not state]
Storing computed errors in state means every field change requires updating two
places — they will eventually drift. A getter recalculates on read and is always
in sync. Reading `form.errors` in render auto-tracks the state fields the getter
touches; use `select` only when the getter result should be the explicit
re-render boundary. See [Dependency Tracking](/react/dependency-tracking).
:::

:::caution[PII in state]
Form state (email addresses, passwords, health data) is observable by plugins
and `watch` callbacks. If you install analytics or logging plugins, ensure they
scrub sensitive field names before shipping to a sink. Consider `excludeFromDevTools`
on forms that handle passwords:

```ts twoslash
import { blac, Cubit } from '@blac/core';

@blac({ excludeFromDevTools: true })
class SecureFormCubit extends Cubit<{ password: string }> {
  constructor() {
    super({ password: '' });
  }
}
```

:::

## Async field-level validation

For async checks (username availability, coupon validation), pattern them like a
debounced async action — see [Debounce](/guide/recipes/debounce) — and merge the
result into the errors object or a separate `asyncErrors` field.

## See also

- [Cubit](/core/cubit) — `patch`, `emit`, getters
- [Patterns](/guide/patterns) — named instances for billing/shipping form sections
- [Debounce](/guide/recipes/debounce) — async field-level validation

---

# Optimistic Update

> Apply a mutation to local Cubit state immediately, snapshot for rollback, fire the request, and restore the previous state on failure.

Source: /guide/recipes/optimistic-update/

**Use when:** you want the UI to reflect a mutation immediately, before the server
confirms it — then reconcile or roll back when the response arrives.
**Don't use when:** the action is destructive and hard to undo, or the server
response carries data that can't be predicted client-side.

## Pattern

Apply the change to local state immediately, record enough context to roll back,
fire the request, and on failure restore the previous state (or re-fetch the
authoritative list).

```ts twoslash
import { Cubit } from '@blac/core';

interface Todo {
  id: string;
  text: string;
  done: boolean;
}

interface TodoState {
  items: Todo[];
  error: string | null;
}

declare const api: {
  markDone(id: string): Promise<void>;
};
// ---cut---
class TodoCubit extends Cubit<TodoState> {
  constructor() {
    super({ items: [], error: null });
  }

  toggleDone = async (id: string) => {
    // 1. Snapshot for rollback.
    const previous = this.state.items;

    // 2. Apply optimistically — update only the matching item.
    this.patch({
      items: previous.map((t) => (t.id === id ? { ...t, done: !t.done } : t)),
      error: null,
    });

    try {
      await api.markDone(id);
      // Server confirmed — nothing more to do.
    } catch (e) {
      // 3. Roll back to the snapshot on failure.
      //    ⚠️ Do NOT ship the full state to an analytics sink before
      //    confirming — a rolled-back item would send false telemetry.
      this.patch({ items: previous, error: String(e) });
    }
  };
}
```

```tsx
// Hoisted to module level so the reference is stable across renders.
// This component only calls actions and never reads state, so an empty
// selector suppresses all re-renders.
const selectNothing = () => [];

function TodoItem({
  id,
  text,
  done,
}: {
  id: string;
  text: string;
  done: boolean;
}) {
  const [, todo] = useBloc(TodoCubit, { select: selectNothing });

  return (
    <li style={{ opacity: done ? 0.5 : 1 }}>
      <input
        type="checkbox"
        checked={done}
        onChange={() => todo.toggleDone(id)}
      />
      {text}
    </li>
  );
}
```

:::tip[Snapshot granularity]
Snapshot only the slice you're mutating (`this.state.items`), not the whole
state — this avoids accidentally rolling back unrelated fields that changed
between the optimistic apply and the server response.
:::

:::caution[Race condition]
If `toggleDone` is called twice rapidly, both calls capture the _same_
`previous`. Use the [request-id guard](/guide/async#the-request-id-guard) or
disable the trigger while a request is in-flight to prevent the second rollback
from clobbering the first response.
:::

## See also

- [Async](/guide/async) — request-id guard for concurrent requests
- [Cubit](/core/cubit) — `patch` deep-merges; `emit` replaces wholesale

---

# Pagination

> Page through a large server-side list in a Cubit — offset/page-based and cursor-based (infinite scroll) variants with per-page loading state.

Source: /guide/recipes/pagination/

**Use when:** you need to page through a large server-side list — cursor-based or
offset/page-based — with loading state per page and optional prefetch.
**Don't use when:** the full list fits in memory comfortably; just load everything
once and slice client-side.

## Offset / page-based

The most common shape: a `page` number plus a `totalPages` count returned by the
server.

```ts twoslash
import { Cubit } from '@blac/core';

interface Article {
  id: string;
  title: string;
}

interface PageResult {
  items: Article[];
  totalPages: number;
}

declare const api: {
  listArticles(page: number, perPage: number): Promise<PageResult>;
};
// ---cut---
interface PaginationState {
  items: Article[];
  page: number;
  totalPages: number;
  status: 'idle' | 'loading' | 'success' | 'error';
  error: string | null;
}

class ArticleListCubit extends Cubit<PaginationState> {
  private readonly perPage = 20;
  private requestId = 0;

  constructor() {
    super({ items: [], page: 1, totalPages: 1, status: 'idle', error: null });
  }

  protected override async init() {
    await this.loadPage(1);
  }

  loadPage = async (page: number) => {
    const reqId = ++this.requestId;
    this.patch({ status: 'loading', error: null });

    try {
      const { items, totalPages } = await api.listArticles(page, this.perPage);
      if (reqId !== this.requestId) return;
      this.patch({ items, page, totalPages, status: 'success' });
    } catch (e) {
      if (reqId !== this.requestId) return;
      this.patch({ status: 'error', error: String(e) });
    }
  };

  nextPage = () => {
    if (this.state.page < this.state.totalPages) {
      void this.loadPage(this.state.page + 1);
    }
  };

  prevPage = () => {
    if (this.state.page > 1) {
      void this.loadPage(this.state.page - 1);
    }
  };

  get hasNext() {
    return this.state.page < this.state.totalPages;
  }

  get hasPrev() {
    return this.state.page > 1;
  }
}
```

```tsx
function ArticleList() {
  const [state, list] = useBloc(ArticleListCubit, {
    select: (s, bloc) => [
      s.items,
      s.page,
      s.totalPages,
      s.status,
      bloc.hasNext,
      bloc.hasPrev,
    ],
  });

  if (state.status === 'loading') return <p>Loading…</p>;
  if (state.status === 'error') return <p>Error: {state.error}</p>;

  return (
    <div>
      <ul>
        {state.items.map((a) => (
          <li key={a.id}>{a.title}</li>
        ))}
      </ul>
      <button onClick={list.prevPage} disabled={!list.hasPrev}>
        ← Prev
      </button>
      <span>
        Page {state.page} / {state.totalPages}
      </span>
      <button onClick={list.nextPage} disabled={!list.hasNext}>
        Next →
      </button>
    </div>
  );
}
```

## Cursor-based (infinite scroll / "load more")

Cursor pagination keeps appending items rather than replacing them. The server
returns an opaque `nextCursor`; a `null` cursor signals the end.

```ts twoslash
import { Cubit } from '@blac/core';

interface Post {
  id: string;
  body: string;
}

declare const api: {
  fetchPosts(
    cursor: string | null,
  ): Promise<{ posts: Post[]; nextCursor: string | null }>;
};
// ---cut---
interface FeedState {
  posts: Post[];
  cursor: string | null; // null = no more pages
  status: 'idle' | 'loading' | 'success' | 'error';
  error: string | null;
}

class FeedCubit extends Cubit<FeedState> {
  private requestId = 0;

  constructor() {
    super({ posts: [], cursor: null, status: 'idle', error: null });
  }

  protected override async init() {
    await this.loadMore();
  }

  loadMore = async () => {
    // Guard: do nothing if already loading or no more pages.
    if (
      this.state.status === 'loading' ||
      (this.state.status === 'success' && this.state.cursor === null)
    ) {
      return;
    }

    const reqId = ++this.requestId;
    this.patch({ status: 'loading', error: null });

    try {
      const { posts, nextCursor } = await api.fetchPosts(this.state.cursor);
      if (reqId !== this.requestId) return;
      // Append — do not replace the existing list.
      this.patch({
        posts: [...this.state.posts, ...posts],
        cursor: nextCursor,
        status: 'success',
      });
    } catch (e) {
      if (reqId !== this.requestId) return;
      this.patch({ status: 'error', error: String(e) });
    }
  };

  get hasMore() {
    return this.state.cursor !== null;
  }
}
```

```tsx
function Feed() {
  const [state, feed] = useBloc(FeedCubit, {
    select: (s, bloc) => [s.posts, s.status, bloc.hasMore],
  });

  return (
    <div>
      {state.posts.map((p) => (
        <div key={p.id}>{p.body}</div>
      ))}
      {feed.hasMore && (
        <button onClick={feed.loadMore} disabled={state.status === 'loading'}>
          {state.status === 'loading' ? 'Loading…' : 'Load more'}
        </button>
      )}
    </div>
  );
}
```

:::caution[Cursor leakage]
Never log or expose raw cursor tokens to the UI — they may embed user identity
or internal shard keys. Treat `cursor` as an opaque internal value.
:::

:::tip[Reset on filter change]
When the user changes a filter, reset the entire list: `this.emit({ posts: [],
cursor: null, status: 'idle', error: null })` then call `loadMore()`. Without the
reset, old posts from the previous filter bleed into the new page.
:::

## See also

- [Async](/guide/async) — request-id guard and the loadable surface
- [Cubit](/core/cubit) — `patch` deep-merges, `emit` replaces wholesale

---

# Reset to Initial State

> Restore every field to its defaults in one atomic emit by storing the initial state in the constructor or seeding it from args in init.

Source: /guide/recipes/reset-to-initial/

**Use when:** a form, wizard, or filter panel needs a "Clear" or "Cancel" button
that restores every field to its defaults in one action.
**Don't use when:** the reset is partial (only some fields) — prefer `patch` with
the specific defaults rather than a full state replace.

## Pattern

Store the initial state once in the constructor and call `emit` with it to restore
it in one atomic update.

```ts twoslash
import { Cubit } from '@blac/core';

interface FilterState {
  query: string;
  category: string;
  minPrice: number;
  maxPrice: number;
  sortBy: 'price' | 'rating' | 'newest';
}
// ---cut---
const DEFAULT_FILTER: FilterState = {
  query: '',
  category: 'all',
  minPrice: 0,
  maxPrice: 10_000,
  sortBy: 'newest',
};

class FilterCubit extends Cubit<FilterState> {
  // Keep the initial state immutable — emit makes a reference check so we
  // must not mutate this object in place.
  private readonly initial: FilterState;

  constructor(initial: FilterState = DEFAULT_FILTER) {
    super(initial);
    this.initial = initial;
  }

  setQuery = (query: string) => this.patch({ query });
  setCategory = (category: string) => this.patch({ category });
  setMinPrice = (minPrice: number) => this.patch({ minPrice });
  setMaxPrice = (maxPrice: number) => this.patch({ maxPrice });
  setSortBy = (sortBy: FilterState['sortBy']) => this.patch({ sortBy });

  /** Restore all fields to their initial values in one emit. */
  reset = () => {
    // emit replaces the whole state; patch would also work but emit is
    // clearer in intent — we're not updating a subset, we're replacing all.
    this.emit({ ...this.initial });
    //          ^^^^^^^^^^^^^^^
    // Spread produces a new object reference so the equality check can
    // detect a change even if the current state already matches the defaults.
  };

  get isDirty() {
    const s = this.state;
    return (
      s.query !== this.initial.query ||
      s.category !== this.initial.category ||
      s.minPrice !== this.initial.minPrice ||
      s.maxPrice !== this.initial.maxPrice ||
      s.sortBy !== this.initial.sortBy
    );
  }
}
```

```tsx
function FilterPanel() {
  const [state, filter] = useBloc(FilterCubit, {
    select: (s, bloc) => [s.query, s.category, s.sortBy, bloc.isDirty],
  });

  return (
    <div>
      <input
        value={state.query}
        onChange={(e) => filter.setQuery(e.target.value)}
        placeholder="Search…"
      />
      <select
        value={state.category}
        onChange={(e) => filter.setCategory(e.target.value)}
      >
        <option value="all">All</option>
        <option value="books">Books</option>
        <option value="music">Music</option>
      </select>
      {filter.isDirty && <button onClick={filter.reset}>Clear filters</button>}
    </div>
  );
}
```

## Args-seeded initial state

When the initial state comes from `args` (for example a per-user default saved on
the server), capture it in `init` instead of the constructor:

```ts twoslash
import { Cubit } from '@blac/core';

interface FilterState {
  query: string;
  category: string;
}
// ---cut---
class UserFilterCubit extends Cubit<FilterState, FilterState> {
  private savedInitial!: FilterState;

  constructor() {
    super({ query: '', category: 'all' });
  }

  protected override init(args: FilterState) {
    // args is the authoritative initial state for this user.
    this.savedInitial = args;
    this.emit({ ...args });
  }

  reset = () => {
    this.emit({ ...this.savedInitial });
  };
}
```

:::caution[Spread before emit]
`this.emit(this.initial)` passes the _same object reference_ as the current
state if nothing has changed yet. `emit` short-circuits on referential equality
(`prev === next`), so the reset would be silently skipped. Spread (`{ ...this.initial }`)
produces a fresh object, ensuring the emit goes through.
:::

:::tip[Partial reset]
If you want to reset only specific fields, use `patch` instead of `emit`:

```ts twoslash
import { Cubit } from '@blac/core';
interface FilterState {
  query: string;
  category: string;
  sortBy: string;
}
class FilterCubit extends Cubit<FilterState> {
  constructor() {
    super({ query: '', category: 'all', sortBy: 'newest' });
  }
  // ---cut---
  resetSearch = () => {
    // Resets only `query`; keeps `category` and `sortBy` intact.
    this.patch({ query: '' });
  };
  // ---cut-after---
}
```

:::

## See also

- [Cubit](/core/cubit) — `emit` replaces state; `patch` deep-merges
- [Patterns](/guide/patterns) — named instances for parallel forms

---

# Undo / Redo

> Implement undo/redo in a Cubit with past and future state stacks, a history cap, and getters for canUndo/canRedo.

Source: /guide/recipes/undo-redo/

**Use when:** users need to reverse discrete actions — a text editor, a canvas,
a form with destructive bulk edits.
**Don't use when:** the state is large and serialization is expensive; consider
structural sharing or operation-log approaches instead.

## Pattern

Keep a stack of past states and a stack of future states alongside the current
one. Each mutation saves the previous state to `past`; undo pops from `past` and
pushes to `future`; redo reverses that.

```ts twoslash
import { Cubit } from '@blac/core';

// The domain value being edited.
interface Note {
  title: string;
  body: string;
}

interface EditorState {
  note: Note;
  past: Note[]; // oldest … newest-before-current
  future: Note[]; // most-recently-undone … oldest-undone
}
// ---cut---
class EditorCubit extends Cubit<EditorState, Note> {
  // Hard cap prevents unbounded memory growth.
  private static readonly MAX_HISTORY = 50;

  // One instance per note title — args both seed and key the instance.
  static key = (initial: Note) => initial.title;

  constructor() {
    super({ note: { title: '', body: '' }, past: [], future: [] });
  }

  protected init(initial: Note) {
    this.emit({ note: initial, past: [], future: [] });
  }

  /** Push the current note onto the past stack, then apply `next`. */
  private applyChange(next: Note) {
    const { note, past } = this.state;
    const trimmed = past.slice(-(EditorCubit.MAX_HISTORY - 1));
    this.emit({ note: next, past: [...trimmed, note], future: [] });
    //                                                 ^^^^^^^^
    // ⚠️ Always clear `future` on a new edit — an undo-then-type flow should
    // not let the user redo the overwritten branch.
  }

  setTitle = (title: string) => {
    this.applyChange({ ...this.state.note, title });
  };

  setBody = (body: string) => {
    this.applyChange({ ...this.state.note, body });
  };

  undo = () => {
    const { note, past, future } = this.state;
    if (past.length === 0) return;

    const previous = past[past.length - 1];
    this.emit({
      note: previous,
      past: past.slice(0, -1),
      future: [note, ...future],
    });
  };

  redo = () => {
    const { note, past, future } = this.state;
    if (future.length === 0) return;

    const next = future[0];
    this.emit({
      note: next,
      past: [...past, note],
      future: future.slice(1),
    });
  };

  get canUndo() {
    return this.state.past.length > 0;
  }

  get canRedo() {
    return this.state.future.length > 0;
  }
}
```

```tsx
function NoteEditor({ initial }: { initial: { title: string; body: string } }) {
  // `static key` derives identity from the title — one EditorCubit per note.
  const [state, editor] = useBloc(EditorCubit, {
    args: initial,
    select: (s, bloc) => [
      s.note.title,
      s.note.body,
      bloc.canUndo,
      bloc.canRedo,
    ],
  });

  return (
    <div>
      <input
        value={state.note.title}
        onChange={(e) => editor.setTitle(e.target.value)}
      />
      <textarea
        value={state.note.body}
        onChange={(e) => editor.setBody(e.target.value)}
      />
      <button onClick={editor.undo} disabled={!editor.canUndo}>
        Undo
      </button>
      <button onClick={editor.redo} disabled={!editor.canRedo}>
        Redo
      </button>
    </div>
  );
}
```

:::tip[History cap]
Without `MAX_HISTORY`, a long editing session accumulates unbounded state
snapshots. Cap it and trim the oldest entries — `past.slice(-(MAX - 1))` keeps
the most recent `MAX - 1` entries before adding the new one.
:::

:::caution[Avoid storing derived state in history]
Only snapshot values that are the _source of truth_ (here, `note`). Including
computed flags or loading status in the history stack inflates its size and can
produce impossible states on undo.
:::

## See also

- [Cubit](/core/cubit) — `emit` replaces wholesale; `update` derives from current state
- [Patterns](/guide/patterns) — getter-based computed values (`canUndo`/`canRedo`)

---

# WebSocket Subscription

> Open a WebSocket in a Cubit's init, push frames into state with patch, and close the socket on the dispose system event so it is always cleaned up.

Source: /guide/recipes/websocket/

**Use when:** you need a persistent, server-pushed connection — a live chat feed,
real-time dashboard, presence indicators, or a collaborative document.
**Don't use when:** you only need server-sent data occasionally and polling would
suffice; a persistent socket has reconnect overhead and connection limits.

## Pattern

Open the socket in `init`, push received messages into state with `patch`, and
close the socket in the `dispose` system event so it is always cleaned up.

```ts twoslash
import { Cubit } from '@blac/core';

interface ChatMessage {
  id: string;
  author: string;
  text: string;
  timestamp: number;
}

interface ChatState {
  messages: ChatMessage[];
  connected: boolean;
  error: string | null;
}

// Minimal WebSocket-like interface for illustration.
declare class ReconnectingWebSocket {
  constructor(url: string);
  onopen: (() => void) | null;
  onclose: (() => void) | null;
  onerror: ((e: Event) => void) | null;
  onmessage: ((e: { data: string }) => void) | null;
  send(data: string): void;
  close(): void;
}

declare const WS_URL: string;
// ---cut---
class ChatCubit extends Cubit<ChatState, { channelId: string }> {
  private socket: ReconnectingWebSocket | null = null;

  constructor() {
    super({ messages: [], connected: false, error: null });

    this.onSystemEvent('dispose', () => {
      // Always close on disposal — avoid orphaned connections.
      this.socket?.close();
      this.socket = null;
    });
  }

  protected override init({ channelId }: { channelId: string }) {
    this.connect(channelId);
  }

  private connect(channelId: string) {
    const ws = new ReconnectingWebSocket(`${WS_URL}/chat/${channelId}`);
    this.socket = ws;

    ws.onopen = () => {
      this.patch({ connected: true, error: null });
    };

    ws.onclose = () => {
      this.patch({ connected: false });
    };

    ws.onerror = (e) => {
      // ⚠️ Never forward raw WebSocket error events to an analytics sink —
      // they may contain auth tokens present in the connection URL.
      this.patch({ connected: false, error: 'Connection error' });
    };

    ws.onmessage = ({ data }) => {
      // Parse incoming data defensively — the server may send system frames.
      let message: ChatMessage;
      try {
        message = JSON.parse(data) as ChatMessage;
      } catch {
        return; // ignore malformed frames
      }
      this.patch({
        messages: [...this.state.messages, message],
      });
    };
  }

  sendMessage = (text: string) => {
    if (!this.state.connected || !this.socket) return;
    this.socket.send(JSON.stringify({ text }));
  };
}
```

```tsx
function ChatRoom({ channelId }: { channelId: string }) {
  // args: { channelId } both seeds init() and keys the instance — one per channel
  const [state, chat] = useBloc(ChatCubit, {
    args: { channelId },
  });

  return (
    <div>
      <span>{state.connected ? '🟢 Connected' : '🔴 Disconnected'}</span>
      <ul>
        {state.messages.map((m) => (
          <li key={m.id}>
            <strong>{m.author}</strong>: {m.text}
          </li>
        ))}
      </ul>
      <MessageInput onSend={chat.sendMessage} disabled={!state.connected} />
    </div>
  );
}
```

:::danger[Orphaned connections]
If the socket outlives the Cubit it will fire `onmessage` on a disposed container
and throw. The `onSystemEvent('dispose', …)` cleanup above prevents this. Do not
skip it.
:::

:::tip[Per-channel instances]
`channelId` lives in `args`, which both seeds `init()` and keys the instance.
Multiple `<ChatRoom>` components with different `channelId` values each get their
own Cubit (and socket); the same `channelId` reuses a shared instance. When all
consumers of a channel unmount, the instance is disposed and the socket is closed
automatically.
:::

:::caution[Message volume]
High-frequency feeds (>10 messages/sec) that call `patch` on every frame will
saturate the emit-rate circuit breaker. Batch incoming messages before applying
them — accumulate in a local buffer and flush on a 16 ms `setTimeout`, or sample
at the cadence your UI needs.
:::

## See also

- [System Events](/core/system-events) — `dispose` event for cleanup
- [Instance Management](/core/instance-management) — ref-counting and per-channel instances
- [Async](/guide/async) — cancellation on disposal

---

# Troubleshooting & FAQ

> A symptom-to-fix lookup table for the most common BlaC problems, with links into the reference pages that own each explanation.

Source: /guide/troubleshooting/

This page is a fast lookup table for the problems that actually bite. Each entry is **symptom → cause → fix**, with a link into the reference page that owns the full explanation. If you are new and want the _why_ behind these behaviours, read the [Mental Model](/guide/mental-model) first — this page assumes you just want the answer.

:::tip[How to use this page]
Scan the **Symptom** column for the thing you are seeing, expand the matching detail block, apply the fix, and follow the link if you need depth. Nothing here invents new API — every fix uses the surface documented in [`useBloc`](/react/use-bloc), [Instance management](/core/instance-management), and [Configuration](/core/configuration).
:::

## Common problems

### Re-rendering

| Symptom                                       | Likely cause                                                       | Fix                                                                                      |
| --------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| Component never re-renders when state changes | State was read **outside** the render body                         | Read the value during render, not in an effect/callback                                  |
| Component never re-renders                    | State was **destructured/copied before** the tracked read          | Read leaf properties off the live `state` proxy during render                            |
| Component never re-renders                    | A `select` selector is present and never returns the changed value | Add the value to the selector array (or remove `select` to auto-track)                   |
| Component never re-renders                    | State was **mutated in place** instead of replaced                 | Use `emit` / `update` / `patch` so a new reference is published                          |
| Component re-renders too often                | Reading a coarse path (whole array/object) instead of the leaf     | Read the specific leaf you render; see [dependency tracking](/react/dependency-tracking) |

<details>
<summary>"My component does not re-render" — full walk-through</summary>

Auto-tracking records a state path **only when you read it on the `state` proxy during render**. Four things break that contract:

**1. The read happened outside render.** Reads inside `useEffect`, event handlers, `setTimeout`, or `onMount` are not recorded — only synchronous reads in the render body are.

```tsx
// ✗ read happens in an effect — nothing is tracked, no re-render
const [state, bloc] = useBloc(CounterCubit);
useEffect(() => {
  console.log(state.count); // recorded? no.
}, []);

// ✓ read during render — `count` is tracked
const [state] = useBloc(CounterCubit);
return <span>{state.count}</span>;
```

**2. You destructured or copied before reading.** Pulling values into a local at the top, or spreading the state, can read a parent path (coarse) or no path at all, depending on how you then use it. Read the exact leaf you render, off the live proxy.

```tsx
// △ spreading reads the parent, widening (or losing) what is tracked
const { ...snapshot } = state;
return <span>{snapshot.count}</span>;

// ✓ read the leaf directly
return <span>{state.count}</span>;
```

**3. You passed a `select` selector that omits the value.** Providing `select` opts **out** of auto-tracking entirely — the hook re-renders only when the returned array changes per index (`Object.is`). If the value you render is not in that array, it will never trigger a render.

```tsx
// ✗ render uses `total`, but the selector only watches `count`
const [state] = useBloc(CartCubit, { select: (s) => [s.count] });
return <span>{state.total}</span>;

// ✓ either include it…
const [state] = useBloc(CartCubit, { select: (s) => [s.count, s.total] });
// ✓ …or drop `select` and let auto-tracking handle it
const [state] = useBloc(CartCubit);
```

**4. You mutated state in place.** `emit` short-circuits when `prev === next` by reference, and `patch` skips per-key when `Object.is(old, new)` holds. Mutating the existing object and re-emitting it publishes nothing.

```ts
// ✗ same reference — emit no-ops
update((s) => {
  s.count++;
  return s;
});

// ✓ new reference
update((s) => ({ ...s, count: s.count + 1 }));
// ✓ or target the field
patch({ count: this.state.count + 1 });
```

Owner page: [Dependency tracking](/react/dependency-tracking). Mechanism: [Mental Model](/guide/mental-model).

</details>

:::caution[Map / Set / Date / class instances are leaves]
The tracker wraps **plain objects and arrays** only. A `Map`, `Set`, `Date`, or class instance in state is treated as a single leaf value — a change is detected as a **reference change at that path**, never as a change to something inside it. Replace the whole value (`emit(new Map(prev).set(k, v))`) rather than mutating it in place. See [dependency tracking limitations](/react/dependency-tracking).
:::

---

### Stale values in callbacks

| Symptom                              | Likely cause                                                   | Fix                                                                         |
| ------------------------------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------- |
| A callback fires with an old value   | Closure captured a render-time snapshot                        | Read off the bloc inside the callback, or invert the callback into the bloc |
| `deps` callback sees stale variables | Inline arrow re-created each render but captured stale closure | Make the handle stable; put the _logic_ in the bloc                         |

<details>
<summary>"Stale value in a callback" — callback inversion</summary>

A callback you define in the component closes over the variables that existed **when that render ran**. If it fires later, it still sees those old values.

```tsx
// ✗ `count` is frozen at the render that created this handler
const [state, bloc] = useBloc(CounterCubit);
const onClick = () => console.log(state.count); // stale
```

Two fixes, in order of preference:

**Read off the bloc, not the closure.** The `bloc` instance is stable for the consumer's lifetime, and `bloc.state` is always current.

```tsx
const [, bloc] = useBloc(CounterCubit);
const onClick = () => console.log(bloc.state.count); // always current
```

**Invert the callback into the bloc.** Better still, move the behaviour onto the bloc as a method (an arrow-function class field, so `this` binds). The component just calls the action; there is no closure to go stale.

```ts
class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  logCount = () => console.log(this.state.count); // `this.state` is live
}
```

```tsx
const [, bloc] = useBloc(CounterCubit);
return <button onClick={bloc.logCount}>log</button>;
```

If you must pass a callback **into** a bloc, route it through the `deps` lane (a non-serializable, per-consumer handle) rather than `args` — and keep the handle referentially stable so it does not re-key. Putting a fresh inline arrow in `deps` every render is the classic stale-closure trap. See [Passing inputs](/guide/inputs#deps-non-serializable-handles).

</details>

---

### Instance identity (too many / too few)

| Symptom                                                   | Likely cause                                                                             | Fix                                                                                      |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Two instances when you expected one                       | `args` differ structurally between consumers (or a fresh object that hashes differently) | Ensure args are equal; narrow identity with `static key`                                 |
| A **new** instance every render                           | A function or non-serializable value is in `args`                                        | Move it to `deps`; `args` must be JSON-serializable                                      |
| Everyone shares one instance, but you wanted one per item | All consumers use the same key (default, or same `args`)                                 | Pass distinct `args` (e.g. a name field, or `_id: useId()` + `static key` for per-mount) |
| Per-item components leak into each other                  | Same `args` key reused across items                                                      | Give each item distinct `args` (e.g. the row id)                                         |

<details>
<summary>"I got two instances when I expected one"</summary>

Identity is resolved from, in precedence order: own **`args`** (via `static key(args)`, else the **structural hash of `args`**) → `<BlocProvider>` context args → the `'default'` sentinel. Two consumers land on the same instance only when their resolved key matches.

Common causes of an unexpected split:

- **Args differ structurally.** `{ userId: '1' }` and `{ userId: 1 }` hash differently (string vs number). Normalise the type.
- **You only want a subset of args to key the instance.** Use `static key` so config that "rides along" does not fork instances:

  ```ts
  class DocumentCubit extends Cubit<
    DocState,
    { docId: string; readonly: boolean }
  > {
    static key = (args: DocumentCubit['args']) => args.docId; // `readonly` does not fork
  }
  ```

`args` is memoised internally on `JSON.stringify(args)`, so a fresh object literal each render is fine **as long as its contents are equal**. Owner page: [Passing inputs](/guide/inputs#args-construction-data-that-keys-the-instance).

</details>

<details>
<summary>"A new instance is created on every render"</summary>

If `args` contains a **function** (or other non-serializable value), the structural-key hash throws in dev with:

```text
[blac] args must be serializable; put refs/callbacks in `deps`
```

In production the hash will differ each render and you get a brand-new instance constantly. The fix is always the same: **`args` is for serializable identity data only.** Refs, callbacks, and live handles go in the [`deps`](/guide/inputs#deps-non-serializable-handles) lane.

```tsx
// ✗ callback in args — throws in dev, new instance in prod
useBloc(ListCubit, { args: { onSelect: () => {} } });

// ✓ identity data in args, handle in deps (deps never key identity)
useBloc(ListCubit, {
  args: { listId } /* , deps: { onSelect } via your deps wiring */,
});
```

</details>

<details>
<summary>"Everyone shares one instance when I wanted per-item"</summary>

By default, a bloc with `void` args resolves to the single `'default'` key — every consumer shares it. To get one instance per item, give each consumer distinct `args`. Identity always comes from `args`; differ by intent only in _what_ you put there:

| Want                                                   | Use                                                               |
| ------------------------------------------------------ | ----------------------------------------------------------------- |
| One instance per **data identity** (e.g. per `userId`) | `args: { userId }` — same args share, different args split        |
| One instance per **caller-chosen key**                 | a name field in args, e.g. `args: { row: row.id }` + `static key` |
| One **fresh** instance per component mount             | `args: { _id: useId() }` + `static key`                           |

```tsx
// per data identity
useBloc(UserCardCubit, { args: { userId } });

// caller-chosen key — each row is its own instance (static key = a => a.row)
useBloc(RowCubit, { args: { row: row.id } });
```

```tsx
// fresh per mount — useId() is a stable-per-mount value (static key = a => a._id)
const _id = useId();
useBloc(WidgetCubit, { args: { _id } });
```

A per-mount instance keyed off `useId()` always resolves to its own key, never the args supplied by an ancestor [`BlocProvider`](/react/use-bloc), so each mount stays private. Owner page: [Instance management](/core/instance-management).

</details>

:::caution[`args: { _id: useId() }`, not `autoInstance` or `instanceId`]
You may see `autoInstance` or an `instanceId` option in old notes or stale comments — neither exists in the shipping API. The per-mount mechanism is a synthetic `args` field plus a `static key` that selects it (use `useId()` for a stable-per-mount value). There is no `isolated`, `autoInstance`, or `instanceId` field or hook option. See the [glossary](/guide/glossary).
:::

---

### Lifecycle (disposed too early / never disposed)

| Symptom                                      | Likely cause                                                       | Fix                                                                            |
| -------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| Instance disposed while still in use         | A `depend()`/`ensure` reference holds no ref count                 | Hold a real ref (a `useBloc` consumer), or mark the source `keepAlive`         |
| Instance never disposed                      | A ref was acquired without a matching release                      | Pair every `acquire` with a `release` (outside React)                          |
| State unexpectedly resets                    | Last consumer unmounted → auto-dispose → fresh instance on remount | Mark the class `@blac({ keepAlive: true })` if it should outlive its consumers |
| State persists when you wanted a clean slate | `keepAlive` is on, so refcount 0 never disposes                    | Drop `keepAlive`, or `release(..., forceDispose)` / `clear` in teardown        |

<details>
<summary>"Instance disposed too early / never disposed" — ref counting</summary>

The registry ref-counts instances. Each `useBloc` consumer acquires one ref on mount and releases it on unmount. When the ref count reaches **0**, the instance is auto-disposed (unless it is `keepAlive`), and the dispose **cascades** to `ensure`-created dependencies that now also have zero refs.

**Disposed too early.** `depend()` resolves its target via `ensure()`, which takes **no ref**. If nothing else holds the dependency, it can be disposed out from under you. Keep it alive by having a real consumer hold it, or mark the source class `keepAlive`.

```ts
// inside a bloc — depend() does NOT keep the target alive on its own
private user = this.depend(UserCubit);
```

```ts
// keep a shared, long-lived source alive
@blac({ keepAlive: true })
class SessionCubit extends Cubit<SessionState> {
  /* … */
}
```

**Never disposed.** Outside React you manage refs yourself: every `acquire` must be paired with a `release`. A missing `release` leaks the instance forever.

```ts
const refId = 'job-42';
const job = acquire(JobCubit, { refId });
// … later, always:
release(JobCubit, { refId });
```

`keepAlive` instances are never auto-disposed at refcount 0; tear them down explicitly with `release(C, { forceDispose: true })` or `clear(Class)` (a test/teardown utility — see [testing core](/testing/core)). Owner page: [Instance management](/core/instance-management); see also [Configuration](/core/configuration#keepalive-true).

</details>

---

### Type errors

| Symptom                                      | Likely cause                            | Fix                                                                              |
| -------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------- |
| `args` is **forbidden** (`never`)            | The bloc's `Args` is the default `void` | Remove `args` from the `useBloc` call                                            |
| Wrong `args` shape causes a type error       | Passed `args` don't match the bloc type | Match the bloc's declared `Args` shape; `args` is optional but typed when passed |
| `select` "must be stable" re-keys constantly | A fresh selector function each render   | Wrap the selector in `useCallback`                                               |

<details>
<summary>"'args' does not exist / wrong args shape"</summary>

`useBloc`'s `args` option is **conditional on the bloc's type**:

```ts
type ArgsOption<T> =
  ExtractArgs<T> extends void ? { args?: never } : { args?: ExtractArgs<T> };
```

- If the bloc extends `Cubit<S, SomeArgs>`, `args` is **optional** — omitting it inherits args from a `<BlocProvider>` ancestor, or falls back to the default key. When passed, it must match the declared `Args` shape.
- If the bloc uses the default `void` args, `args` is typed `never` — **passing** it is a compile error.

```tsx
// bloc: class UserCubit extends Cubit<S, { userId: string }>
useBloc(UserCubit); // ✓ inherits BlocProvider args or uses default key
useBloc(UserCubit, { args: { userId } }); // ✓ explicit args

// bloc: class CounterCubit extends Cubit<S>  (void args)
useBloc(CounterCubit, { args: {} }); // ✗ 'args' does not exist on type
useBloc(CounterCubit); // ✓
```

If you genuinely need to pass data to a `void`-args bloc, give the bloc an `Args` type. Owner page: [Passing inputs](/guide/inputs).

</details>

---

### DevTools not showing

| Symptom                                  | Likely cause                                    | Fix                                                           |
| ---------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------- |
| DevTools panel empty / nothing appears   | The DevTools plugin is not installed            | `install` the DevTools plugin via `getPluginManager()`        |
| A specific bloc is missing from DevTools | The class is `excludeFromDevTools`              | Remove `@blac({ excludeFromDevTools: true })` from that class |
| DevTools loaded but no live updates      | Plugin installed only for the wrong environment | Check the plugin's `environment` config matches `NODE_ENV`    |

<details>
<summary>"DevTools not showing my blocs"</summary>

Two independent gates control DevTools visibility:

**1. The plugin must be installed.** DevTools is a plugin, not built in. Install it through the plugin manager, and respect its `environment` (a plugin configured for `'development'` is skipped in production by a runtime `NODE_ENV` check).

```ts
import { getPluginManager } from '@blac/core';
// install your devtools plugin instance:
getPluginManager().install(devtoolsPlugin, { environment: 'development' });
```

**2. The class must not be excluded.** A class marked `excludeFromDevTools` (checked via `isExcludedFromDevTools`) is deliberately hidden:

```ts
@blac({ excludeFromDevTools: true })
class NoiseCubit extends Cubit<NoiseState> {
  /* … */
}
```

If you want this bloc visible, drop that option. The option is documented in [Configuration](/core/configuration); usage lives in [the DevTools plugin](/plugins/devtools).

</details>

---

### SSR & hydration

| Symptom                                        | Likely cause                                         | Fix                                                                    |
| ---------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------- |
| Hydration mismatch warning from React          | Server and client produced different first snapshots | Seed initial state from `args` in `init(args)` so both render the same |
| Persisted state appears, then vanishes         | State changed _while_ hydrating → discarded          | Hold writes until `$blac.hydration.isHydrated`; observe `hydrationChanged`             |
| Instance key differs between server and client | Relying on internal auto-ids for stable identity     | Key off stable `args` (or a `BlocProvider`) for SSR-stable identity    |

<details>
<summary>"SSR / hydration notes"</summary>

A few facts that matter when rendering on the server:

- **First snapshot is synchronous.** `args` are forwarded to `init(args)` **once, before the first state snapshot**, so a bloc keyed by `args` renders identical initial state on server and client — no flash, no mismatch — provided the `args` are the same on both sides.
- **`useBloc` does not fight React for SSR id slots.** Internally it uses a plain module counter for its consumer id (a `useId()` slot is reserved but unused), so it will not desync SSR-streamed ids. For identity that must be **stable across server/client**, derive it from stable `args` or a [`BlocProvider`](/react/use-bloc); do not rely on auto-generated ids.
- **State hydration is a guarded lifecycle.** `$blac.hydration.begin()` → `$blac.hydration.apply(next)` → `$blac.hydration.finish()`. `apply` returns `false` (and skips) if the bloc was disposed, is not hydrating, or **`changedWhileHydrating`** — i.e. a normal write landed mid-hydration, so the live state wins and the persisted snapshot is discarded. If persisted state seems to be ignored, you almost certainly wrote to the bloc before hydration finished. Observe transitions via the [`hydrationChanged`](/core/system-events) system event and gate writes on `$blac.hydration.isHydrated`.

See [Persistence](/plugins/persistence) for the full hydration story and [System events](/core/system-events) for `hydrationChanged`.

</details>

---

## FAQ

<details>
<summary>Is there a `Bloc` class?</summary>

No. The only base classes are `StateContainer` (abstract) and [`Cubit`](/core/cubit) (abstract, extends `StateContainer`). "Bloc" is colloquial shorthand for any container instance — see the [glossary](/guide/glossary).

</details>

<details>
<summary>How do I track a value without decorating it? Where is `@tracked`?</summary>

There is no `@tracked` decorator and no `autoTrack` option. Tracking is **automatic and unconditional** whenever `select` is omitted — a render-time proxy records every leaf path you read. The only opt-out is supplying `select`. See [dependency tracking](/react/dependency-tracking).

</details>

<details>
<summary>`emit` vs `update` vs `patch`?</summary>

`emit(next)` replaces the whole state; `update(fn)` is `emit(fn(state))`; `patch(partial)` deep-merges a `DeepPartial<S>`. Note the equality check applies to `emit`/`update` only — `patch` filters per-key with its own `Object.is` comparison. A common mistake is calling `emit` with a partial object, which silently drops the missing fields. See [Cubit](/core/cubit).

</details>

<details>
<summary>Why did my `select` start re-keying / re-subscribing each render?</summary>

`select` must be **referentially stable**. A fresh function each render is treated as a new consumer and forces the subscription to re-key. Wrap it in `useCallback`. See [`useBloc`](/react/use-bloc).

</details>

<details>
<summary>Does `depend()` make my component re-render when the dependency changes?</summary>

A plain `.untracked()` read does **not** auto-subscribe to the dependency's channel — but `.track()` does: read a dep's state via `const [s] = this.dep.track()` inside a getter and the component reading that getter re-renders when the dependency changes, no second `useBloc` needed. Calling a dependency's method (through `.untracked()`) never subscribes you to it. See [Bloc communication](/core/bloc-communication#auto-tracking-with-track).

</details>

<details>
<summary>`watch` callback fires async / `watch` never stops — what gives?</summary>

`watch` fires once immediately, then on every change, but subscriptions are **microtask-deferred** — callbacks land after the synchronous `emit`. `watch` returns a cleanup function; if you never call it (or never return `watch.STOP`), the watcher leaks. Also note `watch` uses `ensure` and takes **no ref**, so it does not keep the bloc alive. See [`watch`](/core/watch).

</details>

<details>
<summary>My tests leak state between cases.</summary>

The registry is global. Reset it between tests with the testing setup helpers so instances do not bleed across cases. See [Testing overview](/testing/overview) and [Testing core](/testing/core).

</details>

<details>
<summary>A circuit breaker threw ("max instances" / "max refs").</summary>

You hit `maxInstancesPerType` or `maxRefsPerInstance` from the global config — usually a leak (unreleased refs, or distinct `args` exploding instance count). Find the leak first; raise the limit (or set it to `Infinity` to disable) only if the count is legitimately high. `maxEmitsPerSecond` only warns in dev, never throws. See [Configuration](/core/configuration).

</details>

## See also

- [Mental Model](/guide/mental-model) — the _why_ behind tracking, identity, and disposal
- [Passing inputs](/guide/inputs) — `args` and `deps` in depth
- [`useBloc`](/react/use-bloc) — the canonical options and precedence reference
- [Instance management](/core/instance-management) — acquire/release, ref counting, `keepAlive`
- [Glossary](/guide/glossary) — one-line definitions for every term used here

---

# Tutorial: build a Todo app, then make it time-travel

> Build a Todo app one step at a time and finish with full undo, redo, and time travel using only BlaC's core state primitives.

Source: /guide/tutorial/

This is the long way round — one app, built in seven numbered steps, each a small diff on the last. We start with an empty Cubit and finish with full **undo / redo and time travel**, all from the same state primitives you meet in the first step. No new APIs appear at the end; the payoff is that BlaC's plain-immutable-state model makes undo fall out almost for free.

If you have not read [Quick Start](/guide/getting-started) and [Core Concepts](/guide/concepts) yet, skim them first — this page assumes you know what `emit`/`update`/`patch` do and that `useBloc` returns a `[state, bloc]` tuple. Everything else is built up here.

There are two interactive checkpoints: one when the app first becomes usable, one at the end with time travel. The code blocks in between are type-checked against the real published API by the docs build, so they compile exactly as written.

## What we are building

A todo list with:

- adding, toggling, and removing items;
- a filter (all / active / done) that is _view_ state, kept separate from the data;
- a derived "items left" count;
- and — the finale — a full history stack so every change can be undone, redone, or jumped to.

The whole thing is **one Cubit**. Every component reads only the slice it needs, so adding a todo never re-renders the filter chips, and toggling the filter never re-renders the add box. That isolation is automatic; you will see it without writing a single selector for most of the app.

## Step 1 — the state shape and the first action

Start with the data. A todo has an `id`, `text`, and a `done` flag. The Cubit's state is a list of them. Nothing else yet.

```ts twoslash
import { Cubit } from '@blac/core';

export interface Todo {
  id: string;
  text: string;
  done: boolean;
}

export interface TodoState {
  todos: Todo[];
}

export class TodoCubit extends Cubit<TodoState> {
  constructor() {
    super({ todos: [] });
  }

  add = (text: string) => {
    const trimmed = text.trim();
    if (!trimmed) return;
    // patch deep-merges: we mention only the key we change.
    this.patch({
      todos: [
        ...this.state.todos,
        { id: crypto.randomUUID(), text: trimmed, done: false },
      ],
    });
  };
}
```

Two things to notice, both from [Quick Start](/guide/getting-started):

- `add` is an **arrow-function field**, not a method, so `this` stays bound when you pass `todo.add` straight to an event handler.
- We build the next array with a spread (`[...this.state.todos, …]`) rather than `push`. State is treated as immutable; you always hand `patch`/`emit` a fresh value. That immutability is exactly what makes Step 7 possible.

## Step 2 — render it in React

`useBloc(TodoCubit)` gives this component the shared instance and subscribes it to the state it reads. Here it reads `state.todos`, so it wakes whenever the list changes.

```tsx
import { useBloc } from '@blac/react';
import { TodoCubit } from './TodoCubit';

function TodoList() {
  const [state] = useBloc(TodoCubit);
  return (
    <ul>
      {state.todos.map((t) => (
        <li key={t.id}>{t.text}</li>
      ))}
    </ul>
  );
}
```

And an input to drive `add`. This component reads _nothing_ from state — it only calls an action — so it never re-renders when the list changes:

```tsx
import { useState } from 'react';
import { useBloc } from '@blac/react';
import { TodoCubit } from './TodoCubit';

function AddRow() {
  const [text, setText] = useState('');
  const [, todo] = useBloc(TodoCubit); // only the bloc, no state read

  return (
    <input
      value={text}
      onChange={(e) => setText(e.target.value)}
      onKeyDown={(e) => {
        if (e.key === 'Enter') {
          todo.add(text);
          setText('');
        }
      }}
    />
  );
}
```

That `const [, todo] =` — dropping the state slot — is the idiom for an action-only consumer. There is no subscription to anything, so nothing wakes it.

## Step 3 — toggle and remove

Two more actions on the Cubit. Both produce a brand-new array; neither mutates the old one. `toggle` maps over the list flipping one item's `done`; `remove` filters it out.

```ts twoslash
import { Cubit } from '@blac/core';
interface Todo {
  id: string;
  text: string;
  done: boolean;
}
interface TodoState {
  todos: Todo[];
}
class Base extends Cubit<TodoState> {
  constructor() {
    super({ todos: [] });
  }
}
// ---cut---
class TodoCubit extends Base {
  toggle = (id: string) => {
    this.patch({
      todos: this.state.todos.map((t) =>
        t.id === id ? { ...t, done: !t.done } : t,
      ),
    });
  };

  remove = (id: string) => {
    this.patch({ todos: this.state.todos.filter((t) => t.id !== id) });
  };
}
```

In the row component, wire a checkbox to `toggle` and a button to `remove`. A row only needs the bloc, plus the props passed by its parent:

```tsx
function TodoRow({ id, text, done }: Todo) {
  const [, todo] = useBloc(TodoCubit);
  return (
    <li>
      <input type="checkbox" checked={done} onChange={() => todo.toggle(id)} />
      <span>{text}</span>
      <button onClick={() => todo.remove(id)}>✕</button>
    </li>
  );
}
```

## Step 4 — a filter, kept separate from the data

The filter is **view state**: which subset of the list to show. It is _not_ part of the todo data, so it gets its own key. Crucially, keeping it separate is what lets the history in Step 7 record only the data and ignore the view.

Add a `filter` field and a derived `visible` getter that applies it. Getters recompute on every read, so `visible` can never drift out of sync with `todos` or `filter`.

```ts twoslash
import { Cubit } from '@blac/core';

interface Todo {
  id: string;
  text: string;
  done: boolean;
}

type Filter = 'all' | 'active' | 'done';

interface TodoState {
  todos: Todo[];
  filter: Filter;
}

export class TodoCubit extends Cubit<TodoState> {
  constructor() {
    super({ todos: [], filter: 'all' });
  }

  setFilter = (filter: Filter) => this.patch({ filter });

  // Derived on every read — never stored, never stale.
  get visible(): Todo[] {
    const { todos, filter } = this.state;
    if (filter === 'active') return todos.filter((t) => !t.done);
    if (filter === 'done') return todos.filter((t) => t.done);
    return todos;
  }

  get remaining(): number {
    return this.state.todos.filter((t) => !t.done).length;
  }
}
```

Auto-tracking handles getters read during render: the `todo` value returned by `useBloc` is proxied, so `todo.visible` records the `todos` and `filter` reads inside the getter. Here we still use `select` because `visible` allocates a filtered array; the selector makes that computed array the explicit re-render boundary:

```tsx
function List() {
  // Re-render whenever the computed `visible` list changes.
  const [, todo] = useBloc(TodoCubit, {
    select: (_, bloc) => [bloc.visible],
  });
  return (
    <ul>
      {todo.visible.map((t) => (
        <TodoRow key={t.id} {...t} />
      ))}
    </ul>
  );
}
```

`select` returns an array; the component re-renders when any entry changes by identity. That identity boundary matters: this getter may allocate a new filtered array when it runs, so keep the selector focused on values that should wake the list. In this tutorial, `todos` and `filter` are the only fields that affect `visible`, so this wakes the list at the right moments. If unrelated state changes also cause the selector to run, memoize the derived array or select the source fields instead.

### Checkpoint — it works

That is a complete, usable todo app: add, toggle, remove, filter, and a live "items left" count. Try it below — add a few items, toggle some, switch filters. Hit **View code** and edit anything; the preview re-runs live.

<BlacSandpack
  client:only="react"
  files={tutorialInteractiveFiles}
  activeFile="/TodoCubit.ts"
  defaultOpen={false}
/>

Open `/TodoCubit.ts` in the sandbox — that one class is the entire app's logic. The components in `/App.tsx` are thin: each calls `useBloc`, reads its slice, and renders. No reducers, no actions object, no provider.

## Step 5 — seed it from somewhere (async)

Real apps load their initial todos. An async action is just a method that `await`s and emits as it goes — BlaC has no special async primitive. We model the load lifecycle as state so the view can render "loading" and "error" instead of guessing.

We will track the load status alongside the todos. A request-id guard makes a slow response unable to clobber a newer one — the full reasoning is in the [Async guide](/guide/async); here is the shape applied to our Cubit:

```ts twoslash
import { Cubit } from '@blac/core';

interface Todo {
  id: string;
  text: string;
  done: boolean;
}
type Filter = 'all' | 'active' | 'done';

declare const api: { fetchTodos(): Promise<Todo[]> };
// ---cut---
type LoadStatus = 'idle' | 'loading' | 'error';

interface TodoState {
  todos: Todo[];
  filter: Filter;
  status: LoadStatus;
}

export class TodoCubit extends Cubit<TodoState> {
  private requestId = 0;

  constructor() {
    super({ todos: [], filter: 'all', status: 'idle' });
  }

  load = async () => {
    const reqId = ++this.requestId; // claim the latest slot
    this.patch({ status: 'loading' });
    try {
      const todos = await api.fetchTodos();
      if (reqId !== this.requestId) return; // a newer call won; bail
      this.patch({ todos, status: 'idle' });
    } catch {
      if (reqId !== this.requestId) return;
      this.patch({ status: 'error' });
    }
  };
}
```

Kick the load off when the view appears using the `onMount` option — it fires after the bloc is acquired:

```tsx
function App() {
  const [state, todo] = useBloc(TodoCubit, {
    onMount: (bloc) => bloc.load(),
  });

  if (state.status === 'loading') return <p>Loading…</p>;
  if (state.status === 'error') {
    return <button onClick={todo.load}>Retry</button>;
  }
  return <TodoList />;
}
```

There is no Suspense boundary here, by design — the loading branch of this `if` _is_ the fallback, written by hand and fully type-checked. The [Async guide](/guide/async#suspense) explains why BlaC models loading as explicit state rather than throwing promises.

:::tip[Loading-status state is also "view" state]
Like `filter`, the transient `status` describes how to render, not the durable todo data. When we add history next, we will record only the todos — not `status`, not `filter` — so an undo never accidentally rewinds you into a stale "loading" screen.
:::

## Step 6 — route every mutation through one funnel

Before we can add history, every change to the todo list must flow through a single place. Right now `add`, `toggle`, and `remove` each call `patch({ todos: … })` directly. Refactor them to compute the next list and hand it to one private `commit` helper.

This is a pure refactor — behavior is identical — but it gives us the one chokepoint history will hook into.

```ts twoslash
import { Cubit } from '@blac/core';

interface Todo {
  id: string;
  text: string;
  done: boolean;
}
type Filter = 'all' | 'active' | 'done';

interface TodoState {
  todos: Todo[];
  filter: Filter;
}
// ---cut---
export class TodoCubit extends Cubit<TodoState> {
  constructor() {
    super({ todos: [], filter: 'all' });
  }

  // The single funnel: takes the next todo list and commits it.
  private commit = (next: Todo[]) => this.patch({ todos: next });

  add = (text: string) => {
    const trimmed = text.trim();
    if (!trimmed) return;
    this.commit([
      ...this.state.todos,
      { id: crypto.randomUUID(), text: trimmed, done: false },
    ]);
  };

  toggle = (id: string) => {
    this.commit(
      this.state.todos.map((t) => (t.id === id ? { ...t, done: !t.done } : t)),
    );
  };

  remove = (id: string) => {
    this.commit(this.state.todos.filter((t) => t.id !== id));
  };

  setFilter = (filter: Filter) => this.patch({ filter });
}
```

Note `setFilter` does **not** go through `commit` — switching filters should not create an undo entry. That separation we set up in Step 4 is paying off already.

## Step 7 — time travel

Now the finale. Instead of storing a single `todos` array, store an array of _every_ list we have ever committed — a `past` stack — plus a `cursor` pointing at the one currently shown. `commit` appends; `undo`/`redo` just move the cursor; `jumpTo` sets it anywhere.

Because BlaC state is plain immutable values, **a list of past values is already a complete undo history**. There is no diffing, no command pattern, no special engine — the snapshots are the values you were emitting all along.

```ts twoslash
import { Cubit } from '@blac/core';

interface Todo {
  id: string;
  text: string;
  done: boolean;
}
type Filter = 'all' | 'active' | 'done';
// ---cut---
interface TodoState {
  // Every committed snapshot of the todo list, oldest first.
  past: Todo[][];
  // Index into `past` of the snapshot we are showing.
  cursor: number;
  // Filter stays OUTSIDE history — switching it is not undoable.
  filter: Filter;
}

const EMPTY: Todo[] = [];

export class TodoCubit extends Cubit<TodoState> {
  constructor() {
    super({ past: [EMPTY], cursor: 0, filter: 'all' });
  }

  // Drop any "future" we had undone past, append the new snapshot,
  // and point the cursor at it.
  private commit = (next: Todo[]) => {
    const { past, cursor } = this.state;
    const kept = past.slice(0, cursor + 1);
    this.patch({ past: [...kept, next], cursor: kept.length });
  };

  // The list everything else reads: whatever the cursor points at.
  get todos(): Todo[] {
    return this.state.past[this.state.cursor];
  }

  add = (text: string) => {
    const trimmed = text.trim();
    if (!trimmed) return;
    this.commit([
      ...this.todos,
      { id: crypto.randomUUID(), text: trimmed, done: false },
    ]);
  };

  toggle = (id: string) => {
    this.commit(
      this.todos.map((t) => (t.id === id ? { ...t, done: !t.done } : t)),
    );
  };

  remove = (id: string) => {
    this.commit(this.todos.filter((t) => t.id !== id));
  };

  setFilter = (filter: Filter) => this.patch({ filter });

  // Time travel: just move the cursor. No todo data is mutated.
  undo = () => {
    if (this.canUndo) this.patch({ cursor: this.state.cursor - 1 });
  };
  redo = () => {
    if (this.canRedo) this.patch({ cursor: this.state.cursor + 1 });
  };
  jumpTo = (index: number) => this.patch({ cursor: index });

  get canUndo(): boolean {
    return this.state.cursor > 0;
  }
  get canRedo(): boolean {
    return this.state.cursor < this.state.past.length - 1;
  }

  get visible(): Todo[] {
    const { filter } = this.state;
    if (filter === 'active') return this.todos.filter((t) => !t.done);
    if (filter === 'done') return this.todos.filter((t) => t.done);
    return this.todos;
  }

  get remaining(): number {
    return this.todos.filter((t) => !t.done).length;
  }
}
```

What changed, and what did not:

- **`todos` became a getter** over `past[cursor]`. Every action and getter that used to read `this.state.todos` now reads `this.todos` instead — a one-word change at each call site.
- **`add` / `toggle` / `remove` are untouched** apart from that. They still compute a next list and call `commit`. The funnel from Step 6 is the only thing that needed to learn about history.
- **`undo` / `redo` / `jumpTo` mutate nothing but the cursor.** Going back in time is not a destructive operation; the future snapshots are still there until you commit a new change over them.
- **`filter` is still outside the stack**, so switching filters or rewinding history are completely independent.

The undo/redo buttons drive `undo`/`redo`; a row of dots renders one button per snapshot and calls `jumpTo`:

```tsx
function HistoryBar() {
  const [, todo] = useBloc(TodoCubit, {
    select: (_, bloc) => [bloc.canUndo, bloc.canRedo],
  });
  return (
    <div>
      <button disabled={!todo.canUndo} onClick={todo.undo}>
        Undo
      </button>
      <button disabled={!todo.canRedo} onClick={todo.redo}>
        Redo
      </button>
    </div>
  );
}

function Timeline() {
  const [state, todo] = useBloc(TodoCubit, {
    select: (_, bloc) => [bloc.state.cursor, bloc.state.past.length],
  });
  return (
    <div>
      {state.past.map((_, i) => (
        <button
          key={i}
          className={i === state.cursor ? 'current' : ''}
          onClick={() => todo.jumpTo(i)}
        />
      ))}
    </div>
  );
}
```

### Checkpoint — time travel

Add several todos, toggle a few, then hit **Undo** repeatedly and watch the list rewind one change at a time. **Redo** walks forward again. Click any dot in the history row to jump straight to that point. Switch filters at any cursor position — the filter never disturbs the timeline.

<BlacSandpack
  client:only="react"
  files={tutorialTimeTravelFiles}
  activeFile="/TodoCubit.ts"
  defaultOpen={false}
/>

Open `/TodoCubit.ts` and compare it with the Step 4 version above. The diff that bought you a full undo system is small: a `past`/`cursor` pair instead of a bare `todos` array, a slightly smarter `commit`, three cursor-moving methods, and two boolean getters. Everything else — the actions, the components, the filter — barely moved.

## What you learned

- **One Cubit, many thin consumers.** Each component reads only its slice via `useBloc`; action-only components read nothing and never re-render.
- **`patch` for the data path; the replace-vs-merge rule from [Quick Start](/guide/getting-started).** State is always handed over as a fresh immutable value, never mutated in place.
- **Derived getters over stored duplicates.** `visible`, `remaining`, `canUndo` recompute on read and cannot drift; auto-tracking records getter reads in render, and `select` can gate on getter results.
- **View state lives apart from durable data.** `filter` and load `status` describe rendering, so they stay out of the history that records the todos.
- **A single mutation funnel makes cross-cutting features cheap.** Once every change flowed through `commit`, undo/redo/time-travel was an afternoon, not a rewrite.
- **Async is just methods that emit.** A request-id guard and an explicit status union replace Suspense — see the [Async guide](/guide/async).

## Where to go next

- [Mental Model](/guide/mental-model) — _why_ the per-consumer tracking and immutable-state model work the way they do.
- [Dependency Tracking](/react/dependency-tracking) — the full rules behind auto-tracking and `select`.
- [Async](/guide/async) — the loadable surface, cancellation, and the Suspense rationale in depth.
- [Patterns & Recipes](/guide/patterns) — cross-bloc communication, persistence, and more.
- [Persistence](/plugins/persistence) — make your todos (or their history) survive a reload.

---

# TypeScript

> How state shape, action signatures, args, deps, and select all flow from a single Cubit class declaration with minimal annotations.

Source: /guide/typescript/

BlaC is written in TypeScript and assumes you are too. Almost everything you need — state shape, action signatures, the args a consumer must pass — flows from a single class declaration, so most of this page is about _reading_ the inference rather than writing annotations.

This is the discoverable, example-driven tour. For the exhaustive list of exported type utilities (`ExtractState`, `ExtractArgs`, `ExtractDeps`, `InstanceReadonlyState`, and friends), see [Core Types](/core/types).

## Compiler posture

BlaC works with a standard strict React setup. The defaults that matter:

```jsonc
{
  "compilerOptions": {
    "target": "ESNext",
    "jsx": "react-jsx",
    "strict": true,
    "useDefineForClassFields": true,
    "experimentalDecorators": true, // only if you use @blac(...) decorator syntax
  },
}
```

`strict: true` is the assumption behind every inference example below — `strictNullChecks` in particular is what makes `this.args` correctly `Args | undefined` and what forces you to narrow discriminated unions. Without it the examples still compile, but the safety they demonstrate is gone.

Decorators are optional. The `@blac(...)` configuration decorator works as either a legacy (`experimentalDecorators`) decorator _or_ a TC39/stage-3 decorator — pick whichever your toolchain emits. If you'd rather not touch decorator flags at all, the functional form needs none:

```ts twoslash
import { Cubit, blac } from '@blac/core';
// ---cut---
const AuthCubit = blac({ keepAlive: true })(
  class extends Cubit<{ user: string | null }> {
    constructor() {
      super({ user: null });
    }
  },
);
```

`blac(opts)(class)` is a plain higher-order function — no compiler flag, no syntax proposal. The decorator form is sugar over exactly this. See [Configuration](/core/configuration) for the full options union (`keepAlive`, `equality`, `excludeFromDevTools`, `key`).

:::tip[Match getting-started]
The tsconfig block above is the same one in [Getting Started](/guide/getting-started). If you change one, change both.
:::

## The three generics

Both `Cubit` and `StateContainer` take the same three type parameters, in the same order — `State`, `Args`, `Deps`:

```ts
abstract class StateContainer<
  S extends object = any,
  Args = void,
  Deps extends object = Record<string, never>,
> extends StructuralContainer<S> {}

abstract class Cubit<
  S extends object = any,
  Args = void,
  Deps extends object = Record<string, never>,
> extends StateContainer<S, Args, Deps> {}
```

So:

| Param  | Constraint       | Default                 | What it is                                       |
| ------ | ---------------- | ----------------------- | ------------------------------------------------ |
| `S`    | `extends object` | `any`                   | The state shape. Always provide it.              |
| `Args` | none             | `void`                  | Typed construction input passed to `init(args)`. |
| `Deps` | `extends object` | `Record<string, never>` | Non-serializable handles read via `this.deps`.   |

You only declare the ones you use, left to right. State-only is the common case:

```ts twoslash
import { Cubit } from '@blac/core';
// ---cut---
interface CounterState {
  count: number;
}

class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0 });
  }

  increment = () => this.emit({ count: this.state.count + 1 });
}
```

### How inference flows from `S`

Declaring `S` is the only annotation you need — `state`, `emit`, `update`, and `patch` all specialize from it. Hover any of these and you'll see the concrete type, not `any`:

```ts twoslash
import { Cubit } from '@blac/core';
// ---cut---
interface CounterState {
  count: number;
  label: string;
}

class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0, label: 'start' });
  }

  demo() {
    const c = this.state.count;
    //    ^?
    this.emit({ count: 1, label: 'a' }); // emit/update take the FULL state
    this.update((s) => ({ ...s, count: s.count + 1 }));
    this.patch({ count: 2 }); // patch takes DeepPartial<S>
  }
}
```

`emit` and the value `update`'s callback returns both require the _complete_ `S` — omit a key and it's a type error, which is the compiler enforcing the replace-not-merge rule. `patch` accepts a `DeepPartial<S>`, so partial objects are legal there and only there:

```ts twoslash
// @errors: 2345
import { Cubit } from '@blac/core';
// ---cut---
interface CounterState {
  count: number;
  label: string;
}

class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0, label: 'start' });
  }

  bad() {
    this.emit({ count: 1 }); // missing `label` — emit replaces, so this is an error
  }
}
```

## Getters as derived state

Anything computed from state belongs in a getter. Getters infer their return type, can't drift from the state they read, and require no extra type plumbing:

```ts twoslash
import { Cubit } from '@blac/core';
// ---cut---
interface CartState {
  items: { price: number; qty: number }[];
}

class CartCubit extends Cubit<CartState> {
  constructor() {
    super({ items: [] });
  }

  get total(): number {
    return this.state.items.reduce((sum, i) => sum + i.price * i.qty, 0);
  }

  get isEmpty() {
    // return type inferred as boolean — no annotation needed
    return this.state.items.length === 0;
  }
}
```

:::tip[Getters track in render]
Reading `cart.total` directly in render is reactive: the `bloc` returned by `useBloc` is proxied, and `this.state` inside the getter records through the current state proxy. Use [`select`](#typing-select) (`select: (state, bloc) => [bloc.total]`) only when the getter's return value should be the explicit re-render boundary. This is a _runtime_ tracking rule, not a type rule — the types let you read `cart.total` anywhere. See [Dependency Tracking](/react/dependency-tracking).
:::

## Discriminated unions and narrowing

The single most useful TypeScript pattern in BlaC is a discriminated-union state. Model a request as a `status` tag and the compiler will _force_ you to handle every case and _forbid_ you from reading a field before it exists.

Declare the union as the state type. Each variant carries only the data that's valid in that state:

```ts twoslash
import { Cubit } from '@blac/core';
// ---cut---
interface User {
  id: string;
  name: string;
}

type UserState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; user: User }
  | { status: 'error'; error: string };

class UserCubit extends Cubit<UserState> {
  constructor() {
    super({ status: 'idle' });
  }

  load = async (id: string) => {
    this.emit({ status: 'loading' });
    try {
      const user = await fetchUser(id);
      this.emit({ status: 'success', user });
    } catch (e) {
      this.emit({ status: 'error', error: String(e) });
    }
  };
}

declare function fetchUser(id: string): Promise<User>;
```

Because `emit` wants the full `UserState`, you can't emit `{ status: 'success' }` without a `user` — the variant's required fields are checked at the emit site:

```ts twoslash
// @errors: 2345
import { Cubit } from '@blac/core';
// ---cut---
type UserState =
  | { status: 'idle' }
  | { status: 'success'; user: { id: string } };

class UserCubit extends Cubit<UserState> {
  constructor() {
    super({ status: 'idle' });
  }

  oops() {
    this.emit({ status: 'success' }); // forgot `user`
  }
}
```

### Narrowing on the read side

The payoff is on the read side. Switch on `state.status` and inside each branch TypeScript narrows the union — `state.user` exists only in the `success` arm, `state.error` only in `error`. Here the consumer is a plain function so the inference is visible; in a component the same `state` comes out of `useBloc`:

```ts twoslash
import { Cubit } from '@blac/core';
import { useBloc } from '@blac/react';
interface User {
  id: string;
  name: string;
}
type UserState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; user: User }
  | { status: 'error'; error: string };
declare class UserCubit extends Cubit<UserState> {}
// ---cut---
function userLabel(): string {
  const [state] = useBloc(UserCubit);

  switch (state.status) {
    case 'idle':
      return 'Not loaded';
    case 'loading':
      return 'Loading…';
    case 'success':
      return `Hello ${state.user.name}`;
    //                      ^? (state narrowed to the success variant)
    case 'error':
      return `Failed: ${state.error}`;
  }
}
```

Rendered in a component, that's an ordinary `switch` over `state.status`:

```tsx
function UserCard() {
  const [state] = useBloc(UserCubit);

  switch (state.status) {
    case 'idle':
      return <p>Not loaded</p>;
    case 'loading':
      return <p>Loading…</p>;
    case 'success':
      return <p>Hello {state.user.name}</p>; // state.user only exists here
    case 'error':
      return <p>Failed: {state.error}</p>;
  }
}
```

Reaching for a field outside its variant is a compile error, which is exactly the bug class discriminated unions exist to kill:

```ts twoslash
// @errors: 2339
import { Cubit } from '@blac/core';
import { useBloc } from '@blac/react';
type UserState =
  | { status: 'loading' }
  | { status: 'success'; user: { name: string } };
declare class UserCubit extends Cubit<UserState> {}
// ---cut---
function userName(): string {
  const [state] = useBloc(UserCubit);
  // no narrowing yet — `user` doesn't exist on the `loading` arm
  return state.user.name;
}
```

:::tip[Exhaustiveness checking]
Give your `switch` a `default` that assigns `state` to `never`. Add a new variant later and forget to handle it, and the assignment fails to compile — a free reminder.

```ts twoslash
// @errors: 2322
type UserState = { status: 'idle' } | { status: 'loading' };
declare const state: UserState;
// ---cut---
function render(): string {
  switch (state.status) {
    case 'idle':
      return 'idle';
    // forgot the 'loading' case
    default: {
      const _exhaustive: never = state; // error: 'loading' is not assignable to never
      return _exhaustive;
    }
  }
}
```

:::

Narrowing works identically inside a getter — derive a flag once and read it everywhere:

```ts twoslash
import { Cubit } from '@blac/core';
// ---cut---
type UserState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; user: { name: string } }
  | { status: 'error'; error: string };

class UserCubit extends Cubit<UserState> {
  constructor() {
    super({ status: 'idle' });
  }

  get displayName(): string {
    const s = this.state;
    return s.status === 'success' ? s.user.name : 'Guest';
    //                                  ^? (narrowed to the success variant)
  }
}
```

## Typing `select`

`select` lets a consumer use an explicit dependency array instead of auto-tracked reads. The component re-renders only when one of those values changes (compared per-index with `Object.is`). Its signature is:

```ts twoslash
import type {
  ExtractState,
  InstanceReadonlyState,
  StateContainerConstructor,
} from '@blac/core';
// ---cut---
type Select<TBloc extends StateContainerConstructor> = (
  state: ExtractState<TBloc>,
  bloc: InstanceReadonlyState<TBloc>,
) => unknown[];
```

Both arguments are fully inferred from the bloc you pass to `useBloc` — `state` is the readonly state, `bloc` is the readonly instance (so getters are reachable). The return type is `unknown[]`, an array of whatever values gate the re-render:

```ts twoslash
import { Cubit } from '@blac/core';
import { useBloc } from '@blac/react';
// ---cut---
interface CartState {
  items: { price: number; qty: number }[];
  coupon: string | null;
}

class CartCubit extends Cubit<CartState> {
  constructor() {
    super({ items: [], coupon: null });
  }
  get total() {
    return this.state.items.reduce((s, i) => s + i.price * i.qty, 0);
  }
}

function cartTotal(): number {
  // re-renders only when `total` or item count changes
  const [, cart] = useBloc(CartCubit, {
    select: (state, bloc) => [bloc.total, state.items.length],
    //                ^?
  });
  return cart.total;
}
```

`state` is `Readonly`, so `select` can't accidentally mutate it; that's also why reading a getter here (`bloc.total`) is the supported way to make a derived value drive re-renders. Keep the selector referentially stable — a fresh function each render re-keys the subscription. See [useBloc](/react/use-bloc#select).

## Conditional `args`

When a bloc declares an `Args` type, `args` in `useBloc` is _optional_ — you may omit it and the hook will inherit args from a `<BlocProvider>` ancestor, or fall back to the default instance key. When the bloc's `Args` is the default `void`, passing `args` is _forbidden_. The type system enforces both directions through a conditional option type (verified in `@blac/react`'s `types.ts`):

```ts twoslash
import type { ExtractArgs, StateContainerConstructor } from '@blac/core';
// ---cut---
type ArgsOption<T extends StateContainerConstructor> =
  ExtractArgs<T> extends void ? { args?: never } : { args?: ExtractArgs<T> };
```

`ExtractArgs<T>` pulls the second generic off the class. If it's `void`, the option becomes `{ args?: never }` — present-but-forbidden. Otherwise it's `{ args?: Args }` — optional and typed.

A void-args bloc rejects `args` (the option's type there is `never`):

```ts twoslash
// @errors: 2322
import { Cubit } from '@blac/core';
import { useBloc } from '@blac/react';
// ---cut---
class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
}

function count(): number {
  // CounterCubit has no Args → passing `args` is a type error
  const [state] = useBloc(CounterCubit, { args: { foo: 1 } });
  return state.count;
}
```

A bloc that declares `Args` accepts it as optional — omitting it inherits args from a `<BlocProvider>` ancestor, else the default key is used. When you do pass `args`, it is type-checked against the declared shape:

```ts twoslash
import { Cubit } from '@blac/core';
import { useBloc } from '@blac/react';
// ---cut---
interface UserState {
  name: string;
}

class UserCubit extends Cubit<UserState, { userId: string }> {
  constructor() {
    super({ name: '' });
  }
  protected init(args: { userId: string }) {
    void args.userId;
  }
}

function userName(): string {
  // args is optional — omit to inherit from BlocProvider, or pass explicitly:
  const [state] = useBloc(UserCubit, { args: { userId: '42' } });
  return state.name;
}
```

Provide it correctly and `args` is type-checked against the declared shape:

```ts twoslash
import { Cubit } from '@blac/core';
import { useBloc } from '@blac/react';
interface UserState {
  name: string;
}
class UserCubit extends Cubit<UserState, { userId: string }> {
  constructor() {
    super({ name: '' });
  }
}
// ---cut---
function userName(userId: string): string {
  const [state, user] = useBloc(UserCubit, { args: { userId } });
  //            ^?
  return state.name;
}
```

Inside the bloc, the `args` getter is `Args | undefined` (it's unset until the instance is acquired), so reach for the value `init(args)` hands you when you need it non-optionally:

```ts twoslash
import { Cubit } from '@blac/core';
// ---cut---
class UserCubit extends Cubit<{ name: string }, { userId: string }> {
  constructor() {
    super({ name: '' });
  }

  protected init(args: { userId: string }) {
    // `args` here is the non-optional declared shape
    void this.fetch(args.userId);
  }

  retry() {
    // the `args` GETTER is `Args | undefined` — guard it
    const id = this.args?.userId;
    //    ^?
    if (id) void this.fetch(id);
  }

  private async fetch(_id: string) {}
}
```

## A typed custom hook

Wrapping `useBloc` in a domain hook is the idiomatic way to give a feature a named, typed entry point. Inference is preserved end to end as long as you don't widen the return — let it flow:

```ts twoslash
import { Cubit } from '@blac/core';
import { useBloc } from '@blac/react';
// ---cut---
interface TodoState {
  items: string[];
  filter: 'all' | 'active' | 'done';
}

class TodoCubit extends Cubit<TodoState> {
  constructor() {
    super({ items: [], filter: 'all' });
  }
  add = (t: string) => this.patch({ items: [...this.state.items, t] });
  get count() {
    return this.state.items.length;
  }
}

// Custom hook: no explicit return annotation needed — it's inferred as
// [Readonly<TodoState>, InstanceReadonlyState<typeof TodoCubit>, ...]
function useTodos() {
  return useBloc(TodoCubit);
}

function todoCount(): number {
  const [state, todo] = useTodos();
  //            ^?
  todo.add('x');
  return state.items.length;
}
```

For a hook that takes arguments, type the parameters and forward them — the bloc's `Args` requirement still applies at the call site inside the hook:

```ts twoslash
import { Cubit } from '@blac/core';
import { useBloc } from '@blac/react';
// ---cut---
interface UserState {
  name: string;
}

class UserCubit extends Cubit<UserState, { userId: string }> {
  constructor() {
    super({ name: '' });
  }
  protected init(args: { userId: string }) {
    void args.userId;
  }
}

// the hook's signature documents what the feature needs
function useUser(userId: string) {
  return useBloc(UserCubit, { args: { userId } });
}

function profileName(id: string): string {
  const [state] = useUser(id);
  return state.name;
}
```

If you _do_ want to annotate the return — for a public package API, say — derive it from the bloc rather than restating the shape. `ExtractState` and `InstanceReadonlyState` are exported from `@blac/core`:

```ts twoslash
import { Cubit } from '@blac/core';
import type { ExtractState, InstanceReadonlyState } from '@blac/core';
import { useBloc } from '@blac/react';
declare class TodoCubit extends Cubit<{ items: string[] }> {}
// ---cut---
type TodoState = ExtractState<typeof TodoCubit>;
//   ^?
type TodoBloc = InstanceReadonlyState<typeof TodoCubit>;

function useTodos(): [TodoState, TodoBloc] {
  const [state, bloc] = useBloc(TodoCubit);
  return [state, bloc];
}
```

These utilities, plus `ExtractArgs`, `ExtractDeps`, and the rest, are documented in full in [Core Types](/core/types).

## See also

- [Core Types](/core/types) — the exhaustive reference for every exported type utility
- [Cubit](/core/cubit) — `emit` / `update` / `patch`, `init`, getters, and lifecycle
- [useBloc](/react/use-bloc) — the hook, its option surface, and `select`
- [Passing Inputs](/guide/inputs) — the `args` / `deps` / events model in depth
- [Dependency Tracking](/react/dependency-tracking) — how getter reads participate in auto-tracking

---

# Versioning & Stability

> BlaC's semver policy, the React and browser support matrix, the stability tier of every package, and where to find the deprecation record.

Source: /guide/versioning/

This page documents BlaC's versioning policy, the React and browser support matrix,
the stability tier of every package, and where to find the full deprecation record.

:::caution[Beta / pre-release]
BlaC v2 is in pre-release (beta). While in beta, **breaking API changes may ship in patch releases** without a major version bump — pin exact versions and check the changelog before upgrading. The strict semver policy below resumes once v2 is officially out of beta.
:::

## Semver policy

BlaC v2 is currently in **beta**. Until it leaves beta, the team reserves the
right to ship breaking public-API changes in **patch** releases (`2.0.x`) so the
API can be refined ahead of a stable `2.x` line. Pin exact versions and read the
changelog before every upgrade.

Once v2 is out of beta, all published BlaC packages follow
[Semantic Versioning 2.0](https://semver.org):

- **PATCH** — backwards-compatible bug fixes. Safe to upgrade any time.
- **MINOR** — new backwards-compatible features. Safe to upgrade.
- **MAJOR** — breaking public API changes. The changelog documents every
  breaking change before the release; always read it before upgrading a major.

"Public API" means anything exported without an `@internal` JSDoc tag. Items
tagged `@internal` may change in any release, including patches.

### Release channel

All packages are published to the npm public registry from the `main` branch.
There is no separate `next` or `canary` channel at this time. Pre-release
versions (e.g. `0.0.x`) indicate that the package's own API is still stabilizing;
they still follow the intent of semver within the `0.y.z` range (i.e. any minor
bump may be breaking for `0.x` packages).

## Current package versions

| Package              | npm name                 | Version  | Stability    |
| -------------------- | ------------------------ | -------- | ------------ |
| Core                 | `@blac/core`             | `2.0.18` | Beta         |
| React bindings       | `@blac/react`            | `2.0.18` | Beta         |
| DevTools connect     | `@blac/devtools-connect` | `2.0.21` | Beta         |
| DevTools UI          | `@blac/devtools-ui`      | `2.0.20` | Beta         |
| Logging plugin       | `@blac/logging-plugin`   | `2.0.19` | Beta         |
| Persistence plugin   | `@blac/plugin-persist`   | `0.0.14` | Experimental |
| DirtyTalk engine     | `@dirtytalk/engine`      | `0.0.4`  | Experimental |
| DirtyTalk structural | `@dirtytalk/structural`  | `0.0.6`  | Experimental |
| DirtyTalk spatial    | `@dirtytalk/spatial`     | `0.0.4`  | Experimental |

### Why DirtyTalk ships at `0.0.x` alongside core `2.0.x`

`@blac/core` and `@blac/react` are feature-complete and battle-tested in
practice, but remain in **beta** while their v2 public API is finalized — see the
beta notice above. The `@dirtytalk/*` packages are the reactive-tracking
substrate extracted from that work — they power the proxy and path-interning
inside core — but their own _public_ APIs are still being refined as additional
use-cases (spatial dirty tracking, standalone reactive trees) are explored.

Publishing them at `0.0.x` is an honest signal: the implementations are
production-proven inside core, but the DirtyTalk package boundaries, export
shapes, and hook points are subject to change without a semver major. If you
build directly on `@dirtytalk/*`, pin the exact version and watch the changelog.
If you use only `@blac/core` and `@blac/react`, the DirtyTalk internals are
opaque to you.

## Stability badge legend

Pages throughout these docs use these stability tiers:

| Badge            | Meaning                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Beta**         | Feature-complete and usable in production, but the v2 public API is still being finalized. Breaking changes may ship in patch releases until v2 leaves beta — pin exact versions. |
| **Stable**       | Public API follows semver strictly. No breaking changes without a major bump. Safe to use in production.                        |
| **Experimental** | The feature or package is usable but the API shape is still evolving. May see breaking changes in minor or even patch releases. |
| **Internal**     | Tagged `@internal` in source. Not part of the public API contract. May change or disappear in any release.                      |

Stability badges apply to packages as a whole (see the table above) and to
individual APIs within a package — for example, `APPLY_DEPS` and `REMOVE_DEPS_OWNER`
are `@internal` symbols exported from `@blac/core` for framework-integration use
only and are not subject to semver guarantees.

## React and browser support matrix

### React

`@blac/react` declares `react` as a peer dependency and is tested against the
following ranges:

| React version      | Supported       | Notes                                                          |
| ------------------ | --------------- | -------------------------------------------------------------- |
| React 18           | Yes (`^18.0.0`) | Full support; `useSyncExternalStore` is used for subscription. |
| React 19           | Yes (`^19.0.0`) | Full support including React Compiler compatibility.           |
| React 17 and below | No              | `useSyncExternalStore` is required; no polyfill is bundled.    |

The `@types/react` peer is optional — if you are on a JavaScript project you can
omit it. Testing utilities in `@blac/react/testing` additionally accept
`@testing-library/react ^14.0.0 || ^15.0.0 || ^16.0.0` as an optional peer.

### Browser and runtime targets

All packages compile to **ES2021** (the TypeScript `target` used across the
monorepo). The output format is dual ESM + CJS, so both modern bundlers and
Node.js `require()` are supported.

| Target       | Details                                                                                                                                                                |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Browsers     | Any browser supporting ES2021 natively (Chrome 92+, Firefox 90+, Safari 15+, Edge 92+). Older browsers require a transpilation step in your own build.                 |
| Node.js      | The ESM entry works with Node 16+ (native ESM). The CJS entry works with Node 14+.                                                                                     |
| Bundlers     | Vite, webpack 5, Rollup, esbuild — any bundler that honours `exports` map.                                                                                             |
| React Native | Not officially tested. The `@blac/core` state-only layer has no DOM dependencies; `@blac/react` wraps React hooks and should work in RN environments, but is untested. |

### `@dirtytalk/structural` React peer

`@dirtytalk/structural` declares `react >= 18` as an optional peer dependency
for its `/react` subpath export. If you do not import the React subpath you do
not need React installed.

## Deprecations

When a public API is slated for removal it is first marked `@deprecated` in the
type definitions, with the JSDoc tag pointing at the replacement. Deprecated APIs
keep working for the remainder of the current major and are removed only on the
next major bump, so a `@deprecated` warning is never a build break on its own.

The changelog is the canonical record: every deprecation, the version that
introduced it, and the version that removes it are listed there. Run your build
with deprecation warnings enabled to surface anything you are still relying on
before you upgrade across a major.

---

# Bloc communication

> Use depend() to let one Cubit read another bloc's state or call its methods without holding a hard reference, with opt-in reactive cross-bloc tracking.

Source: /core/bloc-communication/

Real apps are made of several focused blocs — a cart, a shipping calculator, an auth session — that need to read each other's state or trigger each other's behavior. The naive fix is to merge them into one giant Cubit, but that destroys the very separation that makes each piece testable and reusable.

`depend()` is the answer: it lets one [Cubit](/core/cubit) declare a dependency on another and read its state (or call its methods) **without holding a hard reference and without the two classes importing each other's instances**. The dependency is resolved lazily from the [registry](/core/instance-management), so each bloc stays decoupled from how the other is created or keyed.

:::note[Mental model]
Think of `depend()` as "I need to know about that bloc, but I don't own it." It records an intent ("CartCubit depends on ShippingCubit") and hands you a handle that fetches the live instance on demand — `.untracked()` for a plain read or method call, `.track()` to subscribe the reading component reactively. Ownership and lifetime still flow through the registry's [ref counting](/core/instance-management) — see [Lifecycle: who keeps the dependency alive?](#lifecycle-who-keeps-the-dependency-alive) below for the gotcha this creates.
:::

## `depend(Type)`

Declare a cross-bloc dependency from inside a Cubit. Returns a branded handle with two accessors: `.untracked()` resolves the other instance from the registry on each call, and `.track()` does the same _plus_ opts the reading React consumer into automatic cross-bloc re-renders.

```ts
protected depend<T extends StateContainerConstructor>(
  Type: T,
  defaultArgs?: ExtractArgs<T>,
): DepHandle<T>
```

| Parameter     | Type                                  | Required | Description                                                                                                                                                                |
| ------------- | ------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Type`        | `T extends StateContainerConstructor` | yes      | The state-container class to depend on.                                                                                                                                    |
| `defaultArgs` | `ExtractArgs<T>`                      | no       | The `args` that identify which [keyed instance](/core/instance-management) to resolve when an accessor is called without its own `args`. Defaults to the default instance. |

**Returns:** a [`DepHandle<T>`](#what-track-returns) — a branded handle with two methods:

- **`handle.untracked(options?)`** resolves the live instance from the registry lazily, on each call. Use it for imperative method calls (`this.shipping.untracked().recalc()`) and one-off state reads that should _not_ subscribe the reader.
- **`handle.track(options?)`** resolves the same instance and, inside a React render, opts the current consumer into automatic cross-bloc re-renders — see [Auto-tracking with `.track()`](#auto-tracking-with-track).

Both accept an optional `{ args }` to resolve a specific [keyed instance](/core/instance-management) at call time (overriding `defaultArgs`), so the resolved instance can derive from current state. The handle is returned immediately at declaration time; resolution happens each time you call an accessor.

:::tip[This is the part most state libraries can't do]
A getter on one bloc can read **another bloc's** state (and its getters) and, via `.track()`, the React component reading that getter wakes when _either_ bloc changes — with no `useBloc(Other)`, no selectors, and no provider wiring. Jump to [Auto-tracking with `.track()`](#auto-tracking-with-track) for the whole story.
:::

**Behavior.** `depend()` records the dependency (the `Type` → `instanceKey` pair is stored on the instance), then returns a handle whose accessors call `this._registry.ensure(Type, key)` on each invocation. Resolution is **lazy per call**, which keeps the surface immune to dep-instance churn — if the depended-on instance is disposed and recreated, the next accessor call simply returns the new one. `.untracked()` does **not** wire a reactive subscription between the two blocs: `this.shipping.untracked().state.rate` is a plain read inside the bloc. Reactivity comes from the consumer — `.track()` inside a tracked getter (a React component's auto-tracking proxy), or an explicit `watch()`. A naive always-on auto-bridge would loop on mutual deps, which is why tracking is opt-in per read.

:::caution[`depend()` does not auto-subscribe]
`depend()` only records the dependency and resolves the instance — it does **not** wire up a reactive subscription between the two blocs. Inside the bloc, `this.shipping.untracked().state.rate` is a plain read; it returns the current value but does not cause `CartCubit` to re-emit when shipping changes.

Reactivity is supplied by the consumer that reads the derived value: a React component via the [auto-tracking proxy](/react/dependency-tracking), or non-React code via [`watch()`](/core/watch). If you need a bloc itself to react to a dependency's changes, subscribe explicitly (e.g. `watch(...)`) and tear it down in [`dispose`](/core/system-events). This is deliberate — a naive auto-bridge would loop forever on mutual dependencies.
:::

```ts twoslash
import { Cubit } from '@blac/core';

class ShippingCubit extends Cubit<{ rate: number }> {
  constructor() {
    super({ rate: 5.99 });
  }
}

interface CartItem {
  price: number;
}

class CartCubit extends Cubit<{ items: CartItem[] }> {
  private shipping = this.depend(ShippingCubit);

  constructor() {
    super({ items: [] });
  }

  get total() {
    const subtotal = this.state.items.reduce((sum, i) => sum + i.price, 0);
    // Plain (untracked) read — see `.track()` below for the reactive version.
    return subtotal + this.shipping.untracked().state.rate;
  }
}
```

### How `depend()` works

1. `this.depend(ShippingCubit)` records the dependency (`ShippingCubit` → instance key) and returns a `DepHandle<ShippingCubit>`.
2. Calling `.untracked()` (or `.track()`) resolves the instance via [`ensure()`](/core/instance-management) from the registry — creating it if it does not exist yet.
3. The dependency is resolved **lazily on every call**, not when you declare it. This keeps `CartCubit` immune to dep-instance churn: if the depended-on instance is disposed and recreated, the next `shipping.untracked()` call simply returns the new one.
4. When a React component reads `cart.total`, reactivity comes from the render-time tracker. Plain `this.shipping.untracked().state.rate` reads a live (untracked) instance — the component re-renders only if it is also subscribed to `ShippingCubit` via `useBloc`. To opt into automatic cross-bloc subscriptions without a second `useBloc` call, use [`.track()`](#auto-tracking-with-track) on the handle.

### Named instance dependencies

By default, `depend(Type)` targets the `'default'` instance key. To depend on a specific [named instance](/core/instance-management), pass the `defaultArgs` that identify it (or override per call with `.track({ args })` / `.untracked({ args })`):

```ts twoslash
import { Cubit } from '@blac/core';

class EditorCubit extends Cubit<{ content: string }, { docId: string }> {
  static key = (a: { docId: string }) => a.docId;
  constructor() {
    super({ content: '' });
  }
}

class ReviewCubit extends Cubit<{ approved: boolean }> {
  private editor = this.depend(EditorCubit, { docId: 'doc-42' });

  constructor() {
    super({ approved: false });
  }
}
```

The `args` passed here must resolve to the same key the target instance is acquired under (via its `static key` or structural hash). Mismatched args resolve a _different_ instance — see [Inputs and identity](/guide/inputs) for how keys are derived.

## Alternatives

### `ensure()` and `borrow()`

For one-off access outside the class constructor, use registry functions directly:

```ts twoslash
import { Cubit, borrow } from '@blac/core';

interface NotificationState {
  message: string;
}

class UserCubit extends Cubit<{ name: string }> {
  constructor() {
    super({ name: '' });
  }
}

class NotificationCubit extends Cubit<NotificationState> {
  constructor() {
    super({ message: '' });
  }

  showUserError = () => {
    const user = borrow(UserCubit); // must already exist
    this.patch({ message: `Error for ${user.state.name}` });
  };
}
```

### When to use which

| Approach             | Use when                                               |
| -------------------- | ------------------------------------------------------ |
| `this.depend(Class)` | Ongoing dependency used in getters or multiple methods |
| `ensure(Class)`      | One-off access; creates if missing                     |
| `borrow(Class)`      | One-off access; instance must already exist            |

## Lifecycle: who keeps the dependency alive?

`depend()` resolves through `ensure()`, and **`ensure()` does not take a reference** — it creates the instance if needed but does not increment the dependency's ref count. This has a concrete consequence worth internalizing:

> A bloc you `depend()` on is not kept alive _by you_. If nothing else holds a reference to it, the registry may dispose it the moment its own ref count hits zero.

In practice this is usually fine, because the depended-on bloc is also mounted somewhere (a component holds a ref via [`useBloc`](/react/use-bloc)). But it is a real gotcha when the dependency is a "pure derived" service that no component renders directly.

There are two clean ways to guarantee a dependency stays alive:

- **`keepAlive`** — mark the dependency class with `@blac({ keepAlive: true })` so the registry never auto-disposes it. See [Configuration](/core/configuration).
- **The cascade does the right thing on teardown.** When a bloc that _created_ its dependencies (via `ensure`) is itself disposed and reaches zero refs, the registry cascades disposal to those deps if they too have zero refs and are not `keepAlive`. So a `depend()`-only dependency graph tears itself down cleanly without leaking.

<details>
<summary>Why lazy resolution matters here</summary>

Because the handle re-resolves on every call, a dependency that _was_ disposed out from under you is not a dangling pointer — the next `shipping.untracked()` simply re-creates a fresh instance via `ensure()`. The cost is that any state the old instance held is gone. If that state must survive, use `keepAlive` rather than relying on re-creation.

</details>

## Avoiding cycles and constructor-time reads

Two cross-bloc patterns reliably cause bugs. Both are easy to avoid once you know the rule: **resolve dependencies lazily, read them late.**

:::caution[Common mistakes]
**Reading a dependency's state in the constructor.** The dependency may not be initialized yet — its `init()` may not have run, so its state is still the raw initial value. Read deps inside getters or methods (or `init`), never in the constructor.

**Mutual `depend()` between two blocs.** `A` depends on `B` and `B` depends on `A`. Declaration alone is safe (resolution is lazy), but if you also wire explicit subscriptions both ways, a change in one re-emits the other forever. The channel's same-tick coalescing limits the blast radius, but a true mutual reactive cycle is a design smell — extract the shared concern into a third bloc that both depend on, with the dependency arrows pointing one way.
:::

When you find yourself wanting a cycle, it usually signals that two blocs are really one concern, or that a piece of shared state belongs in a third, lower-level bloc. See [Best Practices](/guide/best-practices) for when cross-bloc coupling is a smell versus a sound dependency.

## Calling methods on dependencies

Dependencies aren't just for reading state — you can call methods on them to trigger side effects in other blocs.

```ts twoslash
import { Cubit } from '@blac/core';

interface Message {
  userId: string;
  text: string;
}

interface ChannelState {
  channelId: string;
  messages: Message[];
}

class NotificationCubit extends Cubit<{ unread: number }> {
  constructor() {
    super({ unread: 0 });
  }

  incrementUnread = (_channelId: string) => {
    this.update((s) => ({ unread: s.unread + 1 }));
  };

  clearUnread = (_channelId: string) => {
    this.emit({ unread: 0 });
  };
}

class ChannelCubit extends Cubit<ChannelState> {
  private notifications = this.depend(NotificationCubit);

  constructor() {
    super({ channelId: '', messages: [] });
  }

  receiveMessage = (message: Message) => {
    this.update((s) => ({
      ...s,
      messages: [...s.messages, message],
    }));

    // Trigger a side effect in another bloc. `.untracked()` resolves the live
    // instance without subscribing — a method call needs no reactivity.
    this.notifications.untracked().incrementUnread(this.state.channelId);
  };

  markAsRead = () => {
    this.notifications.untracked().clearUnread(this.state.channelId);
  };
}
```

This keeps notification logic in `NotificationCubit` while letting `ChannelCubit` coordinate when it fires.

:::tip[Reading state vs calling methods]
These behave differently with respect to re-renders. **Reading** a dependency's `state` via `.track()` inside a getter subscribes the consuming component to that path (via the [auto-tracking proxy](/react/dependency-tracking)). **Calling a method** on a dependency through `.untracked()` — like `incrementUnread()` above — does not subscribe to anything; it just triggers a side effect in the other bloc. A component that only triggers actions on a dependency will not re-render when that dependency's state changes, which is exactly what you want for action-only coordination.
:::

## Derived getters across blocs

Getters that read from multiple blocs with `.track()` are wired through the proxy: a component reading `dashboard.summary` subscribes to every dependency path the getter touches (`auth.user.name`, `cart.items`), and re-renders only when one of those changes.

```ts twoslash
import { Cubit } from '@blac/core';

class AuthCubit extends Cubit<{ user: { name: string } | null }> {
  constructor() {
    super({ user: null });
  }
}

class CartCubit extends Cubit<{ items: string[] }> {
  constructor() {
    super({ items: [] });
  }
}

class DashboardCubit extends Cubit<Record<string, never>> {
  private auth = this.depend(AuthCubit);
  private cart = this.depend(CartCubit);

  constructor() {
    super({});
  }

  get summary() {
    const [authState] = this.auth.track();
    const [cartState] = this.cart.track();
    const user = authState.user;
    const itemCount = cartState.items.length;
    return `${user?.name ?? 'Guest'} has ${itemCount} items`;
  }
}
```

:::caution[A coordinating bloc with empty state is a smell]
`Cubit<{}>` here holds no state of its own — it exists purely to compose other blocs' state. That is fine for a small read-only aggregator, but if it grows methods and starts coordinating writes across many blocs, it tends to become a god-bloc that re-couples everything `depend()` was meant to decouple. Prefer reading derived values directly in the component (or a small focused bloc per view) over one central dashboard bloc. See [Best Practices](/guide/best-practices).
:::

## Auto-tracking with `.track()`

`this.depend(OtherBloc).untracked()` gets the live instance. Reading its state inside a getter — `this.shipping.untracked().state.rate` — is a plain live read. A React consumer won't re-render when `ShippingCubit` emits unless the component also calls `useBloc(ShippingCubit)` itself.

Calling `.track()` on the handle opts the **current render's consumer** into automatic cross-bloc subscriptions, without a second `useBloc` at the component level:

```ts
import { Cubit } from '@blac/core';

class PriceBloc extends Cubit<{ amount: number }> {
  constructor() {
    super({ amount: 100 });
  }
}

class CartBloc extends Cubit<{ qty: number }> {
  private price = this.depend(PriceBloc);
  constructor() {
    super({ qty: 2 });
  }

  get total() {
    const [priceState] = this.price.track(); // opt in to cross-bloc tracking
    return this.state.qty * priceState.amount;
  }
}
```

A component that reads `cart.total` during render auto-subscribes to both `CartBloc` **and** `PriceBloc` — no `useBloc(PriceBloc)` needed:

```ts
// In a React component:
const [, cart] = useBloc(CartBloc);
return <span>{cart.total}</span>; // re-renders when qty OR price.amount changes
```

### What `.track()` returns

```ts
handle.track(); // → [trackedState, depProxy]
```

| Element        | Type               | Description                                                                                                                                                                                   |
| -------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trackedState` | dep's state        | Snapshot recorded by the render-time tracker. Access fields here to record leaf paths (e.g. `priceState.amount`).                                                                             |
| `depProxy`     | dep instance proxy | The dep wrapped in a tracking proxy. Use this to call getters on the dep; those getters' own `this.state.x` reads are also tracked (see [Dep getter transitivity](#dep-getter-transitivity)). |

### Render-aware: safe everywhere

`.track()` is **render-aware**. Outside a React render — in an event handler, an effect, or a plain method — it degrades gracefully to live values with no subscription side effects:

```ts
import { Cubit } from '@blac/core';

class PriceBloc extends Cubit<{ amount: number }> {
  constructor() {
    super({ amount: 100 });
  }
}

class CartBloc extends Cubit<{ qty: number }> {
  private price = this.depend(PriceBloc);
  constructor() {
    super({ qty: 2 });
  }

  get total() {
    const [priceState] = this.price.track();
    return this.state.qty * priceState.amount;
  }

  logTotal() {
    // Called outside render — .track() returns live values, no subscription registered.
    const [priceState] = this.price.track();
    console.log('total:', this.state.qty * priceState.amount);
  }
}
```

You can safely call `.track()` from methods without worrying about accidentally registering subscriptions at the wrong time.

### Dep getter transitivity

The second element of `.track()` — the `depProxy` — threads tracking through the dep's own getters. If the dep's getter reads `this.state.field`, that read is also recorded for the consumer:

```ts
import { Cubit } from '@blac/core';

class SrcBloc extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 5 });
  }
  get doubled() {
    return this.state.count * 2;
  }
}

class AggBloc extends Cubit<{ offset: number }> {
  private src = this.depend(SrcBloc);
  constructor() {
    super({ offset: 0 });
  }
  get computed() {
    const [, s] = this.src.track();
    // `s.doubled` calls the getter through the dep proxy. Inside `doubled`,
    // `this.state.count` is intercepted and records `count` as a tracked path
    // for the current consumer — so a SrcBloc emit on `count` wakes the consumer.
    return this.state.offset + s.doubled;
  }
}
```

This works transitively for deep chains: if `A.track(B)` and inside `B.computed` there is `B.track(C)`, a consumer reading `A.computed` is subscribed to C's channel too. Bumping C wakes the consumer.

### Conditional tracking

`.track()` is called during the render of the getter. If it runs conditionally, the subscription is added or dropped automatically after each render:

```ts
import { Cubit } from '@blac/core';

class FeatureFlagBloc extends Cubit<{ enabled: boolean }> {
  constructor() {
    super({ enabled: false });
  }
}

class LivePriceBloc extends Cubit<{ price: number }> {
  constructor() {
    super({ price: 0 });
  }
}

class ProductBloc extends Cubit<{ base: number }> {
  private flags = this.depend(FeatureFlagBloc);
  private livePrice = this.depend(LivePriceBloc);
  constructor() {
    super({ base: 10 });
  }

  get display() {
    const [flags] = this.flags.track(); // always tracked
    if (flags.enabled) {
      const [p] = this.livePrice.track(); // only tracked when feature is on
      return p.price;
    }
    return this.state.base;
  }
}
```

When `flags.enabled` becomes `false` on the next render, the `LivePriceBloc` subscription and ref are released. Turning it back on re-subscribes.

### Mutual dependencies and cycle safety

Two blocs can safely track each other (`A.track(B)` + `B.track(A)`). The reconciler detects re-entrant tracking within the same render and unions the paths rather than re-acquiring. No infinite loop occurs.

### `select` mode stays primary-only

When a consumer uses the `select` option on `useBloc`, `.track()` degrades to live values (same as outside-render). The `select` callback runs against the primary bloc only. This is by design — `select` is a manual subscription that opts out of auto-tracking entirely.

## On-demand instance creation

Sometimes a dependency doesn't exist yet and needs to be created conditionally. Use `borrowSafe` to check and `acquire` to create on demand:

```ts twoslash
import { Cubit, borrowSafe, acquire } from '@blac/core';

class UserCubit extends Cubit<{ userId: string }, { userId: string }> {
  static key = (a: { userId: string }) => a.userId;
  constructor() {
    super({ userId: '' });
  }

  protected init(args: { userId: string }) {
    this.patch({ userId: args.userId });
  }

  setUserId = (id: string) => this.patch({ userId: id });
}

interface ChannelState {
  messages: string[];
}

interface MessageData {
  userId: string;
  text: string;
}

class ChannelCubit extends Cubit<ChannelState> {
  constructor() {
    super({ messages: [] });
  }

  private ensureUserCubit(userId: string) {
    const result = borrowSafe(UserCubit, { args: { userId } });
    if (!result.error) return; // already exists

    // Create on demand, keyed by userId (init seeds the state)
    acquire(UserCubit, { args: { userId } });
  }

  receiveMessage = (message: MessageData) => {
    this.ensureUserCubit(message.userId);
    this.update((s) => ({ messages: [...s.messages, message.text] }));
  };
}
```

:::tip
Use `borrowSafe` over `borrow` when the instance may not exist yet. `borrow` throws, while `borrowSafe` returns `{ error, instance }` so you can handle the missing case gracefully.
:::

## See also

- [Instance Management](/core/instance-management) — the registry, ref counting, and `ensure`/`borrow`/`acquire`
- [Inputs and identity](/guide/inputs) — how `args` and `static key` resolve the instance a `depend()` targets
- [Best Practices](/guide/best-practices) — when cross-bloc coupling is sound versus a smell
- [Glossary](/guide/glossary) — definitions for registry, `ensure`, `keepAlive`, and auto-tracking

---

# Configuration

> Per-class config with the @blac decorator (keepAlive, equality, key, excludeFromDevTools) and global config with configureBlac, including the circuit breakers that catch leaks and emit storms.

Source: /core/configuration/

There are two layers of configuration in BlaC, and it helps to keep them straight:

- **Per-class config** with the `@blac` decorator (or `blac()` function) — opt one bloc into special behavior: keep it alive, hide it from DevTools, override its equality check, or control how its instances are keyed.
- **Global config** with `configureBlac` — set app-wide defaults and tune the safety limits (circuit breakers) that catch leaks and runaway emits before they freeze the app.

This page covers both. If you just want one bloc to survive route changes, you want `@blac({ keepAlive: true })` below. If you want to swap the default equality check or raise a circuit-breaker limit, jump to [`configureBlac`](#global-config-configureblac).

## Per-class config: `@blac`

`BlacOptions` is a **union type** — you can specify exactly **one** option per `@blac` call. Each option sets a single static property on the class that the registry and React layer read at runtime.

```ts
import { blac, Cubit } from '@blac/core';

@blac({ keepAlive: true })
class AuthCubit extends Cubit<AuthState> {
  constructor() {
    super({ user: null });
  }
}
```

:::caution[One option per call]
Because `BlacOptions` is a union, this is a **type error** — you cannot combine options in a single call:

```ts
// Type error: object literal may only specify one of these members
@blac({ keepAlive: true, key: (args) => args.id })
class Bad extends Cubit<S> {}
```

To apply more than one, stack decorators (or chain function calls). Each call sets its own static property and returns the class:

```ts
@blac({ keepAlive: true })
@blac({ key: (args) => args.id })
class Good extends Cubit<S, { id: string }> {}
```

:::

### `{ keepAlive: true }`

Prevents the instance from being auto-disposed when its ref count reaches zero. The instance persists for the lifetime of the app (it can still be torn down explicitly via `clear()` or `release(..., forceDispose)`).

**Why:** By default, BlaC disposes an instance the moment the last consumer releases it — see [Instance Management](/core/instance-management). That is exactly what you want for screen-local state, but wrong for state that must outlive the components reading it.

```ts
@blac({ keepAlive: true })
class AuthCubit extends Cubit<AuthState> {
  constructor() {
    super({ user: null });
  }
}
```

**When to use:** global state that should survive route changes and component churn — authentication, user preferences, app-wide settings, a feature-flag cache.

### `{ excludeFromDevTools: true }`

Hides every instance of the class from DevTools inspection.

**Why:** the DevTools plugin subscribes to each tracked container. A container that emits at high frequency (an animation clock, a pointer-position store) would flood the DevTools panel and add overhead on every frame. Excluding it keeps the panel readable and avoids self-induced feedback when DevTools-related state changes.

```ts
@blac({ excludeFromDevTools: true })
class InternalTimerCubit extends Cubit<TimerState> {
  constructor() {
    super({ tick: 0 });
  }
}
```

**When to use:** high-frequency or purely internal state containers that would clutter DevTools. See [DevTools](/plugins/devtools) for how the plugin consumes this flag.

### `{ equality: EqualityFn }`

Overrides the global equality check for this one class. The function receives the previous and next state; **return `true` to treat them as equal and skip the emit**.

**Why:** `emit`/`update` short-circuit when the new state is considered equal to the old, which prevents needless re-renders and downstream work. The global default ([`shallowEqualState`](#defaults)) compares top-level keys with `Object.is`. If a specific bloc holds deeply nested state where a shallow check is too eager (or not eager enough), give it its own comparator.

```ts
import { blac, Cubit, type EqualityFn } from '@blac/core';

const deepEqual: EqualityFn = (prev, next) =>
  JSON.stringify(prev) === JSON.stringify(next);

@blac({ equality: deepEqual })
class FilterCubit extends Cubit<FilterState> {
  constructor() {
    super({ tags: [], range: { min: 0, max: 100 } });
  }
}
```

:::note[Equality applies to emit/update, not patch]
The configured equality function gates `emit` and `update` only. `patch` does its own per-key `Object.is` filtering and ignores this function — see [Cubit](/core/cubit) for the difference between the mutation methods.
:::

### `{ key: (args) => string }`

Overrides how the registry derives an instance key from `args`. The function receives the bloc's `args` and returns the key string: **distinct return values produce distinct instances; identical values share one instance.**

**Why:** by default, a bloc with `args` is keyed by a structural hash of the entire `args` object. That is usually right, but sometimes only part of `args` is identity-bearing. A `static key` lets you key on just the identifying field so that non-identity fields (display options, a callback flag) don't accidentally fork a brand-new instance every time they change.

```ts
// Two consumers passing { userId: 'u1', highlight: true/false }
// should share ONE instance keyed only by userId.
@blac({ key: (args: { userId: string }) => args.userId })
class UserCardCubit extends Cubit<
  UserState,
  { userId: string; highlight?: boolean }
> {
  constructor() {
    super({ user: null });
  }
}
```

The same key function can be set directly as a class static (`static key = (args) => …`) if you prefer not to use a decorator. The registry reads either form. See [Passing Inputs](/guide/inputs) for the full identity model, and [Instance Management](/core/instance-management) for how keys drive sharing and disposal.

## Without decorators

If you're not using TypeScript decorators, call `blac` as a regular function. The decorator and function forms are identical — the decorator is just sugar for calling the returned wrapper on your class.

```ts
class AuthCubit extends Cubit<AuthState> {
  constructor() {
    super({ user: null });
  }
}

blac({ keepAlive: true })(AuthCubit);
```

:::note[Decorator setup]
The decorator form (`@blac({ … })`) requires decorator support in your toolchain — `experimentalDecorators` in `tsconfig.json` for the TypeScript-style decorators, or a build that understands TC39 decorators. If you hit a decorator-syntax error, switch to the function form above; it needs no special configuration.
:::

## Global config: `configureBlac`

`configureBlac` sets app-wide defaults. Call it **once, early** (before any blocs are acquired) — typically at your app's entry point. It shallow-merges the partial config into the current globals, so you only pass the keys you want to change.

```ts twoslash
import { configureBlac } from '@blac/core';

configureBlac({
  maxInstancesPerType: 5000,
  maxEmitsPerSecond: 240, // allow 4x/frame for a 60fps animation bloc
});
```

The config object has four keys: the default `equality` function and three **circuit breakers**.

### Circuit breakers

Circuit breakers are guardrails for the two failure modes that quietly destroy a BlaC app: leaks (instances or refs that are created but never disposed) and emit storms (a tight loop pushing high-frequency data through state). They cost nothing on the happy path and turn a silent freeze into a loud, actionable error.

| Option                | Guards against                                                                                                                                                                                    | Behavior when exceeded                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `maxInstancesPerType` | Too many **live instances** of one class — almost always an unstable instance key (a fresh object/array passed as `args` every render, or a missing `static key`) leaking one instance per render | `acquire` **throws**                                                             |
| `maxRefsPerInstance`  | Too many **distinct refs** on one instance — consumer cleanup (e.g. a `useBloc` unmount `release`) never firing, so refs pile up without bound                                                    | `acquire` **throws**                                                             |
| `maxEmitsPerSecond`   | An **emit storm** — a tight loop (RAF/animation, or an effect emitting on every commit) pushing high-frequency changes that saturate subscribers, plugins, and the main thread                    | Dev-only `console.warn` once per instance; **never throws**; no-op in production |

A few details that matter when tuning these:

- `maxInstancesPerType` throws when the live-instance count for a class **reaches** the limit (`>=`). `maxRefsPerInstance` throws when an instance's distinct-ref count **exceeds** the limit (`>`).
- `maxEmitsPerSecond` counts only **real** state changes (emits that actually changed state, after equality filtering) in a rolling one-second window, and warns at most once per instance. It is a heuristic — high-frequency state is occasionally legitimate, so it never blocks you.
- **Disable any breaker** by setting it to `Infinity` or any non-positive value (`0`, `-1`).

:::caution[A thrown breaker is a symptom, not the bug]
If `acquire` throws an instance- or ref-limit error, raising the limit usually just delays the freeze. The real cause is almost always an unstable key or a missing `release`. Stabilize the `args` / add a `static key` ([Passing Inputs](/guide/inputs)), or fix the missing cleanup ([Instance Management](/core/instance-management)), before reaching for a higher limit.
:::

### `equality` (global default)

The global equality function applied to every bloc that doesn't declare its own via [`@blac({ equality })`](#equality-equalityfn). The exported default, `shallowEqualState`, short-circuits on `Object.is`, returns `false` for non-objects/`null`, and otherwise compares top-level keys with `Object.is`. Swap it to change the default skip behavior for the whole app:

```ts twoslash
import { configureBlac, shallowEqualState } from '@blac/core';

// Treat any two states as different unless referentially identical
configureBlac({ equality: (a, b) => Object.is(a, b) });
```

### Defaults

| Option                | Type         | Default             | What it does                                                                      |
| --------------------- | ------------ | ------------------- | --------------------------------------------------------------------------------- |
| `equality`            | `EqualityFn` | `shallowEqualState` | App-wide default equality for `emit`/`update`; return `true` to skip the emit     |
| `maxInstancesPerType` | `number`     | `1000`              | Max live instances per class before `acquire` throws                              |
| `maxRefsPerInstance`  | `number`     | `1000`              | Max distinct refs per instance before `acquire` throws                            |
| `maxEmitsPerSecond`   | `number`     | `100`               | Dev-only soft limit; real emits/sec per instance before a one-time `console.warn` |

<details>
<summary>Reading the current config (advanced)</summary>

`getBlacConfig()` returns the live config object and `resetBlacConfig()` restores defaults. Both are marked `@internal` — `resetBlacConfig()` is handy in test teardown to undo a `configureBlac` from a previous test, but neither belongs in application code.

</details>

## See also

- [Instance Management](/core/instance-management) — how `keepAlive`, ref counting, and instance keys drive sharing and disposal
- [Passing Inputs](/guide/inputs) — `args`, `static key`, and the full instance-identity model
- [Cubit](/core/cubit) — `emit` vs `update` vs `patch`, and where equality applies
- [DevTools](/plugins/devtools) — how `excludeFromDevTools` is consumed

---

# Cubit

> A Cubit is the state container you subclass for almost everything in BlaC — typed state, emit/update/patch mutations, derived getters, and the args/deps lifecycle.

Source: /core/cubit/

A Cubit is a state container that holds a typed state value and exposes methods to change it. It is the class you subclass for almost everything in BlaC. Every signature on this page is quoted from the `@blac/core` source.

```ts
class Cubit<
  S extends object = any,
  Args = void,
  Deps extends object = Record<string, never>,
> extends StateContainer<S, Args, Deps> {}
```

| Type parameter | Default                 | Description                                                                                                                    |
| -------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `S`            | `any`                   | The state shape. Must be an object type (`S extends object`); primitives like `number` or `string` are not supported as state. |
| `Args`         | `void`                  | Serializable construction data delivered to `init(args)`. See [Args](#args-typed-construction-data).                           |
| `Deps`         | `Record<string, never>` | Non-serializable handles injected per consumer and read via `this.deps`. See [Deps](#deps-non-serializable-handles).           |

`Cubit` adds nothing structurally over `StateContainer` — it exists as a real class so `instance instanceof Cubit` works and so you have one obvious thing to extend.

## Why a class? (and why "Cubit", not "Bloc")

BlaC has exactly two base types: `StateContainer` (the abstract engine) and `Cubit` (the concrete class you extend). There is **no `Bloc` class** — if you are coming from `flutter_bloc`, the closest equivalent is `Cubit`. We use the name "bloc" colloquially to mean "any state-container instance," but the only thing you ever extend is `Cubit`. See the [glossary](/guide/glossary) for the full StateContainer / Cubit / bloc / instance hierarchy.

The state lives in a **class** for three concrete reasons:

- **State and the logic that changes it live together.** Methods like `addItem` sit next to the state they mutate, so an action is a method call, not a reducer plus an action-type constant plus a dispatch.
- **Derived values are just getters.** A `get total()` is computed on read and tracked automatically — no selector library, no memo wiring (see [Getters](#getters-derived-state)).
- **Instances have identity and a lifecycle.** The registry can create, key, ref-count, and dispose instances. That is what makes shared-vs-scoped state, `args`, and `deps` possible (see [Instance Management](/core/instance-management)).

For the deeper rationale (why proxy tracking over selectors, why microtask batching, how this compares to Redux/Zustand/MobX), see the [Mental Model](/guide/mental-model).

## Constructor

Define your state type as a generic parameter and pass the initial state to `super()`.

```ts
constructor(initialState: S, options?: StructuralContainerOptions)
```

| Parameter      | Type                         | Required | Description                                                                                      |
| -------------- | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `initialState` | `S`                          | yes      | The starting state. Must be an object.                                                           |
| `options`      | `StructuralContainerOptions` | no       | Low-level container options (custom per-path equality, skeleton hints). Most subclasses omit it. |

**Returns:** a new instance. The registry always builds instances zero-arg, so your subclass constructor takes no arguments — it only calls `super(initialState)`.

**Behavior.** Runs before `init(args)`. Use it solely to set the initial state; args-derived setup belongs in [`init`](#init-args).

```ts twoslash
import { Cubit } from '@blac/core';

interface TodoState {
  items: string[];
  filter: 'all' | 'active' | 'done';
}

class TodoCubit extends Cubit<TodoState> {
  constructor() {
    super({ items: [], filter: 'all' });
  }

  addItem = (text: string) => {
    this.update((s) => ({ ...s, items: [...s.items, text] }));
  };

  setFilter = (filter: TodoState['filter']) => {
    this.patch({ filter });
  };
}
```

:::tip[Why arrow-function fields for methods?]
Notice `addItem` and `setFilter` are defined as arrow-function class fields, not regular methods. This binds `this` to the instance, so the method keeps working when passed as a callback — `onClick={cubit.addItem}` or destructured `const { addItem } = cubit`. A regular method would lose its `this` in those cases. Use arrow-function fields for any method you intend to pass around; getters and internal helpers can stay regular methods.
:::

## Mutation methods

State in BlaC is **immutable from the outside**: you never assign to `this.state.x`. Instead you hand the container a _new_ state and it diffs the change, marks which paths moved, and wakes only the consumers that read those paths. The three methods below are three ways to produce that next state.

:::note[Why immutable?]
The diffing that powers smart re-renders (see [Dependency Tracking](/react/dependency-tracking)) needs a previous value and a next value to compare. Mutating in place would leave nothing to compare against, so a mutation would either re-render everything or nothing. Producing a new value on every change is what lets BlaC wake exactly the right consumers.
:::

### `emit(next)`

Replace the entire state. Use when you have the full new state ready.

```ts
emit(next: S): void
```

| Parameter | Type | Required | Description                                                                           |
| --------- | ---- | -------- | ------------------------------------------------------------------------------------- |
| `next`    | `S`  | yes      | The complete new state. Replaces the current state wholesale — it does **not** merge. |

**Returns:** `void`.

**Behavior.** `emit` is a no-op when the next state is equal to the current one: it short-circuits if `prev === next` by reference, or if the configured equality function (default: shallow per-key `Object.is`) reports them equal. So emitting an object that happens to match the current state will not wake any consumers. Equality is configurable per class via `blac({ equality })` and globally via `configureBlac` — see [Configuration](/core/configuration).

```ts twoslash
import { Cubit } from '@blac/core';

interface CounterState {
  count: number;
  label: string;
}

class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0, label: 'start' });
  }

  reset = () => {
    this.emit({ count: 0, label: 'reset' }); // full replacement
  };
}
```

:::danger[Common mistake: emit with a partial object]
`emit` _replaces_ the whole state — it does not merge. Passing a partial object silently drops every field you left out. If you only mean to change some fields, use `patch`, or read-and-spread with `update`. See [Troubleshooting](#emit-silently-drops-fields).
:::

### `update(fn)`

Derive new state from the current state. Use when you need to read the current state to compute the next one.

```ts
update(fn: (state: S) => S): void
```

| Parameter | Type              | Required | Description                                                                  |
| --------- | ----------------- | -------- | ---------------------------------------------------------------------------- |
| `fn`      | `(state: S) => S` | yes      | A reducer receiving the current state and returning the complete next state. |

**Returns:** `void`.

**Behavior.** `update` is sugar over `emit`: it calls `this.emit(fn(currentState))`, so it inherits `emit`'s equality short-circuit. Your `fn` must return the **full** next state — the same "no merge" rule as `emit` applies, so spread the existing state when you only change a few fields.

```ts twoslash
import { Cubit } from '@blac/core';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }

  increment = () => {
    this.update((current) => ({ ...current, count: current.count + 1 }));
  };
}
```

### `patch(partial)`

Deep-merge partial changes into the current state. Use when you want to update some fields without touching others.

```ts
patch(partial: DeepPartial<S>): void
```

| Parameter | Type             | Required | Description                                                                                                                                                               |
| --------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `partial` | `DeepPartial<S>` | yes      | The subtree to merge. Nested objects can be patched without spreading the full structure; arrays, `Date`, `Map`, `Set`, and class instances are treated as atomic leaves. |

**Returns:** `void`.

**Behavior.** `patch` deep-merges along plain-object branches and value-filters the result: a path is marked dirty only if its value actually changed. It skips the update entirely if all provided top-level values are already `Object.is`-equal to the current state (a shallow pre-spread no-op check), and `deepMerge` also returns the previous state by reference on a deep no-op.

:::caution[patch ignores the equality function]
The per-class/global equality function applies to `emit` and `update` only. `patch` does its own per-key/per-path `Object.is` filtering instead, so a custom `equality` will not change how `patch` decides what counts as a change.
:::

```ts twoslash
import { Cubit } from '@blac/core';

interface ProfileState {
  loading: boolean;
  user: { profile: { name: string; age: number } };
}

class ProfileCubit extends Cubit<ProfileState> {
  constructor() {
    super({ loading: false, user: { profile: { name: '', age: 0 } } });
  }

  startLoad = () => {
    this.patch({ loading: true });
  };

  rename = (name: string) => {
    // Only updates user.profile.name — age and other fields are preserved
    this.patch({ user: { profile: { name } } });
  };
}
```

### Choosing a method

| Scenario                   | Method   |
| -------------------------- | -------- |
| Full state replacement     | `emit`   |
| Derived from current state | `update` |
| Update a few fields        | `patch`  |
| Toggle a boolean           | `update` |
| Reset to initial state     | `emit`   |

## Getters: derived state

Getters are how you model **derived state** — values computed from other state rather than stored. Prefer a getter over storing a computed field: a stored `total` can drift out of sync with `items`, but a `get total()` is recomputed on every read and can never be stale.

A getter has no signature fence of its own — it is plain TypeScript on your subclass. In React render, it participates in auto-tracking:

:::tip[Getters auto-track in render]
Reading a getter from the `bloc` returned by `useBloc` (`bloc.total`) records the `this.state` paths the getter touches. Name the getter in `select` only when the getter's return value should be the explicit re-render boundary: `useBloc(CartCubit, { select: (state, bloc) => [bloc.total] })`. See [Dependency Tracking](/react/dependency-tracking).
:::

```ts twoslash
import { Cubit } from '@blac/core';

interface CartItem {
  price: number;
}

class CartCubit extends Cubit<{ items: CartItem[] }> {
  constructor() {
    super({ items: [] });
  }

  get total() {
    return this.state.items.reduce((sum, item) => sum + item.price, 0);
  }

  get isEmpty() {
    return this.state.items.length === 0;
  }

  addItem = (item: CartItem) => {
    this.update((s) => ({ items: [...s.items, item] }));
  };
}
```

```tsx
function CartSummary() {
  const [, cart] = useBloc(CartCubit);
  // re-renders when items change because the getter reads this.state.items
  return <span>Total: ${cart.total}</span>;
}
```

## Lifecycle, args, and deps

A Cubit instance moves through a fixed sequence, and the input hooks slot into specific points:

1. **Construct** — `new Type()` runs your constructor, which calls `super(initialState)`. The constructor takes no arguments; the registry always builds instances zero-arg.
2. **`init(args)`** — called **once**, synchronously, after construction and before any consumer reads the first snapshot. This is where args-derived setup belongs.
3. **`onDepsChanged(next, prev)`** — called whenever the merged per-consumer `deps` view changes (and once more on dispose, with everything cleared).
4. **Mutations** — `emit` / `update` / `patch` run as your methods are called.
5. **Dispose** — when the last consumer releases the instance (unless `keepAlive`); fires the `dispose` system event.

Steps 2 and 3 are the two input lanes: **args** for serializable identity data, **deps** for live non-serializable handles. The rest of this section covers each.

### `init(args)`

Seed args-derived state or kick off loads, once per instance, before the first snapshot.

```ts
protected init(args: Args): void
```

| Parameter | Type   | Required | Description                                                                                             |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `args`    | `Args` | yes      | The args passed at acquire time (`useBloc(Type, { args })`). `void` when no `Args` generic is declared. |

**Returns:** `void`.

**Behavior.** A protected lifecycle method — not callable from outside the class. The framework calls it **once per instance**, synchronously after `new Type()` and before the first state snapshot is read. It replaces the old `setConfig`/`setProps` patterns. When `useBloc` is called with `{ args }`, those args are required at the call site (type error if omitted when `Args != void`), used to derive the instance identity (different args ⇒ different instance), and available synchronously in `init` before any consumer sees state. See [Passing Inputs](/guide/inputs) for the full args/identity model.

```ts twoslash
import { Cubit } from '@blac/core';

interface UserCardState {
  name: string;
  loading: boolean;
}

class UserCardCubit extends Cubit<UserCardState, { userId: string }> {
  constructor() {
    super({ name: '', loading: false });
  }

  // Constructor stays zero-arg. The framework calls init(args) before first snapshot.
  protected init(args: { userId: string }) {
    this.patch({ loading: true });
    void this.loadUser(args.userId);
  }

  private async loadUser(_id: string) {
    /* ...fetch... */
  }
}
```

### `static key`: explicit identity declaration

By default, instance identity is the structural hash of all args. Override with a static property on the class to control exactly which args distinguish one instance from another:

```ts
static key: (args: Args) => string
```

**Behavior.** A function `(args: Args) => string` declared once on the class, not at every call site. When absent, BlaC hashes the full args object. Args not referenced by `key` ride along as config but do **not** fork instances.

```ts twoslash
import { Cubit } from '@blac/core';

interface DocState {
  title: string;
}

class DocumentCubit extends Cubit<
  DocState,
  { docId: string; readonly: boolean }
> {
  constructor() {
    super({ title: '' });
  }

  static key = (args: DocumentCubit['args']) => args?.docId ?? '';
  // `readonly` rides along as config but does NOT fork instances
}
```

### Deps: non-serializable handles

Declare a `Deps` type as the third generic parameter to receive non-serializable values (refs, callbacks, controller instances) that can't go in `args`. Deps are read lazily via `this.deps.x` and may be `undefined` — always guard.

```ts
get deps(): Readonly<Deps>
```

**Returns:** a `Readonly<Deps>` view — the union of every consumer's contributed slice.

**Key properties of deps:**

- **Never key identity** — different refs don't fork the instance.
- **Per-consumer merged** — each `useBloc` call contributes its own slice; the bloc sees the union (last writer wins on key collisions).
- **Live** — updated after each commit; may change over time. May legitimately be `undefined`, so always optional-chain.

```ts twoslash
import { Cubit } from '@blac/core';

interface UploadState {
  progress: number;
}

interface InputRef {
  current?: { click?: () => void };
}

class FileUploadCubit extends Cubit<
  UploadState,
  { endpoint: string }, // Args
  { inputRef?: InputRef } // Deps
> {
  private endpoint = '';

  constructor() {
    super({ progress: 0 });
  }

  protected init(args: { endpoint: string }) {
    this.endpoint = args.endpoint;
  }

  openPicker() {
    this.deps.inputRef?.current?.click?.(); // lazy read, may be undefined
  }
}
```

### `onDepsChanged(next, prev)`

For handles that require initialization when they arrive (a canvas element, a rich-text-editor controller), implement `onDepsChanged`. It fires after each deps merge with the new and previous combined views.

```ts
protected onDepsChanged(next: Readonly<Deps>, prev: Readonly<Deps>): void
```

| Parameter | Type             | Required | Description                                                                   |
| --------- | ---------------- | -------- | ----------------------------------------------------------------------------- |
| `next`    | `Readonly<Deps>` | yes      | The merged deps view after this reconcile.                                    |
| `prev`    | `Readonly<Deps>` | yes      | The merged view before it. Compare the two to detect arrivals and departures. |

**Returns:** `void`.

**Behavior.** Optional — blocs that don't declare it just read `this.deps.x` lazily. When declared, it gives the bloc clean acquire/release edges without any consumer-side cleanup wiring. It also fires once on dispose with every key cleared (so `next.x` is `undefined`), giving you a teardown edge.

```ts twoslash
import { Cubit } from '@blac/core';

interface RenderState {
  ready: boolean;
}

interface RteController {
  destroy(): void;
}

class CanvasRendererCubit extends Cubit<
  RenderState,
  { sceneId: string },
  { canvas?: HTMLCanvasElement; controller?: RteController }
> {
  constructor() {
    super({ ready: false });
  }

  onDepsChanged(next: this['deps'], prev: this['deps']) {
    if (next.canvas && next.canvas !== prev.canvas) {
      this.initRenderer(next.canvas);
    }
    if (!next.canvas && prev.canvas) {
      this.disposeRenderer();
    }
    if (next.controller !== prev.controller) {
      this.bindController(next.controller);
    }
  }

  private initRenderer(_c: HTMLCanvasElement) {}
  private disposeRenderer() {}
  private bindController(_c?: RteController) {}
}
```

:::danger[Common mistakes with args and deps]

- **Non-serializable value in `args`.** Args are hashed to derive instance identity; a function, ref, or class instance in `args` either throws (functions) or produces a fresh hash every render, spawning a new instance each time. Put non-serializable handles in `deps` instead. See [Troubleshooting](#a-new-instance-is-created-on-every-render).
- **Two consumers writing the same `deps` key.** Deps are merged per consumer into one view. If two `useBloc` call sites both supply `deps.controller`, the bloc sees one of them (last writer for that key) — decide a single owner.
- **Reading `this.deps.x` without guarding.** A dep may legitimately be `undefined` (no consumer has supplied it yet, or it unmounted). Always use optional chaining, as in `this.deps.inputRef?.current`.

See [Passing Inputs](/guide/inputs) for the full identity/merge model and [Best Practices](/guide/best-practices) for the judgment on which lane to reach for.
:::

## `depend(Type)`

Declare a cross-bloc dependency. See [Bloc Communication](/core/bloc-communication) for the full pattern.

```ts
protected depend<T extends StateContainerConstructor>(
  Type: T,
  defaultArgs?: ExtractArgs<T>,
): DepHandle<T>
```

| Parameter     | Type                                  | Required | Description                                                                                         |
| ------------- | ------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `Type`        | `T extends StateContainerConstructor` | yes      | The state-container class to depend on.                                                             |
| `defaultArgs` | `ExtractArgs<T>`                      | no       | Args identifying which keyed instance to resolve when an accessor is called without its own `args`. |

**Returns:** a `DepHandle<T>` with two accessors — `handle.untracked()` resolves the dep against the registry lazily on each call (`this.user.untracked()`), and `handle.track()` does the same _plus_ subscribes the reading React consumer. Both take an optional `{ args }` to override `defaultArgs` per call. See [Auto-tracking with `.track()`](/core/bloc-communication#auto-tracking-with-track).

**Behavior.** Records the dependency, then returns the handle. Resolving on every call keeps the surface immune to dep-instance churn. Note: `.untracked()` does **not** auto-resubscribe to the dep's channel — consumers that need reactive updates use `.track()` (or subscribe explicitly via `useBloc`'s tracker). A naive always-on auto-bridge would cycle on mutual deps, which is why tracking is opt-in.

```ts twoslash
import { Cubit } from '@blac/core';

class AuthCubit extends Cubit<{ userId: string | null }> {
  constructor() {
    super({ userId: null });
  }
}

class ProfileCubit extends Cubit<{ name: string }> {
  private auth = this.depend(AuthCubit);

  constructor() {
    super({ name: '' });
  }

  get currentUserId() {
    return this.auth.untracked().state.userId; // lazy resolve
  }
}
```

## Protected APIs

These are available inside your Cubit class but not from the outside:

- `this.state` — read the current state.
- [`this.init(args)`](#init-args) — lifecycle called once before first snapshot (override when `Args` is declared).
- [`this.onDepsChanged(next, prev)`](#ondepschanged-next-prev) — lifecycle called after each `deps` merge (override when `Deps` is declared).
- `this.onSystemEvent(event, handler)` — listen to lifecycle events (see [System Events](/core/system-events)).
- [`this.depend(OtherClass)`](#depend-type) — declare a dependency on another state container (see [Bloc Communication](/core/bloc-communication)).

## Public properties

| Property                     | Type               | Description                                                                                                               |
| ---------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `state`                      | `Readonly<S>`      | Current state value                                                                                                       |
| `$blac`                      | `BlacMeta<S>`      | Identity and lifecycle metadata. See the table below.                                                                     |
| `$blac.name`                 | `string`           | Display name (defaults to class name)                                                                                     |
| `$blac.id`                   | `string`           | Unique instance identifier                                                                                                |
| `$blac.createdAt`            | `number`           | Creation timestamp                                                                                                        |
| `$blac.disposed`             | `boolean`          | Whether the instance has been disposed                                                                                    |
| `$blac.hydration`            | `BlacHydration<S>` | Hydration lifecycle object. See below.                                                                                    |
| `$blac.hydration.status`     | `HydrationStatus`  | Current hydration phase (`'idle'` \| `'hydrating'` \| `'hydrated'` \| `'error'`); see [Persistence](/plugins/persistence) |
| `$blac.hydration.isHydrated` | `boolean`          | Shorthand: `status === 'hydrated'`                                                                                        |
| `$blac.hydration.wait()`     | `Promise<void>`    | Resolves once hydration settles; see [Persistence](/plugins/persistence)                                                  |

## Async methods

Cubits handle async operations naturally. Model loading/error state explicitly and guard against stale responses:

```ts twoslash
import { Cubit } from '@blac/core';

interface Article {
  id: string;
}

declare const api: { fetchArticles(category: string): Promise<Article[]> };

interface ArticleState {
  articles: Article[];
  status: 'idle' | 'loading' | 'error' | 'success';
  error: string | null;
}

class ArticleCubit extends Cubit<ArticleState> {
  private requestId = 0;

  constructor() {
    super({ articles: [], status: 'idle', error: null });
  }

  load = async (category: string) => {
    const id = ++this.requestId;
    this.patch({ status: 'loading', error: null });

    try {
      const articles = await api.fetchArticles(category);
      if (id !== this.requestId) return; // stale response
      this.emit({ articles, status: 'success', error: null });
    } catch (e) {
      if (id !== this.requestId) return;
      this.patch({ status: 'error', error: String(e) });
    }
  };
}
```

The `requestId` pattern discards responses from superseded requests. Each new `load()` call increments the ID, and callbacks from previous calls see a mismatch and bail out.

:::tip[Form validation pattern]
Cubits work well for form state. Use `patch` for field updates and getters for validation:

```ts twoslash
import { Cubit } from '@blac/core';

class FormCubit extends Cubit<{ email: string; password: string }> {
  constructor() {
    super({ email: '', password: '' });
  }

  setEmail = (email: string) => this.patch({ email });
  setPassword = (password: string) => this.patch({ password });

  get errors() {
    const errors: Record<string, string> = {};
    if (!this.state.email.includes('@')) errors.email = 'Invalid email';
    if (this.state.password.length < 8) errors.password = 'Too short';
    return errors;
  }

  get isValid() {
    return Object.keys(this.errors).length === 0;
  }
}
```

:::

## See also

- [Mental Model](/guide/mental-model) — why class-based containers, proxy tracking, and microtask batching
- [Best Practices](/guide/best-practices) — how to scope blocs, model async, and choose args vs deps
- [Passing Inputs](/guide/inputs) — the full args / deps identity model
- [Glossary](/guide/glossary) — StateContainer vs Cubit vs bloc vs instance, and other terms

## Troubleshooting

For the full FAQ see [Troubleshooting](/guide/troubleshooting). Below are the Cubit-specific problems.

### `emit` silently drops fields

**Symptom:** After calling `emit`, some state fields are `undefined` even though you didn't intend to clear them.

**Cause:** `emit` **replaces** the entire state — it does not merge. Passing a partial object drops every field you omit.

**Fix:** Use `patch` for partial updates, or spread existing state in `update`:

```ts twoslash
import { Cubit } from '@blac/core';

class TodoCubit extends Cubit<{
  items: string[];
  filter: 'all' | 'done';
}> {
  constructor() {
    super({ items: [], filter: 'all' });
  }

  // state: { items: [...], filter: 'all' }
  bad = () => {
    // @ts-expect-error — items is required; emit replaces the whole state
    this.emit({ filter: 'done' }); // items would be undefined!
  };

  // Fix A — patch merges only the listed fields
  fixA = () => this.patch({ filter: 'done' });

  // Fix B — update reads current state first
  fixB = () => this.update((s) => ({ ...s, filter: 'done' }));
}
```

See [Mutation methods: choosing a method](#choosing-a-method) above.

### A new instance is created on every render

**Symptom:** DevTools shows a new bloc instance being created and destroyed on every render, or the circuit-breaker throws "max instances exceeded."

**Cause:** A non-serializable value (function, ref, class instance) is in `args`. Because `args` must be JSON-serializable, a fresh object reference each render produces a different hash and therefore a different instance key.

**Fix:** Move non-serializable values to the bloc's `Deps` lane — they never affect instance identity:

```tsx
// Non-serializable in args → new instance every render (throws in dev)
useBloc(UploadCubit, { args: { onComplete: () => {} } });

// Serializable identity in args, handle in deps
useBloc(UploadCubit, { args: { endpoint: '/upload' } });
// (wire the callback via deps — see Cubit Deps and Passing Inputs)
```

See [Deps: non-serializable handles](#deps-non-serializable-handles) and [Troubleshooting: instance identity](/guide/troubleshooting#instance-identity-too-many--too-few).

---

# Instance management

> The registry is a global singleton that manages the lifecycle of state container instances — creation, sharing, ref counting, and disposal via acquire, ensure, borrow, and release.

Source: /core/instance-management/

The registry is a global singleton that manages the lifecycle of state container instances. It handles creation, sharing, ref counting, and disposal. Every signature on this page is quoted from the `@blac/core` source.

## The mental model: a shared library with checkouts

Think of the registry as a **lending library** for bloc instances:

- Each `(class, instanceKey)` pair is one **book** on the shelf. Ask for the same pair twice and you get the same physical book — that is how two components share state without prop-drilling.
- A consumer that needs a book **checks it out** (`acquire`) and **returns it** (`release`) when done. Every checkout is a **reference** (a "ref").
- The library keeps a **count of who has each book checked out**. When the count drops to zero, the book is **discarded** (`dispose`) — its state is gone and any timers or subscriptions it set up are torn down.
- `keepAlive` marks a book as a permanent reference copy: it stays on the shelf even at zero checkouts.

Two consequences fall straight out of this model:

1. **Sharing is automatic.** The first `acquire` of a key creates the instance; every later `acquire` of the same key reuses it. You never wire instances together by hand.
2. **Cleanup is automatic — but only if every checkout is returned.** A missing `release` is like never returning a library book: the count never reaches zero, the instance never disposes, and its memory (and subscriptions) leak.

## How ref counting works

When you call `useBloc(CounterCubit)` in React:

1. The hook calls `acquire(CounterCubit)`, which either creates a new instance or returns the existing one.
2. The ref count increments (+1). Each consumer gets its own ref (a unique `refId`), so two components reading the same bloc count as two refs.
3. When the component unmounts, `release(CounterCubit)` decrements the ref count (-1).
4. At ref count zero, the instance is disposed (unless `keepAlive` is set).

This means shared instances are automatically cleaned up when no component needs them.

```text
acquire ───▶  ref count 1   (created, init() runs, 'created' fires)
acquire ───▶  ref count 2   (same instance reused — shared)
release ───▶  ref count 1   (still alive, one consumer remains)
release ───▶  ref count 0   ─┬─ keepAlive?  yes ─▶ stays alive
                             └─ keepAlive?  no  ─▶ dispose()
                                                  ├─ 'dispose' system event fires
                                                  ├─ subscriptions/handlers torn down
                                                  ├─ entry removed from registry
                                                  └─ ensure-created deps with 0 refs cascade-dispose
```

:::note[When does disposal actually happen?]
Disposal is **synchronous** with the `release` call that drops the count to zero — there is no idle delay or timer. The very next `acquire` of that key (e.g. a new component mounting) creates a **fresh** instance with fresh state. If you need state to persist across that gap, use [`keepAlive`](/core/configuration).
:::

## Registry functions

### `acquire(BlocClass, opts?)`

Create or return an existing instance, incrementing the ref count.

```ts
function acquire<T extends StateContainerConstructor>(
  BlocClass: T,
  opts?: { args?: ExtractArgs<T>; refId?: string },
): InstanceType<T>;
```

| Parameter    | Type                                  | Required | Description                                                                                    |
| ------------ | ------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `BlocClass`  | `T extends StateContainerConstructor` | yes      | The state-container class to acquire an instance of.                                           |
| `opts.args`  | `ExtractArgs<T>`                      | no       | Serializable construction data passed to `init(args)`. Derives the instance key.               |
| `opts.refId` | `string`                              | no       | Caller-supplied ref identifier. Used by `useBloc` to pair with `release`. Rarely set manually. |

**Returns:** `InstanceType<T>` — the live instance (newly created or existing).

**Behavior.** The instance key is derived from `opts.args` (`static key` if declared, else the structural hash, else `'default'`). If no instance exists for the resolved key, `acquire` creates one, calls `init(args)`, and fires the internal `'created'` event. If an instance already exists, it is returned as-is. The ref count is always incremented. **Every `acquire` must have a matching `release`** — a missing `release` is the canonical instance leak. In React, `useBloc` owns this pair; call `acquire` directly only in server-side or scripting contexts.

```ts twoslash
import { acquire, release } from '@blac/core';
import { Cubit } from '@blac/core';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  increment = () => this.update((s) => ({ count: s.count + 1 }));
}

// --- outside React ---
const counter = acquire(CounterCubit);
counter.increment();
console.log(counter.state.count); // => 1
release(CounterCubit); // must pair with acquire
```

### `ensure(BlocClass, opts?)`

Create or return an existing instance **without** taking a ref.

```ts
function ensure<T extends StateContainerConstructor>(
  BlocClass: T,
  opts?: { args?: ExtractArgs<T> },
): InstanceType<T>;
```

| Parameter   | Type                                  | Required | Description                                            |
| ----------- | ------------------------------------- | -------- | ------------------------------------------------------ |
| `BlocClass` | `T extends StateContainerConstructor` | yes      | The state-container class.                             |
| `opts.args` | `ExtractArgs<T>`                      | no       | Construction data for `init(args)` and key derivation. |

**Returns:** `InstanceType<T>` — the live instance.

**Behavior.** Like `acquire`, but takes **no ref** — the instance can be disposed by another caller while you hold the returned reference. Use `ensure` inside other cubits (via `depend()`) or in tooling that only needs the instance to exist without pinning its lifecycle. Because no ref is taken, no matching `release` is needed.

```ts twoslash
import { ensure } from '@blac/core';
import { Cubit } from '@blac/core';

class AuthCubit extends Cubit<{ userId: string | null }> {
  constructor() {
    super({ userId: null });
  }
}

// ensure creates AuthCubit if it's not alive yet, but does not keep it alive
const auth = ensure(AuthCubit);
console.log(auth.state.userId); // no release needed
```

### `borrow(BlocClass, opts?)`

Return an existing instance without taking a ref. Throws if the instance does not exist.

```ts
function borrow<T extends StateContainerConstructor>(
  BlocClass: T,
  opts?: { args?: ExtractArgs<T> },
): InstanceType<T>;
```

| Parameter   | Type                                  | Required | Description                                                     |
| ----------- | ------------------------------------- | -------- | --------------------------------------------------------------- |
| `BlocClass` | `T extends StateContainerConstructor` | yes      | The state-container class.                                      |
| `opts.args` | `ExtractArgs<T>`                      | no       | Args identifying the instance. Defaults to the `'default'` key. |

**Returns:** `InstanceType<T>` — the live instance.

**Behavior.** Does not create the instance if it is absent; throws an `Error` instead. Use `borrow` when the absence of an instance is a programming error — it makes the failure loud and immediate rather than silently returning `undefined`. No ref is taken, so no `release` is needed.

```ts twoslash
import { borrow } from '@blac/core';
import { Cubit } from '@blac/core';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
}

// Safe read-only access — no acquire/release pair needed
function readCount(): number {
  return borrow(CounterCubit).state.count;
}
```

### `borrowSafe(BlocClass, opts?)`

Return an existing instance without taking a ref. Returns an error object instead of throwing.

```ts
function borrowSafe<T extends StateContainerConstructor>(
  BlocClass: T,
  opts?: { args?: ExtractArgs<T> },
):
  | { error: Error; instance: null }
  | { error: null; instance: InstanceType<T> };
```

| Parameter   | Type                                  | Required | Description                                                     |
| ----------- | ------------------------------------- | -------- | --------------------------------------------------------------- |
| `BlocClass` | `T extends StateContainerConstructor` | yes      | The state-container class.                                      |
| `opts.args` | `ExtractArgs<T>`                      | no       | Args identifying the instance. Defaults to the `'default'` key. |

**Returns:** `{ error: null; instance: InstanceType<T> }` when the instance exists, or `{ error: Error; instance: null }` when it does not.

**Behavior.** Identical to `borrow` but returns a discriminated union instead of throwing. Prefer `borrowSafe` in code paths where absence is expected (e.g. optional integrations) and `borrow` where absence is always a bug.

```ts twoslash
import { borrowSafe } from '@blac/core';
import { Cubit } from '@blac/core';

class AuthCubit extends Cubit<{ userId: string | null }> {
  constructor() {
    super({ userId: null });
  }
}

const { error, instance } = borrowSafe(AuthCubit);
if (error) {
  console.log('Auth not initialized yet');
} else {
  console.log(instance.state.userId);
}
```

### `release(BlocClass, opts?)`

Decrement the ref count. Dispose the instance when count reaches zero.

```ts
function release<T extends StateContainerConstructor>(
  BlocClass: T,
  opts?: { args?: ExtractArgs<T>; refId?: string; forceDispose?: boolean },
): void;
```

| Parameter           | Type                                  | Required | Description                                                                   |
| ------------------- | ------------------------------------- | -------- | ----------------------------------------------------------------------------- |
| `BlocClass`         | `T extends StateContainerConstructor` | yes      | The state-container class.                                                    |
| `opts.args`         | `ExtractArgs<T>`                      | no       | The args used when `acquire` was called. **Must resolve to the same key.**    |
| `opts.refId`        | `string`                              | no       | The ref identifier passed to `acquire`. Rarely set manually.                  |
| `opts.forceDispose` | `boolean`                             | no       | When `true`, dispose immediately even if `keepAlive` is set. Default `false`. |

**Returns:** `void`.

**Behavior.** `release` is **idempotent for an already-dropped ref** — releasing more times than you acquired won't throw, it just no-ops once the count is gone. The `args` you release with **must resolve to the same key** you acquired with; a mismatch leaves the original ref dangling forever. At ref count zero, the instance is disposed synchronously (unless `keepAlive` is set or `forceDispose` is `false`).

```ts twoslash
import { acquire, release } from '@blac/core';
import { Cubit } from '@blac/core';

class SessionCubit extends Cubit<{ token: string | null }, { scope: string }> {
  static key = (a: { scope: string }) => a.scope;
  constructor() {
    super({ token: null });
  }
}

const session = acquire(SessionCubit, { args: { scope: 'main' } });
// ... use session ...
release(SessionCubit, { args: { scope: 'main' } }); // args must match acquire's
```

## Named instances

To manage distinct named instances, declare an `Args` shape and pass `args` to any registry function. The instance key is derived from those args — a `static key` if the class declares one, otherwise the structural hash of the args:

```ts twoslash
import { acquire, release } from '@blac/core';
import { Cubit } from '@blac/core';

class EditorCubit extends Cubit<{ content: string }, { docId: string }> {
  static key = (a: { docId: string }) => a.docId;
  constructor() {
    super({ content: '' });
  }
}

const editor1 = acquire(EditorCubit, { args: { docId: 'doc-42' } });
const editor2 = acquire(EditorCubit, { args: { docId: 'doc-99' } });

// These are different instances
const areDifferent = editor1 !== editor2; // true

release(EditorCubit, { args: { docId: 'doc-42' } });
release(EditorCubit, { args: { docId: 'doc-99' } });
```

In React, pass the same `args`:

```tsx
const [state] = useBloc(EditorCubit, { args: { docId: 'doc-42' } });
```

### Args derive identity

`args` are the **only** way to get distinct instances — the meaningful value keys the instance _and_ feeds `init(args)`, so you never pass the same id twice:

```tsx
// The meaningful value keys the instance AND feeds init(args)
const [s] = useBloc(UserCardCubit, { args: { userId } });
```

Identity precedence: own `args` (via `static key(args)`, else structural hash of `args`) > `<BlocProvider>` context args > `'default'`.

The resolved key is the registry's single source of truth — `acquire` and `release` both run their `args` through the same resolution, so a ref taken under a given args key is dropped under the same key. See [Passing Inputs](/guide/inputs) for the full model and [Configuration](/core/configuration#key-args-string) for `static key`.

## Querying the registry

```ts twoslash
import {
  hasInstance,
  getRefCount,
  getAll,
  forEach,
  getStats,
} from '@blac/core';
import { Cubit } from '@blac/core';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
}

const _a = hasInstance(CounterCubit); // boolean
const _b = getRefCount(CounterCubit); // number of distinct active refs
const _c = getAll(CounterCubit); // all instances of this class
forEach(CounterCubit, (_inst) => {}); // iterate instances
const _d = getStats(); // { registeredTypes, totalInstances, typeBreakdown }
```

## Cleanup

```ts twoslash
import { clear, clearAll } from '@blac/core';
import { Cubit } from '@blac/core';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
}

clear(CounterCubit); // dispose and remove all instances of this class
clearAll(); // dispose and remove everything
```

:::caution[`clear` / `clearAll` are teardown tools, not app code]
`clear` and `clearAll` dispose instances **regardless of ref count**, ignoring `keepAlive`. That is exactly what you want between tests to isolate the registry, but in running app code it will pull state out from under live components. Reach for them in test setup/teardown — see [Testing core logic](/testing/core) — not in feature code.
:::

## In React vs outside React

In React, `useBloc` handles `acquire` and `release` automatically. You rarely call registry functions directly.

Outside React (tests, scripts, server-side code), manage the lifecycle manually:

```ts twoslash
import { acquire, release } from '@blac/core';
import { Cubit } from '@blac/core';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  increment = () => this.update((s) => ({ count: s.count + 1 }));
}

const counter = acquire(CounterCubit);
counter.increment();
console.log(counter.state.count);
release(CounterCubit);
```

## See also

- [Configuration](/core/configuration) — `keepAlive`, `static key`, and the circuit breakers that catch leaks
- [Passing Inputs](/guide/inputs) — `args` and the full instance-identity model
- [System Events](/core/system-events) — the `dispose` event that fires when an instance is torn down
- [Testing core logic](/testing/core) — using `clear`/`clearAll` to isolate the registry between tests

## Troubleshooting

For the full FAQ see [Troubleshooting](/guide/troubleshooting). Below are the instance-management-specific problems.

### State unexpectedly resets on remount

**Symptom:** A component unmounts and remounts and finds the bloc in its initial state — any previous state is gone.

**Cause:** When the last consumer releases, the instance is disposed immediately (ref count 0 → dispose). The next consumer acquires a brand-new instance with fresh state.

**Fix:** If state must persist across unmounts, mark the class `keepAlive`:

```ts twoslash
import { blac, Cubit } from '@blac/core';

interface SessionState {
  token: string | null;
}

@blac({ keepAlive: true })
class SessionCubit extends Cubit<SessionState> {
  constructor() {
    super({ token: null });
  }
}
```

`keepAlive` instances are never auto-disposed at ref count 0 — tear them down explicitly with `release(Class, { forceDispose: true })` or `clear(Class)` in teardown. See [Configuration](/core/configuration#keepalive-true).

### Instance never disposed / memory leak

**Symptom:** DevTools shows an instance that should have been disposed is still alive, or ref count never returns to 0.

**Cause:** An `acquire` outside React has no matching `release`. Every call to `acquire` increments the ref count; without a matching `release` the count never reaches zero.

**Fix:** Pair every `acquire` with a `release`, ideally in a `try/finally`. If you only need to read without owning the lifecycle, use `borrow` or `ensure` — neither takes a ref:

```ts twoslash
import { acquire, borrow, release } from '@blac/core';
import { Cubit } from '@blac/core';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
}

// Leaks — no release
function readOnceBad() {
  const c = acquire(CounterCubit);
  return c.state.count;
  // BUG: ref count never drops to 0
}

// Fixed — borrow takes no ref
function readOnce() {
  return borrow(CounterCubit).state.count;
}
```

### Circuit breaker threw ("max instances" / "max refs")

**Symptom:** `acquire` throws with a message like "exceeded the maximum live instances" or "exceeded the maximum refs."

**Cause:** Almost always a leak — an unstable instance key (non-serializable `args`) spawning endless instances, or a missing `release` accumulating refs. The limit is not too low; the leak is real.

**Fix:** Find and fix the leak before raising the limit. Common causes: non-serializable values in `args` (fix: move to `deps`), `acquire` without `release` (fix: pair them), args that differ structurally each render (fix: normalise types). See [Configuration: circuit breakers](/core/configuration#circuit-breakers) and [Troubleshooting](/guide/troubleshooting#instance-identity-too-many--too-few).

---

# Plugin Authoring

> A plugin installs once, globally, and observes lifecycle events across every state container — the escape hatch for cross-cutting concerns like logging, DevTools, persistence, and analytics.

Source: /core/plugins/

Some behavior does not belong to any single bloc — logging every state change, mirroring state into DevTools, persisting to IndexedDB, sending analytics. Wiring that into each bloc by hand would scatter the same concern across your codebase and couple your domain logic to infrastructure.

A **plugin** is the escape hatch: it installs once, globally, and observes lifecycle events across _every_ state container in the registry. Write the cross-cutting concern once; it applies everywhere automatically.

:::note[Plugins vs system events — which do I reach for?]
[System events](/core/system-events) (`this.onSystemEvent(...)`) are for logic that belongs to **one bloc** ("when _this_ cart changes, recompute _this_ total"). Plugins are for behavior that applies **across all blocs** ("log every state change in the app"). If you find yourself adding the same `onSystemEvent` handler to many blocs, that is the signal to lift it into a plugin.
:::

## The BlacPlugin interface

A plugin is a plain object: a `name`, a `version`, and any subset of the optional hooks below. Implement only what you need — every hook is optional.

```ts twoslash
import { type BlacPlugin, type PathSet, ALL_PATHS } from '@blac/core';

const myPlugin: BlacPlugin = {
  name: 'my-plugin',
  version: '1.0.0',

  // Fires once when the plugin is installed.
  // ctx.container is undefined here — onInstall is global, not per-bloc.
  onInstall(ctx) {},

  // Fires once when the plugin is uninstalled. No context.
  onUninstall() {},

  // Fires when any state container is first created and acquired.
  // The new container is ctx.container.
  onCreated(ctx) {},

  // Fires once per microtask flush after any state change.
  // prev/next are the coalesced before/after states; paths is the
  // set of changed property paths (or ALL_PATHS for a full change).
  onStateChange(ctx, prev, next, paths: PathSet) {},

  // Fires when any state container is disposed.
  // The disposed container is ctx.container ($blac.disposed is already true).
  onDestroyed(ctx) {},

  // Fires on every hydration status transition of any container.
  onHydrationChange(ctx, status, previousStatus) {},
};
```

:::caution[The container is on `ctx`, not a separate parameter]
Every per-container hook receives the focal bloc as `ctx.container`, not as a second argument. There is no `instance` parameter. This is a common mistake when porting from older drafts — `onCreated(ctx, instance)` is wrong; use `ctx.container`.
:::

### Hook signatures (verbatim)

| Hook                | Signature                       | When it fires                                     |
| ------------------- | ------------------------------- | ------------------------------------------------- |
| `onInstall`         | `(ctx)`                         | Once at install. `ctx.container` is `undefined`.  |
| `onUninstall`       | `()`                            | Once at uninstall. No context.                    |
| `onCreated`         | `(ctx)`                         | Synchronously when a container is first acquired. |
| `onStateChange`     | `(ctx, prev, next, paths)`      | Once per microtask flush after a state change.    |
| `onDestroyed`       | `(ctx)`                         | Synchronously after a container is disposed.      |
| `onHydrationChange` | `(ctx, status, previousStatus)` | On each hydration status transition.              |

<details>
<summary>Internal devtools-only hooks</summary>

The interface also declares `onRefAcquired(ctx, refId)`, `onRefReleased(ctx, refId)`, and `onDepsChanged(ctx, previousDeps, currentDeps)`. These are marked `@internal` and exist to support the DevTools connector; they are not part of the stable plugin contract and may change. Avoid them in application plugins.

</details>

## Installing a plugin

`getPluginManager()` returns the singleton `PluginManager` bound to the global registry. Call it once, near app startup, to install your plugins.

```ts
import { getPluginManager } from '@blac/core';

getPluginManager().install(myPlugin, {
  enabled: true,
  environment: 'development', // 'development' | 'production' | 'test' | 'all'
});
```

| Config option | Default | Meaning                                                                                                                                              |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`     | `true`  | Set `false` to register the plugin but skip all hook dispatch.                                                                                       |
| `environment` | `'all'` | Active only when `process.env.NODE_ENV` matches (`'development'`, `'production'`, `'test'`) or `'all'`. A mismatch logs a skip and installs nothing. |

The `environment` gate is a runtime check against `NODE_ENV`, not tree-shaking. Use `'development'` for debug-only plugins (logging, DevTools) so they add zero overhead in production; use `'all'` for plugins you genuinely want everywhere, like persistence.

:::caution[Common mistakes]

- **`install` throws if a plugin with the same `name` is already installed.** Names are the unique key; pick a stable, unique `name`.
- **If `onInstall` throws, the plugin is rolled back** (removed) and the error rethrown — a failed install leaves nothing half-registered.
- **Forgetting `environment` means a debug plugin runs in production.** A noisy logging plugin left at the default `'all'` will log in prod. Gate it to `'development'`.
  :::

## Uninstalling

`uninstall` takes the plugin's **name string**, not the plugin object. It throws if no plugin with that name is installed.

```ts
getPluginManager().uninstall('my-plugin');
```

Other `PluginManager` methods: `getPlugin(name)`, `getAllPlugins()`, `hasPlugin(name)`, `clear()` (uninstall all), and `destroy()` (clear plus detach the registry lifecycle hooks).

## PluginContext

The `ctx` parameter (always first) carries the focal container plus safe, read-only access to registry data. A fresh `ctx` is built per dispatch — it is cheap and closes over the registry.

- **`ctx.container`** — the bloc this event is about (`StateContainer | undefined`). It is `undefined` only inside `onInstall`. For per-container hooks (`onCreated`, `onStateChange`, `onDestroyed`, `onHydrationChange`) it is the focal bloc. Use `ctx.container` to read `state`, `interner`, `$blac.id`, etc.

The methods below take an `instance` argument so a plugin can also reach blocs other than the focal one (e.g. via `queryInstances`):

| Method                                | Returns                                                                             |
| ------------------------------------- | ----------------------------------------------------------------------------------- |
| `getInstanceMetadata(instance)`       | `{ id, className, isDisposed, name, state, createdAt, args, hydrationStatus, ... }` |
| `getState(instance)`                  | Current state of the instance                                                       |
| `getHydrationStatus(instance)`        | Current `HydrationStatus` of the instance                                           |
| `startHydration(instance)`            | Begin hydration for the instance                                                    |
| `applyHydratedState(instance, state)` | Apply restored state during hydration                                               |
| `finishHydration(instance)`           | Mark hydration as complete                                                          |
| `failHydration(instance, error)`      | Mark hydration as failed                                                            |
| `waitForHydration(instance)`          | `Promise<void>` that resolves when hydration completes                              |
| `queryInstances(Type)`                | All instances of a given class                                                      |
| `getAllTypes()`                       | All registered state container classes                                              |
| `getStats()`                          | `{ registeredTypes, totalInstances, typeBreakdown }`                                |
| `getRefIds(instanceId)`               | Array of ref holder IDs for an instance                                             |

The five hydration methods — `startHydration`, `applyHydratedState`, `finishHydration`, `failHydration`, and `waitForHydration` — exist so a plugin can drive the [hydration lifecycle](/core/system-events) from the outside. The [Persistence plugin](/plugins/persistence) is their real-world consumer: it begins hydration, restores saved state, and finishes (or fails) hydration through exactly these methods.

## PathSet and the path interner

:::tip[You probably do not need this]
Most plugins act on the whole `next` state and ignore `paths` entirely. Reach for the interner only when you are building field-level tooling — structured logs or DevTools integrations that report _which_ property changed.
:::

`onStateChange` receives `paths: PathSet` as its fourth argument: a `Set<PathId>` of the property paths that changed in the flush — **or the `ALL_PATHS` sentinel** when the change spans every path (for example a full `emit` replacing the whole state, or a single-consumer container that skips path diffing). It is never `undefined`.

A `PathId` is an integer, not a string. Each BlaC class has its own **per-class `PathInterner`** that maps path strings (`"items"`, `"user.profile.name"`) to those integers. Interning to integers keeps the hot path (diffing and set intersection on every flush) cheap — comparing numbers beats comparing strings. To turn a `PathId` back into a readable string, call `interner.lookup(pathId)` on the **focal container's** interner, reachable via `ctx.container`:

```ts twoslash
import { type BlacPlugin, type PathSet, ALL_PATHS } from '@blac/core';

const pathLoggingPlugin: BlacPlugin = {
  name: 'path-logger',
  version: '1.0.0',

  onStateChange(ctx, prev, next, paths) {
    const container = ctx.container;
    if (!container) return;

    if (paths === ALL_PATHS) {
      console.log(`[${container.$blac.name}] changed: (all paths)`);
      return;
    }

    for (const pathId of paths) {
      const path = container.interner.lookup(pathId);
      console.log(`[${container.$blac.name}] changed: ${path}`);
    }
  },
};
```

:::caution[Always handle `ALL_PATHS` before iterating]
`paths` is a union of `Set<PathId>` and the `ALL_PATHS` symbol. Iterating the symbol with `for..of` throws. Check `paths === ALL_PATHS` first, every time. The interner lives on the container (`ctx.container.interner`), not on the metadata object returned by `getInstanceMetadata` — that metadata has no `interner` field.
:::

## A complete minimal plugin

Here is an end-to-end plugin you can install as-is. It logs creation and disposal, and reports each state change with its changed paths — a self-contained template you can adapt for analytics, audit logs, or telemetry.

```ts twoslash
import {
  getPluginManager,
  type BlacPlugin,
  type PathSet,
  ALL_PATHS,
} from '@blac/core';

const auditPlugin: BlacPlugin = {
  name: 'audit-log',
  version: '1.0.0',

  onCreated(ctx) {
    const c = ctx.container;
    if (c) console.log(`[audit] created ${c.$blac.name} (${c.$blac.id})`);
  },

  onStateChange(ctx, _prev, _next, paths) {
    const c = ctx.container;
    if (!c) return;

    const changed =
      paths === ALL_PATHS
        ? ['(all)']
        : [...paths].map((id) => c.interner.lookup(id));

    console.log(`[audit] ${c.$blac.name} changed:`, changed);
  },

  onDestroyed(ctx) {
    const c = ctx.container;
    if (c) console.log(`[audit] disposed ${c.$blac.name} (${c.$blac.id})`);
  },
};

// Install once at startup. Gate to development so it adds no prod overhead.
getPluginManager().install(auditPlugin, { environment: 'development' });
```

:::caution[Common mistakes]

- **Mutating state inside `onStateChange`.** Calling `ctx.container.emit(...)` (or `patch`/`update`) from this hook triggers another flush, which fires `onStateChange` again — an infinite loop. Plugins observe; they do not write back.
- **Skipping the `ALL_PATHS` check.** See the warning above — iterating the sentinel throws.
- **Leaving a debug plugin at `environment: 'all'`.** It will run (and log, and cost) in production. Gate noisy plugins to `'development'`.
  :::

<details>
<summary>Performance note: plugins defeat the single-consumer skip</summary>

To deliver `onStateChange` for every flush, the manager subscribes to each container's channel with `ALL_PATHS` interest. That subscription counts as a consumer, which disables the single-consumer fast path in the structural container (where `emit` would otherwise skip path diffing entirely). The trade-off is intentional — DevTools and persistence genuinely need every change — but it is why a plugin you do not need should stay uninstalled or `environment`-gated rather than installed-but-disabled.

</details>

## `onStateChange` is once-per-flush

`onStateChange` fires **once per microtask flush**, not once per individual `emit`/`patch`/`update` call. If a method calls `patch` three times synchronously, `onStateChange` receives a single call with the final state and the union of all changed paths. Two consequences:

- `prev` is snapshotted **once per flush** (the state before the first emit of that flush) and reused for every plugin, so the value a plugin sees is independent of install order.
- For true per-call granularity (rare), subscribe to the container's channel directly instead of using a plugin hook.

This batching mirrors `onSystemEvent('stateChanged')` inside a bloc — the same microtask-coalescing model, seen from the global side rather than the per-instance side. See [System Events](/core/system-events) for the per-instance view and the full rationale for why BlaC batches.

## Built-in plugins

These official plugins are themselves authored against the interface above — read their source as worked examples:

- [Logging](/plugins/logging) — console logging and monitoring
- [DevTools](/plugins/devtools) — Chrome DevTools integration
- [Persistence](/plugins/persistence) — IndexedDB state persistence (the real consumer of the hydration methods on `ctx`)

## See also

- [Plugin Overview](/plugins/overview) — the plugin catalog and where to start
- [System Events](/core/system-events) — per-instance lifecycle hooks and when to use them instead
- [Persistence](/plugins/persistence) — a complete plugin that drives the hydration API
- [Glossary](/guide/glossary) — definitions for plugin, hydration, interner, and `PathSet`

---

# channel.subscribe

> The lowest-level way to observe a bloc — register a callback on a container's channel that fires when a dirty region overlaps your declared interest. For plugins, devtools, and infrastructure.

Source: /core/subscribe/

The lowest-level way to observe a bloc. Every container owns a `channel` — a `DirtyChannel<PathSet>` from the DirtyTalk engine — and `channel.subscribe(interest, cb)` registers a callback that fires when the channel flushes a dirty region that overlaps your declared interest.

Almost no application code needs this. It exists for plugins, devtools, and infrastructure that must compose path-scoped subscriptions directly on a container. If you are inside a React component, use [`useBloc`](/react/use-bloc); if you are outside React, use [`watch`](/core/watch). `watch` is itself a thin wrapper around `channel.subscribe(() => ALL_PATHS, ...)`.

:::note[Where this sits in the stack]
`channel` is inherited from `StructuralContainer` (the structural layer under every `Cubit`). The same `subscribe` shape is also exposed one level up as a pass-through `container.subscribe(...)` (which internally delegates to `container.channel.subscribe(...)`). This page documents the channel method directly, because that is the surface plugins compose against.
:::

## Stability

`channel`, `ALL_PATHS`, and the `PathSet` type are **public** — `@blac/core` re-exports `ALL_PATHS` (value) and `PathSet` (type) specifically so plugins can compose channel subscriptions. The mechanism for minting a _specific_ `PathSet` (the `PathInterner` and its numeric `PathId`s) is **`@internal`**: it is not re-exported from `@blac/core` and its representation can change between releases. In practice that means the only stable, portable interest you can construct from outside the framework is `ALL_PATHS` (observe everything). Path-scoped interests are an internal optimization that `useBloc`'s render tracker builds for itself.

## Signature

```ts
// On the channel (DirtyChannel<PathSet>), from packages/dirtytalk-engine/src/dirty-channel.ts:58
subscribe(interest: () => Region, cb: (dirty: Region) => void): () => void
```

For a bloc's channel, `Region` is instantiated as `PathSet`:

```ts
// container.channel is DirtyChannel<PathSet>, so subscribe reads as:
subscribe(interest: () => PathSet, cb: (dirty: PathSet) => void): () => void
```

| Parameter  | Type                       | Description                                                                                                                                                                                                                                    |
| ---------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `interest` | `() => PathSet`            | A thunk returning the region this subscriber cares about. Re-evaluated lazily, once per flush per subscriber — **not** snapshotted at subscribe time. Skipped entirely on empty-dirty flushes. Return `ALL_PATHS` to be woken by every change. |
| `cb`       | `(dirty: PathSet) => void` | Invoked with the accumulated dirty region whenever it intersects `interest()`. The bloc's _new_ state is already applied when this runs — read `container.state` inside the callback.                                                          |
| returns    | `() => void`               | An idempotent unsubscribe closure. Safe to call more than once, and safe to call from inside the callback mid-flush.                                                                                                                           |

## The interest / PathSet shape

```ts
// packages/dirtytalk-structural/src/path-set.ts
const ALL_PATHS: unique symbol;
type AllPaths = typeof ALL_PATHS;
type PathSet = Set<PathId> | AllPaths;

// packages/dirtytalk-structural/src/types.ts
type PathId = number;
```

A `PathSet` is either:

- the **`ALL_PATHS`** sentinel — "every path", i.e. wake on any change; or
- a `Set<PathId>` of interned path ids — a specific set of fields.

`PathId`s are interned per container **class** by an internal `PathInterner`; you do not construct them by hand, and the interner is not part of the public `@blac/core` surface. Because of that, the portable interest from application/plugin code is `ALL_PATHS`. The `Set<PathId>` form is what `useBloc`'s render tracker assembles internally to get fine-grained re-renders — see [Tracking](/core/tracked).

## The callback contract

- **Coalesced, asynchronous.** The channel uses a microtask scheduler by default, so several synchronous `emit`/`patch`/`update` calls fold into a **single** flush. Your callback does not fire once per mutation; it fires once per flush, after the current tick. See [System Events](/core/system-events) for the batching model.
- **Interest is a thunk, re-run each flush.** The channel calls `interest()` lazily on every non-empty flush, then delivers only if `intersects(interest(), dirty)` is true. It is not captured once at subscribe time.
- **No immediate fire.** Unlike `watch`, `channel.subscribe` does **not** invoke the callback once on setup. It only runs on the next flush after a matching change. If you need the current value immediately, read `container.state` yourself.
- **Errors are collected, not swallowed silently.** A throw from your callback (or your interest thunk) is recorded; after all subscribers run, a single error re-throws as-is, and multiple throw as an `AggregateError`.

## Unsubscribe

`subscribe` returns an unsubscribe function. Calling it marks the subscriber dead and removes it from the channel. The closure is **idempotent** — calling it twice is a no-op — and is safe to call from inside the callback (e.g. for one-shot subscriptions). Forgetting to call it leaks the subscription for the life of the bloc.

```ts twoslash
import { Cubit, ALL_PATHS } from '@blac/core';
import { ensure } from '@blac/core';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  increment() {
    this.patch({ count: this.state.count + 1 });
  }
}

const counter = ensure(CounterCubit);

// Subscribe to ALL changes on this bloc's channel.
const unsubscribe = counter.channel.subscribe(
  () => ALL_PATHS, // interest thunk: re-run each flush
  (dirty) => {
    // `dirty` is the PathSet that changed; the new state is already applied.
    console.log('counter changed ->', counter.state.count);
  },
);

counter.increment();
counter.increment(); // both fold into ONE coalesced flush next microtask

// Later — tear down. Idempotent.
unsubscribe();
unsubscribe(); // safe no-op
```

:::caution[No JSX here]
This is the vanilla, outside-React surface. Do not reach for `channel.subscribe` inside a component — use [`useBloc`](/react/use-bloc), which builds a path-scoped interest for you and re-renders only on the fields you read.
:::

## Inside React vs outside React

`channel.subscribe` is the floor of a three-tier API. Pick the highest tier that fits:

| Where you are                                       | Use                          | What you get                                                             |
| --------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------ |
| Inside a React component                            | [`useBloc`](/react/use-bloc) | Auto-tracked, path-scoped re-renders; lifecycle tied to mount.           |
| Outside React (logging, sync, imperative UI, tests) | [`watch`](/core/watch)       | The bloc **instance**, fires once immediately, multi-bloc, `watch.STOP`. |
| Building a plugin / devtools / infra                | `channel.subscribe`          | Raw `PathSet` deltas, no instance sugar, no immediate fire.              |

In short: **inside React → `useBloc`; outside React → `watch`** for almost everything, and **`channel.subscribe`** only when you are composing on the channel itself. `watch` exists precisely so you rarely touch the channel directly — it is `channel.subscribe(() => ALL_PATHS, ...)` plus instance resolution, an immediate fire, and a `STOP` sentinel.

## See also

- [watch](/core/watch) — the outside-React wrapper around this method; prefer it unless you need raw channel access
- [Tracking](/core/tracked) — how `useBloc` builds a fine-grained `Set<PathId>` interest so it re-renders only on the fields you read
- [System Events](/core/system-events) — the microtask flush and coalescing model behind every channel callback
- [DirtyTalk engine: DirtyChannel](/dirtytalk/engine/api-reference#dirtychannel-region) — the underlying channel, its flush semantics, and the `Space`/`Scheduler` it is built on

---

# System events

> Lifecycle hooks inside a single state container instance — react to its own state changes, disposal, or hydration status via onSystemEvent, without external wiring.

Source: /core/system-events/

System events are lifecycle hooks **inside a single state container instance**. Use them to react to that instance's own state changes, disposal, or hydration status — from within the class, without any external wiring. Every signature on this page is quoted from the `@blac/core` source.

**Why they exist:** sometimes a bloc needs to do something in response to its own lifecycle — tear down a timer when it's disposed, kick off a derived computation when its state settles, log a transition. `onSystemEvent` is the in-class hook for exactly that. It is the per-instance counterpart to [plugins](/core/plugins), which observe the same kinds of events but across _every_ instance (see [the comparison below](#system-events-vs-plugins)).

## Available events

```ts twoslash
type SystemEvent = 'stateChanged' | 'dispose' | 'hydrationChanged';
```

## `onSystemEvent(event, handler)`

Register a handler for a lifecycle event on this instance.

```ts
protected onSystemEvent = <E extends SystemEvent>(
  event: E,
  handler: SystemEventHandler<S, E>,
): (() => void)
```

| Parameter | Type                       | Required | Description                                                                            |
| --------- | -------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `event`   | `SystemEvent`              | yes      | The event name: `'stateChanged'`, `'dispose'`, or `'hydrationChanged'`.                |
| `handler` | `SystemEventHandler<S, E>` | yes      | Callback receiving the event payload. The payload shape differs per event (see below). |

**Returns:** `() => void` — an unsubscribe function. Call it to remove the handler before the instance is disposed. For handlers that should live as long as the instance, you can discard the return value — all handlers are torn down automatically on `dispose`.

**Behavior.** A protected method — only callable inside the class. Handlers added for the same event are fired in registration order. Registering in the constructor (or in `init`) ensures handlers are wired before the instance starts emitting. `dispose` tears down all registered handlers automatically, so no manual cleanup is needed for instance-lifetime handlers.

:::tip[Where to register handlers]
Register handlers in the constructor (or in `init`) so they're wired before the instance starts emitting. For handlers with a lifetime shorter than the instance (e.g. conditional subscriptions), hold onto the returned unsubscribe function and call it when done.
:::

```ts twoslash
import { Cubit } from '@blac/core';

class MyCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });

    this.onSystemEvent('stateChanged', ({ state, previousState }) => {
      console.log('State changed:', previousState, '->', state);
    });

    this.onSystemEvent('dispose', () => {
      console.log('Instance disposed');
    });
  }
}
```

## Event payloads

The handler argument differs by event. The payload types are:

```ts
interface SystemEventPayloads<S> {
  stateChanged: { state: S; previousState: S };
  dispose: void;
  hydrationChanged: {
    status: HydrationStatus;
    previousStatus: HydrationStatus;
    error?: Error;
    changedWhileHydrating: boolean;
  };
}
```

### `stateChanged`

Fired once per **microtask flush** after state changes via `emit`, `update`, or `patch`. Multiple synchronous mutations are coalesced — the handler receives the final state once, not once per call.

| Payload field   | Type | Description                                   |
| --------------- | ---- | --------------------------------------------- |
| `state`         | `S`  | The final state after the flush.              |
| `previousState` | `S`  | The state before any mutations in this flush. |

:::note[Why once-per-flush?]
A single user action often triggers several `emit`/`patch` calls in a row. If `stateChanged` fired on each one, every handler (and every subscriber and plugin downstream) would run multiple times for one logical change, with `previousState` pointing at transient in-between values nobody cares about. BlaC instead **coalesces** all synchronous mutations into one flush on the next microtask: `previousState` is the state before the _first_ mutation, `state` is the state after the _last_. That keeps handlers cheap and consistent, and it's the same batching model plugins' `onStateChange` and [`watch`](/core/watch) callbacks ride on. The trade-off: your handler runs **asynchronously**, just after the current synchronous code finishes — not inside the `emit` call.
:::

```ts twoslash
import { Cubit } from '@blac/core';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });

    this.onSystemEvent('stateChanged', ({ state, previousState }) => {
      // state: the final state after the flush
      // previousState: the state before any mutations in this flush
      console.log(`count: ${previousState.count} -> ${state.count}`);
    });
  }

  increment = () => this.update((s) => ({ count: s.count + 1 }));
}
```

### `dispose`

Fired when the instance is disposed (ref count reaches zero or `dispose()` is called directly). This is your hook to release anything the instance set up that the registry can't clean up for you.

**Payload:** `void` — no payload; the instance is already disposed when this fires.

:::tip[The dispose hook is your `componentWillUnmount`]
If a bloc starts a `setInterval`, opens a WebSocket, or subscribes to something external in its constructor/`init`, the `dispose` event is where you stop it. The registry disposes the instance the moment its last consumer releases (see [Instance Management](/core/instance-management)); without a `dispose` handler, those external resources keep running after the bloc is gone.
:::

```ts twoslash
import { Cubit } from '@blac/core';

class PollingCubit extends Cubit<{ data: string | null }> {
  private timer: ReturnType<typeof setInterval> | null = null;

  constructor() {
    super({ data: null });

    this.timer = setInterval(() => {
      this.patch({ data: new Date().toISOString() });
    }, 1000);

    this.onSystemEvent('dispose', () => {
      if (this.timer !== null) {
        clearInterval(this.timer);
        this.timer = null;
      }
    });
  }
}
```

### `hydrationChanged`

Fired when the hydration status changes. Relevant when using the [Persistence plugin](/plugins/persistence).

| Payload field           | Type                   | Description                                                             |
| ----------------------- | ---------------------- | ----------------------------------------------------------------------- |
| `status`                | `HydrationStatus`      | The new status: `'idle'` \| `'hydrating'` \| `'hydrated'` \| `'error'`. |
| `previousStatus`        | `HydrationStatus`      | The status before the change.                                           |
| `error`                 | `Error` \| `undefined` | Present when `status` is `'error'`.                                     |
| `changedWhileHydrating` | `boolean`              | `true` if state was modified before hydration completed.                |

**Returns:** `void`.

`changedWhileHydrating` is the signal that the bloc emitted real state _while_ async hydration was in flight — the persistence layer uses it to decide whether the just-loaded persisted state is stale and should be discarded. See [Persistence](/plugins/persistence) for the full hydration lifecycle.

```ts twoslash
import { Cubit } from '@blac/core';

class StoredCubit extends Cubit<{ value: string }> {
  constructor() {
    super({ value: '' });

    this.onSystemEvent(
      'hydrationChanged',
      ({ status, previousStatus, error, changedWhileHydrating }) => {
        if (status === 'error' && error) {
          console.error('Hydration failed:', error.message);
        }
        if (changedWhileHydrating) {
          console.warn(
            'State changed before hydration finished — persisted state may be stale',
          );
        }
        console.log(`${previousStatus} -> ${status}`);
      },
    );
  }
}
```

## Unsubscribing

`onSystemEvent` returns an unsubscribe function:

```ts twoslash
import { Cubit } from '@blac/core';

class ExampleCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });

    const unsub = this.onSystemEvent('stateChanged', ({ state }) => {
      console.log(state);
    });
    // Call unsub() to remove the handler early — before the instance is disposed.
    // For instance-lifetime handlers you can discard the return value.
    unsub();
  }
}
```

You only need to call this for handlers with a lifetime shorter than the instance (e.g. one registered conditionally). Handlers that should live for the whole instance need no manual cleanup — `dispose` tears them all down.

## System events vs plugins

Both observe lifecycle, and they share the same coalesced-flush model — the difference is **scope** and **where the code lives**:

|              | System events                           | Plugins                                    |
| ------------ | --------------------------------------- | ------------------------------------------ |
| **Scope**    | Single instance                         | All instances                              |
| **Access**   | Inside the class (`this.onSystemEvent`) | Global via `getPluginManager()`            |
| **Use case** | Instance-specific side effects          | Cross-cutting concerns (logging, devtools) |

Use system events for cleanup logic, derived computations, or side effects that belong to **one specific instance**. Use [plugins](/core/plugins) for behavior that applies **across all** state containers.

A useful way to see the relationship: a `stateChanged` system handler and a plugin's `onStateChange` hook fire off the _same_ underlying flush. The system event is the narrow, in-class view (this instance only, payload `{ state, previousState }`); the plugin hook is the broad, external view (every instance, plus the changed `paths` and a rich `PluginContext`). Reach for whichever scope matches the job — don't install a plugin to do one instance's cleanup, and don't try to make a system handler observe the whole app.

:::caution[Common mistakes]
**Don't emit from inside a `stateChanged` handler.** Mutating this bloc's state inside its own `stateChanged` handler schedules another flush, which fires the handler again — an unbounded feedback loop. (BlaC's dev-only emit-rate breaker will eventually `console.warn`, but the loop is still a bug.) Derive values without emitting, or move the write behind a guard that can't re-trigger.

**Don't do heavy synchronous work in `stateChanged`.** It runs on every flush; expensive work there compounds with frequent updates. Debounce, or move the work into the action that caused the change.

**Don't rely on `stateChanged` firing synchronously.** It's microtask-deferred, so code reading a side effect immediately after `emit()` won't see it yet. If you need the value right away, read `this.state` directly instead of waiting on the event.
:::

## See also

- [Plugins](/core/plugins) — the same lifecycle hooks observed across all instances
- [watch](/core/watch) — observe a bloc's changes from outside the class (rides the same flush)
- [Instance Management](/core/instance-management) — what triggers the `dispose` event
- [Persistence](/plugins/persistence) — the real-world consumer of `hydrationChanged`

---

# Tracking

> How BlaC records which leaves of state each consumer reads via a recording proxy, then wakes only the consumers whose leaves actually moved.

Source: /core/tracked/

Tracking is how BlaC knows which consumers care about a given state change. Instead of re-running every observer on every change, BlaC records exactly which leaves of the state each consumer reads, then wakes only the consumers whose leaves actually moved.

This page explains the mechanism: what gets recorded, how the recording proxy works, how getters fold into it, and how it maps onto re-renders. If you only want the React-facing rules, jump to [Dependency Tracking](/react/dependency-tracking); for the design rationale, see the [Mental Model](/guide/mental-model).

:::caution[Tracking is automatic — there is nothing to opt into]
Tracking is **automatic and unconditional**: there is no `tracked()` helper, no `@tracked` decorator, no `autoTrack` option, and nothing to opt into. The recording happens for you whenever a consumer reads state. To see which paths trigger re-renders at runtime, use the [BlaC DevTools](/plugins/devtools). To narrow or opt out of tracking in React, use the `select` option (see below).
:::

## What tracking is

Every state container holds an immutable state object. When you `emit`/`update`/`patch`, the container produces a _new_ state and diffs it against the previous one, marking the set of **paths** that changed — for example `user.name` or `items`. A path is a dotted route to a leaf in the state tree.

Separately, each consumer (a `useBloc` call, a plugin, a manual subscriber) declares an **interest**: the set of paths it reads. On each change, the container intersects "paths that changed" with "paths this consumer reads." If the intersection is empty, the consumer stays asleep.

The clever part is that you never write the interest set by hand. BlaC observes which paths you read and builds it for you.

## The read-recording proxy

### `trackRender(state, interner)`

The internal function that wraps state in a recording `Proxy` for each consumer render.

```ts
function trackRender<S>(state: S, interner: PathInterner): TrackResult<S>;
```

| Parameter  | Type           | Required | Description                                                                                                    |
| ---------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `state`    | `S`            | yes      | The raw state value to wrap. Non-object values (primitives, `null`) are returned as-is with an empty path set. |
| `interner` | `PathInterner` | yes      | The path interner for the container — interns dotted path strings into compact `PathId` values.                |

**Returns:** a `TrackResult<S>` — an object `{ value: S, paths: Set<PathId> }` where `value` is the recording proxy and `paths` is the live set that grows as properties are read.

**Behavior.** This is an internal API, not exported from `@blac/core`. It is called automatically by the React adapter (`useBloc`) on every render. The proxy records according to these rules:

| Rule                                                    | Effect                                                                                                                                                                                                                  |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Leaf-only (maximal) recording**                       | Reading `a.b.c` records just `a.b.c`, and drops the parent `a.b` from the set. Two consumers reading sibling leaves (`user.name` vs `user.address`) are isolated — one does not wake when the other's sibling changes.  |
| **Reading a whole object keeps it as the leaf**         | If you read `state.user` and stop there (no deeper key), `user` is your leaf and you wake on any change inside it. Read deeper to narrow.                                                                               |
| **Primitives short-circuit**                            | Reading a primitive, `null`, or `undefined` returns it as-is and records the path you took to reach it.                                                                                                                 |
| **Nested objects/arrays return child proxies**          | They record into the same set, and are cached per read, so `state.user === state.user` within one render.                                                                                                               |
| **Iteration coarsens**                                  | `for..of`, `.map`, `.find`, `.reduce` record the container path (e.g. `users`) but not per-index paths; callbacks receive the raw values. So a list component re-renders when the list changes, which is what you want. |
| **`Map` / `Set` / `Date` / class instances are leaves** | They are not wrapped. A change to one is detected as a reference change at its own path — so you must replace the whole value (a new `Map`), not mutate it in place, for the change to be seen.                         |

:::danger[Common mistake: non-plain values are not deeply tracked]
Only plain object literals and arrays are proxied. If you store a `Map`, `Set`, `Date`, or a class instance in state and mutate it in place, no path is marked and nothing re-renders. Replace the value with a new instance instead:

```ts twoslash
import { Cubit } from '@blac/core';

class TagCubit extends Cubit<{ tags: Set<string> }> {
  constructor() {
    super({ tags: new Set() });
  }

  // Won't re-render — same reference, no path marked
  // (never mutate state directly anyway — state is immutable)
  // this.state.tags.add('new'); ← wrong

  // Will re-render — new reference at the `tags` path
  addTag = (tag: string) => {
    this.update((s) => ({ tags: new Set([...s.tags, tag]) }));
  };
}
```

:::

## Getters auto-track during render

A getter on the bloc is **derived state**: it reads other state and computes a value. Getters are the right way to model a value derived from state — a `get total()` is recomputed on every read and can never drift from `items`.

In React auto-tracking mode, the `bloc` returned by `useBloc` is a per-consumer proxy too. Getter calls are invoked with a tracked `this`, so `this.state` inside the getter resolves to the current render's recording proxy:

```ts twoslash
import { Cubit } from '@blac/core';

interface CartItem {
  price: number;
}

class CartCubit extends Cubit<{ items: CartItem[]; coupon: string | null }> {
  get total() {
    // During render, this records `items` through the consumer's proxy.
    return this.state.items.reduce((sum, i) => sum + i.price, 0);
  }
}
```

So a render can read the getter directly:

```tsx
function Total() {
  const [, cart] = useBloc(CartCubit);
  return <span>{cart.total}</span>;
}
```

Use `select` when you want the getter's return value, rather than its source paths, to gate re-renders:

```tsx
function Total() {
  const [, cart] = useBloc(CartCubit, {
    select: (state, cart) => [cart.total],
  });
  return <span>{cart.total}</span>;
}
```

See [Dependency Tracking](/react/dependency-tracking#what-does-not-register-a-dependency) for the full list of what does and doesn't register.

## When tracking matters (and when it doesn't)

Tracking exists to make re-renders precise. It matters most when:

- A single container holds many fields and different components read different subsets.
- A container updates frequently (typing, dragging, streaming) but each tick changes only a slice.

It matters less for a tiny container where every consumer reads everything — there the diff is cheap and the wake set is "everyone" regardless.

:::note[Tracking outside React]
Auto-tracking via the recording proxy is a **React render-time** feature, driven by `useBloc`. The lower-level container API (`channel.subscribe(interest, cb)`) lets you declare an interest set directly. The convenience helper [`watch`](/core/watch) deliberately does **not** auto-track: it subscribes to _all_ paths and fires on every change. If you need selective observation outside React, subscribe to the channel with an explicit interest, or filter inside your callback.
:::

## How tracking relates to re-renders

Putting it together, one update flows like this:

1. A method calls `emit` / `update` / `patch`. The container diffs old vs new state and marks the changed paths.
2. Changes are coalesced per microtask flush, so several synchronous mutations produce one notification (see [System Events](/core/system-events)).
3. On flush, each consumer's recorded interest is intersected with the changed paths.
4. Consumers with a non-empty intersection re-render (React) or have their callback invoked. The rest stay asleep.
5. On the next render, the proxy re-records the interest from scratch — so if a component conditionally reads different fields, the tracked set adapts automatically.

The practical takeaway: read exactly the state you render, keep state immutable, and BlaC will re-render the minimum. To drive a specific consumer from an explicit derived-value array instead of render-time reads, use the `select` option on `useBloc` (see [Dependency Tracking](/react/dependency-tracking#the-select-escape-hatch)).

## See also

- [Dependency Tracking](/react/dependency-tracking) — the React-facing rules, `select`, and limitations
- [Performance](/react/performance) — splitting readers from writers and avoiding over-reads
- [Mental Model](/guide/mental-model) — why proxy tracking beats selectors and memoization
- [watch](/core/watch) — observing state outside React

## Troubleshooting

For the full FAQ see [Troubleshooting](/guide/troubleshooting). Below are tracking-specific problems.

### Mutating a `Map`, `Set`, or `Date` doesn't trigger a re-render

**Symptom:** You call `.set()`, `.add()`, or another mutating method on a `Map`/`Set`/`Date` stored in state, but the component doesn't re-render.

**Cause:** The tracker wraps plain objects and arrays only. A `Map`, `Set`, `Date`, or class instance is treated as a single leaf — the tracker detects changes as a **reference change** at that path, never as an internal mutation.

**Fix:** Replace the whole value with a new instance so the reference changes:

```ts twoslash
import { Cubit } from '@blac/core';

class TagCubit extends Cubit<{ tags: Set<string> }> {
  constructor() {
    super({ tags: new Set() });
  }

  // No-op — same Set reference, nothing tracked
  // this.state.tags.add('new'); ← never mutate state directly anyway

  // Correct — new Set reference, change detected at the `tags` path
  addTag = (tag: string) => {
    this.update((s) => ({ tags: new Set([...s.tags, tag]) }));
  };
}
```

### Getter read outside render never wakes the component

**Symptom:** Code reads `bloc.computedValue` (a getter) in an effect, event handler, async callback, or other post-render code and expects that read to subscribe the component.

**Cause:** The recording proxy is active only while React is evaluating the render body. After commit, getters fall through to live state and record nothing.

**Fix:** Read the getter during render, or depend on it via `select`:

```tsx
function Total() {
  const [, cart] = useBloc(CartCubit);
  return <span>${cart.total}</span>;
}
```

See [Getters auto-track during render](#getters-auto-track-during-render) above and [Performance: Getters as computed properties](/react/performance#pattern-getters-as-computed-properties).

---

# Types

> The complete type toolkit exported from @blac/core — utilities to derive state, args, deps, and instance shapes from a container class, plus branded-ID helpers.

Source: /core/types/

The complete type toolkit exported from `@blac/core`. These utilities let you derive the state, args, deps, and instance shapes of a container class without hand-writing them, and the branded-ID helpers give you nominal `InstanceId` strings. Every signature on this page is quoted verbatim from source.

For a task-oriented walkthrough of typing blocs (generic parameters, inference, common pitfalls) see [TypeScript](/guide/typescript). This page is the reference: one heading per export, the exact signature, what it does, and a small example.

:::note[Where these come from]
The extraction and instance utilities live in `@blac/core`'s `types/utilities` module; the branded-ID helpers live in `types/branded`. Both are re-exported from the package root, so you import everything from `@blac/core` directly.
:::

All examples assume this setup, which is hidden from the rendered snippet but type-checked:

```ts twoslash
import { Cubit } from '@blac/core';

interface CounterState {
  count: number;
  label: string;
}

class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0, label: 'idle' });
  }
}
```

## Extracting type parameters

A `StateContainer` (and therefore `Cubit`) carries three type parameters: `S` (state), `Args` (serializable construction/identity data), and `Deps` (injected non-serializable handles). These utilities pull each one back out of a container _class_ (the constructor, e.g. `typeof CounterCubit`), so you never have to re-declare a state shape that already lives on the class.

### `ExtractState`

**Signature**

```ts
export type ExtractState<T> =
  T extends StateContainerConstructor<infer S> ? Readonly<S> : never;
```

Extracts the state type from a container constructor as a `Readonly<S>`. This is the type you get back from `useBloc` and from the `state` getter — read-only, because state is immutable from the outside. Resolves to `never` if `T` is not a container constructor.

```ts twoslash
import { Cubit } from '@blac/core';
import type { ExtractState } from '@blac/core';
interface CounterState {
  count: number;
  label: string;
}
class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0, label: 'idle' });
  }
}
// ---cut---
type S = ExtractState<typeof CounterCubit>;
//   ^?
```

### `ExtractStateMutable`

**Signature**

```ts
export type ExtractStateMutable<T> =
  T extends StateContainerConstructor<infer S> ? S : never;
```

The same as `ExtractState`, but without the `Readonly<>` wrapper — the raw `S` as the class declared it. Reach for this only when you genuinely need a mutable view (for example, building the next state object before you `emit` it); prefer `ExtractState` everywhere a value is being read.

```ts twoslash
import { Cubit } from '@blac/core';
import type { ExtractStateMutable } from '@blac/core';
interface CounterState {
  count: number;
  label: string;
}
class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0, label: 'idle' });
  }
}
// ---cut---
type Draft = ExtractStateMutable<typeof CounterCubit>;
//   ^?
```

### `ExtractArgs`

**Signature**

```ts
export type ExtractArgs<T> = T extends new () => StateContainer<
  any,
  infer A,
  any
>
  ? A
  : void;
```

Extracts the `Args` type — the serializable data a bloc is constructed/identified with (see [Passing Inputs](/guide/inputs)). Falls back to `void` when the class declares no args. Note the match is against a zero-argument constructor shape (`new () =>`), which is how container subclasses are written.

```ts twoslash
import { Cubit } from '@blac/core';
import type { ExtractArgs } from '@blac/core';
// ---cut---
interface UserState {
  name: string;
}
class UserCubit extends Cubit<UserState, { userId: string }> {
  constructor() {
    super({ name: '' });
  }
}

type A = ExtractArgs<typeof UserCubit>;
//   ^?
```

### `ExtractDeps`

**Signature**

```ts
export type ExtractDeps<T> = T extends new () => StateContainer<
  any,
  any,
  infer D
>
  ? D
  : Record<string, never>;
```

Extracts the `Deps` type — the injected non-serializable handles (clients, services, other blocs) a container depends on. Falls back to `Record<string, never>` (the "no deps" shape) when none are declared.

```ts twoslash
import { Cubit } from '@blac/core';
import type { ExtractDeps } from '@blac/core';
// ---cut---
interface FeedState {
  posts: string[];
}
class FeedCubit extends Cubit<FeedState, void, { api: { fetch(): void } }> {
  constructor() {
    super({ posts: [] });
  }
}

type D = ExtractDeps<typeof FeedCubit>;
//   ^?
```

### `ExtractConstructorArgs`

**Signature**

```ts
export type ExtractConstructorArgs<T> = T extends new (...args: infer P) => any
  ? P
  : never[];
```

Extracts the _runtime_ constructor parameter tuple from any class — this is plain TypeScript constructor inference, not BlaC's `Args`. Use it when you need the literal `constructor(...)` parameters of a class. Resolves to `never[]` for non-constructors.

```ts twoslash
import type { ExtractConstructorArgs } from '@blac/core';
// ---cut---
class Point {
  constructor(
    public x: number,
    public y: number,
  ) {}
}

type P = ExtractConstructorArgs<typeof Point>;
//   ^?
```

## Instance and constructor types

These describe the _instance_ a container class produces, and the _constructor_ shape (including the static registry methods like `acquire` and `release`) that `@blac/core` and `@blac/react` use to type their entry points.

### `BlocInstanceType`

**Signature**

```ts
export type BlocInstanceType<T extends abstract new (...args: any) => any> =
  T extends abstract new (...args: any) => infer R ? R : any;
```

Resolves a constructor type to its instance type, including abstract classes. It is the abstract-aware sibling of TypeScript's built-in `InstanceType<T>` (which rejects abstract constructors). Because `Cubit` and `StateContainer` are abstract, this is the safe choice for "the instance of this class."

```ts twoslash
import { Cubit } from '@blac/core';
import type { BlocInstanceType } from '@blac/core';
interface CounterState {
  count: number;
  label: string;
}
class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0, label: 'idle' });
  }
}
// ---cut---
type Instance = BlocInstanceType<typeof CounterCubit>;
```

### `BlocConstructor`

**Signature**

```ts
export type BlocConstructor<
  S extends object = any,
  T extends new (...args: any[]) => StateContainer<S, any, any> = new (
    ...args: any[]
  ) => StateContainer<S, any, any>,
> = (new (...args: any[]) => InstanceType<T>) & {
  keepAlive?: boolean;
};
```

A constructor type for a `StateContainer` subclass, with an optional `keepAlive` static flag. Any ordinary `Cubit` / `Bloc` subclass satisfies `BlocConstructor` directly. There is no static registry surface on the type itself — `acquire`, `borrow`, `borrowSafe`, `ensure`, and `release` are **standalone functions** imported from `@blac/core`, not static methods on the class. Their parameter type is the lighter [`StateContainerConstructor`](#statecontainerconstructor). See [Instance Management](/core/instance-management) for what those functions do.

```ts twoslash
import { acquire, release } from '@blac/core';
import type { BlocConstructor, StateContainerConstructor } from '@blac/core';
import { Cubit } from '@blac/core';
interface CounterState {
  count: number;
  label: string;
}
class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0, label: 'idle' });
  }
}
// ---cut---
// A helper that only needs "some container class" uses StateContainerConstructor.
// A plain Cubit/Bloc subclass satisfies this directly.
function describe(Bloc: StateContainerConstructor) {
  const inst = acquire(Bloc);
  release(Bloc);
  return inst;
}

describe(CounterCubit);

// BlocConstructor is an alias for a constructable StateContainer with an
// optional keepAlive flag — any Cubit/Bloc subclass satisfies it directly.
type CounterCtor = BlocConstructor<CounterState>;
//   ^?
```

### `InstanceReadonlyState`

**Signature**

```ts
export type InstanceReadonlyState<T extends StateContainerConstructor = any> =
  Omit<InstanceType<T>, 'state'> & { state: ExtractState<T> };
```

The instance type of a container class with its `state` property narrowed to the `Readonly` state for that class. Useful when you want the full instance (methods, getters) but with a precisely-typed, read-only `state`.

```ts twoslash
import { Cubit } from '@blac/core';
import type { InstanceReadonlyState } from '@blac/core';
interface CounterState {
  count: number;
  label: string;
}
class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0, label: 'idle' });
  }
}
// ---cut---
type ReadonlyInstance = InstanceReadonlyState<typeof CounterCubit>;
declare const c: ReadonlyInstance;
c.state.count;
//        ^?
```

### `InstanceState`

**Signature**

```ts
export type InstanceState<T extends StateContainerConstructor = any> = Omit<
  InstanceType<T>,
  'state'
> & { state: ExtractStateMutable<T> };
```

Like `InstanceReadonlyState`, but the `state` property is the _mutable_ `S` rather than `Readonly<S>`. Reach for it only when you specifically need a writable view of state on a typed instance.

```ts twoslash
import { Cubit } from '@blac/core';
import type { InstanceState } from '@blac/core';
interface CounterState {
  count: number;
  label: string;
}
class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0, label: 'idle' });
  }
}
// ---cut---
type MutableInstance = InstanceState<typeof CounterCubit>;
```

### `StateContainerInstance`

**Signature**

```ts
export type StateContainerInstance<S extends object = any> = Omit<
  StateContainer<S, any, any>,
  'state'
> & { state: Readonly<S> };
```

A `StateContainer` instance keyed by its _state_ type `S` rather than by a concrete class, with `state` narrowed to `Readonly<S>`. Use it when you want to describe "any container holding this state shape" without pinning a specific subclass.

```ts twoslash
import type { StateContainerInstance } from '@blac/core';
// ---cut---
interface CounterState {
  count: number;
  label: string;
}
function readCount(c: StateContainerInstance<CounterState>) {
  return c.state.count;
}
```

### `StateContainerConstructor`

**Signature**

```ts
export type StateContainerConstructor<S extends object = any> = new (
  ...args: any[]
) => StateContainer<S, any, any>;
```

The minimal constructor type for a container class, parameterized by state `S`. It is the constraint the extraction utilities (`ExtractState`, `ExtractStateMutable`, `InstanceReadonlyState`, `InstanceState`) match against. Unlike [`BlocConstructor`](#blocconstructor) it carries no static registry methods — use it where you only care that something is a container class.

```ts twoslash
import { Cubit } from '@blac/core';
import type { StateContainerConstructor } from '@blac/core';
interface CounterState {
  count: number;
  label: string;
}
class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0, label: 'idle' });
  }
}
// ---cut---
const Ctor: StateContainerConstructor<CounterState> = CounterCubit;
```

## Branded IDs

BlaC tags instance-identity strings with a _brand_ so a plain `string` cannot be passed where an `InstanceId` is expected. The brand is a compile-time-only phantom property keyed by a `unique symbol`; it has no runtime footprint — branded values are just strings at runtime.

### `Brand`

**Signature**

```ts
declare const brand: unique symbol;

export type Brand<T, B> = T & { [brand]: B };
```

The general nominal-typing helper: intersects a base type `T` with a phantom property under a private `unique symbol`, tagged by the brand identifier `B`. Two `Brand`s with different `B` are incompatible even when `T` is identical, which is what prevents accidental mixing of similar primitive types.

```ts twoslash
import type { Brand } from '@blac/core';
// ---cut---
type UserId = Brand<string, 'UserId'>;
type OrderId = Brand<string, 'OrderId'>;

declare const u: UserId;
declare function loadOrder(id: OrderId): void;
// @errors: 2345
loadOrder(u);
```

### `BrandedId`

**Signature**

```ts
export type BrandedId<B> = Brand<string, B>;
```

A convenience alias for the common case of branding a `string`: `BrandedId<B>` is exactly `Brand<string, B>`. Use it whenever the base type is a string ID.

```ts twoslash
import type { BrandedId } from '@blac/core';
// ---cut---
type SessionId = BrandedId<'SessionId'>;
```

### `InstanceId`

**Signature**

```ts
export type InstanceId = Brand<string, 'InstanceId'>;
```

The branded `string` type BlaC uses for state-container instance identities — `BrandedId<'InstanceId'>` by another name. Registry and identity APIs accept and return this rather than a bare `string`, so an arbitrary string cannot stand in for an instance key by accident.

```ts twoslash
import type { InstanceId } from '@blac/core';
// ---cut---
declare function lookup(id: InstanceId): void;
// @errors: 2345
lookup('not-branded');
```

### `instanceId()`

**Signature**

```ts
export function instanceId(id: string): InstanceId {
  return id as InstanceId;
}
```

The value-level helper that brands a plain `string` as an [`InstanceId`](#instanceid). It is a pure cast at runtime (returns the input unchanged); its only job is to give you a typed `InstanceId` to hand to APIs that require one, without writing the `as InstanceId` assertion yourself.

```ts twoslash
import { instanceId } from '@blac/core';
import type { InstanceId } from '@blac/core';
// ---cut---
const id: InstanceId = instanceId('user-42');
```

## See also

- [TypeScript](/guide/typescript) — typing blocs end to end: generics, inference, and pitfalls
- [Cubit](/core/cubit) — the class these utilities extract types from
- [Instance Management](/core/instance-management) — `acquire` / `borrow` / `release` and the registry surface that `BlocConstructor` describes
- [Passing Inputs](/guide/inputs) — the args / deps identity model that `ExtractArgs` and `ExtractDeps` read
- [useBloc](/react/use-bloc) — where `ExtractState` shows up as the hook's return type

---

# watch

> Observe one or more blocs outside React and run a callback whenever their state changes — the escape hatch for loggers, analytics, localStorage sync, imperative UI, and test assertions.

Source: /core/watch/

`useBloc` connects a bloc to a React component. But state often needs to reach code that has no component to render: a logger, an analytics pipeline, a `localStorage` sync, a `<canvas>` driven by an imperative library, or a test assertion. `watch` is the escape hatch for those cases — it observes one or more blocs **outside of React** and runs a callback whenever their state changes.

:::note[watch fires on every change, not only on what you read]
Unlike `useBloc`, `watch` does **not** auto-track which properties your callback reads. It subscribes to the bloc's full state and invokes your callback on _every_ change (and once immediately). If you need to react only to a specific field, compare it yourself inside the callback, or use the lower-level `channel.subscribe(interest, cb)` API. Auto-tracking is a React render-time feature — see [Tracking](/core/tracked).
:::

## `watch(bloc, callback)`

Observe one or more blocs outside React and run a callback on every state change.

```ts
// Single bloc
function watch<T extends StateContainerConstructor>(
  bloc: T | BlocRef<T>,
  callback: (bloc: InstanceType<T>) => void | typeof watch.STOP,
): () => void;

// Multiple blocs
function watch<T extends readonly BlocInput[]>(
  blocs: T,
  callback: (blocs: ExtractInstances<T>) => void | typeof watch.STOP,
): () => void;
```

| Parameter        | Type                                                   | Required | Description                                                                                                                                                            |
| ---------------- | ------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bloc` / `blocs` | `T \| BlocRef<T>` or `readonly BlocInput[]`            | yes      | A bloc class (resolves to the default instance), an [`instance(Class, id)`](#watching-a-named-instance) reference, or a `readonly` array of either.                    |
| `callback`       | `(bloc: InstanceType<T>) => void \| typeof watch.STOP` | yes      | Runs once immediately with the current instance(s), then on every subsequent state change. Return `watch.STOP` to tear down the subscription from inside the callback. |

**Returns:** a `stop()` function. Calling it unsubscribes and is idempotent — calling it more than once is safe.

**Behavior.** `watch` resolves each input from the registry via `ensure` — creating the instance if it does not exist yet. It does **not** hold a ref: `watch` will not keep an otherwise-unused bloc alive, and a bloc it created can be disposed if nothing else references it. Subscriptions are coalesced per microtask flush — several synchronous mutations produce a single callback run — so callbacks land asynchronously after `emit()`. The callback fires **once immediately** on setup with the current state, then again after every subsequent change.

```ts twoslash
import { watch } from '@blac/core';
import { Cubit } from '@blac/core';

class UserCubit extends Cubit<{ name: string }> {
  constructor() {
    super({ name: 'Alice' });
  }
}

const stop = watch(UserCubit, (user) => {
  console.log('User state changed:', user.state.name);
});

// later — e.g. in a cleanup or on teardown of your module:
stop();
```

## `instance(BlocClass, args?)`

Create a reference to a specific keyed bloc instance for use with `watch`.

```ts
function instance<T extends StateContainerConstructor>(
  BlocClass: T,
  args?: ExtractArgs<T>,
): BlocRef<T>;
```

| Parameter   | Type                                  | Required | Description                                                                                                                  |
| ----------- | ------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `BlocClass` | `T extends StateContainerConstructor` | yes      | The bloc class to reference.                                                                                                 |
| `args`      | `ExtractArgs<T>`                      | no       | The args identifying the instance — the same args you pass to `useBloc`. Resolved to a key via `static key`/structural hash. |

**Returns:** a `BlocRef<T>` — a lightweight reference object that tells `watch` which keyed instance to resolve.

**Behavior.** By default `watch(SomeCubit, ...)` resolves the **default** instance. Wrap with `instance(Class, args)` to target the instance keyed by those args.

```ts twoslash
import { watch, instance } from '@blac/core';
import { Cubit } from '@blac/core';

class UserCubit extends Cubit<{ name: string }, { userId: string }> {
  static key = (a: { userId: string }) => a.userId;
  constructor() {
    super({ name: '' });
  }
}

const stop = watch(instance(UserCubit, { userId: 'user-123' }), (user) => {
  console.log(user.state.name);
});
```

## Stopping a watch

A watch lives until you stop it. There are two ways, and forgetting both is the most common `watch` bug.

### Call the returned stop function

```ts twoslash
import { watch } from '@blac/core';
import { Cubit } from '@blac/core';

class UserCubit extends Cubit<{ name: string }> {
  constructor() {
    super({ name: '' });
  }
}

const stop = watch(UserCubit, (user) => {
  console.log(user.state.name);
});

// later — e.g. in a cleanup, useEffect teardown, or on teardown of your module:
stop();
```

### Return `watch.STOP` from the callback

For one-shot or self-terminating watches, return the `watch.STOP` sentinel and the subscription tears itself down:

```ts twoslash
import { watch } from '@blac/core';
import { Cubit } from '@blac/core';

class UserCubit extends Cubit<{ onboardingComplete: boolean }> {
  constructor() {
    super({ onboardingComplete: false });
  }
}

declare function runOnce(): void;

watch(UserCubit, (user) => {
  if (user.state.onboardingComplete) {
    runOnce();
    return watch.STOP; // stop after the condition is met
  }
});
```

:::danger[Common mistake: leaking the watcher]
A `watch` you never stop keeps its subscription forever, holding a reference to the bloc and re-running your callback for the life of the process. Always either store and call `stop()`, or return `watch.STOP` once the work is done. Inside React, prefer `useBloc` over `watch`; if you must `watch` from an effect, return `stop` from the effect:

```tsx
import { useEffect } from 'react';
import { watch } from '@blac/core';

// (in a React component)
useEffect(() => {
  // const stop = watch(AuthCubit, (auth) => persistToken(auth.state.token));
  // return stop; // tear down on unmount
}, []);
```

:::

## Watching multiple blocs

Pass a `readonly` array to observe several blocs at once — the callback fires when **any** of them changes.

```ts twoslash
import { watch } from '@blac/core';
import { Cubit } from '@blac/core';

class UserCubit extends Cubit<{ name: string }> {
  constructor() {
    super({ name: '' });
  }
}

class SettingsCubit extends Cubit<{ theme: string }> {
  constructor() {
    super({ theme: 'light' });
  }
}

declare function syncToServer(name: string, theme: string): void;

// Watch several blocs at once; the callback fires when any of them changes.
const stop = watch([UserCubit, SettingsCubit] as const, ([user, settings]) => {
  syncToServer(user.state.name, settings.state.theme);
});
```

## When to use watch

| Scenario                                             | Use                                         |
| ---------------------------------------------------- | ------------------------------------------- |
| A React component needs state                        | [`useBloc`](/react/use-bloc)                |
| Non-React side effects (logging, analytics, syncing) | `watch`                                     |
| Bridging a bloc to imperative / non-React UI         | `watch`                                     |
| Test assertions on state over time                   | `watch`                                     |
| You need selective, path-scoped observation          | `container.channel.subscribe(interest, cb)` |

## Examples

### Logging state changes

```ts twoslash
import { watch } from '@blac/core';
import { Cubit } from '@blac/core';

interface CartItem {
  price: number;
}

class CartCubit extends Cubit<{ items: CartItem[] }> {
  constructor() {
    super({ items: [] });
  }

  get total() {
    return this.state.items.reduce((sum, i) => sum + i.price, 0);
  }
}

declare const logger: { info(msg: string, data: unknown): void };

const stop = watch(CartCubit, (cart) => {
  logger.info('cart changed', {
    itemCount: cart.state.items.length,
    total: cart.total, // getters work here too
  });
});
```

### Bridging to non-React code

Drive an imperative library (a chart, a map, a canvas) from bloc state without a React wrapper:

```ts twoslash
import { watch } from '@blac/core';
import { Cubit } from '@blac/core';

class MetricsCubit extends Cubit<{ series: number[] }> {
  constructor() {
    super({ series: [] });
  }
}

declare function createChart(el: HTMLElement): {
  setData(series: number[]): void;
  destroy(): void;
};

function attachChart(el: HTMLElement) {
  const chart = createChart(el);
  const stop = watch(MetricsCubit, (metrics) => {
    chart.setData(metrics.state.series);
  });
  // hand the caller a teardown that stops the watch and the chart
  return () => {
    stop();
    chart.destroy();
  };
}
```

## `watch` vs `channel.subscribe`

Both observe a single container outside React; both fire once per microtask flush. The differences:

- **`watch`** gives you the **instance** (so getters and methods are available), accepts multiple blocs, supports `instance()` references and the `watch.STOP` sentinel, and fires once immediately on setup.
- **`channel.subscribe`** is the lower-level path-scoped surface on a container's channel. You pass an _interest_ thunk (the paths you care about, or `ALL_PATHS` for everything) and a callback that fires when a matching path changes. It does not fire on setup and gives you the changed path set rather than the instance — read `state` off the container yourself. Prefer `watch` for whole-state observation; reach for `channel.subscribe` when you need path-scoped interest.

```ts twoslash
import { watch, ensure, ALL_PATHS } from '@blac/core';
import { Cubit } from '@blac/core';

class UserCubit extends Cubit<{ name: string }> {
  constructor() {
    super({ name: '' });
  }
}

const user = ensure(UserCubit);

// channel.subscribe: path-scoped, fires on change (not on setup)
const unsub = user.channel.subscribe(
  () => ALL_PATHS,
  () => {
    console.log(user.state.name);
  },
);

// watch: the instance, fires immediately, supports STOP and multiple blocs
const stop = watch(UserCubit, (u) => {
  console.log(u.state.name);
});
```

## See also

- [System Events](/core/system-events) — the microtask flush and coalescing model behind `watch`
- [Tracking](/core/tracked) — why `watch` does not auto-track, and how `useBloc` does
- [Dependency Tracking](/react/dependency-tracking) — the React side of selective re-renders

---

# Dependency tracking

> How BlaC auto-tracking records the state properties a component reads and re-renders only when one of those properties changes.

Source: /react/dependency-tracking/

When a component subscribes to a state container, the naive contract is "re-render whenever the state changes." That contract is wasteful: a `UserCubit` holding `name`, `email`, and `avatarUrl` would re-render your avatar component every time the email changes, even though the avatar never reads it.

BlaC fixes this with **auto-tracking**: it records which state properties each component actually reads during render, and re-renders that component only when one of _those_ properties changes. You write plain property access; the re-render scope is inferred for you — no selectors, no `useMemo`, no manual dependency arrays.

:::note[Mental model]
Auto-tracking, dependency tracking, and "proxy tracking" all name the same mechanism. The feature is **dependency tracking**; the default mode is **auto-tracking**; the implementation is a render-time recording **Proxy**. For the design rationale (why a proxy beats hand-written selectors), see [Mental Model](/guide/mental-model).
:::

## Auto-tracking (default)

The `state` value returned by `useBloc` is a `Proxy` that records every property your component reads during render. The recorded set becomes the component's re-render scope.

### Signature

```ts
// useBloc with no `select` option — auto-tracking is active
function useBloc<T extends StateContainerConstructor>(
  BlocClass: T,
  options?: Omit<UseBlocOptions<T>, 'select'>,
): [
  state: ExtractState<T>,
  bloc: InstanceReadonlyState<T>,
  ref: RefObject<ComponentRef>,
];
```

**Returns:** `[state, bloc, ref]` where `state` is a tracking Proxy and `bloc` is a per-consumer proxy for the instance. Any property accessed through `state` during render is recorded as a dependency. Getters read through `bloc` during render also record their underlying `this.state` reads. The component re-renders only when a recorded path changes.

**Behavior.**

1. During render, the Proxy records each property access as a **path** (`state.avatarUrl` → `avatarUrl`).
2. After the render commits, BlaC registers that path set with the container as this consumer's interest.
3. On a state change, the container diffs which paths actually changed and wakes only the consumers whose recorded paths intersect the change.
4. Tracking is recomputed on **every** render — if your component conditionally reads different properties next time, the tracked set adapts to match.

Each `useBloc` call gets its own proxy and its own recorded path set, so two components reading the same container are isolated from each other's re-renders.

```tsx
function UserAvatar() {
  const [state] = useBloc(UserCubit);
  return <img src={state.avatarUrl} />;
  // records: ['avatarUrl']
  // changes to state.name, state.email, etc. do NOT re-render this component
}
```

**Try it live.** Two components share one bloc. Each reads a different field — change one, only its reader re-renders:

<DependencyTrackingDemo client:visible />

### What DOES register a dependency

| Read pattern                                                     | Records             | Notes                                       |
| ---------------------------------------------------------------- | ------------------- | ------------------------------------------- |
| `state.name`                                                     | `name`              | Direct property access.                     |
| `state.user.profile.name`                                        | `user.profile.name` | Nested reads record the **leaf** path only. |
| `state.items[0]`                                                 | `items.0`           | Indexed access on an array.                 |
| `state.items.length`                                             | `items.length`      | `.length` is an own property read.          |
| Reading the whole object: `const u = state.user` (no deeper key) | `user`              | Wakes on **any** change to `user`.          |
| Getter read in render: `bloc.total`                              | getter source paths | The returned bloc is proxied; `this.state` inside the getter uses the tracking proxy. |

:::tip[Sibling-leaf isolation]
Recording is **leaf-only**: reading `state.user.name` records `user.name`, not `user`. So when an immutable update replaces the `user` object because a _sibling_ (`user.address`) changed, a component that only read `user.name` does **not** re-render — its observed leaf still resolves to the same value. Read the whole `user` object (with no deeper key) and you opt back into waking on any change beneath it.
:::

### What does NOT register a dependency

These are the patterns newcomers expect to track but don't — or that track more or less than intended.

:::caution[Common mistakes]

- **Destructuring is just reading** — `const { name } = state` records `name` (good). But `const { user } = state; return user.name` records only `user` (the deeper `.name` read happens off the _raw_ destructured value, not the proxy), so you wake on every `user` change. Read through the proxy chain (`state.user.name`) to get leaf isolation.
- **Spreading reads everything** — `<Card {...state} />` or `{ ...state }` enumerates every own key, so the component tracks the **entire** state object and re-renders on any change. Pass only the fields you need.
- **Reading inside an effect does not track** — the proxy records during _render_. Anything you read inside `useEffect`, an event handler, or an async callback runs after the render proxy is gone and records nothing. Read the value in the render body (or capture it from `state` there) if it should drive re-renders.
- **Iteration coarsens to the entry path** — `.map`, `.find`, `.reduce`, `for..of` record the array path (`items`) but **not** per-index paths, and their callbacks receive raw (un-proxied) values. A list re-renders when the array changes, not per item. See [Performance](/react/performance#list-rendering-patterns) for the per-item isolation pattern.
- **Non-plain values are leaves, not deeply tracked** — only plain objects `{}` and arrays `[]` are proxied. A `Map`, `Set`, `Date`, or class instance in your state is treated as a single leaf: BlaC detects a _reference_ change at that value's own path, but reading _into_ it (`state.cache.get(id)`) records nothing finer. Replace the whole value on update, or model that data as plain objects/arrays.
- **Methods read off the prototype don't record** — reading `bloc.increment` without calling it records nothing (methods live on the prototype, not as own properties). This is fine: action handlers shouldn't drive re-renders.
- **Getter reads outside render do not track** — a getter read in an effect, event handler, async callback, or after commit sees live state but records no dependency. Read the getter in the render body if it should drive re-renders, or use `select: (state, bloc) => [bloc.total]` when you want the getter's return value to be the explicit boundary.
  :::

### Conditional reads

Auto-tracking re-records on every render, which makes most conditional reads correct automatically. The condition itself must be read for the adaptive behavior to work:

```tsx
function UserInfo() {
  const [state] = useBloc(UserCubit);
  return (
    <div>
      <span>{state.name}</span>
      {state.showEmail && <span>{state.email}</span>}
    </div>
  );
}
```

This is correct. `state.showEmail` is **always** read, so it's always tracked. While `showEmail` is `false`, `email` is not read and not tracked — but when `showEmail` flips to `true`, the component re-renders (it tracked `showEmail`), the new render reads `email`, and `email` joins the tracked set from that point on.

:::caution[Where conditional reads break]
The hazard is reading a property behind a condition that is **never re-evaluated by a tracked change**. If the deciding value comes from a prop or another hook (not from this bloc's tracked state), flipping it may not re-run the read against the latest state. When the branch and the value both come from the same bloc's state, you're safe. When the deciding value is external, prefer `select` to make the dependency explicit.
:::

## The `select` escape hatch

### Signature

```ts
select?: (state: ExtractState<T>, bloc: InstanceReadonlyState<T>) => unknown[]
```

| Parameter | Type                       | Required | Description                                                           |
| --------- | -------------------------- | -------- | --------------------------------------------------------------------- |
| `state`   | `ExtractState<T>`          | yes      | The current raw state (not a proxy when `select` is active).          |
| `bloc`    | `InstanceReadonlyState<T>` | yes      | The bloc instance; use it to include getters in the dependency array. |

**Returns:** `unknown[]` — a tuple compared per-index via `Object.is`. The component re-renders only when an element changes.

**Behavior.** Providing a `select` function **opts out of auto-tracking** for that call. Instead, the component subscribes to all changes, runs `select` on each, and re-renders only when the returned array changes per-index (`Object.is` per element). In `select` mode the returned `state` is the raw state object, not a tracking proxy.

```tsx
function CountOnly() {
  const [state] = useBloc(CounterCubit, {
    select: (state) => [state.count],
  });
  return <span>{state.count}</span>;
}
```

The callback receives both the state and the bloc instance, so you can select from getters:

```tsx
const [state, cart] = useBloc(CartCubit, {
  select: (state, bloc) => [bloc.total, state.items.length],
});
```

:::caution[Keep `select` referentially stable]
`select` must be stable across renders — wrap it in `useCallback` or define it at module scope. A fresh function each render re-keys the subscription, which the underlying channel treats as a brand-new consumer (and defeats the optimization you reached for `select` to get).
:::

### When to reach for `select`

- You want re-renders driven by a **computed value** (a getter combining several fields) rather than every source path the getter reads.
- Auto-tracking records more paths than you want and you want to pin the dependency set explicitly, the way you would a `useMemo` dependency array.
- You want a value that is intentionally _coarser_ or _derived_ (e.g. `[bloc.isEmpty]` re-renders on the empty/non-empty boundary, not on every item added).

For the inverse case — a component that should never re-render because it only triggers actions — you don't need any option at all: a component that reads no state property records an empty path set and is never woken. See [Performance: split readers and writers](/react/performance#pattern-split-readers-and-writers).

## Choosing a mode

```text
Start with auto-tracking (the default — no option)
    │
    ├─ Component only calls methods, never reads state?
    │   └─ Read nothing from `state`; it won't re-render. No option needed.
    │
    ├─ Want re-renders driven by a computed/derived value,
    │  or to pin the dependency set by hand?
    │   └─ Use `select`
    │
    └─ Otherwise: auto-tracking is correct.
```

| Mode                    | Re-renders when                                | Best for                                    |
| ----------------------- | ---------------------------------------------- | ------------------------------------------- |
| Auto-tracking (default) | A tracked path changes                         | Almost everything                           |
| `select` (escape hatch) | A selected array element changes (`Object.is`) | Computed/derived values, explicit narrowing |
| No reads                | Never (empty path set)                         | Action-only components                      |

## See also

- [useBloc](/react/use-bloc) — the full options reference, including `select`
- [Performance](/react/performance) — re-render isolation, measuring, and list patterns
- [Mental Model](/guide/mental-model) — why proxy tracking beats selectors and memoization
- [Glossary](/guide/glossary) — auto-tracking, path, interner, and friends

---

# React Getting Started

> Install BlaC and connect a React component to a Cubit with useBloc, getting from install to a working counter and todo list.

Source: /react/getting-started/

BlaC's mental model is one line: **state lives in a class (a Cubit), and `useBloc` connects a component to it, re-rendering only when the data that component actually reads changes.** No providers to wire up, no reducers, no selectors required. For the full reasoning behind that design, see [Mental Model](/guide/mental-model).

This page gets you from install to a working counter and todo list. For the framework-agnostic introduction to Cubits, see [Getting Started](/guide/getting-started); this page focuses on the React binding.

## Installation

<Tabs syncKey="pkg">
<TabItem label="pnpm">

```bash
pnpm add @blac/core @blac/react
```

</TabItem>
<TabItem label="npm">

```bash
npm install @blac/core @blac/react
```

</TabItem>
</Tabs>

Requires React 18+ and TypeScript is recommended.

## Your first component

Two steps: define a Cubit that holds state and exposes methods to change it, then connect a component to it with `useBloc`. The snippet below is complete and copy-pasteable.

```tsx
import { Cubit } from '@blac/core';
import { useBloc } from '@blac/react';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 }); // initial state goes to super()
  }

  // Arrow-function fields keep `this` bound, so you can pass them straight
  // to onClick without wrapping. (See "common mistakes" below.)
  increment = () => this.emit({ count: this.state.count + 1 });
  decrement = () => this.update((s) => ({ count: s.count - 1 }));
}

function Counter() {
  const [state, counter] = useBloc(CounterCubit);

  return (
    <div>
      <p>Count: {state.count}</p>
      <button onClick={counter.increment}>+</button>
      <button onClick={counter.decrement}>-</button>
    </div>
  );
}
```

`useBloc` returns a tuple `[state, bloc]`:

- **state** — the current state, tracked for re-renders. Reading `state.count` here subscribes this component to `count` only; if the state grows other fields, changing them won't re-render `Counter`.
- **bloc** — the Cubit instance. Call its methods to drive state changes (`counter.increment()`).

There is no `<Provider>` to add at the root and nothing to register. The first component to call `useBloc(CounterCubit)` creates the instance; the last one to unmount disposes it.

### Three ways to update state

A Cubit exposes three mutation methods. Most code uses `emit`; reach for the others when they read better:

| Method   | Shape                         | Use when                                                |
| -------- | ----------------------------- | ------------------------------------------------------- |
| `emit`   | `emit(nextState)`             | You're replacing the whole state object.                |
| `update` | `update((prev) => nextState)` | The next state derives from the previous one.           |
| `patch`  | `patch(partial)`              | You want to deep-merge a few fields and leave the rest. |

:::caution[Common mistakes]

- **Regular methods lose `this`.** `increment() { ... }` (a normal method) loses its `this` binding when passed as `onClick={counter.increment}`. Use arrow-function class fields (`increment = () => { ... }`) as every example here does — they capture `this` at construction.
- **`emit` replaces, it does not merge.** `emit({ count: 1 })` on a state of `{ count, name }` drops `name`. To change only some fields, use `patch({ count: 1 })` (deep-merge) or spread inside `update((s) => ({ ...s, count: 1 }))`.
  :::

<details>
<summary>Where does the state live?</summary>

The instance is held in a global registry and reference-counted by `useBloc`. The "what just happened" details — acquire on mount, release on unmount, automatic disposal at zero refs — are covered in [Instance Management](/core/instance-management), and the reasoning behind the design is in [Mental Model](/guide/mental-model).

</details>

## Tracking modes at a glance

Auto-tracking is on by default and needs no configuration. The only knob is per call: pass a `select` function to `useBloc` to choose exactly what drives re-renders instead.

| Mode          | How to enable              | Re-renders when                                  |
| ------------- | -------------------------- | ------------------------------------------------ |
| Auto-tracking | Default (no `select`)      | A state path you read during render changes      |
| Manual select | `select: (s) => [s.count]` | A selected value changes (per-index `Object.is`) |

:::tip[There is no `autoTrack` flag and no required config]
Tracking is automatic and structural — driven by a render-time proxy, not by decorating fields or flipping a switch. `configureBlacReact` exists but currently has no options. Use `select` only when a computed value or explicit dependency list should drive re-renders. See [Dependency Tracking](/react/dependency-tracking) for the full model.
:::

## Instance modes at a glance

By default all components calling `useBloc(SameCubit)` share one instance. You can scope instances by `args` values or per mount:

| Mode                    | How to enable                                              | Behavior                                                |
| ----------------------- | ---------------------------------------------------------- | ------------------------------------------------------- |
| Shared                  | Default (no `args`)                                        | All components share one instance                       |
| Per-args (default hash) | `{ args: { id } }`                                         | Each distinct `args` value gets its own instance        |
| Per-args (custom key)   | `{ args: { id } }` + `static key = (a) => a.id`            | Only the keyed field forks instances; others ride along |
| Per-mount               | `{ args: { _id: useId() } }` + `static key = (a) => a._id` | Each component mount gets a private instance            |

See [Passing Inputs](/guide/inputs) for the full identity model and precedence.

## What's next?

Once the counter works, the natural next steps are reading state efficiently and giving blocs input:

- [useBloc](/react/use-bloc) — Full hook reference, options, and identity rules
- [Dependency Tracking](/react/dependency-tracking) — How smart re-renders work and their limits
- [Passing Inputs](/guide/inputs) — `args`, per-mount instances, and identity keying

## See also

- [Mental Model](/guide/mental-model) — Why BlaC works the way it does
- [Cubit](/core/cubit) — The state container: `emit`, `update`, `patch`, lifecycle
- [Performance](/react/performance) — Patterns and anti-patterns
- [Getting Started](/guide/getting-started) — Framework-agnostic introduction

---

# Performance

> BlaC's re-render isolation — each component re-renders only when the state it reads changes — plus patterns for measuring it and rendering large lists.

Source: /react/performance/

BlaC's performance story is **re-render isolation**: each component re-renders only when the specific state it reads changes, and components that read nothing don't re-render at all. This falls out of [auto-tracking](/react/dependency-tracking) — most apps get it for free. This page is for when you want to confirm it's working, push it further, or render large lists efficiently.

:::note[Where the gains come from]
There is no shared subscription that wakes every consumer. Each `useBloc` call records its own path set and the container wakes only the consumers whose paths intersect a change. So the cost of a state update scales with _how many components read the changed field_, not with _how many components use the container_. The deep "why" lives in [Mental Model](/guide/mental-model).
:::

## How auto-tracking helps

By default, `useBloc` wraps the returned state in a Proxy that records which properties your component reads. Only changes to those properties trigger re-renders.

```tsx
function UserName() {
  const [state] = useBloc(UserCubit);
  return <span>{state.name}</span>;
  // changes to state.email, state.avatar, etc. are ignored
}
```

This happens automatically — no selectors, no memoization, no configuration. For the exact recording rules (and the patterns that quietly over-track), see [Dependency Tracking](/react/dependency-tracking).

## Interactive before/after

The two rows below use the same `DashCubit` (three independent fields: temperature, humidity, pressure). The render counters show which components actually re-render on each button press.

**Top row — coarse read.** Each card uses `select: all three fields`. Any field change wakes every card — all three counters tick.

**Bottom row — per-field auto-tracking.** Each card calls `useBloc` with no `select` and reads only its own field. Auto-tracking records exactly which path was read, so only the card whose field changed re-renders — only that counter ticks.

<PerformanceDemo client:visible />

:::tip[What changed between "before" and "after"]
The only structural difference is the tracking mode: the coarse row passes a `select` that returns all three fields; the fine row omits `select` and reads only one field per component. No `React.memo`, no `useMemo` — just not over-reading state.
:::

## Measuring re-render isolation

Before optimizing, confirm where the re-renders actually are. Three approaches, cheapest first:

**1. Inline render counter (quick, local).**

```tsx
function MyComponent() {
  const renderCount = useRef(0);
  renderCount.current++;

  const [state] = useBloc(MyCubit);
  return (
    <div>
      <span>Renders: {renderCount.current}</span>
      {/* ... */}
    </div>
  );
}
```

:::tip[Count in the render body, not in an effect]
Increment the ref in the render body. The body runs on every render; `useEffect` runs _after_ commit and can be skipped or batched, so a ref bumped there under-counts. Reading it in the body gives the true render count.
:::

**2. React DevTools Profiler (visual, whole-tree).** Record an interaction and look for components that highlight (re-rendered) when they shouldn't have. A component that lights up on a state change it doesn't read is over-tracking — usually a spread or a whole-object read (see [Common mistakes](#common-mistakes)).

**3. BlaC DevTools (state-change-centric).** The [BlaC DevTools](/plugins/devtools) show which instances are live and when each state change fires, so you can correlate a render spike with the emit that caused it and spot unexpected instance churn. The [Logging Plugin](/plugins/logging) additionally warns on rapid create/destroy lifecycles in the console.

## Pattern: Split readers and writers

Separate components that _display_ state from components that only _trigger_ actions. A component that reads no state property records an empty path set and is therefore never woken by state changes — no option required.

```tsx
function Counter() {
  return (
    <>
      <CountDisplay />
      <CountButtons />
    </>
  );
}

function CountDisplay() {
  const [state] = useBloc(CounterCubit);
  return <span>{state.count}</span>;
}

function CountButtons() {
  // Destructures only the bloc instance — never touches `state`.
  const [, counter] = useBloc(CounterCubit);
  return (
    <>
      <button onClick={counter.increment}>+</button>
      <button onClick={counter.decrement}>-</button>
    </>
  );
}
```

`CountButtons` never re-renders on count changes because it reads nothing from `state`. The recipe form of this pattern lives in [Patterns: action-only components](/guide/patterns); this page owns the _why_.

## Pattern: `select` for coarse, derived control

When you want re-renders driven by a **computed value** rather than the raw fields auto-tracking would pick up, reach for `select`. It opts out of auto-tracking and re-renders only when the returned array changes per-index.

```ts
select?: (state: S, bloc: T) => unknown[]
```

| Parameter | Type | Required | Description                                                        |
| --------- | ---- | -------- | ------------------------------------------------------------------ |
| `state`   | `S`  | yes      | Current raw state (not a proxy in `select` mode).                  |
| `bloc`    | `T`  | yes      | The bloc instance; use to include getters in the dependency array. |

**Returns:** `unknown[]` — compared per-index via `Object.is`. The component re-renders only when an element changes.

**Behavior.** Disables auto-tracking for that `useBloc` call. The selector runs on every state change and the component re-renders only when the returned array changes. Keep it referentially stable (module-scope or `useCallback`).

```tsx
function CartBadge() {
  const [, cart] = useBloc(CartCubit, {
    select: (_, bloc) => [bloc.isEmpty],
  });
  return cart.isEmpty ? null : <Badge />;
}
```

This re-renders only when `isEmpty` flips, not on every item added. Keep `select` referentially stable (`useCallback` or module scope) — see [Dependency Tracking: the `select` escape hatch](/react/dependency-tracking#the-select-escape-hatch).

:::tip[Auto-track vs `select`: when to narrow vs derive]
Reach for `select` to depend on a **derived/computed** value or to pin an explicit dependency set. To make a component _not_ re-render, don't pass an option — just don't read state. There is no `autoTrack` flag; the mode is chosen by the presence or absence of `select`.
:::

## Pattern: Getters as computed properties

Define getters on your Cubit for derived values. A getter centralizes the computation and keeps components thin.

```ts
class CartCubit extends Cubit<{ items: CartItem[] }> {
  get total() {
    return this.state.items.reduce((sum, i) => sum + i.price, 0);
  }
}
```

:::tip[Getters auto-track in render]
The `bloc` returned by `useBloc` is also proxied for getters. When a render reads `cart.total`, the getter runs with a tracked `this.state`, so its source paths join the component's interest set automatically:

```tsx
function CartTotal() {
  const [, cart] = useBloc(CartCubit);
  return <span>${cart.total}</span>;
}
```

Use `select` when you want the getter's return value to be the boundary instead of the source paths. For example, this wakes only when `total` changes value:

```tsx
function CartTotalSelected() {
  const [, cart] = useBloc(CartCubit, {
    select: (_, bloc) => [bloc.total],
  });
  return <span>${cart.total}</span>;
}
```

Auto-tracking wakes when one of the getter's tracked source paths changes; `select` wakes when the selected getter result changes by `Object.is`. Either is preferable to reading the raw array and reducing it inside the component.
:::

## List-rendering patterns

Iteration **coarsens**: `.map`/`.find`/`for..of` record the array's entry path (`items`) but not per-index paths, and their callbacks receive raw values. So a component that maps over `state.items` re-renders whenever the array changes — including when a single item's field changes (which produces a new array via immutable update).

For long lists where individual rows update independently, isolate each row in its own component that reads only its own item. There are two idiomatic shapes:

**Map to keys, render rows by id.** The list reads the ids (changes when items are added/removed/reordered); each row reads its own item.

```tsx
function TodoList() {
  const [state] = useBloc(TodoCubit);
  return (
    <ul>
      {state.items.map((item) => (
        <TodoRow key={item.id} id={item.id} />
      ))}
    </ul>
  );
}

function TodoRow({ id }: { id: string }) {
  // `args` keys identity; each row instance reads only its own item.
  const [item] = useBloc(TodoItemCubit, { args: { id } });
  return <li className={item.done ? 'done' : ''}>{item.text}</li>;
}
```

Here each row's `TodoItemCubit` is keyed by `args: { id }`, so toggling one row wakes only that row. See [Passing Inputs](/guide/inputs) for the identity model behind `args`.

**Or pass the item down and let the parent own the data.** When a single Cubit holds the list, render rows from a `select` that pins the row's own slice, so a row re-renders only when _its_ item changes:

```tsx
function TodoRow({ id }: { id: string }) {
  const [, todos] = useBloc(TodoCubit, {
    select: (state) => [state.items.find((i) => i.id === id)],
  });
  const item = todos.state.items.find((i) => i.id === id)!;
  return <li className={item.done ? 'done' : ''}>{item.text}</li>;
}
```

:::caution[Stable keys, stable order]
Use a stable `key` (an id, never the array index) so React reconciles rows correctly across reorders, and prefer immutable updates that replace only the changed item so unaffected rows keep reference-equal data.
:::

## Pattern: Keep most state flat

Auto-tracking works at any depth, and `patch` accepts a `DeepPartial<S>` so deep updates are ergonomic — depth is **supported**. But flatter state is still usually the better default:

- Each level of nesting is one more proxy to create on read and one more path segment to diff.
- Leaf isolation only helps if siblings live at the same level; over-nesting groups unrelated fields under a shared parent, so a whole-object read of that parent over-tracks.

```ts
// Prefer this
interface UserState {
  name: string;
  email: string;
  avatarUrl: string;
}

// Over this
interface UserState {
  profile: {
    personal: { name: string; contact: { email: string } };
    media: { avatarUrl: string };
  };
}
```

:::note[Nesting isn't banned]
Reach for nesting when the structure is _meaningful_ — a list of records, a normalized entity map, a genuinely tree-shaped domain. The guidance is "don't nest for the sake of organizing flat fields," not "never nest." Deep `patch` exists precisely so that legitimately nested state stays easy to update.
:::

## Common mistakes

These all manifest the same way in the Profiler: a component re-renders on a change it doesn't display.

:::caution[Over-tracking anti-patterns]

- **Spreading the whole state** tracks every property.

  ```tsx
  // Bad: tracks every property of state
  return <ProfileCard {...state} />;
  // Better: pass only what's rendered
  return <ProfileCard name={state.name} avatar={state.avatarUrl} />;
  ```

- **Reading the whole array to compute a boolean** over-tracks the array's contents. Track the narrow thing you actually need (`state.items.length`), or select the derived value so you only wake on the boundary:

  ```tsx
  // Tracks the full array on every change:
  return <Icon badge={state.items.length > 0} />;
  // Wakes only when empty/non-empty flips (getter via select):
  const [, cart] = useBloc(CartCubit, { select: (_, b) => [b.isEmpty] });
  return <Icon badge={!cart.isEmpty} />;
  ```

  Reading `!cart.isEmpty` without `select` also tracks correctly, but it wakes on the getter's source paths. Use `select` when only the empty/non-empty boundary should re-render. See [Getters as computed properties](#pattern-getters-as-computed-properties).

- **Reading a whole object when you need one field** wakes on any sibling change. Read the leaf (`state.user.name`), not the object (`state.user`).
- **Destructuring then drilling off the raw value** — `const { user } = state; user.name` tracks `user`, not `user.name`. Drill through the proxy: `state.user.name`.
  :::

## Pattern: Lifecycle hooks instead of useEffect

Use `onMount` and `onUnmount` to run side effects tied to the component lifecycle without writing `useEffect`:

```tsx
function Feed() {
  const [state] = useBloc(FeedCubit, {
    onMount: (feed) => feed.load('latest'),
    onUnmount: (feed) => feed.cancelPending(),
  });

  if (state.status === 'loading') return <Spinner />;
  return <ArticleList articles={state.articles} />;
}
```

This keeps the component body clean and avoids the usual `useEffect` dependency-array pitfalls. `onMount` fires after the bloc is acquired; `onUnmount` fires _before_ the registry releases its ref, so the bloc is still alive when it runs.

## See also

- [Dependency Tracking](/react/dependency-tracking) — the recording rules that drive all of the above
- [useBloc](/react/use-bloc) — the full options reference (`select`, `args`, `onMount`/`onUnmount`)
- [DevTools](/plugins/devtools) — inspect live instances and state-change timing
- [Best Practices](/guide/best-practices) — when to narrow, derive, or split, as principles

## Troubleshooting

For the full FAQ see [Troubleshooting](/guide/troubleshooting). Below are the performance-specific problems.

### Getter wakes more often than expected

**Symptom:** A component reads `bloc.total` (a getter) and re-renders whenever its source paths change, even when the computed total is the same.

**Cause:** Auto-tracking records the getter's underlying `this.state` reads. That is usually what you want, but it means the source paths, not the computed return value, drive wakeups.

**Fix:** Depend on the getter explicitly with `select` when the computed value should gate re-renders:

```tsx
function CartTotal() {
  const [, cart] = useBloc(CartCubit, {
    select: (_, bloc) => [bloc.total],
  });
  return <span>${cart.total}</span>;
}
```

Auto-tracking is still correct for the default case: `const [, cart] = useBloc(CartCubit); return <span>{cart.total}</span>;`. See [Getters as computed properties](#pattern-getters-as-computed-properties) above.

### `select` re-keys / re-subscribes every render

**Symptom:** The component re-renders on every state change regardless of what `select` returns, or you see unexpected subscription churn in DevTools.

**Cause:** A fresh selector function is passed each render. The hook treats a new function identity as a new consumer, re-keying the subscription.

**Fix:** Wrap the selector in `useCallback` or define it at module scope so the reference is stable:

```tsx
const selectTotal = (state: CartState, bloc: CartCubit) => [bloc.total];

function CartBadge() {
  const [, cart] = useBloc(CartCubit, { select: selectTotal });
  return cart.isEmpty ? null : <Badge />;
}
```

See [Troubleshooting: `select` re-keying](/guide/troubleshooting#stale-values-in-callbacks) and [`useBloc`: `select`](/react/use-bloc#select).

---

# Preact

> The planned @blac/preact binding provides the same useBloc hook and API as @blac/react over the same @blac/core engine.

Source: /react/preact/

:::caution[Not yet published]
A dedicated `@blac/preact` package is **planned but not yet released** — it does not currently ship in this repo. This page describes the intended binding so the design is on record; the import paths and `configureBlacPreact` below are not available until the package lands. In the meantime, `@blac/core` is framework-agnostic and Preact components can drive blocs through [`watch`](/core/watch). Track the package status before depending on the snippets here.
:::

The planned `@blac/preact` package will provide the same `useBloc` hook with the same API as `@blac/react`, over the same `@blac/core` engine. If you already know the React binding, there is nothing new to learn — only the import changes.

:::tip[New to BlaC?]
Start with [Getting Started](/react/getting-started) and [useBloc](/react/use-bloc) using the React examples — every concept transfers verbatim. This page covers only what is Preact-specific.
:::

## Installation

<Tabs syncKey="pkg">
<TabItem label="pnpm">

```bash
pnpm add @blac/core @blac/preact
```

</TabItem>
<TabItem label="npm">

```bash
npm install @blac/core @blac/preact
```

</TabItem>
</Tabs>

Requires Preact 10.x. `@blac/core` is a peer dependency.

## Usage

```tsx
import { useBloc } from '@blac/preact';
import { Cubit } from '@blac/core';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  increment = () => this.patch({ count: this.state.count + 1 });
}

function Counter() {
  const [state, counter] = useBloc(CounterCubit);
  return (
    <div>
      <p>{state.count}</p>
      <button onClick={counter.increment}>+</button>
    </div>
  );
}
```

Auto-tracking works exactly as it does in React: `state.count` is recorded during render, so this component re-renders only when `count` changes. See [Dependency Tracking](/react/dependency-tracking) for the recording rules.

## API

The hook signature, return tuple, and options are identical to the React version:

```ts
const [state, bloc, ref] = useBloc(MyCubit, {
  args: { id }, // typed; required when the bloc declares Args; derives identity
  select: (state, bloc) => [bloc.someGetter], // re-render selector (opts out of auto-track)
  onMount: (bloc) => {
    /* runs after acquire */
  },
  onUnmount: (bloc) => {
    /* runs before release */
  },
});
```

`@blac/preact` is built for parity with `@blac/react`, so the input model is the same: typed `args` for instance identity, the per-consumer `deps` lane on the container, and the `select` re-render selector. Like React, `deps` is **not** a `useBloc` option; wire it from an effect as described in [Passing Inputs](/guide/inputs). There is no `autoTrack` option in either binding — a component re-renders based on what it reads, or on `select` when you provide one; a component that reads no state never re-renders. For the complete, canonical options reference, see [useBloc](/react/use-bloc).

## Global configuration

```ts
import { configureBlacPreact } from '@blac/preact';

configureBlacPreact({
  // Reserved for forwards-compatible knobs; currently no options.
});
```

`configureBlacPreact` mirrors `configureBlacReact`: both configuration surfaces are intentionally empty today. The hook's tracking model is fixed — auto-tracking when `select` is omitted, selector-driven re-renders when it is provided — and is not configurable.

## Differences from React

- The hook is built against Preact's hook implementations rather than React's; the subscription and tracking model is otherwise identical.
- Everything else — `@blac/core`, the registry, ref-counting, plugins, and the tracking engine in `@dirtytalk/structural` — is shared between the two bindings. State containers themselves are framework-agnostic: the _same_ Cubit class works under React, Preact, or no framework at all (via [watch](/core/watch)).

## See also

- [Getting Started](/react/getting-started) — the quickstart; all examples transfer to Preact
- [useBloc](/react/use-bloc) — the canonical hook and options reference
- [Passing Inputs](/guide/inputs) — `args`, `deps`, and instance identity
- [Dependency Tracking](/react/dependency-tracking) — how auto-tracking decides re-renders

---

# useBloc

> The useBloc hook connects a React component to a state container, returning the current state, the bloc instance, and a ref.

Source: /react/use-bloc/

The `useBloc` hook connects a React component to a state container. It acquires (or creates) a bloc instance, subscribes to state changes, and returns the current state, the bloc instance, and an internal ref.

## Signature

```ts
function useBloc<T extends StateContainerConstructor>(
  BlocClass: T,
  options?: UseBlocOptions<T>,
): [
  state: ExtractState<T>,
  bloc: InstanceReadonlyState<T>,
  ref: RefObject<ComponentRef>,
];
```

| Parameter   | Type                                  | Required | Description                                            |
| ----------- | ------------------------------------- | -------- | ------------------------------------------------------ |
| `BlocClass` | `T extends StateContainerConstructor` | yes      | The state-container class to acquire.                  |
| `options`   | `UseBlocOptions<T>`                   | no       | Optional configuration: see [Options](#options) below. |

**Returns:** a `[state, bloc, ref]` tuple.

| Index | Name    | Description                                                                                                                                                                                                                                |
| ----- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 0     | `state` | Current state. In auto-tracking mode (the default) this is a tracking proxy that records which paths you read so re-renders stay scoped to them. In `select` mode it's the raw state object.                                               |
| 1     | `bloc`  | A per-consumer proxy for the Cubit instance. Call its methods to drive changes (`bloc.increment()`). Getters read during render auto-track because `this.state` inside the getter is routed through the current state proxy. |
| 2     | `ref`   | An advanced-use ref object for component-bloc binding. You almost never need it; destructure just the first two values.                                                                                                                    |

Typically you destructure just the first two:

```tsx
const [state, counter] = useBloc(CounterCubit);
```

## Tracking modes

By default, `useBloc` uses auto-tracking to keep re-renders scoped: the hook wraps `state` in a tracking proxy that records which paths you actually read, and the component re-renders only when one of those paths changes. This means two components consuming the same state can read different slices — one re-renders when `left` changes, the other only when `right` changes.

**Minimal counter — wired through `useBloc`:**

<UseBlocDemo client:visible />

## Options

`useBloc` accepts one optional options object. `UseBlocOptions` has exactly four keys — reach for the one that matches your need:

| Option      | Type                               | Required            | Description                                                                                        |
| ----------- | ---------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------- |
| `args`      | the bloc's `Args` type             | when `Args != void` | Typed construction data; derives instance identity. Required when declared, forbidden when `void`. |
| `select`    | `(state: S, bloc: InstanceReadonlyState<T>) => unknown[]` | no                  | Explicit dependency selector; disables auto-tracking.                                              |
| `onMount`   | `(bloc: InstanceType<T>) => void`  | no                  | Called once when the component mounts with the bloc instance.                                      |
| `onUnmount` | `(bloc: InstanceType<T>) => void`  | no                  | Called when the component unmounts (bloc still alive at this point).                               |

:::tip[These four are the entire option surface]
`UseBlocOptions` has exactly these keys. Two things people expect that are **not** options here:

- **Per-mount instances** — pass a per-mount unique value in `args` (e.g. `args: { _id: useId() }`) with a matching `static key` on the class so each mount gets its own private instance (see [`args`](#args) and [Passing Inputs](/guide/inputs)).
- **Non-serializable handles** (refs, callbacks) are a bloc-level `Deps` concept, not a `useBloc` option; see [Injecting handles (`deps`)](#injecting-handles-deps).

There is no `autoTrack` flag — auto-tracking is the default and you opt out with `select`.
:::

### `args`

```ts
args: ExtractArgs<T>;
```

**Required when the bloc declares `Args != void`; forbidden (type `never`) when `void`.**

**Returns:** `void` (the option feeds the bloc's `init(args)` before the first snapshot).

**Behavior.** Pass typed construction data to the bloc. Args are forwarded to the bloc's `init(args)` method before the first state snapshot, and they derive the instance identity by default — different args ⇒ different instance. Only serializable values are permitted; non-serializable handles (refs, callbacks, DOM elements) must go in the bloc's `Deps` instead.

```tsx
class UserCardCubit extends Cubit<UserCardState, { userId: string }> {
  protected init(args: { userId: string }) {
    void this.loadUser(args.userId);
  }
}

// args is required and type-checked; omitting it is a compile error
const [state] = useBloc(UserCardCubit, { args: { userId } });
```

- **Identity:** different `args` values produce different instances. By default identity is the structural hash of all args. Override with `static key` on the class.
- **Serializable only** — refs, callbacks, and DOM elements must not go in `args` (they'd produce a new instance every render). Put them in the bloc's `Deps` instead — see [Injecting handles (`deps`)](#injecting-handles-deps).
- **Per-component private instances** — to give each mount its own instance (disposed on unmount), include a per-mount unique value in `args` and declare `static key` on the class so it becomes the identity key:

```tsx
class FormCubit extends Cubit<FormState, { _id: string }> {
  static key = (a: { _id: string }) => a._id;
}

// each mount of this component gets its own FormCubit instance
const _id = useId();
const [state, cubit] = useBloc(FormCubit, { args: { ...options, _id } });
```

See [Passing Inputs](/guide/inputs) for the full identity model.

### `select`

```ts
select?: (state: ExtractState<T>, bloc: InstanceReadonlyState<T>) => unknown[]
```

**Returns:** `void` (the hook uses the returned array to decide whether to re-render).

**Behavior.** Provide an explicit dependency array. The component re-renders only when the shallow-compared values change (per-index `Object.is`). Setting this disables auto-tracking for that call.

```tsx
const [state] = useBloc(UserCubit, {
  select: (state) => [state.name, state.email],
});
```

The function receives both state and the bloc instance, so you can use getters as the explicit re-render boundary:

```tsx
const [state, cart] = useBloc(CartCubit, {
  select: (state, bloc) => [bloc.total, state.items.length],
});
```

:::caution[Keep the selector stable]
Keep the selector referentially stable across renders — wrap it in `useCallback` or define it at module scope. A new function identity each render re-keys the subscription, which the underlying channel treats as a new consumer.
:::

### `onMount`

```ts
onMount?: (bloc: InstanceType<T>) => void
```

**Returns:** `void`.

**Behavior.** Called once in a mount effect after the bloc is acquired. Use it to kick off work tied to this component's lifecycle (e.g. fetch on mount).

```tsx
const [state] = useBloc(DataCubit, {
  onMount: (bloc) => bloc.fetchData(),
});
```

### `onUnmount`

```ts
onUnmount?: (bloc: InstanceType<T>) => void
```

**Returns:** `void`.

**Behavior.** Called when the component unmounts, _before_ the registry releases its ref — so the bloc is still alive when this runs. Use it to clean up subscriptions or cancel pending work.

```tsx
const [state] = useBloc(StreamCubit, {
  onUnmount: (bloc) => bloc.disconnect(),
});
```

## Injecting handles (`deps`)

Non-serializable handles (refs, stable callbacks, controller instances) are **not** a `useBloc` option. They are a bloc-level concept: the bloc declares a `Deps` type and reads from `this.deps.x` (which may be `undefined` — always guard).

```ts
class FileUploadCubit extends Cubit<
  UploadState,
  { endpoint: string },
  { inputRef?: RefObject<HTMLInputElement>; onComplete?: () => void }
> {
  async upload() {
    this.deps.inputRef?.current?.click?.();
    // ... perform upload ...
    this.deps.onComplete?.();
  }
}
```

For handles that need to trigger initialization on arrival (e.g. a canvas ref), implement `onDepsChanged` on the bloc — see [Cubit](/core/cubit). For how `deps` are supplied and merged across consumers, and the full input model, see [Passing Inputs](/guide/inputs).

:::tip[Avoid raw inline callbacks as handles]
An inline callback (`onComplete={() => …}`) gets a new identity every render, so a bloc that captured it holds a stale closure. Prefer:

1. **Callback inversion (best):** expose state; let the component call its fresh callback from its own `useEffect`.
2. **Stabilize with `useCallback`** before passing.
3. **Push via an event** — call a bloc method from an effect.
   :::

## Identity and keying

This is the canonical instance-identity precedence for `useBloc`. Other pages defer to this list:

1. **`<BlocProvider>` context args** — inherited from a parent provider when present
2. **`static key(args)`** — class-supplied key derived from `args`
3. **Structural hash of `args`** — default when the bloc declares `Args` and no `key` is set
4. **`'default'`** — singleton fallback when the bloc has no `args`, no key, and no provider

Blocs declare explicit identity via a static property:

```ts
class DocumentCubit extends Cubit<
  DocState,
  { docId: string; readonly: boolean }
> {
  static key = (args: DocumentCubit['args']) => args.docId;
  // docId keys the instance; readonly is config that rides along but doesn't fork instances
}
```

A note on `<BlocProvider>`: it supplies `args` to descendant `useBloc` calls that don't pass their own, so a subtree can share a scoped instance without threading data through props.

```tsx
import { BlocProvider } from '@blac/react';

<BlocProvider bloc={CustomerCubit} args={{ customerId: 'customer-42' }}>
  <CustomerView />{' '}
  {/* useBloc(CustomerCubit) here inherits args from the provider */}
</BlocProvider>;
```

See [Passing Inputs](/guide/inputs) for the full decision matrix.

:::caution[Common mistakes]

- **Passing a fresh `select` each render.** The selector must be referentially stable (wrap it in `useCallback`). A new function identity each render re-keys the subscription, which the underlying channel treats as a new consumer.
- **Putting non-serializable values in `args`.** Refs, callbacks, and DOM nodes change identity every render, so a fresh `args` object produces a brand-new instance each time (and `args` must be JSON-serializable). Use the bloc's `Deps` for handles — see [Injecting handles (`deps`)](#injecting-handles-deps).
- **Expecting an `autoTrack`, `autoInstance`, or `instanceId` option.** None of these exist. Opt out of tracking with `select`; get per-mount instances by including a per-mount unique value in `args` with a matching `static key`.
  :::

## Lifecycle

1. **Mount:** `acquire(BlocClass)` creates or retrieves the instance, incrementing the ref count
2. **`init(args)` called** (once, when the instance is first created) before the first state snapshot
3. **Subscribe:** the hook subscribes to the bloc's channel using the selected tracking mode (auto-track or `select`)
4. **`onMount(bloc)` fires** in a mount effect, after the bloc is acquired
5. **Re-render:** only triggered when a tracked state path or a `select` value changes
6. **Unmount:** `onUnmount(bloc)` fires (bloc still alive), then `release(BlocClass)` decrements the ref count. At zero, the instance is disposed unless the class is [`keepAlive`](/core/configuration)

For the registry mechanics behind acquire/release and ref counting, see [Instance Management](/core/instance-management).

## How re-renders are scheduled

`useBloc` subscribes to the bloc's path-scoped channel and triggers a re-render through a `useReducer` dispatch — React's normal update path — whenever a tracked path (or `select` value) changes. State is read directly from the bloc during render, so reads are consistent within a single render. The hook does not use `useSyncExternalStore`.

## See also

- [Passing Inputs](/guide/inputs) — `args`, `deps`, per-mount isolation, and the identity model
- [Dependency Tracking](/react/dependency-tracking) — How auto-tracking decides what re-renders
- [Performance](/react/performance) — Splitting readers and writers, anti-patterns
- [Cubit](/core/cubit) — The state container these options connect to

## Troubleshooting

For the full FAQ see [Troubleshooting](/guide/troubleshooting). Below are the problems most specific to `useBloc`.

### Component re-renders too often

**Symptom:** A component re-renders on state changes it doesn't display.

**Cause:** Reading a coarse path (whole object or array) instead of the specific leaf you render. A spread (`{...state}`) or an early destructure before drilling into a path widens the tracked set.

**Fix:** Read exactly the leaf you render through the live proxy, or use `select` to depend on a derived value:

```tsx
// Tracks every property — any change re-renders:
const { user } = state;
return <span>{user.name}</span>;

// Tracks only user.name:
return <span>{state.user.name}</span>;

// Or: select a derived/computed value so re-renders are gated on the boundary
```

See [Dependency Tracking](/react/dependency-tracking) for the full recording rules.

### State leaks between component mounts

**Symptom:** A component mounts, unmounts, and then remounts with stale state from the previous mount — or two independent mounts share state unexpectedly.

**Cause:** Both mounts resolve to the same instance key (`'default'` when there are no `args`). When the first mount releases, the instance disposes and the remount creates a fresh one — but if `keepAlive` is set, the instance persists and the remount picks it back up.

**Fix:** For one private instance per mount, include a per-mount unique value in `args` and use `static key` to make it the identity key. `useId()` returns a stable-per-mount value:

```tsx
class WidgetCubit extends Cubit<WidgetState, { _id: string }> {
  static key = (a: { _id: string }) => a._id;
}

const _id = useId();
const [state] = useBloc(WidgetCubit, { args: { _id } });
```

See [Instance Management](/core/instance-management) and [Passing Inputs](/guide/inputs).

### `autoTrack`, `autoInstance`, `isolated`, or `instanceId` option not found

**Symptom:** TypeScript errors or runtime `undefined` when passing `autoTrack`, `autoInstance`, `isolated`, `instanceId`, or `dependencies` to `useBloc`.

**Cause:** None of these are `useBloc` options. `UseBlocOptions` has exactly four keys: `args`, `select`, `onMount`, `onUnmount`.

**Fix:**

| Tried                       | What to use instead                                                                  |
| --------------------------- | ------------------------------------------------------------------------------------ |
| `autoTrack`                 | Auto-tracking is the default; opt out with `select`                                  |
| `autoInstance` / `isolated` | Include a per-mount unique value in `args` with `static key` for per-mount instances |
| `instanceId`                | Use `args`-derived identity; include a unique value in `args` + `static key`         |
| `dependencies`              | Use `select`                                                                         |

---

# DevTools

> A full DevTools suite — in-app overlay, Chrome DevTools panel, and console API — for inspecting live instances, state diffs, event timelines, and time-travel.

Source: /plugins/devtools/

BlaC ships with a full DevTools suite: an in-app overlay, a Chrome DevTools panel, and a console API. Together they let you inspect live instances, view state diffs, browse event timelines, and time-travel to previous states.

DevTools is delivered as a [plugin](/plugins/overview): once installed, it observes every state container from the outside, so there is nothing to wire up per bloc. Keep it scoped to `environment: 'development'` — it tracks state snapshots and event history, which you do not want in a production bundle.

## Packages

| Package                  | What it does                                                 |
| ------------------------ | ------------------------------------------------------------ |
| `@blac/devtools-connect` | Core plugin that tracks instances and exposes the global API |
| `@blac/devtools-ui`      | React UI components (floating overlay and panel)             |
| BlaC Chrome Extension    | Chrome DevTools panel that connects automatically            |

## Setup

### 1. Install the plugin

```bash
pnpm add @blac/devtools-connect
```

```ts
import { getPluginManager } from '@blac/core';
import { createDevToolsBrowserPlugin } from '@blac/devtools-connect';

getPluginManager().install(createDevToolsBrowserPlugin(), {
  environment: 'development',
});
```

This is the minimum setup. The plugin starts tracking all state containers and exposes `window.__BLAC_DEVTOOLS__` for programmatic access.

### 2. Add the in-app UI (recommended)

```bash
pnpm add @blac/devtools-ui
```

```tsx
import { BlacDevtoolsUi } from '@blac/devtools-ui';

function App() {
  return (
    <>
      <YourApp />
      <BlacDevtoolsUi />
    </>
  );
}
```

Drop `<BlacDevtoolsUi />` anywhere in your tree. It renders a draggable floating overlay that you toggle with **Alt+D** (or by dispatching a `blac-devtools-toggle` custom event).

### 3. Chrome extension (optional)

Install the BlaC Chrome Extension from the Chrome Web Store (or build from `apps/devtools-extension/`). Once installed, a **BlaC** tab appears in Chrome DevTools alongside Elements, Console, etc.

The extension connects automatically when the browser plugin is active — no extra configuration needed. It stays in sync across page reloads.

## Plugin configuration

```ts
createDevToolsBrowserPlugin({
  enabled: true, // kill switch (default: true)
  maxInstances: 2000, // max tracked instances before FIFO eviction
  maxSnapshots: 20, // state snapshots kept per instance
});
```

## What you can do

### Inspect instances

The Instances tab lists every active state container with everything you need to identify and triage it at a glance:

- **Class name + instance ID** with a state preview.
- **`args`** that keyed the instance — surfaced inline so two instances of the same class with different `args` are easy to tell apart.
- **Ref holders** (`R:n`) — every active holder of the instance: each `useBloc` mount (which acquires a ref) plus any manual [`acquire()`](/core/instance-management).
- **Hydration badge** — `HYDRATING` while state is being restored by the persistence plugin, or `ERR` if hydration failed.
- **Insight pills** — inline warnings when a threshold trips: large state size (≥ 50 KB) or a high update rate (≥ 30 updates / 10 s).

Click an instance to see its full state tree and a side-by-side diff history.

:::tip[Screenshot pending]
The Instances tab shows every active bloc. Each row displays the class name, a truncated instance ID, the current ref count (`R:2`), and a compact JSON preview of the current state. A yellow insight pill appears on a bloc when its update rate exceeds 30/10 s.
_A human will capture this from the running examples app and drop the file at `apps/docs/public/devtools-instances.png` (then re-add the `<img>`)._
:::

:::note[Reading `R:n`]
`R:n` comes straight from the registry's [ref-counting model](/core/instance-management). Every `useBloc` mount acquires a ref, and every manual `acquire()` adds one; the bloc stays alive while the count is above zero. If an instance lingers after all its components have unmounted, a stray `acquire()` without a matching `release()` (or `keepAlive: true`) is the usual cause.
:::

### View state diffs

When you select an instance, the detail panel shows a side-by-side diff of the previous and current state. Each state change is recorded with a timestamp and the call stack that triggered it.

:::tip[Screenshot pending]
The detail panel shows a side-by-side diff for the selected bloc. The left column (red) is the previous state; the right column (green) is the current state. Changed keys are highlighted, with a timestamp and abbreviated call stack below each diff entry.
_Drop the file at `apps/docs/public/devtools-state-diff.png` (then re-add the `<img>`)._
:::

### Browse the event log

The Logs tab shows a timeline of all lifecycle events:

| Event               | When                                                                              |
| ------------------- | --------------------------------------------------------------------------------- |
| `instance-created`  | A state container is created                                                      |
| `instance-updated`  | State changes (coalesced per animation frame — one entry per rAF, not per emit)   |
| `instance-disposed` | A state container is disposed                                                     |
| `refs-changed`      | The set of ref holders changes (a `useBloc` mount/unmount or `acquire`/`release`) |
| `deps-changed`      | The merged `deps` view changes — payload carries `previousDeps` and `currentDeps` |

:::note[`instance-updated` batching]
State changes are coalesced once per animation frame: if a bloc emits several times before the next rAF tick, the Logs tab records a single `instance-updated` entry with the final state. This keeps the timeline readable during high-frequency updates. The full snapshot history in the detail panel still captures every intermediate state.
:::

:::tip[Screenshot pending]
The Logs tab lists events with a type badge, a timestamp, and a collapsible payload. The `refs-changed` event shows the previous and current ref count; `instance-updated` shows the coalesced final state for that frame.
_Drop the file at `apps/docs/public/devtools-event-log.png` (then re-add the `<img>`)._
:::

### Time-travel

Click any snapshot in the state history to restore the instance to that point. This calls `emit` on the instance with the stored state, so your components update in real time.

:::caution[Time-travel bypasses your action logic]
Because time-travel calls `emit` directly with a stored snapshot, it skips the methods that normally produce that state. Anything those methods also do — network requests, writes to other blocs, external side effects — does **not** replay. The bloc's in-memory state jumps, but derived or external systems can desync. Treat time-travel as a UI-debugging aid, not a way to re-run application logic.
:::

### Search and filter

Use the search bar to filter instances by class name. Useful when you have dozens of active containers.

## Keyboard shortcut

Press **Alt+D** to toggle the in-app DevTools overlay.

## Excluding instances from DevTools

High-frequency or internal state containers can be hidden:

```ts twoslash
import { blac, Cubit } from '@blac/core';

@blac({ excludeFromDevTools: true })
class AnimationCubit extends Cubit<{ frame: number }> {
  constructor() {
    super({ frame: 0 });
  }
}
```

The DevTools plugin skips these instances entirely — no tracking overhead. `excludeFromDevTools` is one of the [`blac()` configuration options](/core/configuration); this page shows it in use, but [Configuration](/core/configuration) documents the full option set.

## Console API

With the plugin installed, `window.__BLAC_DEVTOOLS__` is available in the browser console:

```ts
// List all active instances
__BLAC_DEVTOOLS__.getInstances();

// Full state dump with snapshot history
__BLAC_DEVTOOLS__.getFullState();

// Event timeline
__BLAC_DEVTOOLS__.getEventHistory();

// Subscribe to real-time events
const unsub = __BLAC_DEVTOOLS__.subscribe((event) => {
  console.log(event.type, event.data);
});

// Time-travel an instance to a previous state
__BLAC_DEVTOOLS__.timeTravel(instanceId, previousState);

// Check plugin version
__BLAC_DEVTOOLS__.getVersion();
```

## Programmatic access

You can also interact with the plugin instance directly in your code:

```ts
const devtools = createDevToolsBrowserPlugin();
getPluginManager().install(devtools, { environment: 'development' });

devtools.subscribe((event) => {
  // { type, timestamp, data }
});

devtools.getInstances();
devtools.getFullState();
devtools.getEventHistory();
```

## See also

- [Plugin Overview](/plugins/overview) — the plugin catalog and the install API
- [Logging Plugin](/plugins/logging) — passive console/CI logging; complements DevTools
- [Instance Management](/core/instance-management) — the ref-counting model behind `R:n`
- [Configuration](/core/configuration) — `excludeFromDevTools` and the other `blac()` options

---

# Logging Plugin

> Console output for state changes, instance lifecycle events, and monitoring alerts — a passive, scannable record of what your blocs are doing.

Source: /plugins/logging/

The logging plugin provides console output for state changes, instance lifecycle events, and monitoring alerts. Reach for it when you want a passive, scannable record in the console or in CI logs — a running narrative of what your blocs are doing. For interactive, point-and-click inspection (state trees, diffs, time-travel) use [DevTools](/plugins/devtools) instead; the two are complementary and can run side by side. Like all plugins, it observes every instance from outside — see [Plugin Overview](/plugins/overview) for the bigger picture.

## Installation

```bash
pnpm add @blac/logging-plugin
```

## Quick setup

```ts
import { LoggingPlugin } from '@blac/logging-plugin';
import { getPluginManager } from '@blac/core';

getPluginManager().install(new LoggingPlugin({ level: 'info' }), {
  environment: 'development',
});
```

## What the output looks like

The default `format: 'grouped'` writes collapsible `console.group` entries for every event. Here is representative output for a short session — plugin install, a `CartCubit` state change, and its disposal:

```console
▶ [BlaC] Plugin installed
    Registered types: 1
    Total instances:  0

▶ [BlaC] Created CartCubit#a1b2c3d4
    Class:         CartCubit
    Instance ID:   a1b2c3d4-e5f6-7890-abcd-ef1234567890
    Initial state: { items: [], total: 0 }

▶ [BlaC] CartCubit#a1b2c3d4 state changed
    Previous: { items: [], total: 0 }
    Current:  { items: [{ id: 1, name: "Widget", qty: 2 }], total: 19.98 }

▶ [BlaC] Disposed CartCubit#a1b2c3d4
    Lifespan:      4.2s
    State changes: 1
    Final state:   { items: [{ id: 1, name: "Widget", qty: 2 }], total: 19.98 }
```

Groups are collapsed by default — click the `▶` arrow to expand. Switch to `format: 'simple'` for a flat, line-per-event view:

```console
[BlaC] Plugin installed (1 types, 0 instances)
[BlaC] Created CartCubit#a1b2c3d4
[BlaC] CartCubit#a1b2c3d4 state: {"items":[],"total":0} → {"items":[{"id":1,"name":"W...
[BlaC] Disposed CartCubit#a1b2c3d4 (lived 4.2s)
```

The simple format truncates state JSON at 50 characters, which keeps CI logs scannable.

:::tip[Screenshot pending]
The Console panel shows collapsed `[BlaC]` groups — plugin install, instance creation, a state change, and disposal — with the state-change group expanded to reveal the Previous / Current diff.
_Drop the file at `apps/docs/public/devtools-logging-console.png` (then re-add the `<img>`)._
:::

## Configuration

Pass a `LoggingPluginConfig` object to the constructor:

```ts
new LoggingPlugin({
  level: 'debug',
  format: 'grouped',
  include: ['CartCubit', 'AuthCubit'],
  logStateChanges: true,
  logLifecycle: true,
});
```

### Options

| Option             | Type                                          | Default     | Description                                     |
| ------------------ | --------------------------------------------- | ----------- | ----------------------------------------------- |
| `level`            | `'minimal' \| 'info' \| 'debug' \| 'verbose'` | `'info'`    | Log verbosity                                   |
| `format`           | `'simple' \| 'grouped'`                       | `'grouped'` | Output format. `'grouped'` uses `console.group` |
| `logger`           | `Logger`                                      | `console`   | Custom logger implementation                    |
| `prefix`           | `string`                                      | `'[BlaC]'`  | Prefix for log messages                         |
| `logLifecycle`     | `boolean`                                     | `true`      | Log instance creation and disposal              |
| `logStateChanges`  | `boolean`                                     | `true`      | Log state changes                               |
| `includeCallstack` | `boolean`                                     | `false`     | Show call stacks for state changes              |
| `logPaths`         | `boolean`                                     | `false`     | Log the dirtytalk paths that changed            |
| `include`          | `string[]`                                    | —           | Whitelist: only log these class names           |
| `exclude`          | `string[]`                                    | —           | Blacklist: skip these class names               |
| `filter`           | `FilterFn`                                    | —           | Custom filter function                          |

### Monitoring options

| Option                          | Type      | Default | Description                               |
| ------------------------------- | --------- | ------- | ----------------------------------------- |
| `instanceCountWarningThreshold` | `number`  | `50`    | Warn when instance count exceeds this     |
| `detectRapidLifecycles`         | `boolean` | `true`  | Detect rapid create/dispose cycles        |
| `rapidLifecycleWindowMs`        | `number`  | `1000`  | Time window for rapid lifecycle detection |
| `rapidLifecycleThreshold`       | `number`  | `5`     | Cycles in window to trigger warning       |

## Log levels

| Level     | Lifecycle | State changes  | Monitoring |
| --------- | --------- | -------------- | ---------- |
| `minimal` | No        | No             | Yes        |
| `info`    | Yes       | Yes            | Yes        |
| `debug`   | Yes       | Yes (detailed) | Yes        |
| `verbose` | Yes       | Yes (full)     | Yes        |

## Filtering

### By class name

```ts
new LoggingPlugin({
  include: ['CartCubit', 'AuthCubit'], // only these
  exclude: ['TimerCubit'], // or skip these
});
```

### Custom filter

```ts
new LoggingPlugin({
  filter: (ctx) => {
    // ctx: { instance, className, instanceId }
    return ctx.className !== 'InternalCubit'; // skip specific types
  },
});
```

:::note[`filter` ctx is not the plugin `PluginContext`]
The `filter` callback receives a small `{ instance, className, instanceId }` object — not the `PluginContext` passed to plugin hooks like `onStateChange`. Don't expect the hydration or query helpers here; this is just enough to decide whether a given instance should be logged.
:::

## Custom logger

Replace `console` with your own logging implementation:

```ts
new LoggingPlugin({
  logger: {
    log: (...args) => myLogger.info(...args),
    warn: (...args) => myLogger.warn(...args),
    error: (...args) => myLogger.error(...args),
    group: (label) => myLogger.group(label),
    groupEnd: () => myLogger.groupEnd(),
  },
});
```

## Registry stats

Call `logStats()` to print a summary of the current registry state:

```ts
const logging = new LoggingPlugin({ level: 'info' });
getPluginManager().install(logging);

// later, in a debug context:
logging.logStats();
```

## Rate limiting

State change logging is automatically disabled if more than 1,000 changes per second are detected. This prevents flooding the console in high-frequency scenarios. A warning is logged when rate limiting kicks in.

:::tip[Logging went quiet?]
If state-change logs suddenly stop, you have likely tripped the 1,000/s limiter — usually a sign of an emit storm (e.g. emitting on every animation frame). That same high update rate is what the `instanceCountWarningThreshold` and `detectRapidLifecycles` monitors are designed to surface. Treat these warnings as a pointer toward a [performance](/react/performance) problem rather than a logging quirk; lifecycle and monitoring logs keep flowing regardless of the limiter.
:::

## See also

- [Plugin Overview](/plugins/overview) — the plugin catalog and the install API
- [DevTools](/plugins/devtools) — interactive inspection; pairs well with logging
- [Performance](/react/performance) — diagnosing the emit storms the rate limiter guards against
- [Plugin Authoring](/core/plugins) — the hooks this plugin is built on

---

# Plugins

> A plugin observes all bloc instances from the outside — the right tool for cross-cutting concerns like logging, inspection, and persistence.

Source: /plugins/overview/

A plugin is a single object that taps into the registry's lifecycle — every instance created, every state change, every disposal flows through it. Where [system events](/core/system-events) let one bloc react to its _own_ lifecycle from the inside, a plugin observes _all_ instances from the outside. That makes plugins the right tool for cross-cutting concerns: logging, inspection, persistence — anything you want to apply uniformly without editing each bloc.

BlaC has an official set of plugins for these common needs. All plugins implement the `BlacPlugin` interface and are installed once, at startup, via `getPluginManager().install()`.

## Official plugins

| Package                                                                  | Purpose                                                         | Typical environment |
| ------------------------------------------------------------------------ | --------------------------------------------------------------- | ------------------- |
| [`@blac/logging-plugin`](/plugins/logging)                               | Console logging, instance monitoring, rapid lifecycle detection | Development         |
| [`@blac/devtools-connect`](/plugins/devtools)                            | Core plugin for instance tracking and state inspection          | Development         |
| [`@blac/devtools-ui`](/plugins/devtools#2-add-the-in-app-ui-recommended) | In-app draggable overlay and panel UI components                | Development         |
| [`@blac/plugin-persist`](/plugins/persistence)                           | Persist state to IndexedDB with automatic hydration             | All                 |

## Installing a plugin

```ts
import { getPluginManager } from '@blac/core';

getPluginManager().install(myPlugin, {
  enabled: true,
  environment: 'development', // 'development' | 'production' | 'test' | 'all'
});
```

The `environment` option controls when the plugin is active. The check is a **runtime comparison** against `process.env.NODE_ENV` (which falls back to `'development'`) performed inside `install()`: if the environments don't match, the plugin is skipped with a log message and never wired up. So `environment: 'development'` means the plugin does nothing in a production build — but the import still ships unless your bundler tree-shakes it. To keep dev-only plugin code out of the bundle entirely, guard the `install()` call behind your own `import.meta.env.DEV` (or equivalent) check.

:::note[Install once, at startup]
Install plugins before any blocs are acquired so the first `onCreated` hooks fire. `install()` throws if a plugin with the same `name` is already installed; calling it twice is a mistake, not an upsert.
:::

## Multiple plugins

Install as many plugins as you need. They all receive the same lifecycle callbacks independently.

```ts
import { getPluginManager } from '@blac/core';
import { LoggingPlugin } from '@blac/logging-plugin';
import { createDevToolsBrowserPlugin } from '@blac/devtools-connect';
import { createIndexedDbPersistPlugin } from '@blac/plugin-persist';

const pm = getPluginManager();

pm.install(new LoggingPlugin({ level: 'info' }), {
  environment: 'development',
});
pm.install(createDevToolsBrowserPlugin(), { environment: 'development' });
pm.install(createIndexedDbPersistPlugin());
```

## Building your own

See [Plugin Authoring](/core/plugins) for the full `BlacPlugin` interface, the hook firing model, and the `PluginContext` API.

## See also

- [Plugin Authoring](/core/plugins) — the `BlacPlugin` interface and how to write your own
- [System Events](/core/system-events) — per-instance lifecycle hooks, and when to use them instead of a plugin
- [Logging Plugin](/plugins/logging) · [DevTools](/plugins/devtools) · [Persistence](/plugins/persistence) — the official plugins in detail
- [Glossary](/guide/glossary) — definitions for plugin, hydration, and registry

---

# Persistence Plugin

> Automatically saves state to IndexedDB and restores it when instances are created, driven by the registry lifecycle and the hydration API.

Source: /plugins/persistence/

The persistence plugin automatically saves state to IndexedDB and restores it when instances are created. It is a [plugin](/plugins/overview) like any other — installed once at startup — but with one extra step: you tell it _which_ classes to persist by calling `.persist()`. Everything else (saving on change, hydrating on create, status tracking) happens through the registry lifecycle, driving the same [hydration API](/core/system-events#hydrationchanged) that any plugin can use.

## Installation

```bash
pnpm add @blac/plugin-persist
```

## Quick setup

```ts
import { createIndexedDbPersistPlugin } from '@blac/plugin-persist';
import { getPluginManager } from '@blac/core';

const persist = createIndexedDbPersistPlugin();
persist.persist(UserSettingsCubit);
getPluginManager().install(persist);
```

That's it. `UserSettingsCubit` state is now saved to IndexedDB on every change and restored when the instance is created.

## Plugin options

```ts
createIndexedDbPersistPlugin({
  databaseName: 'my-app', // default: 'blac-persist'
  storeName: 'app-state', // default: 'blac-state'
  pluginName: 'my-persist', // default: 'indexeddb-persist'
  adapter: customAdapter, // custom storage adapter
});
```

## Registering containers

Call `.persist()` for each class you want to persist. The method is chainable.

```ts
persist
  .persist(UserSettingsCubit)
  .persist(CartCubit, { debounceMs: 500 })
  .persist(ThemeCubit);
```

### Registration options

```ts
persist.persist(CartCubit, {
  key: 'cart', // custom storage key (default: ClassName:instanceId)
  debounceMs: 500, // debounce saves (default: 0)
  stateToDb: (state) => state.items, // transform before saving
  dbToState: (payload) => ({ items: payload }), // transform on load
  onHydrated: (state, ctx) => {
    // called after restore
    console.log('Cart restored with', state.items.length, 'items');
  },
  onError: (error, ctx) => {
    // called on save or load error
    console.error('Persist error:', error);
  },
});
```

| Option       | Type                        | Default                | Description                            |
| ------------ | --------------------------- | ---------------------- | -------------------------------------- |
| `key`        | `string \| (ctx) => string` | `ClassName:instanceId` | Storage key                            |
| `debounceMs` | `number`                    | `0`                    | Debounce save operations               |
| `stateToDb`  | `(state, ctx) => TPayload`  | Identity               | Transform state before saving          |
| `dbToState`  | `(payload, ctx) => S`       | Identity               | Transform persisted data back to state |
| `onHydrated` | `(state, ctx) => void`      | —                      | Called after successful hydration      |
| `onError`    | `(error, ctx) => void`      | —                      | Called on error                        |

### Dynamic keys

Use a function for per-instance storage keys:

```ts
persist.persist(EditorCubit, {
  key: (ctx) => `editor:${ctx.instanceId}`,
});
```

## Hydration lifecycle

When a persisted instance is created:

```text
idle → hydrating → hydrated
                 → error (if load fails)
```

After hydration, on state changes:

```text
hydrated → saving → saved
                  → error (if save fails)
```

### Dirty state during hydration

If state changes before hydration completes (e.g., the user interacts with the component immediately), the persisted state is **discarded**. The user's changes take priority — stale data from disk should never clobber something the user just did.

You can detect this via the `changedWhileHydrating` field on the [`hydrationChanged` system event](/core/system-events#hydrationchanged). That event is the other side of this same mechanism: the persistence plugin reads the flag to decide whether to apply the loaded state, and you can observe the same flag to react in your own code.

## Status monitoring

### Per-instance status

```ts
const status = persist.getStatus(myInstance);
// { key, className, instanceId, phase, hydratedFromStorage, savedAt?, error? }
```

Phases: `'idle'` | `'hydrating'` | `'hydrated'` | `'saving'` | `'saved'` | `'error'`

### Subscribe to status changes

```ts
const unsub = persist.subscribe((event) => {
  // event: { instance, status }
  console.log(event.status.phase);
});
```

## Clearing stored data

```ts
await persist.clearRecord('cart'); // clear one record
await persist.clearAll(); // clear everything
```

## Custom storage adapter

Implement the `IndexedDbPersistAdapter` interface to use a different storage backend:

```ts
import {
  createIndexedDbPersistPlugin,
  type IndexedDbPersistAdapter,
  type PersistedRecord,
} from '@blac/plugin-persist';

// A simple in-memory backend (handy for tests or non-IndexedDB environments).
const store = new Map<string, PersistedRecord>();

const memoryAdapter: IndexedDbPersistAdapter = {
  isAvailable: () => true,
  get: async (key) => store.get(key) ?? null,
  put: async (record) => {
    store.set(record.id, record);
  },
  delete: async (key) => {
    store.delete(key);
  },
  clear: async () => {
    store.clear();
  },
};

const persist = createIndexedDbPersistPlugin({ adapter: memoryAdapter });
```

This is useful for testing or for environments where IndexedDB is not available.

## Waiting for hydration

`$blac.hydration.wait()` is available on every state container, not something this plugin adds — it resolves once hydration settles (or immediately, if the bloc was never set up to hydrate). That makes it safe to call even on blocs you have not registered with `.persist()`. Use it in your Cubit to defer work until restored state is in place:

```ts
class AuthCubit extends Cubit<AuthState> {
  constructor() {
    super({ user: null, token: null });
  }

  async initialize() {
    await this.$blac.hydration.wait();
    if (this.state.token) {
      await this.refreshSession();
    }
  }
}
```

The plugin automatically checks IndexedDB availability on install and disables itself with a warning if unavailable.

## Common mistakes

:::caution[Watch for these]

- **Persisting non-serializable state.** Functions, class instances, `Map`/`Set`, and DOM nodes do not round-trip through IndexedDB. Keep persisted state to plain JSON-compatible data, or use `stateToDb`/`dbToState` to project to and from a serializable shape.
- **Expecting persistence without `.persist()`.** Installing the plugin alone does nothing — a class is only saved and hydrated after you register it. Register before any instance of that class is acquired so hydration runs on first create.
- **Key collisions across instances.** The default key is `ClassName:instanceId`, which keeps multiple instances of the same class separate. If you set a static `key` string, every instance of that class shares one record and overwrites the others. For per-instance persistence, use a [dynamic key](#dynamic-keys) function instead.
:::

## See also

- [Plugin Overview](/plugins/overview) — the plugin catalog and the install API
- [System Events](/core/system-events#hydrationchanged) — the `hydrationChanged` event behind the dirty-state logic
- [Cubit](/core/cubit#public-properties) — `$blac.hydration.status`, `$blac.hydration.isHydrated`, and `$blac.hydration.wait()` on the container
- [Patterns](/guide/patterns) — hydration-aware loading recipes
- [Glossary](/guide/glossary) — definitions for hydration, plugin, and registry

---

# Plugin Recipes

> Copy-paste BlacPlugin recipes for common cross-cutting concerns — localStorage, debounced saves, cross-tab sync, Sentry breadcrumbs, and audit logging.

Source: /plugins/recipes/

Copy-paste plugins for common cross-cutting concerns. Each recipe is a
self-contained `BlacPlugin` that you can drop into your app and tweak. All
recipes use only `@blac/core` imports so they work without any extra
dependencies unless noted.

For the plugin authoring API that every recipe is built on, see
[Plugin Authoring](/core/plugins). For the official first-party plugins see
[Plugin Overview](/plugins/overview).

## Compose order and throw semantics

Plugins execute in install order. Keep these rules in mind when you compose
several recipes together:

- **Persistence first.** If you layer a logging plugin on top of a
  persistence plugin, the logger will see the post-hydration state. That is
  usually what you want — logging will then record the initial _restored_
  value rather than the constructor default.
- **Sinks last.** Send-to-server plugins (Sentry, audit log) should be
  installed after any transforming or filtering plugins so they see the final
  view of the state.
- **Hook throws are not caught.** If `onStateChange` throws, the exception
  propagates synchronously out of the flush and the remaining plugins in the
  chain are skipped. Guard any I/O inside a `try/catch` in your hooks rather
  than letting errors bubble.

---

## 1. localStorage adapter

A minimal persistence plugin backed by `localStorage` instead of IndexedDB.
Good for small string-serializable state where IndexedDB is unnecessary.

:::caution[PII caveat]
`localStorage` is readable by any script on the same origin. Do not persist
state that contains passwords, tokens, health data, or any other personally
identifiable information. If you need to store sensitive data, prefer the
official [Persistence plugin](/plugins/persistence) with an encrypted adapter,
or keep it in a `sessionStorage`-backed variant.
:::

```ts twoslash
import {
  getPluginManager,
  type BlacPlugin,
  type PathSet,
  ALL_PATHS,
  type StateContainerConstructor,
} from '@blac/core';

// --- Recipe: localStorage persistence ---

interface LocalStorageOptions<S extends object> {
  /**
   * Classes to persist. State must be JSON-serializable.
   * e.g. [CartCubit, ThemeCubit]
   */
  targets: StateContainerConstructor<S>[];
  /** Storage key prefix. Defaults to "blac". */
  prefix?: string;
}

function createLocalStoragePlugin<S extends object>(
  opts: LocalStorageOptions<S>,
): BlacPlugin {
  const prefix = opts.prefix ?? 'blac';
  const targetNames = new Set(opts.targets.map((T) => T.name));

  return {
    name: 'local-storage-persist',
    version: '1.0.0',

    onCreated(ctx) {
      const c = ctx.container;
      if (!c || !targetNames.has(c.$blac.name)) return;

      const key = `${prefix}:${c.$blac.name}:${c.$blac.id}`;
      try {
        const raw = localStorage.getItem(key);
        if (raw !== null) {
          const saved = JSON.parse(raw) as S;
          ctx.startHydration(c);
          ctx.applyHydratedState(c, saved);
          ctx.finishHydration(c);
        }
      } catch {
        ctx.failHydration(c, new Error('localStorage read failed'));
      }
    },

    onStateChange(ctx, _prev, next, _paths: PathSet) {
      const c = ctx.container;
      if (!c || !targetNames.has(c.$blac.name)) return;

      const key = `${prefix}:${c.$blac.name}:${c.$blac.id}`;
      try {
        localStorage.setItem(key, JSON.stringify(next));
      } catch {
        // Storage full or private-browsing restriction — fail silently.
      }
    },
  };
}

// Install once at app startup.
// getPluginManager().install(createLocalStoragePlugin({ targets: [] }));
```

---

## 2. Debounced-save adapter

Wraps any synchronous write with a debounce so rapid state changes only
trigger one write per quiet window. Useful when state changes on every
keystroke and the save target (IndexedDB, a remote API) is slow.

```ts twoslash
import {
  getPluginManager,
  type BlacPlugin,
  type PathSet,
  ALL_PATHS,
} from '@blac/core';

// --- Recipe: debounced-save wrapper ---

type SaveFn = (key: string, state: unknown) => void;

interface DebouncedSaveOptions {
  /**
   * Synchronous or async function that does the actual write.
   * Called once per quiet window per instance.
   */
  save: SaveFn;
  /** Milliseconds of inactivity before flushing. Default: 300. */
  debounceMs?: number;
  /** Key prefix. Default: "blac". */
  prefix?: string;
  /** Optional set of class names to include. Omit to include all. */
  include?: string[];
}

function createDebouncedSavePlugin(opts: DebouncedSaveOptions): BlacPlugin {
  const debounceMs = opts.debounceMs ?? 300;
  const prefix = opts.prefix ?? 'blac';
  const includeSet = opts.include ? new Set(opts.include) : null;
  const timers = new Map<string, ReturnType<typeof setTimeout>>();

  return {
    name: 'debounced-save',
    version: '1.0.0',

    onStateChange(ctx, _prev, next, _paths: PathSet) {
      const c = ctx.container;
      if (!c) return;
      if (includeSet && !includeSet.has(c.$blac.name)) return;

      const key = `${prefix}:${c.$blac.name}:${c.$blac.id}`;

      const existing = timers.get(key);
      if (existing !== undefined) clearTimeout(existing);

      timers.set(
        key,
        setTimeout(() => {
          timers.delete(key);
          opts.save(key, next);
        }, debounceMs),
      );
    },

    onDestroyed(ctx) {
      const c = ctx.container;
      if (!c) return;
      const key = `${prefix}:${c.$blac.name}:${c.$blac.id}`;
      const existing = timers.get(key);
      if (existing !== undefined) {
        // Flush immediately on disposal — don't lose the last state.
        clearTimeout(existing);
        timers.delete(key);
        opts.save(key, c.state);
      }
    },
  };
}

// Example: write to localStorage with a 500 ms debounce.
const debouncedPlugin = createDebouncedSavePlugin({
  save: (key, state) => localStorage.setItem(key, JSON.stringify(state)),
  debounceMs: 500,
  include: ['CartCubit', 'DraftCubit'],
});

// Install once at app startup.
// getPluginManager().install(debouncedPlugin);
```

:::tip[Compose order]
Install the debounced-save plugin **after** any persistence plugin if you
also use the official `@blac/plugin-persist`. The official plugin handles
hydration; this recipe only handles writes.
:::

---

## 3. Cross-tab sync

Broadcasts state changes to other browser tabs via `BroadcastChannel` and
applies incoming updates through the hydration API. Use this when multiple
tabs show the same app and you want them to stay in sync (e.g. a shopping
cart or an auth session).

:::caution[PII caveat]
`BroadcastChannel` messages are visible to all same-origin tabs for the
duration of the browser session. Strip or redact any sensitive fields
(tokens, PII) in the `serialize` option before broadcasting.
:::

```ts twoslash
import {
  getPluginManager,
  type BlacPlugin,
  type PathSet,
  ALL_PATHS,
  type StateContainerConstructor,
} from '@blac/core';

// --- Recipe: cross-tab sync via BroadcastChannel ---

interface CrossTabSyncOptions<S extends object> {
  /** Classes to sync across tabs. */
  targets: StateContainerConstructor<S>[];
  /** BroadcastChannel name. Default: "blac-sync". */
  channelName?: string;
  /**
   * Optional transform applied before broadcasting.
   * Use this to strip PII or tokens before the message leaves the tab.
   */
  serialize?: (state: S) => unknown;
  /** Optional transform applied when receiving a message. */
  deserialize?: (payload: unknown) => S;
}

interface SyncMessage {
  type: 'state-update';
  className: string;
  instanceId: string;
  state: unknown;
}

function createCrossTabSyncPlugin<S extends object>(
  opts: CrossTabSyncOptions<S>,
): BlacPlugin {
  const channelName = opts.channelName ?? 'blac-sync';
  const targetNames = new Set(opts.targets.map((T) => T.name));

  let channel: BroadcastChannel | null = null;
  // Track which instance keys are receiving a remote update so we don't
  // echo the incoming state back out to other tabs.
  const receiving = new Set<string>();

  return {
    name: 'cross-tab-sync',
    version: '1.0.0',

    onInstall(ctx) {
      if (typeof BroadcastChannel === 'undefined') return;
      channel = new BroadcastChannel(channelName);

      channel.onmessage = (event: MessageEvent<SyncMessage>) => {
        const msg = event.data;
        if (msg?.type !== 'state-update') return;
        if (!targetNames.has(msg.className)) return;

        const instances = ctx.queryInstances(
          // Use the metadata helper to match by name since we only have strings.
          // queryInstances needs the constructor — skip if class not in registry.
          opts.targets.find(
            (T) => T.name === msg.className,
          ) as StateContainerConstructor<S>,
        );

        for (const inst of instances) {
          if (inst.$blac.id !== msg.instanceId) continue;

          const key = `${msg.className}:${msg.instanceId}`;
          receiving.add(key);
          const next = opts.deserialize
            ? opts.deserialize(msg.state)
            : (msg.state as S);
          ctx.startHydration(inst);
          ctx.applyHydratedState(inst, next);
          ctx.finishHydration(inst);
          // Remove after the microtask so onStateChange fires first.
          Promise.resolve().then(() => receiving.delete(key));
        }
      };
    },

    onUninstall() {
      channel?.close();
      channel = null;
    },

    onStateChange(ctx, _prev, next, _paths: PathSet) {
      const c = ctx.container;
      if (!c || !channel) return;
      if (!targetNames.has(c.$blac.name)) return;

      const key = `${c.$blac.name}:${c.$blac.id}`;
      if (receiving.has(key)) return; // avoid echo

      const payload = opts.serialize
        ? opts.serialize(next as unknown as S)
        : next;

      const msg: SyncMessage = {
        type: 'state-update',
        className: c.$blac.name,
        instanceId: c.$blac.id,
        state: payload,
      };
      channel.postMessage(msg);
    },
  };
}

// Install once at app startup.
// getPluginManager().install(createCrossTabSyncPlugin({ targets: [] }));
```

---

## 4. Sentry breadcrumb sink

Adds a Sentry breadcrumb for each state change. Because breadcrumbs are sent
with every event, this gives you a state-change timeline attached to error
reports — similar to Redux DevTools' action history but visible in Sentry.

:::caution[PII caveat]
State is included verbatim in Sentry breadcrumbs and uploaded to Sentry's
servers. Redact or omit any fields that contain passwords, tokens, health
data, or other PII using the `sanitize` option below. Failure to do so may
violate GDPR, HIPAA, or your own privacy policy.
:::

:::note[No `@sentry/browser` in twoslash scope]
The Sentry SDK is not installed in the docs type-checker. The snippet below
uses a plain `ts` fence. Copy it into a project where `@sentry/browser` (or
`@sentry/react`) is installed.
:::

```ts
import { getPluginManager } from '@blac/core';
import type { BlacPlugin, PathSet } from '@blac/core';
import * as Sentry from '@sentry/browser';

// --- Recipe: Sentry breadcrumb sink ---

interface SentryPluginOptions {
  /** Classes to include. Omit to include all blocs. */
  include?: string[];
  /** Classes to exclude. */
  exclude?: string[];
  /**
   * Strip sensitive fields from state before attaching to the breadcrumb.
   * Called with the full next state; return the shape you want Sentry to see.
   * REQUIRED if your state contains PII, tokens, or health data.
   */
  sanitize?: (state: unknown, className: string) => unknown;
}

function createSentryPlugin(opts: SentryPluginOptions = {}): BlacPlugin {
  const includeSet = opts.include ? new Set(opts.include) : null;
  const excludeSet = opts.exclude ? new Set(opts.exclude) : null;

  return {
    name: 'sentry-breadcrumbs',
    version: '1.0.0',

    onStateChange(ctx, _prev, next, _paths: PathSet) {
      const c = ctx.container;
      if (!c) return;
      if (includeSet && !includeSet.has(c.$blac.name)) return;
      if (excludeSet && excludeSet.has(c.$blac.name)) return;

      const data = opts.sanitize ? opts.sanitize(next, c.$blac.name) : next;

      Sentry.addBreadcrumb({
        category: 'blac.state',
        message: `${c.$blac.name} changed`,
        level: 'info',
        data: data as Record<string, unknown>,
      });
    },
  };
}

// Install once at app startup. Gate to production so dev overhead stays low.
// getPluginManager().install(createSentryPlugin({
//   sanitize: (state, name) => {
//     if (name === 'AuthCubit') {
//       const s = state as { user: unknown; token: unknown };
//       return { user: s.user, token: '[redacted]' };
//     }
//     return state;
//   },
// }), { environment: 'production' });
```

---

## 5. Audit log

Writes a structured log entry for every state change, creation, and
disposal. Useful for compliance or debugging — you can pipe `entries` to your
existing logging infrastructure, a remote endpoint, or a circular buffer.

:::caution[PII caveat]
The audit log captures the full `prev` and `next` states. If any bloc holds
PII (user profiles, payment details, health data), provide a `sanitize`
function to strip sensitive fields before they are stored. Do not ship raw
state to external endpoints without first sanitizing it.
:::

```ts twoslash
import {
  getPluginManager,
  type BlacPlugin,
  type PathSet,
  ALL_PATHS,
} from '@blac/core';

// --- Recipe: structured audit log ---

type AuditEventKind = 'created' | 'state-changed' | 'disposed';

interface AuditEntry {
  kind: AuditEventKind;
  className: string;
  instanceId: string;
  timestamp: number;
  prev?: unknown;
  next?: unknown;
  /** Human-readable changed paths, or "(all)" for a full-replace. */
  paths?: string[];
}

interface AuditLogOptions {
  /**
   * Called with each new entry. Wire to console.log, a remote endpoint,
   * or push into a circular buffer.
   */
  onEntry: (entry: AuditEntry) => void;
  /** Optional per-entry sanitizer. Strip PII before logging externally. */
  sanitize?: (state: unknown, className: string) => unknown;
  /** Optional allowlist of class names to audit. */
  include?: string[];
  /** Optional denylist of class names to skip. */
  exclude?: string[];
}

function createAuditLogPlugin(opts: AuditLogOptions): BlacPlugin {
  const includeSet = opts.include ? new Set(opts.include) : null;
  const excludeSet = opts.exclude ? new Set(opts.exclude) : null;

  const allowed = (name: string) => {
    if (includeSet && !includeSet.has(name)) return false;
    if (excludeSet && excludeSet.has(name)) return false;
    return true;
  };

  const san = (state: unknown, name: string) =>
    opts.sanitize ? opts.sanitize(state, name) : state;

  return {
    name: 'audit-log',
    version: '1.0.0',

    onCreated(ctx) {
      const c = ctx.container;
      if (!c || !allowed(c.$blac.name)) return;
      opts.onEntry({
        kind: 'created',
        className: c.$blac.name,
        instanceId: c.$blac.id,
        timestamp: Date.now(),
        next: san(c.state, c.$blac.name),
      });
    },

    onStateChange(ctx, prev, next, paths: PathSet) {
      const c = ctx.container;
      if (!c || !allowed(c.$blac.name)) return;

      const changedPaths =
        paths === ALL_PATHS
          ? ['(all)']
          : [...paths].map((id) => c.interner.lookup(id));

      opts.onEntry({
        kind: 'state-changed',
        className: c.$blac.name,
        instanceId: c.$blac.id,
        timestamp: Date.now(),
        prev: san(prev, c.$blac.name),
        next: san(next, c.$blac.name),
        paths: changedPaths,
      });
    },

    onDestroyed(ctx) {
      const c = ctx.container;
      if (!c || !allowed(c.$blac.name)) return;
      opts.onEntry({
        kind: 'disposed',
        className: c.$blac.name,
        instanceId: c.$blac.id,
        timestamp: Date.now(),
        prev: san(c.state, c.$blac.name),
      });
    },
  };
}

// Example: log to console with a circular buffer of the last 100 entries.
const auditEntries: AuditEntry[] = [];

getPluginManager().install(
  createAuditLogPlugin({
    onEntry(entry) {
      if (auditEntries.length >= 100) auditEntries.shift();
      auditEntries.push(entry);
      console.debug('[audit]', entry.kind, entry.className, entry.paths);
    },
    sanitize(state, name) {
      if (name === 'AuthCubit') {
        const s = state as { user: unknown; token?: string };
        return { ...s, token: '[redacted]' };
      }
      return state;
    },
  }),
  { environment: 'development' },
);
```

---

## See also

- [Plugin Authoring](/core/plugins) — the `BlacPlugin` interface and hook reference
- [Plugin Overview](/plugins/overview) — first-party plugin catalog
- [Persistence](/plugins/persistence) — official IndexedDB persistence, including a custom adapter API
- [Logging](/plugins/logging) — official structured console logging plugin

---

# Core Testing API

> The full @blac/core/testing helper reference — registry isolation, state seeding, stubs, overrides, and async helpers.

Source: /testing/core/

All core testing utilities are imported from `@blac/core/testing`. They work with any test runner and have no framework-specific dependencies — only the test globals (`describe`/`it`/`expect`/`vi`) come from your runner, which in this project is [`vite-plus`](/testing/overview#why-registry-isolation-matters).

```ts
import {
  blacTestSetup,
  createTestRegistry,
  withTestRegistry,
  registerOverride,
  overrideEnsure,
  createCubitStub,
  withBlocState,
  withBlocMethod,
  flush,
} from '@blac/core/testing';
```

:::tip[Which helper do I reach for?]
These tools overlap, so start from the question you are answering:

| Goal                                                         | Helper                                |
| ------------------------------------------------------------ | ------------------------------------- |
| Isolate **every** test in a file (the default)               | `blacTestSetup()`                     |
| Isolate **one block** of code, sync or async                 | `withTestRegistry(fn)`                |
| Use a **real** instance, just with starting state            | `withBlocState(Cubit, state)`         |
| Replace **one method** on a real instance                    | `withBlocMethod(Cubit, name, impl)`   |
| Build an instance with state, mocked methods, args, or deps  | `createCubitStub(Cubit, options)`     |
| Force the registry to return **your** instance (e.g. a stub) | `registerOverride(Cubit, instance)`   |
| Override the registry for a **single expression**            | `overrideEnsure(Cubit, instance, fn)` |

Rule of thumb: prefer real instances (`withBlocState`, `withBlocMethod`) so you exercise real logic; reach for stubs and overrides only to control a bloc's _dependencies_ or to intercept side effects.
:::

## Registry isolation

### `blacTestSetup()`

Installs `beforeEach` / `afterEach` hooks that swap in a fresh registry for every test. Call it once at the top of a test file or inside a `describe` block.

```ts
import { it, expect } from 'vite-plus/test';
import { blacTestSetup } from '@blac/core/testing';
import { ensure } from '@blac/core';

blacTestSetup();

it('test A — fresh registry', () => {
  const counter = ensure(CounterCubit);
  counter.increment();
  expect(counter.state.count).toBe(1);
});

it('test B — does not see test A state', () => {
  const counter = ensure(CounterCubit);
  expect(counter.state.count).toBe(0);
});
```

This is the recommended default for almost every test file. Use the lower-level helpers below only when you need more control.

### `createTestRegistry()`

Returns a new, empty `StateContainerRegistry`. Use this when you need to create a registry without installing it as the global one.

```ts
const registry = createTestRegistry();
```

### `withTestRegistry(fn)`

```ts
function withTestRegistry<T>(fn: (registry: StateContainerRegistry) => T): T;
```

Runs a callback with a temporary isolated registry, then restores the previous one. Works with both sync and async callbacks. The registry is always restored — even if the callback throws.

```ts
import { withTestRegistry } from '@blac/core/testing';
import { ensure } from '@blac/core';

const result = withTestRegistry(() => {
  const counter = ensure(CounterCubit);
  counter.increment();
  return counter.state.count;
});
expect(result).toBe(1);

// Outside the callback, the original registry is restored
```

Async example:

```ts
await withTestRegistry(async () => {
  const data = ensure(AsyncDataCubit);
  await data.fetchItems();
  expect(data.state.items).toHaveLength(3);
});
```

`withTestRegistry` can be nested. Each level gets its own isolated registry:

```ts
withTestRegistry(() => {
  ensure(CounterCubit).increment(); // count = 1

  withTestRegistry(() => {
    // Inner registry is independent
    expect(ensure(CounterCubit).state.count).toBe(0);
  });

  // Outer registry is restored
  expect(ensure(CounterCubit).state.count).toBe(1);
});
```

## Seeding state

### `withBlocState(BlocClass, state, args?)`

```ts
function withBlocState<T extends StateContainerConstructor>(
  BlocClass: T,
  state: Partial<ExtractState<T>>,
  args?: ExtractArgs<T>,
): InstanceType<T>;
```

Ensures an instance exists in the registry and seeds its state. For object-state cubits, the state is merged via `patch()` so you only need to provide the fields you care about. Returns the instance.

```ts
blacTestSetup();

it('filters active todos', () => {
  const todo = withBlocState(TodoCubit, {
    items: [
      { id: '1', text: 'Buy milk', done: false },
      { id: '2', text: 'Walk dog', done: true },
    ],
  });

  expect(todo.activeTodos).toHaveLength(1);
});
```

For named instances, pass the `args` that identify them (resolved via the class's `static key`/structural hash):

```ts
withBlocState(EditorCubit, { content: 'Hello' }, { docId: 'doc-1' });
withBlocState(EditorCubit, { content: 'World' }, { docId: 'doc-2' });
```

### `withBlocMethod(BlocClass, methodName, impl, args?)`

```ts
function withBlocMethod<T extends StateContainerConstructor>(
  BlocClass: T,
  methodName: keyof InstanceType<T>,
  impl: (...args: any[]) => any,
  args?: ExtractArgs<T>,
): InstanceType<T>;
```

Ensures an instance exists and replaces a single method. Other methods remain fully functional.

```ts
import { it, expect, vi } from 'vite-plus/test';

blacTestSetup();

it('calls save on submit', () => {
  const mockSave = vi.fn();
  withBlocMethod(FormCubit, 'save', mockSave);

  const form = ensure(FormCubit);
  form.save();
  expect(mockSave).toHaveBeenCalled();
});
```

This is useful when you want a real instance with real state management, but need to intercept a specific side-effecting method (API calls, navigation, etc.).

## Stubs

### `createCubitStub(BlocClass, options?)` {#create-cubit-stub}

```ts
function createCubitStub<T extends StateContainerConstructor>(
  BlocClass: T,
  options?: {
    state?: Partial<ExtractState<T>>;
    methods?: Partial<Record<MethodKeys<InstanceType<T>>, Function>>;
    args?: ExtractArgs<T>;
    deps?: Partial<ExtractDeps<T>>;
  },
): InstanceType<T>;
```

Creates a real instance of the cubit with optional pre-set state and method overrides. The stub is a fully functional instance — subscriptions, `emit`, `patch`, and `dispose` all work normally. Only the explicitly overridden methods are replaced.

| Option    | Effect                                                                                                                                                                       |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`   | Seeds starting state. Merged via `patch()` for object state (provide only the fields you care about); replaced via `emit()` for non-object state.                            |
| `methods` | Replaces specific methods on the instance. Everything else stays real.                                                                                                       |
| `args`    | Runs the bloc's `init(args)` once via the same internal path the registry uses, so `init` and lifecycle hooks fire. Only allowed when the bloc declares a non-`void` `Args`. |
| `deps`    | Pre-wires a [`deps`](/guide/inputs) slice so `onDepsChanged` fires during the test.                                                                                          |

The options apply in source order: `args` runs `init` first, then `state` overrides on top, then `methods` are swapped, then `deps` are wired (which may itself emit via `onDepsChanged`).

```ts
import { it, expect, vi } from 'vite-plus/test';

blacTestSetup();

it('creates a stub with partial state', () => {
  const stub = createCubitStub(AuthCubit, {
    state: { loggedIn: true, userId: 'user-1' },
  });
  expect(stub.state.loggedIn).toBe(true);
  expect(stub.state.role).toBe('viewer'); // default preserved
});

it('creates a stub with mocked methods', () => {
  const mockLogout = vi.fn();
  const stub = createCubitStub(AuthCubit, {
    methods: { logout: mockLogout },
  });
  stub.logout();
  expect(mockLogout).toHaveBeenCalled();
  // login() and other methods still work normally
});
```

#### Stubbing blocs that take `args` or `deps`

If a bloc derives its initial state from `args` in `init()`, pass `args` so `init` actually runs:

```ts
it('seeds state from args via init()', () => {
  // class UserCubit extends Cubit<UserState, { userId: string }> {
  //   protected init(a) { this.emit({ id: a.userId }); }
  // }
  const stub = createCubitStub(UserCubit, { args: { userId: 'alice' } });
  expect(stub.state.id).toBe('alice');
});
```

For blocs that react to injected handles, pass `deps` to drive `onDepsChanged`:

```ts
it('reacts to a wired dependency', () => {
  const el = { id: 42 };
  const stub = createCubitStub(CanvasCubit, { deps: { el } });

  expect(stub.deps.el).toBe(el); // onDepsChanged fired with this slice
});
```

`args` and `deps` can be combined with `state` and `methods` in the same call.

:::tip
`createCubitStub` is the only place `deps` enter the testing API. The registry helpers (`withBlocState`, `withBlocMethod`, `registerOverride`, `overrideEnsure`) take an optional trailing `args` argument — it both keys the instance and seeds `init(args)` — but none of them accept `deps`. For a deps-wired instance, build it with `createCubitStub({ args, deps })` and inject it with `registerOverride`. See [Inputs](/guide/inputs) for the `args`/`deps` model.
:::

Stubs are commonly paired with `registerOverride` to inject them into the registry for use by dependent code or React components.

## Overrides

### `registerOverride(BlocClass, instance, args?)`

```ts
function registerOverride<T extends StateContainerConstructor>(
  BlocClass: T,
  instance: InstanceType<T>,
  args?: ExtractArgs<T>,
): void;
```

Injects a specific instance into the registry, replacing any existing one. The previous instance is disposed if it exists. Use this when you need full control over what instance the registry returns for a given class.

```ts
blacTestSetup();

it('uses the override when resolving dependencies', () => {
  const authStub = createCubitStub(AuthCubit, {
    state: { loggedIn: true, userId: 'test-user' },
  });
  registerOverride(AuthCubit, authStub);

  // DashboardCubit.depend(AuthCubit) will resolve to authStub
  const dashboard = ensure(DashboardCubit);
  expect(dashboard.summary).toContain('test-user');
});
```

### `overrideEnsure(BlocClass, instance, fn, args?)`

```ts
function overrideEnsure<T extends StateContainerConstructor, R>(
  BlocClass: T,
  instance: InstanceType<T>,
  fn: () => R,
  args?: ExtractArgs<T>,
): R;
```

Scoped override — registers the instance inside a temporary registry, runs the callback, then cleans up. Useful for one-off assertions without affecting other tests.

```ts
it('computes total with shipping', () => {
  const shipping = createCubitStub(ShippingCubit, { state: { rate: 9.99 } });

  const total = overrideEnsure(ShippingCubit, shipping, () => {
    const cart = ensure(CartCubit);
    return cart.total;
  });

  expect(total).toBe(9.99);
});
```

## Async helpers

### `flush()`

```ts
function flush(): Promise<void>;
```

BlaC coalesces state changes onto a microtask (the default `MicrotaskScheduler`), so a value set inside an action is not visible to subscribers, `onSystemEvent('stateChanged')` handlers, or plugin hooks until the channel flushes. `flush()` drains those pending microtasks — `await` it after triggering a change and before asserting on any side effect.

```ts
it('propagates async state', async () => {
  const data = ensure(AsyncDataCubit);
  data.triggerUpdate();
  await flush();
  expect(data.state.updated).toBe(true);
});
```

:::note[Reading `state` directly does not need a flush]
`flush()` is about _propagation_. The instance's own `state` getter is synchronous — `data.state` is up to date the instant `emit`/`patch` returns. You only need `await flush()` when asserting on something downstream of the channel flush (a `subscribe` listener, a `stateChanged` handler, a re-rendered component, a plugin).
:::

:::caution[`flush()` drains microtasks, not timers]
`flush()` awaits the microtask queue. If your code schedules work with `setTimeout`/`setInterval`, drive it with `vi.useFakeTimers()` + `vi.advanceTimersByTime()` instead — `flush()` will not advance real or fake timers. This is the mirror image of the once-per-flush batching described in [System Events](/core/system-events).
:::

## Combining helpers

The real power of these utilities comes from combining them. Here's a complete example testing a cubit that depends on two others:

```ts
import { describe, it, expect, vi } from 'vite-plus/test';
import {
  blacTestSetup,
  createCubitStub,
  registerOverride,
  withBlocState,
} from '@blac/core/testing';
import { ensure } from '@blac/core';

blacTestSetup();

describe('DashboardCubit', () => {
  it('shows user greeting with cart count', () => {
    // Seed dependencies with known state
    registerOverride(
      AuthCubit,
      createCubitStub(AuthCubit, {
        state: { loggedIn: true, userId: 'u1', name: 'Alice' },
      }),
    );
    registerOverride(
      CartCubit,
      createCubitStub(CartCubit, {
        state: { items: [{ id: '1', price: 10 }] },
      }),
    );

    const dashboard = ensure(DashboardCubit);
    expect(dashboard.summary).toBe('Alice has 1 items');
  });

  it('shows guest greeting when logged out', () => {
    registerOverride(
      AuthCubit,
      createCubitStub(AuthCubit, {
        state: { loggedIn: false },
      }),
    );

    const dashboard = ensure(DashboardCubit);
    expect(dashboard.summary).toContain('Guest');
  });
});
```

## Testing cubits with `depend()`

When a cubit uses `this.depend()`, it resolves dependencies lazily from the registry. Use `registerOverride` to control what it gets:

```ts
class CartCubit extends Cubit<CartState> {
  private shipping = this.depend(ShippingCubit);

  get total() {
    return (
      this.state.items.reduce((s, i) => s + i.price, 0) +
      this.shipping.untracked().state.rate
    );
  }
}
```

```ts
blacTestSetup();

it('includes shipping in total', () => {
  registerOverride(
    ShippingCubit,
    createCubitStub(ShippingCubit, { state: { rate: 4.99 } }),
  );

  const cart = withBlocState(CartCubit, {
    items: [{ id: '1', price: 20 }],
  });

  expect(cart.total).toBe(24.99);
});
```

The stub is a real `ShippingCubit` instance, so `cart`'s `.shipping.untracked()` resolves it exactly as it would in production — no special mocking framework needed. (For the production-side picture of how `depend()` resolves from the registry, see [Bloc Communication](/core/bloc-communication).)

:::danger[Common mistakes]

- **Overriding a dependency _after_ the dependent bloc has already read it.** `depend()` resolves lazily on each call, but if your dependent bloc cached a value in `init()` from the dependency, register the override _before_ you `ensure` the dependent bloc.
- **Forgetting that `depend()` uses `ensure` (no ref).** Within a test the registry is isolated, so this rarely bites — but in app code a depended-on bloc can be disposed if nothing holds a ref. See [Bloc Communication](/core/bloc-communication).
  :::

## Testing keyed instances

Pass the `args` that identify each instance to any helper (the class's `static key`/structural hash resolves them to the registry key):

```ts
blacTestSetup();

it('manages independent editor instances', () => {
  withBlocState(EditorCubit, { content: 'Doc A' }, { docId: 'doc-a' });
  withBlocState(EditorCubit, { content: 'Doc B' }, { docId: 'doc-b' });

  const editorA = ensure(EditorCubit, { args: { docId: 'doc-a' } });
  const editorB = ensure(EditorCubit, { args: { docId: 'doc-b' } });

  expect(editorA.state.content).toBe('Doc A');
  expect(editorB.state.content).toBe('Doc B');
});
```

## See also

- [Testing Overview](/testing/overview) — why registry isolation matters and the import convention
- [React Testing](/testing/react) — `renderWithBloc` / `renderWithRegistry`, built on these primitives
- [Instance Management](/core/instance-management) — the registry, `ensure`, and ref counting these helpers isolate
- [Bloc Communication](/core/bloc-communication) — the canonical `depend()` / cross-bloc example
- [System Events](/core/system-events) — the once-per-flush batching that `flush()` drains

---

# Testing

> First-party testing utilities for fast, isolated tests of your cubits and the components that use them.

Source: /testing/overview/

BlaC provides first-party testing utilities so you can write fast, isolated tests for your cubits and the components that use them. The utilities live in two entry points:

- **`@blac/core/testing`** — registry isolation, state seeding, stubs, and method mocks
- **`@blac/react/testing`** — React component rendering with controlled bloc state

Both are tree-shakable and shipped as separate entry points, so they are never included in your production bundle.

## Installation

The core testing utilities have no extra dependencies. Install your test runner of choice (Vitest is recommended):

<Tabs syncKey="pkg">

<TabItem label="pnpm">

```bash
pnpm add -D vitest
```

</TabItem>

<TabItem label="npm">

```bash
npm install -D vitest
```

</TabItem>

<TabItem label="yarn">

```bash
yarn add -D vitest
```

</TabItem>

</Tabs>

For React component tests, you also need `@testing-library/react`:

<Tabs syncKey="pkg">

<TabItem label="pnpm">

```bash
pnpm add -D @testing-library/react
```

</TabItem>

<TabItem label="npm">

```bash
npm install -D @testing-library/react
```

</TabItem>

<TabItem label="yarn">

```bash
yarn add -D @testing-library/react
```

</TabItem>

</Tabs>

## Why registry isolation matters

BlaC stores every bloc instance in a single global [registry](/core/instance-management). That is what lets any component call `useBloc(CounterCubit)` and reach the _same_ instance without prop drilling. In tests, that same shared-by-default behavior works against you: a bloc created or mutated in one test is still in the registry when the next test runs, so tests leak state into each other and fail depending on execution order.

The mental model for testing BlaC is therefore simple: **give every test its own registry.** Once each test starts from an empty registry, the shared-instance model becomes a feature again — you seed exactly the instances a test needs and nothing carries over.

Every testing utility in this guide is built around that idea. The most common approach is `blacTestSetup()`, which swaps in a fresh registry before each test and restores the original after:

```ts
import { describe, it, expect } from 'vite-plus/test';
import { blacTestSetup } from '@blac/core/testing';
import { ensure } from '@blac/core';

blacTestSetup();

describe('CounterCubit', () => {
  it('starts at zero', () => {
    const counter = ensure(CounterCubit);
    expect(counter.state.count).toBe(0);
  });

  it('does not see state from the previous test', () => {
    // This test gets a completely fresh registry
    const counter = ensure(CounterCubit);
    expect(counter.state.count).toBe(0);
  });
});
```

## Quick start

### Testing a cubit in isolation

```ts
import { it, expect } from 'vite-plus/test';
import { blacTestSetup, withBlocState } from '@blac/core/testing';
import { ensure } from '@blac/core';
import { TodoCubit } from '../blocs/TodoCubit';

blacTestSetup();

it('adds an item', () => {
  const todo = ensure(TodoCubit);
  todo.addItem('Buy milk');
  expect(todo.state.items).toHaveLength(1);
});

it('can start with seeded state', () => {
  withBlocState(TodoCubit, { items: ['Existing item'] });
  const todo = ensure(TodoCubit);
  expect(todo.state.items).toHaveLength(1);
});
```

### Testing a React component

```tsx
import { it, expect } from 'vite-plus/test';
import { screen } from '@testing-library/react';
import { renderWithBloc } from '@blac/react/testing';
import { Counter } from '../components/Counter';
import { CounterCubit } from '../blocs/CounterCubit';

it('displays the current count', () => {
  renderWithBloc(<Counter />, {
    bloc: CounterCubit,
    state: { count: 42 },
  });
  expect(screen.getByText('42')).toBeInTheDocument();
});
```

:::caution[Import test globals from `vite-plus/test`]
This project runs tests through `vite-plus`, so `describe`/`it`/`expect`/`vi` are imported from `vite-plus/test`, not from `vitest` directly:

```ts
import { describe, it, expect, vi } from 'vite-plus/test';
```

Tests still run if you import bare globals, but linting fails. If you use a different runner, substitute its import — the BlaC helpers themselves are runner-agnostic.
:::

:::danger[Common mistakes]

- **Forgetting `blacTestSetup()`** (or another isolation helper). Without it, a bloc mutated in one test survives into the next and you get order-dependent, flaky failures — exactly the problem isolation exists to prevent. See [Core Testing API](/testing/core) for the lower-level alternatives.
- **Asserting on async state too early.** State changes are flushed on a microtask, so a value set inside an async action may not be visible on the very next line. `await flush()` (or React Testing Library's `findBy*` queries) before asserting. See [System Events](/core/system-events) for the batching model.
  :::

## See also

- [Core Testing API](/testing/core) — the full helper reference (`blacTestSetup`, stubs, overrides, seeding)
- [React Testing API](/testing/react) — rendering components with controlled bloc state
- [Instance Management](/core/instance-management) — the registry these helpers isolate
- [Glossary](/guide/glossary) — definitions for _registry_, _stub_, _override_, _instance key_

---

# React Testing

> Render React components with controlled bloc state in an isolated registry — renderWithBloc and renderWithRegistry, built on the core testing primitives.

Source: /testing/react/

The React testing utilities build on top of [`@blac/core/testing`](/testing/core) and `@testing-library/react` to provide a simple way to render components with controlled bloc state. They follow the same principle as the core helpers: render the component into a fresh, isolated [registry](/core/instance-management) so each test starts from a known set of bloc instances.

```ts
import { renderWithBloc, renderWithRegistry } from '@blac/react/testing';
```

:::tip[Which one do I use?]

- **One bloc to control?** Reach for `renderWithBloc` — it stubs and registers a single bloc in one call.
- **Multiple blocs, or fine-grained setup?** Use `renderWithRegistry` and configure the registry yourself in a callback.

Both isolate the registry and restore it on unmount, so they compose freely with `blacTestSetup()`.
:::

:::note[Test globals]
As elsewhere in this project, import `describe`/`it`/`expect`/`vi` from [`vite-plus/test`](/testing/overview#why-registry-isolation-matters). The examples below also use `userEvent`, which comes from `@testing-library/user-event`.
:::

:::tip
`@testing-library/react` is an optional peer dependency of `@blac/react`. Install it alongside your test runner to use these utilities.
:::

## `renderWithBloc(ui, options)`

```ts
function renderWithBloc<T extends StateContainerConstructor>(
  ui: ReactElement,
  options: {
    bloc: T;
    state?: Partial<ExtractState<T>>;
    methods?: Partial<Record<MethodKeys<InstanceType<T>>, Function>>;
    args?: ExtractArgs<T>;
    deps?: Partial<ExtractDeps<T>>;
  },
): RenderResult & { bloc: InstanceType<T> };
```

Renders a React component with a single bloc pre-configured in an isolated registry. Under the hood it:

1. Creates a fresh test registry
2. Creates a cubit stub with the provided options (`state`, `methods`, `args`, `deps`)
3. Registers it as an override keyed by the resolved `args` value
4. Renders the component via `@testing-library/react`
5. Wraps `unmount()` to restore the previous registry

The returned object is the standard `RenderResult` from Testing Library, plus a `bloc` property containing the stub instance.

Aside from `bloc`, the options are exactly the [`createCubitStub`](/testing/core#create-cubit-stub) options — including `args` (to run `init()`) and `deps` (to fire `onDepsChanged`). See [Inputs](/guide/inputs) for what those lanes mean.

### Basic usage

```tsx
import { it, expect } from 'vite-plus/test';
import { screen } from '@testing-library/react';
import { renderWithBloc } from '@blac/react/testing';

it('displays the count', () => {
  renderWithBloc(<Counter />, {
    bloc: CounterCubit,
    state: { count: 7 },
  });
  expect(screen.getByText('7')).toBeInTheDocument();
});
```

### Interacting with the bloc

The returned `bloc` is the live stub instance. Mutate it to test how your component responds to state changes:

```tsx
import { act } from '@testing-library/react';

it('updates when count changes', () => {
  const { bloc } = renderWithBloc(<Counter />, {
    bloc: CounterCubit,
    state: { count: 0 },
  });

  act(() => bloc.increment());
  expect(screen.getByText('1')).toBeInTheDocument();
});
```

:::tip[`act()` vs `userEvent`]
Wrap **direct bloc mutations** (`bloc.increment()`) in `act()` so React processes the resulting re-render before you assert. For **user-driven interactions** (typing, clicking), prefer `userEvent` — it already wraps its actions in `act()`, so you do not need to add your own. As a rule: reach into the bloc → `act()`; drive the UI → `userEvent`.
:::

### Mocking methods

Pass `methods` to replace specific methods on the stub. This is useful for intercepting side effects like API calls or navigation:

```tsx
import { it, expect, vi } from 'vite-plus/test';
import { screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

it('calls save on form submit', async () => {
  const mockSave = vi.fn();
  renderWithBloc(<SettingsForm />, {
    bloc: SettingsCubit,
    state: { theme: 'dark', locale: 'en' },
    methods: { save: mockSave },
  });

  await userEvent.click(screen.getByRole('button', { name: 'Save' }));
  expect(mockSave).toHaveBeenCalled();
});
```

### Named instances

If your component keys a bloc by `args` (e.g. `useBloc(EditorCubit, { args: { docId } })`), pass the same `args` so the stub registers under the matching instance key:

```tsx
it('renders the correct editor', () => {
  renderWithBloc(<Editor docId="doc-42" />, {
    bloc: EditorCubit,
    state: { content: 'Hello world' },
    args: { docId: 'doc-42' },
  });
  expect(screen.getByText('Hello world')).toBeInTheDocument();
});
```

:::caution[Match the resolved instance key]
The `args` you pass must resolve to the same key your component's `useBloc` resolves to — `renderWithBloc` runs them through the same `static key`/structural-hash resolution. There is no separate string-key option; identity always flows through `args`. See [Inputs](/guide/inputs) for how identity is resolved.
:::

### `args`- and `deps`-based blocs

When a component renders a bloc that takes `args` or `deps`, you can pre-build the stub with those lanes so the component sees fully-initialized state. Pass `args` (runs `init()`) and `deps` (fires `onDepsChanged`) right alongside `state`:

```tsx
it('renders a profile seeded from args and deps', () => {
  // function Profile() {
  //   const [s] = useBloc(ProfileCubit, { args: { name: 'Alice' } });
  //   // deps are wired from a mount effect in app code; the test seeds them below.
  //   ...
  // }
  const { bloc } = renderWithBloc(<Profile />, {
    bloc: ProfileCubit,
    args: { name: 'Alice' },
    deps: { token: 'secret' },
  });

  expect(bloc.state.displayName).toBe('Alice');
  expect(screen.getByText('Alice')).toBeInTheDocument();
});
```

Because the stub is seeded before render, the component reads the initialized state on its very first paint — no `flush()` needed for the initial values.

## `renderWithRegistry(ui, setup)`

```ts
function renderWithRegistry(
  ui: ReactElement,
  setup: (registry: StateContainerRegistry) => void,
): RenderResult;
```

Renders a component with a fresh registry that you configure via a callback. Use this when a component depends on multiple blocs, or when you need more control than `renderWithBloc` provides.

### Multi-bloc components

```tsx
import { it, expect } from 'vite-plus/test';
import { screen } from '@testing-library/react';
import { renderWithRegistry } from '@blac/react/testing';
import { createCubitStub, registerOverride } from '@blac/core/testing';

it('shows dashboard with user and cart data', () => {
  renderWithRegistry(<Dashboard />, () => {
    registerOverride(
      AuthCubit,
      createCubitStub(AuthCubit, {
        state: { loggedIn: true, name: 'Alice' },
      }),
    );
    registerOverride(
      CartCubit,
      createCubitStub(CartCubit, {
        state: { items: [{ id: '1', name: 'Widget', price: 9.99 }] },
      }),
    );
  });

  expect(screen.getByText('Alice')).toBeInTheDocument();
  expect(screen.getByText('$9.99')).toBeInTheDocument();
});
```

### Mixing with core helpers

The setup callback runs with the test registry active, so all `@blac/core/testing` helpers work inside it:

```tsx
import { withBlocState, withBlocMethod } from '@blac/core/testing';

it('renders notification list', () => {
  renderWithRegistry(<NotificationPanel />, () => {
    withBlocState(AuthCubit, { loggedIn: true, userId: 'u1' });
    withBlocState(NotificationCubit, {
      items: [
        { id: '1', message: 'Welcome!', read: false },
        { id: '2', message: 'New feature', read: true },
      ],
    });
  });

  expect(screen.getByText('Welcome!')).toBeInTheDocument();
  expect(screen.getAllByRole('listitem')).toHaveLength(2);
});
```

## Cleanup

Both `renderWithBloc` and `renderWithRegistry` wrap the Testing Library `unmount()` to restore the original registry. This means cleanup happens automatically when:

- You call `unmount()` on the render result
- Testing Library's `cleanup()` runs (automatic in most setups)

If you're also using `blacTestSetup()` in the same file, that's fine — they don't conflict. The `afterEach` hook from `blacTestSetup` provides an extra safety net.

## Common patterns

### Testing loading states

```tsx
it('shows a spinner while loading', () => {
  renderWithBloc(<ArticleList />, {
    bloc: ArticleCubit,
    state: { articles: [], status: 'loading', error: null },
  });
  expect(screen.getByRole('progressbar')).toBeInTheDocument();
});

it('shows articles after load', () => {
  renderWithBloc(<ArticleList />, {
    bloc: ArticleCubit,
    state: {
      articles: [{ id: '1', title: 'Hello' }],
      status: 'success',
      error: null,
    },
  });
  expect(screen.getByText('Hello')).toBeInTheDocument();
  expect(screen.queryByRole('progressbar')).not.toBeInTheDocument();
});

it('shows error message on failure', () => {
  renderWithBloc(<ArticleList />, {
    bloc: ArticleCubit,
    state: { articles: [], status: 'error', error: 'Network error' },
  });
  expect(screen.getByText('Network error')).toBeInTheDocument();
});
```

### Testing user interactions

```tsx
import { it, expect } from 'vite-plus/test';
import { screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

it('adds a todo item', async () => {
  const { bloc } = renderWithBloc(<TodoApp />, {
    bloc: TodoCubit,
    state: { items: [], filter: 'all' },
  });

  await userEvent.type(screen.getByRole('textbox'), 'Buy milk');
  await userEvent.click(screen.getByRole('button', { name: 'Add' }));

  expect(bloc.state.items).toContainEqual(
    expect.objectContaining({ text: 'Buy milk' }),
  );
});
```

### Testing components with `onMount`

Components that use `onMount` to trigger data loading can have that method mocked:

```tsx
import { it, expect, vi } from 'vite-plus/test';

it('calls fetchData on mount', () => {
  const mockFetch = vi.fn();
  renderWithBloc(<DataView />, {
    bloc: DataCubit,
    state: { items: [], status: 'idle' },
    methods: { fetchData: mockFetch },
  });

  expect(mockFetch).toHaveBeenCalledOnce();
});
```

### Testing components that read getters

Components using `bloc.total` or similar getters work naturally since the stub is a real instance:

```tsx
it('displays computed total', () => {
  renderWithBloc(<CartSummary />, {
    bloc: CartCubit,
    state: {
      items: [
        { id: '1', price: 10 },
        { id: '2', price: 20 },
      ],
    },
  });
  expect(screen.getByText('$30')).toBeInTheDocument();
});
```

The getter runs against real state, so you test real logic — not a mocked return value.

:::danger[Common mistakes]

- **Mismatched args key.** If the component resolves a named or args-keyed instance but you register the stub under different args (or no args), the component will spin up its own real instance and ignore your stub. Pass the same `args` to `renderWithBloc` that the component passes to `useBloc` so the resolved keys match.
- **Asserting before React commits.** Direct bloc mutations need `act()`; user-driven flows need `await userEvent...`; async data needs `await screen.findBy*` (or `await flush()` then a sync query). A missing `await` is the usual cause of "the test sees the old UI."
:::

## See also

- [Core Testing API](/testing/core) — the stub/override/seeding primitives these helpers wrap
- [Testing Overview](/testing/overview) — registry isolation and the import convention
- [useBloc](/react/use-bloc) — the hook your components use, and how it resolves instance identity
- [Inputs](/guide/inputs) — the `args` / `deps` lanes you seed in tests

---

# Next.js

> BlaC works in Next.js without extra packages — register server-side state isolation like any SSR app and keep blocs in Client Components.

Source: /integrations/nextjs/

BlaC works in Next.js without extra packages. The main considerations are (1) registering server-side state isolation the same way as any SSR app, and (2) understanding which rendering boundary owns your blocs.

## App Router

### Mark bloc-consuming components `'use client'`

Blocs live in JavaScript module state and require browser APIs (event listeners, subscriptions). Any component that calls `useBloc` must be a Client Component:

```tsx
'use client';

import { useBloc } from '@blac/react';
import { Cubit } from '@blac/core';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  increment = () => this.update((s) => ({ count: s.count + 1 }));
}

export function Counter() {
  const [state, cubit] = useBloc(CounterCubit);
  return <button onClick={cubit.increment}>Count: {state.count}</button>;
}
```

### Do not read or write blocs in Server Components

Server Components run on the server, in the same Node.js process that handles every request. The module-level registry is shared across all concurrent requests in that process. Reading or mutating a bloc from a Server Component is a **data-leakage hazard** — see [SSR & per-request isolation](/integrations/ssr) for the full explanation.

:::danger[Do not call registry functions from Server Components]
Calling `acquire`, `ensure`, `borrow`, `watch`, or any other registry function inside a Server Component shares the module-level singleton across requests.

```tsx
// BAD — Server Component touching the registry
// This leaks state between concurrent users.
import { ensure } from '@blac/core';
import { UserCubit } from './UserCubit';

export default function UserPage() {
  // acquire / ensure / borrow in a Server Component = cross-request leak
  const user = ensure(UserCubit);
  return <div>{user.state.name}</div>;
}
```

Pass server-fetched data down as props instead, then feed it to blocs via `args` in a Client Component.
:::

### Feeding server data to blocs via args

Fetch data in the Server Component and pass it as props. Receive the props in a Client Component and forward them to `useBloc` as `args` so the bloc's `init` method can set the initial state before the first render:

```tsx
// app/users/[id]/page.tsx  — Server Component (no 'use client')
import { UserCard } from './UserCard';

export default async function UserPage({ params }: { params: { id: string } }) {
  // Fetch happens on the server; no blocs involved here.
  const userData = await fetch(`/api/users/${params.id}`).then((r) => r.json());
  return <UserCard initialData={userData} userId={params.id} />;
}
```

```tsx
// app/users/[id]/UserCard.tsx — Client Component
'use client';

import { useBloc } from '@blac/react';
import { Cubit } from '@blac/core';

interface UserState {
  name: string;
  bio: string;
}
interface UserArgs {
  userId: string;
  initialData: UserState;
}

class UserCardCubit extends Cubit<UserState, UserArgs> {
  protected init(args: UserArgs) {
    this.update(() => args.initialData);
  }
}

interface Props {
  userId: string;
  initialData: UserState;
}

export function UserCard({ userId, initialData }: Props) {
  const [state] = useBloc(UserCardCubit, { args: { userId, initialData } });
  return <div>{state.name}</div>;
}
```

The `args` value keys the instance (different `userId` → different instance) and is passed to `init` once at creation — the initial state is correct on the first render, no flash.

### Store-per-request for route handlers and Server Actions

If you need to invoke bloc logic inside a route handler, a Server Action, or `generateStaticParams`, follow the same registry-isolation pattern as any Node.js SSR handler. Each request gets its own registry:

```ts
import { AsyncLocalStorage } from 'node:async_hooks';
import {
  StateContainerRegistry,
  setRegistry,
  globalRegistry,
} from '@blac/core';

const registryStore = new AsyncLocalStorage<StateContainerRegistry>();

async function withRequestRegistry<T>(fn: () => Promise<T>): Promise<T> {
  const requestRegistry = new StateContainerRegistry();
  return registryStore.run(requestRegistry, async () => {
    setRegistry(requestRegistry);
    try {
      return await fn();
    } finally {
      requestRegistry.clearAll();
      setRegistry(globalRegistry);
    }
  });
}
```

```ts
// app/api/summary/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { withRequestRegistry } from '@/lib/registry';
import { acquire, release } from '@blac/core';
import { SummaryCubit } from '@/blocs/SummaryCubit';

export async function GET(req: NextRequest) {
  const result = await withRequestRegistry(async () => {
    const bloc = acquire(SummaryCubit);
    await bloc.generate(req.nextUrl.searchParams.get('q') ?? '');
    const summary = bloc.state.text;
    release(SummaryCubit);
    return summary;
  });
  return NextResponse.json({ summary: result });
}
```

See [SSR & per-request isolation](/integrations/ssr) for the full treatment of the `withRequestRegistry` helper and the async-concurrency caveats.

## Pages Router

The Pages Router uses `getServerSideProps` (or `getStaticProps`) to fetch data and `_app.tsx` for global layout. The rules are the same: do not touch the registry in server-side data-fetching functions, and mark any component using `useBloc` as a Client Component — in the Pages Router this just means writing a normal component; there is no `'use client'` directive, but the file is always bundled for the browser.

### Seeding initial state via getServerSideProps

Pass server data as page props and receive them in a Client Component — the same pattern as the App Router:

```tsx
// pages/users/[id].tsx
import type { GetServerSideProps } from 'next';
import { UserCard } from '@/components/UserCard';

interface UserData {
  name: string;
  bio: string;
}
interface PageProps {
  userId: string;
  initialData: UserData;
}

export const getServerSideProps: GetServerSideProps<PageProps> = async (
  ctx,
) => {
  // Fetch data server-side; no blocs here.
  const userId = ctx.params?.id as string;
  const initialData: UserData = await fetch(
    `https://api.example.com/users/${userId}`,
  ).then((r) => r.json());
  return { props: { userId, initialData } };
};

export default function UserPage({ userId, initialData }: PageProps) {
  return <UserCard userId={userId} initialData={initialData} />;
}
```

`UserCard` is a regular component that calls `useBloc` — exactly the same as the App Router example above. No extra Next.js-specific plumbing is needed.

## Plugin setup

Install plugins in a module that is imported once by the client bundle — the Next.js equivalent is `app/providers.tsx` (App Router) or `pages/_app.tsx` (Pages Router):

```tsx
// app/providers.tsx  (App Router)
'use client';

import { getPluginManager } from '@blac/core';
import { createIndexedDbPersistPlugin } from '@blac/plugin-persist';
import { UserSettingsCubit } from '@/blocs/UserSettingsCubit';

const persist = createIndexedDbPersistPlugin();
persist.persist(UserSettingsCubit);
getPluginManager().install(persist);

export function Providers({ children }: { children: React.ReactNode }) {
  return <>{children}</>;
}
```

Plugins that use browser APIs (IndexedDB, `localStorage`) are safe here because `'use client'` ensures they only run in the browser bundle.

## See also

- [SSR & per-request isolation](/integrations/ssr) — the `withRequestRegistry` pattern and the async-concurrency caveats
- [Passing Inputs](/guide/inputs) — `args`, `init`, and instance identity
- [Instance Management](/core/instance-management) — `acquire`, `release`, and the ref-counting lifecycle
- [Persistence Plugin](/plugins/persistence) — IndexedDB persistence setup

---

# Using BlaC outside React

> @blac/core has no dependency on React — use blocs in vanilla JS, Node.js, or any framework via watch (observe) and acquire/release (own the lifecycle).

Source: /integrations/outside-react/

`@blac/core` has no dependency on React. You can use blocs in vanilla JavaScript, Node.js scripts, worker threads, or any framework — without `@blac/react` installed. This page covers the two main patterns: **observing** state with `watch` and **owning** the lifecycle with `acquire`/`release`.

## Observing state with `watch`

`watch` is the primary way to react to state changes outside a component. It creates a subscription, fires the callback once immediately with the current state, and then on every subsequent change.

```ts twoslash
import { watch, Cubit } from '@blac/core';

class AuthCubit extends Cubit<{ token: string | null }> {
  constructor() {
    super({ token: null });
  }

  setToken = (token: string) => this.update(() => ({ token }));
  logout = () => this.update(() => ({ token: null }));
}

// Subscribe — fires immediately, then on every change.
const stop = watch(AuthCubit, (auth) => {
  if (auth.state.token) {
    console.log('Signed in:', auth.state.token.slice(0, 8) + '...');
  } else {
    console.log('Signed out');
  }
});

// Tear down when no longer needed.
stop();
```

`watch` returns a `stop` function. Always call it when the subscription is no longer needed. Forgetting is the most common outside-React leak — a subscription you never stop keeps the bloc alive and runs your callback for the life of the process. See [watch](/core/watch) for the full API.

### Watching multiple blocs

Pass a `readonly` array to observe several blocs at once. The callback fires when **any** of them changes:

```ts twoslash
import { watch, Cubit } from '@blac/core';

class UserCubit extends Cubit<{ name: string }> {
  constructor() {
    super({ name: '' });
  }
}

class ThemeCubit extends Cubit<{ mode: 'light' | 'dark' }> {
  constructor() {
    super({ mode: 'light' });
  }
}

declare function updateDocTitle(name: string, mode: string): void;

const stop = watch([UserCubit, ThemeCubit] as const, ([user, theme]) => {
  updateDocTitle(user.state.name, theme.state.mode);
});

// Call stop() when tearing down
stop();
```

### Self-terminating watches

Return `watch.STOP` from the callback to unsubscribe after a condition is met — useful for one-shot observations:

```ts twoslash
import { watch, Cubit } from '@blac/core';

class AppCubit extends Cubit<{ ready: boolean }> {
  constructor() {
    super({ ready: false });
  }
}

declare function startWorker(): void;

watch(AppCubit, (app) => {
  if (app.state.ready) {
    startWorker();
    return watch.STOP; // unsubscribes after the first match
  }
});
```

## Managing lifecycle with acquire and release

In React, `useBloc` owns the `acquire`/`release` pair for you. Outside React you call them directly. Every `acquire` increments the ref count; the matching `release` decrements it. At ref count zero the instance is disposed.

```ts twoslash
import { acquire, release, Cubit } from '@blac/core';

class TaskQueueCubit extends Cubit<{ pending: number }> {
  constructor() {
    super({ pending: 0 });
  }
  enqueue = () => this.update((s) => ({ pending: s.pending + 1 }));
  dequeue = () => this.update((s) => ({ pending: Math.max(0, s.pending - 1) }));
}

// Acquire a ref — the instance is created on first acquire.
const queue = acquire(TaskQueueCubit);

queue.enqueue();
console.log(queue.state.pending); // 1

// Release when done — drops the ref count.
// At ref count 0 the instance is disposed (unless keepAlive).
release(TaskQueueCubit);
```

:::danger[Pair every acquire with a release]
A missing `release` is an instance leak: the ref count never reaches zero, the bloc never disposes, and any subscriptions and timers it holds run forever. Use a `try/finally` when the release might be skipped due to an error:

```ts twoslash
import { acquire, release, Cubit } from '@blac/core';

class ReportCubit extends Cubit<{ data: string[] }> {
  constructor() {
    super({ data: [] });
  }
}

declare function processData(data: string[]): Promise<void>;

async function runReport() {
  const report = acquire(ReportCubit);
  try {
    await processData(report.state.data);
  } finally {
    // Runs even if processData throws.
    release(ReportCubit);
  }
}
```

:::

### Read-only access without a ref

If you only need to read the current state and do not need to keep the instance alive, use `borrow` (throws if absent) or `borrowSafe` (returns an error object). Neither takes a ref, so no `release` is needed:

```ts twoslash
import { borrow, borrowSafe, Cubit } from '@blac/core';

class ConfigCubit extends Cubit<{ apiUrl: string }> {
  constructor() {
    super({ apiUrl: '' });
  }
}

// borrow: throws if the instance does not exist.
// Use when absence is a programming error.
const url = borrow(ConfigCubit).state.apiUrl;

// borrowSafe: discriminated union instead of throwing.
// Use when absence is expected.
const result = borrowSafe(ConfigCubit);
if (result.error) {
  console.warn('Config not initialized');
} else {
  console.log(result.instance.state.apiUrl);
}
```

### Combining watch with acquire

`watch` calls `ensure` internally — it does not take a ref. If you need both a stable subscription **and** a ref (to keep the instance alive while nothing else holds it), `acquire` first, then `watch`:

```ts twoslash
import { acquire, release, watch, Cubit } from '@blac/core';

class MetricsCubit extends Cubit<{ fps: number }> {
  constructor() {
    super({ fps: 0 });
  }
}

declare function updateDashboard(fps: number): void;

// Keep the instance alive + observe changes.
const metrics = acquire(MetricsCubit);

const stop = watch(MetricsCubit, (m) => {
  updateDashboard(m.state.fps);
});

// On teardown — stop watching first, then release the ref.
function teardown() {
  stop();
  release(MetricsCubit);
}
```

## Node.js scripts and worker threads

Blocs work in Node.js without any changes. The module-level registry is per-module-graph, so in a single Node process the same singleton rules apply as in a browser tab.

For **worker threads** (`node:worker_threads`), each worker has its own module graph and therefore its own registry. Blocs do not cross thread boundaries — pass data between threads via the standard `postMessage` / `MessageChannel` API.

For **long-running servers** that handle multiple requests in the same process, apply the [per-request registry isolation](/integrations/ssr) pattern to prevent state bleed between concurrent users.

```ts twoslash
import { watch, acquire, release, Cubit } from '@blac/core';

class JobCubit extends Cubit<{ status: 'idle' | 'running' | 'done' }> {
  constructor() {
    super({ status: 'idle' });
  }
  start = () => this.update(() => ({ status: 'running' }));
  finish = () => this.update(() => ({ status: 'done' }));
}

// Node.js CLI script — no React, no browser.
const job = acquire(JobCubit);

// Watch for completion then exit.
watch(JobCubit, (j) => {
  if (j.state.status === 'done') {
    console.log('Job complete');
    return watch.STOP;
  }
});

job.start();
// ... do work ...
job.finish(); // callback fires, prints "Job complete"

release(JobCubit);
```

## See also

- [watch](/core/watch) — full API, `instance()` references, `watch.STOP`, and the coalescing model
- [Instance Management](/core/instance-management) — the full registry API: `acquire`, `release`, `borrow`, `ensure`, `clearAll`
- [SSR & per-request isolation](/integrations/ssr) — isolating the registry in long-lived server processes
- [Testing core logic](/testing/core) — `clearAll` for isolating the registry between tests

---

# React Native

> BlaC's core and React bindings run in React Native unchanged — the one feature that needs a platform adapter is persistence, with an AsyncStorage adapter example.

Source: /integrations/react-native/

BlaC's core and React bindings are platform-agnostic JavaScript — `@blac/core` and `@blac/react` install and run in React Native without modification. The one feature that needs a platform adapter is **persistence**: the built-in persist plugin uses IndexedDB, which does not exist in React Native. This page covers both topics.

## Installation

```bash
# npm / yarn / bun
npm install @blac/core @blac/react
```

`useBloc`, `watch`, `Cubit`, and every other core API work the same in React Native as in the browser. No polyfills are needed for the core reactive machinery.

## Basic usage

Nothing React Native-specific is required:

```tsx
import { useBloc } from '@blac/react';
import { Cubit } from '@blac/core';

interface CounterState {
  count: number;
}

class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0 });
  }
  increment = () => this.update((s) => ({ count: s.count + 1 }));
}

export function Counter() {
  const [state, cubit] = useBloc(CounterCubit);
  return (
    <View>
      <Text>{state.count}</Text>
      <Button title="+" onPress={cubit.increment} />
    </View>
  );
}
```

## Persistence: writing an AsyncStorage adapter

The official persist plugin ships one built-in adapter: `NativeIndexedDbAdapter`, which uses the global `indexedDB` (`isAvailable()` checks `typeof indexedDB !== 'undefined'`). That API does not exist in React Native. The plugin's adapter interface is designed to be replaced — supply a custom `adapter` option that wraps React Native's `AsyncStorage` instead.

### The adapter interface

```ts
// IndexedDbPersistAdapter — four async methods + one sync availability check:
//
// isAvailable(): boolean
// get<T>(key: string): Promise<PersistedRecord<T> | null>
// put<T>(record: PersistedRecord<T>): Promise<void>
// delete(key: string): Promise<void>
// clear(): Promise<void>
```

### AsyncStorage adapter implementation

Install `@react-native-async-storage/async-storage` if you have not already, then implement the adapter:

```ts
import type {
  IndexedDbPersistAdapter,
  PersistedRecord,
} from '@blac/plugin-persist';

// AsyncStorage type stub — the real type comes from
// @react-native-async-storage/async-storage
interface AsyncStorageLike {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
  getAllKeys(): Promise<readonly string[]>;
  multiRemove(keys: string[]): Promise<void>;
}

/**
 * AsyncStorage adapter for @blac/plugin-persist.
 *
 * Pass this to createIndexedDbPersistPlugin({ adapter: asyncStorageAdapter })
 * to use React Native AsyncStorage instead of IndexedDB.
 */
export function createAsyncStorageAdapter(
  storage: AsyncStorageLike,
  namespace = 'blac:',
): IndexedDbPersistAdapter {
  const prefixed = (key: string) => `${namespace}${key}`;

  return {
    isAvailable() {
      // AsyncStorage is always available in React Native.
      return true;
    },

    async get<T>(key: string): Promise<PersistedRecord<T> | null> {
      const raw = await storage.getItem(prefixed(key));
      if (raw === null) return null;
      try {
        return JSON.parse(raw) as PersistedRecord<T>;
      } catch {
        return null;
      }
    },

    async put<T>(record: PersistedRecord<T>): Promise<void> {
      await storage.setItem(prefixed(record.id), JSON.stringify(record));
    },

    async delete(key: string): Promise<void> {
      await storage.removeItem(prefixed(key));
    },

    async clear(): Promise<void> {
      const all = await storage.getAllKeys();
      const ours = (all as string[]).filter((k) => k.startsWith(namespace));
      if (ours.length > 0) {
        await storage.multiRemove(ours);
      }
    },
  };
}
```

### Wiring it up

Create the plugin with the custom adapter once at app startup:

```ts
import { createIndexedDbPersistPlugin } from '@blac/plugin-persist';
import { getPluginManager } from '@blac/core';
// import AsyncStorage from '@react-native-async-storage/async-storage';

const persist = createIndexedDbPersistPlugin({
  adapter: createAsyncStorageAdapter(AsyncStorage),
});

persist.persist(UserSettingsCubit);
getPluginManager().install(persist);
```

From this point on `UserSettingsCubit` state is saved through AsyncStorage and restored when the instance is created — the same lifecycle as the IndexedDB adapter, only the storage backend differs.

:::note[Serialization constraints]
The same constraint as the browser plugin applies: state must be JSON-serializable. Functions, class instances, `Map`, `Set`, and any value that does not survive `JSON.parse(JSON.stringify(v))` cannot be persisted. Use `stateToDb` / `dbToState` to project to and from a serializable shape when needed. See [Persistence Plugin: registration options](/plugins/persistence#registration-options).
:::

## See also

- [Persistence Plugin](/plugins/persistence) — full plugin API, registration options, status monitoring, and `$blac.hydration.wait()`
- [Instance Management](/core/instance-management) — `acquire`, `release`, and the registry lifecycle
- [watch](/core/watch) — observing blocs outside React (useful for imperative React Native patterns)
- [Passing Inputs](/guide/inputs) — `args` and instance identity

---

# Remix

> Seed each bloc's initial state from Remix loader data via init(args) so server-rendered HTML and the client's initial state match without hydration mismatches.

Source: /integrations/remix/

Remix runs loaders and actions on the server for every navigation, then hydrates the same component tree in the browser. BlaC's job is to make sure the server-rendered HTML and the client's initial state **match**, preventing hydration mismatches.

## The hydration challenge

Remix loaders return data that the server uses to render HTML. After the page reaches the browser, React hydrates the existing HTML by running the component tree again. If a bloc's initial state on the client differs from what the server rendered, React reports a hydration mismatch.

The fix is to seed each bloc's initial state from the loader data via `init(args)` so both renders start from the same snapshot.

## Seeding blocs from loader data

A Remix loader is a server function — do not call registry functions there. Instead, return the data as JSON, receive it in the component, and forward it to `useBloc` as `args`:

```ts twoslash
// app/routes/product.$id.tsx  — loader
import type { Cubit } from '@blac/core';

// Type stubs — replace with your actual loader return type
declare function json<T>(data: T): { data: T };
declare function fetchProduct(
  id: string,
): Promise<{ id: string; title: string; price: number }>;

type LoaderArgs = { params: { id: string } };

export async function loader({ params }: LoaderArgs) {
  const product = await fetchProduct(params.id);
  return json({ product });
}
```

```tsx
// app/routes/product.$id.tsx  — component (runs on server and client)
import { useLoaderData } from '@remix-run/react';
import { useBloc } from '@blac/react';
import { Cubit } from '@blac/core';

interface ProductState {
  id: string;
  title: string;
  price: number;
}
interface ProductArgs {
  productId: string;
  initialData: ProductState;
}

class ProductCubit extends Cubit<ProductState, ProductArgs> {
  protected init(args: ProductArgs) {
    // Called once at instance creation, before the first snapshot.
    // Both the server render and the client hydration call this with the
    // same args, so the initial state is identical on both sides.
    this.update(() => args.initialData);
  }

  addToCart = () => {
    /* ... */
  };
}

export default function ProductPage() {
  const { product } = useLoaderData<typeof loader>();

  // args keys the instance (productId) and seeds init().
  // Server render and client hydration both pass the same args.
  const [state, cubit] = useBloc(ProductCubit, {
    args: { productId: product.id, initialData: product },
  });

  return (
    <div>
      <h1>{state.title}</h1>
      <p>${state.price}</p>
      <button onClick={cubit.addToCart}>Add to cart</button>
    </div>
  );
}
```

`init(args)` runs synchronously before the first state snapshot, so the bloc's initial state on the server and the client are identical. React hydrates without a mismatch.

:::note[Why not call the loader data directly in the constructor?]
The constructor runs at instance creation, but `useLoaderData` is a hook — it can only be called from a component. `init(args)` is the bridge: it is called by the framework from inside `useBloc` with the `args` you provided, giving the bloc access to per-render data at the right moment.
:::

## Mutations via actions and bloc methods

Actions are Remix's server-side mutation path. After an action, Remix re-runs the loader and re-renders. Blocs handle optimistic UI and local state changes; the loader refetch propagates server state back:

```tsx
import { useFetcher, useLoaderData } from '@remix-run/react';
import { useBloc } from '@blac/react';

// (CartCubit and ProductCubit definitions omitted for brevity)

export default function ProductPage() {
  const { product } = useLoaderData<typeof loader>();
  const [state, cubit] = useBloc(ProductCubit, {
    args: { productId: product.id, initialData: product },
  });
  const fetcher = useFetcher();

  const handleAddToCart = () => {
    // Optimistic update in the bloc — immediate feedback
    cubit.addToCart();
    // Server-side mutation via Remix action
    fetcher.submit(
      { productId: product.id },
      { method: 'post', action: '/cart' },
    );
  };

  return (
    <div>
      <h1>{state.title}</h1>
      <button onClick={handleAddToCart}>Add to cart</button>
    </div>
  );
}
```

## Per-request isolation for Remix server code

If you call registry functions inside Remix resource routes or utility modules that run in the Node process, wrap them in `withRequestRegistry` so state does not bleed between concurrent requests. See [SSR & per-request isolation](/integrations/ssr) for the full pattern.

## Plugin setup

Install plugins in `root.tsx` so they run once in the browser. Guard with `typeof window !== 'undefined'` to prevent plugin code from running in the server-side bundle:

```tsx
// app/root.tsx
import { getPluginManager } from '@blac/core';
import { createIndexedDbPersistPlugin } from '@blac/plugin-persist';
import { UserSettingsCubit } from '~/blocs/UserSettingsCubit';

if (typeof window !== 'undefined') {
  const persist = createIndexedDbPersistPlugin();
  persist.persist(UserSettingsCubit);
  getPluginManager().install(persist);
}
```

The IndexedDB persistence plugin checks `typeof indexedDB !== 'undefined'` inside `isAvailable()` and silently disables itself when unavailable, but the guard above makes the intent explicit and avoids unnecessary code in the server bundle.

## See also

- [SSR & per-request isolation](/integrations/ssr) — per-request registry isolation and the `withRequestRegistry` helper
- [Passing Inputs](/guide/inputs) — `args`, `init`, and instance identity
- [Instance Management](/core/instance-management) — the registry and ref-counting lifecycle
- [Persistence Plugin](/plugins/persistence) — IndexedDB persistence setup

---

# SSR & per-request isolation

> BlaC's registry is a module-level singleton — on a server, give each request its own isolated registry to prevent cross-request state leakage.

Source: /integrations/ssr/

BlaC's registry is a module-level singleton. In the browser that is exactly what you want: every `useBloc` call across your app resolves the same `(class, key)` to the same instance, so state is shared with no providers. On a server, that same singleton is a problem — one process handles many requests, and a shared registry means **one user's bloc state can bleed into another user's request**.

This page names that hazard plainly and shows the fix that already ships: swapping the active registry per request via `setRegistry` / `getRegistry`, so each request gets its own isolated set of bloc instances.

## The problem: cross-request state leakage

On the client there is one user and one registry, for the life of the tab. On the server there is one **process** and one module-level registry (`globalRegistry`), but **many concurrent users**. Every registry function — `acquire`, `ensure`, `borrow`, `release`, and `watch` (which resolves via `ensure`) — routes through a single module-level variable inside `@blac/core`:

```ts
// packages/blac-core/src/registry/config.ts (verified)
let _registry = globalRegistry;

export function getRegistry(): StateContainerRegistry {
  return _registry;
}

export function setRegistry(registry: StateContainerRegistry): void {
  _registry = registry;
}
```

If nothing swaps `_registry`, **every request shares `globalRegistry`**. Concretely:

- Request A renders for user A, `acquire(SessionCubit)` creates an instance keyed `'default'` and fills it with user A's data.
- Request B renders for user B. `acquire(SessionCubit)` finds that _same_ `'default'` instance already on the shelf and reuses it — now serving user A's session data to user B.

This is not a re-render bug or a hydration mismatch. It is a correctness and **security** hole: server-rendered HTML for one user can contain another user's state. The same goes for any keyed instance whose key is not perfectly request-unique — and for `keepAlive` blocs, which by design survive ref count zero and therefore persist _across_ requests in a long-lived process.

:::danger[The cross-request leak rule]
**On the server, never let two requests share a registry.** A module-level singleton that lives for the life of the process is shared by every request that process handles. Give each request its own `StateContainerRegistry`, make it the active one for the duration of that request only, and discard it when the request ends. State that outlives a single request is a data-leak waiting to happen.
:::

## The fix: a registry per request

`@blac/core` exposes the registry as a swappable slot, not a hard-coded global. Three exports do the work:

```ts twoslash
import {
  StateContainerRegistry,
  getRegistry,
  setRegistry,
  globalRegistry,
} from '@blac/core';

// Construct a fresh, empty registry — its own instance map, no shared state.
const requestRegistry = new StateContainerRegistry();

// Make it the active registry. Every acquire/ensure/release/watch now uses it.
setRegistry(requestRegistry);

// Read the active registry (defaults to globalRegistry until you swap it).
const active: StateContainerRegistry = getRegistry();

// Restore the process-wide default when the request is done.
setRegistry(globalRegistry);
```

| Export                   | What it is                                                                                             | Role in SSR                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `StateContainerRegistry` | The registry **class**. `new StateContainerRegistry()` is an empty registry with its own instance map. | Construct one per request.                                      |
| `setRegistry(registry)`  | Sets the module-level active registry.                                                                 | Point the active slot at the request's registry.                |
| `getRegistry()`          | Returns the current active registry (initially `globalRegistry`).                                      | Read it back if you need to operate on the active one directly. |
| `globalRegistry`         | The default singleton, used until `setRegistry` is called.                                             | The value you restore the slot to after a request.              |

A fresh `StateContainerRegistry` starts empty: no registered types, no instances, no refs. Bloc classes are not pre-registered against a registry — the first `acquire`/`ensure` of a class against whichever registry is active registers and creates the instance there. So once `setRegistry(requestRegistry)` runs, the very first `acquire(SessionCubit)` in that request creates a brand-new `SessionCubit` **inside `requestRegistry`**, isolated from every other request.

:::note[There is no `registry.dispose()`]
A `StateContainerRegistry` has no whole-registry teardown method. To dispose the blocs inside one, call `registry.clearAll()` (disposes and removes every instance it holds, ignoring ref counts and `keepAlive`). If you simply drop all references to a per-request registry instead, it — and the blocs it holds — become eligible for garbage collection along with the request. Verify the surface in [Instance Management](/core/instance-management).
:::

## The pattern: scope the swap to the request

`setRegistry` is a single global slot, so the naive "set at the start of the handler, restore at the end" only works if nothing async interleaves between two requests. Under real concurrency — `await`ing a data fetch mid-render while another request runs — a bare set/restore races: request B's `setRegistry` clobbers the slot while request A is suspended.

Node's [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html) is the standard tool for request-scoped values that survive `await`. BlaC does **not** ship an `AsyncLocalStorage` integration — the exports above are the primitives. The wiring below is an **application-level pattern** you build on top of `setRegistry` / `getRegistry`: keep the per-request registry in `AsyncLocalStorage`, and make a tiny shim so `getRegistry` resolves the registry for the _current async context_ rather than a single shared variable.

```ts
import { AsyncLocalStorage } from 'node:async_hooks';
import {
  StateContainerRegistry,
  setRegistry,
  globalRegistry,
} from '@blac/core';

// One ALS for the whole process; each request stores its own registry in it.
const registryStore = new AsyncLocalStorage<StateContainerRegistry>();

// Resolve the active registry from the current async context, falling back to
// the process default for any code that runs outside a request scope.
function activeRegistry(): StateContainerRegistry {
  return registryStore.getStore() ?? globalRegistry;
}

// Run `fn` with a fresh, isolated registry that is torn down afterwards.
async function withRequestRegistry<T>(fn: () => Promise<T>): Promise<T> {
  const requestRegistry = new StateContainerRegistry();
  return registryStore.run(requestRegistry, async () => {
    // Point @blac/core's active slot at this request's registry while the
    // synchronous render runs. (See the note below on the async caveat.)
    setRegistry(requestRegistry);
    try {
      return await fn();
    } finally {
      // Dispose every bloc created during this request, then restore default.
      requestRegistry.clearAll();
      setRegistry(globalRegistry);
    }
  });
}
```

A realistic server handler then wraps the render in `withRequestRegistry` (reusing the helper defined above):

```ts
async function handleRequest(req: Request): Promise<Response> {
  const html = await withRequestRegistry(async () => {
    // Any acquire/ensure/watch reached during this render resolves against
    // THIS request's registry — never another request's, never the global one.
    return renderToString(<App url={req.url} />);
  });

  return new Response(`<!doctype html><div id="root">${html}</div>`, {
    headers: { 'content-type': 'text/html' },
  });
}
```

:::caution[The async caveat with the single global slot]
`setRegistry` mutates one process-wide variable. `AsyncLocalStorage` makes the registry available per-context, but `getRegistry()` inside `@blac/core` still reads that one variable unless you bridge the two. Two robust ways to do that:

- **Render synchronously per request.** If the render that touches blocs is synchronous (no `await` between `setRegistry(requestRegistry)` and `setRegistry(globalRegistry)`), no other request can interleave on the slot, and the bare set/restore is safe. This is the simplest correct setup and covers most `renderToString` flows.
- **Bridge `getRegistry` to your ALS.** If your render `await`s mid-flight, do not rely on the global slot during those awaits. Resolve the registry from `AsyncLocalStorage` (the `activeRegistry()` helper above) at every registry call site so each suspended request keeps reading its own registry. The exported `setRegistry`/`getRegistry` slot remains the fallback for non-request code.

Pick synchronous rendering if you can; reach for the ALS bridge only when concurrent async renders genuinely share the process.
:::

## Client hydration uses the global registry

On the client there is one registry for the whole tab, so isolation is a non-issue — do **not** call `setRegistry` in browser code. Client `useBloc` calls resolve against `globalRegistry` (the default the slot points at until something swaps it), exactly as in a non-SSR app.

That means the registries on the two sides are independent: the server's per-request registry produced the HTML string, and the client's `globalRegistry` rehydrates from scratch on mount. BlaC does not serialize the server registry into the client — blocs re-create from their constructors during hydration. If a bloc needs server-computed data to render identically on both sides, pass that data in as [`args`](/guide/inputs) (or serialize it into the page and feed it to the bloc's `init`), the same way you would seed any client-side state for hydration.

## A note on Vite / dev SSR

Under Vite's dev SSR (`vite-node`, `ssrLoadModule`) each request goes through the same module graph in one process, so the module-level registry slot is shared exactly as in production — the per-request pattern above applies unchanged in dev. The one extra hazard is **HMR**: hot-reloading the module that owns `globalRegistry`, or your ALS store, can leave you with two copies of the singleton (the old one and the freshly evaluated one) and instances split between them. If you see stale or duplicated instances only after a hot update, force a full reload rather than chasing it as a logic bug.

## See also

- [Instance Management](/core/instance-management) — the registry, ref counting, `clearAll`, and the lending-library model
- [Passing Inputs](/guide/inputs) — `args` and instance identity, the seam for feeding server data into hydration
- [Configuration](/core/configuration) — `keepAlive` (which makes cross-request persistence worse) and the circuit breakers
- [watch](/core/watch) — observing blocs outside React, and how it resolves through the active registry
- [Testing core logic](/testing/core) — `clearAll` for isolating the registry between tests, the same primitive you use per request

---

# DirtyTalk

> A family of small, framework-agnostic libraries answering one question after every mutation — what changed, who cares, and when do we tell them?

Source: /dirtytalk/

DirtyTalk is a family of small, framework-agnostic libraries built around one question: **after a mutation, what changed, who cares, and when do we tell them?** Each package answers that question in a different domain, but they all share a single move — compute "what changed" once at the source, in a format every subscriber can intersect cheaply. This page is the entry point to the whole section; it explains the shared thesis and points you to the package you actually need.

## The shared thesis

Two unrelated problems turn out to be the same problem. A WebGPU renderer mutates a scene and must repaint; a state container mutates state and must notify subscribers. Both face the same three sub-questions after every mutation:

1. **What changed?** — a region of the world the mutation touched.
2. **Who cares?** — the subscribers whose interest overlaps that region.
3. **When do we tell them?** — the scheduling window in which we batch and deliver.

The naive answer pushes all the work down to each consumer. A renderer with a single dirty bit repaints the whole canvas because the bit lost the information about _where_ the change was. A state container re-walks the entire state tree once per subscriber — N consumers means N separate tree walks doing the same equality checks. Both approaches throw away the structure of the change and pay for it on every read.

DirtyTalk's answer is to compute "what changed" **once, at the source**, and express it as a **Region** — a value in an algebra with `empty`, `union`, and `intersects`. The source accumulates a single dirty region per scheduling window. Each subscriber declares an interest region. Deciding who to wake is then just one cheap `intersects` check per subscriber against the one shared dirty region — work proportional to the number of subscribers, not to the size of the state or the scene multiplied by the number of subscribers.

:::note[Why "Region" is the right abstraction]
A single dirty bit is a Region too — but a degenerate one that only answers "did _anything_ change?" By keeping the Region rich (damage rectangles, or a set of changed paths), the source preserves exactly the information each subscriber needs to do less work: skip an undamaged screen area, or skip a re-render when an unread field changed.
:::

## The layering

DirtyTalk separates the **abstract algebra** from its **concrete instantiations**. The engine defines the shape of the problem; the two domain packages fill in what a `Region` actually is.

| Package                 | Role                                                                                                                                                                                                                                                                                                                                                                                                       | What a `Region` is         | Built for                              |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | -------------------------------------- |
| `@dirtytalk/engine`     | The abstract algebra + scheduling glue. Defines the `Space<Region>` interface (`empty` / `isEmpty` / `union` / `intersects`), the `Scheduler` interface (with `SyncScheduler`, `ManualScheduler`, `MicrotaskScheduler`, `RAFScheduler`), and `DirtyChannel<Region>` — the core that accumulates marks within a window and fans out to interested subscribers in one flush. Ships **no** concrete `Region`. | abstract — you supply one  | The shared core both domains depend on |
| `@dirtytalk/spatial`    | The concrete instantiation for 2D rendering. `RectSpace` implements `Space<DirtyRegion>` where a `Region` is a list of damage rects (`Damage` entries carrying a `Rect` and a `kind`). Adds a `SceneNode` / `SceneRoot` tree, a three-stage `data → layout → paint` pipeline, and a `PointerRouter`.                                                                                                       | a list of damage rects     | canvas / GPU renderers                 |
| `@dirtytalk/structural` | The concrete instantiation for state containers. `PathSetSpace` implements `Space<PathSet>` where a `Region` is a set of interned path IDs. Adds a `PathInterner`, a `trackRender` proxy recorder, diff helpers, and an abstract `StructuralContainer`.                                                                                                                                                    | a set of interned path IDs | observable state / data stores         |

Each domain package answers the _same_ algebra in its own terms. "Union two dirty regions" means "bounding-box-concatenate two damage lists" in spatial and "set-union two path-ID sets" in structural. "Does this interest intersect the dirty region?" means "do any rects overlap?" in spatial and "do the sets share an ID?" in structural. The `DirtyChannel` machinery — coalescing, selective fan-out, lazy interest thunks, re-entrancy handling, error isolation — is written once in the engine and reused by both.

<details>
<summary>The engine ships zero `Region` implementations — on purpose</summary>

`@dirtytalk/engine` never references React, the DOM, or a GPU, and it ships no concrete `Space`. `RectSpace` lives in spatial; `PathSetSpace` lives in structural. The engine only `union`s and `intersects` whatever Regions you hand it — producing a Region from a mutation is the consumer's job. There is no dependency graph, no auto-tracking, and no diffing at the engine layer.

</details>

## Relationship to BlaC

If you arrived here from the BlaC documentation: **BlaC is the headline product of these docs.** It is a state-container library with per-consumer path tracking, and it is a motivating consumer of the structural model — `@dirtytalk/structural` is the lower-level lineage of BlaC's per-consumer path tracking.

These DirtyTalk packages are **standalone and framework-agnostic**. You can use `@dirtytalk/engine`, `@dirtytalk/spatial`, or `@dirtytalk/structural` entirely on their own, with no React and no BlaC. This section documents that lower-level engine family directly. If you want a batteries-included state library for React, start with [the BlaC introduction](/guide/introduction); if you want the underlying machinery, read on.

## Install

<Tabs syncKey="pkg">
<TabItem label="pnpm">

```bash
# The abstract core (always available; the domain packages depend on it)
pnpm add @dirtytalk/engine

# 2D rendering domain
pnpm add @dirtytalk/spatial

# State-container domain
pnpm add @dirtytalk/structural
```

</TabItem>
<TabItem label="npm">

```bash
npm install @dirtytalk/engine
npm install @dirtytalk/spatial
npm install @dirtytalk/structural
```

</TabItem>
<TabItem label="yarn">

```bash
yarn add @dirtytalk/engine
yarn add @dirtytalk/spatial
yarn add @dirtytalk/structural
```

</TabItem>
</Tabs>

Both `@dirtytalk/spatial` and `@dirtytalk/structural` depend on `@dirtytalk/engine`, so installing either one pulls the engine in transitively. Install the engine on its own only when you are wiring up a brand-new domain with your own `Space`.

## Which package do I want?

| If you want to…                                                                                      | Use                          | Start at                                                            |
| ---------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------- |
| Track changes to a 2D scene and repaint only what moved (canvas / WebGPU)                            | `@dirtytalk/spatial`         | [Spatial getting started](/dirtytalk/spatial/getting-started)       |
| Observe a state container and wake only the consumers that read the changed fields                   | `@dirtytalk/structural`      | [Structural getting started](/dirtytalk/structural/getting-started) |
| Use BlaC's state management in a React app                                                           | `@blac/core` + `@blac/react` | [BlaC introduction](/guide/introduction)                            |
| Apply the "compute changes once, fan out cheaply" pattern to a **new** domain with your own `Region` | `@dirtytalk/engine`          | [Engine getting started](/dirtytalk/engine/getting-started)         |
| Understand the algebra and scheduling model before picking a domain                                  | `@dirtytalk/engine`          | [Engine concepts](/dirtytalk/engine/concepts)                       |

:::tip[Not sure?]
If your changes have a position on screen, you want **spatial**. If your changes are fields in an object graph, you want **structural**. If you are building neither but recognize the "what changed / who cares / when" pattern, you want the **engine** plus a `Space` of your own.
:::

## Next steps

Pick a package and dive in:

- **Engine** — the abstract core. [Getting started](/dirtytalk/engine/getting-started) builds your first `DirtyChannel`; [concepts](/dirtytalk/engine/concepts) covers the `Space` algebra, schedulers, and the `DirtyChannel` flush model.
- **Spatial** — the 2D rendering domain. [Getting started](/dirtytalk/spatial/getting-started) builds your first scene; [concepts](/dirtytalk/spatial/concepts) covers the damage model, the render pipeline, and pointer routing.
- **Structural** — the state-container domain. [Getting started](/dirtytalk/structural/getting-started) builds your first container; [concepts](/dirtytalk/structural/concepts) covers path sets, the observed skeleton, and read tracking.

## See also

- [Engine: concepts](/dirtytalk/engine/concepts) — the `Space` algebra, schedulers, and `DirtyChannel` in depth.
- [Spatial: concepts](/dirtytalk/spatial/concepts) — how damage rects drive the `data → layout → paint` pipeline.
- [Structural: concepts](/dirtytalk/structural/concepts) — interned path IDs, the skeleton, and per-consumer tracking.
- [BlaC: introduction](/guide/introduction) — the headline state library that motivated the structural model.

---

# API Reference

> The exhaustive public surface of @dirtytalk/engine, organized by export — Observable, Signal, Space, the four schedulers, and DirtyChannel.

Source: /dirtytalk/engine/api-reference/

The exhaustive surface of `@dirtytalk/engine`, organized by export. Every signature here is quoted from the source. For the conceptual model behind these types see [Concepts](/dirtytalk/engine/concepts); for a guided introduction see [Getting Started](/dirtytalk/engine/getting-started).

## Entry points

The package has two entry points:

| Import path                    | Exports                                                                                                                                |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `@dirtytalk/engine`            | `Observable`, `Signal`, `Space`, `Scheduler`, `SyncScheduler`, `ManualScheduler`, `MicrotaskScheduler`, `RAFScheduler`, `DirtyChannel` |
| `@dirtytalk/engine/primitives` | `Observable`, `Signal`                                                                                                                 |

`Observable`, `Space`, and `Scheduler` are **type-only** exports (interfaces). The rest are runtime classes.

```ts
// Everything:
import {
  Signal,
  SyncScheduler,
  ManualScheduler,
  MicrotaskScheduler,
  RAFScheduler,
  DirtyChannel,
} from '@dirtytalk/engine';
import type { Observable, Space, Scheduler } from '@dirtytalk/engine';

// Just the primitive:
import { Signal } from '@dirtytalk/engine/primitives';
import type { Observable } from '@dirtytalk/engine/primitives';
```

---

## `Observable<T>`

A read-and-subscribe interface. `Signal<T>` is the only built-in implementation; the interface exists so consumers can accept any observable value.

```ts
interface Observable<T> {
  peek(): T;
  subscribe(cb: (value: T) => void): () => void;
}
```

| Member      | Signature                              | Description                                                                                |
| ----------- | -------------------------------------- | ------------------------------------------------------------------------------------------ |
| `peek`      | `(): T`                                | Read the current value without subscribing.                                                |
| `subscribe` | `(cb: (value: T) => void): () => void` | Register a callback invoked with the new value on change. Returns an unsubscribe function. |

---

## `Signal<T>`

`class Signal<T> implements Observable<T>` — a synchronous notification primitive for a single observable value. No scheduler, no coalescing.

### Constructor

```ts
constructor(initial: T, equals?: (a: T, b: T) => boolean)
```

| Parameter | Type                      | Required | Description                                                                      |
| --------- | ------------------------- | -------- | -------------------------------------------------------------------------------- |
| `initial` | `T`                       | yes      | Starting value.                                                                  |
| `equals`  | `(a: T, b: T) => boolean` | no       | Equality predicate used to short-circuit notifications. Defaults to `Object.is`. |

Because the default is `Object.is`: `NaN` is considered equal to `NaN` (so writing `NaN` over `NaN` does not notify), and `+0`/`-0` are considered distinct (so writing one over the other _does_ notify).

### Members

```ts
get value(): T
set value(next: T)
peek(): T
subscribe(cb: (value: T) => void): () => void
```

| Member        | Signature                                       | Returns                  | Description                                                                                                                 |
| ------------- | ----------------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `value` (get) | `get value(): T`                                | `T`                      | The current value.                                                                                                          |
| `value` (set) | `set value(next: T)`                            | `void`                   | Assign with an equality guard (see below).                                                                                  |
| `peek`        | `peek(): T`                                     | `T`                      | Read without subscribing. Identical result to the `value` getter; provided for `Observable` conformance and intent clarity. |
| `subscribe`   | `subscribe(cb: (value: T) => void): () => void` | unsubscribe `() => void` | Add `cb` to the subscriber set. Returns an idempotent unsubscribe closure.                                                  |

**`set value` behavior.** If `equals(current, next)` is true, the setter returns immediately — no store, no notify. Otherwise it stores `next`, snapshots the current subscribers (`Array.from`), and invokes each with `next`. Subscribers are stored in a `Set`, so they run in registration (insertion) order. Errors thrown by callbacks are collected, not aborted on; after all subscribers run, a single error is re-thrown as-is, and multiple errors are thrown as `new AggregateError(errors, 'Signal: multiple subscriber errors')`.

**`subscribe` behavior.** Adds `cb` to the internal set and returns a closure that removes it. The closure is idempotent (guarded by a local flag) — calling it more than once is safe. Because subscribers are snapshotted before a notify, unsubscribing during a notify still lets the already-snapshotted callback run on the _current_ set, but not on the next.

:::tip[Re-entrant writes recurse]
Setting `value` from inside a subscriber triggers a fresh, fully synchronous notify cycle — unlike `DirtyChannel`, whose re-entrant marks defer to the next flush.
:::

```ts
import { Signal } from '@dirtytalk/engine/primitives';

const count = new Signal(0);
const unsub = count.subscribe((v) => console.log('count:', v));

count.value = 1; // => "count: 1"
count.value = 1; // no notify — Object.is(1, 1) is true
count.peek(); // 1
unsub();

// custom equality:
const user = new Signal({ id: 1 }, (a, b) => a.id === b.id);
user.subscribe((u) => console.log(u));
user.value = { id: 1 }; // no notify — same id
user.value = { id: 2 }; // notifies
```

---

## `Space<Region>`

The algebra of "what changed" and "what I care about". Both are values of type `Region`. The package ships **no** concrete implementation — consuming libraries supply one.

```ts
interface Space<Region> {
  empty(): Region;
  isEmpty(r: Region): boolean;
  union(a: Region, b: Region): Region;
  intersects(interest: Region, dirty: Region): boolean;
}
```

| Member       | Signature                                    | Description                                                                       |
| ------------ | -------------------------------------------- | --------------------------------------------------------------------------------- |
| `empty`      | `(): Region`                                 | The identity/zero region — "nothing changed".                                     |
| `isEmpty`    | `(r: Region): boolean`                       | True iff `r` is the empty region. Used for the no-op flush fast-path.             |
| `union`      | `(a: Region, b: Region): Region`             | Accumulate two dirty regions.                                                     |
| `intersects` | `(interest: Region, dirty: Region): boolean` | The delivery predicate: does this subscriber's interest overlap the dirty region? |

**Contracts (required):**

- `union(empty(), r)` must equal `r`.
- `intersects(empty(), _)` must return `false`.
- All four operations must be **pure** — same inputs, same output, no side effects. `DirtyChannel` calls them many times per flush and relies on stable results.

```ts
import type { Space } from '@dirtytalk/engine';

// A bitset Space: Region = number.
const BitsetSpace: Space<number> = {
  empty: () => 0,
  isEmpty: (r) => r === 0,
  union: (a, b) => a | b,
  intersects: (i, d) => (i & d) !== 0,
};
```

---

## `Scheduler`

Controls when a flush runs. A `DirtyChannel` hands the scheduler a flush callback via `request`; the scheduler is responsible for invoking it.

```ts
interface Scheduler {
  request(flush: () => void): void;
  cancel?(): void;
}
```

| Member    | Signature                   | Required | Description                                                                                                                                                                                                                        |
| --------- | --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request` | `(flush: () => void): void` | yes      | Ask for `flush` to be invoked. Must be idempotent within a scheduling window: N requests before the first flush produce one flush. (`SyncScheduler` is the deliberate exception.) Implementations store the latest `flush` passed. |
| `cancel`  | `(): void`                  | optional | Teardown that prevents a pending flush. Implemented by `MicrotaskScheduler` and `RAFScheduler`; **not** implemented by `SyncScheduler` or `ManualScheduler`.                                                                       |

---

## `SyncScheduler`

`class SyncScheduler implements Scheduler` — flushes immediately and synchronously on every `request`.

```ts
class SyncScheduler implements Scheduler {
  request(flush: () => void): void;
}
```

| Member    | Signature                   | Description                                                                                                          |
| --------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `request` | `(flush: () => void): void` | Calls `flush()` immediately and synchronously, before `request` returns. Every request flushes — there is no dedupe. |

No constructor arguments. No `cancel`. Intended for tests and synchronous-emit compatibility. Because each request flushes at once, every `mark` on a channel using `SyncScheduler` flushes immediately.

```ts
import { DirtyChannel, SyncScheduler } from '@dirtytalk/engine';

const ch = new DirtyChannel(BitsetSpace, new SyncScheduler());
ch.subscribe(
  () => 0b1,
  (d) => console.log('dirty =', d),
);
ch.mark(0b1); // => "dirty = 1" (synchronous)
```

---

## `ManualScheduler`

`class ManualScheduler implements Scheduler` — defers every flush until you call `pump()`.

```ts
class ManualScheduler implements Scheduler {
  request(flush: () => void): void;
  pump(): void;
}
```

| Member    | Signature                   | Description                                                                                                                                          |
| --------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request` | `(flush: () => void): void` | Marks a flush pending and stores `flush` as the latest pending callback. Does **not** invoke it.                                                     |
| `pump`    | `(): void`                  | If nothing is pending, returns immediately (no-op). Otherwise clears the pending and stored-flush state **first**, then invokes the stored callback. |

No constructor arguments. No `cancel`. Because `pump` clears state before invoking, a re-entrant `request` made during the flush is preserved for the _next_ `pump` rather than cascading synchronously. Intended for tests, replay, and SSR.

```ts
import { DirtyChannel, ManualScheduler } from '@dirtytalk/engine';

const sched = new ManualScheduler();
const ch = new DirtyChannel(BitsetSpace, sched);

const calls: number[] = [];
ch.subscribe(
  () => 0b1,
  (d) => calls.push(d),
);

ch.mark(0b1);
ch.mark(0b1); // nothing has run yet
sched.pump(); // flush now
console.log(calls); // [1] — one coalesced flush
sched.pump(); // no-op, nothing pending
```

---

## `MicrotaskScheduler`

`class MicrotaskScheduler implements Scheduler` — coalesces requests within a tick into a single flush at the end of the microtask queue.

```ts
class MicrotaskScheduler implements Scheduler {
  request(flush: () => void): void;
  cancel(): void;
}
```

| Member    | Signature                   | Description                                                                                                                                                                       |
| --------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request` | `(flush: () => void): void` | Stores `flush` as the latest. If not already pending, schedules a drain via `queueMicrotask`. All requests within a tick coalesce into one microtask; the last stored flush wins. |
| `cancel`  | `(): void`                  | Clears pending state and the stored flush, preventing the scheduled drain from running anything. After `cancel`, a fresh `request` works normally.                                |

No constructor arguments. Drains at the end of the current microtask queue. The intended default for `blac`.

```ts
import { DirtyChannel, MicrotaskScheduler } from '@dirtytalk/engine';

const ch = new DirtyChannel(BitsetSpace, new MicrotaskScheduler());
ch.subscribe(
  () => 0b011,
  (dirty) => console.log('flush dirty =', dirty),
);

ch.mark(0b001);
ch.mark(0b010); // both coalesce into ONE flush
await Promise.resolve(); // => "flush dirty = 3"
```

---

## `RAFScheduler`

`class RAFScheduler implements Scheduler` — coalesces requests to a single flush per animation frame, with a timer fallback.

```ts
class RAFScheduler implements Scheduler {
  constructor();
  request(flush: () => void): void;
  cancel(): void;
}
```

| Member        | Signature                   | Description                                                                                                                                                                                                         |
| ------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `constructor` | `()`                        | Takes no arguments. Captures whether `requestAnimationFrame` is available **once**, at construction (`typeof globalThis.requestAnimationFrame === 'function'`).                                                     |
| `request`     | `(flush: () => void): void` | Stores `flush` as the latest. If no drain is currently scheduled, schedules one via `requestAnimationFrame` when available, otherwise `setTimeout(fn, 16)`. Coalesces to one flush per frame/tick; last flush wins. |
| `cancel`      | `(): void`                  | If a drain is pending, unschedules it (`cancelAnimationFrame` or `clearTimeout`), nulls the handle, and clears the stored flush.                                                                                    |

Intended for `insomni` (frame-aligned repaints).

:::caution[rAF detection is one-time]
The rAF-vs-`setTimeout` choice is fixed at construction. Polyfilling `requestAnimationFrame` _after_ the instance is built will not change its behavior.
:::

```ts
import { DirtyChannel, RAFScheduler } from '@dirtytalk/engine';

const ch = new DirtyChannel(BitsetSpace, new RAFScheduler());
ch.subscribe(
  () => 0b1,
  (dirty) => repaint(dirty),
);
ch.mark(0b1);
ch.mark(0b1); // coalesced; one repaint next frame
```

---

## `DirtyChannel<Region>`

`class DirtyChannel<Region>` — the core engine. Accumulates `mark`s within a scheduler window, then delivers the unioned dirty region to interested subscribers in one flush.

```ts
class DirtyChannel<Region> {
  constructor(space: Space<Region>, scheduler: Scheduler);
  mark(r: Region): void;
  subscribe(interest: () => Region, cb: (dirty: Region) => void): () => void;
}
```

### Constructor

```ts
constructor(space: Space<Region>, scheduler: Scheduler)
```

| Parameter   | Type            | Description               |
| ----------- | --------------- | ------------------------- |
| `space`     | `Space<Region>` | The region algebra.       |
| `scheduler` | `Scheduler`     | Controls when flush runs. |

On construction the channel initializes its accumulator to `space.empty()` and allocates a single stable bound flush function once (to avoid GC churn and let identity-keying schedulers dedupe). Construction does **not** call `scheduler.request`.

### `mark`

```ts
mark(r: Region): void
```

| Parameter | Type     | Description                   |
| --------- | -------- | ----------------------------- |
| `r`       | `Region` | The region that just changed. |

**Returns:** `void`.

**Behavior.** Always folds `r` into the accumulator via `space.union(accumulated, r)` — once per mark, regardless of flushing state. It then requests a flush **only if** the channel is neither currently flushing nor already scheduled. A mark made during a flush accumulates into the next flush's payload; the tail of the current flush schedules that follow-up. This guard is what coalesces N marks into a single flush.

### `subscribe`

```ts
subscribe(interest: () => Region, cb: (dirty: Region) => void): () => void
```

| Parameter  | Type                      | Description                                                                                                                                                                                |
| ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `interest` | `() => Region`            | A thunk returning the region this subscriber cares about. Re-evaluated lazily, once per flush per subscriber — not snapshotted at subscribe time. Skipped entirely on empty-dirty flushes. |
| `cb`       | `(dirty: Region) => void` | Invoked with the accumulated dirty region when `space.intersects(interest(), dirty)` is true.                                                                                              |

**Returns:** an unsubscribe function `() => void`.

**Behavior.** Assigns a monotonic id, stores a live entry in a registration-ordered map, and returns an idempotent unsubscribe closure that marks the entry dead and removes it. The unsubscribe is safe to call at any time, including from inside a callback mid-flush.

**Flush semantics** (the ordered behavior of an internal flush):

1. Snapshot `dirty = accumulated`, reset the accumulator to `empty()`, clear the scheduled flag — all before any callback runs.
2. If `space.isEmpty(dirty)`, return immediately. The subscriber loop is skipped and interest thunks are **not** evaluated.
3. Enter flushing mode.
4. Snapshot the subscriber list. Subscribers added during this flush will not run this cycle.
5. Iterate the snapshot in registration order. Skip dead entries (checked on the entry's `alive` flag); evaluate the interest thunk in a try/catch (a throw is recorded and the subscriber is skipped); skip if `intersects` is false; otherwise invoke the callback in a try/catch (a throw is recorded and iteration continues).
6. Exit flushing mode.
7. If a re-entrant mark left the accumulator non-empty, schedule the next flush.
8. Surface errors: 0 → nothing; exactly 1 → re-throw as-is; more than 1 → `throw new AggregateError(errors, 'DirtyChannel: subscriber errors during flush')`. Interest-thunk errors and callback errors both count toward the aggregate.

```ts
import { DirtyChannel, SyncScheduler } from '@dirtytalk/engine';
import type { Space } from '@dirtytalk/engine';

const StringSetSpace: Space<Set<string>> = {
  empty: () => new Set(),
  isEmpty: (r) => r.size === 0,
  union: (a, b) => new Set([...a, ...b]),
  intersects: (interest, dirty) => {
    for (const k of interest) if (dirty.has(k)) return true;
    return false;
  },
};

const channel = new DirtyChannel(StringSetSpace, new SyncScheduler());

const unsub = channel.subscribe(
  () => new Set(['users', 'session']), // interest thunk, re-run each flush
  (dirty) => console.log('dirty keys:', [...dirty]),
);

channel.mark(new Set(['users'])); // => "dirty keys: [ 'users' ]"
channel.mark(new Set(['theme'])); // => no output: doesn't intersect interest
unsub();
```

---

## See also

- [Concepts](/dirtytalk/engine/concepts) — the Space algebra, scheduler comparison, and full flush lifecycle.
- [Getting Started](/dirtytalk/engine/getting-started) — install and build your first channel.
- [Structural: api reference](/dirtytalk/structural/api-reference) — a higher-level package built on this engine.
- [Spatial: api reference](/dirtytalk/spatial/api-reference) — the engine applied to 2D scene damage.

---

# Concepts

> The model behind @dirtytalk/engine — why a region carries what changed, the Space algebra, the four schedulers, and the DirtyChannel flush lifecycle.

Source: /dirtytalk/engine/concepts/

This page explains the model behind `@dirtytalk/engine`: why a region carries "what changed", what the `Space` algebra guarantees, how the four schedulers differ, and exactly what happens inside a flush. It is the "why" companion to the task-oriented [Getting Started](/dirtytalk/engine/getting-started) and the lookup-oriented [API Reference](/dirtytalk/engine/api-reference).

## The single-dirty-bit problem

The naive way to track change is a boolean: "something is dirty, re-run everything." It is cheap to set and useless to act on. When a single value changes, every subscriber wakes up, recomputes, and most of them discover they did not care. A renderer with one dirty bit repaints the whole canvas. A state container with one dirty bit walks the entire tree once per consumer.

The fix is to make the dirty signal carry information: not _that_ something changed, but _what_ changed. If "what changed" is a value subscribers can cheaply test their own interest against, then a flush can skip every subscriber that does not overlap. That value is the **`Region`** — and the engine's only opinion is that "what changed" and "what I care about" are the same kind of value, so they can be intersected.

This is not a hypothetical generalization. Two real libraries motivated it: `insomni`, a WebGPU renderer whose region is a union of damage rectangles, and `blac`, a state-container library whose region is a set of interned path IDs. Different domains, identical algebra. The engine is that algebra plus the scheduling glue, and nothing else.

## The Space algebra

A `Space<Region>` is the contract a consuming library implements to describe its notion of change. It is four pure functions:

```ts
interface Space<Region> {
  empty(): Region;
  isEmpty(r: Region): boolean;
  union(a: Region, b: Region): Region;
  intersects(interest: Region, dirty: Region): boolean;
}
```

Read it as a small algebra over regions:

- `empty()` is the **zero region** — the identity element. "Nothing changed."
- `isEmpty(r)` recognizes that zero. The channel uses it for a no-op fast-path.
- `union(a, b)` **accumulates** two dirty regions into one. This is how many marks become a single flush payload.
- `intersects(interest, dirty)` is the **delivery predicate** — the one decision the engine makes per subscriber per flush.

### The contracts, and why they exist

Two laws are non-negotiable:

1. **`union(empty(), r)` equals `r`.** `empty()` is the identity for `union`. The channel starts each window with `empty()` and folds every mark into it; if `empty()` were not the identity, the first mark of every window would be corrupted.
2. **`intersects(empty(), _)` returns `false`.** An empty interest is interest in nothing. A subscriber whose thunk returns `empty()` must never be called. (The channel separately skips the _whole_ loop when the _dirty_ region is empty, but this law covers the per-subscriber case.)

On top of those, every operation must be **pure**: same inputs produce the same output, with no side effects. The channel calls `union`, `intersects`, `isEmpty`, and `empty` many times across a flush and relies on stable results. A `Space` that mutates its arguments, caches statefully, or returns different answers for the same inputs will produce undefined behavior. Do not, for example, put logging or lazy initialization inside `intersects`.

### Worked example: `StringSet`

A region that is a set of changed string keys satisfies the algebra cleanly:

```ts
import type { Space } from '@dirtytalk/engine';

const StringSetSpace: Space<Set<string>> = {
  empty: () => new Set(), // zero = the empty set
  isEmpty: (r) => r.size === 0, // recognizes the empty set
  union: (a, b) => new Set([...a, ...b]), // set union accumulates
  intersects: (interest, dirty) => {
    for (const k of interest) {
      if (dirty.has(k)) return true; // any shared key = overlap
    }
    return false; // empty interest can never match
  },
};
```

Check the laws: `union(new Set(), r)` is a fresh set with exactly `r`'s elements — equal to `r`. `intersects(new Set(), _)` loops zero times and returns `false`. Both operations are pure (each `union` allocates a new set rather than mutating an input). A bitset (`Region = number`, `union = a | b`, `intersects = (i & d) !== 0`) satisfies the same laws and is even cheaper.

## The four schedulers

The `Space` decides _what_ and _who_. The `Scheduler` decides _when_. A scheduler receives a `flush` callback via `request(flush)` and is responsible for invoking it. The contract: within a scheduling window, `request` is idempotent — N calls before the first flush produce **one** flush, not N. (`SyncScheduler` is the deliberate exception: each `request` is its own window and flushes immediately.) An optional `cancel()` prevents a pending flush.

The engine ships four implementations:

| Scheduler            | When it flushes                                         | Coalesces?                 | `cancel()`? | Use it for                                    |
| -------------------- | ------------------------------------------------------- | -------------------------- | ----------- | --------------------------------------------- |
| `SyncScheduler`      | Immediately, inside `request`                           | No (every request flushes) | No          | Tests, synchronous-emit compatibility         |
| `ManualScheduler`    | Only when you call `pump()`                             | Yes (until pumped)         | No          | Tests, replay, SSR — deterministic timing     |
| `MicrotaskScheduler` | End of the current microtask queue                      | Yes (one per tick)         | Yes         | `blac` (the default) — batch within a JS turn |
| `RAFScheduler`       | Next `requestAnimationFrame`, else `setTimeout(fn, 16)` | Yes (one per frame)        | Yes         | `insomni` — frame-aligned repaints            |

A few details worth internalizing:

- **`SyncScheduler` does not coalesce at the scheduler level.** Every `request` flushes synchronously. With `SyncScheduler`, each `mark` therefore flushes immediately. Coalescing of marks within a window — when it happens at all — comes from the `DirtyChannel`'s own scheduled-flag guard, not from this scheduler.
- **`ManualScheduler.pump()` clears its pending state _before_ invoking the flush.** A re-entrant `request` made during that flush is preserved for the _next_ `pump`, not cascaded synchronously. A `pump` with nothing pending is a harmless no-op.
- **`MicrotaskScheduler` and `RAFScheduler` store the latest flush and coalesce.** Multiple requests within the same tick/frame collapse to one drain; the last stored flush wins. Both implement `cancel()` to drop a pending drain.
- **`RAFScheduler` chooses rAF-vs-setTimeout once, at construction.** It captures `typeof globalThis.requestAnimationFrame === 'function'` in the constructor. If you polyfill `requestAnimationFrame` _after_ building the instance, it will keep using `setTimeout`.

## The DirtyChannel lifecycle

A `DirtyChannel<Region>` ties a `Space` and a `Scheduler` together. Here is the full flow, narrated, from a mark to a delivered callback.

### mark → accumulate

```ts
channel.mark(region);
```

Every `mark` folds the region into the channel's internal accumulator via `space.union(accumulated, region)` — once per mark, regardless of whether a flush is in progress. Then, _only if_ the channel is not already flushing and has not already scheduled, it sets a scheduled flag and calls `scheduler.request(flush)`. This guard is what turns N marks into one flush request: the second through Nth marks see the flag already set and just accumulate.

### scheduler window → flush

The scheduler decides when to invoke the flush callback (immediately, on `pump`, on a microtask, on a frame). The channel always hands the scheduler the **same bound function instance**, allocated once at construction. This avoids GC churn and lets identity-keying schedulers dedupe correctly.

### flush: snapshot, evaluate, deliver

When the flush finally runs, it executes in a fixed order:

1. **Snapshot and reset.** The accumulated region is captured into a local `dirty`, the accumulator is reset to `empty()`, and the scheduled flag is cleared — all _before_ any callback runs. This is what lets re-entrant marks land cleanly in the fresh accumulator.
2. **Empty fast-path.** If `space.isEmpty(dirty)`, the flush returns immediately. The subscriber loop is skipped entirely and **interest thunks are not even called**. A no-op flush fires nothing.
3. **Enter flushing mode** — a flag the channel uses to recognize re-entrant marks.
4. **Snapshot the subscriber list.** Subscribers added during this flush are not in the snapshot and will not run this cycle.
5. **Iterate in registration order.** For each entry: skip it if it has been unsubscribed (an `alive` flag checked on the entry, so unsubscribing a _later_ subscriber from an _earlier_ callback works); evaluate its interest thunk; if `space.intersects(interest, dirty)` is false, skip; otherwise invoke its callback with `dirty`.
6. **Exit flushing mode.**
7. **Schedule any follow-up.** If a mark arrived during dispatch, the accumulator is now non-empty, so the channel re-sets the scheduled flag and requests the next flush — done _after_ clearing the flushing flag so `mark`'s guard does not double-schedule.
8. **Surface errors** (described below).

### Coalescing

Many marks in one window → one flush, carrying the single unioned `dirty` region. The subscriber sees the whole batch at once, not one callback per mark. This is the core efficiency win and it falls directly out of the `union`-on-mark plus the scheduled-flag guard.

### Re-entrant marks defer to the next flush

If a subscriber callback calls `mark` during a flush, that region accumulates into the _next_ flush's payload — it never re-enters the current dispatch synchronously. The follow-up is scheduled at step 7 once the current flush is fully done. This bounds the work per tick and makes infinite synchronous loops impossible within a single flush.

:::caution[Signal does the opposite]
A re-entrant _write_ inside a `Signal` subscriber recurses synchronously — a fresh, fully synchronous notify cycle. `DirtyChannel` defers; `Signal` recurses. Do not assume one behaves like the other.
:::

### Error isolation and AggregateError

A throwing interest thunk is treated as "no interest this flush": the error is recorded and the subscriber is skipped. A throwing callback is likewise recorded, and iteration continues to the remaining subscribers. Errors surface only **after** the whole flush completes and the channel's state is clean (including any follow-up scheduling):

- 0 errors → nothing thrown.
- exactly 1 error → that error is re-thrown **as-is**, unwrapped.
- more than 1 → thrown as `new AggregateError(errors, 'DirtyChannel: subscriber errors during flush')`.

One subscriber throwing never starves the others. If you want per-callback isolation that never throws, wrap your own callbacks.

### Subscribe / unsubscribe during a flush is safe

Because the subscriber list is snapshotted at step 4, a `subscribe` during a callback adds an entry that runs on the _next_ flush, not the current one. An `unsubscribe` during a callback flips the entry's `alive` flag and removes it from the map immediately, so a not-yet-visited subscriber in the snapshot is skipped this cycle. Unsubscribe is idempotent — safe to call any number of times, including mid-flush.

### Interest is a thunk

The interest passed to `subscribe` is a function, re-evaluated lazily once per flush per subscriber — never snapshotted at subscribe time, and skipped entirely on empty-dirty flushes. This lets a subscriber move, resize, or reconfigure between flushes and always be matched against its _current_ interest. The flip side: do not put load-bearing side effects in an interest thunk (it may not run on a given flush), and keep it pure-ish — a throw is swallowed-as-error and skips that subscriber for that flush.

## The Signal / Observable layer

Alongside the channel, the engine exposes a much simpler primitive for single observable values that do not need region machinery.

```ts
interface Observable<T> {
  peek(): T;
  subscribe(cb: (value: T) => void): () => void;
}
```

`Signal<T>` is the only built-in implementation. It holds one value, notifies subscribers synchronously when that value changes, and short-circuits the notify when the new value is equal to the old (by `Object.is`, or a custom comparator you pass). There is no scheduler and no coalescing — set the value, subscribers run now.

How it differs from `DirtyChannel`:

|                    | `Signal<T>`                                                               | `DirtyChannel<Region>`                                                              |
| ------------------ | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Carries            | one value `T`                                                             | a region of "what changed"                                                          |
| Notification       | synchronous on set                                                        | deferred to a scheduler window                                                      |
| Coalescing         | none                                                                      | many marks → one flush                                                              |
| Selective delivery | none (every subscriber notified)                                          | interest ∩ dirty per subscriber                                                     |
| Re-entrancy        | recurses synchronously                                                    | defers to next flush                                                                |
| Error surfacing    | single re-thrown / `AggregateError('Signal: multiple subscriber errors')` | single re-thrown / `AggregateError('DirtyChannel: subscriber errors during flush')` |

Reach for `Signal` when you have "one value, tell everyone now". Reach for `DirtyChannel` when you have "many things, tell the right people once, when the moment is right".

## What it is not

The engine is deliberately small. It is not a reactivity framework, and it leaves several things to the layers above it:

- **No concrete `Space`.** The package ships zero region implementations. You (or `@dirtytalk/spatial` / `@dirtytalk/structural`) supply one.
- **No auto-tracked computed values.** There is no `computed(() => a + b)` with a hidden dependency graph. Derived values are built above this layer.
- **No effect system with cleanups.** `subscribe` returns an unsubscribe function; that is the entire cleanup story.
- **No selector or memoization helpers.** That is a consumer concern (React's `useMemo`, blac's per-consumer tracker).
- **No diffing utilities.** Turning a mutation into a `Region` is the consuming library's job. The engine only `union`s and `intersects`.
- **No glitch-free dependency graph.** There is no dependency graph at this layer at all.
- **Not coupled to any framework.** React, the DOM, and the GPU are never referenced. There is no React entry point — the only entries are `.` and `./primitives`.

## See also

- [Getting Started](/dirtytalk/engine/getting-started) — build a channel and watch these mechanics in action.
- [API Reference](/dirtytalk/engine/api-reference) — exact signatures, parameters, and behavior notes for every export.
- [Structural: concepts](/dirtytalk/structural/concepts) — a real `Space` over interned path-ID sets.
- [Spatial: concepts](/dirtytalk/spatial/concepts) — a real `Space` over damage rectangles, with a frame-aligned scheduler.

---

# Getting Started

> From an empty file to a working DirtyChannel you can mark and observe, then swapping the scheduler to change timing.

Source: /dirtytalk/engine/getting-started/

This page gets you from an empty file to a working `DirtyChannel` you can mark and observe, then shows how swapping the scheduler changes timing. It is the hands-on introduction to `@dirtytalk/engine`; for the reasoning behind the design see [Concepts](/dirtytalk/engine/concepts), and for the exhaustive surface see the [API Reference](/dirtytalk/engine/api-reference).

## Install

<Tabs syncKey="pkg">
<TabItem label="pnpm">

```bash
pnpm add @dirtytalk/engine
```

</TabItem>
<TabItem label="npm">

```bash
npm install @dirtytalk/engine
```

</TabItem>
<TabItem label="yarn">

```bash
yarn add @dirtytalk/engine
```

</TabItem>
</Tabs>

The package is ESM-first (`"type": "module"`), side-effect free, and has zero runtime dependencies. It ships a main entry point and one subpath, `@dirtytalk/engine/primitives`, for the standalone `Signal` and `Observable` types.

## The one idea

Every reactive system eventually answers the same three questions after a mutation: **what changed, who cares, and when do we tell them?** The engine's whole job is to answer those three questions once, cheaply, at the source. You describe "what changed" as a `Region` (a value in an algebra you supply), the channel accumulates regions from many `mark` calls into a single union, a `Scheduler` decides when to flush, and at flush time each subscriber's declared interest is intersected against the accumulated dirty region to decide whether its callback runs. That is the entire model. Everything else on this page is filling in the blanks.

## A complete walkthrough

Let's build the smallest useful channel: a `Region` that is a `Set<string>` of keys. Marking `{ "users" }` means "the users data changed"; a subscriber interested in `{ "users", "session" }` should hear about it, while one interested only in `{ "theme" }` should not.

### 1. Define a Space

The engine ships **no** concrete `Region` types — you bring your own by implementing the `Space<Region>` interface. A `Space` is four pure functions over your region type.

```ts
import type { Space } from '@dirtytalk/engine';

// Region = Set<string>: a set of string keys that changed.
const StringSetSpace: Space<Set<string>> = {
  empty: () => new Set(),
  isEmpty: (r) => r.size === 0,
  union: (a, b) => new Set([...a, ...b]),
  intersects: (interest, dirty) => {
    for (const k of interest) {
      if (dirty.has(k)) return true;
    }
    return false;
  },
};
```

Two contracts make the channel work correctly: `union(empty(), r)` must equal `r`, and `intersects(empty(), _)` must be `false`. The set implementation satisfies both for free. (More on why these matter in [Concepts](/dirtytalk/engine/concepts).)

### 2. Construct a channel

A `DirtyChannel` takes your `Space` and a `Scheduler`. We start with `SyncScheduler`, which flushes immediately on every request — the easiest thing to reason about while learning.

```ts
import { DirtyChannel, SyncScheduler } from '@dirtytalk/engine';

const channel = new DirtyChannel(StringSetSpace, new SyncScheduler());
```

Construction does nothing observable: it does not request a flush and does not touch the scheduler. The channel just holds an empty accumulator until you `mark`.

### 3. Subscribe with an interest thunk

`subscribe` takes two functions. The first is an **interest thunk** — it returns the region this subscriber cares about, and it is re-evaluated on every flush (not snapshotted now). The second is the **callback** that fires with the accumulated dirty region when the interest intersects it.

```ts
const unsub = channel.subscribe(
  () => new Set(['users', 'session']), // interest, re-run each flush
  (dirty) => {
    console.log('dirty keys:', [...dirty]);
  },
);
```

### 4. Mark and observe

Now drive the channel. With `SyncScheduler`, each `mark` flushes synchronously before `mark` returns.

```ts
channel.mark(new Set(['users']));
// => "dirty keys: [ 'users' ]"
// 'users' is in our interest, so the callback fires.

channel.mark(new Set(['theme']));
// => (no output)
// 'theme' does not intersect { 'users', 'session' }, so the callback is skipped.

unsub();
channel.mark(new Set(['users']));
// => (no output) — we unsubscribed.
```

That contrast — delivery for `users`, silence for `theme` — is the selective fan-out the engine exists to provide. The subscriber is never told about changes it did not declare interest in.

:::tip[Why a thunk and not a value?]
Because subscribers move. A rendered node that has scrolled, a query whose key set grew — the interest you cared about last frame may not be the one you care about now. Returning it fresh each flush keeps the subscription correct without re-subscribing. See [interest is a thunk](/dirtytalk/engine/concepts#interest-is-a-thunk).
:::

## Swapping the scheduler

The `Space` answers "what changed" and "who cares". The `Scheduler` answers "when do we tell them". Swapping it is a one-line change and the rest of your code is untouched.

### Microtask: coalesce a burst into one flush

`MicrotaskScheduler` defers the flush to the end of the current microtask queue, so many marks in the same tick collapse into a single flush with a single unioned region.

```ts
import { DirtyChannel, MicrotaskScheduler } from '@dirtytalk/engine';

const channel = new DirtyChannel(StringSetSpace, new MicrotaskScheduler());

channel.subscribe(
  () => new Set(['users']),
  (dirty) => console.log('flush dirty:', [...dirty]),
);

channel.mark(new Set(['users']));
channel.mark(new Set(['session'])); // does not intersect, but still accumulates
channel.mark(new Set(['users'])); // same window

await Promise.resolve();
// => "flush dirty: [ 'users', 'session' ]"
// ONE flush, with the union of all three marks.
```

Compare this with `SyncScheduler`, where those three marks would have produced up to three separate flushes. The subscriber logic did not change — only the timing did.

### Manual: flush exactly when you say

`ManualScheduler` never flushes on its own. You call `pump()` to drain. This is the deterministic choice for tests, replay, and server-side rendering.

```ts
import { DirtyChannel, ManualScheduler } from '@dirtytalk/engine';

const scheduler = new ManualScheduler();
const channel = new DirtyChannel(StringSetSpace, scheduler);

const seen: string[][] = [];
channel.subscribe(
  () => new Set(['users']),
  (dirty) => seen.push([...dirty]),
);

channel.mark(new Set(['users']));
channel.mark(new Set(['users']));
// Nothing has fired yet.

scheduler.pump();
console.log(seen); // [ [ 'users' ] ] — one coalesced flush

scheduler.pump();
console.log(seen); // unchanged — nothing pending, pump is a no-op
```

There is also a fourth built-in, `RAFScheduler`, which flushes once per animation frame (falling back to `setTimeout(fn, 16)` when `requestAnimationFrame` is unavailable). It is the right choice for frame-aligned repaints. All four are compared in the [scheduler table](/dirtytalk/engine/concepts#the-four-schedulers).

## The Signal primitive

Sometimes you have a single observable value that does not need the full channel ceremony — no regions, no interest, no coalescing window. For that, the engine exposes `Signal<T>`, a synchronous notification primitive, on the `/primitives` subpath.

```ts
import { Signal } from '@dirtytalk/engine/primitives';

const count = new Signal(0);

const unsub = count.subscribe((v) => console.log('count:', v));

count.value = 1; // => "count: 1"
count.value = 1; // skipped — Object.is equality short-circuits the notify
count.peek(); // 1 — read without subscribing
unsub();
```

`Signal` notifies synchronously the moment you set `value`, guarded by an equality check that defaults to `Object.is`. You can pass a custom comparator as the second constructor argument:

```ts
import { Signal } from '@dirtytalk/engine/primitives';

const user = new Signal({ id: 1, name: 'a' }, (a, b) => a.id === b.id);
user.subscribe((u) => console.log('user:', u));

user.value = { id: 1, name: 'b' }; // no notify — same id
user.value = { id: 2, name: 'b' }; // => "user: { id: 2, name: 'b' }"
```

`Signal` is intentionally not a `DirtyChannel`: it has no scheduler and no coalescing, and a re-entrant write inside a subscriber recurses synchronously rather than deferring. Pick `Signal` for "one value changed, tell everyone now"; pick `DirtyChannel` for "many things changed, tell the right people once". The difference is covered in [Concepts](/dirtytalk/engine/concepts#the-signal-observable-layer).

## When to use the engine directly

`@dirtytalk/engine` is the unopinionated core. You implement the `Space`, you wire the `Scheduler`, you produce regions from your mutations. That is the right level when you are building a notification layer for a new domain, or you want full control over the region algebra.

If you are working in an already-modeled domain, reach for a higher-level package instead:

| You want to...                                                               | Use                                                              |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| A scene graph with rect-level damage, a render pipeline, and pointer routing | [`@dirtytalk/spatial`](/dirtytalk/spatial/getting-started)       |
| Path-set tracking over structured state (interned path IDs, skeletons)       | [`@dirtytalk/structural`](/dirtytalk/structural/getting-started) |
| The raw region/scheduler/channel machinery, with your own `Space`            | `@dirtytalk/engine` (this package)                               |

Both `spatial` and `structural` are built on this engine — they supply the concrete `Space` (rect unions, path-ID sets) and the ergonomics. If one of them fits your domain, start there and drop down to the engine only when you need something neither provides.

## See also

- [Concepts](/dirtytalk/engine/concepts) — the Space algebra, the four schedulers, and the DirtyChannel lifecycle in depth.
- [API Reference](/dirtytalk/engine/api-reference) — exhaustive signatures for every export.
- [DirtyTalk overview](/dirtytalk/) — the shared thesis and how the three packages relate.
- [Spatial: getting started](/dirtytalk/spatial/getting-started) — the engine applied to 2D scenes.

---

# API Reference

> The complete public surface of @dirtytalk/spatial — Rect helpers, RectSpace, SceneNode, SceneRoot, the render pipeline, and PointerRouter.

Source: /dirtytalk/spatial/api-reference/

The complete public surface of `@dirtytalk/spatial`, organised by export. Every signature here matches the source. This page is a lookup reference; for the model behind these APIs read [Concepts](/dirtytalk/spatial/concepts), and for a guided build see [Getting Started](/dirtytalk/spatial/getting-started).

All exports come from the package root — there are no subpaths:

```ts
import {
  // values
  rectOverlaps,
  rectEquals,
  unionRects,
  rectClamp,
  pointInRect,
  RectSpace,
  SceneNode,
  SceneRoot,
  PointerRouter,
} from '@dirtytalk/spatial';

import type {
  // types
  Rect,
  DamageKind,
  Damage,
  DirtyRegion,
  SceneNodeOptions,
  Renderer2D,
  SceneRootOptions,
  FrameTiming,
  SpatialPointerEvent,
  PointerHandler,
} from '@dirtytalk/spatial';
```

Scheduler classes (`SyncScheduler`, `ManualScheduler`, `RAFScheduler`, `MicrotaskScheduler`) and the `Space`/`DirtyChannel` primitives come from [`@dirtytalk/engine`](/dirtytalk/engine/api-reference).

## Types

### `Rect`

A 2D axis-aligned rectangle in CSS pixels, top-left origin. Note the field names are `w`/`h`, not `width`/`height`.

```ts
interface Rect {
  x: number;
  y: number;
  w: number;
  h: number;
}
```

### `DamageKind`

Classifies a damage entry and thereby selects which pipeline stages run.

```ts
type DamageKind = 'paint' | 'layout' | 'data';
```

| Value      | Stages run             |
| ---------- | ---------------------- |
| `'paint'`  | Paint only.            |
| `'layout'` | Layout → paint.        |
| `'data'`   | Data → layout → paint. |

### `Damage`

A single damage entry: a rectangle, a kind, and (at runtime) the emitting node.

```ts
interface Damage {
  rect: Rect;
  kind: DamageKind;
  node?: unknown;
}
```

`node` is typed `unknown` to avoid an import cycle between `types.ts` and `scene-node.ts`. At runtime it holds the emitting `SceneNode`; `SceneRoot` casts it to `SceneNode | undefined` when running the pipeline. It is optional — damage marked directly on the channel may have no node.

### `DirtyRegion`

The region type carried by the spatial `DirtyChannel`: a read-only list of damage entries.

```ts
type DirtyRegion = readonly Damage[];
```

:::caution[Treat as immutable]
`RectSpace.union` may return one of its inputs _by reference_ (the empty short-circuit). Never mutate an array obtained from `union` or `empty`; the `readonly` type enforces this at compile time.
:::

## Rect helpers

All five are pure, side-effect-free `const` arrow functions. Only `unionRects` and `rectClamp` allocate a new `Rect`.

### `rectOverlaps(a, b)`

```ts
const rectOverlaps: (a: Rect, b: Rect) => boolean;
```

Returns `true` iff the two rects share _positive_ area. Uses half-open semantics: touching edges do not overlap. Returns `false` if either rect has `w <= 0` or `h <= 0`.

| Inputs                                       | Result  |
| -------------------------------------------- | ------- |
| Identical non-empty rects                    | `true`  |
| One fully contained in the other             | `true`  |
| Right edge of A == left edge of B (touching) | `false` |
| Either rect has `w = 0` or `h = 0`           | `false` |

```ts
rectOverlaps({ x: 0, y: 0, w: 10, h: 10 }, { x: 5, y: 5, w: 10, h: 10 }); // true
rectOverlaps({ x: 0, y: 0, w: 10, h: 10 }, { x: 10, y: 0, w: 10, h: 10 }); // false (touching)
```

### `rectEquals(a, b)`

```ts
const rectEquals: (a: Rect, b: Rect) => boolean;
```

Field-by-field structural equality using `===` (no epsilon/tolerance): `a.x === b.x && a.y === b.y && a.w === b.w && a.h === b.h`. Any single differing field yields `false`.

```ts
rectEquals({ x: 1, y: 2, w: 3, h: 4 }, { x: 1, y: 2, w: 3, h: 4 }); // true
rectEquals({ x: 1, y: 2, w: 3, h: 4 }, { x: 1, y: 2, w: 3, h: 5 }); // false
```

### `unionRects(rects)`

```ts
const unionRects: (rects: readonly Rect[]) => Rect;
```

Returns the bounding box (axis-aligned hull) of all input rects. Does not mutate inputs.

- Empty array → the origin sentinel `{ x: 0, y: 0, w: 0, h: 0 }`.
- Single-element array → a rect equal to that element.
- Each rect's extent is treated as `[x, x + w]`; zero-area members are not special-cased and can still pull the hull toward their corner.

```ts
unionRects([
  { x: 0, y: 0, w: 30, h: 30 },
  { x: 50, y: 50, w: 20, h: 20 },
]); // { x: 0, y: 0, w: 70, h: 70 }

unionRects([]); // { x: 0, y: 0, w: 0, h: 0 }
```

### `rectClamp(inner, outer)`

```ts
const rectClamp: (inner: Rect, outer: Rect) => Rect;
```

Returns the _geometric intersection_ of `inner` and `outer`, with width and height floored at `0` via `Math.max(0, …)`. This is the function used to clip damage to clipping ancestors.

- Non-overlapping inputs → a zero-area rect.
- `inner` fully inside `outer` → a rect value-equal to `inner`.
- `inner` equal to `outer` → an equal rect.

```ts
rectClamp({ x: 5, y: 5, w: 100, h: 100 }, { x: 0, y: 0, w: 50, h: 50 });
// { x: 5, y: 5, w: 45, h: 45 }  (intersection)

rectClamp({ x: 200, y: 200, w: 10, h: 10 }, { x: 0, y: 0, w: 50, h: 50 });
// { x: 200, y: 200, w: 0, h: 0 }  (no overlap -> zero area)
```

### `pointInRect(x, y, r)`

```ts
const pointInRect: (x: number, y: number, r: Rect) => boolean;
```

Half-open point test over `[x, x + w) × [y, y + h)`: the top-left corner is inclusive, the bottom-right edge is exclusive (CSS pixel-grid convention). A zero-area rect (`w = 0` or `h = 0`) contains no points.

```ts
pointInRect(0, 0, { x: 0, y: 0, w: 10, h: 10 }); // true  (top-left inclusive)
pointInRect(10, 5, { x: 0, y: 0, w: 10, h: 10 }); // false (right edge exclusive)
```

:::note[`pointInRect` is fully public]
It is exported from the package root even though the README's export table omits it.
:::

## `RectSpace`

```ts
const RectSpace: Space<DirtyRegion>;
```

The `Space<DirtyRegion>` implementation that wires the rect algebra into the engine's `DirtyChannel`. `Space<Region>` (from `@dirtytalk/engine`) requires four pure methods, which `RectSpace` provides:

| Method                                 | Behaviour                                                                                                                                                                                                         |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `empty(): DirtyRegion`                 | Returns `[]`. A **fresh array on every call** (`empty() !== empty()`).                                                                                                                                            |
| `isEmpty(r): boolean`                  | `r.length === 0`.                                                                                                                                                                                                 |
| `union(a, b): DirtyRegion`             | Identity short-circuit: if `a` is empty returns `b` by reference; if `b` is empty returns `a` by reference; otherwise returns `[...a, ...b]`. Never mutates. Concatenation only — no dedup, no geometric merge.   |
| `intersects(interest, dirty): boolean` | `false` if either side is empty. Otherwise a nested loop returning `true` as soon as any `interest` rect overlaps any `dirty` rect (via `rectOverlaps`). O(N×M). **`DamageKind` is ignored** — only rects matter. |

You normally never call these directly; `SceneRoot` passes `RectSpace` to its `DirtyChannel`. They are public for advanced uses (e.g. building your own channel over the spatial region).

```ts
import { DirtyChannel } from '@dirtytalk/engine';
import { RectSpace } from '@dirtytalk/spatial';
import type { DirtyRegion } from '@dirtytalk/spatial';

const channel = new DirtyChannel<DirtyRegion>(RectSpace, scheduler);
```

## `SceneNode`

```ts
abstract class SceneNode {
  constructor(options?: SceneNodeOptions);
}
```

The abstract base class for every node in the scene tree. Subclass it and implement `paint`. Owns its bounds and contributes damage to the root channel via the parent chain.

### `SceneNodeOptions`

```ts
interface SceneNodeOptions {
  bounds?: Rect;
  clipsOverflow?: boolean;
}
```

| Option          | Default                      | Meaning                                                                     |
| --------------- | ---------------------------- | --------------------------------------------------------------------------- |
| `bounds`        | `{ x: 0, y: 0, w: 0, h: 0 }` | The node's initial axis-aligned rectangle.                                  |
| `clipsOverflow` | `false`                      | When `true`, _descendants'_ damage rects are clamped to this node's bounds. |

### Public properties

| Property        | Type                | Default                     | Meaning                                                                    |
| --------------- | ------------------- | --------------------------- | -------------------------------------------------------------------------- |
| `bounds`        | `Rect`              | from options or `{0,0,0,0}` | The node's rectangle. Mutable, but prefer `setBounds` for damage tracking. |
| `parent`        | `SceneNode \| null` | `null`                      | Parent in the tree; set by `adoptChild` / `removeChild`.                   |
| `children`      | `SceneNode[]`       | `[]`                        | Direct children in adoption order (= z-order; later = topmost).            |
| `clipsOverflow` | `boolean`           | `false`                     | When `true`, descendants' damage is clamped to this node's bounds.         |

### `abstract paint(layer)`

```ts
abstract paint(layer: unknown): void;
```

Called during the paint stage. Subclasses **must** implement it. `layer` is the renderer-provided draw surface; the spatial package never inspects it (during the culled walk `SceneRoot` calls `child.paint(undefined)`). Define `layer` to whatever your renderer needs.

### `rebuildData?()` (optional)

```ts
rebuildData?(): void;
```

Optional hook for nodes that own a data pipeline (e.g. plot mark layers). Called in **Stage 1** only for `data`-kind damage entries whose node defines it. Use it to re-bin or recompute derived geometry.

### `doLayout?()` (optional)

```ts
doLayout?(): void;
```

Optional hook for nodes that own layout. Called in **Stage 2** for any non-`paint` damage entry (`layout` _or_ `data`) whose node defines it. Use it to position content within `this.bounds`.

### `protected markDamaged(kind, rect?)`

```ts
protected markDamaged(kind: DamageKind, rect?: Rect): void;
```

The core damage emitter — protected, so only subclasses call it. Behaviour:

1. `rect` defaults to `this.bounds` if omitted.
2. The rect is clipped by walking up the parent chain: every ancestor with `clipsOverflow === true` clamps it (`rectClamp`) to that ancestor's bounds. Cumulative across multiple clipping ancestors. (A node's own `clipsOverflow` does not clip its own damage — only ancestors clip.)
3. Builds `{ rect: clipped, kind, node: this }`.
4. If a `batch` is active, pushes into the buffer and returns (no emit yet).
5. Otherwise resolves the root. If there is no connected root, it is a **silent no-op**. Otherwise calls `root._emitDamage(damage)`.

```ts
class Badge extends SceneNode {
  paint(_layer: unknown): void {}
  flash(): void {
    this.markDamaged('paint'); // defaults to this.bounds
  }
}
```

### `protected batch(fn)`

```ts
protected batch(fn: () => void): void;
```

Coalesces all `markDamaged` calls made inside `fn` before emitting.

- **Nested batch**: if a batch is already in flight, just runs `fn()` — the outer batch absorbs everything; the inner one does not emit separately.
- Runs `fn()` inside `try/finally`; the buffer is always cleared even if `fn` throws.
- **Empty buffer → no emit** (`batch(() => {})` emits nothing).
- On flush, buffered damages are grouped by kind. For each kind: one entry → emitted as-is; multiple → emitted as a single entry whose rect is `unionRects` of that kind's rects. Each grouped entry is emitted via the root.
- Kind-grouping order follows first-seen-kind order.

```ts
class Panel extends SceneNode {
  paint(_layer: unknown): void {}
  redrawTwoRegions(): void {
    this.batch(() => {
      this.markDamaged('paint', { x: 0, y: 0, w: 30, h: 30 });
      this.markDamaged('paint', { x: 50, y: 50, w: 20, h: 20 });
    });
    // Same-kind rects union -> beginFrame gets ONE region:
    //   [{ x: 0, y: 0, w: 70, h: 70 }]
  }
}
```

:::caution[batch unions same-kind rects; a move does not]
`batch` collapses same-kind rects into one region. By contrast `setBounds` deliberately emits two _disjoint_ `paint` rects (old + new footprint) that are not unioned, so a multi-rect-scissor renderer can skip the dead gap between them.
:::

### `setBounds(next)`

```ts
setBounds(next: Rect): void;
```

The damage-tracked way to move or resize a node.

- **No-op if** `rectEquals(this.bounds, next)` — no damage, no mutation.
- Otherwise: emits `markDamaged('paint', prev)` (erase old footprint), assigns `this.bounds = next`, emits `markDamaged('paint', next)` (fill new footprint), and **if the node has a parent**, emits `markDamaged('layout')` (re-layout the parent). Net for a connected node with a parent: **2 paint + 1 layout**.
- On a root-less node it still mutates `this.bounds` but emits nothing.

```ts
node.setBounds({ x: 100, y: 40, w: 120, h: 40 });
// erase old rect (paint) + fill new rect (paint) + parent layout
```

### `adoptChild(child)`

```ts
adoptChild(child: SceneNode): void;
```

Attaches `child` as the topmost child of this node.

- If `child` already has a parent, detaches it first via `child.parent.removeChild(child)`.
- Sets `child.parent = this` and appends to `this.children` (so it becomes topmost in z-order).
- **If this node is connected to a root**, emits a single full-bounds `paint` for the child (`child.markDamaged('paint', child.bounds)`) so the newly-visible region paints. If not connected, no damage is emitted.

### `removeChild(child)`

```ts
removeChild(child: SceneNode): void;
```

Detaches `child` from this node.

- No-op if `child` is not in `this.children`.
- Splices the child out, then emits `child.markDamaged('paint', child.bounds)` to damage the vacated area, **then** sets `child.parent = null`. (Order matters: damage is emitted while the child is still parented so root resolution still works.)

<details>
<summary>Root resolution and clipping internals</summary>

`SceneNode` resolves its owning root by walking the parent chain, **starting at itself** — a node that is itself a root resolves to itself (so `SceneRoot.adoptChild` can emit adopt-time paint for its direct children). Root detection is structural/duck-typed: any ancestor exposing a function-valued `_emitDamage` member counts as a root. A node not connected to such a root silently swallows all damage. Damage rects are clipped by cumulative `rectClamp` against each ancestor whose `clipsOverflow` is `true`.

</details>

## `SceneRoot`

```ts
class SceneRoot extends SceneNode {
  constructor(renderer: Renderer2D, options?: SceneRootOptions);
}
```

The concrete root node. Owns the `DirtyChannel<DirtyRegion>`, the scheduler, and the `Renderer2D`, and drives the three-stage pipeline. Inherits all of `SceneNode` (`bounds`, `parent`, `children`, `clipsOverflow`, `setBounds`, `adoptChild`, `removeChild`, `markDamaged`, `batch`).

### Constructor

```ts
constructor(renderer: Renderer2D, options: SceneRootOptions = {})
```

| Parameter               | Notes                                                                             |
| ----------------------- | --------------------------------------------------------------------------------- |
| `renderer`              | Required. Stored on `this.renderer`.                                              |
| `options.scheduler`     | Default `new RAFScheduler()`. Pass `SyncScheduler` or `ManualScheduler` in tests. |
| `options.bounds`        | Passed to `super`; defaults to `{0,0,0,0}`. Used as the default interest region.  |
| `options.onFrameTiming` | Optional. When set, every rendered frame is timed and reported.                   |

On construction it creates `this.channel = new DirtyChannel(RectSpace, scheduler ?? new RAFScheduler())` and subscribes once with `interest = () => [{ rect: this.bounds, kind: 'paint' }]` (a thunk, re-evaluated per flush so resizing is respected) and callback `(dirty) => this._renderFrame(dirty)`.

### `SceneRootOptions`

```ts
interface SceneRootOptions {
  scheduler?: Scheduler; // default: new RAFScheduler()
  bounds?: Rect; // default interest region
  onFrameTiming?: (timing: FrameTiming) => void; // opt-in timing hook
}
```

### Public properties

| Property    | Type                                 | Notes                                                                                                                                                                                                           |
| ----------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `channel`   | `readonly DirtyChannel<DirtyRegion>` | The owned dirty channel. You can push marks directly via `channel.mark([...])`.                                                                                                                                 |
| `renderer`  | `readonly Renderer2D`                | The renderer contract instance.                                                                                                                                                                                 |
| `fullFrame` | `boolean` (default `false`)          | When `true`, damage is ignored: every frame repaints `[this.bounds]` and the paint walk visits all children (no culling). The "damage tracking off" baseline for cost comparison — leave `false` in production. |

### `paint(_layer)`

```ts
paint(_layer: unknown): void;
```

The root does not paint itself. It walks children in adoption order and calls each `child.paint(_layer)`. This is the un-culled walk, distinct from the culled walk used during rendering.

### `hitTest(x, y)`

```ts
hitTest(x: number, y: number): SceneNode | null;
```

Returns the topmost, deepest node containing the point, or `null`.

- Walks children in reverse adoption order (topmost = last adopted wins).
- For the first child whose bounds contain `(x, y)` (`pointInRect`, half-open), recurses and returns the deepest descendant hit, else that child itself.
- Returns `null` if no child contains the point. **The root is never a valid hit target.**

```ts
const node = root.hitTest(120, 35); // SceneNode | null
```

### `channel`-direct marking

Because `channel` is public, you can mark damage that has no owning node — e.g. a manual full-region invalidation:

```ts
root.channel.mark([{ rect: { x: 0, y: 0, w: 800, h: 600 }, kind: 'paint' }]);
```

### The render pipeline (behaviour)

When the channel flushes, the root runs three ordered stages over the flushed `DirtyRegion`:

1. **Stage 1 — data.** For each entry: if `kind === 'data'` and the node defines `rebuildData`, call it.
2. **Stage 2 — layout.** For each entry: if `kind !== 'paint'` (so `layout` or `data`) and the node defines `doLayout`, call it.
3. **Stage 3 — paint.** `regions = fullFrame ? [this.bounds] : dirty.map(d => d.rect)` (the individual, disjoint rects — not their union). Call `renderer.beginFrame(regions)`; paint each top-level child whose bounds overlap a region, in adoption order (this is the cull); call `renderer.endFrame()`.

Strict per-frame call order for a `data` damage: `rebuildData → doLayout → beginFrame → paint → endFrame`. The cull is one level deep — only direct children of the root are culled; a painted child draws its own subtree.

### `Renderer2D`

```ts
interface Renderer2D {
  beginFrame(regions: readonly Rect[]): void;
  endFrame(): void;
}
```

The renderer contract the package ships (no implementation). `beginFrame(regions)` begins a frame clipped/scissored to the given damage regions; **the array is never empty when called**, and `regions` is the list of _individual_ damage rects, not their union. A v1 renderer may `unionRects(regions)` and clip to the bounding box, or ignore `regions` and clear the whole canvas; a multi-rect renderer scissors to each. `endFrame()` takes no arguments (submit/flush).

```ts
const renderer: Renderer2D = {
  beginFrame(regions) {
    // v1: clip to the bounding box of all damage
    const box = unionRects([...regions]);
    ctx.save();
    ctx.beginPath();
    ctx.rect(box.x, box.y, box.w, box.h);
    ctx.clip();
    ctx.clearRect(box.x, box.y, box.w, box.h);
  },
  endFrame() {
    ctx.restore();
  },
};
```

### `FrameTiming`

```ts
interface FrameTiming {
  layoutMs: number; // ms in data + layout stages (rebuildData + doLayout)
  paintMs: number; // ms in paint stage (beginFrame -> paint walk -> endFrame)
  paintedNodes: number; // top-level nodes whose paint() actually ran this frame
}
```

Reported via `onFrameTiming` exactly once per _rendered_ frame. `paintedNodes` is the headline cost signal — it scales with the damaged area (every child in full-frame mode), not the scene size. When `onFrameTiming` is omitted there is **zero overhead**: `performance.now()` is never called.

```ts
const root = new SceneRoot(renderer, {
  bounds: { x: 0, y: 0, w: 800, h: 600 },
  onFrameTiming: ({ layoutMs, paintMs, paintedNodes }) => {
    console.log(
      `layout ${layoutMs}ms paint ${paintMs}ms nodes ${paintedNodes}`,
    );
  },
});
```

## `PointerRouter`

```ts
class PointerRouter {
  constructor(root: SceneRoot);
  dispatch(e: SpatialPointerEvent): SceneNode | null;
}
```

Routes pointer events into the scene with capture semantics. Framework-agnostic: you translate DOM `PointerEvent`s into `SpatialPointerEvent`s at the boundary. Maintains a private capture map keyed by `pointerId`.

### `SpatialPointerEvent`

```ts
interface SpatialPointerEvent {
  type: 'down' | 'move' | 'up' | 'cancel';
  x: number;
  y: number;
  buttons: number;
  pointerId: number;
}
```

A minimal, surface-agnostic pointer event. Build it from a DOM event: `{ type, x: e.offsetX, y: e.offsetY, buttons: e.buttons, pointerId: e.pointerId }`.

### `PointerHandler`

```ts
interface PointerHandler {
  onPointerDown?(e: SpatialPointerEvent): void;
  onPointerMove?(e: SpatialPointerEvent): void;
  onPointerUp?(e: SpatialPointerEvent): void;
  onPointerCancel?(e: SpatialPointerEvent): void;
}
```

The optional handler interface a `SceneNode` may implement to receive pointer callbacks. The router treats nodes as `Partial<PointerHandler>` and optional-chains the matching method — a node with no handler is still a valid hit target, receives no callback, and never throws.

### `constructor(root)`

```ts
constructor(root: SceneRoot)
```

Holds the root for hit-testing.

### `dispatch(e)`

```ts
dispatch(e: SpatialPointerEvent): SceneNode | null;
```

Dispatches an event and returns the receiving node (or `null`). Capture-based semantics:

| Event                                 | Behaviour                                                                                                                                                      |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `down`                                | Hit-tests via `root.hitTest`. On a hit: captures the node for `e.pointerId`, invokes `onPointerDown`, returns it. On a miss: captures nothing, returns `null`. |
| `move`/`up`/`cancel` **with capture** | Delivers to the captured node (even if the pointer drifted outside its bounds). On `up`/`cancel`, releases the capture. Returns the captured node.             |
| `move` **uncaptured**                 | Hit-tests by current position; invokes `onPointerMove` on the hit (if any); returns it or `null`.                                                              |
| `up`/`cancel` **uncaptured**          | Dropped — returns `null`, no handler invoked.                                                                                                                  |

Multiple `pointerId`s are tracked independently. Hover is just `move` dispatch — a node repaints on hover by calling `markDamaged('paint')` inside `onPointerMove`.

```ts
const router = new PointerRouter(root);

const hit = router.dispatch({
  type: 'down',
  x: 120,
  y: 35,
  buttons: 1,
  pointerId: 1,
});
// `hit` is the captured node; subsequent move/up for pointerId 1 follow it.
```

## See also

- [Getting Started](/dirtytalk/spatial/getting-started) — install and build a working scene.
- [Concepts](/dirtytalk/spatial/concepts) — the damage model, pipeline, and pointer routing explained.
- [Engine: API Reference](/dirtytalk/engine/api-reference) — `Space`, `DirtyChannel`, and the scheduler classes.
- [Engine: Concepts](/dirtytalk/engine/concepts) — coalescing, interest, and flush semantics.

---

# Concepts

> The model behind @dirtytalk/spatial — why a single dirty bit loses information, the damage list that replaces it, and the data → layout → paint pipeline.

Source: /dirtytalk/spatial/concepts/

This page explains the model behind `@dirtytalk/spatial`: why a single dirty bit is not enough, how the damage list replaces it, and how the scene root turns a flushed list of damage into ordered data → layout → paint work. It is the _why_ and the _mental model_. For a hands-on walkthrough, start with [Getting Started](/dirtytalk/spatial/getting-started); for the exhaustive surface, see the [API Reference](/dirtytalk/spatial/api-reference).

## The problem: a single dirty bit loses information

After a mutation, every renderer faces three questions: _what_ changed, _who_ cares, and _when_ do we tell them. The naive answer is a boolean: "something is dirty, repaint." That bit is cheap to set and tells you nothing useful. It cannot tell the renderer _which pixels_ to redraw, so the renderer clears the whole canvas. It cannot tell the pipeline _what kind_ of change happened, so even a colour tweak re-runs layout. The dirty bit is lossy by construction — it throws away precisely the information you need to do less work.

The fix is to make "what changed" a _value_, not a flag. In the 2D-spatial domain that value is a list of **damage entries**, each carrying a rectangle (where) and a kind (what sort of change). A subscriber can intersect its interest against the list cheaply; the renderer can rasterise exactly the listed rectangles; the pipeline can decide, per entry, which stages to run. The damage list is computed once at the source and shared by everyone downstream.

This is the DirtyTalk thesis applied to pixels. The same engine primitives power [`@dirtytalk/structural`](/dirtytalk/structural/concepts) for state-shaped domains; there the region is a set of paths instead of a set of rects.

## Rect: the unit of "where"

A `Rect` is an axis-aligned rectangle in CSS pixels, with a top-left origin:

```ts
interface Rect {
  x: number;
  y: number;
  w: number; // width  — note: w/h, not width/height
  h: number;
}
```

All spatial geometry is expressed in these. The package ships a small set of pure rect helpers — no side effects, allocation-light:

| Helper                    | Answers                                                  |
| ------------------------- | -------------------------------------------------------- |
| `rectOverlaps(a, b)`      | Do these two rects share positive area?                  |
| `rectEquals(a, b)`        | Are these structurally identical (field-by-field `===`)? |
| `unionRects(rects)`       | What is the bounding box of all of these?                |
| `rectClamp(inner, outer)` | What is the intersection of these two?                   |
| `pointInRect(x, y, r)`    | Does this point fall inside this rect?                   |

Two conventions matter and are consistent across the package:

- **Half-open intervals.** Both `rectOverlaps` and `pointInRect` treat the bottom and right edges as _exclusive_: a point at `r.x + r.w` is _outside_, and two rects whose edges merely touch do **not** overlap. This matches the CSS pixel-grid convention and means adjacent tiles never double-count a shared edge.
- **Zero-area rects are empty.** A rect with `w <= 0` or `h <= 0` overlaps nothing and contains no points. `unionRects([])` returns the origin sentinel `{ x: 0, y: 0, w: 0, h: 0 }`.

:::caution[`rectClamp` is intersection, not "move inside"]
Despite the name, `rectClamp(inner, outer)` returns the _geometric intersection_ of the two rects, flooring width and height at zero. If `inner` lies entirely outside `outer`, you get a zero-area rect — not `inner` nudged inward. It is used to clip damage to clipping ancestors, which is exactly an intersection.
:::

## DamageKind: the unit of "what sort"

Each damage entry carries a `kind` that classifies the change and, through it, decides which pipeline stages run:

```ts
type DamageKind = 'paint' | 'layout' | 'data';
```

| Kind     | Emit when                                                                                | Stages triggered                                    |
| -------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `paint`  | A visual-only field changed — colour, label, pressed/hover state. Geometry is unchanged. | Paint only.                                         |
| `layout` | The node's bounds changed. `setBounds` emits this for the parent automatically.          | Layout (`doLayout`) → paint.                        |
| `data`   | The underlying data set changed — e.g. new plot samples that must be re-binned.          | Data (`rebuildData`) → layout (`doLayout`) → paint. |

The ordering is a containment hierarchy: `data` implies `layout` implies `paint`. A `data` change must rebuild derived data, which may move things, which must be redrawn. A `paint` change skips straight to drawing. Stage selection is **per entry**: in a single flush that mixes kinds, a `data` node runs all three stages while a `paint` node in the same flush only paints.

A full damage entry is:

```ts
interface Damage {
  rect: Rect;
  kind: DamageKind;
  node?: unknown; // the emitting SceneNode at runtime; optional for root-level marks
}
```

`node` is typed `unknown` on purpose so the `types.ts` module has no import cycle with `scene-node.ts`. At runtime it holds the `SceneNode` that emitted the damage (the root casts it back when running the pipeline). It is optional because damage pushed directly into the channel — not through a node — may have no owning node.

## RectSpace: the algebra the channel speaks

The engine's `DirtyChannel` is generic over a region type via a `Space<Region>` — four pure methods that define how regions combine and test for overlap. `RectSpace` is that algebra instantiated for `DirtyRegion`, which is simply `readonly Damage[]`:

```ts
type DirtyRegion = readonly Damage[];

// RectSpace satisfies Space<DirtyRegion>:
//   empty()                 -> []  (a fresh array each call)
//   isEmpty(r)              -> r.length === 0
//   union(a, b)             -> [...a, ...b]  (with identity short-circuits)
//   intersects(interest, d) -> any interest rect overlaps any dirty rect
```

Three properties of this v1 implementation are worth internalising:

- **`union` is concatenation with a reference short-circuit.** If one side is empty, the other side is returned _by reference_ (no copy); otherwise the two arrays are concatenated into a fresh one. There is no dedup and no geometric merge — damage entries accumulate as a plain list. This is safe precisely because `DirtyRegion` is `readonly`: nobody may mutate an array returned by `union` or `empty`.
- **`intersects` ignores `DamageKind`.** Overlap is purely geometric: it returns `true` as soon as any interest rect overlaps any dirty rect, regardless of kind. A `paint` interest matches a `layout` damage at the same rect.
- **It is O(N×M).** Both `union` and `intersects` are linear/quadratic over a plain array. There is no spatial index in v1. For typical per-frame damage counts this is cheap; it is a deliberate simplicity trade-off, not an oversight.

:::note[Why a list and not a merged region?]
A merged region (one big union rect, or a coverage mask) would lose the disjoint structure that makes partial redraw pay off. Keeping damage as a list of individual rects lets a multi-rect-scissor renderer skip the dead space _between_ damaged areas — most importantly the gap a node leaves behind when it moves. See the move discussion under `setBounds` below.
:::

## SceneNode: who owns bounds and emits damage

A `SceneNode` is one node in the retained scene tree. It is abstract — you subclass it and implement `paint`. Its responsibilities:

- **Own its `bounds`.** The node's axis-aligned rectangle. Mutate it through `setBounds` (which tracks damage) rather than assigning directly.
- **Hold the parent chain.** `parent` and `children` form the tree. `children` is in _adoption order_, which is also _z-order_: later-adopted children are topmost.
- **Emit damage.** The protected `markDamaged(kind, rect?)` is how a node declares that a region of itself changed. The rect defaults to the node's bounds and is clipped on the way up by any ancestor with `clipsOverflow === true`.
- **Coalesce mutations.** The protected `batch(fn)` buffers all `markDamaged` calls made inside `fn` and flushes them grouped by kind when `fn` returns.

### How damage reaches the root

`markDamaged` does not talk to the channel directly. It resolves the owning root by walking _up_ the parent chain (starting at the node itself), and calls the root's emit method. Root identity is **duck-typed**: any ancestor exposing a function-valued `_emitDamage` member counts as a root. The corollary is the most important gotcha in the package:

:::caution[Detached nodes silently swallow damage]
If a node is not connected to a root, `markDamaged` is a no-op — it does not throw. `setBounds` still mutates `bounds`, and `adoptChild`/`removeChild` still wire the tree, but no damage is emitted. Adopt-time paint only fires once the whole subtree is connected to a root. Build your tree, attach it to a `SceneRoot`, _then_ mutate.
:::

### batch vs. a move: two coalescing behaviours

These look similar but differ deliberately, and the difference is the whole reason damage is a list:

- **`batch(fn)` unions same-kind rects into one region.** Two `paint` marks inside a batch become a single `paint` entry whose rect is their bounding box. A `paint` plus a `data` mark become two entries (one per kind). The grouping is by kind, in first-seen order.
- **`setBounds` (a move) emits two _disjoint_ paint rects, not unioned.** Moving a node emits `paint` over the old footprint (erase) and `paint` over the new footprint (fill), plus a `layout` for the parent. These two paint rects are deliberately _not_ unioned at the channel level, so a renderer that scissors per-rect leaves the dead gap between the old and new positions untouched. Unioning them would force a repaint of everything in between.

If `setBounds` is called with an equal rect, it is a complete no-op — no damage, no mutation.

## SceneRoot: the three-stage pipeline

`SceneRoot` is the concrete node at the top of the tree. It owns the `DirtyChannel`, the scheduler, and the `Renderer2D`, and it subscribes itself exactly once at construction. Its interest is a _thunk_ returning its current bounds, so resizing the root is respected on the next flush. Any damage overlapping the root's bounds triggers a frame.

When the channel flushes, the root receives the coalesced `DirtyRegion` and runs three ordered stages over it:

1. **Stage 1 — data.** For each entry whose `kind === 'data'`, if its node defines `rebuildData()`, call it. This is where a plot layer re-bins samples or recomputes mark geometry.
2. **Stage 2 — layout.** For each entry whose `kind !== 'paint'` (so `layout` _and_ `data`), if its node defines `doLayout()`, call it. Data changes flow through here too, because new data may need repositioning.
3. **Stage 3 — paint.** Compute the paint regions — in normal mode these are the _individual_ damage rects (`dirty.map(d => d.rect)`), **not** their union. Call `renderer.beginFrame(regions)`, then walk the children in adoption order painting only those whose bounds overlap a region (the _cull_), then call `renderer.endFrame()`.

For a single `data` damage the strict call order is: `rebuildData → doLayout → beginFrame → paint → endFrame`.

<details>
<summary>Culling is where the win lands, and it is one level deep</summary>

`_paintCulled` walks the root's direct children and paints a child only if its bounds overlap at least one damage region. Repaint cost therefore scales with the _damaged area_, not the _scene size_ — the headline benefit of damage tracking. The cull is one level deep: only the root's direct children are tested. A child that survives the cull is responsible for drawing its own subtree however it likes. If you set `root.fullFrame = true`, the cull is bypassed: every frame repaints `[this.bounds]` and every child paints. That mode exists as a baseline for measuring the cost difference, not for production.

</details>

The optional `onFrameTiming` hook reports `{ layoutMs, paintMs, paintedNodes }` per rendered frame. When the hook is omitted, `performance.now()` is never called — there is zero timing overhead in the common case.

## PointerRouter: hit-testing and z-order

Input is the dual of output: the renderer asks "what is at this rect?", the pointer router asks "what is at this point?". `PointerRouter` answers by hit-testing the tree.

`SceneRoot.hitTest(x, y)` walks children in _reverse_ adoption order, so the topmost (last-adopted) child wins when several overlap. For the first child whose bounds contain the point (`pointInRect`, half-open), it recurses and returns the _deepest_ descendant hit, or that child if no grandchild matches. If no child contains the point it returns `null` — the root itself is never a valid hit target.

`PointerRouter.dispatch(e)` adds **capture** semantics on top of hit-testing:

- A `down` hit-tests, _captures_ the hit node for that `pointerId`, invokes its `onPointerDown`, and returns it. A miss captures nothing and returns `null`.
- A `move`/`up`/`cancel` with an existing capture is delivered to the _captured_ node even if the pointer has drifted outside its bounds — this is what makes dragging work. An `up` or `cancel` releases the capture.
- An _uncaptured_ `move` routes by current hit (this is how hover works). An _uncaptured_ `up`/`cancel` is dropped and returns `null`.

Handlers are optional. The router treats a node as a `Partial<PointerHandler>` and optional-chains the relevant method, so a node with no handler is a valid, returnable hit target that simply receives no callback and never throws. The router is framework-agnostic: `SpatialPointerEvent` is a plain object you build from a DOM `PointerEvent` at the boundary.

## The Renderer2D contract: v1 vs. the planned v2

`SceneRoot` never rasterises. It calls two abstract hooks on the renderer you supply:

```ts
interface Renderer2D {
  beginFrame(regions: readonly Rect[]): void; // never called with an empty array
  endFrame(): void;
}
```

The contract's subtlety is in `regions`. It is the list of the frame's _individual_ damage rects, **not** their union. A far single-frame move arrives as two disjoint rects (erase old, fill new), so a renderer that scissors to each rect leaves the dead gap untouched.

- **v1 — bounding-rect redraw.** The simplest correct renderer ignores the disjoint structure: call `unionRects(regions)` and clip to that one bounding box, or ignore `regions` entirely and clear the whole canvas. Correct, easy, but repaints the gap.
- **planned v2 — tile/scissor redraw.** A renderer that issues one scissored draw call per rect (or per damaged tile) redraws only the listed areas and skips everything between them. The damage list is shaped to make this possible — that is why same-kind batch rects are unioned but a move's two footprints are not.

## What it is not

- **Not a GPU renderer.** It ships the `Renderer2D` contract, not an implementation. You bring the rasteriser.
- **Not a spatial index.** v1 uses a plain array; `union` concatenates and `intersects` is O(N×M). No dedup, no quadtree.
- **Not auto-tracked reactivity.** `paint()` runs because a node was _damaged_, not because a field was read. This is a declared-damage model, not a dependency graph like React or MobX. Contrast [BlaC tracked state](/core/tracked).
- **Not a virtual-scene diff.** Nodes declare their own damage; the renderer trusts the declaration. There is no reconciliation pass.
- **Not an animation primitive.** Animate by calling `markDamaged('paint')` each step.
- **Not coupled to the browser.** No dependency on `window`, `document`, or `HTMLCanvasElement`. `SpatialPointerEvent` is a plain object you construct at the DOM boundary.

## See also

- [Getting Started](/dirtytalk/spatial/getting-started) — build a working scene step by step.
- [API Reference](/dirtytalk/spatial/api-reference) — every type, helper, method, and option.
- [Engine: Concepts](/dirtytalk/engine/concepts) — the `Space` algebra, `DirtyChannel`, and scheduler model this builds on.
- [Structural: Concepts](/dirtytalk/structural/concepts) — the same engine applied to path-set state.

---

# Getting Started

> From an empty file to a live scene graph that paints only what changed — a stub renderer, a SceneNode, a SceneRoot, and pointer routing.

Source: /dirtytalk/spatial/getting-started/

This page gets you from an empty file to a live scene graph that paints only what changed. It is hands-on: you will build a stub renderer, a tiny `Button` node, wire up a `SceneRoot`, mutate state, and watch the exact damaged region flow through the pipeline. Then you will route a DOM `PointerEvent` into the scene. If you want the _why_ behind the design, read [Concepts](/dirtytalk/spatial/concepts); for the exhaustive surface, see the [API Reference](/dirtytalk/spatial/api-reference).

## What this package is for

`@dirtytalk/spatial` is the 2D-spatial instantiation of the DirtyTalk thesis: compute _what changed_ once, at the source, as a list of rectangle-carrying damage entries, so every subscriber can do less work. A renderer normally has to choose between repainting the whole canvas (cheap to write, expensive to run) or hand-rolling per-widget invalidation (fast, but bespoke and bug-prone). This package gives you the second outcome with the first amount of effort: nodes declare their own damage, the root coalesces it through a scheduler, and the paint walk is culled to the damaged area.

It is a _compute layer_, not a rendering engine. It tells you which rectangles to redraw and in what order to run data/layout/paint work. You supply the actual rasteriser behind the `Renderer2D` contract.

## Install

`@dirtytalk/spatial` depends on `@dirtytalk/engine` — the engine provides the `Space`, `DirtyChannel`, and `Scheduler` primitives that the scene root is built on. Install both.

<Tabs syncKey="pkg">
<TabItem label="pnpm">

```bash
pnpm add @dirtytalk/spatial @dirtytalk/engine
```

</TabItem>
<TabItem label="npm">

```bash
npm install @dirtytalk/spatial @dirtytalk/engine
```

</TabItem>
<TabItem label="yarn">

```bash
yarn add @dirtytalk/spatial @dirtytalk/engine
```

</TabItem>
</Tabs>

:::note[Single entry point]
Everything is exported from the package root. There are no subpath entries — import `Rect`, `SceneNode`, `SceneRoot`, `PointerRouter`, and the rect helpers all from `@dirtytalk/spatial`. Scheduler classes (`SyncScheduler`, `ManualScheduler`, `RAFScheduler`, `MicrotaskScheduler`) come from `@dirtytalk/engine`.
:::

## A complete minimal scene

We will build the smallest scene that demonstrates the whole loop: a renderer that logs frames, a node that knows how to invalidate itself, and a root that drives the pipeline.

### Step 1 — a stub renderer

The package ships the `Renderer2D` _contract_, not an implementation. A renderer is just an object with `beginFrame(regions)` and `endFrame()`. For learning, log the regions you are handed.

```ts
import type { Renderer2D, Rect } from '@dirtytalk/spatial';

const stubRenderer: Renderer2D = {
  beginFrame(regions: readonly Rect[]): void {
    console.log('beginFrame', regions);
  },
  endFrame(): void {
    console.log('endFrame');
  },
};
```

`beginFrame` receives the frame's _individual_ damage rects (never an empty array). `endFrame` takes no arguments and is where a real renderer would submit or flush.

### Step 2 — a node that damages itself

Subclass `SceneNode` and implement the abstract `paint` method. When the node's visible state changes, call the protected `markDamaged('paint')` to tell the root that this node's rectangle needs repainting.

```ts
import { SceneNode } from '@dirtytalk/spatial';

class Button extends SceneNode {
  private _label = '';

  get label(): string {
    return this._label;
  }

  setValue(label: string): void {
    if (this._label === label) return; // skip redundant work
    this._label = label;
    this.markDamaged('paint'); // visual-only change -> paint stage only
  }

  paint(_layer: unknown): void {
    // Draw the button into the renderer-provided layer.
    // The spatial package never inspects `_layer` — it's yours to define.
  }
}
```

Two things to notice. First, the early-return guard: if the label did not change, do not emit damage. Second, `markDamaged('paint')` with no rect defaults to the node's own `bounds`, which is exactly the region a label change dirties.

### Step 3 — construct the root with a scheduler

`SceneRoot` owns the dirty channel, the scheduler, and the renderer. For a predictable, synchronous teaching loop, pass a `SyncScheduler` — every `markDamaged` flushes immediately, so one mutation produces one frame.

```ts
import { SceneRoot } from '@dirtytalk/spatial';
import { SyncScheduler } from '@dirtytalk/engine';

const root = new SceneRoot(stubRenderer, {
  scheduler: new SyncScheduler(),
  bounds: { x: 0, y: 0, w: 800, h: 600 },
});
```

The `bounds` you pass become the root's _interest region_: any damage overlapping that rectangle triggers a frame.

### Step 4 — set bounds and adopt the child

Give the button a footprint and attach it to the tree with `adoptChild`. Because the root is connected, the adoption emits a one-time full-bounds `paint` for the newly visible child.

```ts
const btn = new Button({ bounds: { x: 10, y: 10, w: 120, h: 40 } });

root.adoptChild(btn);
// => beginFrame [ { x: 10, y: 10, w: 120, h: 40 } ]
// => endFrame
```

### Step 5 — mutate and observe the painted region

Now change the label. The node damages its own bounds, the channel flushes synchronously, and the renderer is handed exactly that rectangle.

```ts
btn.setValue('Click me');
// => beginFrame [ { x: 10, y: 10, w: 120, h: 40 } ]
// => endFrame

btn.setValue('Click me'); // no change -> no damage -> no frame
// (nothing logged)
```

The second call logs nothing: the guard in `setValue` short-circuits, so the channel never marks, and an empty flush fires no callback. This is the payoff in miniature — work is proportional to what actually changed.

:::tip[Scheduler choice changes everything about coalescing]
`SyncScheduler` flushes on every `mark`, so three mutations produce three frames. Swap in `ManualScheduler` (flush on `pump()`), `MicrotaskScheduler`, or the default `RAFScheduler`, and multiple mutations before the flush coalesce into one frame. See [Concepts](/dirtytalk/spatial/concepts) and the engine's [scheduler model](/dirtytalk/engine/concepts).
:::

### The full file

```ts
import { SceneNode, SceneRoot } from '@dirtytalk/spatial';
import type { Renderer2D, Rect } from '@dirtytalk/spatial';
import { SyncScheduler } from '@dirtytalk/engine';

const stubRenderer: Renderer2D = {
  beginFrame(regions: readonly Rect[]): void {
    console.log('beginFrame', regions);
  },
  endFrame(): void {
    console.log('endFrame');
  },
};

class Button extends SceneNode {
  private _label = '';
  get label(): string {
    return this._label;
  }
  setValue(label: string): void {
    if (this._label === label) return;
    this._label = label;
    this.markDamaged('paint');
  }
  paint(_layer: unknown): void {
    // draw with _layer
  }
}

const root = new SceneRoot(stubRenderer, {
  scheduler: new SyncScheduler(),
  bounds: { x: 0, y: 0, w: 800, h: 600 },
});

const btn = new Button({ bounds: { x: 10, y: 10, w: 120, h: 40 } });
root.adoptChild(btn);

btn.setValue('Click me');
```

## Wiring up pointer input

The scene graph does not know about the DOM. To drive it from real input, construct a `PointerRouter` over the root and translate each DOM `PointerEvent` into a plain `SpatialPointerEvent` at the boundary.

```ts
import { PointerRouter } from '@dirtytalk/spatial';
import type { SpatialPointerEvent } from '@dirtytalk/spatial';

const router = new PointerRouter(root);

canvas.addEventListener('pointerdown', (e) => {
  const spatialEvent: SpatialPointerEvent = {
    type: 'down',
    x: e.offsetX,
    y: e.offsetY,
    buttons: e.buttons,
    pointerId: e.pointerId,
  };

  const hit = router.dispatch(spatialEvent);
  // `hit` is the topmost SceneNode at (x, y), or null.
});
```

`dispatch` returns the node that received the event (or `null` if nothing was hit). A `down` _captures_ the hit node for that `pointerId`: subsequent `move`/`up`/`cancel` events for the same pointer are delivered to the captured node even if the pointer has drifted off its bounds — exactly the drag behaviour you want. Route every pointer phase through the same `dispatch`.

```ts
for (const [domType, spatialType] of [
  ['pointerdown', 'down'],
  ['pointermove', 'move'],
  ['pointerup', 'up'],
  ['pointercancel', 'cancel'],
] as const) {
  canvas.addEventListener(domType, (e) => {
    router.dispatch({
      type: spatialType,
      x: e.offsetX,
      y: e.offsetY,
      buttons: e.buttons,
      pointerId: e.pointerId,
    });
  });
}
```

To react to a pointer, give the node a handler method. Any of `onPointerDown`, `onPointerMove`, `onPointerUp`, `onPointerCancel` is optional; the router optional-chains them, so a node without a handler is still a valid hit target and simply receives no callback.

```ts
class HoverButton extends SceneNode {
  private _hovered = false;
  paint(_layer: unknown): void {}
  onPointerMove(_e: SpatialPointerEvent): void {
    if (this._hovered) return;
    this._hovered = true;
    this.markDamaged('paint'); // hover repaints, like any other state change
  }
}
```

Hover is just a `move` dispatch; the node decides whether the change is worth a repaint by calling `markDamaged`.

## When to reach for this package

Use `@dirtytalk/spatial` when you have a 2D scene where repainting everything on every change is too expensive, and you want a principled invalidation model rather than ad-hoc dirty flags. Good fits:

- A canvas/WebGPU UI with many widgets where most frames touch a small area.
- A chart or plot surface where data updates should re-bin and re-layout, but a hover should only repaint.
- Any retained-mode 2D tree that needs ordered data → layout → paint stages keyed off _what_ changed.

Reach for something else when you only ever full-frame repaint (then you do not need damage tracking), when you need a full GPU renderer out of the box (this ships only the contract), or when you want auto-tracked reactive reads — this is a _declared-damage_ model, not a dependency graph. The sibling [`@dirtytalk/structural`](/dirtytalk/structural/concepts) package applies the same engine to state-shaped (path-set) domains.

## See also

- [Concepts](/dirtytalk/spatial/concepts) — the damage model, the three-stage pipeline, and pointer routing explained.
- [API Reference](/dirtytalk/spatial/api-reference) — every export, signature, and option.
- [Engine: Concepts](/dirtytalk/engine/concepts) — the `Space` algebra, schedulers, and `DirtyChannel` that power the root.
- [DirtyTalk overview](/dirtytalk/) — the shared thesis across the three packages.

---

# API Reference

> The complete export-by-export reference for @dirtytalk/structural — PathInterner, the PathSet algebra, trackRender, the diff helpers, StructuralContainer, and useStructural.

Source: /dirtytalk/structural/api-reference/

The complete, export-by-export reference for `@dirtytalk/structural`. The package has two entry points: the main module `@dirtytalk/structural` (core, no React) and the React adapter `@dirtytalk/structural/react`. For the concepts behind these APIs, read [Concepts](/dirtytalk/structural/concepts); for a guided tour, [Getting Started](/dirtytalk/structural/getting-started).

## Module map

| Subpath                       | Exports                                                                                                                                                                                                                                                                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `@dirtytalk/structural`       | `PathId`, `ConsumerId` (types); `PathInterner`; `ALL_PATHS`, `emptyPathSet`, `pathSetUnion`, `pathSetEquals`, `PathSetSpace`, `PathSet`, `AllPaths`; `trackRender`, `TrackResult`; `diffAlongSkeleton`, `pathsFromPatch`, `changedPathsFromPatch`, `getAt`; `StructuralContainer`, `StructuralContainerOptions`, `DeepPartial` |
| `@dirtytalk/structural/react` | `useStructural` (the `UseStructuralOptions` and `UseStructuralResult` interfaces are declared alongside the hook and describe its parameter and return shapes)                                                                                                                                                                 |

:::caution[Schedulers are not re-exported]
`SyncScheduler`, `ManualScheduler`, `MicrotaskScheduler`, and `RAFScheduler` are **not** exported from `@dirtytalk/structural`. Import them from [`@dirtytalk/engine`](/dirtytalk/engine/api-reference). The container takes a scheduler via `StructuralContainerOptions.scheduler`, not as a positional argument.
:::

## Type aliases

```ts
/** An interned identifier for a path through state. Stable per Container class. */
export type PathId = number;

/** Opaque consumer identifier. */
export type ConsumerId = string | symbol;
```

`PathId` is the integer a `PathInterner` assigns to a dotted path string. `ConsumerId` identifies a registered consumer in a container's registry (the React hook uses the string from `useId()`).

## `PathInterner`

A bidirectional string ↔ `PathId` table. IDs are assigned monotonically from `0` in insertion order. One interner is shared per container _class_, but the class is standalone and directly instantiable.

```ts
export class PathInterner {
  intern(path: string): PathId;
  lookup(id: PathId): string;
  get size(): number;
}
```

### `intern(path)`

|           |                                |
| --------- | ------------------------------ |
| Signature | `intern(path: string): PathId` |
| Returns   | The `PathId` for `path`        |

Idempotent. Returns the existing ID if `path` was already interned; otherwise assigns the next sequential ID (`0, 1, 2, …`) and returns it. The same string always maps to the same ID.

### `lookup(id)`

|           |                                                              |
| --------- | ------------------------------------------------------------ |
| Signature | `lookup(id: PathId): string`                                 |
| Returns   | The dotted path string for `id`                              |
| Throws    | `RangeError` if `id < 0`, is not an integer, or `id >= size` |

Reverse lookup. The error message is `PathInterner.lookup: unknown PathId ${id} (size=${size})`.

### `get size()`

|           |                                |
| --------- | ------------------------------ |
| Signature | `get size(): number`           |
| Returns   | Count of unique interned paths |

Re-interning an already-seen string does not increase `size`.

```ts
import { PathInterner } from '@dirtytalk/structural';

const interner = new PathInterner();
const a = interner.intern('user.name'); // 0
const b = interner.intern('user.email'); // 1
interner.intern('user.name'); // 0 (idempotent)
interner.lookup(a); // 'user.name'
interner.size; // 2
interner.lookup(99); // throws RangeError
```

Independent instances have independent namespaces — both start at ID `0` for the same string.

## PathSet algebra

### `ALL_PATHS` and types

```ts
export const ALL_PATHS: unique symbol; // Symbol.for('@dirtytalk/structural/ALL_PATHS')
export type AllPaths = typeof ALL_PATHS;
export type PathSet = Set<PathId> | AllPaths;
```

`ALL_PATHS` is a registered sentinel symbol meaning "every possible path." Because it is created with `Symbol.for`, its identity is stable across module realms sharing the registry. A `PathSet` is either a concrete `Set<PathId>` or `ALL_PATHS`.

### `emptyPathSet()`

|           |                                                 |
| --------- | ----------------------------------------------- |
| Signature | `emptyPathSet(): PathSet`                       |
| Returns   | A fresh empty `Set<PathId>` (never `ALL_PATHS`) |

Allocates a new empty set on every call.

### `pathSetUnion(a, b)`

|           |                                                      |
| --------- | ---------------------------------------------------- |
| Signature | `pathSetUnion(a: PathSet, b: PathSet): PathSet`      |
| Returns   | The union; `ALL_PATHS` if either side is `ALL_PATHS` |

Pure. When both are Sets, allocates a new `Set` copy of `a` and adds all of `b`. Never mutates its inputs. `pathSetUnion(emptyPathSet(), r)` is a fresh set equal by value to `r` (not the same reference).

### `pathSetEquals(a, b)`

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| Signature | `pathSetEquals(a: PathSet, b: PathSet): boolean`                              |
| Returns   | `true` iff both are `ALL_PATHS`, or both Sets of equal size with the same IDs |

Order-independent. `ALL_PATHS` is never equal to any Set, including an empty one.

### `PathSetSpace`

```ts
export const PathSetSpace: Space<PathSet>;
```

The `Space<PathSet>` implementation consumed by the engine's `DirtyChannel`. Its members:

| Member                        | Behaviour                                                              |
| ----------------------------- | ---------------------------------------------------------------------- |
| `empty()`                     | `emptyPathSet()`                                                       |
| `isEmpty(r)`                  | `r !== ALL_PATHS && r.size === 0` (so `isEmpty(ALL_PATHS)` is `false`) |
| `union(a, b)`                 | `pathSetUnion(a, b)`                                                   |
| `intersects(interest, dirty)` | See below                                                              |

`intersects` semantics (load-bearing for wake-up decisions):

| `interest`  | `dirty`     | Result                                                                                        |
| ----------- | ----------- | --------------------------------------------------------------------------------------------- |
| `ALL_PATHS` | `ALL_PATHS` | `true`                                                                                        |
| `ALL_PATHS` | Set         | `true` iff `dirty` is non-empty                                                               |
| Set         | `ALL_PATHS` | `true` iff `interest` is non-empty                                                            |
| Set         | Set         | iterates the smaller set, looks up in the larger; `true` on the first shared ID, else `false` |

A consequence: `intersects(emptyPathSet(), ALL_PATHS)` is `false` — an empty interest never wakes.

```ts
import {
  ALL_PATHS,
  emptyPathSet,
  pathSetUnion,
  pathSetEquals,
  PathSetSpace,
} from '@dirtytalk/structural';

const a = new Set([0, 1]);
const b = new Set([1, 2]);
pathSetUnion(a, b); // Set { 0, 1, 2 } (new set; a and b untouched)
pathSetEquals(a, new Set([1, 0])); // true
PathSetSpace.intersects(a, b); // true (share 1)
PathSetSpace.intersects(emptyPathSet(), ALL_PATHS); // false
```

## `trackRender`

```ts
export interface TrackResult<S> {
  value: S; // the recording Proxy (or raw value for non-objects)
  paths: PathSet; // ALWAYS a Set<PathId>, NEVER ALL_PATHS
}

export const trackRender: <S>(
  state: S,
  interner: PathInterner,
) => TrackResult<S>;
```

| Param      | Type           | Meaning                                   |
| ---------- | -------------- | ----------------------------------------- |
| `state`    | `S`            | The state to wrap and record reads on     |
| `interner` | `PathInterner` | Interner used to assign IDs to read paths |

Returns `{ value, paths }`. `value` is a recording `Proxy` (or the raw value if `state` is not a wrappable object). `paths` is a **live** `Set<PathId>` that is empty on return and **grows as you read properties off `value`** — it is mutated after `trackRender` returns. `paths` is never `ALL_PATHS`.

Recording rules (exact):

- **Non-object short-circuit.** If `state` is a primitive, `null`, or `undefined`, returns `{ value: state, paths: <empty Set> }` with no proxy.
- **Own, non-symbol reads only.** Symbol keys and inherited/prototype properties never record. Re-reads do not re-record. Conditional reads record only the taken branch.
- **Leaf-only recording.** Reading `a.b.c` records `a.b.c` and drops the immediate parent (`a.b`) as it descends, yielding sibling-leaf isolation.
- **Primitives, `null`, `undefined` returned as-is** — but reading the key still records that field's path.
- **Nested plain objects/arrays** return child proxies recording into the same `paths` set, cached per target in a per-call `WeakMap` (so `value.user === value.user` within one render; independent across calls).
- **Iteration coarsens.** Array methods (`for..of`, `.map`, `.find`, `.reduce`, …) record the entry path only, not per-index paths or `.length`; their callbacks receive raw values. Direct index access records the leaf (`value.items[2].name` → `items.2.name`).
- **Leaf collection types** (`Map`, `Set`, `Date`, class instances) are not recursed; the field's path is recorded and the raw value returned. Wrappable = arrays, or objects whose prototype is `Object.prototype` or `null`.
- **Own methods on non-array objects are bound to the proxy** so internal `this.x` reads keep recording when invoked. Reading a method without invoking does not record.

```ts
import { PathInterner, trackRender } from '@dirtytalk/structural';

const interner = new PathInterner();
const { value, paths } = trackRender(
  { user: { name: 'a' }, items: [1, 2, 3] },
  interner,
);

void value.user.name; // records "user.name" (drops "user")
value.items.reduce((s, n) => s + n, 0); // records "items" only — not items.0/.length
// `paths` is now a Set<PathId> containing the IDs for "user.name" and "items".
```

## Diff helpers

```ts
export const getAt: (state: unknown, path: string) => unknown;

export const diffAlongSkeleton: <S>(
  prev: S,
  next: S,
  skeleton: PathSet,
  interner: PathInterner,
  equalsAt?: (pathId: PathId, prev: unknown, next: unknown) => boolean,
) => PathSet;

export const pathsFromPatch: <S>(
  patch: Partial<S>,
  interner: PathInterner,
  basePath?: string, // default '', internal recursion seed; callers omit
) => PathSet;

export const changedPathsFromPatch: <S>(
  prev: S,
  next: S,
  patch: Partial<S>,
  interner: PathInterner,
  equalsAt?: (pathId: PathId, prev: unknown, next: unknown) => boolean,
) => PathSet;
```

### `getAt(state, path)`

Reads the value at a dot-separated `path` (`""`, `"a"`, `"user.email"`, `"items.5.name"` — numeric segments index arrays via bracket access). An empty path returns `state` itself. Returns `undefined` for any missing, `null`, or primitive intermediate — **never throws**. Only own-property bracket access; no extra prototype walking.

### `diffAlongSkeleton(prev, next, skeleton, interner, equalsAt?)`

Walks each `PathId` in `skeleton`, reads the value at its path in `prev` and `next` via `getAt`, and includes the ID iff the values are not equal under `equalsAt` (default `Object.is`).

- `skeleton === ALL_PATHS` short-circuits to `ALL_PATHS`.
- An empty skeleton short-circuits to a fresh empty set, regardless of states.
- Pure — does not mutate `prev`, `next`, or `skeleton`.
- With the default `Object.is`: `NaN` compares equal; shared sub-tree references compare equal (no entry). An intermediate path (e.g. `user`) _is_ flagged if the outer object got a new reference, even when its leaves are unchanged.
- `equalsAt` is invoked as `(pathId, prevValue, nextValue)` — the per-path custom-equality seam.

```ts
import { PathInterner, diffAlongSkeleton } from '@dirtytalk/structural';

const interner = new PathInterner();
const skeleton = new Set([
  interner.intern('user.name'),
  interner.intern('user.email'),
]);

const prev = { user: { name: 'Ada', email: 'a@x.io' } };
const next = { user: { name: 'Grace', email: 'a@x.io' } };

const dirty = diffAlongSkeleton(prev, next, skeleton, interner) as Set<number>;
dirty.has(interner.intern('user.name')); // true
dirty.has(interner.intern('user.email')); // false
```

### `pathsFromPatch(patch, interner, basePath?)`

Flattens a patch tree into a `PathSet` of interned dotted paths with **tree-pulses-up** semantics: each plain-object branch contributes its own path _and_ recurses. `{ user: { email: 'x' } }` records both `"user"` and `"user.email"`. Leaves — arrays, primitives, `null`, `undefined`, class instances, `Date`, `Map`, `Set` — record their path and stop (arrays are atomic). An empty patch yields an empty set with nothing interned. Does not mutate input. `basePath` is an internal recursion seed; callers omit it.

:::note[Shape-based, not value-based]
`pathsFromPatch` is exported, but the container marks with `changedPathsFromPatch` instead. Use `pathsFromPatch` only when you want shape-based marking without value comparison.
:::

### `changedPathsFromPatch(prev, next, patch, interner, equalsAt?)`

Like `pathsFromPatch` but **value-filtered**: a path is included only when its value actually changed. It walks the same plain-object branches and pulses up, but compares `prev[key]` vs `next[key]` at each step (threading the parallel subtrees down — equivalent to `getAt` but without re-walking from the root). It **prunes recursion** into unchanged branches: a branch whose reference is `Object.is`-equal (and, by the immutable-update invariant, its entire subtree) is skipped. This makes patch-marking precise and skeleton-independent, so raw channel subscribers wake correctly while over-spread patches do not over-wake siblings. `equalsAt` is the same `(pathId, prev, next)` seam; default `Object.is`. Returns an empty set when nothing changed.

Example outcomes:

- Over-spread `{ user: { name: 'Grace', email: 'a@x.io' } }` where only `name` changed → `['user', 'user.name']`.
- Swapping a nested object → `['user', 'user.address', 'user.address.city']`.
- A custom equality treating equal-content arrays as equal → `[]`.

## `StructuralContainer<S>`

Abstract base class. Owns a piece of state `S`, a `DirtyChannel<PathSet>`, and a consumer registry. Subclass it; instances of the same subclass share one `PathInterner` (keyed by constructor).

### Options and types

```ts
export interface StructuralContainerOptions {
  /** Scheduler for the underlying DirtyChannel.
   *  Default: a fresh MicrotaskScheduler per instance. Tests/SSR should pass SyncScheduler. */
  scheduler?: Scheduler;
  /** Per-path-pattern equality override. Keys are EXACT dotted path strings
   *  (interned at construction). Glob/pattern matching is a follow-up — not supported. */
  equality?: ReadonlyMap<string, (a: unknown, b: unknown) => boolean>;
}

export type DeepPartial<T> =
  T extends ReadonlyArray<infer U>
    ? ReadonlyArray<DeepPartial<U>>
    : T extends Date | Map<unknown, unknown> | Set<unknown> | RegExp
      ? T
      : T extends object
        ? { [K in keyof T]?: DeepPartial<T[K]> }
        : T;
```

`DeepPartial<T>` recurses plain-object branches so nested patches type-check without casts; arrays become `ReadonlyArray<DeepPartial<U>>` (matching runtime: arrays are leaves, not per-index expandable); `Date | Map | Set | RegExp` pass through whole; primitives and functions are unchanged.

### Constructor

```ts
constructor(initial: S, options?: StructuralContainerOptions)
```

| Param               | Type                                     | Default                                         | Meaning                                                                                                      |
| ------------------- | ---------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `initial`           | `S`                                      | —                                               | The starting state                                                                                           |
| `options.scheduler` | `Scheduler`                              | `new MicrotaskScheduler()` (fresh per instance) | The scheduler for the underlying channel. Pass `SyncScheduler` for synchronous tests/SSR.                    |
| `options.equality`  | `ReadonlyMap<string, (a, b) => boolean>` | `undefined`                                     | Exact dotted-path → equality fn map; each key is interned at construction into an internal `Map<PathId, eq>` |

### Static

```ts
static getInternerFor(ctor: object): PathInterner
```

Returns the lazily-created `PathInterner` for a constructor, creating one on first call. Backed by a private static `WeakMap<object, PathInterner>` so constructors can be garbage-collected once all instances are gone. Same constructor → same interner; distinct constructors → distinct interners, even with identical state shapes. Path IDs never bleed across subclasses.

### Read accessors

| Accessor              | Type                    | Returns                                                |
| --------------------- | ----------------------- | ------------------------------------------------------ |
| `get state()`         | `S`                     | Current state. Immutable — do not mutate in place.     |
| `get interner()`      | `PathInterner`          | `StructuralContainer.getInternerFor(this.constructor)` |
| `get channel()`       | `DirtyChannel<PathSet>` | The underlying engine channel                          |
| `get consumerCount()` | `number`                | Number of registered consumers (registry size)         |

### Mutations

```ts
emit(next: S): void
patch(partial: DeepPartial<S>): void
update(fn: (state: S) => S): void
```

#### `emit(next)`

Replaces state with `next`.

- **Reference-equal short-circuit:** if `Object.is(state, next)`, a complete no-op (no mark, no notify).
- Sets the new state first.
- **Single-consumer skip:** if `consumerCount <= 1` (0 or 1 registered consumers), marks `ALL_PATHS` instead of diffing — the sole consumer (if any) wakes regardless of whether its interest overlaps the change.
- Otherwise (≥2 consumers): `diffAlongSkeleton(prev, next, skeleton, interner, equalsFn)` marks only observed-skeleton paths that actually changed.
- Then marks the channel.

#### `patch(partial)`

Shallow-or-deep merge of a `DeepPartial<S>`.

- **Empty patch is a no-op** (`Object.keys(partial).length === 0`).
- Computes `next` via an internal `deepMerge` that walks plain-object branches only; arrays, class instances, `Date`, `Map`, `Set`, primitives, `null`, `undefined` replace their slot atomically. It returns the **original `prev` reference when nothing actually changed** and keeps untouched subtree references stable.
- If `Object.is(prev, next)` (no-op merge), returns without marking.
- Applies the new state **before** marking, so consumers reading `state` inside the dirty callback see the new value.
- Marks via `changedPathsFromPatch` (value-filtered, skeleton-independent). `patch` ignores the skeleton and always value-diffs, regardless of consumer count.

#### `update(fn)`

Sugar for `this.emit(fn(this.state))`. Same semantics as `emit`, including the single-consumer skip and the reference-equal no-op.

:::caution[No in-place mutation]
There is no in-place mutation primitive. Mutating `state` directly bypasses change tracking silently. All updates must be immutable replacements via `emit`/`patch`/`update`.
:::

### Subscriptions and consumer registry

```ts
subscribe(interest: () => PathSet, cb: (dirty: PathSet) => void): () => void
registerConsumerPaths(id: ConsumerId, paths: PathSet): void
unregisterConsumer(id: ConsumerId): void
```

#### `subscribe(interest, cb)`

Pass-through to `channel.subscribe`. Returns an unsubscribe function. For devtools, plugins, and manual subscribers that bypass the tracker registry. These subscribers do **not** affect the skeleton or `consumerCount`. `interest` is a thunk evaluated lazily once per flush per subscriber; return `ALL_PATHS` for "wants everything."

```ts
import { ALL_PATHS } from '@dirtytalk/structural';

const unsub = container.subscribe(
  () => ALL_PATHS,
  (dirty) => console.log('changed', dirty),
);
// later:
unsub();
```

#### `registerConsumerPaths(id, paths)`

Records a consumer's observed `PathSet`, used to build the skeleton that `emit`/`update` diff against. **Fast-path skip:** if the previous paths for `id` are `pathSetEquals` to the new ones, returns without recomputing. Otherwise stores them and recomputes the skeleton (the union of all consumer paths). Re-registering an existing `id` replaces (does not add) — `consumerCount` is keyed by `id`.

#### `unregisterConsumer(id)`

Removes the consumer and recomputes the skeleton only if the `id` was present.

### Equality and the skeleton

- **Custom equality** (`options.equality`) is used by both `emit` (via `diffAlongSkeleton`) and `patch` (via `changedPathsFromPatch`). When configured, the per-path callback resolves the matched path's function, falling back to `Object.is` for unmatched paths. When no overrides exist, the helpers use plain `Object.is` (the fast path). A custom equality returning `true` suppresses the diff entry even for a real value change.
- **The skeleton** is the union of all registered consumers' `PathSet`s, recomputed (`O(consumers × paths)`) on every registry change. It is consulted only by `emit`/`update`; `patch` ignores it.

### Full example

```ts
import { StructuralContainer, ALL_PATHS } from '@dirtytalk/structural';
import { SyncScheduler } from '@dirtytalk/engine';

interface CounterState {
  count: number;
  label: string;
}

class Counter extends StructuralContainer<CounterState> {
  increment() {
    this.patch({ count: this.state.count + 1 });
  }
}

const c = new Counter(
  { count: 0, label: 'counter' },
  { scheduler: new SyncScheduler() },
);

const unsub = c.subscribe(
  () => ALL_PATHS, // plugin-style: wants everything
  (dirty) => console.log(c.state, dirty),
);

c.increment(); // SyncScheduler → fires synchronously: { count: 1, ... }
unsub();
```

## `useStructural` (`@dirtytalk/structural/react`)

```ts
export interface UseStructuralOptions {
  select?: never; // reserved; no selector option is supported
}

export interface UseStructuralResult<S, C extends StructuralContainer<S>> {
  0: S;
  1: C;
  readonly length: 2;
  [Symbol.iterator](): IterableIterator<S | C>;
}

export function useStructural<S, C extends StructuralContainer<S>>(
  container: C,
  _options?: UseStructuralOptions,
): readonly [S, C];
```

| Param       | Type                               | Meaning                                 |
| ----------- | ---------------------------------- | --------------------------------------- |
| `container` | `C extends StructuralContainer<S>` | The container instance to bind to       |
| `_options`  | `UseStructuralOptions`             | Reserved and currently inert (see note) |

Returns `[state, container]` (a readonly tuple). `state` is a recording proxy for this render: reading fields off it during render records this component's observed paths, and only those paths trigger re-renders.

Mechanics:

- Consumer id from React's `useId()`. Re-renders are forced via `useReducer((x) => x + 1, 0)` — no virtual DOM; React reconciles.
- Each render calls `trackRender(container.state, container.interner)` and stores the live `paths` set in a ref. `registerConsumerPaths` is intentionally **not** called in the render body (paths are empty until JSX reads the proxy; registering then would freeze an empty skeleton and silently drop wakeups).
- A `useLayoutEffect` (every render, no deps) registers the now-populated path ref after render — keeping the container's skeleton in sync with what was actually read. Conditional reads adapt the skeleton automatically; no selector needed.
- A `useEffect` keyed on `[container, consumerId]` re-registers paths (handling StrictMode cleanup re-runs where the render body did not re-run) and subscribes `() => pathRef.current` to force re-renders. Cleanup unsubscribes and unregisters the consumer.
- StrictMode-safe: double-invoke leaves a clean registry; unmount returns `consumerCount` to 0; two components on one container get distinct consumer ids; raw `subscribe` plugins coexist with hook consumers.

:::note[The options arg is inert]
The `_options` argument is reserved by the `select?: never` typing — there is no selector API. Path recording replaces selectors, so passing anything has no effect today.
:::

```tsx
import { useStructural } from '@dirtytalk/structural/react';

function CounterDisplay({ counter }: { counter: Counter }) {
  const [state, container] = useStructural(counter);
  // Reading state.count records "count"; a patch to "label" won't re-render this.
  return <button onClick={() => container.increment()}>{state.count}</button>;
}
```

## See also

- [Structural: Getting Started](/dirtytalk/structural/getting-started) — install and first container.
- [Structural: Concepts](/dirtytalk/structural/concepts) — path sets, the skeleton, the tracker, the diff model.
- [Engine: API Reference](/dirtytalk/engine/api-reference) — `DirtyChannel`, `Space`, and the schedulers you inject.
- [Engine: Concepts](/dirtytalk/engine/concepts) — the flush/coalescing model these mutations rely on.

---

# Concepts

> The model behind @dirtytalk/structural — the quadratic diffing problem, interned path IDs, the observed skeleton, the proxy recorder, and the React adapter.

Source: /dirtytalk/structural/concepts/

This page explains the model behind `@dirtytalk/structural`: the diffing-cost problem it solves, how paths become interned IDs, what the _skeleton_ is, how the proxy recorder works, and how the React adapter ties it all together. Read it after [Getting Started](/dirtytalk/structural/getting-started) when you want to understand _why_ the package is shaped the way it is.

## The problem: per-consumer diffing is quadratic

State containers and UI renderers both ask the same question after a mutation: _what changed, who cares, and when do we tell them?_ For structural state — objects and arrays whose consumers track named paths — the honest answer is a set of changed paths matched against each consumer's set of observed paths.

The naive way to compute this is **per-consumer diffing**: for each of `N` consumers, walk the previous and next state comparing the paths that consumer observes. When many consumers share one container and observe overlapping shapes, this is roughly `N` consumers × `N` redundant tree walks, doing the same equality checks over and over. The cost grows quadratically with consumer count exactly when you least want it to — a busy container with many subscribers.

The fix this package implements is **one walk plus N intersections**:

1. Maintain a single _skeleton_ — the union of every live consumer's observed paths.
2. On a mutation, do **one** diff walk bounded to that skeleton, producing a set of changed path IDs (the _dirty_ set).
3. Decide who to wake with `N` cheap **set intersections**: a consumer wakes iff its observed path set intersects the dirty set.

The expensive part (the tree walk) happens once per mutation instead of once per consumer. The per-consumer part collapses to set-membership checks. The saving is proportional to `N` when consumers share a container. This is the lineage of BlaC's per-consumer path tracking, extracted and built on top of [`@dirtytalk/engine`](/dirtytalk/engine/concepts)'s `DirtyChannel`, `Space`, and `Scheduler`.

## Paths as interned IDs: `PathInterner`

Comparing and unioning dotted path strings (`"user.name"`) over and over would be wasteful. So every path is **interned** into a small integer `PathId` once, and all set operations work on those integers.

`PathInterner` is a bidirectional string ↔ ID table. `intern(path)` returns a stable ID, assigning the next sequential integer (starting from `0`) the first time it sees a string and returning the same ID forever after. `lookup(id)` is the reverse. Same string, same ID — always.

```ts
import { PathInterner } from '@dirtytalk/structural';

const interner = new PathInterner();
interner.intern('user.name'); // 0
interner.intern('user.email'); // 1
interner.intern('user.name'); // 0 again — idempotent
interner.lookup(0); // 'user.name'
interner.size; // 2
```

### One interner per container class

IDs are only comparable within a single interner's namespace — `0` means `"user.name"` in one interner and could mean anything in another. So `StructuralContainer` keeps **one interner per subclass**, keyed by constructor in a `WeakMap` (`StructuralContainer.getInternerFor`). Every instance of the same subclass shares it, so their path IDs line up and can be unioned and intersected freely. Distinct subclasses get distinct interners even if their state shapes are identical — IDs never bleed across classes. The `WeakMap` lets a constructor (and its interner) be garbage-collected once all instances are gone.

## Path sets and the `ALL_PATHS` sentinel

A `PathSet` is the unit of "interest" and "dirtiness." It is either a concrete `Set<PathId>` or the special `ALL_PATHS` sentinel.

`ALL_PATHS` is a registered symbol (`Symbol.for('@dirtytalk/structural/ALL_PATHS')`), so its identity is stable even across module realms that share the symbol registry. It means "every possible path." Its key property is intersection behaviour: an `ALL_PATHS` interest intersects any non-empty dirty set, and any non-empty interest intersects an `ALL_PATHS` dirty set. (An _empty_ interest never wakes, even against `ALL_PATHS` — empty means "I care about nothing.")

`ALL_PATHS` shows up in two places:

- **Source-side signalling.** When the container can't or won't compute a precise dirty set, it marks `ALL_PATHS` to wake everyone (see the single-consumer skip below).
- **Opt-in blanket interest.** A devtools panel or plugin can `subscribe(() => ALL_PATHS, …)` to hear about every change.

The set algebra lives in a handful of pure functions:

| Function              | Meaning                                                                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `emptyPathSet()`      | A fresh empty `Set<PathId>` (never `ALL_PATHS`).                                                                |
| `pathSetUnion(a, b)`  | Pure union; `ALL_PATHS` if either side is `ALL_PATHS`. Does not mutate inputs.                                  |
| `pathSetEquals(a, b)` | Value equality; both `ALL_PATHS`, or two Sets with the same members.                                            |
| `PathSetSpace`        | The `Space<PathSet>` the engine's `DirtyChannel` consumes (provides `empty`, `isEmpty`, `union`, `intersects`). |

These satisfy the engine's [`Space` contract](/dirtytalk/engine/concepts): `union(empty(), r)` equals `r` by value, `intersects(empty(), _)` is `false`, and every operation is pure.

### The single-consumer skip

The skeleton-based diff only pays off when there are multiple consumers to share the walk across. With **0 or 1** registered consumers, `emit` and `update` skip the diff entirely and just mark `ALL_PATHS` — the sole consumer (if any) wakes regardless of whether the change touched a path it observes. Cheaper than building a dirty set when there is nobody to discriminate between. Fine-grained isolation begins at two or more registered consumers.

Note that `patch` does **not** take this shortcut: it always value-diffs the patch shape (more on this below), independent of consumer count.

## The observed skeleton

The **skeleton** is the union of all currently registered consumers' path sets. It is the bound on the diff walk: `emit`/`update` only check whether the paths _somebody_ observes have changed, ignoring fields no live consumer reads.

It is maintained through the consumer registry:

- `registerConsumerPaths(id, paths)` records (or replaces) one consumer's observed set, then recomputes the skeleton as the union of all registered sets. There is a fast-path skip: if the new set is `pathSetEquals` to the previously stored one, nothing is recomputed.
- `unregisterConsumer(id)` drops a consumer and recomputes the skeleton if it was present.

Recompute is `O(consumers × paths)` — a full re-union on every registry change (incremental update is a future optimisation). The skeleton is consulted **only** by `emit`/`update`. `patch` ignores it (it value-diffs the patch directly), and raw `subscribe` callers never touch the registry — so a path observed only by a raw subscriber is invisible to `emit`'s skeleton diff, though `patch` will still wake it via value-filtered marking.

## `trackRender`: the Proxy recorder

How does a consumer declare which paths it observes without writing a selector? It just _reads_ the state, and a recording proxy notes what was read.

`trackRender(state, interner)` wraps `state` in a `Proxy` and returns `{ value, paths }`. `value` is the proxy; `paths` is a **live** `Set<PathId>` that grows as you read properties off `value`. It is empty until you read, and it is mutated _after_ `trackRender` returns. `paths` is always a concrete `Set` — never `ALL_PATHS`.

The recording rules are deliberate, and they are what make sibling isolation work:

- **Leaf-only (maximal) recording.** Reading `a.b.c` records only `a.b.c`. As each deeper read descends, the immediate parent path is dropped from the set. So a consumer reading `user.name` records exactly `user.name` — not `user`. When an immutable update replaces the whole `user` object because a _sibling_ (`user.address`) changed, the consumer of `user.name` does **not** wake: its recorded leaf still resolves to the same value. A consumer that reads the whole `user` object (no deeper key) keeps `user` as its leaf and wakes on any change to it.
- **Own, non-symbol reads only.** Symbol keys (`Symbol.iterator`, `Symbol.toStringTag`) and inherited/prototype properties never record. Re-reading a path does not re-record (idempotent via the Set). Conditional reads record only the branch actually taken.
- **Primitives pass through.** Reading a field whose value is a primitive, `null`, or `undefined` returns it as-is — but reading the key still records that field's path.
- **Nested plain objects and arrays return child proxies** recording into the same `paths` set, cached per target in a per-call `WeakMap` so `value.user === value.user` within one render. The cache dies with the call frame, so each `trackRender` call records independently.
- **Iteration coarsens.** `for..of`, `.map`, `.find`, `.reduce` and friends on an array record the **entry path** (e.g. `items`) but **not** per-index paths (`items.0`) or `items.length`. Array prototype methods are bound to the raw target so their internal index reads bypass the proxy, and callbacks receive raw (un-proxied) values. Direct index access _does_ record the leaf — `value.items[2].name` records `items.2.name`.
- **Leaf collection types are not recursed.** `Map`, `Set`, `Date`, and class instances are returned raw (wrapping them would rebind receiver-checked built-ins like `Map.prototype.get` and throw). Reading the field records the field's path only; a reference change to the whole value still wakes the consumer. The wrappable predicate is: arrays, or objects whose prototype is `Object.prototype` or `null`.
- **Own methods on non-array objects are bound to the proxy** so their internal `this.x` reads keep recording when invoked. Reading a method without calling it does not record (methods live on the prototype).

This is why the React hook needs no selector: the JSX _is_ the dependency declaration.

## The diff helpers and when each applies

Two questions, two helpers. "Did the paths somebody observes change?" is answered by walking the skeleton. "Which paths did this patch actually change?" is answered by walking the patch. `getAt` is the shared path-read primitive.

| Helper                                                          | Walks           | Used by                             | Question it answers                                           |
| --------------------------------------------------------------- | --------------- | ----------------------------------- | ------------------------------------------------------------- |
| `getAt(state, path)`                                            | one dotted path | the others, internally              | What value lives at this path? (never throws)                 |
| `diffAlongSkeleton(prev, next, skeleton, interner, equalsAt?)`  | the skeleton    | `emit` / `update`                   | Which observed paths changed value between `prev` and `next`? |
| `pathsFromPatch(patch, interner)`                               | the patch shape | exported, not used by the container | Which paths does this patch _touch_ (regardless of value)?    |
| `changedPathsFromPatch(prev, next, patch, interner, equalsAt?)` | the patch shape | `patch`                             | Which patched paths actually changed value?                   |

- **`diffAlongSkeleton`** reads each skeleton path in both states and includes it iff the values differ under `equalsAt` (default `Object.is`). It short-circuits: `ALL_PATHS` skeleton returns `ALL_PATHS`, empty skeleton returns empty. It is pure. Because the default is reference equality, an intermediate path like `user` _is_ flagged if the outer object got a new reference even when its leaves are unchanged — which is correct for a consumer that observes `user` as a leaf.
- **`pathsFromPatch`** flattens a patch tree to interned paths with **tree-pulses-up** semantics: each plain-object branch contributes its own path _and_ recurses, so `{ user: { email: 'x' } }` yields both `"user"` and `"user.email"`. Arrays, primitives, class instances, `Date`, `Map`, `Set` are leaves (recorded then stopped). It does not compare values — it is shape-based. The container does not use it for marking, but it is exported for callers who want shape-based marking.
- **`changedPathsFromPatch`** is `pathsFromPatch` with a value filter: it pulses up the same branches but compares `prev[key]` vs `next[key]` at each step and skips paths whose value did not change. Crucially it **prunes recursion** into unchanged branches — relying on the invariant that an unchanged subtree keeps its reference. This makes patch marking precise and skeleton-independent, so a raw channel subscriber wakes correctly while an over-spread patch (spreading a whole parent when one field changed) does not over-wake siblings.

For example, an over-spread patch `{ user: { name: 'Grace', email: 'a@x.io' } }` where only `name` actually changed marks `['user', 'user.name']` — not `user.email`.

## `emit` vs `patch` vs `update`, and the immutable-replacement requirement

All three mutators install a **new** immutable value and then mark the channel. None of them mutate state in place, and there is no primitive that does.

- **`emit(next)`** replaces the whole state with `next`. It short-circuits to a no-op if `Object.is(state, next)`. Otherwise it sets the new state, then computes the dirty set: `ALL_PATHS` under the single-consumer skip, else `diffAlongSkeleton` against the observed skeleton. Then it marks the channel.
- **`patch(partial)`** deep-merges a `DeepPartial<S>` into the current state. An empty patch is a no-op. The merge walks plain-object branches only; arrays, class instances, `Date`, `Map`, `Set`, and primitives replace their slot atomically. If the merge produces no actual change it returns the original reference and the whole call is a no-op. State is applied **before** marking (so consumers reading `state` inside the dirty callback see the new value), and marking uses `changedPathsFromPatch` — value-filtered and skeleton-independent.
- **`update(fn)`** is sugar for `this.emit(fn(this.state))`. Same semantics as `emit`, including the single-consumer skip and the reference-equal no-op.

:::caution[In-place mutation is invisible]
Because change detection relies on reference comparison (`Object.is`) and on unchanged subtrees keeping their references, **mutating `state` in place is silently invisible** to tracking. `container.state.items.push(x)` will not wake anyone. Always replace immutably: `patch({ ... })`, or `update(s => ({ ...s, items: [...s.items, x] }))`.
:::

## The React adapter

`useStructural(container)` connects a component to a container with per-render path tracking. The mechanics:

- It derives a stable consumer id from React's `useId()`, and forces re-renders with `useReducer((x) => x + 1, 0)` — there is no virtual DOM here; React's own reconciliation handles the update.
- On each render it calls `trackRender(container.state, container.interner)` and stashes the live `paths` set in a ref. It deliberately does **not** call `registerConsumerPaths` in the render body: the proxy has not been read yet, so `paths` is empty — registering it then would freeze an empty skeleton and silently drop wakeups.
- A `useLayoutEffect` with no deps runs after every render and registers the now-populated path set. Conditional reads therefore reshape the skeleton automatically, render to render — no selector to keep in sync.
- A `useEffect` keyed on `[container, consumerId]` re-registers the paths (covering StrictMode cleanup cycles where the render body did not re-run) and subscribes `() => pathRef.current` to the channel, forcing a re-render when the interest intersects the dirty set. Cleanup unsubscribes and unregisters the consumer.

The result is StrictMode-safe: double-invocation leaves a clean registry, unmount returns `consumerCount` to zero, and two components on one container get distinct consumer ids. Raw `subscribe` plugins coexist with hook consumers. The `options` argument is reserved (`select?: never`) and currently inert — path recording replaces selectors, so there is no selector API to configure.

## Lineage to BlaC

This package is the per-consumer path tracking from BlaC, extracted and rebuilt as a standalone, engine-backed container. If you know BlaC's [tracked state](/core/tracked) and [`useBloc` dependency tracking](/react/dependency-tracking), the model maps cleanly: read the fields you need during render, re-render only when those fields change. For the BlaC mental model in full, see [BlaC: Mental Model](/guide/mental-model). `@dirtytalk/structural` is the focused, framework-light distillation of that idea on top of `@dirtytalk/engine`.

## What it is not

- **Not a computed/derived-value system.** There is no dependency graph and no auto-tracked computeds. Build derived values in a layer above the container.
- **Not an effect system.** The unsubscribe function returned by `subscribe` is the only cleanup primitive.
- **Not a mutable store.** No in-place mutation primitive exists; all updates are immutable replacements via `emit`/`patch`/`update`.
- **Not a virtual DOM.** The React adapter forces a re-render via `useReducer`; reconciliation is React's job.
- **Not glob/pattern equality.** The `equality` option keys are exact dotted-path strings only — pattern matching is a follow-up.
- **Not a scheduler provider.** Schedulers live in `@dirtytalk/engine`; this package forces none and injects whatever you give it.

## See also

- [Structural: Getting Started](/dirtytalk/structural/getting-started) — install and build your first container.
- [Structural: API Reference](/dirtytalk/structural/api-reference) — exhaustive signatures for every export.
- [Engine: Concepts](/dirtytalk/engine/concepts) — the `Space` algebra, schedulers, and `DirtyChannel` this package builds on.
- [React: Dependency Tracking](/react/dependency-tracking) — the BlaC ancestor of this model.

---

# Getting Started

> Build a small state container with no framework, watch it notify subscribers on a microtask flush, then wire it into React for path-level re-render isolation.

Source: /dirtytalk/structural/getting-started/

This page teaches `@dirtytalk/structural` by doing. You will build a small state container with no framework, watch it notify subscribers on a microtask flush, and then wire the same container into React so that a component re-renders only when the exact fields it read actually change. It is written for anyone who wants fine-grained, path-level change tracking for object state.

## What this package gives you

`@dirtytalk/structural` is a state container for **structural data** — plain objects and arrays whose consumers care about specific named paths (`user.name`, `items`, `count`). When you mutate the state, it works out which paths actually changed and wakes only the consumers that read those paths. A component that read `state.count` will not re-render because `state.label` changed.

It is built on [`@dirtytalk/engine`](/dirtytalk/engine/getting-started), which provides the dirty-tracking channel and the schedulers that decide _when_ notifications fire. The engine is a runtime dependency — you will import schedulers from it directly.

## Install

`@dirtytalk/structural` depends on `@dirtytalk/engine`. Install both. React is an optional peer dependency, only needed if you use the `/react` subpath.

<Tabs syncKey="pkg">
<TabItem label="pnpm">

```bash
pnpm add @dirtytalk/structural @dirtytalk/engine
```

</TabItem>
<TabItem label="npm">

```bash
npm install @dirtytalk/structural @dirtytalk/engine
```

</TabItem>
<TabItem label="yarn">

```bash
yarn add @dirtytalk/structural @dirtytalk/engine
```

</TabItem>
</Tabs>

:::note[Engine is required]
`@dirtytalk/structural` lists `@dirtytalk/engine` as a dependency, so a package manager will pull it in automatically. You still import schedulers (`SyncScheduler`, `MicrotaskScheduler`, …) from `@dirtytalk/engine` directly — they are **not** re-exported from `@dirtytalk/structural`.
:::

## A core walkthrough (no React)

Let's build a container by subclassing `StructuralContainer<S>`, drive it with `patch`/`emit`/`update`, subscribe to it through its channel, and observe a flush.

### 1. Subclass `StructuralContainer<S>`

`StructuralContainer<S>` is abstract. You subclass it, type its state shape, and add your own methods that call the protected-by-convention mutators (`patch`, `emit`, `update`).

```ts
import { StructuralContainer } from '@dirtytalk/structural';
import { SyncScheduler } from '@dirtytalk/engine';

interface CounterState {
  count: number;
  label: string;
}

class Counter extends StructuralContainer<CounterState> {
  increment() {
    // patch merges a DeepPartial<S> into the current state.
    this.patch({ count: this.state.count + 1 });
  }

  rename(label: string) {
    this.patch({ label });
  }
}

// The constructor takes (initial, options). For deterministic, synchronous
// behaviour (tests, SSR, this walkthrough) pass a SyncScheduler from the engine.
const counter = new Counter(
  { count: 0, label: 'clicks' },
  {
    scheduler: new SyncScheduler(),
  },
);
```

:::caution[Schedulers come from the engine]
You import `SyncScheduler` from `@dirtytalk/engine`, and you pass it as `options.scheduler` — an object, not a bare positional argument. The default scheduler (if you pass none) is a fresh `MicrotaskScheduler`, which defers and coalesces notifications onto a microtask.
:::

### 2. Subscribe through the channel using `ALL_PATHS`

Every container exposes a `subscribe(interest, cb)` method that passes straight through to the underlying [`DirtyChannel`](/dirtytalk/engine/concepts). `interest` is a thunk returning the set of paths this subscriber cares about. For a devtools-style subscriber that wants to hear about _every_ change, return the `ALL_PATHS` sentinel.

```ts
import { ALL_PATHS } from '@dirtytalk/structural';

const unsubscribe = counter.subscribe(
  () => ALL_PATHS, // "wake me on any change"
  (dirty) => {
    console.log('state is now', counter.state, 'dirty:', dirty);
  },
);
```

The callback receives `dirty`, the set of path IDs that changed (or `ALL_PATHS`). Because we used a `SyncScheduler`, the callback fires synchronously the moment a mutation marks the channel.

```ts
counter.increment(); // logs: state is now { count: 1, label: 'clicks' } ...
counter.rename('taps'); // logs: state is now { count: 1, label: 'taps' } ...

unsubscribe(); // stop listening
```

:::note[Single-consumer shortcut]
With at most one registered consumer, `emit`/`update` skip diffing and mark `ALL_PATHS` — the lone consumer wakes on any change. Raw `subscribe` callers like the one above do not count toward that registry (they never call `registerConsumerPaths`), so a `subscribe` returning `ALL_PATHS` always hears every change regardless. Fine-grained, path-level isolation kicks in once there are two or more _registered_ consumers, which is exactly what the React hook does for you.
:::

### 3. Observe a microtask flush

Switch to the default scheduler to see coalescing. Drop the `scheduler` option (or pass `new MicrotaskScheduler()`), and multiple mutations in one synchronous tick collapse into a single deferred notification.

```ts
import { StructuralContainer, ALL_PATHS } from '@dirtytalk/structural';

const c = new Counter({ count: 0, label: 'clicks' }); // default: MicrotaskScheduler

let flushes = 0;
c.subscribe(
  () => ALL_PATHS,
  () => {
    flushes += 1;
  },
);

c.increment();
c.increment();
c.increment();

console.log(flushes); // 0 — nothing has flushed yet, still in this tick

await Promise.resolve(); // let the microtask run

console.log(flushes); // 1 — three marks coalesced into one flush
```

This is the same flush/coalescing model the engine documents in [Engine: Concepts](/dirtytalk/engine/concepts): marks accumulate via set union, a flush is requested from the scheduler, and the subscriber sees the unioned dirty region exactly once.

## A React walkthrough

The React adapter lives at the `@dirtytalk/structural/react` subpath and exposes a single hook, `useStructural`. It returns `[state, container]`, where `state` is a recording proxy: reading a field off it during render registers _that path_ as this component's interest, so only changes to paths it read trigger a re-render.

```tsx
import { useStructural } from '@dirtytalk/structural/react';

function CountButton({ counter }: { counter: Counter }) {
  const [state, container] = useStructural(counter);
  // Reading state.count registers the path "count" for this component.
  return (
    <button onClick={() => container.increment()}>
      clicked {state.count} times
    </button>
  );
}

function LabelTag({ counter }: { counter: Counter }) {
  const [state] = useStructural(counter);
  // This component reads only state.label, so it registers "label".
  return <span>{state.label}</span>;
}
```

Now the isolation pays off. With both components mounted against the same `counter` instance:

- `counter.increment()` changes `count`. Only `CountButton` re-renders. `LabelTag` read `label` and stays asleep.
- `counter.rename('taps')` changes `label`. Only `LabelTag` re-renders. `CountButton` stays asleep.

No selector function, no manual dependency array. The hook tracks exactly the paths your JSX touched this render, and adapts automatically when conditional reads change which fields you access. Pass the container instance in however you like — props, context, or a module singleton.

:::note[How the hook tracks]
`useStructural` wraps `container.state` in a recording proxy each render and stores the set of paths read into a ref. After the render commits, a layout effect registers that path set with the container, keeping the container's skeleton in sync with what the component actually read. It then subscribes to the channel and forces a re-render (via `useReducer`) when an overlapping path goes dirty. It is StrictMode-safe and uses React's `useId()` for a stable per-component consumer id. See [Concepts](/dirtytalk/structural/concepts) for the full mechanism.
:::

:::caution[Immutable updates only]
There is no in-place mutation primitive. Mutating `state` directly (`counter.state.count++`) bypasses change tracking entirely and nobody will wake. Always go through `emit`, `patch`, or `update`, all of which install a new immutable value.
:::

## When to use this package, and how it relates to BlaC

Reach for `@dirtytalk/structural` when:

- You have object/array state with **many independent consumers** that each read different slices of it, and you want each consumer to re-render only when its slice changes — without writing selectors.
- You want path-level change tracking that is **framework-agnostic at the core** (the container and diff helpers have no React dependency) with an optional thin React adapter.
- You are building on `@dirtytalk/engine` and want a higher-level, path-aware container rather than wiring a `DirtyChannel` by hand.

It is the spiritual successor to BlaC's per-consumer path tracking. If you have used BlaC's [tracked state](/core/tracked) and [dependency tracking in `useBloc`](/react/dependency-tracking), the model here will feel familiar: read what you need, re-render when it changes. `@dirtytalk/structural` distills that idea into a standalone, engine-backed package. If you want the full BlaC programming model (cubits, cross-bloc dependencies, the wider ecosystem), see the [BlaC introduction](/guide/introduction). If you want fine-grained structural tracking as a focused building block, this package is it.

## See also

- [Structural: Concepts](/dirtytalk/structural/concepts) — the why and the model: path sets, the skeleton, the tracker.
- [Structural: API Reference](/dirtytalk/structural/api-reference) — every export, signature, and option.
- [Engine: Getting Started](/dirtytalk/engine/getting-started) — the `DirtyChannel` and schedulers this package is built on.
- [Engine: Concepts](/dirtytalk/engine/concepts) — Space algebra, scheduling, and the flush model.

---

# BlaC

> Type-safe state management for React with automatic re-render optimization.

Source: /

:::caution[Beta / pre-release]
BlaC v2 is in pre-release (beta). While in beta, **breaking API changes may ship in patch releases** without a major version bump — pin exact versions and check the changelog before upgrading. Strict semver resumes once v2 is officially out of beta.
:::

<SectionBreak label="§ the whole loop" dotSize="7px" dotOpacity="0.2" />

<RisoHeading as="h2" intensity="subtle">
  Here. This is all of it.
</RisoHeading>

A class holds your state and the methods that change it. One hook connects it
to React. That's the entire mental model — no store setup, no provider tree,
no action types yelling in `SCREAMING_SNAKE_CASE`.

```tsx twoslash
import React from 'react';
import { Cubit } from '@blac/core';
import { useBloc } from '@blac/react';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
  increment = () => this.emit({ count: this.state.count + 1 });
}

function Counter() {
  const [state, counter] = useBloc(CounterCubit);
  return <button onClick={counter.increment}>Count: {state.count}</button>;
}
```

And that's not a screenshot — here's the real thing running, the actual
`@blac/react` hook driving an actual `Cubit`. The badge counts genuine renders:

<CounterDemo client:visible />

<SectionBreak label="§ why blac" dotSize="7px" dotOpacity="0.2" />

<RisoHeading as="h2" intensity="subtle">
  Chaos resolving into calm
</RisoHeading>

State changes are messy by nature. BlaC lets you write the messy part plainly
and read it back as something calm, typed, and predictable.

<CardGrid>
  <Card title="Touch it, you're subscribed" icon="magnifier">
    Read `state.user.name` and you're subscribed to exactly that — nothing
    more. No selectors to write, no memoization homework, no
    "why is this re-rendering" archaeology. BlaC tracks what each component
    actually reads. [How tracking works](/react/dependency-tracking/)
  </Card>
  <Card title="Surgical re-renders" icon="rocket">
    Every `useBloc` consumer gets its own dependency tracker. When one slice of
    state changes, components that never read it stay asleep. Performance you
    don't have to earn — it's just how the hook works.
    [See the numbers](/react/performance/)
  </Card>
  <Card title="Your logic lives in classes" icon="pencil">
    Methods are your actions. `this.state` is your source of truth.
    `emit`, `update`, and `patch` change it. It reads like the code you'd
    write anyway — because it is. [Core concepts](/guide/concepts/)
  </Card>
  <Card title="Type-safe to the edges" icon="approve-check">
    Inference flows from your state shape through every consumer. No casts, no
    `any`, no generics gymnastics. If it compiles, the wiring is right.
    [TypeScript guide](/guide/typescript/)
  </Card>
  <Card title="Async without the acrobatics" icon="setting">
    Kick off a fetch in a method, `emit` when it lands. Debounce, optimistic
    updates, WebSockets — all plain methods on a plain class.
    [Async guide](/guide/async/) · [Recipes](/guide/patterns/)
  </Card>
  <Card title="Escapes React when you do" icon="puzzle">
    The core is framework-agnostic. `watch()` a bloc from anywhere — a router,
    a game loop, a test. React is a binding, not a requirement.
    [Outside React](/integrations/outside-react/)
  </Card>
</CardGrid>

<SectionBreak label="§ batteries" dotSize="7px" dotOpacity="0.2" />

<RisoHeading as="h2" intensity="subtle">
  Batteries included, opt-in
</RisoHeading>

The core stays tiny; the extras snap on when you want them.

- **DevTools** — inspect every instance, every state change, live.
  [Plug it in →](/plugins/devtools/)
- **Persistence** — state that survives a refresh, one decorator away.
  [Persist things →](/plugins/persistence/)
- **Logging** — see every emit as it happens, filter the noise.
  [Log it →](/plugins/logging/)
- **Testing utilities** — drive blocs directly, assert on state, no DOM
  required. [Test it →](/testing/overview/)
- **SSR & per-request isolation** — Next.js, Remix, React Native: covered.
  [Integrations →](/integrations/ssr/)

<SectionBreak label="§ where to next" dotSize="7px" dotOpacity="0.2" />

<RisoHeading as="h2" intensity="subtle">
  Pick your door
</RisoHeading>

- **New here?** The [Quick Start](/guide/getting-started/) gets you from
  `pnpm add` to a working component in about five minutes.
- **Want to build something real?** The
  [tutorial](/guide/tutorial/) takes a todo app all the way to time-travel.
- **Coming from [Zustand](/guide/coming-from-zustand/),
  [Redux](/guide/coming-from-redux/), or
  [Flutter Bloc](/guide/coming-from-flutter-bloc/)?** There's a translation
  guide with your name on it.
- **Just want the API?** Reference docs for
  [`@blac/core`](/core/cubit/) and [`@blac/react`](/react/getting-started/),
  plus the [dirtytalk](/dirtytalk/) sub-libraries for spatial, structural, and
  engine work.

---

# Playground

> An open-ended, editable BlaC sandbox that runs in your browser — no install needed. Start from a typed Cubit and a render counter, then make it your own.

Source: /playground/

An interactive, editable BlaC sandbox running entirely in your browser. No
install needed — just edit the code and watch it update.

The starter demonstrates a **Cubit** with typed state, a **`useBloc`** hook
consumer, and a **render counter** wired directly in the render body (not
`useEffect`) so every real re-render is counted accurately.

:::tip[What to try]
- Add a new field to `CounterState` in `counter.ts` and read it in `App.tsx`.
- Add a second independent component that consumes the same Cubit — bump the
  counter and notice the render counter of the other component does **not**
  tick (per-consumer auto-tracking).
- Add an `events` array to the Cubit and record each user intent before
  reducing it into state.
:::

<BlacSandpack
  client:only="react"
  files={playgroundStarterFiles}
  activeFile="/App.tsx"
  editorHeight={580}
  defaultOpen={true}
  showConsole={true}
/>

## What you're editing

| File                | Role                                                                                                                               |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `App.tsx`           | Root component; renders the `Counter` component and passes nothing — the Cubit is resolved automatically from the global registry. |
| `counter.ts`        | `CounterCubit` — start here. Add state fields, tweak actions, or model an explicit event log in state.                             |
| `RenderCounter.tsx` | Utility component that counts renders in the render body. Carry this into any component to measure re-render isolation.            |
| `styles.css`        | Plain CSS — no framework. Edit freely.                                                                                             |

## Starting ideas

**Extend the Cubit** — add a `history: number[]` field and record each value
after every increment.

**Per-consumer isolation** — split the counter display into two sibling
components: one reads `state.count`, the other reads `state.step`. Add render
counters to both, then change the step. Only the step reader should re-render.

**Async action** — add an `incrementAfterDelay` method that calls
`setTimeout` before invoking `this.update(...)`. Watch the UI stay responsive
while the delay runs.

**Event log** — add a `CounterEvent` union and an `events: CounterEvent[]`
field. Have each action append an event before applying the state change, so
you can inspect the history without introducing a separate dispatch API.

---

# Showcase

> Forkable interactive demos — counter, todo, form, and dashboard — all running the published @blac/core and @blac/react packages live in your browser.

Source: /showcase/

Each demo below runs entirely in your browser via
[Sandpack](https://sandpack.codesandbox.io/). Sandpack installs the **published**
`@blac/core` and `@blac/react` packages from its CDN, so you're running the real
API — not a mock or workspace build.

Every embed is **fully editable**. Hit **View code**, change a file, and watch
the preview hot-reload. Click **Open in CodeSandbox** (top-right of the editor)
to fork the sandbox and keep experimenting.

:::tip[First load]
The preview may take a few seconds on first load while Sandpack resolves the
dependency tree from CDN. Subsequent loads are cached.
:::

## Counter

The minimum viable BlaC app. One `CounterCubit` holds `{ count, lastAction }`.
The component calls cubit methods — no action objects, no reducers, no dispatch.

- **`Cubit`** — subclass with a typed initial state
- **`patch()`** — partial-merge update; `emit()` for a full replace
- **`useBloc()`** — returns `[state, cubit]` (no provider needed)

<BlacSandpack
  client:only="react"
  files={counterShowcaseFiles}
  activeFile="/App.tsx"
  editorHeight={480}
/>

## Todo list

Multiple components consume the same `TodoCubit` without any extra wiring —
no context, no prop-drilling. Derived getters (`filteredItems`, `activeCount`)
live on the cubit and recompute whenever state changes.

- Reactive **list state** — add, toggle, remove, filter
- **Derived getters** on the Cubit class
- Multiple unrelated components, all reading the same singleton

<BlacSandpack
  client:only="react"
  files={todoShowcaseFiles}
  activeFile="/App.tsx"
  editorHeight={540}
/>

## Registration form

`FormCubit` tracks every field's `value` and `touched` flag, plus computed
`errors`, `isValid`, and `progress`. Validation logic stays in the cubit — the
components are pure view.

- Per-field **touched state** — errors surface only after blur
- **Derived `errors` getter** returns only fields that fail
- **Progress bar** driven by a computed percentage, no local state

<BlacSandpack
  client:only="react"
  files={formShowcaseFiles}
  activeFile="/App.tsx"
  editorHeight={500}
/>

## Analytics dashboard

Two independent Cubits — `StatsCubit` (counters + live simulation) and
`ActivityCubit` (event log) — coexist without a provider. A `useEffect` in
`App` writes to the activity log whenever stats refresh, showing cross-cubit
coordination via React effects instead of `this.depend()`.

- **Two Cubits** used in the same tree, no shared provider
- **Live simulation** with `setInterval` managed inside the cubit
- Cross-cubit coordination via React effects

<BlacSandpack
  client:only="react"
  files={dashboardShowcaseFiles}
  activeFile="/App.tsx"
  editorHeight={560}
  showConsole={true}
/>

:::note[Messenger not included]
The messenger scenario was scoped out of this gallery. It requires several
blocs, a mock service layer, real-time typing indicators, and a multi-file
component tree that is too large to be self-contained as a Sandpack string
module. It remains available in the `apps/examples` workspace for local
exploration.
:::

## What to try

Once a demo loads, hit **View code** and try these edits to explore the API:

- **Counter** — add a `double` method to `CounterCubit` that calls
  `this.patch({ count: this.state.count * 2 })`.
- **Todo** — add a `prioritize(id)` method and a `priority` field to the
  `Todo` interface; sort `filteredItems` by priority.
- **Form** — add a fourth field (e.g. `username`) and a uniqueness rule to
  `errors`.
- **Dashboard** — wire `StatsCubit` to `ActivityCubit` using `this.depend()`
  inside `StatsCubit.tick()` so the log updates without a React effect.