superdoc 2.4.0 → 2.5.0

package/README.md

@@ -1,106 +1,28 @@
-# SuperDoc
+# superdoc
 
-> The document engine for DOCX files.
+Browser editor for opening, editing, and rendering DOCX files.
 
-[![Documentation](https://img.shields.io/badge/docs-available-1355ff.svg)](https://docs.superdoc.dev/)
-[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-1355ff.svg)](https://www.gnu.org/licenses/agpl-3.0)
-[![npm version](https://img.shields.io/npm/v/superdoc.svg?color=1355ff)](https://www.npmjs.com/package/superdoc)
-[![codecov](https://codecov.io/gh/superdoc/docx-editor/branch/main/graph/badge.svg)](https://codecov.io/gh/superdoc/docx-editor)
-[![Discord](https://img.shields.io/badge/discord-join-1355ff)](https://discord.com/invite/b9UuaZRyaB)
-
-SuperDoc renders and edits DOCX files in the browser. Built on OOXML — not bolted onto HTML. As you type, you write directly to the XML. Import a document, edit it, export it. Nothing lost.
-
-## Features
-
-- **Real DOCX, not rich text** — Built on OOXML. Real pagination, section breaks, headers/footers, complex tables. Not a contenteditable wrapper with export bolted on.
-- **Self-hosted** — Runs entirely in the browser. Your documents never leave your servers.
-- **Any framework** — React, Vue, Angular, Svelte, vanilla JS. One component, zero lock-in.
-- **Real-time collaboration** — Yjs-based CRDT. Multiplayer editing with comments, tracked changes, and automatic conflict resolution.
-- **Built for agents** — [SDK](https://www.npmjs.com/package/@superdoc-dev/sdk), [CLI](https://www.npmjs.com/package/@superdoc-dev/cli), and [MCP server](https://www.npmjs.com/package/@superdoc-dev/mcp) let LLMs read, edit, and save .docx files programmatically.
-- **Dual licensed** — AGPLv3 for community use. [Commercial license](https://www.superdocportal.dev/get-in-touch) for proprietary deployments.
-
-## Quick start
+## Install
 
 ```bash
 npm install superdoc
 ```
 
-```javascript
-import 'superdoc/style.css';
-import { SuperDoc } from 'superdoc';
-
-const superdoc = new SuperDoc({
-  selector: '#superdoc',
-  documentMode: 'editing',
-  documents: [
-    {
-      id: 'my-doc-id',
-      type: 'docx',
-      data: fileObject,
-    },
-  ],
-});
-```
-
-Supported document modes are `editing`, `viewing`, and `suggesting`. Do not use `edit`, `view`, or `suggest`.
-
-### Browser Document API contract
-
-`superdoc.activeEditor.doc` is the browser-facing v2 Document API facade. In the
-browser it is intentionally async-capable, so custom UI code must tolerate
-promise-returning reads and writes, including the default worker-backed runtime.
-SDK/headless document-automation surfaces remain synchronous; this async
-contract is specific to the browser `superdoc` package.
-
-### Vanilla wrapper for a DOCX file
-
-When an agent needs to create a small vanilla JS wrapper around a DOCX `File`, use this shape:
+## Quick start
 
-```javascript
+```js
 import { SuperDoc } from 'superdoc';
 import 'superdoc/style.css';
 
-export function embedSuperDoc({ file }) {
-  return new SuperDoc({
-    selector: '#editor',
-    documentMode: 'editing',
-    documents: [
-      {
-        id: 'contract',
-        type: 'docx',
-        data: file,
-      },
-    ],
-  });
-}
-```
-
-For React, Vue, and other frameworks, see the [documentation](https://docs.superdoc.dev).
-
-### Using an AI coding agent?
-
-```bash
-claude mcp add superdoc -- npx @superdoc-dev/mcp   # connect agent to DOCX files
+const editor = new SuperDoc({
+  selector: '#editor',
+  document: '/document.docx',
+});
 ```
 
-## Documentation
-
-[docs.superdoc.dev](https://docs.superdoc.dev) — installation, integration guides, collaboration setup, API reference, and more.
-
-## Contributing
-
-Check the [issue tracker](https://github.com/superdoc/docx-editor/issues) for open issues, or read the [Contributing Guide](../../CONTRIBUTING.md) to get started. Bug reports with reproduction .docx files are especially valuable.
-
-## Community
-
-- [Discord](https://discord.com/invite/b9UuaZRyaB) — Chat with the team and other contributors
-- [Email](mailto:q@superdoc.dev) — Reach the team directly
+See the [editor quick start](https://docs.superdoc.dev/editor/quickstart) for a complete example and the
+[SuperDoc documentation](https://docs.superdoc.dev) for configuration and APIs.
 
 ## License
 
-- Open source: [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0.html)
-- Commercial: [Enterprise License](https://www.superdocportal.dev/get-in-touch)
-
----
-
-Created and maintained by [Harbour](https://www.superdoc.dev) and the SuperDoc community.
+AGPL-3.0. Commercial licenses are available from [SuperDoc](https://www.superdoc.dev).

package/dist/chunks/{create-super-doc-ui-CqGmoMMA.cjs → create-super-doc-ui-Bom7oDPv.cjs}

@@ -13,6 +13,8 @@ var DOM_CLASS_NAMES = {
 	PAGE: "superdoc-page",
 	/** Fragment container (paragraph, table, image block, etc.). */
 	FRAGMENT: "superdoc-fragment",
+	/** Non-flowing fragment whose visual position must not define body flow geometry. */
+	FLOATING_FRAGMENT: "superdoc-floating-fragment",
 	/** Line container within a fragment. */
 	LINE: "superdoc-line",
 	/**
@@ -614,7 +616,6 @@ var SUPERDOC_UI_REASONS = {
 * No descriptor imports a v1 editor internal or a private v2 runtime package,
 * and no routed command mutates while the document is read-only / viewing.
 *
-* See `docs/architecture/custom-ui-command-matrix.md` for the per-id matrix.
 */
 /**
 * The 14 canonical v2-native command ids. These are the historically stable
@@ -1873,6 +1874,23 @@ INLINE_PROPERTY_REGISTRY.filter((entry) => entry.storage === "mark").map((entry)
 * `false` when the surface is unavailable (view mode, a pre-ready editor, or a
 * host that has not exposed a Document API facade) rather than throwing.
 */
+function uiBenchNowMs() {
+	return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+function readUiBenchRuntime() {
+	const benchGlobal = globalThis;
+	return {
+		sink: typeof benchGlobal.__superdocV2BenchPipelineTiming === "function" ? benchGlobal.__superdocV2BenchPipelineTiming : null,
+		workerContext: benchGlobal.__superdocV2BenchWorkerMessageContext ?? null
+	};
+}
+function emitUiBenchTiming(event) {
+	const { sink } = readUiBenchRuntime();
+	if (!sink) return;
+	try {
+		sink(event);
+	} catch {}
+}
 var sharedUiTrackedChangesCatalogByHost = /* @__PURE__ */ new WeakMap();
 function acquireSharedUiTrackedChangesCatalog(host) {
 	let state = sharedUiTrackedChangesCatalogByHost.get(host);
@@ -3702,6 +3720,7 @@ function createSuperDocUI(options) {
 		if (options?.invalidateQueuedNavigation !== false) queuedTrackChangeNavigationInvalidation += 1;
 	};
 	const listeners = /* @__PURE__ */ new Set();
+	let state;
 	let disposed = false;
 	let controllerRef = null;
 	const asyncReads = /* @__PURE__ */ new Map();
@@ -3714,12 +3733,13 @@ function createSuperDocUI(options) {
 	let foregroundAsyncRetryTimer = null;
 	let pendingSelectionSeedValidationToken = null;
 	let typingContentInvalidationTimer = null;
+	const pendingAsyncReadSettlements = [];
 	const scheduleAsyncRefresh = () => {
 		if (asyncRefreshScheduled || disposed) return;
 		asyncRefreshScheduled = true;
 		const run = () => {
 			asyncRefreshScheduled = false;
-			if (!disposed) recompute();
+			if (!disposed) recompute("async-read-settled");
 		};
 		if (typeof queueMicrotask === "function") queueMicrotask(run);
 		else Promise.resolve().then(run);
@@ -4273,6 +4293,24 @@ function createSuperDocUI(options) {
 				failureCount: 0,
 				retryAtMs: 0
 			});
+			const { sink, workerContext } = readUiBenchRuntime();
+			if (sink) {
+				const settledAtMs = uiBenchNowMs();
+				pendingAsyncReadSettlements.push({
+					key,
+					settledAtMs,
+					commandId: workerContext?.commandId ?? null,
+					commandKind: workerContext?.commandKind ?? null
+				});
+				emitUiBenchTiming({
+					stage: "superdoc-ui-async-read-settled",
+					atMs: settledAtMs,
+					key,
+					settledAtMs,
+					commandId: workerContext?.commandId ?? null,
+					commandKind: workerContext?.commandKind ?? null
+				});
+			}
 			scheduleAsyncRefresh();
 		}, () => {
 			const entry = asyncReads.get(key);
@@ -6533,31 +6571,57 @@ function createSuperDocUI(options) {
 			diagnostics
 		};
 	};
-	const computeState = () => {
-		const documentMode = readDocumentMode();
-		const selection = computeSelection();
+	const computeState = (reason = "direct") => {
+		const { sink } = readUiBenchRuntime();
+		const startedAtMs = sink ? uiBenchNowMs() : 0;
+		const phaseMs = {};
+		const measure = (phase, run) => {
+			if (!sink) return run();
+			const phaseStartedAtMs = uiBenchNowMs();
+			try {
+				return run();
+			} finally {
+				phaseMs[phase] = uiBenchNowMs() - phaseStartedAtMs;
+			}
+		};
+		const documentMode = measure("documentMode", readDocumentMode);
+		const selection = measure("selection", computeSelection);
 		if (selection.status === "ready") pruneSelectionScopedAsyncReads(selection);
 		reconcilePendingInlineFormat(selection);
 		const selectionSignature = selectionInlineValueSignature(selection);
 		for (const [commandId, optimistic] of optimisticInlineToggles) if (!selectionSignature || optimistic.selectionSignature !== selectionSignature) optimisticInlineToggles.delete(commandId);
 		else if (optimistic.settled && selection.status === "ready") optimisticInlineToggles.delete(commandId);
-		return {
+		const nextState = {
 			ready: getEditor() != null,
 			documentMode,
-			document: computeDocument(),
+			document: measure("document", computeDocument),
 			selection,
 			toolbar: {
 				context: documentMode,
-				commands: computeCommandStates(selection),
+				commands: measure("toolbarCommands", () => computeCommandStates(selection)),
 				copyFormatActive: painter.mode !== "idle"
 			},
-			comments: computeComments(selection),
-			trackChanges: computeTrackChanges(selection),
-			contentControls: computeContentControls(selection),
-			zoom: computeZoom(),
-			fonts: computeFonts(),
-			styles: computeStyles(selection)
-		};
+			comments: measure("comments", () => computeComments(selection)),
+			trackChanges: measure("trackChanges", () => computeTrackChanges(selection)),
+			contentControls: measure("contentControls", () => computeContentControls(selection)),
+			zoom: measure("zoom", computeZoom),
+			fonts: measure("fonts", computeFonts),
+			styles: measure("styles", () => computeStyles(selection))
+		};
+		if (sink) {
+			const completedAtMs = uiBenchNowMs();
+			emitUiBenchTiming({
+				stage: "superdoc-ui-compute-state",
+				atMs: completedAtMs,
+				reason,
+				startedAtMs,
+				completedAtMs,
+				durationMs: completedAtMs - startedAtMs,
+				phaseMs,
+				asyncReadSettlements: pendingAsyncReadSettlements.splice(0)
+			});
+		}
+		return nextState;
 	};
 	const syncOptimisticInlineSelection = (selection) => {
 		const nextSignature = selectionInlineValueSignature(selection);
@@ -6642,7 +6706,7 @@ function createSuperDocUI(options) {
 			const unsubscribe = next.subscribe((snapshot) => {
 				selectionEpoch += 1;
 				seedCaretSelectionFromHost(snapshot);
-				recompute();
+				recompute("host-selection");
 			});
 			if (typeof unsubscribe === "function") detachHostSelection = unsubscribe;
 		} catch {
@@ -6667,15 +6731,24 @@ function createSuperDocUI(options) {
 		const target = rawTarget && typeof rawTarget === "object" ? rawTarget : null;
 		let next = null;
 		if (target?.entityType === "trackedChange" && typeof target.entityId === "string" && target.entityId.length > 0) {
-			const paintedEntityId = target.entityId;
 			const targetStory = target.story && typeof target.story === "object" ? target.story : void 0;
-			const allStoryItems = readAllStoryTrackChanges();
-			const entityId = (allStoryItems ? targetStory ? buildStoryScopedTrackedChangeIdContext(allStoryItems, targetStory).toPublicId(paintedEntityId) : buildTrackedChangeIdContext(allStoryItems).toPublicId(paintedEntityId) : null) ?? paintedEntityId;
 			const story = targetStory && storyLocatorSignature(targetStory) !== storyLocatorSignature(null) ? targetStory : void 0;
+			const rawPaintedEntityId = typeof target.paintedEntityId === "string" && target.paintedEntityId.length > 0 ? target.paintedEntityId : null;
+			const lookupEntityId = rawPaintedEntityId ?? target.entityId;
+			const publicId = (() => {
+				if (story) {
+					const allStoryItems = readAllStoryTrackChanges();
+					const storyContext = allStoryItems ? buildStoryScopedTrackedChangeIdContext(allStoryItems, story) : null;
+					return storyContext?.toPublicId(lookupEntityId) ?? storyContext?.toPublicId(target.entityId) ?? target.entityId;
+				}
+				const bodyContext = buildTrackedChangeIdContext(Array.isArray(state?.trackChanges.items) ? state.trackChanges.items : []);
+				return bodyContext.toPublicId(lookupEntityId) ?? bodyContext.toPublicId(target.entityId) ?? target.entityId;
+			})();
+			const paintedEntityId = rawPaintedEntityId ?? (lookupEntityId !== publicId ? lookupEntityId : null);
 			next = {
-				id: entityId,
+				id: publicId,
 				...story ? { story } : {},
-				...typeof target.paintedEntityId === "string" && target.paintedEntityId.length > 0 ? { paintedEntityId: target.paintedEntityId } : entityId !== paintedEntityId ? { paintedEntityId } : {}
+				...paintedEntityId && paintedEntityId !== publicId ? { paintedEntityId } : {}
 			};
 		}
 		if (rawTarget == null && next == null && explicitActiveChange != null && hasPendingTrackChangeRevealFocus(explicitActiveChange)) return false;
@@ -6741,7 +6814,7 @@ function createSuperDocUI(options) {
 	};
 	syncCoordinatorEditor();
 	syncTrackedChangeFocusFromHostReviewTarget(readHostActiveReviewTarget(readHostReviewSource()));
-	let state = computeState();
+	state = computeState("initial");
 	lastOptimisticInlineSelectionSignature = selectionInlineValueSignature(state.selection);
 	const syncHostEventsSubscription = () => {
 		const events = (getEditor()?.host)?.events;
@@ -6809,8 +6882,10 @@ function createSuperDocUI(options) {
 			currentHostEventsSource = null;
 		}
 	};
-	const recompute = () => {
+	const recompute = (reason = "unspecified") => {
 		if (disposed) return;
+		const { sink } = readUiBenchRuntime();
+		const startedAtMs = sink ? uiBenchNowMs() : 0;
 		editCommandsRecomputeQueued = false;
 		syncCoordinatorEditor();
 		syncHostSelectionSubscription();
@@ -6819,10 +6894,36 @@ function createSuperDocUI(options) {
 		syncHostReviewSubscription();
 		syncDocumentSelectionFallbackSubscription();
 		syncHostEventsSubscription();
-		const nextState = computeState();
+		const nextState = computeState(reason);
 		syncOptimisticInlineSelection(nextState.selection);
 		state = nextState;
-		for (const listener of [...listeners]) listener(state);
+		let listenerTotalMs = 0;
+		let listenerMaxMs = 0;
+		for (const listener of [...listeners]) {
+			if (!sink) {
+				listener(state);
+				continue;
+			}
+			const listenerStartedAtMs = uiBenchNowMs();
+			listener(state);
+			const listenerMs = uiBenchNowMs() - listenerStartedAtMs;
+			listenerTotalMs += listenerMs;
+			listenerMaxMs = Math.max(listenerMaxMs, listenerMs);
+		}
+		if (sink) {
+			const completedAtMs = uiBenchNowMs();
+			emitUiBenchTiming({
+				stage: "superdoc-ui-recompute",
+				atMs: completedAtMs,
+				reason,
+				startedAtMs,
+				completedAtMs,
+				durationMs: completedAtMs - startedAtMs,
+				listenerCount: listeners.size,
+				listenerTotalMs,
+				listenerMaxMs
+			});
+		}
 	};
 	/**
 	* Work that is bound to one specific active editor and cannot survive a swap.
@@ -7412,7 +7513,7 @@ function createSuperDocUI(options) {
 		if (options && options.success === false) return options;
 		if (!selection.selectionTarget) return options ? op(input, options) : op(input);
 		return op(input, {
-			...options ?? {},
+			...options,
 			offsetSpace: "selection"
 		});
 	};
@@ -8743,6 +8844,66 @@ function createSuperDocUI(options) {
 		}
 	};
 	/**
+	* Derive the browser-shell's `importedId` carrier-lookup alias from a
+	* public list row's `wordRevisionIds` / `sourceIds` provenance fields,
+	* mirroring `create-v2-tracked-changes-adapter.js`'s own derivation
+	* (`wordRevisionIds.insert ?? .delete ?? .format ?? sourceIds.wordIdInsert
+	* ?? .wordIdDelete ?? .wordIdOther[0]`). A carrier imported from a legacy
+	* Word revision id is painted with THIS id, not the canonical public id —
+	* `focusTrackedChange`'s carrier lookup only tries it when explicitly
+	* passed as `importedId` on an object input (see `scrollTrackChangeIntoView`).
+	*/
+	const deriveTrackedChangeImportedId = (row) => {
+		if (!row || typeof row !== "object") return null;
+		const record = row;
+		const wordRevisionIds = record.wordRevisionIds && typeof record.wordRevisionIds === "object" ? record.wordRevisionIds : null;
+		const sourceIds = record.sourceIds && typeof record.sourceIds === "object" ? record.sourceIds : null;
+		const wordIdOther = Array.isArray(sourceIds?.wordIdOther) ? sourceIds.wordIdOther : void 0;
+		const candidate = wordRevisionIds?.insert ?? wordRevisionIds?.delete ?? wordRevisionIds?.format ?? sourceIds?.wordIdInsert ?? sourceIds?.wordIdDelete ?? wordIdOther?.[0];
+		return typeof candidate === "string" && candidate.length > 0 ? candidate : null;
+	};
+	/**
+	* Scroll a tracked-change target into view, falling back to the v2
+	* browser-shell's `focusTrackedChange` (the same mechanism the built-in
+	* comments/tracked-changes sidebar uses via `CommentDialog.vue`'s
+	* `setFocus`) when the shared host geometry path can't resolve the target.
+	* The host's `normalizeGeometryTarget` only understands `text`/`replacement`
+	* targets (enriched with painted `segments`) and never `structural`/
+	* `formatting` targets, so those always fail the primary path and need this
+	* fallback.
+	*
+	* `story`, when present, is threaded into the fallback input as
+	* `trackedChangeStory` — a bare id always resolves to the body story in
+	* `focusTrackedChange`'s target resolver, which would collapse a non-body
+	* (footnote/header/footer) occurrence onto its body counterpart sharing the
+	* same raw id. `importedId`, when present, is threaded in too: the carrier
+	* lookup (`buildTrackChangeCarrierLookupIds`) tries it as an ADDITIONAL alias
+	* alongside the canonical id, for rows whose painted carrier only matches
+	* through a legacy-imported Word revision id, not the canonical public id
+	* (`create-v2-tracked-changes-adapter.test.js` pins this alias path as
+	* necessary for some rows).
+	*/
+	const scrollTrackChangeIntoView = async (changeId, target, story, importedId, options) => {
+		const primary = await scrollTargetIntoView(target, options);
+		if (primary.ok) return primary;
+		const trackedChanges = getV2TrackedChanges();
+		const focusTrackedChange = trackedChanges?.focusTrackedChange;
+		if (typeof focusTrackedChange !== "function") return primary;
+		const fallbackInput = story || importedId ? {
+			commentId: changeId,
+			...story ? { trackedChangeStory: story } : {},
+			...importedId ? { importedId } : {}
+		} : changeId;
+		try {
+			const fallbackResult = await Promise.resolve(focusTrackedChange.call(trackedChanges, fallbackInput));
+			if (fallbackResult && typeof fallbackResult === "object" && fallbackResult.ok === true) return {
+				success: true,
+				ok: true
+			};
+		} catch {}
+		return primary;
+	};
+	/**
 	* Resolve a document entity (comment / tracked change) to its anchor target.
 	* Prefers the already-loaded list row, falling back to a live `get({ id })`
 	* read when the list does not carry the row.
@@ -9004,9 +9165,11 @@ function createSuperDocUI(options) {
 				rollback();
 				return { success: false };
 			}
+			const activeRow = trackChangesSub.get().items.find((item) => entityRowMatchesRequest(item, activeId, optimisticActiveChange?.story)) ?? trackChangesSub.get().items.find((item) => readEntityId(item) === activeId);
+			const importedId = deriveTrackedChangeImportedId(activeRow);
 			trackedChangeNavigationInFlight += 1;
 			try {
-				const result = await scrollTargetIntoView(target, {
+				const result = await scrollTrackChangeIntoView(activeId, target, optimisticActiveChange?.story, importedId, {
 					behavior: "auto",
 					shouldContinue: isCurrent
 				});
@@ -9130,7 +9293,9 @@ function createSuperDocUI(options) {
 			const requestedAtInvalidation = trackChangeRevealInvalidation;
 			const loadedItems = trackChangesSub.get().items;
 			const publicId = buildTrackedChangeIdContext(loadedItems).toPublicId(changeId) ?? changeId;
-			const story = readEntityRequestStory(loadedItems.find((item) => readEntityId(item) === publicId));
+			const matchingRow = loadedItems.find((item) => readEntityId(item) === publicId);
+			const story = readEntityRequestStory(matchingRow);
+			const importedId = deriveTrackedChangeImportedId(matchingRow);
 			const previousActiveChange = explicitActiveChange;
 			const requestedActiveChange = {
 				id: publicId,
@@ -9162,7 +9327,7 @@ function createSuperDocUI(options) {
 				recompute();
 				trackedChangeNavigationInFlight += 1;
 				try {
-					const result = await scrollTargetIntoView(target, {
+					const result = await scrollTrackChangeIntoView(publicId, target, story, importedId, {
 						behavior: "auto",
 						shouldContinue: isCurrent
 					});