diff --git a/README.md b/README.md
index 5f88ece..e5f0901 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
# makepad-html
+English | [简体中文](README.zh-CN.md)
+
Reusable native HTML/CSS rendering for Makepad applications. The standalone Rust core lays out and paints documents; the optional `HtmlView` widget displays them with native scrolling. Applications supply HTML, resource bytes, viewport size and lifecycle decisions.
This repository owns the rendering API, Makepad adapter, standalone viewer, Blitz patches and compatibility lab. Robrix’s article editor is one consumer. [Architecture and responsibilities](docs/architecture.md).
@@ -105,7 +107,7 @@ Extracted from `OctoSense-org/robrix2`'s `wechat-ui` renderer work, based on Rob
commit `7f24f14ac5c59f65b84f078944443e3977c9f6f0` plus the reviewed CSS fixes.
Original license notices are retained. Blitz source provenance and the exact
local diffs are recorded in `vendor/blitz/UPSTREAM.json`, `wechat-css-1.patch`
-and the subsequent `table-2.patch` and `text-shadow-3.patch`.
+and the subsequent `table-2.patch`, `text-shadow-3.patch` and `inline-4.patch`.
The table parity pass fixes merged-cell borders, border conflicts and cell
alignment. It passes 27 default / 29 extended tests and retains the same
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..9443bc8
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,120 @@
+# makepad-html
+
+[English](README.md) | 简体中文
+
+为 Makepad 应用提供可复用的原生 HTML/CSS 渲染。独立的 Rust 核心负责文档的布局与绘制;可选的 `HtmlView` 控件以原生滚动方式显示渲染结果。应用负责提供 HTML、资源字节、视口尺寸以及生命周期决策。
+
+本仓库负责渲染 API、Makepad 适配层、独立查看器、Blitz 补丁和兼容性实验室。Robrix 的文章编辑器是其中一个使用方。参见[架构与职责](docs/architecture.md)。
+
+经过测试的引擎是 [Blitz e99fbdbd](https://github.com/DioxusLabs/blitz/tree/e99fbdbd1d03b9f0aa1622c3f810d95daac92042),而不是 WebView:html5ever → Stylo → Taffy/Parley → AnyRender/Vello CPU → RGBA。这次初步集成在渲染时保留输入的 HTML/CSS;HTML 编辑以及无损保留样式的导入仍是单独的后续工作。
+
+```rust
+use ::makepad_html::{render_html, RenderOptions, ResourceMap};
+
+let mut resources = ResourceMap::default();
+// Bytes have already been selected/authorized/downloaded by the host.
+let stylesheet_url = resources.insert_css("theme.css", "p { color: #337b60 }")?;
+let html = format!("
你好,世界
");
+let bitmap = render_html(&html, RenderOptions::default(), &resources)?;
+assert_eq!(bitmap.rgba.len(), bitmap.width as usize * bitmap.height as usize * 4);
+# Ok::<(), makepad_html::RenderError>(())
+```
+
+请在工作线程上运行 `render_html`。宿主在展示结果之前,需要确认文档以及相关的资源授权仍然有效。`ResourceMap` 是一份不可变的授权快照,而不是持久的权限令牌。`DocumentSession` 会一直持有这份快照,直到宿主释放该会话。权限或账号发生变化后,请重新构建资源表。切勿把访问令牌、cookie 或带签名的远程 URL 放进文档的 HTML/CSS 或资源标识符中。
+
+## 资源边界
+
+只有宿主插入的、位于 `https://makepad-html.invalid/assets/` 之下的精确 URL 才能被解析。PNG/JPEG 图片在准入之前会在限定范围内解码;CSS 必须是 UTF-8 且有大小限制。相对引用会解析到这一命名空间内。未映射的 URL,包括 HTTP(S)、`file:`、`data:`、CSS `@import`、图片/背景 URL 以及 `@font-face` URL,都会得到空响应,不发生任何 I/O。必须把被拒绝的请求也以响应完成,否则被拒绝的样式表可能让上游无限期等待。
+
+没有 `blitz-net`、请求客户端、导航集成、剪贴板集成,也没有 JavaScript 包。主动元素和子文档元素(`script`、`iframe`、表单、object/embed)以及 SVG 和 MathML 都会被拒绝。文档按标准模式 HTML 解析。事件属性在本渲染器中不起作用;**它不是可用于后续浏览器场景的 HTML 净化器**。
+
+默认的 `system-fonts` 特性会有意启用操作系统字体的发现与加载,从而在 Apple 平台上支持 `font-family: "PingFang SC", system-ui, sans-serif`;这与经文档授权的文件加载是两回事。`--no-default-features` 会关闭系统字体发现,但目前这一初版 API 不提供自定义字体注册接口,文字覆盖范围因此受限。
+
+预算:HTML 256 KiB;保守的 token/深度预检(16,384 个 token,64 个显式开始标签);最多 48 个已授权资源,每个 8 MiB,合计 24 MiB;每个 CSS 资源 64 KiB;图片最大 4096 × 4096,解码分配上限 64 MiB;128 次资源请求;8 轮解析;输出最多 16,777,216 像素。输出尺寸上限为 16,384 像素,低于 Vello CPU 的 16 位尺寸限制。过长的内容会报告 `clipped`;宿主必须展示这一状态,或改用未来的分页/分块实现,而不能把裁剪后的结果悄悄当作完整文档。
+
+这些限制约束的是输入、已授权资源和输出分配。它们**不**约束 Stylo/Taffy/Vello 的全部中间分配,也不提供可取消的 CPU 时限。工作线程能让 UI 保持响应,但不等于进程隔离。不要声称这个 beta 引擎已针对任意恶意 HTML/CSS 做过加固;在大范围部署之前,导入不可信的公开内容需要单独受监管的进程和资源控制。
+
+## Makepad 适配层
+
+启用 `features = ["makepad"]`,在注册 Makepad 基础控件之后注册 `makepad_html::makepad::script_mod(vm)`,然后实例化 `mod.widgets.HtmlView`。在 Rust 作用域中引入 `makepad_html::makepad::HtmlViewWidgetRefExt`:
+
+```rust,ignore
+ui.html_view(cx, ids!(html_preview)).set_rendered(cx, &bitmap);
+// On logout, grant revocation, or document replacement:
+ui.html_view(cx, ids!(html_preview)).clear(cx);
+```
+
+Makepad 也把它内置的解析器重新导出为 `makepad_html`。使用
+`use makepad_widgets::*` 时,请用 `::makepad_html` 引入这个外部 crate,
+或者给它设置一个 Cargo 依赖别名(Robrix 使用 `makepad-html-renderer`)。
+
+如果接收者是 `Widget`/`RefMut` 而不是 `WidgetRef`,请改为引入
+`HtmlViewWidgetExt`。
+
+适配层把 RGBA 转换为 Makepad 的 `VecBGRAu8_32`,在带裁剪的原生滚动视图中显示结果,不使用 WebView。本 crate 的 lockfile 将 Makepad 固定在 `47837267faf6970a6cc36acedf9f83846b277307`,与 Robrix 使用相同的来源/分支,以避免出现重复的控件类型。宿主应按测得的视图宽度和当前 DPI 渲染;视图宽度变化时,在宿主重新渲染之前只会缩放现有位图。
+
+适配层会发出文档坐标系下的点击事件,以及水平方向的滚轮/触控板事件。
+在工作线程上保留一个 `DocumentSession`,调用 `activate` / `scroll_horizontal`,
+状态变化后再调用 `render`。`HtmlAction::OpenLink` 只是发给宿主的请求;
+不会自动打开浏览器、发起 HTTP 请求或进行导航。请把 `ScrollTo` 转发给
+`HtmlViewRef::scroll_to`。独立查看器演示了这一生命周期,包括滚动后的链接、
+页内片段跳转、details 展开/收起以及嵌套的水平滚动容器。宿主替换文档或撤销授权时,
+请释放会话并清空控件;丢弃过期的工作线程结果。
+
+目前尚未提供文字选择/复制、键盘链接焦点、无障碍文本和富文本编辑。
+渲染和纹理上传仍然整张替换位图;这不是分块渲染器。
+
+## 复现
+
+本 crate 有自己的 workspace/lockfile,因此可以独立于 Robrix 构建。运行时测试使用 aarch64 macOS 上的 Rust 1.98.0。在关闭默认特性的情况下,锁定依赖的构建检查也在 Rust 1.94.0 上通过。
+
+```sh
+cargo +1.98.0 test --locked
+cargo +1.98.0 test --locked --features test-svg,blitz-dom/floats
+cargo +1.98.0 run --locked --example render_fixture -- target/render-evidence
+cargo +1.98.0 run --locked --features makepad --example viewer
+
+# View a host-selected document. Resources are explicit ID=PATH grants.
+cargo +1.98.0 run --locked --features makepad --example viewer -- \
+ page.html theme.css=./theme.css logo.png=./logo.png
+
+# macOS: verify the native widget, screenshot OCR and scrolling.
+python3 lab/verify_native.py target/debug/examples/viewer
+```
+
+原生验证脚本只启动隔离的 fixture 可执行文件,使用自有的 loopback 桥接,截图并用 OCR 检查中文文字和表格,滚动原生视图,然后退出该进程。它不会连接 Matrix 账号。`MAKEPAD_HIDE_WINDOWS=1` 可让验证过程不出现在用户屏幕上。
+
+证据与局限见 `lab/README.zh-CN.md`。测试证明的是本地行为,而不是微信 9/10 的视觉评分。上游仍处于 beta 阶段,CSS 支持并不完整:[上游状态](https://blitz.is/status/css)。
+
+## 兼容性实验室
+
+[源自微信的 CSS 用例](lab/wechat-corpus/README.md)是其中一套兼容性测试,
+包含原始来源哈希、固定版本的上游与打过补丁的 Blitz 截图,以及真实
+WKWebView 参考截图。[HTML5 对照](lab/comparison/README.zh-CN.md)
+覆盖通用 HTML。两套测试都不依赖文章编辑器。
+
+引擎补丁由本仓库维护,位于 [vendor/blitz](vendor/blitz/README.makepad-html.md)。
+使用方直接依赖本 crate;不需要 Cargo patch 覆盖,也不需要 Robrix 的检出。
+该控件显示的是一张位图,可选地由持久的离线文档支撑。
+选择、键盘/无障碍集成、动画以及更完整的手势路由仍在路线图中。
+
+## 来源
+
+提取自 `OctoSense-org/robrix2` 的 `wechat-ui` 渲染器工作,基于 Robrix
+提交 `7f24f14ac5c59f65b84f078944443e3977c9f6f0` 以及经过评审的 CSS 修复。
+保留了原有的许可证声明。Blitz 源码来源和确切的本地差异记录在
+`vendor/blitz/UPSTREAM.json`、`wechat-css-1.patch`
+以及后续的 `table-2.patch`、`text-shadow-3.patch` 和 `inline-4.patch` 中。
+
+表格对齐轮次修复了合并单元格边框、边框冲突和单元格对齐。
+默认 27 项 / 扩展 29 项测试通过,并保持相同的生产资源策略。参见[实测结果与剩余差距](docs/table-parity.md)。
+
+文字阴影轮次增加了偏移、模糊、多重阴影、继承颜色以及文字装饰阴影。
+它启用了 Vello CPU 的 `filters` 特性;测试所用的后端采用单线程渲染(当上游的
+`multithreading` 特性被统一启用时,上游会禁用 filters)。这并不代表已支持通用的 CSS
+filter 链。参见[对照结果与限制](docs/text-shadow-parity.md)。
+
+行内/交互轮次增加了水平 HTML ruby 注音、sup/sub 以及嵌套的长度/百分比偏移,
+修正了原子行内盒的基线,保留了 span 之间的空格,并加入由工作线程持有的文档交互。
+Parley 0.11.1 与 Blitz 一同 vendored,使下游应用获得相同的布局补丁。
+参见[测量、原生证据与剩余限制](docs/inline-parity.md)。
diff --git a/lab/README.md b/lab/README.md
index 9a7e168..68ed0d3 100644
--- a/lab/README.md
+++ b/lab/README.md
@@ -1,5 +1,7 @@
# Native HTML integration validation
+English | [简体中文](README.zh-CN.md)
+
This integration supplies native HTML/CSS article previews to independent hosts. It is not a migration of Robrix to Dioxus, an OctoSense runtime dependency, or an implementation of arbitrary HTML rich-text editing.
Source: this repository (`src/`). Engine commit: `e99fbdbd1d03b9f0aa1622c3f810d95daac92042`. Makepad commit: `47837267faf6970a6cc36acedf9f83846b277307`. Standalone lockfile records all resolved dependencies. Runtime tests: Rust 1.98.0, aarch64 macOS. Rust 1.94.0 `--no-default-features` build check also passed.
@@ -29,7 +31,7 @@ Known boundaries:
- Output/resource budgets do not create a CPU or process sandbox. Upstream intermediate allocations and pathological CSS still require stronger containment before admitting arbitrary public documents.
- Long documents beyond the bitmap budget are explicitly reported as clipped; the host must display that condition. Tiled rendering is future work.
-Reproduction commands and the host API are in `README.md`. No personal Matrix credentials, profiles or accounts were used.
+Reproduction commands and the host API are in the [repository README](../README.md). No personal Matrix credentials, profiles or accounts were used.
Robrix's optional `article_blitz` feature now uses this renderer for validated
local draft previews. Its integration checks, Palpo lifecycle checks and actual
diff --git a/lab/README.zh-CN.md b/lab/README.zh-CN.md
new file mode 100644
index 0000000..e6c2893
--- /dev/null
+++ b/lab/README.zh-CN.md
@@ -0,0 +1,46 @@
+# 原生 HTML 集成验证
+
+[English](README.md) | 简体中文
+
+本集成为独立宿主提供原生 HTML/CSS 文章预览。它不是把 Robrix 迁移到 Dioxus,不是 OctoSense 的运行时依赖,也不是对任意 HTML 富文本编辑的实现。
+
+来源:本仓库(`src/`)。引擎提交:`e99fbdbd1d03b9f0aa1622c3f810d95daac92042`。Makepad 提交:`47837267faf6970a6cc36acedf9f83846b277307`。独立的 lockfile 记录了所有已解析的依赖。运行时测试:Rust 1.98.0,aarch64 macOS。Rust 1.94.0 下的 `--no-default-features` 构建检查也已通过。
+
+测试样例是原创的合成文章,不是抓取的微信页面。它们覆盖中英文(使用 PingFang SC 的 CSS 字体偏好)、行内强调、嵌套章节、图片资源授权、边框、背景、间距、CSS 变量、class/行内样式层叠、响应式媒体规则、深色模式以及一个基础表格。它们是有用的集成证据,但不是微信兼容性基准。
+
+生成的证据:
+
+- `evidence/mobile-light.png`:390 CSS px,2× 渲染。
+- `evidence/desktop-light.png`:760 CSS px,1× 渲染。
+- `evidence/mobile-dark.png`:390 CSS px,2× 渲染,使用样例自带的深色主题 CSS。
+- `evidence/native-top.png` 和 `native-bottom.png`:隔离 Makepad 窗口的真实截图,包括 Blitz 纹理的原生滚动。
+- `evidence/render-results.json`:引擎版本、尺寸、资源决策和耗时。
+- `evidence/native-validation.json`:原生可执行文件/图片哈希、窗口尺寸、OCR 断言和进程隔离检查。
+- `validation.json`:最终的测试/检查结果和证据哈希。
+
+渲染器测试套件通过像素检查 CSS 层叠/媒体查询变量、精确的内存内授权、被拒绝的远程/文件/data 资源、被阻止的嵌套导入、图片解码/显示、畸形资源、主动元素、输入/视口/深度限制、请求次数上限、长文章裁剪,以及中文响应式/深色样例。原生验证还会通过截图 OCR 检查真实的 Makepad 纹理路径和滚动行为。
+
+已知边界:
+
+- 该位图控件不支持 HTML 到可编辑文档的转换、导入样式的持久化 schema、文字选择或无障碍文本。
+- CSS 深色模式基于样例自带的规则,并不声称能复现微信的自动深色配色转换。
+- 没有 iOS 真机验证,也没有 Android/Windows/Linux 运行时验证。
+- 不支持任意 SVG、动画组件或微信私有标签;不执行 JavaScript。
+- 明确启用了系统字体发现;不捆绑分发 PingFang。
+- 没有与真实微信截图的相似度测量,也不声称达到 9/10。
+- 输出/资源预算并不构成 CPU 或进程沙箱。在接收任意公开文档之前,上游的中间分配和病态 CSS 仍需要更强的隔离。
+- 超出位图预算的长文档会被明确报告为已裁剪;宿主必须显示这一状态。分块渲染是后续工作。
+
+复现命令和宿主 API 见[仓库 README](../README.zh-CN.md)。未使用任何个人 Matrix 凭据、资料或账号。
+
+Robrix 的可选 `article_blitz` 特性现在使用本渲染器来预览经过验证的
+本地草稿。其集成检查、Palpo 生命周期检查以及真实的 Robrix
+截图单独记录在 [Robrix 集成实验室](https://github.com/OctoSense-org/robrix2/tree/wechat-ui/lab/article-components)。
+
+行内/交互轮次通过 `DocumentSession` 增加了原生链接、展开/收起、页内片段跳转
+以及水平嵌套滚动。额外的检查是
+`python3 lab/verify_interactions.py target/debug/examples/viewer`(需要 Pillow)。
+它检查真实的指针输入、拖动抑制、展开/收起往返后的像素、
+片段跳转 OCR、滚动后的链接,以及切换/点击水平幻灯片。
+结果:[交互证据](evidence/interactions/native-validation.json) 和
+[行内对照报告](../docs/inline-parity.md)。
diff --git a/lab/comparison/README.md b/lab/comparison/README.md
index fc6bf63..e68d07b 100644
--- a/lab/comparison/README.md
+++ b/lab/comparison/README.md
@@ -1,8 +1,12 @@
# DigitalOcean HTML: Blitz vs macOS WKWebView
+English | [简体中文](README.zh-CN.md)
+
Open [the interactive comparison](index.html). It has side-by-side captures,
desktop/narrow viewport selection, a same-coordinate wipe slider, text crops and
difference images. Raw captures and DOM measurements are in `evidence/`.
+The page, `evidence/` and `results.json` are generated locally by the
+reproduction steps below; they are git-ignored and not committed.
Source: [digitalocean/sample-html index.html](https://github.com/digitalocean/sample-html/blob/b658ada1c68912e9ac4026db63d687e8e2aa808a/index.html),
commit `b658ada1c68912e9ac4026db63d687e8e2aa808a`.
diff --git a/lab/comparison/README.zh-CN.md b/lab/comparison/README.zh-CN.md
new file mode 100644
index 0000000..89446c7
--- /dev/null
+++ b/lab/comparison/README.zh-CN.md
@@ -0,0 +1,91 @@
+# DigitalOcean HTML:Blitz 与 macOS WKWebView 对照
+
+[English](README.md) | 简体中文
+
+打开[交互对照页](index.html)。其中有并排截图、桌面/窄屏视口切换、
+同坐标擦除滑块、文字局部放大图和差异图。原始截图和 DOM 测量数据在 `evidence/` 中。
+对照页、`evidence/` 和 `results.json` 由下文的复现步骤在本地生成;
+它们被 git 忽略,不纳入版本库。
+
+来源:[digitalocean/sample-html index.html](https://github.com/digitalocean/sample-html/blob/b658ada1c68912e9ac4026db63d687e8e2aa808a/index.html),
+提交 `b658ada1c68912e9ac4026db63d687e8e2aa808a`。
+SHA-256:`96448c90c3ed0ede400f5f68d904201428bc730aa4355b3a4141f4c4c11071bc`。
+两个引擎接收的是完全相同的 4,394 个原始字节。下载的源文件保存在被忽略的
+`inputs/` 中;复现时会重新获取并校验固定版本。
+
+## 方法
+
+- 真实的 macOS 26.6.2 `WKWebView.takeSnapshot`,使用非持久数据存储,
+ 对比 Blitz `e99fbdbd` / Vello CPU 的像素输出,所用渲染器依赖与 Robrix
+ 相同。不改写 HTML/CSS,也不做图像配准/对齐。
+- 视口:800×600 和 390×844 CSS 像素,均为 DPR 2、浅色外观。
+ 窄视口是 macOS WebKit,**不是** iOS 设备测试。
+- 静态对照:关闭 WKWebView 页面 JavaScript。宿主诊断 JS
+ 等待 `document.fonts.ready`,读取计算样式和几何信息;
+ 它不修改文档。Blitz 没有 JS 引擎。
+- 动态对照:原始 HTML 不做修改,开启 WKWebView 页面 JS。
+ 一个 document-start `WKUserScript` 把 `Math.random` 替换为带固定种子的 LCG,
+ 使颜色可复现。这是对测试环境的改动,不是对源码的改写。
+ 卡片/正文点击使用 DOM `.click()`,而不是原生指针事件。
+- 生产入口 `makepad_html::render_html` 会以
+ `unsupported active/document element: script` 拒绝这一原始页面。`compare_html.rs`
+ 是一条单独的诊断用原始引擎路径,没有可以加载资源的网络 provider。
+ 它让 script 元素保持惰性,并不放宽应用的准入策略。这些原始引擎截图的成功
+ **并不**意味着 Robrix 能兼容原始源码。
+
+## 结果
+
+| 测量项 | Blitz | WKWebView |
+| --- | ---: | ---: |
+| 桌面卡片 x / y,CSS px | 268 / 240.5 | 266.8125 / 240.5 |
+| 窄屏卡片 x / y,CSS px | 63 / 362.5 | 61.8125 / 362.5 |
+| 卡片宽 × 高,CSS px | 264 × 119 | 266.359375 × 119 |
+| 静态内容 | `#000000` | `#000000` |
+| 加载时的页面 JS | 未执行 | `#20bc92` |
+| JS 卡片点击 | 无 JS 运行时 | 保持 `#20bc92` |
+| JS 正文点击 | 无 JS 运行时 | 变为 `#71da4e` |
+
+两个视口出现了相同的静态几何差异。Flex 居中、100% 页面高度、CSS 变量、
+内边距、rem 尺寸和静态颜色都能正确渲染。
+两张卡片矩形的交并比为 99.114%。Blitz 的卡片窄 2.359375
+CSS 像素;左边缘向右偏 1.1875 像素。虽然两个引擎报告的 y 坐标相同,
+但观察到的 Blitz 卡片光栅起点低一个设备像素(DPR 2 下为 0.5 CSS 像素)。
+
+任一 RGB 通道误差 >16/255 的像素占比:
+
+- 卡片并集区域:两个视口均为 **4.762%**。
+- 文字并集裁剪区域(含六个设备像素的边距):**16.332%**。
+- 整帧:桌面 0.315%,窄屏 0.460%。相同的黑色背景
+ 主导了这些整帧数字;它们不是有意义的整体保真度评分。
+ 文字裁剪区域显示出笔画/抗锯齿和字距差异。
+ 尚未把字体选择、字形整形和光栅化分别确认为原因。
+
+`results.json` 包含矩形数值、绝对通道误差、裁剪边界、
+来源与产物哈希,以及明确的测试限定条件。差异 PNG
+把绝对 RGB 误差放大四倍以便观察。文字放大图对相同裁剪坐标使用 3× 最近邻
+放大;原始截图均予保留。
+
+结论:该样本的静态布局很接近,但存在可测量的字体排印和
+像素对齐差异。其 JS 驱动的行为 Blitz 无法复现。
+这一个简单的变色页面不涵盖文章图片、表格、复杂的微信
+CSS、长文档或编辑,也不能据此得出 9/10 的兼容性评分。
+
+## 复现
+
+需要 macOS、Swift、Rust 1.98、Python 3、Pillow 和 NumPy。在仓库根目录运行:
+
+```sh
+cargo +1.98.0 build --locked --manifest-path Cargo.toml --example compare_html
+swiftc lab/comparison/webview.swift -o target/html-comparison-webview
+python3 lab/comparison/compare.py --render \
+ --blitz-bin target/debug/examples/compare_html \
+ --webview-bin target/html-comparison-webview
+open lab/comparison/index.html
+```
+
+不带 `--render` 运行 `compare.py` 时,只会根据已有的原生截图
+重新计算指标/合成图。页面的随机变色行为经过了测试,但任意页面
+JS、外部资源、导航和 iOS 都不在本实验范围内。
+
+本地文件输入、下载的第三方资源及其截图均被忽略(不纳入版本库)。
+可复现的原创样例和已发布的截图位于 `../wechat-corpus/`。