dsh-codinput 0.3.8 → 0.4.0

package/src/client/markdown/heavy.ts

@@ -0,0 +1,159 @@
+/**
+ * 扩展渲染 Heavy 扩展的统一注册入口 + 自有 CSS。
+ *
+ * 三个 registry 扩展（基础渲染 `registerMarkdownExtension`）：
+ * - `dci-heavy-code`    —— marked.renderer.code 覆盖（highlight.js 高亮 + 语言标签
+ *                           + 复制按钮），activate 里挂复制事件委托；
+ * - `dci-heavy-math`    —— marked 行内/块级 `$...$` 占位扩展，activate 里同步
+ *                           `katex.renderToString` 替换（字体 CSS 全内置）；
+ * - `dci-heavy-mermaid` —— 只做 allowAttrs（占位属性）+ activate 异步渲染 SVG。
+ *
+ * 调用点：`src/client/index.tsx` 的 apply() 里调一次（幂等，返回注销函数）。
+ * CSS 由 `src/client/styles.ts` 追加拼接（本模块只导出字符串，不自己注入全局样式，
+ * 避免与 基础渲染的样式注入顺序打架）；KaTeX 自带 CSS 在首次用到公式时懒注入。
+ */
+
+import { registerMarkdownExtension } from './index';
+import { activateCodeBlocks, renderCodeBlock } from './code';
+import { activateMath, mathMarkedExtensions } from './math';
+import { activateMermaid } from './mermaid';
+
+let disposer: (() => void) | null = null;
+
+/**
+ * 注册 扩展渲染的三个渲染扩展（幂等）。
+ * @returns 注销函数（再次注册会先复用同一个注册集）。
+ */
+export function registerHeavyMarkdown(): () => void {
+  if (disposer) return disposer;
+  const offs: (() => void)[] = [];
+  try {
+    offs.push(
+      registerMarkdownExtension({
+        name: 'dci-heavy-code',
+        marked: { renderer: { code: renderCodeBlock } },
+        activate: activateCodeBlocks,
+      }),
+    );
+    offs.push(
+      registerMarkdownExtension({
+        name: 'dci-heavy-math',
+        marked: { extensions: mathMarkedExtensions },
+        allowAttrs: ['data-dci-md-math', 'data-dci-md-display'],
+        activate: activateMath,
+      }),
+    );
+    offs.push(
+      registerMarkdownExtension({
+        name: 'dci-heavy-mermaid',
+        allowAttrs: ['data-dci-md-mermaid', 'data-dci-md-state'],
+        activate: activateMermaid,
+      }),
+    );
+  } catch (error) {
+    for (const off of offs) {
+      try {
+        off();
+      } catch {
+        // 回滚失败不掩盖原始错误。
+      }
+    }
+    throw error;
+  }
+  disposer = () => {
+    for (const off of offs) {
+      try {
+        off();
+      } catch {
+        // 注销异常不应中断组件卸载。
+      }
+    }
+    disposer = null;
+  };
+  return disposer;
+}
+
+/** 扩展渲染 自有样式（追加在 基础渲染 markdownStyles 之后，不动既有段）。 */
+export const heavyMarkdownStyles = `
+/* ===== 扩展渲染：代码块（highlight.js + 语言标签 + 复制按钮）===== */
+.dci-md .dci-md-codeblock { margin: 0.7em 0; border-radius: var(--dsw-radius-sm, 8px); overflow: hidden;
+  background: var(--dsw-alias-markdown-code-block, color-mix(in srgb, currentColor 6%, transparent));
+  border: 0.5px solid var(--dsw-alias-border-l1, color-mix(in srgb, currentColor 12%, transparent)); }
+.dci-md .dci-md-codebar { display: flex; align-items: center; justify-content: space-between; gap: 8px;
+  padding: 3px 8px 3px 10px; border-bottom: 0.5px solid var(--dsw-alias-border-l1, color-mix(in srgb, currentColor 10%, transparent));
+  font-size: 11px; line-height: 16px; color: var(--dsw-alias-label-tertiary, color-mix(in srgb, currentColor 62%, transparent)); }
+.dci-md .dci-md-codelang { font-family: var(--ds-font-family-code, ui-monospace, monospace); letter-spacing: 0.02em; }
+.dci-md .dci-md-copy { display: inline-flex; align-items: center; gap: 4px; padding: 1px 6px; border: none; border-radius: 5px;
+  background: transparent; color: inherit; font: inherit; cursor: pointer; transition: color 0.12s, background-color 0.12s; }
+.dci-md .dci-md-copy:hover { background: var(--dsw-alias-interactive-bg-hover, color-mix(in srgb, currentColor 10%, transparent));
+  color: var(--dsw-alias-label-primary, currentColor); }
+.dci-md .dci-md-copy:focus-visible { outline: 2px solid var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary, #4c8dff)); outline-offset: 1px; }
+.dci-md .dci-md-copy-glyph { width: 12px; height: 12px; flex: none; background-color: currentColor;
+  -webkit-mask: var(--dci-md-icon-copy) center / 12px 12px no-repeat; mask: var(--dci-md-icon-copy) center / 12px 12px no-repeat; }
+.dci-md .dci-md-copy[data-dci-copied='true'] { color: var(--dsw-alias-state-success-primary, #2f9e6e); }
+.dci-md .dci-md-copy[data-dci-copied='true'] .dci-md-copy-glyph {
+  -webkit-mask-image: var(--dci-md-icon-check); mask-image: var(--dci-md-icon-check); }
+.dci-md .dci-md-copy-text { white-space: nowrap; }
+.dci-md .dci-md-pre { margin: 0; padding: 10px 12px; overflow-x: auto; overflow-y: hidden; background: transparent;
+  border: 0; border-radius: 0; font-family: var(--ds-font-family-code, ui-monospace, monospace); font-size: 12px; line-height: 1.55; }
+.dci-md .dci-md-pre code { padding: 0; border: 0; background: transparent; font: inherit; white-space: pre; }
+
+/* highlight.js token 配色：全部走宿主 --dsw-* 语义 token，浅/深色自动适配；
+   token 缺失时用 currentColor 混合回退，保证可读。 */
+.dci-md .hljs { color: var(--dsw-alias-label-primary, currentColor); background: transparent; }
+.dci-md .hljs-comment, .dci-md .hljs-quote { color: var(--dsw-alias-label-tertiary, color-mix(in srgb, currentColor 55%, transparent)); font-style: italic; }
+.dci-md .hljs-keyword, .dci-md .hljs-selector-tag, .dci-md .hljs-literal, .dci-md .hljs-doctag,
+.dci-md .hljs-name, .dci-md .hljs-tag { color: var(--dsw-alias-state-business-primary, #79a7ff); }
+.dci-md .hljs-string, .dci-md .hljs-regexp, .dci-md .hljs-addition, .dci-md .hljs-attribute,
+.dci-md .hljs-meta .hljs-string, .dci-md .hljs-template-tag { color: var(--dsw-alias-state-success-primary, #6fcf97); }
+.dci-md .hljs-number, .dci-md .hljs-symbol, .dci-md .hljs-bullet, .dci-md .hljs-variable,
+.dci-md .hljs-template-variable, .dci-md .hljs-selector-attr, .dci-md .hljs-selector-pseudo,
+.dci-md .hljs-link { color: var(--dsw-alias-state-warn-primary, #e5b567); }
+.dci-md .hljs-title, .dci-md .hljs-title.class_, .dci-md .hljs-title.function_, .dci-md .hljs-section,
+.dci-md .hljs-selector-id { color: var(--dsw-alias-state-business-primary, #79a7ff); font-weight: 600; }
+.dci-md .hljs-attr, .dci-md .hljs-property, .dci-md .hljs-params, .dci-md .hljs-subst { color: var(--dsw-alias-label-primary, currentColor); }
+.dci-md .hljs-built_in, .dci-md .hljs-type, .dci-md .hljs-class .hljs-title { color: var(--dsw-alias-state-success-primary, #6fcf97); }
+.dci-md .hljs-meta { color: var(--dsw-alias-label-tertiary, color-mix(in srgb, currentColor 58%, transparent)); }
+.dci-md .hljs-deletion { color: var(--dsw-alias-state-error-primary, #e5484d); }
+.dci-md .hljs-emphasis { font-style: italic; }
+.dci-md .hljs-strong { font-weight: 700; }
+
+/* ===== 扩展渲染：KaTeX 数学（公式 CSS 本体懒注入，这里只做容器与主题微调）===== */
+.dci-md .dci-md-math-inline { display: inline; }
+.dci-md .dci-md-math-block { display: block; margin: 0.65em 0; text-align: center; overflow-x: auto; overflow-y: hidden; }
+.dci-md .katex { font-size: 1.06em; }
+.dci-md .katex-display { margin: 0.35em 0; }
+.dci-md .dci-md-math-error { display: inline-block; max-width: 100%; padding: 1px 5px; border-radius: 4px;
+  color: var(--dsw-alias-state-error-primary, #e5484d);
+  background: color-mix(in srgb, var(--dsw-alias-state-error-primary, #e5484d) 10%, transparent);
+  font-family: var(--ds-font-family-code, ui-monospace, monospace); font-size: 0.92em; white-space: pre-wrap; overflow-wrap: anywhere; }
+.dci-md .dci-md-math-block.dci-md-math-error { display: block; text-align: left; padding: 6px 8px; }
+
+/* ===== 扩展渲染：Mermaid（占位源码 → 异步 SVG / 错误回退）===== */
+.dci-md .dci-md-mermaid { position: relative; margin: 0.7em 0; border-radius: var(--dsw-radius-sm, 8px);
+  border: 0.5px solid var(--dsw-alias-border-l1, color-mix(in srgb, currentColor 12%, transparent));
+  background: var(--dsw-alias-markdown-code-block, color-mix(in srgb, currentColor 4%, transparent));
+  overflow-x: auto; overflow-y: hidden; }
+.dci-md .dci-md-mermaid[data-dci-md-state='rendered'] { display: flex; justify-content: center; padding: 6px 8px;
+  border-color: transparent; background: transparent; }
+.dci-md .dci-md-mermaid[data-dci-md-state='rendered'] svg { max-width: 100%; height: auto; }
+.dci-md .dci-md-mermaid[data-dci-md-state='rendered'] .dci-md-mermaid-pending { display: none; }
+.dci-md .dci-md-mermaid[data-dci-md-state='error'] { padding: 8px 10px;
+  border-left: 3px solid var(--dsw-alias-state-error-primary, #e5484d); }
+.dci-md .dci-md-mermaid-badge { display: inline-block; margin: 0 0 2px 10px; padding: 1px 6px; border-radius: 999px;
+  font-family: var(--ds-font-family-code, ui-monospace, monospace); font-size: 10px; line-height: 14px;
+  color: var(--dsw-alias-state-business-primary, #79a7ff);
+  background: color-mix(in srgb, var(--dsw-alias-state-business-primary, #79a7ff) 14%, transparent); }
+.dci-md .dci-md-mermaid-pending .dci-md-pre { padding-top: 4px; }
+.dci-md .dci-md-mermaid[data-dci-md-state='rendering'] .dci-md-mermaid-badge { opacity: 0.65; }
+.dci-md .dci-md-mermaid-error { color: var(--dsw-alias-label-primary, currentColor); }
+.dci-md .dci-md-mermaid-error-head { font-size: 12px; font-weight: 600; line-height: 18px;
+  color: var(--dsw-alias-state-error-primary, #e5484d); }
+.dci-md .dci-md-mermaid-error-msg { margin: 2px 0 4px; font-size: 11px; line-height: 16px; white-space: pre-wrap;
+  overflow-wrap: anywhere; color: var(--dsw-alias-label-tertiary, color-mix(in srgb, currentColor 60%, transparent)); }
+.dci-md .dci-md-mermaid-error .dci-md-pre { padding-left: 0; padding-right: 0; }
+
+/* 复制/成功图标（CSS mask + data URI，不往 DOM 里塞 SVG，净化白名单保持收敛）。 */
+.dci-md { --dci-md-icon-copy: url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2016%2016'%20fill='none'%20stroke='black'%20stroke-width='1.4'%3E%3Crect%20x='5.75'%20y='5.75'%20width='7.5'%20height='7.5'%20rx='1.6'/%3E%3Cpath%20d='M10.25%205.75V4.1A1.6%201.6%200%200%200%208.65%202.5H4.1A1.6%201.6%200%200%200%202.5%204.1v4.55a1.6%201.6%200%200%200%201.6%201.6h1.65'/%3E%3C/svg%3E");
+  --dci-md-icon-check: url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2016%2016'%20fill='none'%20stroke='black'%20stroke-width='1.8'%20stroke-linecap='round'%20stroke-linejoin='round'%3E%3Cpath%20d='M2.8%208.6l3.2%203.1%207.2-7.4'/%3E%3C/svg%3E"); }
+`;

package/src/client/markdown/index.ts

@@ -0,0 +1,289 @@
+/**
+ * 统一 Markdown 渲染管线的**唯一入口**。
+ *
+ * 预览面板（CodinputSurface）与用户消息（UserMessageMarkdown）都只调
+ * `renderMarkdown(text)`：同步、返回已净化 HTML，两处输出逐字节一致。
+ * 渲染之外的 DOM 交互（图片灯箱、wikilink 复制、扩展渲染的异步激活）由本模块
+ * 的辅助函数接管，组件侧只挂一个 onClick + 一个 activateMarkdown effect。
+ *
+ * ## 对外接口
+ * - `renderMarkdown(text, options?)` → sanitized HTML（同步）
+ * - `markdownStyles` → 本管线新增 CSS（由 `src/client/styles.ts` 拼接注入）
+ * - `registerMarkdownExtension(ext)` → 轻量 registry（扩展渲染 高亮/KaTeX/Mermaid）
+ * - `activateMarkdown(root, surface?)` → innerHTML 落地后的扩展激活（可返回清理函数）
+ * - `handleMarkdownClick(event, { onImage })` → 图片点击开灯箱 / wikilink 点击复制
+ * - `copyTextToClipboard(text)` → 剪贴板（含 execCommand 兜底）
+ *
+ * ## registry 约定（扩展渲染 契约）
+ * ```ts
+ * const off = registerMarkdownExtension({
+ *   name: 'katex',                       // 唯一名；重复注册覆盖旧项
+ *   marked: { extensions: [...], renderer: { ... } }, // marked 扩展（必须同步）
+ *   allowTags: ['math', 'annotation'],   // 增量放行 DOMPurify 白名单
+ *   allowAttrs: ['data-katex'],
+ *   // 异步面（Mermaid）：innerHTML 落地后由 activateMarkdown 调，返回清理函数
+ *   activate(root, { surface }) { ...; return () => cleanup(); },
+ * });
+ * off(); // 注销并重建解析器
+ * ```
+ * 约束：`marked` 扩展不得设 `async: true`（renderMarkdown 是同步契约）；异步渲染
+ * 请放 `activate`（宿主 DOM 已就绪），需要的高度变化由调用方/ResizeObserver 处理。
+ * `renderer` 扩展返回 `false` 可回退上一实现（marked 约定）。
+ */
+
+import { Marked, type MarkedExtension } from 'marked';
+import { diagError } from '../diag';
+import { escapeHtml, sanitizeMarkdown, type SanitizeExtras } from './sanitize';
+import {
+  beginFootnoteRender,
+  buildFootnotesHtml,
+  coreMarkedOptions,
+  endFootnoteRender,
+  extractFootnotes,
+} from './extensions';
+import { markdownStyles } from './styles';
+
+export { markdownStyles };
+
+/** 渲染面：预览面板 / 用户消息气泡（扩展渲染 可据此做差异化激活）。 */
+export type MarkdownSurface = 'preview' | 'user-message';
+
+/** 激活钩子拿到的上下文。 */
+export interface MarkdownRenderContext {
+  surface: MarkdownSurface;
+}
+
+/**
+ * registry 扩展项。基础渲染 只用到基础面；扩展渲染的代码高亮/KaTeX 走 `marked`，
+ * Mermaid 走 `activate`（异步、DOM 就绪后）。
+ */
+export interface MarkdownExtension {
+  /** 唯一标识；同名重复注册以最后一次为准。 */
+  name: string;
+  /** marked 扩展（tokenizer/renderer/hooks）。不得声明 async。 */
+  marked?: MarkedExtension;
+  /** 追加放行的 DOMPurify 标签（如 KaTeX 的 math/annotation）。 */
+  allowTags?: readonly string[];
+  /** 追加放行的 DOMPurify 属性（如 data-katex）。 */
+  allowAttrs?: readonly string[];
+  /**
+   * innerHTML 落地后调用（组件在 useEffect 里调 `activateMarkdown`）。
+   * 返回清理函数，会在下次渲染/卸载前执行。只应在已净化的根节点上工作。
+   */
+  activate?: (root: HTMLElement, context: MarkdownRenderContext) => void | (() => void);
+}
+
+export interface RenderMarkdownOptions {
+  /** 渲染面标识；基础渲染 只作激活上下文透传，不改变输出。 */
+  surface?: MarkdownSurface;
+}
+
+/* ---------- 解析器 / registry ---------- */
+
+let extensions: MarkdownExtension[] = [];
+let parser: Marked = buildParser();
+let sanitizeExtras: SanitizeExtras | undefined;
+
+function buildParser(): Marked {
+  const packs: MarkedExtension[] = [coreMarkedOptions];
+  for (const extension of extensions) {
+    if (extension.marked) packs.push(extension.marked);
+  }
+  // marked 的 use() 对后注册的 tokenizer 前插：registry 扩展天然覆盖核心扩展。
+  return new Marked(...packs);
+}
+
+function rebuild(): void {
+  parser = buildParser();
+  const tags: string[] = [];
+  const attrs: string[] = [];
+  for (const extension of extensions) {
+    if (extension.allowTags) tags.push(...extension.allowTags);
+    if (extension.allowAttrs) attrs.push(...extension.allowAttrs);
+  }
+  sanitizeExtras = tags.length > 0 || attrs.length > 0 ? { tags, attrs } : undefined;
+}
+
+/**
+ * 注册一个渲染扩展（扩展渲染 接高亮/KaTeX/Mermaid 用）。返回注销函数。
+ * 注册后立即重建解析器；同名覆盖旧项。
+ */
+export function registerMarkdownExtension(extension: MarkdownExtension): () => void {
+  if (!extension || typeof extension.name !== 'string' || extension.name === '') {
+    throw new Error('markdown: registerMarkdownExtension requires a non-empty name');
+  }
+  extensions = [...extensions.filter((item) => item.name !== extension.name), extension];
+  rebuild();
+  return () => {
+    const next = extensions.filter((item) => item !== extension);
+    if (next.length === extensions.length) return;
+    extensions = next;
+    rebuild();
+  };
+}
+
+/** 当前已注册的扩展名（诊断 / QA 用）。 */
+export function registeredMarkdownExtensions(): string[] {
+  return extensions.map((extension) => extension.name);
+}
+
+/* ---------- 渲染 ---------- */
+
+let renderSeq = 0;
+
+/**
+ * 把 Markdown 渲染成可安全 `dangerouslySetInnerHTML` 的 HTML（同步）。
+ * 空串返回空串（组件据此显示占位）；任何异常降级为「原文转义 + <br>」，
+ * 错误进 `__dshCodinputErrs`（不把未净化 HTML 塞进 DOM）。
+ */
+export function renderMarkdown(text: string, _options: RenderMarkdownOptions = {}): string {
+  const source = typeof text === 'string' ? text : '';
+  if (source.trim() === '') return '';
+  const renderId = ++renderSeq;
+  try {
+    const { text: body, definitions } = extractFootnotes(source);
+    const numbers = new Map(definitions.map((definition) => [definition.id, definition.number] as const));
+    beginFootnoteRender({ prefix: `dci-md-${renderId}-`, numbers, shownRefs: new Map() });
+    const parsed = parser.parse(body, { async: false }) as unknown;
+    if (typeof parsed !== 'string') {
+      throw new Error('markdown: async marked extensions are not supported by renderMarkdown()');
+    }
+    let html = parsed;
+    if (definitions.length > 0) {
+      html += buildFootnotesHtml(definitions, (markdown) => parser.parse(markdown, { async: false }));
+    }
+    return sanitizeMarkdown(html, sanitizeExtras);
+  } catch (error) {
+    diagError('markdown.render', error);
+    try {
+      return sanitizeMarkdown(`<p>${escapeHtml(source).replace(/\n/gu, '<br>')}</p>`, sanitizeExtras);
+    } catch {
+      return '';
+    }
+  } finally {
+    endFootnoteRender();
+  }
+}
+
+/**
+ * innerHTML 落地后激活已注册扩展（扩展渲染的 Mermaid 异步渲染走这里）。
+ * 返回清理函数；组件在 useEffect 里 `return activateMarkdown(ref.current, surface)`。
+ * 没有注册扩展时是零开销 no-op。
+ */
+export function activateMarkdown(root: HTMLElement | null, surface: MarkdownSurface = 'preview'): () => void {
+  if (!root || extensions.length === 0) return () => {};
+  const context: MarkdownRenderContext = { surface };
+  const cleanups: (() => void)[] = [];
+  for (const extension of extensions) {
+    if (typeof extension.activate !== 'function') continue;
+    try {
+      const cleanup = extension.activate(root, context);
+      if (typeof cleanup === 'function') cleanups.push(cleanup);
+    } catch (error) {
+      diagError('markdown.activate', error);
+    }
+  }
+  return () => {
+    for (const cleanup of cleanups) {
+      try {
+        cleanup();
+      } catch (error) {
+        diagError('markdown.activate', error);
+      }
+    }
+  };
+}
+
+/* ---------- DOM 交互（图片灯箱 / wikilink 复制） ---------- */
+
+export interface MarkdownImageTarget {
+  src: string;
+  alt: string;
+}
+
+interface MarkdownActivation {
+  image?: MarkdownImageTarget;
+  wikilink?: string;
+}
+
+/** 从点击目标解析出「Markdown 根内的图片 / wikilink」。 */
+function activationFromEvent(event: { target: EventTarget | null }): MarkdownActivation | null {
+  const target = event.target;
+  if (!(target instanceof Element)) return null;
+  const root = target.closest('.dci-md');
+  if (!root) return null;
+  const image = target.closest('img');
+  if (image && root.contains(image)) {
+    const src = image.getAttribute('src') ?? '';
+    if (/^https?:\/\//i.test(src)) return { image: { src, alt: image.getAttribute('alt') ?? '' } };
+  }
+  const wikilink = target.closest('[data-dci-wikilink]');
+  if (wikilink && root.contains(wikilink)) {
+    const value = wikilink.getAttribute('data-dci-wikilink') ?? '';
+    if (value !== '') return { wikilink: value };
+  }
+  return null;
+}
+
+/** 剪贴板写入（含旧 API 兜底；保留官方复制钮同款实现）。 */
+export async function copyTextToClipboard(text: string): Promise<boolean> {
+  try {
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch {
+    try {
+      const area = document.createElement('textarea');
+      area.value = text;
+      area.style.position = 'fixed';
+      area.style.opacity = '0';
+      document.body.appendChild(area);
+      area.select();
+      const ok = document.execCommand('copy');
+      area.remove();
+      return ok;
+    } catch {
+      return false;
+    }
+  }
+}
+
+function flashWikilinkCopied(element: HTMLElement): void {
+  element.dataset.dciCopied = 'true';
+  window.setTimeout(() => {
+    delete element.dataset.dciCopied;
+  }, 900);
+}
+
+export interface MarkdownClickHandlers {
+  /** Markdown 内的 http(s) 图片被点击（组件接灯箱）。 */
+  onImage?(image: MarkdownImageTarget): void;
+  /** wikilink 目标已复制成功。 */
+  onWikilink?(target: string): void;
+}
+
+/**
+ * Markdown 根的点击委派：图片 → `onImage`（组件开灯箱）；wikilink → 复制目标名。
+ * 返回是否已处理（组件可据此阻止默认行为/冒泡）。
+ */
+export function handleMarkdownClick(
+  event: { target: EventTarget | null; preventDefault?: () => void },
+  handlers: MarkdownClickHandlers = {},
+): boolean {
+  const activation = activationFromEvent(event);
+  if (!activation) return false;
+  if (activation.image) {
+    event.preventDefault?.();
+    handlers.onImage?.(activation.image);
+    return true;
+  }
+  const target = activation.wikilink as string;
+  event.preventDefault?.();
+  const element =
+    event.target instanceof Element ? event.target.closest<HTMLElement>('[data-dci-wikilink]') : null;
+  void copyTextToClipboard(target).then((ok) => {
+    if (!ok || !element) return;
+    flashWikilinkCopied(element);
+    handlers.onWikilink?.(target);
+  });
+  return true;
+}

package/src/client/markdown/math.ts

@@ -0,0 +1,134 @@
+/**
+ * 扩展渲染：KaTeX 数学公式（`$...$` 行内 / `$$...$$` 块级；字体全内置离线）。
+ *
+ * ## 为什么是「占位符 + activate 替换」而不是直接出 KaTeX HTML
+ * KaTeX 的 HTML 输出依赖大量 inline style（strut 高度、分式/上下标定位），而
+ * 基础渲染的净化白名单为了安全硬性 `FORBID_ATTR: ['style']`（见 sanitize.ts）。
+ * 因此这里让 marked 只产出**空占位元素**（源码以 base64 放 data 属性，经
+ * registry 的 `allowAttrs` 增量放行），`activateMath` 在 innerHTML 落地后同步
+ * 调 `katex.renderToString` 替换 innerHTML —— KaTeX 输出由库生成、输入 escape、
+ * `trust:false`，不经过 DOMPurify 也不会引入用户可控 HTML。
+ *
+ * 失败（`throwOnError:true` → 抛错）回退「原样公式源码 + 错误样式」，不抛到页面。
+ *
+ * ## 行内 `$...$` 的防误伤规则（对齐 KaTeX auto-render 思路）
+ * - 开 `$` 后不能是空白或另一个 `$`（`$$` 是块级）；
+ * - 闭 `$` 前不能是空白/反斜杠（`\$` 是字面量）；
+ * - 闭 `$` 后不能是数字或 `$`（`$5 and $10` 这类货币文本不会命中）；
+ * - 内容不允许换行；转义字符按 `\x` 整体吞掉。
+ */
+
+import katex from 'katex';
+import type { TokenizerAndRendererExtension, Tokens } from 'marked';
+import katexCss from 'virtual:katex-css';
+import { decodeBase64Utf8, encodeBase64Utf8 } from './heavy-shared';
+
+const KATEX_STYLE_ID = 'dci-md-katex-css';
+let katexCssInjected = false;
+
+/**
+ * 首次出现公式时注入 KaTeX CSS（字体是 CSS 内嵌的 data URI，零网络请求）。
+ * 必须插在本插件 `<style id="dsh-codinput-styles">` **之前**：KaTeX 默认样式
+ * 先落地，我们在 heavyMarkdownStyles 里的 `.dci-md .katex` 覆盖才能生效。
+ */
+export function ensureKatexCss(): void {
+  if (katexCssInjected || typeof document === 'undefined') return;
+  katexCssInjected = true;
+  if (document.getElementById(KATEX_STYLE_ID)) return;
+  if (typeof katexCss !== 'string' || katexCss === '') return;
+  const style = document.createElement('style');
+  style.id = KATEX_STYLE_ID;
+  style.textContent = katexCss;
+  const pluginStyle = document.getElementById('dsh-codinput-styles');
+  if (pluginStyle && pluginStyle.parentNode) pluginStyle.parentNode.insertBefore(style, pluginStyle);
+  else document.head.appendChild(style);
+}
+
+/* ---------- marked 侧：占位元素 ---------- */
+
+function placeholder(tex: string, display: boolean): string {
+  const encoded = encodeBase64Utf8(tex);
+  const tag = display ? 'div' : 'span';
+  const className = display ? 'dci-md-math-block' : 'dci-md-math-inline';
+  return `<${tag} class="${className}" data-dci-md-math="${encoded}" data-dci-md-display="${display ? '1' : '0'}"></${tag}>`;
+}
+
+/** 块级 `$$ ... $$`（可跨行；要求独占块边界）。 */
+const blockMathExtension: TokenizerAndRendererExtension = {
+  name: 'dciBlockMath',
+  level: 'block',
+  start(src: string): number | undefined {
+    const index = src.indexOf('$$');
+    return index < 0 ? undefined : index;
+  },
+  tokenizer(src: string): Tokens.Generic | undefined {
+    const match = /^\$\$[ \t]*\n?([\s\S]+?)\n?[ \t]*\$\$[ \t]*(?:\n|$)/u.exec(src);
+    if (!match) return undefined;
+    const tex = match[1].trim();
+    if (tex === '') return undefined;
+    return { type: 'dciBlockMath', raw: match[0], text: tex };
+  },
+  renderer(token: Tokens.Generic): string {
+    return `${placeholder(String(token['text'] ?? ''), true)}\n`;
+  },
+};
+
+/** 行内 `$ ... $`（规则见文件头注释）。 */
+const inlineMathExtension: TokenizerAndRendererExtension = {
+  name: 'dciInlineMath',
+  level: 'inline',
+  start(src: string): number | undefined {
+    const index = src.indexOf('$');
+    return index < 0 ? undefined : index;
+  },
+  tokenizer(src: string): Tokens.Generic | undefined {
+    const match = /^\$(?![\s$])((?:\\.|[^$\\\n])+?)(?<![\s\\])\$(?![\d$])/u.exec(src);
+    if (!match) return undefined;
+    const tex = match[1];
+    if (tex.trim() === '') return undefined;
+    return { type: 'dciInlineMath', raw: match[0], text: tex };
+  },
+  renderer(token: Tokens.Generic): string {
+    return placeholder(String(token['text'] ?? ''), false);
+  },
+};
+
+/** 交给 registry 的 `marked.extensions`。 */
+export const mathMarkedExtensions: TokenizerAndRendererExtension[] = [blockMathExtension, inlineMathExtension];
+
+/* ---------- 激活期：同步替换为 KaTeX HTML ---------- */
+
+function renderMathNode(node: HTMLElement): void {
+  const encoded = node.getAttribute('data-dci-md-math') ?? '';
+  const display = node.getAttribute('data-dci-md-display') === '1';
+  const tex = decodeBase64Utf8(encoded);
+  try {
+    const html = katex.renderToString(tex, {
+      displayMode: display,
+      throwOnError: true,
+      trust: false,
+      strict: false,
+      output: 'htmlAndMathml',
+    });
+    node.innerHTML = html;
+    node.classList.add('dci-md-math-rendered');
+  } catch (error) {
+    node.classList.add('dci-md-math-error');
+    node.textContent = tex;
+    node.setAttribute('title', error instanceof Error ? error.message : String(error));
+  }
+}
+
+/** innerHTML 落地后的公式渲染（同步；基础渲染 `activateMarkdown` 调用）。 */
+export function activateMath(root: HTMLElement): void {
+  const nodes = root.querySelectorAll<HTMLElement>('[data-dci-md-math]');
+  if (nodes.length === 0) return;
+  ensureKatexCss();
+  for (const node of nodes) {
+    try {
+      renderMathNode(node);
+    } catch {
+      // renderMathNode 已处理 KaTeX 解析错误；这里兜底任何意外（不抛给 React）。
+    }
+  }
+}