@extend-ai/react-docx 0.7.0-alpha.4 → 0.7.0-alpha.6

package/dist/index.d.cts

@@ -401,6 +401,17 @@ interface DocumentNoteDefinition {
     text: string;
     nodes?: DocNode[];
 }
+interface DocumentCommentDefinition {
+    id: number;
+    author?: string;
+    initials?: string;
+    date?: string;
+    text: string;
+    /** Comment id this comment replies to (from commentsExtended threading). */
+    parentId?: number;
+    /** True when the comment thread is marked done in commentsExtended. */
+    resolved?: boolean;
+}
 interface DocumentCompatibilitySettings {
     suppressSpacingBeforeAfterPageBreak?: boolean;
     usePrinterMetrics?: boolean;
@@ -427,6 +438,7 @@ interface DocModel {
         compatibility?: DocumentCompatibilitySettings;
         footnotes?: DocumentNoteDefinition[];
         endnotes?: DocumentNoteDefinition[];
+        comments?: DocumentCommentDefinition[];
     };
 }
 
@@ -618,6 +630,32 @@ interface DocxTrackedChange {
     nodeIndex: number;
     location: DocxTextRangeLocation;
 }
+/**
+ * A document comment anchored to a text range.
+ *
+ * Comment definitions come from `word/comments.xml` (threading and resolution
+ * state from `word/commentsExtended.xml`); the anchor location is resolved
+ * from the paragraph that carries the `commentReference` run.
+ */
+interface DocxComment {
+    /** Stable identifier (unique per rendered anchor). */
+    id: string;
+    /** Comment id from `word/comments.xml` (`w:id`). */
+    commentId: number;
+    author?: string;
+    initials?: string;
+    date?: string;
+    /** Plain-text comment body. */
+    text: string;
+    /** Comment id this comment replies to, when part of a thread. */
+    parentId?: number;
+    /** True when the comment thread is marked done. */
+    resolved?: boolean;
+    /** Plain-text excerpt of the commented document range. */
+    anchorText?: string;
+    nodeIndex: number;
+    location: DocxTextRangeLocation;
+}
 type DocxLineSpacingRule = "auto" | "exact" | "atLeast";
 type DocxSelectionSessionKind = "idle" | "pointer" | "keyboard" | "composition" | "command" | "history-restore";
 interface DocxLineSpacingInfo {
@@ -665,6 +703,12 @@ interface UseDocxEditorOptions {
      * @defaultValue `false`
      */
     initialShowTrackedChanges?: boolean;
+    /**
+     * Whether document comments are visible when the editor first mounts.
+     *
+     * @defaultValue `false`
+     */
+    initialShowComments?: boolean;
 }
 /**
  * Controller returned by `useDocxEditor`.
@@ -713,6 +757,8 @@ interface DocxEditorController {
     availableParagraphStyles: ParagraphStyleDefinition[];
     trackedChanges: DocxTrackedChange[];
     showTrackedChanges: boolean;
+    comments: DocxComment[];
+    showComments: boolean;
     currentPage: number;
     totalPages: number;
     hasUnorderedList: boolean;
@@ -723,8 +769,10 @@ interface DocxEditorController {
     setStatus: React.Dispatch<React.SetStateAction<string>>;
     setDocumentTheme: (theme: DocxDocumentTheme) => void;
     setShowTrackedChanges: (showTrackedChanges: boolean) => void;
+    setShowComments: (showComments: boolean) => void;
     syncPaginationInfo: (pagination: DocxPaginationInfo) => void;
     toggleShowTrackedChanges: () => void;
+    toggleShowComments: () => void;
     importDocxFile: (file: File) => Promise<void>;
     newDocument: () => void;
     exportDocx: () => void;
@@ -920,6 +968,22 @@ interface DocxPageVirtualizationOptions {
      * @defaultValue `0`
      */
     settleDelayMs?: number;
+    /**
+     * Explicit scroll container for internal page virtualization.
+     *
+     * Omit this to let the viewer discover the nearest scrollable ancestor.
+     * Provide it when the host app owns scrolling, such as when the viewer is
+     * mounted inside a custom scroll-area viewport.
+     */
+    scrollElement?: HTMLElement | null;
+    /**
+     * Effective visual scale applied around the viewer.
+     *
+     * Omit this to let the viewer infer CSS `zoom` from its ancestor chain.
+     * Provide it when toolbar zoom is controlled outside the viewer so virtual
+     * page offsets update synchronously with the selected zoom.
+     */
+    zoomScale?: number;
 }
 /**
  * Externally controlled visible page window.
@@ -1048,6 +1112,17 @@ interface DocxEditorViewerProps {
      * Custom renderer for tracked-change cards in the page gutter.
      */
     renderTrackedChangeCard?: (props: DocxTrackedChangeCardRenderProps) => React.ReactNode;
+    /**
+     * Overrides whether document comments are shown.
+     *
+     * If omitted, the value from `useDocxComments(editor)` or
+     * `editor.showComments` is used.
+     */
+    showComments?: boolean;
+    /**
+     * Custom renderer for comment cards in the page gutter.
+     */
+    renderCommentCard?: (props: DocxCommentCardRenderProps) => React.ReactNode;
     /**
      * Custom renderer for table context menus.
      *
@@ -1085,6 +1160,22 @@ interface DocxTrackedChangeCardRenderProps {
     /** Positioning style computed by the viewer. Apply this to the card root. */
     style: React.CSSProperties;
 }
+interface DocxCommentCardRenderProps {
+    /** Comment data represented by the card. */
+    comment: DocxComment;
+    /** Plain-text comment body (already normalized for display). */
+    snippet: string;
+    /** Formatted comment date, if the source document provided one. */
+    formattedDate?: string;
+    /** Accent color chosen for comments. */
+    accentColor: string;
+    /** Current document theme. */
+    documentTheme: DocxDocumentTheme;
+    /** Zero-based page index that owns the card. */
+    pageIndex: number;
+    /** Positioning style computed by the viewer. Apply this to the card root. */
+    style: React.CSSProperties;
+}
 /**
  * Viewer interaction mode.
  *
@@ -1129,6 +1220,14 @@ interface UseDocxTrackChangesResult {
     changesByLocation: Map<string, DocxTrackedChange[]>;
     getChangesForLocation: (location: DocxTextRangeLocation) => DocxTrackedChange[];
 }
+interface UseDocxCommentsResult {
+    comments: DocxComment[];
+    showComments: boolean;
+    setShowComments: (showComments: boolean) => void;
+    toggleShowComments: () => void;
+    commentsByLocation: Map<string, DocxComment[]>;
+    getCommentsForLocation: (location: DocxTextRangeLocation) => DocxComment[];
+}
 interface DocxSectionColumnLayout {
     count: number;
     gapPx: number;
@@ -1307,9 +1406,15 @@ declare function useDocxLineSpacing(editor: Pick<DocxEditorController, "selected
 declare function useDocxBorders(editor: Pick<DocxEditorController, "selectedBorderContext" | "activeBorderPresets" | "applyBorderPreset">): UseDocxBordersResult;
 declare function useDocxFormFields(editor: Pick<DocxEditorController, "model" | "selectedFormField" | "selectFormField" | "setFormFieldValue" | "toggleFormCheckbox" | "updateFormFieldWidget">): UseDocxFormFieldsResult;
 declare function useDocxTrackChanges(editor: Pick<DocxEditorController, "trackedChanges" | "showTrackedChanges" | "setShowTrackedChanges" | "toggleShowTrackedChanges">): UseDocxTrackChangesResult;
+/**
+ * Exposes document comments and the show/hide state, mirroring
+ * `useDocxTrackChanges`. Pair with `DocxEditorViewer`'s `renderCommentCard`
+ * to fully customize how comments render.
+ */
+declare function useDocxComments(editor: Pick<DocxEditorController, "comments" | "showComments" | "setShowComments" | "toggleShowComments">): UseDocxCommentsResult;
 declare function useDocxPageLayout(editor: Pick<DocxEditorController, "model">): UseDocxPageLayoutResult;
 declare function useDocxPagination(editor: Pick<DocxEditorController, "currentPage" | "totalPages">): UseDocxPaginationResult;
-declare function DocxEditorViewer({ editor, className, style, pageBackgroundColor, pageGapBackgroundColor, deferInitialPaginationPaint, loadingState, pageVirtualization, visiblePageRange, onPageCountChange, onRequestPageReveal, headingStyles, showTrackedChanges, renderTrackedChangeCard, renderTableContextMenu, renderContextMenu, onFormFieldDoubleClick, mode, }: DocxEditorViewerProps): React.JSX.Element;
+declare function DocxEditorViewer({ editor, className, style, pageBackgroundColor, pageGapBackgroundColor, deferInitialPaginationPaint, loadingState, pageVirtualization, visiblePageRange, onPageCountChange, onRequestPageReveal, headingStyles, showTrackedChanges, renderTrackedChangeCard, showComments, renderCommentCard, renderTableContextMenu, renderContextMenu, onFormFieldDoubleClick, mode, }: DocxEditorViewerProps): React.JSX.Element;
 
 interface InsertParagraphOptions {
     paragraphStyle?: ParagraphStyle;
@@ -1623,4 +1728,4 @@ interface UseDocxModelState {
 declare function useDocxModel(file?: ArrayBuffer): UseDocxModelState;
 declare function ReactDocxViewer({ file, model, className, layoutOptions, emptyState }: ReactDocxViewerProps): React.JSX.Element;
 
-export { DEFAULT_MIN_PARAGRAPH_LINE_HEIGHT_PX, DEFAULT_PAGE_OVERFLOW_TOLERANCE_PX, type DocModel, type DocNode, type DocumentCompatibilitySettings, type DocumentNoteDefinition, type DocumentPageNodeSegment, type DocumentPageRange, type DocumentPageSegmentationOptions, type DocumentSection, type DocxBorderContext, type DocxBorderPreset, type DocxBorderPresetState, type DocxContextMenuAction, type DocxContextMenuActionId, type DocxContextMenuContext, type DocxContextMenuRenderProps, type DocxDocumentTheme, type DocxEditorController, type DocxEditorSelection, DocxEditorViewer, type DocxEditorViewerMode, type DocxEditorViewerProps, type DocxFormFieldLocation, type DocxHeadingStyleMap, type DocxImageDropTarget, type DocxImageLocation, type DocxImageWrapMenuOption, type DocxImageWrapMode, type DocxImageWrapState, type DocxLineSpacingInfo, type DocxListType, type DocxPageLayoutInfo, type DocxPageThumbnailBounds, type DocxPageThumbnailItem, type DocxPageThumbnailResolution, type DocxPageThumbnailResolutionOptions, type DocxPageThumbnailStatus, type DocxPageVirtualizationOptions, type DocxPaginationInfo, type DocxSectionColumnLayout, type DocxSelectedFormField, type DocxTableContextMenuAction, type DocxTableContextMenuActionId, type DocxTableContextMenuContext, type DocxTableContextMenuRenderProps, type DocxTextRange, type DocxTextRangeLocation, type DocxTrackedChange, type DocxTrackedChangeCardRenderProps, type DocxTrackedChangeKind, type DocxViewerThumbnails, type DocxVisiblePageRange, type FooterSection, type FormFieldCheckboxWidgetSettings, type FormFieldDropdownWidgetSettings, type FormFieldOption, type FormFieldRunNode, type FormFieldSourceKind, type FormFieldTextWidgetSettings, type FormFieldType, type FormFieldWidgetSettings, type HeaderSection, type HeadingLevel, type ImageRunNode, type InsertParagraphOptions, type LayoutBlock, type LayoutFragmentSource, type LayoutImageRun, type LayoutOptions, type LayoutPage, type LayoutParagraphBlock, type LayoutRun, type LayoutSnapshot, type LayoutSnapshotBlockFragment, type LayoutSnapshotImageRun, type LayoutSnapshotMargins, type LayoutSnapshotOptions, type LayoutSnapshotPage, type LayoutSnapshotPageSize, type LayoutSnapshotParagraphFragment, type LayoutSnapshotRect, type LayoutSnapshotRun, type LayoutSnapshotTableCellFragment, type LayoutSnapshotTableFragment, type LayoutSnapshotTableRowFragment, type LayoutSnapshotTextRun, type LayoutTableBlock, type LayoutTableCell, type LayoutTableRow, type LayoutTextRun, type LegacyWasmOoxmlPackage, type LetterheadColumnSegmentGroup, type NumberingAbstractDefinition, type NumberingDefinitionSet, type NumberingInstanceDefinition, type NumberingLevelDefinition, type NumberingPictureBulletDefinition, type OoxmlPackage, type OoxmlPart, type OverflowBreakCollectionOptions, type PageSegmentationCallbacks, type PaginationSectionMetrics, type ParagraphAlignment, type ParagraphBorderSet, type ParagraphBorderStyle, type ParagraphChildNode, type ParagraphIndent, type ParagraphLineRange, type ParagraphNode, type ParagraphNumbering, type ParagraphSpacing, type ParagraphSplitControlOptions, type ParagraphStyle, type ParagraphStyleDefinition, type ParagraphTabStop, ReactDocxViewer, type ReactDocxViewerProps, type ResolvedDocument, type ResolvedDocumentSection, type ResolvedLayoutMetrics, type ResolvedModelSection, type TableBorderSet, type TableBorderStyle, type TableBoxSpacing, type TableCellContentNode, type TableCellNode, type TableCellStyle, type TableExplicitPageBreakInfo, type TableNode, type TableRowNode, type TableRowRange, type TableRowStyle, type TableStyle, type TextRunBorderStyle, type TextRunNode, type TextStyle, type UpdateTextOptions, type UseDocxBordersResult, type UseDocxDocumentThemeResult, type UseDocxEditorOptions, type UseDocxFormFieldsResult, type UseDocxImageWrapMenuResult, type UseDocxLineSpacingResult, type UseDocxModelState, type UseDocxPageLayoutResult, type UseDocxPageThumbnailsOptions, type UseDocxPageThumbnailsResult, type UseDocxPaginationResult, type UseDocxParagraphStylesResult, type UseDocxTrackChangesResult, type UseDocxViewerThumbnailsOptions, type WasmOoxmlPackage, type WasmSource, applyRunStyle, buildDocModel, buildDocModelFromBytes, buildDocumentPageNodeSegments, buildDocumentPageRanges, buildLayoutSnapshot, cloneDocModel, collectDocxEstimatedOverflowBreakStartNodeIndexes, collectDocxHardPageBreakStartNodeIndexes, collectDocxLastRenderedPageBreakStartNodeIndexes, collectTableExplicitPageBreakInfo, collectTopLevelExplicitPageBreakStartNodeIndexes, copyParagraphs, createMinimalDocxPackage, defaultStarterModel, duplicateParagraph, getPart, initWasm, insertParagraph, layoutDocument, modelToDocumentXml, normalizeDocModel, packageToArrayBuffer, paragraphAfterSpacingPx, paragraphBeforeSpacingPx, paragraphHasExplicitPageBreak, paragraphHasLastRenderedPageBreak, paragraphHasPageBreakBefore, paragraphLetterheadColumnGroupAtSegmentOffset, paragraphLetterheadFloatSideAtNodeIndex, paragraphStartsWithLastRenderedPageBreak, parseDocx, parseParagraphsFromClipboard, parseSectionLayout, pasteParagraphs, removeParagraph, replaceText, resolveDocumentForLayout, resolveDocumentLayout, resolveDocumentPageSegmentStartNodeIndex, resolveDocumentSectionsFromMetadata, resolveDocxPageThumbnailResolution, resolvePaginationSectionMetricsIndexForNodeIndex, resolveParagraphBeforeSpacingPx, resolveSectionIndexForNodeIndex, resolveSectionPropertiesXmlForNodeIndex, scalePaginationSectionMetricsHeights, scorePaginationAgainstStoredPageBreaks, sectionBreakAfterParagraphStartsNewPage, sectionBreakPropertiesStartNewPage, sectionTitlePageEnabled, selectSectionVariantForPage, serializeDocModel, serializeDocx, serializeParagraphsForClipboard, setParagraphAlignment, setParagraphHeading, setRunColor, setRunHighlight, setWasmSource, splitParagraphChildrenAtTextOffsets, toggleRunStyleFlag, updateParagraphText, updateTableCellParagraphText, updateTableCellParagraphTextRecursive, updateTableCellText, useDocxBorders, useDocxDocumentTheme, useDocxEditor, useDocxFormFields, useDocxImageWrapMenu, useDocxLineSpacing, useDocxModel, useDocxPageLayout, useDocxPageThumbnails, useDocxPagination, useDocxParagraphStyles, useDocxTrackChanges, useDocxViewerThumbnails, withPart };
+export { DEFAULT_MIN_PARAGRAPH_LINE_HEIGHT_PX, DEFAULT_PAGE_OVERFLOW_TOLERANCE_PX, type DocModel, type DocNode, type DocumentCommentDefinition, type DocumentCompatibilitySettings, type DocumentNoteDefinition, type DocumentPageNodeSegment, type DocumentPageRange, type DocumentPageSegmentationOptions, type DocumentSection, type DocxBorderContext, type DocxBorderPreset, type DocxBorderPresetState, type DocxComment, type DocxCommentCardRenderProps, type DocxContextMenuAction, type DocxContextMenuActionId, type DocxContextMenuContext, type DocxContextMenuRenderProps, type DocxDocumentTheme, type DocxEditorController, type DocxEditorSelection, DocxEditorViewer, type DocxEditorViewerMode, type DocxEditorViewerProps, type DocxFormFieldLocation, type DocxHeadingStyleMap, type DocxImageDropTarget, type DocxImageLocation, type DocxImageWrapMenuOption, type DocxImageWrapMode, type DocxImageWrapState, type DocxLineSpacingInfo, type DocxListType, type DocxPageLayoutInfo, type DocxPageThumbnailBounds, type DocxPageThumbnailItem, type DocxPageThumbnailResolution, type DocxPageThumbnailResolutionOptions, type DocxPageThumbnailStatus, type DocxPageVirtualizationOptions, type DocxPaginationInfo, type DocxSectionColumnLayout, type DocxSelectedFormField, type DocxTableContextMenuAction, type DocxTableContextMenuActionId, type DocxTableContextMenuContext, type DocxTableContextMenuRenderProps, type DocxTextRange, type DocxTextRangeLocation, type DocxTrackedChange, type DocxTrackedChangeCardRenderProps, type DocxTrackedChangeKind, type DocxViewerThumbnails, type DocxVisiblePageRange, type FooterSection, type FormFieldCheckboxWidgetSettings, type FormFieldDropdownWidgetSettings, type FormFieldOption, type FormFieldRunNode, type FormFieldSourceKind, type FormFieldTextWidgetSettings, type FormFieldType, type FormFieldWidgetSettings, type HeaderSection, type HeadingLevel, type ImageRunNode, type InsertParagraphOptions, type LayoutBlock, type LayoutFragmentSource, type LayoutImageRun, type LayoutOptions, type LayoutPage, type LayoutParagraphBlock, type LayoutRun, type LayoutSnapshot, type LayoutSnapshotBlockFragment, type LayoutSnapshotImageRun, type LayoutSnapshotMargins, type LayoutSnapshotOptions, type LayoutSnapshotPage, type LayoutSnapshotPageSize, type LayoutSnapshotParagraphFragment, type LayoutSnapshotRect, type LayoutSnapshotRun, type LayoutSnapshotTableCellFragment, type LayoutSnapshotTableFragment, type LayoutSnapshotTableRowFragment, type LayoutSnapshotTextRun, type LayoutTableBlock, type LayoutTableCell, type LayoutTableRow, type LayoutTextRun, type LegacyWasmOoxmlPackage, type LetterheadColumnSegmentGroup, type NumberingAbstractDefinition, type NumberingDefinitionSet, type NumberingInstanceDefinition, type NumberingLevelDefinition, type NumberingPictureBulletDefinition, type OoxmlPackage, type OoxmlPart, type OverflowBreakCollectionOptions, type PageSegmentationCallbacks, type PaginationSectionMetrics, type ParagraphAlignment, type ParagraphBorderSet, type ParagraphBorderStyle, type ParagraphChildNode, type ParagraphIndent, type ParagraphLineRange, type ParagraphNode, type ParagraphNumbering, type ParagraphSpacing, type ParagraphSplitControlOptions, type ParagraphStyle, type ParagraphStyleDefinition, type ParagraphTabStop, ReactDocxViewer, type ReactDocxViewerProps, type ResolvedDocument, type ResolvedDocumentSection, type ResolvedLayoutMetrics, type ResolvedModelSection, type TableBorderSet, type TableBorderStyle, type TableBoxSpacing, type TableCellContentNode, type TableCellNode, type TableCellStyle, type TableExplicitPageBreakInfo, type TableNode, type TableRowNode, type TableRowRange, type TableRowStyle, type TableStyle, type TextRunBorderStyle, type TextRunNode, type TextStyle, type UpdateTextOptions, type UseDocxBordersResult, type UseDocxCommentsResult, type UseDocxDocumentThemeResult, type UseDocxEditorOptions, type UseDocxFormFieldsResult, type UseDocxImageWrapMenuResult, type UseDocxLineSpacingResult, type UseDocxModelState, type UseDocxPageLayoutResult, type UseDocxPageThumbnailsOptions, type UseDocxPageThumbnailsResult, type UseDocxPaginationResult, type UseDocxParagraphStylesResult, type UseDocxTrackChangesResult, type UseDocxViewerThumbnailsOptions, type WasmOoxmlPackage, type WasmSource, applyRunStyle, buildDocModel, buildDocModelFromBytes, buildDocumentPageNodeSegments, buildDocumentPageRanges, buildLayoutSnapshot, cloneDocModel, collectDocxEstimatedOverflowBreakStartNodeIndexes, collectDocxHardPageBreakStartNodeIndexes, collectDocxLastRenderedPageBreakStartNodeIndexes, collectTableExplicitPageBreakInfo, collectTopLevelExplicitPageBreakStartNodeIndexes, copyParagraphs, createMinimalDocxPackage, defaultStarterModel, duplicateParagraph, getPart, initWasm, insertParagraph, layoutDocument, modelToDocumentXml, normalizeDocModel, packageToArrayBuffer, paragraphAfterSpacingPx, paragraphBeforeSpacingPx, paragraphHasExplicitPageBreak, paragraphHasLastRenderedPageBreak, paragraphHasPageBreakBefore, paragraphLetterheadColumnGroupAtSegmentOffset, paragraphLetterheadFloatSideAtNodeIndex, paragraphStartsWithLastRenderedPageBreak, parseDocx, parseParagraphsFromClipboard, parseSectionLayout, pasteParagraphs, removeParagraph, replaceText, resolveDocumentForLayout, resolveDocumentLayout, resolveDocumentPageSegmentStartNodeIndex, resolveDocumentSectionsFromMetadata, resolveDocxPageThumbnailResolution, resolvePaginationSectionMetricsIndexForNodeIndex, resolveParagraphBeforeSpacingPx, resolveSectionIndexForNodeIndex, resolveSectionPropertiesXmlForNodeIndex, scalePaginationSectionMetricsHeights, scorePaginationAgainstStoredPageBreaks, sectionBreakAfterParagraphStartsNewPage, sectionBreakPropertiesStartNewPage, sectionTitlePageEnabled, selectSectionVariantForPage, serializeDocModel, serializeDocx, serializeParagraphsForClipboard, setParagraphAlignment, setParagraphHeading, setRunColor, setRunHighlight, setWasmSource, splitParagraphChildrenAtTextOffsets, toggleRunStyleFlag, updateParagraphText, updateTableCellParagraphText, updateTableCellParagraphTextRecursive, updateTableCellText, useDocxBorders, useDocxComments, useDocxDocumentTheme, useDocxEditor, useDocxFormFields, useDocxImageWrapMenu, useDocxLineSpacing, useDocxModel, useDocxPageLayout, useDocxPageThumbnails, useDocxPagination, useDocxParagraphStyles, useDocxTrackChanges, useDocxViewerThumbnails, withPart };

package/dist/index.d.ts

@@ -401,6 +401,17 @@ interface DocumentNoteDefinition {
     text: string;
     nodes?: DocNode[];
 }
+interface DocumentCommentDefinition {
+    id: number;
+    author?: string;
+    initials?: string;
+    date?: string;
+    text: string;
+    /** Comment id this comment replies to (from commentsExtended threading). */
+    parentId?: number;
+    /** True when the comment thread is marked done in commentsExtended. */
+    resolved?: boolean;
+}
 interface DocumentCompatibilitySettings {
     suppressSpacingBeforeAfterPageBreak?: boolean;
     usePrinterMetrics?: boolean;
@@ -427,6 +438,7 @@ interface DocModel {
         compatibility?: DocumentCompatibilitySettings;
         footnotes?: DocumentNoteDefinition[];
         endnotes?: DocumentNoteDefinition[];
+        comments?: DocumentCommentDefinition[];
     };
 }
 
@@ -618,6 +630,32 @@ interface DocxTrackedChange {
     nodeIndex: number;
     location: DocxTextRangeLocation;
 }
+/**
+ * A document comment anchored to a text range.
+ *
+ * Comment definitions come from `word/comments.xml` (threading and resolution
+ * state from `word/commentsExtended.xml`); the anchor location is resolved
+ * from the paragraph that carries the `commentReference` run.
+ */
+interface DocxComment {
+    /** Stable identifier (unique per rendered anchor). */
+    id: string;
+    /** Comment id from `word/comments.xml` (`w:id`). */
+    commentId: number;
+    author?: string;
+    initials?: string;
+    date?: string;
+    /** Plain-text comment body. */
+    text: string;
+    /** Comment id this comment replies to, when part of a thread. */
+    parentId?: number;
+    /** True when the comment thread is marked done. */
+    resolved?: boolean;
+    /** Plain-text excerpt of the commented document range. */
+    anchorText?: string;
+    nodeIndex: number;
+    location: DocxTextRangeLocation;
+}
 type DocxLineSpacingRule = "auto" | "exact" | "atLeast";
 type DocxSelectionSessionKind = "idle" | "pointer" | "keyboard" | "composition" | "command" | "history-restore";
 interface DocxLineSpacingInfo {
@@ -665,6 +703,12 @@ interface UseDocxEditorOptions {
      * @defaultValue `false`
      */
     initialShowTrackedChanges?: boolean;
+    /**
+     * Whether document comments are visible when the editor first mounts.
+     *
+     * @defaultValue `false`
+     */
+    initialShowComments?: boolean;
 }
 /**
  * Controller returned by `useDocxEditor`.
@@ -713,6 +757,8 @@ interface DocxEditorController {
     availableParagraphStyles: ParagraphStyleDefinition[];
     trackedChanges: DocxTrackedChange[];
     showTrackedChanges: boolean;
+    comments: DocxComment[];
+    showComments: boolean;
     currentPage: number;
     totalPages: number;
     hasUnorderedList: boolean;
@@ -723,8 +769,10 @@ interface DocxEditorController {
     setStatus: React.Dispatch<React.SetStateAction<string>>;
     setDocumentTheme: (theme: DocxDocumentTheme) => void;
     setShowTrackedChanges: (showTrackedChanges: boolean) => void;
+    setShowComments: (showComments: boolean) => void;
     syncPaginationInfo: (pagination: DocxPaginationInfo) => void;
     toggleShowTrackedChanges: () => void;
+    toggleShowComments: () => void;
     importDocxFile: (file: File) => Promise<void>;
     newDocument: () => void;
     exportDocx: () => void;
@@ -920,6 +968,22 @@ interface DocxPageVirtualizationOptions {
      * @defaultValue `0`
      */
     settleDelayMs?: number;
+    /**
+     * Explicit scroll container for internal page virtualization.
+     *
+     * Omit this to let the viewer discover the nearest scrollable ancestor.
+     * Provide it when the host app owns scrolling, such as when the viewer is
+     * mounted inside a custom scroll-area viewport.
+     */
+    scrollElement?: HTMLElement | null;
+    /**
+     * Effective visual scale applied around the viewer.
+     *
+     * Omit this to let the viewer infer CSS `zoom` from its ancestor chain.
+     * Provide it when toolbar zoom is controlled outside the viewer so virtual
+     * page offsets update synchronously with the selected zoom.
+     */
+    zoomScale?: number;
 }
 /**
  * Externally controlled visible page window.
@@ -1048,6 +1112,17 @@ interface DocxEditorViewerProps {
      * Custom renderer for tracked-change cards in the page gutter.
      */
     renderTrackedChangeCard?: (props: DocxTrackedChangeCardRenderProps) => React.ReactNode;
+    /**
+     * Overrides whether document comments are shown.
+     *
+     * If omitted, the value from `useDocxComments(editor)` or
+     * `editor.showComments` is used.
+     */
+    showComments?: boolean;
+    /**
+     * Custom renderer for comment cards in the page gutter.
+     */
+    renderCommentCard?: (props: DocxCommentCardRenderProps) => React.ReactNode;
     /**
      * Custom renderer for table context menus.
      *
@@ -1085,6 +1160,22 @@ interface DocxTrackedChangeCardRenderProps {
     /** Positioning style computed by the viewer. Apply this to the card root. */
     style: React.CSSProperties;
 }
+interface DocxCommentCardRenderProps {
+    /** Comment data represented by the card. */
+    comment: DocxComment;
+    /** Plain-text comment body (already normalized for display). */
+    snippet: string;
+    /** Formatted comment date, if the source document provided one. */
+    formattedDate?: string;
+    /** Accent color chosen for comments. */
+    accentColor: string;
+    /** Current document theme. */
+    documentTheme: DocxDocumentTheme;
+    /** Zero-based page index that owns the card. */
+    pageIndex: number;
+    /** Positioning style computed by the viewer. Apply this to the card root. */
+    style: React.CSSProperties;
+}
 /**
  * Viewer interaction mode.
  *
@@ -1129,6 +1220,14 @@ interface UseDocxTrackChangesResult {
     changesByLocation: Map<string, DocxTrackedChange[]>;
     getChangesForLocation: (location: DocxTextRangeLocation) => DocxTrackedChange[];
 }
+interface UseDocxCommentsResult {
+    comments: DocxComment[];
+    showComments: boolean;
+    setShowComments: (showComments: boolean) => void;
+    toggleShowComments: () => void;
+    commentsByLocation: Map<string, DocxComment[]>;
+    getCommentsForLocation: (location: DocxTextRangeLocation) => DocxComment[];
+}
 interface DocxSectionColumnLayout {
     count: number;
     gapPx: number;
@@ -1307,9 +1406,15 @@ declare function useDocxLineSpacing(editor: Pick<DocxEditorController, "selected
 declare function useDocxBorders(editor: Pick<DocxEditorController, "selectedBorderContext" | "activeBorderPresets" | "applyBorderPreset">): UseDocxBordersResult;
 declare function useDocxFormFields(editor: Pick<DocxEditorController, "model" | "selectedFormField" | "selectFormField" | "setFormFieldValue" | "toggleFormCheckbox" | "updateFormFieldWidget">): UseDocxFormFieldsResult;
 declare function useDocxTrackChanges(editor: Pick<DocxEditorController, "trackedChanges" | "showTrackedChanges" | "setShowTrackedChanges" | "toggleShowTrackedChanges">): UseDocxTrackChangesResult;
+/**
+ * Exposes document comments and the show/hide state, mirroring
+ * `useDocxTrackChanges`. Pair with `DocxEditorViewer`'s `renderCommentCard`
+ * to fully customize how comments render.
+ */
+declare function useDocxComments(editor: Pick<DocxEditorController, "comments" | "showComments" | "setShowComments" | "toggleShowComments">): UseDocxCommentsResult;
 declare function useDocxPageLayout(editor: Pick<DocxEditorController, "model">): UseDocxPageLayoutResult;
 declare function useDocxPagination(editor: Pick<DocxEditorController, "currentPage" | "totalPages">): UseDocxPaginationResult;
-declare function DocxEditorViewer({ editor, className, style, pageBackgroundColor, pageGapBackgroundColor, deferInitialPaginationPaint, loadingState, pageVirtualization, visiblePageRange, onPageCountChange, onRequestPageReveal, headingStyles, showTrackedChanges, renderTrackedChangeCard, renderTableContextMenu, renderContextMenu, onFormFieldDoubleClick, mode, }: DocxEditorViewerProps): React.JSX.Element;
+declare function DocxEditorViewer({ editor, className, style, pageBackgroundColor, pageGapBackgroundColor, deferInitialPaginationPaint, loadingState, pageVirtualization, visiblePageRange, onPageCountChange, onRequestPageReveal, headingStyles, showTrackedChanges, renderTrackedChangeCard, showComments, renderCommentCard, renderTableContextMenu, renderContextMenu, onFormFieldDoubleClick, mode, }: DocxEditorViewerProps): React.JSX.Element;
 
 interface InsertParagraphOptions {
     paragraphStyle?: ParagraphStyle;
@@ -1623,4 +1728,4 @@ interface UseDocxModelState {
 declare function useDocxModel(file?: ArrayBuffer): UseDocxModelState;
 declare function ReactDocxViewer({ file, model, className, layoutOptions, emptyState }: ReactDocxViewerProps): React.JSX.Element;
 
-export { DEFAULT_MIN_PARAGRAPH_LINE_HEIGHT_PX, DEFAULT_PAGE_OVERFLOW_TOLERANCE_PX, type DocModel, type DocNode, type DocumentCompatibilitySettings, type DocumentNoteDefinition, type DocumentPageNodeSegment, type DocumentPageRange, type DocumentPageSegmentationOptions, type DocumentSection, type DocxBorderContext, type DocxBorderPreset, type DocxBorderPresetState, type DocxContextMenuAction, type DocxContextMenuActionId, type DocxContextMenuContext, type DocxContextMenuRenderProps, type DocxDocumentTheme, type DocxEditorController, type DocxEditorSelection, DocxEditorViewer, type DocxEditorViewerMode, type DocxEditorViewerProps, type DocxFormFieldLocation, type DocxHeadingStyleMap, type DocxImageDropTarget, type DocxImageLocation, type DocxImageWrapMenuOption, type DocxImageWrapMode, type DocxImageWrapState, type DocxLineSpacingInfo, type DocxListType, type DocxPageLayoutInfo, type DocxPageThumbnailBounds, type DocxPageThumbnailItem, type DocxPageThumbnailResolution, type DocxPageThumbnailResolutionOptions, type DocxPageThumbnailStatus, type DocxPageVirtualizationOptions, type DocxPaginationInfo, type DocxSectionColumnLayout, type DocxSelectedFormField, type DocxTableContextMenuAction, type DocxTableContextMenuActionId, type DocxTableContextMenuContext, type DocxTableContextMenuRenderProps, type DocxTextRange, type DocxTextRangeLocation, type DocxTrackedChange, type DocxTrackedChangeCardRenderProps, type DocxTrackedChangeKind, type DocxViewerThumbnails, type DocxVisiblePageRange, type FooterSection, type FormFieldCheckboxWidgetSettings, type FormFieldDropdownWidgetSettings, type FormFieldOption, type FormFieldRunNode, type FormFieldSourceKind, type FormFieldTextWidgetSettings, type FormFieldType, type FormFieldWidgetSettings, type HeaderSection, type HeadingLevel, type ImageRunNode, type InsertParagraphOptions, type LayoutBlock, type LayoutFragmentSource, type LayoutImageRun, type LayoutOptions, type LayoutPage, type LayoutParagraphBlock, type LayoutRun, type LayoutSnapshot, type LayoutSnapshotBlockFragment, type LayoutSnapshotImageRun, type LayoutSnapshotMargins, type LayoutSnapshotOptions, type LayoutSnapshotPage, type LayoutSnapshotPageSize, type LayoutSnapshotParagraphFragment, type LayoutSnapshotRect, type LayoutSnapshotRun, type LayoutSnapshotTableCellFragment, type LayoutSnapshotTableFragment, type LayoutSnapshotTableRowFragment, type LayoutSnapshotTextRun, type LayoutTableBlock, type LayoutTableCell, type LayoutTableRow, type LayoutTextRun, type LegacyWasmOoxmlPackage, type LetterheadColumnSegmentGroup, type NumberingAbstractDefinition, type NumberingDefinitionSet, type NumberingInstanceDefinition, type NumberingLevelDefinition, type NumberingPictureBulletDefinition, type OoxmlPackage, type OoxmlPart, type OverflowBreakCollectionOptions, type PageSegmentationCallbacks, type PaginationSectionMetrics, type ParagraphAlignment, type ParagraphBorderSet, type ParagraphBorderStyle, type ParagraphChildNode, type ParagraphIndent, type ParagraphLineRange, type ParagraphNode, type ParagraphNumbering, type ParagraphSpacing, type ParagraphSplitControlOptions, type ParagraphStyle, type ParagraphStyleDefinition, type ParagraphTabStop, ReactDocxViewer, type ReactDocxViewerProps, type ResolvedDocument, type ResolvedDocumentSection, type ResolvedLayoutMetrics, type ResolvedModelSection, type TableBorderSet, type TableBorderStyle, type TableBoxSpacing, type TableCellContentNode, type TableCellNode, type TableCellStyle, type TableExplicitPageBreakInfo, type TableNode, type TableRowNode, type TableRowRange, type TableRowStyle, type TableStyle, type TextRunBorderStyle, type TextRunNode, type TextStyle, type UpdateTextOptions, type UseDocxBordersResult, type UseDocxDocumentThemeResult, type UseDocxEditorOptions, type UseDocxFormFieldsResult, type UseDocxImageWrapMenuResult, type UseDocxLineSpacingResult, type UseDocxModelState, type UseDocxPageLayoutResult, type UseDocxPageThumbnailsOptions, type UseDocxPageThumbnailsResult, type UseDocxPaginationResult, type UseDocxParagraphStylesResult, type UseDocxTrackChangesResult, type UseDocxViewerThumbnailsOptions, type WasmOoxmlPackage, type WasmSource, applyRunStyle, buildDocModel, buildDocModelFromBytes, buildDocumentPageNodeSegments, buildDocumentPageRanges, buildLayoutSnapshot, cloneDocModel, collectDocxEstimatedOverflowBreakStartNodeIndexes, collectDocxHardPageBreakStartNodeIndexes, collectDocxLastRenderedPageBreakStartNodeIndexes, collectTableExplicitPageBreakInfo, collectTopLevelExplicitPageBreakStartNodeIndexes, copyParagraphs, createMinimalDocxPackage, defaultStarterModel, duplicateParagraph, getPart, initWasm, insertParagraph, layoutDocument, modelToDocumentXml, normalizeDocModel, packageToArrayBuffer, paragraphAfterSpacingPx, paragraphBeforeSpacingPx, paragraphHasExplicitPageBreak, paragraphHasLastRenderedPageBreak, paragraphHasPageBreakBefore, paragraphLetterheadColumnGroupAtSegmentOffset, paragraphLetterheadFloatSideAtNodeIndex, paragraphStartsWithLastRenderedPageBreak, parseDocx, parseParagraphsFromClipboard, parseSectionLayout, pasteParagraphs, removeParagraph, replaceText, resolveDocumentForLayout, resolveDocumentLayout, resolveDocumentPageSegmentStartNodeIndex, resolveDocumentSectionsFromMetadata, resolveDocxPageThumbnailResolution, resolvePaginationSectionMetricsIndexForNodeIndex, resolveParagraphBeforeSpacingPx, resolveSectionIndexForNodeIndex, resolveSectionPropertiesXmlForNodeIndex, scalePaginationSectionMetricsHeights, scorePaginationAgainstStoredPageBreaks, sectionBreakAfterParagraphStartsNewPage, sectionBreakPropertiesStartNewPage, sectionTitlePageEnabled, selectSectionVariantForPage, serializeDocModel, serializeDocx, serializeParagraphsForClipboard, setParagraphAlignment, setParagraphHeading, setRunColor, setRunHighlight, setWasmSource, splitParagraphChildrenAtTextOffsets, toggleRunStyleFlag, updateParagraphText, updateTableCellParagraphText, updateTableCellParagraphTextRecursive, updateTableCellText, useDocxBorders, useDocxDocumentTheme, useDocxEditor, useDocxFormFields, useDocxImageWrapMenu, useDocxLineSpacing, useDocxModel, useDocxPageLayout, useDocxPageThumbnails, useDocxPagination, useDocxParagraphStyles, useDocxTrackChanges, useDocxViewerThumbnails, withPart };
+export { DEFAULT_MIN_PARAGRAPH_LINE_HEIGHT_PX, DEFAULT_PAGE_OVERFLOW_TOLERANCE_PX, type DocModel, type DocNode, type DocumentCommentDefinition, type DocumentCompatibilitySettings, type DocumentNoteDefinition, type DocumentPageNodeSegment, type DocumentPageRange, type DocumentPageSegmentationOptions, type DocumentSection, type DocxBorderContext, type DocxBorderPreset, type DocxBorderPresetState, type DocxComment, type DocxCommentCardRenderProps, type DocxContextMenuAction, type DocxContextMenuActionId, type DocxContextMenuContext, type DocxContextMenuRenderProps, type DocxDocumentTheme, type DocxEditorController, type DocxEditorSelection, DocxEditorViewer, type DocxEditorViewerMode, type DocxEditorViewerProps, type DocxFormFieldLocation, type DocxHeadingStyleMap, type DocxImageDropTarget, type DocxImageLocation, type DocxImageWrapMenuOption, type DocxImageWrapMode, type DocxImageWrapState, type DocxLineSpacingInfo, type DocxListType, type DocxPageLayoutInfo, type DocxPageThumbnailBounds, type DocxPageThumbnailItem, type DocxPageThumbnailResolution, type DocxPageThumbnailResolutionOptions, type DocxPageThumbnailStatus, type DocxPageVirtualizationOptions, type DocxPaginationInfo, type DocxSectionColumnLayout, type DocxSelectedFormField, type DocxTableContextMenuAction, type DocxTableContextMenuActionId, type DocxTableContextMenuContext, type DocxTableContextMenuRenderProps, type DocxTextRange, type DocxTextRangeLocation, type DocxTrackedChange, type DocxTrackedChangeCardRenderProps, type DocxTrackedChangeKind, type DocxViewerThumbnails, type DocxVisiblePageRange, type FooterSection, type FormFieldCheckboxWidgetSettings, type FormFieldDropdownWidgetSettings, type FormFieldOption, type FormFieldRunNode, type FormFieldSourceKind, type FormFieldTextWidgetSettings, type FormFieldType, type FormFieldWidgetSettings, type HeaderSection, type HeadingLevel, type ImageRunNode, type InsertParagraphOptions, type LayoutBlock, type LayoutFragmentSource, type LayoutImageRun, type LayoutOptions, type LayoutPage, type LayoutParagraphBlock, type LayoutRun, type LayoutSnapshot, type LayoutSnapshotBlockFragment, type LayoutSnapshotImageRun, type LayoutSnapshotMargins, type LayoutSnapshotOptions, type LayoutSnapshotPage, type LayoutSnapshotPageSize, type LayoutSnapshotParagraphFragment, type LayoutSnapshotRect, type LayoutSnapshotRun, type LayoutSnapshotTableCellFragment, type LayoutSnapshotTableFragment, type LayoutSnapshotTableRowFragment, type LayoutSnapshotTextRun, type LayoutTableBlock, type LayoutTableCell, type LayoutTableRow, type LayoutTextRun, type LegacyWasmOoxmlPackage, type LetterheadColumnSegmentGroup, type NumberingAbstractDefinition, type NumberingDefinitionSet, type NumberingInstanceDefinition, type NumberingLevelDefinition, type NumberingPictureBulletDefinition, type OoxmlPackage, type OoxmlPart, type OverflowBreakCollectionOptions, type PageSegmentationCallbacks, type PaginationSectionMetrics, type ParagraphAlignment, type ParagraphBorderSet, type ParagraphBorderStyle, type ParagraphChildNode, type ParagraphIndent, type ParagraphLineRange, type ParagraphNode, type ParagraphNumbering, type ParagraphSpacing, type ParagraphSplitControlOptions, type ParagraphStyle, type ParagraphStyleDefinition, type ParagraphTabStop, ReactDocxViewer, type ReactDocxViewerProps, type ResolvedDocument, type ResolvedDocumentSection, type ResolvedLayoutMetrics, type ResolvedModelSection, type TableBorderSet, type TableBorderStyle, type TableBoxSpacing, type TableCellContentNode, type TableCellNode, type TableCellStyle, type TableExplicitPageBreakInfo, type TableNode, type TableRowNode, type TableRowRange, type TableRowStyle, type TableStyle, type TextRunBorderStyle, type TextRunNode, type TextStyle, type UpdateTextOptions, type UseDocxBordersResult, type UseDocxCommentsResult, type UseDocxDocumentThemeResult, type UseDocxEditorOptions, type UseDocxFormFieldsResult, type UseDocxImageWrapMenuResult, type UseDocxLineSpacingResult, type UseDocxModelState, type UseDocxPageLayoutResult, type UseDocxPageThumbnailsOptions, type UseDocxPageThumbnailsResult, type UseDocxPaginationResult, type UseDocxParagraphStylesResult, type UseDocxTrackChangesResult, type UseDocxViewerThumbnailsOptions, type WasmOoxmlPackage, type WasmSource, applyRunStyle, buildDocModel, buildDocModelFromBytes, buildDocumentPageNodeSegments, buildDocumentPageRanges, buildLayoutSnapshot, cloneDocModel, collectDocxEstimatedOverflowBreakStartNodeIndexes, collectDocxHardPageBreakStartNodeIndexes, collectDocxLastRenderedPageBreakStartNodeIndexes, collectTableExplicitPageBreakInfo, collectTopLevelExplicitPageBreakStartNodeIndexes, copyParagraphs, createMinimalDocxPackage, defaultStarterModel, duplicateParagraph, getPart, initWasm, insertParagraph, layoutDocument, modelToDocumentXml, normalizeDocModel, packageToArrayBuffer, paragraphAfterSpacingPx, paragraphBeforeSpacingPx, paragraphHasExplicitPageBreak, paragraphHasLastRenderedPageBreak, paragraphHasPageBreakBefore, paragraphLetterheadColumnGroupAtSegmentOffset, paragraphLetterheadFloatSideAtNodeIndex, paragraphStartsWithLastRenderedPageBreak, parseDocx, parseParagraphsFromClipboard, parseSectionLayout, pasteParagraphs, removeParagraph, replaceText, resolveDocumentForLayout, resolveDocumentLayout, resolveDocumentPageSegmentStartNodeIndex, resolveDocumentSectionsFromMetadata, resolveDocxPageThumbnailResolution, resolvePaginationSectionMetricsIndexForNodeIndex, resolveParagraphBeforeSpacingPx, resolveSectionIndexForNodeIndex, resolveSectionPropertiesXmlForNodeIndex, scalePaginationSectionMetricsHeights, scorePaginationAgainstStoredPageBreaks, sectionBreakAfterParagraphStartsNewPage, sectionBreakPropertiesStartNewPage, sectionTitlePageEnabled, selectSectionVariantForPage, serializeDocModel, serializeDocx, serializeParagraphsForClipboard, setParagraphAlignment, setParagraphHeading, setRunColor, setRunHighlight, setWasmSource, splitParagraphChildrenAtTextOffsets, toggleRunStyleFlag, updateParagraphText, updateTableCellParagraphText, updateTableCellParagraphTextRecursive, updateTableCellText, useDocxBorders, useDocxComments, useDocxDocumentTheme, useDocxEditor, useDocxFormFields, useDocxImageWrapMenu, useDocxLineSpacing, useDocxModel, useDocxPageLayout, useDocxPageThumbnails, useDocxPagination, useDocxParagraphStyles, useDocxTrackChanges, useDocxViewerThumbnails, withPart };