@deot/docs-playground 1.1.5 → 1.1.7

package/README.md

@@ -53,7 +53,7 @@ const files = ref({
 | `id` | `string` | `''` | 标题锚点 id；未传时从 `title` 自动生成。仅挂在内联 runtime 标题上，弹窗不重复。 |
 | `expandable` | `true \| number` | `undefined` | 开启预览高度展开；未传不显示控件；`true` 展开到剩余视口；正数为目标高度（px）。 |
 | `previewScroller` | `boolean` | `false` | 在 iframe 内用 `@deot/vc` Scroller 替换原生滚动条；开启后会动态探测 `Scroller`，不存在则回退原生滚动。 |
-| `local` | `boolean` | `false` | 在当前文档编译并挂载，不使用 iframe。`vue` 使用宿主同一份实例；其余 import map 仍是 URL，加载后作为模块变量。 |
+| `local` | `boolean` | `true` | 在当前文档编译并挂载。内置模块默认继承宿主，可通过 import map 逐个覆盖；预览使用所选 Vue 运行时挂载。 |
 | `options` | `PlaygroundOptions` | `{}` | 传给 Vue REPL store 的实例级选项；`cdnURL` 会同时作用于预览样式和默认 import map。 |
 | `previewOptions` | `SandboxProps['previewOptions']` | `undefined` | 传给当前 iframe 的 preview 选项。 |
 | `locale` | `Language` | `en-US` | 界面语言；未传入时使用上层 Locale Provider。 |
@@ -149,18 +149,19 @@ const handleMessage = async () => {
 
 同时导出 `PlaygroundFiles`、`PlaygroundView`、`PlaygroundViewport`、`PlaygroundOptions`、`PlaygroundPreviewOptions`、`EditorFilesChange` 和 `EditorFilesChangeAction` 类型。
 
-站点级 Playground 模块与预览 CSS 默认由 Client 的 `$docs.modules` 与 `$docs.styles` 管理（见 [`@deot/docs-client`](../client/README.md)）。独立嵌入 Playground 时，可通过 `options.builtinImportMap` 与 `options.cdnURL` 覆盖实例级配置。
+站点级 Playground 模块与预览 CSS 默认由 Client 的 `$docs.modules` 与 `$docs.styles` 管理（见 [`@deot/docs-client`](../client/README.md)）。模块地址优先级由低到高为：内置默认 → `$docs.modules` → 管理页覆盖 → 实例 `options.builtinImportMap.imports`。实例只覆盖声明的模块，其余继承默认配置；也可通过 `options.cdnURL` 调整默认 CDN。
 
 ## 运行环境
 
-- Playground 运行时通过公共 CDN 加载 Vue 和默认 import map 中的依赖，手工预览需要网络访问。
+- iframe 运行时通过公共 CDN 加载 Vue 和默认 import map 中的依赖；local 运行时加载 URL 覆盖或宿主未提供的模块时也需要网络访问。
 - 默认 CDN 为 `https://cdn.jsdelivr.net/npm`，可通过 `options.cdnURL` 换成 unpkg 等兼容 `/{package}/{file}` 路径的镜像；该地址用于预览样式和内置 import map。
 - `lodash-es` 和在线 Sass 编译器使用 jsDelivr 的 `/+esm` 入口；unpkg 等 CDN 不支持该路径。
-- 直接渲染时，未配置的 npm 模块（含作用域包和子路径）自动从 jsDelivr 的 `/+esm` 入口加载；组件包的传递依赖也适用，`import()` 在调用时加载。`@deot/vc` 的组件、hooks 和 locale 走远程模块加载器，Vue 保持与宿主共用。可用 `options.builtinImportMap.imports` 指定依赖的版本和 URL。
+- 直接渲染时，宿主未提供且未配置的 npm 模块（含作用域包和子路径）自动从 jsDelivr 的 `/+esm` 入口加载；组件包的传递依赖也适用，`import()` 在调用时加载。可用 `options.builtinImportMap.imports` 指定依赖的版本和 URL。
 - Vue SFC 的 `<style lang="scss">` / `lang="sass"` 以及独立 `.scss` / `.sass` 文件会在浏览器里编译；`_partial.scss` 只作为 `@use` 依赖。
-- `options.builtinImportMap.imports` 可以覆盖默认模块 URL。Vue 运行时仍从 `play.vuejs.org` 加载。
+- local 模式按模块识别显式 URL 覆盖，即使地址与内置默认相同也会加载该 URL。覆盖 `vue` 时，预览的编译产物、挂载、组件引用和注入使用这份 Vue；内置组件、hooks、locale、Pinia 和 vue-router 随之重新加载以匹配 Vue，未覆盖的普通工具模块继续复用宿主。不同预览的覆盖互不影响，显式覆盖的模块在各自预览内执行。
+- local 模式在当前页面按 URL 缓存外部模块的下载和转换成果，并合并并发请求；切换文档时可复用，最多保留最近使用的 128 个模块。各预览仍独立执行模块并解析依赖覆盖；失败的加载不缓存，同源模块实时读取，刷新页面会清空缓存。
 - 每个 Playground 实例都使用自己的 preview 配置和 iframe 消息来源校验。
-- `local` 默认开启：同一份 `files` 在当前文档里编译。内置依赖默认用宿主副本；`modules` 里与默认 CDN 不同的地址会覆盖，包括 `vue` 和 `vue/server-renderer`。直接渲染不撑开预览高度，`expandable` 固定为关闭，`docs:playground.run` 不会申请临时高度；`<DocsLink>` 仍通过 `docs:navigate` 通知。`local: false` 改回 iframe Sandbox。
+- `local` 默认开启：同一份 `files` 在当前文档里编译。直接渲染不撑开预览高度，`expandable` 固定为关闭，`docs:playground.run` 不会申请临时高度；`<DocsLink>` 仍通过 `docs:navigate` 通知。`local: false` 改回 iframe Sandbox。
 
 ## 仓库内 examples
 

package/dist/index.cjs

@@ -170,10 +170,10 @@ var icon_default = /* @__PURE__ */ (0, vue.defineComponent)({
 });
 //#endregion
 //#region packages/playground/src/core/code-preview/github.css?inline
-var github_default = "pre code.hljs{display:block;padding:1em}code.hljs{padding:3px 5px}.hljs{color:#24292e;background:#fff}.hljs-doctag,.hljs-keyword,.hljs-meta .hljs-keyword,.hljs-template-tag,.hljs-template-variable,.hljs-type,.hljs-variable.language_{color:#d73a49}.hljs-title,.hljs-title.class_,.hljs-title.class_.inherited__,.hljs-title.function_{color:#6f42c1}.hljs-attr,.hljs-attribute,.hljs-literal,.hljs-meta,.hljs-number,.hljs-operator,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id,.hljs-variable{color:#005cc5}.hljs-meta .hljs-string,.hljs-regexp,.hljs-string{color:#032f62}.hljs-built_in,.hljs-symbol{color:#e36209}.hljs-code,.hljs-comment,.hljs-formula{color:#6a737d}.hljs-name,.hljs-quote,.hljs-selector-pseudo,.hljs-selector-tag{color:#22863a}.hljs-subst{color:#24292e}.hljs-section{font-weight:700;color:#005cc5}.hljs-bullet{color:#735c0f}.hljs-emphasis{font-style:italic;color:#24292e}.hljs-strong{font-weight:700;color:#24292e}.hljs-addition{color:#22863a;background-color:#f0fff4}.hljs-deletion{color:#b31d28;background-color:#ffeef0}[data-doc-theme=dark] .hljs,[data-vc-theme=dark] .hljs{color:#c9d1d9;background:#0d1117}[data-doc-theme=dark] .hljs-doctag,[data-doc-theme=dark] .hljs-keyword,[data-doc-theme=dark] .hljs-meta .hljs-keyword,[data-doc-theme=dark] .hljs-template-tag,[data-doc-theme=dark] .hljs-template-variable,[data-doc-theme=dark] .hljs-type,[data-doc-theme=dark] .hljs-variable.language_,[data-vc-theme=dark] .hljs-doctag,[data-vc-theme=dark] .hljs-keyword,[data-vc-theme=dark] .hljs-meta .hljs-keyword,[data-vc-theme=dark] .hljs-template-tag,[data-vc-theme=dark] .hljs-template-variable,[data-vc-theme=dark] .hljs-type,[data-vc-theme=dark] .hljs-variable.language_{color:#ff7b72}[data-doc-theme=dark] .hljs-title,[data-doc-theme=dark] .hljs-title.class_,[data-doc-theme=dark] .hljs-title.function_,[data-vc-theme=dark] .hljs-title,[data-vc-theme=dark] .hljs-title.class_,[data-vc-theme=dark] .hljs-title.function_{color:#d2a8ff}[data-doc-theme=dark] .hljs-attr,[data-doc-theme=dark] .hljs-literal,[data-doc-theme=dark] .hljs-number,[data-doc-theme=dark] .hljs-variable,[data-vc-theme=dark] .hljs-attr,[data-vc-theme=dark] .hljs-literal,[data-vc-theme=dark] .hljs-number,[data-vc-theme=dark] .hljs-variable{color:#79c0ff}[data-doc-theme=dark] .hljs-regexp,[data-doc-theme=dark] .hljs-string,[data-vc-theme=dark] .hljs-regexp,[data-vc-theme=dark] .hljs-string{color:#a5d6ff}[data-doc-theme=dark] .hljs-code,[data-doc-theme=dark] .hljs-comment,[data-vc-theme=dark] .hljs-code,[data-vc-theme=dark] .hljs-comment{color:#8b949e}[data-doc-theme=dark] .hljs-name,[data-doc-theme=dark] .hljs-selector-tag,[data-vc-theme=dark] .hljs-name,[data-vc-theme=dark] .hljs-selector-tag{color:#7ee787}";
+var github_default = "pre code.hljs{display:block;padding:1em}code.hljs{padding:3px 5px}.hljs{color:#24292e;background:#fff}.hljs-doctag,.hljs-keyword,.hljs-meta .hljs-keyword,.hljs-template-tag,.hljs-template-variable,.hljs-type,.hljs-variable.language_{color:#d73a49}.hljs-title,.hljs-title.class_,.hljs-title.class_.inherited__,.hljs-title.function_{color:#6f42c1}.hljs-attr,.hljs-attribute,.hljs-literal,.hljs-meta,.hljs-number,.hljs-operator,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id,.hljs-variable{color:#005cc5}.hljs-meta .hljs-string,.hljs-regexp,.hljs-string{color:#032f62}.hljs-built_in,.hljs-symbol{color:#e36209}.hljs-code,.hljs-comment,.hljs-formula{color:#6a737d}.hljs-name,.hljs-quote,.hljs-selector-pseudo,.hljs-selector-tag{color:#22863a}.hljs-subst{color:#24292e}.hljs-section{font-weight:700;color:#005cc5}.hljs-bullet{color:#735c0f}.hljs-emphasis{font-style:italic;color:#24292e}.hljs-strong{font-weight:700;color:#24292e}.hljs-addition{color:#22863a;background-color:#f0fff4}.hljs-deletion{color:#b31d28;background-color:#ffeef0}@media screen{[data-doc-theme=dark] .hljs,[data-vc-theme=dark] .hljs{color:#c9d1d9;background:#0d1117}[data-doc-theme=dark] .hljs-doctag,[data-doc-theme=dark] .hljs-keyword,[data-doc-theme=dark] .hljs-meta .hljs-keyword,[data-doc-theme=dark] .hljs-template-tag,[data-doc-theme=dark] .hljs-template-variable,[data-doc-theme=dark] .hljs-type,[data-doc-theme=dark] .hljs-variable.language_,[data-vc-theme=dark] .hljs-doctag,[data-vc-theme=dark] .hljs-keyword,[data-vc-theme=dark] .hljs-meta .hljs-keyword,[data-vc-theme=dark] .hljs-template-tag,[data-vc-theme=dark] .hljs-template-variable,[data-vc-theme=dark] .hljs-type,[data-vc-theme=dark] .hljs-variable.language_{color:#ff7b72}[data-doc-theme=dark] .hljs-title,[data-doc-theme=dark] .hljs-title.class_,[data-doc-theme=dark] .hljs-title.function_,[data-vc-theme=dark] .hljs-title,[data-vc-theme=dark] .hljs-title.class_,[data-vc-theme=dark] .hljs-title.function_{color:#d2a8ff}[data-doc-theme=dark] .hljs-attr,[data-doc-theme=dark] .hljs-literal,[data-doc-theme=dark] .hljs-number,[data-doc-theme=dark] .hljs-variable,[data-vc-theme=dark] .hljs-attr,[data-vc-theme=dark] .hljs-literal,[data-vc-theme=dark] .hljs-number,[data-vc-theme=dark] .hljs-variable{color:#79c0ff}[data-doc-theme=dark] .hljs-regexp,[data-doc-theme=dark] .hljs-string,[data-vc-theme=dark] .hljs-regexp,[data-vc-theme=dark] .hljs-string{color:#a5d6ff}[data-doc-theme=dark] .hljs-code,[data-doc-theme=dark] .hljs-comment,[data-vc-theme=dark] .hljs-code,[data-vc-theme=dark] .hljs-comment{color:#8b949e}[data-doc-theme=dark] .hljs-name,[data-doc-theme=dark] .hljs-selector-tag,[data-vc-theme=dark] .hljs-name,[data-vc-theme=dark] .hljs-selector-tag{color:#7ee787}}";
 //#endregion
 //#region packages/playground/src/core/code-preview/code-preview.scss?inline
-var code_preview_default$1 = ".docs-code-preview{position:relative;display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;min-height:0;overflow:hidden;background:var(--docs-background-color-soft,var(--vc-background-color,#f7f8fa));border-radius:8px}.docs-code-preview__language{z-index:1;min-width:28px;padding:0 8px;font-size:12px;line-height:18px;white-space:nowrap;-webkit-box-sizing:border-box;box-sizing:border-box;-webkit-transition:opacity .15s;transition:opacity .15s}.docs-code-preview__copy,.docs-code-preview__language{position:absolute;top:6px;right:12px;display:-webkit-inline-box;display:-webkit-inline-flex;display:-ms-inline-flexbox;display:inline-flex;height:28px;color:var(--docs-foreground-color-mute,var(--vc-color-dark-extralight,#71717a));-webkit-box-pack:center;-webkit-justify-content:center;-ms-flex-pack:center;justify-content:center;-webkit-box-align:center;-webkit-align-items:center;-ms-flex-align:center;align-items:center}.docs-code-preview__copy{z-index:2;width:28px;padding:0;pointer-events:none;cursor:pointer;background:var(--docs-background-color-soft,var(--vc-background-color,#f7f8fa));border:1px solid var(--docs-border-color,var(--vc-color-light-deeper,#d4d4d8));border-radius:8px;opacity:0;-webkit-transition:opacity .15s,background-color .15s;transition:opacity .15s,background-color .15s}.docs-code-preview__copy:hover{background:var(--docs-background-color,var(--vc-background-color-light,#fff))}.docs-code-preview__copy:focus-visible{pointer-events:auto;opacity:1}.docs-code-preview:has(.docs-code-preview__copy:focus-visible) .docs-code-preview__language,.docs-code-preview:hover .docs-code-preview__language{opacity:0}.docs-code-preview:has(.docs-code-preview__copy:focus-visible) .docs-code-preview__copy,.docs-code-preview:hover .docs-code-preview__copy{pointer-events:auto;opacity:1}.docs-code-preview__scroller{width:100%;height:100%;min-width:0;min-height:0;-webkit-box-flex:1;-webkit-flex:1 1 auto;-ms-flex:1 1 auto;flex:1 1 auto}.docs-code-preview__code{width:-webkit-max-content;width:-moz-max-content;width:max-content;margin:0}.docs-code-preview__code,.docs-code-preview__code code.hljs{min-width:100%;min-height:100%;overflow:visible;background:var(--docs-background-color-soft,var(--vc-background-color,#f7f8fa))}.docs-code-preview__code code.hljs{display:block;padding:12px 96px 12px 24px;-webkit-box-sizing:border-box;box-sizing:border-box}";
+var code_preview_default$1 = ".docs-code-preview{position:relative;display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;min-height:0;overflow:hidden;background:var(--docs-background-color-soft,var(--vc-background-color,#f7f8fa));border-radius:8px}.docs-code-preview__language{z-index:1;min-width:28px;padding:0 8px;font-size:12px;line-height:18px;white-space:nowrap;-webkit-box-sizing:border-box;box-sizing:border-box;-webkit-transition:opacity .15s;transition:opacity .15s}.docs-code-preview__copy,.docs-code-preview__language{position:absolute;top:6px;right:12px;display:-webkit-inline-box;display:-webkit-inline-flex;display:-ms-inline-flexbox;display:inline-flex;height:28px;color:var(--docs-foreground-color-mute,var(--vc-color-dark-extralight,#71717a));-webkit-box-pack:center;-webkit-justify-content:center;-ms-flex-pack:center;justify-content:center;-webkit-box-align:center;-webkit-align-items:center;-ms-flex-align:center;align-items:center}.docs-code-preview__copy{z-index:2;width:28px;padding:0;pointer-events:none;cursor:pointer;background:var(--docs-background-color-soft,var(--vc-background-color,#f7f8fa));border:1px solid var(--docs-border-color,var(--vc-border-color,#d4d4d8));border-radius:8px;opacity:0;-webkit-transition:opacity .15s,background-color .15s;transition:opacity .15s,background-color .15s}.docs-code-preview__copy:hover{background:var(--docs-background-color,var(--vc-background-color-lightest,#fff))}.docs-code-preview__copy:focus-visible{pointer-events:auto;opacity:1}.docs-code-preview:has(.docs-code-preview__copy:focus-visible) .docs-code-preview__language,.docs-code-preview:hover .docs-code-preview__language{opacity:0}.docs-code-preview:has(.docs-code-preview__copy:focus-visible) .docs-code-preview__copy,.docs-code-preview:hover .docs-code-preview__copy{pointer-events:auto;opacity:1}.docs-code-preview__scroller{width:100%;height:100%;min-width:0;min-height:0;-webkit-box-flex:1;-webkit-flex:1 1 auto;-ms-flex:1 1 auto;flex:1 1 auto}.docs-code-preview__code{width:-webkit-max-content;width:-moz-max-content;width:max-content;margin:0}.docs-code-preview__code,.docs-code-preview__code code.hljs{min-width:100%;min-height:100%;overflow:visible;background:var(--docs-background-color-soft,var(--vc-background-color,#f7f8fa))}.docs-code-preview__code code.hljs{display:block;padding:12px 96px 12px 24px;-webkit-box-sizing:border-box;box-sizing:border-box}";
 //#endregion
 //#region packages/playground/src/core/code-preview/style.ts
 var CODE_PREVIEW_STYLE_ID = "docs-code-preview-style";
@@ -2201,9 +2201,9 @@ var escapeHtmlAttr = (value) => value.replace(/&/gu, "&").replace(/"/gu, "&q
 /**
 * runtime 画布色。`previewInset` 露出的 padding、iframe chrome 和 sandbox
 * `html`/`body` 必须共用这一变量，暗色下 `--docs-background-color` 与
-* `--vc-background-color-light` 不同，否则会出现色带割裂。
+* `--vc-background-color-lightest` 不同，否则会出现色带割裂。
 */
-var PLAYGROUND_RUNTIME_CANVAS_BACKGROUND = "var(--vc-background-color-light, var(--docs-background-color, #fff))";
+var PLAYGROUND_RUNTIME_CANVAS_BACKGROUND = "var(--vc-background-color-lightest, var(--docs-background-color, #fff))";
 var createRuntimePreviewOptions = (cdnURL = require_css.DEFAULT_CDN_URL, options = {}) => {
 	const previewScroller = options.previewScroller === true;
 	const hrefs = Object.values({
@@ -2233,22 +2233,30 @@ var createRuntimePreviewOptions = (cdnURL = require_css.DEFAULT_CDN_URL, options
 		}
 	};
 };
-var toReplFilename = (filename) => filename.startsWith("src/") ? filename : `src/${filename}`;
+var toReplFilename = (filename) => filename === "import-map.json" || filename.startsWith("src/") ? filename : `src/${filename}`;
 var createReplFile = (filename, code) => {
 	const replFilename = toReplFilename(filename);
 	return new _vue_repl.File(replFilename, code);
 };
 /**
-* 默认 CDN → 站点 modules → 实例 builtinImportMap → 管理页覆盖。
+* 保留显式配置的模块，供 local 区分宿主默认与 URL 覆盖。
+* @param builtinImportMap 实例层 import map。
+* @returns 按优先级合并的显式模块地址。
+*/
+var createRuntimeImportOverrides = (builtinImportMap) => ({
+	...getPlaygroundSiteModules(),
+	...getPlaygroundImportMapOverrides(),
+	...filterSafeHrefs(builtinImportMap?.imports)
+});
+/**
+* 默认 CDN → 站点 modules → 管理页覆盖 → 实例 builtinImportMap。
 * iframe import map 与直接渲染加载的是同一份地址表。
 * @param cdnURL
 * @param builtinImportMap
 */
 var createRuntimeImports = (cdnURL = require_css.DEFAULT_CDN_URL, builtinImportMap) => ({
 	...require_css.createBuiltinImports(cdnURL),
-	...getPlaygroundSiteModules(),
-	...filterSafeHrefs(builtinImportMap?.imports),
-	...getPlaygroundImportMapOverrides()
+	...createRuntimeImportOverrides(builtinImportMap)
 });
 var createRuntimeStore = (files, entry, options) => {
 	const { cdnURL, builtinImportMap, ...storeOptions } = options;
@@ -2256,6 +2264,7 @@ var createRuntimeStore = (files, entry, options) => {
 		const file = createReplFile(filename, code);
 		return [file.filename, file];
 	})));
+	replFiles.value["import-map.json"] ??= new _vue_repl.File("import-map.json", "{}");
 	const mainFile = (0, vue.ref)(toReplFilename(entry));
 	const activeFilename = (0, vue.ref)(toReplFilename(entry));
 	const imports = createRuntimeImports(cdnURL, builtinImportMap);
@@ -2274,6 +2283,11 @@ var createRuntimeStore = (files, entry, options) => {
 		})
 	});
 	require_css.bindPlaygroundScss(store);
+	const setFiles = store.setFiles.bind(store);
+	store.setFiles = (nextFiles, nextEntry) => setFiles({
+		"import-map.json": store.files["import-map.json"].code,
+		...nextFiles
+	}, nextEntry);
 	bindReplModules(store);
 	require_css.whenSassReady(files, () => {
 		const specifiers = require_css.collectBareSpecifiers(files, Object.keys(files));
@@ -2525,7 +2539,7 @@ var Alone = new _deot_vc.Portal(wrapper_default, {
 /**
 * 直接渲染与页面同文档，弹层不需要临时撑高。
 * `run` 仍返回可调用函数，但不会申请高度，也不会改动预览尺寸。
-* @param vue 宿主 Vue，只用其中的 `isRef`。
+* @param vue 当前预览的 Vue，只用其中的 `isRef`。
 * @returns 注入给预览的 `docs:playground`。
 */
 var createLocalPlayground = (vue) => {
@@ -2776,6 +2790,15 @@ var resolveHostModule = (id, modules) => {
 	return null;
 };
 var HOST_VUE_SPECIFIERS = /* @__PURE__ */ new Set(["vue", "vue/server-renderer"]);
+var VUE_DEPENDENT_BUILTINS = /* @__PURE__ */ new Set([
+	"vue/server-renderer",
+	"vue-router",
+	"pinia",
+	"@deot/vc",
+	"@deot/vc-components",
+	"@deot/vc-hooks",
+	"@deot/vc-locale"
+]);
 var messageOf = (error) => error instanceof Error ? error.message : String(error);
 /**
 * 找到 import map 里能覆盖该说明符的键。子路径没有独立 URL 时回退到父包。
@@ -2794,24 +2817,23 @@ var resolveImportTarget = (id, imports) => {
 		cursor = parent;
 	}
 };
-var prefersLocalBuiltin = (id, imports, cdnURL) => {
+var prefersLocalBuiltin = (id, imports, overrides = new Set(Object.keys(imports))) => {
 	if (!localBuiltinIds.has(id) && !HOST_VUE_SPECIFIERS.has(id)) return false;
-	const url = imports[id];
-	if (!url) return true;
-	return url === require_css.createBuiltinImports(cdnURL)[id];
+	if (overrides.has(id)) return false;
+	return !VUE_DEPENDENT_BUILTINS.has(id) || !overrides.has("vue");
 };
 /**
-* 内置依赖先注入宿主副本。import map 里与默认 CDN 不同的地址会覆盖，包括 `vue`。
+* 内置依赖默认注入宿主副本，显式 URL 按模块覆盖，包括与默认 CDN 相同的地址。
 * @param specifiers 本次预览用到的裸模块说明符。
 * @param imports 合并后的 import map。
 * @param builtins 宿主 Vue 与 vue-router。
 * @param builtins.vue 当前页面的 Vue 模块。
 * @param builtins.vueRouter 打包进来的 vue-router，可被 import map 覆盖。
 * @param loader 按 URL 加载远程模块。
-* @param cdnURL 当前 CDN 根，用来识别默认地址。
+* @param overrides 显式配置的模块名，与自动补齐的默认地址区分。
 * @returns 模块表和加载错误。
 */
-var loadLocalModules = async (specifiers, imports, builtins, loader, cdnURL) => {
+var loadLocalModules = async (specifiers, imports, builtins, loader, overrides = new Set(Object.keys(imports))) => {
 	const modules = {
 		"vue": builtins.vue,
 		"vue-router": builtins.vueRouter
@@ -2821,14 +2843,14 @@ var loadLocalModules = async (specifiers, imports, builtins, loader, cdnURL) =>
 	const localIds = /* @__PURE__ */ new Set();
 	specifiers.forEach((specifier) => {
 		let local = false;
-		if (prefersLocalBuiltin(specifier, imports, cdnURL)) localIds.add(specifier);
+		if (prefersLocalBuiltin(specifier, imports, overrides)) localIds.add(specifier);
 		else {
 			let cursor = specifier;
 			while (true) {
 				const slash = cursor.lastIndexOf("/");
 				if (slash <= 0) break;
 				const parent = cursor.slice(0, slash);
-				if (prefersLocalBuiltin(parent, imports, cdnURL)) {
+				if (prefersLocalBuiltin(parent, imports, overrides)) {
 					localIds.add(parent);
 					local = true;
 					break;
@@ -2836,12 +2858,8 @@ var loadLocalModules = async (specifiers, imports, builtins, loader, cdnURL) =>
 				cursor = parent;
 			}
 		}
-		if (specifier === "vue-router") {
-			if (imports["vue-router"]) targets.add("vue-router");
-			return;
-		}
 		const target = resolveImportTarget(specifier, imports);
-		if (target && prefersLocalBuiltin(target, imports, cdnURL)) localIds.add(target);
+		if (target && prefersLocalBuiltin(target, imports, overrides)) localIds.add(target);
 		else if (target) targets.add(target);
 		else if (!local && !localIds.has(specifier)) {
 			imports[specifier] = require_css.resolveNpmImport(specifier);
@@ -2858,7 +2876,7 @@ var loadLocalModules = async (specifiers, imports, builtins, loader, cdnURL) =>
 	}));
 	for (const id of targets) {
 		const url = imports[id];
-		if (!url || prefersLocalBuiltin(id, imports, cdnURL)) continue;
+		if (!url || prefersLocalBuiltin(id, imports, overrides)) continue;
 		try {
 			modules[id] = await loader(url);
 		} catch (error) {
@@ -2873,12 +2891,13 @@ var loadLocalModules = async (specifiers, imports, builtins, loader, cdnURL) =>
 //#endregion
 //#region packages/playground/src/core/runtime/local/vue-guard.ts
 /**
-* 给 files 注入的 vue：同一份宿主 Vue，但 `createApp().mount` 不会卸掉页面。
+* 给 files 注入选定的 Vue，但 `createApp().mount` 不会卸掉页面。
 * 防护按本次 link 创建，多个 Playground 互不覆盖。
 * @param capture 本次链接收集到的根组件、局部组件和 provide。
+* @param vue 当前预览选定的 Vue。
 * @returns 带防护的 Vue 模块。
 */
-var createGuardedVue = (capture) => {
+var createGuardedVue = (capture, vue$4 = vue) => {
 	const createApp = (rootComponent, rootProps) => {
 		const fakeApp = {
 			_component: rootComponent,
@@ -2918,14 +2937,14 @@ var createGuardedVue = (capture) => {
 			mount() {
 				capture.components = { ...fakeApp._context.components };
 				capture.provides = { ...fakeApp._context.provides };
-				capture.mountedComponent = (0, vue.defineComponent)({
+				capture.mountedComponent = vue$4.defineComponent({
 					name: "PlaygroundCapturedApp",
 					components: fakeApp._context.components,
 					setup() {
 						Reflect.ownKeys(fakeApp._context.provides).forEach((key) => {
-							(0, vue.provide)(key, fakeApp._context.provides[key]);
+							vue$4.provide(key, fakeApp._context.provides[key]);
 						});
-						return () => (0, vue.h)(rootComponent, rootProps || null);
+						return () => vue$4.h(rootComponent, rootProps || null);
 					}
 				});
 				return capture.mountedComponent;
@@ -2937,7 +2956,7 @@ var createGuardedVue = (capture) => {
 		};
 		return fakeApp;
 	};
-	return new Proxy(vue, { get(target, prop, receiver) {
+	return new Proxy(vue$4, { get(target, prop, receiver) {
 		if (prop === "createApp" || prop === "createSSRApp") return createApp;
 		if (prop === "default") return receiver;
 		return Reflect.get(target, prop, receiver);
@@ -2947,7 +2966,7 @@ var createGuardedVue = (capture) => {
 //#region packages/playground/src/core/runtime/local/linker.ts
 /**
 * 在当前页面链接编译结果，返回入口组件。
-* 未覆盖 `vue` 时换成带防护的宿主实例，避免 `mount` 卸掉页面。
+* 给选定的 Vue 加上 mount 防护，避免字符串入口卸掉页面。
 * @param compiled 浏览器编译结果。
 * @param files 当前 Playground 文件表。
 * @param options 可选的宿主模块表。
@@ -2966,7 +2985,7 @@ var linkPlayground = (compiled, files, options = {}) => {
 		provides: {}
 	};
 	const modules = { ...options.modules || {} };
-	if (modules.vue == null || modules.vue === vue) modules.vue = createGuardedVue(capture);
+	modules.vue = createGuardedVue(capture, modules.vue || vue);
 	const fileIndex = require_css.createFileIndex(files);
 	const root = require_css.getCommonRoot([...fileIndex.keys()]);
 	const cache = /* @__PURE__ */ new Map();
@@ -3034,16 +3053,54 @@ var linkPlayground = (compiled, files, options = {}) => {
 //#endregion
 //#region packages/playground/src/core/runtime/local/remote.ts
 var HOST_VUE = /* @__PURE__ */ new Set(["vue", "vue/server-renderer"]);
+var moduleUrl = (url) => new URL(url, globalThis.location?.href).href;
+var REMOTE_SOURCE_CACHE_LIMIT = 128;
+var sourceCache = /* @__PURE__ */ new Map();
+var prepareRemoteSource = async (url) => {
+	const response = await fetch(url);
+	if (!response.ok) throw new Error(`${response.status} ${url}`);
+	const text = await response.text();
+	await (0, es_module_lexer.init)();
+	const [specifiers] = (0, es_module_lexer.parse)(text);
+	let source = text;
+	for (const item of [...specifiers].reverse()) if (item.type === "dynamic") source = source.slice(0, item.importStart) + "__import" + source.slice(item.importStart + 6);
+	const cjs = (0, sucrase.transform)(require_css.rewriteImportMeta(source, url), {
+		transforms: ["imports"],
+		disableESTransforms: true,
+		production: true,
+		filePath: url
+	}).code;
+	return {
+		dependencies: specifiers.filter((item) => item.type === "static" || item.type === "reexport-star").map((item) => item.specifier),
+		run: new Function("require", "module", "exports", "__import", cjs)
+	};
+};
+var readRemoteSource = (url) => {
+	if (new URL(url).origin === globalThis.location?.origin) return prepareRemoteSource(url);
+	const cached = sourceCache.get(url);
+	if (cached) {
+		sourceCache.delete(url);
+		sourceCache.set(url, cached);
+		return cached;
+	}
+	const task = prepareRemoteSource(url).catch((error) => {
+		if (sourceCache.get(url) === task) sourceCache.delete(url);
+		throw error;
+	});
+	sourceCache.set(url, task);
+	if (sourceCache.size > REMOTE_SOURCE_CACHE_LIMIT) sourceCache.delete(sourceCache.keys().next().value);
+	return task;
+};
 /**
 * 把 CDN 上的 ESM 先拉完整张依赖图，再在当前页面里执行。
 * 裸导入优先走 import map，缺失的 npm 依赖回退到 CDN ESM；import() 按需加载。
 * @param imports 合并后的 import map。
 * @param builtins 宿主 Vue 与 vue-router。
-* @param cdnURL 当前 CDN 根，用来识别默认地址。
+* @param overrides 显式配置的模块名，与自动补齐的默认地址区分。
 * @param importModule 浏览器原生 ESM 加载器。
 * @returns 按 URL 加载并执行远程模块的加载器。
 */
-var createRemoteLoader = (imports, builtins, cdnURL, importModule = (url) => import(
+var createRemoteLoader = (imports, builtins, overrides = new Set(Object.keys(imports)), importModule = (url) => import(
 	/* @vite-ignore */
 	url
 )) => {
@@ -3052,9 +3109,9 @@ var createRemoteLoader = (imports, builtins, cdnURL, importModule = (url) => imp
 		"vue-router": builtins.vueRouter
 	};
 	const pendingBuiltins = /* @__PURE__ */ new Set();
-	const texts = /* @__PURE__ */ new Map();
+	const sources = /* @__PURE__ */ new Map();
+	const pendingSources = /* @__PURE__ */ new Map();
 	const evaluated = /* @__PURE__ */ new Map();
-	const crawled = /* @__PURE__ */ new Set();
 	const nativeModules = /* @__PURE__ */ new Map();
 	const loadNative = (url) => {
 		let pending = nativeModules.get(url);
@@ -3069,24 +3126,34 @@ var createRemoteLoader = (imports, builtins, cdnURL, importModule = (url) => imp
 		return pending;
 	};
 	const localBuiltinId = (id) => {
-		if (imports[id] && !prefersLocalBuiltin(id, imports, cdnURL)) return null;
-		if (prefersLocalBuiltin(id, imports, cdnURL)) return id;
+		if (imports[id] && !prefersLocalBuiltin(id, imports, overrides)) return null;
+		if (prefersLocalBuiltin(id, imports, overrides)) return id;
 		let cursor = id;
 		while (true) {
 			const slash = cursor.lastIndexOf("/");
 			if (slash <= 0) return null;
 			const parent = cursor.slice(0, slash);
-			if (prefersLocalBuiltin(parent, imports, cdnURL)) return parent;
+			if (prefersLocalBuiltin(parent, imports, overrides)) return parent;
 			cursor = parent;
 		}
 	};
-	const dependencyUrl = (from, specifier) => {
-		if (require_css.isRelativeSpecifier(specifier) || /^https?:\/\//.test(specifier)) return new URL(specifier, from).href;
-		if (imports[specifier] && !prefersLocalBuiltin(specifier, imports, cdnURL)) return imports[specifier];
-		if (HOST_VUE.has(specifier) && prefersLocalBuiltin(specifier, imports, cdnURL)) return null;
+	const dependencySpecifier = (from, specifier) => {
+		if (require_css.isRelativeSpecifier(specifier) || /^https?:\/\//.test(specifier)) {
+			const url = new URL(specifier, from);
+			const match = url.origin === "https://cdn.jsdelivr.net" ? url.pathname.match(/^\/npm\/((?:@[^/]+\/)?[^/@]+)(?:@[^/]+)?\/\+esm$/) : null;
+			if (match && (imports[match[1]] || localBuiltinIds.has(match[1]))) return match[1];
+			return url.href;
+		}
+		return specifier;
+	};
+	const dependencyUrl = (from, id) => {
+		const specifier = dependencySpecifier(from, id);
+		if (/^https?:\/\//.test(specifier)) return specifier;
+		if (imports[specifier] && !prefersLocalBuiltin(specifier, imports, overrides)) return moduleUrl(imports[specifier]);
+		if (HOST_VUE.has(specifier) && prefersLocalBuiltin(specifier, imports, overrides)) return null;
 		let cursor = specifier;
 		while (cursor) {
-			if (localBuiltinIds.has(cursor) && prefersLocalBuiltin(cursor, imports, cdnURL)) {
+			if (localBuiltinIds.has(cursor) && prefersLocalBuiltin(cursor, imports, overrides)) {
 				pendingBuiltins.add(cursor);
 				return null;
 			}
@@ -3099,37 +3166,36 @@ var createRemoteLoader = (imports, builtins, cdnURL, importModule = (url) => imp
 			imports[specifier] = require_css.resolveNpmImport(specifier);
 			return imports[specifier];
 		}
-		return imports[target];
+		return moduleUrl(imports[target]);
 	};
-	const crawl = async (url) => {
-		if (/\/\+esm(?:[?#]|$)/.test(url)) {
+	const crawl = async (url, visited = /* @__PURE__ */ new Set()) => {
+		if (!overrides.size && /\/\+esm(?:[?#]|$)/.test(url)) {
 			await loadNative(url);
 			return;
 		}
-		if (crawled.has(url)) return;
-		crawled.add(url);
-		const response = await fetch(url);
-		if (!response.ok) throw new Error(`${response.status} ${url}`);
-		const text = await response.text();
-		await (0, es_module_lexer.init)();
-		const [specifiers] = (0, es_module_lexer.parse)(text);
-		let source = text;
-		for (const item of [...specifiers].reverse()) if (item.type === "dynamic") source = source.slice(0, item.importStart) + "__import" + source.slice(item.importStart + 6);
-		texts.set(url, source);
-		await Promise.all(specifiers.map(async (item) => {
-			if (item.type !== "static" && item.type !== "reexport-star") return;
-			const next = dependencyUrl(url, item.specifier);
-			if (next) await crawl(next);
+		if (visited.has(url)) return;
+		visited.add(url);
+		let pending = pendingSources.get(url);
+		if (!pending) {
+			pending = readRemoteSource(url);
+			pendingSources.set(url, pending);
+		}
+		const source = await pending;
+		sources.set(url, source);
+		await Promise.all(source.dependencies.map(async (specifier) => {
+			const next = dependencyUrl(url, specifier);
+			if (next) await crawl(next, visited);
 		}));
 	};
-	const requireFrom = (from) => (id) => {
-		if (HOST_VUE.has(id) && prefersLocalBuiltin(id, imports, cdnURL)) return toHostModule(builtins.vue);
+	const requireFrom = (from) => (specifier) => {
+		const id = dependencySpecifier(from, specifier);
+		if (HOST_VUE.has(id) && prefersLocalBuiltin(id, imports, overrides)) return toHostModule(builtins.vue);
 		const builtinId = localBuiltinId(id);
 		if (builtinId) return toHostModule(hostModules[builtinId]);
-		if (require_css.isRelativeSpecifier(id) || /^https?:\/\//.test(id)) return evaluate(new URL(id, from).href);
+		if (require_css.isRelativeSpecifier(id) || /^https?:\/\//.test(id)) return evaluate(dependencyUrl(from, id));
 		const target = imports[id] ? id : resolveImportTarget(id, imports);
 		if (!target || !imports[target]) throw new Error(`[Playground] 未注册的模块 "${id}"`);
-		const loaded = evaluate(imports[target]);
+		const loaded = evaluate(moduleUrl(imports[target]));
 		if (target === id) return loaded;
 		if (!resolveHostModule(id, { [target]: loaded }))
  /* istanbul ignore next -- 父包没有对应导出时才拒绝 */
@@ -3138,21 +3204,16 @@ var createRemoteLoader = (imports, builtins, cdnURL, importModule = (url) => imp
 	};
 	const evaluate = (url) => {
 		if (evaluated.has(url)) return evaluated.get(url);
-		const text = texts.get(url);
-		if (text == null) throw new Error(`[Playground] 远程模块尚未下载: ${url}`);
-		const cjs = (0, sucrase.transform)(require_css.rewriteImportMeta(text, url), {
-			transforms: ["imports"],
-			disableESTransforms: true,
-			production: true,
-			filePath: url
-		}).code;
+		const source = sources.get(url);
+		if (!source) throw new Error(`[Playground] 远程模块尚未下载: ${url}`);
 		const module = { exports: {} };
 		evaluated.set(url, module.exports);
-		new Function("require", "module", "exports", "__import", cjs)(requireFrom(url), module, module.exports, async (id) => {
+		const runner = source.run;
+		runner(requireFrom(url), module, module.exports, async (id) => {
 			const next = dependencyUrl(url, id);
 			if (next) await load(next);
 			else {
-				const builtinId = localBuiltinId(id);
+				const builtinId = localBuiltinId(dependencySpecifier(url, id));
 				if (builtinId && !(builtinId in hostModules)) hostModules[builtinId] = await ensureLocalBuiltin(builtinId);
 			}
 			return requireFrom(url)(id);
@@ -3161,7 +3222,8 @@ var createRemoteLoader = (imports, builtins, cdnURL, importModule = (url) => imp
 		return module.exports;
 	};
 	const loading = /* @__PURE__ */ new Map();
-	const load = (url) => {
+	const load = (sourceUrl) => {
+		const url = moduleUrl(sourceUrl);
 		const pending = loading.get(url);
 		if (pending) return pending;
 		const task = (async () => {
@@ -3222,14 +3284,14 @@ var local_sandbox_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ (0
 			});
 		};
 		(0, vue.watch)([compileError, runtimeError], publishError);
-		const createDocsLink = (preview) => (0, vue.defineComponent)({
+		const createDocsLink = (preview, vue$2) => vue$2.defineComponent({
 			name: "DocsLink",
 			props: { to: {
 				type: String,
 				default: ""
 			} },
 			setup(linkProps, { slots }) {
-				return () => (0, vue.h)("a", {
+				return () => vue$2.h("a", {
 					href: linkProps.to,
 					style: {
 						color: "inherit",
@@ -3250,27 +3312,27 @@ var local_sandbox_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ (0
 			previewApp = null;
 			require_css.removeStyle(styleId);
 		};
-		const mountPreview = (component, preview, css) => {
+		const mountPreview = (job, preview) => {
 			if (!mountEl.value) return;
+			const { component, vue: vue$3, scroller, css } = job;
 			destroyPreview();
 			require_css.injectStyle(styleId, css);
 			if (props.clearConsole) console.clear();
-			const useScroller = props.previewScroller === true;
-			const app = vue.createApp({
+			const app = vue$3.createApp({
 				name: "LocalSandboxRoot",
 				setup() {
-					const service = createLocalPlayground(vue);
-					(0, vue.provide)("docs:playground", service);
-					(0, vue.onErrorCaptured)((error) => {
+					const service = createLocalPlayground(vue$3);
+					vue$3.provide("docs:playground", service);
+					vue$3.onErrorCaptured((error) => {
 						const message = formatPlaygroundRuntimeError(error);
 						if (message) runtimeError.value = message;
 						return false;
 					});
-					(0, vue.onBeforeUnmount)(() => service.dispose());
+					vue$3.onBeforeUnmount(() => service.dispose());
 					return () => {
-						const content = (0, vue.h)(component);
-						if (!useScroller) return content;
-						return (0, vue.h)(_deot_vc.Scroller, {
+						const content = vue$3.h(component);
+						if (!scroller) return content;
+						return vue$3.h(scroller, {
 							height: "100%",
 							native: false,
 							autoResize: true,
@@ -3280,7 +3342,7 @@ var local_sandbox_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ (0
 					};
 				}
 			});
-			app.component("DocsLink", createDocsLink(preview));
+			app.component("DocsLink", createDocsLink(preview, vue$3));
 			app.config.errorHandler = (error) => {
 				const message = formatPlaygroundRuntimeError(error);
 				if (message) runtimeError.value = message;
@@ -3311,7 +3373,7 @@ var local_sandbox_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ (0
 			/* istanbul ignore if -- 桥接 iframe 尚未就绪或编译已被取代 */
 			if (pendingMount !== job || !mountEl.value) return;
 			pendingMount = null;
-			mountPreview(job.component, preview, job.css);
+			mountPreview(job, preview);
 		};
 		const run = async () => {
 			const current = ++version;
@@ -3333,15 +3395,18 @@ var local_sandbox_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ (0
 					return;
 				}
 				const imports = createRuntimeImports(props.options.cdnURL, props.options.builtinImportMap);
+				const overrides = new Set(Object.keys(createRuntimeImportOverrides(props.options.builtinImportMap)));
 				const specifiers = require_css.collectBareSpecifiers(props.files, require_css.collectReachableFilenames(props.files, compiled.entry));
+				specifiers.push("vue");
+				if (props.previewScroller === true) specifiers.push("@deot/vc");
 				const remote = createRemoteLoader(imports, {
 					vue,
 					vueRouter: vue_router
-				}, props.options.cdnURL);
+				}, overrides);
 				const loaded = await loadLocalModules(specifiers, imports, {
 					vue,
 					vueRouter: vue_router
-				}, (url) => remote.load(url), props.options.cdnURL);
+				}, (url) => remote.load(url), overrides);
 				/* istanbul ignore if -- 并发编译时只保留最后一次 */
 				if (current !== version) return;
 				if (loaded.errors.length) {
@@ -3359,6 +3424,8 @@ var local_sandbox_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ (0
 				}
 				pendingMount = {
 					component: linked.component,
+					vue: loaded.modules.vue,
+					scroller: props.previewScroller === true ? loaded.modules["@deot/vc"].Scroller : void 0,
 					css: linked.css,
 					version: current
 				};