@nguyenphp/antigravity-marketing 1.0.16 → 1.0.19

package/templates/.agent/skills/minimax-docx/references/openxml_encyclopedia_part3.md

@@ -0,0 +1,3381 @@
+# OpenXML SDK C# Code Encyclopedia
+Complete, heavily commented C# code patterns for DocumentFormat.OpenXml 3.x / .NET 8+ / C# 12.
+
+**Namespace aliases used throughout:**
+```csharp
+using DocumentFormat.OpenXml;
+using DocumentFormat.OpenXml.Packaging;
+using DocumentFormat.OpenXml.Wordprocessing;
+using A  = DocumentFormat.OpenXml.Drawing;
+using DW = DocumentFormat.OpenXml.Drawing.Wordprocessing;
+using M  = DocumentFormat.OpenXml.Math;
+using PIC = DocumentFormat.OpenXml.Drawing.Pictures;
+```
+
+**EMU conversion reference** (used throughout image/shape code):
+```
+1 inch  = 914400 EMU
+1 cm    = 360000 EMU
+1 pixel @ 96dpi = 9525 EMU
+1 pt    = 12700 EMU
+```
+
+---
+
+## Table of Contents
+
+1. [Table of Contents (TOC)](#1-table-of-contents-toc)
+2. [Footnotes and Endnotes](#2-footnotes-and-endnotes)
+3. [Field Codes — Comprehensive](#3-field-codes--comprehensive)
+4. [Track Changes / Revisions](#4-track-changes--revisions)
+5. [Comments (4-File System)](#5-comments-4-file-system)
+6. [Images — Deep Dive](#6-images--deep-dive)
+7. [Drawing Shapes (Non-Image)](#7-drawing-shapes-non-image)
+8. [Math / Equations (OMML)](#8-math--equations-omml)
+9. [Numbering System — Deep Dive](#9-numbering-system--deep-dive)
+10. [Document Protection & Encryption](#10-document-protection--encryption)
+
+---
+
+## 1. Table of Contents (TOC)
+
+### 1.1 Basic TOC Field (SimpleField Pattern)
+
+The simplest way to insert a TOC. Uses `SimpleField` which wraps the entire field in one element.
+
+```csharp
+// Creates:
+// <w:p>
+//   <w:r>
+//     <w:fldChar w:fldCharType="begin"/>
+//   </w:r>
+//   <w:r>
+//     <w:instrText xml:space="preserve"> TOC \o "1-3" \h \z \u </w:instrText>
+//   </w:r>
+//   <w:r>
+//     <w:fldChar w:fldCharType="separate"/>
+//   </w:r>
+//   <w:r>
+//     <w:t>Update this field to generate table of contents.</w:t>
+//   </w:r>
+//   <w:r>
+//     <w:fldChar w:fldCharType="end"/>
+//   </w:r>
+// </w:p>
+
+var tocParagraph = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" TOC \\o \"1-3\" \\h \\z \\u ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    // Placeholder text shown before update
+    new Run(new Text("Update this field to generate table of contents.") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+body.Append(tocParagraph);
+```
+
+**TOC switch reference:**
+| Switch | Meaning |
+|--------|---------|
+| `\o "1-3"` | Include outline levels 1–3 (customize as needed) |
+| `\h` | Make entries hyperlinks (clickable) |
+| `\z` | Hide tab leader and page numbers in Web Layout view |
+| `\u` | Use applied paragraph outline level |
+| `\f` | TOC entry from bookmark |
+| `\t "style1,style2"` | Use custom styles instead of outline levels |
+| `\n "1-2"` | Omit page numbers for levels 1–2 |
+
+### 1.2 TOC Field with SdtBlock Wrapper
+
+Wrapping a TOC in a Structured Document Tag (SdtBlock) enables rich content control features.
+
+```csharp
+// SdtBlock wrapper provides:
+// - Ability to repeat/remove the entire TOC
+// - Richer programmatic control
+// - "Content Control" appearance in Word UI
+
+var sdtBlock = new SdtBlock(
+    // SdtProperties defines the control's identity and behavior
+    new SdtProperties(
+        new SdtAlias { Val = "Table of Contents" },
+        new Tag { Val = "toc" },
+        new SdtContentText()  // Plain text content
+    ),
+    // SdtContentBlock contains the actual TOC field
+    new SdtContentBlock(
+        new Paragraph(
+            new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+            new Run(new FieldCode(" TOC \\o \"1-2\" \\h \\z ") { Space = SpaceProcessingModeValues.Preserve }),
+            new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+            new Run(new Text("Press F9 or right-click and select 'Update Field'") { Space = SpaceProcessingModeValues.Preserve }),
+            new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+        )
+    )
+);
+body.Append(sdtBlock);
+```
+
+### 1.3 TOC with Custom Heading Levels
+
+Use the `\t` switch to build a TOC from arbitrary styles (not just Heading 1–9).
+
+```csharp
+// TOC using custom style names instead of outline levels:
+// \t switch format: "style1,level1,style2,level2,..."
+// This uses CustomHeading1 and CustomHeading2 styles mapped to TOC levels
+
+var customTocPara = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" TOC \\t \"CustomHeading1,1,CustomHeading2,2,CustomHeading3,3\" \\h \\z ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("Update to see entries from CustomHeading1/2/3 styles.") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+### 1.4 TOC with Hyperlinks (\h switch)
+
+The `\h` switch makes TOC entries clickable hyperlinks. This requires the entries to have a hyperlink anchor.
+
+```csharp
+// When \h is used, Word generates internal hyperlinks to each heading.
+// The target is the bookmark automatically created by Word for headings.
+// This is the standard pattern — no additional work needed in the field code itself.
+
+var tocWithHyperlinks = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" TOC \\o \"1-3\" \\h \\z \\u ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    // In Web Layout/Print Layout, Word will populate this with real entries
+    // Each entry will be a hyperlink pointing to the heading's internal bookmark
+    new Run(new Text("Click to update...") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+### 1.5 Auto-Update TOC on Document Open
+
+You cannot programmatically update a TOC field's content (Word does this on open). Instead, tell Word to update fields automatically.
+
+```csharp
+// Method 1: Via DocumentSettingsPart — UpdateFieldsOnOpen
+var settingsPart = mainDocumentPart.AddNewPart<DocumentSettingsPart>();
+settingsPart.Settings = new Settings(
+    new UpdateFieldsOnOpen { Val = true }  // Triggers field update on open
+);
+settingsPart.Settings.Save();
+
+// Method 2: Field code includes \w to preserve formatting changes
+// (Field code approach is limited — you still need Word to evaluate it)
+
+// GOTCHA: OpenXML SDK cannot evaluate field codes.
+// Word evaluates fields on open. Other readers (e.g., LibreOffice) may not.
+// The document opens without content until the user explicitly updates.
+```
+
+### 1.6 TOC Styles — Custom TOC1, TOC2, TOC3 Styles with Leaders
+
+Define custom TOC styles with indentation, tab leaders, and proper formatting.
+
+```csharp
+// First, add TOC1/TOC2/TOC3 styles to StyleDefinitionsPart
+var stylesPart = mainDocumentPart.AddNewPart<StyleDefinitionsPart>();
+var styles = new Styles();
+
+// TOC1 — Top-level entry (e.g., "1. Heading")
+var toc1Style = new Style(
+    new StyleName { Val = "toc 1" },
+    new BasedOn { Val = "Normal" },
+    new PrimaryStyle(),
+    new StyleParagraphProperties(
+        new SpacingBetweenLines { Before = "120", After = "60" },
+        new Tabs(new TabStop { Val = TabStopValues.Right, Leader = TabStopLeaderCharValues.Dot, Position = 9072 })  // 5 inches right-aligned with dot leader
+    ),
+    new StyleRunProperties(
+        new Bold(),
+        new FontSize { Val = "24" },  // 12pt
+        new FontSizeComplexScript { Val = "24" }
+    )
+) { Type = StyleValues.Paragraph, StyleId = "TOC1" };
+styles.Append(toc1Style);
+
+// TOC2 — Second-level entry (e.g., "1.1  Subheading")
+var toc2Style = new Style(
+    new StyleName { Val = "toc 2" },
+    new BasedOn { Val = "Normal" },
+    new PrimaryStyle(),
+    new StyleParagraphProperties(
+        new Indentation { Left = "220", Hanging = "220" },  // 0.15" indent, hang to align after number
+        new SpacingBetweenLines { Before = "60", After = "40" },
+        new Tabs(new TabStop { Val = TabStopValues.Right, Leader = TabStopLeaderCharValues.Dot, Position = 9072 })
+    ),
+    new StyleRunProperties(
+        new FontSize { Val = "20" },  // 10pt
+        new FontSizeComplexScript { Val = "20" }
+    )
+) { Type = StyleValues.Paragraph, StyleId = "TOC2" };
+styles.Append(toc2Style);
+
+// TOC3 — Third-level entry
+var toc3Style = new Style(
+    new StyleName { Val = "toc 3" },
+    new BasedOn { Val = "Normal" },
+    new PrimaryStyle(),
+    new StyleParagraphProperties(
+        new Indentation { Left = "440", Hanging = "440" },  // 0.3" indent
+        new SpacingBetweenLines { Before = "40", After = "20" },
+        new Tabs(new TabStop { Val = TabStopValues.Right, Leader = TabStopLeaderCharValues.Dot, Position = 9072 })
+    ),
+    new StyleRunProperties(
+        new Italic(),
+        new FontSize { Val = "20" },
+        new FontSizeComplexScript { Val = "20" }
+    )
+) { Type = StyleValues.Paragraph, StyleId = "TOC3" };
+styles.Append(toc3Style);
+
+stylesPart.Styles = styles;
+stylesPart.Styles.Save();
+
+// Now use \t switch to reference these styles in the TOC field:
+// TOC \t "TOC1,1,TOC2,2,TOC3,3" \h \z
+```
+
+**Tab leader options:** `TabStopLeaderCharValues.Dot` (........), `TabStopLeaderCharValues.Dash` (--------), `TabStopLeaderCharValues.Underscore` (________), `TabStopLeaderCharValues.MiddleDot` (·······).
+
+### 1.7 Mini TOC for a Section
+
+A mini TOC covers only a portion of the document using a bookmark-scoped `\f` switch.
+
+```csharp
+// Step 1: Define a bookmark around the section to be covered
+var sectionStart = new BookmarkStart { Id = "10", Name = "_Section1TOC" };
+var sectionEnd = new BookmarkEnd { Id = "10" };
+
+// Step 2: Put heading paragraphs inside the bookmark range
+var headingPara = new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+    new Run(new Text("Section A: Introduction"))
+);
+
+// Full section wrapped in bookmark
+body.Append(sectionStart);
+body.Append(headingPara);
+body.Append(sectionEnd);
+
+// Step 3: Mini TOC field references that bookmark with \f switch
+var miniTocPara = new Paragraph(
+    new Run(new Text("In this section: ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" TOC \\f _Section1TOC ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("Mini TOC placeholder") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+---
+
+## 2. Footnotes and Endnotes
+
+### 2.1 FootnotesPart — Initialization
+
+Footnotes in Word require a dedicated `FootnotesPart`. The first three footnotes are special: separator, continuation separator, and continuation notice.
+
+```csharp
+// Initialize the FootnotesPart
+var footnotesPart = mainDocumentPart.AddNewPart<FootnotesPart>();
+var footnotes = new Footnotes();
+
+// CRITICAL: Footnotes must start with these 3 special footnotes:
+// 1. Separator (id="0") — thin line between main text and footnotes
+// 2. ContinuationSeparator (id="1") — thick line when footnotes continue to next column/page
+// 3. ContinuationNotice (id="2") — "..." text when footnotes overflow
+
+// Footnote ID=0: Separator (appears between main text and first footnote)
+var separatorFootnote = new Footnote(
+    new Paragraph(
+        new ParagraphProperties(
+            new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }
+        ),
+        // The separator is just a paragraph with a border at the bottom
+        new Paragraph(
+            new Run(new Separator())
+        )
+    )
+) { Type = FootnoteEndnoteValues.Separator, Id = 0 };
+footnotes.Append(separatorFootnote);
+
+// Footnote ID=1: Continuation Separator
+var continuationSepFootnote = new Footnote(
+    new Paragraph(
+        new ParagraphProperties(
+            new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }
+        ),
+        new Run(new ContinuationSeparator())
+    )
+) { Type = FootnoteEndnoteValues.ContinuationSeparator, Id = 1 };
+footnotes.Append(continuationSepFootnote);
+
+// Footnote ID=2: Continuation Notice (optional, appears when footnotes overflow)
+var continuationNoticeFootnote = new Footnote(
+    new Paragraph(
+        new ParagraphProperties(
+            new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }
+        ),
+        new Run(new Text("...") { Space = SpaceProcessingModeValues.Preserve })
+    )
+) { Type = FootnoteEndnoteValues.ContinuationNotice, Id = 2 };
+footnotes.Append(continuationNoticeFootnote);
+
+footnotesPart.Footnotes = footnotes;
+footnotesPart.Footnotes.Save();
+```
+
+### 2.2 Adding a Normal Footnote
+
+Place a `FootnoteReference` in the document body and corresponding `Footnote` content in `FootnotesPart`.
+
+```csharp
+// In the document body, at the insertion point:
+var footnoteRefRun = new Run(
+    new RunProperties(
+        new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }
+    ),
+    new FootnoteReference { Id = 3 }  // ID must match the Footnote's Id
+);
+body.Append(new Paragraph(
+    new Run(new Text("Some text with a footnote marker.") { Space = SpaceProcessingModeValues.Preserve }),
+    footnoteRefRun
+));
+
+// In FootnotesPart, add the corresponding footnote content:
+// <w:footnote w:id="3">
+//   <w:p>
+//     <w:pPr><w:pStyle w:val="FootnoteText"/></w:pPr>
+//     <w:r><w:footnoteRef/></w:r>
+//     <w:r><w:t xml:space="preserve"> This is the footnote text.</w:t></w:r>
+//   </w:p>
+// </w:footnote>
+
+var newFootnote = new Footnote { Id = 3 };
+newFootnote.Append(new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "FootnoteText" }),
+    new Run(new FootnoteReferenceMark()),  // Small superscript mark
+    new Run(new Text(" This is the footnote text.") { Space = SpaceProcessingModeValues.Preserve })
+));
+footnotesPart.Footnotes!.Append(newFootnote);
+footnotesPart.Footnotes.Save();
+```
+
+### 2.3 Footnote with Custom Mark (Asterisk, Symbol)
+
+Override the default auto-numbering with a custom symbol.
+
+```csharp
+// Use FootnoteReferenceMark (the automatic symbol) OR provide a custom character.
+// For custom marks, use a regular Run with the symbol character instead of FootnoteReferenceMark.
+
+// Footnote ID=4 with custom asterisk mark
+var customFootnote = new Footnote { Id = 4 };
+customFootnote.Append(new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "FootnoteText" }),
+    // Custom mark: use a bold asterisk from Symbol font
+    new Run(
+        new RunProperties(
+            new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }
+        ),
+        new RunFonts { Ascii = "Symbol", HighAnsi = "Symbol" },
+        new Text("*")
+    ),
+    new Run(new Text(" Custom footnote with symbol mark.") { Space = SpaceProcessingModeValues.Preserve })
+));
+footnotesPart.Footnotes!.Append(customFootnote);
+
+// In document body, at the insertion point:
+var customFootnoteRef = new Run(
+    new RunProperties(
+        new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }
+    ),
+    new FootnoteReference { Id = 4 }
+);
+```
+
+### 2.4 FootnotePosition — Placement via SectionProperties
+
+Control whether footnotes appear at the bottom of each page or beneath the text.
+
+```csharp
+// Add FootnoteProperties to SectionProperties
+var sectPr = body.Elements<SectionProperties>().First()
+    ?? body.AppendChild(new SectionProperties());
+
+// Footnote placement:
+// - BottomOfPage (default) — footnotes appear at bottom of page
+// - BeneathText — footnotes appear immediately below the last text on the page
+sectPr.Append(new FootnoteProperties(
+    new FootnotePosition { Val = FootnotePositionValues.BeneathText }
+));
+
+// Footnote numbering restart options:
+// - RestartAtSection — restart numbering at each section
+// - RestartAtPage — restart at each page (Word default for footnotes)
+// - Continuous — don't restart (number sequentially through document)
+sectPr.Append(new FootnoteProperties(
+    new FootnotePosition { Val = FootnotePositionValues.BottomOfPage },
+    new FootnoteNumberingFormat { Val = NumberFormatValues.Decimal },  // 1, 2, 3...
+    new FootnoteNumberingStart { Val = 1 },  // Start at 1
+    new FootnoteNumberingRestart { Val = FootnoteRestartValues.RestartAtPage }
+));
+```
+
+### 2.5 EndnotesPart — Same Pattern
+
+Endnotes follow the exact same structure as footnotes but use `EndnotesPart`.
+
+```csharp
+var endnotesPart = mainDocumentPart.AddNewPart<EndnotesPart>();
+var endnotes = new Endnotes();
+
+// Endnote ID=0: Separator (same pattern as footnotes)
+var endnoteSeparator = new Endnote(
+    new Paragraph(new Run(new Separator()))
+) { Type = FootnoteEndnoteValues.Separator, Id = 0 };
+endnotes.Append(endnoteSeparator);
+
+// Endnote ID=1: ContinuationSeparator
+var endnoteContSep = new Endnote(
+    new Paragraph(new Run(new ContinuationSeparator()))
+) { Type = FootnoteEndnoteValues.ContinuationSeparator, Id = 1 };
+endnotes.Append(endnoteContSep);
+
+endnotesPart.Endnotes = endnotes;
+endnotesPart.Endnotes.Save();
+
+// In document body, use EndnoteReference instead of FootnoteReference
+var endnoteRefRun = new Run(
+    new RunProperties(
+        new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }
+    ),
+    new EndnoteReference { Id = 3 }
+);
+body.Append(new Paragraph(
+    new Run(new Text("An endnote marker.") { Space = SpaceProcessingModeValues.Preserve }),
+    endnoteRefRun
+));
+
+// Corresponding Endnote content in EndnotesPart
+var newEndnote = new Endnote { Id = 3 };
+newEndnote.Append(new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "EndnoteText" }),
+    new Run(new EndnoteReferenceMark()),
+    new Run(new Text(" This is the endnote content.") { Space = SpaceProcessingModeValues.Preserve })
+));
+endnotesPart.Endnotes!.Append(newEndnote);
+```
+
+### 2.6 Endnote Placement via SectionProperties
+
+```csharp
+// EndnoteProperties on SectionProperties controls endnote placement
+sectPr.Append(new EndnoteProperties(
+    new EndnotePosition { Val = EndnotePositionValues.EndOfDocument }  // Default
+    // Other options: EndOfSection, BeneathText (rarely used for endnotes)
+));
+```
+
+---
+
+## 3. Field Codes — Comprehensive
+
+### 3.1 SimpleField vs Complex Field Architecture
+
+**SimpleField** — single element, easier to write but less control:
+```csharp
+// <w:fldSimple w:instr=" PAGE "><w:r><w:t>1</w:t></w:r></w:fldSimple>
+new SimpleField(new Run(new Text("1"))) { Instruction = " PAGE " }
+```
+
+**Complex Field (Begin/Separate/End)** — full control over each field component:
+```csharp
+// <w:r><w:fldChar w:fldCharType="begin"/></w:r>
+// <w:r><w:instrText> PAGE </w:instrText></w:r>
+// <w:r><w:fldChar w:fldCharType="separate"/></w:r>
+// <w:r><w:t>1</w:t></w:r>
+// <w:r><w:fldChar w:fldCharType="end"/></w:r>
+new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }),
+new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+new Run(new Text("1")),  // Cached result shown until update
+new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+```
+
+**Key differences:**
+- `SimpleField` is one `w:fldSimple` element containing one `w:r`
+- Complex field uses `FieldChar` with `FieldCharValues.Begin/Separate/End` to delimit regions
+- `FieldCode` is `w:instrText` — contains the field instruction string
+- The text between `Separate` and `End` is the "cached result" shown before update
+- After `Separate`, `FieldCode` contains the switches that define field behavior
+
+### 3.2 PAGE, NUMPAGES, DATE, TIME
+
+**PAGE — current page number:**
+```csharp
+// SimpleField version
+new SimpleField(new Run(new Text("1"))) { Instruction = " PAGE " }
+
+// Complex field version
+new Paragraph(
+    new Run(new Text("Page ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("1")),  // Cached value
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+**NUMPAGES — total page count:**
+```csharp
+new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" NUMPAGES ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("10")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    new Run(new Text(" pages") { Space = SpaceProcessingModeValues.Preserve })
+);
+```
+
+**DATE — current date with format switch:**
+```csharp
+// DATE with custom format: \@ "yyyy-MM-dd"
+// The \@ switch specifies the date picture
+new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" DATE \\@ \"yyyy-MM-dd\" ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("2026-03-22")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// DATE with time: \@ "MMMM d, yyyy h:mm AM/PM"
+new Run(new FieldCode(" DATE \\@ \"MMMM d, yyyy h:mm AM/PM\" ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// DATE with locale: \* MERGEFORMAT preserves formatting on update
+new Run(new FieldCode(" DATE \\@ \"d/M/yyyy\" \\* MERGEFORMAT ") { Space = SpaceProcessingModeValues.Preserve }),
+```
+
+**TIME — current time:**
+```csharp
+new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" TIME \\@ \"HH:mm:ss\" ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("14:30:00")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+### 3.3 FILENAME, AUTHOR, TITLE (Document Properties)
+
+These fields pull from the document's core properties.
+
+```csharp
+// FILENAME — document filename
+new Run(new FieldCode(" FILENAME ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// FILENAME with path: \* MERGEFORMAT
+new Run(new FieldCode(" FILENAME \\* MERGEFORMAT ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// AUTHOR — from document core properties
+new Run(new FieldCode(" AUTHOR ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// TITLE — from document core properties
+new Run(new FieldCode(" TITLE ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// SUBJECT — from document core properties
+new Run(new FieldCode(" SUBJECT ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// Keywords — from document core properties
+new Run(new FieldCode(" KEYWORDS ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// All document property fields
+new Paragraph(
+    new Run(new Text("Title: ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" TITLE ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("My Document")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+**Set document properties programmatically:**
+```csharp
+// Set core properties via PackageProperties (OfficePackage)
+var package = doc.ExtendedFilePropertiesPart?.Properties;
+if (package != null)
+{
+    package.Creator = "Author Name";
+    package.Title = "Document Title";
+    package.Subject = "Subject";
+    package.Description = "Description";
+    package.Keywords = "keyword1, keyword2";
+    package.Save();
+}
+```
+
+### 3.4 REF — Cross-Reference to Bookmark
+
+`REF` retrieves the text of a bookmarked paragraph or the value of a REF field.
+
+```csharp
+// First, create a bookmark around some content
+var bookmarkStart = new BookmarkStart { Id = "100", Name = "Figure1Caption" };
+var bookmarkEnd = new BookmarkEnd { Id = "100" };
+var captionPara = new Paragraph(
+    new Run(new Text("Figure 1: Architecture diagram") { Space = SpaceProcessingModeValues.Preserve })
+);
+body.Append(new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "Caption" }),
+    bookmarkStart,
+    new Run(new Text("Figure 1: Architecture diagram")),
+    bookmarkEnd
+));
+
+// Now reference it with REF field
+var refField = new Paragraph(
+    new Run(new Text("As shown in ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" REF Figure1Caption \\* MERGEFORMAT ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("Figure 1: Architecture diagram")),  // Cached result
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    new Run(new Text(", the system consists of...") { Space = SpaceProcessingModeValues.Preserve })
+);
+```
+
+**REF switches:**
+| Switch | Effect |
+|--------|--------|
+| `\r` | Insert bookmarked text but as hyperlink |
+| `\h` | Make REF a hyperlink to the bookmark |
+| `\n` | Suppress paragraph number |
+| `\p` | Show relative position (above/below) |
+| `\t` | Suppress trailing spaces |
+| `\* MERGEFORMAT` | Preserve formatting |
+
+### 3.5 SEQ — Sequence Numbering for Figures/Tables
+
+`SEQ` generates auto-incrementing numbers for elements like figures, tables, and listings.
+
+```csharp
+// First figure caption
+var fig1Caption = new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "Caption" }),
+    new Run(new Text("Figure ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" SEQ Figure \\* ARABIC ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("1")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    new Run(new Text(": System Architecture") { Space = SpaceProcessingModeValues.Preserve })
+);
+
+// Second figure (Word auto-increments)
+var fig2Caption = new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "Caption" }),
+    new Run(new Text("Figure ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" SEQ Figure \\* ARABIC ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("2")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    new Run(new Text(": Data Flow") { Space = SpaceProcessingModeValues.Preserve })
+);
+
+// Reference a figure number
+var figRef = new Paragraph(
+    new Run(new Text("See Figure ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" SEQ Figure \\* ARABIC ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("1")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    new Run(new Text(" above.") { Space = SpaceProcessingModeValues.Preserve })
+);
+
+// SEQ sequence identifier: "Figure" can be any name
+// Multiple sequences: SEQ Figure, SEQ Table, SEQ Listing are independent
+```
+
+### 3.6 HYPERLINK — Internal and External Links
+
+```csharp
+// External hyperlink (to URL)
+var extHyperlinkRel = mainDocumentPart.AddHyperlinkRelationship(
+    new Uri("https://example.com"), true);
+var extHyperlink = new Hyperlink(
+    new Run(
+        new RunProperties(new Color { Val = "0563C1" }, new Underline { Val = UnderlineValues.Single }),
+        new Text("Visit Example.com")
+    )
+) { Id = extHyperlinkRel.Id };  // Id references the relationship
+
+// Internal hyperlink (to bookmark)
+var intHyperlink = new Hyperlink(
+    new Run(
+        new RunProperties(new Color { Val = "0563C1" }, new Underline { Val = UnderlineValues.Single }),
+        new Text("Go to Chapter 1")
+    )
+) { Anchor = "Chapter1Bookmark" };  // Anchor = bookmark name
+
+// HYPERLINK field for advanced cases (with screen tip)
+var hyperlinkedField = new Run(
+    new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" HYPERLINK \\l \"Chapter1Bookmark\" \\t \"_top\" ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("Go to Chapter 1")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// \l = target (anchor for internal, URL for external)
+// \t = target frame (optional, e.g., "_top" to open in same window)
+```
+
+### 3.7 MERGEFIELD — Mail Merge
+
+```csharp
+// MERGEFIELD uses a special syntax: MERGEFIELD FieldName
+// The field name must match a mail merge data source column name
+
+// Simple MERGEFIELD
+var mergeFieldPara = new Paragraph(
+    new Run(new Text("Dear ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" MERGEFIELD FirstName ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("«FirstName»")),  // «» are Word's placeholder markers
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    new Run(new Text(",") { Space = SpaceProcessingModeValues.Preserve })
+);
+
+// Full name with formatting
+var mergeFieldWithFormat = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" MERGEFIELD FullName \\* UPPERCASE ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("«FullName»")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// To actually perform mail merge, use Word's MailMerge settings
+var settingsPart = mainDocumentPart.AddNewPart<DocumentSettingsPart>();
+settingsPart.Settings = new Settings(
+    new MailMerge(
+        new DataType { Val = MailMergeDataValues.TextFile },
+        new DataSourceReference { Id = "rIdForDataSource" }
+    )
+);
+```
+
+### 3.8 IF Field — Conditional Text
+
+The `IF` field evaluates a condition and displays one of two text values. Commonly used with `MERGEFIELD`.
+
+```csharp
+// IF Field syntax: IF [expression] [operator] [value] "true_text" "false_text"
+// Often combined with MERGEFIELD:
+
+// If the recipient's region equals "USA", show "Dear Customer", otherwise "Dear Valued Customer"
+var ifFieldPara = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    // Complex nested: { IF { MERGEFIELD Region } = "USA" "Dear American Customer" "Dear Customer" }
+    new Run(new FieldCode(" IF ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),  // Nested MERGEFIELD begin
+    new Run(new FieldCode(" MERGEFIELD Region ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("«Region»")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),     // Nested MERGEFIELD end
+    new Run(new FieldCode(" = \"USA\" \"Dear American Customer\" \"Dear Customer\" ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("Dear Customer")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// Note: Nested fields within IF are tricky with complex field syntax.
+// A simpler approach: use two separate IF fields checking a bookmark value.
+```
+
+### 3.9 STYLEREF — Reference Heading Text
+
+`STYLEREF` displays the text of the nearest paragraph with a specified style — useful for running headers.
+
+```csharp
+// STYLEREF Heading1 — inserts the text of the most recent Heading1 paragraph
+// Great for running headers that show the current chapter
+
+// Running header in footer
+var footerPart = mainDocumentPart.AddNewPart<FooterPart>();
+footerPart.Footer = new Footer(
+    new Paragraph(
+        new ParagraphProperties(
+            new Justification { Val = JustificationValues.Right }
+        ),
+        // Left-aligned: chapter heading
+        new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+        new Run(new FieldCode(" STYLEREF \"Heading 1\" ") { Space = SpaceProcessingModeValues.Preserve }),
+        new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+        new Run(new Text("Chapter Title")),
+        new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+        new Run(new Text("\t") { Space = SpaceProcessingModeValues.Preserve }),  // Tab
+        // Right-aligned: page number
+        new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+        new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }),
+        new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+        new Run(new Text("1")),
+        new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+    )
+);
+
+// STYLEREF with \n switch to suppress paragraph numbering
+new Run(new FieldCode(" STYLEREF \"Heading 1\" \\n ") { Space = SpaceProcessingModeValues.Preserve }),
+
+// STYLEREF with \p switch to show relative position
+new Run(new FieldCode(" STYLEREF \"Heading 2\" \\p ") { Space = SpaceProcessingModeValues.Preserve }),
+```
+
+### 3.10 SET and ASK Fields
+
+`SET` stores a value in a variable. `ASK` prompts the user and stores their response.
+
+```csharp
+// SET — define a document variable (accessed via DOCPROPERTY or REF)
+var setField = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" SET MyVariable \"some value\" ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// REF to read the variable
+var refMyVar = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" REF MyVariable ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("some value")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// ASK — prompt user for input when field is updated
+// Note: ASK displays a dialog box when updated
+var askField = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" ASK AuthorName \"Enter author name:\" ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End }),
+    // REF to display the stored value
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" REF AuthorName ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("Author Name")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+```
+
+### 3.11 Calculated Fields (= Expressions)
+
+The `=` field evaluates arithmetic expressions.
+
+```csharp
+// = field with arithmetic
+var calcPara = new Paragraph(
+    new Run(new Text("Total: $") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" = 100 + 250 - 30 ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("320")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// = with multiplication using SEQ references
+var calcWithSeq = new Paragraph(
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),
+    new Run(new FieldCode(" = 3 * 5 ") { Space = SpaceProcessingModeValues.Preserve }),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }),
+    new Run(new Text("15")),
+    new Run(new FieldChar { FieldCharType = FieldCharValues.End })
+);
+
+// Combine with formatting
+new Run(new FieldCode(" = 1000 * 1.08 \\# \"#,##0.00\" ") { Space = SpaceProcessingModeValues.Preserve }),
+// \# switch applies number format to result
+```
+
+### 3.12 UpdateFieldsOnOpen — Automatic Field Updates
+
+```csharp
+// Settings that trigger field updates when document opens
+var settingsPart = mainDocumentPart.AddNewPart<DocumentSettingsPart>();
+settingsPart.Settings = new Settings(
+    // Update all fields (TOC, REF, PAGE, etc.) on open
+    new UpdateFieldsOnOpen { Val = true }
+);
+settingsPart.Settings.Save();
+
+// Additional field-related settings:
+var additionalSettings = new Settings(
+    // Auto-format fractions: 1/2 → ½
+    new AutomaticAdjustmentOfFontSizesToFitDocument(),
+
+    // True: use field codes instead of cached values on update
+    new UseXSLTWhenSaving(),
+
+    // Mail merge settings
+    new MailMerge(
+        new MainDocumentType { Val = MailMergeDocumentValues.FormLetters }
+    )
+);
+```
+
+---
+
+## 4. Track Changes / Revisions
+
+### 4.1 Enabling Track Changes
+
+Track changes must be explicitly enabled via DocumentSettingsPart.
+
+```csharp
+var settingsPart = mainDocumentPart.AddNewPart<DocumentSettingsPart>();
+settingsPart.Settings = new Settings(
+    // Enable track changes — any edit will be tracked
+    new TrackRevisions()
+);
+
+// Also recommended: prevent fields from being updated during tracking
+settingsPart.Settings.Append(new DonNotTrackFormatting());
+```
+
+### 4.2 InsertedRun (w:ins) — Tracked Insertion
+
+```csharp
+// <w:ins w:id="5" w:author="Alice" w:date="2026-03-22T10:00:00Z">
+//   <w:r>
+//     <w:t>Inserted text.</w:t>
+//   </w:r>
+// </w:ins>
+
+var insertedText = new InsertedRun(
+    new Run(
+        new Text("Inserted text.") { Space = SpaceProcessingModeValues.Preserve }
+    )
+)
+{
+    Author = "Alice",
+    Date = new DateTime(2026, 3, 22, 10, 0, 0, DateTimeKind.Utc),
+    Id = "5"
+};
+
+var para = new Paragraph(
+    new Run(new Text("Existing text. ") { Space = SpaceProcessingModeValues.Preserve }),
+    insertedText,
+    new Run(new Text(" More existing text.") { Space = SpaceProcessingModeValues.Preserve })
+);
+```
+
+### 4.3 DeletedRun (w:del) — Tracked Deletion
+
+**CRITICAL: Inside `w:del`, text MUST be `DeletedText` (`w:delText`), NOT `Text` (`w:t`)!**
+
+```csharp
+// <w:del w:id="6" w:author="Alice" w:date="2026-03-22T10:05:00Z">
+//   <w:r>
+//     <w:rPr><w:b/></w:rPr>
+//     <w:delText>Deleted text.</w:delText>
+//   </w:r>
+// </w:del>
+
+var deletedRun = new DeletedRun(
+    new Run(
+        new RunProperties(new Bold()),
+        new DeletedText("Deleted text.") { Space = SpaceProcessingModeValues.Preserve }
+    )
+)
+{
+    Author = "Alice",
+    Date = new DateTime(2026, 3, 22, 10, 5, 0, DateTimeKind.Utc),
+    Id = "6"
+};
+
+var para = new Paragraph(
+    new Run(new Text("Keep this. ") { Space = SpaceProcessingModeValues.Preserve }),
+    deletedRun,
+    new Run(new Text(" Keep this too.") { Space = SpaceProcessingModeValues.Preserve })
+);
+
+// GOTCHA: Never use <w:t> inside <w:del> — use <w:delText> only.
+// Using w:t inside w:del causes corruption or silent repair by Word.
+```
+
+### 4.4 RunPropertiesChange — Formatting Change Tracking
+
+Records that a run's formatting was changed. The `w:rPrChange` goes inside `w:rPr`.
+
+```csharp
+// <w:r>
+//   <w:rPr>
+//     <w:b/>  <!-- New: bold -->
+//     <w:rPrChange w:id="7" w:author="Bob" w:date="2026-03-22T11:00:00Z">
+//       <w:rPr/>  <!-- Old: no formatting -->
+//     </w:rPrChange>
+//   </w:rPr>
+//   <w:t>Formatted text.</w:t>
+// </w:r>
+
+// The current (new) formatting is in the outer w:rPr
+// The old (previous) formatting is in the w:rPrChange child
+var formattedTextRun = new Run(
+    new RunProperties(
+        new Bold(),  // New formatting: now bold
+        new RunPropertiesChange(  // Records the old formatting (empty = not bold)
+            new RunProperties()  // Empty = previously had no formatting
+        )
+        {
+            Author = "Bob",
+            Date = new DateTime(2026, 3, 22, 11, 0, 0, DateTimeKind.Utc),
+            Id = "7"
+        }
+    ),
+    new Text("Formatted text.") { Space = SpaceProcessingModeValues.Preserve }
+);
+```
+
+### 4.5 ParagraphPropertiesChange
+
+Records that paragraph-level properties were changed.
+
+```csharp
+// <w:pPr>
+//   <w:jc w:val="center"/>  <!-- New: centered -->
+//   <w:pPrChange w:id="8" w:author="Bob" w:date="2026-03-22T11:05:00Z">
+//     <w:pPr>
+//       <w:jc w:val="left"/>  <!-- Old: left-aligned -->
+//     </w:pPr>
+//   </w:pPrChange>
+// </w:pPr>
+
+var changedPara = new Paragraph(
+    new ParagraphProperties(
+        new Justification { Val = JustificationValues.Center },  // New
+        new ParagraphPropertiesChange(
+            new ParagraphProperties(
+                new Justification { Val = JustificationValues.Left }  // Old
+            )
+        )
+        {
+            Author = "Bob",
+            Date = new DateTime(2026, 3, 22, 11, 5, 0, DateTimeKind.Utc),
+            Id = "8"
+        }
+    ),
+    new Run(new Text("Centered paragraph."))
+);
+```
+
+### 4.6 ParagraphMarkRunPropertiesChange
+
+Records that the paragraph mark's formatting (trailing formatting) was changed.
+
+```csharp
+// <w:p>
+//   <w:pPr>
+//     <w:pPrChange .../>
+//   </w:pPr>
+//   <w:r>
+//     <w:rPr>
+//       <w:b/>  <!-- New paragraph mark: bold -->
+//       <w:rPrChange w:id="9" ...>
+//         <w:rPr/>  <!-- Old: no formatting on paragraph mark -->
+//       </w:rPrChange>
+//     </w:rPr>
+//   </w:r>
+// </w:r>
+```
+
+### 4.7 Table Revision Marks
+
+```csharp
+// TableRowInsertionRevision — a row was inserted
+// <w:trPr>
+//   <w:ins w:id="10" w:author="Alice" w:date="..."/>
+// </w:trPr>
+
+var insertedRow = new TableRow(
+    new TableRowProperties(
+        new TableRowInsertionRevision
+        {
+            Author = "Alice",
+            Date = new DateTime(2026, 3, 22, 12, 0, 0, DateTimeKind.Utc),
+            Id = "10"
+        }
+    ),
+    new TableCell(new Paragraph(new Run(new Text("New row cell"))))
+);
+
+// TableCellInsertionRevision — a cell was inserted
+var insertedCell = new TableCell(
+    new TableCellProperties(
+        new TableCellInsertionRevision
+        {
+            Author = "Alice",
+            Date = new DateTime(2026, 3, 22, 12, 1, 0, DateTimeKind.Utc),
+            Id = "11"
+        }
+    ),
+    new Paragraph(new Run(new Text("New cell")))
+);
+```
+
+### 4.8 SectionPropertiesChange
+
+```csharp
+// <w:sectPr>
+//   <w:sectPrChange w:id="12" w:author="Bob" w:date="...">
+//     <w:sectPr>
+//       <w:pgSz w:w="12240" w:h="15840"/>  <!-- Old: Letter -->
+//     </w:sectPr>
+//   </w:sectPrChange>
+//   <w:pgSz w:w="16838" w:h="11906"/>  <!-- New: A4 -->
+// </w:sectPr>
+
+var changedSection = new SectionProperties(
+    new PageSize { Width = 16838U, Height = 11906U },  // New: A4
+    new SectionPropertiesChange(
+        new SectionProperties(
+            new PageSize { Width = 12240U, Height = 15840U }  // Old: Letter
+        )
+    )
+    {
+        Author = "Bob",
+        Date = new DateTime(2026, 3, 22, 12, 30, 0, DateTimeKind.Utc),
+        Id = "12"
+    }
+);
+```
+
+### 4.9 NumberingChange
+
+```csharp
+// <w:numPr>
+//   <w:ilvl w:val="0"/>
+//   <w:numId w:val="3"/>
+//   <w:numPrChange w:id="13" w:author="Alice" w:date="...">
+//     <w:numPr>
+//       <w:ilvl w:val="0"/>
+//       <w:numId w:val="1"/>  <!-- Old: was numId 1 -->
+//     </w:numPr>
+//   </w:numPrChange>
+// </w:numPr>
+
+var changedNumbering = new NumberingProperties(
+    new NumberingLevelReference { Val = 0 },
+    new NumberingId { Val = 3 },  // New: numId 3
+    new NumberingChange(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 0 },
+            new NumberingId { Val = 1 }  // Old: numId 1
+        )
+    )
+    {
+        Author = "Alice",
+        Date = new DateTime(2026, 3, 22, 13, 0, 0, DateTimeKind.Utc),
+        Id = "13"
+    }
+);
+```
+
+### 4.10 Accepting All Revisions Programmatically
+
+```csharp
+// Accept all revisions: unwrap w:ins (keep content), remove w:del entirely
+public static void AcceptAllRevisions(WordprocessingDocument doc)
+{
+    var body = doc.MainDocumentPart?.Document?.Body;
+    if (body == null) return;
+
+    // Accept insertions: remove w:ins wrapper, keep inner runs
+    var insertions = body.Descendants<InsertedRun>().ToList();
+    foreach (var ins in insertions)
+    {
+        var parent = ins.Parent;
+        if (parent == null) continue;
+        var children = ins.ChildElements.ToList();
+        foreach (var child in children)
+        {
+            child.Remove();
+            parent.InsertBefore(child, ins);
+        }
+        ins.Remove();
+    }
+
+    // Accept deletions: remove entire w:del element
+    var deletions = body.Descendants<DeletedRun>().ToList();
+    foreach (var del in deletions)
+        del.Remove();
+}
+
+// Also accept formatting changes:
+// For w:rPrChange: replace the entire RunProperties with the "old" properties inside the change
+// For w:pPrChange: replace with the old properties
+```
+
+### 4.11 Rejecting All Revisions Programmatically
+
+```csharp
+// Reject all revisions: unwrap w:del (restore text), remove w:ins entirely
+public static void RejectAllRevisions(WordprocessingDocument doc)
+{
+    var body = doc.MainDocumentPart?.Document?.Body;
+    if (body == null) return;
+
+    // Reject insertions: remove entire w:ins element and its content
+    var insertions = body.Descendants<InsertedRun>().ToList();
+    foreach (var ins in insertions)
+        ins.Remove();
+
+    // Reject deletions: unwrap w:del, convert w:delText back to w:t
+    var deletions = body.Descendants<DeletedRun>().ToList();
+    foreach (var del in deletions)
+    {
+        var parent = del.Parent;
+        if (parent == null) continue;
+        foreach (var run in del.Elements<Run>().ToList())
+        {
+            foreach (var delText in run.Elements<DeletedText>().ToList())
+            {
+                var text = new Text(delText.Text) { Space = delText.Space };
+                delText.InsertAfterSelf(text);
+                delText.Remove();
+            }
+            run.Remove();
+            parent.InsertBefore(run, del);
+        }
+        del.Remove();
+    }
+}
+```
+
+### 4.12 MoveFrom / MoveTo — Tracked Text Moving
+
+```csharp
+// MoveFrom (w:moveFrom) marks the origin of moved text
+// MoveTo (w:moveTo) marks the destination
+// Both must have the same w:id
+
+// <w:moveFrom w:id="14" w:author="Alice" w:date="...">
+//   <w:r><w:t>Text that was moved.</w:t></w:r>
+// </w:moveFrom>
+
+// At destination:
+// <w:moveTo w:id="14" w:author="Alice" w:date="...">
+//   <w:r><w:t>Text that was moved.</w:t></w:r>
+// </w:moveTo>
+
+var movedFrom = new MoveFromRun(
+    new Run(new Text("Text that was moved.") { Space = SpaceProcessingModeValues.Preserve })
+)
+{
+    Author = "Alice",
+    Date = new DateTime(2026, 3, 22, 14, 0, 0, DateTimeKind.Utc),
+    Id = "14"
+};
+
+var movedTo = new MoveToRun(
+    new Run(new Text("Text that was moved.") { Space = SpaceProcessingModeValues.Preserve })
+)
+{
+    Author = "Alice",
+    Date = new DateTime(2026, 3, 22, 14, 0, 0, DateTimeKind.Utc),
+    Id = "14"
+};
+```
+
+### 4.13 RevisionId Generation
+
+All revision elements need unique, monotonically increasing integer IDs.
+
+```csharp
+public static int GetNextRevisionId(Body body)
+{
+    int maxId = 0;
+    foreach (var elem in body.Descendants<OpenXmlElement>())
+    {
+        // Check common revision element types for Id attribute
+        var idAttr = elem.GetAttributes()
+            .FirstOrDefault(a => a.LocalName == "id" &&
+                (elem is InsertedRun or DeletedRun or DeletedText or
+                 MoveFromRun or MoveToRun or RunPropertiesChange or
+                 ParagraphPropertiesChange or SectionPropertiesChange or
+                 TableRowInsertionRevision or TableCellInsertionRevision));
+        if (idAttr.Value != null && int.TryParse(idAttr.Value, out int id) && id > maxId)
+            maxId = id;
+    }
+    return maxId + 1;
+}
+
+// Simpler approach: scan all elements with "id" attribute in the document
+public static int GetNextRevisionIdSimple(Body body)
+{
+    int maxId = 0;
+    foreach (var elem in body.Descendants<OpenXmlElement>())
+    {
+        foreach (var attr in elem.GetAttributes())
+        {
+            if (attr.LocalName == "id" && int.TryParse(attr.Value, out int id) && id > maxId)
+                maxId = id;
+        }
+    }
+    return maxId + 1;
+}
+```
+
+---
+
+## 5. Comments (4-File System)
+
+### 5.1 Full 4-File Comment System Setup
+
+Comments require four XML files plus markers in `document.xml`.
+
+```csharp
+// This method creates a complete comment with all 4 files properly initialized
+public static int AddFullComment(
+    WordprocessingDocument doc,
+    string text,
+    string author,
+    string initials,
+    string rangeText,
+    int? existingCommentId = null)
+{
+    var mainPart = doc.MainDocumentPart
+        ?? throw new InvalidOperationException("Document has no MainDocumentPart.");
+
+    int commentId = existingCommentId ?? GetNextCommentId(doc);
+
+    // Generate paraId (8-char hex) and durableId (8-digit hex)
+    string paraId = Guid.NewGuid().ToString("N")[..8].ToUpperInvariant();
+    string durableId = new Random().Next(0x10000000, 0xFFFFFFFF).ToString("X8");
+
+    var body = mainPart.Document!.Body!;
+
+    // ─────────────────────────────────────────────────────────────
+    // FILE 1: word/comments.xml — Main comment content
+    // ─────────────────────────────────────────────────────────────
+    var commentsPart = mainPart.WordprocessingCommentsPart
+        ?? mainPart.AddNewPart<WordprocessingCommentsPart>();
+
+    if (commentsPart.Comments == null)
+        commentsPart.Comments = new Comments();
+
+    // Create a paragraph for the comment with a unique paraId (via w14:paraId)
+    var commentPara = new Paragraph(
+        new ParagraphProperties(
+            new ParagraphStyleId { Val = "CommentText" },
+            // w14:paraId for modern comment threading
+            new乳啜攠嘶嘐呓顾纨asiId { Val = paraId }
+        ),
+        new Run(
+            new RunProperties(new RunStyle { Val = "CommentReference" }),
+            new AnnotationReferenceMark()
+        ),
+        new Run(new Text(text))
+    );
+
+    var comment = new Comment
+    {
+        Id = commentId.ToString(),
+        Author = author,
+        Date = DateTime.UtcNow,
+        Initials = initials
+    };
+    comment.Append(commentPara);
+    commentsPart.Comments.Append(comment);
+    commentsPart.Comments.Save();
+
+    // ─────────────────────────────────────────────────────────────
+    // FILE 2: word/commentsExtended.xml — W15 extensions (paraId, done status)
+    // ─────────────────────────────────────────────────────────────
+    var commentsExPart = mainPart.WordprocessingCommentsExPart
+        ?? mainPart.AddNewPart<WordprocessingCommentsExPart>();
+
+    if (commentsExPart.CommentsEx == null)
+        commentsExPart.CommentsEx = new CommentExCollection();
+
+    // w15:commentEx links the comment to its paragraph and tracks done/resolved
+    var commentEx = new CommentEx
+    {
+        ParaId = new HexBinaryValue(paraId),
+        Done = new OnOffValue(false)  // done="0" = not resolved
+    };
+    commentsExPart.CommentsEx.Append(commentEx);
+    commentsExPart.CommentsEx.Save();
+
+    // ─────────────────────────────────────────────────────────────
+    // FILE 3: word/commentsIds.xml — Persistent ID mapping
+    // ─────────────────────────────────────────────────────────────
+    var commentsIdsPart = mainPart.WordprocessingCommentsIdsPart
+        ?? mainPart.AddNewPart<WordprocessingCommentsIdsPart>();
+
+    if (commentsIdsPart.CommentsIds == null)
+        commentsIdsPart.CommentsIds = new CommentIds();
+
+    // w16cid:commentId maps paraId to a durable (globally unique) ID
+    var commentIdEntry = new CommentId
+    {
+        ParaId = new HexBinaryValue(paraId),
+        DurableId = durableId
+    };
+    commentsIdsPart.CommentsIds.Append(commentIdEntry);
+    commentsIdsPart.CommentsIds.Save();
+
+    // ─────────────────────────────────────────────────────────────
+    // FILE 4: word/commentsExtensible.xml — W16 extensible
+    // ─────────────────────────────────────────────────────────────
+    var commentsExtPart = mainPart.WordprocessingCommentsExtensiblePart
+        ?? mainPart.AddNewPart<WordprocessingCommentsExtensiblePart>();
+
+    if (commentsExtPart.CommentsExtensible == null)
+        commentsExtPart.CommentsExtensible = new CommentExtensibleCollection();
+
+    // w16cex:commentExtensible provides the durable ID with UTC timestamp
+    var extensibleEntry = new CommentExtensible
+    {
+        DurableId = durableId,
+        DateUtc = DateTime.UtcNow
+    };
+    commentsExtPart.CommentsExtensible.Append(extensibleEntry);
+    commentsExtPart.CommentsExtensible.Save();
+
+    // ─────────────────────────────────────────────────────────────
+    // document.xml — Insert range markers around the target text
+    // ─────────────────────────────────────────────────────────────
+    // commentRangeStart and commentRangeEnd bracket the commented text
+    // commentReference is a run containing the visible superscript number
+    var rangeStart = new CommentRangeStart { Id = commentId.ToString() };
+    var rangeEnd = new CommentRangeEnd { Id = commentId.ToString() };
+    var refRun = new Run(
+        new RunProperties(new RunStyle { Val = "CommentReference" }),
+        new CommentReference { Id = commentId.ToString() }
+    );
+
+    // Find the paragraph containing rangeText and insert markers
+    // Simple approach: append at end of body
+    body.Append(rangeStart);
+    body.Append(new Paragraph(new Run(new Text(rangeText))));
+    body.Append(rangeEnd);
+    body.Append(new Paragraph(refRun));  // The comment ref must be in its own paragraph
+
+    return commentId;
+}
+
+// Helper: get next comment ID
+private static int GetNextCommentId(WordprocessingDocument doc)
+{
+    var commentsPart = doc.MainDocumentPart?.WordprocessingCommentsPart;
+    if (commentsPart?.Comments == null) return 1;
+    int max = 0;
+    foreach (var c in commentsPart.Comments.Elements<Comment>())
+        if (c.Id?.Value != null && int.TryParse(c.Id.Value, out int id) && id > max)
+            max = id;
+    return max + 1;
+}
+```
+
+**The 4 files at a glance:**
+
+| File | Part Class | Content | Key Attributes |
+|------|-----------|---------|----------------|
+| `comments.xml` | `WordprocessingCommentsPart` | Comment text | `w:id`, `w:author`, `w:date`, `w:initials` |
+| `commentsExtended.xml` | `WordprocessingCommentsExPart` | W15 extensions | `w15:paraId`, `w15:done` |
+| `commentsIds.xml` | `WordprocessingCommentsIdsPart` | Persistent IDs | `w16cid:paraId`, `w16cid:durableId` |
+| `commentsExtensible.xml` | `WordprocessingCommentsExtensiblePart` | W16 extensible | `w16cex:durableId`, `w16cex:dateUtc` |
+
+### 5.2 Comment Reply (Threaded Comments)
+
+```csharp
+// To add a reply, create a new comment and link it to the parent via commentsExtended.xml
+
+public static int AddCommentReply(
+    WordprocessingDocument doc,
+    int parentCommentId,
+    string replyText,
+    string author,
+    string initials)
+{
+    var mainPart = doc.MainDocumentPart!;
+
+    // Get parent's paraId from commentsExtended.xml
+    var commentsExPart = mainPart.WordprocessingCommentsExPart;
+    var parentParaId = "";
+    if (commentsExPart?.CommentsEx != null)
+    {
+        var parentCommentEx = commentsExPart.CommentsEx
+            .Elements<CommentEx>()
+            .FirstOrDefault(ce =>
+                ce.Parent is Comment c &&
+                c.Id?.Value == parentCommentId.ToString());
+        // Actually need to cross-reference through paraId...
+        // Simpler: look up via comments.xml paraId
+    }
+
+    // Generate new IDs for the reply
+    int replyId = GetNextCommentId(doc);
+    string replyParaId = Guid.NewGuid().ToString("N")[..8].ToUpperInvariant();
+    string durableId = new Random().Next(0x10000000, 0xFFFFFFFF).ToString("X8");
+
+    // Add to comments.xml (new comment with same structure)
+    var commentsPart = mainPart.WordprocessingCommentsPart!;
+    var replyComment = new Comment
+    {
+        Id = replyId.ToString(),
+        Author = author,
+        Date = DateTime.UtcNow,
+        Initials = initials
+    };
+    replyComment.Append(new Paragraph(
+        new ParagraphProperties(new ParagraphStyleId { Val = "CommentText" }),
+        new Run(new RunProperties(new RunStyle { Val = "CommentReference" }), new AnnotationReferenceMark()),
+        new Run(new Text(replyText))
+    ));
+    commentsPart.Comments!.Append(replyComment);
+    commentsPart.Comments.Save();
+
+    // KEY: In commentsExtended.xml, use paraIdParent to link to parent
+    var commentsEx = mainPart.WordprocessingCommentsExPart!;
+    var replyEx = new CommentEx
+    {
+        ParaId = new HexBinaryValue(replyParaId),
+        ParaIdParent = new HexBinaryValue(parentParaId),  // Link to parent
+        Done = new OnOffValue(false)
+    };
+    commentsEx.CommentsEx!.Append(replyEx);
+    commentsEx.CommentsEx.Save();
+
+    // Add to commentsIds.xml and commentsExtensible.xml (same pattern as parent)
+    // ... (same as AddFullComment for these two files)
+
+    // Note: Replies do NOT need range markers in document.xml
+    // They appear threaded under the parent in Word's UI
+
+    return replyId;
+}
+```
+
+### 5.3 Resolving a Comment
+
+```csharp
+// To resolve (mark done), set w15:done="1" in commentsExtended.xml
+public static void ResolveComment(WordprocessingDocument doc, int commentId)
+{
+    var mainPart = doc.MainDocumentPart!;
+
+    // Need to find the paraId for this commentId, then update commentsExtended.xml
+    // Step 1: Get paraId from comments.xml
+    var commentsPart = mainPart.WordprocessingCommentsPart!;
+    var comment = commentsPart.Comments!
+        .Elements<Comment>()
+        .FirstOrDefault(c => c.Id?.Value == commentId.ToString());
+
+    // Find the paragraph and get its paraId
+    string? paraId = null;
+    if (comment != null)
+    {
+        var para = comment.Elements<Paragraph>().FirstOrDefault();
+        var paraIdElem = para?.ParagraphProperties?
+            .Elements<乳啜攠嘶嘐呓顾纨asiId>().FirstOrDefault();
+        paraId = paraIdElem?.Val?.Value;
+    }
+
+    if (paraId == null) return;
+
+    // Step 2: Update commentsExtended.xml
+    var commentsExPart = mainPart.WordprocessingCommentsExPart!;
+    var commentEx = commentsExPart.CommentsEx!
+        .Elements<CommentEx>()
+        .FirstOrDefault(ce => ce.ParaId?.Value == paraId);
+
+    if (commentEx != null)
+        commentEx.Done = new OnOffValue(true);  // Sets done="1"
+
+    commentsExPart.CommentsEx!.Save();
+}
+```
+
+### 5.4 Deleting a Comment (All 4 Files)
+
+```csharp
+// Must remove from all 4 files AND from document.xml
+public static void DeleteComment(WordprocessingDocument doc, int commentId)
+{
+    var mainPart = doc.MainDocumentPart!;
+    string commentIdStr = commentId.ToString();
+
+    // ── Remove from comments.xml ──
+    var commentsPart = mainPart.WordprocessingCommentsPart;
+    if (commentsPart?.Comments != null)
+    {
+        var comment = commentsPart.Comments
+            .Elements<Comment>()
+            .FirstOrDefault(c => c.Id?.Value == commentIdStr);
+        if (comment != null)
+        {
+            // Get paraId before deletion for other files
+            string? paraId = null;
+            var para = comment.Elements<Paragraph>().FirstOrDefault();
+            var paraIdElem = para?.ParagraphProperties?
+                .Elements<乳啜攠嘶嘐呓顾纨asiId>().FirstOrDefault();
+            paraId = paraIdElem?.Val?.Value;
+
+            comment.Remove();
+
+            // ── Remove from commentsExtended.xml ──
+            var commentsExPart = mainPart.WordprocessingCommentsExPart;
+            if (commentsExPart?.CommentsEx != null && paraId != null)
+            {
+                var commentEx = commentsExPart.CommentsEx
+                    .Elements<CommentEx>()
+                    .FirstOrDefault(ce => ce.ParaId?.Value == paraId);
+                commentEx?.Remove();
+                commentsExPart.CommentsEx.Save();
+            }
+
+            // ── Remove from commentsIds.xml ──
+            var commentsIdsPart = mainPart.WordprocessingCommentsIdsPart;
+            if (commentsIdsPart?.CommentsIds != null && paraId != null)
+            {
+                var cidEntry = commentsIdsPart.CommentsIds
+                    .Elements<CommentId>()
+                    .FirstOrDefault(ci => ci.ParaId?.Value == paraId);
+                cidEntry?.Remove();
+                commentsIdsPart.CommentsIds.Save();
+            }
+
+            // ── Remove from commentsExtensible.xml ──
+            // Need to look up by durableId...
+            var commentsExtPart = mainPart.WordprocessingCommentsExtensiblePart;
+            if (commentsExtPart?.CommentsExtensible != null)
+            {
+                // Find by matching durableId (must track separately)
+                var extEntry = commentsExtPart.CommentsExtensible
+                    .Elements<CommentExtensible>()
+                    .FirstOrDefault();  // Match by durableId lookup
+                extEntry?.Remove();
+                commentsExtPart.CommentsExtensible.Save();
+            }
+        }
+    }
+
+    // ── Remove from document.xml ──
+    var body = mainPart.Document!.Body!;
+
+    // Remove CommentRangeStart
+    var rangeStart = body.Descendants<CommentRangeStart>()
+        .FirstOrDefault(crs => crs.Id?.Value == commentIdStr);
+    rangeStart?.Remove();
+
+    // Remove CommentRangeEnd
+    var rangeEnd = body.Descendants<CommentRangeEnd>()
+        .FirstOrDefault(cre => cre.Id?.Value == commentIdStr);
+    rangeEnd?.Remove();
+
+    // Remove CommentReference run (the superscript marker)
+    var commentRefs = body.Descendants<CommentReference>()
+        .Where(cr => cr.Id?.Value == commentIdStr)
+        .ToList();
+    foreach (var cr in commentRefs)
+    {
+        var run = cr.Parent as Run;
+        cr.Remove();
+        run?.Remove();
+    }
+
+    commentsPart?.Comments?.Save();
+}
+```
+
+---
+
+## 6. Images — Deep Dive
+
+### 6.1 Adding an ImagePart (All Image Types)
+
+```csharp
+// All image types supported by AddImagePart:
+void AddImageExamples(MainDocumentPart mainPart, string pngPath, string jpegPath,
+    string gifPath, string svgPath, string bmpPath, string tiffPath)
+{
+    // PNG
+    var pngPart = mainPart.AddImagePart(ImagePartType.Png);
+    using (var s = File.OpenRead(pngPath)) pngPart.FeedData(s);
+    string pngRelId = mainPart.GetIdOfPart(pngPart);
+
+    // JPEG
+    var jpegPart = mainPart.AddImagePart(ImagePartType.Jpeg);
+    using (var s = File.OpenRead(jpegPath)) jpegPart.FeedData(s);
+    string jpegRelId = mainPart.GetIdOfPart(jpegPart);
+
+    // GIF
+    var gifPart = mainPart.AddImagePart(ImagePartType.Gif);
+    using (var s = File.OpenRead(gifPath)) gifPart.FeedData(s);
+    string gifRelId = mainPart.GetIdOfPart(gifPart);
+
+    // SVG (may require additional handling for fallback)
+    var svgPart = mainPart.AddImagePart(ImagePartType.Svg);
+    using (var s = File.OpenRead(svgPath)) svgPart.FeedData(s);
+    string svgRelId = mainPart.GetIdOfPart(svgPart);
+
+    // BMP (stored internally as PNG in OOXML)
+    var bmpPart = mainPart.AddImagePart(ImagePartType.Bmp);
+    using (var s = File.OpenRead(bmpPath)) bmpPart.FeedData(s);
+    string bmpRelId = mainPart.GetIdOfPart(bmpPart);
+
+    // TIFF (similarly converted)
+    var tiffPart = mainPart.AddImagePart(ImagePartType.Tiff);
+    using (var s = File.OpenRead(tiffPath)) tiffPart.FeedData(s);
+    string tiffRelId = mainPart.GetIdOfPart(tiffPart);
+
+    // Also available: ImagePartType.Icon, ImagePartType.Emf, ImagePartType.Wmf
+}
+```
+
+### 6.2 Inline Image (DW.Inline)
+
+Inline images are anchored to a specific character position, not floating.
+
+```csharp
+// Dimensions: widthPx * 9525 EMU = EMU width, heightPx * 9525 EMU = EMU height
+// Assuming 600x400 pixel image at 96dpi:
+//   cx = 600 * 9525 = 5715000 EMU
+//   cy = 400 * 9525 = 3810000 EMU
+
+long cx = (long)(widthInches * 914400);    // From inches to EMU
+long cy = (long)(heightInches * 914400);   // From inches to EMU
+
+// Or from pixels at 96dpi:
+long cxPx = 600, cyPx = 400;
+long cx = cxPx * 9525L;  // 5715000 EMU
+long cy = cyPx * 9525L;  // 3810000 EMU
+
+// Drawing → DW.Inline → A.Graphic → A.GraphicData → PIC.Picture
+var drawing = new Drawing(
+    new DW.Inline(
+        // Extent: defines the image's display size in EMU
+        new DW.Extent { Cx = cx, Cy = cy },
+        // EffectExtent: needed for some effects (set to 0 for basic images)
+        new DW.EffectExtent { EffectExtentL = 0, EffectExtentT = 0, EffectExtentR = 0, EffectExtentB = 0 },
+        // DocProperties: metadata for the image (Id must be unique in document)
+        new DW.DocProperties { Id = 1U, Name = "Image_1", Description = "A sample image" },
+        // NonVisualGraphicFrameDrawingProperties: locks and frame settings
+        new DW.NonVisualGraphicFrameDrawingProperties(
+            new A.GraphicFrameLocks { NoChangeAspect = true }
+        ),
+        // The actual image
+        new A.Graphic(
+            new A.GraphicData(
+                new PIC.Picture(
+                    // Non-visual properties
+                    new PIC.NonVisualPictureProperties(
+                        new PIC.NonVisualDrawingProperties { Id = 0U, Name = "image1" },
+                        new PIC.NonVisualPictureDrawingProperties()
+                    ),
+                    // Fill: how the image is stretched to fill its frame
+                    new PIC.BlipFill(
+                        // Blip: the actual image data reference
+                        new A.Blip { Embed = relId, CompressionState = A.BlipCompressionValues.Print },
+                        // Stretch: how to fill if aspect ratio doesn't match
+                        new A.Stretch(new A.FillRectangle())
+                    ),
+                    // ShapeProperties: transform and geometry
+                    new PIC.ShapeProperties(
+                        new A.Transform2D(
+                            new A.Offset { X = 0L, Y = 0L },
+                            new A.Extents { Cx = cx, Cy = cy }
+                        ),
+                        new A.PresetGeometry(new A.AdjustValueList())
+                        { Preset = A.ShapeTypeValues.Rectangle }
+                    )
+                )
+            ) { Uri = "http://schemas.openxmlformats.org/drawingml/2006/picture" }
+        )
+    )
+    {
+        DistanceFromTop = 0U,
+        DistanceFromBottom = 0U,
+        DistanceFromLeft = 0U,
+        DistanceFromRight = 0U
+    }
+);
+
+// Append to a paragraph
+var para = new Paragraph(new Run(drawing));
+body.Append(para);
+```
+
+### 6.3 Floating / Anchored Image (DW.Anchor)
+
+Floating images have text wrapping and can be positioned relative to page, margin, column, or paragraph.
+
+```csharp
+// DW.Anchor — positioned floating image with text wrapping
+// Key differences from Inline:
+//   - DW.Anchor instead of DW.Inline
+//   - DW.PositionH / DW.PositionV for positioning
+//   - wrapping element (WrapSquare, WrapTight, etc.)
+//   - can have extent on the anchor (effect extent)
+
+var floatingDrawing = new Drawing(
+    new DW.Anchor(
+        // Horizontal positioning
+        new DW.SimplePosition { X = 0L, Y = 0L },  // Offset from anchor point
+        new DW.HorizontalPosition(
+            new DW.PositionOffset((914400L * 2).ToString())  // 2 inches from left
+        )
+        { RelativeFrom = DW.HorizontalRelativePositionValues.Page },
+        // Vertical positioning
+        new DW.VerticalPosition(
+            new DW.PositionOffset((914400L * 3).ToString())  // 3 inches from top
+        )
+        { RelativeFrom = DW.VerticalRelativePositionValues.Page },
+
+        // Image extent (size)
+        new DW.Extent { Cx = cx, Cy = cy },
+        new DW.EffectExtent { EffectExtentL = 0, EffectExtentT = 0, EffectExtentR = 0, EffectExtentB = 0 },
+
+        new DW.DocProperties { Id = 2U, Name = "Floating_Image" },
+        new DW.NonVisualGraphicFrameDrawingProperties(
+            new A.GraphicFrameLocks { NoChangeAspect = true }
+        ),
+
+        // Text wrapping — several options:
+        // WrapSquare: text wraps on all sides (default)
+        // WrapTight: text wraps close to image shape
+        // WrapThrough: text wraps through the image
+        // WrapTopAndBottom: image on its own line, text above and below
+        // WrapNone: image behind/in front of text
+        new DW.WrapSquare { WrapText = DW.WrapTextValues.RightMargin },
+
+        // Layout in table cell (if applicable)
+        new DW.DocPart Gallery { Val = DW.DocPartGalleryValues.Default },
+
+        // Change paragraph that the image is anchored to
+        // Allow the image to move with the paragraph
+        new DW.EditingIndependentFromParagraph { Val = false },
+
+        // Horizontal anchor: anchor to character/column/margin/page
+        new DW.HorizontalAnchor { Val = DW.HorizontalAnchorValues.Page },
+        // Vertical anchor: anchor to character/line/margin/page/paragraph
+        new DW.VerticalAnchor { Val = DW.VerticalAnchorValues.Page },
+
+        // Alignment (if using alignment-based positioning)
+        new DW.Aligned { Horizontal = DW.HorizontalAlignmentValues.Left,
+                         Vertical = DW.VerticalAlignmentValues.Top },
+
+        new A.Graphic(...)
+    )
+    {
+        // Anchor lock: prevents moving in Word UI
+        EditId = "1A2B3C",
+        BehindDoc = false,  // true = behind text, false = in front
+        Locked = false,
+        LayoutInCell = true,  // Allow layout inside table cells
+        AllowOverlap = true   // Allow overlap with other floating elements
+    }
+);
+```
+
+### 6.4 Text Wrapping Options
+
+```csharp
+// WrapSquare — text surrounds on all sides
+new DW.WrapSquare { WrapText = DW.WrapTextValues.RightMargin }
+
+// WrapTight — text follows contour of image (if shape has custom geometry)
+new DW.WrapTight { WrapText = DW.WrapTextValues.LeftMargin }
+
+// WrapThrough — text intermingles with image
+new DW.WrapThrough(
+    new DW.WrapTextValues.LeftMargin,  // Text on left
+    new DW.WrapTextValues.RightMargin   // Text on right
+)
+
+// WrapTopAndBottom — image on own line
+new DW.WrapTopAndBottom()
+
+// WrapNone — image is at anchor position, text overlays (or vice versa)
+new DW.WrapNone()
+
+// Behind document text:
+var anchor = new DW.Anchor(...){ BehindDoc = true, Locked = false };
+```
+
+### 6.5 Image Sizing — EMU Calculations
+
+```csharp
+// EMU reference:
+//   1 inch = 914400 EMU
+//   1 cm   = 360000 EMU
+//   1 pixel at 96dpi = 9525 EMU
+//   1 pixel at 72dpi = 635 EMU (point, not EMU)
+
+public static class ImageSizing
+{
+    // From pixel dimensions at given DPI
+    public static (long cx, long cy) FromPixels(int widthPx, int heightPx, int dpi = 96)
+    {
+        long emuPerPixel = 914400L / dpi;  // ~9525 at 96dpi
+        return (widthPx * emuPerPixel, heightPx * emuPerPixel);
+    }
+
+    // From inches
+    public static (long cx, long cy) FromInches(double widthIn, double heightIn)
+    {
+        return ((long)(widthIn * 914400), (long)(heightIn * 914400));
+    }
+
+    // From centimeters
+    public static (long cx, long cy) FromCentimeters(double widthCm, double heightCm)
+    {
+        return ((long)(widthCm * 360000), (long)(heightCm * 360000));
+    }
+
+    // Maintain aspect ratio given a target width
+    public static (long cx, long cy) ScaleToWidth(long originalCx, long originalCy, long targetCx)
+    {
+        double ratio = (double)originalCy / originalCx;
+        return (targetCx, (long)(targetCx * ratio));
+    }
+
+    // Common photo sizes in inches: 4x6, 5x7, 8x10
+    public static (long cx, long cy) PhotoSize4x6()
+        => FromInches(4, 6);
+
+    public static (long cx, long cy) PhotoSize5x7()
+        => FromInches(5, 7);
+
+    public static (long cx, long cy) PhotoSize8x10()
+        => FromInches(8, 10);
+}
+```
+
+### 6.6 Image with Border
+
+```csharp
+// Add border to image via PIC.ShapeProperties → A.Outline
+new PIC.ShapeProperties(
+    new A.Transform2D(
+        new A.Offset { X = 0L, Y = 0L },
+        new A.Extents { Cx = cx, Cy = cy }
+    ),
+    new A.PresetGeometry(new A.AdjustValueList())
+    { Preset = A.ShapeTypeValues.Rectangle },
+    // The border/outline
+    new A.Outline(
+        new A.SolidFill(new A.RgbColorModelHex { Val = "000000" }),
+        new A.PresetDash { Val = A.PresetLineDashValues.Solid }
+    )
+    { Width = 12700 }  // 12700 EMU = 1pt, so 25400 = 2pt
+);
+```
+
+### 6.7 Image with Alt Text (DocProperties.Description)
+
+```csharp
+// Alt text is set via DocProperties.Description
+// Also accessible via Picture's alternative text in Word UI
+
+new DW.DocProperties
+{
+    Id = 1U,
+    Name = "Chart showing growth",
+    Description = "Bar chart showing quarterly revenue growth from Q1 to Q4 2025"
+    // Title is also available but Description is what Word shows as alt text
+};
+
+// Also set via A.Descriptive (for some image types)
+```
+
+### 6.8 Image in Header / Footer
+
+```csharp
+// Images in headers/footers work the same as in body, just on the respective part
+var headerPart = mainPart.AddNewPart<HeaderPart>();
+
+// Logo in header
+var logoDrawing = new Drawing(
+    new DW.Inline(
+        new DW.Extent { Cx = 914400L, Cy = 457200L },  // 1" x 0.5" logo
+        new DW.EffectExtent(),
+        new DW.DocProperties { Id = 1U, Name = "HeaderLogo" },
+        new DW.NonVisualGraphicFrameDrawingProperties(
+            new A.GraphicFrameLocks { NoChangeAspect = true }),
+        new A.Graphic(
+            new A.GraphicData(
+                new PIC.Picture(
+                    new PIC.NonVisualPictureProperties(
+                        new PIC.NonVisualDrawingProperties { Id = 0U, Name = "logo" },
+                        new PIC.NonVisualPictureDrawingProperties()),
+                    new PIC.BlipFill(
+                        new A.Blip { Embed = headerLogoRelId },
+                        new A.Stretch(new A.FillRectangle())),
+                    new PIC.ShapeProperties(
+                        new A.Transform2D(
+                            new A.Offset { X = 0L, Y = 0L },
+                            new A.Extents { Cx = 914400L, Cy = 457200L }),
+                        new A.PresetGeometry(new A.AdjustValueList())
+                        { Preset = A.ShapeTypeValues.Rectangle }))
+                )
+            ) { Uri = "http://schemas.openxmlformats.org/drawingml/2006/picture" }
+        )
+    )
+    { DistanceFromTop = 0U, DistanceFromBottom = 0U,
+      DistanceFromLeft = 0U, DistanceFromRight = 0U }
+);
+
+headerPart.Header = new Header(
+    new Paragraph(
+        new ParagraphProperties(
+            new Justification { Val = JustificationValues.Right }),
+        new Run(logoDrawing)
+    )
+);
+```
+
+### 6.9 Image in Table Cell
+
+```csharp
+// Images in table cells use the same patterns
+// With inline: works fine within cell
+// With floating/anchor: set LayoutInCell = true
+
+var cellWithImage = new TableCell(
+    new TableCellProperties(
+        new TableCellWidth { Width = 2000, Type = TableWidthUnitValues.Dxa }
+    ),
+    new Paragraph(
+        new Run(
+            new Drawing(
+                new DW.Inline(
+                    new DW.Extent { Cx = 914400L, Cy = 914400L },  // 1"x1"
+                    new DW.EffectExtent(),
+                    new DW.DocProperties { Id = 5U, Name = "CellImage" },
+                    new DW.NonVisualGraphicFrameDrawingProperties(
+                        new A.GraphicFrameLocks { NoChangeAspect = true }),
+                    new A.Graphic(
+                        new A.GraphicData(
+                            new PIC.Picture(...)
+                        ) { Uri = "..." }
+                    )
+                )
+                { DistanceFromTop = 0U, DistanceFromBottom = 0U,
+                  DistanceFromLeft = 0U, DistanceFromRight = 0U }
+            )
+        )
+    )
+);
+```
+
+### 6.10 Replacing an Image (Update Blip.Embed)
+
+```csharp
+// To replace an existing image, update the Blip's Embed relationship ID
+// 1. Get the existing image's relationship ID from Blip.Embed
+// 2. Replace the image data in that ImagePart with new data
+// 3. Keep the same relationship ID (so all references remain valid)
+
+public static void ReplaceImage(WordprocessingDocument doc, string newImagePath)
+{
+    var mainPart = doc.MainDocumentPart!;
+    var body = mainPart.Document!.Body!;
+
+    foreach (var drawing in body.Descendants<Drawing>())
+    {
+        // Look for inline or anchor images
+        var inline = drawing.Descendants<DW.Inline>().FirstOrDefault();
+        var anchor = drawing.Descendants<DW.Anchor>().FirstOrDefault();
+
+        var blipFill = (inline ?? anchor as OpenXmlElement)?
+            .Descendants<PIC.BlipFill>().FirstOrDefault();
+
+        if (blipFill == null) continue;
+
+        var blip = blipFill.Blip;
+        if (blip?.Embed == null) continue;
+
+        string relId = blip.Embed.Value!;
+
+        // Get the existing ImagePart
+        if (mainPart.GetPartById(relId) is ImagePart existingImagePart)
+        {
+            // Replace the data
+            using (var newData = File.OpenRead(newImagePath))
+                existingImagePart.FeedData(newData);
+            return;  // Replace first found, or loop for all
+        }
+    }
+}
+```
+
+### 6.11 SVG with PNG Fallback (SvgBlip)
+
+```csharp
+// SVG images use SvgBlip for modern Word apps, with PNG fallback for older versions
+// This is handled through the package structure — Word picks the best supported format
+
+// SVG stored as ImagePartType.Svg, but rendered via BlipFill with extension:
+// <a:blip xmlns:a="..." r:embed="rId...">
+//   <a:extLst>
+//     <a:ext uri="http://schemas.openxmlformats.org/drawingml/2006/svg">
+//       <asvg:svg xmlns:asvg="..."/>  <!-- SVG-specific data -->
+//     </a:ext>
+//   </a:extLst>
+// </a:blip>
+
+var svgImagePart = mainPart.AddImagePart(ImagePartType.Svg);
+using (var s = File.OpenRead("chart.svg")) svgImagePart.FeedData(s);
+string svgRelId = mainPart.GetIdOfPart(svgImagePart);
+
+// Word automatically handles SVG→PNG fallback in older versions
+// No explicit fallback needed in code — the document format handles it
+
+// Note: SvgBlip class in SDK 3.x provides direct support
+new A.SvgBlip { Embed = svgRelId };
+```
+
+---
+
+## 7. Drawing Shapes (Non-Image)
+
+### 7.1 WordprocessingShape — Basic Shapes (wsp)
+
+WordprocessingShape uses the `wps` namespace for Word's built-in shape library.
+
+```csharp
+// Shapes require:
+// - MainDocumentPart.AddNewPart<WordprocessingShapePart>() or
+// - Embedded via DrawingML inside a Drawing element
+// The most common approach is embedding shapes directly in a Drawing element
+
+// Shapes in WordprocessingDrawing are placed like images (inline or anchored)
+var shapeDrawing = new Drawing(
+    new DW.Inline(
+        new DW.Extent { Cx = 1714500L, Cy = 914400L },  // 1.875" x 1" rectangle
+        new DW.EffectExtent(),
+        new DW.DocProperties { Id = 10U, Name = "Rectangle 1" },
+        new DW.NonVisualGraphicFrameDrawingProperties(
+            new A.GraphicFrameLocks()),
+        // The shape itself
+        new A.Graphic(
+            new A.GraphicData(
+                // WordprocessingShape = wsp:wsp (rectangle, roundedRect, ellipse, etc.)
+                new WSP.WordprocessingShape(
+                    // Non-visual properties
+                    new WSP.NonVisualDrawingShapeProperties(
+                        new A.ShapeLocks { NoChangeAspect = true }
+                    ),
+                    // Shape properties (fill, outline, geometry)
+                    new WSP.ShapeProperties(
+                        new A.Transform2D(
+                            new A.Offset { X = 0L, Y = 0L },
+                            new A.Extents { Cx = 1714500L, Cy = 914400L }
+                        ),
+                        // PresetGeometry determines the shape type
+                        new A.PresetGeometry(new A.AdjustValueList())
+                        {
+                            Preset = A.ShapeTypeValues.Rectangle
+                            // Other values: RoundedRectangle, Ellipse, Triangle, etc.
+                        },
+                        // Fill color (solid)
+                        new A.SolidFill(
+                            new A.RgbColorModelHex { Val = "4472C4" }
+                        ),
+                        // Outline
+                        new A.Outline(
+                            new A.NoFill()  // No outline
+                            // Or: new A.SolidFill(new A.RgbColorModelHex { Val = "000000" })
+                            // { Width = 12700 } for 1pt border
+                        )
+                    ),
+                    // Text box content
+                    new WSP.TextBoxInfo2(
+                        new TextBoxContent(
+                            new Paragraph(
+                                new ParagraphProperties(
+                                    new Justification { Val = JustificationValues.Center }),
+                                new Run(
+                                    new RunProperties(
+                                        new Color { Val = "FFFFFF" },
+                                        new Bold()),
+                                    new Text("Hello World"))
+                            )
+                        )
+                    )
+                )
+            ) { Uri = "http://schemas.microsoft.com/office/word/2010/wordprocessingShape" }
+        )
+    )
+    { DistanceFromTop = 0U, DistanceFromBottom = 0U,
+      DistanceFromLeft = 0U, DistanceFromRight = 0U }
+);
+```
+
+**Preset shape types (`A.ShapeTypeValues`):**
+- `Rectangle`, `RoundedRectangle`, `Ellipse`, `Triangle`, `RightTriangle`
+- `Parallelogram`, `Trapezoid`, `Pentagon`, `Hexagon`, `Octagon`
+- `Star4`, `Star5`, `Star6`, `Star8`, `Star10`, `Star12`
+- `Heart`, `ArrowRight`, `ArrowLeft`, `ArrowUp`, `ArrowDown`
+- `Callout1`, `Callout2`, `Callout3` (with tail)
+- `FlowChartProcess`, `FlowChartDecision`, `FlowChartDocument`
+
+### 7.2 Shape with Gradient Fill
+
+```csharp
+new WSP.ShapeProperties(
+    new A.Transform2D(...),
+    new A.PresetGeometry(new A.AdjustValueList())
+    { Preset = A.ShapeTypeValues.RoundedRectangle },
+    // Gradient fill
+    new A.GradientFill(
+        new A.LinearGradientFill(
+            new A.Stop { Offset = "0", Color = new A.RgbColorModelHex { Val = "4472C4" } },
+            new A.Stop { Offset = "100000", Color = new A.RgbColorModelHex { Val = "2F5496" } }
+        )
+        { Rotation = 5400000 }  // 54° = diagonal
+    )
+    // OR: A.RadialGradientFill for radial gradient
+);
+```
+
+### 7.3 Shape Positioning (Anchored)
+
+```csharp
+// Anchored (floating) shapes use DW.Anchor with the shape inside
+var anchoredShape = new Drawing(
+    new DW.Anchor(
+        new DW.SimplePosition { X = 0L, Y = 0L },
+        new DW.HorizontalPosition(
+            new DW.PositionOffset((914400L * 1).ToString()))  // 1 inch from left
+        { RelativeFrom = DW.HorizontalRelativePositionValues.Margin },
+        new DW.VerticalPosition(
+            new DW.PositionOffset((914400L * 2).ToString()))  // 2 inches from top
+        { RelativeFrom = DW.VerticalRelativePositionValues.Page },
+        new DW.Extent { Cx = 914400L, Cy = 914400L },
+        new DW.EffectExtent(),
+        new DW.DocProperties { Id = 11U, Name = "AnchoredShape" },
+        new DW.NonVisualGraphicFrameDrawingProperties(new A.GraphicFrameLocks()),
+        new DW.WrapSquare(),
+        new A.Graphic(new A.GraphicData(
+            new WSP.WordprocessingShape(...)
+        ) { Uri = "http://schemas.microsoft.com/office/word/2010/wordprocessingShape" })
+    )
+    { BehindDoc = false, LayoutInCell = true }
+);
+```
+
+### 7.4 Grouped Shapes (GroupShape)
+
+```csharp
+// GroupShape combines multiple shapes into one manipulable unit
+// Uses a different URI: "http://schemas.microsoft.com/office/word/2010/wordprocessingGroupShape"
+
+var groupShapeDrawing = new Drawing(
+    new DW.Inline(
+        new DW.Extent { Cx = 4572000L, Cy = 2286000L },  // 5" x 2.5"
+        new DW.EffectExtent(),
+        new DW.DocProperties { Id = 12U, Name = "Shape Group" },
+        new DW.NonVisualGraphicFrameDrawingProperties(new A.GraphicFrameLocks()),
+        new A.Graphic(
+            new A.GraphicData(
+                new WPG.GroupShape(
+                    // Child shapes are positioned relative to group origin
+                    // Shape 1 at (0,0)
+                    new WSP.WordprocessingShape(
+                        new WSP.NonVisualDrawingShapeProperties(
+                            new A.ShapeLocks { NoChangeAspect = true }),
+                        new WSP.ShapeProperties(
+                            new A.Transform2D(
+                                new A.Offset { X = 0L, Y = 0L },
+                                new A.Extents { Cx = 914400L, Cy = 914400L }),
+                            new A.PresetGeometry(new A.AdjustValueList())
+                            { Preset = A.ShapeTypeValues.Ellipse },
+                            new A.SolidFill(new A.RgbColorModelHex { Val = "FF0000" })),
+                        new WSP.TextBoxInfo2(
+                            new TextBoxContent(new Paragraph(
+                                new Run(new Text("Red Circle")))))
+                    ),
+                    // Shape 2 offset to the right
+                    new WSP.WordprocessingShape(
+                        new WSP.NonVisualDrawingShapeProperties(
+                            new A.ShapeLocks { NoChangeAspect = true }),
+                        new WSP.ShapeProperties(
+                            new A.Transform2D(
+                                new A.Offset { X = 914400L, Y = 0L },  // 1" to the right
+                                new A.Extents { Cx = 914400L, Cy = 914400L }),
+                            new A.PresetGeometry(new A.AdjustValueList())
+                            { Preset = A.ShapeTypeValues.Rectangle },
+                            new A.SolidFill(new A.RgbColorModelHex { Val = "00FF00" })),
+                        new WSP.TextBoxInfo2(
+                            new TextBoxContent(new Paragraph(
+                                new Run(new Text("Green Square")))))
+                    )
+                )
+            ) { Uri = "http://schemas.microsoft.com/office/word/2010/wordprocessingGroupShape" }
+        )
+    )
+    { DistanceFromTop = 0U, DistanceFromBottom = 0U,
+      DistanceFromLeft = 0U, DistanceFromRight = 0U }
+);
+```
+
+### 7.5 Shape Effects — Shadow, Reflection
+
+```csharp
+// Shadow effect
+new WSP.ShapeProperties(
+    new A.Transform2D(...),
+    new A.PresetGeometry(new A.AdjustValueList())
+    { Preset = A.ShapeTypeValues.RoundedRectangle },
+    new A.SolidFill(new A.RgbColorModelHex { Val = "4472C4" }),
+    // Shadow via EffectList
+    new A.EffectList(
+        new A.OuterShadow(
+            new A.RgbColorModelHex { Val = "000000" }
+        )
+        {
+            BlurRadius = 50800L,   // 4pt blur (50800 EMU = 4pt at 12700EMU/pt)
+            Distance = 38100L,     // 3pt offset
+            Direction = 2700000,   // 45° (in 60000ths of a degree)
+            Alignment = A.RectangleAlignmentValues.BottomRight
+        }
+    )
+);
+
+// Reflection
+new A.EffectList(
+    new A.Reflection(
+        new A.ReflectionEffect()
+        {
+            ReflectionBlurRadius = 63500L,  // 5pt
+            ReflectionDistance = 76200L,     // 6pt
+            ReflectionFade = 50000,         // 50% fade
+            ReflectionOverlap = 25000       // 25% overlap
+        }
+    )
+);
+```
+
+---
+
+## 8. Math / Equations (OMML)
+
+### 8.1 OfficeMath Container — Basic Setup
+
+```csharp
+// All math equations must be inside an OfficeMath container
+// OfficeMath can be inline (in a run) or display (in its own paragraph)
+
+// Inline equation in a run
+var inlineMathPara = new Paragraph(
+    new Run(
+        new RunProperties(new RunFonts { Ascii = "Cambria Math", HighAnsi = "Cambria Math" }),
+        // Inline math: use OfficeMath directly in Run
+        new OfficeMath(
+            new M.Fraction(
+                new M.Numerator(
+                    new M.Run(new M.Text("1"))
+                ),
+                new M.Denominator(
+                    new M.Run(new M.Text("2"))
+                )
+            )
+        )
+    )
+);
+
+// Display equation (on its own centered paragraph)
+var displayMathPara = new Paragraph(
+    new ParagraphProperties(
+        new Justification { Val = JustificationValues.Center }
+    ),
+    new Run(
+        new OfficeMath(
+            new M.Fraction(
+                new M.Numerator(
+                    new M.Run(new M.Text("x"))
+                ),
+                new M.Denominator(
+                    new M.Run(new M.Text("y"))
+                )
+            )
+        )
+    )
+);
+
+// To make a display equation centered with extra spacing:
+var displayEquationPara = new Paragraph(
+    new ParagraphProperties(
+        new SpacingBetweenLines { Before = "240", After = "240" },
+        new Justification { Val = JustificationValues.Center }
+    ),
+    new Run(new OfficeMath(
+        // Equation content here
+    ))
+);
+```
+
+### 8.2 Fraction (M.Fraction)
+
+```csharp
+// \frac{x}{y} pattern
+new M.Fraction(
+    new M.Numerator(
+        new M.Run(
+            new M.RunText("x") { Space = SpaceProcessingModeValues.Preserve }
+        )
+    ),
+    new M.Denominator(
+        new M.Run(
+            new M.RunText("y") { Space = SpaceProcessingModeValues.Preserve }
+        )
+    )
+);
+
+// Nested fraction: (a+b)/(c+d)
+new M.Fraction(
+    new M.Numerator(
+        new M.Run(new M.Text("a")) { FontSize = 24 },
+        new M.Run(new M.Text("+")) { FontSize = 24 },
+        new M.Run(new M.Text("b")) { FontSize = 24 }
+    ),
+    new M.Denominator(
+        new M.Run(new M.Text("c")) { FontSize = 24 },
+        new M.Run(new M.Text("+")) { FontSize = 24 },
+        new M.Run(new M.Text("d")) { FontSize = 24 }
+    )
+);
+
+// Display fraction (skips 1 as numerator/denominator style)
+new M.Fraction(
+    new M.Numerator(...),
+    new M.Denominator(...),
+    new M.FractionPr(
+        new M.Type { Val = M.FractionValues.Skewed }  // or Normal, Linear,丝
+    )
+);
+```
+
+### 8.3 Superscript and Subscript
+
+```csharp
+// Superscript: x²
+new M.Superscript(
+    new M.Base(
+        new M.Run(new M.Text("x")))
+    ),
+    new M.SuperscriptOperand(
+        new M.Run(new M.Text("2")))
+    )
+);
+
+// Subscript: x₁
+new M.Subscript(
+    new M.Base(
+        new M.Run(new M.Text("x")))
+    ),
+    new M.SubscriptOperand(
+        new M.Run(new M.Text("1")))
+    )
+);
+
+// Pre-sub/superscript: _b^a (baseline then super)
+// or use M.SubscriptSuperscript for combined
+
+// SubscriptSuperscript (both at once): _b^a C
+new M.SubscriptSuperscript(
+    new M.Base(new M.Run(new M.Text("C"))),
+    new M.Subscript(new M.Run(new M.Text("b"))),
+    new M.Superscript(new M.Run(new M.Text("a")))
+);
+```
+
+### 8.4 Square Root and Nth Root
+
+```csharp
+// Square root: √x
+new M.Radical(
+    new M.Root(
+        new M.Run(new M.Text("x")))
+    )
+);
+
+// Square root with degree hidden (just √)
+new M.Radical(
+    new M.Root(
+        new M.Run(new M.Text("x")))
+    ),
+    new M.RadicalPr(
+        new M.Degree { Val = false }  // Hide the root index
+    )
+);
+
+// Nth root: ∛(x+1)  — cube root of (x+1)
+new M.Radical(
+    new M.Root(
+        new M.Fraction(
+            new M.Numerator(new M.Run(new M.Text("1"))),
+            new M.Denominator(new M.Run(new M.Text("3")))
+        )
+    ),  // This is the "3" for cube root
+    new M.Root(
+        new M.Run(new M.Text("x"))),
+        new M.Run(new M.Text("+"))),
+        new M.Run(new M.Text("1")))
+    )
+);
+// Actually, for nth root: first Root is the index (degree), second is the radicand
+new M.Radical(
+    new M.Root(new M.Run(new M.Text("3"))),  // The index: 3rd root
+    new M.Root(
+        new M.Run(new M.Text("x")),
+        new M.Run(new M.Text("+")),
+        new M.Run(new M.Text("1"))
+    )
+);
+```
+
+### 8.5 N-ary Operators — Integral, Summation, Product
+
+```csharp
+// Integral ∫ from a to b of f(x) dx
+new M.Nary(
+    new M.NaryProperties(
+        new M.NaryType { Val = M.NaryValues.Integral }  // ∫
+    )
+    {
+        SubSuperscript = M.SubSuperscriptValues.NoSubSuperscript
+    },
+    new M.Base(
+        new M.Run(new M.Text("f(x)")))
+    ),
+    new M.Subscript(
+        new M.Run(new M.Text("a")))
+    ),
+    new M.Superscript(
+        new M.Run(new M.Text("b")))
+    )
+);
+
+// Summation Σ from i=1 to n of i²
+new M.Nary(
+    new M.NaryProperties(
+        new M.NaryType { Val = M.NaryValues.Sum },  // Σ
+        new M.GrowBindings = true
+    ),
+    new M.Base(
+        new M.SubscriptSuperscript(
+            new M.Base(new M.Run(new M.Text("i"))),
+            new M.Subscript(new M.Run(new M.Text("1"))),
+            new M.Superscript(new M.Run(new M.Text("n")))
+        )
+    ),
+    new M.Subscript(
+        new M.Run(new M.Text("i")))
+    ),
+    new M.Superscript(
+        new M.Run(new M.Text("2")))
+    )
+);
+
+// Product ∏ from i=1 to n
+new M.Nary(
+    new M.NaryProperties(
+        new M.NaryType { Val = M.NaryValues.Product }  // ∏
+    ),
+    new M.Base(
+        new M.SubscriptSuperscript(
+            new M.Base(new M.Run(new M.Text("i"))),
+            new M.Subscript(new M.Run(new M.Text("1"))),
+            new M.Superscript(new M.Run(new M.Text("n")))
+        )
+    ),
+    new M.Subscript(
+        new M.Run(new M.Text("i")))
+    ),
+    new M.Superscript(
+        new M.Run(new M.Text("2")))
+    )
+);
+
+// N-ary type values: Integral, Sum, Product, Union, Intersection, etc.
+```
+
+### 8.6 Matrix
+
+```csharp
+// 2x2 matrix
+// [a  b]
+// [c  d]
+new M.Matrix(
+    new M.MatrixRows(
+        // Row 1
+        new M.MatrixRow(
+            new M.MatrixCell(
+                new M.Run(new M.Text("a"))
+            ),
+            new M.MatrixCell(
+                new M.Run(new M.Text("b"))
+            )
+        ),
+        // Row 2
+        new M.MatrixRow(
+            new M.MatrixCell(
+                new M.Run(new M.Text("c"))
+            ),
+            new M.MatrixCell(
+                new M.Run(new M.Text("d"))
+            )
+        )
+    ),
+    new M.MatrixProperties(
+        new M.Jc { Val = M.JustificationValues.Center },  // Centered
+        new M.Structure { Val = M.MathStructureValues.SinglePUNCT },
+        new M.RowSpacing { Val = 120 },  // Row spacing in twips
+        new M.RowSpacing1 { Val = 120 }
+    )
+)
+```
+
+### 8.7 Delimiter (Parentheses/Brackets/Braces)
+
+```csharp
+// (a + b) or [a + b] or {a + b}
+new M.Delimiter(
+    new M.DelimiterProperties(
+        new M.Begin(new M.Text("(")),  // Opening char
+        new M.End(new M.Text(")")),   // Closing char
+        new M.Separator(new M.Text(",")),  // Separator between elements
+        new M.Structure { Val = M.MathStructureValues.Minimal }
+    ),
+    new M.DelimiterContents(
+        new M.Run(new M.Text("a")),
+        new M.Run(new M.Text("+")),
+        new M.Run(new M.Text("b"))
+    )
+);
+
+// {a, b, c} with curly braces
+new M.Delimiter(
+    new M.DelimiterProperties(
+        new M.Begin(new M.Text("{")),
+        new M.End(new M.Text("}")),
+        new M.Separator(new M.Text(","))
+    ),
+    new M.DelimiterContents(
+        new M.Run(new M.Text("a")),
+        new M.Run(new M.Text("b")),
+        new M.Run(new M.Text("c"))
+    )
+);
+
+// 2x2 matrix in parentheses
+new M.Delimiter(
+    new M.DelimiterProperties(
+        new M.Begin(new M.Text("(")),
+        new M.End(new M.Text(")"))
+    ),
+    new M.DelimiterContents(
+        // Inline 2x2 using subscripts
+        new M.SubscriptSuperscript(...)
+    )
+);
+```
+
+### 8.8 Equation Array (Aligned Equations)
+
+```csharp
+// EquationArray (M.EquationArray) creates a series of equations aligned at markers
+// Like \begin{align} in LaTeX
+
+new M.EquationArray(
+    new M.EquationArrayProperties(
+        new M.Jc { Val = M.JustificationValues.Left },
+        new M.RowSpacing { Val = 240 },
+        new M.RowSpacing1 { Val = 240 }
+    ),
+    // Each equation is a Paragraph inside the array
+    new Paragraph(new Run(new M.Text("x") { Space = SpaceProcessingModeValues.Preserve })),
+    new Paragraph(
+        new Run(new M.Text("+") { Space = SpaceProcessingModeValues.Preserve }),
+        new Run(new M.Text("y") { Space = SpaceProcessingModeValues.Preserve }),
+        new Run(new M.Text("=") { Space = SpaceProcessingModeValues.Preserve }),
+        new Run(new M.Text("z") { Space = SpaceProcessingModeValues.Preserve })
+    )
+);
+
+// Or use M.Break with AlignmentTab for manual alignment points
+```
+
+### 8.9 Greek Letters and Math Symbols
+
+```csharp
+// Greek letters via M.RunText with Symbol font or Unicode
+// Common Greek letters and their uses:
+
+// α (alpha)
+new M.Run(new M.Text("\u03B1"))  // or use Unicode directly
+
+// β (beta)
+new M.Run(new M.Text("\u03B2"))
+
+// γ (gamma)
+new M.Run(new M.Text("\u03B3"))
+
+// π (pi) — use Greek small letter pi
+new M.Run(new M.Text("\u03C0"))
+
+// σ (sigma)
+new M.Run(new M.Text("\u03C3"))
+
+// Σ (Sigma, capital) — summation symbol
+new M.Run(new M.Text("\u03A3"))
+
+// θ (theta)
+new M.Run(new M.Text("\u03B8"))
+
+// ∞ (infinity)
+new M.Run(new M.Text("\u221E"))
+
+// ≤ (less than or equal)
+new M.Run(new M.Text("\u2264"))
+
+// ≥ (greater than or equal)
+new M.Run(new M.Text("\u2265"))
+
+// ≠ (not equal)
+new M.Run(new M.Text("\u2260"))
+
+// ± (plus-minus)
+new M.Run(new M.Text("\u00B1"))
+
+// × (multiplication)
+new M.Run(new M.Text("\u00D7"))
+
+// ÷ (division)
+new M.Run(new M.Text("\u00F7"))
+
+// For best results, set the font to "Cambria Math" on math runs
+new M.Run(
+    new RunFonts { Ascii = "Cambria Math", HighAnsi = "Cambria Math" },
+    new M.Text("\u03C0")
+)
+```
+
+---
+
+## 9. Numbering System — Deep Dive
+
+### 9.1 Architecture Overview
+
+```
+NumberingDefinitionsPart (numbering.xml)
+    └── <w:numbering>
+        ├── <w:abstractNum>  (templates)
+        │     ├── <w:lvl> × 9 (levels 0-8)
+        │     └── <w:pPr><w:numPr> links to this abstractNum
+        └── <w:num> (instances)
+              └── <w:abstractNumId val="N"/>
+```
+
+**Key rule**: `AbstractNum` must appear BEFORE `NumberingInstance` in the XML root.
+
+### 9.2 AbstractNum with Multi-Level Decimal Numbering
+
+```csharp
+// AbstractNum: the numbering template (what it looks like)
+// NumberingInstance: a specific use of that template (how it's applied)
+
+var numberingPart = mainPart.AddNewPart<NumberingDefinitionsPart>();
+var numbering = new Numbering();
+
+// ─────────────────────────────────────────────────────────────
+// Step 1: Define AbstractNum (the template)
+// ─────────────────────────────────────────────────────────────
+var abstractNum = new AbstractNum { AbstractNumberId = 1 };
+// MultiLevelType specifies this is a multi-level list
+abstractNum.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
+
+// Level 0: "1." — decimal, bold number
+abstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "%1." },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "360", Hanging = "360" }  // 0.25" hanging indent
+    ),
+    new NumberingSymbolRunProperties(
+        new Bold(),
+        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
+        new Color { Val = "2F5496" }
+    )
+) { LevelIndex = 0 });
+
+// Level 1: "1.1." — indent 0.5"
+abstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "%1.%2." },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "720", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" }
+    )
+) { LevelIndex = 1 });
+
+// Level 2: "1.1.1."
+abstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "%1.%2.%3." },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "1080", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" }
+    )
+) { LevelIndex = 2 });
+
+// ─────────────────────────────────────────────────────────────
+// Step 2: Create NumberingInstance (a reference to the template)
+// ─────────────────────────────────────────────────────────────
+var numInstance = new NumberingInstance(
+    new AbstractNumId { Val = 1 }  // Points to abstractNum above
+) { NumberID = 1 };
+
+// ─────────────────────────────────────────────────────────────
+// Step 3: Assemble — AbstractNum BEFORE NumberingInstance!
+// ─────────────────────────────────────────────────────────────
+numbering.Append(abstractNum);
+numbering.Append(numInstance);
+numberingPart.Numbering = numbering;
+numberingPart.Numbering.Save();
+
+// ─────────────────────────────────────────────────────────────
+// Step 4: Apply to a paragraph
+// ─────────────────────────────────────────────────────────────
+var numberedPara = new Paragraph(
+    new ParagraphProperties(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 0 },  // Use level 0 of numId 1
+            new NumberingId { Val = 1 }                // Use numbering instance 1
+        )
+    ),
+    new Run(new Text("First item"))
+);
+
+// For level 1 sub-item:
+var subItemPara = new Paragraph(
+    new ParagraphProperties(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 1 },  // Use level 1
+            new NumberingId { Val = 1 }
+        )
+    ),
+    new Run(new Text("Sub-item"))
+);
+```
+
+### 9.3 Bullet Lists with Custom Symbols
+
+```csharp
+// Bullet numbering uses NumberFormatValues.Bullet
+// The bullet character is defined in LevelText and NumberingSymbolRunProperties
+
+var bulletAbstractNum = new AbstractNum { AbstractNumberId = 2 };
+bulletAbstractNum.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
+
+// Level 0 bullet: ● (Unicode bullet)
+bulletAbstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Bullet },  // Key: Bullet format
+    new LevelText { Val = "\u2022" },  // ● bullet character
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "720", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Symbol", HighAnsi = "Symbol" }
+        // Symbol font maps ● to character 0xD8 in Symbol encoding
+    )
+) { LevelIndex = 0 });
+
+// Level 1 bullet: ○ (white circle)
+bulletAbstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Bullet },
+    new LevelText { Val = "\u25CB" },  // ○ Unicode
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "1080", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Courier New", HighAnsi = "Courier New" }
+    )
+) { LevelIndex = 1 });
+
+// Level 2 bullet: ■ (black square)
+bulletAbstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Bullet },
+    new LevelText { Val = "\u25A0" },  // ■
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "1440", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Arial", HighAnsi = "Arial" }
+    )
+) { LevelIndex = 2 });
+
+var bulletNumInstance = new NumberingInstance(
+    new AbstractNumId { Val = 2 }
+) { NumberID = 2 };
+
+numbering.Append(bulletAbstractNum);
+numbering.Append(bulletNumInstance);
+```
+
+**Common bullet characters:**
+
+| Symbol | Character | Unicode | Common Font |
+|--------|-----------|---------|-------------|
+| ● Filled circle | Bullet | U+2022 | Symbol |
+| ○ Empty circle | White circle | U+25CB | Arial |
+| ■ Filled square | Black square | U+25A0 | Arial |
+| □ Empty square | White square | U+25A1 | Arial |
+| ➢ Right arrow | Right arrow | U+27A2 | Wingdings |
+| ✓ Checkmark | Check mark | U+2713 | Wingdings |
+| ✗ Cross | Ballot X | U+2717 | Wingdings |
+| ▶ Play | Right triangle | U+25B6 | Arial |
+
+### 9.4 Restart Numbering at Specific Point
+
+```csharp
+// Method 1: StartOverride on a specific paragraph
+// Use LevelOverride + StartOverride to restart at a specific level
+
+var restartNumInstance = new NumberingInstance(
+    new AbstractNumId { Val = 1 }
+) { NumberID = 3 };
+
+// Override level 0 to start at 5 instead of 1
+restartNumInstance.Append(new LevelOverride { LevelIndex = 0 },
+    new StartOverrideNumberingValue { Val = 5 }
+);
+
+// Apply this to a paragraph — this paragraph starts numbering at 5
+var restartPara = new Paragraph(
+    new ParagraphProperties(
+        new NumberingProperties(
+            new NumberingLevelReference { Val = 0 },
+            new NumberingId { Val = 3 }  // Use the restart instance
+        )
+    ),
+    new Run(new Text("Item 5 (restarted)"))
+);
+```
+
+### 9.5 Continue Numbering from Previous List
+
+```csharp
+// By default, Word continues numbering across lists using the same AbstractNum.
+// To force continuation, ensure the list uses the same numId.
+
+// If you need explicit continuation control:
+var continuedNumInstance = new NumberingInstance(
+    new AbstractNumId { Val = 1 }
+) { NumberID = 4 };
+
+// When multiple NumberingInstances share the same AbstractNumId,
+// they share the same numbering state (continuation)
+
+// To prevent continuation (start fresh), use a new AbstractNum:
+var freshAbstractNum = new AbstractNum { AbstractNumberId = 5 };
+freshAbstractNum.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
+// ... define levels ...
+var freshNumInstance = new NumberingInstance(
+    new AbstractNumId { Val = 5 }
+) { NumberID = 5 };
+// This starts at 1 again, independent of the previous list
+```
+
+### 9.6 Link Numbering to Heading Styles (Outline Numbering)
+
+```句话说，link numbering to heading styles so that Heading1 starts a new numbering sequence, Heading2 is a sub-item, etc.
+
+```csharp
+// This links styles to numbering levels automatically via StyleLink
+var abstractNumForOutline = new AbstractNum { AbstractNumberId = 10 };
+abstractNumForOutline.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
+abstractNumForOutline.Append(new StyleLink { Val = "Heading1" });  // Links level 0 to Heading1
+abstractNumForOutline.Append(new StyleLink { Val = "Heading2" });  // Links level 1 to Heading2
+abstractNumForOutline.Append(new StyleLink { Val = "Heading3" });  // Links level 2 to Heading3
+
+// Level 0 for Heading1
+abstractNumForOutline.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "Chapter %1" },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "360", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new Bold(),
+        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
+        new FontSize { Val = "28" }
+    )
+) { LevelIndex = 0 });
+
+// Level 1 for Heading2
+abstractNumForOutline.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "%1.%2" },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "720", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" }
+    )
+) { LevelIndex = 1 });
+
+// Level 2 for Heading3
+abstractNumForOutline.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "%1.%2.%3" },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "1080", Hanging = "360" }
+    ),
+    new NumberingSymbolRunProperties(
+        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" }
+    )
+) { LevelIndex = 2 });
+
+// Now when you apply Heading1/2/3 styles, numbering follows automatically
+var heading1Para = new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+    new Run(new Text("Introduction"))  // Automatically gets "Chapter 1" prefix
+);
+var heading2Para = new Paragraph(
+    new ParagraphProperties(new ParagraphStyleId { Val = "Heading2" }),
+    new Run(new Text("Background"))  // Automatically gets "1.1" prefix
+);
+```
+
+### 9.7 NumberingFormat Values Reference
+
+```csharp
+// NumberFormatValues enum — all supported numbering formats:
+NumberFormatValues.Decimal          // 1, 2, 3...
+NumberFormatValues.LowerRoman       // i, ii, iii...
+NumberFormatValues.UpperRoman       // I, II, III...
+NumberFormatValues.LowerLetter      // a, b, c...
+NumberFormatValues.UpperLetter      // A, B, C...
+NumberFormatValues.Ordinal          // 1st, 2nd, 3rd... (locale-dependent)
+NumberFormatValues.OrdinalText      // First, Second, Third... (locale-dependent)
+NumberFormatValues.Hex              // 0, 1, 2... F, 10, 11... (hexadecimal)
+NumberFormatValues.ChicagoManual    // Chapter numbering (I, A, 1, a)
+NumberFormatValues.Kanji           // 漢数字
+NumberFormatValues.KanjiDigit      // 一, 二, 三...
+NumberFormatValues.DoubleByte      // Ideographic: 一, 二, 三
+NumberFormatValues.ArabicFullWidth // Full-width: １, ２, ３
+NumberFormatValues.Bullet          // Custom symbol (●, ✓, etc.)
+NumberFormatValues.None            // No number
+```
+
+### 9.8 IsLegalNumberingStyle — Using Arabic with Nested Levels
+
+```csharp
+// IsLegalNumberingStyle=false (default): each level can have its own format
+// IsLegalNumberingStyle=true: forces all sub-levels to use Arabic numerals
+
+// This is important for legal/formal numbering where you want:
+// 1. level 1 = A, B, C (alphabetic)
+// 2. level 2 = 1, 2, 3 (Arabic) — NOT a, b, c
+// Without IsLegalNumberingStyle=false, level 2 would inherit alphabetic
+
+var legalAbstractNum = new AbstractNum { AbstractNumberId = 20 };
+legalAbstractNum.Append(new MultiLevelType { Val = MultiLevelValues.Multilevel });
+legalAbstractNum.Append(new IsLegalNumberingStyle());  // No val = true (default when element present)
+
+// Level 0: A. B. C.
+legalAbstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.UpperLetter },
+    new LevelText { Val = "%1." },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "360", Hanging = "360" }
+    )
+) { LevelIndex = 0 });
+
+// Level 1: 1. 2. 3. (NOT a. b. c.)
+legalAbstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.Decimal },
+    new LevelText { Val = "%2." },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "720", Hanging = "360" }
+    )
+) { LevelIndex = 1 });
+
+// Level 2: (a) (b) (c)
+legalAbstractNum.Append(new Level(
+    new StartNumberingValue { Val = 1 },
+    new NumberingFormat { Val = NumberFormatValues.LowerLetter },
+    new LevelText { Val = "(%3)" },
+    new LevelJustification { Val = LevelJustificationValues.Left },
+    new ParagraphProperties(
+        new Indentation { Left = "1080", Hanging = "360" }
+    )
+) { LevelIndex = 2 });
+```
+
+---
+
+## 10. Document Protection & Encryption
+
+### 10.1 DocumentProtection — Basic Forms
+
+```csharp
+// DocumentProtection is placed in DocumentSettingsPart
+var settingsPart = mainPart.AddNewPart<DocumentSettingsPart>();
+settingsPart.Settings = new Settings();
+
+// ReadOnly: prevents editing, allows reading
+settingsPart.Settings.Append(new DocumentProtection
+{
+    Edit = DocumentProtectionValues.ReadOnly,
+    Enforcement = true
+});
+
+// Comments: can only add/edit comments (not modify body text)
+settingsPart.Settings.Append(new DocumentProtection
+{
+    Edit = DocumentProtectionValues.Comments,
+    Enforcement = true
+});
+
+// TrackedChanges: can only edit with track changes ON
+settingsPart.Settings.Append(new DocumentProtection
+{
+    Edit = DocumentProtectionValues.TrackedChanges,
+    Enforcement = true
+});
+
+// Forms: only form fields are editable
+settingsPart.Settings.Append(new DocumentProtection
+{
+    Edit = DocumentProtectionValues.Forms,
+    Enforcement = true
+});
+```
+
+### 10.2 Password Hashing for DocumentProtection
+
+Modern Word uses SHA-512 with salt for password hashing (ECMA-376 standard).
+
+```csharp
+// SHA-512 password hashing for strong protection
+// CryptographicProviderType must be "rsaAES" or "rsaAES" for SHA-512
+
+settingsPart.Settings.Append(new DocumentProtection
+{
+    Edit = DocumentProtectionValues.ReadOnly,
+    Enforcement = true,
+    CryptographicProviderType = CryptProviderValues.RsaAES,
+    CryptographicAlgorithmClass = CryptAlgorithmClassValues.Hash,
+    CryptographicAlgorithmType = CryptAlgorithmValues.TypeAny,
+    CryptographicAlgorithmSid = 14,  // SHA-512
+    CryptographicSpinCount = 100000U,
+    Hash = "base64-encoded-hash-here",
+    Salt = "base64-encoded-salt-here"
+});
+
+// Generate hash in .NET:
+public static (string hash, string salt) GeneratePasswordHash(string password, int spinCount = 100000)
+{
+    byte[] saltBytes = new byte[16];
+    using (var rng = System.Security.Cryptography.RandomNumberGenerator.Create())
+        rng.GetBytes(saltBytes);
+
+    // PBKDF2 with SHA-512, 100000 iterations
+    using var pbkdf2 = new System.Security.Cryptography.Rfc2898DeriveBytes(
+        password, saltBytes, spinCount, System.Security.Cryptography.HashAlgorithmName.SHA512);
+    byte[] hash = pbkdf2.GetBytes(64);  // 512 bits
+
+    return (Convert.ToBase64String(hash), Convert.ToBase64String(saltBytes));
+}
+```
+
+### 10.3 WriteProtection — Recommend Opening as Read-Only
+
+```csharp
+// WriteProtection is different from DocumentProtection
+// It recommends (but doesn't enforce) that users open as read-only
+// Found in extended properties (docProps/custom.xml or settings)
+
+settingsPart.Settings.Append(new WriteProtection
+{
+    Recommended = true  // "Recommend opening as read-only"
+});
+
+// Or force read-only recommendation with a specific application name
+settingsPart.Settings.Append(new WriteProtection
+{
+    Recommended = true,
+    ApplicationName = "Microsoft Word"
+});
+```
+
+### 10.4 Restrict Editing to Form Fields Only
+
+```csharp
+// This protects the document but allows editing in form field content controls
+settingsPart.Settings = new Settings(
+    new DocumentProtection
+    {
+        Edit = DocumentProtectionValues.Forms,
+        Enforcement = true
+    },
+    // Also set to allow editing only in form fields
+    new EditingRestrictions { Val = EditingRestrictionValues.Forms }
+);
+```
+
+### 10.5 PermStart / PermEnd — Editable Regions in Protected Document
+
+Allow specific regions (ranges) to be edited even when the document is protected.
+
+```csharp
+// <w:permStart w:id="1" w:editor="everyone"/>
+// <w:r><w:t>Editable text</w:t></w:r>
+// <w:permEnd w:id="1"/>
+
+// Even when document protection is on, this range can be edited by everyone
+
+var editableRegion = new Paragraph(
+    new ParagraphProperties(
+        new PermStart { Id = 1, EditorGroup = RangePermissionEditingGroupValues.Everyone }
+    ),
+    new Run(new Text("This text can be edited even in a protected document.") { Space = SpaceProcessingModeValues.Preserve }),
+    new ParagraphProperties(
+        new PermEnd { Id = 1 }
+    )
+);
+
+// EditorGroup values:
+// Everyone         — anyone can edit
+// Administrators   — only administrators
+// Contributors     — only contributors
+// Editors          — only editors
+// Owners           — only document owners
+// Nobody           — nobody can edit (use with w:perm sbz="1" for "does not include")
+
+// Use specific user name:
+// <w:permStart w:id="2" w:author="Alice"/>
+
+// For tracked changes review scenario (allow comments but not direct editing):
+var commentableRegion = new Paragraph(
+    new ParagraphProperties(
+        new PermStart { Id = 2, EditorGroup = RangePermissionEditingGroupValues.Everyone }
+    ),
+    new Run(new Text("This region allows comments and tracked changes.") { Space = SpaceProcessingModeValues.Preserve }),
+    new ParagraphProperties(
+        new PermEnd { Id = 2 }
+    )
+);
+```
+
+### 10.6 Full Document Protection with Password and Salt
+
+```csharp
+public static void ProtectDocument(
+    WordprocessingDocument doc,
+    string password,
+    DocumentProtectionValues protectionType)
+{
+    var settingsPart = doc.MainDocumentPart!.AddNewPart<DocumentSettingsPart>();
+    if (settingsPart.Settings == null)
+        settingsPart.Settings = new Settings();
+
+    // Generate password hash
+    byte[] salt = new byte[16];
+    using (var rng = System.Security.Cryptography.RandomNumberGenerator.Create())
+        rng.GetBytes(salt);
+
+    int spinCount = 100000;
+    using var pbkdf2 = new System.Security.Cryptography.Rfc2898DeriveBytes(
+        password, salt, spinCount, System.Security.Cryptography.HashAlgorithmName.SHA512);
+    byte[] hash = pbkdf2.GetBytes(64);
+
+    var protection = new DocumentProtection
+    {
+        Edit = protectionType,
+        Enforcement = true,
+        CryptographicProviderType = CryptProviderValues.RsaAES,
+        CryptographicAlgorithmClass = CryptAlgorithmClassValues.Hash,
+        CryptographicAlgorithmType = CryptAlgorithmValues.TypeAny,
+        CryptographicAlgorithmSid = 14,  // SHA-512
+        CryptographicSpinCount = (UInt32Value)spinCount,
+        Hash = Convert.ToBase64String(hash),
+        Salt = Convert.ToBase64String(salt)
+    };
+
+    settingsPart.Settings.Append(protection);
+    settingsPart.Settings.Save();
+}
+```
+
+---
+
+## Quick Reference: Common Element Order in OpenXML
+
+When building complex elements, remember these ordering rules:
+
+### Run Elements Order (inside RunProperties):
+`RunFonts` → `Bold`/`Italic` → `Color` → `FontSize` → `Underline` → `VerticalTextAlignment` → `Emphasis` → (any other)
+
+### Paragraph Elements Order (inside ParagraphProperties):
+`ParagraphStyleId` → `KeepNext` → `KeepLines` → `PageBreakBefore` → `FrameProperties` → `WidowControl` → `NumPr` → `Indentation` → `SpacingBetweenLines` → `Justification` → `SectionProperties`
+
+### Table Properties Order:
+`TableWidth` → `TextDirection` → `Borders` → `Shading` → `TableLayout` → `TableCellMarginDefault`
+
+### SectionProperties Order:
+`FootnotePr` → `EndnotePr` → `Type` → `PageSize` → `PageMargin` → `PaperSource` → `PageBorders` → `LineNumberRestart` → `PageNumberFormat` → `TitlePage` → `TextDirection`
+
+---
+
+*Generated for DocumentFormat.OpenXml 3.x / .NET 8+ / C# 12*
+*Last updated: 2026-03-22*