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

package/dist/superdoc/src/internal/toolbar/built-in-toolbar.d.ts

@@ -187,6 +187,17 @@ export class BuiltInToolbar extends EventEmitter<string | symbol, any> {
     _detachFormatPainterModeChange: any;
     /** Registered custom-button command unregister handles. */
     _customCommandRegs: Map<any, any>;
+    /**
+     * 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.
+     */
+    _reportedInvalidCustomItems: Set<any>;
     /** Signature of the last-built font options, to skip redundant rebuilds. */
     _lastFontOptionsSignature: string;
     app: import('vue').App<Element> | undefined;

package/dist/superdoc/src/public/index.d.cts

@@ -99,6 +99,7 @@ import type { SuperDocExceptionEditorPayload as __Cjs_SuperDocExceptionEditorPay
 import type { SuperDocExceptionPayload as __Cjs_SuperDocExceptionPayload } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocExceptionRestorePayload as __Cjs_SuperDocExceptionRestorePayload } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocExceptionStorePayload as __Cjs_SuperDocExceptionStorePayload } from './index.js' with { "resolution-mode": "import" };
+import type { SuperDocExceptionToolbarPayload as __Cjs_SuperDocExceptionToolbarPayload } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocExtension as __Cjs_SuperDocExtension } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocExtensionActivateReturn as __Cjs_SuperDocExtensionActivateReturn } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocExtensionCapabilities as __Cjs_SuperDocExtensionCapabilities } from './index.js' with { "resolution-mode": "import" };
@@ -166,6 +167,12 @@ import type { SurfacesModuleConfig as __Cjs_SurfacesModuleConfig } from './index
 import type { TextAddress as __Cjs_TextAddress } from './index.js' with { "resolution-mode": "import" };
 import type { TextSegment as __Cjs_TextSegment } from './index.js' with { "resolution-mode": "import" };
 import type { TextTarget as __Cjs_TextTarget } from './index.js' with { "resolution-mode": "import" };
+import type { ToolbarCustomButton as __Cjs_ToolbarCustomButton } from './index.js' with { "resolution-mode": "import" };
+import type { ToolbarCustomButtonContext as __Cjs_ToolbarCustomButtonContext } from './index.js' with { "resolution-mode": "import" };
+import type { ToolbarCustomButtonItem as __Cjs_ToolbarCustomButtonItem } from './index.js' with { "resolution-mode": "import" };
+import type { ToolbarCustomDropdownItem as __Cjs_ToolbarCustomDropdownItem } from './index.js' with { "resolution-mode": "import" };
+import type { ToolbarCustomDropdownOption as __Cjs_ToolbarCustomDropdownOption } from './index.js' with { "resolution-mode": "import" };
+import type { ToolbarCustomSeparatorItem as __Cjs_ToolbarCustomSeparatorItem } from './index.js' with { "resolution-mode": "import" };
 import type { TrackChangeAuthor as __Cjs_TrackChangeAuthor } from './index.js' with { "resolution-mode": "import" };
 import type { TrackChangeHighlightColors as __Cjs_TrackChangeHighlightColors } from './index.js' with { "resolution-mode": "import" };
 import type { TrackChangesAuthorColorsConfig as __Cjs_TrackChangesAuthorColorsConfig } from './index.js' with { "resolution-mode": "import" };
@@ -290,6 +297,7 @@ export type { __Cjs_SuperDocExceptionEditorPayload as SuperDocExceptionEditorPay
 export type { __Cjs_SuperDocExceptionPayload as SuperDocExceptionPayload };
 export type { __Cjs_SuperDocExceptionRestorePayload as SuperDocExceptionRestorePayload };
 export type { __Cjs_SuperDocExceptionStorePayload as SuperDocExceptionStorePayload };
+export type { __Cjs_SuperDocExceptionToolbarPayload as SuperDocExceptionToolbarPayload };
 export type { __Cjs_SuperDocExtension as SuperDocExtension };
 export type { __Cjs_SuperDocExtensionActivateReturn as SuperDocExtensionActivateReturn };
 export type { __Cjs_SuperDocExtensionCapabilities as SuperDocExtensionCapabilities };
@@ -357,6 +365,12 @@ export type { __Cjs_SurfacesModuleConfig as SurfacesModuleConfig };
 export type { __Cjs_TextAddress as TextAddress };
 export type { __Cjs_TextSegment as TextSegment };
 export type { __Cjs_TextTarget as TextTarget };
+export type { __Cjs_ToolbarCustomButton as ToolbarCustomButton };
+export type { __Cjs_ToolbarCustomButtonContext as ToolbarCustomButtonContext };
+export type { __Cjs_ToolbarCustomButtonItem as ToolbarCustomButtonItem };
+export type { __Cjs_ToolbarCustomDropdownItem as ToolbarCustomDropdownItem };
+export type { __Cjs_ToolbarCustomDropdownOption as ToolbarCustomDropdownOption };
+export type { __Cjs_ToolbarCustomSeparatorItem as ToolbarCustomSeparatorItem };
 export type { __Cjs_TrackChangeAuthor as TrackChangeAuthor };
 export type { __Cjs_TrackChangeHighlightColors as TrackChangeHighlightColors };
 export type { __Cjs_TrackChangesAuthorColorsConfig as TrackChangesAuthorColorsConfig };

package/dist/superdoc/src/public/index.d.ts

@@ -62,6 +62,7 @@ export type { SuperDocAwarenessUpdatePayload } from '../core/types/index.js';
 export type { SuperDocCommentsUpdatePayload } from '../core/types/index.js';
 export type { SuperDocEditorPayload } from '../core/types/index.js';
 export type { SuperDocExceptionEditorPayload } from '../core/types/index.js';
+export type { SuperDocExceptionToolbarPayload } from '../core/types/index.js';
 export type { SuperDocExceptionPayload } from '../core/types/index.js';
 export type { SuperDocExceptionRestorePayload } from '../core/types/index.js';
 export type { SuperDocExceptionStorePayload } from '../core/types/index.js';
@@ -75,6 +76,12 @@ export type { LayoutMode } from '../../../layout-engine/painters/dom/src/index.j
 export type { CommentsConfig } from '../core/types/index.js';
 export type { TrackChangeHighlightColors } from '../core/types/index.js';
 export type { ContentControlsConfig } from '../core/types/index.js';
+export type { ToolbarCustomButton } from '../core/types/index.js';
+export type { ToolbarCustomButtonItem } from '../core/types/index.js';
+export type { ToolbarCustomDropdownItem } from '../core/types/index.js';
+export type { ToolbarCustomDropdownOption } from '../core/types/index.js';
+export type { ToolbarCustomSeparatorItem } from '../core/types/index.js';
+export type { ToolbarCustomButtonContext } from '../core/types/index.js';
 export type { LinkPopoverConfig } from '../core/types/index.js';
 export type { LinkPopoverContext } from '../core/types/index.js';
 export type { LinkPopoverResolution } from '../core/types/index.js';

package/dist/superdoc.cjs

@@ -4,7 +4,7 @@ const require_blank_docx = require("./chunks/blank-docx-BuFAbRjs.cjs");
 const require_eventemitter3 = require("./chunks/eventemitter3-C_TAnXOl.cjs");
 const require_uuid = require("./chunks/uuid-BhG0ngwk.cjs");
 const require_jszip = require("./chunks/jszip-D8mAFF-r.cjs");
-const require_create_super_doc_ui = require("./chunks/create-super-doc-ui-BWYOinLD.cjs");
+const require_create_super_doc_ui = require("./chunks/create-super-doc-ui-CTe12b19.cjs");
 const require__plugin_vue_export_helper = require("./chunks/_plugin-vue_export-helper-SDR04tiH.cjs");
 const require_constants = require("./chunks/constants-DpXuDx_g.cjs");
 let vue = require("vue");
@@ -9908,16 +9908,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;
@@ -9927,20 +9949,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 };
 	};
@@ -15838,6 +15863,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. */
@@ -20302,8 +20354,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__*/ require__plugin_vue_export_helper._plugin_vue_export_helper_default({
 	__name: "SuperDoc",
 	emits: ["selection-update"],
@@ -20424,7 +20474,6 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 		let v2GeometryRafHandle = 0;
 		let v2TrackedChangeRestampRetainPaints = 0;
 		let v2TrackedChangeRestampRetentionReason = null;
-		let v2TrackedChangeRestampRetentionIds = null;
 		const activeEditorRef = (0, vue.computed)(() => proxy.$superdoc.activeEditor);
 		const getSuperDocUI = () => proxy.$superdoc?.ui ?? null;
 		const UNAVAILABLE_COMMAND_STATE = Object.freeze({
@@ -21334,49 +21383,29 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 				}
 			},
 			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) => {
@@ -21399,6 +21428,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 		const onV2RenderReadiness = (payload) => {
 			const snapshot = payload?.snapshot ?? payload ?? null;
 			if (!snapshot) return;
+			if (v2TypingReviewHydrationScheduler.isPending()) return;
 			v2ReviewHydrationController.onRenderReadiness(snapshot);
 		};
 		const v2PageMetricsSnapshot = (0, vue.shallowRef)(null);
@@ -21458,8 +21488,6 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 			v2RulerHostStyle.value = {};
 			v2RulerReady.value = false;
 		};
-		let v2TypingReviewHydrationTimer = 0;
-		let v2TypingReviewVisiblePrimeTimer = 0;
 		const hydrateV2CommentRowsFromHost = () => {
 			const commentsAdapter = proxy.$superdoc?.activeEditor?.v2Comments ?? null;
 			if (!commentsAdapter) return;
@@ -21480,19 +21508,6 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 				...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 = require_create_super_doc_ui.createV2ReviewMutationReconciler({
 			getContext: () => {
 				const activeEditor = proxy.$superdoc?.activeEditor ?? null;
@@ -21522,46 +21537,21 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 				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;
@@ -21571,6 +21561,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 			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,
@@ -21621,7 +21612,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 			v2ReviewHydrationController.invalidate("mutation-committed");
 			const reviewImpact = require_create_super_doc_ui.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";
@@ -21641,11 +21632,13 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 				Promise.resolve(reconciliation).then(settleReviewMutation, () => settleReviewMutation(false));
 				return;
 			}
+			const isTypingMutation = require_create_super_doc_ui.isV2EditableTextMutationEvent(event);
+			if (!isTypingMutation) clearV2TypingReviewHydrationTimer();
 			if (reviewImpact?.reconcileMode === "authoritative" && reviewImpact.upsertIds.size > 0) {
 				hydrateV2CommentRowsFromHost();
 				return;
 			}
-			if (require_create_super_doc_ui.isV2EditableTextMutationEvent(event)) {
+			if (isTypingMutation) {
 				scheduleV2TypingReviewHydration();
 				return;
 			}
@@ -21671,6 +21664,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 		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);
@@ -21689,6 +21683,22 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 				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.";
@@ -21816,6 +21826,11 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 				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
@@ -22148,6 +22163,8 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 		});
 		(0, vue.watch)(showCommentsSidebar, (value) => {
 			proxy.$superdoc.broadcastSidebarToggle(value);
+			v2BuiltInReviewSurfaceOpen = value === true;
+			syncV2ReviewCatalogDemand();
 		});
 		useViewportFit({
 			getSuperdoc: () => proxy.$superdoc,
@@ -22313,6 +22330,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 			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 = (0, vue.ref)(null);
 		const isDragging = (0, vue.ref)(false);
@@ -22808,7 +22826,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 			], 38);
 		};
 	}
-}, [["__scopeId", "data-v-62293b70"]]);
+}, [["__scopeId", "data-v-25570fd2"]]);
 //#endregion
 //#region src/core/create-app.js
 var PINIA_DEVTOOLS_SETUP_EVENT = "devtools-plugin:setup";
@@ -39686,7 +39704,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 = (0, vue.ref)(require_uuid.v4());
 	const type = options.type;
@@ -39731,6 +39749,12 @@ var useToolbarItem = (options) => {
 	const nestedOptions = (0, vue.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) => {
@@ -42257,6 +42281,17 @@ var BuiltInToolbar = class extends require_eventemitter3.import_eventemitter3.de
 		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;
@@ -42363,8 +42398,23 @@ var BuiltInToolbar = class extends require_eventemitter3.import_eventemitter3.de
 			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);
@@ -42777,13 +42827,15 @@ var BuiltInToolbar = class extends require_eventemitter3.import_eventemitter3.de
 		}
 	}
 	#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.
@@ -43278,7 +43330,7 @@ var SuperDoc = class extends require_eventemitter3.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 || require_uuid.v4();
 		this.colors = this.config.colors ?? [];
@@ -44700,6 +44752,7 @@ var SuperDoc = class extends require_eventemitter3.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
@@ -44709,6 +44762,7 @@ var SuperDoc = class extends require_eventemitter3.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 });
 		}
 	}
 	/**