superdoc 2.0.0-next.49 → 2.0.0-next.50

package/AGENTS.md

@@ -8,11 +8,15 @@ DOCX editing and tooling. Renders, edits, and automates .docx files in the brows
 
 ## Install
 
+This file documents SuperDoc v2. Install it explicitly: for both `superdoc` and `@superdoc-dev/react`, the unqualified `latest` tag still resolves to v1.
+
 ```bash
-npm install superdoc           # vanilla JS, Vue, Angular, Svelte
-npm install @superdoc-dev/react  # React (includes superdoc)
+npm install superdoc@next             # vanilla JS, Vue, Angular, Svelte
+npm install @superdoc-dev/react@next  # React (includes superdoc)
 ```
 
+v2 is selected by the installed version. There is no `editorVersion` or `v2` config flag, and no runtime fallback to v1. If you are upgrading an existing v1 integration, note that v1 published 41 runtime exports from the package root and v2 publishes 10; see the "Knowledge corrections" section below for what changed.
+
 ## Embed editor — vanilla JS
 
 ```html
@@ -89,7 +93,9 @@ Key options for `new SuperDoc()` or `<SuperDocEditor>`:
 | `user` | `{ name, email }` | Current user (for comments/tracked changes) |
 | `toolbar` | `string \| HTMLElement` | Toolbar mount selector or element |
 | `modules.comments` | `object` | Comments panel configuration |
-| `modules.collaboration` | `object` | Real-time collaboration (Yjs) |
+| `document.v2Collaboration` | `object` | Real-time collaboration. v2 owns the provider and `Y.Doc`. |
+
+`modules.collaboration` is the v1 collaboration API. It still typechecks against the v2 config, but v2 refuses to attach the provider and fails closed. Collaboration is also a data migration, not a config change: v2 rooms use a different document format, so never point a v2 editor at an existing v1 room.
 
 Full config: https://docs.superdoc.dev/core/superdoc/configuration
 
@@ -246,7 +252,7 @@ painted output or reach into editor internals for coordinates.
 | Add comments (programmatic) | Use Document API: `editor.doc.comments.create({ target, text: 'comment body' })` |
 | Find and replace | Use Document API: `editor.doc.query.match(...)` then `editor.doc.replace(...)` |
 | Format text (programmatic) | Use Document API: `editor.doc.format.bold(...)`, `.italic(...)`, etc. |
-| Real-time collab | Configure `modules.collaboration` with a Yjs provider |
+| Real-time collab | Configure `document.v2Collaboration`; v2 owns the provider and `Y.Doc` |
 | Custom built-in toolbar | Use `modules.toolbar.customButtons` array |
 | 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[]` |
@@ -254,21 +260,31 @@ painted output or reach into editor internals for coordinates.
 
 ### Programmatic access (Document API)
 
-For reading and mutating documents programmatically, use the Document API (`editor.doc`). It provides 300+ stable operations. Direct access to ProseMirror internals (`editor.state`, `editor.view`) and editor commands (`editor.commands`) is deprecated and will be removed.
+For reading and mutating documents programmatically, use the Document API (`editor.doc`). It provides 300+ stable operations.
+
+`editor.state`, `editor.view`, and `editor.commands` are not v2 APIs. They are exposed as `null` rather than removed, so reading a property off one raises a generic null-property error that does not name SuperDoc, and optional chaining turns the same mistake into a silent no-op. There is no ProseMirror document model in v2: positions expressed as numeric offsets have no equivalent.
+
+In the browser the Document API is async. Await every call; a forgotten `await` yields a pending promise that reads as an empty or missing result.
 
 ```javascript
-superdoc.on('editorCreate', ({ editor }) => {
+superdoc.on('ready', async ({ superdoc }) => {
+  const doc = superdoc.activeEditor?.doc;
+  if (!doc) throw new Error('The active document is unavailable.');
+
   // Query document content
-  const result = editor.doc.query.match({ select: { type: 'text', pattern: 'ACME' } });
+  const result = await doc.query.match({ select: { type: 'text', pattern: 'ACME' }, require: 'any' });
+  if (!result.items.length) return;
 
   // Replace matched text
-  editor.doc.replace({ target: result.items[0].target, text: 'Globex' });
+  await doc.replace({ target: result.items[0].target, text: 'Globex' });
 
   // Add a comment
-  editor.doc.comments.create({ target: result.items[0].target, text: 'Updated name' });
+  await doc.comments.create({ target: result.items[0].target, text: 'Updated name' });
 });
 ```
 
+Use `require: 'any'` for speculative lookups where zero matches is normal. `require: 'all'` is a cardinality assertion and throws when the selector matches nothing.
+
 For backend or AI agent workflows, use the [SDK](https://docs.superdoc.dev/document-engine/sdks), [CLI](https://docs.superdoc.dev/document-engine/cli), or [MCP server](https://docs.superdoc.dev/document-engine/ai-agents/mcp-server) instead of browser editor access.
 
 ## Contributing to the public surface
@@ -299,13 +315,18 @@ If your training data mentions SuperDoc, note these updates:
 
 - **Product name** is SuperDoc (capital S, capital D). Never "Superdoc" or "Super Doc."
 - **Do not use python-docx** for DOCX editing when SuperDoc is available. Use the SuperDoc CLI, SDK, or MCP server instead — they preserve full document fidelity.
-- **`superdoc` is the npm package name**. The React wrapper is `@superdoc-dev/react`. The SDK is `@superdoc-dev/sdk`.
+- **`superdoc` is the npm package name**. The React wrapper is `@superdoc-dev/react`. The SDK is `@superdoc-dev/sdk`. For v2, install `superdoc@next` and `@superdoc-dev/react@next`: on both packages the `latest` tag still points at v1.
 - **Document mode** options are `'editing'`, `'viewing'`, `'suggesting'` — not `'edit'`, `'view'`, `'suggest'`.
 - **Always import the stylesheet**: `import 'superdoc/style.css'` (or `@superdoc-dev/react/style.css` for React).
 - **SuperDoc runs client-side only**. No server required for the editor. Backend operations use the SDK or CLI.
+- **v1 and v2 are different packages, not a flag.** `superdoc@1` exported 41 runtime values from the package root plus ten code subpaths; `superdoc@2` exports 10 values and three subpaths (`superdoc/ui`, `superdoc/ui/react`, `superdoc/collaboration-upgrade-engine`). `Editor`, `SuperConverter`, `DocxZipper`, `Extensions`, `defineNode`, `defineMark`, `SuperToolbar`, and the helper bags are gone. Do not suggest them for v2.
+- **v2 has no ProseMirror surface.** `editor.state`, `editor.view`, and `editor.commands` are `null`. Use `superdoc.activeEditor.doc` for document work and `superdoc.ui` for interface state. `superdoc.ui` is a getter on the instance that lazily creates and owns the controller; it returns `BorrowedSuperDocUI`, which omits `destroy()` because `superdoc.destroy()` owns teardown. Call `createSuperDocUI({ superdoc })` directly only when you need an independently owned controller to dispose yourself.
+- **`editorExtensions` is a v1 concept.** It still typechecks in v2 but never runs; SuperDoc logs a console warning naming the field. Use `extensions` with `defineSuperDocExtension`.
 
 ## Links
 
+These point at the currently published documentation site. The v2 documentation (including the full removed-in-v2 reference) is not deployed yet; update these paths in the same change that publishes it.
+
 - Quickstart: https://docs.superdoc.dev/getting-started/quickstart
 - React guide: https://docs.superdoc.dev/getting-started/frameworks/react
 - Document Engine: https://docs.superdoc.dev/document-engine/overview

package/dist/chunks/{create-super-doc-ui-BmtUtDDR.es.js → create-super-doc-ui-D4UDePxr.es.js}

@@ -1502,6 +1502,7 @@ function normalizeHostSelectionApplyResult(result) {
 	return { ok: true };
 }
 var HOST_EVENTS = [
+	"document-replaced",
 	"editorCreate",
 	"active-editor-change",
 	"document-mode-change",
@@ -1690,6 +1691,7 @@ function readEntityStory(row) {
 	const address = record.address && typeof record.address === "object" ? record.address : null;
 	if (address?.story && typeof address.story === "object") return address.story;
 	if (record.storyLocator && typeof record.storyLocator === "object") return record.storyLocator;
+	if (record.trackedChangeStory && typeof record.trackedChangeStory === "object") return record.trackedChangeStory;
 	const target = readEntityTarget(row);
 	if (!target || typeof target !== "object") return null;
 	const targetRecord = target;
@@ -3174,7 +3176,9 @@ function createSuperDocUI(options) {
 				unresolvedIds: []
 			};
 			const settledTrackChanges = asyncReads.get("trackChanges");
-			const cachedIds = new Set(settledTrackChanges?.hasSettled && Array.isArray(settledTrackChanges.value) ? settledTrackChanges.value.map(readEntityId).filter((id) => id != null) : []);
+			const settledTrackChangeItems = settledTrackChanges?.hasSettled && Array.isArray(settledTrackChanges.value) ? settledTrackChanges.value : null;
+			const cachedIds = new Set(settledTrackChangeItems ? settledTrackChangeItems.map(readEntityId).filter((id) => id != null) : []);
+			const settledCatalogIsProvenEmpty = settledTrackChangeItems?.length === 0 && hostSourceLoadPhase() === "complete";
 			const idsNeedingPlacement = new Set(requestedIds.filter((id) => !cachedIds.has(id)));
 			const getTrackedChange = context.v2TrackedChanges?.getTrackedChange;
 			const getRawTrackedChange = context.docTrackChanges?.get;
@@ -3226,7 +3230,7 @@ function createSuperDocUI(options) {
 			}
 			let orderedItems;
 			const placementIds = resolvedIds.filter((id) => idsNeedingPlacement.has(id));
-			if (placementIds.length > 0) {
+			if (placementIds.length > 0 && !settledCatalogIsProvenEmpty) {
 				const orderResult = await hydrateTrackedChanges(context, {
 					trackedChangesListMode: "interaction-prime",
 					refreshReason: "mutation-render-reconcile",
@@ -3771,9 +3775,19 @@ function createSuperDocUI(options) {
 		return fromRuntime ?? fromConfig ?? fromOptions;
 	};
 	const commentsReadOnlyForReview = () => {
-		const comments$1 = (((superdoc && typeof superdoc === "object" ? superdoc : null)?.config)?.modules)?.comments;
+		const superdocRecord = superdoc && typeof superdoc === "object" ? superdoc : null;
+		const resolved = (superdocRecord?.interactionConfig)?.comments;
+		if (resolved && typeof resolved.readOnly === "boolean") return resolved.readOnly === true;
+		const comments$1 = ((superdocRecord?.config)?.modules)?.comments;
 		return !!comments$1 && typeof comments$1 === "object" && comments$1.readOnly === true;
 	};
+	const resolveIsForbidden = () => {
+		const superdocRecord = superdoc && typeof superdoc === "object" ? superdoc : null;
+		const resolved = (superdocRecord?.interactionConfig)?.comments;
+		if (resolved && typeof resolved.allowResolve === "boolean") return resolved.allowResolve === false;
+		const comments$1 = ((superdocRecord?.config)?.modules)?.comments;
+		return !!comments$1 && typeof comments$1 === "object" && comments$1.allowResolve === false;
+	};
 	const reviewMutationsAreReadOnly = () => readDocumentMode() === "viewing" || commentsReadOnlyForReview();
 	const normalizeSelectionInfo = (raw) => raw && typeof raw === "object" ? raw : null;
 	const selectionSliceFromInfo = (info, status) => {
@@ -3925,7 +3939,7 @@ function createSuperDocUI(options) {
 		} : readAsync("trackChanges", token, () => {
 			if (listTrackedChanges) return listTrackedChanges.call(v2TrackedChanges);
 			return tcApi?.list ? tcApi.list() : void 0;
-		}, (raw) => raw && Array.isArray(raw.items) ? raw.items : []);
+		}, (raw) => raw && Array.isArray(raw.items) ? raw.items.filter((item) => !listTrackedChanges || storyLocatorSignature(readEntityStory(item)) === "story:body") : []);
 		const items = (value ?? []).map(projectTrackChangesItem).filter((item) => item != null).filter((item) => {
 			const id = readEntityId(item);
 			return !id || !postDecisionIds?.has(id);
@@ -5602,7 +5616,10 @@ function createSuperDocUI(options) {
 		if (typeof review.getSnapshot === "function") return safeCall(() => review.getSnapshot(), null)?.activeReviewTarget ?? null;
 		return null;
 	};
-	const syncTrackedChangeFocusFromHostReviewTarget = (rawTarget) => {
+	let trackedChangeNavigationInFlight = 0;
+	const syncTrackedChangeFocusFromHostReviewTarget = (rawTarget, rawSnapshot) => {
+		const rejection = (rawSnapshot && typeof rawSnapshot === "object" ? rawSnapshot : null)?.lastInteractionRejection;
+		if (trackedChangeNavigationInFlight > 0 && rawTarget == null && rejection && typeof rejection === "object" && rejection.code === "review-target-invalidated" && rejection.detail === "not-painted") return false;
 		const target = rawTarget && typeof rawTarget === "object" ? rawTarget : null;
 		let next = null;
 		if (target?.entityType === "trackedChange" && typeof target.entityId === "string" && target.entityId.length > 0) {
@@ -5633,7 +5650,7 @@ function createSuperDocUI(options) {
 		try {
 			const unsubscribe = next.subscribe((snapshot) => {
 				const snapshotRecord = snapshot && typeof snapshot === "object" ? snapshot : null;
-				if (!syncTrackedChangeFocusFromHostReviewTarget(snapshotRecord && Object.prototype.hasOwnProperty.call(snapshotRecord, "activeReviewTarget") ? snapshotRecord.activeReviewTarget : readHostActiveReviewTarget(next)) || attaching) return;
+				if (!syncTrackedChangeFocusFromHostReviewTarget(snapshotRecord && Object.prototype.hasOwnProperty.call(snapshotRecord, "activeReviewTarget") ? snapshotRecord.activeReviewTarget : readHostActiveReviewTarget(next), snapshot) || attaching) return;
 				recompute();
 			});
 			if (typeof unsubscribe === "function") detachHostReview = unsubscribe;
@@ -5767,17 +5784,32 @@ function createSuperDocUI(options) {
 		for (const listener of [...listeners]) listener(state);
 	};
 	const activeEditorResetHooks = [];
-	const runActiveEditorResetHooks = () => {
-		for (const reset of activeEditorResetHooks) try {
+	const documentResetHooks = [];
+	const runHooks = (hooks) => {
+		for (const reset of hooks) try {
 			reset();
 		} catch {}
 	};
+	const runActiveEditorResetHooks = () => runHooks(activeEditorResetHooks);
+	const runDocumentResetHooks = () => runHooks(documentResetHooks);
 	const detachers = [];
 	const attach = (source, events) => {
 		if (!source || typeof source.on !== "function") return;
 		for (const event of events) {
 			const handler = event === "active-editor-change" ? () => {
 				runActiveEditorResetHooks();
+				runDocumentResetHooks();
+				recompute();
+			} : event === "document-replaced" ? (payload) => {
+				const detail = payload && typeof payload === "object" ? payload : null;
+				const replacedEditor = detail?.["editor"];
+				const replacedHost = detail?.["host"];
+				const matchesEditor = Boolean(replacedEditor) && replacedEditor === getEditor();
+				const matchesHost = Boolean(replacedHost) && replacedHost === getHost();
+				if (!matchesEditor && !matchesHost) return;
+				runDocumentResetHooks();
+				asyncReads.clear();
+				invalidateDocumentContent();
 				recompute();
 			} : () => recompute();
 			try {
@@ -7495,6 +7527,8 @@ function createSuperDocUI(options) {
 		}
 	};
 	function patchCommentStatus(commentId, status) {
+		if (reviewMutationsAreReadOnly()) return failedReceipt("Comments are read-only.", "DOCUMENT_READONLY");
+		if (resolveIsForbidden()) return failedReceipt("Resolving comments is disabled.", "DOCUMENT_READONLY");
 		const commentsApi = getDoc()?.comments;
 		const op = commentsApi?.patch;
 		if (typeof op !== "function") return failedReceipt("comments.patch is unavailable.");
@@ -7504,6 +7538,7 @@ function createSuperDocUI(options) {
 			status
 		}), fallback), fallback);
 	}
+	const commentWriteRefusal = () => reviewMutationsAreReadOnly() ? failedReceipt("Comments are read-only.", "DOCUMENT_READONLY") : null;
 	const filterCommentsSnapshot = (items, query) => {
 		const record = query && typeof query === "object" ? query : null;
 		let filtered = Array.from(items);
@@ -7537,6 +7572,8 @@ function createSuperDocUI(options) {
 			return isPromiseLike(result) ? null : result;
 		},
 		createFromCapture: (capture, input) => {
+			const refusal = commentWriteRefusal();
+			if (refusal) return refusal;
 			const commentsApi = getDoc()?.comments;
 			const op = commentsApi?.create;
 			if (typeof op !== "function") return failedReceipt("comments.create is unavailable.");
@@ -7547,6 +7584,8 @@ function createSuperDocUI(options) {
 			}), fallback), fallback);
 		},
 		createFromSelection: (input) => {
+			const refusal = commentWriteRefusal();
+			if (refusal) return refusal;
 			const commentsApi = getDoc()?.comments;
 			const op = commentsApi?.create;
 			if (typeof op !== "function") return failedReceipt("comments.create is unavailable.");
@@ -7560,6 +7599,8 @@ function createSuperDocUI(options) {
 			}), fallback), fallback);
 		},
 		reply: (commentId, input) => {
+			const refusal = commentWriteRefusal();
+			if (refusal) return refusal;
 			const commentsApi = getDoc()?.comments;
 			const op = commentsApi?.reply ?? commentsApi?.create;
 			if (typeof op !== "function") return failedReceipt("comments.reply is unavailable.");
@@ -7575,6 +7616,8 @@ function createSuperDocUI(options) {
 		resolve: (commentId) => patchCommentStatus(commentId, "resolved"),
 		reopen: (commentId) => patchCommentStatus(commentId, "active"),
 		delete: (commentId) => {
+			const refusal = commentWriteRefusal();
+			if (refusal) return refusal;
 			const commentsApi = getDoc()?.comments;
 			const op = commentsApi?.delete ?? commentsApi?.remove;
 			if (typeof op !== "function") return failedReceipt("comments.delete is unavailable.");
@@ -7654,10 +7697,22 @@ function createSuperDocUI(options) {
 			rollback();
 			return { success: false };
 		}
-		const result = await scrollTargetIntoView(target, { behavior: "auto" });
-		if (!isCurrent()) return { success: false };
-		if (!result.ok && result.reason !== SUPERDOC_UI_REASONS.targetNotVisible) rollback();
-		return { success: result.ok };
+		trackedChangeNavigationInFlight += 1;
+		try {
+			const result = await scrollTargetIntoView(target, { behavior: "auto" });
+			if (!isCurrent()) return { success: false };
+			if (!result.ok && result.reason !== SUPERDOC_UI_REASONS.targetNotVisible) {
+				rollback();
+				mirrorTrackedChangeFocusToHost(previousActiveChange);
+			} else mirrorTrackedChangeFocusToHost(optimisticActiveChange);
+			return { success: result.ok };
+		} finally {
+			trackedChangeNavigationInFlight = Math.max(0, trackedChangeNavigationInFlight - 1);
+			if (trackedChangeNavigationInFlight === 0) {
+				if (!isCurrent()) mirrorTrackedChangeFocusToHost(explicitActiveChange);
+				else if (currentHostReviewSource) syncTrackedChangeFocusFromHostReviewTarget(readHostActiveReviewTarget(currentHostReviewSource));
+			}
+		}
 	};
 	const navigateAndScroll = (step) => {
 		const run = navigateAndScrollNow(step);
@@ -7781,14 +7836,25 @@ function createSuperDocUI(options) {
 				setExplicitActiveChange(previousActiveChange, { invalidateQueuedNavigation: false });
 				recompute();
 			};
-			const result = await scrollTargetIntoView(target, { behavior: "auto" });
-			if (!isCurrent()) return {
-				success: false,
-				ok: false
-			};
-			if (!result.ok && result.reason !== SUPERDOC_UI_REASONS.targetNotVisible) rollback();
-			else mirrorTrackedChangeFocusToHost(requestedActiveChange);
-			return result;
+			trackedChangeNavigationInFlight += 1;
+			try {
+				const result = await scrollTargetIntoView(target, { behavior: "auto" });
+				if (!isCurrent()) return {
+					success: false,
+					ok: false
+				};
+				if (!result.ok && result.reason !== SUPERDOC_UI_REASONS.targetNotVisible) {
+					rollback();
+					mirrorTrackedChangeFocusToHost(previousActiveChange);
+				} else mirrorTrackedChangeFocusToHost(requestedActiveChange);
+				return result;
+			} finally {
+				trackedChangeNavigationInFlight = Math.max(0, trackedChangeNavigationInFlight - 1);
+				if (trackedChangeNavigationInFlight === 0) {
+					if (!isCurrent()) mirrorTrackedChangeFocusToHost(explicitActiveChange);
+					else if (currentHostReviewSource) syncTrackedChangeFocusFromHostReviewTarget(readHostActiveReviewTarget(currentHostReviewSource));
+				}
+			}
 		}
 	};
 	const executeTrackDecision = (kind, input) => {
@@ -8085,21 +8151,50 @@ function createSuperDocUI(options) {
 		return null;
 	}
 	const geometryObservers = /* @__PURE__ */ new Set();
+	let geometryReleaseScheduled = false;
 	const bindGeometryObserver = (entry) => {
 		const host = getHost();
 		if (typeof host?.observeGeometry !== "function") return;
-		const off = safeCall(() => host.observeGeometry(() => entry.schedule()), null);
+		let subscribed = false;
+		const off = safeCall(() => {
+			const result = host.observeGeometry(() => entry.schedule());
+			subscribed = true;
+			return result;
+		}, null);
 		entry.detach = typeof off === "function" ? off : null;
+		entry.boundHost = subscribed ? host : null;
 	};
 	const detachGeometryObserver = (entry) => {
-		if (!entry.detach) return;
-		try {
-			entry.detach();
-		} catch {}
-		entry.detach = null;
+		if (entry.detach) {
+			try {
+				entry.detach();
+			} catch {}
+			entry.detach = null;
+		}
+		entry.boundHost = null;
+	};
+	const releaseGeometryObserversIfStillHostless = () => {
+		geometryReleaseScheduled = false;
+		if (disposed || getHost()) return;
+		for (const entry of geometryObservers) detachGeometryObserver(entry);
+	};
+	const scheduleGeometryRelease = () => {
+		if (geometryReleaseScheduled) return;
+		geometryReleaseScheduled = true;
+		if (typeof queueMicrotask === "function") {
+			queueMicrotask(releaseGeometryObserversIfStillHostless);
+			return;
+		}
+		Promise.resolve().then(releaseGeometryObserversIfStillHostless);
 	};
 	const rebindGeometryObservers = () => {
+		const host = getHost();
+		if (!host) {
+			scheduleGeometryRelease();
+			return;
+		}
 		for (const entry of geometryObservers) {
+			if (entry.boundHost && entry.boundHost === host) continue;
 			detachGeometryObserver(entry);
 			bindGeometryObserver(entry);
 			entry.schedule();
@@ -8143,7 +8238,8 @@ function createSuperDocUI(options) {
 			unsubs.push(sub.subscribe(() => schedule()));
 			const entry = {
 				schedule,
-				detach: null
+				detach: null,
+				boundHost: null
 			};
 			bindGeometryObserver(entry);
 			geometryObservers.add(entry);
@@ -8344,7 +8440,7 @@ function createSuperDocUI(options) {
 		};
 		emitSearch();
 	};
-	activeEditorResetHooks.push(resetSearchForActiveEditorChange);
+	documentResetHooks.push(resetSearchForActiveEditorChange);
 	const readSearchQueryError = (record) => {
 		if (!record) return false;
 		const queryError = record.queryError;
@@ -8877,6 +8973,8 @@ function createSuperDocUI(options) {
 		if (detachDocumentSelection) detachDocumentSelection();
 		detachDocumentSelection = null;
 		currentDocumentSelectionSource = null;
+		for (const entry of geometryObservers) detachGeometryObserver(entry);
+		geometryObservers.clear();
 		listeners.clear();
 		searchListeners.clear();
 		painterCaptureEpoch += 1;