feat: 新增 word-builder-swift — Swift fluent API 直接寫 .docx（類 docx.js）

[kiki830621]

Problem

Original text（來自對話 2026-04-06）:
「我其實想要做的就是也能做到 nodejs 那種寫 word 的程式而已」
「我其實今天看到有人用 js 結果做出很漂亮的 word，我很驚訝」
「好，所以我要用 word-builder-swift 吧」
— Source: 2026-04-06 設計討論對話

使用者希望 macdoc 生態中擁有類似 Node.js docx.js 的能力 — 用程式碼直接建構 .docx 檔案，取代手動操作 Word 或透過 che-word-mcp 的互動式 tool calls。

目前 macdoc 的 ooxml-swift 已具備完整的 OOXML writer 能力（DocxWriter + Document/Paragraph/Run/Table/Image model），但僅作為內部 converter 後端（md-to-word, html-to-word, tex-to-docx）使用，沒有對外暴露成「直接可用的 builder API」。

Type

feature

Expected

使用者可以在 Swift code 裡這樣寫：

import WordBuilderSwift

let doc = Document()
    .heading(1, "Q1 季報")
    .paragraph { p in
        p.text("營收成長 ")
        p.text("15%", bold: true)
    }
try doc.write(to: URL(fileURLWithPath: "report.docx"))

Actual

目前若要用 Swift 寫 .docx，必須直接 import OOXMLSwift 並手動建構 model：

import OOXMLSwift

var doc = WordDocument()
var props = ParagraphProperties()
props.style = "Heading1"
doc.appendParagraph(Paragraph(text: "Q1 季報", properties: props))

let runs: [Run] = [
    Run(text: "營收成長 "),
    Run(text: "15%", properties: RunProperties(bold: true))
]
doc.appendParagraph(Paragraph(runs: runs))
try DocxWriter.write(doc, to: url)

需要手動建 RunProperties() / ParagraphProperties()、記住 style 名稱字串（"Heading1"）、沒有 fluent chaining，學習曲線較高。

Impact

Positive:

• 降低「用 Swift 程式化產生 .docx」的門檻，對齊 docx.js 的開發者體驗
• 為 macdoc 補上一個新的 source format：不是文件格式，而是「Swift code 作為來源」
• 可作為 md-to-word / html-to-word 等 converter 內部的共用 builder 層，未來可重構集中化

Risks / Open Questions:

• 需要先用 ooxml-swift 現有 API 寫幾份真實範例，才知道 wrapper 該長什麼樣（避免先寫抽象、後發現不合身）
• 可能不需要新 package，僅寫 USAGE.md + 範例就足夠（待驗證）
• 命名是否沿用 *-mac 街道命名原則（e.g., word-builder-mac）

Exploration Summary

已探勘 ooxml-swift 和 md-to-word-swift 現況：

檢查項	狀態
DocxWriter.write(_:to:) public API	✅ 已存在
WordDocument / Paragraph / Run / Table / Image / Style model	✅ 完整
ParagraphProperties / RunProperties（bold/italic/color/font/alignment...）	✅ 完整
document.appendParagraph(_:)	✅ 存在
對外 fluent builder API	❌ 缺

預估 wrapper 厚度：~200-400 行 Swift（薄層糖衣）

相關檔案：

• packages/ooxml-swift/Sources/OOXMLSwift/IO/DocxWriter.swift (534 行，寫入入口)
• packages/ooxml-swift/Sources/OOXMLSwift/Models/Document.swift (1997 行)
• packages/ooxml-swift/Sources/OOXMLSwift/Models/Paragraph.swift (322 行)
• packages/ooxml-swift/Sources/OOXMLSwift/Models/Run.swift (206 行)
• packages/md-to-word-swift/Sources/MDToWord/MarkdownASTWalker.swift (使用範例，L90 / L104 / L124)
• packages/md-to-word-swift/Sources/MDToWord/MarkdownToWordConverter.swift (L33 呼叫 DocxWriter.write)

Proposed Approaches

選項	做法	成本
A. 零 package	寫 USAGE.md + 3-5 個真實範例到 ooxml-swift README	0
B. 薄 wrapper	新 package word-builder-swift，只加 fluent builder + helper	~300 行
C. 厚 wrapper	B + 重構 md-to-word / html-to-word 改用 builder	~800 行 + 改現有 converter

建議路徑：先走 A 驗證真實使用情境，做 3-5 份「漂亮的 .docx」出來，用過幾次再決定要不要做 B。避免先寫抽象、後發現不合身。

---

Current Status

Phase: closed
Last updated: 2026-04-18 by idd-close

Key Decisions

• Scope 升級為「1:1 mirror of npm docx (dolanmiu/docx@9.6.1)」而非薄糖衣 wrapper（原 issue Option B → C+ 變體）
• reference/docx-js/ 已 clone（MIT, shallow）作為 API 對應 single source of truth
• 新 package word-builder-swift 需獨立 repo（與 common-converter-swift / word-to-md-swift 同規格，.package(url:) 依賴）
• 交付分 3 phases：P1 core API + Packer (~500 行) / P2 styling + layout (~400 行) / P3 advanced (~300 行)
• ooxml-swift 需補 DocxWriter.writeData(_:) throws -> Data（對應 docx.js Packer.toBuffer）
• Section 模型差異（docx.js array vs ooxml-swift flat）→ word-builder-swift 對外暴露 sections array，內部扁平化
• Phase 1 shipped 2026-04-18: 46/46 tasks, 24+3 tests passing, zero code duplication verified

Scope Changes

• 從「3 選 1」（A 零 package / B 薄 wrapper / C 厚 wrapper）→ 選定 B 的加強版（scope 對齊整個 docx.js public API surface）
• ooxml-swift DocxWriter.writeData API 已新增 + released as v0.7.0
• md-to-word / html-to-word / tex-to-docx 不重構（維持用 ooxml-swift 內部 model）

Blocking

• (none) — Phase 1 complete, Phase 2/3 deferred as scoped in diagnosis

Commits

• ooxml-swift@4cf39a2 feat: DocxWriter.writeData for in-memory .docx output → released v0.7.0
• word-builder-swift@b3c8862 feat: Phase 1 — 1:1 Swift mirror of docx.js 9.6.x → released v0.9.0
• macdoc Package.swift + CLAUDE.md wiring — pending commit on next sync to main

[kiki830621]

Diagnosis

Type

feature

Analysis — 需求解讀

使用者策略（2026-04-18 對話）：

「我覺得要能夠跟 npm 的 word 能夠完全對應，可以把那個 package 下載到 references 裡面」

將 feature 的 scope 從「薄糖衣 wrapper」升級為「system-wide 1:1 mirror of npm docx (dolanmiu/docx@9.6.1)」：

• reference/docx-js/ 作為 API 對應的 single source of truth（已 clone，見下方 Exploration）
• word-builder-swift 的 public API shape 要能讓「會寫 docx.js 的人幾乎零學習成本直接翻譯到 Swift」
• 命名、options struct 結構、builder chain 方式盡量對齊（Swift 慣例允許的例外另列）

Exploration — 現況盤點

已 clone: reference/docx-js/ (dolanmiu/docx@9.6.1, MIT)

docx.js 的 top-level public API surface（從 src/file/index.ts + src/index.ts 掃出）：

類別	docx.js	ooxml-swift 既有對應	狀態
入口	Document (aka File)	WordDocument	✅ 可 alias
段落	Paragraph / IParagraphOptions	Paragraph / ParagraphProperties	✅
Run	Run / TextRun / IRunOptions	Run / RunProperties	✅（TextRun 是糖衣）
表格	Table / TableRow / TableCell	Table / TableRow / TableCell	✅
樣式	Styles / StyleLevel	Style / StyleType	✅
編號	Numbering / Level / LevelFormat	Numbering / Level / NumberFormat	✅
Header/Footer	Header / Footer	Header / Footer	✅
超連結	Hyperlink / PageReference	Hyperlink	🟡 PageReference 缺
書籤	Bookmark (inline API)	Bookmark / ParagraphBookmark	✅
註腳	Footnote	Footnote	✅
圖片	ImageRun / Media	ImageReference / Drawing	🟡 沒有 ImageRun 的 paragraph child 糖衣
核心屬性	CoreProperties / IPropertiesOptions	DocumentProperties	✅
章節	sections: [{ children: [...] }]	SectionProperties + Body.children	🟡 section 概念模型不同（下方說明）
分頁/分欄	PageBreak	PageBreak	✅
符號/CheckBox	SymbolRun / CheckBox / CheckBoxUtil	❌	❌ 需新增
文字方塊	Textbox	❌	❌ 需新增
字型	FontWrapper / createFont	❌（只靠 RunProperties.fontName）	🟡
追蹤修訂	RunPropertiesChange / track-revision	Revision	✅
TOC	TableOfContents	TableOfContents	✅
匯出	Packer.toBuffer / .toBlob / .toBase64String	DocxWriter.write(_:to: URL)	🟡 沒有 buffer/Data output

Section 模型差異（關鍵設計點）

• docx.js：Document({ sections: [{ properties, headers, footers, children }, ...] }) — section 是一等公民，每個 section 有自己的 headers/footers/page setup
• ooxml-swift：WordDocument.body.children: [BodyChild] + SectionProperties 用 paragraph break 標記 — 扁平模型，不是 section array
• 設計決策：word-builder-swift 要對外暴露 Sections 陣列（1:1 API），內部轉換成 ooxml-swift 的扁平結構

Packer 缺口（關鍵 gap）

• docx.js：Packer.toBuffer(doc) / .toBlob(doc) / .toBase64String(doc) / .toStream(doc) — 不落地，直接 in-memory buffer
• ooxml-swift：DocxWriter.write(_:to: URL) 只能寫檔，沒有 Data/Stream output
• 修復：ooxml-swift 需補 DocxWriter.writeData(_:) throws -> Data（或 Packer wrapper）

Impact

影響的檔案 / 套件：

• 🆕 新 package：packages/word-builder-swift/（Sources/WordBuilderSwift/*）
• 🆕 新 repo：PsychQuant/word-builder-swift（跟 common-converter-swift / word-to-md-swift 同規格，遠端 .package(url:) 依賴）
• ✏️ packages/ooxml-swift/Sources/OOXMLSwift/IO/DocxWriter.swift — 補 writeData(_:) throws -> Data API
• 🆕 (opt-in) macdoc CLI：macdoc convert --to docx file.swift（把 .swift 當 source format，exec 後產出 docx — 需 dynamic loading 機制，可能 push 到後續 issue）
• 📖 reference/docx-js/（已 clone，純參考，不 commit）

不影響：

• ❌ 不重構 md-to-word-swift / html-to-word-swift / tex-to-docx-swift（它們繼續用 ooxml-swift model 內部 API；word-builder-swift 是對外使用者的層）
• ❌ 不影響 che-word-mcp（MCP 也是用 ooxml-swift，非 wrapper 層）

Strategy

分三階段交付（每階段都可獨立 ship，減少 big-bang 風險）：

Phase 1：Core API mirror + Packer equivalent（~500 行）

• 新建 word-builder-swift package（scaffold + README + LICENSE）— shipped in 0.9.0
• ooxml-swift 補 DocxWriter.writeData(_:) throws -> Data — shipped in ooxml-swift v0.7.0
• WordBuilderSwift.Document、Paragraph、TextRun、Table/TableRow/TableCell fluent constructor — shipped; options-struct pattern chosen (no result-builder DSL)
• WordBuilderSwift.Packer — toData() / toFile(url:) / toBase64String() — shipped as uninhabited enum
• Sections 陣列模型 → 扁平 body 的轉換層 — shipped (Phase 1 emits sections[0], multi-section deferred)
• 5 個範例對照 — shipped in examples/01-hello-world.swift … 05-aligned-paragraphs.swift + ExamplesIntegrationTests

Phase 2：Styling + Layout API parity（~400 行）

• HeadingLevel、AlignmentType、UnderlineType enum 對齊 — shipped in 0.9.0; LevelFormat deferred with Numbering (Phase 2)
• [-] Header / Footer / PageNumber fluent API — deferred to Phase 2 (tracked when Phase 2 is started, per non-goals in proposal.md)
• [-] Hyperlink / Bookmark / PageReference 補齊 — deferred to Phase 2
• [-] Numbering / AbstractNumbering fluent builder — deferred to Phase 2
• [-] Styles 全域樣式定義 — deferred to Phase 2

Phase 3：Advanced features（~300 行，optional）

• [-] ImageRun 糖衣（paragraph child）— deferred to Phase 3 (optional)
• [-] CheckBox / SymbolRun — deferred to Phase 3 (needs ooxml-swift model additions)
• [-] Textbox — deferred to Phase 3 (needs ooxml-swift model additions)
• [-] Footnote / Endnote fluent API — deferred to Phase 3
• [-] CoreProperties / CustomProperties builder — deferred to Phase 3

命名慣例決策（spectra-discuss 要定案）：

1. TextRun vs Run：兩個都保留，TextRun(String) 當 convenience（同 docx.js）
2. Options struct：用 Swift struct with defaulted init params，不用 builder DSL（避免兩套 API）
3. readonly TS 屬性 → Swift let（struct immutability 天然對齊）
4. new Paragraph({...}) → Paragraph(...) init（不需 new）
5. Fluent chaining：提供 .add(_:) / .heading(_:_:) sugar method，但不強制
6. 命名空間：import WordBuilderSwift 暴露全部公開類型（對應 import "docx"）

Complexity

SDD-warranted（理由）：

• ✅ 新 package + 新 repo（跨 filesystem + git）
• ✅ 改動跨 3+ 檔案：Document / Paragraph / Run / Table / Packer / Sections 各自 Swift file
• ✅ 需要新共用抽象：Packer 是全新概念，Sections 扁平化轉換層是新設計
• ✅ 設計決策多：命名、options shape、builder 模式、錯誤處理（docx.js throws runtime error，Swift 要 throws 還是 Result？）
• ✅ 影響 upstream ooxml-swift：writeData 新 API
• ✅ Strategy 有 3 phases 共 ~20+ 步，順序依賴（Packer 要先做才能測 examples）

Risks

1. API 永遠追不上 docx.js（9.6.1 → 後續版本）。對策：固定 reference 版本，word-builder-swift 版本號 mirror（例如 word-builder-swift@0.9.6-x）
2. TS options object 語法在 Swift 很尷尬。對策：Phase 1 先做 Document/Paragraph/TextRun/Table 驗證模式，再決定要不要加 result builder sugar
3. Sections 扁平化 bug：docx.js 每個 section 有獨立 headers/footers/page setup，轉成 ooxml-swift 扁平模型時 section break 的 header/footer 關聯容易出錯。對策：Phase 1 只支援「單一 section」，Phase 2 再擴充多 section
4. 維護負擔：兩套 API（ooxml-swift 低階 + word-builder-swift 高階）。對策：ooxml-swift 維持「converter 內部用」定位，word-builder-swift 對外；兩者不混用
5. reference/docx-js/ 的授權：MIT license，在 repo 外做參考沒問題，但不可直接複製程式碼，只對齊 API shape 與命名

Next Steps

依 Complexity = SDD-warranted，下一步走 /spectra-discuss 對齊以下 open questions：

1. word-builder-swift 的版本號策略（mirror docx.js 版號 vs 獨立）
2. 命名慣例最終決策（TextRun 保留？options struct 還是 init params？）
3. Phase 1 scope 的邊界（最小可 ship 的範圍）
4. ooxml-swift.DocxWriter.writeData 是否先開獨立 PR（解 blocker）
5. 單 section vs 多 sections 的交付節奏
6. word-builder-swift repo 放 PsychQuant org 還是其他 org

[kiki830621]

Implementation Complete — word-builder-swift 0.9.0

Release: https://github.com/PsychQuant/word-builder-swift/releases/tag/v0.9.0
Repo: https://github.com/PsychQuant/word-builder-swift
Upstream bump: ooxml-swift → v0.7.0 (adds DocxWriter.writeData(_:) throws -> Data)
Spectra change: openspec/changes/word-builder-swift
Tests: 24 pass in WordBuilderSwift + 3 new in OOXMLSwift (205 total) — all green

Phase 1 shipped

Public API (1:1 mirror of docx.js 9.6.x):

• Document, Section, Paragraph, TextRun, Run
• Table, TableRow, TableCell
• Packer.toData(_:), Packer.toFile(_:url:), Packer.toBase64String(_:)
• HeadingLevel (.heading1 – .heading6)
• AlignmentType (.start / .center / .end / .both)
• WordBuilderError (.emptyDocument, .writerFailed(String))

Five worked examples

Under packages/word-builder-swift/examples/ (translated from docx.js README/demos):

File	Covers
01-hello-world.swift	Minimum doc — one paragraph, one run
02-heading-and-paragraphs.swift	HeadingLevel.HEADING_1 + body paragraphs
03-table-3x3.swift	Table / TableRow / TableCell with 3 rows × 3 cols
04-mixed-formatting.swift	TextRun with bold / italics / color / strike
05-aligned-paragraphs.swift	AlignmentType.CENTER / START / END

Each example maps directly to a docx.js README/demo snippet — a user who knows docx.js can copy the translation line-by-line.

Decisions captured in openspec/changes/word-builder-swift/design.md

1. API mirrors docx.js naming 1:1
2. Options use Swift struct init parameters with defaults (not a result builder DSL)
3. TextRun is a String-overload convenience wrapper over Run
4. Packer is an uninhabited enum (static-method facade over DocxWriter.writeData)
5. OOXMLSwift.DocxWriter gains writeData(_:) — unblocks in-memory packing
6. Phase 1 accepts [Section] but only emits sections[0]
7. Version 0.9.x tracks docx.js 9.6.x (minor number mirrors, patch independent)

Phase 2+ deferred scope

Category	Examples	Blocks on
Multi-section	Multiple <w:sectPr> blocks, per-section headers/footers/page setup	OOXMLSwift flat-body model mapping
Headers / Footers	Header, Footer, page number fields	Phase 1 only supports body
Numbering	AbstractNumbering, Numbering, LevelFormat	Lists with numeric / alphabetic / bullet styles
Hyperlinks	Hyperlink, PageReference	Cross-references
Bookmarks	Bookmark inline API
Footnotes / Endnotes	Footnote, Endnote
Images	ImageRun paragraph child	media handling
CheckBox	CheckBox, CheckBoxUtil, SymbolRun
Textbox	Textbox, VML shape
Table of Contents	TableOfContents fluent builder	already exists in OOXMLSwift but no fluent wrapper
CoreProperties	CoreProperties, CustomProperties	Document metadata
Global styles	Styles, StyleLevel	User-defined style chains
Packer.toStream	Streaming .docx output	low priority — toData sufficient
macdoc convert --to docx file.swift	Dynamic Swift-file compilation	requires runtime compiler

Housekeeping

• reference/docx-js/ stays gitignored (confirmed .gitignore line reference/)
• Zero 5-contiguous-line duplication between packages/word-builder-swift/Sources/ and reference/docx-js/src/ (scanned 577 TS vs 8 Swift files) — only API shape and naming are mirrored, not implementation

macdoc wiring

• Package.swift now depends on word-builder-swift from: "0.9.0"
• Available for future CLI features; Phase 1 adds no user-visible CLI subcommand
• Existing converters (md-to-word, html-to-word, tex-to-docx) continue using OOXMLSwift directly — no refactor, intentional per design (word-builder-swift is author-facing, OOXMLSwift is converter-internal)

Closing this issue. Phase 2 scope will be tracked separately when it's ready to start.

[kiki830621]

Closing Summary

Problem

Swift developers who wanted to generate .docx files programmatically had to hand-build OOXMLSwift.WordDocument values — no fluent builder, no familiar shape for anyone coming from Node.js docx.js. The 2026-04-06 conversation surfaced the ask directly: "其實想要做的就是也能做到 nodejs 那種寫 word 的程式而已".

Root Cause

OOXMLSwift is designed as a low-level model used by converters (md-to-word, html-to-word, tex-to-docx, che-word-mcp) — it was never intended as an author-facing builder. The parallel already existed on the markdown side (markdown-builder spec for MarkdownBuilder in markdown-swift); the docx equivalent was missing.

Solution — Phase 1 (shipped)

Published word-builder-swift 0.9.0, a new Swift package whose public API is a 1:1 mirror of npm docx (dolanmiu/docx) 9.6.x. A docx.js user can translate code line-by-line to Swift using identical class names (Document, Section, Paragraph, TextRun, Run, Table, TableRow, TableCell, Packer, HeadingLevel, AlignmentType) and option shapes.

Key internal additions:

• OOXMLSwift.DocxWriter.writeData(_:) throws -> Data — in-memory .docx output via ZIPFoundation in-memory Archive, released as ooxml-swift v0.7.0
• ZipHelper.zipToData(_:) — refactored zip pipeline; the existing zip(_:to:) now delegates to zipToData + Data.write(to:)
• WordBuilderSwift.DocumentConverter — maps Document → Section → Paragraph / Table → OOXMLSwift.WordDocument
• Packer — uninhabited enum namespace exposing toData / toFile / toBase64String (compile-error on Packer() attempts)
• Five runnable examples under examples/ translated from docx.js README/demos

Deferred to Phase 2/3 (see proposal Non-Goals): headers/footers, numbering, hyperlinks, bookmarks, footnotes, images, checkboxes, textboxes, TOC, core properties, global styles definitions, multi-section rendering. The [Section] array shape is accepted from day one so Phase 2 won't break callers.

Verification

• OOXMLSwift test suite: 205/205 pass (+3 new: DocxWriterWriteDataTests — ZIP magic bytes, byte-equality with write(_:to:), no persistent tempdir residue)
• WordBuilderSwift test suite: 24/24 pass — covers all 11 spec requirements including DocxReader round-trip and Packer.toBase64String decoding symmetry
• macdoc build: swift build clean with new dep (103.47s, zero regressions)
• Spectra change archived: openspec/changes/archive/2026-04-18-word-builder-swift/; 11 requirements promoted to openspec/specs/word-builder-swift/spec.md
• No code duplication: scanned 577 reference/docx-js/src/**/*.ts files vs 8 Sources/WordBuilderSwift/*.swift files → 0 five-contiguous-line matches (only API shape + naming mirrored, implementation independent)
• reference/docx-js/ stays gitignored (entry reference/ in .gitignore)

Changes

ooxml-swift (v0.6.1 → v0.7.0, released):

• 4cf39a2 — feat: DocxWriter.writeData for in-memory .docx output
• Tag: https://github.com/PsychQuant/ooxml-swift/releases/tag/v0.7.0

word-builder-swift (new repo, released at v0.9.0):

• b3c8862 — feat: Phase 1 — 1:1 Swift mirror of docx.js 9.6.x
• Repo: https://github.com/PsychQuant/word-builder-swift
• Tag: https://github.com/PsychQuant/word-builder-swift/releases/tag/v0.9.0

macdoc (wiring — 3-line diff, pending commit on next sync to main):

• Package.swift: +1 line .package(url: ".../word-builder-swift.git", from: "0.9.0")
• CLAUDE.md: +2 lines (Layer 4 architecture + Sub-Repositories table entry)
• Package.resolved auto-updated by SPM

Follow-ups

• Phase 2 (Header/Footer/Numbering/Hyperlink/Bookmark/Styles) and Phase 3 (Image/CheckBox/Textbox/Footnote/CoreProperties) — open new issues when ready to start, reference this one for design context.
• The macdoc wiring diff above is part of the next merge to main (currently on branch refactor/extract-note-packages-78 for issue refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78; both changes are independent and land together on the next consolidation).