superdoc 2.0.0-next.45 → 2.0.0-next.46

package/AGENTS.md

@@ -179,7 +179,14 @@ For building your own browser UI (toolbars, selection popovers, comment panels,
 citation cards) around a live SuperDoc editor, use the v2-native public custom-UI
 entrypoints. They are the supported subpath exports for custom UI:
 
-- `superdoc/ui` — framework-agnostic controller: `createSuperDocUI({ superdoc })`.
+- `superdoc.ui` — the framework-agnostic controller every instance owns. Read it;
+  do not build one. `superdoc.destroy()` tears it down. The property is typed
+  `BorrowedSuperDocUI`, which omits `destroy()`, so you cannot tear down state
+  the built-in toolbar and other consumers of that instance are still reading.
+  Only a controller you created yourself is yours to destroy.
+- `superdoc/ui` — the controller's types, plus `createSuperDocUI({ superdoc })`
+  for the rare case you want a **second, independently owned** controller that
+  you create and destroy yourself.
 - `superdoc/ui/react` — React bindings: `SuperDocUIProvider`, `useSetSuperDoc`,
   `useSuperDocUI`, `useSuperDocHost`, and slice hooks.
 
@@ -207,14 +214,14 @@ painted output or reach into editor internals for coordinates.
 **Supported / unsupported.**
 
 - There is **no public headless path.** Backend / external Document API access uses
-  the SDK (`@superdoc-dev/sdk`) — see *Document Engine* above. Browser custom UI uses
-  `superdoc/ui`.
+  the SDK (`@superdoc-dev/sdk`) — see *Document Engine* above. Browser custom UI
+  reads `superdoc.ui`, typed by `superdoc/ui`.
 - **Migrating from v1 `superdoc/headless-toolbar*`?** Those package subpaths are
   intentionally removed in v2 (migration-only posture). Move v1 custom toolbar /
-  headless-toolbar code to `superdoc/ui` (`createSuperDocUI`) and
-  `superdoc/ui/react`. Unsupported or not-yet-migrated commands stay visible in
-  the toolbar snapshot as disabled with a stable `reason` (the `SuperDocUIReason`
-  taxonomy on `CommandState`) instead of silently disappearing.
+  headless-toolbar code to `superdoc.ui` and `superdoc/ui/react`. Unsupported or
+  not-yet-migrated commands stay visible in the toolbar snapshot as disabled with
+  a stable `reason` (the `SuperDocUIReason` taxonomy on `CommandState`) instead
+  of silently disappearing.
 - The SuperDoc shell may import only the supported `@superdoc/docx-engine`
   package entries. Do **not** import internal implementation packages such as
   `@superdoc/v2-host`, `@superdoc/document-api-v2-adapter`, or
@@ -241,7 +248,7 @@ painted output or reach into editor internals for coordinates.
 | Format text (programmatic) | Use Document API: `editor.doc.format.bold(...)`, `.italic(...)`, etc. |
 | Real-time collab | Configure `modules.collaboration` with a Yjs provider |
 | Custom built-in toolbar | Use `modules.toolbar.customButtons` array |
-| Build your own UI | Use `superdoc/ui` / `superdoc/ui/react` (`createSuperDocUI`) — see *Custom UI* above |
+| Build your own UI | Read `superdoc.ui`, or use `superdoc/ui/react` — see *Custom UI* above |
 | Anchor citations to inserted text | Read the Document API receipt's `effects.insertedText[]` |
 | Listen to events | `superdoc.on('ready', ({ superdoc }) => { ... })` |
 

package/dist/chunks/{create-super-doc-ui-DDxbK_M7.cjs → create-super-doc-ui-6FUZ9d-y.cjs}

@@ -539,118 +539,6 @@ const isV2EditableTextMutationEvent = (event) => {
 	if (event?.type !== "mutation:committed" || event.origin !== "command") return false;
 	return V2_TYPING_COMMAND_KINDS.has(event.editableCommandKind);
 };
-function shallowEqual(a, b) {
-	if (Object.is(a, b)) return true;
-	if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) return false;
-	if (Array.isArray(a) !== Array.isArray(b)) return false;
-	const aKeys = Object.keys(a);
-	const bKeys = Object.keys(b);
-	if (aKeys.length !== bKeys.length) return false;
-	for (const key of aKeys) {
-		if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
-		if (!Object.is(a[key], b[key])) return false;
-	}
-	return true;
-}
-function sdRunPropsToInlineRunPatch(props) {
-	if (!props || typeof props !== "object") return {};
-	const patch = {};
-	if (props.fonts) patch.rFonts = {
-		ascii: props.fonts.ascii,
-		hAnsi: props.fonts.hAnsi,
-		eastAsia: props.fonts.eastAsia,
-		cs: props.fonts.cs,
-		asciiTheme: props.fonts.asciiTheme,
-		hAnsiTheme: props.fonts.hAnsiTheme,
-		eastAsiaTheme: props.fonts.eastAsiaTheme,
-		csTheme: props.fonts.csTheme,
-		hint: props.fonts.hint
-	};
-	if (props.fontFamily != null) patch.fontFamily = props.fontFamily;
-	if (props.lang) patch.lang = {
-		val: props.lang.val,
-		eastAsia: props.lang.eastAsia,
-		bidi: props.lang.bidi
-	};
-	if (props.fontSize != null) patch.fontSize = props.fontSize;
-	if (props.fontSizeCs != null) patch.fontSizeCs = props.fontSizeCs;
-	const color = projectColorRefToInlineColor(props.color);
-	if (color != null) patch.color = color;
-	if (props.highlight != null) patch.highlight = props.highlight;
-	const shading = projectShadingToInlinePatch(props.shading);
-	if (shading) patch.shading = shading;
-	if (props.cs != null) patch.cs = props.cs;
-	if (props.rtl != null) patch.rtl = props.rtl;
-	if (props.bold != null) patch.bold = props.bold;
-	if (props.boldCs != null) patch.bCs = props.boldCs;
-	if (props.italic != null) patch.italic = props.italic;
-	if (props.italicCs != null) patch.iCs = props.italicCs;
-	const underline = projectUnderlineToInlinePatch(props.underline);
-	if (underline !== void 0) patch.underline = underline;
-	if (props.strikethrough != null) patch.strike = props.strikethrough;
-	if (props.doubleStrikethrough != null) patch.dstrike = props.doubleStrikethrough;
-	if (props.caps != null) patch.caps = props.caps;
-	if (props.smallCaps != null) patch.smallCaps = props.smallCaps;
-	if (props.outline != null) patch.outline = props.outline;
-	if (props.shadow != null) patch.shadow = props.shadow;
-	if (props.emboss != null) patch.emboss = props.emboss;
-	if (props.imprint != null) patch.imprint = props.imprint;
-	if (props.verticalAlign != null) patch.vertAlign = props.verticalAlign;
-	if (props.characterSpacing != null) patch.letterSpacing = props.characterSpacing;
-	if (props.characterScale != null) patch.charScale = props.characterScale;
-	if (props.kern != null) patch.kerning = props.kern;
-	if (props.baselineShift != null) patch.position = props.baselineShift;
-	if (props.fitTextWidth != null) patch.fitText = { val: props.fitTextWidth };
-	if (props.vanish != null) patch.vanish = props.vanish;
-	if (props.webHidden != null) patch.webHidden = props.webHidden;
-	if (props.specVanish != null) patch.specVanish = props.specVanish;
-	const border = projectBorderToInlinePatch(props.border);
-	if (border) patch.border = border;
-	return patch;
-}
-function projectColorRefToInlineColor(color) {
-	if (!color) return void 0;
-	if (typeof color === "string") return color;
-	if (color.model === "rgb") return color.value;
-	if (color.model === "auto") return "auto";
-}
-function projectUnderlineToInlinePatch(underline) {
-	if (underline == null) return void 0;
-	const patch = {};
-	if (underline.style != null) patch.style = underline.style;
-	if (underline.color?.model === "rgb") patch.color = underline.color.value;
-	if (underline.color?.model === "theme") patch.themeColor = underline.color.theme;
-	return Object.keys(patch).length > 0 ? patch : true;
-}
-function projectShadingToInlinePatch(shading) {
-	if (!shading) return void 0;
-	const patch = {};
-	const fill = projectColorRefToInlineColor(shading.fill);
-	if (fill != null) patch.fill = fill;
-	const color = projectColorRefToInlineColor(shading.color);
-	if (color != null) patch.color = color;
-	if (shading.pattern != null) patch.val = shading.pattern;
-	return Object.keys(patch).length > 0 ? patch : void 0;
-}
-function projectBorderToInlinePatch(border) {
-	if (!border) return void 0;
-	const patch = {};
-	if (border.style != null) patch.val = border.style;
-	if (border.width != null) patch.sz = border.width;
-	if (border.space != null) patch.space = border.space;
-	const color = projectColorRefToInlineColor(border.color);
-	if (color != null) patch.color = color;
-	return Object.keys(patch).length > 0 ? patch : void 0;
-}
-function selectionKey(selection) {
-	const target = selection?.selectionTarget ?? selection?.target;
-	if (!selection || !target) return "";
-	try {
-		return JSON.stringify(target);
-	} catch {
-		return String(target);
-	}
-}
 const SUPERDOC_UI_REASONS = {
 	notReady: "not-ready",
 	documentApiUnavailable: "document-api-unavailable",
@@ -1313,6 +1201,118 @@ const ALL_BUILT_IN_COMMAND_IDS = COMMAND_CATALOG.map((d) => d.id);
 function getCommandDescriptor(id) {
 	return CATALOG_BY_ID.get(id) ?? null;
 }
+function shallowEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) return false;
+	if (Array.isArray(a) !== Array.isArray(b)) return false;
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+	if (aKeys.length !== bKeys.length) return false;
+	for (const key of aKeys) {
+		if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+		if (!Object.is(a[key], b[key])) return false;
+	}
+	return true;
+}
+function sdRunPropsToInlineRunPatch(props) {
+	if (!props || typeof props !== "object") return {};
+	const patch = {};
+	if (props.fonts) patch.rFonts = {
+		ascii: props.fonts.ascii,
+		hAnsi: props.fonts.hAnsi,
+		eastAsia: props.fonts.eastAsia,
+		cs: props.fonts.cs,
+		asciiTheme: props.fonts.asciiTheme,
+		hAnsiTheme: props.fonts.hAnsiTheme,
+		eastAsiaTheme: props.fonts.eastAsiaTheme,
+		csTheme: props.fonts.csTheme,
+		hint: props.fonts.hint
+	};
+	if (props.fontFamily != null) patch.fontFamily = props.fontFamily;
+	if (props.lang) patch.lang = {
+		val: props.lang.val,
+		eastAsia: props.lang.eastAsia,
+		bidi: props.lang.bidi
+	};
+	if (props.fontSize != null) patch.fontSize = props.fontSize;
+	if (props.fontSizeCs != null) patch.fontSizeCs = props.fontSizeCs;
+	const color = projectColorRefToInlineColor(props.color);
+	if (color != null) patch.color = color;
+	if (props.highlight != null) patch.highlight = props.highlight;
+	const shading = projectShadingToInlinePatch(props.shading);
+	if (shading) patch.shading = shading;
+	if (props.cs != null) patch.cs = props.cs;
+	if (props.rtl != null) patch.rtl = props.rtl;
+	if (props.bold != null) patch.bold = props.bold;
+	if (props.boldCs != null) patch.bCs = props.boldCs;
+	if (props.italic != null) patch.italic = props.italic;
+	if (props.italicCs != null) patch.iCs = props.italicCs;
+	const underline = projectUnderlineToInlinePatch(props.underline);
+	if (underline !== void 0) patch.underline = underline;
+	if (props.strikethrough != null) patch.strike = props.strikethrough;
+	if (props.doubleStrikethrough != null) patch.dstrike = props.doubleStrikethrough;
+	if (props.caps != null) patch.caps = props.caps;
+	if (props.smallCaps != null) patch.smallCaps = props.smallCaps;
+	if (props.outline != null) patch.outline = props.outline;
+	if (props.shadow != null) patch.shadow = props.shadow;
+	if (props.emboss != null) patch.emboss = props.emboss;
+	if (props.imprint != null) patch.imprint = props.imprint;
+	if (props.verticalAlign != null) patch.vertAlign = props.verticalAlign;
+	if (props.characterSpacing != null) patch.letterSpacing = props.characterSpacing;
+	if (props.characterScale != null) patch.charScale = props.characterScale;
+	if (props.kern != null) patch.kerning = props.kern;
+	if (props.baselineShift != null) patch.position = props.baselineShift;
+	if (props.fitTextWidth != null) patch.fitText = { val: props.fitTextWidth };
+	if (props.vanish != null) patch.vanish = props.vanish;
+	if (props.webHidden != null) patch.webHidden = props.webHidden;
+	if (props.specVanish != null) patch.specVanish = props.specVanish;
+	const border = projectBorderToInlinePatch(props.border);
+	if (border) patch.border = border;
+	return patch;
+}
+function projectColorRefToInlineColor(color) {
+	if (!color) return void 0;
+	if (typeof color === "string") return color;
+	if (color.model === "rgb") return color.value;
+	if (color.model === "auto") return "auto";
+}
+function projectUnderlineToInlinePatch(underline) {
+	if (underline == null) return void 0;
+	const patch = {};
+	if (underline.style != null) patch.style = underline.style;
+	if (underline.color?.model === "rgb") patch.color = underline.color.value;
+	if (underline.color?.model === "theme") patch.themeColor = underline.color.theme;
+	return Object.keys(patch).length > 0 ? patch : true;
+}
+function projectShadingToInlinePatch(shading) {
+	if (!shading) return void 0;
+	const patch = {};
+	const fill = projectColorRefToInlineColor(shading.fill);
+	if (fill != null) patch.fill = fill;
+	const color = projectColorRefToInlineColor(shading.color);
+	if (color != null) patch.color = color;
+	if (shading.pattern != null) patch.val = shading.pattern;
+	return Object.keys(patch).length > 0 ? patch : void 0;
+}
+function projectBorderToInlinePatch(border) {
+	if (!border) return void 0;
+	const patch = {};
+	if (border.style != null) patch.val = border.style;
+	if (border.width != null) patch.sz = border.width;
+	if (border.space != null) patch.space = border.space;
+	const color = projectColorRefToInlineColor(border.color);
+	if (color != null) patch.color = color;
+	return Object.keys(patch).length > 0 ? patch : void 0;
+}
+function selectionKey(selection) {
+	const target = selection?.selectionTarget ?? selection?.target;
+	if (!selection || !target) return "";
+	try {
+		return JSON.stringify(target);
+	} catch {
+		return String(target);
+	}
+}
 function parseCommaSeparatedIds(value) {
 	return value.split(",").map((id) => id.trim()).filter(Boolean);
 }
@@ -1725,6 +1725,7 @@ function normalizeHostSelectionApplyResult(result) {
 }
 var HOST_EVENTS = [
 	"editorCreate",
+	"active-editor-change",
 	"document-mode-change",
 	"zoomChange",
 	"measurement-unit-change",
@@ -5950,11 +5951,20 @@ function createSuperDocUI(options) {
 		state = nextState;
 		for (const listener of [...listeners]) listener(state);
 	};
+	const activeEditorResetHooks = [];
+	const runActiveEditorResetHooks = () => {
+		for (const reset of activeEditorResetHooks) try {
+			reset();
+		} catch {}
+	};
 	const detachers = [];
 	const attach = (source, events) => {
 		if (!source || typeof source.on !== "function") return;
 		for (const event of events) {
-			const handler = () => recompute();
+			const handler = event === "active-editor-change" ? () => {
+				runActiveEditorResetHooks();
+				recompute();
+			} : () => recompute();
 			try {
 				source.on(event, handler);
 				detachers.push(() => {
@@ -8258,6 +8268,28 @@ function createSuperDocUI(options) {
 		if (typeof xOrInput === "object") return pointEntityHits(xOrInput?.x, xOrInput?.y);
 		return null;
 	}
+	const geometryObservers = /* @__PURE__ */ new Set();
+	const bindGeometryObserver = (entry) => {
+		const host = getHost();
+		if (typeof host?.observeGeometry !== "function") return;
+		const off = safeCall(() => host.observeGeometry(() => entry.schedule()), null);
+		entry.detach = typeof off === "function" ? off : null;
+	};
+	const detachGeometryObserver = (entry) => {
+		if (!entry.detach) return;
+		try {
+			entry.detach();
+		} catch {}
+		entry.detach = null;
+	};
+	const rebindGeometryObservers = () => {
+		for (const entry of geometryObservers) {
+			detachGeometryObserver(entry);
+			bindGeometryObserver(entry);
+			entry.schedule();
+		}
+	};
+	activeEditorResetHooks.push(rebindGeometryObservers);
 	const viewport = {
 		getRect: (input) => {
 			const host = getHost();
@@ -8293,12 +8325,15 @@ function createSuperDocUI(options) {
 				zoom: s.zoom
 			}));
 			unsubs.push(sub.subscribe(() => schedule()));
-			const host = getHost();
-			if (typeof host?.observeGeometry === "function") {
-				const off = safeCall(() => host.observeGeometry(() => schedule()), null);
-				if (typeof off === "function") unsubs.push(off);
-			}
+			const entry = {
+				schedule,
+				detach: null
+			};
+			bindGeometryObserver(entry);
+			geometryObservers.add(entry);
 			return () => {
+				geometryObservers.delete(entry);
+				detachGeometryObserver(entry);
 				if (frame && typeof cancelAnimationFrame === "function") cancelAnimationFrame(frame);
 				for (const unsub of unsubs.splice(0)) try {
 					unsub();
@@ -8472,6 +8507,28 @@ function createSuperDocUI(options) {
 		return searchState;
 	};
 	let searchRequestGeneration = 0;
+	let releaseActiveSearchSession = null;
+	const releaseSearchSession = () => {
+		const release = releaseActiveSearchSession;
+		releaseActiveSearchSession = null;
+		if (!release) return;
+		safeCall(() => {
+			release();
+			return null;
+		}, null);
+	};
+	const resetSearchForActiveEditorChange = () => {
+		searchRequestGeneration += 1;
+		releaseSearchSession();
+		const available = searchIsAvailable();
+		searchState = {
+			...SEARCH_UNAVAILABLE_SLICE,
+			available,
+			reason: available ? void 0 : SUPERDOC_UI_REASONS.searchUnavailable
+		};
+		emitSearch();
+	};
+	activeEditorResetHooks.push(resetSearchForActiveEditorChange);
 	const readSearchQueryError = (record) => {
 		if (!record) return false;
 		const queryError = record.queryError;
@@ -8623,11 +8680,14 @@ function createSuperDocUI(options) {
 		},
 		close: () => {
 			searchRequestGeneration += 1;
-			const host = getHostSearch();
-			if (host && typeof host.clear === "function") safeCall(() => host.clear(), null);
+			if (releaseActiveSearchSession) releaseSearchSession();
 			else {
-				const editSearch = getEditCommandSearch();
-				if (editSearch && typeof editSearch.query === "function") safeCall(() => editSearch.query({ query: "" }), null);
+				const host = getHostSearch();
+				if (host && typeof host.clear === "function") safeCall(() => host.clear(), null);
+				else {
+					const editSearch = getEditCommandSearch();
+					if (editSearch && typeof editSearch.query === "function") safeCall(() => editSearch.query({ query: "" }), null);
+				}
 			}
 			searchState = {
 				...SEARCH_UNAVAILABLE_SLICE,
@@ -8655,6 +8715,9 @@ function createSuperDocUI(options) {
 						open: true,
 						reason: void 0
 					});
+					releaseActiveSearchSession = () => {
+						editSearch.query({ query: "" });
+					};
 					const result = safeCall(() => editSearch.query({
 						query,
 						caseSensitive,
@@ -8695,6 +8758,9 @@ function createSuperDocUI(options) {
 				open: true,
 				reason: void 0
 			});
+			releaseActiveSearchSession = () => {
+				if (typeof host.clear === "function") host.clear();
+			};
 			applyHostSearchResult(safeCall(() => host.setSession(query, {
 				caseSensitive,
 				includeDeletedText,
@@ -8704,6 +8770,11 @@ function createSuperDocUI(options) {
 			if (query.length > 0 && searchState.total === 0 && searchState.reason !== SUPERDOC_UI_REASONS.searchInvalidPattern) {
 				const editSearch = getEditCommandSearch();
 				if (editSearch && typeof editSearch.query === "function" && typeof editSearch.getState === "function") {
+					const releaseHostSession = releaseActiveSearchSession;
+					releaseActiveSearchSession = () => {
+						releaseHostSession?.();
+						editSearch.query({ query: "" });
+					};
 					const commandResult = safeCall(() => editSearch.query({
 						query,
 						caseSensitive,
@@ -8968,6 +9039,8 @@ function createSuperDocUI(options) {
 		currentDocumentSelectionSource = null;
 		listeners.clear();
 		searchListeners.clear();
+		painterCaptureEpoch += 1;
+		painterModeListeners.clear();
 		customCommands.clear();
 	};
 	const controller = {
@@ -8991,12 +9064,14 @@ function createSuperDocUI(options) {
 		styles,
 		formatPainter: {
 			setPointerSelecting(flag) {
+				if (disposed) return;
 				painter = {
 					...painter,
 					pointerSelecting: flag
 				};
 			},
 			notifyPointerUp() {
+				if (disposed) return;
 				painter = {
 					...painter,
 					pointerSelecting: false
@@ -9004,12 +9079,14 @@ function createSuperDocUI(options) {
 				maybeApply();
 			},
 			setKeyboardSelecting(flag) {
+				if (disposed) return;
 				painter = {
 					...painter,
 					keyboardSelecting: flag
 				};
 			},
 			notifyKeyUp() {
+				if (disposed) return;
 				painter = {
 					...painter,
 					keyboardSelecting: false
@@ -9017,9 +9094,11 @@ function createSuperDocUI(options) {
 				maybeApply();
 			},
 			cancel() {
+				if (disposed) return;
 				exitFormatPainter();
 			},
 			onModeChange(cb) {
+				if (disposed) return () => {};
 				painterModeListeners.add(cb);
 				return () => painterModeListeners.delete(cb);
 			}