@coding01/docsjs 0.1.3 → 0.1.6

package/README.md

@@ -3,8 +3,19 @@
 Render-first Word fidelity component for the web.  
 Import Word/WPS/Google Docs content from paste or `.docx` while preserving structure and layout as much as possible.
 
+[![npm version](https://img.shields.io/npm/v/@coding01/docsjs)](https://www.npmjs.com/package/@coding01/docsjs)
+[![npm downloads](https://img.shields.io/npm/dm/@coding01/docsjs)](https://www.npmjs.com/package/@coding01/docsjs)
+[![CI](https://github.com/fanly/docsjs/actions/workflows/ci.yml/badge.svg)](https://github.com/fanly/docsjs/actions/workflows/ci.yml)
+[![Pages](https://github.com/fanly/docsjs/actions/workflows/pages.yml/badge.svg)](https://github.com/fanly/docsjs/actions/workflows/pages.yml)
+
 [中文文档](./README.zh-CN.md)
 
+## GitHub Pages
+
+- Product page: [https://docsjs.coding01.cn/](https://docsjs.coding01.cn/)
+- Source: `docs/index.html`
+- Deploy workflow: `.github/workflows/pages.yml`
+
 ## What You Get
 
 - Web Component core: `docs-word-editor`
@@ -70,7 +81,7 @@ el.addEventListener("docsjs-change", (e) => {
 ### Events
 
 - `docsjs-change`
-  - payload: `{ htmlSnapshot: string; source: "paste" | "upload" | "api" | "clear"; fileName?: string }`
+  - payload: `{ htmlSnapshot: string; source: "paste" | "upload" | "api" | "clear"; fileName?: string; parseReport?: DocxParseReport }`
 - `docsjs-error`
   - payload: `{ message: string }`
 - `docsjs-ready`
@@ -91,27 +102,49 @@ el.addEventListener("docsjs-change", (e) => {
 
 ## Feature Checklist
 
+<!-- GENERATED:FEATURE_CHECKLIST_EN:START -->
+### Core
+
 - ✅ Web Component core (`docs-word-editor`)
-- ✅ React adapter (`@coding01/docsjs/react`)
-- ✅ Vue adapter (`@coding01/docsjs/vue`)
-- ✅ Paste import (`text/html`, `text/plain`)
-- ✅ Clipboard image hydration (`file:/blob:/cid:/mhtml:` to data URL)
-- ✅ `.docx` upload and parse
-- ✅ Basic paragraph semantics (alignment, headings, line break)
-- ✅ Basic run styles (bold/italic/underline/strike/color/highlight/super/sub)
-- ✅ List reconstruction (`numId` + `ilvl` + `lvlText`)
-- ✅ Basic table structure (`table/tr/td`)
-- ✅ Embedded image relationship mapping (`rId -> media`)
-- ✅ Page geometry mapping (page height, margins, content width)
-- ✅ Runtime render fixes (`mso-*` compatibility, pagination spacer, empty paragraph normalization)
-- ✅ Events and public methods
-- ✅ React and Vue runnable demos
-- ✅ npm publish workflow with OIDC trusted publishing
-- ⏳ Floating anchors (`wp:anchor`) full layout fidelity
-- ⏳ Merged cells / nested tables full fidelity
-- ⏳ Footnotes / endnotes / comments / track changes
-- ⏳ OMML / charts / SmartArt
-- ⏳ Automated fidelity benchmark scorecard
+- ✅ React adapter + Vue adapter
+- ✅ Events and imperative public API
+- ✅ Strict-only parser strategy
+
+### Import Pipeline
+
+- ✅ Clipboard import (`text/html`, `text/plain`)
+- ✅ `.docx` upload + relationship media mapping
+- ✅ Clipboard image hydration (`file:/blob:/cid:`)
+- ✅ Output as stable HTML snapshot
+
+### Layout Fidelity
+
+- ✅ List reconstruction (`numId`, `ilvl`, `lvlText`)
+- ✅ Table v1 (`tblGrid/tcW`, merge, border, spacing)
+- ✅ Floating anchors v1 (`wp:anchor` metadata)
+- ⏳ Anchor collision parity (pixel-level wrap)
+
+### Advanced Semantics
+
+- ✅ Footnotes / endnotes / comments
+- ✅ Revision markers (`ins` / `del`) + metadata
+- ✅ Page break semantic markers
+- ✅ DOCX hyperlink relationship + anchor mapping
+
+### Semantic Fallback
+
+- ✅ OMML fallback output
+- ✅ Chart semantic extraction fallback
+- ✅ SmartArt node fallback extraction
+- ⏳ OMML high-fidelity render pipeline (MathML/KaTeX)
+
+### Engineering Quality
+
+- ✅ 50 automated tests (regression + boundary)
+- ✅ Baseline snapshot regression framework
+- ✅ `verify` quality gate (lint/typecheck/test/build/size)
+- ✅ Parse report API for performance tuning
+<!-- GENERATED:FEATURE_CHECKLIST_EN:END -->
 
 ## What's New in v0.1.3
 
@@ -121,15 +154,21 @@ el.addEventListener("docsjs-change", (e) => {
   - footnotes and endnotes (read-only rendering)
   - comments (read-only rendering)
   - revisions insert/delete markers (read-only rendering)
+  - comment range markers and revision metadata attributes
   - page break semantic markers (`w:br type=page`, `lastRenderedPageBreak`)
+  - table width mapping (`tblGrid/gridCol`, `tcW`)
+  - table border model / cell spacing / table-layout mapping
+  - OMML formula fallback rendering and chart/SmartArt semantic fallback
 - Added floating image MVP:
   - anchor position mapping (`wp:anchor`)
   - wrap mode markers (`square`, `tight`, `topAndBottom`, `none`)
+  - anchor layout metadata (`relativeFrom`, `behindDoc`, `allowOverlap`, `layoutInCell`, `relativeHeight`, `dist*`)
 - Added fidelity tooling:
   - semantic stats collector
   - fidelity score calculator
   - baseline regression framework (config-driven)
   - visual regression workflow scaffold (Playwright + diff artifacts)
+  - golden corpus benchmark + trend report workflow (`fidelity-benchmark.yml`)
 - Added engineering quality gates:
   - ESLint + strict verify pipeline (`lint`, `typecheck`, `test`, `build`, `sizecheck`)
   - CI workflow for mandatory quality checks
@@ -146,8 +185,16 @@ npm install
 npm run typecheck
 npm run test
 npm run build
+npm run benchmark:fidelity
 ```
 
+## Engineering Modes
+
+- Spec and conventions: [ENGINEERING_MODES.md](./ENGINEERING_MODES.md)
+- Parse API now supports:
+  - `parseDocxToHtmlSnapshot(file)`
+  - `parseDocxToHtmlSnapshotWithReport(file)`
+
 ## Demos
 
 ### React demo
@@ -184,6 +231,15 @@ Workflow: `.github/workflows/publish.yml`
 - Trigger: push tag `v*.*.*`
 - Steps: `npm ci` -> `npm run typecheck` -> `npm run build` -> `npm publish --provenance`
 
+### GitHub Packages (repo sidebar "Packages")
+
+Workflow: `.github/workflows/publish-github-packages.yml`
+
+- Trigger: push tag `v*.*.*` or manual run
+- Target registry: `https://npm.pkg.github.com`
+- Package name in GitHub Packages: `@fanly/docsjs`
+- Note: GitHub sidebar "Packages" only shows packages published to GitHub Packages, not npmjs
+
 ## Roadmap
 
 See [ROADMAP.md](./ROADMAP.md) for prioritized execution plan (P0/P1/P2) and acceptance criteria.

package/README.zh-CN.md

@@ -3,8 +3,19 @@
 面向 Web 的 Render-first Word 高保真导入组件。  
 目标是在粘贴或上传 `.docx` 时，尽可能无损保留 Word/WPS/Google Docs 的结构和版式。
 
+[![npm version](https://img.shields.io/npm/v/@coding01/docsjs)](https://www.npmjs.com/package/@coding01/docsjs)
+[![npm downloads](https://img.shields.io/npm/dm/@coding01/docsjs)](https://www.npmjs.com/package/@coding01/docsjs)
+[![CI](https://github.com/fanly/docsjs/actions/workflows/ci.yml/badge.svg)](https://github.com/fanly/docsjs/actions/workflows/ci.yml)
+[![Pages](https://github.com/fanly/docsjs/actions/workflows/pages.yml/badge.svg)](https://github.com/fanly/docsjs/actions/workflows/pages.yml)
+
 [English README](./README.md)
 
+## GitHub Pages
+
+- 产品单页: [https://docsjs.coding01.cn/](https://docsjs.coding01.cn/)
+- 页面源码: `docs/index.html`
+- 自动部署: `.github/workflows/pages.yml`
+
 ## 核心能力
 
 - Web Component 内核：`docs-word-editor`
@@ -86,27 +97,49 @@ document.body.appendChild(el);
 
 ## 功能清单
 
+<!-- GENERATED:FEATURE_CHECKLIST_ZH:START -->
+### 核心
+
 - ✅ Web Component 内核（`docs-word-editor`）
-- ✅ React 适配（`@coding01/docsjs/react`）
-- ✅ Vue 适配（`@coding01/docsjs/vue`）
-- ✅ 粘贴导入（`text/html`、`text/plain`）
-- ✅ 剪贴板不稳定图片源替换（`file:/blob:/cid:/mhtml:` -> data URL）
-- ✅ `.docx` 上传解析
-- ✅ 段落基础语义（对齐、标题映射、换行）
-- ✅ Run 基础样式（粗斜体、下划线、删除线、颜色、高亮、上下标）
-- ✅ 列表基础恢复（`numId` + `ilvl` + `lvlText`）
-- ✅ 表格基础结构（`table/tr/td`）
-- ✅ 图片关系映射（`rId -> media`）
-- ✅ 页面几何映射（页高、页边距、版心宽）
-- ✅ 运行时渲染修正（`mso-*` 兼容、分页 spacer、空段落修正）
-- ✅ 事件与公共 API
-- ✅ React/Vue 可运行示例
-- ✅ npm OIDC 自动发布流水线
-- ⏳ 浮动锚点对象（`wp:anchor`）完整还原
-- ⏳ 合并单元格/嵌套表格完整还原
-- ⏳ 批注/脚注/修订等高级语义
-- ⏳ OMML/图表/SmartArt
-- ⏳ 自动化保真评分体系
+- ✅ React + Vue 适配层
+- ✅ 事件体系与命令式公开 API
+- ✅ 严格模式唯一解析策略
+
+### 导入链路
+
+- ✅ 剪贴板导入（`text/html`、`text/plain`）
+- ✅ `.docx` 上传与关系媒体映射
+- ✅ 不稳定图片 URI 修复（`file:/blob:/cid:`）
+- ✅ 输出稳定 HTML Snapshot
+
+### 版式保真
+
+- ✅ 列表结构恢复（`numId`、`ilvl`、`lvlText`）
+- ✅ 表格 v1（`tblGrid/tcW`、合并、边框、间距）
+- ✅ 浮动锚点 v1（`wp:anchor` 元数据）
+- ⏳ 锚点碰撞一致性（像素级绕排）
+
+### 高级语义
+
+- ✅ 脚注/尾注/批注
+- ✅ 修订标记（`ins`/`del`）与元数据
+- ✅ 分页语义标记
+- ✅ DOCX 超链接关系与锚点映射
+
+### 语义降级
+
+- ✅ OMML 语义降级输出
+- ✅ 图表语义提取降级
+- ✅ SmartArt 节点降级提取
+- ⏳ OMML 高保真渲染链（MathML/KaTeX）
+
+### 工程质量
+
+- ✅ 50 条自动化测试（回归 + 边界）
+- ✅ 基准快照回归框架
+- ✅ `verify` 质量门禁（lint/typecheck/test/build/size）
+- ✅ 解析报告 API（性能调优）
+<!-- GENERATED:FEATURE_CHECKLIST_ZH:END -->
 
 ## v0.1.3 更新内容
 
@@ -116,15 +149,21 @@ document.body.appendChild(el);
   - 脚注与尾注（只读渲染）
   - 批注（只读渲染）
   - 修订新增/删除标记（只读渲染）
+  - 批注区间标记与修订元数据属性
   - 分页语义标记（`w:br type=page`、`lastRenderedPageBreak`）
+  - 表格宽度映射（`tblGrid/gridCol`、`tcW`）
+  - 表格边框模型/单元格间距/布局类型映射
+  - OMML 公式降级渲染、图表/SmartArt 语义降级渲染
 - 浮动图片 MVP：
   - 锚点定位（`wp:anchor`）
   - 绕排模式标记（`square`、`tight`、`topAndBottom`、`none`）
+  - 锚点布局元数据（`relativeFrom`、`behindDoc`、`allowOverlap`、`layoutInCell`、`relativeHeight`、`dist*`）
 - 保真工具链增强：
   - 语义统计器
   - 保真评分器
   - 配置驱动的基准回归测试框架
   - 视觉回归工作流骨架（Playwright + diff artifacts）
+  - golden corpus 基准评分 + 趋势报告工作流（`fidelity-benchmark.yml`）
 - 工程质量门增强：
   - ESLint + 严格 `verify`（`lint/typecheck/test/build/sizecheck`）
   - CI 必过质量门
@@ -141,8 +180,16 @@ npm install
 npm run typecheck
 npm run test
 npm run build
+npm run benchmark:fidelity
 ```
 
+## 工程模式
+
+- 规则说明: [ENGINEERING_MODES.md](./ENGINEERING_MODES.md)
+- 解析 API 支持:
+  - `parseDocxToHtmlSnapshot(file)`
+  - `parseDocxToHtmlSnapshotWithReport(file)`
+
 ## 演示
 
 ### React demo
@@ -165,6 +212,13 @@ npm run dev
 
 执行优先级与验收标准见 [ROADMAP.md](./ROADMAP.md)。
 
+## 发布与关联
+
+- npmjs 发布工作流：`.github/workflows/publish.yml`
+- GitHub Packages 发布工作流：`.github/workflows/publish-github-packages.yml`
+- GitHub 侧栏 `Packages` 只显示发布到 GitHub Packages 的包，不显示 npmjs 包
+- 当前 GitHub Packages 包名：`@fanly/docsjs`
+
 ## 安全说明
 
 - 默认策略是保真优先，不主动清洗 Word 内联样式。