superdoc 2.4.0-next.16 → 2.4.0-next.18

package/dist/superdoc.es.js

@@ -3,7 +3,7 @@ import { t as blank_default } from "./chunks/blank-docx-DzQccOlW.es.js";
 import { t as import_eventemitter3 } from "./chunks/eventemitter3-DEIiXiH2.es.js";
 import { t as v4 } from "./chunks/uuid-H0Xcmmhy.es.js";
 import { a as init_dist$1, i as global, n as init_dist$2, o as Buffer, r as process$1, s as init_dist, t as require_jszip_min } from "./chunks/jszip-BzJ3CyxR.es.js";
-import { a as createV2ReviewMutationReconciler, i as isV2EditableTextMutationEvent, o as getV2TrackedChangeMutationImpact, s as DOM_CLASS_NAMES, t as createSuperDocUI } from "./chunks/create-super-doc-ui-BRBwfV-s.es.js";
+import { a as getV2TrackedChangeMutationImpact, i as createV2ReviewMutationReconciler, o as DOM_CLASS_NAMES, t as createSuperDocUI } from "./chunks/create-super-doc-ui-BbNbi0cj.es.js";
 import { t as _plugin_vue_export_helper_default } from "./chunks/_plugin-vue_export-helper-BOaGB7Aw.es.js";
 import { t as PDF_TO_CSS_UNITS } from "./chunks/constants-B6VBlmKp.es.js";
 import * as Vue from "vue";
@@ -7761,6 +7761,7 @@ var useCommentsStore = defineStore("comments", () => {
 		syncResolvedCommentsWithDocument();
 	});
 	watch(commentsList, () => {
+		canonicalizeActiveCommentAlias();
 		syncResolvedCommentsWithDocument();
 	}, { deep: false });
 	/**
@@ -8560,6 +8561,61 @@ var useCommentsStore = defineStore("comments", () => {
 		syncCommentsToClients(superdoc, event);
 		return Promise.resolve({ ok: true });
 	};
+	const applyV2ThreadLifecycleReceipt = ({ superdoc, documentId, lifecycle } = {}) => {
+		const commentId = normalizeCommentId(lifecycle?.commentId);
+		const status = lifecycle?.status;
+		if (!commentId || status !== "open" && status !== "resolved") return null;
+		const normalizedDocumentId = normalizeCommentId(documentId);
+		const rows = commentsList.value.filter((comment) => {
+			if (!comment || comment.trackedChange === true || isV2SyntheticTrackedChangeRow(comment)) return false;
+			const rowDocumentId = normalizeCommentId(comment.fileId);
+			return normalizedDocumentId == null || rowDocumentId == null || rowDocumentId === normalizedDocumentId;
+		});
+		const byAlias = /* @__PURE__ */ new Map();
+		const childrenByParentAlias = /* @__PURE__ */ new Map();
+		for (const row of rows) {
+			for (const alias of [row.commentId, row.importedId].map(normalizeCommentId).filter(Boolean)) if (!byAlias.has(alias)) byAlias.set(alias, row);
+			const parentId = normalizeCommentId(row.parentCommentId);
+			if (parentId) {
+				const children = childrenByParentAlias.get(parentId) ?? [];
+				children.push(row);
+				childrenByParentAlias.set(parentId, children);
+			}
+		}
+		let root = byAlias.get(commentId) ?? null;
+		const seenParents = /* @__PURE__ */ new Set();
+		while (root?.parentCommentId != null) {
+			const parentId = normalizeCommentId(root.parentCommentId);
+			if (!parentId || seenParents.has(parentId)) break;
+			seenParents.add(parentId);
+			const parent = byAlias.get(parentId);
+			if (!parent) break;
+			root = parent;
+		}
+		if (!root) return null;
+		const family = [];
+		const queue = [root];
+		const visited = /* @__PURE__ */ new Set();
+		while (queue.length > 0) {
+			const row = queue.shift();
+			if (!row || visited.has(row)) continue;
+			visited.add(row);
+			family.push(row);
+			for (const alias of [row.commentId, row.importedId].map(normalizeCommentId).filter(Boolean)) queue.push(...childrenByParentAlias.get(alias) ?? []);
+		}
+		const isResolved = status === "resolved";
+		const resolvedAt = Date.now();
+		for (const row of family) {
+			row.resolvedTime = isResolved ? row.resolvedTime ?? resolvedAt : null;
+			row.resolvedById = isResolved ? superdoc?.user?.id ?? null : null;
+			row.resolvedByEmail = isResolved ? superdoc?.user?.email ?? null : null;
+			row.resolvedByName = isResolved ? superdoc?.user?.name ?? null : null;
+		}
+		return {
+			added: null,
+			lifecycleUpdated: family.length
+		};
+	};
 	const runV2CommentMutation = async ({ superdoc, adapter, fileId, operation, eventType, rejectionFallbackReason, rejectionEventExtras = {}, validateOutcome, successEventBuilder }) => {
 		let outcome;
 		try {
@@ -8609,11 +8665,17 @@ var useCommentsStore = defineStore("comments", () => {
 			superdoc?.emit?.("comments-update", rejectedEvent);
 			return failedOutcome;
 		}
-		const reconciled = reconcileCommentsFromV2({
+		const documentId = adapter.documentId ?? fileId;
+		const reconciled = applyV2ThreadLifecycleReceipt({
+			superdoc,
+			documentId,
+			lifecycle: outcome.threadLifecycle
+		}) ?? reconcileCommentsFromV2({
 			superdoc,
 			adapter,
-			documentId: adapter.documentId ?? fileId,
-			items: outcome.items ?? []
+			documentId,
+			items: outcome.items ?? [],
+			pruneStale: outcome.complete !== false
 		});
 		const successEvent = successEventBuilder?.({
 			outcome,
@@ -8623,7 +8685,11 @@ var useCommentsStore = defineStore("comments", () => {
 		return {
 			ok: true,
 			items: outcome.items ?? [],
-			reconciled
+			reconciled,
+			...outcome.complete === false ? { complete: false } : {},
+			...outcome.visibleWindowSource != null ? { visibleWindowSource: outcome.visibleWindowSource } : {},
+			...outcome.threadLifecycle != null ? { threadLifecycle: outcome.threadLifecycle } : {},
+			...outcome.mutationPath != null ? { mutationPath: outcome.mutationPath } : {}
 		};
 	};
 	const mapV2OutcomeCommentInputs = ({ outcome, adapter, fileId }) => {
@@ -8639,6 +8705,23 @@ var useCommentsStore = defineStore("comments", () => {
 	const commentInputParentId = (input) => input?.parentCommentId != null ? String(input.parentCommentId) : null;
 	const validateV2ThreadLifecycleRefresh = ({ outcome, adapter, fileId, commentId, expectedResolved, operation }) => {
 		const id = commentId != null ? String(commentId) : null;
+		const receiptLifecycle = outcome?.threadLifecycle;
+		if (receiptLifecycle != null) {
+			const observedId = normalizeCommentId(receiptLifecycle.commentId);
+			const observedResolved = receiptLifecycle.status === "resolved";
+			if (observedId === id && observedResolved === expectedResolved) return { ok: true };
+			return {
+				ok: false,
+				reason: `v2-${operation}-receipt-lifecycle-mismatch`,
+				detail: {
+					expected: {
+						commentId: id,
+						status: expectedResolved ? "resolved" : "open"
+					},
+					observed: receiptLifecycle
+				}
+			};
+		}
 		const inputs = mapV2OutcomeCommentInputs({
 			outcome,
 			adapter,
@@ -8784,8 +8867,8 @@ var useCommentsStore = defineStore("comments", () => {
 	* Resolve an existing comment through the v2 adapter.
 	*
 	* Plan §4.3 rules:
-	*   - successful resolve refreshes from v2 list and clears the active
-	*     comment / dialog target if the resolved comment was active
+	*   - successful resolve applies the committed lifecycle receipt to the
+	*     hydrated thread and clears the active comment / dialog target
 	*   - rejection leaves the row active, emits a rejected event
 	*   - active state must never reference a deleted/missing anchor — the
 	*     reconciler is already family-scoped (see TCS 001 §5)
@@ -8843,18 +8926,19 @@ var useCommentsStore = defineStore("comments", () => {
 	*
 	* Symmetric inverse of {@link resolveCommentV2}. The adapter routes the
 	* reopen through `activeEditor.doc.comments.patch({ status: 'active' })`,
-	* which removes the resolved anchors and restores the live comment mark,
-	* then refreshes from the v2 comment list. Rules:
+	* which removes the resolved anchors and restores the live comment mark.
+	* The successful receipt updates the hydrated thread immediately while
+	* normal review hydration remains the eventual reconciliation path. Rules:
 	*   - the store owns mutation gating (via the adapter capability state),
-	*     adapter identity stamping, refresh reconciliation, and event emission
+	*     adapter identity stamping, local lifecycle projection, and event emission
 	*   - there is no dedicated REOPENED event in the comment event enum, so a
-	*     successful reopen emits an UPDATE event with the refreshed (now open)
+	*     successful reopen emits an UPDATE event with the now-open
 	*     comment payload
 	*   - rejection is non-mutating and emits the same rejected-event shape as
 	*     the other v2 comment mutations; the row stays resolved so the user can
 	*     retry
-	*   - body / replies / anchor identity are preserved by the reconciler; we
-	*     only confirm the open state after the refreshed list lands
+	*   - body / replies / anchor identity are preserved; only lifecycle metadata
+	*     changes on the hydrated thread
 	*/
 	const reopenCommentV2 = async ({ superdoc, commentId } = {}) => {
 		if (commentsAreReadOnly()) return readOnlyMutationOutcome();
@@ -9019,7 +9103,7 @@ var useCommentsStore = defineStore("comments", () => {
 			trackedItems: preparedParams.length
 		};
 	});
-	const hydrateCommentsFromV2 = async ({ superdoc, adapter, documentId, trackedChangesListMode = "all", isCurrent, signal, hydrationGeneration } = {}) => withInteractionSpan("store.comments.hydrateFromV2", "comments-list", { documentId: documentId ?? null }, async () => {
+	const hydrateCommentsFromV2 = async ({ superdoc, adapter, documentId, trackedChangesListMode = "all", commentIds, isCurrent, signal, hydrationGeneration } = {}) => withInteractionSpan("store.comments.hydrateFromV2", "comments-list", { documentId: documentId ?? null }, async () => {
 		const effectiveAdapter = adapter ?? getV2CommentsAdapter(superdoc);
 		const visibleWindow = trackedChangesListMode === "visible-window";
 		const read = visibleWindow ? effectiveAdapter?.selectVisibleReviewComments : effectiveAdapter?.refresh;
@@ -9041,6 +9125,7 @@ var useCommentsStore = defineStore("comments", () => {
 		let result;
 		try {
 			const refreshOptions = {};
+			if (visibleWindow && Array.isArray(commentIds)) refreshOptions.targetIds = commentIds;
 			if (signal) refreshOptions.signal = signal;
 			if (typeof hydrationGeneration === "number") refreshOptions.hydrationGeneration = hydrationGeneration;
 			result = Object.keys(refreshOptions).length > 0 ? await read.call(effectiveAdapter, refreshOptions) : await read.call(effectiveAdapter);
@@ -9071,7 +9156,7 @@ var useCommentsStore = defineStore("comments", () => {
 			adapter: effectiveAdapter,
 			documentId,
 			items: result.items ?? [],
-			pruneStale: !visibleWindow,
+			pruneStale: !visibleWindow || Array.isArray(commentIds) && (!Array.isArray(result.unresolvedIds) || result.unresolvedIds.length === 0),
 			hydrationGeneration
 		});
 		return {
@@ -9304,6 +9389,27 @@ var useCommentsStore = defineStore("comments", () => {
 			storySnapshots
 		};
 	};
+	const reconcileAuthoritativeV2TrackedChangeSidebar = ({ superdoc, editor, documentId, refreshReason = "tracked-change-sidebar-authoritative" } = {}) => {
+		const adapter = getV2TrackedChangesAdapter(superdoc) ?? editor?.v2TrackedChanges ?? null;
+		if (!adapter || typeof adapter.listTrackedChanges !== "function" || typeof adapter.mapV2TrackedChangeToCommentParams !== "function") return false;
+		const effectiveDocumentId = documentId ?? adapter.documentId ?? editor?.documentId ?? editor?.options?.documentId ?? superdoc?.activeEditor?.documentId ?? superdoc?.activeEditor?.options?.documentId ?? null;
+		if (effectiveDocumentId == null) return false;
+		const normalizedDocumentId = String(effectiveDocumentId);
+		hydrateTrackedChangesFromV2({
+			superdoc,
+			adapter,
+			documentId: normalizedDocumentId,
+			trackedChangesListMode: "background-reconcile",
+			refreshReason,
+			blocking: false,
+			isCurrent: () => {
+				const activeEditor = superdoc?.activeEditor ?? null;
+				const activeDocumentId = activeEditor?.documentId ?? activeEditor?.options?.documentId ?? null;
+				return activeDocumentId == null || String(activeDocumentId) === normalizedDocumentId;
+			}
+		});
+		return true;
+	};
 	/**
 	* Bootstrap tracked-change comment threads after a DOCX import finishes.
 	*
@@ -9341,6 +9447,12 @@ var useCommentsStore = defineStore("comments", () => {
 			editor,
 			structuralChanges: captured.structuralChanges
 		});
+		reconcileAuthoritativeV2TrackedChangeSidebar({
+			superdoc,
+			editor,
+			documentId: editor?.options?.documentId,
+			refreshReason: "import-bootstrap-authoritative"
+		});
 		return true;
 	};
 	const isCurrentImportedTrackedChangeBootstrap = (task) => {
@@ -10326,7 +10438,8 @@ var useCommentsStore = defineStore("comments", () => {
 			lateResultDropped: true
 		};
 		if (!result?.ok) return result;
-		const pruneStale = !(trackedChangesListMode === "startup-page" || trackedChangesListMode === "interaction-prime" || trackedChangesListMode === "visible-window") && result.visibleWindowSource == null && result.complete === true && result.sourceCoverageComplete === true;
+		const partialListMode = trackedChangesListMode === "startup-page" || trackedChangesListMode === "interaction-prime" || trackedChangesListMode === "visible-window";
+		const pruneStale = trackedChangesListMode === "visible-window" && Array.isArray(targetIds) && (!Array.isArray(result.visibleTrackedChangeFailedIds) || result.visibleTrackedChangeFailedIds.length === 0) || !partialListMode && result.visibleWindowSource == null && result.complete === true && result.sourceCoverageComplete === true;
 		if (signal?.aborted || trackedChangeSyncGeneration(effectiveAdapter) !== syncGeneration) return {
 			ok: false,
 			reason: "review-hydration-superseded",
@@ -10730,6 +10843,12 @@ var useCommentsStore = defineStore("comments", () => {
 			broadcastChanges,
 			structuralChanges: captured.structuralChanges
 		});
+		reconcileAuthoritativeV2TrackedChangeSidebar({
+			superdoc,
+			editor,
+			documentId: activeDocumentId,
+			refreshReason: "sync-authoritative"
+		});
 	};
 	/**
 	* Surface decidable whole-table structural tracked changes (table insert /
@@ -11200,6 +11319,16 @@ var useCommentsStore = defineStore("comments", () => {
 	const syncActiveFloatingInstanceWithComment = (commentId) => {
 		if (!doesFloatingInstanceBelongToComment(activeFloatingCommentInstanceId.value, commentId)) setActiveFloatingCommentInstance(null);
 	};
+	function canonicalizeActiveCommentAlias() {
+		const activeId = normalizeCommentId(activeComment.value);
+		if (!activeId) return false;
+		const comment = getComment(activeId);
+		const canonicalId = normalizeCommentId(comment?.commentId);
+		if (!canonicalId || canonicalId === activeId) return false;
+		activeComment.value = canonicalId;
+		syncActiveFloatingInstanceWithComment(canonicalId);
+		return true;
+	}
 	const setViewingVisibility = ({ documentMode, commentsVisible, trackChangesVisible } = {}) => {
 		if (typeof documentMode === "string") viewingVisibility.documentMode = documentMode;
 		if (typeof commentsVisible === "boolean") viewingVisibility.commentsVisible = commentsVisible;
@@ -13896,6 +14025,12 @@ var FloatingComments_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 	setup(__props) {
 		const ESTIMATED_HEIGHT = 110;
 		const OBSERVER_MARGIN = 600;
+		const SCROLL_OWNER_OVERFLOW_VALUES = /* @__PURE__ */ new Set([
+			"auto",
+			"scroll",
+			"hidden",
+			"clip"
+		]);
 		const resolveCollisions = (positions, activeIndex, gap) => {
 			if (activeIndex >= 0) {
 				positions[activeIndex].top = positions[activeIndex].anchorTop;
@@ -14300,6 +14435,8 @@ var FloatingComments_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 		let activeLayoutContinuityFrame = null;
 		let directDecisionContinuity = null;
 		let directDecisionSourceId = null;
+		let ownerScrollContinuityResetFrame = null;
+		const ownerScrollTargets = /* @__PURE__ */ new Set();
 		const releaseDirectDecisionContinuity = () => {
 			directDecisionContinuity = null;
 			directDecisionSourceId = null;
@@ -14363,6 +14500,36 @@ var FloatingComments_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			}
 			setInstantLayoutTransitionsDisabled(false);
 		};
+		const releaseDecisionContinuityForOwnerScroll = () => {
+			if (!directDecisionContinuity && !sidebarContinuityAnchor) return;
+			releaseDirectDecisionContinuity();
+			clearSidebarContinuityAnchor();
+			setInstantLayoutTransitionsDisabled(true);
+			sidebarOffsetY.value = 0;
+			if (ownerScrollContinuityResetFrame != null) cancelAnimationFrame(ownerScrollContinuityResetFrame);
+			ownerScrollContinuityResetFrame = requestAnimationFrame(() => {
+				ownerScrollContinuityResetFrame = null;
+				if (!directDecisionContinuity && !sidebarContinuityAnchor) setInstantLayoutTransitionsDisabled(false);
+			});
+		};
+		const handleOwnerScroll = () => {
+			releaseDecisionContinuityForOwnerScroll();
+			refreshViewportWindow();
+		};
+		const registerOwnerScrollListeners = () => {
+			const addTarget = (target) => {
+				if (!target?.addEventListener || ownerScrollTargets.has(target)) return;
+				target.addEventListener("scroll", handleOwnerScroll, { passive: true });
+				ownerScrollTargets.add(target);
+			};
+			addTarget(props.parent);
+			for (let ancestor = floatingCommentsContainer.value?.parentElement; ancestor; ancestor = ancestor.parentElement) if (SCROLL_OWNER_OVERFLOW_VALUES.has(window.getComputedStyle(ancestor).overflowY)) addTarget(ancestor);
+			addTarget(window);
+		};
+		const unregisterOwnerScrollListeners = () => {
+			for (const target of ownerScrollTargets) target.removeEventListener?.("scroll", handleOwnerScroll);
+			ownerScrollTargets.clear();
+		};
 		const scheduleSidebarContinuityAlignment = () => {
 			if (!sidebarContinuityAnchor || continuityAlignmentScheduled) return;
 			continuityAlignmentScheduled = true;
@@ -14615,7 +14782,7 @@ var FloatingComments_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 		});
 		onMounted(() => {
 			setupObserver();
-			props.parent?.addEventListener?.("scroll", refreshViewportWindow, { passive: true });
+			registerOwnerScrollListeners();
 			window.addEventListener("resize", refreshViewportWindow, { passive: true });
 			document.addEventListener("pointerdown", releaseDirectDecisionContinuityForUnrelatedPointer, true);
 			nextTick(observePlaceholders);
@@ -14629,7 +14796,11 @@ var FloatingComments_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				cancelAnimationFrame(activeLayoutContinuityFrame);
 				activeLayoutContinuityFrame = null;
 			}
-			props.parent?.removeEventListener?.("scroll", refreshViewportWindow);
+			if (ownerScrollContinuityResetFrame != null) {
+				cancelAnimationFrame(ownerScrollContinuityResetFrame);
+				ownerScrollContinuityResetFrame = null;
+			}
+			unregisterOwnerScrollListeners();
 			window.removeEventListener("resize", refreshViewportWindow);
 			document.removeEventListener("pointerdown", releaseDirectDecisionContinuityForUnrelatedPointer, true);
 			if (viewportFrame != null) {
@@ -14697,7 +14868,7 @@ var FloatingComments_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			}), 128))], 4)], 36);
 		};
 	}
-}, [["__scopeId", "data-v-a0a841ce"]]);
+}, [["__scopeId", "data-v-d8d03209"]]);
 //#endregion
 //#region src/components/CommentsLayer/PdfCommentsLayer.vue
 var _hoisted_1$22 = {
@@ -15373,6 +15544,19 @@ var VALID_COMMENTS_DISPLAY_MODES = /* @__PURE__ */ new Set([
 	"inline"
 ]);
 /**
+* Whether a context-menu event landed inside the tracked-change carrier that
+* is already visually active. The review visual owner maintains this marker,
+* so the right-click path can stay synchronous and avoid a catalog lookup or
+* document-wide DOM query.
+*
+* @param {EventTarget | null} target
+* @returns {boolean}
+*/
+function isActiveTrackedChangeContextMenuTarget(target) {
+	const element = target;
+	return typeof element?.closest === "function" && element.closest(".track-change-focused") != null;
+}
+/**
 * Normalize adaptive comments UI policy fields.
 *
 * @param {false | Record<string, unknown> | undefined} commentsConfig
@@ -15808,74 +15992,6 @@ function resolveV2ReviewTargetCommentId(target, getComment) {
 	return commentId != null ? String(commentId) : null;
 }
 //#endregion
-//#region src/helpers/v2-remote-review-hydration.js
-function normalizeDocumentId(value) {
-	return value == null ? null : String(value);
-}
-function createV2RemoteReviewHydrationScheduler({ hydrate, getActiveDocumentId, debounceMs = 250, ceilingMs = 1e3, now = () => Date.now(), setTimer = (callback, delay) => setTimeout(callback, delay), clearTimer = (timer) => clearTimeout(timer) }) {
-	let timer = null;
-	let heldSinceMs = null;
-	let pendingDocumentId = null;
-	const matchesActiveDocument = (documentId) => {
-		return normalizeDocumentId(getActiveDocumentId()) === documentId;
-	};
-	const clear = () => {
-		if (timer != null) clearTimer(timer);
-		timer = null;
-		heldSinceMs = null;
-		pendingDocumentId = null;
-	};
-	const schedule = (documentId) => {
-		const normalizedDocumentId = normalizeDocumentId(documentId);
-		if (!matchesActiveDocument(normalizedDocumentId)) return false;
-		if (pendingDocumentId !== normalizedDocumentId) clear();
-		const scheduledAtMs = now();
-		pendingDocumentId = normalizedDocumentId;
-		heldSinceMs ??= scheduledAtMs;
-		if (timer != null) clearTimer(timer);
-		const ceilingRemainingMs = Math.max(0, ceilingMs - (scheduledAtMs - heldSinceMs));
-		timer = setTimer(() => {
-			const deliveredDocumentId = pendingDocumentId;
-			timer = null;
-			heldSinceMs = null;
-			pendingDocumentId = null;
-			if (matchesActiveDocument(deliveredDocumentId)) hydrate();
-		}, Math.min(debounceMs, ceilingRemainingMs));
-		return true;
-	};
-	return {
-		schedule,
-		clear
-	};
-}
-//#endregion
-//#region src/helpers/v2-typing-review-hydration.js
-/**
-* Coalesce automatic review-catalog reconciliation behind a genuine typing
-* quiet period. Every typing signal restarts the trailing timer; there is no
-* maximum-wait escape hatch because that would deliberately run the expensive
-* catalog reads in the middle of a sustained input burst.
-*/
-function createV2TypingReviewHydrationScheduler({ hydrate, idleMs = 6500, setTimer = (callback, delay) => setTimeout(callback, delay), clearTimer = (timer) => clearTimeout(timer) }) {
-	let timer = null;
-	const clear = () => {
-		if (timer != null) clearTimer(timer);
-		timer = null;
-	};
-	const schedule = () => {
-		clear();
-		timer = setTimer(() => {
-			timer = null;
-			hydrate();
-		}, idleMs);
-	};
-	return {
-		schedule,
-		clear,
-		isPending: () => timer != null
-	};
-}
-//#endregion
 //#region src/helpers/v2-author-required-rejection.js
 var NO_AUTHOR_SIGNAL = "no-author-configured";
 /** Stable, non-terminal exception code surfaced to consumers. */
@@ -20312,9 +20428,9 @@ var _hoisted_1$16 = {
 var _hoisted_2$13 = ["innerHTML"];
 var _hoisted_3$10 = { class: "superdoc__document document" };
 var _hoisted_4$7 = { class: "floating-comments" };
+var TRACKED_CHANGE_CARRIERS_RESTAMPED_EVENT = "superdoc:v2-tracked-change-carriers-restamped";
 var UNAVAILABLE_COMMAND_RESULT = false;
 var V2_SELECTION_TOOLBAR_SYNC_RETRY_FRAMES = 3;
-var V2_TYPING_REVIEW_HYDRATION_IDLE_MS = 6500;
 var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 	__name: "SuperDoc",
 	emits: ["selection-update"],
@@ -20477,6 +20593,27 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				editor: proxy.$superdoc?.activeEditor
 			});
 		};
+		const reconcileAuthoritativeV2TrackedChangeSidebar = ({ adapter, documentId, refreshReason = "startup-authoritative" } = {}) => {
+			if (!adapter || typeof adapter.listTrackedChanges !== "function") return false;
+			const normalizedDocumentId = documentId == null ? null : String(documentId);
+			if (!normalizedDocumentId) return false;
+			commentsStore.hydrateTrackedChangesFromV2?.({
+				superdoc: proxy.$superdoc,
+				adapter,
+				documentId: normalizedDocumentId,
+				trackedChangesListMode: "background-reconcile",
+				refreshReason,
+				blocking: false,
+				isCurrent: () => {
+					const activeEditor = proxy.$superdoc?.activeEditor ?? null;
+					const activeDocumentId = activeEditor?.documentId ?? activeEditor?.options?.documentId ?? null;
+					if (activeDocumentId != null && String(activeDocumentId) !== normalizedDocumentId) return false;
+					const activeAdapter = activeEditor?.v2TrackedChanges ?? commentsStore.getV2TrackedChangesAdapter?.(proxy.$superdoc);
+					return !activeAdapter || activeAdapter === adapter;
+				}
+			});
+			return true;
+		};
 		const scheduleReplayTrackedChangeSync = () => {
 			pendingReplayTrackedChangeSync.value = true;
 			nextTick(() => {
@@ -21020,7 +21157,11 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				pageFurniture: pageFurniture ?? null,
 				presence: presence ?? null,
 				lock: lock ?? null,
-				reviewHydration: { getDiagnostics: () => v2ReviewHydrationController.getDiagnostics() },
+				reviewHydration: {
+					getDiagnostics: () => v2ReviewHydrationController.getDiagnostics(),
+					getSnapshot: () => v2ReviewHydrationController.getSnapshot?.() ?? null,
+					subscribe: (listener) => v2ReviewHydrationController.subscribe?.(listener) ?? (() => void 0)
+				},
 				extensions: createV2ExtensionsFacet(host),
 				fonts: fonts ?? host?.getFontRuntime?.() ?? null,
 				/**
@@ -21076,6 +21217,11 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 					console.warn("[SuperDoc][v2] initial render-readiness snapshot failed", err);
 				}
 			}
+			if (commentsModuleEnabled && trackedChangesAdapter) reconcileAuthoritativeV2TrackedChangeSidebar({
+				adapter: trackedChangesAdapter,
+				documentId,
+				refreshReason: "startup-authoritative"
+			});
 			if (areDocumentsReady.value && !proxy.$superdoc.config.collaboration) isReady.value = true;
 			isFloatingCommentsReady.value = true;
 			hasInitializedLocations.value = true;
@@ -21344,7 +21490,6 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				}
 			},
 			onCommittedPagePaint: (commit) => {
-				if (commit?.routeLane === "canonical.typing-mutation" || v2TypingReviewHydrationScheduler.isPending()) return;
 				v2ReviewHydrationController.onCommittedPagePaint?.({
 					...commit,
 					documentId: commit?.payload?.documentId ?? null
@@ -21389,7 +21534,6 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 		const onV2RenderReadiness = (payload) => {
 			const snapshot = payload?.snapshot ?? payload ?? null;
 			if (!snapshot) return;
-			if (v2TypingReviewHydrationScheduler.isPending()) return;
 			v2ReviewHydrationController.onRenderReadiness(snapshot);
 		};
 		const v2PageMetricsSnapshot = shallowRef(null);
@@ -21439,8 +21583,6 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			if (latestV2MountStage && (clearedDocumentId == null || latestV2MountStage.dataset?.superdocV2DocumentId === clearedDocumentId)) latestV2MountStage = null;
 			v2ReviewHydrationController.reset("render-cleared");
 			v2ReviewMutationReconciler.reset();
-			clearV2TypingReviewHydrationTimer();
-			v2RemoteReviewHydrationScheduler.clear();
 			commentsStore.setV2CommentsAdapter?.(null);
 			commentsStore.setV2TrackedChangesAdapter?.(null);
 			commentsStore.clearEditorCommentPositions?.();
@@ -21449,26 +21591,6 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			v2RulerHostStyle.value = {};
 			v2RulerReady.value = false;
 		};
-		const hydrateV2CommentRowsFromHost = () => {
-			const commentsAdapter = proxy.$superdoc?.activeEditor?.v2Comments ?? null;
-			if (!commentsAdapter) return;
-			commentsStore.hydrateCommentsFromV2?.({
-				superdoc: proxy.$superdoc,
-				adapter: commentsAdapter,
-				documentId: proxy.$superdoc?.activeEditor?.documentId ?? null
-			});
-		};
-		const hydrateV2ReviewRowsFromHost = (options = {}) => {
-			hydrateV2CommentRowsFromHost();
-			const trackedChangesAdapter = proxy.$superdoc?.activeEditor?.v2TrackedChanges ?? null;
-			if (!trackedChangesAdapter) return;
-			commentsStore.hydrateTrackedChangesFromV2?.({
-				superdoc: proxy.$superdoc,
-				adapter: trackedChangesAdapter,
-				documentId: proxy.$superdoc?.activeEditor?.documentId ?? null,
-				...options
-			});
-		};
 		const v2ReviewMutationReconciler = createV2ReviewMutationReconciler({
 			getContext: () => {
 				const activeEditor = proxy.$superdoc?.activeEditor ?? null;
@@ -21498,31 +21620,10 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				reason: "review-reconcile"
 			})
 		});
-		const v2TypingReviewHydrationScheduler = createV2TypingReviewHydrationScheduler({
-			idleMs: V2_TYPING_REVIEW_HYDRATION_IDLE_MS,
-			hydrate: () => v2ReviewHydrationController.reconcileInBackground?.("typing-idle")
-		});
-		const clearV2TypingReviewHydrationTimer = () => {
-			v2TypingReviewHydrationScheduler.clear();
-		};
-		const scheduleV2TypingReviewHydration = () => {
-			v2TypingReviewHydrationScheduler.schedule();
-		};
-		const v2RemoteReviewHydrationScheduler = createV2RemoteReviewHydrationScheduler({
-			hydrate: () => {
-				if (v2TypingReviewHydrationScheduler.isPending()) return false;
-				return v2ReviewHydrationController.reconcileInBackground?.("remote-review-change");
-			},
-			getActiveDocumentId: () => {
-				const activeEditor = proxy.$superdoc?.activeEditor ?? null;
-				return activeEditor?.documentId ?? activeEditor?.options?.documentId ?? null;
-			}
-		});
 		const onV2HostEvent = (document, event) => {
 			if (!event) return;
 			const documentId = document?.id ?? null;
 			if (event.type === "review-mutation:started") {
-				clearV2TypingReviewHydrationTimer();
 				const activeEditor = proxy.$superdoc?.activeEditor ?? null;
 				commentsStore.supersedeV2ReviewHydration?.({
 					commentsAdapter: activeEditor?.v2Comments ?? null,
@@ -21544,8 +21645,7 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				return;
 			}
 			if (event.type === "collaboration:remote-changed") {
-				v2ReviewHydrationController.invalidate("collaboration:remote-changed");
-				v2RemoteReviewHydrationScheduler.schedule(documentId);
+				if (event.reviewChanged !== false) v2ReviewHydrationController.invalidate("collaboration:remote-review-changed");
 				return;
 			}
 			if (event.type === "source:complete") {
@@ -21570,11 +21670,12 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				emitV2EditorUpdate();
 			}
 			if (event.type !== "mutation:committed") return;
-			v2ReviewHydrationController.invalidate("mutation-committed");
+			if (event.reviewSidecarOnly === true) v2ReviewHydrationController.hydrateNow("review-sidecar-committed");
 			const reviewImpact = getV2TrackedChangeMutationImpact(event);
 			if (Array.isArray(reviewImpact?.remappedPairs) && reviewImpact.remappedPairs.length > 0) commentsStore.remapTrackedChangeIdentities?.(reviewImpact.remappedPairs, { documentId });
 			if (reviewImpact) armV2TrackedChangeRestampGeometryRetention("tracked-change-mutation");
-			const readiness = (proxy.$superdoc?.activeEditor ?? null)?.documentMutationReadiness ?? null;
+			const activeEditor = proxy.$superdoc?.activeEditor ?? null;
+			const readiness = activeEditor?.documentMutationReadiness ?? null;
 			const receipt = event.origin === "history" ? null : event.receipt;
 			const canWaitForExactPaint = reviewImpact && typeof receipt?.txId === "string" && receipt.txId.length > 0 && typeof readiness?.whenPainted === "function";
 			const reconciliation = v2ReviewMutationReconciler.enqueueAfterPaint(reviewImpact, canWaitForExactPaint ? () => readiness.whenPainted.call(readiness, receipt) : null);
@@ -21589,43 +21690,37 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 						resumeDomains: reconciledAllResolved ? ["comments"] : ["comments", "trackedChanges"],
 						trackedRowCount: commentsStore.getV2TrackedChangeRowCount?.(documentId) ?? null
 					});
+					if (!reconciledAllResolved) reconcileAuthoritativeV2TrackedChangeSidebar({
+						adapter: activeEditor?.v2TrackedChanges ?? null,
+						documentId,
+						refreshReason: "mutation-authoritative"
+					});
 				};
 				Promise.resolve(reconciliation).then(settleReviewMutation, () => settleReviewMutation(false));
 				return;
 			}
-			const isTypingMutation = isV2EditableTextMutationEvent(event);
-			if (!isTypingMutation) clearV2TypingReviewHydrationTimer();
-			if (reviewImpact?.reconcileMode === "authoritative" && reviewImpact.upsertIds.size > 0) {
-				hydrateV2CommentRowsFromHost();
-				return;
-			}
-			if (isTypingMutation) {
-				scheduleV2TypingReviewHydration();
-				return;
-			}
+			if (reviewImpact?.reconcileMode === "authoritative" && reviewImpact.upsertIds.size > 0) return;
 			if (reviewImpact?.removedIds.size > 0 && reviewImpact.upsertIds.size === 0) return;
-			hydrateV2ReviewRowsFromHost();
 		};
 		const onV2LinkClick = (payload) => {
 			linkPopover.handleLinkClick(payload);
 		};
-		const recollectV2GeometryIfActive = () => {
+		const recollectV2GeometryIfActive = (options = void 0) => {
 			if (!isV2Mode.value) return;
 			if (!v2GeometryPublisher.getLastPayload()) return;
 			if (v2GeometryRafHandle && typeof cancelAnimationFrame === "function") cancelAnimationFrame(v2GeometryRafHandle);
 			if (typeof requestAnimationFrame !== "function") {
-				v2GeometryPublisher.recollect();
+				v2GeometryPublisher.recollect(resolveV2GeometryPublishOptions(options));
 				return;
 			}
 			v2GeometryRafHandle = requestAnimationFrame(() => {
 				v2GeometryRafHandle = 0;
-				v2GeometryPublisher.recollect();
+				v2GeometryPublisher.recollect(resolveV2GeometryPublishOptions(options));
 			});
 		};
 		const handleV2DocumentModeChange = () => {
 			if (!isV2Mode.value) return;
 			try {
-				clearV2TypingReviewHydrationTimer();
 				v2ReviewHydrationController.hydrateNow("document-mode-change");
 			} catch (err) {
 				console.warn("[SuperDoc][v2] document-mode-change rehydrate failed", err);
@@ -21644,22 +21739,6 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				else republishGeometry();
 			});
 		};
-		let v2BuiltInReviewSurfaceOpen = false;
-		let v2ExternalReviewSurfaceOpen = false;
-		const syncV2ReviewCatalogDemand = () => {
-			if (!isV2Mode.value) return;
-			if (!v2BuiltInReviewSurfaceOpen && !v2ExternalReviewSurfaceOpen) {
-				v2ReviewHydrationController.releaseCatalogDemand();
-				return;
-			}
-			clearV2TypingReviewHydrationTimer();
-			v2ReviewHydrationController.demandCatalog("review-sidebar-visible");
-		};
-		const handleV2CommentsListChange = ({ isRendered } = {}) => {
-			v2ExternalReviewSurfaceOpen = isRendered === true;
-			syncV2ReviewCatalogDemand();
-		};
-		proxy.$superdoc?.on?.("comments-list-change", handleV2CommentsListChange);
 		const getV2EditorFailureMessage = (reason) => {
 			switch (reason) {
 				case "editing-mount-required": return "SuperDoc could not load the document editor because the page did not provide a mount container.";
@@ -21734,7 +21813,7 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			if (!root) return;
 			if (!(event.target instanceof Node) || !root.contains(event.target)) return;
 			if (layers.value?.contains(event.target)) {
-				commentsStore.setActiveComment(proxy.$superdoc, null);
+				if (!isActiveTrackedChangeContextMenuTarget(event.target)) commentsStore.setActiveComment(proxy.$superdoc, null);
 				commentsStore.removePendingComment(proxy.$superdoc);
 				resetClickAnchor();
 			}
@@ -21787,16 +21866,17 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				onFontsResolved: onFontsResolvedFn,
 				onPageCountKnown: proxy.$superdoc.config.onPageCountKnown ?? null,
 				onReviewWindowPlanned: (payload) => {
-					if (payload?.routeLane === "canonical.typing-mutation") {
-						v2TypingReviewHydrationScheduler.schedule();
-						return;
-					}
-					if (v2TypingReviewHydrationScheduler.isPending()) return;
 					v2ReviewHydrationController.onReviewWindowPlanned?.({
 						...payload,
 						documentId: doc.id
 					});
 				},
+				onReviewWindowCommitted: (payload) => {
+					v2ReviewHydrationController.onCommittedPagePaint?.({
+						...payload,
+						documentId: doc.id
+					});
+				},
 				fontAssets: proxy.$superdoc.config.fonts,
 				proofing: resolvedProofingConfig.value,
 				isNewFile,
@@ -22124,8 +22204,6 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 		});
 		watch(showCommentsSidebar, (value) => {
 			proxy.$superdoc.broadcastSidebarToggle(value);
-			v2BuiltInReviewSurfaceOpen = value === true;
-			syncV2ReviewCatalogDemand();
 		});
 		useViewportFit({
 			getSuperdoc: () => proxy.$superdoc,
@@ -22150,6 +22228,16 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 		const handleViewportScrollOrResize = () => {
 			recollectV2GeometryIfActive();
 		};
+		const handleV2TrackedChangeCarriersRestamped = (event) => {
+			if (!isV2Mode.value) return;
+			const itemIds = Array.isArray(event?.detail?.itemIds) ? event.detail.itemIds.map((id) => id == null ? "" : String(id)).filter(Boolean) : [];
+			armV2TrackedChangeRestampGeometryRetention(event?.detail?.refreshReason ?? "tracked-change-restamp");
+			recollectV2GeometryIfActive({
+				retainMissingTrackedChangeGeometry: true,
+				...itemIds.length > 0 ? { retainedTrackedChangeIds: itemIds } : {},
+				reason: "tracked-change-restamp"
+			});
+		};
 		onMounted(() => {
 			document.addEventListener("contextmenu", handleDocumentContextMenu, true);
 			document.addEventListener("keydown", handleDocumentShortcut, true);
@@ -22157,6 +22245,7 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			claimFindShortcut(findShortcutOwner);
 			superdocRoot.value?.addEventListener("pointerdown", handleFindOwnershipInteraction, true);
 			superdocRoot.value?.addEventListener("focusin", handleFindOwnershipInteraction, true);
+			superdocRoot.value?.addEventListener(TRACKED_CHANGE_CARRIERS_RESTAMPED_EVENT, handleV2TrackedChangeCarriersRestamped);
 			if (typeof window !== "undefined") {
 				window.addEventListener("scroll", handleViewportScrollOrResize, true);
 				window.addEventListener("resize", handleViewportScrollOrResize, true);
@@ -22273,6 +22362,7 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			proxy.$superdoc?.off?.("search:open", handleOpenFindRequest);
 			superdocRoot.value?.removeEventListener("pointerdown", handleFindOwnershipInteraction, true);
 			superdocRoot.value?.removeEventListener("focusin", handleFindOwnershipInteraction, true);
+			superdocRoot.value?.removeEventListener(TRACKED_CHANGE_CARRIERS_RESTAMPED_EVENT, handleV2TrackedChangeCarriersRestamped);
 			releaseFindShortcut(findShortcutOwner);
 			if (typeof window !== "undefined") {
 				window.removeEventListener("scroll", handleViewportScrollOrResize, true);
@@ -22282,8 +22372,6 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				cancelAnimationFrame(v2GeometryRafHandle);
 				v2GeometryRafHandle = 0;
 			}
-			clearV2TypingReviewHydrationTimer();
-			v2RemoteReviewHydrationScheduler.clear();
 			document.removeEventListener("focusin", handleRuntimeFocusIn, true);
 			document.removeEventListener("pointerdown", handleRuntimePointerDown, true);
 			document.removeEventListener("mousedown", handleRuntimeMouseDown, true);
@@ -22291,7 +22379,6 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			document.removeEventListener("mouseup", handleDocumentSelectionChange, true);
 			document.removeEventListener("selectionchange", handleDocumentSelectionChange);
 			proxy.$superdoc?.off?.("document-mode-change", handleV2DocumentModeChange);
-			proxy.$superdoc?.off?.("comments-list-change", handleV2CommentsListChange);
 		});
 		const selectionLayer = ref(null);
 		const isDragging = ref(false);
@@ -22787,7 +22874,7 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			], 38);
 		};
 	}
-}, [["__scopeId", "data-v-25570fd2"]]);
+}, [["__scopeId", "data-v-6833a014"]]);
 //#endregion
 //#region src/core/create-app.js
 var PINIA_DEVTOOLS_SETUP_EVENT = "devtools-plugin:setup";
@@ -43264,7 +43351,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 		this.config.colors = shuffleArray(this.config.colors);
 		this.userColorMap = /* @__PURE__ */ new Map();
 		this.colorIndex = 0;
-		this.version = "2.4.0-next.16";
+		this.version = "2.4.0-next.18";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || v4();
 		this.colors = this.config.colors ?? [];