@ultimat3/ui 23.0.0 → 24.0.0

package/src/theme/brand.ts

@@ -72,10 +72,11 @@ export function defineTheme(input: BrandInput): Brand {
   // `html[data-theme]`. A brand that only wrote `:root` would lose to those attribute rules on
   // specificity, so every level it emits is answered here, in the same order.
   if (light.length > 0) blocks.push(rule("html[data-theme='light']", light));
-  if (dark.length > 0) {
-    blocks.push(`@media (prefers-color-scheme: dark) {\n${indent(rule(':root', dark))}\n}`);
-    blocks.push(rule("html[data-theme='dark']", dark));
+  const media = darkMediaDeclarations(input.colors);
+  if (media.length > 0) {
+    blocks.push(`@media (prefers-color-scheme: dark) {\n${indent(rule(':root', media))}\n}`);
   }
+  if (dark.length > 0) blocks.push(rule("html[data-theme='dark']", dark));
 
   return Object.freeze({ css: blocks.join('\n\n') });
 }
@@ -111,6 +112,24 @@ function indent(block: string): string {
     .join('\n');
 }
 
+/**
+ * The dark media `:root` must answer every role the brand's own `:root` touched. That `:root`
+ * (light) comes after `theme.scss`'s dark media `:root` at equal specificity, so a role overridden
+ * in light only would otherwise reach an OS-dark document with no `data-theme` — scripting off, or
+ * storage throwing in the boot script — on the dark palette it was never measured against. Such a
+ * role is answered with the SHIPPED dark channels. Called after both scopes were validated.
+ */
+function darkMediaDeclarations(colors: BrandInput['colors']): string[] {
+  const out: string[] = [];
+  for (const role of COLOR_ROLES) {
+    const value =
+      colors?.dark?.[role] ??
+      (colors?.light?.[role] === undefined ? undefined : colorTokens.dark[role]);
+    if (value !== undefined) out.push(`--color-${role}: ${value};`);
+  }
+  return out;
+}
+
 /**
  * Ordered by the canonical role list, not by the caller's object — a brand file rendered twice
  * must be byte-identical, or every consumer's CSP hash and diff churns for nothing.

package/src/theme/theme.ts

@@ -1,6 +1,6 @@
-// Theme resolution. One rule: an explicit choice in storage wins, otherwise the
-// OS decides. Every side effect goes through an injected `ThemeEnv`, so this is
-// testable without a DOM and reusable on the server.
+// Theme resolution. One rule: an explicit choice in storage wins, then the theme the boot script
+// already stamped on the document, then the app's `theme.defaultMode` (the OS for `'system'`). Every side effect
+// goes through an injected `ThemeEnv`, so this is testable without a DOM and reusable on the server.
 
 import { invalidThemeError, runtimeMissingError } from '../errors';
 import type { Theme } from '../tokens/tokens';
@@ -9,11 +9,18 @@ export type { Theme };
 
 export const THEME_STORAGE_KEY = 'ultimate.theme';
 export const THEME_ATTRIBUTE = 'data-theme';
+/** Where the boot script records `theme.defaultMode` itself — `'light'`, `'dark'` or `'system'`.
+ *  `@ultimat3/render`'s `themeScriptBody` writes `${attribute}-default`; this is that name. */
+export const THEME_DEFAULT_ATTRIBUTE = `${THEME_ATTRIBUTE}-default`;
 export const THEME_MEDIA_QUERY = '(prefers-color-scheme: dark)';
 
 /** The host capabilities theme control needs. Injected so tests need no DOM. */
 export interface ThemeEnv {
   read(): string | null;
+  /** The theme the document carries right now — what the boot script stamped, or the last apply. */
+  current(): string | null;
+  /** The app's `theme.defaultMode` as the boot stamped it, or `null` when no boot ran. */
+  appDefault(): string | null;
   write(value: string): void;
   remove(): void;
   prefersDark(): boolean;
@@ -40,9 +47,25 @@ export function osTheme(env: ThemeEnv): Theme {
   return env.prefersDark() ? 'dark' : 'light';
 }
 
-/** Resolution order: explicit stored choice -> OS preference. */
+/**
+ * What "no explicit choice" means for this app: its fixed `theme.defaultMode` when it has one, the
+ * OS when it is `'system'` or unknown. Clearing a choice and following the OS both answer this, so
+ * an app that opens dark is never flipped light by an OS change or a "system" pick.
+ */
+export function defaultTheme(env: ThemeEnv): Theme {
+  const fixed = env.appDefault();
+  return isTheme(fixed) ? fixed : osTheme(env);
+}
+
+/**
+ * Resolution order: explicit stored choice -> the theme on the document -> OS preference. The
+ * middle step is the app's default: with `theme.defaultMode: 'dark'` the boot script stamps dark
+ * on a light-OS machine, and answering the OS here made the first toggle write the theme already
+ * on screen — a click that did nothing.
+ */
 export function resolveTheme(env: ThemeEnv): Theme {
-  return storedTheme(env) ?? osTheme(env);
+  const current = env.current();
+  return storedTheme(env) ?? (isTheme(current) ? current : defaultTheme(env));
 }
 
 /** Run once on load. Idempotent — safe after the inline head script. */
@@ -60,10 +83,10 @@ export function setTheme(theme: Theme, env: ThemeEnv = browserThemeEnv()): Theme
   return theme;
 }
 
-/** Forget the explicit choice and follow the OS again. */
+/** Forget the explicit choice and return to the app's default (the OS, for `'system'`). */
 export function clearTheme(env: ThemeEnv = browserThemeEnv()): Theme {
   env.remove();
-  const theme = osTheme(env);
+  const theme = defaultTheme(env);
   env.apply(theme);
   return theme;
 }
@@ -74,12 +97,12 @@ export function toggleTheme(env: ThemeEnv = browserThemeEnv()): Theme {
 }
 
 /**
- * Follow the OS live — but only while the user has made no explicit choice.
- * Returns an unsubscribe so a component can drop it on cleanup.
+ * Follow the OS live — but only while the user has made no explicit choice AND the app's default
+ * is the OS. Returns an unsubscribe so a component can drop it on cleanup.
  */
 export function watchOsTheme(env: ThemeEnv = browserThemeEnv()): () => void {
   return env.observeOs(() => {
-    if (storedTheme(env) === null) env.apply(osTheme(env));
+    if (storedTheme(env) === null && !isTheme(env.appDefault())) env.apply(osTheme(env));
   });
 }
 
@@ -94,6 +117,8 @@ export function browserThemeEnv(): ThemeEnv {
   const media = window.matchMedia(THEME_MEDIA_QUERY);
   return {
     read: () => safeStorage(() => window.localStorage.getItem(THEME_STORAGE_KEY), null),
+    current: () => document.documentElement.getAttribute(THEME_ATTRIBUTE),
+    appDefault: () => document.documentElement.getAttribute(THEME_DEFAULT_ATTRIBUTE),
     write: (value) => safeStorage(() => window.localStorage.setItem(THEME_STORAGE_KEY, value)),
     remove: () => safeStorage(() => window.localStorage.removeItem(THEME_STORAGE_KEY)),
     prefersDark: () => media.matches,

package/src/theme/inline-script.ts

@@ -1,49 +0,0 @@
-// The blocking <head> snippet that kills the flash of wrong theme. Built from the
-// same constants as theme.ts so the two can never disagree. Server/build-only:
-// the hash is computed with Bun's hasher for the CSP header.
-//
-// DEPRECATED `As of 20.2.0`: the framework's boot inlines this script itself, from
-// `@ultimat3/render`'s `themeScript({ fallback })` with `theme.defaultMode` in `app.config.ts` as
-// the fallback, and admits it to the CSP — an app no longer writes either half. This module stays
-// exported for one major so an app that inlined it by hand keeps building; it is removed in 21.
-
-import { runtimeMissingError } from '../errors';
-import { THEME_ATTRIBUTE, THEME_MEDIA_QUERY, THEME_STORAGE_KEY } from './theme';
-
-/**
- * Minified on purpose — this runs before first paint and is inlined into every
- * document. Reads the explicit choice, falls back to the OS, and always stamps
- * `data-theme` so screenshots and Playwright runs are deterministic.
- */
-export const THEME_INLINE_SCRIPT =
-  `try{var d=document.documentElement,` +
-  `s=localStorage.getItem('${THEME_STORAGE_KEY}');` +
-  `d.setAttribute('${THEME_ATTRIBUTE}',` +
-  `s==='light'||s==='dark'?s:` +
-  `matchMedia('${THEME_MEDIA_QUERY}').matches?'dark':'light')}catch(e){}`;
-
-/** The exact tag to inline. No attributes, so the CSP hash stays valid. */
-export function themeInlineScriptTag(): string {
-  return `<script>${THEME_INLINE_SCRIPT}</script>`;
-}
-
-let cachedHash: string | null = null;
-
-/** `sha256-<base64>` for `script-src`. Stable for a given script text. */
-export function themeInlineScriptHash(): string {
-  if (cachedHash !== null) return cachedHash;
-  if (typeof Bun === 'undefined') {
-    throw runtimeMissingError(
-      'Bun.CryptoHasher to hash the theme inline script',
-      'call themeInlineScriptHash() during build or SSR, never in browser code',
-    );
-  }
-  const digest = new Bun.CryptoHasher('sha256').update(THEME_INLINE_SCRIPT).digest('base64');
-  cachedHash = `sha256-${digest}`;
-  return cachedHash;
-}
-
-/** Quoted CSP source expression, ready to concatenate into a `script-src`. */
-export function themeInlineScriptCspSource(): string {
-  return `'${themeInlineScriptHash()}'`;
-}