superdoc 2.2.0 → 2.3.0

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

@@ -0,0 +1,453 @@
+import { BlockNodeAddress, NodeKind } from '../types/base.js';
+import { SelectionTarget } from '../types/address.js';
+import { SDFragment } from '../types/fragment.js';
+import { ReceiptFailure, ReceiptInsert } from '../types/receipt.js';
+/**
+ * Semantic SDT subtype derived from `w:sdtPr` children.
+ *
+ * `richText` covers both explicit `<w:richText/>` and the OOXML default for
+ * sdtPr with no type child (ECMA-376 §17.5.2.26: typeless SDT shall be of
+ * type richText). `unknown` means an unsupported or unrecognized type child.
+ */
+export type ContentControlType = 'text' | 'richText' | 'date' | 'checkbox' | 'comboBox' | 'dropDownList' | 'repeatingSection' | 'repeatingSectionItem' | 'group' | 'unknown';
+export declare const CONTENT_CONTROL_TYPES: readonly ["text", "richText", "date", "checkbox", "comboBox", "dropDownList", "repeatingSection", "repeatingSectionItem", "group", "unknown"];
+/** ECMA-376 `w:lock` modes. */
+export type LockMode = 'unlocked' | 'sdtLocked' | 'contentLocked' | 'sdtContentLocked';
+export declare const LOCK_MODES: readonly ["unlocked", "sdtLocked", "contentLocked", "sdtContentLocked"];
+/** Visual appearance of the content control wrapper in Word. */
+export type ContentControlAppearance = 'boundingBox' | 'tags' | 'hidden';
+export declare const CONTENT_CONTROL_APPEARANCES: readonly ["boundingBox", "tags", "hidden"];
+/** Symbol specification for checkbox checked/unchecked glyphs. */
+export interface ContentControlSymbol {
+    font: string;
+    char: string;
+}
+/** Choice list item (shared by comboBox and dropDownList). */
+export interface ContentControlListItem {
+    displayText: string;
+    value: string;
+}
+/** Data binding metadata from `w:dataBinding`. */
+export interface ContentControlBinding {
+    storeItemId: string;
+    xpath: string;
+    prefixMappings?: string;
+}
+export interface TextControlProperties {
+    multiline?: boolean;
+}
+export interface DateControlProperties {
+    dateFormat?: string;
+    dateLocale?: string;
+    storageFormat?: string;
+    calendar?: string;
+}
+export interface CheckboxControlProperties {
+    checked?: boolean;
+    checkedSymbol?: ContentControlSymbol;
+    uncheckedSymbol?: ContentControlSymbol;
+}
+export interface ChoiceControlProperties {
+    items?: ContentControlListItem[];
+    selectedValue?: string;
+}
+export interface RepeatingSectionControlProperties {
+    allowInsertDelete?: boolean;
+}
+export interface ContentControlProperties {
+    tag?: string;
+    alias?: string;
+    /**
+     * Visual chrome behavior (`<w15:appearance w15:val="…">`).
+     *
+     * Returned verbatim from the imported XML. When the source omits
+     * the element, this field is `undefined` — NOT silently set to
+     * `boundingBox`. Word's effective default when the element is
+     * absent is `boundingBox`, but consumers building UI on top of
+     * appearance (e.g. deciding whether to draw chrome) must apply
+     * that default themselves; the API does not fabricate it.
+     *
+     * Contract:
+     *   - `'boundingBox'` → explicit; show chrome
+     *   - `'tags'`        → explicit; show tag markers
+     *   - `'hidden'`      → explicit; render transparently
+     *   - `undefined`     → source XML omitted the element; treat as
+     *                       Word's effective default (`'boundingBox'`).
+     */
+    appearance?: ContentControlAppearance;
+    color?: string;
+    placeholder?: string;
+    showingPlaceholder?: boolean;
+    /**
+     * `<w:temporary/>` toggle (ECMA-376 §17.5.2.43).
+     *
+     * When enabled, Word treats the content control as temporary and may
+     * remove the SDT wrapper after the user edits/fills the control.
+     *
+     * Returned verbatim from the imported XML:
+     *   - `true`      → element present (`<w:temporary/>` or `w:val="true"`/`"1"`)
+     *   - `false`     → element present with `w:val="false"`/`"0"`
+     *   - `undefined` → element absent in source; treat as Word's
+     *                   effective default (`false`).
+     */
+    temporary?: boolean;
+    tabIndex?: number;
+    multiline?: boolean;
+    dateFormat?: string;
+    dateLocale?: string;
+    storageFormat?: string;
+    calendar?: string;
+    checked?: boolean;
+    checkedSymbol?: ContentControlSymbol;
+    uncheckedSymbol?: ContentControlSymbol;
+    items?: ContentControlListItem[];
+    selectedValue?: string;
+    allowInsertDelete?: boolean;
+}
+export interface ContentControlTarget {
+    kind: NodeKind;
+    nodeType: 'sdt';
+    nodeId: string;
+}
+export type ContentControlMoveDestination = ContentControlTarget | {
+    kind: 'documentStart';
+} | {
+    kind: 'documentEnd';
+} | {
+    kind: 'before';
+    target: ContentControlTarget;
+} | {
+    kind: 'after';
+    target: ContentControlTarget;
+}
+/**
+ * Drop the control at an arbitrary caret inside a paragraph (SD-3779). `target`
+ * addresses the destination paragraph and `offset` is a text-character offset
+ * within it (0 = paragraph start). Mirrors `ImageCreateLocation`'s `inParagraph`
+ * variant so drag-and-drop can land a content control anywhere in the body, not
+ * just relative to another SDT. Direct-mode only.
+ */
+ | {
+    kind: 'inParagraph';
+    target: BlockNodeAddress;
+    offset?: number;
+};
+/**
+ * Canonical content control info returned by all read/list operations.
+ * Replaces the old `SdtNodeInfo`.
+ */
+export interface ContentControlInfo {
+    nodeType: 'sdt';
+    kind: NodeKind;
+    id: string;
+    controlType: ContentControlType;
+    lockMode: LockMode;
+    properties: ContentControlProperties;
+    binding?: ContentControlBinding;
+    raw?: Record<string, unknown>;
+    target: ContentControlTarget;
+    selectionTarget?: SelectionTarget | null;
+    text?: string;
+}
+export interface ContentControlMutationSuccess {
+    success: true;
+    contentControl: ContentControlTarget;
+    updatedRef?: ContentControlTarget;
+    trackedChangeRefs?: ReceiptInsert[];
+}
+export interface ContentControlMutationFailure {
+    success: false;
+    failure: ReceiptFailure;
+}
+export type ContentControlMutationResult = ContentControlMutationSuccess | ContentControlMutationFailure;
+export interface ContentControlsListResult {
+    items: ContentControlInfo[];
+    total: number;
+}
+export interface ContentControlsPaginationOptions {
+    offset?: number;
+    limit?: number;
+}
+export interface CreateContentControlInput {
+    kind: NodeKind;
+    controlType?: ContentControlType;
+    target?: ContentControlTarget;
+    /**
+     * Text range to wrap in the new content control. Mutually exclusive with `target`.
+     * When `content` is also provided, it replaces the selected text inside the new SDT.
+     * When `content` is omitted, the existing text in the range becomes the SDT content.
+     */
+    at?: SelectionTarget;
+    tag?: string;
+    alias?: string;
+    lockMode?: LockMode;
+    content?: string;
+    /**
+     * Structured block preset authored from HTML. Supported only for block
+     * content controls. Mutually exclusive with `content` and `json`.
+     */
+    html?: string;
+    /**
+     * Structured block preset authored from SDFragment-compatible JSON. Legacy
+     * type-discriminated fragment shapes are validated at runtime too.
+     *
+     * Supported only for block content controls. Mutually exclusive with
+     * `content` and `html`.
+     */
+    json?: SDFragment | Record<string, unknown> | Array<Record<string, unknown>>;
+}
+export interface ContentControlsListQuery extends ContentControlsPaginationOptions {
+    controlType?: ContentControlType;
+    tag?: string;
+}
+export interface ContentControlsGetInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsListInRangeInput extends ContentControlsPaginationOptions {
+    startBlockId: string;
+    endBlockId: string;
+}
+export interface ContentControlsSelectByTagInput extends ContentControlsPaginationOptions {
+    tag: string;
+}
+export interface ContentControlsSelectByTitleInput extends ContentControlsPaginationOptions {
+    title: string;
+}
+export interface ContentControlsListChildrenInput extends ContentControlsPaginationOptions {
+    target: ContentControlTarget;
+}
+export interface ContentControlsGetParentInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsWrapInput {
+    kind: NodeKind;
+    target: ContentControlTarget;
+    tag?: string;
+    alias?: string;
+    lockMode?: LockMode;
+}
+export interface ContentControlsUnwrapInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsDeleteInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsCopyInput {
+    target: ContentControlTarget;
+    destination: ContentControlTarget;
+}
+export interface ContentControlsMoveInput {
+    target: ContentControlTarget;
+    destination: ContentControlMoveDestination;
+}
+export interface ContentControlsPatchInput {
+    target: ContentControlTarget;
+    alias?: string | null;
+    tag?: string | null;
+    appearance?: ContentControlAppearance | null;
+    color?: string | null;
+    placeholder?: string | null;
+    showingPlaceholder?: boolean;
+    temporary?: boolean;
+    tabIndex?: number | null;
+}
+export interface ContentControlsSetLockModeInput {
+    target: ContentControlTarget;
+    lockMode: LockMode;
+}
+export interface ContentControlsSetTypeInput {
+    target: ContentControlTarget;
+    controlType: ContentControlType;
+}
+export interface ContentControlsGetContentInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsGetContentResult {
+    content: string;
+    format: 'text' | 'html';
+}
+export interface ContentControlsReplaceContentInput {
+    target: ContentControlTarget;
+    content: string;
+    format?: 'text' | 'html';
+}
+export interface ContentControlsClearContentInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsAppendContentInput {
+    target: ContentControlTarget;
+    content: string;
+    format?: 'text' | 'html';
+}
+export interface ContentControlsPrependContentInput {
+    target: ContentControlTarget;
+    content: string;
+    format?: 'text' | 'html';
+}
+export interface ContentControlsInsertBeforeInput {
+    target: ContentControlTarget;
+    content: string;
+    format?: 'text' | 'html';
+}
+export interface ContentControlsInsertAfterInput {
+    target: ContentControlTarget;
+    content: string;
+    format?: 'text' | 'html';
+}
+export interface ContentControlsGetBindingInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsSetBindingInput {
+    target: ContentControlTarget;
+    storeItemId: string;
+    xpath: string;
+    prefixMappings?: string;
+}
+export interface ContentControlsClearBindingInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsGetRawPropertiesInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsGetRawPropertiesResult {
+    properties: Record<string, unknown>;
+}
+export type RawPatchOp = {
+    op: 'set';
+    name: string;
+    element: Record<string, unknown>;
+} | {
+    op: 'remove';
+    name: string;
+} | {
+    op: 'setAttr';
+    name: string;
+    attr: string;
+    value: string;
+} | {
+    op: 'removeAttr';
+    name: string;
+    attr: string;
+};
+export interface ContentControlsPatchRawPropertiesInput {
+    target: ContentControlTarget;
+    patches: RawPatchOp[];
+}
+export interface ContentControlsValidateWordCompatibilityInput {
+    target: ContentControlTarget;
+}
+export interface WordCompatibilityDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+}
+export interface ContentControlsValidateWordCompatibilityResult {
+    compatible: boolean;
+    diagnostics: WordCompatibilityDiagnostic[];
+}
+export interface ContentControlsNormalizeWordCompatibilityInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsNormalizeTagPayloadInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsTextSetMultilineInput {
+    target: ContentControlTarget;
+    multiline: boolean;
+}
+export interface ContentControlsTextSetValueInput {
+    target: ContentControlTarget;
+    value: string;
+}
+export interface ContentControlsTextClearValueInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsDateSetValueInput {
+    target: ContentControlTarget;
+    value: string;
+}
+export interface ContentControlsDateClearValueInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsDateSetDisplayFormatInput {
+    target: ContentControlTarget;
+    format: string;
+}
+export interface ContentControlsDateSetDisplayLocaleInput {
+    target: ContentControlTarget;
+    locale: string;
+}
+export interface ContentControlsDateSetStorageFormatInput {
+    target: ContentControlTarget;
+    format: string;
+}
+export interface ContentControlsDateSetCalendarInput {
+    target: ContentControlTarget;
+    calendar: string;
+}
+export interface ContentControlsCheckboxGetStateInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsCheckboxGetStateResult {
+    checked: boolean;
+}
+export interface ContentControlsCheckboxSetStateInput {
+    target: ContentControlTarget;
+    checked: boolean;
+}
+export interface ContentControlsCheckboxToggleInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsCheckboxSetSymbolPairInput {
+    target: ContentControlTarget;
+    checkedSymbol: ContentControlSymbol;
+    uncheckedSymbol: ContentControlSymbol;
+}
+export interface ContentControlsChoiceListGetItemsInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsChoiceListGetItemsResult {
+    items: ContentControlListItem[];
+    selectedValue?: string;
+}
+export interface ContentControlsChoiceListSetItemsInput {
+    target: ContentControlTarget;
+    items: ContentControlListItem[];
+}
+export interface ContentControlsChoiceListSetSelectedInput {
+    target: ContentControlTarget;
+    value: string;
+}
+export interface ContentControlsRepeatingSectionListItemsInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsRepeatingSectionListItemsResult {
+    items: ContentControlInfo[];
+    total: number;
+}
+export interface ContentControlsRepeatingSectionInsertItemBeforeInput {
+    target: ContentControlTarget;
+    index: number;
+}
+export interface ContentControlsRepeatingSectionInsertItemAfterInput {
+    target: ContentControlTarget;
+    index: number;
+}
+export interface ContentControlsRepeatingSectionCloneItemInput {
+    target: ContentControlTarget;
+    index: number;
+}
+export interface ContentControlsRepeatingSectionDeleteItemInput {
+    target: ContentControlTarget;
+    index: number;
+}
+export interface ContentControlsRepeatingSectionSetAllowInsertDeleteInput {
+    target: ContentControlTarget;
+    allow: boolean;
+}
+export interface ContentControlsGroupWrapInput {
+    target: ContentControlTarget;
+}
+export interface ContentControlsGroupUngroupInput {
+    target: ContentControlTarget;
+}

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

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

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

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './command-catalog.js';
+export * from './schemas.js';
+export * from './operation-map.js';
+export * from './reference-doc-map.js';
+export * from './reference-aliases.js';
+export * from './operation-registry.js';
+export * from './step-op-catalog.js';
+export { INTENT_GROUP_META, OPERATION_DEFINITIONS, V1_RUNTIME_UNAVAILABLE_OPERATION_IDS, projectFromDefinitions, type IntentGroupMeta, type OperationDefinitionEntry, type ReferenceGroupKey, } from './operation-definitions.js';

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

@@ -0,0 +1,30 @@
+import { ReceiptFailureCode } from '../types/receipt.js';
+export declare const OPERATION_IDEMPOTENCY_VALUES: readonly ["idempotent", "conditional", "non-idempotent"];
+export type OperationIdempotency = (typeof OPERATION_IDEMPOTENCY_VALUES)[number];
+export declare const PRE_APPLY_THROW_CODES: readonly ["TARGET_NOT_FOUND", "CAPABILITY_UNAVAILABLE", "INVALID_TARGET", "AMBIGUOUS_TARGET", "REVISION_MISMATCH", "MATCH_NOT_FOUND", "AMBIGUOUS_MATCH", "STYLE_CONFLICT", "PRECONDITION_FAILED", "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", "INTERNAL_ERROR", "ADDRESS_STALE", "DUPLICATE_ID", "INVALID_CONTEXT", "RAW_MODE_REQUIRED", "PRESERVE_ONLY_VIOLATION", "CAPABILITY_UNSUPPORTED", "LOCK_VIOLATION", "TYPE_MISMATCH", "STORY_NOT_FOUND", "STORY_MISMATCH", "STORY_NOT_SUPPORTED", "CROSS_STORY_PLAN", "MATERIALIZATION_FAILED"];
+export type PreApplyThrowCode = (typeof PRE_APPLY_THROW_CODES)[number];
+export interface CommandThrowPolicy {
+    preApply: readonly PreApplyThrowCode[];
+    postApplyForbidden: true;
+}
+export interface CommandStaticMetadata {
+    mutates: boolean;
+    idempotency: OperationIdempotency;
+    supportsDryRun: boolean;
+    supportsTrackedMode: boolean;
+    possibleFailureCodes: readonly ReceiptFailureCode[];
+    throws: CommandThrowPolicy;
+    deterministicTargetResolution: boolean;
+    remediationHints?: readonly string[];
+    /** When true, this operation bypasses PM transaction history (out-of-band XML mutation). */
+    historyUnsafe?: boolean;
+    /**
+     * When true, the operation's successful/receipt-returning path resolves a
+     * Promise and callers must `await` it. Synchronous `throws.preApply` guards
+     * still throw before the Promise is created. Defaults to `false` (the
+     * operation returns its receipt synchronously).
+     */
+    returnsPromise?: boolean;
+    /** When true, the operation result follows the Receipt success/failure envelope. */
+    returnsReceipt?: boolean;
+}