@stll/folio-react 0.1.1 → 0.3.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 { t as messages_exports } from "./messages.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";
@@ -62,20 +63,21 @@ import { recordLayoutPhase } from "@stll/folio-core/layout-engine/layoutInstrume
 import { LayoutPainter } from "@stll/folio-core/layout-painter";
 import { PAINTER_PAINTED_EVENT, findPageShellForPmPos } from "@stll/folio-core/layout-painter/renderPage";
 import { LayoutSelectionGate } from "@stll/folio-core/paged-layout/LayoutSelectionGate";
-import { collectRunFontsAtPmPositions, measureContentLeft, projectRangesToRects } from "@stll/folio-core/paged-layout/rangeProjection";
+import { collectRunFontsAtPmPositions, measureDirectiveGutter, projectRangesToRects } from "@stll/folio-core/paged-layout/rangeProjection";
 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, 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";
@@ -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";
@@ -1447,63 +1450,213 @@ const overlayStyles = {
 };
 const BLOCK_OPENERS = /* @__PURE__ */ new Set(["if", "each"]);
 const BLOCK_CLOSERS = /* @__PURE__ */ new Set(["endif", "endeach"]);
-const RAIL_BASE_GUTTER = 12;
+const RAIL_WIDTH = 2.5;
+/** Horizontal gap between adjacent nesting depths' rails. */
 const RAIL_DEPTH_GAP = 5;
-const RAIL_WIDTH = 2;
+/** Minimum clear space between the innermost (deepest) rail and the text edge. */
+const RAIL_TEXT_CLEARANCE = 6;
+/** Keep the outermost rail this far off the physical page-left edge. */
+const RAIL_EDGE_PAD = 2;
+/** Drop per-page segments thinner than this (sub-pixel slivers at a page seam). */
+const RAIL_SEGMENT_MIN_HEIGHT = 2;
+const bandKindOf = (kind) => kind === "each" ? "each" : "if";
 /**
-* Pair opener/closer block directives with a stack so each conditional/loop
-* region knows its top, bottom, and nesting depth (for the gutter rail).
-* Unbalanced directives are skipped. The rail's horizontal position comes from
-* the stable `contentLeft` anchor (not the opener's re-projected rect), so it
-* stays put while text above reflows; only its vertical span tracks the rects.
+* Deepest nesting level whose rail still fits inside the left margin with a
+* `RAIL_TEXT_CLEARANCE` gap to the text and a `RAIL_EDGE_PAD` gap to the page
+* edge. Depths past this reuse the deepest offset, so a 5-level nest can never
+* march a rail into the text column. Pure function of the measured margin width.
 */
-const computeBands = (groups, contentLeft) => {
-	const blocks = groups.filter((g) => g.range.block && (BLOCK_OPENERS.has(g.range.kind) || BLOCK_CLOSERS.has(g.range.kind))).sort((a, b) => a.range.from - b.range.from);
-	const bands = [];
+const railBudgetDepth = (marginWidth) => {
+	const usable = marginWidth - RAIL_TEXT_CLEARANCE - RAIL_WIDTH - RAIL_EDGE_PAD;
+	if (usable <= 0) return 0;
+	return Math.floor(usable / RAIL_DEPTH_GAP);
+};
+/**
+* Left edge (container space) of a depth-`depth` rail. The deepest rail the
+* budget allows sits `RAIL_TEXT_CLEARANCE + RAIL_WIDTH` left of the text edge;
+* shallower (outer) blocks fan further left into the margin — nested blocks read
+* as concentric brackets `[ [ [ text ] ] ]`. Depths beyond the budget clamp to
+* the deepest offset.
+*/
+const railXForDepth = (depth, contentLeft, marginWidth) => {
+	const budget = railBudgetDepth(marginWidth);
+	const capped = Math.min(Math.max(0, depth), budget);
+	return contentLeft - RAIL_TEXT_CLEARANCE - RAIL_WIDTH - (budget - capped) * RAIL_DEPTH_GAP;
+};
+/**
+* Clip a band's vertical span to each page's body-content band so a rail is
+* drawn as one rounded segment per page and never paints across the inter-page
+* gap, header, or footer. With no page bands (geometry not ready) the whole span
+* is returned as a single segment so rails still show. Pure math.
+*/
+const segmentBandByPages = (band, pageBands) => {
+	if (pageBands.length === 0) return band.bottom - band.top >= RAIL_SEGMENT_MIN_HEIGHT ? [band] : [];
+	const segments = [];
+	for (const page of pageBands) {
+		const top = Math.max(band.top, page.top);
+		const bottom = Math.min(band.bottom, page.bottom);
+		if (bottom - top >= RAIL_SEGMENT_MIN_HEIGHT) segments.push({
+			top,
+			bottom
+		});
+	}
+	return segments;
+};
+/**
+* Pair block openers with their closers via a kind-aware stack, so both chips of
+* a pair share a `blockId`, the rail knows its opener→closer PM span, and each
+* pairing carries the `depth` recorded in this very walk (never a second,
+* possibly-divergent depth pass). A closer matches the nearest opener of the same
+* family ({{/if}} ⇒ {{#if}}, {{/each}} ⇒ {{#each}}) and drops any still-open
+* openers nested above it; a closer with no matching opener is ignored. This keeps
+* a mid-edit / unbalanced template from pairing a {{/if}} with an {{#each}}.
+* Inline (block:false) markers are excluded. Pure function of the ranges.
+*/
+const pairBlockRanges = (ranges) => {
+	const blocks = ranges.filter((r) => r.block && (BLOCK_OPENERS.has(r.kind) || BLOCK_CLOSERS.has(r.kind))).slice().sort((a, b) => a.from - b.from);
+	const pairings = [];
 	const stack = [];
-	for (const group of blocks) {
-		if (BLOCK_OPENERS.has(group.range.kind)) {
+	for (const range of blocks) {
+		if (BLOCK_OPENERS.has(range.kind)) {
 			stack.push({
-				group,
+				range,
 				depth: stack.length
 			});
 			continue;
 		}
-		const open = stack.pop();
-		const openerRect = open?.group.rects[0];
-		const closerRect = group.rects[0];
-		if (!open || !openerRect || !closerRect) continue;
-		const railBase = contentLeft ?? openerRect.x;
-		bands.push({
+		const wantOpener = range.kind === "endif" ? "if" : "each";
+		let matched;
+		let matchIdx = -1;
+		for (let i = stack.length - 1; i >= 0; i -= 1) {
+			const entry = stack[i];
+			if (entry?.range.kind === wantOpener) {
+				matched = entry;
+				matchIdx = i;
+				break;
+			}
+		}
+		if (!matched) continue;
+		stack.length = matchIdx;
+		pairings.push({
+			blockId: matched.range.from,
+			kind: bandKindOf(matched.range.kind),
+			depth: matched.depth,
+			openerFrom: matched.range.from,
+			closerFrom: range.from,
+			closerTo: range.to,
+			openerExpr: matched.range.expr
+		});
+	}
+	return pairings;
+};
+/** Hover hint for a closer chip: what it closes, e.g. `/if · hasVerdicts`. */
+const closerHintLabel = (kind, openerExpr) => {
+	const head = kind === "each" ? "/each" : "/if";
+	return openerExpr ? `${head} · ${openerExpr}` : head;
+};
+/**
+* Block id of the innermost pairing whose opener→closer span contains `caretPos`
+* (largest opener position wins), or null. Drives the caret emphasis.
+*/
+const innermostBlockAt = (pairings, caretPos) => {
+	if (caretPos === null) return null;
+	let bestBlockId = null;
+	let bestOpener = Number.NEGATIVE_INFINITY;
+	for (const pairing of pairings) if (caretPos >= pairing.openerFrom && caretPos <= pairing.closerTo && pairing.openerFrom > bestOpener) {
+		bestOpener = pairing.openerFrom;
+		bestBlockId = pairing.blockId;
+	}
+	return bestBlockId;
+};
+/**
+* Assemble the per-page rail segments for every balanced block: look up
+* opener/closer rects by `from`, place the rail by the pairing's own budgeted
+* depth, and clip its span to each page. Depth comes from the pairing (same walk
+* that matched opener→closer), so a rail's indentation and its span always agree.
+* O(pairings); all geometry comes from the props.
+*/
+const computeRailBands = (pairings, groups, gutter) => {
+	const groupByFrom = new Map(groups.map((group) => [group.range.from, group]));
+	const bands = [];
+	for (const pairing of pairings) {
+		const openerRect = groupByFrom.get(pairing.openerFrom)?.rects[0];
+		const closerRect = groupByFrom.get(pairing.closerFrom)?.rects[0];
+		if (!openerRect || !closerRect) continue;
+		const segments = segmentBandByPages({
 			top: openerRect.y,
-			bottom: closerRect.y + closerRect.height,
-			railX: railBase - RAIL_BASE_GUTTER + open.depth * RAIL_DEPTH_GAP
+			bottom: closerRect.y + closerRect.height
+		}, gutter.pageBands);
+		if (segments.length === 0) continue;
+		bands.push({
+			blockId: pairing.blockId,
+			kind: pairing.kind,
+			railX: railXForDepth(pairing.depth, gutter.contentLeft, gutter.marginWidth),
+			segments
 		});
 	}
 	return bands;
 };
-const TemplateDirectivesOverlay = ({ groups, contentLeft }) => {
+const blockIdFromTarget = (target) => {
+	if (!(target instanceof HTMLElement)) return null;
+	const raw = target.dataset["folioBlockId"];
+	return raw === void 0 ? null : Number(raw);
+};
+const TemplateDirectivesOverlay = ({ groups, gutter, caretPos, ranges }) => {
+	const [hoveredBlockId, setHoveredBlockId] = useState(null);
 	if (groups.length === 0) return null;
+	const pairings = pairBlockRanges(ranges);
+	const railBands = gutter ? computeRailBands(pairings, groups, gutter) : [];
+	const blockIdByFrom = /* @__PURE__ */ new Map();
+	const closerLabelByFrom = /* @__PURE__ */ new Map();
+	for (const pairing of pairings) {
+		blockIdByFrom.set(pairing.openerFrom, pairing.blockId);
+		blockIdByFrom.set(pairing.closerFrom, pairing.blockId);
+		closerLabelByFrom.set(pairing.closerFrom, closerHintLabel(pairing.kind, pairing.openerExpr));
+	}
+	const caretBlockId = innermostBlockAt(pairings, caretPos);
+	const isActive = (blockId) => blockId === hoveredBlockId || blockId === caretBlockId;
+	const handlePointerOver = (event) => {
+		const blockId = blockIdFromTarget(event.target);
+		if (blockId !== null) setHoveredBlockId(blockId);
+	};
+	const handlePointerOut = (event) => {
+		const from = blockIdFromTarget(event.target);
+		if (from === null) return;
+		const to = blockIdFromTarget(event.relatedTarget);
+		if (to === from) return;
+		setHoveredBlockId((current) => current === from ? to : current);
+	};
 	return /* @__PURE__ */ jsxs("div", {
 		style: overlayStyles,
 		"data-folio-template-directives-overlay": "",
-		children: [computeBands(groups, contentLeft).map((band, bandIdx) => /* @__PURE__ */ jsx("div", {
-			className: "folio-template-band-rail",
+		onPointerOver: handlePointerOver,
+		onPointerOut: handlePointerOut,
+		children: [railBands.flatMap((band) => band.segments.map((segment, segmentIdx) => /* @__PURE__ */ jsx("div", {
+			className: `folio-template-band-rail folio-template-band-rail--${band.kind}${isActive(band.blockId) ? " folio-template-band-rail--active" : ""}`,
+			"data-folio-block-id": band.blockId,
 			style: {
 				left: band.railX,
-				top: band.top,
+				top: segment.top,
 				width: RAIL_WIDTH,
-				height: Math.max(0, band.bottom - band.top)
-			}
-		}, `rail:${bandIdx}`)), groups.flatMap(({ range, rects }, groupIdx) => rects.map((rect, idx) => /* @__PURE__ */ jsx("span", {
-			className: `folio-template-directive folio-template-directive--${range.kind}`,
-			style: {
-				left: rect.x - 1,
-				top: rect.y + 1,
-				width: rect.width + 2,
-				height: Math.max(0, rect.height - 2)
-			}
-		}, `d:${groupIdx}:${idx}`)))]
+				height: Math.max(0, segment.bottom - segment.top)
+			}
+		}, `rail:${band.blockId}:${segmentIdx}`))), groups.flatMap(({ range, rects }, groupIdx) => {
+			const blockId = range.block ? blockIdByFrom.get(range.from) : void 0;
+			const isBlockChip = range.block && (BLOCK_OPENERS.has(range.kind) || BLOCK_CLOSERS.has(range.kind));
+			const closerLabel = range.block ? closerLabelByFrom.get(range.from) : void 0;
+			const active = blockId !== void 0 && isActive(blockId);
+			return rects.map((rect, idx) => /* @__PURE__ */ jsx("span", {
+				className: `folio-template-directive folio-template-directive--${range.kind}${isBlockChip ? " folio-template-directive--block" : ""}${active ? " folio-template-directive--active" : ""}`,
+				...blockId !== void 0 ? { "data-folio-block-id": blockId } : {},
+				...closerLabel !== void 0 ? { title: closerLabel } : {},
+				style: {
+					left: rect.x - 1,
+					top: rect.y + 1,
+					width: rect.width + 2,
+					height: Math.max(0, rect.height - 2)
+				}
+			}, `d:${groupIdx}:${idx}`));
+		})]
 	});
 };
 //#endregion
@@ -2561,7 +2714,8 @@ function PagedEditor(props) {
 	const [autocompleteText, setAutocompleteText] = useState("");
 	const [autocompleteIsStreaming, setAutocompleteIsStreaming] = useState(false);
 	const [directiveRectGroups, setDirectiveRectGroups] = useState([]);
-	const [directiveContentLeft, setDirectiveContentLeft] = useState(null);
+	const [directiveGutter, setDirectiveGutter] = useState(null);
+	const [directiveCaretPos, setDirectiveCaretPos] = useState(null);
 	const directivesRef = useRef([]);
 	const directivesOverlayRequestSeqRef = useRef(0);
 	const templatePreviewRef = useRef({
@@ -2948,6 +3102,7 @@ function PagedEditor(props) {
 		const requestSeq = selectionOverlayRequestSeqRef.current + 1;
 		selectionOverlayRequestSeqRef.current = requestSeq;
 		const isCurrentRequest = () => selectionOverlayRequestSeqRef.current === requestSeq;
+		if (directivesRef.current.length > 0) setDirectiveCaretPos(state.selection.head);
 		onSelectionChangeRef.current?.(from, to);
 		folioEmitterRef.current.emit("selectionChange", {
 			from,
@@ -3252,10 +3407,10 @@ function PagedEditor(props) {
 		const pagesContainer = pagesContainerRef.current;
 		if (ranges.length === 0 || !pagesContainer) {
 			setDirectiveRectGroups([]);
-			setDirectiveContentLeft(null);
+			setDirectiveGutter(null);
 			return;
 		}
-		setDirectiveContentLeft(measureContentLeft(pagesContainer, zoom));
+		setDirectiveGutter(measureDirectiveGutter(pagesContainer, zoom));
 		(async () => {
 			const projected = await projectRangesToRects(ranges, {
 				pagesContainer,
@@ -3569,6 +3724,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 });
@@ -4989,6 +5162,7 @@ function PagedEditor(props) {
 		},
 		scrollToPosition: scrollToPositionImpl,
 		scrollToPage: scrollToPageImpl,
+		scrollToParaId: scrollToParaIdImpl,
 		getPageNumberForPmPos(pmPos) {
 			const container = pagesContainerRef.current;
 			if (!container) return null;
@@ -5028,6 +5202,7 @@ function PagedEditor(props) {
 		ensureHiddenEditorView,
 		folioEditor,
 		scrollToPageImpl,
+		scrollToParaIdImpl,
 		scrollToPositionImpl
 	]);
 	useEffect(() => {
@@ -5144,8 +5319,10 @@ function PagedEditor(props) {
 						}),
 						/* @__PURE__ */ jsx(AISuggestionRectsOverlay, { groups: aiSuggestionRectGroups }),
 						showTemplateDirectives && /* @__PURE__ */ jsx(TemplateDirectivesOverlay, {
-							contentLeft: directiveContentLeft,
-							groups: directiveRectGroups
+							gutter: directiveGutter,
+							groups: directiveRectGroups,
+							caretPos: directiveCaretPos,
+							ranges: directivesRef.current
 						}),
 						/* @__PURE__ */ jsx(SelectionOverlay, {
 							selectionRects: hfEditMode ? EMPTY_SELECTION_RECTS : selectionRects,
@@ -6238,30 +6415,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
@@ -6345,12 +6526,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,
@@ -6672,7 +6853,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,
@@ -9691,21 +9872,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) {
@@ -9715,7 +9907,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 = [];
@@ -9801,6 +9998,7 @@ function useFolioComments({ doc, autoOpenReviewSidebar, anchorPositions, editorC
 	return {
 		comments,
 		setComments,
+		isControlledComments,
 		commentsRef,
 		commentsDirtyRef,
 		commentsLoadedRef,
@@ -9836,7 +10034,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;
@@ -9915,7 +10113,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 = () => {
@@ -10129,7 +10327,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) => {
@@ -11390,6 +11590,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,
@@ -12318,4 +12519,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: (0, messages_exports.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 };