@docx-editor.dev/core 2.9.2 → 2.11.0

package/dist/tree-op-types-BPyXNxyL.d.cts

@@ -0,0 +1,3053 @@
+import { ParagraphTabStop } from './contracts/types.cjs';
+
+/**
+ * The engine's trust-boundary caps: recursion depth, element counts, and the rest.
+ *
+ * A caller may LOWER any of these but never raise or disable one — an override of `Infinity`,
+ * zero, a negative or `NaN` clamps into `(0, ceiling]` rather than turning the limit off. These
+ * are security ceilings, not performance budgets.
+ */
+interface ResourceLimits {
+    /** Max nested-structure recursion (tables/shapes/SDT/groups). */
+    readonly maxRecursionDepth: number;
+    /** Max total parsed element count. */
+    readonly maxElementCount: number;
+    /** Max package part count. */
+    readonly maxPartCount: number;
+    /** Max total decompressed bytes (zip-bomb guard). */
+    readonly maxDecompressedBytes: number;
+    /** Max total compressed input bytes. */
+    readonly maxCompressedBytes: number;
+    /** Max decompressed:compressed ratio per entry. */
+    readonly maxCompressionRatio: number;
+    /** In-memory chunk budget for streaming/spooling. */
+    readonly maxChunkBytes: number;
+    /** Max pagination passes before non-convergence is declared. */
+    readonly maxPaginationPasses: number;
+    /** Max queued items in any bounded work queue. */
+    readonly maxQueueDepth: number;
+}
+/** Non-disableable hard ceilings: no resolved limit may exceed these. */
+declare const HARD_CEILINGS: ResourceLimits;
+/** Finite defaults, all <= their hard ceiling. */
+declare const DEFAULT_LIMITS: ResourceLimits;
+/**
+ * Resolve caller overrides into a frozen, always-finite limit set. Each value is
+ * `min(override>0 ? override : default, ceiling)`. Infinity/0/negative/NaN can
+ * never disable a limit — the hard ceiling always wins.
+ */
+declare function resolveLimits(overrides?: Partial<ResourceLimits>): ResourceLimits;
+/** Bounded image decode limits (typed-drawings-and-images task 4). */
+/** Trust-boundary caps specific to image decoding and embedding. */
+interface ImageResourceLimits {
+    readonly maxEncodedBytes: number;
+    readonly maxDecodedBytes: number;
+    readonly maxPixels: number;
+    readonly maxDimension: number;
+    readonly maxPolygonPoints: number;
+    readonly maxExternalRedirects: number;
+}
+/** Image caps nothing can raise past. A caller's override clamps into these. */
+declare const IMAGE_RESOURCE_HARD_CEILINGS: ImageResourceLimits;
+/** The image caps in force when a host configures none. Conservative and finite. */
+declare const DEFAULT_IMAGE_RESOURCE_LIMITS: ImageResourceLimits;
+/** Resolve caller overrides into frozen image limits; hard ceilings cannot be raised. */
+declare function resolveImageResourceLimits(overrides?: Partial<ImageResourceLimits>): ImageResourceLimits;
+
+/**
+ * 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;
+
+/** 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;
+
+/** 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 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;
+    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 inside a run. */
+interface OoxmlHardBreakNode extends OoxmlElementBase<readonly [], readonly OoxmlKnownNodeAttribute[]> {
+    readonly kind: 'hardBreak';
+    readonly namespaceUri: typeof WML_NAMESPACE_URI;
+    readonly localName: 'br';
+}
+/**
+ * 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;
+
+/**
+ * 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 per-entry uncompressed:compressed ratio (zip-bomb guard). */
+    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;
+};
+/**
+ * Inflate a ZIP archive with bounds + OPC name normalization. Entry name, count,
+ * compression-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.
+ */
+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;
+
+/** 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;
+}
+
+/**
+ * The renderable subset of a `wps:wsp` non-picture graphic: closed polygon subpaths
+ * (`a:custGeom` with move/line/close verbs only, or `a:prstGeom prst="rect"`) with a
+ * solid sRGB fill and/or stroke. Anything richer (curves, theme fills, text bodies,
+ * rotation) 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;
+    }>;
+    /** Closed subpath polygons in extent-EMU space; fill rule is even-odd. */
+    readonly subpathsEmu: readonly (readonly Readonly<{
+        x: number;
+        y: number;
+    }>[])[];
+    /** Validated 6-digit sRGB hex (no `#`), or null for no fill. */
+    readonly fillHex: string | null;
+    /** Validated 6-digit sRGB hex (no `#`), or null for no stroke. */
+    readonly strokeHex: string | null;
+    /** Stroke width in EMU; 0 when absent. */
+    readonly strokeWidthEmu: number;
+}
+/**
+ * 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';
+    /** 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;
+}
+
+/**
+ * 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;
+    readonly textboxStory: TextboxStoryProjection | null;
+    readonly locks: DrawingLocks;
+    readonly effects: Readonly<{
+        grayscale: boolean;
+        brightness: number;
+        contrast: number;
+    }>;
+    readonly compatibilityBranchNodeId: string | null;
+    readonly diagnostics: readonly DrawingDiagnostic[];
+}
+interface DrawingAccessibility {
+    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;
+}>): DrawingProjection | null;
+
+/** Opaque handle — bytes are reachable only through {@link mintValidatedImageBytes}. */
+interface ValidatedImageBytesHandle {
+    readonly registryId: number;
+    readonly resourceKey: string;
+    readonly contentId: string;
+    readonly generation: number;
+}
+
+/**
+ * Raster media the decode port measures and any authoring path may write.
+ *
+ * BMP and WebP are here for the same reason the other three are: an `<img>` decodes them
+ * natively, so they need a signature and a structural header and nothing else. BMP is what
+ * older documents carry; WebP is what current Word writes.
+ */
+type SupportedImageMime = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/bmp' | 'image/webp';
+/**
+ * Vector media painted straight from validated bytes. An `<img>` renders SVG in the
+ * browser's secure static mode — no script, no external subresource loads — so there is
+ * no decode step and no raster buffer sized by a file-supplied number.
+ */
+type VectorImageMime = 'image/svg+xml';
+/** Every mime the painter can hand to an `<img>`. */
+type RenderableImageMime = SupportedImageMime | VectorImageMime;
+/**
+ * Media kept in the package byte-for-byte that the painter cannot hand to an `<img>`.
+ * A decode port may rasterize it; without one it paints as a labelled placeholder.
+ */
+type PreservedImageMime = 'image/tiff' | 'image/x-emf' | 'image/x-wmf';
+/**
+ * What is known about one embedded image: validated, refused, or still decoding.
+ *
+ * Content type is a CLAIM. Signature sniffing, structural header validation and the decode port
+ * are authoritative, and bytes that fail them never enter public state.
+ */
+type ImageResourceState = {
+    readonly kind: 'ready';
+    readonly partName: string;
+    readonly contentId: string;
+    readonly resourceKey: string;
+    readonly validatedHandle: ValidatedImageBytesHandle;
+    readonly mime: RenderableImageMime;
+    readonly pixelWidth: number;
+    readonly pixelHeight: number;
+    readonly dpiX: number;
+    readonly dpiY: number;
+} | {
+    readonly kind: 'unrenderable';
+    readonly partName: string | null;
+    readonly mime: RenderableImageMime | PreservedImageMime | 'unknown';
+    readonly reason: 'unsupported-format' | 'non-picture-graphic' | 'signature-mismatch' | 'decode-failed' | 'resource-limit';
+} | {
+    readonly kind: 'external';
+    readonly relationshipId: string;
+    readonly sinkSafe: boolean;
+} | {
+    readonly kind: 'missing';
+    readonly relationshipId: string;
+} | {
+    readonly kind: 'pending';
+    readonly resourceKey: string;
+};
+/**
+ * The injected image decoder.
+ *
+ * A port rather than a direct `Image`/`createImageBitmap` call, so a worker or server runtime
+ * supplies its own and the engine never reaches for a browser global.
+ */
+interface ImageDecodePort {
+    decode(bytes: Uint8Array, mime: SupportedImageMime, limits: ImageResourceLimits): Promise<Readonly<{
+        pixelWidth: number;
+        pixelHeight: number;
+        dpiX: number;
+        dpiY: number;
+    }>>;
+    /**
+     * Optional conversion of media an `<img>` cannot render (EMF/WMF metafiles, TIFF) into a
+     * renderable raster. The returned bytes are untrusted and re-enter the full raster
+     * validation path (sniff, header, pixel caps, decode) before they can become a ready
+     * resource. A null return declines the format and keeps the labelled placeholder; so does
+     * a throw, as `decode-failed`.
+     */
+    convertPreserved?(bytes: Uint8Array, mime: PreservedImageMime, limits: ImageResourceLimits): Promise<Readonly<{
+        bytes: Uint8Array;
+        mime: SupportedImageMime;
+    }> | null>;
+}
+/** Resolves a relationship id to a validated image resource, or reports why it could not. */
+interface ImageResourceLookup {
+    readonly resolveEmbedded: (ownerPartName: string, relationshipId: string) => Promise<ImageResourceState>;
+    readonly resolveLinked: (ownerPartName: string, relationshipId: string) => ImageResourceState;
+    readonly resolveForProjection: (projection: DrawingProjection) => Promise<ImageResourceState>;
+    readonly liveReferenceCount: (partName: string) => number;
+    readonly dispose: () => void;
+}
+/** Maximum prefix inspected for SVG root detection (exported for bounded-scan tests). */
+declare const MAX_SVG_SNIFF_BYTES = 512;
+/** A raster header that passed structural validation: its real MIME type and pixel extent. */
+interface ValidatedRasterHeader {
+    readonly pixelWidth: number;
+    readonly pixelHeight: number;
+}
+/** Bounded scan for an `<svg` document root (optional `<?xml` prolog only). */
+declare function hasBoundedSvgRoot(bytes: Uint8Array): boolean;
+/** Signature sniffing — authoritative over declared content type. */
+declare function sniffImageMime(bytes: Uint8Array): RenderableImageMime | PreservedImageMime | 'unknown';
+/** Structural PNG IHDR validation before decode. */
+declare function validatePngHeader(bytes: Uint8Array): ValidatedRasterHeader | null;
+/** Structural GIF logical screen descriptor validation before decode. */
+declare function validateGifHeader(bytes: Uint8Array): ValidatedRasterHeader | null;
+/** Bounded JPEG marker scan through the first supported SOF marker. */
+declare function validateJpegHeader(bytes: Uint8Array): ValidatedRasterHeader | null;
+/**
+ * Intrinsic size of an SVG, resolved the way a browser sizes one: absolute `width`/`height`
+ * first, then `viewBox` for the missing axis or ratio, then the CSS 300x150 default.
+ *
+ * This is metadata for insert and reset-to-natural-size only. Layout uses the authored
+ * `wp:extent` and the browser rasterizes into that box, so nothing here sizes an allocation
+ * and an out-of-range value is clamped rather than refused.
+ */
+declare function resolveSvgIntrinsicSize(bytes: Uint8Array, limits: ImageResourceLimits): ValidatedRasterHeader | null;
+/**
+ * Validate a raster image's header structurally and report its real MIME type and extent.
+ *
+ * Content type is a CLAIM; this is what makes it a fact. A file declaring `image/png` over JPEG
+ * bytes is caught here rather than at decode.
+ */
+declare function validateRasterHeader(bytes: Uint8Array, mime: SupportedImageMime): ValidatedRasterHeader | null;
+/** Package-wide live drawing references to a media part name. */
+declare function liveDrawingReferenceCount(pkg: OoxmlPackage, partName: string): number;
+/** How the image cache decodes, and what it will spend doing so. */
+interface CreateImageResourceCacheOptions {
+    readonly limits?: Partial<ImageResourceLimits>;
+    readonly decodePort: ImageDecodePort;
+}
+/**
+ * Derived cache for one immutable package snapshot. Registry identity is
+ * `(package snapshot, decodePort object, normalized limits)` — the first caller
+ * never imposes its decoder or limits on later callers with different options.
+ */
+declare function imageResourceLookupFor(pkg: OoxmlPackage, options: CreateImageResourceCacheOptions): ImageResourceLookup;
+/** @deprecated Prefer {@link imageResourceLookupFor} — registry binds cache to package identity. */
+/** Build the per-document image cache. Validated bytes only; refusals are remembered too. */
+declare function createImageResourceCache(initialPkg: OoxmlPackage, options: CreateImageResourceCacheOptions): ImageResourceLookup;
+
+/** 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;
+};
+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;
+
+/** 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.
+ */
+declare function contentControlTextOf(control: OoxmlNode): 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];
+
+/** 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];
+
+/**
+ * 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;
+}
+
+/** JSON-safe color input carried on table cell property ops. Theme/auto require a validated literal. */
+/**
+ * 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 cell edges a selected-cell border op targets. */
+/** Which edges a border op addresses — the four sides, the interiors, all, or clear. */
+type TableBorderTarget = 'all' | 'outside' | 'inside' | 'none' | 'top' | 'bottom' | 'left' | 'right';
+/** Concrete edge scopes that apply or clear a complete border spec. */
+/** 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"];
+/**
+ * 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 = {
+    /**
+     * 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;
+    }[];
+} | {
+    readonly op: 'insertText';
+    readonly paragraphId: 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';
+} | {
+    readonly op: 'deleteText';
+    readonly paragraphId: string;
+    readonly start: number;
+    readonly end: number;
+    /** Write this as a TRACKED deletion — the characters stay, wrapped in `w:del`. */
+    readonly revision?: RevisionAttributionInput;
+} | {
+    /**
+     * 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;
+} | {
+    readonly op: 'rejectRevision';
+    readonly revision: RevisionAddress;
+    readonly localName?: 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';
+    /** Internal shared-notes scope. When present, this must be the canonical id of a note root. */
+    readonly scopeRootId?: string;
+} | {
+    readonly op: 'rejectAllRevisions';
+    /** 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;
+} | {
+    /**
+     * 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;
+} | {
+    /**
+     * 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;
+    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;
+} | {
+    /**
+     * 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;
+} | {
+    /** 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;
+} | {
+    /** 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;
+} | {
+    /**
+     * 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';
+    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;
+    }[];
+};
+/** 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'];
+/** Every {@link TreeDocOpKind}, for validation and exhaustiveness checks. */
+declare const TREE_DOC_OP_KINDS: readonly ["replaceStoryBlocks", "insertText", "deleteText", "setParagraphMarkRevision", "proposeParagraphMerge", "insertCommentMarker", "acceptRevision", "rejectRevision", "acceptAllRevisions", "rejectAllRevisions", "insertTab", "insertHardBreak", "insertPageBreak", "insertPageField", "setListLevel", "setListNumbering", "setParagraphTabStops", "setParagraphMarkProperties", "splitParagraph", "splitParagraphMany", "joinParagraphs", "setRunProperties", "setParagraphProperties", "setSectionProperties", "setSectionMark", "insertHyperlink", "setHyperlinkTarget", "removeHyperlink", "setMathEquation", "removeMathEquation", "setContentControlValue", "removeContentControl", "insertInlineContentControl", "addRepeatingSectionItem", "removeRepeatingSectionItem", "deleteBlock", "insertTable", "insertTableRow", "deleteTableRow", "insertTableColumn", "deleteTableColumn", "setTableColumnWidths", "setTableRightEdgeWidth", "setTableRowHeight", "setTableCellBorders", "setTableCellFill", "setTableCellVerticalAlignment", "createHeaderFooter", "deleteHeaderFooter", "linkToPrevious", "unlinkFromPrevious", "setSectionFurnitureOptions", "insertNote", "deleteNote", "convertNote", "convertAllNotes", "setNoteProperties", "setContentControlProperties", "insertContentControl", "insertFragment", "insertDrawing", "replaceDrawingResource", "deleteDrawing", "resizeDrawing", "cropDrawing", "positionDrawing", "setDrawingWrap", "setDrawingMetadata", "setDrawingLocks", "transformDrawing", "insertToc", "replaceTocResult", "rewriteTocPageNumbers"];
+/**
+ * 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' | '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 { type ContentControlKind as $, type DrawingVerticalReferenceFrame as A, type VectorImageMime as B, type ImageDecodePort as C, type DrawingKind as D, type RevisionAttributionInput as E, type DrawingTreeDocOp as F, type TreeDocColorValue as G, DEFAULT_IMAGE_RESOURCE_LIMITS as H, type ImpactClass as I, IMAGE_WRAP_TARGETS as J, type ImageResourceLimits as K, resolveImageResourceLimits as L, resolveSvgIntrinsicSize as M, sniffImageMime as N, type OoxmlPart as O, type PreservedImageMime as P, validateRasterHeader as Q, type RevisionAddress as R, type SourceCrop as S, type TreeDocOp as T, type DrawingAccessibility as U, type ValidatedImageBytesHandle as V, type DrawingTransform as W, type VectorShapeProjection as X, type DrawingProjection as Y, type OoxmlDrawingNode as Z, type TableBorderStyle as _, type OoxmlNode as a, type OoxmlContentControlStoreMappedDataAsNode as a$, type ContentControlLevel as a0, type ContentControlLock as a1, type ContentControlDataBinding as a2, type ResourceLimits as a3, type OoxmlInvariantResult as a4, type RelationshipRecord as a5, type OoxmlInvariantIssue as a6, type OoxmlHardBreakNode as a7, type OoxmlFldCharNode as a8, type OoxmlFldSimpleNode as a9, IMAGE_RESOURCE_HARD_CEILINGS as aA, type ImageRelationshipResolution as aB, type ImageResourceLookup as aC, type IndexResult as aD, MAX_CONTENT_CONTROLS_PER_PART as aE, MAX_CONTENT_CONTROL_NESTING as aF, MAX_SVG_SNIFF_BYTES as aG, type NameRejection as aH, type NameResult as aI, OFFICE_RELATIONSHIP_NAMESPACE_URI as aJ, OOXML_NODE_IDENTITY_RULES as aK, type OoxmlBodyNode as aL, type OoxmlBookmarkEndNode as aM, type OoxmlBookmarkStartNode as aN, type OoxmlContentControlCalendarNode as aO, type OoxmlContentControlCheckboxNode as aP, type OoxmlContentControlCheckedNode as aQ, type OoxmlContentControlCheckedStateNode as aR, type OoxmlContentControlComboBoxNode as aS, type OoxmlContentControlDataBindingNode as aT, type OoxmlContentControlDateFormatNode as aU, type OoxmlContentControlDateNode as aV, type OoxmlContentControlDropDownListNode as aW, type OoxmlContentControlEndPropertiesNode as aX, type OoxmlContentControlLidNode as aY, type OoxmlContentControlListItemNode as aZ, type OoxmlContentControlPropertiesNode as a_, type OoxmlInstrTextNode as aa, type OoxmlAttribute as ab, type TreeOpResult as ac, ACCEPTED_PARAGRAPH_PROPERTIES as ad, ACCEPTED_RUN_PROPERTIES as ae, CONTENT_CONTROL_ID_MAX as af, CONTENT_CONTROL_PROPERTY_ORDER as ag, type ContentControlCheckbox as ah, type ContentControlCheckboxState as ai, type ContentControlDateFormat as aj, type ContentControlEntry as ak, type ContentControlListItem as al, type ContentControlProperties as am, type ContentTypeError as an, type ContentTypeIndex as ao, type ContentTypeRecords as ap, type CreateImageResourceCacheOptions as aq, DEFAULT_LIMITS as ar, DEFAULT_OOXML_PACKAGE_LIMITS as as, DEFAULT_ZIP_LIMITS as at, type DefaultRecord as au, HARD_CEILINGS as av, HYPERLINK_RELATIONSHIP_TYPE as aw, type HyperlinkKind as ax, type HyperlinkTarget as ay, IMAGE_RELATIONSHIP_TYPE as az, type OoxmlPackage as b, flattenContentControls as b$, type OoxmlContentControlTextNode as b0, type OoxmlContentControlUncheckedStateNode as b1, type OoxmlDocumentNode as b2, type OoxmlExternalTarget as b3, type OoxmlGenericExtensionAttribute as b4, type OoxmlHyperlinkNode as b5, type OoxmlInvariantIssueCode as b6, type OoxmlKnownNodeAttribute as b7, type OoxmlNamespaceBinding as b8, type OoxmlNodeIdentityRules as b9, XMLNS_NAMESPACE_URI as bA, XML_NAMESPACE_URI as bB, type XmlLimits as bC, type XmlNode as bD, type XmlRejection as bE, type XmlResult as bF, type ZipLimits as bG, type ZipReadResult as bH, type ZipRejection as bI, allocateContentControlId as bJ, asciiFold as bK, buildContentTypeIndex as bL, buildRelationshipSet as bM, childElements as bN, contentControlContentChildren as bO, contentControlContentNodeOf as bP, contentControlEndPropertiesNodeOf as bQ, contentControlLevelOf as bR, contentControlPropertiesNodeOf as bS, contentControlPropertiesOf as bT, contentControlTextOf as bU, contentControlsIn as bV, createImageResourceCache as bW, detectDuplicateNames as bX, extensionKey as bY, findContentControl as bZ, findElement as b_, type OoxmlPackageResult as ba, type OoxmlParagraphPropertiesNode as bb, type OoxmlPartMetadata as bc, type OoxmlReadRejection as bd, type OoxmlReadResult as be, type OoxmlRunNode as bf, type OoxmlRunPropertiesNode as bg, type OoxmlTabNode as bh, type OoxmlTextElementNode as bi, type OoxmlTextNode as bj, type OoxmlWmlValAttribute as bk, type OoxmlXmlSpaceAttribute as bl, type OverrideRecord as bm, type RelationshipError as bn, type RelationshipSetResult as bo, type RelationshipTargetResolver as bp, type ResolveResult as bq, type ResolvedRelationship as br, TABLE_BORDER_STYLES as bs, TREE_DOC_OP_KINDS as bt, type TabStopWrite as bu, type TargetMode as bv, type TreeDocOpKind as bw, type TreeOpEffect as bx, type ValidatedRasterHeader as by, WML_NAMESPACE_URI as bz, type OoxmlNodeId as c, hasBoundedSvgRoot as c0, hyperlinkAnchorOf as c1, hyperlinkRelationshipIdOf as c2, hyperlinkTargetOf as c3, imageResourceLookupFor as c4, isContentControlContentNode as c5, isContentControlNode as c6, isContentControlWrapper as c7, isContentRevisionKind as c8, isHyperlinkNode as c9, withPart as cA, writeOoxmlPackage as cB, writeZip as cC, isRangeMarkerKind as ca, isValidMime as cb, liveDrawingReferenceCount as cc, lockForbidsEdit as cd, lockForbidsRemoval as ce, normalizePartName as cf, orderedContentControlProperties as cg, parseContentControlId as ch, partNameKey as ci, projectDrawing as cj, readOnOffChild as ck, readOoxmlPackage as cl, readOoxmlPart as cm, readXml as cn, readZip as co, resolveContentControlLock as cp, resolveContentType as cq, resolveImageRelationship as cr, resolveInternalTarget as cs, resolveLimits as ct, resolveRelationship as cu, textContent as cv, validateExternalTarget as cw, validateGifHeader as cx, validateJpegHeader as cy, validatePngHeader as cz, type OoxmlGenericElementNode as d, type OoxmlPackageLimits as e, type OoxmlPackageRejection as f, type OoxmlElement as g, type OoxmlContentControlNode as h, type OoxmlContentControlContentNode as i, type OoxmlParagraphNode as j, type OoxmlNoteNode as k, type OoxmlContinuationSeparatorNode as l, type OoxmlEndnotesNode as m, type OoxmlFootnotesNode as n, type OoxmlNoteRefNode as o, type OoxmlNoteReferenceNode as p, type OoxmlSeparatorNode as q, type TreeOpRejection as r, type OoxmlProperty as s, type RenderableImageMime as t, type ImageWrapTarget as u, type DrawingPositionInput as v, type DrawingLocks as w, type ImageResourceState as x, type SupportedImageMime as y, type DrawingHorizontalReferenceFrame as z };