superdoc 2.6.1-next.3 → 2.7.0-next.2

package/dist/chunks/{create-super-doc-ui-DCjm-_Xo.es.js → create-super-doc-ui-BTNVc3UD.es.js}

@@ -438,9 +438,8 @@ Object.freeze([
 * 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 apply removals/remaps locally; the
-* next committed window supplies surviving or restored rows. History follows
-* the same bounded path and never enumerates invisible review identities.
+* kernel and derived review UI. Direct receipts carry entity refs; mutation
+* plans carry the same identities through `trackedChanges` and per-step ids.
 */
 function getV2TrackedChangeMutationImpact(event) {
 	if (event?.type !== "mutation:committed") return null;
@@ -461,6 +460,11 @@ function getV2TrackedChangeMutationImpact(event) {
 	if (Array.isArray(payload.inserted)) payload.inserted.forEach((entry) => collectEntity(entry, upsertIds));
 	if (Array.isArray(payload.updated)) payload.updated.forEach((entry) => collectEntity(entry, upsertIds));
 	if (Array.isArray(payload.trackedChangeRefs)) payload.trackedChangeRefs.forEach((entry) => collectEntity(entry, upsertIds));
+	if (Array.isArray(payload.trackedChanges)) payload.trackedChanges.forEach((entry) => collectEntity(entry, upsertIds));
+	if (Array.isArray(payload.steps)) for (const step of payload.steps) {
+		if (!Array.isArray(step?.trackedChangeIds)) continue;
+		for (const id of step.trackedChangeIds) if (typeof id === "string" && id.length > 0) upsertIds.add(id);
+	}
 	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) {

package/dist/chunks/{create-super-doc-ui-CwCvqMOa.cjs → create-super-doc-ui-C44xPZxz.cjs}

@@ -438,9 +438,8 @@ Object.freeze([
 * 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 apply removals/remaps locally; the
-* next committed window supplies surviving or restored rows. History follows
-* the same bounded path and never enumerates invisible review identities.
+* kernel and derived review UI. Direct receipts carry entity refs; mutation
+* plans carry the same identities through `trackedChanges` and per-step ids.
 */
 function getV2TrackedChangeMutationImpact(event) {
 	if (event?.type !== "mutation:committed") return null;
@@ -461,6 +460,11 @@ function getV2TrackedChangeMutationImpact(event) {
 	if (Array.isArray(payload.inserted)) payload.inserted.forEach((entry) => collectEntity(entry, upsertIds));
 	if (Array.isArray(payload.updated)) payload.updated.forEach((entry) => collectEntity(entry, upsertIds));
 	if (Array.isArray(payload.trackedChangeRefs)) payload.trackedChangeRefs.forEach((entry) => collectEntity(entry, upsertIds));
+	if (Array.isArray(payload.trackedChanges)) payload.trackedChanges.forEach((entry) => collectEntity(entry, upsertIds));
+	if (Array.isArray(payload.steps)) for (const step of payload.steps) {
+		if (!Array.isArray(step?.trackedChangeIds)) continue;
+		for (const id of step.trackedChangeIds) if (typeof id === "string" && id.length > 0) upsertIds.add(id);
+	}
 	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) {

package/dist/collaboration-upgrade-engine.cjs

@@ -19,7 +19,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = (0, _superdoc_docx_engine_collaboration_upgrade_engine.getCollaborationUpgradeEngineInfo)();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.6.1-next.3",
+	superdocVersion: "2.7.0-next.2",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

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

@@ -18,7 +18,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = getCollaborationUpgradeEngineInfo$1();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.6.1-next.3",
+	superdocVersion: "2.7.0-next.2",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/document-api/src/contract/command-catalog.d.ts

@@ -1,7 +1,7 @@
 import { CommandCatalog, CommandStaticMetadata, OperationId } from './types.js';
 export declare const COMMAND_CATALOG: CommandCatalog;
 /** Operation IDs whose catalog entry has `mutates: true`. */
-export declare const MUTATING_OPERATION_IDS: ("replace" | "find" | "delete" | "get" | "insert" | "info" | "format.apply" | "blocks.split" | "blocks.merge" | "blocks.move" | "lists.getState" | "lists.apply" | "lists.continue" | "lists.restart" | "lists.remove" | "format.paragraph.setMarkRunProps" | "tables.moveRow" | "format.bold" | "format.strike" | "format.color" | "format.italic" | "format.rtl" | "format.cs" | "format.shading" | "format.fontFamily" | "format.lang" | "format.fontSize" | "format.fontSizeCs" | "format.highlight" | "format.underline" | "format.caps" | "format.smallCaps" | "format.outline" | "format.shadow" | "format.emboss" | "format.imprint" | "format.vanish" | "format.webHidden" | "format.specVanish" | "format.border" | "format.fitText" | "format.dstrike" | "format.vertAlign" | "format.position" | "format.bCs" | "format.iCs" | "format.snapToGrid" | "format.oMath" | "format.letterSpacing" | "format.charScale" | "format.kerning" | "format.rStyle" | "format.rFonts" | "format.eastAsianLayout" | "format.em" | "format.ligatures" | "format.numForm" | "format.numSpacing" | "format.stylisticSets" | "format.contextualAlternates" | "getNode" | "getNodeById" | "getText" | "getMarkdown" | "getHtml" | "markdownToFragment" | "extract" | "clearContent" | "formatRange" | "blocks.list" | "blocks.delete" | "blocks.deleteRange" | "styles.apply" | "styles.getCatalog" | "templates.apply" | "create.paragraph" | "create.heading" | "create.sectionBreak" | "sections.list" | "sections.get" | "sections.setBreakType" | "sections.setPageMargins" | "sections.setHeaderFooterMargins" | "sections.setPageSetup" | "sections.setColumns" | "sections.setLineNumbering" | "sections.setPageNumbering" | "sections.setTitlePage" | "sections.setOddEvenHeadersFooters" | "sections.setVerticalAlign" | "sections.setSectionDirection" | "sections.setHeaderFooterRef" | "sections.clearHeaderFooterRef" | "sections.setLinkToPrevious" | "sections.setPageBorders" | "sections.clearPageBorders" | "styles.paragraph.setStyle" | "styles.paragraph.setStyleRef" | "styles.paragraph.clearStyle" | "format.paragraph.resetDirectFormatting" | "format.paragraph.setAlignment" | "format.paragraph.clearAlignment" | "format.paragraph.setIndentation" | "format.paragraph.clearIndentation" | "format.paragraph.setSpacing" | "format.paragraph.clearSpacing" | "format.paragraph.setKeepOptions" | "format.paragraph.setOutlineLevel" | "format.paragraph.setFlowOptions" | "format.paragraph.setTabStop" | "format.paragraph.clearTabStop" | "format.paragraph.clearAllTabStops" | "format.paragraph.setBorder" | "format.paragraph.clearBorder" | "format.paragraph.setShading" | "format.paragraph.clearShading" | "format.paragraph.setDirection" | "format.paragraph.clearDirection" | "format.paragraph.setNumbering" | "lists.list" | "lists.get" | "lists.insert" | "lists.create" | "lists.attach" | "lists.detach" | "lists.delete" | "lists.indent" | "lists.outdent" | "lists.join" | "lists.canJoin" | "lists.separate" | "lists.merge" | "lists.split" | "lists.setLevel" | "lists.setValue" | "lists.continuePrevious" | "lists.canContinuePrevious" | "lists.setLevelRestart" | "lists.convertToText" | "lists.applyTemplate" | "lists.applyPreset" | "lists.setType" | "lists.captureTemplate" | "lists.setLevelNumbering" | "lists.setLevelBullet" | "lists.setLevelPictureBullet" | "lists.setLevelAlignment" | "lists.setLevelIndents" | "lists.setLevelTrailingCharacter" | "lists.setLevelMarkerFont" | "lists.clearLevelOverrides" | "lists.getStyle" | "lists.applyStyle" | "lists.restartAt" | "lists.setLevelNumberStyle" | "lists.setLevelText" | "lists.setLevelStart" | "lists.setLevelLayout" | "comments.create" | "comments.patch" | "comments.delete" | "comments.get" | "comments.list" | "trackChanges.list" | "trackChanges.get" | "trackChanges.decide" | "query.match" | "ranges.resolve" | "selection.current" | "mutations.preview" | "mutations.apply" | "plan.execute" | "capabilities.get" | "create.table" | "tables.convertFromText" | "tables.delete" | "tables.clearContents" | "tables.move" | "tables.split" | "tables.convertToText" | "tables.setLayout" | "tables.insertRow" | "tables.deleteRow" | "tables.setRowHeight" | "tables.distributeRows" | "tables.setRowOptions" | "tables.insertColumn" | "tables.deleteColumn" | "tables.setColumnWidth" | "tables.distributeColumns" | "tables.insertCell" | "tables.deleteCell" | "tables.mergeCells" | "tables.unmergeCells" | "tables.splitCell" | "tables.setCellProperties" | "tables.setCellText" | "tables.sort" | "tables.setAltText" | "tables.setStyle" | "tables.clearStyle" | "tables.setStyleOption" | "tables.setBorder" | "tables.clearBorder" | "tables.applyBorderPreset" | "tables.setShading" | "tables.clearShading" | "tables.setTablePadding" | "tables.setCellPadding" | "tables.setCellSpacing" | "tables.clearCellSpacing" | "tables.applyStyle" | "tables.setBorders" | "tables.setTableOptions" | "tables.applyPreset" | "tables.get" | "tables.getCells" | "tables.getProperties" | "tables.getStyles" | "tables.setDefaultStyle" | "tables.clearDefaultStyle" | "create.tableOfContents" | "toc.list" | "toc.get" | "toc.configure" | "toc.update" | "toc.remove" | "toc.markEntry" | "toc.unmarkEntry" | "toc.listEntries" | "toc.getEntry" | "toc.editEntry" | "history.get" | "history.undo" | "history.redo" | "create.image" | "images.list" | "images.get" | "images.delete" | "images.move" | "images.convertToInline" | "images.convertToFloating" | "images.setSize" | "images.setWrapType" | "images.setWrapSide" | "images.setWrapDistances" | "images.setPosition" | "images.setAnchorOptions" | "images.setZOrder" | "images.scale" | "images.setLockAspectRatio" | "images.rotate" | "images.flip" | "images.crop" | "images.resetCrop" | "images.replaceSource" | "images.setAltText" | "images.setDecorative" | "images.setName" | "images.setHyperlink" | "images.insertCaption" | "images.updateCaption" | "images.removeCaption" | "hyperlinks.list" | "hyperlinks.get" | "hyperlinks.wrap" | "hyperlinks.insert" | "hyperlinks.patch" | "hyperlinks.remove" | "headerFooters.list" | "headerFooters.get" | "headerFooters.resolve" | "headerFooters.refs.set" | "headerFooters.refs.clear" | "headerFooters.refs.setLinkedToPrevious" | "headerFooters.parts.list" | "headerFooters.parts.create" | "headerFooters.parts.delete" | "create.contentControl" | "contentControls.list" | "contentControls.get" | "contentControls.listInRange" | "contentControls.selectByTag" | "contentControls.selectByTitle" | "contentControls.listChildren" | "contentControls.getParent" | "contentControls.wrap" | "contentControls.unwrap" | "contentControls.delete" | "contentControls.copy" | "contentControls.move" | "contentControls.patch" | "contentControls.setLockMode" | "contentControls.setType" | "contentControls.getContent" | "contentControls.replaceContent" | "contentControls.clearContent" | "contentControls.appendContent" | "contentControls.prependContent" | "contentControls.insertBefore" | "contentControls.insertAfter" | "contentControls.getBinding" | "contentControls.setBinding" | "contentControls.clearBinding" | "contentControls.getRawProperties" | "contentControls.patchRawProperties" | "contentControls.validateWordCompatibility" | "contentControls.normalizeWordCompatibility" | "contentControls.normalizeTagPayload" | "contentControls.text.setMultiline" | "contentControls.text.setValue" | "contentControls.text.clearValue" | "contentControls.date.setValue" | "contentControls.date.clearValue" | "contentControls.date.setDisplayFormat" | "contentControls.date.setDisplayLocale" | "contentControls.date.setStorageFormat" | "contentControls.date.setCalendar" | "contentControls.checkbox.getState" | "contentControls.checkbox.setState" | "contentControls.checkbox.toggle" | "contentControls.checkbox.setSymbolPair" | "contentControls.choiceList.getItems" | "contentControls.choiceList.setItems" | "contentControls.choiceList.setSelected" | "contentControls.repeatingSection.listItems" | "contentControls.repeatingSection.insertItemBefore" | "contentControls.repeatingSection.insertItemAfter" | "contentControls.repeatingSection.cloneItem" | "contentControls.repeatingSection.deleteItem" | "contentControls.repeatingSection.setAllowInsertDelete" | "contentControls.group.wrap" | "contentControls.group.ungroup" | "bookmarks.list" | "bookmarks.get" | "bookmarks.insert" | "bookmarks.rename" | "bookmarks.remove" | "footnotes.list" | "footnotes.get" | "footnotes.insert" | "footnotes.update" | "footnotes.remove" | "footnotes.configure" | "clipboard.parse" | "clipboard.insert" | "clipboard.serializeSelection" | "crossRefs.list" | "crossRefs.get" | "crossRefs.insert" | "crossRefs.rebuild" | "crossRefs.remove" | "index.list" | "index.get" | "index.insert" | "index.configure" | "index.rebuild" | "index.remove" | "index.entries.list" | "index.entries.get" | "index.entries.insert" | "index.entries.update" | "index.entries.remove" | "captions.list" | "captions.get" | "captions.insert" | "captions.update" | "captions.remove" | "captions.configure" | "fields.list" | "fields.get" | "fields.insert" | "fields.rebuild" | "fields.remove" | "citations.list" | "citations.get" | "citations.insert" | "citations.update" | "citations.remove" | "citations.sources.list" | "citations.sources.get" | "citations.sources.insert" | "citations.sources.update" | "citations.sources.remove" | "citations.bibliography.get" | "citations.bibliography.insert" | "citations.bibliography.rebuild" | "citations.bibliography.configure" | "citations.bibliography.remove" | "authorities.list" | "authorities.get" | "authorities.insert" | "authorities.configure" | "authorities.rebuild" | "authorities.remove" | "authorities.entries.list" | "authorities.entries.get" | "authorities.entries.insert" | "authorities.entries.update" | "authorities.entries.remove" | "diff.capture" | "diff.compare" | "diff.apply" | "export.toDocx" | "protection.get" | "protection.setEditingRestriction" | "protection.clearEditingRestriction" | "permissionRanges.list" | "permissionRanges.get" | "permissionRanges.create" | "permissionRanges.remove" | "permissionRanges.updatePrincipal" | "customXml.parts.list" | "customXml.parts.get" | "customXml.parts.create" | "customXml.parts.patch" | "customXml.parts.remove" | "metadata.attach" | "metadata.list" | "metadata.get" | "metadata.update" | "metadata.remove" | "metadata.resolve")[];
+export declare const MUTATING_OPERATION_IDS: ("replace" | "find" | "delete" | "get" | "insert" | "info" | "format.apply" | "blocks.split" | "blocks.merge" | "blocks.move" | "lists.getState" | "lists.apply" | "lists.continue" | "lists.restart" | "lists.remove" | "format.paragraph.setMarkRunProps" | "tables.moveRow" | "format.bold" | "format.strike" | "format.color" | "format.italic" | "format.rtl" | "format.cs" | "format.shading" | "format.fontFamily" | "format.lang" | "format.fontSize" | "format.fontSizeCs" | "format.highlight" | "format.underline" | "format.caps" | "format.smallCaps" | "format.outline" | "format.shadow" | "format.emboss" | "format.imprint" | "format.vanish" | "format.webHidden" | "format.specVanish" | "format.border" | "format.fitText" | "format.dstrike" | "format.vertAlign" | "format.position" | "format.bCs" | "format.iCs" | "format.snapToGrid" | "format.oMath" | "format.letterSpacing" | "format.charScale" | "format.kerning" | "format.rStyle" | "format.rFonts" | "format.eastAsianLayout" | "format.em" | "format.ligatures" | "format.numForm" | "format.numSpacing" | "format.stylisticSets" | "format.contextualAlternates" | "getNode" | "getNodeById" | "getText" | "getMarkdown" | "getHtml" | "markdownToFragment" | "htmlToFragment" | "extract" | "clearContent" | "formatRange" | "blocks.list" | "blocks.delete" | "blocks.deleteRange" | "styles.apply" | "styles.getCatalog" | "templates.apply" | "create.paragraph" | "create.heading" | "create.sectionBreak" | "sections.list" | "sections.get" | "sections.setBreakType" | "sections.setPageMargins" | "sections.setHeaderFooterMargins" | "sections.setPageSetup" | "sections.setColumns" | "sections.setLineNumbering" | "sections.setPageNumbering" | "sections.setTitlePage" | "sections.setOddEvenHeadersFooters" | "sections.setVerticalAlign" | "sections.setSectionDirection" | "sections.setHeaderFooterRef" | "sections.clearHeaderFooterRef" | "sections.setLinkToPrevious" | "sections.setPageBorders" | "sections.clearPageBorders" | "styles.paragraph.setStyle" | "styles.paragraph.setStyleRef" | "styles.paragraph.clearStyle" | "format.paragraph.resetDirectFormatting" | "format.paragraph.setAlignment" | "format.paragraph.clearAlignment" | "format.paragraph.setIndentation" | "format.paragraph.clearIndentation" | "format.paragraph.setSpacing" | "format.paragraph.clearSpacing" | "format.paragraph.setKeepOptions" | "format.paragraph.setOutlineLevel" | "format.paragraph.setFlowOptions" | "format.paragraph.setTabStop" | "format.paragraph.clearTabStop" | "format.paragraph.clearAllTabStops" | "format.paragraph.setBorder" | "format.paragraph.clearBorder" | "format.paragraph.setShading" | "format.paragraph.clearShading" | "format.paragraph.setDirection" | "format.paragraph.clearDirection" | "format.paragraph.setNumbering" | "lists.list" | "lists.get" | "lists.insert" | "lists.create" | "lists.attach" | "lists.detach" | "lists.delete" | "lists.indent" | "lists.outdent" | "lists.join" | "lists.canJoin" | "lists.separate" | "lists.merge" | "lists.split" | "lists.setLevel" | "lists.setValue" | "lists.continuePrevious" | "lists.canContinuePrevious" | "lists.setLevelRestart" | "lists.convertToText" | "lists.applyTemplate" | "lists.applyPreset" | "lists.setType" | "lists.captureTemplate" | "lists.setLevelNumbering" | "lists.setLevelBullet" | "lists.setLevelPictureBullet" | "lists.setLevelAlignment" | "lists.setLevelIndents" | "lists.setLevelTrailingCharacter" | "lists.setLevelMarkerFont" | "lists.clearLevelOverrides" | "lists.getStyle" | "lists.applyStyle" | "lists.restartAt" | "lists.setLevelNumberStyle" | "lists.setLevelText" | "lists.setLevelStart" | "lists.setLevelLayout" | "comments.create" | "comments.patch" | "comments.delete" | "comments.get" | "comments.list" | "trackChanges.list" | "trackChanges.get" | "trackChanges.decide" | "query.match" | "ranges.resolve" | "selection.current" | "mutations.preview" | "mutations.apply" | "plan.execute" | "capabilities.get" | "create.table" | "tables.convertFromText" | "tables.delete" | "tables.clearContents" | "tables.move" | "tables.split" | "tables.convertToText" | "tables.setLayout" | "tables.insertRow" | "tables.deleteRow" | "tables.setRowHeight" | "tables.distributeRows" | "tables.setRowOptions" | "tables.insertColumn" | "tables.deleteColumn" | "tables.setColumnWidth" | "tables.distributeColumns" | "tables.insertCell" | "tables.deleteCell" | "tables.mergeCells" | "tables.unmergeCells" | "tables.splitCell" | "tables.setCellProperties" | "tables.setCellText" | "tables.sort" | "tables.setAltText" | "tables.setStyle" | "tables.clearStyle" | "tables.setStyleOption" | "tables.setBorder" | "tables.clearBorder" | "tables.applyBorderPreset" | "tables.setShading" | "tables.clearShading" | "tables.setTablePadding" | "tables.setCellPadding" | "tables.setCellSpacing" | "tables.clearCellSpacing" | "tables.applyStyle" | "tables.setBorders" | "tables.setTableOptions" | "tables.applyPreset" | "tables.get" | "tables.getCells" | "tables.getProperties" | "tables.getStyles" | "tables.setDefaultStyle" | "tables.clearDefaultStyle" | "create.tableOfContents" | "toc.list" | "toc.get" | "toc.configure" | "toc.update" | "toc.remove" | "toc.markEntry" | "toc.unmarkEntry" | "toc.listEntries" | "toc.getEntry" | "toc.editEntry" | "history.get" | "history.undo" | "history.redo" | "create.image" | "images.list" | "images.get" | "images.delete" | "images.move" | "images.convertToInline" | "images.convertToFloating" | "images.setSize" | "images.setWrapType" | "images.setWrapSide" | "images.setWrapDistances" | "images.setPosition" | "images.setAnchorOptions" | "images.setZOrder" | "images.scale" | "images.setLockAspectRatio" | "images.rotate" | "images.flip" | "images.crop" | "images.resetCrop" | "images.replaceSource" | "images.setAltText" | "images.setDecorative" | "images.setName" | "images.setHyperlink" | "images.insertCaption" | "images.updateCaption" | "images.removeCaption" | "hyperlinks.list" | "hyperlinks.get" | "hyperlinks.wrap" | "hyperlinks.insert" | "hyperlinks.patch" | "hyperlinks.remove" | "headerFooters.list" | "headerFooters.get" | "headerFooters.resolve" | "headerFooters.refs.set" | "headerFooters.refs.clear" | "headerFooters.refs.setLinkedToPrevious" | "headerFooters.parts.list" | "headerFooters.parts.create" | "headerFooters.parts.delete" | "create.contentControl" | "contentControls.list" | "contentControls.get" | "contentControls.listInRange" | "contentControls.selectByTag" | "contentControls.selectByTitle" | "contentControls.listChildren" | "contentControls.getParent" | "contentControls.wrap" | "contentControls.unwrap" | "contentControls.delete" | "contentControls.copy" | "contentControls.move" | "contentControls.patch" | "contentControls.setLockMode" | "contentControls.setType" | "contentControls.getContent" | "contentControls.replaceContent" | "contentControls.clearContent" | "contentControls.appendContent" | "contentControls.prependContent" | "contentControls.insertBefore" | "contentControls.insertAfter" | "contentControls.getBinding" | "contentControls.setBinding" | "contentControls.clearBinding" | "contentControls.getRawProperties" | "contentControls.patchRawProperties" | "contentControls.validateWordCompatibility" | "contentControls.normalizeWordCompatibility" | "contentControls.normalizeTagPayload" | "contentControls.text.setMultiline" | "contentControls.text.setValue" | "contentControls.text.clearValue" | "contentControls.date.setValue" | "contentControls.date.clearValue" | "contentControls.date.setDisplayFormat" | "contentControls.date.setDisplayLocale" | "contentControls.date.setStorageFormat" | "contentControls.date.setCalendar" | "contentControls.checkbox.getState" | "contentControls.checkbox.setState" | "contentControls.checkbox.toggle" | "contentControls.checkbox.setSymbolPair" | "contentControls.choiceList.getItems" | "contentControls.choiceList.setItems" | "contentControls.choiceList.setSelected" | "contentControls.repeatingSection.listItems" | "contentControls.repeatingSection.insertItemBefore" | "contentControls.repeatingSection.insertItemAfter" | "contentControls.repeatingSection.cloneItem" | "contentControls.repeatingSection.deleteItem" | "contentControls.repeatingSection.setAllowInsertDelete" | "contentControls.group.wrap" | "contentControls.group.ungroup" | "bookmarks.list" | "bookmarks.get" | "bookmarks.insert" | "bookmarks.rename" | "bookmarks.remove" | "footnotes.list" | "footnotes.get" | "footnotes.insert" | "footnotes.update" | "footnotes.remove" | "footnotes.configure" | "clipboard.parse" | "clipboard.insert" | "clipboard.serializeSelection" | "crossRefs.list" | "crossRefs.get" | "crossRefs.insert" | "crossRefs.rebuild" | "crossRefs.remove" | "index.list" | "index.get" | "index.insert" | "index.configure" | "index.rebuild" | "index.remove" | "index.entries.list" | "index.entries.get" | "index.entries.insert" | "index.entries.update" | "index.entries.remove" | "captions.list" | "captions.get" | "captions.insert" | "captions.update" | "captions.remove" | "captions.configure" | "fields.list" | "fields.get" | "fields.insert" | "fields.rebuild" | "fields.remove" | "citations.list" | "citations.get" | "citations.insert" | "citations.update" | "citations.remove" | "citations.sources.list" | "citations.sources.get" | "citations.sources.insert" | "citations.sources.update" | "citations.sources.remove" | "citations.bibliography.get" | "citations.bibliography.insert" | "citations.bibliography.rebuild" | "citations.bibliography.configure" | "citations.bibliography.remove" | "authorities.list" | "authorities.get" | "authorities.insert" | "authorities.configure" | "authorities.rebuild" | "authorities.remove" | "authorities.entries.list" | "authorities.entries.get" | "authorities.entries.insert" | "authorities.entries.update" | "authorities.entries.remove" | "diff.capture" | "diff.compare" | "diff.apply" | "export.toDocx" | "protection.get" | "protection.setEditingRestriction" | "protection.clearEditingRestriction" | "permissionRanges.list" | "permissionRanges.get" | "permissionRanges.create" | "permissionRanges.remove" | "permissionRanges.updatePrincipal" | "customXml.parts.list" | "customXml.parts.get" | "customXml.parts.create" | "customXml.parts.patch" | "customXml.parts.remove" | "metadata.attach" | "metadata.list" | "metadata.get" | "metadata.update" | "metadata.remove" | "metadata.resolve")[];
 /** Maps each operation to its human-readable description. */
 export declare const OPERATION_DESCRIPTION_MAP: Record<OperationId, string>;
 /** Maps each operation to whether it requires an open document to execute. */

package/dist/document-api/src/contract/operation-definitions.d.ts

@@ -3490,6 +3490,15 @@ export declare const OPERATION_DEFINITIONS: {
         readonly referenceDocPath: "markdown-to-fragment.mdx";
         readonly referenceGroup: "core";
     };
+    readonly htmlToFragment: {
+        readonly memberPath: "htmlToFragment";
+        readonly description: "Convert an HTML string into an SDM/1 structural fragment.";
+        readonly expectedResult: "Returns an SDHtmlToFragmentResult with the converted fragment, lossy flag, and diagnostics.";
+        readonly requiresDocumentContext: true;
+        readonly metadata: CommandStaticMetadata;
+        readonly referenceDocPath: "html-to-fragment.mdx";
+        readonly referenceGroup: "core";
+    };
     readonly info: {
         readonly memberPath: "info";
         readonly description: "Return document summary info including word, character, paragraph, heading, table, image, comment, tracked-change, SDT-field, list, and page counts, plus outline and capabilities.";

package/dist/document-api/src/contract/operation-registry.d.ts

@@ -2,7 +2,7 @@ import { OperationId } from './types.js';
 import { NodeAddress } from '../types/index.js';
 import { SDNodeResult, SDFindInput, SDFindResult, SDGetInput } from '../types/sd-envelope.js';
 import { TextMutationReceipt, Receipt } from '../types/receipt.js';
-import { SDMutationReceipt, SDMarkdownToFragmentResult } from '../types/sd-contract.js';
+import { SDHtmlToFragmentResult, SDMutationReceipt, SDMarkdownToFragmentResult } from '../types/sd-contract.js';
 import { DocumentInfo } from '../types/info.types.js';
 import { SDDocument } from '../types/fragment.js';
 import { CreateParagraphInput, CreateParagraphResult, CreateHeadingInput, CreateHeadingResult } from '../types/create.types.js';
@@ -12,6 +12,7 @@ import { GetTextInput } from '../get-text/get-text.js';
 import { GetMarkdownInput } from '../get-markdown/get-markdown.js';
 import { GetHtmlInput } from '../get-html/get-html.js';
 import { MarkdownToFragmentInput } from '../markdown-to-fragment/markdown-to-fragment.js';
+import { HtmlToFragmentInput } from '../html-to-fragment/html-to-fragment.js';
 import { InfoInput } from '../info/info.js';
 import { ExtractInput } from '../extract/extract.js';
 import { ExtractResult } from '../types/extract.types.js';
@@ -107,6 +108,11 @@ export interface OperationRegistry extends FormatInlineAliasOperationRegistry {
         options: never;
         output: SDMarkdownToFragmentResult;
     };
+    htmlToFragment: {
+        input: HtmlToFragmentInput;
+        options: never;
+        output: SDHtmlToFragmentResult;
+    };
     info: {
         input: InfoInput;
         options: never;

package/dist/document-api/src/contract/sd-fragment-schema.d.ts

@@ -0,0 +1,4 @@
+type JsonSchema = Record<string, unknown>;
+export declare const SD_CONVERSION_FRAGMENT_SCHEMA_DEFS: Record<string, JsonSchema>;
+export declare const SD_CONVERSION_FRAGMENT_SCHEMA: JsonSchema;
+export {};

package/dist/document-api/src/html-to-fragment/html-to-fragment.d.ts

@@ -0,0 +1,8 @@
+import { SDHtmlToFragmentResult } from '../types/sd-contract.js';
+export interface HtmlToFragmentInput {
+    html: string;
+}
+export interface HtmlToFragmentAdapter {
+    htmlToFragment(input: HtmlToFragmentInput): SDHtmlToFragmentResult;
+}
+export declare function executeHtmlToFragment(adapter: HtmlToFragmentAdapter | undefined, input: HtmlToFragmentInput): SDHtmlToFragmentResult;

package/dist/document-api/src/index.d.ts

@@ -13,7 +13,8 @@ import { GetTextAdapter, GetTextInput } from './get-text/get-text.js';
 import { GetMarkdownAdapter, GetMarkdownInput } from './get-markdown/get-markdown.js';
 import { GetHtmlAdapter, GetHtmlInput } from './get-html/get-html.js';
 import { MarkdownToFragmentAdapter, MarkdownToFragmentInput } from './markdown-to-fragment/markdown-to-fragment.js';
-import { SDMarkdownToFragmentResult } from './types/sd-contract.js';
+import { HtmlToFragmentAdapter, HtmlToFragmentInput } from './html-to-fragment/html-to-fragment.js';
+import { SDHtmlToFragmentResult, SDMarkdownToFragmentResult } from './types/sd-contract.js';
 import { InfoAdapter, InfoInput } from './info/info.js';
 import { ExtractAdapter, ExtractInput } from './extract/extract.js';
 import { ClearContentAdapter, ClearContentInput } from './clear-content/clear-content.js';
@@ -76,6 +77,8 @@ export * from './header-footers/header-footers.types.js';
 export type { ClearContentAdapter, ClearContentInput } from './clear-content/clear-content.js';
 export type { MarkdownToFragmentInput, MarkdownToFragmentAdapter, } from './markdown-to-fragment/markdown-to-fragment.js';
 export { executeMarkdownToFragment } from './markdown-to-fragment/markdown-to-fragment.js';
+export type { HtmlToFragmentInput, HtmlToFragmentAdapter } from './html-to-fragment/html-to-fragment.js';
+export { executeHtmlToFragment } from './html-to-fragment/html-to-fragment.js';
 export type { HistoryState, HistoryActionResult, HistoryNoopReason, SDHistoryStatus, SDHistoryCollaborationMeta, } from './history/history.types.js';
 export { executeTrackChangesGet, executeTrackChangesList, executeTrackChangesDecide, } from './track-changes/track-changes.js';
 export { createPlanApi, type PlanApi, type PlanExecuteInput, type PlanExecuteEntry, type PlanExecuteEntryExpect, type PlanExecuteResult, type PlanEntryReceipt, type PlanEntryReceiptStatus, type PlanExecuteFailure, type PlanCaptureRefMarker, type PlanProjectTextOffsetMarker, } from './plan/plan.js';
@@ -152,12 +155,12 @@ export { executeBlocksList, executeBlocksDelete, executeBlocksDeleteRange, execu
 export { executeListsIndent, executeListsOutdent, executeListsGetState, executeListsApply, executeListsContinueV2, executeListsRestartV2, executeListsRemoveV2, } from './lists/lists.js';
 export { DocumentApiValidationError } from './errors.js';
 export { textReceiptToSDReceipt, buildStructuralReceipt } from './receipt-bridge.js';
-export type { StructuralReceiptParams } from './receipt-bridge.js';
+export type { MutationReceiptBridgeContext, StructuralReceiptParams } from './receipt-bridge.js';
 export { isBlockNodeAddress } from './validation-primitives.js';
-export type { InsertInput, InsertContentType, TextInsertInput, LegacyInsertInput } from './insert/insert.js';
+export type { InsertInput, InsertContentType, TextInsertInput, RichContentInsertInput, LegacyInsertInput, } from './insert/insert.js';
 export { isStructuralInsertInput } from './insert/insert.js';
-export type { ReplaceInput, TextReplaceInput } from './replace/replace.js';
-export { executeReplace, isStructuralReplaceInput } from './replace/replace.js';
+export type { ReplaceInput, TextReplaceInput, RichContentReplaceInput } from './replace/replace.js';
+export { executeReplace, isStructuralReplaceInput, isRichContentReplaceInput } from './replace/replace.js';
 export { executeFind } from './find/find.js';
 export { validateDocumentFragment, validateSDFragment } from './validation/fragment-validator.js';
 export type { DeleteInput } from './delete/delete.js';
@@ -288,6 +291,10 @@ export interface DocumentApi {
      * Convert a Markdown string into an SDM/1 structural fragment.
      */
     markdownToFragment(input: MarkdownToFragmentInput): SDMarkdownToFragmentResult;
+    /**
+     * Convert an HTML string into an SDM/1 structural fragment.
+     */
+    htmlToFragment(input: HtmlToFragmentInput): SDHtmlToFragmentResult;
     /**
      * Return document summary info including document counts and capabilities.
      */
@@ -503,6 +510,7 @@ export interface DocumentApiAdapters {
     getMarkdown: GetMarkdownAdapter;
     getHtml: GetHtmlAdapter;
     markdownToFragment: MarkdownToFragmentAdapter;
+    htmlToFragment?: HtmlToFragmentAdapter;
     info: InfoAdapter;
     extract: ExtractAdapter;
     clearContent: ClearContentAdapter;

package/dist/document-api/src/insert/insert.d.ts

@@ -27,7 +27,6 @@ export type TextInsertInput = OptionalInsertLocator & {
 /**
  * Type-safe input for markdown/html inserts with block-level positioning.
  * Accepts BlockNodeAddress targets and placement (routed through the structural insert path).
- * Standalone export: not part of the InsertInput union to avoid type narrowing issues in the runtime.
  */
 export type RichContentInsertInput = {
     target?: SelectionTarget | BlockNodeAddress;
@@ -45,7 +44,7 @@ export type LegacyInsertInput = TextInsertInput;
  * Discrimination: presence of `content` (structural) vs `value` (text string).
  * These are mutually exclusive: providing both is an error.
  */
-export type InsertInput = TextInsertInput | SDInsertInput;
+export type InsertInput = TextInsertInput | RichContentInsertInput | SDInsertInput;
 /** Returns true when the input uses the structural SDFragment shape. */
 export declare function isStructuralInsertInput(input: InsertInput): input is SDInsertInput;
 /**

package/dist/document-api/src/receipt-bridge.d.ts

@@ -1,4 +1,24 @@
-import { TextMutationReceipt, TextMutationRange, ReceiptEffects, SDMutationReceipt, SelectionTarget, MutationResolutionTarget } from './types/index.js';
+import { TextMutationReceipt, TextMutationRange, ReceiptEffects, SDMutationReceipt, SelectionTarget, MutationResolutionTarget, ReceiptSuccess, SDMutationConversionReport } from './types/index.js';
+export interface MutationReceiptBridgeContext {
+    evaluatedRevision?: {
+        before: string;
+        after: string;
+    };
+    conversion?: SDMutationConversionReport;
+}
+interface CanonicalSuccessMetadata {
+    id?: ReceiptSuccess['id'];
+    inserted?: ReceiptSuccess['inserted'];
+    updated?: ReceiptSuccess['updated'];
+    removed?: ReceiptSuccess['removed'];
+    invalidatedRefs?: ReceiptSuccess['invalidatedRefs'];
+    remappedRefs?: ReceiptSuccess['remappedRefs'];
+    affectedStories?: ReceiptSuccess['affectedStories'];
+    textRangeShifts?: ReceiptSuccess['textRangeShifts'];
+    txId?: ReceiptSuccess['txId'];
+    warnings?: ReceiptSuccess['warnings'];
+    effects?: ReceiptSuccess['effects'];
+}
 /**
  * Wraps a TextMutationReceipt into an SDMutationReceipt at the public API boundary.
  *
@@ -6,9 +26,9 @@ import { TextMutationReceipt, TextMutationRange, ReceiptEffects, SDMutationRecei
  * - Resolution is passed through directly (both use TextAddress).
  * - Failure codes from the text pipeline are mapped to SDErrorCode.
  */
-export declare function textReceiptToSDReceipt(receipt: TextMutationReceipt): SDMutationReceipt;
+export declare function textReceiptToSDReceipt(receipt: TextMutationReceipt, context?: MutationReceiptBridgeContext): SDMutationReceipt;
 /** Parameters for building a structural mutation receipt. */
-export interface StructuralReceiptParams {
+export interface StructuralReceiptParams extends CanonicalSuccessMetadata, MutationReceiptBridgeContext {
     target: MutationResolutionTarget;
     range: TextMutationRange;
     selectionTarget?: SelectionTarget;
@@ -28,3 +48,4 @@ export declare function buildStructuralReceipt(success: false, params: Structura
     code: string;
     message: string;
 }): SDMutationReceipt;
+export {};

package/dist/document-api/src/replace/replace.d.ts

@@ -3,6 +3,8 @@ import { SelectionTarget, TargetLocator } from '../types/address.js';
 import { SDMutationReceipt } from '../types/sd-contract.js';
 import { SDReplaceInput } from '../types/structural-input.js';
 import { StoryLocator } from '../types/story.types.js';
+import { BlockNodeAddress } from '../types/base.js';
+import { NestingPolicy } from '../types/placement.js';
 import { SelectionMutationAdapter } from '../selection-mutation.js';
 import { WriteAdapter } from '../write/write.js';
 /** Text replacement input: uses SelectionTarget / ref. */
@@ -13,12 +15,22 @@ export type TextReplaceInput = TargetLocator & {
     /** Target a specific document story (body, header, footer, footnote, endnote). */
     in?: StoryLocator;
 };
+/** HTML or Markdown replacement input for conversion and structured application. */
+export type RichContentReplaceInput = {
+    value: string;
+    type: 'html' | 'markdown';
+    target?: SelectionTarget | BlockNodeAddress;
+    ref?: string;
+    in?: StoryLocator;
+    nestingPolicy?: NestingPolicy;
+};
 /**
  * Input payload for the `doc.replace` operation.
  *
- * Discrimination: presence of `content` (structural) vs `text` (text replacement).
+ * Discrimination: `text` (plain), `value` (HTML/Markdown), or `content` (SDFragment).
  */
-export type ReplaceInput = TextReplaceInput | SDReplaceInput;
+export type ReplaceInput = TextReplaceInput | RichContentReplaceInput | SDReplaceInput;
 /** Returns true when the input uses the structural SDFragment shape. */
 export declare function isStructuralReplaceInput(input: ReplaceInput): input is SDReplaceInput;
+export declare function isRichContentReplaceInput(input: ReplaceInput): input is RichContentReplaceInput;
 export declare function executeReplace(selectionAdapter: SelectionMutationAdapter, writeAdapter: WriteAdapter, input: ReplaceInput, options?: MutationOptions): SDMutationReceipt;

package/dist/document-api/src/types/clipboard.d.ts

@@ -1,6 +1,7 @@
 import { AdapterMutationFailure } from './adapter-result.js';
 import { SelectionTarget } from './address.js';
 import { ReceiptFailure, ReceiptSuccess, ReviewWarning } from './receipt.js';
+import { SDConversionDiagnostic, SDDiagnostic } from './sd-contract.js';
 import { StoryLocator } from './story.types.js';
 export declare const SUPERDOC_V2_CLIPBOARD_MIME = "application/x-superdoc-v2-fragment";
 export declare const SUPERDOC_V22_CLIPBOARD_MIME = "application/x-superdoc-v2-fragment-v2.2";
@@ -46,11 +47,34 @@ export interface SDPasteRunMarks {
 export interface SDPasteRun {
     text: string;
     marks?: SDPasteRunMarks;
+    /** Transient conversion identity used to map mutation effects back to source nodes. */
+    sourcePath?: readonly (string | number)[];
 }
-export type SDPasteInline = {
+export interface SDPasteParagraphProperties {
+    alignment?: 'left' | 'center' | 'right' | 'justify';
+    indent?: {
+        start?: number;
+        end?: number;
+        left?: number;
+        right?: number;
+        firstLine?: number;
+        hanging?: number;
+    };
+    spacing?: {
+        before?: number;
+        after?: number;
+        line?: number;
+        lineRule?: 'auto' | 'exact' | 'atLeast';
+    };
+}
+export type SDPasteLeafInline = {
     kind: 'text';
     text: string;
     marks?: SDPasteRunMarks;
+    sourcePath?: readonly (string | number)[];
+} | {
+    kind: 'lineBreak';
+    sourcePath?: readonly (string | number)[];
 } | {
     kind: 'image';
     assetId: string;
@@ -59,11 +83,26 @@ export type SDPasteInline = {
     name?: string;
     alt?: string;
     title?: string;
+    sourcePath?: readonly (string | number)[];
+};
+export type SDPasteInline = SDPasteLeafInline | {
+    kind: 'hyperlink';
+    target: {
+        kind: 'external';
+        url: string;
+    } | {
+        kind: 'anchor';
+        anchor: string;
+    };
+    inlines: readonly SDPasteLeafInline[];
+    tooltip?: string;
+    sourcePath?: readonly (string | number)[];
 };
 export interface SDPasteParagraphBlock {
     kind: 'paragraph';
     runs: readonly SDPasteRun[];
     inlines?: readonly SDPasteInline[];
+    paragraphProps?: SDPasteParagraphProperties;
     styleRef?: string;
     /** Portable built-in style intent; destination style identity remains local. */
     semanticStyleRole?: 'default-paragraph' | 'title' | 'subtitle' | `heading-${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}`;
@@ -83,7 +122,12 @@ export interface SDPasteParagraphBlock {
         level?: number;
         /** True on the first block of a distinct adjacent portable list. */
         startsNewList?: boolean;
+        /** Positive ordinal for an ordered-list restart at `level`. */
+        start?: number;
+        format?: 'decimal' | 'lowerLetter' | 'upperLetter' | 'lowerRoman' | 'upperRoman';
+        text?: string;
     };
+    listItemContinuationLevel?: number;
     /**
      * Pre-validated direct `<w:pPr>` properties. Same-document copy carries the
      * source paragraph's materialized properties for fidelity; external HTML
@@ -99,6 +143,16 @@ export interface SDPasteParagraphBlock {
      * paste anchor's paragraph, independent of whether they carry formatting.
      */
     complete?: boolean;
+    /** Transient conversion identity used to map mutation effects back to source nodes. */
+    sourcePath?: readonly (string | number)[];
+}
+export interface SDPasteHeadingBlock extends Omit<SDPasteParagraphBlock, 'kind' | 'semanticStyleRole'> {
+    kind: 'heading';
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+}
+export interface SDPasteHorizontalRuleBlock {
+    kind: 'horizontalRule';
+    sourcePath?: readonly (string | number)[];
 }
 export interface SDPasteTableCell {
     /** Cell content: paragraph blocks rendered through the shared paste renderer. */
@@ -114,9 +168,12 @@ export interface SDPasteTableCell {
         bottomPt?: number;
         leftPt?: number;
     };
+    sourcePath?: readonly (string | number)[];
 }
 export interface SDPasteTableRow {
     cells: readonly SDPasteTableCell[];
+    header?: boolean;
+    sourcePath?: readonly (string | number)[];
 }
 /**
  * Table paste block: rendered as `w:tbl` with V1-parity defaults. Cell
@@ -126,8 +183,9 @@ export interface SDPasteTableRow {
 export interface SDPasteTableBlock {
     kind: 'table';
     rows: readonly SDPasteTableRow[];
+    sourcePath?: readonly (string | number)[];
 }
-export type SDPasteBlock = SDPasteParagraphBlock | SDPasteTableBlock;
+export type SDPasteBlock = SDPasteParagraphBlock | SDPasteHeadingBlock | SDPasteHorizontalRuleBlock | SDPasteTableBlock;
 export interface SDPasteAsset {
     id: string;
     mimeType: 'image/png' | 'image/jpeg';
@@ -146,12 +204,17 @@ export interface SDPasteFragment {
     assets?: readonly SDPasteAsset[];
     diagnostics?: readonly ClipboardInsertDiagnostic[];
 }
-export interface ClipboardInsertDiagnostic {
-    severity: 'error' | 'warning' | 'info';
+export interface ClipboardInsertDiagnostic extends SDDiagnostic {
     reason: SDPasteUnsupportedReason;
-    message: string;
     sourceKind?: ClipboardSourceKind;
-    path?: Array<string | number>;
+    /** Fatal rich-conversion attempt retained when a plain-text fallback is selected. */
+    cause?: SDConversionDiagnostic;
+}
+/** HTML conversion diagnostic with the clipboard negotiation envelope retained. */
+export interface ClipboardHtmlConversionDiagnostic extends SDConversionDiagnostic {
+    reason: SDPasteUnsupportedReason;
+    sourceKind: 'html';
+    cause?: SDConversionDiagnostic;
 }
 export interface ClipboardInsertPlanSummary {
     sourceKind: ClipboardSourceKind;

package/dist/document-api/src/types/fragment.d.ts

@@ -16,7 +16,7 @@ export interface SDDocument {
     annotations?: SDAnnotations;
     metadata?: SDDocumentMeta;
 }
-export declare const SD_CONTENT_NODE_KINDS: readonly ["paragraph", "heading", "list", "table", "toc", "index", "bibliography", "tableOfAuthorities", "break", "sectionBreak", "sectPr", "image", "drawing", "sdt", "customXml", "altChunk", "math", "field"];
+export declare const SD_CONTENT_NODE_KINDS: readonly ["paragraph", "heading", "list", "table", "toc", "index", "bibliography", "tableOfAuthorities", "break", "horizontalRule", "sectionBreak", "sectPr", "image", "drawing", "sdt", "customXml", "altChunk", "math", "field"];
 export type SDContentNodeKind = (typeof SD_CONTENT_NODE_KINDS)[number];
 export declare const SD_INLINE_NODE_KINDS: readonly ["run", "hyperlink", "crossRef", "indexEntry", "sequenceField", "citation", "authorityEntry", "tocEntry", "image", "drawing", "sdt", "customXml", "math", "field", "tab", "lineBreak", "footnoteRef", "endnoteRef"];
 export type SDInlineNodeKind = (typeof SD_INLINE_NODE_KINDS)[number];

package/dist/document-api/src/types/index.d.ts

@@ -23,6 +23,7 @@ export * from './discovery.js';
 export * from './blocks.types.js';
 export * from './toc.types.js';
 export * from './fragment.js';
+export * from './sd-contract.js';
 export * from './placement.js';
 export * from './adapter-result.js';
 export * from './structural-input.js';

package/dist/document-api/src/types/mutation-plan.types.d.ts

@@ -5,6 +5,7 @@ import { InsertStylePolicy, StylePolicy } from './style-policy.types.js';
 import { InlineRunPatch } from '../format/inline-run-patch.js';
 import { SDFragment } from './fragment.js';
 import { Placement, NestingPolicy } from './placement.js';
+import { AffectedRef } from './receipt.js';
 import { ChangeMode } from '../write/write.js';
 import { StoryLocator } from './story.types.js';
 export type SelectWhere = {
@@ -229,6 +230,8 @@ export type PlanReceipt = {
     };
     steps: StepOutcome[];
     trackedChanges?: TrackedChangeAddress[];
+    /** Caller-held refs that no longer resolve after the plan. */
+    invalidatedRefs?: AffectedRef[];
     timing: {
         totalMs: number;
     };

package/dist/document-api/src/types/receipt.d.ts

@@ -68,6 +68,8 @@ export interface TextRangeShift {
 /** A visible text span created by a mutation (e.g. `doc.insert`). */
 export interface TextMutationEffect {
     kind: 'insertedText';
+    /** Transient source fragment path that produced this created span. */
+    sourcePath?: readonly (string | number)[];
     /**
      * Block-absolute address of the created span. `range.start` is the base
      * offset within the target block (nonzero when text was appended into a
@@ -82,6 +84,8 @@ export interface TextMutationEffect {
 /** A block created by a structural mutation (e.g. paragraph/heading insert). */
 export interface BlockMutationEffect {
     kind: 'insertedBlock';
+    /** Transient source fragment path that produced this created block. */
+    sourcePath?: readonly (string | number)[];
     /** Address of the created block. */
     target: BlockNodeAddress;
     /**