Architecture and Entries

架构与入口

三个入口

导入	用途	加载 TableKit
tiptap-markdown-react	编辑器 / 工具栏 / 实时预览	是
tiptap-markdown-react/server	Server Components / ISR 的 renderReportHtml	是
tiptap-markdown-react/reader	客户端阅读页（ReportContentInteractive 等）	否

不要在同一客户端 bundle 里混用 . 与 ./server。 ProseMirror 每个 JS realm 只注册一次表格单元格选择，两个入口同载会抛 Duplicate use of selection JSON ID cell。阅读页的正确姿势：服务端用 ./server 渲染 HTML，客户端用 ./reader 水合，且该客户端模块图里不要引编辑器入口。

./reader 不加载 TableKit，所以只阅读不编辑的页面 bundle 更小。

服务端渲染管线（./server）

import { renderReportHtml, ReportContent } from 'tiptap-markdown-react/server';
const { html, toc, ok, tocDegraded } = renderReportHtml(markdown);

• 返回 { html, toc, ok, tocDegraded? }；includeToc 默认开启，卡片预览可关
• 解析失败时 ok: false，不把已有 HTML 吞成空串
• tocDegraded: true 表示正文已渲染但锚点/目录缺失（TOC 管线降级）——用来区分「文档没有标题」和「目录丢了」
• stabilizeMarkdown() 给流式半成品补未闭合的围栏（``` / ~~~），适合边生成边渲染
• 图表在服务端只输出 div[data-type=chart] 占位，Chart.js 不上服务器

配套导出：stabilizeMarkdown、extractToc、makeTocGetId、baseExtensions、pureCodeBlock、pureImage、lowlight。

客户端水合（./reader）

组件	能力
ReportContent	静态 HTML 外壳 + 正文样式；toc 开启时画左侧目录
ReportContentInteractive	上面 + 脚注点击/悬停交互（onCitationEnter / onCitationLeave）
ReportContentWithCharts	上面 + 图表水合（Chart.js 在客户端接管占位块）
CitationInteractive	想自己组壳时用（不要内置目录）
extractFootnoteSources(markdown)	把 GFM 脚注定义行抽成 SourceRef[] 并从正文剥离

目录锚点在三端之间一致（编辑器预览与服务端渲染页用同一套 slug），收藏的锚点链接在发布页上仍然有效。

共享 tokenizer

<img …>（缩放/对齐/图注）和 <p|hn style>（段落样式）这类库自定义的 HTML，在解析端由编辑器、预览、服务端共用的同一个 tokenizer 认领（它先于 window.DOMParser 路径运行）。这就是这些样式在 SSR 里也能还原、而不会被转义成字面文本的原因。详见Markdown 往返规则第 3 节。

库内结构速览

• 编辑器组件 + 自绘 UI（工具栏、查找条、表格手柄、链接浮层、斜杠菜单）都在包内，通过 --tmr-* CSS 变量主题化；下拉/浮层用 Radix primitives，图标为内联 SVG
• 大量能力是「导出的工具函数 + 命令」（resetImageSize、setImageAlign、applyLink、查找替换的命令面……），宿主可以只取命令、自绘 UI
• 中英文 locale 内置，各可见组件各收一个 locale prop