feat(mermaid): Markdown 预览安全渲染 Mermaid 图表(strict 清洗 + 懒加载 chunk + 点击放大) (#164)
* feat(mermaid): 新增 mermaid 懒加载 chunk(构建链四处同步 + mermaid 依赖) tsdown CHUNKS / bundle-route CHUNK_NAMES / chunk-loader ChunkName / package.json files 同步注册 mermaid chunk;mermaid ^11.16.1 进依赖与 lockfile;chunk 构建注入 uuid 浏览器入口别名,绕开 node:crypto 纯度门。 * feat(mermaid): Markdown 预览安全渲染 mermaid 图表 + 点击放大弹窗 - splitMermaidBlocks 纯函数按 fence 切块,无 mermaid 文件零行为变化; - mermaid.initialize 走 securityLevel strict + htmlLabels:false,不应用 bindFunctions(静态图);渲染 SVG 经 mermaid-sanitize 二次清洗: 删 foreignObject/script/外来 HTML 元素、剥 @*/on* 属性、移除全部 href/xlink:href,仅接受 SVG 根,解析失败返回空串; - 点击图表弹出放大弹窗(滚轮缩放/拖拽平移/快捷键,借鉴 PR #75 交互, 基于已清洗 SVG 克隆重写,不新增攻击面); - 深浅色跟随重渲、失败回退错误条 + 原码、CodeBlock 同款 chrome。 * test(mermaid): splitter/sanitize 单测 + chunk 清单同步 + 挂载冒烟 diagram.md - mermaid-blocks.spec 10 例 fence 切块语义; - mermaid-sanitize.spec 8 例 XSS(foreignObject/on*/@*/href/xlink:href/ script/外来元素/畸形 XML/非 SVG 根); - bundle-route / chunk-artifact / manifest-consistency 清单加入 mermaid (chunk-artifact 补 addEventListener stub); - 挂载冒烟新增 diagram.md:client-mermaid.js 往返、SVG 节点文字、 点击弹窗 Esc 关闭、preview 模式编辑器隐藏。 * docs(mermaid): 安全渲染设计文档 + lazy-chunks 表 + README 双语更新 设计文档记录基线决策(PR #99 架构 + PR #75 点击放大)、安全模型 (strict/htmlLabels/清洗/href 剥离/无 bindFunctions)、验证与取舍。 * fix(mermaid): sanitizer 属性名大小写归一,堵住混合大小写属性绕过(CR P1) XML 属性名保留大小写,而输出会经 HTML 解析归一化(dangerouslySetInnerHTML), oNload/HREF/xlink:HREF 这类混合大小写属性此前会漏过清洗。比较前先 toLowerCase(),按原名删除;新增混合大小写事件/链接属性回归用例。 * fix(mermaid): sanitizer 元素黑名单大小写归一,堵住混合大小写元素绕过(CR P1) XML 元素名保留大小写,querySelectorAll('script') 等选择器匹配不到 <sCrIpT>/<foreignobject>,而输出经 HTML 解析会被归一化为 SVG script/foreignObject(可执行/可注入 HTML)。改为遍历全部元素按 localName.toLowerCase() 命中小写黑名单后整节点删除;新增混合大小写 script/foreignObject/外来 HTML 元素回归用例(jsdom 实证:旧选择器 命中 0,新逻辑命中 2)。 * fix(mermaid): 单次 Markdown 解析 + 占位交换(CR P1)+ CommonMark fence 规则(CR P2) P1(跨 fence 语义):弃用逐块 MarkdownText 拆分,改为整篇文档单次 MarkdownText 渲染,布局后把 language-mermaid 代码块交换为 MermaidDiagram (React 管理的 .md-code-block 宿主保留在树中、display:contents 抑制盒子, 协调安全;块不再 mermaid 时还原原 children)。新增 tests/mermaid-markdown.spec.tsx 与 e2e 跨 fence 引用链接断言。 P2(fence 匹配):支持 3+ 反引号与波浪号开 fence;闭 fence 须同字符且 长度不小于开 fence;反引号 info string 含反引号不视为开 fence;修复 带缩进开 fence 的 info 提取。blocks 单测 +3 例。
This commit is contained in:
1 parent
9bea6c5539
commit
5e416eccef
23 files changed
+2131
-25
No files matched your search
@@ -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
|
||||
}
|
||||
Reference in new issue
Block a user