Found while verifying the #1803 fix against a real app (bughq). The #1803 fix works — the color-mode boot script is now ahead of the stores bundle. But there is a second, independent pre-paint theme system that is emitted before it, does not know it exists, and disagrees with it about both the storage key and the mechanism.
Two injectors, no shared contract
site-builder/theme.ts | color-mode-boot.ts | |
|---|---|---|
| marker | data-stx-theme-guard | data-stx-color-mode-boot |
| config source | site.theme | app.colorMode |
| storage key | opts.storageKey ?? 'theme' | configured (bughq_theme) |
| mechanism | classList.add/remove('dark') | setAttribute('data-theme', …) |
| default | opts.default ?? 'dark' | initialMode |
| also emits | a document-level click handler for #theme-toggle | — |
injectThemeBootstrap (packages/stx/src/site-builder/theme.ts:120) is guarded only by
"is it already in the HTML":
if (!html.includes('__stxThemeGuard') && /<head\b[^>]*>/i.test(html)) {
const guard = `<script data-stx-theme-guard="1">${FOUC_SCRIPT(defaultTheme, storageKey, lightColor, darkColor)};window.__stxThemeGuard=1;</script>`
html = html.replace(/<head\b([^>]*)>/i, `<head$1>\n ${guard}`)
}So an app that configures app.colorMode and never configures site.theme still gets the
legacy guard, running on defaults it never chose. That is the bughq case: config/ui.ts
sets app.colorMode to { storageKey: 'bughq_theme', attribute: 'data-theme', darkClass: null }
and sets no site.theme at all. Both scripts ship on every page.
The FOUC guard causes the FOUC
Because the guard reads localStorage['theme'] — a key nothing in the app ever writes —
read() always takes the t === null branch and resolves to the 'dark' default. It then
puts class="dark" on the root element at the very top of <head>, before anything else
runs.
Measured on /login with a stored preference of light (bughq_theme=light), recording
every attribute mutation on the root element from a script installed before any page script:
class="dark" ← legacy guard, byte 63. Wrong.
data-theme="light" ← color-mode boot. Correct.
data-theme="light"
data-theme="light" ← applied 3× total
class="" ← wrong class removed only after hydrationThe root element carries the wrong theme class from first paint until hydration completes.
bughq happens not to render differently for it (0 dark: utilities, no .dark selector),
so there is no visible flash here — but .dark on the root element is the default
dark-mode strategy for Crosswind/Tailwind-style utilities, and for any app using it this is
a dark flash on every load for every light-preference user. Which is the exact thing the
guard exists to prevent.
Worth noting data-theme is written three times where once would do.
It also pushes <meta charset> out of the spec budget
The #1803 commit deliberately hoisted <meta charset> because "moving the ~800-byte boot
script above it would have pushed the encoding declaration out of the spec's
first-1024-bytes budget". That hoist works against the color-mode boot script — but the
theme guard is injected at head-open too, is ~1.75KB, and lands ahead of it.
Measured byte offsets in the served /login document:
data-stx-theme-guard → 63
<meta charset> → 1819 ← past the 1024-byte limit
data-stx-color-mode-boot → 1852<meta charset> at byte 1819 violates the HTML spec requirement that the character
encoding declaration appear entirely within the first 1024 bytes. So #1803's hoist is
currently defeated by an injector that runs earlier than the one it was written against.
Repro
Any app that configures app.colorMode and not site.theme:
app.colorMode = { storageKey: 'myapp_theme', attribute: 'data-theme', darkClass: null }- Load any page,
localStorage.setItem('myapp_theme', 'light'), reload. - Root element gets
class="dark"pre-paint, then loses it after hydration. <meta charset>sits past byte 1024.
Suggested direction
Flagging rather than fixing, since the ownership question is a design call:
- (a) Make the two systems one.
app.colorModeis the configured, attribute-based, documented path;site.themepredates it. Ifapp.colorModeis configured, skipinjectThemeBootstrapentirely — that alone fixes the wrong class, the charset offset, and the dead 1.75KB. - (b) If both must coexist, have
injectThemeBootstrapreadapp.colorModeforstorageKey/darkClass/defaultso they cannot disagree, and inject after charset. - (c) At minimum, re-assert the charset hoist after
injectThemeBootstrapthe same way #1803 re-asserts the boot script position after all injectors — ordering injectors pairwise is what #1803's commit message already argues against.
(a) seems right to me: the emitted guard in bughq reads a key nothing writes, toggles a
class no stylesheet uses, and registers a document click handler for #theme-toggle,
which does not exist in the app. It is pure render-blocking weight on every page.