Thanks for tackling #3248, @champ96k — the per-handler scoping is exactly the right thing to clarify. Sharing a few suggestions that I think would strengthen the PR, cc @felangel for a maintainer steer:

1. Use a snippet component instead of a raw code fence. Every code sample in bloc-concepts.mdx is imported as a <...Snippet /> .astro component (<Code code={...} lang="dart" title="..." />) rather than an inline ```dart block — e.g. DebounceEventTransformerSnippet. The inline fence in the new section is the only one on the page that breaks that pattern. Extracting it into docs/src/components/concepts/bloc/…Snippet.astro keeps it consistent (and picks up the site's syntax highlighting + filename chrome).

2. Make the example self-consistent. The current sample references SearchEvent / SearchState / _onQueryChanged / _onClearSearch without defining them. A sealed class SearchEvent with two final subclasses (matching the sealed-class style the rest of the docs now use) makes it copy-paste-coherent.

3. Answer the follow-up the reporter actually asked. In #3248, @msackman ends on "how do I keep sequential ordering across event types?" — and @federicodesia points at grouping (#3143). The PR explains that handlers are independent but doesn't show the resolution. One extra snippet closes that loop:

class SearchBloc extends Bloc<SearchEvent, SearchState> {
  SearchBloc() : super(const SearchState.initial()) {
    // A single handler on the shared supertype sequences every subtype.
    on<SearchEvent>(_onEvent, transformer: sequential());
  }

  Future<void> _onEvent(SearchEvent event, Emitter<SearchState> emit) async {
    switch (event) {
      case QueryChanged():
        // ...
      case SearchCleared():
        // ...
    }
  }
}

4. Worth a one-liner on the invariant. on<E> may be registered only once per event type (it throws a StateError otherwise) — noting this makes it clear why per-handler scoping is the model rather than an accident.

On the transformer doc comments: the clarifications read well. Minor: the appended paragraph is the same three lines verbatim across all four transformers — folding the scope note into each existing **Note** (and, for sequential/restartable, pointing at the grouping pattern) keeps them tighter.

Happy to open a PR against your branch with these if that's easier, or you're welcome to lift any of it directly — whatever you and @felangel prefer. Thanks again for pushing this forward. 🙏