@cellgit/markdown-render 0.1.0 → 1.0.0

package/README.md

@@ -1,34 +1,92 @@
-# markdown-render
-
-一个功能完整的前端 Markdown 渲染库，基于 markdown-it，支持语法高亮、数学公式、任务列表、Emoji 等特性。完美兼容 WebView、Web、React Native 和 Electron。
-
-## 特性
-
-✅ **基于 markdown-it** - 使用业界标准的 markdown-it 解析器
-✅ **语法高亮** - 内置 highlight.js，支持 180+ 编程语言
-✅ **数学公式** - KaTeX 集成，支持行内和块级数学公式
-✅ **任务列表** - 支持 `- [x]` 和 `- [ ]` 语法
-✅ **嵌套列表** - 支持多层嵌套列表（有序/无序）
-✅ **Emoji** - 支持 emoji shortcode，如 `:smile:` :smile:
-✅ **表格** - 完整的 markdown 表格支持
-✅ **代码块增强** - 带语言标签和复制按钮的代码块
-✅ **主题支持** - 内置明暗主题自动切换
-✅ **单文件输出** - 所有依赖打包在一个 JS 文件中
-✅ **Pipeline 架构** - 可扩展的后处理机制
-
-## 安装
-
-### 从 npm 安装（推荐）
+# @cellgit/markdown-render
+
+English | **[简体中文](README.zh-CN.md)**
+
+Streaming-friendly Markdown renderer built on `markdown-it`. Supports KaTeX
+math, GitHub-style code highlighting, task lists, emoji shortcodes, tables,
+and dynamic-height rendering inside `WKWebView`. Tuned for AI chat
+streams — see `docs/render-core-fixes-v1.md` for the v1.0 design notes.
+
+## 📖 Resources
+
+- [npm package page](https://www.npmjs.com/package/@cellgit/markdown-render)
+- [markdown-render repository](https://github.com/cellgit/markdown-render)
+- [iOS integration example](https://github.com/cellgit/MarkdownRenderDemo)
+- [npm package test project](https://github.com/cellgit/markdown-render-npm-test)
+
+## Features
+
+- ✅ **Built on markdown-it** — the industry-standard Markdown parser
+- ✅ **Syntax highlighting** — bundled highlight.js (common build, ~40 mainstream languages incl. Swift/Kotlin/TS; unlabeled blocks auto-detect among 20 high-frequency languages, and blocks over 8KB render as plain text to keep streaming fast)
+- ✅ **Math** — KaTeX integration, inline and block formulas
+- ✅ **Tolerant of non-standard markdown** — a `$` next to a price, a bracketed citation, a formula whose closing brace has not streamed in yet: none of these turn red. Anything KaTeX cannot parse falls back to the author's own characters, in the surrounding text colour
+- ✅ **Streaming** — rAF-coalesced flushes + incremental safe-boundary caching; a whole stream renders in O(n) total
+- ✅ **Reasoning folds** — `<think>` … `</think>` is routed out of the answer into a collapsible panel that streams while the model thinks and folds to one line when the answer starts; providers that stream reasoning on a separate field feed the same panel directly
+- ✅ **Task lists** — `- [x]` / `- [ ]` syntax
+- ✅ **Nested lists** — multi-level ordered/unordered lists
+- ✅ **Emoji** — shortcodes such as `:smile:`
+- ✅ **Tables** — full Markdown table support with horizontal scroll on narrow viewports
+- ✅ **Enhanced code blocks** — language label + copy button
+- ✅ **Theming** — automatic light/dark switching plus a token-based theme engine
+- ✅ **Declarative extensions** — register custom inline syntax by configuration (@mentions, [[wikilinks]], `||spoilers||`, …)
+- ✅ **Single-file output** — all dependencies in one JS file (~620KB)
+- ✅ **Pipeline architecture** — extensible HTML post-processing
+
+## Roadmap: LLM output coverage
+
+Real LLM output is messier than well-formed Markdown. The patterns below were
+**verified against the current renderer** and are not yet first-class; they are
+the planned next tranche. Full evaluation, acceptance criteria, and suggested
+order live in [docs/llm-output-roadmap.md](docs/llm-output-roadmap.md).
+
+| priority | pattern | today | planned |
+|---|---|---|---|
+| P0 | GitHub alerts `> [!NOTE]` | plain blockquote, literal `[!NOTE]` | themable callout cards (5 types) |
+| P0 | Footnotes `[^1]` | literal text | superscript chips + tap events (RAG citations) |
+| P0 | Unclosed `**bold` / `$math` at the stream tail | raw markers flash, then jump | soft-close at the tail, restored on final flush; optional typing caret |
+| P0 | YAML frontmatter | misrendered as `<hr>` + heading | stripped at document start |
+| ✅ done | `<think>` / `<thinking>` reasoning | escaped to visible text | routed into a collapsible fold, streaming-safe across chunk boundaries |
+| P0 | `<details>` / `<sub>` / `<sup>` / `<kbd>` | escaped to visible text | sanitized safe-HTML subset |
+| P1 | ```` ```mermaid ```` fences | highlighted source code | diagram rendered on fence close, code fallback on error (lazy-loaded) |
+| P1 | Chemistry `\ce{…}`, math a11y & copy | KaTeX error fallback; no copy | mhchem, tap-to-copy raw LaTeX, MathML output for VoiceOver |
+| P1 | Code block ergonomics | scroll + copy only | wrap toggle, line numbers, collapse long blocks |
+| P1 | Image policy | broken icon on failure | failure placeholder, lazy loading, remote-image switch |
+| P1 | Numeric citations `[1]`, `【12†source】` | literal text | clickable citation chips |
+| P2 | Chat-list scale (SDK) | one `WKWebView` per message | WebView pooling / single-WebView message list |
+| P2 | Long sessions & lifecycle | no benchmarks; finish-only streams | virtualization, memory ceiling, benchmark suite, `abortStreaming()` |
+
+### Production-readiness spec (commercial SDK)
+
+Syntax coverage is only one of nine capability domains a commercial SDK must
+close. The full audited specification — every domain with verified current
+status, priorities, and acceptance criteria, plus the GA blocking checklist —
+lives in [docs/production-readiness-spec.md](docs/production-readiness-spec.md):
+
+| domain | status | GA blockers (examples) |
+|---|---|---|
+| 1. Input robustness | ⚠️ | size limits, nesting bombs, Unicode/bidi safety, fuzzing |
+| 2. Security & privacy compliance | ⚠️ | link-scheme risk signals (privacy manifest & OSS notices ✅ shipped) |
+| 3. Platform & lifecycle | ⚠️ | runtime theme switching (web-process crash recovery ✅ shipped) |
+| 4. API completeness & DX | ⚠️ | scroll control, SwiftUI self-sizing, runtime options, SPM/Pods |
+| 5. Rendering fidelity & conformance | ⚠️ | CommonMark/GFM corpus baseline + CI gate |
+| 6. Streaming protocol robustness | ⚠️ | chunking-invariant property tests, out-of-order call semantics |
+| 7. Performance & footprint | ⚠️ | budgets + benchmark suite + memory baseline (bundle −56%, fonts −73% ✅) |
+| 8. Quality & release engineering | ❌ | CI builds, signed XCFramework, checksums, release checklist |
+| 9. Licensing & commercial ops | ⚠️ | build-time public-key injection, key rotation, status API |
+
+## Installation
+
+### From npm (recommended)
 
 ```bash
-npm install markdown-render
-# 或
-yarn add markdown-render
-# 或
-pnpm add markdown-render
+npm install @cellgit/markdown-render
+# or
+yarn add @cellgit/markdown-render
+# or
+pnpm add @cellgit/markdown-render
 ```
 
-### 从源码构建
+### From source
 
 ```bash
 git clone <repository-url>
@@ -37,14 +95,14 @@ npm install
 npm run build
 ```
 
-## 使用方法
+## Usage
 
-### 在 npm 项目中使用
+### In an npm project
 
-**React 示例：**
+**React:**
 ```jsx
-import { renderMarkdown } from 'markdown-render';
-import 'markdown-render/styles';
+import { renderMarkdown } from '@cellgit/markdown-render';
+import '@cellgit/markdown-render/styles';
 
 function App() {
   const html = renderMarkdown('# Hello **React**!');
@@ -52,58 +110,84 @@ function App() {
 }
 ```
 
-**Vue 示例：**
+**Vue:**
 ```vue
 <template>
   <div v-html="html"></div>
 </template>
 
 <script setup>
-import { renderMarkdown } from 'markdown-render';
-import 'markdown-render/styles';
+import { renderMarkdown } from '@cellgit/markdown-render';
+import '@cellgit/markdown-render/styles';
 
 const html = renderMarkdown('# Hello **Vue**!');
 </script>
 ```
 
-**Vanilla JS：**
+**Vanilla JS:**
 ```javascript
-import { renderMarkdown } from 'markdown-render';
-import 'markdown-render/styles';
-
-const html = renderMarkdown('# Hello **World**!');
+import { renderMarkdown, setTheme } from '@cellgit/markdown-render';
+import '@cellgit/markdown-render/styles';
+
+setTheme('dark'); // optional; null restores prefers-color-scheme behaviour
+const html = renderMarkdown('# Hello **World**!', {
+  allowRawHTML: false,   // default; opt in only for trusted input
+  math: true,
+  taskLists: true
+});
 document.getElementById('app').innerHTML = html;
 ```
 
-📚 **完整文档：**
-- [NPM 使用指南](NPM_USAGE.md) - 详细的 npm 使用说明
-- [示例代码](examples/) - React、Vue、Vanilla JS 完整示例
+### Render options
+
+| key | default | description |
+|---|---|---|
+| `allowRawHTML` | `false` | Preserve raw HTML in markdown source. **Enable only for trusted content.** |
+| `linkify` | `true` | Auto-detect bare URLs. |
+| `typographer` | `true` | Smart quotes / dashes / ellipses. |
+| `breaks` | `false` | Convert single `\n` into `<br>`. |
+| `taskLists` | `true` | `- [ ]` and `- [x]` rendering. |
+| `emoji` | `true` | `:smile:` shortcodes. |
+| `math` | `true` | Inline (`$…$`, `\(…\)`) and block (`$$…$$`, `\[…\]`) KaTeX. |
+| `highlight` | hljs default | Custom highlighter `(code, lang) => string`. |
+| `pipeline` | `['wrapTables', 'addCopyButton', 'handleLinks']` | Ordered processor names. |
+| `openLinksInNewTab` | `false` | When `true`, links get `target="_blank"`. |
 
-### 在 iOS 项目中使用
+📚 **Full docs:**
+- [NPM usage guide](NPM_USAGE.md)
+- [Examples](examples/) — complete React, Vue, and Vanilla JS samples
 
-专为 iOS 打包：
+### In an iOS project
+
+Build the iOS package:
 
 ```bash
 npm run build:ios
 ```
 
-这会在 `ios-bundle/` 目录生成适用于 iOS 的文件包。详细集成步骤请查看 [iOS 集成指南](ios-example/README.md)。
+This produces an iOS-ready bundle under `ios-bundle/`. See the
+[iOS integration guide](ios-example/README.md) for detailed steps.
 
-快速开始：
-1. 运行 `npm run build:ios`
-2. 将 `ios-bundle/` 中的文件添加到 Xcode 项目
-3. 使用 `MarkdownViewController` 渲染 Markdown
+Quick start:
+1. Run `npm run build:ios`
+2. Add the files from `ios-bundle/` to your Xcode project
+3. Render Markdown with `MarkdownViewController`
 
-> 需要自定义 WebView 模板？请编辑 `templates/markdown-render.html`，然后重新运行 `npm run build` 或 `npm run build:ios`，生成的 `dist/markdown-render.html` 会自动更新并被后续打包脚本使用。
+> Need a custom WebView template? Edit `templates/markdown-render.html`, then
+> re-run `npm run build` or `npm run build:ios` — the generated
+> `dist/markdown-render.html` updates automatically and is picked up by the
+> packaging scripts.
 
 ```swift
 let markdownVC = MarkdownViewController()
 markdownVC.renderMarkdown("# Hello iOS\nThis is **bold** text!")
 ```
 
-完整示例代码请参考 `ios-example/MarkdownViewController.swift`。
+See `ios-example/MarkdownViewController.swift` for the complete sample. For
+the commercial SDK wrapper (encrypted resources + licensing), see the
+`swift-markdown-kit` repository.
 
-### 在 HTML 中使用
+### In plain HTML
 
 ```html
 <!DOCTYPE html>
@@ -136,7 +220,7 @@ Math: $E = mc^2$
 </html>
 ```
 
-### 在 ES Module 中使用
+### As an ES module
 
 ```javascript
 import { renderMarkdown } from './dist/markdown-render.js';
@@ -145,182 +229,356 @@ const html = renderMarkdown('# Hello World');
 console.log(html);
 ```
 
-### 添加复制代码功能
+### Wiring the copy button (browser hosts)
+
+Inside the iOS WebView host, `scripts/copy.js` already handles copying. In a
+plain browser, delegate the click yourself:
 
 ```javascript
-document.addEventListener('click', function(e) {
-  if (e.target.classList.contains('code-copy-button') ||
-      e.target.closest('.code-copy-button')) {
-    const button = e.target.classList.contains('code-copy-button')
-      ? e.target
-      : e.target.closest('.code-copy-button');
-
-    const wrapper = button.closest('.code-block-wrapper');
-    if (!wrapper) return;
-
-    const codeNode = wrapper.querySelector('code');
-    const codeText = codeNode ? codeNode.textContent : '';
-
-    navigator.clipboard.writeText(codeText).then(() => {
-      const copyTextSpan = button.querySelector('.copy-text');
-      copyTextSpan.textContent = 'Copied!';
-      setTimeout(() => {
-        copyTextSpan.textContent = 'Copy code';
-      }, 2000);
-    });
-  }
+document.addEventListener('click', (e) => {
+  const button = e.target.closest('.code-copy-button');
+  if (!button) return;
+  const code = button.closest('.code-block-wrapper')?.querySelector('code');
+  if (!code) return;
+  navigator.clipboard.writeText(code.textContent).then(() => {
+    const label = button.querySelector('.copy-text');
+    label.textContent = 'Copied!';
+    setTimeout(() => { label.textContent = 'Copy'; }, 2000);
+  });
 });
 ```
 
-## 功能示例
+## Chat runtime
 
-### 代码块
+`templates/scripts/chat-renderer.js` is an upper runtime built on the same
+single-document renderer. It keeps a whole conversation in one container and
+incrementally updates only the active message:
 
-\`\`\`javascript
-function hello() {
-  console.log("Hello, World!");
-}
-\`\`\`
+```js
+MarkdownChatRenderer.mount();
+MarkdownChatRenderer.setMessages(messages);
+MarkdownChatRenderer.appendMessage(message);
+MarkdownChatRenderer.appendChunk(messageId, chunk, { isLast: false });
+MarkdownChatRenderer.finishMessage(messageId);
+MarkdownChatRenderer.scrollToBottom(true);
+```
 
-### 数学公式
+When enabled through `chat.messageActions`, it renders accessible whole-message
+copy/retry/edit controls. Browser and native hosts can listen for
+`markdown-chat-action` and `markdown-chat-viewport` DOM events. The latter
+reports `isNearBottom`, scroll offset, content height, and viewport height.
 
-行内数学：$E = mc^2$
+### Reasoning
 
-块级数学：
+A reasoning model publishes its chain of thought in one of two shapes, and the
+runtime handles both without the host having to know which:
 
-$$
-\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}
-$$
+```js
+// Inline: `<think>` … `</think>` arrives inside the content stream.
+MarkdownChatRenderer.appendChunk(id, '<think>weighing the options');
+MarkdownChatRenderer.appendChunk(id, '</think>The answer is 42.');
 
-### 任务列表
+// Channel: the provider streams reasoning in its own SSE field.
+MarkdownChatRenderer.appendReasoningChunk(id, 'weighing the options');
+MarkdownChatRenderer.appendChunk(id, 'The answer is 42.');
+```
 
-- [x] 已完成的任务
-- [ ] 未完成的任务
+Either way the reasoning lands in a fold above the message: open while the model
+is thinking, collapsed to a single tappable line the moment the first answer
+text arrives. A reader who opens or closes the fold themselves is never
+overruled afterwards. `finishReasoning(id)` closes it early;
+`setReasoningVisible(id, expanded)` drives it from the host; toggles are
+published as a `markdown-chat-reasoning` DOM event.
+
+Copying a message copies the answer, not the reasoning.
+
+```js
+window.MarkdownWebViewConfig = {
+  chat: {
+    reasoning: {
+      enabled: true,          // false leaves markers as literal text
+      inlineTags: true,       // false: only appendReasoningChunk feeds the fold
+      tags: ['think', 'thinking', 'thought', 'reasoning', 'reason'],
+      autoCollapse: true,     // fold away when the answer begins
+      defaultExpanded: false, // for finished messages loaded from history
+      labels: {
+        thinking: 'Thinking…',
+        done: 'Thought process',
+        duration: 'Thought for {seconds}s'
+      }
+    }
+  }
+};
+```
 
-### 嵌套列表
+Outside the chat runtime, `renderMarkdown()` folds a complete `<think>` block
+into a `<details class="md-reasoning">` element — configured through the same
+shape under the `reasoning` render option, and available without turning on
+`allowRawHTML`. `splitReasoning(text)` and `createReasoningSplitter()` are
+exported for hosts that want to separate the two channels themselves; the
+splitter is streaming-safe, so a marker arriving as `<thi` + `nk>` is still
+recognised.
 
-- 第一层
-  - 第二层
-    - 第三层
+## Streaming & bridge event contract
 
-### 表格
+The WebView host (`templates/scripts/renderer.js`) exposes:
 
-| 列1 | 列2 | 列3 |
-|-----|-----|-----|
-| A   | B   | C   |
-| 1   | 2   | 3   |
+```js
+window.renderMarkdown(text)                   // full render (starts a new content cycle)
+window.appendMarkdownChunk(chunk, { isLast }) // streaming append (rAF-coalesced)
+window.clearContent()                         // clear (starts a new content cycle)
+window.getContentHeight()                     // synchronous height measurement
+```
 
-### Emoji
+Event contract (delivered to the native host via `bridge.js`):
 
-支持 emoji shortcode：:smile: :heart: :rocket:
+| event | when it fires |
+|---|---|
+| `renderComplete` | **Exactly twice** per content cycle: first paint + the final (`isLast`) flush. |
+| `contentHeightChanged` | Height changes in between — streaming flushes, image loads, font-size changes (debounced host-side). |
 
-## 项目结构
+Incremental streaming (the default) caches HTML up to the last completed safe
+block boundary and re-renders only the unstable tail, keeping total render
+cost O(n) across the whole stream; set `streaming.incremental = false` to fall
+back to full re-renders. A safe boundary is a blank line, the closing fence of
+a code block, or the closing `$$` of a display formula — so a long code block
+or formula leaves the live tail as soon as it is complete instead of being
+reparsed on every frame until the next blank line.
 
+`renderMarkdownFragment(text, options)` renders straight to a `DocumentFragment`
+instead of an HTML string. The chat runtime uses it so that a streamed message
+is parsed once per frame rather than being serialized and parsed back again.
+
+## Malformed markdown
+
+Model output is only approximately standard markdown, and the renderer treats
+that as normal rather than as an error:
+
+| input | rendered as |
+|---|---|
+| `The bag is $100 and the tripod is $200.` | plain text — a lone `$` is not a formula |
+| `Formula: $x^{2$` | the literal `$x^{2$`, in the surrounding text colour |
+| `$\foobar{x}$` | the literal source — an unknown macro is not painted red |
+| `See \[1\] for details.` | one sentence — a citation is not promoted to display maths |
+| `` `echo $PATH` `` then `$HOME` | code span preserved, `$HOME` left alone |
+
+An expression that fails to parse is emitted as `<span class="md-math-raw">`
+carrying the original delimiters, so nothing is lost and copying the text back
+out still round-trips. When the parse failed on settled (non-streaming) text
+the span also carries `data-md-math-error` with KaTeX's reason, which is
+invisible to the reader and useful in a debugger.
+
+## Theme system (token-based)
+
+The render core ships a **token-based theme engine**: a named preset plus
+per-token overrides, switchable at runtime (no rebuild required).
+
+### API
+
+```javascript
+import { applyTheme, setThemePreset, getThemePresets } from '@cellgit/markdown-render';
+
+// 1) Switch to a named preset
+setThemePreset('github');           // 'system' (default) | 'github'
+
+// 2) Preset + forced color scheme + per-token overrides
+applyTheme({
+  preset: 'github',
+  mode: 'auto',                     // 'auto' | 'light' | 'dark'
+  tokens: {
+    light:   { '--chat-link-color': '#0a7d55' },
+    dark:    { '--chat-link-color': '#3fb950' },
+    metrics: { '--md-h1-size': '2.2em', '--md-code-radius': '8px' },
+    code:    { light: { '--hljs-keyword': '#d73a49' } }
+  }
+});
+
+getThemePresets(); // ['system', 'github']
 ```
-markdown-render/
-├── src/
-│   ├── index.js              # 主入口
-│   ├── markdown.js           # markdown-it 配置
-│   ├── highlight.js          # 代码高亮
-│   ├── math.js               # 数学公式渲染
-│   ├── utils.js              # 工具函数
-│   ├── styles.css            # 样式表
-│   └── pipeline/             # Pipeline 后处理
-│       ├── index.js          # Pipeline 编排
-│       ├── copy-button.js    # 复制按钮
-│       └── link-handler.js   # 链接处理
-├── dist/
-│   └── markdown-render.js    # 构建产物
-├── package.json
-├── rollup.config.js
-└── test.html                 # 测试页面
+
+`applyTheme` creates/updates a single `<style id="md-theme-vars">` whose
+selectors mirror the base stylesheet, so overrides win on equal specificity
+and `mode:'auto'` still follows the system color scheme. Tokens you don't
+override fall back to the baseline defaults in `styles.css`.
+
+### The three token families
+
+| family | purpose | representative tokens | per-scheme |
+|---|---|---|---|
+| palette | text / links / fills / tables / code card colors, error text | `--chat-text-color`, `--chat-link-color`, `--code-surface`, `--md-blockquote-border`, `--md-error-color` | yes (light/dark) |
+| code | syntax-highlight colors | `--hljs-keyword`, `--hljs-string`, `--hljs-comment` | yes (light/dark) |
+| metrics | sizes / line-heights / spacing / radii (relative to base font) | `--md-h1-size`…`--md-h6-size`, `--md-body-line-height`, `--md-paragraph-margin`, `--md-list-indent`, `--md-code-radius` | no (shared) |
+
+See `src/theme.js` for the complete token list. Layout variables are set via
+host APIs: `--markdown-padding` / `--markdown-background` /
+`--markdown-bottom-gap` / `--markdown-font-size` (mapped from iOS Dynamic
+Type by the SDK).
+
+### Config contract (WebView hosts / iOS SDK)
+
+WebView hosts drive the theme through the injected global config:
+
+```js
+window.MarkdownWebViewConfig = {
+  theme: {
+    mode: 'auto',          // 'auto' | 'light' | 'dark'
+    preset: 'system',      // 'system' | 'github'
+    tokens: { /* same shape as applyTheme's tokens, optional */ }
+  }
+};
 ```
 
-## Pipeline 机制
+`renderer.js` passes that `theme` straight to `applyTheme`. The Swift
+`MarkdownTheme` in `swift-markdown-kit` serializes into exactly this shape.
+
+## Extensions (custom inline syntax)
 
-本库采用 Pipeline 架构，可以轻松扩展后处理功能：
+The render core supports **declarative inline extensions**: custom syntax
+registered by configuration, never arbitrary JS — safe (CSP-friendly, all
+values escaped), themable (`.md-ext-{name}`), and tappable. Two recognition
+modes:
+
+- **prefix**: a trigger string plus a bounded body, e.g. `@alice`, `$AAPL`, `#tag`.
+- **delimiter**: paired delimiters capturing inner text, e.g. `[[Home]]`, `||spoiler||`.
 
 ```javascript
-// src/pipeline/index.js
-const pipelines = [
-  addCopyButton,    // 添加复制按钮
-  handleLinks       // 处理链接
+const extensions = [
+  { name: 'mention',  type: 'prefix',    trigger: '@', body: 'word',  action: 'mention' },
+  { name: 'ticker',   type: 'prefix',    trigger: '$', body: 'upper', action: 'ticker', className: 'ticker' },
+  { name: 'wikilink', type: 'delimiter', open: '[[', close: ']]',     action: 'wikilink', display: '{value}' }
 ];
 
-export function applyPipeline(html) {
-  return pipelines.reduce((currentHtml, processor) => {
-    return processor(currentHtml);
-  }, html);
-}
+renderMarkdown('Hi @alice, buy $AAPL, see [[Home]]', { extensions });
+// → <span class="md-ext md-ext-mention" data-md-ext="mention" data-md-value="alice" data-md-action="mention">@alice</span> …
 ```
 
-## 自定义 Pipeline
+| field | description |
+|---|---|
+| `name` | Extension id (drives the `md-ext-{name}` class and `data-md-ext`); sanitized to `[A-Za-z0-9_-]` |
+| `type` | `'prefix'` (default) or `'delimiter'` |
+| `trigger` | prefix: the trigger string (e.g. `@`) |
+| `body` | prefix: body character class `word`/`alnum`/`letter`/`upper`/`upperdigit`, or an explicit allowed-character string |
+| `open` / `close` | delimiter: the delimiters |
+| `action` | optional; action name reported on tap (via the host bridge) |
+| `display` | optional; display template with a `{value}` placeholder (default: prefix shows trigger+body, delimiter shows inner text) |
+| `className` / `dataset` | optional; extra class / `data-*` attributes (keys sanitized, values escaped) |
+
+**Safety**: values and display text are always HTML-escaped, identifiers are
+sanitized, and scanning is length-capped (no ReDoS, no HTML/JS injection).
+
+**Any trigger character works**: markdown-it's `text` rule only stops at
+"terminator" characters. When an extension's first character is not one of
+them (e.g. `||…||`, `/cmd`), the core automatically swaps in an equivalent
+text rule so the extension also matches mid-text — no caller action needed.
+
+### Per-extension style hooks (themable)
+
+`buildExtensionCSS(extensions)` generates CSS rules with fallback values for
+each extension, injected automatically by `renderer.js`
+(`<style id="md-ext-vars">`). Hosts restyle extensions purely through theme
+tokens — no CSS crosses the bridge:
+
+```css
+/* available for each extension {name}: */
+--md-ext-{name}-color      /* default var(--chat-link-color) */
+--md-ext-{name}-bg         /* default transparent */
+--md-ext-{name}-radius / -padding / -weight / -decoration
+```
+
+### Config contract (WebView hosts / iOS SDK)
+
+```js
+window.MarkdownWebViewConfig = { extensions: [ /* same array as above */ ] };
+```
+
+`renderer.js` passes `extensions` through to the renderer; `MarkdownExtension`
+in `swift-markdown-kit` serializes into this array, and taps on elements with
+`data-md-action` are reported back to Swift over the bridge.
+
+## Pipeline
 
-你可以添加自己的 pipeline 处理器：
+Rendered HTML flows through a configurable post-processing pipeline (one
+parse / one serialize regardless of processor count). Built-ins:
+`wrapTables` (horizontal-scroll containers), `addCopyButton` (code block
+header + copy button), `handleLinks` (link policy).
+
+Custom processors:
 
 ```javascript
-// src/pipeline/my-processor.js
-export function myProcessor(html) {
-  // 处理 html
-  return html;
-}
+import { registerPipeline } from '@cellgit/markdown-render';
 
-// 在 src/pipeline/index.js 中添加
-import { myProcessor } from './my-processor.js';
+// Processors mutate the Document in place (no string round-trips)
+registerPipeline('addAnchor', (doc) => {
+  doc.querySelectorAll('h2').forEach((h) => h.setAttribute('id', h.textContent));
+});
 
-const pipelines = [
-  addCopyButton,
-  handleLinks,
-  myProcessor  // 添加你的处理器
-];
+renderMarkdown(text, { pipeline: ['wrapTables', 'addCopyButton', 'handleLinks', 'addAnchor'] });
+```
+
+## Project structure
+
+```
+markdown-render/
+├── src/
+│   ├── index.js              # main entry (public API)
+│   ├── markdown.js           # markdown-it setup + math rules
+│   ├── highlight.js          # code highlighting (common build + auto-detect policy)
+│   ├── math.js               # KaTeX rendering & preprocessing
+│   ├── extensions.js         # declarative inline extensions
+│   ├── theme.js              # token-based theme engine
+│   ├── dom-utils.js          # streaming DOM diff
+│   ├── styles.css            # baseline styles
+│   └── pipeline/             # HTML post-processing pipeline
+├── templates/
+│   ├── markdown-render.html  # WebView host page
+│   └── scripts/              # bridge / renderer / height-sync / copy
+├── dist/                     # build output
+├── ios-bundle/               # build:ios output (input to swift-markdown-kit)
+└── tests/                    # Node test suites
 ```
 
-## 版本依赖
+## Dependencies
 
 - **markdown-it**: ^14.1.0
-- **highlight.js**: ^11.9.0 (匹配 GPTDemo)
-- **katex**: ^0.16.9 (匹配 GPTDemo)
+- **highlight.js**: ^11.9.0 (common build)
+- **katex**: ^0.16.9
 - **markdown-it-task-lists**: ^2.1.1
 - **markdown-it-emoji**: ^3.0.0
 
-## 构建
+## Build
 
 ```bash
-npm run build
+npm run build       # dist/ (browser IIFE + ESM + CSS + fonts + templates)
+npm run build:ios   # the above + ios-bundle/ (consumed by swift-markdown-kit)
 ```
 
-构建产物：`dist/markdown-render.js` (约 1.3MB)
+Output: `dist/markdown-render.js` (~620KB, highlight.js common build).
 
-## 测试
+> **Syncing with swift-markdown-kit**: after changing anything under `src/` or
+> `templates/`, run `npm run build:ios` →
+> `swift-markdown-kit/create_xcframework.sh` (encrypts `ios-bundle/` into
+> `MarkdownRenderPackage.dat` and produces the XCFramework). See the
+> swift-markdown-kit README for details.
 
-在浏览器中打开 `test.html` 查看所有功能演示。
+## Tests
 
-## CSS 变量
+```bash
+npm test
+```
 
-可通过 CSS 变量自定义主题：
+Node-side test suites under `tests/`:
 
-```css
-:root {
-  --chat-text-color: #1C1C1E;
-  --chat-link-color: #0A5EFF;
-  --chat-background: #FFFFFF;
-  --chat-code-bg: var(--chat-background);
-  --chat-inline-code-bg: rgba(175, 184, 193, 0.2);
-  --chat-table-border: #D1D5DB;
-  --chat-copy-button-bg: rgba(0, 0, 0, 0.65);
-}
+| file | what it covers |
+|---|---|
+| `tests/render.test.mjs` | Math boundary checks, table wrapping, link policy, options gating, raw HTML default, emoji, task lists. |
+| `tests/streaming.test.mjs` | rAF-coalesced incremental streaming; stable / unstable boundary correctness; the renderComplete / height event contract. |
+| `tests/extensions.test.mjs` | Declarative extensions: prefix / delimiter recognition, non-terminator trigger chars, escaping & sanitizing, `buildExtensionCSS`. |
+| `tests/theme.test.mjs` | Token-based theme engine: presets, override precedence, style element reuse. |
+| `tests/math-no-corruption.test.mjs` | Math boundaries never corrupt prose (currency, code spans, …). |
 
-@media (prefers-color-scheme: dark) {
-  :root {
-    --chat-text-color: #ECECEC;
-    --chat-link-color: #0A84FF;
-    --chat-background: #1C1C1E;
-    /* ... */
-  }
-}
-```
+Open `test.html` in a browser for the visual sandbox.
 
-## 浏览器兼容性
+## Browser compatibility
 
 - Chrome/Edge: ✅
 - Safari: ✅
@@ -332,9 +590,9 @@ npm run build
 
 MIT
 
-## 致谢
+## Acknowledgements
 
-本项目基于以下优秀开源项目：
+Built on these excellent open-source projects:
 
 - [markdown-it](https://github.com/markdown-it/markdown-it)
 - [highlight.js](https://highlightjs.org/)