@docx-editor.dev/core 2.19.1 → 2.20.0

package/dist/{tree-op-types-DbdM7fJV.d.ts → types-barrel-CEOy-Jv0.d.ts}

@@ -1,59 +1,3 @@
-import { ParagraphTabStop } from './contracts/types.js';
-
-/**
- * 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.
  *
@@ -1573,159 +1517,6 @@ declare function projectDrawing(drawing: OoxmlDrawingNode, context: Readonly<{
     resolveStyleMatrixReference?: ShapeStyleMatrixResolver;
 }>): 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, 
-    /** Aborted when the owning lookup/session is disposed. */
-    signal?: AbortSignal): 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, 
-    /** Aborted when the owning lookup/session is disposed. */
-    signal?: AbortSignal): 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;
-    /** Horizontal physical density when bounded header metadata supplies it. */
-    readonly dpiX?: number;
-    /** Vertical physical density when bounded header metadata supplies it. */
-    readonly dpiY?: 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;
@@ -1931,6 +1722,962 @@ interface CommitTextFormFieldOp {
     readonly fieldNodeId: string;
 }
 
+/** The `w15` namespace: `commentsExtended.xml` — thread parent and resolved state. */
+declare const W15_NAMESPACE_URI = "http://schemas.microsoft.com/office/word/2012/wordml";
+/** A position in one story: a paragraph node id plus a UTF-16 offset inside it. */
+interface CommentPosition {
+    readonly paragraphId: string;
+    readonly offset: number;
+}
+/**
+ * Where a comment is anchored, as a range.
+ *
+ * `orphaned` records that the file did not give this comment a usable range — a reference with
+ * no range markers, or a start with no end. The comment is still listed, marked orphaned,
+ * rather than dropped: a reviewer's remark disappearing silently is worse than one that says
+ * it lost its text.
+ */
+interface CommentAnchor {
+    readonly commentId: string;
+    /** Canonical name of the part the range lives in, so a header comment is attributable. */
+    readonly partName: string;
+    readonly start: CommentPosition;
+    readonly end: CommentPosition;
+    readonly orphaned: boolean;
+}
+/** One comment as authored in `word/comments.xml`. */
+interface CommentRecord {
+    readonly id: string;
+    readonly author: string;
+    readonly initials?: string;
+    readonly date?: string;
+    /** Body paragraphs, as tree nodes, so the surface renders measured text rather than a string. */
+    readonly blocks: readonly OoxmlElement[];
+    /** `w14:paraId` of the last body paragraph — the key thread state is stored under. */
+    readonly paraId?: string;
+    /** `@w16cid:parentId` — the `w:id` of the comment this replies to, when the file names it. */
+    readonly parentCommentId?: string;
+}
+/** Thread state for one comment, read from `commentsExtended.xml`. */
+interface CommentThreadState {
+    /** `@w15:paraIdParent` — the comment this one replies to, absent for a top-level comment. */
+    readonly parentParaId?: string;
+    readonly done: boolean;
+}
+/**
+ * Every comment anchor in one story, in document order.
+ *
+ * Overlapping and nested ranges are supported because each anchor is resolved independently —
+ * Word produces both, and a model that assumed ranges nest cleanly would mis-anchor them.
+ *
+ * A start with no matching end anchors to the end of its own paragraph and is reported orphaned
+ * rather than guessed at: extending it to the next end marker would attach a reviewer's remark
+ * to text they never saw.
+ */
+declare function commentAnchorsOfStory(part: OoxmlPart): CommentAnchor[];
+/**
+ * The comments in `word/comments.xml`, in authored order.
+ *
+ * Every value here comes from a file an attacker fully controls, so nothing is interpreted:
+ * author, initials and date are carried verbatim for a surface that will set them as TEXT.
+ */
+declare function commentsOfPart(part: OoxmlPart): CommentRecord[];
+/**
+ * Thread state by `w14:paraId`, from `commentsExtended.xml`.
+ *
+ * The part being PRESENT is not evidence of threading. `issue-68-large-comments-suggestions.docx`
+ * ships it with 212 entries carrying `@w15:done` and not one `@w15:paraIdParent`, so it records
+ * resolved state for a flat list. Absent parent means top-level, and that is a fact about the
+ * file rather than a default this code chose.
+ */
+declare function threadStateOfPart(part: OoxmlPart): Map<string, CommentThreadState>;
+/**
+ * Whether the package holds any `w:comment` record — the cheap gate before a reap.
+ *
+ * Overflow cannot prove the package is comment-free, so it returns true and the reap still
+ * runs rather than skipping cleanup.
+ */
+declare function hasAnyComment(pkg: OoxmlPackage): boolean;
+
+/** A position in the model offset space of one story. */
+interface ReviewPosition {
+    readonly paragraphId: string;
+    readonly offset: number;
+}
+/** Where an item is anchored: a range in one story. */
+interface ReviewRange {
+    readonly partName: string;
+    readonly start: ReviewPosition;
+    readonly end: ReviewPosition;
+}
+/**
+ * What kind of decision a revision card represents.
+ *
+ * Wider than the four content wrappers, because a reviewer has to be shown every pending
+ * decision, including the ones that decorate no characters. A card the surface cannot show is
+ * a change the reviewer never learns about — and `acceptAllRevisions` refuses if ANY revision
+ * in the document is one the engine cannot resolve, so an invisible one makes Accept All fail
+ * for a reason nothing on screen explains.
+ */
+type ReviewRevisionKind = 'insert' | 'delete'
+/**
+ * A deletion and an insertion that are one edit: text typed over a selection.
+ *
+ * Word shows these as a single `Replaced "x" with "y"` card, and resolving one half
+ * without the other is never what the reviewer meant — accepting the deletion alone
+ * leaves the replacement text unproposed, rejecting it alone leaves both.
+ */
+ | 'replace' | 'moveFrom' | 'moveTo'
+/** `w:rPrChange` / `w:pPrChange` — the words are unchanged, their formatting is not. */
+ | 'format'
+/** `w:pPr/w:rPr/w:ins|w:del` — a paragraph split or merge. */
+ | 'paragraphMark'
+/** A row, cell, section or grid revision. Supported row revisions are resolvable. */
+ | 'structural';
+/**
+ * One tracked change as a review card.
+ *
+ * Keyed per DECISION rather than per site: a revision spanning three ranges is one card, because
+ * accepting it accepts all three.
+ */
+interface ReviewRevisionItem {
+    readonly kind: 'revision';
+    /** Stable across renders and unique per DECISION, not per site. */
+    readonly id: string;
+    /** The payload `acceptRevision` / `rejectRevision` take. */
+    readonly address: RevisionAddress;
+    /**
+     * EVERY address this decision covers, `address` first.
+     *
+     * More than one only for a replacement, whose halves a foreign editor may have written
+     * as two independent revisions. Accept and reject walk all of them in one transaction:
+     * resolving one half and leaving the other is a state no reviewer asked for.
+     */
+    readonly addresses: readonly RevisionAddress[];
+    /** The words a replacement removes. Empty for every other kind. */
+    readonly replacedText: string;
+    readonly revisionKind: ReviewRevisionKind;
+    /** OOXML property-change element, used to resolve independently numbered formatting kinds. */
+    readonly formattingKind?: string;
+    /** Changed direct formatting values, ready for localized review summaries. */
+    readonly formattingChanges?: readonly {
+        readonly property: 'bold' | 'italic' | 'underline' | 'strike' | 'fontFamily' | 'fontSize' | 'color' | 'alignment' | 'leftIndent' | 'rightIndent' | 'firstLineIndent' | 'hangingIndent' | 'spaceBefore' | 'spaceAfter';
+        /** New direct value; null means inherit. Sizes and distances are in points. */
+        readonly value: string | null;
+    }[];
+    /** Newly applied proofing language codes in a tracked formatting change. */
+    readonly formattingLanguages?: readonly string[];
+    /**
+     * WHICH decision a `paragraphMark` records, absent for every other kind.
+     *
+     * `EG_ParaRPrTrackChanges` is `ins? del? moveFrom? moveTo?`, and the four say opposite
+     * things about one break. Without this a card called a deleted break an inserted one, which
+     * is the reverse of what Accept on that card does.
+     */
+    readonly markDirection?: 'insert' | 'delete' | 'moveFrom' | 'moveTo';
+    readonly author: string;
+    readonly date?: string;
+    /** Text the revision covers, for the card summary. Empty for changes with no characters. */
+    readonly text: string;
+    /** Every site this decision touches, in document order. */
+    readonly ranges: readonly ReviewRange[];
+    /**
+     * How deeply this change is NESTED inside other changes, 0 for an unenclosed one.
+     *
+     * `w:ins` wrapping `w:del` is content one reviewer added and another struck. Both stay
+     * pending, so both are cards, over one identical range — and a range then cannot say which
+     * change a caret is in. Word treats the innermost as the operative one, so it wins the caret
+     * and the change enclosing it stays listed and reachable.
+     */
+    readonly nesting: number;
+    /**
+     * How many leading `ranges` are the STRUCK half of a replacement.
+     *
+     * A replacement's card is one decision but its ranges are two colours — red over what is
+     * going, green over what takes its place. ABSENT when the halves do not split at a single
+     * point, which is what a file recording both under one revision id can produce; a surface
+     * then has no basis for two colours and should paint one neutral band rather than guess.
+     */
+    readonly replacedRangeCount?: number;
+    /**
+     * True when the engine cannot resolve this kind, so accept and reject must not be offered.
+     *
+     * Derived by the DERIVATION rather than from a caller-supplied predicate: the refusal list
+     * is internal, and a surface asked to compute it would have to guess. A card that offers a
+     * button the engine will refuse is worse than one that explains why it cannot.
+     */
+    readonly readOnly: boolean;
+    /** The other half of a move, or the other side of a delete/insert replacement. */
+    readonly pairedWith?: string;
+    /**
+     * Comments answering this change, in document order.
+     *
+     * A reply to a tracked change IS a comment: `w:ins` and `w:del` carry no body, so the text
+     * is written as a comment over the revision's own range and the range is what links them.
+     */
+    readonly replyIds: readonly string[];
+}
+/**
+ * One comment as a review card. A reply carries `parentId`; OOXML gives replies no separate
+ * element, so threads are reconstructed from that link.
+ */
+interface ReviewCommentItem {
+    readonly kind: 'comment';
+    readonly id: string;
+    readonly comment: CommentRecord;
+    readonly range: ReviewRange | null;
+    readonly resolved: boolean;
+    /** The comment this replies to, absent for a top-level comment. */
+    readonly parentId?: string;
+    /** The REVISION this comment answers, when it covers exactly that change's characters. */
+    readonly parentRevisionId?: string;
+    /** Replies to this comment, in document order. Empty for a reply or a childless comment. */
+    readonly replyIds: readonly string[];
+    /** True when the file gave this comment no usable range. */
+    readonly orphaned: boolean;
+}
+/**
+ * A card contributed by a recognized custom node (`defineCustomNode` with a `reviewCard`
+ * hook), anchored at the node's range.
+ *
+ * Informational, never resolvable: there is nothing to accept or reject, so the engine
+ * refuses those verbs on it. `title` and `detail` are HOST-authored (the definition's hook
+ * produced them), but `attrs` and `text` originate in a file an attacker controls — a
+ * surface renders every one of these as text, never markup.
+ */
+interface ReviewCustomItem {
+    readonly kind: 'custom';
+    /** The SDT node's stable id in the canonical tree. */
+    readonly id: string;
+    /** The definition's `name`. */
+    readonly name: string;
+    /** The raw `w:tag` the node was recognized from. Untrusted input. */
+    readonly tag: string;
+    /** Attrs decoded from the tag, after the definition's recognition hook. Untrusted input. */
+    readonly attrs: Readonly<Record<string, string>>;
+    /** The SDT's literal content text. Untrusted input. */
+    readonly text: string;
+    /**
+     * The payload the node's control binds to, after the definition validated it.
+     *
+     * Undefined when the node carries none or the payload did not match — see the pro package's
+     * `RecognizedCustomNode.data`, which this is carried from.
+     */
+    readonly data?: unknown;
+    /**
+     * Whether this node asked for a sidebar card.
+     *
+     * False for a definition with no `reviewCard`: the item exists so the chip's own surfaces can
+     * read `attrs`, `text` and `data` off it, and the rail leaves it out. A surface listing cards
+     * filters on this rather than on an empty `title`.
+     */
+    readonly carded: boolean;
+    /** Card title, from the definition's `reviewCard` hook. Empty when `carded` is false. */
+    readonly title: string;
+    /** Card body, from the definition's `reviewCard` hook. */
+    readonly detail?: string;
+    /**
+     * Glyph for this node in the collapsed rail, as an SVG path in a `0 -960 960 960` viewBox.
+     *
+     * A PATH rather than a rendered node because this item crosses core, which is DOM-free and
+     * React-free — the same reason `title` and `detail` are strings. A host that wants arbitrary
+     * markup overrides the `Markers` part's `icon` instead, which lives in the adapter where JSX
+     * belongs. Absent falls back to the generic custom-node glyph.
+     *
+     * HOST-AUTHORED, never file data: it is interpolated into an SVG `d` attribute, and a path
+     * taken from a document would be attacker-controlled markup.
+     */
+    readonly icon?: string;
+    readonly range: ReviewRange | null;
+}
+/**
+ * One pending decision in the review queue: a tracked change, a comment thread, or a pro
+ * custom-node card. Discriminate on `kind`.
+ *
+ * The store's own derivation (`collectReviewItems`) only ever produces the first two; the
+ * `kind: 'custom'` card is contributed by the pro review module, which recognizes the node.
+ */
+type ReviewItem = ReviewRevisionItem | ReviewCommentItem | ReviewCustomItem;
+/** What the review queue derivation reads: one story part plus its comment parts. */
+interface ReviewModelInput {
+    /** The story the ranges live in — the main document, a header, a note. */
+    readonly storyPart: OoxmlPart;
+    /**
+     * Header/footer story parts, in section order. Their revisions and comment anchors join
+     * the queue: a tracked change in a header is a pending decision like any other, and a
+     * queue that only walked the body silently hid it from the rail AND from Accept All.
+     */
+    readonly furnitureParts?: readonly OoxmlPart[] | undefined;
+    /** `word/comments.xml`, absent when the package has none. */
+    readonly commentsPart?: OoxmlPart | undefined;
+    /** `word/commentsExtended.xml`, absent when the package has none. */
+    readonly commentsExtendedPart?: OoxmlPart | undefined;
+    /**
+     * Custom node definitions from the module registry, forwarded OPAQUELY.
+     *
+     * Core carries them the way the registry does — as unknowns — so the definition shape
+     * stays a capability-package concern. The pro derivation narrows them and contributes
+     * `kind: 'custom'` cards for definitions that opted in.
+     */
+    readonly customNodes?: readonly unknown[] | undefined;
+    /**
+     * Where a capability package reports a node it could not read. Supplied per editor, so a page
+     * with two of them keeps their diagnostics apart.
+     */
+    readonly reportCustomNodeDiagnostic?: ((diagnostic: unknown) => void) | undefined;
+    /**
+     * The payload each of the story's controls binds to, keyed by the control's node id.
+     *
+     * Resolved by the ENGINE and handed over, because a payload lives in a customXml data part
+     * and a derivation that only receives story parts has no way to reach one. Untrusted file
+     * input on both members; a capability package validates it against whatever shape it
+     * declared before handing it to a host.
+     */
+    readonly customNodePayloads?: ReadonlyMap<string, {
+        readonly nodeId: string;
+        readonly label: string;
+        readonly data: string;
+    }> | undefined;
+}
+/** The stable key a surface uses for the active item and for a React list. */
+declare function reviewItemKey(item: ReviewItem): string;
+/** Every range a decision touches. One card can cover several, in different paragraphs. */
+declare function reviewItemRanges(item: ReviewItem): readonly ReviewRange[];
+/** The first range of an item, in authored order, or null when it has none. */
+declare function firstReviewRange(item: ReviewItem): ReviewRange | null;
+/**
+ * A single comparable number for document order.
+ *
+ * Paragraph index dominates offset, so a revision spanning paragraphs still sorts by where it
+ * STARTS. An item with no resolvable range sorts last rather than to position zero, which is
+ * where an orphan used to land — tearing an orphaned reply out of its own thread.
+ */
+declare function reviewItemPositionRank(item: ReviewItem, order: ReadonlyMap<string, number>): number;
+/**
+ * Every item covering a position, innermost first.
+ *
+ * Returning the whole stack rather than one winner is what lets a surface offer cycling, a
+ * stacked card, or a "1 of 3" affordance. A comment wrapping a revision used to be unreachable
+ * because only the tightest range was ever returned.
+ */
+declare function reviewItemsAt(items: readonly ReviewItem[], position: ReviewPosition, order: ReadonlyMap<string, number>): ReviewItem[];
+/**
+ * The item the caret is in, or null.
+ *
+ * A resolved comment never activates: a settled thread must not reopen itself as the reviewer
+ * types near it.
+ *
+ * A REPLY resolves to the thread it belongs to. A reply is anchored over its parent's range,
+ * so both cover the caret — and the reply, being newer, wins the innermost test. It is not a
+ * card of its own (it renders inside its parent's), so the thread would have gone active with
+ * nothing on screen showing it: the reply box vanished from a comment the moment somebody
+ * replied to it.
+ */
+declare function activeReviewItem(items: readonly ReviewItem[], position: ReviewPosition, order: ReadonlyMap<string, number>): ReviewItem | null;
+/**
+ * Walk a reply up to the card that heads its thread. Guarded against a cyclic file.
+ *
+ * The head is not always a comment. A reply to a tracked change renders inside the REVISION's
+ * card, so resolving it to itself opened an item nothing on screen was drawing — the reply box
+ * vanished the moment somebody answered a change.
+ *
+ * EXPORTED because the paginated surface answers "which card is open" itself, against its own
+ * dismissed-key state, rather than through {@link activeReviewItem}. Two copies of the
+ * innermost-wins rule was survivable while a reply could only be a comment — the parent came
+ * first in `comments.xml` order and won the tie by accident. It stopped being survivable the
+ * moment a reply could answer a revision, which outranks it outright.
+ */
+declare function reviewThreadRootOf(items: readonly ReviewItem[], comment: ReviewCommentItem): ReviewItem;
+
+/** A canonical review decision. Keys are valid only in the open document. @public */
+interface RevisionBatchEntry {
+    readonly key: string;
+    readonly author: string;
+    readonly partName: string;
+    readonly revisionKind: ReviewRevisionItem['revisionKind'];
+}
+/** Why a requested decision remains pending. @public */
+type RevisionBatchSkipReason = 'unsupported-revision' | 'incomplete-group' | 'unknown-revision';
+/** Outcome of one selected-set decision. Counts refer to review decisions, not XML markers. @public */
+interface RevisionBatchResult {
+    readonly resolved: readonly RevisionBatchEntry[];
+    readonly skipped: readonly {
+        readonly key: string;
+        readonly reason: RevisionBatchSkipReason;
+        readonly revision?: RevisionBatchEntry;
+    }[];
+    /** All pending decisions in the addressed scope, including excluded and unsupported changes. */
+    readonly remaining: number;
+}
+/** @internal Pure preflight; callers commit its operations through their normal write guards. */
+declare function planRevisionBatch(part: OoxmlPart, action: 'accept' | 'reject', keys?: readonly string[], scopeRoot?: OoxmlNode): {
+    ops: readonly TreeDocOp[];
+    result: RevisionBatchResult;
+};
+
+/**
+ * Shared types for the `@docx-editor.dev/core` contract. Type-only, zero runtime.
+ *
+ * `@docx-editor.dev/core/contracts/types` re-exports this module verbatim, through
+ * `types-barrel.ts`. There is no `@docx-editor.dev/core/types` subpath.
+ */
+/** Which paragraph-level reads the selection disagrees about. @public */
+interface ParagraphDisagreements {
+    readonly alignment: boolean;
+    readonly spaceBeforePt: boolean;
+    readonly spaceAfterPt: boolean;
+    readonly lineSpacing: boolean;
+    readonly tabStops: boolean;
+}
+/**
+ * The five paragraph flags a Paragraph dialog shows as checkboxes.
+ *
+ * `contextualSpacing` is Word's "Don't add space between paragraphs of the same style";
+ * the rest are its Pagination block. `null` means the selection disagrees.
+ *
+ * @public
+ */
+interface ParagraphFlags {
+    readonly contextualSpacing: boolean | null;
+    readonly keepNext: boolean | null;
+    readonly keepLines: boolean | null;
+    readonly widowControl: boolean | null;
+    readonly pageBreakBefore: boolean | null;
+}
+/**
+ * Every field of the Paragraph dialog, as `setParagraphFormat` takes it.
+ *
+ * An omitted field is left as authored. `null` REMOVES a setting so the style supplies it
+ * again — not the same as a zero, which blocks the cascade.
+ *
+ * @public
+ */
+interface ParagraphFormatCommand {
+    alignment?: 'left' | 'center' | 'right' | 'justify';
+    spaceBeforePt?: number | null;
+    spaceAfterPt?: number | null;
+    lineSpacing?: {
+        rule: 'multiple' | 'exact' | 'atLeast';
+        value: number;
+    } | null;
+    indentLeftTwips?: number | null;
+    indentRightTwips?: number | null;
+    /** ONE signed first-line offset: negative is a hanging indent. */
+    indentFirstLineTwips?: number | null;
+    contextualSpacing?: boolean;
+    keepNext?: boolean;
+    keepLines?: boolean;
+    widowControl?: boolean;
+    pageBreakBefore?: boolean;
+    /**
+     * Replace the paragraph's custom tab stops. An empty list CLEARS them, which is what
+     * "Clear All" does; omit the field to leave them as authored.
+     */
+    tabStops?: readonly ParagraphTabStop[];
+}
+/** One custom tab stop, as a command states it. @public */
+interface ParagraphTabStop {
+    readonly positionTwips: number;
+    readonly alignment: 'left' | 'center' | 'right' | 'decimal' | 'bar';
+    readonly leader?: 'none' | 'dot' | 'hyphen' | 'underscore' | 'heavy' | 'middleDot';
+}
+/** Ownership token for one retained selection highlight. @public */
+type SelectionPin = symbol;
+/**
+ * The LLM- and JSON-facing address for a piece of a document.
+ *
+ * `paraId` is the 8-hex `w14:paraId`, matched case-insensitively. `search` is a
+ * phrase that must match EXACTLY ONCE inside that paragraph; ambiguous or
+ * missing matches fail with `'ambiguous'` / `'notFound'` rather than falling
+ * back to first-match.
+ *
+ * Offset-based addressing was tried and abandoned: an agent cannot compute a
+ * character offset it has not seen, and offsets do not survive concurrent
+ * edits. Do not reintroduce `{ blockId, offset }`.
+ */
+interface DocAnchor {
+    paraId: string;
+    search?: string;
+    /** Opt-in disambiguation. Omit to require uniqueness. */
+    occurrence?: number;
+}
+/** Structural addressing for content the paraId map cannot reach. */
+interface DocLocation {
+    container: ContainerRef;
+    /** Block indices, descending into tables and content controls. */
+    path: number[];
+    offset?: number;
+}
+/**
+ * Which STORY a location belongs to.
+ *
+ * The body is one container; every header, footer and note is another. A path alone is
+ * ambiguous without it, because block index 0 exists in every story a document has.
+ */
+type ContainerRef = {
+    part: 'body';
+} | {
+    part: 'header' | 'footer';
+    rId: string;
+} | {
+    part: 'footnote' | 'endnote';
+    noteId: number;
+};
+/**
+ * Anything an operation can be pointed at: a paragraph-relative {@link DocAnchor}, a structural
+ * {@link DocLocation}, or a {@link DocRange} spanning two of them.
+ */
+type DocTarget = DocAnchor | DocLocation | DocRange;
+/** A span between two positions. The endpoints may be addressed either way, independently. */
+interface DocRange {
+    from: DocAnchor | DocLocation;
+    to: DocAnchor | DocLocation;
+}
+/**
+ * Every write returns this rather than `boolean`.
+ *
+ * A bare boolean cannot distinguish "no-op" from "target not found" from
+ * "content control is locked", and the editor layer already throws eight
+ * distinct ContentControl error classes that a boolean would flatten.
+ */
+type ExecResult = {
+    ok: true;
+    changed: boolean;
+    revisions?: RevisionBatchResult;
+} | {
+    ok: false;
+    code: ExecErrorCode;
+    reason: string;
+    target?: DocTarget;
+    revisions?: RevisionBatchResult;
+};
+/**
+ * Why a write was refused, as a value to branch on.
+ *
+ * Deliberately finer-grained than a boolean: "no-op", "target not found" and "content control is
+ * locked" are different outcomes, and a caller retrying the first should not retry the third.
+ */
+type ExecErrorCode = 'notFound' | 'ambiguous' | 'locked' | 'bound' | 'typeMismatch' | 'kindMismatch' | 'outOfBounds' | 'unsupported' | 'invalidArgs';
+/**
+ * A parsed .docx.
+ *
+ * NOT JSON-round-trippable: it holds `Map`s and `Date`s, plus an internal
+ * side-table of verbatim XML used for lossless round-tripping. Use `toJSON` /
+ * `fromJSON` before sending it over JSON-RPC or handing it to a model.
+ */
+interface DocxDocument {
+    readonly body: DocumentBody;
+    readonly styles: StyleDefinitions;
+    readonly theme?: Theme;
+    readonly comments: readonly DocComment[];
+    readonly revisions: readonly Revision[];
+}
+/** The main story: its blocks in reading order, plus the sections derived from them. */
+interface DocumentBody {
+    readonly content: readonly Block[];
+    /**
+     * Derived, not stored: recomputed on read from section-break markers and
+     * section inheritance. Never treat it as a spreadable field.
+     */
+    readonly sections: readonly Section[];
+}
+/** The JSON-safe projection of a document. */
+interface DocxDocumentJSON {
+    readonly [key: string]: unknown;
+}
+/** One section: the page it lays out on, and the header/footer stories it declares. */
+interface Section {
+    readonly properties: SectionProperties;
+    readonly headers: HeaderFooterSet;
+    readonly footers: HeaderFooterSet;
+}
+/**
+ * A section's three header (or footer) variants, each a relationship id.
+ *
+ * All optional: a variant a section does not declare inherits the previous section's, and one
+ * absent everywhere means the document simply has none.
+ */
+interface HeaderFooterSet {
+    readonly default?: string;
+    readonly first?: string;
+    readonly even?: string;
+}
+/** Anything that can sit at block level in a story. Discriminate on `kind`. */
+type Block = Paragraph | Table | ContentControl;
+/** One paragraph: its runs, the style it names, and its list membership. */
+interface Paragraph {
+    readonly kind: 'paragraph';
+    /** `w14:paraId`. The stable handle `DocAnchor` addresses. */
+    readonly paraId?: string;
+    readonly runs: readonly Run[];
+    readonly styleId?: string;
+    readonly numbering?: NumberingRef;
+}
+/** A stretch of text sharing one set of character properties. */
+interface Run {
+    readonly text: string;
+    readonly formatting?: RunFormatting;
+    /** Set when the run carries a tracked change. Unique only within its part. */
+    readonly revisionId?: number;
+}
+/**
+ * Character formatting, and — at selection level — the paragraph properties a toolbar reads
+ * alongside it.
+ *
+ * One type serves both roles so a toolbar reads alignment, style and script state from the same
+ * object as bold and italic. On a {@link Run} the selection-level fields stay absent: a run has
+ * no alignment or paragraph style of its own.
+ */
+interface RunFormatting {
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+    readonly strike?: boolean;
+    readonly color?: ColorValue;
+    readonly highlight?: string;
+    readonly fontFamily?: string;
+    readonly fontSizePt?: number;
+    readonly superscript?: boolean;
+    readonly subscript?: boolean;
+    /** Paragraph alignment at the selection. `both` is OOXML's spelling of justify. */
+    readonly alignment?: 'left' | 'center' | 'right' | 'both';
+    /** Paragraph style id (`w:pStyle`) at the selection. */
+    readonly styleId?: string;
+    /**
+     * Line spacing at the selection, in the unit its rule implies — LINES for `multiple`,
+     * points for `exact` and `atLeast`. The same vocabulary `setLineSpacing` takes, so a
+     * control can show what it reads and send back what it shows. Absent when the
+     * selection's paragraphs disagree or state no line spacing.
+     */
+    readonly lineSpacing?: {
+        readonly rule: 'multiple' | 'exact' | 'atLeast';
+        readonly value: number;
+    };
+    /**
+     * Space above and below the paragraph at the selection, in points.
+     *
+     * The measurement the cascade STATES — `w:docDefaults`, the style chain and direct
+     * formatting resolved together — not the gap the page finally draws. The two differ for a
+     * paragraph carrying `w:beforeAutospacing`, where Word substitutes its own value and
+     * ignores the measurement, and again where two paragraphs collapse their adjacent spacing.
+     * Absent when the selection's paragraphs disagree or no level states it.
+     */
+    readonly spaceBeforePt?: number;
+    readonly spaceAfterPt?: number;
+    /**
+     * The paragraph flags the Paragraph dialog shows as checkboxes.
+     *
+     * Each is `true`, `false`, or `null` when the selection's paragraphs disagree — a
+     * checkbox needs all three. Read through the cascade, so a flag a STYLE sets reads as on,
+     * which is what the box has to show over a paragraph the page is visibly keeping with the
+     * next. Absent on a `Run`, like every other selection-level field here.
+     */
+    readonly paragraphFlags?: ParagraphFlags;
+    /**
+     * Which paragraph-level fields above are absent because the selection DISAGREES, as
+     * opposed to because nothing states them.
+     *
+     * A `null`/absent value alone cannot tell those apart, and both readings have shipped as
+     * bugs: a disagreement rendered as a concrete value is uncorrectable, because the value
+     * that would fix it is the one already on screen; an absent value rendered as "mixed"
+     * tells a single paragraph it disagrees with itself.
+     */
+    readonly disagrees?: ParagraphDisagreements;
+    /**
+     * The paragraph's custom tab stops at the selection, cascade included. Absent when the
+     * selection disagrees or the paragraphs have none.
+     */
+    readonly tabStops?: readonly ParagraphTabStop[];
+    /**
+     * The EFFECTIVE paragraph indent at the selection — cascade and numbering merge
+     * included, so a numbered item that authors no `w:ind` reports the indent its list
+     * definition gives it. Absent when nothing is loaded, or when the selection is inside a
+     * table (see {@link IndentFormatting}).
+     */
+    readonly indent?: IndentFormatting;
+}
+/**
+ * Indent at the selection, in twips.
+ *
+ * Unlike every other field here, this does NOT go absent when the selection's paragraphs
+ * disagree. A ruler has to draw its handles somewhere, and Word draws them at the FIRST
+ * selected paragraph's values — Select All is the commonest indent gesture, and hiding the
+ * handles for it would be worse than showing one paragraph's truth. The values are
+ * therefore always the first touched paragraph's, and {@link mixed} records per field
+ * whether the rest agree.
+ *
+ * `firstLine` is ONE SIGNED offset: negative is a hanging indent. OOXML spells it as two
+ * mutually exclusive attributes and this collapses them hanging-wins (§17.3.1.12), which
+ * is the model Word itself keeps.
+ *
+ * Absent inside a table. The value would be correct there, but it is measured from the
+ * cell's content edge while a ruler is drawn against the page's margin, and the ruler does
+ * not know the cell.
+ */
+interface IndentFormatting {
+    /** Left indent, signed. Negative pulls text into the margin, as Word allows. */
+    readonly left: number;
+    /** Right indent, signed. */
+    readonly right: number;
+    /** First-line offset from {@link left}, signed. Negative is a hanging indent. */
+    readonly firstLine: number;
+    /** Per field, whether the selection's paragraphs disagree about it. */
+    readonly mixed: {
+        readonly left: boolean;
+        readonly right: boolean;
+        readonly firstLine: boolean;
+    };
+}
+/** A table: its rows, and the table style they resolve through. */
+interface Table {
+    readonly kind: 'table';
+    readonly rows: readonly TableRow[];
+    readonly styleId?: string;
+}
+/** One table row. Cell count may vary between rows: `colSpan` and vertical merges reshape it. */
+interface TableRow {
+    readonly cells: readonly TableCell[];
+}
+/**
+ * One cell. Its `content` is ordinary blocks, so a cell may hold paragraphs, nested tables and
+ * content controls alike.
+ */
+interface TableCell {
+    readonly content: readonly Block[];
+    /** Vertical merge span. Absent means 1. */
+    readonly rowSpan?: number;
+    /** `w:gridSpan`. Absent means 1. */
+    readonly colSpan?: number;
+}
+/** Structured document tag (`w:sdt`). */
+interface ContentControl {
+    readonly kind: 'contentControl';
+    readonly id: string;
+    readonly tag?: string;
+    readonly alias?: string;
+    readonly controlType: ContentControlType;
+    readonly locked?: boolean;
+    readonly content: readonly Block[];
+}
+/** Which kind of control a `w:sdt` is, and therefore what a value written into it must be. */
+type ContentControlType = 'richText' | 'plainText' | 'checkbox' | 'dropdown' | 'comboBox' | 'date' | 'picture' | 'repeatingSection';
+/**
+ * The control kinds an insertion can author.
+ *
+ * A NARROWING of {@link ContentControlType}, not a separate vocabulary: a kind read off an
+ * existing control can be handed straight back to `insertContentControl`. Three kinds are
+ * absent because an insertion would have to invent what they carry — a checkbox needs its two
+ * declared glyph states, a picture needs an image part, and a repeating section is a container
+ * whose items have their own verbs. Reading still answers the wider type; a document may hold
+ * kinds this cannot create.
+ *
+ * `dropDownList` is the same kind as `dropdown`, spelt as OOXML spells it. Both are accepted,
+ * so a type read off a control can be handed back without translating it — and the OOXML
+ * spelling is the one the automation protocol takes, so a caller who uses both surfaces can
+ * write that one everywhere.
+ */
+type InsertableContentControlType = Extract<ContentControlType, 'richText' | 'plainText' | 'dropdown' | 'comboBox' | 'date'> | 'dropDownList';
+/**
+ * Narrows a content-control query. Fields combine with AND; an empty filter matches every
+ * control.
+ */
+interface ContentControlFilter {
+    readonly tag?: string;
+    readonly alias?: string;
+    readonly controlType?: ContentControlType;
+}
+/**
+ * A position in one story: a paragraph and a UTF-16 offset inside it.
+ *
+ * The same offset space the ops and the caret use, so an anchor read here can be handed
+ * straight back to a selection without re-deriving anything.
+ */
+interface DocAnchorRange {
+    /** Canonical part name of the story the range lives in, e.g. `/word/document.xml`. */
+    readonly part: string;
+    readonly startParagraphId: string;
+    readonly startOffset: number;
+    /** May sit in a later paragraph: the range markers are independent elements. */
+    readonly endParagraphId: string;
+    readonly endOffset: number;
+}
+/**
+ * One comment or reply, as `comments.xml` records it.
+ *
+ * A reply is a comment with a `parentId`; OOXML gives replies no separate element, so the thread
+ * is reconstructed from that link rather than from nesting.
+ */
+interface DocComment {
+    readonly id: string;
+    readonly author: string;
+    /**
+     * OPTIONAL, because `CT_Comment` makes `@w:date` optional and files omit it. A comment
+     * with no date is a comment, not a defect, and fabricating one is a content change.
+     */
+    readonly date?: string;
+    readonly text: string;
+    readonly parentId?: string;
+    readonly resolved?: boolean;
+    /**
+     * Where the comment is anchored, absent when the file gave it no usable range.
+     *
+     * A comment lives in `comments.xml` and is placed by markers in a STORY, so the story is
+     * part of the address: a comment anchored in a header belongs to a part the body never saw.
+     */
+    readonly anchor?: DocAnchorRange;
+    /**
+     * True when the file gave this comment no usable range — a reference with no markers, or a
+     * start with no end. Reported rather than dropped: a reviewer's remark vanishing silently
+     * is worse than one that says it lost its text.
+     */
+    readonly orphaned?: boolean;
+}
+/**
+ * What kind of decision a revision represents.
+ *
+ * Wider than insert/delete/format, and it has to be. `w:moveFrom`/`w:moveTo` are not a
+ * deletion and an insertion — resolving one half alone duplicates or loses the content;
+ * `w:pPr/w:rPr/w:ins|w:del` decorates no characters at all and merges paragraphs when
+ * resolved; a row or cell revision is structural. A reviewer shown only three kinds is a
+ * reviewer who never learns about the rest.
+ */
+type RevisionType = 'insert' | 'delete'
+/** A deletion and an insertion that are one edit: text typed over a selection. */
+ | 'replace' | 'moveFrom' | 'moveTo'
+/** `w:rPrChange` / `w:pPrChange` — the words are unchanged, their formatting is not. */
+ | 'format'
+/** `w:pPr/w:rPr/w:ins|w:del` — a paragraph split or merge. */
+ | 'paragraphMark'
+/** A row, cell, section or grid revision. */
+ | 'structural';
+/**
+ * One tracked change.
+ *
+ * Addressing needs BOTH `id` and `part`: `@w:id` is unique only within a part, so an id alone
+ * names two revisions in any package that has a header or a comments part.
+ */
+interface Revision {
+    /** Numeric, and unique only WITHIN a part. Pair with `part` to address one. */
+    readonly id: number;
+    readonly type: RevisionType;
+    readonly author: string;
+    /**
+     * OPTIONAL. `CT_TrackChange` requires `@w:id` and `@w:author` and makes `@w:date`
+     * optional, and producers that omit it are ordinary. Requiring it here forced either a
+     * fabricated date — a content change — or dropping the revision from the list.
+     */
+    readonly date?: string;
+    /**
+     * REQUIRED, and a canonical PART NAME rather than a three-value enum.
+     *
+     * `@w:id` is unique only within a part, so an address without one names two revisions in a
+     * package that has both. The enum could not express the parts revisions actually occur in:
+     * `header3.xml`, `footer1.xml`, `comments.xml`, and `styles.xml`, which carries
+     * `w:pPrChange` inside style definitions with ids that collide with `document.xml`.
+     */
+    readonly part: string;
+}
+/** `w:sectPr`: the page a section lays out on. Twips throughout, as the file stores them. */
+interface SectionProperties {
+    readonly pageSize: {
+        widthTwips: number;
+        heightTwips: number;
+    };
+    readonly margins: PageMargins;
+    readonly columns?: {
+        count: number;
+        gapTwips: number;
+    };
+    /** `w:titlePg` — whether the section's first page takes the `first` header/footer variant. */
+    readonly titlePage?: boolean;
+}
+/** Page margins in twips. */
+interface PageMargins {
+    readonly topTwips: number;
+    readonly rightTwips: number;
+    readonly bottomTwips: number;
+    readonly leftTwips: number;
+}
+/**
+ * `styles.xml`, split by the three style families that address separately.
+ *
+ * Keyed by style ID rather than by the name a reader sees, because the ID is what a paragraph or
+ * run actually references.
+ */
+interface StyleDefinitions {
+    readonly paragraph: ReadonlyMap<string, StyleDefinition>;
+    readonly character: ReadonlyMap<string, StyleDefinition>;
+    readonly table: ReadonlyMap<string, StyleDefinition>;
+}
+/** One style: the ID content references, the name a reader sees, and its inheritance link. */
+interface StyleDefinition {
+    readonly id: string;
+    readonly name: string;
+    /** `w:basedOn` — the style this one inherits from. Absent at the root of a chain. */
+    readonly basedOn?: string;
+}
+/** A paragraph's list membership: which `numbering.xml` definition, and at which level. */
+interface NumberingRef {
+    readonly numId: string;
+    /** Zero-based. OOXML numbering has nine levels, 0 through 8. */
+    readonly level: number;
+}
+/**
+ * A colour as the FILE expresses it, not as a resolved RGB string.
+ *
+ * A theme colour stays a theme reference — slot plus tint or shade — so that changing the theme
+ * repaints the document the way Word does. Flattening to hex at read time would freeze the
+ * resolved value and break that link. `auto` is Word's "let the renderer decide", usually black
+ * on white.
+ */
+type ColorValue = {
+    readonly kind: 'hex';
+    readonly value: string;
+} | {
+    readonly kind: 'theme';
+    readonly slot: string;
+    readonly tint?: number;
+    readonly shade?: number;
+} | {
+    readonly kind: 'auto';
+};
+/** `theme1.xml` — what a {@link ColorValue} of kind `theme` resolves against. */
+interface Theme {
+    readonly colorScheme: ThemeColorScheme;
+    readonly fontScheme?: Record<string, string>;
+}
+/** Theme colour slots (`accent1`, `dk1`, `lt2`, …) to hex. */
+type ThemeColorScheme = Readonly<Record<string, string>>;
+/** A watermark, which OOXML expresses as either text or an image — never both meaningfully. */
+interface Watermark {
+    readonly text?: string;
+    readonly imageData?: Uint8Array;
+}
+/** A size in EMUs, the unit DrawingML stores extents in. 914400 EMU = 1 inch. */
+interface Extent {
+    readonly widthEmu: number;
+    readonly heightEmu: number;
+}
+/** A font the document names, and whether its bytes travel inside the package. */
+interface FontDefinition {
+    readonly family: string;
+    readonly embedded: boolean;
+}
+/** An axis-aligned rectangle in points, the unit layout works in throughout. */
+interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** A position in points. */
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** What every subscription returns. Calling it twice is safe. */
+type Unsubscribe = () => void;
+
 /** 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. */
@@ -2373,10 +3120,14 @@ type TreeDocOp = SetFieldCodeOp | {
      * changes made one decision, and one undo should restore all of them.
      */
     readonly op: 'acceptAllRevisions';
+    /** Exact canonical sites selected by bulk preflight. */
+    readonly siteNodeIds?: readonly string[];
     /** Internal shared-notes scope. When present, this must be the canonical id of a note root. */
     readonly scopeRootId?: string;
 } | {
     readonly op: 'rejectAllRevisions';
+    /** Exact canonical sites selected by bulk preflight. */
+    readonly siteNodeIds?: readonly string[];
     /** Internal shared-notes scope. When present, this must be the canonical id of a note root. */
     readonly scopeRootId?: string;
 } | {
@@ -3262,4 +4013,4 @@ type TreeOpResult = {
     readonly detail?: string;
 };
 
-export { type VectorShapeProjection as $, type AutomationTableMutation as A, type OoxmlFootnotesNode as B, type OoxmlNoteRefNode as C, type DrawingKind as D, type OoxmlNoteReferenceNode as E, type OoxmlSeparatorNode as F, type DrawingTreeDocOp as G, type ImpactClass as H, type ImageWrapTarget as I, type TreeDocColorValue as J, DEFAULT_IMAGE_RESOURCE_LIMITS as K, IMAGE_WRAP_TARGETS as L, TEXT_FORM_FORMATS as M, resolveImageResourceLimits as N, type OoxmlPart as O, type PreservedImageMime as P, resolveSvgIntrinsicSize as Q, type RevisionAddress as R, type SourceCrop as S, type TreeDocOp as T, sniffImageMime as U, type ValidatedImageBytesHandle as V, validateRasterHeader as W, type TableBorderStyle as X, type DrawingAccessibility as Y, type DrawingImageEffects as Z, type DrawingTransform as _, type OoxmlNode as a, type OoxmlContentControlDateFormatNode as a$, type DrawingProjection as a0, type OoxmlDrawingNode as a1, type ContentControlKind as a2, type ContentControlLevel as a3, type ContentControlLock as a4, type ContentControlDataBinding as a5, type VectorShapeComponent as a6, type ResourceLimits as a7, type OoxmlInvariantResult as a8, type RelationshipRecord as a9, type DeleteTextOp as aA, HARD_CEILINGS as aB, HYPERLINK_RELATIONSHIP_TYPE as aC, type HyperlinkKind as aD, type HyperlinkTarget as aE, IMAGE_RELATIONSHIP_TYPE as aF, IMAGE_RESOURCE_HARD_CEILINGS as aG, type ImageRelationshipResolution as aH, type ImageResourceLookup as aI, type IndexResult as aJ, type InsertTextOp as aK, MAX_CONTENT_CONTROLS_PER_PART as aL, MAX_CONTENT_CONTROL_NESTING as aM, MAX_SVG_SNIFF_BYTES as aN, type NameRejection as aO, type NameResult as aP, OFFICE_RELATIONSHIP_NAMESPACE_URI as aQ, OOXML_NODE_IDENTITY_RULES as aR, type OoxmlBodyNode as aS, type OoxmlBookmarkEndNode as aT, type OoxmlBookmarkStartNode as aU, type OoxmlContentControlCalendarNode as aV, type OoxmlContentControlCheckboxNode as aW, type OoxmlContentControlCheckedNode as aX, type OoxmlContentControlCheckedStateNode as aY, type OoxmlContentControlComboBoxNode as aZ, type OoxmlContentControlDataBindingNode as a_, type OoxmlInvariantIssue as aa, type OoxmlHardBreakNode as ab, type OoxmlFldCharNode as ac, type OoxmlFldSimpleNode as ad, type OoxmlInstrTextNode as ae, type OoxmlAttribute as af, type TreeOpResult as ag, ACCEPTED_PARAGRAPH_PROPERTIES as ah, ACCEPTED_RUN_PROPERTIES as ai, CONTENT_CONTROL_ID_MAX as aj, CONTENT_CONTROL_PROPERTY_ORDER as ak, type CommitTextFormFieldOp as al, type ContentControlCheckbox as am, type ContentControlCheckboxState as an, type ContentControlDateFormat as ao, type ContentControlEntry as ap, type ContentControlListItem as aq, type ContentControlProperties as ar, type ContentTypeError as as, type ContentTypeIndex as at, type ContentTypeRecords as au, type CreateImageResourceCacheOptions as av, DEFAULT_LIMITS as aw, DEFAULT_OOXML_PACKAGE_LIMITS as ax, DEFAULT_ZIP_LIMITS as ay, type DefaultRecord as az, type OoxmlPackage as b, contentControlLevelOf as b$, type OoxmlContentControlDateNode as b0, type OoxmlContentControlDropDownListNode as b1, type OoxmlContentControlEndPropertiesNode as b2, type OoxmlContentControlLidNode as b3, type OoxmlContentControlListItemNode as b4, type OoxmlContentControlPropertiesNode as b5, type OoxmlContentControlStoreMappedDataAsNode as b6, type OoxmlContentControlTextNode as b7, type OoxmlContentControlUncheckedStateNode as b8, type OoxmlDocumentNode as b9, TABLE_BORDER_STYLES as bA, type TabStopWrite as bB, type TargetMode as bC, type TextFormFieldOptions as bD, type TextFormFieldRange as bE, type TextFormFieldType as bF, type TreeDocOpKind as bG, type TreeOpEffect as bH, type ValidatedRasterHeader as bI, WML_NAMESPACE_URI as bJ, XMLNS_NAMESPACE_URI as bK, XML_NAMESPACE_URI as bL, type XmlLimits as bM, type XmlNode as bN, type XmlRejection as bO, type XmlResult as bP, type ZipLimits as bQ, type ZipReadResult as bR, type ZipRejection as bS, allocateContentControlId as bT, asciiFold as bU, buildContentTypeIndex as bV, buildRelationshipSet as bW, childElements as bX, contentControlContentChildren as bY, contentControlContentNodeOf as bZ, contentControlEndPropertiesNodeOf as b_, type OoxmlExternalTarget as ba, type OoxmlGenericExtensionAttribute as bb, type OoxmlHyperlinkNode as bc, type OoxmlInvariantIssueCode as bd, type OoxmlKnownNodeAttribute as be, type OoxmlNamespaceBinding as bf, type OoxmlNodeIdentityRules as bg, type OoxmlPackageResult as bh, type OoxmlParagraphPropertiesNode as bi, type OoxmlPartMetadata as bj, type OoxmlReadRejection as bk, type OoxmlReadResult as bl, type OoxmlRunNode as bm, type OoxmlRunPropertiesNode as bn, type OoxmlTabNode as bo, type OoxmlTextElementNode as bp, type OoxmlTextNode as bq, type OoxmlWmlValAttribute as br, type OoxmlXmlSpaceAttribute as bs, type OverrideRecord as bt, type RelationshipError as bu, type RelationshipSetResult as bv, type RelationshipTargetResolver as bw, type ResolveResult as bx, type ResolvedRelationship as by, type SetTextFormFieldDefaultOp as bz, type OoxmlNodeId as c, contentControlPropertiesNodeOf as c0, contentControlPropertiesOf as c1, contentControlTextOf as c2, contentControlsIn as c3, createImageResourceCache as c4, detectDuplicateNames as c5, extensionKey as c6, findContentControl as c7, findElement as c8, flattenContentControls as c9, resolveContentType as cA, resolveImageRelationship as cB, resolveInternalTarget as cC, resolveLimits as cD, resolveRelationship as cE, textContent as cF, textFormFieldsOf as cG, validateExternalTarget as cH, validateGifHeader as cI, validateJpegHeader as cJ, validatePngHeader as cK, withPart as cL, writeOoxmlPackage as cM, writeZip as cN, hasBoundedSvgRoot as ca, hyperlinkAnchorOf as cb, hyperlinkRelationshipIdOf as cc, hyperlinkTargetOf as cd, imageResourceLookupFor as ce, isContentControlContentNode as cf, isContentControlNode as cg, isContentControlWrapper as ch, isContentRevisionKind as ci, isHyperlinkNode as cj, isRangeMarkerKind as ck, isValidMime as cl, liveDrawingReferenceCount as cm, lockForbidsEdit as cn, lockForbidsRemoval as co, normalizePartName as cp, orderedContentControlProperties as cq, parseContentControlId as cr, partNameKey as cs, projectDrawing as ct, readOnOffChild as cu, readOoxmlPackage as cv, readOoxmlPart as cw, readXml as cx, readZip as cy, resolveContentControlLock as cz, type OoxmlGenericElementNode as d, type OoxmlElement as e, type OoxmlPackageLimits as f, type OoxmlPackageRejection as g, type OoxmlProperty as h, type OoxmlContentControlNode as i, type OoxmlContentControlContentNode as j, type RenderableImageMime as k, type TreeOpRejection as l, type DrawingPositionInput as m, type DrawingLocks as n, type ImageResourceState as o, type SupportedImageMime as p, type DrawingHorizontalReferenceFrame as q, type DrawingVerticalReferenceFrame as r, type VectorImageMime as s, type ImageDecodePort as t, type RevisionAttributionInput as u, type ImageResourceLimits as v, type OoxmlParagraphNode as w, type OoxmlNoteNode as x, type OoxmlContinuationSeparatorNode as y, type OoxmlEndnotesNode as z };
+export { type RevisionBatchSkipReason as $, type IndentFormatting as A, type Block as B, type CommentRecord as C, type DocxDocument as D, type ExecResult as E, type ParagraphFlags as F, type ParagraphTabStop as G, type HeaderFooterSet as H, type InsertableContentControlType as I, type RevisionType as J, type Section as K, type SectionProperties as L, type StyleDefinition as M, type Theme as N, type OoxmlPart as O, type Paragraph as P, type ThemeColorScheme as Q, type ReviewModelInput as R, type StyleDefinitions as S, type Table as T, type OoxmlNodeId as U, type OoxmlGenericElementNode as V, type TreeDocOp as W, type OoxmlPackageLimits as X, type OoxmlPackageRejection as Y, type RevisionBatchEntry as Z, type RevisionBatchResult as _, type ReviewItem as a, type CommentPosition as a$, type OoxmlProperty as a0, type OoxmlElement as a1, type OoxmlContentControlNode as a2, type OoxmlContentControlContentNode as a3, type DrawingProjection as a4, type TreeOpRejection as a5, type AutomationTableMutation as a6, type SourceCrop as a7, type DrawingKind as a8, type ImageWrapTarget as a9, type OoxmlSeparatorNode as aA, type DrawingTreeDocOp as aB, type ImpactClass as aC, type TreeDocColorValue as aD, IMAGE_WRAP_TARGETS as aE, TEXT_FORM_FORMATS as aF, type TableBorderStyle as aG, type DrawingAccessibility as aH, type DrawingImageEffects as aI, type DrawingTransform as aJ, type VectorShapeProjection as aK, type OoxmlDrawingNode as aL, type OoxmlInvariantResult as aM, type RelationshipRecord as aN, type OoxmlInvariantIssue as aO, type OoxmlHardBreakNode as aP, type OoxmlFldCharNode as aQ, type OoxmlFldSimpleNode as aR, type OoxmlInstrTextNode as aS, type OoxmlAttribute as aT, type TreeOpResult as aU, type CommentThreadState as aV, ACCEPTED_PARAGRAPH_PROPERTIES as aW, ACCEPTED_RUN_PROPERTIES as aX, CONTENT_CONTROL_ID_MAX as aY, CONTENT_CONTROL_PROPERTY_ORDER as aZ, type CommentAnchor as a_, type DrawingPositionInput as aa, type DrawingLocks as ab, type ParagraphFormatCommand as ac, type Watermark as ad, type Rect as ae, type SelectionPin as af, type Unsubscribe as ag, type DocxDocumentJSON as ah, type DrawingHorizontalReferenceFrame as ai, type DrawingVerticalReferenceFrame as aj, type FontDefinition as ak, type NumberingRef as al, type PageMargins as am, type ParagraphDisagreements as an, type Point as ao, type Run as ap, type TableCell as aq, type TableRow as ar, type RevisionAttributionInput as as, type OoxmlParagraphNode as at, type OoxmlNoteNode as au, type OoxmlContinuationSeparatorNode as av, type OoxmlEndnotesNode as aw, type OoxmlFootnotesNode as ax, type OoxmlNoteRefNode as ay, type OoxmlNoteReferenceNode as az, type ReviewRevisionItem as b, type OoxmlRunNode as b$, type CommitTextFormFieldOp as b0, type ContentControlCheckbox as b1, type ContentControlCheckboxState as b2, type ContentControlDataBinding as b3, type ContentControlDateFormat as b4, type ContentControlEntry as b5, type ContentControlKind as b6, type ContentControlLevel as b7, type ContentControlListItem as b8, type ContentControlLock as b9, type OoxmlContentControlCheckedNode as bA, type OoxmlContentControlCheckedStateNode as bB, type OoxmlContentControlComboBoxNode as bC, type OoxmlContentControlDataBindingNode as bD, type OoxmlContentControlDateFormatNode as bE, type OoxmlContentControlDateNode as bF, type OoxmlContentControlDropDownListNode as bG, type OoxmlContentControlEndPropertiesNode as bH, type OoxmlContentControlLidNode as bI, type OoxmlContentControlListItemNode as bJ, type OoxmlContentControlPropertiesNode as bK, type OoxmlContentControlStoreMappedDataAsNode as bL, type OoxmlContentControlTextNode as bM, type OoxmlContentControlUncheckedStateNode as bN, type OoxmlDocumentNode as bO, type OoxmlExternalTarget as bP, type OoxmlGenericExtensionAttribute as bQ, type OoxmlHyperlinkNode as bR, type OoxmlInvariantIssueCode as bS, type OoxmlKnownNodeAttribute as bT, type OoxmlNamespaceBinding as bU, type OoxmlNodeIdentityRules as bV, type OoxmlPackageResult as bW, type OoxmlParagraphPropertiesNode as bX, type OoxmlPartMetadata as bY, type OoxmlReadRejection as bZ, type OoxmlReadResult as b_, type ContentControlProperties as ba, type ContentTypeError as bb, type ContentTypeIndex as bc, type ContentTypeRecords as bd, DEFAULT_OOXML_PACKAGE_LIMITS as be, DEFAULT_ZIP_LIMITS as bf, type DefaultRecord as bg, type DeleteTextOp as bh, HYPERLINK_RELATIONSHIP_TYPE as bi, type HyperlinkKind as bj, type HyperlinkTarget as bk, IMAGE_RELATIONSHIP_TYPE as bl, type ImageRelationshipResolution as bm, type IndexResult as bn, type InsertTextOp as bo, MAX_CONTENT_CONTROLS_PER_PART as bp, MAX_CONTENT_CONTROL_NESTING as bq, type NameRejection as br, type NameResult as bs, OFFICE_RELATIONSHIP_NAMESPACE_URI as bt, OOXML_NODE_IDENTITY_RULES as bu, type OoxmlBodyNode as bv, type OoxmlBookmarkEndNode as bw, type OoxmlBookmarkStartNode as bx, type OoxmlContentControlCalendarNode as by, type OoxmlContentControlCheckboxNode as bz, type ReviewCommentItem as c, isValidMime as c$, type OoxmlRunPropertiesNode as c0, type OoxmlTabNode as c1, type OoxmlTextElementNode as c2, type OoxmlTextNode as c3, type OoxmlWmlValAttribute as c4, type OoxmlXmlSpaceAttribute as c5, type OverrideRecord as c6, type RelationshipError as c7, type RelationshipSetResult as c8, type RelationshipTargetResolver as c9, childElements as cA, commentAnchorsOfStory as cB, commentsOfPart as cC, contentControlContentChildren as cD, contentControlContentNodeOf as cE, contentControlEndPropertiesNodeOf as cF, contentControlLevelOf as cG, contentControlPropertiesNodeOf as cH, contentControlPropertiesOf as cI, contentControlTextOf as cJ, contentControlsIn as cK, detectDuplicateNames as cL, extensionKey as cM, findContentControl as cN, findElement as cO, firstReviewRange as cP, flattenContentControls as cQ, hasAnyComment as cR, hyperlinkAnchorOf as cS, hyperlinkRelationshipIdOf as cT, hyperlinkTargetOf as cU, isContentControlContentNode as cV, isContentControlNode as cW, isContentControlWrapper as cX, isContentRevisionKind as cY, isHyperlinkNode as cZ, isRangeMarkerKind as c_, type ResolveResult as ca, type ResolvedRelationship as cb, type SetTextFormFieldDefaultOp as cc, TABLE_BORDER_STYLES as cd, type TabStopWrite as ce, type TargetMode as cf, type TextFormFieldOptions as cg, type TextFormFieldRange as ch, type TextFormFieldType as ci, type TreeDocOpKind as cj, type TreeOpEffect as ck, W15_NAMESPACE_URI as cl, WML_NAMESPACE_URI as cm, XMLNS_NAMESPACE_URI as cn, XML_NAMESPACE_URI as co, type XmlLimits as cp, type XmlNode as cq, type XmlRejection as cr, type XmlResult as cs, type ZipLimits as ct, type ZipReadResult as cu, type ZipRejection as cv, allocateContentControlId as cw, asciiFold as cx, buildContentTypeIndex as cy, buildRelationshipSet as cz, type ReviewCustomItem as d, lockForbidsEdit as d0, lockForbidsRemoval as d1, normalizePartName as d2, orderedContentControlProperties as d3, parseContentControlId as d4, partNameKey as d5, planRevisionBatch as d6, projectDrawing as d7, readOnOffChild as d8, readOoxmlPackage as d9, readOoxmlPart as da, readXml as db, readZip as dc, resolveContentControlLock as dd, resolveContentType as de, resolveImageRelationship as df, resolveInternalTarget as dg, resolveRelationship as dh, reviewItemKey as di, reviewItemRanges as dj, textContent as dk, textFormFieldsOf as dl, threadStateOfPart as dm, validateExternalTarget as dn, withPart as dp, writeOoxmlPackage as dq, writeZip as dr, type VectorShapeComponent as ds, activeReviewItem as dt, reviewItemPositionRank as du, reviewItemsAt as dv, reviewThreadRootOf as dw, type ReviewPosition as e, type ReviewRange as f, type ReviewRevisionKind as g, type RevisionAddress as h, type OoxmlNode as i, type OoxmlPackage as j, type ContentControlType as k, type DocTarget as l, type RunFormatting as m, type Extent as n, type ContainerRef as o, type ContentControlFilter as p, type DocRange as q, type Revision as r, type DocComment as s, type ColorValue as t, type ContentControl as u, type DocAnchor as v, type DocAnchorRange as w, type DocLocation as x, type DocumentBody as y, type ExecErrorCode as z };