12 · Seven versions of one file

The script running in the browser's background is the most treacherous element in the whole stack. It went through seven versions, mostly within a single session, and each fixed a problem that only became visible once the previous one was fixed.

The final division of strategies is this. Page navigation: network first, and cache only when there is no network. That way an online reader always sees fresh content and an offline one gets the last known version. Built assets and images: cache first, because their names contain a hash of their contents — a new version means a new name, so an old copy is never stale.

That second rule is more important than it looks. The entire correctness of the mechanism rests on the file name changing together with its contents. If assets had fixed names, a cache-first strategy would serve old code indefinitely.

The hardest part turned out not to be offline mode itself but moving between subpages without a reload when there is no network. The application then fetches code fragments on demand, and those fragments were not always in the cache. A hard reload worked, an in-place transition did not.

The solution — and we say this plainly, because it is a workaround rather than a removal of the cause — is an automatic page reload in the error handler, guarded against looping. For the reader the effect is right. For us it is a debt recorded in a code comment. That same mechanism came back to us a few weeks later in an entirely different role, which has its own entry in the other series.