@antdv-next/docs-plugins 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Antdv Next
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# @antdv-next/docs-plugins
+
+[antdv-next/docs-base](https://github.com/antdv-next/docs-base) 文档站点的插件与组件集:一条开箱即用的 Vite + markdown-it 管线,负责 Markdown → Vue 渲染、demo 收集、代码高亮与在线编辑,并附带可复用的 `<CodeDemo>` 展示组件。
+
+## 安装
+
+```bash
+pnpm add -D @antdv-next/docs-plugins
+```
+
+## 快速开始
+
+### 1. 接入 markdown 管线
+
+```ts
+// vite.config.ts
+import { mdPlugin } from '@antdv-next/docs-plugins'
+
+export default defineConfig({
+  plugins: [
+    mdPlugin(),
+  ],
+})
+```
+
+`mdPlugin()` = `md2VuePlugin`(Markdown → Vue SFC)+ `demoPlugin`(demo 收集虚拟模块),覆盖:
+
+- shiki 双主题高亮、anchor/toc/frontmatter/emoji、tip/warning 等容器、GitHub Alerts
+- demo 收集:页面里 `<demo src="./demo/basic.vue">标题</demo>` 生成锚点目录与按需加载的 demo 模块
+- 外部链接自动新标签页打开
+
+### 2. 编写文档与 demo
+
+```md
+## 代码演示 {#examples}   <!-- 英文页写 ## Examples -->
+
+<demo src="./demo/basic.vue">基本用法</demo>
+```
+
+- demo 文件放在页面同级的 `demo/` 目录(默认收集 `<root>/src/pages/**/demo/*.vue`,可用 `include` 调整)
+- demo SFC 内的 `<docs>` 自定义块作为该 demo 的描述文案
+- 锚点统一挂到 slug 为 `examples` 的标题下
+
+### 3. 隔离 markdown 样式(可选)
+
+```ts
+css: {
+  postcss: {
+    plugins: [postcssIsolateStyles()],
+  },
+},
+```
+
+## `<CodeDemo>` 组件(自定义 demo 渲染时使用)
+
+demo 的展示与在线编辑由包内组件承担,站点只需注入站点差异:
+
+```ts
+import CodeDemo from '@antdv-next/docs-plugins/component/code-demo/index.vue'
+import { provideDemoContext } from '@antdv-next/docs-plugins/component/code-demo/context'
+
+provideDemoContext({
+  locale: () => (route.meta?.locale === 'en-US' ? 'en-US' : 'zh-CN'),
+  isDark: () => isDark.value,
+  // 演示源码可 import 的模块(浏览器实时编译用),逐模块容错
+  modules: {
+    'antdv-next': () => import('antdv-next'),
+    '@antdv-next/icons': () => import('@antdv-next/icons'),
+  },
+  openPlayground: code => window.open(loadPlaygroundUrl(code), '_blank'),
+  // openStackBlitz / demoPageUrl / iframeRenderer / preferredCodeType 可选
+})
+```
+
+```vue
+<CodeDemo src="/src/pages/components/button/demo/basic.vue">
+  基本用法
+</CodeDemo>
+```
+
+- 展开代码面板即得可编辑编辑器(Sandpack),编辑内容经 `@vue/compiler-sfc` + `sucrase` 在浏览器端实时编译并替换预览
+- 未提供的能力(如 StackBlitz)对应按钮自动隐藏
+
+建议在 vite 中对这些依赖做 `resolve.dedupe`,保证与站点共享同一实例:
+
+```ts
+resolve: {
+  dedupe: ['vue', 'vue-router', '@vueuse/core', 'antdv-next', '@antdv-next/icons', 'antdv-style'],
+},
+```
+
+### virtual:demos 类型声明
+
+自定义 demo UI 时引用包内自带的类型:
+
+```ts
+/// <reference types="@antdv-next/docs-plugins/component/code-demo/virtual" />
+```
+
+## 默认行为与选项
+
+| 选项 | 默认 | 说明 |
+| --- | --- | --- |
+| `markdown.demo.headerMode` | `'examples'` | demo 锚点挂到 slug 为 `examples` 的标题下;`'section'` 为跟随章节层级 |
+| `markdown.demo.debugDemo` | `true` | 生产构建跳过带 `debug` 属性 demo 的目录收集 |
+| `markdown.demo.wrapper` | `'demo'` | demo 标签名 |
+| `markdown.externalLink` | `true` | 外部链接自动 `target="_blank"` + `rel="noopener noreferrer"` |
+| `demo.include` | `/src/pages/**/demo/*.vue` | demo 收集范围 |
+| `demo.sourceVersionOnHmr` | `true` | 任意 HMR 提升 sourceVersion,促使已挂载 demo 重新拉取源码 |
+| `demo.jsFormatter` | 内置 oxfmt | TS → JS 源码格式化器,可用 `createOxfmtJsFormatter(style)` 换风格 |
+| ~~`demo.renderSourceHtml` / `demo.virtualMode`~~ | 已移除 | 源码统一在浏览器端编译展示;`virtual:demos` 统一为懒加载注册表 |
+
+## API 总览
+
+- `mdPlugin(options)` / `md2VuePlugin` / `demoPlugin`
+- `createMarkdown` / `useMarkdown` / `loadBaseMd` / `loadShiki`(`CreateMarkdownOptions`)
+- markdown-it 插件:`container` / `demo` / `github-alerts` / `image` / `link` / `pre-wrapper` / `stackblitz` / `table`
+- `postcssIsolateStyles`:markdown 样式隔离 PostCSS 插件
+- `tsToJs` + `createOxfmtJsFormatter`:demo 源码 TS → JS 转换与格式化
+- 组件:`CodeDemo` + `provideDemoContext` / `useDemoContext`(类型:`DemoModule` / `DemoSourceData` 等)
+- 工具:`getDemoId` / `shortHash`
+
+## 本地开发
+
+```bash
+pnpm install        # 安装依赖
+pnpm build          # tsdown 构建 dist(插件部分;组件以 src 源码形态被站点引用)
+pnpm dev            # watch 模式
+pnpm lint           # eslint
+pnpm typecheck      # tsc --noEmit
+```
+
+下游站点开发期可通过 pnpm `link:` 引用本工程联调,发布后改为正常版本依赖。

package/dist/demo/formatter.d.ts

@@ -0,0 +1,17 @@
+import { JsFormatter } from "./tsToJs.js";
+//#region src/demo/formatter.d.ts
+interface OxfmtStyleOptions {
+  /** 语句末尾分号 */
+  semi?: boolean;
+  /** 使用单引号 */
+  singleQuote?: boolean;
+  [key: string]: unknown;
+}
+/**
+ * 基于 oxfmt 的内置 demo 源码 JS 格式化器。
+ * oxfmt 随本包安装，站点无需自行提供格式化器；
+ * 不可用时静默降级为不格式化。
+ */
+declare function createOxfmtJsFormatter(style?: OxfmtStyleOptions): JsFormatter;
+//#endregion
+export { OxfmtStyleOptions, createOxfmtJsFormatter };

package/dist/demo/formatter.js

@@ -0,0 +1,32 @@
+//#region src/demo/formatter.ts
+let oxfmtPromise = null;
+async function getOxfmtFormat() {
+	if (!oxfmtPromise) oxfmtPromise = (async () => {
+		try {
+			const { format } = await import("oxfmt");
+			return format;
+		} catch {
+			return null;
+		}
+	})();
+	return oxfmtPromise;
+}
+/**
+* 基于 oxfmt 的内置 demo 源码 JS 格式化器。
+* oxfmt 随本包安装，站点无需自行提供格式化器；
+* 不可用时静默降级为不格式化。
+*/
+function createOxfmtJsFormatter(style = {}) {
+	return async (code, lang) => {
+		try {
+			const format = await getOxfmtFormat();
+			if (!format) return code;
+			const result = await format(`virtual-demo-script.${lang === "tsx" ? "jsx" : "js"}`, code, style);
+			return result.errors.length > 0 ? code : result.code;
+		} catch {
+			return code;
+		}
+	};
+}
+//#endregion
+export { createOxfmtJsFormatter };

package/dist/demo/get-demo-id.d.ts

@@ -0,0 +1,9 @@
+//#region src/demo/get-demo-id.d.ts
+/**
+ * 由 demo 文件路径生成稳定的锚点 id：
+ * 取路径中最后一个 `demo` 目录往前一级（组件目录）组成的路径，
+ * 去掉扩展名并把分隔符替换为 `-`。
+ */
+declare function getDemoId(src: string): string;
+//#endregion
+export { getDemoId };

package/dist/demo/get-demo-id.js

@@ -0,0 +1,19 @@
+//#region src/demo/get-demo-id.ts
+const BACKSLASH_RE = /\\/g;
+const LEADING_SLASH_RE = /^\/+/;
+const EXTENSION_RE = /\.[^.]+$/;
+const PATH_SEP_RE = /[/\\.]/g;
+/**
+* 由 demo 文件路径生成稳定的锚点 id：
+* 取路径中最后一个 `demo` 目录往前一级（组件目录）组成的路径，
+* 去掉扩展名并把分隔符替换为 `-`。
+*/
+function getDemoId(src) {
+	if (!src) return "";
+	const reversedSegments = [...src.replace(BACKSLASH_RE, "/").split("/").filter(Boolean)].reverse();
+	const demoIndex = reversedSegments.findIndex((segment) => segment.toLowerCase() === "demo");
+	if (demoIndex === -1) return src.replace(LEADING_SLASH_RE, "").replace(EXTENSION_RE, "").replace(PATH_SEP_RE, "-");
+	return reversedSegments.slice(0, demoIndex + 2).reverse().join("/").replace(EXTENSION_RE, "").replace(PATH_SEP_RE, "-");
+}
+//#endregion
+export { getDemoId };

package/dist/demo/index.d.ts

@@ -0,0 +1,26 @@
+import { JsFormatter } from "./tsToJs.js";
+import { PluginOption } from "vite";
+//#region src/demo/index.d.ts
+interface DemoPluginOptions {
+  /**
+   * demo 文件 glob（相对于项目 root）
+   * @default 收集 root 下所有 `demo` 目录内的 `.vue` 文件
+   */
+  include?: string[];
+  /**
+   * 任意 HMR 更新时提升 sourceVersion，促使已挂载的 demo 重新拉取源码
+   * @default true
+   */
+  sourceVersionOnHmr?: boolean;
+  /**
+   * TS -> JS 源码格式化器，默认使用内置的 oxfmt 格式化器
+   */
+  jsFormatter?: JsFormatter;
+}
+/**
+ * 将绝对路径转换为相对于项目根目录的路径
+ */
+declare function toRelativePath(absolutePath: string, root: string): string;
+declare function demoPlugin(options?: DemoPluginOptions): PluginOption;
+//#endregion
+export { DemoPluginOptions, demoPlugin, toRelativePath };

package/dist/demo/index.js

@@ -0,0 +1,359 @@
+import { createOxfmtJsFormatter } from "./formatter.js";
+import { createMarkdown, loadBaseMd, loadShiki } from "../markdown.js";
+import { tsToJs } from "./tsToJs.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import pm from "picomatch";
+import { normalizePath } from "vite";
+import { parse } from "vue/compiler-sfc";
+//#region src/demo/index.ts
+const EXT_LANG_MAP = {
+	".json": "json",
+	".ts": "ts",
+	".tsx": "tsx",
+	".js": "js",
+	".jsx": "jsx",
+	".mjs": "js",
+	".cjs": "js",
+	".vue": "vue",
+	".css": "css",
+	".less": "less",
+	".scss": "scss",
+	".md": "md",
+	".html": "html"
+};
+function extLang(ext) {
+	return EXT_LANG_MAP[ext.toLowerCase()] ?? "text";
+}
+/**
+* 收集 demo 内相对导入的伴生文件（用于多文件代码 tab 展示）。
+* 跳过无扩展名的导入（如目录 index），避免内联无关模块。
+*/
+async function collectExtraFiles(filePath, sourceCode) {
+	const dir = path.dirname(filePath);
+	const seen = /* @__PURE__ */ new Set();
+	const files = [];
+	const importRegex = /(?:from|import)\s*(?:\(\s*)?["'](\.{1,2}\/[^"']+)["']/g;
+	for (let match = importRegex.exec(sourceCode); match !== null; match = importRegex.exec(sourceCode)) {
+		const rel = match[1];
+		const ext = path.extname(rel);
+		if (seen.has(rel) || !ext) continue;
+		seen.add(rel);
+		const resolved = path.resolve(dir, rel);
+		try {
+			const content = await fs.readFile(resolved, "utf-8");
+			const lang = extLang(ext);
+			files.push({
+				name: rel,
+				lang,
+				code: content
+			});
+		} catch {}
+	}
+	return files;
+}
+/**
+* 将绝对路径转换为相对于项目根目录的路径
+*/
+function toRelativePath(absolutePath, root) {
+	const normalizedPath = normalizePath(absolutePath);
+	const normalizedRoot = normalizePath(root);
+	return normalizedPath.startsWith(normalizedRoot) ? normalizedPath.slice(normalizedRoot.length) : normalizedPath;
+}
+function isDemoFile(filePath, root, patterns) {
+	const relativePath = toRelativePath(filePath, root);
+	return patterns.some((pattern) => pm.isMatch(relativePath, pattern));
+}
+function toDemoKey(filePath, root) {
+	const relativePath = toRelativePath(filePath, root);
+	return relativePath.startsWith("/") ? relativePath : `/${relativePath}`;
+}
+/**
+* 完整解析 demo 文件（用于 build 缓存和 dev source endpoint）
+*/
+async function parseDemoFile(filePath, md, options) {
+	const code = await fs.readFile(filePath, "utf-8");
+	const locales = await parseDemoLocales(code, filePath, md);
+	const sourceCode = code.replace(/<docs[^>]*>[\s\S]*?<\/docs>/g, "").trim();
+	return {
+		locales,
+		sourceCode,
+		jsSourceCode: await tsToJs(sourceCode, options.jsFormatter),
+		extraFiles: await collectExtraFiles(filePath, sourceCode)
+	};
+}
+/**
+* 仅解析 locales（用于 HMR 和 dev module code）
+*/
+async function parseDemoLocales(code, filePath, md) {
+	const { descriptor } = parse(code, {
+		filename: filePath,
+		sourceMap: false
+	});
+	const locales = {};
+	const docsBlocks = descriptor.customBlocks.filter((block) => block.type === "docs");
+	await Promise.all(docsBlocks.map(async (block) => {
+		const lang = typeof block.attrs.lang === "string" ? block.attrs.lang : "zh-CN";
+		const env = {};
+		const html = await md.renderAsync(block.content.trim(), env);
+		const formatterTitle = env.formatters?.title;
+		locales[lang] = {
+			html,
+			title: formatterTitle || (typeof env.title === "string" ? env.title : "")
+		};
+	}));
+	return locales;
+}
+function serializeSourceData(parsed) {
+	const data = {
+		source: parsed.sourceCode,
+		jsSource: parsed.jsSourceCode,
+		extraFiles: parsed.extraFiles
+	};
+	return JSON.stringify(data);
+}
+function demoPlugin(options = {}) {
+	const md = createMarkdown()({
+		withPlugin: false,
+		config(md) {
+			loadBaseMd(md);
+			loadShiki(md);
+		}
+	});
+	const VIRTUAL_MODULE_ID = "virtual:demos";
+	const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
+	const DEMO_SUFFIX = "demo=true";
+	const DEMO_GLOB = options.include ?? ["/src/pages/**/demo/*.vue"];
+	const DEMO_REGISTRY_ADD_EVENT = "demo-registry:add";
+	const DEMO_REGISTRY_REMOVE_EVENT = "demo-registry:remove";
+	const DEV_SOURCE_PATH = "/__demo_source";
+	const sourceVersionOnHmr = options.sourceVersionOnHmr ?? true;
+	const jsFormatter = options.jsFormatter ?? createOxfmtJsFormatter();
+	let isServe = false;
+	let root = process.cwd();
+	let base = "/";
+	const buildDemoParseCache = /* @__PURE__ */ new Map();
+	const devDemoParseTasks = /* @__PURE__ */ new Map();
+	async function getBuildParsedDemo(filePath) {
+		if (!buildDemoParseCache.has(filePath)) buildDemoParseCache.set(filePath, await parseDemoFile(filePath, md, { jsFormatter }));
+		return buildDemoParseCache.get(filePath);
+	}
+	function getDevParsedDemo(filePath) {
+		const currentTask = devDemoParseTasks.get(filePath);
+		if (currentTask) return currentTask;
+		const task = parseDemoFile(filePath, md, { jsFormatter }).finally(() => {
+			if (devDemoParseTasks.get(filePath) === task) devDemoParseTasks.delete(filePath);
+		});
+		devDemoParseTasks.set(filePath, task);
+		return task;
+	}
+	return {
+		name: "vite:demo",
+		enforce: "pre",
+		configResolved(config) {
+			isServe = config.command === "serve";
+			root = config.root;
+			base = config.base;
+		},
+		configureServer(server) {
+			const sourcePath = `${base === "/" ? "" : base.replace(/\/$/, "")}${DEV_SOURCE_PATH}`;
+			server.middlewares.use(async (request, response, next) => {
+				const url = new URL(request.url ?? "", "http://vite.local");
+				if (url.pathname !== sourcePath) return next();
+				const id = url.searchParams.get("id");
+				const filePath = id ? path.resolve(root, `.${id}`) : "";
+				const relativePath = filePath ? path.relative(root, filePath) : "..";
+				if (!id?.startsWith("/") || relativePath.startsWith("..") || path.isAbsolute(relativePath) || !isDemoFile(filePath, root, DEMO_GLOB)) {
+					response.statusCode = 400;
+					response.end("Invalid demo source path");
+					return;
+				}
+				try {
+					const parsed = await getDevParsedDemo(filePath);
+					response.statusCode = 200;
+					response.setHeader("Content-Type", "application/json; charset=utf-8");
+					response.setHeader("Cache-Control", "no-store");
+					response.end(serializeSourceData(parsed));
+				} catch (error) {
+					server.config.logger.error(`Failed to load demo source ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+					response.statusCode = 500;
+					response.end("Failed to load demo source");
+				}
+			});
+			const handleDemoAdd = (filePath) => {
+				if (!isDemoFile(filePath, server.config.root, DEMO_GLOB)) return;
+				server.ws.send({
+					type: "custom",
+					event: DEMO_REGISTRY_ADD_EVENT,
+					data: {
+						id: toDemoKey(filePath, server.config.root),
+						timestamp: Date.now()
+					}
+				});
+			};
+			const handleDemoRemove = (filePath) => {
+				if (!isDemoFile(filePath, server.config.root, DEMO_GLOB)) return;
+				server.ws.send({
+					type: "custom",
+					event: DEMO_REGISTRY_REMOVE_EVENT,
+					data: { id: toDemoKey(filePath, server.config.root) }
+				});
+			};
+			server.watcher.on("add", handleDemoAdd);
+			server.watcher.on("unlink", handleDemoRemove);
+		},
+		async resolveId(id, importer) {
+			if (id === VIRTUAL_MODULE_ID) return RESOLVED_VIRTUAL_MODULE_ID;
+			if (id.includes(DEMO_SUFFIX)) {
+				const resolved = await this.resolve(id, importer, { skipSelf: true });
+				if (resolved) return `\0${resolved.id}`;
+			}
+		},
+		async load(id) {
+			const [, query] = id.split("?");
+			const params = new URLSearchParams(query);
+			if (params.get("vue") !== null && params.get("type") === "docs") return "export default {}";
+			if (id === RESOLVED_VIRTUAL_MODULE_ID) return `
+import { shallowReactive } from 'vue'
+
+const demoLoaders = import.meta.glob(${JSON.stringify(DEMO_GLOB)}, {
+  query: { demo: 'true' },
+})
+
+const demos = shallowReactive({})
+
+async function registerDemo(id, timestamp = Date.now()) {
+  const mod = await import(/* @vite-ignore */ \`\${id}?demo=true&t=\${timestamp}\`)
+  demos[id] = mod.default ?? mod
+}
+
+export async function loadDemo(id) {
+  if (demos[id])
+    return demos[id]
+
+  const loader = demoLoaders[id]
+  if (!loader)
+    return null
+
+  const mod = await loader()
+  demos[id] = mod.default ?? mod
+  return demos[id]
+}
+
+function removeDemo(id) {
+  delete demos[id]
+}
+
+if (import.meta.hot) {
+  import.meta.hot.accept()
+  import.meta.hot.on(${JSON.stringify(DEMO_REGISTRY_ADD_EVENT)}, async (data) => {
+    if (!data?.id)
+      return
+    await registerDemo(data.id, data.timestamp)
+  })
+  import.meta.hot.on(${JSON.stringify(DEMO_REGISTRY_REMOVE_EVENT)}, (data) => {
+    if (!data?.id)
+      return
+    removeDemo(data.id)
+  })
+}
+
+export default demos
+`;
+			if (id.startsWith("\0") && id.includes(DEMO_SUFFIX)) {
+				const [filePath] = id.slice(1).split("?");
+				if (!filePath) return;
+				const normalizedFile = normalizePath(filePath);
+				this.addWatchFile(filePath);
+				const parsed = isServe ? void 0 : await getBuildParsedDemo(filePath);
+				const locales = parsed ? parsed.locales : await parseDemoLocales(await fs.readFile(filePath, "utf-8"), filePath, md);
+				for (const file of parsed?.extraFiles ?? []) this.addWatchFile(path.resolve(path.dirname(filePath), file.name));
+				const sourceUrl = isServe ? void 0 : this.getFileName(this.emitFile({
+					type: "asset",
+					name: `demo-source-${path.basename(filePath, ".vue")}.json`,
+					source: serializeSourceData(parsed)
+				}));
+				return {
+					code: isServe ? `
+import { ref } from 'vue'
+
+const localesRef = ref(${JSON.stringify(locales)})
+const sourceVersionRef = ref(0)
+
+const demoData = {
+  component: () => import(${JSON.stringify(filePath)}),
+  get locales() { return localesRef.value },
+  get sourceVersion() { return sourceVersionRef.value },
+  async loadSource(signal) {
+    const url = new URL(import.meta.env.BASE_URL + ${JSON.stringify(DEV_SOURCE_PATH.slice(1))}, window.location.origin)
+    url.searchParams.set('id', ${JSON.stringify(toDemoKey(filePath, root))})
+    url.searchParams.set('t', String(sourceVersionRef.value))
+    const res = await fetch(url.href, { cache: 'no-store', signal })
+    if (!res.ok)
+      throw new Error(\`Failed to load demo source: \${res.status} \${res.statusText}\`)
+    return res.json()
+  }
+}
+
+if (import.meta.hot) {
+  import.meta.hot.accept()${sourceVersionOnHmr ? `
+  import.meta.hot.on('vite:beforeUpdate', () => {
+    sourceVersionRef.value = Date.now()
+  })` : ""}
+  import.meta.hot.on(${JSON.stringify(`demo-update:${normalizedFile}`)}, (data) => {
+    if ('locales' in data) localesRef.value = data.locales
+    if ('timestamp' in data) sourceVersionRef.value = data.timestamp
+  })
+}
+
+export default demoData
+` : `
+import { ref } from 'vue'
+
+const localesRef = ref(${JSON.stringify(locales)})
+
+const demoData = {
+  component: () => import(${JSON.stringify(filePath)}),
+  get locales() { return localesRef.value },
+  sourceVersion: 0,
+  async loadSource(signal) {
+    const url = new URL(import.meta.env.BASE_URL + ${JSON.stringify(sourceUrl)}, import.meta.url)
+    const res = await fetch(url.href, { signal })
+    if (!res.ok)
+      throw new Error(\`Failed to load demo source: \${res.status} \${res.statusText}\`)
+    return res.json()
+  }
+}
+
+if (import.meta.hot) {
+  import.meta.hot.accept()
+  import.meta.hot.on(${JSON.stringify(`demo-update:${normalizedFile}`)}, (data) => {
+    if ('locales' in data) localesRef.value = data.locales
+  })
+}
+
+export default demoData
+`,
+					map: null
+				};
+			}
+		},
+		async handleHotUpdate(ctx) {
+			if (!isDemoFile(ctx.file, ctx.server.config.root, DEMO_GLOB)) return;
+			const normalizedFile = normalizePath(ctx.file);
+			buildDemoParseCache.delete(ctx.file);
+			const locales = await parseDemoLocales(await fs.readFile(ctx.file, "utf-8"), ctx.file, md);
+			ctx.server.ws.send({
+				type: "custom",
+				event: `demo-update:${normalizedFile}`,
+				data: {
+					locales,
+					timestamp: Date.now()
+				}
+			});
+			return ctx.modules;
+		}
+	};
+}
+//#endregion
+export { demoPlugin, toRelativePath };

package/dist/demo/tsToJs.d.ts

@@ -0,0 +1,9 @@
+//#region src/demo/tsToJs.d.ts
+/**
+ * TS -> JS 源码的格式化器。
+ * 站点各自注入（如 eslint / oxfmt），失败时返回原始代码即可。
+ */
+type JsFormatter = (code: string, lang: string) => Promise<string> | string;
+declare function tsToJs(sourceCode: string, format?: JsFormatter): Promise<string>;
+//#endregion
+export { JsFormatter, tsToJs };

package/dist/demo/tsToJs.js

@@ -0,0 +1,60 @@
+import { transformWithOxc } from "vite";
+//#region src/demo/tsToJs.ts
+const SCRIPT_BLOCK_REGEX = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+const SCRIPT_LANG_REGEX = /\blang\s*=\s*(['"]?)([\w-]+)\1/i;
+const TS_LANGS = /* @__PURE__ */ new Set([
+	"ts",
+	"tsx",
+	"mts",
+	"cts"
+]);
+const EXPORT_MARKER_REGEX = /\n?export\s*\{\s*\};?\s*$/u;
+async function transpileScript(code, lang) {
+	const oxcLang = lang === "tsx" ? "tsx" : "ts";
+	return (await transformWithOxc(code, `virtual-demo-script.${oxcLang}`, {
+		lang: oxcLang,
+		sourceType: "module",
+		target: "es2020",
+		jsx: oxcLang === "tsx" ? "preserve" : void 0,
+		typescript: { onlyRemoveTypeImports: true },
+		sourcemap: false
+	})).code.replace(EXPORT_MARKER_REGEX, "");
+}
+async function tsToJs(sourceCode, format) {
+	let nextSourceCode = "";
+	let lastIndex = 0;
+	SCRIPT_BLOCK_REGEX.lastIndex = 0;
+	for (const match of sourceCode.matchAll(SCRIPT_BLOCK_REGEX)) {
+		const [fullMatch, attrs = "", code = ""] = match;
+		const startIndex = match.index ?? 0;
+		nextSourceCode += sourceCode.slice(lastIndex, startIndex);
+		const langMatch = attrs.match(SCRIPT_LANG_REGEX);
+		if (!langMatch) {
+			nextSourceCode += fullMatch;
+			lastIndex = startIndex + fullMatch.length;
+			continue;
+		}
+		const [, quote, lang = ""] = langMatch;
+		const normalizedLang = lang.toLowerCase();
+		if (!TS_LANGS.has(normalizedLang)) {
+			nextSourceCode += fullMatch;
+			lastIndex = startIndex + fullMatch.length;
+			continue;
+		}
+		const nextLang = normalizedLang === "tsx" ? "jsx" : "js";
+		const wrappedQuote = quote || "\"";
+		const nextAttrs = attrs.replace(SCRIPT_LANG_REGEX, `lang=${wrappedQuote}${nextLang}${wrappedQuote}`);
+		try {
+			const transpiledCode = await transpileScript(code, normalizedLang);
+			const normalizedCode = format ? await format(transpiledCode, normalizedLang) : transpiledCode;
+			nextSourceCode += `<script${nextAttrs}>\n${normalizedCode.trim()}\n<\/script>`;
+		} catch {
+			nextSourceCode += fullMatch;
+		}
+		lastIndex = startIndex + fullMatch.length;
+	}
+	nextSourceCode += sourceCode.slice(lastIndex);
+	return nextSourceCode;
+}
+//#endregion
+export { tsToJs };