Skip to content

Themes: each one built into a single, versioned file - #320

Merged
rdrake merged 4 commits into
developfrom
theme-build
Nov 21, 2026
Merged

rdrake merged 4 commits into
developfrom
theme-build

Conversation

@rdrake

@rdrake rdrake commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Item 1 of the theme-structure review. Each theme used to load as a chain of @imports fetched one file at a time (frost → cobalt → coffee → day), unminified and unversioned. Now the build makes each one a single file.

What changes

  • One file per theme (vite.config.mts bundleTheme).
    • The build inlines each @import chain the way the browser would: every import in place, under its media condition, as many times as it is imported.
    • It then runs Lightning CSS for the bundle's browser targets, minified in production. ps goes from 188 KB in three files to 94 KB in one.
    • The build fails on a leftover @import, an import cycle, or a rule Lightning CSS can't read.
  • Not Lightning CSS's bundle(). It keeps a file that is reached twice only once, under the first condition alone. That dropped day.css's window frame from macos.css in light mode, because macos imports coffee for dark and creama (which imports coffee again) for light.
  • Versioned links. Theme links carry the build in their query: helpers/themeHref.ts, index.html, and the pre-boot loader, which reuses index.html's query.
  • Offline. The service worker precaches every theme under that version. Before, an update evicted the theme in use, and the next offline start had no theme.
    • One theme that fails to fetch no longer ends the install; the failure is logged.
    • Offline, the exact URL is tried first, then any cached build's copy of the same theme, so a tab still on the previous deploy keeps its theme.
    • A theme's own assets (ps's fonts and scene art) are still cached only when the page fetches them.
  • Scenarios compare the theme link without the query.

Verification

  • pnpm test passes (lint, typecheck, mocha).
  • New build tests:
    • no @import left in any built theme;
    • macos has day's frame in both its dark and light halves;
    • every theme is precached;
    • index.html links themes/coffee.css?v=<token>;
    • the pre-boot loader keeps that query.
  • New service worker tests: the offline exact-then-any-version lookup, and an install that waits for the theme fetches.
  • Computed styles were compared in Chromium between the raw source themes and the built ones, for all 20 themes, light and dark, on a chat page. The only difference is the --lightningcss-light/dark variables that Lightning CSS adds.
  • Two review rounds; their findings are fixed here.

Not done

  • ps's fonts and scene art are not precached, so a first offline start in ps has the stylesheet but uses fallback fonts and shows no scene.
  • The production worker's precache list and the cascade of a built theme are covered by the build tests, not by a worker test against the production build.

@rdrake
rdrake marked this pull request as ready for review November 21, 2026 01:58
A theme is authored as plain CSS that @imports the theme it builds on, and
the browser fetched that chain one file at a time (frost, cobalt, coffee,
day), unminified and unversioned. The build now inlines each chain as the
browser would, every import in place under its media condition, then runs
it through Lightning CSS for the bundle's browsers, minified in production
(ps: 188 KB in three files becomes 94 KB in one). It fails on an @import
left over, a cycle, or a rule it cannot read. Lightning CSS's own bundler
is not used: it keeps a file reached twice once, under the first condition
only, which dropped day.css's window frame from macos.css by light.

The link carries the build in its query (helpers/themeHref.ts, index.html,
the pre-boot loader), and the service worker precaches every theme under
it, so an update no longer evicts the theme in use and leaves an offline
start without one. Scenarios compare the link without the query.
…d fetch no longer ends the install

Offline, a theme stylesheet is matched without its ?v=, so a tab left open
across a deploy (asking for its own build's version, or none) still gets
the new build's copy of that theme. The precache waits for every path to
settle, so a theme the network drops cannot let skipWaiting() sweep the
last complete cache while the shell is still being written. The docs give
the one @import form the build inlines, and pwa.md the new precache.
Offline, a theme stylesheet is looked up by its exact URL first; only a
miss falls back to the same theme under any ?v=. The docs say how a
theme's @import chain is inlined and what the build accepts.
@rdrake
rdrake merged commit 9b7580c into develop Nov 21, 2026
12 checks passed
@rdrake
rdrake deleted the theme-build branch November 21, 2026 03:25

This branch was previously deployed

1 inactive deployment
github-pages — 5198bc7a Deployed Nov 21, 2026 by rdrake via deploy #1387
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant