Offline access with File / Save As

From Red Blob Games's Blog

One of my low priority goals for my site is to make my pages work offline. I had looked into "web manifests" but they seem more suited for web apps and not for documents like mine. So I looked at what it would take to make File→Save As work, preserving interactivity. It turns out it does not work in general on my site. Why?

I tried to make the original HTML + JavaScript should work offline in the sense that they only access resources on the current server and not from any CDN, Google Fonts, etc. So if you save the HTML + JavaScript it should work on a local web server. However, File→Save As doesn't work this way!

The browser saves the HTML after it has been modified by running Javascript. But that HTML contains the modified HTML without the event handlers or JavaScript variables. When you load the saved page, it re-runs the JavaScript, and that will modify the HTML again. Unless that code is carefully written, you can end up with two of some things, and some errors when the code can't handle two of something.

The property we want is idempotency. When the code runs a second time, it should produce the same results as it did the first time it ran.

I think it's too much work to expect idempotency on most of my pages. The Hexagons guide is the main place I thought it'd be useful for someone to have an offline copy, and fortunately most of that page was ready for idempotency, because I used Vue with server-side prerendering. It turns out my A* Introduction was mostly idempotent, so I made the rest of it idempotent.

Unfortunately it's fragile. Even if they're idempotent now, it would be easy for me to miss something in a future update and lose the idempotency. I could run Save As in a script and do some testing, but it turns out the output HTML is not actually the same the second time. It's functionally the same but I can't test it with a simple string compare. I could either run some kind of in-browser test that simulates clicks and other interactions, or I could run a textural diff on the HTML and make exceptions for all the things the browser changes during Save As.

I think the number of people who use Save As is going to be small enough that it's not setting up a lot of infrastructure to test this. :-( It'll be nice when it works but it's just not worth it.

I also discovered a few other things during this mini project:

1. Browsers will not load ES6 modules from file:// urls. This is unfortunate. To make the A* page work, I had to compile my ES6 module code into non-module code using esbuild (which I love!). But I really don't like that browser makers are limiting some features to having the correct mime types, or not working on file:// urls, or requiring https. All these limit what locally saved file:// pages can do.
2. Browsers will only save resources in subfolders, not in parent folders. This is reasonable. But since I share code across pages on my site, that code didn't get saved, and that broke the interactivity. For the hex and A* pages I ended up restructuring some files so that they would get saved.
3. Links within the page like <a href="#foo"> don't get saved property in Chrome or Safari. Those browsers rewrite the links to point back to the original site. Firefox saves them as local links. So I recommend if you want to save an offline copy, use Firefox.

Unfortunately this was all a distraction. I sometimes fall into this trap of doing something low value but easier in order to procrastinate doing something high value but harder. I think it was far lower value than making my pages printable to PDF, as I think PDF is probably a better solution for offline access than relying on the browser's Save As feature. And even that was pretty low value. Putting the pages on GitHub would be better, but my pages are so tangled together that I will have to solve several issues to make that work.

In good news, as part of this project I shrunk the JavaScript down to 15k, and delayed diagram rendering until the page has loaded. This sped up page loading some more. Try going to my home page and clicking the A* Introduction link. Does it load fast for you?

I want to shift gears and work on something unrelated to my tutorials, but I keep falling into these rabbit holes. It's easier to go improve an existing page than to start something unfamiliar and new.

Labels: making-of