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: needs-fix
Last updated: 2026-08-14 by idd-verify R3
Dashboard: For Reviewer / Collaborator

Key Decisions

• Markdown → DOCX 維持向後相容的 literal 預設；原生 Word math 只由 --math omath 選擇性啟用。
• v1 使用保守 dollar delimiter scanner 與 latex-math-swift v0.2.0 子集，unsupported／malformed formula 以具來源位置的公開錯誤 fail-loud。
• inline／display 分別輸出 m:oMath／m:oMathPara，並在任何目的檔寫入前完成全部掃描與解析。

Scope Changes

• 新增 link label、image alt、frontmatter line offset、CRLF、reference link、placeholder collision、container code、archived namespace 與 logical paragraph 邊界驗收。
• R3 要求把scanner與原始CommonMark AST/source ranges對齊，避免在AST前洗掉block／container／HTML／destination邊界。
• 乾淨套件基線的 42 個既有失敗已獨立立案 bug: restore a green md-to-word-swift package test baseline #155，不在 feat: convert md→docx 支援 LaTeX math → 原生 OMath(downstream: bestOCR ocr-to) #141 分支擴張修復。

Blocking

• R3：multiline display span可跨原始CommonMark block/container，成功轉檔時改變文件結構。
• R3：multiline reference label與angle destination grammar不完整，可把generated placeholder寫進relationship target。
• R3：multiline／quoted HTML boundary未完整排除，可造成隱藏公式失敗或可見placeholder外洩。
• R3：$*x*$等跨formatting-node delimiter與frozen proposal non-goal不一致。

Closed since R2

• Marker allocation O(N²)已以一次預索引與Set lookup關閉。
• 普通multiline inline link／image destination regression已綠，但完整destination grammar仍由R3阻擋。
• transformed AST display validation已加入，但原始跨block span仍須在替換前拒絕。

Commits

• d79e6a5 — native Markdown OMath conversion, CLI surface, specs, tests, and documentation.
• 3365faf — archived namespace、已知 container/reference 邊界與 render-time token lookup remediation.
• 68c7403 — multiline link、AST display validation與linear marker remediation.

Verification

• R3 FAIL report: feat: convert Markdown math to native Word OMath #154 (comment)

Pull Request

• feat: convert Markdown math to native Word OMath #154

[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 已實作 opt-in Markdown → DOCX 原生 OMath；公開 library mode、--math literal|omath、typed errors、測試與文件都在 PR #154。
Blocking：PR #154 尚待獨立多面向 IDD 驗證；乾淨套件基線既有的 42 個 round-trip 失敗已另由 #155 追蹤。
你該做什麼：審閱 PR #154；驗證結果會另行貼在 PR，PASS 前不合併。

last-updated by idd-implement at implemented, 2026-08-14

[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。