From 25009ca4b129c01ea62d920aa09b338c260f5a9c Mon Sep 17 00:00:00 2001
From: Ian Paschal <ianpaschal@users.noreply.github.com>
Date: Wed, 3 Jun 2026 08:20:10 +0200
Subject: [PATCH 1/5] Improve theme handling particularly for SSR sites

---
 src/components/ThemeProvider/README.md        | 145 ++++++++++++++++++
 .../ThemeProvider/ThemeProvider.hooks.ts      |  24 ++-
 .../ThemeProvider/ThemeProvider.store.ts      |  68 ++++++--
 .../ThemeProvider/ThemeProvider.tsx           |  34 ++--
 .../ThemeProvider/ThemeProvider.types.ts      |   5 +
 src/components/ThemeProvider/index.ts         |   7 +-
 6 files changed, 247 insertions(+), 36 deletions(-)
 create mode 100644 src/components/ThemeProvider/README.md
diff --git a/src/components/ThemeProvider/README.md b/src/components/ThemeProvider/README.md
new file mode 100644
index 0000000..8665d01
--- /dev/null
+++ b/src/components/ThemeProvider/README.md
@@ -0,0 +1,145 @@
+### How It Works
+
+`ThemeProvider` manages the active theme by generating CSS custom properties into a `<style>` block in `<head>` and switching themes via a `data-theme` attribute on `<html>`.
+
+At registration time, each theme's CSS variables are pre-computed and cached.
+`getThemeStyleSheet()` serializes all registered themes into a single CSS block scoped by `:root[data-theme="<key>"]`.
+Switching themes is a single `setAttribute` call rather than N `setProperty` calls.
+
+The active theme key is persisted to `localStorage` under `THEME_STORAGE_KEY` (`"cc-theme"`).
+A blocking preflight script (`injectThemePreflight()`) can be dropped into `<head>` to apply the saved theme before first paint.
+This avoids a flash of unstyled content on first paint.
+
+### Basic Usage
+
+Wrap your app in `ThemeProvider`.
+No other setup is needed for React apps.
+The stylesheet is injected automatically on mount.
+
+```tsx
+import { ThemeProvider } from '@ianpaschal/combat-command-components';
+
+export const App = () => (
+  <ThemeProvider>
+    <YourApp />
+  </ThemeProvider>
+);
+```
+
+To lock a specific theme (e.g. in a preview or demo), pass the `theme` prop:
+
+```tsx
+<ThemeProvider theme="dark">
+  <YourApp />
+</ThemeProvider>
+```
+
+### Built-In Themes
+
+| Key | Display Name | Dark |
+|---|---|---|
+| `light` | Light | No |
+| `dark` | Dark | Yes |
+| `daybreak` | Daybreak | No |
+| `midnight` | Midnight | Yes |
+
+`SYSTEM_THEME_KEY` (`"__system"`) resolves to `dark` or `light` based on `prefers-color-scheme`.
+It is the default when no preference is stored.
+
+### Accessing the Theme in a Component
+
+```tsx
+import { useThemeManager } from '@ianpaschal/combat-command-components';
+
+const { key, theme, options, setTheme } = useThemeManager();
+```
+
+| Property | Type | Description |
+|---|---|---|
+| `key` | `string` | The active key, including `"__system"` if no explicit choice was made. |
+| `theme` | `Theme` | The resolved `Theme` object. |
+| `options` | `SelectOption[]` | All registered themes plus the system option, ready for a `<Select>`. |
+| `setTheme` | `(key: string) => void` | Updates the active theme and persists it to localStorage. |
+
+### Registering a Custom Theme
+
+Call `registerTheme` before the app mounts.
+Each registered theme is merged on top of a parent (defaults to `light`).
+
+```ts
+import { registerTheme } from '@ianpaschal/combat-command-components';
+
+registerTheme('branded', {
+  displayName: 'Branded',
+  dark: false,
+  surface: {
+    page: { bg: '#f0e8ff' },
+    card: { bg: '#ffffff', border: '#d8c8f0' },
+  },
+  colors: {
+    accent: { bg: '#7c3aed', text: '#ffffff', focus: '#7c3aed' },
+  },
+});
+```
+
+Custom themes registered before `getThemeStyleSheet()` is first called are included in the generated stylesheet.
+
+### SSR / Static Sites (e.g. Astro)
+
+For server-rendered pages, inject the stylesheet and preflight script into `<head>` before any content renders:
+
+```astro
+---
+import {
+  getThemeStyleSheet,
+  injectThemePreflight,
+} from '@ianpaschal/combat-command-components';
+
+const themeCSS = getThemeStyleSheet();
+---
+<head>
+  <!-- Inject CSS vars for all themes, scoped to :root[data-theme]. -->
+  <style is:inline set:html={themeCSS}></style>
+  <!-- Blocking script: reads localStorage and sets data-theme before first paint. -->
+  <script is:inline set:html={injectThemePreflight()}></script>
+</head>
+```
+
+The `<style>` tag carries a `data-theme-vars` attribute so the client-side `ThemeProvider` won't inject a duplicate.
+
+### API Reference
+
+#### `ThemeProvider`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `theme` | `string` | - | Locks the active theme; overrides user selection and localStorage. |
+| `children` | `ReactNode` | - | |
+
+#### `getThemeStyleSheet(): string`
+
+Serializes all registered themes' CSS variables into a single CSS string scoped by `:root[data-theme="<key>"]`.
+In a browser context, also injects the result as a `<style data-theme-vars>` element in `<head>` (idempotent).
+Returns the CSS string.
+
+#### `injectThemePreflight(): string`
+
+Returns a self-executing script string that reads `localStorage.getItem("cc-theme")` and sets `data-theme` on `<html>` before first paint.
+If no key is stored or the stored key is `"__system"`, it falls back to `prefers-color-scheme`.
+Drop the returned string into a blocking `<script>` in `<head>`.
+
+#### `registerTheme(key, theme, parentKey?)`
+
+Registers a new theme or overrides an existing one.
+`theme` is deep-merged onto `parentKey` (Default: `"light"`).
+CSS variables are computed and cached immediately.
+
+#### `THEME_STORAGE_KEY`
+
+The localStorage key used to persist the active theme choice (`"cc-theme"`).
+Use this if you need to read or write the preference outside of `ThemeProvider`.
+
+#### `SYSTEM_THEME_KEY`
+
+The sentinel value (`"__system"`) that resolves to `"light"` or `"dark"` based on `prefers-color-scheme`.
+Passed to `setTheme` to restore automatic OS-based switching.
diff --git a/src/components/ThemeProvider/ThemeProvider.hooks.ts b/src/components/ThemeProvider/ThemeProvider.hooks.ts
index 6417390..00f54ef 100644
--- a/src/components/ThemeProvider/ThemeProvider.hooks.ts
+++ b/src/components/ThemeProvider/ThemeProvider.hooks.ts
@@ -1,7 +1,6 @@
 import {
   useContext,
   useEffect,
-  useLayoutEffect,
   useState,
 } from 'react';
 import { useStore } from '@tanstack/react-store';
@@ -10,11 +9,10 @@ import { light } from './themes/light';
 import { themeContext } from './ThemeProvider.context';
 import { themeStore } from './ThemeProvider.store';
 import { Theme } from './ThemeProvider.types';
-import { buildThemeVars } from './ThemeProvider.utils';
 
 export const SYSTEM_THEME_KEY = '__system';
 
-export const useResolvedTheme = (activeKey: string): Theme => {
+export const useResolvedTheme = (activeKey: string): { theme: Theme; resolvedKey: string } => {
   const registry = useStore(themeStore);
   const [isDark, setIsDark] = useState(() => window.matchMedia('(prefers-color-scheme: dark)').matches);
 
@@ -26,18 +24,16 @@ export const useResolvedTheme = (activeKey: string): Theme => {
   }, []);
 
   if (activeKey === SYSTEM_THEME_KEY) {
-    return isDark ? (registry['dark'] ?? registry['light'] ?? light) : (registry['light'] ?? light);
+    const resolvedKey = isDark ? 'dark' : 'light';
+    return {
+      theme: registry[resolvedKey]?.theme ?? registry['light']?.theme ?? light,
+      resolvedKey,
+    };
   }
-  return registry[activeKey] ?? registry['light'] ?? light;
+  return {
+    theme: registry[activeKey]?.theme ?? registry['light']?.theme ?? light,
+    resolvedKey: activeKey,
+  };
 };
 
 export const useThemeManager = () => useContext(themeContext);
-
-export const useThemeVars = (theme: Theme): void => {
-  useLayoutEffect(() => {
-    const vars = buildThemeVars(theme);
-    for (const [key, value] of Object.entries(vars)) {
-      document.body.style.setProperty(key, value);
-    }
-  }, [theme]);
-};
diff --git a/src/components/ThemeProvider/ThemeProvider.store.ts b/src/components/ThemeProvider/ThemeProvider.store.ts
index f8f2d7b..ba60d6c 100644
--- a/src/components/ThemeProvider/ThemeProvider.store.ts
+++ b/src/components/ThemeProvider/ThemeProvider.store.ts
@@ -6,27 +6,73 @@ import { daybreak } from './themes/daybreak';
 import { light } from './themes/light';
 import { midnight } from './themes/midnight';
 import { DeepPartial } from '../../types';
-import { Theme } from './ThemeProvider.types';
+import { Theme, ThemeRegistryEntry } from './ThemeProvider.types';
+import { buildThemeVars } from './ThemeProvider.utils';
 
-export const themeStore = new Store<Record<string, Theme>>({
-  light,
-  dark,
-  daybreak,
-  midnight,
+export const THEME_STORAGE_KEY = 'cc-theme';
+
+const makeEntry = (theme: Theme): ThemeRegistryEntry => ({
+  theme,
+  vars: buildThemeVars(theme),
+});
+
+export const themeStore = new Store<Record<string, ThemeRegistryEntry>>({
+  light: makeEntry(light),
+  dark: makeEntry(dark),
+  daybreak: makeEntry(daybreak),
+  midnight: makeEntry(midnight),
 });
 
 export const registerTheme = (key: string, theme: DeepPartial<Theme>, parentKey?: string): void => {
   themeStore.setState((state) => {
-    const parent = parentKey ? (state[parentKey] ?? light) : light;
-    return { ...state, [key]: deepmerge(parent, theme as Theme) };
+    const parent = parentKey ? (state[parentKey]?.theme ?? light) : light;
+    const merged = deepmerge(parent, theme as Theme);
+    return { ...state, [key]: makeEntry(merged) };
   });
 };
 
 export const getRegisteredTheme = (key: string): Theme => {
-  const theme = themeStore.state[key];
-  if (!theme) {
+  const entry = themeStore.state[key];
+  if (!entry) {
     console.warn(`Could not find a theme with key ${key}. Will use 'light' instead.`);
     return light;
   }
-  return theme;
+  return entry.theme;
+};
+
+export const getThemeStyleSheet = (): string => {
+  const css = Object.entries(themeStore.state).map(([key, { vars }]) => {
+    const declarations = Object.entries(vars).map(([k, v]) => `  ${k}: ${v};`).join('\n');
+    return `:root[data-theme="${key}"] {\n${declarations}\n}`;
+  }).join('\n\n');
+
+  if (typeof document !== 'undefined') {
+    const existing = document.querySelector('style[data-theme-vars]');
+    if (!existing) {
+      const style = document.createElement('style');
+      style.setAttribute('data-theme-vars', '');
+      style.textContent = css;
+      document.head.appendChild(style);
+    }
+  }
+
+  return css;
+};
+
+export const injectThemePreflight = (defaults?: { dark?: string; light?: string }): string => {
+  const dark = defaults?.dark ?? 'dark';
+  const light = defaults?.light ?? 'light';
+  return (
+    `(function(){` +
+    `function a(){` +
+    `var k=localStorage.getItem('${THEME_STORAGE_KEY}')||'__system';` +
+    `if(k==='__system'){k=window.matchMedia('(prefers-color-scheme: dark)').matches?'${dark}':'${light}';}` +
+    `document.documentElement.setAttribute('data-theme',k);` +
+    `}` +
+    `a();` +
+    `new MutationObserver(function(ms){ms.forEach(function(m){` +
+    `if(m.attributeName==='data-theme'&&!document.documentElement.getAttribute('data-theme'))a();` +
+    `});}).observe(document.documentElement,{attributes:true,attributeFilter:['data-theme']});` +
+    `})();`
+  );
 };
diff --git a/src/components/ThemeProvider/ThemeProvider.tsx b/src/components/ThemeProvider/ThemeProvider.tsx
index 893d73c..39621eb 100644
--- a/src/components/ThemeProvider/ThemeProvider.tsx
+++ b/src/components/ThemeProvider/ThemeProvider.tsx
@@ -1,17 +1,18 @@
 import {
   ReactNode,
+  useLayoutEffect,
   useMemo,
   useState,
 } from 'react';
 import { useStore } from '@tanstack/react-store';
 
 import { ThemeContextProvider } from './ThemeProvider.context';
+import { SYSTEM_THEME_KEY, useResolvedTheme } from './ThemeProvider.hooks';
 import {
-  SYSTEM_THEME_KEY,
-  useResolvedTheme,
-  useThemeVars,
-} from './ThemeProvider.hooks';
-import { themeStore } from './ThemeProvider.store';
+  getThemeStyleSheet,
+  THEME_STORAGE_KEY,
+  themeStore,
+} from './ThemeProvider.store';
 
 export interface ThemeProviderProps {
 
@@ -24,22 +25,35 @@ export const ThemeProvider = ({
   theme: forcedTheme,
   children,
 }: ThemeProviderProps) => {
-  const [key, setKey] = useState(SYSTEM_THEME_KEY);
+  const [key, setKey] = useState(() => localStorage.getItem(THEME_STORAGE_KEY) ?? SYSTEM_THEME_KEY);
   const activeKey = forcedTheme ?? key;
-  const theme = useResolvedTheme(activeKey);
+  const { theme, resolvedKey } = useResolvedTheme(activeKey);
   const registry = useStore(themeStore);
   const options = useMemo(() => [
     { value: SYSTEM_THEME_KEY, label: 'System' },
-    ...Object.entries(registry).map(([k, { displayName }]) => ({
+    ...Object.entries(registry).map(([k, { theme: { displayName } }]) => ({
       value: k,
       label: displayName,
     })),
   ], [registry]);
 
-  useThemeVars(theme);
+  useLayoutEffect(() => {
+    getThemeStyleSheet();
+  }, []);
+
+  useLayoutEffect(() => {
+    document.documentElement.setAttribute('data-theme', resolvedKey);
+  }, [resolvedKey]);
+
+  const handleSetTheme = (newKey: string) => {
+    if (!forcedTheme) {
+      localStorage.setItem(THEME_STORAGE_KEY, newKey);
+    }
+    setKey(newKey);
+  };
 
   return (
-    <ThemeContextProvider value={{ key: activeKey, theme, options, setTheme: setKey }}>
+    <ThemeContextProvider value={{ key: activeKey, theme, options, setTheme: handleSetTheme }}>
       {children}
     </ThemeContextProvider>
   );
diff --git a/src/components/ThemeProvider/ThemeProvider.types.ts b/src/components/ThemeProvider/ThemeProvider.types.ts
index 113d744..798a481 100644
--- a/src/components/ThemeProvider/ThemeProvider.types.ts
+++ b/src/components/ThemeProvider/ThemeProvider.types.ts
@@ -1,5 +1,10 @@
 import { ThemeColor } from '../../types';
 
+export type ThemeRegistryEntry = {
+  theme: Theme;
+  vars: Record<string, string>;
+};
+
 export type Theme = {
   displayName: string;
   dark: boolean;
diff --git a/src/components/ThemeProvider/index.ts b/src/components/ThemeProvider/index.ts
index dc7958b..f543b6b 100644
--- a/src/components/ThemeProvider/index.ts
+++ b/src/components/ThemeProvider/index.ts
@@ -6,7 +6,12 @@ export {
   SYSTEM_THEME_KEY,
   useThemeManager,
 } from './ThemeProvider.hooks';
-export { registerTheme } from './ThemeProvider.store';
+export {
+  getThemeStyleSheet,
+  injectThemePreflight,
+  registerTheme,
+  THEME_STORAGE_KEY,
+} from './ThemeProvider.store';
 export type { Theme } from './ThemeProvider.types';
 export { dark } from './themes/dark';
 export { light } from './themes/light';

From 2538ea2cb2b814673e2b9b7a234d1542c74902fc Mon Sep 17 00:00:00 2001
From: Ian Paschal <ianpaschal@users.noreply.github.com>
Date: Wed, 3 Jun 2026 09:01:25 +0200
Subject: [PATCH 2/5] PR Feedback

---
 src/components/ThemeProvider/README.md        | 22 +++++++++++++++++--
 .../ThemeProvider/ThemeProvider.hooks.ts      |  9 +++++++-
 .../ThemeProvider/ThemeProvider.store.ts      | 22 ++++++++++---------
 .../ThemeProvider/ThemeProvider.tsx           | 11 +++++++---
 4 files changed, 48 insertions(+), 16 deletions(-)

diff --git a/src/components/ThemeProvider/README.md b/src/components/ThemeProvider/README.md
index 8665d01..1229f9f 100644
--- a/src/components/ThemeProvider/README.md
+++ b/src/components/ThemeProvider/README.md
@@ -122,10 +122,28 @@ Serializes all registered themes' CSS variables into a single CSS string scoped
 In a browser context, also injects the result as a `<style data-theme-vars>` element in `<head>` (idempotent).
 Returns the CSS string.
 
-#### `injectThemePreflight(): string`
+#### `injectThemePreflight(defaults?): string`
 
 Returns a self-executing script string that reads `localStorage.getItem("cc-theme")` and sets `data-theme` on `<html>` before first paint.
-If no key is stored or the stored key is `"__system"`, it falls back to `prefers-color-scheme`.
+If no key is stored or the stored key is `"__system"`, it falls back to `prefers-color-scheme`, mapping to the resolved theme keys.
+
+`defaults` is an optional object that overrides the theme keys used when the stored value is `"__system"`:
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `dark` | `string` | `"dark"` | The theme key applied when `prefers-color-scheme: dark` matches. |
+| `light` | `string` | `"light"` | The theme key applied otherwise. |
+
+When omitted, `"dark"` and `"light"` are used.
+
+```ts
+// Use built-in keys (dark → "dark", light → "light")
+injectThemePreflight()
+
+// Map system dark/light to custom registered keys
+injectThemePreflight({ dark: 'midnight', light: 'daybreak' })
+```
+
 Drop the returned string into a blocking `<script>` in `<head>`.
 
 #### `registerTheme(key, theme, parentKey?)`
diff --git a/src/components/ThemeProvider/ThemeProvider.hooks.ts b/src/components/ThemeProvider/ThemeProvider.hooks.ts
index 00f54ef..fac376c 100644
--- a/src/components/ThemeProvider/ThemeProvider.hooks.ts
+++ b/src/components/ThemeProvider/ThemeProvider.hooks.ts
@@ -1,6 +1,7 @@
 import {
   useContext,
   useEffect,
+  useLayoutEffect,
   useState,
 } from 'react';
 import { useStore } from '@tanstack/react-store';
@@ -14,7 +15,13 @@ export const SYSTEM_THEME_KEY = '__system';
 
 export const useResolvedTheme = (activeKey: string): { theme: Theme; resolvedKey: string } => {
   const registry = useStore(themeStore);
-  const [isDark, setIsDark] = useState(() => window.matchMedia('(prefers-color-scheme: dark)').matches);
+  const [isDark, setIsDark] = useState(() => (
+    typeof window !== 'undefined' && window.matchMedia('(prefers-color-scheme: dark)').matches
+  ));
+
+  useLayoutEffect(() => {
+    setIsDark(window.matchMedia('(prefers-color-scheme: dark)').matches);
+  }, []);
 
   useEffect(() => {
     const mq = window.matchMedia('(prefers-color-scheme: dark)');
diff --git a/src/components/ThemeProvider/ThemeProvider.store.ts b/src/components/ThemeProvider/ThemeProvider.store.ts
index ba60d6c..edf2579 100644
--- a/src/components/ThemeProvider/ThemeProvider.store.ts
+++ b/src/components/ThemeProvider/ThemeProvider.store.ts
@@ -48,7 +48,9 @@ export const getThemeStyleSheet = (): string => {
 
   if (typeof document !== 'undefined') {
     const existing = document.querySelector('style[data-theme-vars]');
-    if (!existing) {
+    if (existing) {
+      existing.textContent = css;
+    } else {
       const style = document.createElement('style');
       style.setAttribute('data-theme-vars', '');
       style.textContent = css;
@@ -63,16 +65,16 @@ export const injectThemePreflight = (defaults?: { dark?: string; light?: string
   const dark = defaults?.dark ?? 'dark';
   const light = defaults?.light ?? 'light';
   return (
-    `(function(){` +
-    `function a(){` +
+    '(function(){' +
+    'function a(){' +
     `var k=localStorage.getItem('${THEME_STORAGE_KEY}')||'__system';` +
     `if(k==='__system'){k=window.matchMedia('(prefers-color-scheme: dark)').matches?'${dark}':'${light}';}` +
-    `document.documentElement.setAttribute('data-theme',k);` +
-    `}` +
-    `a();` +
-    `new MutationObserver(function(ms){ms.forEach(function(m){` +
-    `if(m.attributeName==='data-theme'&&!document.documentElement.getAttribute('data-theme'))a();` +
-    `});}).observe(document.documentElement,{attributes:true,attributeFilter:['data-theme']});` +
-    `})();`
+    'document.documentElement.setAttribute(\'data-theme\',k);' +
+    '}' +
+    'a();' +
+    'new MutationObserver(function(ms){ms.forEach(function(m){' +
+    'if(m.attributeName===\'data-theme\'&&!document.documentElement.getAttribute(\'data-theme\'))a();' +
+    '});}).observe(document.documentElement,{attributes:true,attributeFilter:[\'data-theme\']});' +
+    '})();'
   );
 };
diff --git a/src/components/ThemeProvider/ThemeProvider.tsx b/src/components/ThemeProvider/ThemeProvider.tsx
index 39621eb..17128a7 100644
--- a/src/components/ThemeProvider/ThemeProvider.tsx
+++ b/src/components/ThemeProvider/ThemeProvider.tsx
@@ -1,5 +1,6 @@
 import {
   ReactNode,
+  useEffect,
   useLayoutEffect,
   useMemo,
   useState,
@@ -14,6 +15,8 @@ import {
   themeStore,
 } from './ThemeProvider.store';
 
+const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+
 export interface ThemeProviderProps {
 
   /** Locks the active theme; overrides user selection and any setTheme calls. */
@@ -25,7 +28,9 @@ export const ThemeProvider = ({
   theme: forcedTheme,
   children,
 }: ThemeProviderProps) => {
-  const [key, setKey] = useState(() => localStorage.getItem(THEME_STORAGE_KEY) ?? SYSTEM_THEME_KEY);
+  const [key, setKey] = useState(() => (
+    typeof window !== 'undefined' ? (localStorage.getItem(THEME_STORAGE_KEY) ?? SYSTEM_THEME_KEY) : SYSTEM_THEME_KEY
+  ));
   const activeKey = forcedTheme ?? key;
   const { theme, resolvedKey } = useResolvedTheme(activeKey);
   const registry = useStore(themeStore);
@@ -37,11 +42,11 @@ export const ThemeProvider = ({
     })),
   ], [registry]);
 
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     getThemeStyleSheet();
   }, []);
 
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     document.documentElement.setAttribute('data-theme', resolvedKey);
   }, [resolvedKey]);
 

From c3234b18305d45582a3cd4428a2a8ef94a25e2a6 Mon Sep 17 00:00:00 2001
From: Ian Paschal <ianpaschal@users.noreply.github.com>
Date: Wed, 3 Jun 2026 09:33:23 +0200
Subject: [PATCH 3/5] More Code Review

---
 .../ThemeProvider/ThemeProvider.constants.ts          |  2 ++
 src/components/ThemeProvider/ThemeProvider.hooks.ts   |  3 +--
 src/components/ThemeProvider/ThemeProvider.store.ts   |  7 +++----
 src/components/ThemeProvider/ThemeProvider.tsx        | 11 ++++-------
 src/components/ThemeProvider/index.ts                 |  7 ++-----
 5 files changed, 12 insertions(+), 18 deletions(-)
 create mode 100644 src/components/ThemeProvider/ThemeProvider.constants.ts

diff --git a/src/components/ThemeProvider/ThemeProvider.constants.ts b/src/components/ThemeProvider/ThemeProvider.constants.ts
new file mode 100644
index 0000000..61aaac8
--- /dev/null
+++ b/src/components/ThemeProvider/ThemeProvider.constants.ts
@@ -0,0 +1,2 @@
+export const THEME_STORAGE_KEY = 'cc-theme';
+export const SYSTEM_THEME_KEY = '__system';
diff --git a/src/components/ThemeProvider/ThemeProvider.hooks.ts b/src/components/ThemeProvider/ThemeProvider.hooks.ts
index fac376c..1d8f4da 100644
--- a/src/components/ThemeProvider/ThemeProvider.hooks.ts
+++ b/src/components/ThemeProvider/ThemeProvider.hooks.ts
@@ -7,12 +7,11 @@ import {
 import { useStore } from '@tanstack/react-store';
 
 import { light } from './themes/light';
+import { SYSTEM_THEME_KEY } from './ThemeProvider.constants';
 import { themeContext } from './ThemeProvider.context';
 import { themeStore } from './ThemeProvider.store';
 import { Theme } from './ThemeProvider.types';
 
-export const SYSTEM_THEME_KEY = '__system';
-
 export const useResolvedTheme = (activeKey: string): { theme: Theme; resolvedKey: string } => {
   const registry = useStore(themeStore);
   const [isDark, setIsDark] = useState(() => (
diff --git a/src/components/ThemeProvider/ThemeProvider.store.ts b/src/components/ThemeProvider/ThemeProvider.store.ts
index edf2579..805de35 100644
--- a/src/components/ThemeProvider/ThemeProvider.store.ts
+++ b/src/components/ThemeProvider/ThemeProvider.store.ts
@@ -6,11 +6,10 @@ import { daybreak } from './themes/daybreak';
 import { light } from './themes/light';
 import { midnight } from './themes/midnight';
 import { DeepPartial } from '../../types';
+import { SYSTEM_THEME_KEY, THEME_STORAGE_KEY } from './ThemeProvider.constants';
 import { Theme, ThemeRegistryEntry } from './ThemeProvider.types';
 import { buildThemeVars } from './ThemeProvider.utils';
 
-export const THEME_STORAGE_KEY = 'cc-theme';
-
 const makeEntry = (theme: Theme): ThemeRegistryEntry => ({
   theme,
   vars: buildThemeVars(theme),
@@ -67,8 +66,8 @@ export const injectThemePreflight = (defaults?: { dark?: string; light?: string
   return (
     '(function(){' +
     'function a(){' +
-    `var k=localStorage.getItem('${THEME_STORAGE_KEY}')||'__system';` +
-    `if(k==='__system'){k=window.matchMedia('(prefers-color-scheme: dark)').matches?'${dark}':'${light}';}` +
+    `var k=localStorage.getItem('${THEME_STORAGE_KEY}')||'${SYSTEM_THEME_KEY}';` +
+    `if(k==='${SYSTEM_THEME_KEY}'){k=window.matchMedia('(prefers-color-scheme: dark)').matches?'${dark}':'${light}';}` +
     'document.documentElement.setAttribute(\'data-theme\',k);' +
     '}' +
     'a();' +
diff --git a/src/components/ThemeProvider/ThemeProvider.tsx b/src/components/ThemeProvider/ThemeProvider.tsx
index 17128a7..efdf270 100644
--- a/src/components/ThemeProvider/ThemeProvider.tsx
+++ b/src/components/ThemeProvider/ThemeProvider.tsx
@@ -7,13 +7,10 @@ import {
 } from 'react';
 import { useStore } from '@tanstack/react-store';
 
+import { SYSTEM_THEME_KEY, THEME_STORAGE_KEY } from './ThemeProvider.constants';
 import { ThemeContextProvider } from './ThemeProvider.context';
-import { SYSTEM_THEME_KEY, useResolvedTheme } from './ThemeProvider.hooks';
-import {
-  getThemeStyleSheet,
-  THEME_STORAGE_KEY,
-  themeStore,
-} from './ThemeProvider.store';
+import { useResolvedTheme } from './ThemeProvider.hooks';
+import { getThemeStyleSheet, themeStore } from './ThemeProvider.store';
 
 const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
 
@@ -53,8 +50,8 @@ export const ThemeProvider = ({
   const handleSetTheme = (newKey: string) => {
     if (!forcedTheme) {
       localStorage.setItem(THEME_STORAGE_KEY, newKey);
+      setKey(newKey);
     }
-    setKey(newKey);
   };
 
   return (
diff --git a/src/components/ThemeProvider/index.ts b/src/components/ThemeProvider/index.ts
index f543b6b..d7dc73c 100644
--- a/src/components/ThemeProvider/index.ts
+++ b/src/components/ThemeProvider/index.ts
@@ -2,15 +2,12 @@ export {
   ThemeProvider,
   type ThemeProviderProps,
 } from './ThemeProvider';
-export {
-  SYSTEM_THEME_KEY,
-  useThemeManager,
-} from './ThemeProvider.hooks';
+export { SYSTEM_THEME_KEY, THEME_STORAGE_KEY } from './ThemeProvider.constants';
+export { useThemeManager } from './ThemeProvider.hooks';
 export {
   getThemeStyleSheet,
   injectThemePreflight,
   registerTheme,
-  THEME_STORAGE_KEY,
 } from './ThemeProvider.store';
 export type { Theme } from './ThemeProvider.types';
 export { dark } from './themes/dark';

From 65ed32c2197567c8105d4ae77caf6b3896fc7e84 Mon Sep 17 00:00:00 2001
From: Ian Paschal <ianpaschal@users.noreply.github.com>
Date: Wed, 3 Jun 2026 11:12:51 +0200
Subject: [PATCH 4/5] Even More Code Review

---
 .../ThemeProvider/ThemeProvider.hooks.ts      | 13 +++
 .../ThemeProvider/ThemeProvider.store.ts      | 86 +++++++++++++++----
 .../ThemeProvider/ThemeProvider.tsx           |  2 +-
 3 files changed, 84 insertions(+), 17 deletions(-)

diff --git a/src/components/ThemeProvider/ThemeProvider.hooks.ts b/src/components/ThemeProvider/ThemeProvider.hooks.ts
index 1d8f4da..40bcc6c 100644
--- a/src/components/ThemeProvider/ThemeProvider.hooks.ts
+++ b/src/components/ThemeProvider/ThemeProvider.hooks.ts
@@ -12,6 +12,15 @@ import { themeContext } from './ThemeProvider.context';
 import { themeStore } from './ThemeProvider.store';
 import { Theme } from './ThemeProvider.types';
 
+/**
+ * Resolves an active theme key to a `Theme` object and a concrete registry key.
+ * Handles `SYSTEM_THEME_KEY` by mapping it to `"dark"` or `"light"` based on
+ * `prefers-color-scheme`, and subscribes to OS preference changes.
+ *
+ * @param activeKey - The active theme key, which may be `SYSTEM_THEME_KEY`.
+ * @returns The resolved `Theme` object and the concrete key (never
+ *   `SYSTEM_THEME_KEY`).
+ */
 export const useResolvedTheme = (activeKey: string): { theme: Theme; resolvedKey: string } => {
   const registry = useStore(themeStore);
   const [isDark, setIsDark] = useState(() => (
@@ -42,4 +51,8 @@ export const useResolvedTheme = (activeKey: string): { theme: Theme; resolvedKey
   };
 };
 
+/**
+ * Returns the theme context value from the nearest `ThemeProvider`, exposing
+ * the active key, resolved `Theme` object, available options, and `setTheme`.
+ */
 export const useThemeManager = () => useContext(themeContext);
diff --git a/src/components/ThemeProvider/ThemeProvider.store.ts b/src/components/ThemeProvider/ThemeProvider.store.ts
index 805de35..69a3cb9 100644
--- a/src/components/ThemeProvider/ThemeProvider.store.ts
+++ b/src/components/ThemeProvider/ThemeProvider.store.ts
@@ -22,7 +22,21 @@ export const themeStore = new Store<Record<string, ThemeRegistryEntry>>({
   midnight: makeEntry(midnight),
 });
 
-export const registerTheme = (key: string, theme: DeepPartial<Theme>, parentKey?: string): void => {
+/**
+ * Registers a new theme or overrides an existing one. The provided theme is
+ * deep-merged onto the parent (defaults to `light`). CSS variables are computed
+ * and cached immediately.
+ *
+ * @param key - Unique key used to identify and activate the theme.
+ * @param theme - Partial theme object; missing values are inherited from the
+ *   parent.
+ * @param parentKey - Key of the theme to inherit from. Defaults to `"light"`.
+ */
+export const registerTheme = (
+  key: string,
+  theme: DeepPartial<Theme>,
+  parentKey?: string,
+): void => {
   themeStore.setState((state) => {
     const parent = parentKey ? (state[parentKey]?.theme ?? light) : light;
     const merged = deepmerge(parent, theme as Theme);
@@ -30,6 +44,12 @@ export const registerTheme = (key: string, theme: DeepPartial<Theme>, parentKey?
   });
 };
 
+/**
+ * Returns the resolved `Theme` object for the given key. Falls back to `light`
+ * and logs a warning if the key is not registered.
+ *
+ * @param key - Key of the registered theme to retrieve.
+ */
 export const getRegisteredTheme = (key: string): Theme => {
   const entry = themeStore.state[key];
   if (!entry) {
@@ -39,9 +59,19 @@ export const getRegisteredTheme = (key: string): Theme => {
   return entry.theme;
 };
 
+/**
+ * Serializes all registered themes' CSS variables into a single stylesheet
+ * string, with each theme scoped to `:root[data-theme="<key>"]`. In a browser
+ * context, also injects or updates a `<style data-theme-vars>` element in
+ * `<head>` (idempotent).
+ *
+ * @returns The generated CSS string.
+ */
 export const getThemeStyleSheet = (): string => {
   const css = Object.entries(themeStore.state).map(([key, { vars }]) => {
-    const declarations = Object.entries(vars).map(([k, v]) => `  ${k}: ${v};`).join('\n');
+    const declarations = Object.entries(vars).map(([k, v]) => (
+      `  ${k}: ${v};`
+    )).join('\n');
     return `:root[data-theme="${key}"] {\n${declarations}\n}`;
   }).join('\n\n');
 
@@ -60,20 +90,44 @@ export const getThemeStyleSheet = (): string => {
   return css;
 };
 
-export const injectThemePreflight = (defaults?: { dark?: string; light?: string }): string => {
+/**
+ * Returns a self-executing script string that reads `localStorage` and sets
+ * `data-theme` on `<html>` before first paint, preventing a flash of unstyled
+ * content. Also installs a `MutationObserver` to re-apply the theme if
+ * `data-theme` is removed (e.g. during Astro page transitions). Drop the
+ * returned string into a blocking `<script>` in `<head>`.
+ *
+ * @param defaults - Optional overrides for the theme keys used when the stored
+ *   value is `SYSTEM_THEME_KEY`. Defaults to `{ dark: "dark", light: "light" }`.
+ */
+export const injectThemePreflight = (
+  defaults?: { dark?: string; light?: string },
+): string => {
   const dark = defaults?.dark ?? 'dark';
   const light = defaults?.light ?? 'light';
-  return (
-    '(function(){' +
-    'function a(){' +
-    `var k=localStorage.getItem('${THEME_STORAGE_KEY}')||'${SYSTEM_THEME_KEY}';` +
-    `if(k==='${SYSTEM_THEME_KEY}'){k=window.matchMedia('(prefers-color-scheme: dark)').matches?'${dark}':'${light}';}` +
-    'document.documentElement.setAttribute(\'data-theme\',k);' +
-    '}' +
-    'a();' +
-    'new MutationObserver(function(ms){ms.forEach(function(m){' +
-    'if(m.attributeName===\'data-theme\'&&!document.documentElement.getAttribute(\'data-theme\'))a();' +
-    '});}).observe(document.documentElement,{attributes:true,attributeFilter:[\'data-theme\']});' +
-    '})();'
-  );
+  return `
+    (() => {
+      const applyTheme = () => {
+        var key = '${SYSTEM_THEME_KEY}';
+        try {
+          key = localStorage.getItem('${THEME_STORAGE_KEY}') || '${SYSTEM_THEME_KEY}';
+        } catch(e) {}
+        if (key === '${SYSTEM_THEME_KEY}') {
+          key = window.matchMedia('(prefers-color-scheme: dark)').matches ? '${dark}' : '${light}';
+        }
+        document.documentElement.setAttribute('data-theme', key);
+      };
+      applyTheme();
+      new MutationObserver((mutations) => {
+        mutations.forEach((mutation) => {
+          if (mutation.attributeName === 'data-theme' && !document.documentElement.getAttribute('data-theme')) {
+            applyTheme();
+          }
+        });
+      }).observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ['data-theme'],
+      });
+    })()
+  `;
 };
diff --git a/src/components/ThemeProvider/ThemeProvider.tsx b/src/components/ThemeProvider/ThemeProvider.tsx
index efdf270..2f21e8a 100644
--- a/src/components/ThemeProvider/ThemeProvider.tsx
+++ b/src/components/ThemeProvider/ThemeProvider.tsx
@@ -41,7 +41,7 @@ export const ThemeProvider = ({
 
   useIsomorphicLayoutEffect(() => {
     getThemeStyleSheet();
-  }, []);
+  }, [registry]);
 
   useIsomorphicLayoutEffect(() => {
     document.documentElement.setAttribute('data-theme', resolvedKey);

From af3fd56d9c9f12a22cd1cf47e521709841992112 Mon Sep 17 00:00:00 2001
From: Ian Paschal <ianpaschal@users.noreply.github.com>
Date: Wed, 3 Jun 2026 12:01:12 +0200
Subject: [PATCH 5/5] Still More Code Review

---
 .../ThemeProvider/ThemeProvider.constants.ts      |  8 ++++++++
 .../ThemeProvider/ThemeProvider.hooks.ts          |  4 +++-
 .../ThemeProvider/ThemeProvider.store.ts          | 15 +++++++++++++--
 src/components/ThemeProvider/ThemeProvider.tsx    | 12 ++++++------
 4 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/src/components/ThemeProvider/ThemeProvider.constants.ts b/src/components/ThemeProvider/ThemeProvider.constants.ts
index 61aaac8..5fe2f23 100644
--- a/src/components/ThemeProvider/ThemeProvider.constants.ts
+++ b/src/components/ThemeProvider/ThemeProvider.constants.ts
@@ -1,2 +1,10 @@
 export const THEME_STORAGE_KEY = 'cc-theme';
 export const SYSTEM_THEME_KEY = '__system';
+
+const VALID_THEME_KEY = /^[a-zA-Z0-9_-]+$/;
+
+export const validateKey = (key: string, context: string): void => {
+  if (!VALID_THEME_KEY.test(key)) {
+    throw new Error(`Invalid theme key "${key}" (${context}). Keys must contain only letters, numbers, hyphens, and underscores.`);
+  }
+};
diff --git a/src/components/ThemeProvider/ThemeProvider.hooks.ts b/src/components/ThemeProvider/ThemeProvider.hooks.ts
index 40bcc6c..f4ac8e9 100644
--- a/src/components/ThemeProvider/ThemeProvider.hooks.ts
+++ b/src/components/ThemeProvider/ThemeProvider.hooks.ts
@@ -12,6 +12,8 @@ import { themeContext } from './ThemeProvider.context';
 import { themeStore } from './ThemeProvider.store';
 import { Theme } from './ThemeProvider.types';
 
+export const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+
 /**
  * Resolves an active theme key to a `Theme` object and a concrete registry key.
  * Handles `SYSTEM_THEME_KEY` by mapping it to `"dark"` or `"light"` based on
@@ -27,7 +29,7 @@ export const useResolvedTheme = (activeKey: string): { theme: Theme; resolvedKey
     typeof window !== 'undefined' && window.matchMedia('(prefers-color-scheme: dark)').matches
   ));
 
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     setIsDark(window.matchMedia('(prefers-color-scheme: dark)').matches);
   }, []);
 
diff --git a/src/components/ThemeProvider/ThemeProvider.store.ts b/src/components/ThemeProvider/ThemeProvider.store.ts
index 69a3cb9..998f305 100644
--- a/src/components/ThemeProvider/ThemeProvider.store.ts
+++ b/src/components/ThemeProvider/ThemeProvider.store.ts
@@ -6,7 +6,11 @@ import { daybreak } from './themes/daybreak';
 import { light } from './themes/light';
 import { midnight } from './themes/midnight';
 import { DeepPartial } from '../../types';
-import { SYSTEM_THEME_KEY, THEME_STORAGE_KEY } from './ThemeProvider.constants';
+import {
+  SYSTEM_THEME_KEY,
+  THEME_STORAGE_KEY,
+  validateKey,
+} from './ThemeProvider.constants';
 import { Theme, ThemeRegistryEntry } from './ThemeProvider.types';
 import { buildThemeVars } from './ThemeProvider.utils';
 
@@ -37,7 +41,11 @@ export const registerTheme = (
   theme: DeepPartial<Theme>,
   parentKey?: string,
 ): void => {
+  validateKey(key, 'registerTheme');
   themeStore.setState((state) => {
+    if (parentKey && !state[parentKey]) {
+      console.warn(`registerTheme: parent key "${parentKey}" not found for theme "${key}". Falling back to "light".`);
+    }
     const parent = parentKey ? (state[parentKey]?.theme ?? light) : light;
     const merged = deepmerge(parent, theme as Theme);
     return { ...state, [key]: makeEntry(merged) };
@@ -69,10 +77,11 @@ export const getRegisteredTheme = (key: string): Theme => {
  */
 export const getThemeStyleSheet = (): string => {
   const css = Object.entries(themeStore.state).map(([key, { vars }]) => {
+    const safeKey = key.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
     const declarations = Object.entries(vars).map(([k, v]) => (
       `  ${k}: ${v};`
     )).join('\n');
-    return `:root[data-theme="${key}"] {\n${declarations}\n}`;
+    return `:root[data-theme="${safeKey}"] {\n${declarations}\n}`;
   }).join('\n\n');
 
   if (typeof document !== 'undefined') {
@@ -104,7 +113,9 @@ export const injectThemePreflight = (
   defaults?: { dark?: string; light?: string },
 ): string => {
   const dark = defaults?.dark ?? 'dark';
+  validateKey(dark, 'injectThemePreflight defaults.dark');
   const light = defaults?.light ?? 'light';
+  validateKey(light, 'injectThemePreflight defaults.light');
   return `
     (() => {
       const applyTheme = () => {
diff --git a/src/components/ThemeProvider/ThemeProvider.tsx b/src/components/ThemeProvider/ThemeProvider.tsx
index 2f21e8a..d0387fd 100644
--- a/src/components/ThemeProvider/ThemeProvider.tsx
+++ b/src/components/ThemeProvider/ThemeProvider.tsx
@@ -1,7 +1,5 @@
 import {
   ReactNode,
-  useEffect,
-  useLayoutEffect,
   useMemo,
   useState,
 } from 'react';
@@ -9,11 +7,9 @@ import { useStore } from '@tanstack/react-store';
 
 import { SYSTEM_THEME_KEY, THEME_STORAGE_KEY } from './ThemeProvider.constants';
 import { ThemeContextProvider } from './ThemeProvider.context';
-import { useResolvedTheme } from './ThemeProvider.hooks';
+import { useIsomorphicLayoutEffect, useResolvedTheme } from './ThemeProvider.hooks';
 import { getThemeStyleSheet, themeStore } from './ThemeProvider.store';
 
-const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
-
 export interface ThemeProviderProps {
 
   /** Locks the active theme; overrides user selection and any setTheme calls. */
@@ -49,7 +45,11 @@ export const ThemeProvider = ({
 
   const handleSetTheme = (newKey: string) => {
     if (!forcedTheme) {
-      localStorage.setItem(THEME_STORAGE_KEY, newKey);
+      try {
+        localStorage.setItem(THEME_STORAGE_KEY, newKey);
+      } catch (e) {
+        console.error(e);
+      }
       setKey(newKey);
     }
   };
