@keith9681/dsh-sidebar 0.15.2

package/src/client/mermaid-blocks.ts

@@ -0,0 +1,110 @@
+/**
+ * Markdown/mermaid fence detection for the markdown preview. The preview
+ * renders the WHOLE document through one DSH `MarkdownText` pass (so
+ * cross-fence semantics — reference-style links, footnotes, list
+ * continuity — stay intact) and the mermaid lazy chunk then swaps the
+ * rendered `language-mermaid` code blocks for diagrams. This module's pure
+ * splitter exists to detect whether the source contains a mermaid fence at
+ * all, so the mermaid chunk is only fetched when needed (unit-tested in
+ * tests/mermaid-blocks.spec.ts).
+ */
+
+/** One fenced mermaid diagram lifted out of the markdown source. */
+export interface MermaidBlock {
+  kind: 'mermaid'
+  /** The raw diagram source between the fences (info string stripped). */
+  code: string
+}
+
+/** A span of plain markdown source (may itself contain non-mermaid fences). */
+export interface MarkdownBlock {
+  kind: 'markdown'
+  text: string
+}
+
+export type MdBlock = MarkdownBlock | MermaidBlock
+
+/** Props of the chunk-resident `MermaidMarkdown` component (shared contract). */
+export interface MermaidMarkdownProps {
+  /** The full markdown source (rendered in a single MarkdownText pass). */
+  text: string
+  codeLabels: { copyLabel: string; copiedLabel: string }
+}
+
+/** CommonMark opening fence: 0-3 spaces indent + a run of 3+ backticks or tildes. */
+const OPEN_FENCE_RE = /^ {0,3}(`{3,}|~{3,})/
+
+/** A closing-fence line: 0-3 spaces indent + 3+ backticks/tildes + trailing spaces only. */
+const CLOSE_FENCE_RE = /^ {0,3}(`{3,}|~{3,})[ \t]*$/
+
+/** Parse the info string from the line tail after the fence run; null when invalid. */
+function fenceInfo(rest: string, fence: string): string | null {
+  const info = rest.trimStart().split(/\s+/)[0] ?? ''
+  // CommonMark: a backtick fence's info string may not contain backticks —
+  // such a line is not an opening fence at all.
+  if (fence.charAt(0) === '`' && info.includes('`')) return null
+  return info
+}
+
+/** True when the fence info string names mermaid (bare or `mermaid{...}`). */
+function isMermaidInfo(info: string): boolean {
+  const word = info.toLowerCase()
+  return word === 'mermaid' || word.startsWith('mermaid{')
+}
+
+/**
+ * Split markdown source into md/mermaid blocks for detection: only fences
+ * whose info string names mermaid are lifted; every other line stays in the
+ * markdown stream untouched. CommonMark fence rules are honored — opening
+ * fences of 3+ backticks OR tildes, and a closing fence must use the same
+ * character with at least as many characters as the opening fence. An
+ * unterminated mermaid fence swallows the rest of the file (the same
+ * recovery CommonMark applies to open fences).
+ */
+export function splitMermaidBlocks(text: string): MdBlock[] {
+  if (text === '') return []
+  const lines = text.split('\n')
+  const blocks: MdBlock[] = []
+  let markdown: string[] = []
+  let index = 0
+  const flushMarkdown = (): void => {
+    if (markdown.length === 0) return
+    blocks.push({ kind: 'markdown', text: markdown.join('\n') })
+    markdown = []
+  }
+  while (index < lines.length) {
+    const line = lines[index] ?? ''
+    const fenceMatch = OPEN_FENCE_RE.exec(line)
+    if (fenceMatch === null) {
+      markdown.push(line)
+      index += 1
+      continue
+    }
+    const fence = fenceMatch[1]!
+    // The line tail after the whole matched prefix (indent + fence run).
+    const rest = line.slice(fenceMatch.index + fenceMatch[0].length)
+    const info = fenceInfo(rest, fence)
+    if (info === null || !isMermaidInfo(info)) {
+      markdown.push(line)
+      index += 1
+      continue
+    }
+    flushMarkdown()
+    const char = fence.charAt(0)
+    const length = fence.length
+    const code: string[] = []
+    index += 1
+    while (index < lines.length) {
+      const candidate = lines[index] ?? ''
+      const close = CLOSE_FENCE_RE.exec(candidate)
+      if (close !== null && close[1]!.charAt(0) === char && close[1]!.length >= length) break
+      code.push(candidate)
+      index += 1
+    }
+    // Consume the closing fence (or run off the end on an open fence).
+    index += 1
+    blocks.push({ kind: 'mermaid', code: code.join('\n') })
+  }
+  flushMarkdown()
+  return blocks
+}

package/src/client/mermaid-sanitize.ts

@@ -0,0 +1,93 @@
+/**
+ * SVG sanitization for mermaid-rendered diagrams (markdown preview). The
+ * diagrams come from untrusted markdown sources, so the emitted SVG is
+ * re-sanitized before it reaches dangerouslySetInnerHTML — defense in depth
+ * on top of mermaid's own `securityLevel: 'strict'` (labels escaped, click
+ * directives inert) and `htmlLabels: false` (labels as real SVG <text>).
+ *
+ * What is stripped, and why:
+ * - `foreignObject`: the only channel that can carry raw HTML inside an
+ *   SVG document — with it gone, a hostile label cannot smuggle an
+ *   <img onerror> / <iframe> through the XML parse (any non-SVG element
+ *   outside foreignObject makes the XML parse fail and the whole diagram
+ *   is rejected).
+ * - `script` and foreign HTML elements (`img`/`iframe`/`object`/`embed`/
+ *   `video`/`audio`/`input`/`button`/`form`/`link`/`meta`/`base`): belt and
+ *   braces — real browsers reject these outside foreignObject at XML parse
+ *   time (→ '') while lenient parsers keep them, so they are stripped
+ *   explicitly instead of relying on the parser alone. Element names are
+ *   matched case-insensitively (XML preserves their case; the output is
+ *   re-parsed as HTML whose parser normalizes tag casing, so `<sCrIpT>` /
+ *   `<foreignobject>` would otherwise come back as script/foreignObject).
+ * - `@*` / `on*` attributes: event-handler channels (Vue-style directives
+ *   and native listeners), matched case-insensitively — the output is
+ *   re-parsed as HTML whose parser normalizes attribute casing, so
+ *   `oNload`/`OnClick` must not survive either.
+ * - ALL `href` / `xlink:href` attributes: the diagrams are static (no
+ *   bindFunctions, no click navigation), so links carry no value — and an
+ *   attacker-controlled URL (even an http(s) one) could otherwise navigate
+ *   the whole GUI away from the sidebar. Removing every href keeps the
+ *   surface deterministic.
+ *
+ * Parsing happens with `image/svg+xml`, so a malformed SVG fails the XML
+ * parse and the function returns '' (the caller surfaces the error
+ * fallback) instead of ever passing the raw string through; only a document
+ * whose root is an `<svg>` element is accepted.
+ */
+/** Element local names stripped case-insensitively (all lowercase). */
+const STRIP_ELEMENTS = new Set([
+  'foreignobject',
+  'script',
+  'img',
+  'iframe',
+  'object',
+  'embed',
+  'video',
+  'audio',
+  'input',
+  'button',
+  'form',
+  'link',
+  'meta',
+  'base',
+])
+
+/** A parse failure keeps nothing of the input: the caller shows the error. */
+export function sanitizeSvg(svg: string): string {
+  if (typeof DOMParser === 'undefined' || typeof XMLSerializer === 'undefined') return ''
+  let doc: Document
+  try {
+    doc = new DOMParser().parseFromString(svg, 'image/svg+xml')
+  } catch {
+    return ''
+  }
+  if (doc.querySelector('parsererror') !== null) return ''
+  if (doc.documentElement === null || doc.documentElement.localName !== 'svg') return ''
+  doc.querySelectorAll('*').forEach((node) => {
+    // XML element names preserve case; the string is later re-parsed as HTML
+    // whose parser normalizes tag casing — so mixed-case spellings of the
+    // strip list (e.g. `<sCrIpT>`, `<foreignobject>`) must be caught the
+    // same way as their canonical forms.
+    if (STRIP_ELEMENTS.has(node.localName.toLowerCase())) {
+      node.remove()
+      return
+    }
+    for (const attribute of [...node.attributes]) {
+      const name = attribute.name
+      // XML attribute names preserve case; the string is later re-parsed as
+      // HTML (dangerouslySetInnerHTML), whose parser normalizes attribute
+      // casing — so a mixed-case `oNload`/`HREF` must be caught the same way
+      // as its lowercase form. Compare on the lowercased name, remove with
+      // the original.
+      const normalized = name.toLowerCase()
+      if (normalized.startsWith('@') || normalized.startsWith('on')) {
+        node.removeAttribute(name)
+        continue
+      }
+      if (normalized === 'href' || normalized === 'xlink:href') {
+        node.removeAttribute(name)
+      }
+    }
+  })
+  return new XMLSerializer().serializeToString(doc.documentElement)
+}

package/src/client/mermaid.tsx

@@ -0,0 +1,401 @@
+/**
+ * Mermaid diagram renderer for the markdown preview, resident in the
+ * `mermaid` lazy chunk (src/client/chunks/mermaid.tsx): the mermaid library
+ * and its transitive graph deps (d3/dagre/cytoscape) are inlined into
+ * lib/client-mermaid.js and fetched only when a previewed markdown file
+ * actually contains a mermaid fence (see mermaid-blocks.ts).
+ *
+ * Rendering architecture: the whole document is rendered ONCE through the
+ * DSH `MarkdownText` (so cross-fence semantics — reference-style links,
+ * footnotes, ordered-list continuity — stay intact), then a layout effect
+ * swaps every rendered `language-mermaid` CodeBlock for a diagram. The
+ * swap keeps the React-managed `.md-code-block` host node in the tree and
+ * only replaces its children (display:contents suppresses the code-block
+ * chrome), so React reconciliation never loses the host; when a swapped
+ * block stops being a mermaid fence, the original children are restored.
+ *
+ * Security: mermaid.render → sanitized SVG injected into the block.
+ * `bindFunctions` is intentionally NOT applied (static diagrams; no
+ * flowchart click handlers), `securityLevel` stays 'strict' (labels are
+ * escaped, no raw-HTML foreignObject), `htmlLabels: false` keeps node text
+ * as real SVG <text>, and the emitted SVG is re-sanitized (see
+ * mermaid-sanitize.ts) before it reaches dangerouslySetInnerHTML. Clicking
+ * a rendered diagram opens a zoom/pan modal (borrowed interaction design
+ * from the mermaid PR #75, reimplemented on top of the sanitized SVG —
+ * the clone carries no event surface, so the modal adds no attack surface).
+ */
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type MouseEvent as ReactMouseEvent } from 'react'
+import { createPortal } from 'react-dom'
+import { createRoot, type Root } from 'react-dom/client'
+import mermaid from 'mermaid'
+import { IconCopyOutline16, MarkdownText, writeClipboard } from '@deepseek-ai/dsh-client-ui-primitives'
+import { isDarkScheme, subscribeColorScheme } from './theme.ts'
+import { t } from './locales.ts'
+import { sanitizeSvg } from './mermaid-sanitize.ts'
+import type { MermaidMarkdownProps } from './mermaid-blocks.ts'
+import css from './sidebar.module.css'
+
+/** Monotonic id seed: every render call gets a fresh, document-unique id. */
+let mermaidSeq = 0
+
+/** Configure mermaid for the current color scheme (idempotent). */
+function configureMermaid(): void {
+  mermaid.initialize({
+    startOnLoad: false,
+    securityLevel: 'strict',
+    // Labels as real SVG <text>: mermaid's default htmlLabels renders node
+    // text inside <foreignObject>, which the sanitizer strips wholesale —
+    // forcing pure SVG text keeps labels visible and the HTML label channel
+    // closed (strict already escapes label content).
+    htmlLabels: false,
+    theme: isDarkScheme() ? 'dark' : 'default',
+  })
+}
+
+/** First lines of a mermaid error (its dumps are huge; the head explains). */
+function summarizeError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error)
+  return message.split('\n').slice(0, 6).join('\n')
+}
+
+/** The zoom/pan modal for one rendered diagram (click-to-enlarge). */
+function MermaidZoomModal({ svg, onClose }: { svg: SVGSVGElement; onClose: () => void }): React.ReactNode {
+  const overlayRef = useRef<HTMLDivElement>(null)
+  const stageRef = useRef<HTMLDivElement>(null)
+  const svgRef = useRef<SVGSVGElement | null>(null)
+  const dragRef = useRef({ active: false, startX: 0, startY: 0 })
+  const zoomRef = useRef({ scale: 1, tx: 0, ty: 0 })
+
+  const applyTransform = (): void => {
+    const node = svgRef.current
+    if (node === null) return
+    const { scale, tx, ty } = zoomRef.current
+    node.style.transform = `translate(${tx}px, ${ty}px) scale(${scale})`
+  }
+
+  /** Zoom by `delta` keeping the stage point (centerX/centerY) fixed. */
+  const zoom = useCallback((delta: number, centerX?: number, centerY?: number): void => {
+    const stage = stageRef.current
+    if (stage === null) return
+    const rect = stage.getBoundingClientRect()
+    const cx = centerX ?? rect.width / 2
+    const cy = centerY ?? rect.height / 2
+    const current = zoomRef.current
+    const newScale = Math.min(8, Math.max(0.2, current.scale * delta))
+    // The svg is flex-centered in the stage, so its center sits at
+    // (rect.width/2, rect.height/2). Solve for the translate that keeps the
+    // mouse point stationary in stage coordinates across the scale change.
+    const sx = rect.width / 2
+    const sy = rect.height / 2
+    const ratio = newScale / current.scale
+    current.tx = cx - sx - (cx - sx - current.tx) * ratio
+    current.ty = cy - sy - (cy - sy - current.ty) * ratio
+    current.scale = newScale
+    applyTransform()
+  }, [])
+
+  const reset = useCallback((): void => {
+    zoomRef.current = { scale: 1, tx: 0, ty: 0 }
+    applyTransform()
+  }, [])
+
+  const close = useCallback((): void => { onClose() }, [onClose])
+
+  // Mount the caller-provided (sanitized) svg clone imperatively: React
+  // types don't accept a raw DOM node as a child, and the modal owns the
+  // node's lifetime (removed on unmount; the preview copy is untouched).
+  useEffect(() => {
+    const stage = stageRef.current
+    if (stage === null) return
+    svgRef.current = svg
+    stage.appendChild(svg)
+    return () => {
+      svg.remove()
+      svgRef.current = null
+    }
+  }, [svg])
+
+  useEffect(() => {
+    const stage = stageRef.current
+    const node = svgRef.current
+    const overlay = overlayRef.current
+    if (stage === null || node === null || overlay === null) return
+
+    const onWheel = (event: WheelEvent): void => {
+      event.preventDefault()
+      const rect = stage.getBoundingClientRect()
+      zoom(event.deltaY < 0 ? 1.1 : 1 / 1.1, event.clientX - rect.left, event.clientY - rect.top)
+    }
+    const onKey = (event: KeyboardEvent): void => {
+      if (event.key === 'Escape') { close(); return }
+      if (event.key === '+' || event.key === '=') zoom(1.2)
+      else if (event.key === '-') zoom(1 / 1.2)
+      else if (event.key === '0') reset()
+    }
+    const onMouseDown = (event: MouseEvent): void => {
+      event.preventDefault()
+      dragRef.current = {
+        active: true,
+        startX: event.clientX - zoomRef.current.tx,
+        startY: event.clientY - zoomRef.current.ty,
+      }
+    }
+    const onMouseMove = (event: MouseEvent): void => {
+      if (!dragRef.current.active) return
+      zoomRef.current.tx = event.clientX - dragRef.current.startX
+      zoomRef.current.ty = event.clientY - dragRef.current.startY
+      applyTransform()
+    }
+    const onMouseUp = (): void => { dragRef.current.active = false }
+    const onOverlayClick = (event: MouseEvent): void => {
+      if (event.target === overlay) close()
+    }
+
+    // React's synthetic wheel is passive; a native listener is required to
+    // preventDefault (the page must not scroll while zooming the modal).
+    stage.addEventListener('wheel', onWheel, { passive: false })
+    node.addEventListener('mousedown', onMouseDown)
+    window.addEventListener('mousemove', onMouseMove)
+    window.addEventListener('mouseup', onMouseUp)
+    window.addEventListener('keydown', onKey)
+    overlay.addEventListener('click', onOverlayClick)
+    return () => {
+      stage.removeEventListener('wheel', onWheel)
+      node.removeEventListener('mousedown', onMouseDown)
+      window.removeEventListener('mousemove', onMouseMove)
+      window.removeEventListener('mouseup', onMouseUp)
+      window.removeEventListener('keydown', onKey)
+      overlay.removeEventListener('click', onOverlayClick)
+    }
+  }, [zoom, reset, close])
+
+  return createPortal(
+    <div className={css.mermaidModal} data-mermaid-modal ref={overlayRef}>
+      <div className={css.mermaidModalToolbar}>
+        <button
+          type="button"
+          className={css.mermaidModalButton}
+          title={t('mermaidZoomOut')}
+          onClick={() => zoom(1 / 1.2)}
+        >
+          −
+        </button>
+        <button
+          type="button"
+          className={css.mermaidModalButton}
+          title={t('mermaidZoomIn')}
+          onClick={() => zoom(1.2)}
+        >
+          +
+        </button>
+        <button
+          type="button"
+          className={css.mermaidModalButton}
+          title={t('mermaidZoomReset')}
+          onClick={reset}
+        >
+          ⟳
+        </button>
+        <button
+          type="button"
+          className={css.mermaidModalButton}
+          title={t('close')}
+          onClick={close}
+        >
+          ✕
+        </button>
+      </div>
+      <div className={css.mermaidModalStage} ref={stageRef} />
+      <div className={css.mermaidModalHint}>{t('mermaidZoomHint')}</div>
+    </div>,
+    document.body,
+  )
+}
+
+/** One rendered mermaid fence: header chrome + diagram (or error + source). */
+function MermaidDiagram({ code }: { code: string }): React.ReactNode {
+  const [svg, setSvg] = useState<string | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [copied, setCopied] = useState(false)
+  /** Scheme state: a flip re-renders the diagram with the matching theme. */
+  const [dark, setDark] = useState(() => isDarkScheme())
+  /** The cloned svg shown in the zoom modal (null = closed). */
+  const [zoomSvg, setZoomSvg] = useState<SVGSVGElement | null>(null)
+  const copyTimer = useRef<number | undefined>(undefined)
+
+  useEffect(() => subscribeColorScheme(() => { setDark(isDarkScheme()) }), [])
+
+  useEffect(() => {
+    let cancelled = false
+    setSvg(null)
+    setError(null)
+    if (code.trim() === '') return () => { cancelled = true }
+    configureMermaid()
+    const id = `dsh-md-mermaid-${mermaidSeq += 1}`
+    mermaid.render(id, code)
+      .then(({ svg: rendered }) => {
+        if (cancelled) return
+        const clean = sanitizeSvg(rendered)
+        if (clean === '') {
+          // Parse/sanitize rejection: never pass the raw string through.
+          setError(t('mermaidError'))
+          return
+        }
+        setSvg(clean)
+      })
+      .catch((reason: unknown) => {
+        if (cancelled) return
+        setError(summarizeError(reason))
+      })
+    return () => { cancelled = true }
+  }, [code, dark])
+
+  const onCopy = useCallback(() => {
+    if (copied) return
+    writeClipboard(code).then((ok) => {
+      if (!ok) return
+      setCopied(true)
+      window.clearTimeout(copyTimer.current)
+      copyTimer.current = window.setTimeout(() => { setCopied(false) }, 1000)
+    })
+  }, [code, copied])
+
+  /** Clicking the diagram opens the zoom modal with a sanitized clone. */
+  const onBodyClick = (event: ReactMouseEvent<HTMLDivElement>): void => {
+    const svgEl = (event.target as Element).closest('svg')
+    if (svgEl === null) return
+    const clone = svgEl.cloneNode(true) as SVGSVGElement
+    // The modal owns sizing/transform; drop the preview's inline geometry.
+    clone.removeAttribute('style')
+    clone.removeAttribute('width')
+    clone.removeAttribute('height')
+    setZoomSvg(clone)
+  }
+
+  return (
+    <div className={css.mermaidWrap}>
+      <div className={css.mermaidHeader}>
+        <span className={css.mermaidInfo}>mermaid</span>
+        <button
+          type="button"
+          className={css.mermaidCopy}
+          onClick={onCopy}
+          aria-label={t('copy')}
+          title={t('copy')}
+        >
+          <IconCopyOutline16 />
+          <span>{copied ? t('copied') : t('copy')}</span>
+        </button>
+      </div>
+      {error !== null && <div className={css.mermaidError} title={error}>{t('mermaidError')}</div>}
+      {svg !== null && (
+        <div
+          className={css.mermaidBody}
+          data-mermaid-diagram
+          onClick={onBodyClick}
+          dangerouslySetInnerHTML={{ __html: svg }}
+        />
+      )}
+      {error !== null && <pre className={css.mermaidCode}><code>{code}</code></pre>}
+      {zoomSvg !== null && <MermaidZoomModal svg={zoomSvg} onClose={() => { setZoomSvg(null) }} />}
+    </div>
+  )
+}
+
+/** One swapped mount: the diagram root + the CodeBlock children it displaced. */
+interface MermaidMount {
+  root: Root
+  source: string
+  removed: ChildNode[]
+}
+
+/**
+ * True when a rendered CodeBlock is a mermaid fence. The DSH CodeBlock has
+ * two bodies: the shiki path carries the `language-*` class on generated
+ * <code> elements, while the plain path (which is always the one mermaid
+ * takes — no shiki grammar) only shows the language in the banner
+ * infostring (first element of the banner row; CSS-module classes are
+ * hashed, so that match is structural).
+ */
+function isMermaidBlock(block: HTMLElement): boolean {
+  const code = block.querySelector('code')
+  if (code !== null && [...code.classList].some(c => c.startsWith('language-mermaid'))) return true
+  const infostring = block.firstElementChild?.firstElementChild?.firstElementChild
+  return infostring !== null
+    && infostring !== undefined
+    && (infostring.textContent ?? '').trim() === 'mermaid'
+}
+
+/**
+ * The chunk-resident markdown preview renderer: ONE MarkdownText pass over
+ * the full source (cross-fence reference/footnote/list semantics intact),
+ * then every rendered `language-mermaid` code block is swapped for a
+ * `MermaidDiagram`. The `.md-code-block` host stays in the React tree —
+ * only its children are replaced — so reconciliation never loses the host;
+ * a block that stops being a mermaid fence gets its original children back.
+ * Only mounted when the source contains at least one mermaid fence (see
+ * TextEditor.tsx).
+ */
+export function MermaidMarkdown({ text, codeLabels }: MermaidMarkdownProps): React.ReactNode {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const mountsRef = useRef(new Map<HTMLElement, MermaidMount>())
+
+  useLayoutEffect(() => {
+    const container = containerRef.current
+    if (container === null) return
+    const mounts = mountsRef.current
+    const seen = new Set<HTMLElement>()
+
+    for (const block of container.querySelectorAll<HTMLElement>('.md-code-block')) {
+      const mount = mounts.get(block)
+      const isMermaid = isMermaidBlock(block)
+      if (!isMermaid) {
+        // A previously swapped block that is no longer a mermaid fence:
+        // restore the CodeBlock children React still manages, so the plain
+        // fence renders normally again.
+        if (mount !== undefined) {
+          mount.root.unmount()
+          block.replaceChildren(...mount.removed)
+          block.removeAttribute('data-mermaid-processed')
+          mounts.delete(block)
+        }
+        continue
+      }
+      seen.add(block)
+      // The plain body always carries the fence source in <code>.
+      const source = block.querySelector('code')?.textContent ?? ''
+      if (mount !== undefined && mount.source === source) continue
+      if (mount === undefined) {
+        const host = document.createElement('div')
+        const removed = [...block.childNodes]
+        block.replaceChildren(host)
+        block.setAttribute('data-mermaid-processed', 'true')
+        const root = createRoot(host)
+        mounts.set(block, { root, source, removed })
+        root.render(<MermaidDiagram code={source} />)
+      } else {
+        mount.source = source
+        mount.root.render(<MermaidDiagram code={source} />)
+      }
+    }
+
+    // Drop mounts whose code block left the tree (fence removed, document
+    // restructured): the host node is gone with it.
+    for (const [block, mount] of mounts) {
+      if (seen.has(block)) continue
+      mount.root.unmount()
+      mounts.delete(block)
+    }
+  }, [text])
+
+  useEffect(() => () => {
+    for (const { root } of mountsRef.current.values()) root.unmount()
+    mountsRef.current.clear()
+  }, [])
+
+  return (
+    <div className={css.mermaidMarkdown} ref={containerRef}>
+      <MarkdownText text={text} codeLabels={codeLabels} />
+    </div>
+  )
+}

package/src/client/open-when-sized.ts

@@ -0,0 +1,43 @@
+/**
+ * Deferred one-shot open for hosts that may not have a real size yet.
+ *
+ * xterm's `Terminal.open()` must not run in a zero-size container: the
+ * renderer creation fails there (the DomRenderer is built from the host's
+ * dimensions), leaving the render service's renderer `undefined`, and the
+ * next Viewport refresh crashes reading `.dimensions` off it. WebKit-based
+ * hosts (WKWebView) reliably report zero while the bottom panel's expand
+ * slide is in flight; any `display:none`-hidden ancestor does the same.
+ *
+ * The caller's `open` callback (open + fit + resize) is invoked exactly
+ * once, on the first frame where the host reports a real size. While the
+ * host stays zero-sized the polling continues every frame; it stops when
+ * the host leaves the document (`isConnected`), so a pending open never
+ * fires after unmount. The returned cancel function drops a pending frame
+ * immediately (idempotent).
+ *
+ * `raf`/`caf` are injectable so tests can drive the polling deterministically.
+ */
+export function openWhenSized(
+  host: HTMLElement,
+  open: () => void,
+  raf: (cb: FrameRequestCallback) => number = requestAnimationFrame,
+  caf: (id: number) => void = cancelAnimationFrame,
+): () => void {
+  let frame: number | null = null
+  const step = (): void => {
+    frame = null
+    if (!host.isConnected) return
+    if (host.clientWidth > 0 && host.clientHeight > 0) {
+      open()
+      return
+    }
+    frame = raf(step)
+  }
+  frame = raf(step)
+  return () => {
+    if (frame !== null) {
+      caf(frame)
+      frame = null
+    }
+  }
+}