@coding01/docsjs 0.1.5 → 0.1.7

package/README.md

@@ -6,9 +6,16 @@ Import Word/WPS/Google Docs content from paste or `.docx` while preserving struc
 [![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`
@@ -74,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`
@@ -95,34 +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`)
-- ✅ Table merge + nested table read-only fidelity (`vMerge/gridSpan`)
-- ✅ Table width mapping (`tblGrid/gridCol`, `tcW`)
-- ✅ 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
-- ✅ Footnotes / endnotes / comments / track changes read-only semantics
-- ✅ Comment range markers (`commentRangeStart/commentRangeEnd`)
-- ✅ Revision metadata markers (`id/author/date`)
-- ✅ Floating anchors (`wp:anchor`) v1 fidelity (position ref / overlap / layer / wrap distance markers)
-- ✅ Word table v1 fidelity (border model / cell spacing / table-layout mapping)
-- ✅ OMML / charts / SmartArt semantic fallback rendering (v1)
-- ✅ Automated fidelity benchmark v1 (golden corpus + CI trend artifacts)
-- ⏳ Floating anchor text-wrap collision fidelity (pixel-level)
-- ⏳ Word table auto layout parity with desktop Word
-- ⏳ OMML high-fidelity renderer (MathML/KaTeX pipeline)
+- ✅ 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
 
@@ -166,6 +188,13 @@ 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

package/README.zh-CN.md

@@ -6,9 +6,16 @@
 [![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`
@@ -90,34 +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`）
-- ✅ 表格合并与嵌套表格只读保真（`vMerge/gridSpan`）
-- ✅ 表格宽度映射（`tblGrid/gridCol`、`tcW`）
-- ✅ 图片关系映射（`rId -> media`）
-- ✅ 页面几何映射（页高、页边距、版心宽）
-- ✅ 运行时渲染修正（`mso-*` 兼容、分页 spacer、空段落修正）
-- ✅ 事件与公共 API
-- ✅ React/Vue 可运行示例
-- ✅ npm OIDC 自动发布流水线
-- ✅ 批注/脚注/修订只读语义支持
-- ✅ 批注区间标记（`commentRangeStart/commentRangeEnd`）
-- ✅ 修订元数据标记（`id/author/date`）
-- ✅ 浮动锚点对象 v1 保真（定位参照/层级/避让距离/重叠策略标记）
-- ✅ Word 表格 v1 保真（边框模型/单元格间距/布局类型映射）
-- ✅ OMML/图表/SmartArt 语义降级渲染（v1）
-- ✅ 自动化保真评分 v1（golden corpus + CI 趋势产物）
-- ⏳ 浮动对象文字绕排碰撞的像素级还原
-- ⏳ Word 表格自动布局与桌面 Word 深度一致
-- ⏳ OMML 高保真渲染（MathML/KaTeX 渲染链）
+- ✅ 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 更新内容
 
@@ -161,6 +183,13 @@ npm run build
 npm run benchmark:fidelity
 ```
 
+## 工程模式
+
+- 规则说明: [ENGINEERING_MODES.md](./ENGINEERING_MODES.md)
+- 解析 API 支持:
+  - `parseDocxToHtmlSnapshot(file)`
+  - `parseDocxToHtmlSnapshotWithReport(file)`
+
 ## 演示
 
 ### React demo