@arbidocs/blocks 0.4.101 → 0.4.103

package/node_modules/@docx-editor.dev/core/dist/types-barrel-D3xCgQX6.d.ts

@@ -0,0 +1,4269 @@
+import { c as HistoryGroupOutcome } from './editor-scope-OHPwVQ5l.js';
+
+/**
+ * How a tracked change is addressed: `@w:id`, `@w:author` and `@w:date` together, within a
+ * part.
+ *
+ * All of them, always. `@w:id` is unique only within a part, so an id alone names two
+ * revisions in any package with a header or a comments part — and it is not author-scoped
+ * either, so `(part, id)` would merge two authors' distinct revisions. One logical revision is
+ * also deliberately many elements sharing an id, as a tracked row insertion is, which no
+ * uniqueness rule could express.
+ */
+interface RevisionAddress {
+    readonly id: string;
+    readonly author: string;
+    /** Absent when the file wrote no `@w:date`; part of the identity either way. */
+    readonly date?: string;
+}
+/** The author and timestamp a tracked edit is recorded under. */
+interface RevisionAttributionInput {
+    readonly author: string;
+    /** ISO-8601. Omitted writes no `@w:date`. */
+    readonly date?: string;
+}
+
+/**
+ * One parsed XML node, preserving significant order, whitespace and raw lexical values.
+ *
+ * Attribute records have a NULL prototype: attribute names come from a file and become object
+ * keys, so `__proto__` must be inert by construction rather than by filtering.
+ */
+type XmlNode = {
+    readonly type: 'element';
+    readonly name: string;
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly children: readonly XmlNode[];
+} | {
+    readonly type: 'text';
+    readonly value: string;
+};
+/**
+ * Why XML was refused at the trust boundary.
+ *
+ * DTDs, entity declarations and external-entity references are PRE-rejected before parsing —
+ * blocking XXE and billion-laughs by never handing the parser the construct, rather than by
+ * trusting it to be configured safely.
+ */
+type XmlRejection = 'too-large' | 'dtd-forbidden' | 'entity-forbidden' | 'too-deep' | 'too-many-elements' | 'invalid-limits' | 'parse-error';
+/** A parsed document, or a typed refusal. Never throws — the input is untrusted. */
+type XmlResult = {
+    readonly ok: true;
+    readonly nodes: readonly XmlNode[];
+} | {
+    readonly ok: false;
+    readonly reason: XmlRejection;
+};
+/** Per-part caps on size, element count and depth. Clamped into the hard ceilings. */
+interface XmlLimits {
+    readonly maxBytes: number;
+    /** Element budget; may raise or lower the engine default, up to its hard ceiling. */
+    readonly maxElements?: number;
+}
+/** Read XML into an ordered tree, refusing DTDs/entities and bounding size. */
+/**
+ * Read XML at the trust boundary: bounded, entity-free, and fidelity-preserving.
+ *
+ * Pre-rejects DTDs and entity constructs, disables expansion and value coercion, and keeps child
+ * order, attributes, whitespace and raw lexical form — everything a lossless re-emit needs.
+ */
+declare function readXml(xml: string, limits?: XmlLimits): XmlResult;
+/** Find the first descendant element with the given qualified name. */
+declare function findElement(nodes: readonly XmlNode[], name: string): Extract<XmlNode, {
+    type: 'element';
+}> | undefined;
+/** All direct child elements with the given name. */
+declare function childElements(node: Extract<XmlNode, {
+    type: 'element';
+}>, name: string): Extract<XmlNode, {
+    type: 'element';
+}>[];
+/** Concatenated text content of an element (all descendant text nodes). */
+declare function textContent(node: Extract<XmlNode, {
+    type: 'element';
+}>): string;
+
+/** The WordprocessingML main namespace — the `w:` prefix in every `word/document.xml`. */
+declare const WML_NAMESPACE_URI = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+/** The reserved `xml:` namespace, which carries `xml:space`. */
+declare const XML_NAMESPACE_URI = "http://www.w3.org/XML/1998/namespace";
+/** The reserved `xmlns:` namespace that namespace declarations themselves live in. */
+declare const XMLNS_NAMESPACE_URI = "http://www.w3.org/2000/xmlns/";
+/** The `w14` wordml-2010 extension namespace — `w14:paraId`/`w14:textId` live here. */
+declare const W14_NAMESPACE_URI = "http://schemas.microsoft.com/office/word/2010/wordml";
+declare const DRAWINGML_MAIN_NAMESPACE_URI = "http://schemas.openxmlformats.org/drawingml/2006/main";
+declare const WP_NAMESPACE_URI = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
+declare const PIC_NAMESPACE_URI = "http://schemas.openxmlformats.org/drawingml/2006/picture";
+/** The four content-position revision wrappers, which nest and carry runs. */
+declare function isContentRevisionKind(kind: OoxmlNode['kind']): kind is 'revisionInsert' | 'revisionDelete' | 'revisionMoveFrom' | 'revisionMoveTo';
+/** Move-range and comment-range boundary markers, which are empty and sit between runs. */
+declare function isRangeMarkerKind(kind: OoxmlNode['kind']): kind is 'moveFromRangeStart' | 'moveFromRangeEnd' | 'moveToRangeStart' | 'moveToRangeEnd' | 'commentRangeStart' | 'commentRangeEnd';
+/**
+ * OOXML on/off toggle: on only when a same-namespace child is present and its `w:val`
+ * (same namespace as the child) does not explicitly disable. Foreign-namespace siblings
+ * with the same local name cannot turn the flag on.
+ */
+declare function readOnOffChild(parent: OoxmlNode, localName: string, namespaceUri?: string): boolean;
+
+/**
+ * A node's stable identity within its part.
+ *
+ * Minted deterministically from the structural path at parse, then RETAINED through structural
+ * sharing — the same bytes always produce the same ids, and an edit elsewhere in the document
+ * does not renumber untouched nodes. Every tree op addresses nodes by these.
+ */
+type OoxmlNodeId = string;
+/**
+ * One `xmlns:` declaration carried on a node.
+ *
+ * Preserved rather than normalized away: a document that binds `w14` at the root and a document
+ * that binds it on a paragraph are different bytes, and re-emitting the wrong one is a fidelity
+ * loss even though the semantics match.
+ */
+interface OoxmlNamespaceBinding {
+    readonly prefix: string;
+    readonly namespaceUri: string;
+}
+interface OoxmlAttributeBase {
+    readonly namespaceUri: string;
+    readonly localName: string;
+    readonly prefix?: string;
+    readonly value: string;
+}
+/** `xml:space`, which decides whether a run's leading and trailing whitespace survives. */
+interface OoxmlXmlSpaceAttribute extends OoxmlAttributeBase {
+    readonly kind: 'xmlSpace';
+    readonly namespaceUri: typeof XML_NAMESPACE_URI;
+    readonly localName: 'space';
+    readonly prefix: 'xml';
+    readonly value: 'default' | 'preserve';
+}
+/** `w:val` — the attribute nearly every WordprocessingML property carries its value in. */
+interface OoxmlWmlValAttribute extends OoxmlAttributeBase {
+    readonly kind: 'wmlVal';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'val';
+}
+/**
+ * Any attribute outside the typed vocabulary, carried verbatim.
+ *
+ * Where losslessness actually happens: an attribute this engine has no model for is preserved
+ * exactly rather than dropped, so a save re-emits what the file said.
+ */
+interface OoxmlGenericExtensionAttribute extends OoxmlAttributeBase {
+    readonly kind: 'genericExtension';
+}
+/** Any attribute on any node: the two typed ones, plus the verbatim catch-all. */
+type OoxmlAttribute = OoxmlXmlSpaceAttribute | OoxmlWmlValAttribute | OoxmlGenericExtensionAttribute;
+/**
+ * Attributes a TYPED node may carry.
+ *
+ * Excludes `w:val` on purpose: a node the engine models keeps its value in typed fields, and
+ * allowing a stray `w:val` alongside them would create two sources of truth for one property.
+ */
+type OoxmlKnownNodeAttribute = OoxmlXmlSpaceAttribute | OoxmlGenericExtensionAttribute;
+interface OoxmlElementBase<Children extends readonly OoxmlNode[] = readonly OoxmlNode[], Attributes extends readonly OoxmlAttribute[] = readonly OoxmlAttribute[]> {
+    readonly id: OoxmlNodeId;
+    readonly namespaceUri: string;
+    readonly localName: string;
+    /** Authored prefix retained as non-authoritative fidelity evidence. */
+    readonly prefix?: string;
+    /** Namespace declarations authored directly on this element, in source order. */
+    readonly namespaceBindings: readonly OoxmlNamespaceBinding[];
+    readonly attributes: Attributes;
+    readonly children: Children;
+}
+/** `w:document` — the root of a main document part. */
+interface OoxmlDocumentNode extends OoxmlElementBase<readonly (OoxmlBodyNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'document';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'document';
+}
+/** `w:body` — the main story's block content. */
+interface OoxmlBodyNode extends OoxmlElementBase<readonly (OoxmlParagraphNode | OoxmlTableNode | OoxmlContentControlNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'body';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'body';
+}
+interface OoxmlTableNode extends OoxmlElementBase<readonly (OoxmlTablePropertiesNode | OoxmlTableGridNode | OoxmlTableRowNode | OoxmlContentControlNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'table';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'tbl';
+}
+interface OoxmlTableRowNode extends OoxmlElementBase<readonly (OoxmlTableCellNode | OoxmlContentControlNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'tableRow';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'tr';
+}
+interface OoxmlTableCellNode extends OoxmlElementBase<readonly (OoxmlParagraphNode | OoxmlTableNode | OoxmlContentControlNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'tableCell';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'tc';
+}
+/** Grid children (`w:gridCol`) stay generic: they are property leaves, not structure. */
+interface OoxmlTableGridNode extends OoxmlElementBase<readonly OoxmlGenericElementNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'tableGrid';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'tblGrid';
+}
+/** Property children stay generic, mirroring `runProperties`. */
+interface OoxmlTablePropertiesNode extends OoxmlElementBase<readonly OoxmlGenericElementNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'tableProperties';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'tblPr';
+}
+/**
+ * `w:p` — a paragraph, and the unit every offset in this engine is relative to.
+ *
+ * Positions are addressed as this node's id plus a UTF-16 offset, which is what makes a paragraph
+ * inside a table cell no different from one at the top level.
+ */
+interface OoxmlParagraphNode extends OoxmlElementBase<readonly (OoxmlParagraphPropertiesNode | OoxmlRunNode | OoxmlHyperlinkNode | OoxmlContentControlNode | OoxmlBookmarkStartNode | OoxmlBookmarkEndNode | OoxmlRevisionContentNode | OoxmlRangeMarkerNode | OoxmlFldSimpleNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'paragraph';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'p';
+}
+/**
+ * `CT_Hyperlink` (ECMA-376 §17.16.22) — a RUN CONTAINER, not a leaf.
+ *
+ * Its runs are part of the paragraph's inline sequence: they measure, paint, select and
+ * take offsets exactly like a run written directly under the `w:p`. Typing the element is
+ * what lets them in; while it was generic, its runs never reached the token stream and the
+ * words inside every link simply did not paint.
+ *
+ * Targets live in the ATTRIBUTES, and §17.16.22 declares exactly six. They divide into two
+ * groups, and the difference is load-bearing:
+ *
+ *   MODELED    `r:id` (a relationship, resolved against the owning part's rels), `w:anchor`
+ *              (a bookmark name in this document) and `w:tooltip`. These are the three the
+ *              ops read and write — `setHyperlinkTarget` sets one target attribute and
+ *              CLEARS the other, so a link never carries both and resolves by the wrong one.
+ *
+ *   PRESERVED  `w:tgtFrame`, `w:docLocation` and `w:history`. Nothing in this engine
+ *              interprets them and no op names them; they survive because attributes are
+ *              carried verbatim, and `setHyperlinkTarget` must leave them exactly as
+ *              authored. That is a REQUIREMENT, not an incidental property of the current
+ *              applier: `w:docLocation` names a location inside the target document, so
+ *              silently dropping it on a retarget would change where a link goes.
+ *              `hyperlink-lossless-editing.test.ts` pins both against a retarget.
+ *
+ * Nothing here is a runtime URL — the sanitized projection is computed separately (see
+ * `hyperlinkTargetOf`), and only that reaches a DOM or navigation sink.
+ *
+ * Bookmark markers are admitted as children because Word writes them inside links; anything
+ * else it can carry (a drawing, a field, a nested SDT) stays `generic` at its position, so a
+ * link around a picture keeps both the picture and the link.
+ *
+ * A link may contain ANOTHER link: §17.16.22's content model is `EG_PContent`, which lists
+ * `w:hyperlink` among its own members. That is why this child union is self-referential
+ * rather than bottoming out at runs. Demoting the inner one to `generic` would have been the
+ * easier type, and it would have reintroduced exactly the bug typing this element fixed —
+ * a generic link's runs never reach the token stream, so the words inside it stop painting.
+ * Every walk that descends a link therefore recurses (`segmentsOf`, `runsUnder`,
+ * `runPropertyEdits`) instead of descending one level.
+ */
+interface OoxmlHyperlinkNode extends OoxmlElementBase<readonly (OoxmlRunNode | OoxmlHyperlinkNode | OoxmlContentControlNode | OoxmlBookmarkStartNode | OoxmlBookmarkEndNode | OoxmlRevisionContentNode | OoxmlRangeMarkerNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'hyperlink';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'hyperlink';
+}
+/**
+ * A content-position revision wrapper — `w:ins`, `w:del`, `w:moveFrom`, `w:moveTo`.
+ *
+ * These wrap runs, so a walk that visits only direct `run` children never reaches
+ * the content inside them. Typing them is what lets layout descend deliberately
+ * rather than treating tracked content as unknown markup.
+ *
+ * ECMA-376 §17.13.5.18/.14/.25/.29. All four extend `CT_TrackChange`: `@w:id` and
+ * `@w:author` are required, `@w:date` is optional and is never fabricated.
+ *
+ * The SAME element names appear in property positions — `w:pPr/w:rPr/w:ins` marks a
+ * paragraph mark, `w:trPr/w:del` marks a row — where they carry no content and mean
+ * something structurally different. Those stay generic; see `contentRevisionKind`.
+ */
+interface OoxmlRevisionContentNode extends OoxmlElementBase<readonly (OoxmlRunNode | OoxmlRevisionContentNode | OoxmlHyperlinkNode | OoxmlRangeMarkerNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'revisionInsert' | 'revisionDelete' | 'revisionMoveFrom' | 'revisionMoveTo';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'ins' | 'del' | 'moveFrom' | 'moveTo';
+}
+/**
+ * `w:bookmarkStart` — a ZERO-LENGTH point anchor (`@w:id`, `@w:name`).
+ *
+ * It takes no text offset and paints nothing; it only marks a position, which is what an
+ * internal hyperlink's `w:anchor` names. Split and join place it by that position, the
+ * behaviour `tree-op-split-anchors.test.ts` pins.
+ */
+interface OoxmlBookmarkStartNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'bookmarkStart';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'bookmarkStart';
+}
+/** `w:bookmarkEnd` — the closing point anchor (`@w:id`), zero-length like its start. */
+interface OoxmlBookmarkEndNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'bookmarkEnd';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'bookmarkEnd';
+}
+/**
+ * A range marker: the move-range and comment-range boundaries.
+ *
+ * Three of the base types in this family disagree, and the disagreement is load-bearing:
+ *
+ * - `w:moveFromRangeStart` / `w:moveToRangeStart` are `CT_MoveBookmark` (§17.13.5.22/.26):
+ *   `@w:name`, `@w:author`, and `@w:date` are all REQUIRED.
+ * - `w:moveFromRangeEnd` / `w:moveToRangeEnd` / `w:commentRangeStart` / `w:commentRangeEnd`
+ *   are `CT_MarkupRange` (§17.13.5.21): `@w:id` only, with NO author and NO date. Requiring
+ *   provenance here refuses valid files; writing it emits invalid XML.
+ *
+ * Two different join keys ride on these: `@w:name` pairs a `moveFrom` range with its
+ * `moveTo` range, while `@w:id` pairs a range start with its own range end. In a real
+ * document the two halves of a named pair carry different ids, so neither key substitutes
+ * for the other.
+ */
+interface OoxmlRangeMarkerNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'moveFromRangeStart' | 'moveFromRangeEnd' | 'moveToRangeStart' | 'moveToRangeEnd' | 'commentRangeStart' | 'commentRangeEnd';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'moveFromRangeStart' | 'moveFromRangeEnd' | 'moveToRangeStart' | 'moveToRangeEnd' | 'commentRangeStart' | 'commentRangeEnd';
+}
+/** `w:commentReference` — the in-run mark that carries the comment's anchor point. */
+interface OoxmlCommentReferenceNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'commentReference';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'commentReference';
+}
+/** The `word/comments.xml` root (`CT_Comments`, §17.13.4.2). */
+interface OoxmlCommentsNode extends OoxmlElementBase<readonly (OoxmlCommentNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'comments';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'comments';
+}
+/**
+ * One comment (`CT_Comment`, §17.13.4.4) — `CT_TrackChange` plus `@w:initials`, holding
+ * block content. The block content is why a comment body is a story rather than a string.
+ */
+interface OoxmlCommentNode extends OoxmlElementBase<readonly (OoxmlParagraphNode | OoxmlTableNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'comment';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'comment';
+}
+/** `w:r` — a run: text and atoms sharing one set of character properties. */
+interface OoxmlRunNode extends OoxmlElementBase<readonly (OoxmlRunPropertiesNode | OoxmlTextElementNode | OoxmlDeletedTextNode | OoxmlTabNode | OoxmlHardBreakNode | OoxmlCommentReferenceNode | OoxmlFldCharNode | OoxmlInstrTextNode | OoxmlNoteReferenceNode | OoxmlNoteRefNode | OoxmlSeparatorNode | OoxmlContinuationSeparatorNode | OoxmlDrawingNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'run';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'r';
+}
+/** `w:drawing` — run content only; exactly one typed inline or anchored child. */
+interface OoxmlDrawingNode extends OoxmlElementBase<readonly (OoxmlInlineDrawingNode | OoxmlAnchoredDrawingNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawing';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'drawing';
+}
+/** `wp:inline` / `wp:anchor` shared payload children. */
+type OoxmlDrawingAnchorChild = OoxmlDrawingExtentNode | OoxmlDrawingEffectExtentNode | OoxmlDrawingDocPrNode | OoxmlDrawingGraphicFramePrNode | OoxmlDrawingGraphicNode | OoxmlDrawingSimplePosNode | OoxmlDrawingPositionHNode | OoxmlDrawingPositionVNode | OoxmlDrawingWrapNoneNode | OoxmlDrawingWrapSquareNode | OoxmlDrawingWrapTightNode | OoxmlDrawingWrapThroughNode | OoxmlDrawingWrapTopBottomNode | OoxmlGenericElementNode;
+/** `wp:inline` (`CT_Inline`) — typed only under `w:drawing`. */
+interface OoxmlInlineDrawingNode extends OoxmlElementBase<readonly OoxmlDrawingAnchorChild[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'inlineDrawing';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'inline';
+}
+/** `wp:anchor` (`CT_Anchor`) — typed only under `w:drawing`. */
+interface OoxmlAnchoredDrawingNode extends OoxmlElementBase<readonly OoxmlDrawingAnchorChild[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'anchoredDrawing';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'anchor';
+}
+interface OoxmlDrawingExtentNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingExtent';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'extent';
+}
+interface OoxmlDrawingEffectExtentNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingEffectExtent';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'effectExtent';
+}
+interface OoxmlDrawingDocPrNode extends OoxmlElementBase<readonly OoxmlGenericElementNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingDocPr';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'docPr';
+}
+interface OoxmlDrawingGraphicFramePrNode extends OoxmlElementBase<readonly OoxmlGenericElementNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingGraphicFramePr';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'cNvGraphicFramePr';
+}
+interface OoxmlDrawingGraphicNode extends OoxmlElementBase<readonly (OoxmlDrawingGraphicDataNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingGraphic';
+    readonly namespaceUri: typeof DRAWINGML_MAIN_NAMESPACE_URI;
+    readonly localName: 'graphic';
+}
+interface OoxmlDrawingGraphicDataNode extends OoxmlElementBase<readonly (OoxmlPictureNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingGraphicData';
+    readonly namespaceUri: typeof DRAWINGML_MAIN_NAMESPACE_URI;
+    readonly localName: 'graphicData';
+}
+interface OoxmlDrawingSimplePosNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingSimplePos';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'simplePos';
+}
+interface OoxmlDrawingPositionHNode extends OoxmlElementBase<readonly (OoxmlDrawingPositionAlignNode | OoxmlDrawingPositionOffsetNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingPositionH';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'positionH';
+}
+interface OoxmlDrawingPositionVNode extends OoxmlElementBase<readonly (OoxmlDrawingPositionAlignNode | OoxmlDrawingPositionOffsetNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingPositionV';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'positionV';
+}
+interface OoxmlDrawingPositionAlignNode extends OoxmlElementBase<readonly (OoxmlTextNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingPositionAlign';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'align';
+}
+interface OoxmlDrawingPositionOffsetNode extends OoxmlElementBase<readonly (OoxmlTextNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingPositionOffset';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'posOffset';
+}
+interface OoxmlDrawingWrapNoneNode extends OoxmlElementBase<readonly OoxmlGenericElementNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingWrapNone';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'wrapNone';
+}
+interface OoxmlDrawingWrapSquareNode extends OoxmlElementBase<readonly (OoxmlDrawingEffectExtentNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingWrapSquare';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'wrapSquare';
+}
+interface OoxmlDrawingWrapTightNode extends OoxmlElementBase<readonly (OoxmlDrawingWrapPolygonNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingWrapTight';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'wrapTight';
+}
+interface OoxmlDrawingWrapThroughNode extends OoxmlElementBase<readonly (OoxmlDrawingWrapPolygonNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingWrapThrough';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'wrapThrough';
+}
+interface OoxmlDrawingWrapTopBottomNode extends OoxmlElementBase<readonly (OoxmlDrawingEffectExtentNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingWrapTopBottom';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'wrapTopAndBottom';
+}
+interface OoxmlDrawingWrapPolygonNode extends OoxmlElementBase<readonly (OoxmlDrawingWrapPolygonStartNode | OoxmlDrawingWrapPolygonLineToNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingWrapPolygon';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'wrapPolygon';
+}
+interface OoxmlDrawingWrapPolygonStartNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingWrapPolygonStart';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'start';
+}
+interface OoxmlDrawingWrapPolygonLineToNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'drawingWrapPolygonLineTo';
+    readonly namespaceUri: typeof WP_NAMESPACE_URI;
+    readonly localName: 'lineTo';
+}
+/** `pic:pic` (`CT_Picture`) — typed only under picture `a:graphicData`. */
+interface OoxmlPictureNode extends OoxmlElementBase<readonly (OoxmlPictureNvPicPrNode | OoxmlPictureBlipFillNode | OoxmlPictureShapePropertiesNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'picture';
+    readonly namespaceUri: typeof PIC_NAMESPACE_URI;
+    readonly localName: 'pic';
+}
+interface OoxmlPictureNvPicPrNode extends OoxmlElementBase<readonly OoxmlGenericElementNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'pictureNvPicPr';
+    readonly namespaceUri: typeof PIC_NAMESPACE_URI;
+    readonly localName: 'nvPicPr';
+}
+interface OoxmlPictureBlipFillNode extends OoxmlElementBase<readonly (OoxmlPictureBlipNode | OoxmlPictureSrcRectNode | OoxmlPictureStretchNode | OoxmlPictureTileNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'pictureBlipFill';
+    readonly namespaceUri: typeof PIC_NAMESPACE_URI;
+    readonly localName: 'blipFill';
+}
+interface OoxmlPictureBlipNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'pictureBlip';
+    readonly namespaceUri: typeof DRAWINGML_MAIN_NAMESPACE_URI;
+    readonly localName: 'blip';
+}
+interface OoxmlPictureSrcRectNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'pictureSrcRect';
+    readonly namespaceUri: typeof DRAWINGML_MAIN_NAMESPACE_URI;
+    readonly localName: 'srcRect';
+}
+interface OoxmlPictureStretchNode extends OoxmlElementBase<readonly OoxmlGenericElementNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'pictureStretch';
+    readonly namespaceUri: typeof DRAWINGML_MAIN_NAMESPACE_URI;
+    readonly localName: 'stretch';
+}
+interface OoxmlPictureTileNode extends OoxmlElementBase<readonly OoxmlGenericElementNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'pictureTile';
+    readonly namespaceUri: typeof DRAWINGML_MAIN_NAMESPACE_URI;
+    readonly localName: 'tile';
+}
+interface OoxmlPictureShapePropertiesNode extends OoxmlElementBase<readonly (OoxmlPictureTransformNode | OoxmlPicturePresetGeometryNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'pictureShapeProperties';
+    readonly namespaceUri: typeof PIC_NAMESPACE_URI;
+    readonly localName: 'spPr';
+}
+interface OoxmlPictureTransformNode extends OoxmlElementBase<readonly (OoxmlPictureTransformOffsetNode | OoxmlPictureTransformExtentNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'pictureTransform';
+    readonly namespaceUri: typeof DRAWINGML_MAIN_NAMESPACE_URI;
+    readonly localName: 'xfrm';
+}
+interface OoxmlPictureTransformOffsetNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'pictureTransformOffset';
+    readonly namespaceUri: typeof DRAWINGML_MAIN_NAMESPACE_URI;
+    readonly localName: 'off';
+}
+interface OoxmlPictureTransformExtentNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'pictureTransformExtent';
+    readonly namespaceUri: typeof DRAWINGML_MAIN_NAMESPACE_URI;
+    readonly localName: 'ext';
+}
+interface OoxmlPicturePresetGeometryNode extends OoxmlElementBase<readonly OoxmlGenericElementNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'picturePresetGeometry';
+    readonly namespaceUri: typeof DRAWINGML_MAIN_NAMESPACE_URI;
+    readonly localName: 'prstGeom';
+}
+/**
+ * `w:delText` (§17.3.3.7) — the text container a run uses once its content is deleted.
+ *
+ * Structurally identical to `w:t`, and deliberately a DIFFERENT kind: it must never flow
+ * as ordinary text, and rejecting the deletion that contains it turns it back into `w:t`.
+ */
+interface OoxmlDeletedTextNode extends OoxmlElementBase<readonly OoxmlTextNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'deletedText';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'delText';
+}
+/**
+ * `w:rPr` — a run's character properties, whose children stay GENERIC.
+ *
+ * Deliberately unmodelled below this point: the property vocabulary is large and mostly
+ * uninteresting to layout, so carrying it verbatim preserves everything without the engine having
+ * to know what each element means.
+ */
+interface OoxmlRunPropertiesNode extends OoxmlElementBase<readonly OoxmlGenericElementNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'runProperties';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'rPr';
+}
+/** `w:t` — the element holding a run's literal characters. */
+interface OoxmlTextElementNode extends OoxmlElementBase<readonly OoxmlTextNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'text';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 't';
+}
+/** `w:pPr` — a paragraph's properties. Children stay generic, like `w:rPr`'s. */
+interface OoxmlParagraphPropertiesNode extends OoxmlElementBase<readonly (OoxmlRunPropertiesNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'paragraphProperties';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'pPr';
+}
+/** `w:tab` inside a run — one tab character as its own element. */
+interface OoxmlTabNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'tab';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'tab';
+}
+/** `w:br` — a line, column or page break; `w:cr` — a manual line break. */
+interface OoxmlHardBreakNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'hardBreak';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'br' | 'cr';
+}
+/**
+ * Complex-field character (`w:fldChar`).
+ *
+ * Children stay generic so `w:ffData` (legacy form fields / macros) round-trips as inert
+ * payload and is never promoted to an executable surface. `@w:fldCharType`, `@w:dirty`,
+ * and `@w:fldLock` are preserved on `attributes`.
+ */
+interface OoxmlFldCharNode extends OoxmlElementBase<readonly OoxmlGenericElementNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'fldChar';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'fldChar';
+}
+/**
+ * Field instruction text (`w:instrText`), same text-carrier shape as `w:t`.
+ *
+ * Instruction strings are never executed; layout may recognize allowlisted page-number
+ * keywords only.
+ */
+interface OoxmlInstrTextNode extends OoxmlElementBase<readonly OoxmlTextNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'instrText';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'instrText';
+}
+/**
+ * Simple field (`w:fldSimple`) at paragraph content level.
+ *
+ * `@w:instr`, `@w:dirty`, and `@w:fldLock` round-trip on `attributes`. Cached result
+ * children stay structurally preserved; the field is one atomic addressable unit.
+ */
+interface OoxmlFldSimpleNode extends OoxmlElementBase<readonly (OoxmlRunNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'fldSimple';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'fldSimple';
+}
+/**
+ * Footnotes part root (`w:footnotes`). Children are typed notes or preserved generics.
+ * Never a story root itself — each note body is its own story for layout.
+ */
+interface OoxmlFootnotesNode extends OoxmlElementBase<readonly (OoxmlNoteNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'footnotes';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'footnotes';
+}
+/**
+ * Endnotes part root (`w:endnotes`). Same content model as {@link OoxmlFootnotesNode}.
+ */
+interface OoxmlEndnotesNode extends OoxmlElementBase<readonly (OoxmlNoteNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'endnotes';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'endnotes';
+}
+/**
+ * One footnote or endnote (`w:footnote` / `w:endnote`).
+ *
+ * Discriminated by `localName`. `@w:id` and optional `@w:type` (`ST_FtnEdn`, including
+ * authored `normal`) live on `attributes`. Children are ordinary block content.
+ */
+interface OoxmlNoteNode extends OoxmlElementBase<readonly (OoxmlParagraphNode | OoxmlTableNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'note';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'footnote' | 'endnote';
+}
+/**
+ * Body citation (`w:footnoteReference` / `w:endnoteReference`) as a typed run child.
+ * Display mark is derived — never stored as text. One UTF-16 atom in addressing.
+ */
+interface OoxmlNoteReferenceNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'noteReference';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'footnoteReference' | 'endnoteReference';
+}
+/**
+ * Auto mark inside a note body (`w:footnoteRef` / `w:endnoteRef`).
+ * One UTF-16 atom; display digit is derived at paint time.
+ */
+interface OoxmlNoteRefNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'noteRef';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'footnoteRef' | 'endnoteRef';
+}
+/** Run-inner separator rule (`w:separator`). One UTF-16 atom. */
+interface OoxmlSeparatorNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'separator';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'separator';
+}
+/** Run-inner continuation separator (`w:continuationSeparator`). One UTF-16 atom. */
+interface OoxmlContinuationSeparatorNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'continuationSeparator';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'continuationSeparator';
+}
+/**
+ * `w:sdt` — structured document tag (content control) at block, inline, row, or cell level.
+ *
+ * Placement is not a separate kind: the same element name appears in every `EG_*Content`
+ * group. Child shape is the union of those placements; parents admit the control wherever
+ * `generic` was previously accepted (see `isPreservedChild`). Identity is the node id —
+ * `w:id` inside `w:sdtPr` is optional, preserved when present, never fabricated here.
+ */
+interface OoxmlContentControlNode extends OoxmlElementBase<readonly (OoxmlContentControlPropertiesNode | OoxmlContentControlEndPropertiesNode | OoxmlContentControlContentNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControl';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'sdt';
+}
+/**
+ * `w:sdtPr` (`CT_SdtPr`) — schema-ordered properties. Unmodelled children (alias/tag/id/lock
+ * leaves with `w:val`, `w15:*`, empty type markers) stay `generic` in position. Typed
+ * payloads: dropdown/combo/listItem, date (+ leaves), text, dataBinding, `w14:checkbox`.
+ */
+interface OoxmlContentControlPropertiesNode extends OoxmlElementBase<readonly (OoxmlRunPropertiesNode | OoxmlContentControlDataBindingNode | OoxmlContentControlDropDownListNode | OoxmlContentControlComboBoxNode | OoxmlContentControlDateNode | OoxmlContentControlTextNode | OoxmlContentControlCheckboxNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControlProperties';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'sdtPr';
+}
+/** `w:sdtEndPr` — end-character properties; children are `w:rPr` or generic. */
+interface OoxmlContentControlEndPropertiesNode extends OoxmlElementBase<readonly (OoxmlRunPropertiesNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControlEndProperties';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'sdtEndPr';
+}
+/**
+ * `w:sdtContent` — control contents for every placement. Block content is paragraphs/tables;
+ * inline content is runs/hyperlinks; row/cell content is rows/cells. Nested controls stay typed.
+ */
+interface OoxmlContentControlContentNode extends OoxmlElementBase<readonly OoxmlNode[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControlContent';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'sdtContent';
+}
+/** `w:dropDownList` — `@w:lastValue` plus typed `w:listItem` children. */
+interface OoxmlContentControlDropDownListNode extends OoxmlElementBase<readonly (OoxmlContentControlListItemNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControlDropDownList';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'dropDownList';
+}
+/** `w:comboBox` — same payload shape as dropdown; free entry is an editing concern. */
+interface OoxmlContentControlComboBoxNode extends OoxmlElementBase<readonly (OoxmlContentControlListItemNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControlComboBox';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'comboBox';
+}
+/** `w:listItem` — `@w:displayText` / `@w:value` as preserved attributes (not `w:val`). */
+interface OoxmlContentControlListItemNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControlListItem';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'listItem';
+}
+/**
+ * `w:date` — `@w:fullDate` plus typed dateFormat/lid/storeMappedDataAs/calendar leaves.
+ * Those leaves allow `w:val` (the only known kinds that do) so they are not demoted.
+ */
+interface OoxmlContentControlDateNode extends OoxmlElementBase<readonly (OoxmlContentControlDateFormatNode | OoxmlContentControlLidNode | OoxmlContentControlStoreMappedDataAsNode | OoxmlContentControlCalendarNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControlDate';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'date';
+}
+/** `w:dateFormat` — the picture string a date picker formats its value with. */
+interface OoxmlContentControlDateFormatNode extends OoxmlElementBase<readonly [], readonly (OoxmlKnownNodeAttribute | OoxmlWmlValAttribute)[]> {
+    readonly kind: 'contentControlDateFormat';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'dateFormat';
+}
+/** `w:lid` — the language id a date picker parses and formats under. */
+interface OoxmlContentControlLidNode extends OoxmlElementBase<readonly [], readonly (OoxmlKnownNodeAttribute | OoxmlWmlValAttribute)[]> {
+    readonly kind: 'contentControlLid';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'lid';
+}
+/** `w:storeMappedDataAs` — which representation a bound date is written to its XML part as. */
+interface OoxmlContentControlStoreMappedDataAsNode extends OoxmlElementBase<readonly [], readonly (OoxmlKnownNodeAttribute | OoxmlWmlValAttribute)[]> {
+    readonly kind: 'contentControlStoreMappedDataAs';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'storeMappedDataAs';
+}
+/** `w:calendar` — which calendar system a date picker uses (Gregorian, Hijri, …). */
+interface OoxmlContentControlCalendarNode extends OoxmlElementBase<readonly [], readonly (OoxmlKnownNodeAttribute | OoxmlWmlValAttribute)[]> {
+    readonly kind: 'contentControlCalendar';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'calendar';
+}
+/** `w:text` (`CT_SdtText`) — distinct from `w:t` (`kind: 'text'`). `@w:multiLine` preserved. */
+interface OoxmlContentControlTextNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControlText';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'text';
+}
+/**
+ * `w:dataBinding` — xpath / storeItemID / prefixMappings preserved as attributes.
+ * This tree never resolves or fetches the binding target.
+ */
+interface OoxmlContentControlDataBindingNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControlDataBinding';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'dataBinding';
+}
+/**
+ * `w14:checkbox` — Microsoft extension, not an ECMA-376 type choice. Distinguishable from
+ * untyped rich-text controls that merely wrap a `w:sym`.
+ */
+interface OoxmlContentControlCheckboxNode extends OoxmlElementBase<readonly (OoxmlContentControlCheckedNode | OoxmlContentControlCheckedStateNode | OoxmlContentControlUncheckedStateNode | OoxmlGenericElementNode)[], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControlCheckbox';
+    readonly namespaceUri: typeof W14_NAMESPACE_URI;
+    readonly localName: 'checkbox';
+}
+/** `w14:checked` — a checkbox's recorded state, independent of the glyph drawn for it. */
+interface OoxmlContentControlCheckedNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControlChecked';
+    readonly namespaceUri: typeof W14_NAMESPACE_URI;
+    readonly localName: 'checked';
+}
+/** `w14:checkedState` — the font and code point drawn when a checkbox is checked. */
+interface OoxmlContentControlCheckedStateNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControlCheckedState';
+    readonly namespaceUri: typeof W14_NAMESPACE_URI;
+    readonly localName: 'checkedState';
+}
+/** `w14:uncheckedState` — the font and code point drawn when a checkbox is not checked. */
+interface OoxmlContentControlUncheckedStateNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'contentControlUncheckedState';
+    readonly namespaceUri: typeof W14_NAMESPACE_URI;
+    readonly localName: 'uncheckedState';
+}
+/**
+ * Any element the typed vocabulary does not cover — the other half of the preservation model.
+ *
+ * Also where a KNOWN element lands when it appears somewhere invalid: an element is demoted to
+ * generic rather than rejected, so malformed or unfamiliar content is carried losslessly and
+ * never locks editing.
+ */
+interface OoxmlGenericElementNode extends OoxmlElementBase<readonly OoxmlNode[]> {
+    readonly kind: 'generic';
+}
+/** A literal text value. The only node kind with no children and no attributes. */
+interface OoxmlTextNode {
+    readonly id: OoxmlNodeId;
+    readonly kind: 'textValue';
+    readonly value: string;
+}
+/** Every element node kind: the typed vocabulary plus the generic catch-all. */
+type OoxmlElement = OoxmlDocumentNode | OoxmlBodyNode | OoxmlParagraphNode | OoxmlRunNode | OoxmlHyperlinkNode | OoxmlBookmarkStartNode | OoxmlBookmarkEndNode | OoxmlRunPropertiesNode | OoxmlTextElementNode | OoxmlDeletedTextNode | OoxmlParagraphPropertiesNode | OoxmlTabNode | OoxmlHardBreakNode | OoxmlFldCharNode | OoxmlInstrTextNode | OoxmlFldSimpleNode | OoxmlFootnotesNode | OoxmlEndnotesNode | OoxmlNoteNode | OoxmlNoteReferenceNode | OoxmlNoteRefNode | OoxmlSeparatorNode | OoxmlContinuationSeparatorNode | OoxmlTableNode | OoxmlTableRowNode | OoxmlTableCellNode | OoxmlTableGridNode | OoxmlTablePropertiesNode | OoxmlRevisionContentNode | OoxmlRangeMarkerNode | OoxmlCommentReferenceNode | OoxmlCommentsNode | OoxmlCommentNode | OoxmlContentControlNode | OoxmlContentControlPropertiesNode | OoxmlContentControlEndPropertiesNode | OoxmlContentControlContentNode | OoxmlContentControlDropDownListNode | OoxmlContentControlComboBoxNode | OoxmlContentControlListItemNode | OoxmlContentControlDateNode | OoxmlContentControlDateFormatNode | OoxmlContentControlLidNode | OoxmlContentControlStoreMappedDataAsNode | OoxmlContentControlCalendarNode | OoxmlContentControlTextNode | OoxmlContentControlDataBindingNode | OoxmlContentControlCheckboxNode | OoxmlContentControlCheckedNode | OoxmlContentControlCheckedStateNode | OoxmlContentControlUncheckedStateNode | OoxmlDrawingNode | OoxmlInlineDrawingNode | OoxmlAnchoredDrawingNode | OoxmlDrawingExtentNode | OoxmlDrawingEffectExtentNode | OoxmlDrawingDocPrNode | OoxmlDrawingGraphicFramePrNode | OoxmlDrawingGraphicNode | OoxmlDrawingGraphicDataNode | OoxmlDrawingSimplePosNode | OoxmlDrawingPositionHNode | OoxmlDrawingPositionVNode | OoxmlDrawingPositionAlignNode | OoxmlDrawingPositionOffsetNode | OoxmlDrawingWrapNoneNode | OoxmlDrawingWrapSquareNode | OoxmlDrawingWrapTightNode | OoxmlDrawingWrapThroughNode | OoxmlDrawingWrapTopBottomNode | OoxmlDrawingWrapPolygonNode | OoxmlDrawingWrapPolygonStartNode | OoxmlDrawingWrapPolygonLineToNode | OoxmlPictureNode | OoxmlPictureNvPicPrNode | OoxmlPictureBlipFillNode | OoxmlPictureBlipNode | OoxmlPictureSrcRectNode | OoxmlPictureStretchNode | OoxmlPictureTileNode | OoxmlPictureShapePropertiesNode | OoxmlPictureTransformNode | OoxmlPictureTransformOffsetNode | OoxmlPictureTransformExtentNode | OoxmlPicturePresetGeometryNode | OoxmlGenericElementNode;
+/**
+ * Any node in the canonical tree.
+ *
+ * Typed where layout needs structure, generic everywhere else — one tree carries a whole document
+ * whether or not the engine understands every part of it.
+ */
+type OoxmlNode = OoxmlElement | OoxmlTextNode;
+/** One XML part of the package, parsed into a canonical tree. */
+interface OoxmlPart {
+    readonly id: string;
+    /** Canonical part name, e.g. `/word/document.xml`. */
+    readonly name: string;
+    readonly contentType: string;
+    readonly root: OoxmlElement;
+}
+/** A part's identity without its tree — enough to enumerate a package cheaply. */
+interface OoxmlPartMetadata {
+    readonly name: string;
+    readonly contentType: string;
+}
+/**
+ * Why a part could not be read into a tree.
+ *
+ * Widens the XML-level rejections with the tree-level ones. All of them describe the FILE, which
+ * is why reading returns a result rather than throwing.
+ */
+type OoxmlReadRejection = XmlRejection | 'missing-root' | 'multiple-roots' | 'invalid-name' | 'invalid-namespace' | 'undeclared-prefix' | 'duplicate-expanded-attribute';
+/** A parsed part, or a typed refusal. Never throws — the input is untrusted by definition. */
+type OoxmlReadResult = {
+    readonly ok: true;
+    readonly part: OoxmlPart;
+} | {
+    readonly ok: false;
+    readonly reason: OoxmlReadRejection;
+};
+/**
+ * The node-identity contract, written down as a type so it is checkable rather than merely
+ * documented.
+ *
+ * Ids are deterministic from a normalized parse, retained through structural sharing, explicit on
+ * replacement, and unique within a part. Everything that addresses nodes — ops, the caret, the
+ * paraId bimap — depends on all four holding.
+ */
+interface OoxmlNodeIdentityRules {
+    readonly initial: 'deterministic-structural-path-after-normalized-parse';
+    readonly unchanged: 'retain-id-through-structural-sharing';
+    readonly replacement: 'explicitly-retain-or-allocate';
+    readonly uniqueness: 'unique-within-part';
+}
+/**
+ * Identity policy for future immutable tree edits. This defines the boundary
+ * without implementing task 2.4 edit primitives.
+ */
+declare const OOXML_NODE_IDENTITY_RULES: OoxmlNodeIdentityRules;
+/** What a tree invariant walk found wrong. Each names a rule the canonical tree must satisfy. */
+type OoxmlInvariantIssueCode = 'invalid-id' | 'duplicate-id' | 'invalid-name' | 'invalid-namespace' | 'invalid-qname' | 'duplicate-expanded-attribute' | 'invalid-xml-value' | 'known-node-invariant';
+/** One invariant violation, located by structural path and node id. */
+interface OoxmlInvariantIssue {
+    readonly code: OoxmlInvariantIssueCode;
+    readonly path: string;
+    readonly nodeId?: string;
+}
+/** Whether a tree satisfies its invariants, listing every violation when it does not. */
+type OoxmlInvariantResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly issues: readonly OoxmlInvariantIssue[];
+};
+/**
+ * Read one XML part into the additive typed/generic foundation. Existing package
+ * parsing and DocumentStore models intentionally remain unchanged until their
+ * later migration tasks; this tree is not yet the repository's sole runtime authority.
+ * Structural-path IDs are deterministic across normalized reopen. Preserving an
+ * identity through moves and edits is deferred to PackageModel/DocumentStore integration.
+ */
+declare function readOoxmlPart(xml: string, metadata: OoxmlPartMetadata, limits?: XmlLimits): OoxmlReadResult;
+
+type AutomationTableMutation = {
+    readonly kind: 'insertRows';
+    readonly rowId: string;
+    readonly location: 'before' | 'after';
+    readonly count: number;
+    readonly values?: readonly (readonly string[])[];
+} | {
+    readonly kind: 'values';
+    readonly values: readonly (readonly string[])[];
+} | {
+    readonly kind: 'addRows' | 'addColumns';
+    readonly location: 'start' | 'end';
+    readonly count: number;
+    readonly values?: readonly (readonly string[])[];
+} | {
+    readonly kind: 'deleteRows' | 'deleteColumns';
+    readonly index: number;
+    readonly count: number;
+} | {
+    readonly kind: 'delete';
+} | {
+    readonly kind: 'properties';
+    readonly styleId?: string;
+    readonly headerRowCount?: number;
+} | {
+    readonly kind: 'cell';
+    readonly cellId: string;
+    readonly value?: string;
+    readonly columnWidth?: number;
+    readonly shadingColor?: string;
+    readonly verticalAlignment?: 'Top' | 'Center' | 'Bottom';
+};
+
+/** Select one declared entry of a legacy Word dropdown form field. */
+interface SetLegacyDropdownOp {
+    readonly op: 'setLegacyDropdown';
+    readonly paragraphId: string;
+    readonly fieldNodeId: string;
+    readonly selectedIndex: number;
+}
+
+interface SetFieldCodeOp {
+    readonly op: 'setFieldCode';
+    readonly paragraphId: string;
+    readonly fieldNodeId: string;
+    readonly code: string;
+}
+
+type InsertTextOp = {
+    readonly op: 'insertText';
+    readonly paragraphId: string;
+    /** Legacy text form identity for protected filling; never an inline wrapper owner. */
+    readonly textFormFieldId?: string;
+    readonly offset: number;
+    readonly text: string;
+    /**
+     * Write this as a TRACKED insertion, attributed here.
+     *
+     * On the op rather than on the store, so suggesting stays a decision the surface makes
+     * per edit and the write vocabulary stays explicit — a global "everything is tracked
+     * now" flag is exactly what `DocEdits` refuses, because it makes the meaning of an op
+     * depend on state the op does not carry.
+     */
+    readonly revision?: RevisionAttributionInput;
+    /**
+     * When set, the text belongs INSIDE this content control, whatever sits at the offset.
+     *
+     * A boundary offset is owned by the run that starts there, which at a control's trailing
+     * edge is the run after the control — so an offset alone cannot say "append to this field",
+     * the way it cannot say which run of a field result to format (see `targetRunIds`). A
+     * caller that names the control gets the text in the control; one that does not gets the
+     * plain offset rule, which is what a keystroke beside a field means.
+     */
+    readonly inside?: string;
+    /**
+     * Which side of a run BOUNDARY the text joins. Default `'left'` — Word's typing rule:
+     * the next character takes the formatting of the character before the caret.
+     *
+     * `'right'` is for a caller that is not typing but placing text inside the run that
+     * STARTS at the offset — the hyperlink editor rewriting a link's display text, where
+     * landing left of the boundary would put the new text outside the link. Ignored when
+     * the offset falls strictly inside a run, which has no boundary to choose.
+     */
+    readonly bias?: 'left' | 'right';
+};
+type DeleteTextOp = {
+    readonly op: 'deleteText';
+    readonly paragraphId: string;
+    /** Legacy text form identity for protected filling; never an inline wrapper owner. */
+    readonly textFormFieldId?: string;
+    readonly start: number;
+    readonly end: number;
+    /** Write this as a TRACKED deletion — the characters stay, wrapped in `w:del`. */
+    readonly revision?: RevisionAttributionInput;
+};
+
+/** Editable legacy text input types. Other authored types remain inert. */
+type TextFormFieldType = 'regular' | 'number' | 'date';
+/** Options stored in the legacy field definition. Zero means unlimited length. */
+interface TextFormFieldOptions {
+    readonly type: TextFormFieldType;
+    readonly maxLength: number;
+    readonly format: string;
+    readonly enabled: boolean;
+}
+/** Supported format choices for legacy text input fields. @public */
+declare const TEXT_FORM_FORMATS: {
+    readonly regular: readonly ['', 'Uppercase', 'Lowercase', 'First capital', 'Title case'];
+    readonly number: readonly ['', '0', '0.00', '#,##0', '#,##0.00', '0%', '0.00%'];
+    readonly date: readonly ['', 'M/d/yyyy', 'MM/dd/yyyy', 'd/M/yyyy', 'dd/MM/yyyy', 'yyyy-MM-dd', 'd MMMM yyyy', 'MMMM d, yyyy'];
+};
+
+/** A legacy text input in the shared paragraph offset space. */
+interface TextFormFieldRange {
+    readonly fieldNodeId: string;
+    readonly start: number;
+    readonly end: number;
+    readonly enabled: boolean;
+    readonly defaultText: string;
+    readonly type: string;
+    readonly maxLength: number;
+    readonly format: string;
+    readonly chromeIds: readonly string[];
+}
+/** Uses the field parser and offset index; never introduces another inline walk. */
+declare function textFormFieldsOf(paragraph: OoxmlParagraphNode): readonly TextFormFieldRange[];
+/** Options edit for an existing legacy text form. */
+interface SetTextFormFieldDefaultOp {
+    readonly op: 'setTextFormFieldDefault';
+    /** Regional conventions for new date input; defaults to en-US. */
+    readonly locale?: string;
+    readonly paragraphId: string;
+    readonly fieldNodeId: string;
+    readonly text: string;
+    readonly options?: TextFormFieldOptions;
+}
+/** Validate and format the existing result when a user finishes filling a field. */
+interface CommitTextFormFieldOp {
+    readonly op: 'commitTextFormField';
+    /** Regional conventions for new date input; defaults to en-US. */
+    readonly locale?: string;
+    readonly paragraphId: string;
+    readonly fieldNodeId: string;
+}
+
+/** One FORMCHECKBOX in the shared paragraph offset space. */
+interface LegacyCheckboxFieldRange {
+    /** The begin `w:fldChar` node: what the op addresses. */
+    readonly fieldNodeId: string;
+    readonly start: number;
+    readonly end: number;
+    readonly checked: boolean;
+    /** `w:enabled` under `w:ffData`; a disabled field renders but refuses the toggle. */
+    readonly enabled: boolean;
+}
+/** Flip a FORMCHECKBOX's state; the only write into `w:ffData` a checkbox permits. */
+interface SetLegacyCheckboxOp {
+    readonly op: 'setLegacyCheckbox';
+    readonly paragraphId: string;
+    readonly fieldNodeId: string;
+    readonly checked: boolean;
+}
+/** Every FORMCHECKBOX in a paragraph, in document order; uses the shared field parser. */
+declare function legacyCheckboxFieldsOf(paragraph: OoxmlParagraphNode): readonly LegacyCheckboxFieldRange[];
+
+/** Replace a building block gallery control's content with one block's body. */
+interface InsertBuildingBlockOp {
+    readonly op: 'insertBuildingBlock';
+    readonly controlId: string;
+    /** `w:docPartPr/w:name` of the picked block, for the journal and the host. */
+    readonly name: string;
+    /**
+     * Self-contained `w:docPartBody` children, cloned with fresh ids at apply.
+     * Resource, style, field, bookmark, note and revision references return `unsupported`.
+     */
+    readonly blocks: readonly OoxmlNode[];
+}
+
+/**
+ * Why a zip was refused at the trust boundary.
+ *
+ * `too-large` and `too-many-entries` are the zip-bomb guards; `bad-name` catches path traversal —
+ * an entry with `..` or a leading `/` is rejected rather than normalized.
+ */
+type ZipRejection = 'too-many-entries' | 'too-large' | 'bad-name' | 'inflate-error';
+/** Archive caps: entry count, total decompressed bytes, and the decompression ratio. */
+interface ZipLimits {
+    readonly maxEntries: number;
+    /** Max total UNCOMPRESSED bytes across the archive. */
+    readonly maxTotalBytes: number;
+    /**
+     * Max ratio of the archive's total declared uncompressed bytes to the archive's own byte
+     * length (zip-bomb guard). Applies once that total exceeds 8 MiB, so a small archive is
+     * never refused for compressing well.
+     */
+    readonly maxRatio?: number;
+}
+/** The archive caps in force when a host configures none. Conservative and finite. */
+declare const DEFAULT_ZIP_LIMITS: ZipLimits;
+/** The read entries, or the typed refusal. Never throws — the bytes are untrusted. */
+type ZipReadResult = {
+    readonly ok: true;
+    readonly entries: ReadonlyMap<string, Uint8Array>;
+} | {
+    readonly ok: false;
+    readonly reason: ZipRejection;
+    readonly detail?: string;
+    readonly limit?: 'zip.maxTotalBytes' | 'zip.maxRatio';
+};
+/**
+ * Inflate a ZIP archive with bounds + OPC name normalization. Entry name, count, archive
+ * ratio, and total-uncompressed-size limits are enforced BEFORE each entry is decompressed
+ * (via fflate's pre-inflation filter), so a zip bomb or a traversal name is rejected without
+ * ever being inflated. Keys are canonical part names.
+ *
+ * The budgets count each entry's DECLARED sizes, and the declared size is also a hard cap on
+ * what the entry may produce: fflate inflates into a buffer of exactly `originalSize` bytes
+ * and never grows it, so an entry whose stream holds more than it declares is truncated (or
+ * refused as `inflate-error`), never expanded past its budget. A stored entry is copied at
+ * its compressed size, so the larger of its two declared sizes is what counts.
+ */
+declare function readZip(bytes: Uint8Array, limits?: ZipLimits): ZipReadResult;
+/** Deflate a set of canonical-part-name -> bytes into a ZIP archive. Every part name
+ *  is re-validated through the OPC normalization profile before writing, so a
+ *  traversal/encoded/normalized-alias name from an untrusted serialized model can
+ *  never be smuggled into a ZIP entry (write-side path-traversal guard). */
+declare function writeZip(entries: ReadonlyMap<string, Uint8Array>): Uint8Array;
+
+/**
+ * Why a part or relationship name was refused.
+ *
+ * Path traversal is the reason this exists: a name with `..` or a leading `/` is refused rather
+ * than normalized, because normalizing is how a crafted package reaches outside itself.
+ */
+type NameRejection = 'empty' | 'control-char' | 'backslash' | 'drive-or-unc' | 'encoded-separator' | 'encoded-dot' | 'bad-encoding' | 'empty-segment' | 'dot-segment' | 'unsafe-key' | 'segment-trailing-dot' | 'traversal-escape' | 'not-absolute-uri' | 'unsafe-scheme';
+/** A validated OPC name, or the typed reason it was refused. */
+type NameResult = {
+    readonly ok: true;
+    readonly partName: string;
+} | {
+    readonly ok: false;
+    readonly reason: NameRejection;
+};
+/**
+ * Normalize a ZIP entry name or OPC part name into a canonical part name
+ * (`/word/document.xml`). Accepts leading-slash and no-leading-slash inputs;
+ * rejects traversal, dot segments, and the attack surface. Duplicate detection
+ * folds ASCII case (OPC part-name equivalence).
+ */
+declare function normalizePartName(raw: string): NameResult;
+/**
+ * ASCII-only lowercase fold. OPC part-name/extension equivalence is US-ASCII
+ * case-insensitive; a locale `toLowerCase()` mis-folds e.g. Turkish `I`/`İ` and
+ * could let two "equivalent" part names evade duplicate detection.
+ */
+declare function asciiFold(s: string): string;
+/** Case-folded key for OPC part-name equivalence / duplicate detection. */
+declare function partNameKey(partName: string): string;
+/**
+ * Detect archive entries that collide after normalization (before inflation).
+ * Returns the case-folded keys that more than one raw name maps to.
+ */
+declare function detectDuplicateNames(rawNames: readonly string[]): {
+    readonly duplicates: readonly string[];
+    readonly rejected: readonly {
+        raw: string;
+        reason: NameRejection;
+    }[];
+};
+/**
+ * Resolve an internal relationship target against its owner part, without
+ * escaping the package root. `ownerPartName` is a canonical part name; the base
+ * is its containing folder. A leading "/" target is package-absolute. `.`/`..`
+ * segments resolve on a stack; popping above root is `traversal-escape`.
+ */
+declare function resolveInternalTarget(ownerPartName: string, rawTarget: string): NameResult;
+/**
+ * Validate an external-mode relationship target. It MUST be an absolute URI, is
+ * retained verbatim by the caller, and is NEVER owner-resolved or fetched here.
+ * Unsafe schemes (javascript/vbscript/data/file) are rejected for runtime sinks;
+ * the raw lexical form is still preserved separately by the authored record.
+ */
+declare function validateExternalTarget(raw: string): NameResult;
+
+/** OOXML image relationship type for embedded or linked media parts. */
+declare const IMAGE_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
+/**
+ * Whether a relationship points inside the package or out of it.
+ *
+ * The security-relevant distinction: an `External` target is retained VERBATIM and never
+ * owner-resolved or fetched, because auto-loading a file-supplied remote target is a zero-click
+ * external fetch.
+ */
+type TargetMode = 'Internal' | 'External';
+/**
+ * One authored relationship, with nothing materialized away: owner part, id, type, raw target
+ * lexical form, mode, and position.
+ */
+interface RelationshipRecord {
+    readonly ownerPart: string;
+    readonly id: string;
+    readonly type: string;
+    readonly rawTarget: string;
+    readonly targetMode: TargetMode;
+    readonly order: number;
+}
+/** Why a relationship set is invalid. Duplicate ids within one owner fail closed. */
+type RelationshipError = {
+    readonly code: 'duplicate-id';
+    readonly ownerPart: string;
+    readonly id: string;
+};
+/** The validated relationship set, or the conflict that rejected it. */
+type RelationshipSetResult = {
+    readonly ok: true;
+    readonly byOwner: ReadonlyMap<string, readonly RelationshipRecord[]>;
+} | {
+    readonly ok: false;
+    readonly error: RelationshipError;
+};
+/** Group relationships by owner in authored order; reject duplicate ids per owner. */
+declare function buildRelationshipSet(records: readonly RelationshipRecord[]): RelationshipSetResult;
+/**
+ * A relationship resolved to a part, or the reason it could not be.
+ *
+ * External targets resolve to a refusal by design: they are never followed from a file.
+ */
+type ResolvedRelationship = {
+    readonly mode: 'Internal';
+    readonly target: NameResult;
+    readonly raw: string;
+} | {
+    readonly mode: 'External';
+    readonly sinkSafe: NameResult;
+    readonly raw: string;
+};
+/**
+ * Resolve a relationship to a runtime projection while the raw target stays
+ * authored. Internal -> owner-relative part name; External -> sink-safe
+ * validation only (never owner-resolved, never fetched). `raw` is always the
+ * verbatim authored target.
+ */
+declare function resolveRelationship(rec: RelationshipRecord): ResolvedRelationship;
+/**
+ * An image relationship resolved to package bytes, or why it was refused.
+ *
+ * External-mode image rels are refused rather than fetched — the no-zero-click-external-fetch
+ * rule applies to images exactly as it does to links.
+ */
+type ImageRelationshipResolution = {
+    readonly mode: 'internal';
+    readonly partName: string;
+    readonly raw: string;
+} | {
+    readonly mode: 'external';
+    readonly sinkSafe: boolean;
+    readonly raw: string;
+} | {
+    readonly mode: 'missing';
+};
+/**
+ * Resolve an image relationship id from an owner part. Internal targets resolve
+ * owner-relative; external targets are never fetched; a missing id is `missing`.
+ */
+declare function resolveImageRelationship(records: readonly RelationshipRecord[] | undefined, ownerPart: string, relationshipId: string): ImageRelationshipResolution;
+
+/** One `<Default>`: a file extension mapped to a content type. */
+interface DefaultRecord {
+    readonly extension: string;
+    readonly contentType: string;
+    readonly order: number;
+}
+/** One `<Override>`: a specific part name mapped to a content type. Beats any Default. */
+interface OverrideRecord {
+    readonly partName: string;
+    readonly contentType: string;
+    readonly order: number;
+}
+/**
+ * The authored `[Content_Types].xml` records, in significant order.
+ *
+ * Retained rather than collapsed into a lookup, because the file's lexical form and ordering are
+ * part of what a lossless save re-emits.
+ */
+interface ContentTypeRecords {
+    readonly defaults: readonly DefaultRecord[];
+    readonly overrides: readonly OverrideRecord[];
+}
+/**
+ * Why content-type records could not be indexed.
+ *
+ * All fail CLOSED: conflicting Defaults on one extension, duplicate normalized Override names, or
+ * invalid MIME syntax are refused rather than resolved by picking one.
+ */
+type ContentTypeError = {
+    readonly code: 'invalid-mime';
+    readonly value: string;
+} | {
+    readonly code: 'conflicting-default';
+    readonly extension: string;
+} | {
+    readonly code: 'duplicate-override';
+    readonly partName: string;
+} | {
+    readonly code: 'invalid-override-name';
+    readonly partName: string;
+} | {
+    readonly code: 'too-many-records';
+    readonly limit: number;
+};
+/** Whether a string is syntactically a MIME type. Syntax only — no registry lookup. */
+declare function isValidMime(value: string): boolean;
+/** ASCII-case-insensitive extension key (leading dot removed; ASCII-only fold). */
+declare function extensionKey(extension: string): string;
+/** The resolved lookup: Override by case-folded part name, Default by case-insensitive extension. */
+interface ContentTypeIndex {
+    /** ext key -> single MIME (identical duplicates collapsed). */
+    readonly defaults: ReadonlyMap<string, string>;
+    /** case-folded part name -> MIME. */
+    readonly overrides: ReadonlyMap<string, string>;
+}
+/** The built index, or the conflict that made it impossible. */
+type IndexResult = {
+    readonly ok: true;
+    readonly index: ContentTypeIndex;
+} | {
+    readonly ok: false;
+    readonly error: ContentTypeError;
+};
+/**
+ * Build a resolved content-type index, failing closed on conflict/duplicate/MIME
+ * errors. `maxRecords` bounds the combined record count (N/N+1 gate).
+ */
+declare function buildContentTypeIndex(records: ContentTypeRecords, maxRecords?: number): IndexResult;
+/**
+ * A part's content type, or why it has none.
+ *
+ * An orphan record never determines a part's type — a Default with no matching part is preserved
+ * inertly rather than applied.
+ */
+type ResolveResult = {
+    readonly ok: true;
+    readonly contentType: string;
+    readonly source: 'override' | 'default';
+} | {
+    readonly ok: false;
+    readonly reason: 'unknown';
+};
+/** Resolve a part's content type: Override wins over Default; else unknown. */
+declare function resolveContentType(index: ContentTypeIndex, partName: string): ResolveResult;
+
+type ShapeSchemeColorResolver = (scheme: string) => string | null;
+type ShapeStyleMatrixResolver = (kind: 'fill' | 'line', index: number) => OoxmlElement | null;
+/**
+ * The renderable subset of a `wps:wsp` non-picture graphic, or of one bounded `wpg:wgp`
+ * group of them: closed polygon subpaths (`a:custGeom` with move/line/close/cubicBezTo
+ * verbs, or a supported `a:prstGeom`) with a solid fill and/or stroke. The colour may come
+ * from `a:srgbClr` or from the theme, through `a:schemeClr` or a `wps:style` matrix
+ * reference. Anything richer (gradient and picture fills, text bodies, rotation, a nested
+ * group) projects as `null` and paints the labelled placeholder instead.
+ */
+interface VectorShapeProjection {
+    /** The drawing extent that frames the subpath coordinate space. */
+    readonly extentEmu: Readonly<{
+        cx: number;
+        cy: number;
+    }>;
+    /**
+     * Every component's subpath polygons, flattened, in extent-EMU space; fill rule is
+     * even-odd. Painting reads `components`, which keeps each polygon with its own colours;
+     * this stays the geometry summary (bounds, hit tests, wrap holes).
+     */
+    readonly subpathsEmu: readonly (readonly Readonly<{
+        x: number;
+        y: number;
+    }>[])[];
+    /**
+     * Validated 6-digit sRGB hex (no `#`) of the one component, or null. A group of two or
+     * more components has no single fill, so this is null there as well: null means "no one
+     * fill to name", not "nothing is filled". Read `components` to paint.
+     */
+    readonly fillHex: string | null;
+    readonly fillAlpha?: number;
+    /** As `fillHex`, for the stroke: the one component's stroke, else null. */
+    readonly strokeHex: string | null;
+    readonly strokeAlpha?: number;
+    /** The one component's stroke width in EMU; 0 when absent or when grouped. */
+    readonly strokeWidthEmu: number;
+    /** Independently styled paths, always non-empty. A direct shape has one component. */
+    readonly components: readonly VectorShapeComponent[];
+}
+interface VectorShapeComponent {
+    readonly subpathsEmu: readonly (readonly Readonly<{
+        x: number;
+        y: number;
+    }>[])[];
+    /** Authored close commands; omitted by older consumers means closed polygons. */
+    readonly subpathsClosed?: readonly boolean[];
+    /** Filled line-end polygons in the same projected coordinate space. */
+    readonly arrowheadsEmu?: readonly (readonly Readonly<{
+        x: number;
+        y: number;
+    }>[])[];
+    readonly fillHex: string | null;
+    readonly fillAlpha: number;
+    readonly strokeHex: string | null;
+    readonly strokeAlpha: number;
+    readonly strokeWidthEmu: number;
+    /**
+     * The outline sits inside the closed geometry (`a:ln algn="in"`): painters draw it at twice
+     * its width clipped to the path, so the authored width stays inside the shape and adds no
+     * reach past the extent. Set only for a closed outline with area.
+     */
+    readonly strokeInset?: boolean;
+}
+/**
+ * The story carried by a `wps:wsp` text box (`wps:txbx` → `w:txbxContent`).
+ *
+ * The projection captures only the story root and the shape chrome reads; it never walks the
+ * story content, so the per-drawing element budget is not spent on paragraphs. Layout collects
+ * blocks from `content` under its own caps.
+ */
+interface TextboxStoryProjection {
+    /** Canonical node id of the `w:txbxContent` element. */
+    readonly contentNodeId: string;
+    /** The `w:txbxContent` element itself; treated as an opaque story root here. */
+    readonly content: OoxmlElement;
+    /** `wps:bodyPr` insets with the OOXML defaults (91440 EMU l/r, 45720 EMU t/b) when absent. */
+    readonly insetsEmu: Readonly<{
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    }>;
+    /** `wps:bodyPr/@anchor` collapsed to the three renderable positions; default top. */
+    readonly verticalAnchor: 'top' | 'center' | 'bottom';
+    /** Autofit child of `wps:bodyPr`; extent stays authoritative either way (diagnostic only). */
+    readonly autofit: 'none' | 'shape' | 'normal';
+    /**
+     * `wps:bodyPr/@wrap="none"` (VML `mso-wrap-style:none`): lines never wrap at the box edge,
+     * and the box takes the width of its widest line plus the insets. Absent for wrapped text.
+     */
+    readonly noWrap?: true;
+    /** Solid fill of the hosting shape, painted behind the story; null for no fill. */
+    readonly fillHex: string | null;
+    /** Solid outline of the hosting shape; null for no outline. */
+    readonly strokeHex: string | null;
+    /** Outline width in EMU; 0 when absent. */
+    readonly strokeWidthEmu: number;
+}
+
+/** Only generated, escaped SVG and relationship slots; never authored markup. */
+type LegacyGraphicFragment = string | Readonly<{
+    relationshipId: string;
+    before: string;
+    after: string;
+    nativeCrop?: SourceCrop;
+}>;
+interface LegacyGraphicProjection {
+    readonly width: number;
+    readonly height: number;
+    readonly fragments: readonly LegacyGraphicFragment[];
+}
+
+/** Picture color adjustments shared by projection, layout, and paint.
+ * @public
+ */
+interface DrawingImageEffects {
+    /** Fixed alpha multiplier for raster painting; omitted means opaque. */
+    readonly opacity?: number;
+    readonly grayscale: boolean;
+    readonly brightness: number;
+    readonly contrast: number;
+    readonly bilevel?: number;
+}
+
+/** One text box member of a drawing group. */
+interface GroupTextboxProjection {
+    /** Canonical node id of the member `wps:wsp`; namespaces the story's line ids. */
+    readonly memberNodeId: string;
+    /** The member box in the group's extent space, in EMU (origin at the extent's top-left). */
+    readonly frameEmu: Readonly<{
+        x: number;
+        y: number;
+        cx: number;
+        cy: number;
+    }>;
+    /** The member's story, projected at the scaled member size. */
+    readonly story: TextboxStoryProjection;
+    /**
+     * Clockwise turn of the member's text about the member box center, in degrees [0, 360):
+     * the member's `rot`, plus 180 for `flipV`. `flipH` never mirrors the text.
+     */
+    readonly rotationDegrees: number;
+}
+
+/** The relationship namespace `r:id` lives in. */
+declare const OFFICE_RELATIONSHIP_NAMESPACE_URI = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+/** The `Type` a hyperlink relationship declares. */
+declare const HYPERLINK_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
+/**
+ * What a part's relationships answer for one `r:id`: the authored target and whether the
+ * package declared it external. `null` for an id the part does not declare — a DANGLING
+ * relationship, which is a real thing in real documents.
+ */
+type RelationshipTargetResolver = (relationshipId: string) => {
+    readonly target: string;
+    readonly external: boolean;
+    /**
+     * The PACKAGE's own verdict on this target (`validateExternalTarget`): whether it is an
+     * absolute URI with a safe scheme.
+     *
+     * Carried separately because `sanitizeHref` cannot answer it. That function is a SCHEME
+     * allowlist and deliberately admits relative URLs — the right rule for a value the host
+     * authored, and the wrong one for a value a `.docx` did. A file-supplied
+     * `Target="/admin/delete-account"` has no scheme to refuse, so it would pass the
+     * allowlist and resolve against the EMBEDDING APPLICATION'S origin: a link reading
+     * "Company policy" that issues an authenticated same-origin request to whatever host
+     * app the editor is mounted in. Absent, a target is treated as unverified.
+     */
+    readonly sinkSafe?: boolean;
+} | null;
+/**
+ * What a hyperlink points at, which decides what activating it may do.
+ *
+ * The security-relevant split: an `external` link goes through `sanitizeHref` and opens only on
+ * explicit user action, while an anchor merely scrolls and never navigates.
+ */
+type HyperlinkKind = 
+/** `r:id` → a relationship with `TargetMode="External"`. Opens somewhere else. */
+'external'
+/** `w:anchor` → a bookmark in this document. Scrolls, never navigates. */
+ | 'internal'
+/**
+ * `r:id` naming a relationship the part does not declare, or one that is not external.
+ *
+ * The link keeps its runs — the text is never lost twice — but there is nothing to
+ * activate, so it paints inert exactly like a refused scheme.
+ */
+ | 'unresolved';
+/** A resolved hyperlink: its kind, its target, and the tooltip Word shows on hover. */
+interface HyperlinkTarget {
+    readonly kind: HyperlinkKind;
+    /**
+     * The authored target, verbatim: the relationship's `Target` for an `r:id` link, the
+     * anchor name for an internal one. Save re-emits from the tree, never from this — it is
+     * here so a UI can show what the document actually says.
+     */
+    readonly authored: string;
+    /**
+     * The sanitized runtime projection, or `null` when there is nothing safe to navigate to.
+     * The ONLY value permitted in a DOM `href`, `window.open`, or a copied link.
+     */
+    readonly href: string | null;
+    /** `w:anchor`, for an internal link. */
+    readonly anchor?: string;
+    /** `w:tooltip` — Word's hover text; paint puts it on the anchor's `title`. */
+    readonly tooltip?: string;
+    /** The authored `r:id`, so an edit can rewrite the relationship it names. */
+    readonly relationshipId?: string;
+}
+/** Whether a node is a typed `w:hyperlink`. */
+declare function isHyperlinkNode(node: OoxmlNode): boolean;
+/** A typed hyperlink's `w:anchor`, or undefined. */
+declare function hyperlinkAnchorOf(link: OoxmlNode): string | undefined;
+/** A typed hyperlink's `r:id`, or undefined. */
+declare function hyperlinkRelationshipIdOf(link: OoxmlNode): string | undefined;
+/**
+ * Read a typed `w:hyperlink` into its target record.
+ *
+ * `r:id` wins over `w:anchor` when a link carries both, matching Word: the relationship
+ * names the document and the anchor names a place inside it, so the pair is a link to a
+ * bookmark in ANOTHER file — which this engine will not follow, but whose external half is
+ * the part that decides where it points.
+ *
+ * A link with neither is `unresolved`: it paints its runs and does nothing.
+ */
+declare function hyperlinkTargetOf(link: OoxmlNode, resolve: RelationshipTargetResolver): HyperlinkTarget;
+
+interface DrawingProjectionLimits {
+    readonly maxCompatibilityBranches: number;
+    readonly maxVisitedElements: number;
+    readonly maxDrawingDepth: number;
+}
+interface DrawingDiagnostic {
+    readonly code: 'malformed-drawing' | 'unsupported-graphic' | 'unresolvable-frame' | 'invalid-geometry' | 'resource-refused' | 'wrap-polygon-over-limit' | 'wrap-polygon-malformed';
+    readonly nodeId: string;
+    readonly detail: string | null;
+}
+
+/** One picture painted as a member of a drawing group. */
+interface GroupPictureProjection {
+    readonly embeddedRelationshipId: string | null;
+    readonly linkedRelationshipId: string | null;
+    readonly crop: Readonly<{
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    }>;
+    /** The picture's rectangle inside the drawing extent, in extent EMU. */
+    readonly frameEmu: Readonly<{
+        x: number;
+        y: number;
+        cx: number;
+        cy: number;
+    }>;
+    /** Canonical node id of the `pic:pic` member. The vector projection skips it. */
+    readonly memberNodeId: string;
+    /**
+     * Whether the group is the chosen branch of a run-level `mc:AlternateContent`. Layout then
+     * drops the whole group when the picture resource fails, as the projection drops other
+     * MC payloads it cannot draw.
+     */
+    readonly alternateContent: boolean;
+}
+
+/**
+ * Whether a drawing sits in the text flow or is positioned against a frame.
+ *
+ * The distinction that decides everything downstream: an inline drawing occupies a character
+ * position, while an anchored one has offsets relative to a page, margin or column.
+ */
+type DrawingKind = 'inline' | 'anchored';
+/** Nine Word wrap menu targets (inline plus eight floating modes). @public */
+type ImageWrapTarget = 'inline' | 'square' | 'squareLeft' | 'squareRight' | 'tight' | 'through' | 'topAndBottom' | 'behind' | 'inFront';
+/** Every text-wrap mode a drawing may be set to, including `inline`. */
+declare const IMAGE_WRAP_TARGETS: readonly ImageWrapTarget[];
+type DrawingWrapElement = 'none' | 'square' | 'tight' | 'through' | 'topAndBottom';
+type DrawingHorizontalReferenceFrame = 'character' | 'column' | 'insideMargin' | 'leftMargin' | 'margin' | 'outsideMargin' | 'page' | 'rightMargin';
+type DrawingVerticalReferenceFrame = 'bottomMargin' | 'insideMargin' | 'line' | 'margin' | 'outsideMargin' | 'page' | 'paragraph' | 'topMargin';
+/** `a:srcRect` — how much of each edge of the source image is cropped away, as fractions. */
+interface SourceCrop {
+    readonly left: number;
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+}
+interface DrawingTransform {
+    readonly rotationDegrees: number;
+    readonly flipHorizontal: boolean;
+    readonly flipVertical: boolean;
+    /** Source `a:off` in EMU; defaults to origin when absent. */
+    readonly offsetEmu: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    /** Source `a:ext` in EMU; zero falls back to `wp:extent` at geometry time. */
+    readonly extentEmu: Readonly<{
+        cx: number;
+        cy: number;
+    }>;
+}
+/**
+ * What a drawing refuses: selection, movement, resizing, aspect change.
+ *
+ * Read and honoured rather than advisory — chrome that offered a handle the store will refuse
+ * would promise an edit that cannot happen.
+ */
+interface DrawingLocks {
+    readonly select: boolean;
+    readonly move: boolean;
+    readonly resize: boolean;
+    readonly changeAspect: boolean;
+}
+interface DrawingLocksInput {
+    readonly select?: boolean;
+    readonly move?: boolean;
+    readonly resize?: boolean;
+    readonly changeAspect?: boolean;
+}
+/**
+ * An anchored drawing's position: offsets, and the frames they are relative to.
+ *
+ * The relative-to bases matter as much as the offsets. Writing an offset without preserving its
+ * base re-anchors the drawing against a different reference and moves it somewhere nobody asked.
+ */
+interface DrawingPositionInput {
+    /**
+     * `'simple'` when `@simplePos="1"`: `horizontalEmu` / `verticalEmu` are authoritative
+     * `wp:simplePos` x/y. `'frame'` (default) uses positionH/V relative frames.
+     */
+    readonly mode?: 'frame' | 'simple';
+    readonly horizontalEmu?: number;
+    readonly verticalEmu?: number;
+    readonly relativeToH?: DrawingHorizontalReferenceFrame;
+    readonly relativeToV?: DrawingVerticalReferenceFrame;
+}
+interface DrawingProjection {
+    readonly drawingNodeId: string;
+    readonly ownerPartName: string;
+    readonly kind: DrawingKind;
+    readonly relationshipId: string | null;
+    readonly docPrId: number | null;
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly hyperlinkHref: string | null;
+    readonly hidden: boolean;
+    readonly extentEmu: Readonly<{
+        cx: number;
+        cy: number;
+    }>;
+    readonly effectExtentEmu: Readonly<{
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    }>;
+    readonly inlineDistancesEmu: Readonly<{
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    }>;
+    readonly wrap: ImageWrapTarget;
+    readonly wrapGeometry: DrawingWrapProjection | null;
+    readonly position: DrawingPositionProjection | null;
+    readonly anchor: Readonly<{
+        simplePos: boolean;
+        relativeHeight: number;
+        behindDocument: boolean;
+        layoutInCell: boolean;
+        allowOverlap: boolean;
+    }> | null;
+    readonly picture: PictureProjection | null;
+    readonly vectorShape: VectorShapeProjection | null;
+    /** The picture member of a `wpg:wgp` group; `picture` stays null for a group. */
+    readonly groupPicture: GroupPictureProjection | null;
+    readonly textboxStory: TextboxStoryProjection | null;
+    /** Text box members of a `wpg:wgp` group, laid out read-only; absent when none has text. */
+    readonly groupTextboxes?: readonly GroupTextboxProjection[];
+    /** Read-only preview of the supported native VML subset; the canonical XML is untouched. */
+    readonly legacyGraphic?: LegacyGraphicProjection;
+    readonly locks: DrawingLocks;
+    readonly effects: DrawingImageEffects;
+    readonly compatibilityBranchNodeId: string | null;
+    readonly diagnostics: readonly DrawingDiagnostic[];
+    /** Layout-only wrap area of an MC payload that cannot paint (`wrapFootprintProjection`). */
+    readonly footprintOnly?: true;
+}
+interface DrawingAccessibility {
+    /**
+     * The record takes part in layout only, for example the wrap area of a payload that cannot
+     * paint. Outputs must not paint, hit-test, select, link, or export it.
+     */
+    readonly hidden: boolean;
+    readonly decorative: boolean;
+    readonly label: string | null;
+}
+interface DrawingPositionProjection {
+    readonly simplePosition: Readonly<{
+        xEmu: number;
+        yEmu: number;
+    }>;
+    readonly horizontal: Readonly<{
+        relativeFrom: DrawingHorizontalReferenceFrame;
+        align: string | null;
+        offsetEmu: number | null;
+    }>;
+    readonly vertical: Readonly<{
+        relativeFrom: DrawingVerticalReferenceFrame;
+        align: string | null;
+        offsetEmu: number | null;
+    }>;
+}
+interface DrawingWrapProjection {
+    readonly element: DrawingWrapElement;
+    readonly textSide: 'bothSides' | 'left' | 'right' | 'largest';
+    readonly distancesEmu: Readonly<{
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    }>;
+    readonly polygon: readonly Readonly<{
+        x: number;
+        y: number;
+    }>[];
+}
+interface PictureProjection {
+    readonly embeddedRelationshipId: string | null;
+    readonly linkedRelationshipId: string | null;
+    readonly crop: SourceCrop;
+    readonly fillMode: 'stretch' | 'tile';
+    readonly transform: DrawingTransform;
+    readonly presetGeometry: string | null;
+}
+/**
+ * Project one `w:drawing` into the resolved shape layout and chrome read.
+ *
+ * Bounded throughout: extents, crops and nesting all come from a file. Returns a projection that
+ * reports `hidden` and its locks rather than throwing, so an unusable drawing degrades to
+ * something the surface can skip.
+ */
+declare function projectDrawing(drawing: OoxmlDrawingNode, context: Readonly<{
+    ownerPartName: string;
+    supportedMcRequires: ReadonlySet<string>;
+    limits: DrawingProjectionLimits;
+    namespaceScope?: ReadonlyMap<string, string>;
+    resolveRelationship?: RelationshipTargetResolver;
+    resolveSchemeColor?: ShapeSchemeColorResolver;
+    resolveStyleMatrixReference?: ShapeStyleMatrixResolver;
+}>): DrawingProjection | null;
+
+/** Caps applied while loading a package: zip, XML, part count and relationship count. */
+interface OoxmlPackageLimits {
+    readonly zip?: ZipLimits;
+    readonly xml?: XmlLimits;
+    /** Cap on parts converted into canonical trees (N/N+1 gate, not a soft target). */
+    readonly maxXmlParts?: number;
+    /** Cap on relationship records across every rels part. */
+    readonly maxRelationships?: number;
+}
+/** The limits in force when a host configures none. Conservative and finite. */
+declare const DEFAULT_OOXML_PACKAGE_LIMITS: Required<Pick<OoxmlPackageLimits, 'maxXmlParts' | 'maxRelationships'>>;
+/**
+ * An external relationship target. Retained verbatim as authored evidence, with the
+ * sink-safety verdict alongside it. Never resolved against the package, never fetched.
+ */
+interface OoxmlExternalTarget {
+    readonly ownerPart: string;
+    readonly id: string;
+    readonly type: string;
+    readonly rawTarget: string;
+    /** False when the target is not a safe sink (javascript:, file:, ...). Still not fetched. */
+    readonly sinkSafe: boolean;
+}
+/**
+ * A loaded package: every XML part as a canonical tree, plus the non-XML parts kept verbatim.
+ *
+ * The preservation model in one value. Modelled parts re-emit normalized; everything else is
+ * byte-identical, which is why an unrecognized part never costs a document anything.
+ */
+interface OoxmlPackage {
+    /** Canonical trees, keyed by canonical part name. Non-XML parts are absent by design. */
+    readonly parts: ReadonlyMap<string, OoxmlPart>;
+    /** Raw bytes of every entry, including the non-XML parts that have no tree. */
+    readonly partBytes: ReadonlyMap<string, Uint8Array>;
+    /** Internal relationships by owner part, in authored order. */
+    readonly relationships: ReadonlyMap<string, readonly RelationshipRecord[]>;
+    readonly externalTargets: readonly OoxmlExternalTarget[];
+    readonly contentTypes: ContentTypeIndex;
+    /** Canonical name of the part the root `officeDocument` relationship points at. */
+    readonly mainDocumentPart: string;
+}
+/** Why a package could not be loaded. Every code describes the FILE, not the caller. */
+type OoxmlPackageRejection = ZipRejection | OoxmlReadRejection | 'no-content-types' | 'bad-content-types' | 'no-main-document' | 'bad-relationship-target' | 'duplicate-relationship-id' | 'too-many-relationships' | 'too-many-xml-parts';
+/** A loaded package, or a typed refusal. Never throws. */
+type OoxmlPackageResult = {
+    readonly ok: true;
+    readonly package: OoxmlPackage;
+} | {
+    readonly ok: false;
+    readonly reason: OoxmlPackageRejection;
+    readonly detail?: string;
+    readonly limit?: 'zip.maxTotalBytes' | 'zip.maxRatio';
+};
+/**
+ * Load DOCX bytes into canonical typed/generic OOXML trees, bounded at every step.
+ *
+ * THE trust boundary for a document. Composes the hardened primitives — zip limits and OPC name
+ * normalization, content-type indexing, relationship validation, entity-free XML — into one
+ * loader, and returns a typed rejection rather than throwing from inside a decoder.
+ *
+ * Fails closed on every limit, malformed name, unresolvable internal target, duplicate
+ * relationship id, and XML rejection. An external relationship never causes a failure and
+ * never causes a fetch: it is recorded with its sink-safety verdict for a later, explicitly
+ * user-gated lane. A content-type record with an invalid MIME type is treated as absent,
+ * unless it decides the type of the main document part, a relationships part, or a
+ * non-payload part that the package root or the main document relates to.
+ */
+declare function readOoxmlPackage(bytes: Uint8Array, limits?: OoxmlPackageLimits): OoxmlPackageResult;
+/**
+ * Serialize a canonical package back to DOCX bytes.
+ *
+ * Starts from the ORIGINAL entry bytes and overwrites only the parts held as trees. A part
+ * the loader did not model — media, fonts, an XML part outside the modeled set — passes
+ * through untouched, so round-tripping a document cannot lose a part the engine never
+ * claimed to understand.
+ *
+ * The modeled parts are re-emitted NORMALIZED from the tree rather than patched as text.
+ * That is the whole point of the canonical tree: correctness is judged by the two D9
+ * oracles (the namespace-aware fingerprint and the save/reopen semantic digest), not by
+ * byte equality, so a different-but-equivalent spelling is not a defect.
+ *
+ * `writeZip` re-validates every part name, so a name that became unsafe between load and
+ * save cannot be smuggled into the archive.
+ */
+declare function writeOoxmlPackage(pkg: OoxmlPackage): Uint8Array;
+/** Replace one part's tree, returning a new package. Pure, like the tree edits themselves. */
+declare function withPart(pkg: OoxmlPackage, part: OoxmlPart): OoxmlPackage;
+
+/** The `w15` namespace: `commentsExtended.xml` — thread parent and resolved state. */
+declare const W15_NAMESPACE_URI = "http://schemas.microsoft.com/office/word/2012/wordml";
+/** A position in one story: a paragraph node id plus a UTF-16 offset inside it. */
+interface CommentPosition {
+    readonly paragraphId: string;
+    readonly offset: number;
+}
+/**
+ * Where a comment is anchored, as a range.
+ *
+ * `orphaned` records that the file did not give this comment a usable range — a reference with
+ * no range markers, or a start with no end. The comment is still listed, marked orphaned,
+ * rather than dropped: a reviewer's remark disappearing silently is worse than one that says
+ * it lost its text.
+ */
+interface CommentAnchor {
+    readonly commentId: string;
+    /** Canonical name of the part the range lives in, so a header comment is attributable. */
+    readonly partName: string;
+    readonly start: CommentPosition;
+    readonly end: CommentPosition;
+    readonly orphaned: boolean;
+}
+/** One comment as authored in `word/comments.xml`. */
+interface CommentRecord {
+    readonly id: string;
+    readonly author: string;
+    readonly initials?: string;
+    readonly date?: string;
+    /** Body paragraphs, as tree nodes, so the surface renders measured text rather than a string. */
+    readonly blocks: readonly OoxmlElement[];
+    /** `w14:paraId` of the last body paragraph — the key thread state is stored under. */
+    readonly paraId?: string;
+    /** `@w16cid:parentId` — the `w:id` of the comment this replies to, when the file names it. */
+    readonly parentCommentId?: string;
+}
+/** Thread state for one comment, read from `commentsExtended.xml`. */
+interface CommentThreadState {
+    /** `@w15:paraIdParent` — the comment this one replies to, absent for a top-level comment. */
+    readonly parentParaId?: string;
+    readonly done: boolean;
+}
+/**
+ * Every comment anchor in one story, in document order.
+ *
+ * Overlapping and nested ranges are supported because each anchor is resolved independently —
+ * Word produces both, and a model that assumed ranges nest cleanly would mis-anchor them.
+ *
+ * A start with no matching end anchors to the end of its own paragraph and is reported orphaned
+ * rather than guessed at: extending it to the next end marker would attach a reviewer's remark
+ * to text they never saw.
+ */
+declare function commentAnchorsOfStory(part: OoxmlPart): CommentAnchor[];
+/**
+ * The comments in `word/comments.xml`, in authored order.
+ *
+ * Every value here comes from a file an attacker fully controls, so nothing is interpreted:
+ * author, initials and date are carried verbatim for a surface that will set them as TEXT.
+ */
+declare function commentsOfPart(part: OoxmlPart): CommentRecord[];
+/**
+ * Thread state by `w14:paraId`, from `commentsExtended.xml`.
+ *
+ * The part being PRESENT is not evidence of threading. `issue-68-large-comments-suggestions.docx`
+ * ships it with 212 entries carrying `@w15:done` and not one `@w15:paraIdParent`, so it records
+ * resolved state for a flat list. Absent parent means top-level, and that is a fact about the
+ * file rather than a default this code chose.
+ */
+declare function threadStateOfPart(part: OoxmlPart): Map<string, CommentThreadState>;
+/**
+ * Whether the package holds any `w:comment` record — the cheap gate before a reap.
+ *
+ * Overflow cannot prove the package is comment-free, so it returns true and the reap still
+ * runs rather than skipping cleanup.
+ */
+declare function hasAnyComment(pkg: OoxmlPackage): boolean;
+
+/** A position in the model offset space of one story. */
+interface ReviewPosition {
+    readonly paragraphId: string;
+    readonly offset: number;
+}
+/** Where an item is anchored: a range in one story. */
+interface ReviewRange {
+    readonly partName: string;
+    readonly start: ReviewPosition;
+    readonly end: ReviewPosition;
+}
+/**
+ * What kind of decision a revision card represents.
+ *
+ * Wider than the four content wrappers, because a reviewer has to be shown every pending
+ * decision, including the ones that decorate no characters. A card the surface cannot show is
+ * a change the reviewer never learns about — and `acceptAllRevisions` refuses if ANY revision
+ * in the document is one the engine cannot resolve, so an invisible one makes Accept All fail
+ * for a reason nothing on screen explains.
+ */
+type ReviewRevisionKind = 'insert' | 'delete'
+/**
+ * A combined deletion and insertion decision. The built-in reader lists them separately,
+ * unless a review query asks to pair replacements or a custom review provider combines them.
+ */
+ | 'replace' | 'moveFrom' | 'moveTo'
+/** `w:rPrChange` / `w:pPrChange` — the words are unchanged, their formatting is not. */
+ | 'format'
+/** `w:pPr/w:rPr/w:ins|w:del` — a paragraph split or merge. */
+ | 'paragraphMark'
+/** A row, cell, section or grid revision. Supported row revisions are resolvable. */
+ | 'structural';
+/**
+ * One tracked change as a review card.
+ *
+ * Keyed per DECISION rather than per site: a revision spanning three ranges is one card, because
+ * accepting it accepts all three.
+ */
+interface ReviewRevisionItem {
+    readonly kind: 'revision';
+    /** Stable across renders and unique per decision within this editor instance. */
+    readonly id: string;
+    /** The payload `acceptRevision` / `rejectRevision` take. */
+    readonly address: RevisionAddress;
+    /**
+     * EVERY address this decision covers, `address` first.
+     *
+     * Adjacent text fragments, table fragments, and formatting changes can combine multiple
+     * original revisions into one decision. Review commands resolve the complete decision
+     * in one transaction while preserving independent changes outside the group.
+     */
+    readonly addresses: readonly RevisionAddress[];
+    /** The words a replacement removes. Empty for every other kind. */
+    readonly replacedText: string;
+    readonly revisionKind: ReviewRevisionKind;
+    /** OOXML property-change element, used to resolve independently numbered formatting kinds. */
+    readonly formattingKind?: string;
+    /** Distinct structural operations covered by this decision, in document order. */
+    readonly structuralChanges?: readonly ('rowInsert' | 'rowDelete' | 'cellInsert' | 'cellDelete' | 'cellMerge' | 'numberingInsert')[];
+    /** Changed direct formatting values, ready for localized review summaries. */
+    readonly formattingChanges?: readonly {
+        readonly property: 'bold' | 'italic' | 'underline' | 'strike' | 'fontFamily' | 'fontSize' | 'color' | 'alignment' | 'leftIndent' | 'rightIndent' | 'firstLineIndent' | 'hangingIndent' | 'spaceBefore' | 'spaceAfter' | 'direction';
+        /**
+         * New direct value; null means inherit. Sizes and distances are in points. A direction is
+         * `rtl` or `ltr`.
+         */
+        readonly value: string | null;
+    }[];
+    /** Newly applied proofing language codes in a tracked formatting change. */
+    readonly formattingLanguages?: readonly string[];
+    /**
+     * WHICH decision a `paragraphMark` records, absent for every other kind.
+     *
+     * `EG_ParaRPrTrackChanges` is `ins? del? moveFrom? moveTo?`, and the four say opposite
+     * things about one break. Without this a card called a deleted break an inserted one, which
+     * is the reverse of what Accept on that card does.
+     */
+    readonly markDirection?: 'insert' | 'delete' | 'moveFrom' | 'moveTo';
+    readonly author: string;
+    readonly date?: string;
+    /** Text the revision covers, for the card summary. Empty for changes with no characters. */
+    readonly text: string;
+    /** Every site this decision touches, in document order. */
+    readonly ranges: readonly ReviewRange[];
+    /**
+     * How deeply this change is NESTED inside other changes, 0 for an unenclosed one.
+     *
+     * `w:ins` wrapping `w:del` is content one reviewer added and another struck. Both stay
+     * pending, so both are cards, over one identical range — and a range then cannot say which
+     * change a caret is in. Word treats the innermost as the operative one, so it wins the caret
+     * and the change enclosing it stays listed and reachable.
+     */
+    readonly nesting: number;
+    /**
+     * How many leading `ranges` are the STRUCK half of a replacement.
+     *
+     * A replacement's card is one decision but its ranges are two colours — red over what is
+     * going, green over what takes its place. ABSENT when the halves do not split at a single
+     * point, which is what a file recording both under one revision id can produce; a surface
+     * then has no basis for two colours and should paint one neutral band rather than guess.
+     */
+    readonly replacedRangeCount?: number;
+    /**
+     * True when the engine cannot resolve this kind, so accept and reject must not be offered.
+     *
+     * Derived by the DERIVATION rather than from a caller-supplied predicate: the refusal list
+     * is internal, and a surface asked to compute it would have to guess. A card that offers a
+     * button the engine will refuse is worse than one that explains why it cannot.
+     */
+    readonly readOnly: boolean;
+    /** The other half of a move, or the other side of a delete/insert replacement. */
+    readonly pairedWith?: string;
+    /**
+     * Comments answering this change, in document order.
+     *
+     * A reply to a tracked change IS a comment: `w:ins` and `w:del` carry no body, so the text
+     * is written as a comment over the revision's own range and the range is what links them.
+     */
+    readonly replyIds: readonly string[];
+}
+/**
+ * One comment as a review card. A reply carries `parentId`; OOXML gives replies no separate
+ * element, so threads are reconstructed from that link.
+ */
+interface ReviewCommentItem {
+    readonly kind: 'comment';
+    readonly id: string;
+    readonly comment: CommentRecord;
+    readonly range: ReviewRange | null;
+    readonly resolved: boolean;
+    /** The comment this replies to, absent for a top-level comment. */
+    readonly parentId?: string;
+    /** The REVISION this comment answers, when it covers exactly that change's characters. */
+    readonly parentRevisionId?: string;
+    /** Replies to this comment, in document order. Empty for a reply or a childless comment. */
+    readonly replyIds: readonly string[];
+    /** True when the file gave this comment no usable range. */
+    readonly orphaned: boolean;
+}
+/**
+ * A card contributed by a recognized custom node (`defineCustomNode` with a `reviewCard`
+ * hook), anchored at the node's range.
+ *
+ * Informational, never resolvable: there is nothing to accept or reject, so the engine
+ * refuses those verbs on it. `title` and `detail` are HOST-authored (the definition's hook
+ * produced them), but `attrs` and `text` originate in a file an attacker controls — a
+ * surface renders every one of these as text, never markup.
+ */
+interface ReviewCustomItem {
+    readonly kind: 'custom';
+    /** The SDT node's stable id in the canonical tree. */
+    readonly id: string;
+    /** The definition's `name`. */
+    readonly name: string;
+    /** The raw `w:tag` the node was recognized from. Untrusted input. */
+    readonly tag: string;
+    /** Attrs decoded from the tag, after the definition's recognition hook. Untrusted input. */
+    readonly attrs: Readonly<Record<string, string>>;
+    /** The SDT's literal content text. Untrusted input. */
+    readonly text: string;
+    /**
+     * The payload the node's control binds to, after the definition validated it.
+     *
+     * Undefined when the node carries none or the payload did not match — see the pro package's
+     * `RecognizedCustomNode.data`, which this is carried from.
+     */
+    readonly data?: unknown;
+    /**
+     * Whether this node asked for a sidebar card.
+     *
+     * False for a definition with no `reviewCard`: the item exists so the chip's own surfaces can
+     * read `attrs`, `text` and `data` off it, and the rail leaves it out. A surface listing cards
+     * filters on this rather than on an empty `title`. An uncarded node never becomes the active
+     * review item, so it never shows the active highlight.
+     */
+    readonly carded: boolean;
+    /** Card title, from the definition's `reviewCard` hook. Empty when `carded` is false. */
+    readonly title: string;
+    /** Card body, from the definition's `reviewCard` hook. */
+    readonly detail?: string;
+    /**
+     * Glyph for this node in the collapsed rail, as an SVG path in a `0 -960 960 960` viewBox.
+     *
+     * A PATH rather than a rendered node because this item crosses core, which is DOM-free and
+     * React-free — the same reason `title` and `detail` are strings. A host that wants arbitrary
+     * markup overrides the `Markers` part's `icon` instead, which lives in the adapter where JSX
+     * belongs. Absent falls back to the generic custom-node glyph.
+     *
+     * HOST-AUTHORED, never file data: it is interpolated into an SVG `d` attribute, and a path
+     * taken from a document would be attacker-controlled markup.
+     */
+    readonly icon?: string;
+    readonly range: ReviewRange | null;
+}
+/**
+ * One pending decision in the review queue: a tracked change, a comment thread, or a pro
+ * custom-node card. Discriminate on `kind`.
+ *
+ * The store's own derivation (`collectReviewItems`) only ever produces the first two; the
+ * `kind: 'custom'` card is contributed by the pro review module, which recognizes the node.
+ */
+type ReviewItem = ReviewRevisionItem | ReviewCommentItem | ReviewCustomItem;
+/** What the review queue derivation reads: one story part plus its comment parts. */
+interface ReviewModelInput {
+    /** The story the ranges live in — the main document, a header, a note. */
+    readonly storyPart: OoxmlPart;
+    /**
+     * Header/footer story parts, in section order. Their revisions and comment anchors join
+     * the queue: a tracked change in a header is a pending decision like any other, and a
+     * queue that only walked the body silently hid it from the rail AND from Accept All.
+     */
+    readonly furnitureParts?: readonly OoxmlPart[] | undefined;
+    /** Shared style definitions. Their revisions have no paragraph range. */
+    readonly stylesPart?: OoxmlPart | undefined;
+    /** `word/comments.xml`, absent when the package has none. */
+    readonly commentsPart?: OoxmlPart | undefined;
+    /** `word/commentsExtended.xml`, absent when the package has none. */
+    readonly commentsExtendedPart?: OoxmlPart | undefined;
+    /**
+     * Custom node definitions from the module registry, forwarded OPAQUELY.
+     *
+     * Core carries them the way the registry does — as unknowns — so the definition shape
+     * stays a capability-package concern. The pro derivation narrows them and contributes
+     * `kind: 'custom'` cards for definitions that opted in.
+     */
+    readonly customNodes?: readonly unknown[] | undefined;
+    /**
+     * Where a capability package reports a node it could not read. Supplied per editor, so a page
+     * with two of them keeps their diagnostics apart.
+     */
+    readonly reportCustomNodeDiagnostic?: ((diagnostic: unknown) => void) | undefined;
+    /**
+     * The payload each of the story's controls binds to, keyed by the control's node id.
+     *
+     * Resolved by the ENGINE and handed over, because a payload lives in a customXml data part
+     * and a derivation that only receives story parts has no way to reach one. Untrusted file
+     * input on both members; a capability package validates it against whatever shape it
+     * declared before handing it to a host.
+     */
+    readonly customNodePayloads?: ReadonlyMap<string, {
+        readonly nodeId: string;
+        readonly label: string;
+        readonly data: string;
+    }> | undefined;
+}
+/** The stable key a surface uses for the active item and for a React list. */
+declare function reviewItemKey(item: ReviewItem): string;
+/** Every range a decision touches. One card can cover several, in different paragraphs. */
+declare function reviewItemRanges(item: ReviewItem): readonly ReviewRange[];
+/** The first range of an item, in authored order, or null when it has none. */
+declare function firstReviewRange(item: ReviewItem): ReviewRange | null;
+/**
+ * A single comparable number for document order.
+ *
+ * Paragraph index dominates offset, so a revision spanning paragraphs still sorts by where it
+ * STARTS. An item with no resolvable range sorts last rather than to position zero, which is
+ * where an orphan used to land — tearing an orphaned reply out of its own thread.
+ */
+declare function reviewItemPositionRank(item: ReviewItem, order: ReadonlyMap<string, number>): number;
+/**
+ * Every item covering a position, innermost first.
+ *
+ * Returning the whole stack rather than one winner is what lets a surface offer cycling, a
+ * stacked card, or a "1 of 3" affordance. A comment wrapping a revision used to be unreachable
+ * because only the tightest range was ever returned.
+ */
+declare function reviewItemsAt(items: readonly ReviewItem[], position: ReviewPosition, order: ReadonlyMap<string, number>): ReviewItem[];
+/**
+ * The item the caret is in, or null.
+ *
+ * A resolved comment never activates: a settled thread must not reopen itself as the reviewer
+ * types near it.
+ *
+ * A REPLY resolves to the thread it belongs to. A reply is anchored over its parent's range,
+ * so both cover the caret — and the reply, being newer, wins the innermost test. It is not a
+ * card of its own (it renders inside its parent's), so the thread would have gone active with
+ * nothing on screen showing it: the reply box vanished from a comment the moment somebody
+ * replied to it.
+ */
+declare function activeReviewItem(items: readonly ReviewItem[], position: ReviewPosition, order: ReadonlyMap<string, number>): ReviewItem | null;
+/**
+ * Walk a reply up to the card that heads its thread. Guarded against a cyclic file.
+ *
+ * The head is not always a comment. A reply to a tracked change renders inside the REVISION's
+ * card, so resolving it to itself opened an item nothing on screen was drawing — the reply box
+ * vanished the moment somebody answered a change.
+ *
+ * EXPORTED because the paginated surface answers "which card is open" itself, against its own
+ * dismissed-key state, rather than through {@link activeReviewItem}. Two copies of the
+ * innermost-wins rule was survivable while a reply could only be a comment — the parent came
+ * first in `comments.xml` order and won the tie by accident. It stopped being survivable the
+ * moment a reply could answer a revision, which outranks it outright.
+ */
+declare function reviewThreadRootOf(items: readonly ReviewItem[], comment: ReviewCommentItem): ReviewItem;
+
+/** How deep controls may nest before a walk stops descending. Shared by every lane. */
+declare const MAX_CONTENT_CONTROL_NESTING = 32;
+/** Cap on controls one walk reports, so a hostile file cannot make a read unbounded. */
+declare const MAX_CONTENT_CONTROLS_PER_PART = 10000;
+/** `CT_SdtPr/w:id` is `ST_DecimalNumber`; Word treats it as a signed 32-bit integer. */
+declare const CONTENT_CONTROL_ID_MAX = 2147483647;
+/** `ST_Lock` (§17.5.2.24). An absent `w:lock` is `unlocked`. */
+/**
+ * `w:lock` — what a control refuses.
+ *
+ * `sdtLocked` protects the wrapper, `contentLocked` the text inside it, and `sdtContentLocked`
+ * both. A control inside a locked one is locked in effect regardless of its own value.
+ */
+type ContentControlLock = 'unlocked' | 'sdtLocked' | 'contentLocked' | 'sdtContentLocked';
+/**
+ * What kind of control this is.
+ *
+ * `checkbox` is the Microsoft `w14:checkbox` extension rather than an ECMA-376 type
+ * element, and the two are not mutually exclusive with "declares no type": four controls
+ * in the comprehensive fixture declare the extension and no `w:`-prefixed type, so a scan
+ * that read only the ECMA-376 choice reported them untyped. `untyped` means the control
+ * declares neither — a rich-text container, which is what Word treats it as.
+ */
+/** Which kind of control a `w:sdt` is, and therefore what a written value must look like. */
+type ContentControlKind = 'richText' | 'plainText' | 'checkbox' | 'dropDownList' | 'comboBox' | 'date' | 'picture' | 'docPartObj' | 'docPartList' | 'group' | 'citation' | 'bibliography' | 'equation' | 'untyped';
+/** One declared option of a dropdown or combo box: its display text and its stored value. */
+interface ContentControlListItem {
+    readonly displayText: string;
+    readonly value: string;
+}
+/** A date picker's authored format and locale, for rendering and for parsing what it stores. */
+interface ContentControlDateFormat {
+    readonly fullDate?: string;
+    readonly dateFormat?: string;
+    readonly lid?: string;
+    readonly storeMappedDataAs?: string;
+    readonly calendar?: string;
+}
+/** One of a checkbox's two glyphs: the font and code point it is drawn with. */
+interface ContentControlCheckboxState {
+    /** The `w14:val` hex code point of the glyph, exactly as the control declares it. */
+    readonly value: string;
+    readonly font?: string;
+}
+/**
+ * A checkbox's state and the two glyphs it chooses between.
+ *
+ * Both glyphs matter on a write: setting the value has to update `w14:checked` AND the run's
+ * character, or the document's glyph and its recorded state disagree.
+ */
+interface ContentControlCheckbox {
+    readonly checked: boolean;
+    readonly checkedState?: ContentControlCheckboxState;
+    readonly uncheckedState?: ContentControlCheckboxState;
+}
+/** `CT_DataBinding` — preserved metadata. Never resolved, never fetched. */
+/** `w:dataBinding` — the custom-XML part and XPath a control's value is bound to. */
+interface ContentControlDataBinding {
+    readonly xpath?: string;
+    readonly storeItemID?: string;
+    readonly prefixMappings?: string;
+}
+/**
+ * A control's whole `w:sdtPr`, projected into one typed shape.
+ *
+ * What every other lane reads instead of walking `localName` strings — which also means a Word
+ * re-save that demotes the properties node to generic does not break the projection.
+ */
+interface ContentControlProperties {
+    readonly type: ContentControlKind;
+    readonly alias?: string;
+    readonly tag?: string;
+    /** `@w:val` of `w:id` when the file declares a parseable one. Never fabricated. */
+    readonly id?: number;
+    readonly lock: ContentControlLock;
+    /** The glossary entry named by `w:placeholder/w:docPart`. Preserved, never loaded. */
+    readonly placeholderDocPart?: string;
+    readonly temporary: boolean;
+    readonly showingPlaceholder: boolean;
+    readonly dataBinding?: ContentControlDataBinding;
+    readonly label?: string;
+    readonly tabIndex?: number;
+    /** Items a dropdown or combo box offers. Empty for every other type. */
+    readonly listItems: readonly ContentControlListItem[];
+    readonly lastValue?: string;
+    readonly date?: ContentControlDateFormat;
+    readonly multiLine?: boolean;
+    readonly checkbox?: ContentControlCheckbox;
+}
+/** Whether a node is a `w:sdt` wrapper. */
+declare function isContentControlNode(node: OoxmlNode): node is OoxmlContentControlNode;
+/** Whether a node is a `w:sdtContent` — the container holding a control's actual content. */
+declare function isContentControlContentNode(node: OoxmlNode): node is OoxmlContentControlContentNode;
+/**
+ * A `w:sdt` wrapper, TYPED or DEMOTED.
+ *
+ * Flattening predates typing and must not stop at a control the reader refused to type: a
+ * demoted wrapper still renders its content in place in Word, so a walk that only saw the
+ * typed kind would drop every paragraph inside a malformed control out of the story.
+ */
+declare function isContentControlWrapper(node: OoxmlNode): boolean;
+/**
+ * The children of a wrapper's `w:sdtContent`, typed or demoted, in order.
+ *
+ * The one place that knows a control's content is reached through an intermediate element,
+ * so the four flattening walks (story blocks, layout, header/footer references, list
+ * resolution) ask the same question rather than each re-deriving it.
+ */
+declare function contentControlContentChildren(wrapper: OoxmlNode): readonly OoxmlNode[];
+/**
+ * A container's children with every content-control wrapper flattened away, bounded in depth.
+ *
+ * ONE unwrap rule, for the places where a control sits between a container and the children that
+ * container is defined in terms of. `CT_SdtRow` puts it between `w:tbl` and `w:tr`, `CT_SdtCell`
+ * between `w:tr` and `w:tc`, and a walk that filtered on the child's kind dropped the row or cell
+ * entirely: not measured, not painted, not addressable. Flattening at the point of the filter
+ * means a controlled row is the same row to the grid pass, the pagination pass and the story walk.
+ *
+ * Returns the SAME array identity when there is nothing to unwrap, so the tables that carry no
+ * controls — nearly all of them — allocate nothing and the incremental layout cache still sees
+ * its own inputs.
+ */
+declare function flattenContentControls(children: readonly OoxmlNode[], maxDepth?: number): readonly OoxmlNode[];
+/** A control's `w:sdtPr`, or null. Matches structurally, so a Word-demoted node still resolves. */
+declare function contentControlPropertiesNodeOf(control: OoxmlNode): OoxmlContentControlPropertiesNode | undefined;
+/** A control's `w:sdtEndPr` — the run properties applied to its closing marker. */
+declare function contentControlEndPropertiesNodeOf(control: OoxmlNode): OoxmlContentControlEndPropertiesNode | undefined;
+/** A control's `w:sdtContent`, or null when the wrapper has none. */
+declare function contentControlContentNodeOf(control: OoxmlNode): OoxmlContentControlContentNode | undefined;
+/** A signed 32-bit `ST_DecimalNumber`, or undefined when the file wrote something else. */
+declare function parseContentControlId(raw: string | undefined): number | undefined;
+/**
+ * Read a control's properties.
+ *
+ * Total: a control with no `w:sdtPr` at all answers the same shape with the defaults an
+ * absent property means, so no caller has to branch on the container's existence.
+ */
+declare function contentControlPropertiesOf(control: OoxmlNode): ContentControlProperties;
+/** Where a control sits, read off what its content holds. */
+type ContentControlLevel = 'block' | 'inline' | 'row' | 'cell' | 'empty';
+/**
+ * How deeply a control is nested inside other controls.
+ *
+ * Bounded by {@link MAX_CONTENT_CONTROL_NESTING}: nesting depth comes from a file and is a
+ * recursion bound.
+ */
+declare function contentControlLevelOf(control: OoxmlNode): ContentControlLevel;
+/** One control, plus how deeply it is nested and the controls that enclose it. */
+interface ContentControlEntry {
+    readonly node: OoxmlContentControlNode;
+    /** 0 for a top-level control; the nesting depth otherwise. */
+    readonly depth: number;
+    /** Enclosing controls, outermost first. Empty at depth 0. */
+    readonly ancestors: readonly OoxmlContentControlNode[];
+}
+/**
+ * Every control under a node, in document order, bounded in depth and in count.
+ *
+ * ONE walk, shared. The nesting bound is the same one layout flattens with, so a control
+ * a lane can address is a control every lane can address — and a file that nests past it
+ * keeps its content in the tree (the serializer never stops) while no walk recurses
+ * further.
+ */
+declare function contentControlsIn(root: OoxmlNode, options?: {
+    readonly maxDepth?: number;
+    readonly limit?: number;
+}): readonly ContentControlEntry[];
+/** Find one control by canonical node id, with the same bounded walk. */
+declare function findContentControl(root: OoxmlNode, nodeId: string): ContentControlEntry | null;
+/**
+ * The plain text a control's content holds, in reading order.
+ *
+ * `w:delText` is excluded: struck text is not the control's value, and a dropdown whose
+ * old item is still present as a tracked deletion would otherwise report both.
+ *
+ * A manual line break is left out unless `lineBreak` names the text to report it as.
+ * With that option, column breaks report U+000E so callers cannot silently discard them.
+ */
+declare function contentControlTextOf(control: OoxmlNode, lineBreak?: string): string;
+/**
+ * Resolve the lock a position inherits from the controls enclosing it.
+ *
+ * CONSERVATIVE, because a template that says a field cannot be edited and sits inside a
+ * section that says it cannot be removed means both. Each half of `ST_Lock` is taken
+ * independently and the strongest wins, so an unlocked control inside a `contentLocked`
+ * one is still content-locked — a nested control cannot grant a permission its parent
+ * withheld, which is the only reading under which a lock is a lock.
+ */
+declare function resolveContentControlLock(chain: readonly ContentControlLock[]): ContentControlLock;
+/** Whether a resolved lock forbids editing the content it covers. */
+declare function lockForbidsEdit(lock: ContentControlLock): boolean;
+/** Whether a resolved lock forbids removing the control itself. */
+declare function lockForbidsRemoval(lock: ContentControlLock): boolean;
+/**
+ * `CT_SdtPr`'s declared child order (§17.5.2.38), followed by the type choice.
+ *
+ * Serialization re-emits children in tree order, so the ONLY way a write keeps the
+ * sequence valid is to place the child it authors at its schema position — which is what
+ * {@link orderedContentControlProperties} does.
+ */
+declare const CONTENT_CONTROL_PROPERTY_ORDER: readonly string[];
+/**
+ * Rebuild a `w:sdtPr`'s children in schema order.
+ *
+ * Modelled children sort to their declared position and the type element follows them,
+ * as the sequence requires. Everything else — a `w15:repeatingSection`, a vendor
+ * extension, the `w14:checkbox` that is not part of the ECMA-376 choice — keeps the order
+ * it was authored in and follows the modelled block, so a write that touches one property
+ * neither drops nor reorders anything it does not name.
+ */
+declare function orderedContentControlProperties(children: readonly OoxmlNode[]): readonly OoxmlNode[];
+/**
+ * The next `w:id` to write.
+ *
+ * Solo: one past the document's own maximum. Never a clock, a timestamp, a random source
+ * or a hash: those collide with ids already in the file and produce values Word rejects.
+ * Null when the document already reaches the signed 32-bit bound, so the caller refuses
+ * rather than wrapping into a negative id. Hostile or out-of-range existing values are
+ * ignored for seeding rather than counted past.
+ *
+ * When a collaboration actor is bound (explicit argument or the open store transaction),
+ * the next id is the next unused value in that actor's stripe. Two peers inserting a
+ * generic content control — including a custom node authored as `w:sdt` — from the same
+ * snapshot then cannot share a `w:id`.
+ */
+declare function allocateContentControlId(root: OoxmlNode, actorId?: string): number | null;
+
+/** The value a control accepts, by what kind of control it is. */
+type ContentControlValueInput = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'listItem';
+    readonly value: string;
+} | {
+    readonly kind: 'checkbox';
+    readonly checked: boolean;
+}
+/** A calendar date, `YYYY-MM-DD` or a full ISO-8601 instant. */
+ | {
+    readonly kind: 'date';
+    readonly iso: string;
+};
+/** The control types an insertion may author. Picture and repeating section are deferred. */
+declare const INSERTABLE_CONTENT_CONTROL_TYPES: readonly ["richText", "plainText", "dropDownList", "comboBox", "date"];
+/**
+ * The OOXML spellings the store writes.
+ *
+ * NOT the contract's `InsertableContentControlType`, which is the same set of kinds in the
+ * READ vocabulary (`dropdown`) plus this lane's spelling of it (`dropDownList`). The editor
+ * maps between the two; the names differ so a reader can tell which vocabulary a value is in.
+ */
+type InsertableContentControlKind = (typeof INSERTABLE_CONTENT_CONTROL_TYPES)[number];
+
+/** A canonical review decision. Keys are valid only in the open document. @public */
+interface RevisionBatchEntry {
+    readonly key: string;
+    readonly author: string;
+    readonly partName: string;
+    readonly revisionKind: ReviewRevisionItem['revisionKind'];
+}
+/** Why a requested decision remains pending. @public */
+type RevisionBatchSkipReason = 'unsupported-revision' | 'incomplete-group' | 'retained-structure' | 'unknown-revision';
+/** Outcome of one selected-set decision. Counts refer to review decisions, not XML markers. @public */
+interface RevisionBatchResult {
+    readonly resolved: readonly RevisionBatchEntry[];
+    readonly skipped: readonly {
+        readonly key: string;
+        readonly reason: RevisionBatchSkipReason;
+        readonly revision?: RevisionBatchEntry;
+    }[];
+    /** All pending decisions in the addressed scope, including excluded and unsupported changes. */
+    readonly remaining: number;
+}
+/** @internal Pure preflight; callers commit its operations through their normal write guards. */
+declare function planRevisionBatch(part: OoxmlPart, action: 'accept' | 'reject', keys?: readonly string[], scopeRoot?: OoxmlNode): {
+    ops: readonly TreeDocOp[];
+    result: RevisionBatchResult;
+};
+
+/** Why a requested change keeps its attribution. @public */
+type RevisionAuthorSkipReason = 'unknown-revision' | 'unsupported-revision';
+/**
+ * One reattributed change. `key` and `author` describe the change after the update, because
+ * review keys include the author. @public
+ */
+interface RevisionAuthorEntry extends RevisionBatchEntry {
+    /**
+     * The key the caller selected the change by. It differs from `key` when the attribution
+     * changed, because review keys include the author and date.
+     */
+    readonly previousKey: string;
+    /** The author the change had before the update. */
+    readonly previousAuthor: string;
+}
+/** Outcome of one attribution change. Counts refer to review decisions, not XML markers. @public */
+interface RevisionAuthorResult {
+    /** Changes that now carry the requested attribution, in selection order. */
+    readonly updated: readonly RevisionAuthorEntry[];
+    /** Requested changes that kept their attribution. */
+    readonly skipped: readonly {
+        readonly key: string;
+        readonly reason: RevisionAuthorSkipReason;
+        readonly revision?: RevisionBatchEntry;
+    }[];
+}
+/** A planned attribution change: its ops, and how to name the result once they commit. */
+interface RevisionAuthorPlan {
+    readonly ops: readonly TreeDocOp[];
+    /** The outcome before commit. Updated entries still carry their previous keys. */
+    readonly result: RevisionAuthorResult;
+    /** The outcome against the committed part, with each updated change under its new key. */
+    finish(after: OoxmlPart): RevisionAuthorResult;
+}
+/**
+ * Plan an attribution change for selected review keys. Omitted keys select every change.
+ * `authors` keeps only the changes those authors made.
+ * Callers validate `revision` with `invalidRevisionAuthorInput` first.
+ * @internal
+ */
+declare function planRevisionAuthorChange(part: OoxmlPart, revision: RevisionAttributionInput, keys?: readonly string[], scopeRoot?: OoxmlNode, authors?: readonly string[]): RevisionAuthorPlan;
+
+/** Allowlisted OOXML table border line styles — store/layout authority. */
+declare const TABLE_BORDER_STYLES: readonly ['single', 'dashed', 'dotted', 'double', 'triple', 'thick'];
+/**
+ * One of the border line styles this engine draws.
+ *
+ * An ALLOWLIST, not the full `ST_Border` enumeration: a file may name any of the seventy-odd
+ * OOXML border styles, and anything outside this set falls back rather than being passed through
+ * to paint.
+ */
+type TableBorderStyle = (typeof TABLE_BORDER_STYLES)[number];
+
+/**
+ * Shared types for the `@docx-editor.dev/core` contract. Type-only, zero runtime.
+ *
+ * `@docx-editor.dev/core/contracts/types` re-exports this module verbatim, through
+ * `types-barrel.ts`. There is no `@docx-editor.dev/core/types` subpath.
+ */
+/** Which paragraph-level reads the selection disagrees about. @public */
+interface ParagraphDisagreements {
+    readonly alignment: boolean;
+    /** The selection mixes left-to-right and right-to-left paragraphs. */
+    readonly direction: boolean;
+    readonly spaceBeforePt: boolean;
+    readonly spaceAfterPt: boolean;
+    readonly lineSpacing: boolean;
+    readonly tabStops: boolean;
+}
+/**
+ * The five paragraph flags a Paragraph dialog shows as checkboxes.
+ *
+ * `contextualSpacing` is Word's "Don't add space between paragraphs of the same style";
+ * the rest are its Pagination block. `null` means the selection disagrees.
+ *
+ * @public
+ */
+interface ParagraphFlags {
+    readonly contextualSpacing: boolean | null;
+    readonly keepNext: boolean | null;
+    readonly keepLines: boolean | null;
+    readonly widowControl: boolean | null;
+    readonly pageBreakBefore: boolean | null;
+}
+/**
+ * Every field of the Paragraph dialog, as `setParagraphFormat` takes it.
+ *
+ * An omitted field is left as authored. `null` REMOVES a setting so the style supplies it
+ * again — not the same as a zero, which blocks the cascade.
+ *
+ * @public
+ */
+interface ParagraphFormatCommand {
+    alignment?: 'left' | 'center' | 'right' | 'justify';
+    /**
+     * Paragraph base direction (`w:bidi`), Word's Direction setting. `ltr` writes an explicit
+     * off value where a style would otherwise make the paragraph right-to-left.
+     */
+    direction?: 'ltr' | 'rtl';
+    spaceBeforePt?: number | null;
+    spaceAfterPt?: number | null;
+    lineSpacing?: {
+        rule: 'multiple' | 'exact' | 'atLeast';
+        value: number;
+    } | null;
+    indentLeftTwips?: number | null;
+    indentRightTwips?: number | null;
+    /** ONE signed first-line offset: negative is a hanging indent. */
+    indentFirstLineTwips?: number | null;
+    contextualSpacing?: boolean;
+    keepNext?: boolean;
+    keepLines?: boolean;
+    widowControl?: boolean;
+    pageBreakBefore?: boolean;
+    /**
+     * Replace the paragraph's custom tab stops. An empty list CLEARS them, which is what
+     * "Clear All" does; omit the field to leave them as authored.
+     */
+    tabStops?: readonly ParagraphTabStop[];
+}
+/** One custom tab stop, as a command states it. @public */
+interface ParagraphTabStop {
+    readonly positionTwips: number;
+    readonly alignment: 'left' | 'center' | 'right' | 'decimal' | 'bar';
+    readonly leader?: 'none' | 'dot' | 'hyphen' | 'underscore' | 'heavy' | 'middleDot';
+}
+/** Ownership token for one retained selection highlight. @public */
+type SelectionPin = symbol;
+/**
+ * The LLM- and JSON-facing address for a piece of a document.
+ *
+ * `paraId` is the 8-hex `w14:paraId`, matched case-insensitively. `search` is a
+ * phrase that must match EXACTLY ONCE inside that paragraph; ambiguous or
+ * missing matches fail with `'ambiguous'` / `'notFound'` rather than falling
+ * back to first-match.
+ *
+ * Offset-based addressing was tried and abandoned: an agent cannot compute a
+ * character offset it has not seen, and offsets do not survive concurrent
+ * edits. Do not reintroduce `{ blockId, offset }`.
+ */
+interface DocAnchor {
+    paraId: string;
+    search?: string;
+    /** Opt-in disambiguation. Omit to require uniqueness. */
+    occurrence?: number;
+}
+/** Structural addressing for content the paraId map cannot reach. */
+interface DocLocation {
+    container: ContainerRef;
+    /** Block indices, descending into tables and content controls. */
+    path: number[];
+    offset?: number;
+}
+/**
+ * Which STORY a location belongs to.
+ *
+ * The body is one container; every header, footer and note is another. A path alone is
+ * ambiguous without it, because block index 0 exists in every story a document has.
+ */
+type ContainerRef = {
+    part: 'body';
+} | {
+    part: 'header' | 'footer';
+    rId: string;
+} | {
+    part: 'footnote' | 'endnote';
+    noteId: number;
+};
+/**
+ * Anything an operation can be pointed at: a paragraph-relative {@link DocAnchor}, a structural
+ * {@link DocLocation}, or a {@link DocRange} spanning two of them.
+ */
+type DocTarget = DocAnchor | DocLocation | DocRange;
+/** A span between two positions. The endpoints may be addressed either way, independently. */
+interface DocRange {
+    from: DocAnchor | DocLocation;
+    to: DocAnchor | DocLocation;
+}
+/**
+ * Every write returns this rather than `boolean`.
+ *
+ * A bare boolean cannot distinguish "no-op" from "target not found" from
+ * "content control is locked", and the editor layer already throws eight
+ * distinct ContentControl error classes that a boolean would flatten.
+ */
+type ExecResult = {
+    ok: true;
+    /** Whether the DOCUMENT changed; view-only calls (pane, activation, mode) always report `false`. */
+    changed: boolean;
+    revisions?: RevisionBatchResult;
+    /** Present on `setReviewChangesAuthor`: the changes it updated and the ones it skipped. */
+    revisionAuthors?: RevisionAuthorResult;
+    history?: HistoryGroupOutcome;
+} | {
+    ok: false;
+    code: ExecErrorCode;
+    reason: string;
+    target?: DocTarget;
+    revisions?: RevisionBatchResult;
+    revisionAuthors?: RevisionAuthorResult;
+};
+/**
+ * Why a write was refused, as a value to branch on.
+ *
+ * Deliberately finer-grained than a boolean: "no-op", "target not found" and "content control is
+ * locked" are different outcomes, and a caller retrying the first should not retry the third.
+ */
+type ExecErrorCode = 'notFound' | 'ambiguous' | 'locked' | 'bound' | 'typeMismatch' | 'kindMismatch' | 'outOfBounds' | 'unsupported' | 'invalidArgs';
+/**
+ * A parsed .docx.
+ *
+ * NOT JSON-round-trippable: it holds `Map`s and `Date`s, plus an internal
+ * side-table of verbatim XML used for lossless round-tripping. Use `toJSON` /
+ * `fromJSON` before sending it over JSON-RPC or handing it to a model.
+ */
+interface DocxDocument {
+    readonly body: DocumentBody;
+    readonly styles: StyleDefinitions;
+    readonly theme?: Theme;
+    readonly comments: readonly DocComment[];
+    readonly revisions: readonly Revision[];
+}
+/** The main story: its blocks in reading order, plus the sections derived from them. */
+interface DocumentBody {
+    readonly content: readonly Block[];
+    /**
+     * Derived, not stored: recomputed on read from section-break markers and
+     * section inheritance. Never treat it as a spreadable field.
+     */
+    readonly sections: readonly Section[];
+}
+/** The JSON-safe projection of a document. */
+interface DocxDocumentJSON {
+    readonly [key: string]: unknown;
+}
+/** One section: the page it lays out on, and the header/footer stories it declares. */
+interface Section {
+    readonly properties: SectionProperties;
+    readonly headers: HeaderFooterSet;
+    readonly footers: HeaderFooterSet;
+}
+/**
+ * A section's three header (or footer) variants, each a relationship id.
+ *
+ * All optional: a variant a section does not declare inherits the previous section's, and one
+ * absent everywhere means the document simply has none.
+ */
+interface HeaderFooterSet {
+    readonly default?: string;
+    readonly first?: string;
+    readonly even?: string;
+}
+/** Anything that can sit at block level in a story. Discriminate on `kind`. */
+type Block = Paragraph | Table | ContentControl;
+/** One paragraph: its runs, the style it names, and its list membership. */
+interface Paragraph {
+    readonly kind: 'paragraph';
+    /** `w14:paraId`. The stable handle `DocAnchor` addresses. */
+    readonly paraId?: string;
+    readonly runs: readonly Run[];
+    readonly styleId?: string;
+    readonly numbering?: NumberingRef;
+}
+/** A stretch of text sharing one set of character properties. */
+interface Run {
+    readonly text: string;
+    readonly formatting?: RunFormatting;
+    /** Set when the run carries a tracked change. Unique only within its part. */
+    readonly revisionId?: number;
+}
+/**
+ * Character formatting, and — at selection level — the paragraph properties a toolbar reads
+ * alongside it.
+ *
+ * One type serves both roles so a toolbar reads alignment, style and script state from the same
+ * object as bold and italic. On a {@link Run} the selection-level fields stay absent: a run has
+ * no alignment or paragraph style of its own.
+ */
+interface RunFormatting {
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+    readonly strike?: boolean;
+    readonly color?: ColorValue;
+    readonly highlight?: string;
+    readonly fontFamily?: string;
+    readonly fontSizePt?: number;
+    readonly superscript?: boolean;
+    readonly subscript?: boolean;
+    /**
+     * Paragraph alignment at the selection, as a PHYSICAL edge. `both` is OOXML's spelling of
+     * justify. A right-to-left paragraph with no `w:jc` reads `right`.
+     */
+    readonly alignment?: 'left' | 'center' | 'right' | 'both';
+    /**
+     * Paragraph base direction at the selection (`w:bidi` through the style cascade). Absent
+     * when the selection's paragraphs disagree; `disagrees.direction` then says so.
+     */
+    readonly direction?: 'ltr' | 'rtl';
+    /** Paragraph style id (`w:pStyle`) at the selection. */
+    readonly styleId?: string;
+    /**
+     * Line spacing at the selection, in the unit its rule implies — LINES for `multiple`,
+     * points for `exact` and `atLeast`. The same vocabulary `setLineSpacing` takes, so a
+     * control can show what it reads and send back what it shows. Absent when the
+     * selection's paragraphs disagree or state no line spacing.
+     */
+    readonly lineSpacing?: {
+        readonly rule: 'multiple' | 'exact' | 'atLeast';
+        readonly value: number;
+    };
+    /**
+     * Space above and below the paragraph at the selection, in points.
+     *
+     * The measurement the cascade STATES — `w:docDefaults`, the style chain and direct
+     * formatting resolved together — not the gap the page finally draws. The two differ for a
+     * paragraph carrying `w:beforeAutospacing`, where Word substitutes its own value and
+     * ignores the measurement, and again where two paragraphs collapse their adjacent spacing.
+     * Absent when the selection's paragraphs disagree or no level states it.
+     */
+    readonly spaceBeforePt?: number;
+    readonly spaceAfterPt?: number;
+    /**
+     * The paragraph flags the Paragraph dialog shows as checkboxes.
+     *
+     * Each is `true`, `false`, or `null` when the selection's paragraphs disagree — a
+     * checkbox needs all three. Read through the cascade, so a flag a STYLE sets reads as on,
+     * which is what the box has to show over a paragraph the page is visibly keeping with the
+     * next. Absent on a `Run`, like every other selection-level field here.
+     */
+    readonly paragraphFlags?: ParagraphFlags;
+    /**
+     * Which paragraph-level fields above are absent because the selection DISAGREES, as
+     * opposed to because nothing states them.
+     *
+     * A `null`/absent value alone cannot tell those apart, and both readings have shipped as
+     * bugs: a disagreement rendered as a concrete value is uncorrectable, because the value
+     * that would fix it is the one already on screen; an absent value rendered as "mixed"
+     * tells a single paragraph it disagrees with itself.
+     */
+    readonly disagrees?: ParagraphDisagreements;
+    /**
+     * The paragraph's custom tab stops at the selection, cascade included. Absent when the
+     * selection disagrees or the paragraphs have none.
+     */
+    readonly tabStops?: readonly ParagraphTabStop[];
+    /**
+     * The EFFECTIVE paragraph indent at the selection — cascade and numbering merge
+     * included, so a numbered item that authors no `w:ind` reports the indent its list
+     * definition gives it. Absent when nothing is loaded, or when the selection is inside a
+     * table (see {@link IndentFormatting}).
+     */
+    readonly indent?: IndentFormatting;
+}
+/**
+ * Indent at the selection, in twips.
+ *
+ * Unlike every other field here, this does NOT go absent when the selection's paragraphs
+ * disagree. A ruler has to draw its handles somewhere, and Word draws them at the FIRST
+ * selected paragraph's values — Select All is the commonest indent gesture, and hiding the
+ * handles for it would be worse than showing one paragraph's truth. The values are
+ * therefore always the first touched paragraph's, and {@link mixed} records per field
+ * whether the rest agree.
+ *
+ * `firstLine` is ONE SIGNED offset: negative is a hanging indent. OOXML spells it as two
+ * mutually exclusive attributes and this collapses them hanging-wins (§17.3.1.12), which
+ * is the model Word itself keeps.
+ *
+ * Absent inside a table. The value would be correct there, but it is measured from the
+ * cell's content edge while a ruler is drawn against the page's margin, and the ruler does
+ * not know the cell.
+ */
+interface IndentFormatting {
+    /**
+     * Leading indent (`w:left`), signed: the left one, or the right one in a right-to-left
+     * paragraph. Negative pulls text into the margin, as Word allows.
+     */
+    readonly left: number;
+    /** Trailing indent (`w:right`), signed: the right one, or the left one right to left. */
+    readonly right: number;
+    /** First-line offset from {@link left}, signed. Negative is a hanging indent. */
+    readonly firstLine: number;
+    /** Per field, whether the selection's paragraphs disagree about it. */
+    readonly mixed: {
+        readonly left: boolean;
+        readonly right: boolean;
+        readonly firstLine: boolean;
+    };
+    /**
+     * The first selected paragraph reads right to left, so `left` and the first line sit on
+     * the right margin. Absent for a left-to-right paragraph.
+     */
+    readonly rtl?: true;
+}
+/** A table: its rows, and the table style they resolve through. */
+interface Table {
+    readonly kind: 'table';
+    readonly rows: readonly TableRow[];
+    readonly styleId?: string;
+}
+/** One table row. Cell count may vary between rows: `colSpan` and vertical merges reshape it. */
+interface TableRow {
+    readonly cells: readonly TableCell[];
+}
+/**
+ * One cell. Its `content` is ordinary blocks, so a cell may hold paragraphs, nested tables and
+ * content controls alike.
+ */
+interface TableCell {
+    readonly content: readonly Block[];
+    /** Vertical merge span. Absent means 1. */
+    readonly rowSpan?: number;
+    /** `w:gridSpan`. Absent means 1. */
+    readonly colSpan?: number;
+}
+/** Structured document tag (`w:sdt`). */
+interface ContentControl {
+    readonly kind: 'contentControl';
+    readonly id: string;
+    readonly tag?: string;
+    readonly alias?: string;
+    readonly controlType: ContentControlType;
+    readonly locked?: boolean;
+    readonly content: readonly Block[];
+}
+/** Which kind of control a `w:sdt` is, and therefore what a value written into it must be. */
+type ContentControlType = 'richText' | 'plainText' | 'checkbox' | 'dropdown' | 'comboBox' | 'date' | 'picture' | 'buildingBlockGallery' | 'repeatingSection';
+/**
+ * The control kinds an insertion can author.
+ *
+ * A NARROWING of {@link ContentControlType}, not a separate vocabulary: a kind read off an
+ * existing control can be handed straight back to `insertContentControl`. Three kinds are
+ * absent because an insertion would have to invent what they carry — a checkbox needs its two
+ * declared glyph states, a picture needs an image part, a building block gallery needs a
+ * glossary to list, and a repeating section is a container whose items have their own verbs. Reading still answers the wider type; a document may hold
+ * kinds this cannot create.
+ *
+ * `dropDownList` is the same kind as `dropdown`, spelt as OOXML spells it. Both are accepted,
+ * so a type read off a control can be handed back without translating it — and the OOXML
+ * spelling is the one the automation protocol takes, so a caller who uses both surfaces can
+ * write that one everywhere.
+ */
+type InsertableContentControlType = Extract<ContentControlType, 'richText' | 'plainText' | 'dropdown' | 'comboBox' | 'date'> | 'dropDownList';
+/**
+ * Narrows a content-control query. Fields combine with AND; an empty filter matches every
+ * control.
+ */
+interface ContentControlFilter {
+    readonly tag?: string;
+    readonly alias?: string;
+    readonly controlType?: ContentControlType;
+}
+/**
+ * A position in one story: a paragraph and a UTF-16 offset inside it.
+ *
+ * The same offset space the ops and the caret use, so an anchor read here can be handed
+ * straight back to a selection without re-deriving anything.
+ */
+interface DocAnchorRange {
+    /** Canonical part name of the story the range lives in, e.g. `/word/document.xml`. */
+    readonly part: string;
+    readonly startParagraphId: string;
+    readonly startOffset: number;
+    /** May sit in a later paragraph: the range markers are independent elements. */
+    readonly endParagraphId: string;
+    readonly endOffset: number;
+}
+/**
+ * One comment or reply, as `comments.xml` records it.
+ *
+ * A reply is a comment with a `parentId`; OOXML gives replies no separate element, so the thread
+ * is reconstructed from that link rather than from nesting.
+ */
+interface DocComment {
+    readonly id: string;
+    readonly author: string;
+    /**
+     * OPTIONAL, because `CT_Comment` makes `@w:date` optional and files omit it. A comment
+     * with no date is a comment, not a defect, and fabricating one is a content change.
+     */
+    readonly date?: string;
+    readonly text: string;
+    readonly parentId?: string;
+    readonly resolved?: boolean;
+    /**
+     * Where the comment is anchored, absent when the file gave it no usable range.
+     *
+     * A comment lives in `comments.xml` and is placed by markers in a STORY, so the story is
+     * part of the address: a comment anchored in a header belongs to a part the body never saw.
+     */
+    readonly anchor?: DocAnchorRange;
+    /**
+     * True when the file gave this comment no usable range — a reference with no markers, or a
+     * start with no end. Reported rather than dropped: a reviewer's remark vanishing silently
+     * is worse than one that says it lost its text.
+     */
+    readonly orphaned?: boolean;
+}
+/**
+ * What kind of decision a revision represents.
+ *
+ * Wider than insert/delete/format, and it has to be. `w:moveFrom`/`w:moveTo` are not a
+ * deletion and an insertion — resolving one half alone duplicates or loses the content;
+ * `w:pPr/w:rPr/w:ins|w:del` decorates no characters at all and merges paragraphs when
+ * resolved; a row or cell revision is structural. A reviewer shown only three kinds is a
+ * reviewer who never learns about the rest.
+ */
+type RevisionType = 'insert' | 'delete'
+/** A deletion and an insertion that are one edit: text typed over a selection. */
+ | 'replace' | 'moveFrom' | 'moveTo'
+/** `w:rPrChange` / `w:pPrChange` — the words are unchanged, their formatting is not. */
+ | 'format'
+/** `w:pPr/w:rPr/w:ins|w:del` — a paragraph split or merge. */
+ | 'paragraphMark'
+/** A row, cell, section or grid revision. */
+ | 'structural';
+/**
+ * One tracked change.
+ *
+ * Addressing needs BOTH `id` and `part`: `@w:id` is unique only within a part, so an id alone
+ * names two revisions in any package that has a header or a comments part.
+ */
+interface Revision {
+    /** Numeric, and unique only WITHIN a part. Pair with `part` to address one. */
+    readonly id: number;
+    readonly type: RevisionType;
+    readonly author: string;
+    /**
+     * OPTIONAL. `CT_TrackChange` requires `@w:id` and `@w:author` and makes `@w:date`
+     * optional, and producers that omit it are ordinary. Requiring it here forced either a
+     * fabricated date — a content change — or dropping the revision from the list.
+     */
+    readonly date?: string;
+    /**
+     * REQUIRED, and a canonical PART NAME rather than a three-value enum.
+     *
+     * `@w:id` is unique only within a part, so an address without one names two revisions in a
+     * package that has both. The enum could not express the parts revisions actually occur in:
+     * `header3.xml`, `footer1.xml`, `comments.xml`, and `styles.xml`, which carries
+     * `w:pPrChange` inside style definitions with ids that collide with `document.xml`.
+     */
+    readonly part: string;
+}
+/** `w:sectPr`: the page a section lays out on. Twips throughout, as the file stores them. */
+interface SectionProperties {
+    readonly pageSize: {
+        widthTwips: number;
+        heightTwips: number;
+    };
+    readonly margins: PageMargins;
+    readonly columns?: {
+        count: number;
+        gapTwips: number;
+    };
+    /** `w:titlePg` — whether the section's first page takes the `first` header/footer variant. */
+    readonly titlePage?: boolean;
+}
+/** Page margins in twips. */
+interface PageMargins {
+    readonly topTwips: number;
+    readonly rightTwips: number;
+    readonly bottomTwips: number;
+    readonly leftTwips: number;
+}
+/**
+ * `styles.xml`, split by the three style families that address separately.
+ *
+ * Keyed by style ID rather than by the name a reader sees, because the ID is what a paragraph or
+ * run actually references.
+ */
+interface StyleDefinitions {
+    readonly paragraph: ReadonlyMap<string, StyleDefinition>;
+    readonly character: ReadonlyMap<string, StyleDefinition>;
+    readonly table: ReadonlyMap<string, StyleDefinition>;
+}
+/** One style: the ID content references, the name a reader sees, and its inheritance link. */
+interface StyleDefinition {
+    readonly id: string;
+    readonly name: string;
+    /** `w:basedOn` — the style this one inherits from. Absent at the root of a chain. */
+    readonly basedOn?: string;
+}
+/** A paragraph's list membership: which `numbering.xml` definition, and at which level. */
+interface NumberingRef {
+    readonly numId: string;
+    /** Zero-based. OOXML numbering has nine levels, 0 through 8. */
+    readonly level: number;
+}
+/**
+ * A colour as the FILE expresses it, not as a resolved RGB string.
+ *
+ * A theme colour stays a theme reference — slot plus tint or shade — so that changing the theme
+ * repaints the document the way Word does. Flattening to hex at read time would freeze the
+ * resolved value and break that link. `auto` is Word's "let the renderer decide", usually black
+ * on white.
+ */
+type ColorValue = {
+    readonly kind: 'hex';
+    readonly value: string;
+} | {
+    readonly kind: 'theme';
+    readonly slot: string;
+    readonly tint?: number;
+    readonly shade?: number;
+} | {
+    readonly kind: 'auto';
+};
+/** `theme1.xml` — what a {@link ColorValue} of kind `theme` resolves against. */
+interface Theme {
+    readonly colorScheme: ThemeColorScheme;
+    readonly fontScheme?: Record<string, string>;
+}
+/** Theme colour slots (`accent1`, `dk1`, `lt2`, …) to hex. */
+type ThemeColorScheme = Readonly<Record<string, string>>;
+/** A watermark, which OOXML expresses as either text or an image — never both meaningfully. */
+interface Watermark {
+    readonly text?: string;
+    readonly imageData?: Uint8Array;
+}
+/** A size in EMUs, the unit DrawingML stores extents in. 914400 EMU = 1 inch. */
+interface Extent {
+    readonly widthEmu: number;
+    readonly heightEmu: number;
+}
+/** A font the document names, and whether its bytes travel inside the package. */
+interface FontDefinition {
+    readonly family: string;
+    readonly embedded: boolean;
+}
+/** An axis-aligned rectangle in points, the unit layout works in throughout. */
+interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** A position in points. */
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** What every subscription returns. Calling it twice is safe. */
+type Unsubscribe = () => void;
+
+/**
+ * A colour as an op carries it: a literal, a theme reference, or automatic.
+ *
+ * Theme references stay references so the document keeps following its theme; flattening one to
+ * hex at write time would freeze the resolved value into the file.
+ */
+type TreeDocColorValue = {
+    readonly kind: 'hex';
+    readonly value: string;
+} | {
+    readonly kind: 'theme';
+    readonly slot: string;
+    readonly resolvedHex: string;
+    readonly tint?: number;
+    readonly shade?: number;
+} | {
+    readonly kind: 'auto';
+    readonly resolvedHex: string;
+};
+/** Which edges a border op addresses — the four sides, the interiors, all, or clear. */
+type TableBorderTarget = 'all' | 'outside' | 'inside' | 'none' | 'top' | 'bottom' | 'left' | 'right';
+/** A {@link TableBorderTarget} that draws something — everything except clear. */
+type TableBorderEdgeTarget = Exclude<TableBorderTarget, 'none'>;
+/** Complete border spec for non-`none` selected-cell border scopes. Size is in eighths of a point. */
+/** A complete border spec: style, width and colour. Ops carry all three, never a partial edit. */
+interface TableBorderSpecInput {
+    readonly style: TableBorderStyle;
+    readonly size: number;
+    readonly color: TreeDocColorValue;
+}
+/**
+ * The accepted RUN property boundary (design D8), as the OOXML element names that carry it.
+ *
+ * An explicit allowlist rather than "any `w:rPr` child": a property outside D8 has no
+ * resolver, no layout behavior and no support claim, so accepting it here would let an
+ * operation assert support the engine does not have. Unknown properties still ROUND-TRIP —
+ * they are generic nodes in the tree — they simply cannot be authored by an op.
+ */
+declare const ACCEPTED_RUN_PROPERTIES: readonly ['rFonts', 'sz', 'szCs', 'color', 'b', 'bCs', 'i', 'iCs', 'u', 'strike', 'dstrike', 'highlight', 'vertAlign', 'position', 'caps', 'smallCaps', 'spacing', 'w', 'kern'];
+/** The accepted PARAGRAPH property boundary (design D8). */
+declare const ACCEPTED_PARAGRAPH_PROPERTIES: readonly ['pStyle', 'jc', 'spacing', 'ind', 'tabs', 'numPr', 'keepNext', 'keepLines', 'widowControl', 'pageBreakBefore', 'contextualSpacing', 'shd', 'bidi'];
+/**
+ * One tab stop an op can author: where it sits, how it aligns, and what fills the gap.
+ *
+ * An alias, not a second declaration. The contract lane already names this shape, and two
+ * public names for one shape is a trap — a caller building a stop for a read and for an op
+ * would otherwise have to name it two things.
+ */
+type TabStopWrite = ParagraphTabStop;
+/**
+ * One authored property: an element name plus its `w:`-namespace attributes.
+ *
+ * Modeled as name+attributes rather than a typed record per property because that is what
+ * the tree holds, so an op maps to nodes without a lossy intermediate vocabulary. Attribute
+ * VALUES are validated as XML text; their meaning is the resolver's business.
+ *
+ * Deliberately structural rather than a typed union: the accepted property lists bound WHICH
+ * properties may be written, so the shape itself does not need to enumerate them.
+ */
+interface OoxmlProperty {
+    readonly localName: string;
+    readonly attributes?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Every mutation the store accepts, as one JSON-safe discriminated union.
+ *
+ * The ONLY write path into a document. Each op addresses nodes by id plus UTF-16 offset, which is
+ * what makes editing a paragraph inside a table cell no different from editing one at the top
+ * level. Declarative and serializable, so the same op crosses a worker or transport boundary
+ * unchanged.
+ */
+type TreeDocOp = SetFieldCodeOp | {
+    /**
+     * Replace one story's complete block structure with fresh plain paragraphs.
+     *
+     * Unlike a span replacement, this removes section-ending paragraphs and content-control
+     * wrappers. A body's final direct `w:sectPr` survives to retain the page setup.
+     */
+    readonly op: 'replaceStoryBlocks';
+    readonly storyRootId: string;
+    readonly paragraphs: readonly string[];
+} | {
+    /**
+     * Insert an SDT-wrapped TOC immediately before a body paragraph.
+     * The initial cached result and any heading bookmarks land in one undo unit.
+     */
+    readonly op: 'insertToc';
+    readonly beforeParagraphId: string;
+    readonly instruction: string;
+    readonly alias: string;
+    readonly entries: readonly {
+        readonly level: number;
+        readonly text: string;
+        readonly headingParagraphId: string;
+        readonly bookmarkName: string;
+        readonly pageNumberText: string;
+    }[];
+    readonly bookmarksToCreate: readonly {
+        readonly paragraphId: string;
+        readonly name: string;
+    }[];
+} | InsertTextOp | DeleteTextOp | {
+    /**
+     * Mark a paragraph's own MARK as inserted or deleted (`w:pPr/w:rPr/w:ins|w:del`,
+     * §17.13.5). The change is to the paragraph break itself, so no character carries it.
+     */
+    readonly op: 'setParagraphMarkRevision';
+    readonly paragraphId: string;
+    readonly kind: 'ins' | 'del';
+    readonly revision: RevisionAttributionInput;
+} | {
+    /**
+     * Propose merging this paragraph into its PREDECESSOR by striking the predecessor's
+     * mark. Addressed by the SECOND paragraph so a multi-paragraph delete marks each
+     * paragraph's own predecessor rather than stamping the group head N times.
+     */
+    readonly op: 'proposeParagraphMerge';
+    readonly paragraphId: string;
+    readonly revision: RevisionAttributionInput;
+} | {
+    /**
+     * Place one piece of comment markup at a model offset.
+     *
+     * Separate from the comment BODY, which lives in another part: this op is the story half
+     * of a comment write, and the two are staged in one package transaction.
+     */
+    readonly op: 'insertCommentMarker';
+    readonly paragraphId: string;
+    readonly offset: number;
+    readonly commentId: string;
+    readonly marker: 'start' | 'end' | 'reference';
+} | {
+    /**
+     * Accept one revision, resolving every site in this part that carries its triple.
+     */
+    readonly op: 'acceptRevision';
+    readonly revision: RevisionAddress;
+    /** When set, only wrappers with this element local name resolve (ins/del/moveFrom/moveTo). */
+    readonly localName?: string;
+    /** Internal exact-site scope used when one Word revision address names separate decisions. */
+    readonly siteNodeIds?: readonly string[];
+} | {
+    readonly op: 'rejectRevision';
+    readonly revision: RevisionAddress;
+    readonly localName?: string;
+    /** Internal exact-site scope used when one Word revision address names separate decisions. */
+    readonly siteNodeIds?: readonly string[];
+} | {
+    /**
+     * Accept every revision in the part, or in one exact note root, in ONE transaction and one
+     * history entry.
+     *
+     * Deliberately not a loop over `acceptRevision`: a reviewer who accepts a document's
+     * changes made one decision, and one undo should restore all of them.
+     */
+    readonly op: 'acceptAllRevisions';
+    /** Exact canonical sites selected by bulk preflight. */
+    readonly siteNodeIds?: readonly string[];
+    /** Internal shared-notes scope. When present, this must be the canonical id of a note root. */
+    readonly scopeRootId?: string;
+} | {
+    /**
+     * Attribute pending revisions to another author, and optionally another date, without
+     * deciding them. `sites` name revision elements and move range starts. Sites sharing a
+     * `renumber` label take one fresh `w:id`, so the change cannot merge with another one.
+     */
+    readonly op: 'setRevisionAttribution';
+    readonly revision: RevisionAttributionInput;
+    readonly sites: readonly {
+        readonly nodeId: string;
+        readonly renumber?: string;
+    }[];
+} | {
+    readonly op: 'rejectAllRevisions';
+    /** Exact canonical sites selected by bulk preflight. */
+    readonly siteNodeIds?: readonly string[];
+    /** Internal shared-notes scope. When present, this must be the canonical id of a note root. */
+    readonly scopeRootId?: string;
+} | {
+    readonly op: 'insertTab';
+    readonly paragraphId: string;
+    readonly offset: number;
+    /** Write this as a TRACKED insertion, on the same terms as `insertText`. */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    readonly op: 'insertHardBreak';
+    readonly paragraphId: string;
+    readonly offset: number;
+    /** Write this as a TRACKED insertion, on the same terms as `insertText`. */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    readonly op: 'insertPageBreak';
+    readonly paragraphId: string;
+    readonly offset: number;
+    /** Write this as a TRACKED insertion, on the same terms as `insertText`. */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    /**
+     * Insert an allowlisted page-number complex field at a UTF-16 offset.
+     *
+     * `PAGE_X_OF_Y` is PAGE + literal " of " + NUMPAGES in one undoable op. Non-page
+     * instructions are refused — never authored through this path.
+     */
+    readonly op: 'insertPageField';
+    readonly paragraphId: string;
+    readonly offset: number;
+    readonly field: 'PAGE' | 'NUMPAGES' | 'SECTIONPAGES' | 'PAGE_X_OF_Y';
+    /**
+     * Write this as a TRACKED insertion, on the same terms as `insertText`.
+     *
+     * The whole field — every `w:fldChar`, the instruction, the `PAGE_X_OF_Y` literal —
+     * goes into ONE `w:ins`, because the field is one proposal: rejecting it must take
+     * the complete atom back, never leave a `begin` standing without its `end`.
+     */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    /**
+     * Move a numbered paragraph to another `w:numPr/w:ilvl`.
+     *
+     * A list item's LEVEL is what selects its format out of `numbering.xml`, so this is
+     * the op behind Increase/Decrease Indent on a list: the marker changes with it. A
+     * paragraph carrying no `w:numPr` is refused rather than silently numbered.
+     */
+    readonly op: 'setListLevel';
+    readonly paragraphId: string;
+    readonly level: number;
+    readonly revision?: RevisionAttributionInput;
+} | {
+    /**
+     * Put a paragraph in a list, or take it out of one.
+     *
+     * `numId` names a `w:num` in `numbering.xml`; null removes `w:numPr` entirely, which
+     * is what turning a bullet off means. Everything else in `w:pPr` survives.
+     */
+    /**
+     * Run properties of the PARAGRAPH MARK (`w:pPr/w:rPr`, ECMA-376 17.3.1.29).
+     *
+     * The mark carries the formatting a paragraph's own pilcrow has, and Word keeps it
+     * in step whenever formatting is applied to a whole paragraph. It is what a list
+     * marker inherits its face from — so without it, sizing a bulleted paragraph leaves
+     * the bullet at the old size.
+     */
+    readonly op: 'setParagraphMarkProperties';
+    readonly paragraphId: string;
+    readonly properties: readonly OoxmlProperty[];
+    /** Record this as a TRACKED format change (`w:pPr/w:rPr/w:rPrChange`, §17.13.5.31). */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    readonly op: 'setListNumbering';
+    readonly paragraphId: string;
+    readonly numId: string | null;
+    readonly level?: number;
+    readonly revision?: RevisionAttributionInput;
+} | {
+    /**
+     * Replace a paragraph's custom tab stops, or clear them with an empty list.
+     *
+     * Its OWN op rather than a `w:tabs` entry in `setParagraphProperties`, because
+     * `OoxmlProperty` is flat and `w:tabs` carries its meaning in `w:tab` children — the
+     * same reason `setListNumbering` exists for `w:numPr`.
+     */
+    readonly op: 'setParagraphTabStops';
+    readonly paragraphId: string;
+    readonly stops: readonly TabStopWrite[];
+    /**
+     * Every stop position IN FORCE when the editor read the paragraph, including the
+     * ones a style supplied.
+     *
+     * Tab stops are read through the cascade and written at the paragraph level, so a
+     * replace alone cannot remove an inherited stop — the user clears a row, the style
+     * puts it straight back, and the command reports success. A position that was in
+     * force and is not in `stops` is suppressed with `w:val="clear"`, which is what the
+     * value exists for (§17.3.1.37). Omit when the caller has no cascade to speak of;
+     * the write is then a plain paragraph-level replace.
+     */
+    readonly inForcePositionsTwips?: readonly number[];
+} | {
+    readonly op: 'splitParagraph';
+    readonly paragraphId: string;
+    readonly offset: number;
+    /**
+     * The `w:pStyle` the MINTED tail takes, instead of the head's own.
+     *
+     * A split otherwise clones the whole `w:pPr`, which is right for every property but
+     * the style when the caller is an Enter at the end of a paragraph: Word gives that
+     * new paragraph the style's `w:next`, so a heading is followed by body text rather
+     * than by a second heading. `null` authors no `w:pStyle` at all, which is what the
+     * document's default style is spelled as. Omit to clone the head's style unchanged.
+     */
+    readonly tailStyleId?: string | null;
+} | {
+    /**
+     * Split one `w:p` at MANY offsets in a single op.
+     *
+     * Equivalent to applying `splitParagraph` at each offset from the last to the first,
+     * but the paragraph's content is cut in one pass and the parent's child sequence is
+     * rebuilt once. A plain-text paste is a paragraph mark per line: as individual ops,
+     * a large paste rebuilt the body — and re-sliced the pasted text — once per line,
+     * which is quadratic in paste size.
+     */
+    readonly op: 'splitParagraphMany';
+    readonly paragraphId: string;
+    /**
+     * Non-decreasing UTF-16 offsets; each produces one paragraph boundary. A repeated
+     * offset produces an empty paragraph between the two boundaries — a blank line.
+     */
+    readonly offsets: readonly number[];
+    /**
+     * Propose the breaks rather than making them, exactly as the single split does.
+     *
+     * Every boundary is a paragraph mark this author is adding, so each paragraph that
+     * PRECEDES one carries `w:rPr/w:ins`. Without it a multi-line paste in suggesting mode
+     * tracked its text and not its breaks, and Reject left the extra paragraphs standing.
+     */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    readonly op: 'joinParagraphs';
+    readonly firstId: string;
+    readonly secondId: string;
+} | {
+    readonly op: 'setRunProperties';
+    readonly paragraphId: string;
+    readonly start: number;
+    readonly end: number;
+    readonly properties: readonly OoxmlProperty[];
+    /**
+     * Record this as a TRACKED format change: each run keeps its new `w:rPr` and gains a
+     * `w:rPrChange` (§17.13.5.30) holding the properties it had, so Reject restores them.
+     */
+    readonly revision?: RevisionAttributionInput;
+    /**
+     * When set, format only these runs (field result ownership). Offset range still
+     * gates the edit and drives edge splits; without this, multi-run field results that
+     * share one atom offset would homogenise under a single property bag.
+     */
+    readonly targetRunIds?: readonly string[];
+} | {
+    readonly op: 'setParagraphProperties';
+    readonly paragraphId: string;
+    readonly properties: readonly OoxmlProperty[];
+    /** Record this as a TRACKED format change (`w:pPrChange`, §17.13.5.29). */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    /**
+     * Set page-setup fields — page size, orientation, margins — on every targeted
+     * `w:sectPr`: all of them (Word's "Apply to: Whole document", the default) or
+     * only the one governing `anchorParagraphId`. A document whose write must reach
+     * the implicit tail section gets a body-level `w:sectPr` minted as the body's
+     * last child. Omitted fields are left exactly as authored per section. Explicit
+     * dimensions are written literally; `orientation` WITHOUT dimensions swaps each
+     * section's own (see `plannedSectionDimensions`), so distinct paper sizes
+     * survive a whole-document flip.
+     */
+    readonly op: 'setSectionProperties';
+    readonly pageWidthTwips?: number;
+    readonly pageHeightTwips?: number;
+    readonly orientation?: 'portrait' | 'landscape';
+    readonly marginTopTwips?: number;
+    readonly marginRightTwips?: number;
+    readonly marginBottomTwips?: number;
+    readonly marginLeftTwips?: number;
+    /**
+     * Word's "Apply to: This section": update only the section GOVERNING this
+     * paragraph — the nearest mid-body `w:sectPr` at or after it, else the body-level
+     * one. Absent means every section.
+     */
+    readonly anchorParagraphId?: string;
+} | {
+    /**
+     * End a section AT this paragraph: mint a `w:pPr/w:sectPr` cloning the governing
+     * section's effective page setup, so the blocks up to and including this paragraph
+     * become their own section. The paragraph must not already carry one.
+     */
+    readonly op: 'setSectionMark';
+    readonly paragraphId: string;
+    /**
+     * Where the section that STARTS after this mark begins — Word's Breaks menu.
+     *
+     * `w:type` states how a section starts relative to the previous one (§17.6.22), so it
+     * is written on the section FOLLOWING the mark, never on the minted one, which keeps
+     * the cloned type because it starts where the section it was cut from did. `'nextPage'`
+     * clears `w:type` (absent IS nextPage), so a next-page break inside a continuous
+     * section really starts a page. Omitted leaves the following section untouched.
+     */
+    readonly breakType?: 'nextPage' | 'continuous';
+} | {
+    /**
+     * Wrap `[start, end)` of a paragraph in a `w:hyperlink`.
+     *
+     * The RANGE is the link — text and formatting inside it are untouched, and runs that
+     * straddle either edge are divided so the link covers exactly the characters asked
+     * for. Exactly one of `relationshipId` (an external target, already minted on the
+     * package) or `anchor` (a bookmark in this document) names where it goes.
+     *
+     * A collapsed range is refused: a link with no text is markup with nothing to click,
+     * and the caller that wants "insert a link with display text" inserts the text first.
+     */
+    readonly op: 'insertHyperlink';
+    readonly paragraphId: string;
+    readonly start: number;
+    readonly end: number;
+    readonly relationshipId?: string;
+    readonly anchor?: string;
+    readonly tooltip?: string;
+    /**
+     * Character style to mark the linked runs with (`w:rStyle`), normally `Hyperlink`.
+     *
+     * Written HERE rather than through `setRunProperties` because `w:rStyle` is preserved,
+     * not accepted: it is not in the set a property write replaces, and putting it there
+     * would make a later bold toggle delete it. Marking the text is part of making it a
+     * link — Word does both in one operation — so the op that wraps it also styles it.
+     * Omitted for a document that declares no such style.
+     */
+    readonly styleId?: string;
+} | {
+    /**
+     * Re-aim an existing link. `relationshipId` moves it to another external target,
+     * `anchor` to a bookmark; supplying one CLEARS the other, so a link never ends up
+     * carrying both and resolving by the wrong one.
+     */
+    readonly op: 'setHyperlinkTarget';
+    readonly linkId: string;
+    /** Optional exact paragraph offsets for an ordinary text subrange of this link. */
+    readonly range?: {
+        readonly start: number;
+        readonly end: number;
+    };
+    readonly relationshipId?: string;
+    readonly anchor?: string;
+    readonly tooltip?: string;
+} | {
+    /**
+     * Unlink: splice the `w:hyperlink`'s children into the paragraph in its place.
+     *
+     * The runs keep their identity, their formatting and their order, and any bookmark
+     * markers inside the link stay exactly where they were. Only the link element goes,
+     * which is what Word's Remove Hyperlink does — the text is not the link's, it was
+     * only wrapped by it.
+     */
+    readonly op: 'removeHyperlink';
+    readonly linkId: string;
+    /** Optional exact paragraph offsets for an ordinary text subrange of this link. */
+    readonly range?: {
+        readonly start: number;
+        readonly end: number;
+    };
+} | {
+    /**
+     * Replace one preserved `m:oMath` atom from bounded linear-math input.
+     *
+     * The complete equation changes as one unit. Internal OMML text never enters the
+     * paragraph offset space, so callers cannot leave a partially edited math tree.
+     */
+    readonly op: 'setMathEquation';
+    readonly equationId: string;
+    readonly linear: string;
+} | {
+    /** Remove one complete `m:oMath` atom. */
+    readonly op: 'removeMathEquation';
+    readonly equationId: string;
+} | {
+    /**
+     * Insert a NEW run-level content control at a text offset: `w:sdt` with a
+     * `w:sdtPr` carrying the given tag (and alias/lock) and a `w:sdtContent`
+     * holding one run of `text`.
+     *
+     * The write half of the custom-node contract (pro-review-and-custom-nodes):
+     * a node's identity lives in `w:tag`, `sdtLocked` keeps Word users from
+     * unwrapping the anchor, and the literal run text is what Word (and the
+     * free tier) render. The TAG IS ATTACKER-ADJACENT ON READ but authored
+     * here; it is written as an ordinary attribute value, so the serializer's
+     * escaping covers it like every other attribute.
+     */
+    readonly op: 'insertInlineContentControl';
+    readonly paragraphId: string;
+    readonly offset: number;
+    readonly tag: string;
+    readonly text: string;
+    readonly alias?: string;
+    /** `w:lock` value; omitted writes no lock. */
+    readonly lock?: 'sdtLocked' | 'sdtContentLocked' | 'contentLocked';
+    /**
+     * `w:dataBinding` — the customXml data part node this control mirrors.
+     *
+     * The payload half of the custom-node contract: `w:tag` caps at 64
+     * characters, so anything larger lives in a data part and the control
+     * points at it. All three attributes travel together because Word needs
+     * all three — the store's `ds:itemID`, the XPath to the node's label, and
+     * the prefix declaration that XPath's steps resolve through.
+     *
+     * A control that carries one is READ-ONLY in Word (verified against
+     * `sdt-custom-node-databinding-word-roundtrip.docx`), and this engine
+     * refuses content edits inside it for the same reason — see
+     * `bindingRefusal`. That is what keeps the store and the page from
+     * drifting: there is no edit that could move one without the other.
+     *
+     * Nothing here is resolved or fetched. The op writes the three strings and
+     * the store lane owns the part they name.
+     */
+    readonly dataBinding?: {
+        readonly prefixMappings: string;
+        readonly xpath: string;
+        readonly storeItemId: string;
+    };
+} | {
+    /** Repeating-section item insert — unsupported at this layer (out of scope). */
+    readonly op: 'addRepeatingSectionItem';
+    readonly controlId: string;
+    readonly index?: number;
+} | {
+    /** Repeating-section item remove — unsupported at this layer (out of scope). */
+    readonly op: 'removeRepeatingSectionItem';
+    readonly controlId: string;
+    readonly index: number;
+} | {
+    /**
+     * Remove a typed block and everything under it.
+     *
+     * Validation restricts this structural operation to `w:p`, `w:tbl`, and `w:tr`, and
+     * refuses removals that would violate required-container or section-mark invariants.
+     */
+    readonly op: 'deleteBlock';
+    readonly blockId: string;
+} | {
+    /**
+     * Insert a fresh empty table immediately before a block-level paragraph.
+     *
+     * Before, never after, so the anchor paragraph stays as the block that follows the
+     * table: a `w:tbl` is not a valid final child of a story container, and two tables
+     * that end up adjacent merge into one when the file is reopened. When the anchor's
+     * previous sibling is already a table, a separating empty paragraph is authored with
+     * it, which is what Word does for the same reason.
+     */
+    readonly op: 'insertTable';
+    readonly beforeParagraphId: string;
+    readonly rows: number;
+    readonly cols: number;
+    /** Width of every grid column, in twips. The caller divides the content width. */
+    readonly columnWidthTwips: number;
+    /** Propose the complete table through native row and cell insertion revisions. */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    /** Insert a fresh row above or below a canonical table row. */
+    readonly op: 'insertTableRow';
+    readonly tableId: string;
+    readonly rowId: string;
+    readonly where: 'above' | 'below';
+    /** When present, author the row as a Word tracked insertion. */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    /** Delete one canonical table row; refuses the final row. */
+    readonly op: 'deleteTableRow';
+    readonly tableId: string;
+    readonly rowId: string;
+    /** Optional anchor cell for column-aware caret recovery after deletion. */
+    readonly referenceCellId?: string;
+    /** When present, retain the row and author a Word tracked deletion. */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    /** Insert one grid column left or right of a canonical `w:gridCol`. */
+    readonly op: 'insertTableColumn';
+    readonly tableId: string;
+    readonly where: 'left' | 'right';
+    readonly gridColumnId: string;
+} | {
+    /**
+     * Insert one grid column beside a first-row reference cell when `w:tblGrid` is absent.
+     * Synthesizes a canonical grid before mutation.
+     */
+    readonly op: 'insertTableColumn';
+    readonly tableId: string;
+    readonly where: 'left' | 'right';
+    readonly referenceCellId: string;
+} | {
+    /** Delete one canonical grid column; refuses the final column. */
+    readonly op: 'deleteTableColumn';
+    readonly tableId: string;
+    readonly gridColumnId: string;
+} | {
+    /**
+     * Resize one internal divider between two adjacent canonical grid columns.
+     * Preserves the pair total and sets fixed table layout.
+     */
+    readonly op: 'setTableColumnWidths';
+    readonly tableId: string;
+    readonly leftGridColumnId: string;
+    readonly rightGridColumnId: string;
+    readonly leftWidthTwips: number;
+    readonly rightWidthTwips: number;
+} | {
+    /**
+     * Resize the outer-right edge: last grid column, matching cells, and `w:tblW` total.
+     */
+    readonly op: 'setTableRightEdgeWidth';
+    readonly tableId: string;
+    readonly gridColumnId: string;
+    readonly columnWidthTwips: number;
+    readonly tableWidthTwips: number;
+} | {
+    /** Atomic semantic table authoring. Newly created nodes never need caller-supplied IDs. */
+    readonly op: 'authorTable';
+    /** Native row revisions. Other structural mutations refuse this option. */
+    readonly revision?: RevisionAttributionInput;
+    readonly action: {
+        readonly kind: 'existing';
+        readonly tableId: string;
+        readonly mutation: AutomationTableMutation;
+    } | {
+        readonly kind: 'insert';
+        readonly paragraphId: string;
+        readonly offset: number;
+        readonly rowCount: number;
+        readonly columnCount: number;
+        readonly values?: readonly (readonly string[])[];
+    };
+} | {
+    /** Lossless direct table properties; widths are one value per rectangular grid column. */
+    readonly op: 'setTableProperties';
+    readonly tableId: string;
+    readonly styleId?: string;
+    readonly headerRowCount?: number;
+    readonly columnWidthsTwips?: readonly number[];
+} | {
+    /** Set one authored table row to an exact height in twips. */
+    readonly op: 'setTableRowHeight';
+    readonly tableId: string;
+    readonly rowId: string;
+    readonly heightTwips: number;
+} | {
+    /** Clear the active edge target on a bounded rectangular cell selection. */
+    readonly op: 'setTableCellBorders';
+    readonly tableId: string;
+    readonly cellIds: readonly string[];
+    readonly scope: 'none';
+    readonly target: TableBorderEdgeTarget;
+} | {
+    /** Apply a complete border spec to the requested edge target. */
+    readonly op: 'setTableCellBorders';
+    readonly tableId: string;
+    readonly cellIds: readonly string[];
+    readonly scope: TableBorderEdgeTarget;
+    readonly spec: TableBorderSpecInput;
+} | {
+    /** Write or remove direct selected-cell shading (`w:tcPr/w:shd`). */
+    readonly op: 'setTableCellFill';
+    readonly tableId: string;
+    readonly cellIds: readonly string[];
+    readonly color: TreeDocColorValue | null;
+} | {
+    /** Set direct selected-cell vertical alignment (`w:tcPr/w:vAlign`). */
+    readonly op: 'setTableCellVerticalAlignment';
+    readonly tableId: string;
+    readonly cellIds: readonly string[];
+    readonly alignment: 'top' | 'center' | 'bottom';
+} | {
+    /** Allocate an empty header/footer part and declare it on a section. Package-level. */
+    readonly op: 'createHeaderFooter';
+    readonly sectionIndex: number;
+    readonly kind: 'header' | 'footer';
+    readonly variant: 'default' | 'first' | 'even';
+    /** When true, also set section `w:titlePg` in the same package transaction. */
+    readonly titlePage?: boolean;
+    /** When true, also set document `w:evenAndOddHeaders` in the same package transaction. */
+    readonly evenAndOddHeaders?: boolean;
+} | {
+    /** Remove a section's declared header/footer reference; GC when orphaned. Package-level. */
+    readonly op: 'deleteHeaderFooter';
+    readonly sectionIndex: number;
+    readonly kind: 'header' | 'footer';
+    readonly variant: 'default' | 'first' | 'even';
+} | {
+    /** Drop a declared ref so the section inherits from the previous. Package-level. */
+    readonly op: 'linkToPrevious';
+    readonly sectionIndex: number;
+    readonly kind: 'header' | 'footer';
+    readonly variant: 'default' | 'first' | 'even';
+} | {
+    /** Clone an inherited part into a new declared reference. Package-level. */
+    readonly op: 'unlinkFromPrevious';
+    readonly sectionIndex: number;
+    readonly kind: 'header' | 'footer';
+    readonly variant: 'default' | 'first' | 'even';
+} | {
+    /**
+     * Section/document furniture options: `titlePg`, header/footer distances on the
+     * section; `evenAndOddHeaders` document-wide in settings. Package-level.
+     */
+    readonly op: 'setSectionFurnitureOptions';
+    readonly sectionIndex?: number;
+    readonly titlePage?: boolean;
+    readonly evenAndOddHeaders?: boolean;
+    readonly headerDistanceTwips?: number;
+    readonly footerDistanceTwips?: number;
+} | {
+    /**
+     * Word's Protect Document: enforce or lift `w:documentProtection` in `settings.xml`.
+     * Enforcing writes `w:edit="forms"` (filling in forms, the one restriction the store
+     * applies); lifting keeps the recorded mode and clears `w:enforcement`, as Word's Stop
+     * Protection does. A password-protected file refuses to lift. Package-level.
+     */
+    readonly op: 'setDocumentProtection';
+    readonly enforce: boolean;
+} | {
+    /**
+     * Insert a footnote or endnote: body reference + notes-part body (+ create the
+     * notes part/rel/content-type when missing). Package-level; one ModelChange.
+     */
+    readonly op: 'insertNote';
+    readonly noteKind: 'footnote' | 'endnote';
+    readonly paragraphId: string;
+    readonly offset: number;
+    /**
+     * Write the citing REFERENCE as a tracked insertion (`w:ins` around the reference
+     * run), on the same terms as `insertText`. The note body itself is not revision
+     * markup: rejecting the reference removes it, and the body cascade sweeps the
+     * orphaned note exactly as an untracked reference deletion does.
+     */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    /**
+     * Delete a note body and every matching reference (body, HF, other notes).
+     * Package-level; one ModelChange.
+     */
+    readonly op: 'deleteNote';
+    readonly noteKind: 'footnote' | 'endnote';
+    readonly noteId: number;
+} | {
+    /** Convert a footnote ↔ endnote, reallocating id in the target part. Package-level. */
+    readonly op: 'convertNote';
+    readonly fromKind: 'footnote' | 'endnote';
+    readonly noteId: number;
+} | {
+    /**
+     * Convert every normal footnote↔endnote of `fromKind` in one package transaction.
+     * One ModelChange / undo unit; bounded by notes-part size.
+     */
+    readonly op: 'convertAllNotes';
+    readonly fromKind: 'footnote' | 'endnote';
+} | {
+    /**
+     * Write a content control's VALUE, in the vocabulary its own type accepts.
+     *
+     * One transaction for the whole transition: the content, `w:showingPlcHdr`, and the
+     * type's own record of the value (`@w:lastValue`, `@w:fullDate`, `w14:checked`) move
+     * together, because a control whose glyph says checked and whose flag says unchecked is
+     * a document Word and this engine read differently.
+     */
+    readonly op: 'setContentControlValue';
+    readonly controlId: string;
+    /** String is the editor-facing v2 form; structured input is the automation form. */
+    readonly value: string | ContentControlValueInput;
+} | {
+    /**
+     * Author the metadata a control carries: its tag, its title, its lock.
+     *
+     * `null` removes the property. Everything else in `CT_SdtPr` — the type payload, a data
+     * binding, an extension this vocabulary does not model — survives in schema order.
+     */
+    readonly op: 'setContentControlProperties';
+    readonly controlId: string;
+    readonly tag?: string | null;
+    readonly alias?: string | null;
+    readonly lock?: ContentControlLock;
+} | {
+    /**
+     * Remove a control. `keepContent` splices its content into its place — Word's own
+     * "Remove content control" — and false takes the content with it.
+     */
+    readonly op: 'removeContentControl';
+    readonly controlId: string;
+    /** Defaults to true for the editor-facing v2 operation. */
+    readonly keepContent?: boolean;
+} | {
+    /**
+     * Wrap `[start, end)` of a paragraph in a new control of the named type.
+     *
+     * A control is a SIBLING of runs, never a thing inside one, so a range ending mid-run
+     * splits that run at both edges first. The characters and their formatting are the ones
+     * that were there; only the run boundaries move.
+     */
+    readonly op: 'insertContentControl';
+    /** Record a wrapper over existing text as a native replacement revision. */
+    readonly revision?: RevisionAttributionInput;
+    readonly paragraphId: string;
+    readonly start: number;
+    readonly end: number;
+    readonly type: InsertableContentControlKind;
+    readonly tag?: string;
+    readonly alias?: string;
+    readonly lock?: ContentControlLock;
+} | {
+    /**
+     * Author `w:footnotePr` / `w:endnotePr` at document (settings) or section scope.
+     * Refuse endnote `pageBottom`. Package-level; does not invent props on unedited saves.
+     */
+    readonly op: 'setNoteProperties';
+    readonly scope: 'document' | 'section';
+    readonly sectionIndex?: number;
+    readonly footnote?: {
+        readonly numFmt?: string;
+        readonly numRestart?: string;
+        readonly position?: string;
+        readonly numStart?: number;
+    };
+    readonly endnote?: {
+        readonly numFmt?: string;
+        readonly numRestart?: string;
+        readonly position?: string;
+        readonly numStart?: number;
+    };
+} | {
+    /**
+     * Insert clipboard-fragment blocks at a paragraph position, atomically.
+     *
+     * Blocks only — resources (styles, numbering, media, rels, note parts) merge through
+     * the package-edit path in the same transaction, and the whole commit is promoted to
+     * a package undo unit. A merged edge paragraph takes the properties of the paragraph
+     * mark that ends it: the fragment's first mark leading, the host's original mark
+     * trailing. Nodes receive fresh ids at apply.
+     */
+    readonly op: 'insertFragment';
+    readonly paragraphId: string;
+    readonly offset: number;
+    readonly blocks: readonly OoxmlNode[];
+    /** True when the fragment's last paragraph mark travelled (its paragraph stays whole). */
+    readonly lastMarkCovered?: boolean;
+} | {
+    readonly op: 'insertDrawing';
+    readonly paragraphId: string;
+    readonly offset: number;
+    readonly drawing: OoxmlDrawingNode;
+    /** Present in suggesting mode: the drawing's run goes into a `w:ins` as one proposal. */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    readonly op: 'replaceDrawingResource';
+    readonly drawingNodeId: string;
+    readonly relationshipId: string;
+} | {
+    readonly op: 'deleteDrawing';
+    readonly drawingNodeId: string;
+    /** Suggesting-mode tracked deletion is refused; owned by typed-revisions-and-comments. */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    readonly op: 'resizeDrawing';
+    readonly drawingNodeId: string;
+    readonly extentEmu: {
+        readonly cx: number;
+        readonly cy: number;
+    };
+} | {
+    readonly op: 'cropDrawing';
+    readonly drawingNodeId: string;
+    readonly crop: SourceCrop;
+} | {
+    readonly op: 'positionDrawing';
+    readonly drawingNodeId: string;
+    readonly position: DrawingPositionInput;
+} | {
+    readonly op: 'setDrawingWrap';
+    readonly drawingNodeId: string;
+    readonly wrap: ImageWrapTarget;
+} | {
+    readonly op: 'setDrawingMetadata';
+    readonly drawingNodeId: string;
+    readonly title: string;
+    readonly description: string;
+    /** Omitted preserves existing `a:hlinkClick`; null removes it; a URL needs a package transaction. */
+    readonly hyperlink?: string | null;
+} | {
+    readonly op: 'setDrawingLocks';
+    readonly drawingNodeId: string;
+    readonly locks: DrawingLocksInput;
+} | {
+    readonly op: 'transformDrawing';
+    readonly drawingNodeId: string;
+    readonly action: 'rotateCW' | 'rotateCCW' | 'flipH' | 'flipV';
+} | {
+    /**
+     * Replace a detected TOC field's cached result paragraphs and ensure heading bookmarks.
+     * Preserves field chrome / instruction. One undo unit (phase A of TOC refresh).
+     */
+    readonly op: 'replaceTocResult';
+    readonly tocId: string;
+    readonly entries: readonly {
+        readonly level: number;
+        readonly text: string;
+        readonly headingParagraphId: string;
+        readonly bookmarkName: string;
+        readonly pageNumberText: string;
+    }[];
+    readonly bookmarksToCreate: readonly {
+        readonly paragraphId: string;
+        readonly name: string;
+    }[];
+} | {
+    /**
+     * Rewrite page-number text runs inside existing TOC result paragraphs.
+     * One undo unit (phase B of TOC refresh).
+     */
+    readonly op: 'rewriteTocPageNumbers';
+    readonly tocId: string;
+    readonly updates: readonly {
+        readonly paragraphId: string;
+        readonly pageNumberText: string;
+    }[];
+} | SetTextFormFieldDefaultOp | CommitTextFormFieldOp | SetLegacyCheckboxOp | SetLegacyDropdownOp | InsertBuildingBlockOp | {
+    /**
+     * Rewrite recognized fields' cached RESULT runs in place — between the `separate` and
+     * `end` fldChars, or a `w:fldSimple`'s content. The instruction is never modified; a
+     * result holding anything but plain runs is skipped (see `tree-op-field-results.ts`).
+     */
+    readonly op: 'refreshFieldResults';
+    readonly updates: readonly {
+        readonly paragraphId: string;
+        /** Node id of the field's begin `w:fldChar`, or of the `w:fldSimple` element. */
+        readonly fieldNodeId: string;
+        readonly text: string;
+    }[];
+};
+/** Drawing mutation ops from typed-drawings-and-images task 11. */
+type DrawingTreeDocOp = Extract<TreeDocOp, {
+    readonly op: 'insertDrawing' | 'replaceDrawingResource' | 'deleteDrawing' | 'resizeDrawing' | 'cropDrawing' | 'positionDrawing' | 'setDrawingWrap' | 'setDrawingMetadata' | 'setDrawingLocks' | 'transformDrawing';
+}>;
+/** Just the `op` discriminants, for dispatch tables and validation. */
+type TreeDocOpKind = TreeDocOp['op'];
+
+/**
+ * How far a committed op can reach, so layout can scope its work (task 5.2).
+ *
+ * `text-local` touches one paragraph's characters; `paragraph-local` changes one
+ * paragraph's own properties; `flow-structural` changes the block sequence and can
+ * repaginate everything after it; `global` invalidates every page that shares the
+ * edited story (header/footer parts attached to many sections/pages).
+ */
+/**
+ * How far an op's effects reach — what layout must re-do after it.
+ *
+ * The knob incremental layout turns: a `text-local` edit re-breaks one paragraph, while a
+ * `global` one invalidates the document.
+ */
+type ImpactClass = 'text-local' | 'paragraph-local' | 'flow-structural' | 'global';
+/**
+ * What one applied op changed: the ids dirtied, created and deleted.
+ *
+ * These ids are what let layout and paint re-do only what moved instead of the whole document.
+ */
+interface TreeOpEffect {
+    readonly dirty: readonly string[];
+    readonly created: readonly string[];
+    readonly deleted: readonly string[];
+    readonly split?: {
+        readonly from: string;
+        readonly tail: string;
+    };
+    /** One entry per boundary of a many-way split, in document order. */
+    readonly splits?: readonly {
+        readonly from: string;
+        readonly tail: string;
+    }[];
+    readonly join?: {
+        readonly kept: string;
+        readonly removed: string;
+    };
+    readonly dependencyKeys: readonly string[];
+    readonly impact: ImpactClass;
+    /** First post-edit caret paragraph for table column structural ops. */
+    readonly caret?: {
+        readonly paragraphId: string;
+    };
+}
+/**
+ * Why an op was refused.
+ *
+ * `not-adjacent-siblings` is the notable one: a join across table cells is refused rather than
+ * silently merging content out of the cell that owned it.
+ */
+type TreeOpRejection = 'unknown-op' | 'unknown-paragraph' | 'not-a-paragraph' | 'offset-out-of-range' | 'invalid-range' | 'not-a-list-paragraph' | 'splits-surrogate-pair' | 'invalid-text' | 'unsupported-property' | 'invalid-property-value' | 'not-adjacent-siblings'
+/**
+ * The addressed position is strictly inside content nothing can divide: a hyperlink, an
+ * inline content control, a revision wrapper, or an atomic field.
+ *
+ * Distinct from `invalid-range`, which is an offset the paragraph does not have. This one is
+ * a real offset that is not a PLACE — refused rather than resolved to the nearest one, so a
+ * caller learns the node would not have landed where they asked.
+ */
+ | 'indivisible-content'
+/**
+ * The range has one end inside a field's editable saved result and the other outside it.
+ * Deleting it would leave the field's begin, separate, and end markers unbalanced, so it is
+ * refused. A range that covers the whole field removes the field.
+ */
+ | 'field-structure'
+/**
+ * In the editable field-result mode, an op other than typing, deletion, or run formatting
+ * addresses a position inside a field's saved result. Splits, tabs, links, notes, and
+ * fragments there are not supported yet.
+ */
+ | 'field-result-unsupported' | 'unknown-block' | 'not-a-block' | 'block-required' | 'carries-section-mark'
+/** The transaction named a part the package does not hold. */
+ | 'unknown-part'
+/**
+ * The transaction would have published a package that does not open: a relationship
+ * pointing at a part nobody created, or a part with no declared content type.
+ */
+ | 'package-invariant'
+/** No revision in this part carries the addressed `(id, author, date)` triple. */
+ | 'unknown-revision'
+/**
+ * A matched revision is a kind whose accept/reject semantics are structural and not
+ * implemented. Refusing is deliberate: removing the markup alone would report the decision
+ * applied while leaving the row, cell, or section it describes untouched.
+ */
+ | 'unsupported-revision' | 'tree-invariant'
+/** No content control in this part carries the addressed node id. */
+ | 'unknown-content-control'
+/** The addressed node exists and is not a `w:sdt`. */
+ | 'not-a-content-control'
+/**
+ * A content control's `w:lock` — or one an enclosing control imposes — forbids this.
+ *
+ * The same code for an edit inside `contentLocked` content and for the removal of an
+ * `sdtLocked` control: both are "the document says no", and the two halves are already
+ * distinguished by which operation was refused.
+ */
+ | 'locked'
+/** The control declares `w:dataBinding`; its value belongs to a custom XML part. */
+ | 'bound'
+/** The value offered is not one this control's type accepts. */
+ | 'typeMismatch' | 'unknown-control' | 'unsupported'
+/** Malformed lifecycle args / first-section link — mirrors Editor `invalidArgs`. */
+ | 'invalidArgs'
+/** The addressed table id is missing, duplicated, or not a typed table. */
+ | 'unknown-table'
+/** The addressed row id is missing or not a direct child of the table. */
+ | 'unknown-row'
+/** A table property container appears more than once on a typed node. */
+ | 'duplicate-property-container'
+/**
+ * A row holds a `w:tc` inside a cell-level wrapper such as `w:sdt`, so the row's grid
+ * mapping cannot be trusted and the inserted row would not match it.
+ */
+ | 'row-hides-cell'
+/** Column edit refused because the table carries horizontal or vertical merges. */
+ | 'table-has-merge'
+/** The addressed grid column id is missing or ambiguous without `w:tblGrid`. */
+ | 'unknown-grid-column'
+/** The operation would exceed bounded table topology limits. */
+ | 'resource-limit'
+/** The addressed node is not a top-level `w:drawing`. */
+ | 'not-a-drawing'
+/** No `w:drawing` with this id exists in the part. */
+ | 'unknown-drawing'
+/** The drawing's graphic payload is not a supported picture. */
+ | 'not-a-picture-drawing'
+/** A lock flag or `@locked` forbids this mutation. */
+ | 'drawing-locked'
+/** Finite EMU extent, crop, or position value is out of range. */
+ | 'invalid-drawing-value'
+/** Insertion would cross a table-cell boundary or wrong story container. */
+ | 'cross-cell-drawing'
+/** Suggesting-mode drawing deletion is not implemented in this change. */
+ | 'trackedDrawingDeletionUnsupported'
+/** Hyperlink target creation or change needs an OPC relationship in a package transaction. */
+ | 'packageTransactionRequired'
+/** A clipboard fragment block nests deeper than the recursion cap. */
+ | 'fragment-too-deep'
+/** A clipboard fragment block is not a paragraph, table, or content control subtree. */
+ | 'fragment-invalid-block'
+/** A clipboard fragment exceeds its block or node budget. */
+ | 'fragment-resource-budget';
+/** Whether an op applied, with the effect it produced or the reason it was refused. */
+type TreeOpResult = {
+    readonly ok: true;
+    readonly part: OoxmlPart;
+    readonly effect: TreeOpEffect;
+} | {
+    readonly ok: false;
+    readonly reason: TreeOpRejection;
+    readonly detail?: string;
+};
+
+export { CONTENT_CONTROL_ID_MAX as a$, IMAGE_WRAP_TARGETS as aH, TEXT_FORM_FORMATS as aI, ACCEPTED_PARAGRAPH_PROPERTIES as aZ, ACCEPTED_RUN_PROPERTIES as a_, CONTENT_CONTROL_PROPERTY_ORDER as b0, DEFAULT_OOXML_PACKAGE_LIMITS as bh, DEFAULT_ZIP_LIMITS as bi, HYPERLINK_RELATIONSHIP_TYPE as bl, IMAGE_RELATIONSHIP_TYPE as bo, MAX_CONTENT_CONTROLS_PER_PART as bu, MAX_CONTENT_CONTROL_NESTING as bv, OFFICE_RELATIONSHIP_NAMESPACE_URI as by, OOXML_NODE_IDENTITY_RULES as bz, hyperlinkTargetOf as c$, allocateContentControlId as cD, asciiFold as cE, buildContentTypeIndex as cF, buildRelationshipSet as cG, childElements as cH, commentAnchorsOfStory as cI, commentsOfPart as cJ, contentControlContentChildren as cK, contentControlContentNodeOf as cL, contentControlEndPropertiesNodeOf as cM, contentControlLevelOf as cN, contentControlPropertiesNodeOf as cO, contentControlPropertiesOf as cP, contentControlTextOf as cQ, contentControlsIn as cR, detectDuplicateNames as cS, extensionKey as cT, findContentControl as cU, findElement as cV, firstReviewRange as cW, flattenContentControls as cX, hasAnyComment as cY, hyperlinkAnchorOf as cZ, hyperlinkRelationshipIdOf as c_, TABLE_BORDER_STYLES as ck, W15_NAMESPACE_URI as cs, WML_NAMESPACE_URI as ct, XMLNS_NAMESPACE_URI as cu, XML_NAMESPACE_URI as cv, isContentControlContentNode as d0, isContentControlNode as d1, isContentControlWrapper as d2, isContentRevisionKind as d3, isHyperlinkNode as d4, isRangeMarkerKind as d5, isValidMime as d6, legacyCheckboxFieldsOf as d7, lockForbidsEdit as d8, lockForbidsRemoval as d9, writeZip as dA, activeReviewItem as dC, reviewItemPositionRank as dD, reviewItemsAt as dE, reviewThreadRootOf as dF, normalizePartName as da, orderedContentControlProperties as db, parseContentControlId as dc, partNameKey as dd, planRevisionAuthorChange as de, planRevisionBatch as df, projectDrawing as dg, readOnOffChild as dh, readOoxmlPackage as di, readOoxmlPart as dj, readXml as dk, readZip as dl, resolveContentControlLock as dm, resolveContentType as dn, resolveImageRelationship as dp, resolveInternalTarget as dq, resolveRelationship as dr, reviewItemKey as ds, reviewItemRanges as dt, textContent as du, textFormFieldsOf as dv, threadStateOfPart as dw, validateExternalTarget as dx, withPart as dy, writeOoxmlPackage as dz };
+export type { OoxmlContentControlContentNode as $, ParagraphTabStop as A, Block as B, CommentRecord as C, DocxDocument as D, ExecResult as E, RevisionType as F, Section as G, HeaderFooterSet as H, InsertableContentControlType as I, SectionProperties as J, StyleDefinition as K, Theme as L, ThemeColorScheme as M, OoxmlNode as N, OoxmlPart as O, Paragraph as P, OoxmlPackage as Q, ReviewModelInput as R, StyleDefinitions as S, Table as T, OoxmlNodeId as U, OoxmlGenericElementNode as V, TreeDocOp as W, OoxmlProperty as X, OoxmlPackageRejection as Y, OoxmlElement as Z, OoxmlContentControlNode as _, ReviewItem as a, DrawingProjection as a0, OoxmlPackageLimits as a1, RevisionAuthorEntry as a2, RevisionAuthorResult as a3, RevisionAuthorSkipReason as a4, RevisionBatchEntry as a5, RevisionBatchResult as a6, RevisionBatchSkipReason as a7, TreeOpRejection as a8, AutomationTableMutation as a9, PageMargins as aA, ParagraphDisagreements as aB, Point as aC, Run as aD, TableCell as aE, TableRow as aF, TreeDocColorValue as aG, TableBorderStyle as aJ, DrawingAccessibility as aK, DrawingImageEffects as aL, DrawingTransform as aM, VectorShapeProjection as aN, OoxmlDrawingNode as aO, OoxmlInvariantResult as aP, OoxmlInvariantIssue as aQ, OoxmlFldCharNode as aR, OoxmlFldSimpleNode as aS, OoxmlInstrTextNode as aT, TreeOpResult as aU, RelationshipRecord as aV, OoxmlHardBreakNode as aW, OoxmlAttribute as aX, CommentThreadState as aY, RevisionAttributionInput as aa, OoxmlParagraphNode as ab, OoxmlNoteNode as ac, OoxmlContinuationSeparatorNode as ad, OoxmlEndnotesNode as ae, OoxmlFootnotesNode as af, OoxmlNoteRefNode as ag, OoxmlNoteReferenceNode as ah, OoxmlSeparatorNode as ai, DrawingTreeDocOp as aj, ImpactClass as ak, SourceCrop as al, DrawingKind as am, ImageWrapTarget as an, DrawingPositionInput as ao, DrawingLocks as ap, ParagraphFormatCommand as aq, Watermark as ar, Rect as as, SelectionPin as at, Unsubscribe as au, DocxDocumentJSON as av, DrawingHorizontalReferenceFrame as aw, DrawingVerticalReferenceFrame as ax, FontDefinition as ay, NumberingRef as az, ReviewRevisionItem as b, OoxmlPackageResult as b$, CommentAnchor as b1, CommentPosition as b2, CommitTextFormFieldOp as b3, ContentControlCheckbox as b4, ContentControlCheckboxState as b5, ContentControlDataBinding as b6, ContentControlDateFormat as b7, ContentControlEntry as b8, ContentControlKind as b9, OoxmlBodyNode as bA, OoxmlBookmarkEndNode as bB, OoxmlBookmarkStartNode as bC, OoxmlContentControlCalendarNode as bD, OoxmlContentControlCheckboxNode as bE, OoxmlContentControlCheckedNode as bF, OoxmlContentControlCheckedStateNode as bG, OoxmlContentControlComboBoxNode as bH, OoxmlContentControlDataBindingNode as bI, OoxmlContentControlDateFormatNode as bJ, OoxmlContentControlDateNode as bK, OoxmlContentControlDropDownListNode as bL, OoxmlContentControlEndPropertiesNode as bM, OoxmlContentControlLidNode as bN, OoxmlContentControlListItemNode as bO, OoxmlContentControlPropertiesNode as bP, OoxmlContentControlStoreMappedDataAsNode as bQ, OoxmlContentControlTextNode as bR, OoxmlContentControlUncheckedStateNode as bS, OoxmlDocumentNode as bT, OoxmlExternalTarget as bU, OoxmlGenericExtensionAttribute as bV, OoxmlHyperlinkNode as bW, OoxmlInvariantIssueCode as bX, OoxmlKnownNodeAttribute as bY, OoxmlNamespaceBinding as bZ, OoxmlNodeIdentityRules as b_, ContentControlLevel as ba, ContentControlListItem as bb, ContentControlLock as bc, ContentControlProperties as bd, ContentTypeError as be, ContentTypeIndex as bf, ContentTypeRecords as bg, DefaultRecord as bj, DeleteTextOp as bk, HyperlinkKind as bm, HyperlinkTarget as bn, ImageRelationshipResolution as bp, IndexResult as bq, InsertBuildingBlockOp as br, InsertTextOp as bs, LegacyCheckboxFieldRange as bt, NameRejection as bw, NameResult as bx, ReviewCommentItem as c, OoxmlParagraphPropertiesNode as c0, OoxmlPartMetadata as c1, OoxmlReadRejection as c2, OoxmlReadResult as c3, OoxmlRunNode as c4, OoxmlRunPropertiesNode as c5, OoxmlTabNode as c6, OoxmlTextElementNode as c7, OoxmlTextNode as c8, OoxmlWmlValAttribute as c9, ZipLimits as cA, ZipReadResult as cB, ZipRejection as cC, OoxmlXmlSpaceAttribute as ca, OverrideRecord as cb, RelationshipError as cc, RelationshipSetResult as cd, RelationshipTargetResolver as ce, ResolveResult as cf, ResolvedRelationship as cg, SetLegacyCheckboxOp as ch, SetLegacyDropdownOp as ci, SetTextFormFieldDefaultOp as cj, TabStopWrite as cl, TargetMode as cm, TextFormFieldOptions as cn, TextFormFieldRange as co, TextFormFieldType as cp, TreeDocOpKind as cq, TreeOpEffect as cr, XmlLimits as cw, XmlNode as cx, XmlRejection as cy, XmlResult as cz, ReviewCustomItem as d, VectorShapeComponent as dB, ReviewPosition as e, ReviewRange as f, ReviewRevisionKind as g, RevisionAddress as h, ContentControlType as i, DocTarget as j, RunFormatting as k, Extent as l, ContainerRef as m, ContentControlFilter as n, DocRange as o, Revision as p, DocComment as q, ColorValue as r, ContentControl as s, DocAnchor as t, DocAnchorRange as u, DocLocation as v, DocumentBody as w, ExecErrorCode as x, IndentFormatting as y, ParagraphFlags as z };