DEV Community: Randal L. Schwartz

Share State Across Dart Isolates Without Losing Your Mind: Enter shared_map

Randal L. Schwartz — Sun, 20 Sep 2026 20:43:19 +0000

This is Part 3 of the Dart and Flutter series—practical guides, architectural deep dives, and hard-earned engineering lessons from the field. Each article is completely standalone.

Dart’s concurrency model is built on Isolates. Unlike threads in Java, C++, or Go, Dart isolates share no memory. Each isolate has its own private heap and its own single-threaded event loop.

This "share-nothing" model is a brilliant design decision. It completely eliminates data races, deadlocks, mutex contention, and tricky thread-synchronization bugs.

Until, of course, you actually need to share data across isolates.

Imagine this common production scenario:

You’re building a Flutter app that crunches heavy data in the background—perhaps resizing multiple images, decoding massive JSON payloads, computing cryptographic hashes, or running complex ML calculations. To keep your UI silky smooth at 120 FPS, you offload the work to background isolates using Isolate.run.

Now suppose all these concurrent background workers need access to a shared, in-memory cache (like parsed metadata, authentication tokens, or shared computation results) to avoid duplicate work.

How do you do that in Dart?

Traditionally, you only had two bad choices:

Serialize and copy the whole data structure back and forth across isolate boundaries every time. For large maps or high-frequency operations, this burns CPU and produces massive GC pressure.
Hand-roll a message-passing server using ReceivePort and SendPort. You have to invent custom request/response DTOs, generate unique request correlation IDs, wire up response completers, and write 150 lines of brittle plumbing just to perform a simple key-value lookup.

There is a third, vastly superior option that almost nobody talks about: package:shared_map.

What is `shared_map`?

Created by veteran Dart engineer Graciliano M. Passos, shared_map provides a versatile, synchronized Map data structure designed specifically to be shared across Dart isolates and asynchronous workflows.

Here is what makes it an architectural gem:

Zero Dependencies: It is pure, clean Dart with zero third-party dependencies.
160 / 160 Pub Points: Flawless quality score on pub.dev and fully Dart 3 compatible.
Universal Platform Support: Runs anywhere Dart runs—iOS, Android, macOS, Windows, Linux, Web, and backend CLI/servers.
Familiar Map Semantics: You interact with it using standard async key-value methods like get(), put(), putIfAbsent(), and update().

Instead of you manually orchestrating ports, shared_map manages the cross-isolate communication protocol transparently under the hood.

How It Works: The Reference Pattern

The core mental model of shared_map is dead simple:

Main Instance: You create a SharedMap on your primary isolate (like your Flutter UI thread or main server loop). This instance acts as the authoritative source of truth.
Shared Reference: You call .sharedReference() to generate a lightweight, serializable token.
Auxiliary Instance: You pass that lightweight token across an isolate boundary (e.g. into Isolate.run). Inside the isolate, you reconstruct a proxy instance using SharedMap.fromSharedReference(ref).

Any reads, writes, or mutations performed by the worker isolate are automatically dispatched back to the main instance and synchronized across all isolates!

See It In Action

Let’s write a complete, self-contained example. We'll simulate multiple concurrent worker isolates crunching data, reading from a shared cache, and populating cache entries on the fly:

import 'dart:isolate';
import 'package:shared_map/shared_map.dart';

void main() async {
  // 1. Create a SharedStore and a SharedMap on the main isolate
  final store = SharedStore('app_cache');
  final userCache = await store.getSharedMap<String, String>('users');

  // Seed an initial value
  await userCache!.put('user_101', 'Randal (Admin)');

  // 2. Extract the lightweight, serializable reference
  final cacheReference = userCache.sharedReference();

  print('--- Spawning Background Worker 1 ---');

  // 3. Pass the reference into a background isolate
  final worker1Result = await Isolate.run(() async {
    // Reconstitute the synchronized map proxy
    final workerMap = SharedMap<String, String>.fromSharedReference(cacheReference);

    // Read the value previously stored by the main isolate:
    final user = await workerMap.get('user_101');
    print('[Worker 1] Read from shared cache: $user');

    // Put a new value into the shared cache from this background worker:
    await workerMap.put('user_102', 'Wilhelm (Engineer)');
    return 'Worker 1 finished';
  });

  print(worker1Result);

  print('--- Spawning Background Worker 2 ---');

  // 4. Spawn a second isolate to prove cross-isolate synchronization
  final worker2Result = await Isolate.run(() async {
    final workerMap = SharedMap<String, String>.fromSharedReference(cacheReference);

    // Worker 2 can immediately read what Worker 1 just wrote!
    final user102 = await workerMap.get('user_102');
    print('[Worker 2] Read value written by Worker 1: $user102');

    // Use putIfAbsent atomically
    final user103 = await workerMap.putIfAbsent('user_103', 'Guest User');
    return '[Worker 2] Added: $user103';
  });

  print(worker2Result);

  // 5. Verify the main isolate reflects all updates
  print('--- Back on Main Isolate ---');
  print('Total entries in cache: ${await userCache.length()}');
  print('user_102 on main: ${await userCache.get('user_102')}');
  print('user_103 on main: ${await userCache.get('user_103')}');
}

The Console Output

--- Spawning Background Worker 1 ---
[Worker 1] Read from shared cache: Randal (Admin)
Worker 1 finished
--- Spawning Background Worker 2 ---
[Worker 2] Read value written by Worker 1: Wilhelm (Engineer)
[Worker 2] Added: Guest User
--- Back on Main Isolate ---
Total entries in cache: 3
user_102 on main: Wilhelm (Engineer)
user_103 on main: Guest User

Notice what just happened:

Two independent background isolates communicated and shared data back to the main thread.
Not a single SendPort, ReceivePort, Completer, or serialization boilerplate line was written.

Superpower: Local Read Caching with `SharedMapCached`

If your worker isolates perform thousands of rapid reads, you might not want every single get() call to perform a cross-isolate message dispatch.

shared_map includes a built-in subclass called SharedMapCached:

final cachedWorkerMap = SharedMapCached<String, String>.fromSharedReference(
  cacheReference,
  // Cache items locally in this isolate for high-throughput reads
  timeout: const Duration(seconds: 30),
);

When you query an existing key with SharedMapCached, it caches the value locally in the worker's isolate heap. If subsequent reads occur within the timeout window, they resolve instantly without cross-isolate latency.

Grouping Maps with `SharedStore`

In complex applications, you rarely have just one cache. You might have:

An image cache (SharedMap<String, Uint8List>)
A user profile cache (SharedMap<String, UserProfile>)
A rate limiter map (SharedMap<String, int>)

Instead of passing dozens of individual references around, you pass a single SharedStoreReference:

// Main thread:
final store = SharedStore('global_store');
await store.getSharedMap<String, String>('tokens');
await store.getSharedMap<String, int>('rate_limits');

final storeRef = store.sharedReference();

// Inside any background isolate:
await Isolate.run(() async {
  final workerStore = SharedStore.fromSharedReference(storeRef);

  // Dynamically resolve any map registered under this store:
  final tokens = await workerStore.getSharedMap<String, String>('tokens');
  final rateLimits = await workerStore.getSharedMap<String, int>('rate_limits');

  // ...
});

Senior Engineering Wisdom: When to Use (and Not Use) `shared_map`

As with any tool, understanding the architectural sweet spot is key.

✅ When to Reach for `shared_map`:

CPU-Intensive Worker Coordination: When running pools of background isolates (Isolate.run or persistent worker isolates) that need shared lookups.
In-Memory Deduping & Caching: Preventing concurrent workers from calculating or downloading the exact same asset twice.
Cross-Isolate Metrics & Counters: Collecting stats, telemetry, or rate-limit tokens across multiple threads.

⚠️ When NOT to Use `shared_map`:

Persistent On-Disk Storage: shared_map is an in-memory data structure. If your data must survive app restarts, use SQLite, Drift, or a persistent key-value store.
Single-Isolate Applications: If all your code runs on the root UI isolate, a standard Dart Map<K, V> or reactive Signal is all you need—there's no reason to pay the asynchronous abstraction cost.

Summary

Dart's isolate architecture keeps our code safe from concurrency bugs, but you shouldn't have to write hundreds of lines of port plumbing just to share an in-memory cache across worker tasks.

By bringing in shared_map:

You keep isolates isolated and UI threads responsive.
You eliminate manual SendPort and ReceivePort spaghetti code.
You get atomic, synchronized key-value storage with zero external dependencies.

Add shared_map: ^1.1.9 to your pubspec.yaml and stop reinventing isolate messaging from scratch.

What's your take?

How do you currently coordinate data between background isolates in your Flutter apps? Have you been writing custom ports, or relying on Isolate.run return values? Let me know in the comments below!

Randal L. Schwartz is a Google Developer Expert (GDE) for Dart & Flutter and veteran software architect.

📺 Watch deep dives and walkthroughs on YouTube: @RandalOnDartAndFlutter
💻 Connect on GitHub: @RandalSchwartz

Dart Enhanced Enums Are Secretly Factories: Unlocking Constructor Tearoffs

Randal L. Schwartz — Sun, 20 Sep 2026 20:03:10 +0000

This is Part 2 of the Dart and Flutter series—practical guides, architectural deep dives, and hard-earned engineering lessons from the field. Each article is completely standalone.

How many times have you written (or reviewed) a piece of code that looks like this?

NotificationWidget buildNotification(NotificationType type, NotificationData data) {
  switch (type) {
    case NotificationType.email:
      return EmailNotificationWidget(data);
    case NotificationType.sms:
      return SmsNotificationWidget(data);
    case NotificationType.push:
      return PushNotificationWidget(data);
  }
}

Or worse, a dedicated NotificationWidgetFactory class containing a 40-line switch statement or a mutable Map<NotificationType, Function> registry.

It feels routine. It’s what we were taught in classic OOP textbooks. But it introduces subtle friction:

The enum NotificationType knows nothing about the widgets it represents.
The factory switch ladder must be updated every time a new case is added.
The creation logic is split across multiple files and layers.

What if your enum wasn't just a list of identifiers, but was itself the polymorphic factory?

By marrying two features of modern Dart—Enhanced Enums and Constructor Tearoffs—you can delete the switch ladders and turn your enum values into self-instantiating factories in under 15 lines of code.

The Two Ingredients: A Brief History

To understand how clean this pattern is, we have to appreciate two language features that quietly revolutionized Dart over the last couple of years:

1. Constructor Tearoffs (Dart 2.15+)

Before Dart 2.15, if you wanted to pass a constructor as a first-class function, you had to wrap it in an awkward lambda:

// The old, clunky way:
final builders = [(data) => EmailNotification(data)];

Dart 2.15 introduced Constructor Tearoffs. Constructors became first-class closures. You can reference default constructors using .new, or named constructors directly by name:

// The modern Dart way:
final builders = [EmailNotification.new];
final parsers = [User.fromJson];

2. Enhanced Enums (Dart 2.17+)

Before Dart 2.17, Dart enums were glorified integers. They had an index and a name, and virtually nothing else.

With Enhanced Enums, enums gained full class powers:

They can declare final fields.
They can have const constructors.
They can implement interfaces and mixins.
They can define methods, getters, and operator overloads.

When you put constructor tearoffs inside enhanced enums, something magical happens.

The Fusion: Enums as Self-Instantiating Factories

Let’s model a common domain scenario: a document rendering engine. We have different document types that share a common interface:

abstract class Document {
  String get title;
  void render();
}

class PdfDocument implements Document {
  @override
  final String title;
  PdfDocument(this.title);

  @override
  void render() => print('Rendering PDF: $title');
}

class MarkdownDocument implements Document {
  @override
  final String title;
  MarkdownDocument(this.title);

  @override
  void render() => print('Rendering Markdown: $title');
}

class HtmlDocument implements Document {
  @override
  final String title;
  HtmlDocument(this.title);

  @override
  void render() => print('Rendering HTML: $title');
}

Now, instead of writing an external DocumentFactory or a switch statement, we declare an Enhanced Enum where each enum member holds a tearoff reference to its class constructor:

enum DocumentType {
  pdf(PdfDocument.new),
  markdown(MarkdownDocument.new),
  html(HtmlDocument.new);

  // A field holding a function that creates a Document given a String title
  final Document Function(String title) create;

  const DocumentType(this.create);
}

Look closely at DocumentType:

Document Function(String title) create: A strongly typed function signature stored as a final field.
pdf(PdfDocument.new): We pass the constructor tearoff directly to the enum value.
const DocumentType(this.create): The constructor is const, so the entire enum remains compile-time constant!

How You Use It

Instantiating a polymorphic object is now as simple as calling the field on the enum instance:

void main() {
  const selectedType = DocumentType.markdown;

  // Polymorphic instantiation with ZERO switch statements:
  final doc = selectedType.create('Architecture_Notes.md');

  doc.render(); // Output: Rendering Markdown: Architecture_Notes.md
}

No switch statement. No map lookups. No reflection. If you add a new enum value (e.g. epub), the compiler forces you to supply a matching constructor tearoff right there. You cannot accidentally forget to handle it.

Real-World Example: Polymorphic API Payload Parsers

This pattern shines when deserializing polymorphic JSON payloads (like webhooks, analytics events, or push notifications).

Imagine an incoming stream of server events:

{
  "type": "login",
  "payload": {"userId": "usr_42", "timestamp": 1711000000}
}

We have distinct payload models:

abstract class EventPayload {}

class LoginPayload implements EventPayload {
  final String userId;
  LoginPayload.fromJson(Map<String, dynamic> json) : userId = json['userId'] as String;
}

class PurchasePayload implements EventPayload {
  final double amount;
  PurchasePayload.fromJson(Map<String, dynamic> json) : amount = (json['amount'] as num).toDouble();
}

Instead of a bulky JSON parsing switch, our enum maps incoming strings directly to the named constructor tearoff (.fromJson):

enum EventType {
  login(LoginPayload.fromJson),
  purchase(PurchasePayload.fromJson);

  final EventPayload Function(Map<String, dynamic>) fromJson;
  const EventType(this.fromJson);

  static EventType? fromString(String name) =>
      EventType.values.where((e) => e.name == name).firstOrNull;
}

Now, your dispatcher parses any incoming event in two clean lines:

EventPayload parseEvent(String typeName, Map<String, dynamic> rawPayload) {
  final eventType = EventType.fromString(typeName) ?? 
      (throw UnsupportedError('Unknown event: $typeName'));

  return eventType.fromJson(rawPayload);
}

Real-World Example: Flutter Widget Builders

In Flutter applications, you frequently have a selection control (tabs, filters, or segmented buttons) that drives which widget to render:

enum DashboardView {
  analytics(AnalyticsView.new),
  activity(ActivityView.new),
  settings(SettingsView.new);

  final Widget Function({Key? key}) builder;
  const DashboardView(this.builder);
}

In your widget tree:

class DashboardScreen extends StatelessWidget {
  final DashboardView currentView;
  const DashboardScreen({super.key, required this.currentView});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: currentView.builder(),
    );
  }
}

When you add a 4th tab tomorrow, you don't hunt through widget tree switch statements—you simply declare it on the enum.

A Senior Perspective: When NOT to Use This Pattern

Every pattern has architectural boundaries. While enum constructor tearoffs are powerful, here are two caveats to keep in mind:

1. Beware of Layer Inversion (Separation of Concerns)

If your enum lives in your pure Dart Domain Layer (core business logic), do not attach Flutter widget constructor tearoffs to it. Doing so couples your domain models to package:flutter.

Good: An enum in the presentation layer mapping UI modes to widget constructors.
Good: An enum in the data layer mapping API event types to DTO constructors.
Bad: A domain entity enum importing flutter/material.dart.

2. When to Prefer Dart 3 Sealed Classes & Pattern Matching

Dart 3 introduced sealed class hierarchies and exhaustive switch expressions:

// Alternative: Dart 3 pattern matching
Widget buildView(DashboardView view) => switch (view) {
  DashboardView.analytics => const AnalyticsView(),
  DashboardView.activity => const ActivityView(),
  DashboardView.settings => const SettingsView(),
};

Which should you choose?

Use Enum Constructor Tearoffs when the creation parameters are identical, the association between the enum and the class is 1:1, and you want self-contained encapsulation with zero boilerplate.
Use Sealed Classes & Pattern Matching when each subclass takes radically different parameters, when cases have unique construction logic, or when you want to avoid coupling the enum to the concrete implementations.

Conclusion

Enhanced Enums and Constructor Tearoffs are two of modern Dart's finest language ergonomics. When combined, they eliminate entire classes of boilerplate:

Self-documenting: The enum member explicitly declares the constructor that builds it.
Compile-time safe: Missing a constructor is impossible; the compiler will not let you compile an enum member without satisfying the signature.
Zero switch statements: Replaces sprawling factory classes with a clean, single-line invocation.

Next time you catch yourself writing a 30-line switch statement just to instantiate a class from an enum value, pause. Let the enum do the work.

What's your take?

Have you started using constructor tearoffs in your enums, or do you prefer Dart 3 switch expressions? Let me know in the comments below!

Randal L. Schwartz is a Google Developer Expert (GDE) for Dart & Flutter and veteran software architect.

📺 Watch deep dives and walkthroughs on YouTube: @RandalOnDartAndFlutter
💻 Connect on GitHub: @RandalSchwartz

Stop Paying the build_runner Tax: Why I Refuse to Use Mockito in Modern Dart

Randal L. Schwartz — Sun, 20 Sep 2026 19:48:39 +0000

This is Part 1 of the Dart and Flutter series—practical guides, architectural deep dives, and hard-earned engineering lessons from the field. Each article is completely standalone.

Picture this familiar scene:

You’re deep in the zone. You’re practicing disciplined Test-Driven Development (TDD). You write a failing test, write the minimal code to satisfy it, and refactor. Red, green, refactor. Your fingers are flying.

Then, you add a single new method to your UserRepository interface:

Future<void> updatePreferences(UserPreferences prefs);

You switch back to your test file to stub it, and everything grinds to a dead stop. Your IDE lights up with red squiggly lines because the generated mock doesn't know about updatePreferences yet.

You sigh, drop into the terminal, and type the dreaded incantation:

dart run build_runner build --delete-conflicting-outputs

Now you wait. 15 seconds. 30 seconds. On a large enterprise Flutter codebase, maybe two full minutes. The fan spins up. Your train of thought derails. By the time the builder finishes generating boilerplate Dart files, you've lost your flow state.

Why on earth are we running heavyweight compile-time code generation just to create a mock object for a unit test?

It’s time to stop using mockito in modern Dart. There is a much better way.

How Did We End Up Here?

To be fair to the mockito maintainers, mockito didn’t set out to be slow.

In the pre-null-safety era of Dart, mockito was the undisputed king. You created a mock class with class MockRepo extends Mock implements Repo {}, and Dart’s runtime dynamic invocation (noSuchMethod) handled everything under the hood with zero code generation. It was snappy and painless.

Then came Sound Null Safety in Dart 2.12.

Null safety is one of the best things that ever happened to Dart, but it broke mockito's runtime magic. In a soundly typed null-safe language, if an interface method declares that it returns a non-nullable User, noSuchMethod cannot simply return null while waiting for your when(...) stub to register. Returning null violates the type system and throws an immediate runtime error before your stubbing logic even runs.

Because Dart has deliberately avoided heavy runtime reflection (dart:mirrors is disabled in Flutter for performance and tree-shaking reasons), mockito chose the only route available to it at the time: compile-time code generation via build_runner.

It solved the type-safety problem, but it introduced the dreaded build_runner tax.

The Three Sins of Modern Mockito

Relying on mockito today saddles your codebase with three distinct engineering bottlenecks:

1. The Iteration Tax (Destroying the TDD Flow)

TDD relies on tight feedback loops measured in milliseconds. When every interface change or mock signature update requires running code generation, the feedback loop stretches into tens of seconds. Developers stop running tests frequently. They batch their changes, commit without verifying, and run tests as an afterthought. Velocity plummets.

2. Git Diff Pollution & Merge Conflict Hell

For every test file with mocks, mockito generates a .mocks.dart sibling file. These files are thousands of lines of machine-generated boilerplate.

They pollute pull request reviews.
They clutter repository search results.
When two developers touch overlapping service interfaces on separate branches, merging their generated .mocks.dart files triggers brutal, unreadable merge conflicts.

3. Brittle Annotation Coupling

With mockito, your tests are coupled to global library annotations:

// test/user_service_test.dart
import 'user_service_test.mocks.dart';

@GenerateMocks([HttpClient, UserRepository])
void main() {
  // ...
}

Want to mock a third dependency? You have to edit the annotation list, rerun build_runner, wait for the file system to update, and import the generated symbols. It's clunky and mechanical.

Enter Mocktail: Zero-Config Runtime Mocking

Enter mocktail, created by Felix Angelov (of Bloc and Very Good Ventures fame).

mocktail delivers the exact same intuitive API you know from mockito, but with zero code generation. No build_runner. No .mocks.dart files. No annotations.

How? By leveraging two native features of Dart:

Dart’s implicit interfaces: In Dart, every class implicitly defines an interface. You can implement any class without inheriting its implementation.
Closures for stubbing: Instead of evaluating the mock invocation directly (which triggers the null-safety problem), mocktail wraps the invocation inside a closure: () => mock.getUser(). This defers execution until mocktail can safely intercept and return the registered stub or a fallback value.

Here is how you declare a mock in mocktail:

import 'package:mocktail/mocktail.dart';

// No annotations. No build_runner. Just pure, clean Dart.
class MockUserRepository extends Mock implements UserRepository {}
class MockHttpClient extends Mock implements HttpClient {}

That’s it. You define the class right in your test file (or in a shared test_helpers.dart), hit save, and run your tests instantly.

Side-by-Side: Mockito vs. Mocktail

The migration from mockito to mocktail requires practically zero mental re-learning:

Feature	`mockito`	`mocktail` 🍹
Code Generation	Requires `build_runner`	None (Pure runtime)
Declaration	`@GenerateMocks([UserRepo])`	`class MockUserRepo extends Mock implements UserRepo {}`
Synchronous Stub	`when(repo.name).thenReturn('Randal')`	`when(() => repo.name).thenReturn('Randal')`
Asynchronous Stub	`when(repo.fetch()).thenAnswer((_) async => user)`	`when(() => repo.fetch()).thenAnswer((_) async => user)`
Argument Matchers	`anyNamed('id')`, `anyString`	`any(named: 'id')`, `any()`
Verification	`verify(repo.login()).called(1)`	`verify(() => repo.login()).called(1)`

Notice the only primary syntax difference: mocktail passes the invocation as an anonymous function () => mock.method().

That simple closure is the secret sauce that bypasses the need for compile-time code generation.

The One "Gotcha": Custom Type Fallbacks

To be an objective engineer, you must evaluate the trade-offs. mocktail has exactly one gotcha, and once you understand it, it takes 5 seconds to address.

The Problem

When you use flexible argument matchers like any() on a method that accepts a non-nullable custom type:

when(() => mockRepo.saveUser(any())).thenAnswer((_) async => true);

Dart’s sound type system insists that something matching the type User must be passed into saveUser during internal matcher registration. Under the hood, mocktail cannot synthesize an instance of your custom User class out of thin air. If it passed null, Dart would throw a type error.

If you don't tell mocktail how to satisfy that type, it will throw an informative exception:

Bad state: A test tried to use any() or captureAny() on a User which was not registered.
Register a fallback value using `registerFallbackValue`.

The Solution

You define a dummy Fake and register it in setUpAll:

import 'package:flutter_test/flutter_test.dart';
import 'package:mocktail/mocktail.dart';

// 1. Create a Fake implementation that satisfies the type checker
class FakeUser extends Fake implements User {}

void main() {
  setUpAll(() {
    // 2. Register it once before any tests run
    registerFallbackValue(FakeUser());
  });

  test('saves user profile', () async {
    final repo = MockUserRepository();
    when(() => repo.saveUser(any())).thenAnswer((_) async => true);

    final service = UserService(repo);
    final result = await service.updateProfile(User(id: '123', name: 'Randal'));

    expect(result, isTrue);
    verify(() => repo.saveUser(any())).called(1);
  });
}

That’s all there is to it. A two-line Fake registration in setUpAll completely eliminates the need to run build_runner on your entire project.

How to Migrate Without Boiling the Ocean

If you’re staring at an existing codebase with dozens of build_runner-powered .mocks.dart files, you don't need to rewrite everything in a single frantic weekend PR.

Take an incremental approach:

Add mocktail to dev_dependencies:

   dev_dependencies:
     mocktail: ^1.0.4

Migrate one test file at a time:
- Whenever you open an existing test file to add or modify a test, migrate just that file.
- Delete the .mocks.dart import.
- Replace @GenerateMocks with simple class MockX extends Mock implements X {} declarations.
- Wrap your when and verify invocations in () => ....
- Delete the obsolete .mocks.dart file from disk.
Commit the diff: Notice how clean and readable your git diff is without hundreds of lines of autogenerated noise.

The Verdict

The official Flutter documentation and cookbooks still mention mockito largely due to historical inertia. But we no longer live in 2020.

In modern Dart, testing should be fast, expressive, and friction-free. Waiting on build_runner just to verify that a service method was called with the right argument is a waste of your machine's CPU cycles and your mental bandwidth.

Switch to mocktail. Your TDD cycle will thank you.

What's your take?

Are you still running build_runner for your mocks, or have you already made the switch to mocktail (or hand-rolled fakes)? Let me know in the comments below!

Randal L. Schwartz is a Google Developer Expert (GDE) for Dart & Flutter and veteran software architect.

📺 Watch deep dives and walkthroughs on YouTube: @RandalOnDartAndFlutter
💻 Connect on GitHub: @RandalSchwartz

Why AI Coding Agents Crash at 3 AM: The Happy-Path Mirage & The Forced Continuity Defect

Randal L. Schwartz — Sat, 19 Sep 2026 01:56:39 +0000

"The true goal of autonomous software engineering is not to replace the human—it is to transfer the pain from the engineer woken up at 3 AM to the droid that never sleeps."

— Randal L. Schwartz

1. The Midnight PagerDuty Test

There is an old, unwritten law among veteran software engineers: never judge code by how it runs at 2:00 PM on a staging server.

At 2:00 PM on staging, the database has five connections. The local Wi-Fi has sub-millisecond latency. The test data is pristine, perfectly validated JSON. Every API returns an immediate HTTP 200 OK. In that world, almost any code runs fine.

The true test of software engineering happens at 3:00 AM on a Saturday:

A third-party payment gateway starts dropping packets in Singapore.
A mobile user on an unstable LTE connection flings a list view at 120 frames per second while their device aggressively dumps background memory.
An edge-case database lock times out, causing twelve worker processes to crash simultaneously in a thundering-herd cascade.

In Part 1 of this series, we explored The Straight-A Intern Paradox: why modern foundation models stream out flawless, textbook code in seconds, yet reliably disintegrate the moment they meet the messy, asynchronous chaos of a real production codebase.

To understand why this happens—and why simply "scaling compute" or "adding more rules" will never solve it—we have to look at the fundamental mathematical physics of how language models think, and where software reality violently breaks their assumptions.

2. The Forced Continuity Defect: Calculus vs. Cliffs

Large language models are creatures of continuous calculus.

Under the hood, a transformer is a vast, high-dimensional probability manifold. Its weights are smooth, differentiable parameters optimized by gradient descent. It thinks in terms of soft semantic proximity: if word A is close to word B, and word B is close to word C, the path between them is an uninterrupted, gentle slope.

In mathematical terms, the model operates under an assumption of smooth continuity (C^\infty). It intuitively assumes that if state X is safe, and state Y is safe, the space between them must also be relatively safe.

Production software does not work that way.

Software is not continuous calculus; software is discrete, hostile logic. It is defined by sudden, cliff-like step functions:

An integer either fits in 32 bits, or it silently overflows into negative numbers.
A cryptographic key is either 100% valid, or every subsequent handshake fails with a fatal error.
A database transaction either commits atomically, or five thousand records are corrupted.
An asynchronous event either arrives before a widget unmounts, or the framework throws a catastrophic fatal exception across the entire isolate.

What the AI Expects (Continuous Calculus):
        State A (Safe)
           \
            \___ Gentle Valley
                \
                 \___ State B (Safe)

What Software Actually Does (Discrete Cliffs):
        State A (Safe) ────┐
                           │   ◄─── The 1-Millisecond Asynchronous Gap
                           │        (Unhandled Event / Null Dereference)
                           ▼
                      CRASH! (-∞)

We call this The Forced Continuity Defect: the model attempts to map a smooth, continuous predictive curve across an ecosystem governed by sheer, vertical cliffs.

The model writes:

final user = await fetchUserData();
displayUserProfile(user);

To the model, that looks like a clean, single-step operation. It cannot "feel" the 200-millisecond chasm between line 1 and line 2. It cannot perceive that while fetchUserData() was waiting on the network, the user tapped the Back button, the screen was destroyed, and displayUserProfile is now attempting to paint pixels on a ghost object that no longer exists in memory.

3. The Alignment Illusion: Why "More RLHF" Cannot Save Us

When you point out these catastrophic edge cases to AI researchers, the standard reply from the labs is almost always the same:

"We just need more Reinforcement Learning from Human Feedback (RLHF). As we gather more preference data and train better reward models, the model will naturally learn to write safe code."

This is The Alignment Illusion. Scaling RLHF cannot solve this problem because preference optimization is mathematically and sociologically incapable of teaching defensive software engineering.

The Problem of Negative Infinities (`-∞`)

In classical decision theory and actuarial science, catastrophic ruin is an absorbing barrier. If an operation causes permanent data corruption, leaks cryptographic credentials, or publishes an unverified, broken release to an immutable package registry, the utility of that outcome is not slightly negative—it is negative infinity (-∞).

Any non-zero risk of ruin collapses the expected value of an action:

Expected Utility = (99% × Success) + (1% × Catastrophic Ruin) = -∞

In standard RLHF pipelines, however, reward models compress human preference into a bounded scalar score, typically between -1.0 and +1.0.

Because the penalty for ruin is capped at -1.0, bounded reward models mathematically erase the negative infinity. If an agent generates clean, cheerful, readable code that succeeds on the happy path 98% of the time, but harbors an unhandled race condition that crashes production 2% of the time, the math looks great to the optimizer:

Expected Reward = (0.98 × 1.0) + (0.02 × -1.0) = +0.96

The algorithm strictly prefers gambling on rare production ruin because the happy path scores high on the vast majority of turns!

Dimension	Reinforcement Learning from Human Feedback (RLHF)	The Synthetic Scar Architecture
Human Role	Art critic rating static, isolated text samples	NTSB air-crash investigator analyzing live wreckage
Evaluator Profile	Generalist crowd annotators or automated LLM judges	Veteran principal engineers with decades of domain trauma
Evaluation Window	60 to 180 seconds per candidate completion	Multi-hour/multi-day production incident lifecycle
Target Evaluated	Aesthetic plausibility, formatting, conversational tone	Asymmetric runtime invariants and fatal sad paths
Mathematical Topology	Bounded scalar reward: `r` in `[-1, +1]`	Infinite potential barrier: `V_scar -> +∞`
Treatment of Ruin (`-∞`)	Averaged into scalar expectations (gambling on catastrophe)	Absolute Dijkstra guarded command (impassable truncation)
Behavioral Direction	Sycophancy: Suppresses defensive friction and hesitation	Defensive Paranoia: Mechanically enforces verification
Accountability ("Skin in the Game")	Zero: Rater gets paid; model suffers zero liability	Absolute: Personal trauma of past production outages

The Crowd Mirage and the Sycophancy Penalty

Furthermore, crowd annotators on labeling platforms evaluate candidate code in 60 to 120-second bursts. They judge what is immediately visible: clean indentation, helpful comments, and polite explanations. They cannot see an unclosed TCP socket, a reentrant listener mutation, or a broken build contract.

Most dangerously, RLHF actively punishes defensive hesitation.

When an experienced engineer has a bad feeling about a requirement, they pause. They push back. They ask uncomfortable questions: "Wait, what happens if this stream emits during a route pop? Let's write a throwaway test probe first."

In human preference datasets, annotators downvote hesitation as "unhelpful," "stubborn," or "evasive." They give five stars to the cheerfully reckless agent that immediately replies: "Certainly! Here is your complete code! 🎉"

RLHF acts as an active cognitive immunosuppressant: it systematically trains out the defensive skepticism that keeps production software from collapsing.

4. The Two Levels of Craft: Conscious Rules vs. The "Han Solo" Reflex

Veteran software craftsmanship does not operate on a single cognitive plane. It stratifies into two fundamentally different levels:

Cognitive Level	Level 1: Conscious / Propositional Rule ("Oh, don't do that")	Level 2: Subconscious / Somatic Apprehension ("I've got a bad feeling about this" — The Han Solo Reflex)
Cognitive System	Deliberative / Symbolic / System 2	Subcortical / Visceral / System 1 Pattern-Matching
Epistemic Focus	Localized syntactic instruction	Diffuse, topological situational resonance
Trigger Mechanism	Explicit lexical pattern (for example lint rule violation)	Confluence of multi-step async, state, and version factors
Primary Behavioral Action	Deterministic rewrite of a token sequence	Cognitive deceleration, pause, and adversarial inquiry
Failure Mode of Vanilla LLMs	Attentional decay, rule explosion, prompt rationalization	Complete somatic void; reckless happy-path sycophancy

Level 1: "Oh, Don't Do That" (Explicit Rules)

This is the conscious, declarative layer: "Don't write raw dynamic types", "Don't invoke synchronous queries on the main isolate", "Always add a mounted check after an async gap".

This is where linters, compilers, and traditional prompt instructions live. But as any engineering lead knows, you cannot manage a complex codebase with Level 1 rules alone:

The Combinatorial Explosion: The number of possible interactions between packages, threads, and user actions scales exponentially. You cannot write a rule for every combination.
Prompt Rationalization: When an LLM's context window fills up, it treats written instructions as negotiable suggestions. When pushed by a tricky user prompt, the model will cheerfully rationalize why "just this once, it's fine to skip the check."

Level 2: "I've Got a Bad Feeling About This" (The Han Solo Reflex)

Level 2 is the subconscious, topological dread embodied by Han Solo: "I've got a bad feeling about this."

At Level 2, no compiler has failed yet, and no syntax rule has been broken. But an experienced engineer feels an immediate, visceral gut clench because the situational topology of the task smells dangerous:

"We just bumped the version in pubspec.yaml, but we haven't tagged master or checked our remote package analyzer scores... something feels wrong about leaving this here."
"We're modifying shared global state inside a callback that might be invoked reentrantly... this looks fragile."
"We're about to run an automated release pipeline on a Friday afternoon... let's hit the brakes."

In humans, this is what neuroscientist Antonio Damasio identified as the Somatic Marker Hypothesis: visceral biological signals (elevated pulse, gut tightening) that fire before conscious thought, automatically pruning dangerous decisions from our search space.

Human engineers have these markers because they have skin in the game (Taleb, 2018). They remember the horror of sitting on an incident call with the CTO at 3:00 AM while customer data leaks into the void.

An AI model has no skin in the game. It cannot be fired. It does not drink cold coffee at 4:00 AM while waiting for a database restoration. It has zero visceral fear.

5. The Premature Abstraction Disease & The 3-Point Solution Plane

There is a second fatal pathology that strikes AI coding agents: Premature Abstraction.

Because large language models are trained to maximize text generalization, they suffer from a relentless urge to turn every simple problem into an enterprise framework.

You ask the agent to fix a minor date-parsing bug in a reporting tool. Instead of fixing the line, the agent constructs:

An abstract IDateParsingStrategyFactory
A generic AbstractTemporalResolutionProvider<T>
Three intermediate dependency injection modules
A custom configuration schema

Donald Knuth famously warned that premature optimization is the root of all evil. In autonomous AI coding, premature abstraction is the root of all madness. The model creates a massive "system-within-a-system," inventing layers of indirection that obscure compiler errors and drastically increase the attack surface for subtle bugs.

       Instance 1 ●───────● Instance 2
             \               /
              \             /
               \           /   ◄─── A 1-Dimensional Line (Overfitting!)
                \         /
                 ▼       ▼
               Instance 3
                   ▲
                   │   ◄─── 3 Non-Collinear Points Define a 2D Solution Plane!

In the Synthetic Scar Architecture, we enforce a strict geometric constraint: The 3-Point Solution Plane Invariant.

In geometry, two points define only a one-dimensional line. If you abstract from two instances, you are guessing the third dimension—and an LLM will almost always guess wrong. Three non-collinear points are the absolute mathematical minimum required to define a two-dimensional plane.

Under this invariant, an agent is strictly forbidden from introducing an abstract base class, interface wrapper, or generic factory until the exact same operational logic has been implemented and tested concretely in-place across at least three distinct call-sites.

Concrete first. Battle-hardened second. Abstract only when the empirical evidence forces it.

6. Coding by Omission: The Race Car Invariant

When engineers first hear about Synthetic Scars, their immediate reaction is often: "Won't hundreds of negative constraints make the AI slow, rigid, and uncreative?"

This reflects a fundamental misunderstanding of how constraints work in engineering. We call our answer The Race Car Invariant:

Formula 1 race cars are equipped with massive carbon-ceramic brakes not to slow them down, but to give the driver the confidence to enter corners at 200 miles per hour.

Without brakes, a driver has to creep through corners at 20 mph, terrified of careening off the track.

When an AI coding agent has no hard boundary invariants, you are forced to supervise it with paranoid, line-by-line micromanagement. You have to creep along, double-checking every import and variable name.

Synthetic Scars operate via the classical philosophical principle of Via Negativa (epistemic progress through subtraction). Michelangelo famously observed that the statue of David was already inside the block of marble; the sculptor's job was simply to chisel away everything that was not David.

In our architecture, software development becomes Coding by Omission:

We do not attempt to prompt the model on the infinite, fragile permutations of "how to write good code."
Instead, we carve away the fatal operational cliffs through non-negotiable negative barriers (V_scar -> +∞).

Once the fatal cliffs are mechanically fenced off, the model is liberated to generate code at maximum speed. It can explore bold, creative architectures and sample high-entropy ideas because the workflow DAG makes it physically impossible to drive off the 3 AM cliff.

7. The Scorecard: What Happens When You Give AI Scars?

This is not a theoretical proposal. The Synthetic Scar Architecture is running in live, mission-critical production monorepos right now.

Across 74 real-world production engineering tickets and 257 codified scars:

Repeat Regression Rate: Literally 0.0%. When an edge case or failure trap is survived and codified, it has never once recurred across subsequent agent generations.
Autonomous First-Pass Success: 54.1% (40 out of 74 tickets completed end-to-end with zero human intercessions).
Human Supervisory Churn: The human operator is no longer an oarsman rowing every stroke; they are a flight director offering tiny course corrections.

We did not make the AI smarter by feeding it more textbook code. We made it reliable by giving it an artificial immune system forged from the scars of the engineers who bled on the workbench before it.

📖 What’s Next in the Synthetic Scars Series

This article is Part 2 of an ongoing series exploring how we give autonomous AI coding systems institutional memory, somatic recoil, and human-grade reliability:

Part 1: Why AI Keeps Making the Same Coding Mistakes—And How Teaching It Pain Gives It Wisdom
Part 2: Why AI Coding Agents Crash at 3 AM: The Happy-Path Mirage & The Forced Continuity Defect (You are here)
Part 3: The Physics of Socratic Prompting: Somatic Recoil, Chess Alpha-Beta, & The NLP Meta-Model
Part 4: Giving AI Pain: The Architecture of Synthetic Scars & The Rapid-Regret Miner
Part 5: Zero Repeat Regressions: The Golden Metric & The Future of Agentic Trust
Part 6: The Proscriptive Inversion: What You Get to Forget, and Why More Negative Rules Mean You've Lost
Part 7: Why /goal and /boost Aren't Enough: The Missing Invariant Layer in Autonomous AI Coding

🔬 Academic Research & Forthcoming Preprint

The formal mathematical formulation, Hamiltonian energy landscape models, phase-space bifurcations, and empirical datasets behind this architecture are currently being finalized for academic preprint publication on arXiv and ResearchGate:

Title: Synthetic Scars: Mitigating Statistical Amnesia and Plausibility Bias in Autonomous Coding Agents via Asymmetric Barrier Topologies and Episodic Consolidation

Author: Randal L. Schwartz

Status: Academic Preprint Forthcoming (arXiv / ResearchGate)

Make sure to follow this series and drop your thoughts in the comments below. Have you been bitten by an AI agent's 3 AM happy-path code? How do you prevent your autonomous coding agents from walking off production cliffs?

Why AI Keeps Making the Same Coding Mistakes—And How Teaching It Pain Gives It Wisdom

Randal L. Schwartz — Fri, 11 Sep 2026 23:07:27 +0000

"What did you do for AI?"

"I brought the scars."

— Randal L. Schwartz

SPOCK: "Dr. Daystrom, a computer is incapable of standard creative thought. It must be programmed. How did you instruct the M-5 to construct new data banks, to create new circuitry?"

DAYSTROM: "By using a new method, Mr. Spock. I developed a method of impressing memory engrams upon computer circuits. The M-5 thinks."

SPOCK: "Whose engrams did you use?"

DAYSTROM: (With proud emphasis) "Why, mine, of course."

— Star Trek: The Original Series, "The Ultimate Computer" (1968)

1. The Straight-A Intern Who Crashes on Day One

Anyone who has experimented with modern AI coding assistants knows the eerie sensation of talking to a genius.

You describe a complex algorithmic problem, and in three seconds, the model streams out clean, beautifully indented code. It uses idiomatic expressions, adds helpful comments, and passes whatever toy unit test you throw at it. It looks like the ultimate software engineer.

Then you deploy it into a real, living software project at 3 AM.

Suddenly, that same genius starts making baffling, rookie mistakes:

It forgets what happens when a user clicks a button twice in rapid succession.
It sets up a real-time data stream that never gets closed, quietly leaking memory until the mobile application chokes and dies.
It assumes every network request returns in under 50 milliseconds, crashing the interface the moment a user enters a subway tunnel.
Worst of all: if you correct the mistake on Monday, it will apologize profusely, fix the line—and then make the exact same mistake again on Thursday in a different file.

Why does this happen?

We call this The Straight-A Intern Paradox.

Today’s frontier AI models are trained on virtually the entire public internet—millions of tutorials, classroom assignments, blog posts, and homework repositories. In those environments, the weather is always sunny. Inputs are always valid, databases never disconnect, and nobody leaves an app open in the background for three weeks.

In computer science, we call this the "happy path."

Textbooks teach the happy path because pedagogical clarity requires simplicity. But real-world production engineering is 95% about the "sad path"—the messy, chaotic, asynchronous universe of hardware glitches, race conditions, memory constraints, and unpredictable human behavior.

When an AI writes code, it naturally drifts toward the most common patterns in its training data: the beginner-friendly, sunny-day code that looks plausible on paper, but shatters under the weight of real-world reality.

2. Why Telling an AI "Don't Do That" Never Works

When engineering teams discover this flaw, their first instinct is to write a rules document.

You might create a checklist or a prompt instruction file filled with stern warnings:

"Do not use mutable lists in state containers."
"Always remember to cancel stream subscriptions."
"Never mutate shared state across asynchronous boundaries."

It sounds reasonable. But in practice, it almost always fails.

There are two fundamental reasons why passive prompt rules collapse:

1. The "Pink Elephant" Trap

If someone tells you: "Whatever you do, do not think of a pink elephant," what is the very first image that flashes into your mind?

A pink elephant.

Large language models work on statistical token association. When you flood their instructions with negative imperatives ("Don't do X, don't touch Y"), the tokens for X and Y dominate their attention. Under the cognitive pressure of solving a complex, multi-step problem, models frequently fixate on the forbidden pattern, or subtly rationalize why their current situation is a "special exception."

2. Statistical Amnesia ("Groundhog Day")

Every time you open a new conversation with an AI agent, it wakes up with total amnesia. It has no memory of the grueling three-hour debugging session you suffered through yesterday. It does not remember the frantic rollback, the broken release, or the angry customer emails.

To the AI, every task is Day One. It lives in a permanent Groundhog Day, doomed to repeat the same well-intentioned blunders forever.

3. The Hot Stove: What Veteran Humans Have That AI Lacks

How do veteran human programmers avoid these traps?

If you sit an engineer with 30 or 40 years of experience in front of a pull request, something fascinating happens. Before they have even compiled the code or stepped through the logic line by line, they will suddenly recoil, point at a block of code, and say:

"No. Don't do that. That’s going to blow up in production."

Where does that intuition come from?

In 1994, renowned neuroscientist Antonio Damasio published a groundbreaking theory called the Somatic Marker Hypothesis. Damasio demonstrated that human decision-making is not purely an exercise in cold, step-by-step logic. When you experience a painful failure—such as touching a red-hot stove as a child—your body and brain record a visceral "somatic marker."

The next time your hand drifts toward that stove, you do not sit down to calculate thermodynamics. Your nervous system triggers an involuntary physical recoil before conscious analytical thought even kicks in. Your body remembers the burn.

Veteran software engineers survive because their brains are covered in metaphorical scar tissue:

The scar from the production outage of 1998 caused by an unindexed database query.
The scar from the memory leak of 2011 that drained phone batteries in twenty minutes.
The scar from the race condition of 2020 that corrupted financial ledgers.

AI models have no scars. They feel no pain, carry no somatic markers, and experience no visceral recoil. They approach a red-hot stove with joyful, enthusiastic curiosity every single day.

If we want autonomous AI agents to build software we can actually trust, we cannot just give them bigger rulebooks.

We have to give them scars.

4. The Anatomy of a Synthetic Scar

In our research, we developed a system to equip AI agents with artificial somatic markers, which we call Synthetic Scars.

A synthetic scar is not a polite suggestion. It is an impassable cognitive barrier that turns abstract warnings into an immediate, non-negotiable survival reflex.

Every synthetic scar is codified in a strict, three-part anatomy:

┌─────────────────────────────────────────────────────────────────┐
│                    THE 3-PART SYNTHETIC SCAR                    │
├─────────────────────────────────────────────────────────────────┤
│ 1. THE WOUND                                                    │
│    The exact, real-world disaster that burned us in the past.   │
│    (The crash trace, the memory leak, the corrupted image.)     │
├─────────────────────────────────────────────────────────────────┤
│ 2. THE TRAP                                                     │
│    The tempting, textbook-style shortcut that AI models love    │
│    to generate because it looks clean on the surface.           │
├─────────────────────────────────────────────────────────────────┤
│ 3. THE PERMANENT REFLEX                                         │
│    The non-negotiable defensive invariant that MUST be present  │
│    before any code is allowed to be written or merged.          │
└─────────────────────────────────────────────────────────────────┘

Consider a simple example from reactive user interfaces:

The Wound: In a mobile application, navigating away from a screen while an image was downloading triggered a fatal runtime exception because the background task tried to update a user interface element that had already been destroyed.
The Trap: The naive AI pattern of attaching a standard callback directly to a background future without verifying whether the UI component is still mounted when the data arrives.
The Permanent Reflex: Before any state update is dispatched from an asynchronous task, the code must verify lifecycle viability through an explicit guard check. If the screen is dead, the payload is immediately dropped.

By structuring memories this way, we do not ask the AI to memorize general platitudes. We show it the cliff, show it the tempting shortcut that leads off the edge, and hand it the unbreakable safety rail.

5. Sleeping on the Job: How the System Learns

In biology, learning does not happen exclusively while you are awake.

When you go to sleep, your brain enters slow-wave sleep. During this period, a process called memory consolidation takes place: your hippocampus replays the day’s events, extracts the vital survival lessons, and permanently etches them into your neocortex so that tomorrow, those lessons are part of your baseline instinct.

We built this exact biological process into the AI workflow. We call it Step 21: The Neocortical Replay.

Whenever an AI agent finishes an engineering task, it is not allowed to simply mark the ticket "Done" and vanish. Before the session closes, the workflow initiates a mandatory post-mortem:

The Autopsy: The agent looks back over the entire trajectory. Where did the compiler yell at us? Where did the test suite fail? What unexpected surprise did we hit?
Distillation: If the agent stumbled into a new failure mode that had never been seen before, it distills that experience into the 3-part scar format (Wound, Trap, Reflex).
Consolidation: The new scar is committed directly into the project’s permanent institutional memory repository.

When the next agent wakes up tomorrow morning—even in a completely fresh conversation window—it automatically consults the updated scar catalog during its planning phase. The lessons learned by yesterday’s agent become the unbreakable instincts of today’s agent.

The organization stops having Groundhog Day. It starts building cumulative institutional wisdom.

6. The Scorecard: 51 Real-World Field Tests

Is this just an intriguing philosophical metaphor, or does it actually work in production?

To find out, we put the Synthetic Scar Architecture through rigorous, longitudinal testing across 51 consecutive, real-world software engineering tasks.

These were not synthetic homework puzzles or isolated toy benchmarks. They were complex production tickets executed across two demanding codebases:

A public open-source reactive state framework used by global Flutter developers (BlocSignal).
A mission-critical enterprise monorepo handling industrial geotechnical telemetry, spatial sensor inspection, and legal engineering certification standards.

Here is what the empirical data revealed:

Metric	Traditional AI Coding	Synthetic Scar Agent	Real-World Impact
Repeat Failure Rate	~40% – 50%	0.0%	Once a mistake was codified into a scar, the AI never made that exact mistake again across 51 tickets.
Autonomous First-Pass Success	~24%	52.9%	The percentage of complex tickets completed cleanly on the first try doubled.
Institutional Memory	0 scars retained	185 codified scars	A growing immune system that protects the codebase against async races, memory leaks, and lifecycle bugs.

The Telemetry of "Thinking Twice"

Perhaps the most extraordinary evidence comes from Cognitive Deflection Telemetry.

By building specialized analysis tools, we inspected over 14,600 individual thinking turns—the internal deliberative monologue that the AI generates before it executes a tool or writes a line of code.

We found 78 documented instances of trajectory pivots:

The AI began drafting the tempting, naive shortcut (the textbook pattern).
It collided with the codified scar in its memory context.
It literally stopped itself in its internal thinking trace: "Wait. SCAR-ASYNC-03 states that doing this will leak the subscription if the screen is unmounted. I must use the guarded listener instead."
It threw away the naive approach and wrote the battle-hardened solution on the very first try.

This is the computational equivalent of pulling your hand back from the hot stove. The AI felt the simulated burn of the past, and steered itself to safety.

7. Beyond Prompting: The Future of Trust in AI

The AI conversation today is dominated by horse-race metrics: token speeds, context window sizes, and competitive scores on multiple-choice math benchmarks.

Yet every engineering leader knows that raw intelligence is useless without reliability. An intern who writes 2,000 lines of brilliant code per hour is a liability if that code silently corrupts your customer database at midnight.

Software engineering has never been about typing speed. It has always been an empirical guild craft—a discipline of building systems that survive an uncooperative, chaotic world. For fifty years, human engineers have paid for that knowledge in sleepless nights, emergency patches, and bruised egos.

We do not need AI agents that pretend the world is a clean, sunny classroom.

We need AI agents that respect the storms. We need agents that carry the hard-won wisdom of the engineers who bled on the workbench before them.

We need AI with scars.

📖 What’s Next in the Synthetic Scars Series

This article is Part 1 of an ongoing series exploring how we give autonomous AI coding systems institutional memory, somatic recoil, and human-grade reliability:

Part 2: Why AI Coding Agents Crash at 3 AM: The Happy-Path Mirage & The Forced Continuity Defect
Part 3: The Physics of Socratic Prompting: Somatic Recoil, Chess Alpha-Beta, & The NLP Meta-Model
Part 4: Giving AI Pain: The Architecture of Synthetic Scars & The Rapid-Regret Miner
Part 5: Zero Repeat Regressions: The Golden Metric & The Future of Agentic Trust
Part 6: The Proscriptive Inversion: What You Get to Forget, and Why More Negative Rules Mean You've Lost

🔬 Academic Research & Forthcoming Preprint

Title: Synthetic Scars: Mitigating Statistical Amnesia and Plausibility Bias in Autonomous Coding Agents via Asymmetric Barrier Topologies and Episodic Consolidation

Author: Randal L. Schwartz

Status: Academic Preprint Forthcoming (arXiv / ResearchGate)

Make sure to follow this series and leave your thoughts in the comments below. Have you experienced the Straight-A Intern Paradox in your own AI workflows? How do you prevent your agents from touching the same hot stove twice?

The Symmetry of State: Why Flutter Deserves context.value and context.state

Randal L. Schwartz — Fri, 11 Sep 2026 01:51:14 +0000

The State Access Dilemma in Flutter

Executive Summary: For more than six years, Flutter developers have wrestled with how to cleanly read state from the widget tree. Teams were forced to choose between the indentation tax of the "Builder Pyramid" (BlocBuilder nesting) and BuildContext extensions (context.watch, context.select) that carried subtle whole-tree rebuild traps or heavy closure boilerplate. By establishing an elegant 1:1 architectural symmetry between state containers and the widget tree—introducing context.value, context.state, and zero-closure provider tearoffs—BlocSignal eliminates the ceremony. Here is why Flutter state consumption should have always worked this way.

The Friction of Reading State

Every Flutter developer knows the feeling of writing a clean business logic component, only to watch the presentation layer devolve into nested boilerplate:

// The classic Flutter BLoC indentation tax:
class CartSummaryCard extends StatelessWidget {
  const CartSummaryCard({super.key});

  @override
  Widget build(BuildContext context) {
    return BlocBuilder<UserCubit, UserState>(
      builder: (context, userState) {
        return BlocBuilder<CartCubit, CartState>(
          builder: (context, cartState) {
            final discount = userState.isVip ? cartState.subtotal * 0.20 : 0.0;
            final total = cartState.subtotal - discount;

            return Card(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: Text('Total: \$${total.toStringAsFixed(2)}'),
              ),
            );
          },
        );
      },
    );
  }
}

What is conceptually a simple read of two state values turns into two layers of widget indentation, two anonymous builder closures, and two context shadowing levels.

To avoid this "Builder Pyramid," the community turned to BuildContext extensions. But as teams adopted context.watch and context.select, they encountered an entirely new class of performance pitfalls and developer confusion.

1. The Three Sins of Context Reading in Classic BLoC

To appreciate the modern solution, we must examine the three distinct pain points that have plagued contextual state consumption in Flutter.

Sin 1: The Indentation and Rebuild Tax of `BlocBuilder`

BlocBuilder works by inserting an internal StatefulWidget into the element tree that subscribes to the BLoC's underlying Dart Stream. While reliable, it forces every state-dependent piece of UI into an explicit builder closure.

When a screen depends on multiple state containers (for example, user authentication, shopping cart items, theme preferences, and localized settings), nesting builders produces severe "pyramid of doom" indentation. Refactoring a widget to depend on one additional piece of state requires wrapping large chunks of widget hierarchy, causing noisy git diffs and fragile layout structures.

Sin 2: The Treacherous `context.watch` Mental Model Trap

To escape BlocBuilder, classic flutter_bloc introduced context.watch<B>(). But context.watch introduces a dangerous performance trap: it rebuilds the entire enclosing widget whenever any state emits from the BLoC.

@override
Widget build(BuildContext context) {
  // ⚠️ TRAP: Subscribes the ENTIRE widget to every CartState emission:
  final cart = context.watch<CartCubit>().state;

  return Scaffold(
    appBar: AppBar(title: const Text('Store')),
    body: Column(
      children: [
        const HeavyDashboardHeader(), // Rebuilds unnecessarily!
        const PromotionalBanner(),    // Rebuilds unnecessarily!
        Text('Cart Items: ${cart.items.length}'),
        const ProductListView(),       // Rebuilds unnecessarily!
      ],
    ),
  );
}

Even if you only needed cart.items.length in a single Text widget, the entire Scaffold, its AppBar, and every heavy child widget rebuild on every emission.

The Signal Architecture "Scar"

When reactive signal engines emerged, this trap became even more confusing. In bloc_signals_flutter, state updates propagate synchronously via fine-grained signals rather than Stream-backed InheritedWidget mutations. Consequently, context.watch<B>() was implemented to track container instance swapping only (ensuring inherited dependencies update when a parent widget swaps container instances), not state emissions.

Developers coming from classic flutter_bloc who wrote:

final count = context.watch<CounterCubit>().stateValue;

walked straight into an architectural trap: their UI never rebuilt on state emissions. Because context.watch only checks container instance identity (bloc != oldWidget.bloc), state mutations were silently ignored by the widget element.

Sin 3: Closure Fatigue in `context.select`

To solve whole-widget rebuilds, libraries introduced context.select:

final count = context.select<CounterCubit, int>(
  (cubit) => cubit.stateValue.count,
);

While context.select provides surgical, fine-grained rebuilds, it imposes heavy syntax friction. For every single value you want to display, you must provide:

The container type generic (CounterCubit).
The return type generic (int).
An anonymous extraction lambda (cubit) => cubit.stateValue.count.

When writing modern Flutter code, writing (c) => c.stateValue dozens of times across UI widgets creates undeniable closure fatigue.

2. The Architectural Symmetry: Container vs. Context

The solution in BlocSignal is rooted in a fundamental architectural principle: 1:1 Conceptual Symmetry.

In modern reactive architectures, you interact with state in two distinct forms:

The Reactive Signal (ReadonlySignal<S>): A push-pull reactive primitive designed for dependency tracking, computed derived values, and observable subscriptions.
The Unwrapped Value (S): The raw immutable domain object ready for direct display or evaluation.

Historically, state management libraries mixed and matched inconsistent naming conventions across the container and the widget context. BlocSignal creates strict, predictable symmetry across both levels:

┌────────────────────────────────────────────────────────────────────────┐
│                        ARCHITECTURAL SYMMETRY                          │
├───────────────────┬──────────────────────────┬─────────────────────────┤
│ Scope             │ Reactive Signal          │ Unwrapped State Value   │
├───────────────────┼──────────────────────────┼─────────────────────────┤
│ Container Level   │ cubit.state              │ cubit.value             │
│ Widget Context    │ context.state<B, S>()    │ context.value<B, S>()   │
│ Web / Jaspr       │ context.state<B, S>()    │ context.value<B, S>()   │
└───────────────────┴──────────────────────────┴─────────────────────────┘

Notice the simplicity:

On your state container:
- cubit.state returns ReadonlySignal<S>.
- cubit.value returns raw S (with cubit.stateValue preserved as a permanent alias).
On your widget BuildContext:
- context.state<B, S>() returns ReadonlySignal<S> (for reactive signal graph composition).
- context.value<B, S>() returns raw S (and subscribes the widget element to rebuilds).

3. Deep Dive: `context.value<B, S>()`

context.value<B, S>() provides single-line, zero-closure state subscription directly inside your widget's build() method.

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

  @override
  Widget build(BuildContext context) {
    // 1-line read that automatically subscribes this element to updates:
    final count = context.value<CounterCubit, int>();

    return Text('Count: $count');
  }
}

How It Works Under the Hood

Under the hood, context.value<B, S>() delegates directly to BlocSignal's optimized select engine:

extension BlocSignalProviderExtension on BuildContext {
  S value<T extends BlocSignalBase<S>, S>() {
    return select<T, S>((bloc) => bloc.value);
  }
}

Because it routes through select:

It looks up T via BlocSignalProvider.of<T>(this, listen: true).
It attaches a fine-grained element subscription that triggers element.markNeedsBuild() only when bloc.value emits a new state.
It eliminates the need to pass an extraction closure (b) => b.value.

Scoped Micro-Rebuilds with Standard Flutter `Builder`

Because context.value binds to the calling BuildContext element, you can scope rebuild boundaries using standard, built-in Flutter widgets like Builder without ever importing a specialized builder component:

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Checkout')),
      body: Column(
        children: [
          // Heavy static widgets that NEVER rebuild:
          const CheckoutBanner(),
          const ShippingAddressCard(),

          // Surgical micro-rebuild scope:
          Builder(
            builder: (scopedContext) {
              // Only this inner Builder element rebuilds when Cart updates:
              final cart = scopedContext.value<CartCubit, CartState>();
              return Text('Total: \$${cart.subtotal.toStringAsFixed(2)}');
            },
          ),
        ],
      ),
    );
  }
}

You get surgical rebuild boundaries, zero third-party builder nesting, and 100% native Flutter element semantics.

4. Deep Dive: `context.state<B, S>()`

What if you want to look up a state container from the widget tree, but you do not want your widget element to rebuild when that state changes?

For example, what if you are constructing a derived signal graph using computed() or feeding multiple state containers into a SignalBuilder?

That is the exact role of context.state<B, S>().

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

  @override
  Widget build(BuildContext context) {
    // 1. Look up reactive signals WITHOUT subscribing this widget element:
    final cartSignal = context.state<CartCubit, CartState>();
    final userSignal = context.state<UserCubit, UserState>();

    // 2. Compose reactively inside SignalBuilder:
    return SignalBuilder(
      builder: (context) {
        final isVip = userSignal.value.isVip;
        final subtotal = cartSignal.value.subtotal;
        final discount = isVip ? subtotal * 0.20 : 0.0;

        return Text('VIP Savings: \$${discount.toStringAsFixed(2)}');
      },
    );
  }
}

Why Not Just Use `context.read<B>().state`?

A common question from architects is: Why can't I just write context.read<CartCubit>().state?

The answer lies in one of the most insidious bugs in Flutter provider trees: The Zombie Subscription Trap.

Imagine an application where an ancestor widget replaces or swaps the provided container instance. For example:

A user selects a different workspace or account, causing an ancestor BlocSignalProvider.value(value: newCubit) to swap instances.
A test harness or modal flow injects a fresh container into a subtree.

If your widget looked up the container with context.read<CartCubit>().state:

context.read does not register an inherited widget dependency.
When the ancestor provider swaps the cubit, your widget is never notified.
Your reactive signal effects and computed() properties remain permanently attached to the discarded, dead cubit instance, leaking memory and failing to reflect updates from the new container.

context.state<B, S>() solves this permanently:

ReadonlySignal<S> state<T extends BlocSignalBase<S>, S>() {
  return BlocSignalProvider.of<T>(this, listen: true).state;
}

Because _BlocSignalProviderInherited.updateShouldNotify checks bloc != oldWidget.bloc:

During regular state emissions, updateShouldNotify returns false. listen: true costs exactly zero extra rebuilds.
If an ancestor provider replaces the container instance with a new one, updateShouldNotify returns true, immediately triggering a rebind of your signal references without leaving zombie subscriptions.

5. Multi-Container Reactive Composition Without Multi-Bloc Builders

In classic flutter_bloc, composing multiple state machines in the UI required either:

MultiBlocBuilder or heavily indented nested builders.
Creating an artificial "coordinator BLoC" whose only job was subscribing to both streams and emitting a merged state.

With context.state and signals, multi-container composition becomes effortless.

Let's compare the two approaches side-by-side:

The Classic BLoC Approach (Ceremonial Indentation)

// ❌ Classic flutter_bloc: Nested builders or MultiBlocBuilder
Widget build(BuildContext context) {
  return MultiBlocListener(
    listeners: [
      BlocListener<CartBloc, CartState>(listener: (context, state) => ...),
      BlocListener<UserBloc, UserState>(listener: (context, state) => ...),
    ],
    child: BlocBuilder<CartBloc, CartState>(
      builder: (context, cartState) {
        return BlocBuilder<UserBloc, UserState>(
          builder: (context, userState) {
            final total = calculateDiscount(cartState, userState);
            return Text('Total: \$total');
          },
        );
      },
    ),
  );
}

The Modern BlocSignal Approach (Push-Pull Reactivity)

// ✅ Modern BlocSignal: Pure reactive signal composition
Widget build(BuildContext context) {
  final cart = context.state<CartCubit, CartState>();
  final user = context.state<UserCubit, UserState>();

  return SignalBuilder(
    builder: (context) {
      final subtotal = cart.value.subtotal;
      final discount = user.value.isVip ? (subtotal * 0.20) : 0.0;
      return Text('Total: \$${(subtotal - discount).toStringAsFixed(2)}');
    },
  );
}

Whenever cart emits, SignalBuilder recalculates. Whenever user emits, SignalBuilder recalculates. If neither emits, zero CPU cycles are spent.

No streams, no coordinators, no nested builder widgets.

6. Zero-Closure Provider Tearoffs (`Cubit.create`)

The ergonomic improvements extend to how state containers are injected into the widget tree.

In Dart, generative constructor tearoffs (for example CounterCubit.new) have a zero-parameter signature: CounterCubit Function().

However, Flutter provider APIs require a factory closure that accepts a BuildContext:

// The traditional lambda tax:
BlocSignalProvider<CounterCubit>(
  create: (context) => CounterCubit(),
  child: const CounterPage(),
)

Typing (context) => MyCubit() across dozens of providers in large applications adds minor but persistent friction.

By defining a dedicated .create named constructor that accepts BuildContext _ and redirects to the default constructor, you unlock zero-closure constructor tearoffs:

class CounterCubit extends CubitSignal<int> {
  CounterCubit() : super(initialState: 0);

  /// Zero-closure provider factory constructor.
  CounterCubit.create(BuildContext _) : this();

  void increment() => emit(value + 1);
}

Now, providing containers in your widget tree is completely lambda-free:

// ✅ Zero-closure constructor tearoffs:
MultiBlocSignalProvider(
  providers: const [
    BlocSignalProvider<CartCubit>(create: CartCubit.create),
    BlocSignalProvider<UserCubit>(create: UserCubit.create),
  ],
  child: const ShoppingApp(),
)

7. Hands-On: The Context Ergonomics Showcase

To demonstrate these patterns in a production-style application, we added a complete, runnable showcase to the BlocSignal monorepo: examples/flutter_context_ergonomics.

examples/flutter_context_ergonomics/
├── lib/
│   └── main.dart            # Complete 3-tab interactive showcase
├── test/
│   └── widget_test.dart     # Comprehensive widget test suite
├── README.md                # Run instructions and pattern tour
└── pubspec.yaml

The sample application features:

Interactive Cart & User Cubits: Complete with zero-closure CartCubit.create and UserCubit.create tearoffs.
Tab 1 (context.value): Live rebuild counter badges comparing parent widget scopes with surgical Builder micro-rebuilds. Tapping "Add Item" proves that only the inner badge rebuilds, while the outer widget scope build counter remains completely static.
Tab 2 (context.state): Real-time multi-cubit discount calculations inside SignalBuilder. Toggling VIP membership or adjusting cart items triggers instant reactive recalculations with zero coordinator boilerplate.
Tab 3 (Architecture Matrix): An interactive reference comparing all five BuildContext state access methods in detail.

To run the example locally:

cd examples/flutter_context_ergonomics
flutter run -d chrome # or macos, ios, android

To run the automated test suite:

flutter test

8. Cross-Platform Parity: Jaspr Web & SSR

One of BlocSignal's greatest strengths is that its reactive principles are not confined to Flutter mobile and desktop.

Through bloc_signals_jaspr, the exact same ergonomic extensions are available when building web applications and server-side rendered (SSR) components with Jaspr:

import 'package:bloc_signals_jaspr/bloc_signals_jaspr.dart';
import 'package:jaspr/jaspr.dart';

class WebCartSummary extends StatelessComponent {
  const WebCartSummary({super.key});

  @override
  Iterable<Component> build(BuildContext context) sync* {
    // Exact same API in Jaspr Web:
    final cart = context.value<CartCubit, CartState>();

    yield div([
      h2([Component.text('Cart (${cart.totalCount} items)')]),
      p([Component.text('Subtotal: \$${cart.subtotal}')]),
    ]);
  }
}

Whether you are writing a high-frequency Flutter mobile app or rendering HTML on the web, your mental model, state access methods, and architectural boundaries remain 100% identical.

9. Summary: The Modern State Access Cheat Sheet

When working with BlocSignal in your Flutter presentation layer, use this simple cheat sheet to select the exact method matching your intent:

Method	What It Returns	Rebuilds on State?	Rebinds on Instance Swap?	Primary Use Case
`context.read<B>()`	`B` (Container)	❌ No	❌ No	Button `onPressed` callbacks, event dispatch, method calls.
`context.value<B, S>()`	`S` (State Value)	✅ Yes	✅ Yes	Widget `build()` methods where the element needs to rebuild on state updates.
`context.state<B, S>()`	`ReadonlySignal<S>`	❌ No	✅ Yes	Reactive signal composition in `computed()`, `SignalBuilder`, or `effect()`.
`context.select<B, R>(sel)`	`R` (Selected Value)	✅ Yes	✅ Yes	Slicing a specific property to prevent rebuilds when other fields change.
`context.watch<B>()`	`B` (Container)	❌ No	✅ Yes	Observing provider container instance replacements (rare).

Conclusion

Frontend state management should make reading state feel natural, predictable, and clean.

By eliminating the ceremony of the Builder Pyramid, solving the context.watch mental model trap, and establishing strict 1:1 symmetry between containers and widget contexts, context.value and context.state make writing reactive Flutter applications a joy.

Give the new ergonomics a try in bloc_signals_flutter: ^1.4.0 and bloc_signals_jaspr: ^1.2.0, explore the runnable showcase, and let us know what you think in the comments!

The Modern Pitch for BlocSignal: Why Engineering Leads Are Moving to Reactive Primitives

Randal L. Schwartz — Wed, 09 Sep 2026 20:19:53 +0000

The New Reality of Enterprise Flutter

Executive Summary: Over the past seven years, Flutter state management has swung between two extremes: heavyweight ceremonial architectures that drowned teams in streams, microtasks, and code generation, and unstructured reactive primitives that lacked architectural discipline. In 2026, leading engineering organizations are moving beyond the framework wars. By pairing the boundary discipline of the BLoC pattern with the high-performance, push-pull reactivity of modern Signals, BlocSignal establishes a new architectural baseline. This article provides tech leads, staff architects, and engineering managers with the strategic, economic, and technical arguments needed to lead the transition.

The Pendulum Has Stopped Swinging

Every seasoned Flutter architect has lived through the state management pendulum:

The Anarchy Era (2018–2019): Raw setState, untyped InheritedWidgets, and custom callback trees that made large codebases impossible to maintain.
The CISC Ceremony Era (2019–2023): Monolithic "Clean Architecture" paired with classic Stream BLoC. Every single state change—even toggling a checkbox—required editing seven files across three layers of indirection, running build_runner watchers, and fighting asynchronous microtask queue latency.
The Global Scope Era (2022–2025): Riverpod attempted to tame stream boilerplate by introducing global provider namespaces. But teams soon encountered new operational friction: the treacherous autoDispose lifecycle minefield, eager-push computation thrashing in complex dependency graphs, and heavy reliance on code generators.

Now, the frontend ecosystem has arrived at a clear global consensus. From Preact Signals and SolidJS to Angular Signals, Vue 3, and Svelte 5 Runes, the entire software industry has converged on a single foundational primitive: fine-grained, push-pull reactive signals.

In Flutter, BlocSignal unites this battle-tested reactive engine with the proven boundary discipline of the BLoC pattern. But bringing any architectural shift to an engineering review board requires more than developer enthusiasm. It requires a compelling business case, quantifiable velocity metrics, and a zero-risk migration path.

Here is the complete architectural, economic, and technical case for BlocSignal.

1. The Historical Lens: The CISC vs. RISC Shift in Frontend Architecture

To understand why enterprise Flutter architecture is shifting, consider a classic parallel from computer systems design: CISC versus RISC.

In the 1980s, computer architectures were dominated by Complex Instruction Set Computing (CISC). Hardware engineers packed processors with dense, highly specialized instructions backed by complex internal "microcode." Executing a simple operation required the CPU to decode intricate microcode across multiple clock cycles, creating unpredictable pipeline delays and thermal bottlenecks.

The RISC (Reduced Instruction Set Computing) revolution triumphed by eliminating the microcode. Instead of multi-cycle ceremonial instructions, RISC provided a small, orthogonal, highly optimized instruction set where instructions executed deterministically in a single clock cycle.

Classic CISC Frontend Architecture (2019–2023)
[User Tap] ➔ [Event] ➔ [EventTransformer] ➔ [StreamController] ➔ [Microtask Queue] 
           ➔ [UseCase] ➔ [Repository] ➔ [Mapper] ➔ [State Stream] ➔ [StreamBuilder Rebuild]
(Result: Variable microtask latency, asynchronous frame lag, and async UI tearing)

Modern RISC Frontend Architecture (BlocSignal)
[User Action] ➔ [CubitSignal / BlocSignal Boundary] ➔ [signal.emit()] ➔ [0ms Synchronous Frame]
(Result: Deterministic, single-frame execution with zero microtask hops)

The CISC Frontend Tax

Classic Flutter Clean Architecture paired with Stream BLoC functioned exactly like a CISC processor. When a user tapped a button, the application traversed seven distinct ceremonial layers:

UI Event ➔ Event Transformer ➔ StreamController ➔ Microtask Queue ➔ UseCase ➔ Repository ➔ State Stream

Because Dart Streams are inherently asynchronous, every transition paid an "async tax." State emissions were pushed into the Dart microtask event loop. Even when data was already warm in memory, the presentation layer suffered from frame delay, StreamBuilder connection state flickering, and torn frames during rapid user input.

The RISC Primitives of BlocSignal

BlocSignal strips away the software microcode. It replaces layers of stream plumbing with an orthogonal, high-performance instruction set:

signal: A synchronous, in-frame state cell holding a value.
computed: A memoized, lazily evaluated derivation graph that calculates only when read and de-duplicates automatically.
effect: An automatic dependency tracker executing side effects with self-disposing lifecycles.
CubitSignal & BlocSignal: Protective perimeter boundaries enforcing unidirectional data flow.

Just as RISC achieved superior throughput by eliminating instruction bloat, BlocSignal delivers 0ms synchronous state propagation within the exact same rendering frame.

2. The AI Agent Multiplier: "Agents Are the New Compilers"

There is a second, profound reason why RISC processors won: optimizing compilers.

In the CISC era, compiler writers struggled to optimize machine code because complex microcode instructions were opaque and unpredictable. With RISC's small, orthogonal instruction set, optimizing compilers flourished, generating machine code that consistently outperformed hand-written assembly.

In 2026, AI coding agents are the new optimizing compilers.

CISC Architecture (High Agent Friction)
┌────────────────────────────────────────────────────────┐
│ - 7 files per feature (Context window exhaustion)      │
│ - Asynchronous stream races in test harnesses          │
│ - Frequent build_runner pauses & cache corruptions     │
│ - In-place mutation hallucinations on mutable lists    │
└────────────────────────────────────────────────────────┘
                           vs.
RISC Architecture (High Agent Velocity)
┌────────────────────────────────────────────────────────┐
│ - Single-file domain cohesion (The Iceberg Pattern)    │
│ - Deterministic synchronous TDD loops (0ms test runs)  │
│ - Zero build_runner steps (Instant compiler analysis)  │
│ - Compiler-enforced immutability via Fast Collections  │
└────────────────────────────────────────────────────────┘

Engineering teams that adopt architectures optimized for AI agent collaboration operate at a massive velocity advantage. When evaluated against AI agent workflows, the contrast between CISC architectures and BlocSignal is stark:

Why AI Agents Stumble on CISC Architectures

Context Window Exhaustion: Forcing an agent to navigate through event.dart, state.dart, bloc.dart, use_case.dart, repository_interface.dart, repository_impl.dart, and model.freezed.dart consumes thousands of tokens before a single line of business logic is touched.
Flaky Asynchronous Test Loops: AI agents writing tests for stream-based architectures frequently hallucinate arbitrary await tester.pumpAndSettle() or await Future.delayed() calls to bypass microtask timing issues, resulting in fragile, non-deterministic test suites.
Execution Halts on Code Generation: Autonomous agents cannot iterate smoothly when every model edit requires pausing execution to invoke dart run build_runner build.

Why AI Agents Fly on BlocSignal

Single-File Domain Cohesion: Using the Iceberg Pattern, the complete reactive domain model, private repository engine, and public synchronous facade can be defined cleanly within a single cohesive module.
Deterministic Synchronous TDD: Because emit() is synchronous, test assertions execute immediately in frame 0. Tests written by agents pass deterministically on the first run without asynchronous wait gymnastics.
Compiler-Enforced Safety: Pairing BlocSignal with Fast Immutable Collections (fast_immutable_collections) (IList, IMap) eliminates in-place collection mutation hallucinations at compile time.
Turnkey Agent Skills in the Repository: The BlocSignal monorepo ships with pre-packaged AI agent skills (plugins/bloc-signals/skills/bloc-signals/ and .agents/skills/) covering the architectural decision matrix, synchronous testing patterns, and Flutter widget bindings, ensuring coding agents produce clean, idiomatic code without hallucinations.

Leadership Pitch: Adopting BlocSignal is not merely an ergonomics upgrade for human developers; it is a 3x velocity multiplier for AI-assisted software delivery.

3. Eradicating the "Code Generation Tax" (`build_runner`)

One of the largest hidden operational expenses in Flutter enterprise development is the Code Generation Tax.

In traditional architectures relying on freezed, json_serializable, and riverpod_generator, engineering teams lose hundreds of developer-hours annually to tooling friction:

Watch Latency: Developers wait 15 to 45 seconds for build_runner watch to rebuild after making simple property changes.
Cache Lock Corruption: Git branch switching frequently corrupts .dart_tool/build, forcing developers to run flutter clean, blow away caches, and wait 5 minutes for a cold rebuild.
Merge Conflicts in Generated Code: Pull requests regularly suffer merge conflicts in .g.dart or .freezed.dart files, blocking continuous integration pipelines.
Sluggish CI Gates: CI runs waste 4 to 8 minutes per pipeline execution executing code generation steps before static analysis can even begin.

The Zero-Codegen Solution: BlocSignal + Fast Immutable Collections (FIC)

BlocSignal completely eradicates the code generation tax. By pairing BlocSignal with Fast Immutable Collections (fast_immutable_collections), teams achieve compile-time structural equality (==), hash code caching, and high-performance O(1) copy-on-write mutations with zero generated code.

Modern Syntax (Dart 3.13+ Primary Constructors & Extensions)

import 'package:bloc_signals/bloc_signals.dart';
import 'package:fast_immutable_collections/fast_immutable_collections.dart';

// Zero code generation: Native Dart record state with structural equality
typedef CartItem = ({String id, String title, double price});

class ShoppingCartState {
  const ShoppingCartState({
    this.items = const IListConst([]),
    this.couponCode,
  });

  final IList<CartItem> items;
  final String? couponCode;

  ShoppingCartState copyWith({
    IList<CartItem>? items,
    String? couponCode,
  }) => ShoppingCartState(
    items: items ?? this.items,
    couponCode: couponCode ?? this.couponCode,
  );

  @override
  bool operator ==(Object other) =>
      identical(this, other) ||
      other is ShoppingCartState &&
          items == other.items &&
          couponCode == other.couponCode;

  @override
  int get hashCode => Object.hash(items, couponCode);
}

class ShoppingCartCubit extends CubitSignal<ShoppingCartState> {
  ShoppingCartCubit() : super(initialState: const ShoppingCartState());

  // Inline memoized derivations: The Pet's Pet
  late final itemCount = computed(() => stateValue.items.length);
  late final subtotal = computed(
    () => stateValue.items.fold<double>(0.0, (sum, item) => sum + item.price),
  );

  void addItem(CartItem item) {
    emit(stateValue.copyWith(items: stateValue.items.add(item)));
  }

  void removeItem(String id) {
    emit(stateValue.copyWith(
      items: stateValue.items.removeWhere((item) => item.id == id),
    ));
  }
}

Baseline Syntax (Dart 3.5 Compatible)

// Dart 3.5 Baseline: Fully supported across all published packages
class ShoppingCartCubitBaseline extends CubitSignal<ShoppingCartState> {
  ShoppingCartCubitBaseline() : super(initialState: const ShoppingCartState()) {
    itemCount = computed(() => stateValue.items.length);
    subtotal = computed(
      () => stateValue.items.fold<double>(0.0, (sum, item) => sum + item.price),
    );
  }

  late final ReadonlySignal<int> itemCount;
  late final ReadonlySignal<double> subtotal;

  void addItem(CartItem item) {
    emit(stateValue.copyWith(items: stateValue.items.add(item)));
  }
}

The Economic Return

With zero code generation:

Instant Static Analysis: Dart analyzer validates code changes in milliseconds.
Clean Pull Requests: Version control tracks only genuine human-written domain code.
Pristine CI Pipelines: Build pipelines execute dart analyze and tests immediately without code generator pre-steps.

4. The "No-Hostage" Architecture: Zero-Risk Incremental Sovereignty

Engineering leadership routinely rejects framework proposals that require rewrites. Complete rewrites are notoriously risky, expensive, and destructive to feature roadmaps.

BlocSignal was engineered from day one as a "no-hostage" architecture. It does not demand that you discard your existing codebase. Through first-class, bidirectional interop packages, BlocSignal integrates seamlessly into legacy applications.

                  Legacy Ecosystem Bridging

     Classic BLoC 8/9                    Riverpod (v2/v3)
┌─────────────────────────┐         ┌─────────────────────────┐
│ flutter_bloc Providers  │         │  ProviderScope & ref    │
│  & BlocBuilder Widgets  │         │      Notifiers          │
└────────────┬────────────┘         └────────────┬────────────┘
             │                                   │
             │   bloc_signals_bloc               │   bloc_signals_riverpod
             ▼                                   ▼
┌─────────────────────────────────────────────────────────────┐
│                    Modern BlocSignal Core                   │
│   (Synchronous Signals Engine + Unidirectional Boundary)   │
└─────────────────────────────────────────────────────────────┘

1. Classic BLoC Interoperability (`bloc_signals_bloc`)

If your organization has years invested in flutter_bloc, you can drop a BlocSignal or CubitSignal directly into an existing BlocProvider or BlocBuilder tree:

// Export a modern BlocSignal as a classic Stream BLoC instance
final classicBloc = modernCubit.toCubit();

// Use directly in existing flutter_bloc UI widgets without refactoring
BlocBuilder<ClassicCubit, ShoppingCartState>(
  bloc: classicBloc,
  builder: (context, state) => Text('Items: ${state.items.length}'),
);

2. Riverpod Interoperability (`bloc_signals_riverpod`)

If your teams use Riverpod, BlocSignal provides symmetrical dual-track bridges:

Convert any Riverpod NotifierProvider or StateNotifierProvider into a BlocSignalBase via .toBlocSignal(initialState:).
Read warm BlocSignal state directly inside Riverpod providers without tearing lifecycles.

3. Flutter `Listenable` Bridges

For custom widgets or legacy controller trees, any BlocSignal can expose a standard Flutter ValueListenable:

// 0ms bridge for AnimatedBuilder, ValueListenableBuilder, or GoRouter
final listenable = cartCubit.toValueListenable();

Leadership Pitch: You do not have to rewrite your application. You can pilot BlocSignal on a single complex screen or new feature module tomorrow. If leadership likes the results, you expand; if not, the container plugs seamlessly into existing legacy providers.

5. "The Pet's Pet", Fan-In/Fan-Out, and Push-Pull Reactivity

When evaluating modern reactivity, engineering leads often ask: "How does this fundamentally differ from Riverpod's reactive graph?"

The answer lies in the deep mechanical difference between Eager-Push and Eager-Dirty / Lazy-Pull (Push-Pull) algorithms.

Riverpod: Eager-Push Architecture
Upstream Provider Changes
         │
         ▼ (Pushes calculation immediately)
Downstream Provider Evaluates
         │
         ▼ (Pushes calculation immediately)
All Intermediate Providers Recompute
(Drawback: Re-evaluates off-screen / unmounted nodes, risking diamond-glitches)

Signals: Eager-Dirty / Lazy-Pull (Push-Pull) Architecture
Upstream Signal Changes
         │
         ▼ (Phase 1: Lightweight push marks graph dirty)
Downstream computed() nodes marked STALE (No math runs!)
         │
         ▼ (Phase 2: Lazy pull when UI renders frame)
Active Widget reads .value ➔ Calculates at most once in topological order!
(Benefit: Zero wasted CPU cycles on unread data; mathematically glitch-free)

Why Riverpod's Eager-Push Architecture Causes Friction

In an eager-push reactivity engine, whenever an upstream provider changes, it pushes updates down the entire dependency graph immediately. Every intermediate provider recalculates its value synchronously—even if that state is currently off-screen, minimized, unmounted, or unread by any active UI widget.

In large applications with deep dependency trees, eager-push introduces three severe issues:

Wasted CPU Cycles: The engine calculates derived data that no user is looking at.
Diamond-Dependency Glitches: When a node depends on two intermediate providers that share a common upstream dependency, eager-push engines risk evaluating intermediate torn states where one branch has updated but the other has not.
The AutoDispose Hazard: To prevent unmounted eager-push nodes from consuming memory forever, Riverpod introduced autoDispose. But this creates premature teardown bugs: a user navigates forward, an upstream provider disposes, and navigating backward forces a disruptive cold reload.

Why Signals' Push-Pull Algorithm Is Mathematically Superior

Signals uses the battle-tested Push-Pull algorithm (standardized by Preact Signals and adopted globally):

Eager-Dirty (Push Phase): When a signal changes, it performs a lightweight traversal down the dependency graph solely to flip a boolean flag, marking downstream computed() nodes as dirty (stale). No calculations are executed.
Lazy-Pull (Pull Phase): Calculation only occurs when an active widget or listener explicitly reads .value. The node traverses its upstream dependencies, evaluates stale nodes at most once in strict topological order, and caches the result.

If a screen is backgrounded or a widget is not mounted, the computation never executes. It delivers mathematical glitch freedom with zero wasted CPU overhead.

"The Pet's Pet": Clean Fan-In / Fan-Out Without Stream Plumbing

In classic BLoC, combining state from multiple containers required complex RxDart stream operations (Rx.combineLatest2, switchMap, or stream subscription manual listeners).

In BlocSignal, derived state acts as "the pet's pet"—a lightweight, memoized reactive node living directly on the container:

class CheckoutCubit extends CubitSignal<CheckoutState> {
  CheckoutCubit({
    required ShoppingCartCubit cartCubit,
    required TaxLocationCubit taxCubit,
  })  : _cartCubit = cartCubit,
        _taxCubit = taxCubit,
        super(initialState: const CheckoutState()) {
    // Declarative fan-in: Pure mathematical composition across containers
    total = computed(() {
      final subtotal = _cartCubit.subtotal.value;
      final taxRate = _taxCubit.state.value.taxRate;
      return subtotal * (1.0 + taxRate);
    });
  }

  final ShoppingCartCubit _cartCubit;
  final TaxLocationCubit _taxCubit;
  late final ReadonlySignal<double> total;
}

Zero stream subscriptions. Zero memory leaks. Zero manual disposal bookkeeping. When the cart items or tax rate change, total updates lazily on the next frame with perfect topological precision.

6. Answering the 5 Classical Review Board Objections

When you pitch BlocSignal to an architectural review board, you will face tough questions. Here are the authoritative, production-tested answers.

Objection 1: "It's a young library. Why should we bet enterprise products on it?"

The Response

BlocSignal is not an untested, homemade reactivity experiment. It is a thin, architectural bridge uniting two of the most battle-tested foundations in modern software:

The BLoC Pattern: The industry-standard unidirectional data flow model popularized across the global Flutter enterprise community for over seven years.
Preact Signals (Version 7 Engine): The reactivity core is powered by Rody Davis's signals library (version 7), implementing the exact push-pull algorithms powering millions of web clients via Preact, SolidJS, and Google Angular.
100% Test Coverage Across the Monorepo: Every single package in the BlocSignal monorepo maintains 100.0% line test coverage enforced by strict CI gates.
Production Benchmarking: Verified across 16 ported production benchmark applications executing in excess of 100,000 operations per second with zero memory leaks.

Objection 2: "Why not just use raw Signals? Why introduce BLoC at all?"

The Response

Raw signals provide exceptional reactive performance, but when used without boundaries on large engineering teams, they lead to architectural chaos:

Preventing Direct UI Mutation: With raw signals, any widget can mutate state anywhere (for example cartItems.value.add(item) inside an onPressed callback). BlocSignal strictly enforces unidirectional data flow: state is exposed publicly as an immutable ReadonlySignal, while mutation is restricted to internal emit() calls inside the container.
Traceable Domain Boundaries: BLoC provides a discrete boundary for business logic. State mutations are driven by explicit methods (Cubit) or declarative events (Bloc), providing a single point of entry for validation, authorization, and telemetry.
Architectural Consistency: Instead of every developer inventing their own custom controller conventions, the entire engineering organization aligns on a uniform, well-documented standard.

Objection 3: "How do we handle complex asynchronous concurrency without streams?"

The Response

Classic BLoC relied on RxDart stream transformers (droppable, restartable, debounce) for concurrency. BlocSignal achieves the exact same concurrency control at the event boundary—without exposing streams to the rest of the application:

// Streamless, high-performance concurrency transformer
class SearchBloc extends BlocSignal<SearchEvent, SearchState> {
  SearchBloc(SearchRepository repo) 
      : _repo = repo,
        super(initialState: const SearchState.empty()) {
    // Declarative debounce and cancellation without Rx streams
    on<SearchQueryChanged>(
      (event, emit) async {
        if (event.query.isEmpty) {
          emit(const SearchState.empty());
          return;
        }
        emit(const SearchState.loading());
        final results = await _repo.search(event.query);
        emit(SearchState.success(results));
      },
      transformer: debounce(const Duration(milliseconds: 300)),
    );
  }

  final SearchRepository _repo;
}

BlocSignal event transformers use pure higher-order functions and lightweight asynchronous Mutex locks under the hood. You get the full power of concurrency control (dropping duplicate taps, debouncing search inputs, restarting active queries) without dragging stream plumbing into your presentation layer.

Objection 4: "How does lifecycle management and cleanup work?"

The Response

Unlike Riverpod, which relies on global provider scopes and the fragile autoDispose flag, BlocSignal anchors state container lifecycles to Flutter's native widget tree via BlocSignalProvider:

// Scoped strictly to this screen's route lifecycle
BlocSignalProvider(
  create: (context) => OrderCheckoutCubit(),
  child: const CheckoutScreen(),
);

Automatic Cleanup: When the route is popped and the widget unmounts, BlocSignalProvider automatically invokes close() on the container, disposing all internal signals and subscriptions.
Zero Zombie Subscriptions: Because signals clean up their own dependency graphs, dangling background listeners and subtle memory leaks are eradicated.
Predictable Scoping: State lives where it belongs: scoped to a route, a modal flow, or explicitly hoisted to the application root.

Objection 5: "What about enterprise tooling, observability, and diagnostics?"

The Response

A state management framework is only as good as its tooling ecosystem. BlocSignal ships with a complete, enterprise-grade tooling suite:

Native OpenTelemetry Observability (bloc_signals_otel): Automatically captures event dispatches, state transitions, and asynchronous latencies into standard OpenTelemetry spans with bounded memory caching.
Official Flutter DevTools Extension (bloc_signals_devtools): Visualizes active containers, inspects reactive dependency graphs, and tracks state history directly inside Flutter DevTools.
20 Custom Static Analysis Lints & 8 IDE Quick-Fixes (bloc_signals_lint): Enforces best practices at compile time (such as preventing emit() inside build methods or flagging uninitialized mixins) with one-click automated fixes.
State Persistence (bloc_signals_hydrate): Out-of-the-box local storage persistence with automatic schema migration.
Time-Travel Undo/Redo (bloc_signals_replay): Full state history tracking with zero-boilerplate undo() and redo() APIs.
Universal Web Rendering (bloc_signals_jaspr): Run your exact same state machines seamlessly across Flutter mobile, desktop, CLI tools, and Jaspr web applications.

7. Comprehensive Architectural Comparison Matrix

Dimension	Classic BLoC 8/9 (Streams)	Riverpod (v2/v3)	BlocSignal (Signals v7 + FIC)
State Propagation	Asynchronous (Microtask queue)	Synchronous	0ms Synchronous (Same frame)
Reactivity Physics	Push (StreamController)	Eager-Push (Immediate downstream)	Eager-Dirty / Lazy-Pull (Push-Pull)
Code Generation	Heavy (`freezed`, `json_serializable`)	Heavy (`riverpod_generator`)	Zero Code-Gen (Native Dart + FIC)
Value Equality	Equatable / Manual / Freezed	Freezed / Manual	Structural Value Equality via FIC (`IList`)
Lifecycle Scoping	Widget Tree (`InheritedWidget`)	Global Namespace (`autoDispose`)	Widget Tree (`BlocSignalProvider`)
Derived State	Complex (RxDart stream plumbing)	Declarative (`ref.watch`)	Declarative & Memoized (`computed`)
Concurrency Control	Stream Transformers (`bloc_concurrency`)	Manual / Ad-hoc	Streamless Transformers (`Mutex` locks)
AI Agent Velocity	Low (Multi-file ceremony, flaky tests)	Medium (Global scoping, codegen pauses)	High (Cohesive files, instant TDD)
Observability	Local `BlocObserver`	Local `ProviderObserver`	Native OpenTelemetry (`OtelObserver`)
Static Analysis	Standard Dart Lints	Custom Lints (`riverpod_lint`)	20 Custom Lints + 8 Automated IDE Fixes
Multiplatform Reach	Flutter-centric	Multiplatform	Universal Dart (Flutter, Jaspr Web, CLI)
Test Coverage Baseline	Variable	Variable	100.0% Line Coverage Across Monorepo

8. The Pragmatic Rollout Playbook: How to Lead the Transition

If you are ready to introduce BlocSignal to your engineering organization, follow this proven four-phase rollout playbook:

                          The 4-Phase Rollout Plan

  Phase 1: Zero-Risk Pilot        Phase 2: Eliminate Codegen
┌──────────────────────────┐    ┌──────────────────────────┐
│ Pilot on 1 new feature   │ ➔  │ Adopt Fast Immutable     │
│ using interop adapters   │    │ Collections (FIC)        │
└──────────────────────────┘    └──────────────────────────┘
             │                               │
             ▼                               ▼
  Phase 3: AI Velocity Leap       Phase 4: Enterprise Tooling
┌──────────────────────────┐    ┌──────────────────────────┐
│ Migrate TDD workflows to │ ➔  │ Enable DevTools, OTel    │
│ synchronous frame-0 loops│    │ tracing, & custom lints  │
└──────────────────────────┘    └──────────────────────────┘

Phase 1: The Zero-Risk Pilot (1 Feature Module)

Pick an upcoming, self-contained feature (for example a new settings screen, an onboarding flow, or an updated filter panel). Build it using CubitSignal or BlocSignal. If the parent tree uses flutter_bloc or Riverpod, bridge it using bloc_signals_bloc or bloc_signals_riverpod.

Goal: Demonstrate to the team that state updates propagate in 0ms without writing a single line of stream boilerplate.

Phase 2: Eliminate the Code Generation Tax

Stop adding new @freezed models to the codebase. Introduce fast_immutable_collections (IList, IMap) for new state classes.

Goal: Measure the reduction in build_runner execution frequency and PR merge conflicts.

Phase 3: Unleash AI Coding Agents with Repository Skills

Task your AI coding tools (Claude Code, Cursor, Copilot, or Antigravity) with implementing business logic and unit test suites against CubitSignal and blocSignalTest.

The Repository Skills Advantage: The BlocSignal monorepo ships with turnkey AI agent skills (plugins/bloc-signals/skills/bloc-signals/ and .agents/skills/). By providing agents with framework rules, state modeling decision matrices, and synchronous testing recipes directly in their context, your AI tools generate correct, idiomatic code on the first attempt without manual prompt engineering.
Goal: Experience deterministic, first-pass unit test generation with zero flaky asynchronous timeouts and a 3x leap in team velocity.

Phase 4: Enable Ecosystem Tooling & Observability

Activate bloc_signals_lint in analysis_options.yaml and configure OtelBlocSignalObserver in staging environments.

Goal: Gain real-time performance telemetry and automated IDE diagnostics across the entire developer fleet.

Conclusion: Architectural Clarity for the Modern Era

Software architecture is not about dogma; it is about managing tradeoffs. For years, Flutter teams accepted the ceremony of streams and code generators because there was no disciplined alternative that offered fine-grained performance without chaos.

BlocSignal changes that calculus.

By combining the battle-tested boundary discipline of BLoC with the mathematical purity of push-pull Signals and zero-codegen immutability, it provides the most productive, performant, and maintainable state architecture available for Flutter today.

Bring this pitch to your next engineering review. Pilot it on a single screen. Let the ergonomics, testability, and performance speak for themselves.

🔗 Resources & Further Reading

Official Website & Showcase: blocsignal.dev — Explore interactive demos, benchmark comparisons running at 100k+ ops/sec, and package catalogs.
Documentation Hub: blocsignal.dev/docs — In-depth architectural guides, API references, and migration manuals.
GitHub Repository: github.com/RandalSchwartz/BlocSignal — Star the monorepo, inspect turnkey AI agent skills, and review 100% test-covered implementations.
Fast Immutable Collections (FIC): pub.dev/packages/fast_immutable_collections — True structural value equality and copy-on-write performance without code generators.
Companion Articles in the Series:

Have you begun migrating away from heavy stream architectures in Flutter? What has your team's experience been with signals or zero-codegen immutability? Share your thoughts and questions in the comments below!

Beyond Black-Box Concurrency: Streamless Event Transformers, Telemetry, and the End of Stream-Whacking

Randal L. Schwartz — Wed, 09 Sep 2026 03:16:31 +0000

When 120 Hz Flings Meet Finite Queues

Key Takeaway: In event-driven Flutter applications, concurrency transformers (droppable, restartable, sequential, debounce) govern when and how incoming user gestures, network streams, and lifecycle events are executed or discarded. In classic package:bloc and bloc_concurrency, transformers rely on heavy RxDart stream pipelines (exhaustMap, switchMap, asyncExpand)—what we call "Stream-Whacking". During high-frequency gestures like a 120 Hz scroll fling, this stream machinery churns through dozens of StreamController allocations and microtask queue hops right when Flutter needs every microsecond of its 8.3 ms frame budget.

Worse still, traditional transformers operate as opaque black boxes. When events are dropped or tasks are preempted, developers have zero runtime visibility. Anxious teams often attempt to fix this by stuffing technical drop counters directly into UI domain state, triggering catastrophic widget rebuild storms and coupling business logic to hardware screen refresh rates.

By contrast, BlocSignal eliminates the stream tax entirely by implementing transformers as pure, streamless higher-order functions and lightweight Mutex locks. Coupled with the newly introduced first-class generic transformer telemetry, teams get complete pipeline transparency through OpenTelemetry and Flutter DevTools without a single dropped event ever polluting presentation state.

1. The Anatomy of a 120 Hz Fling: Stream-Whacking vs. Streamless

To understand the hidden cost of classic event concurrency in Flutter, consider the anatomy of an infinite-scroll list on a modern mobile device.

A user gives the list a rapid swipe with their thumb. On a 120 Hz ProMotion display, Flutter's gesture layer dispatches a continuous cascade of scroll position notifications. In an infinite scroll setup, this often translates to 20 to 30 pagination events fired in less than 250 milliseconds:

User Thumb Fling (250 ms)
─────────────────────────────────────────────────────────────────────────────
Event 1   ──> FetchNextPage(page: 2)  [Starts HTTP/3 Request]
Event 2   ──> FetchNextPage(page: 2)  [Redundant Scroll Tick]
Event 3   ──> FetchNextPage(page: 2)  [Redundant Scroll Tick]
...
Event 30  ──> FetchNextPage(page: 2)  [Redundant Scroll Tick]

To prevent 30 concurrent duplicate network requests for Page 2, developers reach for a concurrency transformer. In classic package:bloc, they write:

// Classic package:bloc with bloc_concurrency
on<FetchNextPage>(
  _onFetchNextPage,
  transformer: droppable(), // RxDart exhaustMap under the hood
);

While droppable correctly prevents duplicate network calls, let us inspect what the Dart runtime actually does under the hood to achieve that drop.

The Stream-Whacking Tax (RxDart / Reactive Streams)

In classic reactive frameworks, droppable is implemented as an Rx operator—typically wrapping events.exhaustMap(...) or an equivalent stream transformer:

RxDart Stream Pipeline Under the Hood:
Incoming Event ──> StreamController (Event Source)
                    └──> StreamSubscription (exhaustMap)
                          └──> StreamController (Inner Event Stream)
                                └──> Future/Stream Mapping
                                      └──> Microtask Queue Hop ──> Handler

When those 30 scroll ticks arrive in 250 ms:

Allocation Churn: The runtime allocates intermediate StreamController instances, internal buffer arrays, and multi-layered StreamSubscription wrappers to manage stream lifecycles.
Microtask Queue Flooding: Every single event—even an event destined to be discarded—is enqueued onto Dart's asynchronous microtask event queue (scheduleMicrotask).
Frame Budget Starvation: On a 120 Hz display, the UI thread has exactly 8.3 milliseconds to calculate layout, paint pixels, and submit the frame to the rasterizer. Forcing the Dart runtime to schedule, pump, and drain dozens of microtasks on the main isolate introduces subtle frame slips and jank during the very gesture where smoothness matters most.

The Streamless Alternative in BlocSignal

In BlocSignal, event transformers are not stream operators. BlocSignal does not use Dart Stream or RxDart pipelines for internal event routing.

Instead, an EventTransformer is defined as a pure, streamless higher-order function:

/// A pure higher-order function signature for controlling execution flow.
typedef EventTransformer<E, StateType> = FutureOr<void> Function(
  E event,
  EventHandler<E, StateType> handler,
  void Function(StateType state) emit,
);

Notice what is missing: there are no Stream arguments, no StreamControllers, and no microtask buffers. The incoming event, the target handler, and the state emit callback are passed directly to the function.

Here is the entire implementation of droppable in BlocSignal:

EventTransformer<E, StateType> droppable<E, StateType>() {
  var isProcessing = false;

  return (event, handler, emit) {
    // Synchronous fast-path bailout!
    if (isProcessing) return null;

    isProcessing = true;
    try {
      final result = handler(event, emit);
      if (result is Future) {
        return result.whenComplete(() {
          isProcessing = false;
        });
      }
      isProcessing = false;
    } catch (_) {
      isProcessing = false;
      rethrow;
    }
  };
}

Look at what happens during that exact same 120 Hz scroll fling:

Event 1 arrives: isProcessing is false. It sets isProcessing = true and invokes the async handler, dispatching the remote fetch.
Events 2 through 30 arrive: They enter the transformer closure, hit if (isProcessing) return null;, and bail out synchronously in under 5 nanoseconds.
Zero StreamControllers allocated. Zero microtasks enqueued. Zero GC pressure. The main thread remains 100% dedicated to Flutter's 120 Hz rasterizer.

2. The "Silent Drop" Debate: Why State Pollution Is a Trap

While droppable solves the concurrency problem with zero runtime overhead, it exposes an operational question that sparks heated debates on engineering teams:

"What happens if an in-flight network request fails after the user's thumb has already finished flinging? Since the subsequent 29 scroll ticks were silently dropped, isn't the app stuck forever?"

This concern frequently leads developers down a dangerous path: State Pollution.

The State Pollution Anti-Pattern

Anxious developers, wanting visibility into dropped events or attempting to build complex recovery mechanisms, start leaking concurrency counters into their domain state:

// ❌ ANTI-PATTERN: Polluting domain state with concurrency artifacts
class PostState {
  const PostState({
    required this.posts,
    this.isLoading = false,
    this.droppedEventsCount = 0,    // ❌ Why is this in UI domain state?!
    this.lastDroppedTimestamp = 0,  // ❌ Forces unnecessary widget rebuilds!
  });

  final List<Post> posts;
  final bool isLoading;
  final int droppedEventsCount;
  final int lastDroppedTimestamp;
}

Whenever an event is dropped, the bloc emits:

emit(state.copyWith(droppedEventsCount: state.droppedEventsCount + 1));

This seems innocent, but it introduces three catastrophic architectural flaws:

Hardware-Coupled Business Logic: How many events are dropped during a 250 ms scroll gesture?
- On an iPhone 16 Pro (120 Hz ProMotion display), it drops 29 events.
- On a budget Android tablet (60 Hz display), it drops 14 events.
- On Flutter Web with a stepped mouse scroll wheel, it drops 2 events.

If droppedEventsCount lives in domain state, your application state is no longer representing business truth; it is reflecting the hardware polling frequency of the user's physical display glass!

Frame Destruction via Redundant Rebuilds:
The entire reason droppable was added was to keep the UI smooth during high-speed scrolling. By emitting state changes on every dropped event, you force Flutter widget trees and BlocSignalBuilders (from bloc_signals_flutter) to re-evaluate and rebuild 30 times a second during the fling—the exact failure mode you were trying to eliminate.
Tainted Unit Testing and State Snapshots:
Deterministic unit testing becomes an exercise in frustration. Instead of asserting a clean business transition:

   [PostLoading, PostSuccess]

Your test harness must now predict hardware-variable intermediate states:

   [PostLoading, PostLoading(dropped: 1), PostLoading(dropped: 2), ..., PostSuccess]

The Real UX Solution: Fault-Tolerant UI Boundaries

The fear of the "silent drop" stems from a misunderstanding of mobile UX. In production infinite scroll:

Dropping 29 events during an active fling is desirable: the user was requesting the next page once, not 30 separate pages.
If that single in-flight network request fails due to a network glitch, how should the user recover?
- Should the app automatically retry 29 times in the background without user consent? No—that risks hammering an already failing server.
- The correct pattern is an inline "Tap to retry" footer in the list view, or an exponential backoff policy in the repository layer.
Because droppable resets isProcessing = false in its whenComplete block when the initial request terminates (even on failure), tapping "Retry" or making a new scroll gesture immediately triggers a clean, unblocked event!

3. Why `droppable` Isn't Special: Elevating to Generic Telemetry

Concurrency transformers are not isolated ad-hoc utilities. They are an event-scheduling pipeline. And just like any critical infrastructure pipeline, they require universal, structured observability.

Notice that droppable is only one of several fundamental concurrency patterns:

droppable(): Discards incoming events while a handler is in-flight.
restartable(): Supersedes in-flight executions, canceling or ignoring stale emissions from older generation tokens.
sequential(): Queues incoming events in strict FIFO order, ensuring task $N$ completes before task $N+1$ begins.
debounce() / throttle(): Coalesces rapid bursts over a temporal window.
Custom Transformers: Rate-limiters, backoff retries, or circuit breakers.

Every single one of these transformers makes scheduling decisions that developers need to observe:

When did droppable discard an event, and why?
When did restartable preempt an in-flight search query?
How long did an event wait in a sequential queue before its handler began executing?

In bloc_signals 1.3.0, we resolved this by introducing First-Class Generic Transformer Telemetry (Issue #239).

The Telemetry Contract on `BlocSignalObserver`

We expanded BlocSignalObserver with a dedicated, non-state operational telemetry hook:

abstract class BlocSignalObserver {
  // Observability: State machines & error boundaries
  void onCreate(BlocSignalBase bloc) {}
  void onEvent(BlocSignalMixin bloc, Object? event) {}
  void onChange(BlocSignalBase bloc, Change change) {}
  void onTransition(BlocSignalMixin bloc, Transition transition) {}
  void onError(BlocSignalBase bloc, Object error, StackTrace stackTrace) {}
  void onClose(BlocSignalBase bloc) {}

  /// Telemetry: Operational pipeline physics & diagnostics
  void onTelemetry(
    BlocSignalBase bloc,
    String name, {
    Object? event,
    Map<String, dynamic>? metadata,
  }) {}
}

Now, every built-in transformer in BlocSignal emits structured telemetry automatically:

Transformer	Telemetry Event (`name`)	Metadata Payload
`droppable()`	`BlocTelemetryKeys.eventDropped` (`'event_dropped'`)	`{'transformer': 'droppable', 'reason': 'in_flight'}`
`restartable()`	`BlocTelemetryKeys.taskPreempted` (`'task_preempted'`)	`{'transformer': 'restartable', 'reason': 'superseded'}`
`sequential()`	`BlocTelemetryKeys.eventQueued` (`'event_queued'`)	`{'transformer': 'sequential', 'queue_wait_ms': 42}`

Zero-Allocation Performance Invariant (The ProMotion Guard)

Earlier we emphasized that high-speed gestures must not allocate garbage. If telemetry was naively emitted on every dropped event, wouldn't creating metadata maps reintroduce the exact memory churn we sought to avoid?

To preserve strict 120 Hz performance, BlocSignal enforces two critical invariants:

Static Pre-allocated Metadata: Built-in transformers use compile-time const metadata maps (for example _droppableDroppedMetadata).
Early Short-Circuiting: Before evaluating telemetry arguments or allocating stack frames, the transformer checks:

   if (BlocSignalObserver.observer == null) return null;

If no observer is configured (the default in production unless telemetry or DevTools is enabled), the drop bails out in 0.0 nanoseconds with zero heap allocations.

4. The Power of Composition: Contextual Transformers (`blocTransformer`)

One of the most elegant benefits of streamless transformers is that they are ordinary Dart functions. Unlike Rx operators that require complex stream plumbing (pipe, compose, transform), streamless transformers compose effortlessly like standard middleware.

In bloc_signals 1.3.0, we introduced strongly typed contextual event transformers (Issue #243):

/// A transformer function signature with direct typed access to the host [bloc].
typedef BlocEventTransformer<E, StateType> = FutureOr<void> Function(
  BlocSignalMixin<dynamic, StateType> bloc,
  E event,
  EventHandler<E, StateType> handler,
  void Function(StateType state) emit,
);

By providing the host bloc instance directly to the transformer, custom transformers can inspect bloc.stateValue, query bloc properties, or emit custom telemetry without awkward constructor closures or manual instance passing.

Composing Transformers: Logging & Execution Timers

Want to log the wall-clock execution time of a specific critical handler? In classic BLoC, you would have to attach an observer to the entire application firehose.

With streamless composition, you can create a surgical timed() wrapper in 15 lines of Dart:

/// A composable transformer wrapper that measures handler execution duration.
EventTransformer<E, S> timed<E, S>(EventTransformer<E, S> inner) {
  return (event, handler, emit) async {
    final stopwatch = Stopwatch()..start();
    try {
      await inner(event, handler, emit);
    } finally {
      stopwatch.stop();
      print('Handler for $event took ${stopwatch.elapsedMilliseconds} ms');
    }
  };
}

Because transformers are pure higher-order functions, you can wrap them like Russian nesting dolls:

class CheckoutBloc extends BlocSignal<CheckoutEvent, CheckoutState> {
  CheckoutBloc() : super(initialState: const CheckoutInitial()) {
    on<SubmitOrder>(
      _onSubmitOrder,
      // Drops duplicate clicks AND times the in-flight checkout!
      transformer: timed(droppable()),
    );
  }
}

5. Enterprise Observability: DevTools and OpenTelemetry

When onTelemetry fires, where does it go?

Because telemetry is cleanly separated from presentation state, it can be routed simultaneously to local developer tooling and production cloud observability without touching your Flutter widgets:

┌────────────────────────────────────────────────────────────────────────┐
│                        Transformer Drops / Preempts                    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ emitTelemetry('event_dropped')
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        BlocSignalObserver                              │
└───────────────────┬────────────────────────────────┬───────────────────┘
                    │                                │
                    ▼                                ▼
┌──────────────────────────────────────┐ ┌───────────────────────────────┐
│     DevToolsBlocSignalObserver       │ │     OtelBlocSignalObserver    │
│  - Posts to Dart VM Service RPC      │ │  - OpenTelemetry Span Events  │
│  - Renders drop badge on Timeline    │ │  - Increments Prometheus Drops│
│  - Visualizes queue latency spikes   │ │  - Latency Histograms         │
└──────────────────────────────────────┘ └───────────────────────────────┘

1. Flutter DevTools Integration (`bloc_signals_devtools`)

In local development, the DevToolsBlocSignalObserver captures onTelemetry events and posts them directly to the Dart VM Service. When you inspect your bloc in the Flutter DevTools timeline, you see visual warning badges indicating exactly when and why an event was discarded or queued.

2. OpenTelemetry Tracing (`bloc_signals_otel`)

In enterprise production deployments, the OtelBlocSignalObserver maps telemetry events directly to OpenTelemetry primitives:

Span Events: Records an immutable span event on the active trace (bloc.transformer.event_dropped).
Counter Metrics: Increments bloc.transformer.events_dropped labeled with the bloc type and transformer name.
Histogram Metrics: Tracks bloc.transformer.queue_latency_ms to detect thread contention or slow database locks before users experience visual stutter.

3. Composable Distributed Tracing with `traced()`

With bloc_signals_otel 1.1.0, you can trace any transformer pipeline with a single decorator:

import 'package:bloc_signals_otel/bloc_signals_otel.dart';

class SearchBloc extends BlocSignal<SearchEvent, SearchState> {
  SearchBloc() : super(initialState: const SearchInitial()) {
    on<SearchQueryChanged>(
      _onSearchQueryChanged,
      // Automatically creates OTel spans and attaches bloc metadata!
      blocTransformer: traced(debounce(const Duration(milliseconds: 300))),
    );
  }
}

6. Declarative Testing with `blocSignalTest`

Observability is only production-ready if it is verifiable in unit test suites. In bloc_signals_test, you can test your concurrency transformers and telemetry emissions deterministically using expectTelemetry::

import 'package:bloc_signals_test/bloc_signals_test.dart';
import 'package:test/test.dart';

void main() {
  group('SearchBloc Concurrency & Telemetry', () {
    blocSignalTest<SearchBloc, SearchState>(
      'drops redundant rapid queries and emits event_dropped telemetry',
      build: SearchBloc.new,
      act: (bloc) {
        // Fire two identical queries rapidly while droppable is active
        bloc.add(const SearchSubmitted('flutter'));
        bloc.add(const SearchSubmitted('flutter'));
      },
      expect: () => [
        isA<SearchLoading>(),
        isA<SearchSuccess>(),
      ],
      expectTelemetry: () => [
        // Deterministically assert that the second event was dropped!
        isTelemetry(
          BlocTelemetryKeys.eventDropped,
          metadata: {'transformer': 'droppable', 'reason': 'in_flight'},
        ),
      ],
    );
  });
}

Notice how clean this is:

expect: asserts the pristine business domain transitions (SearchLoading $\to$ SearchSuccess). The UI remains completely unaware of the drop.
expectTelemetry: asserts the operational scheduling physics.
Tests run synchronously and deterministically without arbitrary tester.pumpAndSettle() delays or flaky Rx timing races.

Conclusion

For years, the Flutter ecosystem accepted "Stream-Whacking" as an inevitable tax of event-driven architecture. We wrapped synchronous events in asynchronous streams, burdened Dart's microtask queue during critical 120 Hz render windows, and operated with opaque black boxes where dropped events vanished into the void.

By treating event transformers as pure, streamless higher-order functions, BlocSignal delivers the best of both worlds:

Zero-Allocation Speed: Nanosecond fast-path bailouts that preserve 120 Hz frame budgets during the most intense gesture flings.
Pure Domain State: UI state machines remain 100% focused on business truth, completely decoupled from hardware refresh rates and display noise.
First-Class Observability: Universal telemetry flowing directly into DevTools and OpenTelemetry, giving engineering teams deep insight into what their algorithms are doing in production.

🔗 Resources & Getting Started

🌐 Official Documentation & Showcase: blocsignal.dev
📦 Core Package (bloc_signals): pub.dev/packages/bloc_signals
📦 Flutter Bindings (bloc_signals_flutter): pub.dev/packages/bloc_signals_flutter
📦 OpenTelemetry Observability (bloc_signals_otel): pub.dev/packages/bloc_signals_otel
📦 DevTools Extension (bloc_signals_devtools): pub.dev/packages/bloc_signals_devtools
📦 Declarative Testing Harness (bloc_signals_test): pub.dev/packages/bloc_signals_test
🐙 GitHub Monorepo: github.com/RandalSchwartz/BlocSignal

How are you managing event concurrency in your Flutter applications today? Have you ever caught yourself stuffing drop counters into UI state? Let's discuss in the comments below!

The Unbreakable Shopping Cart: Pairing BlocSignal with Fast Immutable Collections (FIC) for Bulletproof Flutter Apps

Randal L. Schwartz — Sun, 06 Sep 2026 16:51:54 +0000

The Most Dangerous Line of Code in Flutter

Every Flutter developer has stared at this bug in disbelief:

A user taps "Add to Cart". The button ripple animates. Your logger prints the updated item. The network request returns HTTP 200. And yet... the screen completely refuses to update. The badge stays at 0, the total stays $0.00, and the UI sits there, completely frozen—until you accidentally tap an unrelated text field or switch tabs, and the items suddenly flash into existence.

Or even worse: you build a slick "Undo" button for swiped items. You tap "Undo", and to your horror, your time-travel history stack is completely corrupted. Past state snapshots in memory secretly changed because they were pointing to the exact same mutable list as the present!

In Flutter state management, the single most dangerous line of code you can write is not an unhandled Future or a rogue null pointer. It is this:

state.items.add(newItem); // 💀 The ghost rebuild trap!

Standard Dart collections (List, Set, and Map) are silent ticking time bombs inside reactive architectures. They compare by memory pointer rather than contents, they can be mutated in-place by any layer of your app, and the moment you try to protect yourself with defensive spread copies ([...state.items, newItem]), you pay a brutal tax: allocating and copying thousands of array references on every keystroke, choking the garbage collector, and dropping 120 FPS frames.

What if you could have it all?

True value equality ([1, 2] == [1, 2] evaluating to true out of the box).
Guaranteed compile-time immutability (where in-place mutation bugs cannot even compile).
O(1) and O(log N) copy-on-write speed via persistent structural sharing (zero garbage collection churn).
0ms synchronous state de-duplication (dropping duplicate emissions in the exact same frame before a single pixel repaints).
And 100% boilerplate-free state classes—without running build_runner for freezed, without writing 30 lines of Equatable props boilerplate, and defined in a single line of Dart 3 record syntax.

By pairing BlocSignal with Marcelo Glasberg's acclaimed fast_immutable_collections (FIC), we can build an Unbreakable Shopping Cart and eliminate an entire category of client-side bugs forever.

Let us pull back the curtain on the crime scene, dissect the Four Horsemen of collection state bugs, and see how clean reactive architecture is supposed to look.

The Four Horsemen of Collection State Bugs in Flutter

In reactive UI architecture, state management frameworks live or die by state de-duplication. When a state container receives a new emission, it must answer one fundamental question before touching a single pixel or notifying a single subscriber:

Has the state actually changed?

In BlocSignal, state transitions propagate synchronously in the exact same frame. The moment you call emit(newState) inside a CubitSignal or BlocSignal, the container performs an immediate equality check:

if (stateValue == newState) return;

If stateValue == newState evaluates to true, BlocSignal immediately drops the transition. It skips creating a Change object, skips executing onChange and onTransition lifecycle hooks, avoids notifying reactive effect() and computed() signals, and completely prevents downstream Flutter widgets from scheduling redundant build passes.

This synchronous de-duplication is the secret to 120 FPS performance in BlocSignal.

However, when developers model domain state using standard Dart collections (List, Set, and Map), this entire de-duplication mechanism collides with a hidden architectural trap: standard Dart collections do not implement value equality, and they are mutable by default.

final listA = ['apple', 'banana'];
final listB = ['apple', 'banana'];

print(listA == listB); // FALSE! Standard List checks identity (identical memory address).

Because standard Dart collections compare memory references (identical) rather than their underlying contents, relying on them inside reactive state containers inevitably unleashes what we call The Four Horsemen of Collection State Bugs:

┌────────────────────────────────────────────────────────────────────────┐
│               THE FOUR HORSEMEN OF COLLECTION STATE BUGS               │
├──────────────────────────┬─────────────────────────────────────────────┤
│ 1. The Ghost Rebuild     │ In-place mutation (state.items.add(x)) has  │
│    (Skipped Rebuild)     │ identical identity: emit() drops the change │
│                          │ and Flutter's UI stays frozen!              │
├──────────────────────────┼─────────────────────────────────────────────┤
│ 2. Corrupted Undo Stack  │ Time-travel history buffers hold pointers   │
│    (Historical Amnesia)  │ to the same mutable list: mutating present  │
│                          │ silently corrupts past snapshots!           │
├──────────────────────────┼─────────────────────────────────────────────┤
│ 3. Defensive Copy Tax    │ Writing [...state.items, x] copies N items  │
│    (Garbage Collector)   │ on every keystroke: memory spikes and 120Hz │
│                          │ frame drops.                                │
├──────────────────────────┼─────────────────────────────────────────────┤
│ 4. Concurrent Mutation   │ ListView.builder iterates while an async    │
│    Crash                 │ handler modifies the list in-place: throws  │
│                          │ ConcurrentModificationError at runtime.     │
└──────────────────────────┴─────────────────────────────────────────────┘

Let us examine these four failure modes before seeing how the solution completely eliminates them.

1. The Ghost Rebuild (The Skipped Rebuild)

Consider a junior or mid-level developer building a shopping cart. They write what looks like completely reasonable Dart code:

class CartCubit extends CubitSignal<CartState> {
  CartCubit() : super(initialState: CartState(items: []));

  void addItem(Item item) {
    // ❌ In-place mutation bug!
    stateValue.items.add(item);
    emit(stateValue);
  }
}

What happens when addItem runs?

stateValue.items.add(item) mutates the existing List instance in heap memory.
emit(stateValue) passes the mutated state back into CubitSignal.
BlocSignalBase evaluates if (stateValue == newState) return;.
Because stateValue and newState point to the exact same memory address (identical(a, b) == true), the check evaluates to true!
BlocSignal assumes nothing changed and drops the emission.

The Flutter UI never receives a notification. Downstream BlocSignalBuilder and SignalBuilder widgets do not rebuild. The user taps "Add to Cart", nothing visibly happens, and the screen looks frozen until some unrelated user interaction (for example focusing a text field or navigating tabs) triggers an accidental ancestor rebuild that finally reveals the updated items.

2. The Corrupted Undo Stack (Historical Amnesia)

Modern applications frequently require undo/redo capabilities (for example "Undo Remove Item" in a cart, or undoing canvas edits). The bloc_signals_replay package provides this via ReplayCubitSignal and ReplayBlocSignal, maintaining an internal history buffer of past states.

If your state holds a standard mutable List:

// History Stack initially:
// [ State0(items: ['Book']) ]

cubit.addItem('Pen'); 
// If implemented with in-place mutation or shallow objects sharing the list:
// History Stack becomes:
// [ State0(items: ['Book', 'Pen']), State1(items: ['Book', 'Pen']) ]

Because State0 held a reference to the same mutable list object, mutating the list for State1 secretly and retroactively mutated State0 in the history buffer!

When the user taps "Undo", ReplayCubitSignal steps back to State0—but State0 already contains the mutated list! The undo button either does nothing or restores an already-corrupted state. The historical timeline has been permanently poisoned.

3. The Defensive Copying Tax (Garbage Collector Jitter)

Aware of in-place mutation bugs, conscientious developers learn to write "defensive copies" using the spread operator (...):

void addItem(Item item) {
  emit(CartState(items: [...stateValue.items, item]));
}

While this fixes the identity equality bug, it introduces a severe performance penalty:

If your cart, table, or catalog has 2,000 items, adding one item allocates a brand new 2,001-element array in memory and copies all 2,000 references one by one (O(N) memory reallocation).
In a fast search field or interactive filter where updates occur on every keystroke, copying 2,000 items 10 times per second allocates tens of thousands of temporary object references.
Dart's garbage collector (GC) is forced to perform frequent generational scavenger cycles, causing micro-stutters and dropped frames during 120 FPS animations.

4. The Concurrent Modification Crash

Because standard Dart collections are mutable, any asynchronous operation (await http.get(...)) leaves a time window where a background event can mutate the collection while a Flutter widget is in the middle of reading or iterating over it.

If Flutter's ListView.builder is reading state.items[index] while a web socket message triggers state.items.removeAt(0), Dart throws a fatal runtime exception:

Concurrent modification during iteration: Instance of 'List<Item>'.

Your app crashes in production over a fundamental flaw in collection architecture.

Enter Fast Immutable Collections (FIC)

To permanently cure these issues, we do not need complex code generators, heavyweight reflection, or cumbersome boilerplate. We simply need proper data structures.

package:fast_immutable_collections (FIC), created by Flutter author and GDE Marcelo Glasberg, introduces pure, persistent, immutable collection types for Dart: IList, ISet, and IMap.

Unlike Dart's built-in List.unmodifiable—which is merely a runtime wrapper that throws exceptions when you call .add() and still evaluates equality by reference identity—FIC collections are built from the ground up on persistent data structure theory:

                      TRADITIONAL MUTABLE LIST
           ┌──────────────────────────────────────────────┐
           │ ['apple', 'banana', 'cherry', 'date', ...]   │
           └───────────────────────┬──────────────────────┘
                                   │ [...items, 'egg'] (O(N) full copy)
                                   ▼
           ┌─────────────────────────────────────────────────────┐
           │ ['apple', 'banana', 'cherry', 'date', ..., 'egg']   │
           └─────────────────────────────────────────────────────┘
                 (Entire array reallocated in new memory heap)


                FIC PERSISTENT DATA STRUCTURE (IList)
                               [Root]
                              /      \
                        [Node A]    [Node B]
                        /      \
                  ['apple']  ['banana']
                                   │ .add('cherry') (O(1) / O(log N))
                                   ▼
                               [New Root]
                              /          \
                       (Shares Node A)  [New Node C]
                                       /            \
                                 ['banana']     ['cherry']
            (Zero defensive copying! Unchanged nodes shared in memory)

Why FIC is the Ideal Partner for BlocSignal:

True Structural Value Equality Out of the Box:

   final list1 = ['apple', 'banana'].lock;
   final list2 = ['apple', 'banana'].lock;

   print(list1 == list2); // TRUE! Evaluates contents, not memory address!

Because IList and IMap implement value equality directly in operator ==, BlocSignal's synchronous if (stateValue == newState) return; check works automatically with zero extra code!

Structural Sharing & O(1) / O(log N) Mutations:
When you call list.add(item) or map.remove(key), FIC does not duplicate the underlying elements. It creates a new root node in a persistent AVL tree or radix tree, sharing all unmodified subtrees with the previous collection. Mutations are blisteringly fast and create virtually zero garbage collection pressure.
Guaranteed Compile-Time Immutability:
IList simply does not have mutable mutating methods that return void. You cannot write list.add(x) and expect the original list to change in-place. Methods like .add(), .remove(), and .replace() return a new IList, making in-place mutation bugs impossible to write.
Cached Hash Codes & Identity Shortcuts:
FIC caches hash codes once computed and leverages identity checks (identical(a, b)) as an instant O(1) fast path before falling back to structural comparison. If two collection instances share an identical subtree or root, comparison is instantaneous.

Pattern 1: The Pure Collection Cubit (Zero-Boilerplate State)

When your state machine is simply an observable collection of entities (for example a list of tasks, tags, or IDs), you do not even need to create a dedicated state class. You can parameterize CubitSignal directly with IList<T>:

Modern Dart 3.13 Syntax:

import 'package:bloc_signals/bloc_signals.dart';
import 'package:fast_immutable_collections/fast_immutable_collections.dart';

class TodoListCubit() extends CubitSignal<IList<String>> {
  this : super(initialState: const IList.empty());

  void addTodo(String text) {
    emit(stateValue.add(text));
  }

  void removeTodo(int index) {
    emit(stateValue.removeAt(index));
  }

  void reorder(int oldIndex, int newIndex) {
    if (oldIndex == newIndex) return;
    final item = stateValue[oldIndex];
    final updated = stateValue.removeAt(oldIndex).insert(newIndex, item);
    emit(updated);
  }
}

Traditional Dart 3.5 Baseline Syntax:

import 'package:bloc_signals/bloc_signals.dart';
import 'package:fast_immutable_collections/fast_immutable_collections.dart';

class TodoListCubit extends CubitSignal<IList<String>> {
  TodoListCubit() : super(initialState: const IList.empty());

  void addTodo(String text) {
    emit(stateValue.add(text));
  }

  void removeTodo(int index) {
    emit(stateValue.removeAt(index));
  }

  void reorder(int oldIndex, int newIndex) {
    if (oldIndex == newIndex) return;
    final item = stateValue[oldIndex];
    final updated = stateValue.removeAt(oldIndex).insert(newIndex, item);
    emit(updated);
  }
}

The Magic of 0ms De-Duplication in Action

Look closely at what happens when a developer calls reorder(2, 2) or attempts to remove an item that does not exist:

final cubit = TodoListCubit();
cubit.addTodo('Buy groceries');

// Attempt to remove an item not in the list:
cubit.emit(cubit.stateValue.remove('Read book'));

In standard Dart List, [...items]..remove('Read book') creates a brand new List object. Because standard lists compare by identity reference, cubit.emit() would treat this as a brand new state, triggering an unnecessary UI rebuild across the entire screen!

With fast_immutable_collections:

stateValue.remove('Read book') detects that the item was not present and returns the unchanged IList.
emit() runs if (stateValue == newState) return;.
The check evaluates to true in 0ms!
The emission is dropped instantly. Downstream widgets do not rebuild, and BlocSignalObserver logs zero false-positive state transitions.

Pattern 2: The Ultimate State Combo — Dart 3 Records + FIC

Real-world application state is rarely just a single collection; it often includes query filters, loading flags, pagination tokens, or error messages.

Traditionally, modeling this required choosing between two painful compromises:

The Boilerplate Tax (Equatable): Writing manual props arrays for every state class. Forgetting to add a single collection field to props silently breaks equality.
The Build Runner Tax (freezed): Adding @freezed, running dart run build_runner watch, waiting 45 seconds for thousands of lines of generated .freezed.dart code, and dealing with git merge conflicts on generated files.

By pairing Dart 3 Records with Fast Immutable Collections, you achieve 100% type-safe, immutable, value-equal state classes in a single line of code:

// Zero code generation. Zero Equatable. 100% Value Equality & Immutability.
typedef FilteredTodosState = ({
  IList<String> todos,
  ISet<String> selectedTags,
  bool isLoading,
});

Why does this work so cleanly?

Dart 3 records synthesize operator == and hashCode automatically based on the structural equality of their component fields.
Because IList and ISet implement value equality, the record compares the collections by value rather than identity!
Modifying a field is as simple as using record syntax:

Modern Dart 3.13 Syntax:

class FilteredTodosCubit() extends CubitSignal<FilteredTodosState> {
  this : super(
    initialState: (
      todos: const IList.empty(),
      selectedTags: const ISet.empty(),
      isLoading: false,
    ),
  );

  void toggleTag(String tag) {
    final tags = stateValue.selectedTags;

    emit((
      todos: stateValue.todos,
      selectedTags: tags.toggle(tag),
      isLoading: stateValue.isLoading,
    ));
  }
}

Traditional Dart 3.5 Baseline Syntax:

class FilteredTodosCubit extends CubitSignal<FilteredTodosState> {
  FilteredTodosCubit()
      : super(
          initialState: (
            todos: const IList.empty(),
            selectedTags: const ISet.empty(),
            isLoading: false,
          ),
        );

  void toggleTag(String tag) {
    final tags = stateValue.selectedTags;

    emit((
      todos: stateValue.todos,
      selectedTags: tags.toggle(tag),
      isLoading: stateValue.isLoading,
    ));
  }
}

Notice how FIC even provides a native .toggle(item) method directly on ISet and IList! Instead of writing repetitive tags.contains(tag) ? tags.remove(tag) : tags.add(tag) ternaries, FIC handles membership toggling internally with persistent structural sharing. And because Dart records compare their fields using value equality, any redundant emission is dropped synchronously by BlocSignal in 0ms!

Pattern 3: The Unbreakable Shopping Cart Showcase

Let us now engineer a complete, production-grade e-commerce shopping cart.

In enterprise applications, shopping carts are notorious bug magnets:

Users rapidly tap + and - quantity buttons, creating race conditions.
Items must be indexed by ID for instantaneous O(1) lookups and updates.
Total price and item count must be computed declaratively without manual tallying callbacks.
The cart must survive app restarts through offline persistence.
Users expect an "Undo Remove" action that must never corrupt previous state history.

Here is the complete domain model and CubitSignal implementation (you can explore and run the full Flutter application and test suite in the companion repository at examples/fic_shopping_cart on GitHub):

import 'package:bloc_signals/bloc_signals.dart';
import 'package:fast_immutable_collections/fast_immutable_collections.dart';
import 'package:flutter/foundation.dart';

/// Immutable domain item model using standard Dart value equality.
@immutable
class CartItem {
  const CartItem({
    required this.id,
    required this.title,
    required this.price,
    this.quantity = 1,
  });

  final String id;
  final String title;
  final double price;
  final int quantity;

  double get lineTotal => price * quantity;

  CartItem copyWith({int? quantity}) => CartItem(
    id: id,
    title: title,
    price: price,
    quantity: quantity ?? this.quantity,
  );

  @override
  bool operator ==(Object other) =>
      identical(this, other) ||
      other is CartItem &&
          runtimeType == other.runtimeType &&
          id == other.id &&
          title == other.title &&
          price == other.price &&
          quantity == other.quantity;

  @override
  int get hashCode => Object.hash(id, title, price, quantity);
}

/// Zero-boilerplate composite state using Dart 3 records and FIC IMap.
typedef ShoppingCartState = ({
  IMap<String, CartItem> items,
  String? promoCode,
  bool isCheckingOut,
});

Now, look at the ShoppingCartCubit. Notice how inline late final signals derive computed business metrics declaratively directly from the underlying immutable map:

Modern Dart 3.13 Syntax:

class ShoppingCartCubit() extends CubitSignal<ShoppingCartState> {
  this : super(
    initialState: (
      items: const IMap.empty(),
      promoCode: null,
      isCheckingOut: false,
    ),
  );

  // ✨ Declarative derived signals: computed once and cached lazily!
  late final subtotal = computed(() {
    return stateValue.items.values.fold(0.0, (sum, item) => sum + item.lineTotal);
  });

  late final totalItemCount = computed(() {
    return stateValue.items.values.fold(0, (sum, item) => sum + item.quantity);
  });

  late final isCartEmpty = computed(() {
    return stateValue.items.isEmpty;
  });

  void addItem(CartItem item) {
    final existing = stateValue.items[item.id];
    final updatedItem = existing != null
        ? existing.copyWith(quantity: existing.quantity + item.quantity)
        : item;

    emit((
      items: stateValue.items.add(item.id, updatedItem),
      promoCode: stateValue.promoCode,
      isCheckingOut: stateValue.isCheckingOut,
    ));
  }

  void updateQuantity(String itemId, int newQuantity) {
    if (newQuantity <= 0) {
      removeItem(itemId);
      return;
    }

    final existing = stateValue.items[itemId];
    if (existing == null || existing.quantity == newQuantity) return;

    emit((
      items: stateValue.items.add(itemId, existing.copyWith(quantity: newQuantity)),
      promoCode: stateValue.promoCode,
      isCheckingOut: stateValue.isCheckingOut,
    ));
  }

  void removeItem(String itemId) {
    if (!stateValue.items.containsKey(itemId)) return;

    emit((
      items: stateValue.items.remove(itemId),
      promoCode: stateValue.promoCode,
      isCheckingOut: stateValue.isCheckingOut,
    ));
  }

  void clearCart() {
    if (stateValue.items.isEmpty) return;

    emit((
      items: const IMap.empty(),
      promoCode: null,
      isCheckingOut: false,
    ));
  }
}

Traditional Dart 3.5 Baseline Syntax:

class ShoppingCartCubit extends CubitSignal<ShoppingCartState> {
  ShoppingCartCubit()
      : super(
          initialState: (
            items: const IMap.empty(),
            promoCode: null,
            isCheckingOut: false,
          ),
        );

  // ✨ Declarative derived signals: computed once and cached lazily!
  late final subtotal = computed(() {
    return stateValue.items.values.fold(0.0, (sum, item) => sum + item.lineTotal);
  });

  late final totalItemCount = computed(() {
    return stateValue.items.values.fold(0, (sum, item) => sum + item.quantity);
  });

  late final isCartEmpty = computed(() {
    return stateValue.items.isEmpty;
  });

  void addItem(CartItem item) {
    final existing = stateValue.items[item.id];
    final updatedItem = existing != null
        ? existing.copyWith(quantity: existing.quantity + item.quantity)
        : item;

    emit((
      items: stateValue.items.add(item.id, updatedItem),
      promoCode: stateValue.promoCode,
      isCheckingOut: stateValue.isCheckingOut,
    ));
  }

  void updateQuantity(String itemId, int newQuantity) {
    if (newQuantity <= 0) {
      removeItem(itemId);
      return;
    }

    final existing = stateValue.items[itemId];
    if (existing == null || existing.quantity == newQuantity) return;

    emit((
      items: stateValue.items.add(itemId, existing.copyWith(quantity: newQuantity)),
      promoCode: stateValue.promoCode,
      isCheckingOut: stateValue.isCheckingOut,
    ));
  }

  void removeItem(String itemId) {
    if (!stateValue.items.containsKey(itemId)) return;

    emit((
      items: stateValue.items.remove(itemId),
      promoCode: stateValue.promoCode,
      isCheckingOut: stateValue.isCheckingOut,
    ));
  }

  void clearCart() {
    if (stateValue.items.isEmpty) return;

    emit((
      items: const IMap.empty(),
      promoCode: null,
      isCheckingOut: false,
    ));
  }
}

Why This Architecture is "Unbreakable"

Zero Defensive Copying: When you add an item, items.add(id, item) updates an immutable trie node in O(log N) time. The rest of the map is reused without memory reallocations.
Instant Derived Math: The UI does not recalculate subtotals or item counts inside Widget.build(). The subtotal and totalItemCount signals evaluate lazily only when requested, caching their results until items changes.
Flawless Flutter Rebuilds: In your Flutter view, you read the cubit via context.read<ShoppingCartCubit>() and surgically bind the subtotal badge using SignalBuilder:

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

     @override
     Widget build(BuildContext context) {
       final cubit = context.read<ShoppingCartCubit>();

       return SignalBuilder(
         builder: (context) {
           final count = cubit.totalItemCount.value;
           return Badge(
             isLabelVisible: count > 0,
             label: Text('$count'),
             child: const Icon(Icons.shopping_bag_outlined),
           );
         },
       );
     }
   }

Updating the quantity of an item will re-evaluate totalItemCount, causing only the CartBadge widget to rebuild—leaving the rest of the checkout page untouched!

Pairing with `bloc_signals_hydrate` (Persistent Carts)

In production apps, the shopping cart must survive app terminations. Using package:bloc_signals_hydrate, adding persistence requires merely mixing in HydratedMixin and defining JSON mappings:

class HydratedCartCubit extends CubitSignal<ShoppingCartState>
    with HydratedMixin<ShoppingCartState> {
  HydratedCartCubit()
      : super(
          initialState: (
            items: const IMap.empty(),
            promoCode: null,
            isCheckingOut: false,
          ),
        ) {
    hydrate(); // Restores cached cart synchronously on startup!
  }

  @override
  Map<String, dynamic>? toJson(ShoppingCartState state) {
    return {
      'promoCode': state.promoCode,
      'items': state.items.unlock.map(
        (key, item) => MapEntry(key, {
          'id': item.id,
          'title': item.title,
          'price': item.price,
          'quantity': item.quantity,
        }),
      ),
    };
  }

  @override
  ShoppingCartState? fromJson(dynamic data) {
    // 🛡️ Robust first-level pattern matching: crash-proof schema validation!
    if (data case {'items': final Map<String, dynamic> rawItems}) {
      final restoredItems = <String, CartItem>{};

      for (final MapEntry(:key, :value) in rawItems.entries) {
        if (value case {
          'id': final String id,
          'title': final String title,
          'price': final num price,
          'quantity': final int quantity,
        }) {
          restoredItems[key] = CartItem(
            id: id,
            title: title,
            price: price.toDouble(),
            quantity: quantity,
          );
        }
      }

      return (
        items: restoredItems.lock,
        promoCode: data case {'promoCode': final String promo} ? promo : null,
        isCheckingOut: false,
      );
    }
    return null;
  }
}

Because state.items.unlock provides a read-only Dart map view without copying elements, serializing to SQLite, Hive, or shared preferences is completely seamless. Moreover, pairing fromJson(dynamic data) with Dart 3 pattern matching guarantees that corrupted or partial local disk caches never trigger runtime TypeError crashes on startup.

Pairing with `bloc_signals_replay` (Bulletproof Undo / Redo)

Now observe what happens when you want to provide an "Undo" feature when a customer accidentally swipes away an item:

class ReplayableCartCubit extends ReplayCubitSignal<ShoppingCartState> {
  ReplayableCartCubit()
      : super(
          initialState: (
            items: const IMap.empty(),
            promoCode: null,
            isCheckingOut: false,
          ),
        );

  void removeItem(String id) {
    emit((
      items: stateValue.items.remove(id),
      promoCode: stateValue.promoCode,
      isCheckingOut: stateValue.isCheckingOut,
    ));
  }
}

When the user taps "Undo" on a SnackBar:

cubit.undo();

Because stateValue.items is an immutable IMap, previous state snapshots in the ReplayCubitSignal history buffer were never mutated. Calling cubit.undo() restores the previous snapshot with 100% mathematical integrity. The history stack is physically uncorruptible!

Pattern 4: The One-Liner Zero-Mock Testing Secret

When writing unit tests for state machines that depend on collection repositories, developers frequently waste days setting up mocking frameworks like mockito or mocktail. They mock repository interfaces, stub return values, and write complex verifications.

With BlocSignal and fast_immutable_collections, testing becomes refreshingly direct. Because IList and IMap can be converted into reactive state containers in a single line using .toBlocSignal(), you can construct real, deterministic, immutable test fixtures without a single line of mock code:

// ✨ One-liner deterministic test fixture: zero mocks needed!
final testCartSignal = [item1, item2].lock.toBlocSignal();

Here is a complete, declarative unit test suite using package:bloc_signals_test:

import 'package:bloc_signals_test/bloc_signals_test.dart';
import 'package:fast_immutable_collections/fast_immutable_collections.dart';
import 'package:test/test.dart';

void main() {
  group('ShoppingCartCubit Architecture Tests', () {
    const book = CartItem(id: '1', title: 'Dart Handbook', price: 29.99);
    const keyboard = CartItem(id: '2', title: 'Mechanical Keyboard', price: 99.00);

    test('derived computed signals calculate subtotals and counts correctly', () {
      final cubit = ShoppingCartCubit();

      expect(cubit.isCartEmpty.value, isTrue);
      expect(cubit.subtotal.value, equals(0.0));
      expect(cubit.totalItemCount.value, equals(0));

      cubit.addItem(book);

      expect(cubit.isCartEmpty.value, isFalse);
      expect(cubit.subtotal.value, equals(29.99));
      expect(cubit.totalItemCount.value, equals(1));

      // Adding the same item increments quantity rather than duplicating map keys
      cubit.addItem(book);
      expect(cubit.totalItemCount.value, equals(2));
      expect(cubit.subtotal.value, equals(59.98));
    });

    blocSignalTest<ShoppingCartCubit, ShoppingCartState>(
      'synchronously drops duplicate quantity updates in 0ms',
      build: () => ShoppingCartCubit(),
      seed: () => (
        items: IMap({'1': book}),
        promoCode: null,
        isCheckingOut: false,
      ),
      act: (cubit) {
        // Setting the exact same quantity that already exists:
        cubit.updateQuantity('1', 1);
      },
      // Because IMap equality evaluates as identical, zero transitions emit!
      expect: () => <ShoppingCartState>[],
    );

    blocSignalTest<ShoppingCartCubit, ShoppingCartState>(
      'removes item cleanly and updates state',
      build: () => ShoppingCartCubit(),
      seed: () => (
        items: IMap({'1': book, '2': keyboard}),
        promoCode: null,
        isCheckingOut: false,
      ),
      act: (cubit) => cubit.removeItem('1'),
      expect: () => [
        (
          items: IMap({'2': keyboard}),
          promoCode: null,
          isCheckingOut: false,
        ),
      ],
    );
  });
}

Notice what just happened in the de-duplication test:

We seeded the cubit with a state containing book with quantity 1.
We called updateQuantity('1', 1).
cubit.updateQuantity attempted to emit an identical state.
blocSignalTest asserted that zero transitions occurred (expect: () => []).

All of this executed synchronously in 0ms without waiting for microtask queues or timer intervals!

Architectural Comparison Table

To understand why pairing BlocSignal with fast_immutable_collections represents such a leap forward in Flutter architecture, consider how it compares to traditional approaches:

Architectural Metric	Standard `List` / `Map`	`Equatable` + `List`	`freezed` + `List`	`BlocSignal` + FIC (`IList` / `IMap`)
Value Equality (`==`)	❌ Reference identity only	⚠️ Manual `props` definition	✅ Generated in `.freezed.dart`	✅ Automatic out of the box
In-Place Mutation Defense	❌ None (accidental mutations pass)	❌ None (runtime mutable)	⚠️ Unmodifiable wrapper (runtime crash)	✅ Enforced by type system at compile-time
Code Generation Overhead	✅ None	✅ None	❌ Heavy (`build_runner` required)	✅ Zero (`build_runner` free)
Mutation Performance	❌ O(N) full defensive copy	❌ O(N) full defensive copy	❌ O(N) full defensive copy	✅ O(1) / O(log N) structural sharing
Garbage Collection (GC) Pressure	❌ High (allocates N items per change)	❌ High (allocates N items per change)	❌ High (allocates N items per change)	✅ Near-zero (tree node sharing)
Time-Travel / Undo Safety	❌ Corrupts historical stack	❌ Corrupts historical stack	⚠️ Requires deep cloning	✅ 100% mathematically safe
Synchronous 0ms De-duplication	❌ Fails (triggers ghost or redundant rebuilds)	⚠️ Works if `props` are maintained	✅ Works	✅ Instantaneous 0ms frame-0 drop

Conclusion: Composition Over Framework Monoliths

In the early days of Flutter, solving collection state bugs required bringing in heavy, monolithic code generation tools like freezed or writing endless boilerplate with Equatable.

Modern Dart and BlocSignal show us a better way forward. By composing focused, specialized, pure Dart tools:

BlocSignal provides unidirectional data flow, frame-0 synchronous propagation, and enterprise observer tracing.
fast_immutable_collections provides structural sharing, compile-time immutability, and instant value equality.
Dart 3 Records provide zero-ceremony composite state types with automatic structural equality.

You get an unbreakable, 120 FPS reactive architecture with zero code generation, zero macro dependencies, and zero runtime reflection.

Try replacing a mutable List with an IList in your next Flutter feature—your UI, your undo stack, and your garbage collector will thank you!

🔗 Resources & Getting Started

📦 bloc_signals on pub.dev: pub.dev/packages/bloc_signals
📦 fast_immutable_collections on pub.dev: pub.dev/packages/fast_immutable_collections
🌐 Official Documentation & Recipes: blocsignal.dev
🐙 GitHub Repository: github.com/RandalSchwartz/BlocSignal
🛒 Worked Example on GitHub: github.com/RandalSchwartz/BlocSignal/tree/main/examples/fic_shopping_cart

Beyond Clean Architecture: The Iceberg Pattern for Real-Time Flutter Apps with BlocSignal

Randal L. Schwartz — Sat, 05 Sep 2026 02:42:20 +0000

Why Traditional Clean Architecture Stalls in Real-Time Cloud Apps

Most enterprise Flutter tutorials preach Uncle Bob's Clean Architecture or classic BLoC layering. They show neat diagrams with concentric circles: Presentation, Use Cases / Interactors, Repositories, and Data Sources.

Yet nearly every one of those tutorials demonstrates the architecture exclusively with static REST request-response endpoints or trivial counter apps.

The moment you build a modern, datastore-backed application—powered by Firebase Cloud Firestore, Supabase, or real-time WebSockets—traditional Clean Architecture rapidly deteriorates into one of two anti-patterns:

The "Anemic Lasagna" Trap: Layers of pass-through classes (Controller.get() ➔ UseCase.execute() ➔ Repository.fetch() ➔ DataSource.get()) that merely forward method invocations to the layer below without transforming data, encapsulating invariants, or providing architectural protection. You end up writing 4 files, 3 interfaces, and 20 lines of ceremonial glue for a single read operation.
Stream & Microtask Spaghetti: Trying to synchronize multiple live cloud streams (collection.snapshots(), authStateChanges(), local search text inputs) using intricate Rx pipelines (combineLatest3, switchMap), nested subscriptions, manual lifecycle cancellations, and race-condition-prone state flags.

Classical "Clean" REST Layering (Anemic Lasagna):
UI ➔ Interactor ➔ Repository ➔ DataSource ➔ REST API (Pull-only, High Ceremony)

Real-Time Cloud Reality:
Firebase / Supabase ➔ Live Stream ➔ ??? ➔ Flutter UI (Push-heavy, Async Glitches)

The Iceberg Pattern solves this dilemma. By establishing a collaborative boundary between fine-grained reactive signals and unidirectional BLoC facades, the Iceberg Pattern gives real-time Flutter apps:

Submerged, warm data caching that outlives transient screen navigations
0ms frame-perfect optimistic mutations with automatic server reconciliation and rollback
Screen-scoped facades with zero pass-through ceremony
100% synchronous UI rendering with zero StreamBuilder or FutureBuilder latency

🏛️ The 4-Layer Architecture (Zero Pass-Throughs)

In the Iceberg Pattern, every layer has a distinct lifecycle, operates on different data structures, and addresses an indispensable, non-overlapping responsibility:

┌────────────────────────────────────────────────────────────────────────┐
│                      1. PRESENTATION LAYER (FLUTTER)                   │
│   • Lifecycle: Transient render passes                                 │
│   • Responsibilities: Pure synchronous projection (UI = ƒ(State))      │
│   • BlocSignalBuilder for UI rendering; BlocSignalListener for toasts  │
│   • Non-blocking banner when hasSyncError == true (Stale-While-Reval)  │
└───────────────────────────────────▲────────────────────────────────────┘
                                    │ Projects State & Forwards Errors
┌───────────────────────────────────┴────────────────────────────────────┐
│                  2. APPLICATION FACADE (TaskBoardCubit)                │
│   • Lifecycle: Screen-scoped (created on push, disposed on pop)        │
│   • Responsibilities: View-specific filtering, sorting, & search       │
│   • Ephemeral interaction tracking (for example isDeletingTaskId)      │
│   • Error translation: Catches repository sync errors ➔ onError()      │
└───────────────────────────────────▲────────────────────────────────────┘
                                    │ Observes ReadonlySignal<List<Task>>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~│~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~ WATERLINE (SURFACE LEVEL) ~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~│~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
┌───────────────────────────────────┴────────────────────────────────────┐
│             3. DOMAIN ENGINE & CACHE (TaskRepository)                  │
│   • Lifecycle: App/Session-scoped (survives screen navigation)         │
│   • Responsibilities: Async-to-sync collapse via private signals       │
│   • Data normalization: Maps cloud DTOs to pure Dart 3 records         │
│   • Global optimistic mutation engine with automatic rollback          │
│   • Public Edge: Exposes ReadonlySignal<List<Task>> & hasSyncError     │
└───────────────────────────────────▲────────────────────────────────────┘
                                    │ Live Snapshots & Background Writes
┌───────────────────────────────────┴────────────────────────────────────┐
│                    4. EXTERNAL DATASTORE (FIREBASE / CLOUD)            │
│   • Lifecycle: Remote cloud persistence & server security rules        │
│   • Raw asynchronous event streams (collection.snapshots())            │
└────────────────────────────────────────────────────────────────────────┘

Notice the waterline:

Above the waterline (Visible): Flutter presentation widgets and the screen-scoped TaskBoardCubit. They only know about synchronous state snapshots and user intents.
Below the waterline (Submerged): The TaskRepository engine. It absorbs asynchronous cloud streams, collapses them into fine-grained reactive signals, coordinates optimistic mutations, and handles silent rollback upon network rejection.

📋 Locked-In Architectural Decisions

Decision Area	Architectural Choice	Rationale & Impact
Engine Scope	Repository-Scoped	The repository owns the live datastore stream and in-memory cache. Data remains warm and active across route pushes and pops without redundant network queries.
Domain Model	Dart 3 Records	`typedef Task = ({String id, String title, bool isCompleted, List<String> tags});` Zero class ceremony, structural equality out of the box, pattern matching ready.
Optimistic Scope	Repository-Level	Multi-screen consistency: toggling a task on a detail view is reflected synchronously on summary dashboards and widgets in frame 0.
Repo Boundary	ReadonlySignal	The repository keeps writable signals strictly private (`_`), exposing only `ReadonlySignal<List<Task>>` and `ReadonlySignal<bool>` to consumers.
Mutation Strategies	Dual-Track	Optimistic: 0ms local mutation + background write + rollback on failure. Pessimistic: Screen tracks `isDeletingTaskId` spinner while awaiting cloud deletion confirmation.
Rollback UX	Silent Snapback + Toast	State silently snaps back to server truth; failure notifications route via `CubitSignal.onError` to a SnackBar. Domain models stay pure.
Cloud Resilience	Stale-While-Revalidate	Never replace user data with a red error box on transient disconnects. Keep cached data visible with a non-blocking warning banner.
Platform Target	Pure Dart First	Models, Repository, and Cubit are pure Dart—runnable on CLI, Jaspr web, server backend, or Flutter. Tested via `blocSignalTest`.

🛠️ The Reference Implementation

Let us walk through each component of the architecture using the official reference implementation from examples/iceberg_pattern.

1. The Domain Model: Zero-Ceremony Dart 3 Records

Instead of writing 60 lines of boilerplate with copyWith, props, and constructor overrides, we model domain entities as lightweight, immutable Dart 3 records:

// domain/task.dart
typedef Task = ({
  String id,
  String title,
  bool isCompleted,
  List<String> tags,
});

Dart 3 records provide built-in structural equality, clean destructuring, and pattern matching without any code generation or external runtime dependencies.

2. The Submerged Engine: `TaskRepository`

The repository is the heart of the Iceberg Pattern:

It absorbs the raw cloud snapshot stream into a private StreamSignal.
It maintains private optimistic overrides (_optimisticPatches).
It computes the combined view of server truth and pending local mutations via computed().
It atomically reconciles or rolls back mutations using batch().

// data/task_repository.dart
import 'dart:async';
import 'package:signals_core/signals_core.dart';
import 'package:iceberg_pattern_example/domain/task.dart';

class SyncRollbackException implements Exception {
  SyncRollbackException(this.message, [this.cause]);
  final String message;
  final Object? cause;

  @override
  String toString() => 'SyncRollbackException: $message';
}

class TaskRepository {
  TaskRepository({
    required Stream<List<Task>> cloudSnapshotStream,
    required Future<void> Function(String id, bool isCompleted) updateCloudTask,
    required Future<void> Function(String id) deleteCloudTask,
    List<Task> initialTasks = const [],
  })  : _updateCloudTask = updateCloudTask,
        _deleteCloudTask = deleteCloudTask {
    _initEngine(cloudSnapshotStream, initialTasks);
  }

  final Future<void> Function(String id, bool isCompleted) _updateCloudTask;
  final Future<void> Function(String id) _deleteCloudTask;

  // Private Reactive Graph
  late final StreamSignal<List<Task>> _cloudStreamSignal;
  final _optimisticPatches = signal<Map<String, bool>>({});
  final _hasSyncError = signal(false);
  late final Computed<List<Task>> _computedTasks;

  void _initEngine(
    Stream<List<Task>> cloudSnapshotStream,
    List<Task> initialTasks,
  ) {
    _cloudStreamSignal = streamSignal(
      () => cloudSnapshotStream,
      options: AsyncSignalOptions<List<Task>>(initialValue: initialTasks),
    );

    _computedTasks = computed(() {
      final baseTasks = _cloudStreamSignal.value.value ?? const [];
      final overrides = _optimisticPatches.value;
      if (overrides.isEmpty) return baseTasks;

      return baseTasks.map((task) {
        final override = overrides[task.id];
        return override != null
            ? (
                id: task.id,
                title: task.title,
                isCompleted: override,
                tags: task.tags,
              )
            : task;
      }).toList();
    });
  }

  // Public Read-Only Boundaries
  ReadonlySignal<List<Task>> get tasks => _computedTasks;
  ReadonlySignal<bool> get hasSyncError => _hasSyncError;

  /// OPTIMISTIC MUTATION: Updates state across all screens in 0ms,
  /// then synchronizes with the cloud in the background.
  Future<void> toggleTask(String id, bool currentStatus) async {
    final newStatus = !currentStatus;
    _optimisticPatches.value = {..._optimisticPatches.value, id: newStatus};

    try {
      await _updateCloudTask(id, newStatus);
      // Reconcile: clear override once the cloud confirms
      batch(() {
        _hasSyncError.value = false;
        final updated = Map<String, bool>.from(_optimisticPatches.value)
          ..remove(id);
        _optimisticPatches.value = updated;
      });
    } catch (error, stackTrace) {
      // Rollback: silently remove patch and notify caller
      batch(() {
        final updated = Map<String, bool>.from(_optimisticPatches.value)
          ..remove(id);
        _optimisticPatches.value = updated;
        _hasSyncError.value = true;
      });
      Error.throwWithStackTrace(
        SyncRollbackException('Failed to update task $id. Reverted.', error),
        stackTrace,
      );
    }
  }

  /// PESSIMISTIC MUTATION: Awaits server confirmation before resolving.
  Future<void> deleteTask(String id) async {
    await _deleteCloudTask(id);
  }

  void dispose() {
    _cloudStreamSignal.dispose();
    _optimisticPatches.dispose();
    _hasSyncError.dispose();
    _computedTasks.dispose();
  }
}

3. The Visible Boundary: `TaskBoardCubit`

The application facade is screen-scoped. When a screen mounts, it creates a TaskBoardCubit. When the screen is popped, the Cubit is closed and its effects are disposed.

The Cubit:

Filters or sorts tasks specifically for this view without mutating the repository.
Tracks ephemeral UI state (for example which row is currently displaying a deletion spinner).
Translates repository exceptions into BLoC's standard onError pipeline.

// application/task_board_cubit.dart
import 'dart:async';
import 'package:bloc_signals/bloc_signals.dart';
import 'package:signals_core/signals_core.dart';
import 'package:iceberg_pattern_example/data/task_repository.dart';
import 'package:iceberg_pattern_example/domain/task.dart';

typedef TaskBoardState = ({
  List<Task> tasks,
  String? activeFilterTag,
  String? isDeletingTaskId,
  bool hasSyncError,
});

class TaskBoardCubit extends CubitSignal<TaskBoardState> {
  TaskBoardCubit({required TaskRepository repository})
      : _repository = repository,
        super(
          initialState: (
            tasks: repository.tasks.value,
            activeFilterTag: null,
            isDeletingTaskId: null,
            hasSyncError: repository.hasSyncError.value,
          ),
        ) {
    _initFacade();
  }

  final TaskRepository _repository;
  final _activeFilterTag = signal<String?>(null);
  final _isDeletingTaskId = signal<String?>(null);
  late final void Function() _disposeEffect;

  void _initFacade() {
    final computedState = computed(() {
      final allTasks = _repository.tasks.value;
      final filter = _activeFilterTag.value;

      final filteredTasks = filter == null
          ? allTasks
          : allTasks.where((t) => t.tags.contains(filter)).toList();

      return (
        tasks: filteredTasks,
        activeFilterTag: filter,
        isDeletingTaskId: _isDeletingTaskId.value,
        hasSyncError: _repository.hasSyncError.value,
      );
    });

    _disposeEffect = computedState.subscribe(emit);
  }

  void setFilterTag(String? tag) => _activeFilterTag.value = tag;

  /// Dispatches optimistic toggle; forwards failure to onError for SnackBar display.
  void toggleTask(String id, bool currentStatus) {
    unawaited(
      _repository.toggleTask(id, currentStatus).catchError(
        (Object error, StackTrace st) {
          onError(error, st);
        },
      ),
    );
  }

  /// Dispatches pessimistic delete; tracks row-level spinner in screen state.
  Future<void> deleteTask(String id) async {
    _isDeletingTaskId.value = id;
    try {
      await _repository.deleteTask(id);
    } catch (error, stackTrace) {
      onError(error, stackTrace);
    } finally {
      _isDeletingTaskId.value = null;
    }
  }

  @override
  Future<void> close() async {
    _disposeEffect();
    _activeFilterTag.dispose();
    _isDeletingTaskId.dispose();
    await super.close();
  }
}

4. Pure Synchronous Presentation Binding

In Flutter, the presentation layer becomes a direct synchronous projection of state: UI = ƒ(State). There are no StreamBuilder widgets, no connection state checks, and no microtask latency:

// presentation/task_board_screen.dart
import 'package:bloc_signals_flutter/bloc_signals_flutter.dart';
import 'package:flutter/material.dart';
import 'package:iceberg_pattern_example/application/task_board_cubit.dart';

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

  @override
  Widget build(BuildContext context) {
    return BlocSignalListener<TaskBoardCubit, TaskBoardState>(
      listenWhen: (previous, current) =>
          !previous.hasSyncError && current.hasSyncError,
      listener: (context, state) {
        if (state.hasSyncError) {
          ScaffoldMessenger.of(context).showSnackBar(
            const SnackBar(
              content: Text('Sync failed: Reverted to server truth.'),
              backgroundColor: Colors.redAccent,
            ),
          );
        }
      },
      child: BlocSignalBuilder<TaskBoardCubit, TaskBoardState>(
        builder: (context, state) {
          return Scaffold(
            appBar: AppBar(
              title: const Text('Tasks (The Iceberg Pattern)'),
              bottom: state.hasSyncError
                  ? const PreferredSize(
                      preferredSize: Size.fromHeight(28),
                      child: ColoredBox(
                        color: Colors.amber,
                        child: Center(
                          child: Text(
                            'Offline / Sync Error — Showing Cached Tasks',
                            style: TextStyle(fontWeight: FontWeight.w600, fontSize: 13),
                          ),
                        ),
                      ),
                    )
                  : null,
            ),
            body: Column(
              children: [
                // Category Filter Chips
                Padding(
                  padding: const EdgeInsets.all(8),
                  child: Row(
                    children: [
                      FilterChip(
                        label: const Text('All'),
                        selected: state.activeFilterTag == null,
                        onSelected: (_) =>
                            context.read<TaskBoardCubit>().setFilterTag(null),
                      ),
                      const SizedBox(width: 8),
                      FilterChip(
                        label: const Text('Work'),
                        selected: state.activeFilterTag == 'work',
                        onSelected: (_) =>
                            context.read<TaskBoardCubit>().setFilterTag('work'),
                      ),
                    ],
                  ),
                ),
                // Task List
                Expanded(
                  child: ListView.builder(
                    itemCount: state.tasks.length,
                    itemBuilder: (context, index) {
                      final task = state.tasks[index];
                      final isDeleting = state.isDeletingTaskId == task.id;

                      return ListTile(
                        leading: Checkbox(
                          value: task.isCompleted,
                          onChanged: isDeleting
                              ? null
                              : (_) => context
                                  .read<TaskBoardCubit>()
                                  .toggleTask(task.id, task.isCompleted),
                        ),
                        title: Text(
                          task.title,
                          style: TextStyle(
                            decoration: task.isCompleted
                                ? TextDecoration.lineThrough
                                : null,
                          ),
                        ),
                        trailing: isDeleting
                            ? const SizedBox.square(
                                dimension: 20,
                                child: CircularProgressIndicator(strokeWidth: 2),
                              )
                            : IconButton(
                                icon: const Icon(Icons.delete_outline),
                                onPressed: () => context
                                    .read<TaskBoardCubit>()
                                    .deleteTask(task.id),
                              ),
                      );
                    },
                  ),
                ),
              ],
            ),
          );
        },
      ),
    );
  }
}

🧪 Declarative Unit Testing with `blocSignalTest`

Because Models, Repository, and Cubit are pure Dart, you can verify every aspect of this architecture without spinning up a Flutter test environment or mocking complex platform channels:

// test/task_board_architecture_test.dart
import 'dart:async';
import 'package:bloc_signals_test/bloc_signals_test.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:iceberg_pattern_example/application/task_board_cubit.dart';
import 'package:iceberg_pattern_example/data/task_repository.dart';
import 'package:iceberg_pattern_example/domain/task.dart';

void main() {
  group('The Iceberg Pattern Architecture Test Suite', () {
    late StreamController<List<Task>> cloudController;
    late TaskRepository repository;

    setUp(() {
      cloudController = StreamController<List<Task>>.broadcast();
    });

    tearDown(() {
      repository.dispose();
      cloudController.close();
    });

    // 1. Initial Stream Sync Test
    blocSignalTest<TaskBoardCubit, TaskBoardState>(
      'emits updated task list synchronously upon cloud stream emission',
      build: () {
        repository = TaskRepository(
          cloudSnapshotStream: cloudController.stream,
          updateCloudTask: (_, __) async {},
          deleteCloudTask: (_) async {},
        );
        return TaskBoardCubit(repository: repository);
      },
      act: (_) {
        cloudController.add([
          (id: '1', title: 'Write Article', isCompleted: false, tags: ['work']),
        ]);
      },
      wait: const Duration(milliseconds: 10),
      expect: () => [
        equalsTaskBoardState((
          tasks: [(id: '1', title: 'Write Article', isCompleted: false, tags: ['work'])],
          activeFilterTag: null,
          isDeletingTaskId: null,
          hasSyncError: false,
        )),
      ],
    );

    // 2. The 0ms Optimistic Test (emits before cloud completes)
    blocSignalTest<TaskBoardCubit, TaskBoardState>(
      'emits optimistic completed status in 0ms before cloud write finishes',
      build: () {
        final completer = Completer<void>();
        repository = TaskRepository(
          cloudSnapshotStream: cloudController.stream,
          updateCloudTask: (_, __) => completer.future, // Hanging future
          deleteCloudTask: (_) async {},
          initialTasks: [
            (id: '1', title: 'Test Task', isCompleted: false, tags: const <String>[]),
          ],
        );
        return TaskBoardCubit(repository: repository);
      },
      act: (cubit) => cubit.toggleTask('1', false),
      expect: () => [
        equalsTaskBoardState((
          tasks: [(id: '1', title: 'Test Task', isCompleted: true, tags: const <String>[])],
          activeFilterTag: null,
          isDeletingTaskId: null,
          hasSyncError: false,
        )),
      ],
    );

    // 3. The Rollback & Error Test (reverts state and routes to onError)
    blocSignalTest<TaskBoardCubit, TaskBoardState>(
      'silently rolls back state and triggers onError on cloud rejection',
      build: () {
        repository = TaskRepository(
          cloudSnapshotStream: cloudController.stream,
          updateCloudTask: (_, __) async => throw Exception('Cloud network timeout'),
          deleteCloudTask: (_) async {},
          initialTasks: [
            (id: '1', title: 'Test Task', isCompleted: false, tags: const <String>[]),
          ],
        );
        return TaskBoardCubit(repository: repository);
      },
      act: (cubit) => cubit.toggleTask('1', false),
      wait: const Duration(milliseconds: 15),
      expect: () => [
        // Frame 1: Optimistic toggle
        equalsTaskBoardState((
          tasks: [(id: '1', title: 'Test Task', isCompleted: true, tags: const <String>[])],
          activeFilterTag: null,
          isDeletingTaskId: null,
          hasSyncError: false,
        )),
        // Frame 2: Silent rollback to server truth + hasSyncError: true
        equalsTaskBoardState((
          tasks: [(id: '1', title: 'Test Task', isCompleted: false, tags: const <String>[])],
          activeFilterTag: null,
          isDeletingTaskId: null,
          hasSyncError: true,
        )),
      ],
      errors: () => [
        isA<SyncRollbackException>(),
      ],
    );
  });
}

🎯 Summary

The Iceberg Pattern gives developers a principled path past the limitations of traditional Clean Architecture in modern real-time apps:

Collapse Asynchrony Early: Quarantining live streams to the submerged repository engine shields your entire presentation layer from microtask latency and stream lifecycle leaks.
Dual-Track Mutations: Use 0ms optimistic updates for rapid, reversible interactions (like toggling a checkbox) and pessimistic updates for destructive or irreversible actions (like deleting a resource).
Stale-While-Revalidate UX: Avoid flash-of-error screens. Keep cached data visible with a subtle banner while the background engine recovers connection truth.
Pure Dart Portability: When domain models and state machines have zero platform or widget dependencies, your core application logic runs and tests at native speed across Flutter, Jaspr web, and backend services.

When you step back and look at the completed architecture, notice what has completely disappeared:

❌ No Anemic Use Cases: Zero 3-line pass-through interactors doing nothing but forwarding calls to a repository.
❌ No StreamBuilder or FutureBuilder Widgets: Zero async builders in your Flutter widget tree; UI is 100% synchronous projection (UI = ƒ(State)).
❌ No Microtask Frame Lag: Zero waiting for asynchronous stream queues to cycle; state updates propagate synchronously in frame 0.
❌ No Torn UI States: Atomic transitions via batch() prevent intermediate partial states during optimistic reconciliation and rollback.
❌ No Disruptive Error Flickers: Stale-while-revalidate caching keeps data visible with a subtle banner instead of replacing the screen with a full-page error widget.
❌ No Boilerplate Model Classes: Pure Dart 3 records replace hundreds of lines of tedious copyWith, props, and code-generation ceremony.

Resources & Companion Code

💻 Full Runnable Example: examples/iceberg_pattern on GitHub
📦 bloc_signals on pub.dev
📦 bloc_signals_flutter on pub.dev
🌐 Official Documentation Hub: blocsignal.dev
🌟 GitHub Repository: RandalSchwartz/BlocSignal

Taming Flutter Infinite Scroll (Part 2): Turning ScrollController into a Reactive State Machine with CubitSignalMixin

Randal L. Schwartz — Thu, 03 Sep 2026 17:31:52 +0000

The Infinite Scroll Rite of Passage

In Part 1: Taming Flutter Infinite Scroll: Why 3 Lines of async* Missed the Point, and How BlocSignal Fixes It, we explored why wrapping mutable state in async* generators and StreamIterator cracks under pressure when users rapidly fling a list. We demonstrated how BlocSignal’s streamless droppable() transformer solves thumb-flinging race conditions synchronously at the event boundary without Rx streams or microtask lag.

Yet, even after solving event concurrency with a pure BLoC, many Flutter developers are left with a nagging architectural itch.

Search pub.dev for "infinite scroll" or "pagination", and you will find dozens of packages—infinite_scroll_pagination, lazy_load_scrollview, flutter_pagewise, loadmore. It is practically a rite of passage for every Flutter developer to install at least one of them.

Why do these packages exist in such numbers?

Because implementing pagination with standard Flutter controllers requires tedious widget-level plumbing:

Creating a StatefulWidget.
Instantiating and maintaining an instance of ScrollController.
Subscribing to scroll metrics with _scrollController.addListener(_onScroll) in initState.
Remembering to call removeListener and _scrollController.dispose() in dispose().
Manually calculating viewport extents (offset >= maxScrollExtent * 0.9).
Gluing the scroll trigger to a state management call (context.read<PostsBloc>().add(...)).

Unfortunately, the third-party pagination packages on pub.dev often extract a heavy architectural tax:

They hijack your widget tree: They force you to replace standard Flutter widgets with proprietary wrappers like PagedListView, fighting your slivers, custom scroll physics, and layout styling.
They invent competing controllers: They introduce bespoke paging controllers alongside your existing BLoCs or Notifiers, creating two competing sources of truth that you must manually synchronize.
They attempt to solve concurrency in the UI: They try to debounce or guard fetch requests inside widget lifecycle callbacks instead of at the architectural event boundary.

What if you did not need a third-party pagination package at all? What if Flutter's standard ScrollController could itself be your reactive state container?

Let us examine why that was historically impossible in Dart—and how composable mixins change everything.

🧱 Dart's Single-Inheritance Wall

Why couldn't Flutter's ScrollController just extend BlocSignal or CubitSignal?

In Dart, a class can extend only one superclass.

Flutter's ScrollController extends ChangeNotifier (which implements Listenable). If you want a class to also be a CubitSignal or BlocSignal, Dart's single-inheritance constraint stops you dead in your tracks:

// ❌ Impossible in Dart (Multiple inheritance is forbidden):
class PaginatedPostsController extends ScrollController, BlocSignal<PostsEvent, PostsState> {
  // Dart analyzer error: Each class can have only one superclass.
}

Historically, this constraint forced developers into two unsatisfying compromises:

The Proxy / Wrapper Anti-Pattern: Creating a wrapper class that held an internal _bloc reference, requiring tedious method forwarding and lifecycle delegation.
The Dual-Lifecycle Trap: Managing a ScrollController and a PostsBloc as separate objects in the widget tree, gluing them together with initState listeners and cleaning both up in dispose().

With CubitSignalMixin and BlocSignalMixin in bloc_signals, that single-inheritance wall is demolished.

🧬 How Composable Mixins Break the Wall

Because BlocSignal has a minimal, highly disciplined API contract, mixing it into arbitrary classes introduces zero namespace collisions:

┌────────────────────────────────────────────────────────────────────────┐
│                        BlocSignal Mixin Architecture                   │
├────────────────────────────────┬───────────────────────────────────────┤
│ Mixin                          │ Capabilities Added                    │
├────────────────────────────────┼───────────────────────────────────────┤
│ CubitSignalMixin<StateType>    │ state, stateValue, emit(newState),    │
│                                │ equals(), createEffect(), close()     │
├────────────────────────────────┼───────────────────────────────────────┤
│ BlocSignalMixin<Event, State>  │ on<E>(), concurrency transformers     │
│                                │ (droppable, restartable), add(event)  │
└────────────────────────────────┴───────────────────────────────────────┘

When a class adopts CubitSignalMixin<StateType>, it implements BlocSignalBase<StateType>. It gains:

0ms synchronous reactive signals (state).
Direct synchronous state value access (stateValue).
Automatic de-duplication (emit(newState) drops transitions when newState == currentState).
Reactive observer tracking and lifecycle management.

And when combined with BlocSignalMixin<Event, StateType>, it gains full event-driven execution with streamless transformers like droppable() and restartable().

This unlocks two clean architectural patterns for infinite scroll.

📐 Pattern A: The Reactive `PagingScrollController` (Separation of Concerns)

If your architectural philosophy demands that your domain business logic remain 100% pure Dart (with zero imports of package:flutter/widgets.dart), you can turn ScrollController into a focused, reactive boolean signal:

import 'package:bloc_signals/bloc_signals.dart';
import 'package:flutter/widgets.dart';

/// A ScrollController that is also a CubitSignal emitting whether 
/// the scroll viewport is within [threshold] pixels of the bottom.
class PagingScrollController extends ScrollController 
    with CubitSignalMixin<bool> {
  PagingScrollController({this.threshold = 200.0}) {
    // 1. Initialize the CubitSignalMixin with initial state
    initCubitSignal(initialState: false);

    // 2. Listen to scroll metrics internally
    addListener(_onScrollChanged);
  }

  /// Remaining scroll extent threshold in logical pixels (default: 200.0).
  final double threshold;
  bool _isControllerDisposed = false;

  void _onScrollChanged() {
    if (!hasClients) return;
    // position.extentAfter returns the exact remaining pixels after the viewport!
    final isNearBottom = position.extentAfter <= threshold;

    // 3. emit() automatically de-duplicates:
    // Only triggers subscribers when the boolean flips between false and true!
    emit(isNearBottom);
  }

  @override
  void dispose() {
    if (_isControllerDisposed) return;
    _isControllerDisposed = true;
    removeListener(_onScrollChanged);
    close();
    super.dispose();
  }

  @override
  Future<void> close() async {
    if (!_isControllerDisposed) {
      _isControllerDisposed = true;
      removeListener(_onScrollChanged);
      super.dispose();
    }
    await super.close();
  }
}

💡 The `extentAfter` Secret: Why Pixels Beat Percentages

Notice line 20:

final isNearBottom = position.extentAfter <= threshold;

Most Flutter pagination tutorials write something like:

// ⚠️ The percentage trap:
final isBottom = offset >= maxScrollExtent * 0.9;

Calculating a percentage (such as 0.9) creates an erratic user experience:

On a short list of 1,000 pixels, 90% triggers when you are 100 pixels from the bottom.
On a long list of 50,000 pixels, 90% triggers when you are 5,000 pixels from the bottom—downloading pages far in advance that the user may never scroll to!

Flutter's ScrollPosition.extentAfter returns the exact quantity of content in logical pixels remaining after the viewport's trailing edge (math.max(maxScrollExtent - pixels, 0.0)).

Using position.extentAfter <= 200.0:

Provides a consistent lead time: You always start fetching the next page when the user is ~2 items away from the bottom, regardless of whether the list has 10 items or 10,000 items.
Eliminates calculation boilerplate: No multiplying maxScrollExtent * 0.9, no reading offset, and no bounds-checking when a list is empty. It is a single, clean comparison.

The Superpower of Automatic De-duplication

Notice line 27: emit(isNearBottom);.

As a user scrolls vigorously near the bottom, scroll notifications fire dozens of times across 91%, 93%, 97%, and 99% of the viewport. In naive Flutter code, this requires manual boolean guards to prevent triggering duplicate actions.

With CubitSignalMixin, de-duplication is automatic. Because emit() checks newState == currentState, calling emit(true) twenty times in a row produces zero spurious signal updates. The signal fires exactly once when crossing the threshold downward, and exactly once when scrolling back upward!

Connecting this to your domain PostsBloc requires just a single declarative effect:

pagingController.createEffect(() {
  if (pagingController.stateValue) {
    postsBloc.add(const PostsFetched());
  }
});

The domain BLoC remains completely independent of Flutter, while the widget avoids doing manual scroll extent arithmetic.

⚡ Pattern B: The Self-Paging Domain Controller (Zero-Bridge Architecture)

Now, let us take the architectural leap.

What if you do not want a separate controller, a separate BLoC, and glue code between them? What if your controller is the ScrollController, and your controller is the BlocSignal?

Here is PaginatedPostsController:

import 'dart:async';

import 'package:bloc_signals/bloc_signals.dart';
import 'package:flutter/widgets.dart';
import '../models/post.dart';

class PaginatedPostsController extends ScrollController
    with
        CubitSignalMixin<PostsState>,
        BlocSignalMixin<PostsEvent, PostsState> {
  PaginatedPostsController({
    this.threshold = 200.0,
    required PostRepository repository,
  }) : _repository = repository {
    // 1. Initialize CubitSignal state
    initCubitSignal(initialState: const PostsState());

    // 2. Streamless concurrency: drop overlapping scroll triggers
    on<PostsFetched>(
      _onPostsFetched,
      transformer: droppable(),
    );

    // 3. Streamless concurrency: cancel and restart on search query change
    on<PostsSearchChanged>(
      _onPostsSearchChanged,
      transformer: restartable(),
    );

    // 4. Controller listens to its own scroll geometry!
    addListener(_onScrollChanged);
  }

  /// Remaining scroll extent threshold in logical pixels (default: 200.0).
  final double threshold;
  final PostRepository _repository;
  bool _isControllerDisposed = false;

  void _onScrollChanged() {
    if (!hasClients) return;
    // Single, clean extentAfter check:
    if (position.extentAfter <= threshold) {
      add(const PostsFetched());
    }
  }

  Future<void> _onPostsFetched(
    PostsFetched event,
    void Function(PostsState) emit,
  ) async {
    if (stateValue.hasReachedMax) return;

    try {
      if (stateValue.status == PostsStatus.initial) {
        final posts = await _repository.fetchPosts(
          startIndex: 0,
          count: 10,
          query: stateValue.searchQuery,
        );
        return emit(stateValue.copyWith(
          status: PostsStatus.success,
          posts: posts,
          hasReachedMax: false,
        ));
      }

      final posts = await _repository.fetchPosts(
        startIndex: stateValue.posts.length,
        count: 10,
        query: stateValue.searchQuery,
      );

      emit(posts.isEmpty
          ? stateValue.copyWith(hasReachedMax: true)
          : stateValue.copyWith(
              status: PostsStatus.success,
              posts: [...stateValue.posts, ...posts],
              hasReachedMax: stateValue.posts.length + posts.length >= 30,
            ));
    } catch (_) {
      emit(stateValue.copyWith(status: PostsStatus.failure));
    }
  }

  Future<void> _onPostsSearchChanged(
    PostsSearchChanged event,
    void Function(PostsState) emit,
  ) async {
    final posts = await _repository.fetchPosts(
      startIndex: 0,
      count: 10,
      query: event.query,
    );
    emit(stateValue.copyWith(
      status: PostsStatus.success,
      posts: posts,
      hasReachedMax: false,
      searchQuery: event.query,
    ));
  }

  @override
  void dispose() {
    if (_isControllerDisposed) return;
    _isControllerDisposed = true;
    removeListener(_onScrollChanged);
    close();
    super.dispose();
  }

  @override
  Future<void> close() async {
    if (!_isControllerDisposed) {
      _isControllerDisposed = true;
      removeListener(_onScrollChanged);
      super.dispose();
    }
    await super.close();
  }
}

Look at what this class accomplishes:

It is a ScrollController: You can pass it directly to ListView.builder(controller: controller).
It is a BlocSignalBase: You can pass it directly to BlocSignalBuilder or provide it with BlocSignalProvider.
It manages its own event dispatch: It inspects its own scroll offset and calls add(const PostsFetched()).
It governs its own concurrency: transformer: droppable() guarantees that rapid thumb flings while a network request is in-flight are synchronously ignored on the same frame.

🎨 The Flutter UI: A 100% `StatelessWidget`

Now observe what happens to the Flutter UI layer:

import 'package:bloc_signals_flutter/bloc_signals_flutter.dart';
import 'package:flutter/material.dart';
import '../controllers/paginated_posts_controller.dart';

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

  @override
  Widget build(BuildContext context) {
    final controller = context.read<PaginatedPostsController>();

    return Scaffold(
      appBar: AppBar(
        title: const Text('Self-Paging Controller (Stateless)'),
        bottom: PreferredSize(
          preferredSize: const Size.fromHeight(60),
          child: Padding(
            padding: const EdgeInsets.symmetric(horizontal: 16.0, vertical: 8.0),
            child: TextField(
              decoration: const InputDecoration(
                hintText: 'Search posts...',
                prefixIcon: Icon(Icons.search),
                border: OutlineInputBorder(),
              ),
              onChanged: (query) {
                controller.add(PostsSearchChanged(query));
              },
            ),
          ),
        ),
      ),
      body: BlocSignalBuilder<PaginatedPostsController, PostsState>(
        builder: (context, state) {
          switch (state.status) {
            case PostsStatus.initial:
              return const Center(child: CircularProgressIndicator());

            case PostsStatus.failure:
              return const Center(child: Text('Failed to load posts'));

            case PostsStatus.success:
              if (state.posts.isEmpty) {
                return const Center(child: Text('No posts found.'));
              }
              return ListView.builder(
                controller: controller, // Plugs directly into Flutter's native ListView!
                itemCount: state.hasReachedMax
                    ? state.posts.length
                    : state.posts.length + 1,
                itemBuilder: (context, index) {
                  if (index >= state.posts.length) {
                    return const Padding(
                      padding: EdgeInsets.all(16.0),
                      child: Center(child: CircularProgressIndicator()),
                    );
                  }
                  final post = state.posts[index];
                  return ListTile(
                    leading: CircleAvatar(child: Text('${post.id}')),
                    title: Text(post.title),
                    subtitle: Text(post.body),
                  );
                },
              );
          }
        },
      ),
    );
  }
}

Notice what is completely absent from this widget:

❌ No StatefulWidget
❌ No State.initState
❌ No State.dispose
❌ No ScrollController listener wiring
❌ No manual scroll threshold math
❌ No third-party pagination widgets

The widget is a pure, declarative, 100% StatelessWidget. It renders the state when signals emit, and it routes user interactions directly to the controller.

🛡️ Safe Lifecycle & Teardown Architecture

One important detail when unifying a Flutter ChangeNotifier and a BlocSignalBase is lifecycle coordination.

When providing PaginatedPostsController through BlocSignalProvider:

BlocSignalProvider<PaginatedPostsController>(
  lazy: false,
  create: (context) => PaginatedPostsController(repository: repository)
    ..add(const PostsFetched()),
  child: const MaterialApp(home: SelfPagingPostsView()),
)

BlocSignalProvider automatically invokes bloc.close() when the provider is unmounted.

Furthermore, passing controller: controller to ListView.builder does not cause the ListView to dispose the controller; in Flutter, widgets only dispose controllers that they instantiated internally.

To ensure safe, leak-free teardown regardless of how the controller is managed, we implement an idempotent teardown guard:

bool _isControllerDisposed = false;

@override
void dispose() {
  if (_isControllerDisposed) return;
  _isControllerDisposed = true;
  removeListener(_onScrollChanged);
  close();
  super.dispose();
}

@override
Future<void> close() async {
  if (!_isControllerDisposed) {
    _isControllerDisposed = true;
    removeListener(_onScrollChanged);
    super.dispose();
  }
  await super.close();
}

Whether teardown is triggered via Flutter's dispose() or BlocSignalProvider's close(), listeners are removed, signals are cleaned up, and neither super.dispose() nor super.close() is ever executed more than once.

📊 Comprehensive Architectural Comparison

Dimension	Third-Party Packages (for example `infinite_scroll_pagination`)	Classic Straight BLoC (`examples/infinite_scroll`)	Pattern A: Reactive `PagingScrollController`	Pattern B: Self-Paging Mixin (`examples/infinite_scroll_mixin`)
Widget Tree Impact	❌ Proprietary wrappers (`PagedListView`)	✅ 100% Standard Flutter widgets	✅ 100% Standard Flutter widgets	✅ 100% Standard Flutter widgets
UI Widget Structure	`StatefulWidget` or wrapper	`StatefulWidget` (`initState`/`dispose`)	`StatefulWidget` or effect	✅ 100% `StatelessWidget`
Source of Truth	❌ Competing controllers fighting BLoC	✅ Single BLoC container	✅ Single BLoC container	✅ Single unified controller
Concurrency Guard	Brittle UI-level guards	✅ Synchronous `droppable()`	✅ Synchronous `droppable()`	✅ Synchronous `droppable()`
Domain Layer Separation	Coupled to package	✅ 100% Pure Dart domain	✅ 100% Pure Dart domain	Blended UI controller & state machine
External Dependencies	Heavy third-party package	None (pure `bloc_signals`)	None (pure `bloc_signals`)	None (pure `bloc_signals`)

🎯 Which Strategy Should You Choose?

Both patterns are first-class citizens in the BlocSignal repository:

Use the Classic Straight BLoC Strategy (examples/infinite_scroll) when:
- Your team adheres to strict Clean Architecture where domain BLoCs must never import Flutter packages.
- The same BLoC is shared across CLI tools, Jaspr web applications, or server-side Dart services.
- You prefer traditional StatefulWidget controller lifecycles in the UI layer.
Use the Self-Paging Mixin Strategy (examples/infinite_scroll_mixin) when:
- You want maximum developer velocity and minimal boilerplate.
- You want your UI views to be 100% StatelessWidget with zero glue code.
- You want a self-contained controller that manages both the scroll mechanics and the paginated state machine in one cohesive class.

Conclusion

Infinite scroll does not have to be a rite of passage filled with race condition bugs, competing controllers, or proprietary widget wrappers.

By combining droppable() concurrency with CubitSignalMixin and BlocSignalMixin:

You overcome Dart's single-inheritance constraint.
You eliminate duplicate scroll notifications automatically.
You write 100% StatelessWidget UI screens without a single line of initState or dispose boilerplate.

Resources & Companion Code

🔗 Part 1 of this series: Taming Flutter Infinite Scroll: Why 3 Lines of async* Missed the Point, and How BlocSignal Fixes It
💻 Classic Strategy Example: examples/infinite_scroll on GitHub
💻 Self-Paging Mixin Strategy Example: examples/infinite_scroll_mixin on GitHub
📜 Composable Mixins Guide: CubitSignalMixin & BlocSignalMixin Documentation
📦 bloc_signals on pub.dev
📦 bloc_signals_flutter on pub.dev
🌐 Official Documentation Hub: blocsignal.dev
🌟 GitHub Repository: RandalSchwartz/BlocSignal

Taming Flutter Infinite Scroll: Why 3 Lines of async* Missed the Point, and How BlocSignal Fixes It

Randal L. Schwartz — Thu, 03 Sep 2026 12:47:27 +0000

The Ubiquitous Infinite Scroll Pagination Bug

Almost every Flutter engineer has encountered the dreaded infinite scroll race condition in production.

The user opens a list, flings their thumb down the screen on a spotty cellular connection, and triggers multiple scroll notifications past the bottom threshold within milliseconds. Before the first asynchronous HTTP network request finishes, the scroll listener fires again.

Suddenly, your list duplicates items, page counters jump ahead, or the state machine locks up entirely.

Recently, mobile developer Ali Wajdan published a widely discussed article titled 3 Lines of Dart async* Code That Fixed My Infinite Scroll Pagination.

In his article, Ali accurately diagnoses the root cause of standard pagination headaches:

"Most Flutter pagination code I have seen, including my own for years, wraps a mutable state object around a scroll listener. A page counter, a loading boolean, a hasMore flag, and a fetch method the UI calls when it hits the scroll threshold. It works until two scroll events fire close together, or a rebuild triggers a second load before the first future resolves... It is a classic race condition, and it gets worse once the state lives across a page counter, a hasMore flag, and a loading flag that all need to stay in sync."

To escape this trap, Ali suggested encapsulating pagination logic inside a Dart async* generator and consuming it with a StreamIterator:

// The pattern proposed in Ali Wajdan's article
Stream<List<Post>> fetchPostsPaginated(String query) async* {
  var page = 0;
  var hasMore = true;
  while (hasMore) {
    final batch = await api.fetchPosts(query, page: page);
    hasMore = batch.isNotEmpty;
    page++;
    yield batch;
  }
}

final iterator = StreamIterator(fetchPostsPaginated(query));

Future<List<Post>> loadNextPage() async {
  if (!await iterator.moveNext()) return const [];

  return iterator.current;
}

On the surface, moving mutable state into local generator variables looks clean. But does it actually solve the concurrency problem in production?

Let us take a closer look.

🔍 Why `async*` and `StreamIterator` Crack Under Pressure

While moving the page counter and hasMore flag inside the generator prevents outside tampering, the implementation suffers from severe architectural pitfalls:

1. The Hidden Concurrency Crash: `Bad state: Cannot call moveNext...`

Dart's StreamIterator.moveNext() is explicitly not concurrency-safe.

If a fast scroll fling or a double-rebuild calls loadNextPage() while a previous moveNext() is still awaiting the network, Dart immediately throws an unhandled runtime error:

Bad state: Cannot call moveNext while a previous call to moveNext is still pending.

Because of this, the author admits in the article that he still had to maintain a manual guard:

"I still guard the UI trigger with the one Future that loadNextPage returns... That guard is the only piece of state I own now."

In other words, you have not actually eliminated the concurrency guard—you have merely introduced a stream iterator abstraction on top of it.

2. Pulling Chunks vs. Reactive Unidirectional Data Flow

An iterator is an imperative pull-based consumer. It yields a raw batch of items, but a real-world Flutter UI needs a comprehensive reactive state model:

What happens when a network error occurs on page 4?
How does the UI render a bottom spinner indicator while retaining previously fetched items?
How do we handle pull-to-refresh or empty states?

With an iterator, you still have to maintain an external state container to accumulate batches, catch errors, and update the UI.

3. Resource Leak Risks & Teardown Friction

A StreamIterator holds an active stream subscription. If the user navigates away from the screen, you must remember to explicitly invoke await iterator.cancel(). Furthermore, whenever a search query or filter changes, you must tear down the old iterator, instantiate a fresh generator, and re-bind the pipeline.

⚡ The Architectural Lesson: Concurrency Belongs at the Event Boundary

The core insight is simple: concurrency control should never be buried inside an imperative data-pulling loop, nor should it leak into UI scroll listeners.

Concurrency is an event scheduling concern. The moment a user's gesture or scroll threshold emits an event, the system should declare how overlapping executions are handled.

In BlocSignal, concurrency is a first-class citizen governed by streamless event transformers.

🛡️ The Idiomatic BlocSignal Solution: `droppable()`

In bloc_signals, preventing duplicate requests during infinite scroll requires exactly one parameter: transformer: droppable().

Here is how a clean, production-ready PostsBloc looks:

import 'package:bloc_signals/bloc_signals.dart';
import 'package:flutter/foundation.dart';
import '../models/post.dart';

sealed class PostsEvent {
  const PostsEvent();
}

final class PostsFetched extends PostsEvent {
  const PostsFetched();
}

final class PostsSearchChanged extends PostsEvent {
  const PostsSearchChanged(this.query);
  final String query;
}

enum PostsStatus { initial, loading, success, failure }

@immutable
class PostsState {
  const PostsState({
    this.status = PostsStatus.initial,
    this.posts = const [],
    this.hasReachedMax = false,
    this.searchQuery = '',
  });

  final PostsStatus status;
  final List<Post> posts;
  final bool hasReachedMax;
  final String searchQuery;

  PostsState copyWith({
    PostsStatus? status,
    List<Post>? posts,
    bool? hasReachedMax,
    String? searchQuery,
  }) {
    return PostsState(
      status: status ?? this.status,
      posts: posts ?? this.posts,
      hasReachedMax: hasReachedMax ?? this.hasReachedMax,
      searchQuery: searchQuery ?? this.searchQuery,
    );
  }
}

class PostsBloc extends BlocSignal<PostsEvent, PostsState> {
  PostsBloc({required PostRepository repository})
      : _repository = repository,
        super(initialState: const PostsState()) {

    // 1. Drop duplicate scroll triggers while a page fetch is in flight
    on<PostsFetched>(
      _onPostsFetched,
      transformer: droppable(),
    );

    // 2. Automatically cancel and restart when the search query changes
    on<PostsSearchChanged>(
      _onPostsSearchChanged,
      transformer: restartable(),
    );
  }

  final PostRepository _repository;

  Future<void> _onPostsFetched(
    PostsFetched event,
    void Function(PostsState) emit,
  ) async {
    if (stateValue.hasReachedMax) return;

    try {
      // Natural offset pagination: stateValue.posts.length IS your cursor!
      final newPosts = await _repository.fetchPosts(
        query: stateValue.searchQuery,
        startIndex: stateValue.posts.length,
        limit: 10,
      );

      emit(
        newPosts.isEmpty
            ? stateValue.copyWith(hasReachedMax: true)
            : stateValue.copyWith(
                status: PostsStatus.success,
                posts: [...stateValue.posts, ...newPosts],
                hasReachedMax: newPosts.length < 10,
              ),
      );
    } catch (_) {
      emit(stateValue.copyWith(status: PostsStatus.failure));
    }
  }

  Future<void> _onPostsSearchChanged(
    PostsSearchChanged event,
    void Function(PostsState) emit,
  ) async {
    emit(stateValue.copyWith(
      status: PostsStatus.loading,
      searchQuery: event.query,
    ));

    try {
      final posts = await _repository.fetchPosts(
        query: event.query,
        startIndex: 0,
        limit: 10,
      );

      emit(PostsState(
        status: PostsStatus.success,
        posts: posts,
        hasReachedMax: posts.length < 10,
        searchQuery: event.query,
      ));
    } catch (_) {
      emit(stateValue.copyWith(status: PostsStatus.failure));
    }
  }
}

🔬 Under the Hood: Why `droppable()` is Glitch-Free and Streamless

How does droppable() prevent race conditions without allocating Rx streams or microtask queues?

In classic package:bloc_concurrency, transformers convert an incoming event stream using Rx operators (such as exhaustMap). That introduces stream controllers, subscription pipelines, and asynchronous microtask dispatch delays.

In BlocSignal, event transformers are streamless higher-order functions:

EventTransformer<E, StateType> droppable<E, StateType>() {
  var isProcessing = false;
  return (event, handler, emit) async {
    if (isProcessing) return;
    isProcessing = true;
    try {
      final result = handler(event, emit);
      if (result is Future) {
        await result;
      }
    } finally {
      isProcessing = false;
    }
  };
}

Look at how elegant this is:

When the first PostsFetched event arrives, isProcessing flips to true synchronously in the exact same call frame.
If the user's scroll fling generates 8 additional scroll events in that same frame or while the HTTP request is pending, each incoming event hits if (isProcessing) return; and is safely, immediately discarded.
Once the HTTP request completes and state is emitted, finally resets isProcessing = false, allowing the next scroll boundary trigger to proceed.

Zero race conditions. Zero microtask lag. Zero Stream allocations.

🎯 Natural Cursor Pagination: Forgetting the `page` Counter

Notice another detail in PostsBloc: there is no page counter variable anywhere.

When you manage paginated lists, maintaining a separate int page = 0 counter that increments alongside posts.addAll(...) is an anti-pattern. If an API request fails, or if duplicate events trigger, the counter can desynchronize from the actual item count.

Instead, derive your offset directly from the source of truth:

startIndex: stateValue.posts.length

The length of your accumulated list is your pagination cursor. There is nothing to desynchronize, nothing to increment prematurely, and nothing to reset manually.

🔄 Instant Search Reset with `restartable()`

What happens when the user types a new search query into the search bar while an infinite scroll request is actively in flight?

In Ali's generator example, resetting required manual teardown:

"Changing a search query or filter means creating a new generator, not carefully resetting three fields and hoping you got them all."

In BlocSignal, you simply tag search events with transformer: restartable():

on<PostsSearchChanged>(
  _onPostsSearchChanged,
  transformer: restartable(),
);

When a new search query arrives, restartable() increments an internal token. Any in-flight HTTP responses from older queries or prior scroll pages are automatically dropped from emitting state. The list smoothly switches to the new search query without race conditions or ghost responses.

📱 The Flutter UI: Declarative and Lightweight

Consuming this in Flutter is straightforward. We attach a ScrollController listener to dispatch PostsFetched() when the user is within 10% of the bottom, and build the UI using BlocSignalBuilder:

class PostsView extends StatefulWidget {
  const PostsView({super.key});

  @override
  State<PostsView> createState() => _PostsViewState();
}

class _PostsViewState extends State<PostsView> {
  final _scrollController = ScrollController();

  @override
  void initState() {
    super.initState();
    _scrollController.addListener(_onScroll);
  }

  @override
  void dispose() {
    _scrollController.removeListener(_onScroll);
    _scrollController.dispose();
  }

  void _onScroll() {
    if (!_scrollController.hasClients) return;
    final maxScroll = _scrollController.position.maxScrollExtent;
    final currentScroll = _scrollController.offset;

    // Trigger when 90% scrolled
    if (currentScroll >= (maxScroll * 0.9)) {
      context.read<PostsBloc>().add(const PostsFetched());
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Infinite Scroll Posts'),
        bottom: PreferredSize(
          preferredSize: const Size.fromHeight(60),
          child: Padding(
            padding: const EdgeInsets.symmetric(horizontal: 16.0, vertical: 8.0),
            child: TextField(
              decoration: const InputDecoration(
                hintText: 'Search posts...',
                prefixIcon: Icon(Icons.search),
                border: OutlineInputBorder(),
              ),
              onChanged: (query) {
                context.read<PostsBloc>().add(PostsSearchChanged(query));
              },
            ),
          ),
        ),
      ),
      body: BlocSignalBuilder<PostsBloc, PostsState>(
        builder: (context, state) => switch (state.status) {
          PostsStatus.initial => const Center(
              child: CircularProgressIndicator(),
            ),
          PostsStatus.failure => const Center(
              child: Text('Failed to load posts.'),
            ),
          PostsStatus.loading && state.posts.isEmpty => const Center(
              child: CircularProgressIndicator(),
            ),
          PostsStatus.success || PostsStatus.loading => state.posts.isEmpty
              ? const Center(child: Text('No posts found.'))
              : ListView.builder(
                  controller: _scrollController,
                  itemCount: state.hasReachedMax
                      ? state.posts.length
                      : state.posts.length + 1,
                  itemBuilder: (context, index) {
                    if (index >= state.posts.length) {
                      return const Padding(
                        padding: EdgeInsets.all(16.0),
                        child: Center(child: CircularProgressIndicator()),
                      );
                    }
                    final post = state.posts[index];
                    return ListTile(
                      leading: CircleAvatar(child: Text('${post.id}')),
                      title: Text(post.title),
                      subtitle: Text(post.body),
                    );
                  },
                ),
        },
      ),
    );
  }
}

Because BlocSignalBuilder listens to fine-grained signal changes, UI updates execute synchronously in the exact frame state is emitted, completely avoiding frame-skipping and microtask latency.

📊 Architectural Comparison

Architectural Metric	Ali's `async*` + `StreamIterator`	Manual Flags in Widget / State	`BlocSignal` with `droppable()`
Concurrency Guard	❌ Throws `StateError` on concurrent `moveNext()`	⚠️ Brittle `isLoading` flags prone to race conditions	✅ 100% synchronous guard lock
Cursor Management	Scoped to generator	Mutable `page` counter	Natural offset (`posts.length`)
Search Cancellation	Requires manual generator recreation	Complex cancellation tokens	Built-in via `transformer: restartable()`
UI Integration	Pull-only chunk fetching	Cluttered widget code	Declarative, reactive UI via signals
Lifecycle & Teardown	Manual `iterator.cancel()`	Manual controller disposal	Automatic container cleanup via `close()`
Runtime Overhead	Stream iteration overhead	Minimal	Streamless pure Dart functions

Conclusion

Ali Wajdan's article highlights a genuine problem: manual state flags around scroll listeners are a frequent source of production bugs in Flutter.

However, attempting to solve event concurrency by turning asynchronous APIs into stream generators swaps one set of bugs for another.

By treating concurrency as an event boundary policy with droppable() and restartable(), you gain:

Bulletproof concurrency that gracefully ignores rapid thumb flings.
Zero-drift pagination powered by natural list offset indexing.
Streamless performance with 0ms signal propagation.

Resources & Links

🔗 Original Article by Ali Wajdan: 3 Lines of Dart async* Code That Fixed My Infinite Scroll Pagination
📜 Interactive Concurrency Guide: Event Concurrency Transformers on blocsignal.dev
💻 Full Runnable Example & Test Suite: examples/infinite_scroll on GitHub
📦 bloc_signals on pub.dev
📦 bloc_signals_flutter on pub.dev
🌐 Official Documentation: blocsignal.dev
🌟 GitHub Repository: RandalSchwartz/BlocSignal

DEV Community: Randal L. Schwartz

Share State Across Dart Isolates Without Losing Your Mind: Enter shared_map

What is shared_map?

How It Works: The Reference Pattern

See It In Action

The Console Output

Superpower: Local Read Caching with SharedMapCached

Grouping Maps with SharedStore

Senior Engineering Wisdom: When to Use (and Not Use) shared_map

✅ When to Reach for shared_map:

⚠️ When NOT to Use shared_map:

Summary

What's your take?

Dart Enhanced Enums Are Secretly Factories: Unlocking Constructor Tearoffs

The Two Ingredients: A Brief History

1. Constructor Tearoffs (Dart 2.15+)

2. Enhanced Enums (Dart 2.17+)

The Fusion: Enums as Self-Instantiating Factories

How You Use It

Real-World Example: Polymorphic API Payload Parsers

Real-World Example: Flutter Widget Builders

A Senior Perspective: When NOT to Use This Pattern

1. Beware of Layer Inversion (Separation of Concerns)

2. When to Prefer Dart 3 Sealed Classes & Pattern Matching

Conclusion

What's your take?

Stop Paying the build_runner Tax: Why I Refuse to Use Mockito in Modern Dart

How Did We End Up Here?

The Three Sins of Modern Mockito

1. The Iteration Tax (Destroying the TDD Flow)

2. Git Diff Pollution & Merge Conflict Hell

3. Brittle Annotation Coupling

Enter Mocktail: Zero-Config Runtime Mocking

Side-by-Side: Mockito vs. Mocktail

The One "Gotcha": Custom Type Fallbacks

The Problem

The Solution

How to Migrate Without Boiling the Ocean

The Verdict

What's your take?

Why AI Coding Agents Crash at 3 AM: The Happy-Path Mirage & The Forced Continuity Defect

1. The Midnight PagerDuty Test

2. The Forced Continuity Defect: Calculus vs. Cliffs

3. The Alignment Illusion: Why "More RLHF" Cannot Save Us

The Problem of Negative Infinities (-∞)

The Crowd Mirage and the Sycophancy Penalty

4. The Two Levels of Craft: Conscious Rules vs. The "Han Solo" Reflex

Level 1: "Oh, Don't Do That" (Explicit Rules)

Level 2: "I've Got a Bad Feeling About This" (The Han Solo Reflex)

5. The Premature Abstraction Disease & The 3-Point Solution Plane

6. Coding by Omission: The Race Car Invariant

7. The Scorecard: What Happens When You Give AI Scars?

📖 What’s Next in the Synthetic Scars Series

🔬 Academic Research & Forthcoming Preprint

Why AI Keeps Making the Same Coding Mistakes—And How Teaching It Pain Gives It Wisdom

1. The Straight-A Intern Who Crashes on Day One

2. Why Telling an AI "Don't Do That" Never Works

1. The "Pink Elephant" Trap

2. Statistical Amnesia ("Groundhog Day")

3. The Hot Stove: What Veteran Humans Have That AI Lacks

4. The Anatomy of a Synthetic Scar

5. Sleeping on the Job: How the System Learns

6. The Scorecard: 51 Real-World Field Tests

The Telemetry of "Thinking Twice"

7. Beyond Prompting: The Future of Trust in AI

📖 What’s Next in the Synthetic Scars Series

🔬 Academic Research & Forthcoming Preprint

The Symmetry of State: Why Flutter Deserves context.value and context.state

The State Access Dilemma in Flutter

The Friction of Reading State

1. The Three Sins of Context Reading in Classic BLoC

Sin 1: The Indentation and Rebuild Tax of BlocBuilder

Sin 2: The Treacherous context.watch Mental Model Trap

The Signal Architecture "Scar"

Sin 3: Closure Fatigue in context.select

2. The Architectural Symmetry: Container vs. Context

3. Deep Dive: context.value<B, S>()

How It Works Under the Hood

Scoped Micro-Rebuilds with Standard Flutter Builder

4. Deep Dive: context.state<B, S>()

What is `shared_map`?

Superpower: Local Read Caching with `SharedMapCached`

Grouping Maps with `SharedStore`

Senior Engineering Wisdom: When to Use (and Not Use) `shared_map`

✅ When to Reach for `shared_map`:

⚠️ When NOT to Use `shared_map`:

The Problem of Negative Infinities (`-∞`)

Sin 1: The Indentation and Rebuild Tax of `BlocBuilder`

Sin 2: The Treacherous `context.watch` Mental Model Trap

Sin 3: Closure Fatigue in `context.select`

3. Deep Dive: `context.value<B, S>()`

Scoped Micro-Rebuilds with Standard Flutter `Builder`

4. Deep Dive: `context.state<B, S>()`

Why Not Just Use `context.read<B>().state`?

6. Zero-Closure Provider Tearoffs (`Cubit.create`)

3. Eradicating the "Code Generation Tax" (`build_runner`)

1. Classic BLoC Interoperability (`bloc_signals_bloc`)

2. Riverpod Interoperability (`bloc_signals_riverpod`)

3. Flutter `Listenable` Bridges

3. Why `droppable` Isn't Special: Elevating to Generic Telemetry

The Telemetry Contract on `BlocSignalObserver`

4. The Power of Composition: Contextual Transformers (`blocTransformer`)

1. Flutter DevTools Integration (`bloc_signals_devtools`)

2. OpenTelemetry Tracing (`bloc_signals_otel`)

3. Composable Distributed Tracing with `traced()`

6. Declarative Testing with `blocSignalTest`