format.rtl

Set or clear the rtl inline run property on the target text range. This does not change paragraph direction; use format.paragraph.setDirection for paragraph-level RTL.

Summary

Set or clear the rtl inline run property on the target text range. This does not change paragraph direction; use format.paragraph.setDirection for paragraph-level RTL.

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

Expected result

Returns a TextMutationReceipt confirming only the inline run property patch was applied to the target range; paragraph direction is unchanged.

Input fields

Variant 1 (target.kind=“selection”)

Field	Type	Required	Description
target	SelectionTarget	yes	SelectionTarget
target.end	SelectionPoint	yes	SelectionPoint
target.kind	"selection"	yes	Constant: "selection"
target.start	SelectionPoint	yes	SelectionPoint
value	boolean \	null	no	One of: boolean, null

Variant 2 (required: ref)

Field	Type	Required	Description
ref	string	yes
value	boolean \	null	no	One of: boolean, null

Example request

{
  "target": {
    "end": {
      "blockId": "block-abc123",
      "kind": "text",
      "offset": 0
    },
    "kind": "selection",
    "start": {
      "blockId": "block-abc123",
      "kind": "text",
      "offset": 0
    }
  },
  "value": true
}

Output fields

Variant 1 (success=true)

Field	Type	Required	Description
inserted	EntityAddress[]	no
removed	EntityAddress[]	no
resolution	TextMutationResolution	yes	TextMutationResolution
resolution.range	TextMutationRange	yes	TextMutationRange
resolution.range.from	integer	yes
resolution.range.to	integer	yes
resolution.requestedTarget	TextAddress	no	TextAddress
resolution.requestedTarget.blockId	string	no
resolution.requestedTarget.kind	"text"	no	Constant: "text"
resolution.requestedTarget.range	Range	no	Range
resolution.requestedTarget.range.end	integer	no
resolution.requestedTarget.range.start	integer	no
resolution.selectionTarget	SelectionTarget	no	SelectionTarget
resolution.selectionTarget.end	SelectionPoint	no	SelectionPoint
resolution.selectionTarget.kind	"selection"	no	Constant: "selection"
resolution.selectionTarget.start	SelectionPoint	no	SelectionPoint
resolution.target	TextAddress	yes	TextAddress
resolution.target.blockId	string	yes
resolution.target.kind	"text"	yes	Constant: "text"
resolution.target.range	Range	yes	Range
resolution.target.range.end	integer	yes
resolution.target.range.start	integer	yes
resolution.text	string	yes
success	true	yes	Constant: true
updated	EntityAddress[]	no

Variant 2 (success=false)

Field	Type	Required	Description
failure	object	yes
failure.code	enum	yes	"INVALID_TARGET"
failure.details	any	no
failure.message	string	yes
resolution	TextMutationResolution	yes	TextMutationResolution
resolution.range	TextMutationRange	yes	TextMutationRange
resolution.range.from	integer	yes
resolution.range.to	integer	yes
resolution.requestedTarget	TextAddress	no	TextAddress
resolution.requestedTarget.blockId	string	no
resolution.requestedTarget.kind	"text"	no	Constant: "text"
resolution.requestedTarget.range	Range	no	Range
resolution.requestedTarget.range.end	integer	no
resolution.requestedTarget.range.start	integer	no
resolution.selectionTarget	SelectionTarget	no	SelectionTarget
resolution.selectionTarget.end	SelectionPoint	no	SelectionPoint
resolution.selectionTarget.kind	"selection"	no	Constant: "selection"
resolution.selectionTarget.start	SelectionPoint	no	SelectionPoint
resolution.target	TextAddress	yes	TextAddress
resolution.target.blockId	string	yes
resolution.target.kind	"text"	yes	Constant: "text"
resolution.target.range	Range	yes	Range
resolution.target.range.end	integer	yes
resolution.target.range.start	integer	yes
resolution.text	string	yes
success	false	yes	Constant: false

Example response

{
  "inserted": [
    {
      "entityId": "entity-789",
      "entityType": "comment",
      "kind": "entity"
    }
  ],
  "resolution": {
    "range": {
      "from": 0,
      "to": 10
    },
    "requestedTarget": {
      "blockId": "block-abc123",
      "kind": "text",
      "range": {
        "end": 10,
        "start": 0
      }
    },
    "selectionTarget": {
      "end": {
        "blockId": "block-abc123",
        "kind": "text",
        "offset": 0
      },
      "kind": "selection",
      "start": {
        "blockId": "block-abc123",
        "kind": "text",
        "offset": 0
      }
    },
    "target": {
      "blockId": "block-abc123",
      "kind": "text",
      "range": {
        "end": 10,
        "start": 0
      }
    },
    "text": "Hello, world."
  },
  "success": true,
  "updated": [
    {
      "entityId": "entity-789",
      "entityType": "comment",
      "kind": "entity"
    }
  ]
}

Pre-apply throws

• TARGET_NOT_FOUND
• CAPABILITY_UNAVAILABLE
• INVALID_TARGET
• INVALID_INPUT
• STORY_NOT_FOUND
• STORY_MISMATCH
• STORY_NOT_SUPPORTED
• CROSS_STORY_PLAN
• MATERIALIZATION_FAILED

Non-applied failure codes

• INVALID_TARGET

Raw schemas

Raw input schema

{
  "oneOf": [
    {
      "additionalProperties": false,
      "properties": {
        "target": {
          "$ref": "#/$defs/SelectionTarget",
          "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle."
        },
        "value": {
          "oneOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "target"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "ref": {
          "description": "Handle ref string from a superdoc_search result. Pass the handle.ref value directly (e.g. 'text:eyJ...'). Preferred over 'target' for inline formatting.",
          "type": "string"
        },
        "value": {
          "oneOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "ref"
      ],
      "type": "object"
    }
  ]
}

Raw output schema

{
  "oneOf": [
    {
      "$ref": "#/$defs/TextMutationSuccess"
    },
    {
      "additionalProperties": false,
      "properties": {
        "failure": {
          "additionalProperties": false,
          "properties": {
            "code": {
              "enum": [
                "INVALID_TARGET"
              ]
            },
            "details": {},
            "message": {
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object"
        },
        "resolution": {
          "$ref": "#/$defs/TextMutationResolution"
        },
        "success": {
          "const": false
        }
      },
      "required": [
        "success",
        "failure",
        "resolution"
      ],
      "type": "object"
    }
  ]
}

Raw success schema

{
  "$ref": "#/$defs/TextMutationSuccess"
}

Raw failure schema

{
  "additionalProperties": false,
  "properties": {
    "failure": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "enum": [
            "INVALID_TARGET"
          ]
        },
        "details": {},
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "resolution": {
      "$ref": "#/$defs/TextMutationResolution"
    },
    "success": {
      "const": false
    }
  },
  "required": [
    "success",
    "failure",
    "resolution"
  ],
  "type": "object"
}