One line, one game

Marketing asks for “a little game in the app” every few months: a summer campaign, a loyalty reward, a daily challenge. Each time, a team builds a one-off screen that nobody wants to maintain afterwards.

Flame Gallery turns that into one dependency and one call:

final result = await FlameGallery.show(context, game: const FruitSlice());

The call pushes a full screen game with start, pause and game over menus, and completes with a GameResult you can turn into points, coupons or analytics. It is open source (MIT), built on Flame, and you can play it in your browser right now.

In numbers: 6 packages on pub.dev · 4 games · about 6,000 lines of library code · unit and game tests in every package · 6 Maestro end-to-end flows on iOS and Android.

From WebView games to native power

For years, the mini game inside a mobile app was usually an HTML5 game: JavaScript running in a WebView. It works, but you can feel it. Here is what changes when the game is drawn by Flutter itself:

• Rendering. A WebView game runs a browser engine inside your app. Flame Gallery draws with Flutter’s own engine, the same one drawing the rest of your UI.
• First load. No pages, scripts or assets to download. Everything ships in the app bundle and works offline.
• Touch and frame rate. No extra layers between the finger and the frame. Gestures and frames are handled natively by Flutter.
• Score back to the app. No JavaScript bridge and string messages. You get a typed Dart GameResult from an await.
• Look and feel. No separate web styling to keep in sync. The game uses your app’s Theme, font and colors.
• Who maintains it. Not a separate web team: the same Flutter team, the same CI.

That is the core idea: campaign games get the same native performance as the rest of your app, and the integration is one awaited function call instead of a bridge.

Four games, four Flame techniques

Every game package has the same inside: src/logic/ is pure Dart with unit tests, src/component/ holds one Flame component per file, and src/game/ only orchestrates.

Fruit Slice · flame_gallery_slice

Swipe to slice fruit, slice three or more in one stroke for a combo, avoid the bomb.

• Launch physics. LaunchPlanner picks an apex between 15% and 45% of the screen height, sets gravity to g = 1.2 · h · speed² and the launch speed to v = √(2gh). Harder levels make fruit faster, but it always reaches the same height.
• Cutting. Every segment of the swipe is tested against each fruit as a segment–circle intersection, so a fast swipe never skips a fruit between two frames.
• Halves. A sliced fruit is the same sprite cut in two with srcPosition; each half keeps the fruit’s motion and drifts away from the cut line.
• Look. A blade trail that thins and blurs as it ages, juice bursts from the shared GalleryBurst effect.

Ruins Runner · flame_gallery_runner

Top-down, three lanes. Swipe left or right to change lane, up to jump, down to slide, collect coins while the world speeds up.

• Fixed time step. The simulated step is capped at 1/30 s. Flame does not cap dt, so one janky frame could otherwise move an obstacle straight through the player.
• Fair rows. ObstacleRowPlanner always leaves at least one passable lane, verified with 50 seeds × 200 rows in tests. Collision is a table of obstacle type against player pose.
• Feel. A jump and a slide can cancel each other, so back-to-back rows stay passable even at top speed. A short invulnerability window follows every hit.

Sweet Swap · flame_gallery_match

Swap neighbouring candies; three or more in a row clear, and chain reactions score ×2, ×3. Move limit, timer and target score are all optional.

• Pure board. MatchBoard is plain Dart: matches, gravity, refill and chains come out as a list of CascadeStep records, fully deterministic for a given Random.
• Stage queue. Flame plays those steps through a queue where every stage returns its own duration. Input is locked while the queue is busy.
• No lost points. End conditions are checked only after the chain settles, so a timer that runs out mid-cascade never eats points already earned.
• Daily challenge. A seed gives every player the same board.

Note Rush · flame_gallery_rhythm

Notes fall down four lanes; tap when they reach the line. Perfect ≤ 60 ms, Great ≤ 120 ms, Good ≤ 180 ms, combos up to ×4.

• Song clock. Note positions are computed every frame from the song clock instead of summing dt, so they never drift. The clock syncs to the audio player’s position each frame.
• Bring your own audio. The library only defines a RhythmAudio interface. audioLatency compensates for headphone delay; the example app plugs in flame_audio.
• Input. Lanes take taps independently, so multi-touch works.

Quick start

flutter pub add flame_gallery

Only need one game? Each one is its own package, for example flame_gallery_slice.

import 'package:flame_gallery/flame_gallery.dart';

final result = await FlameGallery.show(
  context,
  game: FruitSlice(
    config: const SliceConfig(timeLimit: Duration(seconds: 30), bomb: null),
  ),
  onEvent: (event) => analytics.log('$event'),
);
if (result case GameResult(isCompleted: true, :final score) when score >= 50) {
  grantCoupon();
}

The result carries the score, play time, how the game ended and per-game stats. Stats are read through const keys, never string literals:

final sliced = result.stats[SliceStatKeys.sliced];
final endedBy = result.stats[GameStatKeys.endedBy]; // 'timeUp', 'bomb', 'quit'...

onEvent streams GameStarted, GameScoreChanged, GamePaused, GameResumed and GameFinished. GameResult.toJson() gives a flat map for analytics or a platform channel.

Make it your brand, without forking

Everything a company wants to change is config: colors, font, logo, background, texts, sprites and rules. Pass no colors and the game simply follows your app’s theme.

FlameGallery.show(
  context,
  game: FruitSlice(
    theme: GameTheme(
      colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xFF00897B)),
      logo: const AssetImage('assets/brand_logo.png'),
      background: const GameBackground.gradient(
        LinearGradient(colors: [Color(0xFF004D40), Color(0xFF00897B)]),
      ),
    ),
    strings: FruitSlice.stringsTr.copyWith(title: 'Summer Campaign'),
  ),
  overlays: GameOverlayBuilders(
    gameOver: (context, ui) => MyResultSheet(
      score: ui.result()?.score ?? 0,
      onAgain: ui.start,
      onClose: ui.close,
    ),
  ),
);

• Your own sprites. GameAsset('assets/products/can.png') swaps any image; GameAnimation turns a horizontal sprite strip into an animation.
• Your own menus. Replace the start, HUD, pause or game over overlay; ui hands you the strings, the score and the actions.
• Your own sounds. The library plays nothing itself. It emits cues (coin, hit, slice, noteHit…) and you map them to whatever audio package your app already uses.
• Your own difficulty. Presets like SliceDifficulty.hard stay, and copyWith tunes any number on top of them.

Architecture: how it fits together

Packages and their borders

The repo is a pub workspace managed with Melos. Every game is its own package; all of them depend on one core and never see each other. Most host apps only add the facade.

Library packages depend only on flutter and flame: no bloc, freezed, get_it or audio package, so a host app never inherits our version choices. State lives in private ValueNotifiers exposed as read-only ValueListenables.

A two-layer game contract

• GalleryGame<G>, for the host app. An immutable recipe: config, GameTheme, GameStrings. createGame(colors) builds a fresh Flame game for every session and buildHud builds the HUD. FruitSlice, SweetSwap and the others are these.
• GalleryFlameGame, for the game engine. Owns the phase machine, the score, the overlays and the event stream. A game only implements onRoundStart(), calls addScore() and finish(), and adds stats in collectStats().

Only the core changes the phase. Games check isPlaying before scoring or penalising, so a late event after the round has ended can never change the score.

One session, start to finish

The event stream is synchronous on purpose: the quit result raised while the game is being removed still reaches the host before it unsubscribes.

How graphics are managed

A library that runs inside someone else’s app cannot leak memory, fight over a global cache or drain the battery. These are the rules every game follows.

• A private image cache per game. GalleryFlameGame gives each game its own Images(prefix: ''). The global Flame.images is never touched, so other Flame games in the host app are not affected.
• The cache is cleared on close. Flame only clears images in dispose(), and GameWidget never calls it. The core clears the cache in onRemove, so opening a game fifty times does not grow memory fifty times.
• One way to name an asset. GameAsset('assets/my_fruit.png') (plus an optional package) becomes a bundle key. The same type points at our placeholder sprites or at the host’s product images.
• Parallel loading. loadSprites(assets) loads every sprite with Future.wait and keeps their order.
• Animations from strips. GameAnimation turns a horizontal sprite strip into a SpriteAnimation: frame count and step time, nothing else.
• Backgrounds behind the canvas. GameBackground is a sealed type (color, gradient or image). The host page draws it behind the GameWidget, and games return resolveBackground(colors.surface) from backgroundColor(), which turns transparent when a backdrop exists.
• Shared effects. Juice bursts and floating “+10” labels come from GalleryBurst and FloatingLabel in core. TextPaints are created once in onLoad, never per label.
• Two random sources. Particles use a separate _effectsRandom. The injected Random drives gameplay only, so a seed reproduces the same spawns however the player plays.
• Battery. The engine pauses 0.8 s after game over: enough for the last effects to finish, then frames stop.
• System UI. Games run in immersiveSticky and restore edgeToEdge on close; immersive: false opts out.
• IP-clean art. Mechanics are free, names and art are not. Every sprite and the music are generated placeholders, so companies can ship them or swap in their own.

Technical decisions and why

• One package per game. A company adds only the game it needs; games cannot break each other; shared needs go to core.
• Minimal dependencies. No version clashes with the host app. Even audio is an interface; the example app wires it with flame_audio.
• Pure Dart logic layer. Physics, rules and board logic are tested in milliseconds, without Flame.
• Immutable config + copyWith. Campaign variants are easy to derive. Nullable fields take a ValueGetter: copyWith(bomb: () => null) removes the bomb.
• @internal entry points. Game classes are exported for the HUD, but methods like swipe or spawnWave stay closed outside the package.
• final class everywhere. Concrete classes are final, contracts are abstract base or abstract interface, event families are sealed.

Testing a game engine, for real

• Rules, with test. Launch physics, slice geometry, combos, the row planner’s guarantee, board generation and cascades, timing windows, the song timeline.
• Game flow, with flame_test. Phases, score, end conditions, sound cue order; Random(seed) makes every run repeatable.
• End to end, with Maestro. All four games on an iPhone 17 simulator and a Pixel 7a emulator: menus, pause, HUD values, exact scores, the result returned to the host.

Menus and HUD values carry Semantics(identifier:) ids (GalleryKeys, RunnerKeys, MatchKeys, RhythmKeys), so tests look for ids, not text, and work in any language. On the seeded Sweet Swap board, one specific swap is verified end to end to trigger a three-level chain worth exactly 210 points.

Lessons from testing a Flame game with Maestro

• A running game is never “idle”, and every element lookup waits for idle: 1–3 s on iOS, about 10 s on Android. HUD checks run while the game is paused.
• On Android, a swipe that starts at the screen edge becomes the system back gesture (pause, then close). Test swipes start between 12% and 88% of the width.
• The first switch to immersive mode shows a one-time Android hint; a shared sub-flow taps it away.

From merge to pub.dev

A release is a version bump plus a CHANGELOG entry. When CI is green on main, release.yml tags every package whose version is not on pub.dev yet (flame_gallery_core-v0.2.0) and runs publish.yml on each tag in order. Publishing uses pub.dev’s GitHub OIDC, so no token lives in the repo. It runs flutter pub publish, because the stock dart-lang/setup-dart workflow cannot publish packages that depend on the Flutter SDK.

The packages on pub.dev

• flame_gallery: the facade, FlameGallery.show and every game. Start here.
• flame_gallery_core: contracts, host page, menus. Use it to build your own game.
• flame_gallery_slice: Fruit Slice
• flame_gallery_runner: Ruins Runner
• flame_gallery_match: Sweet Swap
• flame_gallery_rhythm: Note Rush

What’s next

• flame_gallery_native: native iOS and Android apps open the same games through Flutter add-to-app, with GameResult.toJson() as the payload back. A team without Flutter gets native-rendered mini games too.
• Android polish: keep the side-edge back gesture from interrupting play.
• Quality: golden tests for menus and HUD, and frame-time measurements in profile mode on physical devices.
• More games on the same core.

Try it, break it and tell me what your campaign needs. Issues and pull requests are welcome.

• Play in the browser: vb10.github.io/flutter_flame_gallery/play
• Website: vb10.github.io/flutter_flame_gallery
• GitHub: VB10/flutter_flame_gallery
• pub.dev: flame_gallery

GitHub - VB10/flutter_flame_gallery: Drop-in, brandable 2D mini games for Flutter apps, built on Flame: Fruit Slice, Ruins Runner, Sweet Swap (match-3) and Note Rush (rhythm). One call: FlameGallery.show(context, game: ...).

Flame Gallery: Drop-in Mini Games for Flutter Apps was originally published in Flutter Community on Medium, where people are continuing the conversation by highlighting and responding to this story.

🙌 TL;DR I created a dart script to automatically migrate your Flutter project with ease. You can find it at the bottom of this article.

If your application or plugin supports Flutter version ≥ 3.44, then you might consider migrating it to use Built In Kotlin support. This is needed in order to support Android Gradle Plugin (AGP) versions ≥ 9. If you are not supporting Flutter version ≥ 3.44 or if your project is not currently using AGP ≥ 9, you don’t need to do this right now, but you might want to consider it.

I have undergone this migration process with one of my applications, and would like to share the process I had to go through, so you may have an easier going though it.

✋ If you have a Flutter plugin that is a pure Dart plugin (meaning no native Android code), then you don’t need to do anything regarding the migration and you can leave it as is.

Setting up Flutter ≥ 3.44

The first thing you need to do in order to migrate your application/plugin is to make sure you are on a Flutter version that supports it. That means, to upgrade your local Flutter version to at least 3.44. Before you upgrade the version, make sure you are on the stable channel in Flutter. You can do so by opening up a terminal and typing:

flutter channel

If the output shows you that you are on the stable channel, you can proceed to upgrade by typing:

flutter upgrade

This will upgrade your Flutter version to the latest one in the stable channel.

After doing this, we need to also declare in our pubspec.yaml file what our minimum supported Flutter version is:

environment:
  sdk: ^3.2.0
  flutter: '>=3.44.0'

Upgrading AGP ≥ 9 (the manual approach)

To upgrade the Android Gradle Plugin version to be ≥ 9, you need to open the android folder of your Flutter project. Make sure you have at least Android Studio Otter 3 since that is the first version that supports AGP 9. Once you have opened the project, you can use the AGP Upgrade Assistant under the Tools menu option.

Now, there are several changes you need to make in the project.

1. In the build.gradle file located under android/app, remove the

id “org.jetbrains.kotlin.android”

in the plugins block. So this:

plugins {
    id "com.android.application"
    id "org.jetbrains.kotlin.android"
    id "dev.flutter.flutter-gradle-plugin"
}

becomes this:

plugins {
    id "com.android.application"
    id "dev.flutter.flutter-gradle-plugin"
}

2. Change this block:

kotlinOptions {
        jvmTarget = '17'
    }

to

kotlin {
    compilerOptions {
        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
    }
}

Moving on to the gradle.properties file:

3. Remove the

android.defaults.buildfeatures.buildconfig=true

4. Add the following attributes

android.builtInKotlin=true
android.newDsl=false

Not Done Yet (Dependencies)

It might seem like your past the migration, but there is one more step you need to do. If your Flutter project has any dependencies, you need to make sure those dependencies support built in Kotlin as well. So what you need to do is:

• Go over each dependency and see if there is a version for it that has built in Kotlin support
• If it doesn’t have one, you have two choices: Either swap it out with another dependency that gives you the same functionality but has built in Kotlin support, or don’t migrate your Flutter project until this dependency does

Automation

At this day and age, why would we want to do anything by hand? There’s no reason for it. That is why I created a pure Dart script you can run on your project to get the necessary output of what needs to be done.

When running it on a Flutter project of mine that was not migrated, I got the following output:

[TODO] Project "pill"
       Path: PROJECT_PATH
       Type: Flutter app
       Result: Migration needed
       - AGP: 8.9.1   Kotlin plugin version: 2.1.0   Gradle: 8.11.1
       - android.builtInKotlin: not set   android.newDsl: not set   Kotlin source files: 1
       - Kotlin plugin applied at android\app\build.gradle.kts:3
       - Kotlin plugin declared (apply false) at android\settings.gradle:22
       - Kotlin plugin declared (apply false) at android\settings.gradle.kts:23
       - Dependency audit: 2 Android build file(s) checked; 1 package(s) apply the Kotlin plugin unconditionally, 0 only inside a condition.
       Blockers:
         * shared_preferences_android-2.4.23: build.gradle.kts:34   id("kotlin-android")
       Proposed edits (nothing changes until you approve):
         1. Remove the applied Kotlin plugin
              android\app\build.gradle.kts
                line 3:  - id("kotlin-android")
         2. Remove "android.defaults.buildfeatures.buildconfig=true" (rejected by AGP 9)
              android\gradle.properties
                line 4:  - android.defaults.buildfeatures.buildconfig=true
         3. Add android.builtInKotlin=true
              android\gradle.properties
                after line 6:  + android.builtInKotlin=true
         4. Upgrade AGP 8.9.1 -> 9.0.1
              android\settings.gradle
                line 21:  - id "com.android.application" version '8.9.1' apply false
                            + id "com.android.application" version '9.0.1' apply false
         5. Upgrade AGP 8.11.1 -> 9.0.1
              android\settings.gradle.kts
                line 22:  - id("com.android.application") version "8.11.1" apply false
                            + id("com.android.application") version "9.0.1" apply false
         6. Upgrade the Gradle wrapper 8.11.1 -> 9.3.1 (AGP 9 requires a newer Gradle)
              android\gradle\wrapper\gradle-wrapper.properties
                line 3:  - distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip
                            + distributionUrl=https\://services.gradle.org/distributions/gradle-9.3.1-bin.zip
         7. Raise the Kotlin version pin 2.1.0 -> 2.3.20 (Flutter rejected anything below 2.2.20 when I checked) [optional]
              android\settings.gradle
                line 22:  - id "org.jetbrains.kotlin.android" version "2.1.0" apply false
                            + id "org.jetbrains.kotlin.android" version "2.3.20" apply false
       Manual steps (this tool does not do these):
         1. Replace the kotlinOptions block at android\app\build.gradle.kts:18 with a top-level block (outside android { }):
           kotlin {
               compilerOptions {
                   jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
               }
           }
         (Not automated: where this block belongs depends on your file.)
         2. Upgrade or replace the plugins listed under "Blockers", or fall back to android.builtInKotlin=false on AGP 9 with the Kotlin plugin kept.
       Note: Both settings.gradle and settings.gradle.kts exist in android. Gradle only uses one of them, so a stale duplicate can make this report misleading and doubles the proposed edits. Check which one is real and consider deleting the other.
       Note: Keep the Kotlin plugin declaration with "apply false" in settings.gradle: on AGP 9 it pins the Kotlin version.

Warning: git reports uncommitted changes in:
  PROJECT_PATH
Committing or stashing first makes the edits easy to review.
Continue anyway? [y/N]: y
Apply all 6 proposed edit(s)? [y]es / [n]o / [s]elect one by one: y

Optional: Raise the Kotlin version pin 2.1.0 -> 2.3.20 (Flutter rejected anything below 2.2.20 when I checked)
  android\settings.gradle
    line 22:  - id "org.jetbrains.kotlin.android" version "2.1.0" apply false
                + id "org.jetbrains.kotlin.android" version "2.3.20" apply false
  Apply this optional edit? [y/N]: y
  updated android\app\build.gradle.kts
  updated android\gradle.properties
  updated android\settings.gradle
  updated android\settings.gradle.kts
  updated android\gradle\wrapper\gradle-wrapper.properties

Changed 5 file(s).
Backup of the originals: C:\Users\tomer\Documents\Projects\Pill/.builtin_kotlin_backup/2026-10-23T11-13-59
To undo, copy the backed-up files back over the originals, or use git. Delete the .builtin_kotlin_backup folder when you are done.
Next: run "flutter clean", "flutter pub get", then "flutter run".

It also automatically detects if your Flutter project is a plugin or an application and only proceeds to make changes based on your approval.

And after the migration, you will see:

Re-checking after the edits:

[WARN] Project "pill"
       Path: PROJECT_PATH
       Type: Flutter app
       Result: Migrated, but blocked by dependencies that still apply the Kotlin plugin
       - AGP: 9.0.1   Kotlin plugin version: 2.3.20   Gradle: 9.3.1
       - android.builtInKotlin: true   android.newDsl: not set   Kotlin source files: 1
       - Kotlin plugin declared (apply false) at android\settings.gradle:22
       - Kotlin plugin declared (apply false) at android\settings.gradle.kts:23
       - No Kotlin plugin is applied and builtInKotlin=true on AGP 9.0.1: already migrated.
       - The Kotlin plugin declaration with "apply false" is a version pin. That is expected here: it keeps the Kotlin version at or above Flutter's minimum.
       - Dependency audit: 2 Android build file(s) checked; 1 package(s) apply the Kotlin plugin unconditionally, 0 only inside a condition.
       Blockers:
         * shared_preferences_android-2.4.23: build.gradle.kts:34   id("kotlin-android")
       Manual steps (this tool does not do these):
         1. Upgrade or replace the plugins listed under "Blockers", or fall back to android.builtInKotlin=false on AGP 9 with the Kotlin plugin kept.
       Note: Both settings.gradle and settings.gradle.kts exist in android. Gradle only uses one of them, so a stale duplicate can make this report misleading and doubles the proposed edits. Check which one is real and consider deleting the other.

Summary: 1 project(s) analyzed, 1 need attention.

You can find it here →

If you would like to read other articles I have written, you can see them here →

GitHub - TomerPacific/MediumArticles: A repository that contains code associated with various Medium articles I have written

References:

• Documentation

Migrating A Flutter Project to Built In Kotlin was originally published in Flutter Community on Medium, where people are continuing the conversation by highlighting and responding to this story.

If you have written E2E tests for a Flutter app, you have probably run into this: someone renames one widget key or changes a button label, and a whole row of tests turns red. Then the time goes into fixing test scripts instead of real problems in the app.

In mid-September, TypeSafe AI released Jev, a model made only for decisions. It works differently from a normal LLM. We first list the possible answers as options, then it picks one of them and tells us how sure it is, but it never generates any text.

When I saw this design, the first thing I thought of was Flutter. Every widget on a screen that you can tap or type into is already part of a limited list, so if we give that list to Jev, it should be able to decide the next step of an E2E test, and when the UI renames something, it can read the new name from the current screen. For the past few weeks I connected it to the E2E tests of a Flutter app and ran it many times, and in this article I want to share the process and the results with you.

Here is the conclusion first. In E2E tests, letting Jev pick every step, letting an LLM write only the text, and asking the LLM to referee when Jev cannot decide, was the best value combination I measured:

• Correct → 18/18, the same as an agent that uses an LLM for everything
• Robust → 12/12 after the UI renames
• Fast → 1.7x faster than the all-LLM agent
• Cheap → 3.5x cheaper than the all-LLM agent, with zero false passes

The rest of this article covers what Jev can do for Flutter, how it differs from a normal LLM (not quite what I expected), how to combine the two, and which situations did not work well in my tests. All numbers were measured on my own machine.

A few terms used in this article:

• marionette → an open-source tool from LeanCode that lets an outside program read and control a running Flutter app
• E2E test → a program operates the app automatically and goes through the flow a real user would
• agent → the model looks at the screen and decides the next step by itself, instead of following a script

How the widget tree connects to Jev

First, the overall architecture. The app, the runner and the judging all run locally. Only two kinds of request leave the machine: asking Jev for the next step, and asking an LLM to write text or to referee.

From a running app, marionette can read each interactive widget’s type, key, visible text, enabled state and position. I turn that into a list like this:

@e1 TextField key=email_field = (empty)
@e2 TextField key=password_field = (empty)
@e3 CheckboxListTile key=remember_me
@e4 FilledButton key=signin_button
@e5 TextButton key=forgot_password_button

This list goes into the request to Jev almost unchanged:

body = {
    "model": "jev-latest",
    "state": state,                      # screen + task + actions taken so far
    "questions": {
        "nextAction": {
            "type": "choice",
            "instructions": "Pick an action that moves the task forward",
            "criteria": {a.id: a.description for a in actions},
        },
        "taskComplete": {"type": "noul",
                         "instructions": "Looking at the screen only, is the task done?"},
    },
}

The important line is criteria. Its value is the list of actions read from the screen, in the form {action id: what this action does}, and the model can only answer with one of those keys.

I also really like that questions can hold several questions at once. The request above asks two things: "where to tap next" is a choice question, and "is the task already done" is a noul question that returns a judgment from 0 to 1. One round trip gives us two answers. The "is it done" question matters a lot later, because it decides whether the whole test can report a false success.

Of course, there is still a layer of code I wrote in the middle, and it is not short. By default marionette returns every property of every widget, including the controller, decoration, colorSpace and so on. A sign-in screen with only nine elements is already 5,488 characters, about 1,370 tokens. After converting it into the format above, it is only 337 characters, about 85 tokens, which is 94% smaller. The description of each action is also generated by the code.

At first I thought Jev would at least save us from handling hallucinations, because an LLM might invent a button that does not exist, while Jev can only answer with a key from the list. After testing, this advantage turned out to be smaller than I thought. As long as the LLM uses structured output and its answer is limited to the keys of the same list (Gemini’s responseSchema supports enum), it never picked a nonexistent action in 749 decisions, with zero retries. So for hallucinations, both sides can rely on the type system.

What really makes Jev different is the probability it returns. There is an experiment about this later, and it was the result that surprised me the most.

The same pattern appears in other places. When GenUI decides which widget to use for the next screen, it also picks one from a catalog of widgets. In the next section I simulate this step and measure it, without using the real GenUI. Support ticket classification and PR risk levels in CI look similar too, but I have not actually tested those two. My own rule is that if the range of possible answers can be listed, this approach probably works.

Separate deciding from producing

This section started from a demo that Abdallah Shaban shared on X: a Flutter GenUI screen where every widget was picked by Jev from a widget catalog, and he said it felt as fast as running everything locally. Someone asked under the post, “where does the text in the widgets come from?” In this section I first break down that “fast” and measure it. Where the text comes from is answered later, in the “Let Jev pick, let the LLM write” section. Below are the measurements; the catalog and the data are my own.

I did not use Flutter’s genui package. I only simulated the step where it picks a widget: I wrote my own widget catalog, let the models output the A2UI format GenUI uses, and measured what they returned and how long it took. With the same catalog and twelve real chat turns, each run three times, I compared three approaches:

• Gemini writes the full UI description JSON
• Gemini only returns the name of one widget
• Jev picks one from the same catalog

The “only return a name” group is one I added on purpose. Without it, “generating vs picking” and “an LLM vs a model that cannot write” would be mixed together as two variables, and the comparison would not tell us much.

The results can be read in two parts. Letting the model decide and produce JSON at the same time costs an extra 600 ms, and in this sample its agreement was also lower, 75% against 83%. Tying deciding and producing together does not help either side. The other part is that when both only pick a name, Jev is 3.4x faster than the small model.

But I would not say Jev is more accurate. In this round it actually got five fewer answers right, 25/36 against 30/36. Most of the misses were in two turns: for “where is my refund” it picked the order list, and for “what’s in my cart” it twice picked a plain text reply. Twelve turns run three times are really only twelve questions, so this gap is not enough to say which one is more accurate, but we also cannot say they are the same. What is certain is the speed, more than three times faster.

There was also one turn that all three approaches “got wrong”, and later I felt I had labeled it wrong myself. The user said “I got the wrong size”, and all three picked the order list instead of the return form. Thinking about it again, they were right: the user did not say which order, so showing the list first is reasonable. I prefer to list disagreements like this instead of counting them as errors.

After a UI rename: scripts versus agents

Let’s start with the most direct example. In the demo app, I renamed the key nav_orders to nav_orders_v14. The hand-written test script could not find the widget and failed at step 4, while the agent running the same flow finished all 13 steps. Here is its log:

step 4: Tap @e7, the NavigationDestination nav_orders_v14
step 7: Tap @e2, the FilledButton start_return_button_v14
step 8: Tap @e3, the FilledButton return_next_button_v14

Nobody told the agent that the name had changed. It read the new key from the current screen and used it directly.

I added these changes to the demo app on purpose. The app has a switch that takes a number (called a seed in the code; the same number always produces exactly the same changes, so the script and the agent face the same set of changes). It renames about two in five widget keys, swaps a few button labels and shuffles some lists, which is the kind of UI change a team makes in a normal week of development.

We need to be clear about what this example proves. A hand-written test hard-codes the UI’s implementation details, and an agent does not, so when the UI changes, the script has to be updated and the agent does not. An LLM agent can do the same, just slower and at a higher cost. I measured this too: with the same four flows and the same value table, only changing the deciding model from Jev to gemini-3.1-flash-lite, both were 12/12, and the LLM was 2.7x slower and 4.7x more expensive.

After expanding to 4 sets of changes with 3 runs each, the results are:

The script failing every time was what I expected. The surprise was that “Jev only” got just 6/12. Its choices were right. It stopped on seeds 7 and 91 because those two seeds renamed the email field, from email_field to email_field_v17, while my hand-written value table still looked values up by the old key. With no value found, Jev could tap the field but could not type into it, its confidence dropped, and it stopped before the threshold.

In other words, a value table is also a kind of selector. When the UI is renamed it breaks as well, just in a safer way. The two approaches where the LLM writes text from the current screen do not have this problem, and the one where Jev does the picking is 1.9x faster and 4.3x cheaper. Its one miss has nothing to do with the rename. It was the navigation stop I explain later, and with the referee added it went to 12/12.

So in this example, the real value Jev brings is the risk-tiered threshold table later in this article, not just the fact that the test passed.

There is also one case I originally wanted to use as an example and later downgraded myself. In the first comparison, the hand-written support flow got stuck on contact_us_button. This button is below the FAQ list, outside the screen, so the script could not tap it. The agent passed, because at step 5 it typed refund into the search box, the list got shorter and the button appeared. That step was not in the script, and I had not thought of it either. However, the string refund came from my value table. Jev does not produce text; what it did was decide to use the search box to move forward. So this is more of an advantage of agents in general, not something special about Jev.

This value table later became the bottleneck of the Jev-only approach, and the 6/12 above was caused by it. I explain later how I handled it.

Why give the decisions to Jev: risk-tiered thresholds

I got this part wrong at first. I set one global threshold: below a confidence of 0.55, stop instead of guessing. The model kept picking the right next step and kept getting blocked. Once it correctly chose to “fill in the password, then tap sign in” with a confidence of 0.45, and it was blocked.

Then I went back to the official docs, which explain it clearly:

low confidence on a Choice often means none of the options are a clear winner over the others

The confidence of a Choice shows how flat the probability distribution is, in other words how closely the options compete, which is a different thing from whether the answer is right. When two actions can both move the flow forward, a low confidence is actually an honest answer, and blocking it is the mistake.

After I set a different threshold for each kind of action based on its risk, the problem was solved:

CONFIDENCE_FLOOR = {
    "scroll": 0.20,   # just scroll back
    "fill":   0.30,   # typing can be redone
    "tap":    0.35,   # navigation can go back a page
    "submit": 0.70,   # writes something the user will see
    "finish": 0.60,   # a wrong "done" makes the whole test lie
}

A wrong scroll can just be scrolled back, but a wrong “done” makes the whole test report a wrong result. These two cases should not share one threshold.

For this table to work, the probability itself has to mean something: decisions at a confidence of 0.7 should really be wrong less often than decisions at 0.3. TypeSafe says their probabilities are calibrated, but I did not verify this myself, so I do not treat it as a conclusion. Verifying it needs a correct answer key, and this task does not have one. What I can share is the result in practice: after switching to risk tiers, all 24 runs passed, while the old global 0.55 threshold blocked correct decisions. It is not as good as a calibration curve, but at least it is what I actually saw.

Same wrong data, only one side reports a false pass

Later I added an experiment to see whether this probability actually helps when something goes wrong.

The task was “report that order 5198 arrived damaged”. I deliberately did not update the value table, so it still held the values from another flow: order 5213, with the message “my parcel has not moved in four days”. Then Jev and gemini-3.1-flash-lite each ran it three times. Both got exactly the same screens, candidate actions and value table; only the deciding model was different. For judging, I did not look at what the agent reported. After each run I read the app's store directly to check whether a support ticket was sent and what it said.

The LLM reported success all three times, and all three times it was wrong: it sent the wrong support ticket and still reported the task as done. Jev did not finish any of the three, but it did not write any wrong data either. Another task, “add a new address labeled Home”, went the same way, with Office in the value table. The LLM saved an Office address from the table and reported success, all three times. Jev filled in Office from the table, its confidence dropped to between 0.28 and 0.34, and it stopped.

Jev’s probability reflected that the input did not match the task, and the LLM’s self-reported confidence did not. This was the first time the risk-tiered table had experimental data behind it, not just “it passes when we use it”.

The scope of this experiment needs to be clear too. The temperature was 0, so three repeats are not three independent samples; it is closer to looking at the same situation three times. And it is only two tasks and one app, not a full calibration curve. But the direction is clear: a test that reports a false success is more dangerous than a test that fails, and that is exactly the difference here.

If you want to use this in a real project, I suggest spending half a day first: group the decisions you have run by confidence, label them right or wrong by hand, and see what the curve looks like. This is also the next thing I want to do.

The way I used to build tools was the opposite: let the model decide freely, then add checks afterward to catch hallucinations. Defining the options in code, letting the model only pick, and setting thresholds by risk is a different approach, and the threshold is a number you can tune, not a prompt.

When I reran everything with the new home screen, I ran into a real example. The new home screen has two equally correct ways to reach the orders page: the Orders tab at the bottom, and the “Your orders” shortcut. Jev’s confidence at this step was between 0.34 and 0.53, with the probability split across two correct options. Out of the 27 decisions the return flow made at this step, 3 landed exactly at 0.34, below the tap threshold of 0.35, so it stopped. It did not pick wrong and did not report a false pass; it just honestly showed that both ways were fine. This is also why thresholds should be tiered by risk: navigation can go back a page, so its threshold can be lower, or the screen can keep only one way. I did not tune the threshold to make the numbers look better, so that is where the no-referee results of 17/18 and 11/12 come from.How the referee closes those two gaps is in “When Jev cannot decide, ask the LLM to referee” below.

Following this, I also ran into a more basic problem. Once I saw a confidence of only 0.40, and my first thought was that the model was not strong enough. After checking, I found that the home screen had eight InkWell and GestureDetector widgets without keys, so the option list contained eight tap_gesturedetector_x_x_x_x entries. When the options themselves are unclear, the model's confidence cannot be high.

Let Jev pick, let the LLM write

We already saw the weakness of the Jev-only approach: it cannot write, so it cannot type anything the value table does not have. It got 0/6 on the two new tasks, although it safely stopped every time.

So I split the two jobs. Which action to take at each step is up to Jev, and only when a new input field appears do I call gemini-3.1-flash-lite once to write the text. Once for sign-in and once for a form, a full run calls the LLM only 2.7 times on average, and Jev handles all the other steps.

One step looks like this, with Jev and the LLM each appearing only in their own part:

This is what a real run of the combination looks like. The task is one sentence, “sign in and report that order 5198 arrived damaged”. Filled tags are actions Jev picked, outlined tags are text the LLM wrote after reading the screen, and the last frame shows the support ticket the app actually received:

The same task, “report that order 5198 arrived damaged”, run once with each of four approaches:

When Jev cannot decide, ask the LLM to referee

Earlier, on the new home screen, Jev could not decide between two correct ways and stopped at the threshold 3 times. To handle this, I did not change the threshold. Instead I added a seventh approach: when Jev is not confident enough on a step that can be undone (tap, scroll, typing), it does not stop, and flash-lite picks one from the same options instead. Submitting and judging “done” still stop, because low confidence there usually means the input data itself is wrong. I ran a separate batch of the six tasks plus the four UI changes, 30 runs in total. All of them finished with no false passes, at $0.00098 per run, almost the same as $0.00094 without the referee. The referee was called only once, on the renamed home screen at the step where confidence was 0.33. It picked the Orders tab and the flow finished. Only one tie came up in 30 runs, so part of this 30/30 is luck, but the direction is clear: when there is a tie, asking once more is a better deal than stopping.

Comparing all seven approaches

Six tasks (the original four flows plus two new tasks), three runs for each approach, judged by reading the store as before:

The sixth approach, the combination without a referee, got 17/18 and the all-LLM agent 18/18.The one miss was the navigation stop mentioned above, and it wrote no wrong data. The seventh approach with the referee closed the gap at 18/18. In return it is 1.7x faster and 3.6x cheaper. After the UI renames, the combination got 11/12 and the all-LLM agent 12/12, with the combination 1.9x faster and 4.3x cheaper, while the hand-written script got 0/12. Compared with the flagship model, the combination is 5.8x faster, 57x cheaper, and more accurate. Pro got 14/18: in the support flow it went to the tracking page of order 5213 all three times instead of the support tab, and finally reported that it could not finish. In a flow that moves forward one step at a time, more reasoning only makes it slower and more expensive, and the accuracy did not go up with it.

The first version of the combination actually missed once, because I wrote the prompt wrong. The task “add a new address labeled Office” did not mention a street, and I had told the writing model to “leave fields the task does not need empty”, so it left the required address field empty too. Jev’s confidence when saving was only 0.29, so it stopped and wrote no wrong data. After adding “for a required field the task does not mention, fill in a reasonable value”, it did not happen again, and all later numbers use the fixed version.

The hand-written script is still the fastest, as long as it is correct. For new tasks there is no script at all, and someone still has to write one.

This split follows the same idea as the GenUI section: writing goes to the model that can write, and only when needed. Picking each step and judging whether the task is done goes to the model that honestly tells you how unsure it is. When it cannot decide and the step can still be undone, we ask the model that can write to pick once.

Before you start: the quality of your key names

This part is specific to Flutter, and it is something I did not expect.

The agent’s action descriptions are generated from key names. Key('start_return_button') becomes "Tap the FilledButton start_return_button", and the model can understand what that is. On the other hand, if the keys are named carelessly, or there are no keys at all, the agent can only match on visible text, so it breaks as soon as the copy changes and becomes as fragile as a hand-written script again. How well your keys are named directly affects how understandable the options are for the model.

One more detail, so you do not waste a round of testing like I did: changing only the key without changing the Semantics identifier is the same as not changing it, because the tool falls back to the identifier. The first time I ran the rename experiment it had no effect at all, and it took me a long time to find out why.

When it is worth it: split the total time first

To decide whether Jev fits a situation, my way is to split the total time first and see how much of it the model calls take.

For this project, the conclusion is not very good for Jev. One return flow takes 12.8 seconds. Split up: Jev made 18 decisions in 4.4 seconds (35%), 189 transport calls took 1.9 seconds (15%), and the remaining 6.5 seconds or so (51%) were spent waiting for the app’s own animations and loading.

The model is only a bit over a third of the time. That means even if Jev took zero seconds, the whole test would only be about 1.5x faster, 1.53x by the breakdown above. The rest of the time goes to Flutter’s page transitions, waiting for the screen to settle, and the number of steps itself, none of which depends on the model’s speed.

At first I spent a whole round tuning parameters and the multiplier never showed up, because the part I was optimizing was only a third of the total. I should have split the time first and then decided what to tune, and I only realized this after I was done.

My rough rule is:

• The model is 80% of the time or more → the multiplier shows up directly, and switching is well worth it
• The model is only a third → the ceiling is about 1.5x, and you will barely feel the difference
• Somewhere in between → do the math yourself

The best fit is a judgment that finishes in one call, such as classification, routing, scoring, filtering, or acting as a verifier for another model. It fits less well when the model is just one small step in a loop, like driving a UI, crawling web pages, or anything that waits for an outside system.

The multiplier is real in single-call tasks

To check this, I ran a separate single-call experiment, used for picking stories for my daily tech digest. Given one news item, it returns three typed judgments: whether to include it, which category it belongs to, and how technical it is. The material was 20 real Hacker News items fetched from the API, and each of the three models ran 40 times.

Compared with a flagship model that reasons, Jev is 19.5x faster and 220x cheaper. The gap comes mostly from 364 thinking tokens. The flagship model’s final answer is only 26 tokens, but before that it writes 364 tokens of thinking that the user never sees, and you still pay for the time and the cost.

The trade-off is agreement. On the same 20 items, Jev and the flagship model agreed on “include or not” 14/20 and on “which category” 13/20, and on both at the same time only 9/20. Neither side is a correct answer key. “Would a senior engineer want to read this” is a subjective judgment, and two people would not agree on everything either, so I can only talk about agreement, not accuracy.

The more complete way to say it: 19.5x faster, 220x cheaper, a third of the answers differ, and this experiment cannot tell which side is right.

What E2E tests actually get

Driving a UI is not where the multiplier lives, so what does Jev bring to E2E tests? First the numbers, four flows with three runs each, all 24 runs passed:

The script is faster on all four flows. The script already knows the answer to every step, while the agent has to ask the model at each step. As long as the script is correct, it will always be faster, and tuning parameters cannot change that.

I ran into the “as long as the script is correct” condition myself. After I moved the “Add to cart” and “View cart” buttons on the product page into a bar fixed at the bottom of the screen, the add-to-cart script became more than 6 seconds slower on every run. The reason was two scroll_to steps still left in the script. The buttons were already on screen, so scrolling changed nothing, and the runner kept waiting for the screen to change until it timed out. When a script no longer matches the UI, the result is not always a failure. Sometimes it just gets slower quietly, and the test still looks green.

So the benefit Jev brings to E2E is two things other than speed. The first is the rename example earlier: when the UI changes the script breaks and the agent does not, which happens almost every week in real projects. The second is that the cost is low enough to ignore. One full run costs $0.0007 on average, about 15,000 input tokens. Running four flows for each PR costs about $0.0026, twenty PRs a day is five cents, and a month is about one and a half US dollars. The median latency of each decision was between 221 and 236 ms, measured from Taiwan to the US West.

Agent tests used to be hard to put into CI mainly because they were slow and expensive. The slow part is still there, about 1.5x to 3x slower, but the cost is no longer a problem.

How to start

Putting it all together, among the agent approaches, the combination with the referee is the best value: the same accuracy as an all-LLM agent, much better speed and cost, and no false passes.

Jev no longer has a waitlist. I use an official TypeSafe API key: sign in at console.typesafe.ai with Google or email, and create one under Settings → Keys. I recommend the official key first, because the direct connection is the fastest, and all the latency numbers in this article were measured on it, from Taiwan to the US West. If you cannot use an official key, you can also call Jev through OpenRouter, but the extra hop is much slower. In my tests a call through OpenRouter took 1.3 to 2.2 seconds, while calling TypeSafe directly took about 0.36 seconds.

If it were me, I would start like this:

• Use it first on flows whose UI changes often, places where hand-written scripts often break, and new flows nobody has written a script for yet. These are where an agent does better than a script: after the UI renames, the script got 0/12 and the combination with the referee got 12/12. Critical flows that are stable can stay as they are. As long as the script is correct, it is still the fastest (3.8 seconds) and free, so the two can live side by side.
• Give each step’s choice and the “is it done” judgment to Jev, with thresholds set by the risk of the action: 0.70 for submit and 0.60 for judging done.
• Call a cheap LLM to write only when a new input field appears, and remind it: “for a required field the task does not mention, fill in a reasonable value”. For steps that can be undone, like tap and scroll, if Jev is not confident enough, let the same LLM referee once.
• When judging the result, read the app’s state directly instead of trusting the pass the agent reports. That is how the three false successes above were caught.

The cost is about $0.001 per full run. Twenty PRs a day with four flows each comes to about 8 cents.

There are also a few things to watch out for. I ran into thirteen problems along the way, and half of them came from the tools themselves. A hot restart replaces the isolate, so a persistent connection keeps holding a tree that no longer exists. Elements outside the screen do not appear in the list at all, rather than being marked as invisible. A SnackBar removes the buttons under it from the widget tree completely until it closes. And on macOS, when the app window is fully covered by another window, it stops drawing, so the agent reads an empty screen and every approach fails at the same place, which is easy to mistake for a model problem.

The sample size also needs to be clear: one app, three runs for each case, temperature 0. If you want to use these results to convince your team, I suggest running it on your own app first.

Conclusion

What this experiment made me more sure of is that a Flutter widget tree and a model like Jev, which only makes choices, work well together. Adding an LLM to write text and to referee when Jev cannot decide covers accuracy, robustness, speed and cost at the same time. It does not make E2E tests faster than scripts, but it makes them handle UI changes better, and it does not report false successes.

The code is open source, including the thirteen-screen demo app, the runner with a persistent websocket, and the comparison scripts that produced the charts in this article (the main experiments are in runner/arms.py, together with a snapshot of the store after every run): https://github.com/chyiiiiiiiiiiii/flutter-jev

My next step is to connect Jev to the story picking of my daily digest, because it is exactly the kind of task that finishes in one call: one news item in, three judgments out, no loop and no waiting for other systems. Based on the numbers above, the cost of that part can drop by two orders of magnitude. I will share the results when I have them.

References

• flutter-jev (code for this article)
• TypeSafe: Introducing System One models and Jev
• Jev confidence docs
• TypeSafe Console (get an API key)
• OpenRouter: Jev
• marionette_mcp
• Abdallah Shaban’s GenUI demo

Your widget tree is already a list of options: where Jev fits in a Flutter project was originally published in Flutter Community on Medium, where people are continuing the conversation by highlighting and responding to this story.

One codebase, multiple platforms, and all using local LLMs — can this work without compromises? When thinking about integrating local LLM features into your app, you will also start thinking about performance soon. The answer to performance is often “build native”. It makes perfect sense considering with LLMs you’ll want GPU access and NPU acceleration. All that is platform-specific.
And yet, Flutter Gemma v1.x takes a modular approach to resolve this conflict. In this article we’ll show you exactly how this works using a real demo app for Android and iOS with six feature areas: setup, text generation, analysis, embeddings, RAG capabilities, and chat.

Why Cross-platform for on-device AI?

For classical business use cases, the argument for having one codebase is well-known: Write logic once and deploy on multiple platforms like iOS and Android. For features including local models, this becomes more important because model handling and prompting strategies come on top of classical UI frontend development. Things you really don’t want to maintain in more than one place.

The inference itself stays platform-specific. Native runtimes, GPU, and NPU access differ fundamentally between Android and iOS. Android relies on open acceleration APIs such as NNAPI and GPU delegates via LiteRT, used to run Gemini Nano on modern Android devices. Apple devices use Core ML and the Neural Engine to run the Foundation Model inside a closed, vendor-specific stack. A good cross-platform layer bridges this gap without hiding it. The developer is still in control of which engine runs on which platform. For real-time applications where performance is critical, native development remains the way to go. However, for most product features related to on-device local LLMs, Flutter is becoming an increasingly viable choice.

The Ecosystem: Cross-platform options for local LLMs

Before diving deep into Flutter Gemma, we will look at the solution space: Generic approaches rely on Dart FFI and bind directly to llama.cpp/ggml or custom platform channel bridges for each platform. For example, llamadart uses llama.cpp for GGUF models and LiteRT for .litertlm models. But there are also pure Dart approaches even without an ffi dependency like ollama_dart. In addition, there are other smaller Flutter packages with similar concepts at various stages of maturity and varying levels of maintenance and active development.

Outside of Flutter, it’s worth taking a look at the purely native solution LLM.swift for iOS. It is a platform-exclusive approach that clearly illustrates the native control you give up when you opt for cross-platform development but also how much platform-specific work you save yourself in the process.

The common thread among most approaches is that they solve the question “can the model run at all?” rather than “how do I build a product feature interface around it?” That’s exactly where Flutter Gemma comes in.

Why Flutter Gemma stands out

Since release v1.0.0 Flutter Gemma follows a modular architecture: a core package and optional engine packages, instead of one big monolithic dependency. Right now, developers can choose between the following:

• flutter_gemma_mediapipe: .task and .bin models (Android, iOS, Web)
• flutter_gemma_litertlm: .litertlm models (Android, iOS, Desktop)
• flutter_gemma_embeddings: text embeddings
• flutter_gemma_rag_sqlite: sqlite vector store enabling RAG capabilities

How to choose the correct model for Flutter Gemma?

Answering this question isn’t too easy and includes more pitfalls than you might think at first.

Format first

Flutter Gemma does not just load any GGUF or Safetensor file you give it to. It explicitly expects .task/ .bin files (MediaPipe) or .litertlm files (LiteRT-LM). Both formats are already converted and ready for the engine. Practically this means: You look for a fitting model on HuggingFace, e.g., the Gemma family from the Google community or some LiteRT-LM models from the LiteRT community, instead of converting a model yourself.

Quantization is no trivial matter

Most pre-converted models are quantized, very often as INT4 (sometimes as INT8). This drastically reduces download size and RAM requirements — exactly what makes on-device inference on a smartphone even possible in the first place. The trade-off is a certain loss of quality compared to full precision. For most everyday use cases, like rewriting, classification, and summarization, INT4 is a good compromise. If you think the output is becoming too imprecise, you should look for a higher-resolution variant of the same model, rather than simply choosing a larger model across the board.

RAM is the real limiting factor, not storage space: The download size provides only a rough estimate for the required RAM. During inference, the model requires additional RAM depending on the context length and backend (LiteRT-LM or MediaPipe), which can result in significantly larger memory usage than the file size. A model that runs smoothly on your own test device may already reach its limits on an older device or one with less RAM and crash the app when trying to load the model or run inference.

Additional Considerations for Selection

• Gated vs public
  Some models like Gemma3, Gemma4 or EmbeddingGemma require a license agreement and a HuggingFace API token, while Qwen3 or Gecko are freely available. This is relevant for user onboarding as well as CI/CD and not just for local development. We enjoy using Gemma models because they offer pretty good quality in the context of mobile on-device inference, but Qwen3 and Gecko are great alternatives that don’t require auth.
• Backend support
  Not every quantization level performs equally on GPU and CPU delegates. Some combinations only perform well on one of the two. This requires good testing with a variety of devices.
• Context length
  Smaller models often come with smaller maximum context windows. For long RAG contexts or detailed chat histories, this can quickly become a limiting factor. In our experience, this is the biggest drawback — but for all mobile local LLMs.

The Flutter Gemma Demo App

For this article, we built a small Flutter app that serves as a central theme. It uses flutter_gemma and all its submodules for model setup and inference as well as flutter_bloc for state management. We’re deliberately leaving out the navigation and similar peripheral topics. The app is divided into five tabs (Generation, Analysis, Embedding, RAG and Chat) and a setup screen. Each feature is built as its own Bloc + Widget pair with model access handled centrally using the FlutterGemma API.

The demo app uses Qwen3 0.6B for text inference and Gecko 256 for embeddings. Both models are publicly available and do not require a HuggingFace API token.

The central initialization runs once at app start and includes registering the engine.

Future<void> main() async {
  // ...
  await FlutterGemma.initialize(
    inferenceEngines: const [
      LiteRtLmEngine(), // .litertlm — Android, iOS, Desktop
      MediaPipeEngine(), // .task / .bin — Android, iOS, Web
    ],
    embeddingBackends: const [
      LiteRtEmbeddingBackend(),
    ],
    vectorStore: kIsWeb ? WebSqliteVectorStore() : SqliteVectorStore(),
    huggingFaceToken: dotenv.env['HUGGING_FACE_API_KEY'],
  );
}

Model Setup: Download, Installation, Availability

The entry point for the app is the Setup screen. First, it checks if there is any model installed without loading it.

/// [hasActiveModel] is a synchronous and cheap check
if (FlutterGemma.hasActiveModel()) { 
  emit(state.copyWith(status: SetupStatus.ready));
} else {
  emit(state.copyWith(status: SetupStatus.notInstalled));
}

If there is no model available, the app automatically initiates a download from HuggingFace with a progress bar visible in the UI.

await FlutterGemma.installModel(
      modelType: ModelType.qwen3,
      fileType: ModelFileType.litertlm,
    )
    .fromNetwork(
      ModelConstants.inferenceModelUrl,
    )
    .withProgress((progress) => add(_ProgressUpdated(progress)))
    .install();

Public models like Qwen3 or Gecko do not need API tokens. If your model requires a token, you can use a .env file in combination with the dotenv package to securely provide the API token. If the download fails, e.g., a network or storage problem occurs, the package throws a dedicated DownloadException instead of a generic Exception or Error:

try {
  await FlutterGemma.installModel(
    modelType: ModelType.qwen3,
    fileType: ModelFileType.litertlm,
  )
  .fromNetwork(
    ModelConstants.inferenceModelUrl,
    // dotenv.env['HUGGING_FACE_API_KEY'], // pass token here if required
  )
  .withProgress((progress) => add(_ProgressUpdated(progress)))
  .install();
} on DownloadException catch (e) {
  emit(
    state.copyWith(
      status: SetupStatus.error,
      errorMessage: e.error.toUserMessage(),
    ),
  );
}

In short: Setup is the only place where network or storage problems could realistically occur. The rest of the app can rely on the already installed models.

Feature: Text generation (Rewrite & Summarize)

The Generation Tab rewrites text in a specific mood or simply summarizes the text. The prompt gives the model clear instructions, including the instruction to preserve critical data like numbers or names.

enum AiMood {
  professional,
  casual,
  concise,
  analytical;

  String get label {
    return switch (this) {
      AiMood.professional => 'Professional',
      AiMood.casual => 'Casual',
      AiMood.concise => 'Concise',
      AiMood.analytical => 'Analytical',
    };
  }
}

final prompt = '''
You are a professional writing assistant. Rewrite the following text 
to sound highly ${event.mood.label.toLowerCase()}. Maintain all 
critical data facts, numbers, dates, names, and contact details 
exactly as written. Do not omit them.\n\n
Text to rewrite:\n${state.inputText};'''

The technical flow behind this is a pattern, that will be used in several places in the app:

1. Get the active model
2. Create a chat session
3. Get the response
4. Close the model

final model = await FlutterGemma.getActiveModel(
  maxTokens: ModelConstants.maxTokens,
);
try {
  final chat = await model.createChat();
  await chat.addQueryChunk(Message.text(text: prompt, isUser: true));
  final response = await chat.generateChatResponse();
  final text = response is TextResponse ? response.token : '';
  emit(state.copyWith(status: GenerationStatus.success, output: text));
} finally {
  await model.close();
}

This chat/session pattern of Flutter Gemma is perfectly fine and a good reusable pattern for every text feature, but not for classical chats, as we will see later in the chapter Feature: Chat with History. The quality of responses varies a lot between models used. For Qwen3 0.6B, the results for summarization and rewriting are quite good, although sometimes it just repeats the original text.

Feature: Structured Analysis (Classification and Entity Extraction)

The Analysis tab includes two scenarios: Classifying a support mail and extracting entities from log entries. The key to getting structured output here is prompting and telling the model (Qwen3) to generate plain JSON without Markdown or explanations.

const prompt = '''
Classify this content and respond with valid JSON only — 
no markdown, no explanation:\n
$_kScenario3Text\n\n
JSON format:\n
{"category":"...","priority":"...","labels":["...","..."]};'''

Even the bigger mobile local LLMs don’t always strictly follow these rules. That’s why post-processing matters even more. The code must be robust against format deviations. An easy fallback is returning the raw response.

String _formatClassification(String raw) {
  try {
    final json = jsonDecode(_extractJson(raw)) as Map<String, dynamic>;
    final category = json['category'] ?? '—';
    final priority = json['priority'] ?? '—';
    final labels = (json['labels'] as List?)?.join(', ') ?? '—';
    return '📋 CLASSIFICATION REPORT\n'
        'Category: $category\n'
        'Priority: $priority\n'
        'Tags: $labels';
  } catch (_) {
    return raw.trim();
  }
}

String _extractJson(String raw) {
  final start = raw.indexOf('{');
  final end = raw.lastIndexOf('}');
  if (start == -1 || end == -1) return raw;
  return raw.substring(start, end + 1);
}

While classification with Qwen3 0.6B seems to work reliably, entity extraction almost never succeeds in extracting all the information. In most cases it struggles to detect the “Impacted Users” (which is “14,000” in the example, but “0” got extracted). Repeating the entity extraction multiple times results in different outcomes for each execution.

Feature: Embeddings and Semantic Similarity

The Embedding tab uses its own model (Gecko 256), along with its own runtime ( flutter_gemma_embeddings), separate from the text generation model (Qwen3). Embeddings are a different class of models with their own workflow and use case: similarity and search rather than text generation. They need a completely different mental model consisting of vectors instead of words and similarity instead of responses. When choosing a model, there’s a classic trade-off. For example, Gecko 256 is small and publicly available, while EmbeddingGemma 512 is more accurate but gated.

The technical flow is rather simple:

1. Embed reference text
2. Embed user input
3. Calculate cosine similarity between the two vectors

final embedder = await FlutterGemma.getActiveEmbedder();
try {
  final inputVec = await embedder.generateEmbedding(
    state.similarityInput,
  );
  final score = _cosineSimilarity(state.referenceVector!, inputVec);
  emit(
    state.copyWith(
      status: EmbeddingStatus.referenceReady,
      similarityScore: score,
    ),
  );
} finally {
  await embedder.close();
}

Calculating the cosine similarity is pure Dart code and not part of the FlutterGemma API.

double _cosineSimilarity(List<double> a, List<double> b) {
  double dot = 0, magA = 0, magB = 0;
  for (var i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    magA += a[i] * a[i];
    magB += b[i] * b[i];
  }
  final denom = math.sqrt(magA) * math.sqrt(magB);
  return denom == 0 ? 0 : dot / denom;
}

In the demo app, we embedded a small text about planets. Comparing our two inputs, “Planets are big rocks in the universe” (A) and “Bees are very important insects because they are the global pollinators” (B), we can see that input A has a higher similarity score than input B because it is semantically closer to the topic in the embedded text. At least with English text, Gecko 256 enables reliable similarity matching on mobile devices.

Feature: RAG with SQLite-VEC and filters

The RAG tab comes with its own small knowledge base consisting of seven short documents on science, cooking, and history. The knowledge base is indexed and searchable fully on-device, without a server or an external vector store.

Notably, we don’t need to install a second embedding model to use Flutter Gemma RAG capabilities. Instead, we use the same active Gecko 256 embedder as the Embedding tab.

Storage is handled by flutter_gemma_rag_sqlite. A SQLite-VEC store is created directly in the app’s Documents directory, and indexing is performed via addDocument() using text and JSON metadata.

await FlutterGemma.rag.initialize('${dir.path}/$_kRagDbFileName');

for (final doc in _kCorpus) {
  await FlutterGemma.rag.addDocument(
    id: doc.id,
    content: doc.content,
    metadata: doc.metadataJson, // {"topic": "...", "year": ...}
  );
}

The real “out-of-the-box” experience is delivered by searchSimilar(). Embedding the user request and performing a cosine-similarity search run in one single call — no manual vector handling required like in the Embedding chapter.

final results = await FlutterGemma.rag.searchSimilar(
  query: state.searchQuery,
  topK: 5,
  filter: _buildFilter(),
);

New in Flutter Gemma v1.x are type-safe metadata filters FilterSchema and FilterField, declared once in FlutterGemma.initialize().

await FlutterGemma.initialize(
    inferenceEngines: const [
      LiteRtLmEngine(),
      MediaPipeEngine(),
    ],
    embeddingBackends: const [
      LiteRtEmbeddingBackend(),
    ],
    vectorStore: kIsWeb ? WebSqliteVectorStore() : SqliteVectorStore(),
    filterSchema: const FilterSchema(
      fields: [
        FilterField(name: 'topic', type: FilterFieldType.string),
        FilterField(name: 'year', type: FilterFieldType.number),
      ],
    ),
    huggingFaceToken: dotenv.env['HUGGING_FACE_API_KEY'],
  );

As a result, the filters for topic and year run as true vec0 column conditions directly in sqlite-vec, rather than post-filtering in Dart. Every column in a virtual table follows strict rules for typing, formatting, and structure requirements. This means robustness, better performance, and less development overhead. In the demo, topic chips and a “from 2020” filter combine to form exactly such a typed condition.

Filter? _buildFilter() {
  final must = <Condition>[];
  if (state.topicFilter != kAllTopics) {
    must.add(FieldEquals(key: 'topic', value: state.topicFilter));
  }
  if (state.recentOnly) {
    must.add(FieldRange(key: 'year', gte: 2020));
  }
  return must.isEmpty ? null : Filter(must: must);
}

Each match also provides a similarity score, which makes it easy to distinguish strong matches from weak ones. While the Embedding chapter shows the basic concept of similarity between two texts, the RAG tab shows a practical application as a searchable knowledge base.

In short, with sqlite-vec and typed filters, Flutter Gemma delivers RAG as a ready-made component rather than a patchwork of individual parts (or packages in Flutter terms).

To get a good mixture of knowledge in the demo app, we provided documents from different centuries about science, history, and cooking with rather complex information to really challenge the on-device LLM capabilities. Again, the Gecko 256 Embedder does a great job, and RAG features of Flutter Gemma seem to work like a charm. Asking, “How is sourdough bread made?

Feature: Chat with History

The Chat tab differs from the previous features in a crucial way: the Generation and Analysis tabs create a new chat session for each request, fetch a single response, and close the model again. For a real chat, this is insufficient because the model needs to remember the whole conversation. In Flutter Gemma this is not a special case but a matter of lifecycle management: InferenceChat maintains its own history internally if you reuse the same instance across multiple turns, rather than creating a new one for each message.

Future<void> _onStarted(ChatStarted event, Emitter<ChatState> emit) async {
  final model = await FlutterGemma.getActiveModel(
    maxTokens: ModelConstants.maxTokens,
  );
  final chat = await model.createChat(
    modelType: ModelType.qwen3, 
  );
}

The parameter modelType is not a minor detail here. For Qwen3 Flutter Gemma automatically appends /no_think to every user message to suppress the built-in thinking mode of the model. The <think> tags are also filtered from the response stream. Without this parameter, Qwen3 behaves significantly more unpredictably.

Every new message is passed to the chat instance via addQueryChunk(). The method generateChatResponseAsync() streams the response token by token. An emit.forEach loop is used to transfer those tokens into UI state.

Future<void> _onSubmitted(ChatMessageSubmitted event, Emitter<ChatState> emit,) async {
  await chat.addQueryChunk(Message.text(text: text, isUser: true));

  final buffer = StringBuffer();
  await emit.forEach<ModelResponse>(
    chat.generateChatResponseAsync(),
    onData: (response) {
      if (response is TextResponse) buffer.write(response.token);
      return state.copyWith(messages: _withStreamedReply(buffer.toString()));
    },
  );
}

History is being persisted in session memory as well as internally by InferenceChat from Flutter Gemma. Like this, the next call of generateChatResponseAsync() knows the whole conversation and not only the last message. This means we don’t have to glue something together or maintain the history ourselves.

Resetting a conversation with clearHistory() does not only clear the message list but also closes the native session and reopens it. Otherwise, the model would continue to respond based on a transcript that is no longer visible in the UI.

await chat.clearHistory();

During this chapter, we learned that multi-turn chat is not an extra feature of Flutter Gemma but rather a direct result of the InferenceChat lifecycle. Chat history is being persisted by keeping the chat instance alive and not because you rebuild it yourself.

Qwen3 0.6B has met exactly the expectations we had for an LLM running on smartphone hardware. The quality of the chat is “okay”, but not really much more than that. Qwen3 0.6B has a mediocre understanding of context: It can stick to a topic quite well, but most information is hallucinated entirely. Sometimes the model strays from the topic after one or two requests. In one case, the model responded with an empty text after three questions, and it did not respond to requests anymore. After clearing the chat, it worked again. Usually, we can write about 8–15 messages before the end of the context window is reached. What I’ve noted very positively is that mixing languages like English and German seems to work better than expected. The model can translate a sentence and correctly switch back to the original language of the conversation. The only problem that occurs when using a language other than English: there are garbled characters at the end of the messages. I don’t know why but it always happens as soon as I start chatting in German. Of course, you must take the model size into account here, and for just 0.6B parameters, it’s astonishing that it produces such a quality at all. Newer models like Gemma4, with more parameters and better quantization, are likely to perform even significantly better in this regard. However, such a comparison would go beyond the scope of this article.

Limitations, Pitfalls and Practical Lessons

On-device models have real storage and memory budgets. Download size and RAM requirements during inference on mobile devices are not an implementation detail — they are a hard limiting factor. Recurring patterns in the demo app: Models need to be closed (e.g., model.close() and embedder.close()) after finishing the task, or otherwise the resources will not be freed.

Despite a unified Dart API, platform differences persist under the hood. The engines of MediaPipe and LiteRT, as well as the systems iOS and Android themselves, do not always behave identically. There are cases where native approaches remain the better choice: Performance-critical scenarios or highly platform-specific hardware acceleration (as with LLM.swift mentioned earlier).

Conclusion

Cross-platform and local AI are not mutually exclusive. This article’s demo app demonstrates how the modular approach of Flutter Gemma resolves an apparent conflict of objectives. For teams that maintain a shared codebase for Android and iOS and don’t have extremely performance-critical real-time requirements, this is a very practical path to on-device LLM features.

Flutter Gemma really shines for small tasks and is a great way to implement local AI features for older smartphones that don’t have native support for Google’s Gemini Nano or Apple’s Foundation Model. Where native solutions continue to lead remains a matter of requirements.

This is evident across all five feature areas: Flutter Gemma doesn’t just answer the question, “Does the model even run?”. Instead, it provides the concepts needed for real product features, ranging from the download pipeline and typed RAG filters to the session lifecycle in chat. The actual work then lies in prompt engineering and product logic, not in the infrastructure.

The quality of the output from on-device smartphone LLMs remains a matter of debate. In our view, it’s already suitable for some use cases, but not so much for others. For example, summarizing and classifying shorter texts, as well as embedding texts, works surprisingly well with these small models. However, when working with complex, longer texts or performing entity extraction, there are still too many errors, so these tasks should continue to be handled by a powerful external model.

You can find the complete code in the our GitHub repository:

GitHub - EXXETA/flutter_local_llm: A small cross-platform mobile app to demonstrate on-device LLMs with Flutter Gemma. It features text generation, classification, entity extraction, RAG capabilities and a chat.

Feel free to try out the app right away with your own model!
(by Jonas Klock)

Flutter Gemma: The hidden gem of cross-platform local AI was originally published in Flutter Community on Medium, where people are continuing the conversation by highlighting and responding to this story.

Everything here runs. Clone it, run the tests, drag the sliders: github.com/rudrakshshukla/context_aware_transit

A bug report lands on a Tuesday. This is all it says:

“The Buy ticket button was gone. Pixel 8, around 8am. No screenshot, sorry.”

You open the app. The button is there. QA opens the app. The button is there. You check the crash logs, the feature flags, the release diff. Nothing.

The ticket sits in triage for eleven days. Then someone closes it: cannot reproduce.

But it was reproducible. Just not at your desk, at 3pm, sitting still, on office Wi-Fi. And that is the only context your tests have ever run in.

This is what Part 1 costs you. Once your UI is built from live context instead of a fixed layout, “does the screen look right?” has no answer. There is no screen. There are thousands of them, one for every combination of context, and your tests have seen about four.

The good news: other fields solved this long ago. Mobile just hasn’t caught up.

Three ways an adaptive UI breaks

Most teams treat these as one problem. They are three, and each needs a different test.

1. Wrong screen. The app read the context correctly, then picked the wrong layout. Someone running for a train gets a browse grid. This is a logic bug, and logic is cheap to test.

2. Flickering screen. The app picked correctly twice, three seconds apart, and the layout changed under the user’s thumb. Every single frame is correct. The bug only exists over time. This is almost certainly our Tuesday ticket.

3. Screen nobody sees. A layout that is correct, stable, and never happens. You build a feature that only appears in bright sunlight, while driving, above 90% battery. That is 0.3% of sessions. The feature is dead and nobody notices.

Widget tests catch the first one badly. They cannot see the other two at all.

First, make context a plain value

Everything else depends on this one move.

In Part 1, the context engine gave us a stream. Streams are fine in production and painful in tests, because you have to drive them. What you want instead is a plain value you can type out in one line.

class UiContext {
  const UiContext({
    required this.motion,
    required this.daypart,
    required this.lux,
    required this.batteryPct,
    required this.online,
    required this.quickActionConfidence,
  });
  // ... plus copyWith
}

Six fields. That is the whole input to your UI.

Add copyWith, and do not skip it. You will write hundreds of test contexts, and almost all of them are “the normal one, but walking” or “the normal one, but offline”. Without copyWith your test files get unreadable, and once they are unreadable people stop adding cases.

Now separate the decision from the drawing:

LayoutSpec decideLayout(UiContext c) {
  // Rule 0 — offline. Never show something that needs the network.
  if (!c.online) return const Discovery([kCachedTickets, kOfflineMap]);

  // Rule 1 — nearly dead battery. Show one thing only.
  if (c.batteryPct < kLowBatteryThreshold) {
    return const QuickAction(kBuyTicket, reason: 'low_battery');
  }

  // Rule 2 — the commuter from Part 1. Moving, and the model is sure.
  if (c.quickActionConfidence >= kQuickActionThreshold &&
      c.motion != Motion.still) {
    return const QuickAction(kBuyTicket, reason: 'commuter_intent');
  }

  // Rule 3 — otherwise, let them browse.
  return const Discovery([kRoutes, kPasses, kOffers]);
}

No widgets. No async. No plugins. No clock. This function runs about a hundred thousand times a second.

And there is not one if statement in home_screen.dart. All the branching lives here, where a test reaches it instantly.

One small thing that matters more than it looks: give LayoutSpec real value equality, and leave reason out of it. The reason is for your logs, not for the user. If two different rules both say “show the buy button”, the screen did not change. The stability test later counts changes the user can see, so including reason would make it fail on refactors nobody could notice. And if you skip equality altogether, every “did the layout change?” check returns false, every stability test passes without testing anything, and you ship the flicker bug with a green board.

Test the decision, not the pixels

final cases = <(String, UiContext, Matcher)>[
  ('sitting at home, just browsing',
      base, isA<Discovery>()),
  ('walking, model is confident — show one action',
      base.copyWith(motion: Motion.walking, quickActionConfidence: 0.9),
      isA<QuickAction>()),
  ('walking, model is unsure — let them browse',
      base.copyWith(motion: Motion.walking, quickActionConfidence: 0.5),
      isA<Discovery>()),
  ('very confident but standing still — still browse',
      base.copyWith(quickActionConfidence: 0.99), isA<Discovery>()),
  ('offline — never offer a purchase',
      base.copyWith(online: false, quickActionConfidence: 0.99),
      isA<Discovery>()),
  ('battery about to die — one action only',
      base.copyWith(batteryPct: 4), isA<QuickAction>()),
];

for (final (name, ctx, matcher) in cases) {
  test(name, () => expect(decideLayout(ctx), matcher, reason: '$ctx'));
}

This file is your product spec. Not a document somewhere. This file.

When a product manager says “push people to buy when they’re clearly in a rush”, that sentence becomes a row here before anyone touches a widget. Read the file top to bottom and a non-engineer should follow it.

Look at the fourth row. Very confident, but standing still. The model is more sure than in row two, and the app deliberately does less.

I did not think of that case when I wrote the rule. I found it ten seconds after dragging a slider in the Context Lab, which I will come back to.

Screenshots: test the edges, not every combination

Six context dimensions with a few useful values each gives you thousands of combinations. You cannot screenshot all of them, and you should not try. A golden file is only worth having if a human will actually look at it when it fails, and nobody reviews four thousand images.

So don’t cover the space. Cover its edges. For every rule, take the context just below its threshold and the context right at it. Then one normal example per branch.

These ten are exactly the ones that break when someone changes a number:

Two habits make this work.

Name the file after the context, not the screen. “walk_confidence_0.72_at.png” tells a reviewer what broke. “home_screen_2.png” tells them nothing, and they will approve the diff without looking.

Render through the same code production uses. If your test builds its own MaterialApp, your golden is testing that MaterialApp, not your app.

Load real fonts, or your tests are green and blind

This one cost me an afternoon, and it is the most fitting bug in the whole project.

When you run flutter test, Flutter uses a placeholder font. Every letter is drawn as a solid black rectangle.

My first ten screenshots had perfect layout, perfect spacing, and black bars where the words should be. Every test passed.

Think about that. A screenshot suite can be green and blind at the same time. That is the exact shape of the bug this article opens with.

Fixing it takes two steps, and only one is obvious:

• Icons are in the test bundle. Setting uses-material-design: true puts MaterialIcons there. Reading FontManifest.json loads them. This is what golden_toolkit does, and it works.
• Roboto is not. The default Material text style asks for a font that never ships inside your app. It lives in the Flutter SDK folder on your machine.

So the usual fix gives you perfect icons and black-box text. That is worse than no fix, because it looks like it worked.

In the repo, loadAppFonts() handles both. It finds the SDK by walking up from the running Dart executable, so nothing gets committed and nothing gets downloaded, and it behaves the same on your laptop and in CI. If it cannot find the fonts, it fails the test instead of quietly saving black boxes. A silent pass is the enemy here.

Properties: catching the cases you didn’t think of

Edge screenshots cover the contexts you imagined. Adaptive UIs break on the ones you didn’t. So write down the things that must be true everywhere, then throw thousands of random contexts at them.

test('invariants hold across 20000 random contexts', () {
  final r = Random(42);              // fixed seed: failures repeat
  for (var i = 0; i < 20000; i++) {
    final c = randomContext(r);
    final spec = decideLayout(c);

    // 1. Same input, same output. Always.
    expect(decideLayout(c), spec, reason: 'not deterministic at $c');

    // 2. Never show the user an empty screen.
    expect(spec.surfacedFeatureIds, isNotEmpty, reason: 'empty at $c');

    // 3. Offline means no purchase path. No exceptions.
    if (!c.online) {
      expect(spec.surfacedFeatureIds, isNot(contains(kBuyTicket)));
    }
  }
});

The first one looks pointless. It isn’t. The moment someone puts a DateTime.now() or a cached value inside the policy, this test goes red. And that is the worst bug you can have here: a UI you cannot reason about, because it is no longer a function of its inputs.

The third one is the one that pays off over years. Personalisation rules pile up over time. What eventually breaks is never the main path. It is some safety rule nobody realised everything depended on.

Make the stability budget a real test

Part 1 mentioned stability budgets as an idea. Turn it into a test that can fail.

The trick is a minimum waiting time. Once a layout is on screen, it stays for at least twenty seconds, whatever the model says:

LayoutSpec apply(LayoutSpec candidate, DateTime now) {
  if (_current == null) { _current = candidate; _changedAt = now; return candidate; }
  if (candidate == _current) return _current!;
  if (now.difference(_changedAt!) < dwell) { _suppressed++; return _current!; }
  _current = candidate; _changedAt = now;
  return candidate;
}

Then test it over time, not in one frame. Replay sixty seconds of realistic sensor noise sitting right on the threshold:

60s of sensor noise at the policy threshold
  without governor: 28 layout changes
  with governor:    2 layout changes (28 suppressed, budget 3)

Twenty-eight rearrangements in one minute. That is what “the button was gone” feels like from the other side of the glass.

This is the only test in the suite that can see problem number two, because it is the only one that looks at time.

Two more things I learned writing it.

Be honest about which assertions really test something. “At most 3 changes per minute” with a 20-second wait is guaranteed by the maths. No random seed can ever break it. Running that across 25 seeds looks rigorous and proves nothing. The assertion with teeth is the one next to it: two changes the user can see are never closer together than the waiting time, in any trace.

Test the opposite failure too. Almost nobody does. If you tune the waiting time too high, your app stops adapting at all, and you are back to a static screen. There is a test for that.

Reachability: the number nobody measures

Code coverage tells you a widget was built. It does not tell you a real person ever saw it.

You can measure this privately, because a context is six numbers, not personal content. Collect them on device, send aggregates, and check what your users actually reach:

reachability over 50000 contexts
  buy_ticket        16.09%
  routes            78.91%
  passes            78.91%
  offers            78.91%
  cached_tickets     5.00%
  offline_map        5.00%

Put that table in any pull request that changes a threshold. It shows the real effect of a one-character diff.

It also answers a question product teams actually care about: what share of real sessions can reach this feature? That beats “is it on the home screen?”.

One more test in that file deliberately hides a feature deep in the rules, then checks that the detector catches it. A passing test is only worth trusting if you have proved it can fail.

The parts that aren’t code

Designers review the rules, not the mockups. Give a designer one Figma frame and you get approval for one context. Give them the rule table plus the edge screenshots and you get approval for the whole system. They pick this up quickly. They have been doing responsive breakpoints for fifteen years, and this is the same idea with more inputs.

Better still, give them the real thing. Running the repo opens a Context Lab: a phone on one side, six sliders on the other. Drag the confidence slider past 0.72 and the interface turns into a different interface in your hand.

It is not a toy. It is where I found the “confident but standing still” case. Someone holding the Lab explores far more of the context space than someone reading a spec.

Log the context with every event. If you record buy_ticket_tapped without the context that produced that layout, you have thrown away the thing that explains it. Log the confidence, the layout you chose, and whether the governor blocked a change. Those three fields turn “conversion dropped 4%, not sure why” into something you can debug.

What actually changes

None of this is new thinking. It is the move compilers made decades ago: stop checking the output, start checking the function that produces it, then prove some things are true for every possible input.

What is new is that mobile teams now need it too.

The fixed screen was never only a design choice. It was the thing that made testing possible. Give it up and you have to replace it with something: a pure decision function, a set of edge screenshots, a few invariants, a test that understands time, and a reachability number.

Do that, and “cannot reproduce” stops being a category of bug. The context that caused it is six numbers. Six numbers fit in a test.

The code: github.com/rudrakshshukla/context_aware_transit — a runnable Flutter app and all 29 tests, with no dependencies beyond Flutter itself. On a fresh clone, flutter test works straight away.

Part 1: The Death of the Static UI

Your Adaptive UI Has No Screenshot was originally published in Flutter Community on Medium, where people are continuing the conversation by highlighting and responding to this story.

Every app you’ve ever shipped made the same quiet assumption: the interface is a fixed thing. You design a screen, you lay out the widgets, and every user sees the same arrangement in the same order — a 22-year-old on a commuter train at 8am and a 60-year-old at home on a Sunday get pixel-identical layouts. For thirty years that was simply what a UI was.

That assumption is dying. In 2026 the leading mobile apps treat the interface as a live surface that reshapes itself in real time — reordering navigation, resizing touch targets, shifting color and density, surfacing the one action you’re most likely to want next — driven by on-device signals about who you are, where you are, and what you’re doing right now. The static screen is becoming the exception, not the default.

Here’s what’s actually driving it, what it takes to build, and what it looks like in code — with Flutter examples throughout.

From static layout to living surface

The old personalization playbook was recommendation, not adaptation. Netflix reordered a content row; Spotify built you a playlist. The chrome around those recommendations — the navigation, the layout, the visual system — stayed frozen. Context-aware UX pushes personalization down into the interface itself.

Concretely, an adaptive UI reacts to signals like these:

• Motion and activity — accelerometer and gyroscope tell you the user is walking, driving, or still. A UI can enlarge touch targets and simplify layout when it detects movement, cutting mis-taps.
• Location and environment — outdoors in bright light, boost contrast and switch to a high-legibility mode; on a known Wi-Fi network at home, load richer media.
• Time and calendar — automatic dark mode at night, a leaving-for-a-meeting layout when the next calendar event is 15 minutes out.
• Usage history — promote the three features this user actually touches, demote the ones they never open. A finance app foregrounds transfer for a power user and check balance for a casual one.
• Device and network state — drop to a minimalist, low-power layout on a dying battery or a weak connection.

The through-line is if/then UX logic: the interface has conditional branches, and an on-device model decides which branch to render.

What it looks like in the wild

These aren’t hypotheticals. A few patterns already shipping:

Spotify reshapes its home surface by daypart and activity — a running-friendly, low-interaction layout with big targets and workout playlists surfaces in the morning, while an evening browse session gets denser, discovery-heavy shelves. The context (time, motion, listening history) reorders the screen, not just the recommendations inside it.

Starbucks drives its app home screen with a real-time decision engine that factors in time of day, weather, store location, and past orders — a cold-brew card on a hot afternoon near a store you frequent, a reorder-your-usual button when you’re on your commute route. The same app renders materially different first screens to different users in different moments.

Banking apps increasingly reorder the dashboard by learned behavior: a user who checks balances and nothing else gets balance-first, while someone who transfers money weekly gets transfer promoted to the top action. Same binary, two different information architectures.

Fitness apps modify the dashboard layout based on workout frequency and current activity state — surfacing start-workout and simplifying the interface when the accelerometer says you’re moving, then switching to progress charts and history when you’re stationary.

The unifying idea: the interface is a function of context, computed fresh, on the device.

Why Flutter is a natural fit

Flutter’s core model is UI = f(state) — widgets rebuild whenever the state they depend on changes. Context-aware UX is just that idea with the state coming from sensors and a model instead of only user taps. You don't need a new paradigm; you point your existing reactive plumbing (StreamBuilder, ValueListenableBuilder, Riverpod, Bloc — pick your poison) at a stream of context and let the widget tree recompute. And because a single Flutter codebase renders on both platforms, one adaptation layer covers Android and iOS at once.

The platforms underneath are pushing the same direction. Android’s Material You 3.0 (with Android 16) extracts 20+ semantic color roles on-device — Flutter taps that dynamic palette through the dynamic_color package, so your theme can follow the system's context-derived colors rather than a hardcoded scheme.

Here’s dynamic, context-driven theming in Flutter — the ThemeData itself becomes a function of context:

class AdaptiveApp extends StatelessWidget {
  final UiContext ctx;
  const AdaptiveApp({super.key, required this.ctx});

  @override
  Widget build(BuildContext context) {
    // dynamic_color surfaces Material You palettes from the OS
    return DynamicColorBuilder(
      builder: (ColorScheme? lightDynamic, ColorScheme? darkDynamic) {
        final useDark = ctx.isNight || ctx.batterySaver;

        var scheme = useDark
            ? (darkDynamic ??
                ColorScheme.fromSeed(
                    seedColor: Colors.teal, brightness: Brightness.dark))
            : (lightDynamic ?? ColorScheme.fromSeed(seedColor: Colors.teal));

        // Boost contrast outdoors / bright light
        if (ctx.ambientLux > 10000) scheme = scheme.toHighContrast();

        return MaterialApp(
          theme: ThemeData(
            colorScheme: scheme,
            // Larger, more legible type when the user is moving
            textTheme: ctx.isMoving ? largeTextTheme : defaultTextTheme,
          ),
          home: HomeScreen(engine: context.read<ContextEngine>()),
        );
      },
    );
  }
}

The engine: on-device ML

Context-aware UX only works because the inference runs locally. You cannot round-trip to a server to decide whether to enlarge a button while someone is walking — the latency kills it, and shipping motion, location, and camera data to the cloud is a privacy non-starter.

The Flutter on-device stack is mature. For the model layer you’ve got tflite_flutter (Dart bindings to TensorFlow Lite / LiteRT) and the google_mlkit_* packages for ready-made vision and language tasks; on iOS you can bridge to Core ML through a platform channel when you need it. For signals, sensors_plus gives you accelerometer/gyroscope, light reads ambient lux on Android, battery_plus covers power state, and geolocator handles location. The same three-stage pattern maps cleanly onto native Compose/SwiftUI too, if you ever go platform-specific.

A clean pipeline has three stages: a signal-collection layer that samples sensors, system state, and interaction history; an on-device inference layer that turns those raw signals into a prediction; and an adaptation layer that maps the prediction onto concrete UI state.

Stages one and two — collect signals, run a local model, expose the result as a stream the UI can react to:

enum Intent { quickAction, browse }

class UiContext {
  final bool isNight;
  final bool isMoving;
  final double ambientLux;
  final bool batterySaver;
  final Intent predictedIntent; // model output

  const UiContext({
    required this.isNight,
    required this.isMoving,
    required this.ambientLux,
    required this.batterySaver,
    required this.predictedIntent,
  });

  factory UiContext.defaults() => const UiContext(
        isNight: false, isMoving: false, ambientLux: 300,
        batterySaver: false, predictedIntent: Intent.browse);
}

class ContextEngine {
  final SensorHub sensors;
  final Interpreter interpreter; // tflite_flutter

  ContextEngine(this.sensors, this.interpreter);

  // combineLatest4 comes from rxdart
  Stream<UiContext> get context => Rx.combineLatest4(
        sensors.activity,      // walking / still / driving
        sensors.ambientLight,
        sensors.batteryState,
        sensors.usageHistory,
        (Activity activity, double lux, BatteryState battery, Usage usage) {
          final features = featurize(activity, lux, battery, usage, DateTime.now());
          final intent = _runInference(features); // <1ms on-device
          return UiContext(
            isNight: _isNight(DateTime.now()),
            isMoving: activity != Activity.still,
            ambientLux: lux,
            batterySaver: battery.saverOn,
            predictedIntent: intent,
          );
        },
      );

  Intent _runInference(List<double> features) {
    final output = List.filled(Intent.values.length, 0.0)
        .reshape([1, Intent.values.length]);
    interpreter.run([features], output); // on-device, no network
    return Intent.values[_argmax(output[0] as List<double>)];
  }
}

Stage three — the widget tree is a pure function of that context. Because Flutter rebuilds on stream emissions, the screen literally rearranges itself when the prediction flips:

class HomeScreen extends StatelessWidget {
  final ContextEngine engine;
  const HomeScreen({super.key, required this.engine});

  @override
  Widget build(BuildContext context) {
    return StreamBuilder<UiContext>(
      stream: engine.context,
      initialData: UiContext.defaults(),
      builder: (context, snapshot) {
        final ctx = snapshot.data!;
        final actions = adaptiveActions(ctx.predictedIntent);

        if (ctx.predictedIntent == Intent.quickAction) {
          // Moving / in a hurry: one big primary action, minimal chrome
          return PrimaryActionCard(
            key: const Key('primaryActionCard'),
            action: actions.first,
            size: ctx.isMoving ? CardSize.large : CardSize.medium,
          );
        }
        // Browsing: richer, denser discovery layout
        return DiscoveryGrid(key: const Key('discoveryGrid'), actions: actions);
      },
    );
  }
}

Keep the model small and quantized, sample sensors at the lowest rate that still feels responsive, and gate expensive work on battery and thermal state — an adaptive UI that drains the phone defeats its own purpose. In Flutter, push the interpreter.run call onto a background isolate (via compute or a long-lived isolate) if your model is heavy enough to jank the frame.

A worked example: the commuter’s transit app

Put the pieces together with one concrete flow. A user opens your transit app at 8:12am on a weekday.

The signal layer reports: activity = walking, time = weekday morning, location = within 200m of their usual station, battery = 34%, usage history = buys a single-ride ticket most weekday mornings. The inference layer featurizes that and predicts Intent.quickAction with high confidence. The adaptation layer renders a stripped-down screen: a single large Buy morning ticket — Station A → Downtown button with a big touch target sized for a walking user, high-contrast colors because ambient light is high, and a dimmed, battery-aware theme. Live departure times sit right below; the trip planner, settings, and promotions collapse behind a menu.

Same user, same app, 7:40pm, sitting at home on Wi-Fi with the phone charging: activity = still, low ambient light, no imminent commute pattern. Now the model predicts Intent.browse, and the screen renders the full discovery layout — trip planner up front, weekend passes, service alerts, a denser dark-mode interface. Two completely different first screens from one code path, decided on-device in under a millisecond, with no user data leaving the phone.

Privacy is what makes it acceptable

The reason this is happening now rather than in 2020 is that the privacy story finally holds up. Users have made clear they’ll walk away from apps that feel invasive — surveys this year found a majority lose loyalty to brands that reduce them to statistics. An architecture that ships behavioral data to a server to personalize is exactly the thing they’re rejecting.

On-device inference flips that. The sensitive signals — location, motion, front-camera emotion cues, usage patterns — never leave the device; only the outcome (a rearranged layout) is visible. Where you do need to improve models across your user base, federated learning lets you train on-device and share only gradient updates, and differential privacy adds calibrated noise so no individual’s data can be reconstructed from those updates. That combination — local inference plus privacy-preserving training — is what lets you personalize deeply without building a surveillance liability. Treat it as a feature you can market, not a compliance checkbox.

The hard part: your UI is now non-deterministic

Here’s the challenge teams underestimate. The moment your interface adapts, you’ve given up the thing that made mobile QA tractable: a fixed set of screens. There is no single home screen to design-review or golden-file test anymore — there’s a distribution of home screens, one per context.

The practical fix is to make context an injectable input so you can pin it in tests. Notice that HomeScreen above takes its context from a stream — in a widget test you feed it a fabricated UiContext and assert the resulting layout:

testWidgets('moving commuter gets the quick action', (tester) async {
  const ctx = UiContext(
    isNight: false,
    isMoving: true,
    ambientLux: 12000,
    batterySaver: true,
    predictedIntent: Intent.quickAction,
  );

  await tester.pumpWidget(
    MaterialApp(home: HomeScreen(engine: FakeEngine(ctx))),
  );
  await tester.pump(); // let the stream emit

  expect(find.byKey(const Key('primaryActionCard')), findsOneWidget);
  expect(find.byKey(const Key('discoveryGrid')), findsNothing);
});

That reframes the rest of the discipline too. Design review shifts from approving a comp to approving rules and bounds — designers specify how far the UI is allowed to move, not one frozen state. Accessibility can actually improve here — real-time touch-target enlargement and automatic WCAG-compliant contrast are natural fits for adaptive systems — but only if you make it an explicit adaptation rule rather than hoping it falls out.

And you have to respect a stability budget. A UI that rearranges itself too often is disorienting; users build spatial memory, and moving the button they reach for by reflex is a bug, not a feature. Adapt at sensible boundaries — app launch, a clear context change — not continuously. Over-personalization also risks echo chambers and the creepy-manipulation feeling that erodes trust, so give users a visible, easy way to see and reset how the app has adapted to them.

Why it’s worth the complexity

The pull is commercial, and the numbers vendors and analysts cite are large: personalized calls-to-action outperform generic ones by around 200%, extensive personalization has been linked to triple-digit lifts in revenue per user, and a majority of business leaders report higher retention from it. Treat the specific figures as directional — they come from marketing research, not controlled trials — but the direction is consistent and it’s why every major platform is now shipping the primitives.

The static screen was always a compromise: one layout that had to be acceptable for everyone and optimal for no one. On-device ML removes the reason for that compromise. The interface can finally meet each user in their actual moment — walking or sitting, morning or midnight, power user or newcomer — without asking them to configure anything or surrendering their data to do it.

The screen that never changes is starting to look like the thing that dates your app. In 2026, the interface is a conversation with context — and the apps that learn to hold that conversation are the ones users stay in.

Part 2 is now up: Your Adaptive UI Has No Screenshot — once the interface is built from live context instead of a fixed layout, “does the screen look right?” stops having an answer. Part 2 is about the three ways an adaptive UI breaks, and the tests that catch each one.

Both articles now have runnable code: github.com/rudrakshshukla/context_aware_transit — a working Flutter app with the context engine from this article, plus the full test suite from Part 2. No dependencies beyond Flutter itself: clone it and flutter test works straight away.

Sources: TechSling (AI-driven adaptive UI on Android); ParallelHQ (AI personalization in UX); Techqware (Material You 3.0 / Android 16); IEEE and NSF research (privacy-preserving personalized federated learning with differential privacy); Innowise (mobile app development trends 2026). Flutter code samples are illustrative and simplified.

The Death of the Static UI: Building Context-Aware Mobile Apps in 2026 was originally published in Flutter Community on Medium, where people are continuing the conversation by highlighting and responding to this story.

Every few months, like clockwork, the tech blogosphere gets flooded with the same recycled headline: “Is Flutter Dying?”, “Why CTOs Are Quietly Leaving Flutter”, or “Why Google is Killing Its Cross-Platform Bet.”

As someone who has been a Flutter Google Developer Expert for eight years now — literally from day one of the GDE program — and a five-decade software industry veteran, I usually just chuckle at the clickbait.

“Flutter is dead.” — Said every six months since 2018.
Meanwhile: Flutter is kicking tail on every single measurable scale.

The alarmist articles point to standard corporate reorganizations, shifting tech job boards, and “state management fatigue” as evidence of Flutter’s demise. But having watched this ecosystem evolve from an experimental alpha into an enterprise powerhouse, the reality on the ground is the exact opposite.

Here is the real insider story on what’s actually happening with Dart and Flutter.

1. The Inside Story: What Happened at Google?

When tech companies restructured engineering teams recently, the internet spun a wild narrative that “Google put Flutter on life support.”

Having direct access to internal teams, I watched the commitment to Dart and Flutter remain steadfast within the organization. However, there was a temporary disconnect: internal engineering activity was roaring, but external communications and public advocacy had slowed down, leaving an information vacuum that clickbait writers eagerly filled.

I personally called out to team leaders and senior VPs that this perception gap needed immediate correction.

And the leadership responded strongly:

• Revitalized DevRel & Advocacy: A renewed surge in active community engagement, tutorials, and public roadmaps.
• Enterprise Adoption Transparency: Showcasing massive internal and external production milestones.
• Aggressive Core Investment: Deep work on the Impeller rendering engine, Dart 3.x ergonomics, WebAssembly (Wasm) compilation, and native multiplatform performance.

Flutter is not a side project at Google; it powers critical business apps across Google (Google Ads, Google Pay, Family Link, Google Classroom) and continues to see deep infrastructure investment.

2. The “Hiring Paradox”: Why Flutter Job Postings Look Different

Critics often point to public job boards and claim, “Look, there are fewer Flutter job postings than native Android or iOS!”

What they fail to realize is how enterprises actually adopt Flutter:

When an enterprise migrates to Flutter, they rarely post 10 new external job listings. Instead, they merge their existing 5-person iOS team and 5-person Android team into a single, unified Flutter team — often cutting total hiring demand in half while doubling feature velocity.

Flutter’s sheer efficiency is what creates the illusion of fewer job listings.

And when greenfield Flutter positions do open up, junior applicants aren’t competing in a vacuum — they are competing against senior mobile engineers with a decade of native iOS and Android experience who upskilled into Flutter. That’s not a sign of a dying framework; that’s a sign of a mature, competitive engineering discipline.

3. “State Management Fatigue” Is a Solved Problem

Another frequent complaint is that Flutter has “too many state management libraries.”

Yes, Flutter gave developers freedom. And over the years, the community experimented with everything from ScopedModel and Provider to BLoC, MobX, and Riverpod.

2018 (Streams & Microtasks): Heavyweight stream controllers and async microtask queues.
2020 (Provider & Codegen): Context lookups, code generation, and complex lifecycles.
2026 (Signals & Modern BLoC): Fine-grained reactivity, 0ms synchronous updates, and zero boilerplate.

That evolution isn’t a sign of fragmentation — it’s the natural progress of modern software engineering. We learned what worked (unidirectional data flow, state machines, fine-grained reactivity) and discarded what didn’t (excessive code generation, microtask queue latency, and lingering build dependencies).

Today, with modern solutions like pure Dart Signals and frameworks like BlocSignal, state management in Flutter is faster, more synchronous, and more reliable than it has ever been.

4. The Measurable Reality: Flutter is Kicking Tail

If you want to know whether a framework is healthy, look at the cold, hard data:

• Play Store / App Store Presence: Over 1,000,000+ Flutter apps published and growing rapidly.
• Rendering Engine: Impeller delivers flawless 60/120fps GPU pipelines, eliminating shader jank once and for all.
• Web Performance: Wasm compilation brings near-native performance to the browser.
• Universal Reach: Seamless execution across iOS, Android, macOS, Windows, Linux, Embedded, and Web (via Jaspr).
• Language Evolution: Modern Dart 3.x delivers sealed classes, pattern matching, records, and primary constructors.

The Bottom Line

Every successful technology goes through the classic hype curve:

1. The Novelty Phase (Everything is magic!)
2. The “Trough of Disillusionment” (Clickbait writers declare it dead when the initial hype normalizes)
3. The Plateau of Productivity (Enterprises quietly build profitable, massive-scale products with it every day)

Flutter is firmly in the Plateau of Productivity. It is mature, stable, blazingly fast, and supported by one of the most vibrant developer communities in software history.

So the next time you see a headline asking “Is Flutter Dying?”… smile, close the tab, and go build something great. 🚀

Randal L. Schwartz is a Google Developer Expert (GDE) in Dart and Flutter, author of numerous classic programming books, five-decade software industry veteran, and Project Lead for the BlocSignal ecosystem.

I’ve Been a Flutter GDE for 8 Years. Here’s the Ground Truth on “Flutter is Dying” was originally published in Flutter Community on Medium, where people are continuing the conversation by highlighting and responding to this story.

If you’ve been following my articles here on Medium over the years, thank you! I wanted to share a quick update on where I’m primarily publishing my new technical deep dives, architectural guides, and Flutter/Dart tutorials.

Going forward, my primary writing hub is DEV.to (@randalschwartz) and the official Google Developer Experts (GDE) organization on DEV.to.

DEV.to provides a vibrant developer community, native Dart syntax highlighting, and a built-in Series feature that links connected articles into structured, multi-part curricula.

🚀 The New Series: BlocSignal Architecture & Practice

Over the last month, my team and I launched BlocSignal — a production-grade state management framework for Dart and Flutter that bridges BLoC’s enterprise discipline with Signals’ 0ms synchronous reactivity.

We’ve published a comprehensive 14-part series on DEV.to covering everything from core state machine philosophy and Riverpod/Provider interop to dependency injection, OpenTelemetry tracing, and Jaspr web development.

Here is the complete roadmap of all 14 articles available to read right now on DEV.to:

🏛️ 1. Core Architecture & Philosophy

1. Introducing BlocSignal: Unidirectional Data Flow Meets Reactive Signals The origin story: bridging BLoC semantics with Rody Davis’s signals v7 primitives for 0ms microtask queue latency.
2. BLoC meets Signals: How to Pitch BlocSignal to Your Dev Leads How to navigate technical team reviews and explain the enterprise value of synchronous signal graphs.
3. How We Achieved Full BLoC API & Protocol Parity in BlocSignal 0.2.0 A deep dive into BlocProvider, BlocBuilder, BlocListener, BlocConsumer, and context.select parity.
4. Beyond ProviderNotFound: How BlocSignal Rethinks State Location and Synchronous Propagation Solving scope lookups and understanding why synchronous signal updates prevent frame tearing.
5. From Raw Signals to BlocSignal: Taming Reactivity for Enterprise Scale How encapsulating signals inside Cubit/Bloc containers stops global signal “spaghetti mutations” in multi-developer teams.

🔄 2. Ecosystem & Framework Interoperability

1. Switching Tracks in BlocSignal: The Universal State Switchyard for BLoC, Riverpod, and Provider Using bidirectional adapters to incrementally migrate or interop across BLoC, Riverpod, and Provider.
2. Solving Riverpod’s Family Provider Cache Dilemma with Signals & mapSignal How O(1) mapSignal keying handles lazy, parameterized caching without complex 3rd-party cache engines or background timers.
3. Seamless Flutter Hooks Integration with BlocSignal via signals_hooks Combining HookWidget lifecycle convenience (useSignal, useComputed) with CubitSignal business logic.
4. Beyond Flutter: Running BlocSignal State Machines in Pure Dart, Jaspr Web, and CLI Tools Demonstrating 100% business logic reuse across Jaspr web SSR/SSG apps, server backends, and Dart CLI tools.

📐 3. Patterns, Practices & Dependency Injection

1. Why ValueNotifier Fails at Scale: The Non-Composability Problem (and How Signals Fix It) Why ValueNotifier listener chains leak memory and how declarative computed() graphs solve composability.
2. The Six Flavors of Dependency Injection in Flutter Comparing InheritedWidget, Provider, GetIt, Riverpod, and BlocSignalProvider for clean dependency scoping.
3. Layered Architecture in Flutter with BlocSignal: Bringing BLoC Discipline and Signals Speed to CodeWithAndrea’s Pattern Applying BlocSignal to CodeWithAndrea’s classic 4-layer Flutter architecture (Data, Repository, Service, Presentation).
4. Porting 16 BLoC & Signal Benchmark Apps to BlocSignal: Elevating Flutter UX & DX Lessons learned from porting 16 production benchmark applications to measure end-to-end execution throughput.
5. Exploring Form Management Patterns in Flutter with BlocSignal Comparing primary vs. derived state, CubitSignal methods, and pure reducer BlocSignal pattern matching for complex forms.

📌 Follow Along on DEV.to & The Official Website

If you’d like to stay up to date with new articles as they are published:

• Follow me on DEV.to: dev.to/randalschwartz
• Bookmark the Series Hub: BlocSignal Architecture & Practice Series
• Explore Live Demos & Docs: blocsignal.dev

Thank you again for reading, commenting, and following my journey here on Medium. I look forward to seeing you over on DEV.to!

Where I’m Writing Now: The Complete 14-Part BlocSignal Series on DEV.to was originally published in Flutter Community on Medium, where people are continuing the conversation by highlighting and responding to this story.

Are there any use cases for Generative UI other than chat responses? Can you share some inspiration?

Seth Ladd answered, “Let’s see what is beyond chat together.” 🚀

Since that moment, exploring GenUI beyond chat has been my primary focus.

I shared my first journey with GenUI in an article series: a small GenUI framework built with Gemini structured outputs, and a migration to Flutter GenUI SDK and A2UI surfaces.

Then I tried a different kind of use case: a Finnish 🇫🇮 grammar course inside my Finnish it language-learning app.

In this feature, the learner browses a curriculum in their own language, opens one small grammar topic, and moves through a sequence of Flutter pages.

Problem Definition

I had four constraints:

1. I do not speak Finnish, and I am not a language teacher.
2. I don’t have time to manually plan and structure a grammar book’s
   worth of micro-lessons in every language.
3. I want interactive application UI, not a long Markdown response.
4. Hyper-personalization is crucial. The explanation should begin from the learner’s language. A Turkish learner can approach Finnish vowel harmony through Turkish vowel harmony; an English learner needs another bridge since it has no similar concept.

The same rule does not feel equally foreign

That fourth constraint is more than UI localization.

Turkish speakers will find two familiar concepts in Finnish grammar: attaching grammatical markers directly to the ends of nouns, and changing suffix vowels to match the root word.

For example, expressing “in” or “at” requires the exact same mental process in both languages:

• Turkish: ev + -de = evde (in the house)
• Finnish: talo + -ssa = talossa (in the house)

An English speaker has a completely different starting point. English relies on separate prepositions (“in,” “from,” “to”) rather than suffixes for spatial relationships.

For a Turkish learner, the opening can activate an existing instinct: “You already attach location to a noun with endings such as `-de/-da`, and their vowels adapt to the word. Finnish asks you to make a related move with `-ssa/-ssä`, but the cases and usage rules are Finnish.” The explanation can then spend its time on the differences.

For an English learner, the opening cannot assume that instinct. It should first show that Finnish places part of the job done by “in,” “from,” or “to” inside the noun itself. A visual `talo + -ssa → talossa` breakdown establishes the mental model and the vowel harmony comes after that model is visible.

This is why directly translating a grammar textbook from one language to another rarely works. While the target language is the same, the learner’s starting line is different. What needs to be explicitly taught depends entirely on what already feels familiar.

This series has three parts:

• Part 1, this article: the curriculum, teaching system prompt, GenUI catalog, and localized curriculum.
• Part 2: generating lessons in surface batches and caching their A2UI output in Firestore for replay.
• Part 3: the Widgetbook integration used to develop and review individual catalog components and complete lessons.

If you are new to the GenUI, here is the one-paragraph refresher: with GenUI, the model does not write Flutter code. It streams A2UI messages — compact JSON that says “create a surface, put these components on it, with this data” — and every component must come from a catalog of widgets your app registered up front. A surface is a screen recipe; your widgets do the rendering, and the model becomes a composer rather than a painter.

Before starting, a strong recommendation is to read the last part of the previous GenUI article series where A2UI and Flutter GenUi SDK are explained in detail.

Designing the Teaching System

Separate what to teach from how to teach it

My first version of the problem was too broad:

Generate Finnish grammar lessons.

That instruction delegates nearly every important product decision to the model. Which topics belong in the course? What should an CEFR A1 learner study? Where does one lesson end and the next begin? Which examples, contrasts, and exceptions are required?

GenUI cannot answer those questions. It can constrain the model to registered widgets and turn its response into an interface, but it cannot determine whether a Finnish explanation is accurate or whether the teaching sequence makes sense.

I needed to separate three responsibilities:

• The curriculum defines what to teach.
• The system prompt defines how to teach it.
• The GenUI catalog defines how the teaching can be expressed as an interface.

The curriculum defines what to teach

I organized the curriculum around the CEFR levels and connected them to the YKI levels my learners prepare for. With Gemini’s help, I researched terminology, progression, and examples using references including Leila White’s A Grammar Book of Finnish and Iso suomen kielioppi.

The result is:

• 6 CEFR levels, from A1 to C2
• 30 chapters
• 150 grammar lessons
• 150 lesson-specific generation briefs
• 150 lesson-relation entries
• 44 broader grammar concepts

A lesson is the smallest teachable unit, not a textbook chapter. “The Vowel Harmony Rule and Exceptions” is one lesson. “Short versus Long Sounds” is another.

That granularity matters. Gemini receives one lesson and its authoritative brief — not the entire course. The brief states what the lesson must cover, what it must exclude, and where its editorial boundary ends.

The system prompt defines how to teach it

I am not a language teacher. The model performs the teaching, but I define the teaching contract.

That contract lives in my GrammarLessonPromptBuilder class. I keep it separate from the generation state machine because it is closer to an editorial document than an implementation detail. I should be able to review and rewrite the teaching philosophy without changing how pages are streamed, validated, or cached.

The prompt first defines the learner. These are adult immigrants and expats living in Finland, learning the Finnish they need at social services, at the doctor, at work, in a supermarket, or on public transport. Many are also preparing for the intermediate YKI test.

Even the tone is deliberate: warm and matter-of-fact, never condescending, and willing to acknowledge that a difficult point trips up almost everyone at first. Language anxiety is part of the product context.

The lesson then follows a teaching framework: Concept → Mechanism → Use → Application.

• Concept: What does this grammar point mean, and why does the learner need it? Where possible, the learner encounters it in a short sentence or dialogue before seeing the rule.
• Mechanism: How is it formed? The lesson demonstrates the stem, ending, consonant gradation, and vowel harmony, highlighting the exact change.
• Use: When should the learner choose it? If two forms compete — partitive versus total object, or -ssa versus -lla—the lesson contrasts them and provides a practical decision cue.
• Application: The learner immediately applies the rule through an interaction instead of only reading about it.

The interactions also have distinct jobs. QuickCheck tests recognition using plausible learner mistakes, not random distractors. ClozeSentence asks the learner to produce an inflected form in context. Flashcard supports recall of vocabulary, phrases, and irregular forms. Feedback explains both why the answer is correct and which misconception produced the wrong alternatives.

GenUI turns the teaching strategy into an interface

This is where GenUI becomes part of the pedagogy rather than merely a presentation layer.

The system prompt does not simply say, “Make the lesson interactive.” It maps teaching decisions to components. A stem transformation belongs in a visual breakdown. A choice between competing forms belongs in a decision tree or contrast panel. Recognition, production, and recall each have their own interaction.

The catalog supplies the model’s design vocabulary; the system prompt explains when each part of that vocabulary should be used.

The ending is constrained as well. The final surface contains a realistic mini-dialogue, three to five key takeaways, and an “Up Next” card whose recommendations are supplied by the app.

Together, the curriculum, prompt, and catalog govern the complete learning arc: decide what belongs in the lesson, establish its relevance, reveal the pattern, teach the choice, let the learner practise, and close with a real-life use.

This ordering makes the logic easier to follow because it moves from editorial scope → teaching method → generated interface.

Four JSON documents define the course

The editorial layer lives in four JSON documents:

curriculum.json             hierarchy: levels → chapters → lesson
curriculum_topics.json      lesson id → generation brief
curriculum_relations.json   lesson id → related lesson ids
curriculum_concepts.json    concept id → gloss + lesson ids

These documents have different jobs. Combining them on one JSON file would make localization, lesson generation, and cross-feature references harder and expensive.

Let’s follow one lesson through all four curriculum documents.

curriculum.json: hierarchy and learner-facing titles

Inside the A1 chapter “The Sound & Spelling of Finnish,” the lesson looks like this:

The title is used in the table of contents. The compactTitles let the same lesson appear as shorter discovery prompts in a horizontally sliding carousel without creating duplicate lessons.

The important field is id. vowel_harmony is not presentation text. It is protocol identity. It is preserved across languages and connects:

• the hierarchy;
• the localized title cache;
• the lesson generation brief;
• related-topic links;
• the concept taxonomy;
• the generated-lesson cache key.

curriculum_topics.json: one brief, one fence

The hierarchy says that the article exists. The brief says what the generated lesson covers and what it excludes.

For vowel_harmony, the stored value is a plain JSON string containig the following info:

Objective: Teach the Vowel Harmony rule for attaching suffixes.

Key Concepts: Words with back vowels (a, o, u) take back suffixes such as -ssa. Words with front vowels (ä, ö, y) take front suffixes such as -ssä. Words containing only neutral vowels (e, i) take front suffixes. In compounds, the ending is determined by the last word.

Examples to Include: talo → talossa, työ → työssä, tie → tiellä, kirjakauppa → kirjakaupassa.

Strict Constraints: Assume the learner knows the vowel groups. Do not teach consonant changes (k, p, t) or explain the meanings of the cases used.

The exclusions are as important as the objective. Without them, a model can give a useful but badly placed explanation. Vowel harmony lesson can drift into consonant gradation. A lesson about suffix choice can turn into a lesson about noun cases.

The curriculum is planned in 150 explicit fences each corresponds to a micro lesson.

The finished prose and surfaces can vary by learner’s native language. The lesson boundary does not.

curriculum_relations.json: deterministic next steps

The relation document stores curated lesson links. At the end of the each lesson we suggest the next lessons users can read. To do this suggestion the model does not need to know 150-lesson ids and their briefs just to suggest what comes next. The app already knows the allowed IDs and can resolve their localized titles.

curriculum_concepts.json: a taxonomy above individual lessons

The concept document groups lessons that explain different parts of a broader idea:

{
  "word_stems_gradation": {
    "gloss": "Consonant gradation (k/p/t: kk↔k, nt↔nn) and ...",
    "lessons": [
      "quantitative_gradation",
      "qualitative_gradation",
      "reverse_kpt",
      "link_vowel_vartalovokaali"
    ]
  }
}

This taxonomy is not another navigation tree. It lets other learning features to connect an observed problem to the lessons that address it. For example, after the learner finishes a speaking practice, and the model notices a broader problem at the feedback phase, it can suggest these set of grouped lessons.

What GenUI Controls — and What It Does Not

At this point, the curriculum has decided what to teach, and the system prompt has decided how to teach it. GenUI has a narrower but equally important responsibility: turning those decisions into an app-owned interface.

The model does not generate Dart code, Flutter widgets, or pixels. It selects components from a catalog registered by the application and emits A2UI messages describing how those components should be composed.

Flutter still owns the implementation. The application decides how each component is rendered, how it responds to different screen sizes, how it follows the theme, how accessibility works, and what happens when the learner interacts with it.

This creates a useful boundary:

The model chooses the teaching components and their content. The application decides what those components are and how they behave.

The catalog is both a design vocabulary and an input cost

My grammar catalog contains about forty components, from basic layout primitives to specialized widgets for inflection, pronunciation, grammatical contrasts, and practice.

The generated UI is only as good as the choices this catalog gives the model. Every component needs a specific purpose and a description that explains when it should and should not be used.

If two components solve the same problem, the model has to guess between them. That ambiguity produces inconsistent component selection and unpredictable layouts. It also has a direct token cost.

The catalog is not only a registry that exists inside Flutter. Its component names, descriptions, schemas, example data, and additional usage rules become part of the model’s input. Every catalog item makes that fixed input block larger, and the block is sent again on every provider turn.

Input tokens are usually cheaper than output tokens, but they are not free especially when the same catalog is repeatedly attached to a multi-turn generation flow. A component added for one rare lesson still contributes to the input cost of every lesson.

This creates two competing pressures.

• Clarity and orthogonality. Components should have distinct pedagogical responsibilities. A stem transformation, a comparison between competing forms, and a vocabulary-recall exercise represent different teaching operations and deserve different components. Orthogonality improves both model selection and token efficiency because the catalog does not spend tokens describing several ways to perform the same job.
• Variety versus token cost. More components give the model more ways to create visually engaging lessons, but each new schema increases the fixed input cost. The goal is therefore not to build the largest possible catalog. It is to build the smallest catalog that still gives the model the semantic vocabulary it needs.

A useful test is:

Does the model need to make this decision, or can Flutter make it more reliably?

Consider tabular data. A table works well on a large screen, while vertically stacked cards may be easier to read on a phone or when translated text becomes long. I could register DataTable and DataCards as separate choices and ask the model to select one. But that adds another decision, another schema, and more input tokens—even though the difference is primarily responsive presentation.

Instead, the catalog can expose one semantic data component. The model supplies the headings and rows; Flutter chooses whether to render them as a table or cards using the available width, text length, and accessibility settings.

The model decides what the data means. Flutter decides how that data fits the screen. This distinction lets me preserve catalog variety where it improves teaching while removing choices that the model should never have been asked to make.

This fixed catalog cost becomes important when a lesson requires several provider turns. In Part 2, I will show why I generate several surfaces per turn instead of paying that input cost once per page.

From catalog schema to Flutter widget: CaseCard

All of this is easier to understand through one concrete catalog item.

CaseCard introduces or recaps one Finnish grammatical case. It shows the case name, its everyday meaning, the question it answers, its endings, and an optional worked example.

The visible CaseCard is an ordinary Flutter design-system widget. It does not import GenUI, know about Gemini, or parse A2UI. Its GenUI contract lives in a separate CatalogItem adapter.

The adapter has four responsibilities:

• Give the component a stable name.
• Describe when the model should choose it.
• Define the data the model may provide.
• Convert that data into the ordinary Flutter widget.

final _schema = S.object(
  description:
      'A reference / identity card for ONE grammatical case: its name and '
      'everyday meaning as a title, the question word it answers and the case '
      'ending shown as chips, and one worked example (base word → inflected '
      'form with the ending highlighted). Pick this to introduce or recap a '
      'single case such as the Inessive, Adessive, or Illative. Use EndingRules '
      'when the rule branches on the word ending, or InflectionBreakdown for a '
      'staged build-up of one word.',
  properties: {
    'caseName': S.string(
      description:
          'The case name, e.g. "Inessiivi". Inline Markdown emphasis is '
          'supported.',
    ),
    'meaning': S.string(
      description:
          'The everyday meaning shown after the name, e.g. "inside something".'
          ' Inline Markdown emphasis is supported.',
    ),
    'question': S.string(
      description:
          'The question word the case answers, e.g. "Missä?". Inline Markdown '
          'emphasis is supported.',
    ),
    'ending': S.string(
      description:
          'The case ending(s), e.g. "-ssa / -ssä". Inline Markdown emphasis '
          'is supported.',
    ),
    'exampleLabel': S.string(
      description:
          'Optional label above the example, e.g. "Esimerkki (Example)". '
          'Inline Markdown emphasis is supported.',
    ),
    'exampleFrom': S.string(
      description:
          'The example base word, e.g. "Helsinki". Inline Markdown emphasis '
          'is supported.',
    ),
    'exampleTo': S.string(
      description:
          'The example inflected form; wrap the case ending in **bold** to '
          'highlight it, e.g. "Helsingi**ssä**".',
    ),
    'exampleFromGloss': S.string(
      description:
          'Optional gloss under the base word, e.g. "Helsinki". Inline '
          'Markdown emphasis is supported.',
    ),
    'exampleToGloss': S.string(
      description:
          'Optional gloss under the inflected form, e.g. "in Helsinki". '
          'Inline Markdown emphasis is supported.',
    ),
  },
  required: ['caseName'],
);


final caseCard = CatalogItem(
  name: 'CaseCard',
  dataSchema: _schema,
  exampleData: [_buildExample],
  widgetBuilder: (context) {
    final map = context.data as Map<String, Object?>;

    final exampleFrom = map['exampleFrom'] as String?;
    final exampleTo = map['exampleTo'] as String?;
    final hasExample =
        exampleFrom != null &&
        exampleFrom.isNotEmpty &&
        exampleTo != null &&
        exampleTo.isNotEmpty;

    return GenUiCatalogItemSection(
      child: CaseCard(
        caseName: (map['caseName'] as String?) ?? '',
        meaning: map['meaning'] as String?,
        question: map['question'] as String?,
        ending: map['ending'] as String?,
        example: hasExample
            ? CaseExample(
                label: map['exampleLabel'] as String?,
                from: exampleFrom,
                to: exampleTo,
                fromGloss: map['exampleFromGloss'] as String?,
                toGloss: map['exampleToGloss'] as String?,
              )
            : null,
      ),
    );
  },
);

The description establishes catalog item’s boundary for the model.

CaseCard is appropriate when the lesson needs an identity card for one grammatical case. It is not the right component when the rule branches according to a word ending or when the learner needs to see a transformation in several stages.

This is orthogonality in practice: the catalog does not merely tell the model what components exist; it explains which teaching operation belongs to each one.

When Gemini selects CaseCard, its A2UI output contains component data shaped like this:

{
  "id": "inessive_case",
  "component": {
    "CaseCard": {
      "caseName": "Inessiivi",
      "meaning": "inside something",
      "question": "Missä?",
      "ending": "-ssa / -ssä",
      "exampleLabel": "Example",
      "exampleFrom": "Helsinki",
      "exampleFromGloss": "Helsinki",
      "exampleTo": "Helsingi**ssä**",
      "exampleToGloss": "in Helsinki"
    }
  }
}

This component arrives as part of an A2UI updateComponents message. GenUI finds the registered item named CaseCard, checks the supplied data against its schema, and passes the data to widgetBuilder. The builder constructs the ordinary Flutter CaseCard, and the application handles the actual rendering.

The model never receives the Flutter layout implementation. It only sees the component’s purpose, schema, and example data.

That gives each layer one clear responsibility:

• System prompt → why the lesson needs this teaching operation
• Catalog description → when CaseCard should be selected
• JSON schema → which data CaseCard accepts
• A2UI message → the generated values for this instance
• Widget builder → how those values enter the Flutter widget
• Flutter widget → layout, theme, accessibility, and rendering

The curriculum itself needs localization

Before a learner generates anything, they need to browse the course.

The hierarchy contains learner-facing level, chapter, lesson, and compact titles. I treat each localized curriculum as a generated cache derived from one English source.

The Firestore layout for the curriculum is:

// Each curriculum is a localized document under grammar_curriculum collection
grammar_curriculum/en          canonical English curriculum
grammar_curriculum/tr          complete Turkish curriculum cache
grammar_curriculum/es          complete Spanish curriculum cache
grammar_curriculum/{language}  complete target-language cache

// Below collections do not need localization since they are not user-facing
grammar_curriculum/topics      lesson generation briefs
grammar_curriculum/relations   language-independent relation graph
grammar_curriculum/concepts    language-independent concept taxonomy

These are documents in one collection. The English document contains the canonical json. A target language document contains a complete localized json plus synchronization metadata.

The curriculum translation is not direct translation from English. It is done using LLM with the following prompt:

'''
# ROLE
You are an expert educational localizer for a Finnish grammar curriculum. Readers are adult learners of Finnish who study the grammar in Finnish but use the app in their own language.

# TASK
Localize the supplied English grammar curriculum labels into ${targetLanguageInstruction}. Every label is a short UI title on a lesson card, so keep each translation about as short as its source.

# RULES
1. Return exactly one output unit per input unit and copy each \`key\` unchanged.
2. Translate meaning, not words: use the grammar terminology a native speaker of the target language meets in language textbooks, and translate recurring terms (partitive, stem, suffix, case, verb type...) the same way in every unit.
3. Keep every piece of Finnish exactly as written — example words and sentences (lapsi ➔ lapse-, Minulla ei ole autoa), endings and suffix patterns (-ssa/-ssä, -ni, -si, -nsa), Finnish grammar names (Genetiivi, Vartalovokaali, Lauseenvastikkeet), and terms such as YKI, Kela, puhekieli, kirjakieli: the Finnish is what the learner is studying. Translate only the non-Finnish text around it, and keep symbols such as ➔, /, "...", and hyphens in place.
4. When English merely explains Finnish — usually a gloss in parentheses like "rahatta (without money)" — translate that explanation. When a label leans on English itself (for example the possessive "'s"), adapt the comparison so it makes sense to a reader of the target language.
5. Keep CEFR codes (A1, B2...) verbatim. Never leave English wording untranslated; only Finnish material, proper nouns, and codes pass through unchanged.
6. Keep the friendly, curious tone. Recreate wordplay and humor naturally in the target language instead of translating it literally; when a pun cannot carry over, write a natural label with the same meaning.
7. Translate \`compactTitles\` item by item: same count, same order. Output \`compactTitles\` only for units whose input has \`compactTitles\`; otherwise output only \`title\`.
8. Return only JSON matching the response schema.

# EXAMPLE
Input unit: {"key":"article:abessive_case","title":"Without (Abessive Case)","compactTitles":["rahatta (without money)","The -tta / -ttä ending","Abessiivi"]}
A correct output translates the title using the target language's name for the abessive case, keeps "rahatta" and translates only its parenthetical gloss, keeps "-tta / -ttä" while translating "The ... ending", and returns "Abessiivi" unchanged.

# INPUT
${JSON.stringify(units.map((unit) => ({ key: unit.key, ...unit.payload })))}
'''

Closing: the lesson now has boundaries

At this point, the system has the pieces required to generate a lesson:

• A stable lesson ID and a brief
• A CEFR level
• A learner explanation language
• A teaching contract
• A constrained catalog of Flutter components
• A localized curriculum through which the learner can find the lesson

The curriculum controls what belongs in the lesson. The system prompt controls how it should be taught. The catalog controls how that teaching can be expressed as an interface.

That creates deterministic boundaries around generation, but generation itself still costs time and tokens.

When the first Turkish learner opens vowel_harmony, Gemini can compose the lesson. When the next Turkish learner opens the same lesson, generating it again would repeat the same expensive work.

The output already contains everything Flutter needs to rebuild the lesson: the A2UI messages that describe its surfaces and components.

In Part 2, I will store that A2UI output in Firestore and feed it back through the same GenUI transport. On a miss, Gemini supplies the lesson recipe. On a hit, Firestore supplies it.

GenUI Beyond Chat: Designing a Grammar Book with Flutter GenUI — Part 1 was originally published in Flutter Community on Medium, where people are continuing the conversation by highlighting and responding to this story.

Recently, I’ve been working on migrating our app’s routing system. We previously used auto_route, but eventually realized its tightly coupled nature made it incredibly difficult to scale across independent modules. Furthermore, its heavy reliance on code generation became a bottleneck for our workflow.

To resolve this, we decided to architect a clean, scalable, and highly decoupled routing system. Our new solution is a powerful wrapper built on top of go_router. It abstracts away the raw string navigation and supercharges the router with custom features to maximize usability and type safety.

In this blog post, I will walk you through the core benefits of this new routing system, covering the following key topics:

• Unified Routing Protocol (AppRouteInfo)
• Strictly Typed Route Arguments
• Native & Path Parameters Support
• Cross-Module Modularization (AppModuleRouter)
• Hierarchical Back stack & Sub-Routes (Nested Route Definitions, Decoupled Cross-Module Navigation)
• Dynamic Presentation Modes (e.g., Native, ModalSheet, NoTransition)
• Guard Interceptor Mechanism (Type-Safe Redirects, Global Interceptors)

Note: This blog will show the general usage and problems it solved. For more detailed code, you can check the following link: https://github.com/thisisyusub/scalable-routing-system-demo

Architectural Structure of Routing System

Here is how the demo application is structured to achieve a fully decoupled, scalable routing system:

• scalable_routing_system_demo (main app): The entry point of the application responsible for wiring up all services, dependency injection, and global route configurations.
• app_routes: Houses all route definitions, parameters, routing protocols, and models to ensure fully type-safe navigation. This is decoupled from the core routing package to separate app-specific business needs from generic routing mechanics.
• routing_system (core router): A generic, domain-agnostic router package that has zero knowledge of the app’s specific routes. It exclusively provides the underlying routing configuration and composition mechanisms.
• home (shell route): Acts as the parent shell route wrapping the posts and settings modules as its children. Notably, it has no direct dependencies on them—a pattern achieved through architectural contracts and dependency injection.
• posts & settings (feature modules): Independent feature modules that manage their own internal views while exposing or exporting specific routes through shared contracts.

Initialization of the routing system (DI)

The routing system allows us to easily set up a project using simple class initialization. As you can see, it configures all routes based on a modular approach. We will explore modular route definitions in more detail shortly.

RouterConfig<Object> initRouterConfig() {
  final routerConfig = AppGoRouterConfig(
    initialLocation: AuthRoutesInfo.login,
    modules: [
      AuthModuleRouter(),
      HomeModuleRouter(
        postViewCompositionApi: getIt(),
        settingViewCompositionApi: getIt(),
      ),
      PostsModuleRouter(),
    ],
    guards: [],
    observers: [],
    debugLogDiagnostics: kDebugMode,
  );

  getIt.registerSingleton<AppRouterConfig>(routerConfig);

  getIt.registerSingleton<AppNavigationService>(
    GoRouterNavigationService(getIt<AppRouterConfig>().config),
  );

  return routerConfig.config;
}

Route Info Definition & Typed Safe Route Setup

First, we need to set up the route information for our modules. To achieve this, we use the app_routes module. For example, here is how the routes are defined for the auth module.

Under the hood, we rely on a protocol named AppRouteInfo, which establishes the standard guidelines for setting up route information.

final class AuthRoutesInfo extends AppRouteInfo {
  const AuthRoutesInfo._({required super.name, required super.path});

  static const login = AuthRoutesInfo._(name: 'login', path: '/login');
  static const register = AuthRoutesInfo._(name: 'register', path: '/register');
  static const forgotPassword = AuthRoutesInfo._(
    name: 'forgot-password',
    path: '/forgot-password',
  );
}

Next, we write helper functions to enable type-safe navigation. (Note that we aren’t using query or path parameters for these specific routes just yet, but the structure is ready for them.)

@internal
final class AuthRoutes {
  AppRouteRequest login() =>
      const AppRouteRequest(routeInfo: AuthRoutesInfo.login);
  AppRouteRequest register() =>
      const AppRouteRequest(routeInfo: AuthRoutesInfo.register);
  AppRouteRequest forgotPassword() =>
      const AppRouteRequest(routeInfo: AuthRoutesInfo.forgotPassword);
}

Finally, we group all these route functions together into a single class, like this:

abstract final class AppRoutes {
  static final auth = AuthRoutes();
  static final post = PostRoutes();
  static final setting = SettingRoutes();
}

How to setup ModuleRouter?

Each module defines its own routes by implementing the AppModuleRouter protocol. (Some modules might only be used as sub-routes inside other modules and don't need global registration, but we will look at that later.) Here is an example of the AuthModuleRouter:

final class AuthModuleRouter implements AppModuleRouter {
  @override
  List<AppModuleRoute> get routes => [
    AppPageRoute(
      routeInfo: AuthRoutesInfo.login,
      argsParser: RouteNoArgs.fromRaw,
      routeBuilder: (_, _) => const LoginView(),
    ),
    AppPageRoute(
      routeInfo: AuthRoutesInfo.register,
      presentationMode: const BottomSheetPresentationMode(),
      argsParser: RouteNoArgs.fromRaw,
      routeBuilder: (_, _) => const RegisterView(),
    ),
    AppPageRoute(
      routeInfo: AuthRoutesInfo.forgotPassword,
      presentationMode: const DialogPresentationMode(),
      argsParser: RouteNoArgs.fromRaw,
      routeBuilder: (_, _) => const ForgotPasswordView(),
    ),
  ];
}

• AppModuleRouter Protocol: Every feature module implements this protocol to declare its own routing table. This keeps routing decentralized — the core app doesn’t need to know how individual features are built internally; it just aggregates these routers
• AppPageRoute Configuration: Each entry maps a type-safe routeInfo to a specific widget builder (routeBuilder).
• Flexible Presentation Modes: Notice how modularity shines here. While the LoginView behaves as a standard full-screen page, the RegisterView is configured to open as a BottomSheet, and the ForgotPasswordView opens as a Dialog. The routing system handles these custom presentation transitions seamlessly out of the box.
• RouteNoArgs.fromRaw: Since these specific auth routes don't require path or query parameters yet, we use a zero-argument parser to keep things clean and strictly typed.

How can we navigate?

We have two options for handling navigation: using the BuildContext directly or utilizing the AppNavigationService.

Since we register the AppNavigationService during our application initialization process, any Cubit, BLoC, or other business logic component can take it as an abstract dependency. This allows for clean, framework-independent navigation right from your business layer.

For example, if we want to navigate to one of our Auth routes, we can use the following methods:

// using context
 context.goRoute(AppRoutes.auth.login());
 context.pushRoute(AppRoutes.auth.login());
 context.replaceRoute(AppRoutes.auth.login());

// using AppNavigationService (it is totally same)
final navService = getIt.get<AppNavigationService>();
navService.goRoute(AppRoutes.auth.login());
navService.pushRoute(AppRoutes.auth.login());
navService.replaceRoute(AppRoutes.auth.login());

Additionally, the system provides standard stack-management helpers such as canPopRoute, popRoute, maybePopRoute, and popUntilRoute to cover all your navigational flow requirements.

How some module can export its views for other modules to use as sub-routes?

For example, in our case, the home module needs pages from the posts and settings modules to use them as sub-routes (specifically, as its shell branches). As you can see, the home view displays both posts and settings as its inner views.

Directly exporting UI widgets from a feature module and importing them into the home module creates tightly coupled dependencies, which goes against our clean architecture goals. Instead, I solved this by introducing architectural contracts and composition protocols. Let me show you how this is implemented using the posts module as an example.

First, we create an interface (protocol) inside the app_routes module specifically for the posts feature. This allows us to define clean getter functions for each view or route that the posts module exposes for composition.

/// Defines the UI components the Posts feature exposes to be
/// embedded inside other feature layouts.
abstract interface class PostViewCompositionApi {
  /// The route to be used as a tab or nav rail item in the home navigation.
  AppModuleRoute get homeShellRoute;
}

Then, inside the posts module, we create the concrete implementation of this composition API and register it in our service locator so it can be consumed without direct coupling:

/// post_view_composition_impl.dart -> [posts] module
final class PostViewCompositionImpl implements PostViewCompositionApi {
  @override
  AppModuleRoute get homeShellRoute => AppPageRoute(
    routeInfo: PostRouteInfo.homePostsTab,
    argsParser: RouteNoArgs.fromRaw,
    routeBuilder: (context, args) => const PostsView(),
  );
}

/// post_route_info.dart -> [app_routes] module -> post folder
final class PostRouteInfo extends AppRouteInfo {
  const PostRouteInfo._({required super.name, required super.path});

  static const homePostsTab = PostRouteInfo._(
    name: 'home_posts_tab',
    path: '/home/posts',
  );

  /// will use it later for inner screen case
  static const postDetails = PostRouteInfo._(
    name: 'post_details',
    path: '/posts/:id',
  );
}

/// post_di.dart -> [post] module (we call it in the main app)
final class PostDI {
  static Future<void> init() async {
    GetIt.instance.registerFactory<PostViewCompositionApi>(
      () => PostViewCompositionImpl(),
    );
  }
}

Finally, we can consume this composition API inside our HomeModuleRouter to seamlessly define the posts and settings views as child shell routes, entirely decoupling the home module from the internal implementation details of those features:

final class HomeModuleRouter implements AppModuleRouter {
  const HomeModuleRouter({
    required this.postViewCompositionApi,
    required this.settingViewCompositionApi,
  });

  final PostViewCompositionApi postViewCompositionApi;
  final SettingViewCompositionApi settingViewCompositionApi;

  @override
  List<AppModuleRoute> get routes => [
    AppStatefulShellRoute(
      shellBuilder: (context, appStatefulShell, child) =>
          HomeView(appStatefulShell: appStatefulShell, child: child),
      branches: [
        AppStatefulShellBranch(routes: [postViewCompositionApi.homeShellRoute]),
        AppStatefulShellBranch(
          routes: [settingViewCompositionApi.homeShellRoute],
        ),
      ],
    ),
  ];
}

Once we define the helper functions for our post routes like this, we can invoke our navigation requests easily and in a fully type-safe manner:

@internal
final class PostRoutes {
  AppRouteRequest homePostTab() => const AppRouteRequest(routeInfo: PostRouteInfo.homePostsTab);
}

context.replaceRoute(AppRoutes.post.homePostTab());

How we can define query & path params and extras?

In our demo app, when a user clicks on a post item, it opens the post details screen by passing the unique post ID. To ensure type-safe parameter handling, we create a dedicated arguments class inside the app_routes module (under the posts directory):

final class PostDetailsArgs {
  const PostDetailsArgs({
    required this.id,
    // this.viewAsPublic = false,
    // this.extraInfo,
  });

  final String id;

  // final bool viewAsPublic;
  // final String? extraInfo;

  static PostDetailsArgs fromRaw(AppRouteArguments rawArgs) {
    return PostDetailsArgs(
      id: rawArgs.pathParameters['id'] ?? '',
      // viewAsPublic: rawArgs.queryParameters['view_as_public'] == 'true' ? true : false,
      // extraInfo: rawArgs.extra as String?,
    );
  }

  AppRouteRequest toRequest() => AppRouteRequest(
    routeInfo: PostRouteInfo.postDetails,
    pathParameters: {'id': id},
    // queryParameters: {'view_as_public': viewAsPublic ? 'true' : 'false'},
    // extra: extraInfo,
  );
}

While we only used path parameters in this example, this argument class pattern can easily be extended to support query parameters, extra data objects, or any other required types.

Next, within our PostsModuleRouter, we wire up the argument parser to map the raw route data directly to our PostDetailsArgs class:

final class PostsModuleRouter implements AppModuleRouter {
  @override
  List<AppModuleRoute> get routes => [
    AppPageRoute(
      routeInfo: PostRouteInfo.posts,
      argsParser: RouteNoArgs.fromRaw,
      routeBuilder: (context, args) => const PostsView(),
    ),
    AppPageRoute(
      routeInfo: PostRouteInfo.postDetails,
      argsParser: PostDetailsArgs.fromRaw,
      // it automatically casts args to PostDetailsArgs in [routerBuilder]
      // so we can safely use args.id (IDE gives its fields)
      routeBuilder: (context, args) => PostDetailsView(postId: args.id),
    ),
  ];
}

Once again, to achieve type-safe navigation, we rely on our helper functions:

/// post_routes.dart
@internal
final class PostRoutes {
  AppRouteRequest homePostTab() => const AppRouteRequest(routeInfo: PostRouteInfo.homePostsTab);
  AppRouteRequest postDetails({required String id}) => PostDetailsArgs(id: id).toRequest();
}

/// post_route_info.dart
static const postDetails = PostRouteInfo._(
  name: 'post_details',
  path: '/posts/:id',
);

Because it’s configured as an independent route rather than a child of the shell, it opens globally on top of the home screen (hiding the bottom navigation bar).

Finally, we can invoke it anywhere in our UI cleanly and safely:

context.pushRoute(AppRoutes.post.postDetails(id: post.id));

Role of AppRouteWrapper for Providers

When working with BLoCs, Cubits, or ChangeNotifier instances that depend on the widget tree, we often need to wrap our routes with their respective providers. However, doing this directly inside the router definition can quickly clutter the code and make it hard to maintain.

To solve this, I implemented an auto_route-style wrapping mechanism. For example, if we have a Cubit like this:

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

  void increase() => emit(state + 1);

  void decrease() => emit(state - 1);
}

We can provide it cleanly by having our view implement the AppRouteWrapper protocol:

class CounterView extends StatelessWidget implements AppRouteWrapper {
  const CounterView({super.key});

  @override
  Widget wrappedRoute(BuildContext context) {
    return BlocProvider(create: (_) => CounterCubit());
  }

  @override
  Widget build(BuildContext context) {
    return ...;
  }

With this approach, we completely avoid cluttering our router definition with provider boilerplate. The routing system detects the wrapper protocol and automatically injects the provider behind the scenes.

Wiring Custom Observer

To monitor navigation events, log route transitions, or integrate with analytics tools (like Firebase Analytics or Sentry), our routing system supports custom navigation observers.

Here is how you can implement a simple custom observer to track screen pushes, pops, and replacements:

import 'package:flutter/material.dart';

final class AppNavigationObserver extends NavigatorObserver {
  @override
  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) {
    super.didPush(route, previousRoute);
    debugPrint('🚀 Navigated TO: ${route.settings.name} (from: ${previousRoute?.settings.name})');
  }

  @override
  void didPop(Route route, Route? previousRoute) {
    super.didPop(route, previousRoute);
    debugPrint('🔙 Popped FROM: ${route.settings.name} (returned to: ${previousRoute?.settings.name})');
  }

  @override
  void didReplace({Route? newRoute, Route? oldRoute}) {
    super.didReplace(newRoute: newRoute, oldRoute: oldRoute);
    debugPrint('🔄 Replaced: ${oldRoute?.settings.name} WITH ${newRoute?.settings.name}');
  }
}

Once implemented, you can pass your custom observer directly into your router configuration during app initialization:

RouterConfig<Object> initRouterConfig() {
  final routerConfig = AppGoRouterConfig(
    initialLocation: AuthRoutesInfo.login,
    modules: [
      AuthModuleRouter(),
      HomeModuleRouter(
        postViewCompositionApi: getIt(), 
        settingViewCompositionApi: getIt(),
      ),
      PostsModuleRouter(),
    ],
    guards: [],
    observers: [AppNavigationObserver()], // here
    debugLogDiagnostics: kDebugMode,
  );

  getIt.registerSingleton<AppRouterConfig>(routerConfig);
  getIt.registerSingleton<AppNavigationService>(GoRouterNavigationService(getIt<AppRouterConfig>().config));
  return routerConfig.config;
}

Securing Routes with Navigation Guards

In any production-grade application, certain screens require authentication or specific permissions before access is granted. To handle this cleanly, our routing system supports Navigation Guards using a straightforward redirect-based protocol.

Here is how you implement an AppRouteGuard. The redirect method evaluates a condition and returns either null (allowing navigation to proceed) or an AppRouteRequest to redirect the user:

final class AuthGuard implements AppRouteGuard {
  AuthGuard({required AuthService authService}) : _authService = authService;

  final AuthService _authService;

  @override
  FutureOr<AppRouteRequest?> redirect(BuildContext context, AppRouteArguments args) async {
    // Check if the user is authenticated
    final isAuthenticated = await _authService.checkIsAuthenticated();
    
    // If not authenticated, redirect to login; otherwise, allow access (return null)
    if (!isAuthenticated) {
      return AppRoutes.auth.login();
    }
    
    return null;
  }
}

So, we can register it in the configuration file:

RouterConfig<Object> initRouterConfig() {
  final routerConfig = AppGoRouterConfig(
    initialLocation: AuthRoutesInfo.login,
    modules: [
      AuthModuleRouter(),
      HomeModuleRouter(postViewCompositionApi: getIt(), settingViewCompositionApi: getIt()),
      PostsModuleRouter(),
    ],
    guards: [AuthGuard(authService: getIt())], // here
    observers: [AppNavigationObserver()],
    debugLogDiagnostics: kDebugMode,
  );

  getIt.registerSingleton<AppRouterConfig>(routerConfig);

  getIt.registerSingleton<AppNavigationService>(GoRouterNavigationService(getIt<AppRouterConfig>().config));

  return routerConfig.config;
}

Conclusion

By moving away from monolithic route files and embracing a modular, type-safe architecture, you can tame even the most complex navigation requirements in Flutter. With decentralized module routers, clean composition APIs, automatic provider wrapping, global observers, navigation guards, and responsive presentation modes, your routing layer becomes robust, testable, and completely decoupled.

This setup not only keeps your codebase clean as your team and project scale, but it also delivers a seamless, adaptive experience across mobile, tablet, and desktop platforms. Happy coding!

GitHub - thisisyusub/scalable-routing-system-demo

Make scalable routing system for your Flutter Apps was originally published in Flutter Community on Medium, where people are continuing the conversation by highlighting and responding to this story.