Document apiReferenceFormat

format.readSelection

Read inline formatting across a selection or caret, reporting each property as uniform, mixed, unset or unresolvable.

read-onlyidempotent
doc.format.readSelection(…)

Expected result

Returns per-property states whose uniform values use the same shape format.apply accepts, without changing the document.

Inputs

target
targetSelectionTargetrequired
Fields
kind"selection"required
startSelectionPointrequired

A point in the document. Use {kind:'text', blockId, offset} for character positions or {kind:'nodeEdge', node:{kind:'block', nodeType, nodeId}, edge:'before'|'after'} for block boundaries.

text
kind"text"required
blockIdstringrequired
offsetintegerrequired
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
nodeEdge
kind"nodeEdge"required
nodeSelectionEdgeNodeAddressrequired
edge"before" | "after"required
endSelectionPointrequired

A point in the document. Use {kind:'text', blockId, offset} for character positions or {kind:'nodeEdge', node:{kind:'block', nodeType, nodeId}, edge:'before'|'after'} for block boundaries.

text
kind"text"required
blockIdstringrequired
offsetintegerrequired
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
nodeEdge
kind"nodeEdge"required
nodeSelectionEdgeNodeAddressrequired
edge"before" | "after"required
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
coordinateSpaceTextCoordinateSpace
keys"bold" | "italic" | "strike" | "underline" | "highlight" | "color" | "fontSize" | "fontFamily" | "letterSpacing" | "vertAlign" | "position" | "dstrike" | "smallCaps" | "caps" | "shading" | "border" | "outline" | "shadow" | "emboss" | "imprint" | "charScale" | "kerning" | "vanish" | "webHidden" | "specVanish" | "rtl" | "cs" | "bCs" | "iCs" | "eastAsianLayout" | "em" | "fitText" | "snapToGrid" | "lang" | "oMath" | "rStyle" | "rFonts" | "fontSizeCs" | "ligatures" | "numForm" | "numSpacing" | "stylisticSets" | "contextualAlternates"[]

Inline properties to read. Defaults to every format.apply property.

view"effective" | "direct"

'effective' (default) resolves the style cascade; 'direct' reads run-level formatting only.

inStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
Fields
kind"section"required
sectionIdstringrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
ref
refstringrequired

Handle ref string from a search result.

keys"bold" | "italic" | "strike" | "underline" | "highlight" | "color" | "fontSize" | "fontFamily" | "letterSpacing" | "vertAlign" | "position" | "dstrike" | "smallCaps" | "caps" | "shading" | "border" | "outline" | "shadow" | "emboss" | "imprint" | "charScale" | "kerning" | "vanish" | "webHidden" | "specVanish" | "rtl" | "cs" | "bCs" | "iCs" | "eastAsianLayout" | "em" | "fitText" | "snapToGrid" | "lang" | "oMath" | "rStyle" | "rFonts" | "fontSizeCs" | "ligatures" | "numForm" | "numSpacing" | "stylisticSets" | "contextualAlternates"[]

Inline properties to read. Defaults to every format.apply property.

view"effective" | "direct"

'effective' (default) resolves the style cascade; 'direct' reads run-level formatting only.

inStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
Fields
kind"section"required
sectionIdstringrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
selection
selection"current"required

Read the live editor selection, including pending caret formatting.

keys"bold" | "italic" | "strike" | "underline" | "highlight" | "color" | "fontSize" | "fontFamily" | "letterSpacing" | "vertAlign" | "position" | "dstrike" | "smallCaps" | "caps" | "shading" | "border" | "outline" | "shadow" | "emboss" | "imprint" | "charScale" | "kerning" | "vanish" | "webHidden" | "specVanish" | "rtl" | "cs" | "bCs" | "iCs" | "eastAsianLayout" | "em" | "fitText" | "snapToGrid" | "lang" | "oMath" | "rStyle" | "rFonts" | "fontSizeCs" | "ligatures" | "numForm" | "numSpacing" | "stylisticSets" | "contextualAlternates"[]

Inline properties to read. Defaults to every format.apply property.

view"effective" | "direct"

'effective' (default) resolves the style cascade; 'direct' reads run-level formatting only.

inStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
Fields
kind"section"required
sectionIdstringrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired

Result

The top-level fields are shown here. Use the raw schema artifact for the complete capability matrix.

Output fields
collapsedbooleanrequired
pendingAppliedboolean
propertiesobjectrequired

Failures

Pre-apply throws

  • TARGET_NOT_FOUND
  • CAPABILITY_UNAVAILABLE
  • INVALID_TARGET
7 more codes
  • INVALID_INPUT
  • REVISION_MISMATCH
  • STORY_NOT_FOUND
  • STORY_MISMATCH
  • STORY_NOT_SUPPORTED
  • CROSS_STORY_PLAN
  • MATERIALIZATION_FAILED

Raw schemas

Open the generated JSON artifact for the exact input, output, success, and failure schemas represented by this contract version.

View raw JSON schemas