superdoc 2.4.0-next.10 → 2.4.0-next.12

package/dist/chunks/{create-super-doc-ui-ByvmsAAG.cjs → create-super-doc-ui-BWYOinLD.cjs}

@@ -1,44 +1,128 @@
-const DOM_CLASS_NAMES = {
+//#region ../layout-engine/dom-contract/src/class-names.ts
+/**
+* DOM Contract: Class Names
+*
+* CSS class names stamped on rendered document elements by the DOM painter.
+* These names form a public contract read by the painter (emitter) and by
+* editor-side DOM observation code (reader).
+*
+* Changing a value here is a breaking change for both systems.
+*/
+var DOM_CLASS_NAMES = {
+	/** Top-level page container element. */
 	PAGE: "superdoc-page",
+	/** Fragment container (paragraph, table, image block, etc.). */
 	FRAGMENT: "superdoc-fragment",
+	/** Line container within a fragment. */
 	LINE: "superdoc-line",
+	/**
+	* Inline structured-content (SDT) wrapper.
+	*
+	* Carries `data-pm-start` / `data-pm-end` for selection highlighting.
+	* Should be EXCLUDED from click-to-position mapping — child spans are
+	* the character-level targets.
+	*/
 	INLINE_SDT_WRAPPER: "superdoc-structured-content-inline",
+	/** Inline structured-content label chrome. */
 	INLINE_SDT_LABEL: "superdoc-structured-content-inline__label",
+	/** Block-level structured-content container. */
 	BLOCK_SDT: "superdoc-structured-content-block",
+	/** Block-level structured-content label chrome. */
 	BLOCK_SDT_LABEL: "superdoc-structured-content__label",
+	/** Table fragment container (resize overlay and click-mapping target). */
 	TABLE_FRAGMENT: "superdoc-table-fragment",
+	/** Document section container. */
 	DOCUMENT_SECTION: "superdoc-document-section",
+	/**
+	* Grouped hover highlight applied to all fragments of the same block SDT.
+	* Set by document-runtime hover coordination via event delegation.
+	*/
 	SDT_GROUP_HOVER: "sdt-group-hover",
+	/** Paragraph fragment rendered as a Table of Contents entry. */
 	TOC_ENTRY: "superdoc-toc-entry",
+	/** TOC analogue of `SDT_GROUP_HOVER`, applied to every fragment sharing a `data-toc-id`. */
 	TOC_GROUP_HOVER: "toc-group-hover",
+	/** Block-level image fragment (ImageBlock). */
 	IMAGE_FRAGMENT: "superdoc-image-fragment",
+	/** Inline image element (ImageRun inside a paragraph). */
 	INLINE_IMAGE: "superdoc-inline-image",
+	/** Wrapper around a paragraph's list marker (bullet glyph or ordered number). */
 	LIST_MARKER: "superdoc-list-marker",
+	/** Clip wrapper around a cropped inline image. */
 	INLINE_IMAGE_CLIP_WRAPPER: "superdoc-inline-image-clip-wrapper",
+	/** Field annotation outer wrapper. */
 	ANNOTATION: "annotation",
+	/** Field annotation inner content wrapper. */
 	ANNOTATION_CONTENT: "annotation-content",
+	/** Hidden caret anchor span appended after field annotation content. */
 	ANNOTATION_CARET_ANCHOR: "annotation-caret-anchor"
 };
-const STRUCTURED_CONTENT_CHROME_LABEL_CLASS_NAMES = [DOM_CLASS_NAMES.INLINE_SDT_LABEL, DOM_CLASS_NAMES.BLOCK_SDT_LABEL];
-const DATA_ATTRS = {
+DOM_CLASS_NAMES.INLINE_SDT_LABEL, DOM_CLASS_NAMES.BLOCK_SDT_LABEL;
+//#endregion
+//#region ../layout-engine/dom-contract/src/data-attrs.ts
+/**
+* DOM Contract: Data Attributes
+*
+* Named constants for `data-*` attributes stamped on rendered DOM elements.
+* These attributes are read by editor-side DOM observers, click-to-position
+* mapping, and bridge compatibility code.
+*
+* Each constant stores the full attribute name (e.g. `"data-pm-start"`) as it
+* appears in `getAttribute()` / `setAttribute()` calls and CSS selectors.
+*
+* The `DATASET_KEYS` mirror provides the camelCase equivalents used with
+* `element.dataset.*` access.
+*
+* Editor-neutral (prep-001) attributes live alongside the legacy `data-pm-*`
+* attributes; both surfaces are emitted so that v1 consumers continue to work
+* unmodified while future editor-neutral consumers (hit-test / range mapping)
+* can address rendered output without consulting ProseMirror positions.
+*/
+/**
+* Full attribute names for use with `getAttribute` / `setAttribute` / CSS selectors.
+*/
+var DATA_ATTRS = {
+	/** ProseMirror start position of the element's content range. */
 	PM_START: "data-pm-start",
+	/** ProseMirror end position of the element's content range. */
 	PM_END: "data-pm-end",
+	/** Layout epoch stamp — incremented on each layout pass. */
 	LAYOUT_EPOCH: "data-layout-epoch",
+	/** JSON-encoded table boundary metadata for resize overlays. */
 	TABLE_BOUNDARIES: "data-table-boundaries",
+	/** SDT unique identifier. */
 	SDT_ID: "data-sdt-id",
+	/** SDT type (fieldAnnotation, structuredContent, documentSection, etc.). */
 	SDT_TYPE: "data-sdt-type",
+	/** Field annotation field identifier. */
 	FIELD_ID: "data-field-id",
+	/** Field annotation field type (signer, text, checkbox, etc.). */
 	FIELD_TYPE: "data-field-type",
+	/** Marks an element as draggable by the editor. */
 	DRAGGABLE: "data-draggable",
+	/** Display label text for drag toast / accessibility. */
 	DISPLAY_LABEL: "data-display-label",
+	/** Field annotation variant (text, image, signature, checkbox, html, link). */
 	VARIANT: "data-variant",
+	/** Element type discriminator (annotation variant, etc.). */
 	TYPE: "data-type",
+	/** Schema version for the editor-neutral layout boundary attributes. */
 	LAYOUT_BOUNDARY_SCHEMA: "data-layout-boundary-schema",
+	/** Stable opaque id of the rendered fragment (see `LayoutFragmentId`). */
 	LAYOUT_FRAGMENT_ID: "data-layout-fragment-id",
+	/** Encoded story locator (e.g. `body`, `header:rId4`, `footer:rId7`). */
 	LAYOUT_STORY: "data-layout-story",
+	/** Source block reference (today: producer's `blockId`). */
 	LAYOUT_BLOCK_REF: "data-layout-block-ref"
 };
-const decodeLayoutStoryDataset = (raw) => {
+/**
+* Decode the dataset string back into a `LayoutStoryLocator`-shaped object.
+*
+* Used by editor-side DOM observers. Unknown kinds fall back to
+* `{ kind: 'unknown' }` so downstream code can treat the value as a
+* diagnostic, not as a default body.
+*/
+var decodeLayoutStoryDataset = (raw) => {
 	if (!raw) return { kind: "unknown" };
 	if (raw === "body") return { kind: "body" };
 	const idx = raw.indexOf(":");
@@ -57,8 +141,21 @@ const decodeLayoutStoryDataset = (raw) => {
 		default: return { kind: "unknown" };
 	}
 };
-const SDT_BLOCK_WITH_ID_SELECTOR = `.${DOM_CLASS_NAMES.BLOCK_SDT}[${DATA_ATTRS.SDT_ID}]`;
-const DRAGGABLE_SELECTOR = `[${DATA_ATTRS.DRAGGABLE}="true"]`;
+`${DOM_CLASS_NAMES.BLOCK_SDT}${DATA_ATTRS.SDT_ID}`;
+`${DATA_ATTRS.DRAGGABLE}`;
+//#endregion
+//#region ../layout-engine/contracts/src/direction-context.ts
+/**
+* Read a paragraph's inline base direction from its attributes.
+*
+* Prefers the resolved {@link ParagraphDirectionContext} (SD-2776) when
+* present. Falls back to `paragraphProperties.rightToLeft` for PM-node /
+* editor paths that store direction on the raw OOXML properties rather
+* than the typed direction context.
+*
+* Consumers should call this instead of inspecting attrs ad hoc so the
+* direction source check stays in one place.
+*/
 function getParagraphInlineDirection(attrs) {
 	const fromContext = attrs?.directionContext?.inlineDirection;
 	if (fromContext != null) return fromContext;
@@ -66,97 +163,65 @@ function getParagraphInlineDirection(attrs) {
 	if (ppRtl === true) return "rtl";
 	if (ppRtl === false) return "ltr";
 }
-var FALLBACK_PALETTE = [
-	"#1f6feb",
-	"#d1242f",
-	"#8250df",
-	"#bf3989",
-	"#1a7f37",
-	"#9a6700",
-	"#bc4c00",
-	"#0969da",
-	"#cf222e",
-	"#6639ba",
-	"#116329",
-	"#7d4e00"
-];
-const authorIdentityKey = (author) => {
-	if (!author) return "";
-	return `${typeof author.name === "string" ? author.name : ""} ${typeof author.email === "string" ? author.email : ""}`;
-};
-var hashString = (value) => {
-	let hash = 2166136261;
-	for (let i = 0; i < value.length; i += 1) {
-		hash ^= value.charCodeAt(i);
-		hash = Math.imul(hash, 16777619);
-	}
-	return hash >>> 0;
-};
-const fallbackAuthorColor = (author) => {
-	return FALLBACK_PALETTE[hashString(authorIdentityKey(author)) % FALLBACK_PALETTE.length];
-};
-var isNonEmptyString = (value) => typeof value === "string" && value.length > 0;
-const composeAuthorColorResolver = (config) => {
-	if (!config || config.enabled === false) return void 0;
-	const overrides = config.overrides && typeof config.overrides === "object" ? config.overrides : void 0;
-	const resolve = typeof config.resolve === "function" ? config.resolve : void 0;
-	return (author) => {
-		const safeAuthor = author ?? {};
-		if (overrides) {
-			if (isNonEmptyString(safeAuthor.email) && isNonEmptyString(overrides[safeAuthor.email])) return overrides[safeAuthor.email];
-			if (isNonEmptyString(safeAuthor.name) && isNonEmptyString(overrides[safeAuthor.name])) return overrides[safeAuthor.name];
-		}
-		if (resolve) try {
-			const resolved = resolve(safeAuthor);
-			if (isNonEmptyString(resolved)) return resolved;
-		} catch {}
-		return fallbackAuthorColor(safeAuthor);
-	};
-};
-const TRACKED_CHANGE_CONFIGURABLE_SEMANTIC_COLOR_KEYS = [
-	"insertion",
-	"deletion",
-	"move",
-	"move-from",
-	"move-to",
-	"table-cell-insertion",
-	"table-cell-deletion",
-	"cell-merge",
-	"cell-split",
-	"image-insertion",
-	"image-deletion",
-	"image-property-change"
-];
-var CONFIGURABLE_SEMANTIC_COLOR_KEY_SET = new Set(TRACKED_CHANGE_CONFIGURABLE_SEMANTIC_COLOR_KEYS);
-const DRAWING_DIAGNOSTIC_CODES = {
+//#endregion
+//#region ../layout-engine/contracts/src/drawing-taxonomy.ts
+/**
+* Frozen canonical diagnostic codes for drawing rendering.
+*
+* New extractor/adapter diagnostics MUST use these exact strings. Family-
+* specific codes are required — do not collapse everything to
+* `render.unsupported-inline-ooxml` (plan §4).
+*/
+var DRAWING_DIAGNOSTIC_CODES = {
+	/** External image relationship (`r:link` / `TargetMode="External"`). Not fetched. */
 	externalImageDeferred: "render.media.external-image-deferred",
+	/** Drawing references a relationship id that does not exist on the owner part. */
 	missingRelationship: "render.drawing.missing-relationship",
+	/** Relationship resolves but the target media part bytes are missing/empty. */
 	missingMediaPart: "render.media.missing-part",
+	/** Relationship exists but is not an image relationship type. */
 	unsupportedRelationshipType: "render.drawing.unsupported-relationship-type",
+	/** Media MIME is not in the supported allowlist. */
 	unsupportedMime: "render.media.unsupported-mime",
+	/** Media part exceeds the host byte-size policy before bytes are materialized. */
 	imageTooLarge: "render.media.image-too-large",
+	/** SVG content rejected by the SVG safety policy. */
 	unsafeSvg: "render.media.unsafe-svg",
+	/** Metafile / TIFF (EMF, WMF, TIFF) with no approved conversion path. */
 	unsupportedFormat: "render.media.unsupported-format",
+	/** OLE / ActiveX / embedded package object. */
 	embeddedObjectNotSupported: "render.embedded-object-not-supported",
+	/** SmartArt / diagram / unknown external graphic-data object. */
 	unsupportedObject: "render.drawing.unsupported-object",
+	/** VML structure outside any supported image-like subset. */
 	vmlUnsupported: "render.drawing.vml-unsupported",
+	/** VML image-like content that could not be promoted to a supported image. */
 	vmlImageUnsupported: "render.drawing.vml-image-unsupported",
+	/** Custom geometry command the extractor does not implement (e.g. `arcTo`). */
 	unsupportedGeometryCommand: "render.drawing.unsupported-geometry-command",
+	/** Anchor fields required for honest placement are unsupported. */
 	anchorUnsupported: "render.drawing.anchor-unsupported",
+	/** Wrap fields required for honest placement are unsupported. */
 	wrapUnsupported: "render.drawing.wrap-unsupported",
+	/** `mc:AlternateContent` had no supported choice and no usable fallback. */
 	altContentNoSupportedChoice: "render.drawing.altcontent-no-supported-choice",
+	/** A child of an otherwise-supported group is unsupported. */
 	groupChildUnsupported: "render.drawing.group-child-unsupported"
 };
-const DRAWING_DIAGNOSTIC_CODE_ALIASES = {
-	"render.media.missing-relationship": DRAWING_DIAGNOSTIC_CODES.missingRelationship,
-	"render.media.wrong-relationship-type": DRAWING_DIAGNOSTIC_CODES.unsupportedRelationshipType,
-	"render.media.unsupported-target": DRAWING_DIAGNOSTIC_CODES.unsupportedRelationshipType,
-	"render.media.invalid-image-size": DRAWING_DIAGNOSTIC_CODES.imageTooLarge,
-	"render.media-resolver-unavailable": DRAWING_DIAGNOSTIC_CODES.missingMediaPart,
-	"render.chart-not-supported": DRAWING_DIAGNOSTIC_CODES.unsupportedObject,
-	"render.textbox.vml-unsupported": DRAWING_DIAGNOSTIC_CODES.vmlUnsupported
-};
-const DRAWING_SUPPORT_TAXONOMY = {
+DRAWING_DIAGNOSTIC_CODES.missingRelationship, DRAWING_DIAGNOSTIC_CODES.unsupportedRelationshipType, DRAWING_DIAGNOSTIC_CODES.unsupportedRelationshipType, DRAWING_DIAGNOSTIC_CODES.imageTooLarge, DRAWING_DIAGNOSTIC_CODES.missingMediaPart, DRAWING_DIAGNOSTIC_CODES.unsupportedObject, DRAWING_DIAGNOSTIC_CODES.vmlUnsupported;
+/**
+* The frozen drawing support taxonomy.
+*
+* Invariants (enforced by `drawing-taxonomy.test.ts`):
+* - every `supported` family has a real contract target (`!== 'none'`);
+* - every `DrawingBlock`-targeted family declares a `drawingKind`;
+* - every `fail-closed` family declares a canonical `diagnostic`;
+* - every canonical diagnostic code is referenced by at least one fail-closed
+*   family;
+* - `deferred` families make no support claim (`contract: 'none'`, no
+*   diagnostic).
+*/
+var DRAWING_SUPPORT_TAXONOMY = {
 	inlineBitmap: {
 		family: "inlineBitmap",
 		support: "supported",
@@ -352,8 +417,8 @@ const DRAWING_SUPPORT_TAXONOMY = {
 		contract: "none"
 	}
 };
-const DRAWING_FAMILIES = Object.keys(DRAWING_SUPPORT_TAXONOMY);
-const PAGE_CHECKPOINT_DEPENDENCY_CLASSES = Object.freeze([
+Object.keys(DRAWING_SUPPORT_TAXONOMY);
+Object.freeze([
 	"multiple-sections",
 	"furniture-page-tokens",
 	"non-balanceable-multi-column-sections",
@@ -364,18 +429,31 @@ const PAGE_CHECKPOINT_DEPENDENCY_CLASSES = Object.freeze([
 	"tables",
 	"furniture-anchored-objects"
 ]);
+//#endregion
+//#region src/helpers/v2-review-mutation-impact.js
+/**
+* Classify the tracked-change identities carried by a v2 mutation event.
+*
+* Receipt entities are the durable invalidation contract between the document
+* kernel and derived review UI. Consumers can refresh `upsertIds` narrowly via
+* `trackChanges.get(...)`, drop `removedIds` immediately, and leave a bounded
+* full-list reconciliation as background verification. History results are
+* different: undo/redo can restore many identities at once, so consumers use
+* one authoritative catalog after render instead of issuing one read per id.
+*/
 function getV2TrackedChangeMutationImpact(event) {
 	if (event?.type !== "mutation:committed") return null;
 	const payload = event.origin === "history" ? event.result : event.receipt;
 	if (!payload || typeof payload !== "object") return null;
 	const upsertIds = /* @__PURE__ */ new Set();
 	const removedIds = /* @__PURE__ */ new Set();
+	/** @type {Array<{ from: string, to: string }>} */
 	const remappedPairs = [];
 	const collectEntity = (entry, into) => {
 		if (entry?.kind !== "entity" || entry.entityType !== "trackedChange") return;
 		if (typeof entry.entityId === "string" && entry.entityId.length > 0) into.add(entry.entityId);
 	};
-	const readEntityId$1 = (entry) => {
+	const readEntityId = (entry) => {
 		if (entry?.kind !== "entity" || entry.entityType !== "trackedChange") return null;
 		return typeof entry.entityId === "string" && entry.entityId.length > 0 ? entry.entityId : null;
 	};
@@ -385,8 +463,8 @@ function getV2TrackedChangeMutationImpact(event) {
 	if (Array.isArray(payload.removed)) payload.removed.forEach((entry) => collectEntity(entry, removedIds));
 	if (Array.isArray(payload.invalidatedRefs)) payload.invalidatedRefs.forEach((entry) => collectEntity(entry, removedIds));
 	if (Array.isArray(payload.remappedRefs)) for (const mapping of payload.remappedRefs) {
-		const fromId = readEntityId$1(mapping?.from);
-		const toId = readEntityId$1(mapping?.to);
+		const fromId = readEntityId(mapping?.from);
+		const toId = readEntityId(mapping?.to);
 		if (fromId) removedIds.add(fromId);
 		if (toId) upsertIds.add(toId);
 		if (fromId && toId && fromId !== toId) remappedPairs.push({
@@ -410,6 +488,8 @@ function readAllResolvedFact(event, receipt) {
 	if (event?.origin === "history" || !fact || fact.schemaVersion !== 1 || fact.targetKind !== "all" || fact.decision !== "accept" && fact.decision !== "reject" || fact.remainingLogicalCount !== 0 || typeof fact.catalogRevision !== "string" || !fact.catalogRevision || typeof fact.sourceCoverageRevision !== "string" || !fact.sourceCoverageRevision || !Number.isSafeInteger(fact.logicalTargetCount) || fact.logicalTargetCount <= 0 || !Number.isSafeInteger(fact.physicalCarrierCount) || fact.physicalCarrierCount < fact.logicalTargetCount || typeof fact.txId !== "string" || fact.txId !== receipt.txId || typeof fact.documentEpoch !== "string" || !Number.isSafeInteger(fact.commitSequence) || typeof fact.packagePreviousRevision !== "string" || typeof fact.packageNextRevision !== "string" || fact.packagePreviousRevision === fact.packageNextRevision) return null;
 	return fact;
 }
+//#endregion
+//#region src/helpers/v2-review-mutation-reconciler.js
 var normalizeIds = (values) => new Set(Array.from(values ?? []).filter((value) => typeof value === "string" && value.length > 0));
 var itemId = (item) => {
 	if (typeof item?.id === "string" && item.id.length > 0) return item.id;
@@ -418,6 +498,13 @@ var itemId = (item) => {
 	return null;
 };
 var contextMatches = (left, right) => left?.adapter === right?.adapter && left?.documentId === right?.documentId && left?.editor === right?.editor && left?.reconcileToken === right?.reconcileToken;
+/**
+* Reconcile tracked changes only after their canonical render has made the
+* read model observable. Command receipts use narrow reads; history results
+* use one authoritative catalog because undo/redo can restore hundreds of
+* identities in one transaction. An absent history identity only converges
+* when both catalog and source coverage are explicitly complete.
+*/
 function createV2ReviewMutationReconciler({ getContext, reconcile, hydrate, onReconciled }) {
 	const pendingUpserts = /* @__PURE__ */ new Map();
 	let pendingAllResolved = null;
@@ -485,7 +572,9 @@ function createV2ReviewMutationReconciler({ getContext, reconcile, hydrate, onRe
 			reconcileMode: "targeted"
 		});
 		if (!isCurrent(capturedGeneration, context)) return;
-		await notifyReconciled(context, clearResolved(idsFromResult(result), snapshot), result);
+		const resolvedIds = idsFromResult(result);
+		const clearedIds = clearResolved(resolvedIds, snapshot);
+		await notifyReconciled(context, clearedIds, result);
 		if (new Set([...snapshot].filter(([id, version]) => pendingUpserts.get(id) === version).map(([id]) => id)).size === 0) return;
 		const fallback = await hydrate(context, {
 			trackedChangesListMode: "interaction-prime",
@@ -493,7 +582,9 @@ function createV2ReviewMutationReconciler({ getContext, reconcile, hydrate, onRe
 			blocking: false
 		});
 		if (!isCurrent(capturedGeneration, context)) return;
-		await notifyReconciled(context, clearResolved(idsFromResult(fallback), snapshot), fallback);
+		const fallbackResolvedIds = idsFromResult(fallback);
+		const fallbackClearedIds = clearResolved(fallbackResolvedIds, snapshot);
+		await notifyReconciled(context, fallbackClearedIds, fallback);
 	};
 	const reconcileAuthoritativeSnapshot = async (context, snapshot, capturedGeneration) => {
 		const result = await hydrate(context, {
@@ -617,7 +708,7 @@ function createV2ReviewMutationReconciler({ getContext, reconcile, hydrate, onRe
 					resolve
 				});
 			});
-			const impactedIds = new Set([...normalizeIds(impact.upsertIds), ...normalizeIds(impact.removedIds)]);
+			const impactedIds = /* @__PURE__ */ new Set([...normalizeIds(impact.upsertIds), ...normalizeIds(impact.removedIds)]);
 			const capturedEntries = new Map([...impactedIds].flatMap((id) => {
 				const entry = pendingUpserts.get(id);
 				return entry ? [[id, entry]] : [];
@@ -671,7 +762,19 @@ function createV2ReviewMutationReconciler({ getContext, reconcile, hydrate, onRe
 		}
 	};
 }
-var V2_TYPING_COMMAND_KINDS = new Set([
+//#endregion
+//#region src/helpers/v2-typing-mutation-event.js
+/**
+* Command kinds whose committed mutations belong to the sustained typing
+* cadence class (insert / replace / plain paste / Backspace / Delete).
+*
+* The SuperDoc shell debounces per-keystroke review-row hydration for these
+* kinds instead of refreshing comments + tracked changes on every commit —
+* hydrating immediately per keystroke was a measured worker-read storm during
+* typing and backspace bursts. The `text.*` aliases cover integrations that
+* forward Document API style command ids rather than editable-input kinds.
+*/
+var V2_TYPING_COMMAND_KINDS = /* @__PURE__ */ new Set([
 	"insert-text",
 	"replace-text",
 	"plain-text-paste",
@@ -693,33 +796,158 @@ var V2_TYPING_COMMAND_KINDS = new Set([
 	"backspace:list-remove",
 	"backspace:list-outdent"
 ]);
-const isV2EditableTextMutationEvent = (event) => {
+/**
+* True when a forwarded v2 host event is a committed editable-input mutation
+* of the sustained-typing class, i.e. review-row hydration for it should be
+* debounced rather than fired immediately.
+*
+* Events without a forwarded `editableCommandKind` (programmatic Document API
+* mutations, history commits, unclassified structural commands) return false
+* so they keep hydrating immediately.
+*
+* @param {{ type?: string, origin?: string, editableCommandKind?: string } | null | undefined} event
+* @returns {boolean}
+*/
+var isV2EditableTextMutationEvent = (event) => {
 	if (event?.type !== "mutation:committed" || event.origin !== "command") return false;
 	return V2_TYPING_COMMAND_KINDS.has(event.editableCommandKind);
 };
-const SUPERDOC_UI_REASONS = {
+//#endregion
+//#region src/public/ui/reasons.ts
+/**
+* Stable public reason taxonomy for the v2-native `superdoc/ui` controller.
+*
+* These strings are the canonical, stable vocabulary the controller uses to
+* explain WHY a command or workflow handle is disabled, unsupported, deferred,
+* or otherwise fails closed. They are part of the public custom-UI contract:
+* consumer toolbars/panels can branch on them and migration docs reference
+* them. Once shipped, a value must not be repurposed — add a new member rather
+* than changing the meaning of an existing one.
+*
+* The reasons distinguish the failure-mode families a custom UI must tell
+* apart (see `plans/v2-custom-ui-toolbar-parity-plan-set.md`, Workstream 2):
+*
+*   - command unsupported by v2            → `command-unsupported`
+*   - reserved recognized/deferred command → `command-deferred`
+*   - editor / Document API not ready yet   → `not-ready`, `document-api-unavailable`
+*   - blocked by viewing / read-only state  → `document-readonly`
+*   - blocked by missing selection/context  → `selection-required`,
+*     `range-selection-required`, `context-unavailable`, `target-unresolved`,
+*     `target-not-visible`, `geometry-unavailable`
+*   - operation / host capability missing   → `operation-unavailable`,
+*     `host-capability-unavailable`, `bulk-decisions-disabled`
+*
+* Geometry results (`viewport.getRect`, `metadata.getRect`) carry a separate,
+* geometry-local `reason` vocabulary (`not-mounted`, `unresolved`,
+* `invalid-target`, `not-ready`, `unavailable`); see `ViewportRectResult`.
+* That vocabulary predates this taxonomy and is intentionally narrower.
+*/
+var SUPERDOC_UI_REASONS = {
+	/** The active editor is not mounted / ready yet. */
 	notReady: "not-ready",
+	/** The editor is ready but its Document API facade is not available or has not been published yet. */
 	documentApiUnavailable: "document-api-unavailable",
+	/** The document is in viewing / read-only mode, so mutating commands are blocked. */
 	documentReadonly: "document-readonly",
+	/** A selection is required and none is active. */
 	selectionRequired: "selection-required",
+	/** A non-empty (range) selection is required and the current selection is collapsed/empty. */
 	rangeSelectionRequired: "range-selection-required",
+	/** Required pointer / entity / document context could not be resolved. */
 	contextUnavailable: "context-unavailable",
+	/** Painted geometry for the target could not be resolved. */
 	geometryUnavailable: "geometry-unavailable",
+	/** A navigation / geometry target could not be resolved to a live document address. */
 	targetUnresolved: "target-unresolved",
+	/** A navigation target was resolved but could not be brought into the visible viewport. */
 	targetNotVisible: "target-not-visible",
+	/** The command is not supported by v2 at all. */
 	commandUnsupported: "command-unsupported",
+	/** Reserved migration reason for a recognized command that is intentionally deferred. */
 	commandDeferred: "command-deferred",
+	/**
+	* The command is a real v2 operation, but its required document context
+	* (the current table / row / column / cell) cannot be resolved from any
+	* public custom-UI state: `selection.current` exposes only text block ids,
+	* and no public operation resolves the table ancestry of a block. This is a
+	* precise, named context-facade gap — distinct from `command-deferred` — for
+	* the table cell-context command family.
+	*/
 	tableContextUnavailable: "table-context-unavailable",
+	/** The backing Document API / SuperDoc operation is not present on this host. */
 	operationUnavailable: "operation-unavailable",
+	/** Bulk accept/reject decisions are disabled unless the host opts in. */
 	bulkDecisionsDisabled: "bulk-decisions-disabled",
+	/** A host-owned capability (geometry, hit-test, navigation) is unavailable. */
 	hostCapabilityUnavailable: "host-capability-unavailable",
+	/** Undo / redo cannot run because the host history stack has no matching entry. */
 	historyEmpty: "history-empty",
+	/**
+	* The shared search/find surface is unavailable because the host does not
+	* expose a search facade (e.g. a pre-ready editor, a worker-backed v2 host,
+	* or a build without the search substrate). Search reads return empty and
+	* search actions fail closed rather than fabricating matches.
+	*/
 	searchUnavailable: "search-unavailable",
+	/** The search pattern is an invalid or unsafe regular expression. */
 	searchInvalidPattern: "search-invalid-pattern",
+	/**
+	* Find-and-replace is intentionally out of the first v2 search parity tranche.
+	* The shared search surface implements query / navigation only; replace and
+	* replace-all fail closed with this reason until replace ships. This is an
+	* explicit product posture, not a missing-capability accident.
+	*/
 	replaceUnsupported: "replace-unsupported",
+	/**
+	* The selection overlaps a content control (SDT) whose lock mode
+	* (`contentLocked` / `sdtContentLocked`) forbids styling its content — Word
+	* parity (SD-3274): the toolbar must not leave styling controls clickable
+	* when the style change cannot apply. Alignment / paragraph-level commands
+	* are never gated by this reason.
+	*/
 	contentControlLocked: "content-control-locked"
 };
-const BUILT_IN_COMMAND_IDS = {
+//#endregion
+//#region src/public/ui/commands.ts
+/**
+* Built-in command catalog for the v2-native UI controller.
+*
+* This module is the SINGLE SOURCE OF TRUTH for the controller's built-in
+* command ids, their aliases, how each one routes (public Document API
+* operation, public SuperDoc-instance method, tracked-change decision, or no
+* supported route yet), whether it mutates the document, how v1-style payloads
+* are normalized, and the stable fail-closed reason a recognized-but-unrouted
+* command reports. `create-super-doc-ui.ts` reads these descriptors; it no
+* longer carries an ad hoc route map.
+*
+* Posture (migration-only): every v1 headless-toolbar command id is present
+* here with an explicit disposition —
+*
+*   - `routed`      → backed by a public surface today (Document API operation,
+*                     SuperDoc-instance method, or tracked-change decision) and
+*                     browser-proven through `ui.commands.execute`;
+*   - `context-gap` → a real v2 operation whose required document context (the
+*                     current table / row / column / cell) cannot be resolved
+*                     from public custom-UI state; reports the precise, named
+*                     `table-context-unavailable` reason and fails closed;
+*   - `unsupported` → no clear public v2 equivalent (product decision) or an
+*                     unknown id; reports `command-unsupported` and fails closed.
+*
+* No routeable v1 toolbar command remains `command-deferred` (that disposition
+* stays in the type for migration scaffolding but is unused by the catalog).
+*
+* 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
+* `superdoc/ui` built-ins; the broader catalog below adds v1 headless-toolbar
+* coverage. Kept as a named export because it is part of the public `superdoc/ui`
+* surface (`verify-public-facade-emit.cjs`, consumer typechecks).
+*/
+var BUILT_IN_COMMAND_IDS = {
 	bold: "bold",
 	italic: "italic",
 	underline: "underline",
@@ -737,6 +965,7 @@ const BUILT_IN_COMMAND_IDS = {
 	bulletList: "bullet-list",
 	numberedList: "numbered-list"
 };
+/** Strip a trailing `pt` unit from v1-style font sizes (`"12pt"` → `"12"`). */
 function normalizeFontSizePayload(payload) {
 	const strip = (value) => typeof value === "string" ? value.replace(/\s*pt$/i, "").trim() : value;
 	if (typeof payload === "string") return strip(payload);
@@ -749,6 +978,12 @@ function normalizeFontSizePayload(payload) {
 	}
 	return payload;
 }
+/**
+* Normalize v1-style zoom payloads to the percentage `SuperDoc.setZoom`
+* expects (`100 === 100%`). Accepts `150`, `"150%"`, `"1.5"`, or `1.5`.
+* Percentages pass through as numbers; legacy fraction-style values in the
+* `0..5` range are converted to percentages (`1.5` → `150`).
+*/
 function normalizeZoomPayload(payload) {
 	const normalizeNumber = (value, percentLiteral) => {
 		if (!percentLiteral && value > 0 && value <= 5) return value * 100;
@@ -763,6 +998,12 @@ function normalizeZoomPayload(payload) {
 	if (typeof payload === "number" && Number.isFinite(payload)) return normalizeNumber(payload, false);
 	return payload;
 }
+/**
+* Normalize a measurement-unit payload to the `'in'` / `'cm'` form
+* `SuperDoc.setMeasurementUnit` expects. Accepts the canonical `'in'` / `'cm'`,
+* a `{ value }` wrapper, or common long forms (`"inches"`, `"centimeters"`).
+* An unrecognized value passes through so the instance method can reject it.
+*/
 function normalizeMeasurementUnitPayload(payload) {
 	const raw = payload && typeof payload === "object" && "value" in payload ? payload.value : payload;
 	if (raw === "in" || raw === "cm") return raw;
@@ -773,6 +1014,12 @@ function normalizeMeasurementUnitPayload(payload) {
 	}
 	return raw;
 }
+/**
+* Normalize a v1-style color payload to the `#RRGGBB` form the inline
+* `format.color` / `format.highlight` operations expect. Accepts `"#RRGGBB"`,
+* `"RRGGBB"`, or `{ value }`. `null` (clear) passes through unchanged; an
+* unrecognized value is returned as-is so the operation can reject it.
+*/
 function normalizeColorPayload(payload) {
 	const coerce = (value) => {
 		if (value === null) return null;
@@ -792,6 +1039,7 @@ function normalizeColorPayload(payload) {
 	}
 	return coerce(payload);
 }
+/** Unwrap a `{ value }` / `{ alignment } ` / `{ styleId }` wrapper to its scalar. */
 function unwrapScalar(payload, keys) {
 	if (payload && typeof payload === "object") {
 		const record = payload;
@@ -799,6 +1047,7 @@ function unwrapScalar(payload, keys) {
 	}
 	return payload;
 }
+/** Normalize a v1 alignment payload (`"left"`, `{ value }`, `"justified"`) to a `ParagraphAlignment`. */
 function normalizeAlignmentPayload(payload) {
 	const raw = unwrapScalar(payload, ["alignment", "value"]);
 	if (typeof raw !== "string") return raw;
@@ -806,6 +1055,11 @@ function normalizeAlignmentPayload(payload) {
 	if (v === "justified" || v === "both") return "justify";
 	return v;
 }
+/**
+* Normalize a v1 line-height payload to OOXML auto line spacing (240ths of a
+* line: 240 = single, 360 = 1.5×, 480 = double). A multiplier in the `0..10`
+* range is converted (`1.5` → `360`); a larger raw value passes through.
+*/
 function normalizeLineHeightPayload(payload) {
 	const raw = unwrapScalar(payload, [
 		"line",
@@ -816,6 +1070,7 @@ function normalizeLineHeightPayload(payload) {
 	if (!Number.isFinite(num) || num <= 0) return raw;
 	return num <= 10 ? Math.round(num * 240) : Math.round(num);
 }
+/** Preserve semantic style intent; normalize legacy linked-style payloads to a concrete ID. */
 function normalizeStyleIdPayload(payload) {
 	if (payload && typeof payload === "object" && "role" in payload) return payload;
 	const raw = unwrapScalar(payload, [
@@ -825,6 +1080,7 @@ function normalizeStyleIdPayload(payload) {
 	]);
 	return typeof raw === "string" ? raw.trim() : raw;
 }
+/** Resolve a document-mode payload (`"viewing"` or `{ mode }`) to the mode string. */
 function normalizeDocumentModePayload(payload) {
 	if (typeof payload === "string") return payload;
 	if (payload && typeof payload === "object") {
@@ -835,7 +1091,14 @@ function normalizeDocumentModePayload(payload) {
 }
 var UNSUPPORTED = SUPERDOC_UI_REASONS.commandUnsupported;
 var TABLE_CONTEXT = SUPERDOC_UI_REASONS.tableContextUnavailable;
-const COMMAND_CATALOG = [
+/**
+* The built-in command catalog. Order is documentation-only. Every v1
+* headless-toolbar id appears here with an explicit disposition; the 14
+* canonical v2 ids route today, the kebab track-change selection ids and the
+* zoom / document-mode ids are newly routed in this unit, and the remaining v1
+* workflows are deferred or marked product-unsupported with a stable reason.
+*/
+var COMMAND_CATALOG = [
 	{
 		id: "bold",
 		family: "inline marks",
@@ -1355,10 +1618,23 @@ const COMMAND_CATALOG = [
 	}
 ];
 var CATALOG_BY_ID = new Map(COMMAND_CATALOG.map((descriptor) => [descriptor.id, descriptor]));
-const ALL_BUILT_IN_COMMAND_IDS = COMMAND_CATALOG.map((d) => d.id);
+/** All built-in command ids known to the controller (routed + deferred + unsupported). */
+var ALL_BUILT_IN_COMMAND_IDS = COMMAND_CATALOG.map((d) => d.id);
+/** Resolve a command descriptor by id, or `null` when the id is unknown. */
 function getCommandDescriptor(id) {
 	return CATALOG_BY_ID.get(id) ?? null;
 }
+//#endregion
+//#region src/public/ui/equality.ts
+/**
+* Shallow equality used by the controller to suppress redundant slice
+* notifications. v2-native, dependency-free.
+*/
+/**
+* Returns `true` when `a` and `b` are the same reference, or are objects with
+* the same own-enumerable keys and `Object.is`-equal values one level deep.
+* Arrays compare by index. Primitives compare with `Object.is`.
+*/
 function shallowEqual(a, b) {
 	if (Object.is(a, b)) return true;
 	if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) return false;
@@ -1372,6 +1648,16 @@ function shallowEqual(a, b) {
 	}
 	return true;
 }
+//#endregion
+//#region src/public/ui/format-painter-helpers.js
+/**
+* Maps SDRunProps field names to InlineRunPatch field names.
+* SDRunProps (read-side) and InlineRunPatch (write-side) use different keys
+* for the same properties; direct assignment between them is forbidden.
+*
+* @param {Record<string, unknown>} props - SDRunProps object from doc.getNodeById
+* @returns {Record<string, unknown>} InlineRunPatch ready for doc.format.apply
+*/
 function sdRunPropsToInlineRunPatch(props) {
 	if (!props || typeof props !== "object") return {};
 	const patch = {};
@@ -1462,6 +1748,16 @@ function projectBorderToInlinePatch(border) {
 	if (color != null) patch.color = color;
 	return Object.keys(patch).length > 0 ? patch : void 0;
 }
+/**
+* Serializes a selection to a stable string key used to detect whether
+* the target selection is the same as the source (skip apply in that case).
+*
+* Falls back to the plain text target when the host has not populated an
+* explicit `selectionTarget` yet.
+*
+* @param {{ selectionTarget?: unknown; target?: unknown } | null | undefined} selection
+* @returns {string}
+*/
 function selectionKey(selection) {
 	const target = selection?.selectionTarget ?? selection?.target;
 	if (!selection || !target) return "";
@@ -1471,9 +1767,21 @@ function selectionKey(selection) {
 		return String(target);
 	}
 }
+//#endregion
+//#region src/public/ui/entity-at.ts
 function parseCommaSeparatedIds(value) {
 	return value.split(",").map((id) => id.trim()).filter(Boolean);
 }
+/**
+* Collect every public-id candidate a painted run can carry for a tracked
+* change, deduped, in priority order: the canonical
+* `data-track-change-preferred-target-id` first (when the painter stamps one),
+* then the `data-track-change-ids` list, then the singular
+* `data-track-change-id`. The caller validates these against the live
+* tracked-changes slice and keeps whichever is the public id, so it does not
+* matter which attribute carries it — an imported/raw alias on one attribute
+* never hides the public id on another (a union, not a prefer-one-attribute).
+*/
 function getTrackChangeIds(node) {
 	const out = [];
 	const add = (id) => {
@@ -1485,6 +1793,21 @@ function getTrackChangeIds(node) {
 	add(node.getAttribute("data-track-change-id"));
 	return out;
 }
+/**
+* Read painted entities off `el` and every ancestor up to the document root, or
+* up to and INCLUDING `stopAt` when given. Innermost-first ordering: a tracked
+* change inside a comment highlight returns `[{ trackedChange }, { comment }]`,
+* matching what a switch on `hits[0]` expects when picking the most specific
+* entity.
+*
+* `stopAt` bounds the walk to the visible host: its own attributes are read, but
+* the walk never climbs into an app wrapper ABOVE it, so wrapper data-* cannot
+* leak into the hits. Omitting it keeps the original walk-to-document-root.
+*
+* Returns `[]` for null / non-Element starts. Uses duck-typed `getAttribute`
+* access so it works under any DOM implementation (happy-dom, jsdom, real
+* browser) without an `instanceof` check that could fail across realms.
+*/
 function collectEntityHitsFromChain(start, stopAt) {
 	if (!start || typeof start.getAttribute !== "function") return [];
 	const hits = [];
@@ -1546,6 +1869,8 @@ function collectEntityHitsFromChain(start, stopAt) {
 	}
 	return hits;
 }
+//#endregion
+//#region ../document-api/src/format/inline-run-patch.ts
 var schemaBooleanOrNull = () => ({ oneOf: [{ type: "boolean" }, { type: "null" }] });
 var schemaStringOrNull = () => ({ oneOf: [{
 	type: "string",
@@ -1637,7 +1962,7 @@ var runAttribute = (key, type, ooxmlElement, schema, runPropertyKey) => ({
 	carrier: runAttributeCarrier(runPropertyKey ?? key),
 	schema
 });
-const INLINE_PROPERTY_REGISTRY = [
+var INLINE_PROPERTY_REGISTRY = [
 	markBoolean("bold", "w:b", "bold"),
 	markBoolean("italic", "w:i", "italic"),
 	markBoolean("strike", "w:strike", "strike"),
@@ -1794,12 +2119,24 @@ const INLINE_PROPERTY_REGISTRY = [
 	runAttribute("stylisticSets", "array", "w14:stylisticSets", schemaStylisticSets()),
 	runAttribute("contextualAlternates", "boolean", "w14:cntxtAlts", schemaBooleanOrNull())
 ];
-const INLINE_PROPERTY_KEY_SET = new Set(INLINE_PROPERTY_REGISTRY.map((entry) => entry.key));
-const INLINE_PROPERTY_BY_KEY = Object.fromEntries(INLINE_PROPERTY_REGISTRY.map((entry) => [entry.key, entry]));
-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)
-};
+new Set(INLINE_PROPERTY_REGISTRY.map((entry) => entry.key));
+var 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);
+//#endregion
+//#region src/public/ui/create-super-doc-ui.ts
+/**
+* v2-native `createSuperDocUI` controller.
+*
+* A small, truthful layer over the public v2 active-editor facade
+* (`superdoc.activeEditor`), its read-only-guarded Document API
+* (`activeEditor.doc`), and SuperDoc lifecycle events. No v1 editor imports,
+* no private v2 runtime imports. In browser mode the underlying Document API
+* facade is async-capable, so the controller normalizes it into live slices
+* plus promise-capable workflow helpers. Every document read/mutation is
+* attempted through the public Document API and degrades to a stable noop /
+* `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.
+*/
 var sharedUiTrackedChangesCatalogByHost = /* @__PURE__ */ new WeakMap();
 function acquireSharedUiTrackedChangesCatalog(host) {
 	let state = sharedUiTrackedChangesCatalogByHost.get(host);
@@ -1828,6 +2165,12 @@ 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;
 }
+/**
+* Normalize the host selection apply helper's return value for
+* `selection.apply` / `selection.restore`: host `{ ok: false, reason }`
+* results pass through (unknown reasons coerce to `target-unresolved`);
+* anything else — including legacy void/boolean returns — counts as success.
+*/
 function normalizeHostSelectionApplyResult(result) {
 	if (result && typeof result === "object") {
 		if (result.ok === false) {
@@ -1844,6 +2187,7 @@ function normalizeHostSelectionApplyResult(result) {
 	}
 	return { ok: true };
 }
+/** Lifecycle events the controller subscribes to. */
 var HOST_EVENTS = [
 	"document-replaced",
 	"editorCreate",
@@ -1854,6 +2198,12 @@ var HOST_EVENTS = [
 	"viewport-change",
 	"fonts-changed"
 ];
+/**
+* row-862 — list toolbar ids routed through the v2 editor host edit-command
+* surface (`activeEditor.editCommands.lists.apply`) rather than a raw one-off
+* `doc.lists.apply` mutation, so readiness / mount / selection / read-only
+* gating and command state stay coherent with the rest of the editor chrome.
+*/
 var LIST_TOGGLE_KINDS = {
 	[BUILT_IN_COMMAND_IDS.bulletList]: "bullet",
 	[BUILT_IN_COMMAND_IDS.numberedList]: "ordered"
@@ -1861,6 +2211,15 @@ var LIST_TOGGLE_KINDS = {
 function listToggleKind(id) {
 	return LIST_TOGGLE_KINDS[id] ?? null;
 }
+/**
+* SD-3571 — the built-in toolbar's bullet/numbered style dropdowns emit a bare
+* toolbar style-key string (e.g. `'upper-roman'`, `'decimal-paren'`) as the
+* command argument. Map each to the Document API `ListPresetId` so the chosen
+* glyph/number format actually applies instead of being dropped to the default
+* decimal/disc list. Keys mirror `internal/toolbar/built-in/list-style-buttons.js`
+* (asserted by a coverage test); the public command surface also still accepts
+* an options object with an explicit `preset`.
+*/
 var TOOLBAR_LIST_STYLE_PRESETS = {
 	disc: "disc",
 	circle: "circle",
@@ -1891,7 +2250,7 @@ var EMPTY_SELECTION = {
 	activeChangeIds: [],
 	quotedText: ""
 };
-const HEAVY_DOC_READ_POLICY = [
+var HEAVY_DOC_READ_POLICY = [
 	{
 		key: "contentControls",
 		match: "exact",
@@ -1938,19 +2297,22 @@ const HEAVY_DOC_READ_POLICY = [
 		note: "reserved: full sections list"
 	}
 ];
-var COMMENTS_CATALOG_PART_URIS = new Set([
+var COMMENTS_CATALOG_PART_URIS = /* @__PURE__ */ new Set([
 	"/word/comments.xml",
 	"/word/commentsExtended.xml",
 	"/word/commentsIds.xml"
 ]);
+/** Whether a coordinator cache key falls under the heavy-read policy. */
 function isHeavyDocReadKey(key) {
 	return HEAVY_DOC_READ_POLICY.some((entry) => entry.match === "exact" ? entry.key === key : key.startsWith(entry.key));
 }
+/** Status precedence: a combined status is as "unsettled" as its worst part. */
 var STATUS_RANK = {
 	ready: 0,
 	stale: 1,
 	pending: 2
 };
+/** Combine read statuses; `pending` (no data yet) dominates `stale`, which dominates `ready`. */
 function combineStatus(...statuses) {
 	let worst = "ready";
 	for (const status of statuses) if (STATUS_RANK[status] > STATUS_RANK[worst]) worst = status;
@@ -1968,6 +2330,7 @@ function safeCall(fn, fallback) {
 function isPromiseLike(value) {
 	return Boolean(value) && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
 }
+/** Resolve a dotted path (e.g. `format.bold`) to a callable on the doc facade. */
 function resolveDocOperation(doc, path) {
 	if (!doc) return null;
 	const parts = path.split(".");
@@ -2002,6 +2365,7 @@ function partialLinkEditFailure(hyperlinkResult, textResult) {
 		textResult
 	};
 }
+/** Read a stable public `target` off a doc-api entity row. */
 function readEntityTarget(row) {
 	if (!row || typeof row !== "object") return null;
 	const target = row.target;
@@ -2018,8 +2382,8 @@ function isHostGeometryTarget(target) {
 	const isTextSegment = (segment) => {
 		if (!segment || typeof segment !== "object") return false;
 		const candidate = segment;
-		const range$1 = candidate.range;
-		return typeof candidate.blockId === "string" && typeof range$1?.start === "number" && typeof range$1.end === "number";
+		const range = candidate.range;
+		return typeof candidate.blockId === "string" && typeof range?.start === "number" && typeof range.end === "number";
 	};
 	if (Array.isArray(record.segments)) {
 		const first = record.segments[0];
@@ -2031,6 +2395,12 @@ function isHostGeometryTarget(target) {
 	const range = record.range;
 	return typeof range?.start === "number" && typeof range.end === "number";
 }
+/**
+* Convert the tracked-change catalog's document-stable block address into the
+* text address accepted by the host geometry surface. Keeping the entity
+* address lets the host prefer the exact painted review carrier after the
+* containing block has been materialized.
+*/
 function readTrackedChangeNavigationTarget(row) {
 	if (!row || typeof row !== "object") return null;
 	const target = readEntityTarget(row);
@@ -2089,11 +2459,35 @@ function entityRowMatchesRequest(row, id, story) {
 	if (!story) return true;
 	return storyLocatorSignature(readEntityStory(row)) === storyLocatorSignature(story);
 }
+/**
+* Story to thread through a navigation / scroll request for a loaded list row:
+* the row's own non-body story, or `undefined` for body / story-less rows.
+* Mirrors `getAt`, which omits body stories from its hits, so body-only
+* documents keep their id-only matching byte-for-byte unchanged while a
+* non-body row (footnote / endnote / header / footer) pins target and carrier
+* resolution to its own story — an id repeated across stories can no longer
+* resolve to another story's occurrence (IT-1250).
+*/
 function readEntityRequestStory(row) {
 	const story = readEntityStory(row);
 	if (!story || storyLocatorSignature(story) === storyLocatorSignature(null)) return void 0;
 	return story;
 }
+/**
+* Bridge a painter `data-layout-story` value to the public Document API
+* {@link StoryLocator} shape the controller's story-aware matchers speak.
+*
+* The painter encodes the layout story as `"body"` or `"<kind>:<id>"`;
+* `decodeLayoutStoryDataset` turns that back into `{ kind, id }`. Tracked-change
+* rows, however, carry a Document API `StoryLocator` (`{ kind: 'story',
+* storyType, noteId | refId }`), and `storyLocatorSignature` keys on
+* `storyType`, so the two forms must be reconciled before they can be compared.
+* Body, unknown, and id-less stories all return `undefined` so callers fall back
+* to id-only matching and never stamp a story onto the public hit — that keeps
+* body-only documents byte-for-byte unchanged. Story disambiguation only kicks
+* in for the non-body stories (footnote, endnote, header/footer) that can repeat
+* a tracked-change id across stories.
+*/
 function layoutStoryDatasetToStoryLocator(raw) {
 	if (typeof raw !== "string" || raw.length === 0) return void 0;
 	const decoded = decodeLayoutStoryDataset(raw);
@@ -2118,6 +2512,22 @@ function layoutStoryDatasetToStoryLocator(raw) {
 		default: return;
 	}
 }
+/**
+* Bridge a painter `data-story-key` value to the public Document API
+* {@link StoryLocator} shape. PREFERRED over {@link layoutStoryDatasetToStoryLocator}
+* for tracked changes: the run/marker element carries the real owning story in
+* `data-story-key` (`'body'`, `'fn:<noteId>'`, `'en:<noteId>'`,
+* `'hf:part:<refId>'`), while the layout fragment's `data-layout-story` falls
+* back to `'body'` for the footnote/endnote band — so reading only the layout
+* story loses the story identity needed to disambiguate repeated source ids.
+*
+* Split on the FIRST delimiter group only: the `fn:`/`en:` id and the `hf:part:`
+* refId are taken verbatim after their prefix, so an id that itself contains a
+* colon survives intact. The resulting shapes match what `storyLocatorSignature`
+* keys on and what the all-story `list({ in: 'all' })` rows carry. Body, empty,
+* and unknown keys return `undefined` so callers fall back to id-only matching
+* and body-only documents stay byte-for-byte unchanged.
+*/
 function storyKeyToStoryLocator(raw) {
 	if (typeof raw !== "string" || raw.length === 0 || raw === "body") return void 0;
 	if (raw.startsWith("hf:part:")) {
@@ -2145,6 +2555,7 @@ function storyKeyToStoryLocator(raw) {
 		} : void 0;
 	}
 }
+/** Read a public `selectionTarget` off a content-control row when available. */
 function readSelectionTarget(row) {
 	if (!row || typeof row !== "object") return null;
 	const target = row.selectionTarget;
@@ -2166,12 +2577,19 @@ function collapseSelectionTargetToCaret(target) {
 		end: start
 	};
 }
+/** Read a stable public row id from discovery/list/detail shapes. */
 function readEntityId(row) {
 	if (!row || typeof row !== "object") return null;
 	const record = row;
 	const id = record.id ?? record.commentId ?? record.changeId;
 	return typeof id === "string" && id.length > 0 ? id : null;
 }
+/**
+* Read the tracked-change carrier shared by both ends of a collapsed host
+* selection. Unlike the public sync seed, this painted caret metadata is
+* available without a worker read and proves that the caret still belongs to
+* the same review carrier.
+*/
 function readCollapsedHostTrackChangeId(snapshot) {
 	if (!snapshot || typeof snapshot !== "object") return null;
 	const record = snapshot;
@@ -2184,6 +2602,11 @@ function readCollapsedHostTrackChangeId(snapshot) {
 	return typeof anchorId === "string" && anchorId.length > 0 && anchorId === focusId ? anchorId : null;
 }
 var trackedChangeIdContextCache = /* @__PURE__ */ new WeakMap();
+/**
+* Collect the raw source-provenance ids a tracked-change list item exposes,
+* reading from both the top-level row and its nested `change` payload (the
+* public projection surfaces provenance on either shape).
+*/
 function readTrackChangeProvenanceIds(item) {
 	const out = [];
 	const push = (value) => {
@@ -2224,6 +2647,7 @@ function readTrackChangeProvenanceIds(item) {
 	if (change && change !== item) scan(change);
 	return out;
 }
+/** Build (or reuse) the alias↔canonical context for a tracked-change list slice. */
 function buildTrackedChangeIdContext(items) {
 	const cached = trackedChangeIdContextCache.get(items);
 	if (cached) return cached;
@@ -2256,6 +2680,19 @@ function buildTrackedChangeIdContext(items) {
 }
 var storyScopedTrackedChangeIdContextCache = /* @__PURE__ */ new WeakMap();
 var declaredBodyItemsCache = /* @__PURE__ */ new WeakMap();
+/**
+* Alias↔canonical context scoped to the rows in a single `story`.
+*
+* {@link buildTrackedChangeIdContext} keys aliases purely on the raw Word
+* `w:id` / `imported:<id>` painter form, so when body / footnote / header
+* changes reuse the same `w:id`, the first row inserted wins the alias for
+* EVERY story. A click in a later story would then map through
+* `toPublicId` to the first story's public id and get dropped by the
+* subsequent `entityRowMatchesRequest(..., story)` check (or focus the wrong
+* same-story split). Restricting the alias map to same-story candidates keeps
+* each story's ids independent so the reconciliation resolves within the
+* painted story. Falls back to id-only when the row carries no comparable story.
+*/
 function buildStoryScopedTrackedChangeIdContext(items, story) {
 	const signature = storyLocatorSignature(story);
 	let byStory = storyScopedTrackedChangeIdContextCache.get(items);
@@ -2272,6 +2709,21 @@ function buildStoryScopedTrackedChangeIdContext(items, story) {
 function isTextboxStory(story) {
 	return !!story && typeof story === "object" && story.storyType === "textbox";
 }
+/**
+* Resolve a textbox selection against rows that carry no story locator.
+*
+* Textbox rows arrive from the v2 adapter without a comparable locator, but body
+* rows omit theirs too (body is the documented default). A missing story is
+* therefore not proof of textbox ownership: when a textbox change and a body
+* change reuse one Word revision id, live selection can supply both canonical
+* ids, and taking the first story-less match would publish whichever the catalog
+* happened to list first.
+*
+* The signal is a shared revision id, not a count. A selection spanning several
+* independent changes in one textbox is ordinary — those ids describe different
+* revisions and the first is the right active one. Two ids tracing back to the
+* same revision id are the ambiguous case, and that fails closed.
+*/
 function resolveStorylessCanonicalTrackedChangeId(items, selectionIds) {
 	const storyless = selectionIds.filter((id) => items.some((item) => readEntityId(item) === id && readEntityStory(item) == null));
 	if (storyless.length === 0) return null;
@@ -2287,6 +2739,13 @@ function resolveStorylessCanonicalTrackedChangeId(items, selectionIds) {
 	}
 	return storyless[0];
 }
+/**
+* Keep only rows that explicitly declare a story locator.
+*
+* A missing locator is not the same claim as `{ storyType: 'body' }`, but both
+* share the body story signature. Filtering the undeclared rows out keeps a body
+* selection from aliasing onto one of them.
+*/
 function declaredBodyItems(items) {
 	const cached = declaredBodyItemsCache.get(items);
 	if (cached) return cached;
@@ -2295,6 +2754,17 @@ function declaredBodyItems(items) {
 	declaredBodyItemsCache.set(items, result);
 	return result;
 }
+/**
+* Map `selection.activeChangeIds` to a public tracked-change id for
+* `TrackChangesSlice.activeId`.
+*
+* Prefer the live selection's story against the all-story catalog so a
+* footnote/header/footer alias that reuses a Word revision id cannot resolve
+* to a colliding body change. Unscoped body mapping is only for body
+* selection. While the all-story catalog is unsettled for a non-body
+* selection, keep activeId null rather than publishing an unvalidated raw
+* painter alias or canonical-looking id.
+*/
 function resolveSelectionActiveChangeId(options) {
 	const { selectionIds, publicIds, selection, bodyItems, allStoryItems } = options;
 	if (selectionIds.length === 0) return null;
@@ -2319,11 +2789,20 @@ function resolveSelectionActiveChangeId(options) {
 	if (isBodySelection) return mapIds(buildTrackedChangeIdContext(bodyItems)) ?? selectionIds[0] ?? null;
 	return null;
 }
+/**
+* Resolve a requested comment activation id to its thread's canonical active
+* id. Accepts a bare `id`, the `importedId` v2 minted when it had to repair
+* a malformed/duplicated source comment id on import, or a reply's id - all
+* resolve to the same thread-root comment, matching main's accepted aliases
+* for `ui.comments.setActive`. Returns `null` when `commentId` matches no
+* currently loaded comment under either alias.
+*/
 function resolveActiveCommentId(items, commentId) {
 	const item = items.find((candidate) => readEntityId(candidate) === commentId || candidate.importedId === commentId);
 	if (!item) return null;
 	return item.rootCommentId ?? item.parentCommentId ?? readEntityId(item) ?? commentId;
 }
+/** Derive a `{ startBlockId, endBlockId }` block range from a selection slice. */
 function selectionBlockRange(selection) {
 	const sel = selection.selectionTarget;
 	if (sel) {
@@ -2346,6 +2825,16 @@ function selectionBlockRange(selection) {
 	};
 	return null;
 }
+/**
+* Distinct block ids the selection covers, in document order. In the v2 adapter
+* the selection's `blockId` is the same identifier the public block operations
+* accept as `nodeId` (both resolve to the OOXML `paraId`), so these are valid
+* `nodeId`s for `format.paragraph.*` / `styles.paragraph.*` / `lists.*`.
+*
+* A collapsed caret still yields its containing block id (the v2
+* `selection.current` returns a zero-length text segment), so paragraph/list
+* commands work from a caret — they do not require a range selection.
+*/
 function selectionBlockIds(selection) {
 	const ids = [];
 	const push = (id) => {
@@ -2365,6 +2854,7 @@ var MAX_REACTIVE_SELECTION_BLOCK_READS = 64;
 function canProbeEverySelectedBlock(blockIds) {
 	return blockIds.length <= MAX_REACTIVE_SELECTION_BLOCK_READS;
 }
+/** Resolve the selection's story, defaulting to the main body story. */
 function selectionStory(selection) {
 	const target = selection.target;
 	const explicit = selection.selectionTarget;
@@ -2376,6 +2866,7 @@ function selectionStory(selection) {
 		storyType: "body"
 	};
 }
+/** Build a `ParagraphTarget` ( `format.paragraph.*` / `styles.paragraph.*` ). */
 function paragraphTarget(blockId, story) {
 	return {
 		kind: "block",
@@ -2384,6 +2875,7 @@ function paragraphTarget(blockId, story) {
 		...story && typeof story === "object" ? { story } : {}
 	};
 }
+/** Build a `ListsBlockTarget` ( `lists.apply` / `lists.remove` / `lists.getState` ). */
 function listsBlockTarget(blockId) {
 	return {
 		kind: "block",
@@ -2391,6 +2883,7 @@ function listsBlockTarget(blockId) {
 		nodeId: blockId
 	};
 }
+/** Build a `ListItemAddress` ( `lists.indent` / `lists.outdent` / `lists.applyStyle` ). */
 function listItemTarget(blockId, story) {
 	return {
 		kind: "block",
@@ -2428,6 +2921,7 @@ function readParagraphIndentationFromResult(result) {
 		...hanging != null ? { hanging } : {}
 	};
 }
+/** Build one `TextAddress` per covered text segment for `hyperlinks.wrap`. */
 function selectionTextAddresses(selection) {
 	const target = selection.target;
 	const segments = target && Array.isArray(target.segments) ? target.segments : [];
@@ -2569,12 +3063,12 @@ function selectionTextSegments(selection) {
 	const target = selection.target;
 	const segments = target && Array.isArray(target.segments) ? target.segments : [];
 	const out = [];
-	const push = (blockId, start$1, end$1) => {
-		if (typeof blockId !== "string" || typeof start$1 !== "number" || typeof end$1 !== "number") return;
+	const push = (blockId, start, end) => {
+		if (typeof blockId !== "string" || typeof start !== "number" || typeof end !== "number") return;
 		out.push({
 			blockId,
-			start: Math.min(start$1, end$1),
-			end: Math.max(start$1, end$1)
+			start: Math.min(start, end),
+			end: Math.max(start, end)
 		});
 	};
 	for (const segment of segments) {
@@ -2614,6 +3108,12 @@ function selectionInlineValueSignature(selection) {
 	if (segments.length === 0) return null;
 	return [selectionInlineValueStorySignature(selection), ...segments.map((segment) => `${segment.blockId}:${segment.start}-${segment.end}`)].join("|");
 }
+/**
+* The effective-uniformity worker operation accepts the durable
+* `selectionTarget`, not the expanded segment list. Whole-story segment lists
+* grow as source coverage arrives, so using them as this cache key restarts the
+* same worker read indefinitely while the document is loading.
+*/
 function selectionEffectiveUniformitySignature(selection) {
 	const target = selection.selectionTarget;
 	if (!target || typeof target !== "object") return null;
@@ -2656,6 +3156,11 @@ function sameSelectionTextSegments(left, right) {
 		return candidate?.blockId === segment.blockId && candidate?.start === segment.start && candidate?.end === segment.end;
 	});
 }
+/**
+* Pick the `query.match` result item that best covers the selection. Pure over
+* a settled query result so the controller's async read coordinator owns the
+* (promise-capable) `query.match` call and this stays a synchronous projection.
+*/
 function pickSelectionTextQueryItem(result, selection) {
 	const segments = selectionTextSegments(selection);
 	if (segments.length === 0) return null;
@@ -2681,6 +3186,7 @@ function readProjectedInlineStyleValue(styles, key) {
 	if (key === "color" || key === "highlight") return trimmed.toUpperCase();
 	return trimmed;
 }
+/** Primary named family from a resolved CSS font stack, dropping generic fallbacks (SD-3652). */
 function normalizeLayoutFontFamily(value) {
 	if (typeof value !== "string") return void 0;
 	const first = value.split(",")[0]?.trim().replace(/^['"]+|['"]+$/g, "").trim();
@@ -2689,6 +3195,7 @@ function normalizeLayoutFontFamily(value) {
 	if (lower === "serif" || lower === "sans-serif" || lower === "monospace" || lower === "cursive" || lower === "fantasy") return;
 	return first;
 }
+/** Convert a resolved run font size in CSS px to the toolbar's point value (SD-3652). */
 function normalizeLayoutFontSizePt(value) {
 	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return void 0;
 	const pt = Math.round(value * .75 * 2) / 2;
@@ -2749,6 +3256,7 @@ function projectInlineValuesFromQueryItem(item, selection) {
 	}
 	return projection;
 }
+/** A create-location `at` derived from the current block, or `documentEnd`. */
 function createLocationAt(selection, mode) {
 	const blockId = selectionBlockIds(selection)[0];
 	if (!blockId) return { kind: "documentEnd" };
@@ -2810,6 +3318,12 @@ function commandResultSucceeded(result) {
 function isLooseObject(value) {
 	return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
+/**
+* Flatten mounted projection blocks into text-bearing blocks (those with a
+* `runs` array), descending into table rows/cells so table-cell content is
+* reachable (SD-3652). A block carries either `runs` (paragraph) or `rows`
+* (table); nested tables recurse.
+*/
 function collectProjectionTextBlocks(blocks) {
 	const out = [];
 	const visit = (node) => {
@@ -2829,6 +3343,7 @@ function collectProjectionTextBlocks(blocks) {
 	if (Array.isArray(blocks)) for (const block of blocks) visit(block);
 	return out;
 }
+/** A projection block matches a selection block id by `sourceAnchor.sourceNodeId` or `block.id`. */
 function projectionBlockMatchesId(block, id) {
 	if (block.sourceAnchor?.sourceNodeId === id) return true;
 	return block.id === id;
@@ -2877,6 +3392,7 @@ function hyperlinkTargetFromHref(href) {
 		url: href
 	};
 }
+/** Tracked-change decision spec for a command id, from the descriptor catalog. */
 function trackDecisionCommand(id) {
 	return getCommandDescriptor(id)?.trackDecision ?? null;
 }
@@ -2888,6 +3404,7 @@ function rectResult(rects) {
 		rect: rects[0]
 	};
 }
+/** Fail-closed empty geometry result carrying a stable reason. */
 function rectFailure(reason) {
 	return {
 		found: false,
@@ -2896,6 +3413,7 @@ function rectFailure(reason) {
 		reason
 	};
 }
+/** Offset client-space rects so they are relative to `relativeTo`, when given. */
 function relativizeRects(result, relativeTo) {
 	if (!relativeTo || typeof relativeTo.getBoundingClientRect !== "function" || result.rects.length === 0) return result;
 	let origin;
@@ -2921,6 +3439,16 @@ function relativizeRects(result, relativeTo) {
 		rect: rects[0]
 	};
 }
+/**
+* Whether a text-target segment carries the addressable shape AND the value
+* invariants the derived selection target relies on (`blockId` string plus a
+* `range` of valid integer bounds, `start >= 0` and `start <= end` — the
+* documented `TextTarget` contract). Captures can be stale or deserialized from
+* a host store, so entries are validated instead of trusted: a segment that is
+* malformed (missing `range`) or out of bounds (negative, non-integer, or
+* inverted) makes the caller return `null` (fail closed) rather than throw
+* mid-derivation or restore a clamped, different range than was captured.
+*/
 function isAddressableSegment(segment) {
 	if (!segment || typeof segment !== "object") return false;
 	const candidate = segment;
@@ -2956,6 +3484,15 @@ function selectionTargetForRestore(capture) {
 	if (capture.selectionTarget) return capture.selectionTarget;
 	return selectionTargetFromTextTarget(capture.target);
 }
+/**
+* Resolve the live selection slice to a `SelectionTarget` the inline
+* `format.*` operations accept. Returns the explicit `selectionTarget` when the
+* source provides one, otherwise derives a same-story selection target from the
+* resolved text target's first/last covered segments. Returns `null` when the
+* selection is empty or has no resolvable range — the inline command then fails closed with
+* `range-selection-required` rather than calling `format.*` with a missing
+* target (which the public Document API rejects with `INVALID_INPUT`).
+*/
 function resolveInlineSelectionTarget(selection) {
 	if (selection.empty) return null;
 	if (selection.selectionTarget) return selection.selectionTarget;
@@ -2963,10 +3500,17 @@ function resolveInlineSelectionTarget(selection) {
 	if (fallback && fallback.start.kind === "text" && fallback.end.kind === "text" && fallback.start.blockId !== fallback.end.blockId) return null;
 	return fallback;
 }
+/**
+* The `format.*` method name a stored inline mark is keyed by (SD-3654). The
+* host store and the toggle command both address a mark by its Document API
+* method (`docRoute` minus the `format.` prefix), which differs from the inline
+* `key` for strikethrough (`key: 'strike'` vs `docRoute: 'format.strikethrough'`).
+*/
 function inlineFormatMethod(descriptor) {
 	if (!descriptor.inline || typeof descriptor.docRoute !== "string") return null;
 	return descriptor.docRoute.startsWith("format.") ? descriptor.docRoute.slice(7) : null;
 }
+/** Inline run-property keys cleared by `clear-formatting` via `format.apply`. */
 var CLEAR_INLINE_PATCH = {
 	bold: null,
 	italic: null,
@@ -2982,7 +3526,22 @@ var CLEAR_INLINE_PATCH = {
 	letterSpacing: null,
 	dstrike: null
 };
+/**
+* Subset of `CLEAR_INLINE_PATCH` whose registry entry supports tracked
+* changes. Tracked `format.apply` rejects the whole patch with
+* `CAPABILITY_UNAVAILABLE` if any key isn't `tracked: true` (e.g. `smallCaps`,
+* `dstrike`), regardless of whether the selection actually carries them, so
+* suggesting mode must send this filtered patch instead of the full one.
+*/
 var TRACKED_CLEAR_INLINE_PATCH = Object.fromEntries(Object.entries(CLEAR_INLINE_PATCH).filter(([key]) => INLINE_PROPERTY_BY_KEY[key]?.tracked === true));
+/**
+* Build the public Document API input for an inline-format command from the
+* resolved selection target, the normalized payload, and the command's live
+* active state. Boolean mark commands can also receive an explicit boolean/null
+* payload, which is useful for hosts that know the desired state themselves.
+* Returns `null` when the payload is invalid for the spec (so the controller
+* fails closed instead of forwarding a malformed value).
+*/
 function buildInlineFormatInput(spec, target, payload, active) {
 	switch (spec.kind) {
 		case "toggle": {
@@ -3024,6 +3583,7 @@ function buildInlineFormatInput(spec, target, payload, active) {
 		default: return null;
 	}
 }
+/** Read a `{ start, end }` cell-range from the host snapshot, when well-formed. */
 function readMergeRange(range) {
 	const point = (value) => {
 		if (!value || typeof value !== "object") return null;
@@ -3046,6 +3606,12 @@ function readMergeRange(range) {
 		end
 	};
 }
+/**
+* Build the public `tables.*` input for a table cell-context command from the
+* resolved table context. Returns `null` when the action's required context is
+* missing (e.g. split with no resolved cell), so the controller fails closed
+* with `table-context-unavailable` rather than calling with a malformed locator.
+*/
 function buildTableCommandInput(action, context) {
 	const { tableNodeId: nodeId, rowIndex, columnIndex, cellNodeId, mergeRange } = context;
 	switch (action) {
@@ -3134,18 +3700,22 @@ function createSuperDocUI(options) {
 	let frozenProjectedValues = {};
 	let frozenProjectedValuesKey = "";
 	let heldSettledInlineValues = null;
+	/** Read the live active editor (or null). */
 	const getEditor = () => {
 		const editor = superdoc?.activeEditor;
 		return editor && typeof editor === "object" ? editor : null;
 	};
+	/** Read the live browser Document API facade (or null). */
 	const getDoc = () => {
 		const doc = getEditor()?.doc;
 		return doc && typeof doc === "object" ? doc : null;
 	};
+	/** Read the live v2 tracked-change facade, when exposed. */
 	const getV2TrackedChanges = () => {
 		const trackedChanges = getEditor()?.v2TrackedChanges;
 		return trackedChanges && typeof trackedChanges === "object" ? trackedChanges : null;
 	};
+	/** Read the live v2 editor host (inline mode only), when exposed. */
 	const getHost = () => {
 		const host = getEditor()?.host;
 		return host && typeof host === "object" ? host : null;
@@ -3184,6 +3754,7 @@ function createSuperDocUI(options) {
 		}
 		return null;
 	};
+	/** Read the host's stored inline marks (SD-3654/SD-3652), when any pending. */
 	const readPendingInlineFormat = () => {
 		const host = getHost();
 		const fn = host?.getPendingInlineFormat;
@@ -3191,6 +3762,11 @@ function createSuperDocUI(options) {
 		const pending = safeCall(() => fn.call(host), null);
 		return pending && typeof pending === "object" ? pending : null;
 	};
+	/**
+	* Active state contributed by a stored inline mark for this command, or null
+	* when nothing is pending for it (SD-3654). Only meaningful for a collapsed
+	* caret; the store is cleared on any selection move, so a range never has one.
+	*/
 	const pendingInlineActive = (descriptor) => {
 		const method = inlineFormatMethod(descriptor);
 		if (!method) return null;
@@ -3200,6 +3776,7 @@ function createSuperDocUI(options) {
 		if (descriptor.inline?.kind === "toggle") return value === true;
 		return value != null && value !== "";
 	};
+	/** The pending caret font/size value for this command's `format.*` method, if any (SD-3652). */
 	const pendingInlineValueFor = (descriptor) => {
 		const method = inlineFormatMethod(descriptor);
 		if (!method) return void 0;
@@ -3209,6 +3786,7 @@ function createSuperDocUI(options) {
 		if (typeof value === "string" && value !== "") return value;
 		if (typeof value === "number" && Number.isFinite(value)) return String(value);
 	};
+	/** Record / clear the stored inline mark for a collapsed-caret pick (SD-3654/SD-3652). */
 	const setPendingInlineFormatOnHost = (method, value) => {
 		const host = getHost();
 		const fn = host?.setPendingInlineFormat;
@@ -3219,16 +3797,23 @@ function createSuperDocUI(options) {
 		const fn = host?.clearPendingInlineFormat;
 		if (typeof fn === "function") safeCall(() => fn.call(host, method), void 0);
 	};
-	const BOOLEAN_INLINE_FORMAT_METHODS = new Set([
+	/** Inline `format.*` methods whose active state is a boolean mark (name === method). */
+	const BOOLEAN_INLINE_FORMAT_METHODS = /* @__PURE__ */ new Set([
 		"bold",
 		"italic",
 		"underline",
 		"strikethrough"
 	]);
-	const reconcilePendingInlineFormat = (selection$1) => {
+	/**
+	* Retire a stored inline mark (SD-3654/SD-3652) once the selection's own
+	* formatting has caught up to it: a boolean mark when the live activeMarks
+	* match, a font/size when the projection matches. Runs each recompute so the
+	* toolbar hands off from "pending" to the real marks/value without a gap.
+	*/
+	const reconcilePendingInlineFormat = (selection) => {
 		const pending = readPendingInlineFormat();
 		if (!pending) return;
-		const activeMarks = Array.isArray(selection$1.activeMarks) ? selection$1.activeMarks : [];
+		const activeMarks = Array.isArray(selection.activeMarks) ? selection.activeMarks : [];
 		let projected = null;
 		for (const method of Object.keys(pending)) {
 			const value = pending[method];
@@ -3236,33 +3821,47 @@ function createSuperDocUI(options) {
 			if (BOOLEAN_INLINE_FORMAT_METHODS.has(method)) matched = activeMarks.includes(method) === (value === true);
 			else if (isProjectedInlineSelectionValueKey(method)) {
 				if (value == null) continue;
-				if (!projected) projected = projectSelectionInlineValues(selection$1);
+				if (!projected) projected = projectSelectionInlineValues(selection);
 				matched = projected[method] === value;
 			} else matched = false;
 			if (matched) clearPendingInlineFormatOnHost(method);
 		}
 	};
+	/** Read the live v2 edit-command adapters (`activeEditor.editCommands`), when exposed. */
 	const getEditCommands = () => {
 		const editCommands = getEditor()?.editCommands;
 		return editCommands && typeof editCommands === "object" ? editCommands : null;
 	};
+	/** Read one edit-command snapshot entry (`activeEditor.editCommands.getSnapshot().commands[id]`). */
 	const readEditCommandStateEntry = (commandId) => {
 		const editCommands = getEditCommands();
 		if (!editCommands || typeof editCommands.getSnapshot !== "function") return null;
 		const entry = (safeCall(() => editCommands.getSnapshot(), null)?.commands)?.[commandId];
 		return entry && typeof entry === "object" ? entry : null;
 	};
+	/** Read the `lists.apply` command state surfaced by the v2 edit-command snapshot. */
 	const readListApplyStateEntry = () => {
 		return readEditCommandStateEntry("lists.apply");
 	};
+	/** Read the additive list active state surfaced by the edit-command snapshot. */
 	const readListActiveSeed = (entry) => {
 		const seed = (entry?.value)?.seed;
 		return seed === "bullet" || seed === "ordered" ? seed : null;
 	};
+	/** Read the lower host-state entry mirrored into the public `undo` / `redo` ids. */
 	const readMirroredEditCommandStateEntry = (commandId) => {
 		const mirrored = MIRRORED_EDIT_COMMAND_IDS[commandId];
 		return mirrored ? readEditCommandStateEntry(mirrored) : null;
 	};
+	/**
+	* Shared table-context resolution. Reads the V2 host table-context facade
+	* (`host.getTableContext()`) — the single public surface that resolves the
+	* current selection's enclosing table without private editor internals — and
+	* normalizes it to the locator inputs the `tables.*` operations need. Returns
+	* `null` when the caret is not inside a table, the host does not expose the
+	* facade, or the snapshot is missing the table node id / indices. Both the
+	* built-in toolbar authority and custom UIs consume this same resolution.
+	*/
 	const readHostTableContext = () => {
 		const host = getHost();
 		if (!host || typeof host.getTableContext !== "function") return null;
@@ -3329,11 +3928,11 @@ function createSuperDocUI(options) {
 		if (typeof review.getActiveReviewTarget !== "function" || typeof review.clearActiveReviewTarget !== "function") return;
 		if (safeCall(() => review.getActiveReviewTarget(), null)?.entityType === "trackedChange") safeCall(() => review.clearActiveReviewTarget(), void 0);
 	};
-	const setExplicitActiveChange = (next, options$1) => {
+	const setExplicitActiveChange = (next, options) => {
 		explicitActiveChange = next;
 		explicitActiveChangeRevision += 1;
 		trackChangeRevealInvalidation += 1;
-		if (options$1?.invalidateQueuedNavigation !== false) queuedTrackChangeNavigationInvalidation += 1;
+		if (options?.invalidateQueuedNavigation !== false) queuedTrackChangeNavigationInvalidation += 1;
 	};
 	const listeners = /* @__PURE__ */ new Set();
 	let disposed = false;
@@ -3455,6 +4054,7 @@ function createSuperDocUI(options) {
 	let allTrackedChangesResolvedToken = null;
 	let selectionEpoch = 0;
 	let lastCoordinatorEditor = null;
+	/** Token shared by document-content reads (editor identity + mutation revision). */
 	const contentToken = () => `${editorIdentityId(getEditor())}|m${documentMutationRevision}`;
 	const clearPostDecisionTrackChanges = () => {
 		postDecisionTrackChangesToken = null;
@@ -3531,6 +4131,14 @@ function createSuperDocUI(options) {
 		};
 		notifyPostDecisionTrackChanges(receipt);
 	};
+	/**
+	* Publish the exact empty catalog proved by an all-resolved receipt.
+	* Reject All does not carry one removed ref per logical change, so the
+	* ordinary identity-pruning path cannot clear selection-derived focus or
+	* the slice total. Keep this proof scoped to the current content token: the
+	* next independent document mutation advances the token and resumes normal
+	* catalog/selection reads.
+	*/
 	const publishAllTrackedChangesResolved = (receipt) => {
 		const previous = state.trackChanges;
 		const changed = previous.items.length > 0 || previous.total !== 0 || previous.activeId !== null || previous.authors.length > 0;
@@ -3555,11 +4163,18 @@ function createSuperDocUI(options) {
 		const newlyRemoved = new Set([...ids].filter((id) => !alreadyRemoved.has(id)));
 		if (newlyRemoved.size === 0) return;
 		postDecisionTrackChangesToken = token;
-		postDecisionTrackChangeIds = new Set([...alreadyRemoved, ...newlyRemoved]);
+		postDecisionTrackChangeIds = /* @__PURE__ */ new Set([...alreadyRemoved, ...newlyRemoved]);
 		applyPostDecisionTrackChangesToCache(postDecisionTrackChangeIds);
 		publishPostDecisionTrackChanges(newlyRemoved, receipt);
 	};
 	const postDecisionTrackChangeIdsForToken = (token) => postDecisionTrackChangesToken === token && postDecisionTrackChangeIds.size > 0 ? postDecisionTrackChangeIds : null;
+	/**
+	* Merge a narrow tracked-change read into the two settled review caches.
+	* Existing enriched adapter fields are retained while the fresh Document
+	* API fields win. The entry keeps its original content token, so a row that
+	* settles after the typing invalidation is truthfully served as stale rather
+	* than discarded or mislabeled as a complete current-token catalog.
+	*/
 	const mergeTrackedChangeItemsIntoCache = (items, orderedItems = []) => {
 		const projected = items.map(projectTrackChangesItem).filter((item) => item != null && readEntityId(item) != null);
 		if (projected.length === 0) return;
@@ -3627,22 +4242,22 @@ function createSuperDocUI(options) {
 			inflightToken: null
 		});
 	};
-	const hydrateTrackedChanges = async (context, options$1) => {
+	const hydrateTrackedChanges = async (context, options) => {
 		try {
 			const listTrackedChanges = context.v2TrackedChanges?.listTrackedChanges;
 			if (typeof listTrackedChanges === "function") {
-				const result$1 = await Promise.resolve(listTrackedChanges.call(context.v2TrackedChanges, {
-					mode: options$1.trackedChangesListMode,
-					refreshReason: options$1.refreshReason,
-					blocking: options$1.blocking,
-					...options$1.targetIds?.length ? { targetIds: options$1.targetIds } : {}
+				const result = await Promise.resolve(listTrackedChanges.call(context.v2TrackedChanges, {
+					mode: options.trackedChangesListMode,
+					refreshReason: options.refreshReason,
+					blocking: options.blocking,
+					...options.targetIds?.length ? { targetIds: options.targetIds } : {}
 				}));
-				const ok = options$1.trackedChangesListMode === "all" && options$1.refreshReason === "mutation-history-render-reconcile" ? result$1?.ok === true : result$1?.ok !== false;
+				const ok = options.trackedChangesListMode === "all" && options.refreshReason === "mutation-history-render-reconcile" ? result?.ok === true : result?.ok !== false;
 				return {
 					ok,
-					items: ok && Array.isArray(result$1?.items) ? result$1.items : [],
-					...typeof result$1?.complete === "boolean" ? { complete: result$1.complete } : {},
-					...typeof result$1?.sourceCoverageComplete === "boolean" ? { sourceCoverageComplete: result$1.sourceCoverageComplete } : {}
+					items: ok && Array.isArray(result?.items) ? result.items : [],
+					...typeof result?.complete === "boolean" ? { complete: result.complete } : {},
+					...typeof result?.sourceCoverageComplete === "boolean" ? { sourceCoverageComplete: result.sourceCoverageComplete } : {}
 				};
 			}
 			const list = context.docTrackChanges?.list;
@@ -3663,6 +4278,13 @@ function createSuperDocUI(options) {
 			};
 		}
 	};
+	/**
+	* Read receipt-addressed review effects after their exact canonical paint.
+	* The adapter's narrow get preserves its enriched row projection; the public
+	* Document API is the fallback for hosts without that bridge method. Empty
+	* successful reads remain unresolved and immediately use one bounded
+	* interaction-prime list instead of waiting for the typing-idle catalog.
+	*/
 	const reviewMutationReconciler = createV2ReviewMutationReconciler({
 		getContext: () => {
 			const editor = getEditor();
@@ -3706,12 +4328,12 @@ function createSuperDocUI(options) {
 			const reads = await Promise.all(requestedIds.map(async (id) => {
 				try {
 					if (typeof getTrackedChange === "function") {
-						const result$1 = await Promise.resolve(getTrackedChange.call(context.v2TrackedChanges, id));
+						const result = await Promise.resolve(getTrackedChange.call(context.v2TrackedChanges, id));
 						return {
 							id,
-							ok: result$1?.ok !== false,
-							items: result$1?.ok !== false && Array.isArray(result$1?.items) ? result$1.items : [],
-							result: result$1
+							ok: result?.ok !== false,
+							items: result?.ok !== false && Array.isArray(result?.items) ? result.items : [],
+							result
 						};
 					}
 					const result = await Promise.resolve(getRawTrackedChange.call(context.docTrackChanges, { id }));
@@ -3778,11 +4400,12 @@ function createSuperDocUI(options) {
 				recompute();
 				return;
 			}
-			mergeTrackedChangeItemsIntoCache((result?.items ?? []).filter((item) => {
+			const items = (result?.items ?? []).filter((item) => {
 				const projected = projectTrackChangesItem(item);
 				const id = projected == null ? null : readEntityId(projected);
 				return id != null && ids.has(id);
-			}), result?.orderedItems ?? result?.items ?? []);
+			});
+			mergeTrackedChangeItemsIntoCache(items, result?.orderedItems ?? result?.items ?? []);
 			recompute();
 		}
 	});
@@ -3796,10 +4419,12 @@ function createSuperDocUI(options) {
 			reviewMutationReconciler.onRender(true);
 		}, delayMs);
 	};
+	/** Token for the live selection read, including the mode that controls its public projection. */
 	const selectionReadToken = () => `${contentToken()}|m${readDocumentMode()}|s${selectionEpoch}`;
-	const selectionSignature = (selection$1) => JSON.stringify({
-		t: selection$1.target ?? null,
-		s: selection$1.selectionTarget ?? null
+	/** Stable signature of a settled selection, used to key selection-scoped reads. */
+	const selectionSignature = (selection) => JSON.stringify({
+		t: selection.target ?? null,
+		s: selection.selectionTarget ?? null
 	});
 	const SELECTION_SCOPED_ASYNC_READ_PREFIXES = [
 		"contentControls:inRange:",
@@ -3808,6 +4433,7 @@ function createSuperDocUI(options) {
 	];
 	const FOREGROUND_ASYNC_RETRY_MS = 120;
 	const COLD_ASYNC_READ_START_DELAY_MS = 180;
+	/** Tri-state host source-load phase derived from the loading snapshot seam. */
 	const hostSourceLoadPhase = () => {
 		const host = getHost();
 		const read = host?.getDocumentLoadingSnapshot;
@@ -3830,9 +4456,14 @@ function createSuperDocUI(options) {
 		return Array.isArray(entry.value) && entry.value.length > 0;
 	};
 	const heavyReadDemandActive = (key, token) => demandedHeavyReads.get(key) === token;
+	/**
+	* Demand-driven route for the content-controls catalog (panel / API use).
+	* Explicit demand bypasses both active-loading and post-complete idle holds.
+	*/
 	const ensureContentControlsCatalog = (_reason) => {
 		demandHeavyDocRead("contentControls");
 	};
+	/** Demand-driven route for an explicitly consumed tracked-change list. */
 	const ensureTrackChangesCatalog = () => {
 		const entry = asyncReads.get("trackChanges");
 		if (entry?.hasSettled || entry?.inflightToken != null) return;
@@ -3842,9 +4473,21 @@ function createSuperDocUI(options) {
 	const HEAVY_READ_IDLE_CEILING_MS = 8e3;
 	const HEAVY_READ_IDLE_POLL_MS = 250;
 	let lastEditableMutationAtMs = 0;
+	/**
+	* Last burst-class mutation: a local typing command or a remote apply whose
+	* originating operation is unavailable. Drives the steady-phase heavy-read
+	* hold while one-off local programmatic mutations keep refreshing promptly.
+	*/
 	let lastTypingMutationAtMs = 0;
+	/**
+	* True from the first deferred heavy read until the input-idle release runs.
+	* Held reads stay deferred even after source-complete so a typing-driven
+	* recompute cannot bypass the idle gate.
+	*/
 	let heavyReadsHeldUntilIdle = false;
+	/** When the STEADY-phase typing hold began; bounds it to the same ceiling. */
 	let heavyReadsTypingHoldSinceMs = 0;
+	/** Lets one ceiling-triggered recompute refresh every heavy key as a group. */
 	let heavyReadCeilingReleaseActive = false;
 	let heavyReadCompletionRecomputeTimer = null;
 	const scheduleHeavyReadCompletionRecompute = () => {
@@ -3904,15 +4547,15 @@ function createSuperDocUI(options) {
 		const host = getEditor()?.host;
 		const read = host?.getForegroundMutationState;
 		if (typeof read !== "function") return null;
-		const state$1 = safeCall(() => read.call(host), null);
+		const state = safeCall(() => read.call(host), null);
 		return {
-			active: typeof state$1?.active === "number" ? state$1.active : 0,
-			pending: typeof state$1?.pending === "number" ? state$1.pending : 0
+			active: typeof state?.active === "number" ? state.active : 0,
+			pending: typeof state?.pending === "number" ? state.pending : 0
 		};
 	};
 	const foregroundMutationActive = () => {
-		const state$1 = foregroundMutationState();
-		return Boolean(state$1 && (state$1.active > 0 || state$1.pending > 0));
+		const state = foregroundMutationState();
+		return Boolean(state && (state.active > 0 || state.pending > 0));
 	};
 	const scheduleForegroundAsyncRetry = (delayMs = FOREGROUND_ASYNC_RETRY_MS) => {
 		if (disposed || foregroundAsyncRetryTimer) return;
@@ -3938,6 +4581,12 @@ function createSuperDocUI(options) {
 		scheduleForegroundAsyncRetry(COLD_ASYNC_READ_START_DELAY_MS);
 		return true;
 	};
+	/**
+	* A large-selection uniformity read walks every covered paragraph. The first
+	* settled selection reads immediately; later distinct selection keys debounce
+	* so pointer-drag/autoscroll updates supersede one another before worker work
+	* starts. Refreshes of the same selection stay immediate.
+	*/
 	const shouldDeferEffectiveInlineRead = (key) => {
 		if (lastEffectiveInlineReadKey == null || key === lastEffectiveInlineReadKey) {
 			if (pendingEffectiveInlineRead?.timer) clearTimeout(pendingEffectiveInlineRead.timer);
@@ -4084,6 +4733,12 @@ function createSuperDocUI(options) {
 		});
 		return null;
 	};
+	/**
+	* Read a doc value through the settled cache. Returns the best-known value
+	* plus a {@link SliceStatus}: `ready` (settled for this token), `stale`
+	* (older settled value while a refresh runs), or `pending` (nothing settled
+	* yet). Never returns or surfaces a promise.
+	*/
 	const readAsync = (key, token, run, normalize) => {
 		const entry = asyncReads.get(key);
 		if (entry && entry.token === token && entry.hasSettled) return {
@@ -4182,23 +4837,24 @@ function createSuperDocUI(options) {
 	const clearAsyncReadKeys = (predicate) => {
 		for (const key of asyncReads.keys()) if (predicate(key)) asyncReads.delete(key);
 	};
-	const selectionScopedAsyncReadKeys = (selection$1) => {
-		const signature = selectionSignature(selection$1);
-		const effectiveUniformitySignature = selectionEffectiveUniformitySignature(selection$1);
-		return new Set([
+	const selectionScopedAsyncReadKeys = (selection) => {
+		const signature = selectionSignature(selection);
+		const effectiveUniformitySignature = selectionEffectiveUniformitySignature(selection);
+		return /* @__PURE__ */ new Set([
 			`contentControls:inRange:${signature}`,
 			`query:${signature}`,
 			...effectiveUniformitySignature ? [`effInline:${effectiveUniformitySignature}`] : []
 		]);
 	};
-	const pruneSelectionScopedAsyncReads = (selection$1) => {
-		const retained = selectionScopedAsyncReadKeys(selection$1);
+	const pruneSelectionScopedAsyncReads = (selection) => {
+		const retained = selectionScopedAsyncReadKeys(selection);
 		clearAsyncReadKeys((key) => SELECTION_SCOPED_ASYNC_READ_PREFIXES.some((prefix) => key.startsWith(prefix)) && !retained.has(key));
 		for (const key of coldAsyncReadDeferrals) {
 			const readKey = key.split("\0", 1)[0];
 			if (SELECTION_SCOPED_ASYNC_READ_PREFIXES.some((prefix) => readKey.startsWith(prefix)) && !retained.has(readKey)) coldAsyncReadDeferrals.delete(key);
 		}
 	};
+	/** Drop cached reads when the active editor identity changes (avoids cross-editor leakage). */
 	const syncCoordinatorEditor = () => {
 		const editor = getEditor();
 		if (editor === lastCoordinatorEditor) return;
@@ -4228,12 +4884,20 @@ function createSuperDocUI(options) {
 		clearPostDecisionTrackChanges();
 		allTrackedChangesResolvedToken = null;
 	};
+	/** Bump the document-mutation revision so content reads re-fetch on the next compute. */
 	const invalidateDocumentContent = () => {
 		const carryAuthoritativeTrackChangesHold = authoritativeTrackChangesPendingToken !== null;
 		documentMutationRevision += 1;
 		if (carryAuthoritativeTrackChangesHold) authoritativeTrackChangesPendingToken = contentToken();
 		clearPostDecisionTrackChanges();
 	};
+	/**
+	* Refresh command-derived document slices without discarding an exact
+	* all-resolved catalog received while the async command was settling. Host
+	* mutation events arrive before the command promise resolves; a generic
+	* invalidation at that later boundary would otherwise advance the cache
+	* token and immediately re-list the catalog we already know is empty.
+	*/
 	const invalidateAfterCommandSettlement = () => {
 		const carryAllResolvedCatalog = allTrackedChangesResolvedToken === contentToken();
 		invalidateDocumentContent();
@@ -4243,6 +4907,12 @@ function createSuperDocUI(options) {
 		}
 		recompute();
 	};
+	/**
+	* Insert plain text through the public Document API. The narrow built-in /
+	* custom insertion helper exposed on the custom-command callback context.
+	* Fails closed (failure receipt) in viewing mode or when `doc.insert` is
+	* unavailable — never reaching into `activeEditor.commands`.
+	*/
 	const insertText = (text) => {
 		if (typeof text !== "string" || text.length === 0) return failedReceipt("insertText requires a non-empty string.", "INVALID_INPUT");
 		if (readDocumentMode() === "viewing") return failedReceipt("The document is read-only.", "DOCUMENT_READONLY");
@@ -4251,8 +4921,8 @@ function createSuperDocUI(options) {
 		if (!doc || typeof op !== "function") return failedReceipt("insert is unavailable.");
 		const currentSelection = doc.selection?.current;
 		if (typeof currentSelection !== "function") return failedReceipt("selection.current is unavailable.");
-		const insertAtLiveSelection = (selection$2) => {
-			const record = selection$2 && typeof selection$2 === "object" ? selection$2 : null;
+		const insertAtLiveSelection = (selection) => {
+			const record = selection && typeof selection === "object" ? selection : null;
 			const target = record?.selectionTarget ?? record?.target ?? null;
 			if (!target || typeof target !== "object") return failedReceipt("insertText requires a live selection target.", "PRECONDITION_FAILED");
 			return safeCall(() => settleWorkflowReceipt(op.call(doc, {
@@ -4261,15 +4931,16 @@ function createSuperDocUI(options) {
 				target
 			}), failedReceipt("insert failed.")), failedReceipt("insert failed."));
 		};
-		let selection$1;
+		let selection;
 		try {
-			selection$1 = currentSelection.call(doc.selection);
+			selection = currentSelection.call(doc.selection);
 		} catch {
 			return failedReceipt("insertText could not resolve the live selection.", "PRECONDITION_FAILED");
 		}
-		if (isPromiseLike(selection$1)) return Promise.resolve(selection$1).then(insertAtLiveSelection, () => failedReceipt("insertText could not resolve the live selection.", "PRECONDITION_FAILED"));
-		return insertAtLiveSelection(selection$1);
+		if (isPromiseLike(selection)) return Promise.resolve(selection).then(insertAtLiveSelection, () => failedReceipt("insertText could not resolve the live selection.", "PRECONDITION_FAILED"));
+		return insertAtLiveSelection(selection);
 	};
+	/** Build the shared V2-truthful callback context for a custom command / button. */
 	const buildCustomCommandContext = (payload, context) => ({
 		payload,
 		state,
@@ -4291,10 +4962,11 @@ function createSuperDocUI(options) {
 		const editor = getEditor();
 		const superdocRecord = superdoc && typeof superdoc === "object" ? superdoc : null;
 		const fromConfig = normalizeDocumentMode((superdocRecord?.config)?.documentMode);
-		const fromRuntime = normalizeDocumentMode(safeCall(typeof superdocRecord?.getActiveRuntime === "function" ? () => {
+		const runtimeSnapshot = safeCall(typeof superdocRecord?.getActiveRuntime === "function" ? () => {
 			const runtime = superdocRecord.getActiveRuntime();
 			return typeof runtime?.getSnapshot === "function" ? runtime.getSnapshot() : null;
-		} : void 0, null)?.documentMode);
+		} : void 0, null);
+		const fromRuntime = normalizeDocumentMode(runtimeSnapshot?.documentMode);
 		const fromOptions = normalizeDocumentMode((editor?.options)?.documentMode);
 		if (fromConfig && fromRuntime && fromConfig !== fromRuntime) return fromConfig;
 		return fromRuntime ?? fromConfig ?? fromOptions;
@@ -4303,15 +4975,20 @@ function createSuperDocUI(options) {
 		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 comments = ((superdocRecord?.config)?.modules)?.comments;
+		return !!comments && typeof comments === "object" && comments.readOnly === true;
+	};
+	/**
+	* Whether `interaction.comments.allowResolve` forbids changing a thread's
+	* resolved state. Same precedence as `readOnly`: the resolved policy first,
+	* the legacy block only when it is absent.
+	*/
 	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 comments = ((superdocRecord?.config)?.modules)?.comments;
+		return !!comments && typeof comments === "object" && comments.allowResolve === false;
 	};
 	const reviewMutationsAreReadOnly = () => readDocumentMode() === "viewing" || commentsReadOnlyForReview();
 	const normalizeSelectionInfo = (raw) => raw && typeof raw === "object" ? raw : null;
@@ -4345,6 +5022,7 @@ function createSuperDocUI(options) {
 		const selectionApi = getDoc()?.selection;
 		return selectionApi?.current ? selectionApi.current({ includeText: true }) : void 0;
 	};
+	/** True when a host sync snapshot is a resolved collapsed caret (not a range). */
 	const isCollapsedCaretSnapshot = (info) => {
 		if (info.empty !== true) return false;
 		const target = info.selectionTarget;
@@ -4352,6 +5030,21 @@ function createSuperDocUI(options) {
 		const end = target?.end;
 		return start?.kind === "text" && end?.kind === "text" && typeof start.blockId === "string" && start.blockId === end.blockId && typeof start.offset === "number" && start.offset === end.offset;
 	};
+	/**
+	* On a caret move, seed the `selection` read cache synchronously from the
+	* host's local snapshot so the toolbar reflects the NEW caret's block (and the
+	* effective font resolved from it) on the next recompute, instead of serving
+	* the previous selection until the worker `selection.current` round-trip lands
+	* (SD-3652). Only a resolvable COLLAPSED CARET is seeded - a range's snapshot
+	* cannot be resolved synchronously in worker mode, so ranges defer to the async
+	* read (seeding an empty value would wrongly disable range-only commands). The
+	* authoritative async read still overwrites marks/text/review overlap, but
+	* foreground typing defers and coalesces that worker hop through the shared
+	* retry gate. Previous marks are carried forward for toolbar continuity. A
+	* tracked-change id is carried only when the host's painted caret proves the
+	* same carrier, or while an active typing dispatch advances the same caret by
+	* one code point. Pending work alone never carries review command context.
+	*/
 	const seedCaretSelectionFromHost = (hostSelectionSnapshot) => {
 		const host = getHost();
 		const read = host?.readLiveSelectionSyncSnapshot;
@@ -4423,15 +5116,15 @@ function createSuperDocUI(options) {
 		recompute();
 		return state.selection;
 	};
-	const computeComments = (selection$1) => {
+	const computeComments = (selection) => {
 		const commentsApi = getDoc()?.comments;
 		const { value, status: listStatus } = readAsync("comments", contentToken(), () => commentsApi?.list ? commentsApi.list() : void 0, (raw) => raw && Array.isArray(raw.items) ? raw.items : []);
 		const items = value ?? [];
-		const activeIds = selection$1.activeCommentIds;
+		const activeIds = selection.activeCommentIds;
 		if (explicitActiveCommentId && !items.some((item) => readEntityId(item) === explicitActiveCommentId)) explicitActiveCommentId = null;
 		const activeId = explicitActiveCommentId ?? activeIds[0] ?? null;
 		return {
-			status: combineStatus(listStatus, selection$1.status),
+			status: combineStatus(listStatus, selection.status),
 			listStatus,
 			items,
 			total: items.length,
@@ -4461,7 +5154,7 @@ function createSuperDocUI(options) {
 		});
 		return status === "ready" ? value : null;
 	};
-	const computeTrackChanges = (selection$1) => {
+	const computeTrackChanges = (selection) => {
 		const tcApi = getDoc()?.trackChanges;
 		const v2TrackedChanges = getV2TrackedChanges();
 		const listTrackedChanges = typeof v2TrackedChanges?.listTrackedChanges === "function" ? v2TrackedChanges.listTrackedChanges : null;
@@ -4494,51 +5187,58 @@ function createSuperDocUI(options) {
 			} else if (!items.some((item) => readEntityId(item) === active.id)) setExplicitActiveChange(null);
 		}
 		const publicIdItems = allStoryItems ?? items;
-		const selectionIdContext = buildStoryScopedTrackedChangeIdContext(publicIdItems, selectionStory(selection$1));
-		const selectionActiveChangeIds = allTrackedChangesResolvedToken === token ? [] : postDecisionIds ? selection$1.activeChangeIds.filter((id) => !postDecisionIds.has(id)) : selection$1.activeChangeIds;
+		const selectionIdContext = buildStoryScopedTrackedChangeIdContext(publicIdItems, selectionStory(selection));
+		const selectionActiveChangeIds = allTrackedChangesResolvedToken === token ? [] : postDecisionIds ? selection.activeChangeIds.filter((id) => !postDecisionIds.has(id)) : selection.activeChangeIds;
 		const selectionPublicChangeIds = selectionActiveChangeIds.map((id) => selectionIdContext.toPublicId(id) ?? id);
 		const explicitActiveIdContext = explicitActiveChange?.story ? buildStoryScopedTrackedChangeIdContext(publicIdItems, explicitActiveChange.story) : buildTrackedChangeIdContext(publicIdItems);
 		const explicitActiveId = explicitActiveChange ? explicitActiveIdContext.toPublicId(explicitActiveChange.id) ?? explicitActiveChange.id : null;
 		const selectionActiveId = resolveSelectionActiveChangeId({
 			selectionIds: selectionActiveChangeIds,
 			publicIds: selectionPublicChangeIds,
-			selection: selection$1,
+			selection,
 			bodyItems: items,
 			allStoryItems
 		});
 		const activeId = explicitActiveId ?? selectionActiveId;
 		return {
-			status: combineStatus(listStatus, selection$1.status),
+			status: combineStatus(listStatus, selection.status),
 			items,
 			total: items.length,
 			activeId,
 			authors: [...authors]
 		};
 	};
-	const computeContentControls = (selection$1) => {
+	const computeContentControls = (selection) => {
 		const ccApi = getDoc()?.contentControls;
 		const { value, status: listStatus } = readAsync("contentControls", contentToken(), () => ccApi?.list ? ccApi.list() : void 0, (raw) => raw && Array.isArray(raw.items) ? raw.items : []);
 		const items = value ?? [];
-		const { ids: activeIds, status: rangeStatus } = computeActiveContentControlIds(ccApi, selection$1);
+		const { ids: activeIds, status: rangeStatus } = computeActiveContentControlIds(ccApi, selection);
 		return {
-			status: combineStatus(listStatus, rangeStatus, selection$1.status),
+			status: combineStatus(listStatus, rangeStatus, selection.status),
 			items,
 			total: items.length,
 			activeId: activeIds[0] ?? null,
 			activeIds
 		};
 	};
-	const computeActiveContentControlLockModes = (ccApi, selection$1) => {
+	/**
+	* Lock mode of every content control overlapping the current selection's
+	* block range, keyed by control id. Powers `contentControlLockReason` so the
+	* toolbar can disable styling controls when the selection touches a
+	* `contentLocked`/`sdtContentLocked` control (SD-3274) — block-range scoped,
+	* same precision as `computeActiveContentControlIds` below.
+	*/
+	const computeActiveContentControlLockModes = (ccApi, selection) => {
 		if (!ccApi || typeof ccApi.listInRange !== "function") return {
 			lockModesById: /* @__PURE__ */ new Map(),
 			status: "ready"
 		};
-		const range = selectionBlockRange(selection$1);
+		const range = selectionBlockRange(selection);
 		if (!range) return {
 			lockModesById: /* @__PURE__ */ new Map(),
 			status: "ready"
 		};
-		const { value, status } = readAsync(`contentControls:inRange:${selectionSignature(selection$1)}`, contentToken(), () => ccApi.listInRange(range), (raw) => raw && Array.isArray(raw.items) ? raw.items : []);
+		const { value, status } = readAsync(`contentControls:inRange:${selectionSignature(selection)}`, contentToken(), () => ccApi.listInRange(range), (raw) => raw && Array.isArray(raw.items) ? raw.items : []);
 		const rows = value ?? [];
 		const lockModesById = /* @__PURE__ */ new Map();
 		for (const row of rows) if (typeof row?.id === "string") lockModesById.set(row.id, typeof row.lockMode === "string" ? row.lockMode : "unlocked");
@@ -4547,8 +5247,8 @@ function createSuperDocUI(options) {
 			status
 		};
 	};
-	const computeActiveContentControlIds = (ccApi, selection$1) => {
-		const { lockModesById, status } = computeActiveContentControlLockModes(ccApi, selection$1);
+	const computeActiveContentControlIds = (ccApi, selection) => {
+		const { lockModesById, status } = computeActiveContentControlLockModes(ccApi, selection);
 		return {
 			ids: [...lockModesById.keys()],
 			status
@@ -4562,14 +5262,14 @@ function createSuperDocUI(options) {
 		};
 	};
 	const computeZoom = () => {
-		const state$1 = safeCall(superdoc?.getZoomState ? () => superdoc.getZoomState() : void 0, null);
-		const value = typeof state$1?.value === "number" ? state$1.value : 100;
-		const rawMode = state$1?.mode;
+		const state = safeCall(superdoc?.getZoomState ? () => superdoc.getZoomState() : void 0, null);
+		const value = typeof state?.value === "number" ? state.value : 100;
+		const rawMode = state?.mode;
 		return {
 			mode: rawMode === "manual" || rawMode === "fit-width" ? rawMode : rawMode === "fixed" ? "manual" : null,
 			value,
-			min: typeof state$1?.min === "number" ? state$1.min : 10,
-			max: typeof state$1?.max === "number" ? state$1.max : 100
+			min: typeof state?.min === "number" ? state.min : 10,
+			max: typeof state?.max === "number" ? state.max : 100
 		};
 	};
 	const readMeasurementUnit = () => {
@@ -4583,12 +5283,18 @@ function createSuperDocUI(options) {
 			dirty: editor ? Boolean(editor.isDirty) : false
 		};
 	};
-	const selectionTextQueryRequest = (selection$1) => {
-		const pattern = selection$1.quotedText;
+	/**
+	* Resolve the `query.match` row covering the current selection through the
+	* async read coordinator. The promise-capable browser `query.match` is read
+	* via the cache (keyed by selection signature + content revision), so inline
+	* value projection no longer collapses to empty when the read is async.
+	*/
+	const selectionTextQueryRequest = (selection) => {
+		const pattern = selection.quotedText;
 		if (typeof pattern !== "string" || pattern.length === 0) return null;
-		const segments = selectionTextSegments(selection$1);
+		const segments = selectionTextSegments(selection);
 		if (segments.length === 0 || !canProbeEverySelectedBlock(segments.map((segment) => segment.blockId))) return null;
-		const target = selection$1.target;
+		const target = selection.target;
 		const within = segments.length === 1 ? paragraphTarget(segments[0].blockId, target?.story) : void 0;
 		return {
 			select: {
@@ -4601,24 +5307,30 @@ function createSuperDocUI(options) {
 			require: "any"
 		};
 	};
-	const resolveSelectionTextQueryItem = (selection$1) => {
+	const resolveSelectionTextQueryItem = (selection) => {
 		const query = getDoc()?.query;
 		if (typeof query?.match !== "function") return null;
-		const request = selectionTextQueryRequest(selection$1);
+		const request = selectionTextQueryRequest(selection);
 		if (!request) return null;
-		const { value } = readAsync(`query:${selectionSignature(selection$1)}`, contentToken(), () => query.match(request), (raw) => raw && typeof raw === "object" ? raw : null);
-		return pickSelectionTextQueryItem(value, selection$1);
-	};
-	const resolveEffectiveInlineValuesFromLayout = (selection$1) => {
+		const { value } = readAsync(`query:${selectionSignature(selection)}`, contentToken(), () => query.match(request), (raw) => raw && typeof raw === "object" ? raw : null);
+		return pickSelectionTextQueryItem(value, selection);
+	};
+	/**
+	* Effective (cascade-resolved) font family / size for the selection, read from
+	* the mounted layout and matched by source node id (SD-3652). The Document API
+	* query surfaces only DIRECT run properties, so inherited fonts have no
+	* projected value; the layout has already resolved them for painting.
+	*/
+	const resolveEffectiveInlineValuesFromLayout = (selection) => {
 		const host = getHost();
-		const blockIds = new Set(selectionBlockIds(selection$1));
+		const blockIds = new Set(selectionBlockIds(selection));
 		if (blockIds.size === 0) return {};
 		const readByIds = host?.readMountedProjectionBlocksByIds;
 		const readAll = host?.readMountedProjectionBlocks;
 		if (typeof readByIds !== "function" && typeof readAll !== "function") return {};
 		const blocks = safeCall(() => {
 			if (typeof readByIds !== "function") return readAll.call(host);
-			const story = selectionStoryLocator(selection$1);
+			const story = selectionStoryLocator(selection);
 			return story ? readByIds.call(host, [...blockIds], story) : readByIds.call(host, [...blockIds]);
 		}, null);
 		if (!Array.isArray(blocks)) return {};
@@ -4633,7 +5345,7 @@ function createSuperDocUI(options) {
 			if (typeof run.highlight === "string" && run.highlight.trim() !== "") out.highlight = run.highlight.trim().toUpperCase();
 			return out;
 		};
-		const caret = collapsedTextAddressFromSelection(selection$1);
+		const caret = collapsedTextAddressFromSelection(selection);
 		const caretOffset = caret && typeof caret.range?.start === "number" ? caret.range.start : null;
 		if (caret && caretOffset !== null && blockIds.has(caret.blockId)) {
 			const block = flatBlocks.find((b) => projectionBlockMatchesId(b, caret.blockId));
@@ -4657,7 +5369,7 @@ function createSuperDocUI(options) {
 				return runFontValues(chosen);
 			}
 		}
-		const segments = selectionTextSegments(selection$1);
+		const segments = selectionTextSegments(selection);
 		if (segments.length > 0) {
 			const rangeFamilies = /* @__PURE__ */ new Set();
 			const rangeSizes = /* @__PURE__ */ new Set();
@@ -4687,10 +5399,10 @@ function createSuperDocUI(options) {
 				}
 			}
 			if (offsetSafe && rangeSawRun) {
-				const projection$1 = {};
-				if (rangeFamilies.size === 1) projection$1.fontFamily = [...rangeFamilies][0];
-				if (rangeSizes.size === 1) projection$1.fontSize = [...rangeSizes][0];
-				return projection$1;
+				const projection = {};
+				if (rangeFamilies.size === 1) projection.fontFamily = [...rangeFamilies][0];
+				if (rangeSizes.size === 1) projection.fontSize = [...rangeSizes][0];
+				return projection;
 			}
 		}
 		const families = /* @__PURE__ */ new Set();
@@ -4713,16 +5425,29 @@ function createSuperDocUI(options) {
 		if (sizes.size === 1) projection.fontSize = [...sizes][0];
 		return projection;
 	};
-	const resolveEffectiveMarkValuesFromLayout = (selection$1) => {
+	/**
+	* Effective (cascade-resolved) toggle-mark state read from the mounted
+	* projection (SD-3860). `run.bold`/`run.italic`/`run.strike`/`run.underline`
+	* on a projected run are already the FINAL merged value (style cascade +
+	* any direct rPr override) — the same values `DomPainter` paints with — so
+	* unlike the raw-rPr-only `selection.activeMarks` scan, this correctly
+	* reports `false` for an explicit `<w:b w:val="0"/>` override even when a
+	* paragraph/table style says bold. A key is left `undefined` when the
+	* covered runs disagree (genuine mixed selection) or nothing could be read,
+	* so the caller falls through to the worker-side uniformity read rather
+	* than guessing. Mounted-projection `underline` is an object (`{}` /
+	* `{ style: 'single' }`) when active, never a bare `true` — check presence.
+	*/
+	const resolveEffectiveMarkValuesFromLayout = (selection) => {
 		const host = getHost();
-		const blockIds = new Set(selectionBlockIds(selection$1));
+		const blockIds = new Set(selectionBlockIds(selection));
 		if (blockIds.size === 0) return {};
 		const readByIds = host?.readMountedProjectionBlocksByIds;
 		const readAll = host?.readMountedProjectionBlocks;
 		if (typeof readByIds !== "function" && typeof readAll !== "function") return {};
 		const blocks = safeCall(() => {
 			if (typeof readByIds !== "function") return readAll.call(host);
-			const story = selectionStoryLocator(selection$1);
+			const story = selectionStoryLocator(selection);
 			return story ? readByIds.call(host, [...blockIds], story) : readByIds.call(host, [...blockIds]);
 		}, null);
 		if (!Array.isArray(blocks)) return {};
@@ -4741,7 +5466,7 @@ function createSuperDocUI(options) {
 			}
 			return out;
 		};
-		const caret = collapsedTextAddressFromSelection(selection$1);
+		const caret = collapsedTextAddressFromSelection(selection);
 		const caretOffset = caret && typeof caret.range?.start === "number" ? caret.range.start : null;
 		if (caret && caretOffset !== null && blockIds.has(caret.blockId)) {
 			const block = flatBlocks.find((b) => projectionBlockMatchesId(b, caret.blockId));
@@ -4765,7 +5490,7 @@ function createSuperDocUI(options) {
 				return runMarkValues(chosen);
 			}
 		}
-		const segments = selectionTextSegments(selection$1);
+		const segments = selectionTextSegments(selection);
 		if (segments.length > 0) {
 			const rangeSets = {
 				bold: /* @__PURE__ */ new Set(),
@@ -4819,12 +5544,12 @@ function createSuperDocUI(options) {
 		if (!sawWholeRun) return {};
 		return collapseMarkSets(wholeSets);
 	};
-	const completeProjectedInlineValues = (selection$1, direct) => {
+	const completeProjectedInlineValues = (selection, direct) => {
 		if (direct.fontFamily !== void 0 && direct.fontSize !== void 0 && direct.color !== void 0 && direct.highlight !== void 0) return {
 			values: direct,
 			effectiveUniformityStatus: "ready"
 		};
-		const resolved = resolveEffectiveInlineValuesFromLayout(selection$1);
+		const resolved = resolveEffectiveInlineValuesFromLayout(selection);
 		const combined = {
 			...resolved.fontFamily !== void 0 ? { fontFamily: resolved.fontFamily } : {},
 			...resolved.fontSize !== void 0 ? { fontSize: resolved.fontSize } : {},
@@ -4832,8 +5557,8 @@ function createSuperDocUI(options) {
 			...resolved.highlight !== void 0 ? { highlight: resolved.highlight } : {},
 			...direct
 		};
-		if (!selection$1.empty && (combined.fontFamily === void 0 || combined.fontSize === void 0)) {
-			const uniformity = resolveEffectiveInlineUniformityValues(selection$1);
+		if (!selection.empty && (combined.fontFamily === void 0 || combined.fontSize === void 0)) {
+			const uniformity = resolveEffectiveInlineUniformityValues(selection);
 			if (uniformity.values) {
 				if (combined.fontFamily === void 0 && uniformity.values.fontFamily !== void 0) combined.fontFamily = uniformity.values.fontFamily;
 				if (combined.fontSize === void 0 && uniformity.values.fontSize !== void 0) combined.fontSize = uniformity.values.fontSize;
@@ -4848,6 +5573,13 @@ function createSuperDocUI(options) {
 			effectiveUniformityStatus: "ready"
 		};
 	};
+	/**
+	* Cached async access to the INTERNAL `format.readEffectiveInlineUniformity`
+	* read (duck-typed; absent on hosts that do not provide it). Returns only
+	* settled UNIFORM values - mixed and unresolvable keys stay undefined so the
+	* toolbar renders its mixed/blank state, and a pending read serves nothing
+	* (the held-value logic covers the transition).
+	*/
 	const EFFECTIVE_INLINE_UNIFORMITY_KEYS = [
 		"fontFamily",
 		"fontSize",
@@ -4856,8 +5588,8 @@ function createSuperDocUI(options) {
 		"underline",
 		"strikethrough"
 	];
-	const readEffectiveInlineUniformityCached = (selection$1) => {
-		const target = selection$1.selectionTarget;
+	const readEffectiveInlineUniformityCached = (selection) => {
+		const target = selection.selectionTarget;
 		if (!target) return {
 			value: null,
 			status: "ready"
@@ -4867,14 +5599,15 @@ function createSuperDocUI(options) {
 			value: null,
 			status: "ready"
 		};
-		return readAsync(`effInline:${selectionEffectiveUniformitySignature(selection$1) ?? selectionSignature(selection$1)}`, contentToken(), () => op({
+		const signature = selectionEffectiveUniformitySignature(selection) ?? selectionSignature(selection);
+		return readAsync(`effInline:${signature}`, contentToken(), () => op({
 			target,
 			offsetSpace: "selection",
 			keys: EFFECTIVE_INLINE_UNIFORMITY_KEYS
 		}), (raw) => raw && typeof raw === "object" ? raw : null);
 	};
-	const resolveEffectiveInlineUniformityValues = (selection$1) => {
-		const { value, status } = readEffectiveInlineUniformityCached(selection$1);
+	const resolveEffectiveInlineUniformityValues = (selection) => {
+		const { value, status } = readEffectiveInlineUniformityCached(selection);
 		if (!value || value.success !== true) return {
 			values: null,
 			status
@@ -4893,8 +5626,9 @@ function createSuperDocUI(options) {
 			status
 		};
 	};
-	const resolveEffectiveMarkUniformityValues = (selection$1) => {
-		const { value, status } = readEffectiveInlineUniformityCached(selection$1);
+	/** Worker-side cascade-resolved mark uniformity, for selections whose tail isn't mounted (SD-3860). */
+	const resolveEffectiveMarkUniformityValues = (selection) => {
+		const { value, status } = readEffectiveInlineUniformityCached(selection);
 		if (!value || value.success !== true) return {
 			values: null,
 			status
@@ -4910,18 +5644,25 @@ function createSuperDocUI(options) {
 			status
 		};
 	};
-	const effectiveMarkActiveState = (descriptor, selection$1) => {
+	/**
+	* Effective active state for a toggle-mark command (bold/italic/underline/
+	* strikethrough), SD-3860: the mounted-layout read is tried first (fast,
+	* synchronous), then the worker uniformity read for unmounted content.
+	* Returns `null` (no opinion) only when neither source has resolved yet,
+	* in which case the caller falls back to the raw direct-only check.
+	*/
+	const effectiveMarkActiveState = (descriptor, selection) => {
 		const mark = descriptor.activeMark;
 		if (!mark || !EFFECTIVE_MARK_KEYS.includes(mark)) return null;
 		const key = mark;
-		const fromLayout = resolveEffectiveMarkValuesFromLayout(selection$1)[key];
+		const fromLayout = resolveEffectiveMarkValuesFromLayout(selection)[key];
 		if (fromLayout !== void 0) return fromLayout;
-		const { values } = resolveEffectiveMarkUniformityValues(selection$1);
+		const { values } = resolveEffectiveMarkUniformityValues(selection);
 		const fromWorker = values?.[key];
 		return fromWorker !== void 0 ? fromWorker : null;
 	};
-	const readEffectiveInlineUniformityNow = async (selection$1) => {
-		const target = selection$1.selectionTarget;
+	const readEffectiveInlineUniformityNow = async (selection) => {
+		const target = selection.selectionTarget;
 		if (!target) return null;
 		const op = resolveDocOperation(getDoc(), "format.readEffectiveInlineUniformity");
 		if (!op) return null;
@@ -4944,23 +5685,30 @@ function createSuperDocUI(options) {
 			else delete projected[key];
 		}
 	};
-	const projectSelectionInlineValuesWithStatus = (selection$1) => completeProjectedInlineValues(selection$1, projectInlineValuesFromQueryItem(resolveSelectionTextQueryItem(selection$1), selection$1));
-	const projectSelectionInlineValues = (selection$1) => projectSelectionInlineValuesWithStatus(selection$1).values;
-	const readFormatPainterInlineValues = async (selection$1) => {
+	const projectSelectionInlineValuesWithStatus = (selection) => completeProjectedInlineValues(selection, projectInlineValuesFromQueryItem(resolveSelectionTextQueryItem(selection), selection));
+	const projectSelectionInlineValues = (selection) => projectSelectionInlineValuesWithStatus(selection).values;
+	/**
+	* Read command-critical inline values for format-painter capture. Reactive
+	* command state intentionally serves stale values while its worker read is
+	* refreshing, but arming the painter must snapshot the mutation that just
+	* settled. A direct, bounded query here makes the async capture authoritative
+	* without changing the non-blocking toolbar snapshot policy.
+	*/
+	const readFormatPainterInlineValues = async (selection) => {
 		const query = getDoc()?.query;
-		const request = selectionTextQueryRequest(selection$1);
-		if (typeof query?.match !== "function" || !request) return projectSelectionInlineValues(selection$1);
+		const request = selectionTextQueryRequest(selection);
+		if (typeof query?.match !== "function" || !request) return projectSelectionInlineValues(selection);
 		try {
 			const raw = await Promise.resolve(query.match(request));
-			const direct = projectInlineValuesFromQueryItem(pickSelectionTextQueryItem(raw && typeof raw === "object" ? raw : null, selection$1), selection$1);
-			const completed = completeProjectedInlineValues(selection$1, direct);
+			const direct = projectInlineValuesFromQueryItem(pickSelectionTextQueryItem(raw && typeof raw === "object" ? raw : null, selection), selection);
+			const completed = completeProjectedInlineValues(selection, direct);
 			if (completed.effectiveUniformityStatus !== "ready" && (direct.fontFamily === void 0 || direct.fontSize === void 0)) {
-				const effective = await readEffectiveInlineUniformityNow(selection$1);
+				const effective = await readEffectiveInlineUniformityNow(selection);
 				if (effective) applyEffectiveInlineUniformity(completed.values, direct, effective);
 			}
 			return completed.values;
 		} catch {
-			return projectSelectionInlineValues(selection$1);
+			return projectSelectionInlineValues(selection);
 		}
 	};
 	const readBlockNode = async (address) => {
@@ -4972,21 +5720,35 @@ function createSuperDocUI(options) {
 			nodeType: address["nodeType"]
 		}));
 	};
-	const selectionQueryStatus = (selection$1) => {
+	/**
+	* Returns the settled status of the query.match read backing the current
+	* selection's inline-value projection. Called after resolveSelectionTextQueryItem
+	* so readAsync always finds an existing cache entry — this is a status-only lookup.
+	*/
+	const selectionQueryStatus = (selection) => {
 		const query = getDoc()?.query;
 		if (typeof query?.match !== "function") return "ready";
-		const request = selectionTextQueryRequest(selection$1);
+		const request = selectionTextQueryRequest(selection);
 		if (!request) return "ready";
-		const { status } = readAsync(`query:${selectionSignature(selection$1)}`, contentToken(), () => query.match(request), (raw) => raw && typeof raw === "object" ? raw : null);
+		const { status } = readAsync(`query:${selectionSignature(selection)}`, contentToken(), () => query.match(request), (raw) => raw && typeof raw === "object" ? raw : null);
 		return status;
 	};
-	const projectInlineValuesWithSettledHold = (selection$1) => {
-		const projection = projectSelectionInlineValuesWithStatus(selection$1);
+	/**
+	* Last fully-settled inline projection, keyed by the selection's inline
+	* signature (content-token-free: the SAME selection across content
+	* revisions keeps its key). While a refresh of the same selection is
+	* pending/stale, settled values fill keys the in-flight projection has not
+	* resolved yet, so the toolbar font field does not flicker blank mid-edit.
+	* A NEW selection never reads a previous selection's held values, and a
+	* SETTLED mixed selection overwrites the hold (blank is then correct).
+	*/
+	const projectInlineValuesWithSettledHold = (selection) => {
+		const projection = projectSelectionInlineValuesWithStatus(selection);
 		const projected = projection.values;
-		if (selection$1.empty) return projection;
-		const signature = selectionInlineValueSignature(selection$1);
+		if (selection.empty) return projection;
+		const signature = selectionInlineValueSignature(selection);
 		if (!signature) return projection;
-		if (selection$1.status === "ready" && selectionQueryStatus(selection$1) === "ready" && projection.effectiveUniformityStatus === "ready") {
+		if (selection.status === "ready" && selectionQueryStatus(selection) === "ready" && projection.effectiveUniformityStatus === "ready") {
 			heldSettledInlineValues = {
 				key: signature,
 				values: projected
@@ -5002,39 +5764,56 @@ function createSuperDocUI(options) {
 		};
 		return projection;
 	};
-	const computeCommandStates = (selection$1) => {
+	const computeCommandStates = (selection) => {
 		const doc = getDoc();
-		const projectedInlineRead = projectInlineValuesWithSettledHold(selection$1);
+		const projectedInlineRead = projectInlineValuesWithSettledHold(selection);
 		const projectedInlineValues = projectedInlineRead.values;
-		if (selection$1.status === "ready" && !selection$1.empty && selectionQueryStatus(selection$1) === "ready" && projectedInlineRead.effectiveUniformityStatus === "ready") {
+		if (selection.status === "ready" && !selection.empty && selectionQueryStatus(selection) === "ready" && projectedInlineRead.effectiveUniformityStatus === "ready") {
 			frozenProjectedValues = projectedInlineValues;
-			frozenProjectedValuesKey = `${selectionKey(selection$1)}:${contentToken()}`;
+			frozenProjectedValuesKey = `${selectionKey(selection)}:${contentToken()}`;
 		}
 		const ccApi = doc?.contentControls;
-		const { lockModesById } = computeActiveContentControlLockModes(ccApi, selection$1);
+		const { lockModesById } = computeActiveContentControlLockModes(ccApi, selection);
 		const states = {};
-		for (const id of allCommandIds()) states[id] = computeCommandState(id, doc, selection$1, projectedInlineValues, lockModesById);
+		for (const id of allCommandIds()) states[id] = computeCommandState(id, doc, selection, projectedInlineValues, lockModesById);
 		return states;
 	};
+	/** Stable reason a routed command cannot reach its Document API operation. */
 	const unavailableRouteReason = (doc) => {
 		if (doc) return SUPERDOC_UI_REASONS.operationUnavailable;
 		return getEditor() ? SUPERDOC_UI_REASONS.documentApiUnavailable : SUPERDOC_UI_REASONS.notReady;
 	};
+	/**
+	* Lock modes that block run-level styling mutations (bold/italic/font/etc.),
+	* mirroring the content-mutation axis the content-controls adapter's
+	* `guardContentUnlocked` enforces server-side (`contentLocked` /
+	* `sdtContentLocked`). `sdtLocked` protects only the wrapper, not styling.
+	*/
 	const blocksContentStyling = (lockMode) => lockMode === "contentLocked" || lockMode === "sdtContentLocked";
+	/**
+	* Stable reason an inline (run-level) styling command is disabled because the
+	* selection overlaps a content control whose lock forbids styling it — Word
+	* parity (SD-3274): SuperDoc must not leave styling controls clickable when
+	* the mutation cannot apply. Block-range scoped (same precision as
+	* `computeActiveContentControlLockModes`), so this can over-disable when an
+	* unrelated selection shares a block with a locked control — accepted for
+	* now; alignment/paragraph-level commands are never gated here.
+	*/
 	const contentControlLockReason = (lockModesById) => {
 		for (const lockMode of lockModesById.values()) if (blocksContentStyling(lockMode)) return SUPERDOC_UI_REASONS.contentControlLocked;
 	};
-	const trackDecisionReason = (command, supported, readonly, selection$1, doc) => {
+	/** Stable reason a tracked-change decision command is disabled, or undefined when enabled. */
+	const trackDecisionReason = (command, supported, readonly, selection, doc) => {
 		if (!supported) return command.scope === "all" ? SUPERDOC_UI_REASONS.bulkDecisionsDisabled : unavailableRouteReason(doc);
 		if (readonly) return SUPERDOC_UI_REASONS.documentReadonly;
-		if (command.scope !== "all" && selection$1.activeChangeIds.length === 0) return SUPERDOC_UI_REASONS.selectionRequired;
+		if (command.scope !== "all" && selection.activeChangeIds.length === 0) return SUPERDOC_UI_REASONS.selectionRequired;
 	};
 	const hostCommandSupport = (command) => {
 		const host = getHost();
-		const commands$1 = safeCall(typeof host?.getCapabilities === "function" ? () => host.getCapabilities() : void 0, null)?.editableSubset?.commands;
-		if (Array.isArray(commands$1)) return commands$1.find((entry) => entry?.command === command || entry?.id === command) ?? null;
-		if (commands$1 && typeof commands$1 === "object") {
-			const record = commands$1[command];
+		const commands = safeCall(typeof host?.getCapabilities === "function" ? () => host.getCapabilities() : void 0, null)?.editableSubset?.commands;
+		if (Array.isArray(commands)) return commands.find((entry) => entry?.command === command || entry?.id === command) ?? null;
+		if (commands && typeof commands === "object") {
+			const record = commands[command];
 			return record && typeof record === "object" ? record : null;
 		}
 		return null;
@@ -5046,7 +5825,7 @@ function createSuperDocUI(options) {
 		if (support && (support.status === "supported" || support.enabled === true)) return void 0;
 		return SUPERDOC_UI_REASONS.bulkDecisionsDisabled;
 	};
-	const computeCommandState = (id, doc, selection$1, projectedInlineValues, lockModesById = /* @__PURE__ */ new Map()) => {
+	const computeCommandState = (id, doc, selection, projectedInlineValues, lockModesById = /* @__PURE__ */ new Map()) => {
 		if (customCommands.has(id)) return normalizeCommandState({
 			supported: true,
 			enabled: true,
@@ -5073,7 +5852,7 @@ function createSuperDocUI(options) {
 			const supportsSingle = typeof tcApi?.decide === "function" || typeof tcApi?.[trackCommand.kind] === "function";
 			const supportsAll = typeof tcApi?.decide === "function" || typeof tcApi?.[`${trackCommand.kind}All`] === "function";
 			const supported = trackCommand.scope === "all" ? supportsAll : supportsSingle;
-			const reason = bulkTrackDecisionBlockedReason(trackCommand, tcApi) ?? trackDecisionReason(trackCommand, supported, reviewMutationsAreReadOnly(), selection$1, doc);
+			const reason = bulkTrackDecisionBlockedReason(trackCommand, tcApi) ?? trackDecisionReason(trackCommand, supported, reviewMutationsAreReadOnly(), selection, doc);
 			return normalizeCommandState({
 				enabled: reason == null,
 				active: false,
@@ -5128,7 +5907,7 @@ function createSuperDocUI(options) {
 				supported: true,
 				reason: lockReason
 			}, "builtin");
-			const enabled = selectionBlockIds(selection$1).length > 0 || resolveInlineSelectionTarget(selection$1) != null;
+			const enabled = selectionBlockIds(selection).length > 0 || resolveInlineSelectionTarget(selection) != null;
 			return normalizeCommandState({
 				enabled,
 				active: false,
@@ -5171,10 +5950,10 @@ function createSuperDocUI(options) {
 				reason
 			}, "builtin");
 		}
-		const active = commandActiveState(descriptor, doc, selection$1);
-		const value = routedCommandValue(descriptor, doc, selection$1, projectedInlineValues);
-		if (descriptor.list?.mode === "indent" || descriptor.list?.mode === "outdent") return computeHybridIndentCommandState(descriptor, doc, readonly, selection$1, active, value);
-		if (descriptor.list?.mode === "toggle-seed") return computeListToggleCommandState(descriptor, doc, readonly, selection$1, active, value);
+		const active = commandActiveState(descriptor, doc, selection);
+		const value = routedCommandValue(descriptor, doc, selection, projectedInlineValues);
+		if (descriptor.list?.mode === "indent" || descriptor.list?.mode === "outdent") return computeHybridIndentCommandState(descriptor, doc, readonly, selection, active, value);
+		if (descriptor.list?.mode === "toggle-seed") return computeListToggleCommandState(descriptor, doc, readonly, selection, active, value);
 		if (descriptor.mutates && readonly) return normalizeCommandState({
 			enabled: false,
 			active,
@@ -5182,7 +5961,7 @@ function createSuperDocUI(options) {
 			value,
 			reason: SUPERDOC_UI_REASONS.documentReadonly
 		}, "builtin");
-		if (descriptor.inline && !resolveInlineSelectionTarget(selection$1)) {
+		if (descriptor.inline && !resolveInlineSelectionTarget(selection)) {
 			const lockReason = contentControlLockReason(lockModesById);
 			if (lockReason) return normalizeCommandState({
 				enabled: false,
@@ -5191,7 +5970,7 @@ function createSuperDocUI(options) {
 				value,
 				reason: lockReason
 			}, "builtin");
-			return normalizeCommandState(selectionBlockIds(selection$1).length > 0 && typeof getHost()?.setPendingInlineFormat === "function" ? {
+			return normalizeCommandState(selectionBlockIds(selection).length > 0 && typeof getHost()?.setPendingInlineFormat === "function" ? {
 				enabled: true,
 				active,
 				supported: true,
@@ -5204,14 +5983,14 @@ function createSuperDocUI(options) {
 				reason: SUPERDOC_UI_REASONS.rangeSelectionRequired
 			}, "builtin");
 		}
-		if ((descriptor.blockParagraph || descriptor.list) && selectionBlockIds(selection$1).length === 0) return normalizeCommandState({
+		if ((descriptor.blockParagraph || descriptor.list) && selectionBlockIds(selection).length === 0) return normalizeCommandState({
 			enabled: false,
 			active,
 			supported: true,
 			value,
 			reason: SUPERDOC_UI_REASONS.selectionRequired
 		}, "builtin");
-		if (descriptor.link && !active && selectionTextAddresses(selection$1).length === 0 && !collapsedTextAddressFromSelection(selection$1)) return normalizeCommandState({
+		if (descriptor.link && !active && selectionTextAddresses(selection).length === 0 && !collapsedTextAddressFromSelection(selection)) return normalizeCommandState({
 			enabled: false,
 			active,
 			supported: true,
@@ -5234,7 +6013,7 @@ function createSuperDocUI(options) {
 			value
 		}, "builtin");
 	};
-	function hyperlinkOverlapsSelection(link, selection$1) {
+	function hyperlinkOverlapsSelection(link, selection) {
 		const anchor = link.address?.anchor;
 		const start = anchor?.start;
 		const end = anchor?.end;
@@ -5244,7 +6023,7 @@ function createSuperDocUI(options) {
 		const linkStart = typeof start?.offset === "number" ? start.offset : null;
 		const linkEnd = typeof end?.offset === "number" ? end.offset : null;
 		if (linkStart == null || linkEnd == null) return false;
-		const target = selection$1.target;
+		const target = selection.target;
 		const segments = target && Array.isArray(target.segments) ? target.segments : [];
 		for (const segment of segments) {
 			const segmentBlockId = typeof segment?.blockId === "string" ? segment.blockId : null;
@@ -5267,10 +6046,15 @@ function createSuperDocUI(options) {
 		}
 		return false;
 	}
-	const resolveCurrentHyperlink = (doc, selection$1) => {
+	/**
+	* Resolve the hyperlink overlapping the current selection/caret via
+	* `hyperlinks.list({ within })` scoped to the selection's covered blocks.
+	* Returns the first overlapping list row (`{ address, properties }`) or null.
+	*/
+	const resolveCurrentHyperlink = (doc, selection) => {
 		const linksApi = doc?.hyperlinks;
 		if (!linksApi || typeof linksApi.list !== "function") return null;
-		const blockIds = selectionBlockIds(selection$1);
+		const blockIds = selectionBlockIds(selection);
 		if (!canProbeEverySelectedBlock(blockIds)) return null;
 		for (const blockId of blockIds) {
 			const within = {
@@ -5279,44 +6063,52 @@ function createSuperDocUI(options) {
 				nodeId: blockId
 			};
 			const { value: result } = readAsync(`hyperlinks:${blockId}`, contentToken(), () => linksApi.list({ within }), (raw) => raw && typeof raw === "object" ? raw : null);
-			const hit = (result && Array.isArray(result.items) ? result.items : []).find((item) => hyperlinkOverlapsSelection(item, selection$1));
+			const hit = (result && Array.isArray(result.items) ? result.items : []).find((item) => hyperlinkOverlapsSelection(item, selection));
 			if (hit) return hit;
 		}
 		return null;
 	};
-	const commandActiveState = (descriptor, doc, selection$1) => {
-		if (descriptor.link) return resolveCurrentHyperlink(doc, selection$1) != null;
-		if (descriptor.list?.mode === "toggle-seed" && descriptor.list.seed) return readListSeed(doc, selection$1) === descriptor.list.seed;
+	/**
+	* Active state for a routed command. Links resolve by public hyperlink
+	* address overlap; list commands read the current block's list state and
+	* match the seeded kind. Other inline marks use the selection mark set when
+	* the host exposes it.
+	*/
+	const commandActiveState = (descriptor, doc, selection) => {
+		if (descriptor.link) return resolveCurrentHyperlink(doc, selection) != null;
+		if (descriptor.list?.mode === "toggle-seed" && descriptor.list.seed) return readListSeed(doc, selection) === descriptor.list.seed;
 		const pending = pendingInlineActive(descriptor);
 		if (pending !== null) return pending;
 		const optimistic = optimisticInlineToggles.get(descriptor.id);
-		const selectionSignature$1 = selectionInlineValueSignature(selection$1);
-		if (selectionSignature$1 && optimistic?.selectionSignature === selectionSignature$1) return optimistic.active;
-		const effective = effectiveMarkActiveState(descriptor, selection$1);
+		const selectionSignature = selectionInlineValueSignature(selection);
+		if (selectionSignature && optimistic?.selectionSignature === selectionSignature) return optimistic.active;
+		const effective = effectiveMarkActiveState(descriptor, selection);
 		if (effective !== null) return effective;
-		return commandIsActive(descriptor, selection$1);
+		return commandIsActive(descriptor, selection);
 	};
-	const routedCommandValue = (descriptor, doc, selection$1, projectedInlineValues) => {
+	/** Live `value` for a routed command, when modeled (current paragraph style / link href). */
+	const routedCommandValue = (descriptor, doc, selection, projectedInlineValues) => {
 		if (descriptor.inline && isProjectedInlineSelectionValueKey(descriptor.inline.key)) {
 			const pending = pendingInlineValueFor(descriptor);
 			if (pending !== void 0) return pending;
 			const projected = projectedInlineValues[descriptor.inline.key];
 			if (projected !== void 0) return projected;
-			const signature = selectionInlineValueSignature(selection$1);
+			const signature = selectionInlineValueSignature(selection);
 			const cached = signature ? optimisticInlineValues.get(descriptor.inline.key) : void 0;
 			if (signature && cached?.selectionSignature === signature) return cached.value;
 		}
 		if (descriptor.id === "linked-style") {
-			const { style: active } = computeActiveParagraphStyle(selection$1, getStyleCatalog().cache);
+			const { style: active } = computeActiveParagraphStyle(selection, getStyleCatalog().cache);
 			if (!active.styleId || active.mixed) return void 0;
 			return {
 				styleId: active.styleId,
 				styleName: active.styleName
 			};
 		}
-		if (descriptor.id === "text-align") return readToolbarParagraphAlignment(doc, selection$1);
-		if (descriptor.id === "link") return readActiveLinkHref(doc, selection$1) ?? void 0;
+		if (descriptor.id === "text-align") return readToolbarParagraphAlignment(doc, selection);
+		if (descriptor.id === "link") return readActiveLinkHref(doc, selection) ?? void 0;
 	};
+	/** Read one block's list state and cache status through the selected story's list-state seam. */
 	const readListStateSnapshotForBlock = (doc, blockId, story) => {
 		const listsApi = doc?.lists;
 		if (!listsApi) return {
@@ -5338,14 +6130,22 @@ function createSuperDocUI(options) {
 			status
 		};
 	};
+	/** Read one block's settled list state through the selected story's list-state seam. */
 	const readListStateForBlock = (doc, blockId, story) => {
 		return readListStateSnapshotForBlock(doc, blockId, story).value;
 	};
+	/** Read one block's list seed (`'bullet'` / `'ordered'`) in the selected story. */
 	const readListSeedForBlock = (doc, blockId, story) => {
 		const result = readListStateForBlock(doc, blockId, story);
 		if (!result || result.isListItem !== true) return null;
 		return result.seed === "bullet" || result.seed === "ordered" ? result.seed : null;
 	};
+	/**
+	* Read whether a block is a list item. `null` means the authoritative state is
+	* unavailable or has not settled yet; it must never be interpreted as a plain
+	* paragraph. A list item may legitimately have no bullet/ordered seed (for
+	* example, a linked Word numbering definition).
+	*/
 	const readListMembershipSnapshotForBlock = (doc, blockId, story) => {
 		const snapshot = readListStateSnapshotForBlock(doc, blockId, story);
 		const result = snapshot.value;
@@ -5354,15 +6154,17 @@ function createSuperDocUI(options) {
 			status: snapshot.status
 		};
 	};
-	const readListSeed = (doc, selection$1) => {
-		const blockIds = selectionBlockIds(selection$1);
+	/** Read a uniform list seed across the covered blocks, or null when mixed / non-list. */
+	const readListSeed = (doc, selection) => {
+		const blockIds = selectionBlockIds(selection);
 		if (blockIds.length === 0 || !canProbeEverySelectedBlock(blockIds)) return null;
-		const story = selectionStory(selection$1);
+		const story = selectionStory(selection);
 		const firstSeed = readListSeedForBlock(doc, blockIds[0], story);
 		if (firstSeed !== "bullet" && firstSeed !== "ordered") return null;
 		for (const blockId of blockIds.slice(1)) if (readListSeedForBlock(doc, blockId, story) !== firstSeed) return null;
 		return firstSeed;
 	};
+	/** Read a paragraph node in its story through the async read coordinator. */
 	const readNodeById = (doc, blockId, story) => {
 		if (!doc) return {
 			value: null,
@@ -5399,11 +6201,12 @@ function createSuperDocUI(options) {
 	const isProjectionResolvedParagraphAlignment = (value) => {
 		return value === "start" || value === "end" || value === "distributed" || value === "numTab" || value === "lowKashida" || value === "mediumKashida" || value === "highKashida" || value === "thaiDistribute";
 	};
-	const readEffectiveParagraphAlignments = (selection$1, blockIds) => {
+	/** Read effective paragraph alignments from the mounted, style-resolved layout. */
+	const readEffectiveParagraphAlignments = (selection, blockIds) => {
 		const host = getHost();
 		const readByIds = host?.readMountedProjectionBlocksByIds;
 		if (typeof readByIds !== "function") return null;
-		const story = selectionStoryLocator(selection$1);
+		const story = selectionStoryLocator(selection);
 		const blocks = safeCall(() => story ? readByIds.call(host, [...blockIds], story) : readByIds.call(host, [...blockIds]), null);
 		if (!Array.isArray(blocks)) return /* @__PURE__ */ new Map();
 		const projectionBlocks = collectProjectionTextBlocks(blocks);
@@ -5418,6 +6221,7 @@ function createSuperDocUI(options) {
 		}
 		return alignments;
 	};
+	/** Read public paragraph alignment, then fall back to the resolved projection. */
 	const readParagraphAlignment = (doc, blockId, story, effectiveAlignments) => {
 		const { value: result, status, refreshing } = readNodeById(doc, blockId, story);
 		const effective = effectiveAlignments?.get(blockId);
@@ -5454,11 +6258,12 @@ function createSuperDocUI(options) {
 		};
 		return { status: "unavailable" };
 	};
-	const readUniformParagraphAlignment = (doc, selection$1) => {
-		const blockIds = selectionBlockIds(selection$1);
+	/** Resolve a uniform effective alignment across every selected paragraph. */
+	const readUniformParagraphAlignment = (doc, selection) => {
+		const blockIds = selectionBlockIds(selection);
 		if (blockIds.length === 0 || !canProbeEverySelectedBlock(blockIds)) return { status: "unavailable" };
-		const story = selectionStory(selection$1);
-		const effectiveAlignments = readEffectiveParagraphAlignments(selection$1, blockIds);
+		const story = selectionStory(selection);
+		const effectiveAlignments = readEffectiveParagraphAlignments(selection, blockIds);
 		const first = readParagraphAlignment(doc, blockIds[0], story, effectiveAlignments);
 		if (first.status !== "uniform") return first;
 		for (const blockId of blockIds.slice(1)) {
@@ -5468,22 +6273,23 @@ function createSuperDocUI(options) {
 		}
 		return first;
 	};
-	const paragraphAlignmentSelectionSignature = (selection$1) => {
-		const blockIds = selectionBlockIds(selection$1);
+	const paragraphAlignmentSelectionSignature = (selection) => {
+		const blockIds = selectionBlockIds(selection);
 		if (blockIds.length === 0) return null;
-		return `${storyLocatorSignature(selectionStory(selection$1))}:${blockIds.join(",")}`;
+		return `${storyLocatorSignature(selectionStory(selection))}:${blockIds.join(",")}`;
 	};
-	const readToolbarParagraphAlignment = (doc, selection$1) => {
-		const resolution = readUniformParagraphAlignment(doc, selection$1);
+	/** Keep a toolbar pick stable until its painted paragraph state is readable. */
+	const readToolbarParagraphAlignment = (doc, selection) => {
+		const resolution = readUniformParagraphAlignment(doc, selection);
 		const resolved = resolution.status === "uniform" ? resolution.value : void 0;
 		const optimistic = optimisticParagraphAlignment;
 		if (!optimistic) return resolved;
-		const selectionSignature$1 = paragraphAlignmentSelectionSignature(selection$1);
-		if (selectionSignature$1 && selectionSignature$1 !== optimistic.selectionSignature) {
+		const selectionSignature = paragraphAlignmentSelectionSignature(selection);
+		if (selectionSignature && selectionSignature !== optimistic.selectionSignature) {
 			optimisticParagraphAlignment = null;
 			return resolved;
 		}
-		if (!selectionSignature$1) return optimistic.value;
+		if (!selectionSignature) return optimistic.value;
 		if (!optimistic.settled) return optimistic.value;
 		if (resolution.status !== "pending") {
 			optimisticParagraphAlignment = null;
@@ -5491,14 +6297,14 @@ function createSuperDocUI(options) {
 		}
 		return optimistic.value;
 	};
-	const armOptimisticParagraphAlignment = (selection$1, payload) => {
+	const armOptimisticParagraphAlignment = (selection, payload) => {
 		const alignment = normalizeParagraphAlignment(payload);
-		const selectionSignature$1 = paragraphAlignmentSelectionSignature(selection$1);
-		const blockIds = selectionBlockIds(selection$1);
-		if (!alignment || !selectionSignature$1 || blockIds.length === 0) return null;
+		const selectionSignature = paragraphAlignmentSelectionSignature(selection);
+		const blockIds = selectionBlockIds(selection);
+		if (!alignment || !selectionSignature || blockIds.length === 0) return null;
 		const generation = ++optimisticParagraphAlignmentGeneration;
 		optimisticParagraphAlignment = {
-			selectionSignature: selectionSignature$1,
+			selectionSignature,
 			value: alignment,
 			generation,
 			settled: false,
@@ -5521,6 +6327,16 @@ function createSuperDocUI(options) {
 		}
 		optimistic.settled = true;
 	};
+	/**
+	* Await a block's list membership authoritatively. Membership comes from
+	* `isListItem`, not `seed`: linked/custom Word numbering can be a valid list
+	* item while returning `seed: null`. Command execution must also fail closed
+	* when membership cannot be resolved instead of assuming a plain paragraph.
+	*
+	* The read resolves directly instead of peeking at the async cache. Only the
+	* first selected block is warmed by the command-state snapshot, so command
+	* execution cannot depend on that cache being warm (SD-3659).
+	*/
 	const resolveListMembershipForBlockAsync = async (doc, blockId, story) => {
 		const listsApi = doc?.lists;
 		if (!listsApi) return null;
@@ -5537,6 +6353,7 @@ function createSuperDocUI(options) {
 			return null;
 		}
 	};
+	/** Read a list seed directly for mutation planning instead of trusting the reactive cache. */
 	const resolveListSeedForBlock = (doc, blockId, story) => {
 		const unavailable = {
 			resolved: false,
@@ -5565,6 +6382,7 @@ function createSuperDocUI(options) {
 			return unavailable;
 		}
 	};
+	/** Await a block's current paragraph indentation authoritatively. */
 	const resolveParagraphIndentationForBlockAsync = async (doc, blockId, story) => {
 		if (!doc) return null;
 		try {
@@ -5578,7 +6396,7 @@ function createSuperDocUI(options) {
 			return null;
 		}
 	};
-	const computeHybridIndentCommandState = (descriptor, doc, readonly, selection$1, active, value) => {
+	const computeHybridIndentCommandState = (descriptor, doc, readonly, selection, active, value) => {
 		if (descriptor.mutates && readonly) return normalizeCommandState({
 			enabled: false,
 			active,
@@ -5586,7 +6404,7 @@ function createSuperDocUI(options) {
 			value,
 			reason: SUPERDOC_UI_REASONS.documentReadonly
 		}, "builtin");
-		const blockIds = selectionBlockIds(selection$1);
+		const blockIds = selectionBlockIds(selection);
 		if (blockIds.length === 0) return normalizeCommandState({
 			enabled: false,
 			active,
@@ -5599,7 +6417,7 @@ function createSuperDocUI(options) {
 		const paragraphClearIndent = resolveDocOperation(doc, "format.paragraph.clearIndentation");
 		const mode = descriptor.list?.mode;
 		const paragraphOpAvailable = mode === "indent" ? paragraphSetIndent != null : paragraphSetIndent != null || paragraphClearIndent != null;
-		const story = selectionStory(selection$1);
+		const story = selectionStory(selection);
 		let listMembership = null;
 		if (story.storyType !== "body") {
 			listMembership = [];
@@ -5683,7 +6501,7 @@ function createSuperDocUI(options) {
 			reason: unavailableRouteReason(doc)
 		}, "builtin");
 	};
-	const computeListToggleCommandState = (descriptor, doc, readonly, selection$1, active, value) => {
+	const computeListToggleCommandState = (descriptor, doc, readonly, selection, active, value) => {
 		if (descriptor.mutates && readonly) return normalizeCommandState({
 			enabled: false,
 			active,
@@ -5691,7 +6509,7 @@ function createSuperDocUI(options) {
 			value,
 			reason: SUPERDOC_UI_REASONS.documentReadonly
 		}, "builtin");
-		const blockIds = selectionBlockIds(selection$1);
+		const blockIds = selectionBlockIds(selection);
 		if (blockIds.length === 0) return normalizeCommandState({
 			enabled: false,
 			active,
@@ -5699,7 +6517,7 @@ function createSuperDocUI(options) {
 			value,
 			reason: SUPERDOC_UI_REASONS.selectionRequired
 		}, "builtin");
-		const story = selectionStory(selection$1);
+		const story = selectionStory(selection);
 		const listsApi = doc?.lists;
 		if (!(typeof listsApi?.getStateInStory === "function" || story.storyType === "body" && typeof listsApi?.getState === "function")) return normalizeCommandState({
 			enabled: false,
@@ -5727,7 +6545,7 @@ function createSuperDocUI(options) {
 			supported: true,
 			value
 		}, "builtin");
-		if (snapshots.some(({ value: state$1 }) => state$1 === null)) return normalizeCommandState({
+		if (snapshots.some(({ value: state }) => state === null)) return normalizeCommandState({
 			enabled: false,
 			active,
 			supported: false,
@@ -5735,7 +6553,7 @@ function createSuperDocUI(options) {
 			reason: SUPERDOC_UI_REASONS.operationUnavailable
 		}, "builtin");
 		const seed = descriptor.list?.seed;
-		const shouldRemove = snapshots.every(({ value: state$1 }) => state$1?.isListItem === true && state$1.seed === seed);
+		const shouldRemove = snapshots.every(({ value: state }) => state?.isListItem === true && state.seed === seed);
 		if (story.storyType === "body") return normalizeCommandState(!shouldRemove || resolveDocOperation(doc, "lists.remove") != null ? {
 			enabled: true,
 			active,
@@ -5763,10 +6581,12 @@ function createSuperDocUI(options) {
 			reason: SUPERDOC_UI_REASONS.operationUnavailable
 		}, "builtin");
 	};
-	const readActiveLinkHref = (doc, selection$1) => {
-		const href = (resolveCurrentHyperlink(doc, selection$1)?.properties)?.href;
+	/** Read the active hyperlink's href overlapping the selection, when present. */
+	const readActiveLinkHref = (doc, selection) => {
+		const href = (resolveCurrentHyperlink(doc, selection)?.properties)?.href;
 		return typeof href === "string" ? href : null;
 	};
+	/** State for a command routed through a public SuperDoc-instance method. */
 	const computeInstanceCommandState = (descriptor) => {
 		if (!getEditor()) return normalizeCommandState({
 			enabled: false,
@@ -5788,12 +6608,14 @@ function createSuperDocUI(options) {
 			value: descriptorValue(descriptor)
 		}, "builtin");
 	};
+	/** Live active state for a host-owned chrome control (`ruler`, `formatting-marks`). */
 	const chromeActiveState = (descriptor) => {
 		const config = superdoc?.config ?? void 0;
 		if (descriptor.valueFrom === "ruler") return Boolean(config?.rulers);
 		if (descriptor.valueFrom === "formattingMarks") return Boolean((config?.layoutEngineOptions)?.showFormattingMarks);
 		return false;
 	};
+	/** State for a table cell-context command routed through `tables.*`. */
 	const computeTableCommandState = (descriptor, doc, readonly) => {
 		if (readonly) return normalizeCommandState({
 			enabled: false,
@@ -5820,12 +6642,14 @@ function createSuperDocUI(options) {
 			supported: true
 		}, "builtin");
 	};
+	/** Resolve a descriptor's live `value` from public controller state, when modeled. */
 	const descriptorValue = (descriptor) => {
 		if (descriptor.valueFrom === "zoom") return computeZoom().value;
 		if (descriptor.valueFrom === "documentMode") return readDocumentMode();
 		if (descriptor.valueFrom === "measurementUnit") return readMeasurementUnit();
 		if (descriptor.valueFrom === "ruler" || descriptor.valueFrom === "formattingMarks") return chromeActiveState(descriptor);
 	};
+	/** Validate normalized payloads before invoking public SuperDoc-instance methods. */
 	const instanceCommandPayloadIsValid = (descriptor, payload) => {
 		if (descriptor.id === "zoom") return typeof payload === "number" && Number.isFinite(payload) && payload > 0;
 		if (descriptor.id === "document-mode") return payload === "editing" || payload === "suggesting" || payload === "viewing";
@@ -5833,7 +6657,7 @@ function createSuperDocUI(options) {
 		return true;
 	};
 	const allCommandIds = () => {
-		return [...new Set([...ALL_BUILT_IN_COMMAND_IDS, ...customCommands.keys()])];
+		return [.../* @__PURE__ */ new Set([...ALL_BUILT_IN_COMMAND_IDS, ...customCommands.keys()])];
 	};
 	const DEFAULT_PARAGRAPH_STYLE_ID = "Normal";
 	const EMPTY_STYLES_SLICE = {
@@ -5847,6 +6671,14 @@ function createSuperDocUI(options) {
 		sourceStatus: null,
 		diagnostics: []
 	};
+	/**
+	* Read the public Document API style catalogue (`doc.styles.getCatalog`)
+	* through the async read coordinator. A promise-returning browser read
+	* settles into the cache (keyed by content revision) instead of collapsing
+	* the catalogue to `null`. `value` is `null` when the styles surface is
+	* unreachable (worker-backed `doc` is null or the operation is missing); the
+	* accompanying {@link SliceStatus} reports pending/stale/ready.
+	*/
 	const readStyleCatalogLive = (input) => {
 		const stylesApi = getDoc()?.styles;
 		if (!stylesApi || typeof stylesApi.getCatalog !== "function") return {
@@ -5855,6 +6687,7 @@ function createSuperDocUI(options) {
 		};
 		return readAsync(`styles:catalog:${JSON.stringify(input ?? {})}`, contentToken(), () => stylesApi.getCatalog(input), (raw) => raw && typeof raw === "object" ? raw : null);
 	};
+	/** Resolve the catalogue (coordinator-cached by content revision) plus its readiness. */
 	const getStyleCatalog = () => {
 		const full = readStyleCatalogLive({ includePreview: true });
 		if (!full.value) return {
@@ -5877,6 +6710,13 @@ function createSuperDocUI(options) {
 			status: combineStatus(full.status, quickResult.status)
 		};
 	};
+	/**
+	* Read one block's paragraph `styleRef` through the public `getNodeById`
+	* read. `ok` distinguishes a successful read (styleRef may be null when the
+	* paragraph has no explicit style) from an unavailable read (no operation, a
+	* promise in worker mode, or a missing node) so active-style resolution can
+	* fail closed precisely.
+	*/
 	const readBlockStyleRef = (doc, blockId, story) => {
 		const { value: result, status } = readNodeById(doc, blockId, story);
 		if (!result) return {
@@ -5899,7 +6739,13 @@ function createSuperDocUI(options) {
 			status
 		};
 	};
-	const computeActiveParagraphStyle = (selection$1, catalog) => {
+	/**
+	* Resolve the active paragraph style from the current selection. Handles the
+	* uniform, default (no explicit style → document default paragraph style),
+	* and mixed cases, and fails closed with diagnostics when block reads are
+	* unavailable.
+	*/
+	const computeActiveParagraphStyle = (selection, catalog) => {
 		const diagnostics = [];
 		const doc = getDoc();
 		if (!doc) {
@@ -5918,7 +6764,7 @@ function createSuperDocUI(options) {
 				status: "ready"
 			};
 		}
-		const blockIds = selectionBlockIds(selection$1);
+		const blockIds = selectionBlockIds(selection);
 		if (blockIds.length === 0) {
 			diagnostics.push({
 				severity: "info",
@@ -5957,7 +6803,7 @@ function createSuperDocUI(options) {
 		let blockReadFailures = 0;
 		let defaultReadFailures = 0;
 		let readStatus = "ready";
-		const story = selectionStory(selection$1);
+		const story = selectionStory(selection);
 		for (const blockId of blockIds) {
 			const read = readBlockStyleRef(doc, blockId, story);
 			readStatus = combineStatus(readStatus, read.status);
@@ -5969,13 +6815,13 @@ function createSuperDocUI(options) {
 				defaultReadFailures += 1;
 				continue;
 			}
-			const styleId$1 = read.styleRef ?? defaultId;
-			if (!styleId$1) {
+			const styleId = read.styleRef ?? defaultId;
+			if (!styleId) {
 				defaultReadFailures += 1;
 				continue;
 			}
 			resolved += 1;
-			resolvedIds.add(styleId$1);
+			resolvedIds.add(styleId);
 		}
 		if (resolved === 0) {
 			const onlyDefaultUnavailable = defaultReadFailures > 0 && blockReadFailures === 0;
@@ -6031,10 +6877,10 @@ function createSuperDocUI(options) {
 			status: readStatus
 		};
 	};
-	const computeStyles = (selection$1) => {
+	const computeStyles = (selection) => {
 		if (!getEditor()) return EMPTY_STYLES_SLICE;
 		const { cache: catalog, status: catalogStatus } = getStyleCatalog();
-		const { style: active, status: activeStatus } = computeActiveParagraphStyle(selection$1, catalog);
+		const { style: active, status: activeStatus } = computeActiveParagraphStyle(selection, catalog);
 		let diagnostics;
 		if (catalog) diagnostics = active.diagnostics.length === 0 ? catalog.full.diagnostics : [...catalog.full.diagnostics, ...active.diagnostics];
 		else diagnostics = [{
@@ -6044,7 +6890,7 @@ function createSuperDocUI(options) {
 		}, ...active.diagnostics];
 		return {
 			ready: true,
-			status: combineStatus(catalogStatus, activeStatus, selection$1.status),
+			status: combineStatus(catalogStatus, activeStatus, selection.status),
 			catalogRevision: catalog?.full.revision ?? null,
 			quickGallery: catalog?.quickGallery ?? [],
 			activeParagraphStyleId: active.styleId,
@@ -6056,32 +6902,32 @@ function createSuperDocUI(options) {
 	};
 	const computeState = () => {
 		const documentMode = readDocumentMode();
-		const selection$1 = computeSelection();
-		if (selection$1.status === "ready") pruneSelectionScopedAsyncReads(selection$1);
-		reconcilePendingInlineFormat(selection$1);
-		const selectionSignature$1 = selectionInlineValueSignature(selection$1);
-		for (const [commandId, optimistic] of optimisticInlineToggles) if (!selectionSignature$1 || optimistic.selectionSignature !== selectionSignature$1) optimisticInlineToggles.delete(commandId);
-		else if (optimistic.settled && selection$1.status === "ready") optimisticInlineToggles.delete(commandId);
+		const 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 {
 			ready: getEditor() != null,
 			documentMode,
 			document: computeDocument(),
-			selection: selection$1,
+			selection,
 			toolbar: {
 				context: documentMode,
-				commands: computeCommandStates(selection$1),
+				commands: computeCommandStates(selection),
 				copyFormatActive: painter.mode !== "idle"
 			},
-			comments: computeComments(selection$1),
-			trackChanges: computeTrackChanges(selection$1),
-			contentControls: computeContentControls(selection$1),
+			comments: computeComments(selection),
+			trackChanges: computeTrackChanges(selection),
+			contentControls: computeContentControls(selection),
 			zoom: computeZoom(),
 			fonts: computeFonts(),
-			styles: computeStyles(selection$1)
+			styles: computeStyles(selection)
 		};
 	};
-	const syncOptimisticInlineSelection = (selection$1) => {
-		const nextSignature = selectionInlineValueSignature(selection$1);
+	const syncOptimisticInlineSelection = (selection) => {
+		const nextSignature = selectionInlineValueSignature(selection);
 		if (nextSignature && lastOptimisticInlineSelectionSignature && nextSignature !== lastOptimisticInlineSelectionSignature) {
 			optimisticInlineValues.clear();
 			optimisticInlineToggles.clear();
@@ -6129,8 +6975,8 @@ function createSuperDocUI(options) {
 	let detachDocumentSelection = null;
 	const readHostSelectionSource = () => {
 		const host = getEditor()?.host;
-		const selection$1 = safeCall(host?.getHandles ? () => host.getHandles() : void 0, null)?.editing?.selection;
-		return selection$1 && typeof selection$1.subscribe === "function" ? selection$1 : null;
+		const selection = safeCall(host?.getHandles ? () => host.getHandles() : void 0, null)?.editing?.selection;
+		return selection && typeof selection.subscribe === "function" ? selection : null;
 	};
 	const syncHostSelectionSubscription = () => {
 		const next = readHostSelectionSource();
@@ -6202,7 +7048,8 @@ 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), snapshot) || attaching) return;
+				const target = snapshotRecord && Object.prototype.hasOwnProperty.call(snapshotRecord, "activeReviewTarget") ? snapshotRecord.activeReviewTarget : readHostActiveReviewTarget(next);
+				if (!syncTrackedChangeFocusFromHostReviewTarget(target, snapshot) || attaching) return;
 				recompute();
 			});
 			if (typeof unsubscribe === "function") detachHostReview = unsubscribe;
@@ -6356,7 +7203,29 @@ function createSuperDocUI(options) {
 		state = nextState;
 		for (const listener of [...listeners]) listener(state);
 	};
+	/**
+	* Work that is bound to one specific active editor and cannot survive a swap.
+	* Recomputing aggregate state is not enough for these: a geometry
+	* subscription points at a DOM host that is going away, and an in-flight
+	* async query would publish the old document's result into the new one.
+	*
+	* Populated by the viewport and search handles further down. The handler only
+	* runs on a host event, which cannot happen during construction, so
+	* registering later than `attach` is safe.
+	*/
 	const activeEditorResetHooks = [];
+	/**
+	* The subset bound to the DOCUMENT rather than to the editor.
+	*
+	* `replaceFile()` swaps content in place: the editor object and its host both
+	* survive, so a geometry subscription is still attached to the thing now
+	* rendering the replacement and must be left alone. Search state describes
+	* content that is gone and must not be.
+	*
+	* Measured rather than assumed — after an in-place replace the geometry
+	* subscription is never detached and keeps firing, while `search.total` still
+	* reports the previous document's match count.
+	*/
 	const documentResetHooks = [];
 	const runHooks = (hooks) => {
 		for (const reset of hooks) try {
@@ -6419,6 +7288,20 @@ function createSuperDocUI(options) {
 		};
 	};
 	const sliceHandle = (selector) => select(selector);
+	/**
+	* Wrap an underlying selector {@link Subscribable} (raw `get` + value
+	* `subscribe`) in the main-compatible domain-handle subscription shape so
+	* every customer-facing handle exposes the same contract main does:
+	*
+	*   - `getSnapshot()` reads the current slice;
+	*   - `observe(listener)` emits the current value immediately, then on each
+	*     change (the listener receives the snapshot directly);
+	*   - `subscribe(listener)` is the `{ snapshot }`-shaped alias of `observe`,
+	*     likewise emitting immediately then on change.
+	*
+	* The generic `select(...)` substrate stays raw-value and unchanged; only the
+	* domain handles are composed from this.
+	*/
 	const snapshotHandle = (sub) => {
 		const observe = (listener) => {
 			const safe = (snapshot) => {
@@ -6440,8 +7323,8 @@ function createSuperDocUI(options) {
 	function readTrackDecisionTargetId(target) {
 		return target && typeof target === "object" && typeof target.id === "string" ? String(target.id) : null;
 	}
-	function nonBodySelectionStoryLocator(selection$1) {
-		const story = selectionStoryLocator(selection$1);
+	function nonBodySelectionStoryLocator(selection) {
+		const story = selectionStoryLocator(selection);
 		return story && storyLocatorSignature(story) !== storyLocatorSignature(null) ? story : void 0;
 	}
 	function trackDecisionIdTarget(changeId, story) {
@@ -6451,15 +7334,24 @@ function createSuperDocUI(options) {
 			...story ? { story } : {}
 		};
 	}
-	function trackDecisionRangeFromSelection(selection$1) {
-		if (selection$1.empty) return null;
-		const explicit = selection$1.selectionTarget;
+	/**
+	* Build the Document API range target for a partial tracked-change decision.
+	* The explicit selection target is authoritative and labels its coordinates:
+	* ordinary/insertion selections are visible-space, while a selection that
+	* reaches painted deleted text is projected in tracked space by the host.
+	*
+	* A cross-block or malformed selection fails closed. Its intermediate block
+	* coverage cannot be reconstructed from two endpoints without guessing.
+	*/
+	function trackDecisionRangeFromSelection(selection) {
+		if (selection.empty) return null;
+		const explicit = selection.selectionTarget;
 		const start = explicit?.start;
 		const end = explicit?.end;
 		if (explicit?.kind !== "selection" || start?.kind !== "text" || end?.kind !== "text" || typeof start.blockId !== "string" || start.blockId !== end.blockId || !Number.isInteger(start.offset) || !Number.isInteger(end.offset) || start.offset < 0 || end.offset < 0 || start.offset === end.offset) return null;
 		const rangeStart = Math.min(start.offset, end.offset);
 		const rangeEnd = Math.max(start.offset, end.offset);
-		const story = selectionStoryLocator(selection$1);
+		const story = selectionStoryLocator(selection);
 		return {
 			kind: "range",
 			coordinateSpace: explicit.coordinateSpace === "tracked" ? "tracked" : "visible",
@@ -6478,17 +7370,17 @@ function createSuperDocUI(options) {
 	}
 	function readBodyTrackChangeForDecision(activeId, story) {
 		if (storyLocatorSignature(story) !== storyLocatorSignature(null)) return void 0;
-		const trackChanges$1 = getDoc()?.trackChanges;
-		const list = trackChanges$1?.list;
+		const trackChanges = getDoc()?.trackChanges;
+		const list = trackChanges?.list;
 		if (typeof list !== "function") return void 0;
-		const raw = safeCall(() => list.call(trackChanges$1), null);
+		const raw = safeCall(() => list.call(trackChanges), null);
 		if (isPromiseLike(raw) || !raw || typeof raw !== "object") return void 0;
 		const items = raw.items;
 		if (!Array.isArray(items)) return void 0;
 		return items.map(projectTrackChangesItem).find((item) => item != null && entityRowMatchesRequest(item, activeId, story));
 	}
-	function selectedTextCoversTrackChangeText(selection$1, item) {
-		const selected = normalizeTrackDecisionText(selection$1.quotedText);
+	function selectedTextCoversTrackChangeText(selection, item) {
+		const selected = normalizeTrackDecisionText(selection.quotedText);
 		if (!selected) return false;
 		const payload = trackChangesItemPayload(item);
 		return [
@@ -6520,7 +7412,8 @@ function createSuperDocUI(options) {
 			if (isPromiseLike(result)) return settleCommandExecution(Promise.resolve(result).then((settled) => {
 				return commandResultSucceeded(commandResultFromOperationResult(settled)) ? settled : fallback();
 			}));
-			return settleCommandExecution(commandResultSucceeded(commandResultFromOperationResult(result)) ? result : fallback());
+			const commandResult = commandResultFromOperationResult(result);
+			return settleCommandExecution(commandResultSucceeded(commandResult) ? result : fallback());
 		} catch {
 			return false;
 		}
@@ -6663,8 +7556,8 @@ function createSuperDocUI(options) {
 	const scheduleInlineToggleMutation = (key, mutate) => {
 		if (!inlineToggleMutationActive) {
 			inlineToggleMutationActive = true;
-			inlineToggleMutationIdle = new Promise((resolve$1) => {
-				resolveInlineToggleMutationIdle = resolve$1;
+			inlineToggleMutationIdle = new Promise((resolve) => {
+				resolveInlineToggleMutationIdle = resolve;
 			});
 			try {
 				return {
@@ -6701,20 +7594,21 @@ function createSuperDocUI(options) {
 			release: releaseInlineToggleMutationOnce()
 		};
 	};
-	const UNSUPPORTED_TRACKED_UI_MUTATION_ROUTES = new Set(["create.tableOfContents"]);
+	const UNSUPPORTED_TRACKED_UI_MUTATION_ROUTES = /* @__PURE__ */ new Set(["create.tableOfContents"]);
 	const unsupportedTrackedMutationReceipt = (route) => failedReceipt(`Tracked authoring is not supported for ${route}.`);
 	const editorMutationOptionsForRoute = (route) => {
 		if (readDocumentMode() !== "suggesting") return void 0;
 		if (UNSUPPORTED_TRACKED_UI_MUTATION_ROUTES.has(route)) return unsupportedTrackedMutationReceipt(route);
 		return { changeMode: "tracked" };
 	};
+	/** Clear-patch to send for the current document mode (see TRACKED_CLEAR_INLINE_PATCH). */
 	const clearInlinePatchForMode = () => readDocumentMode() === "suggesting" ? TRACKED_CLEAR_INLINE_PATCH : CLEAR_INLINE_PATCH;
 	const callEditorMutation = (route, op, input) => {
-		const options$1 = editorMutationOptionsForRoute(route);
-		if (options$1 && options$1.success === false) return options$1;
-		return options$1 ? op(input, options$1) : op(input);
+		const options = editorMutationOptionsForRoute(route);
+		if (options && options.success === false) return options;
+		return options ? op(input, options) : op(input);
 	};
-	const captureOptimisticInlineValueResult = (descriptor, selection$1, input, result) => {
+	const captureOptimisticInlineValueResult = (descriptor, selection, input, result) => {
 		const inline = descriptor.inline;
 		if (!inline) return;
 		const commandResult = commandResultFromOperationResult(result);
@@ -6725,35 +7619,35 @@ function createSuperDocUI(options) {
 			return;
 		}
 		if (inline.kind === "toggle" || !isProjectedInlineSelectionValueKey(inline.key)) return;
-		const selectionSignature$1 = selectionInlineValueSignature(selection$1);
-		if (!selectionSignature$1) return;
+		const selectionSignature = selectionInlineValueSignature(selection);
+		if (!selectionSignature) return;
 		const value = normalizeOptimisticInlineSelectionValue(inline.key, input.value);
 		if (value == null) {
 			optimisticInlineValues.delete(inline.key);
 			return;
 		}
 		optimisticInlineValues.set(inline.key, {
-			selectionSignature: selectionSignature$1,
+			selectionSignature,
 			value
 		});
 	};
-	const decorateInlineCommandResult = (descriptor, selection$1, input, result) => {
+	const decorateInlineCommandResult = (descriptor, selection, input, result) => {
 		if (!descriptor.inline || descriptor.inline.kind === "toggle") return result;
 		if (isPromiseLike(result)) return Promise.resolve(result).then((resolved) => {
-			captureOptimisticInlineValueResult(descriptor, selection$1, input, resolved);
+			captureOptimisticInlineValueResult(descriptor, selection, input, resolved);
 			return resolved;
 		});
 		return result;
 	};
-	const captureOptimisticInlineToggle = (descriptor, selection$1, input, result) => {
+	const captureOptimisticInlineToggle = (descriptor, selection, input, result) => {
 		if (descriptor.inline?.kind !== "toggle") return null;
 		if (!commandResultSucceeded(commandResultFromOperationResult(result))) return null;
 		if (typeof input.value !== "boolean" && input.value !== null) return null;
-		const selectionSignature$1 = selectionInlineValueSignature(selection$1);
-		if (!selectionSignature$1) return null;
+		const selectionSignature = selectionInlineValueSignature(selection);
+		if (!selectionSignature) return null;
 		const generation = ++optimisticInlineToggleGeneration;
 		optimisticInlineToggles.set(descriptor.id, {
-			selectionSignature: selectionSignature$1,
+			selectionSignature,
 			active: input.value === true,
 			generation,
 			settled: false
@@ -6821,6 +7715,11 @@ function createSuperDocUI(options) {
 		recompute();
 		return normalizedReceipt;
 	};
+	/**
+	* Apply a Document API operation once per covered block, building the input
+	* from the block id. Returns the last success receipt (or `true`), else the
+	* last result (or `false`). Recompute is the caller's responsibility.
+	*/
 	const applyPerBlock = (route, op, blockIds, buildInput) => {
 		const immediateResults = [];
 		const settledResults = [];
@@ -6839,6 +7738,7 @@ function createSuperDocUI(options) {
 		pendingCommandSettlement = settledResults.length ? Promise.all(settledResults).then((results) => combineCommandResults(results)) : null;
 		return combineCommandResults(immediateResults);
 	};
+	/** Apply a Document API operation once per covered text segment. */
 	const applyPerTextAddress = (route, op, targets, buildInput) => {
 		const immediateResults = [];
 		const settledResults = [];
@@ -6857,15 +7757,25 @@ function createSuperDocUI(options) {
 		pendingCommandSettlement = settledResults.length ? Promise.all(settledResults).then((results) => combineCommandResults(results)) : null;
 		return combineCommandResults(immediateResults);
 	};
-	const callInlineFormatMutation = (route, op, input, selection$1 = state.selection) => {
-		const options$1 = editorMutationOptionsForRoute(route);
-		if (options$1 && options$1.success === false) return options$1;
-		if (!selection$1.selectionTarget) return options$1 ? op(input, options$1) : op(input);
+	/**
+	* Call an inline `format.*` operation against the live selection. Mirrors
+	* `callEditorMutation` (suggesting mode adds `changeMode: 'tracked'`), and
+	* when the target is the host's own editable `selectionTarget` it also
+	* carries the PRIVATE V2 option `offsetSpace: 'selection'` (browser
+	* selection offsets count an inline object as one caret position). The
+	* option is not part of public `MutationOptions`; this is the same cast
+	* pattern the delete/replace callers use.
+	*/
+	const callInlineFormatMutation = (route, op, input, selection = state.selection) => {
+		const options = editorMutationOptionsForRoute(route);
+		if (options && options.success === false) return options;
+		if (!selection.selectionTarget) return options ? op(input, options) : op(input);
 		return op(input, {
-			...options$1 ?? {},
+			...options ?? {},
 			offsetSpace: "selection"
 		});
 	};
+	/** Build the `format.paragraph.*` / `styles.paragraph.*` input for a block. */
 	const buildBlockParagraphInput = (spec, blockId, payload, story) => {
 		const target = paragraphTarget(blockId, story);
 		switch (spec.kind) {
@@ -6910,6 +7820,14 @@ function createSuperDocUI(options) {
 			default: return null;
 		}
 	};
+	/**
+	* Store a caret pick as a pending mark (SD-3654/SD-3652) so the next typed text
+	* carries it. Mirrors ProseMirror `storedMarks`: a toggle flips the stored
+	* value against the current active state; a value command (color/font/size)
+	* stores the value or clears it on a null/empty ("None") payload; a clear
+	* command drops all stored marks. The host applies the store to the created
+	* span on the next insert; settleCommandExecution drives the recompute.
+	*/
 	const storePendingInlineFormat = (descriptor, payload) => {
 		const spec = descriptor.inline;
 		const method = inlineFormatMethod(descriptor);
@@ -6947,9 +7865,9 @@ function createSuperDocUI(options) {
 			immediateResults.push(settled.immediate);
 			settledResults.push(settled.settled);
 		};
-		const run = (op, input, options$1) => {
+		const run = (op, input, options) => {
 			try {
-				record(options$1 ? op(input, options$1) : op(input));
+				record(options ? op(input, options) : op(input));
 			} catch {
 				immediateResults.push(false);
 				settledResults.push(Promise.resolve(false));
@@ -7008,6 +7926,7 @@ function createSuperDocUI(options) {
 		pendingCommandSettlement = settledResults.length ? Promise.all(settledResults).then((results) => combineCommandResults(results)) : null;
 		return combineCommandResults(immediateResults.length ? immediateResults : [false]);
 	};
+	/** Route a block-level paragraph command (`format.paragraph.*` / `styles.paragraph.*`). */
 	const executeBlockParagraph = (descriptor, op, payload) => {
 		const blockIds = selectionBlockIds(state.selection);
 		if (blockIds.length === 0) return false;
@@ -7113,6 +8032,7 @@ function createSuperDocUI(options) {
 		})();
 		return true;
 	};
+	/** Route a list command (`lists.apply` / `lists.remove` / list level changes). */
 	const executeListCommand = (descriptor, op) => {
 		const spec = descriptor.list;
 		const doc = getDoc();
@@ -7150,9 +8070,9 @@ function createSuperDocUI(options) {
 					seed
 				};
 				try {
-					const result$1 = settleOperationResult(callEditorMutation(route, operation, input));
-					immediateResults.push(result$1.immediate);
-					settledResults.push(result$1.settled);
+					const result = settleOperationResult(callEditorMutation(route, operation, input));
+					immediateResults.push(result.immediate);
+					settledResults.push(result.settled);
 				} catch {
 					immediateResults.push(false);
 					settledResults.push(Promise.resolve(false));
@@ -7166,8 +8086,8 @@ function createSuperDocUI(options) {
 		const stateReads = blockIds.map((blockId) => resolveListSeedForBlock(doc, blockId, story));
 		if (stateReads.some(isPromiseLike)) {
 			pendingCommandSettlement = Promise.all(stateReads).then(async (states) => {
-				const result$1 = executeResolved(states);
-				return result$1.settled ? await result$1.settled : result$1.immediate;
+				const result = executeResolved(states);
+				return result.settled ? await result.settled : result.immediate;
 			});
 			return true;
 		}
@@ -7193,6 +8113,7 @@ function createSuperDocUI(options) {
 		const capture = record.capture && typeof record.capture === "object" ? record.capture : null;
 		return record.target ?? capture?.target ?? capture?.selectionTarget ?? record.selectionTarget ?? record.textTarget ?? null;
 	}
+	/** Route a link command (`hyperlinks.wrap` / `insert` / `patch` / `remove`). */
 	const executeLinkCommand = (payload) => {
 		const doc = getDoc();
 		const linksApi = doc?.hyperlinks;
@@ -7328,8 +8249,8 @@ function createSuperDocUI(options) {
 			if (wrapTargets.length > 0) {
 				if (typeof wrap !== "function") return false;
 				try {
-					return applyPerTextAddress("hyperlinks.wrap", wrap, wrapTargets, (target$1) => ({
-						target: target$1,
+					return applyPerTextAddress("hyperlinks.wrap", wrap, wrapTargets, (target) => ({
+						target,
 						link: { destination: { href: normalizedHref } }
 					}));
 				} catch {
@@ -7337,14 +8258,14 @@ function createSuperDocUI(options) {
 				}
 			}
 			const insert = linksApi.insert;
-			const text$1 = readLinkPayloadText(payload, normalizedHref);
-			if (typeof insert !== "function" || text$1.trim() === "") return false;
+			const text = readLinkPayloadText(payload, normalizedHref);
+			if (typeof insert !== "function" || text.trim() === "") return false;
 			const target = collapsedTextAddressFromTarget(payloadTarget) ?? collapsedTextAddressFromSelection(state.selection);
 			if (!target) return false;
 			try {
 				return callEditorMutation("hyperlinks.insert", insert, {
 					target,
-					text: text$1,
+					text,
 					link: { destination: { href: normalizedHref } }
 				});
 			} catch {
@@ -7353,6 +8274,7 @@ function createSuperDocUI(options) {
 		}
 		return false;
 	};
+	/** Route a create command (`create.table` / `create.image` / `create.tableOfContents`). */
 	const executeCreateCommand = (descriptor, op, payload) => {
 		const kind = descriptor.create.kind;
 		const record = payload && typeof payload === "object" ? payload : {};
@@ -7398,16 +8320,16 @@ function createSuperDocUI(options) {
 					}
 				};
 			}
-			const input$1 = {
+			const input = {
 				src,
 				at
 			};
-			if (nonBodyStory) input$1.in = at.kind === "inParagraph" ? resolveActiveHeaderFooterSlot(nonBodyStory) ?? nonBodyStory : nonBodyStory;
-			if (typeof record.alt === "string") input$1.alt = record.alt;
-			if (typeof record.title === "string") input$1.title = record.title;
-			if (record.size && typeof record.size === "object") input$1.size = record.size;
+			if (nonBodyStory) input.in = at.kind === "inParagraph" ? resolveActiveHeaderFooterSlot(nonBodyStory) ?? nonBodyStory : nonBodyStory;
+			if (typeof record.alt === "string") input.alt = record.alt;
+			if (typeof record.title === "string") input.title = record.title;
+			if (record.size && typeof record.size === "object") input.size = record.size;
 			try {
-				return callEditorMutation(descriptor.docRoute, op, input$1);
+				return callEditorMutation(descriptor.docRoute, op, input);
 			} catch {
 				return false;
 			}
@@ -7421,6 +8343,13 @@ function createSuperDocUI(options) {
 			return false;
 		}
 	};
+	/**
+	* Route a table cell-context command (`tables.*`) against the live table
+	* context resolved from the shared facade. Fails closed (`false`) when the
+	* caret is not in a table, the context is incomplete, or the action's
+	* required cell is missing — never calling the operation with a malformed
+	* locator.
+	*/
 	const executeTableCommand = (descriptor, op) => {
 		const spec = descriptor.table;
 		const context = resolveTableContext();
@@ -7433,9 +8362,9 @@ function createSuperDocUI(options) {
 				const host = getHost();
 				const insertRow = ((typeof host?.getHandles === "function" ? host.getHandles() : null)?.editing)?.tables;
 				if (typeof insertRow?.insertRow !== "function") return false;
-				const options$1 = editorMutationOptionsForRoute(descriptor.docRoute);
-				if (options$1 && options$1.success === false) return options$1;
-				return options$1 ? insertRow.insertRow(input, options$1) : insertRow.insertRow(input);
+				const options = editorMutationOptionsForRoute(descriptor.docRoute);
+				if (options && options.success === false) return options;
+				return options ? insertRow.insertRow(input, options) : insertRow.insertRow(input);
 			}
 			return callEditorMutation(descriptor.docRoute, op, input);
 		} catch {
@@ -7476,7 +8405,8 @@ function createSuperDocUI(options) {
 		if (disposed) return false;
 		const custom = customCommands.get(id);
 		if (custom) try {
-			return settleCommandExecution(custom.execute(buildCustomCommandContext(payload, context)));
+			const result = custom.execute(buildCustomCommandContext(payload, context));
+			return settleCommandExecution(result);
 		} catch {
 			return false;
 		}
@@ -7497,7 +8427,8 @@ function createSuperDocUI(options) {
 			if (typeof method !== "function") return false;
 			try {
 				const arg = descriptor.fixedArg !== void 0 ? descriptor.fixedArg : normalized;
-				return settleCommandExecution(method.call(superdoc, arg));
+				const result = method.call(superdoc, arg);
+				return settleCommandExecution(result);
 			} catch {
 				return false;
 			}
@@ -7531,12 +8462,13 @@ function createSuperDocUI(options) {
 					if (getEditor() !== commandEditor || getDoc() !== doc || readDocumentMode() !== commandMode) return false;
 					return callInlineFormatMutation(route, op, input);
 				};
-				const selectionSignature$1 = selectionInlineValueSignature(state.selection) ?? selectionKey(state.selection);
-				const scheduledMutation = descriptor.inline.kind === "toggle" ? scheduleInlineToggleMutation(`${descriptor.id}:${selectionSignature$1}`, mutate) : null;
+				const selectionSignature = selectionInlineValueSignature(state.selection) ?? selectionKey(state.selection);
+				const scheduledMutation = descriptor.inline.kind === "toggle" ? scheduleInlineToggleMutation(`${descriptor.id}:${selectionSignature}`, mutate) : null;
 				releaseScheduledMutation = scheduledMutation?.release ?? null;
 				const mutationResult = scheduledMutation ? scheduledMutation.result : mutate();
 				const optimisticGeneration = captureOptimisticInlineToggle(descriptor, state.selection, input, mutationResult);
-				const immediate = settleCommandExecution(decorateInlineCommandResult(descriptor, state.selection, input, mutationResult), (settled) => {
+				const result = decorateInlineCommandResult(descriptor, state.selection, input, mutationResult);
+				const immediate = settleCommandExecution(result, (settled) => {
 					settleOptimisticInlineToggle(descriptor, optimisticGeneration, settled);
 					releaseScheduledMutation?.();
 					releaseScheduledMutation = null;
@@ -7555,10 +8487,22 @@ function createSuperDocUI(options) {
 				settleOptimisticParagraphAlignment(optimisticAlignmentGeneration, settled);
 			});
 		}
-		if (descriptor.list) return settleCommandExecution(executeListCommand(descriptor, op));
-		if (descriptor.link) return settleCommandExecution(executeLinkCommand(normalized));
-		if (descriptor.create) return settleCommandExecution(executeCreateCommand(descriptor, op, normalized));
-		if (descriptor.table) return settleCommandExecution(executeTableCommand(descriptor, op));
+		if (descriptor.list) {
+			const result = executeListCommand(descriptor, op);
+			return settleCommandExecution(result);
+		}
+		if (descriptor.link) {
+			const result = executeLinkCommand(normalized);
+			return settleCommandExecution(result);
+		}
+		if (descriptor.create) {
+			const result = executeCreateCommand(descriptor, op, normalized);
+			return settleCommandExecution(result);
+		}
+		if (descriptor.table) {
+			const result = executeTableCommand(descriptor, op);
+			return settleCommandExecution(result);
+		}
 		try {
 			return settleCommandExecution(descriptor.mutates ? callEditorMutation(route, op, normalized) : op(normalized));
 		} catch {
@@ -7625,8 +8569,8 @@ function createSuperDocUI(options) {
 		recompute();
 		return true;
 	};
-	const captureFormatPainter = async (selection$1, captureSlice, captureProjected, visibleActiveMarks = []) => {
-		const selTarget = captureSlice?.target ?? selection$1?.target;
+	const captureFormatPainter = async (selection, captureSlice, captureProjected, visibleActiveMarks = []) => {
+		const selTarget = captureSlice?.target ?? selection?.target;
 		if (!selTarget || selTarget["kind"] !== "text") return null;
 		const segments = Array.isArray(selTarget["segments"]) ? selTarget["segments"] : [];
 		if (segments.length === 0) return null;
@@ -7638,7 +8582,8 @@ function createSuperDocUI(options) {
 			const node = (await readBlockNode(paragraphTarget(segment["blockId"], sourceStory)))?.["node"] ?? null;
 			if (!node) continue;
 			const para = getParagraphLikeData(node);
-			const slicedProps = sliceAndIntersectRunProps(Array.isArray(para?.["inlines"]) ? para["inlines"] : [], segment["range"]);
+			const runs = Array.isArray(para?.["inlines"]) ? para["inlines"] : [];
+			const slicedProps = sliceAndIntersectRunProps(runs, segment["range"]);
 			if (!mergedRunProps) mergedRunProps = slicedProps;
 			else mergedRunProps = intersectRunProps(mergedRunProps, slicedProps);
 		}
@@ -7649,9 +8594,9 @@ function createSuperDocUI(options) {
 			underline: "underline",
 			strikethrough: "strike"
 		};
-		const activeMarks = new Set([...captureSlice?.activeMarks ?? (Array.isArray(selection$1?.["activeMarks"]) ? selection$1["activeMarks"] : []), ...visibleActiveMarks]);
+		const activeMarks = /* @__PURE__ */ new Set([...captureSlice?.activeMarks ?? (Array.isArray(selection?.["activeMarks"]) ? selection["activeMarks"] : []), ...visibleActiveMarks]);
 		for (const [markName, patchKey] of Object.entries(MARK_TO_PATCH)) if (activeMarks.has(markName)) inlinePatch[patchKey] = true;
-		const projectedInlineValues = captureProjected ?? await readFormatPainterInlineValues(captureSlice ?? selectionSliceFromInfo(selection$1, "ready"));
+		const projectedInlineValues = captureProjected ?? await readFormatPainterInlineValues(captureSlice ?? selectionSliceFromInfo(selection, "ready"));
 		if (projectedInlineValues.fontFamily) inlinePatch["fontFamily"] = projectedInlineValues.fontFamily;
 		if (projectedInlineValues.color) inlinePatch["color"] = projectedInlineValues.color;
 		if (projectedInlineValues.highlight) inlinePatch["highlight"] = projectedInlineValues.highlight;
@@ -7688,12 +8633,12 @@ function createSuperDocUI(options) {
 			return r["run"]?.["props"];
 		};
 		if (range.start === range.end) {
-			let offset$1 = 0;
+			let offset = 0;
 			for (const run of runs) {
 				const text = getRunText(run);
-				const runStart = offset$1;
-				const runEnd = offset$1 + text.length;
-				offset$1 = runEnd;
+				const runStart = offset;
+				const runEnd = offset + text.length;
+				offset = runEnd;
 				if (range.start >= runStart && range.start <= runEnd) {
 					const rPr = getRunProps(run);
 					return rPr ? { ...rPr } : {};
@@ -7770,7 +8715,8 @@ function createSuperDocUI(options) {
 		if (painter.pointerSelecting || painter.keyboardSelecting) return;
 		const selectionApi = getDoc()?.selection;
 		const readSelection = async () => {
-			return normalizeSelectionInfo(typeof selectionApi?.["current"] === "function" ? await Promise.resolve(selectionApi["current"]({ includeText: true })) : readSelectionInfoLive().value);
+			const rawSelection = typeof selectionApi?.["current"] === "function" ? await Promise.resolve(selectionApi["current"]({ includeText: true })) : readSelectionInfoLive().value;
+			return normalizeSelectionInfo(rawSelection);
 		};
 		const waitForSelectionSettle = () => new Promise((resolve) => setTimeout(resolve, 16));
 		const MAX_SELECTION_ATTEMPTS = 8;
@@ -7796,7 +8742,7 @@ function createSuperDocUI(options) {
 			await applyFormatPainter(caretSel);
 		}
 	};
-	const applyFormatPainter = async (selection$1) => {
+	const applyFormatPainter = async (selection) => {
 		const snap = painter.snapshot;
 		if (!snap) {
 			if (painter.mode === "armed") exitFormatPainter();
@@ -7804,21 +8750,21 @@ function createSuperDocUI(options) {
 		}
 		const doc = getDoc();
 		if (!doc) return;
-		const targetSelection = selectionSliceFromInfo(selection$1, "ready");
+		const targetSelection = selectionSliceFromInfo(selection, "ready");
 		const { lockModesById } = computeActiveContentControlLockModes(doc.contentControls, targetSelection);
 		if (contentControlLockReason(lockModesById)) {
 			recompute();
 			return;
 		}
-		const selTarget = selection$1["target"];
-		const selectionTarget = selection$1["selectionTarget"];
-		if (!(selection$1["empty"] === true) && Object.keys(snap.inline).length > 0) {
+		const selTarget = selection["target"];
+		const selectionTarget = selection["selectionTarget"];
+		if (!(selection["empty"] === true) && Object.keys(snap.inline).length > 0) {
 			const inlineOp = resolveDocOperation(doc, "format.apply");
 			if (inlineOp && selectionTarget) try {
 				if (!commandResultSucceeded(commandResultFromOperationResult(await Promise.resolve(callInlineFormatMutation("format.apply", inlineOp, {
 					target: selectionTarget,
 					inline: snap.inline
-				}, selection$1))))) {
+				}, selection))))) {
 					recompute();
 					return;
 				}
@@ -7854,11 +8800,11 @@ function createSuperDocUI(options) {
 				if (spacing) {
 					const sp = spacing;
 					const rawLr = sp["lineRule"] ?? "auto";
-					const lr = new Set([
+					const lr = (/* @__PURE__ */ new Set([
 						"auto",
 						"exact",
 						"atLeast"
-					]).has(rawLr) ? rawLr : "auto";
+					])).has(rawLr) ? rawLr : "auto";
 					const rawSpacing = {
 						...sp["before"] != null ? { before: Math.round(sp["before"] * 20) } : {},
 						...sp["after"] != null ? { after: Math.round(sp["after"] * 20) } : {},
@@ -7948,6 +8894,14 @@ function createSuperDocUI(options) {
 	};
 	const selectionSub = sliceHandle((s) => s.selection);
 	const selectionSnap = snapshotHandle(selectionSub);
+	/**
+	* Resolve the host-owned selection apply helper (`editing.selectionTargets`)
+	* with a truthful failure reason. `host.getHandles()` throws a
+	* `V2EditorHostError` with a lifecycle `reason` while the host is booting or
+	* disposed — that is a readiness condition, not a missing capability, so it
+	* maps to `not-ready` instead of being swallowed into
+	* `host-capability-unavailable`.
+	*/
 	const getSelectionApplyHelper = () => {
 		const host = getHost();
 		if (typeof host?.getHandles !== "function") return { reason: SUPERDOC_UI_REASONS.hostCapabilityUnavailable };
@@ -7966,8 +8920,8 @@ function createSuperDocUI(options) {
 		const host = getHost();
 		if (typeof host?.getHandles !== "function") return;
 		try {
-			const contentControls$1 = (host.getHandles()?.editing)?.contentControls;
-			if (typeof contentControls$1?.activate === "function") contentControls$1.activate({ id });
+			const contentControls = (host.getHandles()?.editing)?.contentControls;
+			if (typeof contentControls?.activate === "function") contentControls.activate({ id });
 		} catch {}
 	};
 	const selection = {
@@ -8095,7 +9049,17 @@ function createSuperDocUI(options) {
 		execute: executeCommand,
 		executeAsync: executeCommandAsync
 	};
-	const scrollTargetIntoView = async (target, options$1) => {
+	/**
+	* Scroll a resolved document target into view through the host navigation
+	* surface (`host.scrollTargetIntoView`). Shared by comments / tracked changes /
+	* content controls and the generic `viewport.scrollIntoView`. Alignment
+	* defaults to `block: 'center'` / `behavior: 'smooth'` (matching the generic
+	* method and v1) so every scroll path lands consistently; callers may
+	* override. Fails closed with a stable reason rather than a no-op recompute;
+	* a resolved target that cannot be made visible is `target-not-visible`, not
+	* `target-unresolved`.
+	*/
+	const scrollTargetIntoView = async (target, options) => {
 		if (!getEditor()) return {
 			success: false,
 			ok: false,
@@ -8116,10 +9080,10 @@ function createSuperDocUI(options) {
 		try {
 			const input = {
 				target,
-				block: options$1?.block ?? "center",
-				behavior: options$1?.behavior ?? "smooth"
+				block: options?.block ?? "center",
+				behavior: options?.behavior ?? "smooth"
 			};
-			const result = await Promise.resolve(options$1?.shouldContinue ? scroll.call(host, input, options$1.shouldContinue) : scroll.call(host, input));
+			const result = await Promise.resolve(options?.shouldContinue ? scroll.call(host, input, options.shouldContinue) : scroll.call(host, input));
 			if (result && typeof result === "object" && result.success === false) return {
 				success: false,
 				ok: false,
@@ -8137,6 +9101,11 @@ function createSuperDocUI(options) {
 			};
 		}
 	};
+	/**
+	* 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.
+	*/
 	const resolveEntityTarget = async (namespace, id, loaded, request) => {
 		const requestedStory = namespace === "trackChanges" ? request?.story : void 0;
 		const withRequestedStory = (target) => {
@@ -8189,6 +9158,18 @@ function createSuperDocUI(options) {
 			status
 		}), fallback), fallback);
 	}
+	/**
+	* The refusal every comment write shares, or `null` when the policy permits.
+	*
+	* `readOnly` is policy rather than presentation, so it cannot be left to the
+	* built-in dialog hiding its affordances: a custom comment UI calls
+	* `createFromCapture`, `createFromSelection`, `reply`, and `delete` directly,
+	* and the Document API underneath carries no policy of its own. Missing one
+	* route fails open on exactly the surface the policy exists for.
+	*
+	* `allowResolve` is deliberately not checked here — it forbids only the
+	* resolve/reopen transition, which `patchCommentStatus` owns.
+	*/
 	const commentWriteRefusal = () => reviewMutationsAreReadOnly() ? failedReceipt("Comments are read-only.", "DOCUMENT_READONLY") : null;
 	const filterCommentsSnapshot = (items, query) => {
 		const record = query && typeof query === "object" ? query : null;
@@ -8323,7 +9304,7 @@ function createSuperDocUI(options) {
 		}
 	};
 	const trackChangesSub = sliceHandle((s) => s.trackChanges);
-	const navigateTrackChange = (step, options$1) => {
+	const navigateTrackChange = (step, options) => {
 		const allRows = trackChangesSub.get().items.filter((item) => readEntityId(item) !== null);
 		if (allRows.length === 0) return null;
 		const currentId = state.trackChanges.activeId;
@@ -8338,7 +9319,7 @@ function createSuperDocUI(options) {
 		setExplicitActiveChange(story ? {
 			id: activeId,
 			story
-		} : { id: activeId }, options$1);
+		} : { id: activeId }, options);
 		recompute();
 		return activeId;
 	};
@@ -8559,11 +9540,12 @@ function createSuperDocUI(options) {
 			id: input,
 			story: void 0
 		} : input;
-		return executeTrackDecisionTarget(kind, {
+		const target = {
 			kind: "id",
 			id,
 			...story ? { story } : {}
-		}, id, story);
+		};
+		return executeTrackDecisionTarget(kind, target, id, story);
 	};
 	const executeTrackDecisionTarget = (kind, target, changeId, story) => {
 		try {
@@ -8813,9 +9795,9 @@ function createSuperDocUI(options) {
 		const hits = [];
 		for (const hit of rawHits) {
 			if (hit.type !== "trackedChange") {
-				const key$1 = `${hit.type}:${hit.id}`;
-				if (seen.has(key$1)) continue;
-				seen.add(key$1);
+				const key = `${hit.type}:${hit.id}`;
+				if (seen.has(key)) continue;
+				seen.add(key);
 				hits.push(hit);
 				continue;
 			}
@@ -8871,6 +9853,21 @@ function createSuperDocUI(options) {
 		}
 		entry.boundHost = null;
 	};
+	/**
+	* Move every live geometry subscription to the editor that is now active.
+	* Without this, scroll and repaint on the replacement editor never reach a
+	* listener that was registered against the previous one, so overlays stop
+	* tracking the document while still responding to selection and zoom.
+	*/
+	/**
+	* Release every geometry subscription once a hostless moment turns out to be
+	* permanent. Deferred rather than immediate because a null host is ambiguous
+	* at the instant it arrives: `registerV2Runtime` unregisters the outgoing
+	* runtime and installs the replacement in ONE synchronous block, so a refresh
+	* shows up here as a null followed by the new host with nothing in between.
+	* By the time a microtask runs, a refresh has already installed its host and a
+	* true clear (`removeDocument()`, a fail-closed projection) still has none.
+	*/
 	const releaseGeometryObserversIfStillHostless = () => {
 		geometryReleaseScheduled = false;
 		if (disposed || getHost()) return;
@@ -9007,6 +10004,7 @@ function createSuperDocUI(options) {
 		return target && typeof target === "object" ? target : null;
 	};
 	const metadataResolveKey = (id) => `metadata:resolve:${id}`;
+	/** Resolve a metadata id to its SelectionTarget, or null when unresolved. */
 	const resolveMetadataTarget = (id) => {
 		const metaApi = getDoc()?.metadata;
 		if (!metaApi || typeof metaApi.resolve !== "function") return null;
@@ -9090,16 +10088,16 @@ function createSuperDocUI(options) {
 	let searchState = { ...SEARCH_UNAVAILABLE_SLICE };
 	const searchListeners = /* @__PURE__ */ new Set();
 	const getHostSearch = () => {
-		const search$1 = getHost()?.search;
-		return search$1 && typeof search$1 === "object" ? search$1 : null;
+		const search = getHost()?.search;
+		return search && typeof search === "object" ? search : null;
 	};
 	const getEditCommandSearch = () => {
-		const search$1 = getEditCommands()?.search;
-		return search$1 && typeof search$1 === "object" ? search$1 : null;
+		const search = getEditCommands()?.search;
+		return search && typeof search === "object" ? search : null;
 	};
 	const searchIsAvailable = () => {
-		const search$1 = getHostSearch();
-		if (search$1 && typeof search$1.setSession === "function") return true;
+		const search = getHostSearch();
+		if (search && typeof search.setSession === "function") return true;
 		const editSearch = getEditCommandSearch();
 		return Boolean(editSearch) && typeof editSearch.query === "function" && typeof editSearch.getState === "function";
 	};
@@ -9117,7 +10115,21 @@ function createSuperDocUI(options) {
 		return searchState;
 	};
 	let searchRequestGeneration = 0;
+	/**
+	* How to tear down the session that is currently open, captured when it was
+	* opened.
+	*
+	* A closure rather than a reference to the facade, because the two search
+	* paths are released differently: a host session ends with `host.clear()`,
+	* while the worker-backed fallback ends by querying the empty string through
+	* `editCommands.search`. Both bind to the editor that owned them, and by the
+	* time an active-editor change reaches us `activeEditor` already points at the
+	* replacement, so neither is reachable by looking it up again. Capturing the
+	* teardown keeps the two paths from drifting apart: whichever one opens a
+	* session is the one that says how to close it.
+	*/
 	let releaseActiveSearchSession = null;
+	/** Release whatever session is open, then forget it. */
 	const releaseSearchSession = () => {
 		const release = releaseActiveSearchSession;
 		releaseActiveSearchSession = null;
@@ -9127,6 +10139,23 @@ function createSuperDocUI(options) {
 			return null;
 		}, null);
 	};
+	/**
+	* Drop everything the previous active editor owned.
+	*
+	* Three separate hazards. An in-flight async query still holds a generation
+	* that is current, so without bumping the token it would resolve and publish
+	* the old document's matches into the new one. The slice itself describes a
+	* document that is gone: leaving it in place reports a total and an active
+	* match for content nobody is looking at any more. And the previous host still
+	* holds the session it painted, so without clearing it the old document keeps
+	* its highlights and switching back shows a closed slice over a host that
+	* still has matches.
+	*
+	* This closes the session rather than re-running the query against the
+	* replacement document. Re-running is a plausible product choice and arguably
+	* the nicer one, but it is a feature decision, not the correctness fix, so it
+	* is deliberately not made here.
+	*/
 	const resetSearchForActiveEditorChange = () => {
 		searchRequestGeneration += 1;
 		releaseSearchSession();
@@ -9307,11 +10336,11 @@ function createSuperDocUI(options) {
 			if (!searchState.available) searchState.reason = SUPERDOC_UI_REASONS.searchUnavailable;
 			emitSearch();
 		},
-		search: (query, options$1) => {
+		search: (query, options) => {
 			const host = getHostSearch();
-			const caseSensitive = Boolean(options$1?.caseSensitive);
-			const includeDeletedText = options$1?.includeDeletedText === true;
-			const regex = options$1?.regex === true;
+			const caseSensitive = Boolean(options?.caseSensitive);
+			const includeDeletedText = options?.includeDeletedText === true;
+			const regex = options?.regex === true;
 			const generation = ++searchRequestGeneration;
 			if (!host || typeof host.setSession !== "function") {
 				const editSearch = getEditCommandSearch();
@@ -9371,12 +10400,13 @@ function createSuperDocUI(options) {
 			releaseActiveSearchSession = () => {
 				if (typeof host.clear === "function") host.clear();
 			};
-			applyHostSearchResult(safeCall(() => host.setSession(query, {
+			const result = safeCall(() => host.setSession(query, {
 				caseSensitive,
 				includeDeletedText,
 				...regex ? { regex: true } : {},
 				highlight: true
-			}), null));
+			}), null);
+			applyHostSearchResult(result);
 			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") {
@@ -9506,13 +10536,13 @@ function createSuperDocUI(options) {
 					ok: false,
 					reason: SUPERDOC_UI_REASONS.operationUnavailable
 				};
-				const result$1 = safeCall(() => editSearch.replace({ replacement: typeof replacement === "string" ? replacement : "" }), null);
-				if (isPromiseLike(result$1)) {
+				const result = safeCall(() => editSearch.replace({ replacement: typeof replacement === "string" ? replacement : "" }), null);
+				if (isPromiseLike(result)) {
 					const generation = searchRequestGeneration;
 					syncSearchStateFromHost();
 					emitSearch();
 					const isCurrent = () => generation === searchRequestGeneration;
-					return Promise.resolve(result$1).then((resolved) => {
+					return Promise.resolve(result).then((resolved) => {
 						if (isCurrent()) {
 							applyHostSearchResult(resolved, readEditCommandCanReplace());
 							syncSearchStateFromHost();
@@ -9532,7 +10562,7 @@ function createSuperDocUI(options) {
 				}
 				syncSearchStateFromHost();
 				emitSearch();
-				return mapHostReplaceResult(result$1);
+				return mapHostReplaceResult(result);
 			}
 			if (typeof host.replaceCurrent !== "function") return {
 				ok: false,
@@ -9555,13 +10585,13 @@ function createSuperDocUI(options) {
 					ok: false,
 					reason: SUPERDOC_UI_REASONS.operationUnavailable
 				};
-				const result$1 = safeCall(() => editSearch.replaceAll({ replacement: typeof replacement === "string" ? replacement : "" }), null);
-				if (isPromiseLike(result$1)) {
+				const result = safeCall(() => editSearch.replaceAll({ replacement: typeof replacement === "string" ? replacement : "" }), null);
+				if (isPromiseLike(result)) {
 					const generation = searchRequestGeneration;
 					syncSearchStateFromHost();
 					emitSearch();
 					const isCurrent = () => generation === searchRequestGeneration;
-					return Promise.resolve(result$1).then((resolved) => {
+					return Promise.resolve(result).then((resolved) => {
 						if (isCurrent()) {
 							applyHostSearchResult(resolved, readEditCommandCanReplace());
 							syncSearchStateFromHost();
@@ -9581,7 +10611,7 @@ function createSuperDocUI(options) {
 				}
 				syncSearchStateFromHost();
 				emitSearch();
-				return mapHostReplaceResult(result$1);
+				return mapHostReplaceResult(result);
 			}
 			if (typeof host.replaceAll !== "function") return {
 				ok: false,
@@ -9600,7 +10630,7 @@ function createSuperDocUI(options) {
 		getSnapshot: stylesSnap.getSnapshot,
 		subscribe: stylesSnap.subscribe,
 		observe: stylesSnap.observe,
-		getCatalog: (options$1) => readStyleCatalogLive(options$1).value,
+		getCatalog: (options) => readStyleCatalogLive(options).value,
 		getQuickGallery: () => stylesSub.get().quickGallery,
 		getActiveParagraphStyle: () => computeActiveParagraphStyle(state.selection, getStyleCatalog().cache).style
 	};
@@ -9747,6 +10777,12 @@ function createSuperDocUI(options) {
 	controllerRef = controller;
 	return controller;
 }
+/**
+* Default font-family offerings, used to backfill the picker when the active document resolves few
+* (or no) fonts and the runtime picker list is unavailable. Values are logical Word family names —
+* the formatting command writes them verbatim as logical `w:rFonts` intent; the runtime resolves
+* substitutes only at measure/paint time.
+*/
 var DEFAULT_FONT_FAMILY_OPTIONS = [
 	{
 		value: "Arial",
@@ -9779,6 +10815,11 @@ var DEFAULT_FONT_FAMILY_OPTIONS = [
 		previewFamily: "Verdana, sans-serif"
 	}
 ];
+/**
+* The Word-facing logical family: first family of a CSS stack, quotes stripped.
+* Document / command values sometimes carry `"Cambria, serif"`; the picker must
+* advertise `Cambria` so it dedupes against picker/default rows.
+*/
 function canonicalFontFamilyName(family) {
 	const trimmed = family.trim();
 	const quote = trimmed[0];
@@ -9789,6 +10830,10 @@ function canonicalFontFamilyName(family) {
 	const comma = trimmed.indexOf(",");
 	return (comma === -1 ? trimmed : trimmed.slice(0, comma)).trim().replace(/^["']|["']$/g, "");
 }
+/**
+* Normalize document-only rows (`DocumentFontOption` with `logicalFamily`) into the custom-UI
+* picker shape. Raw document families may be CSS stacks, so canonicalize to the first family.
+*/
 function normalizeDocumentFontOptions(raw) {
 	if (!Array.isArray(raw)) return [];
 	const out = [];
@@ -9806,6 +10851,11 @@ function normalizeDocumentFontOptions(raw) {
 	}
 	return out;
 }
+/**
+* Normalize picker rows (`FontFamilyOption`) without treating their value as a CSS stack. The font
+* runtime has already converted quoted document stacks such as `"Acme, Inc Sans", serif` into the
+* exact apply value (`Acme, Inc Sans`), so preserving `value` avoids truncating internal commas.
+*/
 function normalizePickerFontOptions(raw) {
 	if (!Array.isArray(raw)) return [];
 	const out = [];
@@ -9824,6 +10874,11 @@ function normalizePickerFontOptions(raw) {
 	}
 	return out;
 }
+/**
+* Compose document font options on top of the picker/default rows: document rows lead and win on
+* value collisions (case-insensitive), defaults backfill the rest. Order within each group is
+* preserved so document-used families stay at the front of the custom-UI picker (SD-3887).
+*/
 function composeFontFamilyOptions(documentOptions, pickerOptions = []) {
 	const out = [];
 	const seen = /* @__PURE__ */ new Set();
@@ -9880,9 +10935,11 @@ var DEFAULT_FONT_SIZE_OPTIONS = [
 		label: "36"
 	}
 ];
+/** Active state for a routed command: true when its mark is live at the selection. */
 function commandIsActive(descriptor, selection) {
 	return descriptor.activeMark ? selection.activeMarks.includes(descriptor.activeMark) : false;
 }
+//#endregion
 Object.defineProperty(exports, "BUILT_IN_COMMAND_IDS", {
 	enumerable: true,
 	get: function() {
@@ -9895,12 +10952,6 @@ Object.defineProperty(exports, "DOM_CLASS_NAMES", {
 		return DOM_CLASS_NAMES;
 	}
 });
-Object.defineProperty(exports, "composeAuthorColorResolver", {
-	enumerable: true,
-	get: function() {
-		return composeAuthorColorResolver;
-	}
-});
 Object.defineProperty(exports, "createSuperDocUI", {
 	enumerable: true,
 	get: function() {