@docx-editor.dev/core 2.31.0 → 2.32.0

package/dist/{types-barrel-CkF2JbU4.d.ts → tree-op-types-C_S2niXW.d.ts}

@@ -1,4 +1,4 @@
-import { d as HistoryGroupOutcome } from './editor-scope-C7ke1KJG.js';
+import { H as HistoryGroupOutcome } from './editor-scope-B3L-1ALc.js';
 
 /**
  * Why a zip was refused at the trust boundary.
@@ -2001,6 +2001,18 @@ type AutomationTableMutation = {
     readonly kind: 'deleteRows' | 'deleteColumns';
     readonly index: number;
     readonly count: number;
+} | {
+    /** Merge the rectangle from one cell to another, by row and in-row cell index. */
+    readonly kind: 'mergeCells';
+    readonly topRow: number;
+    readonly firstCell: number;
+    readonly bottomRow: number;
+    readonly lastCell: number;
+} | {
+    readonly kind: 'splitCell';
+    readonly cellId: string;
+    readonly rowCount: number;
+    readonly columnCount: number;
 } | {
     readonly kind: 'delete';
 } | {
@@ -2031,6 +2043,70 @@ interface SetFieldCodeOp {
     readonly code: string;
 }
 
+/**
+ * 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.
+ */
+interface InsertPageFieldOp {
+    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;
+}
+/**
+ * Insert one complex field with an empty cached result at a UTF-16 offset.
+ *
+ * The instruction must be one that `inertFieldInstruction` admits: a page number, a reference
+ * to a bookmark, note, or style, a sequence number, or a date. It is written as text and never
+ * evaluated. Every other instruction refuses with `invalidArgs`.
+ */
+interface InsertComplexFieldOp {
+    readonly op: 'insertComplexField';
+    readonly paragraphId: string;
+    readonly offset: number;
+    readonly instruction: string;
+    /** Write the whole field as ONE tracked insertion, on the same terms as `insertText`. */
+    readonly revision?: RevisionAttributionInput;
+}
+
+/** Set one field's cached result text. See the module comment for the placements. */
+interface SetFieldResultOp {
+    readonly op: 'setFieldResult';
+    readonly paragraphId: string;
+    /** The begin `w:fldChar`, or the `w:fldSimple` element. */
+    readonly fieldNodeId: string;
+    /** Plain text. A tab becomes `w:tab`; other control characters refuse. */
+    readonly text: string;
+    /**
+     * The author whose pending insertion holds the field. The result joins that insertion. The
+     * op mints no revision of its own.
+     */
+    readonly revision?: RevisionAttributionInput;
+}
+
+/** Insert one inline `m:oMath` and the plain runs beside it. */
+interface InsertEquationOp {
+    readonly op: 'insertEquation';
+    readonly paragraphId: string;
+    readonly offset: number;
+    /** Plain runs and exactly one inline `m:oMath`, in order. Receive fresh ids at apply. */
+    readonly nodes: readonly OoxmlNode[];
+    /** Model length of `nodes`: their text, plus one for the equation. */
+    readonly length: number;
+    /** Write the nodes as ONE tracked insertion, on the same terms as `insertText`. */
+    readonly revision?: RevisionAttributionInput;
+}
+
 type InsertTextOp = {
     readonly op: 'insertText';
     readonly paragraphId: string;
@@ -2877,8 +2953,18 @@ interface RevisionBatchResult {
     /** 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): {
+/**
+ * @internal Pure preflight; callers commit its operations through their normal write guards.
+ *
+ * `countRemaining: false` skips the exact count of the decisions left after the batch, and
+ * reports `remaining` as the decisions not resolved here. The exact count resolves the whole
+ * batch once more on a copy and lists what is left, which on a long reviewed document cost more
+ * than the plan itself, and a caller that reads only the operations or the skipped changes
+ * (a check, one decision, an editor that recounts its queue) paid it on every call.
+ */
+declare function planRevisionBatch(part: OoxmlPart, action: 'accept' | 'reject', keys?: readonly string[], scopeRoot?: OoxmlNode, options?: {
+    readonly countRemaining?: boolean;
+}): {
     ops: readonly TreeDocOp[];
     result: RevisionBatchResult;
 };
@@ -3787,26 +3873,7 @@ type TreeDocOp = SetFieldCodeOp | {
     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;
-} | {
+} | InsertPageFieldOp | InsertComplexFieldOp | SetFieldResultOp | InsertEquationOp | {
     /**
      * Move a numbered paragraph to another `w:numPr/w:ilvl`.
      *
@@ -4095,6 +4162,8 @@ type TreeDocOp = SetFieldCodeOp | {
         readonly xpath: string;
         readonly storeItemId: string;
     };
+    /** Propose the control as a tracked `w:ins`; rejecting removes it with its text. */
+    readonly revision?: RevisionAttributionInput;
 } | {
     /** Repeating-section item insert — unsupported at this layer (out of scope). */
     readonly op: 'addRepeatingSectionItem';
@@ -4169,6 +4238,18 @@ type TreeDocOp = SetFieldCodeOp | {
     readonly op: 'deleteTableColumn';
     readonly tableId: string;
     readonly gridColumnId: string;
+} | {
+    /** Merge cells covering one rectangle into its top-left cell, content in reading order. */
+    readonly op: 'mergeTableCells';
+    readonly tableId: string;
+    readonly cellIds: readonly string[];
+} | {
+    /** Split one cell into `rows` by `columns` equal cells; a one-row cell adds rows. */
+    readonly op: 'splitTableCell';
+    readonly tableId: string;
+    readonly cellId: string;
+    readonly rows: number;
+    readonly columns: number;
 } | {
     /**
      * Resize one internal divider between two adjacent canonical grid columns.
@@ -4648,8 +4729,18 @@ type TreeOpRejection = 'unknown-op' | 'unknown-paragraph' | 'not-a-paragraph' |
  * 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. */
+/** The table carries a legacy `w:hMerge`, which grid edits cannot place. */
  | 'table-has-merge'
+/** The cells to merge do not cover one rectangle, or cover only one cell. */
+ | 'cells-not-rectangle'
+/** A cell merged over several rows splits only into a divisor of them. */
+ | 'split-rows-not-divisor'
+/** The cells hold a tracked cell insertion, deletion, or merge. */
+ | 'cell-has-revision'
+/** The split cells would be narrower than the minimum column width. */
+ | 'cell-too-narrow'
+/** Without `w:tblGrid`, a cell splits only into a divisor of the columns it spans. */
+ | 'split-needs-grid'
 /** The addressed grid column id is missing or ambiguous without `w:tblGrid`. */
  | 'unknown-grid-column'
 /** The operation would exceed bounded table topology limits. */
@@ -4687,5 +4778,5 @@ type TreeOpResult = {
     readonly detail?: string;
 };
 
-export { validateRasterHeader as a$, DEFAULT_IMAGE_RESOURCE_LIMITS as aV, IMAGE_WRAP_TARGETS as aW, TEXT_FORM_FORMATS as aX, resolveImageResourceLimits as aY, resolveSvgIntrinsicSize as aZ, sniffImageMime as a_, DEFAULT_LIMITS as bF, DEFAULT_OOXML_PACKAGE_LIMITS as bG, DEFAULT_ZIP_LIMITS as bH, HARD_CEILINGS as bL, HYPERLINK_RELATIONSHIP_TYPE as bM, IMAGE_RELATIONSHIP_TYPE as bP, IMAGE_RESOURCE_HARD_CEILINGS as bQ, MAX_CONTENT_CONTROLS_PER_PART as bY, MAX_CONTENT_CONTROL_NESTING as bZ, MAX_SVG_SNIFF_BYTES as b_, ACCEPTED_PARAGRAPH_PROPERTIES as bj, ACCEPTED_RUN_PROPERTIES as bk, CONTENT_CONTROL_ID_MAX as bm, CONTENT_CONTROL_PROPERTY_ORDER as bn, OFFICE_RELATIONSHIP_NAMESPACE_URI as c1, OOXML_NODE_IDENTITY_RULES as c2, TABLE_BORDER_STYLES as cO, W15_NAMESPACE_URI as cV, WML_NAMESPACE_URI as cW, XMLNS_NAMESPACE_URI as cX, XML_NAMESPACE_URI as cY, reviewItemKey as d$, allocateContentControlId as d4, asciiFold as d5, buildContentTypeIndex as d6, buildRelationshipSet as d7, childElements as d8, commentAnchorsOfStory as d9, isContentControlWrapper as dA, isContentRevisionKind as dB, isHyperlinkNode as dC, isRangeMarkerKind as dD, isValidMime as dE, legacyCheckboxFieldsOf as dF, liveDrawingReferenceCount as dG, lockForbidsEdit as dH, lockForbidsRemoval as dI, normalizePartName as dJ, orderedContentControlProperties as dK, parseContentControlId as dL, partNameKey as dM, planRevisionAuthorChange as dN, planRevisionBatch as dO, projectDrawing as dP, readOnOffChild as dQ, readOoxmlPackage as dR, readOoxmlPart as dS, readXml as dT, readZip as dU, resolveContentControlLock as dV, resolveContentType as dW, resolveImageRelationship as dX, resolveInternalTarget as dY, resolveLimits as dZ, resolveRelationship as d_, commentsOfPart as da, contentControlContentChildren as db, contentControlContentNodeOf as dc, contentControlEndPropertiesNodeOf as dd, contentControlLevelOf as de, contentControlPropertiesNodeOf as df, contentControlPropertiesOf as dg, contentControlTextOf as dh, contentControlsIn as di, createImageResourceCache as dj, detectDuplicateNames as dk, enclosedBookmarkDeletions as dl, extensionKey as dm, findContentControl as dn, findElement as dp, firstReviewRange as dq, flattenContentControls as dr, hasAnyComment as ds, hasBoundedSvgRoot as dt, hyperlinkAnchorOf as du, hyperlinkRelationshipIdOf as dv, hyperlinkTargetOf as dw, imageResourceLookupFor as dx, isContentControlContentNode as dy, isContentControlNode as dz, reviewItemRanges as e0, textContent as e1, textFormFieldsOf as e2, threadStateOfPart as e3, validateExternalTarget as e4, validateGifHeader as e5, validateJpegHeader as e6, validatePngHeader as e7, withPart as e8, withoutBookmarkInPart as e9, writeOoxmlPackage as ea, writeZip as eb, activeReviewItem as ed, reviewItemPositionRank as ee, reviewItemsAt as ef, reviewThreadRootOf as eg };
-export type { DrawingVerticalReferenceFrame as $, ParagraphTabStop as A, Block as B, CommentRecord as C, DocxDocument as D, ExecResult as E, RevisionType as F, Section as G, HeaderFooterSet as H, InsertableContentControlType as I, SectionProperties as J, StyleDefinition as K, Theme as L, ThemeColorScheme as M, OoxmlNode as N, OoxmlPart as O, Paragraph as P, OoxmlPackage as Q, ReviewModelInput as R, StyleDefinitions as S, Table as T, OoxmlNodeId as U, OoxmlGenericElementNode as V, DocxDocumentJSON as W, DrawingHorizontalReferenceFrame as X, DrawingKind as Y, DrawingLocks as Z, DrawingPositionInput as _, ReviewItem as a, FontDefinition as a0, ImageResourceState as a1, ImageWrapTarget as a2, NumberingRef as a3, PageMargins as a4, ParagraphDisagreements as a5, ParagraphFormatCommand as a6, Point as a7, PreservedImageMime as a8, Rect as a9, RevisionBatchSkipReason as aA, RevisionSiteRefusal as aB, TreeOpRejection as aC, ImageResourceLimits as aD, ImageDecodePort as aE, AutomationTableMutation as aF, RevisionAttributionInput as aG, PackageWatermarkWrite as aH, OoxmlInvariantIssue as aI, DrawingTreeDocOp as aJ, ImpactClass as aK, OoxmlParagraphNode as aL, OoxmlNoteNode as aM, OoxmlContinuationSeparatorNode as aN, OoxmlEndnotesNode as aO, OoxmlFootnotesNode as aP, OoxmlNoteRefNode as aQ, OoxmlNoteReferenceNode as aR, OoxmlSeparatorNode as aS, SourceCrop as aT, TreeDocColorValue as aU, RenderableImageMime as aa, RevisionAuthorResult as ab, RevisionBatchResult as ac, Run as ad, SelectionPin as ae, SupportedImageMime as af, TableCell as ag, TableRow as ah, Unsubscribe as ai, ValidatedImageBytesHandle as aj, VectorImageMime as ak, Watermark as al, WatermarkLayout as am, WatermarkState as an, TreeDocOp as ao, OoxmlElement as ap, OoxmlContentControlNode as aq, OoxmlContentControlContentNode as ar, OoxmlPackageRejection as as, OoxmlProperty as at, OoxmlPackageResult as au, OoxmlPackageLimits as av, RevisionAuthorEntry as aw, RevisionAuthorSkipReason as ax, RevisionBatchEntry as ay, RevisionBatchSkipDetail as az, ReviewRevisionItem as b, NameRejection as b$, TextFormFieldRange as b0, TextFormFieldOptions as b1, DrawingTransform as b2, TableBorderStyle as b3, DrawingAccessibility as b4, DrawingImageEffects as b5, VectorShapeProjection as b6, DrawingProjection as b7, OoxmlDrawingNode as b8, OoxmlInvariantResult as b9, ContentControlProperties as bA, ContentTypeError as bB, ContentTypeIndex as bC, ContentTypeRecords as bD, CreateImageResourceCacheOptions as bE, DefaultRecord as bI, DeleteBookmarkOp as bJ, DeleteTextOp as bK, HyperlinkKind as bN, HyperlinkTarget as bO, ImageRelationshipResolution as bR, ImageResourceLookup as bS, IndexResult as bT, InsertBookmarkOp as bU, InsertBuildingBlockOp as bV, InsertTextOp as bW, LegacyCheckboxFieldRange as bX, OoxmlFldCharNode as ba, OoxmlFldSimpleNode as bb, OoxmlInstrTextNode as bc, TreeOpResult as bd, RelationshipRecord as be, OoxmlHardBreakNode as bf, OoxmlAttribute as bg, ResourceLimits as bh, CommentThreadState as bi, BookmarkOpPosition as bl, CommentAnchor as bo, CommentPosition as bp, CommitTextFormFieldOp as bq, ContentControlCheckbox as br, ContentControlCheckboxState as bs, ContentControlDataBinding as bt, ContentControlDateFormat as bu, ContentControlEntry as bv, ContentControlKind as bw, ContentControlLevel as bx, ContentControlListItem as by, ContentControlLock as bz, ReviewCommentItem as c, XmlRejection as c$, NameResult as c0, OoxmlBodyNode as c3, OoxmlBookmarkEndNode as c4, OoxmlBookmarkStartNode as c5, OoxmlContentControlCalendarNode as c6, OoxmlContentControlCheckboxNode as c7, OoxmlContentControlCheckedNode as c8, OoxmlContentControlCheckedStateNode as c9, OoxmlTabNode as cA, OoxmlTextElementNode as cB, OoxmlTextNode as cC, OoxmlWmlValAttribute as cD, OoxmlXmlSpaceAttribute as cE, OverrideRecord as cF, RelationshipError as cG, RelationshipSetResult as cH, RelationshipTargetResolver as cI, ResolveResult as cJ, ResolvedRelationship as cK, SetLegacyCheckboxOp as cL, SetLegacyDropdownOp as cM, SetTextFormFieldDefaultOp as cN, TabStopWrite as cP, TargetMode as cQ, TextFormFieldType as cR, TreeDocOpKind as cS, TreeOpEffect as cT, ValidatedRasterHeader as cU, XmlLimits as cZ, XmlNode as c_, OoxmlContentControlComboBoxNode as ca, OoxmlContentControlDataBindingNode as cb, OoxmlContentControlDateFormatNode as cc, OoxmlContentControlDateNode as cd, OoxmlContentControlDropDownListNode as ce, OoxmlContentControlEndPropertiesNode as cf, OoxmlContentControlLidNode as cg, OoxmlContentControlListItemNode as ch, OoxmlContentControlPropertiesNode as ci, OoxmlContentControlStoreMappedDataAsNode as cj, OoxmlContentControlTextNode as ck, OoxmlContentControlUncheckedStateNode as cl, OoxmlDocumentNode as cm, OoxmlExternalTarget as cn, OoxmlGenericExtensionAttribute as co, OoxmlHyperlinkNode as cp, OoxmlInvariantIssueCode as cq, OoxmlKnownNodeAttribute as cr, OoxmlNamespaceBinding as cs, OoxmlNodeIdentityRules as ct, OoxmlParagraphPropertiesNode as cu, OoxmlPartMetadata as cv, OoxmlReadRejection as cw, OoxmlReadResult as cx, OoxmlRunNode as cy, OoxmlRunPropertiesNode as cz, ReviewCustomItem as d, XmlResult as d0, ZipLimits as d1, ZipReadResult as d2, ZipRejection as d3, ReviewPosition as e, VectorShapeComponent as ec, ReviewRange as f, ReviewRevisionKind as g, RevisionAddress as h, ContentControlType as i, DocTarget as j, RunFormatting as k, Extent as l, ContainerRef as m, ContentControlFilter as n, DocRange as o, Revision as p, DocComment as q, ColorValue as r, ContentControl as s, DocAnchor as t, DocAnchorRange as u, DocLocation as v, DocumentBody as w, ExecErrorCode as x, IndentFormatting as y, ParagraphFlags as z };
+export { validateRasterHeader as a$, DEFAULT_IMAGE_RESOURCE_LIMITS as aV, IMAGE_WRAP_TARGETS as aW, TEXT_FORM_FORMATS as aX, resolveImageResourceLimits as aY, resolveSvgIntrinsicSize as aZ, sniffImageMime as a_, MAX_CONTENT_CONTROLS_PER_PART as b$, DEFAULT_LIMITS as bF, DEFAULT_OOXML_PACKAGE_LIMITS as bG, DEFAULT_ZIP_LIMITS as bH, HARD_CEILINGS as bL, HYPERLINK_RELATIONSHIP_TYPE as bM, IMAGE_RELATIONSHIP_TYPE as bP, IMAGE_RESOURCE_HARD_CEILINGS as bQ, ACCEPTED_PARAGRAPH_PROPERTIES as bj, ACCEPTED_RUN_PROPERTIES as bk, CONTENT_CONTROL_ID_MAX as bm, CONTENT_CONTROL_PROPERTY_ORDER as bn, XMLNS_NAMESPACE_URI as c$, MAX_CONTENT_CONTROL_NESTING as c0, MAX_SVG_SNIFF_BYTES as c1, OFFICE_RELATIONSHIP_NAMESPACE_URI as c4, OOXML_NODE_IDENTITY_RULES as c5, TABLE_BORDER_STYLES as cS, W15_NAMESPACE_URI as cZ, WML_NAMESPACE_URI as c_, resolveImageRelationship as d$, XML_NAMESPACE_URI as d0, allocateContentControlId as d8, asciiFold as d9, hyperlinkTargetOf as dA, imageResourceLookupFor as dB, isContentControlContentNode as dC, isContentControlNode as dD, isContentControlWrapper as dE, isContentRevisionKind as dF, isHyperlinkNode as dG, isRangeMarkerKind as dH, isValidMime as dI, legacyCheckboxFieldsOf as dJ, liveDrawingReferenceCount as dK, lockForbidsEdit as dL, lockForbidsRemoval as dM, normalizePartName as dN, orderedContentControlProperties as dO, parseContentControlId as dP, partNameKey as dQ, planRevisionAuthorChange as dR, planRevisionBatch as dS, projectDrawing as dT, readOnOffChild as dU, readOoxmlPackage as dV, readOoxmlPart as dW, readXml as dX, readZip as dY, resolveContentControlLock as dZ, resolveContentType as d_, buildContentTypeIndex as da, buildRelationshipSet as db, childElements as dc, commentAnchorsOfStory as dd, commentsOfPart as de, contentControlContentChildren as df, contentControlContentNodeOf as dg, contentControlEndPropertiesNodeOf as dh, contentControlLevelOf as di, contentControlPropertiesNodeOf as dj, contentControlPropertiesOf as dk, contentControlTextOf as dl, contentControlsIn as dm, createImageResourceCache as dn, detectDuplicateNames as dp, enclosedBookmarkDeletions as dq, extensionKey as dr, findContentControl as ds, findElement as dt, firstReviewRange as du, flattenContentControls as dv, hasAnyComment as dw, hasBoundedSvgRoot as dx, hyperlinkAnchorOf as dy, hyperlinkRelationshipIdOf as dz, resolveInternalTarget as e0, resolveLimits as e1, resolveRelationship as e2, reviewItemKey as e3, reviewItemRanges as e4, textContent as e5, textFormFieldsOf as e6, threadStateOfPart as e7, validateExternalTarget as e8, validateGifHeader as e9, validateJpegHeader as ea, validatePngHeader as eb, withPart as ec, withoutBookmarkInPart as ed, writeOoxmlPackage as ee, writeZip as ef, activeReviewItem as eh, reviewItemPositionRank as ei, reviewItemsAt as ej, reviewThreadRootOf as ek };
+export type { Table as $, ParagraphDisagreements as A, Block as B, CommentRecord as C, DocxDocument as D, ExecResult as E, ParagraphFlags as F, ParagraphTabStop as G, HeaderFooterSet as H, InsertableContentControlType as I, RevisionAuthorEntry as J, RevisionAuthorResult as K, RevisionAuthorSkipReason as L, RevisionBatchEntry as M, NumberingRef as N, OoxmlPart as O, PageMargins as P, RevisionBatchResult as Q, ReviewModelInput as R, StyleDefinitions as S, RevisionBatchSkipDetail as T, RevisionBatchSkipReason as U, RevisionSiteRefusal as V, RevisionType as W, Run as X, Section as Y, SectionProperties as Z, StyleDefinition as _, ReviewItem as a, TableCell as a0, TableRow as a1, Theme as a2, ThemeColorScheme as a3, OoxmlNode as a4, OoxmlPackage as a5, DocxDocumentJSON as a6, DrawingHorizontalReferenceFrame as a7, DrawingKind as a8, DrawingLocks as a9, OoxmlPackageResult as aA, OoxmlPackageRejection as aB, OoxmlNodeId as aC, OoxmlPackageLimits as aD, AutomationTableMutation as aE, RevisionAttributionInput as aF, TreeOpRejection as aG, PackageWatermarkWrite as aH, OoxmlInvariantIssue as aI, DrawingTreeDocOp as aJ, ImpactClass as aK, OoxmlParagraphNode as aL, OoxmlNoteNode as aM, OoxmlContinuationSeparatorNode as aN, OoxmlEndnotesNode as aO, OoxmlFootnotesNode as aP, OoxmlNoteRefNode as aQ, OoxmlNoteReferenceNode as aR, OoxmlSeparatorNode as aS, SourceCrop as aT, TreeDocColorValue as aU, DrawingPositionInput as aa, DrawingVerticalReferenceFrame as ab, FontDefinition as ac, ImageDecodePort as ad, ImageResourceLimits as ae, ImageResourceState as af, ImageWrapTarget as ag, ParagraphFormatCommand as ah, Point as ai, PreservedImageMime as aj, Rect as ak, RenderableImageMime as al, SelectionPin as am, SupportedImageMime as an, Unsubscribe as ao, ValidatedImageBytesHandle as ap, VectorImageMime as aq, Watermark as ar, WatermarkLayout as as, WatermarkState as at, TreeDocOp as au, OoxmlElement as av, OoxmlContentControlNode as aw, OoxmlGenericElementNode as ax, OoxmlContentControlContentNode as ay, OoxmlProperty as az, ReviewRevisionItem as b, TextFormFieldRange as b0, TextFormFieldOptions as b1, DrawingTransform as b2, TableBorderStyle as b3, DrawingAccessibility as b4, DrawingImageEffects as b5, VectorShapeProjection as b6, DrawingProjection as b7, OoxmlDrawingNode as b8, OoxmlInvariantResult as b9, ContentControlProperties as bA, ContentTypeError as bB, ContentTypeIndex as bC, ContentTypeRecords as bD, CreateImageResourceCacheOptions as bE, DefaultRecord as bI, DeleteBookmarkOp as bJ, DeleteTextOp as bK, HyperlinkKind as bN, HyperlinkTarget as bO, ImageRelationshipResolution as bR, ImageResourceLookup as bS, IndexResult as bT, InsertBookmarkOp as bU, InsertBuildingBlockOp as bV, InsertComplexFieldOp as bW, InsertEquationOp as bX, InsertPageFieldOp as bY, InsertTextOp as bZ, LegacyCheckboxFieldRange as b_, OoxmlFldCharNode as ba, OoxmlFldSimpleNode as bb, OoxmlInstrTextNode as bc, TreeOpResult as bd, RelationshipRecord as be, OoxmlHardBreakNode as bf, OoxmlAttribute as bg, ResourceLimits as bh, CommentThreadState as bi, BookmarkOpPosition as bl, CommentAnchor as bo, CommentPosition as bp, CommitTextFormFieldOp as bq, ContentControlCheckbox as br, ContentControlCheckboxState as bs, ContentControlDataBinding as bt, ContentControlDateFormat as bu, ContentControlEntry as bv, ContentControlKind as bw, ContentControlLevel as bx, ContentControlListItem as by, ContentControlLock as bz, ReviewCommentItem as c, NameRejection as c2, NameResult as c3, OoxmlBodyNode as c6, OoxmlBookmarkEndNode as c7, OoxmlBookmarkStartNode as c8, OoxmlContentControlCalendarNode as c9, OoxmlReadResult as cA, OoxmlRunNode as cB, OoxmlRunPropertiesNode as cC, OoxmlTabNode as cD, OoxmlTextElementNode as cE, OoxmlTextNode as cF, OoxmlWmlValAttribute as cG, OoxmlXmlSpaceAttribute as cH, OverrideRecord as cI, RelationshipError as cJ, RelationshipSetResult as cK, RelationshipTargetResolver as cL, ResolveResult as cM, ResolvedRelationship as cN, SetFieldResultOp as cO, SetLegacyCheckboxOp as cP, SetLegacyDropdownOp as cQ, SetTextFormFieldDefaultOp as cR, TabStopWrite as cT, TargetMode as cU, TextFormFieldType as cV, TreeDocOpKind as cW, TreeOpEffect as cX, ValidatedRasterHeader as cY, OoxmlContentControlCheckboxNode as ca, OoxmlContentControlCheckedNode as cb, OoxmlContentControlCheckedStateNode as cc, OoxmlContentControlComboBoxNode as cd, OoxmlContentControlDataBindingNode as ce, OoxmlContentControlDateFormatNode as cf, OoxmlContentControlDateNode as cg, OoxmlContentControlDropDownListNode as ch, OoxmlContentControlEndPropertiesNode as ci, OoxmlContentControlLidNode as cj, OoxmlContentControlListItemNode as ck, OoxmlContentControlPropertiesNode as cl, OoxmlContentControlStoreMappedDataAsNode as cm, OoxmlContentControlTextNode as cn, OoxmlContentControlUncheckedStateNode as co, OoxmlDocumentNode as cp, OoxmlExternalTarget as cq, OoxmlGenericExtensionAttribute as cr, OoxmlHyperlinkNode as cs, OoxmlInvariantIssueCode as ct, OoxmlKnownNodeAttribute as cu, OoxmlNamespaceBinding as cv, OoxmlNodeIdentityRules as cw, OoxmlParagraphPropertiesNode as cx, OoxmlPartMetadata as cy, OoxmlReadRejection as cz, ReviewCustomItem as d, XmlLimits as d1, XmlNode as d2, XmlRejection as d3, XmlResult as d4, ZipLimits as d5, ZipReadResult as d6, ZipRejection as d7, ReviewPosition as e, VectorShapeComponent as eg, ReviewRange as f, ReviewRevisionKind as g, RevisionAddress as h, ContentControlType as i, DocTarget as j, RunFormatting as k, Extent as l, ContainerRef as m, ContentControlFilter as n, DocRange as o, Revision as p, DocComment as q, ColorValue as r, ContentControl as s, DocAnchor as t, DocAnchorRange as u, DocLocation as v, DocumentBody as w, ExecErrorCode as x, IndentFormatting as y, Paragraph as z };

package/dist/{tree-package-store-B8l8DX3Z.d.ts → tree-package-store-CRHvMyNj.d.ts}

@@ -1,4 +1,4 @@
-import { Q as OoxmlPackage, af as SupportedImageMime, O as OoxmlPart, N as OoxmlNode, ap as OoxmlElement, aH as PackageWatermarkWrite, aI as OoxmlInvariantIssue, aE as ImageDecodePort, aG as RevisionAttributionInput, aJ as DrawingTreeDocOp, aK as ImpactClass, ao as TreeDocOp, aC as TreeOpRejection, aL as OoxmlParagraphNode, aM as OoxmlNoteNode, aN as OoxmlContinuationSeparatorNode, aO as OoxmlEndnotesNode, aP as OoxmlFootnotesNode, aQ as OoxmlNoteRefNode, aR as OoxmlNoteReferenceNode, aS as OoxmlSeparatorNode } from './types-barrel-CkF2JbU4.js';
+import { a5 as OoxmlPackage, an as SupportedImageMime, O as OoxmlPart, a4 as OoxmlNode, av as OoxmlElement, aH as PackageWatermarkWrite, aI as OoxmlInvariantIssue, ad as ImageDecodePort, aF as RevisionAttributionInput, aJ as DrawingTreeDocOp, aK as ImpactClass, au as TreeDocOp, aG as TreeOpRejection, aL as OoxmlParagraphNode, aM as OoxmlNoteNode, aN as OoxmlContinuationSeparatorNode, aO as OoxmlEndnotesNode, aP as OoxmlFootnotesNode, aQ as OoxmlNoteRefNode, aR as OoxmlNoteReferenceNode, aS as OoxmlSeparatorNode } from './tree-op-types-C_S2niXW.js';
 
 /** A freshly allocated drawing property id, or the reason one could not be minted. */
 type DrawingPropertyIdResult = {
@@ -1382,4 +1382,4 @@ declare class TreePackageStore {
 }
 
 export { NOTE_CONTINUATION_SEPARATOR_ID as B, DEFAULT_MAX_EDITABLE_STORY_PARTS as D, NOTE_ID_MAX as G, NOTE_ID_MIN as J, NOTE_SEPARATOR_ID as K, MAX_FRAGMENT_DECODED_BYTES as M, TreePackageStore as T, allocateDrawingPropertyId as a8, allocateNoteId as a9, isNoteNode as aA, isNoteRefNode as aB, isNoteReferenceNode as aC, isSeparatorNode as aD, normalNoteIds as aE, noteAtomText as aF, noteIdOf as aG, noteKindOf as aH, noteRefKindOf as aI, noteReferenceKindOf as aJ, noteTypeOf as aK, notesOf as aL, notesPartHasId as aM, observeHistoryGroup as aN, parentNodeOf as aO, parseNoteId as aP, parseNoteScopeId as aQ, removeNode as aR, replaceChildren as aS, replaceNode as aT, resolveHeaderFooterParts as aU, resolveHeaderFooterPartsBySection as aV, resolveHeaderFooterResolutionBySection as aW, resolveNotesPart as aX, withBinaryPart as aY, withEmbeddedImage as aZ, withoutUnreferencedImagePart as a_, applyEdits as aa, applyFragmentPaste as ab, applyHeaderFooterLifecycleOp as ac, applyNoteLifecycleOp as ad, atomicNoteSpansOf as ae, cascadeDeletedNoteReferences as af, collectNodeIds as ag, collectNoteReferences as ah, collectPackageNoteReferences as ai, collectSectionPropertyNodes as aj, createNodeIdAllocator as ak, createNoteReferenceScanBudget as al, customMarkFollows as am, diagnoseNoteReferences as an, findNode as ao, findNoteById as ap, formatNoteScopeId as aq, hasNode as ar, insertChildren as as, isContinuationSeparatorNode as at, isEndnotesNode as au, isFootnotesNode as av, isHeaderFooterLifecycleOp as aw, isNormalNote as ax, isNoteAtomNode as ay, isNoteLifecycleOp as az, TreeDocumentStore as f, reportHistoryGroup as r, MAX_NOTES_PER_PART as w, MAX_NOTE_REFERENCE_PARTS as x, MAX_NOTE_REFERENCE_SCAN as y, NOTE_ATOM_CHAR as z };
-export type { PackageTransactResult as $, ApplyImagePropertiesInput as A, ContentLockPolicy as C, EditOptions as E, FieldResultsMode as F, HeaderFooterParts as H, InsertImageInput as I, NoteDiagnostic as L, NoteKind as N, NoteDiagnosticCode as O, NoteLifecycleImpact as P, NoteLifecycleOp as Q, ReplaceImageOptions as R, StoryScope as S, NoteLifecycleOptions as U, NoteLifecycleRejection as V, NoteLifecycleResult as W, NoteReferenceHit as X, NoteReferenceScanBudget as Y, NoteType as Z, OoxmlEditResult as _, HeaderFooterSectionResolution as a, RemotePackageAttribution as a0, StoryResolveResult as a1, TransactionRevisionIds as a2, TreeDocumentStoreOptions as a3, TreePackageStoreOptions as a4, TreeStoryRef as a5, TransactResult as a6, TransactionContext as a7, StoryTargetRejection as b, HeaderFooterVariant as c, HistoryGroup as d, TreeModelChange as e, SelectionMark as g, TransactOptions as h, ImageIntentResult as i, FragmentPasteInput as j, FragmentPasteResult as k, AtomicNoteSpan as l, CascadeDeletedNoteReferencesOptions as m, DrawingPropertyIdResult as n, HeaderFooterKind as o, HeaderFooterLifecycleImpact as p, HeaderFooterLifecycleOp as q, HeaderFooterLifecycleRejection as s, HeaderFooterLifecycleResult as t, HeaderFooterSlotMeta as u, HistoryCaptureKind as v };
+export type { PackageTransactResult as $, ApplyImagePropertiesInput as A, ContentLockPolicy as C, EditOptions as E, FieldResultsMode as F, HeaderFooterParts as H, InsertImageInput as I, NoteDiagnostic as L, NoteKind as N, NoteDiagnosticCode as O, NoteLifecycleImpact as P, NoteLifecycleOp as Q, ReplaceImageOptions as R, StoryScope as S, NoteLifecycleOptions as U, NoteLifecycleRejection as V, NoteLifecycleResult as W, NoteReferenceHit as X, NoteReferenceScanBudget as Y, NoteType as Z, OoxmlEditResult as _, StoryTargetRejection as a, RemotePackageAttribution as a0, StoryResolveResult as a1, TransactionRevisionIds as a2, TreeDocumentStoreOptions as a3, TreePackageStoreOptions as a4, TreeStoryRef as a5, TransactResult as a6, TransactionContext as a7, HeaderFooterSectionResolution as b, HeaderFooterVariant as c, HistoryGroup as d, TreeModelChange as e, SelectionMark as g, TransactOptions as h, ImageIntentResult as i, FragmentPasteInput as j, FragmentPasteResult as k, AtomicNoteSpan as l, CascadeDeletedNoteReferencesOptions as m, DrawingPropertyIdResult as n, HeaderFooterKind as o, HeaderFooterLifecycleImpact as p, HeaderFooterLifecycleOp as q, HeaderFooterLifecycleRejection as s, HeaderFooterLifecycleResult as t, HeaderFooterSlotMeta as u, HistoryCaptureKind as v };

package/dist/{tree-session-contract-DeLRqohz.d.ts → tree-session-contract-D1awo_dA.d.ts}

@@ -1,10 +1,10 @@
-import { S as StoryScope, g as SelectionMark, h as TransactOptions, d as HistoryGroup, b as StoryTargetRejection, e as TreeModelChange, H as HeaderFooterParts, a as HeaderFooterSectionResolution, I as InsertImageInput, i as ImageIntentResult, R as ReplaceImageOptions, A as ApplyImagePropertiesInput, j as FragmentPasteInput, k as FragmentPasteResult } from './tree-package-store-B8l8DX3Z.js';
-import { ao as TreeDocOp, O as OoxmlPart, N as OoxmlNode, Q as OoxmlPackage, ap as OoxmlElement, a as ReviewItem, af as SupportedImageMime, aE as ImageDecodePort, aG as RevisionAttributionInput } from './types-barrel-CkF2JbU4.js';
-import { D as DocumentTrackingSettings, I as InsertCustomNodeWrite, C as CustomNodeWriteResult, a as CustomNodeSweepOutcome, E as EmbeddedFont, B as BookmarkIndex, L as ListKind } from './custom-node-writes-TeUvMP13.js';
-import { H as HeadlessDocumentView, D as DocumentProperties } from './headless-document-view-qOpaCF82.js';
+import { S as StoryScope, g as SelectionMark, h as TransactOptions, d as HistoryGroup, a as StoryTargetRejection, e as TreeModelChange, H as HeaderFooterParts, b as HeaderFooterSectionResolution, I as InsertImageInput, i as ImageIntentResult, R as ReplaceImageOptions, A as ApplyImagePropertiesInput, j as FragmentPasteInput, k as FragmentPasteResult } from './tree-package-store-CRHvMyNj.js';
+import { au as TreeDocOp, O as OoxmlPart, a4 as OoxmlNode, a5 as OoxmlPackage, av as OoxmlElement, a as ReviewItem, an as SupportedImageMime, ad as ImageDecodePort, aF as RevisionAttributionInput } from './tree-op-types-C_S2niXW.js';
+import { D as DocumentTrackingSettings, I as InsertCustomNodeWrite, C as CustomNodeWriteResult, a as CustomNodeSweepOutcome, E as EmbeddedFont, B as BookmarkIndex, L as ListKind } from './custom-node-writes-CLJKGD9t.js';
+import { H as HeadlessDocumentView, D as DocumentProperties } from './headless-document-view-Bcz9_Qva.js';
 import { Node } from 'prosemirror-model';
 import { CollaborationDocumentPort } from './collaboration/replication.js';
-import { V as ViewScope } from './editor-scope-C7ke1KJG.js';
+import { V as ViewScope } from './editor-scope-B3L-1ALc.js';
 
 /**
  * Why an edited projection could not be mapped back into tree ops.

package/dist/unsupported-elements-CVos5cqe.d.ts

@@ -0,0 +1,23 @@
+import { U as UnsupportedElement } from './semantic-records-BvN-WWst.js';
+
+/** A component mount point and its built-in fallback. @public */
+interface UnsupportedElementHost {
+    /** Stable identity for one painted occurrence. */
+    readonly key: string;
+    readonly element: HTMLElement;
+    readonly fallback: HTMLElement;
+    readonly slot: HTMLElement;
+    readonly unsupported: UnsupportedElement;
+    /** Hide the default and expose custom controls to assistive technology. Restore with false. */
+    setCustomized(custom: boolean): void;
+}
+/**
+ * Observe placeholder mounts across repaint, pagination, and document replacement.
+ * The returned function disconnects the observer. Component mutations do not publish
+ * another list unless the engine's mount points change.
+ * @public
+ */
+declare function observeUnsupportedElements(container: HTMLElement, listener: (hosts: readonly UnsupportedElementHost[]) => void): () => void;
+
+export { observeUnsupportedElements as o };
+export type { UnsupportedElementHost as U };

package/docs/accept-reject-without-scrolling.md

@@ -0,0 +1,95 @@
+<!-- Generated from docs/site/content/recipes by scripts/sync-agent-docs.mjs. Edit the source and run `bun run docs:agent`. -->
+
+# Accept or reject without scrolling
+
+When your own list drives the scroll, open an item with `useReview().setActive(key, { reveal: false })`. The caret moves to the item, and the page stays where it is. Then resolve the item with `accept(item)` or `reject(item)`. Review writes such as accept, reject, and comment never scroll the page.
+
+**React**
+
+```tsx
+import { useReview, type ReviewItemView } from '@docx-editor.dev/pro/react';
+
+export function ChangeRow({ item }: { item: ReviewItemView }) {
+  const { setActive, accept, reject } = useReview();
+  return (
+    <li onClick={() => setActive(item.key, { reveal: false })}>
+      {item.text}
+      <button
+        disabled={item.readOnly}
+        onClick={(event) => {
+          event.stopPropagation();
+          accept(item);
+        }}
+      >
+        Accept
+      </button>
+      <button
+        disabled={item.readOnly}
+        onClick={(event) => {
+          event.stopPropagation();
+          reject(item);
+        }}
+      >
+        Reject
+      </button>
+    </li>
+  );
+}
+```
+
+`accept` and `reject` return `false` when the editor refuses the decision, for example in viewing mode. Read `useReview().lastRefusal` for the diagnostic code.
+
+**Vue**
+
+```vue
+<script setup lang="ts">
+import { useReview, type ReviewItemView } from '@docx-editor.dev/pro/vue';
+
+defineProps<{ item: ReviewItemView }>();
+const { setActive, accept, reject } = useReview();
+</script>
+
+<template>
+  <li @click="setActive(item.key, { reveal: false })">
+    {{ item.text }}
+    <button :disabled="item.readOnly" @click.stop="accept(item)">Accept</button>
+    <button :disabled="item.readOnly" @click.stop="reject(item)">Reject</button>
+  </li>
+</template>
+```
+
+`accept` and `reject` return `false` when the editor refuses the decision, for example in viewing mode. `useReview()` returns `lastRefusal` as a ref, so read `lastRefusal.value?.code` in script, or `lastRefusal?.code` in the template.
+
+The buttons stop the click from reaching the row, so a decision does not also activate the item.
+
+`reveal` takes `false` or one of four placements:
+
+| Value | Where the item lands |
+| --- | --- |
+| `'centerIfNeeded'` (default) | Stays still when the item is on screen; centered when it has to travel. |
+| `'center'` | Always centered. |
+| `'nearest'` | The smallest scroll that brings it into view. |
+| `'start'` | Near the top of the viewport. |
+
+Add `announce: true` to open the packaged balloon or card for the item.
+
+## Decide in a headless pipeline
+
+The editing API has no viewport. Load the revisions and call `Revision.accept()` or `Revision.reject()`.
+
+```ts
+import { DocxEditor } from '@docx-editor.dev/editor-api';
+
+const runtime = await DocxEditor.createServer(bytes, { author: 'Review bot' });
+await runtime.run(async (context) => {
+  const revisions = context.document.body.revisions;
+  revisions.load('items/author');
+  await context.sync();
+  for (const revision of revisions.items) {
+    if (revision.author === 'Review bot') revision.accept();
+  }
+  await context.sync();
+});
+const saved = await runtime.save();
+runtime.dispose();
+```

package/docs/comment-on-found-text.md

@@ -0,0 +1,72 @@
+<!-- Generated from docs/site/content/recipes by scripts/sync-agent-docs.mjs. Edit the source and run `bun run docs:agent`. -->
+
+# Comment on found text
+
+In a browser host, find the text with `editor.findMatches`, select the first match with `editor.selectMatch`, and then call `useReview().comment`. The comment is written as the editor's `author`, so set `author` on the editor and add `reviewModule()` to its modules. `selectMatch` opens the header, footer, or note that holds the match, so a match in any story works.
+
+**React**
+
+```tsx
+import { useDocxEditor } from '@docx-editor.dev/react';
+import { useReview } from '@docx-editor.dev/pro/react';
+
+export function CommentOnTerm({ term }: { term: string }) {
+  const editor = useDocxEditor();
+  const { comment } = useReview();
+  const run = () => {
+    const [match] = editor?.findMatches(term, { wholeWord: true }) ?? [];
+    if (match && editor?.selectMatch(match).ok) comment(`Define "${term}".`);
+  };
+  return <button onClick={run}>Comment on {term}</button>;
+}
+```
+
+`comment` returns `false` when the editor refuses the write. Read `useReview().lastRefusal` for the diagnostic code.
+
+**Vue**
+
+```vue
+<script setup lang="ts">
+import { useDocxEditor } from '@docx-editor.dev/vue';
+import { useReview } from '@docx-editor.dev/pro/vue';
+
+const props = defineProps<{ term: string }>();
+const editor = useDocxEditor();
+const { comment } = useReview();
+function run() {
+  const [match] = editor.value?.findMatches(props.term, { wholeWord: true }) ?? [];
+  if (match && editor.value?.selectMatch(match).ok) comment(`Define "${props.term}".`);
+}
+</script>
+
+<template>
+  <button @click="run">Comment on {{ term }}</button>
+</template>
+```
+
+`comment` returns `false` when the editor refuses the write. `useReview()` returns `lastRefusal` as a ref, so read `lastRefusal.value?.code` in script, or `lastRefusal?.code` in the template.
+
+## Comment in a headless pipeline
+
+On a server or in an agent pipeline, search the body and call `Range.insertComment`. The runtime writes the comment as its `author` option.
+
+```ts
+import { DocxEditor } from '@docx-editor.dev/editor-api';
+
+const runtime = await DocxEditor.createServer(bytes, { author: 'Review bot' });
+await runtime.run(async (context) => {
+  const found = context.document.body.search(term, { matchWholeWord: true });
+  found.load('items');
+  await context.sync();
+  found.items[0]?.insertComment(`Define "${term}".`);
+  await context.sync();
+});
+const saved = await runtime.save();
+runtime.dispose();
+```
+
+Both paths save the same comment markup: the same `w:comment` attributes, the same date format, and the same range markers.
+
+## Reply to a thread
+
+To answer an existing comment, call `useReview().reply(item, text)` in a browser host, or `Comment.reply(text)` in the editing API.

package/docs/custom-review-cards.md

@@ -0,0 +1,178 @@
+<!-- Generated from docs/site/content/recipes by scripts/sync-agent-docs.mjs. Edit the source and run `bun run docs:agent`. -->
+
+# Custom cards in the review rail
+
+To draw your own cards, render `DocxEditorReview` with `preset` set to `false` and put your card component inside it. Your component reads the items from `useReview()`, measures each card, stacks the cards with `useStackedReviewPositions`, and converts positions to pixels with `useReviewRailMetrics()`.
+
+Measure every card with a `ResizeObserver` and pass the heights in CSS pixels. Without measured heights, each card reserves only `defaultHeight`, and a taller card overlaps the next one.
+
+**React**
+
+```tsx
+import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react';
+import {
+  DocxEditorReview,
+  useReview,
+  useReviewRailMetrics,
+  useStackedReviewPositions,
+} from '@docx-editor.dev/pro/react';
+
+type OnHeight = (key: string, height: number) => void;
+
+function MeasuredCard({
+  id,
+  top,
+  onHeight,
+  children,
+}: {
+  id: string;
+  top: number;
+  onHeight: OnHeight;
+  children: ReactNode;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const node = ref.current!;
+    const observer = new ResizeObserver(() => onHeight(id, node.offsetHeight));
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [id, onHeight]);
+  return (
+    <div ref={ref} style={{ position: 'absolute', top }}>
+      {children}
+    </div>
+  );
+}
+
+function MyCards() {
+  const { items, selectionAnchorY, accept } = useReview();
+  const metrics = useReviewRailMetrics();
+  const [heights, setHeights] = useState<ReadonlyMap<string, number>>(() => new Map());
+  const onHeight = useCallback<OnHeight>(
+    (key, height) =>
+      setHeights((prev) => (prev.get(key) === height ? prev : new Map(prev).set(key, height))),
+    []
+  );
+  const positions = useStackedReviewPositions(items, heights, {
+    scale: metrics.scale,
+    defaultHeight: 96,
+  });
+  const top = (y: number) => metrics.top + y * metrics.scale;
+  return (
+    <>
+      {items.map((item) => (
+        <MeasuredCard
+          key={item.key}
+          id={item.key}
+          top={top(positions.get(item.key) ?? 0)}
+          onHeight={onHeight}
+        >
+          {item.text}
+          {item.kind === 'revision' && <button onClick={() => accept(item)}>Accept</button>}
+        </MeasuredCard>
+      ))}
+      <DocxEditorReview.Draft top={top(selectionAnchorY ?? 0)} />
+    </>
+  );
+}
+
+export function MyRail() {
+  return (
+    <DocxEditorReview preset={false}>
+      <MyCards />
+      <DocxEditorReview.AddComment />
+    </DocxEditorReview>
+  );
+}
+```
+
+The heights map gets a new reference only when a height changes, so the stack recomputes only then. Keep that rule if you store heights another way.
+
+**Vue**
+
+```vue
+<!-- MyCards.vue -->
+<script setup lang="ts">
+import { onBeforeUnmount, shallowReactive } from 'vue';
+import {
+  DocxEditorReview,
+  useReview,
+  useReviewRailMetrics,
+  useStackedReviewPositions,
+} from '@docx-editor.dev/pro/vue';
+
+const { items, selectionAnchorY, accept } = useReview();
+const { metrics } = useReviewRailMetrics();
+// Reactive, so a new measurement restacks the cards.
+const heights = shallowReactive(new Map<string, number>());
+const positions = useStackedReviewPositions(items, heights, () => ({
+  scale: metrics.value.scale,
+  defaultHeight: 96,
+}));
+const top = (y: number) => `${metrics.value.top + y * metrics.value.scale}px`;
+
+const observed = new Map<string, { el: Element; observer: ResizeObserver }>();
+function measure(key: string, el: unknown) {
+  const current = observed.get(key);
+  if (current?.el === el) return;
+  current?.observer.disconnect();
+  observed.delete(key);
+  if (!(el instanceof HTMLElement)) {
+    heights.delete(key);
+    return;
+  }
+  const observer = new ResizeObserver(() => heights.set(key, el.offsetHeight));
+  observer.observe(el);
+  observed.set(key, { el, observer });
+}
+onBeforeUnmount(() => observed.forEach(({ observer }) => observer.disconnect()));
+</script>
+
+<template>
+  <div
+    v-for="item in items"
+    :key="item.key"
+    :ref="(el) => measure(item.key, el)"
+    :style="{ position: 'absolute', top: top(positions.get(item.key) ?? 0) }"
+  >
+    {{ item.text }}
+    <button v-if="item.kind === 'revision'" @click="accept(item)">Accept</button>
+  </div>
+  <DocxEditorReview.Draft :top="metrics.top + (selectionAnchorY ?? 0) * metrics.scale" />
+</template>
+```
+
+```vue
+<!-- MyRail.vue -->
+<script setup lang="ts">
+import { DocxEditorReview } from '@docx-editor.dev/pro/vue';
+import MyCards from './MyCards.vue';
+</script>
+
+<template>
+  <DocxEditorReview :preset="false">
+    <MyCards />
+    <DocxEditorReview.AddComment />
+  </DocxEditorReview>
+</template>
+```
+
+A plain `Map` is not reactive, so writes to it would not restack the cards. Use `shallowReactive(new Map())`, or a ref that you replace on each change.
+
+## Root parts and card parts
+
+`DocxEditorReview` finds its parts among its own children by element type.
+
+- **Root parts** are `List`, `Markers`, `AddComment`, `Draft`, and `Balloon`. Put them as direct children of `DocxEditorReview`. Fragments are transparent in React and in Vue. The rail gives these parts geometry that only it can compute, such as the comment button's `top`. A root part inside your own wrapper component is not a part. It renders as ordinary content, without that wiring.
+- **Card parts** are `Card`, `Empty`, and the parts inside a card, such as `Author`, `Summary`, `Accept`, and `Reply`. Put them inside `DocxEditorReview.List`.
+
+With `preset` set to `false`, the rail adds no defaults. Root parts that you pass keep their wiring. Every other child renders as is inside the rail element, where `useReviewRailMetrics()` reads the rail's own measurement.
+
+## Position the compose box
+
+`DocxEditorReview.Draft` renders only while a comment draft is open. A draft opens from `DocxEditorReview.AddComment` or from the `review.addComment` toolbar control. You can place `Draft` in either of these places:
+
+- As a direct child of `DocxEditorReview`.
+- Inside your own card component, as in the example. It still renders only while the draft is open.
+
+Without `top`, the box sits where the packaged card stack puts it. That position comes from the packaged cards, not yours, so when you render your own cards, pass `top` from your own stack. In the narrow compact rail, the box takes the compact card's `left` in both cases, so it does not overflow the marker strip. The example places the box at the selection's anchor. To keep it clear of your cards, add an entry with the key of your choice and the anchor `selectionAnchorY` to the list that you pass to `useStackedReviewPositions`, in document order.