useColorMode's option resolution cannot express an explicit null coming from
app.colorMode, which is the one path the pre-paint boot global exists to serve.
The code
packages/stx/src/signals.ts, inside useColorMode:
// Explicit-undefined checks rather than ||, so an explicit darkClass:null
// or attribute:null opts out instead of falling through to the default.
function pick(a, b, fallback) {
if (a !== undefined) return a;
if (b !== undefined && b !== null) return b; // <-- rejects null
return fallback;
}
var storageKey = pick(options.storageKey, boot && boot.storageKey, 'stx-color-mode');
var initialMode = pick(options.initialMode, boot && boot.initialMode, 'auto');
var darkClass = pick(options.darkClass, boot && boot.darkClass, 'dark');
var attribute = pick(options.attribute, boot && boot.attribute, null);a is the call-site option, b is window.__STX_COLOR_MODE__ (published from
app.colorMode). The comment's promise — an explicit null opts out — holds for a and
not for b. A null in the boot payload is treated as "unspecified" and falls through to
fallback.
The asymmetry is easy to miss because it only bites where fallback is non-null:
attribute: null→ fallback isnull→ looks like it worksdarkClass: null→ fallback is'dark'→ silently becomes'dark'
Why it matters
The boot global exists precisely so a bare useColorMode() agrees with the app's config
(the comment right above pick says so). But config is exactly the path that cannot say
null. To opt out of the dark class you must repeat the option at every call site — which
defeats the single-source arrangement the global was added for.
Repro
// config/ui.ts
app.colorMode = {
storageKey: 'myapp_theme',
attribute: 'data-theme',
darkClass: null, // "do not manage a class; my CSS selects on the attribute"
initialMode: 'auto',
}const cm = useColorMode() // bare — the intended usageObserved: the root element gets class="dark" added and removed as the mode changes.
Expected: no class is touched; only data-theme changes.
Passing useColorMode({ darkClass: null }) at the call site works, confirming it is the
b branch and not the config plumbing.
Verified in a real app: config/ui.ts sets darkClass: null, and the root element is
still class-managed, because an auto-bundled useDark() calls through bare. The boot
script itself serializes the value correctly ({"darkClass":null,…} is present in the
emitted payload) — it is only pick that drops it.
Fix
The boot payload is generated by stx and always contains every key, so absence and
explicit-null are already distinguishable — b !== undefined is sufficient:
function pick(a, b, fallback) {
if (a !== undefined) return a;
if (b !== undefined) return b;
return fallback;
}If a boot payload could legitimately carry null meaning "unset", the alternative is to
omit those keys when serializing rather than emit null, so undefined remains the single
"unspecified" signal on both branches.
Worth a test asserting darkClass: null in app.colorMode leaves classList untouched —
that is the case that currently passes at the call site and fails through config.