@zpress/ui 0.5.0 → 0.5.1

package/dist/head/css/loader-backdrop.css

@@ -0,0 +1 @@
+html:before{content:"";position:fixed;inset:0;background-color:var(--zp-c-bg, #fff);z-index:9998;pointer-events:none;opacity:1;transition:opacity .2s ease}html.zp-loader-fade:before{opacity:0}html[data-zp-ready]:before{display:none}

package/dist/head/css/loader-dots.css

@@ -0,0 +1 @@
+html:after{content:attr(data-zp-loader-text);position:fixed;top:50%;left:50%;width:8em;margin-left:-4em;margin-top:-.5em;text-align:left;color:var(--zp-c-text-2, #888);font-family:Geist Pixel Square,ui-sans-serif,system-ui,sans-serif;font-size:24px;font-weight:400;letter-spacing:.04em;z-index:9999;pointer-events:none;opacity:1;transition:opacity .2s ease}html.zp-loader-fade:after{opacity:0}html[data-zp-ready]:after{display:none}

package/dist/head/css/themes/arcade.css

@@ -0,0 +1 @@
+:root{--zp-c-brand-1: #00ff88;--zp-c-brand-2: #00cc6a;--zp-c-brand-3: #00aa55;--zp-c-brand-soft: rgba(0, 255, 136, .14);--zp-c-bg: #0d0d1a;--zp-c-bg-alt: #10102a;--zp-c-bg-elv: #141433;--zp-c-bg-soft: #18183d;--zp-c-bg-icon: #2a2a55;--zp-c-text-1: #e0ffe0;--zp-c-text-2: rgba(224, 255, 224, .72);--zp-c-text-3: rgba(224, 255, 224, .48);--zp-c-divider: #1a1a40;--zp-c-border: #252560;--zp-c-gutter: #10102a;--zp-code-block-bg: #10102a;--zp-button-brand-bg: #00aa55;--zp-button-brand-hover-bg: #00cc6a;--zp-button-brand-active-bg: #008844;--zp-button-brand-text: #0d0d1a;--rp-c-brand: #00ff88;--rp-c-brand-light: #66ffbb;--rp-c-brand-lighter: #99ffcc;--rp-c-brand-dark: #00cc6a;--rp-c-brand-darker: #00aa55;--rp-c-brand-tint: rgba(0, 255, 136, .14);--rp-home-background-bg: #0d0d1a;--rp-c-bg: #0d0d1a;--rp-c-bg-soft: #18183d;--rp-c-text-1: #e0ffe0;--rp-c-text-2: rgba(224, 255, 224, .72);--rp-c-text-3: rgba(224, 255, 224, .48);--rp-c-divider: #1a1a40}html,body{background-color:var(--zp-c-bg);color:var(--zp-c-text-1)}

package/dist/head/css/themes/base.css

@@ -0,0 +1 @@
+:root{--zp-c-brand-1: #a78bfa;--zp-c-brand-2: #8b5cf6;--zp-c-brand-3: #7c3aed;--zp-c-brand-soft: rgba(167, 139, 250, .14);--zp-c-bg: #ffffff;--zp-c-bg-alt: #f9f9f9;--zp-c-bg-elv: #f5f5f5;--zp-c-bg-soft: #f0f0f0;--zp-c-bg-icon: #cccccc;--zp-c-text-1: #1a1a1a;--zp-c-text-2: rgba(26, 26, 26, .72);--zp-c-text-3: rgba(26, 26, 26, .48);--zp-c-divider: #e2e2e2;--zp-c-border: #d0d0d0;--zp-c-gutter: #f5f5f5;--zp-code-block-bg: #f5f5f5;--zp-button-brand-bg: #7c3aed;--zp-button-brand-hover-bg: #8b5cf6;--zp-button-brand-active-bg: #6d28d9;--zp-button-brand-text: #ffffff;--rp-c-brand: #a78bfa;--rp-c-brand-light: #c4b5fd;--rp-c-brand-lighter: #ddd6fe;--rp-c-brand-dark: #8b5cf6;--rp-c-brand-darker: #7c3aed;--rp-c-brand-tint: rgba(167, 139, 250, .14);--rp-home-background-bg: #fff;--rp-c-bg: #ffffff;--rp-c-bg-soft: #f0f0f0;--rp-c-text-1: #1a1a1a;--rp-c-text-2: rgba(26, 26, 26, .72);--rp-c-text-3: rgba(26, 26, 26, .48);--rp-c-divider: #e2e2e2}html,body{background-color:var(--zp-c-bg);color:var(--zp-c-text-1)}

package/dist/head/css/themes/midnight.css

@@ -0,0 +1 @@
+:root{--zp-c-brand-1: #60a5fa;--zp-c-brand-2: #3b82f6;--zp-c-brand-3: #2563eb;--zp-c-brand-soft: rgba(96, 165, 250, .14);--zp-c-bg: #0f0f0f;--zp-c-bg-alt: #121212;--zp-c-bg-elv: #161616;--zp-c-bg-soft: #1a1a1a;--zp-c-bg-icon: #2a2a2a;--zp-c-text-1: #f0f0f0;--zp-c-text-2: rgba(240, 240, 240, .72);--zp-c-text-3: rgba(240, 240, 240, .48);--zp-c-divider: #1e1e1e;--zp-c-border: #282828;--zp-c-gutter: #121212;--zp-code-block-bg: #121212;--zp-button-brand-bg: #2563eb;--zp-button-brand-hover-bg: #3b82f6;--zp-button-brand-active-bg: #1d4ed8;--zp-button-brand-text: #f0f0f0;--rp-c-brand: #60a5fa;--rp-c-brand-light: #93c5fd;--rp-c-brand-lighter: #bfdbfe;--rp-c-brand-dark: #3b82f6;--rp-c-brand-darker: #2563eb;--rp-c-brand-tint: rgba(96, 165, 250, .14);--rp-home-background-bg: #0f0f0f;--rp-c-bg: #0f0f0f;--rp-c-bg-soft: #1a1a1a;--rp-c-text-1: #f0f0f0;--rp-c-text-2: rgba(240, 240, 240, .72);--rp-c-text-3: rgba(240, 240, 240, .48);--rp-c-divider: #1e1e1e}html,body{background-color:var(--zp-c-bg);color:var(--zp-c-text-1)}

package/dist/head/js/color-mode-dark.js

@@ -0,0 +1 @@
+try{localStorage.setItem("rspress-theme-appearance","dark")}catch{}document.documentElement.classList.add("rp-dark","dark"),document.documentElement.style.colorScheme="dark";

package/dist/head/js/color-mode-light.js

@@ -0,0 +1 @@
+try{localStorage.setItem("rspress-theme-appearance","light")}catch{}document.documentElement.classList.remove("rp-dark","dark"),document.documentElement.style.colorScheme="light";

package/dist/head/js/loader-dots.js

@@ -0,0 +1 @@
+(function(){var t=["loading","loading.","loading..","loading..."],e=0;document.documentElement.dataset.zpLoaderText=t[0],window.__zpDotsInterval=setInterval(function(){e=(e+1)%4,document.documentElement.dataset.zpLoaderText=t[e]},300)})();

package/dist/head/js/vscode-detect.js

@@ -0,0 +1 @@
+try{var s=sessionStorage.getItem("zpress-env"),p=new URLSearchParams(location.search).get("env");(s==="vscode"||p==="vscode")&&(document.documentElement.dataset.zpressEnv="vscode",p==="vscode"&&sessionStorage.setItem("zpress-env","vscode"))}catch{}

package/dist/index.mjs

@@ -2,20 +2,59 @@ import { execSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import node_path from "node:path";
 import { isBuiltInTheme, resolveDefaultColorMode } from "@zpress/theme";
-const BASE_CRITICAL_CSS = ":root{--zp-c-brand-1:#a78bfa;--zp-c-brand-2:#8b5cf6;--zp-c-brand-3:#7c3aed;--zp-c-brand-soft:rgba(167,139,250,0.14);--zp-c-bg:#ffffff;--zp-c-bg-alt:#f9f9f9;--zp-c-bg-elv:#f5f5f5;--zp-c-bg-soft:#f0f0f0;--zp-c-bg-icon:#cccccc;--zp-c-text-1:#1a1a1a;--zp-c-text-2:rgba(26,26,26,0.72);--zp-c-text-3:rgba(26,26,26,0.48);--zp-c-divider:#e2e2e2;--zp-c-border:#d0d0d0;--zp-c-gutter:#f5f5f5;--zp-code-block-bg:#f5f5f5;--zp-button-brand-bg:#7c3aed;--zp-button-brand-hover-bg:#8b5cf6;--zp-button-brand-active-bg:#6d28d9;--zp-button-brand-text:#ffffff;--rp-c-brand:#a78bfa;--rp-c-brand-light:#c4b5fd;--rp-c-brand-lighter:#ddd6fe;--rp-c-brand-dark:#8b5cf6;--rp-c-brand-darker:#7c3aed;--rp-c-brand-tint:rgba(167,139,250,0.14);--rp-home-background-bg:#fff;--rp-c-bg:#ffffff;--rp-c-bg-soft:#f0f0f0;--rp-c-text-1:#1a1a1a;--rp-c-text-2:rgba(26,26,26,0.72);--rp-c-text-3:rgba(26,26,26,0.48);--rp-c-divider:#e2e2e2}html,body{background-color:var(--zp-c-bg);color:var(--zp-c-text-1)}";
-const MIDNIGHT_CRITICAL_CSS = ":root{--zp-c-brand-1:#60a5fa;--zp-c-brand-2:#3b82f6;--zp-c-brand-3:#2563eb;--zp-c-brand-soft:rgba(96,165,250,0.14);--zp-c-bg:#0a0e1a;--zp-c-bg-alt:#0d1120;--zp-c-bg-elv:#111523;--zp-c-bg-soft:#141829;--zp-c-bg-icon:#2d3548;--zp-c-text-1:#e8edf5;--zp-c-text-2:rgba(232,237,245,0.72);--zp-c-text-3:rgba(232,237,245,0.48);--zp-c-divider:#1a1f2e;--zp-c-border:#252a3a;--zp-c-gutter:#0d1120;--zp-code-block-bg:#0d1120;--zp-button-brand-bg:#2563eb;--zp-button-brand-hover-bg:#3b82f6;--zp-button-brand-active-bg:#1d4ed8;--zp-button-brand-text:#e8edf5;--rp-c-brand:#60a5fa;--rp-c-brand-light:#93c5fd;--rp-c-brand-lighter:#bfdbfe;--rp-c-brand-dark:#3b82f6;--rp-c-brand-darker:#2563eb;--rp-c-brand-tint:rgba(96,165,250,0.14);--rp-home-background-bg:#0a0e1a;--rp-c-bg:#0a0e1a;--rp-c-bg-soft:#141829;--rp-c-text-1:#e8edf5;--rp-c-text-2:rgba(232,237,245,0.72);--rp-c-text-3:rgba(232,237,245,0.48);--rp-c-divider:#1a1f2e}html,body{background-color:var(--zp-c-bg);color:var(--zp-c-text-1)}";
-const ARCADE_CRITICAL_CSS = ":root{--zp-c-brand-1:#f472b6;--zp-c-brand-2:#ec4899;--zp-c-brand-3:#db2777;--zp-c-brand-soft:rgba(244,114,182,0.14);--zp-c-bg:#fef7fb;--zp-c-bg-alt:#fef3f9;--zp-c-bg-elv:#fdeef7;--zp-c-bg-soft:#fce9f4;--zp-c-bg-icon:#f9d5ea;--zp-c-text-1:#1a0a14;--zp-c-text-2:rgba(26,10,20,0.72);--zp-c-text-3:rgba(26,10,20,0.48);--zp-c-divider:#fce0f0;--zp-c-border:#fad0e8;--zp-c-gutter:#fef3f9;--zp-code-block-bg:#fef3f9;--zp-button-brand-bg:#db2777;--zp-button-brand-hover-bg:#ec4899;--zp-button-brand-active-bg:#be185d;--zp-button-brand-text:#fef7fb;--rp-c-brand:#f472b6;--rp-c-brand-light:#f9a8d4;--rp-c-brand-lighter:#fbcfe8;--rp-c-brand-dark:#ec4899;--rp-c-brand-darker:#db2777;--rp-c-brand-tint:rgba(244,114,182,0.14);--rp-home-background-bg:#fef7fb;--rp-c-bg:#fef7fb;--rp-c-bg-soft:#fce9f4;--rp-c-text-1:#1a0a14;--rp-c-text-2:rgba(26,10,20,0.72);--rp-c-text-3:rgba(26,10,20,0.48);--rp-c-divider:#fce0f0}html,body{background-color:var(--zp-c-bg);color:var(--zp-c-text-1)}";
-const CRITICAL_CSS_MAP = {
-    base: BASE_CRITICAL_CSS,
-    midnight: MIDNIGHT_CRITICAL_CSS,
-    arcade: ARCADE_CRITICAL_CSS,
-    'arcade-fx': ARCADE_CRITICAL_CSS
+function resolveAsset(relativePath) {
+    return node_path.resolve(import.meta.dirname, 'head', relativePath);
+}
+function readAsset(relativePath) {
+    const fullPath = resolveAsset(relativePath);
+    try {
+        const content = readFileSync(fullPath, 'utf8').trim();
+        return [
+            null,
+            content
+        ];
+    } catch  {
+        const error = {
+            _tag: 'AssetError',
+            type: 'missing',
+            message: `Missing head asset: ${relativePath} — run "pnpm build" in packages/ui first`,
+            path: fullPath
+        };
+        return [
+            error,
+            null
+        ];
+    }
+}
+function readCss(relativePath) {
+    const [error, content] = readAsset(relativePath);
+    if (error) {
+        process.stderr.write(`[zpress] ${error.message}\n`);
+        return '';
+    }
+    return content;
+}
+function readJs(relativePath) {
+    const [error, content] = readAsset(relativePath);
+    if (error) {
+        process.stderr.write(`[zpress] ${error.message}\n`);
+        return '';
+    }
+    return content;
+}
+const THEME_CSS_MAP = {
+    base: readCss('css/themes/base.css'),
+    midnight: readCss('css/themes/midnight.css'),
+    arcade: readCss('css/themes/arcade.css')
 };
-function getCriticalCss(themeName) {
-    const theme = themeName;
-    const css = CRITICAL_CSS_MAP[theme];
-    if (!css) return '';
-    return css;
+const BACKDROP_CSS = readCss('css/loader-backdrop.css');
+const DOTS_LOADER_CSS = readCss('css/loader-dots.css');
+const LOADER_CSS = BACKDROP_CSS + DOTS_LOADER_CSS;
+function getThemeCss(themeName) {
+    if (!Object.hasOwn(THEME_CSS_MAP, themeName)) return LOADER_CSS;
+    const themeColors = THEME_CSS_MAP[themeName];
+    if (themeColors) return themeColors + LOADER_CSS;
+    return LOADER_CSS;
 }
 function zpressPlugin() {
     const componentsDir = node_path.resolve(import.meta.dirname, 'theme', 'components');
@@ -65,6 +104,25 @@ function resolveThemeDarkColors(config) {
     if (config.theme && config.theme.darkColors) return config.theme.darkColors;
     return {};
 }
+const COLOR_MODE_DARK_JS = readJs('js/color-mode-dark.js');
+const COLOR_MODE_LIGHT_JS = readJs('js/color-mode-light.js');
+const VSCODE_DETECT_JS = readJs('js/vscode-detect.js');
+const LOADER_DOTS_JS = readJs('js/loader-dots.js');
+function buildColorModeJs(colorMode) {
+    if ('dark' === colorMode) return COLOR_MODE_DARK_JS;
+    if ('light' === colorMode) return COLOR_MODE_LIGHT_JS;
+    return '';
+}
+function buildHeadScriptBody(options) {
+    const colorModeJs = buildColorModeJs(options.colorMode);
+    const themeAttrJs = `document.documentElement.dataset.zpTheme=function(){try{var t=localStorage.getItem('zpress-theme');if(t)return t}catch(_){}return ${JSON.stringify(options.themeName)}}();`;
+    return [
+        colorModeJs,
+        themeAttrJs,
+        VSCODE_DETECT_JS,
+        LOADER_DOTS_JS
+    ].filter(Boolean).join('');
+}
 function createRspressConfig(options) {
     const { config, paths, logLevel } = options;
     const sidebar = loadGenerated(paths.contentDir, 'sidebar.json', {});
@@ -76,13 +134,11 @@ function createRspressConfig(options) {
     const themeSwitcher = resolveThemeSwitcher(config);
     const themeColors = resolveThemeColors(config);
     const themeDarkColors = resolveThemeDarkColors(config);
-    const criticalCss = getCriticalCss(themeName);
-    const headElements = (()=>{
-        if (criticalCss) return [
-            `<style data-zpress-critical>${criticalCss}</style>`
-        ];
-        return [];
-    })();
+    const themeCss = getThemeCss(themeName);
+    const headScriptBody = buildHeadScriptBody({
+        colorMode,
+        themeName
+    });
     return {
         root: paths.contentDir,
         outDir: paths.distDir,
@@ -99,7 +155,6 @@ function createRspressConfig(options) {
         plugins: [
             zpressPlugin()
         ],
-        head: headElements,
         builderConfig: {
             ...(()=>{
                 if (logLevel) return {
@@ -107,6 +162,25 @@ function createRspressConfig(options) {
                 };
                 return {};
             })(),
+            html: {
+                tags: [
+                    {
+                        tag: 'style',
+                        children: themeCss,
+                        attrs: {
+                            'data-zpress-theme-css': true
+                        },
+                        append: false,
+                        head: true
+                    },
+                    {
+                        tag: "script",
+                        children: `(function(){${headScriptBody}})()`,
+                        append: false,
+                        head: true
+                    }
+                ]
+            },
             resolve: {
                 alias: {
                     '@zpress/ui/theme': node_path.resolve(import.meta.dirname, 'theme', 'index.tsx')

package/dist/theme/components/nav/layout.tsx

@@ -6,82 +6,48 @@ import { BranchTag } from './branch-tag'
 import { ThemeSwitcher } from './theme-switcher'
 import { VscodeTag } from './vscode-tag'
 
-const VSCODE_OVERRIDES = `
-/* Hide left sidebar and its placeholder */
-html[data-zpress-env="vscode"] .rp-doc-layout__sidebar {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-doc-layout__sidebar-placeholder {
-  display: none;
-}
-
-/* Hide right TOC and its placeholder */
-html[data-zpress-env="vscode"] .rp-doc-layout__outline {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-doc-layout__outline-placeholder {
-  display: none;
-}
-
-/* Center content at 1200px max */
-html[data-zpress-env="vscode"] .rp-doc-layout__doc {
-  max-width: 1200px;
-  margin: 0 auto;
-}
-
-/* Hide nav items, social links, hamburger */
-html[data-zpress-env="vscode"] .rp-nav-menu__item {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-social-links {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-nav-hamburger {
-  display: none;
-}
-
-/* Hide mobile navigation elements */
-html[data-zpress-env="vscode"] .rp-nav-screen {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-nav-screen-menu {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-local-nav {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-appearance {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-doc-layout__menu {
-  display: none;
+/**
+ * Detect vscode mode synchronously from sessionStorage and URL params.
+ * Returns false during SSR — client initializes correctly via lazy useState.
+ */
+function readVscodeMode(): boolean {
+  if (globalThis.window === undefined) {
+    return false
+  }
+  try {
+    const params = new URLSearchParams(globalThis.location.search)
+    return (
+      params.get('env') === 'vscode' || globalThis.sessionStorage.getItem('zpress-env') === 'vscode'
+    )
+  } catch {
+    return false
+  }
 }
-`
 
+/**
+ * Returns true when the page is loaded in VS Code preview mode.
+ *
+ * Initializes synchronously from sessionStorage/URL so the VscodeTag
+ * renders in the same paint as the rest of the nav. The data-zpress-env
+ * attribute and static vscode.css are applied by the inline head script
+ * before React mounts, so no dynamic style injection is needed here.
+ */
 function useVscodeMode(): boolean {
-  const [active, setActive] = useState(false)
+  const [active] = useState<boolean>(readVscodeMode)
 
+  // Persist vscode mode across SPA route changes — the inline head script
+  // sets sessionStorage on first load via URL param, but client-side
+  // navigation may lose the param. This ensures the flag survives.
   useEffect(() => {
-    const params = new URLSearchParams(globalThis.location.search)
-    const isVscode =
-      params.get('env') === 'vscode' || globalThis.sessionStorage.getItem('zpress-env') === 'vscode'
-
-    if (!isVscode) {
+    if (!active) {
       return
     }
-
-    globalThis.sessionStorage.setItem('zpress-env', 'vscode')
-    setActive(true)
-    document.documentElement.dataset.zpressEnv = 'vscode'
-
-    const style = document.createElement('style')
-    style.textContent = VSCODE_OVERRIDES
-    document.head.append(style)
-    return () => {
-      style.remove()
-      delete document.documentElement.dataset.zpressEnv
+    try {
+      sessionStorage.setItem('zpress-env', 'vscode')
+    } catch {
+      // sessionStorage may be blocked in some environments
     }
-  }, [])
+  }, [active])
 
   return active
 }

package/dist/theme/components/nav/theme-switcher.tsx

@@ -17,9 +17,23 @@ const THEME_OPTIONS: readonly ThemeOption[] = [
   { name: 'base', label: 'Base', swatch: '#a78bfa', defaultColorMode: 'toggle' },
   { name: 'midnight', label: 'Midnight', swatch: '#60a5fa', defaultColorMode: 'dark' },
   { name: 'arcade', label: 'Arcade', swatch: '#00ff88', defaultColorMode: 'dark' },
-  { name: 'arcade-fx', label: 'Arcade FX', swatch: '#ff00ff', defaultColorMode: 'dark' },
 ]
 
+const VALID_THEME_NAMES = new Set(THEME_OPTIONS.map((t) => t.name))
+
+/**
+ * Validate a stored theme name, rejecting unknown values.
+ */
+function sanitizeThemeName(raw: string | null): string {
+  if (!raw) {
+    return 'base'
+  }
+  if (VALID_THEME_NAMES.has(raw)) {
+    return raw
+  }
+  return 'base'
+}
+
 /**
  * Build the className string for a theme option button.
  */
@@ -39,13 +53,15 @@ function applyTheme(theme: ThemeOption): void {
   localStorage.setItem('zpress-theme', theme.name)
 
   if (theme.defaultColorMode === 'dark') {
-    html.classList.add('rp-dark')
+    // 'rp-dark' is Rspress's dark mode class; 'dark' is added for Tailwind compatibility
+    html.classList.add('rp-dark', 'dark')
     html.dataset.dark = 'true'
-    localStorage.setItem('rspress-theme', 'dark')
+    localStorage.setItem('rspress-theme-appearance', 'dark')
   } else if (theme.defaultColorMode === 'light') {
-    html.classList.remove('rp-dark')
+    // Remove both Rspress and Tailwind dark mode classes
+    html.classList.remove('rp-dark', 'dark')
     html.dataset.dark = 'false'
-    localStorage.setItem('rspress-theme', 'light')
+    localStorage.setItem('rspress-theme-appearance', 'light')
   }
 }
 
@@ -56,11 +72,11 @@ function applyTheme(theme: ThemeOption): void {
 export function ThemeSwitcher(): React.ReactElement | null {
   const [isOpen, setIsOpen] = useState(false)
   const [activeTheme, setActiveTheme] = useState(() => {
-    if (typeof globalThis === 'undefined') {
+    if (globalThis.window === undefined) {
       return 'base'
     }
     try {
-      return localStorage.getItem('zpress-theme') || 'base'
+      return sanitizeThemeName(globalThis.localStorage.getItem('zpress-theme'))
     } catch {
       return 'base'
     }

package/dist/theme/components/theme-provider.tsx

@@ -1,4 +1,4 @@
-import { useEffect } from 'react'
+import { useEffect, useLayoutEffect } from 'react'
 import type React from 'react'
 
 declare const __ZPRESS_THEME_NAME__: string
@@ -87,14 +87,75 @@ function parseColors(raw: string): Record<string, string> {
   }
 }
 
+/**
+ * useLayoutEffect on the client, useEffect on the server (avoids SSR warning).
+ * Ensures DOM mutations happen synchronously before browser paint.
+ */
+function getIsomorphicEffect(): typeof useLayoutEffect {
+  if (globalThis.window !== undefined) {
+    return useLayoutEffect
+  }
+  return useEffect
+}
+
+const useIsomorphicLayoutEffect = getIsomorphicEffect()
+
+/**
+ * Minimum time (ms) the loading overlay stays visible before fading out.
+ */
+const LOADER_MIN_DISPLAY_MS = 150
+
+/**
+ * Duration (ms) of the CSS fade-out transition. Must match the
+ * `transition: opacity` value in loader-backdrop.css / loader-dots.css.
+ */
+const LOADER_FADE_MS = 200
+
+/**
+ * Dismiss the loading overlay with a two-phase approach:
+ *   1. Add `zp-loader-fade` class → CSS transitions opacity to 0
+ *   2. After transition completes → set `data-zp-ready` attribute → CSS hard removes (display: none)
+ *
+ * Also clears the JS-driven dots animation interval set by loader-dots.js.
+ *
+ * Returns a cleanup function that cancels pending timers.
+ */
+function clearDotsInterval(): void {
+  const dotsInterval = (globalThis as Record<string, unknown>).__zpDotsInterval
+  if (typeof dotsInterval === 'number') {
+    clearInterval(dotsInterval)
+  }
+}
+
+function dismissLoader(html: HTMLElement): () => void {
+  const fadeTimer = setTimeout(() => {
+    html.classList.add('zp-loader-fade')
+  }, LOADER_MIN_DISPLAY_MS)
+
+  const removeTimer = setTimeout(() => {
+    html.dataset.zpReady = 'true'
+    html.classList.remove('zp-loader-fade')
+    clearDotsInterval()
+  }, LOADER_MIN_DISPLAY_MS + LOADER_FADE_MS)
+
+  return () => {
+    clearTimeout(fadeTimer)
+    clearTimeout(removeTimer)
+    html.classList.remove('zp-loader-fade')
+    clearDotsInterval()
+  }
+}
+
 /**
  * ThemeProvider — global UI component that configures the active theme.
  *
  * Sets `data-zp-theme` attribute, forces color mode, and applies
  * inline CSS custom property overrides from build-time defines.
+ * Sets `data-zp-ready` on <html> to dismiss the loading overlay
+ * injected by critical CSS.
  */
 export function ThemeProvider(): React.ReactElement | null {
-  useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     const html = document.documentElement
     const themeName = safeGetItem('zpress-theme') || __ZPRESS_THEME_NAME__
     const colorMode = __ZPRESS_COLOR_MODE__
@@ -108,13 +169,21 @@ export function ThemeProvider(): React.ReactElement | null {
 
     // 2. Force color mode if not toggle
     if (colorMode === 'dark') {
-      html.classList.add('rp-dark')
+      html.classList.add('rp-dark', 'dark')
       html.dataset.dark = 'true'
-      localStorage.setItem('rspress-theme', 'dark')
+      try {
+        localStorage.setItem('rspress-theme-appearance', 'dark')
+      } catch {
+        // storage unavailable
+      }
     } else if (colorMode === 'light') {
-      html.classList.remove('rp-dark')
+      html.classList.remove('rp-dark', 'dark')
       html.dataset.dark = 'false'
-      localStorage.setItem('rspress-theme', 'light')
+      try {
+        localStorage.setItem('rspress-theme-appearance', 'light')
+      } catch {
+        // storage unavailable
+      }
     }
 
     // 3. Apply base color overrides
@@ -145,12 +214,17 @@ export function ThemeProvider(): React.ReactElement | null {
 
       observer.observe(html, { attributes: true, attributeFilter: ['class'] })
 
+      // 5. Dismiss loading overlay
+      const cancelLoader = dismissLoader(html)
+
       return () => {
         observer.disconnect()
+        cancelLoader()
       }
     }
 
-    // no cleanup needed when dark color overrides are absent
+    // 5. Dismiss loading overlay (no dark-color observer needed)
+    return dismissLoader(html)
   }, [])
 
   return null

package/dist/theme/index.tsx

@@ -16,6 +16,9 @@ import './styles/overrides/rspress.css'
 import './styles/themes/base.css'
 import './styles/themes/midnight.css'
 import './styles/themes/arcade.css'
+// arcade-fx.css is intentionally separate from arcade.css:
+// arcade.css = color palette tokens, arcade-fx.css = visual effects
+// (border trace, neon pulse, CRT scanlines, etc.) scoped to [data-zp-theme='arcade']
 import './styles/themes/arcade-fx.css'
 import './styles/overrides/details.css'
 import './styles/overrides/scrollbar.css'
@@ -23,6 +26,7 @@ import './styles/overrides/sidebar.css'
 import './styles/overrides/home.css'
 import './styles/overrides/home-card.css'
 import './styles/overrides/section-card.css'
+import './styles/overrides/vscode.css'
 
 // Re-export everything from the original Rspress theme
 // (theme-original avoids circular resolution when used inside a themeDir)

package/dist/theme/styles/overrides/vscode.css

@@ -0,0 +1,36 @@
+/**
+ * VS Code preview mode overrides.
+ *
+ * Applied when html[data-zpress-env="vscode"] is set — injected synchronously
+ * by the inline head script before first paint.
+ */
+
+/* Hide left sidebar and its placeholder */
+html[data-zpress-env='vscode'] .rp-doc-layout__sidebar,
+html[data-zpress-env='vscode'] .rp-doc-layout__sidebar-placeholder {
+  display: none;
+}
+
+/* Hide right TOC and its placeholder */
+html[data-zpress-env='vscode'] .rp-doc-layout__outline,
+html[data-zpress-env='vscode'] .rp-doc-layout__outline-placeholder {
+  display: none;
+}
+
+/* Center content at 1200px max */
+html[data-zpress-env='vscode'] .rp-doc-layout__doc {
+  max-width: 1200px;
+  margin: 0 auto;
+}
+
+/* Hide nav items, social links, hamburger, mobile nav, appearance toggle */
+html[data-zpress-env='vscode'] .rp-nav-menu__item,
+html[data-zpress-env='vscode'] .rp-social-links,
+html[data-zpress-env='vscode'] .rp-nav-hamburger,
+html[data-zpress-env='vscode'] .rp-nav-screen,
+html[data-zpress-env='vscode'] .rp-nav-screen-menu,
+html[data-zpress-env='vscode'] .rp-local-nav,
+html[data-zpress-env='vscode'] .rp-appearance,
+html[data-zpress-env='vscode'] .rp-doc-layout__menu {
+  display: none;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zpress/ui",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Rspress plugin, theme components, and styles for zpress",
   "keywords": [
     "react",
@@ -52,15 +52,16 @@
     "@iconify-json/vscode-icons": "^1.2.45",
     "@iconify/react": "^6.0.2",
     "ts-pattern": "^5.9.0",
-    "@zpress/config": "0.2.0",
-    "@zpress/core": "0.6.0",
-    "@zpress/theme": "0.2.0"
+    "@zpress/config": "0.2.1",
+    "@zpress/core": "0.6.1",
+    "@zpress/theme": "0.2.1"
   },
   "devDependencies": {
     "@rslib/core": "^0.20.0",
     "@rspress/core": "^2.0.5",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "esbuild": "^0.27.4",
     "geist": "^1.7.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
@@ -76,6 +77,7 @@
   },
   "scripts": {
     "build": "rslib build",
+    "postbuild": "node scripts/minify-head.mjs",
     "dev": "rslib build --watch --no-clean",
     "typecheck": "tsc --noEmit"
   }

package/src/theme/components/nav/layout.tsx

@@ -6,82 +6,48 @@ import { BranchTag } from './branch-tag'
 import { ThemeSwitcher } from './theme-switcher'
 import { VscodeTag } from './vscode-tag'
 
-const VSCODE_OVERRIDES = `
-/* Hide left sidebar and its placeholder */
-html[data-zpress-env="vscode"] .rp-doc-layout__sidebar {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-doc-layout__sidebar-placeholder {
-  display: none;
-}
-
-/* Hide right TOC and its placeholder */
-html[data-zpress-env="vscode"] .rp-doc-layout__outline {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-doc-layout__outline-placeholder {
-  display: none;
-}
-
-/* Center content at 1200px max */
-html[data-zpress-env="vscode"] .rp-doc-layout__doc {
-  max-width: 1200px;
-  margin: 0 auto;
-}
-
-/* Hide nav items, social links, hamburger */
-html[data-zpress-env="vscode"] .rp-nav-menu__item {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-social-links {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-nav-hamburger {
-  display: none;
-}
-
-/* Hide mobile navigation elements */
-html[data-zpress-env="vscode"] .rp-nav-screen {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-nav-screen-menu {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-local-nav {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-appearance {
-  display: none;
-}
-html[data-zpress-env="vscode"] .rp-doc-layout__menu {
-  display: none;
+/**
+ * Detect vscode mode synchronously from sessionStorage and URL params.
+ * Returns false during SSR — client initializes correctly via lazy useState.
+ */
+function readVscodeMode(): boolean {
+  if (globalThis.window === undefined) {
+    return false
+  }
+  try {
+    const params = new URLSearchParams(globalThis.location.search)
+    return (
+      params.get('env') === 'vscode' || globalThis.sessionStorage.getItem('zpress-env') === 'vscode'
+    )
+  } catch {
+    return false
+  }
 }
-`
 
+/**
+ * Returns true when the page is loaded in VS Code preview mode.
+ *
+ * Initializes synchronously from sessionStorage/URL so the VscodeTag
+ * renders in the same paint as the rest of the nav. The data-zpress-env
+ * attribute and static vscode.css are applied by the inline head script
+ * before React mounts, so no dynamic style injection is needed here.
+ */
 function useVscodeMode(): boolean {
-  const [active, setActive] = useState(false)
+  const [active] = useState<boolean>(readVscodeMode)
 
+  // Persist vscode mode across SPA route changes — the inline head script
+  // sets sessionStorage on first load via URL param, but client-side
+  // navigation may lose the param. This ensures the flag survives.
   useEffect(() => {
-    const params = new URLSearchParams(globalThis.location.search)
-    const isVscode =
-      params.get('env') === 'vscode' || globalThis.sessionStorage.getItem('zpress-env') === 'vscode'
-
-    if (!isVscode) {
+    if (!active) {
       return
     }
-
-    globalThis.sessionStorage.setItem('zpress-env', 'vscode')
-    setActive(true)
-    document.documentElement.dataset.zpressEnv = 'vscode'
-
-    const style = document.createElement('style')
-    style.textContent = VSCODE_OVERRIDES
-    document.head.append(style)
-    return () => {
-      style.remove()
-      delete document.documentElement.dataset.zpressEnv
+    try {
+      sessionStorage.setItem('zpress-env', 'vscode')
+    } catch {
+      // sessionStorage may be blocked in some environments
     }
-  }, [])
+  }, [active])
 
   return active
 }

package/src/theme/components/nav/theme-switcher.tsx

@@ -17,9 +17,23 @@ const THEME_OPTIONS: readonly ThemeOption[] = [
   { name: 'base', label: 'Base', swatch: '#a78bfa', defaultColorMode: 'toggle' },
   { name: 'midnight', label: 'Midnight', swatch: '#60a5fa', defaultColorMode: 'dark' },
   { name: 'arcade', label: 'Arcade', swatch: '#00ff88', defaultColorMode: 'dark' },
-  { name: 'arcade-fx', label: 'Arcade FX', swatch: '#ff00ff', defaultColorMode: 'dark' },
 ]
 
+const VALID_THEME_NAMES = new Set(THEME_OPTIONS.map((t) => t.name))
+
+/**
+ * Validate a stored theme name, rejecting unknown values.
+ */
+function sanitizeThemeName(raw: string | null): string {
+  if (!raw) {
+    return 'base'
+  }
+  if (VALID_THEME_NAMES.has(raw)) {
+    return raw
+  }
+  return 'base'
+}
+
 /**
  * Build the className string for a theme option button.
  */
@@ -39,13 +53,15 @@ function applyTheme(theme: ThemeOption): void {
   localStorage.setItem('zpress-theme', theme.name)
 
   if (theme.defaultColorMode === 'dark') {
-    html.classList.add('rp-dark')
+    // 'rp-dark' is Rspress's dark mode class; 'dark' is added for Tailwind compatibility
+    html.classList.add('rp-dark', 'dark')
     html.dataset.dark = 'true'
-    localStorage.setItem('rspress-theme', 'dark')
+    localStorage.setItem('rspress-theme-appearance', 'dark')
   } else if (theme.defaultColorMode === 'light') {
-    html.classList.remove('rp-dark')
+    // Remove both Rspress and Tailwind dark mode classes
+    html.classList.remove('rp-dark', 'dark')
     html.dataset.dark = 'false'
-    localStorage.setItem('rspress-theme', 'light')
+    localStorage.setItem('rspress-theme-appearance', 'light')
   }
 }
 
@@ -56,11 +72,11 @@ function applyTheme(theme: ThemeOption): void {
 export function ThemeSwitcher(): React.ReactElement | null {
   const [isOpen, setIsOpen] = useState(false)
   const [activeTheme, setActiveTheme] = useState(() => {
-    if (typeof globalThis === 'undefined') {
+    if (globalThis.window === undefined) {
       return 'base'
     }
     try {
-      return localStorage.getItem('zpress-theme') || 'base'
+      return sanitizeThemeName(globalThis.localStorage.getItem('zpress-theme'))
     } catch {
       return 'base'
     }

package/src/theme/components/theme-provider.tsx

@@ -1,4 +1,4 @@
-import { useEffect } from 'react'
+import { useEffect, useLayoutEffect } from 'react'
 import type React from 'react'
 
 declare const __ZPRESS_THEME_NAME__: string
@@ -87,14 +87,75 @@ function parseColors(raw: string): Record<string, string> {
   }
 }
 
+/**
+ * useLayoutEffect on the client, useEffect on the server (avoids SSR warning).
+ * Ensures DOM mutations happen synchronously before browser paint.
+ */
+function getIsomorphicEffect(): typeof useLayoutEffect {
+  if (globalThis.window !== undefined) {
+    return useLayoutEffect
+  }
+  return useEffect
+}
+
+const useIsomorphicLayoutEffect = getIsomorphicEffect()
+
+/**
+ * Minimum time (ms) the loading overlay stays visible before fading out.
+ */
+const LOADER_MIN_DISPLAY_MS = 150
+
+/**
+ * Duration (ms) of the CSS fade-out transition. Must match the
+ * `transition: opacity` value in loader-backdrop.css / loader-dots.css.
+ */
+const LOADER_FADE_MS = 200
+
+/**
+ * Dismiss the loading overlay with a two-phase approach:
+ *   1. Add `zp-loader-fade` class → CSS transitions opacity to 0
+ *   2. After transition completes → set `data-zp-ready` attribute → CSS hard removes (display: none)
+ *
+ * Also clears the JS-driven dots animation interval set by loader-dots.js.
+ *
+ * Returns a cleanup function that cancels pending timers.
+ */
+function clearDotsInterval(): void {
+  const dotsInterval = (globalThis as Record<string, unknown>).__zpDotsInterval
+  if (typeof dotsInterval === 'number') {
+    clearInterval(dotsInterval)
+  }
+}
+
+function dismissLoader(html: HTMLElement): () => void {
+  const fadeTimer = setTimeout(() => {
+    html.classList.add('zp-loader-fade')
+  }, LOADER_MIN_DISPLAY_MS)
+
+  const removeTimer = setTimeout(() => {
+    html.dataset.zpReady = 'true'
+    html.classList.remove('zp-loader-fade')
+    clearDotsInterval()
+  }, LOADER_MIN_DISPLAY_MS + LOADER_FADE_MS)
+
+  return () => {
+    clearTimeout(fadeTimer)
+    clearTimeout(removeTimer)
+    html.classList.remove('zp-loader-fade')
+    clearDotsInterval()
+  }
+}
+
 /**
  * ThemeProvider — global UI component that configures the active theme.
  *
  * Sets `data-zp-theme` attribute, forces color mode, and applies
  * inline CSS custom property overrides from build-time defines.
+ * Sets `data-zp-ready` on <html> to dismiss the loading overlay
+ * injected by critical CSS.
  */
 export function ThemeProvider(): React.ReactElement | null {
-  useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     const html = document.documentElement
     const themeName = safeGetItem('zpress-theme') || __ZPRESS_THEME_NAME__
     const colorMode = __ZPRESS_COLOR_MODE__
@@ -108,13 +169,21 @@ export function ThemeProvider(): React.ReactElement | null {
 
     // 2. Force color mode if not toggle
     if (colorMode === 'dark') {
-      html.classList.add('rp-dark')
+      html.classList.add('rp-dark', 'dark')
       html.dataset.dark = 'true'
-      localStorage.setItem('rspress-theme', 'dark')
+      try {
+        localStorage.setItem('rspress-theme-appearance', 'dark')
+      } catch {
+        // storage unavailable
+      }
     } else if (colorMode === 'light') {
-      html.classList.remove('rp-dark')
+      html.classList.remove('rp-dark', 'dark')
       html.dataset.dark = 'false'
-      localStorage.setItem('rspress-theme', 'light')
+      try {
+        localStorage.setItem('rspress-theme-appearance', 'light')
+      } catch {
+        // storage unavailable
+      }
     }
 
     // 3. Apply base color overrides
@@ -145,12 +214,17 @@ export function ThemeProvider(): React.ReactElement | null {
 
       observer.observe(html, { attributes: true, attributeFilter: ['class'] })
 
+      // 5. Dismiss loading overlay
+      const cancelLoader = dismissLoader(html)
+
       return () => {
         observer.disconnect()
+        cancelLoader()
       }
     }
 
-    // no cleanup needed when dark color overrides are absent
+    // 5. Dismiss loading overlay (no dark-color observer needed)
+    return dismissLoader(html)
   }, [])
 
   return null

package/src/theme/index.tsx

@@ -16,6 +16,9 @@ import './styles/overrides/rspress.css'
 import './styles/themes/base.css'
 import './styles/themes/midnight.css'
 import './styles/themes/arcade.css'
+// arcade-fx.css is intentionally separate from arcade.css:
+// arcade.css = color palette tokens, arcade-fx.css = visual effects
+// (border trace, neon pulse, CRT scanlines, etc.) scoped to [data-zp-theme='arcade']
 import './styles/themes/arcade-fx.css'
 import './styles/overrides/details.css'
 import './styles/overrides/scrollbar.css'
@@ -23,6 +26,7 @@ import './styles/overrides/sidebar.css'
 import './styles/overrides/home.css'
 import './styles/overrides/home-card.css'
 import './styles/overrides/section-card.css'
+import './styles/overrides/vscode.css'
 
 // Re-export everything from the original Rspress theme
 // (theme-original avoids circular resolution when used inside a themeDir)

package/src/theme/styles/overrides/vscode.css

@@ -0,0 +1,36 @@
+/**
+ * VS Code preview mode overrides.
+ *
+ * Applied when html[data-zpress-env="vscode"] is set — injected synchronously
+ * by the inline head script before first paint.
+ */
+
+/* Hide left sidebar and its placeholder */
+html[data-zpress-env='vscode'] .rp-doc-layout__sidebar,
+html[data-zpress-env='vscode'] .rp-doc-layout__sidebar-placeholder {
+  display: none;
+}
+
+/* Hide right TOC and its placeholder */
+html[data-zpress-env='vscode'] .rp-doc-layout__outline,
+html[data-zpress-env='vscode'] .rp-doc-layout__outline-placeholder {
+  display: none;
+}
+
+/* Center content at 1200px max */
+html[data-zpress-env='vscode'] .rp-doc-layout__doc {
+  max-width: 1200px;
+  margin: 0 auto;
+}
+
+/* Hide nav items, social links, hamburger, mobile nav, appearance toggle */
+html[data-zpress-env='vscode'] .rp-nav-menu__item,
+html[data-zpress-env='vscode'] .rp-social-links,
+html[data-zpress-env='vscode'] .rp-nav-hamburger,
+html[data-zpress-env='vscode'] .rp-nav-screen,
+html[data-zpress-env='vscode'] .rp-nav-screen-menu,
+html[data-zpress-env='vscode'] .rp-local-nav,
+html[data-zpress-env='vscode'] .rp-appearance,
+html[data-zpress-env='vscode'] .rp-doc-layout__menu {
+  display: none;
+}