# 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.
- [Best Practices](/guide/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.
- [Coming from flutter_bloc](/guide/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.
- [Coming from Redux (Toolkit)](/guide/coming-from-redux/): 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.
- [Coming from Zustand](/guide/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.
- [Comparison](/guide/comparison/): An honest, side-by-side look at how BlaC compares to Zustand and Jotai, and when each is the better choice.
- [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.
- [Glossary](/guide/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.
- [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.
- [Patterns & Recipes](/guide/patterns/): Concrete, copy-pasteable patterns for async operations, named instances, cross-bloc communication, plugins, keep-alive, and getter-based computed values.
- [Debounce](/guide/recipes/debounce/): Collapse rapid user input into one deferred Cubit action by storing the debounce timer as a private field and clearing it on dispose.
- [Form Validation](/guide/recipes/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.
- [Optimistic Update](/guide/recipes/optimistic-update/): Apply a mutation to local Cubit state immediately, snapshot for rollback, fire the request, and restore the previous state on failure.
- [Pagination](/guide/recipes/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.
- [Reset to Initial State](/guide/recipes/reset-to-initial/): 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.
- [Undo / Redo](/guide/recipes/undo-redo/): Implement undo/redo in a Cubit with past and future state stacks, a history cap, and getters for canUndo/canRedo.
- [WebSocket Subscription](/guide/recipes/websocket/): 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.
- [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.
- [Versioning & Stability](/guide/versioning/): BlaC's semver policy, the React and browser support matrix, the stability tier of every package, and where to find the deprecation record.

## 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.
- [Preact](/react/preact/): The planned @blac/preact binding provides the same useBloc hook and API as @blac/react over the same @blac/core engine.
- [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

- [Next.js](/integrations/nextjs/): BlaC works in Next.js without extra packages — register server-side state isolation like any SSR app and keep blocs in Client Components.
- [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).
- [React Native](/integrations/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.
- [Remix](/integrations/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.
- [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/): A family of small, framework-agnostic libraries answering one question after every mutation — what changed, who cares, and when do we tell them?
- [API Reference](/dirtytalk/engine/api-reference/): The exhaustive public surface of @dirtytalk/engine, organized by export — Observable, Signal, Space, the four schedulers, and DirtyChannel.
- [Concepts](/dirtytalk/engine/concepts/): The model behind @dirtytalk/engine — why a region carries what changed, the Space algebra, the four schedulers, and the DirtyChannel flush lifecycle.
- [Getting Started](/dirtytalk/engine/getting-started/): From an empty file to a working DirtyChannel you can mark and observe, then swapping the scheduler to change timing.
- [API Reference](/dirtytalk/spatial/api-reference/): The complete public surface of @dirtytalk/spatial — Rect helpers, RectSpace, SceneNode, SceneRoot, the render pipeline, and PointerRouter.
- [Concepts](/dirtytalk/spatial/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.
- [Getting Started](/dirtytalk/spatial/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.
- [API Reference](/dirtytalk/structural/api-reference/): The complete export-by-export reference for @dirtytalk/structural — PathInterner, the PathSet algebra, trackRender, the diff helpers, StructuralContainer, and useStructural.
- [Concepts](/dirtytalk/structural/concepts/): The model behind @dirtytalk/structural — the quadratic diffing problem, interned path IDs, the observed skeleton, the proxy recorder, and the React adapter.
- [Getting Started](/dirtytalk/structural/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.

## Examples

- [Playground](/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.
- [Showcase](/showcase/): Forkable interactive demos — counter, todo, form, and dashboard — all running the published @blac/core and @blac/react packages live in your browser.