DEV Community: K M Shahriar Hossain

The Same Seed Picked Minute 13 on the Phone and 18 on the Web

K M Shahriar Hossain — Mon, 28 Sep 2026 18:24:21 +0000

A dev.to thread last week was about daily reminders: fire one at a
random minute each afternoon, but make the minute the same for a given day, so
the schedule can be rebuilt as often as you like without a reminder appearing
to move. The standard trick is a seeded generator:

final minute = Random('2026-09-29'.hashCode).nextInt(60);

Same date, same seed, same minute. I compiled that one line four ways on Dart
3.13.4 and ran each on a Mac: the native builds directly, the JavaScript and
Wasm output under Node, and later all of it again in Chrome.

compiler	where it runs	minute
AOT (`dart compile exe`)	Android and iOS release builds	13
JIT (`dart run`)	debug builds, tests	13
dart2wasm	Flutter web built with `--wasm`	13
dart2js	Flutter web, the default build	18

The phone and the website disagree about the date.

Random isn't the problem

The first suspect is Random, and it's innocent. Random(42) produced the
same sequence, 587, 758, 4, 885, 77, under all four compilers, and so did
every seed I tried from −2³¹−1 up to 2³³, along with List.shuffle(Random(7)).

What changed was the seed. '2026-09-29'.hashCode is 160143713 on the VM
and on Wasm, and 374027133 when compiled to JavaScript. It isn't only
strings:

expression	VM, AOT	dart2wasm	dart2js
`'2026-09-29'.hashCode`	160143713	160143713	374027133
`7.hashCode`	81207	81207	7
`true.hashCode`	1231	1231	519018
`3.5.hashCode`	3377700795056128	786432	349197722
`DateTime.utc(2026, 9, 29).hashCode`	487035471	487035471	518150374
`Object.hash(1, 2)`	different every run	different every run	different every run

None of this is a bug. Object.hashCode is documented as something that "need
not be consistent between executions of the same program", and Object.hash
says outright that it may depend on values that change on each run, and every
run here gave a new number. A hash code exists to put things in a
Map during one execution. It was never a fingerprint.

What makes it slip through is that the VM happens to be stable for strings:
same value every run, so every test on your machine and every run on your
phone agrees with itself. 'a'.hashCode even matches on all three. The
difference only shows up on the build you probably tested least.

So hash it yourself — and it breaks again

The obvious fix is to stop borrowing hashCode and hash the bytes. FNV-1a is
a few lines:

int fnv1a(String s) {
  var h = 0x811c9dc5;
  for (final b in utf8.encode(s)) {
    h ^= b;
    h = (h * 0x01000193) & 0xffffffff;
  }
  return h;
}

Phone: minute 7. dart2js: minute 24.

On the web, a Dart int is a JavaScript number, and Dart's number
documentation spells out the two consequences. Integers "lose precision past 53
bits", and for bitwise operators "the operands are truncated to 32-bit
integers". Here the multiply is the problem: a 32-bit hash times a 25-bit prime
is a 57-bit product, and the low bits, the only ones the mask keeps, are
exactly the ones JavaScript rounded away.

Shifts fail the same way. 1 << 40 is 1099511627776 on the phone and 0 on
the web, so a seed built with a shift was never the same number in the first
place.

One web app, two answers

The table's last two rows are both Flutter web, and a --wasm build doesn't
choose between them — the browser does. A --wasm build compiles to
JavaScript as well, and Flutter's loader decides which one to start. In
Flutter 3.47, flutter.js ships a default allow-list of
{blink: true, gecko: false, webkit: false}: Chrome and Edge get the Wasm
build, and Safari, Firefox and every browser on iOS get the JavaScript one.

So the same deploy, at the same URL, picks minute 13 for someone in Chrome and
minute 18 for someone on an iPhone. Without --wasm it's 18 for everyone on
the web and 13 in the app, which is at least consistent within each.

That matters well beyond reminders: A/B bucketing by user id, a daily puzzle
seeded by the date, procedurally generated levels, shuffled quiz order, a
cache key or shard derived from a string. Anything where two devices are meant
to agree.

What held

Two versions gave the same answer under all four compilers.

A real hash from package:crypto, which does its arithmetic in 32-bit
pieces on purpose:

int stableHash(String s) {
  final d = sha256.convert(utf8.encode(s)).bytes;
  return (d[0] << 24 | d[1] << 16 | d[2] << 8 | d[3]) & 0x7fffffff;
}

Or FNV-1a with every intermediate kept under 2⁵³, by multiplying the low
and high halves separately:

int fnv1a(String s) {
  var h = 0x811c9dc5;
  for (final b in utf8.encode(s)) {
    h = (h ^ b) & 0xffffffff;
    h = ((h & 0xffff) * 0x01000193 +
            (((h >>> 16) * 0x0193 & 0xffff) << 16)) &
        0xffffffff;
  }
  return h;
}

Then take the value from the hash, not from a generator seeded with it:

final minute = stableHash(day) % 60;

Random(seed) does agree across compilers today, but its own documentation
says "the implementation of the random stream can change between releases of
the library." An SDK upgrade could move every reminder. A hash reduced with
% can't.

Test it where it breaks

A golden value catches all of this, but only if the test runs on each
compiler. Pin the answer once and run the same file three ways:

test('the minute for a date is fixed', () {
  expect(minuteFor('2026-09-29'), 53); // pinned from one VM run
});

dart test -p vm
dart test -p chrome
dart test -p chrome -c dart2wasm

With hashCode or the first FNV-1a, the VM and Wasm runs pass and the Chrome
run fails, with Expected: <53> and Actual: <33> for hashCode. With either
of the versions above, all three pass. -p vm alone passes everything, which
is how this ships.

Originally published at devshakib.jumyn.com. I write about Flutter, Dart and the parts of shipping that are genuinely awkward — and publish the packages that came out of them at pub.dev/publishers/jumyn.com.

Firestore Security Rules: Deny by Default, Then Open the Narrowest Hole

K M Shahriar Hossain — Thu, 24 Sep 2026 12:05:45 +0000

Every few months someone opens an issue on a Firebase project along the lines of "your API key is exposed in the JavaScript bundle." It isn't a vulnerability, and the panic is misplaced — but the instinct behind it is right, just aimed at the wrong thing. A Firebase Web API key is a project identifier, not a credential. It's supposed to be public. What people are actually reaching for when they panic about it is the real question: if anyone can point a Firestore client at my project, what stops them reading everything and writing whatever they like?

The answer is one file. Not obfuscation, not a proxy, not "nobody knows the collection names." Security rules are the entire perimeter, and they're the only part of the stack an attacker can't route around, because they execute on Google's servers before a single byte of your data moves. Everything else — your Flutter code, your admin panel's login screen, the if (isAdmin) check that hides the delete button — is client-side theatre that a curious person can bypass with the browser console and ten minutes.

My portfolio runs 114 blog posts, 98 browser tools, 32 games and an admin panel on Firestore and Cloud Storage, and it costs me exactly $0 a month on the Blaze plan. That $0 is partly a rules property: there are no public writes to content anywhere in the schema, so there is no path by which an anonymous visitor can run up my bill. This post is the rules file I actually ship, section by section, with the reasoning behind each line — including the one behaviour that makes people think their rules are broken when they're working perfectly.

Start with the deny, then open the narrowest hole

The mental model that keeps rules files honest is to write them backwards from how you'd naturally think about them. Don't start with "the blog should be readable." Start with nothing is readable and nothing is writable, and then make yourself justify every hole you punch in it.

Concretely, that means the last block in my file is this, and it was the first block I wrote:

// Default deny: anything not matched above is locked down
match /{document=**} {
  allow read, write: if false;
}

Firestore's default is already deny — an unmatched path is denied without you saying so. Writing it explicitly anyway matters for two reasons. First, it documents intent: the next person to open the file (which is me, eight months later) sees immediately that this is a closed-by-default schema and not an accidentally incomplete one. Second, it changes how you add things. With the deny at the bottom, adding a feature means consciously adding a match block above it and deciding on read and write separately. Without it, people tend to grow rules by loosening whatever's nearest.

The order of operations I follow when a new collection shows up:

Write the match block with nothing allowed.
Ask who needs to read it — public, admin, or nobody — and open exactly that.
Ask who needs to write it, which is almost always "admin only."
If the answer to step 3 is "the public," write a validation predicate before you write the allow.

Step 4 is where most of the real work is, and where most of the bugs live. I'll get to it.

One structural note: rules do not cascade the way file permissions do. A match /posts/{docId} block does not grant anything to /posts/{docId}/comments/{commentId} — subcollections need their own match, or a recursive {document=**} wildcard. This trips people in both directions: they assume a parent grant covers children (it doesn't), or they use a recursive wildcard to save typing and accidentally expose a subcollection they hadn't thought about. Be explicit.

One admin, identified by an email claim

Here's the whole authorisation model for my site:

function isAdmin() {
  return request.auth != null
    && request.auth.token.email == 'admin@yourdomain.com';
}

That's it. One function, one address, no roles collection, no permissions document, no membership lookup. Every write in the entire schema goes through it.

The reason this is safe is worth stating precisely, because it looks flimsy at first glance: the email in request.auth.token is not client-supplied. It's a claim inside a Firebase ID token, signed by Google, and verified server-side before the rule ever runs. You can't set it from the client any more than you can set your own bank balance. To make isAdmin() return true, an attacker has to actually authenticate as that account — which means having the password, or the second factor if you've enabled one. The email address itself isn't a secret and doesn't need protecting; knowing it buys you nothing.

There's a cheaper reason to like it too: it costs zero document reads. A role-collection approach — get(/databases/$(database)/documents/roles/$(request.auth.uid)).data.admin == true — does a real Firestore read on every single rule evaluation, and those are billable. On a site whose entire purpose is to cost nothing, that's a design constraint, not a micro-optimisation.

Where this is the wrong answer

I want to be honest about the trade, because "single admin identified by email" is genuinely bad advice above a team size of one.

The moment there are two admins, you're editing a rules file and running a deploy to grant access, which is a terrible way to manage people. It doesn't revoke cleanly, it has no audit trail, it can't express "this person can publish posts but not delete apps," and the rules file becomes a personnel record living in git history forever.

The right answer at team scale is custom claims: request.auth.token.admin == true, or request.auth.token.role in ['editor', 'admin'], set through the Firebase Admin SDK. Claims are still signed, still free to check, and they decouple identity from authorisation — you grant and revoke by running a script against a UID, not by deploying rules. The catch, and the reason I haven't done it, is that setting a custom claim requires somewhere privileged to run the Admin SDK, and I have deliberately no Cloud Functions in this project (they're the main way a "free" Firebase project stops being free). A one-off local Node script against a service account key works fine for a handful of users; a real team wants that wired into an onboarding flow.

So: email claim for one person, custom claims the moment there are two. Role collections mostly when the permission model is genuinely dynamic and data-driven, and then accept that you're paying a read for every rule evaluation.

One hardening note I'd add before enabling a second auth provider: check request.auth.token.email_verified == true alongside the address. With a single email/password account it's redundant, but some identity providers will hand you a token carrying an email the user never proved they own, and the whole model rests on that address meaning something.

Public read of published content only

Content collections split into two shapes. The always-public ones are trivial:

match /profile/{docId} {
  allow read: if true;
  allow write: if isAdmin();
}

The ones with drafts need a predicate:

function isPublished() {
  return resource.data.get('status', 'draft') == 'published';
}

match /posts/{docId} {
  allow read: if isPublished() || isAdmin();
  allow create, update, delete: if isAdmin();
}

Two details in there earn their place. resource (no request. prefix) is the document as it currently exists in the database — this is a read rule, so we're inspecting stored data, not incoming data. And .get('status', 'draft') supplies a default, so a legacy document that predates the status field is treated as a draft rather than blowing up the rule. Defaulting to the closed state is the right instinct: if the data is ambiguous, deny.

Splitting write into create, update, delete rather than using the write shorthand is deliberate too. They're identical here, but when I later needed different logic for create versus update on the leads collection, the block was already shaped to take it.

The list-query behaviour that looks exactly like a bug

Now the part that generates the most confused Stack Overflow questions in the whole Firebase ecosystem.

With allow read: if isPublished() in place, this query fails with permission-denied:

FirebaseFirestore.instance.collection('posts').get();

Every single document in that collection might be published. It still fails. And the first time it happens it looks completely broken — you can fetch an individual published post by ID and it works, but listing the collection doesn't.

The reason is a rule Firebase states plainly and everyone forgets: security rules are not filters. The server does not run your query, fetch the matching documents, evaluate the rule against each one, and quietly drop the failures. That would be a query-cost and information-leak problem, and it would make query latency depend on how much data you can't see. Instead, Firestore evaluates the rule against the query itself and demands that the query is provably safe before it runs. An unconstrained collection('posts') could match an unpublished draft, therefore the whole request is denied.

allow read covers two operations — get (one document by ID) and list (a query). Fetching a published post by ID satisfies the rule because there's a concrete resource to evaluate. A list has no single resource, so Firestore checks whether your query's constraints guarantee the rule holds for everything it could return.

The fix is to make the constraint explicit in the query:

FirebaseFirestore.instance
    .collection('posts')
    .where('status', isEqualTo: 'published')
    .orderBy('publishedAt', descending: true)
    .limit(20)
    .get();

Now the query itself proves that every document it can return satisfies isPublished(), and it's allowed. The denial was correct behaviour and the client was wrong — which is exactly the shape of a good security control, and exactly why it feels like a bug.

Two practical consequences. First, your admin panel and your public site need genuinely different query code, not the same call with a different UI. Second, that where plus orderBy combination needs a composite index; mine lives in firestore.indexes.json as status ascending plus publishedAt descending, with a second one adding tags array-contains for the tag pages. You'll find this out from a console error with a link that creates it for you, but it's worth knowing that a rule requiring a filter implies an index requiring deployment — the two are coupled, and forgetting the second one breaks production while the emulator (which builds indexes on the fly) stays green.

Validating request.resource on write

resource is what's in the database. request.resource is what the client is trying to put there. Read rules inspect the first; write rules inspect the second. Mixing them up is the single most common rules bug I see, and it fails in the dangerous direction — a create has no existing resource, so a rule that references resource.data on create evaluates against null and denies, which you'll notice; but a rule that checks resource.data.ownerId on update is checking the stored owner, not the incoming one, which may or may not be what you meant.

For anything the public can write, the rule needs to constrain the incoming document hard. My contact form is the only such path on the site, and it looks like this:

match /leads/{docId} {
  allow create: if
    request.resource.data.keys().hasOnly(
      ['name', 'email', 'subject', 'message', 'type', 'budget', 'company', 'read', 'createdAt']
    )
    && request.resource.data.name is string
    && request.resource.data.name.size() > 0
    && request.resource.data.name.size() < 120
    && isValidEmail(request.resource.data.email)
    && request.resource.data.message is string
    && request.resource.data.message.size() > 0
    && request.resource.data.message.size() < 5000
    && request.resource.data.read == false
    && request.resource.data.createdAt == request.time;
  allow read, update, delete: if isAdmin();
}

Four separate defences in there, each closing a specific hole.

The field whitelist. keys().hasOnly([...]) is the most important line in the block. Without it, a client can post a perfectly valid contact form that also carries {isAdmin: true}, or {read: true} to hide itself from my inbox, or 400 junk fields. The rule schema and the app's model class drift apart the moment someone adds a field to one and not the other, and a whitelist makes that drift a failed write instead of silent data pollution. Note it's hasOnly, not hasAll — hasAll checks required keys, hasOnly forbids extras, and you frequently want both.

Size caps on every free-text field. A Firestore document can be just under 1 MiB. A message field with no cap means an anonymous visitor can write a megabyte per submission, as fast as they can loop. That's a storage bill and a bandwidth bill in my admin panel, and it's trivially scriptable. Every string a stranger can set gets a maximum. Note the optional fields get the same treatment — a field being optional doesn't mean it's safe if present:

&& (!('company' in request.resource.data)
    || (request.resource.data.company is string
        && request.resource.data.company.size() < 200))

Server-controlled fields pinned to their initial value. read == false on create means a submission always lands unread; a client can't ship one pre-marked. Any field whose meaning is owned by your backend rather than the user needs pinning like this, or excluding from the whitelist entirely.

Never trusting client timestamps. request.resource.data.createdAt == request.time is my favourite line in the file. request.time is the server's clock at the moment of evaluation. The only way a client can satisfy that equality is by sending FieldValue.serverTimestamp() — the sentinel that tells Firestore to fill the value in server-side. Anything the client computes itself, including DateTime.now(), fails. This turns "please use a server timestamp" from a code-review convention into an enforced invariant. Without it, a spammer can backdate submissions to the bottom of my sorted inbox, and more generally, any ordering or expiry logic built on a client clock is built on a value the client fully controls.

Storage: content type and size are the whole game

Cloud Storage rules follow the same shape, with two extra levers:

function isAllowedUpload() {
  return request.resource.size < 10 * 1024 * 1024
    && request.resource.contentType.matches('image/.*|application/pdf');
}

match /public/{allPaths=**} {
  allow read: if true;
  allow write: if isAdmin() && isAllowedUpload();
  allow delete: if isAdmin();
}

match /{allPaths=**} {
  allow read, write: if false;
}

request.resource.size is the byte count of the incoming object and contentType is its declared MIME type, and on a bucket where uploads are admin-only these are belt-and-braces — but they're the difference between a compromised admin session costing me an afternoon and costing me a bandwidth bill. On any bucket where users can upload, they are not optional.

The caveat worth naming: contentType is client-declared metadata, not a content inspection. Restricting to image/.* stops someone casually uploading a 200 MB video; it does not stop someone uploading a disguised payload with an image content type. Rules can constrain the envelope, not the contents. If what's inside matters, you need processing behind the upload, and that's a different system.

The structural decision that matters more than either rule: large binaries don't live in Storage at all. APKs and DMGs for my apps sit on GitHub Releases, and the site links out. Download bandwidth is the line item that turns a free Firebase project into a surprising invoice, and the cheapest way to control it is to not serve the large files.

Rules are a security boundary, not a validation framework

Everything above might read as an argument for pushing all your validation into rules. It isn't, and the distinction is the most useful thing in this post.

Rules are the right place for anything that must hold no matter who is calling — the field whitelist, the size caps, the server timestamp, "only the admin writes here." These are properties an attacker must not be able to violate, so they belong on the server side of the trust boundary, and there is no other server side in a Firebase-only architecture.

Rules are a bad place for everything else, and the constraints of the language tell you why. Rules Language has no loops, no regular-expression capture groups, no way to call out to anything, a hard limit on expression complexity, and a cap on get() calls per evaluation. You can't cross-validate two documents meaningfully. You get no error message back beyond permission-denied, so a user who fills a form wrong sees a generic failure with nothing actionable in it. And every additional get() you add to satisfy a business rule is a billable read on every single request.

So the split I use:

Business validation lives in the client, where you can give a real error message next to the offending field, in real time, before anything is sent.
Security invariants live in rules, where they're unbypassable and where the error being unhelpful is fine, because the only people hitting it are misbehaving.
Where they overlap — an email must be well-formed, a message must be non-empty — I write it in both places and accept the duplication. The client version is a user experience; the rules version is a guarantee.

The last piece is testing, because a rules file is executable code that ships with no test coverage by default. @firebase/rules-unit-testing against the emulator lets you assert both directions, and the negative assertions are the ones that matter:

await assertFails(db.collection('posts').get());              // unfiltered list denied
await assertSucceeds(publishedPostsQuery(db).get());          // filtered list allowed
await assertFails(db.collection('leads').add({ ...ok, isAdmin: true }));

I run those with firebase emulators:exec before any rules deploy. Rules changes are the highest-blast-radius deploys in the whole project — one loosened predicate and your drafts are public — and they're also the easiest to get wrong, because the failure is invisible. Nothing errors. Nothing looks different. The data is just readable now.

Key takeaways

Your Firebase API key is a project identifier, not a credential — everything in the client bundle is public by definition, which makes security rules the only real perimeter your data has.
Write the deny-by-default rule first, then justify every hole you open, and split write into create/update/delete so the block is already shaped for the day the logic diverges.
A single admin identified by a signed email claim is correct at team-size one and wrong the moment there are two — move to custom claims before you're editing a rules file to onboard a colleague.
Security rules are not filters: an unfiltered collection query is denied even when every document in it would pass, because Firestore validates the query rather than the results — and the fix is a where clause plus the composite index it implies.
resource is what's stored and request.resource is what's incoming — write rules must constrain the second with a hasOnly field whitelist, size caps on every free-text field, and server-owned fields pinned to their initial values.
Comparing a timestamp field to request.time forces the client to use FieldValue.serverTimestamp(), turning "don't trust client clocks" from a convention into an invariant the server enforces.
Rules are a security boundary, not a validation framework — put unbypassable invariants there, put helpful user-facing validation in the client, and test the denials against the emulator before every deploy.

The rules file is the smallest, highest-leverage piece of code in a Firebase project. Mine is 192 lines and it's the only thing standing between an anonymous visitor and every document I own — and because it's server-side, it's the only part of my stack whose guarantees survive a determined person with the browser console open. Write the deny first. Open the narrowest possible hole. Constrain every incoming document by shape and by size. Let the server set the clock. And when a query comes back permission-denied and the data looks like it should have been readable, consider — before you loosen anything — that the rule might simply be right.

Most of the mistakes above can be seen without running a single rule, so there is now a VS Code extension that looks for them as you type: ds_rules flags open writes, test mode left on, anyone-can-edit and unchecked uploads, and stays quiet about the public reads and admin writes you meant.

Google Indexed the Blog and Nothing Else on My Flutter Web Site

K M Shahriar Hossain — Fri, 18 Sep 2026 13:47:25 +0000

On 10 September, Search Console's verdict on this site was 18 pages indexed and
401 not. Four hundred of those sat in "Discovered — currently not indexed",
which is Google saying it knows the URL exists and hasn't bothered to fetch it.

The breakdown was stranger than the count. Of the 23 pages that had ever
appeared in a search result, 22 were blog posts and the 23rd was the home page.
Not one app, tool, game or package page had a single impression, and /apps,
the page that links to 96 of them, read "URL is unknown to Google".

"Discovered — currently not indexed" usually gets blamed on crawl budget or a
young domain. Neither explains why one kind of page gets in and every other
kind doesn't. Something about the blog was different.

Flutter web draws text Google can't read

The site is Flutter web with the CanvasKit renderer, which paints everything,
text included, onto a <canvas>. To a crawler, a canvas full of words is an
image with no alt text.

The usual answer is to ship the words separately. A build step
(tool/prerender.py here) writes a real HTML file for every route, with the
page's text and links inside the served document:

<div id="prerendered-content">
  <h1>Apps</h1>
  <p>…</p>
  <a href="/apps/helm">Helm</a> …
</div>

It's clipped to one pixel rather than hidden with display: none, so it stays
in the document for crawlers and screen readers without being seen. curl any
route and the content is there. That check passed on every page from the day
it shipped.

The part `curl` can't see

Google doesn't index the HTML the server sends. It runs the page's JavaScript
and indexes the DOM that results. For a Flutter app, that means main.dart.js
boots and paints a first frame.

And index.html had this, written alongside the prerendering:

window.addEventListener('flutter-first-frame', function () {
  // ...fade out the loading screen...
  var seo = document.getElementById('prerendered-content');
  if (seo) { seo.remove(); }
});

A comment in the stylesheet explained why: the crawler copy goes "the moment
Flutter paints the same content properly". That's true for a person looking at
the screen. It isn't true for the DOM. Under CanvasKit, "painted properly" means
pixels, so once the handler ran, the document held a canvas and nothing else:
zero words and zero links on every route.

Every route except blog posts. Posts carry a second copy: when a post opens,
the app adds its body to the document as a hidden <article>. The handler
removed one element by id, and that wasn't it. That is the whole difference
between the 22 pages Google knew and the rest.

It also explains "Discovered". Google had found the other pages through the
sitemap and nothing else. The hub pages that should have linked to them
rendered as empty dead ends, and a URL that only appears in a sitemap is about
the lowest crawl priority there is. So they waited.

Let the app keep the copy

The handler isn't wrong in general; the loading screen should go. The copy just
shouldn't go with it. So the app claims the block before its first frame by
renaming it, and the handler's getElementById finds nothing to remove:

// In main(), before runApp.
final el = web.document.querySelector('#prerendered-content');
if (el != null) {
  el.id = 'seo-prerendered';         // the first-frame handler now misses it
  el.setAttribute('style', clipped); // the clipping CSS was keyed on the old id
  el.setAttribute('aria-hidden', 'true');
}

Three details matter:

Re-apply the clipping inline. The stylesheet rule that hid the block was keyed on the old id. Rename it without this and the whole crawler copy appears on screen.
Hide it from screen readers. The app turns on Flutter's semantics tree, which is the accessible version of the page. With both exposed, a screen reader would read every page twice.
Drop it on navigation. The block describes the route that was served. When the visitor moves to another route inside the app, it's removed, so the document never carries text for a page that isn't showing.

It's the same content the app paints, so this isn't a different page for
Google. The crawler just gets the text version of the page instead of a picture
of it.

What changed

Search Console's live test afterwards returned "URL is available to Google",
and the rendered HTML of /apps had 159 words and 96 links instead of none.

Then indexing was requested for eight pages: the home page, the six hubs
(/apps, /tools, /blog, /games, /work, /packages) and one app page.
Not the 400 leaves. Requests are capped at roughly ten a day, and one crawled
hub hands Google about 96 links, which is how leaves get discovered without
being requested one at a time.

By 14 September: 99 indexed, up from 18. It isn't a controlled experiment,
since the fix and the requests landed in the same week, but requesting an empty
hub would have handed Google nothing to follow. And 330 pages are still in
"Discovered — currently not indexed", so this is a slope, not a switch. The
queries now arriving are for tools and posts ("flutter treemap", "tone
generator"), the kinds of page that used to be invisible.

Check the rendered page, not the response

If you ship Flutter web with prerendered HTML, curl is not the test that
matters:

Search Console → URL Inspection → Test live URL → View tested page → HTML. That's the DOM Google indexes. Search it for a sentence from your page.
Or open the page, wait for it to paint, and run document.body.innerText.length in the console. If it's near zero on a page full of text, a crawler sees the same nothing.
Search index.html for anything that removes elements on flutter-first-frame, and ask what exactly it removes.

The served HTML was right the whole time. The page deleted it before the one
reader who mattered got there.

Five Requests in Fifteen Seconds From One Status Bar Item

K M Shahriar Hossain — Mon, 14 Sep 2026 16:40:57 +0000

Claude Code knows how much of your usage limits you have left, but it shows you
in a panel you have to go and open. The number belongs where you are already
looking, so it went into the VS Code status bar:

Claude 5h 12% · 7d 39%

Hover for every limit and when each one resets; the item turns amber at 75% and
red at 90%. The first version worked. The second, released the same evening, had
the usage endpoint answering 429: five requests in fifteen seconds, and every one
of them extended the wait.

Every window runs your extension again

The mistake was thinking of the extension as one program. It isn't. Each VS Code
window runs its own copy, with its own timers and its own event handlers, and
nothing is shared between them unless you share it.

So the real schedule was never "one request every five minutes". It was:

every open window, polling on its own timer,
plus a fetch whenever any window gained focus,
plus a fetch on every click of the item, including while the server was saying wait.

Move between a few windows, click the item because the number looks stale, and
you get what happened here: five requests in fifteen seconds, each one making
the block longer.

One result, shared through a file

VS Code gives every extension a global storage folder,
context.globalStorageUri, and it is the same folder in every window. That makes
it the simplest place to keep a result that all of them can read.

A window no longer asks the server just because it woke up. It reads the file
first, and only fetches if the numbers there are older than the refresh
interval:

// Fresh enough? Then this is just a render — no request.
const age = last ? Date.now() - last.at : Infinity;
if (age < (manual ? CLAIM_MS : s.minutes * 60_000)) {
  render();
  return;
}

Two windows can still find the same stale file at the same moment, so the one
that fetches writes a claim first, and any window that sees a claim younger than
30 seconds stays out of it:

// Another window is already fetching.
if (cache.fetchingAt && Date.now() - cache.fetchingAt < CLAIM_MS) return;

The timers also carry up to 20 seconds of random jitter, so windows opened
together don't wake together. Focusing a window now costs nothing: it re-renders
what is already in the file.

A 429 is an instruction

The worst part of the old version was the click. The item looked stuck, so it
got clicked, and each click was another request to a server that had just said
stop.

Now a 429 sets a block, written to the same shared file so every window obeys it.
Its length is whichever is longer: the server's own retry-after, or 5 minutes
doubling on each repeat up to 30.

function nextBlock(strikeCount, retryAfterMs) {
  const curve = Math.min(BLOCK_MAX, BLOCK_MIN * 2 ** Math.max(0, strikeCount - 1));
  return Math.max(curve, retryAfterMs || 0);
}

And a click cannot override it. That felt wrong to write, because a button that
does nothing looks broken. So the tooltip says when the next check is due, which
turns "why won't it refresh" into an answer.

A failed check is not an outage

The very first version had the opposite problem: it treated one failure as news.

The extension reads the login Claude Code already keeps: the macOS Keychain
entry Claude Code-credentials, or ~/.claude/.credentials.json elsewhere.
Claude Code rewrites that entry whenever it renews its login, and a read that
lands in that moment comes back without a token. The status bar showed a warning
where the numbers should have been, until the next poll five minutes later.

Now a failure keeps the last numbers on screen, falls back to the token already
held, and retries after 20 seconds, then 60, then 120. The warning appears only
after three failures in a row, and the tooltip always names the last one. Nothing
is hidden; it just stops shouting.

What it touches

Anything that reads a login should say plainly what it does with it:

The login, read-only. The token is never refreshed, never written back and never logged, so the extension cannot sign Claude Code out. If the stored token has expired, the item says so, and using Claude Code once renews it.
One request every few minutes, to api.anthropic.com, shared by every window.
Nothing else: no telemetry, no other network calls.

The endpoint deserves the same honesty. It is the one Claude Code's own usage
panel reads, not a published API, so a Claude Code update could change or remove
it. If that happens, the extension shows a warning instead of numbers.

Three rules for a polling extension

Assume one copy per window. Anything on a timer or a focus event is multiplied by the number of windows open. Share the result, not the schedule.
Treat 429 as an instruction. Store the wait where every copy can see it, don't let a button override it, and show when the next try is due.
One failure is noise. Keep the last good value, retry quickly, and warn only when failures repeat.

ds_usage is free and MIT licensed, on the
VS Code Marketplace,
with the source on GitHub.

Full Disk Access Was On, and macOS Still Refused the App

K M Shahriar Hossain — Sat, 12 Sep 2026 19:16:35 +0000

A Mac app I maintain needs Full Disk Access. It measures disk usage, and most of
what is worth measuring sits behind that permission. I switched it on in System
Settings ▸ Privacy & Security ▸ Full Disk Access, and the app went on reporting
limited access. Its banner said what these banners say: already granted?
Relaunch. Relaunching changed nothing, and never could have.

The app did not validate

A permission is granted to an app, and to macOS "the app" is not a name. So the
first question is whether macOS can tell what the app is:

$ codesign --verify --deep --strict --verbose=2 /Applications/Helm.app
/Applications/Helm.app: nested code is modified or invalid
file modified: /Applications/Helm.app/Contents/Frameworks/App.framework

App.framework is where Flutter puts the compiled Dart. Verified on its own it
was fine, and so were the other four frameworks in the bundle. What failed was
the app around them.

An app's signature seals its contents. Contents/_CodeSignature/CodeResources
records, for every nested framework, the hash of the code that should be there.
It recorded one App.framework, and the bundle held another:

seal records    Frameworks/App.framework   4ba5cc60…
actually there  Frameworks/App.framework   c7a45621…

Contents/_CodeSignature/CodeResources      15:08:47
Contents/MacOS/Helm                        15:08:47
Contents/Frameworks/App.framework/…/App    15:30:38

The seal and the executable came from one build. The framework came from a build
twenty-two minutes later, which put a new App.framework in place and never
re-sealed the app around it.

Why a stale seal turns the switch into decoration

TCC, the part of macOS behind every Privacy & Security switch, does not store
"this app is allowed". It stores a code requirement and checks the running app
against it. For an app signed with a Developer ID, that requirement names the
developer's team. For an ad-hoc signature, which is what you have without one,
it is effectively the hash of the code.

A bundle whose nested code does not match its own seal does not validate, and
code that does not validate cannot satisfy a requirement. The grant attaches to
nothing. The switch reads ON, every protected path stays refused, and no relaunch
touches any of it.

Re-signing the bundle and granting access again fixed it: the app reported Full
Disk Access on, and kept it through a restart.

How the seal went stale

Two things write a Flutter macOS bundle. A script phase runs
macos_assemble.sh embed, which hands off to Flutter's xcode_backend.dart: it
copies the freshly compiled App.framework into Contents/Frameworks and signs
it. Then Xcode signs the app, which writes the seal. In a good build the
timestamps land a second apart, framework first:

build 1  clean              verify ok   seal 23:19:32   App.framework 23:19:31
build 2  one Dart change    verify ok   seal 23:20:06   App.framework 23:20:05

So it is not simply what an incremental build does, which is what I assumed at
first and wrote into a changelog. A clean build seals correctly, and so does a
Dart-only rebuild straight after it.

What reproduced it, once, was a crash. On a copy of the project, a Swift change
built fine. The next build, a one-line Dart change, died:

error: unexpected service error: The Xcode build system has crashed. Build again to continue.

Doing as told, with another Dart-only change:

✓ Built build/macos/Build/Products/Release/Helm.app (47.1MB)

$ codesign --verify --strict Helm.app
Helm.app: nested code is modified or invalid

seal records App.framework dda6dabc96dd    actual afaf15310e15
Contents/_CodeSignature/CodeResources      23:22:42
Contents/MacOS/Helm                        23:22:42
Contents/Frameworks/App.framework/…/App    23:23:28

The build after the crash ran Flutter's embed step, skipped the app's signing,
and reported success. Same fingerprint as the build that shipped: seal and
executable from one build, framework from a later one.

I can't prove the shipped build went through a crash. I had kept only the last
few lines of each build, and a crash in an earlier one is exactly what that
throws away. Nor do I know which other failures leave the same state. An
interrupted build is the obvious suspect, and I haven't tested it. That
uncertainty is the argument for the next two sections.

(Reproduced on Flutter 3.47.3, Xcode 26.6, macOS 26.6.2. The shipped build was on
Flutter 3.47.1, and none of the patch-release changes in between are about
signing.)

Why nothing caught it

Not because the check is subtle. My first theory was that only --deep compares
nested code with the outer seal, so a check without it would have waved this
bundle through. It was wrong. On a copy with App.framework swapped out:

codesign --verify App.framework        exit 0    valid on its own
codesign --verify Helm.app             exit 1    nested code is modified or invalid
SecStaticCodeCheckValidity, flags 0    -67021    nested code is modified or invalid

No flags needed. Any verification of the app fails it.

The release script did not verify at all. Its signing and its verification lived
in the same branch:

if [[ -n "$SIGN_ID" ]]; then     # a Developer ID certificate was found
  # ...sign every framework, then the app...
  codesign --verify --strict "$BUILD_APP"
fi

The app is free and deliberately has no $99-a-year Developer ID, so that branch
never ran. The path that always ran signed nothing and checked nothing, and the
DMG shipped whatever flutter build had left behind.

The fix

Sign and verify on every path, and let a failed verification fail the release:

if [[ -n "$SIGN_ID" ]]; then
  SIGN=(--force --timestamp --options runtime --sign "$SIGN_ID")
else
  SIGN=(--force --sign -)   # ad-hoc: never notarised, so no runtime or timestamp
fi

# Inside-out: nested code first, then the bundle that holds it.
for fw in "$APP"/Contents/Frameworks/*.framework; do
  codesign "${SIGN[@]}" "$fw"
done
codesign "${SIGN[@]}" --entitlements macos/Runner/Release.entitlements "$APP"

codesign --verify --deep --strict "$APP" || { echo "signature broken" >&2; exit 1; }

Sign with a loop rather than codesign --deep, which Apple advises against for
signing. For verifying, --deep is fine, and with --verbose it names the file
that changed.

And the app now checks itself before telling anyone to relaunch. This goes
through the Security framework rather than running /usr/bin/codesign, which
does ship with macOS, because it is a yes-or-no question with a status code for
an answer:

import Security

func bundleValidates() -> Bool {
  var code: SecStaticCode?
  guard SecStaticCodeCreateWithPath(Bundle.main.bundleURL as CFURL, [], &code) == errSecSuccess,
        let code else { return true }          // couldn't ask: don't accuse
  let flags = SecCSFlags(rawValue: kSecCSCheckNestedCode | kSecCSStrictValidate)
  return SecStaticCodeCheckValidity(code, flags, nil) == errSecSuccess
}

When access reads as denied and that returns false, the banner stops saying
"relaunch" and says the true thing: this copy cannot hold the permission, so
reinstall it and grant access again. When the check cannot run at all, it
answers true. Telling someone a working app is broken is worse than saying
nothing.

The part that is not a bug

An ad-hoc requirement is the hash of the code, so to TCC every build is a
different app. Every update loses Full Disk Access and needs granting again. No
release script fixes that. It is the cost of not having a Developer ID, whose
requirement names the team instead of the bytes and so survives an update. For a
free app, the honest move is to say so at the top of the release notes rather
than let people find out.

Three rules

Verify the bundle you ship, on every path. Plain codesign --verify is enough. Never gate the check behind having a certificate: the path without one is the path that always runs.
Don't trust ✓ Built after a build that crashed. Build clean, or verify. The build after a crash can succeed at everything except sealing the app.
If your app needs a privacy permission, check its own signature before blaming the user. "Relaunch" is sometimes a loop with no exit.

The app is Helm, a free Mac utility
built with Flutter. Its release script and self-check are in the repository.

The self-check is a package now: macos_grants reads Full Disk Access, Accessibility and Screen Recording, and answers the question underneath them — whether this copy of your app can hold a grant at all.

macOS Made a File That Reports Zero Bytes and Occupies Sixty Kilobytes

K M Shahriar Hossain — Tue, 08 Sep 2026 10:16:30 +0000

I was writing a storage analyser, which means walking every file on the disk
and adding up what it costs. Somewhere around the 140,000th file the progress
line printed a path that does not exist:

/Users/me/Applications/Chrome Apps.localized/localized

There is no localized in that folder. There is a .localized, and there is
one other thing, and that other thing turned out to be two separate problems
wearing one filename.

The file

$ ls -b ~/Applications/Chrome\ Apps.localized/
Icon\r

Not Icon followed by something. The name is the four characters I, c,
o, n, and then byte 0x0D — a carriage return. Python is blunt about it:

>>> os.listdir(d)
['Icon\r', '.localized']

macOS wrote that. Every folder with a custom icon gets one: Finder → Get Info →
paste an image, and this appears. The trailing CR is a fossil from classic Mac
OS, where it was the line terminator, and it is there to keep the file out of
the way of anything that lists a directory naively. It has outlived the reason.

Problem one: it eats your log line

A filename on a POSIX system may contain any byte except / and NUL. That
includes carriage return, newline, escape, and backspace. Almost nothing you
write treats a path as anything other than text you can print, and this is
where that assumption gets paid.

Here is what a progress line actually emits:

$ find box -type f -print0 | while IFS= read -r -d '' f; do
    printf 'scanning %s  42,318 files\n' "$f"
  done | hexdump -C
00000000  73 63 61 6e 6e 69 6e 67  20 62 6f 78 2f 49 63 6f  |scanning box/Ico|
00000010  6e 0d 20 20 34 32 2c 33  31 38 20 66 69 6c 65 73  |n.  42,318 files|

Look at offset 0x11: 6e 0d — the n of Icon, then 0d, the carriage
return. The terminal receives it and does what a terminal has always done with
a CR: it moves the cursor back to column zero. The rest of the line then
overwrites what you just printed. You do not see a corrupted path. You see a
line that is missing its front half, spliced onto whatever came next — which
is precisely as confusing as it sounds when the count in front of it is also
changing.

The same byte does the same damage to a single-line label in a GUI, a CI log,
and anything that later parses its own output. And the CR is the polite one: a
filename containing \n will break find | while read line outright, because
that loop's entire contract is that filenames do not contain newlines. Hence
-print0 and read -d '', which exist for this reason and not for style.

If you render paths anywhere a human will look, strip the control range first:

final safe = path.replaceAll(RegExp(r'[\x00-\x1f\x7f]'), '?');

Problem two: it is zero bytes, and it is sixty kilobytes

This is the one that actually mattered for a disk tool.

stat -f %z         (st_size)        0 bytes
ls -l                              0
os.path.getsize()                  0
------------------------------------------------
st_blocks × 512                61,440 bytes
du -k                              60 KB

The data fork is genuinely empty. The icon — 61,010 bytes of it — lives in an
extended attribute:

$ xattr ~/Applications/Chrome\ Apps.localized/Icon^M
com.apple.FinderInfo
com.apple.ResourceFork
com.apple.provenance
com.apple.quarantine

com.apple.ResourceFork is the resource fork, the other half of a classic Mac
file, kept alive on APFS as an xattr and reachable through a magic path:

$ stat -f %z ~/Applications/.../Icon^M/..namedfork/rsrc
61010

st_size describes the data fork. It always has. So a scanner that sums
st_size — which is the obvious thing to sum, and what os.path.getsize hands
you — reports this file as free. Sixty kilobytes, invisible, once per folder
with a custom icon.

Sixty kilobytes is nothing. The habit is not nothing. st_size is a statement
about content; st_blocks is a statement about the disk, and a disk usage
tool is answering the second question. They come apart in three directions and
resource forks are only one of them:

Sparse files report a large st_size and occupy almost no blocks.
Compressed files — macOS transparently compresses much of /System and many app bundles — report the uncompressed size and occupy less.
Resource forks and xattrs report nothing and occupy real space.

Sum st_size across a volume and your total will not match About This Mac, in
either direction, and the user will believe Apple. Correctly. du has always
used st_blocks; that is the whole reason du and ls -l disagree, and I had
read that fact several times without it meaning anything until a zero-byte file
turned up holding an icon.

The catch, if you write Dart

Knowing to use st_blocks and being able to are different problems. Dart's
FileStat exposes size, mode, type and three timestamps. There is no
blocks. File.length() is st_size as well. The number you want is in the
stat struct the VM already called and did not surface, so reaching it means
going around the standard library:

// dart:ffi against stat(2), or a platform channel to
// URLResourceKey.totalFileAllocatedSizeKey on the Swift side.

Which is the actual reason so many size-summing tools get this wrong. It is not
that st_size is chosen over st_blocks; it is that in most high-level
languages st_size is the only one handed to you, and the difference between
"how big is this file" and "what does this file cost me" never comes up until
something reports zero and takes sixty kilobytes.

Two rules I would now write down before starting a tool like this:

Sum st_blocks, not st_size, and if the language will not give you st_blocks, that is a dependency you take on day one rather than a refactor you do after the totals disagree with About This Mac.
Strip [\x00-\x1f] from any path before rendering it. Paths are bytes, not strings, and one of them on your Mac right now ends in a carriage return.

The file is still there. It is on your Mac too — find ~ -name 'Icon?' -type f
will tell you, and the ? is the only way to match it that does not require
you to type a carriage return into your shell.

Flutter Assumes There Is Only One Window. I Gave It Two.

K M Shahriar Hossain — Sun, 06 Sep 2026 17:02:19 +0000

Document Picture-in-Picture is a browser API that gives you a real operating
system window. Not an overlay pinned inside your page — an actual window the
browser owns, floating above your editor and your terminal and everything else,
which keeps running when you switch tabs.

Chrome and Edge have had it since 116. Firefox shipped it in 151. Almost
nothing uses it, and I could not find anything reaching it from Flutter, so I
wrote document_pip to find out why.

The API itself is about four lines. The difficulty is entirely on the Flutter
side, and it has one cause: the engine is built on the assumption that there
is one window. Not stated anywhere as a constraint — just quietly baked into
three different singletons. A second window makes each of them wrong, and every
one of them fails silently, in a way that looks like a different problem.

A package cannot turn multi-view on

The first wall is structural. Multi-view Flutter has no single root, so an app
that can grow a second view calls runWidget, not runApp. That part is
documented.

The part that is not: only the JavaScript app object returned by
engine.runApp() can add a view. dart:ui_web exposes the view list
read-only. So the object that can create the pop-out's view lives in the
bootstrap, before any Dart has run, and a package published to pub.dev cannot
reach it. The app has to hand it over:

const engine = await engineInitializer.initializeEngine({
  multiViewEnabled: true,
});
const app = await engine.runApp();
window.documentPipApp = app;          // the package needs this
app.addView({ hostElement: document.querySelector('#app') });

Multi-view is a property of how the engine starts. Nothing published to
pub.dev can switch it on from the inside, which is worth knowing before you go
looking for the API that does.

One trap in that snippet. Never pass document.body as hostElement. Flutter
clears a host element's children and sizes the view to 100% of it, so body
wipes your page — script tags included — and then measures zero. A blank screen
and no exception. I had that exact line sitting in an error message until the
pre-publish audit caught it — of the three copies of that snippet in the
package, the wrong one was the copy a stuck developer actually reaches, and the
only copy never run.

The window freezes exactly when you need it

Here is the good one.

You open the pop-out, switch to another tab to do the thing you opened it for,
and it stops. Frozen frame, still floating, still on top, completely dead.

The cause is a disagreement between two true statements. Chromium keeps
painting a document-picture-in-picture opener at full rate while its tab is in
the background — that is the entire point, the window has to keep working. But
it still reports the page as hidden, because by any normal definition it is:
the user is looking at another tab.

Flutter's web engine reads visibilityState: "hidden" and turns it into
AppLifecycleState.hidden. SchedulerBinding responds by clearing
framesEnabled, after which scheduleFrame() returns early forever. That is
correct behaviour and good citizenship — nobody wants a backgrounded tab
burning battery. It is also exactly wrong here, because the one surface the
user can still see is the one Flutter just stopped drawing.

Measured rather than argued, because the whole failure is about believing a
report instead of checking:

Chromium, tab in the background	browser frames	Flutter frames
no pop-out open	2 in 2.5s	—
pop-out open	302 in 2.5s	0 in 3s
pop-out open, with the fix	302 in 2.5s	311 in 3s

The browser was drawing at roughly 120fps. Flutter drew nothing.

scheduleForcedFrame() is the documented way past it — it ignores
framesEnabled and only checks whether a frame is already pending. So the root
widget re-arms it for exactly as long as both conditions hold:

void _keepPaintingWhileHidden(Duration _) {
  if (!mounted) return;
  final binding = WidgetsBinding.instance;
  if (binding.framesEnabled) return;              // page is back
  if (DocumentPip.popOutViewIds.isEmpty) return;  // last window closed
  binding.scheduleForcedFrame();
  binding.addPostFrameCallback(_keepPaintingWhileHidden);
}

Both guards end the loop on their own, which matters: this is a hand-rolled
frame pump, and one that cannot stop is a battery bug wearing the costume of a
fix. A post-frame callback rather than a persistent one for the same reason —
a persistent frame callback can never be removed, and would pin the State
forever.

And it is a Chromium problem specifically. Firefox 151 and 155 keep reporting
the opener visible with a pop-out open — 308 frames in 2.5s against 9 for the
same page without one — so framesEnabled is never cleared and that first
guard returns immediately. The workaround is gated on the failure rather than
on the browser, so where the failure does not exist it never runs.

The keyboard is dead, but typing works

The second singleton. Flutter's KeyboardBinding attaches capture-phase
keydown/keyup listeners once, globally, to the opener's window. A
picture-in-picture window is a separate browsing context with its own window,
so while it has focus the engine hears nothing.

What makes this genuinely nasty is which half breaks. Type into a text field in
the pop-out and it works perfectly — the browser routes characters to the
focused DOM element natively, and the engine reads them back off that element.
So the feature you would test first is the one that is fine.

Everything that travels as a key event is dead: Shortcuts, Actions,
Focus.onKeyEvent, HardwareKeyboard, Escape, Tab traversal. Text selection
has the same shape, since all three of the engine's selectionchange
subscriptions are on the opener's document — so moving the caret with the
arrow keys never reaches Flutter's editing state either.

The fix is to replay the events into the opener and hand Flutter's focus to the
pop-out's view when its window takes focus. Which produces its own trap worth
stealing:

// One tear-off each, kept: every `.toJS` makes a NEW JS function, so
// removing with a second one silently leaves the listener attached.
late final JSFunction _onKeyRef = _onKey.toJS;

.toJS on the same Dart function twice gives you two different JavaScript
objects. removeEventListener compares by identity, finds nothing, removes
nothing, and reports success. That is not specific to picture-in-picture — it
applies to every addEventListener you write in Dart, and it fails as a leak
rather than as an error.

Keys held when a window closes are released explicitly, too. Otherwise
HardwareKeyboard still believes they are down, and the next real press of the
same key trips its consistency assertion — a crash somewhere else entirely,
minutes later.

Two rules the browser imposes

open() must be the first await in a gesture handler. The browser only
permits this while handling a real click, and awaiting anything beforehand
spends the gesture. Load your data after:

onPressed: () async {
  final window = await DocumentPip.open();   // first
  final data = await fetchTrack();           // then
}

Get it wrong and Chrome says NotAllowedError — which it also says when you
call from an iframe, and when a window is already open. Three causes, one error
name. The package lists all three rather than asserting the common one, because
sending someone to fix a click handler that was already correct costs them an
afternoon.

One window, browser-wide. Not per tab, per browser. Opening a second closes
the first, including one belonging to a completely different site. Your window
can vanish because someone else opened theirs, so closed completes for that
too and you handle it like any other close.

What the pattern actually is

None of these are bugs in Flutter, and I want to be precise about that. Turning
frames off for a hidden page is right. Binding the keyboard once is right.
Assuming one view is right for every app that has one view, which is very
nearly all of them.

They are all the same shape of problem: a framework generalisation that holds
for every case but yours, failing in a way that produces no error. A frozen
window looks like a rendering bug. A dead shortcut looks like a focus bug —
especially when typing still works. Neither logs anything.

The only thing that actually worked was refusing to reason about it. Every
number in this post came from driving a real browser and counting frames,
because in all three cases the platform's report was true and the conclusion
drawn from it was wrong, and no amount of reading the source would have told me
which.

document_pip is MIT and on
pub.dev; the source is at
github.com/devShakib015/flutter_packages.

What It Actually Takes to Run a Cross-Border Marketplace: Six Years of Shpper

K M Shahriar Hossain — Sun, 06 Sep 2026 12:16:06 +0000

Shpper is a cross-border personal-shopping marketplace. A buyer wants something
they cannot get where they live. A traveller is already flying that route with
unused luggage space. The platform introduces them, holds the money until the
item arrives, and turns an empty few kilos in someone's suitcase into a delivery
network.

I am the CTO. I own the platform end to end — the Flutter apps for both sides,
the backend, payments and escrow, identity verification, and the release
pipeline. We are on version 14.2.0, rated 4.64 on the App Store from 72 ratings.

Fourteen major versions is enough distance to say something useful about what
this kind of product actually demands. Almost none of the hard parts were the
ones I expected.

You are not building one app

The first structural fact about a two-sided marketplace is that "the app" is two
products with opposed interests, and you ship both.

The buyer wants their item cheaply, quickly, and with certainty it will arrive.
The traveller wants to be paid well, carry as little risk as possible, and not be
blamed for customs. Those are not complementary desires. Every feature has to be
designed twice, from two points of view, and any change to the shared middle —
the request, the offer, the trip — reaches into both.

This has a consequence people underestimate: your release cadence is bounded by
the slower side. A change to how offers work is not shipped when the buyer app
ships. It is shipped when both apps are live, on both platforms, and enough of
both populations have updated. Mobile app review is not a build step you can
optimise away; it is a scheduling constraint that shapes how you design changes,
which is why so much of the logic has to be able to change without a release.

The hard problem is trust, and it is not a feature

A marketplace's actual product is trust between strangers. Everything else is
plumbing.

Consider what the platform is asking. A buyer sends money for an item that does
not exist yet, to be bought by someone they have never met, in a country they
are not in, and carried across a border. A traveller agrees to spend their own
money on someone else's goods, in exchange for a promise of repayment, and to
carry those goods through customs under their own name.

Neither side would do that for a stranger. They do it because the platform
stands between them, and everything about the engineering follows from that
position:

Escrow is not a payments feature, it is the entire trust mechanism. Money is
held from the moment a deal is struck until the item is confirmed delivered. That
single design decision is what makes the rest possible — the buyer risks nothing
until they have the item, and the traveller knows the money genuinely exists
before they spend their own.

Identity verification is what makes escrow meaningful. Held funds only
protect you if there is a real, identified person on the other end when
something goes wrong. Verification is not a compliance checkbox bolted on for
regulators; it is the thing that makes the escrow promise enforceable.

The state machine is the product. A request becomes an offer, becomes an
accepted deal, becomes a purchase, becomes a carried item, becomes a delivery,
becomes a release of funds. Every transition can fail, and each failure needs a
defined answer: what happens to the money, what each side sees, who is told what
and when. The unhappy paths outnumber the happy one, and they are where the
product either holds together or falls apart.

Money makes everything irreversible

Ordinary app bugs are annoying. Bugs that touch money are a different category,
because you usually cannot fix them by shipping a patch.

A double-charge is not resolved by correcting the code — the money has already
moved, and now there is a human on the other end who is angry and correct to be.
A payout that fires twice is gone. A state transition that releases escrow early
cannot be un-released by a hotfix.

This changes how you write things. Every money-moving operation has to be
idempotent, because networks retry and users tap twice and both of those are
normal. State transitions have to be atomic, because a partial write in the
middle of a payment is worse than a failure. And ledgers have to be
append-only — the record of what happened is not something you edit, because the
moment it is editable it stops being evidence.

None of this is exotic. All of it is the difference between a bug you fix and a
bug you refund.

Cross-border is a category of its own

Everything above applies to any escrow marketplace. Crossing a border adds
problems that are not software problems at all, and the engineering has to
absorb them anyway.

Prices move while a deal is open, because currencies move. Customs and duty are
real costs that land on somebody, and the product has to be unambiguous about who
before anyone commits, not after. Items that are perfectly ordinary in one
country are restricted in another. Trips get cancelled, delayed, or rerouted, and
a delivery network built from other people's travel plans inherits all the
volatility of those plans.

The engineering lesson is that a design which assumes stability will spend the
rest of its life being patched. Timelines slip, prices change, routes vanish.
Building for that from the start is much cheaper than discovering it across
fourteen versions.

What being CTO of this actually means

The title suggests architecture diagrams. The reality is that owning it end to
end means the boundary between "engineering problem" and "business problem" does
not exist.

When a delivery goes wrong, the question is not only what the code did. It is
what the policy should be, who absorbs the cost, what both users are told, and
what changes so it happens less often. That is one conversation, not four, and
being the person who understands both the state machine and the commercial
consequence is most of the job.

The other half is choosing what not to build. Every marketplace has an infinite
backlog because both sides always want more, and the sides want different things.
Fourteen versions in, the decisions I am most glad about are almost all
subtractions.

The stack, briefly

Flutter for both apps, so one codebase covers iOS and Android on each side —
which matters enormously when "shipping a feature" already means shipping two
products. Firebase for the backend. The choice that has aged best is not a
technology but a principle: keep as much behaviour as possible changeable
without an app release, because you cannot hotfix your way out of a marketplace
problem when app review sits between you and your users.

The thing I would tell someone starting one of these: you are not building
software that connects buyers and sellers. You are building the reason two
strangers are willing to take a risk on each other, and every technical decision
either strengthens that or quietly erodes it. Escrow, verification, and an
honest state machine are not features on a roadmap. They are the product, and
everything else is how it is delivered.

Shpper is at shpper.com, and there is a longer
case study on this site.

Your Flutter 404 Page Is Probably Crashing, and Your Server Is Probably Lying About It

K M Shahriar Hossain — Sun, 06 Sep 2026 12:16:05 +0000

Someone sent me a screenshot of my own 404 page. Washed-out grey text on a light
background, barely readable, nothing like the dark theme every other page uses.
My first thought was a styling bug.

It was not a styling bug. The page was crashing before it could paint, and the
fallback I had built for exactly that case was doing its job. Underneath it was a
second bug that had been hiding the first one for months.

Bug one: the status code was a lie

The site is a Flutter web app with every route prerendered to a real HTML file.
Firebase Hosting served those files, and anything unmatched hit a catch-all
rewrite:

"rewrites": [
  { "source": "**", "destination": "/404.html" }
]

That looks right. It is not, and the reason is worth internalising: a Firebase
rewrite always responds 200. That is what a rewrite is — serve this other
content under the requested URL. So every nonexistent URL on the site returned
200 OK with a page that said "Page not found".

Browsers do not care. Crawlers care a great deal. A 200 means "this is a real
page, index it", so every typo, every dead inbound link, every scanner probing
for /wp-admin was eligible to be indexed as a real page. This is the soft 404,
and it is invisible from a browser because the page looks correct.

The fix is to delete the catch-all rather than repoint it. With every real route
prerendered as a file, Firebase serves those directly, and for anything with no
matching file it falls through to its own handling — which serves 404.html
with an actual 404 status.

One caveat that will bite you if your app has client-only routes. My admin panel
has no prerendered file, so removing the catch-all 404'd my own admin URL. It
needs a rewrite scoped to that path alone:

"rewrites": [
  { "source": "/your-client-only-path/**", "destination": "/index.html" }
]

Scoped rewrites for the routes that genuinely need them; no catch-all; real 404s
for everything else.

Bug two: the page was crashing the whole time

Fixing the status code is what made me actually look at the page, and that is
when the grey rendering stopped looking like a theme problem.

My prerendered HTML carries the page's text in the DOM, clipped to a single
pixel, with a boot guard that reveals it if Flutter never paints. The idea is
that a failed boot shows the content rather than a spinner turning forever. So
the washed-out text was the guard firing correctly, telling me Flutter had
died.

The console had it:

GoError: There is no GoRouterState above the current context.
This method should only be called under the sub tree of a RouteBase.builder.

Here is the chain. errorBuilder renders my NotFoundPage. That page uses the
same shell as every other page, and the shell contains the nav bar, and the nav
bar asks which route is current so it can highlight the right link:

final current = GoRouterState.of(context).uri.path;

On every real route that is fine. On the 404 page it throws, because
errorBuilder renders outside any RouteBase.builder — there is no route
subtree above it and therefore no GoRouterState to inherit.

The fix that does not exist, and the one that also fails

The instinct is maybeOf. In go_router 17 there is no GoRouterState.maybeOf.
of() throws unconditionally; there is no nullable variant to fall back to.

So the next instinct is to ask the router itself, which definitely sits above
everything:

current = GoRouter.of(context).state.uri.path;   // also throws

I tried exactly this, and it fails too — differently, which is what makes it
interesting. GoRouter.state reads matches.last on the current match list, and
on an unmatched URL that list is empty, so you get a StateError: Bad state: No element. The accessor fails for precisely the reason you are on the 404 page
at all.

Both router-side answers are dead ends. But the browser knows the path regardless
of what the router made of it:

String current;
try {
  current = GoRouterState.of(context).uri.path;
} catch (_) {
  current = Uri.base.path;
}

The broad catch is deliberate, and I would defend it specifically here.
Determining which nav item to highlight is decoration. This widget renders inside
every page on the site. Failing at decoration must never be able to take down the
page around it, and the two failure modes above are different exception types
from different call sites — narrowing the catch buys nothing except a chance to
miss the third one.

Nothing highlights on a 404, which is correct: no nav item corresponds to a page
that does not exist.

Why it survived so long

Because the two bugs concealed each other. The 404 page had been broken for
months and rendered identically whether it answered 200 or 404 — so nothing
looked wrong from a browser, and nothing in the logs distinguished it. Crawlers
saw 200 and were happy. I never visited my own 404 page, because why would I.

The status-code fix did not cause the crash. It made someone look at the page,
which is a different and more useful thing.

Two habits fall out of this. Check your 404 page's status code, not just its
appearance — curl -o /dev/null -w '%{http_code}' https://yoursite/nonsense
takes two seconds and is the only way to see a soft 404. And actually load your
error page in a browser after a routing change, because it is the one page in
your app that renders through a completely different code path from every other
page, and therefore the one page your testing never touches.

A Squarified Treemap by Hand, Because Charting Packages Cannot Drill Down

K M Shahriar Hossain — Sun, 06 Sep 2026 12:15:09 +0000

Helm's storage tool shows your disk as a treemap: every folder a rectangle,
every rectangle sized by how much space it takes. Click one and you are inside
it, looking at its children, with a breadcrumb trail back out. It goes from a
494 GB volume down to a single file.

I drew it by hand. Not because the packages are bad, but because the thing that
makes a treemap useful for disk space is the part they do not expose.

What the packages give you, and what they don't

Search for a Flutter treemap and you will find several that work. Hand them a
list of values, get back a coloured rectangle layout. For a dashboard showing
revenue by region, that is the whole job.

A disk browser needs four things beyond that, and each one reaches into the
layout rather than sitting on top of it:

Hit-testing that returns the node, not a coordinate. A tap has to resolve to which folder, at whatever depth you are currently at.
Navigation as a first-class state. Diving into a rectangle re-lays out the entire canvas from a new root, and the breadcrumb has to be able to climb back.
Labels that adapt. A rectangle 400 px wide gets a name and a size. One 20 px wide gets nothing, because a clipped half-word is worse than blank space.
Layout over a subtree, not a list. The input is not fifty values, it is a tree with a million nodes, and you lay out one level at a time.

Any one of those is a fork of the package. All four means you are writing it
anyway, and you would rather own it than fight an abstraction built for a
different problem.

Squarified, and why it is worth the trouble

The naive treemap slices the rectangle repeatedly along one axis. It is easy and
it produces slivers — long thin shapes that are impossible to read, impossible
to tap, and misleading, because human eyes judge area badly when the aspect
ratio is extreme.

The squarified algorithm keeps rectangles as close to square as it can. The idea
is simple enough to hold in your head: sort children largest first, then add
them one at a time to the current row while doing so improves the worst aspect
ratio in that row. The moment adding one makes the worst ratio worse, close the
row, and start a new one in the remaining space.

That is the entire algorithm. Sort descending, accumulate greedily, close the
row when the worst ratio stops improving, recurse into the space that is left.

Two implementation notes that cost me time:

Sort descending or the greedy step is meaningless. The whole method assumes
you place the biggest item first. Feed it unsorted input and it still produces
a layout — a bad one, with no error to tell you why.

Guard against zero. Empty folders, and the remaining space after the last
row, both produce zero-width or zero-height rectangles, which turn into
divide-by-zero in the ratio computation and NaN in the layout. NaN
propagates silently through a layout pass and you get an empty canvas with no
exception, which is a genuinely unpleasant thing to debug.

Making it fast enough over a real disk

Scanning a 347 GB volume walks several hundred thousand files. Two things keep
that from freezing the UI, and neither is about the treemap itself.

Scan off the main isolate. Walking a filesystem is not CPU-heavy so much as
relentless — hundreds of thousands of stat calls. Done on the main isolate it
blocks the frame loop, and the app appears hung exactly while it is doing the
work the user asked for.

Lay out one level at a time. The tree has a million nodes; the screen shows
a few dozen rectangles. There is no reason to lay out anything but the current
level's children. Diving in is a fresh layout over a smaller subtree, which is
why it stays instant no matter how deep you go — the work is bounded by what is
visible, not by what exists.

The second point is the one that also solves the label problem. Because you only
lay out the visible level, you know each rectangle's real pixel size at paint
time, so deciding whether a name fits is a measurement rather than a guess.

The bit that has nothing to do with drawing

The hardest part of Helm's storage tool is not the treemap. It is making the
numbers agree with the operating system.

macOS reports purgeable space — snapshots and caches the system will reclaim
when it needs to. If you sum file sizes and ignore purgeable, your total
disagrees with About This Mac, and when a user sees two numbers they believe the
one from Apple. Correctly, too: yours is the one that is wrong.

So the categories have to be disjoint buckets that reconcile to the volume's
reported capacity, purgeable included as its own slice rather than quietly
dropped or quietly counted as used. A beautiful visualisation of numbers the
user does not trust is worth nothing, and trust here is a single comparison
against a system dialog they already know.

Was it worth writing?

For a dashboard, no — use a package. For anything where the treemap is the
interface rather than a picture of the data, you will end up writing it, because
drill-down, hit-testing and adaptive labels all live below the API surface that
a general charting package exposes.

The reward is that it is genuinely the fastest way to answer "what is eating my
disk". A list of the largest folders makes you read and compare. A treemap makes
the answer the biggest thing on screen.

Helm is free and MIT, and the treemap is in
lib/tools/storage/ui/widgets/treemap.dart if you want to read it rather than
reimplement it: github.com/devShakib015/helm.

The DNS Field That Could Run Anything as Root

K M Shahriar Hossain — Sun, 06 Sep 2026 12:15:08 +0000

Sonar has a Control tab. One of the things it does is switch the DNS resolver
for your Mac — tap Cloudflare, tap Quad9, or paste in the address of your own
Pi-hole. Changing a network service's DNS servers is a privileged operation, so
the app asks macOS for authorisation and runs networksetup on the other side
of that prompt.

That is a completely ordinary feature. It is also where I put a
command-injection that ran as root.

The shape of the bug

The custom-resolver field exists because people run Pi-hole and NextDNS on their
own networks, and hardcoding four public resolvers would have been useless to
them. So the field takes a string. The string goes into the arguments of a
privileged command. Between those two facts there was nothing at all.

The mental model that produced this is worth naming, because it is the one that
produces most injection bugs: it's my own app, and the field is for an IP
address, so it will contain an IP address. Both halves are wrong. The field is
for whatever the user types, and "my own app" is not a security boundary — the
whole point of asking for authorisation is that the code on the other side of
the prompt has more power than the code before it.

A privileged call is a trust boundary even when both sides are yours. Especially
when both sides are yours, because that is exactly when you stop looking.

Why "it's just a settings field" is not a defence

Two arguments came to mind while I was fixing it, and both are bad.

"The user would only be attacking themselves." Sometimes. But the value
that reaches that field does not have to be typed by the person sitting at the
machine. Anything that can put text into a field — a paste from a webpage, a
support article that says "paste this into the custom DNS box", an
accessibility-driven automation — becomes a way to run a command with elevated
privileges. Social engineering is a lot easier when the last step is paste this
string into the box and click Apply, and the app has already trained the user
to expect an admin prompt at that point.

"The authorisation prompt is the protection." The prompt authorises the
operation the app described, not whatever ends up in the argument list. The
user consenting to "change DNS servers" has not consented to anything else the
string can be made to mean. Consent obtained for one action does not cover a
different one that happens to travel through the same code path.

The fix, in the right order

The instinct is to reach for escaping — quote the string, strip the dangerous
characters, block a list of metacharacters. That is the wrong first move. Every
blocklist is a bet that you thought of everything, and you did not; that is what
a blocklist is.

Validate against what the value is allowed to be, then pass it in a way that
cannot be reinterpreted.

Allowlist the shape. A DNS server is an IPv4 or IPv6 address. That is a
tiny, completely specified grammar. Parse the string into an address type and
reject anything that does not parse — not "remove the bad characters", but
refuse the input. If it is not an address, there is no version of it that is
safe to pass along, so there is nothing to sanitise.

Never build a shell string. Pass arguments as an array to the process, so
there is no shell to interpret them and no quoting to get right. This is the
part people skip because a formatted string is quicker to write, and it is the
single highest-value habit in this whole area: if there is no shell, an
injection has nothing to inject into.

Keep the privileged surface small. The privileged side should accept the
narrowest possible instruction — "set the resolvers for this service to these
validated addresses" — not a command to run. The less expressive the interface
across the trust boundary, the less there is to abuse.

Those three in that order. Validation is the fix; the array-argument call is the
belt; the narrow interface is the braces.

The other twenty-five

I found this during a full pass over the app before shipping version 2, which
turned up twenty-six fixes. Three others are worth repeating because they are
the same category of mistake wearing different clothes.

Credentials in a plist. NextDNS and Pi-hole integrations need API tokens.
They were sitting in preferences, which is a plain file that any process running
as you can read, and which gets swept into backups and sync. They belong in the
Keychain, which is the one place on macOS designed to hold them. That is not a
hard fix; it is a fix nobody makes until they look.

CSV export as an attack. Sonar exports the network map. A device name is
attacker-controlled — anyone on your network can name their device. If a name
starts with =, a spreadsheet treats it as a formula when the file is opened.
Export is a place where your data becomes someone else's input, and that
direction gets almost no attention compared to import.

Corrupt-safe writes. The device history was written in place. A crash or a
full disk mid-write left a truncated file, and the next launch would read it,
fail, and start empty — silently destroying months of history. Writes are now
atomic, and a file that fails to parse is preserved rather than overwritten. The
distinction matters: losing data is bad, but losing it quietly means nobody
finds out until they need it.

What I would tell myself a version earlier

None of these were exotic. Every one is in the first chapter of anything written
about the subject, and I still shipped them, in a tool whose entire premise is
that it tells you when your network is exposed.

The reason is not ignorance, it is attention. Features get scrutiny while you
build them and then never again. The DNS field was written in an afternoon,
worked immediately, and was never reopened, because working code does not ask
for anything. A settings field that has never failed is the safest-feeling code
in the project and one of the most dangerous.

So the practice that actually helps is not a checklist. It is a question, asked
of the code you are least worried about: where does user input cross into
something with more power than the code that received it? Find those crossings
and look at every one, especially the boring ones you wrote in an afternoon and
never thought about again.

Sonar is free and open source under MIT, and all of this is in the history if
you want to read the diffs rather than take my word for it:
github.com/devShakib015/sonar.

Saving a Real File From Flutter Web, Instead of Downloading Another Copy

K M Shahriar Hossain — Sat, 05 Sep 2026 23:32:13 +0000

Build an editor on Flutter Web. The user opens budget.csv, edits it, hits
save. They get budget.csv in their Downloads folder.

They edit again, save again: budget (1).csv.

Again: budget (2).csv.

Their real file — the one on their Desktop that they opened — has never been
touched. By the end of an afternoon they have nine numbered copies and no idea
which is current. This is not a Flutter problem; it is what "saving" has meant on
the web for twenty years. The browser hands you a download, and a download is
always a new file.

The API that changed this

The File System Access API gives a page a real handle to a real file, with
the user's permission, granted through the browser's own picker. With a handle
you can write back to the same file. Not a copy. That one.

It is a genuine capability, gated properly: the user picks the file, the browser
mediates every access, and the permission can be revoked. There is no way for a
page to reach a file the user has not deliberately handed over.

final file = await FileSystemAccess.openFile();
await file.write(bytes);   // the same file, in place

No download. No (1). The file on their Desktop now has their edits.

Why the old way works the way it does

The download-a-copy behaviour is not laziness on anyone's part. For most of the
web's history, a page having write access to your filesystem would have been an
enormous security hole, so the only sanctioned direction was out: the page
produces bytes, the browser saves them somewhere the page cannot see or reach.

That is why <a download> and the blob-URL trick that every Flutter Web file-save
snippet uses cannot ever overwrite. They are not writing a file. They are handing
the browser a payload and asking it to save one, and "save one" means a new one.

Understanding that is what tells you the File System Access API is a genuinely
different mechanism rather than a nicer wrapper over the same thing. The
permission model changed; the API followed.

Coming back after a reload

The second half is what makes it feel like an application rather than a web page.

Handles can be persisted. Store one, and after a page reload — or the next
morning — you can ask for that same file again. The browser will re-prompt for
permission, which is correct and is the point, but the user is confirming access
to a file they already chose rather than hunting through a picker to find it
again.

That single behaviour is the difference between "a web tool I paste things into"
and "the thing I edit my file with".

Handles are stored in IndexedDB — they are structured-cloneable objects, not
strings — so they persist like any other browser data and survive until the user
clears site data. Which means the recovery flow is:

On startup, look for a stored handle.
If there is one, ask whether permission is still granted.
If it is, open silently and show the document.
If it is not, show one button: Reopen budget.csv.

Step four is the honest version of "restore my session". You are not
re-prompting for a file the user must find again; you are asking them to confirm
a file you both already know about.

Directories, not just files

The same API grants handles to whole directories. That unlocks a different class
of application entirely — a project folder, a photo set, a folder of Markdown
notes — where the app can enumerate, read and write within the folder the user
chose, and nothing outside it.

For anything resembling an editor, that is the difference between a single-file
toy and something people keep their work in.

What you must handle

This is where an honest package earns its keep, because the API is not
universally available and pretending otherwise produces a broken app on a third
of browsers.

Support is real but partial. Chrome, Edge and other Chromium browsers have
it. Safari and Firefox largely do not. So the capability check is not optional
housekeeping — it decides which UI you show:

if (await FileSystemAccess.isSupported) {
  // "Save" — writes in place
} else {
  // "Download a copy" — the old behaviour, honestly labelled
}

Label the fallback accurately. A button that says Save and silently produces
budget (3).csv is worse than a button that says Download a copy, because the
first one lies about what just happened.

Permission is per-handle and revocable. A write can fail because the user
revoked access, or the file moved, or the browser dropped the grant. Handle it as
a normal outcome rather than an exception path you never test.

It needs a user gesture. The picker cannot be opened from a timer or an
async continuation far from a tap. Open it directly in the button handler.

Design for the fallback, do not bolt it on

The temptation is to write the good path and add a fallback later. That produces
an app whose Safari experience is an afterthought, and Safari is not a rounding
error.

A structure that works: define one interface with open, save and saveAs.
Implement it twice — once over the File System Access API, once over the classic
picker-and-download. Choose at startup. The rest of your app never branches, and
the difference is confined to which implementation is behind the interface and
what the save button says.

The label matters more than it sounds. If the fallback button says Save and
produces budget (3).csv, the app has lied about what it did. If it says
Download a copy, the user understands the platform limitation immediately and
does not blame the app when their original file is unchanged.

Why this matters more on Flutter Web than elsewhere

Flutter Web is unusually good at the kind of app this unlocks — editors,
spreadsheets, diagram tools, code playgrounds, anything with a document. Those
are exactly the apps where "download another copy" is most obviously wrong.

It is also the gap people cite when they say Flutter Web "isn't ready for real
apps". Not being able to save a file properly is a fair thing to hold against a
platform. It is no longer true, on the browsers that matter, and it is worth
knowing.

A note on security, since people ask

Every time this API comes up someone asks whether a web page can now read their
whole disk. It cannot, and the reasons are worth knowing so you can answer the
question when a user asks you:

Every handle comes from a user gesture through the browser's own picker. A page cannot construct a handle to a path it names.
Access is per-handle. Being granted budget.csv grants nothing about the folder it sits in, or any other file.
The browser blocks sensitive locations — system directories, and in Chromium's case a maintained blocklist that includes things like the user's home root and library folders.
Permission is revocable and is re-confirmed after a reload rather than granted permanently in the background.
It requires a secure context. No HTTPS, no API.

The design is closer to "the user hands your app a file" than to "your app gets
filesystem access", which is the right shape for a capability this significant.

Try it

file_system_access is on pub.dev — MIT, 160/160
pub points. It wraps the picker, the in-place write, the persisted handle and the
capability check.

It returns false from the capability check on browsers that cannot do this,
rather than throwing or half-working — so your fallback is a decision you make at
startup rather than a crash you discover from a Safari user three weeks after
launch.