@docx-editor.dev/core 2.8.0 → 2.9.0

package/dist/{review-support--I4ChuzF.d.ts → review-items-D5SPFtsO.d.ts}

@@ -1,5 +1,5 @@
-import { e as OoxmlPart, a as OoxmlElement } from './ooxml-tree-BU0e3DVi.js';
-import { R as RevisionAddress } from './tree-op-types-BbzrA-kg.js';
+import { b as OoxmlElement, O as OoxmlPart, c as OoxmlPackage } from './ooxml-package-CdEy9ufK.js';
+import { R as RevisionAddress } from './tree-op-types-XMVsJSpe.js';
 
 /** The `w15` namespace: `commentsExtended.xml` — thread parent and resolved state. */
 declare const W15_NAMESPACE_URI = "http://schemas.microsoft.com/office/word/2012/wordml";
@@ -32,7 +32,7 @@ interface CommentRecord {
     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 first body paragraph — the key thread state is stored under. */
+    /** `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;
@@ -43,6 +43,41 @@ interface CommentThreadState {
     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;
@@ -136,8 +171,8 @@ interface ReviewRevisionItem {
     /**
      * True when the engine cannot resolve this kind, so accept and reject must not be offered.
      *
-     * Derived by the MODULE 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
+     * 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;
@@ -227,6 +262,9 @@ interface ReviewCustomItem {
 /**
  * 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. */
@@ -251,6 +289,11 @@ interface ReviewModelInput {
      * `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.
      *
@@ -259,11 +302,6 @@ interface ReviewModelInput {
      * input on both members; a capability package validates it against whatever shape it
      * declared before handing it to a host.
      */
-    /**
-     * 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;
     readonly customNodePayloads?: ReadonlyMap<string, {
         readonly nodeId: string;
         readonly label: string;
@@ -272,11 +310,6 @@ interface ReviewModelInput {
 }
 /** The stable key a surface uses for the active item and for a React list. */
 declare function reviewItemKey(item: ReviewItem): string;
-/** Plain text of a comment's body, so a card never re-implements the run walk. */
-declare function commentBodyText(comment: CommentRecord): string;
-/** Author initials for an avatar, from `@w:initials` or the name. */
-declare function commentInitials(comment: CommentRecord): 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. */
@@ -324,91 +357,5 @@ declare function activeReviewItem(items: readonly ReviewItem[], position: Review
  * moment a reply could answer a revision, which outranks it outright.
  */
 declare function reviewThreadRootOf(items: readonly ReviewItem[], comment: ReviewCommentItem): ReviewItem;
-/** Where one paragraph sits, resolved once so a card is an O(1) lookup. */
-interface ReviewParagraphAnchor {
-    readonly pageIndex: number;
-    /** Sheet-absolute y of the page's content box. */
-    readonly contentY: number;
-    /** The fragment's own y, measured from that content box. */
-    readonly fragmentY: number;
-    readonly lines?: readonly {
-        readonly range: {
-            readonly end: number;
-        };
-        readonly box: {
-            readonly y: number;
-        };
-        /**
-         * Present on a real line. A merged fragment's join line carries spans from two
-         * paragraphs, and its `range` can only name one of them, so the OTHER paragraph's extent
-         * on that line is readable here and nowhere else.
-         */
-        readonly spans?: readonly {
-            readonly range: {
-                readonly paragraphId: string;
-                readonly end: number;
-            };
-        }[];
-    }[];
-}
-/**
- * The y of the line a position sits on, measured from the anchor's own origin.
- *
- * An ordinary line answers from its own range, exactly as it always did. On a merged
- * fragment's join line the range names one of the two paragraphs, so an offset compared
- * against it either overshot — putting a card in the absorbed half beside the wrong line —
- * or matched the first line every time.
- */
-declare function anchorLineY(anchor: ReviewParagraphAnchor, paragraphId: string, offset: number): number;
-/**
- * Paragraph id to its place on the page, in ONE pass over the layout.
- *
- * Built once per layout and reused by every card. The straightforward version — scan the
- * pages until the paragraph turns up, per card — is a full-document walk per card, and a
- * contract with two hundred comments walked the document two hundred times every time the
- * caret moved. Toggling the pane was visibly slow for exactly that reason.
- */
-declare function reviewAnchorIndex<TPage extends {
-    readonly index: number;
-    readonly contentBox: {
-        readonly y: number;
-    };
-}>(layout: {
-    readonly pages: readonly TPage[];
-}, paragraphFragments: (page: TPage) => readonly {
-    readonly paragraphId: string;
-    readonly box: {
-        readonly y: number;
-    };
-    readonly lines?: readonly {
-        readonly range: {
-            readonly end: number;
-        };
-        readonly box: {
-            readonly y: number;
-        };
-        /** Present on a real line; a merged one carries spans from more than one paragraph. */
-        readonly spans?: readonly {
-            readonly range: {
-                readonly paragraphId: string;
-                readonly end: number;
-            };
-        }[];
-    }[];
-}[]): Map<string, ReviewParagraphAnchor>;
-/**
- * Where a card belongs beside the page, from LAYOUT RECORDS.
- *
- * The one question the tree cannot answer, and the one a surface must not answer for itself:
- * measuring painted DOM puts the sidebar a repaint behind the document and breaks outright
- * while pagination is in flight.
- *
- * Returns null when the item has no resolvable range, or when its paragraph is not in this
- * layout — a comment anchored in a header belongs to a story the body layout never saw.
- */
-declare function reviewItemGeometry(item: ReviewItem, index: ReadonlyMap<string, ReviewParagraphAnchor>): {
-    readonly pageIndex: number;
-    readonly y: number;
-} | null;
 
-export { type CommentRecord as C, type ReviewModelInput as R, W15_NAMESPACE_URI as W, type ReviewItem as a, type ReviewRevisionItem as b, type ReviewCommentItem as c, type ReviewCustomItem as d, type ReviewPosition as e, type ReviewRange as f, type ReviewRevisionKind as g, type CommentAnchor as h, type CommentPosition as i, type CommentThreadState as j, type ReviewParagraphAnchor as k, activeReviewItem as l, anchorLineY as m, commentBodyText as n, commentInitials as o, firstReviewRange as p, reviewItemGeometry as q, reviewAnchorIndex as r, reviewItemKey as s, reviewItemPositionRank as t, reviewItemRanges as u, reviewItemsAt as v, reviewThreadRootOf as w };
+export { type CommentRecord as C, type ReviewModelInput as R, W15_NAMESPACE_URI as W, type ReviewItem as a, type ReviewRevisionItem as b, type ReviewCommentItem as c, type ReviewCustomItem as d, type ReviewPosition as e, type ReviewRange as f, type ReviewRevisionKind as g, type CommentThreadState as h, type CommentAnchor as i, type CommentPosition as j, activeReviewItem as k, firstReviewRange as l, reviewItemPositionRank as m, reviewItemRanges as n, reviewItemsAt as o, reviewThreadRootOf as p, commentAnchorsOfStory as q, reviewItemKey as r, commentsOfPart as s, hasAnyComment as t, threadStateOfPart as u };

package/dist/{review-support-CG7aVSPh.d.cts → review-items-DpsqTHio.d.cts}

@@ -1,5 +1,5 @@
-import { e as OoxmlPart, a as OoxmlElement } from './ooxml-tree-BU0e3DVi.cjs';
-import { R as RevisionAddress } from './tree-op-types-A-SLSKzK.cjs';
+import { b as OoxmlElement, O as OoxmlPart, c as OoxmlPackage } from './ooxml-package-CdEy9ufK.cjs';
+import { R as RevisionAddress } from './tree-op-types-B0-sCtw-.cjs';
 
 /** The `w15` namespace: `commentsExtended.xml` — thread parent and resolved state. */
 declare const W15_NAMESPACE_URI = "http://schemas.microsoft.com/office/word/2012/wordml";
@@ -32,7 +32,7 @@ interface CommentRecord {
     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 first body paragraph — the key thread state is stored under. */
+    /** `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;
@@ -43,6 +43,41 @@ interface CommentThreadState {
     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;
@@ -136,8 +171,8 @@ interface ReviewRevisionItem {
     /**
      * True when the engine cannot resolve this kind, so accept and reject must not be offered.
      *
-     * Derived by the MODULE 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
+     * 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;
@@ -227,6 +262,9 @@ interface ReviewCustomItem {
 /**
  * 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. */
@@ -251,6 +289,11 @@ interface ReviewModelInput {
      * `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.
      *
@@ -259,11 +302,6 @@ interface ReviewModelInput {
      * input on both members; a capability package validates it against whatever shape it
      * declared before handing it to a host.
      */
-    /**
-     * 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;
     readonly customNodePayloads?: ReadonlyMap<string, {
         readonly nodeId: string;
         readonly label: string;
@@ -272,11 +310,6 @@ interface ReviewModelInput {
 }
 /** The stable key a surface uses for the active item and for a React list. */
 declare function reviewItemKey(item: ReviewItem): string;
-/** Plain text of a comment's body, so a card never re-implements the run walk. */
-declare function commentBodyText(comment: CommentRecord): string;
-/** Author initials for an avatar, from `@w:initials` or the name. */
-declare function commentInitials(comment: CommentRecord): 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. */
@@ -324,91 +357,5 @@ declare function activeReviewItem(items: readonly ReviewItem[], position: Review
  * moment a reply could answer a revision, which outranks it outright.
  */
 declare function reviewThreadRootOf(items: readonly ReviewItem[], comment: ReviewCommentItem): ReviewItem;
-/** Where one paragraph sits, resolved once so a card is an O(1) lookup. */
-interface ReviewParagraphAnchor {
-    readonly pageIndex: number;
-    /** Sheet-absolute y of the page's content box. */
-    readonly contentY: number;
-    /** The fragment's own y, measured from that content box. */
-    readonly fragmentY: number;
-    readonly lines?: readonly {
-        readonly range: {
-            readonly end: number;
-        };
-        readonly box: {
-            readonly y: number;
-        };
-        /**
-         * Present on a real line. A merged fragment's join line carries spans from two
-         * paragraphs, and its `range` can only name one of them, so the OTHER paragraph's extent
-         * on that line is readable here and nowhere else.
-         */
-        readonly spans?: readonly {
-            readonly range: {
-                readonly paragraphId: string;
-                readonly end: number;
-            };
-        }[];
-    }[];
-}
-/**
- * The y of the line a position sits on, measured from the anchor's own origin.
- *
- * An ordinary line answers from its own range, exactly as it always did. On a merged
- * fragment's join line the range names one of the two paragraphs, so an offset compared
- * against it either overshot — putting a card in the absorbed half beside the wrong line —
- * or matched the first line every time.
- */
-declare function anchorLineY(anchor: ReviewParagraphAnchor, paragraphId: string, offset: number): number;
-/**
- * Paragraph id to its place on the page, in ONE pass over the layout.
- *
- * Built once per layout and reused by every card. The straightforward version — scan the
- * pages until the paragraph turns up, per card — is a full-document walk per card, and a
- * contract with two hundred comments walked the document two hundred times every time the
- * caret moved. Toggling the pane was visibly slow for exactly that reason.
- */
-declare function reviewAnchorIndex<TPage extends {
-    readonly index: number;
-    readonly contentBox: {
-        readonly y: number;
-    };
-}>(layout: {
-    readonly pages: readonly TPage[];
-}, paragraphFragments: (page: TPage) => readonly {
-    readonly paragraphId: string;
-    readonly box: {
-        readonly y: number;
-    };
-    readonly lines?: readonly {
-        readonly range: {
-            readonly end: number;
-        };
-        readonly box: {
-            readonly y: number;
-        };
-        /** Present on a real line; a merged one carries spans from more than one paragraph. */
-        readonly spans?: readonly {
-            readonly range: {
-                readonly paragraphId: string;
-                readonly end: number;
-            };
-        }[];
-    }[];
-}[]): Map<string, ReviewParagraphAnchor>;
-/**
- * Where a card belongs beside the page, from LAYOUT RECORDS.
- *
- * The one question the tree cannot answer, and the one a surface must not answer for itself:
- * measuring painted DOM puts the sidebar a repaint behind the document and breaks outright
- * while pagination is in flight.
- *
- * Returns null when the item has no resolvable range, or when its paragraph is not in this
- * layout — a comment anchored in a header belongs to a story the body layout never saw.
- */
-declare function reviewItemGeometry(item: ReviewItem, index: ReadonlyMap<string, ReviewParagraphAnchor>): {
-    readonly pageIndex: number;
-    readonly y: number;
-} | null;
 
-export { type CommentRecord as C, type ReviewModelInput as R, W15_NAMESPACE_URI as W, type ReviewItem as a, type ReviewRevisionItem as b, type ReviewCommentItem as c, type ReviewCustomItem as d, type ReviewPosition as e, type ReviewRange as f, type ReviewRevisionKind as g, type CommentAnchor as h, type CommentPosition as i, type CommentThreadState as j, type ReviewParagraphAnchor as k, activeReviewItem as l, anchorLineY as m, commentBodyText as n, commentInitials as o, firstReviewRange as p, reviewItemGeometry as q, reviewAnchorIndex as r, reviewItemKey as s, reviewItemPositionRank as t, reviewItemRanges as u, reviewItemsAt as v, reviewThreadRootOf as w };
+export { type CommentRecord as C, type ReviewModelInput as R, W15_NAMESPACE_URI as W, type ReviewItem as a, type ReviewRevisionItem as b, type ReviewCommentItem as c, type ReviewCustomItem as d, type ReviewPosition as e, type ReviewRange as f, type ReviewRevisionKind as g, type CommentThreadState as h, type CommentAnchor as i, type CommentPosition as j, activeReviewItem as k, firstReviewRange as l, reviewItemPositionRank as m, reviewItemRanges as n, reviewItemsAt as o, reviewThreadRootOf as p, commentAnchorsOfStory as q, reviewItemKey as r, commentsOfPart as s, hasAnyComment as t, threadStateOfPart as u };

package/dist/review-reads-B2Ji3fVU.d.ts

@@ -0,0 +1,176 @@
+import { a as OoxmlNode, b as OoxmlElement, p as OoxmlContentControlNode, m as OoxmlGenericElementNode, q as OoxmlContentControlContentNode, O as OoxmlPart } from './ooxml-package-CdEy9ufK.js';
+import { C as CommentRecord, f as ReviewRange, R as ReviewModelInput, a as ReviewItem, e as ReviewPosition, h as CommentThreadState, c as ReviewCommentItem, b as ReviewRevisionItem } from './review-items-D5SPFtsO.js';
+
+/** Nested content-control wrappers deeper than this stop flattening; content stays preserved. */
+declare const MAX_CONTENT_CONTROL_NESTING = 32;
+type ContentControlLike = OoxmlContentControlNode | OoxmlGenericElementNode;
+type ContentControlContentLike = OoxmlContentControlContentNode | OoxmlGenericElementNode;
+/**
+ * Block or inline structured-document-tag wrapper — typed or generic during migration.
+ *
+ * Generic fallback requires the WordprocessingML namespace so foreign-namespace
+ * `<x:sdt>` elements stay opaque wrappers and are never treated as Word controls.
+ */
+declare function isContentControl(node: OoxmlNode): node is ContentControlLike;
+/**
+ * True when `node` is the control's content container (`w:sdtContent`).
+ *
+ * Generic `sdtContent` requires the WML namespace — same foreign-namespace rule as
+ * {@link isContentControl}.
+ */
+declare function isContentControlContent(node: OoxmlNode): node is ContentControlContentLike;
+/** Children of the first `w:sdtContent` under a control, or null when absent or not a control. */
+declare function contentControlContentOf(node: OoxmlNode): readonly OoxmlNode[] | null;
+/**
+ * Children of every `w:sdtContent` under a control, in document order.
+ *
+ * Does not recurse into nested controls — callers that flatten blocks or inline runs do that
+ * with their own depth counter against {@link MAX_CONTENT_CONTROL_NESTING}.
+ */
+declare function contentControlContentChildren(control: OoxmlNode): readonly OoxmlNode[];
+/**
+ * Collect paragraph and table blocks from a sibling list, flattening through content-control
+ * wrappers up to {@link MAX_CONTENT_CONTROL_NESTING}.
+ *
+ * `accept` filters which typed blocks are kept (e.g. skip revision-removed paragraphs). When
+ * nesting exceeds the bound the wrapper is skipped entirely — same fail-closed rule as the
+ * historical `storyBlocks` walk.
+ */
+declare function collectFlowBlocks(children: readonly OoxmlNode[], depth?: number, accept?: (block: OoxmlElement) => boolean): OoxmlElement[];
+/**
+ * Story blocks in document order, flattening block-level content controls — same shape as
+ * layout's `storyBlocks` and store `bodyBlocks`.
+ */
+declare function walkStoryBlocks(children: readonly OoxmlNode[], depth: number, visit: (block: OoxmlElement) => void): void;
+/**
+ * Every story paragraph in reading order — body, table cells, and flattened block controls.
+ */
+declare function walkAllStoryParagraphs(children: readonly OoxmlNode[], sdtDepth: number, visit: (paragraph: OoxmlElement) => void): void;
+/**
+ * Paragraph-level inline sequence — runs, hyperlinks, and inline content controls in order.
+ *
+ * `visit` receives each direct `w:r` and any other inline node the caller treats as opaque
+ * (bookmarks, drawings, …). Hyperlinks and content controls are descended transparently.
+ */
+declare function walkParagraphInline(children: readonly OoxmlNode[], depth: number, visit: (child: OoxmlNode) => void): void;
+
+/** Plain text of a comment's body, so a card never re-implements the run walk. */
+declare function commentBodyText(comment: CommentRecord): string;
+/** Author initials for an avatar, from `@w:initials` or the name. */
+declare function commentInitials(comment: CommentRecord): string;
+/**
+ * Every revision in one story, one card per DECISION.
+ *
+ * Sites sharing an `(id, author, date)` triple are ONE revision — a tracked row insertion is
+ * `w:trPr/w:ins` plus `w:cellIns` on every cell — so they coalesce into one card listing every
+ * range it touches. Keying per site would show the reviewer four decisions where there is one,
+ * and accepting any of them would make the other three vanish.
+ *
+ * Memoized per part root like the indexes it reads, and for the same reason: a heavily
+ * tracked document produces tens of thousands of cards, and rebuilding them per read cost
+ * more than everything the memos above saved. The paragraph-scoped view the local review
+ * patch derives (`revisionItemsOfParagraph`'s synthetic paragraph-root part) is NOT cached:
+ * each keystroke would insert a fresh root and churn the bounded ring. The instance is
+ * SHARED, so the return type is readonly.
+ */
+declare function revisionItemsOf(part: OoxmlPart): readonly ReviewRevisionItem[];
+/**
+ * Comment cards, threaded however the file says so and flat when nothing says so.
+ *
+ * ECMA-376 §17.13.4.2 gives `CT_Comment` no parent pointer, so threading is never something
+ * the standard states outright. Three sources, strongest first: `@w15:paraIdParent`, then
+ * `@w16cid:parentId` — both in namespaces outside Part 1 — and finally a COINCIDENT anchor, a
+ * comment whose `w:commentRangeStart`/`End` cover exactly the characters an earlier comment's
+ * cover. The ranges are Part 1's own vocabulary and the only part of a thread that survives a
+ * producer dropping the extension parts. Coincidence is the last resort and never overrides a
+ * stated link.
+ *
+ * Deliberately not containment. A remark on one word inside another remark's sentence nests
+ * without being a reply, and reading that as a thread would bury an independent comment inside
+ * someone else's.
+ */
+declare function commentItemsOf(comments: readonly CommentRecord[], anchors: readonly {
+    commentId: string;
+    partName: string;
+    start: ReviewPosition;
+    end: ReviewPosition;
+    orphaned: boolean;
+}[], threadState: ReadonlyMap<string, CommentThreadState>): ReviewCommentItem[];
+/**
+ * Everything the review surface lists, in document order.
+ *
+ * Order is by paragraph position within the story, then by offset. A comment and the revision
+ * it covers therefore arrive together, which is what lets a surface group them. Furniture
+ * stories rank after the body in one merged order — their geometry (the page they first paint
+ * on) is a layout question the queue deliberately does not answer.
+ */
+declare function collectReviewItems(input: ReviewModelInput): ReviewItem[];
+/**
+ * The shape {@link linkRevisionReplies} needs, stated STRUCTURALLY.
+ *
+ * The store's queue is revisions and comments; the layout lane's adds a third kind for custom
+ * nodes, and neither union is assignable to the other. Both lanes have to run this pass — the
+ * store on the full derivation, the session on the locally patched list — so the pass is
+ * written against the fields it actually reads rather than against either union, and hands
+ * back the caller's own item type.
+ */
+interface LinkableReviewItem {
+    readonly kind: string;
+    readonly id: string;
+    readonly ranges?: readonly ReviewRange[];
+    readonly range?: ReviewRange | null;
+    readonly parentId?: string;
+    readonly parentRevisionId?: string;
+    readonly replyIds?: readonly string[];
+    readonly orphaned?: boolean;
+    /** How deeply a revision is nested; absent on the kinds that cannot nest. */
+    readonly nesting?: number;
+}
+/**
+ * Attach each comment that answers a tracked change to the change it answers.
+ *
+ * The evidence is the RANGE, exactly as it is for a coincident comment thread: replying to a
+ * revision writes a comment over that revision's own characters, because OOXML gives `w:ins`
+ * and `w:del` nowhere else to put the text. Without this the reply came back as an independent
+ * card in the rail, sitting beside the change rather than inside it, and the reader had no way
+ * to see which change their answer belonged to.
+ *
+ * Three things keep it from over-claiming. A ZERO-WIDTH range is evidence of nothing — the same
+ * rule the comment threading uses, and a format or paragraph-mark revision decorates no
+ * characters at all. A comment already stated to be a REPLY to another comment is not claimed
+ * directly, because a stated link always beats an inferred one. And the FIRST revision on a span
+ * wins, so a card cannot claim a reply another card already holds.
+ *
+ * The WHOLE conversation moves, not its head. A change's card renders `replyIds` as a flat list,
+ * so linking only the top comment of a thread left every answer to that answer rendered by
+ * nobody: reply twice to one change and the second reply existed in `comments.xml` and appeared
+ * nowhere on screen. Descendants ride along, in the order they were authored.
+ *
+ * IDEMPOTENT, and that is load-bearing. The session re-runs this over a list whose comments are
+ * ALREADY linked, so a pass that only ever added links left a stale `parentRevisionId` behind
+ * when a keystroke shifted the revision's offsets out from under it — the rail filters such a
+ * comment out of its roots, and with no revision claiming it any more the card vanished until
+ * the next full re-derivation. Every link is rebuilt from the ranges on every pass.
+ */
+declare function linkRevisionReplies<T extends LinkableReviewItem>(items: readonly T[]): T[];
+/**
+ * Paragraph node id → document position, from the TREE rather than from a layout.
+ *
+ * Memoized on the immutable root: one full derivation pass asks this question three times
+ * (replacement pairing, the queue's merged order, the session's cached order), and each
+ * answer was a fresh full-tree walk. The instance is SHARED, so the return type is
+ * ReadonlyMap: a caller mutating it would poison every later reader of this root.
+ */
+declare function paragraphOrderOfPart(part: OoxmlPart): ReadonlyMap<string, number>;
+/**
+ * Like {@link paragraphOrderOfPart}, but descends INTO paragraphs, so paragraphs nested
+ * in a run's content — a textbox's `w:txbxContent` — rank right after their host.
+ *
+ * A separate function on purpose: the shallow order feeds the review queue's card
+ * ordering, and re-ranking nested paragraphs there would move cards. This one exists for
+ * position containment tests ("is the caret inside this range"), where a paragraph the
+ * shallow order cannot see is a position that can never match.
+ */
+declare function deepParagraphOrderOfPart(part: OoxmlPart): ReadonlyMap<string, number>;
+
+export { type LinkableReviewItem as L, MAX_CONTENT_CONTROL_NESTING as M, commentBodyText as a, commentInitials as b, collectFlowBlocks as c, contentControlContentChildren as d, isContentControlContent as e, collectReviewItems as f, commentItemsOf as g, contentControlContentOf as h, isContentControl as i, deepParagraphOrderOfPart as j, walkParagraphInline as k, linkRevisionReplies as l, walkStoryBlocks as m, paragraphOrderOfPart as p, revisionItemsOf as r, walkAllStoryParagraphs as w };