docnest 0.1.1 → 0.1.3

package/server/static/js/core/doc-pdf-export.js

@@ -488,6 +488,65 @@
     });
   }
 
+  function showPdfExportError(message) {
+    var modalId = 'pdf-export-error';
+    var existing = document.querySelector('.pdf-export-error');
+    if (existing && existing.parentNode) {
+      existing.parentNode.removeChild(existing);
+    }
+    if (typeof removeModal === 'function') {
+      removeModal(modalId);
+    }
+
+    var overlay = document.createElement('div');
+    overlay.className = 'pdf-export-modal pdf-export-error';
+    overlay.innerHTML = [
+      '<div class="pdf-export-modal__panel" role="alertdialog" aria-modal="true" aria-labelledby="pdf-export-error-title" aria-describedby="pdf-export-error-desc">',
+        '<div class="pdf-export-modal__title" id="pdf-export-error-title">导出 PDF 失败</div>',
+        '<div class="pdf-export-modal__desc" id="pdf-export-error-desc"></div>',
+        '<div class="pdf-export-modal__actions">',
+          '<button type="button" class="pdf-export-modal__btn pdf-export-modal__btn--primary" data-action="close">知道了</button>',
+        '</div>',
+      '</div>'
+    ].join('');
+
+    var description = overlay.querySelector('#pdf-export-error-desc');
+    if (description) {
+      description.textContent = message || '暂时无法生成 PDF，请稍后重试。';
+    }
+
+    var closed = false;
+    function close() {
+      if (closed) return;
+      closed = true;
+      if (typeof removeModal === 'function') {
+        removeModal(modalId);
+      }
+      if (overlay.parentNode) {
+        overlay.parentNode.removeChild(overlay);
+      }
+    }
+
+    overlay.addEventListener('click', function(event) {
+      if (event.target === overlay) {
+        close();
+      }
+    });
+
+    var closeButton = overlay.querySelector('[data-action="close"]');
+    if (closeButton) {
+      closeButton.addEventListener('click', close);
+    }
+
+    document.body.appendChild(overlay);
+    if (typeof pushModal === 'function') {
+      pushModal(modalId, close);
+    }
+    if (closeButton) {
+      closeButton.focus();
+    }
+  }
+
   function setButtonLoading(button, loading) {
     if (!button) return;
     if (loading) {
@@ -512,7 +571,7 @@
   function exportCurrentDoc(button, options) {
     var article = document.querySelector('.main-content .markdown-body');
     if (!article) {
-      window.alert('未找到当前文档内容，无法导出 PDF。');
+      showPdfExportError('未找到当前文档内容，无法导出 PDF。');
       return;
     }
 
@@ -552,7 +611,7 @@
       })
       .catch(function(error) {
         console.error('导出 PDF 失败:', error);
-        window.alert('导出 PDF 失败，请稍后重试。');
+        showPdfExportError('暂时无法生成 PDF，请稍后重试。');
       })
       .finally(function() {
         setButtonLoading(button, false);

package/server/static/js/core/theme.js

@@ -1,138 +1,335 @@
-// 主题切换功能（支持系统自动跟随）
+// DocNest 外观系统：主题风格与明暗模式相互独立，并按宿主项目持久化。
 (function() {
-  // 检测系统主题
-  function getSystemTheme() {
-    return window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
-  }
-  
-  // 从 localStorage 读取主题偏好，默认为 'auto'（跟随系统）
-  const savedTheme = localStorage.getItem('markdown-theme') || 'auto';
-  
-  // 相对路径，由 resolveThemeCss 统一加上 base 或前导 /
-  const themes = {
-    light: {
-      css: 'vendor/github-markdown-css/github-markdown-light.css',
-      icon: '☀️',
-      text: '浅色模式'
+  'use strict';
+
+  var THEME_PROFILES = {
+    'slate-modern': {
+      label: 'Slate Modern',
+      description: '清爽、克制的现代文档界面',
+      colors: ['#ffffff', '#111111', '#5e6ad2']
+    },
+    'editorial-atlas': {
+      label: 'Editorial Atlas',
+      description: '安静、舒展的技术出版物',
+      colors: ['#f3f0e7', '#171815', '#1f5b57']
+    },
+    'precision-index': {
+      label: 'Precision Index',
+      description: '高密度、可追溯的工程索引',
+      colors: ['#eef2f3', '#14242b', '#007486']
     },
-    dark: {
-      css: 'vendor/github-markdown-css/github-markdown-dark.css',
-      icon: '🌙',
-      text: '深色模式'
+    'archive-room': {
+      label: 'Archive Room',
+      description: '温和、有秩序的档案阅览室',
+      colors: ['#f3efe4', '#262821', '#a5523d']
     },
-    auto: {
-      css: '',
-      icon: '💻',
-      text: '跟随系统'
+    'swiss-manual': {
+      label: 'Swiss Manual',
+      description: '鲜明、直接的瑞士工程手册',
+      colors: ['#f4f3ef', '#111111', '#e33b27']
     }
   };
 
-  function resolveThemeCss(path) {
-    if (!path) return '';
-    var base = document.querySelector('base');
-    if (base && base.getAttribute('href')) {
-      var baseHref = base.getAttribute('href').replace(/\/?$/, '/');
-      return baseHref + path.replace(/^\//, '');
+  var COLOR_MODES = {
+    auto: { label: '跟随系统', shortLabel: 'A' },
+    light: { label: '浅色', shortLabel: 'L' },
+    dark: { label: '深色', shortLabel: 'D' }
+  };
+  var MODE_CYCLE = ['auto', 'light', 'dark'];
+  var config = window.DOCNEST_CONFIG || {};
+  var appearance = config.appearance || {};
+  var storagePrefix = String(config.storageKeyPrefix || 'docnest');
+  var themeStorageKey = storagePrefix + ':theme-style';
+  var modeStorageKey = storagePrefix + ':theme-mode';
+
+  function readStorage(key) {
+    try {
+      return window.localStorage.getItem(key);
+    } catch (_) {
+      return null;
     }
-    return path.charAt(0) === '/' ? path : '/' + path;
-  }
-  
-  // 获取实际要应用的主题（如果是 auto，则使用系统主题）
-  function getEffectiveTheme(theme) {
-    return theme === 'auto' ? getSystemTheme() : theme;
-  }
-  
-  // 三种形态循环顺序：auto → light → dark → auto
-  const themeCycle = ['auto', 'light', 'dark'];
-
-  // 等待 DOM 加载完成
-  function initTheme() {
-    const themeToggle = document.getElementById('theme-toggle');
-    const themeLink = document.getElementById('markdown-theme');
-    const themeIcon = themeToggle?.querySelector('.theme-icon');
-    const themeText = themeToggle?.querySelector('.theme-text');
-
-    if (!themeToggle || !themeLink || !themeIcon) {
-      if (document.readyState === 'loading') {
-        document.addEventListener('DOMContentLoaded', initTheme);
-        return;
-      }
-      console.warn('主题切换元素未找到，可能 DOM 尚未加载完成');
-      return;
+  }
+
+  function writeStorage(key, value) {
+    try {
+      window.localStorage.setItem(key, value);
+    } catch (_) {}
+  }
+
+  function normalizeThemeName(value) {
+    return value === 'current-docs' ? 'slate-modern' : value;
+  }
+
+  function uniqueKnownThemes(values) {
+    var seen = new Set();
+    return (Array.isArray(values) ? values : [])
+      .map(normalizeThemeName)
+      .filter(function(value) {
+        if (!THEME_PROFILES[value] || seen.has(value)) return false;
+        seen.add(value);
+        return true;
+      });
+  }
+
+  var enabledThemes = uniqueKnownThemes(appearance.enabledThemes);
+  if (enabledThemes.length === 0) enabledThemes = Object.keys(THEME_PROFILES);
+
+  var configuredThemeName = normalizeThemeName(appearance.defaultTheme);
+  var configuredTheme = THEME_PROFILES[configuredThemeName]
+    ? configuredThemeName
+    : 'slate-modern';
+  var defaultTheme = enabledThemes.indexOf(configuredTheme) >= 0
+    ? configuredTheme
+    : enabledThemes[0];
+  var defaultMode = COLOR_MODES[appearance.defaultMode] ? appearance.defaultMode : 'auto';
+  var storedThemeValue = readStorage(themeStorageKey);
+  var storedTheme = normalizeThemeName(storedThemeValue);
+  var storedMode = readStorage(modeStorageKey);
+  var migratedLegacyMode = false;
+
+  // 兼容 0.1.x 的明暗模式存储键；只迁移有效值，不覆盖新的项目级偏好。
+  if (!storedMode) {
+    var legacyMode = readStorage('markdown-theme');
+    if (COLOR_MODES[legacyMode]) {
+      storedMode = legacyMode;
+      migratedLegacyMode = true;
     }
+  }
+
+  var activeTheme = enabledThemes.indexOf(storedTheme) >= 0 ? storedTheme : defaultTheme;
+  var activeMode = COLOR_MODES[storedMode] ? storedMode : defaultMode;
+  if (storedThemeValue === 'current-docs') writeStorage(themeStorageKey, activeTheme);
+  if (migratedLegacyMode) writeStorage(modeStorageKey, activeMode);
+
+  function getSystemMode() {
+    return window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches
+      ? 'dark'
+      : 'light';
+  }
 
-    // 更新按钮显示（图标 + 文案）
-    function updateButtonDisplay(theme) {
-      const themeConfig = themes[theme];
-      if (themeIcon) themeIcon.textContent = themeConfig.icon;
-      if (themeText) themeText.textContent = themeConfig.text;
+  function getEffectiveMode(mode) {
+    return mode === 'auto' ? getSystemMode() : mode;
+  }
+
+  function setAppearanceAttributes(theme, mode) {
+    var effectiveMode = getEffectiveMode(mode);
+    var root = document.documentElement;
+    root.setAttribute('data-doc-theme', theme);
+    root.setAttribute('data-theme', effectiveMode);
+    root.setAttribute('data-theme-mode', mode);
+    root.style.colorScheme = effectiveMode;
+    if (document.body) {
+      document.body.setAttribute('data-doc-theme', theme);
+      document.body.setAttribute('data-theme', effectiveMode);
+      document.body.setAttribute('data-theme-mode', mode);
     }
+    return effectiveMode;
+  }
+
+  // 在 DOM 完成前先写入 html，避免主题闪烁。
+  setAppearanceAttributes(activeTheme, activeMode);
+
+  function resolveThemeCss(assetPath) {
+    var base = document.querySelector('base');
+    if (base && base.getAttribute('href')) {
+      return base.getAttribute('href').replace(/\/?$/, '/') + assetPath.replace(/^\//, '');
+    }
+    return assetPath.charAt(0) === '/' ? assetPath : '/' + assetPath;
+  }
+
+  function applyMarkdownTheme(effectiveMode) {
+    var link = document.getElementById('markdown-theme');
+    if (!link) return;
+    link.href = resolveThemeCss(
+      effectiveMode === 'dark'
+        ? 'vendor/github-markdown-css/github-markdown-dark.css'
+        : 'vendor/github-markdown-css/github-markdown-light.css'
+    );
+  }
+
+  function updateControls() {
+    var profile = THEME_PROFILES[activeTheme];
+    var styleText = document.querySelector('.theme-style-text');
+    var modeText = document.querySelector('.theme-text');
+    var modeIcon = document.querySelector('.theme-icon');
+    if (styleText) styleText.textContent = profile.label;
+    if (modeText) modeText.textContent = COLOR_MODES[activeMode].label;
+    if (modeIcon) modeIcon.textContent = COLOR_MODES[activeMode].shortLabel;
 
-    // 应用主题
-    function applyTheme(theme, skipSave) {
-      const effectiveTheme = getEffectiveTheme(theme);
-      const themeConfig = themes[theme];
-      const effectiveConfig = themes[effectiveTheme];
+    document.querySelectorAll('[data-theme-option]').forEach(function(button) {
+      var checked = button.getAttribute('data-theme-option') === activeTheme;
+      button.setAttribute('aria-checked', String(checked));
+      button.classList.toggle('is-active', checked);
+    });
+    document.querySelectorAll('[data-mode-option]').forEach(function(button) {
+      var checked = button.getAttribute('data-mode-option') === activeMode;
+      button.setAttribute('aria-checked', String(checked));
+      button.classList.toggle('is-active', checked);
+    });
+  }
 
-      themeLink.href = resolveThemeCss(effectiveConfig.css);
-      document.body.setAttribute('data-theme', effectiveTheme);
-      document.body.setAttribute('data-theme-mode', theme);
+  function refreshMermaid(effectiveMode) {
+    if (typeof window.mermaid === 'undefined') return;
+    window.mermaid.initialize({
+      startOnLoad: false,
+      theme: effectiveMode === 'dark' ? 'dark' : 'default',
+      securityLevel: 'loose',
+      flowchart: { useMaxWidth: true, htmlLabels: true }
+    });
+  }
 
-      updateButtonDisplay(theme);
+  function applyAppearance(theme, mode, options) {
+    var nextTheme = enabledThemes.indexOf(theme) >= 0 ? theme : defaultTheme;
+    var nextMode = COLOR_MODES[mode] ? mode : defaultMode;
+    activeTheme = nextTheme;
+    activeMode = nextMode;
+    var effectiveMode = setAppearanceAttributes(activeTheme, activeMode);
+    applyMarkdownTheme(effectiveMode);
+    updateControls();
+    refreshMermaid(effectiveMode);
 
-      if (!skipSave) {
-        localStorage.setItem('markdown-theme', theme);
+    if (!options || options.persist !== false) {
+      writeStorage(themeStorageKey, activeTheme);
+      writeStorage(modeStorageKey, activeMode);
+    }
+
+    window.dispatchEvent(new CustomEvent('docnest:appearance-change', {
+      detail: {
+        theme: activeTheme,
+        mode: activeMode,
+        effectiveMode: effectiveMode
       }
+    }));
+  }
+
+  function buildThemeOptions(container) {
+    enabledThemes.forEach(function(themeName) {
+      var profile = THEME_PROFILES[themeName];
+      var button = document.createElement('button');
+      button.type = 'button';
+      button.className = 'theme-option';
+      button.setAttribute('role', 'radio');
+      button.setAttribute('data-theme-option', themeName);
+      button.setAttribute('aria-checked', 'false');
 
-      if (typeof mermaid !== 'undefined') {
-        mermaid.initialize({
-          startOnLoad: false,
-          theme: effectiveTheme === 'dark' ? 'dark' : 'default',
-          securityLevel: 'loose',
-          flowchart: {
-            useMaxWidth: true,
-            htmlLabels: true
-          }
-        });
-        mermaid.run().then(() => {
-          if (typeof setupDiagramViewer === 'function') {
-            setupDiagramViewer();
-          }
-        });
+      var palette = document.createElement('span');
+      palette.className = 'theme-option-palette';
+      palette.setAttribute('aria-hidden', 'true');
+      profile.colors.forEach(function(color) {
+        var chip = document.createElement('i');
+        chip.style.backgroundColor = color;
+        palette.appendChild(chip);
+      });
+
+      var copy = document.createElement('span');
+      copy.className = 'theme-option-copy';
+      var title = document.createElement('strong');
+      title.textContent = profile.label;
+      var description = document.createElement('small');
+      description.textContent = profile.description;
+      copy.appendChild(title);
+      copy.appendChild(description);
+
+      var check = document.createElement('span');
+      check.className = 'theme-option-check';
+      check.setAttribute('aria-hidden', 'true');
+      check.textContent = '✓';
+
+      button.appendChild(palette);
+      button.appendChild(copy);
+      button.appendChild(check);
+      button.addEventListener('click', function() {
+        applyAppearance(themeName, activeMode);
+      });
+      container.appendChild(button);
+    });
+  }
+
+  function buildModeOptions(container) {
+    MODE_CYCLE.forEach(function(mode) {
+      var button = document.createElement('button');
+      button.type = 'button';
+      button.className = 'theme-mode-option';
+      button.setAttribute('role', 'radio');
+      button.setAttribute('data-mode-option', mode);
+      button.setAttribute('aria-checked', 'false');
+      button.innerHTML = '<span aria-hidden="true">' + COLOR_MODES[mode].shortLabel + '</span>' +
+        '<strong>' + COLOR_MODES[mode].label + '</strong>';
+      button.addEventListener('click', function() {
+        applyAppearance(activeTheme, mode);
+      });
+      container.appendChild(button);
+    });
+  }
+
+  function initAppearanceControls() {
+    setAppearanceAttributes(activeTheme, activeMode);
+    var styleToggle = document.getElementById('theme-style-toggle');
+    var modeToggle = document.getElementById('theme-toggle');
+    var popover = document.getElementById('theme-popover');
+    var themeOptions = document.getElementById('theme-options');
+    var modeOptions = document.getElementById('theme-mode-options');
+
+    if (themeOptions) buildThemeOptions(themeOptions);
+    if (modeOptions) buildModeOptions(modeOptions);
+
+    function setPopoverOpen(open) {
+      if (!styleToggle || !popover) return;
+      popover.hidden = !open;
+      styleToggle.setAttribute('aria-expanded', String(open));
+      if (open) {
+        var activeOption = popover.querySelector('.theme-option.is-active');
+        if (activeOption) activeOption.focus();
       }
     }
 
-    // 一键循环到下一形态
-    function cycleTheme() {
-      const current = document.body.getAttribute('data-theme-mode') || savedTheme;
-      const idx = themeCycle.indexOf(current);
-      const nextIdx = idx >= 0 ? (idx + 1) % themeCycle.length : 0;
-      applyTheme(themeCycle[nextIdx]);
+    if (styleToggle && popover) {
+      styleToggle.addEventListener('click', function(event) {
+        event.stopPropagation();
+        setPopoverOpen(popover.hidden);
+      });
+      popover.addEventListener('click', function(event) {
+        event.stopPropagation();
+      });
+      document.addEventListener('click', function() { setPopoverOpen(false); });
+      document.addEventListener('keydown', function(event) {
+        if (event.key === 'Escape') {
+          setPopoverOpen(false);
+          styleToggle.focus();
+        }
+      });
     }
 
-    if (window.matchMedia && !window._themeMediaQueryBound) {
-      const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
-      mediaQuery.addEventListener('change', function() {
-        const currentMode = document.body.getAttribute('data-theme-mode') || savedTheme;
-        if (currentMode === 'auto') {
-          applyTheme('auto', true);
-        }
+    if (modeToggle) {
+      modeToggle.addEventListener('click', function() {
+        var index = MODE_CYCLE.indexOf(activeMode);
+        applyAppearance(activeTheme, MODE_CYCLE[(index + 1) % MODE_CYCLE.length]);
       });
-      window._themeMediaQueryBound = true;
     }
 
-    applyTheme(savedTheme);
+    if (window.matchMedia && !window.__docnestThemeMediaQueryBound) {
+      var query = window.matchMedia('(prefers-color-scheme: dark)');
+      query.addEventListener('change', function() {
+        if (activeMode === 'auto') applyAppearance(activeTheme, 'auto', { persist: false });
+      });
+      window.__docnestThemeMediaQueryBound = true;
+    }
 
-    themeToggle.addEventListener('click', function(e) {
-      e.stopPropagation();
-      cycleTheme();
-    });
+    applyAppearance(activeTheme, activeMode, { persist: false });
   }
-  
-  // 如果 DOM 已经加载完成，立即执行；否则等待 DOMContentLoaded
+
+  window.DocNestAppearance = {
+    get: function() {
+      return { theme: activeTheme, mode: activeMode, effectiveMode: getEffectiveMode(activeMode) };
+    },
+    setTheme: function(theme) { applyAppearance(theme, activeMode); },
+    setMode: function(mode) { applyAppearance(activeTheme, mode); },
+    themes: Object.keys(THEME_PROFILES)
+  };
+
   if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', initTheme);
+    document.addEventListener('DOMContentLoaded', initAppearanceControls);
   } else {
-    initTheme();
+    initAppearanceControls();
   }
 })();

package/server/views/dir.ejs

@@ -8,7 +8,9 @@
   <link id="markdown-theme" rel="stylesheet" href="/vendor/github-markdown-css/github-markdown-light.css?v=<%= assetVersion %>">
   <link rel="stylesheet" href="/static/css/styles.css?v=<%= assetVersion %>">
   <link rel="stylesheet" href="/static/css/highlight.css?v=<%= assetVersion %>">
+  <link rel="stylesheet" href="/static/css/themes.css?v=<%= assetVersion %>">
   <script src="/mermaid/mermaid.min.js?v=<%= assetVersion %>"></script>
+  <%- include('partials/appearance-head') %>
   <script src="/static/js/core/theme.js?v=<%= assetVersion %>"></script>
   <script src="/static/js/core/sidebar.js?v=<%= assetVersion %>"></script>
 </head>

package/server/views/doc.ejs

@@ -8,13 +8,9 @@
   <link id="markdown-theme" rel="stylesheet" href="/vendor/github-markdown-css/github-markdown-light.css?v=<%= assetVersion %>">
   <link rel="stylesheet" href="/static/css/styles.css?v=<%= assetVersion %>">
   <link rel="stylesheet" href="/static/css/highlight.css?v=<%= assetVersion %>">
+  <link rel="stylesheet" href="/static/css/themes.css?v=<%= assetVersion %>">
   <script src="/mermaid/mermaid.min.js?v=<%= assetVersion %>"></script>
-  <script>
-    window.DOCNEST_CONFIG = {
-      watermarkEnabled: <%= docsWatermarkEnabled ? 'true' : 'false' %>,
-      watermarkText: <%- JSON.stringify(docsWatermarkText) %>
-    };
-  </script>
+  <%- include('partials/appearance-head') %>
   <!-- 基础功能模块 -->
   <script src="/static/js/core/theme.js?v=<%= assetVersion %>"></script>
   <script src="/static/js/core/mermaid-init.js?v=<%= assetVersion %>"></script>

package/server/views/index.ejs

@@ -8,13 +8,9 @@
   <link id="markdown-theme" rel="stylesheet" href="/vendor/github-markdown-css/github-markdown-light.css?v=<%= assetVersion %>">
   <link rel="stylesheet" href="/static/css/styles.css?v=<%= assetVersion %>">
   <link rel="stylesheet" href="/static/css/highlight.css?v=<%= assetVersion %>">
+  <link rel="stylesheet" href="/static/css/themes.css?v=<%= assetVersion %>">
   <script src="/mermaid/mermaid.min.js?v=<%= assetVersion %>"></script>
-  <script>
-    window.DOCNEST_CONFIG = {
-      watermarkEnabled: <%= docsWatermarkEnabled ? 'true' : 'false' %>,
-      watermarkText: <%- JSON.stringify(docsWatermarkText) %>
-    };
-  </script>
+  <%- include('partials/appearance-head') %>
   <!-- 基础功能模块 -->
   <script src="/static/js/core/theme.js?v=<%= assetVersion %>"></script>
   <script src="/static/js/core/mermaid-init.js?v=<%= assetVersion %>"></script>

package/server/views/not-found.ejs

@@ -8,6 +8,8 @@
   <link id="markdown-theme" rel="stylesheet" href="/vendor/github-markdown-css/github-markdown-light.css?v=<%= assetVersion %>">
   <link rel="stylesheet" href="/static/css/styles.css?v=<%= assetVersion %>">
   <link rel="stylesheet" href="/static/css/highlight.css?v=<%= assetVersion %>">
+  <link rel="stylesheet" href="/static/css/themes.css?v=<%= assetVersion %>">
+  <%- include('partials/appearance-head') %>
   <script src="/static/js/core/theme.js?v=<%= assetVersion %>"></script>
   <script src="/static/js/core/sidebar.js?v=<%= assetVersion %>"></script>
 </head>

package/server/views/partials/appearance-head.ejs

@@ -0,0 +1,12 @@
+<script>
+  window.DOCNEST_CONFIG = {
+    watermarkEnabled: <%= docsWatermarkEnabled ? 'true' : 'false' %>,
+    watermarkText: <%- JSON.stringify(docsWatermarkText) %>,
+    storageKeyPrefix: <%- JSON.stringify(docsStorageKeyPrefix) %>,
+    appearance: {
+      defaultTheme: <%- JSON.stringify(docsThemeDefault) %>,
+      defaultMode: <%- JSON.stringify(docsThemeModeDefault) %>,
+      enabledThemes: <%- JSON.stringify(docsThemeEnabled) %>
+    }
+  };
+</script>

package/server/views/partials/header.ejs

@@ -2,7 +2,7 @@
   <div class="header-content">
     <div class="header-title-group">
       <h1>
-        <% if (docsLogo) { %><img class="brand-logo" src="<%= docsLogo %>" alt=""><% } else { %>📚<% } %>
+        <% if (docsLogo) { %><img class="brand-logo" src="<%= docsLogo %>" alt=""><% } else { %><span class="brand-fallback" aria-hidden="true"><span class="brand-fallback-emoji">📚</span><span class="brand-fallback-shape"></span></span><% } %>
         <%= docsTitle %>
       </h1>
       <% if (typeof showBackLink !== 'undefined' && showBackLink) { %>
@@ -25,12 +25,35 @@
             <span class="header-action-text">下载 PDF</span>
           </button>
         <% } %>
-        <div class="theme-selector">
-          <button id="theme-toggle" class="header-action-btn theme-toggle" title="点击切换：跟随系统 / 浅色 / 深色">
-            <span class="theme-icon">💻</span>
-            <span class="theme-text">跟随系统</span>
+        <div class="theme-selector" id="theme-selector">
+          <button
+            id="theme-style-toggle"
+            class="header-action-btn theme-style-toggle"
+            type="button"
+            aria-haspopup="dialog"
+            aria-expanded="false"
+            aria-controls="theme-popover"
+            title="选择文档中心主题"
+          >
+            <span class="theme-swatch" aria-hidden="true"></span>
+            <span class="theme-style-text">Slate Modern</span>
+            <span class="theme-chevron" aria-hidden="true">⌄</span>
           </button>
+          <div class="theme-popover" id="theme-popover" role="dialog" aria-label="外观设置" hidden>
+            <div class="theme-popover-section">
+              <p class="theme-popover-label">主题风格</p>
+              <div class="theme-options" id="theme-options" role="radiogroup" aria-label="主题风格"></div>
+            </div>
+            <div class="theme-popover-section theme-mode-section">
+              <p class="theme-popover-label">明暗模式</p>
+              <div class="theme-mode-options" id="theme-mode-options" role="radiogroup" aria-label="明暗模式"></div>
+            </div>
+          </div>
         </div>
+        <button id="theme-toggle" class="header-action-btn theme-toggle" type="button" title="切换明暗模式">
+          <span class="theme-icon" aria-hidden="true">A</span>
+          <span class="theme-text">跟随系统</span>
+        </button>
       </div>
     </div>
   </div>