fix(website): address shared viewer review feedback

.agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.md
-2026-09-14-docs-mermaid-viewer.md: 03aecb7b4df1c79d2eb254375f6b2c68145079ac
-2026-09-14-docs-mermaid-viewer.zh.md: b66f427a4820eef0d6fa25b163cfc8e3548ec0c6
+2026-09-14-docs-mermaid-viewer.md: 5cb4bae84fcafb49c559b7678e9a9dc1aa961ab0
+2026-09-14-docs-mermaid-viewer.zh.md: 665ab65e48e15651ebb9323e96e6a950c0b48deb

.agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.md

@@ -1,4 +1,4 @@
-# Agent Note: Documentation Mermaid viewer
+# Agent Note: Documentation diagram and image viewer
 
 Status: implemented
 
@@ -6,15 +6,17 @@ English | [中文](2026-09-14-docs-mermaid-viewer.zh.md)
 
 ## Problem
 
-Complex Mermaid diagrams lose readable detail when scaled to the documentation column. Long sequence diagrams need both magnification and movement to inspect interactions while retaining an overview.
+Complex Mermaid diagrams and interface screenshots lose readable detail when scaled to the documentation column. Readers need both magnification and movement to inspect interactions while retaining an overview.
 
 ## Decision
 
 The [VitePress theme](../../../../website/.vitepress/theme/index.ts) adds a corner fullscreen icon to each rendered Mermaid SVG. A native modal dialog provides an inert background and Escape dismissal. Its visible title also names it for assistive technology; a missing or blank page heading uses the localized viewer title. A floating toolbar groups zoom controls, the current scale, and fit; close stays in the top corner, and help opens on demand. Keyboard focus cycles through all five buttons. Panzoom supplies pointer, wheel, and pinch interaction. Arrow keys pan in fixed screen distances. Closing restores the entry's focus without scrolling and restores the page's previous overflow setting.
 
+Ordinary images share one modal and zoom controller with Mermaid. Loaded images with nonempty alt text that occupy their own paragraph open through an image click or corner button; linked, inline, decorative, and `data-no-zoom` images retain their existing interaction. Image alt text names the modal, and the scale button returns to centered natural size (100%) while its accessible name also includes the current scale; keyboard focus cycles through six buttons in image views.
+
 The viewer copies the SVG into a shadow root. Mermaid's embedded selectors and fragment IDs stay local to the copy, so its markers and styles cannot resolve against the original diagram. Panzoom transforms a viewport-sized canvas containing the SVG at its natural viewBox dimensions, so pointer coordinates and the transform origin share the same center; the initial scale and every resize fit the entire diagram without enlarging it beyond its natural size. This preserves vector detail while keeping fit independent of the narrow document column. The canvas has no visible frame; reserved space keeps controls clear of the fitted diagram.
 
-Viewer resources belong to the mounted theme. Route, language, theme, and source-SVG replacement close the active view; asynchronous Mermaid renders receive a fresh entry. The body overflow lock relies on the default theme retaining visible overflow on the HTML element. It avoids mutating HTML attributes, which the Mermaid plugin observes and rerenders in response. The [implementation](../../../../website/.vitepress/theme/mermaid-viewer.ts) leaves Markdown, raw page copies, and `llms.txt` generation with their existing owners.
+Viewer resources belong to the mounted theme. Route, language, theme, and source-content replacement close the active view; asynchronous Mermaid renders and loaded images receive fresh entries. The body overflow lock relies on the default theme retaining visible overflow on the HTML element. It avoids mutating HTML attributes, which the Mermaid plugin observes and rerenders in response. The [shared modal](../../../../website/.vitepress/theme/media-viewer.ts), [Mermaid adapter](../../../../website/.vitepress/theme/mermaid-viewer.ts), and [image adapter](../../../../website/.vitepress/theme/image-viewer.ts) leave Markdown, raw page copies, and `llms.txt` generation with their existing owners.
 
 ## Alternatives considered
 
@@ -26,8 +28,8 @@ Viewer resources belong to the mounted theme. Route, language, theme, and source
 
 ## Consequences
 
-The website gains Panzoom as a direct dependency and uses native dialog, shadow-root, and resize-observer support. Viewer zoom and position are transient: resizing refits the diagram, and navigating or changing the theme closes it. Existing page diagrams remain the reading and link-navigation source.
+The website gains Panzoom as a direct dependency and uses native dialog, shadow-root, and resize-observer support. Viewer zoom and position are transient: resizing refits the content, and navigating or changing the theme closes it. Existing page images and diagrams remain the reading and link-navigation source.
 
-The [focused tests](../../../../website/tests/mermaid-viewer.spec.ts) run in the root unit-test suite; `docs:check` and `doc-sync` also select them so documentation-only validation exercises the viewer. They cover late rendering, accessible titles, initial and resized fit, control wiring, keyboard cycling, replacement, and resource release.
+The [Mermaid tests](../../../../website/tests/mermaid-viewer.spec.ts) and [image tests](../../../../website/tests/image-viewer.spec.ts) run in the root unit-test suite; `docs:check` and `doc-sync` also select them so documentation-only validation exercises the viewer. They cover late rendering and loading, accessible names, initial and resized fit, the 100% action, keyboard cycling, switching between images and diagrams, source replacement, and resource release.
 
 **CI coverage gap.** The DOM tests mock Panzoom and do not execute browser layout. Native modal behavior, SVG markers, pointer-anchored wheel zoom, canvas dragging, theme colors, and narrow-screen geometry require real-browser verification. The recorded browser demonstration supplies evidence for the current implementation, but it is not an automated regression check.

.agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.zh.md

@@ -1,4 +1,4 @@
-# Agent Note: 文档站 Mermaid 查看器
+# Agent Note: 文档站图表与图片查看器
 
 Status: implemented
 
@@ -6,15 +6,17 @@ Status: implemented
 
 ## 问题
 
-复杂 Mermaid 图表缩放到文档正文列宽后，细节难以辨认。阅读长时序图需要在保留全图概览的同时放大和平移，以检查交互细节。
+复杂 Mermaid 图表和界面截图缩放到文档正文列宽后，细节难以辨认。阅读时需要在保留全图概览的同时放大和平移，以检查交互细节。
 
 ## 决策
 
 [VitePress 主题](../../../../website/.vitepress/theme/index.ts) 在每张已渲染的 Mermaid SVG 角落增加全屏图标。原生模态对话框使背景不可交互，并支持 Escape 退出。可见标题也用于辅助技术识别对话框；页面标题缺失或为空白时，使用本地化的查看器标题。浮动工具栏集中显示缩放控件、当前比例和适应窗口操作；关闭按钮位于顶部角落，帮助按需展开。键盘焦点在五个按钮之间循环。Panzoom 提供指针、滚轮和双指交互。方向键按固定的屏幕距离平移。关闭时恢复入口焦点且不滚动页面，并恢复页面原有的 overflow 设置。
 
+普通图片与 Mermaid 共用一个弹层和缩放控制器。已加载、具有非空 alt 文本且独占段落的图片支持点击图片或角落按钮打开；链接图片、行内图片、装饰图片和 `data-no-zoom` 图片保留原有交互。图片的 alt 文本作为弹层标题，比例按钮返回并居中显示自然尺寸（100%），其辅助名称同时包含当前比例；图片视图的键盘焦点在六个按钮之间循环。
+
 查看器将 SVG 复制到 shadow root 中。Mermaid 内嵌的选择器和片段 ID 限定在副本内部，因此副本的标记和样式不会解析到原始图表上。Panzoom 变换与视口等大的画布，其中的 SVG 使用 viewBox 的自然尺寸，使指针坐标与变换原点共享同一个中心；初始缩放以及每次窗口尺寸变化都会适配整张图表，且不会放大到超出自然尺寸。这样既保留矢量细节，也使适配不受文档窄列宽度的影响。画布没有可见边框；预留空间使控件不会遮挡适配后的图表。
 
-查看器资源由已挂载的主题持有。路由、语言、主题和源 SVG 替换都会关闭当前视图；异步渲染的 Mermaid 图表会获得新的入口。body 的 overflow 滚动锁依赖默认主题让 HTML 元素保持 visible overflow。它避免修改 HTML 属性，因为 Mermaid 插件会观察这些属性并重新渲染。[实现](../../../../website/.vitepress/theme/mermaid-viewer.ts) 将 Markdown、原始页面副本和 `llms.txt` 的生成保留在原有归属处。
+查看器资源由已挂载的主题持有。路由、语言、主题和源内容替换都会关闭当前视图；异步渲染的 Mermaid 图表和加载完成的图片会获得新的入口。body 的 overflow 滚动锁依赖默认主题让 HTML 元素保持 visible overflow。它避免修改 HTML 属性，因为 Mermaid 插件会观察这些属性并重新渲染。[共享弹层](../../../../website/.vitepress/theme/media-viewer.ts)、[Mermaid 适配器](../../../../website/.vitepress/theme/mermaid-viewer.ts) 与[图片适配器](../../../../website/.vitepress/theme/image-viewer.ts) 将 Markdown、原始页面副本和 `llms.txt` 的生成保留在原有归属处。
 
 ## 考虑过的替代方案
 
@@ -26,8 +28,8 @@ Status: implemented
 
 ## 影响
 
-文档站增加了 Panzoom 直接依赖，并使用原生 dialog、shadow root 和 ResizeObserver 支持。查看器的缩放和平移状态是临时的：窗口尺寸变化会重新适配图表，导航或主题变化会关闭视图。原有页面图表仍然是阅读和链接导航的来源。
+文档站增加了 Panzoom 直接依赖，并使用原生 dialog、shadow root 和 ResizeObserver 支持。查看器的缩放和平移状态是临时的：窗口尺寸变化会重新适配内容，导航或主题变化会关闭视图。原有页面图片和图表仍然是阅读和链接导航的来源。
 
-[定向测试](../../../../website/tests/mermaid-viewer.spec.ts) 属于根单元测试集；`docs:check` 和 `doc-sync`（文档同步门禁）也会选中这些测试，使仅运行文档验证时同样覆盖查看器。它们验证延迟渲染、无障碍标题、初始及窗口变化后的适配、控件连接、键盘焦点循环、图表替换和资源释放。
+[Mermaid 测试](../../../../website/tests/mermaid-viewer.spec.ts) 与[图片测试](../../../../website/tests/image-viewer.spec.ts) 属于根单元测试集；`docs:check` 和 `doc-sync`（文档同步门禁）也会选中这些测试，使仅运行文档验证时同样覆盖查看器。它们验证延迟渲染和加载、无障碍名称、初始及窗口变化后的适配、100% 操作、键盘焦点循环、图片与图表互相切换、源内容替换和资源释放。
 
 **CI 覆盖缺口。** DOM 测试模拟了 Panzoom，不执行浏览器布局。原生模态行为、SVG 标记、以指针为锚点的滚轮缩放、画布拖动、主题颜色和窄屏几何布局需要真实浏览器验证。浏览器演示记录提供了当前实现的证据，但不属于自动回归检查。

website/.vitepress/theme/image-viewer.ts

@@ -2,8 +2,8 @@
 import { labelButton, type MediaViewer, viewerButton } from './media-viewer.ts'
 
 const messages = {
-  en: 'View image fullscreen',
-  zh: '全屏查看图片',
+  en: 'View image fullscreen: {alt}',
+  zh: '全屏查看图片：{alt}',
 }
 
 interface ImageEntry {
@@ -89,7 +89,7 @@ export class ImageViewer {
     }
     const copy = this.language().startsWith('zh') ? messages.zh : messages.en
     for (const image of images) {
-      const label = `${copy}: ${image.alt}`
+      const label = copy.replace('{alt}', () => image.alt)
       const existing = this.#entries.get(image)
       if (existing) {
         if (existing.button.getAttribute('aria-label') !== label) labelButton(existing.button, label)

website/.vitepress/theme/media-viewer.css

@@ -5,7 +5,7 @@
 
 .vp-doc .dsh-diagram-open,
 .vp-doc .dsh-image-open,
-.dsh-diagram-viewer button {
+.dsh-media-viewer button {
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -26,7 +26,7 @@
   right: 0;
 }
 
-.dsh-diagram-icon {
+.dsh-media-icon {
   width: 20px;
   height: 20px;
   fill: none;
@@ -38,20 +38,20 @@
 
 .dsh-diagram-open:hover,
 .dsh-image-open:hover,
-.dsh-diagram-viewer button:hover,
-.dsh-diagram-viewer button[aria-expanded="true"] {
+.dsh-media-viewer button:hover,
+.dsh-media-viewer button[aria-expanded="true"] {
   color: var(--vp-c-brand-1);
   background: var(--vp-c-bg-soft);
 }
 
 .dsh-diagram-open:focus-visible,
 .dsh-image-open:focus-visible,
-.dsh-diagram-viewer button:focus-visible {
+.dsh-media-viewer button:focus-visible {
   outline: 2px solid var(--vp-c-brand-1);
   outline-offset: 2px;
 }
 
-.dsh-diagram-viewer {
+.dsh-media-viewer {
   position: fixed;
   inset: 0;
   width: 100%;
@@ -67,7 +67,7 @@
   box-sizing: border-box;
 }
 
-.dsh-diagram-title {
+.dsh-media-title {
   position: absolute;
   top: 24px;
   left: 24px;
@@ -79,9 +79,9 @@
   font-size: 13px;
 }
 
-.dsh-diagram-close { position: absolute; top: 12px; right: 16px; }
+.dsh-media-close { position: absolute; top: 12px; right: 16px; }
 
-.dsh-diagram-toolbar {
+.dsh-media-toolbar {
   position: absolute;
   bottom: 20px;
   left: 50%;
@@ -96,7 +96,7 @@
   box-shadow: 0 3px 12px #0000000a;
 }
 
-.dsh-diagram-scale {
+.dsh-media-scale {
   min-width: 48px;
   text-align: center;
   color: var(--vp-c-text-2);
@@ -104,16 +104,16 @@
   font-variant-numeric: tabular-nums;
 }
 
-.dsh-diagram-toolbar .dsh-diagram-fit {
+.dsh-media-toolbar .dsh-media-fit {
   margin-left: 6px;
   border-left: 1px solid var(--vp-c-divider);
   border-top-left-radius: 0;
   border-bottom-left-radius: 0;
 }
 
-.dsh-diagram-help-toggle { position: absolute; bottom: 25px; right: 16px; }
+.dsh-media-help-toggle { position: absolute; bottom: 25px; right: 16px; }
 
-.dsh-diagram-help {
+.dsh-media-help {
   position: absolute;
   right: 16px;
   bottom: 80px;
@@ -127,21 +127,21 @@
   font-size: 13px;
 }
 
-.dsh-diagram-viewport {
+.dsh-media-viewport {
   position: absolute;
   inset: 64px 16px 88px;
   overflow: hidden;
   overscroll-behavior: contain;
 }
 
-.dsh-diagram-paper { position: absolute; inset: 0; }
+.dsh-media-paper { position: absolute; inset: 0; }
 
 @media (max-width: 600px) {
-  .dsh-diagram-title { top: 20px; left: 16px; }
-  .dsh-diagram-close { top: 8px; right: 8px; }
-  .dsh-diagram-viewport { inset: 56px 8px 80px; }
-  .dsh-diagram-toolbar { bottom: 12px; }
-  .dsh-diagram-help-toggle { right: 8px; bottom: 17px; }
+  .dsh-media-title { top: 20px; left: 16px; }
+  .dsh-media-close { top: 8px; right: 8px; }
+  .dsh-media-viewport { inset: 56px 8px 80px; }
+  .dsh-media-toolbar { bottom: 12px; }
+  .dsh-media-help-toggle { right: 8px; bottom: 17px; }
 }
 
 .vp-doc .dsh-image-container { position: relative; width: fit-content; max-width: 100%; }

website/.vitepress/theme/media-viewer.ts

@@ -3,12 +3,12 @@ import Panzoom from '@panzoom/panzoom'
 
 const messages = {
   en: {
-    zoomIn: 'Zoom in', zoomOut: 'Zoom out', fit: 'Fit view', original: 'Original size (100%)',
+    zoomIn: 'Zoom in', zoomOut: 'Zoom out', fit: 'Fit view', original: 'Original size (100%), currently {scale}',
     close: 'Close', helpLabel: 'Viewer help',
     help: 'Scroll or pinch to zoom · Drag or use arrow keys to pan · Esc to close',
   },
   zh: {
-    zoomIn: '放大', zoomOut: '缩小', fit: '适应窗口', original: '原始尺寸（100%）',
+    zoomIn: '放大', zoomOut: '缩小', fit: '适应窗口', original: '原始尺寸（100%），当前{scale}',
     close: '关闭', helpLabel: '查看器帮助',
     help: '滚轮或双指缩放 · 拖动或方向键平移 · Esc 关闭',
   },
@@ -44,7 +44,7 @@ export function viewerButton(doc: Document, label: string, icon: keyof typeof ic
   element.type = 'button'
   labelButton(element, label)
   const svg = doc.createElementNS('http://www.w3.org/2000/svg', 'svg')
-  svg.classList.add('dsh-diagram-icon')
+  svg.classList.add('dsh-media-icon')
   svg.setAttribute('viewBox', '0 0 24 24')
   svg.setAttribute('aria-hidden', 'true')
   svg.setAttribute('focusable', 'false')
@@ -91,44 +91,41 @@ export class MediaViewer {
     const doc = this.doc
     const copy = this.language().startsWith('zh') ? messages.zh : messages.en
     const dialog = doc.createElement('dialog')
-    dialog.className = 'dsh-diagram-viewer'
-    dialog.setAttribute('aria-labelledby', 'dsh-diagram-title')
+    dialog.className = 'dsh-media-viewer'
+    dialog.setAttribute('aria-labelledby', 'dsh-media-title')
     const toolbar = doc.createElement('div')
-    toolbar.className = 'dsh-diagram-toolbar'
+    toolbar.className = 'dsh-media-toolbar'
     const title = doc.createElement('span')
-    title.className = 'dsh-diagram-title'
-    title.id = 'dsh-diagram-title'
+    title.className = 'dsh-media-title'
+    title.id = 'dsh-media-title'
     title.textContent = content.title
     const zoomOut = viewerButton(doc, copy.zoomOut, 'zoomOut')
     const zoomIn = viewerButton(doc, copy.zoomIn, 'zoomIn')
     const original = content.originalSize ? doc.createElement('button') : undefined
-    if (original) {
-      original.type = 'button'
-      labelButton(original, copy.original)
-    }
+    if (original) original.type = 'button'
     const scaleLabel = original ?? doc.createElement('span')
-    scaleLabel.className = 'dsh-diagram-scale'
+    scaleLabel.className = 'dsh-media-scale'
     const fit = viewerButton(doc, copy.fit, 'fit')
-    fit.className = 'dsh-diagram-fit'
+    fit.className = 'dsh-media-fit'
     const close = viewerButton(doc, copy.close, 'close')
-    close.className = 'dsh-diagram-close'
+    close.className = 'dsh-media-close'
     close.autofocus = true
     toolbar.append(zoomOut, scaleLabel, zoomIn, fit)
     const helpToggle = viewerButton(doc, copy.helpLabel, 'help')
-    helpToggle.className = 'dsh-diagram-help-toggle'
+    helpToggle.className = 'dsh-media-help-toggle'
     helpToggle.setAttribute('aria-expanded', 'false')
-    helpToggle.setAttribute('aria-controls', 'dsh-diagram-help-text')
+    helpToggle.setAttribute('aria-controls', 'dsh-media-help-text')
     const help = doc.createElement('p')
-    help.className = 'dsh-diagram-help'
-    help.id = 'dsh-diagram-help-text'
+    help.className = 'dsh-media-help'
+    help.id = 'dsh-media-help-text'
     help.hidden = true
     help.textContent = copy.help
     const viewport = doc.createElement('div')
-    viewport.className = 'dsh-diagram-viewport'
+    viewport.className = 'dsh-media-viewport'
     const paper = doc.createElement('div')
-    paper.className = 'dsh-diagram-paper'
-    // Each Mermaid SVG embeds ID-scoped styles and fragment references. A shadow root
-    // keeps the enlarged copy's IDs and styles separate from the original diagram.
+    paper.className = 'dsh-media-paper'
+    // Shared content lives in a shadow root so Mermaid copies cannot resolve their
+    // embedded styles and fragment IDs against the original diagram.
     const shadow = paper.attachShadow({ mode: 'open' })
     const clone = content.element
     Object.assign(clone.style, {
@@ -178,7 +175,11 @@ export class MediaViewer {
         controller.pan(0, 0, { animate: false })
       }
       const options = { signal: listeners.signal }
-      const updateScale = (): void => { scaleLabel.textContent = `${Math.round(controller.getScale() * 100)}%` }
+      const updateScale = (): void => {
+        const scale = `${Math.round(controller.getScale() * 100)}%`
+        scaleLabel.textContent = scale
+        if (original) labelButton(original, copy.original.replace('{scale}', scale))
+      }
       updateScale()
       paper.addEventListener('panzoomchange', updateScale, options)
       helpToggle.addEventListener('click', () => {

website/.vitepress/theme/mermaid-viewer.ts

@@ -1,5 +1,5 @@
 /** Full-viewport viewing of asynchronously rendered documentation diagrams. */
-import { labelButton, MediaViewer, viewerButton } from './media-viewer.ts'
+import { labelButton, type MediaViewer, viewerButton } from './media-viewer.ts'
 
 const messages = {
   en: { open: 'View diagram fullscreen', title: 'Diagram viewer' },
@@ -26,11 +26,11 @@ function dimensions(svg: SVGSVGElement): { width: number; height: number } | und
  * Enhance rendered Mermaid SVGs without modifying the canonical Markdown or renderer.
  * @param doc Browser document containing VitePress content.
  * @param language Current VitePress language, read again when entries refresh.
- * @param viewer Shared modal owner; defaults to a diagram-only owner when omitted.
+ * @param viewer Shared modal owner for images and diagrams.
  * @returns Resources owned by the mounted theme.
  */
 export function installMermaidViewer(
-  doc: Document, language: () => string, viewer: Pick<MediaViewer, 'open'> = new MediaViewer(doc, language),
+  doc: Document, language: () => string, viewer: Pick<MediaViewer, 'open'>,
 ): MermaidViewer {
   const entries = new Map<Element, { svg: SVGSVGElement; button: HTMLButtonElement }>()
   let active: SVGSVGElement | undefined
@@ -44,7 +44,7 @@ export function installMermaidViewer(
     const copy = language().startsWith('zh') ? messages.zh : messages.en
     const containers = new Set(doc.querySelectorAll('.vp-doc .mermaid'))
     for (const [container, entry] of entries) {
-      if (!containers.has(container) || container.querySelector('svg:not(.dsh-diagram-icon)') !== entry.svg || !entry.button.isConnected) {
+      if (!containers.has(container) || container.querySelector('svg:not(.dsh-media-icon)') !== entry.svg || !entry.button.isConnected) {
         if (entry.svg === active) closeActive()
         entry.button.remove()
         entries.delete(container)
@@ -56,7 +56,7 @@ export function installMermaidViewer(
         if (existing.button.getAttribute('aria-label') !== copy.open) labelButton(existing.button, copy.open)
         continue
       }
-      const svg = container.querySelector<SVGSVGElement>('svg:not(.dsh-diagram-icon)')
+      const svg = container.querySelector<SVGSVGElement>('svg:not(.dsh-media-icon)')
       if (!svg || !dimensions(svg)) continue
       const trigger = viewerButton(doc, copy.open, 'open')
       trigger.className = 'dsh-diagram-open'

website/tests/expected/image-viewer.en-US.html

@@ -1,3 +1,3 @@
-<button type="button" aria-label="View image fullscreen: DeepSeek API settings" title="View image fullscreen: DeepSeek API settings" class="dsh-image-open" aria-haspopup="dialog"><svg class="dsh-diagram-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M14 4h6v6M20 4l-7 7M10 20H4v-6M4 20l7-7"></path></svg></button>
-<dialog class="dsh-diagram-viewer" aria-labelledby="dsh-diagram-title" open=""><div class="dsh-diagram-viewport"><div class="dsh-diagram-paper"></div></div><span class="dsh-diagram-title" id="dsh-diagram-title">DeepSeek API settings</span><button type="button" aria-label="Close" title="Close" class="dsh-diagram-close" autofocus=""><svg class="dsh-diagram-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M6 6l12 12M18 6 6 18"></path></svg></button><div class="dsh-diagram-toolbar"><button type="button" aria-label="Zoom out" title="Zoom out"><svg class="dsh-diagram-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M5 12h14"></path></svg></button><button type="button" aria-label="Original size (100%)" title="Original size (100%)" class="dsh-diagram-scale">63%</button><button type="button" aria-label="Zoom in" title="Zoom in"><svg class="dsh-diagram-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M5 12h14M12 5v14"></path></svg></button><button type="button" aria-label="Fit view" title="Fit view" class="dsh-diagram-fit"><svg class="dsh-diagram-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M9 4H4v5M15 4h5v5M4 15v5h5M20 15v5h-5"></path></svg></button></div><button type="button" aria-label="Viewer help" title="Viewer help" class="dsh-diagram-help-toggle" aria-expanded="false" aria-controls="dsh-diagram-help-text"><svg class="dsh-diagram-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M9.1 8a3 3 0 0 1 5.8 1c0 2-3 2-3 4M12 17v.1"></path></svg></button><p class="dsh-diagram-help" id="dsh-diagram-help-text" hidden="">Scroll or pinch to zoom · Drag or use arrow keys to pan · Esc to close</p></dialog>
+<button type="button" aria-label="View image fullscreen: DeepSeek API settings" title="View image fullscreen: DeepSeek API settings" class="dsh-image-open" aria-haspopup="dialog"><svg class="dsh-media-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M14 4h6v6M20 4l-7 7M10 20H4v-6M4 20l7-7"></path></svg></button>
+<dialog class="dsh-media-viewer" aria-labelledby="dsh-media-title" open=""><div class="dsh-media-viewport"><div class="dsh-media-paper"></div></div><span class="dsh-media-title" id="dsh-media-title">DeepSeek API settings</span><button type="button" aria-label="Close" title="Close" class="dsh-media-close" autofocus=""><svg class="dsh-media-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M6 6l12 12M18 6 6 18"></path></svg></button><div class="dsh-media-toolbar"><button type="button" aria-label="Zoom out" title="Zoom out"><svg class="dsh-media-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M5 12h14"></path></svg></button><button type="button" class="dsh-media-scale" aria-label="Original size (100%), currently 63%" title="Original size (100%), currently 63%">63%</button><button type="button" aria-label="Zoom in" title="Zoom in"><svg class="dsh-media-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M5 12h14M12 5v14"></path></svg></button><button type="button" aria-label="Fit view" title="Fit view" class="dsh-media-fit"><svg class="dsh-media-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M9 4H4v5M15 4h5v5M4 15v5h5M20 15v5h-5"></path></svg></button></div><button type="button" aria-label="Viewer help" title="Viewer help" class="dsh-media-help-toggle" aria-expanded="false" aria-controls="dsh-media-help-text"><svg class="dsh-media-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M9.1 8a3 3 0 0 1 5.8 1c0 2-3 2-3 4M12 17v.1"></path></svg></button><p class="dsh-media-help" id="dsh-media-help-text" hidden="">Scroll or pinch to zoom · Drag or use arrow keys to pan · Esc to close</p></dialog>
 <img src="https://docs.example/provider@2x.png" alt="DeepSeek API settings" draggable="false" style="position: absolute; left: 50%; top: 50%; transform: translate(-50%, -50%); width: 1600px; height: 800px; max-width: none; display: block;">

website/tests/expected/image-viewer.zh-CN.html

@@ -1,3 +1,3 @@
-<button type="button" aria-label="全屏查看图片: DeepSeek API 配置" title="全屏查看图片: DeepSeek API 配置" class="dsh-image-open" aria-haspopup="dialog"><svg class="dsh-diagram-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M14 4h6v6M20 4l-7 7M10 20H4v-6M4 20l7-7"></path></svg></button>
-<dialog class="dsh-diagram-viewer" aria-labelledby="dsh-diagram-title" open=""><div class="dsh-diagram-viewport"><div class="dsh-diagram-paper"></div></div><span class="dsh-diagram-title" id="dsh-diagram-title">DeepSeek API 配置</span><button type="button" aria-label="关闭" title="关闭" class="dsh-diagram-close" autofocus=""><svg class="dsh-diagram-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M6 6l12 12M18 6 6 18"></path></svg></button><div class="dsh-diagram-toolbar"><button type="button" aria-label="缩小" title="缩小"><svg class="dsh-diagram-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M5 12h14"></path></svg></button><button type="button" aria-label="原始尺寸（100%）" title="原始尺寸（100%）" class="dsh-diagram-scale">63%</button><button type="button" aria-label="放大" title="放大"><svg class="dsh-diagram-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M5 12h14M12 5v14"></path></svg></button><button type="button" aria-label="适应窗口" title="适应窗口" class="dsh-diagram-fit"><svg class="dsh-diagram-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M9 4H4v5M15 4h5v5M4 15v5h5M20 15v5h-5"></path></svg></button></div><button type="button" aria-label="查看器帮助" title="查看器帮助" class="dsh-diagram-help-toggle" aria-expanded="false" aria-controls="dsh-diagram-help-text"><svg class="dsh-diagram-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M9.1 8a3 3 0 0 1 5.8 1c0 2-3 2-3 4M12 17v.1"></path></svg></button><p class="dsh-diagram-help" id="dsh-diagram-help-text" hidden="">滚轮或双指缩放 · 拖动或方向键平移 · Esc 关闭</p></dialog>
+<button type="button" aria-label="全屏查看图片：DeepSeek API 配置" title="全屏查看图片：DeepSeek API 配置" class="dsh-image-open" aria-haspopup="dialog"><svg class="dsh-media-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M14 4h6v6M20 4l-7 7M10 20H4v-6M4 20l7-7"></path></svg></button>
+<dialog class="dsh-media-viewer" aria-labelledby="dsh-media-title" open=""><div class="dsh-media-viewport"><div class="dsh-media-paper"></div></div><span class="dsh-media-title" id="dsh-media-title">DeepSeek API 配置</span><button type="button" aria-label="关闭" title="关闭" class="dsh-media-close" autofocus=""><svg class="dsh-media-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M6 6l12 12M18 6 6 18"></path></svg></button><div class="dsh-media-toolbar"><button type="button" aria-label="缩小" title="缩小"><svg class="dsh-media-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M5 12h14"></path></svg></button><button type="button" class="dsh-media-scale" aria-label="原始尺寸（100%），当前63%" title="原始尺寸（100%），当前63%">63%</button><button type="button" aria-label="放大" title="放大"><svg class="dsh-media-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M5 12h14M12 5v14"></path></svg></button><button type="button" aria-label="适应窗口" title="适应窗口" class="dsh-media-fit"><svg class="dsh-media-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M9 4H4v5M15 4h5v5M4 15v5h5M20 15v5h-5"></path></svg></button></div><button type="button" aria-label="查看器帮助" title="查看器帮助" class="dsh-media-help-toggle" aria-expanded="false" aria-controls="dsh-media-help-text"><svg class="dsh-media-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M9.1 8a3 3 0 0 1 5.8 1c0 2-3 2-3 4M12 17v.1"></path></svg></button><p class="dsh-media-help" id="dsh-media-help-text" hidden="">滚轮或双指缩放 · 拖动或方向键平移 · Esc 关闭</p></dialog>
 <img src="https://docs.example/provider@2x.png" alt="DeepSeek API 配置" draggable="false" style="position: absolute; left: 50%; top: 50%; transform: translate(-50%, -50%); width: 1600px; height: 800px; max-width: none; display: block;">

website/tests/image-viewer.spec.ts

@@ -115,7 +115,7 @@ function open(): HTMLDialogElement {
 }
 
 function enlarged(dialog: HTMLElement): HTMLImageElement {
-  return required(dialog.querySelector('.dsh-diagram-paper')?.shadowRoot?.querySelector('img'))
+  return required(dialog.querySelector('.dsh-media-paper')?.shadowRoot?.querySelector('img'))
 }
 
 describe('documentation image viewer', () => {
@@ -167,7 +167,7 @@ describe('documentation image viewer', () => {
 
   it.each([
     { locale: 'en-US', title: 'DeepSeek API settings', name: 'View image fullscreen: DeepSeek API settings', trigger: 'image' },
-    { locale: 'zh-CN', title: 'DeepSeek API 配置', name: '全屏查看图片: DeepSeek API 配置', trigger: 'button' },
+    { locale: 'zh-CN', title: 'DeepSeek API 配置', name: '全屏查看图片：DeepSeek API 配置', trigger: 'button' },
   ])('opens the loaded image with accessible controls in $locale', async ({ locale, title, name, trigger }) => {
     const { image, state } = render()
     language = locale
@@ -200,16 +200,18 @@ describe('documentation image viewer', () => {
     render()
     install()
     const dialog = open()
-    const original = getByRole(dialog, 'button', { name: 'Original size (100%)' })
+    const original = getByRole(dialog, 'button', { name: /^Original size \(100%\), currently / })
     expect(original.textContent).toBe('63%')
+    expect(original.getAttribute('aria-label')).toBe('Original size (100%), currently 63%')
     original.click()
     const current = required(controllers[0])
     expect(current.zoom).toHaveBeenCalledWith(1, { animate: false })
     expect(current.pan).toHaveBeenCalledWith(0, 0, { animate: false })
     current.getScale.mockReturnValue(1)
-    required(dialog.querySelector('.dsh-diagram-paper')).dispatchEvent(new Event('panzoomchange'))
+    required(dialog.querySelector('.dsh-media-paper')).dispatchEvent(new Event('panzoomchange'))
     expect(original.textContent).toBe('100%')
-    const controls = ['Zoom out', 'Original size (100%)', 'Zoom in', 'Fit view', 'Viewer help', 'Close']
+    expect(original.getAttribute('aria-label')).toBe('Original size (100%), currently 100%')
+    const controls = ['Zoom out', 'Original size (100%), currently 100%', 'Zoom in', 'Fit view', 'Viewer help', 'Close']
     expect(document.activeElement).toBe(getByRole(dialog, 'button', { name: 'Close' }))
     for (const name of controls) {
       const event = new KeyboardEvent('keydown', { key: 'Tab', cancelable: true })
@@ -248,7 +250,7 @@ describe('documentation image viewer', () => {
     else required(mermaid).refresh()
     expect(getByRole(document.body, 'dialog')).toBe(dialog)
     expect(document.body.style.overflow).toBe('hidden')
-    expect(queryByRole(dialog, 'button', { name: 'Original size (100%)' }) === null).toBe(first === 'image')
+    expect(queryByRole(dialog, 'button', { name: /^Original size \(100%\), currently / }) === null).toBe(first === 'image')
     getByRole(dialog, 'button', { name: 'Close' }).click()
     expect(document.activeElement).toBe(newTrigger)
     expect(document.body.style.overflow).toBe('auto')
@@ -273,6 +275,29 @@ describe('documentation image viewer', () => {
     expect(enlarged(open()).src).toBe(replacement)
   })
 
+  it('closes stale content when currentSrc changes after the srcset mutation', async () => {
+    const { image, state } = render()
+    state.currentSrc = image.src
+    install()
+    const oldTrigger = entry()
+    const dialog = open()
+    const replacement = 'https://docs.example/provider@2x.png'
+    image.srcset = `${replacement} 2x`
+    await new Promise<void>((resolve) => { queueMicrotask(resolve) })
+    expect(getByRole(document.body, 'dialog')).toBe(dialog)
+    expect(enlarged(dialog).src).toBe(state.currentSrc)
+
+    state.currentSrc = replacement
+    image.dispatchEvent(new Event('load'))
+    expect(queryByRole(document.body, 'dialog')).toBeNull()
+    expect(document.body.style.overflow).toBe('auto')
+    expect(required(controllers[0]).destroy).toHaveBeenCalledOnce()
+    expect(entry()).not.toBe(oldTrigger)
+    oldTrigger.click()
+    expect(queryByRole(document.body, 'dialog')).toBeNull()
+    expect(enlarged(open()).src).toBe(replacement)
+  })
+
   it.each(['refresh', 'dispose', 'remove', 'error'] as const)('releases an open image on %s', async (action) => {
     const { image, container, state } = render()
     install()
@@ -310,7 +335,7 @@ describe('documentation image viewer', () => {
     language = 'zh-CN'
     ready.image.alt = 'API 配置'
     required(viewer).refresh()
-    expect(getByRole(document.body, 'button', { name: '全屏查看图片: API 配置' })).toBe(trigger)
+    expect(getByRole(document.body, 'button', { name: '全屏查看图片：API 配置' })).toBe(trigger)
     required(viewer).dispose()
     pending.state.complete = true
     pending.image.dispatchEvent(new Event('load'))

website/tests/mermaid-viewer.spec.ts

@@ -4,6 +4,7 @@ import assert from 'node:assert/strict'
 import type { PanzoomOptions } from '@panzoom/panzoom'
 import { getByRole, queryAllByRole, queryByRole, waitFor } from '@testing-library/dom'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { MediaViewer } from '../.vitepress/theme/media-viewer.ts'
 import { installMermaidViewer, type MermaidViewer } from '../.vitepress/theme/mermaid-viewer.ts'
 
 const panzoom = vi.hoisted(() => ({
@@ -14,6 +15,8 @@ const panzoom = vi.hoisted(() => ({
 vi.mock('@panzoom/panzoom', () => ({ default: panzoom.create }))
 
 let viewer: MermaidViewer | undefined
+let media: MediaViewer
+let locale = 'en-US'
 let resize: (() => void) | undefined
 let viewportWidth = 1032
 let viewportHeight = 632
@@ -24,6 +27,8 @@ const dialogMethods = new Map(['showModal', 'close'].map(name => [
 
 beforeEach(() => {
   vi.clearAllMocks()
+  locale = 'en-US'
+  media = new MediaViewer(document, () => locale)
   panzoom.create.mockImplementation((_element, options) => {
     panzoom.getScale.mockReturnValue(options.startScale ?? 1)
     return panzoom
@@ -55,6 +60,7 @@ beforeEach(() => {
 
 afterEach(() => {
   viewer?.dispose()
+  media.close()
   viewer = undefined
   resize = undefined
   document.body.replaceChildren()
@@ -95,7 +101,8 @@ describe('documentation Mermaid viewer', () => {
       h1.textContent = heading
       required(document.querySelector('.vp-doc')).prepend(h1)
     }
-    viewer = installMermaidViewer(document, () => language)
+    locale = language
+    viewer = installMermaidViewer(document, () => locale, media)
     getByRole(document.body, 'button').click()
     const dialog = getByRole(document.body, 'dialog', { name: expected })
     const title = required(document.getElementById(required(dialog.getAttribute('aria-labelledby'))))
@@ -103,7 +110,7 @@ describe('documentation Mermaid viewer', () => {
   })
 
   it('adds one entry only after an SVG with usable dimensions renders', async () => {
-    viewer = installMermaidViewer(document, () => 'en-US')
+    viewer = installMermaidViewer(document, () => locale, media)
     expect(queryAllByRole(document.body, 'button')).toHaveLength(0)
     render('0 0 0 3000')
     viewer.refresh()
@@ -124,10 +131,10 @@ describe('documentation Mermaid viewer', () => {
   it('fits the natural SVG into the viewport and isolates copied styles and fragment IDs', () => {
     const source = render()
     const original = source.outerHTML
-    viewer = installMermaidViewer(document, () => 'en-US')
+    viewer = installMermaidViewer(document, () => locale, media)
     const dialog = open()
     expect(panzoom.create.mock.calls[0]?.[1]).toMatchObject({ startScale: 0.2, minScale: 0.1 })
-    const paper = required(dialog.querySelector<HTMLElement>('.dsh-diagram-paper'))
+    const paper = required(dialog.querySelector<HTMLElement>('.dsh-media-paper'))
     const clone = required(paper.shadowRoot?.querySelector('svg'))
     expect(clone.style.width).toBe('2000px')
     expect(clone.style.height).toBe('3000px')
@@ -148,13 +155,13 @@ describe('documentation Mermaid viewer', () => {
 
   it('connects zoom, wheel, keyboard panning and fit without dismissing a canvas click', () => {
     render()
-    viewer = installMermaidViewer(document, () => 'en-US')
+    viewer = installMermaidViewer(document, () => locale, media)
     const dialog = open()
     getByRole(dialog, 'button', { name: 'Zoom in' }).click()
     getByRole(dialog, 'button', { name: 'Zoom out' }).click()
     expect(panzoom.zoomIn).toHaveBeenCalledOnce()
     expect(panzoom.zoomOut).toHaveBeenCalledOnce()
-    const viewport = required(dialog.querySelector<HTMLElement>('.dsh-diagram-viewport'))
+    const viewport = required(dialog.querySelector<HTMLElement>('.dsh-media-viewport'))
     const wheel = new WheelEvent('wheel', { deltaY: -100 })
     viewport.dispatchEvent(wheel)
     expect(panzoom.zoomWithWheel).toHaveBeenCalledWith(wheel)
@@ -170,7 +177,7 @@ describe('documentation Mermaid viewer', () => {
 
   it('wraps keyboard focus through the viewer controls in both directions', () => {
     render()
-    viewer = installMermaidViewer(document, () => 'en-US')
+    viewer = installMermaidViewer(document, () => locale, media)
     const dialog = open()
     const close = getByRole(dialog, 'button', { name: 'Close' })
     const zoomOut = getByRole(dialog, 'button', { name: 'Zoom out' })
@@ -187,10 +194,10 @@ describe('documentation Mermaid viewer', () => {
 
   it('shows zoom changes and reveals help on demand without retaining listeners after close', () => {
     render()
-    viewer = installMermaidViewer(document, () => 'en-US')
+    viewer = installMermaidViewer(document, () => locale, media)
     const dialog = open()
-    const scale = required(dialog.querySelector('.dsh-diagram-scale'))
-    const paper = required(dialog.querySelector('.dsh-diagram-paper'))
+    const scale = required(dialog.querySelector('.dsh-media-scale'))
+    const paper = required(dialog.querySelector('.dsh-media-paper'))
     expect(scale.textContent).toBe('20%')
     panzoom.getScale.mockReturnValue(0.75)
     paper.dispatchEvent(new Event('panzoomchange'))
@@ -213,7 +220,7 @@ describe('documentation Mermaid viewer', () => {
 
   it.each(['button', 'cancel', 'refresh', 'dispose'] as const)('releases resources on %s and restores focus and scrolling', (method) => {
     render()
-    viewer = installMermaidViewer(document, () => 'en-US')
+    viewer = installMermaidViewer(document, () => locale, media)
     const trigger = getByRole(document.body, 'button')
     const dialog = open()
     const zoom = getByRole(dialog, 'button', { name: 'Zoom in' })
@@ -233,8 +240,7 @@ describe('documentation Mermaid viewer', () => {
 
   it('closes a replaced diagram and permits repeated opens with the updated locale', async () => {
     render()
-    let locale = 'en-US'
-    viewer = installMermaidViewer(document, () => locale)
+    viewer = installMermaidViewer(document, () => locale, media)
     open()
     render('0 0 400 200')
     await waitFor(() => {
@@ -252,7 +258,7 @@ describe('documentation Mermaid viewer', () => {
 
   it('closes when route content is removed and stops enhancing after disposal', async () => {
     render()
-    viewer = installMermaidViewer(document, () => 'en-US')
+    viewer = installMermaidViewer(document, () => locale, media)
     open()
     required(document.querySelector('.mermaid')).remove()
     await waitFor(() => {

website/tests/page-markdown-actions.spec.ts

@@ -12,6 +12,8 @@ vi.mock('vitepress/theme', () => ({ default: { Layout: {
   setup: (_props: unknown, { slots }: { slots: Slots }) => () => h('main', null, slots['doc-before']?.()),
 } } }))
 vi.mock('../.vitepress/theme/mermaid-viewer.ts', () => ({ installMermaidViewer: () => ({ refresh() {}, dispose() {} }) }))
+vi.mock('../.vitepress/theme/image-viewer.ts', () => ({ ImageViewer: class { refresh() {} dispose() {} } }))
+vi.mock('../.vitepress/theme/media-viewer.ts', () => ({ MediaViewer: class { close() {} } }))
 
 const data = {
   lang: ref('en-US'), isDark: ref(false),