superdoc 2.4.0-next.12 → 2.4.0-next.13

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-D0mNmAHJ.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 { 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";
@@ -9907,16 +9907,38 @@ var useCommentsStore = defineStore("comments", () => {
 			if (!fromId || !toId || fromId === toId) continue;
 			const comment = commentsList.value.find((row) => matchesRemapSource(row, fromId));
 			if (!comment) continue;
+			const previousCommentId = normalizeCommentId(comment.commentId);
+			const previousCanonicalId = normalizeCommentId(comment.trackedChangeCanonicalId);
+			const previousPositionEntry = resolveCommentPositionEntry(comment).entry;
+			const advancesRemapLineage = ![
+				comment.commentId,
+				comment.importedId,
+				comment.trackedChangeCanonicalId
+			].map((id) => normalizeCommentId(id)).includes(fromId) && previousCommentId != null && previousCanonicalId != null && previousCommentId === previousCanonicalId;
 			const commentIdentityUpdates = {};
 			for (const field of ["commentId", "importedId"]) if (rewriteIfMatch(comment, field, fromId, toId)) commentIdentityUpdates[field] = toId;
 			if (rewriteIfMatch(comment, "trackedChangeCanonicalId", fromId, toId)) commentIdentityUpdates.trackedChangeCanonicalId = toId;
-			const fromAnchor = buildBodyTrackedChangeAnchorKey(fromId);
-			const storyKey = parseTrackedChangeAnchorKey(comment.trackedChangeAnchorKey)?.storyKey ?? normalizeTrackedChangeStoryKey(getTrackedChangeStoryKey(comment));
-			const currentStoryFromAnchor = buildTrackedChangeAnchorKeyForStory(storyKey, fromId);
+			if (advancesRemapLineage) {
+				comment.commentId = toId;
+				comment.trackedChangeCanonicalId = toId;
+				commentIdentityUpdates.commentId = toId;
+				commentIdentityUpdates.trackedChangeCanonicalId = toId;
+			}
+			const currentAnchorParts = parseTrackedChangeAnchorKey(comment.trackedChangeAnchorKey);
+			const storyKey = currentAnchorParts?.storyKey ?? normalizeTrackedChangeStoryKey(getTrackedChangeStoryKey(comment));
 			const toAnchor = buildTrackedChangeAnchorKeyForStory(storyKey, toId);
-			if (normalizeCommentId(comment.trackedChangeAnchorKey) === fromAnchor || comment.trackedChangeAnchorKey == null) comment.trackedChangeAnchorKey = toAnchor;
-			else if (normalizeCommentId(comment.trackedChangeAnchorKey) === currentStoryFromAnchor) comment.trackedChangeAnchorKey = toAnchor;
-			if (Array.isArray(comment.trackedChangePositionAliases)) comment.trackedChangePositionAliases = comment.trackedChangePositionAliases.map((alias) => normalizeCommentId(alias) === fromId ? toId : alias);
+			const anchorSourceIds = /* @__PURE__ */ new Set([fromId]);
+			if (advancesRemapLineage) {
+				if (previousCommentId) anchorSourceIds.add(previousCommentId);
+				if (previousCanonicalId) anchorSourceIds.add(previousCanonicalId);
+			}
+			if (comment.trackedChangeAnchorKey == null || anchorSourceIds.has(currentAnchorParts?.rawId)) comment.trackedChangeAnchorKey = toAnchor;
+			comment.trackedChangePositionAliases = normalizeTrackedChangePositionAliases([...Array.isArray(comment.trackedChangePositionAliases) ? comment.trackedChangePositionAliases : [], fromId]);
+			const identitySourceIds = /* @__PURE__ */ new Set([fromId]);
+			if (advancesRemapLineage) {
+				if (previousCommentId) identitySourceIds.add(previousCommentId);
+				if (previousCanonicalId) identitySourceIds.add(previousCanonicalId);
+			}
 			commentsList.value.forEach((row) => {
 				if (row === comment) return;
 				if (!belongsToTrackedChangeSyncDocument(row, normalizedDocumentId)) return;
@@ -9926,20 +9948,23 @@ var useCommentsStore = defineStore("comments", () => {
 					"trackedChangeParentId",
 					"threadingParentCommentId",
 					"parentCommentId"
-				]) if (rewriteIfMatch(row, field, fromId, toId)) rowIdentityUpdates[field] = toId;
+				]) {
+					if (!identitySourceIds.has(normalizeCommentId(row?.[field]))) continue;
+					row[field] = toId;
+					rowIdentityUpdates[field] = toId;
+				}
 				if (Object.keys(rowIdentityUpdates).length && typeof row.updateIdentityValues === "function") row.updateIdentityValues(rowIdentityUpdates);
 			});
 			if (Object.keys(commentIdentityUpdates).length && typeof comment.updateIdentityValues === "function") comment.updateIdentityValues(commentIdentityUpdates);
-			const fallbackPositionEntries = [positions[fromId], positions[fromAnchor]];
-			const previousEntry = positions[currentStoryFromAnchor] ?? fallbackPositionEntries.find((entry) => entry && positionEntryMatchesTrackedChangeStory(entry, comment));
+			const previousEntry = previousPositionEntry ?? [positions[fromId], positions[buildBodyTrackedChangeAnchorKey(fromId)]].find((entry) => entry && positionEntryMatchesTrackedChangeStory(entry, comment));
 			if (previousEntry) {
 				for (const key of [toId, toAnchor]) if (positions[key] === void 0) {
 					positions[key] = previousEntry;
 					positionsChanged = true;
 				}
 			}
-			if (normalizeCommentId(activeComment.value) === fromId) activeComment.value = toId;
-			if (normalizeCommentId(activeFloatingCommentInstanceId.value) === fromId) activeFloatingCommentInstanceId.value = toId;
+			if (identitySourceIds.has(normalizeCommentId(activeComment.value))) activeComment.value = toId;
+			if (identitySourceIds.has(normalizeCommentId(activeFloatingCommentInstanceId.value))) activeFloatingCommentInstanceId.value = toId;
 		}
 		if (positionsChanged) editorCommentPositions.value = { ...positions };
 	};
@@ -15824,6 +15849,33 @@ function createV2RemoteReviewHydrationScheduler({ hydrate, getActiveDocumentId,
 	};
 }
 //#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. */
@@ -20263,8 +20315,6 @@ var _hoisted_4$7 = { class: "floating-comments" };
 var UNAVAILABLE_COMMAND_RESULT = false;
 var V2_SELECTION_TOOLBAR_SYNC_RETRY_FRAMES = 3;
 var V2_TYPING_REVIEW_HYDRATION_IDLE_MS = 6500;
-var V2_TYPING_REVIEW_HYDRATION_CEILING_MS = 8e3;
-var V2_TYPING_REVIEW_VISIBLE_PRIME_MS = 250;
 var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 	__name: "SuperDoc",
 	emits: ["selection-update"],
@@ -20385,7 +20435,6 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 		let v2GeometryRafHandle = 0;
 		let v2TrackedChangeRestampRetainPaints = 0;
 		let v2TrackedChangeRestampRetentionReason = null;
-		let v2TrackedChangeRestampRetentionIds = null;
 		const activeEditorRef = computed(() => proxy.$superdoc.activeEditor);
 		const getSuperDocUI = () => proxy.$superdoc?.ui ?? null;
 		const UNAVAILABLE_COMMAND_STATE = Object.freeze({
@@ -21295,49 +21344,29 @@ 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
 				});
 			}
 		});
-		const collectV2TrackedChangeRestampIds = (impactOrIds) => {
-			if (impactOrIds instanceof Set) return new Set([...impactOrIds].filter(Boolean).map(String));
-			if (Array.isArray(impactOrIds)) return new Set(impactOrIds.filter(Boolean).map(String));
-			const ids = /* @__PURE__ */ new Set();
-			for (const id of impactOrIds?.upsertIds ?? []) ids.add(String(id));
-			for (const id of impactOrIds?.removedIds ?? []) ids.add(String(id));
-			for (const pair of impactOrIds?.remappedPairs ?? []) {
-				if (pair?.from) ids.add(String(pair.from));
-				if (pair?.to) ids.add(String(pair.to));
-			}
-			return ids;
-		};
-		const armV2TrackedChangeRestampGeometryRetention = (reason = "tracked-change-restamp", impactOrIds = null) => {
+		const armV2TrackedChangeRestampGeometryRetention = (reason = "tracked-change-restamp") => {
 			v2TrackedChangeRestampRetainPaints = Math.max(v2TrackedChangeRestampRetainPaints, 3);
 			v2TrackedChangeRestampRetentionReason = reason;
-			const retainedIds = collectV2TrackedChangeRestampIds(impactOrIds);
-			if (retainedIds.size > 0) v2TrackedChangeRestampRetentionIds = /* @__PURE__ */ new Set([...v2TrackedChangeRestampRetentionIds ?? [], ...retainedIds]);
 		};
 		const takeV2TrackedChangeRestampGeometryRetention = () => {
-			if (v2TrackedChangeRestampRetainPaints <= 0) return void 0;
-			const reason = v2TrackedChangeRestampRetentionReason ?? "tracked-change-restamp";
-			const retainedTrackedChangeIds = v2TrackedChangeRestampRetentionIds?.size ? Array.from(v2TrackedChangeRestampRetentionIds) : null;
-			v2TrackedChangeRestampRetainPaints -= 1;
-			if (v2TrackedChangeRestampRetainPaints <= 0) {
-				v2TrackedChangeRestampRetentionReason = null;
-				v2TrackedChangeRestampRetentionIds = null;
-			}
+			const reason = v2TrackedChangeRestampRetainPaints > 0 ? v2TrackedChangeRestampRetentionReason ?? "tracked-change-restamp" : "render-epoch-handoff";
+			if (v2TrackedChangeRestampRetainPaints > 0) v2TrackedChangeRestampRetainPaints -= 1;
+			if (v2TrackedChangeRestampRetainPaints <= 0) v2TrackedChangeRestampRetentionReason = null;
 			return {
 				retainMissingTrackedChangeGeometry: true,
-				...retainedTrackedChangeIds ? { retainedTrackedChangeIds } : {},
 				reason
 			};
 		};
 		const clearV2TrackedChangeRestampGeometryRetention = () => {
 			v2TrackedChangeRestampRetainPaints = 0;
 			v2TrackedChangeRestampRetentionReason = null;
-			v2TrackedChangeRestampRetentionIds = null;
 		};
 		const resolveV2GeometryPublishOptions = (options) => typeof options === "function" ? options() : options;
 		const scheduleV2GeometryPublish = (payload, options = void 0) => {
@@ -21360,6 +21389,7 @@ 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);
@@ -21419,8 +21449,6 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			v2RulerHostStyle.value = {};
 			v2RulerReady.value = false;
 		};
-		let v2TypingReviewHydrationTimer = 0;
-		let v2TypingReviewVisiblePrimeTimer = 0;
 		const hydrateV2CommentRowsFromHost = () => {
 			const commentsAdapter = proxy.$superdoc?.activeEditor?.v2Comments ?? null;
 			if (!commentsAdapter) return;
@@ -21441,19 +21469,6 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				...options
 			});
 		};
-		const hydrateVisibleV2TrackedChangeRowsFromHost = (options = {}) => {
-			const trackedChangesAdapter = proxy.$superdoc?.activeEditor?.v2TrackedChanges ?? null;
-			if (!trackedChangesAdapter) return;
-			commentsStore.hydrateTrackedChangesFromV2?.({
-				superdoc: proxy.$superdoc,
-				adapter: trackedChangesAdapter,
-				documentId: proxy.$superdoc?.activeEditor?.documentId ?? null,
-				trackedChangesListMode: "visible-window",
-				refreshReason: "typing-visible-prime",
-				blocking: false,
-				...options
-			});
-		};
 		const v2ReviewMutationReconciler = createV2ReviewMutationReconciler({
 			getContext: () => {
 				const activeEditor = proxy.$superdoc?.activeEditor ?? null;
@@ -21483,46 +21498,21 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				reason: "review-reconcile"
 			})
 		});
-		let v2LastTypingMutationAtMs = 0;
-		let v2TypingReviewHydrationHeldSinceMs = 0;
+		const v2TypingReviewHydrationScheduler = createV2TypingReviewHydrationScheduler({
+			idleMs: V2_TYPING_REVIEW_HYDRATION_IDLE_MS,
+			hydrate: () => v2ReviewHydrationController.reconcileInBackground?.("typing-idle")
+		});
 		const clearV2TypingReviewHydrationTimer = () => {
-			if (v2TypingReviewHydrationTimer && typeof clearTimeout === "function") clearTimeout(v2TypingReviewHydrationTimer);
-			if (v2TypingReviewVisiblePrimeTimer && typeof clearTimeout === "function") clearTimeout(v2TypingReviewVisiblePrimeTimer);
-			v2TypingReviewHydrationTimer = 0;
-			v2TypingReviewVisiblePrimeTimer = 0;
-			v2LastTypingMutationAtMs = 0;
-			v2TypingReviewHydrationHeldSinceMs = 0;
-		};
-		const scheduleV2TypingReviewVisiblePrime = (options = {}) => {
-			if (v2TypingReviewVisiblePrimeTimer) return;
-			v2TypingReviewVisiblePrimeTimer = setTimeout(() => {
-				v2TypingReviewVisiblePrimeTimer = 0;
-				hydrateVisibleV2TrackedChangeRowsFromHost(options);
-			}, V2_TYPING_REVIEW_VISIBLE_PRIME_MS);
-		};
-		const scheduleV2TypingReviewHydration = (options = {}) => {
-			v2LastTypingMutationAtMs = Date.now();
-			scheduleV2TypingReviewVisiblePrime(options.primeOptions);
-			if (!v2TypingReviewHydrationHeldSinceMs) v2TypingReviewHydrationHeldSinceMs = v2LastTypingMutationAtMs;
-			if (v2TypingReviewHydrationTimer && typeof clearTimeout === "function") clearTimeout(v2TypingReviewHydrationTimer);
-			const attempt = () => {
-				v2TypingReviewHydrationTimer = 0;
-				const idleForMs = Date.now() - v2LastTypingMutationAtMs;
-				const heldForMs = Date.now() - v2TypingReviewHydrationHeldSinceMs;
-				if (idleForMs < V2_TYPING_REVIEW_HYDRATION_IDLE_MS && heldForMs < V2_TYPING_REVIEW_HYDRATION_CEILING_MS) {
-					const idleRemainingMs = V2_TYPING_REVIEW_HYDRATION_IDLE_MS - idleForMs;
-					const ceilingRemainingMs = V2_TYPING_REVIEW_HYDRATION_CEILING_MS - heldForMs;
-					v2TypingReviewHydrationTimer = setTimeout(attempt, Math.min(idleRemainingMs, ceilingRemainingMs));
-					return;
-				}
-				v2TypingReviewHydrationHeldSinceMs = 0;
-				hydrateV2ReviewRowsFromHost();
-			};
-			const ceilingRemainingMs = Math.max(0, V2_TYPING_REVIEW_HYDRATION_CEILING_MS - (Date.now() - v2TypingReviewHydrationHeldSinceMs));
-			v2TypingReviewHydrationTimer = setTimeout(attempt, Math.min(V2_TYPING_REVIEW_HYDRATION_IDLE_MS, ceilingRemainingMs));
+			v2TypingReviewHydrationScheduler.clear();
+		};
+		const scheduleV2TypingReviewHydration = () => {
+			v2TypingReviewHydrationScheduler.schedule();
 		};
 		const v2RemoteReviewHydrationScheduler = createV2RemoteReviewHydrationScheduler({
-			hydrate: () => v2ReviewHydrationController.reconcileInBackground?.("remote-review-change"),
+			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;
@@ -21532,6 +21522,7 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			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,
@@ -21582,7 +21573,7 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			v2ReviewHydrationController.invalidate("mutation-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", reviewImpact);
+			if (reviewImpact) armV2TrackedChangeRestampGeometryRetention("tracked-change-mutation");
 			const readiness = (proxy.$superdoc?.activeEditor ?? null)?.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";
@@ -21602,11 +21593,13 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				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 (isV2EditableTextMutationEvent(event)) {
+			if (isTypingMutation) {
 				scheduleV2TypingReviewHydration();
 				return;
 			}
@@ -21632,6 +21625,7 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 		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);
@@ -21650,6 +21644,22 @@ 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.";
@@ -21777,6 +21787,11 @@ 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
@@ -22109,6 +22124,8 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 		});
 		watch(showCommentsSidebar, (value) => {
 			proxy.$superdoc.broadcastSidebarToggle(value);
+			v2BuiltInReviewSurfaceOpen = value === true;
+			syncV2ReviewCatalogDemand();
 		});
 		useViewportFit({
 			getSuperdoc: () => proxy.$superdoc,
@@ -22274,6 +22291,7 @@ 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);
@@ -22769,7 +22787,7 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			], 38);
 		};
 	}
-}, [["__scopeId", "data-v-62293b70"]]);
+}, [["__scopeId", "data-v-25570fd2"]]);
 //#endregion
 //#region src/core/create-app.js
 var PINIA_DEVTOOLS_SETUP_EVENT = "devtools-plugin:setup";
@@ -39639,7 +39657,7 @@ var useToolbarItem = (options) => {
 		"dropdown",
 		"overflow"
 	].includes(options.type)) throw new Error("Invalid toolbar item type - " + options.type);
-	if (options.type === "button" && !options.defaultLabel && !options.icon) throw new Error("Toolbar button item needs either icon or label - " + options.name);
+	if (options.type === "button" && !options.defaultLabel && !options.icon) throw new Error(`Toolbar button item needs either "icon" or "defaultLabel" - ${options.name}. "label" is the live label and is not a substitute for "defaultLabel".`);
 	if (!options.name) throw new Error("Invalid toolbar item name - " + options.name);
 	const id = ref(v4());
 	const type = options.type;
@@ -39684,6 +39702,12 @@ var useToolbarItem = (options) => {
 	const nestedOptions = ref([]);
 	if (options.options) {
 		if (!Array.isArray(options.options)) throw new Error("Invalid toolbar item options - " + options.options);
+		let unusable = 0;
+		for (let index = 0; index < options.options.length; index += 1) {
+			const option = options.options[index];
+			if (!option || typeof option !== "object") unusable += 1;
+		}
+		if (unusable) throw new Error(`Toolbar item options must all be objects - ${options.name}. ${unusable} row(s) are not, so this item is skipped.`);
 		nestedOptions.value?.push(...options.options);
 	}
 	const activate = (attrs = {}, ...args) => {
@@ -42191,6 +42215,17 @@ var BuiltInToolbar = class extends import_eventemitter3.default {
 		this._detachFormatPainterModeChange = null;
 		/** Registered custom-button command unregister handles. */
 		this._customCommandRegs = /* @__PURE__ */ new Map();
+		/**
+		* Custom entries already reported as unbuildable.
+		*
+		* `#makeToolbarItems` runs on every throttled resize and on font or
+		* active-editor changes, not only at construction, so a single static
+		* configuration error would otherwise fire `exception` once per rebuild --
+		* unbounded, into consumer telemetry, for a mistake that cannot change
+		* without a reconfigure. Keyed by name plus message so a different fault
+		* on the same entry still reports once.
+		*/
+		this._reportedInvalidCustomItems = /* @__PURE__ */ new Set();
 		/** Signature of the last-built font options, to skip redundant rebuilds. */
 		this._lastFontOptionsSignature = "";
 		if (!this.config.selector && this.config.element) this.config.selector = this.config.element;
@@ -42297,8 +42332,23 @@ var BuiltInToolbar = class extends import_eventemitter3.default {
 			isDev: this.isDev
 		});
 		const customItems = this.config.customButtons || [];
-		const customToolbarItems = customItems.map((item) => this.#prepareCustomButton(item));
-		if (customItems.length) defaultItems.push(...customToolbarItems);
+		const takenNames = new Set([...defaultItems, ...overflowItems].map((item) => item.name?.value).filter(Boolean));
+		const customToolbarItems = customItems.map((item, index) => {
+			try {
+				if (item?.name && takenNames.has(item.name)) throw new Error(`Toolbar item name "${item.name}" is already taken by another item, so this entry is skipped.`);
+				const prepared = this.#prepareCustomButton(item);
+				takenNames.add(prepared.name?.value);
+				return prepared;
+			} catch (error) {
+				const signature = `${item?.name ?? `<unnamed@${index}>`}::${error?.message ?? String(error)}`;
+				if (!this._reportedInvalidCustomItems.has(signature)) {
+					this._reportedInvalidCustomItems.add(signature);
+					this.#emitCommandException(error, item?.name ?? null);
+				}
+				return null;
+			}
+		}).filter(Boolean);
+		if (customToolbarItems.length) defaultItems.push(...customToolbarItems);
 		let allConfigItems = [...defaultItems.map((item) => item.name.value), ...overflowItems.map((item) => item.name.value)];
 		if (hasExplicitGroupComposition) {
 			const groupedItems = Object.values(this.config.groups).flatMap((item) => item);
@@ -42711,13 +42761,15 @@ var BuiltInToolbar = class extends import_eventemitter3.default {
 		}
 	}
 	#emitCommandException(originalError, name) {
-		const error = originalError instanceof Error ? originalError : new Error(String(originalError));
-		this.emit("exception", {
-			error,
+		const payload = {
+			error: originalError instanceof Error ? originalError : new Error(String(originalError)),
 			originalError,
 			itemName: name ?? null,
 			editor: this.superdoc?.activeEditor ?? this.activeEditor ?? null
-		});
+		};
+		const hostPayload = { ...payload };
+		this.emit("exception", payload);
+		this.superdoc?.emit?.("exception", hostPayload);
 	}
 	/**
 	* Main toolbar command entry point used by the rendered components.
@@ -43212,7 +43264,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.12";
+		this.version = "2.4.0-next.13";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || v4();
 		this.colors = this.config.colors ?? [];
@@ -44634,6 +44686,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 		if (element) this.config.modules.comments.element = element;
 		this.commentsList = new SuperComments(this.config.modules?.comments, this);
 		if (this.config.onCommentsListChange) this.config.onCommentsListChange({ isRendered: true });
+		this.emit("comments-list-change", { isRendered: true });
 	}
 	/**
 	* Remove the comments list from the superdoc
@@ -44643,6 +44696,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 			this.commentsList.close();
 			this.commentsList = null;
 			if (this.config.onCommentsListChange) this.config.onCommentsListChange({ isRendered: false });
+			this.emit("comments-list-change", { isRendered: false });
 		}
 	}
 	/**