@stll/folio-react 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,10 +1,11 @@
 import { t as containedHandler } from "./contained-handler-4uiqUVRn.js";
-import { i as cn, n as FolioUIProvider, r as useFolioUI, t as DEFAULT_COMPONENTS } from "./folio-ui-o_rftArH.js";
+import { i as cn, n as FolioUIProvider, r as useFolioUI, t as DEFAULT_COMPONENTS } from "./folio-ui-CA59webC.js";
 import { i as findInDocument, o as scrollToMatch, t as useFindReplace$1 } from "./useFindReplace-MZ8wi31A.js";
+import { n as getFolioMessages } from "./messages-heGr9XLo.js";
 import * as React$1 from "react";
-import { Component, Suspense, cloneElement, createContext, isValidElement, lazy, memo, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import React, { Component, Suspense, cloneElement, createContext, isValidElement, lazy, memo, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { AlertCircleIcon, AlertTriangleIcon, AlignCenterIcon, AlignJustifyIcon, AlignLeftIcon, AlignRightIcon, BaselineIcon, BoldIcon, CheckIcon, ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon, ClipboardCopyIcon, EyeIcon, FileIcon, GlobeIcon, ImageIcon, IndentDecreaseIcon, IndentIncreaseIcon, InfoIcon, ItalicIcon, LinkIcon, ListIcon, ListOrderedIcon, MoreHorizontalIcon, PaintbrushIcon, PenLineIcon, PencilIcon, PilcrowIcon, Redo2Icon, RulerIcon, SeparatorHorizontalIcon, SquarePenIcon, StickyNoteIcon, TableIcon, TableOfContentsIcon, TypeIcon, UnderlineIcon, Undo2Icon, UnlinkIcon, XIcon } from "lucide-react";
-import { useTranslations } from "use-intl";
+import { IntlProvider, useTranslations } from "use-intl";
 import { applyFolioAIEditOperations, applyFolioAIEditOperations as applyFolioAIEditOperations$1, createFolioAIEditSnapshot, createFolioAIEditSnapshot as createFolioAIEditSnapshot$1, diffWordSegments, hashFolioAIBlockText, normalizeFolioAIBlockText } from "@stll/folio-core/ai-edits";
 import { normalizeBaseDirection } from "@stll/folio-core/docx/normalizeBaseDirection";
 import { getCachedNumberingMap } from "@stll/folio-core/docx/numberingParser";
@@ -66,17 +67,18 @@ import { collectRunFontsAtPmPositions, measureContentLeft, projectRangesToRects
 import { isReadOnlyEditKey } from "@stll/folio-core/paged-layout/readOnlyEditAttempt";
 import { getPageScrollTarget, prefersReducedMotionBehavior } from "@stll/folio-core/paged-layout/scrollNavigation";
 import { PAGES_CONTAINER_CLASS, scrollFolioPositionIntoView, scrollPagesToPmPosition } from "@stll/folio-core/paged-layout/scrollToPmPosition";
+import { flashParagraphFragmentsByParaId } from "@stll/folio-core/paged-layout/paragraphFlash";
 import { DEFAULT_PAGE_HEIGHT_PX, getMargins, getPageSize, twipsToPixels as twipsToPixels$1 } from "@stll/folio-core/paged-layout/sectionGeometry";
 import { resizeColumnPair } from "@stll/folio-core/paged-layout/tableColumnResize";
 import { tableInsertButtonOffset } from "@stll/folio-core/paged-layout/tableInsertButtonGeometry";
 import { getTransactionDirtyRange } from "@stll/folio-core/paged-layout/transactionDirtyRange";
+import { findParagraphByParaId, findStartPosForParaId } from "@stll/folio-core/prosemirror/utils/findParagraphByParaId";
 import { expectFontFamilyMarkAttrs, expectImageAttrs, expectTableAttrs, expectTableCellAttrs, mergeImageAttrs, mergeTableAttrs, mergeTableCellAttrs, mergeTableRowAttrs } from "@stll/folio-core/prosemirror/attrs";
 import { extractEmbeddedFonts } from "@stll/folio-core/fonts/embeddedFonts";
 import { panic } from "better-result";
 import { collectRemoteSelections, createHiddenEditorManager, createHiddenEditorState } from "@stll/folio-core/controller/hiddenEditorManager";
 import { createFolioAIEditSnapshot as createFolioAIEditSnapshot$2 } from "@stll/folio-core/ai-edits/snapshot";
-import { findParagraphByParaId } from "@stll/folio-core/prosemirror/utils/findParagraphByParaId";
-import { deriveBlockId, getFolioParaIdFromBlockId, getFolioParaIdFromBlockId as getFolioParaIdFromBlockId$1, isFolioBlockId, isSequentialFolioBlockId } from "@stll/folio-core/types/block-id";
+import { deriveBlockId, getFolioParaIdFromBlockId, getFolioParaIdFromBlockId as getFolioParaIdFromBlockId$1, getSequentialFolioBlockIdIndex, isFolioBlockId, isSequentialFolioBlockId } from "@stll/folio-core/types/block-id";
 import { CONTENT_CONTROL_WIDGET_EVENT_NAME, dispatchDatePick, dispatchDropdownPick } from "@stll/folio-core/prosemirror/plugins/contentControlWidgets";
 import { ErrorManager } from "@stll/folio-core/managers/ErrorManager";
 import { ContextMenuManager } from "@stll/folio-core/managers/ContextMenuManager";
@@ -91,6 +93,7 @@ import { applyImagePosition, applyImageProperties, applyImageTransform, applyIma
 import { classifyEditorKeydown, deleteSelectedTable, isFocusInInputLike, isMacPlatform } from "@stll/folio-core/managers/editorShortcuts";
 import { getScrollTopForZoomAnchor, getViewportCenterZoomAnchorForZoomChange } from "@stll/folio-core/paged-layout/zoomScrollAnchor";
 import { redo, undo } from "prosemirror-history";
+import { createRoot } from "react-dom/client";
 import { createEmptyDocument } from "@stll/folio-core/utils/createDocument";
 import { createDocx } from "@stll/folio-core/docx/rezip";
 import { DEFAULT_AI_SUGGESTION_PRESETS } from "@stll/folio-core/ai-suggestions/types";
@@ -623,7 +626,8 @@ const AutocompleteCaretOverlay = ({ caret, text, isStreaming }) => {
 				position: "absolute",
 				left: caret.x,
 				top: caret.y,
-				lineHeight: `${caret.lineHeight}px`
+				lineHeight: `${caret.lineHeight}px`,
+				...caret.maxWidth !== void 0 ? { maxWidth: `${caret.maxWidth}px` } : {}
 			},
 			children: [text, /* @__PURE__ */ jsx("span", {
 				className: isStreaming ? "folio-autocomplete-caret folio-autocomplete-caret--streaming" : "folio-autocomplete-caret",
@@ -1849,6 +1853,13 @@ const TRANSACTION_LAYOUT_DEBOUNCE_MS = 32;
 const TRANSACTION_LAYOUT_MAX_DELAY_MS = 96;
 /** Keep the visual caret hidden briefly while typed content relayouts. */
 const SELECTION_REVEAL_AFTER_INPUT_DELAY = 120;
+/**
+* Readability floor for the autocomplete ghost width: with the caret at the
+* right content boundary, an unfloored width plus `overflow-wrap: anywhere`
+* would wrap the suggestion into a one-character-wide vertical column. Near
+* the margin the ghost overflows slightly past it instead.
+*/
+const AUTOCOMPLETE_GHOST_MIN_WIDTH = 100;
 const EMPTY_PLUGINS = [];
 const EMPTY_TEMPLATE_PREVIEW_ENTRIES = [];
 const EMPTY_AI_SUGGESTIONS = [];
@@ -3219,10 +3230,13 @@ function PagedEditor(props) {
 			const pageOffsetX = (pageRect.left - overlayRect.left) / zoom;
 			const pageOffsetY = (pageRect.top - overlayRect.top) / zoom;
 			if (!isCurrentRequest()) return;
+			const caretPage = layout.pages.at(caret.pageIndex);
+			const maxWidth = caretPage ? Math.max(AUTOCOMPLETE_GHOST_MIN_WIDTH, caretPage.size.w - caretPage.margins.right - caret.x) : void 0;
 			setAutocompleteCaret({
 				x: caret.x + pageOffsetX,
 				y: caret.y + pageOffsetY,
-				lineHeight: caret.height
+				lineHeight: caret.height,
+				maxWidth
 			});
 			setAutocompleteText(current.text);
 			setAutocompleteIsStreaming(current.status === "streaming");
@@ -3558,6 +3572,24 @@ function PagedEditor(props) {
 			inline: "nearest"
 		});
 	}, [layout, scrollToPositionImpl]);
+	const scrollToParaIdImpl = useCallback((paraId, options) => {
+		const state = hiddenPMRef.current?.getState();
+		if (!state) return false;
+		const startPos = findStartPosForParaId(state.doc, paraId);
+		if (startPos == null || startPos < 0) return false;
+		scrollToPositionImpl(startPos);
+		requestAnimationFrame(() => {
+			if (options?.highlight) {
+				const pages = pagesContainerRef.current;
+				if (pages) flashParagraphFragmentsByParaId(pages, paraId, options.highlight);
+			}
+			const targetNode = state.doc.nodeAt(startPos);
+			const inner = targetNode?.isTextblock === true ? Math.min(startPos + 1 + targetNode.content.size, state.doc.content.size) : Math.min(startPos + 1, state.doc.content.size);
+			hiddenPMRef.current?.setSelection(inner);
+			hiddenPMRef.current?.focus();
+		});
+		return true;
+	}, [scrollToPositionImpl]);
 	const focusHiddenEditor = useCallback(() => {
 		if (readOnly) {
 			containerRef.current?.focus({ preventScroll: true });
@@ -4978,6 +5010,7 @@ function PagedEditor(props) {
 		},
 		scrollToPosition: scrollToPositionImpl,
 		scrollToPage: scrollToPageImpl,
+		scrollToParaId: scrollToParaIdImpl,
 		getPageNumberForPmPos(pmPos) {
 			const container = pagesContainerRef.current;
 			if (!container) return null;
@@ -5017,6 +5050,7 @@ function PagedEditor(props) {
 		ensureHiddenEditorView,
 		folioEditor,
 		scrollToPageImpl,
+		scrollToParaIdImpl,
 		scrollToPositionImpl
 	]);
 	useEffect(() => {
@@ -5891,11 +5925,32 @@ const resolveFolioAIBlockRange = ({ blockId, doc, snapshot }) => {
 			to: liveRange.to
 		};
 	}
-	const anchor = (snapshot ?? createFolioAIEditSnapshot$2(doc)).anchors[blockId];
+	const resolvedSnapshot = snapshot ?? createFolioAIEditSnapshot$2(doc);
+	const anchor = resolvedSnapshot.anchors[blockId] ?? resolveSequentialBlockAnchor(blockId, resolvedSnapshot);
 	if (!anchor) return null;
 	return clampRangeToDocSize(doc.content.size, anchor);
 };
 /**
+* Resolve a `seq-NNNN` fallback id by document position.
+*
+* A sequential id is only minted for a paragraph the source DOCX left
+* without a `w14:paraId`. The live editor's `ParaIdAllocator` fills
+* that gap with a fresh random hex paraId, so a snapshot of the live
+* document keys the block by that hex and never reproduces the
+* server's `seq-NNNN`: the direct anchor lookup misses, and a
+* paraId-based live lookup can't match either (no node carries a
+* `seq-` paraId). The seq number is the block's 1-based position in
+* the same non-empty-block walk the server extractor and
+* `createFolioAIEditSnapshot` share, so it indexes the snapshot's
+* ordered `blocks` directly.
+*/
+const resolveSequentialBlockAnchor = (blockId, snapshot) => {
+	const index = getSequentialFolioBlockIdIndex(blockId);
+	if (index === null) return;
+	const block = snapshot.blocks.at(index - 1);
+	return block ? snapshot.anchors[block.id] : void 0;
+};
+/**
 * Clamp a `{from, to}` pair so both endpoints fit inside a document of
 * `docSize` (in PM content positions). Block-boundary snapshots and stale
 * range data sometimes produce a `to` one past the last inline position;
@@ -6206,30 +6261,34 @@ function ContentControlWidgetsOverlay({ getEditorView }) {
 		if (liveView && value.length > 0) dispatchDatePick(liveView, open.pmPos, value);
 		close();
 	};
-	return createPortal(/* @__PURE__ */ jsxs("div", {
-		role: "dialog",
-		"aria-label": open.kind === "dropdown" ? t("contentControlDropdownAriaLabel") : t("contentControlDateAriaLabel"),
-		style,
-		className: "bg-popover text-popover-foreground min-w-[10rem] rounded-md border p-1 shadow-md",
-		children: [open.kind === "dropdown" && /* @__PURE__ */ jsx("div", {
-			role: "menu",
-			className: "flex flex-col",
-			children: open.items.length === 0 ? /* @__PURE__ */ jsx("div", {
-				className: "text-muted-foreground px-2 py-1 text-sm",
-				children: t("contentControlDropdownNoOptions")
-			}) : open.items.map((item) => /* @__PURE__ */ jsx(MenuItem, {
-				onClick: () => onDropdownPick(item.value),
-				children: item.displayText
-			}, `${item.value}::${item.displayText}`))
-		}), open.kind === "date" && /* @__PURE__ */ jsx(DatePickerPopover, {
-			clearLabel: t("clearDate"),
-			defaultOpen: true,
-			onChange: (value) => {
-				if (value) onDatePick(value);
-			},
-			showIcon: false,
-			value: null
-		})]
+	return createPortal(/* @__PURE__ */ jsx("div", {
+		className: "folio-root",
+		style: { display: "contents" },
+		children: /* @__PURE__ */ jsxs("div", {
+			role: "dialog",
+			"aria-label": open.kind === "dropdown" ? t("contentControlDropdownAriaLabel") : t("contentControlDateAriaLabel"),
+			style,
+			className: "bg-popover text-popover-foreground min-w-[10rem] rounded-md border p-1 shadow-md",
+			children: [open.kind === "dropdown" && /* @__PURE__ */ jsx("div", {
+				role: "menu",
+				className: "flex flex-col",
+				children: open.items.length === 0 ? /* @__PURE__ */ jsx("div", {
+					className: "text-muted-foreground px-2 py-1 text-sm",
+					children: t("contentControlDropdownNoOptions")
+				}) : open.items.map((item) => /* @__PURE__ */ jsx(MenuItem, {
+					onClick: () => onDropdownPick(item.value),
+					children: item.displayText
+				}, `${item.value}::${item.displayText}`))
+			}), open.kind === "date" && /* @__PURE__ */ jsx(DatePickerPopover, {
+				clearLabel: t("clearDate"),
+				defaultOpen: true,
+				onChange: (value) => {
+					if (value) onDatePick(value);
+				},
+				showIcon: false,
+				value: null
+			})]
+		})
 	}), document.body);
 }
 //#endregion
@@ -6313,12 +6372,12 @@ const DocumentOutline = ({ headings, scrollContainerRef, topOffset, docSize, onH
 };
 //#endregion
 //#region src/components/DocxEditorDialogs.tsx
-const FindReplaceDialog = lazy(() => import("./FindReplaceDialog-CG1VKA_g.js").then((m) => ({ default: m.FindReplaceDialog })));
-const TablePropertiesDialog = lazy(() => import("./TablePropertiesDialog-mQMnGfHu.js").then((m) => ({ default: m.TablePropertiesDialog })));
-const ImagePositionDialog = lazy(() => import("./ImagePositionDialog-BQnOnDf4.js").then((m) => ({ default: m.ImagePositionDialog })));
-const ImagePropertiesDialog = lazy(() => import("./ImagePropertiesDialog-Dn4N7qZv.js").then((m) => ({ default: m.ImagePropertiesDialog })));
-const FootnotePropertiesDialog = lazy(() => import("./FootnotePropertiesDialog-MuW4D3gt.js").then((m) => ({ default: m.FootnotePropertiesDialog })));
-const PageSetupDialog = lazy(() => import("./PageSetupDialog-CxJUEkoC.js").then((m) => ({ default: m.PageSetupDialog })));
+const FindReplaceDialog = lazy(() => import("./FindReplaceDialog-EFjmqEbg.js").then((m) => ({ default: m.FindReplaceDialog })));
+const TablePropertiesDialog = lazy(() => import("./TablePropertiesDialog-ZmzjSqME.js").then((m) => ({ default: m.TablePropertiesDialog })));
+const ImagePositionDialog = lazy(() => import("./ImagePositionDialog-FGLCOf0Q.js").then((m) => ({ default: m.ImagePositionDialog })));
+const ImagePropertiesDialog = lazy(() => import("./ImagePropertiesDialog-Baokui4M.js").then((m) => ({ default: m.ImagePropertiesDialog })));
+const FootnotePropertiesDialog = lazy(() => import("./FootnotePropertiesDialog-VfF7SQo2.js").then((m) => ({ default: m.FootnotePropertiesDialog })));
+const PageSetupDialog = lazy(() => import("./PageSetupDialog-Df2HjHiu.js").then((m) => ({ default: m.PageSetupDialog })));
 function DocxEditorDialogs({ findReplace, tableProperties, imagePosition, imageProperties, pageSetup, footnoteProperties }) {
 	return /* @__PURE__ */ jsxs(Suspense, {
 		fallback: null,
@@ -6640,7 +6699,7 @@ function ToolbarButton({ active = false, disabled = false, title, onClick, onDou
 	};
 	const button = /* @__PURE__ */ jsx("button", {
 		type: "button",
-		className: cn("flex h-8 w-8 shrink-0 items-center justify-center rounded-md", "transition-colors duration-100", "-webkit-font-smoothing-antialiased", "text-[var(--doc-text-muted)] hover:bg-[var(--doc-primary-light)] hover:text-[var(--doc-text)]", active && "bg-[var(--doc-primary-light)] text-[var(--doc-text)] hover:bg-[var(--doc-primary-light)]", disabled && "cursor-not-allowed text-[var(--doc-text-subtle)] opacity-[0.16] disabled:hover:bg-transparent disabled:hover:text-[var(--doc-text-subtle)]", className),
+		className: cn("flex h-8 w-8 shrink-0 items-center justify-center rounded-md", "transition-colors duration-100", "antialiased", "text-[var(--doc-text-muted)] hover:bg-[var(--doc-primary-light)] hover:text-[var(--doc-text)]", active && "bg-[var(--doc-primary-light)] text-[var(--doc-text)] hover:bg-[var(--doc-primary-light)]", disabled && "cursor-not-allowed text-[var(--doc-text-subtle)] opacity-[0.16] disabled:hover:bg-transparent disabled:hover:text-[var(--doc-text-subtle)]", className),
 		onMouseDown: handleMouseDown,
 		onClick: disabled ? void 0 : onClick,
 		onDoubleClick: disabled ? void 0 : onDoubleClick,
@@ -9659,21 +9718,32 @@ const getBuiltinTableStyle = (styleId) => BUILTIN_STYLES.find((s) => s.id === st
 * (`replaceComments`/`updateComments`) stay in the component because they
 * depend on its document-build pipeline.
 */
-function useFolioComments({ doc, autoOpenReviewSidebar, anchorPositions, editorContentRef }) {
+function useFolioComments({ doc, autoOpenReviewSidebar, anchorPositions, editorContentRef, commentsProp, onCommentsChange }) {
 	const [showCommentsSidebar, setShowCommentsSidebar] = useState(false);
 	const [visibleCommentAuthors, setVisibleCommentAuthors] = useState(null);
 	const [activeCommentId, setActiveCommentId] = useState(null);
-	const [comments, setComments] = useState([]);
+	const [internalComments, setInternalComments] = useState([]);
+	const isControlledComments = commentsProp !== void 0;
+	const comments = isControlledComments ? commentsProp : internalComments;
 	const commentsDirtyRef = useRef(false);
-	const commentsRef = useRef([]);
+	const commentsRef = useRef(comments);
 	commentsRef.current = comments;
+	const onCommentsChangeRef = useRef(onCommentsChange);
+	onCommentsChangeRef.current = onCommentsChange;
+	const setComments = useCallback((next) => {
+		const resolved = typeof next === "function" ? next(commentsRef.current) : next;
+		if (resolved === commentsRef.current) return;
+		commentsRef.current = resolved;
+		if (!isControlledComments) setInternalComments(resolved);
+		onCommentsChangeRef.current?.(resolved);
+	}, [isControlledComments]);
 	const [isAddingComment, setIsAddingComment] = useState(false);
 	const [commentSelectionRange, setCommentSelectionRange] = useState(null);
 	const [addCommentYPosition, setAddCommentYPosition] = useState(null);
 	const [floatingCommentBtn, setFloatingCommentBtn] = useState(null);
 	const commentsLoadedRef = useRef(false);
 	useEffect(() => {
-		if (commentsLoadedRef.current) return;
+		if (isControlledComments || commentsLoadedRef.current) return;
 		if (!doc) return;
 		const bodyComments = doc.package.document.comments;
 		if (bodyComments && bodyComments.length > 0) {
@@ -9683,7 +9753,12 @@ function useFolioComments({ doc, autoOpenReviewSidebar, anchorPositions, editorC
 			if (autoOpenReviewSidebar) setShowCommentsSidebar(true);
 			commentsLoadedRef.current = true;
 		}
-	}, [autoOpenReviewSidebar, doc]);
+	}, [
+		autoOpenReviewSidebar,
+		doc,
+		isControlledComments,
+		setComments
+	]);
 	const commentAuthors = useMemo(() => {
 		const seen = /* @__PURE__ */ new Set();
 		const authors = [];
@@ -9769,6 +9844,7 @@ function useFolioComments({ doc, autoOpenReviewSidebar, anchorPositions, editorC
 	return {
 		comments,
 		setComments,
+		isControlledComments,
 		commentsRef,
 		commentsDirtyRef,
 		commentsLoadedRef,
@@ -9804,7 +9880,7 @@ function useFolioComments({ doc, autoOpenReviewSidebar, anchorPositions, editorC
 * - Loading states
 */
 const CommentsSidebar = lazy(() => import("./CommentsSidebar-BsYOInaX.js").then((m) => ({ default: m.CommentsSidebar })));
-const TextContextMenu = lazy(() => import("./TextContextMenu-DzTbp2sn.js").then((m) => ({ default: m.TextContextMenu })));
+const TextContextMenu = lazy(() => import("./TextContextMenu-CG0V37wi.js").then((m) => ({ default: m.TextContextMenu })));
 const loadAttemptSelectiveSave = async () => {
 	const { attemptSelectiveSave } = await import("@stll/folio-core/docx/selectiveSave");
 	return attemptSelectiveSave;
@@ -9883,7 +9959,7 @@ function areActiveTrackedChangesEqual(a, b) {
 /**
 * DocxEditor - Complete DOCX editor component
 */
-function DocxEditor({ ref, documentBuffer, document: initialDocument, documentKey, onSave, author = "User", onChange, onSelectionChange, onSelectionTextChange, onError, onFontsLoaded: onFontsLoadedCallback, fontFamilies, fonts, theme, showToolbar = true, showZoomControl = true, showReviewControls = true, showHeaderFooterEditing = true, showMarginGuides: _showMarginGuides = false, marginGuideColor: _marginGuideColor, showRuler: showRulerProp = false, rulerUnit = "inch", initialZoom = 1, enableWheelZoom = true, readOnly: readOnlyProp = false, autoOpenReviewSidebar = true, components, toolbarExtra, className = "", style, placeholder, loadingIndicator, preserveDocumentWhileLoading = false, initialScrollTop, onScrollTopChange, showOutline: showOutlineProp = true, onPrint, onInsertImage, onInsertTable, showTableInsert = true, onInsertPageBreak, onInsertTOC, onCopy: _onCopy, onCut: _onCut, onPaste: _onPaste, mode: modeProp, onModeChange, onReadonlyEditAttempt, onCompatibilityChange, onEditorViewReady, onAnonymizationMatchesChange, onAnonymizationTermClick, selectedAnonymizationCanonical = null, anonymizationSelectionSeq, showTemplateDirectives = false, onSlashMenuChange, onSlashMenuKeyAction, customContextMenuItems, onCustomContextAction, collaboration, featureFlags, onSelectiveSaveTripwire }) {
+function DocxEditor({ ref, documentBuffer, document: initialDocument, documentKey, onSave, author = "User", onChange, onSelectionChange, onSelectionTextChange, onError, onFontsLoaded: onFontsLoadedCallback, fontFamilies, fonts, theme, showToolbar = true, showZoomControl = true, showReviewControls = true, showHeaderFooterEditing = true, showMarginGuides: _showMarginGuides = false, marginGuideColor: _marginGuideColor, showRuler: showRulerProp = false, rulerUnit = "inch", initialZoom = 1, enableWheelZoom = true, readOnly: readOnlyProp = false, autoOpenReviewSidebar = true, components, toolbarExtra, className = "", style, placeholder, loadingIndicator, preserveDocumentWhileLoading = false, initialScrollTop, onScrollTopChange, showOutline: showOutlineProp = true, onPrint, onInsertImage, onInsertTable, showTableInsert = true, onInsertPageBreak, onInsertTOC, onCopy: _onCopy, onCut: _onCut, onPaste: _onPaste, mode: modeProp, onModeChange, onReadonlyEditAttempt, onCompatibilityChange, onEditorViewReady, onAnonymizationMatchesChange, onAnonymizationTermClick, selectedAnonymizationCanonical = null, anonymizationSelectionSeq, showTemplateDirectives = false, onSlashMenuChange, onSlashMenuKeyAction, customContextMenuItems, onCustomContextAction, comments: commentsProp, onCommentsChange, collaboration, featureFlags, onSelectiveSaveTripwire }) {
 	const t = useTranslations("folio");
 	useEffect(() => {
 		const onClipboardReadError = () => {
@@ -10097,7 +10173,9 @@ function DocxEditor({ ref, documentBuffer, document: initialDocument, documentKe
 		doc: history.state,
 		autoOpenReviewSidebar,
 		anchorPositions,
-		editorContentRef
+		editorContentRef,
+		commentsProp,
+		onCommentsChange
 	});
 	const styleResolverCacheRef = useRef(null);
 	const getCachedStyleResolver = useCallback((styles) => {
@@ -11358,6 +11436,7 @@ function DocxEditor({ ref, documentBuffer, document: initialDocument, documentKe
 		scrollToPage: (pageNumber) => {
 			pagedEditorRef.current?.scrollToPage(pageNumber);
 		},
+		scrollToParaId: (paraId, options) => pagedEditorRef.current?.scrollToParaId(paraId, options) ?? false,
 		openPrintPreview: handleDirectPrint,
 		print: handleDirectPrint,
 		loadDocument: loadParsedDocument,
@@ -12286,4 +12365,100 @@ function DocxEditor({ ref, documentBuffer, document: initialDocument, documentKe
 	});
 }
 //#endregion
-export { AutocompleteCaretOverlay, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DocxEditor, FolioUIProvider, FormattingBar, ZOOM_PRESETS, ZoomControl, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applySuggestions, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildPositionalText, clampZoom, clearAutocompleteSuggestion, clearTemplateSlashMenu, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, deriveBlockId, diffWordSegments, finishAutocompleteSuggestion, formatZoom, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getFolioCaretViewportRect, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, insertImageFromFile, insertPageBreakInView, insertTableInView, insertTableOfContentsInView, isFolioBlockId, isSequentialFolioBlockId, isSuggestionStale, normalizeFolioAIBlockText, parseZoom, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setFocusedSuggestionMeta, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult, useWheelZoom };
+//#region src/renderAsync.tsx
+/**
+* Imperative API for mounting a DOCX editor into a DOM element.
+*
+* Returns a framework-agnostic {@link EditorHandle} extended with zoom and
+* scroll helpers. Wraps the editor in `IntlProvider` so `use-intl` works
+* without extra host setup.
+*
+* ```ts
+* import { renderAsync } from "@stll/folio-react";
+* import "@stll/folio-react/standalone.css";
+*
+* const editor = await renderAsync(buffer, document.getElementById("host")!, {
+*   readOnly: false,
+*   showToolbar: true,
+* });
+*
+* const blob = await editor.save();
+* editor.destroy();
+* ```
+*/
+/**
+* Render a DOCX editor into a container element.
+*
+* Resolves once the document has parsed and the first `onChange` fires.
+* Rejects if `onError` runs before that milestone.
+*/
+const renderAsync = (input, container, options = {}) => {
+	const { locale = "en", ...editorOptions } = options;
+	return new Promise((resolve, reject) => {
+		const ref = React.createRef();
+		let root = null;
+		let settled = false;
+		try {
+			root = createRoot(container);
+		} catch (error) {
+			reject(error);
+			return;
+		}
+		const handle = {
+			save: async () => {
+				const buffer = await (ref.current?.save() ?? Promise.resolve(null));
+				if (!buffer) return null;
+				return new Blob([buffer], { type: "application/vnd.openxmlformats-officedocument.wordprocessingml.document" });
+			},
+			getDocument: () => ref.current?.getDocument() ?? null,
+			focus: () => {
+				ref.current?.focus();
+			},
+			setZoom: (zoom) => {
+				ref.current?.setZoom(zoom);
+			},
+			scrollToPosition: (pmPos) => {
+				ref.current?.getEditorRef()?.scrollToPosition(pmPos);
+			},
+			scrollToPage: (pageNumber) => {
+				ref.current?.scrollToPage(pageNumber);
+			},
+			destroy: () => {
+				if (!settled) {
+					settled = true;
+					reject(/* @__PURE__ */ new Error("Editor was destroyed before mounting completed."));
+				}
+				root?.unmount();
+				root = null;
+			}
+		};
+		const element = /* @__PURE__ */ jsx(IntlProvider, {
+			locale,
+			messages: getFolioMessages(locale),
+			children: /* @__PURE__ */ jsx(DocxEditor, {
+				...editorOptions,
+				documentBuffer: input,
+				onError: (error) => {
+					editorOptions["onError"]?.(error);
+					if (!settled) {
+						settled = true;
+						root?.unmount();
+						root = null;
+						reject(error);
+					}
+				},
+				onChange: (doc) => {
+					editorOptions["onChange"]?.(doc);
+					if (!settled) {
+						settled = true;
+						resolve(handle);
+					}
+				},
+				ref
+			})
+		});
+		root.render(element);
+	});
+};
+//#endregion
+export { AutocompleteCaretOverlay, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DocxEditor, FolioUIProvider, FormattingBar, ZOOM_PRESETS, ZoomControl, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applySuggestions, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildPositionalText, clampZoom, clearAutocompleteSuggestion, clearTemplateSlashMenu, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, deriveBlockId, diffWordSegments, finishAutocompleteSuggestion, formatZoom, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getFolioCaretViewportRect, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, insertImageFromFile, insertPageBreakInView, insertTableInView, insertTableOfContentsInView, isFolioBlockId, isSequentialFolioBlockId, isSuggestionStale, normalizeFolioAIBlockText, parseZoom, renderAsync, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setFocusedSuggestionMeta, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult, useWheelZoom };