@deot/docs-dever 1.1.1 → 1.1.3

package/README.md

@@ -54,6 +54,15 @@ development 和 preview 会保持服务运行；build 在 Vite 构建结束后
 - 为客户端路由提供 HTML history fallback；静态托管若只能配置自定义 404 页，请改用 Client 的 [`@deot/docs:redirect`](../client/README.md) 约定。
 - 在 build 模式复制 Markdown、JSON（含 `.page.json`）、SFC 等静态内容资源；
 - 当当前仓库源码存在时，将 locale、renderer、markdown、playground、theme 包映射到本地入口。
+- 在 development 模式提供 `GET /__docs/module/<包名>`，把工作区源码编成一份浏览器 ESM。preview 与 build 对该地址返回 404。
+
+## 本地模块
+
+`doc dev` 扫描项目 `packages/*/package.json`。存在 `src/index.ts` 或 `index.ts`，且真实路径仍在项目内时，可以用 `/__docs/module/<包名>` 取到编译结果。例如 `@deot/docs-locale` 对应 `/__docs/module/@deot/docs-locale`。
+
+当前包内的相对 `.vue`、`.ts`、`.tsx` 和样式会打进这一份 ESM，样式写入 iframe 的 `document.head`。`vue`、其它工作区包，以及其余裸导入保持原样，交给 Playground import map。`vue/jsx-runtime` 会打进包。
+
+站点自己决定是否使用这些地址。本仓库的 `index.html` 在 `window.__DOCS_RUNTIME__?.mode !== 'development'` 时把 `modules` 留空，development 时改指本地地址。直接打开 HTML 没有 runtime，因此仍走内置 CDN。管理页里对同名包的覆盖会压过 `index.html`。改完源码后刷新文档页；已打开的 Playground 不会热更新这份外部模块。
 
 ### `getDeverMode(options)`
 

package/dist/index.cjs

@@ -35,6 +35,7 @@ _vitejs_plugin_vue_jsx = __toESM(_vitejs_plugin_vue_jsx, 1);
 let node_fs = require("node:fs");
 node_fs = __toESM(node_fs, 1);
 let node_crypto = require("node:crypto");
+let node_module = require("node:module");
 let node_http = require("node:http");
 node_http = __toESM(node_http, 1);
 //#region packages/dever/src/workspace.ts
@@ -99,6 +100,272 @@ var resolveDocsWorkspace = (cwd = process.cwd(), workspace) => {
 		node_path.join(projectRoot, "index.html")
 	].join(" "));
 };
+var BUNDLED_SPECIFIERS = /* @__PURE__ */ new Set(["vue/jsx-runtime", "vue/jsx-dev-runtime"]);
+var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
+	"coverage",
+	"dist",
+	"node_modules"
+]);
+var cache = /* @__PURE__ */ new Map();
+var pending = /* @__PURE__ */ new Map();
+var buildCount = 0;
+var readPackageName = (manifestPath) => {
+	try {
+		const manifest = JSON.parse(node_fs.readFileSync(manifestPath, "utf8"));
+		return typeof manifest.name === "string" && manifest.name ? manifest.name : "";
+	} catch {
+		return "";
+	}
+};
+var resolveSourceEntry = (directory) => {
+	for (const relative of ["src/index.ts", "index.ts"]) {
+		const candidate = node_path.resolve(directory, relative);
+		if (!node_fs.existsSync(candidate) || !node_fs.statSync(candidate).isFile()) continue;
+		const realEntry = node_fs.realpathSync(candidate);
+		if (!isInside(directory, realEntry)) continue;
+		return realEntry;
+	}
+	return "";
+};
+/**
+* 收集项目 `packages/*` 里能编成浏览器模块的包。只接受留在项目内的真实路径。
+* @param projectRoot 文档项目根目录。
+* @returns 包名到源码入口的映射。同名包保留先扫描到的一项。
+*/
+var resolveWorkspaceModuleEntries = (projectRoot) => {
+	const realRoot = node_fs.existsSync(projectRoot) ? node_fs.realpathSync(projectRoot) : node_path.resolve(projectRoot);
+	const packagesDir = node_path.resolve(realRoot, "packages");
+	if (!node_fs.existsSync(packagesDir) || !node_fs.statSync(packagesDir).isDirectory()) return [];
+	const realPackages = node_fs.realpathSync(packagesDir);
+	if (!isInside(realRoot, realPackages)) return [];
+	const seen = /* @__PURE__ */ new Set();
+	const entries = [];
+	for (const item of node_fs.readdirSync(packagesDir, { withFileTypes: true })) {
+		if (!item.isDirectory() && !item.isSymbolicLink()) continue;
+		const directory = node_path.resolve(packagesDir, item.name);
+		if (!node_fs.existsSync(directory) || !node_fs.statSync(directory).isDirectory()) continue;
+		const realDirectory = node_fs.realpathSync(directory);
+		if (!isInside(realPackages, realDirectory)) continue;
+		const name = readPackageName(node_path.join(realDirectory, "package.json"));
+		const entry = name ? resolveSourceEntry(realDirectory) : "";
+		if (!name || !entry || seen.has(name)) continue;
+		seen.add(name);
+		entries.push({
+			name,
+			entry,
+			directory: realDirectory
+		});
+	}
+	return entries;
+};
+var directorySignature = (directory) => {
+	const files = [];
+	const walk = (current) => {
+		const realCurrent = node_fs.realpathSync(current);
+		if (!isInside(directory, realCurrent)) return;
+		for (const item of node_fs.readdirSync(realCurrent, { withFileTypes: true })) {
+			if (item.name === ".git" || IGNORED_DIRECTORIES.has(item.name)) continue;
+			const filename = node_path.join(realCurrent, item.name);
+			if (item.isSymbolicLink()) {
+				if (!node_fs.existsSync(filename)) continue;
+				const realName = node_fs.realpathSync(filename);
+				if (!isInside(directory, realName)) continue;
+				const stat = node_fs.statSync(realName);
+				if (stat.isDirectory()) walk(realName);
+				else if (stat.isFile()) files.push(`${realName}:${stat.mtimeMs}`);
+				continue;
+			}
+			if (item.isDirectory()) {
+				walk(filename);
+				continue;
+			}
+			if (item.isFile()) files.push(`${filename}:${node_fs.statSync(filename).mtimeMs}`);
+		}
+	};
+	walk(directory);
+	files.sort();
+	return files.join("\n");
+};
+var isWorkspaceModuleExternal = (id) => {
+	if (!id || id.startsWith("\0") || id.startsWith(".") || node_path.isAbsolute(id)) return false;
+	if (BUNDLED_SPECIFIERS.has(id)) return false;
+	return true;
+};
+var readAssetSource = (source) => typeof source === "string" ? source : Buffer.from(source).toString("utf8");
+var toBundleResult = (result) => {
+	const output = Array.isArray(result) ? result[0] : result;
+	if (!output || !("output" in output) || !Array.isArray(output.output)) throw new Error("Module build did not produce a bundle");
+	return output;
+};
+var injectStyles = (name, code, css) => {
+	if (!css) return code;
+	return [
+		"if (typeof document !== \"undefined\") {",
+		"	const style = document.createElement(\"style\");",
+		`\tstyle.setAttribute("data-docs-module", ${JSON.stringify(name)});`,
+		`\tstyle.textContent = ${JSON.stringify(css)};`,
+		"	document.head.appendChild(style);",
+		"}",
+		code
+	].join("\n");
+};
+var buildWorkspaceModule = async (projectRoot, entry) => {
+	buildCount += 1;
+	const bundle = toBundleResult(await (0, vite.build)({
+		configFile: false,
+		envFile: false,
+		root: projectRoot,
+		publicDir: false,
+		logLevel: "silent",
+		mode: "development",
+		appType: "custom",
+		define: { "process.env.NODE_ENV": JSON.stringify("development") },
+		plugins: [(0, _vitejs_plugin_vue.default)(), (0, _vitejs_plugin_vue_jsx.default)()],
+		build: {
+			write: false,
+			minify: false,
+			cssMinify: false,
+			cssCodeSplit: false,
+			sourcemap: false,
+			emptyOutDir: false,
+			copyPublicDir: false,
+			modulePreload: false,
+			reportCompressedSize: false,
+			assetsInlineLimit: 1e8,
+			chunkSizeWarningLimit: 1e5,
+			rolldownOptions: {
+				input: entry.entry,
+				preserveEntrySignatures: "strict",
+				treeshake: false,
+				external: isWorkspaceModuleExternal,
+				output: {
+					format: "es",
+					codeSplitting: false,
+					entryFileNames: "module.js"
+				}
+			}
+		}
+	}));
+	const chunks = bundle.output.filter((item) => item.type === "chunk");
+	if (chunks.length !== 1) throw new Error(`Expected a single module chunk, got ${chunks.length}`);
+	const css = bundle.output.filter((item) => item.type === "asset" && item.fileName.endsWith(".css")).map((item) => readAssetSource(item.source)).join("\n");
+	return injectStyles(entry.name, chunks[0].code, css);
+};
+/**
+* 把工作区包编成一份浏览器 ESM。`vue` 和其它工作区包保持裸导入。
+* @param projectRoot 用于解析 node_modules 的项目根。
+* @param entry 已通过边界检查的包入口。
+* @returns 可直接交给浏览器执行的模块源码。
+*/
+var compileWorkspaceModule = (projectRoot, entry) => {
+	const signature = directorySignature(entry.directory);
+	const cached = cache.get(entry.name);
+	if (cached?.signature === signature) return Promise.resolve(cached.code);
+	const inflight = pending.get(entry.name);
+	if (inflight) return inflight;
+	const task = buildWorkspaceModule(projectRoot, entry).then((code) => {
+		cache.set(entry.name, {
+			signature: directorySignature(entry.directory),
+			code
+		});
+		return code;
+	}).finally(() => {
+		if (pending.get(entry.name) === task) pending.delete(entry.name);
+	});
+	pending.set(entry.name, task);
+	return task;
+};
+var moduleFailure = (message) => `throw new Error(${JSON.stringify(message)});`;
+/**
+* 响应 `/__docs/module/<包名>`。未知包返回 404；编译失败返回会抛错的 ESM。
+* @param req 开发服务请求。
+* @param res 开发服务响应。
+* @param projectRoot 文档项目根目录。
+* @returns 是否已处理该请求。路径不匹配时为 false。
+*/
+var respondWorkspaceModule = async (req, res, projectRoot) => {
+	const pathname = (req.url || "/").split(/[?#]/u, 1)[0] || "/";
+	if (!pathname.startsWith("/__docs/module/")) return false;
+	if (req.method !== "GET" && req.method !== "HEAD") {
+		res.statusCode = 405;
+		res.setHeader("Allow", "GET, HEAD");
+		res.end("Method Not Allowed");
+		return true;
+	}
+	let name = "";
+	try {
+		name = decodeURIComponent(pathname.slice(15));
+	} catch {
+		res.statusCode = 400;
+		res.end("Bad Request");
+		return true;
+	}
+	if (!name || name.split("/").includes("..") || name.includes("\\") || name.includes("\0")) {
+		res.statusCode = 404;
+		res.end("Not Found");
+		return true;
+	}
+	const entry = resolveWorkspaceModuleEntries(projectRoot).find((item) => item.name === name);
+	if (!entry) {
+		res.statusCode = 404;
+		res.end("Not Found");
+		return true;
+	}
+	let code;
+	try {
+		code = await compileWorkspaceModule(projectRoot, entry);
+	} catch (reason) {
+		code = moduleFailure(reason instanceof Error ? reason.message : "Module compile failed");
+	}
+	res.statusCode = 200;
+	res.setHeader("Content-Type", "text/javascript; charset=utf-8");
+	res.setHeader("Cache-Control", "no-store");
+	if (req.method === "HEAD") res.end();
+	else res.end(code);
+	return true;
+};
+//#endregion
+//#region packages/dever/src/plugins/optional-dependencies.ts
+var resolveOptionalDependency = (id, importer) => {
+	if (!importer || !node_path.isAbsolute(importer) || /^[./]|:/.test(id)) return;
+	const filename = importer.split("?")[0];
+	const name = id.startsWith("@") ? id.split("/").slice(0, 2).join("/") : id.split("/")[0];
+	let directory = node_path.dirname(filename);
+	while (true) {
+		const manifest = node_path.join(directory, "package.json");
+		if (node_fs.existsSync(manifest)) {
+			const pkg = JSON.parse(node_fs.readFileSync(manifest, "utf8"));
+			if (!pkg.peerDependencies?.[name] || !pkg.peerDependenciesMeta?.[name]?.optional) return;
+			try {
+				(0, node_module.createRequire)(filename).resolve(id);
+			} catch (reason) {
+				if (reason.code === "MODULE_NOT_FOUND") return {
+					id: `https://cdn.jsdelivr.net/npm/${id}/+esm`,
+					external: true
+				};
+			}
+			return;
+		}
+		const parent = node_path.dirname(directory);
+		if (parent === directory) return;
+		directory = parent;
+	}
+};
+/**
+* 本地包未安装的 optional peer 由浏览器按需从 CDN 加载。
+* @returns 同时用于 Vite 模块转换与依赖预打包的解析插件。
+*/
+var createOptionalDependenciesPlugin = () => {
+	const resolver = {
+		name: "docs-optional-dependencies",
+		resolveId: resolveOptionalDependency
+	};
+	return {
+		...resolver,
+		enforce: "pre",
+		config: () => ({ optimizeDeps: { rolldownOptions: { plugins: [resolver] } } })
+	};
+};
 //#endregion
 //#region packages/dever/src/plugins/index.ts
 var innerPathRegex = /^\/(@|__)/;
@@ -298,6 +565,15 @@ var configureWorkspaceServer = (options, resolvedWorkspace) => (server) => {
 		let realResourceRoot = realWorkspace;
 		try {
 			const rawPathname = getRawPathname(req.url || "/");
+			if (/^\/__docs\/preview(?:-config-generate)?$/.test(rawPathname) && String(req.headers.accept || "").includes("text/html")) return next();
+			if (!options.preview && rawPathname.startsWith("/__docs/module/")) {
+				respondWorkspaceModule(req, res, resolved.projectRoot).catch((reason) => {
+					if (res.writableEnded) return;
+					res.statusCode = 500;
+					res.end(reason instanceof Error ? reason.message : "Module compile failed");
+				});
+				return;
+			}
 			if (rawPathname.startsWith("/__docs/") && rawPathname !== "/__docs/events") {
 				res.statusCode = 404;
 				res.end("Not Found");
@@ -469,15 +745,17 @@ var createHistoryPlugin = (options, resolvedWorkspace) => ({
 		server.middlewares.use(async (req, res, next) => {
 			const requestUrl = req.url || "/";
 			const url = requestUrl.replace(/\/+/g, "/").replace(/[?#].*$/s, "") || "";
+			const accept = String(req.headers?.accept || "text/html");
+			const isPreviewPage = /^\/__docs\/preview(?:-config-generate)?$/.test(url) && accept.includes("text/html");
 			const candidate = node_path.resolve(root, `.${url}`);
 			const isFile = node_fs.existsSync(candidate) && node_fs.statSync(candidate).isFile();
-			if (options.preview && url.startsWith("/__docs/")) {
+			if (options.preview && url.startsWith("/__docs/") && !isPreviewPage) {
 				res.statusCode = 404;
 				res.end("Not Found");
 				return;
 			}
-			if (res.writableEnded || requestUrl.includes("html-proxy&") || innerPathRegex.test(url) || isFile) return next();
-			if (!String(req.headers?.accept || "text/html").includes("text/html")) return next();
+			if (res.writableEnded || requestUrl.includes("html-proxy&") || innerPathRegex.test(url) && !isPreviewPage || isFile) return next();
+			if (!accept.includes("text/html")) return next();
 			const indexFile = resolvedWorkspace?.entry || resolveDocsWorkspace(options.preview ? root : process.cwd(), options.preview ? "." : options.workspace).entry;
 			if (!node_fs.existsSync(indexFile)) {
 				res.statusCode = 404;
@@ -542,6 +820,7 @@ var createStaticCopyPlugin = (options, resolvedWorkspace) => ({
 	}
 });
 var plugins_default = (options = {}, resolvedWorkspace) => (0, vite.defineConfig)({ plugins: [
+	createOptionalDependenciesPlugin(),
 	createRuntimePlugin(options, resolvedWorkspace),
 	createWorkspacePlugin(options, resolvedWorkspace),
 	createHistoryPlugin(options, resolvedWorkspace),
@@ -706,7 +985,8 @@ var createPreviewRequestHandler = (options) => {
 				return;
 			}
 			const pathname = decodeRequestPath(req.url || "/");
-			if (pathname.startsWith("/__docs/")) {
+			const isPreviewPage = /^\/__docs\/preview(?:-config-generate)?$/.test(pathname) && String(req.headers.accept || "").includes("text/html");
+			if (pathname.startsWith("/__docs/") && !isPreviewPage) {
 				res.statusCode = 404;
 				res.end("Not Found");
 				return;

package/dist/index.js

@@ -7,6 +7,7 @@ import vue from "@vitejs/plugin-vue";
 import vueJsx from "@vitejs/plugin-vue-jsx";
 import * as fs$1 from "node:fs";
 import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
 import * as http from "node:http";
 //#region packages/dever/src/workspace.ts
 /**
@@ -70,6 +71,272 @@ var resolveDocsWorkspace = (cwd = process.cwd(), workspace) => {
 		path.join(projectRoot, "index.html")
 	].join(" "));
 };
+var BUNDLED_SPECIFIERS = /* @__PURE__ */ new Set(["vue/jsx-runtime", "vue/jsx-dev-runtime"]);
+var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
+	"coverage",
+	"dist",
+	"node_modules"
+]);
+var cache = /* @__PURE__ */ new Map();
+var pending = /* @__PURE__ */ new Map();
+var buildCount = 0;
+var readPackageName = (manifestPath) => {
+	try {
+		const manifest = JSON.parse(fs$1.readFileSync(manifestPath, "utf8"));
+		return typeof manifest.name === "string" && manifest.name ? manifest.name : "";
+	} catch {
+		return "";
+	}
+};
+var resolveSourceEntry = (directory) => {
+	for (const relative of ["src/index.ts", "index.ts"]) {
+		const candidate = path.resolve(directory, relative);
+		if (!fs$1.existsSync(candidate) || !fs$1.statSync(candidate).isFile()) continue;
+		const realEntry = fs$1.realpathSync(candidate);
+		if (!isInside(directory, realEntry)) continue;
+		return realEntry;
+	}
+	return "";
+};
+/**
+* 收集项目 `packages/*` 里能编成浏览器模块的包。只接受留在项目内的真实路径。
+* @param projectRoot 文档项目根目录。
+* @returns 包名到源码入口的映射。同名包保留先扫描到的一项。
+*/
+var resolveWorkspaceModuleEntries = (projectRoot) => {
+	const realRoot = fs$1.existsSync(projectRoot) ? fs$1.realpathSync(projectRoot) : path.resolve(projectRoot);
+	const packagesDir = path.resolve(realRoot, "packages");
+	if (!fs$1.existsSync(packagesDir) || !fs$1.statSync(packagesDir).isDirectory()) return [];
+	const realPackages = fs$1.realpathSync(packagesDir);
+	if (!isInside(realRoot, realPackages)) return [];
+	const seen = /* @__PURE__ */ new Set();
+	const entries = [];
+	for (const item of fs$1.readdirSync(packagesDir, { withFileTypes: true })) {
+		if (!item.isDirectory() && !item.isSymbolicLink()) continue;
+		const directory = path.resolve(packagesDir, item.name);
+		if (!fs$1.existsSync(directory) || !fs$1.statSync(directory).isDirectory()) continue;
+		const realDirectory = fs$1.realpathSync(directory);
+		if (!isInside(realPackages, realDirectory)) continue;
+		const name = readPackageName(path.join(realDirectory, "package.json"));
+		const entry = name ? resolveSourceEntry(realDirectory) : "";
+		if (!name || !entry || seen.has(name)) continue;
+		seen.add(name);
+		entries.push({
+			name,
+			entry,
+			directory: realDirectory
+		});
+	}
+	return entries;
+};
+var directorySignature = (directory) => {
+	const files = [];
+	const walk = (current) => {
+		const realCurrent = fs$1.realpathSync(current);
+		if (!isInside(directory, realCurrent)) return;
+		for (const item of fs$1.readdirSync(realCurrent, { withFileTypes: true })) {
+			if (item.name === ".git" || IGNORED_DIRECTORIES.has(item.name)) continue;
+			const filename = path.join(realCurrent, item.name);
+			if (item.isSymbolicLink()) {
+				if (!fs$1.existsSync(filename)) continue;
+				const realName = fs$1.realpathSync(filename);
+				if (!isInside(directory, realName)) continue;
+				const stat = fs$1.statSync(realName);
+				if (stat.isDirectory()) walk(realName);
+				else if (stat.isFile()) files.push(`${realName}:${stat.mtimeMs}`);
+				continue;
+			}
+			if (item.isDirectory()) {
+				walk(filename);
+				continue;
+			}
+			if (item.isFile()) files.push(`${filename}:${fs$1.statSync(filename).mtimeMs}`);
+		}
+	};
+	walk(directory);
+	files.sort();
+	return files.join("\n");
+};
+var isWorkspaceModuleExternal = (id) => {
+	if (!id || id.startsWith("\0") || id.startsWith(".") || path.isAbsolute(id)) return false;
+	if (BUNDLED_SPECIFIERS.has(id)) return false;
+	return true;
+};
+var readAssetSource = (source) => typeof source === "string" ? source : Buffer.from(source).toString("utf8");
+var toBundleResult = (result) => {
+	const output = Array.isArray(result) ? result[0] : result;
+	if (!output || !("output" in output) || !Array.isArray(output.output)) throw new Error("Module build did not produce a bundle");
+	return output;
+};
+var injectStyles = (name, code, css) => {
+	if (!css) return code;
+	return [
+		"if (typeof document !== \"undefined\") {",
+		"	const style = document.createElement(\"style\");",
+		`\tstyle.setAttribute("data-docs-module", ${JSON.stringify(name)});`,
+		`\tstyle.textContent = ${JSON.stringify(css)};`,
+		"	document.head.appendChild(style);",
+		"}",
+		code
+	].join("\n");
+};
+var buildWorkspaceModule = async (projectRoot, entry) => {
+	buildCount += 1;
+	const bundle = toBundleResult(await build({
+		configFile: false,
+		envFile: false,
+		root: projectRoot,
+		publicDir: false,
+		logLevel: "silent",
+		mode: "development",
+		appType: "custom",
+		define: { "process.env.NODE_ENV": JSON.stringify("development") },
+		plugins: [vue(), vueJsx()],
+		build: {
+			write: false,
+			minify: false,
+			cssMinify: false,
+			cssCodeSplit: false,
+			sourcemap: false,
+			emptyOutDir: false,
+			copyPublicDir: false,
+			modulePreload: false,
+			reportCompressedSize: false,
+			assetsInlineLimit: 1e8,
+			chunkSizeWarningLimit: 1e5,
+			rolldownOptions: {
+				input: entry.entry,
+				preserveEntrySignatures: "strict",
+				treeshake: false,
+				external: isWorkspaceModuleExternal,
+				output: {
+					format: "es",
+					codeSplitting: false,
+					entryFileNames: "module.js"
+				}
+			}
+		}
+	}));
+	const chunks = bundle.output.filter((item) => item.type === "chunk");
+	if (chunks.length !== 1) throw new Error(`Expected a single module chunk, got ${chunks.length}`);
+	const css = bundle.output.filter((item) => item.type === "asset" && item.fileName.endsWith(".css")).map((item) => readAssetSource(item.source)).join("\n");
+	return injectStyles(entry.name, chunks[0].code, css);
+};
+/**
+* 把工作区包编成一份浏览器 ESM。`vue` 和其它工作区包保持裸导入。
+* @param projectRoot 用于解析 node_modules 的项目根。
+* @param entry 已通过边界检查的包入口。
+* @returns 可直接交给浏览器执行的模块源码。
+*/
+var compileWorkspaceModule = (projectRoot, entry) => {
+	const signature = directorySignature(entry.directory);
+	const cached = cache.get(entry.name);
+	if (cached?.signature === signature) return Promise.resolve(cached.code);
+	const inflight = pending.get(entry.name);
+	if (inflight) return inflight;
+	const task = buildWorkspaceModule(projectRoot, entry).then((code) => {
+		cache.set(entry.name, {
+			signature: directorySignature(entry.directory),
+			code
+		});
+		return code;
+	}).finally(() => {
+		if (pending.get(entry.name) === task) pending.delete(entry.name);
+	});
+	pending.set(entry.name, task);
+	return task;
+};
+var moduleFailure = (message) => `throw new Error(${JSON.stringify(message)});`;
+/**
+* 响应 `/__docs/module/<包名>`。未知包返回 404；编译失败返回会抛错的 ESM。
+* @param req 开发服务请求。
+* @param res 开发服务响应。
+* @param projectRoot 文档项目根目录。
+* @returns 是否已处理该请求。路径不匹配时为 false。
+*/
+var respondWorkspaceModule = async (req, res, projectRoot) => {
+	const pathname = (req.url || "/").split(/[?#]/u, 1)[0] || "/";
+	if (!pathname.startsWith("/__docs/module/")) return false;
+	if (req.method !== "GET" && req.method !== "HEAD") {
+		res.statusCode = 405;
+		res.setHeader("Allow", "GET, HEAD");
+		res.end("Method Not Allowed");
+		return true;
+	}
+	let name = "";
+	try {
+		name = decodeURIComponent(pathname.slice(15));
+	} catch {
+		res.statusCode = 400;
+		res.end("Bad Request");
+		return true;
+	}
+	if (!name || name.split("/").includes("..") || name.includes("\\") || name.includes("\0")) {
+		res.statusCode = 404;
+		res.end("Not Found");
+		return true;
+	}
+	const entry = resolveWorkspaceModuleEntries(projectRoot).find((item) => item.name === name);
+	if (!entry) {
+		res.statusCode = 404;
+		res.end("Not Found");
+		return true;
+	}
+	let code;
+	try {
+		code = await compileWorkspaceModule(projectRoot, entry);
+	} catch (reason) {
+		code = moduleFailure(reason instanceof Error ? reason.message : "Module compile failed");
+	}
+	res.statusCode = 200;
+	res.setHeader("Content-Type", "text/javascript; charset=utf-8");
+	res.setHeader("Cache-Control", "no-store");
+	if (req.method === "HEAD") res.end();
+	else res.end(code);
+	return true;
+};
+//#endregion
+//#region packages/dever/src/plugins/optional-dependencies.ts
+var resolveOptionalDependency = (id, importer) => {
+	if (!importer || !path.isAbsolute(importer) || /^[./]|:/.test(id)) return;
+	const filename = importer.split("?")[0];
+	const name = id.startsWith("@") ? id.split("/").slice(0, 2).join("/") : id.split("/")[0];
+	let directory = path.dirname(filename);
+	while (true) {
+		const manifest = path.join(directory, "package.json");
+		if (fs$1.existsSync(manifest)) {
+			const pkg = JSON.parse(fs$1.readFileSync(manifest, "utf8"));
+			if (!pkg.peerDependencies?.[name] || !pkg.peerDependenciesMeta?.[name]?.optional) return;
+			try {
+				createRequire(filename).resolve(id);
+			} catch (reason) {
+				if (reason.code === "MODULE_NOT_FOUND") return {
+					id: `https://cdn.jsdelivr.net/npm/${id}/+esm`,
+					external: true
+				};
+			}
+			return;
+		}
+		const parent = path.dirname(directory);
+		if (parent === directory) return;
+		directory = parent;
+	}
+};
+/**
+* 本地包未安装的 optional peer 由浏览器按需从 CDN 加载。
+* @returns 同时用于 Vite 模块转换与依赖预打包的解析插件。
+*/
+var createOptionalDependenciesPlugin = () => {
+	const resolver = {
+		name: "docs-optional-dependencies",
+		resolveId: resolveOptionalDependency
+	};
+	return {
+		...resolver,
+		enforce: "pre",
+		config: () => ({ optimizeDeps: { rolldownOptions: { plugins: [resolver] } } })
+	};
+};
 //#endregion
 //#region packages/dever/src/plugins/index.ts
 var innerPathRegex = /^\/(@|__)/;
@@ -269,6 +536,15 @@ var configureWorkspaceServer = (options, resolvedWorkspace) => (server) => {
 		let realResourceRoot = realWorkspace;
 		try {
 			const rawPathname = getRawPathname(req.url || "/");
+			if (/^\/__docs\/preview(?:-config-generate)?$/.test(rawPathname) && String(req.headers.accept || "").includes("text/html")) return next();
+			if (!options.preview && rawPathname.startsWith("/__docs/module/")) {
+				respondWorkspaceModule(req, res, resolved.projectRoot).catch((reason) => {
+					if (res.writableEnded) return;
+					res.statusCode = 500;
+					res.end(reason instanceof Error ? reason.message : "Module compile failed");
+				});
+				return;
+			}
 			if (rawPathname.startsWith("/__docs/") && rawPathname !== "/__docs/events") {
 				res.statusCode = 404;
 				res.end("Not Found");
@@ -440,15 +716,17 @@ var createHistoryPlugin = (options, resolvedWorkspace) => ({
 		server.middlewares.use(async (req, res, next) => {
 			const requestUrl = req.url || "/";
 			const url = requestUrl.replace(/\/+/g, "/").replace(/[?#].*$/s, "") || "";
+			const accept = String(req.headers?.accept || "text/html");
+			const isPreviewPage = /^\/__docs\/preview(?:-config-generate)?$/.test(url) && accept.includes("text/html");
 			const candidate = path.resolve(root, `.${url}`);
 			const isFile = fs$1.existsSync(candidate) && fs$1.statSync(candidate).isFile();
-			if (options.preview && url.startsWith("/__docs/")) {
+			if (options.preview && url.startsWith("/__docs/") && !isPreviewPage) {
 				res.statusCode = 404;
 				res.end("Not Found");
 				return;
 			}
-			if (res.writableEnded || requestUrl.includes("html-proxy&") || innerPathRegex.test(url) || isFile) return next();
-			if (!String(req.headers?.accept || "text/html").includes("text/html")) return next();
+			if (res.writableEnded || requestUrl.includes("html-proxy&") || innerPathRegex.test(url) && !isPreviewPage || isFile) return next();
+			if (!accept.includes("text/html")) return next();
 			const indexFile = resolvedWorkspace?.entry || resolveDocsWorkspace(options.preview ? root : process.cwd(), options.preview ? "." : options.workspace).entry;
 			if (!fs$1.existsSync(indexFile)) {
 				res.statusCode = 404;
@@ -513,6 +791,7 @@ var createStaticCopyPlugin = (options, resolvedWorkspace) => ({
 	}
 });
 var plugins_default = (options = {}, resolvedWorkspace) => defineConfig({ plugins: [
+	createOptionalDependenciesPlugin(),
 	createRuntimePlugin(options, resolvedWorkspace),
 	createWorkspacePlugin(options, resolvedWorkspace),
 	createHistoryPlugin(options, resolvedWorkspace),
@@ -677,7 +956,8 @@ var createPreviewRequestHandler = (options) => {
 				return;
 			}
 			const pathname = decodeRequestPath(req.url || "/");
-			if (pathname.startsWith("/__docs/")) {
+			const isPreviewPage = /^\/__docs\/preview(?:-config-generate)?$/.test(pathname) && String(req.headers.accept || "").includes("text/html");
+			if (pathname.startsWith("/__docs/") && !isPreviewPage) {
 				res.statusCode = 404;
 				res.end("Not Found");
 				return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deot/docs-dever",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",