DEV Community: Randal L. Schwartz

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

Automate Flutter's New Split Package Migration with AI Agent Skills

Randal L. Schwartz — Mon, 31 Aug 2026 16:20:40 +0000

How to use dart-sdk-skills to empower your AI coding agent to seamlessly migrate Flutter projects to standalone material_ui and cupertino_ui packages

The Flutter framework has undergone one of its most significant architectural evolutions: the complete unbundling of Material Design and Cupertino libraries into standalone pub packages (material_ui and cupertino_ui).

While this decoupling brings independent release cycles, lighter core framework footprints, and true headless UI development, it also introduces a massive migration across existing Flutter apps.

If you rely on AI coding assistants (such as Claude Code, Google Antigravity, Cursor, GitHub Copilot, or Cline), you have likely hit a familiar wall: LLM training cutoffs. Most models still generate monolithic package:flutter/material.dart imports and do not know how to perform the new split package migration.

In this article, we will explore how the open-source dart-sdk-skills repository gives your AI agent the exact knowledge and execution runbooks to automate this migration in a single prompt.

🏛️ The Architectural Shift: Why Split Packages?

Historically, Flutter bundled every Material Design and Cupertino widget directly into the core flutter SDK. While convenient initially, this approach had drawbacks:

Coupled Release Cycles: Updating a single Material button style required waiting for a framework release.
Framework Bloat: Apps building custom enterprise design systems were forced to bundle hundreds of unused Material and Cupertino classes.
Design System Collision: Mixing platform styles often led to tangled dependencies.

Under the modern decoupled architecture:

┌────────────────────────────────────────────────────────────────────────┐
│ Legacy Flutter (Monolithic)                                            │
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │ package:flutter/material.dart  &  package:flutter/cupertino.dart │  │
│  ├──────────────────────────────────────────────────────────────────┤  │
│  │ package:flutter/widgets.dart   &  package:flutter/rendering.dart │  │
│  └──────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────┘
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│ Modern Decoupled Architecture                                          │
│                                                                        │
│  ┌───────────────────────────────┐   ┌──────────────────────────────┐  │
│  │ package:material_ui           │   │ package:cupertino_ui         │  │
│  └───────────────┬───────────────┘   └──────────────┬───────────────┘  │
│                  └───────────────┬──────────────────┘                  │
│                                  ▼                                     │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │ Core Flutter SDK (package:flutter/widgets.dart)                  │  │
│  └──────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────┘

Both design systems are now maintained as independent packages by the official Flutter team on pub.dev:

material_ui (^1.1.0): Canonical entrypoint package:material_ui/material_ui.dart
cupertino_ui (^1.0.1): Canonical entrypoint package:cupertino_ui/cupertino_ui.dart

🧩 The Challenge with AI Coding Agents

When you tell an unassisted AI agent:

"Migrate my app to the new split Flutter design packages."

It often stumbles:

It hallucinates deprecated import paths or non-existent package names.
It does not know about the automated data-driven fix rules in the Dart analyzer.
It misses breaking changes in localization delegates (GlobalMaterialLocalizations).

This is where Agent Skills step in.

⚡ What is `dart-sdk-skills`?

dart-sdk-skills is an authoritative repository of version-by-version agent skills for the Dart and Flutter SDKs. Built using the open Agent Skill specification (SKILL.md), it progressively discloses precise rules, API matrices, and tactical upgrade runbooks to your AI pair programmer.

Installing `dart-sdk-skills` in Seconds

You can add the skills globally or per-project using your preferred tool:

Universal Install (Node / `npx skills`):

# Install globally for all AI agents
npx skills add RandalSchwartz/dart-sdk-skills -g

Dart Skills CLI:

skills add https://github.com/RandalSchwartz/dart-sdk-skills --global --all

Google Antigravity / Manual Symlink:

git clone https://github.com/RandalSchwartz/dart-sdk-skills.git ~/Projects/Dart/dart-sdk-skills
ln -s ~/Projects/Dart/dart-sdk-skills/skills/flutter-sdk-changelog ~/.gemini/config/skills/flutter-sdk-changelog

🤖 The Migration Workflow: Putting Your Agent to Work

Once installed, your agent automatically recognizes split-package requests. Simply prompt:

"Migrate this project to the new split Material and Cupertino packages."

Here is the exact multi-phase pipeline the agent executes based on the skill runbook:

1. Automated Analysis and Data-Driven Transforms

The agent leverages the built-in Dart toolchain fix runner:

dart fix --apply --code=migrate_design_widgets

This updates references and applies data-driven transform rules published inside material_ui/lib/fix_data/.

2. Dependency Configuration (`pubspec.yaml`)

The agent ensures your project bounds satisfy the minimum SDK constraints (Flutter >=3.44.0, Dart ^3.12.0):

dependencies:
  flutter:
    sdk: flutter
  # Standalone design systems
  material_ui: ^1.1.0
  cupertino_ui: ^1.0.1

3. Canonical Import Rewrites

The agent replaces monolithic imports across all Dart files with the canonical entrypoints:

// ❌ Legacy Monolithic Imports
import 'package:flutter/material.dart';
import 'package:flutter/cupertino.dart';

// ✅ Modern Standalone Package Imports
import 'package:material_ui/material_ui.dart';
import 'package:cupertino_ui/cupertino_ui.dart';

4. Localization Delegate Binding

Both material_ui.dart and cupertino_ui.dart export their respective global localization delegates without requiring extra legacy glue:

import 'package:flutter/widgets.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:material_ui/material_ui.dart';
import 'package:cupertino_ui/cupertino_ui.dart';

Widget buildApp() {
  return MaterialApp(
    localizationsDelegates: const [
      GlobalMaterialLocalizations.delegate,
      GlobalCupertinoLocalizations.delegate,
      GlobalWidgetsLocalizations.delegate,
    ],
    supportedLocales: const [
      Locale('en', 'US'),
      Locale('es', 'ES'),
    ],
    home: const HomeScreen(),
  );
}

5. Automated Verification & Quality Gate

The agent finishes by running static analysis and tests to ensure no ambiguous symbol collisions or unresolved imports remain:

dart analyze --fatal-infos
dart test

🎨 Bonus: Building Pure Headless Apps

One of the greatest benefits of this decoupling is that Flutter apps with custom enterprise design systems can now completely omit material_ui and cupertino_ui.

By building directly against package:flutter/widgets.dart, you can create a lightweight, high-performance UI layer with zero design system bloat:

import 'package:flutter/widgets.dart';

class BrandButton extends StatelessWidget {
  final Widget child;
  final VoidCallback onTap;

  const BrandButton({
    super.key,
    required this.child,
    required this.onTap,
  });

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: onTap,
      child: Container(
        padding: const EdgeInsets.symmetric(horizontal: 20.0, vertical: 12.0),
        decoration: BoxDecoration(
          color: const Color(0xFF1E88E5),
          borderRadius: BorderRadius.circular(10.0),
        ),
        child: child,
      ),
    );
  }
}

🚀 Get Started Today

The split package architecture is a major milestone for Flutter's scalability and modularity. By equipping your AI development workflow with dart-sdk-skills, you turn what could be a tedious manual refactor into an effortless, one-command migration.

🌟 GitHub Repository: github.com/RandalSchwartz/dart-sdk-skills
📦 material_ui on Pub: pub.dev/packages/material_ui
🍏 cupertino_ui on Pub: pub.dev/packages/cupertino_ui

Happy coding, and let your agents do the heavy lifting! 🚀

Production Flutter Networking Without the Boilerplate: Reactive Repositories with BlocSignal

Randal L. Schwartz — Sun, 30 Aug 2026 21:04:04 +0000

The Networking Architecture Dilemma in Production Flutter

If you survey ten seasoned Flutter developers about how they structure networking in production, you will almost certainly see the same multi-tiered pipeline:

┌────────────────────────────────────────────────────────────────────────┐
│               Traditional Flutter Networking Pipeline                  │
├────────────────────────────────────────────────────────────────────────┤
│ [Dio / HTTP Client] ─▶ [API Service] ─▶ [Repository Layer] ─▶          │
│                      [Cubit / BLoC] ─▶ [UI Builders & Banners]         │
└────────────────────────────────────────────────────────────────────────┘

The underlying architectural principles are sound: separation of concerns, testability, and isolating network transport details from UI widgets.

However, in practice, this classical layered stack demands an enormous amount of repetitive boilerplate:

Async State Union Ceremony: Defining four separate state classes (Initial, Loading, Success(data), Failure(error)) or union types for every single API endpoint.
Race Conditions & In-Flight Cancellation: When users type queries or switch tabs rapidly, requests finish out of order. Preventing stale responses requires complex Dio CancelToken plumbing or heavy rxdart switchMap streams.
Offline Caching & "Stale-While-Revalidate": Showing cached data on Frame 1 while fetching fresh updates in the background usually requires database synchronization and stream merging logic.
The Repository vs. Controller Divide: Repositories hold data and caching logic, while BLoCs or Cubits hold reactive state. Because Dart only allows single inheritance, developers end up maintaining two separate class hierarchies connected by verbose dependency injection glue.

With bloc_signals, we can preserve complete separation of concerns while eliminating 70% of the friction.

Let us examine how to architect a modern, clean, production-ready networking layer using CubitSignalMixin, HydratedMixin, and .toAsyncBlocSignal().

⚡ 1. Symmetrical Async Projection with `.toAsyncBlocSignal()`

In many cases, a feature only needs to fetch data from an endpoint and present it in the UI with loading and error states.

Instead of writing a custom Cubit and four distinct state classes, any Dart Future<T> converts directly into a BlocSignalBase<AsyncState<T>> with a single method call:

class UserProfileService {
  UserProfileService(this._dio);
  final Dio _dio;

  Future<UserProfile> fetchUserProfile(String userId) async {
    final response = await _dio.get('/users/\$userId');
    return UserProfile.fromJson(response.data as Map<String, dynamic>);
  }
}

In your presentation layer or view model:

// Converts Future<UserProfile> into a synchronous BlocSignalBase<AsyncState<UserProfile>>
final userProfileBloc = profileService
    .fetchUserProfile('user_123')
    .toAsyncBlocSignal();

Declarative Exhaustive UI Binding

Because AsyncState<T> is a sealed class hierarchy (AsyncLoading, AsyncData, AsyncError), you get compile-time exhaustive pattern matching in your Flutter widgets:

BlocSignalBuilder<BlocSignalBase<AsyncState<UserProfile>>, AsyncState<UserProfile>>(
  bloc: userProfileBloc,
  builder: (context, state) => switch (state) {
    AsyncLoading() => const Center(
        child: CircularProgressIndicator(),
      ),
    AsyncData(:final value) => ProfileDetailsView(user: value),
    AsyncError(:final error) => ErrorCard(
        message: error.toString(),
      ),
  },
)

No custom state classes, no manual try/catch event plumbing, and no FutureBuilder rebuild bugs.

🧬 2. Reactive, Offline-Cached Repositories with `CubitSignalMixin` & `HydratedMixin`

In enterprise apps, repositories often need to extend an existing API client base class (such as BaseApiClient or AuthenticatedHttpService) while maintaining persistent local caches.

Because Dart only permits single inheritance, traditional repositories could not be state containers.

With CubitSignalMixin and HydratedMixin, your repository IS the reactive, persistent state container:

import 'package:bloc_signals/bloc_signals.dart';
import 'package:bloc_signals_hydrate/bloc_signals_hydrate.dart';
import 'package:dio/dio.dart';

/// A production domain repository extending BaseApiClient with 0ms reactivity & disk caching!
class ProductRepository extends BaseApiClient
    with
        CubitSignalMixin<AsyncState<List<Product>>>,
        HydratedMixin<AsyncState<List<Product>>> {
  ProductRepository(super.dio) {
    // 1. Initialize reactive signal container
    initCubitSignal(initialState: const AsyncLoading());

    // 2. Initialize Frame-1 persistent storage cache
    initHydrated(storageKey: 'cached_products_v1');
  }

  /// Refreshes data from the network using toFutureSignal to eliminate try-catch
  Future<void> refresh() async {
    emit(const AsyncLoading());

    // ⚡ toFutureSignal automatically projects success into AsyncData and exceptions into AsyncError!
    final fetchSignal = _fetchProducts().toFutureSignal();
    await fetchSignal.future;
    emit(fetchSignal.value);
  }

  Future<List<Product>> _fetchProducts() async {
    final response = await dio.get('/products');
    final rawList = response.data as List<dynamic>;
    return [
      for (final item in rawList) Product.fromJson(item as Map<String, dynamic>),
    ];
  }

  // 💾 Pattern matching for instant offline hydration:
  @override
  Object? toJson(AsyncState<List<Product>> state) => switch (state) {
        AsyncData(:final value) => [
            for (final product in value) product.toJson(),
          ],
        _ => null,
      };

  @override
  AsyncState<List<Product>>? fromJson(dynamic json) => switch (json) {
        {'products': List<dynamic> list} => AsyncData([
            for (final item in list) Product.fromJson(item as Map<String, dynamic>),
          ]),
        List<dynamic> list => AsyncData([
            for (final item in list) Product.fromJson(item as Map<String, dynamic>),
          ]),
        _ => null,
      };
}

What This Architecture Delivers:

Instant Frame-1 Rendering: When the app opens, HydratedMixin restores the cached List<Product> synchronously before the first pixel renders. Zero loading flickers.
Background Refresh: Calling repository.refresh() executes network I/O and updates the UI synchronously on emit(AsyncData(freshProducts)).
Single Class Hierarchy: Extends BaseApiClient without needing an intermediate wrapper or proxy Cubit.

🛑 3. Eliminating Network Race Conditions with `restartable()`

One of the most insidious bugs in mobile networking is the out-of-order response.

If a user searches for "Fl", then "Flu", and finally "Flutter", the network request for "Fl" might take 800ms while "Flutter" takes 200ms. Without cancellation, the "Fl" response resolves last and overwrites the screen with stale data!

With BlocSignalMixin, solving this requires zero cancel tokens or Rx streams—just apply the built-in restartable() transformer:

sealed class SearchEvent {
  const SearchEvent();
}

final class SearchQueryChanged extends SearchEvent {
  const SearchQueryChanged(this.query);
  final String query;
}

class SearchRepository extends BaseApiClient
    with
        CubitSignalMixin<AsyncState<List<SearchResult>>>,
        BlocSignalMixin<SearchEvent, AsyncState<List<SearchResult>>> {
  SearchRepository(super.dio) {
    initCubitSignal(initialState: const AsyncData([]));

    // ⚡ Built-in concurrency control: automatically aborts prior in-flight queries!
    on<SearchQueryChanged>((event, emit) async {
      final query = event.query.trim();
      if (query.isEmpty) {
        emit(const AsyncData([]));
        return;
      }

      emit(const AsyncLoading());
      final searchSignal = _executeSearch(query).toFutureSignal();
      await searchSignal.future;
      emit(searchSignal.value);
    }, transformer: restartable());
  }

  Future<List<SearchResult>> _executeSearch(String query) async {
    final response = await dio.get('/search', queryParameters: {'q': query});
    final results = response.data as List<dynamic>;
    return [
      for (final item in results) SearchResult.fromJson(item as Map<String, dynamic>),
    ];
  }
}

🏛️ Summary Architecture Comparison

┌──────────────────────────────┬────────────────────────┬────────────────────────┐
│ Architectural Concern        │ Traditional Flutter    │ BlocSignal Ecosystem   │
├──────────────────────────────┼────────────────────────┼────────────────────────┤
│ Async State Representation   │ 4 custom classes/enums │ AsyncState<T> sealed   │
│ In-Flight Race Conditions    │ Dio CancelToken / Rx   │ restartable() builtin  │
│ Duplicate Tap Protection     │ Custom boolean flags   │ droppable() builtin    │
│ Frame-1 Offline Persistence  │ SQLite / SharedPreferences│ HydratedMixin frame-1│
│ Existing Base Class Interop  │ Proxy/Wrapper classes  │ CubitSignalMixin       │
└──────────────────────────────┴────────────────────────┴────────────────────────┘

By pairing pure Dart reactive signal primitives with composable mixins and higher-order concurrency transformers, your networking layer remains clean, testable, and robust—with a fraction of the traditional ceremony.

💬 Join the Discussion!

How do you currently handle cancellation, offline caching, and async state in your Flutter networking layer?

Share your architecture setups and thoughts in the comments below!

Overcoming Dart's Single Inheritance Wall: Composable CubitSignalMixin & BlocSignalMixin in Flutter

Randal L. Schwartz — Sun, 30 Aug 2026 16:46:00 +0000

Breaking Free from Dart's Single Inheritance Constraint in State Management

Every Dart and Flutter developer eventually runs headfirst into a fundamental language constraint: single inheritance.

In Dart, a class can extend only one superclass.

In greenfield tutorials, this is rarely an issue because classes start from a clean slate. But in real-world Flutter engineering, domain repositories, controllers, and services frequently already belong to an established inheritance hierarchy:

A search field controller that must extend Flutter's TextEditingController (which itself extends ValueNotifier<TextEditingValue>).
A view controller that extends ChangeNotifier or AnimationController.
A domain repository that extends an enterprise BaseRepository<T>, EntityStore, or microservices client.

Historically, if you wanted that class to also be a Cubit or BLoC, you were out of luck. You could not write:

// ❌ Impossible in Dart (Multiple Inheritance is forbidden):
class SearchController extends TextEditingController, CubitSignal<SearchState> { ... }

This forced developers into a frustrating dilemma:

The Wrapper / Proxy Anti-Pattern: Creating a wrapper class that held an internal _cubit reference, requiring tedious method forwarding and manual synchronization.
Duplicate Controller Lifecycles: Managing two separate objects in the widget tree—a TextEditingController for the input widget and a separate SearchCubit for the state—forcing you to wire listeners between them in initState/dispose.
Inheritance Refactoring: Trying to refactor existing base classes, often breaking third-party library contracts or enterprise architectures.

With bloc_signals 1.2.0, that single inheritance wall has been completely demolished.

We have introduced CubitSignalMixin and BlocSignalMixin, enabling any class in an existing inheritance hierarchy to become a first-class, 0ms reactive BlocSignalBase container with zero wrapper boilerplate.

🧬 How the Composable Mixins Work

Because BlocSignal has a lean, highly disciplined API surface, mixing it into arbitrary classes introduces zero namespace pollution.

┌────────────────────────────────────────────────────────────────────────┐
│                        BlocSignal Mixin Architecture                   │
├────────────────────────────────┬───────────────────────────────────────┤
│ Mixin                          │ Capabilities Added                    │
├────────────────────────────────┼───────────────────────────────────────┤
│ CubitSignalMixin<StateType>    │ state, stateValue, emit(newState),    │
│                                │ equals(), createEffect(), close()     │
├────────────────────────────────┼───────────────────────────────────────┤
│ BlocSignalMixin<Event, State>  │ on<E>(), concurrency transformers     │
│                                │ (restartable, droppable), add(event)  │
└────────────────────────────────┴───────────────────────────────────────┘

1. `CubitSignalMixin<StateType>`

CubitSignalMixin implements BlocSignalBase<StateType>. All you do is mix it in and invoke initCubitSignal(initialState: ...) in your constructor:

class UserProfileRepository extends BaseRepository
    with CubitSignalMixin<UserProfileState> {
  UserProfileRepository(super.apiClient) {
    initCubitSignal(initialState: const UserProfileInitial());
  }

  Future<void> fetchProfile(String userId) async {
    emit(const UserProfileLoading());
    try {
      final profile = await apiClient.getProfile(userId);
      emit(UserProfileLoaded(profile));
    } catch (error, stackTrace) {
      emit(UserProfileError(error.toString()));
    }
  }
}

2. `BlocSignalMixin<Event, StateType>`

When you need full event-driven state machines with concurrency transformers (restartable(), droppable(), sequential()), mix in both CubitSignalMixin and BlocSignalMixin:

class OrderService extends BaseService
    with CubitSignalMixin<OrderState>, BlocSignalMixin<OrderEvent, OrderState> {
  OrderService(super.networkClient) {
    initCubitSignal(initialState: const OrderInitial());

    on<SubmitOrder>((event, emit) async {
      emit(const OrderSubmitting());
      final result = await networkClient.postOrder(event.order);
      emit(OrderSuccess(result.orderId));
    }, transformer: droppable()); // Discards duplicate taps while in flight!
  }
}

🎯 Real-World Killer Use Case: The Self-Debouncing `TextEditingController`

Let us look at a practical scenario where this pattern shines: a live product search input.

In traditional Flutter architectures, building a debounced search input requires:

Creating a TextEditingController in widget state.
Creating a SearchBloc or SearchCubit.
Adding a listener in initState that forwards controller.text into bloc.add(SearchQueryChanged(text)).
Remembering to dispose both in dispose().

With BlocSignalMixin, your TextEditingController IS the debounced BLoC:

sealed class SearchEvent {
  const SearchEvent();
}

final class QueryChanged extends SearchEvent {
  const QueryChanged(this.query);
  final String query;
}

sealed class SearchState {
  const SearchState();
}

final class SearchInitial extends SearchState {
  const SearchInitial();
}

final class SearchLoading extends SearchState {
  const SearchLoading();
}

final class SearchSuccess extends SearchState {
  const SearchSuccess(this.results);
  final List<Product> results;
}

final class SearchError extends SearchState {
  const SearchError(this.message);
  final String message;
}

/// A standard Flutter TextEditingController with built-in BLoC reactivity!
class SearchTextEditingController extends TextEditingController
    with
        CubitSignalMixin<SearchState>,
        BlocSignalMixin<SearchEvent, SearchState> {
  SearchTextEditingController(this._api) {
    initCubitSignal(initialState: const SearchInitial());

    // ⚡ Built-in restartable concurrency transformer automatically cancels
    // previous in-flight queries when new text is entered!
    on<QueryChanged>((event, emit) async {
      final query = event.query.trim();
      if (query.isEmpty) {
        emit(const SearchInitial());
        return;
      }

      emit(const SearchLoading());
      try {
        final products = await _api.search(query);
        emit(SearchSuccess(products));
      } catch (error) {
        emit(SearchError(error.toString()));
      }
    }, transformer: restartable());

    // 🎯 Forward controller text mutations straight into the event pipeline
    addListener(() => add(QueryChanged(text)));
  }

  final SearchApiClient _api;

  @override
  void dispose() {
    close(); // Closes signal subscriptions and cancels pending async transformers
    super.dispose();
  }
}

Clean, Declarative Flutter UI Binding

Because SearchTextEditingController extends TextEditingController AND implements BlocSignalBase<SearchState>, you pass it directly to TextField and read it directly with BlocSignalBuilder:

class SearchScreen extends StatefulWidget {
  const SearchScreen({super.key, required this.api});
  final SearchApiClient api;

  @override
  State<SearchScreen> createState() => _SearchScreenState();
}

class _SearchScreenState extends State<SearchScreen> {
  late final SearchTextEditingController _searchController;

  @override
  void initState() {
    super.initState();
    _searchController = SearchTextEditingController(widget.api);
  }

  @override
  void dispose() {
    _searchController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: TextField(
          controller: _searchController,
          decoration: const InputDecoration(
            hintText: 'Search products...',
            border: InputBorder.none,
          ),
        ),
      ),
      body: BlocSignalBuilder<SearchTextEditingController, SearchState>(
        bloc: _searchController,
        builder: (context, state) => switch (state) {
          SearchInitial() => const Center(
              child: Text('Type a query to search products.'),
            ),
          SearchLoading() => const Center(
              child: CircularProgressIndicator(),
            ),
          SearchSuccess(:final results) when results.isEmpty => const Center(
              child: Text('No products found.'),
            ),
          SearchSuccess(:final results) => ListView.builder(
              itemCount: results.length,
              itemBuilder: (context, index) => ListTile(
                title: Text(results[index].name),
                subtitle: Text('\$${results[index].price}'),
              ),
            ),
          SearchError(:final message) => Center(
              child: Text('Error: $message', style: const TextStyle(color: Colors.red)),
            ),
        },
      ),
    );
  }
}

Look at that simplicity:

Zero glue code.
Single object lifecycle: one controller to instantiate, one controller to dispose.
Native Flutter widget compatibility: passed directly to TextField(controller: ...).
0ms Reactive UI updates: rebuilt synchronously on every state transition.

🏛️ DRY Core Architecture & Universal Polymorphism

One of our guiding principles in BlocSignal is avoiding parallel, divergent abstractions.

In bloc_signals 1.2.0, CubitSignal and BlocSignal themselves compose CubitSignalMixin and BlocSignalMixin as their single source of truth:

abstract class CubitSignal<StateType> extends BlocSignalBase<StateType>
    with CubitSignalMixin<StateType> {
  CubitSignal({
    required StateType initialState,
    bool Function(StateType, StateType)? equals,
    SignalOptions<StateType>? options,
  }) {
    initCubitSignal(
      initialState: initialState,
      equals: equals,
      options: options,
    );
  }
}

abstract class BlocSignal<Event, StateType> extends BlocSignalBase<StateType>
    with CubitSignalMixin<StateType>, BlocSignalMixin<Event, StateType> {
  BlocSignal({
    required StateType initialState,
    bool Function(StateType, StateType)? equals,
    SignalOptions<StateType>? options,
  }) {
    initCubitSignal(
      initialState: initialState,
      equals: equals,
      options: options,
    );
  }
}

Because CubitSignalMixin implements BlocSignalBase<StateType>, any class mixing it in is 100% polymorphic with the entire ecosystem:

BlocSignalProvider: Provide your mixed-in class directly with $O(1)$ lookup.
context.select: Fine-grained rebuilds on state sub-properties (context.select<SearchTextEditingController, int>((c) => c.stateValue.results.length)).
blocSignalTest: Declarative unit testing with zero mocking.
bloc_signals_riverpod: Convert mixed-in classes to Riverpod providers via .toProvider().
bloc_signals_hydrate: Add synchronous Frame-1 persistence by adding with HydratedMixin.
bloc_signals_replay: Add undo/redo change history by adding with ReplayMixin.
DevTools Extension: Automatically monitored in the DevTools timeline and instance tree.

📦 Getting Started

CubitSignalMixin and BlocSignalMixin are available now in bloc_signals 1.2.0:

dependencies:
  bloc_signals: ^1.2.0
  bloc_signals_flutter: ^1.2.1

Or install via terminal:

dart pub add bloc_signals
flutter pub add bloc_signals_flutter

Check out the interactive documentation, live demo visualizer, and architectural decision matrix at blocsignal.dev.

💬 Let's Discuss!

Have you run into Dart's single inheritance constraint when building custom Flutter controllers or enterprise repositories? How do you currently bridge TextEditingController or ChangeNotifier into your state management layer?

Drop your thoughts, questions, and feedback in the comments below!

Grand Central Station: Why BLoC, Riverpod, and BlocSignal Are Now True Peers

Randal L. Schwartz — Sun, 30 Aug 2026 01:27:54 +0000

By Randal L. Schwartz, and a few million TPU cycles

Motto: "With the rigor of Bloc and the flex and speed of Signal"

The State Management Balkanization Is Officially Over

If you have spent any time in the Flutter community over the past eight years, you have witnessed the great "State Management Wars."

On one track sat Classic BLoC: strict, battle-tested, enterprise-grade, but heavily reliant on asynchronous Dart Stream microtasks. On an adjacent track sat Riverpod: offering compile-time safety and declarative dependency graph plumbing, but steering increasingly toward mandatory code generation and build_runner iteration tax. On the newest high-speed track arrived Signals: offering raw sub-microsecond synchronous reactivity and fine-grained UI rebuilding.

For years, choosing a state management library felt like choosing an isolated railroad network. If an engineering team built their core application with flutter_bloc or flutter_riverpod and wanted to take advantage of synchronous Signals for a new high-frequency feature, conventional wisdom dictated a painful choice: either undertake a risky, multi-month rewrite or suffer through clunky, second-class adapter boilerplate.

Traditional "interop" packages in our ecosystem have almost always been an afterthought—awkward, leaky wrappers designed to tolerate legacy code until someone finds the budget to delete it.

Today, with the release of bloc_signals_bloc and a major update to bloc_signals_riverpod, we are fundamentally changing that paradigm.

BLoC, Riverpod, and BlocSignal are no longer competing silos. They are first-class, bidirectional peers.

🏛️ The Metaphor: Grand Central State Terminal

Imagine walking into a majestic railway terminal—vaulted glass arches overhead, golden sunbeams cutting through the air, and railway block signal gantries glowing bright green.

Pulling up to the platforms side by side on three parallel steel tracks are three distinct locomotives:

  🚂 Track 1: Classic BLoC (The Steam Locomotive) ─────┐
                                                        │
  🚚 Track 2: Riverpod (The Heavy Freight Hauler) ──────┼──► [ Grand Central State Terminal ] ◄──► Synchronous Signals
                                                        │
  🚄 Track 3: BlocSignal (The High-Speed Maglev) ───────┘

The Steam Locomotive (Classic BLoC): The venerable, heavy-duty iron horse. Explicit event-to-state contracts, distinct mechanical pistons, and a proven safety record powering thousands of enterprise apps.
The Heavy Freight Locomotive (Riverpod): The industrial logistics powerhouse. Unmatched at hauling complex dependency graph freight, managing scoped provider routes, and coordinating global-to-local supply chains.
The High-Speed Maglev (BlocSignal): The aerodynamic bullet train. Zero microtask drag, instant sub-microsecond acceleration, streamless execution, and fine-grained reactivity.

In Grand Central Terminal, the tracks do not collide, and no train is treated as second-class rolling stock. Platforms sit adjacent to each other. Passengers (state, events, actions) walk across the concourse between trains with zero baggage check fees, zero customs delays, and zero microtask penalties.

⚡ What Makes Them "True Peers"?

In most architectures, adapting one state container to another requires wrapping everything in custom StreamController instances, registering manual listener callbacks, and remembering to clean up disposers to prevent memory leaks.

Under BlocSignal, peer integration is completely bidirectional, lifecycle-managed, and type-safe:

From Target ➔ To Target	How It Works	Developer Ergonomics
Classic BLoC ➔ BlocSignal	`classicBloc.toBlocSignal()`	Exposes synchronous `.state` signal + forwards `.add(event)`
Classic Cubit ➔ CubitSignal	`classicCubit.toBlocSignal()`	Exposes synchronous `.state` signal + typed `.cubit` methods
Riverpod Provider ➔ BlocSignal	`provider.toBlocSignal(ref)`	Exposes synchronous `.state` signal + typed `.notifier` methods + auto-disposal
BlocSignal ➔ Classic BLoC	`blocSignal.toClassicBloc()`	Direct drop-in for legacy `flutter_bloc` `BlocBuilder` / `BlocListener`
CubitSignal ➔ Classic Cubit	`cubitSignal.toClassicCubit()`	Direct drop-in for legacy `flutter_bloc` widgets
BlocSignal / CubitSignal ➔ Riverpod	`blocSignal.toProvider()`	Direct drop-in for Riverpod `ref.watch` and `ref.read`
Riverpod `AsyncValue` ↔ Signals `AsyncState`	`.toAsyncState()` / `.toAsyncValue()`	Seamless mapping across sealed loading/error/data states

Let's put this into practice with a concrete example.

☕ The "Grand Central Triple Counter" (Least Boilerplate Possible)

What does it look like when all three state engines work together in a single Flutter screen?

Here is a complete, runnable Flutter app where a Classic BLoC, a Riverpod Notifier, and a Modern CubitSignal live side by side. Each manages its own domain state, yet they compose synchronously into a unified Grand Total using a single computed signal in under 65 lines of code:

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:bloc/bloc.dart' as bloc_lib;
import 'package:bloc_signals/bloc_signals.dart';
import 'package:bloc_signals_bloc/bloc_signals_bloc.dart';
import 'package:bloc_signals_riverpod/bloc_signals_riverpod.dart';
import 'package:signals_flutter/signals_flutter.dart';

// 🚂 1. CLASSIC BLOC: The Steam Engine (Explicit Event -> State)
class ClassicCounterBloc extends bloc_lib.Bloc<int, int> {
  ClassicCounterBloc() : super(0) {
    on<int>((event, emit) => emit(state + event));
  }
}

// 🚚 2. RIVERPOD: The Freight Hauler (Declarative Notifier)
class RiverpodCounter extends Notifier<int> {
  @override
  int build() => 0;
  void increment() => state++;
}
final riverpodCountProvider =
    NotifierProvider<RiverpodCounter, int>(RiverpodCounter.new);

// 🚄 3. BLOCSIGNAL: The High-Speed Maglev (Synchronous Signals)
class ModernSignalCubit extends CubitSignal<int> {
  ModernSignalCubit() : super(initialState: 0);
  void increment() => emit(stateValue + 1);
}

// 🏛️ GRAND CENTRAL TERMINAL: The Peer Counter Screen
class GrandCentralCounterScreen extends ConsumerWidget {
  const GrandCentralCounterScreen({
    super.key,
    required this.classicBloc,
    required this.signalCubit,
  });

  final ClassicCounterBloc classicBloc;
  final ModernSignalCubit signalCubit;

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 🔀 Adapt BLoC and Riverpod into first-class signal peers:
    final blocPeer = classicBloc.toBlocSignal();
    final riverpodPeer = riverpodCountProvider.toBlocSignal(ref);

    // ⚡ Synchronously compute the Grand Total across all three rail lines:
    final grandTotal = computed(
      () => blocPeer.state() + riverpodPeer.state() + signalCubit.state(),
    );

    return Scaffold(
      appBar: AppBar(title: const Text('Grand Central State Terminal')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('🚂 Classic BLoC Count: ${blocPeer.stateValue}'),
            Text('🚚 Riverpod Count: ${riverpodPeer.stateValue}'),
            Text('🚄 BlocSignal Count: ${signalCubit.stateValue}'),
            const Divider(height: 32, indent: 64, endIndent: 64),
            // Reactively updates the instant ANY train leaves its station!
            Watch((context) => Text(
              '🏁 Grand Total: ${grandTotal()}',
              style: Theme.of(context).textTheme.headlineMedium,
            )),
          ],
        ),
      ),
      floatingActionButton: Row(
        mainAxisAlignment: MainAxisAlignment.end,
        children: [
          FloatingActionButton.extended(
            heroTag: 'bloc',
            label: const Text('+1 BLoC'),
            onPressed: () => blocPeer.add(1),
          ),
          const SizedBox(width: 8),
          FloatingActionButton.extended(
            heroTag: 'riverpod',
            label: const Text('+1 Riverpod'),
            onPressed: () => riverpodPeer.notifier.increment(),
          ),
          const SizedBox(width: 8),
          FloatingActionButton.extended(
            heroTag: 'signal',
            label: const Text('+1 Signal'),
            onPressed: () => signalCubit.increment(),
          ),
        ],
      ),
    );
  }
}

void main() {
  // Initialize classic BLoC and modern CubitSignal instances:
  final classicBloc = ClassicCounterBloc();
  final signalCubit = ModernSignalCubit();

  runApp(
    // Wrap with Riverpod's ProviderScope at the application root:
    ProviderScope(
      child: MaterialApp(
        debugShowCheckedModeBanner: false,
        home: GrandCentralCounterScreen(
          classicBloc: classicBloc,
          signalCubit: signalCubit,
        ),
      ),
    ),
  );
}

Why This Integration Is Revolutionary:

Bidirectional Control via Typed Getters:
- blocPeer.add(1) dispatches directly into the underlying classic Bloc event queue.
- riverpodPeer.notifier.increment() calls the underlying RiverpodCounter methods with full type safety.
- signalCubit.increment() triggers immediate synchronous signal emission.
Lifecycle Auto-Wiring:
- counterProvider.toBlocSignal(ref) automatically registers ref.onDispose to close the underlying bridge when the widget or provider scope unmounts. No memory leaks.
Synchronous Cross-Framework Composition:
- Look at grandTotal: computed(() => blocPeer.state() + riverpodPeer.state() + signalCubit.state()).
- A single computed signal observes state originating in package:bloc, package:riverpod, and package:bloc_signals simultaneously. When any of the three states update, grandTotal recalculates in the exact same frame with zero microtask queue hops.

🔄 The Return Trip: Exporting BlocSignal to Legacy Trees

Peer status is not a one-way street. What if you build a cutting-edge feature using modern BlocSignal containers, but you need to embed it inside an existing application that relies entirely on flutter_bloc's BlocBuilder or Riverpod's ConsumerWidget?

You don't need to rewrite your containers!

1. Modern BlocSignal ➔ Classic `flutter_bloc` Trees

final modernCubit = ModernSignalCubit();

// Adapt to a classic flutter_bloc Cubit:
final classicCubit = modernCubit.toClassicCubit();

// Consume directly inside existing flutter_bloc widgets with standard types:
BlocBuilder<bloc_lib.Cubit<int>, int>(
  bloc: classicCubit,
  builder: (context, state) => Text('Legacy BLoC UI: $state'),
);

2. Modern BlocSignal ➔ Riverpod `ProviderScope` Trees

final modernCubit = ModernSignalCubit();

// Expose modern CubitSignal as a standard Riverpod NotifierProvider:
final myRiverpodProvider = modernCubit.toProvider();

// In any Riverpod ConsumerWidget:
Widget build(BuildContext context, WidgetRef ref) {
  final count = ref.watch(myRiverpodProvider);
  return ElevatedButton(
    onPressed: () => ref.read(myRiverpodProvider.notifier).cubit.increment(),
    child: Text('Riverpod UI: $count'),
  );
}

🎯 What This Means for Engineering Teams

This architectural milestone eliminates the single largest point of friction in Flutter development:

No More All-or-Nothing Rewrites: You can introduce BlocSignal into a massive legacy Riverpod or BLoC production codebase one screen, one dialog, or one widget at a time.
Respect for Established Code: Your battle-tested classic BLoC authentication flows or Riverpod dependency injection graphs do not need to be touched. They plug directly into synchronous signal pipelines as first-class citizens.
Freedom of Choice for Greenfield Features: For new, high-performance features (for example complex forms, real-time dashboards, charts, animations, or web components), your team can leverage zero-codegen, streamless BlocSignal containers with sub-microsecond rendering speed.
Clean AI Coding Skills for Interop and Migration: We provide official, pre-packaged AI coding skill bundles that guide AI assistants (such as Antigravity, Claude Code, Gemini, and Cursor) with exact bidirectional rules, decision trees, and step-by-step migration recipes without hallucinations.

🏁 All Aboard at Grand Central

State management in Flutter does not have to be an ideological battleground.

Whether your architecture runs on the Classic BLoC Iron Horse, the Riverpod Freight Hauler, or the BlocSignal Bullet Train, Grand Central Terminal ensures green lights across all lines.

To get started today, add the peer packages to your pubspec.yaml:

dependencies:
  bloc_signals: ^1.0.0
  bloc_signals_bloc: ^1.0.0      # For Classic BLoC peer bridges
  bloc_signals_riverpod: ^1.2.0  # For Riverpod peer bridges
  bloc_signals_flutter: ^1.0.0   # For Flutter widget bindings

Check out the complete documentation, interactive API catalogs, and live showcase apps at blocsignal.dev.

See you on the tracks!

Mechanically Eliminating FutureBuilder & StreamBuilder: Universal Signal, Future, and Stream Adapters in BlocSignal

Randal L. Schwartz — Fri, 28 Aug 2026 21:32:56 +0000

Making the Migration from In-View Asynchrony to Synchronous State Management Truly Mechanical

After our recent discussions on why FutureBuilder and StreamBuilder are architectural anti-patterns when placed inside Flutter widget trees, I started thinking: how can we make it even easier—even completely mechanical—to convert from a FutureBuilder or StreamBuilder to a BlocSignalBuilder?

Every Flutter developer knows the history. Years ago, I recorded a video breaking down the hidden traps of placing asynchronous builders in UI views: Why you shouldn't put FutureBuilder in your build method. Even the original official Flutter video on FutureBuilder initially instantiated the network future directly inside the build() method, until I filed an issue to get it corrected (which is why the official Flutter YouTube video still proudly bears "Take 2" on its clapperboard!).

The fundamental issue has never been that developers want bad architecture. The issue was friction.

FutureBuilder was simply the path of least resistance. To do it "properly" in traditional state management, developers had to create an entire BLoC or Cubit, declare separate Event and State classes (or union types), write boilerplate event handlers, wire asynchronous repository methods, manage subscription lifecycles, and inject everything into the widget tree.

With bloc_signals 1.1.0, that friction disappears completely.

We have introduced universal, symmetrical adapter extensions that allow any Dart Future, Stream, ReadonlySignal, or lifted primitive (value.$) to adapt into a synchronous BlocSignalBase container with a single method call.

🧭 The Universal Dual-Track Mental Model

When bridging asynchronous sources into synchronous state management, developers typically have one of two distinct intents:

Raw Domain Values (T): You want raw domain objects (for example int, UserProfile, ThemeMode) with zero wrapper ceremony, and you have an immediate default or fallback value for frame 0.
Rich Asynchronous Lifecycle States (AsyncState<T>): You want first-class lifecycle tracking (AsyncLoading → AsyncData or AsyncError) with exhaustive pattern matching.

To make the API completely intuitive and predictable, BlocSignal adheres to the Universal Dual-Track Principle:

┌────────────────────────────────────────────────────────────────────────┐
│                   BlocSignal Universal Adapter Matrix                  │
├───────────────────────────────┬────────────────────────────────────────┤
│ Method                        │ Resulting Container Type               │
├───────────────────────────────┼────────────────────────────────────────┤
│ .toBlocSignal(...)            │ BlocSignalBase<T> (Raw domain state)   │
│ .toAsyncBlocSignal(...)       │ BlocSignalBase<AsyncState<T>> (Async)  │
└───────────────────────────────┴────────────────────────────────────────┘

Let us examine how each track works.

⚡ Track 1: Direct Raw Domain State (`.toBlocSignal`)

The .toBlocSignal(...) family strictly yields a BlocSignalBase<T> holding raw values of type T.

1. Adapting `ReadonlySignal<T>` & Lifted Primitives

Because signals in the signals_core graph always hold an immediate synchronous value, converting any signal to a BlocSignalBase requires no arguments:

// 1. Raw Signal -> BlocSignalBase<int>
final countSignal = signal(0);
final countBloc = countSignal.toBlocSignal();

// 2. Computed Expression -> BlocSignalBase<bool>
final isValidSignal = computed(() => username().isNotEmpty && password().length >= 8);
final authBloc = isValidSignal.toBlocSignal();

// 3. Lifted Primitive -> BlocSignalBase<double>
final priceBloc = 49.99.$.toBlocSignal();

The resulting SignalBlocSignal<T> subscribes directly to the underlying signal graph and emits synchronous state transitions whenever the source signal mutates. Calling close() on the container automatically unsubscribes the effect.

2. Adapting `Future<T>` with a Required Initial State

Futures do not have a synchronous value on frame 0. Therefore, when requesting raw domain values of type T, Future.toBlocSignal() requires an explicit initialState::

// Future<User> -> BlocSignalBase<User>
final userBloc = api.fetchUserProfile(userId).toBlocSignal(
  initialState: User.anonymous(),
);

On frame 0, userBloc.stateValue is immediately User.anonymous(). As soon as the future completes, it emits the resolved User synchronously into the state machine. If the future throws, the error is routed safely to onError() and the container's registered BlocObserver.

3. Adapting `Stream<T>` with a Required Initial State

Similarly, any multi-value Stream<T> (such as a WebSocket, sensor stream, or legacy BLoC/Redux stream) adapts with a required initial value:

// Stream<int> -> BlocSignalBase<int>
final counterBloc = myStream.toBlocSignal(initialState: 0);

// Redux Store -> BlocSignalBase<AppState>
final reduxBloc = store.onChange.toBlocSignal(
  initialState: store.state,
);

🔄 Track 2: Rich Asynchronous State (`.toAsyncBlocSignal`)

When you do not have an initial fallback value and want first-class loading, data, and error states, .toAsyncBlocSignal() converts Future<T> and Stream<T> into a BlocSignalBase<AsyncState<T>>.

// 1. Future<UserProfile> -> BlocSignalBase<AsyncState<UserProfile>>
final userProfileBloc = api.fetchUserProfile(userId).toAsyncBlocSignal();

// 2. Stream<List<ChatMessage>> -> BlocSignalBase<AsyncState<List<ChatMessage>>>
final chatBloc = chatSocket.messageStream.toAsyncBlocSignal();

The state lifecycle is completely automatic:

Frame 0: Starts synchronously in AsyncLoading().
On Resolution / Emission: Synchronously transitions to AsyncData(value).
On Failure / Error: Synchronously transitions to AsyncError(error, stackTrace).

💡 Bonus Win: Goodbye to Async Singleton Boilerplate (Inherently Lazy State)

Think for a moment about how Flutter applications traditionally handled an asynchronous resource with a fallback default. You often had to write 30+ lines of fragile singleton and ChangeNotifier plumbing:

// 😩 The old way: Fragile singleton boilerplate with mutable async init
class UserManager extends ChangeNotifier {
  UserManager._() { _init(); }
  static final instance = UserManager._();

  User _user = User.anonymous();
  User get user => _user;
  bool _loading = true;

  Future<void> _init() async {
    try {
      _user = await api.fetchUser();
    } finally {
      _loading = false;
      notifyListeners();
    }
  }
}

Compare that ceremony with BlocSignal:

// 🪄 The BlocSignal way: 1 declarative expression
final userBloc = api.fetchUserProfile(userId).toBlocSignal(
  initialState: User.anonymous(),
);

Even better: it is inherently lazy.

Because top-level variables and late fields in Dart are evaluated on demand:

Zero Application Startup Cost: Defining top-level or module-level state containers does not execute during void main(). If the user never navigates to that screen or feature, the network request is never fired and no resources are wasted.
Signal-Graph Laziness: In .toAsyncBlocSignal(), the underlying FutureSignal defaults to lazy: true, meaning evaluation only triggers when an active UI consumer or test actually reads the signal.
No async main() Initialization Bottlenecks: You no longer need to stall app startup with await initAllServices() before runApp(). Features initialize on demand on the exact frame they are requested.

The Mindblowing Part: Reactive Dependency Chains

What if userId is dynamic (for example derived from an auth session, a route parameter, or a dropdown selection)?

You can wire it directly into the reactive dependency graph:

// 1. Upstream reactive dependency:
final selectedUserId = signal<String>('42');

// 2. Downstream async pipeline — automatically refetches when selectedUserId changes:
final userProfileBloc = futureSignal(
  () => api.fetchUserProfile(selectedUserId()),
).toBlocSignal();

When selectedUserId.value = '99' changes anywhere in your app, the futureSignal automatically detects the dependency change, refetches the profile, and emits state transitions through userProfileBloc directly into your BlocSignalBuilder—with zero manual listeners, zero event dispatch plumbing, and zero didUpdateWidget lifecycle gymnastics.

🛠️ Step-by-Step Conversion 1: Eliminating `FutureBuilder`

Let us take a real-world example of FutureBuilder and see how clean and non-scary it is to replace it.

The Legacy Anti-Pattern (`FutureBuilder`)

Here is the classic code that lives in thousands of Flutter codebases:

// ❌ ANTI-PATTERN: Trapping async I/O inside the widget tree
class UserProfilePage extends StatelessWidget {
  const UserProfilePage({super.key, required this.userId});
  final String userId;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('User Profile')),
      body: FutureBuilder<UserProfile>(
        // ⚠️ DANGER: Re-invoked on every parent rebuild!
        future: apiClient.fetchUserProfile(userId),
        builder: (context, snapshot) {
          if (snapshot.connectionState == ConnectionState.waiting) {
            return const Center(child: CircularProgressIndicator());
          }
          if (snapshot.hasError) {
            return Center(child: Text('Error: ${snapshot.error}'));
          }
          if (snapshot.hasData) {
            final user = snapshot.data!;
            return ProfileView(user: user);
          }
          return const SizedBox.shrink();
        },
      ),
    );
  }
}

The Clean, Non-Scary Refactor

Instead of wrapping the view in complex provider nesting, we simply pass the adapted container directly into our view widget via constructor parameters (clean prop-drilling):

// 1. At the route boundary, controller, or parent widget:
final userProfileBloc = apiClient.fetchUserProfile(userId).toAsyncBlocSignal();

// 2. Pass it directly to the view:
UserProfilePage(userProfileBloc: userProfileBloc);

Our presentation widget becomes a pure, lightweight StatelessWidget:

// ✅ BLOCSIGNAL PATTERN: Clean, synchronous projection of state
class UserProfilePage extends StatelessWidget {
  const UserProfilePage({
    super.key, 
    required this.userProfileBloc,
  });

  final BlocSignalBase<AsyncState<UserProfile>> userProfileBloc;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('User Profile')),
      body: BlocSignalBuilder(
        bloc: userProfileBloc,
        builder: (context, state) => switch (state) {
          AsyncData(:final value) => ProfileView(user: value),
          AsyncLoading() => const Center(child: CircularProgressIndicator()),
          AsyncError(:final error) => Center(child: Text('Error: $error')),
        },
      ),
    );
  }
}

Look at how clear that is!

There are no nested InheritedWidget provider trees or noisy generic boilerplate. Type inference handles the builder automatically.

Note on Dependency Injection: Because BlocSignal containers are pure Dart objects with zero framework baggage, you can supply them using whichever DI strategy fits your project: simple constructor prop-drilling (as shown above), top-level globals, service locators (such as GetIt), BlocSignalProvider, or Riverpod adapters.

What You Just Won:

Zero Accidental Refetches: If the software keyboard opens, an animation ticks, or the device rotates, build() re-runs synchronously without dispatching a new HTTP request.
Exhaustive Safety: The compiler verifies that you handled AsyncLoading, AsyncData, and AsyncError. No more forgetting edge cases or dealing with force unwraps (snapshot.data!).
0ms Synchronous Testability: In unit tests, you can test userProfileBloc with blocSignalTest in 0ms without mocking microtask timers or calling tester.pumpAndSettle().

🌊 Step-by-Step Conversion 2: Eliminating `StreamBuilder`

Now let us look at StreamBuilder.

The Legacy Anti-Pattern (`StreamBuilder`)

// ❌ ANTI-PATTERN: Stream subscription lifecycle entangled with widget tree
class DeviceTemperatureWidget extends StatelessWidget {
  const DeviceTemperatureWidget({super.key, required this.sensorService});
  final SensorService sensorService;

  @override
  Widget build(BuildContext context) {
    return StreamBuilder<double>(
      stream: sensorService.temperatureStream,
      builder: (context, snapshot) {
        if (!snapshot.hasData) {
          return const Text('Reading sensor...');
        }
        return Text('${snapshot.data!.toStringAsFixed(1)}°C');
      },
    );
  }
}

The Clean Refactor with `.toBlocSignal()`

If you have a sensible initial value (for example 0.0), adapt the stream directly to a raw domain container and pass it straight into your widget:

// ✅ OPTION A: Raw Domain State with explicit initial value
class DeviceTemperatureWidget extends StatelessWidget {
  const DeviceTemperatureWidget({
    super.key, 
    required this.temperatureBloc,
  });

  final BlocSignalBase<double> temperatureBloc;

  @override
  Widget build(BuildContext context) {
    return BlocSignalBuilder(
      bloc: temperatureBloc,
      builder: (context, temperature) {
        return Text('${temperature.toStringAsFixed(1)}°C');
      },
    );
  }
}

Or, if you prefer rich async lifecycle tracking:

// ✅ OPTION B: Rich Async Lifecycle State
class DeviceTemperatureWidget extends StatelessWidget {
  const DeviceTemperatureWidget({
    super.key, 
    required this.temperatureBloc,
  });

  final BlocSignalBase<AsyncState<double>> temperatureBloc;

  @override
  Widget build(BuildContext context) {
    return BlocSignalBuilder(
      bloc: temperatureBloc,
      builder: (context, state) => switch (state) {
        AsyncData(:final value) => Text('${value.toStringAsFixed(1)}°C'),
        AsyncLoading() => const Text('Reading sensor...'),
        AsyncError(:final error) => Text('Sensor offline: $error'),
      },
    );
  }
}

🧪 Testing: From Async Pump Hell to 0ms Determinism

Consider the difference in testability.

Testing a `FutureBuilder` Widget

// ⚠️ Fragile, slow, timer-dependent
testWidgets('renders user profile', (tester) async {
  await tester.pumpWidget(UserProfilePage(
    userProfileBloc: Future.value(mockUser).toAsyncBlocSignal(),
  ));

  // Instant synchronous verification of the initial loading state:
  expect(find.byType(CircularProgressIndicator), findsOneWidget);

  // Settle completion cleanly:
  await tester.pump();
  expect(find.text('Alice'), findsOneWidget);
});

Testing the `BlocSignal` Adapter Unit

Because BlocSignal operates synchronously with 0ms microtask delays, testing state transitions is declarative and instantaneous:

// ✅ Fast, synchronous, 100% deterministic
blocSignalTest<SignalBlocSignal<AsyncState<String>>, AsyncState<String>>(
  'emits AsyncLoading then AsyncData on future completion',
  build: () => Future.value('Alice').toAsyncBlocSignal(),
  wait: const Duration(milliseconds: 10),
  expect: () => [
    isA<AsyncLoading<String>>(),
    isA<AsyncData<String>>().having((s) => s.value, 'value', 'Alice'),
  ],
);

🌌 Like the Force: Binding the Galaxy Together

In modern application engineering, you will inevitably interact with diverse reactive abstractions:

Third-party SDKs that return Future<T>.
Hardware APIs and WebSockets that stream Stream<T>.
Reactive view models built with Signal<T> or Computed<T>.
Classic legacy state stores built with BLoC or Redux.

BlocSignal does not force you to rewrite your entire data layer or choose between the discipline of unidirectional data flow and the speed of fine-grained signals.

With .toBlocSignal() and .toAsyncBlocSignal(), every asynchronous stream, future, and signal in your architecture adapts seamlessly into a synchronous, predictable, 0ms reactive state machine.

Try out bloc_signals 1.1.0 today:

dependencies:
  bloc_signals: ^1.1.0
  bloc_signals_flutter: ^1.1.0

Happy coding!

FutureBuilder and StreamBuilder as Anti-Patterns: Why Your Async Boundary Should Be Far Away From Your Views

Randal L. Schwartz — Wed, 26 Aug 2026 23:09:28 +0000

Why Raw Asynchrony Inside the Presentation Layer Breaks Separation of Concerns, User Experience, and Testability

Every Flutter developer remembers the magic of their first FutureBuilder.

You paste an HTTP request directly into a FutureBuilder inside your widget's build() method, configure a CircularProgressIndicator for ConnectionState.waiting, render your data in ConnectionState.done, and suddenly your app is alive with real-time data in fewer than twenty lines of code.

It feels like superpowers. The official documentation features it. Introductory tutorials celebrate it.

And then your application grows.

Suddenly, users report that typing into a text field causes the entire screen to reload and fetch fresh data from the server. Opening the keyboard triggers duplicate network requests. Sibling widgets flicker and jump across the screen as independent async calls resolve out of order. And writing automated widget tests turns into an exhausting battle with tester.pumpAndSettle(), fake async timers, and microtask queues.

This problem happened often enough across the Flutter community that I recorded a video explaining why it happens and how to fix it: Why you shouldn't put FutureBuilder in your build method. In fact, the very first version of the official Flutter FutureBuilder documentation video got this exact pattern wrong by instantiating the future inside build(), until I filed an issue against the Flutter repository to get it corrected (the current official video on the Flutter YouTube channel even prominently displays "Take 2" on the clapperboard as proof!).

What began as a helpful convenience widget quickly turns into an architectural trap.

In this article, we examine why FutureBuilder and StreamBuilder are architectural anti-patterns when used for application state, explore the four fatal flaws of in-view asynchrony, and demonstrate how to push asynchronous boundaries to the edge of your architecture using AsyncSignal, CubitSignal, and BlocSignal.

🚨 The Core Problem: The Failure of In-View Asynchrony

To understand why FutureBuilder fails at scale, we must return to the foundational principle of Flutter UI engineering:

UI = ƒ(State)

Flutter widgets are designed to be pure, synchronous projections of state. Given a snapshot of data at time t, a widget function should execute synchronously, instantiate a subtree of render objects, and return immediately.

When you drop a FutureBuilder or StreamBuilder directly into your widget tree, you violate this contract. You introduce raw time, transport mechanics, and asynchronous lifecycle orchestration directly into the presentation layer.

Let us break down the four fatal flaws that emerge from this architectural choice.

┌─────────────────────────────────────────────────────────┐
│               The In-View Asynchrony Trap               │
│                                                         │
│  Widget.build()                                         │
│    │                                                    │
│    ├──> Instantiates Future on every build frame ⚠️      │
│    ├──> Orchestrates ConnectionState & HTTP errors ⚠️   │
│    ├──> Triggers uncoordinated layout shifts ⚠️          │
│    └──> Requires multi-pump async widget tests ⚠️       │
└─────────────────────────────────────────────────────────┘

1. Layering Collapse & State Management via Widgets

In a clean layered architecture (such as Domain ← Data ← Application ← Presentation), the presentation layer has exactly one job: translating domain state into visual UI elements.

When a widget embeds a FutureBuilder, that widget suddenly takes on massive orchestration responsibilities:

Connection State Management: Manually inspecting snapshot.connectionState == ConnectionState.waiting, ConnectionState.active, and ConnectionState.done.
Error & Exception Handling: Decoding HTTP 500 errors, socket timeouts, and parsing exceptions inside if (snapshot.hasError).
Caching & Retention: Deciding whether previous data should remain visible while a refresh is in progress or wiped out in favor of a spinner.
Retry Coordination: Wiring reload buttons that must somehow re-trigger the widget's internal asynchronous future.

Your presentation widgets are no longer views; they have become ad-hoc state managers and network controllers.

2. The Re-Execution & Accidental Refetch Trap

Consider the most common bug written by junior and intermediate Flutter developers:

// ❌ ANTI-PATTERN: Re-executing network calls on every rebuild
class UserProfileView extends StatelessWidget {
  const UserProfileView({super.key, required this.userId});

  final String userId;

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<UserProfile>(
      // ⚠️ DANGER: Called on EVERY build frame!
      future: httpApiClient.fetchProfile(userId),
      builder: (context, snapshot) {
        if (snapshot.connectionState == ConnectionState.waiting) {
          return const CircularProgressIndicator();
        }
        if (snapshot.hasError) {
          return Text('Error: ${snapshot.error}');
        }
        return ProfileContent(profile: snapshot.data!);
      },
    );
  }
}

Whenever this widget's parent rebuilds—whether because an ancestor animated, a theme changed, the device rotated, or the software keyboard opened—Flutter calls build().

Every invocation of build() creates a brand-new Future instance. The previous request is abandoned, a new HTTP request is dispatched across the network, and the UI immediately flashes back to CircularProgressIndicator.

The Flawed "StatefulWidget Fix"

Developers often attempt to patch this by converting the view to a StatefulWidget and caching the future in initState():

// ⚠️ NOISY WORKAROUND: Bloating the UI with lifecycle ceremony
class UserProfileView extends StatefulWidget {
  const UserProfileView({super.key, required this.userId});

  final String userId;

  @override
  State<UserProfileView> createState() => _UserProfileViewState();
}

class _UserProfileViewState extends State<UserProfileView> {
  late Future<UserProfile> _profileFuture;

  @override
  void initState() {
    super.initState();
    _profileFuture = httpApiClient.fetchProfile(widget.userId);
  }

  @override
  void didUpdateWidget(UserProfileView oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (oldWidget.userId != widget.userId) {
      _profileFuture = httpApiClient.fetchProfile(widget.userId);
    }
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<UserProfile>(
      future: _profileFuture,
      builder: (context, snapshot) {
        /* ... */
      },
    );
  }
}

While this prevents duplicate fetches on rebuild, look at the architectural cost:

You have introduced mutable lifecycle state (_profileFuture, initState, didUpdateWidget) into what should have been a simple display widget.
The data is trapped inside private widget state _UserProfileViewState. Sibling widgets, app bars, and global analytics cannot read or coordinate with this data.
If the user navigates away and returns, the state is destroyed and refetched from scratch.

3. Uncoordinated UI Cascades & Layout Shift (The "Spinner Storm")

Real-world applications rarely fetch a single piece of data on a screen. A dashboard might require user profile information, unread notifications, recent transactions, and recommended items.

When each of these sections manages its own FutureBuilder or StreamBuilder, they resolve asynchronously at unpredictable microtask intervals.

Frame 1:  [ Profile Spinner ]   [ Notifications Spinner ]   [ Orders Spinner ]
Frame 12: [ Profile Header  ]   [ Notifications Spinner ]   [ Orders Spinner ]  <-- Layout Shift!
Frame 19: [ Profile Header  ]   [ Notifications (0)     ]   [ Orders Spinner ]  <-- Layout Shift!
Frame 34: [ Profile Header  ]   [ Notifications (0)     ]   [ Orders List    ]  <-- Layout Shift!

This causes what designers call The Spinner Storm:

Intermediate progress indicators flash and pop independently.
Content jumps vertically as sections expand at varying millisecond timestamps (causing severe Cumulative Layout Shift).
If one child request fails with an error, half the screen renders data while the other half renders an isolated red error banner.

4. Untestable Views & Async Pump Gymnastics

Try writing a widget test for a screen populated with FutureBuilder widgets:

// ❌ FRAGILE & SLOW: Async pump loops and timing dependencies
testWidgets('renders user profile after loading', (tester) async {
  await tester.pumpWidget(
    const MaterialApp(
      home: UserProfileView(userId: 'user-123'),
    ),
  );

  // Expect loading indicator
  expect(find.byType(CircularProgressIndicator), findsOneWidget);

  // Must drain microtasks and wait for asynchronous network mocks
  await tester.pumpAndSettle();

  // Expect content
  expect(find.text('Jane Doe'), findsOneWidget);
});

Because the widget itself creates and awaits the Future, your widget test cannot simply supply data to the view. Instead, your test must:

Mock the low-level HTTP client or transport layer.
Carefully drain microtasks and fake timers with tester.pumpAndSettle().
Suffer from flaky CI runs when asynchronous timers fail to settle within arbitrary timeouts.

🛡️ The Architectural Solution: Async at the Edge, Synchronous in the Core

The solution to in-view asynchrony is straightforward:

Push the asynchronous boundary as far away from the presentation layer as possible. Quarantine raw I/O strictly at the infrastructure perimeter, coordinate state in pure domain controllers, and deliver deterministic, synchronous states to the views.

┌─────────────────────────────────────────────────────────┐
│               External I/O Perimeter                    │
│   (REST APIs, WebSockets, Databases, Hardware Sensors)  │
└────────────────────────────┬────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────┐
│              Data & Repository Layer                    │
│   (AsyncSignal / FutureSignal / StreamSignal / .$)      │
└────────────────────────────┬────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────┐
│                Domain & Logic Layer                     │
│    (CubitSignal / BlocSignal — Synchronous Core)        │
└────────────────────────────┬────────────────────────────┘
                             │
                             ▼ (Synchronous 0ms Frame Propagation)
┌─────────────────────────────────────────────────────────┐
│                 Presentation Layer                      │
│    (BlocSignalBuilder / context.select() / Pure UI)     │
└─────────────────────────────────────────────────────────┘

In this architecture:

The Data Layer wraps asynchronous operations in reactive signals (FutureSignal, StreamSignal, or the concise .$ extension).
The Domain Layer (CubitSignal / BlocSignal) coordinates these edge signals, manages caching and error boundaries, and emits explicit, immutable state models (AsyncState<T>).
The Presentation Layer binds to state synchronously. It never touches a Future or Stream. On any given frame, the widget reads the current state snapshot and returns its widget tree with zero latency.

💡 Step-by-Step Implementation with BlocSignal

Let us walk through building a complete, production-grade profile screen using this pattern.

Step 1: Async at the Edge (Data & Repository Layer)

At the repository perimeter, we wrap raw asynchronous futures or streams using futureSignal, streamSignal, or the .toSignal() extension:

// data/user_repository.dart
import 'package:signals_core/signals_core.dart';

class UserProfile {
  const UserProfile({
    required this.id,
    required this.name,
    required this.email,
  });

  final String id;
  final String name;
  final String email;
}

abstract class UserRepository {
  FutureSignal<UserProfile> getProfile(String userId);
}

class HttpUserRepository implements UserRepository {
  const HttpUserRepository({required this.apiClient});

  final ApiClient apiClient;

  @override
  FutureSignal<UserProfile> getProfile(String userId) {
    // Quarantine async promise into a reactive FutureSignal at the edge
    return futureSignal(() => apiClient.fetchUserProfile(userId));

    // 💡 Shorthand alternative: You can also use the concise .toSignal() extension!
    // return apiClient.fetchUserProfile(userId).toSignal();
  }
}

Notice what happens here:

HttpUserRepository returns a FutureSignal<UserProfile>.
The async I/O is wrapped at the perimeter. Downstream consumers can read the current AsyncState<UserProfile> synchronously at any time via signal.value without awaiting a Future.
Ultra-concise ergonomics: In addition to futureSignal(...), signals_core provides clean extension shorthands: use .toSignal() on any Future or Stream (such as apiClient.fetchUserProfile(userId).toSignal()) to lift async primitives into reactive signals, and .$ on standard values (such as 0.$ or 'initial'.$) for instant signal creation.

💡 The Hidden Superpower: Built-In `try/catch` Encapsulation

Consider how much repetitive plumbing developers typically write for every single HTTP endpoint:

// 😩 THE OLD CEREMONY: Manual try/catch boilerplate for EVERY endpoint
Future<void> fetchProfile() async {
  emit(const ProfileLoading());
  try {
    final profile = await apiClient.fetchProfile(userId);
    emit(ProfileLoaded(profile));
  } catch (error, stackTrace) {
    emit(ProfileError(error.toString()));
  }
}

If you forget that try/catch block on even one endpoint, an unexpected socket failure, DNS error, or HTTP 500 will bubble up as an unhandled asynchronous exception and crash your isolate.

futureSignal eliminates this entire class of errors. Under the hood, futureSignal automatically runs the callback inside a built-in try/catch quarantine:

Automatic Error Containment: Any network timeout, bad status code, or JSON parsing exception is caught at the perimeter and converted into an AsyncError<T>(error, stackTrace).
Zero Uncaught Promise Rejections: You never have unhandled asynchronous exceptions crashing the isolate or polluting terminal logs.
Deterministic State Modeling: The error and its stack trace become first-class data inside the synchronous AsyncState snapshot, ready to be pattern-matched downstream with zero boilerplate.

Step 2: Clean State Coordination in `CubitSignal` (Domain Layer)

Next, our domain state container (CubitSignal) consumes the edge signal. It manages user intents (such as manual refreshing) and exposes the current AsyncState to the UI:

Traditional Dart 3.5 Syntax:

// domain/profile_cubit.dart
import 'package:bloc_signals/bloc_signals.dart';
import 'package:signals_core/signals_core.dart';

class ProfileCubit extends CubitSignal<AsyncState<UserProfile>> {
  ProfileCubit({
    required UserRepository repository,
    required String userId,
  })  : _profileSignal = repository.getProfile(userId),
        super(initialState: const AsyncState.loading()) {
    // Synchronously propagate state changes whenever the edge signal emits
    createEffect(() => emit(_profileSignal.value));
  }

  final FutureSignal<UserProfile> _profileSignal;

  /// Refreshes the profile by triggering the edge signal's reload
  void refresh() => _profileSignal.refresh();
}

Modern Dart 3.13 Syntax (Primary Constructor):

// domain/profile_cubit.dart
import 'package:bloc_signals/bloc_signals.dart';
import 'package:signals_core/signals_core.dart';

class ProfileCubit(
  UserRepository repository, {
  required String userId,
}) : super(initialState: const AsyncState.loading()) {
  final _profileSignal = repository.getProfile(userId);

  this {
    createEffect(() => emit(_profileSignal.value));
  }

  void refresh() => _profileSignal.refresh();
}

Step 3: Pure Synchronous Rendering in the View (Presentation Layer)

Now, look at the presentation view. The view contains zero asynchronous code. It does not know what an HTTP request is, it does not manage ConnectionState, and it cannot accidentally re-trigger network calls:

// presentation/profile_view.dart
import 'package:bloc_signals_flutter/bloc_signals_flutter.dart';
import 'package:flutter/material.dart';

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('User Profile'),
        actions: [
          IconButton(
            icon: const Icon(Icons.refresh),
            onPressed: () => context.read<ProfileCubit>().refresh(),
          ),
        ],
      ),
      body: BlocSignalBuilder<ProfileCubit, AsyncState<UserProfile>>(
        builder: (context, state) {
          return state.map(
            data: (profile) => ProfileDetailsCard(profile: profile),
            loading: () => const Center(
              child: CircularProgressIndicator(),
            ),
            error: (error, _) => Center(
              child: Column(
                mainAxisSize: MainAxisSize.min,
                children: [
                  Text(
                    'Failed to load profile: $error',
                    style: const TextStyle(color: Colors.red),
                  ),
                  const SizedBox(height: 12),
                  ElevatedButton(
                    onPressed: () => context.read<ProfileCubit>().refresh(),
                    child: const Text('Retry'),
                  ),
                ],
              ),
            ),
          );
        },
      ),
    );
  }
}

class ProfileDetailsCard extends StatelessWidget {
  const ProfileDetailsCard({super.key, required this.profile});

  final UserProfile profile;

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.all(16),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(profile.name, style: Theme.of(context).textTheme.headlineMedium),
          const SizedBox(height: 8),
          Text(profile.email, style: Theme.of(context).textTheme.bodyLarge),
        ],
      ),
    );
  }
}

🛡️ The True Decoupling Test: Zero Presentation Changes on Transport Swaps

Notice what this architectural separation achieves: if you decide to completely change how profiles are fetched—for example replacing the edge futureSignal with a real-time WebSocket streamSignal, a local SQLite database query, or a manual CubitSignal method that imperatively transitions an AsyncState from loading to data—not a single line of presentation code in ProfileView has to change.

By contrast, with FutureBuilder, you cannot switch to a stream without completely replacing the widget with StreamBuilder, and you cannot switch to a synchronous cache without faking artificial Future.value(...) / Completer wrappers just to satisfy the widget's API.

The BlocSignal view depends strictly on the immutable contract of AsyncState<UserProfile>. Transport mechanics, caching strategies, network protocols, and retry policies can evolve independently behind the domain boundary without touching your UI widgets.

🧹 Zero Manual Dispose Management: Complete Owner-Managed Lifecycles

And notice something equally remarkable: there is no dispose management anywhere in this code. Everything is completely managed by its owner.

In traditional Flutter architectures using streams, ChangeNotifier, or raw state controllers, developers spend an enormous amount of time writing defensive teardown code: canceling StreamSubscription instances, detaching listeners, and debugging subtle memory leaks when a view is popped from the navigator.

In BlocSignal, lifecycle ownership is completely automatic:

Effects are owned by the Cubit: The createEffect registered inside ProfileCubit is bound to the cubit's reactive scope and is automatically disposed when cubit.close() executes.
Views are pure and stateless: ProfileView is a clean StatelessWidget. It holds no subscriptions, maintains no mutable state, and requires zero dispose() boilerplate.
Providers manage container lifecycles: When ProfileCubit is provided by BlocSignalProvider, the provider automatically calls close() when the widget subtree unmounts from the element tree.

You get leak-free, frame-accurate reactivity with zero manual disposal ceremony.

⚖️ Side-by-Side Comparison: Before vs. After

Let us compare the two architectures across every critical engineering metric:

Metric	`FutureBuilder` In-View (Anti-Pattern)	`BlocSignal` Async at Edge (Clean Architecture)
Widget Responsibility	Orchestrates I/O, handles HTTP errors, manages connection state	Pure visual projection of synchronous state
Rebuild Safety	Re-executes network call on every frame unless wrapped in `StatefulWidget`	100% safe; rebuilds only read the current synchronous value
State Sharing	Trapped in local widget subtree; impossible to share with app bar or sibling views	Accessible across the subtree or globally via `CubitSignal` / `BlocSignal`
UI Coordination	Uncoordinated layout shifts and independent spinner flicker	Synchronized state transitions; coordinated multi-signal computed graphs
Unit Testing	Requires mock HTTP servers and asynchronous `tester.pumpAndSettle()`	Instant, synchronous testing with `blocSignalTest` and 0ms widget assertions

🧪 Testing Contrast: Instant Determinism vs. Async Gymnastics

One of the greatest benefits of pushing the async boundary to the edge is how testing is transformed.

1. Unit Testing Domain Logic with `blocSignalTest`

Because CubitSignal manages state transitions deterministically, we can unit test our business logic with blocSignalTest in pure Dart with zero Flutter dependencies:

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

class FakeUserRepository implements UserRepository {
  FakeUserRepository({required this.profileSignal});

  final FutureSignal<UserProfile> profileSignal;

  @override
  FutureSignal<UserProfile> getProfile(String userId) => profileSignal;
}

void main() {
  group('ProfileCubit', () {
    const testUser = UserProfile(
      id: 'usr_1',
      name: 'Alice Smith',
      email: 'alice@example.com',
    );

    test('initial state is AsyncState.loading', () {
      final fakeSignal = futureSignal<UserProfile>(() async => testUser);
      final repo = FakeUserRepository(profileSignal: fakeSignal);
      final cubit = ProfileCubit(repository: repo, userId: 'usr_1');

      expect(cubit.stateValue, isA<AsyncLoading<UserProfile>>());
      cubit.close();
    });

    blocSignalTest<ProfileCubit, AsyncState<UserProfile>>(
      'emits AsyncData when edge signal resolves successfully',
      build: () {
        final fakeSignal = futureSignal<UserProfile>(() async => testUser);
        final repo = FakeUserRepository(profileSignal: fakeSignal);
        return ProfileCubit(repository: repo, userId: 'usr_1');
      },
      wait: const Duration(milliseconds: 10),
      expect: () => [
        isA<AsyncLoading<UserProfile>>(),
        predicate<AsyncState<UserProfile>>(
          (state) => state.value == testUser,
          'contains testUser data',
        ),
      ],
    );
  });
}

2. Instant Synchronous Widget Testing

When testing the presentation view, we do not need to mock network clients, fake HTTP latency, or call tester.pumpAndSettle(). We simply inject a mock or fake ProfileCubit emitting a synchronous state and assert the rendered widget tree in Frame 1:

// test/profile_view_test.dart
import 'package:bloc_signals_flutter/bloc_signals_flutter.dart';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:signals_core/signals_core.dart';

class MockProfileCubit extends CubitSignal<AsyncState<UserProfile>> {
  MockProfileCubit(super.initialState);

  void emitState(AsyncState<UserProfile> state) => emit(state);
}

void main() {
  testWidgets('renders user details immediately when state is AsyncData', (tester) async {
    const user = UserProfile(
      id: 'usr_1',
      name: 'Alice Smith',
      email: 'alice@example.com',
    );

    final mockCubit = MockProfileCubit(const AsyncState.data(user));

    await tester.pumpWidget(
      MaterialApp(
        home: BlocSignalProvider<MockProfileCubit>.value(
          value: mockCubit,
          child: const ProfileView(),
        ),
      ),
    );

    // Assert immediately in Frame 1 with NO pumpAndSettle delay!
    expect(find.text('Alice Smith'), findsOneWidget);
    expect(find.text('alice@example.com'), findsOneWidget);
    expect(find.byType(CircularProgressIndicator), findsNothing);
  });

  testWidgets('renders error banner and retry button when state is AsyncError', (tester) async {
    final mockCubit = MockProfileCubit(
      AsyncState.error(Exception('Network timeout'), StackTrace.empty),
    );

    await tester.pumpWidget(
      MaterialApp(
        home: BlocSignalProvider<MockProfileCubit>.value(
          value: mockCubit,
          child: const ProfileView(),
        ),
      ),
    );

    expect(find.textContaining('Network timeout'), findsOneWidget);
    expect(find.text('Retry'), findsOneWidget);
  });
}

Look at the difference:

0ms execution time: The widget test runs in a single synchronous tick without draining microtask queues.
Zero flakiness: No timers, no race conditions, no unhandled async rejections.
Pure UI verification: The test proves that the UI correctly projects state into pixels, without conflating UI verification with network protocol testing.

🎯 Four Non-Negotiable Rules for Async Flutter Architecture

To maintain clean, scalable Flutter applications, enforce these four golden rules across your team:

Never Instantiate or Await a Future or Stream Inside Widget.build(): Widgets are synchronous projectors of state. If a widget is constructing a future, your architecture has a layering leak.
Quarantine Asynchrony at the Repository Perimeter: Wrap remote APIs, databases, and device sensors in AsyncSignal (futureSignal, streamSignal, or .$) at the data layer boundary.
Coordinate State in Domain Containers: Use CubitSignal for straightforward feature state and BlocSignal for complex, event-driven pipelines. Expose synchronous state models (AsyncState<T> or sealed class hierarchies) to the presentation layer.
Bind Pure Synchronous Views with BlocSignalBuilder: Use BlocSignalBuilder or context.select() to read synchronous snapshots. Let the framework handle de-duplication and granular widget updates.

By keeping your async boundaries at the edge and your core synchronous, your Flutter views remain simple, your state transitions remain predictable, and your user experience stays silky smooth at 120 FPS.

📦 Explore the BlocSignal Ecosystem

Core Package: bloc_signals
Flutter Bindings: bloc_signals_flutter
Testing Utilities: bloc_signals_test
Documentation & Interactive Showcase: blocsignal.dev
GitHub Repository: github.com/RandalSchwartz/BlocSignal

Bridging the AI Cutoff: Teaching Coding Agents Every Dart Feature from 1.0 to 3.14

Randal L. Schwartz — Sat, 22 Aug 2026 20:29:26 +0000

If you use AI coding assistants—whether it is Claude Code, Google Antigravity, OpenAI Codex, GitHub Copilot, Cursor, or Cline—you have likely experienced the Training Cutoff Frustration in Dart and Flutter.

Dart moves fast. Over the last few years, we have seen:

Dart 2.12: Sound Null Safety (?, late, !, required).
Dart 2.17: Super-parameters (super.key) and enhanced enums.
Dart 3.0: Records, pattern matching, switch expressions, and sealed classes (while permanently dropping non-null-safe mode).
Dart 3.12–3.13+: Private named parameters, constructor shorthands, and primary constructors (class Point(var int x, var int y);).

Because pre-training datasets naturally lag behind the bleeding edge, vanilla LLMs frequently:

Reject modern Dart 3.13 syntax as "syntax errors".
Write 15 lines of repetitive constructor and equality boilerplate where modern primary constructors belong.
Mess up the environment.sdk lower bound (minSdk) in pubspec.yaml.
Struggle to rescue pre-2.12 legacy apps because they don't know the exact milestone sequence to cross the null-safety divide.

To solve this once and for all, I extracted and open-sourced dart-sdk-skills.

🎯 What is `dart-sdk-skills`?

dart-sdk-skills is an authoritative, version-by-version skill package designed specifically for AI coding agents.

Rather than dumping thousands of lines into your prompt on every turn, it uses progressive disclosure:

The agent holds a compact, fast Feature Matrix covering every version from Dart 1.0 to 3.14.
When an agent is asked "What's new in Dart 3.13?", "What minSdk do I need for private named parameters?", or "Help me modernize this legacy Flutter app", it dynamically reads the exact changelog reference guide on demand.

🛠️ Two Massive Use Cases

1. Modern Greenfield & Bleeding-Edge Dart 3.13+

Instead of fighting the LLM over modern language ergonomics, your agent immediately knows:

Primary constructors & this : assert(...) bodies.
Wildcard variables (_) and digit separators (1_000_000).
Exact minSdk verification so your pubspec.yaml never breaks CI.

2. Rescuing Legacy Codebases (Dart 1.x & Pre-2.12)

Because Dart 3 completely disallows running without sound null safety, rescuing older codebases requires a strict 4-stage pipeline:

Dart 1.x ➔ 2.0: Drop obsolete new keywords and enforce sound static typing.
Pre-2.12 ➔ 2.12: Transform @required annotations, uninitialized nullable fields, and defensive runtime assertions.
pubspec.yaml: Bump environment lower bound to ^3.5.0 or ^3.13.0 and replace deprecated packages (pedantic, tuple).
Dart 3 Modernization: Adopt super-initializers, sealed classes, and pattern matching.

📦 How to Install (One Command)

You can install dart-sdk-skills globally across all your projects in seconds using any skill package manager:

Using `npx skills` (Universal / Node):

npx skills add RandalSchwartz/dart-sdk-skills -g

Using the Dart `skills` CLI:

skills add https://github.com/RandalSchwartz/dart-sdk-skills --global --all

Once installed, your agent is automatically equipped with the entire Dart SDK knowledge base.

Check out the full repository on GitHub:
👉 https://github.com/RandalSchwartz/dart-sdk-skills

When to Use Bloc vs. Cubit vs. Signal: An Architectural Decision Guide

Randal L. Schwartz — Sat, 22 Aug 2026 02:59:36 +0000

The Flutter State Dilemma

Every Flutter developer eventually wrestles with state management granularity:

"How do I balance developer ergonomics against architectural rigor? When is a simple reactive primitive sufficient, and when do I truly need a structured, event-driven state container?"

For years, developers have swung between two frustrating extremes:

The Over-Engineering Trap: Creating multiple event classes, sealed hierarchies, and asynchronous stream plumbing just to toggle a boolean accordion or expand a card.
The Spaghetti Trap: Relying entirely on untracked, ad-hoc mutable state for complex transactional workflows, leading to race conditions, untraceable mutations, and hard-to-test side effects.

With BlocSignal—which bridges Felix Angelov's BLoC architectural rigor with Rody Davis's Preact Signals v7 engine—we have a unified spectrum. State updates propagate synchronously in 0ms, eliminating microtask queue delays while preserving strict architectural boundaries.

Here is the definitive rubric for picking the exact right container for your state.

The 4-Tier State Hierarchy

Rather than forcing every piece of state into the same mold, view your application as a 4-tier hierarchy:

[Raw Signal / computed()]        --> Local widget micro-state & derived calculations
       │
[CubitSignal<State>]             --> Feature domain logic & CRUD with direct method calls
       │
[BlocSignal<Event, State>]       --> Mission-critical pipelines with reified event concurrency
       │
[HydratedMixin / ReplayMixin]    --> Synchronous persistence (Frame 1) & Undo/Redo history

1. Raw Signals: Widget-Local Ephemeral State

Use raw signals (such as signal(), computed(), and the .$ extension syntax) when state is strictly local to a single widget subtree and requires zero backend orchestration.

Ideal Use Cases:

UI Interactions: Accordion open/close toggles, dropdown menu visibility, modal dialog triggers, and hover states.
Derived Computations: Calculating an invoice total dynamically from an active item list (computed(() => items.fold(0, (sum, i) => sum + i.price))).
Direct GPU/Render Bindings: Animation tickers, mouse positions, and custom canvas scroll offsets.

Why It Fits:

Raw signals eliminate class boilerplate entirely. Signal graphs update reactive nodes with sub-millisecond efficiency and are automatically garbage-collected when the hosting widget unmounts.

// Pure view calculation with zero class ceremony
final isExpanded = signal(false);
final totalPrice = computed(() => cart.value.fold(0, (sum, item) => sum + item.price));

Anti-Pattern to Avoid: Never create a full BLoC with separate event classes just to track whether a UI modal is visible.

2. CubitSignal: Feature Domain Logic & CRUD

Use CubitSignal<State> as your default workhorse for standard screen features and business domains.

Ideal Use Cases:

Standard CRUD Screens: Loading user profiles from a REST/GraphQL API, creating records, updating fields, and deleting rows.
Form State: Managing form validation errors, submit button spinners, and error alerts.
Application Settings: Toggling dark mode themes, changing localization languages, and updating account preferences.

Why It Fits:

CubitSignal exposes direct imperative methods (such as cubit.updateName('Alice')), enforcing a clean, predictable unidirectional data flow. You get synchronous in-frame updates, automatic equality de-duplication (if (stateValue == newState) return;), and global observability (BlocSignalObserver) without needing separate event classes.

class ProfileCubit extends CubitSignal<ProfileState> {
  ProfileCubit() : super(initialState: const ProfileState.initial());

  Future<void> updateName(String name) async {
    emit(stateValue.copyWith(name: name, isLoading: true));
    try {
      await userRepository.saveName(name);
      emit(stateValue.copyWith(isLoading: false));
    } catch (error) {
      emit(stateValue.copyWith(isLoading: false, errorMessage: error.toString()));
    }
  }
}

3. BlocSignal: Event Concurrency & Audit Pipelines

Use BlocSignal<Event, State> when your feature requires advanced event coordination, concurrency control, or strict enterprise audit logging.

Ideal Use Cases:

Event Concurrency Control:
- restartable(): Debounced live search inputs where new keystrokes cancel prior in-flight network queries.
- droppable(): Discarding rapid duplicate button taps while a checkout payment transaction is in progress.
- sequential(): Processing incoming chat messages or write operations in strict FIFO sequence.
Multi-Step Wizards & Funnels: Checkout pipelines, onboarding flows, and multi-step transaction wizards.
OpenTelemetry & Compliance Tracing: When every state transition must explicitly record the user action event that caused it (onEvent → onTransition).

sealed class SearchEvent {
  const SearchEvent();
}

final class QueryChanged extends SearchEvent {
  final String query;
  const QueryChanged(this.query);
}

class SearchBloc extends BlocSignal<SearchEvent, SearchState> {
  SearchBloc(this.apiService) : super(initialState: const SearchState.idle()) {
    on<QueryChanged>(
      (event, emit) async {
        if (event.query.isEmpty) {
          emit(const SearchState.idle());
          return;
        }
        emit(const SearchState.loading());
        final results = await apiService.search(event.query);
        emit(SearchState.success(results));
      },
      transformer: restartable(), // Automatically aborts previous query on new input!
    );
  }

  final ApiService apiService;
}

4. Specialized Mixins: Persistence & Undo/Redo

Both CubitSignal and BlocSignal compose with specialized mixins:

Frame-1 Instant Persistence (bloc_signals_hydrate): Restores cached state synchronously on startup before the first frame renders, preventing loading flashes and layout shifts.
Undo & Redo History (bloc_signals_replay): Maintains a bounded change stack (cubit.undo(), cubit.redo(), cubit.canUndo) for drawing surfaces, rich text editors, and document builders.

Architectural Comparison Matrix

State Container	Mutation Model	Concurrency Control	Reified Events	Persistence	Undo / Redo	Ideal Scope
Raw `Signal` / `computed()`	Direct assignment (`.value = x`)	In-frame direct	No	Manual	Manual	Widget-local ephemeral UI state
`CubitSignal<State>`	Direct methods (`cubit.action()`)	Mutex locks	No	Via `HydratedMixin`	Via `ReplayMixin`	Standard screen features, settings, CRUD
`BlocSignal<Event, State>`	Reified events (`bloc.add(Event())`)	Built-in (`droppable`, `restartable`)	Yes	Via `HydratedMixin`	Via `ReplayMixin`	Search inputs, multi-step wizards, audit logs
`HydratedCubitSignal<State>`	Direct methods + storage	Mutex locks	No	Frame-1 Synchronous	Via `ReplayMixin`	Persistent user preferences, auth caching
`ReplayCubitMixin<State>`	Direct methods + change stack	Mutex locks	No	Via `HydratedMixin`	Built-in (`.undo()`, `.redo()`)	Drawing canvas, document editors, undo flows

Syntax Evolution: Dart 3.5 vs. Modern Dart 3.13

Notice how modern Dart 3.13 streamlines event declarations with primary constructors:

Traditional Dart 3.5 Syntax:

sealed class CounterEvent {
  const CounterEvent();
}

final class IncrementRequested extends CounterEvent {
  const IncrementRequested();
}

class CounterBloc extends BlocSignal<CounterEvent, int> {
  CounterBloc() : super(initialState: 0) {
    on<IncrementRequested>((event, emit) => emit(stateValue + 1));
  }
}

Modern Dart 3.13 Syntax:

// Single-line sealed primary constructor hierarchy
sealed class const CounterEvent();
final class const IncrementRequested() extends CounterEvent;

class CounterBloc extends BlocSignal<CounterEvent, int> {
  CounterBloc() : super(initialState: 0) {
    on<IncrementRequested>((event, emit) => emit(stateValue + 1));
  }
}

Try the Interactive Decision Wizard

Want to find the ideal state container for your specific feature?

👉 Try the Interactive State Selector on blocsignal.dev

Select your requirements (concurrency, persistence, undo/redo, scope) and get an instant recommendation with runnable starter code.

AI Coding Assistant Support

If you use Claude Code, Antigravity, or Cursor, BlocSignal includes a pre-packaged AI Agent Skill bundle (bloc-signals) containing these exact architectural rules and validation patterns. Check out the BlocSignal GitHub Repository to explore the 10 modular packages and 25+ runnable examples!

What I Get to Forget About Riverpod Now That I Have BlocSignal

Randal L. Schwartz — Fri, 21 Aug 2026 01:00:50 +0000

The Best Feature in Software Is What You Get to Forget

In software engineering, we usually measure framework upgrades by what they add: new syntax, new macros, new features, new abstractions.

But as any developer who has maintained large Flutter applications over several years knows, the most profound upgrade in developer experience isn't what new concepts you are forced to memorize—it’s the mental gymnastics, framework-specific edge cases, and defensive rituals you finally get to forget and unlearn.

Before we dive into technical specifics, let's establish something essential: Rémi Rousselet is a pioneer and a brilliant engineer. When Rémi created provider in Flutter's early days and later built Riverpod in 2020, he solved real, glaring flaws in Flutter's core InheritedWidget mechanics (such as conditional dependency leaks and lack of compile safety). The entire Flutter ecosystem owes Rémi immense gratitude for pushing the boundaries of Dart architecture.

For years, I was a vocal, passionate—at times almost zealous—advocate for Riverpod. In discussions, community forums, and client architectures, I routinely recommended Riverpod above classic BLoC, Provider, and almost every other state management alternative. I championed its compile-time safety and global declarative graph vision because it genuinely solved tough problems we faced in earlier Flutter eras.

However, over the course of Riverpod's evolution across v1, v2 (the code-gen era), and v3, solving every edge case within a global declarative provider graph led to a staggering accumulation of cognitive surface area. Building real-world Flutter apps with Riverpod today requires developers to maintain a complex internal rules engine just to avoid subtle runtime footguns.

And yet, recognizing how much mental gymnastics this has gradually demanded, I find myself genuinely thrilled and relieved to be pivoting. When you switch to BlocSignal (which combines the proven discipline of BLoC/Cubit with the synchronous speed and fine-grained reactivity of Signals), you realize just how much mental baggage you were carrying—and I am excited to share that journey with all of you.

A Quick Note on Lints and IDE Assists

It is worth acknowledging that the Riverpod ecosystem has invested heavily in custom analyzer lints (riverpod_lint), IDE plugins, and automated quick-fixes (such as "Wrap with ConsumerWidget" or "Convert to Notifier").

While these tooling aids are genuinely helpful, they only address surface-level syntax—they cannot eliminate the underlying cognitive load. An IDE shortcut that automatically rewrites your widget class hierarchy does not prevent a controller from disposing mid-flight during an await gap, nor can a linter rule save a navigation stack from wiping when a router provider re-evaluates.

Tooling assists can bandage syntactic friction, but true architectural simplicity removes the friction at the root.

Here is the running list of everything you get to forget—and why your architecture gets significantly cleaner the moment you do.

1. 🗑️ Forget `build_runner` and Code-Gen Rituals

The Riverpod Gymnastics:

In modern Riverpod (v2/v3), code generation is the officially recommended path. That means:

Annotating classes with @riverpod.
Extending obscure generated private base classes (extends _$AuthNotifier).
Running dart run build_runner watch --delete-conflicting-outputs in a separate terminal tab, spinning laptop fans while consuming gigabytes of RAM.
Waiting several seconds every time you rename a parameter or add a method just for IDE autocomplete to work again.
Dealing with noisy .g.dart generated files cluttering Git diffs and code reviews.

(Yes, Riverpod still technically supports manual NotifierProvider / Notifier syntax without code generation. But code-gen is the officially documented standard and recommended default throughout modern Riverpod tutorials and guides. Writing manual syntax is verbose and forfeits features like typed .family parameter records.)

// 🤯 Riverpod (Code Generation Required)
import 'package:riverpod_annotation/riverpod_annotation.dart';

part 'counter.g.dart';

@riverpod
class Counter extends _$Counter {
  @override
  int build() => 0;

  void increment() => state++;
}

What You Do in BlocSignal:

You write pure Dart. No build_runner. No part files. No code-gen watchers. Instant autocomplete in every IDE, 100% of the time.

// ⚡ BlocSignal (Zero Code-Gen, Pure Dart)
import 'package:bloc_signals/bloc_signals.dart';

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

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

2. 🗑️ Forget Widget Class Hierarchy Gymnastics & `WidgetRef` Plumbing

The Riverpod Gymnastics:

In Riverpod, you cannot read or watch state from standard Flutter widgets without either:

Converting your StatelessWidget into a ConsumerWidget and changing build(BuildContext context) to build(BuildContext context, WidgetRef ref).
Converting your StatefulWidget into a ConsumerStatefulWidget and State<T> into ConsumerState<T>.
If using Flutter Hooks, extending HookConsumerWidget (a Frankenstein base class).
Passing WidgetRef ref down private helper functions, widget sub-methods, and domain callbacks because ref is not accessible from standard BuildContext.

// 🤯 Riverpod
class UserProfileView extends ConsumerWidget {
  const UserProfileView({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final user = ref.watch(userProvider);
    return Text(user.name);
  }
}

What You Do in BlocSignal:

You use standard Flutter widgets. StatelessWidget, StatefulWidget, or HookWidget. You interact via idiomatic BuildContext extensions or dedicated declarative widgets (BlocSignalBuilder, BlocSignalListener, BlocSignalConsumer):

// ⚡ BlocSignal
class UserProfileView extends StatelessWidget {
  const UserProfileView({super.key});

  @override
  Widget build(BuildContext context) {
    final user = context.watch<UserCubit>().stateValue;
    return Text(user.name);
  }
}

Zero custom base classes. Zero WidgetRef drilling. Native Flutter.

3. 🗑️ Forget the Provider "Alphabet Soup" & Deprecation Whiplash

The Riverpod Gymnastics:

Over the last few years, Riverpod developers have had to navigate an exhausting taxonomy of provider variants:

Provider
StateProvider (deprecated in v2/v3)
StateNotifierProvider (deprecated)
ChangeNotifierProvider
FutureProvider
StreamProvider
NotifierProvider
AsyncNotifierProvider
StreamNotifierProvider
AutoDisposeProvider / AutoDisposeFutureProvider
.family modifiers with tuple parameter records

Each variant had its own slightly different rules for error handling, disposal, and lifecycle callbacks.

What You Do in BlocSignal:

There are only two intuitive, unified primitives:

CubitSignal<State>: For method-based state management (call methods, compute derived state, emit new values).
BlocSignal<Event, State>: For formal, event-driven unidirectional data flow with explicit event hierarchies and concurrency transformers (droppable, restartable, sequential).

Both use standard Dart constructors, synchronous emit(), and expose state as a reactive ReadonlySignal<State>.

(While Riverpod's generic AsyncValue is handy for basic fetch-and-display screens, real enterprise applications quickly outgrow generic 3-state wrappers and require rich domain models—such as partial validations, optimistic rollbacks, and multi-step forms. With BlocSignal, you leverage the full expressive power of Dart 3 sealed classes for domain state, while retaining access to AsyncSignal when you want declarative async futures.)

4. 🗑️ Forget the "Ref World vs. Non-Ref World" Boundary

The Riverpod Dilemma:

As I taught developers and engineering teams about Riverpod over the years, I gradually adopted a mental model of the "Ref World" vs. the "Non-Ref World" to help students understand a fundamental reality of Riverpod's design.

In Riverpod, reactive state is strictly confined inside a ProviderContainer—the "Ref World". As long as you are inside a ConsumerWidget or inside another provider, you hold a Ref or WidgetRef, and everything connects. But the moment you step into standard Dart code—such as HTTP client interceptors, WebSocket listeners, background database services, or routing configurations—you are stranded in the "Non-Ref World". To connect the two, you are forced to:

Drill a Ref ref parameter through every layer and pollute pure Dart domain classes with framework dependencies.
Or expose a global top-level ProviderContainer variable as an escape hatch.

What You Do in BlocSignal:

bloc_signals is a 100% pure Dart package with zero Flutter dependencies.

You can instantiate and observe a CubitSignal or BlocSignal anywhere: inside Flutter widgets, CLI tools, Jaspr web applications, or Serverpod backend services.
Pure Dart services can read cubit.stateValue or subscribe directly to cubit.state.subscribe((state) => ...) with zero container ceremony.

What about cross-container coordination? In classic stream-based BLoC, coordinating two Blocs was notoriously clunky (often forcing developers to nest multiple BlocListener widgets in the UI tree). In BlocSignal, because every state is exposed as a reactive ReadonlySignal<State>, cross-Cubit derived state is trivial in pure Dart business logic:

// ⚡ Pure Dart Cross-Cubit Derivation (Zero UI Listeners Needed)
late final isCheckoutReady = computed(() => 
  authCubit.state().isAuthenticated && cartCubit.state().items.isNotEmpty
);

Zero widget tree nesting. Zero stream subscriptions. 100% testable in pure Dart.

5. 🗑️ Forget the `routerProvider` Navigation Stack Nuke

The Riverpod Footgun:

Perhaps the most notorious casualty of the "Non-Ref World" boundary is routing. Because routers like GoRouter are standard Dart objects that live squarely in the Non-Ref World, developers frequently attempt to pull their router into the Ref World by wrapping it in a Riverpod Provider so it can access ref and observe live authentication state:

// 💣 The Innocent-Looking Riverpod Disaster
final routerProvider = Provider<GoRouter>((ref) {
  final auth = ref.watch(authProvider); // 💣 DISASTER
  return GoRouter(
    redirect: (context, state) => auth.isLoggedIn ? null : '/login',
    routes: [...],
  );
});

The Runtime Bug: Whenever authProvider emits (or background token refresh occurs), ref.watch destroys and recreates the entire GoRouter instance.

The user's entire navigation history stack is wiped clean.
Deeply nested tabs and modal sheets vanish instantly.
Scroll offsets reset to the top.

To fix this in Riverpod, you cannot just write intuitive code; you must possess a deep, esoteric understanding of both how GoRouter manages its internal delegate and how Riverpod rebuilds provider dependencies. The prescribed workaround is constructing a custom ChangeNotifier bridge with ref.listen to feed refreshListenable.

Worse still, when this bug strikes in production, there are no error logs or stack traces—just an unexplained navigation reset. Developers are often left struggling with a complete lack of information and traceability, unclear even where to place debugger probes or log statements to catch why the router is vanishing.

What You Do in BlocSignal:

Your GoRouter instance is created once and remains permanent. You connect it directly using toListenable():

// ⚡ BlocSignal: Stable Router, Live Redirects
final router = GoRouter(
  refreshListenable: authCubit.toListenable(),
  redirect: (context, state) => authCubit.stateValue.isLoggedIn ? null : '/login',
  routes: [...],
);

Zero router destruction. Unbroken navigation stacks. 100% deterministic.

6. 🗑️ Forget the "Self-Disposing Async Mutation" Crash

The Riverpod Footgun:

In Riverpod 3.0, auto-disposal is enabled by default. While the intended goal of automatic disposal is commendable (preventing memory leaks in long-lived trees), using implicit UI reference counting to govern asynchronous business logic creates severe race conditions:

// 💣 Riverpod 3.0 Trap
@riverpod
class NoteController extends _$NoteController {
  @override
  Future<List<Note>> build() => repository.fetchNotes();

  Future<void> deleteNote(String id) async {
    state = const AsyncLoading();
    await repository.deleteNote(id);

    // 💥 CRASH: "Cannot use Ref after it has been disposed"
    // If the user navigates away or no widget is watching this controller during the `await`,
    // Riverpod garbage-collects this instance mid-flight!
    ref.invalidateSelf(); 
  }
}

To work around this in Riverpod, developers are forced into defensive gymnastics:

Defensive Guards: Sprinkling if (ref.mounted) checks after every single asynchronous await.
Action Controller Sprawl: Creating an entirely separate NoteDeleteActionController class just to execute a single async method call without auto-disposing the main list provider.
Keep-Alive Token Juggling: Manually acquiring and releasing KeepAliveLink tokens:

  final link = ref.keepAlive(); // 🤯 Manual retain-count management in Dart!
  try {
    await repository.deleteNote(id);
  } finally {
    link.close(); // Remember to release the token, or leak memory forever!
  }

Think about how absurd that is: you find yourself having to write meta-state management just to manage the lifecycle of your state management system. High-level declarative Dart is suddenly reduced to manual reference-count lock juggling.

What You Do in BlocSignal:

In BlocSignal, state containers are standard Dart objects with explicit, predictable ownership. If an async method is running, it executes to completion. If a Bloc is closed, emit() is safely dropped with zero unhandled runtime crashes:

// ⚡ BlocSignal
class NoteCubit extends CubitSignal<NoteState> {
  NoteCubit({required this.repository}) : super(initialState: const NoteState.initial());

  final NoteRepository repository;

  Future<void> deleteNote(String id) async {
    emit(stateValue.copyWith(isLoading: true));
    await repository.deleteNote(id);
    final notes = await repository.fetchNotes();
    emit(stateValue.copyWith(isLoading: false, notes: notes));
  }
}

7. 🗑️ Forget `.family` Parameter Isolation & Cache Silos

The Riverpod Dilemma:

When you use Riverpod's .family modifier to parameterize queries:

final userPostsProvider = FutureProvider.family<List<Post>, String>((ref, userId) => ...);
final postDetailProvider = FutureProvider.family<Post, String>((ref, postId) => ...);

Each parameter generates an isolated provider instance. If the user likes a post in postDetailProvider('post-123'), userPostsProvider('user-456') still contains the old, unliked copy of that post in memory. You now have to build complex cache invalidation bridges across multiple isolated providers.

What You Do in BlocSignal:

You use normal Dart parameters in constructors (PostCubit(userId: id)) and share live reactive signal stores (like mapSignal or computed()) across containers. When a post is updated in the central signal store, every widget and cubit observing it updates synchronously in the exact same frame.

8. 🗑️ Forget the `ref.watch` in Callbacks Infinite Loop Trap

The Riverpod Gotcha:

One of the most common mistakes for Flutter developers learning Riverpod is calling ref.watch inside an onPressed or gesture callback instead of ref.read:

// 💣 Riverpod Bug
ElevatedButton(
  onPressed: () {
    // 💥 Calling watch inside an event handler registers an invalid dependency
    // or creates unexpected rebuild cascades!
    ref.watch(authProvider.notifier).login();
  },
  child: const Text('Login'),
)

What You Do in BlocSignal:

The distinction in BlocSignal is natural and enforced by Flutter's existing BuildContext idioms:

In callbacks/handlers: context.read<AuthCubit>().login() (O(1) lookup, zero subscription).
In UI builders: context.watch<AuthCubit>().stateValue or BlocSignalBuilder<AuthCubit, AuthState> (explicit reactive rebuild boundary).

9. 🗑️ Forget In-Place Mutation Silent Drop Traps

The Riverpod Footgun:

In Riverpod 3, notifying listeners relies strictly on reference equality (identical(oldState, newState)). If you mutate a list in-place:

// 💣 Riverpod 3 Silent Failure
state.add(newItem);
state = state; // ❌ Does NOT trigger UI rebuilds because identical(state, state) is true!

What You Do in BlocSignal:

BlocSignal provides explicit, customizable equality checks via SignalOptions(equals: ...) or standard value equality (using Dart 3 records, Freezed, or fast_immutable_collections). When you call emit(newState), the transition is explicit, logged through BlocSignalObserver, and propagated synchronously.

10. 🗑️ Forget Subtree `ProviderScope(overrides: [...])` Scoping & Modal Traps

The Riverpod Gymnastics:

In Riverpod, when you need to scope data down a specific widget subtree—such as passing item data down a list view or customizing a controller for a nested section—Riverpod prescribes nesting a ProviderScope with overrides::

// 🤯 Riverpod: Scoping data in a list
ListView.builder(
  itemCount: todos.length,
  itemBuilder: (context, index) {
    return ProviderScope(
      overrides: [
        currentTodoProvider.overrideWithValue(todos[index]),
      ],
      child: const TodoItemTile(),
    );
  },
);

This pattern introduces several subtle, high-friction pitfalls:

Container Overhead in Lists: Wrapping 100 list tiles in ProviderScope instantiates 100 nested Element widgets and separate internal provider container nodes.
The "Split-Brain" Dependency Trap: If Provider B depends on Provider A, and you override A in a nested ProviderScope without also explicitly overriding B, Provider B still resolves against the root un-overridden A, causing baffling data desynchronization bugs.
The Modal & Dialog Disconnection Bug: When you call showDialog() or showModalBottomSheet(), Flutter pushes the new route to the root Navigator overlay. Because the dialog is mounted outside the local subtree's ProviderScope, all local overrides are instantly lost—causing the modal to either crash with missing providers or silently read outdated root state.

What You Do in BlocSignal:

You use standard Dart and Flutter idioms:

In lists: Pass data directly via constructor parameters (TodoItemTile(todo: todos[index])).
In subtrees: Use standard Flutter scoping with BlocSignalProvider.value(value: todoCubit, child: ...) or provide scoped instances cleanly.
In dialogs: Pass the Cubit directly to BlocSignalProvider.value in the dialog builder, or let it resolve naturally up the Flutter element tree.

11. 🗑️ Forget Complex `ProviderContainer` Mocking & Test Rigmarole

The Riverpod Testing Ceremony:

In Riverpod, unit tests and widget tests require assembling a ProviderContainer or wrapping test widgets in ProviderScope(overrides: [...]):

// 🤯 Riverpod Test Ceremony
final container = ProviderContainer(
  overrides: [
    authRepositoryProvider.overrideWithValue(mockAuthRepo),
    apiClientProvider.overrideWithValue(mockApiClient),
    // ⚠️ Miss just one transitive provider in this list, and your test
    // will accidentally make real network calls or throw late-init errors!
  ],
);
addTearDown(container.dispose);

What You Do in BlocSignal:

State containers are plain Dart classes with direct constructor injection. You instantiate your Cubit or Bloc with your mock repository directly:

// ⚡ BlocSignal: Declarative, Instant Unit Testing
blocSignalTest<CounterCubit, int>(
  'emits [1] when increment is called',
  build: () => CounterCubit(repository: mockRepository),
  act: (cubit) => cubit.increment(),
  expect: () => [1],
);

Because BlocSignal state transitions are synchronous, assertions execute immediately without flaky tester.pumpAndSettle() timeouts or async race conditions.

12. 🤖 Forget the AI & LLM Hallucination Nightmare

The Riverpod AI Friction:

If you pair-program with AI coding assistants—whether Claude, Cursor, GitHub Copilot, ChatGPT, or Gemini—you have likely experienced how difficult Riverpod is for modern LLMs:

The Version Multi-Verse: LLM training data contains years of conflicting Riverpod eras (v0.14 ChangeNotifierProvider, v1.0 StateNotifierProvider, v2.0 @riverpod code-gen, and v3.0 Notifier). AI models constantly mix up these eras, hallucinating deprecated APIs, invalid provider types, or incompatible syntax.
Code-Gen Blindness: LLMs cannot see generated code before build_runner executes. When an AI generates a @riverpod class, it frequently botches the synthesized _$ClassName inheritance, misnames the generated provider, or forgets the part 'file.g.dart'; declaration.
Ref Scope Confusion: AI models frequently lose track of the "Ref World" boundary—attempting to access ref inside widget constructors, passing WidgetRef into deep business logic layers, or failing to convert widgets to ConsumerStatefulWidget.
Implicit Auto-Disposal Bugs: LLMs routinely write async mutation methods inside auto-disposing notifiers without accounting for ref.mounted guards or keep-alive tokens, generating code that looks plausible but crashes in production.

What You Do in BlocSignal:

LLMs excel at pure, standard Dart with explicit contracts:

Standard Dart & Predictable Conventions: Pure classes, direct constructor injection, and idiomatic Flutter BuildContext lookups. There is no code-gen magic for the LLM to guess.
Zero build_runner Feedback Loops: AI agents can write features, scaffold tests, and immediately verify analyzer diagnostics without waiting for external code generation steps.
Vast Training Ground: BLoC and Cubit are among the most consistently documented and deeply represented architectural patterns in AI training datasets. LLMs generate accurate, idiomatic BlocSignal code on the first try.
Deterministic AI-Generated Tests: AI tools generate rock-solid, synchronous blocSignalTest suites without getting tripped up by ProviderContainer setup boilerplate or async frame timing issues.
First-Class AI Skills From Day One: Rather than leaving LLMs to guess architectural boundaries, BlocSignal ships from day one with installable agent skills covering migrations, interop adapters, and production best practices.

Summary: The Cognitive Weight You Leave Behind

What You Leave Behind in Riverpod	What You Enjoy in BlocSignal
`build_runner` & `.g.dart` Code Generation	Pure, standard Dart with instant IDE autocomplete
`ConsumerWidget` & `WidgetRef` Plumbing	Standard Flutter widgets & clean `BuildContext` APIs
Alphabet Soup of 10+ Provider Types	2 Unified Primitives (`CubitSignal` & `BlocSignal`)
Ref vs Non-Ref Boundary Walls	Zero-dependency pure Dart state usable anywhere
`GoRouter` Navigation Stack Wipes	Stable router instance with `.toListenable()`
"Self-Disposing" Async Mutation Crashes	Predictable, developer-owned object lifecycles
Isolated `.family` Cache Silos	Direct constructor injection & normalized Signals graph
`ref.watch` in Callbacks Rebuild Cascades	Clean separation of `context.read()` & `context.watch()`
In-Place Mutation Silent Drops	Explicit transitions via `emit()` with custom equality
Subtree `ProviderScope(overrides:)` & Modal Disconnects	Standard Dart props & native `InheritedWidget` scoping
Complex `ProviderContainer` Test Overrides	Direct constructor mocking & declarative `blocSignalTest`
AI / LLM Version Hallucinations & Code-Gen Errors	First-shot AI accuracy with standard Dart & BLoC patterns

🌉 Currently Mired in Riverpod? You Don’t Need a Big-Bang Rewrite

If you maintain a large production codebase built on Riverpod, you might be thinking: "This sounds wonderful, but our entire team is already knee-deep in Riverpod. We cannot afford to halt feature delivery for a massive rewrite."

You don't have to.

Through bloc_signals_riverpod, you get a seamless, bidirectional interop bridge that allows you to adopt BlocSignal incrementally, one feature or screen at a time.

Direction 1: Expose a BlocSignal to Existing Riverpod Widgets

If you build a new feature using a clean, pure Dart CubitSignal, you can expose it directly to existing Riverpod widgets as a standard NotifierProvider using .toProvider():

// 1. Build your new feature with a pure Dart Cubit
final cartCubit = CartCubit();

// 2. Adapt it into a Riverpod provider with a single call
final cartProvider = cartCubit.toProvider();

// 3. Existing Riverpod ConsumerWidgets watch it seamlessly:
class CartBadge extends ConsumerWidget {
  const CartBadge({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final cartState = ref.watch(cartProvider);
    return Badge(label: Text('${cartState.itemCount}'));
  }
}

Direction 2: Consume Legacy Riverpod Providers in BlocSignal

Conversely, if your new BlocSignal architecture needs to read data from legacy Riverpod providers that you aren't ready to rewrite yet, you can adapt any ProviderListenable with .toBlocSignal(ref):

// Adapt any legacy Riverpod provider into a reactive BlocSignal
final userBloc = legacyUserProvider.toBlocSignal(ref);

// Read stateValue synchronously or subscribe to state changes
print(userBloc.stateValue.userName);

You can migrate your application piece by piece—shedding the cognitive load on new features immediately while existing code continues running uninterrupted.

Getting Started

If you want the architectural discipline of BLoC combined with the modern, zero-latency reactive power of Signals—without the code-gen or cognitive overhead—give BlocSignal a spin.

dependencies:
  bloc_signals: ^1.0.0
  bloc_signals_flutter: ^1.0.0

  # Optional for incremental migration:
  bloc_signals_riverpod: ^1.0.0

Learn more at blocsignal.dev or explore the source on GitHub.

Why I Tell My AI Coding Agent: "Prefer Dart Over Python"

Randal L. Schwartz — Thu, 20 Aug 2026 01:56:59 +0000

In my global instructions and memory rules for AI coding assistants (like Google Antigravity / Gemini / Claude), I keep a specific directive:

"When you need to create a temporary script to perform an action and the language doesn't really matter, prefer Dart over Python if Dart is an acceptable straightforward solution."

Whenever developers see this rule, they ask: Why Dart? Isn’t Python the undisputed king of glue scripts, quick automation, and AI tooling?

Python may be the default reflex for human developers, but from an AI pair-programming perspective, Python introduces unnecessary friction. Modern Dart consistently yields higher first-run success rates, zero environment headaches, and cleaner code.

Here is why this rule will make your AI workflows significantly more reliable.

1. Zero-Ceremony Execution: Escaping "Environment Hell"

When an AI writes a temporary Python script to process files or hit an endpoint, it frequently fails before line 1 even executes:

Is the shell aliased to python or python3?
Did it hit PEP 668 (error: externally-managed-environment)?
Are dependencies managed with pip, pipx, poetry, conda, or uv?
Did the agent import requests or httpx, only to discover you don’t have them installed in your active subshell?

With Dart, if the Dart SDK is installed, dart run script.dart (or simply dart script.dart) runs anywhere, immediately.

There is one official toolchain. No virtual environment activation, no broken path dependencies, and no package manager guessing games.

2. A Real "Batteries-Included" Core Library

Python's standard library is broad, but dated. To do ergonomic HTTP or clean subprocess streaming, agents almost always reach for third-party packages.

Dart’s core libraries (dart:io, dart:convert, dart:async) are built directly into the runtime and provide everything needed for system tooling out of the box:

JSON & Data Encoding: jsonDecode, jsonEncode, utf8, base64 require zero external dependencies.
Subprocess Management: Process.run() and Process.start() handle stdout/stderr cleanly without obscure shell escape pitfalls.
Symmetrical File I/O: Direct access to both synchronous (readAsStringSync(), listSync()) and asynchronous APIs.

An agent can parse multi-megabyte JSON trees, decode base64 binary streams, and coordinate CLI processes in a single self-contained .dart file without touching a package manifest.

3. Need More Batteries? `dart pub add` Without Virtualenv Headaches

What happens when your script does need external packages (e.g., specialized cryptography, HTML scraping, or CLI argument parsers)?

In Python, pulling in a package is a minefield:

Do you install globally and risk polluting system packages?
Do you force the user or agent to run python3 -m venv .venv && source .venv/bin/activate?
Which config file format do you generate: requirements.txt, Pipfile, setup.py, or pyproject.toml?

In Dart, there is zero package management friction:

One-Command Setup: An agent simply runs:

   dart pub add http path crypto

One Universal Manifest: There is only pubspec.yaml—clean, minimal, and standardized.
No Virtual Environments: Dart resolves and downloads dependencies into a centralized global cache (~/.pub-cache) and links them locally via .dart_tool/. You never have to activate a virtualenv, manage path shims, or resolve corrupted local site-packages.

Even when you need third-party packages, Dart remains painless.

4. Sound Typing + Modern Dart 3 Ergonomics

Dynamic typing in LLM-generated Python is a frequent source of bugs. Agents regularly produce code that trips on nested structures:

KeyError on unexpected dictionary keys
AttributeError: 'NoneType' object has no attribute 'get'
Subtle type-coercion bugs when parsing CLI output

Dart provides sound static typing paired with fast local type inference (var / final), so scripts remain as concise as Python while the compiler catches structural errors before execution.

With Dart 3 Pattern Matching, extracting nested data from APIs or JSON logs is declarative and safe:

// Safe, expressive JSON extraction in Dart 3
final userName = switch (json) {
  {'user': {'profile': {'name': String n}}} => n,
  _ => 'Unknown User',
};

Add Records (String status, int count) to the mix, and the agent can return multiple structured values without defining throwaway classes or relying on untyped Python tuples.

5. Predictable, Deadlock-Free Asynchrony

Writing concurrent scripts in Python (asyncio) is notoriously fraught:

Mixing synchronous file operations or subprocesses inside an event loop often blocks execution.
Running into RuntimeError: This event loop is already running when tools invoke nested loops.

Dart was engineered from day one around a single-threaded event loop with first-class Future, Stream, and async/await:

// Clean, concurrent fan-out without third-party libraries
void main() async {
  final tasks = [
    fetchStatus(1),
    fetchStatus(2),
    fetchStatus(3),
  ];
  final results = await Future.wait(tasks);
  print('Completed: $results');
}

Concurrency in Dart scripts is lightweight, predictable, and doesn't suffer from obscure event-loop lifecycle bugs.

6. What About Rust?

Whenever static typing and reliability are mentioned, the immediate question is: "Why not tell the AI to write temporary tools in Rust?"

Rust is unmatched for production infrastructure, high-performance engines, and memory-critical services. But for AI-generated ad-hoc scripts and glue code, Rust introduces a different set of bottlenecks:

Minimalist std: Rust’s standard library intentionally excludes JSON parsing (serde_json), HTTP clients (reqwest), and an async runtime (tokio). An AI cannot write a standalone, zero-dependency script for common scripting tasks.
Compilation Latency: Compiling Rust crates through rustc/LLVM introduces a multi-second delay. In a tight agentic feedback loop (write → execute → inspect stdout → iterate), that compilation lag slows down the interaction.
Borrow Checker Ceremony: Ownership, lifetimes (&str vs String), and Box<dyn Error> force the LLM to spend extra tokens and reasoning cycles managing memory semantics that simply don't matter for a 50-line throwaway utility script.

⚖️ The Scripting Showdown

Dimension	Dart	Python	Rust
Execution Latency	⚡️ Instant (JIT)	⚡️ Instant (Interpreted)	⏳ Slow (LLVM compile)
Zero-Dependency JSON / I/O / Process	✅ Built into `std`	⚠️ Inconsistent (`urllib` vs `requests`)	❌ Requires external crates
Adding Dependencies	⚡️ `dart pub add` (no venv)	⚠️ `pip` + venv + PEP 668 setup	⏳ `Cargo.toml` + crate compilation
Single-File Portability	✅ `dart script.dart`	⚠️ Virtualenv / PEP 668 friction	❌ Usually requires `Cargo.toml`
Type Safety & Pattern Matching	✅ Sound typing + Dart 3	❌ Runtime errors (`KeyError`, etc.)	✅ Extremely strong
Memory / Lifetime Overhead	🟢 Low (GC)	🟢 Low (GC)	🔴 High (Borrow checker)

Dart occupies the sweet spot: the scripting agility and garbage collection of Python combined with the type safety and single-toolchain reliability that agents need.

7. The Training Data Paradox

Why does the AI default to Python in the first place? Dataset inertia.

Python dominates GitHub and StackOverflow by sheer legacy volume. But sheer volume does not equal linguistic ergonomics or agent reliability.

When you explicitly guide your AI coding assistant to use Dart for tooling and automation:

First-run execution rate increases because syntax and type safety prevent runtime traps.
Scripts run fast on Dart’s JIT compiler.
Artifacts are maintainable: What started as a quick one-off script is already typed, readable, and ready to evolve into a permanent CLI tool if needed.

💡 Try It In Your Own Setup

Add this instruction to your AI coding rules (.cursorrules, CLAUDE.md, Antigravity instructions, or system prompt):

When generating one-off scripts, automation tools, 
or data-processing utilities where the language 
is not specified, prefer Dart over Python if Dart 
provides a straightforward solution.

Dart isn't just for Flutter apps—it's one of the cleanest, most reliable scripting languages available for AI-assisted development.

DEV Community: Randal L. Schwartz

Taming Flutter Infinite Scroll (Part 2): Turning ScrollController into a Reactive State Machine with CubitSignalMixin

The Infinite Scroll Rite of Passage

🧱 Dart's Single-Inheritance Wall

🧬 How Composable Mixins Break the Wall

📐 Pattern A: The Reactive PagingScrollController (Separation of Concerns)

💡 The extentAfter Secret: Why Pixels Beat Percentages

The Superpower of Automatic De-duplication

⚡ Pattern B: The Self-Paging Domain Controller (Zero-Bridge Architecture)

🎨 The Flutter UI: A 100% StatelessWidget

🛡️ Safe Lifecycle & Teardown Architecture

📊 Comprehensive Architectural Comparison

🎯 Which Strategy Should You Choose?

Conclusion

Resources & Companion Code

Taming Flutter Infinite Scroll: Why 3 Lines of async* Missed the Point, and How BlocSignal Fixes It

The Ubiquitous Infinite Scroll Pagination Bug

🔍 Why async* and StreamIterator Crack Under Pressure

1. The Hidden Concurrency Crash: Bad state: Cannot call moveNext...

2. Pulling Chunks vs. Reactive Unidirectional Data Flow

3. Resource Leak Risks & Teardown Friction

⚡ The Architectural Lesson: Concurrency Belongs at the Event Boundary

🛡️ The Idiomatic BlocSignal Solution: droppable()

🔬 Under the Hood: Why droppable() is Glitch-Free and Streamless

🎯 Natural Cursor Pagination: Forgetting the page Counter

🔄 Instant Search Reset with restartable()

📱 The Flutter UI: Declarative and Lightweight

📊 Architectural Comparison

Conclusion

Resources & Links

Automate Flutter's New Split Package Migration with AI Agent Skills

How to use dart-sdk-skills to empower your AI coding agent to seamlessly migrate Flutter projects to standalone material_ui and cupertino_ui packages

🏛️ The Architectural Shift: Why Split Packages?

🧩 The Challenge with AI Coding Agents

⚡ What is dart-sdk-skills?

Installing dart-sdk-skills in Seconds

Universal Install (Node / npx skills):

Dart Skills CLI:

Google Antigravity / Manual Symlink:

🤖 The Migration Workflow: Putting Your Agent to Work

1. Automated Analysis and Data-Driven Transforms

2. Dependency Configuration (pubspec.yaml)

3. Canonical Import Rewrites

4. Localization Delegate Binding

5. Automated Verification & Quality Gate

🎨 Bonus: Building Pure Headless Apps

🚀 Get Started Today

Production Flutter Networking Without the Boilerplate: Reactive Repositories with BlocSignal

The Networking Architecture Dilemma in Production Flutter

⚡ 1. Symmetrical Async Projection with .toAsyncBlocSignal()

Declarative Exhaustive UI Binding

🧬 2. Reactive, Offline-Cached Repositories with CubitSignalMixin & HydratedMixin

What This Architecture Delivers:

🛑 3. Eliminating Network Race Conditions with restartable()

🏛️ Summary Architecture Comparison

💬 Join the Discussion!

Overcoming Dart's Single Inheritance Wall: Composable CubitSignalMixin & BlocSignalMixin in Flutter

Breaking Free from Dart's Single Inheritance Constraint in State Management

🧬 How the Composable Mixins Work

1. CubitSignalMixin<StateType>

2. BlocSignalMixin<Event, StateType>

🎯 Real-World Killer Use Case: The Self-Debouncing TextEditingController

Clean, Declarative Flutter UI Binding

🏛️ DRY Core Architecture & Universal Polymorphism

📦 Getting Started

💬 Let's Discuss!

Grand Central Station: Why BLoC, Riverpod, and BlocSignal Are Now True Peers

The State Management Balkanization Is Officially Over

🏛️ The Metaphor: Grand Central State Terminal

⚡ What Makes Them "True Peers"?

☕ The "Grand Central Triple Counter" (Least Boilerplate Possible)

Why This Integration Is Revolutionary:

🔄 The Return Trip: Exporting BlocSignal to Legacy Trees

1. Modern BlocSignal ➔ Classic flutter_bloc Trees

2. Modern BlocSignal ➔ Riverpod ProviderScope Trees

🎯 What This Means for Engineering Teams

🏁 All Aboard at Grand Central

Mechanically Eliminating FutureBuilder & StreamBuilder: Universal Signal, Future, and Stream Adapters in BlocSignal

Making the Migration from In-View Asynchrony to Synchronous State Management Truly Mechanical

🧭 The Universal Dual-Track Mental Model

📐 Pattern A: The Reactive `PagingScrollController` (Separation of Concerns)

💡 The `extentAfter` Secret: Why Pixels Beat Percentages

🎨 The Flutter UI: A 100% `StatelessWidget`

🔍 Why `async*` and `StreamIterator` Crack Under Pressure

1. The Hidden Concurrency Crash: `Bad state: Cannot call moveNext...`

🛡️ The Idiomatic BlocSignal Solution: `droppable()`

🔬 Under the Hood: Why `droppable()` is Glitch-Free and Streamless

🎯 Natural Cursor Pagination: Forgetting the `page` Counter

🔄 Instant Search Reset with `restartable()`

⚡ What is `dart-sdk-skills`?

Installing `dart-sdk-skills` in Seconds

Universal Install (Node / `npx skills`):

2. Dependency Configuration (`pubspec.yaml`)

⚡ 1. Symmetrical Async Projection with `.toAsyncBlocSignal()`

🧬 2. Reactive, Offline-Cached Repositories with `CubitSignalMixin` & `HydratedMixin`

🛑 3. Eliminating Network Race Conditions with `restartable()`

1. `CubitSignalMixin<StateType>`

2. `BlocSignalMixin<Event, StateType>`

🎯 Real-World Killer Use Case: The Self-Debouncing `TextEditingController`

1. Modern BlocSignal ➔ Classic `flutter_bloc` Trees

2. Modern BlocSignal ➔ Riverpod `ProviderScope` Trees

⚡ Track 1: Direct Raw Domain State (`.toBlocSignal`)

1. Adapting `ReadonlySignal<T>` & Lifted Primitives

2. Adapting `Future<T>` with a Required Initial State

3. Adapting `Stream<T>` with a Required Initial State

🔄 Track 2: Rich Asynchronous State (`.toAsyncBlocSignal`)

🛠️ Step-by-Step Conversion 1: Eliminating `FutureBuilder`

The Legacy Anti-Pattern (`FutureBuilder`)

🌊 Step-by-Step Conversion 2: Eliminating `StreamBuilder`

The Legacy Anti-Pattern (`StreamBuilder`)

The Clean Refactor with `.toBlocSignal()`

Testing a `FutureBuilder` Widget

Testing the `BlocSignal` Adapter Unit

💡 The Hidden Superpower: Built-In `try/catch` Encapsulation

Step 2: Clean State Coordination in `CubitSignal` (Domain Layer)

1. Unit Testing Domain Logic with `blocSignalTest`

🎯 What is `dart-sdk-skills`?

Using `npx skills` (Universal / Node):

Using the Dart `skills` CLI: