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

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/content-projection.d.ts

@@ -0,0 +1,126 @@
+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';
+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"];
+export type SDProjectionReviewMode = (typeof SD_PROJECTION_REVIEW_MODES)[number];
+export declare const SD_PROJECTION_STATUSES: readonly ["success", "warning", "failed"];
+export type SDProjectionStatus = (typeof SD_PROJECTION_STATUSES)[number];
+export declare const SD_PROJECTION_DIAGNOSTIC_CODES: readonly ["projection-normalized-construct", "projection-downgraded-construct", "projection-unsupported-construct", "projection-placeholder-emitted", "projection-annotation-omitted", "projection-numbering-unresolved", "projection-source-coverage-incomplete", "projection-scope-unsupported", "projection-limit-exceeded", "projection-revision-changed", "projection-malformed-source"];
+export type SDProjectionDiagnosticCode = (typeof SD_PROJECTION_DIAGNOSTIC_CODES)[number];
+export declare const SD_PROJECTION_CONSTRUCTS: readonly ["document", "source", "text", "paragraph", "emptyParagraph", "softBreak", "lineBreak", "heading", "bold", "italic", "underline", "strike", "hyperlink", "list", "listLabel", "table", "tableHeader", "tableRow", "tableCell", "colSpan", "rowSpan", "horizontalRule", "inlineCode", "codeBlock", "image", "field", "contentControl", "math", "drawing", "embeddedObject", "sectionBreak", "pageBreak", "columnBreak", "trackedChange", "comment", "scope", "placeholder"];
+export type SDProjectionConstruct = (typeof SD_PROJECTION_CONSTRUCTS)[number];
+export declare const SD_PROJECTION_DISPOSITIONS: readonly ["preserved", "normalized", "downgraded", "placeholder", "omitted", "rejected"];
+export type SDProjectionDisposition = (typeof SD_PROJECTION_DISPOSITIONS)[number];
+export type SDProjectionScope = BlockNodeAddress | SelectionTarget;
+export interface SDProjectionReadInput {
+    in?: StoryLocator;
+    reviewMode?: SDProjectionReviewMode;
+    scope?: SDProjectionScope;
+}
+export interface ProjectHtmlInput extends SDProjectionReadInput {
+    includeSourceMap?: boolean;
+}
+export interface ProjectMarkdownInput extends SDProjectionReadInput {
+    includeSourceMap?: boolean;
+}
+export type SDResolvedProjectionScope = {
+    kind: 'story';
+} | {
+    kind: 'block';
+    target: BlockNodeAddress;
+} | {
+    kind: 'range';
+    target: SelectionTarget & {
+        coordinateSpace: 'tracked';
+    };
+};
+export type SDProjectionBlockMapEntry = {
+    nodeType: BlockNodeType;
+    output: Range;
+    parentBlockId?: string;
+    changeIds?: string[];
+    commentIds?: string[];
+} & ({
+    identity: 'public';
+    blockId: string;
+} | {
+    identity: 'unavailable';
+    identityUnavailableReason: 'positionDerivedFallback';
+    blockId?: never;
+});
+export type SDProjectionDiagnostic = Omit<SDDiagnostic, 'code' | 'construct' | 'disposition' | 'lossy' | 'source'> & {
+    code: SDProjectionDiagnosticCode;
+    construct: SDProjectionConstruct;
+    disposition: SDProjectionDisposition;
+    lossy: boolean;
+    source: {
+        story: StoryLocator;
+        blockId?: string;
+        range?: Range;
+        coordinateSpace?: 'tracked';
+        changeIds?: string[];
+        commentIds?: string[];
+    };
+    output?: {
+        format: SDProjectionFormat;
+        range?: Range;
+    };
+};
+export interface SDProjectionSourceMap {
+    version: 'sd-projection-source-map/1';
+    outputCoordinateSpace: 'utf16';
+    sourceCoordinateSpace: 'tracked';
+    entries: SDProjectionSourceMapEntry[];
+}
+export type SDProjectionSourceMapEntry = {
+    kind: 'text';
+    output: Range;
+    source: TextTarget & {
+        coordinateSpace: 'tracked';
+    };
+    blockId: string;
+    changeIds?: string[];
+    commentIds?: string[];
+} | ({
+    kind: 'synthetic';
+    output: Range;
+    role: 'listLabel' | 'placeholder';
+    changeIds?: string[];
+    commentIds?: string[];
+} & ({
+    identity: 'public';
+    blockId: string;
+} | {
+    identity: 'unavailable';
+    identityUnavailableReason: 'positionDerivedFallback';
+    blockId?: never;
+}));
+export interface SDProjectionAnnotation {
+    kind: 'trackedChange' | 'comment';
+    id: string;
+    blockIds: string[];
+    sourceTarget?: TextTarget;
+    outputRanges: Range[];
+    status: 'emitted' | 'partiallyEmitted' | 'omitted';
+    omittedReason?: 'reviewMode' | 'unsupported';
+    side?: 'inserted' | 'deleted' | 'source' | 'destination' | 'formatting';
+}
+export interface SDContentProjectionResult<TFormat extends SDProjectionFormat = SDProjectionFormat> {
+    format: TFormat;
+    content: string;
+    status: SDProjectionStatus;
+    reviewMode: SDProjectionReviewMode;
+    evaluatedRevision: string;
+    story: StoryLocator;
+    scope: SDResolvedProjectionScope;
+    lossy: boolean;
+    diagnostics: SDProjectionDiagnostic[];
+    blocks: SDProjectionBlockMapEntry[];
+    annotations: SDProjectionAnnotation[];
+    sourceMap?: SDProjectionSourceMap;
+}
+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/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,8 +23,10 @@ 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';
 export * from './story.types.js';
 export * from './clipboard.js';
+export * from './content-projection.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;
     /**

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

@@ -1,13 +1,14 @@
 import { BlockNodeAddress } from './base.js';
 import { SelectionTarget, TextAddress } from './address.js';
-import { ReceiptEffects, TextMutationRange } from './receipt.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 interface SDError {
     code: SDErrorCode;
     message: string;
     path?: Array<string | number>;
     /** The target that caused the error, when available. */
-    target?: BlockNodeAddress | TextAddress | SelectionTarget;
+    target?: BlockNodeAddress | TextAddress | SelectionTarget | BodyStoryLocator;
     details?: Record<string, unknown>;
 }
 /**
@@ -15,8 +16,9 @@ export interface SDError {
  *
  * - `TextAddress` (`kind: 'text'`): text-level insert/replace with block-relative offsets.
  * - `BlockNodeAddress` (`kind: 'block'`): structural insert/replace targeting a whole block.
+ * - `BodyStoryLocator` (`kind: 'story'`): explicit complete-main-body replacement.
  */
-export type MutationResolutionTarget = TextAddress | BlockNodeAddress;
+export type MutationResolutionTarget = TextAddress | BlockNodeAddress | BodyStoryLocator;
 export interface SDMutationReceipt {
     success: boolean;
     failure?: SDError;
@@ -24,6 +26,16 @@ export interface SDMutationReceipt {
         before: string;
         after: string;
     };
+    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'];
     resolution?: {
         target: MutationResolutionTarget;
         /** Engine-resolved absolute document range for the effective target. */
@@ -40,15 +52,59 @@ export interface SDMutationReceipt {
      * read it here instead. See {@link ReceiptEffects}.
      */
     effects?: ReceiptEffects;
+    conversion?: SDMutationConversionReport;
+}
+export declare const SD_CONVERSION_FORMATS: readonly ["html", "markdown"];
+export type SDConversionFormat = (typeof SD_CONVERSION_FORMATS)[number];
+export declare const SD_CONVERSION_DIAGNOSTIC_CODES: readonly ["conversion-normalized-construct", "conversion-unsupported-construct", "conversion-dropped-style", "conversion-unsafe-content", "conversion-unsafe-url", "conversion-source-limit-exceeded", "conversion-depth-limit-exceeded", "conversion-malformed-input", "conversion-empty-result"];
+export type SDConversionDiagnosticCode = (typeof SD_CONVERSION_DIAGNOSTIC_CODES)[number];
+/** Stable feature identifiers used to classify conversion diagnostics. */
+export declare const SD_CONVERSION_CONSTRUCTS: readonly ["document", "source", "text", "paragraph", "emptyParagraph", "softBreak", "lineBreak", "heading", "bold", "italic", "underline", "strike", "hyperlink", "list", "table", "tableHeader", "colSpan", "rowSpan", "horizontalRule", "inlineCode", "codeBlock", "blockquote", "taskList", "image", "footnote", "rawHtml", "unknownWrapper", "script", "style", "eventHandler"];
+export type SDConversionConstruct = (typeof SD_CONVERSION_CONSTRUCTS)[number];
+export declare const SD_CONVERSION_DISPOSITIONS: readonly ["preserved", "normalized", "downgraded", "dropped", "rejected"];
+export type SDConversionDisposition = (typeof SD_CONVERSION_DISPOSITIONS)[number];
+/** UTF-16 offsets are start-inclusive and end-exclusive. */
+export interface SDConversionSourceRange {
+    startOffset: number;
+    endOffset: number;
+    startLine?: number;
+    startColumn?: number;
+    endLine?: number;
+    endColumn?: number;
+}
+export interface SDConversionSource {
+    format: SDConversionFormat;
+    range?: SDConversionSourceRange;
 }
 export interface SDDiagnostic {
     code: string;
     severity: 'error' | 'warning' | 'info';
     message: string;
     path?: Array<string | number>;
+    construct?: SDConversionConstruct;
+    disposition?: SDConversionDisposition;
+    lossy?: boolean;
+    source?: SDConversionSource;
+}
+/** Diagnostic shape guaranteed by the canonical HTML/Markdown converters. */
+export interface SDConversionDiagnostic extends SDDiagnostic {
+    code: SDConversionDiagnosticCode;
+    construct: SDConversionConstruct;
+    disposition: SDConversionDisposition;
+    lossy: boolean;
+    source: SDConversionSource;
 }
-export interface SDMarkdownToFragmentResult {
+export interface SDMutationConversionReport {
+    format: SDConversionFormat;
+    lossy: boolean;
+    diagnostics: SDConversionDiagnostic[];
+}
+export interface SDContentToFragmentResult<TDiagnostic extends SDDiagnostic = SDDiagnostic> {
     fragment: import('./fragment.js').SDFragment;
     lossy: boolean;
-    diagnostics: SDDiagnostic[];
+    diagnostics: TDiagnostic[];
+}
+export type SDHtmlToFragmentResult = SDContentToFragmentResult<SDConversionDiagnostic>;
+/** Existing Markdown adapters may continue returning base diagnostics. */
+export interface SDMarkdownToFragmentResult extends SDContentToFragmentResult<SDDiagnostic> {
 }

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

@@ -74,6 +74,8 @@ export interface SDTableCell {
     props?: SDCellProps;
     colSpan?: number;
     rowSpan?: number;
+    /** Marks a semantic table header cell. */
+    header?: boolean;
     content: SDContentNode[];
 }
 export interface SDTable extends SDNodeBase {
@@ -164,6 +166,12 @@ export interface SDBreak extends SDNodeBase {
         type: 'page' | 'column';
     };
 }
+/** A semantic horizontal rule; the destination chooses its durable representation. */
+export interface SDHorizontalRule {
+    id?: string;
+    kind: 'horizontalRule';
+    horizontalRule: Record<string, never>;
+}
 export interface SDSectionBreak extends SDNodeBase {
     kind: 'sectionBreak';
     sectionBreak: {
@@ -371,5 +379,5 @@ export interface SDExtInlineNode extends SDNodeBase {
     kind: `ext.${string}`;
     [key: string]: unknown;
 }
-export type SDContentNode = SDParagraph | SDHeading | SDList | SDTable | SDToc | SDDocumentIndex | SDBibliography | SDTableOfAuthorities | SDBreak | SDSectionBreak | SDSectPr | SDImage | SDDrawing | SDSdt | SDCustomXml | SDAltChunk | SDMath | SDField | SDExtContentNode;
+export type SDContentNode = SDParagraph | SDHeading | SDList | SDTable | SDToc | SDDocumentIndex | SDBibliography | SDTableOfAuthorities | SDBreak | SDHorizontalRule | SDSectionBreak | SDSectPr | SDImage | SDDrawing | SDSdt | SDCustomXml | SDAltChunk | SDMath | SDField | SDExtContentNode;
 export type SDInlineNode = SDRun | SDHyperlink | SDCrossRef | SDIndexEntry | SDSequenceField | SDCitation | SDAuthorityEntry | SDTocEntry | SDImage | SDDrawing | SDSdt | SDCustomXml | SDMath | SDField | SDTab | SDLineBreak | SDFootnoteRef | SDEndnoteRef | SDExtInlineNode;

package/dist/document-api/src/types/structural-input.d.ts

@@ -2,7 +2,7 @@ import { BlockNodeAddress } from './base.js';
 import { SelectionTarget } from './address.js';
 import { SDFragment } from './fragment.js';
 import { Placement, NestingPolicy } from './placement.js';
-import { StoryLocator } from './story.types.js';
+import { BodyStoryLocator, StoryLocator } from './story.types.js';
 /** Structural shape for the insert operation. */
 export interface SDInsertInput {
     /** Optional insertion target. When omitted, inserts at the end of the document. */
@@ -27,14 +27,29 @@ type StructuralReplaceLocator = {
     ref: string;
     /** Target to replace. BlockNodeAddress replaces the entire block; SelectionTarget replaces a contiguous selection. */
     target?: undefined;
+} | {
+    /** Replace the complete main body while preserving the destination DOCX package. */
+    target: BodyStoryLocator;
+    ref?: undefined;
 };
-/** Structural shape for the replace operation. */
-export type SDReplaceInput = StructuralReplaceLocator & {
+type StructuralReplaceContent = {
     /** Structural content to replace with. */
     content: SDFragment;
+};
+/** Structural shape for the replace operation. */
+export type SDReplaceInput = (Exclude<StructuralReplaceLocator, {
+    target: BodyStoryLocator;
+}> & StructuralReplaceContent & {
     /** Target a specific document story (body, header, footer, footnote, endnote). */
     in?: StoryLocator;
     /** Nesting policy. Defaults to { tables: 'forbid' }. */
     nestingPolicy?: NestingPolicy;
+}) | {
+    /** Replace the complete main body while preserving the destination DOCX package. */
+    target: BodyStoryLocator;
+    content: SDFragment;
+    ref?: never;
+    in?: never;
+    nestingPolicy?: never;
 };
 export {};

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

@@ -66,7 +66,7 @@ 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;
-    /** Structured replace for SDFragment content. Returns SDMutationReceipt. */
+    /** Structured replace for SDFragment or markdown/html content. Returns SDMutationReceipt. */
     replaceStructured(input: ReplaceInput, options?: MutationOptions): SDMutationReceipt;
 }
 export declare function normalizeMutationOptions(options?: MutationOptions): MutationOptions;

package/dist/layout-engine/painters/dom/src/index.d.ts

@@ -3,6 +3,8 @@ import { PageStyles } from './styles.js';
 import { PositionValidationOptions, PositionValidationSummary } from './pm-position-validation.js';
 import { DomPainterInput, PageDecorationProvider, PaintSnapshot, PositionMapping, FlowMode } from './renderer.js';
 import { DomPainterPersistentPageInput } from './persistent-page-surface.js';
+export { createWebFlowPainter, ensureWebFlowStyles, WEB_FLOW_CLASS_NAMES } from './web-flow/index.js';
+export type { WebFlowAppliedPaint, WebFlowDomBinding, WebFlowPaintCommand, WebFlowPaintItem, WebFlowPaintSnapshot, WebFlowPaintTransaction, WebFlowPainterHandle, WebFlowPainterOptions, WebFlowPaintWorkSummary, WebFlowStableDomKey, } from './web-flow/index.js';
 export { DOM_CLASS_NAMES } from './constants.js';
 export type { DomClassName } from './constants.js';
 export { ensureDocumentSurfaceStyles } from './styles.js';

package/dist/layout-engine/painters/dom/src/web-flow/index.d.ts

@@ -0,0 +1,3 @@
+export { createWebFlowPainter } from './painter.js';
+export { ensureWebFlowStyles, WEB_FLOW_CLASS_NAMES } from './styles.js';
+export type { WebFlowAppliedPaint, WebFlowDomBinding, WebFlowPaintCommand, WebFlowPaintItem, WebFlowPaintSnapshot, WebFlowPaintTransaction, WebFlowPainterHandle, WebFlowPainterOptions, WebFlowPaintWorkSummary, WebFlowStableDomKey, } from './types.js';

package/dist/layout-engine/painters/dom/src/web-flow/painter.d.ts

@@ -0,0 +1,2 @@
+import { WebFlowPainterHandle, WebFlowPainterOptions } from './types.js';
+export declare function createWebFlowPainter(mount: HTMLElement, options?: WebFlowPainterOptions): WebFlowPainterHandle;

package/dist/layout-engine/painters/dom/src/web-flow/render.d.ts

@@ -0,0 +1,8 @@
+import { FlowBlock } from '../../../../contracts/src/index.js';
+import { WebFlowPaintItem, WebFlowPainterOptions } from './types.js';
+export declare function doesWebFlowBlockProduceDom(block: FlowBlock): boolean;
+export declare function renderWebFlowItem(item: WebFlowPaintItem, doc: Document, options: WebFlowPainterOptions): HTMLElement | null;
+/** Identity-only signature for deciding whether a retained node needs dataset rebasing. */
+export declare function webFlowItemIdentityFingerprint(item: WebFlowPaintItem): string;
+/** Rebase canonical identity datasets without replacing an unchanged retained node. */
+export declare function rebaseWebFlowItemNode(node: HTMLElement, previous: WebFlowPaintItem, next: WebFlowPaintItem): () => void;

package/dist/layout-engine/painters/dom/src/web-flow/styles.d.ts

@@ -0,0 +1,10 @@
+export declare const WEB_FLOW_CLASS_NAMES: {
+    readonly root: "superdoc-web-flow";
+    readonly block: "superdoc-web-flow-block";
+    readonly paragraph: "superdoc-web-flow-paragraph";
+    readonly run: "superdoc-web-flow-run";
+    readonly listMarker: "superdoc-web-flow-list-marker";
+    readonly table: "superdoc-web-flow-table";
+    readonly diagnostic: "superdoc-web-flow-diagnostic";
+};
+export declare function ensureWebFlowStyles(doc: Document): void;

package/dist/layout-engine/painters/dom/src/web-flow/types.d.ts

@@ -0,0 +1,77 @@
+import { FlowBlock, LayoutSourceIdentity } from '../../../../contracts/src/index.js';
+/** Opaque adapter-issued identity. The painter never derives this value from DOM or block ids. */
+export type WebFlowStableDomKey = string;
+export interface WebFlowPaintItem {
+    readonly stableDomKey: WebFlowStableDomKey;
+    readonly renderFingerprint: string;
+    readonly block: FlowBlock;
+    readonly layoutEpoch?: number;
+    readonly layoutIdentities?: readonly LayoutSourceIdentity[];
+    readonly editable?: boolean;
+}
+export type WebFlowPaintCommand = {
+    readonly kind: 'replace-all';
+    readonly epoch: number;
+    readonly items: readonly WebFlowPaintItem[];
+} | {
+    readonly kind: 'splice';
+    readonly expectedBaseEpoch: number;
+    readonly epoch: number;
+    readonly storyKey: string;
+    readonly expectedRemovedKeys: readonly WebFlowStableDomKey[];
+    readonly expectedLeftKey: WebFlowStableDomKey | null;
+    readonly expectedRightKey: WebFlowStableDomKey | null;
+    readonly items: readonly WebFlowPaintItem[];
+    /** Identity-only updates for retained nodes downstream of a structural splice. */
+    readonly retainedRebases?: readonly WebFlowPaintItem[];
+};
+export interface WebFlowPaintWorkSummary {
+    readonly kind: WebFlowPaintCommand['kind'];
+    readonly retainedNodes: number;
+    readonly createdNodes: number;
+    readonly removedNodes: number;
+    readonly rebasedNodes: number;
+    readonly touchedItems: number;
+}
+export interface WebFlowDomBinding {
+    readonly key: WebFlowStableDomKey;
+    readonly renderFingerprint: string;
+    readonly blockId: string;
+    readonly node: HTMLElement;
+}
+export interface WebFlowPaintSnapshot {
+    readonly epoch: number | null;
+    readonly version: number;
+    readonly bindings: readonly WebFlowDomBinding[];
+}
+export interface WebFlowAppliedPaint {
+    readonly work: WebFlowPaintWorkSummary;
+    /** Bindings directly owned by this command; localized splices never scan the retained root. */
+    readonly touchedBindings: readonly WebFlowDomBinding[];
+    /** Bindings whose DOM node or retained identity changed in this command. */
+    readonly changedBindings: readonly WebFlowDomBinding[];
+}
+export interface WebFlowPaintTransaction {
+    readonly command: WebFlowPaintCommand;
+    /** Installs the candidate synchronously. The caller must then finalize or roll it back. */
+    apply(): WebFlowAppliedPaint;
+    /** Publishes the applied state and releases the rollback journal. */
+    finalize(): WebFlowAppliedPaint;
+    /** Restores the exact pre-apply DOM and retained state. */
+    rollback(): void;
+}
+export interface WebFlowPainterHandle {
+    prepare(command: WebFlowPaintCommand): WebFlowPaintTransaction;
+    snapshot(): WebFlowPaintSnapshot;
+    /** Rebuilds the last committed derived DOM after an externally owned mutation. */
+    restoreCommittedDomAfterUnownedMutation(): WebFlowPaintSnapshot;
+    dispose(): void;
+}
+export interface WebFlowPainterOptions {
+    readonly resolvePhysical?: (cssFontFamily: string, face: {
+        weight: '400' | '700';
+        style: 'normal' | 'italic';
+    }) => string;
+    /** Fires synchronously when the mutation observer first detects unowned DOM. */
+    readonly onUnownedMutation?: (kind: 'text' | 'dom') => void;
+}

package/dist/public/ui-react.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-CwCvqMOa.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-C44xPZxz.cjs");
 let react = require("react");
 //#region src/public/ui/react.ts
 /**

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

@@ -1,4 +1,4 @@
-import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-DCjm-_Xo.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-BTNVc3UD.es.js";
 import { createContext, createElement, useCallback, useContext, useEffect, useRef, useState } from "react";
 //#region src/public/ui/react.ts
 /**