@bndynet/vue-site 1.2.1 → 1.3.1

package/README.md

@@ -10,6 +10,7 @@ Configurable Vue 3 site framework: one package, `site.config.ts`, and Markdown p
 - Hash or HTML5 (`web`) router history, configurable in `site.config.ts`
 - Markdown (`?raw`) or Vue pages
 - highlight.js, light/dark theme + localStorage
+- Custom shell actions for avatars, notifications, help menus, and other app controls
 - Built-in multi-language support (locale switcher, `LocalizedString` config, per-locale pages) — see [Internationalization](#internationalization-i18n)
 - Project `README.md` as Home
 - Full TypeScript types
@@ -29,6 +30,7 @@ import { defineConfig } from '@bndynet/vue-site'
 
 export default defineConfig({
   title: 'My Project',
+  favicon: '/favicon.ico',
   nav: [
     { label: 'Home', icon: 'home', page: () => import('./README.md?raw') },
     { label: 'Guide', icon: 'book-open', page: () => import('./pages/guide.md?raw') },
@@ -42,6 +44,7 @@ export default defineConfig({
 my-site/
   package.json
   site.config.ts
+  public/favicon.ico
   README.md
   pages/guide.md
 ```
@@ -72,13 +75,17 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 |----------|-------------|
 | `title` | Site title (sidebar + tab). `LocalizedString` |
 | `nav` | `NavItem[]` |
+| `navPosition` | Optional navigation placement: `'top'` forces the top/tiered layout, `'sidebar'` forces the full nav tree into the sidebar. Omit to keep automatic behavior based on nav depth |
 | `defaultPath` | Path the site opens at; `/` and unknown paths redirect here. Must match a registered route (a `nav` item's resolved path or a `pages` entry's `path`). Defaults to the first top-level `nav` item |
+| `favicon` | Browser tab icon URL. Use a public asset path, remote URL, or imported asset URL |
 | `logo` | Logo URL or imported image |
 | `theme` | See `ThemeConfig` below; set to `false` to disable theming (hides the switcher, forces a fixed `light` palette, no localStorage persistence) |
 | `i18n` | Multi-language config (`I18nConfig`) — see [Internationalization](#internationalization-i18n) |
 | `footer` | Footer text. `LocalizedString` |
 | `readme` | Raw Home content if no `README.md` |
 | `links` | Header links: Lucide `icon` + `link`, optional `title` (`LocalizedString`) |
+| `shell` | Shell action area config (`ShellConfig`) — see [Shell actions](#shell-actions-shellactions) |
+| `icons` | Lucide icon registry. Generated automatically by the CLI; provide manually only when calling `createSiteApp` without the CLI |
 | `pages` | `StandalonePage[]` — full-screen routes outside the `nav` tree (no top bar/sidebar/footer) |
 | `auth` | Central authorization policy (`AuthConfig`) — see [Per-page authorization](#per-page-authorization-auth) |
 | `router` | History mode (`RouterConfig`) — `hash` (default) or HTML5 `web`; see [Router history](#router-history-router) |
@@ -95,11 +102,59 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 | `icon` | [Lucide](https://lucide.dev/icons) name |
 | `page` | Page content. Simplest is a **file-path string** like `'./pages/AdminView.vue'` or `'./README.md'` (auto-loads per-locale siblings, falls back to the base file). Also accepts a loader (`() => import('./Page.vue')` / `() => import('./page.md?raw')`) or a `localizedPage(...)` result. See [Per-locale page content](#per-locale-page-content) and [Advanced page loaders](#advanced-page-loaders) |
 | `path` | Route path (derived from `label`'s default-locale value if omitted; stays stable across languages) |
+| `layout` | Page content width: `'default'` keeps the standard centered reading width, `'wide'` uses a wider centered canvas, `'full'` fills the available parent container with no framework padding. Ignored for groups and links. |
 | `children` | Nested group |
 | `link` | Render as a hyperlink (internal route path or external URL) instead of a page route |
 | `visible` | `() => boolean \| Promise<boolean>`, awaited once at startup. Return `false` to hide the item from the nav and skip its route (not reachable by direct URL). A hidden parent hides its subtree; a group with no remaining children is pruned. Not reactive to later changes. |
 | `auth` | Authorization rule (`AuthRule`) interpreted by `auth.authorize`. Keeps the route registered and enforces it via a navigation guard (so direct URLs redirect to login). Requires `SiteConfig.auth`. See [Per-page authorization](#per-page-authorization-auth). |
 
+### `StandalonePage`
+
+| Property | Description |
+|----------|-------------|
+| `path` | Route path, used as-is (e.g. `/landing`) |
+| `page` | Page content. Same forms as `NavItem.page` |
+| `layout` | Optional content width. Omit to keep the standalone default: a full-screen, unpadded canvas. |
+| `visible` | `() => boolean \| Promise<boolean>`, awaited once at startup. Return `false` to skip registering the route. |
+| `auth` | Authorization rule (`AuthRule`) enforced by the same navigation guard as `NavItem.auth`. |
+
+### Page layout
+
+Set `layout` on a `NavItem` page when the default reading width is too narrow:
+
+```typescript
+export default defineConfig({
+  nav: [
+    { label: 'Docs', icon: 'book', page: './pages/docs.md' },
+    { label: 'Reports', icon: 'table', layout: 'wide', page: './pages/reports.vue' },
+    { label: 'Dashboard', icon: 'gauge', layout: 'full', page: './pages/dashboard.vue' },
+  ],
+})
+```
+
+### Icon registry
+
+The CLI scans configured Lucide icon names in `nav`, `links`, `i18n.locales`, and `theme.extraThemes`
+and generates an icon registry automatically. Only the icons referenced by the config are bundled.
+
+When using the library directly without the CLI, pass the registry yourself:
+
+```typescript
+import Home from 'lucide-vue-next/dist/esm/icons/home.js'
+import BookOpen from 'lucide-vue-next/dist/esm/icons/book-open.js'
+
+createSiteApp({
+  title: 'My Site',
+  icons: {
+    home: Home,
+    'book-open': BookOpen,
+  },
+  nav: [
+    { label: 'Home', icon: 'home', page: () => import('./README.md?raw') },
+  ],
+})
+```
+
 ### `ThemeConfig`
 
 Built-in themes are `light`, `dark`, plus the always-on extras `sepia` and `ocean` (shown in the switcher for every site). Set `theme: false` on `SiteConfig` to disable theming entirely.
@@ -111,6 +166,45 @@ Built-in themes are `light`, `dark`, plus the always-on extras `sepia` and `ocea
 | `palettes` | — | Partial overrides for built-in light/dark only |
 | `extraThemes` | — | Extra themes: `id`, `label`, `icon`, optional `basedOn`, `palette`; reuse a built-in id (`sepia`/`ocean`) to override it. Import `builtinThemePalettes` for full defaults |
 
+## Shell actions (`shell.actions`)
+
+Use `shell.actions` to render app-specific Vue components in the active layout's global toolbar.
+In top/tiered navigation they appear at the end of the top header; in sidebar-only navigation they
+appear in the sidebar footer after the built-in links, locale switcher, and theme switcher. This is
+the recommended place for a signed-in user avatar, notification button, help menu, or tenant
+switcher.
+
+```typescript
+export default defineConfig({
+  title: 'My Site',
+  shell: {
+    actions: ['./components/UserAvatar.vue'],
+    align: 'left',
+  },
+  nav: [/* ... */],
+})
+```
+
+With the CLI, each path-like string is rewritten to a dynamic import. In library mode, pass an
+imported component or loader instead:
+
+```typescript
+import UserAvatar from './components/UserAvatar.vue'
+
+export default defineConfig({
+  shell: {
+    actions: [UserAvatar, () => import('./components/HelpMenu.vue')],
+    align: 'center',
+  },
+  nav: [/* ... */],
+})
+```
+
+The framework only renders the component; auth state, user data, menus, and logout behavior stay in
+your component so the framework does not need to define a user model.
+Set `align` to `'left'`, `'center'`, or `'right'` for sidebar-footer placement; it defaults to
+`'center'`. Top-header placement keeps the built-in toolbar flow.
+
 ## Internationalization (`i18n`)
 
 Set `i18n` to enable multi-language support. The framework adds a locale switcher to the header,
@@ -461,7 +555,7 @@ app.mount('#app')
 
 Use a top-level `await` in your entry (or an async IIFE): `createSiteApp` is async and **awaits** `configureApp` when it returns a `Promise`. If you set optional `bootstrap` in config, that module loads before the app is created; if you omit `bootstrap`, that step is skipped.
 
-Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useSiteConfig`, `useLocale`, `useLocalize`, `tk`, `resolveLocalized`, `resolveField`, `resolveMessage`, `mergeCatalog`, `flattenMessages`, `isMessageRef`, `localizedPage`, `builtinMessages`, `themeRefKey`, `localeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteExternalLink`, `NavItem`, `StandalonePage`, `AuthRule`, `AuthContext`, `AuthConfig`, `RouterConfig`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`, `I18nConfig`, `LocaleOption`, `LocaleCode`, `LocalizedString`, `MessageRef`, `MessageTree`, `MessageCatalog`, `PageLoader`, `LocalizedPageOptions`.
+Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useSiteConfig`, `useLocale`, `useLocalize`, `tk`, `resolveLocalized`, `resolveField`, `resolveMessage`, `mergeCatalog`, `flattenMessages`, `isMessageRef`, `localizedPage`, `builtinMessages`, `themeRefKey`, `localeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteExternalLink`, `ShellConfig`, `ShellAction`, `ShellActionLoader`, `NavItem`, `StandalonePage`, `PageLayout`, `AuthRule`, `AuthContext`, `AuthConfig`, `RouterConfig`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`, `I18nConfig`, `LocaleOption`, `LocaleCode`, `LocalizedString`, `IconRegistry`, `MessageRef`, `MessageTree`, `MessageCatalog`, `PageLoader`, `LocalizedPageOptions`.
 
 ### Theme in Vue pages (`useTheme`)
 

package/README.zh.md

@@ -29,6 +29,7 @@ import { defineConfig } from '@bndynet/vue-site'
 
 export default defineConfig({
   title: 'My Project',
+  favicon: '/favicon.ico',
   nav: [
     { label: 'Home', icon: 'home', page: () => import('./README.md?raw') },
     { label: 'Guide', icon: 'book-open', page: () => import('./pages/guide.md?raw') },
@@ -42,6 +43,7 @@ export default defineConfig({
 my-site/
   package.json
   site.config.ts
+  public/favicon.ico
   README.md
   pages/guide.md
 ```
@@ -72,7 +74,9 @@ npx vue-site build --base /app/
 |----------|-------------|
 | `title` | 站点标题（侧边栏 + 标签页）。`LocalizedString` |
 | `nav` | `NavItem[]` |
+| `navPosition` | 可选的导航位置：`'top'` 强制使用顶部/分层导航，`'sidebar'` 强制将完整导航树放在侧边栏。不传时保持基于导航深度的自动行为 |
 | `defaultPath` | 站点打开时的路径；`/` 和未知路径会重定向到此。必须匹配一个已注册的路由（某个 `nav` 条目解析后的路径，或某个 `pages` 条目的 `path`）。默认为第一个顶级 `nav` 条目 |
+| `favicon` | 浏览器标签页图标 URL。可使用 public 资源路径、远程 URL 或导入后的资源 URL |
 | `logo` | Logo 的 URL 或导入的图片 |
 | `theme` | 见下方 `ThemeConfig`；设为 `false` 可禁用主题（隐藏切换器、强制使用固定的 `light` 调色板、不进行 localStorage 持久化） |
 | `i18n` | 多语言配置（`I18nConfig`）—— 参见[国际化](#国际化-i18n) |
@@ -95,11 +99,36 @@ npx vue-site build --base /app/
 | `icon` | [Lucide](https://lucide.dev/icons) 图标名 |
 | `page` | 页面内容。最简单的是一个**文件路径字符串**，如 `'./pages/AdminView.vue'` 或 `'./README.md'`（自动加载各语言的同名文件，找不到时回退到基础文件）。也接受加载器（`() => import('./Page.vue')` / `() => import('./page.md?raw')`）或 `localizedPage(...)` 的返回值。见[按语言区分的页面内容](#按语言区分的页面内容)与[高级页面加载器](#高级页面加载器) |
 | `path` | 路由路径（省略时从 `label` 的默认语言值派生；切换语言时保持稳定） |
+| `layout` | 页面内容宽度：`'default'` 保持标准居中阅读宽度，`'wide'` 使用更宽的居中画布，`'full'` 以无框架内边距的方式填满可用父容器。对分组和链接无效。 |
 | `children` | 嵌套分组 |
 | `link` | 渲染为超链接（内部路由路径或外部 URL），而非页面路由 |
 | `visible` | `() => boolean \| Promise<boolean>`，在启动时等待执行一次。返回 `false` 会从导航中隐藏该条目并跳过其路由（无法通过直接 URL 访问）。被隐藏的父项会隐藏其整个子树；没有剩余子项的分组会被剪除。对后续变化不具响应性。 |
 | `auth` | 由 `auth.authorize` 解释的授权规则（`AuthRule`）。会保持路由注册并通过导航守卫强制执行（因此直接访问 URL 会重定向到登录页）。需要配置 `SiteConfig.auth`。参见[按页面授权](#按页面授权-auth)。 |
 
+### `StandalonePage`
+
+| 属性 | 说明 |
+|----------|-------------|
+| `path` | 路由路径，按原样使用（如 `/landing`） |
+| `page` | 页面内容。接受形式与 `NavItem.page` 相同 |
+| `layout` | 可选内容宽度。省略时保持 standalone 默认行为：全屏、无内边距画布。 |
+| `visible` | `() => boolean \| Promise<boolean>`，在启动时等待执行一次。返回 `false` 会跳过该路由注册。 |
+| `auth` | 授权规则（`AuthRule`），由与 `NavItem.auth` 相同的导航守卫强制执行。 |
+
+### 页面布局
+
+当默认阅读宽度太窄时，可以在 `NavItem` 页面上设置 `layout`：
+
+```typescript
+export default defineConfig({
+  nav: [
+    { label: 'Docs', icon: 'book', page: './pages/docs.md' },
+    { label: 'Reports', icon: 'table', layout: 'wide', page: './pages/reports.vue' },
+    { label: 'Dashboard', icon: 'gauge', layout: 'full', page: './pages/dashboard.vue' },
+  ],
+})
+```
+
 ### `ThemeConfig`
 
 内置主题为 `light`、`dark`，外加始终可用的额外主题 `sepia` 和 `ocean`（在每个站点的切换器中都会显示）。在 `SiteConfig` 上设置 `theme: false` 可完全禁用主题。
@@ -468,7 +497,7 @@ app.mount('#app')
 返回 `Promise` 时会 **await** 它。如果你在配置中设置了可选的 `bootstrap`，该模块会在应用创建前加载；
 如果省略 `bootstrap`，则跳过该步骤。
 
-导出：`createSiteApp`、`defineConfig`、`useTheme`、`useSiteConfig`、`useLocale`、`useLocalize`、`tk`、`resolveLocalized`、`resolveField`、`resolveMessage`、`mergeCatalog`、`flattenMessages`、`isMessageRef`、`localizedPage`、`builtinMessages`、`themeRefKey`、`localeRefKey`。类型：`SiteConfig`、`SiteEnvConfig`、`SiteViteConfig`、`SiteExternalLink`、`NavItem`、`StandalonePage`、`AuthRule`、`AuthContext`、`AuthConfig`、`RouterConfig`、`ThemeConfig`、`ThemeOption`、`ThemePaletteVars`、`ResolvedNavItem`、`I18nConfig`、`LocaleOption`、`LocaleCode`、`LocalizedString`、`MessageRef`、`MessageTree`、`MessageCatalog`、`PageLoader`、`LocalizedPageOptions`。
+导出：`createSiteApp`、`defineConfig`、`useTheme`、`useSiteConfig`、`useLocale`、`useLocalize`、`tk`、`resolveLocalized`、`resolveField`、`resolveMessage`、`mergeCatalog`、`flattenMessages`、`isMessageRef`、`localizedPage`、`builtinMessages`、`themeRefKey`、`localeRefKey`。类型：`SiteConfig`、`SiteEnvConfig`、`SiteViteConfig`、`SiteExternalLink`、`NavItem`、`StandalonePage`、`PageLayout`、`AuthRule`、`AuthContext`、`AuthConfig`、`RouterConfig`、`ThemeConfig`、`ThemeOption`、`ThemePaletteVars`、`ResolvedNavItem`、`I18nConfig`、`LocaleOption`、`LocaleCode`、`LocalizedString`、`MessageRef`、`MessageTree`、`MessageCatalog`、`PageLoader`、`LocalizedPageOptions`。
 
 ### 在 Vue 页面中使用主题（`useTheme`）
 

package/bin/vue-site.mjs

@@ -2,6 +2,9 @@
 
 import { createServer, build, preview, mergeConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
+import AutoImport from 'unplugin-auto-import/vite'
+import Components from 'unplugin-vue-components/vite'
+import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
 import { resolve, dirname, basename } from 'path'
 import { fileURLToPath, pathToFileURL } from 'url'
 import { createRequire } from 'module'
@@ -11,17 +14,29 @@ import fs from 'fs'
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 const pkgDir = resolve(__dirname, '..')
-const require = createRequire(import.meta.url)
 const FRAMEWORK_PACKAGE = '@bndynet/vue-site'
 const frameworkEntry = resolve(pkgDir, 'dist/index.es.js')
 const frameworkStyle = resolve(pkgDir, 'dist/style.css')
 
-function resolvePkgDir(pkg) {
-  return dirname(require.resolve(`${pkg}/package.json`))
+function resolvePkgDir(pkg, from = import.meta.url) {
+  return dirname(createRequire(from).resolve(`${pkg}/package.json`))
+}
+
+function toVitePath(file) {
+  return file.replace(/\\/g, '/')
 }
 
 const vuePath = resolvePkgDir('vue')
 const vueRouterPath = resolvePkgDir('vue-router')
+const lucidePath = resolvePkgDir('lucide-vue-next')
+const elementPlusPath = resolvePkgDir('element-plus')
+const elementPlusPackage = resolve(elementPlusPath, 'package.json')
+const elementPlusIconsPath = resolvePkgDir('@element-plus/icons-vue', elementPlusPackage)
+const dayjsPath = resolvePkgDir('dayjs', elementPlusPackage)
+const lucideAliasPath = toVitePath(lucidePath)
+const elementPlusAliasPath = toVitePath(elementPlusPath)
+const elementPlusIconsAliasPath = toVitePath(elementPlusIconsPath)
+const dayjsAliasPath = toVitePath(dayjsPath)
 const cwd = process.cwd()
 /** Lets `import('../file.md?raw')` work when `site.config` lives in a subfolder (README next to cwd). In-repo, ../ often falls under pkgDir; from npm install it does not, so we allow cwd's parent explicitly. */
 const cwdParent = resolve(cwd, '..')
@@ -110,6 +125,8 @@ const VIRTUAL_ENTRY = 'virtual:vue-site-entry'
 const RESOLVED_ENTRY = '\0' + VIRTUAL_ENTRY
 const VIRTUAL_PACKAGE = 'virtual:vue-site-package'
 const RESOLVED_PACKAGE = '\0' + VIRTUAL_PACKAGE
+const VIRTUAL_ICONS = 'virtual:vue-site-icons'
+const RESOLVED_ICONS = '\0' + VIRTUAL_ICONS
 
 function parseRepositoryUrl(pkg) {
   const r = pkg.repository
@@ -169,6 +186,25 @@ function resolveBootstrapUrl(path) {
   return '/' + t.replace(/^\.\//, '')
 }
 
+function escapeHtmlAttr(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/</g, '&lt;')
+}
+
+function getConfiguredFavicon(siteConfig) {
+  const favicon = siteConfig?.favicon
+  return typeof favicon === 'string' ? favicon.trim() : ''
+}
+
+function buildFaviconLink(siteConfig) {
+  const favicon = getConfiguredFavicon(siteConfig)
+  return favicon
+    ? `  <link rel="icon" href="${escapeHtmlAttr(favicon)}" />\n`
+    : ''
+}
+
 // Friendly display names for auto-discovered locale files (`/locales/<code>.json`). Used only when
 // the config doesn't declare `i18n.locales`; unknown codes fall back to the code itself.
 const LOCALE_LABELS = {
@@ -213,12 +249,12 @@ function buildBootstrapScript({ siteConfig, siteConfigSpecifier }) {
       : ''
   return [
     bootstrapImport,
-    `import 'element-plus/dist/index.css'`,
     `import 'element-plus/theme-chalk/dark/css-vars.css'`,
     `import { createSiteApp } from '${FRAMEWORK_PACKAGE}'`,
     `import '${FRAMEWORK_PACKAGE}/style.css'`,
     `import siteConfig from '${siteConfigSpecifier}'`,
     `import { repositoryUrl } from '${VIRTUAL_PACKAGE}'`,
+    `import { iconRegistry } from '${VIRTUAL_ICONS}'`,
     ``,
     `// Auto-discover translations: /locales/<code>.json -> { [code]: { ...messages } }.`,
     `const __localeFiles = import.meta.glob('/locales/*.json', { eager: true, import: 'default' })`,
@@ -274,6 +310,7 @@ function buildBootstrapScript({ siteConfig, siteConfigSpecifier }) {
     `    ...(hasThemeQuery ? { theme: { ...(siteConfig.theme || {}), default: resolvedTheme } } : {}),`,
     `    packageRepository: repositoryUrl,`,
     `    baseUrl: import.meta.env.BASE_URL,`,
+    `    icons: { ...iconRegistry, ...(siteConfig.icons || {}) },`,
     `  })`,
     `  app.mount('#app')`,
     `})()`,
@@ -287,13 +324,13 @@ function buildEntryCode(siteConfig) {
   })
 }
 
-function buildHtmlShell(scriptTag) {
+function buildHtmlShell(scriptTag, siteConfig) {
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title></title>
+${buildFaviconLink(siteConfig)}  <title></title>
 </head>
 <body>
   <div id="app"></div>
@@ -302,10 +339,6 @@ function buildHtmlShell(scriptTag) {
 </html>`
 }
 
-const htmlTemplate = buildHtmlShell(
-  `<script type="module" src="/@id/__x00__${VIRTUAL_ENTRY}"></script>`,
-)
-
 // esbuild plugin stubbing asset / SFC / `?raw` imports (static or dynamic) to an empty default
 // export, so bundling the config for pre-load doesn't choke on resources Node can't load. Page
 // loaders are never invoked during pre-load (only build-time settings are read).
@@ -434,19 +467,41 @@ function fileToLocaleGlobExpr(rawPath) {
 // per-locale files get bundled. Two shapes are rewritten in the user's JS/TS under `cwd`:
 //   localizedPage('./file.md')  -> localizedPage(import.meta.glob([...], { query: '?raw' }))
 //   page: './file.md'           -> page: import.meta.glob([...], { query: '?raw' })
+//   shell.actions: ['./User.vue'] -> shell.actions: [() => import('./User.vue')]
 // Loader functions, locale maps (`localizedPage({ en, zh })`) and explicit `import.meta.glob` are
-// left untouched; the `page:` form only rewrites path-like values (starting with `.` or `/`).
-function localizedPageSugarPlugin() {
+// left untouched; the string forms only rewrite path-like values (starting with `.` or `/`).
+function configSugarPlugin() {
   const CALL_STRING_ARG = /(\blocalizedPage\s*\(\s*)(['"`])((?:\\.|(?!\2).)*)\2/g
   const PAGE_STRING_FIELD = /(\bpage\s*:\s*)(['"`])((?:\\.|(?!\2).)*)\2/g
+  const SHELL_ACTIONS_ARRAY = /(\bshell\s*:\s*\{[\s\S]*?\bactions\s*:\s*\[)([\s\S]*?)(\])/g
+  const STRING_LITERAL = /(['"`])((?:\\.|(?!\1).)*)\1/g
+
+  function rewriteShellActionArray(body) {
+    return body.replace(STRING_LITERAL, (match, _q, rawPath, offset) => {
+      if (!/^[./]/.test(rawPath)) return match
+
+      const before = body.slice(0, offset)
+      const after = body.slice(offset + match.length)
+      if (!/(^|,)\s*$/.test(before) || !/^\s*(,|$)/.test(after)) return match
+
+      return `() => import(${JSON.stringify(rawPath)})`
+    })
+  }
+
   return {
-    name: 'vue-site:localized-page-sugar',
+    name: 'vue-site:config-sugar',
     enforce: 'pre',
     transform(code, id) {
       const file = id.split('?')[0]
       if (!/\.(?:[cm]?[jt]sx?)$/.test(file)) return
       if (!file.startsWith(cwd) || file.includes('/node_modules/')) return
-      if (!code.includes('localizedPage(') && !/\bpage\s*:\s*['"`]/.test(code)) return
+      if (
+        !code.includes('localizedPage(') &&
+        !/\bpage\s*:\s*['"`]/.test(code) &&
+        !/\bshell\s*:\s*\{/.test(code)
+      ) {
+        return
+      }
       let changed = false
       let out = code.replace(CALL_STRING_ARG, (match, head, _q, rawPath) => {
         const expr = fileToLocaleGlobExpr(rawPath)
@@ -462,18 +517,160 @@ function localizedPageSugarPlugin() {
         changed = true
         return `${head}${expr}`
       })
+      out = out.replace(SHELL_ACTIONS_ARRAY, (match, head, body, tail) => {
+        const nextBody = rewriteShellActionArray(body)
+        if (nextBody === body) return match
+        changed = true
+        return `${head}${nextBody}${tail}`
+      })
       return changed ? { code: out, map: null } : undefined
     },
   }
 }
 
-function vueSitePlugin(entryCode) {
+const BUILTIN_ICON_NAMES = [
+  'sun',
+  'moon',
+  'palette',
+  'languages',
+  'github',
+  'coffee',
+  'waves',
+]
+
+function normalizeLucideIconName(name) {
+  const trimmed = String(name ?? '').trim()
+  if (!trimmed) return ''
+  return trimmed
+    .replace(/^lucide[\s_-]?/i, '')
+    .replace(/[\s_-]?icon$/i, '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase()
+}
+
+function toPascalIconName(name) {
+  return normalizeLucideIconName(name)
+    .split('-')
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}
+
+function readLucideIconExportMap() {
+  const map = new Map()
+  const entry = resolve(lucidePath, 'dist/esm/lucide-vue-next.js')
+  const code = fs.readFileSync(entry, 'utf-8')
+  const re = /export\s+\{([^}]+)\}\s+from\s+['"]\.\/icons\/([^'"]+)['"]/g
+  let match
+
+  while ((match = re.exec(code))) {
+    const exports = match[1]
+    const file = match[2]
+    for (const part of exports.split(',')) {
+      const alias = /default\s+as\s+([A-Za-z0-9_$]+)/.exec(part.trim())?.[1]
+      if (alias) map.set(alias, file)
+    }
+  }
+
+  return map
+}
+
+const lucideIconExportMap = readLucideIconExportMap()
+
+function addIconName(set, value) {
+  if (typeof value !== 'string') return
+  const name = value.trim()
+  if (name) set.add(name)
+}
+
+function collectNavIconNames(set, nav = []) {
+  for (const item of nav) {
+    addIconName(set, item?.icon)
+    collectNavIconNames(set, item?.children ?? [])
+  }
+}
+
+function collectIconNames(siteConfig = {}) {
+  const names = new Set(BUILTIN_ICON_NAMES)
+  const themeConfig =
+    siteConfig.theme && typeof siteConfig.theme === 'object'
+      ? siteConfig.theme
+      : undefined
+
+  collectNavIconNames(names, siteConfig.nav ?? [])
+
+  for (const link of siteConfig.links ?? []) {
+    addIconName(names, link?.icon)
+  }
+  for (const locale of siteConfig.i18n?.locales ?? []) {
+    addIconName(names, locale?.icon)
+  }
+  for (const theme of themeConfig?.extraThemes ?? []) {
+    addIconName(names, theme?.icon)
+  }
+
+  return [...names]
+}
+
+function buildIconRegistryCode(siteConfig) {
+  const imports = []
+  const entries = []
+  const imported = new Map()
+  const addedEntries = new Set()
+
+  for (const name of collectIconNames(siteConfig)) {
+    const normalized = normalizeLucideIconName(name)
+    if (!normalized) continue
+
+    const pascal = toPascalIconName(name)
+    const iconSource =
+      lucideIconExportMap.get(pascal) ??
+      lucideIconExportMap.get(`${pascal}Icon`) ??
+      `${normalized}.js`
+    const iconFile = resolve(lucidePath, 'dist/esm/icons', iconSource)
+
+    if (!fs.existsSync(iconFile)) {
+      console.warn(
+        `[vue-site] Icon "${name}" was not found in lucide-vue-next. It will render empty.`,
+      )
+      continue
+    }
+
+    let local = imported.get(normalized)
+    if (!local) {
+      local = `Icon${imported.size}`
+      imported.set(normalized, local)
+      imports.push(
+        `import ${local} from ${JSON.stringify(
+          `lucide-vue-next/dist/esm/icons/${iconSource}`,
+        )}`,
+      )
+    }
+
+    for (const key of new Set([name, normalized])) {
+      if (addedEntries.has(key)) continue
+      addedEntries.add(key)
+      entries.push(`  ${JSON.stringify(key)}: ${local},`)
+    }
+  }
+
+  return [
+    ...imports,
+    `export const iconRegistry = {`,
+    ...entries,
+    `}`,
+  ].join('\n')
+}
+
+function vueSitePlugin(entryCode, htmlTemplate, iconRegistryCode) {
   return [
     {
       name: 'vue-site:virtual-entry',
       resolveId(id) {
         if (id === VIRTUAL_ENTRY) return RESOLVED_ENTRY
         if (id === VIRTUAL_PACKAGE) return RESOLVED_PACKAGE
+        if (id === VIRTUAL_ICONS) return RESOLVED_ICONS
       },
       load(id) {
         if (id === RESOLVED_ENTRY) return entryCode
@@ -481,6 +678,7 @@ function vueSitePlugin(entryCode) {
           const url = readPackageRepositoryUrl()
           return `export const repositoryUrl = ${JSON.stringify(url)}`
         }
+        if (id === RESOLVED_ICONS) return iconRegistryCode
       },
     },
     {
@@ -619,6 +817,11 @@ async function buildViteConfig(options = {}) {
   }
 
   const entryCode = buildEntryCode(siteConfig)
+  const iconRegistryCode = buildIconRegistryCode(siteConfig)
+  const htmlTemplate = buildHtmlShell(
+    `<script type="module" src="/@id/__x00__${VIRTUAL_ENTRY}"></script>`,
+    siteConfig,
+  )
 
   // When watchPackages uses entryPath, SCSS files imported inside the watched
   // package source (e.g. Lit web components with `import styles from './foo.scss'`
@@ -651,10 +854,27 @@ async function buildViteConfig(options = {}) {
           },
         ]
       : []
+  const elementPlusResolver = ElementPlusResolver({
+    importStyle: 'css',
+  })
 
   const baseConfig = {
     root: cwd,
-    plugins: [localizedPageSugarPlugin(), vue(vueOpts), ...watchedScssPlugin, ...vueSitePlugin(entryCode), ...(userPlugins || [])],
+    plugins: [
+      configSugarPlugin(),
+      AutoImport({
+        resolvers: [elementPlusResolver],
+        dts: false,
+      }),
+      Components({
+        resolvers: [elementPlusResolver],
+        dts: false,
+      }),
+      vue(vueOpts),
+      ...watchedScssPlugin,
+      ...vueSitePlugin(entryCode, htmlTemplate, iconRegistryCode),
+      ...(userPlugins || []),
+    ],
     resolve: {
       alias: [
         { find: /^@bndynet\/vue-site$/, replacement: frameworkEntry },
@@ -670,20 +890,50 @@ async function buildViteConfig(options = {}) {
           find: 'vue-router',
           replacement: resolve(vueRouterPath, 'dist/vue-router.mjs'),
         },
+        {
+          find: /^lucide-vue-next$/,
+          replacement: toVitePath(resolve(lucidePath, 'dist/esm/lucide-vue-next.js')),
+        },
+        {
+          find: /^lucide-vue-next\//,
+          replacement: `${lucideAliasPath}/`,
+        },
+        {
+          find: /^element-plus$/,
+          replacement: toVitePath(resolve(elementPlusPath, 'es/index.mjs')),
+        },
+        {
+          find: /^element-plus\//,
+          replacement: `${elementPlusAliasPath}/`,
+        },
+        {
+          find: /^@element-plus\/icons-vue$/,
+          replacement: toVitePath(resolve(elementPlusIconsPath, 'dist/index.js')),
+        },
+        {
+          find: /^@element-plus\/icons-vue\//,
+          replacement: `${elementPlusIconsAliasPath}/`,
+        },
+        {
+          find: /^dayjs$/,
+          replacement: dayjsAliasPath,
+        },
+        {
+          find: /^dayjs\//,
+          replacement: `${dayjsAliasPath}/`,
+        },
       ],
     },
     optimizeDeps: {
-      // Pre-bundle element-plus so Vite crawls its dependency graph and
-      // discovers dayjs (a CJS/UMD package with no ESM default export).
-      // Without this, dayjs.min.js is served raw to the browser and
-      // Element Plus throws "does not provide an export named 'default'".
-      // The virtual entry only imports element-plus CSS, so Vite's static
-      // analysis never sees the JS side — this include bridges that gap.
-      include: ['element-plus'],
       // The virtual entry and user-authored pages both import the framework.
       // Keep it out of dependency pre-bundling so Vite does not instantiate
       // `dist/index.es.js` once via /@fs and again via node_modules/.vite.
       exclude: [FRAMEWORK_PACKAGE],
+      // Element Plus imports dayjs from ESM files, but dayjs itself ships as
+      // CommonJS. Force Vite's CJS interop for the package while letting
+      // discovered `dayjs/*` plugin imports be optimized normally.
+      include: ['dayjs'],
+      needsInterop: ['dayjs'],
     },
     server: {
       open: true,
@@ -723,6 +973,7 @@ async function run() {
       })
       const buildHtml = buildHtmlShell(
         `<script type="module">\n${bootstrapScript}\n  </script>`,
+        siteConfig,
       )
       fs.writeFileSync(tempHtml, buildHtml)
     }