TerraFirma is a GNOME Shell extension that puts the actual sky over your wallpaper. Not a loop of a starfield: the real positions, computed from an ephemeris for your latitude, longitude and clock. Saturn appears at nineteen arcseconds with its rings part-open, because that is where the rings are this decade.
It is drawn underneath the icons and the dock. That is the whole design constraint, and it is a harsh one. A window that stutters is a window with a bug. A wallpaper that stutters is a broken desktop.
The problem was not the maths
The projection ran inside extension.js. That file imports
resource:// modules: the ones that only exist inside a running GNOME Shell
session. Which means you cannot execute it anywhere else. Which means you
cannot time it.
I could measure the whole desktop feeling sluggish. I could not measure which part was costing what, because the only way to run the code was to run the entire shell around it.
So the hot loop moved out into skymath.js, with one rule: it imports nothing
from GNOME Shell. Only gi://, which plain gjs also has. The file now runs
standalone from a terminal.
That is the entire trick, and it is not an astronomy trick. A boundary drawn
for testability is worth more than the code it separates. The same rule shows
up in PANTHEON as a purity lint: pantheon-core may not import from the app
layer, enforced by an AST test that fails CI with PURITY VIOLATION. Different
language, different domain, identical reasoning, if a thing can only run
inside its cathedral, its cost is a guess forever.
What fell out of it
Once the astronomy was standalone, it stopped being extension code and started being a library. Three packages came out, all MIT, all on npm:
- skymaths, positional astronomy with no dependencies
- starwheel: a live planisphere for your terminal
- braillecanvas: a braille framebuffer, 2×4 dots per character cell
That is the same pattern as the six components extracted from PANTHEON. Build the thing, find the piece that is genuinely reusable, take it out, publish the limits with it.
The bug that only an almanac could find
skymaths had a Delta T model: the difference between the Earth's actual
rotation and uniform time. The Espenak–Meeus 1900 polynomial it used is
published for 1900–1920 only, and it was being applied to 1986. Outside its
domain a cubic does what cubics do: it gave -534 seconds for 1950 against a
measured +29, and ran to -5163 seconds, about eighty-six minutes —
further out.
Nothing in the test suite noticed. It could not: every test compared the library against the library. The suite was self-consistent and confidently incorrect.
It was found by checking a computed sunrise against a published almanac. An external source, with no shared assumptions.
That is the lesson I keep relearning in every domain I work in this year. Checking code against itself finds typos. Checking it against something outside the program: an almanac, a hostile input, a rival implementation, the built bundle, the rendered pixels, finds the bugs that matter.
A postscript on the same fix twice
starwheel and braillecanvas both had a line-drawing routine that hung
forever on a non-finite endpoint. Same symptom, same author, one afternoon.
They got different fixes. braillecanvas clips the line properly
(Liang–Barsky). starwheel bounds the iteration count instead.
Not laziness: the clip changes which pixels are drawn at the edges, and
starwheel had published output that people's terminals already rendered.
The correct fix and the correct fix for a released library are not always the
same fix, and pretending otherwise is how a patch release breaks somebody's
screen.
TerraFirma is GPL-2.0. The three packages are MIT. All of it is on /work.html.