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 & identity, React binding, Lifecycle & hydration, and Plugins & observation, then alphabetized within each group.
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.
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.
bloc
Colloquial shorthand for any state-container instance (StateContainer or Cubit). There is no Bloc class in BlaC. See 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.
state
The single object a bloc holds (S extends object). Read via bloc.state; replaced or merged through emit/patch/update. See Cubit.
emit
emit(next) replaces the whole state with next. Skipped when next is reference-equal or passes the configured equality fn. See 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.
update
update(fn) is sugar for emit(fn(state)) — build the next state from the current one. See 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.
registry
The global singleton that creates, keys, shares, ref-counts, and disposes instances. Resolved via getRegistry(). See 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.
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.
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.
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.
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) > <BlocProvider> context args > 'default'. See 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.
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.
Deps
Non-serializable handles (refs, stable callbacks) injected per consumer via the Deps type param. Merged into bloc.deps; never key identity. See Inputs.
deps (runtime)
The merged, read-only view of all consumers’ dep slices, exposed as bloc.deps. Changes fire onDepsChanged. Note: a depsoption on useBloc is internal, not part of the public hook surface. See 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.
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.
static key
A class static key = (args) => string (settable directly or via blac({ key })) that derives the instance key from args. See 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.
excludeFromDevTools
Set via blac({ excludeFromDevTools: true }); the class is excluded from DevTools tracking. See Configuration.
blac()
The decorator/function that sets exactly one class-level option: keepAlive, excludeFromDevTools, equality, or key. See Configuration.
The React hook: useBloc(BlocClass, options?) returns [state, bloc, ref], acquiring on mount and releasing on unmount. See useBloc.
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.
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.
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.
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.
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.
ref (tuple element)
The third element of the useBloc tuple (ComponentRef); an advanced-use ref object rarely needed in app code. See useBloc.
A bloc lifecycle signal subscribed via onSystemEvent(event, handler): one of 'stateChanged', 'dispose', or 'hydrationChanged'. See 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.
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.
hydrationStatus
The current hydration phase ('idle' | 'hydrating' | 'hydrated' | 'error'), accessible as bloc.$blac.hydration.status. See System events.
waitForHydration
bloc.$blac.hydration.wait() returns a promise that resolves once hydration settles (idle/hydrated) or rejects on error. See 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.
onDepsChanged
protected onDepsChanged(next, prev) — an override hook that fires whenever the merged per-consumer deps view changes (and once on dispose with all keys cleared). See Inputs.
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.
instance() (helper)
instance(BlocClass, args) builds a BlocRef so watch targets the instance keyed by those args rather than the default one. See 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.
plugin
An observer (BlacPlugin) that hooks into container lifecycle (onCreated, onStateChange, onDestroyed, onHydrationChange, …) across all instances. See Plugins.
PluginManager
The singleton (via getPluginManager()) that installs, uninstalls, and tracks plugins, gating each by enabled and environment. See Plugins.
PluginContext
The per-dispatch context object passed to plugin hooks; exposes the focal container, metadata, state, hydration controls, and registry queries. See 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.
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.
These clusters cause the most confusion. Keep them straight:
select vs deps
select — a useBloc option that narrows re-renders: (state, bloc) => unknown[]. Opting in disables auto-tracking for that consumer. See Dependency tracking.
deps — the non-serializable handle lane (Deps type param + bloc.deps view). Nothing to do with re-rendering. See Inputs.
StateContainer vs Cubit vs bloc vs instance
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.
auto-tracking vs dependency tracking vs proxy tracking
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.
