Multi-section <w:sectPr> structure collapses to single generic sectPr — headerReference / footerReference lost

[kiki830621]

Problem

ooxml-swift v0.27.0 round-trip on a docx with multiple <w:sectPr> (one per section break, e.g. front-matter / body / title-page) collapses all sections into a single generic sectPr at the end of document.xml. The collapsed sectPr drops:

• <w:headerReference w:type="default|even|first" r:id="..."/> — every section's header invocations
• <w:footerReference w:type="default|even|first|first" r:id="..."/> — every section's footer invocations
• Section-break positions (the section structure is flattened — original break locations gone)
• Section-level page properties (<w:pgSz>, <w:pgMar>, <w:pgNumType>, <w:titlePg/>)

Even when header/footer XML files exist with rich content, none of them are activated because no section references them. Word opens the docx without errors but renders no watermark, no page numbers, no chapter-aware page numbering format (lowerRoman vs decimal).

Discovered while rescuing the NTPU master's thesis (kiki830621/collaboration_guo_analysis#20) immediately after fixing #65 (replaceText) and #66 (header/footer VML).

Type

bug

Evidence

Reproduction: DocxReader.read(_raw.docx) then DocxWriter.write(_, to: out.docx) with no edits in between.

_raw.docx — 3 sections with full structure

Section 1 (front matter, lowerRoman pages):

<w:sectPr w:rsidR="008A36FA" w:rsidRPr="000128A9" w:rsidSect="00F25889">
  <w:headerReference w:type="even"    r:id="rId8"/>
  <w:headerReference w:type="default" r:id="rId9"/>
  <w:footerReference w:type="default" r:id="rId10"/>
  <w:headerReference w:type="first"   r:id="rId11"/>
  <w:footerReference w:type="first"   r:id="rId12"/>
  <w:pgSz w:w="11906" w:h="16838"/>
  <w:pgMar w:top="1440" w:right="1797" w:bottom="1440" w:left="1797"
           w:header="1474" w:footer="397" w:gutter="0"/>
  <w:pgNumType w:fmt="lowerRoman" w:start="1"/>
  <w:cols w:space="425"/>
  <w:docGrid w:type="lines" w:linePitch="381"/>
</w:sectPr>

Section 2 (body, different headers/footers):

<w:sectPr w:rsidR="0020589C" w:rsidRPr="005611B2" w:rsidSect="0089106F">
  <w:headerReference w:type="even"    r:id="rId13"/>
  <w:headerReference w:type="default" r:id="rId14"/>
  <w:footerReference w:type="default" r:id="rId15"/>
  <w:headerReference w:type="first"   r:id="rId16"/>
  <w:footerReference w:type="first"   r:id="rId17"/>
  …same pgSz/pgMar/pgNumType/etc…
</w:sectPr>

Section 3 (cover page, no headers/footers):

<w:sectPr …>
  <w:pgSz w:w="11906" w:h="16838"/>
  …
  <w:titlePg/>
</w:sectPr>

v0.27.0 output — single generic sectPr, no references

Total 228 chars:

<w:sectPr>
  <w:pgSz w:w="12240" w:h="15840"/>
  <w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"
           w:header="720" w:footer="720" w:gutter="0"/>
  <w:cols w:space="720" w:num="1"/>
  <w:docGrid w:linePitch="360"/>
</w:sectPr>

Diff:

• 3 <w:sectPr> → 1
• 5 <w:headerReference> × 2 sections → 0
• 4 <w:footerReference> × 2 sections → 0
• <w:titlePg/> (cover page) → lost
• <w:pgNumType w:fmt="lowerRoman"/> → lost (defaults to decimal)
• Page size: A4 (11906 × 16838) → Letter (12240 × 15840) — likely default fallback because original pgSz dropped
• Page margins: thesis margins (1797/1474/397) → Word defaults (1440/720/720)

document.xml.rels correctly maps rId8..rId17 → header1-6.xml + footer1-4.xml, all files exist in the zip. They are orphaned because the body never invokes them via <w:sectPr>.

Expected

Round-trip preserves:

1. Section break positions (<w:p><w:pPr><w:sectPr>…</w:sectPr></w:pPr></w:p> mid-document and final-paragraph-with-sectPr at end)
2. Each <w:sectPr> byte-equivalent (or at least: all <w:headerReference> / <w:footerReference> / <w:titlePg/> / <w:pgSz> / <w:pgMar> / <w:pgNumType> retained)
3. Multi-section structure → multi-section output

Actual

All sections collapse to one generic sectPr at the end of body. References lost. Page properties reset to Word defaults.

Impact

• P1: silently breaks header/footer activation. Even if header XML files have correct VML (after Header/footer VML <w:pict> not preserved through round-trip — drops to empty paragraph (sister of #62) #66 fix), nothing renders because no section references them.
• Page numbers, watermarks, chapter-aware formatting all lost.
• For NTPU thesis: lowerRoman page numbers in front matter + decimal in body is institutional requirement.
• Cover page (titlePg) gets headers it shouldn't have.

Workaround for thesis #20

Surgical Python sectPr swap: replace v0.27.0's single empty sectPr with _raw section 2's sectPr (string-level inject). Single-section result, but watermark + footer references active. Page-number format distinction (lowerRoman in front matter vs decimal in body) is lost — accepted as P3 cosmetic compromise for thesis-submission deadline.

Reproduction recipe

import OOXMLSwift

// _raw.docx has 3 sectPr in document.xml; v0.27.0 output has 1
let inURL = URL(fileURLWithPath: "/path/to/_raw.docx")
let outURL = URL(fileURLWithPath: "/tmp/out.docx")

var doc = try DocxReader.read(from: inURL)
try DocxWriter.write(doc, to: outURL)

// inspect:
//   unzip -p _raw.docx word/document.xml | grep -c '<w:sectPr'  → 3
//   unzip -p out.docx  word/document.xml | grep -c '<w:sectPr'  → 1
//   unzip -p out.docx  word/document.xml | grep -c '<w:headerReference'  → 0

Long-term fix sketch

DocumentParser (or whoever owns <w:body> parsing) needs to:

1. Capture <w:sectPr> as a typed structure (model class SectionProperties) holding:
   • headerReferences: [HeaderReference] (with type: even|default|first, relId: String)
   • footerReferences: [FooterReference]
   • pageSize: PageSize?
   • pageMargin: PageMargin?
   • pageNumberType: PageNumberType?
   • titlePage: Bool
   • rawXML: String (for byte-equivalent fallback while typed coverage incomplete)
2. Capture both mid-document section breaks (sectPr inside <w:p><w:pPr>) AND final-section sectPr (direct child of <w:body>).
3. Track section break paragraph positions so the writer emits sectPr at the same body position.
4. DocumentWriter re-emits sectPr blocks at captured positions with all header/footer references intact.

If full typed coverage is too large for a single PR, an interim fix is just:

• Capture rawXML for every <w:sectPr> and its enclosing paragraph break verbatim → emit verbatim. No typed access, but byte-equivalent for round-trip safety.

Relationship to #62 / #66

• #62 — VML/wps/wpg in body
• #66 — VML in headers/footers (sister of this issue)
• This issue (#NEW) — section structure / sectPr in document.xml

All three are surfaced during the same NTPU thesis rescue. They're orthogonal but compound: #62 fixes body shapes, #66 fixes header/footer VML, this issue activates header/footer references so they render. All three needed for full thesis fidelity.

Source

Surfaced during /idd-issue invocation while rescuing NTPU thesis (kiki830621/collaboration_guo_analysis#20). Confirmed via Python diff of _raw.docx vs ooxml-swift v0.27.0 round-trip output.

---

Current Status

Phase: implemented
Last updated: 2026-05-05 by idd-implement

Key Decisions

• Phase A landed in commit de83eef — parseSectPr helper + signature cascade (parseBodyChildren / parseBody / top-level caller / recursive sdtContent discard) all in single coordinated commit per plan.
• 5 new Issue67SectPrRoundTripTests all GREEN. Full suite: 883 → 888 ✓, 0 regressions, 1 pre-existing skip preserved.
• rawChildren: [String] field added to SectionProperties for byte-equivalent unknown-children preservation (architectural pattern: Run.rawElements v0.14.0+/[test] Test 25.4 (endnote) missing modifiedParts assertion (asymmetry vs 25.1-25.3) #52).
• Plan committed: only body-level <w:sectPr> (DocxReader:823). Phase B / Phase C deferred per planned scope.
• Implementation Plan posted: Multi-section <w:sectPr> structure collapses to single generic sectPr — headerReference / footerReference lost #67 (comment) (approved via EnterPlanMode/ExitPlanMode 2026-05-05).
• Implementation Complete posted: Multi-section <w:sectPr> structure collapses to single generic sectPr — headerReference / footerReference lost #67 (comment) (with Sister Bugs Filed audit trail).

Scope Changes

• (none — Phase A scope held strictly per plan)

Blocking

• (none — ready for /idd-verify)

Tangential (filed during plan drafting Step 2.5)

• [bug] Phase 7 inline OMath splice emits non-self-closing <w:rFonts ...></w:rFonts> #68 — Phase 7 OMath splice emits non-self-closing <w:rFonts> (344 occurrences in thesis output)
• [bug] settings.xml round-trip loss (~19KB → ~400 bytes) — same skip pattern as #67 #69 — settings.xml round-trip loss (~19KB → ~400 bytes), root cause of thesis CJK font fallback

Commits

• de83eef — fix(sectPr): Phase A — DocxReader parses body-level <w:sectPr> (Multi-section <w:sectPr> structure collapses to single generic sectPr — headerReference / footerReference lost #67)

[kiki830621]

Diagnosis

Type

bug — confirmed reproducible on main (cd00233, post-v0.27.0)

Root Cause / Analysis

Confirmed via fresh probe:

# rescue --refresh-fields-only on _raw.docx (which has 3 sectPrs + headerRef/footerRef)
$ unzip -p _raw.docx word/document.xml | grep -c '<w:sectPr'         # → 3
$ rescue --refresh-fields-only --input _raw.docx --output X.docx
$ unzip -p X.docx word/document.xml | grep -c '<w:sectPr'             # → 1
$ unzip -p X.docx word/document.xml | grep -c '<w:headerReference'    # → 0
$ unzip -p X.docx word/document.xml | grep -c '<w:footerReference'    # → 0

Same loss happens on pure DocxReader+Writer round-trip (no rescue involved).

Root cause located at two call sites in DocxReader.swift that silently skip <w:sectPr>:

// Line 823 — body-level sectPr (final section)
case "sectPr":
    // <w:sectPr> as a direct child of <w:body> is the document-wide
    // section properties block. It's parsed separately into
    // `WordDocument.sectionProperties` (not into BodyChild) — skip
    continue                       // ← skipped, but NEVER actually parsed elsewhere

// Line 1607 — container body (header/footer/footnote/endnote) sectPr
case "sectPr":
    continue                       // ← same: silently dropped

The comment claims sectPr is "parsed separately into WordDocument.sectionProperties" but grep -rn parseSectPr returns no results. There is no parser. The model field starts at sectionProperties = SectionProperties() (defaults) and is never populated during read.

DocxWriter.swift:685 then emits document.sectionProperties.toXML() — which produces a default-init block (<w:pgSz w:w="12240" w:h="15840"/> Letter page, no headerReferences, no footerReferences). That matches exactly what we see in the broken output:

<w:sectPr>
  <w:pgSz w:w="12240" w:h="15840"/>            <!-- US Letter, not original A4 -->
  <w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"
           w:header="720" w:footer="720" w:gutter="0"/>
  <w:cols w:space="720" w:num="1"/>
  <w:docGrid w:linePitch="360"/>
</w:sectPr>

Mid-document section breaks (<w:p><w:pPr><w:sectPr>…</w:sectPr></w:pPr></w:p>) are handled differently — Paragraph.properties.sectionBreak: SectionBreakType? captures only the type attribute (continuous / nextPage / etc). Writer at Paragraph.swift:402 emits <w:sectPr><w:type w:val="next"/></w:sectPr> — losing <w:headerReference>, <w:footerReference>, <w:pgSz>, <w:pgMar> of mid-document section breaks.

Impact

• Multi-section docx (front-matter / body / cover-page distinction common in academic theses, technical docs, books): all sections collapse to one default Letter section.
• Header/footer activation lost: even when header*.xml contains valid VML watermark + page-number wrappers (already preserved by #52 rawElements), Word doesn't render them because no <w:sectPr> references them.
• Page properties lost: A4 → Letter, custom margins → defaults, lowerRoman/decimal page-number distinction → defaults.

Strategy

Two-phase fix:

Phase A: Body-level <w:sectPr> parsing (quick win, single-section coverage)

• DocxReader.swift:823 — replace continue with document.sectionProperties = parseSectPr(el) (new helper).
• parseSectPr(_:) -> SectionProperties — parse children:
  • <w:headerReference w:type="default|even|first" r:id="X"/> → headerReferences.{defaultRef,evenRef,firstRef}
  • <w:footerReference w:type="default|even|first" r:id="X"/> → footerReferences.{defaultRef,evenRef,firstRef}
  • <w:pgSz w:w=… w:h=… w:orient=…/> → pageSize, orientation
  • <w:pgMar …/> → pageMargins
  • <w:pgNumType w:fmt=… w:start=…/> → pageNumberFormat, pageNumberStartValue
  • <w:titlePg/> → titlePageDistinct
  • <w:cols w:num=…/> → columns
  • <w:docGrid …/> → docGrid
  • <w:sectPrChange> → if present, capture as rawXML (revision tracking, low priority)
• Capture remaining unknown children as rawXML on SectionProperties (architectural pattern: Run.rawElements).
• SectionProperties.toXML() — emit captured rawXML for byte-equivalent fallback.
• Test: Issue67SectPrRoundTripTests.testBodyLevelSectPrPreservesHeaderReferences.

This alone would unblock single-section docx (most common case for thesis-style documents that flatten all chapters under one section).

Phase B: Multi-section + mid-document break tracking (full fix)

• Model change: WordDocument.sections: [Section] (new) where Section = (sectPr: SectionProperties, breakBeforeParagraphIndex: Int?). Body-level <w:sectPr> → final entry; mid-document <w:p><w:pPr><w:sectPr> → entry with breakBeforeParagraphIndex set.
• Keep WordDocument.sectionProperties: SectionProperties as a deprecated alias pointing at sections.last?.sectPr ?? SectionProperties() for backward compat.
• Reader: parseContainerBody loop — when paragraph contains <w:pPr><w:sectPr>, parse the sectPr and emit a Section entry; the paragraph itself stays in body.
• Writer: re-emit each Section's sectPr at correct position (mid-document inside the paragraph's <w:pPr>, final at end of <w:body>).
• Test: Issue67SectPrRoundTripTests.testMultiSectionPreservation — verify _raw.docx 3 sectPrs survive read→write byte-equivalent.

Phase C: Container-level sectPr (low priority)

• DocxReader.swift:1607 — same handling but for <w:hdr> / <w:ftr> / <w:footnote> / <w:endnote> containers. Rare but valid (e.g., footnote separator with its own page properties).

Complexity

Plan (or Spectra for Phase B if multi-section model change should be spec'd).

Triggers (Layer P):

• 2+ files have ordered dependencies — DocxReader.swift parser change + Section.swift model change + DocxWriter.swift emit change must land together
• Strategy has 5+ ordered steps — Phase A alone has 8 sub-tasks
• Decision-heavy with 2+ valid approaches — Phase B model: array-of-Section vs deprecate-sectionProperties vs keep-both; mid-document vs final-only first
• Risk-sensitive boundary — round-trip integrity for any docx with multiple sections (academic + corporate templates very common)

Phase A by itself is Plan; if Phase B is in-scope, it's Spectra (model-shape change touches Document + Section + Paragraph public API and would benefit from spec contract for future maintainers).

Recommend tackling Phase A first (Plan tier, single-PR), ship as v0.28.0, then evaluate Phase B as a follow-up issue with full Spectra workflow.

Risks

• Phase A risk: <w:sectPr> at body level vs inside paragraph <w:pPr> have different DOM positions. Phase A only touches body level — mid-document section breaks remain lossy. For docs where section-break-on-paragraph is the only mechanism (Word UI's default "Next Page" break inserts mid-document sectPr inside <w:pPr>), Phase A alone won't help.
• Verify with thesis _raw.docx: post-Phase-A round trip should preserve section 3 (final body-level sectPr — title page); sections 1+2 are mid-document breaks → still lost until Phase B.
• Lenient parsers don't catch: python-docx silently accepts the default-init sectPr; Word's strict validator doesn't reject either (just renders without headers/footers). The bug is silent quality degradation, not a hard failure — easy to miss in CI.

Verification commands (post-fix)

cd ooxml-swift
swift test --filter Issue67SectPrRoundTripTests

# Phase A acceptance:
unzip -p _raw_test.docx word/document.xml | grep -oE 'headerReference w:type="(default|first|even)"' | sort
# vs round-trip output — at least body-level set should match

cd thesis-repo
scripts/rescue/.build/debug/rescue --refresh-fields-only \
  --input docs/...碩士論文_raw.docx --output /tmp/probe.docx
unzip -p /tmp/probe.docx word/document.xml | grep -c '<w:headerReference'
# Phase A: ≥3 (the final body-level sectPr's references)
# Phase B: ≥10 (all 3 sectPrs' references combined)

Workaround for thesis #20

Already applied — surgical Python sectPr swap copying _raw section 2's sectPr into v0.27.0 output. Single-section result with watermark active. Page-number format distinction (lowerRoman in front matter vs decimal in body) lost; accepted P3 cosmetic compromise.

[kiki830621]

Implementation Plan (Plan tier — Phase A)

Scope: only body-level <w:sectPr> parse (DocxReader.swift:823). Phase B (multi-section + mid-document break tracking) and Phase C (container-level sectPr at line 1607) explicitly out-of-scope; will be filed as follow-up if/when Phase A lands and thesis acceptance test reveals remaining gaps.

Files & Changes

• Sources/OOXMLSwift/Models/Section.swift — add var rawChildren: [String] = [] to SectionProperties. Update toXML() to emit captured rawChildren just before the closing </w:sectPr> (after typed children). Pattern: same as Run.rawElements v0.14.0+/[test] Test 25.4 (endnote) missing modifiedParts assertion (asymmetry vs 25.1-25.3) #52 — "if not typed, preserve as raw" architectural principle.

• Sources/OOXMLSwift/IO/DocxReader.swift — three coordinated edits:

  • Add new internal static func parseSectPr(from el: XMLElement, relationships: RelationshipsCollection) throws -> SectionProperties helper. Walks <w:sectPr> children; recognized: headerReference (type=default/first/even → headerReferences.{defaultRef,firstRef,evenRef}), footerReference (same per-type fan-out), pgSz (w/h/orient → pageSize+orientation), pgMar (top/right/bottom/left/header/footer/gutter → pageMargins), pgNumType (fmt/start → pageNumberFormat+pageNumberStartValue), titlePg → titlePageDistinct=true, cols (num → columns), docGrid (linePitch/charSpace → docGrid), lnNumType (countBy/start/restart → lineNumbers), vAlign (val → verticalAlignment), type (val → sectionBreakType). Unknown children → push raw XML serialization to rawChildren.
  • Change parseBodyChildren(in:relationships:styles:numbering:collectingTablesInto:) signature to return tuple (children: [BodyChild], sectPr: SectionProperties?). Inside, line 823 case "sectPr" replaces continue with if sectPr == nil { sectPr = try Self.parseSectPr(from: el, relationships: relationships) }; continue. Last-wins semantics rejected (ECMA-376 spec only allows ONE body-level sectPr); first-wins documented in helper comment.
  • Update misleading comment block at lines 824–829: replace "parsed separately into WordDocument.sectionProperties" with accurate description ("parsed via parseSectPr() and bubbled up through return tuple to caller, which assigns to WordDocument.sectionProperties").
  • Update parseBody at line 749: capture tuple, assign body.children = result.0, return (body, result.1) — also signature change.
  • Update caller at line 191: let bodyResult = try Self.withWhitespaceContext(...) { try parseBody(...) }; then document.body = bodyResult.body; if let sp = bodyResult.sectionProperties { document.sectionProperties = sp }.

• Tests/OOXMLSwiftTests/Issue67SectPrRoundTripTests.swift — new file, four tests:

  • testBodyLevelSectPrPreservesHeaderReferences (RED→GREEN baseline) — input docx with <w:sectPr><w:headerReference w:type="default" r:id="rId8"/><w:headerReference w:type="first" r:id="rId11"/><w:footerReference w:type="default" r:id="rId10"/></w:sectPr> body-level → DocxReader.read → assert document.sectionProperties.headerReferences.defaultRef == "rId8", .firstRef == "rId11", .footerReferences.defaultRef == "rId10".
  • testBodyLevelSectPrRoundTripPreservesPageSize — A4 (<w:pgSz w:w="11906" w:h="16838"/>) survives Reader→Writer round-trip; output zip's word/document.xml contains w:w="11906" w:h="16838" (NOT Letter default 12240×15840).
  • testBodyLevelSectPrPreservesPageNumberType — <w:pgNumType w:fmt="lowerRoman" w:start="1"/> round-trips byte-equivalent.
  • testBodyLevelSectPrPreservesTitlePg — <w:titlePg/> round-trips (boolean field set on read, emitted on write).
  • testBodyLevelSectPrPreservesUnknownChildrenAsRaw — synthetic <w:sectPr><w:foo>bar</w:foo><w:pgSz w:w="11906" w:h="16838"/></w:sectPr> round-trips with <w:foo>bar</w:foo> preserved (rawChildren coverage).

• CHANGELOG.md — ## [0.28.0] - 2026-05-XX entry: "fix(sectPr): Phase A — DocxReader now parses body-level <w:sectPr> and populates WordDocument.sectionProperties. Resolves silent header/footer reference loss + page properties reset to default Letter on round-trip (Multi-section <w:sectPr> structure collapses to single generic sectPr — headerReference / footerReference lost #67). Phase B (multi-section + mid-document break tracking) tracked separately."

Sequencing & Dependencies

1. Tests first (RED): write Issue67SectPrRoundTripTests against current main. Expect 4 of 5 to fail (the testUnknownChildrenAsRaw only fails after rawChildren field exists).
2. Add rawChildren to SectionProperties model + update toXML() — additive, no existing test breakage.
3. Implement parseSectPr helper — no wire-up yet, pure function.
4. Wire-up: change parseBodyChildren signature → cascades to parseBody → caller. Single coordinated commit because signature change has 3 call sites that all break together (line 749, line 814 recursive sdtContent call, line 191 main caller).
5. Run swift test — Issue67 tests now GREEN, no regressions in existing 881 tests.
6. CHANGELOG + release prep.

Critical sequencing note: step 4 changes the signature of parseBodyChildren which is also called recursively from line 814 (sdtContent path). The recursive call doesn't need the sectPr (sdtContent shouldn't have body-level sectPr in any sane document), so it can discard with let (children, _) = try parseBodyChildren(...). This is the only nested complexity.

Decision Points

Question	Decision	Rationale
Signature change vs inout vs side-channel?	Tuple return (children, sectPr)	Cleanest FP-style, no aliasing; only 3 call sites to update; recursive sdtContent caller discards sectPr part with let (c, _).
Include rawChildren field now or defer?	Include now	Issue body explicitly mentions the rawChildren architecture; cost is ~10 lines; prevents future loss bugs for <w:sectPrChange> (revision tracking) and other rare children.
Multiple body-level <w:sectPr> semantics?	First-wins (ignore subsequent)	ECMA-376 §17.6.18 spec only permits ONE body-level sectPr; first-wins is more defensive than last-wins for malformed input.
Update parseBody signature too?	Yes	Cleanest propagation of sectPr from inner walk to caller; alternative (re-walking body XMLElement at line 191 to find <w:sectPr> separately) duplicates work.

Risks & Mitigations

• Existing fixture round-trip baselines: any test that previously asserted "after round-trip, sectionProperties == default-init" will now fail because we'll be reading actual sectPr. Mitigation: pre-flight swift test baseline before changes; identify any such test; either update assertion (preferred) or refactor test to use a fixture without body-level sectPr.
• Public API stability: parseBodyChildren is internal static, signature change is safe. parseBody is private static. Only WordDocument.sectionProperties (already public) is observably mutated, in a strictly-better way.
• Phase B coupling: mid-document section breaks (<w:p><w:pPr><w:sectPr>) are still lossy after Phase A — but they were already lossy before, so no regression. Phase A makes single-section thesis-style docx work; multi-section requires Phase B (separate issue/PR).
• Acceptance: post-Phase-A, thesis _raw.docx round-trip should preserve section 3 (the body-level final sectPr — title page) and emit <w:headerReference>/<w:footerReference> for that section. Sections 1 + 2 remain lossy until Phase B. This is the documented expectation.

Test Plan

Test	Assertion (RED → GREEN)
testBodyLevelSectPrPreservesHeaderReferences	After read: headerReferences.{default,first} + footerReferences.default all populated, not nil.
testBodyLevelSectPrRoundTripPreservesPageSize	After write: zip's document.xml contains w:w="11906" w:h="16838", NOT 12240/15840.
testBodyLevelSectPrPreservesPageNumberType	After write: <w:pgNumType w:start="1" w:fmt="lowerRoman"/> present.
testBodyLevelSectPrPreservesTitlePg	After write: <w:titlePg/> present.
testBodyLevelSectPrPreservesUnknownChildrenAsRaw	After write: <w:foo>bar</w:foo> survives via rawChildren capture.

Plus swift test full suite (currently 881 ✓) — must remain 881 ✓ + 5 new = 886 ✓.

Out-of-scope (explicitly will NOT touch)

• Phase B: multi-section structure, mid-document section break tracking (<w:p><w:pPr><w:sectPr> parse). These still flatten on Phase A.
• Phase C: container-level sectPr at line 1607 (sectPr inside <w:hdr> / <w:ftr> / <w:footnote> / <w:endnote>). Rare; deferred.
• Refactor: WordDocument.sectionProperties: SectionProperties stays singular (no sections: [Section] array migration). That's Phase B's job.
• Existing helpers (set_section_header_footer_references, setPageSize, etc.) untouched — they already operate on sectionProperties correctly post-fix.
• Thesis P3 enhancement: InsertLocationError add LocalizedError conformance (post-che-word-mcp#91 verify follow-up F5) #20 re-rescue with v0.28.0 — separate task, post-PR-merge.

Tangential Observations (filed mid-plan, v2.42.0+ #524)

Filed: #68 (Phase 7 OMath splice emits non-self-closing rFonts — bloat + Office compat risk), #69 (settings.xml round-trip loss 19KB→400 bytes — same skip pattern as #67, blocks CJK font hints).

Why surfaced: #68 found while diff-investigating thesis font issue (344 non-self-closing rFonts in v0.27.0 OMath splice output, 0 in body text). #69 is the actual root cause of the thesis "font missing" symptom that surfaced during /idd-close #66 — fixing #67 alone will not restore CJK fonts; #69 is also needed.

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• Sources/OOXMLSwift/Models/Section.swift — var rawChildren: [String] = [] added; toXML() emits rawChildren before </w:sectPr> → commit de83eef
• Sources/OOXMLSwift/IO/DocxReader.swift — parseSectPr(from:) helper + parseBodyChildren signature (children, sectPr) + parseBody signature (body, sectionProperties) + caller wire-up at line 191 + recursive sdtContent discard + comment fix → commit de83eef
• Tests/OOXMLSwiftTests/Issue67SectPrRoundTripTests.swift — 5 tests covering headerReferences / pageSize / pageNumberType / titlePg / unknown rawChildren → commit de83eef
• CHANGELOG.md — ## [0.28.0] - 2026-05-05 Phase A entry with full backward-compat notes → commit de83eef

Legend: - [x] done · - [~] skipped (may revisit) · - [-] won't fix (scope)
idd-close will refuse to close if any - [ ] remains in this checklist.

Changes

• de83eef — fix(sectPr): Phase A — DocxReader parses body-level <w:sectPr> (Multi-section <w:sectPr> structure collapses to single generic sectPr — headerReference / footerReference lost #67)

Files Changed

 CHANGELOG.md                                              |  48 +++++
 Sources/OOXMLSwift/IO/DocxReader.swift                    | 189 ++++++++++++++++++++--
 Sources/OOXMLSwift/Models/Section.swift                   |  16 +++
 Tests/OOXMLSwiftTests/Issue67SectPrRoundTripTests.swift   | 137 +++++++++++++++++ (new)
 4 files changed, 376 insertions(+), 14 deletions(-)

Verification

$ swift test --filter Issue67SectPrRoundTripTests
Test Suite 'Issue67SectPrRoundTripTests' passed
  Executed 5 tests, with 0 failures (0 unexpected) in 0.001 (0.002) seconds

$ swift test
Test Suite 'All tests' passed at 2026-05-05 08:33:48.419.
  Executed 888 tests, with 1 test skipped and 0 failures (0 unexpected) in 6.078s

883 baseline → 888 ✓ (5 new), 1 pre-existing skip preserved, 0 regressions.

Scope Compliance

Strict Phase A only:

• ✅ Body-level <w:sectPr> parse via new parseSectPr helper
• ✅ Signature change cascade (4 sites: parseBodyChildren / parseBody / top-level caller / recursive sdtContent discard) coordinated in single commit
• ✅ rawChildren capture for unknown children (architectural pattern: Run.rawElements [test] Test 25.4 (endnote) missing modifiedParts assertion (asymmetry vs 25.1-25.3) #52)
• ❌ NOT touched: Phase B (multi-section + <w:p><w:pPr><w:sectPr> mid-document), Phase C (container-level sectPr at line 1607), WordDocument.sectionProperties: [Section] array migration. All deferred per plan.

Tangential issues (filed during plan drafting, parallel work)

• [bug] Phase 7 inline OMath splice emits non-self-closing <w:rFonts ...></w:rFonts> #68 — Phase 7 inline OMath splice emits non-self-closing <w:rFonts> (344 in thesis). Distinct from Multi-section <w:sectPr> structure collapses to single generic sectPr — headerReference / footerReference lost #67.
• [bug] settings.xml round-trip loss (~19KB → ~400 bytes) — same skip pattern as #67 #69 — word/settings.xml round-trip loss (~19KB → ~400 bytes). Same skip pattern as Multi-section <w:sectPr> structure collapses to single generic sectPr — headerReference / footerReference lost #67. Root cause of thesis CJK font fallback to PMingLiU.

Next: verification pending

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

none surfaced (Plan drafting Step 2.5 already filed #68 / #69)