@deot/docs-markdown 1.0.10 → 1.1.1

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Fragment, computed, createApp, createBlock, createCommentVNode, createElementBlock, createElementVNode, createVNode, defineComponent, h, inject, nextTick, normalizeClass, normalizeStyle, onBeforeUnmount, openBlock, ref, renderList, shallowRef, toDisplayString, unref, watch, withCtx, withDirectives } from "vue";
+import { Fragment, computed, createApp, createBlock, createCommentVNode, createElementBlock, createElementVNode, defineComponent, h, inject, nextTick, normalizeClass, normalizeStyle, onBeforeUnmount, onMounted, openBlock, ref, renderList, shallowRef, toDisplayString, unref, watch, withDirectives } from "vue";
 import { provideLocale, useLocale } from "@deot/docs-locale";
 import Config from "markdown-it-chain";
 import anchor from "markdown-it-anchor";
@@ -6,30 +6,87 @@ import mdContainer from "markdown-it-container";
 import markdownIt from "markdown-it";
 import JSON5 from "json5";
 import { getScroller } from "@deot/helper-dom";
-import { Scroller } from "@deot/vc";
 //#region packages/markdown/src/markdown.ts
 var HTML_MD_SIGN = "md";
 var PLAYGROUND = "playground";
+var TABS = "tabs";
 var TIP = "tip";
 var WARNING = "warning";
+var CALLOUT_FILLED_RE = /(^|\s)filled(\s|$)/;
+var TAB_MARKDOWN_INFO_RE = /^markdown(?:\s+(.*))?$/i;
+var CALLOUT_INFO_ICON = [
+	"<svg width=\"22\" height=\"28\" viewBox=\"0 0 22 28\" fill=\"none\" aria-hidden=\"true\">",
+	"<circle class=\"docs-markdown-callout-icon__fill\" cx=\"11\" cy=\"14\" r=\"11\"></circle>",
+	"<circle class=\"docs-markdown-callout-icon__ring\" cx=\"11\" cy=\"14\" r=\"10.5\"></circle>",
+	"<path class=\"docs-markdown-callout-icon__mark\"",
+	" d=\"m12.5 19-1.011.337a1 1 0 0 1-1.253-1.3l1.528-4.074a1 1 0 0 0-1.253-1.3L9.5 13\"",
+	" stroke-width=\"1.5\" stroke-linecap=\"round\"></path>",
+	"<path class=\"docs-markdown-callout-icon__mark\" d=\"M12 9a.5.5 0 1 1-1 0 .5.5 0 0 1 1 0Z\" stroke-width=\"1.5\"></path>",
+	"</svg>"
+].join("");
+var CALLOUT_WARNING_ICON = [
+	"<svg width=\"22\" height=\"28\" viewBox=\"0 0 22 28\" fill=\"none\" aria-hidden=\"true\">",
+	"<circle class=\"docs-markdown-callout-icon__fill\" cx=\"11\" cy=\"14\" r=\"11\"></circle>",
+	"<circle class=\"docs-markdown-callout-icon__ring\" cx=\"11\" cy=\"14\" r=\"10.5\"></circle>",
+	"<path class=\"docs-markdown-callout-icon__mark\" d=\"M11 10v5.5\" stroke-width=\"1.5\" stroke-linecap=\"round\"></path>",
+	"<path class=\"docs-markdown-callout-icon__mark\" d=\"M11.5 18.5a.5.5 0 1 1-1 0 .5.5 0 0 1 1 0Z\" stroke-width=\"1.5\"></path>",
+	"</svg>"
+].join("");
+var renderCallout = (name, icon) => (tokens, idx) => {
+	if (tokens[idx].nesting === 1) return [
+		`<div class="${CALLOUT_FILLED_RE.test(tokens[idx].info) ? `${name} ${name}--filled` : name}" md>`,
+		"<span class=\"docs-markdown-callout-icon\" aria-hidden=\"true\">",
+		icon,
+		"</span><div class=\"docs-markdown-callout-body\">\n"
+	].join("");
+	return "</div></div>\n";
+};
 var config = new Config();
 config.options.html(true).typographer(true).linkify(true).end().plugin("anchor").use(anchor, [{ permalink: anchor.permalink.linkInsideHeader({
 	placement: "before",
 	symbol: "#"
 }) }]).end().plugin("container").use(($md) => {
-	const reg = new RegExp(`^${PLAYGROUND}\\s*(.*)$`);
+	const playgroundReg = new RegExp(`^${PLAYGROUND}\\s*(.*)$`);
 	$md.use(mdContainer, PLAYGROUND, { validate(params) {
-		return params.trim().match(reg);
+		return params.trim().match(playgroundReg);
+	} });
+	const tabsReg = new RegExp(`^${TABS}\\s*$`);
+	$md.use(mdContainer, TABS, { validate(params) {
+		return tabsReg.test(params.trim());
 	} });
-	$md.use(mdContainer, TIP);
-	$md.use(mdContainer, WARNING);
+	$md.use(mdContainer, TIP, { render: renderCallout(TIP, CALLOUT_INFO_ICON) });
+	$md.use(mdContainer, WARNING, { render: renderCallout(WARNING, CALLOUT_WARNING_ICON) });
 }).end();
 var md = config.toMd(markdownIt);
 var playgroundOpen = `container_${PLAYGROUND}_open`;
 var playgroundClose = `container_${PLAYGROUND}_close`;
+var tabsOpen = `container_${TABS}_open`;
+var tabsClose = `container_${TABS}_close`;
 var htmlCommentRE = /<!--([\s\S]*?)-->/g;
 var runtimeConfigRE = /<config\s+lang\s*=\s*["']json5["']\s*>([\s\S]*?)<\/config>/i;
 var renderPlaygroundError = (message) => `<div class="docs-playground-error">PLAYGROUND: ${md.utils.escapeHtml(message)}</div>\n`;
+var renderTabsError = (message) => `<div class="docs-markdown-tabs-error">TABS: ${md.utils.escapeHtml(message)}</div>\n`;
+/**
+* 从 fence info 解析 Tab 显示名：去掉可选的 `markdown` 语言前缀。
+* @param info fence 的 info 字符串，如 `markdown Linux` 或 `Android`。
+* @returns 显示标题（可能为空）。
+*/
+var parseTabFenceTitle = (info) => {
+	const trimmed = info.trim();
+	const match = trimmed.match(TAB_MARKDOWN_INFO_RE);
+	if (match) return (match[1] || "").trim();
+	return trimmed;
+};
+/**
+* 生成 `?tab=` 使用的 id：小写、空白变 `-`；含非 ASCII 时与标题锚点一致做 encodeURIComponent。
+* @param title Tab 显示名。
+* @returns 可写入 query 的 id；标题为空时返回空串。
+*/
+var toMarkdownTabId = (title) => {
+	const normalized = title.trim().toLowerCase().replace(/\s+/gu, "-");
+	if (!normalized) return "";
+	return /[^\x20-\x7E]/u.test(normalized) ? encodeURIComponent(normalized) : normalized;
+};
 var PLAYGROUND_VIEWS = ["runtime", "files"];
 var isPlaygroundView = (value) => typeof value === "string" && PLAYGROUND_VIEWS.includes(value);
 var isRuntimeViewport = (viewport) => {
@@ -69,12 +126,22 @@ var validatePreviewInset = (propsData) => {
 	if (Array.isArray(inset) && inset.length === 2 && inset.every(isPreviewInsetValue)) return "";
 	return "previewInset 必须是非负数或 [垂直,水平] 非负数数组";
 };
-var validateExpand = (propsData) => {
-	if (!("expand" in propsData)) return "";
-	const expand = propsData.expand;
-	if (expand === true) return "";
-	if (typeof expand === "number" && Number.isFinite(expand) && expand > 0) return "";
-	return "expand 必须是 true 或正数";
+var validateExpandable = (propsData) => {
+	if (!("expandable" in propsData)) return "";
+	const expandable = propsData.expandable;
+	if (expandable === true) return "";
+	if (typeof expandable === "number" && Number.isFinite(expandable) && expandable > 0) return "";
+	return "expandable 必须是 true 或正数";
+};
+var validateTitle = (propsData) => {
+	if (!("title" in propsData)) return "";
+	if (typeof propsData.title === "string") return "";
+	return "title 必须是字符串";
+};
+var validateTitleId = (propsData) => {
+	if (!("id" in propsData)) return "";
+	if (typeof propsData.id === "string") return "";
+	return "id 必须是字符串";
 };
 var parseRuntimeProps = (tokens) => {
 	for (const token of tokens) {
@@ -97,7 +164,61 @@ var parseRuntimeProps = (tokens) => {
 	return {};
 };
 var renderPlaygroundAttrs = (propsData) => `data-props="${md.utils.escapeHtml(JSON.stringify(propsData))}"`;
-md.core.ruler.after("block", "runtime-files", (state) => {
+var renderTabsHtml = (panels) => {
+	const parts = ["<div class=\"docs-markdown-tabs\" md data-tabs>", "<div class=\"docs-markdown-tabs__nav\" data-tabs-nav></div>"];
+	panels.forEach((panel, index) => {
+		const hidden = index === 0 ? "" : " hidden";
+		const id = md.utils.escapeHtml(panel.id);
+		const title = md.utils.escapeHtml(panel.title);
+		parts.push(`<div class="docs-markdown-tabs__panel" role="tabpanel" data-tab="${id}" data-tab-title="${title}"${hidden}>`, md.render(panel.content), "</div>");
+	});
+	parts.push("</div>\n");
+	return parts.join("");
+};
+md.core.ruler.after("block", "markdown-tabs", (state) => {
+	const panelSources = Array.isArray(state.env?.tabsPanelSources) ? state.env.tabsPanelSources : void 0;
+	for (let index = 0; index < state.tokens.length; index++) {
+		if (state.tokens[index].type !== tabsOpen) continue;
+		let depth = 1;
+		let closeIndex = index + 1;
+		for (; closeIndex < state.tokens.length; closeIndex++) {
+			if (state.tokens[closeIndex].type === tabsOpen) depth++;
+			if (state.tokens[closeIndex].type === tabsClose) depth--;
+			if (depth === 0) break;
+		}
+		const fences = state.tokens.slice(index + 1, closeIndex).filter((token) => token.type === "fence");
+		const placeholder = new state.Token("html_block", "", 0);
+		placeholder.block = true;
+		if (!fences.length) placeholder.content = renderTabsError("至少需要声明一个分栏");
+		else {
+			const panels = [];
+			const seen = /* @__PURE__ */ new Set();
+			let error = "";
+			for (const fence of fences) {
+				const title = parseTabFenceTitle(fence.info);
+				const id = toMarkdownTabId(title);
+				if (!title || !id) {
+					error = "每个分栏都必须声明标题";
+					break;
+				}
+				if (seen.has(id)) {
+					error = `分栏 ${title} 的 id 重复`;
+					break;
+				}
+				seen.add(id);
+				panels.push({
+					id,
+					title,
+					content: fence.content
+				});
+				panelSources?.push(fence.content);
+			}
+			placeholder.content = error ? renderTabsError(error) : renderTabsHtml(panels);
+		}
+		state.tokens.splice(index, closeIndex - index + 1, placeholder);
+	}
+});
+md.core.ruler.after("markdown-tabs", "runtime-files", (state) => {
 	for (let index = 0; index < state.tokens.length; index++) {
 		if (state.tokens[index].type !== playgroundOpen) continue;
 		let depth = 1;
@@ -112,7 +233,7 @@ md.core.ruler.after("block", "runtime-files", (state) => {
 		const placeholder = new state.Token("html_block", "", 0);
 		placeholder.block = true;
 		const propsData = parseRuntimeProps(innerTokens);
-		const propsError = validateRuntimeViews(propsData) || validateRuntimeViewport(propsData) || validatePreviewInset(propsData) || validateExpand(propsData);
+		const propsError = validateRuntimeViews(propsData) || validateRuntimeViewport(propsData) || validatePreviewInset(propsData) || validateExpandable(propsData) || validateTitle(propsData) || validateTitleId(propsData);
 		const propsAttr = renderPlaygroundAttrs(propsData);
 		if (!fences.length) placeholder.content = renderPlaygroundError("至少需要声明一个代码文件");
 		else if (propsError) placeholder.content = renderPlaygroundError(propsError);
@@ -150,7 +271,7 @@ md.core.ruler.after("block", "runtime-files", (state) => {
 });
 var renderAttrs = md.renderer.renderAttrs;
 md.renderer.renderAttrs = (token) => {
-	const reg = new RegExp(`container_${PLAYGROUND}|fence|text`);
+	const reg = new RegExp(`container_${PLAYGROUND}|container_${TABS}|fence|text`);
 	if (token.nesting !== -1 && token.type && !reg.test(token.type)) token.attrPush([HTML_MD_SIGN, ""]);
 	return renderAttrs(token);
 };
@@ -178,32 +299,39 @@ var getInlineSearchText = (token) => {
 * @returns 文档标题、正文和按标题划分的小节。
 */
 var parseMarkdownSearchSections = (content) => {
-	const tokens = md.parse(content, {});
 	const sections = [];
 	const documentParts = [];
 	let activeSection;
-	for (let index = 0; index < tokens.length; index++) {
-		const token = tokens[index];
-		if (token.type === "heading_open") {
-			const inline = tokens[index + 1];
-			if (inline?.type !== "inline") continue;
-			const title = getInlineSearchText(inline);
-			if (!title) continue;
-			activeSection = {
-				title,
-				anchor: token.attrGet("id") || "",
-				level: Number(token.tag.slice(1)) || 1,
-				text: ""
-			};
-			sections.push(activeSection);
-			continue;
-		}
-		if (token.type !== "inline" || tokens[index - 1]?.type === "heading_open") continue;
-		const text = getInlineSearchText(token);
-		if (!text) continue;
+	const consumeInline = (text) => {
+		if (!text) return;
 		documentParts.push(text);
 		if (activeSection) activeSection.text = normalizeSearchText(`${activeSection.text} ${text}`);
-	}
+	};
+	const walk = (source, withHeadings) => {
+		const tabsPanelSources = [];
+		const tokens = md.parse(source, { tabsPanelSources });
+		for (let index = 0; index < tokens.length; index++) {
+			const token = tokens[index];
+			if (withHeadings && token.type === "heading_open") {
+				const inline = tokens[index + 1];
+				if (inline?.type !== "inline") continue;
+				const title = getInlineSearchText(inline);
+				if (!title) continue;
+				activeSection = {
+					title,
+					anchor: token.attrGet("id") || "",
+					level: Number(token.tag.slice(1)) || 1,
+					text: ""
+				};
+				sections.push(activeSection);
+				continue;
+			}
+			if (token.type !== "inline" || tokens[index - 1]?.type === "heading_open") continue;
+			consumeInline(getInlineSearchText(token));
+		}
+		for (const panelSource of tabsPanelSources) walk(panelSource, false);
+	};
+	walk(content, true);
 	return {
 		title: sections.find((section) => section.level === 1)?.title || sections[0]?.title || "",
 		text: normalizeSearchText(documentParts.join(" ")),
@@ -211,11 +339,137 @@ var parseMarkdownSearchSections = (content) => {
 	};
 };
 //#endregion
+//#region packages/markdown/src/tab-query.ts
+var markdownTabQueryKey = Symbol("docs-markdown-tab-query");
+var TAB_QUERY = "tab";
+/**
+* 不依赖 Vue Router 的默认适配器：读写 `location.search` 的 `tab`，
+* 并用 `history.replaceState` 更新（供 examples / 单测使用）。
+* @returns 可注入 TabsNav 的 get/set/subscribe 适配器。
+*/
+var createHistoryTabQueryAdapter = () => {
+	const read = () => {
+		try {
+			return new URLSearchParams(window.location.search).get(TAB_QUERY) || "";
+		} catch {
+			return "";
+		}
+	};
+	const write = (tab) => {
+		try {
+			const url = new URL(window.location.href);
+			if (tab) url.searchParams.set(TAB_QUERY, tab);
+			else url.searchParams.delete(TAB_QUERY);
+			window.history.replaceState(window.history.state, "", `${url.pathname}${url.search}${url.hash}`);
+		} catch {}
+	};
+	return {
+		get: read,
+		set: write,
+		subscribe: (listener) => {
+			const onPopState = () => listener();
+			window.addEventListener("popstate", onPopState);
+			return () => window.removeEventListener("popstate", onPopState);
+		}
+	};
+};
+//#endregion
+//#region packages/markdown/src/tabs-nav.vue?vue&type=script&setup=true&lang.ts
+var _hoisted_1$1 = ["aria-label"];
+var _hoisted_2$1 = [
+	"id",
+	"aria-selected",
+	"aria-controls",
+	"tabindex",
+	"onClick"
+];
+//#endregion
+//#region packages/markdown/src/tabs-nav.vue
+var tabs_nav_default = /* @__PURE__ */ defineComponent({
+	__name: "tabs-nav",
+	props: {
+		items: {},
+		label: {},
+		adapter: {},
+		root: {},
+		groupId: {}
+	},
+	setup(__props) {
+		const props = __props;
+		const activeId = ref("");
+		let unsubscribe;
+		const tabButtonId = (id) => `${props.groupId}-tab-${id}`;
+		const tabPanelId = (id) => `${props.groupId}-panel-${id}`;
+		const resolveActive = () => {
+			const fromQuery = props.adapter.get();
+			const matched = props.items.find((item) => item.id === fromQuery);
+			activeId.value = matched?.id || props.items[0]?.id || "";
+		};
+		const syncPanels = () => {
+			props.root.querySelectorAll(".docs-markdown-tabs__panel").forEach((panel) => {
+				const id = panel.dataset.tab || "";
+				const selected = id === activeId.value;
+				panel.hidden = !selected;
+				panel.setAttribute("aria-labelledby", tabButtonId(id));
+				if (selected) {
+					panel.removeAttribute("hidden");
+					panel.id = tabPanelId(id);
+				} else {
+					panel.setAttribute("hidden", "");
+					panel.id = tabPanelId(id);
+				}
+			});
+		};
+		const select = (id) => {
+			if (!id) return;
+			activeId.value = id;
+			props.adapter.set(id);
+			syncPanels();
+		};
+		onMounted(() => {
+			resolveActive();
+			syncPanels();
+			unsubscribe = props.adapter.subscribe?.(() => {
+				resolveActive();
+				syncPanels();
+			});
+		});
+		onBeforeUnmount(() => {
+			unsubscribe?.();
+			unsubscribe = void 0;
+		});
+		watch(() => props.items.map((item) => item.id).join("\0"), () => {
+			resolveActive();
+			syncPanels();
+		});
+		return (_ctx, _cache) => {
+			return openBlock(), createElementBlock("div", {
+				class: "docs-markdown-tabs__list",
+				role: "tablist",
+				"aria-label": __props.label
+			}, [(openBlock(true), createElementBlock(Fragment, null, renderList(__props.items, (item) => {
+				return openBlock(), createElementBlock("button", {
+					key: item.id,
+					type: "button",
+					class: normalizeClass(["docs-markdown-tabs__tab", { "docs-markdown-tabs__tab--active": item.id === activeId.value }]),
+					role: "tab",
+					id: tabButtonId(item.id),
+					"aria-selected": item.id === activeId.value,
+					"aria-controls": tabPanelId(item.id),
+					tabindex: item.id === activeId.value ? 0 : -1,
+					onClick: ($event) => select(item.id)
+				}, toDisplayString(item.title), 11, _hoisted_2$1);
+			}), 128))], 8, _hoisted_1$1);
+		};
+	}
+});
+//#endregion
 //#region packages/markdown/src/directive.ts
 var mountedApps = /* @__PURE__ */ new WeakMap();
 var renderVersions = /* @__PURE__ */ new WeakMap();
 var playgroundModule;
 var loadPlayground = () => playgroundModule ||= import("@deot/docs-playground");
+var defaultTabQuery = createHistoryTabQueryAdapter();
 var cleanup = (el) => {
 	for (const app of mountedApps.get(el) || []) app.unmount();
 	mountedApps.delete(el);
@@ -223,12 +477,37 @@ var cleanup = (el) => {
 var resolveBlockLanguage = (block) => {
 	return [...block.classList].find((className) => className.startsWith("language-"))?.slice(9) || "";
 };
+var serializePlaygroundDefaults = (value) => JSON.stringify(value || {});
+var mountTabs = (el, apps, locale, adapter) => {
+	const label = locale.markdown?.tabs?.label || "Tabs";
+	el.querySelectorAll("[data-tabs]").forEach((root, index) => {
+		const nav = root.querySelector("[data-tabs-nav]");
+		if (!nav) return;
+		const items = [...root.querySelectorAll(".docs-markdown-tabs__panel")].map((panel) => ({
+			id: panel.dataset.tab || "",
+			title: panel.dataset.tabTitle || panel.dataset.tab || ""
+		})).filter((item) => item.id && item.title);
+		if (!items.length) return;
+		const groupId = `docs-markdown-tabs-${index}`;
+		const app = createApp({ render: () => h(tabs_nav_default, {
+			items,
+			label,
+			adapter,
+			root,
+			groupId
+		}) });
+		app.mount(nav);
+		apps.push(app);
+	});
+};
 var render = async (el, binding) => {
 	cleanup(el);
 	const version = (renderVersions.get(el) || 0) + 1;
 	renderVersions.set(el, version);
 	el.innerHTML = binding.value.source ? Markdown.render(binding.value.source) : "";
 	const apps = [];
+	const adapter = binding.value.tabQuery || defaultTabQuery;
+	mountTabs(el, apps, binding.value.locale, adapter);
 	const blocks = el.querySelectorAll("pre code");
 	const playgrounds = el.querySelectorAll("div[data-playground]");
 	if (!blocks.length && !playgrounds.length) {
@@ -251,6 +530,7 @@ var render = async (el, binding) => {
 		app.mount(mountPoint);
 		apps.push(app);
 	});
+	const sitePlaygroundDefaults = binding.value.playground && typeof binding.value.playground === "object" ? binding.value.playground : {};
 	playgrounds.forEach((item) => {
 		const code = item.dataset.code;
 		let files;
@@ -266,6 +546,7 @@ var render = async (el, binding) => {
 			entry: item.dataset.entry
 		} : { modelValue: code };
 		const app = createApp(() => h(DocsPlayground.Playground, {
+			...sitePlaygroundDefaults,
 			...typeof propsData === "object" ? propsData : {},
 			...runtimeProps,
 			locale: binding.value.locale
@@ -276,7 +557,7 @@ var render = async (el, binding) => {
 	mountedApps.set(el, apps);
 };
 var update = (el, binding) => {
-	if (binding.value.source !== binding.oldValue?.source || binding.value.locale !== binding.oldValue?.locale) render(el, binding);
+	if (binding.value.source !== binding.oldValue?.source || binding.value.locale !== binding.oldValue?.locale || binding.value.tabQuery !== binding.oldValue?.tabQuery || serializePlaygroundDefaults(binding.value.playground) !== serializePlaygroundDefaults(binding.oldValue?.playground)) render(el, binding);
 };
 var vMarkdown = {
 	mounted: (el, binding) => void render(el, binding),
@@ -286,17 +567,154 @@ var vMarkdown = {
 		cleanup(el);
 	}
 };
+/**
+* 指示器高度不能超过正文实际高度，也不能超出当前滚动容器可视区域。
+* 与文档壳大纲的封顶规则一致。
+* @param articleHeight 正文高度。
+* @param viewportHeight 主滚动容器可视高度。
+* @returns 指示器最大高度，单位 px。
+*/
+var capIndicatorMaxHeight = (articleHeight, viewportHeight) => {
+	const article = Math.max(0, articleHeight);
+	const viewport = Math.max(0, viewportHeight);
+	if (!article) return viewport;
+	if (!viewport) return article;
+	return Math.min(article, viewport);
+};
+/**
+* 滑轨高度再受 sticky 父级剩余空间约束，避免滚到文末盖住 footer。
+* @param cap 正文/视口封顶后的高度。
+* @param available 指示器顶部到父级底部的剩余像素；非有限值表示不额外约束。
+* @returns 最终高度，单位 px。
+*/
+var capStickyAvailableHeight = (cap, available) => {
+	const limited = Math.max(0, cap);
+	if (!Number.isFinite(available)) return limited;
+	return Math.min(limited, Math.max(0, available));
+};
+/**
+* 把主滚动位置映射成小地图可视窗口（相对轨道的 0–1 比例）。
+* @param scrollTop 当前滚动偏移。
+* @param clientHeight 滚动容器可视高度。
+* @param scrollHeight 滚动内容总高度。
+* @returns 窗口顶部与高度比例。
+*/
+var getMinimapWindow = (scrollTop, clientHeight, scrollHeight) => {
+	const total = Math.max(0, scrollHeight);
+	if (!total) return {
+		height: 1,
+		top: 0
+	};
+	const height = Math.min(1, Math.max(0, clientHeight / total));
+	const maxTop = Math.max(0, 1 - height);
+	return {
+		height,
+		top: maxTop <= 0 ? 0 : Math.min(maxTop, Math.max(0, scrollTop / total))
+	};
+};
+/**
+* 按小地图窗口顶部选出当前阅读刻度：最后一个仍不晚于窗口顶的块。
+* 滚到末屏时固定最后一条，避免末块永远到不了窗口顶。
+* @param ratios 刻度在正文中的 0–1 比例，按出现顺序。
+* @param windowTop 可视窗口顶部比例。
+* @param windowHeight 可视窗口高度比例。
+* @returns 当前刻度序号；没有刻度时为 -1。
+*/
+var findActiveMinimapIndex = (ratios, windowTop, windowHeight) => {
+	if (!ratios.length) return -1;
+	if (windowTop + windowHeight >= .999) return ratios.length - 1;
+	let active = 0;
+	for (let index = 0; index < ratios.length; index++) if ((ratios[index] || 0) <= windowTop) active = index;
+	return active;
+};
+/**
+* 判断刻度是否落在当前可视窗口内。
+* @param ratio 刻度比例。
+* @param windowTop 可视窗口顶部比例。
+* @param windowHeight 可视窗口高度比例。
+* @returns 是否位于窗口内。
+*/
+var isMinimapMarkerInView = (ratio, windowTop, windowHeight) => {
+	const top = Math.max(0, windowTop);
+	const bottom = top + Math.max(0, windowHeight);
+	return ratio >= top && ratio <= bottom;
+};
+/**
+* 把指针纵坐标映射成轨道上的 0–1 比例。
+* @param clientY 指针视口纵坐标。
+* @param trackTop 轨道顶部。
+* @param trackHeight 轨道高度。
+* @returns 夹紧后的比例。
+*/
+var getMinimapPointerRatio = (clientY, trackTop, trackHeight) => {
+	if (trackHeight <= 0) return 0;
+	return Math.min(1, Math.max(0, (clientY - trackTop) / trackHeight));
+};
+/**
+* 把指示器刻度对齐到文档壳斜纹轨的内侧，并留出 `INDICATOR_RAIL_GAP`。
+* 左侧靠近 `rail--start` 的右缘，右侧靠近 `rail--end` 的左缘。
+* 没有可见轨道时返回 undefined，由样式回退到正文边缘。
+* @param root 指示器根节点相对视口的盒子。
+* @param rail 当前侧斜纹轨的盒子。
+* @param side 指示器所在侧。
+* @param viewportWidth 刻度轨道宽度。
+* @returns 相对指示器根节点的 left 偏移，单位 px。
+*/
+var getIndicatorInlineOffset = (root, rail, side, viewportWidth) => {
+	if (!rail || rail.width <= 0 || rail.height <= 0) return;
+	if (side === "left") return rail.right - root.left + 8;
+	return rail.left - root.left - viewportWidth - 8;
+};
+//#endregion
+//#region packages/markdown/src/headings.ts
+var HEADING_SELECTOR = "h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]";
+var SKIP_CLOSEST = [
+	"pre",
+	".docs-markdown-code-preview",
+	"[data-playground][data-code]",
+	"[data-playground][data-files]",
+	".docs-markdown-tabs__panel[hidden]"
+].join(", ");
+/**
+* 去掉 markdown-it-anchor 的井号后，读取标题的可见文案。
+* @param element 当前标题节点。
+* @returns 单行章节标题。
+*/
+var getMarkdownHeadingTitle = (element) => {
+	const clone = element.cloneNode(true);
+	clone.querySelectorAll(".header-anchor").forEach((node) => node.remove());
+	return (clone.textContent || "").replace(/\s+/g, " ").trim();
+};
+/**
+* 从已渲染的 Markdown 中收集带 id 的标题，规则与文档壳大纲一致：
+* 忽略代码块 / Playground 内部标题；有章节标题时不把页面 h1 算进去。
+* @param root Markdown 所在容器。
+* @returns 大纲条目，按出现顺序排列。
+*/
+var collectMarkdownHeadings = (root) => {
+	if (!root || !("querySelectorAll" in root)) return [];
+	return [...root.querySelectorAll(HEADING_SELECTOR)].filter((element) => !element.closest(SKIP_CLOSEST) && Boolean(getMarkdownHeadingTitle(element))).map((element) => ({
+		element,
+		id: element.id,
+		level: Number(element.tagName.slice(1)),
+		text: getMarkdownHeadingTitle(element)
+	})).filter((item, _, headings) => item.level > 1 || headings.every((heading) => heading.level === 1));
+};
 //#endregion
 //#region packages/markdown/src/indicator.vue?vue&type=script&setup=true&lang.ts
-var _hoisted_1$1 = ["aria-label"];
-var _hoisted_2 = { class: "docs-markdown-indicator__list" };
-var _hoisted_3 = ["aria-label", "onClick"];
-var _hoisted_4 = { class: "docs-markdown-indicator__preview-title" };
-var _hoisted_5 = {
+var _hoisted_1 = ["aria-label"];
+var _hoisted_2 = ["aria-valuenow", "aria-valuetext"];
+var _hoisted_3 = { class: "docs-markdown-indicator__preview-title" };
+var _hoisted_4 = {
 	key: 0,
 	class: "docs-markdown-indicator__preview-content"
 };
-var MAX_ARIA_LABEL_LENGTH = 180;
+var LAYOUT_SELECTOR = ".docs-layout";
+var RAIL_START_SELECTOR = ".docs-layout__rail--start";
+var RAIL_END_SELECTOR = ".docs-layout__rail--end";
+var VIEWPORT_WIDTH = 40;
+/** 与 docs-page-outline 上下 padding 一致，需从轨道高度中扣除。 */
+var INDICATOR_CHROME = 136;
 //#endregion
 //#region packages/markdown/src/indicator.vue
 var indicator_default = /* @__PURE__ */ defineComponent({
@@ -306,61 +724,82 @@ var indicator_default = /* @__PURE__ */ defineComponent({
 		target: {}
 	},
 	setup(__props) {
-		const BLOCK_SELECTOR = [
-			"h1",
-			"h2",
-			"h3",
-			"h4",
-			"h5",
-			"h6",
-			"p",
-			"li",
-			"pre",
-			"blockquote",
-			"table",
-			".tip",
-			".warning",
-			".docs-markdown-code-preview",
-			"[data-playground]"
-		].join(",");
-		const CONTAINER_SELECTOR = [
-			"li",
-			"blockquote",
-			"table",
-			".tip",
-			".warning",
-			".docs-markdown-code-preview",
-			"[data-playground]"
-		].join(",");
 		const props = __props;
 		const { lang: localeName, t } = useLocale();
 		const parentScroller = inject("vc-scroller", null);
 		const indicatorRoot = ref();
 		const viewport = ref();
 		const rail = ref();
-		const indicatorScroller = ref();
 		const markers = shallowRef([]);
-		const activeIndex = ref(0);
 		const hoverIndex = ref();
+		const activeIndex = ref(-1);
 		const previewTop = ref(0);
 		const dragging = ref(false);
-		const stickyInset = ref("0px");
+		const cappedHeight = ref(0);
+		const inlineAnchor = ref();
+		const windowBox = ref(getMinimapWindow(0, 0, 0));
 		let observer;
 		let hostResizeObserver;
 		let scrollHost;
 		let usesParentScroller = false;
 		let captureTarget;
 		let refreshFrame = 0;
-		let activeFrame = 0;
+		let windowFrame = 0;
 		let targetGeneration = 0;
 		const toCssLength = (value, fallback) => typeof value === "number" ? `${value}px` : value || fallback;
+		const resolvedHeight = computed(() => {
+			const cap = cappedHeight.value;
+			const configured = props.options.height;
+			if (typeof configured === "number" && Number.isFinite(configured) && configured > 0) return `${cap > 0 ? Math.min(configured, cap) : configured}px`;
+			if (typeof configured === "string" && configured.trim()) return configured;
+			if (cap > 0) return `${cap}px`;
+			return "calc(100svh - 60px)";
+		});
+		/** 扣除上下 padding 后的轨道高度。小地图轨高等于该值，不再内部滚动。 */
+		const resolvedTrackHeight = computed(() => {
+			const height = resolvedHeight.value;
+			if (height.endsWith("px")) {
+				const total = Number.parseFloat(height);
+				if (Number.isFinite(total)) return `${Math.max(0, total - INDICATOR_CHROME)}px`;
+			}
+			return `calc(${height} - ${INDICATOR_CHROME}px)`;
+		});
 		const rootStyle = computed(() => ({
-			"--docs-markdown-indicator-height": toCssLength(props.options.height, "min(72vh, 600px)"),
-			"--docs-markdown-indicator-inset": stickyInset.value,
+			"--docs-markdown-indicator-height": resolvedHeight.value,
+			"--docs-markdown-indicator-track-height": resolvedTrackHeight.value,
 			"--docs-markdown-indicator-top": toCssLength(props.options.top, "0px")
 		}));
 		const hoveredMarker = computed(() => typeof hoverIndex.value === "number" ? markers.value[hoverIndex.value] : void 0);
-		const previewStyle = computed(() => ({ top: `${previewTop.value}px` }));
+		const isMarkerInView = (index) => {
+			const marker = markers.value[index];
+			if (!marker) return false;
+			return isMinimapMarkerInView(marker.ratio, windowBox.value.top, windowBox.value.height);
+		};
+		const resolvedPosition = computed(() => props.options.position === "right" ? "right" : "left");
+		const scrollProgress = computed(() => Math.round(windowBox.value.top * 100));
+		const viewportStyle = computed(() => {
+			if (typeof inlineAnchor.value !== "number") return;
+			return {
+				left: `${inlineAnchor.value}px`,
+				right: "auto"
+			};
+		});
+		const windowStyle = computed(() => ({
+			height: `${windowBox.value.height * 100}%`,
+			top: `${windowBox.value.top * 100}%`
+		}));
+		const previewStyle = computed(() => {
+			const style = { top: `${previewTop.value}px` };
+			if (typeof inlineAnchor.value !== "number") return style;
+			if (resolvedPosition.value === "left") {
+				style.left = `${inlineAnchor.value + 24}px`;
+				style.right = "auto";
+			} else {
+				style.left = "auto";
+				style.right = `calc(100% - ${inlineAnchor.value}px)`;
+			}
+			return style;
+		});
 		/**
 		* 保留文档块的有效换行，同时折叠每行内部的多余空白。
 		* @param element 当前文档块。
@@ -368,30 +807,21 @@ var indicator_default = /* @__PURE__ */ defineComponent({
 		*/
 		const getBlockText = (element) => (element.textContent || "").split(/\n+/).map((line) => line.replace(/\s+/g, " ").trim()).filter(Boolean).join("\n");
 		/**
-		* 清理标题锚点产生的井号，并提供无标题内容的兜底文本。
-		* @param element 当前标题节点。
-		* @returns 单行章节标题。
+		* 取当前标题到下一标题之间的第一段正文，作为悬停摘要。
+		* @param heading 当前标题。
+		* @param nextHeading 下一个标题，没有则为空。
+		* @returns 摘要文本。
 		*/
-		const getHeadingTitle = (element) => getBlockText(element).replace(/^#\s*/, "").replace(/\s+/g, " ").trim() || t("markdown.indicator.untitled");
-		/**
-		* 为无障碍名称限制长度，避免长代码块生成过大的属性值。
-		* @param title 当前章节标题。
-		* @param content 当前文档块内容。
-		* @returns 标题和内容组成的简短名称。
-		*/
-		const getAriaLabel = (title, content) => {
-			const value = content ? `${title}: ${content.replace(/\s+/g, " ")}` : title;
-			if (value.length <= MAX_ARIA_LABEL_LENGTH) return value;
-			return `${value.slice(0, MAX_ARIA_LABEL_LENGTH).trim()}…`;
-		};
-		/**
-		* 判断候选节点是否已经包含在另一个可独立定位的文档块内。
-		* @param element 当前候选节点。
-		* @returns 是否应由外层文档块统一表示。
-		*/
-		const isNestedBlock = (element) => {
-			const container = element.closest(CONTAINER_SELECTOR);
-			return Boolean(container && container !== element);
+		const getPreviewContent = (heading, nextHeading) => {
+			let node = heading.nextElementSibling;
+			while (node && node !== nextHeading) {
+				if (!/^H[1-6]$/.test(node.tagName)) {
+					const text = getBlockText(node);
+					if (text) return text;
+				}
+				node = node.nextElementSibling;
+			}
+			return "";
 		};
 		/**
 		* 获取 Markdown 使用的原生滚动宿主。
@@ -400,77 +830,118 @@ var indicator_default = /* @__PURE__ */ defineComponent({
 		*/
 		const getScrollHost = () => getScroller(props.target) || window;
 		/**
-		* 获取当前滚动宿主的可视区域顶部。
-		* @returns 相对于视口的顶部坐标。
+		* 读取当前滚动容器的可视高度。
+		* @returns 滚动容器 clientHeight，窗口滚动时回退到 innerHeight。
 		*/
-		const getScrollHostTop = () => {
-			if (usesParentScroller) return parentScroller?.wrapper?.getBoundingClientRect().top || 0;
-			return scrollHost instanceof HTMLElement ? scrollHost.getBoundingClientRect().top : 0;
+		const getScrollHostClientHeight = () => {
+			if (usesParentScroller) return parentScroller?.wrapper?.clientHeight || parentScroller?.clientHeight || window.innerHeight;
+			if (scrollHost instanceof HTMLElement) return scrollHost.clientHeight;
+			return window.innerHeight;
 		};
 		/**
-		* 判断文档是否已经到达滚动末尾。
-		* 末屏通常无法把最后一个内容块推到顶部阈值，因此需要显式选中最后一条刻度。
-		* @returns 是否位于可滚动内容末尾。
+		* 读取主滚动的位置与尺寸，供可视窗口和 scrub 共用。
+		* @returns 当前滚动偏移、可视高度和内容总高度。
 		*/
-		const isScrollEnd = () => {
-			let clientHeight;
-			let scrollHeight;
-			let scrollTop;
-			if (usesParentScroller) {
-				clientHeight = parentScroller?.clientHeight || 0;
-				scrollHeight = parentScroller?.scrollHeight || 0;
-				scrollTop = parentScroller?.scrollTop || 0;
-			} else if (scrollHost instanceof HTMLElement) {
-				clientHeight = scrollHost.clientHeight;
-				scrollHeight = scrollHost.scrollHeight;
-				scrollTop = scrollHost.scrollTop;
-			} else {
-				clientHeight = window.innerHeight;
-				scrollHeight = document.documentElement.scrollHeight;
-				scrollTop = window.scrollY;
-			}
-			return scrollHeight > clientHeight && scrollTop + clientHeight >= scrollHeight - 1;
+		const getScrollMetrics = () => {
+			if (usesParentScroller) return {
+				clientHeight: parentScroller?.clientHeight || parentScroller?.wrapper?.clientHeight || 0,
+				scrollHeight: parentScroller?.scrollHeight || parentScroller?.wrapper?.scrollHeight || 0,
+				scrollTop: parentScroller?.scrollTop || 0
+			};
+			if (scrollHost instanceof HTMLElement) return {
+				clientHeight: scrollHost.clientHeight,
+				scrollHeight: scrollHost.scrollHeight,
+				scrollTop: scrollHost.scrollTop
+			};
+			return {
+				clientHeight: window.innerHeight,
+				scrollHeight: document.documentElement.scrollHeight,
+				scrollTop: window.scrollY
+			};
 		};
 		/**
-		* 保证当前阅读刻度处于内部 Scroller 的可视范围内。
-		* @param index 当前阅读刻度序号。
+		* 按正文、主滚动可视高度，以及 sticky 父级剩余空间封顶，避免盖住 footer。
+		* @returns 指示器可用的最大高度，单位 px。
 		*/
-		const followActiveMarker = async (index) => {
-			await nextTick();
-			const marker = rail.value?.querySelectorAll(".docs-markdown-indicator__marker")[index];
-			const wrapper = viewport.value?.querySelector(".vc-scroller__wrapper");
-			if (!marker || !wrapper) return;
-			const markerRect = marker.getBoundingClientRect();
-			const wrapperRect = wrapper.getBoundingClientRect();
-			const padding = 16;
-			if (markerRect.top >= wrapperRect.top + padding && markerRect.bottom <= wrapperRect.bottom - padding) return;
-			const markerCenter = markerRect.top + markerRect.height / 2;
-			const wrapperCenter = wrapperRect.top + wrapperRect.height / 2;
-			indicatorScroller.value?.setScrollTop(Math.max(0, wrapper.scrollTop + markerCenter - wrapperCenter));
+		const getStickyAvailableHeight = () => {
+			const root = indicatorRoot.value;
+			const parent = root?.parentElement;
+			if (!root || !parent) return Number.POSITIVE_INFINITY;
+			const parentBox = parent.getBoundingClientRect();
+			if (parentBox.height <= 0 && parentBox.bottom === 0) return Number.POSITIVE_INFINITY;
+			return parentBox.bottom - root.getBoundingClientRect().top;
 		};
-		/** 根据滚动位置更新当前阅读块，不触发 Markdown 内容重渲染。 */
-		const updateActiveIndex = () => {
-			activeFrame = 0;
-			if (!markers.value.length) return;
-			const threshold = getScrollHostTop() + 80;
-			let nextIndex = markers.value.length - 1;
-			if (!isScrollEnd()) {
-				nextIndex = 0;
-				for (let index = 0; index < markers.value.length; index++) {
-					if (markers.value[index].element.getBoundingClientRect().top > threshold) break;
-					nextIndex = index;
-				}
+		const updateCappedHeight = () => {
+			cappedHeight.value = capStickyAvailableHeight(capIndicatorMaxHeight(props.target?.offsetHeight || 0, getScrollHostClientHeight()), getStickyAvailableHeight());
+		};
+		/** 根据主滚动位置更新小地图可视窗口和当前刻度。 */
+		const updateWindow = () => {
+			windowFrame = 0;
+			const metrics = getScrollMetrics();
+			windowBox.value = getMinimapWindow(metrics.scrollTop, metrics.clientHeight, metrics.scrollHeight);
+			activeIndex.value = findActiveMinimapIndex(markers.value.map((marker) => marker.ratio), windowBox.value.top, windowBox.value.height);
+		};
+		/**
+		* 有文档壳斜纹轨时，把刻度靠近轨道内侧并留出间距；否则清空偏移，沿用正文边缘定位。
+		*/
+		const updateInlineAnchor = () => {
+			const root = indicatorRoot.value;
+			if (!root) {
+				inlineAnchor.value = void 0;
+				return;
 			}
-			if (activeIndex.value !== nextIndex) {
-				activeIndex.value = nextIndex;
-				followActiveMarker(nextIndex);
+			const layoutRail = root.closest(LAYOUT_SELECTOR)?.querySelector(resolvedPosition.value === "left" ? RAIL_START_SELECTOR : RAIL_END_SELECTOR);
+			const railRect = layoutRail && getComputedStyle(layoutRail).display !== "none" ? layoutRail.getBoundingClientRect() : void 0;
+			inlineAnchor.value = getIndicatorInlineOffset(root.getBoundingClientRect(), railRect, resolvedPosition.value, viewport.value?.offsetWidth || VIEWPORT_WIDTH);
+		};
+		/** 同步高度封顶、斜纹轨锚点、刻度比例和可视窗口。 */
+		const updateLayout = () => {
+			updateCappedHeight();
+			updateInlineAnchor();
+			if (props.target && markers.value.length) {
+				const article = props.target;
+				markers.value = markers.value.map((marker) => ({
+					...marker,
+					ratio: getBlockRatio(marker.element, article)
+				}));
 			}
+			updateWindow();
 		};
-		/** 将连续滚动事件合并到浏览器的下一绘制帧。 */
-		const handleScroll = () => {
-			if (!activeFrame) activeFrame = requestAnimationFrame(updateActiveIndex);
+		/** 跟随滚动容器、正文和指示器自身的尺寸变化。 */
+		const observeHostSize = () => {
+			hostResizeObserver?.disconnect();
+			hostResizeObserver = void 0;
+			if (typeof ResizeObserver !== "undefined") {
+				hostResizeObserver = new ResizeObserver(updateLayout);
+				const host = usesParentScroller ? parentScroller?.wrapper : scrollHost instanceof HTMLElement ? scrollHost : void 0;
+				if (host) hostResizeObserver.observe(host);
+				if (props.target) hostResizeObserver.observe(props.target);
+				if (viewport.value) hostResizeObserver.observe(viewport.value);
+				if (indicatorRoot.value) hostResizeObserver.observe(indicatorRoot.value);
+				const parent = indicatorRoot.value?.parentElement;
+				if (parent) hostResizeObserver.observe(parent);
+				const layout = indicatorRoot.value?.closest(LAYOUT_SELECTOR);
+				if (layout instanceof HTMLElement) hostResizeObserver.observe(layout);
+				const startRail = layout?.querySelector(RAIL_START_SELECTOR);
+				const endRail = layout?.querySelector(RAIL_END_SELECTOR);
+				if (startRail instanceof HTMLElement) hostResizeObserver.observe(startRail);
+				if (endRail instanceof HTMLElement) hostResizeObserver.observe(endRail);
+			}
+			updateLayout();
 		};
-		/** 从最新渲染的 Markdown DOM 重建文档刻度。 */
+		/**
+		* 计算文档块相对正文顶部的比例，用于铺在固定高度轨道上。
+		* @param element 当前文档块。
+		* @param article 正文根节点。
+		* @returns 0–1 的纵向比例。
+		*/
+		const getBlockRatio = (element, article) => {
+			const articleHeight = article.offsetHeight || article.getBoundingClientRect().height;
+			if (articleHeight <= 0) return 0;
+			const top = element.getBoundingClientRect().top - article.getBoundingClientRect().top;
+			return Math.min(1, Math.max(0, top / articleHeight));
+		};
+		/** 从最新渲染的 Markdown DOM 重建小地图刻度。 */
 		const refreshMarkers = () => {
 			refreshFrame = 0;
 			const target = props.target;
@@ -478,67 +949,28 @@ var indicator_default = /* @__PURE__ */ defineComponent({
 				markers.value = [];
 				return;
 			}
-			const elements = [...target.querySelectorAll(BLOCK_SELECTOR)].filter((element) => !isNestedBlock(element));
-			let sectionTitle = t("markdown.indicator.document");
-			markers.value = elements.map((element, index) => {
-				const isHeading = /^H[1-6]$/.test(element.tagName);
-				if (isHeading) sectionTitle = getHeadingTitle(element);
-				const nextElement = elements[index + 1];
-				const content = isHeading && nextElement && !/^H[1-6]$/.test(nextElement.tagName) ? getBlockText(nextElement) : isHeading ? "" : getBlockText(element);
-				return {
-					ariaLabel: getAriaLabel(sectionTitle, content),
-					content,
-					element,
-					id: `${index}-${element.id || element.tagName}`,
-					title: sectionTitle
-				};
-			});
+			const headings = collectMarkdownHeadings(target);
+			markers.value = headings.map((heading, index) => ({
+				content: getPreviewContent(heading.element, headings[index + 1]?.element),
+				element: heading.element,
+				id: heading.id || `${index}`,
+				isHeading: true,
+				ratio: getBlockRatio(heading.element, target),
+				title: heading.text
+			}));
 			hoverIndex.value = void 0;
-			updateActiveIndex();
-			followActiveMarker(activeIndex.value);
+			updateWindow();
 		};
 		/** 合并 MutationObserver 的密集通知，避免 Playground 挂载时重复扫描。 */
 		const scheduleRefresh = () => {
 			if (!refreshFrame) refreshFrame = requestAnimationFrame(refreshMarkers);
 		};
-		/**
-		* 读取当前滚动容器的可视高度。
-		* sticky 的百分比 top 会相对整篇文档计算，不能用来做容器垂直居中。
-		* @returns 滚动容器 clientHeight，窗口滚动时回退到 innerHeight。
-		*/
-		const getScrollHostClientHeight = () => {
-			if (usesParentScroller) return parentScroller?.wrapper?.clientHeight || parentScroller?.clientHeight || window.innerHeight;
-			if (scrollHost instanceof HTMLElement) return scrollHost.clientHeight;
-			return window.innerHeight;
-		};
-		/**
-		* 读取指示器可视高度：数字配置优先，否则测量已挂载节点或回退默认值。
-		* @returns 指示器高度，单位 px。
-		*/
-		const resolveIndicatorHeight = () => {
-			const height = props.options.height;
-			if (typeof height === "number" && Number.isFinite(height) && height > 0) return height;
-			const measured = viewport.value?.getBoundingClientRect().height || 0;
-			if (measured > 0) return measured;
-			return Math.min(window.innerHeight * .72, 600);
-		};
-		/** 把指示器钉在滚动容器可视区域的垂直中心。 */
-		const updateStickyInset = () => {
-			const hostHeight = getScrollHostClientHeight();
-			const indicatorHeight = resolveIndicatorHeight();
-			stickyInset.value = hostHeight > 0 ? `${Math.max(0, (hostHeight - indicatorHeight) / 2)}px` : "0px";
-		};
-		/** 跟随滚动容器和指示器自身的尺寸变化，保持垂直居中。 */
-		const observeHostSize = () => {
-			hostResizeObserver?.disconnect();
-			hostResizeObserver = void 0;
-			if (typeof ResizeObserver !== "undefined") {
-				hostResizeObserver = new ResizeObserver(updateStickyInset);
-				const host = usesParentScroller ? parentScroller?.wrapper : scrollHost instanceof HTMLElement ? scrollHost : void 0;
-				if (host) hostResizeObserver.observe(host);
-				if (viewport.value) hostResizeObserver.observe(viewport.value);
-			}
-			updateStickyInset();
+		/** 将连续滚动事件合并到下一帧：更新可视窗口，并按父级底部收缩高度。 */
+		const handleScroll = () => {
+			if (!windowFrame) windowFrame = requestAnimationFrame(() => {
+				updateCappedHeight();
+				updateWindow();
+			});
 		};
 		/** 解除旧文档的观察和滚动监听。 */
 		const cleanupTarget = () => {
@@ -546,7 +978,7 @@ var indicator_default = /* @__PURE__ */ defineComponent({
 			observer = void 0;
 			hostResizeObserver?.disconnect();
 			hostResizeObserver = void 0;
-			window.removeEventListener("resize", updateStickyInset);
+			window.removeEventListener("resize", updateLayout);
 			if (usesParentScroller) parentScroller?.off?.(handleScroll);
 			else if (scrollHost) scrollHost.removeEventListener("scroll", handleScroll);
 			usesParentScroller = false;
@@ -570,7 +1002,7 @@ var indicator_default = /* @__PURE__ */ defineComponent({
 				scrollHost = getScrollHost();
 				scrollHost.addEventListener("scroll", handleScroll, { passive: true });
 			}
-			window.addEventListener("resize", updateStickyInset, { passive: true });
+			window.addEventListener("resize", updateLayout, { passive: true });
 			observer = new MutationObserver(scheduleRefresh);
 			observer.observe(props.target, {
 				childList: true,
@@ -581,18 +1013,16 @@ var indicator_default = /* @__PURE__ */ defineComponent({
 			observeHostSize();
 		};
 		/**
-		* 将指示器内的纵坐标转换为最近的文档块序号。
-		* @param event 当前指针事件。
-		* @returns 距离指针最近的文档块序号。
+		* 把轨道上的指针位置映射到最近的刻度，只用于悬停预览。
+		* @param ratio 轨道 0–1 比例。
+		* @returns 最近刻度序号。
 		*/
-		const getIndexByPointer = (event) => {
-			if (!rail.value || !markers.value.length) return 0;
-			const elements = [...rail.value.querySelectorAll(".docs-markdown-indicator__marker")];
+		const getIndexByRatio = (ratio) => {
+			if (!markers.value.length) return 0;
 			let closestIndex = 0;
 			let closestDistance = Number.POSITIVE_INFINITY;
-			elements.forEach((element, index) => {
-				const bounds = element.getBoundingClientRect();
-				const distance = Math.abs(event.clientY - (bounds.top + bounds.height / 2));
+			markers.value.forEach((marker, index) => {
+				const distance = Math.abs(marker.ratio - ratio);
 				if (distance < closestDistance) {
 					closestIndex = index;
 					closestDistance = distance;
@@ -601,66 +1031,73 @@ var indicator_default = /* @__PURE__ */ defineComponent({
 			return closestIndex;
 		};
 		/**
-		* 让摘要跟随当前刻度，同时限制在指示器可视高度内。
-		* @param index 当前刻度序号。
+		* 读取指针相对轨道的比例。
+		* @param event 当前指针事件。
+		* @returns 0–1 比例。
+		*/
+		const getPointerRatio = (event) => {
+			const bounds = rail.value?.getBoundingClientRect();
+			if (!bounds) return 0;
+			return getMinimapPointerRatio(event.clientY, bounds.top, bounds.height);
+		};
+		/**
+		* 让摘要跟随指针，同时限制在指示器可视高度内。
 		* @param clientY 指针的视口纵坐标。
 		*/
-		const updatePreviewPosition = (index, clientY) => {
+		const updatePreviewPosition = (clientY) => {
 			const rootBounds = indicatorRoot.value?.getBoundingClientRect();
 			const viewportBounds = viewport.value?.getBoundingClientRect();
-			const marker = rail.value?.querySelectorAll(".docs-markdown-indicator__marker")[index];
-			if (!rootBounds || !viewportBounds || !marker) return;
-			const markerBounds = marker.getBoundingClientRect();
-			const relativeY = (clientY ?? markerBounds.top + markerBounds.height / 2) - rootBounds.top;
-			previewTop.value = Math.min(viewportBounds.height - 48, Math.max(48, relativeY));
+			if (!rootBounds || !viewportBounds) return;
+			previewTop.value = Math.min(viewportBounds.height - 48, Math.max(48, clientY - rootBounds.top));
 		};
 		/**
-		* 滚动到指定文档块；拖动使用即时定位，点击使用平滑定位。
-		* @param index 目标文档块序号。
+		* 按轨道比例滚动正文，不改 hash。
+		* @param ratio 轨道 0–1 比例。
 		* @param behavior 滚动行为。
 		*/
-		const scrollToMarker = (index, behavior) => {
-			const marker = markers.value[index];
-			if (!marker || !scrollHost) return;
-			const markerTop = marker.element.getBoundingClientRect().top;
-			if (usesParentScroller && parentScroller?.setScrollTop) parentScroller.setScrollTop((parentScroller.scrollTop || 0) + markerTop - getScrollHostTop() - 24);
-			else if (scrollHost instanceof HTMLElement) {
-				const hostTop = scrollHost.getBoundingClientRect().top;
+		const scrollToRatio = (ratio, behavior) => {
+			const metrics = getScrollMetrics();
+			const nextTop = ratio * Math.max(0, metrics.scrollHeight - metrics.clientHeight);
+			if (usesParentScroller && parentScroller?.setScrollTop) {
+				parentScroller.setScrollTop(nextTop);
+				return;
+			}
+			if (scrollHost instanceof HTMLElement) {
 				scrollHost.scrollTo({
-					top: scrollHost.scrollTop + markerTop - hostTop - 24,
-					behavior
+					behavior,
+					top: nextTop
 				});
-			} else window.scrollTo({
-				top: window.scrollY + markerTop - 24,
-				behavior
+				return;
+			}
+			window.scrollTo({
+				behavior,
+				top: nextTop
 			});
-			activeIndex.value = index;
-			followActiveMarker(index);
 		};
 		/**
-		* 指针移动时展示摘要；按下拖动时同步快速浏览文档。
+		* 指针移动时展示摘要；按下拖动时按比例 scrub 正文。
 		* @param event 当前指针事件。
 		*/
 		const handlePointerMove = (event) => {
-			const index = getIndexByPointer(event);
-			hoverIndex.value = index;
-			updatePreviewPosition(index, event.clientY);
-			if (dragging.value) scrollToMarker(index, "auto");
+			const ratio = getPointerRatio(event);
+			hoverIndex.value = getIndexByRatio(ratio);
+			updatePreviewPosition(event.clientY);
+			if (dragging.value) scrollToRatio(ratio, "auto");
 		};
 		/**
-		* 开始拖动指示器并定位到按下位置。
+		* 开始 scrub：点击即按比例定位，可拖动时再捕获指针。
 		* @param event 当前指针事件。
 		*/
 		const handlePointerDown = (event) => {
 			if (event.button !== 0) return;
+			const ratio = getPointerRatio(event);
+			hoverIndex.value = getIndexByRatio(ratio);
+			updatePreviewPosition(event.clientY);
+			scrollToRatio(ratio, "auto");
 			dragging.value = props.options.draggable !== false;
-			const index = getIndexByPointer(event);
-			hoverIndex.value = index;
-			updatePreviewPosition(index, event.clientY);
 			if (dragging.value) {
 				captureTarget = event.currentTarget;
 				captureTarget.setPointerCapture?.(event.pointerId);
-				scrollToMarker(index, "auto");
 				event.preventDefault();
 			}
 		};
@@ -678,96 +1115,99 @@ var indicator_default = /* @__PURE__ */ defineComponent({
 			if (!dragging.value) hoverIndex.value = void 0;
 		};
 		/**
-		* 点击单条刻度时平滑定位到对应文档块。
-		* @param index 目标文档块序号。
-		*/
-		const handleClick = (index) => {
-			hoverIndex.value = index;
-			updatePreviewPosition(index);
-			scrollToMarker(index, "smooth");
-		};
-		/**
-		* 计算刻度位置、基础宽度和靠近指针时的鱼眼展开宽度。
+		* 计算刻度在轨道上的位置、标题/正文宽度，以及靠近指针时的鱼眼展开。
 		* @param index 当前刻度序号。
 		* @returns 刻度的定位和宽度样式。
 		*/
 		const getMarkerStyle = (index) => {
+			const marker = markers.value[index];
 			const distance = typeof hoverIndex.value === "number" ? Math.abs(index - hoverIndex.value) : Number.POSITIVE_INFINITY;
-			return { width: `${distance <= 3 ? [
-				28,
-				22,
-				16,
-				10
-			][distance] : 8}px` };
+			const base = marker?.isHeading ? 10 : 6;
+			const expandedWidths = [
+				base + 6,
+				base + 4,
+				base + 2,
+				base + 1
+			];
+			const hoverWidth = distance <= 3 ? expandedWidths[distance] : base;
+			const activeWidth = index === activeIndex.value ? base + 8 : base;
+			return {
+				top: `${(marker?.ratio || 0) * 100}%`,
+				width: `${Math.max(hoverWidth, activeWidth)}px`
+			};
 		};
-		watch([() => props.target, localeName], setupTarget, { immediate: true });
-		watch([() => props.options.height, viewport], () => {
+		watch([() => props.target, localeName], setupTarget, {
+			immediate: true,
+			flush: "post"
+		});
+		watch(indicatorRoot, (root) => {
+			if (root) observeHostSize();
+		}, { flush: "post" });
+		watch([
+			() => props.options.height,
+			() => props.options.position,
+			viewport
+		], () => {
 			if (viewport.value && hostResizeObserver) hostResizeObserver.observe(viewport.value);
-			updateStickyInset();
+			updateLayout();
 		});
 		onBeforeUnmount(() => {
 			targetGeneration++;
 			cleanupTarget();
 			if (refreshFrame) cancelAnimationFrame(refreshFrame);
-			if (activeFrame) cancelAnimationFrame(activeFrame);
+			if (windowFrame) cancelAnimationFrame(windowFrame);
 		});
 		return (_ctx, _cache) => {
-			return markers.value.length > 1 ? (openBlock(), createElementBlock("aside", {
+			return markers.value.length ? (openBlock(), createElementBlock("aside", {
 				key: 0,
 				ref_key: "indicatorRoot",
 				ref: indicatorRoot,
-				class: normalizeClass(["docs-markdown-indicator", `is-${__props.options.position || "right"}`]),
+				class: normalizeClass(["docs-markdown-indicator", `is-${resolvedPosition.value}`]),
 				style: normalizeStyle(rootStyle.value),
 				"aria-label": unref(t)("markdown.indicator.label")
 			}, [createElementVNode("div", {
 				ref_key: "viewport",
 				ref: viewport,
-				class: "docs-markdown-indicator__viewport",
+				class: normalizeClass(["docs-markdown-indicator__viewport", { "is-dragging": dragging.value }]),
+				role: "slider",
+				"aria-orientation": "vertical",
+				"aria-valuemin": 0,
+				"aria-valuemax": 100,
+				"aria-valuenow": scrollProgress.value,
+				"aria-valuetext": `${scrollProgress.value}%`,
+				style: normalizeStyle(viewportStyle.value),
 				onPointermove: handlePointerMove,
 				onPointerleave: handlePointerLeave,
 				onPointerdown: handlePointerDown,
 				onPointerup: handlePointerUp,
 				onPointercancel: handlePointerUp
-			}, [createVNode(unref(Scroller), {
-				ref_key: "indicatorScroller",
-				ref: indicatorScroller,
-				class: "docs-markdown-indicator__scroller",
-				"auto-resize": true,
-				native: false,
-				"show-bar": true,
-				height: "100%",
-				"wrapper-style": "overflow-x: hidden;"
-			}, {
-				default: withCtx(() => [createElementVNode("div", {
-					ref_key: "rail",
-					ref: rail,
-					class: "docs-markdown-indicator__rail"
-				}, [createElementVNode("div", _hoisted_2, [(openBlock(true), createElementBlock(Fragment, null, renderList(markers.value, (marker, index) => {
-					return openBlock(), createElementBlock("button", {
-						key: marker.id,
-						type: "button",
-						class: normalizeClass(["docs-markdown-indicator__marker", {
-							"is-active": index === activeIndex.value,
-							"is-hovered": index === hoverIndex.value
-						}]),
-						style: normalizeStyle(getMarkerStyle(index)),
-						"aria-label": marker.ariaLabel,
-						onClick: ($event) => handleClick(index)
-					}, null, 14, _hoisted_3);
-				}), 128))])], 512)]),
-				_: 1
-			}, 512)], 544), __props.options.preview !== false && hoveredMarker.value ? (openBlock(), createElementBlock("div", {
+			}, [createElementVNode("div", {
+				ref_key: "rail",
+				ref: rail,
+				class: "docs-markdown-indicator__rail"
+			}, [createElementVNode("div", {
+				class: "docs-markdown-indicator__window",
+				style: normalizeStyle(windowStyle.value)
+			}, null, 4), (openBlock(true), createElementBlock(Fragment, null, renderList(markers.value, (marker, index) => {
+				return openBlock(), createElementBlock("div", {
+					key: marker.id,
+					class: normalizeClass(["docs-markdown-indicator__marker", {
+						"is-heading": marker.isHeading,
+						"is-hovered": index === hoverIndex.value,
+						"is-active": index === activeIndex.value,
+						"is-in-view": isMarkerInView(index)
+					}]),
+					style: normalizeStyle(getMarkerStyle(index))
+				}, null, 6);
+			}), 128))], 512)], 46, _hoisted_2), __props.options.preview !== false && !dragging.value && hoveredMarker.value ? (openBlock(), createElementBlock("div", {
 				key: 0,
 				class: "docs-markdown-indicator__preview",
 				style: normalizeStyle(previewStyle.value)
-			}, [createElementVNode("div", _hoisted_4, toDisplayString(hoveredMarker.value.title), 1), hoveredMarker.value.content ? (openBlock(), createElementBlock("div", _hoisted_5, toDisplayString(hoveredMarker.value.content), 1)) : createCommentVNode("v-if", true)], 4)) : createCommentVNode("v-if", true)], 14, _hoisted_1$1)) : createCommentVNode("v-if", true);
+			}, [createElementVNode("div", _hoisted_3, toDisplayString(hoveredMarker.value.title), 1), hoveredMarker.value.content ? (openBlock(), createElementBlock("div", _hoisted_4, toDisplayString(hoveredMarker.value.content), 1)) : createCommentVNode("v-if", true)], 4)) : createCommentVNode("v-if", true)], 14, _hoisted_1)) : createCommentVNode("v-if", true);
 		};
 	}
 });
 //#endregion
-//#region packages/markdown/src/wrapper.vue?vue&type=script&setup=true&lang.ts
-var _hoisted_1 = { class: "docs-markdown" };
-//#endregion
 //#region packages/markdown/src/wrapper.vue
 var wrapper_default = /* @__PURE__ */ defineComponent({
 	__name: "wrapper",
@@ -777,6 +1217,9 @@ var wrapper_default = /* @__PURE__ */ defineComponent({
 			default: true
 		},
 		locale: {},
+		theme: { default: "default" },
+		playground: { default: () => ({}) },
+		tabQuery: {},
 		modelValue: {},
 		value: {}
 	},
@@ -791,13 +1234,19 @@ var wrapper_default = /* @__PURE__ */ defineComponent({
 			if (props.indicator === false) return void 0;
 			return typeof props.indicator === "object" ? props.indicator : {};
 		});
+		const resolvedTheme = computed(() => props.theme === "traditional" ? "traditional" : "default");
+		const injectedTabQuery = inject(markdownTabQueryKey, null);
+		const historyTabQuery = createHistoryTabQueryAdapter();
+		const resolvedTabQuery = computed(() => props.tabQuery || injectedTabQuery || historyTabQuery);
 		const source = computed(() => typeof props.modelValue === "string" ? props.modelValue : props.value);
 		const markdownBinding = computed(() => ({
 			source: source.value,
-			locale: locale.value
+			locale: locale.value,
+			playground: props.playground,
+			tabQuery: resolvedTabQuery.value
 		}));
 		return (_ctx, _cache) => {
-			return openBlock(), createElementBlock("div", _hoisted_1, [indicatorOptions.value ? (openBlock(), createBlock(indicator_default, {
+			return openBlock(), createElementBlock("div", { class: normalizeClass(["docs-markdown", `docs-markdown--${resolvedTheme.value}`]) }, [indicatorOptions.value && content.value ? (openBlock(), createBlock(indicator_default, {
 				key: 0,
 				target: content.value,
 				options: indicatorOptions.value
@@ -805,9 +1254,9 @@ var wrapper_default = /* @__PURE__ */ defineComponent({
 				ref_key: "content",
 				ref: content,
 				class: "docs-markdown-reset"
-			}, null, 512), [[unref(vMarkdown), markdownBinding.value]])]);
+			}, null, 512), [[unref(vMarkdown), markdownBinding.value]])], 2);
 		};
 	}
 });
 //#endregion
-export { wrapper_default as Markdown, parseMarkdownSearchSections };
+export { wrapper_default as Markdown, collectMarkdownHeadings, createHistoryTabQueryAdapter, getMarkdownHeadingTitle, markdownTabQueryKey, parseMarkdownSearchSections, toMarkdownTabId };