> For the complete documentation index, see [llms.txt](/llms.txt). > The full corpus is at [llms-full.txt](/llms-full.txt). # SyntheticBehaviorEvent > **SyntheticBehaviorEvent** = \{ `annotation`: \{ `_key?`: `string`; `name`: `string`; `value`: \{\[`prop`: `string`\]: `unknown`; \}; \}; `at?`: `NonNullable`\<`EditorSelection`\>; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"annotation.add"`\>; \} \| \{ `annotation`: \{ `name`: `string`; \}; `at?`: `NonNullable`\<`EditorSelection`\>; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"annotation.remove"`\>; \} \| \{ `at`: `BlockPath`; `props`: `Record`\<`string`, `unknown`\>; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"block.set"`\>; \} \| \{ `at`: `BlockPath`; `props`: `string`[]; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"block.unset"`\>; \} \| \{ `at`: `ChildPath`; `props`: \{\[`prop`: `string`\]: `unknown`; \}; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"child.set"`\>; \} \| \{ `at`: `ChildPath`; `props`: `string`[]; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"child.unset"`\>; \} \| \{ `at?`: `NonNullable`\<`EditorSelection`\>; `decorator`: `string`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"decorator.add"`\>; \} \| \{ `at?`: `NonNullable`\<`EditorSelection`\>; `decorator`: `string`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"decorator.remove"`\>; \} \| \{ `at?`: `NonNullable`\<`EditorSelection`\>; `direction?`: `"backward"` \| `"forward"`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"delete"`\>; `unit?`: `"character"` \| `"word"` \| `"line"` \| `"block"` \| `"child"`; \} \| \{ `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"history.redo"`\>; \} \| \{ `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"history.undo"`\>; \} \| \{ `at`: `Path`; `position`: `"before"` \| `"after"`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"insert"`\>; `value`: `PortableTextTextBlock` \| `PortableTextObject` \| `PortableTextSpan`; \} \| \{ `at?`: `NonNullable`\<`EditorSelection`\>; `block`: `BlockWithOptionalKey`; `placement`: [`InsertPlacement`](/api/behaviors/type-aliases/insertplacement/); `select?`: `"start"` \| `"end"` \| `"none"`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"insert.block"`\>; \} \| \{ `child`: `ChildWithOptionalKey`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"insert.child"`\>; \} \| \{ `at?`: `Path`; `offset?`: `number`; `text`: `string`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"insert.text"`\>; \} \| \{ `distance`: `number`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"move.backward"`\>; \} \| \{ `distance`: `number`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"move.forward"`\>; \} \| \{ `at`: `Path`; `offset`: `number`; `text`: `string`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"remove.text"`\>; \} \| \{ `at`: `EditorSelection`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"select"`\>; \} \| \{ `at`: `Path`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"set"`\>; `value`: `unknown`; \} \| \{ `at`: `Path`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"unset"`\>; \} \| `AbstractBehaviorEvent` Defined in: behavior.types.event.ts:102 :::caution[Beta] This API should not be used in production and may be trimmed from a public release. ::: ## Type Declaration \{ `annotation`: \{ `_key?`: `string`; `name`: `string`; `value`: \{\[`prop`: `string`\]: `unknown`; \}; \}; `at?`: `NonNullable`\<`EditorSelection`\>; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"annotation.add"`\>; \} ### annotation > **annotation**: `object` #### annotation.\_key? > `optional` **\_key**: `string` #### annotation.name > **name**: `string` #### annotation.value > **value**: `object` ##### Index Signature \[`prop`: `string`\]: `unknown` ### at? > `optional` **at**: `NonNullable`\<`EditorSelection`\> ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"annotation.add"`\> \{ `annotation`: \{ `name`: `string`; \}; `at?`: `NonNullable`\<`EditorSelection`\>; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"annotation.remove"`\>; \} ### annotation > **annotation**: `object` #### annotation.name > **name**: `string` ### at? > `optional` **at**: `NonNullable`\<`EditorSelection`\> ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"annotation.remove"`\> \{ `at`: `BlockPath`; `props`: `Record`\<`string`, `unknown`\>; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"block.set"`\>; \} ### at > **at**: `BlockPath` ### props > **props**: `Record`\<`string`, `unknown`\> ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"block.set"`\> \{ `at`: `BlockPath`; `props`: `string`[]; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"block.unset"`\>; \} ### at > **at**: `BlockPath` ### props > **props**: `string`[] ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"block.unset"`\> \{ `at`: `ChildPath`; `props`: \{\[`prop`: `string`\]: `unknown`; \}; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"child.set"`\>; \} ### at > **at**: `ChildPath` ### props > **props**: `object` #### Index Signature \[`prop`: `string`\]: `unknown` ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"child.set"`\> \{ `at`: `ChildPath`; `props`: `string`[]; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"child.unset"`\>; \} ### at > **at**: `ChildPath` ### props > **props**: `string`[] ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"child.unset"`\> \{ `at?`: `NonNullable`\<`EditorSelection`\>; `decorator`: `string`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"decorator.add"`\>; \} ### at? > `optional` **at**: `NonNullable`\<`EditorSelection`\> ### decorator > **decorator**: `string` ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"decorator.add"`\> \{ `at?`: `NonNullable`\<`EditorSelection`\>; `decorator`: `string`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"decorator.remove"`\>; \} ### at? > `optional` **at**: `NonNullable`\<`EditorSelection`\> ### decorator > **decorator**: `string` ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"decorator.remove"`\> \{ `at?`: `NonNullable`\<`EditorSelection`\>; `direction?`: `"backward"` \| `"forward"`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"delete"`\>; `unit?`: `"character"` \| `"word"` \| `"line"` \| `"block"` \| `"child"`; \} ### at? > `optional` **at**: `NonNullable`\<`EditorSelection`\> ### direction? > `optional` **direction**: `"backward"` \| `"forward"` Defaults to forward deletion. ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"delete"`\> ### unit? > `optional` **unit**: `"character"` \| `"word"` \| `"line"` \| `"block"` \| `"child"` Defaults to character deletion. \{ `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"history.redo"`\>; \} ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"history.redo"`\> \{ `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"history.undo"`\>; \} ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"history.undo"`\> \{ `at`: `Path`; `position`: `"before"` \| `"after"`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"insert"`\>; `value`: `PortableTextTextBlock` \| `PortableTextObject` \| `PortableTextSpan`; \} ### at > **at**: `Path` ### position > **position**: `"before"` \| `"after"` ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"insert"`\> Primitive: insert a node into an array. The last segment of `at` resolves the insertion point: - A keyed `{_key}` segment inserts relative to that sibling. - A numeric index inserts relative to that slot. `position` ('before' or 'after') is always meaningful: `before: [2]` inserts at index 2, `after: [2]` inserts at index 3. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. ::: #### Example ```ts raise({ type: 'insert', at: [{_key: 'list'}, 'items', {_key: 'item3'}], value: newItem, position: 'after', }) ``` ### value > **value**: `PortableTextTextBlock` \| `PortableTextObject` \| `PortableTextSpan` \{ `at?`: `NonNullable`\<`EditorSelection`\>; `block`: `BlockWithOptionalKey`; `placement`: [`InsertPlacement`](/api/behaviors/type-aliases/insertplacement/); `select?`: `"start"` \| `"end"` \| `"none"`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"insert.block"`\>; \} ### at? > `optional` **at**: `NonNullable`\<`EditorSelection`\> ### block > **block**: `BlockWithOptionalKey` ### placement > **placement**: [`InsertPlacement`](/api/behaviors/type-aliases/insertplacement/) ### select? > `optional` **select**: `"start"` \| `"end"` \| `"none"` ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"insert.block"`\> \{ `child`: `ChildWithOptionalKey`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"insert.child"`\>; \} ### child > **child**: `ChildWithOptionalKey` ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"insert.child"`\> \{ `at?`: `Path`; `offset?`: `number`; `text`: `string`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"insert.text"`\>; \} ### at? > `optional` **at**: `Path` ### offset? > `optional` **offset**: `number` ### text > **text**: `string` ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"insert.text"`\> Inserts text into a span. Without `at`/`offset`, text is inserted at the current caret position. This is the form used by typing handlers. With `at` and `offset`, text is inserted at the explicit position. Recommended for plugin behaviors and collaborative-edit contexts. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. ::: #### Example ```ts // Caret form raise({type: 'insert.text', text: 'x'}) // Primitive form (@alpha) raise({ type: 'insert.text', at: [{_key: 'b1'}, 'children', {_key: 's1'}], offset: 5, text: 'world', }) ``` \{ `distance`: `number`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"move.backward"`\>; \} ### distance > **distance**: `number` ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"move.backward"`\> \{ `distance`: `number`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"move.forward"`\>; \} ### distance > **distance**: `number` ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"move.forward"`\> \{ `at`: `Path`; `offset`: `number`; `text`: `string`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"remove.text"`\>; \} ### at > **at**: `Path` ### offset > **offset**: `number` ### text > **text**: `string` ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"remove.text"`\> Primitive: remove text from a span at the given offset. The `text` field carries the exact text being removed (matches the apply-layer shape so the inverse can be computed without re-reading the span). Recommended for collaborative-edit contexts (concurrent edits compose cleanly under operational transform). :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. ::: #### Example ```ts raise({ type: 'remove.text', at: [{_key: 'b1'}, 'children', {_key: 's1'}], offset: 5, text: 'world', }) ``` \{ `at`: `EditorSelection`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"select"`\>; \} ### at > **at**: `EditorSelection` ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"select"`\> \{ `at`: `Path`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"set"`\>; `value`: `unknown`; \} ### at > **at**: `Path` ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"set"`\> Primitive: set a property on a node, or replace a node wholesale. The last segment of `at` is the property name (a string) for property updates, OR a keyed/indexed segment for full-node replacement. Note: `set` on span text (`{at: [...spanPath, 'text'], value: '...'}`) is legal but not recommended in collaborative-edit contexts. Use `insert.text` and `remove.text` for text edits that compose under operational transform. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. ::: #### Example ```ts // Set a block's style raise({type: 'set', at: [{_key: 'b1'}, 'style'], value: 'h1'}) // Replace a block wholesale raise({type: 'set', at: [{_key: 'b1'}], value: newBlock}) ``` ### value > **value**: `unknown` \{ `at`: `Path`; `type`: `StrictExtract`\<`SyntheticBehaviorEventType`, `"unset"`\>; \} ### at > **at**: `Path` ### type > **type**: `StrictExtract`\<`SyntheticBehaviorEventType`, `"unset"`\> Primitive: unset a property on an object, OR remove a node from an array. When the last segment of `at` is a string, the property is removed. When the last segment is a keyed `{_key}` segment or a numeric index, the node at that array position is removed. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. ::: #### Example ```ts // Remove a property raise({type: 'unset', at: [{_key: 'b1'}, 'level']}) // Remove a node from an array raise({type: 'unset', at: [{_key: 'list'}, 'items', {_key: 'item3'}]}) ``` `AbstractBehaviorEvent`