mutations.preview

Dry-run a mutation plan, returning resolved targets without applying changes.

Alpha: Document API is currently alpha and subject to breaking changes.

Summary

Dry-run a mutation plan, returning resolved targets without applying changes.

• Operation ID: mutations.preview
• API member path: editor.doc.mutations.preview(...)
• Mutates document: no
• Idempotency: idempotent
• Supports tracked mode: no
• Supports dry run: no
• Deterministic target resolution: yes

Expected result

Returns a MutationsPreviewOutput with resolved targets and step details without applying changes.

Supported step operations

Use these values in steps[].op when authoring mutation plans.

Assert

Step op (steps[].op)	Description	Related API operation
assert	Assert selector cardinality after mutation steps complete.	—

Text

Step op (steps[].op)	Description	Related API operation
text.rewrite	Rewrite matched text ranges with replacement content.	replace
text.insert	Insert text before or after a matched range.	insert
text.delete	Delete matched text ranges.	delete

Format

Step op (steps[].op)	Description	Related API operation
format.apply	Apply inline formatting patch changes to matched text ranges.	format.apply

Create

Step op (steps[].op)	Description	Related API operation
create.paragraph	Create a paragraph adjacent to the matched block.	create.paragraph
create.heading	Create a heading adjacent to the matched block.	create.heading
create.table	Create a table at the requested location.	create.table

Tables

Step op (steps[].op)	Description	Related API operation
tables.delete	Delete the target table from the document.	tables.delete
tables.clearContents	Clear contents from a target table or cell range.	tables.clearContents
tables.move	Move a table to a new position.	tables.move
tables.split	Split a table into two tables at a target row.	tables.split
tables.convertFromText	Convert a text range into a table.	tables.convertFromText
tables.convertToText	Convert a table to plain text.	tables.convertToText
tables.setLayout	Set table layout mode.	tables.setLayout
tables.insertRow	Insert a row into the target table.	tables.insertRow
tables.deleteRow	Delete a row from the target table.	tables.deleteRow
tables.setRowHeight	Set row height in the target table.	tables.setRowHeight
tables.distributeRows	Distribute row heights evenly.	tables.distributeRows
tables.setRowOptions	Set row-level options (header repeat, page break, etc.).	tables.setRowOptions
tables.insertColumn	Insert a column into the target table.	tables.insertColumn
tables.deleteColumn	Delete a column from the target table.	tables.deleteColumn
tables.setColumnWidth	Set column width in the target table.	tables.setColumnWidth
tables.distributeColumns	Distribute column widths evenly.	tables.distributeColumns
tables.insertCell	Insert a cell into a table row.	tables.insertCell
tables.deleteCell	Delete a cell from a table row.	tables.deleteCell
tables.mergeCells	Merge a range of table cells.	tables.mergeCells
tables.unmergeCells	Unmerge a merged table cell.	tables.unmergeCells
tables.splitCell	Split a table cell into multiple cells.	tables.splitCell
tables.setCellProperties	Set properties on target table cells.	tables.setCellProperties
tables.sort	Sort table rows by a column value.	tables.sort
tables.setAltText	Set table alt text properties.	tables.setAltText
tables.setStyle	Set table style identifier.	tables.setStyle
tables.clearStyle	Clear direct table style assignment.	tables.clearStyle
tables.setStyleOption	Set table style option flags.	tables.setStyleOption
tables.setBorder	Set table border properties.	tables.setBorder
tables.clearBorder	Clear table border properties.	tables.clearBorder
tables.applyBorderPreset	Apply a border preset to a table.	tables.applyBorderPreset
tables.setShading	Set table shading properties.	tables.setShading
tables.clearShading	Clear table shading properties.	tables.clearShading
tables.setTablePadding	Set table-level cell padding.	tables.setTablePadding
tables.setCellPadding	Set cell padding for target cells.	tables.setCellPadding
tables.setCellSpacing	Set table cell spacing.	tables.setCellSpacing
tables.clearCellSpacing	Clear table cell spacing.	tables.clearCellSpacing

The runtime capability snapshot also exposes this allowlist at planEngine.supportedStepOps.

Input fields

Field	Type	Required	Description
atomic	true	yes	Constant: true
changeMode	enum	yes	"direct", "tracked"
expectedRevision	string	no
steps	object[]	yes

Example request

{
  "atomic": true,
  "changeMode": "direct",
  "expectedRevision": "rev-001",
  "steps": [
    {}
  ]
}

Output fields

Field	Type	Required	Description
evaluatedRevision	string	yes
failures	object[]	no
steps	object[]	yes
valid	boolean	yes

Example response

{
  "evaluatedRevision": "rev-001",
  "failures": [
    {}
  ],
  "steps": [
    {}
  ],
  "valid": true
}

Pre-apply throws

• 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
• CAPABILITY_UNAVAILABLE

Non-applied failure codes

• None

Raw schemas

Raw input schema

{
  "additionalProperties": false,
  "properties": {
    "atomic": {
      "const": true
    },
    "changeMode": {
      "enum": [
        "direct",
        "tracked"
      ]
    },
    "expectedRevision": {
      "type": "string"
    },
    "steps": {
      "items": {
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "atomic",
    "changeMode",
    "steps"
  ],
  "type": "object"
}

Raw output schema

{
  "additionalProperties": false,
  "properties": {
    "evaluatedRevision": {
      "type": "string"
    },
    "failures": {
      "items": {
        "type": "object"
      },
      "type": "array"
    },
    "steps": {
      "items": {
        "type": "object"
      },
      "type": "array"
    },
    "valid": {
      "type": "boolean"
    }
  },
  "required": [
    "evaluatedRevision",
    "steps",
    "valid"
  ],
  "type": "object"
}