superdoc 2.7.0-next.10 → 2.7.0-next.12

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.7.0-next.10",
+	superdocVersion: "2.7.0-next.12",
 	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.7.0-next.10",
+	superdocVersion: "2.7.0-next.12",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

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

@@ -1,5 +1,6 @@
 import { OperationId } from '../contract/types.js';
 import { InlinePropertyStorage, InlinePropertyType, InlineRunPatchKey } from '../format/inline-run-patch.js';
+import { SDHtmlMarkdownSupportCheckInput, SDHtmlMarkdownSupportCheckResult } from './html-markdown-support.js';
 export declare const CAPABILITY_REASON_CODES: readonly ["COMMAND_UNAVAILABLE", "HELPER_UNAVAILABLE", "OPERATION_UNAVAILABLE", "TRACKED_MODE_UNAVAILABLE", "DRY_RUN_UNAVAILABLE", "NAMESPACE_UNAVAILABLE", "STYLES_PART_MISSING", "COLLABORATION_ACTIVE"];
 export type CapabilityReasonCode = (typeof CAPABILITY_REASON_CODES)[number];
 /**
@@ -72,6 +73,7 @@ export interface DocumentApiCapabilities {
 /** Engine-specific adapter that resolves runtime capabilities for the current editor instance. */
 export interface CapabilitiesAdapter {
     get(): DocumentApiCapabilities;
+    check?(input: SDHtmlMarkdownSupportCheckInput): Promise<SDHtmlMarkdownSupportCheckResult>;
 }
 /**
  * Delegates to the capabilities adapter to retrieve the current capability snapshot.
@@ -80,3 +82,4 @@ export interface CapabilitiesAdapter {
  * @returns The resolved capabilities for this editor instance.
  */
 export declare function executeCapabilities(adapter: CapabilitiesAdapter): DocumentApiCapabilities;
+export declare function executeCapabilitiesCheck(adapter: CapabilitiesAdapter, input: SDHtmlMarkdownSupportCheckInput): Promise<SDHtmlMarkdownSupportCheckResult>;

package/dist/document-api/src/capabilities/html-markdown-support.d.ts

@@ -0,0 +1,66 @@
+import { RichContentInsertInput } from '../insert/insert.js';
+import { RichContentReplaceInput } from '../replace/replace.js';
+import { ChangeMode } from '../write/write.js';
+import { ProjectHtmlInput, ProjectMarkdownInput, SDContentProjectionResult, SDProjectionReviewMode, SDResolvedProjectionScope } from '../types/content-projection.js';
+import { SDFragment } from '../types/fragment.js';
+import { SDError, SDHtmlMarkdownOutcome, SDMutationConversionReport, SDMutationReceipt } from '../types/sd-contract.js';
+import { StoryLocator } from '../types/story.types.js';
+export interface SDHtmlMarkdownCheckGuard {
+    version: 'sd-html-markdown-check/1';
+    operation: 'insert' | 'replace';
+    evaluatedRevision: string;
+    requestSha256: string;
+    analysisSha256: string;
+}
+export type SDHtmlMarkdownSupportCheckInput = {
+    operation: 'insert';
+    input: RichContentInsertInput;
+    options?: {
+        changeMode?: ChangeMode;
+    };
+} | {
+    operation: 'replace';
+    input: RichContentReplaceInput;
+    options?: {
+        changeMode?: ChangeMode;
+    };
+} | {
+    operation: 'projectHtml';
+    input?: ProjectHtmlInput;
+} | {
+    operation: 'projectMarkdown';
+    input?: ProjectMarkdownInput;
+};
+interface SDHtmlMarkdownCheckCommon {
+    operation: SDHtmlMarkdownSupportCheckInput['operation'];
+    format: 'html' | 'markdown';
+    supported: boolean;
+    outcome: SDHtmlMarkdownOutcome;
+    evaluatedRevision: string;
+    failure?: SDError;
+}
+export interface SDHtmlMarkdownWriteCheckResult extends SDHtmlMarkdownCheckCommon {
+    operation: 'insert' | 'replace';
+    wouldChange: boolean;
+    conversion: SDMutationConversionReport;
+    plan?: {
+        fragment: SDFragment;
+        resolution: NonNullable<SDMutationReceipt['resolution']>;
+        changeMode: ChangeMode;
+        atomic: true;
+    };
+    guard?: SDHtmlMarkdownCheckGuard;
+}
+export interface SDHtmlMarkdownProjectionCheckResult extends SDHtmlMarkdownCheckCommon {
+    operation: 'projectHtml' | 'projectMarkdown';
+    plan?: {
+        reviewMode: SDProjectionReviewMode;
+        story: StoryLocator;
+        scope: SDResolvedProjectionScope;
+        includeSourceMap: boolean;
+    };
+    projection?: SDContentProjectionResult<'html' | 'markdown'>;
+}
+export type SDHtmlMarkdownSupportCheckResult = SDHtmlMarkdownWriteCheckResult | SDHtmlMarkdownProjectionCheckResult;
+export declare function validateSDHtmlMarkdownSupportCheckInput(input: unknown): asserts input is SDHtmlMarkdownSupportCheckInput;
+export {};

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" | "projectMarkdown" | "projectHtml" | "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")[];
+export declare const MUTATING_OPERATION_IDS: ("replace" | "find" | "delete" | "get" | "insert" | "info" | "projectHtml" | "projectMarkdown" | "capabilities.check" | "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

@@ -1055,6 +1055,17 @@ export declare const OPERATION_DEFINITIONS: {
         readonly referenceDocPath: "capabilities/get.mdx";
         readonly referenceGroup: "capabilities";
     };
+    readonly 'capabilities.check': {
+        readonly memberPath: "capabilities.check";
+        readonly description: "Check an exact HTML or Markdown insert, replace, or detailed projection against the current document without mutating it.";
+        readonly expectedResult: "Returns a Promise resolving to structured support, fidelity outcome, diagnostics, and a revision-bound guard for supported writes.";
+        readonly requiresDocumentContext: true;
+        readonly metadata: CommandStaticMetadata;
+        readonly referenceDocPath: "capabilities/check.mdx";
+        readonly referenceGroup: "capabilities";
+        readonly intentGroup: "edit";
+        readonly intentAction: "check_support";
+    };
     readonly 'create.table': {
         readonly memberPath: "create.table";
         readonly description: "Create a new table at the target position.";

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

@@ -21,7 +21,7 @@ import { ClearContentInput } from '../clear-content/clear-content.js';
 import { InsertInput } from '../insert/insert.js';
 import { ReplaceInput } from '../replace/replace.js';
 import { DeleteInput } from '../delete/delete.js';
-import { MutationOptions, RevisionGuardOptions } from '../write/write.js';
+import { MutationOptions, RevisionGuardOptions, RichContentMutationOptions } from '../write/write.js';
 import { FormatInlineAliasInput, FormatRangeInput, StyleApplyInput } from '../format/format.js';
 import { InlineRunPatchKey } from '../format/inline-run-patch.js';
 import { StylesApplyInput, StylesApplyOptions, StylesApplyReceipt, StylesGetCatalogInput, StylesGetCatalogResult } from '../styles/index.js';
@@ -31,6 +31,7 @@ import { CommentInfo, CommentsListQuery, CommentsListResult } from '../comments/
 import { TrackChangesListInput, TrackChangesGetInput, ReviewDecideInput } from '../track-changes/track-changes.js';
 import { TrackChangeInfo, TrackChangesListResult } from '../types/track-changes.types.js';
 import { DocumentApiCapabilities } from '../capabilities/capabilities.js';
+import { SDHtmlMarkdownSupportCheckInput, SDHtmlMarkdownSupportCheckResult } from '../capabilities/html-markdown-support.js';
 import { HistoryState, HistoryActionResult } from '../history/history.types.js';
 import { DiffSnapshot, DiffPayload, DiffApplyResult, DiffCompareInput, DiffApplyInput, DiffApplyOptions } from '../diff/diff.types.js';
 import { ExportToDocxInput, ExportToDocxResult } from '../export/export.types.js';
@@ -141,12 +142,12 @@ export interface OperationRegistry extends FormatInlineAliasOperationRegistry {
     };
     insert: {
         input: InsertInput;
-        options: MutationOptions;
+        options: RichContentMutationOptions;
         output: SDMutationReceipt;
     };
     replace: {
         input: ReplaceInput;
-        options: MutationOptions;
+        options: RichContentMutationOptions;
         output: SDMutationReceipt;
     };
     delete: {
@@ -729,6 +730,11 @@ export interface OperationRegistry extends FormatInlineAliasOperationRegistry {
         options: never;
         output: DocumentApiCapabilities;
     };
+    'capabilities.check': {
+        input: SDHtmlMarkdownSupportCheckInput;
+        options: never;
+        output: Promise<SDHtmlMarkdownSupportCheckResult>;
+    };
     'history.get': {
         input: undefined;
         options: never;

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

@@ -30,9 +30,10 @@ import { CreateAdapter, CreateApi } from './create/create.js';
 import { BlocksAdapter, BlocksApi } from './blocks/blocks.js';
 import { TableLocator, TableMutationResult, TablesConvertFromTextInput, TablesMoveInput, TablesSplitInput, TablesConvertToTextInput, TablesSetLayoutInput, TablesInsertRowInput, TablesDeleteRowInput, TablesMoveRowInput, TablesSetRowHeightInput, TablesDistributeRowsInput, TablesSetRowOptionsInput, TablesInsertColumnInput, TablesDeleteColumnInput, TablesSetColumnWidthInput, TablesDistributeColumnsInput, TablesInsertCellInput, TablesDeleteCellInput, TablesMergeCellsInput, TablesUnmergeCellsInput, TablesSplitCellInput, TablesSetCellPropertiesInput, TablesSetCellTextInput, TablesSortInput, TablesSetAltTextInput, TablesSetStyleInput, TablesClearStyleInput, TablesSetStyleOptionInput, TablesSetBorderInput, TablesClearBorderInput, TablesApplyBorderPresetInput, TablesSetShadingInput, TablesClearShadingInput, TablesSetTablePaddingInput, TablesSetCellPaddingInput, TablesSetCellSpacingInput, TablesClearCellSpacingInput, TablesApplyStyleInput, TablesSetBordersInput, TablesSetTableOptionsInput, TablesApplyPresetInput, TablesGetInput, TablesGetOutput, TablesGetCellsInput, TablesGetCellsOutput, TablesGetPropertiesInput, TablesGetPropertiesOutput, TablesGetStylesInput, TablesGetStylesOutput, TablesSetDefaultStyleInput, TablesClearDefaultStyleInput } from './types/table-operations.types.js';
 import { TrackChangesAdapter, TrackChangesApi } from './track-changes/track-changes.js';
-import { MutationOptions, RevisionGuardOptions, WriteAdapter } from './write/write.js';
+import { MutationOptions, RevisionGuardOptions, RichContentMutationOptions, WriteAdapter } from './write/write.js';
 import { SelectionMutationAdapter } from './selection-mutation.js';
 import { CapabilitiesAdapter, DocumentApiCapabilities } from './capabilities/capabilities.js';
+import { SDHtmlMarkdownSupportCheckInput, SDHtmlMarkdownSupportCheckResult } from './capabilities/html-markdown-support.js';
 import { OperationId } from './contract/types.js';
 import { DynamicInvokeRequest, InvokeRequest, InvokeResult } from './contract/operation-registry.js';
 import { PlanApi } from './plan/plan.js';
@@ -63,6 +64,7 @@ import { AuthoritiesApi, AuthoritiesAdapter } from './authorities/authorities.js
 export * from './types/index.js';
 export * from './contract/index.js';
 export * from './capabilities/capabilities.js';
+export * from './capabilities/html-markdown-support.js';
 export * from './inline-semantics/index.js';
 export type { HistoryAdapter, HistoryApi } from './history/history.js';
 export { executeHistoryGet, executeHistoryUndo, executeHistoryRedo } from './history/history.js';
@@ -97,7 +99,7 @@ export type { GetMarkdownAdapter, GetMarkdownInput } from './get-markdown/get-ma
 export type { GetHtmlAdapter, GetHtmlInput } from './get-html/get-html.js';
 export type { InfoAdapter, InfoInput } from './info/info.js';
 export type { ExtractAdapter, ExtractInput } from './extract/extract.js';
-export type { WriteAdapter, WriteRequest } from './write/write.js';
+export type { WriteAdapter, WriteRequest, RichContentMutationOptions } from './write/write.js';
 export type { FormatInlineAliasApi, FormatInlineAliasInput, FormatBoldInput, FormatItalicInput, FormatRangeInput, FormatUnderlineInput, FormatStrikethroughInput, StyleApplyInput, StyleApplyOptions, } from './format/format.js';
 export type { InlineRunPatch, InlineRunPatchKey, InlinePropertyStorage, InlinePropertyType, InlinePropertyCarrier, InlinePropertyRegistryEntry, UnderlinePatch, ShadingPatch, BorderPatch, FitTextPatch, LangPatch, RFontsPatch, EastAsianLayoutPatch, StylisticSetPatch, } from './format/inline-run-patch.js';
 export { INLINE_PROPERTY_REGISTRY, INLINE_PROPERTY_KEY_SET, INLINE_PROPERTY_BY_KEY, INLINE_PROPERTY_KEYS_BY_STORAGE, validateInlineRunPatch, buildInlineRunPatchSchema, } from './format/inline-run-patch.js';
@@ -232,6 +234,7 @@ export type TablesAdapter = Omit<TablesApi, 'moveRow'> & {
 export interface CapabilitiesApi {
     (): DocumentApiCapabilities;
     get(): DocumentApiCapabilities;
+    check(input: SDHtmlMarkdownSupportCheckInput): Promise<SDHtmlMarkdownSupportCheckResult>;
 }
 export interface QueryApi {
     /** Accepts canonical nested input or a selector shorthand normalized to `{ select: ... }` internally. */
@@ -325,11 +328,11 @@ export interface DocumentApi {
      * Insert content at a target location.
      * If target is omitted, inserts at the end of the document.
      */
-    insert(input: InsertInput, options?: MutationOptions): SDMutationReceipt;
+    insert(input: InsertInput, options?: RichContentMutationOptions): SDMutationReceipt;
     /**
      * Replace text at a target range.
      */
-    replace(input: ReplaceInput, options?: MutationOptions): SDMutationReceipt;
+    replace(input: ReplaceInput, options?: RichContentMutationOptions): SDMutationReceipt;
     /**
      * Delete text at a target range.
      */

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

@@ -1,4 +1,4 @@
-import { MutationOptions, WriteAdapter } from '../write/write.js';
+import { RichContentMutationOptions, WriteAdapter } from '../write/write.js';
 import { SelectionTarget, TargetLocator, SDMutationReceipt } from '../types/index.js';
 import { SDInsertInput } from '../types/structural-input.js';
 import { StoryLocator } from '../types/story.types.js';
@@ -45,8 +45,18 @@ export type LegacyInsertInput = TextInsertInput;
  * These are mutually exclusive: providing both is an error.
  */
 export type InsertInput = TextInsertInput | RichContentInsertInput | SDInsertInput;
+export declare function isRichContentInsertInput(input: InsertInput): input is RichContentInsertInput;
 /** Returns true when the input uses the structural SDFragment shape. */
 export declare function isStructuralInsertInput(input: InsertInput): input is SDInsertInput;
+/**
+ * Validates InsertInput as either text or structural shape.
+ *
+ * Validation order:
+ * 0. Input shape guard (must be non-null plain object)
+ * 1. Union conflict detection (mutually exclusive discriminants)
+ * 2. Shape-specific field and type validation
+ */
+export declare function validateInsertInput(input: unknown): asserts input is InsertInput;
 /**
  * Executes an insert operation, routing to the appropriate adapter path.
  *
@@ -60,5 +70,5 @@ export declare function isStructuralInsertInput(input: InsertInput): input is SD
  * @param options - Optional mutation options (changeMode, dryRun, expectedRevision).
  * @returns Receipt indicating success/failure and mutation metadata.
  */
-export declare function executeInsert(selectionAdapter: SelectionMutationAdapter, writeAdapter: WriteAdapter, input: InsertInput, options?: MutationOptions): SDMutationReceipt;
+export declare function executeInsert(selectionAdapter: SelectionMutationAdapter, writeAdapter: WriteAdapter, input: InsertInput, options?: RichContentMutationOptions): SDMutationReceipt;
 export {};

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

@@ -1,4 +1,4 @@
-import { MutationOptions } from '../types/mutation-plan.types.js';
+import { RichContentMutationOptions, WriteAdapter } from '../write/write.js';
 import { SelectionTarget, TargetLocator } from '../types/address.js';
 import { SDMutationReceipt } from '../types/sd-contract.js';
 import { SDReplaceInput } from '../types/structural-input.js';
@@ -6,7 +6,6 @@ import { BodyStoryLocator, 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, or the complete main body. */
 export type TextReplaceInput = (TargetLocator & {
     target?: SelectionTarget;
@@ -45,4 +44,5 @@ export type ReplaceInput = TextReplaceInput | RichContentReplaceInput | SDReplac
 /** 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;
+export declare function validateReplaceInput(input: unknown): asserts input is ReplaceInput;
+export declare function executeReplace(selectionAdapter: SelectionMutationAdapter, writeAdapter: WriteAdapter, input: ReplaceInput, options?: RichContentMutationOptions): SDMutationReceipt;

package/dist/document-api/src/types/content-projection.d.ts

@@ -1,7 +1,7 @@
 import { BlockNodeAddress, BlockNodeType } from './base.js';
 import { Range, SelectionTarget, TextTarget } from './address.js';
 import { StoryLocator } from './story.types.js';
-import { SDDiagnostic } from './sd-contract.js';
+import { SDDiagnostic, SDHtmlMarkdownOutcome } from './sd-contract.js';
 export declare const SD_PROJECTION_FORMATS: readonly ["html", "markdown"];
 export type SDProjectionFormat = (typeof SD_PROJECTION_FORMATS)[number];
 export declare const SD_PROJECTION_REVIEW_MODES: readonly ["final", "original", "redline"];
@@ -112,6 +112,8 @@ export interface SDContentProjectionResult<TFormat extends SDProjectionFormat =
     format: TFormat;
     content: string;
     status: SDProjectionStatus;
+    /** Fidelity outcome derived from the complete projection diagnostics. */
+    outcome: SDHtmlMarkdownOutcome;
     reviewMode: SDProjectionReviewMode;
     evaluatedRevision: string;
     story: StoryLocator;
@@ -122,5 +124,6 @@ export interface SDContentProjectionResult<TFormat extends SDProjectionFormat =
     annotations: SDProjectionAnnotation[];
     sourceMap?: SDProjectionSourceMap;
 }
+export declare function deriveSDHtmlMarkdownOutcome(diagnostics: readonly Pick<SDDiagnostic, 'severity' | 'lossy'>[]): SDHtmlMarkdownOutcome;
 export declare function deriveSDProjectionStatus(diagnostics: readonly Pick<SDProjectionDiagnostic, 'severity' | 'lossy'>[]): SDProjectionStatus;
 export declare function validateSDProjectionSourceMap(sourceMap: SDProjectionSourceMap, contentLength: number): boolean;

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

@@ -264,4 +264,4 @@ export type PlanExecutionError = {
     stepId?: string;
     details?: unknown;
 };
-export type { RevisionGuardOptions, MutationOptions } from '../write/write.js';
+export type { RevisionGuardOptions, MutationOptions, RichContentMutationOptions } from '../write/write.js';

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

@@ -9,7 +9,7 @@ export type AffectedRefRemapping = {
     from: AffectedRef;
     to: AffectedRef;
 };
-export type ReceiptFailureCode = 'NO_OP' | 'INVALID_TARGET' | 'TARGET_NOT_FOUND' | 'CAPABILITY_UNAVAILABLE' | 'PERMISSION_DENIED' | 'STALE_REVISION' | 'REVISION_MISMATCH' | 'MATCH_NOT_FOUND' | 'AMBIGUOUS_MATCH' | 'STYLE_CONFLICT' | 'PRECONDITION_FAILED' | 'COMMENT_CASCADE_PARTIAL' | 'INVALID_INPUT' | 'CROSS_BLOCK_MATCH' | 'SPAN_FRAGMENTED' | 'TARGET_MOVED' | 'PLAN_CONFLICT_OVERLAP' | 'INVALID_STEP_COMBINATION' | 'REVISION_CHANGED_SINCE_COMPILE' | 'INVALID_INSERTION_CONTEXT' | 'DOCUMENT_IDENTITY_CONFLICT' | 'UNSUPPORTED_ENVIRONMENT' | 'INTERNAL_ERROR' | 'PAGE_NUMBERS_NOT_MATERIALIZED' | 'INCOMPATIBLE_DEFINITIONS' | 'NO_COMPATIBLE_PREVIOUS' | 'ALREADY_CONTINUOUS' | 'NO_PREVIOUS_LIST' | 'NO_ADJACENT_SEQUENCE' | 'ALREADY_SAME_SEQUENCE' | 'LEVEL_OUT_OF_RANGE' | 'LEVEL_NOT_FOUND' | 'INVALID_NESTING' | 'INVALID_PLACEMENT' | 'EMPTY_FRAGMENT' | 'INVALID_FRAGMENT' | 'INVALID_PAYLOAD' | 'CAPABILITY_UNSUPPORTED' | 'ADDRESS_STALE' | 'DUPLICATE_ID' | 'INVALID_CONTEXT' | 'RAW_MODE_REQUIRED' | 'PRESERVE_ONLY_VIOLATION' | 'LOCK_VIOLATION' | 'TYPE_MISMATCH' | 'UNSUPPORTED_SOURCE' | 'INVALID_PACKAGE' | 'UNSUPPORTED_TEMPLATE_CONTENT';
+export type ReceiptFailureCode = 'NO_OP' | 'INVALID_TARGET' | 'TARGET_NOT_FOUND' | 'CAPABILITY_UNAVAILABLE' | 'PERMISSION_DENIED' | 'STALE_REVISION' | 'REVISION_MISMATCH' | 'CHECK_MISMATCH' | 'MATCH_NOT_FOUND' | 'AMBIGUOUS_MATCH' | 'STYLE_CONFLICT' | 'PRECONDITION_FAILED' | 'COMMENT_CASCADE_PARTIAL' | 'INVALID_INPUT' | 'CROSS_BLOCK_MATCH' | 'SPAN_FRAGMENTED' | 'TARGET_MOVED' | 'PLAN_CONFLICT_OVERLAP' | 'INVALID_STEP_COMBINATION' | 'REVISION_CHANGED_SINCE_COMPILE' | 'INVALID_INSERTION_CONTEXT' | 'DOCUMENT_IDENTITY_CONFLICT' | 'UNSUPPORTED_ENVIRONMENT' | 'INTERNAL_ERROR' | 'PAGE_NUMBERS_NOT_MATERIALIZED' | 'INCOMPATIBLE_DEFINITIONS' | 'NO_COMPATIBLE_PREVIOUS' | 'ALREADY_CONTINUOUS' | 'NO_PREVIOUS_LIST' | 'NO_ADJACENT_SEQUENCE' | 'ALREADY_SAME_SEQUENCE' | 'LEVEL_OUT_OF_RANGE' | 'LEVEL_NOT_FOUND' | 'INVALID_NESTING' | 'INVALID_PLACEMENT' | 'EMPTY_FRAGMENT' | 'INVALID_FRAGMENT' | 'INVALID_PAYLOAD' | 'CAPABILITY_UNSUPPORTED' | 'ADDRESS_STALE' | 'DUPLICATE_ID' | 'INVALID_CONTEXT' | 'RAW_MODE_REQUIRED' | 'PRESERVE_ONLY_VIOLATION' | 'LOCK_VIOLATION' | 'TYPE_MISMATCH' | 'UNSUPPORTED_SOURCE' | 'INVALID_PACKAGE' | 'UNSUPPORTED_TEMPLATE_CONTENT';
 export type ReceiptFailure = {
     code: ReceiptFailureCode;
     message: string;

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

@@ -2,7 +2,9 @@ import { BlockNodeAddress } from './base.js';
 import { SelectionTarget, TextAddress } from './address.js';
 import { ReceiptEffects, ReceiptSuccess, TextMutationRange } from './receipt.js';
 import { BodyStoryLocator } from './story.types.js';
-export type SDErrorCode = 'INVALID_PAYLOAD' | 'INVALID_TARGET' | 'TARGET_NOT_FOUND' | 'ADDRESS_STALE' | 'PRECONDITION_FAILED' | 'REVISION_MISMATCH' | 'INVALID_CONTEXT' | 'INVALID_NESTING' | 'INVALID_PLACEMENT' | 'DUPLICATE_ID' | 'CAPABILITY_UNSUPPORTED' | 'RAW_MODE_REQUIRED' | 'PRESERVE_ONLY_VIOLATION' | 'NO_OP' | 'UNSUPPORTED_ENVIRONMENT' | 'INTERNAL_ERROR';
+export type SDErrorCode = 'INVALID_PAYLOAD' | 'INVALID_TARGET' | 'TARGET_NOT_FOUND' | 'ADDRESS_STALE' | 'PRECONDITION_FAILED' | 'REVISION_MISMATCH' | 'CHECK_MISMATCH' | 'INVALID_CONTEXT' | 'INVALID_NESTING' | 'INVALID_PLACEMENT' | 'DUPLICATE_ID' | 'CAPABILITY_UNSUPPORTED' | 'RAW_MODE_REQUIRED' | 'PRESERVE_ONLY_VIOLATION' | 'NO_OP' | 'UNSUPPORTED_ENVIRONMENT' | 'INTERNAL_ERROR';
+export declare const SD_HTML_MARKDOWN_OUTCOMES: readonly ["preserved", "preserved-with-warnings", "simplified", "rejected", "no-op", "invalid-target", "outdated"];
+export type SDHtmlMarkdownOutcome = (typeof SD_HTML_MARKDOWN_OUTCOMES)[number];
 export interface SDError {
     code: SDErrorCode;
     message: string;
@@ -21,6 +23,8 @@ export interface SDError {
 export type MutationResolutionTarget = TextAddress | BlockNodeAddress | BodyStoryLocator;
 export interface SDMutationReceipt {
     success: boolean;
+    /** Rich HTML/Markdown fidelity outcome, when this receipt came from a rich write. */
+    outcome?: SDHtmlMarkdownOutcome;
     failure?: SDError;
     evaluatedRevision?: {
         before: string;

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

@@ -2,6 +2,7 @@ import { TextMutationReceipt, SDMutationReceipt } from '../types/index.js';
 import { InsertInput } from '../insert/insert.js';
 import { ReplaceInput } from '../replace/replace.js';
 import { StoryLocator } from '../types/story.types.js';
+import { SDHtmlMarkdownCheckGuard } from '../capabilities/html-markdown-support.js';
 export type ChangeMode = 'direct' | 'tracked';
 /**
  * Shared semantic validation for the `changeMode` mutation option.
@@ -40,6 +41,10 @@ export interface MutationOptions extends RevisionGuardOptions {
      */
     dryRun?: boolean;
 }
+export interface RichContentMutationOptions extends MutationOptions {
+    /** Guard returned by `doc.capabilities.check` for an exact rich write. */
+    supportCheck?: SDHtmlMarkdownCheckGuard;
+}
 /**
  * Text insertion request: target-less insert at document end.
  *
@@ -65,9 +70,9 @@ export type WriteRequest = InsertWriteRequest;
 export interface WriteAdapter {
     write(request: InsertWriteRequest, options?: MutationOptions): TextMutationReceipt;
     /** Structured insert for SDFragment or markdown/html content. Returns SDMutationReceipt. */
-    insertStructured(input: InsertInput, options?: MutationOptions): SDMutationReceipt;
+    insertStructured(input: InsertInput, options?: RichContentMutationOptions): SDMutationReceipt;
     /** Structured replace for SDFragment or markdown/html content. Returns SDMutationReceipt. */
-    replaceStructured(input: ReplaceInput, options?: MutationOptions): SDMutationReceipt;
+    replaceStructured(input: ReplaceInput, options?: RichContentMutationOptions): SDMutationReceipt;
 }
-export declare function normalizeMutationOptions(options?: MutationOptions): MutationOptions;
+export declare function normalizeMutationOptions(options?: MutationOptions | RichContentMutationOptions, supportCheckOperation?: 'insert' | 'replace'): RichContentMutationOptions;
 export declare function executeWrite(adapter: WriteAdapter, request: InsertWriteRequest, options?: MutationOptions): TextMutationReceipt;

package/dist/superdoc/src/public/ui/types.d.ts

@@ -27,7 +27,7 @@ import { SuperDocUIReason } from './reasons.js';
  * (`scripts/ensure-types.cjs` `rewriteDocApiPaths`), so no bare private
  * specifier leaks into the emitted `.d.ts`.
  */
-export type { Receipt, SelectionInfo, SelectionTarget, SelectionPoint, TextTarget, TextAddress, ScrollIntoViewInput, ScrollIntoViewOutput, DocumentApi, EntityAddress, CommentsListQuery as DocumentApiCommentsListQuery, CommentsListResult, TrackChangesListResult, ContentControlsListResult, ContentControlInfo, } from '../../../../document-api/src/index.js';
+export type { Receipt, SelectionInfo, SelectionTarget, SelectionPoint, TextTarget, TextAddress, ScrollIntoViewInput, ScrollIntoViewOutput, DocumentApi, EntityAddress, CommentsListQuery as DocumentApiCommentsListQuery, CommentsListResult, TrackChangesListResult, ContentControlsListResult, ContentControlInfo, RichContentInsertInput, SDHtmlMarkdownSupportCheckResult, } from '../../../../document-api/src/index.js';
 export type { StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, } from '../../../../document-api/src/index.js';
 export type { ListPresetId } from '../../../../document-api/src/index.js';
 export type { BrowserDocumentApi, PartialBrowserDocumentApi } from '../browser-document-api.js';

package/dist/superdoc/src/public/ui.d.cts

@@ -37,8 +37,10 @@ import type { FontsSlice as __Cjs_FontsSlice } from './ui.js' with { "resolution
 import type { MetadataHandle as __Cjs_MetadataHandle } from './ui.js' with { "resolution-mode": "import" };
 import type { PartialBrowserDocumentApi as __Cjs_PartialBrowserDocumentApi } from './ui.js' with { "resolution-mode": "import" };
 import type { Receipt as __Cjs_Receipt } from './ui.js' with { "resolution-mode": "import" };
+import type { RichContentInsertInput as __Cjs_RichContentInsertInput } from './ui.js' with { "resolution-mode": "import" };
 import type { ScrollIntoViewInput as __Cjs_ScrollIntoViewInput } from './ui.js' with { "resolution-mode": "import" };
 import type { ScrollIntoViewOutput as __Cjs_ScrollIntoViewOutput } from './ui.js' with { "resolution-mode": "import" };
+import type { SDHtmlMarkdownSupportCheckResult as __Cjs_SDHtmlMarkdownSupportCheckResult } from './ui.js' with { "resolution-mode": "import" };
 import type { SelectionCapture as __Cjs_SelectionCapture } from './ui.js' with { "resolution-mode": "import" };
 import type { SelectionHandle as __Cjs_SelectionHandle } from './ui.js' with { "resolution-mode": "import" };
 import type { SelectionInfo as __Cjs_SelectionInfo } from './ui.js' with { "resolution-mode": "import" };
@@ -134,8 +136,10 @@ export type { __Cjs_FontsSlice as FontsSlice };
 export type { __Cjs_MetadataHandle as MetadataHandle };
 export type { __Cjs_PartialBrowserDocumentApi as PartialBrowserDocumentApi };
 export type { __Cjs_Receipt as Receipt };
+export type { __Cjs_RichContentInsertInput as RichContentInsertInput };
 export type { __Cjs_ScrollIntoViewInput as ScrollIntoViewInput };
 export type { __Cjs_ScrollIntoViewOutput as ScrollIntoViewOutput };
+export type { __Cjs_SDHtmlMarkdownSupportCheckResult as SDHtmlMarkdownSupportCheckResult };
 export type { __Cjs_SelectionCapture as SelectionCapture };
 export type { __Cjs_SelectionHandle as SelectionHandle };
 export type { __Cjs_SelectionInfo as SelectionInfo };

package/dist/superdoc/src/public/ui.d.ts

@@ -26,4 +26,4 @@
 export { createSuperDocUI } from './ui/create-super-doc-ui.js';
 export { shallowEqual } from './ui/equality.js';
 export { BUILT_IN_COMMAND_IDS } from './ui/commands.js';
-export type { EqualityFn, SelectorFn, Subscribable, SuperDocUI, BorrowedSuperDocUI, SuperDocUIOptions, SuperDocUIState, SuperDocUIScope, SuperDocLike, SuperDocEditorLike, CommandHandle, CommandState, CommandExecutionResult, WorkflowReceipt, WorkflowActionResult, WorkflowScrollResult, SelectionRestoreResult, SuperDocUIReason, CommandsHandle, ContextMenuItem, CustomCommandContext, CustomCommandHandle, CustomCommandHandleState, CustomCommandRegistration, CustomCommandRegistrationResult, MetadataHandle, SelectionHandle, ToolbarHandle, CommentsHandle, TrackChangesHandle, ContentControlsHandle, ContentControlFocusResult, FontsHandle, ZoomHandle, DocumentHandle, ViewportHandle, StylesHandle, ActiveParagraphStyle, SliceStatus, SelectionSlice, SelectionCapture, CommentAnchorCapture, ToolbarSnapshotSlice, CommentsSlice, TrackChangesSlice, ContentControlsSlice, FontsSlice, ZoomSlice, DocumentSlice, StylesSlice, StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, CommentInfo, CommentsListQuery, TrackChangeInfo, TrackChangePointHit, TrackChangesItem, FontFamilyOption, FontSizeOption, CommentAddress, TrackedChangeAddress, ContentControlViewportAddress, ViewportEntityAddress, ViewportEntityHit, ViewportContext, ViewportRect, ViewportGetRectInput, ViewportRectResult, BrowserDocumentApi, PartialBrowserDocumentApi, DocumentApi, Receipt, SelectionInfo, SelectionTarget, SelectionPoint, TextTarget, TextAddress, ScrollIntoViewInput, ScrollIntoViewOutput, EntityAddress, CommentsListResult, TrackChangesListResult, ContentControlsListResult, ContentControlInfo, } from './ui/types.js';
+export type { EqualityFn, SelectorFn, Subscribable, SuperDocUI, BorrowedSuperDocUI, SuperDocUIOptions, SuperDocUIState, SuperDocUIScope, SuperDocLike, SuperDocEditorLike, CommandHandle, CommandState, CommandExecutionResult, WorkflowReceipt, WorkflowActionResult, WorkflowScrollResult, SelectionRestoreResult, SuperDocUIReason, CommandsHandle, ContextMenuItem, CustomCommandContext, CustomCommandHandle, CustomCommandHandleState, CustomCommandRegistration, CustomCommandRegistrationResult, MetadataHandle, SelectionHandle, ToolbarHandle, CommentsHandle, TrackChangesHandle, ContentControlsHandle, ContentControlFocusResult, FontsHandle, ZoomHandle, DocumentHandle, ViewportHandle, StylesHandle, ActiveParagraphStyle, SliceStatus, SelectionSlice, SelectionCapture, CommentAnchorCapture, ToolbarSnapshotSlice, CommentsSlice, TrackChangesSlice, ContentControlsSlice, FontsSlice, ZoomSlice, DocumentSlice, StylesSlice, StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, CommentInfo, CommentsListQuery, TrackChangeInfo, TrackChangePointHit, TrackChangesItem, FontFamilyOption, FontSizeOption, CommentAddress, TrackedChangeAddress, ContentControlViewportAddress, ViewportEntityAddress, ViewportEntityHit, ViewportContext, ViewportRect, ViewportGetRectInput, ViewportRectResult, BrowserDocumentApi, PartialBrowserDocumentApi, DocumentApi, Receipt, SelectionInfo, SelectionTarget, SelectionPoint, TextTarget, TextAddress, ScrollIntoViewInput, ScrollIntoViewOutput, EntityAddress, CommentsListResult, TrackChangesListResult, ContentControlsListResult, ContentControlInfo, RichContentInsertInput, SDHtmlMarkdownSupportCheckResult, } from './ui/types.js';

package/dist/superdoc.cjs

@@ -43514,7 +43514,7 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 		this.config.colors = shuffleArray(this.config.colors);
 		this.userColorMap = /* @__PURE__ */ new Map();
 		this.colorIndex = 0;
-		this.version = "2.7.0-next.10";
+		this.version = "2.7.0-next.12";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || require_uuid.v4();
 		this.colors = this.config.colors ?? [];

package/dist/superdoc.es.js

@@ -43447,7 +43447,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 		this.config.colors = shuffleArray(this.config.colors);
 		this.userColorMap = /* @__PURE__ */ new Map();
 		this.colorIndex = 0;
-		this.version = "2.7.0-next.10";
+		this.version = "2.7.0-next.12";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || v4();
 		this.colors = this.config.colors ?? [];