superdoc 2.7.0-next.1 → 2.7.0-next.11

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

@@ -0,0 +1,129 @@
+import { BlockNodeAddress, BlockNodeType } from './base.js';
+import { Range, SelectionTarget, TextTarget } from './address.js';
+import { StoryLocator } from './story.types.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"];
+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;
+    /** Fidelity outcome derived from the complete projection diagnostics. */
+    outcome: SDHtmlMarkdownOutcome;
+    reviewMode: SDProjectionReviewMode;
+    evaluatedRevision: string;
+    story: StoryLocator;
+    scope: SDResolvedProjectionScope;
+    lossy: boolean;
+    diagnostics: SDProjectionDiagnostic[];
+    blocks: SDProjectionBlockMapEntry[];
+    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/index.d.ts

@@ -29,3 +29,4 @@ 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;
     };
@@ -261,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

@@ -1,13 +1,16 @@
 import { BlockNodeAddress } from './base.js';
 import { SelectionTarget, TextAddress } from './address.js';
 import { ReceiptEffects, ReceiptSuccess, TextMutationRange } from './receipt.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';
+import { BodyStoryLocator } from './story.types.js';
+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;
     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,10 +18,13 @@ 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;
+    /** 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/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

@@ -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/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
 /**

package/dist/public/ui.cjs

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

package/dist/public/ui.es.js

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

package/dist/superdoc/src/composables/use-link-popover.d.ts

@@ -127,10 +127,9 @@ export type HyperlinkGetResult = {
 };
 /**
  * Result of `doc.bookmarks.get()` as read here (Document API `BookmarkInfo`).
- * `range.from.blockId` is the bookmark's `w14:paraId`, used to find/reveal
- * the target paragraph. `address.story` is populated for non-body
- * bookmarks (omitted for body) — used to scope this fix to body targets,
- * since `revealBodyTarget`/`pageIndexForBodyTarget` are body-only.
+ * `range.from.blockId` identifies the model paragraph sent to the viewport.
+ * `address.story` is populated for non-body bookmarks (omitted for body),
+ * which keeps anchor navigation scoped to body targets.
  */
 export type BookmarkGetResult = {
     address?: {
@@ -184,16 +183,6 @@ export type LinkPopoverDocumentApi = {
         }) => BookmarkGetResult | Promise<BookmarkGetResult | null | undefined> | null | undefined;
     } | null | undefined;
 };
-/**
- * Result of `activeEditor.pageMetrics.revealBodyTarget()` as read here
- * (`V2EditorHostRevealBodyTargetResult`). Only available in editing/
- * suggesting mode — the host rejects with `editing-not-mounted` in
- * viewing mode.
- */
-export type RevealBodyTargetResult = {
-    status?: "rejected" | "revealed" | undefined;
-    reason?: string | undefined;
-};
 /**
  * The `v2-link-click` payload the shell relays from the v2 host's
  * `onLinkClick` callback.

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

@@ -2543,7 +2543,11 @@ export type ViewLayout = 'print' | 'web';
  * Mirrors OOXML document view settings.
  */
 export interface ViewOptions {
-    /** Document view layout (OOXML ST_View compatible). */
+    /**
+     * Document view layout (OOXML ST_View compatible). In the browser editor,
+     * `'web'` selects the retained semantic DOM surface. Browser normal flow
+     * rewraps content as the editor container changes width.
+     */
     layout?: ViewLayout;
 }
 export interface ExportParams {
@@ -3378,6 +3382,11 @@ export interface Config {
     experimental?: {
         unifiedHistory?: boolean;
         v2Host?: boolean;
+        /**
+         * Temporary V2 web-surface rollout control. The value is snapshotted at
+         * mount and changing it requires a remount. This is not a stable renderer API.
+         */
+        v2WebSurface?: 'dense-control' | 'retained-dom';
         /**
          * Derived-invalidation deferral for direct single-paragraph edits (v2
          * engine only). Field display text settles off the keystroke path under
@@ -3605,10 +3614,8 @@ export interface Config {
      */
     workerStartupTimeoutMs?: number;
     /**
-     * Opt-in toggle for the layout engine. Auto-disabled when web layout is
-     * requested without `layoutEngineOptions.flowMode === 'semantic'`; the
-     * loader logs a warning and falls back to the legacy ProseMirror render
-     * path in that case.
+     * Compatibility toggle retained for existing configurations. V2 always
+     * uses the OOXML kernel; `viewOptions.layout` selects the mounted renderer.
      */
     useLayoutEngine?: boolean;
     /**

package/dist/superdoc/src/helpers/v2-review-mutation-impact.d.ts

@@ -2,9 +2,8 @@
  * 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.
  */
 export function getV2TrackedChangeMutationImpact(event: any): {
     allResolved?: any;

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';