@happyvertical/smrt-ui 0.40.26 → 0.40.28

package/dist/themes/ThemeProvider.svelte

@@ -3,7 +3,7 @@ import type { Snippet } from 'svelte';
 import { onMount, untrack } from 'svelte';
 import { setThemeContext, type ThemeContext } from './context.svelte.js';
 import { generateThemeVariables } from './css-generator.js';
-import { getTheme } from './registry.js';
+import { getTheme, isValidPreset } from './registry.js';
 import type {
   ColorScheme,
   Theme,
@@ -24,6 +24,12 @@ interface Props {
   borderRadius?: ThemeConfig['borderRadius'];
   /** Custom CSS variable overrides */
   overrides?: Record<string, string>;
+  /**
+   * Paint the theme's background/color/font onto the wrapper. Set false when
+   * the host app owns its surface palette and only wants the CSS variables +
+   * scheme context — avoids specificity-fighting `.smrt-theme-root`.
+   */
+  paintSurface?: boolean;
   /** Persist preferences to localStorage */
   persist?: boolean;
   /** Storage key for persistence */
@@ -38,6 +44,7 @@ let {
   primaryColor,
   borderRadius = defaultThemeConfig.borderRadius,
   overrides = {},
+  paintSurface = true,
   persist = defaultThemeConfig.persist,
   storageKey = defaultThemeConfig.storageKey,
   children,
@@ -101,7 +108,15 @@ const cssVariables = $derived.by(() => {
 // Convert to style string
 const styleString = $derived.by(() => {
   return Object.entries(cssVariables)
-    .map(([key, value]) => `${key}: ${value}`)
+    .map(([key, value]) => {
+      const isExplicitOverride =
+        Object.hasOwn(config.overrides ?? {}, key) ||
+        (key === '--smrt-color-primary' && config.primaryColor);
+      const bootstrapKey = key.replace(/^--smrt-/, '--smrt-bootstrap-');
+      return `${key}: ${
+        isExplicitOverride ? value : `var(${bootstrapKey}, ${value})`
+      }`;
+    })
     .join('; ');
 });
 
@@ -158,10 +173,32 @@ function loadPersistedConfig(): void {
   try {
     const stored = localStorage.getItem(config.storageKey!);
     if (stored) {
-      const data = JSON.parse(stored);
-      if (data.preset) config.preset = data.preset;
-      if (data.colorScheme) config.colorScheme = data.colorScheme;
-      if (data.borderRadius) config.borderRadius = data.borderRadius;
+      const data = JSON.parse(stored) as unknown;
+      if (!data || typeof data !== 'object') return;
+      const persisted = data as Record<string, unknown>;
+      if (
+        typeof persisted.preset === 'string' &&
+        isValidPreset(persisted.preset)
+      ) {
+        config.preset = persisted.preset;
+      }
+      if (
+        persisted.colorScheme === 'light' ||
+        persisted.colorScheme === 'dark' ||
+        persisted.colorScheme === 'system'
+      ) {
+        config.colorScheme = persisted.colorScheme;
+      }
+      if (
+        persisted.borderRadius === 'none' ||
+        persisted.borderRadius === 'sm' ||
+        persisted.borderRadius === 'md' ||
+        persisted.borderRadius === 'lg' ||
+        persisted.borderRadius === 'xl' ||
+        persisted.borderRadius === 'full'
+      ) {
+        config.borderRadius = persisted.borderRadius;
+      }
     }
   } catch {
     // Ignore storage errors (e.g., corrupted data, JSON parse errors)
@@ -221,23 +258,66 @@ $effect(() => {
   }
 });
 
-// Sync props to state
+// The pre-paint aliases only bridge SSR to the hydrated provider. Remove them
+// after the provider has applied the persisted config so later runtime theme
+// changes use the component's reactive variables normally.
 $effect(() => {
-  config.preset = preset;
+  if (typeof document !== 'undefined' && mounted) {
+    const html = document.documentElement;
+    for (const property of Array.from(html.style)) {
+      if (property.startsWith('--smrt-bootstrap-')) {
+        html.style.removeProperty(property);
+      }
+    }
+    html.removeAttribute('data-smrt-theme-bootstrap');
+  }
 });
 
+// Sync props to state — but only on actual prop changes. config is seeded
+// from the initial props above and onMount applies persisted preferences, so
+// re-asserting the initial prop values here would clobber the persisted
+// choice ($effect order vs onMount is not a safe thing to rely on).
+let prevPreset = untrack(() => preset);
+let prevColorScheme = untrack(() => colorScheme);
+let prevPrimaryColor = untrack(() => primaryColor);
+let prevBorderRadius = untrack(() => borderRadius);
+
 $effect(() => {
-  config.colorScheme = colorScheme;
+  if (preset !== prevPreset) {
+    prevPreset = preset;
+    untrack(() => {
+      config.preset = preset;
+    });
+  }
 });
 
 $effect(() => {
-  if (primaryColor !== undefined) {
-    config.primaryColor = primaryColor;
+  if (colorScheme !== prevColorScheme) {
+    prevColorScheme = colorScheme;
+    untrack(() => {
+      config.colorScheme = colorScheme;
+    });
   }
 });
 
 $effect(() => {
-  config.borderRadius = borderRadius;
+  if (primaryColor !== prevPrimaryColor) {
+    prevPrimaryColor = primaryColor;
+    untrack(() => {
+      if (primaryColor !== undefined) {
+        config.primaryColor = primaryColor;
+      }
+    });
+  }
+});
+
+$effect(() => {
+  if (borderRadius !== prevBorderRadius) {
+    prevBorderRadius = borderRadius;
+    untrack(() => {
+      config.borderRadius = borderRadius;
+    });
+  }
 });
 
 // Sync overrides prop to state
@@ -257,6 +337,7 @@ $effect(() => {
 <div
   class="smrt-theme-root"
   class:dark={isDark}
+  class:no-paint={!paintSurface}
   class:smrt-theme-glass={config.preset === 'glass'}
   style={styleString}
   data-theme={config.preset}
@@ -275,6 +356,12 @@ $effect(() => {
     font-family: var(--smrt-font-family);
   }
 
+  .smrt-theme-root.no-paint {
+    color: inherit;
+    background-color: transparent;
+    font-family: inherit;
+  }
+
   /* Glass theme specific base styles */
   :global(.smrt-theme-glass) {
     --smrt-glass-surface: var(--smrt-color-surface);

package/dist/themes/ThemeProvider.svelte.d.ts

@@ -11,6 +11,12 @@ interface Props {
     borderRadius?: ThemeConfig['borderRadius'];
     /** Custom CSS variable overrides */
     overrides?: Record<string, string>;
+    /**
+     * Paint the theme's background/color/font onto the wrapper. Set false when
+     * the host app owns its surface palette and only wants the CSS variables +
+     * scheme context — avoids specificity-fighting `.smrt-theme-root`.
+     */
+    paintSurface?: boolean;
     /** Persist preferences to localStorage */
     persist?: boolean;
     /** Storage key for persistence */

package/dist/themes/ThemeProvider.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ThemeProvider.svelte.d.ts","sourceRoot":"","sources":["../../src/themes/ThemeProvider.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAKtC,OAAO,KAAK,EACV,WAAW,EAEX,WAAW,EACX,WAAW,EAEZ,MAAM,YAAY,CAAC;AAIpB,UAAU,KAAK;IACb,0BAA0B;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,YAAY,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;IAC3C,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAiPD,QAAA,MAAM,aAAa,2CAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}
+{"version":3,"file":"ThemeProvider.svelte.d.ts","sourceRoot":"","sources":["../../src/themes/ThemeProvider.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAKtC,OAAO,KAAK,EACV,WAAW,EAEX,WAAW,EACX,WAAW,EAEZ,MAAM,YAAY,CAAC;AAIpB,UAAU,KAAK;IACb,0BAA0B;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,YAAY,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;IAC3C,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AA2TD,QAAA,MAAM,aAAa,2CAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}

package/dist/themes/__tests__/theme-provider.test.js

@@ -0,0 +1,109 @@
+/**
+ * Regression tests for ThemeProvider persistence behavior.
+ *
+ * Bug: the prop-sync `$effect`s re-asserted the `colorScheme`/`preset` props on
+ * every mount, clobbering the persisted localStorage preference loaded in
+ * `onMount` — a toggled light/dark choice snapped back to the prop (typically
+ * "system") on reload. Fixed by only syncing props on actual prop changes.
+ */
+import { render, waitFor } from '@testing-library/svelte';
+import { createRawSnippet } from 'svelte';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import ThemeProvider from '../ThemeProvider.svelte';
+function child() {
+    return createRawSnippet(() => ({ render: () => '<span>child</span>' }));
+}
+function mockSystemDark(matches) {
+    window.matchMedia = vi.fn().mockImplementation((query) => ({
+        matches,
+        media: query,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+    }));
+}
+describe('ThemeProvider persistence', () => {
+    beforeEach(() => {
+        localStorage.clear();
+        document.documentElement.removeAttribute('data-theme');
+        document.documentElement.removeAttribute('data-color-scheme');
+    });
+    it('keeps the persisted color scheme instead of clobbering it with the prop', async () => {
+        localStorage.setItem('smrt-theme', JSON.stringify({ colorScheme: 'light' }));
+        mockSystemDark(true); // system is dark; stored choice is light
+        render(ThemeProvider, {
+            props: { colorScheme: 'system', children: child() },
+        });
+        await waitFor(() => {
+            expect(document.documentElement.getAttribute('data-color-scheme')).toBe('light');
+        });
+        // The stored preference must survive too (not rewritten to the prop value)
+        expect(JSON.parse(localStorage.getItem('smrt-theme'))).toMatchObject({
+            colorScheme: 'light',
+        });
+    });
+    it('falls back to the system scheme when nothing is persisted', async () => {
+        mockSystemDark(true);
+        render(ThemeProvider, {
+            props: { colorScheme: 'system', children: child() },
+        });
+        await waitFor(() => {
+            expect(document.documentElement.getAttribute('data-color-scheme')).toBe('dark');
+        });
+    });
+    it('still applies prop changes after mount', async () => {
+        mockSystemDark(false);
+        const { rerender } = render(ThemeProvider, {
+            props: { colorScheme: 'system', children: child() },
+        });
+        await waitFor(() => {
+            expect(document.documentElement.getAttribute('data-color-scheme')).toBe('light');
+        });
+        await rerender({ colorScheme: 'dark', children: child() });
+        await waitFor(() => {
+            expect(document.documentElement.getAttribute('data-color-scheme')).toBe('dark');
+        });
+    });
+    it('paints the surface by default and opts out via paintSurface=false', async () => {
+        mockSystemDark(false);
+        const { container, rerender } = render(ThemeProvider, {
+            props: { children: child() },
+        });
+        const root = container.querySelector('.smrt-theme-root');
+        expect(root).not.toHaveClass('no-paint');
+        await rerender({ paintSurface: false, children: child() });
+        expect(root).toHaveClass('no-paint');
+    });
+    it('ignores invalid persisted theme values instead of breaking hydration', async () => {
+        localStorage.setItem('smrt-theme', JSON.stringify({
+            preset: 'not-a-theme',
+            colorScheme: 'sepia',
+            borderRadius: 'enormous',
+        }));
+        mockSystemDark(false);
+        render(ThemeProvider, {
+            props: {
+                preset: 'material',
+                colorScheme: 'system',
+                children: child(),
+            },
+        });
+        await waitFor(() => {
+            expect(document.documentElement.getAttribute('data-theme')).toBe('material');
+            expect(document.documentElement.getAttribute('data-color-scheme')).toBe('light');
+        });
+    });
+    it('emits bootstrap-aware SSR variable fallbacks', () => {
+        mockSystemDark(false);
+        const { container } = render(ThemeProvider, {
+            props: { children: child() },
+        });
+        const style = container.querySelector('.smrt-theme-root')?.getAttribute('style') ?? '';
+        const bootstrapBackground = [
+            '--smrt',
+            'bootstrap',
+            'color',
+            'background',
+        ].join('-');
+        expect(style).toContain(`--smrt-color-background: var(${bootstrapBackground},`);
+    });
+});

package/dist/themes/__tests__/theme-script.test.js

@@ -0,0 +1,121 @@
+/**
+ * Tests for the themeScript() pre-paint bootstrap generator. The generated
+ * script must mirror ThemeProvider's persistence resolution so apps stop
+ * hand-duplicating it in app.html.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createTheme, registerTheme } from '../create-theme.js';
+import { generateThemeVariables } from '../css-generator.js';
+import { studioTheme } from '../studio/index.js';
+import { themeScript } from '../theme-script.js';
+function mockSystemDark(matches) {
+    window.matchMedia = vi.fn().mockImplementation((query) => ({
+        matches,
+        media: query,
+    }));
+}
+function run(script) {
+    // biome-ignore lint/security/noGlobalEval: the browser evals this inline bootstrap; testing that is the point
+    (0, eval)(script);
+}
+describe('themeScript', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        localStorage.clear();
+        document.documentElement.removeAttribute('data-theme');
+        document.documentElement.removeAttribute('data-color-scheme');
+        document.documentElement.removeAttribute('data-smrt-theme-bootstrap');
+        document.documentElement.classList.remove('dark');
+        for (const property of Array.from(document.documentElement.style)) {
+            if (property.startsWith('--smrt-bootstrap-')) {
+                document.documentElement.style.removeProperty(property);
+            }
+        }
+    });
+    it('resolves system preference when nothing is stored', () => {
+        mockSystemDark(true);
+        run(themeScript({ preset: 'material' }));
+        expect(document.documentElement.getAttribute('data-theme')).toBe('material');
+        expect(document.documentElement.getAttribute('data-color-scheme')).toBe('dark');
+        expect(document.documentElement.classList.contains('dark')).toBe(true);
+    });
+    it('honours a stored scheme and preset over system and defaults', () => {
+        mockSystemDark(true);
+        localStorage.setItem('smrt-theme', JSON.stringify({ preset: 'studio', colorScheme: 'light' }));
+        run(themeScript({ preset: 'material' }));
+        expect(document.documentElement.getAttribute('data-theme')).toBe('studio');
+        expect(document.documentElement.getAttribute('data-color-scheme')).toBe('light');
+        expect(document.documentElement.classList.contains('dark')).toBe(false);
+        expect(document.documentElement.style.getPropertyValue('--smrt-bootstrap-color-background')).toBe(generateThemeVariables(studioTheme, false)['--smrt-color-background']);
+    });
+    it('uses the custom storageKey', () => {
+        mockSystemDark(false);
+        localStorage.setItem('my-theme', JSON.stringify({ colorScheme: 'dark' }));
+        run(themeScript({ storageKey: 'my-theme' }));
+        expect(document.documentElement.getAttribute('data-color-scheme')).toBe('dark');
+    });
+    it('does not read stored preferences when persistence is disabled', () => {
+        mockSystemDark(false);
+        localStorage.setItem('smrt-theme', JSON.stringify({ preset: 'studio', colorScheme: 'dark' }));
+        run(themeScript({
+            persist: false,
+            preset: 'material',
+            defaultColorScheme: 'light',
+        }));
+        expect(document.documentElement.getAttribute('data-theme')).toBe('material');
+        expect(document.documentElement.getAttribute('data-color-scheme')).toBe('light');
+    });
+    it('ignores a raw (non-JSON) stored value like ThemeProvider', () => {
+        mockSystemDark(true);
+        localStorage.setItem('smrt-theme', 'light');
+        run(themeScript());
+        expect(document.documentElement.getAttribute('data-color-scheme')).toBe('dark');
+        expect(document.documentElement.classList.contains('dark')).toBe(true);
+    });
+    it('ignores invalid persisted enum values', () => {
+        mockSystemDark(false);
+        localStorage.setItem('smrt-theme', JSON.stringify({
+            preset: 'not-a-theme',
+            colorScheme: 'sepia',
+        }));
+        run(themeScript({ preset: 'material', defaultColorScheme: 'light' }));
+        expect(document.documentElement.getAttribute('data-theme')).toBe('material');
+        expect(document.documentElement.getAttribute('data-color-scheme')).toBe('light');
+    });
+    it('bootstraps a registered custom theme from persistence', () => {
+        const brandTheme = createTheme({
+            id: 'bootstrap-test-brand',
+            name: 'Bootstrap Test Brand',
+            light: { primary: '#336699', background: '#fefefe' },
+            dark: { primary: '#99ccff', background: '#101820' },
+        });
+        registerTheme(brandTheme);
+        mockSystemDark(false);
+        localStorage.setItem('smrt-theme', JSON.stringify({
+            preset: 'bootstrap-test-brand',
+            colorScheme: 'dark',
+        }));
+        run(themeScript());
+        expect(document.documentElement.getAttribute('data-theme')).toBe('bootstrap-test-brand');
+        expect(document.documentElement.style.getPropertyValue('--smrt-bootstrap-color-background')).toBe(generateThemeVariables(brandTheme, true)['--smrt-color-background']);
+    });
+    it('still applies the fallback when localStorage access throws', () => {
+        mockSystemDark(true);
+        vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+            throw new DOMException('denied', 'SecurityError');
+        });
+        run(themeScript({ preset: 'studio' }));
+        expect(document.documentElement.getAttribute('data-theme')).toBe('studio');
+        expect(document.documentElement.getAttribute('data-color-scheme')).toBe('dark');
+        expect(document.documentElement.classList.contains('dark')).toBe(true);
+    });
+    it('escapes executable inline-script terminators and separators', () => {
+        const script = themeScript({
+            storageKey: '</script><script>alert(1)</script>\u2028\u2029',
+        });
+        expect(script.toLowerCase()).not.toContain('</script');
+        expect(script).not.toContain('\u2028');
+        expect(script).not.toContain('\u2029');
+        expect(script).toContain('\\u003c/script>');
+    });
+});

package/dist/themes/index.d.ts

@@ -27,6 +27,7 @@ export { appleEasing, borderRadiusScale, durationScale, materialEasing, spacingS
 export { smrtTheme } from './smrt/index.js';
 export { studioTheme } from './studio/index.js';
 export { default as ThemeProvider } from './ThemeProvider.svelte';
+export { type ThemeScriptOptions, themeScript } from './theme-script.js';
 export type { BorderRadius, BorderRadiusScale, ColorPalette, ColorScheme, CSSVariableOptions, DurationScale, EasingScale, ElevationScale, GlassEffects, ResolvedScheme, SpacingScale, Theme, ThemeConfig, ThemeContext, ThemePreset, ThemeState, TypographyScale, TypographyToken, } from './types.js';
 export { defaultThemeConfig } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/themes/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/themes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEzE,OAAO,EACL,eAAe,EACf,eAAe,EACf,eAAe,EACf,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,aAAa,EACb,MAAM,GACP,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAElE,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,cAAc,EACd,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,KAAK,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,UAAU,EACV,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/themes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEzE,OAAO,EACL,eAAe,EACf,eAAe,EACf,eAAe,EACf,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,aAAa,EACb,MAAM,GACP,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,EAAE,KAAK,kBAAkB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEzE,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,cAAc,EACd,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,KAAK,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,UAAU,EACV,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/themes/index.js

@@ -34,5 +34,7 @@ export { smrtTheme } from './smrt/index.js';
 export { studioTheme } from './studio/index.js';
 // Main components
 export { default as ThemeProvider } from './ThemeProvider.svelte';
+// Pre-paint bootstrap script
+export { themeScript } from './theme-script.js';
 // Constants
 export { defaultThemeConfig } from './types.js';

package/dist/themes/theme-script.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pre-paint theme bootstrap script generator.
+ *
+ * ThemeProvider resolves the persisted/system color scheme only after mount,
+ * so apps without a pre-paint script flash the wrong scheme on load. Apps used
+ * to hand-duplicate the provider's storage logic in `app.html`; this helper
+ * generates that script from the same config so the two never drift.
+ *
+ * Usage (root layout — SSR renders `svelte:head` into the initial HTML, so the
+ * script runs before first paint):
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { themeScript } from '@happyvertical/smrt-ui/themes';
+ * </script>
+ *
+ * <svelte:head>
+ *   {@html `<script>${themeScript({ preset: 'studio' })}</script>`}
+ * </svelte:head>
+ * ```
+ */
+import type { ColorScheme, ThemePreset } from './types.js';
+export interface ThemeScriptOptions {
+    /** Preset to stamp as `data-theme` when nothing is persisted. */
+    preset?: ThemePreset;
+    /** Read persisted preferences. Must match ThemeProvider's `persist` prop. */
+    persist?: boolean;
+    /** localStorage key — must match ThemeProvider's `storageKey`. */
+    storageKey?: string;
+    /** Fallback scheme when storage holds no value. Default: 'system'. */
+    defaultColorScheme?: ColorScheme;
+}
+/**
+ * Returns the JS body (no `<script>` tags) of a pre-paint bootstrap that
+ * mirrors ThemeProvider's persistence: reads the stored config, resolves
+ * 'system' via matchMedia, then stamps `data-theme`, `data-color-scheme`,
+ * the `dark` class, and `color-scheme` style on <html>. It also sets temporary
+ * bootstrap variables consumed by ThemeProvider's SSR inline fallbacks, so the
+ * persisted preset/scheme wins before hydration rather than only changing
+ * attributes around an already-painted default wrapper.
+ */
+export declare function themeScript(options?: ThemeScriptOptions): string;
+//# sourceMappingURL=theme-script.d.ts.map

package/dist/themes/theme-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-script.d.ts","sourceRoot":"","sources":["../../src/themes/theme-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG3D,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,WAAW,CAAC;CAClC;AAaD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,MAAM,CAoCpE"}

package/dist/themes/theme-script.js

@@ -0,0 +1,68 @@
+/**
+ * Pre-paint theme bootstrap script generator.
+ *
+ * ThemeProvider resolves the persisted/system color scheme only after mount,
+ * so apps without a pre-paint script flash the wrong scheme on load. Apps used
+ * to hand-duplicate the provider's storage logic in `app.html`; this helper
+ * generates that script from the same config so the two never drift.
+ *
+ * Usage (root layout — SSR renders `svelte:head` into the initial HTML, so the
+ * script runs before first paint):
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { themeScript } from '@happyvertical/smrt-ui/themes';
+ * </script>
+ *
+ * <svelte:head>
+ *   {@html `<script>${themeScript({ preset: 'studio' })}</script>`}
+ * </svelte:head>
+ * ```
+ */
+import { generateThemeVariables } from './css-generator.js';
+import { getTheme, getThemeOptions } from './registry.js';
+import { defaultThemeConfig } from './types.js';
+function inlineJSON(value) {
+    return JSON.stringify(value)
+        .replace(/</g, '\\u003c')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
+function bootstrapVariableName(variable) {
+    return variable.replace(/^--smrt-/, '--smrt-bootstrap-');
+}
+/**
+ * Returns the JS body (no `<script>` tags) of a pre-paint bootstrap that
+ * mirrors ThemeProvider's persistence: reads the stored config, resolves
+ * 'system' via matchMedia, then stamps `data-theme`, `data-color-scheme`,
+ * the `dark` class, and `color-scheme` style on <html>. It also sets temporary
+ * bootstrap variables consumed by ThemeProvider's SSR inline fallbacks, so the
+ * persisted preset/scheme wins before hydration rather than only changing
+ * attributes around an already-painted default wrapper.
+ */
+export function themeScript(options = {}) {
+    const presetNames = getThemeOptions().map(({ value }) => value);
+    const requestedPreset = options.preset ?? defaultThemeConfig.preset;
+    const preset = presetNames.includes(requestedPreset)
+        ? requestedPreset
+        : defaultThemeConfig.preset;
+    const persist = options.persist ?? defaultThemeConfig.persist;
+    const storageKey = options.storageKey ?? defaultThemeConfig.storageKey;
+    const requestedFallback = options.defaultColorScheme ?? defaultThemeConfig.colorScheme;
+    const fallback = ['light', 'dark', 'system'].includes(requestedFallback)
+        ? requestedFallback
+        : defaultThemeConfig.colorScheme;
+    const variableNames = Array.from(new Set(presetNames.flatMap((name) => [
+        ...Object.keys(generateThemeVariables(getTheme(name), false)),
+        ...Object.keys(generateThemeVariables(getTheme(name), true)),
+    ])));
+    const bootstrapNames = variableNames.map(bootstrapVariableName);
+    const variableRows = presetNames.flatMap((name) => [false, true].map((dark) => {
+        const variables = generateThemeVariables(getTheme(name), dark);
+        return variableNames.map((variable) => variables[variable] ?? '');
+    }));
+    // Keep this dependency-free and ES5-ish: it runs inline in every browser
+    // before any framework code. Must stay in sync with
+    // ThemeProvider.svelte's loadPersistedConfig()/resolvedScheme.
+    return `(function(){try{var presets=${inlineJSON(presetNames)};var names=${inlineJSON(bootstrapNames)};var rows=${inlineJSON(variableRows)};var scheme=${inlineJSON(fallback)};var preset=${inlineJSON(preset)};${persist ? `try{var raw=localStorage.getItem(${inlineJSON(storageKey)});if(raw){var data=JSON.parse(raw);if(data&&typeof data==='object'){if(data.colorScheme==='light'||data.colorScheme==='dark'||data.colorScheme==='system')scheme=data.colorScheme;if(typeof data.preset==='string'&&presets.indexOf(data.preset)!==-1)preset=data.preset;}}}catch(_){}` : ''}if(scheme==='system'){scheme=window.matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';}var el=document.documentElement;el.setAttribute('data-theme',preset);el.setAttribute('data-color-scheme',scheme);el.setAttribute('data-smrt-theme-bootstrap','');el.classList.toggle('dark',scheme==='dark');el.style.colorScheme=scheme;var row=rows[presets.indexOf(preset)*2+(scheme==='dark'?1:0)];for(var i=0;i<names.length;i++){if(row[i])el.style.setProperty(names[i],row[i]);}}catch(_){}})();`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-ui",
-  "version": "0.40.26",
+  "version": "0.40.28",
   "description": "Domain-agnostic Svelte 5 UI runtime for SMRT: primitives, i18n client, theme system, and module UI registry",
   "type": "module",
   "main": "./dist/index.js",
@@ -124,7 +124,7 @@
   },
   "dependencies": {
     "esm-env": "^1.2.2",
-    "@happyvertical/smrt-types": "0.40.26"
+    "@happyvertical/smrt-types": "0.40.28"
   },
   "peerDependencies": {
     "svelte": "^5.56.4"