# 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.

Full text by package: [BlaC](/llms-blac.txt), [BlaC React](/llms-blac-react.txt), [DirtyTalk](/llms-dirtytalk.txt). Everything in one file: [Complete docs](/llms-full.txt).

## Guide

- [Async](/guide/async/): Model the loading lifecycle as state, guard against overlapping requests, and understand why BlaC does not integrate with React Suspense.
- [Core Concepts](/guide/concepts/): A quick conceptual tour of state containers, the registry, instance modes, dependency tracking, and plugins.
- [Quick Start](/guide/getting-started/): Install BlaC and build your first Cubit-powered React component.
- [Passing Inputs to Blocs](/guide/inputs/): The three input lanes — args, deps, and events — and the identity model that makes shared bloc instances safe.
- [How BlaC Works Internally](/guide/internals/): 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.
- [What is BlaC?](/guide/introduction/): BlaC is a TypeScript state management library for React that separates business logic into class-based, auto-tracked state containers.
- [Mental Model](/guide/mental-model/): The deep reasoning behind BlaC — the reactivity model, the per-consumer tracker, ref-counted lifecycle, and the full mount-to-unmount lifecycle.
- [Troubleshooting & FAQ](/guide/troubleshooting/): A symptom-to-fix lookup table for the most common BlaC problems, with links into the reference pages that own each explanation.
- [Tutorial: build a Todo app, then make it time-travel](/guide/tutorial/): 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.
- [TypeScript](/guide/typescript/): How state shape, action signatures, args, deps, and select all flow from a single Cubit class declaration with minimal annotations.

## Core

- [Bloc communication](/core/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.
- [Configuration](/core/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.
- [Cubit](/core/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.
- [Instance management](/core/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.
- [Plugin Authoring](/core/plugins/): 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.
- [channel.subscribe](/core/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.
- [System events](/core/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.
- [Tracking](/core/tracked/): How BlaC records which leaves of state each consumer reads via a recording proxy, then wakes only the consumers whose leaves actually moved.
- [Types](/core/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.
- [watch](/core/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.

## React

- [Dependency tracking](/react/dependency-tracking/): How BlaC auto-tracking records the state properties a component reads and re-renders only when one of those properties changes.
- [React Getting Started](/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.
- [Performance](/react/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.
- [useBloc](/react/use-bloc/): The useBloc hook connects a React component to a state container, returning the current state, the bloc instance, and a ref.

## Plugins

- [DevTools](/plugins/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.
- [Logging Plugin](/plugins/logging/): Console output for state changes, instance lifecycle events, and monitoring alerts — a passive, scannable record of what your blocs are doing.
- [Plugins](/plugins/overview/): A plugin observes all bloc instances from the outside — the right tool for cross-cutting concerns like logging, inspection, and persistence.
- [Persistence Plugin](/plugins/persistence/): Automatically saves state to IndexedDB and restores it when instances are created, driven by the registry lifecycle and the hydration API.
- [Plugin Recipes](/plugins/recipes/): Copy-paste BlacPlugin recipes for common cross-cutting concerns — localStorage, debounced saves, cross-tab sync, Sentry breadcrumbs, and audit logging.

## Testing

- [Core Testing API](/testing/core/): The full @blac/core/testing helper reference — registry isolation, state seeding, stubs, overrides, and async helpers.
- [Testing](/testing/overview/): First-party testing utilities for fast, isolated tests of your cubits and the components that use them.
- [React Testing](/testing/react/): Render React components with controlled bloc state in an isolated registry — renderWithBloc and renderWithRegistry, built on the core testing primitives.

## Integrations

- [Using BlaC outside React](/integrations/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).
- [SSR & per-request isolation](/integrations/ssr/): BlaC's registry is a module-level singleton — on a server, give each request its own isolated registry to prevent cross-request state leakage.

## DirtyTalk

- [DirtyTalk](/dirtytalk/): The framework-agnostic packages under BlaC — after a mutation, what changed, who cares, and when do we tell them?