feat: convert md→docx 支援 LaTeX math → 原生 OMath(downstream: bestOCR ocr-to)

[kiki830621]

Problem

macdoc convert --to docx file.md 對 markdown 內的 LaTeX math($...$ / $$...$$)是純文字直通——docx 內公式以字面 LaTeX 呈現(實測 v0.5.0:\beta 進 document.xml 為文字 run,無 <m:oMath> 元素)。

Expected

md→docx 路徑支援 $...$ / $$...$$ → Word 原生 OMath 轉換(可為 opt-in flag,如 --math omath)。

Context

• 下游 use case:PsychQuant/bestOCR 的 /bestocr:ocr-to skill(OCR → docx)。目前該 skill 對 math 密集文件走 pandoc(已驗證 $...$→<m:oMath> 可行)作為過渡;macdoc native 支援落地後可收斂回單一轉檔器——追蹤 ref:feat: ocr-to 輸出 docx 的 LaTeX → OMath 公式升級(sister concern from #1) bestOCR#3。
• 受益者不限 bestOCR:任何 md→docx 的學術/數學內容轉檔。

參考

• 轉換目標為 OMML(<m:oMath>);pandoc 的 texmath 是既有實作參考。

---

Current Status

Phase: closed
Last updated: 2026-09-01 by idd-close
Dashboard: For Reviewer / Collaborator

Key Decisions

• Markdown → DOCX 維持向後相容的 literal 預設；原生 Word math 只由 --math omath 選擇性啟用。
• v1 使用原始 CommonMark AST/source ranges 與保守 dollar delimiter scanner；unsupported／malformed formula 以具 UTF-8 source location 的公開錯誤 fail-loud。
• inline／display 分別輸出有效的 m:oMath／m:oMathPara carrier；所有 token 必須恰有一個允許的 consumer。
• 全部公式掃描與解析在任何目的檔寫入前完成；失敗不建立或取代目的檔。

Scope Changes

• source eligibility 覆蓋 code、HTML、autolink、link/reference/image destination、reference metadata、formatting boundary 與 CommonMark block/container。
• multiline link/image fallback 以 enclosing paragraph、單調 cursor 與 KMP 維持 bounded-linear。
• 同行與跨行 display closing 必須是原始 AST 明確認定的可見 Text；reference continuation Target="$$" 維持 byte-exact。
• 乾淨套件基線的 42 個既有失敗由 bug: restore a green md-to-word-swift package test baseline #155 追蹤，不在本分支擴張處理。

Blocking

• 無。Final verify：0 blocking、0 follow-up。
• 模型多樣性限制：本環境無 Claude-family reviewer；已使用 5 個獨立 Codex agent lens 與 Codex CLI gpt-5.4 初審／delta 複審並揭露此限制。

Commits

• 5119c36 — visible OMath closing、reference metadata、same-line opaque boundary 與 multiline recovery 線性化。
• c42f343 — CommonMark UTF-8 source column 對齊與 library／compiled CLI regression。
• Verified snapshot：idd-141-verified。

Verification

• PR #154 full report
• Focused package 65/65；compiled CLI 17/17。
• Full nested package 154 tests，僅 bug: restore a green md-to-word-swift package test baseline #155 已記錄的 42 個 baseline failures。
• Root full：31 XCTest（4 skips）＋43 Swift Testing，0 failures（bug: clean clone baseline regressed through ignored word-to-md-swift path dependency #164 僅暫時 overlay 測試，測後 abort）。
• Spectra strict、CRLF-aware diff gate、Analyze (python)、CodeQL 均 PASS。
• PR feat: convert Markdown math to native Word OMath #154 為 MERGEABLE/CLEAN，closingIssuesReferences 為空；尚未合併。

Pull Request

• feat: convert Markdown math to native Word OMath #154 — awaiting human merge; verify 不會自動合併或關閉 issue。

[kiki830621]

Diagnosis

Type

feature

Root Cause / Analysis

目前 macdoc convert --to docx 的 Markdown 路由直接呼叫 MarkdownToWordConverter。轉換器以 swift-markdown 建 AST，再由 MarkdownWordBuilder.appendInline 把 Text、Emphasis、Strong、InlineCode 等節點轉成 Word run；它沒有公式 delimiter 掃描或 math 節點分支。因此 $...$／$$...$$ 會留在一般 Text 裡，最後成為字面 <w:t>，不會產生 <m:oMath>。

這不是 OOXML emitter 缺口：本 repo 已有 OOXMLSwift.MathComponent／toOMML()，也已有獨立且已發版的 PsychQuant/latex-math-swift v0.2.0；其 LaTeXMathParser.parse(_:) 會把既定 LaTeX 子集轉成 [MathComponent]。缺的是 Markdown math delimiter → parser → Word OMML carrier 的整合層與對外選項契約。

Issue 無附件；上述判斷來自：

• Sources/MacDocCLI/MacDoc+Convert.swift：md→docx 直接呼叫 MarkdownToWordConverter
• packages/md-to-word-swift/Sources/MDToWord/MarkdownToWordConverter.swift：inline switch 無 math 分支
• packages/latex-math-swift v0.2.0：已有 LaTeX→MathComponent parser
• openspec/specs/latex-math-parsing/spec.md：已凍結 parser 支援範圍與 fail-loud 行為

Impact

• 影響的檔案／模組：
  • packages/md-to-word-swift 的公開轉換選項、Markdown 掃描與 OMML 注入
  • packages/md-to-word-swift/Package.swift 與解析後依賴鎖定
  • Sources/MacDocCLI/MacDoc+Convert.swift 的 --math CLI surface
  • converter 與 compiled CLI 的單元／整合測試
  • CONVERSIONS.md／README 與新 Spectra capability
• 影響的使用者流程：所有 md→docx 學術／數學內容；下游 bestOCR 可在 native 路徑成熟後移除 pandoc 過渡。

Strategy

• 以 Spectra 凍結一個 md→docx math capability，先決定 delimiter、預設模式、unsupported formula 與 inline/display carrier 語意。
• 在 MDToWord 新增公開且向後相容的 math mode；建議預設維持 literal，opt-in .omath，CLI 對應 --math literal|omath。
• 新增能辨識 escaped dollar、inline code、fenced code 與 $...$／$$...$$ 邊界的 Markdown math scanner；不得把 code 內的 dollar 當公式。
• .omath 模式呼叫既有 LaTeXMathParser，inline 產生 <m:oMath>，display 產生 <m:oMathPara><m:oMath>…；不在 macdoc 另寫第二套 LaTeX parser。
• 建議 unsupported／malformed LaTeX 在 opt-in 模式 fail-loud，錯誤需含來源位置但不得輸出部分損壞的 docx；literal 模式維持現況。
• 補 parser integration、mixed text+inline math、display math、escape/code exclusion、unsupported syntax、CLI flag、解壓 document.xml 與輸出原子性的測試。
• 文件明列 latex-math-swift 的子集界線；「完整 TeX」不得誤列為已支援。

Conflict Class

C_shared_module_coord

會同時改到共享的 packages/md-to-word-swift、root Package.swift／Package.resolved 與 MacDocCLI convert route；這些實體資源也會與 #20、#72、#148 等 root converter 工作重疊，必須序列化協調。

Complexity

Spectra

• Layer 2：新增 MDToWord 公開選項與 CLI flag，屬 future callers 會依賴的 published behavior。
• Layer 3：要協調既有 latex-math-parsing、OOXML math carrier 與 e2e conversion route；預設／錯誤／delimiter 規則有長期相容性影響。
• Hard-gate: triggered — 單一概念預估跨 MarkdownToWordConverter.swift、新 scanner、兩個 package manifest／resolved、CLI、兩層測試與文件，且 converter 是 root CLI 的共享抽象。

Risks

• 直接以 regex 掃 $ 會誤判 escaped dollar、code span／fence 與跨 inline-style 邊界。
• inline／display OMML carrier 不同；位置或 wrapper 錯誤會產生 Word 可開啟但版面錯誤的文件。
• latex-math-swift 明確只支援子集；若 silent fallback，使用者可能在不知情下得到字面公式或混合格式。
• 新 dependency 版本需與 ooxml-swift 的 MathComponent ABI／版本約束一致。
• 若輸出在公式解析完之前開始寫入，單一錯誤可能留下部分 docx；需先完整建模再原子寫入。

Residue

Issue 的長期目的包含「所有學術／數學 Markdown 都可由 native macdoc 處理」，但 v1 可 operationalize 的範圍只能是 latex-math-swift 已凍結的 LaTeX 子集。完整 TeX／Pandoc texmath 等價性屬未來 horizon，需獨立擴充 parser 規格，不應在本 issue 靜默承諾。

Vagueness Pre-check

• V1: 3 — 目標路由、delimiter 與 OMML target 清楚，但預設模式與 unsupported policy 尚未拍板。
• V4: 4 — 有 <m:oMath> 可驗收，卻未定義 code exclusion、inline/display wrapper、錯誤與原子輸出條件。
• Triggered: yes (max=4)
• User choice: unattended-auto proceed（idd-all 已取得全案授權）
• Effect: 採向後相容的 literal default + opt-in fail-loud 作為安全工作假設；Spectra discuss/proposal 仍須把它寫成明確決策。

Layer V Deferred Record

• Reason: unattended-auto-Step-3.4-layerV-deferred
• V1: 3 — 功能目標清楚，預設模式仍需正式定案
• V4: 4 — 驗收需補齊 code exclusion、wrapper、錯誤與原子性
• Catch-up: /idd-clarify 141 — 人回場後可重走 clarify，或確認上述安全預設後 dismiss

Sister Concerns Filed (mid-diagnose)

• 無新 sister issue。bestOCR 的收斂需求已由既有 PsychQuant/bestOCR 追蹤；LaTeX parser 子集擴充已有獨立 package／規格邊界。

[kiki830621]

📊 For Reviewer / Collaborator

現在：#141 已在 frozen c42f343 完成 IDD verify；PR #154 為 MERGEABLE/CLEAN，Analyze (python) 與 CodeQL 均通過，verified snapshot 為 idd-141-verified。
Blocking：無。Final ensemble 為 0 blocking、0 follow-up；#155 的 42 個套件 baseline failures 屬既有獨立問題。
你該做什麼：審閱並由人決定是否合併 PR #154。Verify 不會自動合併或關閉 issue。

last-updated by idd-verify at verified, 2026-08-31

[kiki830621]

Implementation Plan

• 建立 markdown-omath-conversion Spectra change，凍結 literal 預設、保守 delimiter、OMath carrier、錯誤與原子輸出契約。
• 在 MDToWord 新增公開 MarkdownMathMode、具來源位置的公開錯誤、保守 scanner 與 latex-math-swift 整合。
• 讓 inline／display 公式分別輸出原生 <m:oMath>／<m:oMathPara>，並保留 code、link、image、frontmatter 與 placeholder 邊界。
• 在編譯後 CLI 加入只限 Markdown → DOCX 的 --math literal|omath，失敗時不取代既有目的檔。
• 更新 README、CONVERSIONS 與依賴鎖定，明載 parser 子集與非完整 TeX／Pandoc parity 邊界。
• 完成 RED→GREEN、公開 API、完整套件基線、根目錄回歸與 Spectra 驗證。

Extra Requirements

• TDD：所有程式行為先有可觀察紅燈，再以最小實作修到綠燈。
• Baseline qualification：md-to-word-swift 的 42 個既有 E2E／RoundTrip 失敗不得增加；所有新增與直接受影響測試必須通過。

[kiki830621]

Implementation Complete

Checklist (synced from Spectra tasks)

• 建立並驗證 markdown-omath-conversion Spectra change → d79e6a5。
• 新增公開 literal／OMath mode、保守 scanner、來源位置錯誤與 latex-math-swift 整合 → d79e6a5。
• 輸出 inline <m:oMath> 與 display <m:oMathPara>，涵蓋 code／link／image／frontmatter／placeholder 邊界 → d79e6a5。
• 加入只限 Markdown → DOCX 的編譯後 CLI --math literal|omath 與目的檔保護 → d79e6a5。
• 更新 README、CONVERSIONS 與依賴鎖定，明載 parser 子集邊界 → d79e6a5。
• 完成 RED→GREEN、公開 API、完整回歸、依賴與 Spectra 驗證 → d79e6a5。

Changes

• d79e6a5 — native Markdown OMath conversion, route-scoped CLI surface, tests, specs, and documentation.
• PR: feat: convert Markdown math to native Word OMath #154

Files Changed

17 files changed, 1,875 insertions, 41 deletions.

Verification

• Focused MDToWord: 30/30 passed.
• Compiled CLI route: 7/7 passed.
• Full MDToWord: 114 tests; exactly the clean baseline's 42 pre-existing failures, with no new failures.
• Root: 19 XCTest (3 skipped) + 33 Swift Testing, 0 failures.
• Public non-@testable type-check, dependency resolution, diff hygiene, Spectra analyze/validate passed.

Scope Compliance

改動只涵蓋 #141 的 Markdown → DOCX math capability、測試、文件與規格；沒有在此分支修復既有 round-trip baseline，也沒有觸碰其他 converter 路由的實作。

Sister Bugs Filed (mid-impl, v2.44.0+)

• bug: restore a green md-to-word-swift package test baseline #155 — md-to-word-swift 乾淨基線既有 42 個 E2E／RoundTrip 失敗，獨立追蹤。

Next: verification pending

PR #154 將進入獨立多面向 IDD 驗證；在 PASS 前不視為可合併。

[kiki830621]

Verify（via PR #154）

Result: FAIL — R2 found three scanner blockers (multiline destination corruption, CommonMark block-boundary rejection, and non-linear marker allocation).

Full report: #154 (comment)

[kiki830621]

Verify R3（via PR #154）

Result: FAIL — frozen 68c7403b 尚有四組直接 #141 blockers：multiline display跨CommonMark block/container、destination/reference placeholder汙染、HTML boundary/token消耗缺口、formatting-node契約漂移。

Full report: #154 (comment)

R2 的 marker O(N²) blocker已關閉；普通multiline link與既有AST display案例亦已改善。修正後需以新SHA進R4驗證；本輪不標verified、不合併、不關閉issue。