@beyondwork/docx-react-component 1.0.0 → 1.0.1

package/docs/research/docx-react-component/Canonical Document Schema Specification for a React-based Word-compatible Editor.md

@@ -1,2317 +0,0 @@
-# Canonical Document Schema Specification for a React-based Word-compatible Editor
-
-## Schema principles and compatibility objectives
-
-### Compatibility contract
-
-This specification defines a **Canonical Document Schema (CDS)** that is the **single source of truth** for:
-
-- structured editing in a React-based editor,
-- comments and anchored annotations,
-- tracked changes (revisions),
-- `.docx` (OOXML WordprocessingML) import/export,
-- validation and repair,
-- loss-minimized preservation of unsupported OOXML.
-
-The `.docx` container is an **Open Packaging Conventions (OPC)** ZIP package composed of **parts** (XML and binary) connected by **relationships**. citeturn0search2 The CDS must therefore preserve both (a) **document semantics** and (b) sufficient **package-level information** to reconstruct a Word-openable `.docx`.
-
-### Separation of content vs. annotations
-
-**Rule P1 (Content purity):** The CDS **content tree** contains only structural content nodes and explicit “opaque/preserved content placeholders.” It **does not** embed comments or revision wrappers as structural nodes.
-
-- **Comments** and **revisions** are stored in dedicated top-level stores referencing **ranges/anchors** in the content coordinate space.
-- Export materializes WordprocessingML comment/revision markup from these stores (e.g., comment anchors/range markers, revision containers), rather than storing them inline in the canonical content.
-
-This aligns with how WordprocessingML treats paragraph content as including properties, run content, and **annotations (comments/revisions/bookmarks)** as separate markup within the paragraph stream. citeturn3search0turn11search19
-
-### Immutability vs. mutability model
-
-**Rule P2 (Immutable state, transactional edits):**
-
-- The editor operates on an **immutable** `CanonicalDocument` value.
-- Updates occur via **Transactions** consisting of **Steps**.
-- Applying a transaction yields a new document with structural sharing permitted at implementation level.
-
-This mirrors well-established editor-engine practice: applying atomic steps yields a new document, and each step provides a position mapping. citeturn6search0turn9search4
-
-### Deterministic structure (canonicalization)
-
-**Rule P3 (Canonical JSON):** For any in-memory CDS instance, serialization must be deterministic:
-
-- Object keys are emitted in a stable order (defined below).
-- Arrays with semantic ordering (children, marks, steps) preserve order.
-- Marks are canonical-sorted (defined below).
-- Normalization eliminates representational ambiguity (no empty text nodes, merged adjacent text nodes where allowed, etc.).
-
-### Compatibility-first design
-
-**Rule P4 (Word correctness > editor convenience):** When a choice conflicts between “nice internal modeling” and “Word-openable export,” the schema and invariants prioritize generating OOXML that:
-
-- opens in recent Word without repair warnings,
-- preserves required stories/parts and relationships,
-- respects OOXML constraints for comments/revisions/sections/tables.
-
-### Lossless round-trip requirements
-
-**Rule P5 (Round-trip tiers):** The system distinguishes three fidelity tiers:
-
-- **Tier A (Lossless):** Supported CDS features round-trip `.docx → CDS → .docx → Word` with no semantic loss.
-- **Tier B (Preserved opaque):** Unsupported OOXML is preserved either as untouched parts or as opaque fragments re-injected at export, provided the user did not structurally edit inside those fragments.
-- **Tier C (Degraded with diagnostics):** If edits invalidate preservation reattachment, content may be dropped or flattened, but the system must emit **deterministic diagnostics** describing the loss.
-
-Markup Compatibility constructs like `mc:AlternateContent` are explicitly designed for forward/feature compatibility; they must be preserved in Tier B when unsupported. citeturn2search3turn2search7
-
-### Mapping stability under edits
-
-**Rule P6 (Stable coordinate space):** All anchors (comments, revisions, preservation bindings) use the **same global position space** (defined below). Every transaction produces a **Mapping** allowing deterministic remapping of:
-
-- selections,
-- comment anchors,
-- revision target ranges,
-- preservation bindings.
-
-This is required because `.docx` comment anchors and revision markup are location-based in the content stream (e.g., comment range start/end markers link to a comment id). citeturn0search8turn0search4
-
-## Canonical document envelope and shared types
-
-### Fundamental scalar types
-
-All types are expressed in TypeScript-style interfaces.
-
-```ts
-// Scalars
-export type CDS_SchemaVersion = "cds/1.0.0";
-
-// Identifiers
-export type Id = string;              // non-empty, UTF-8 JSON string
-export type UUID = string;            // RFC 4122 textual form (implementation must validate) citeturn12search0
-export type PartName = string;        // OPC part name, e.g. "/word/document.xml"
-export type RelationshipId = string;  // e.g. "rId10"
-export type ISO8601DateTime = string; // e.g. "2026-03-25T10:15:30.000Z"
-export type HexColorRGB = string;     // "RRGGBB" uppercase
-export type Base64 = string;
-
-// Numeric units aligned with WordprocessingML conventions
-export type Twips = number;       // integer, 1/20 pt
-export type HalfPoints = number;  // integer, 1/2 pt (e.g., w:sz) citeturn8search2turn8search14
-```
-
-### Top-level document model
-
-#### CanonicalDocument interface
-
-```ts
-export interface CanonicalDocument {
-  schemaVersion: CDS_SchemaVersion;
-
-  // Identity
-  docId: UUID;
-
-  // Lifecycle metadata (system-managed)
-  createdAt: ISO8601DateTime;
-  updatedAt: ISO8601DateTime;
-
-  // Document-wide metadata (user/authored + imported)
-  metadata: DocumentMetadata;
-
-  // Main editable story (Word main document body)
-  content: DocNode;
-
-  // Style and numbering catalogs (editable subset + preserved extras)
-  styles: StylesCatalog;
-  numbering: NumberingCatalog;
-
-  // Media registry
-  media: MediaCatalog;
-
-  // Annotations
-  comments: CommentStore;
-  revisions: RevisionStore;
-
-  // Preservation and package fidelity
-  preservation: PreservationStore;
-
-  // Validation/repair output and non-fatal issues
-  diagnostics: DiagnosticStore;
-}
-```
-
-#### Required invariants
-
-**Invariant D1:** `schemaVersion` MUST be exactly `"cds/1.0.0"` for this spec.
-
-**Invariant D2:** `content.type` MUST be `"doc"`.
-
-**Invariant D3:** All IDs in each namespace MUST be unique:
-
-- node ids unique across the content tree,
-- `media.items[*].mediaId` unique,
-- `comments.threads[*].threadId` unique,
-- `revisions.items[*].revisionId` unique,
-- `preservation.fragments[*].fragmentId` unique,
-- `preservation.opc.parts[*].partName` unique.
-
-**Invariant D4:** `updatedAt` MUST be ≥ `createdAt`.
-
-### Document metadata
-
-```ts
-export interface DocumentMetadata {
-  // Human-facing name
-  title?: string;
-
-  // OOXML core/app/custom properties pass-through
-  coreProperties?: Record<string, string>;
-  appProperties?: Record<string, string>;
-  customProperties?: Record<string, string | number | boolean | ISO8601DateTime>;
-
-  // Actors used by comments/revisions
-  actors: Record<Id, Actor>;
-
-  // Import provenance (stable across exports unless reimported)
-  provenance?: ImportProvenance;
-}
-
-export interface Actor {
-  actorId: Id;              // key == actorId
-  displayName: string;      // non-empty
-  email?: string;
-  externalId?: string;      // optional mapping to identity provider
-}
-
-export interface ImportProvenance {
-  importedFrom: "docx";
-  importedAt: ISO8601DateTime;
-  sourceFingerprint: string; // implementation-defined stable hash of original package bytes
-}
-```
-
-### Styles catalog
-
-WordprocessingML styles are defined in the styles part (`styles.xml`) and applied via `w:pStyle` (paragraph) and `w:rStyle` (character). citeturn4search0turn4search5turn4search8
-
-```ts
-export interface StylesCatalog {
-  // Defaults extracted from docDefaults (if present)
-  defaults: {
-    paragraph?: ParagraphStyleProps;
-    run?: RunStyleProps;
-  };
-
-  paragraphStyles: Record<string, ParagraphStyleDef>; // key = styleId
-  characterStyles: Record<string, CharacterStyleDef>; // key = styleId
-  tableStyles: Record<string, TableStyleDef>;         // key = styleId
-
-  // Unmodeled style XML preserved losslessly
-  ooxmlExtras?: {
-    rawStylesXmlBase64?: Base64; // original /word/styles.xml (optional)
-  };
-}
-
-export interface StyleDefBase {
-  styleId: string;     // Word styleId
-  name?: string;
-  basedOn?: string;    // styleId
-  next?: string;       // styleId
-  linked?: string;     // styleId (linked paragraph/character style)
-  isDefault?: boolean;
-  isCustom?: boolean;
-
-  // Preservation hook for unknown style attributes/elements
-  ooxmlUnknown?: PreservedXmlRef;
-}
-
-export interface ParagraphStyleDef extends StyleDefBase {
-  type: "paragraph";
-  pPr?: ParagraphStyleProps;
-  rPr?: RunStyleProps; // run defaults for this paragraph style
-}
-
-export interface CharacterStyleDef extends StyleDefBase {
-  type: "character";
-  rPr?: RunStyleProps;
-}
-
-export interface TableStyleDef extends StyleDefBase {
-  type: "table";
-  tblPr?: TableProps;
-  trPr?: TableRowProps;
-  tcPr?: TableCellProps;
-}
-```
-
-**Style precedence model (required):** When computing effective formatting, apply in this order (lowest to highest), consistent with OOXML style hierarchy: document defaults → table styles → numbering styles → paragraph styles (`w:pStyle`) → character styles (`w:rStyle`) → direct formatting. citeturn4search0turn4search5turn11search20
-
-### Numbering catalog
-
-Numbering in WordprocessingML is referenced from paragraphs via `w:numPr`, including `w:numId` and `w:ilvl`. citeturn4search6turn4search17turn4search2
-
-```ts
-export interface NumberingCatalog {
-  abstractNums: Record<string, AbstractNumDef>; // key = abstractNumId
-  nums: Record<string, NumInstanceDef>;         // key = numId
-
-  ooxmlExtras?: {
-    rawNumberingXmlBase64?: Base64; // original /word/numbering.xml (optional)
-  };
-}
-
-export interface AbstractNumDef {
-  abstractNumId: string;
-  levels: Record<number, NumberingLevelDef>; // level 0..8
-  ooxmlUnknown?: PreservedXmlRef;
-}
-
-export interface NumInstanceDef {
-  numId: string;
-  abstractNumId: string;
-  levelOverrides?: Record<number, NumberingLevelDef>;
-  ooxmlUnknown?: PreservedXmlRef;
-}
-
-export interface NumberingLevelDef {
-  level: number; // 0..8
-  numFmt: "bullet" | "decimal" | "lowerLetter" | "upperLetter" | "lowerRoman" | "upperRoman" | "other";
-  lvlText?: string;      // e.g. "%1."
-  start?: number;        // default start value
-  pPr?: ParagraphStyleProps;
-  rPr?: RunStyleProps;
-  ooxmlUnknown?: PreservedXmlRef;
-}
-```
-
-### Media catalog
-
-Images in WordprocessingML are represented as DrawingML objects inside a run (`w:r/w:drawing`), commonly using `wp:inline` (in-line with text). citeturn2search10
-
-```ts
-export interface MediaCatalog {
-  items: Record<Id, MediaItem>; // key = mediaId
-
-  // Relationship and part naming policy must be deterministic on export.
-  exportPolicy: {
-    mediaFolder: "/word/media";
-    filenameStrategy: "stableByMediaId";
-    relationshipIdStrategy: "stableByOrder";
-  };
-}
-
-export interface MediaItem {
-  mediaId: Id;
-  kind: "image";
-  mimeType: "image/png" | "image/jpeg" | "image/gif" | "image/webp" | "image/svg+xml";
-  sha256: string;      // hex lowercase
-  bytesBase64?: Base64; // present if the CDS is self-contained; optional if stored externally
-  externalUrl?: string; // optional pointer if bytes are not embedded
-
-  // Sizing metadata (used for initial layout hints)
-  pixelWidth?: number;
-  pixelHeight?: number;
-  dpiX?: number;
-  dpiY?: number;
-
-  // OOXML preservation for DrawingML details not modeled
-  ooxmlUnknown?: PreservedXmlRef;
-}
-```
-
-### Diagnostics and warnings
-
-```ts
-export interface DiagnosticStore {
-  items: Diagnostic[];
-}
-
-export type DiagnosticSeverity = "info" | "warning" | "error" | "fatal";
-
-export interface Diagnostic {
-  diagnosticId: UUID;
-  severity: DiagnosticSeverity;
-  code: string;         // stable machine-readable code
-  message: string;      // human-readable
-  createdAt: ISO8601DateTime;
-
-  // Optional localization of where it happened
-  location?: {
-    kind: "docRange" | "nodeId" | "partName";
-    fromPos?: DocPos;
-    toPos?: DocPos;
-    nodeId?: Id;
-    partName?: PartName;
-  };
-
-  // Repair action (if any)
-  repair?: {
-    applied: boolean;
-    description: string;
-  };
-}
-```
-
-## Content model: nodes, marks, and attribute systems
-
-### Global node model
-
-All content is represented as a tree of nodes. Nodes are either **block** or **inline**. Text is inline.
-
-```ts
-export type Node =
-  | DocNode
-  | ParagraphNode
-  | HeadingNode
-  | BlockquoteNode
-  | OrderedListNode
-  | BulletListNode
-  | ListItemNode
-  | TableNode
-  | TableRowNode
-  | TableCellNode
-  | ImageBlockNode
-  | HorizontalRuleNode
-  | SectionBreakNode
-  | OoxmlBlockNode
-  | TextNode
-  | HardBreakNode
-  | HyperlinkNode
-  | InlineImageNode
-  | AnchorPlaceholderNode
-  | OoxmlInlineNode;
-
-export interface NodeBase {
-  id: Id;            // unique within document
-  type: string;      // discriminator
-}
-```
-
-### Block node specifications
-
-WordprocessingML block-level content in the main body is primarily paragraphs (`w:p`) and tables (`w:tbl`). citeturn3search0turn2search5
-
-Each block node below includes: attributes, allowed children, constraints, WordprocessingML mapping, and editing invariants.
-
-#### Document root
-
-```ts
-export interface DocNode extends NodeBase {
-  type: "doc";
-  children: BlockNode[];
-
-  attrs: {
-    // Document-wide section defaults (last section properties in Word)
-    defaultSection?: SectionPropsRef;
-
-    // Track changes flag (mirrors settings.xml w:trackRevisions)
-    trackRevisionsDefault?: boolean;
-  };
-}
-export type BlockNode =
-  | ParagraphNode
-  | HeadingNode
-  | BlockquoteNode
-  | OrderedListNode
-  | BulletListNode
-  | TableNode
-  | ImageBlockNode
-  | HorizontalRuleNode
-  | SectionBreakNode
-  | OoxmlBlockNode;
-```
-
-**Allowed children:** `BlockNode[]` (at least one block is allowed but not required).
-
-**Constraints:** `doc.children` MAY be empty.
-
-**WordprocessingML mapping:** `doc` maps to main document part `w:document/w:body` story. WordprocessingML is composed of “stories,” with the main document being required. citeturn3search4
-
-**Editing invariants:** The editor MUST maintain a valid block sequence; normalization rules below repair invalid blocks.
-
-#### Paragraph
-
-```ts
-export interface ParagraphNode extends NodeBase {
-  type: "paragraph";
-  children: InlineNode[];
-
-  attrs: ParagraphAttrs;
-}
-
-export interface ParagraphAttrs {
-  styleId?: string;              // maps to w:pPr/w:pStyle citeturn4search0
-  alignment?: ParagraphAlignment; // maps to w:pPr/w:jc citeturn5search0
-  indent?: ParagraphIndent;       // maps to w:pPr/w:ind citeturn5search1
-  spacing?: ParagraphSpacing;     // maps to w:pPr/w:spacing citeturn5search2
-  numbering?: ParagraphNumbering; // maps to w:pPr/w:numPr citeturn4search6
-
-  // Paragraph mark formatting (Word stores paragraph mark run props)
-  paragraphMarkRunStyle?: RunStyleProps; // corresponds to w:pPr/w:rPr (paragraph mark) citeturn4search1turn7search12
-
-  // Preservation of unmodeled pPr sub-elements/attrs
-  ooxmlUnknownPPr?: PreservedXmlRef;
-}
-
-export type ParagraphAlignment = "left" | "center" | "right" | "both" | "start" | "end";
-export interface ParagraphIndent {
-  leftTwips?: Twips;
-  rightTwips?: Twips;
-  firstLineTwips?: Twips;
-  hangingTwips?: Twips;
-}
-export interface ParagraphSpacing {
-  beforeTwips?: Twips;
-  afterTwips?: Twips;
-  line?: { rule: "auto" | "atLeast" | "exact"; valueTwips?: Twips; value240thLines?: number };
-  beforeAutoSpacing?: boolean;
-  afterAutoSpacing?: boolean;
-}
-export interface ParagraphNumbering {
-  numId: string;  // numbering instance id (w:numId) citeturn4search17
-  ilvl: number;   // 0..8 (w:ilvl) citeturn4search2
-}
-```
-
-**Allowed children:** `InlineNode[]`.
-
-**Constraints:**
-- Paragraph MUST contain at least one inline node after normalization. If empty, insert a single `AnchorPlaceholderNode` (see inline nodes) to keep selection addressable.
-- `attrs.numbering.ilvl` MUST be integer 0..8.
-- If `attrs.numbering` is present, export MUST emit `w:pPr/w:numPr` with both `w:numId` and `w:ilvl`. citeturn4search6turn4search17turn4search2
-
-**WordprocessingML mapping:** `paragraph` maps to `w:p` with:
-- paragraph properties in `w:pPr` (alignment `w:jc`, indent `w:ind`, spacing `w:spacing`, numbering `w:numPr`, paragraph style `w:pStyle`). citeturn3search0turn5search0turn5search1turn5search2turn4search0turn4search6
-- run-level content (`w:r`, `w:hyperlink`, etc.) as children. citeturn3search0turn3search1turn1search2
-
-**Editing invariants:** Splitting a paragraph MUST produce two valid paragraphs, each normalized to contain at least one inline.
-
-#### Heading
-
-Headings are represented as a dedicated node to provide stable editor semantics. On export/import, headings map to paragraphs with heading semantics via styleId and/or outline-level conventions.
-
-```ts
-export interface HeadingNode extends NodeBase {
-  type: "heading";
-  children: InlineNode[];
-
-  attrs: ParagraphAttrs & {
-    level: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
-  };
-}
-```
-
-**Allowed children:** `InlineNode[]`.
-
-**Constraints:**
-- `level` MUST be 1..9.
-- If `attrs.styleId` is absent at export, exporter MUST map `level` to `Heading1..Heading9` styleId by default (unless the styles catalog defines a different configured mapping).
-- If `attrs.styleId` is present, it MUST be preserved exactly; `level` is an editor semantic and MUST still export a `w:p` (not a special element) because Word stores headings as paragraph formatting (style/properties). citeturn3search0turn4search0
-
-**WordprocessingML mapping:** `heading` exports as `w:p` with `w:pPr/w:pStyle` set to the chosen heading style (or preserved). citeturn4search0
-
-**Editing invariants:** Converting between `paragraph` and `heading` MUST be a pure attribute/node-type change (content unchanged).
-
-#### Blockquote
-
-```ts
-export interface BlockquoteNode extends NodeBase {
-  type: "blockquote";
-  children: BlockNode[];
-
-  attrs: {
-    // export strategy: apply quoteStyleId to contained paragraphs if present
-    quoteStyleId?: string;
-    // optional indentation applied when quoteStyleId absent
-    indentTwips?: Twips;
-
-    ooxmlUnknown?: PreservedXmlRef;
-  };
-}
-```
-
-**Allowed children:** `BlockNode[]` (MUST contain at least one block).
-
-**Constraints:**
-- Children MUST NOT include `SectionBreakNode` directly. If encountered, normalization hoists `SectionBreakNode` out of the blockquote boundary (see repair rules).
-- If `quoteStyleId` is set, exporter MUST apply it as `w:pStyle` to each contained paragraph/heading unless that child already has an explicit `styleId`. citeturn4search0
-
-**WordprocessingML mapping:** WordprocessingML has no native blockquote element; exporter MUST emit a sequence of `w:p`/`w:tbl` content in the body. Blockquote semantics are encoded via paragraph properties (style and/or indentation). citeturn3search0turn5search1turn4search0
-
-**Editing invariants:** Blockquote boundaries MUST be stable under paragraph edits inside; splitting/merging at the boundary MUST either expand or shrink blockquote deterministically (defined in normalization).
-
-#### Ordered list and bullet list
-
-Word uses numbering properties on paragraphs (`w:numPr`) referencing numbering definitions (`numId`, `ilvl`). citeturn4search6turn4search17turn4search2
-
-```ts
-export interface OrderedListNode extends NodeBase {
-  type: "orderedList";
-  children: ListItemNode[];
-
-  attrs: ListAttrs & {
-    kind: "ordered";
-  };
-}
-
-export interface BulletListNode extends NodeBase {
-  type: "bulletList";
-  children: ListItemNode[];
-
-  attrs: ListAttrs & {
-    kind: "bullet";
-  };
-}
-
-export interface ListAttrs {
-  // Word numbering instance id. Required for stable round-trip.
-  numId: string;
-
-  // Base level for this list (0..8). Nested lists add to this.
-  baseIlvl: number;
-
-  // Stable list restart semantics
-  restart?: {
-    atIndex: number; // list item index where restart starts (0-based)
-    startValue: number;
-  };
-
-  // Preservation for advanced numbering not modeled
-  ooxmlUnknown?: PreservedXmlRef;
-}
-```
-
-**Allowed children:** `ListItemNode[]` (MUST contain ≥ 1 item).
-
-**Constraints:**
-- `attrs.baseIlvl` MUST be 0..8.
-- Each list item’s first block MUST be a `paragraph` or `heading`.
-- Export MUST produce `w:p` for each list paragraph with `w:numPr/w:numId` = `attrs.numId` and `w:ilvl` = `attrs.baseIlvl + nestingDepth`. citeturn4search6turn4search2turn4search17
-
-**WordprocessingML mapping:** A list is serialized as ordinary paragraphs bearing numbering properties. citeturn4search6turn4search17turn4search2
-
-**Editing invariants:**
-- Adjacent lists with identical `(kind, numId, baseIlvl)` MUST be merged by normalization.
-- Lifting a list item out MUST adjust numbering levels deterministically (see structural repair).
-
-#### List item
-
-```ts
-export interface ListItemNode extends NodeBase {
-  type: "listItem";
-  children: BlockNode[];
-
-  attrs: {
-    // Optional override of ilvl for this item (rare; used for malformed imports)
-    ilvlOverride?: number; // 0..8
-    // Optional stable identity for Word paragraph rsid retention (preserved, not interpreted)
-    ooxmlUnknown?: PreservedXmlRef;
-  };
-}
-```
-
-**Allowed children:** `BlockNode[]` (MUST contain ≥ 1).
-
-**Constraints:**
-- First child MUST be `paragraph` or `heading`.
-- A `listItem` MUST NOT contain a `SectionBreakNode`; normalization hoists it out.
-
-**WordprocessingML mapping:** Each `listItem` exports as one or more paragraphs/tables; the first paragraph carries the list numbering properties (`w:numPr`). citeturn4search6turn3search0
-
-**Editing invariants:** Adding/removing blocks inside a list item MUST not change list identity; only numbering props on affected paragraphs may change.
-
-#### Table
-
-Tables in WordprocessingML are represented by `<w:tbl>` with optional grid definitions (`<w:tblGrid>`). citeturn2search5turn4search7turn4search3
-
-```ts
-export interface TableNode extends NodeBase {
-  type: "table";
-  children: TableRowNode[];
-
-  attrs: TableProps;
-}
-
-export interface TableProps {
-  styleId?: string; // table styleId (w:tblStyle)
-  alignment?: "left" | "center" | "right"; // table alignment conceptually maps to w:jc at tblPr citeturn5search8
-  widthTwips?: Twips;
-
-  // Grid model for stable cell width semantics
-  grid?: {
-    colWidthsTwips: Twips[]; // length >= 1
-  };
-
-  // Preservation for tblPr/tblLook/tblBorders etc not modeled
-  ooxmlUnknownTblPr?: PreservedXmlRef;
-}
-```
-
-**Allowed children:** `TableRowNode[]` (MUST contain ≥ 1 row).
-
-**Constraints:**
-- If `attrs.grid` present, length MUST equal `max(columns referenced by cells after applying gridSpan)`.
-- Export MUST emit `<w:tbl>` and, if `grid` present, a `<w:tblGrid>` with `<w:gridCol>` entries matching widths. citeturn4search7turn4search3turn4search21
-
-**WordprocessingML mapping:** `<w:tbl>` container, `<w:tr>` rows, `<w:tc>` cells. citeturn2search5turn2search9
-
-**Editing invariants:** Table cell content edits MUST not alter the table grid unless explicitly performing a column/row operation.
-
-#### Table row
-
-```ts
-export interface TableRowNode extends NodeBase {
-  type: "tableRow";
-  children: TableCellNode[];
-
-  attrs: TableRowProps;
-}
-
-export interface TableRowProps {
-  isHeader?: boolean;
-  heightTwips?: Twips;
-  // Tracked row insertion/deletion in Word may be represented separately; preserved here.
-  ooxmlUnknownTrPr?: PreservedXmlRef;
-}
-```
-
-**Allowed children:** `TableCellNode[]` (MUST contain ≥ 1 cell).
-
-**Constraints:** All rows in the same table MUST normalize to consistent column counts after considering `gridSpan`/`vMerge`.
-
-**WordprocessingML mapping:** `<w:tr>` with `<w:trPr>`; cells `<w:tc>`. citeturn2search9turn2search5
-
-**Editing invariants:** Row operations are structural steps; plain text edits inside cells do not affect row identity.
-
-#### Table cell
-
-WordprocessingML cell properties are stored in `<w:tcPr>` and override higher-level table/row properties on conflict. citeturn5search7
-
-```ts
-export interface TableCellNode extends NodeBase {
-  type: "tableCell";
-  children: BlockNode[];
-
-  attrs: TableCellProps;
-}
-
-export interface TableCellProps {
-  gridSpan?: number; // >= 1, maps to w:gridSpan (colspan concept) citeturn5search15
-  vMerge?: "restart" | "continue"; // maps to w:vMerge semantics citeturn5search11
-
-  widthTwips?: Twips;
-  shading?: { fill?: HexColorRGB };
-
-  // Cell-level padding/borders not modeled must be preserved
-  ooxmlUnknownTcPr?: PreservedXmlRef;
-}
-```
-
-**Allowed children:** `BlockNode[]` (MUST contain ≥ 1).
-
-**Constraints:**
-- First child MUST be a `paragraph` or `heading` after normalization (Word requires block content in cells and commonly at least one paragraph).
-- If `vMerge="continue"`, the cell MUST be vertically merged with the cell above at same column position after normalization.
-
-**WordprocessingML mapping:** `<w:tc>` with `<w:tcPr>` including `w:gridSpan`, `w:vMerge`, widths, etc. citeturn5search7turn5search11
-
-**Editing invariants:** Deleting the last paragraph in a cell inserts an empty paragraph placeholder.
-
-#### Image block
-
-```ts
-export interface ImageBlockNode extends NodeBase {
-  type: "imageBlock";
-  children: []; // leaf block (caption is separate paragraph/node)
-
-  attrs: {
-    mediaId: Id;
-    altText?: string;
-
-    // Layout hints
-    widthTwips?: Twips;
-    heightTwips?: Twips;
-
-    // Default export is inline drawing inside its own paragraph
-    exportAs: "ownParagraphInlineDrawing";
-
-    ooxmlUnknown?: PreservedXmlRef;
-  };
-}
-```
-
-**Allowed children:** none.
-
-**Constraints:** `mediaId` MUST exist in `media.items`.
-
-**WordprocessingML mapping:** Exports as a paragraph containing a run with a DrawingML `w:drawing` and `wp:inline` referencing the image relationship. `wp:inline` indicates the object is positioned inline with text. citeturn2search10
-
-**Editing invariants:** Treated as an atomic block for selection and deletion.
-
-#### Horizontal rule
-
-```ts
-export interface HorizontalRuleNode extends NodeBase {
-  type: "horizontalRule";
-  children: [];
-
-  attrs: {
-    // Export strategy uses paragraph borders (not shapes)
-    thicknessTwips?: Twips;
-    color?: HexColorRGB;
-    spacingBeforeTwips?: Twips;
-    spacingAfterTwips?: Twips;
-
-    ooxmlUnknown?: PreservedXmlRef;
-  };
-}
-```
-
-**Allowed children:** none.
-
-**Constraints:** None.
-
-**WordprocessingML mapping:** Exports as an empty paragraph with `pPr` specifying border(s) (typically bottom border). Because OOXML does not define a “horizontal rule” element, this uses paragraph properties. citeturn3search0turn4search4
-
-**Editing invariants:** Atomic block.
-
-#### Section break placeholder
-
-Sections in WordprocessingML store section properties in a `<w:sectPr>` element. For all sections except the last, the `sectPr` is stored as a child of the last paragraph of the section. citeturn0search15turn0search3
-
-```ts
-export interface SectionBreakNode extends NodeBase {
-  type: "sectionBreak";
-  children: [];
-
-  attrs: {
-    // Reference to preserved or generated sectPr XML
-    sectPr: SectionPropsRef;
-
-    // Break type (nextPage, continuous, etc.)
-    kind: "nextPage" | "continuous" | "column";
-
-    ooxmlUnknown?: PreservedXmlRef;
-  };
-}
-
-export interface SectionPropsRef {
-  mode: "preservedXml" | "generated";
-  preservedFragmentId?: Id; // references preservation.fragments
-  generated?: {
-    // Minimal modeled section props (optional; everything else preserved)
-    pageSize?: { widthTwips: Twips; heightTwips: Twips };
-    margins?: { topTwips: Twips; rightTwips: Twips; bottomTwips: Twips; leftTwips: Twips };
-  };
-}
-```
-
-**Allowed children:** none.
-
-**Constraints:**
-- `sectPr.mode="preservedXml"` requires `preservedFragmentId`.
-- Export MUST place section property markup in the correct OOXML location: associated with a paragraph boundary (the paragraph ending the section). citeturn0search15turn0search3
-- If the CDS contains `SectionBreakNode` between blocks, exporter MUST ensure there is a paragraph to carry the `<w:sectPr>` if required by the chosen break kind.
-
-**Editing invariants:** Treated as atomic. Insert/remove must update section association deterministically (defined in export algorithm notes under preservation).
-
-#### Opaque preserved block node
-
-```ts
-export interface OoxmlBlockNode extends NodeBase {
-  type: "ooxmlBlock";
-  children: [];
-
-  attrs: {
-    fragmentId: Id; // references preservation.fragments
-    editability: "locked"; // always locked in this schema version
-    description?: string;
-  };
-}
-```
-
-**Purpose:** Represents unsupported/unmodeled block-level OOXML content in the main body (e.g., complex content controls, altChunk, etc.) preserved for round-trip. Markup Compatibility constructs must be preserved when not supported. citeturn2search3turn2search7
-
-**Constraints:** `fragmentId` MUST exist; exporter MUST re-inject without modification.
-
-### Inline node specifications
-
-Inline nodes occur inside paragraphs/headings.
-
-```ts
-export type InlineNode =
-  | TextNode
-  | HardBreakNode
-  | HyperlinkNode
-  | InlineImageNode
-  | AnchorPlaceholderNode
-  | OoxmlInlineNode;
-```
-
-#### Text
-
-```ts
-export interface TextNode extends NodeBase {
-  type: "text";
-  text: string;      // Unicode string (may include spaces)
-  marks: Mark[];     // canonical sorted
-  attrs?: {
-    // If true, exporter MUST preserve whitespace equivalently to xml:space="preserve" where needed
-    preserveWhiteSpace?: boolean;
-  };
-}
-```
-
-**Constraints:**
-- `text` MUST be non-empty after normalization (empty text nodes forbidden).
-- Adjacent text nodes with identical `marks` and identical `attrs.preserveWhiteSpace` MUST be merged.
-- Export MUST handle whitespace correctly within `w:t`, using XML whitespace preservation rules (`xml:space="preserve"`) when needed. WordprocessingML text handling depends on XML space preservation semantics. citeturn3search9turn12search11
-
-**WordprocessingML mapping:** `text` maps to `<w:r><w:t>...</w:t></w:r>` with `w:rPr` derived from marks. `w:r` is the container for run content. citeturn3search1turn7search11
-
-#### Hard break
-
-```ts
-export interface HardBreakNode extends NodeBase {
-  type: "hardBreak";
-  attrs: {
-    // Word supports variants; default is line break
-    break: "line";
-  };
-}
-```
-
-**WordprocessingML mapping:** `<w:br/>` in run content. A break overrides normal line breaking. citeturn3search3turn3search17
-
-#### Hyperlink
-
-Word hyperlinks are represented by `<w:hyperlink>` with either a relationship id (`r:id`) for external targets or an `anchor` for internal targets; if `id` exists it supersedes `anchor`. citeturn1search2
-
-```ts
-export interface HyperlinkNode extends NodeBase {
-  type: "hyperlink";
-  children: InlineNode[]; // typically text + marks
-
-  attrs: {
-    href?: string;              // external target
-    relationshipId?: RelationshipId; // optional; if absent, exporter generates a relationship
-    anchor?: string;            // internal target bookmark name
-    history?: boolean;
-    tooltip?: string;
-    targetFrame?: string;
-
-    // Optional explicit character style for hyperlink runs
-    characterStyleId?: string; // maps to run style w:rStyle in contained runs citeturn4search5
-
-    ooxmlUnknown?: PreservedXmlRef;
-  };
-}
-```
-
-**Constraints:**
-- Must contain at least one inline child after normalization (if empty, insert a single `TextNode` with `" "`).
-- If `relationshipId` present, exporter MUST create/update a relationship with that id in the main document relationships part for the hyperlink target.
-- If both `href` and `anchor` set, exporter MUST prefer external relationship semantics (consistent with OOXML “id supersedes anchor”). citeturn1search2
-
-**WordprocessingML mapping:** `<w:hyperlink r:id="..."> ... </w:hyperlink>`. citeturn1search2
-
-#### Inline image
-
-```ts
-export interface InlineImageNode extends NodeBase {
-  type: "inlineImage";
-  children: []; // leaf inline atom
-
-  attrs: {
-    mediaId: Id;
-    altText?: string;
-
-    widthTwips?: Twips;
-    heightTwips?: Twips;
-
-    // Export uses DrawingML inline
-    drawing: "wp:inline";
-
-    ooxmlUnknown?: PreservedXmlRef;
-  };
-}
-```
-
-**Constraints:** `mediaId` MUST exist.
-
-**WordprocessingML mapping:** Run with `w:drawing/wp:inline` referencing an embedded relationship to the image part. `wp:inline` indicates in-line positioning. citeturn2search10turn2search14
-
-#### Anchor placeholder
-
-This is a **zero-width addressable inline atom** used to ensure valid selections and to provide stable “point anchors” in cases where empty paragraphs/cells must remain selectable.
-
-```ts
-export interface AnchorPlaceholderNode extends NodeBase {
-  type: "anchor";
-  children: [];
-
-  attrs: {
-    role: "selection" | "emptyParagraph" | "emptyCell";
-  };
-}
-```
-
-**Export behavior:** Exporter MUST NOT emit any visible glyph. It may emit an empty run (`<w:r/>`) if necessary to satisfy Word’s XML constraints for empty paragraphs.
-
-#### Opaque preserved inline node
-
-```ts
-export interface OoxmlInlineNode extends NodeBase {
-  type: "ooxmlInline";
-  children: [];
-
-  attrs: {
-    fragmentId: Id;
-    editability: "locked";
-    description?: string;
-  };
-}
-```
-
-Used for unsupported inline OOXML (complex fields, content controls inline, markup-compat alternate branches, etc.). Markup compatibility preservation applies. citeturn2search3turn2search7
-
-### Marks (inline formatting)
-
-Run properties in Word are encoded using `<w:rPr>` elements inside runs. citeturn7search11turn8search3turn8search1turn8search2
-
-```ts
-export type Mark =
-  | BoldMark
-  | ItalicMark
-  | UnderlineMark
-  | StrikeMark
-  | CodeMark
-  | SubscriptMark
-  | SuperscriptMark
-  | TextStyleMark;
-
-export interface MarkBase {
-  type: string;
-  attrs?: Record<string, unknown>;
-}
-```
-
-#### Bold
-
-```ts
-export interface BoldMark extends MarkBase {
-  type: "bold";
-}
-```
-
-**WordprocessingML mapping:** `<w:b/>` toggle. citeturn7search0turn7search7
-
-#### Italic
-
-```ts
-export interface ItalicMark extends MarkBase {
-  type: "italic";
-}
-```
-
-**WordprocessingML mapping:** `<w:i/>`. citeturn7search8turn7search11
-
-#### Underline
-
-```ts
-export interface UnderlineMark extends MarkBase {
-  type: "underline";
-  attrs: {
-    style: "single" | "double" | "dotted" | "dash" | "wave" | "none";
-  };
-}
-```
-
-**WordprocessingML mapping:** `<w:u w:val="..."/>`, where `val` is an underline style enumeration and `none` is equivalent to no underline. citeturn7search2turn7search20
-
-#### Strike
-
-```ts
-export interface StrikeMark extends MarkBase {
-  type: "strike";
-}
-```
-
-**WordprocessingML mapping:** `<w:strike/>` toggle. citeturn8search0turn8search4
-
-#### Code
-
-```ts
-export interface CodeMark extends MarkBase {
-  type: "code";
-  attrs?: {
-    // If set, reference a character style intended for code formatting.
-    characterStyleId?: string;
-  };
-}
-```
-
-**WordprocessingML mapping (deterministic):**
-- If `characterStyleId` provided, exporter MUST emit `w:rPr/w:rStyle` for runs in the code span. citeturn4search5turn2search4
-- Otherwise exporter MUST emit a monospace font via `w:rPr/w:rFonts` for ASCII + hAnsi at minimum, preserving any existing font theme attributes if present. `w:rFonts` controls fonts for Unicode subsets. citeturn8search3turn8search7turn8search15
-
-#### Subscript and superscript
-
-```ts
-export interface SubscriptMark extends MarkBase {
-  type: "subscript";
-}
-export interface SuperscriptMark extends MarkBase {
-  type: "superscript";
-}
-```
-
-**WordprocessingML mapping:** `<w:vertAlign w:val="subscript|superscript"/>`. citeturn7search3turn7search10
-
-#### Text style (font, color, size, highlight)
-
-```ts
-export interface TextStyleMark extends MarkBase {
-  type: "textStyle";
-  attrs: {
-    // Font: either explicit family or theme-based; exporter must preserve theme attributes if present.
-    font?: {
-      ascii?: string;
-      hAnsi?: string;
-      eastAsia?: string;
-      cs?: string;
-      asciiTheme?: string;
-      hAnsiTheme?: string;
-      eastAsiaTheme?: string;
-      csTheme?: string;
-    };
-
-    // Color: explicit RGB or "auto"
-    color?: { val: HexColorRGB | "auto" };
-
-    // Font size in half-points, per OOXML sz semantics
-    size?: { halfPoints: HalfPoints };
-
-    // Highlight
-    highlight?: { val: string };
-
-    // Preservation
-    ooxmlUnknown?: PreservedXmlRef;
-  };
-}
-```
-
-**WordprocessingML mapping:**
-- Font via `w:rFonts` (font selection per Unicode range). citeturn8search3turn8search7turn8search15
-- Color via `w:color`. citeturn8search1turn8search13
-- Size via `w:sz` half-point values. citeturn8search2turn8search14
-- Highlight via `w:highlight`. citeturn8search5
-
-### Mark stacking, exclusivity, and normalization
-
-**Rule M1 (Canonical mark order):** Marks on a `TextNode` MUST be sorted by this stable order:
-`bold`, `italic`, `underline`, `strike`, `code`, `subscript`, `superscript`, `textStyle`.
-
-**Rule M2 (Exclusivity):**
-- `subscript` and `superscript` are mutually exclusive. If both appear, normalization MUST keep the later-applied mark and drop the other, emitting a warning diagnostic.
-
-**Rule M3 (Merge adjacent text):**
-Two adjacent `TextNode`s MUST be merged if:
-- their mark arrays are deeply equal,
-- their `attrs.preserveWhiteSpace` values are equal.
-
-**Rule M4 (Empty text forbidden):**
-Any `TextNode` with `text.length === 0` MUST be removed. If that would leave a paragraph empty, insert an `AnchorPlaceholderNode`.
-
-## Structural rules and normalization
-
-### Allowed nesting graph (complete)
-
-The allowed parent → child relationships are:
-
-- `doc` → any `BlockNode`.
-- `paragraph` / `heading` → any `InlineNode`.
-- `blockquote` → any `BlockNode` except `SectionBreakNode` (normalized by hoisting).
-- `orderedList` / `bulletList` → `listItem`.
-- `listItem` → any `BlockNode` except `SectionBreakNode` (hoisted).
-- `table` → `tableRow`.
-- `tableRow` → `tableCell`.
-- `tableCell` → any `BlockNode` (but normalized to contain at least one paragraph/heading).
-- `ooxmlBlock` → no children.
-- `hyperlink` → `InlineNode` (but not `hyperlink` nested inside `hyperlink`; normalization unwraps inner link).
-- `inlineImage`, `hardBreak`, `anchor`, `ooxmlInline` → no children.
-
-### Illegal structures (and deterministic repairs)
-
-The engine MUST run normalization after:
-- import,
-- each transaction,
-- before export.
-
-Normalization MUST be deterministic and idempotent.
-
-#### Repair rules
-
-**Repair R1 (Doc root type):** If `content.type !== "doc"`, reject as fatal validation error.
-
-**Repair R2 (Paragraph empty):** If `paragraph.children.length === 0`, set to `[ {type:"anchor", role:"emptyParagraph"} ]`.
-
-**Repair R3 (Table cell empty):** If `tableCell.children.length === 0`, insert a single empty paragraph containing an anchor placeholder.
-
-**Repair R4 (List item first block):** If first child of `listItem` is not `paragraph|heading`, insert an empty paragraph at index 0.
-
-**Repair R5 (Nested hyperlink):** If a `hyperlink` contains a descendant `hyperlink`, normalization MUST unwrap the inner hyperlink by replacing it with its children.
-
-**Repair R6 (Section break inside containers):** If `SectionBreakNode` appears within `blockquote` or `listItem`, hoist it to the nearest ancestor that is a direct child of `doc`. Hoisting preserves relative order by inserting immediately after the container block that contained it.
-
-**Repair R7 (Adjacent lists):** Adjacent lists of same `kind|numId|baseIlvl` MUST be merged.
-
-**Repair R8 (Marks):** Enforce M1–M4; emit diagnostics on conflicts.
-
-### Explicit examples of valid vs invalid structures
-
-#### Valid
-
-```json
-{
-  "type": "paragraph",
-  "children": [
-    { "type": "text", "text": "Hello", "marks": [], "id": "t1" },
-    { "type": "hardBreak", "attrs": { "break": "line" }, "id": "br1" },
-    { "type": "text", "text": "World", "marks": [{ "type": "bold" }], "id": "t2" }
-  ],
-  "attrs": {},
-  "id": "p1"
-}
-```
-
-#### Invalid → corrected (empty cell)
-
-Invalid:
-
-```json
-{ "type": "tableCell", "children": [], "attrs": {}, "id": "c1" }
-```
-
-Corrected by R3:
-
-```json
-{
-  "type": "tableCell",
-  "children": [
-    {
-      "type": "paragraph",
-      "children": [{ "type": "anchor", "children": [], "attrs": { "role": "emptyCell" }, "id": "a1" }],
-      "attrs": {},
-      "id": "p1"
-    }
-  ],
-  "attrs": {},
-  "id": "c1"
-}
-```
-
-## Positions, ranges, selections, and transactions
-
-### Global position indexing model
-
-CDS uses a **single integer-based coordinate space** over the content tree, based on tokenized traversal rules (ProseMirror-style linear positions). This avoids path fragility and supports deterministic mapping across edits. Positions are similar to the documented concept where entering/leaving non-leaf nodes counts as tokens and each character counts as one token. citeturn9search4
-
-#### Node size rules
-
-Let `size(node)` be defined:
-
-- For `TextNode`: `size = numberOfUnicodeCodePoints(text)`.
-- For inline leaf atom nodes (`hardBreak`, `inlineImage`, `anchor`, `ooxmlInline`): `size = 1`.
-- For block leaf nodes (`imageBlock`, `horizontalRule`, `sectionBreak`, `ooxmlBlock`): `size = 1`.
-- For container nodes (all others):  
-  `size = 2 + sum(size(child) for child in children)`  
-  where the `2` accounts for the container’s **start** and **end** tokens.
-
-This is consistent with the notion that entering/leaving a node counts as tokens and leaf nodes count as a single token. citeturn9search4turn9search19
-
-#### Position domain
-
-```ts
-export type DocPos = number; // integer
-
-export interface DocRange {
-  from: DocPos; // inclusive
-  to: DocPos;   // exclusive, must satisfy from <= to
-}
-```
-
-**Invariant PZ1:** `0 <= from <= to <= size(doc)`.
-
-### Selections
-
-```ts
-export type Selection =
-  | TextSelection
-  | NodeSelection
-  | BlockSelection;
-
-export interface TextSelection {
-  kind: "text";
-  range: DocRange;
-  // assoc controls stickiness when mapping through insertions at boundaries
-  assoc: { start: -1 | 1; end: -1 | 1 };
-}
-
-export interface NodeSelection {
-  kind: "node";
-  // selects exactly one atomic node token (leaf: size 1)
-  at: DocPos;
-}
-
-export interface BlockSelection {
-  kind: "block";
-  // selects whole blocks by spanning their token ranges
-  range: DocRange;
-}
-```
-
-**Collapsed vs expanded:**
-- Collapsed selection: `range.from === range.to`.
-- Expanded selection: `range.from < range.to`.
-
-### Transactions and steps
-
-Transactions are the only permitted mutation mechanism.
-
-```ts
-export interface Transaction {
-  txId: UUID;
-  createdAt: ISO8601DateTime;
-  actorId: Id;
-
-  // Steps applied in order
-  steps: Step[];
-
-  // Selection before/after (optional but recommended)
-  selectionBefore?: Selection;
-  selectionAfter?: Selection;
-
-  // Arbitrary metadata
-  meta?: Record<string, unknown>;
-}
-```
-
-#### Steps
-
-```ts
-export type Step =
-  | ReplaceStep
-  | AddMarkStep
-  | RemoveMarkStep
-  | SetNodeAttrsStep;
-
-export interface ReplaceStep {
-  type: "replace";
-  from: DocPos;
-  to: DocPos;
-  slice: Slice; // content fragment to insert
-}
-
-export interface AddMarkStep {
-  type: "addMark";
-  from: DocPos;
-  to: DocPos;
-  mark: Mark;
-}
-
-export interface RemoveMarkStep {
-  type: "removeMark";
-  from: DocPos;
-  to: DocPos;
-  markType: Mark["type"];
-}
-
-export interface SetNodeAttrsStep {
-  type: "setNodeAttrs";
-  // position that resolves to a node boundary (start token of node)
-  at: DocPos;
-  // shallow partial patch (implementation must validate types)
-  patch: Record<string, unknown>;
-}
-```
-
-**Slice definition:**
-
-```ts
-export interface Slice {
-  // A slice is a fragment of block or inline content with open depth metadata.
-  // For this CDS version, slices are always "closed" (openStart=openEnd=0).
-  openStart: 0;
-  openEnd: 0;
-
-  // Content to insert
-  content: Node[]; // must be valid at insertion point post-normalization
-}
-```
-
-### Mapping model
-
-Every step produces a `StepMap` that maps old positions to new positions.
-
-```ts
-export interface StepMap {
-  // A list of [start, oldSize, newSize] triples describing replacements
-  ranges: Array<[number, number, number]>;
-}
-
-export interface Mapping {
-  maps: StepMap[];
-}
-```
-
-**Mapping behavior:** Applying a step shifts positions after the replaced range by `(newSize - oldSize)`. This aligns with the well-established “step provides a change map mapping positions” pattern. citeturn6search0turn9search4
-
-**Mapping function (normative):**
-
-```ts
-export function mapPos(pos: DocPos, map: StepMap, assoc: -1|1): DocPos;
-export function mapRange(range: DocRange, mapping: Mapping, assoc: {start:-1|1, end:-1|1}): DocRange;
-```
-
-Normative rules:
-
-- For each `[start, oldSize, newSize]`:
-  - Let `end = start + oldSize`.
-  - If `pos < start`: unchanged.
-  - If `pos > end`: `pos += (newSize - oldSize)`.
-  - If `start <= pos <= end` (inside replaced region):
-    - If `assoc === -1`, map to `start`.
-    - If `assoc === 1`, map to `start + newSize`.
-
-After applying all ranges in order, return final `pos`.
-
-**Transaction guarantees:**
-- After applying all steps and normalization, the engine MUST remap:
-  - `selectionAfter` if omitted (derive by mapping `selectionBefore`),
-  - all comment anchors and revision targets (rules below),
-  - preservation bindings (rules below),
-  - and MUST ensure invariants hold or emit diagnostics.
-
-## Annotations: comments and tracked changes
-
-### Comment anchor model
-
-Word comments consist of:
-- a comment body stored in the comments part, and
-- anchor/range markup in the main document linking by id. citeturn0search4turn0search8
-
-A comment not referenced by content via a matching id may be ignored by consumers, so linkage integrity is mandatory on export. citeturn0search4
-
-#### Data structures
-
-```ts
-export interface CommentStore {
-  threads: Record<Id, CommentThread>; // key = threadId
-  comments: Record<Id, Comment>;      // key = commentId
-}
-
-export interface CommentThread {
-  threadId: Id;
-
-  // Anchor for the thread in the main document
-  anchor: CommentAnchor;
-
-  // Ordered list of commentIds (first is root comment)
-  commentIds: Id[];
-
-  // Status
-  resolved?: boolean;
-  resolvedAt?: ISO8601DateTime;
-  resolvedBy?: Id;
-
-  // Import/export fidelity
-  ooxmlCommentId?: number; // Word w:id (integer)
-}
-
-export interface Comment {
-  commentId: Id;
-  threadId: Id;
-  authorId: Id;
-  createdAt: ISO8601DateTime;
-
-  // Rich content stored as a mini-doc fragment
-  body: CommentBody;
-
-  // Threading
-  parentCommentId?: Id;
-
-  // Optional edits
-  editedAt?: ISO8601DateTime;
-
-  // OOXML preservation
-  ooxmlUnknown?: PreservedXmlRef;
-}
-
-export interface CommentBody {
-  blocks: BlockNode[]; // same block model; must normalize to valid mini-doc
-}
-```
-
-#### Anchor representation
-
-```ts
-export type CommentAnchor =
-  | RangeAnchor
-  | NodeAnchor
-  | OrphanAnchor;
-
-export interface RangeAnchor {
-  kind: "range";
-  range: DocRange;
-  assoc: { start: -1 | 1; end: -1 | 1 };
-
-  // Context used for degraded reattachment
-  quote?: AnchorQuote;
-}
-
-export interface NodeAnchor {
-  kind: "node";
-  // Selects an atomic node token, such as imageBlock/table/ooxmlBlock
-  at: DocPos;
-  assoc: -1 | 1;
-  quote?: AnchorQuote;
-}
-
-export interface OrphanAnchor {
-  kind: "orphan";
-  lastKnownRange: DocRange;
-  orphanedAt: ISO8601DateTime;
-  reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
-  quote?: AnchorQuote;
-}
-
-export interface AnchorQuote {
-  selectedText?: string; // up to 64 Unicode code points
-  prefix?: string;       // up to 32 code points before
-  suffix?: string;       // up to 32 code points after
-}
-```
-
-#### Anchor survival rules under edits
-
-**Rule C1 (Primary remap):** On every transaction, if anchor is `range` or `node`, remap positions using the transaction’s `Mapping`.
-
-**Rule C2 (Deletion collapse):** If a `RangeAnchor` maps to `range.from === range.to` and the pre-map range length was > 0, mark it as **degraded**:
-- keep as `RangeAnchor` but set `quote.selectedText` unchanged,
-- and add a warning diagnostic, unless content-based reattachment succeeds.
-
-**Rule C3 (Orphaning):** If mapping produces out-of-bounds, or if the anchor points into a region that no longer corresponds to valid selectable content (e.g., removed node), convert to `OrphanAnchor`.
-
-**Rule C4 (Content-based reattachment):** If anchor becomes degraded/orphaned and has a `quote.selectedText`, attempt deterministic reattachment:
-- search for exact occurrences of `selectedText` within ±1000 positions of `lastKnownRange.from` in the document’s extracted plain text,
-- filter by matching `prefix` and `suffix` when present,
-- choose the match with smallest distance; tie-break by lowest position,
-- if exactly one winner, re-anchor to that range; else remain orphaned.
-
-**Rule C5 (Block targets):** To anchor to blocks (tables/images), use `NodeAnchor` selecting the atomic leaf token that represents the block (size 1).
-
-#### WordprocessingML export expectations for comments
-
-Exporter MUST generate:
-
-- `commentRangeStart` at the mapped `from`,
-- `commentRangeEnd` at the mapped `to`,
-- a `commentReference` run linked by the same id, as required to create a link to a comment. citeturn0search0turn0search8
-- a corresponding `<w:comment w:id="...">...</w:comment>` in the comments part. citeturn0search4
-
-### Revision (tracked changes) model
-
-Word’s track revisions setting indicates that revisions are recorded so they can be viewed/accepted/reverted; OOXML defines specific revision markup syntax. citeturn10search3turn10search5
-
-#### Core structures
-
-```ts
-export interface RevisionStore {
-  trackRevisions: boolean; // maps to settings.xml w:trackRevisions citeturn10search3turn10search13
-
-  items: Record<Id, Revision>; // key = revisionId
-}
-
-export type Revision =
-  | InsertionRevision
-  | DeletionRevision
-  | FormatRevision
-  | MoveRevision;
-
-export interface RevisionBase {
-  revisionId: Id;
-  authorId: Id;
-  createdAt: ISO8601DateTime;
-
-  state: "active" | "accepted" | "rejected";
-
-  // Word revision identifier (w:id). Required for stable docx export.
-  ooxmlRevisionId?: number;
-
-  // Optional preservation
-  ooxmlUnknown?: PreservedXmlRef;
-}
-```
-
-#### Insertion
-
-Inserted run content is represented using `w:ins` containers in WordprocessingML. citeturn1search0turn11search19
-
-```ts
-export interface InsertionRevision extends RevisionBase {
-  kind: "insertion";
-  range: DocRange;
-  assoc: { start: -1 | 1; end: -1 | 1 };
-}
-```
-
-**Invariant R-INS1:** `range.from < range.to` when `state="active"`.
-
-#### Deletion
-
-Deleted run content is represented by `w:del` containing the deleted content (often using `w:delText`). citeturn1search1turn1search5turn10search6
-
-```ts
-export interface DeletionRevision extends RevisionBase {
-  kind: "deletion";
-
-  // Point where deletion occurred in the *current* content
-  at: DocPos;
-  assoc: -1 | 1;
-
-  // Payload is the deleted content captured at deletion time
-  deletedSlice: Slice;
-
-  // Optional original range (for UI); may be used for reattachment
-  originalRange?: DocRange;
-  quote?: AnchorQuote;
-}
-```
-
-**Invariant R-DEL1:** `deletedSlice.content.length > 0` when `state="active"`.
-
-#### Formatting revisions
-
-Word tracks some formatting changes via `pPrChange` and `rPrChange`, which store the previous property set and revision metadata. citeturn11search1turn11search0
-
-```ts
-export interface FormatRevision extends RevisionBase {
-  kind: "format";
-
-  scope: "run" | "paragraph";
-  range: DocRange;
-
-  // Canonical before/after representation of formatting
-  before: { marks?: Mark[]; paragraphAttrs?: Partial<ParagraphAttrs> };
-  after:  { marks?: Mark[]; paragraphAttrs?: Partial<ParagraphAttrs> };
-}
-```
-
-#### Move operations (model-aware, optional)
-
-Word supports move tracking with move-range markers and move containers. citeturn11search6turn11search3turn11search11turn11search7
-
-```ts
-export interface MoveRevision extends RevisionBase {
-  kind: "move";
-
-  fromRange: DocRange;
-  toRange: DocRange;
-
-  // Optional payload snapshot for robustness
-  movedSlice?: Slice;
-}
-```
-
-### Revision representation without corrupting structure
-
-**Rule TR1 (No structural wrappers):** Revisions MUST NOT wrap content nodes in the CDS tree. They are separate records referencing positions/ranges.
-
-**Rule TR2 (Export materialization):**
-- Active insertions MUST export as `w:ins` containers around run-level content. citeturn1search0
-- Active deletions MUST export as `w:del` containers with deleted run content using `w:delText` where appropriate. citeturn1search1turn1search5
-- Paragraph mark deletions MUST export using the correct WordprocessingML form for deleted paragraphs/paragraph marks. WordprocessingML defines deleted paragraph semantics. citeturn10search0
-
-### Overlaps, nesting, and invariants
-
-**Invariant TR-O1 (No conflicting active insertion overlap):** Two active insertion revisions MUST NOT overlap in position space. If a new insertion overlaps, normalization MUST split/merge deterministically:
-- If same author and createdAt within 5 minutes and insertion is adjacent/overlapping due to mapping, merge into one range.
-- Otherwise split such that ranges are disjoint and preserve order.
-
-**Invariant TR-O2 (Deletion anchored at a point):** Deletions are point-anchored and can coexist with insertions, but exporter must order emitted OOXML deterministically: deletions first at a position, then insertions.
-
-**Invariant TR-O3 (Format revisions):** Format revisions may overlap insertions/deletions, but export must emit `rPrChange/pPrChange` only for scope-specific changes, preserving OOXML constraints. citeturn11search0turn11search1
-
-### Accept/reject rules (exact)
-
-Let `rev` be a revision.
-
-#### Accept insertion
-
-- Preconditions: `rev.kind="insertion"`.
-- Effect:
-  1. Remove `rev` from `revisions.items`.
-  2. Content remains unchanged (inserted text becomes “normal”).
-  3. Emit transaction steps:
-     - none on content,
-     - a revision-store removal event (implementation-defined but must be atomic with document update).
-
-#### Reject insertion
-
-- Preconditions: `rev.kind="insertion"`.
-- Effect:
-  1. Delete the content in `rev.range` from the document using a `ReplaceStep(from, to, emptySlice)`.
-  2. Remove `rev` from revisions.
-  3. Remap all other anchors through the produced mapping.
-
-#### Accept deletion
-
-- Preconditions: `rev.kind="deletion"`.
-- Effect:
-  1. Remove `rev` from revisions.
-  2. Content remains unchanged (deleted content stays deleted).
-
-#### Reject deletion
-
-- Preconditions: `rev.kind="deletion"`.
-- Effect:
-  1. Insert `rev.deletedSlice` at `rev.at` using `ReplaceStep(at, at, deletedSlice)`.
-  2. Remove `rev`.
-  3. Remap all anchors.
-
-#### Merge revisions
-
-Two active revisions `A` and `B` of same kind MAY merge only if:
-- same authorId,
-- same kind,
-- contiguous after mapping (`A.to === B.from` for insertions; `A.at === B.at` and slice concatenation for deletions),
-- createdAt within merge window (default 5 minutes).
-
-Merging is deterministic: choose smallest revisionId lexicographically as survivor.
-
-## Round-trip preservation, validation, migration, and examples
-
-### Preservation model
-
-#### Goals
-
-Preserve unsupported OOXML in two forms:
-
-1. **Untouched parts**: parts not edited by the CDS editor (headers, footers, footnotes, endnotes, themes, settings, etc.) are preserved as raw bytes and copied back during export.
-2. **Opaque fragments** inside edited parts: unsupported markup embedded in the main document story is preserved as **fragments**, referenced by `ooxmlBlock/ooxmlInline` nodes or by `PreservedXmlRef` fields.
-
-Because `.docx` is an OPC package defined in terms of parts and relationships, preserving unknown parts/relationships is fundamental for compatibility. citeturn0search2turn3search4
-
-Markup Compatibility (e.g., `mc:AlternateContent`) must be preserved when not explicitly supported. citeturn2search3turn2search7
-
-#### Data structures
-
-```ts
-export interface PreservationStore {
-  // XML fragments that can be re-injected into edited parts
-  fragments: Record<Id, PreservedXmlFragment>;
-
-  // OPC package-level preservation
-  opc: OpcPreservation;
-}
-
-export interface PreservedXmlRef {
-  fragmentId: Id;
-}
-
-export interface PreservedXmlFragment {
-  fragmentId: Id;
-  kind: "xmlElement" | "xmlFragment";
-  xmlns: Record<string, string>; // prefix->namespace URI
-  xml: string; // UTF-8 XML text; must be well-formed if wrapped in <cds:frag> by implementation
-
-  // Merge policy
-  policy: "readOnly" | "mergeable";
-
-  // Original location hint for diagnostics
-  source?: { partName: PartName; xpath?: string };
-}
-
-export interface OpcPreservation {
-  // Original [Content_Types].xml bytes
-  contentTypesXmlBase64: Base64;
-
-  // All original parts and relationships
-  parts: Record<PartName, PreservedPart>;
-  relationships: Record<string, Relationship[]>; // key = "package" or partName
-
-  // Parts that CDS regenerates (must be listed explicitly)
-  regeneratedParts: {
-    mainDocument: "/word/document.xml";
-    styles?: "/word/styles.xml";
-    numbering?: "/word/numbering.xml";
-    comments?: "/word/comments.xml";
-    relsMainDocument: "/word/_rels/document.xml.rels";
-  };
-}
-
-export interface PreservedPart {
-  partName: PartName;
-  contentType: string;
-  bytesBase64: Base64;
-  editable: false; // parts are not edited unless explicitly regenerated
-}
-
-export interface Relationship {
-  id: RelationshipId;
-  type: string;   // relationship type URI
-  target: string; // part URI or external URI
-  targetMode?: "External";
-}
-```
-
-### Preservation linking and edit constraints
-
-**Rule PR1 (Fragment integrity):** If a content node references `fragmentId`, that fragment MUST exist and MUST be re-emitted verbatim on export.
-
-**Rule PR2 (Locked regions):** `ooxmlBlock` and `ooxmlInline` nodes are non-editable; attempts to edit inside MUST be rejected and surfaced as a recoverable error diagnostic (editor can still delete the whole atomic node if allowed).
-
-**Rule PR3 (Reattachment):** Opaque fragments represented as nodes reattach automatically because they occupy a position in the content tree. Fragments referenced from `ooxmlUnknown...` fields reattach to their owning node’s corresponding OOXML property container:
-- paragraph `ooxmlUnknownPPr` re-injects into `w:pPr`,
-- run-level unknown re-injects into `w:rPr` for the specific run created from that text span,
-- numbering/style unknown re-injects into the corresponding style/numbering element.
-
-### Validation rules
-
-Validation must classify issues as fatal vs recoverable.
-
-#### Structural validation (fatal unless repairable)
-
-- **V-S1:** Node types and required fields must match unions.
-- **V-S2:** Nesting constraints must hold (graph above).
-- **V-S3:** All IDs must be unique per D3.
-
-If a repair rule exists (R1–R8), the engine MUST repair and emit a warning diagnostic; otherwise fatal.
-
-#### Attribute validation
-
-- **V-A1:** `ParagraphNumbering.ilvl` 0..8.
-- **V-A2:** Heading level 1..9.
-- **V-A3:** Color values must be 6 hex digits or `"auto"`.
-- **V-A4:** Font sizes must be positive half-points. citeturn8search14
-
-#### Anchor validity
-
-- **V-C1:** All anchors positions within 0..size(doc).
-- **V-C2:** Range anchors must satisfy `from<=to`.
-- **V-C3:** Node anchors must resolve to an atomic node token (leaf size=1).
-
-Invalid anchors become `OrphanAnchor` with a warning diagnostic.
-
-#### Revision validity
-
-- **V-R1:** Insertions must have non-empty range.
-- **V-R2:** Deletions must have non-empty deletedSlice.
-- **V-R3:** No overlapping active insertion ranges.
-
-Violations repaired by splitting/merging per deterministic rules, with diagnostics.
-
-#### Preservation integrity
-
-- **V-P1:** All referenced fragment ids exist.
-- **V-P2:** OPC parts referenced in relationships exist unless external.
-- **V-P3:** Regenerated parts must not be simultaneously marked preserved-only.
-
-### Versioning and migration
-
-#### Schema version field
-
-`CanonicalDocument.schemaVersion` is the migration discriminator.
-
-#### Backward compatibility rules
-
-- A loader MUST support `"cds/1.0.0"` documents.
-- The loader MAY accept older versions if a migration function exists; otherwise reject.
-
-#### Forward compatibility handling
-
-If `schemaVersion` is unknown:
-- Reject as fatal, **unless** `preservation.opc` contains the original `.docx` package; in that case the system MAY still allow re-export of the preserved `.docx` without editing (read-only compatibility mode), emitting a fatal diagnostic for editing.
-
-#### Migration strategy (normative)
-
-A migration is defined as:
-
-```ts
-export interface Migration {
-  from: CDS_SchemaVersion;
-  to: CDS_SchemaVersion;
-  migrate(doc: CanonicalDocument): CanonicalDocument;
-}
-```
-
-Rules:
-- Migrations MUST be pure (no external state), deterministic, and idempotent.
-- Each migration MUST run full normalization and validation at the end, emitting diagnostics.
-- Stored documents MUST be migrated incrementally version-by-version (no skipping).
-
-### Examples
-
-All examples below are fully specified CDS JSON documents. IDs are illustrative.
-
-#### Simple document example
-
-```json
-{
-  "schemaVersion": "cds/1.0.0",
-  "docId": "2d6e1c2e-7d15-45a4-8b7a-5f422f18bb3b",
-  "createdAt": "2026-03-25T10:00:00.000Z",
-  "updatedAt": "2026-03-25T10:00:00.000Z",
-  "metadata": {
-    "title": "Simple Doc",
-    "actors": {
-      "u1": { "actorId": "u1", "displayName": "Alex Editor" }
-    }
-  },
-  "content": {
-    "id": "n_doc",
-    "type": "doc",
-    "attrs": { "trackRevisionsDefault": false },
-    "children": [
-      {
-        "id": "p1",
-        "type": "paragraph",
-        "attrs": { "alignment": "left" },
-        "children": [
-          { "id": "t1", "type": "text", "text": "Hello, world!", "marks": [] }
-        ]
-      }
-    ]
-  },
-  "styles": {
-    "defaults": {},
-    "paragraphStyles": {},
-    "characterStyles": {},
-    "tableStyles": {}
-  },
-  "numbering": {
-    "abstractNums": {},
-    "nums": {}
-  },
-  "media": {
-    "items": {},
-    "exportPolicy": {
-      "mediaFolder": "/word/media",
-      "filenameStrategy": "stableByMediaId",
-      "relationshipIdStrategy": "stableByOrder"
-    }
-  },
-  "comments": { "threads": {}, "comments": {} },
-  "revisions": { "trackRevisions": false, "items": {} },
-  "preservation": {
-    "fragments": {},
-    "opc": {
-      "contentTypesXmlBase64": "",
-      "parts": {},
-      "relationships": {},
-      "regeneratedParts": {
-        "mainDocument": "/word/document.xml",
-        "relsMainDocument": "/word/_rels/document.xml.rels"
-      }
-    }
-  },
-  "diagnostics": { "items": [] }
-}
-```
-
-#### Document with lists and tables
-
-```json
-{
-  "schemaVersion": "cds/1.0.0",
-  "docId": "9c2e7d12-0c8b-4bb5-9f0a-5f2d0d0f7d2e",
-  "createdAt": "2026-03-25T10:05:00.000Z",
-  "updatedAt": "2026-03-25T10:05:00.000Z",
-  "metadata": {
-    "title": "Lists and Tables",
-    "actors": {
-      "u1": { "actorId": "u1", "displayName": "Alex Editor" }
-    }
-  },
-  "content": {
-    "id": "doc",
-    "type": "doc",
-    "attrs": { "trackRevisionsDefault": false },
-    "children": [
-      {
-        "id": "h1",
-        "type": "heading",
-        "attrs": { "level": 1, "styleId": "Heading1" },
-        "children": [{ "id": "ht1", "type": "text", "text": "Project Status", "marks": [] }]
-      },
-      {
-        "id": "ol1",
-        "type": "orderedList",
-        "attrs": { "kind": "ordered", "numId": "num1", "baseIlvl": 0 },
-        "children": [
-          {
-            "id": "li1",
-            "type": "listItem",
-            "attrs": {},
-            "children": [
-              {
-                "id": "p_li1",
-                "type": "paragraph",
-                "attrs": { "numbering": { "numId": "num1", "ilvl": 0 } },
-                "children": [{ "id": "t_li1", "type": "text", "text": "Define scope", "marks": [] }]
-              }
-            ]
-          },
-          {
-            "id": "li2",
-            "type": "listItem",
-            "attrs": {},
-            "children": [
-              {
-                "id": "p_li2",
-                "type": "paragraph",
-                "attrs": { "numbering": { "numId": "num1", "ilvl": 0 } },
-                "children": [{ "id": "t_li2", "type": "text", "text": "Build prototype", "marks": [] }]
-              }
-            ]
-          }
-        ]
-      },
-      {
-        "id": "tbl1",
-        "type": "table",
-        "attrs": { "grid": { "colWidthsTwips": [3000, 5000] } },
-        "children": [
-          {
-            "id": "tr1",
-            "type": "tableRow",
-            "attrs": {},
-            "children": [
-              {
-                "id": "tc1",
-                "type": "tableCell",
-                "attrs": {},
-                "children": [
-                  {
-                    "id": "p_tc1",
-                    "type": "paragraph",
-                    "attrs": {},
-                    "children": [{ "id": "t_tc1", "type": "text", "text": "Owner", "marks": [{ "type": "bold" }] }]
-                  }
-                ]
-              },
-              {
-                "id": "tc2",
-                "type": "tableCell",
-                "attrs": {},
-                "children": [
-                  {
-                    "id": "p_tc2",
-                    "type": "paragraph",
-                    "attrs": {},
-                    "children": [{ "id": "t_tc2", "type": "text", "text": "Alex", "marks": [] }]
-                  }
-                ]
-              }
-            ]
-          }
-        ]
-      }
-    ]
-  },
-  "styles": { "defaults": {}, "paragraphStyles": {}, "characterStyles": {}, "tableStyles": {} },
-  "numbering": {
-    "abstractNums": {
-      "abs1": { "abstractNumId": "abs1", "levels": { "0": { "level": 0, "numFmt": "decimal", "lvlText": "%1." } } }
-    },
-    "nums": { "num1": { "numId": "num1", "abstractNumId": "abs1" } }
-  },
-  "media": {
-    "items": {},
-    "exportPolicy": { "mediaFolder": "/word/media", "filenameStrategy": "stableByMediaId", "relationshipIdStrategy": "stableByOrder" }
-  },
-  "comments": { "threads": {}, "comments": {} },
-  "revisions": { "trackRevisions": false, "items": {} },
-  "preservation": {
-    "fragments": {},
-    "opc": {
-      "contentTypesXmlBase64": "",
-      "parts": {},
-      "relationships": {},
-      "regeneratedParts": { "mainDocument": "/word/document.xml", "relsMainDocument": "/word/_rels/document.xml.rels" }
-    }
-  },
-  "diagnostics": { "items": [] }
-}
-```
-
-#### Document with comments
-
-```json
-{
-  "schemaVersion": "cds/1.0.0",
-  "docId": "f88c2c0a-5f7a-4a1a-8a9c-8f0a2a4b3c11",
-  "createdAt": "2026-03-25T10:10:00.000Z",
-  "updatedAt": "2026-03-25T10:10:00.000Z",
-  "metadata": {
-    "title": "Comments Example",
-    "actors": {
-      "u1": { "actorId": "u1", "displayName": "Alex Editor" },
-      "u2": { "actorId": "u2", "displayName": "Casey Reviewer" }
-    }
-  },
-  "content": {
-    "id": "doc",
-    "type": "doc",
-    "attrs": { "trackRevisionsDefault": false },
-    "children": [
-      {
-        "id": "p1",
-        "type": "paragraph",
-        "attrs": {},
-        "children": [
-          { "id": "t1", "type": "text", "text": "Please review this sentence.", "marks": [] }
-        ]
-      }
-    ]
-  },
-  "styles": { "defaults": {}, "paragraphStyles": {}, "characterStyles": {}, "tableStyles": {} },
-  "numbering": { "abstractNums": {}, "nums": {} },
-  "media": {
-    "items": {},
-    "exportPolicy": { "mediaFolder": "/word/media", "filenameStrategy": "stableByMediaId", "relationshipIdStrategy": "stableByOrder" }
-  },
-  "comments": {
-    "threads": {
-      "th1": {
-        "threadId": "th1",
-        "anchor": {
-          "kind": "range",
-          "range": { "from": 2, "to": 28 },
-          "assoc": { "start": -1, "end": 1 },
-          "quote": { "selectedText": "review this sentence" }
-        },
-        "commentIds": ["c1"],
-        "resolved": false,
-        "ooxmlCommentId": 0
-      }
-    },
-    "comments": {
-      "c1": {
-        "commentId": "c1",
-        "threadId": "th1",
-        "authorId": "u2",
-        "createdAt": "2026-03-25T10:10:00.000Z",
-        "body": {
-          "blocks": [
-            {
-              "id": "cp1",
-              "type": "paragraph",
-              "attrs": {},
-              "children": [{ "id": "ct1", "type": "text", "text": "Looks good, but consider tightening wording.", "marks": [] }]
-            }
-          ]
-        }
-      }
-    }
-  },
-  "revisions": { "trackRevisions": false, "items": {} },
-  "preservation": {
-    "fragments": {},
-    "opc": {
-      "contentTypesXmlBase64": "",
-      "parts": {},
-      "relationships": {},
-      "regeneratedParts": { "mainDocument": "/word/document.xml", "comments": "/word/comments.xml", "relsMainDocument": "/word/_rels/document.xml.rels" }
-    }
-  },
-  "diagnostics": { "items": [] }
-}
-```
-
-#### Document with tracked changes
-
-```json
-{
-  "schemaVersion": "cds/1.0.0",
-  "docId": "c1a76d6b-2f15-4c5f-9a4b-b3c9a7d1a0e2",
-  "createdAt": "2026-03-25T10:15:00.000Z",
-  "updatedAt": "2026-03-25T10:15:00.000Z",
-  "metadata": {
-    "title": "Tracked Changes Example",
-    "actors": {
-      "u1": { "actorId": "u1", "displayName": "Alex Editor" }
-    }
-  },
-  "content": {
-    "id": "doc",
-    "type": "doc",
-    "attrs": { "trackRevisionsDefault": true },
-    "children": [
-      {
-        "id": "p1",
-        "type": "paragraph",
-        "attrs": {},
-        "children": [
-          { "id": "t1", "type": "text", "text": "The quick brown fox.", "marks": [] }
-        ]
-      }
-    ]
-  },
-  "styles": { "defaults": {}, "paragraphStyles": {}, "characterStyles": {}, "tableStyles": {} },
-  "numbering": { "abstractNums": {}, "nums": {} },
-  "media": {
-    "items": {},
-    "exportPolicy": { "mediaFolder": "/word/media", "filenameStrategy": "stableByMediaId", "relationshipIdStrategy": "stableByOrder" }
-  },
-  "comments": { "threads": {}, "comments": {} },
-  "revisions": {
-    "trackRevisions": true,
-    "items": {
-      "r_ins_1": {
-        "revisionId": "r_ins_1",
-        "kind": "insertion",
-        "authorId": "u1",
-        "createdAt": "2026-03-25T10:15:00.000Z",
-        "state": "active",
-        "ooxmlRevisionId": 1,
-        "range": { "from": 6, "to": 11 },
-        "assoc": { "start": -1, "end": 1 }
-      },
-      "r_del_1": {
-        "revisionId": "r_del_1",
-        "kind": "deletion",
-        "authorId": "u1",
-        "createdAt": "2026-03-25T10:15:00.000Z",
-        "state": "active",
-        "ooxmlRevisionId": 2,
-        "at": 16,
-        "assoc": -1,
-        "deletedSlice": {
-          "openStart": 0,
-          "openEnd": 0,
-          "content": [
-            { "id": "dt1", "type": "text", "text": "brown ", "marks": [] }
-          ]
-        },
-        "quote": { "selectedText": "brown " }
-      }
-    }
-  },
-  "preservation": {
-    "fragments": {},
-    "opc": {
-      "contentTypesXmlBase64": "",
-      "parts": {},
-      "relationships": {},
-      "regeneratedParts": { "mainDocument": "/word/document.xml", "relsMainDocument": "/word/_rels/document.xml.rels" }
-    }
-  },
-  "diagnostics": { "items": [] }
-}
-```
-
-#### Document with preserved unsupported content
-
-```json
-{
-  "schemaVersion": "cds/1.0.0",
-  "docId": "1f5ef4e7-9e2c-4f77-9a4e-1a0d4f6c9c31",
-  "createdAt": "2026-03-25T10:20:00.000Z",
-  "updatedAt": "2026-03-25T10:20:00.000Z",
-  "metadata": {
-    "title": "Preservation Example",
-    "actors": {
-      "u1": { "actorId": "u1", "displayName": "Alex Editor" }
-    }
-  },
-  "content": {
-    "id": "doc",
-    "type": "doc",
-    "attrs": {},
-    "children": [
-      {
-        "id": "p1",
-        "type": "paragraph",
-        "attrs": {},
-        "children": [{ "id": "t1", "type": "text", "text": "Before preserved block.", "marks": [] }]
-      },
-      {
-        "id": "x1",
-        "type": "ooxmlBlock",
-        "attrs": {
-          "fragmentId": "frag_altcontent_1",
-          "editability": "locked",
-          "description": "Unsupported mc:AlternateContent payload"
-        },
-        "children": []
-      },
-      {
-        "id": "p2",
-        "type": "paragraph",
-        "attrs": {},
-        "children": [{ "id": "t2", "type": "text", "text": "After preserved block.", "marks": [] }]
-      }
-    ]
-  },
-  "styles": { "defaults": {}, "paragraphStyles": {}, "characterStyles": {}, "tableStyles": {} },
-  "numbering": { "abstractNums": {}, "nums": {} },
-  "media": {
-    "items": {},
-    "exportPolicy": { "mediaFolder": "/word/media", "filenameStrategy": "stableByMediaId", "relationshipIdStrategy": "stableByOrder" }
-  },
-  "comments": { "threads": {}, "comments": {} },
-  "revisions": { "trackRevisions": false, "items": {} },
-  "preservation": {
-    "fragments": {
-      "frag_altcontent_1": {
-        "fragmentId": "frag_altcontent_1",
-        "kind": "xmlElement",
-        "xmlns": { "mc": "http://schemas.openxmlformats.org/markup-compatibility/2006" },
-        "xml": "<mc:AlternateContent mc:Ignorable=\"w14\"><mc:Choice Requires=\"w14\"><w14:someFutureFeature xmlns:w14=\"http://schemas.microsoft.com/office/word/2010/wordml\">...</w14:someFutureFeature></mc:Choice><mc:Fallback><w:r xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"><w:t>Fallback</w:t></w:r></mc:Fallback></mc:AlternateContent>",
-        "policy": "readOnly",
-        "source": { "partName": "/word/document.xml", "xpath": "/w:document/w:body/*[2]" }
-      }
-    },
-    "opc": {
-      "contentTypesXmlBase64": "",
-      "parts": {},
-      "relationships": {},
-      "regeneratedParts": { "mainDocument": "/word/document.xml", "relsMainDocument": "/word/_rels/document.xml.rels" }
-    }
-  },
-  "diagnostics": {
-    "items": [
-      {
-        "diagnosticId": "6d0b0b6a-8d5b-4d9b-9a39-8b1b1e1f2d2a",
-        "severity": "warning",
-        "code": "PRESERVE_LOCKED_BLOCK",
-        "message": "Document contains preserved unsupported OOXML block fragment; it is locked and will be round-tripped verbatim.",
-        "createdAt": "2026-03-25T10:20:00.000Z",
-        "location": { "kind": "nodeId", "nodeId": "x1" }
-      }
-    ]
-  }
-}
-```
-
-### Non-goals
-
-The CDS explicitly does **not** attempt to represent:
-
-- exact Word pagination, line breaking, or layout fidelity (these depend on Word’s layout engine and fonts),
-- advanced Word stories as editable content (headers, footers, footnotes, endnotes, text boxes); these are preserved as OPC parts unless explicitly modeled,
-- full fidelity for all OOXML constructs (content controls, complex fields, advanced DrawingML anchoring); unsupported constructs are preserved as opaque fragments or untouched parts,
-- collaborative CRDT semantics (this spec is transactional and mapping-based, single-thread main-thread execution).
-
-### Output quality bar (normative acceptance criteria)
-
-An implementation is conformant to this spec iff:
-
-1. **Schema validity:** It can parse, validate, normalize, and serialize CDS documents matching these interfaces and invariants.
-2. **Deterministic normalization:** Running normalization twice yields identical JSON.
-3. **Anchor stability:** Comment and revision anchors remap through any transaction using the mapping rules, with orphaning only under defined conditions.
-4. **Word-openable export:** Exported `.docx` opens in Word without structural corruption for all modeled features, including:
-   - paragraphs/runs/text/breaks, citeturn3search0turn3search1turn3search3
-   - hyperlinks via `w:hyperlink`, citeturn1search2
-   - comments via range markers and comment part linkage, citeturn0search8turn0search4turn0search0
-   - tracked insertions/deletions via revision markup, citeturn1search0turn1search1turn10search3turn11search19
-   - tables via `w:tbl` and grid/cell props where modeled. citeturn2search5turn4search7turn5search7
-5. **Preservation correctness:** Unsupported OOXML is preserved via locked fragments or untouched parts, including Markup Compatibility constructs. citeturn2search3turn2search7turn0search2