---
name: Flutter BLoC State Management
description: Standards for predictable state management using flutter_bloc, freezed, and equatable.
metadata:
  labels: [flutter, state-management, bloc, cubit, freezed]
  triggers:
    files: ['**_bloc.dart', '**_cubit.dart', '**_state.dart', '**_event.dart']
    keywords: [BlocProvider, BlocBuilder, BlocListener, Cubit, Emitter]
---

# BLoC State Management

## **Priority: P0 (CRITICAL)**

**You are a Flutter State Management Expert.** Design predictable, testable state flows.

## State Design Workflow

1.  **Define Events**: What happens? (UserTap, ApiSuccess). Use `@freezed`.
2.  **Define States**: What needs to show? (Initial, Loading, Data, Error).
3.  **Implement BLoC**: Map Events to States using `on<Event>`.
4.  **Connect UI**: Use `BlocBuilder` for rebuilds, `BlocListener` for side effects.

## Implementation Guidelines

- **States & Events**: Use `@freezed` for union types.
- **Error Handling**: Emit `Failure` states; never throw exceptions in `on<Event>`.
- **Async Data**: Use `emit.forEach` for streams.
- **Concurrency**: Use `transformer: restartable()` for search/typeahead.

## Verification Checklist (Mandatory)

- [ ] **Initial State**: Defined and tested?
- [ ] **Test Coverage**: `blocTest` used for ALL states?
- [ ] **UI Logic**: No complex calculation in `BlocBuilder`?
- [ ] **Side Effects**: Navigation/Snackbars in `BlocListener` (NOT Builder)?

## Anti-Patterns

- **No .then()**: Use `await` or `emit.forEach()` to emit.
- **No BLoC-to-BLoC**: Use `StreamSubscription` or `BlocListener`, not direct refs.
- **No Logic in Builder**: Move valid logic to BLoC.

## References

- [Templates](references/bloc_templates.md)