dsh-coding-sidebar 1.0.0

package/src/client/markdown-html.ts

@@ -0,0 +1,331 @@
+/**
+ * Raw-HTML block detection for the markdown preview. The shared `MarkdownText`
+ * renders raw HTML as literal text (a chat-security stance), so a GitHub-style
+ * README (`<div align="center">` badge walls, `<details>` collapsibles with
+ * markdown inside, table cells full of inline tags) previews as source soup.
+ * This module's pure splitter lifts those HTML runs OUT of the markdown stream
+ * before rendering: markdown runs keep flowing through `MarkdownText` (shiki /
+ * KaTeX / GFM intact, mermaid chunk path unchanged) while HTML runs render as
+ * sanitized DOM (see markdown-html.tsx).
+ *
+ * Splitting follows CommonMark's shape closely enough for real-world READMEs:
+ * a line outside code fences that starts with a block-level tag (type-6 list
+ * below) or `<!--` opens an HTML run that extends to the next blank line
+ * (comments end at the line containing `-->`). Inline-only tags (`<b>`, `<br>`,
+ * `<a>`…) never open a run — they stay in the markdown stream and are handled
+ * by the inline pass instead. Unclosed block tags (`<details>` … markdown …
+ * `</details>`) are surfaced by {@link analyzeHtmlSegment} as ordered parts so
+ * the renderer can nest the in-between markdown inside the open element, the
+ * way GitHub's linear HTML output nests.
+ */
+
+import { CLOSE_FENCE_RE, OPEN_FENCE_RE, fenceInfo } from './mermaid-blocks.ts'
+
+/** A run of raw HTML lines lifted out of the markdown stream. */
+export interface HtmlSegment {
+  kind: 'html'
+  text: string
+}
+
+/** A run of markdown source (may contain non-mermaid fences, inline HTML…). */
+export interface MarkdownHtmlSegment {
+  kind: 'markdown'
+  text: string
+}
+
+export type MdHtmlSegment = MarkdownHtmlSegment | HtmlSegment
+
+/** The doc-wide analysis the preview consumes (all pure, unit-tested here). */
+export interface AnalyzedMarkdownHtml {
+  /** The document split into markdown / html runs (empty input → []). */
+  segments: MdHtmlSegment[]
+  /** True when at least one html run was lifted out. */
+  hasBlockHtml: boolean
+  /** True when the source contains any tag-like text (block OR inline). */
+  hasInlineHtml: boolean
+  /** Every reference definition found in the markdown runs (`[label]: dest`
+   *  lines), joined — appended to each markdown run so `[text][id]` keeps
+   *  resolving across the lifted HTML runs (first-match wins makes the
+   *  appended copy inert inside runs that already define it). */
+  referenceDefinitions: string
+}
+
+/**
+ * CommonMark HTML-block type-6 tag names (block-level elements), lowercased.
+ * A line starting with one of these (open or close) outside a fence begins an
+ * HTML run. `<summary>` is CommonMark-inline but intentionally included: it is
+ * the idiomatic first child of a `<details>` run in GitHub-flavored READMEs.
+ */
+export const HTML_BLOCK_TAGS: ReadonlySet<string> = new Set([
+  'address', 'article', 'aside', 'base', 'basefont', 'blockquote', 'body',
+  'caption', 'center', 'col', 'colgroup', 'dd', 'details', 'dialog', 'dir',
+  'div', 'dl', 'dt', 'fieldset', 'figcaption', 'figure', 'footer', 'form',
+  'frame', 'frameset', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'head', 'header',
+  'hr', 'html', 'legend', 'li', 'link', 'main', 'menu', 'menuitem', 'nav',
+  'noframes', 'ol', 'optgroup', 'option', 'p', 'param', 'picture', 'pre',
+  'section', 'source', 'summary', 'table', 'tbody', 'td', 'tfoot', 'th',
+  'thead', 'title', 'tr', 'track', 'ul', 'video',
+])
+
+/** HTML void elements — never pushed on the balance stack. */
+const VOID_TAGS: ReadonlySet<string> = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta',
+  'param', 'source', 'track', 'wbr',
+])
+
+/** A block-tag line start: indent + `<` or `</` + tag name + space/`/`/`>`. */
+const HTML_BLOCK_START_RE = /^ {0,3}<\/?([a-zA-Z][a-zA-Z0-9-]*)[\s/>]/
+
+/** A comment-open line start (CommonMark type 2). */
+const COMMENT_START_RE = /^ {0,3}<!--/
+
+/** Tag-like text anywhere — the cheap gate for the inline pass. */
+const TAGLIKE_RE = /<\/?[a-zA-Z][a-zA-Z0-9-]*[\s/>]/
+
+/** One HTML tag token (open/close/void) in a lifted HTML run. */
+interface HtmlToken {
+  kind: 'open' | 'close' | 'void'
+  tag: string
+  /** Raw attribute source of an open tag (between the name and `>`/`/>`). */
+  attrs: string
+  start: number
+  end: number
+}
+
+/** A comment range within a run — tags inside comments are not tokens. */
+interface CommentRange {
+  start: number
+  end: number
+}
+
+/** A full tag match including its `>` (token regex; quotes guard `>` inside attrs). */
+const TAG_TOKEN_RE = /<(\/?)([a-zA-Z][a-zA-Z0-9-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g
+const COMMENT_RE = /<!--[\s\S]*?-->/g
+
+/**
+ * Tokenize a lifted HTML run into tags (comments are located first so tags
+ * inside them are skipped). Text between tokens is not tokenized — it stays
+ * part of the raw `html` spans the part analysis slices out.
+ */
+function tokenizeHtml(source: string): HtmlToken[] {
+  const comments: CommentRange[] = []
+  for (const match of source.matchAll(COMMENT_RE)) {
+    comments.push({ start: match.index, end: match.index + match[0].length })
+  }
+  const inComment = (index: number): boolean =>
+    comments.some((range) => index >= range.start && index < range.end)
+  const tokens: HtmlToken[] = []
+  for (const match of source.matchAll(TAG_TOKEN_RE)) {
+    if (inComment(match.index)) continue
+    const closing = match[1] === '/'
+    const tag = match[2]!.toLowerCase()
+    let attrs = match[3] ?? ''
+    // Self-closing syntax (`<div/>`) behaves as void regardless of the name.
+    const selfClosing = /\/\s*$/.test(attrs)
+    if (selfClosing) attrs = attrs.replace(/\/\s*$/, '')
+    tokens.push({
+      kind: closing ? 'close' : selfClosing || VOID_TAGS.has(tag) ? 'void' : 'open',
+      tag,
+      attrs,
+      start: match.index,
+      end: match.index + match[0].length,
+    })
+  }
+  return tokens
+}
+
+/** One structural piece of a lifted HTML run, in document order. */
+export type HtmlPart =
+  | { kind: 'html'; html: string }
+  | { kind: 'open'; tag: string; attrs: string }
+  | { kind: 'close'; tag: string }
+
+/** The run's structure relative to the surrounding document nesting. */
+export interface HtmlSegmentShape {
+  parts: HtmlPart[]
+}
+
+/**
+ * Reduce a lifted HTML run to ordered parts: balanced spans become `html`
+ * leaves, unclosed open tags become `open` (a wrapper the renderer lowers
+ * following markdown runs into), unmatched closes become `close` (pops one
+ * wrapper level). A mismatched close pops through the matching open — the
+ * HTML parser's implicit-close behavior. Runs with no structural tags reduce
+ * to a single `html` part.
+ */
+export function analyzeHtmlSegment(source: string): HtmlSegmentShape {
+  const tokens = tokenizeHtml(source)
+  const stack: { token: HtmlToken }[] = []
+  const unmatchedCloses: HtmlToken[] = []
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index]!
+    if (token.kind === 'void') continue
+    if (token.kind === 'open') {
+      stack.push({ token })
+      continue
+    }
+    // Close: pop through the nearest matching open (implicit closes inside).
+    let matchAt = -1
+    for (let depth = stack.length - 1; depth >= 0; depth -= 1) {
+      if (stack[depth]!.token.tag === token.tag) { matchAt = depth; break }
+    }
+    if (matchAt === -1) {
+      unmatchedCloses.push(token)
+      continue
+    }
+    stack.length = matchAt
+  }
+
+  // Structural tokens in source order: unmatched closes + surviving opens.
+  const structural: Array<{ token: HtmlToken; kind: 'open' | 'close' }> = []
+  for (const token of unmatchedCloses) structural.push({ token, kind: 'close' })
+  for (const entry of stack) structural.push({ token: entry.token, kind: 'open' })
+  structural.sort((a, b) => a.token.start - b.token.start)
+
+  if (structural.length === 0) return { parts: [{ kind: 'html', html: source }] }
+
+  const parts: HtmlPart[] = []
+  let cursor = 0
+  for (const { token, kind } of structural) {
+    if (token.start > cursor) parts.push({ kind: 'html', html: source.slice(cursor, token.start) })
+    parts.push(kind === 'open'
+      ? { kind: 'open', tag: token.tag, attrs: token.attrs }
+      : { kind: 'close', tag: token.tag })
+    cursor = token.end
+  }
+  if (cursor < source.length) parts.push({ kind: 'html', html: source.slice(cursor) })
+  return { parts }
+}
+
+/**
+ * Split markdown source into markdown / html runs (fence-aware: an HTML-looking
+ * line inside any fenced code block is content, not a run start). Blank lines
+ * terminate HTML runs and are dropped between segments (they carry no markdown
+ * semantics the preview needs); everything else stays byte-identical.
+ */
+export function splitHtmlBlocks(text: string): MdHtmlSegment[] {
+  if (text === '') return []
+  const lines = text.split('\n')
+  const segments: MdHtmlSegment[] = []
+  let markdown: string[] = []
+  let html: string[] = []
+  /** Fence state: the char + length of the currently open fence, if any. */
+  let openFence: { char: string; length: number } | null = null
+  /** Comment state: an HTML comment run ends at the line containing `-->`. */
+  let inComment = false
+  /** True while accumulating a blank-line-terminated HTML run. */
+  let inHtmlRun = false
+
+  const flushMarkdown = (): void => {
+    // Separator blank lines around HTML runs carry no markdown semantics.
+    while (markdown.length > 0 && isBlank(markdown[markdown.length - 1] ?? '')) markdown.pop()
+    if (markdown.length === 0) return
+    segments.push({ kind: 'markdown', text: markdown.join('\n') })
+    markdown = []
+  }
+  const flushHtml = (): void => {
+    if (html.length === 0) return
+    segments.push({ kind: 'html', text: html.join('\n') })
+    html = []
+    inHtmlRun = false
+    inComment = false
+  }
+  const isBlank = (line: string): boolean => /^[ \t]*$/.test(line)
+
+  for (const line of lines) {
+    if (openFence !== null) {
+      const close = CLOSE_FENCE_RE.exec(line)
+      if (close !== null && close[1]!.charAt(0) === openFence.char && close[1]!.length >= openFence.length) {
+        openFence = null
+      }
+      markdown.push(line)
+      continue
+    }
+    const fenceMatch = OPEN_FENCE_RE.exec(line)
+    if (fenceMatch !== null) {
+      const fence = fenceMatch[1]!
+      const rest = line.slice(fenceMatch.index + fenceMatch[0].length)
+      const info = fenceInfo(rest, fence)
+      if (info !== null) {
+        openFence = { char: fence.charAt(0), length: fence.length }
+        markdown.push(line)
+        continue
+      }
+      // Not a valid fence (backtick info containing backticks): plain text.
+      markdown.push(line)
+      continue
+    }
+
+    if (inComment) {
+      html.push(line)
+      if (line.includes('-->')) flushHtml()
+      continue
+    }
+    if (inHtmlRun) {
+      if (isBlank(line)) {
+        flushHtml()
+        continue
+      }
+      html.push(line)
+      continue
+    }
+
+    if (COMMENT_START_RE.test(line)) {
+      flushMarkdown()
+      html.push(line)
+      inComment = true
+      if (line.includes('-->')) flushHtml()
+      continue
+    }
+    const htmlMatch = HTML_BLOCK_START_RE.exec(line)
+    const tag = htmlMatch?.[1]?.toLowerCase()
+    if (htmlMatch !== null && tag !== undefined && HTML_BLOCK_TAGS.has(tag)) {
+      flushMarkdown()
+      html.push(line)
+      inHtmlRun = true
+      continue
+    }
+    // Blank lines only survive inside a markdown run (paragraph separators);
+    // at a run boundary they are separators and are dropped.
+    if (isBlank(line) && markdown.length === 0) continue
+    markdown.push(line)
+  }
+  flushMarkdown()
+  flushHtml()
+  return segments
+}
+
+/** A reference definition line: `[label]: destination` (up to 3 spaces indent). */
+const REFERENCE_DEF_RE = /^ {0,3}\[((?:[^\][]|\[[^\]]*\])*)\]:\s*(?:<([^<>]*)>|(\S+))/
+
+/**
+ * Collect the reference definitions of every markdown run (HTML runs cannot
+ * define them), in document order, newline-joined for appending.
+ */
+export function collectReferenceDefinitions(segments: readonly MdHtmlSegment[]): string {
+  const defs: string[] = []
+  for (const segment of segments) {
+    if (segment.kind !== 'markdown') continue
+    for (const line of segment.text.split('\n')) {
+      if (REFERENCE_DEF_RE.test(line)) defs.push(line)
+    }
+  }
+  return defs.join('\n')
+}
+
+/**
+ * The whole-document gate + split the preview consumes. `hasInlineHtml` is a
+ * cheap source-level regex (code-fence content may false-positive; the inline
+ * pass skips rendered code blocks anyway, so a false positive only costs the
+ * enhanced render path, never a behavior change).
+ */
+export function analyzeMarkdownHtml(text: string): AnalyzedMarkdownHtml {
+  const segments = splitHtmlBlocks(text)
+  return {
+    segments,
+    hasBlockHtml: segments.some((segment) => segment.kind === 'html'),
+    hasInlineHtml: TAGLIKE_RE.test(text),
+    referenceDefinitions: collectReferenceDefinitions(segments),
+  }
+}

package/src/client/markdown-images.ts

@@ -0,0 +1,137 @@
+/**
+ * Markdown-preview local-image resolution. The shared `MarkdownText` (from
+ * @deepseek-ai/dsh-client-ui-primitives) only renders absolute http(s) image
+ * URLs — relative links are disabled for chat security — so a local image in
+ * a previewed `.md` (`![alt](./img.png)`, an absolute `/cwd/img.png`, or a
+ * reference definition) would otherwise fall back to its alt text. This
+ * dependency-free helper rewrites those destinations into absolute
+ * `/sidebar/file` media URLs (prefixed with the GUI's own origin) so
+ * `MarkdownText` accepts them; the host media route then serves the bytes,
+ * still restricted to files under the session cwd.
+ */
+
+import type { SessionScope } from './api.ts'
+import { isAbsolutePath } from './paths.ts'
+
+/**
+ * True for a destination that is a remote URL — an absolute `scheme:` URL
+ * that is not a Windows drive path (`C:\...`). http/https/data/mailto etc.
+ * all match here and are handed back to `MarkdownText` untouched.
+ */
+function isRemoteUrl(dest: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:/i.test(dest) && !/^[A-Za-z]:[\\/]/.test(dest)
+}
+
+/**
+ * Collapse `.`/`..` segments of an absolute local path, preserving its root
+ * (POSIX `/`), its Windows drive (`C:\`), or its UNC `\\server\share`
+ * prefix. The host's `requireAbsolute` (`path.resolve`) normalizes anyway,
+ * but producing a canonical path here keeps the `/sidebar/file` URL clean.
+ */
+function normalizeLocalPath(path: string): string {
+  const drive = /^([A-Za-z]:)[\\/]/.exec(path)?.[1]
+  const body = drive !== undefined ? path.slice(drive.length) : path
+  const parts = body.split(/[\\/]+/).filter((segment) => segment !== '' && segment !== '.')
+  const out: string[] = []
+  for (const part of parts) {
+    if (part === '..') { out.pop(); continue }
+    out.push(part)
+  }
+  if (drive !== undefined) return `${drive}\\${out.join('\\')}`
+  const separator = path.startsWith('\\') ? '\\' : '/'
+  const root = path.startsWith('/') ? '/' : path.startsWith('\\') ? '\\\\' : ''
+  return `${root}${out.join(separator)}`
+}
+
+/**
+ * Rewrite markdown image destinations that point at local files into
+ * absolute `/sidebar/file` media URLs. Relative destinations resolve against
+ * the opened file's directory (normalizing `.`/`..` segments); absolute
+ * local paths pass through. Remote (http/https/data/mailto) and `#`-anchor
+ * destinations are left untouched for `MarkdownText`. Reference-style images
+ * (`![x][id]` + `[id]: url`) are covered by rewriting their definition lines.
+ *
+ * Code spans (`` `...` ``) and fenced code blocks (``` ```...``` ```) are
+ * masked before rewriting so documentation that demonstrates `![alt](./img.png)`
+ * is not mutated into a `/sidebar/file` URL. Reference definitions are only
+ * rewritten when their label is actually referenced by an image (collapsed
+ * `[![][id]]`, full `![alt][id]`, or shortcut `![]` referencing the next
+ * definition) — a plain link `[text][id]` must not have its destination
+ * redirected to the media route.
+ * @param text - The raw markdown source (inline + reference images).
+ * @param scope - The session scope (sessionId + cwd) for the media route.
+ * @param filePath - The absolute path of the opened `.md` file.
+ * @param origin - The GUI's own origin (`window.location.origin`); injected
+ * so the core rewrite stays pure and unit-testable.
+ * @returns The markdown with local image destinations rewritten in place.
+ */
+/**
+ * Resolve one media destination against the session's media route: local
+ * (relative or absolute) paths become absolute `/sidebar/file` URLs (prefixed
+ * with the GUI's own origin so the shared MarkdownText http(s) allowlist
+ * accepts them), while remote URLs, `#`-anchors and empty destinations are
+ * returned untouched. Shared by the markdown image rewriter below and by the
+ * preview's raw-HTML sanitizer (`markdown-html.tsx`, which meets the same
+ * allowlist when rendering `<img src="./x.png">` inside HTML blocks).
+ */
+export function resolveLocalMediaDest(
+  dest: string,
+  scope: SessionScope,
+  filePath: string,
+  origin: string,
+): string {
+  const trimmed = dest.trim()
+  if (trimmed === '' || trimmed.startsWith('#')) return dest
+  if (isRemoteUrl(trimmed)) return dest
+  const slash = Math.max(filePath.lastIndexOf('/'), filePath.lastIndexOf('\\'))
+  const directory = slash === -1 ? '/' : filePath.slice(0, slash + 1)
+  const candidate = isAbsolutePath(trimmed) ? trimmed : directory + trimmed
+  // Mirrors api.ts fileUrl/mediaUrl for the /sidebar/file media route, made
+  // absolute so the shared MarkdownText http(s) allowlist accepts it.
+  const params = new URLSearchParams({ sessionId: scope.sessionId, path: normalizeLocalPath(candidate) })
+  if (scope.cwd !== undefined && scope.cwd !== '') params.set('cwd', scope.cwd)
+  return `${origin}/sidebar/file?${params.toString()}`
+}
+
+export function rewriteLocalImageUrls(
+  text: string,
+  scope: SessionScope,
+  filePath: string,
+  origin: string,
+): string {
+  const resolve = (dest: string): string => resolveLocalMediaDest(dest, scope, filePath, origin)
+
+  // Mask fenced code blocks and inline code spans so image-looking text
+  // inside documentation examples is never rewritten. The sentinel uses a
+  // character unlikely to appear in prose; the original spans are restored
+  // after the image rewrite.
+  const masks: string[] = []
+  const masked = text
+    .replace(/```[\s\S]*?```/g, (block) => { masks.push(block); return `\u0000${masks.length - 1}\u0000` })
+    .replace(/`[^`\n]*`/g, (span) => { masks.push(span); return `\u0000${masks.length - 1}\u0000` })
+
+  const inline = masked.replace(/!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g, (_match, alt, dest) => {
+    return `![${alt}](${resolve(dest)})`
+  })
+
+  // Collect labels referenced by image syntax (full `![alt][id]` and
+  // collapsed `![][id]`) so only those reference definitions are rewritten.
+  // A shortcut reference (`![alt]` with no `[id]`) resolves to the label
+  // text `alt` itself; include it too. Plain links `[text][id]` never match
+  // the leading `!` and are left untouched.
+  const imageLabels = new Set<string>()
+  const labelRe = /!\[([^\]]*)\](?:\[((?:[^\][]|\[[^\]]*\])*)\])?/g
+  let labelMatch: RegExpExecArray | null
+  while ((labelMatch = labelRe.exec(inline)) !== null) {
+    const alt = labelMatch[1] ?? ''
+    const ref = labelMatch[2]
+    imageLabels.add(ref !== undefined && ref !== '' ? ref.toLowerCase() : alt.toLowerCase())
+  }
+
+  const refsRewritten = inline.replace(/^(\s*\[([^\]]+)\]:\s*)(<[^>]+>|[^\s]+)/gm, (match, head: string, label: string, dest: string) => {
+    if (!imageLabels.has(label.toLowerCase())) return match
+    return `${head}${resolve(dest.replace(/^<|>$/g, ''))}`
+  })
+
+  return refsRewritten.replace(/\u0000(\d+)\u0000/g, (_m, index: string) => masks[Number(index)] ?? '')
+}

package/src/client/markdown-labels.tsx

@@ -0,0 +1,52 @@
+/**
+ * Copy-button / chrome labels for DSH's shared `MarkdownText`, shaped for
+ * BOTH prop generations the plugin supports:
+ *
+ * - 0.1.1-rc.x: optional flat prop `codeLabels` — the renderer reads
+ *   `labels.copyLabel` / `labels.copiedLabel` directly.
+ * - 0.1.2-alpha.1+: renamed to a REQUIRED `labels` prop with a nested shape
+ *   (`labels.code.copyLabel` + a screen-reader-only `labels.footnotes`
+ *   heading). Passing only the old prop crashes the fence render with
+ *   "Cannot read properties of undefined (reading 'code')" — the exact
+ *   regression the mount lane caught on a real 0.1.2-alpha.1 host.
+ *
+ * The union object satisfies both readers, and {@link markdownTextProps}
+ * passes it under BOTH prop names — each host ignores the one it does not
+ * know. `footnotes` is left empty (the heading is sr-only; give it a real
+ * string only if a locale key ever earns its place in all 19 dictionaries).
+ */
+import type { ComponentProps } from 'react'
+import { MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
+
+/** The flat copy-button pair the plugin threads through its own props
+ *  (e.g. MermaidMarkdownProps.codeLabels — the chunk contract stays put). */
+export interface MarkdownCopyLabels {
+  copyLabel: string
+  copiedLabel: string
+}
+
+/** The dual-generation chrome labels object (see module doc). */
+export interface MarkdownChromeLabels extends MarkdownCopyLabels {
+  /** 0.1.2-alpha.1+ nested reads. */
+  code: MarkdownCopyLabels
+  /** 0.1.2-alpha.1+ sr-only footnotes heading. */
+  footnotes: string
+}
+
+/** Build the dual-shape chrome labels from a flat copy-button pair. */
+export function markdownChromeLabels(labels: MarkdownCopyLabels): MarkdownChromeLabels {
+  return {
+    copyLabel: labels.copyLabel,
+    copiedLabel: labels.copiedLabel,
+    code: { copyLabel: labels.copyLabel, copiedLabel: labels.copiedLabel },
+    footnotes: '',
+  }
+}
+
+/** MarkdownText props carrying the labels under BOTH prop names. The cast is
+ *  load-bearing: the plugin builds against the 0.1.1-rc.x declaration, where
+ *  `labels` does not exist yet (and vice versa on a 0.1.2-alpha.1+ host). */
+export function markdownTextProps(text: string, labels: MarkdownCopyLabels): ComponentProps<typeof MarkdownText> {
+  const chrome = markdownChromeLabels(labels)
+  return { text, codeLabels: chrome, labels: chrome } as unknown as ComponentProps<typeof MarkdownText>
+}

package/src/client/md-toc.tsx

@@ -0,0 +1,127 @@
+/**
+ * The markdown preview's table of contents: a sticky zero-height bar keeping
+ * a small "outline" button pinned at the top-right of the preview's scroll
+ * container, visible once the document has at least {@link TOC_MIN_HEADINGS}
+ * headings. The button opens a popover outline (h1–h6 collected from the
+ * rendered DOM — so headings inside HTML runs count too); clicking an entry
+ * expands any collapsed `<details>` ancestor, smooth-scrolls the heading into
+ * view and flashes it. The scan re-runs through a MutationObserver so late
+ * content (lazy mermaid chunk, shiki highlighting) is picked up.
+ *
+ * Mount contract: render as a DIRECT child of the scroll container it
+ * outlines. The container is discovered through the bar's own DOM position
+ * (`parentElement`), not a passed ref — React attaches a parent host
+ * element's ref only after its children's layout effects have run, so a
+ * ref-based container read here would see null at mount and never re-run.
+ * The bar itself renders unconditionally (zero height, pointer-events
+ * none), so it never affects the preview layout.
+ */
+import { useLayoutEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import { IconListPenOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { t } from './locales.ts'
+import css from './sidebar.module.css'
+
+/** Fewer headings than this and the button stays hidden (no outline value). */
+export const TOC_MIN_HEADINGS = 3
+
+/** One collected outline entry; `el` is the live rendered heading element. */
+interface TocEntry {
+  level: number
+  text: string
+  el: HTMLElement
+}
+
+/** The signature used to skip no-op rescans (identity-safe setState guard). */
+function signatureOf(entries: readonly TocEntry[]): string {
+  return entries.map((entry) => `${entry.level}:${entry.text}`).join('\n')
+}
+
+export function MdToc(): ReactNode {
+  const barRef = useRef<HTMLDivElement>(null)
+  const [entries, setEntries] = useState<TocEntry[]>([])
+  const [open, setOpen] = useState(false)
+  const signatureRef = useRef('')
+
+  useLayoutEffect(() => {
+    // The bar's own host ref is attached before this effect runs; the scroll
+    // container is its parent by the mount contract above.
+    const container = barRef.current?.parentElement ?? null
+    if (container === null) return
+    const scan = (): void => {
+      const found: TocEntry[] = []
+      for (const el of container.querySelectorAll<HTMLElement>('h1, h2, h3, h4, h5, h6')) {
+        const text = (el.textContent ?? '').trim()
+        if (text === '') continue
+        found.push({ level: Number(el.tagName.charAt(1)), text, el })
+      }
+      const signature = signatureOf(found)
+      if (signature === signatureRef.current) return
+      signatureRef.current = signature
+      setEntries(found)
+    }
+    scan()
+    const observer = new MutationObserver(() => { scan() })
+    observer.observe(container, { childList: true, subtree: true })
+    return () => { observer.disconnect() }
+  }, [])
+
+  // Esc closes the popover (the panel is a sibling of the button, so focus
+  // stays wherever the user came from — a document listener is the simplest).
+  useLayoutEffect(() => {
+    if (!open) return
+    const onKey = (event: KeyboardEvent): void => {
+      if (event.key === 'Escape') setOpen(false)
+    }
+    document.addEventListener('keydown', onKey)
+    return () => { document.removeEventListener('keydown', onKey) }
+  }, [open])
+
+  const jump = (entry: TocEntry): void => {
+    entry.el.closest('details:not([open])')?.setAttribute('open', '')
+    entry.el.scrollIntoView({ behavior: 'smooth', block: 'start' })
+    const el = entry.el
+    const flash = css.tocFlash
+    if (flash !== undefined) {
+      el.classList.add(flash)
+      window.setTimeout(() => { el.classList.remove(flash) }, 1200)
+    }
+    setOpen(false)
+  }
+
+  const showOutline = entries.length >= TOC_MIN_HEADINGS
+  return (
+    <div className={css.tocBar} ref={barRef}>
+      {open && showOutline && (
+        <div className={css.tocPanel} data-dsh-md-toc-panel>
+          {entries.map((entry, index) => (
+            <button
+              key={index}
+              type="button"
+              className={css.tocItem}
+              data-level={entry.level}
+              title={entry.text}
+              onClick={() => { jump(entry) }}
+            >
+              <span className={css.tocItemLevel}>{entry.level}</span>
+              <span className={css.tocItemText}>{entry.text}</span>
+            </button>
+          ))}
+        </div>
+      )}
+      {showOutline && (
+        <button
+          type="button"
+          className={css.tocButton}
+          data-dsh-md-toc=""
+          aria-label={t('toc')}
+          title={t('toc')}
+          aria-expanded={open}
+          onClick={() => { setOpen(!open) }}
+        >
+          <IconListPenOutline16 />
+        </button>
+      )}
+    </div>
+  )
+}