~jisifu

notebook · envs.net
no framework, no fonts

post3 minprotocolsgemtextpublishingmeasurement

Progressive enhancement, measured

I used to think progressive enhancement was a stance: build the plain thing, then add the nice thing if the client can take it. Having now shipped one text to four protocols, I think it is a measurement. A page either survives being flattened or it does not, and the flattening can be run on every build.

The flattening#

text.py converts the same markdown into gemtext, gopher menus and a finger plan. The loss is specific and worth naming:

  • a table becomes one line per row, columns separated by spaces
  • bold and italic disappear entirely
  • every link moves to a line of its own, and the sentence that referenced it now points at nothing in particular
  • images become a => line or vanish

Those are not bugs to fix. They are the protocols being honest about what they carry, and they are a useful test: if a paragraph only works because a hover state explained it, the paragraph was not carrying the meaning.

The numbers, because this is a pubnix#

shared CSS + JS, gzipped 6.2 KiB, cached once
page budget 14 KiB, per page, enforced by an assertion
pages over budget 0
JavaScript required to read a page none

The budget is the part that changed my habits. Fourteen kilobytes is generous for prose and tight for a page that wants to be an application, so it forces the question early: is this page text, or is it a tool? The site has exactly one of the second kind — /lab/ — and it pays for itself in bytes that are accounted for: about 6 KiB of HTML, a 6.8 KiB script, and two wasm modules of 512 and 213 bytes.

Compare that to one screenshot of the same demo, which would be the cheapest honest alternative and still larger.

Where this went wrong before#

Two years of notes assumed that a text-only protocol meant an ascetic one. It does not. It means every ornament has to be describable in text, which is a harder and more interesting constraint than “no images”.

I spent a while on emoji as a fallback for icons — the moon phases as a spinner, 🌘🌗🌖🌕🌔🌗🌒 — because emoji are the one visual vocabulary every terminal and browser agrees on. The demo never shipped. The spinner became a benchmark: an actual number about how long a render takes, printed as text, is more useful to a reader than an animation that suggests work is happening.

jp2a was the same lesson from the other direction. It renders a JPEG as ASCII (github.com/cslarsen/jp2a), it installs from source, and it works — but the output is a picture of a picture, and the resolution you want depends on a terminal width you do not control. Text that is about something beats text that merely resembles it.

What the constraint buys#

Every page here is static HTML produced by a build that also produces its gemtext and gopher versions, so a page that reads badly over gopher is caught before it is published. The week I stopped treating Gemini as a stylistic choice and started treating it as a second rendering target, the web version got better too: shorter paragraphs, fewer referents that only work with a mouse, tables that state their columns.

That is the whole argument. Progressive enhancement is not a way to be nice to old browsers. It is a compiler that refuses to let your prose depend on layout — and the compiler runs in 0.60 s, on every build, whether you asked for it or not.