superdoc 2.20.1-next.9 → 2.21.0-next.2

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" | "insert" | "delete" | "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" | "tables.moveColumn" | "format.bold" | "format.strike" | "format.color" | "format.rtl" | "format.cs" | "format.shading" | "format.fontFamily" | "format.lang" | "format.fontSize" | "format.fontSizeCs" | "format.highlight" | "format.italic" | "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" | "get" | "getNode" | "getNodeById" | "getText" | "getMarkdown" | "getHtml" | "markdownToFragment" | "htmlToFragment" | "extract" | "clearContent" | "formatRange" | "blocks.findText" | "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" | "selection.extractOoxml" | "mutations.preview" | "mutations.apply" | "plan.execute" | "capabilities.get" | "capabilities.resolve" | "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" | "headerFooters.pageNumbers.get" | "headerFooters.pageNumbers.insert" | "headerFooters.pageNumbers.set" | "headerFooters.pageNumbers.remove" | "watermarks.apply" | "watermarks.list" | "watermarks.insert" | "watermarks.replace" | "watermarks.remove" | "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" | "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" | "tables.moveColumn" | "format.bold" | "format.strike" | "format.color" | "format.position" | "format.rtl" | "format.cs" | "format.shading" | "format.fontFamily" | "format.lang" | "format.fontSize" | "format.fontSizeCs" | "format.highlight" | "format.italic" | "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.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" | "get" | "getNode" | "getNodeById" | "getText" | "getMarkdown" | "getHtml" | "markdownToFragment" | "htmlToFragment" | "extract" | "clearContent" | "formatRange" | "blocks.findText" | "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" | "selection.extractOoxml" | "mutations.preview" | "mutations.apply" | "plan.execute" | "capabilities.get" | "capabilities.resolve" | "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" | "headerFooters.pageNumbers.get" | "headerFooters.pageNumbers.insert" | "headerFooters.pageNumbers.set" | "headerFooters.pageNumbers.remove" | "watermarks.apply" | "watermarks.list" | "watermarks.insert" | "watermarks.replace" | "watermarks.remove" | "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

@@ -3517,6 +3517,9 @@ export declare const OPERATION_DEFINITIONS: {
     readonly "format.color": OperationDefinitionEntry & {
         memberPath: "format.color";
     };
+    readonly "format.position": OperationDefinitionEntry & {
+        memberPath: "format.position";
+    };
     readonly "format.rtl": OperationDefinitionEntry & {
         memberPath: "format.rtl";
     };
@@ -3586,9 +3589,6 @@ export declare const OPERATION_DEFINITIONS: {
     readonly "format.vertAlign": OperationDefinitionEntry & {
         memberPath: "format.vertAlign";
     };
-    readonly "format.position": OperationDefinitionEntry & {
-        memberPath: "format.position";
-    };
     readonly "format.bCs": OperationDefinitionEntry & {
         memberPath: "format.bCs";
     };

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

@@ -39,15 +39,19 @@ export interface ResolveRangeInput {
 export interface RangeBlockPreview {
     nodeId: string;
     nodeType: BlockNodeType;
+    /** Block text clipped to 200 characters. */
     textPreview: string;
 }
 /** Preview metadata for the resolved range. */
 export interface RangePreview {
-    /** Concatenated text content across the range (truncated if large). */
+    /**
+     * Concatenated text content across the range.
+     * Truncated above 2000 characters; see `truncated`.
+     */
     text: string;
-    /** Whether the text was truncated. */
+    /** Whether `text` was truncated above the 2000-character budget. */
     truncated: boolean;
-    /** Per-block preview entries in document order. */
+    /** Per-block preview entries in document order (each textPreview capped at 200 characters). */
     blocks: RangeBlockPreview[];
 }
 export interface ResolveRangeOutput {

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

@@ -1,5 +1,6 @@
 import { TextAddress } from './address.js';
 import { BlockNodeAddress } from './base.js';
+import { ResolvedHandle } from './discovery.js';
 import { ReceiptFailure, ReceiptInsert } from './receipt.js';
 import { StoryLocator } from './story.types.js';
 export type ParagraphCreateLocation = {
@@ -18,13 +19,57 @@ export interface CreateParagraphInput {
     in?: StoryLocator;
     at?: ParagraphCreateLocation;
     text?: string;
+    /**
+     * Explicit paragraph style id (e.g. `'BodyText'`) to apply instead of the
+     * document's default paragraph style. Neighboring styles and direct
+     * formatting are not inherited. An unknown style id fails
+     * with `INVALID_INPUT` and does not mutate the document.
+     */
+    styleId?: string;
 }
 export interface CreateParagraphSuccessResult {
     success: true;
     paragraph: BlockNodeAddress;
     insertionPoint: TextAddress;
     trackedChangeRefs?: ReceiptInsert[];
-    /** Stable ref handle for the created block. Pass directly to superdoc_format or superdoc_edit without searching. */
+    /**
+     * Mutation-ready handle for the created paragraph. `handle.ref` is an
+     * opaque, self-contained ref (the same shape `ranges.resolve` produces) —
+     * pass it directly to `format.apply`'s `ref` without needing to also pass
+     * `in`/story context, even for a header/footer paragraph. It is pinned to
+     * `evaluatedRevision` (`refStability: 'ephemeral'`), so it is valid for
+     * the immediate next mutation call only; chaining a second one after that
+     * needs a fresh ref from a discovery read (e.g. `blocks.list`,
+     * `query.match`). `paragraph.nodeId` remains stable across revisions for
+     * non-ref addressing (e.g. `{ target: { kind: 'block', nodeType, nodeId } }`).
+     *
+     * With `options.dryRun: true`, nothing was committed, so there is no real
+     * block to reference: `handle.ref` is the literal placeholder `'(dry-run)'`
+     * and `paragraph.nodeId`/`insertionPoint.blockId` are too. Do not pass a
+     * dry-run `handle.ref` to `format.apply` or any other mutation — it does
+     * not resolve and the call fails with `INVALID_TARGET`.
+     *
+     * With no `text` (an empty paragraph), `handle.ref` spans a zero-length
+     * range. This is not specific to create — `format.apply`'s "inline" action
+     * cannot format zero-length text in general (there are no characters to
+     * carry run properties), so chaining `handle.ref` into it fails with
+     * `INVALID_TARGET` for an empty create the same way it would for any other
+     * zero-length selection. Use paragraph-level actions with `paragraph` (its
+     * `nodeId`) instead, e.g. `styles.paragraph.setStyle` or
+     * `format.paragraph.setIndentation`, which target the whole block and do
+     * not need a non-empty text range.
+     */
+    handle: ResolvedHandle;
+    /**
+     * Document revision immediately after this create committed. Pass as
+     * `expectedRevision` on the immediate next mutation call to chain without
+     * a `REVISION_MISMATCH` (SD-4886).
+     */
+    evaluatedRevision: string;
+    /**
+     * @deprecated Use `handle.ref` instead. Kept as an alias of `handle.ref`
+     * for backward compatibility with existing callers of this field.
+     */
     ref?: string;
 }
 export interface CreateParagraphFailureResult {
@@ -40,13 +85,57 @@ export interface CreateHeadingInput {
     level: HeadingLevel;
     at?: HeadingCreateLocation;
     text?: string;
+    /**
+     * Explicit paragraph style id to apply instead of the `Heading{level}`
+     * style normally derived from `level`. `level` still controls numbering
+     * suppression regardless of this override. An unknown style id fails with
+     * `INVALID_INPUT` and does not mutate the document.
+     */
+    styleId?: string;
 }
 export interface CreateHeadingSuccessResult {
     success: true;
     heading: BlockNodeAddress;
     insertionPoint: TextAddress;
     trackedChangeRefs?: ReceiptInsert[];
-    /** Stable ref handle for the created block. Pass directly to superdoc_format or superdoc_edit without searching. */
+    /**
+     * Mutation-ready handle for the created heading. `handle.ref` is an
+     * opaque, self-contained ref (the same shape `ranges.resolve` produces) —
+     * pass it directly to `format.apply`'s `ref` without needing to also pass
+     * `in`/story context, even for a header/footer heading. It is pinned to
+     * `evaluatedRevision` (`refStability: 'ephemeral'`), so it is valid for
+     * the immediate next mutation call only; chaining a second one after that
+     * needs a fresh ref from a discovery read (e.g. `blocks.list`,
+     * `query.match`). `heading.nodeId` remains stable across revisions for
+     * non-ref addressing (e.g. `{ target: { kind: 'block', nodeType, nodeId } }`).
+     *
+     * With `options.dryRun: true`, nothing was committed, so there is no real
+     * block to reference: `handle.ref` is the literal placeholder `'(dry-run)'`
+     * and `heading.nodeId`/`insertionPoint.blockId` are too. Do not pass a
+     * dry-run `handle.ref` to `format.apply` or any other mutation — it does
+     * not resolve and the call fails with `INVALID_TARGET`.
+     *
+     * With no `text` (an empty heading), `handle.ref` spans a zero-length
+     * range. This is not specific to create — `format.apply`'s "inline" action
+     * cannot format zero-length text in general (there are no characters to
+     * carry run properties), so chaining `handle.ref` into it fails with
+     * `INVALID_TARGET` for an empty create the same way it would for any other
+     * zero-length selection. Use paragraph-level actions with `heading` (its
+     * `nodeId`) instead, e.g. `styles.paragraph.setStyle` or
+     * `format.paragraph.setIndentation`, which target the whole block and do
+     * not need a non-empty text range.
+     */
+    handle: ResolvedHandle;
+    /**
+     * Document revision immediately after this create committed. Pass as
+     * `expectedRevision` on the immediate next mutation call to chain without
+     * a `REVISION_MISMATCH` (SD-4886).
+     */
+    evaluatedRevision: string;
+    /**
+     * @deprecated Use `handle.ref` instead. Kept as an alias of `handle.ref`
+     * for backward compatibility with existing callers of this field.
+     */
     ref?: string;
 }
 export interface CreateHeadingFailureResult {

package/dist/layout-engine/contracts/src/index.d.ts

@@ -1272,6 +1272,33 @@ export type ShapeGroupVectorChild = {
         customGeometry?: CustomGeometryData;
         shapeId?: string;
         shapeName?: string;
+        /**
+         * SD-5244: canonical textbox story identity for an in-scope group
+         * child (single-level, unrotated/unflipped group and child). Present
+         * only when the child was successfully bound to an editor-core
+         * textbox story; absent otherwise (see `textboxStaticReason`).
+         */
+        textboxId?: string;
+        /**
+         * Canonical block content for the bound textbox story. Loosely typed
+         * like `DrawingBlockBase.attrs`/`TextboxDrawing`'s own informal
+         * `textboxBinding` attrs entry elsewhere in this file — group
+         * children intentionally reuse that same "opaque round-trip" shape
+         * rather than a dedicated type, so no new cross-package dependency on
+         * v2-layout-adapter's `TextboxProjectionBinding` is introduced here.
+         */
+        contentBlocks?: TextboxContentBlock[];
+        /** Opaque kernel binding round-tripped for the story registration step; not consumed at this layer. */
+        textboxBinding?: unknown;
+        /** Opaque content-block identities round-tripped for the story registration step; not consumed at this layer. */
+        textboxContentBlockIdentities?: unknown;
+        /**
+         * Present iff this child could not be (or was not) bound to an
+         * editable textbox story — e.g. nested group, rotated/flipped group
+         * or child, or a canonical binding was unavailable. Drives the
+         * fail-closed rendering and clean-rejection paths.
+         */
+        textboxStaticReason?: string;
     };
 };
 export type ShapeGroupImageChild = {
@@ -2342,6 +2369,14 @@ export type DrawingMeasure = {
     groupTransform?: ShapeGroupTransform;
     /** Canonical block measurements for textbox content, when the drawing owns a textbox story. */
     contentMeasures?: TextboxContentMeasure[];
+    /**
+     * SD-5244: canonical block measurements for editable shape-group children's
+     * textbox content, keyed by each child's `textboxId`. Kept as a `Measure`/
+     * `Layout`-side artifact — like `contentMeasures` above — rather than on
+     * `ShapeGroupVectorChild.attrs`/`block.shapes`, which `layout-bridge`'s
+     * cache hash serializes in full.
+     */
+    groupChildContentMeasures?: Record<string, TextboxContentMeasure[]>;
 };
 export type TableCellMeasure = {
     /** Multi-block cell measurements (new feature) */
@@ -2715,6 +2750,8 @@ export type DrawingFragment = {
     /** V2 textbox story id for DrawingML textbox content painted inside this drawing. */
     textboxId?: string;
     contentMeasures?: TextboxContentMeasure[];
+    /** SD-5244: see `DrawingMeasure.groupChildContentMeasures` — carried through onto the painted fragment for a `shapeGroup` drawing. */
+    groupChildContentMeasures?: Record<string, TextboxContentMeasure[]>;
     pmStart?: number;
     pmEnd?: number;
     sourceAnchor?: SourceAnchor;

package/dist/layout-engine/contracts/src/segment-geometry.d.ts

@@ -43,10 +43,11 @@ export type NeutralSegmentGeometry = {
  */
 export type NeutralLineGeometryFlags = {
     /**
-     * Line participates in justified alignment. Segment `x`/`width` are the
-     * natural (pre-justify) measured values; the painter distributes slack across
-     * spaces at paint time, so downstream caret math past the first segment is
-     * approximate. Paired with a `approximate-justify` diagnostic on the fragment.
+     * Line participates in justified alignment. When the line actually stretches
+     * (not the true last line of its paragraph, not tab-aligned), segment
+     * `x`/`width` already carry the exact painter-consistent slack — the same
+     * shared word-spacing / inter-character distribution the painter applies at
+     * paint time — so downstream caret math is exact, not approximate.
      */
     justified?: boolean;
     /** Line uses explicit tab/segment positioning (at least one segment has an explicit x). */
@@ -75,7 +76,15 @@ export type NeutralLineGeometry = {
     lineHeight: number;
     /** Container-space x where line content starts after indent + alignment (px). */
     contentLeft: number;
-    /** Measured natural content width of the line (px). */
+    /**
+     * Content width of the line (px), matching what the painter actually
+     * renders: the natural measured width for an unstretched line, or the full
+     * available (post-slack) width for a justified line that is actually
+     * stretched (see {@link NeutralLineGeometryFlags.justified}). Consumers use
+     * this both as the coordinate-space bound for a point on the line and as
+     * the available width fed back into justify math, so it must track the
+     * rendered span, not always the natural one.
+     */
     contentWidth: number;
     /** Resolved inline direction for the line. */
     direction: NeutralTextDirection;
@@ -128,7 +137,14 @@ export type NeutralGeometryDiagnostic =
  | {
     code: 'unsupported-complex-bidi';
 }
-/** Fragment has justified lines; segment x past the first is pre-justify (approximate). */
+/**
+ * Reserved for a justified-line case whose exact position cannot be proven
+ * (mirrors the fail-closed posture of the other diagnostics here). LTR
+ * justify is resolved exactly (see {@link NeutralLineGeometryFlags.justified})
+ * and RTL+justify fails closed with `unsupported-direction` before reaching
+ * per-line geometry, so no producer currently emits this code — kept for
+ * schema stability in case a future unresolved variant needs it.
+ */
  | {
     code: 'approximate-justify';
 }

package/dist/layout-engine/layout-bridge/src/line-justify-adjustment.d.ts

@@ -0,0 +1,106 @@
+import { FlowBlock, Line } from '../../contracts/src/index.js';
+/**
+ * Shared, canvas-independent justify-adjustment calculation.
+ *
+ * Single source of truth for the per-line justify slack (word-spacing and
+ * inter-character distribution) so painter measurement, caret/hit-test
+ * geometry, and the editor-neutral segment-geometry substrate all agree on
+ * the same numbers. Depends only on `@superdoc/contracts` line/run data —
+ * no Canvas context — so it is safe to call from geometry producers that run
+ * without a live DOM.
+ */
+/**
+ * Represents the justify alignment adjustment applied to a line.
+ *
+ * When text is justified, the layout engine distributes extra space (slack)
+ * evenly across all space characters in the line. This type captures both
+ * the per-space adjustment amount and the total number of spaces, which are
+ * used by text measurement functions to accurately calculate character
+ * positions in justified text.
+ *
+ * @property extraPerSpace - Additional pixels to add after each space character (can be 0 for non-justified text)
+ * @property totalSpaces - Total count of space characters in the line (used for validation and debugging)
+ */
+export type JustifyAdjustment = {
+    extraPerSpace: number;
+    totalSpaces: number;
+    interCharacterSpacing: number;
+    interCharacterBoundaries: readonly number[];
+};
+export type GetJustifyAdjustmentParams = {
+    block: FlowBlock;
+    line: Line;
+    availableWidthOverride?: number;
+    alignmentOverride?: string;
+    isLastLineOfParagraph?: boolean;
+    paragraphEndsWithLineBreak?: boolean;
+    skipJustifyOverride?: boolean;
+};
+/**
+ * Counts the number of space characters in a text string.
+ *
+ * Only counts spaces that participate in CSS word-spacing behavior (regular
+ * space and non-breaking space). This is used for justify alignment
+ * calculations where extra width needs to be distributed proportionally
+ * across spaces.
+ *
+ * @param text - The text string to analyze
+ * @returns The count of space characters (regular space U+0020 and non-breaking space U+00A0)
+ *
+ * @example
+ * ```typescript
+ * countSpaces("Hello World");  // Returns: 1
+ * countSpaces("A B C");        // Returns: 2
+ * countSpaces("No-spaces");    // Returns: 0
+ * ```
+ */
+export declare const countSpaces: (text: string) => number;
+/**
+ * Computes the per-space expansion applied when a line is justified.
+ *
+ * Uses shared justify utilities to ensure consistency with the painter's
+ * justify logic, which distributes slack (extra horizontal space) evenly
+ * across all space characters using CSS word-spacing.
+ *
+ * Algorithm:
+ * 1. Use shouldApplyJustify() to determine if justify should be applied (including last-line detection)
+ * 2. Count all space characters (or use pre-computed line.spaceCount)
+ * 3. Use calculateJustifySpacing() to compute per-space adjustment
+ * 4. Support negative slack for compressed lines (naturalWidth > availableWidth)
+ *
+ * Edge Cases:
+ * - Non-justify alignment: Returns zero adjustment
+ * - Last line of paragraph: Returns zero adjustment (unless paragraph ends with soft break)
+ * - No spaces: Returns zero adjustment (prevents division by zero)
+ * - Lines with author-defined tab stops: Returns zero adjustment
+ * - Compressed lines: Returns negative adjustment (naturalWidth used for slack calculation)
+ * - Empty runs array: Returns zero adjustment
+ *
+ * @param params - Named parameters for justify adjustment.
+ * @param params.block - The paragraph block containing the line
+ * @param params.line - The line to compute justify adjustment for
+ * @param params.availableWidthOverride - The available width for content (fragment width minus paragraph indents).
+ *   Must match what the painter uses to ensure consistent justify spacing. If not provided,
+ *   falls back to line.maxWidth or line.width.
+ * @param params.alignmentOverride - Optional alignment override (defaults to block.attrs.alignment)
+ * @param params.isLastLineOfParagraph - Whether this is the last line of the paragraph.
+ *   If not provided, auto-derived from block/line: `line.toRun >= block.runs.length - 1`.
+ *   Auto-derivation ensures measurement matches rendering. Returns false for empty runs arrays.
+ * @param params.paragraphEndsWithLineBreak - Whether the paragraph ends with a soft break (Shift+Enter).
+ *   If not provided, auto-derived: `lastRun?.kind === 'lineBreak'`.
+ *   Auto-derivation ensures measurement matches rendering. Returns false for empty runs arrays.
+ * @param params.skipJustifyOverride - Explicit override to skip justify
+ * @returns Object containing extraPerSpace (pixels to add after each space) and totalSpaces
+ *
+ * @example
+ * ```typescript
+ * // Line with 200px width in 250px available space, 5 spaces
+ * const adj = getJustifyAdjustment({ block, line, availableWidthOverride: 250, isLastLineOfParagraph: false });
+ * // Returns: { extraPerSpace: 10, totalSpaces: 5 }  (50px slack / 5 spaces)
+ *
+ * // Last line of paragraph (no soft break)
+ * const adj = getJustifyAdjustment({ block, line, availableWidthOverride: 250, isLastLineOfParagraph: true });
+ * // Returns: { extraPerSpace: 0, totalSpaces: 5 }  (last line not justified)
+ * ```
+ */
+export declare const getJustifyAdjustment: ({ block, line, availableWidthOverride, alignmentOverride, isLastLineOfParagraph, paragraphEndsWithLineBreak, skipJustifyOverride, }: GetJustifyAdjustmentParams) => JustifyAdjustment;

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-j8Qm5SYa.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-yKesgn9b.cjs");
 const require_slice_source = require("../chunks/slice-source-CFaqq0Vo.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-Cfwszc3b.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-0CZTlOvl.es.js";
 import { t as toSliceSource } from "../chunks/slice-source-gfOhG2MW.es.js";
 import { createContext, createElement, useCallback, useContext, useEffect, useRef, useState } from "react";
 //#region src/public/ui/react.ts

package/dist/public/ui-vue.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-j8Qm5SYa.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-yKesgn9b.cjs");
 const require_slice_source = require("../chunks/slice-source-CFaqq0Vo.cjs");
 let superdoc_entry_vue = require("vue");
 //#region src/public/ui/vue.ts

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

@@ -1,4 +1,4 @@
-import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-Cfwszc3b.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-0CZTlOvl.es.js";
 import { t as toSliceSource } from "../chunks/slice-source-gfOhG2MW.es.js";
 import { computed, inject, onScopeDispose, provide, shallowRef, toRaw, toValue, watch } from "vue";
 //#region src/public/ui/vue.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-j8Qm5SYa.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-yKesgn9b.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 { a as BUILT_IN_COMMAND_IDS, t as createSuperDocUI, u as shallowEqual } from "../chunks/create-super-doc-ui-Cfwszc3b.es.js";
+import { a as BUILT_IN_COMMAND_IDS, t as createSuperDocUI, u as shallowEqual } from "../chunks/create-super-doc-ui-0CZTlOvl.es.js";
 export { BUILT_IN_COMMAND_IDS, createSuperDocUI, shallowEqual };