superdoc 2.0.0-next.43 → 2.0.0-next.45

package/dist/chunks/{create-super-doc-ui-BFz0iim0.es.js → create-super-doc-ui-BTOlZen9.es.js}

@@ -1481,12 +1481,6 @@ const INLINE_PROPERTY_REGISTRY = [
 new Set(INLINE_PROPERTY_REGISTRY.map((entry) => entry.key));
 const INLINE_PROPERTY_BY_KEY = Object.fromEntries(INLINE_PROPERTY_REGISTRY.map((entry) => [entry.key, entry]));
 INLINE_PROPERTY_REGISTRY.filter((entry) => entry.storage === "mark").map((entry) => entry.key), INLINE_PROPERTY_REGISTRY.filter((entry) => entry.storage === "runAttribute").map((entry) => entry.key);
-var POST_DECISION_TRACKED_CHANGES_LIST_OPTIONS = Object.freeze({
-	mode: "background-reconcile",
-	refreshReason: "post-decision-background",
-	blocking: false
-});
-var POST_DECISION_TRACKED_CHANGES_RECONCILE_DELAY_MS = 3e3;
 var SUPERDOC_UI_REASON_VALUES = new Set(Object.values(SUPERDOC_UI_REASONS));
 function coerceSuperDocUIReason(reason, fallback) {
 	return typeof reason === "string" && SUPERDOC_UI_REASON_VALUES.has(reason) ? reason : fallback;
@@ -2911,7 +2905,6 @@ function createSuperDocUI(options) {
 	let foregroundAsyncRetryTimer = null;
 	let pendingSelectionSeedValidationToken = null;
 	let typingContentInvalidationTimer = null;
-	let postDecisionTrackChangesReconcileTimer = null;
 	const scheduleAsyncRefresh = () => {
 		if (asyncRefreshScheduled || disposed) return;
 		asyncRefreshScheduled = true;
@@ -2958,14 +2951,12 @@ function createSuperDocUI(options) {
 	};
 	let scheduleAuthoritativeTrackChangesRetry = (_reconcileToken) => void 0;
 	let postDecisionTrackChangesToken = null;
-	let postDecisionTrackChangesReconcileToken = null;
 	let postDecisionTrackChangeIds = /* @__PURE__ */ new Set();
 	let selectionEpoch = 0;
 	let lastCoordinatorEditor = null;
 	const contentToken = () => `${editorIdentityId(getEditor())}|m${documentMutationRevision}`;
 	const clearPostDecisionTrackChanges = () => {
 		postDecisionTrackChangesToken = null;
-		postDecisionTrackChangesReconcileToken = null;
 		postDecisionTrackChangeIds = /* @__PURE__ */ new Set();
 	};
 	const applyPostDecisionTrackChangesToCache = (ids) => {
@@ -2983,25 +2974,6 @@ function createSuperDocUI(options) {
 			});
 		}
 	};
-	const schedulePostDecisionTrackChangesReconcile = () => {
-		if (disposed || postDecisionTrackChangesReconcileTimer) return;
-		postDecisionTrackChangesReconcileTimer = setTimeout(() => {
-			postDecisionTrackChangesReconcileTimer = null;
-			const run = () => {
-				if (disposed || postDecisionTrackChangeIds.size === 0) return;
-				invalidateDocumentContent({ preservePostDecisionTrackChanges: true });
-				postDecisionTrackChangesToken = contentToken();
-				postDecisionTrackChangesReconcileToken = postDecisionTrackChangesToken;
-				recompute();
-			};
-			const requestIdle = globalThis.requestIdleCallback;
-			if (typeof requestIdle === "function") {
-				requestIdle(run, { timeout: 2e3 });
-				return;
-			}
-			run();
-		}, POST_DECISION_TRACKED_CHANGES_RECONCILE_DELAY_MS);
-	};
 	const notifyPostDecisionTrackChanges = (receipt) => {
 		const notify = () => {
 			if (disposed) return;
@@ -3067,7 +3039,6 @@ function createSuperDocUI(options) {
 		postDecisionTrackChangesToken = token;
 		postDecisionTrackChangeIds = new Set([...alreadyRemoved, ...newlyRemoved]);
 		applyPostDecisionTrackChangesToCache(postDecisionTrackChangeIds);
-		schedulePostDecisionTrackChangesReconcile();
 		publishPostDecisionTrackChanges(newlyRemoved, receipt);
 	};
 	const postDecisionTrackChangeIdsForToken = (token) => postDecisionTrackChangesToken === token && postDecisionTrackChangeIds.size > 0 ? postDecisionTrackChangeIds : null;
@@ -3736,11 +3707,11 @@ function createSuperDocUI(options) {
 		sourceLoadingSubscriptionHost = null;
 		clearPostDecisionTrackChanges();
 	};
-	const invalidateDocumentContent = (options$1) => {
+	const invalidateDocumentContent = () => {
 		const carryAuthoritativeTrackChangesHold = authoritativeTrackChangesPendingToken !== null;
 		documentMutationRevision += 1;
 		if (carryAuthoritativeTrackChangesHold) authoritativeTrackChangesPendingToken = contentToken();
-		if (!options$1?.preservePostDecisionTrackChanges) clearPostDecisionTrackChanges();
+		clearPostDecisionTrackChanges();
 	};
 	const insertText = (text) => {
 		if (typeof text !== "string" || text.length === 0) return failedReceipt("insertText requires a non-empty string.", "INVALID_INPUT");
@@ -3951,10 +3922,9 @@ function createSuperDocUI(options) {
 			value: heldEntry?.hasSettled ? heldEntry.value : null,
 			status: heldEntry?.hasSettled ? "stale" : "pending"
 		} : readAsync("trackChanges", token, () => {
-			if (listTrackedChanges) return postDecisionTrackChangesToken === token ? listTrackedChanges.call(v2TrackedChanges, POST_DECISION_TRACKED_CHANGES_LIST_OPTIONS) : listTrackedChanges.call(v2TrackedChanges);
+			if (listTrackedChanges) return listTrackedChanges.call(v2TrackedChanges);
 			return tcApi?.list ? tcApi.list() : void 0;
 		}, (raw) => raw && Array.isArray(raw.items) ? raw.items : []);
-		if (listStatus === "ready" && postDecisionTrackChangesReconcileToken === token) clearPostDecisionTrackChanges();
 		const items = (value ?? []).map(projectTrackChangesItem).filter((item) => item != null).filter((item) => {
 			const id = readEntityId(item);
 			return !id || !postDecisionIds?.has(id);
@@ -8752,10 +8722,6 @@ function createSuperDocUI(options) {
 			clearTimeout(typingContentInvalidationTimer);
 			typingContentInvalidationTimer = null;
 		}
-		if (postDecisionTrackChangesReconcileTimer) {
-			clearTimeout(postDecisionTrackChangesReconcileTimer);
-			postDecisionTrackChangesReconcileTimer = null;
-		}
 		if (heavyReadCompletionRecomputeTimer) {
 			clearTimeout(heavyReadCompletionRecomputeTimer);
 			heavyReadCompletionRecomputeTimer = null;

package/dist/chunks/{create-super-doc-ui-DYky1UEo.cjs → create-super-doc-ui-DDxbK_M7.cjs}

@@ -1703,12 +1703,6 @@ const INLINE_PROPERTY_KEYS_BY_STORAGE = {
 	mark: INLINE_PROPERTY_REGISTRY.filter((entry) => entry.storage === "mark").map((entry) => entry.key),
 	runAttribute: INLINE_PROPERTY_REGISTRY.filter((entry) => entry.storage === "runAttribute").map((entry) => entry.key)
 };
-var POST_DECISION_TRACKED_CHANGES_LIST_OPTIONS = Object.freeze({
-	mode: "background-reconcile",
-	refreshReason: "post-decision-background",
-	blocking: false
-});
-var POST_DECISION_TRACKED_CHANGES_RECONCILE_DELAY_MS = 3e3;
 var SUPERDOC_UI_REASON_VALUES = new Set(Object.values(SUPERDOC_UI_REASONS));
 function coerceSuperDocUIReason(reason, fallback) {
 	return typeof reason === "string" && SUPERDOC_UI_REASON_VALUES.has(reason) ? reason : fallback;
@@ -3133,7 +3127,6 @@ function createSuperDocUI(options) {
 	let foregroundAsyncRetryTimer = null;
 	let pendingSelectionSeedValidationToken = null;
 	let typingContentInvalidationTimer = null;
-	let postDecisionTrackChangesReconcileTimer = null;
 	const scheduleAsyncRefresh = () => {
 		if (asyncRefreshScheduled || disposed) return;
 		asyncRefreshScheduled = true;
@@ -3180,14 +3173,12 @@ function createSuperDocUI(options) {
 	};
 	let scheduleAuthoritativeTrackChangesRetry = (_reconcileToken) => void 0;
 	let postDecisionTrackChangesToken = null;
-	let postDecisionTrackChangesReconcileToken = null;
 	let postDecisionTrackChangeIds = /* @__PURE__ */ new Set();
 	let selectionEpoch = 0;
 	let lastCoordinatorEditor = null;
 	const contentToken = () => `${editorIdentityId(getEditor())}|m${documentMutationRevision}`;
 	const clearPostDecisionTrackChanges = () => {
 		postDecisionTrackChangesToken = null;
-		postDecisionTrackChangesReconcileToken = null;
 		postDecisionTrackChangeIds = /* @__PURE__ */ new Set();
 	};
 	const applyPostDecisionTrackChangesToCache = (ids) => {
@@ -3205,25 +3196,6 @@ function createSuperDocUI(options) {
 			});
 		}
 	};
-	const schedulePostDecisionTrackChangesReconcile = () => {
-		if (disposed || postDecisionTrackChangesReconcileTimer) return;
-		postDecisionTrackChangesReconcileTimer = setTimeout(() => {
-			postDecisionTrackChangesReconcileTimer = null;
-			const run = () => {
-				if (disposed || postDecisionTrackChangeIds.size === 0) return;
-				invalidateDocumentContent({ preservePostDecisionTrackChanges: true });
-				postDecisionTrackChangesToken = contentToken();
-				postDecisionTrackChangesReconcileToken = postDecisionTrackChangesToken;
-				recompute();
-			};
-			const requestIdle = globalThis.requestIdleCallback;
-			if (typeof requestIdle === "function") {
-				requestIdle(run, { timeout: 2e3 });
-				return;
-			}
-			run();
-		}, POST_DECISION_TRACKED_CHANGES_RECONCILE_DELAY_MS);
-	};
 	const notifyPostDecisionTrackChanges = (receipt) => {
 		const notify = () => {
 			if (disposed) return;
@@ -3289,7 +3261,6 @@ function createSuperDocUI(options) {
 		postDecisionTrackChangesToken = token;
 		postDecisionTrackChangeIds = new Set([...alreadyRemoved, ...newlyRemoved]);
 		applyPostDecisionTrackChangesToCache(postDecisionTrackChangeIds);
-		schedulePostDecisionTrackChangesReconcile();
 		publishPostDecisionTrackChanges(newlyRemoved, receipt);
 	};
 	const postDecisionTrackChangeIdsForToken = (token) => postDecisionTrackChangesToken === token && postDecisionTrackChangeIds.size > 0 ? postDecisionTrackChangeIds : null;
@@ -3958,11 +3929,11 @@ function createSuperDocUI(options) {
 		sourceLoadingSubscriptionHost = null;
 		clearPostDecisionTrackChanges();
 	};
-	const invalidateDocumentContent = (options$1) => {
+	const invalidateDocumentContent = () => {
 		const carryAuthoritativeTrackChangesHold = authoritativeTrackChangesPendingToken !== null;
 		documentMutationRevision += 1;
 		if (carryAuthoritativeTrackChangesHold) authoritativeTrackChangesPendingToken = contentToken();
-		if (!options$1?.preservePostDecisionTrackChanges) clearPostDecisionTrackChanges();
+		clearPostDecisionTrackChanges();
 	};
 	const insertText = (text) => {
 		if (typeof text !== "string" || text.length === 0) return failedReceipt("insertText requires a non-empty string.", "INVALID_INPUT");
@@ -4173,10 +4144,9 @@ function createSuperDocUI(options) {
 			value: heldEntry?.hasSettled ? heldEntry.value : null,
 			status: heldEntry?.hasSettled ? "stale" : "pending"
 		} : readAsync("trackChanges", token, () => {
-			if (listTrackedChanges) return postDecisionTrackChangesToken === token ? listTrackedChanges.call(v2TrackedChanges, POST_DECISION_TRACKED_CHANGES_LIST_OPTIONS) : listTrackedChanges.call(v2TrackedChanges);
+			if (listTrackedChanges) return listTrackedChanges.call(v2TrackedChanges);
 			return tcApi?.list ? tcApi.list() : void 0;
 		}, (raw) => raw && Array.isArray(raw.items) ? raw.items : []);
-		if (listStatus === "ready" && postDecisionTrackChangesReconcileToken === token) clearPostDecisionTrackChanges();
 		const items = (value ?? []).map(projectTrackChangesItem).filter((item) => item != null).filter((item) => {
 			const id = readEntityId(item);
 			return !id || !postDecisionIds?.has(id);
@@ -8974,10 +8944,6 @@ function createSuperDocUI(options) {
 			clearTimeout(typingContentInvalidationTimer);
 			typingContentInvalidationTimer = null;
 		}
-		if (postDecisionTrackChangesReconcileTimer) {
-			clearTimeout(postDecisionTrackChangesReconcileTimer);
-			postDecisionTrackChangesReconcileTimer = null;
-		}
 		if (heavyReadCompletionRecomputeTimer) {
 			clearTimeout(heavyReadCompletionRecomputeTimer);
 			heavyReadCompletionRecomputeTimer = null;

package/dist/collaboration-upgrade-engine.cjs

@@ -7,7 +7,7 @@ const COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = (0, __superdoc_docx_engine_collaboration_upgrade_engine.getCollaborationUpgradeEngineInfo)();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.0.0-next.43",
+	superdocVersion: "2.0.0-next.45",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/collaboration-upgrade-engine.es.js

@@ -6,7 +6,7 @@ const COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = getCollaborationUpgradeEngineInfo$1();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.0.0-next.43",
+	superdocVersion: "2.0.0-next.45",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/public/ui-react.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_rolldown_runtime = require("../chunks/rolldown-runtime-_dR15c8t.cjs");
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DYky1UEo.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DDxbK_M7.cjs");
 let react = require("react");
 var SuperDocUIContext = (0, react.createContext)(null);
 function SuperDocUIProvider(props) {

package/dist/public/ui-react.es.js

@@ -1,4 +1,4 @@
-import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-BFz0iim0.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-BTOlZen9.es.js";
 import { createContext, createElement, useCallback, useContext, useEffect, useRef, useState } from "react";
 var SuperDocUIContext = createContext(null);
 function SuperDocUIProvider(props) {

package/dist/public/ui.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DYky1UEo.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DDxbK_M7.cjs");
 exports.BUILT_IN_COMMAND_IDS = require_create_super_doc_ui.BUILT_IN_COMMAND_IDS;
 exports.createSuperDocUI = require_create_super_doc_ui.createSuperDocUI;
 exports.shallowEqual = require_create_super_doc_ui.shallowEqual;

package/dist/public/ui.es.js

@@ -1,2 +1,2 @@
-import { n as BUILT_IN_COMMAND_IDS, r as shallowEqual, t as createSuperDocUI } from "../chunks/create-super-doc-ui-BFz0iim0.es.js";
+import { n as BUILT_IN_COMMAND_IDS, r as shallowEqual, t as createSuperDocUI } from "../chunks/create-super-doc-ui-BTOlZen9.es.js";
 export { BUILT_IN_COMMAND_IDS, createSuperDocUI, shallowEqual };

package/dist/style.css

@@ -1368,28 +1368,28 @@ img[data-v-c95b2073] {
   background-color: #1355ff7f;
 }
 
-.comment-placeholder[data-v-7f4821a8] {
+.comment-placeholder[data-v-a1bd2282] {
   position: absolute;
   width: 300px;
   transition: top 0.3s ease;
 }
-.comment-placeholder.is-direct-decision-continuity-target[data-v-7f4821a8] .overflow-menu {
+.comment-placeholder.is-direct-decision-continuity-target[data-v-a1bd2282] .overflow-menu {
   opacity: 1;
   pointer-events: auto;
 }
-.floating-comment[data-v-7f4821a8] {
+.floating-comment[data-v-a1bd2282] {
   position: relative;
   display: block;
   min-width: 300px;
 }
-.sidebar-container[data-v-7f4821a8] {
+.sidebar-container[data-v-a1bd2282] {
   position: absolute;
   width: 300px;
   min-height: 300px;
   transition: transform 0.3s ease;
   will-change: transform;
 }
-.section-wrapper[data-v-7f4821a8] {
+.section-wrapper[data-v-a1bd2282] {
   position: relative;
   min-height: 100%;
   width: 300px;

package/dist/style.layered.css

@@ -1368,28 +1368,28 @@ img[data-v-c95b2073] {
   background-color: #1355ff7f;
 }
 
-.comment-placeholder[data-v-7f4821a8] {
+.comment-placeholder[data-v-a1bd2282] {
   position: absolute;
   width: 300px;
   transition: top 0.3s ease;
 }
-.comment-placeholder.is-direct-decision-continuity-target[data-v-7f4821a8] .overflow-menu {
+.comment-placeholder.is-direct-decision-continuity-target[data-v-a1bd2282] .overflow-menu {
   opacity: 1;
   pointer-events: auto;
 }
-.floating-comment[data-v-7f4821a8] {
+.floating-comment[data-v-a1bd2282] {
   position: relative;
   display: block;
   min-width: 300px;
 }
-.sidebar-container[data-v-7f4821a8] {
+.sidebar-container[data-v-a1bd2282] {
   position: absolute;
   width: 300px;
   min-height: 300px;
   transition: transform 0.3s ease;
   will-change: transform;
 }
-.section-wrapper[data-v-7f4821a8] {
+.section-wrapper[data-v-a1bd2282] {
   position: relative;
   min-height: 100%;
   width: 300px;

package/dist/superdoc/src/core/types/index.d.ts

@@ -1639,17 +1639,31 @@ export interface Modules {
     /** Collaboration module configuration. */
     collaboration?: CollaborationConfig;
     /**
-     * Toolbar module configuration. Pass `true` to enable the toolbar with
-     * defaults (equivalent to an empty object). The `selector`, `groups`,
-     * `icons`, and `texts` fields fall back to the top-level `Config.toolbar`,
-     * `Config.toolbarGroups`, `Config.toolbarIcons`, and `Config.toolbarTexts`
-     * aliases respectively if not set here.
+     * Toolbar module configuration. Pass `true` to configure the toolbar with
+     * defaults (equivalent to an empty object).
+     *
+     * This field configures the toolbar's contents and behavior; it does not by
+     * itself provide a place to render it. A toolbar is only rendered once a
+     * mount target resolves, from either `selector` here or the top-level
+     * `Config.toolbar`. Without one, SuperDoc still creates the
+     * `superdoc.toolbar` handle (item lookup and command routing keep working)
+     * but renders no toolbar UI.
+     *
+     * Fallbacks to the top-level aliases are per field: `selector` falls back to
+     * `Config.toolbar`, `icons` to `Config.toolbarIcons`, and `texts` to
+     * `Config.toolbarTexts`. `Config.toolbarGroups` supplies the group ordering,
+     * not `groups`: the two are different settings. `groups` maps group ids to
+     * item ids (composition) and has no top-level alias, so omitting it uses the
+     * built-in composition. Supplying it also replaces the group ordering with
+     * its own keys.
      */
     toolbar?: boolean | ({
         /**
-         * CSS selector (id or class) for the DOM element to render the toolbar
-         * into. Must be a string selector, not an `HTMLElement` reference. Falls
-         * back to `Config.toolbar` if omitted.
+         * Selector for the DOM element to render the toolbar into: an id
+         * selector (`#toolbar`), a class selector (`.toolbar`), or a bare
+         * element id (`toolbar`). Must be a string, not an `HTMLElement`
+         * reference — pass an element through the top-level `Config.toolbar`.
+         * Falls back to `Config.toolbar` if omitted.
          */
         selector?: string;
         /** Toolbar item ids to hide from the default set. */
@@ -2348,7 +2362,18 @@ export interface Config {
     role?: 'editor' | 'viewer' | 'suggester';
     /**
      * The document to load. If a string, it will be treated as a URL. If a File
-     * or Blob, it will be used directly.
+     * or Blob, it will be used directly. For a v2 collaboration room, pass a
+     * structured document carrying `v2Collaboration`.
+     *
+     * Omitting this field and `documents` mounts a blank DOCX, so the Editor
+     * opens a real document rather than an empty surface. The blank document is
+     * a supported v2 source; it is seeded before mount and behaves like any
+     * other opened DOCX, including export.
+     *
+     * Setting the v1 `modules.collaboration` field also suppresses that seeding,
+     * but it is not a supported v2 path: the runtime fails closed with
+     * `collaboration-v1-config-unsupported` and mounts only enough state to
+     * report that error.
      */
     document?: object | string | globalThis.File | globalThis.Blob;
     /** Password for encrypted DOCX files. Forwarded during document load. */
@@ -2371,8 +2396,26 @@ export interface Config {
     modules?: Modules;
     /** Top-level override for permission checks. */
     permissionResolver?: (params: PermissionResolverParams) => boolean | undefined;
-    /** Optional DOM element to render the toolbar in. */
-    toolbar?: string;
+    /**
+     * Where to render the built-in toolbar. Either an `HTMLElement`, or a
+     * selector string in one of the supported forms: an id selector (`#toolbar`),
+     * a class selector (`.toolbar`), or a bare element id (`toolbar`). Other CSS
+     * selector syntax is not supported — an attribute or descendant selector such
+     * as `[data-toolbar]` resolves to nothing and leaves the toolbar unrendered.
+     *
+     * SuperDoc renders into the resolved element but does not manage its
+     * placement, and never includes it in the `contained` layout calculation.
+     * Where the application puts it therefore decides the space it needs: a
+     * sibling of a 400px `contained` Editor adds its own height alongside it,
+     * while a toolbar placed inside that host consumes part of the 400px and can
+     * overflow it.
+     *
+     * Omitting this field (and `modules.toolbar.selector`) renders no toolbar.
+     * `modules.toolbar: true` on its own does not render one either — it creates
+     * the `superdoc.toolbar` handle without a mount target. See
+     * {@link Modules.toolbar}.
+     */
+    toolbar?: string | HTMLElement;
     /** Toolbar groups to show. */
     toolbarGroups?: string[];
     /** Icons to show in the toolbar. */
@@ -2574,11 +2617,26 @@ export interface Config {
     /** Document view options (OOXML ST_View compatible). */
     viewOptions?: ViewOptions;
     /**
-     * Enable contained mode for fixed-height container embedding. When true,
-     * SuperDoc propagates height through its DOM tree and adds internal
-     * scrolling, so multi-page documents scroll within the consumer's
-     * fixed-height container. Default behavior (false) lets the document
-     * expand to its natural height.
+     * Enable contained mode for fixed-height container embedding.
+     *
+     * SuperDoc supports two layout modes, and the host element's height
+     * requirement differs between them:
+     *
+     * - Natural (default, `false`): the Editor grows to the document's full
+     *   height and the page scrolls. The host needs no height. Setting one does
+     *   not constrain the document or enable internal scrolling, because
+     *   SuperDoc leaves overflow visible in this mode, though application CSS
+     *   on the host can still clip what is drawn.
+     * - Contained (`true`): SuperDoc propagates `height: 100%` through its DOM
+     *   tree and scrolls the document internally, so multi-page documents stay
+     *   inside the host. This mode requires the host to have a definite height
+     *   (for example `height: 400px`); without one there is nothing for the
+     *   percentage heights to resolve against.
+     *
+     * A toolbar mounted through `Config.toolbar` or `modules.toolbar.selector` is
+     * never part of this calculation. Placed as a sibling of the host, its height
+     * adds to the host's: a 400px host with a 40px toolbar occupies 440px in
+     * total. Placed inside the host, it consumes part of the 400px instead.
      */
     contained?: boolean;
     /** Content Security Policy nonce for dynamically injected styles. */

package/dist/superdoc.cjs

@@ -6,7 +6,7 @@ const require_uuid = require("./chunks/uuid-CFp0WGVU.cjs");
 const require_jszip = require("./chunks/jszip-BdUBlUeG.cjs");
 const require__plugin_vue_export_helper = require("./chunks/_plugin-vue_export-helper-BTwbGDKw.cjs");
 const require_constants = require("./chunks/constants-sbCZ2O_A.cjs");
-const require_create_super_doc_ui = require("./chunks/create-super-doc-ui-DYky1UEo.cjs");
+const require_create_super_doc_ui = require("./chunks/create-super-doc-ui-DDxbK_M7.cjs");
 let vue = require("vue");
 vue = require_rolldown_runtime.__toESM(vue);
 require("y-websocket");
@@ -3096,14 +3096,12 @@ const useCommentsStore = defineStore("comments", () => {
 	const v2TrackedChangesAdapter = (0, vue.shallowRef)(null);
 	const setV2TrackedChangesAdapter = (adapter) => {
 		v2TrackedChangesAdapter.value = adapter ?? null;
-		if (!adapter) postDecisionBackgroundReconcileByDocument.clear();
 	};
 	const getV2TrackedChangesAdapter = (superdoc) => {
 		const fromFacade = superdoc?.activeEditor?.v2TrackedChanges ?? null;
 		if (fromFacade) return fromFacade;
 		return v2TrackedChangesAdapter.value;
 	};
-	const postDecisionBackgroundReconcileByDocument = /* @__PURE__ */ new Map();
 	const init = (config = {}) => {
 		const updatedConfig = {
 			...commentsConfig,
@@ -5197,16 +5195,6 @@ const useCommentsStore = defineStore("comments", () => {
 			removedIds
 		};
 	};
-	const waitForPostDecisionReconcileIdle = () => new Promise((resolve) => {
-		setTimeout(() => {
-			const requestIdle = globalThis?.requestIdleCallback;
-			if (typeof requestIdle === "function") {
-				requestIdle(() => resolve(void 0), { timeout: 2e3 });
-				return;
-			}
-			resolve(void 0);
-		}, 3e3);
-	});
 	const clearV2ActiveTrackedChangeTarget = (adapter, decidedId) => {
 		if (!decidedId || typeof adapter?.clearActiveTrackedChangeTargetIfMatches !== "function") return;
 		try {
@@ -5232,76 +5220,6 @@ const useCommentsStore = defineStore("comments", () => {
 			});
 		} catch {}
 	};
-	const tracePostDecisionBackgroundReconcile = (superdoc, event, payload = {}) => {
-		const record = {
-			event,
-			refreshReason: "post-decision-background",
-			blocking: false,
-			...payload
-		};
-		tracePreviewComments(`post-decision-background:${event}`, record);
-	};
-	const schedulePostDecisionBackgroundReconcile = ({ superdoc, trackedChangesAdapter, commentsAdapter, documentId } = {}) => {
-		const normalizedDocumentId = normalizeCommentId(documentId);
-		if (!normalizedDocumentId || !trackedChangesAdapter) return null;
-		const existing = postDecisionBackgroundReconcileByDocument.get(normalizedDocumentId);
-		if (existing) return existing;
-		const reconcilePromise = waitForPostDecisionReconcileIdle().then(async () => {
-			tracePostDecisionBackgroundReconcile(superdoc, "start", { documentId: normalizedDocumentId });
-			const trackedResult = await hydrateTrackedChangesFromV2({
-				superdoc,
-				adapter: trackedChangesAdapter,
-				documentId: normalizedDocumentId,
-				trackedChangesListMode: "background-reconcile",
-				refreshReason: "post-decision-background",
-				blocking: false
-			});
-			if (!trackedResult?.ok) tracePostDecisionBackgroundReconcile(superdoc, "tracked-changes-failed", {
-				documentId: normalizedDocumentId,
-				reason: trackedResult?.reason ?? null,
-				detail: trackedResult?.detail ?? null
-			});
-			if (commentsAdapter && typeof commentsAdapter.refresh === "function" && isCurrentV2CommentsAdapter(commentsAdapter)) {
-				let commentsResult;
-				try {
-					commentsResult = await commentsAdapter.refresh();
-				} catch (err) {
-					commentsResult = {
-						ok: false,
-						reason: "comments-refresh-threw",
-						detail: err?.message ?? String(err)
-					};
-				}
-				if (isCurrentV2CommentsAdapter(commentsAdapter) && commentsResult?.ok) reconcileCommentsFromV2({
-					superdoc,
-					adapter: commentsAdapter,
-					documentId: commentsAdapter.documentId ?? normalizedDocumentId,
-					items: commentsResult.items ?? []
-				});
-				else if (!commentsResult?.ok) tracePostDecisionBackgroundReconcile(superdoc, "comments-failed", {
-					documentId: normalizedDocumentId,
-					reason: commentsResult?.reason ?? null,
-					detail: commentsResult?.detail ?? null
-				});
-			}
-			tracePostDecisionBackgroundReconcile(superdoc, "complete", { documentId: normalizedDocumentId });
-			return { ok: true };
-		}).catch((err) => {
-			tracePostDecisionBackgroundReconcile(superdoc, "failed", {
-				documentId: normalizedDocumentId,
-				detail: err?.message ?? String(err)
-			});
-			return {
-				ok: false,
-				reason: "post-decision-background-failed",
-				detail: err?.message ?? String(err)
-			};
-		}).finally(() => {
-			if (postDecisionBackgroundReconcileByDocument.get(normalizedDocumentId) === reconcilePromise) postDecisionBackgroundReconcileByDocument.delete(normalizedDocumentId);
-		});
-		postDecisionBackgroundReconcileByDocument.set(normalizedDocumentId, reconcilePromise);
-		return reconcilePromise;
-	};
 	const decideTrackedChangeFromSidebar = ({ superdoc, comment, decision }) => {
 		if (commentsAreReadOnly$1()) return {
 			ok: false,
@@ -5428,12 +5346,6 @@ const useCommentsStore = defineStore("comments", () => {
 					};
 					if (!reliableDecidedIds.size || !effectiveDocumentId) return runBlockingPostDecisionReconcile();
 					reliableDecidedIds.forEach((id$1) => clearV2ActiveTrackedChangeTarget(v2Adapter, id$1));
-					schedulePostDecisionBackgroundReconcile({
-						superdoc,
-						trackedChangesAdapter: v2Adapter,
-						commentsAdapter: getV2CommentsAdapter(superdoc),
-						documentId: effectiveDocumentId
-					});
 					await waitForTrackedDecisionCanonicalPaint({
 						superdoc,
 						receipt: outcome.receipt
@@ -8757,16 +8669,38 @@ var _sfc_main$30 = {
 		};
 		const getFloatingViewportRange = () => {
 			const container = floatingCommentsContainer.value;
-			const viewportRect = props.parent?.getBoundingClientRect?.();
-			if (!container || !viewportRect) return null;
+			if (!container) return null;
 			const containerRect = container.getBoundingClientRect();
-			if (!Number.isFinite(containerRect.top) || !Number.isFinite(viewportRect.top) || !Number.isFinite(viewportRect.bottom)) return null;
-			const top = viewportRect.top - containerRect.top;
-			const bottom = viewportRect.bottom - containerRect.top;
-			return bottom >= top ? {
-				top,
-				bottom
-			} : null;
+			if (!Number.isFinite(containerRect.top) || !Number.isFinite(window.innerHeight)) return null;
+			let visibleClientTop = 0;
+			let visibleClientBottom = window.innerHeight;
+			for (let ancestor = container.parentElement; ancestor; ancestor = ancestor.parentElement) {
+				const overflowY = window.getComputedStyle(ancestor).overflowY;
+				if (![
+					"auto",
+					"scroll",
+					"hidden",
+					"clip"
+				].includes(overflowY)) continue;
+				const ancestorRect = ancestor.getBoundingClientRect();
+				if (!Number.isFinite(ancestorRect.top) || !Number.isFinite(ancestorRect.bottom)) continue;
+				visibleClientTop = Math.max(visibleClientTop, ancestorRect.top);
+				visibleClientBottom = Math.min(visibleClientBottom, ancestorRect.bottom);
+			}
+			if (visibleClientBottom <= visibleClientTop) return null;
+			const parentRect = props.parent?.getBoundingClientRect?.();
+			if (parentRect && Number.isFinite(parentRect.top) && Number.isFinite(parentRect.bottom)) {
+				const intersectedTop = Math.max(visibleClientTop, parentRect.top);
+				const intersectedBottom = Math.min(visibleClientBottom, parentRect.bottom);
+				if (intersectedBottom > intersectedTop) {
+					visibleClientTop = intersectedTop;
+					visibleClientBottom = intersectedBottom;
+				}
+			}
+			return {
+				top: visibleClientTop - containerRect.top,
+				bottom: visibleClientBottom - containerRect.top
+			};
 		};
 		const instantAlignmentInstanceKey = (0, vue.computed)(() => {
 			if (!instantSidebarAlignmentThreadId.value) return null;
@@ -9374,7 +9308,7 @@ var _sfc_main$30 = {
 		};
 	}
 };
-var FloatingComments_default = /* @__PURE__ */ require__plugin_vue_export_helper.__plugin_vue_export_helper_default(_sfc_main$30, [["__scopeId", "data-v-7f4821a8"]]);
+var FloatingComments_default = /* @__PURE__ */ require__plugin_vue_export_helper.__plugin_vue_export_helper_default(_sfc_main$30, [["__scopeId", "data-v-a1bd2282"]]);
 var _hoisted_1$22 = {
 	class: "superdoc__pdf-comments-layer pdf-comments-layer",
 	"aria-hidden": "false"
@@ -34763,7 +34697,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.0.0-next.43";
+		this.version = "2.0.0-next.45";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || require_uuid.v4_default();
 		this.colors = this.config.colors ?? [];