@bndynet/vue-site 1.2.0 → 1.3.0

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,16 @@ 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) |
 | `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 +101,36 @@ 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. 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' },
+  ],
+})
+```
+
 ### `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 +142,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 +531,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`, `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'
@@ -12,6 +15,9 @@ 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`))
@@ -166,6 +172,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 = {
@@ -208,13 +233,11 @@ function buildBootstrapScript({ siteConfig, siteConfigSpecifier }) {
     bs != null && String(bs).trim() !== ''
       ? `import '${resolveBootstrapUrl(bs)}'\n`
       : ''
-  const pkgDirUrl = pkgDir.replace(/\\/g, '/')
   return [
     bootstrapImport,
-    `import 'element-plus/dist/index.css'`,
     `import 'element-plus/theme-chalk/dark/css-vars.css'`,
-    `import { createSiteApp } from '${pkgDirUrl}/dist/index.es.js'`,
-    `import '${pkgDirUrl}/dist/style.css'`,
+    `import { createSiteApp } from '${FRAMEWORK_PACKAGE}'`,
+    `import '${FRAMEWORK_PACKAGE}/style.css'`,
     `import siteConfig from '${siteConfigSpecifier}'`,
     `import { repositoryUrl } from '${VIRTUAL_PACKAGE}'`,
     ``,
@@ -285,13 +308,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>
@@ -300,10 +323,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).
@@ -432,19 +451,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)
@@ -460,12 +501,18 @@ 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) {
+function vueSitePlugin(entryCode, htmlTemplate) {
   return [
     {
       name: 'vue-site:virtual-entry',
@@ -617,6 +664,10 @@ async function buildViteConfig(options = {}) {
   }
 
   const entryCode = buildEntryCode(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'`
@@ -649,24 +700,49 @@ 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),
+      ...(userPlugins || []),
+    ],
     resolve: {
-      alias: {
-        vue: resolve(vuePath, 'dist/vue.runtime.esm-bundler.js'),
-        'vue-router': resolve(vueRouterPath, 'dist/vue-router.mjs'),
-      },
+      alias: [
+        { find: /^@bndynet\/vue-site$/, replacement: frameworkEntry },
+        {
+          find: /^@bndynet\/vue-site\/style\.css$/,
+          replacement: frameworkStyle,
+        },
+        {
+          find: 'vue',
+          replacement: resolve(vuePath, 'dist/vue.runtime.esm-bundler.js'),
+        },
+        {
+          find: 'vue-router',
+          replacement: resolve(vueRouterPath, 'dist/vue-router.mjs'),
+        },
+      ],
     },
     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],
     },
     server: {
       open: true,
@@ -706,6 +782,7 @@ async function run() {
       })
       const buildHtml = buildHtmlShell(
         `<script type="module">\n${bootstrapScript}\n  </script>`,
+        siteConfig,
       )
       fs.writeFileSync(tempHtml, buildHtml)
     }

package/dist/components/ShellActions.vue.d.ts

@@ -0,0 +1,9 @@
+type __VLS_Props = {
+    placement?: 'top' | 'sidebar';
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    placement: "top" | "sidebar";
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    root: HTMLDivElement;
+}, any>;
+export default _default;

package/dist/composables/useSiteConfig.d.ts

@@ -4,6 +4,7 @@ export interface SiteContext {
     config: SiteConfig;
     resolvedNav: ResolvedNavItem[];
 }
+/** Use `Symbol.for` so pages still inject context if Vite resolves the package twice. */
 export declare const siteContextKey: InjectionKey<SiteContext>;
 export declare function provideSiteConfig(context: SiteContext): void;
 export declare function useSiteConfig(): SiteContext;

package/dist/index.d.ts

@@ -9,5 +9,5 @@ export { builtinMessages } from './i18n-messages';
 export { useSiteConfig } from './composables/useSiteConfig';
 export { builtinThemePalettes } from './theme/presets';
 export { ElMessage, ElMessageBox, ElNotification, } from 'element-plus';
-export type { SiteConfig, SiteEnvConfig, SiteViteConfig, SiteExternalLink, NavItem, StandalonePage, AuthRule, AuthContext, AuthConfig, RouterConfig, ThemeConfig, ThemeOption, ThemePaletteVars, ResolvedNavItem, LocaleCode, LocalizedString, MessageRef, MessageTree, LocaleOption, I18nConfig, PageLoader, } from './types';
+export type { SiteConfig, SiteEnvConfig, SiteViteConfig, SiteExternalLink, ShellConfig, ShellAction, ShellActionLoader, NavItem, StandalonePage, PageLayout, AuthRule, AuthContext, AuthConfig, RouterConfig, ThemeConfig, ThemeOption, ThemePaletteVars, ResolvedNavItem, LocaleCode, LocalizedString, MessageRef, MessageTree, LocaleOption, I18nConfig, PageLoader, } from './types';
 export declare function defineConfig(config: SiteConfig): SiteConfig;