@lijian-ui/dsh-file-manager 0.1.20

package/src/client/preview/markdown.ts

@@ -0,0 +1,351 @@
+/**
+ * A compact markdown renderer for the preview panel: headings, paragraphs,
+ * fenced + inline code, bold/italic, links/images, lists, blockquotes, hr,
+ * and tables. All HTML is escaped before transformation — the output only
+ * ever contains the renderer's own tags. Pure and exported for tests.
+ * @module dsh-filemgr/client/preview/markdown
+ */
+
+/** Escape HTML special characters. */
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+/** How one image src resolves against the markdown file's location. */
+export type MarkdownImageResolution =
+  /** Scheme URL or fragment: the browser resolves it as-is. */
+  | { kind: 'absolute' }
+  /** Workspace-relative target: resolved path plus any ?query#fragment suffix. */
+  | { kind: 'relative'; path: string; suffix: string }
+  /** `..` escaped the project root: the image must be dropped. */
+  | { kind: 'escape' }
+
+/** Directory of a workspace-relative file path ('' when at the root). */
+function dirOf(filePath: string): string {
+  const slash = filePath.lastIndexOf('/')
+  return slash === -1 ? '' : filePath.slice(0, slash)
+}
+
+/** Collapse . and .. segments; null when .. escapes the base. */
+function normalizeRelPath(rel: string): string | null {
+  const out: string[] = []
+  for (const part of rel.split('/')) {
+    if (part === '' || part === '.') continue
+    if (part === '..') {
+      if (out.length === 0) return null
+      out.pop()
+      continue
+    }
+    out.push(part)
+  }
+  return out.join('/')
+}
+
+/** Percent-decode a path portion (best effort; never throws). */
+function decodePathPart(raw: string): string {
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    return raw
+  }
+}
+
+/**
+ * Resolve one markdown image src against the markdown file's location:
+ * - Absolute URLs (http/https/data:/...) and fragment-only srcs are left to
+ *   the browser ('absolute').
+ * - Root-relative srcs (/img.png) resolve from the project root; other
+ *   relative srcs resolve against the file's directory. `..` escaping the
+ *   project root is rejected ('escape').
+ * - The path portion is percent-decoded (markdown authors encode spaces in
+ *   filenames) and any ?query#fragment suffix is preserved verbatim, so
+ *   cache-busting srcs like ./img.png?v=2 still fetch img.png.
+ */
+export function resolveMarkdownImage(filePath: string, src: string): MarkdownImageResolution {
+  const trimmed = src.trim()
+  if (trimmed === '' || trimmed.startsWith('#')) return { kind: 'absolute' }
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed)) return { kind: 'absolute' }
+  const decoded = decodePathPart(trimmed)
+  const q = decoded.indexOf('?')
+  const h = decoded.indexOf('#')
+  let cut = decoded.length
+  if (q !== -1) cut = Math.min(cut, q)
+  if (h !== -1) cut = Math.min(cut, h)
+  const pathPart = decoded.slice(0, cut)
+  const suffix = decoded.slice(cut)
+  const base = pathPart.startsWith('/') ? '' : dirOf(filePath)
+  const joined = base === '' ? pathPart : `${base}/${pathPart}`
+  const normalized = normalizeRelPath(joined)
+  if (normalized === null) return { kind: 'escape' }
+  return { kind: 'relative', path: normalized, suffix }
+}
+
+/** Options controlling markdown rendering. */
+export interface MarkdownRenderOptions {
+  /**
+   * Rewrite image srcs before they are emitted. Return the URL to use, or
+   * null to drop the image (alt text only). Relative workspace paths are
+   * typically resolved to absolute URLs here.
+   */
+  resolveImageSrc?: (src: string) => string | null
+}
+
+/**
+ * Guard a raw link/image target against dangerous protocols. Returns the
+ * (trimmed) raw string when safe, else null. Only these schemes are allowed:
+ * http:, https:, mailto: and fragment anchors (#...). Scheme-less relative
+ * paths (./ ../ / and plain filenames) pass through unchanged. Anything with
+ * a scheme outside the allow-list — javascript:, data:, vbscript:, etc. —
+ * is rejected so the value never reaches dangerouslySetInnerHTML.
+ */
+export function safeUrl(raw: string): string | null {
+  const trimmed = raw.trim()
+  if (trimmed === '') return null
+  if (trimmed.startsWith('#')) return trimmed
+  const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(trimmed)
+  if (scheme === null) return trimmed
+  const name = scheme[1].toLowerCase()
+  return name === 'http' || name === 'https' || name === 'mailto' ? trimmed : null
+}
+
+/** Inline pass: code spans, bold, italic, images, links. */
+export function renderInline(text: string, options?: MarkdownRenderOptions): string {
+  let out = ''
+  let i = 0
+  const n = text.length
+  while (i < n) {
+    const char = text[i]
+    // Fenced inline code first.
+    if (char === '`') {
+      const end = text.indexOf('`', i + 1)
+      if (end !== -1) {
+        out += `<code>${escapeHtml(text.slice(i + 1, end))}</code>`
+        i = end + 1
+        continue
+      }
+    }
+    // Image ![alt](src)
+    if (char === '!' && text[i + 1] === '[') {
+      const close = text.indexOf('](', i + 2)
+      if (close !== -1) {
+        const parenEnd = text.indexOf(')', close + 2)
+        if (parenEnd !== -1) {
+          const alt = text.slice(i + 2, close)
+          const src = text.slice(close + 2, parenEnd)
+          const safe = safeUrl(src)
+          if (safe === null) {
+            // Unsafe image target: drop the img, keep the alt text.
+            out += escapeHtml(alt)
+          } else {
+            let target: string | null = safe
+            if (options?.resolveImageSrc !== undefined) {
+              target = options.resolveImageSrc(safe)
+            }
+            if (target === null) {
+              // The resolver dropped the image (unresolvable path): alt only.
+              out += escapeHtml(alt)
+            } else {
+              const srcEsc = escapeHtml(target).replace(/\s+/g, '%20')
+              out += `<img alt="${escapeHtml(alt)}" src="${srcEsc}" />`
+            }
+          }
+          i = parenEnd + 1
+          continue
+        }
+      }
+    }
+    // Link [text](href)
+    if (char === '[') {
+      const close = text.indexOf('](', i + 1)
+      if (close !== -1) {
+        const parenEnd = text.indexOf(')', close + 2)
+        if (parenEnd !== -1) {
+          const label = text.slice(i + 1, close)
+          const href = text.slice(close + 2, parenEnd)
+          const safe = safeUrl(href)
+          if (safe === null) {
+            // Unsafe link target: render the label as plain text, no <a>.
+            out += renderInline(label, options)
+          } else {
+            out += `<a href="${escapeHtml(safe)}" target="_blank" rel="noopener noreferrer">${renderInline(label, options)}</a>`
+          }
+          i = parenEnd + 1
+          continue
+        }
+      }
+    }
+    // Bold **text**
+    if (char === '*' && text[i + 1] === '*') {
+      const end = text.indexOf('**', i + 2)
+      if (end !== -1) {
+        out += `<strong>${renderInline(text.slice(i + 2, end), options)}</strong>`
+        i = end + 2
+        continue
+      }
+    }
+    // Italic *text*
+    if (char === '*' && text[i - 1] !== '*' && text[i + 1] !== '*') {
+      const end = text.indexOf('*', i + 1)
+      if (end !== -1 && text[end + 1] !== '*') {
+        out += `<em>${renderInline(text.slice(i + 1, end), options)}</em>`
+        i = end + 1
+        continue
+      }
+    }
+    // Strikethrough ~~text~~
+    if (char === '~' && text[i + 1] === '~') {
+      const end = text.indexOf('~~', i + 2)
+      if (end !== -1) {
+        out += `<del>${renderInline(text.slice(i + 2, end), options)}</del>`
+        i = end + 2
+        continue
+      }
+    }
+    out += escapeHtml(char)
+    i += 1
+  }
+  return out
+}
+
+/** Render a markdown document to HTML (block pass). */
+export function renderMarkdown(source: string, options?: MarkdownRenderOptions): string {
+  const lines = source.replace(/\r\n/g, '\n').split('\n')
+  const out: string[] = []
+  let i = 0
+  const n = lines.length
+
+  const flushParagraph = (buffer: string[]): void => {
+    if (buffer.length === 0) return
+    out.push(`<p>${renderInline(buffer.join("\n"), options)}</p>`)
+    buffer.length = 0
+  }
+
+  let paragraph: string[] = []
+  while (i < n) {
+    const line = lines[i]
+
+    // Fenced code block.
+    const fence = /^```([\w+-]*)\s*$/.exec(line)
+    if (fence !== null) {
+      flushParagraph(paragraph)
+      const lang = fence[1] ?? ''
+      i += 1
+      const code: string[] = []
+      while (i < n && !/^```\s*$/.test(lines[i])) {
+        code.push(lines[i])
+        i += 1
+      }
+      i += 1 // closing fence
+      const langAttr = lang === '' ? '' : ` class="language-${escapeHtml(lang)}"`
+      out.push(`<pre${langAttr}><code>${escapeHtml(code.join('\n'))}</code></pre>`)
+      continue
+    }
+
+    // Heading.
+    const heading = /^(#{1,6})\s+(.*)$/.exec(line)
+    if (heading !== null) {
+      flushParagraph(paragraph)
+      const level = heading[1].length
+      out.push(`<h${level}>${renderInline(heading[2] ?? '', options)}</h${level}>`)
+      i += 1
+      continue
+    }
+
+    // Horizontal rule.
+    if (/^\s*(---+|\*\*\*+|___+)\s*$/.test(line)) {
+      flushParagraph(paragraph)
+      out.push('<hr />')
+      i += 1
+      continue
+    }
+
+    // Table: header row then separator row.
+    if (line.includes('|') && i + 1 < n && /^\s*\|?[\s:|-]+\|?\s*$/.test(lines[i + 1]) && lines[i + 1].includes('-')) {
+      flushParagraph(paragraph)
+      const headerCells = splitTableRow(line)
+      i += 2
+      const rows: string[][] = []
+      while (i < n && lines[i].includes('|')) {
+        rows.push(splitTableRow(lines[i]))
+        i += 1
+      }
+      out.push('<table>')
+      out.push(`<thead><tr>${headerCells.map((cell) => `<th>${renderInline(cell, options)}</th>`).join('')}</tr></thead>`)
+      if (rows.length > 0) {
+        out.push(`<tbody>${rows.map((row) => `<tr>${row.map((cell) => `<td>${renderInline(cell, options)}</td>`).join('')}</tr>`).join('')}</tbody>`)
+      }
+      out.push('</table>')
+      continue
+    }
+
+    // Blockquote (one level).
+    const quote = /^>\s?(.*)$/.exec(line)
+    if (quote !== null) {
+      flushParagraph(paragraph)
+      const body: string[] = []
+      while (i < n) {
+        const q = /^>\s?(.*)$/.exec(lines[i])
+        if (q === null) break
+        body.push(q[1] ?? '')
+        i += 1
+      }
+      out.push(`<blockquote><p>${body.map((line) => renderInline(line, options)).join('<br />')}</p></blockquote>`)
+      continue
+    }
+
+    // Unordered list.
+    const ul = /^\s*([-*+])\s+(.*)$/.exec(line)
+    if (ul !== null) {
+      flushParagraph(paragraph)
+      const items: string[] = []
+      while (i < n) {
+        const item = /^\s*([-*+])\s+(.*)$/.exec(lines[i])
+        if (item === null) break
+        items.push(`<li>${renderInline(item[2] ?? '', options)}</li>`)
+        i += 1
+      }
+      out.push(`<ul>${items.join('')}</ul>`)
+      continue
+    }
+
+    // Ordered list.
+    const ol = /^\s*\d+[.)]\s+(.*)$/.exec(line)
+    if (ol !== null) {
+      flushParagraph(paragraph)
+      const items: string[] = []
+      while (i < n) {
+        const item = /^\s*\d+[.)]\s+(.*)$/.exec(lines[i])
+        if (item === null) break
+        items.push(`<li>${renderInline(item[1] ?? '', options)}</li>`)
+        i += 1
+      }
+      out.push(`<ol>${items.join('')}</ol>`)
+      continue
+    }
+
+    // Blank line: flush the paragraph.
+    if (line.trim() === '') {
+      flushParagraph(paragraph)
+      i += 1
+      continue
+    }
+
+    paragraph.push(line)
+    i += 1
+  }
+  flushParagraph(paragraph)
+  return out.join('\n')
+}
+
+/** Split one table row into cells (respecting the leading/trailing pipes). */
+function splitTableRow(line: string): string[] {
+  const trimmed = line.trim()
+  const inner = trimmed.startsWith('|') ? trimmed.slice(1) : trimmed
+  const withoutTrailing = inner.endsWith('|') ? inner.slice(0, -1) : inner
+  return withoutTrailing.split('|').map((cell) => cell.trim())
+}

package/src/client/preview/mermaid.ts

@@ -0,0 +1,274 @@
+/**
+ * Mermaid diagram enhancement for markdown surfaces: lazily loads the
+ * mermaid runtime from the host vendor route (same origin, no CDN), renders
+ * every fenced ```mermaid code block in place, and re-renders on theme
+ * flips. Framework-free so both the preview panel (React effect) and the
+ * chat transcript observer can drive it over disjoint DOM scopes.
+ *
+ * Failure policy: any load/render failure leaves the original code block
+ * untouched (or restores it verbatim); nothing here throws to the caller.
+ * @module dsh-filemgr/client/preview/mermaid
+ */
+
+/** Minimal structural type of the mermaid runtime this module consumes. */
+interface MermaidRuntime {
+  initialize: (config: Record<string, unknown>) => void
+  render: (id: string, text: string, container?: HTMLElement) => Promise<{ svg: string }>
+}
+
+/** Host-served mermaid IIFE bundle (lib/assets/mermaid.min.js behind the route). */
+export const MERMAID_VENDOR_URL = '/filemgr/vendor/mermaid.js'
+
+/** Lifecycle state stamped on diagram containers (`pending`/`rendering`/`done`). */
+const DATA_STATE = 'data-mermaid-state'
+
+/** State stamped on a code block once its container exists (`claimed`). */
+const DATA_CLAIMED = 'data-mermaid-claimed'
+
+/** The verbatim diagram source kept on the container for theme re-renders. */
+const DATA_SOURCE = 'data-mermaid-source'
+
+/** Marker the preview viewer stamps on its own subtree (chat enhancement skips it). */
+export const DATA_MD_SCOPE = 'data-filemgr-md-scope'
+
+let loadPromise: Promise<MermaidRuntime> | undefined
+
+/**
+ * Resolve the mermaid global left by the vendor IIFE bundle, or null while
+ * absent. Narrow and defensive: the bundle is a third-party artifact.
+ */
+function mermaidGlobal(): MermaidRuntime | null {
+  const candidate = (globalThis as Record<string, unknown>).mermaid
+  if (typeof candidate !== 'object' || candidate === null) return null
+  const checked = candidate as Record<string, unknown>
+  if (typeof checked.initialize !== 'function' || typeof checked.render !== 'function') return null
+  return checked as unknown as MermaidRuntime
+}
+
+/**
+ * Load the mermaid runtime once per page: injects a <script> for the host
+ * vendor route and resolves with the runtime. Concurrent callers share one
+ * injection; a failure clears the cache so a later surface can retry.
+ */
+export function loadMermaidLibrary(): Promise<MermaidRuntime> {
+  const existing = mermaidGlobal()
+  if (existing !== null) return Promise.resolve(existing)
+  if (loadPromise !== undefined) return loadPromise
+  loadPromise = new Promise<MermaidRuntime>((resolve, reject) => {
+    const script = document.createElement('script')
+    script.src = MERMAID_VENDOR_URL
+    script.async = true
+    script.onload = () => {
+      const runtime = mermaidGlobal()
+      if (runtime === null) {
+        loadPromise = undefined
+        reject(new Error('mermaid vendor script loaded but window.mermaid is missing'))
+        return
+      }
+      resolve(runtime)
+    }
+    script.onerror = () => {
+      loadPromise = undefined
+      reject(new Error(`failed to load ${MERMAID_VENDOR_URL}`))
+    }
+    document.head.appendChild(script)
+  })
+  return loadPromise
+}
+
+/** Mermaid theme name for the shell theme marker (`default` or `dark`). */
+export function mermaidTheme(isDark: boolean): 'default' | 'dark' {
+  return isDark ? 'dark' : 'default'
+}
+
+/** Whether the shell currently carries the dark marker attribute. */
+export function shellIsDark(): boolean {
+  return document.body.hasAttribute('data-ds-dark-theme')
+}
+
+/** Monotonic id source for render calls (mermaid keys its <svg> by id). */
+let renderSeq = 0
+
+/**
+ * Configure the mermaid runtime for the current theme. Called once per
+ * render batch (enhance or retheme), not per diagram, so a surface with
+ * many diagrams initializes the runtime a single time.
+ */
+function initializeRuntime(runtime: MermaidRuntime, theme: string): void {
+  runtime.initialize({
+    startOnLoad: false,
+    theme,
+    securityLevel: 'strict',
+    fontFamily: '"trebuchet ms", verdana, arial, sans-serif',
+  })
+}
+
+/** Render one diagram source to SVG with the already-initialized runtime. */
+async function renderSvg(runtime: MermaidRuntime, source: string): Promise<string> {
+  const { svg } = await runtime.render(`filemgr-mermaid-${(renderSeq += 1)}`, source)
+  return svg
+}
+
+/** Disallowed elements removed from mermaid SVG output before innerHTML. */
+const DISALLOWED_ELEMENTS = ['script', 'foreignObject', 'iframe', 'object', 'embed']
+
+/** Whether an attribute name is an { on* } event-handler (case-insensitive). */
+function isEventHandler(name: string): boolean {
+  return /^on/i.test(name)
+}
+
+/** Whether an href/xlink:href value carries an executable javascript: URL. */
+function isDangerousHref(value: string): boolean {
+  return /^javascript:/i.test(value.trim())
+}
+
+/**
+ * Application-level defense-in-depth on top of mermaid's own strict-mode
+ * escaping: parse the rendered SVG in a detached container, remove disallowed
+ * elements and dangerous attributes, and return the serialized cleaned markup.
+ * Throws when the input cannot be parsed as markup or still carries dangerous
+ * raw tokens, so callers fall back to their failure path.
+ */
+export function sanitizeSvg(svg: string): string {
+  const template = document.createElement('template')
+  template.innerHTML = svg
+  const root = template.content
+
+  // Remove disallowed elements; loop because removals can expose nested ones.
+  for (let found = true; found; ) {
+    found = false
+    for (const el of Array.from(root.querySelectorAll('*'))) {
+      if (DISALLOWED_ELEMENTS.some((tag) => el.tagName.toLowerCase() === tag.toLowerCase())) {
+        el.remove()
+        found = true
+      }
+    }
+  }
+
+  // Strip event-handler attributes and javascript: hrefs from every element.
+  for (const el of Array.from(root.querySelectorAll('*'))) {
+    for (const attr of Array.from(el.attributes)) {
+      if (isEventHandler(attr.name) || isDangerousHref(attr.value)) el.removeAttribute(attr.name)
+    }
+  }
+
+  const cleaned = template.innerHTML
+  const lower = cleaned.toLowerCase()
+  if (lower.includes('<script') || lower.includes('javascript:')) {
+    throw new Error('mermaid SVG still contains dangerous tokens after sanitization')
+  }
+  return cleaned
+}
+
+/**
+ * Collect the still-unclaimed fenced mermaid code blocks under one scope.
+ * Both shapes are found: the panel renderer's `pre.language-mermaid` and
+ * the chat renderer's `pre > code.language-mermaid` (the claim always
+ * targets the <pre>). Empty blocks and blocks another driver already
+ * claimed are skipped. Pure (DOM-read only) so tests can drive it in jsdom.
+ */
+export function findMermaidCodeBlocks(scope: ParentNode): HTMLPreElement[] {
+  const found: HTMLPreElement[] = []
+  const seen = new Set<Element>()
+  for (const el of Array.from(scope.querySelectorAll('pre.language-mermaid, code.language-mermaid'))) {
+    const pre = el instanceof HTMLPreElement ? el : el.parentElement
+    if (pre === null || !(pre instanceof HTMLPreElement)) continue
+    if (seen.has(pre)) continue
+    seen.add(pre)
+    if (pre.hasAttribute(DATA_CLAIMED)) continue
+    if ((pre.textContent ?? '').trim() === '') continue
+    found.push(pre)
+  }
+  return found
+}
+
+/**
+ * Swap one code block for a diagram container. The original <pre> stays in
+ * the tree (hidden once the render lands) so a failure can restore it
+ * verbatim; the container carries the source for theme re-renders.
+ */
+function claimBlock(pre: HTMLPreElement, className: string): HTMLElement {
+  pre.setAttribute(DATA_CLAIMED, '1')
+  const container = document.createElement('div')
+  container.className = className
+  container.setAttribute(DATA_STATE, 'pending')
+  container.setAttribute(DATA_SOURCE, pre.textContent ?? '')
+  pre.insertAdjacentElement('afterend', container)
+  return container
+}
+
+/** Options for {@link enhanceMermaidBlocks}. */
+export interface EnhanceOptions {
+  /** Class for the diagram container (a CSS module export). */
+  className: string
+  /** Resolved mermaid theme name. */
+  theme: string
+  /** Optional extra exclusion for scopes another driver owns. */
+  skip?: (pre: HTMLPreElement) => boolean
+}
+
+/**
+ * Render every unclaimed ```mermaid block under `scope` into an inline SVG
+ * diagram. Idempotent per block across drivers (claimed blocks are skipped);
+ * failures restore the original code block. Never rejects.
+ */
+export async function enhanceMermaidBlocks(scope: ParentNode, options: EnhanceOptions): Promise<void> {
+  let runtime: MermaidRuntime
+  try {
+    runtime = await loadMermaidLibrary()
+  } catch {
+    return // no vendor route (asset missing): keep plain code blocks
+  }
+  initializeRuntime(runtime, options.theme)
+  const jobs: Array<Promise<void>> = []
+  for (const pre of findMermaidCodeBlocks(scope)) {
+    if (options.skip?.(pre) === true) continue
+    const container = claimBlock(pre, options.className)
+    jobs.push((async () => {
+      try {
+        container.setAttribute(DATA_STATE, 'rendering')
+        const source = container.getAttribute(DATA_SOURCE) ?? ''
+        const svg = await renderSvg(runtime, source)
+        container.innerHTML = sanitizeSvg(svg)
+        container.setAttribute(DATA_STATE, 'done')
+        pre.style.display = 'none'
+      } catch {
+        // Syntax error or render failure: restore the untouched code block.
+        container.remove()
+        pre.removeAttribute(DATA_CLAIMED)
+      }
+    })())
+  }
+  await Promise.all(jobs)
+}
+
+/**
+ * Re-render every completed diagram container under `scope` after a theme
+ * flip (stored sources re-render with the new theme). Containers not in the
+ * `done` state are skipped; a failure keeps the previous render.
+ */
+export async function rethemeMermaidBlocks(scope: ParentNode, options: { theme: string }): Promise<void> {
+  const runtime = mermaidGlobal()
+  if (runtime === null) return
+  initializeRuntime(runtime, options.theme)
+  const containers = Array.from(scope.querySelectorAll<HTMLElement>('[data-mermaid-state="done"]'))
+  await Promise.all(containers.map(async (container) => {
+    const source = container.getAttribute(DATA_SOURCE) ?? ''
+    try {
+      const svg = await renderSvg(runtime, source)
+      container.innerHTML = sanitizeSvg(svg)
+    } catch {
+      // Keep the previous render; a theme flip must not blank diagrams.
+    }
+  }))
+}
+
+/**
+ * One dark-marker watcher per surface: fires on body attribute flips so the
+ * caller can retheme. Returns the disposer.
+ */
+export function watchShellTheme(onChange: (isDark: boolean) => void): () => void {
+  const observer = new MutationObserver(() => { onChange(shellIsDark()) })
+  observer.observe(document.body, { attributes: true, attributeFilter: ['data-ds-dark-theme'] })
+  return () => { observer.disconnect() }
+}