svelte-theme-picker 1.0.0 → 1.1.0

package/README.md

@@ -74,6 +74,155 @@ interface ThemePickerConfig {
 }
 ```
 
+## SSR Support (Preventing Flash)
+
+When using SvelteKit with SSR, themes are applied after JavaScript loads, causing a flash of unstyled content (FOUC). Use the `ThemeHead` component or SSR utilities to prevent this.
+
+### Using ThemeHead Component (Recommended)
+
+The easiest way to prevent theme flash in SvelteKit:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import { ThemeHead, ThemePicker, defaultThemes } from 'svelte-theme-picker';
+</script>
+
+<ThemeHead
+  themes={defaultThemes}
+  storageKey="my-app-theme"
+  defaultTheme="dreamy"
+  preloadFonts={true}
+/>
+
+<ThemePicker config={{ themes: defaultThemes, storageKey: 'my-app-theme' }} />
+
+<slot />
+```
+
+The `ThemeHead` component:
+- Injects a blocking script that applies CSS variables before first paint
+- Adds `no-transitions` class to prevent transition animations during hydration
+- Optionally preloads Google Fonts for all themes
+
+### ThemeHead Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `themes` | `Record<string, Theme>` | required | All available themes |
+| `storageKey` | `string` | `'svelte-theme-picker'` | localStorage key |
+| `defaultTheme` | `string` | first theme | Default theme ID |
+| `cssVarPrefix` | `string` | `''` | CSS variable prefix |
+| `preventTransitions` | `boolean` | `true` | Prevent transition animations during hydration |
+| `preloadFonts` | `boolean` | `false` | Enable Google Fonts preloading |
+| `fontConfig` | `FontConfig` | `{ provider: 'google' }` | Font preloading configuration |
+
+### Using SSR Utilities Directly
+
+For more control, use the SSR utilities to generate blocking scripts:
+
+```typescript
+// src/hooks.server.ts
+import { generateSSRHead } from 'svelte-theme-picker';
+import { myThemes } from './themes';
+
+export async function handle({ event, resolve }) {
+  return resolve(event, {
+    transformPageChunk: ({ html }) => {
+      const ssrHead = generateSSRHead({
+        themes: myThemes,
+        storageKey: 'my-app-theme',
+        defaultTheme: 'dreamy',
+      });
+      return html.replace('</head>', `${ssrHead}</head>`);
+    }
+  });
+}
+```
+
+### Removing No-Transitions Class
+
+After hydration, remove the `no-transitions` class to enable animations:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import { browser } from '$app/environment';
+  import { onMount } from 'svelte';
+
+  onMount(() => {
+    // Small delay to ensure hydration is complete
+    setTimeout(() => {
+      document.documentElement.classList.remove('no-transitions');
+    }, 50);
+  });
+</script>
+```
+
+### SSR Utility Functions
+
+```typescript
+import {
+  generateBlockingScript,  // Generate minified blocking script string
+  generateSSRHead,         // Generate complete head HTML (script + styles + fonts)
+  applyThemeToElement,     // Apply theme to an element (sync, for blocking scripts)
+  getThemeCSS,            // Get CSS variable declarations as string
+  extractFonts,           // Extract font names from a theme
+  generateFontPreloadLinks, // Generate Google Fonts preload links
+  themeSchema,            // CSS variable mapping (for consistency)
+} from 'svelte-theme-picker';
+```
+
+## Cross-Tab Synchronization
+
+Enable automatic theme sync across browser tabs:
+
+```svelte
+<script>
+  import { createThemeStore, ThemePicker } from 'svelte-theme-picker';
+
+  const store = createThemeStore({
+    syncTabs: true,  // Enable cross-tab sync
+    storageKey: 'my-app-theme',
+  });
+</script>
+
+<ThemePicker store={store} />
+```
+
+When a user changes the theme in one tab, all other tabs will automatically update. The store listens for `storage` events and syncs the theme state.
+
+To clean up listeners when done:
+
+```typescript
+store.destroy(); // Removes storage event listener
+```
+
+## External Store Synchronization
+
+If you're using an external store and the `ThemePicker` doesn't update when the store changes externally, use the `{#key}` pattern to force a re-render:
+
+```svelte
+<script>
+  import { ThemePicker, createThemeStore } from 'svelte-theme-picker';
+
+  const themeStore = createThemeStore({ /* config */ });
+  let currentThemeId = $state('dreamy');
+
+  // Subscribe to track external changes
+  themeStore.subscribe((themeId) => {
+    currentThemeId = themeId;
+  });
+</script>
+
+<!-- Force re-render when theme changes externally -->
+{#key currentThemeId}
+  <ThemePicker store={themeStore} />
+{/key}
+```
+
+> **Note**: The `ThemePicker` component captures its configuration once at mount. This is intentional for performance. Use `{#key}` to create a new instance when props need to change.
+
 ## Headless Mode (No UI)
 
 The `ThemePicker` component is completely optional. You can use just the store and utilities for full programmatic control without rendering any UI. This is useful when:
@@ -569,6 +718,57 @@ You can provide your own themes:
 <ThemePicker config={{ themes: myThemes, defaultTheme: 'my-theme' }} />
 ```
 
+## Styling the Picker
+
+The `ThemePicker` component can be customized using CSS custom properties. The picker automatically uses your theme's CSS variables as fallbacks, so it adapts to your theme.
+
+### Picker CSS Properties
+
+Override these to customize the picker appearance:
+
+```css
+/* In your global CSS or :root */
+:root {
+  /* Colors */
+  --stp-bg: var(--bg-card);           /* Panel background */
+  --stp-bg-hover: var(--bg-glow);     /* Hover state background */
+  --stp-bg-active: ...;               /* Active/selected item */
+  --stp-border: ...;                  /* Border color */
+  --stp-text: var(--text-primary);    /* Primary text */
+  --stp-text-muted: var(--text-muted);/* Secondary text */
+  --stp-accent: var(--accent-1);      /* Accent color */
+  --stp-accent-glow: ...;             /* Glow effect color */
+
+  /* Trigger button */
+  --stp-trigger-bg: ...;              /* Trigger background gradient */
+  --stp-trigger-color: var(--bg-deep);/* Trigger icon color */
+
+  /* Layout */
+  --stp-radius: 12px;                 /* Panel border radius */
+  --stp-radius-sm: 8px;               /* Item border radius */
+  --stp-space: 12px;                  /* Standard spacing */
+  --stp-space-sm: 8px;                /* Small spacing */
+  --stp-transition: 0.2s ease;        /* Transition timing */
+}
+```
+
+The picker uses `color-mix()` for calculated colors (active states, borders) that automatically adjust to your theme. No `!important` overrides should be needed.
+
+### Theme Mode
+
+Themes can declare a `mode` property (`'light'` or `'dark'`) to help the picker adjust its styling:
+
+```typescript
+const myTheme: Theme = {
+  name: 'My Light Theme',
+  description: 'A light theme',
+  mode: 'light',  // or 'dark'
+  colors: { ... },
+  fonts: { ... },
+  effects: { ... },
+};
+```
+
 ## CSS Variables
 
 The theme picker applies these CSS variables to your document:
@@ -669,18 +869,28 @@ Full TypeScript support with exported types:
 
 ```typescript
 import type {
+  // Theme types
   Theme,
   ThemeColors,
   ThemeFonts,
   ThemeEffects,
   ThemePickerConfig,
+  // Catalog types
   ThemeCatalog,
   ThemeCatalogEntry,
   ThemeMeta,
   ThemeFilterOptions,
+  // SSR types
+  SSRConfig,
+  FontConfig,
+  ThemeSchema,
 } from 'svelte-theme-picker';
 ```
 
+## Migration Guide
+
+Upgrading from a previous version? See [MIGRATION.md](./MIGRATION.md) for breaking changes and migration steps.
+
 ## License
 
 MIT

package/dist/ThemeHead.svelte

@@ -0,0 +1,69 @@
+<script lang="ts">
+    import { generateBlockingScript, extractFonts, generateFontPreloadLinks } from './ssr.js';
+    import type { Theme, FontConfig } from './types.js';
+
+    interface Props {
+        /** All available themes */
+        themes: Record<string, Theme>;
+        /** localStorage key for theme persistence */
+        storageKey?: string;
+        /** Default theme ID if none is stored */
+        defaultTheme?: string;
+        /** CSS variable prefix */
+        cssVarPrefix?: string;
+        /** Whether to prevent transitions during hydration (default: true) */
+        preventTransitions?: boolean;
+        /** Enable font preloading */
+        preloadFonts?: boolean;
+        /** Font configuration for preloading */
+        fontConfig?: FontConfig;
+    }
+
+    let {
+        themes,
+        storageKey = 'svelte-theme-picker',
+        defaultTheme,
+        cssVarPrefix = '',
+        preventTransitions = true,
+        preloadFonts = false,
+        fontConfig = { provider: 'google' },
+    }: Props = $props();
+
+    // Generate the blocking script
+    const blockingScript = $derived(generateBlockingScript({
+        themes,
+        storageKey,
+        defaultTheme,
+        cssVarPrefix,
+        preventTransitions,
+    }));
+
+    // Generate font preload links if enabled
+    const fontLinks = $derived.by(() => {
+        if (!preloadFonts) return '';
+
+        const allFonts = new Set<string>();
+        for (const theme of Object.values(themes)) {
+            for (const font of extractFonts(theme)) {
+                allFonts.add(font);
+            }
+        }
+        return generateFontPreloadLinks([...allFonts], fontConfig);
+    });
+
+    // No-transitions CSS
+    const noTransitionsCSS = '.no-transitions,.no-transitions *,.no-transitions *::before,.no-transitions *::after{transition:none!important;animation:none!important}';
+</script>
+
+<svelte:head>
+    {#if preloadFonts && fontLinks}
+        <!-- eslint-disable-next-line svelte/no-at-html-tags -->
+        {@html fontLinks}
+    {/if}
+    <!-- eslint-disable-next-line svelte/no-at-html-tags -->
+    {@html `<script>${blockingScript}</script>`}
+    {#if preventTransitions}
+        <!-- eslint-disable-next-line svelte/no-at-html-tags -->
+        {@html `<style>${noTransitionsCSS}</style>`}
+    {/if}
+</svelte:head>

package/dist/ThemeHead.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { Theme, FontConfig } from './types.js';
+interface Props {
+    /** All available themes */
+    themes: Record<string, Theme>;
+    /** localStorage key for theme persistence */
+    storageKey?: string;
+    /** Default theme ID if none is stored */
+    defaultTheme?: string;
+    /** CSS variable prefix */
+    cssVarPrefix?: string;
+    /** Whether to prevent transitions during hydration (default: true) */
+    preventTransitions?: boolean;
+    /** Enable font preloading */
+    preloadFonts?: boolean;
+    /** Font configuration for preloading */
+    fontConfig?: FontConfig;
+}
+declare const ThemeHead: import("svelte").Component<Props, {}, "">;
+type ThemeHead = ReturnType<typeof ThemeHead>;
+export default ThemeHead;

package/dist/ThemePicker.svelte

@@ -171,15 +171,50 @@
 </div>
 
 <style>
+    /*
+     * CSS Custom Properties for ThemePicker
+     * Override these to customize the picker appearance:
+     *
+     * Colors:
+     *   --stp-bg          : Panel background color
+     *   --stp-bg-hover    : Hover state background
+     *   --stp-bg-active   : Active/selected item background
+     *   --stp-border      : Border color
+     *   --stp-text        : Primary text color
+     *   --stp-text-muted  : Secondary/muted text color
+     *   --stp-accent      : Accent color (trigger, scrollbar, checks)
+     *   --stp-accent-glow : Glow effect color for trigger
+     *
+     * Trigger button:
+     *   --stp-trigger-bg       : Trigger button background
+     *   --stp-trigger-color    : Trigger button icon color
+     *
+     * Layout:
+     *   --stp-radius      : Panel border radius
+     *   --stp-radius-sm   : Button/item border radius
+     *   --stp-space       : Standard spacing
+     *   --stp-space-sm    : Small spacing
+     *   --stp-transition  : Transition duration/easing
+     *
+     * Example usage:
+     *   :root {
+     *     --stp-bg: var(--bg-card);
+     *     --stp-text: var(--text-primary);
+     *     --stp-accent: var(--accent-1);
+     *   }
+     */
     .stp-theme-picker {
-        --stp-bg: #2a2a4a;
-        --stp-bg-hover: #3d3d6b;
-        --stp-bg-active: rgba(168, 85, 247, 0.15);
-        --stp-border: rgba(255, 255, 255, 0.1);
-        --stp-text: #e8e0f0;
-        --stp-text-muted: #9090b0;
-        --stp-accent: #a855f7;
-        --stp-accent-glow: rgba(168, 85, 247, 0.3);
+        /* Fallback to theme variables, then to default values */
+        --stp-bg: var(--bg-card, #2a2a4a);
+        --stp-bg-hover: var(--bg-glow, #3d3d6b);
+        --stp-bg-active: color-mix(in srgb, var(--stp-accent, var(--accent-1, #a855f7)) 15%, transparent);
+        --stp-border: color-mix(in srgb, var(--stp-text, var(--text-primary, #e8e0f0)) 10%, transparent);
+        --stp-text: var(--text-primary, #e8e0f0);
+        --stp-text-muted: var(--text-muted, #9090b0);
+        --stp-accent: var(--accent-1, #a855f7);
+        --stp-accent-glow: color-mix(in srgb, var(--stp-accent) 30%, transparent);
+        --stp-trigger-bg: linear-gradient(135deg, var(--primary-3, #c9a0dc), var(--stp-accent));
+        --stp-trigger-color: var(--bg-deep, #1a1a2e);
         --stp-radius: 12px;
         --stp-radius-sm: 8px;
         --stp-space: 12px;
@@ -221,15 +256,15 @@
         height: 48px;
         border-radius: 50%;
         border: none;
-        background: linear-gradient(135deg, #c9a0dc, #a855f7);
-        color: #1a1a2e;
+        background: var(--stp-trigger-bg);
+        color: var(--stp-trigger-color);
         cursor: pointer;
         display: flex;
         align-items: center;
         justify-content: center;
         box-shadow:
             0 4px 20px var(--stp-accent-glow),
-            0 0 40px rgba(168, 85, 247, 0.1);
+            0 0 40px color-mix(in srgb, var(--stp-accent) 10%, transparent);
         transition: transform var(--stp-transition), box-shadow var(--stp-transition);
         /* Performance: Hint browser to prepare GPU layer for animations */
         will-change: transform;
@@ -239,7 +274,7 @@
         transform: scale(1.1);
         box-shadow:
             0 8px 30px var(--stp-accent-glow),
-            0 0 60px rgba(168, 85, 247, 0.2);
+            0 0 60px color-mix(in srgb, var(--stp-accent) 20%, transparent);
     }
 
     .stp-backdrop {
@@ -251,7 +286,7 @@
     .stp-panel {
         position: absolute;
         width: 320px;
-        background: linear-gradient(135deg, rgba(42, 42, 74, 0.95), rgba(61, 61, 107, 0.9));
+        background: color-mix(in srgb, var(--stp-bg) 95%, transparent);
         backdrop-filter: blur(16px);
         -webkit-backdrop-filter: blur(16px); /* Safari support */
         border-radius: var(--stp-radius);
@@ -409,7 +444,7 @@
     }
 
     .stp-list::-webkit-scrollbar-thumb {
-        background: rgba(168, 85, 247, 0.5);
+        background: color-mix(in srgb, var(--stp-accent) 50%, transparent);
         border-radius: 3px;
     }
 
@@ -482,7 +517,7 @@
 
     .stp-check {
         flex-shrink: 0;
-        color: #8ad4d4;
+        color: var(--accent-2, #8ad4d4);
     }
 
     @media (max-width: 640px) {

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { default as ThemePicker } from './ThemePicker.svelte';
-export type { Theme, ThemeColors, ThemeFonts, ThemeEffects, ThemePickerConfig, ThemeMeta, ThemeCatalogEntry, ThemeCatalog, ThemeFilterOptions, } from './types.js';
+export { default as ThemeHead } from './ThemeHead.svelte';
+export type { Theme, ThemeColors, ThemeFonts, ThemeEffects, ThemePickerConfig, ThemeMeta, ThemeCatalogEntry, ThemeCatalog, ThemeFilterOptions, SSRConfig, FontConfig, ThemeSchema, } from './types.js';
 export { createThemeStore, applyTheme, themeStore, type ThemeStore, } from './store.js';
 export { defaultThemes, defaultThemeCatalog, DEFAULT_THEME_ID, dreamy, cyberpunk, sunset, ocean, mono, sakura, aurora, galaxy, milk, light, } from './themes.js';
 export { themesToCatalog, catalogToThemes, filterCatalog, getActiveThemes, getThemesByTag, getThemesByAnyTag, sortCatalog, getCatalogTags, createCatalogEntry, mergeCatalogs, loadCatalogFromJSON, } from './catalog.js';
+export { generateBlockingScript, generateSSRHead, applyThemeToElement, getThemeCSS, extractFonts, generateFontPreloadLinks, themeSchema, } from './ssr.js';

package/dist/index.js

@@ -1,8 +1,11 @@
 // Components
 export { default as ThemePicker } from './ThemePicker.svelte';
+export { default as ThemeHead } from './ThemeHead.svelte';
 // Store
 export { createThemeStore, applyTheme, themeStore, } from './store.js';
 // Default themes
 export { defaultThemes, defaultThemeCatalog, DEFAULT_THEME_ID, dreamy, cyberpunk, sunset, ocean, mono, sakura, aurora, galaxy, milk, light, } from './themes.js';
 // Catalog utilities
 export { themesToCatalog, catalogToThemes, filterCatalog, getActiveThemes, getThemesByTag, getThemesByAnyTag, sortCatalog, getCatalogTags, createCatalogEntry, mergeCatalogs, loadCatalogFromJSON, } from './catalog.js';
+// SSR utilities
+export { generateBlockingScript, generateSSRHead, applyThemeToElement, getThemeCSS, extractFonts, generateFontPreloadLinks, themeSchema, } from './ssr.js';

package/dist/ssr.d.ts

@@ -0,0 +1,42 @@
+import type { Theme, SSRConfig, FontConfig, ThemeSchema } from './types.js';
+/**
+ * CSS variable schema - maps theme properties to CSS variable names.
+ * Use this to ensure consistency between blocking scripts and runtime.
+ */
+export declare const themeSchema: ThemeSchema;
+/**
+ * Get CSS variable declarations for a theme as a string.
+ * Useful for generating inline styles or CSS rules.
+ */
+export declare function getThemeCSS(theme: Theme, prefix?: string): string;
+/**
+ * Apply theme CSS variables to an HTML element synchronously.
+ * This is the same logic as the runtime applyTheme but without requestAnimationFrame,
+ * making it suitable for use in blocking scripts.
+ */
+export declare function applyThemeToElement(element: HTMLElement, theme: Theme, prefix?: string): void;
+/**
+ * Extract font family names from a theme.
+ * Parses CSS font-family values to extract the primary font name.
+ */
+export declare function extractFonts(theme: Theme): string[];
+/**
+ * Generate Google Fonts preload links for the given font names.
+ */
+export declare function generateFontPreloadLinks(fonts: string[], config?: FontConfig): string;
+/**
+ * Generate a blocking script that prevents theme flash on page load.
+ * This script should be placed in the <head> of your HTML before any other scripts.
+ *
+ * The script:
+ * 1. Reads the stored theme from localStorage
+ * 2. Applies CSS variables immediately (before paint)
+ * 3. Optionally adds a 'no-transitions' class to prevent transition animations during hydration
+ * 4. Optionally preloads fonts for the current theme
+ */
+export declare function generateBlockingScript(config: SSRConfig): string;
+/**
+ * Generate a complete SSR script tag that can be inserted into HTML.
+ * Includes the blocking script and optionally font preload links.
+ */
+export declare function generateSSRHead(config: SSRConfig): string;

package/dist/ssr.js

@@ -0,0 +1,239 @@
+/**
+ * CSS variable schema - maps theme properties to CSS variable names.
+ * Use this to ensure consistency between blocking scripts and runtime.
+ */
+export const themeSchema = {
+    colors: {
+        bgDeep: 'bg-deep',
+        bgMid: 'bg-mid',
+        bgCard: 'bg-card',
+        bgGlow: 'bg-glow',
+        bgOverlay: 'bg-overlay',
+        primary1: 'primary-1',
+        primary2: 'primary-2',
+        primary3: 'primary-3',
+        primary4: 'primary-4',
+        primary5: 'primary-5',
+        primary6: 'primary-6',
+        accent1: 'accent-1',
+        accent2: 'accent-2',
+        accent3: 'accent-3',
+        textPrimary: 'text-primary',
+        textSecondary: 'text-secondary',
+        textMuted: 'text-muted',
+    },
+    fonts: {
+        heading: 'font-heading',
+        body: 'font-body',
+        mono: 'font-mono',
+    },
+    effects: {
+        shadowGlow: 'shadow-glow',
+        glowColor: 'glow-color',
+        glowIntensity: 'glow-intensity',
+    },
+};
+/**
+ * Get CSS variable declarations for a theme as a string.
+ * Useful for generating inline styles or CSS rules.
+ */
+export function getThemeCSS(theme, prefix = '') {
+    const p = prefix ? `${prefix}-` : '';
+    const vars = [];
+    // Colors
+    for (const [key, cssVar] of Object.entries(themeSchema.colors)) {
+        const value = theme.colors[key];
+        vars.push(`--${p}${cssVar}: ${value}`);
+    }
+    // Fonts
+    for (const [key, cssVar] of Object.entries(themeSchema.fonts)) {
+        const value = theme.fonts[key];
+        vars.push(`--${p}${cssVar}: ${value}`);
+    }
+    // Effects
+    vars.push(`--${p}${themeSchema.effects.shadowGlow}: 0 0 40px ${theme.effects.glowColor}`);
+    vars.push(`--${p}${themeSchema.effects.glowColor}: ${theme.effects.glowColor}`);
+    vars.push(`--${p}${themeSchema.effects.glowIntensity}: ${theme.effects.glowIntensity}`);
+    return vars.join('; ');
+}
+/**
+ * Apply theme CSS variables to an HTML element synchronously.
+ * This is the same logic as the runtime applyTheme but without requestAnimationFrame,
+ * making it suitable for use in blocking scripts.
+ */
+export function applyThemeToElement(element, theme, prefix = '') {
+    const p = prefix ? `${prefix}-` : '';
+    // Background colors
+    element.style.setProperty(`--${p}bg-deep`, theme.colors.bgDeep);
+    element.style.setProperty(`--${p}bg-mid`, theme.colors.bgMid);
+    element.style.setProperty(`--${p}bg-card`, theme.colors.bgCard);
+    element.style.setProperty(`--${p}bg-glow`, theme.colors.bgGlow);
+    element.style.setProperty(`--${p}bg-overlay`, theme.colors.bgOverlay);
+    // Primary palette
+    element.style.setProperty(`--${p}primary-1`, theme.colors.primary1);
+    element.style.setProperty(`--${p}primary-2`, theme.colors.primary2);
+    element.style.setProperty(`--${p}primary-3`, theme.colors.primary3);
+    element.style.setProperty(`--${p}primary-4`, theme.colors.primary4);
+    element.style.setProperty(`--${p}primary-5`, theme.colors.primary5);
+    element.style.setProperty(`--${p}primary-6`, theme.colors.primary6);
+    // Accent colors
+    element.style.setProperty(`--${p}accent-1`, theme.colors.accent1);
+    element.style.setProperty(`--${p}accent-2`, theme.colors.accent2);
+    element.style.setProperty(`--${p}accent-3`, theme.colors.accent3);
+    // Text colors
+    element.style.setProperty(`--${p}text-primary`, theme.colors.textPrimary);
+    element.style.setProperty(`--${p}text-secondary`, theme.colors.textSecondary);
+    element.style.setProperty(`--${p}text-muted`, theme.colors.textMuted);
+    // Fonts
+    element.style.setProperty(`--${p}font-heading`, theme.fonts.heading);
+    element.style.setProperty(`--${p}font-body`, theme.fonts.body);
+    element.style.setProperty(`--${p}font-mono`, theme.fonts.mono);
+    // Effects
+    element.style.setProperty(`--${p}shadow-glow`, `0 0 40px ${theme.effects.glowColor}`);
+    element.style.setProperty(`--${p}glow-color`, theme.effects.glowColor);
+    element.style.setProperty(`--${p}glow-intensity`, theme.effects.glowIntensity.toString());
+}
+/**
+ * Extract font family names from a theme.
+ * Parses CSS font-family values to extract the primary font name.
+ */
+export function extractFonts(theme) {
+    const fonts = [];
+    const fontValues = [theme.fonts.heading, theme.fonts.body, theme.fonts.mono];
+    for (const fontValue of fontValues) {
+        // Extract the first font family from a CSS font-family value
+        // e.g., "'Quicksand', sans-serif" -> "Quicksand"
+        const match = fontValue.match(/^['"]?([^'",]+)/);
+        if (match && match[1]) {
+            const fontName = match[1].trim();
+            // Exclude generic font families
+            if (!['sans-serif', 'serif', 'monospace', 'cursive', 'fantasy', 'system-ui'].includes(fontName.toLowerCase())) {
+                if (!fonts.includes(fontName)) {
+                    fonts.push(fontName);
+                }
+            }
+        }
+    }
+    return fonts;
+}
+/**
+ * Generate Google Fonts preload links for the given font names.
+ */
+export function generateFontPreloadLinks(fonts, config = {}) {
+    const { provider = 'google', weights = {} } = config;
+    if (provider !== 'google' || fonts.length === 0) {
+        return '';
+    }
+    const defaultWeights = {
+        heading: weights.heading || [400, 600, 700],
+        body: weights.body || [400, 500],
+        mono: weights.mono || [400],
+    };
+    // For simplicity, use all weights for each font
+    const allWeights = [...new Set([
+            ...defaultWeights.heading,
+            ...defaultWeights.body,
+            ...defaultWeights.mono,
+        ])].sort((a, b) => a - b);
+    const fontSpecs = fonts.map(font => {
+        const weightStr = allWeights.join(';');
+        return `family=${encodeURIComponent(font)}:wght@${weightStr}`;
+    });
+    const url = `https://fonts.googleapis.com/css2?${fontSpecs.join('&')}&display=swap`;
+    return `<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="${url}">`;
+}
+/**
+ * Generate a blocking script that prevents theme flash on page load.
+ * This script should be placed in the <head> of your HTML before any other scripts.
+ *
+ * The script:
+ * 1. Reads the stored theme from localStorage
+ * 2. Applies CSS variables immediately (before paint)
+ * 3. Optionally adds a 'no-transitions' class to prevent transition animations during hydration
+ * 4. Optionally preloads fonts for the current theme
+ */
+export function generateBlockingScript(config) {
+    const { themes, storageKey = 'svelte-theme-picker', defaultTheme, cssVarPrefix = '', preventTransitions = true, } = config;
+    // Determine the actual default theme
+    const themeIds = Object.keys(themes);
+    const fallbackDefault = defaultTheme && themes[defaultTheme] ? defaultTheme : themeIds[0];
+    // Serialize themes for the blocking script (only what's needed: colors, fonts, effects)
+    const minimalThemes = {};
+    for (const [id, theme] of Object.entries(themes)) {
+        minimalThemes[id] = {
+            colors: theme.colors,
+            fonts: theme.fonts,
+            effects: theme.effects,
+        };
+    }
+    const themesJson = JSON.stringify(minimalThemes);
+    const prefix = cssVarPrefix ? `${cssVarPrefix}-` : '';
+    // Generate the blocking script
+    const script = `(function(){
+var T=${themesJson};
+var k="${storageKey}";
+var d="${fallbackDefault}";
+var p="${prefix}";
+var r=document.documentElement;
+${preventTransitions ? 'r.classList.add("no-transitions");' : ''}
+try{var s=localStorage.getItem(k);if(!s||!T[s])s=d;}catch(e){s=d;}
+var t=T[s];if(t){
+var c=t.colors,f=t.fonts,e=t.effects;
+r.style.setProperty("--"+p+"bg-deep",c.bgDeep);
+r.style.setProperty("--"+p+"bg-mid",c.bgMid);
+r.style.setProperty("--"+p+"bg-card",c.bgCard);
+r.style.setProperty("--"+p+"bg-glow",c.bgGlow);
+r.style.setProperty("--"+p+"bg-overlay",c.bgOverlay);
+r.style.setProperty("--"+p+"primary-1",c.primary1);
+r.style.setProperty("--"+p+"primary-2",c.primary2);
+r.style.setProperty("--"+p+"primary-3",c.primary3);
+r.style.setProperty("--"+p+"primary-4",c.primary4);
+r.style.setProperty("--"+p+"primary-5",c.primary5);
+r.style.setProperty("--"+p+"primary-6",c.primary6);
+r.style.setProperty("--"+p+"accent-1",c.accent1);
+r.style.setProperty("--"+p+"accent-2",c.accent2);
+r.style.setProperty("--"+p+"accent-3",c.accent3);
+r.style.setProperty("--"+p+"text-primary",c.textPrimary);
+r.style.setProperty("--"+p+"text-secondary",c.textSecondary);
+r.style.setProperty("--"+p+"text-muted",c.textMuted);
+r.style.setProperty("--"+p+"font-heading",f.heading);
+r.style.setProperty("--"+p+"font-body",f.body);
+r.style.setProperty("--"+p+"font-mono",f.mono);
+r.style.setProperty("--"+p+"shadow-glow","0 0 40px "+e.glowColor);
+r.style.setProperty("--"+p+"glow-color",e.glowColor);
+r.style.setProperty("--"+p+"glow-intensity",e.glowIntensity);
+r.setAttribute("data-theme",s);
+}})();`;
+    return script;
+}
+/**
+ * Generate a complete SSR script tag that can be inserted into HTML.
+ * Includes the blocking script and optionally font preload links.
+ */
+export function generateSSRHead(config) {
+    const { themes, fonts } = config;
+    const parts = [];
+    // Add font preload links if configured
+    if (fonts) {
+        // Get all unique fonts from all themes
+        const allFonts = new Set();
+        for (const theme of Object.values(themes)) {
+            for (const font of extractFonts(theme)) {
+                allFonts.add(font);
+            }
+        }
+        const fontLinks = generateFontPreloadLinks([...allFonts], fonts);
+        if (fontLinks) {
+            parts.push(fontLinks);
+        }
+    }
+    // Add the blocking script
+    parts.push(`<script>${generateBlockingScript(config)}</script>`);
+    // Add no-transitions CSS if enabled
+    if (config.preventTransitions !== false) {
+        parts.push(`<style>.no-transitions,.no-transitions *,.no-transitions *::before,.no-transitions *::after{transition:none!important;animation:none!important}</style>`);
+    }
+    return parts.join('\n');
+}

package/dist/store.d.ts

@@ -20,6 +20,8 @@ export interface ThemeStore extends Writable<string> {
     revertPreview: () => void;
     /** Check if currently in preview mode */
     isPreviewMode: () => boolean;
+    /** Destroy the store and clean up any listeners (e.g., cross-tab sync) */
+    destroy: () => void;
 }
 /**
  * Create a theme store with the given configuration

package/dist/store.js

@@ -5,7 +5,7 @@ const isBrowser = typeof window !== 'undefined';
  * Create a theme store with the given configuration
  */
 export function createThemeStore(config = {}) {
-    const { storageKey = 'svelte-theme-picker', defaultTheme = DEFAULT_THEME_ID, themes = defaultThemes, } = config;
+    const { storageKey = 'svelte-theme-picker', defaultTheme = DEFAULT_THEME_ID, themes = defaultThemes, syncTabs = false, } = config;
     function getInitialTheme() {
         if (isBrowser) {
             try {
@@ -66,7 +66,29 @@ export function createThemeStore(config = {}) {
             }
         },
         isPreviewMode: () => previewMode,
+        destroy: () => {
+            if (storageEventHandler) {
+                window.removeEventListener('storage', storageEventHandler);
+                storageEventHandler = null;
+            }
+        },
     };
+    // Cross-tab synchronization via storage events
+    let storageEventHandler = null;
+    if (syncTabs && isBrowser) {
+        storageEventHandler = (event) => {
+            if (event.key === storageKey && event.newValue) {
+                const newThemeId = event.newValue;
+                if (themes[newThemeId]) {
+                    persistedThemeId = newThemeId;
+                    currentThemeId = newThemeId;
+                    previewMode = false;
+                    set(newThemeId);
+                }
+            }
+        };
+        window.addEventListener('storage', storageEventHandler);
+    }
     return store;
 }
 /**

package/dist/themes.js

@@ -4,6 +4,7 @@
 export const dreamy = {
     name: 'Dreamy',
     description: 'Soft pastels with dreamy atmosphere',
+    mode: 'dark',
     colors: {
         bgDeep: '#1a1a2e',
         bgMid: '#232342',
@@ -42,6 +43,7 @@ export const dreamy = {
 export const cyberpunk = {
     name: 'Cyberpunk',
     description: 'High contrast neons against dark backgrounds',
+    mode: 'dark',
     colors: {
         bgDeep: '#0a0a0f',
         bgMid: '#12121a',
@@ -80,6 +82,7 @@ export const cyberpunk = {
 export const sunset = {
     name: 'Sunset',
     description: 'Warm oranges and purples like a summer sunset',
+    mode: 'dark',
     colors: {
         bgDeep: '#1a1020',
         bgMid: '#2a1830',
@@ -118,6 +121,7 @@ export const sunset = {
 export const ocean = {
     name: 'Ocean',
     description: 'Deep blues and teals with bioluminescent accents',
+    mode: 'dark',
     colors: {
         bgDeep: '#0a1628',
         bgMid: '#0f2035',
@@ -156,6 +160,7 @@ export const ocean = {
 export const mono = {
     name: 'Mono',
     description: 'Clean monochromatic design with subtle accents',
+    mode: 'dark',
     colors: {
         bgDeep: '#111111',
         bgMid: '#1a1a1a',
@@ -194,6 +199,7 @@ export const mono = {
 export const sakura = {
     name: 'Sakura',
     description: 'Delicate cherry blossom pinks with spring greens',
+    mode: 'dark',
     colors: {
         bgDeep: '#1a1520',
         bgMid: '#251d28',
@@ -232,6 +238,7 @@ export const sakura = {
 export const aurora = {
     name: 'Aurora',
     description: 'Mystical aurora borealis dancing across the sky',
+    mode: 'dark',
     colors: {
         bgDeep: '#0a0f1a',
         bgMid: '#0f1725',
@@ -270,6 +277,7 @@ export const aurora = {
 export const galaxy = {
     name: 'Galaxy',
     description: 'Deep space with distant stars and cosmic nebulae',
+    mode: 'dark',
     colors: {
         bgDeep: '#05050f',
         bgMid: '#0a0a1a',
@@ -308,6 +316,7 @@ export const galaxy = {
 export const milk = {
     name: 'Milk',
     description: 'Clean and creamy whites with warm neutral accents',
+    mode: 'light',
     colors: {
         bgDeep: '#fefefe',
         bgMid: '#faf9f7',
@@ -346,6 +355,7 @@ export const milk = {
 export const light = {
     name: 'Light',
     description: 'A crisp, modern light theme with purple accents',
+    mode: 'light',
     colors: {
         bgDeep: '#ffffff',
         bgMid: '#f8f9fa',

package/dist/types.d.ts

@@ -70,6 +70,8 @@ export interface Theme {
     fonts: ThemeFonts;
     /** Effect configuration */
     effects: ThemeEffects;
+    /** Theme mode for styling adjustments (affects picker UI, shadows, contrast) */
+    mode?: 'light' | 'dark';
 }
 /**
  * Configuration options for the theme picker
@@ -83,6 +85,8 @@ export interface ThemePickerConfig {
     themes?: Record<string, Theme>;
     /** CSS variable prefix (default: none, uses standard names) */
     cssVarPrefix?: string;
+    /** Enable cross-tab synchronization via storage events (default: false) */
+    syncTabs?: boolean;
 }
 /**
  * Metadata for a theme in a catalog
@@ -126,3 +130,46 @@ export interface ThemeFilterOptions {
     /** Exclude themes with ANY of these tags */
     excludeTags?: string[];
 }
+/**
+ * Configuration for SSR blocking script generation
+ */
+export interface SSRConfig {
+    /** All available themes */
+    themes: Record<string, Theme>;
+    /** localStorage key for theme persistence (default: 'svelte-theme-picker-theme') */
+    storageKey?: string;
+    /** Default theme ID if none is stored */
+    defaultTheme?: string;
+    /** CSS variable prefix (default: none) */
+    cssVarPrefix?: string;
+    /** Whether to add no-transitions class during hydration (default: true) */
+    preventTransitions?: boolean;
+    /** Font configuration for preloading */
+    fonts?: FontConfig;
+}
+/**
+ * Configuration for font preloading
+ */
+export interface FontConfig {
+    /** Font provider: 'google', 'local', or 'custom' */
+    provider?: 'google' | 'local' | 'custom';
+    /** Font weights to preload per category */
+    weights?: {
+        heading?: number[];
+        body?: number[];
+        mono?: number[];
+    };
+    /** Custom font URL generator (for 'custom' provider) */
+    getFontUrl?: (fontName: string, weights: number[]) => string;
+}
+/**
+ * CSS variable schema mapping theme properties to CSS variable names
+ */
+export interface ThemeSchema {
+    /** Color property to CSS variable name mapping */
+    colors: Record<keyof ThemeColors, string>;
+    /** Font property to CSS variable name mapping */
+    fonts: Record<keyof ThemeFonts, string>;
+    /** Effect property to CSS variable name mapping */
+    effects: Record<string, string>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-theme-picker",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A beautiful, customizable theme picker component for Svelte applications",
   "license": "MIT",
   "type": "module",