DEV Community: Frank Milvus

Your Flutter desktop app won't start: one corrupt preferences file

Frank Milvus — Fri, 06 Nov 2026 23:24:37 +0000

The report was short: the desktop build opens and closes immediately. No window, no error dialog, nothing to click. On the terminal, the process printed a stack trace and quit before anything appeared on screen.

The cause was not a broken build, a missing library, or a failed update. It was one settings file with a missing bracket.

This post is about that failure and the fix: how a single corrupt JSON file can stop a Flutter desktop app before its first frame, why wrapping the read in try/catch does not save you, and how the app now repairs itself at launch without throwing away the evidence.

A launch that dies before it can report anything

The terminal showed this:

Unhandled Exception: FormatException: Unexpected character (at character 31943)
...notif_suppressed_136":1793799452696}"flutter.keystore_durability_expecte...

Look closely at the quoted fragment. There is a closing } after a timestamp, and then another key starts immediately: …2696}"flutter…. That is not a value the app wrote. It is two JSON objects glued together — the remains of an interrupted write.

The exception happened inside an awaited call in main(), before runApp(). An async main without a top-level catch lets that exception escape, and the Flutter engine never gets a route to render. From the user's side, the app silently refuses to start.

There is no error boundary for this class of bug. The crash reporting tool had not finished starting either, so there was no report to read. The only evidence was the terminal output and the file on disk.

Why one file decides whether the app starts

On mobile, shared_preferences is backed by platform-native storage. On Linux and Windows, the plugins are different: both keep the entire preferences store in a single file called shared_preferences.json in the app's support directory. On Linux that is:

~/.local/share/com.folcadi.app/shared_preferences.json

Every key the app saves lives in that one JSON object. The plugin does not read keys lazily; it decodes the whole file once, inside SharedPreferences.getInstance(), and hands you a map.

That design is fine for settings. It becomes a critical path when the first thing your app does is read a setting. Folcadi restores the user's appearance preferences before runApp() so the first frame is already in the right theme. That means launch order is:

Flutter bindings initialize.
The app asks for preferences.
The plugin reads and decodes the JSON file.
Only then does the app build its first widget.

If step 3 throws, steps 4 onward never happen.

This is also why the bug was invisible in development. A fresh profile has a valid file. Tests that mock preferences never see the real decoder. The failure needs a file that was damaged outside the app's control — a power loss, a forced shutdown, a full disk during a write, or a sync tool touching the profile directory. We cannot point to the exact event that damaged this one, and that is the point: the app must survive a damaged file regardless of how it happened.

Why `try/catch` around the read is too late

The obvious fix is to catch the exception where preferences are read:

try {
  final prefs = await SharedPreferences.getInstance();
  // ...
} catch (e) {
  // use defaults
}

That helps the call site you wrapped, and it is worth doing — the app now has exactly that guard around its startup restores. But it does not repair the store. Every other call to getInstance() in the app still hits the same file and throws the same error. A settings screen opened ten minutes later fails in a different place, with a different stack trace, and the app looks broken in a new way.

Worse, the failed read leaves the file untouched. The next launch repeats the failure. A one-time catch turns a hard crash into a permanent, scattered malfunction.

The real problem is that the file is untrusted input. Treat it that way: inspect it before the plugin ever opens it, and remove it from the plugin's path when it is unusable.

Validate before you initialize

The repair runs immediately after WidgetsFlutterBinding.ensureInitialized() and before any code touches SharedPreferences:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await repairCorruptSharedPreferences();

  // ...the rest of startup
}

The function has a simple contract. It returns true if a corrupt file was moved aside, and false if there was nothing to do — on web, on mobile, when the file is missing, or when the file is healthy.

Inside, the checks are deliberately narrow:

if (!await target.exists()) return false;

final raw = await target.readAsString();
if (raw.trim().isEmpty) return false;

try {
  final decoded = jsonDecode(raw);
  // The plugin expects a JSON object; anything else is not a usable store.
  if (decoded is Map) return false;
} on FormatException catch (e) {
  debugPrint('PrefsRepair: corrupt preferences file: $e');
}

Three details matter here.

Whitespace-only is not corruption. An empty file is what a fresh install or a cleared profile looks like. Renaming it would create noise and a pointless backup on every clean launch.

Valid JSON is not automatically valid preferences. A file containing [1, 2, 3] decodes without error but cannot be a preferences map. A type check catches that case, which a jsonDecode-only guard would miss.

The check is cheap. Reading one small file and decoding it once adds a few milliseconds to launch. It is negligible next to the network calls that used to run before the first frame, and it buys a guaranteed start.

Platform detection lives in the same function. It returns early unless the target platform is Linux or Windows, so mobile and web keep their native storage untouched:

if (kIsWeb) return false;
if (defaultTargetPlatform != TargetPlatform.linux &&
    defaultTargetPlatform != TargetPlatform.windows) {
  return false;
}

The file is injectable for tests, so the real plugin and the real app directory are not needed to prove the behavior.

Quarantine instead of delete

A corrupt store is unusable. Deleting it would let the app start, but it would also destroy the only artifact that explains what happened. So the repair renames the file:

final backup = File(
  '${target.path}.corrupt-${DateTime.now().millisecondsSinceEpoch}',
);

try {
  await target.rename(backup.path);
  return true;
} catch (e) {
  // Rename can fail across filesystems; startup must still win.
  try {
    await target.delete();
    return true;
  } catch (deleteError) {
    return false;
  }
}

The timestamped suffix means repeated failures do not overwrite each other. The original bytes stay on disk for inspection, and the plugin creates a fresh empty map on the next read.

The delete fallback is not defensive noise. Renames can fail for reasons unrelated to the file itself — a permission change, a directory that is on another mount, a locked path. The priority order is explicit: start the app first, preserve evidence second. A failed repair returns false, which is honest, but the startup guard below means even that does not keep the app down.

The second half: startup must degrade, not block

Repairing the file handles the known failure. The broader rule is that startup initialization is best-effort: a plugin failing should cost you a setting, not the whole app.

Four independent pieces of startup work run together in a Future.wait:

window chrome (desktop only, no-op elsewhere),
the saved appearance preferences,
crash reporting / Firebase initialization,
local notification setup.

All four are wrapped in a single try/catch:

try {
  await Future.wait<void>([
    WindowChrome.ensureInitialized(),
    restoreAppearancePrefs(),
    _initializeFirebase(),
    _initializeNotifications(),
  ]);
} catch (error, stack) {
  // A prefs/plugin failure must not prevent the app from starting:
  // the notifiers already hold their defaults.
  debugPrint('⚠️ Startup restore failed: $error\n$stack');
}

This is a deliberate trade-off. Future.wait fails fast: the first error propagates and the remaining futures keep running unobserved. The app starts with whatever defaults the notifiers already hold. A user might get the light theme instead of the dark one they chose, or miss one restored preference. They still get a working app, and the log names the failure.

The guard is not a substitute for the repair. If the file stays corrupt, every later preferences access still throws. The two layers solve different problems: one removes the bad input, the other guarantees the app does not hang on the splash screen while initialization fails.

Four tests that matter

The repair has four tests, all against real files in a temporary directory:

Case	Input	Expected
Malformed JSON	Two JSON objects concatenated	Renamed to `.corrupt-*`, contents preserved
Valid JSON, wrong shape	`[1, 2, 3]`	Quarantined
Healthy store	`{"flutter.theme_mode":"dark"}`	Untouched, no backup
Missing or blank	No file / whitespace only	Not treated as corruption

The first test uses the actual shape from the crash log. Not an abstract invalid string — the kind of damage the app really saw. That matters, because the test documents the supported failure, not just the code path.

The healthy-file case is just as important. A repair routine that quarantines valid preferences would reset user settings on every launch, and it would look like a much worse bug than the one it fixed.

What it costs the user

Honesty about the trade-off matters more than a clean story.

When the file is quarantined, settings reset to defaults: theme, notification preferences, keyboard options, quick-reaction emoji, and similar local state. The old values remain in the .corrupt-<epoch> backup, but the app does not attempt to salvage them. A partially decoded store is exactly the kind of guess that produces weird states.

The secure session store is untouched, so the keyring-backed login survives. But on desktops where the keyring never proved durable, a plaintext fallback token is kept in this same preferences file. That copy is lost with the file, so a user on such a machine may need to sign in again.

That is the trade: preferences are disposable, launch is not. A few lost settings beat an app that cannot open.

If it happens to you

If a Flutter desktop app dies at launch with a FormatException from shared_preferences, you can recover it manually without waiting for a patch:

Close the app.
Go to the app's support directory. On Linux, ~/.local/share/<app-id>/; on Windows, %APPDATA%\<app-id>\.
Rename shared_preferences.json to something else, or delete it.
Start the app again. It will come up with default settings.

Keep the renamed file if you want to diagnose what wrote the bad data. If the app starts and then fails somewhere else, the preferences file was not the cause — but a corrupt JSON file is one of the few startup failures with such a clean recovery.

What I took away

The bug was not in the preferences code. It was in the assumption that a file written by the app is always readable by the app.

Three rules came out of it:

Any file the app reads at startup is untrusted input. Validate the shape, not just the presence.
Repair at the boundary, not at every call site. One guard before the plugin initializes is simpler and more complete than a catch in every screen.
Preserve the failure. Rename instead of delete; a corrupt file is a bug report you cannot reproduce later.

The app still has plenty of startup work that can fail. The difference is that a failure now produces a running app with default settings and a log line, instead of a process that exits before the window appears.

FAQ

Does this affect mobile?

No. The repair returns early unless the platform is Linux or Windows. Android, iOS, macOS, and web use different storage backends and keep their existing behavior.

Why not switch to a different storage package?

The file format was not the problem; the missing validation was. Whatever storage package you pick, a file on disk can be truncated, replaced, or synced by something else. The fix belongs at the boundary, so it applies regardless of the backend.

Why keep the corrupt file instead of deleting it?

Because it is the only evidence. The backup is timestamped and costs a few kilobytes. If the corruption repeats, having the previous file is how you tell a one-off crash from a write pattern that keeps damaging the store.

Can the settings be recovered from the backup?

Not automatically. The app deliberately starts from defaults rather than trying to decode a damaged map. For a one-off failure, most users will not care. For a recurring one, the backup is diagnostic material, not a restore point.

If you build Flutter desktop apps, the cheap version of this lesson is: check the files your app reads before the first frame. A missing bracket should never be enough to keep a window closed.

Get Folcadi — a language-exchange messenger with live translation.

Official website: folcadi.com
Android: Google Play
Windows: .zip or installer
Linux: .deb or portable tarball
Articles: write-ups and covers
Telegram: @frank_says
Facebook: facebook.com/folcadi

Read chats in the language you study: on-device translation in Flutter

Frank Milvus — Wed, 04 Nov 2026 10:22:14 +0000

Translation is usually a one-way door: the app guesses your mother tongue and everything lands in it. Before Babel opens the other direction. You choose the language you want to read messages in — often the language you are learning — download a language pack, and every incoming message is rendered in it, in the bubble where the text always was.

Nothing else in the app moves. Same chat list, same bubbles, same replies. Only the text changes, converted on the phone, offline, with no server in the loop.

This is how the mode works, why it is built around language packs instead of a translation API, and the three bugs that only appeared once the pipeline ran on real conversations.

What "in place" means

Most translation features add something: a second bubble, a "translated" section under the message, a spinner, a language label. Every one of those is a reminder that you are reading a translation, and every one of them changes the rhythm of a chat.

Before Babel adds nothing. A bubble contains either the original text or the translated text, in the same place, with the same layout. Someone who did not know the mode existed would not notice a UI change.

Two affordances keep it honest:

Long-press a translated message to Show original; the same action flips it back.
Copy copies the text you are currently looking at, not the text underneath it.

If the text is already in the language you chose, or the message is emoji-only, nothing is translated. The bubble shows what was sent.

The learner's angle

Language exchange apps are built around your mother tongue. The recommendation is always "read foreign messages in the language you already speak". That is backwards for someone who is studying.

Consider someone learning Korean whose family writes in English. They set the read language to Korean, and the family group becomes daily reading practice in text they actually care about — not textbook sentences about airports, but "did you eat", "call me when you land", "your cousin passed the exam". Tap any message to check the original when the guess is wrong. Reply in English; nobody on the other side sees anything unusual.

That is the whole idea: immersion using conversations that were going to happen anyway, with no tutor to schedule and no second app to open.

It is also why the feature does not reuse the profile's mother language. Mother language describes how you want the product to talk to you. The read language describes what you are practising. They are different settings, and conflating them was the first thing we removed.

Language packs, not a translation service

The translation runs through Google ML Kit's on-device models. Each language pack is around 30 MB, downloaded from the platform's catalog and stored on the device.

The consequences are the reason this design works:

The message never leaves the phone. Language identification and translation are local calls. There is no queue, no API key, no per-message cost, and no text retention to explain in a privacy policy.
It works offline. Once a pack is downloaded, a flight or a metro tunnel changes nothing.
Storage is explicit. The settings page lists every supported language with a Download button, and downloaded packs move to their own section with a switch and a delete button. The user can see exactly what is taking space and remove it.

ML Kit supports 59 languages; the app's own list is around 130. The mode offers the intersection and shows the rest translated not at all — the original text simply stays. On Android it needs Google Play services; where the platform has no on-device translation, the mode reports itself as unavailable instead of pretending.

The server-side translation endpoint that powers the manual Translate action is untouched. That action still runs when you ask for it, in your mother language, and still shows its own translated section. Before Babel is a separate display mode with its own state, so the two never fight over the same bubble.

Inside the pipeline

Every incoming message is queued, identified, and — if a pack for that language exists — translated into the active read language. The result is written to a per-message field and cached under a key that includes both the target language and the message id.

The skip rules are where most of the behaviour lives:

if (sourceCode == null || sourceCode == target.code || sourceCode == 'und') {
  return;
}

// Translators bake their target in at creation: rebuild them when the
// active language changes, or messages keep arriving in the old language.
if (_translatorTargetCode != target.code) {
  await clearTranslators();
  _translatorTargetCode = target.code;
}

Three details matter more than they look:

Own messages are skipped. Translating your own text into the language you are studying teaches you nothing and doubles the work.
Already-translated messages are skipped. The cache key is per target language, so switching the read language re-translates rather than showing a stale result.
A source model may be downloaded on first contact. If someone writes in a language you have never received, ML Kit fetches that source model at translate time. That is deliberate — "translate from anything into my chosen language" is the promise — but it means the first message in a new language can be slow.

The queue processes one message at a time with a short gap, and pauses when the app is backgrounded. A burst of fifty messages should not heat the phone or stutter the scroll.

The edge cases that shaped the design

Three problems only showed up once the pipeline ran against a real chat, and all three are invisible on a synthetic test with five messages.

Newest messages first

Opening a chat queued the history oldest-first, which is the order the messages arrived in and the wrong order for the person holding the phone. The screen sits at the bottom of the conversation; translating the top of it means nothing visibly changes.

The fix was to reverse the backfill and bound it to the most recent thirty messages, then give live incoming messages a priority slot at the front of the queue. The message that just arrived is translated before the history behind it.

Translators are bound to their target

A translator instance is created for a source/target pair. Ours were cached by source language, so switching the read language from Korean to English kept reusing translators built for Korean. The first few bubbles looked right — they were already translated — and then new messages arrived in the previous language.

The fix tracks the target each cached translator was built for and rebuilds the map whenever the user switches. The comment in the snippet above exists because this bug will come back if someone "optimises" that check away.

Turning the mode off

Disabling the mode stopped the queue but left the translated text on screen: no active target meant no re-render, so bubbles kept showing text the user had just switched away from. Clearing the in-place text, the stored language code, and the show-original flag on disable fixed it — including the case where the user deletes their last pack instead of touching the switch.

What it costs, and where it stops

~30 MB per language model. Multiple languages mean multiple packs; deletion is one tap.
Packs are device-local. They are not synced across devices and not tied to the account.
Android needs Google Play services; without them the mode says so instead of failing silently.
Desktop and web are not supported. The pipeline degrades to the original text rather than throwing.
Quality is a translation engine's quality. Short, everyday messages are the sweet spot. Idioms, slang, and long technical paragraphs are where it struggles, which is exactly why the show-original toggle is one long-press away.

Testing the parts that are easy to get wrong

Two widget tests cover the behaviour that regressions would break quietly:

one asserts that a bubble swaps to the translation in place when the translated text arrives, with no scroll and no rebuild of the list;
one asserts the queue contract: newest-first backfill, the thirty-message bound, live-message priority, and duplicate skipping.

Neither is clever. Both exist because the bugs above were ordering bugs, and ordering bugs survive green tests that only check that translation happens at all.

FAQ

Does my message text leave my device?
No. Language identification and translation are on-device calls. Nothing in this mode talks to a server.

Does it replace the manual Translate action?
No. That action still exists, still uses the server engine, and still renders its own section. The two are independent.

Can I read a language I have not downloaded?
No. The pack has to exist on the device; that is what makes the mode work offline.

What happens in group chats?
Same pipeline. Every incoming message is identified and translated individually, so a group with four languages is just four source models.

Can I go back to the original text?
Per message, yes — long-press and choose Show original. Turning the mode off reverts everything at once.

Before Babel is the feature we wanted for ourselves: the app becomes a reading exercise made of your own conversations. If you are studying a language, the most useful text you can read is a message from someone who actually wants to talk to you.

Get Folcadi — a language-exchange messenger with live translation.

Official website: folcadi.com
Android: Google Play
Windows: .zip or installer
Linux: .deb or portable tarball
Articles: write-ups and covers
Telegram: @frank_says
Facebook: facebook.com/folcadi

Pre-ticked boxes are not consent: notification prompts default to off

Frank Milvus — Sun, 01 Nov 2026 02:18:44 +0000

Notification permissions are usually asked for badly. The app appears for the first time, and before the user has read a single message it shows the operating system's permission dialog. If they say no, the prompt is gone for good and the app quietly decides that notifications are not for this person. If they say yes, the app now has a blank cheque for message alerts, calls, reminder emails, and whatever marketing is invented next.

We shipped the opposite last week in Folcadi, a language-exchange messenger with a Flutter client. After login, once, the app shows its own preference sheet with four channels. Every switch starts off. Nothing is pre-ticked, nothing is bundled, and "Save" with everything off is a complete, accepted answer.

This post is about why the defaults are the whole product decision, and about the code shapes that follow from taking consent seriously: tri-state columns, a fail-open call gate, and an unsubscribe link that works without logging in.

The prompt we replaced

The old app had three problems, and they are the usual three.

The first was timing. The startup path requested the OS notification permission for every user, whether or not they had ever wanted a notification. On Android 13 and later that dialog is a one-shot resource: a reflexive "don't allow" during launch is hard to undo, and a lot of users never find the settings page to reverse it.

The second was bundling. One "notifications" concept covered message alerts, incoming-call ringing, a reminder email for unread chats, and product news. Those are four different offers with four different costs to the user. A person who wants to know about a missed call may not want a marketing email, and an app that conflates them has decided that for them.

The third was the data model. There was no record of anybody's preference, because there was no preference to record. The server mailed and pushed until something errored, and the only way to stop it was to silence the app at the OS level.

Four purposes, four switches

The new sheet is one themed dialog with four rows and a matching set of toggles in Settings → Notifications:

Choice	Starts	What it gates
Message notifications	off	Push alerts for new messages; turning it on asks the OS permission and registers this device
Incoming calls	off	Ringing for background calls; account-level, not per device
Email reminders	off	One reminder email if messages stay unread for days
Product news and offers	off	A separate marketing consent; nothing is sent under it yet

The copy is plain, and each row says what it does rather than what it is called: "Ring for incoming calls on your devices", "Email me if messages stay unread for a few days". The footer states the deal in one line: we only send what you select, and every reminder email carries a one-click unsubscribe link.

Separating the channels is not just politeness. It is the difference between consent that is specific and consent that is a blanket. A single switch forces a user who wants call alerts to accept marketing to get them, or to refuse everything to avoid marketing. Both outcomes are worse than four honest questions.

Why pre-ticked is not consent

In the EU, consent under the GDPR and the ePrivacy rules has to be freely given, specific, informed and unambiguous. Silence, inactivity, and pre-ticked boxes do not count. That is not an interpretation; the Court of Justice said it directly in Planet49 (C‑673/17, 2019), a case about pre-ticked cookie checkboxes. Ticking a box for someone, or treating "they did not untick it" as agreement, fails every part of that test.

I am not a lawyer and this is not legal advice. But the engineering consequence is simple, and it holds even in places where marketing consent is not a legal question at all: a default is a statement about who is making the decision. If the switch is on before the user arrives, the app made the decision and the user is only correcting it. If the switch is off, the user decides. That is also the only version that survives contact with an audit, an app-store review, or a reader asking "how do I stop this".

Marketing email is the strictest case. It gets its own switch, its own consent stamp, and its own unsubscribe path, even though we are not sending any yet. Asking for consent before you need it is fine. Assuming it is not.

Consent is a tri-state, not a boolean

Here is the part that sounds like pedantry and is not. A boolean column cannot tell the difference between "never asked" and "said no". If you treat both as false, then adding the prompt silently turns off call ringing for every existing user who has not opened the app since the release — a change nobody agreed to, discovered when somebody misses a call.

So the columns that represent a choice are nullable, and the third state is meaningful:

#   None  -> no choice recorded yet: keep the previous behaviour
#   True  -> opted in
#   False -> explicitly opted out
class NotificationConsent(Base):
    push_alerts: Mapped[bool | None] = mapped_column(nullable=True)
    call_alerts: Mapped[bool | None] = mapped_column(nullable=True)
    email_reminders: Mapped[bool] = mapped_column(default=False)
    product_news: Mapped[bool] = mapped_column(default=False)

Email reminders and product news default to false because there is no older behaviour to preserve: they are new channels, and new channels start off. Push and call alerts default to NULL, because they already worked, and a user who has not been asked must keep what they had. Only an explicit false suppresses anything:

async def opted_out_of_calls(db, recipients: list[int]) -> set[int]:
    rows = await db.execute(
        select(NotificationConsent.user_id).where(
            NotificationConsent.user_id.in_(recipients),
            NotificationConsent.call_alerts.is_(False),   # explicit no only
        )
    )
    return set(rows.scalars().all())

That single .is_(False) is the difference between honouring a "no" and inventing one.

One OS permission, hidden behind a product choice

There is only one notification permission at the operating-system level, and both message alerts and call ringing need it. Asking for it before the user has expressed an interest wastes the one shot you get.

The sequence we use is: the user picks channels in our sheet, and only if message alerts or calls are switched on do we ask the OS. If the OS says no, the switches go back to off and the app explains it instead of pretending to save:

var pushChoice = supportsPush ? _push : null;
var callsChoice = _calls;
var denied = false;

if (supportsPush && (pushChoice == true || callsChoice)) {
  final granted = await notificationService.requestOsPermission();
  if (!granted) {
    pushChoice = false;
    callsChoice = false;
    denied = true;
  }
}

The message after a denial is deliberately undramatic — "Notifications are blocked in system settings. You can enable them there later." — because a person who declined twice should not be scolded by an app they just installed.

The other half of this is unregistering. When a device ends up with no push channel on, its push token is deleted for that account, so "off" means off rather than "off in the UI, still buzzing".

Fail open where silence is dangerous

Preference lookups can fail. Databases time out, replicas lag, a migration lands mid-request. The question is what the failure means for the user.

For a marketing email, failing closed is right: if we cannot prove consent, we do not send. For an incoming call, the same logic is catastrophic. If the preference query throws and the code treats that as "not allowed", a phone stops ringing because of an unrelated hiccup. That is a missed call caused by a product decision about consent.

So the call gate fails open, explicitly:

try:
    rows = await db.execute(select(...).where(...))
    return set(rows.scalars().all())
except Exception:
    # A preference lookup must never be the reason a call stays silent.
    logger.warning("call-alert preference lookup failed", exc_info=True)
    return set()

The asymmetry is the point, and it is worth writing down next to the code: consent gates should fail closed for growth and open for safety. Marketing, newsletters, and re-engagement features can safely assume the answer is no. Calls, security alerts, and anything a user would call urgent cannot.

One more detail from that gate: cancel pushes are still sent to a user who turned call alerts off. Otherwise a device that was already ringing when the preference landed would keep ringing with no way to dismiss it.

"Not now" must not count as an answer

The sheet is shown once, and the server records both that it was completed and which version of it was shown. That gives us a cheap way to ask again if the choices materially change: bump the version, and the prompt returns once for everyone.

Dismissing is different from deciding. "Not now" closes the sheet without completing it, and the prompt can come back on a later launch — at most once per 24 hours, tracked locally per account. The cap matters: a preference that is genuinely useful deserves to be asked again later; it does not deserve to be asked on every cold start, which is how prompts become wallpaper.

The sheet also refuses to cover the wrong moment. If the app opened a chat or a call from a notification or a deep link, the prompt waits for a route where nothing is in progress, and gets offered on the next launch instead. Interrupting the one thing the user opened the app for is how you teach them to dismiss you.

There is a small implementation detail in the versioned-prompt model that is worth copying: the server is the source of truth for "this person has answered", and a local timestamp is only there to stop the sheet reappearing before the next launch. Clearing app data loses the local timestamp, not the decision.

Push is per device, calls are per account

The same sheet runs on a phone, a desktop client, and anything else signed into the account, and the four rows do not all mean the same thing on each.

Message notification is per device: a phone has a token, a desktop may have none, and a preference set on the phone should not be silently rewritten by a laptop that cannot receive push at all. So the desktop hides that row and reports "no opinion", which is the NULL state from earlier. The Calls choice is account-level, because a call should ring wherever the person is.

Getting this wrong is easy and invisible in testing. A desktop client that sends false for a channel it cannot even show looks like a clear preference in the database and a bug report in the making: "everything is off on my phone, and I never touched it".

Unsubscribing without logging in

Every channel has to be as easy to leave as it was to join, and email is the one where that is hardest, because the user may be reading it in a client that has no idea who they are.

Reminder emails therefore carry a signed link that needs no session, a visible unsubscribe link, and the standard one-click unsubscribe headers. Opening the link flips the flag off. It is the same column the in-app toggle writes, so the two cannot disagree, and the same consent stamp gets a new timestamp — a withdrawal is a decision too and deserves a record.

In the app, Settings → Notifications exposes all four channels with the same write path as the sheet. Changing your mind does not require finding the original prompt again.

What this costs

Honesty section: opt-in rates after this change are lower than they were when the permission was requested automatically. That is the intended result, not a bug.

The trade we made is a smaller list of people who actually want the alerts, in exchange for a list that means something. A push sent to a user who reflexively tapped "allow" during onboarding is worth very little; a push sent to someone who turned the switch on is worth something, and a push sent to someone who turned it off is a reason to uninstall. The same logic applies to the reminder email: it is opt-in, capped to one a week per person, and quiet for anyone who has been active.

We do not have retention numbers to show for this yet — the change is days old, and claiming a measured win would be inventing one. What we can say is that the support-shaped problem is gone: there is now one place that answers "why is this app emailing me", and it is the same place that stops it.

A checklist you can copy

If you are about to ship a notification prompt, these are the parts that mattered most:

Ask after the user has seen something worth notifying them about, not during the first launch animation.
Split the purposes. Message alerts, calls, reminder email, and marketing are four offers, not one.
Start every switch off, and make "all off" a real, saved answer.
Make consent tri-state. "Never asked" must not behave like "no".
Ask the OS last, once, after a product-level yes. Revert the switch and explain if the OS declines.
Write down which gates fail open. Calls and security alerts keep working when the preference lookup breaks; marketing does not.
Version the prompt so a material change can be asked about once, without becoming a nag.
Make leaving as easy as joining, including a link that works without a session.

None of this is exotic. It is mostly the decision to let the user answer the question instead of answering it for them, and then to build the data model that can remember the difference between "not yet" and "no".

FAQ

Is a notification prompt legally required?

Not in general, and this post is not legal advice. What is required in the EU is that consent — especially for marketing email — is freely given, specific, informed and unambiguous, which rules out pre-ticked boxes and silence. Separating the channels and defaulting them off is how you satisfy that while still asking for the alerts that make the app useful.

Why not just ask for notifications on the first launch?

Because the OS permission is a one-shot resource and the first launch is the worst moment to spend it. A user who has not received a message yet has no reason to say yes, and a reflexive "no" is much harder to undo than a considered "yes" is to earn.

What happens if someone dismisses the sheet?

Nothing is recorded as a decision. The sheet can be offered again on a later launch, at most once per 24 hours, and Settings → Notifications is always available. Only pressing Save writes the completion stamp.

Do existing users lose call ringing when they update?

No. The push and call preferences start empty (NULL), which keeps the previous behaviour until the person actually answers the prompt. Only an explicit "off" suppresses anything.

Does turning off message notifications still leave the account reachable?

Yes. In-app calls still arrive while the app is open and connected, and unread counts still work. The switch controls push delivery, not the account.

What does the reminder email contain?

Only a nudge that messages are waiting, with a link back to the app and a one-click unsubscribe. It never includes message content, and for encrypted chats it does not name the sender or the conversation either.

Get Folcadi — a language-exchange messenger with live translation.

Official website: folcadi.com
Android: Google Play
Windows: .zip or installer
Linux: .deb or portable tarball
Articles: write-ups and covers
Telegram: @frank_says

A Small App for Practicing Mental Math 🧠

Frank Milvus — Sun, 01 Nov 2026 01:40:26 +0000

I created NeuroCalT+ Mental Math to help me practice the Trachtenberg system of mental calculation.

The idea is simple: this app is not designed to teach you the entire Trachtenberg system or turn you into a fast calculator overnight. It is primarily a practice tool, with explanations of the methods to help you understand how they work.

I don't always have time to follow the app's progress or see how people are using it. Life gets busy, and sometimes side projects have to wait.

But it's always a pleasure to open Google Play Console and discover that someone has installed the app or found it useful. Even a few downloads are a nice reminder that something you created for yourself might help someone else, too.

Thank you to everyone who has given it a try!

If you're interested in practicing mental math, you can find it here:

📱 NeuroCalT+ Mental Math on Google Play

Sometimes, the best part of building something isn't watching the numbers grow — it's knowing that someone out there might find your work useful.

Keyboard navigation in Flutter on Linux: one modifier, cursors

Frank Milvus — Sat, 31 Oct 2026 06:17:13 +0000

Keyboard navigation in Flutter sounds like a solved problem until you try to add it to a real app. The framework gives you Shortcuts, Actions, and a focus tree, and on a form with a handful of fields that is genuinely enough. Then you open a chat, and the thing you want to activate is a message bubble that is not a focusable control, the list under it is reversed, an overlay is anchored to a row that may scroll away, and the user may be typing at the same time.

That is the situation in Folcadi, a language-exchange messenger with a Flutter client. This post is not a celebration of complete keyboard parity. It is a description of the model we settled on, the two rules that keep it honest, and the parts that are still mouse-only.

The first attempt was a pile of letters

The earliest version was the obvious one. Each screen got letter chords: Alt+S for Settings, Alt+M for Saved Messages, Alt+F for Feedback, and so on. It worked, and it was discoverable, because the tiles could show their own hint.

It also did not scale. Every new row wanted a letter, the letters started to collide across screens, and the help text grew into a list nobody could remember. Worse, the model implied that the keyboard was a second set of buttons rather than a way to move through the interface.

The version that survived is smaller:

one modifier, Alt by default, with Ctrl as an option for keyboards or browsers that claim Alt;
plain keys stay plain, so j, k, r, and d keep typing normally;
navigation is a cursor that moves and activates, not a shortcut per item.

That last point is the whole design. Lists, menus, confirmation dialogs, and the chat message list all use the same interaction: move the highlight, press Enter, press Escape to go back. New rows do not need a new letter; they become reachable the moment they are added to a list.

Resolve the modifier at match time

The modifier is a user setting, not a compile-time constant. Users pick Alt or Ctrl in Settings → Shortcuts, and the choice is stored locally and synced with the rest of their settings. Handlers read it when a key arrives, so changing it takes effect immediately, without rebuilding every screen.

The helper is deliberately small:

bool get _useCtrl => hotkeyModifierNotifier.value == HotkeyModifier.ctrl;

KeyboardShortcut mainHotkey(LogicalKeyboardKey key) =>
    KeyboardShortcut(key: key, alt: !_useCtrl, control: _useCtrl);

bool matchesMainHotkey(KeyEvent event, LogicalKeyboardKey key) =>
    mainHotkey(key).matches(event);

Everything else — handlers, help labels, the in-app cheat sheet — goes through helpers like these. When a chord is displayed, it is formatted from the same source of truth, so switching to Ctrl changes the labels too.

Cursors are the unit of navigation

KeyboardListCursor is the reusable piece. A page supplies the number of rows, an activation callback, and a builder that highlights the row at the current index. The widget owns the index, the raw key handler, and scrolling the highlighted row into view.

The important part is not the widget. It is that the row is built as a pair — the widget and the action — and the tap handler and the Enter handler call the same function. The keyboard path cannot drift from the touch path, because there is only one path.

The same cursor covers the More tab, Settings, contacts, notifications, pinned messages, blocked users, the account switcher, and the recipient pickers for forwarding, sharing, and adding members. Confirmation dialogs follow the same rule: H/K and L/J move between the buttons, Enter runs the focused one, Escape cancels. There are no Y/N letter chords, because a dialog is just another two-row list.

Pages that have nothing to activate — Help, profiles, device settings, a long settings sub-page — get a scroll scope instead: J/K for a small step, the arrow keys for half a page. A page gets a cursor or a scroll scope, never both. Menus need a highlight; switches and sliders need movement.

The chat is where the model gets tested

The chat was the hardest surface. It has bubbles rather than rows, a reversed scroll view, media that can be tall, and a composer that wants every plain letter.

The message cursor moves with J/K. The first press lands on the newest message, movement clamps at both ends, and date separators and system chips are skipped. Space opens the actions menu for the highlighted message, and that menu is a two-dimensional grid: H/L move across, J/K move down, Enter activates. The quick-emoji row is row zero, so reactions are reachable without a detour through the action list.

The most recent change removed a round trip. R, E, and D now act directly on the highlighted message: reply, edit, delete. The menu still offers the same actions, and the eligibility rules are shared with the menu rather than duplicated, so a message that cannot be edited cannot be edited by either path. When the highlighted message is not yours, the keys do nothing.

R was the interesting case, because it already meant "record a voice message" in the composer. Two meanings for one key is how a keyboard model rots. The fix was to make the two modes mutually exclusive: moving the cursor blurs the composer, and focusing the composer — by tap, by I, or by choosing Reply or Edit — drops the cursor. With a highlight, R replies; with no highlight, R records. The state of the screen tells you which one you will get.

Half-page scrolling moved to the arrows at the same time. D and U had been the page-scroll chords, which was fine until D became Delete on the highlighted message. The arrows were unclaimed and are easier to explain. The chat's list is reversed, so the scroll scope flips the sign by axis direction: "down" always means visually down.

The chat also binds F for in-chat search, C for the call chooser, and B for the translation mode. Each calls the exact callback the app-bar button calls.

Escape should cancel before it navigates

The back button is destructive if it leaves the screen while something is half-finished. If you have started a reply, staged a photo, or begun a recording, the first Escape should undo that, not walk you out of the conversation.

The chat's back handler now vetoes navigation while any transient state is active, and unwinds it in a fixed order: message actions overlay, multi-select, search panel, app-bar menu, attach bar, voice recording, edit mode, reply bar, staged image or album, expanded editor. Only when none of those is active does Escape leave the chat.

That one change made the rest of the hotkeys feel safe. Escape is "cancel" for a reply, an edit, or a recording, and Escape is still "back" when there is nothing to cancel. The rule is easy to state and, once implemented, easy to keep — the new E and D actions inherited it for free.

The focus problem nobody warns you about

Flutter's HardwareKeyboard calls every registered raw handler before the focus system gets the event. Returning true from a handler does not stop the focus tree from dispatching it afterwards.

This is not a theory. In a review pass over an earlier keyboard sweep, we found that pressing Enter with a cursor set could run the highlighted row and a button that happened to own focus — for example, opening two stacked confirmations in the account switcher. The fix is a rule, not a workaround: if a control inside the same route already owns focus, the cursor yields and Enter belongs to that control. When nothing in the route owns focus, the cursor takes it.

The same property — every raw handler runs — creates the second rule: one chord, one owner. Two features must never bind the same combination while both are live. A sweep caught exactly that when Alt+X was bound both to "remove this account" in the switcher and to "ignore this call" on the incoming-call ring. Ignore moved to Alt+N. The ring's keys also avoid the letters used by the cursors underneath, because a ring is mounted above every route and shares the focus scope of whatever page is visible.

These are the kinds of bugs that pass a clean analyzer and a green test suite. The behavioural review found them; the tests were written afterwards.

What this was tested on

Everything described here has been developed and tested on Arch Linux with the niri compositor. The key handling itself is ordinary Flutter — HardwareKeyboard, ShortcutScope, and raw handlers, with no compositor-specific code — so there is no reason it should be Arch- or niri-specific. But that is the only combination that has been exercised end to end so far.

Other Linux desktops, X11 sessions, Windows, macOS, and Android with a physical keyboard are expected to behave the same, and the widget tests run on Flutter's standard test platform. They are not verified on real hardware yet. If you try the app on another setup and a chord is inert, fires twice, or fights a desktop shortcut, that report is genuinely useful — it is the kind of gap this post is trying to be honest about.

What is not done yet

It would be easy to write this post and imply that Folcadi now works fully without a pointer. It does not, and I would rather say so plainly.

Some surfaces are still pointer-first. Gestures that have no obvious key equivalent — several drag and swipe interactions, for example — are reachable only by touch or mouse today.
Not every overlay is fully navigable. The main ones are; a few secondary surfaces still need a pointer or Tab.
There is no complete focus traversal. The app has a cursor model, not a full tab-order contract. A screen reader user and a keyboard-only user need different things, and the accessibility work is not the same project as the hotkey work.
Web is the weak platform. Browsers claim several modifier combinations before the app sees them. The hotkeys are designed for desktop and for Android with a physical keyboard, including environments that map a PC keyboard into Android; on the web they are best-effort.
Mobile is for external keyboards. The chords assume a hardware keyboard. On a phone with only a soft keyboard, the touch UI remains the primary interface.
Only one desktop setup is verified. Development and testing happen on Arch Linux with niri; other desktops and operating systems should work by construction but have not been exercised on real hardware.
Documentation drifts. Every new surface has to register its groups with the cheat sheet and the in-app help. If that step is skipped, the feature exists but is undiscoverable.

The direction is to keep closing gaps in that order: make the common flows complete, make the state cancellation predictable, and only then chase breadth.

How to discover what works

Press F1 anywhere. The cheat sheet is assembled from the scopes that are actually active on the current screen, so a plain page shows a few rows and a chat adds its own. The same chords are documented under More → Help, and the labels follow whichever modifier you chose.

If you use a keyboard with the app and find a place where you reach for the mouse, that is useful feedback. The gaps above are known; the one you hit is the one worth fixing next.

FAQ

Which platforms has this been tested on?

Arch Linux with niri. The handlers are plain Flutter and the widget tests run on the standard test platform, so other Linux desktops and Windows or macOS should work, but they have not been verified on real hardware yet. Web is limited by browser shortcuts, and mobile without an external keyboard still relies on touch.

Can I use Ctrl instead of Alt?

Yes. Settings → Shortcuts offers both. The choice is stored locally and synced like other settings, and every hint and help label updates to match.

Why not use plain letters, like a terminal?

Because the app has text fields everywhere. A chat composer, a search box, and a filter field all need ordinary letters. Requiring a modifier keeps typing and navigation from competing for the same keys.

How do I cancel something I started with the keyboard?

Press Escape. It unwinds the current transient state first — a reply, an edit, a recording, a selection — and only leaves the screen when there is nothing left to cancel.

Get Folcadi — a language-exchange messenger with live translation.

Official website: folcadi.com
Android: Google Play
Windows: .zip or installer
Linux: .deb or portable tarball
Articles: write-ups and covers
Telegram: @frank_says

GwinG is now Folcadi

Frank Milvus — Thu, 29 Oct 2026 22:24:05 +0000

The app is now called Folcadi.

The old name was GwinG. Everything else is the same: your account, your conversations, your settings, and the people you talk to.

The new name is rolling out across the app, the website, and the desktop builds. If a notification or a window title still shows the old name, update to the latest build.

That's it.

Welcome to Folcadi.

— the Folcadi team

Get Folcadi — a language-exchange messenger with live translation.

Official website: folcadi.com
Android: Google Play
Windows: .zip or installer
Linux: .deb or portable tarball
Articles: write-ups and covers
Telegram: @frank_says

Flutter WebRTC calls that never connected: three bugs, three fixes

Frank Milvus — Thu, 29 Oct 2026 12:46:14 +0000

For two weeks, every 1:1 audio and video call in our Flutter app failed the same boring way: the caller saw "Calling…", the screen flipped to "Ended" about a second later, and the callee's phone never rang. The client logs looked fine. The peer connection reached have-local-offer and then closed.

The temptation is to pick one suspect and start there. We spent the first evening on the relay server, which was genuinely broken — and fixing it changed nothing, because two other bugs sat in front of it. This is the story of all three, plus the small traps that were still waiting after them.

The symptom: `have-local-offer`, then silence

Worth stating precisely, because it narrows the search:

The app created an offer, set it as its local description, and sent it.
The backend accepted the WebSocket message without an error.
No answer ever arrived. After a timeout, the client tore the call down.

That rules out most of WebRTC theory — codecs, SDP munging, permissions — and leaves one question: did the offer actually reach the other side?

It did not.

Bug 1: the signalling key pointed at a row nobody created

The app signals calls over the WebSocket. Each event carries a call_id, and the backend looked up a CallSession by that id before relaying.

The problem is what call_id contains: the conversation id. The client never creates a call session at all — the table exists, the endpoints exist, and nothing calls them. So the lookup returned None for every offer, answer and ICE candidate, and the handler returned early:

Call 42 not found

Every event was dropped. The call closed immediately after have-local-offer, which is exactly what the symptom looked like.

The fix was to stop looking for a session and route by membership instead: resolve the participants of the conversation, reject a sender who is not a member, and relay the event to everyone else. The wire format did not change. call_id still means the conversation id; the backend re-prefixes the event type (offer → call_offer) and relays any type verbatim, including ones it has never heard of.

Two side benefits fell out of the change:

A new signalling event no longer needs a backend deploy to work.
The dead CallSession/CallParticipant models became obvious — including an endpoint that used a model it never imported, which only surfaced as a NameError. A test now pins that path.

The lesson: when a lookup fails on an id, check whether both sides agree on what the id identifies. call_id was a naming lie, and it cost a week.

Bug 2: a relay only the server could reach

With routing fixed, calls still failed — but now only sometimes. Office Wi‑Fi worked. Mobile networks did not. That is the classic signature of symmetric NAT: direct peer-to-peer connectivity fails, and everything has to go through a relay.

We had a relay. It was simply unreachable.

The TURN server ran on a machine behind NAT, published through a port-forwarding tunnel. Two things were wrong with that, and only one is obvious:

The relay advertised its own container address as the relay candidate, so clients were handed an address that does not exist outside that host.
Even with the address fixed, a single forwarded port cannot carry TURN. A relay is not one connection: each allocation gets its own UDP port for the peer. The tunnel maps one port; the relay needs a range. And STUN through that tunnel reports the tunnel as the client, so the whole candidate dance is meaningless.

The fix was to move the relay to a host that owns a public IP and configure it for the outside world. The settings that mattered, with the real values redacted:

listening-port=3478
external-ip=<public-ip>         # without this: a private address is advertised
min-port=<first-relay-port>
max-port=<last-relay-port>      # a dedicated UDP relay range, firewall-open
denied-peer-ip=<private-range>  # one line per range: loopback, link-local, RFC 1918
no-multicast-peers

Three operational details that are easy to miss:

The DNS record must be DNS-only. If the relay hostname sits behind an HTTP proxy or CDN, the proxy answers the UDP/TCP traffic and the relay never sees it.
Open the whole relay range in the host firewall, not just the listening port.
Keep the kernel's ephemeral port range away from the relay range. Otherwise the kernel can already hold a port the relay wants to bind, and allocations fail intermittently — the worst kind of failure.

The relay is also restricted so it cannot be used as a door into the host's private networks (the denied-peer-ip lines above). A relay reachable from the internet is a feature; a relay that will happily forward to the host's own loopback sockets is a vulnerability.

The lesson: "peer-to-peer works on my network" is not a test. Try a mobile network, and treat a missing relay as an untested code path.

Bug 3: the app stops listening when it goes to the background

Now calls connected — while both apps were open. Minimise one, lock the phone, and the call again reached nobody.

This one is architectural, not a typo. The app closes its WebSocket when it goes to the background, deliberately: an idle socket on a sleeping phone is a battery and reconnection problem. But a call offer is a one-shot event. Sending it to a socket that is closed means the offer is simply gone.

The fix: the backend now sends a data-only push whenever it relays an offer, and the app's background isolate shows a full-screen call notification with a looping ringtone, a vibration pattern, and Accept / Ignore / Decline actions. Accept launches the app and auto-answers; the pending call is parked in shared preferences so the UI isolate can adopt it on cold start or resume. There is no foreground service and no native audio code: the notification is the ring.

Three details turned out to matter more than the notification itself.

The push carries no SDP — and it should not. By the time the callee wakes up, the caller's ICE candidates have already been sent over a socket that was closed. The media path is broken whether or not the callee has the offer. So instead of squeezing an offer through a push, the callee sends an offer_request on accept, and the caller builds a fresh offer with restartIce(). A bare re-offer would reuse the already-converged ICE credentials and produce no new candidates, which is a confusing way to fail. The request also restarts the caller's ring timeout, so a slow wake-up does not look like a hang-up.

Decline is headless. The decline action runs in the background isolate, which has no WebSocket. It refuses the call over HTTP, and the server reuses the same relay path it would have used for a socket event. It also echoes a reject back to the declining device, so a ring that is still visible in the running app clears too. Ignore is also headless but signals nothing — it silences this device and lets the caller ring out.

The push must never block signalling. Pushes run on the caller's own WebSocket loop, right after the offer is relayed, and the ICE candidates are queued behind them. So the push is time-boxed to 1.5 seconds: an unreachable push service may delay the ring, but it must not stop the call from connecting.

Two Android details, since the ring lives in a notification channel:

Channel properties (sound, vibration, importance) are frozen at creation. Changing the ringtone therefore needs a new channel id, so the app selects one of a small family of channels based on the user's sound/vibration preference.
A channel's vibration pattern plays once, and FLAG_INSISTENT reliably repeats the sound, not the vibration. The pattern has to span the whole ring.

And one lock-screen rule: waking the screen and drawing above the keyguard is held only while a call exists, at runtime. Declaring it statically on the activity looks simpler and is worse — every launch then surfaces over the lock screen, which is how users end up staring at their PIN pad after a call.

Three smaller traps we hit afterwards

ICE candidates that arrive before the remote description. Candidates can only be applied once the peer connection has a remote description (the offer on the callee, the answer on the caller). Both sides routinely send candidates before they have it. Applying one too early is rejected by libwebrtc and silently lost — the call "connects", but media never flows. We buffer inbound candidates until the description exists, then flush.
Credential-less ICE entries and JSON null. If a STUN entry is serialised with "username": null, "credential": null, some platforms treat the server as credentialed and hand it to the wrong initialiser. The fix is to omit the keys entirely. This stays invisible until you try a platform you did not test on.
Devices that cannot capture video. One of our test devices exposes a camera that the WebRTC library fails to open with a fatal native error — not an exception Dart can catch, so the process dumps traces and it reads as a crash. Enumeration does not help: the camera is listed. We now combine identity-based detection, an explicit user override (Always on / Automatic / Always off), and a bounded fallback that degrades a call to audio instead of aborting it.

Why we were debugging blind

None of the above was findable from the app alone, because of a one-line mistake: the application root logger had no handler. Every logger.info in the backend — including the "call not found" line that would have ended the investigation in minutes — was silently discarded. The framework was happy to run without one.

Attaching a stdout handler immediately produced the diagnosis. Now the call handler logs one line per relayed event, with ICE candidates at DEBUG so they cannot bury the offer/answer/end lines:

call_offer conversation=42 from=1 to=[2]

The lesson: before adding logging to a subsystem, check that the logging you already have is not being thrown away.

What it looks like when it works

Audio and video calls now connect end to end: peer-to-peer when the network allows, relayed when it does not, and ringing on a locked phone. If ICE drops mid-call — a Wi‑Fi to cellular handover, for example — the caller renegotiates with a fresh offer, and only the caller ever offers, so the two sides cannot both renegotiate at once. A watchdog rebuilds a first attempt that sits in connecting too long, which is the difference between "video shows up in two seconds" and "the first call takes forever". We added the call-end card earlier in the same series of polish work, and it finally has something to show.

What is still missing

Being honest about the edges is part of the design:

Group calls. The relay already fans out to every conversation member, but the client is 1:1 and real group calling needs a different media server.
iOS background ringing. The push is still a background push there.
Ephemeral relay credentials. The credential is static today; short-lived credentials are the next improvement.
A real audio-route switch for speaker. The toggle is cosmetic on some devices.
Multi-device calls. Every device should ring and the first answer should win. That is the next post.

FAQ

Why does a re-offer need `restartIce()`?

Because a new offer alone does not re-gather candidates. The ICE credentials are already converged, so the offer reuses them and produces no new candidates — while the callee still has none of the old ones. restartIce() forces a fresh gathering round. See the WebRTC session lifetime notes and RFC 8656 for the relay side.

Why serve the ICE configuration from the backend instead of embedding it?

A credential compiled into the app cannot be rotated, and it can drift from what the relay actually accepts. Serving it means the server is the single source of truth, and the app caches it for the returned TTL. Configuration trouble then degrades a call to peer-to-peer instead of breaking it.

Why close the WebSocket in the background instead of keeping it open?

An idle socket on a sleeping phone is a battery and reconnection liability, and it does not reliably survive Android's background restrictions anyway. A push for the one event that must not be missed is a much smaller contract.

Do these fixes apply to group calls?

Partly. The signalling is already conversation-based, so relaying to N participants works. What does not work is the media topology: N participants using N peer connections does not scale, and the client is written for 1:1. That needs a different media server and a different post.

How do you make the full-screen ring appear on a locked phone?

A full-screen intent on a high-importance notification channel, plus the runtime lock-screen hold described above. Android grants and can revoke the full-screen intent permission, so the code degrades to a heads-up card with the same actions instead of failing. The Android notification guidance is a good starting point.

Get GwinG — a language-exchange messenger with live translation.

Android: Google Play
Windows: .zip or installer
Linux: .deb or portable tarball
Articles: write-ups and covers
Telegram: @frank_says

It is time for Linux.

Frank Milvus — Thu, 29 Oct 2026 12:39:49 +0000

Switching from Windows to Linux used to come with a steep learning curve. Figuring out different package managers, command-line flags, or manual installers just to get your daily apps running kept many people from making the leap.

That time is over.

With modern AI agents and terminal tools like OpenCode, setting up a new Linux environment is effortless. Want to install your favorite web browser, a chat messenger, or productivity tools? Instead of guessing whether to use apt, snap, or flatpak, you just tell your AI assistant what you want to install—and it handles the syntax and execution for you.

Here is why moving to Linux now makes sense:

Zero app installation friction: Natural language replaces tricky package manager commands.

Instant daily setup: Get your favorite browsers, messengers, and tools running in seconds.

Complete freedom: Enjoy the speed, security, and privacy of Linux without the terminal headaches.

If you’ve been hesitating to leave Windows, the barrier is gone. Linux is ready when you are.

Vibe-decking: how I use AI to build Anki decks for languages

Frank Milvus — Sun, 25 Oct 2026 13:10:33 +0000

I used AI to add 327 Korean grammar and reading cards to my Anki collection. I also used it to update my vocabulary decks without creating a pile of duplicates.

You do not need to know how to code to do this. You do not need a special app, an add-on, or a subscription to a flashcard service. You need three things:

the AI chat you already use (ChatGPT, Claude, Gemini — whichever you like),
Anki, the free flashcard app,
something to learn from: a textbook, a course handout, a grammar reference, or your own existing deck.

The rest is a repeatable loop: describe the deck, let the AI draft it, review it like an editor, import it. I call it vibe-decking, because it is the same idea as vibe coding, applied to language learning.

What vibe-decking has in common with vibe coding

Vibe coding is when you describe an app to an AI, it writes the code, you run it, and you keep fixing what breaks. You can get surprisingly far without being a programmer.

Vibe-decking is the same loop:

Vibe coding	Vibe-decking
You describe the app you want.	You describe the deck you want.
The AI writes the code.	The AI writes the cards.
You run the app and fix errors.	You study the cards and fix mistakes.
Some mistakes show up immediately.	Nothing catches problems for you.

That last row is the important one. Code usually fails loudly: the app crashes, the button does nothing, the page is blank. A bad flashcard fails silently. It looks perfect, you trust it, and three weeks later you discover you have been practising a wrong translation or a grammar pattern that nobody actually uses.

So the rule is simple: the AI writes the first draft, you are the editor. The time saving is real, but it comes from skipping the blank page — not from skipping the review.

Step 1: Start from something real

Start with one source. It can be:

a textbook chapter,
a grammar reference,
a course handout,
a list of words you want to learn,
or your existing Anki deck, if the goal is to improve it.

For the Korean grammar deck, I worked from standard beginner and intermediate grammar. For the reading deck, I worked from the standard pronunciation rules for Hangul, batchim, and sound changes. There was no single book behind those decks, which is exactly why every card needed review afterwards.

Two practical notes:

One source at a time. Mixing a textbook, a website, and a friend's notes makes it harder to tell where a card came from.
If there is no source, say so. The AI can still draft the cards, but you are now relying on its general knowledge. Mark that batch for review before you trust it.

Step 2: Ask for a sample, not the whole deck

This is the step most people skip. Do not ask for 500 cards on the first try. Ask for 20 or 30, look at them, and fix the style while it is cheap.

A prompt you can copy:

I am learning Korean. Make 25 beginner grammar cards.

Use five columns: Pattern, Meaning, How it is formed, Two examples, Russian translation.

One grammar pattern per card. Keep the explanation short. Use natural Korean examples with a romanization and an English translation. Do not mix two patterns into one card.

Read the sample and ask yourself:

Is each card about one thing, or is it a mini lesson?
Do the example sentences sound like something a person would say?
Is the translation accurate?
Is the romanization consistent?
Are two cards testing the same pattern?

Then tell the AI what to change. "Shorter explanations, one example instead of three, and put the Russian at the bottom" is enough. A good sample saves you from redoing 300 cards.

Step 3: Generate in batches, by topic

Once the sample looks right, ask for one topic at a time. For Korean grammar, that meant separate batches for:

beginner patterns: particles, numbers, negation, basic tenses,
intermediate patterns: connectors, cause and contrast, honorifics,
reading: Hangul letters, batchim, and sound changes.

Ask for the same columns every time. A spreadsheet is the easiest middle step: paste the table into Google Sheets, Excel, or LibreOffice, check it, and save it as a CSV file. CSV is just a plain spreadsheet file that Anki can read.

Why batches?

If one batch is bad, you redo one topic, not the whole deck.
You can review 100 cards in one sitting.
You notice gaps while the topic is still fresh in your mind.
You can study beginner cards while the intermediate batch is still being checked.

Step 4: Import the cards into Anki

In Anki:

File → Import.
Choose the CSV file.
Pick the deck (or create a new one).
Match the columns to the card fields: Pattern, Meaning, Formation, Examples.
Import.

The first import takes a couple of minutes. After that it is routine. If you want separate decks per level, import each batch into its own deck — for example, Korean Grammar::Beginner and Korean Grammar::Intermediate.

You can also make the cards look better later: bold the pattern, add color, or make the examples stand out. That is cosmetic. Get the content right first.

Step 5: Updating a deck you already have

This is where AI saves the most time, and where most people accidentally create duplicates.

The trick is to show the AI your current deck before asking for more. Export your deck from Anki as a CSV or a plain text file, upload it, and say:

Here is my current vocabulary deck. I want to add the top 50 Korean verbs. Find the ones I already have and give me only the missing cards, in the same columns. Do not repeat anything that is already in the deck.

I did exactly this with Korean vocabulary. Of the top 50 verbs, 46 were already in my deck. Only four were missing: 걷다, 뛰다, 잃다, and 헤어지다. With the top 50 nouns, 42 already existed and only 8 were new.

Without checking first, I would have added 88 duplicates. A deck full of duplicates is not just annoying — it wastes review time every single day.

"Look at what I have, then give me only what is missing" is the single most useful sentence in this whole workflow.

You can use the same trick to improve existing cards:

These are my current cards. Find the ones with unnatural example sentences, inconsistent romanization, or two ideas on one card. Give me a corrected version and explain what you changed.

Step 6: Review like an editor, not like a customer

The AI will produce cards that sound right. Some of them will be wrong. That is normal, and it is your job to catch it.

What I check in a language deck:

Meaning and translation. Does the English or Russian actually match the Korean? A wrong translation is worse than no card.
Naturalness. Is this how people speak, or is it textbook-only Korean that nobody uses?
Romanization. Is it consistent? In my Korean deck, a check found four romanization mistakes, including 오자마자 written as ojamaso instead of ojamaja, and 닦아요 written as dakayo instead of dagayo.
Pronunciation rules. For reading cards, does the pronounced form match the standard rules, or did the AI simplify it?
One idea per card. If a card asks for a pattern, its meaning, three examples, and an exception, it is not a flashcard anymore.
Your own errors. If you are not sure about a card, ask a native speaker, check a dictionary, or remove the card until you are sure.

A useful extra prompt:

Check these cards against the source. List any card that is not supported, any card that repeats another card, and any translation or romanization you are not confident about. Do not rewrite them yet — just flag them.

Then fix the flagged ones yourself. An AI reviewing its own work is not perfect, but it catches more than no review at all.

What the finished Anki language decks looked like

Deck	Notes	Cards
Grammar::01 Beginner	82	134
Grammar::02 Intermediate	83	134
Reading Rules	59	59
Total	224	327

On top of that, the vocabulary decks got two focused sets: 50 top verbs and 50 top nouns. Most of those were already in the collection, so the AI's job was to find the gaps, not to rewrite what existed.

The grammar cards came in two forms: a meaning card (see the pattern, explain what it means) and a drill card (see an English task, produce the Korean pattern). The reading cards asked "how do you read this?" and showed the pronunciation and the rule on the back.

That variety came from a decision made at the start, not from asking the AI to "make it good".

How much time does it actually save?

These are rough numbers from my own runs, not a scientific study. Card writing speed varies a lot.

Job	By hand	With AI
Korean grammar, 268 cards	6–9 hours	2–3 hours
Korean reading, 59 cards	1.5–2 hours	30–60 minutes
Adding 4 missing verbs to a 50-word set	20–30 minutes	5–10 minutes
Adding 8 missing nouns to a 50-word set	30–45 minutes	10 minutes

The pattern is consistent: the AI saves the first-draft time, and you still pay the review time. A card by hand takes one to two minutes. Drafting it with AI takes seconds. Checking it takes maybe ten to twenty seconds. That is where the roughly 3–4× improvement comes from.

It is not 100×, and anyone who tells you it is has not checked their cards. The first draft is no longer the bottleneck. Accuracy is.

Copy-paste prompts

Build a grammar deck from a textbook

I am learning Korean. I have uploaded [chapter or reference]. Build a study deck one topic at a time. Use the columns Pattern, Meaning, Formation, Two examples, Russian translation. One pattern per card. Use natural examples. Do not invent grammar that is not in the source.

Build a reading deck

Make cards for reading Hangul. Use the columns Prompt, Answer, Examples, Russian. The front shows a letter, syllable, or word. The back shows the pronunciation and the rule that explains it. Include batchim and sound changes.

Update an existing deck

Here is my current deck. Here is the new word list or chapter. Find what I am missing and give me only the new cards, in the same columns. Do not repeat existing cards.

Audit a batch

Check these cards against the source. Flag anything unsupported, duplicated, unnatural, or uncertain. Do not rewrite them yet.

Fix the style

These explanations are too long. Rewrite them as one short sentence each. Keep the same pattern and the same examples.

The bottom line

Vibe coding taught us that you can build software without typing every line yourself. Vibe-decking is the same deal for language learning: you can build a serious deck without writing every card yourself.

But the lesson from vibe coding applies here too. You can generate without coding, and you can generate without writing cards — you just cannot skip reading the result. The AI is a fast, tireless assistant who has read a lot about your language and might still get a translation or a pronunciation wrong. Your job is to be the editor.

Used that way, it is not a gimmick. It is how I went from "I should make a proper Korean deck" to 327 grammar and reading cards — plus two cleaned-up vocabulary sets — without spending a week at the keyboard.

Why I'm building GwinG, a language exchange app for awkward hellos

Frank Milvus — Tue, 20 Oct 2026 10:34:03 +0000

I'm not a language influencer

I'm FrankMilvus, and I build GwinG, a language exchange app. No, I'm not fluent in seven languages, and I don't have a 30-day method to sell you. I'm a developer who wanted to talk to people and got annoyed at how much work the apps made it feel like.

GwinG is the thing I wish I had about five years ago, when I installed a couple of the big language-exchange apps, found people to talk to, and then realised the apps were much better at matching than at the conversation that was supposed to come after.

The idea is roughly five years old. The current codebase is not. I started the version you can install today in July, and the repo is already at almost 900 commits. That number sounds impressive until you notice how many of them say "fix" or "release" and nothing else.

Up front: GwinG is not trying to be the biggest messenger in the world. It's a small product for a specific moment. The moment you want to say something to someone who speaks another language, and you don't want to spend ten minutes translating it in your head first.

The part most language exchange apps skip

Five years ago I wanted to find someone to speak with. Not a course. Not a flashcard deck. A person.

I tried a couple of the usual apps. They did the matching part fine: here's a profile, here's a language, here's a button. Then came the actual conversation, and that part was on me.

Finding a person is a directory problem. Having a conversation is a product problem. A lot of apps stop after the directory.

That's the gap I kept running into. The first message is easy enough. It's the fifth one that gets awkward. You run out of things you can say with the vocabulary you have, the other person switches to English to be helpful, and suddenly the language exchange is over and you're just two people chatting in the same language again.

What I wanted instead

I wanted the app to carry some of that weight.

If I have to copy a message, paste it into a translator, copy the result back, and hope the tone survived, I'm not having a conversation anymore. I'm doing data entry with extra steps. So GwinG puts translation inside the chat. You write in your language, the other person reads in theirs, and the original is always one tap away.

Voice messages work the same way. Transcription turns them into text you can read, search and translate. That matters more than it sounds. A voice note in a language you're still learning is basically a locked box. Text makes it something you can actually work with.

The point isn't to hide the other language. It's to give you a ladder. You read the translation, then you look at the original, and slowly you need the translation less. That's the whole trick. It's not magic, and it doesn't replace the awkward part. It just gives you something to hold onto while you get through it.

What GwinG actually is

The short version: a messenger. Chats and groups, voice and video calls, photos, voice notes, video, files, replies, reactions, pins, search, friends, presence. The usual stuff, plus the translation layer that makes the exchange part possible.

Under the hood it's Flutter on the client and FastAPI with PostgreSQL on the server. WebSockets for realtime, WebRTC for calls, object storage for media, and small services for speech and translation. Android, iOS, Windows and Linux. The code is mostly mine. I'm the person who gets to fix the weird desktop bug at 1am, which is a very effective way to learn desktop packaging.

Not because I'm some 10x developer. Mostly because the app is small enough to hold in my head, and I'm stubborn.

The team is basically a group chat

There are a few of us. We're spread out. Spain, South Korea, a few other places. So the app gets built across time zones whether we plan for it or not.

Between us we speak English, Spanish and Russian, and we're currently poking at Korean and German. Which means we're not guessing what it feels like to be the person who understands half the conversation and smiles anyway. We've all been that person.

That's also why a lot of the product decisions are boring on purpose. If a feature only works when everyone is already fluent, it's not a language-exchange feature. It's a feature for people who don't need the app.

The name is not the product

People ask what GwinG means. Honest answer: it's a project name.

We don't care about it the way you care about a child's name. If the app is good, the name becomes good. If the app is bad, no name saves it. We already changed it once, from tonGues, and the thing that mattered was that nothing underneath changed. Same accounts, same conversations, same keys. The name is a label on the box. The box is the product. If you want the whole rename story, it's here.

What I like about GwinG is that it doesn't pretend to mean anything in particular. It's five letters with a capital at each end. It's ours. That's enough.

"Getting better" is the whole roadmap

The line I keep coming back to is this: we're building a platform that lets people get better.

Not just better at grammar. Better at the messy part. Saying something before you're ready. Asking someone to repeat themselves without dying inside. Laughing at the fact that you just used the wrong word for "chicken" in front of a stranger. Coming back the next day anyway.

Fluency is a long game. Confidence is a shorter one. We can help with the shorter one.

So no, we're not promising you'll be fluent in 30 days. Nobody can promise that. We're trying to make the first message less scary and the tenth one easier. That's the whole pitch. It's not a growth hack, and it doesn't fit in a billboard.

What we're working on now

We're still in the unglamorous phase.

Calls that connect on the first try. Messages that don't get lost when the network blips. Translation that doesn't sound like a robot reading a legal document. Desktop builds that behave like desktop apps instead of a phone app in a big window. The list is long, and almost none of it makes a good demo.

That's also why I write everything up. The good changes, the ugly fixes, the ones that looked simple and turned into a three-day detour. You can find the longer version of the project in the overview post, or just follow the articles as they come out.

Where to find us

The code is private for now, but the decisions aren't. If you want to follow along, argue with a design choice, or tell me the app is missing the one feature you actually need, here's where:

GitHub: https://github.com/FrankMilvus
dev.to: https://dev.to/frankmilvus
Telegram: https://t.me/gwingorg
Articles: https://frankmilvus.github.io/tongues-articles/

Say hi. I read everything, including the messages that start with "this is probably a stupid question." Those are usually the good ones.

— FrankMilvus

Get GwinG — a language-exchange messenger with live translation.

Android: Google Play
Windows: .zip or installer
Linux: .deb or portable tarball

A Flutter tab shell that keeps every page alive

Frank Milvus — Mon, 19 Oct 2026 11:59:35 +0000

The spinner-on-every-tab problem

A bottom navigation bar looks like a solved problem. Four destinations, a selected index, a page for each one. The naive implementation is a pushReplacementNamed on every tap: each destination is its own route, and switching tabs swaps the route.

That works until the app has state worth keeping. In GwinG, each main tab owns real, expensive state:

Search runs a debounced user query, holds a map preview and polls presence for the visible results.
Friends owns the chat list, chat tabs, scroll positions, an avatar cache and a WebSocket subscription.
More is a menu whose keyboard cursor should survive a detour to another tab.
Profile renders the signed-in user's data and media.

With route replacement, every tap re-ran initState: another friends request, another version check, another avatar prewarm, another presence poll, and a scroll position reset to the top. The app was not slow because the network was slow. It was slow because it kept throwing work away.

The fix was to host all four tabs in one route and switch the visible child instead of replacing the route.

The shell in one widget

HomeShell is a StatefulWidget that takes an initial index, builds the four pages once, and keeps them in an IndexedStack:

Scaffold(
  body: FadeTransition(
    opacity: _tabFade,
    child: IndexedStack(
      index: _index,
      children: [
        for (var i = 0; i < _pages.length; i++)
          HeroMode(
            enabled: i == _index,
            child: _visited.contains(i)
                ? _pages[i]
                : const SizedBox.shrink(),
          ),
      ],
    ),
  ),
  bottomNavigationBar: const NavbarWidget(),
)

Three deliberate choices are packed into that tree.

1. Lazy visits, eager Friends

An IndexedStack builds every child it is given, even the ones that are not visible. Building all four tabs at startup would start four network paths before the user has asked for any of them. The shell therefore tracks a _visited set and substitutes an empty placeholder for tabs the user has never opened. A page's initState — and its first request — runs on the first visit, not at app launch.

The exception is Friends. Friends is the home tab in the product's mental model, so it is added to _visited at startup. By the time the user taps it, the list is already loaded or already loading. The tradeoff is one request at launch in exchange for never showing a spinner on a tab people open constantly.

2. One source of truth for the selected tab

The navbar does not navigate. It publishes an index to selectedNavBarNotifier; the shell listens and moves the stack. The same notifier is written by:

a navbar tap,
a horizontal page swipe,
the keyboard tab shortcuts,
a deep link or notification that asks for a specific tab.

Because every entry point writes the same value, the highlight, the visible page and the persisted "last tab" cannot disagree. A second notifier, selectedPageNotifier, records the tab for the next cold start. The shell renders; the notifiers decide.

3. A fade, not a rebuild

Switching tabs is a FadeTransition driven by a short AnimationController. It is subtle on purpose: the pages are already alive, so a large transition would draw attention to the fact that nothing was rebuilt. The duration also goes through the app's motion settings, so reduced-motion users get an instant switch.

What "alive" actually buys

Keeping a page mounted is not just about avoiding a spinner. It preserves:

Scroll position in long chat and search lists.
In-flight work: a search request or a friend refresh that started before the switch can finish and update the tab while it is hidden.
Subscriptions: WebSocket listeners and presence polling keep running, so returning to Friends shows current data instead of a stale snapshot.
Draft UI state: an open search box, an expanded menu or a keyboard cursor is still where it was.
Image cache warmth: avatars and media already decoded do not flash back in.

The price is that hidden pages are still running. That is the part the shell has to manage carefully.

Hidden pages are still listening

Every page that registers a keyboard handler, a WebSocket listener or a timer is still registered while it is off-screen. Without a gate, pressing a search shortcut on the Profile tab could move a cursor in a Search page nobody can see.

The codebase uses two gates consistently:

// In a page's raw key handler:
if (ModalRoute.of(context)?.isCurrent != true) return false;
if (selectedNavBarNotifier.value != _myTabIndex) return false;

The first line rejects input while a pushed page or dialog is on top. The second rejects input while another tab is visible. The same predicate is passed to the F1 hotkey-help registry, so the cheat sheet only advertises chords that actually work on the current screen.

Hero animations need the same treatment. Off-screen tabs stay mounted, so their Hero widgets are still in the tree. Without HeroMode(enabled: i == _index), a profile opened from Search could fly its avatar toward a hidden Friends row that happens to share the same tag. The shell enables heroes only for the visible child.

Layering swipe navigation on top

Once the shell exists, adding a horizontal page swipe is straightforward — provided each page decides who owns the gesture.

More and Search: a page-level wrapper

These pages have no inner pager, so they put HomeTabSwipe around the whole body. The wrapper recognises a decisive horizontal drag, applies distance and velocity thresholds, ignores drags near the left edge (the platform back gesture), and calls the shared tab-switch function with -1 or +1.

Inner gestures keep priority automatically. On Search, the map preview pans horizontally, and the vertical scroll view owns vertical drags; the page wrapper only sees drags that neither of them claimed. That is why the shell-swipe test starts its fling below the map instead of on it.

Friends: hand off at the edges only

Friends cannot use a page-level wrapper for normal swipes, because its body already contains a PageView for chat tabs. Swiping inside that pager must move between chat tabs, not between shell tabs.

The solution is a raw pointer listener around the PageView:

It records the pointer position and the current page on pointer-down.
On pointer-up it measures horizontal travel and rejects the gesture if it is mostly vertical.
Only when the pager is already on its first tab and the swipe goes backward, or on its last tab and the swipe goes forward, does it hand off to the shell.

Because the listener observes raw pointer events and never joins the gesture arena, the inner pager keeps its normal drag behaviour. The shell only takes over at the boundary, which is exactly what a user expects: swipe through your chat tabs, and keep swiping to leave the page.

The shell swipe wrapper is still used on Friends — but only in the loading state, where no PageView exists yet. That detail is the subject of the companion post, Flutter swipe navigation that keeps working while the app loads.

Not every page needs a swipe

The wrapper is opted into per page. Profile, for example, does not install a page-level swipe; its content is a vertically scrolling profile view, and the navbar and keyboard remain the navigation paths. This is a feature of the design, not an omission: gestures should be added where they do not compete with the page's own interactions.

Pull-to-refresh and maps in the same tree

Search combines three gesture layers that could easily fight each other:

A horizontal page swipe at the shell level.
A vertical pull-to-refresh indicator.
A map that pans in both directions.

They coexist because each recogniser is scoped:

The RefreshIndicator wraps a SingleChildScrollView with AlwaysScrollableScrollPhysics, so the pull works even when the result list is shorter than the viewport.
The map owns drags that start inside its bounds.
The page wrapper only accepts horizontal drags that the scroll view and map did not claim.

When a page adds a new horizontal child — a carousel, a swipeable row, a pager — the page-level swipe should be re-checked. The gesture arena will do the right thing most of the time, but "most of the time" is how dead zones and accidental tab switches get shipped.

Back behaviour and persistence

The shell changes what "back" means. On a main tab, the system back button minimises the app; on a sub-page (Settings, a chat, About), it pops back to the shell. The root wrapper implements that distinction once, so individual pages do not need their own PopScope handlers.

Persistence has a subtle failure mode the shell had to fix. The last visible page index was being written even while the user was on a sub-page. After the process was killed and restored, the app could cold-start on a route that is not one of the four tabs and has no navbar. The restore path now normalises the saved index to a tab route before navigating; sub-page indices map to their parent tab. The rule is simple: persist a destination, not an arbitrary route.

Testing a shell

The shell's tests are mostly about the invariants that are easy to break during a refactor:

home_tab_swipe_test.dart checks the gesture thresholds, direction mapping, the edge guard and the desktop no-op.
more_shell_swipe_test.dart and search_shell_swipe_test.dart assert that a swipe moves the shell notifier and the persisted page index.
friends_shell_swipe_test.dart checks all three behaviours: an outward swipe at the first/last chat tab switches shell tabs, an inner swipe stays inside Friends, and a swipe during the loading skeleton switches shell tabs.
Loading-state tests hold the async source open (a never-completing token read or friends fetch) so the dead state is actually reachable. A test that only pumps the loaded page cannot catch a missing wrapper.

The assertions are on navigation state, not on pixels. That keeps them stable across theme and layout changes while still failing when a gesture is silently dropped.

Tradeoffs worth naming

Memory versus refetching. Every visited tab stays in memory. For four tabs with image-heavy lists this is a real cost, mitigated by lazy first visits and by disposing per-tab controllers only when the shell itself goes away. The alternative — rebuilding and refetching on every tap — is a worse user experience and more network traffic.

Eager Friends. Pre-building one tab at startup is a deliberate asymmetry. It spends a little launch work to remove a spinner from the tab users open most.

Fade versus slide. A slide transition suggests spatial movement, which promises that a swipe will move the page with your finger. The shell does not implement that kind of pager; it switches instantly (with a short fade) and treats swipes as commands. Promising less is more honest than a half-implemented parallax.

One route, many states. Because the tabs are not routes, deep links need a mapping layer that both navigates to the shell and selects the right tab. That is a small amount of code, paid once, instead of duplicating state ownership across routes.

FAQ

Why not use a PageView for the whole shell?
A shell-level pager would own horizontal drags that several pages already use — chat tabs, maps, carousels and text selection. It would also keep every page's width in the layout and make state preservation depend on the pager's keep-alive behaviour. The IndexedStack plus per-page gesture wrappers is simpler to reason about.

Do hidden tabs keep making requests?
They can, and that is intentional for subscriptions and in-flight work. Each page still gates user input on visibility, and long-lived listeners are removed when the page is disposed.

Why does Friends appear before I tap it?
It is added to the shell's visited set at startup so it can load in the background. The other tabs stay unbuilt until first use.

Does swiping work on desktop?
No. The gesture wrapper is mobile-only; desktop uses the visible navigation bar and keyboard shortcuts. A horizontal mouse drag is usually selection, not navigation.

What happens in right-to-left languages?
The wrapper maps the swipe direction to the layout's text direction, and the destination is clamped at the first and last tab.

How are dialogs and pushed pages handled?
Both gates — "this route is current" and "this tab is visible" — fail while a pushed page or dialog is on top, so shell shortcuts and gestures stay out of the way.

Where to go next

If you are building a shell like this, start with the state model: one notifier for the selected tab, one persisted index, and a lazy IndexedStack. Add gestures one page at a time, checking what each page already owns. Then write tests that assert the navigation state while the app is loading, not only after it has finished. The loading state is where navigation bugs hide.

For the specific loading-state fix that started this pair of posts, see Flutter swipe navigation that keeps working while the app loads. For what the app itself is, start with the GwinG overview.

Get GwinG — a language-exchange messenger with live translation.

Android: Google Play
Windows: .zip or installer
Linux: .deb or portable tarball

Flutter swipe navigation that keeps working while the app loads

Frank Milvus — Mon, 19 Oct 2026 11:58:57 +0000

The swipe that only worked after the list appeared

GwinG is a language-exchange messenger with four main tabs: More, Search, Friends and Profile. On a phone, a horizontal swipe on a page body moves to the neighbouring tab, just like tapping the bottom navigation bar. It is a small convenience, but it is the kind of gesture people use without thinking.

A reader reported that it did not always work. Opening the Search tab on a slow connection and swiping left did nothing. As soon as the user list appeared, the same swipe worked. The gesture was not broken. It was simply not there during the part of the session where the app was waiting for the network.

That report was a useful reminder: a loading state is still a screen. If a screen can be looked at, it can be swiped, tapped, or dismissed. Treating loading as a placeholder that does not need navigation logic means every slow connection briefly traps the user on one tab.

Two tabs, three loading states

The first step was to stop thinking about "loading" as one state. Search alone has two of them:

The sign-in spinner. Before the app has finished checking its saved session, Search renders a full-page CircularProgressIndicator instead of the map, search field and results. This is a different widget tree from the loaded page.
The results skeleton. Once the session is ready, the normal page renders, but the results area shows shimmering skeleton rows while the first request is in flight.

Friends has a third:

The chats skeleton. The chat list shows skeleton rows until the first friends response arrives. Its shell hand-off lives inside a PageView that only exists once the list is loaded.

Only one of those three was originally wrapped in the swipe handler. The results skeleton was already inside the normal Search page body, so it inherited the gesture. The sign-in spinner was an early return with no wrapper. The Friends skeleton replaced the entire page that owned the PageView, so its swipe logic was gone too.

The wrapper: one page, one horizontal gesture

The shell uses a small widget called HomeTabSwipe. It is deliberately boring:

GestureDetector(
  behavior: HitTestBehavior.opaque,
  onHorizontalDragStart: (details) {
    _dx = 0;
    _ignored = details.globalPosition.dx < _edgeGuard;
  },
  onHorizontalDragUpdate: (details) {
    if (!_ignored) _dx += details.delta.dx;
  },
  onHorizontalDragEnd: _onDragEnd,
  onHorizontalDragCancel: () => _dx = 0,
  child: widget.child,
)

A few details matter more than they look:

Opaque hit testing. A swipe that starts on the gap between rows still counts.
A distance and a velocity threshold. A slow drag needs 48 logical pixels; a quick flick needs 320 pixels per second. Direction comes from the flick when there is one, otherwise from the finger's travel.
An edge guard. Drags starting within 24 pixels of the left edge are left to the platform's back-swipe gesture.
RTL awareness. "Next tab" is left in a left-to-right layout and right in a right-to-left one.
Mobile only. On desktop, tabs are switched with the keyboard or a click; inventing a drag gesture for a mouse would only fight text selection.

Inner horizontal gestures keep priority. A map pans, a horizontally scrolling list scrolls, a text field selects text, and an inner PageView pages. The page-level wrapper only sees the drags that no child claimed. That is exactly the behaviour a shell wants.

Fix 1: make Search swipeable from the first frame

The sign-in branch returned its own Scaffold, so the fix was to wrap its body in the same gesture widget the loaded page uses:

if (_token.isEmpty) {
  return Scaffold(
    appBar: AppBar(toolbarHeight: 0, /* ... */),
    body: HomeTabSwipe(
      onSwipe: _onSwipeToShell,
      child: const Center(child: CircularProgressIndicator()),
    ),
  );
}

_onSwipeToShell is the same handler as before: clamp the destination to the four tabs, give a small haptic, and call the shared selectNavTab function so a swipe and a navbar tap can never drift apart.

The important part is not the extra widget. It is the rule behind it: the swipe wrapper belongs at the page boundary, not around the success UI. If the page can render a full-screen waiting state, that state goes inside the wrapper too.

Fix 2: give the Friends skeleton the shell hand-off

Friends is more interesting because its swipes normally do two different jobs. Inside the loaded page, a PageView moves between chat tabs (All, Encrypted, Friends, and any custom tabs). Only when you reach the first or last chat tab and keep swiping does the shell take over and switch to Search or Profile.

That hand-off is implemented with a raw pointer listener around the PageView. It watches pointer-down and pointer-up, measures horizontal travel, rejects vertical drags, and hands off only at an outer edge. The listener is outside the gesture arena on purpose: the inner pager still owns normal tab swipes.

While the chats are loading, there are no chat tabs and no PageView. There is nothing to page through, so a horizontal swipe can go straight to the neighbouring shell tab:

child: _loading
    ? HomeTabSwipe(
        onSwipe: _handOffEdgeSwipe,
        child: const _FriendsSkeleton(),
      )
    : _loadFailed
        ? AppErrorState(/* ... */)
        : MotionEntrance(/* the loaded page */),

This reuses the same edge-hand-off function as the loaded page, including its clamping and haptic feedback. No new navigation path, no second definition of "which tab is next".

Testing gestures across async boundaries

The regression tests are the part worth copying. A widget test that simply pumps a loaded page cannot catch this class of bug, because the dead state only exists while an async operation is pending.

For Search, the test holds the secure-storage read open. The method-channel mock returns a future that never completes, so the page stays on the sign-in spinner. The test asserts that the spinner is on screen, flings from the middle of the page, and checks the shell's tab notifier:

final tokenRead = Completer<Object?>();
// secure-storage mock returns tokenRead.future for every read

await tester.pumpWidget(/* Search inside MaterialApp */);
await tester.pump();
expect(find.byType(CircularProgressIndicator), findsOneWidget);

await tester.flingFrom(
  const Offset(400, 300),
  const Offset(-300, 0),
  800,
);
await tester.pump();
await tester.pump(const Duration(milliseconds: 300));

expect(selectedNavBarNotifier.value, 2); // Friends

For Friends, the test injects a FriendsService whose fetchFriends() never settles. It asserts that skeleton rows are visible, flings the HomeTabSwipe, and checks that the shell moved to Search.

Two practical notes:

Do not use pumpAndSettle while a shimmer is animating. A repeating animation never settles. Explicit pump calls with a duration are deterministic and fast.
Make sure the test fails without the fix. Asserting "some widget exists" is not enough; assert the navigation result. In both cases the missing wrapper leaves the tab notifier unchanged, so the test fails for the right reason.

We also verified the results-skeleton state separately, including drags that start directly on a skeleton row. It already worked, which narrowed the fix to the two dead states instead of adding wrappers everywhere.

What this changes for users

Nothing about how the loaded pages look. The only visible difference is that a swipe now works while the app is still checking the session, the friends list, or the first page of search results. On a good connection the change is invisible; on a bad one it removes a two-to-ten-second dead zone.

Lessons that generalise

Audit every early return. A return Scaffold(...) above the main layout is a separate screen, and it needs the same navigation affordances.
Wrap at the page boundary. Put page-level gestures around the whole body, not around the widget that renders data.
Let inner gestures win. Maps, pagers, and text selection should keep their drags; the shell only handles what is left.
Test the waiting state. Hold the async source open in a widget test. If the test cannot reach the state, it cannot protect it.
Reuse the navigation function. Swipe, tap and keyboard all call one selectNavTab; a loading-state wrapper should use the same callback, not reimplement the rules.

FAQ

Does wrapping a spinner in a gesture detector cost anything?
No. It is one gesture recognizer on an otherwise static subtree. It does not rebuild during loading and does not delay the request.

Why not make the whole shell a PageView and get swipes for free?
Because several pages already own horizontal drags, and a shell-level pager would constantly compete with them. The architecture behind this choice is the subject of the companion post, A Flutter tab shell that keeps every page alive.

Does this work in right-to-left languages?
Yes. The wrapper maps "next" to the left in LTR and to the right in RTL, and the destination is still clamped at the first and last tab.

Why only mobile?
The gesture is a touch affordance. Desktop users have a visible navigation bar, keyboard shortcuts and a mouse; a horizontal mouse drag is usually selection, not navigation.

What about the platform back gesture on iOS?
Drags that start within 24 logical pixels of the left edge are ignored, so the system back swipe keeps working.

If you want the wider context, the GwinG overview explains what the app is, and the shell post covers how the four tabs stay alive without reloading.

Get GwinG — a language-exchange messenger with live translation.

Android: Google Play
Windows: .zip or installer
Linux: .deb or portable tarball

DEV Community: Frank Milvus

Your Flutter desktop app won't start: one corrupt preferences file

A launch that dies before it can report anything

Why one file decides whether the app starts

Why try/catch around the read is too late

Validate before you initialize

Quarantine instead of delete

The second half: startup must degrade, not block

Four tests that matter

What it costs the user

If it happens to you

What I took away

FAQ

Does this affect mobile?

Why not switch to a different storage package?

Why keep the corrupt file instead of deleting it?

Can the settings be recovered from the backup?

Read chats in the language you study: on-device translation in Flutter

What "in place" means

The learner's angle

Language packs, not a translation service

Inside the pipeline

The edge cases that shaped the design

Newest messages first

Translators are bound to their target

Turning the mode off

What it costs, and where it stops

Testing the parts that are easy to get wrong

FAQ

Pre-ticked boxes are not consent: notification prompts default to off

The prompt we replaced

Four purposes, four switches

Why pre-ticked is not consent

Consent is a tri-state, not a boolean

One OS permission, hidden behind a product choice

Fail open where silence is dangerous

"Not now" must not count as an answer

Push is per device, calls are per account

Unsubscribing without logging in

What this costs

A checklist you can copy

FAQ

Is a notification prompt legally required?

Why not just ask for notifications on the first launch?

What happens if someone dismisses the sheet?

Do existing users lose call ringing when they update?

Does turning off message notifications still leave the account reachable?

What does the reminder email contain?

A Small App for Practicing Mental Math 🧠

Keyboard navigation in Flutter on Linux: one modifier, cursors

The first attempt was a pile of letters

Resolve the modifier at match time

Cursors are the unit of navigation

The chat is where the model gets tested

Escape should cancel before it navigates

The focus problem nobody warns you about

What this was tested on

What is not done yet

How to discover what works

FAQ

Which platforms has this been tested on?

Can I use Ctrl instead of Alt?

Why not use plain letters, like a terminal?

How do I cancel something I started with the keyboard?

GwinG is now Folcadi

Flutter WebRTC calls that never connected: three bugs, three fixes

The symptom: have-local-offer, then silence

Bug 1: the signalling key pointed at a row nobody created

Bug 2: a relay only the server could reach

Bug 3: the app stops listening when it goes to the background

Three smaller traps we hit afterwards

Why we were debugging blind

What it looks like when it works

What is still missing

FAQ

Why does a re-offer need restartIce()?

Why serve the ICE configuration from the backend instead of embedding it?

Why close the WebSocket in the background instead of keeping it open?

Do these fixes apply to group calls?

How do you make the full-screen ring appear on a locked phone?

Why `try/catch` around the read is too late

The symptom: `have-local-offer`, then silence

Why does a re-offer need `restartIce()`?