Edit the document
The AI Toolkit provides primitives to edit the document in different formats.
insertText
Insert plain text into the editor.
Parameters
content
(string
): Text to insertoptions?
(InsertTextOptions
): Options for theinsertText
methodposition?
(InsertPosition
): Where to insert. See options. Default:'selection'
reviewOptions?
(ReviewOptions
): Control preview/review behaviormode?
('disabled' | 'review' | 'preview'
): Whether to review the changes before or after applying them.'disabled'
means no review,'review'
means review after applying,'preview'
means preview before applying. Default:'disabled'
showDiff?
(boolean
): Whether to diff the documents before and after the change to display the change as a detailed diff. Default:false
displayOptions?
(DisplayOptions<{ suggestion: Suggestion }>
): Customize how suggestions are displayedshowAsDiff?
(boolean
): Whether to show the suggestion as a diff where inserted and original content are displayed side by side. Default:true
diffPosition?
('before' | 'after'
): The position of the diff relative to the suggestion. Default:'before'
attributes?
(Record<string, any>
): Extra HTML attributes to be added to the suggestionrenderDecorations?
(RenderDecorations<{ suggestion: Suggestion }>
): A function to render the suggestion as ProseMirror decorations
metadata?
(Record<string, any>
): Extra metadata for the suggestions that can be used to store additional information about them (e.g. their source or their category). It is not used internally by the extension but it may help developers customize how the suggestions are displayed in the UI.
Returns
void
Example
// Insert text at the current selection and show review markers
toolkit.insertText('AI content', { position: 'selection', reviewOptions: { mode: 'review' } })
insertHtml
Insert HTML into the editor.
Parameters
content
(string
): HTML to insertoptions?
(InsertHtmlOptions
): Options for theinsertHtml
methodposition?
(InsertPosition
): Where to insert. See options. Default:'selection'
reviewOptions?
(ReviewOptions
): Control preview/review behaviormode?
('disabled' | 'review' | 'preview'
): Whether to review the changes before or after applying them.'disabled'
means no review,'review'
means review after applying,'preview'
means preview before applying. Default:'disabled'
showDiff?
(boolean
): Whether to diff the documents before and after the change to display the change as a detailed diff. Default:false
displayOptions?
(DisplayOptions<{ suggestion: Suggestion }>
): Customize how suggestions are displayedshowAsDiff?
(boolean
): Whether to show the suggestion as a diff where inserted and original content are displayed side by side. Default:true
diffPosition?
('before' | 'after'
): The position of the diff relative to the suggestion. Default:'before'
attributes?
(Record<string, any>
): Extra HTML attributes to be added to the suggestionrenderDecorations?
(RenderDecorations<{ suggestion: Suggestion }>
): A function to render the suggestion as ProseMirror decorations
metadata?
(Record<string, any>
): Extra metadata for the suggestions that can be used to store additional information about them (e.g. their source or their category). It is not used internally by the extension but it may help developers customize how the suggestions are displayed in the UI.
Returns
void
Example
// Insert a paragraph after the selection
toolkit.insertHtml('<p>AI paragraph</p>', { position: 'selectionEnd' })
insertJson
Insert ProseMirror JSON into the editor.
Parameters
content
(any
): ProseMirror JSON node or sliceoptions?
(InsertJsonOptions
): Options for theinsertJson
methodposition?
(InsertPosition
): Where to insert. See options. Default:'selection'
reviewOptions?
(ReviewOptions
): Control preview/review behaviormode?
('disabled' | 'review' | 'preview'
): Whether to review the changes before or after applying them.'disabled'
means no review,'review'
means review after applying,'preview'
means preview before applying. Default:'disabled'
showDiff?
(boolean
): Whether to diff the documents before and after the change to display the change as a detailed diff. Default:false
displayOptions?
(DisplayOptions<{ suggestion: Suggestion }>
): Customize how suggestions are displayedshowAsDiff?
(boolean
): Whether to show the suggestion as a diff where inserted and original content are displayed side by side. Default:true
diffPosition?
('before' | 'after'
): The position of the diff relative to the suggestion. Default:'before'
attributes?
(Record<string, any>
): Extra HTML attributes to be added to the suggestionrenderDecorations?
(RenderDecorations<{ suggestion: Suggestion }>
): A function to render the suggestion as ProseMirror decorations
metadata?
(Record<string, any>
): Extra metadata for the suggestions that can be used to store additional information about them (e.g. their source or their category). It is not used internally by the extension but it may help developers customize how the suggestions are displayed in the UI.
Returns
void
Example
// Insert a paragraph node
toolkit.insertJson({ type: 'paragraph', content: [{ type: 'text', text: 'AI' }] })
streamText
Stream plain text content into the editor in real-time.
Parameters
stream
(AsyncIterable<string | Uint8Array>
): The stream of text content. It can be any object that implements the Async Iterable protocol, such as a ReadableStream or a generator.options?
(StreamTextOptions
): Options for thestreamText
methodposition?
(InsertPosition
): Where to insert. See options. Default:'selection'
reviewOptions?
(ReviewOptions
): Control preview/review behaviormode?
('disabled' | 'review' | 'preview'
): Whether to review the changes before or after applying them.'disabled'
means no review,'review'
means review after applying,'preview'
means preview before applying. Default:'disabled'
showDiff?
(boolean
): Whether to diff the documents before and after the change to display the change as a detailed diff. Default:false
displayOptions?
(DisplayOptions<{ suggestion: Suggestion }>
): Customize how suggestions are displayedshowAsDiff?
(boolean
): Whether to show the suggestion as a diff where inserted and original content are displayed side by side. Default:true
diffPosition?
('before' | 'after'
): The position of the diff relative to the suggestion. Default:'before'
attributes?
(Record<string, any>
): Extra HTML attributes to be added to the suggestionrenderDecorations?
(RenderDecorations<{ suggestion: Suggestion }>
): A function to render the suggestion as ProseMirror decorations
metadata?
(Record<string, any>
): Extra metadata for the suggestions that can be used to store additional information about them (e.g. their source or their category). It is not used internally by the extension but it may help developers customize how the suggestions are displayed in the UI.
checkChunkForError?
((status: { chunk: string; content: string; range: Range }) => boolean
): A function to check if the chunk contains an error. Returnstrue
if the chunk has an error,false
otherwise. Iftrue
, the stream will be stopped and aStreamingChunkCheckFailedError
will be thrown.onError?
((event: { error: unknown; chunk: string; content: string; range: Range }) => void
): A function to handle errors that occur during streaming.onChunkInserted?
((event: { chunk: string; content: string; range: Range }) => void
): A function to handle when a chunk is streamed. Called after the chunk is inserted into the editor.
Returns
Promise<void>
: A promise that resolves when the stream is complete.
Example
const response = await fetch('/api/generate-text')
// The API endpoint returns a stream of text content
const stream = response.body
toolkit.streamText(stream)
streamHtml
Stream HTML content into the editor in real-time.
Parameters
stream
(AsyncIterable<string | Uint8Array>
): The stream of text content. It can be any object that implements the Async Iterable protocol, such as a ReadableStream or a generator.options?
(StreamHtmlOptions
): Options for thestreamHtml
methodposition?
(InsertPosition
): Where to insert. See options. Default:'selection'
reviewOptions?
(ReviewOptions
): Control preview/review behaviormode?
('disabled' | 'review' | 'preview'
): Whether to review the changes before or after applying them.'disabled'
means no review,'review'
means review after applying,'preview'
means preview before applying. Default:'disabled'
showDiff?
(boolean
): Whether to diff the documents before and after the change to display the change as a detailed diff. Default:false
displayOptions?
(DisplayOptions<{ suggestion: Suggestion }>
): Customize how suggestions are displayedshowAsDiff?
(boolean
): Whether to show the suggestion as a diff where inserted and original content are displayed side by side. Default:true
diffPosition?
('before' | 'after'
): The position of the diff relative to the suggestion. Default:'before'
attributes?
(Record<string, any>
): Extra HTML attributes to be added to the suggestionrenderDecorations?
(RenderDecorations<{ suggestion: Suggestion }>
): A function to render the suggestion as ProseMirror decorations
metadata?
(Record<string, any>
): Extra metadata for the suggestions that can be used to store additional information about them (e.g. their source or their category). It is not used internally by the extension but it may help developers customize how the suggestions are displayed in the UI.
checkChunkForError?
((status: { chunk: string; content: string; range: Range }) => boolean
): A function to check if the chunk contains an error. Returnstrue
if the chunk has an error,false
otherwise. Iftrue
, the stream will be stopped and aStreamingChunkCheckFailedError
will be thrown.onError?
((event: { error: unknown; chunk: string; content: string; range: Range }) => void
): A function to handle errors that occur during streaming.onChunkInserted?
((event: { chunk: string; content: string; range: Range }) => void
): A function to handle when a chunk is streamed. Called after the chunk is inserted into the editor.
Returns
Promise<void>
: A promise that resolves when the stream is complete.
Example
const response = await fetch('/api/generate-html')
// The API endpoint returns a stream of HTML content
const stream = response.body
toolkit.streamHtml(stream)
applyHtmlDiff
Apply context-aware HTML diffs to a chunk or the whole document.
Parameters
diffs
(HtmlDiff[]
): Each item has:context?
(string
): Text/HTML that appears beforedelete
to anchor the changedelete
(string
): Exact HTML to removeinsert
(string
): HTML to insert
options?
(ApplyHtmlDiffOptions
): Options for theapplyHtmlDiff
methodchunkIndex?
(number
): Target chunk index. Default:0
chunkSize?
(number
): The maximum size of a string that can be passed as input to the AI model. Prevents the AI from reading too much content at once so that the context window of the AI model is not exceeded. Default:32000
reviewOptions?
(Omit<ReviewOptions, 'showDiff'>
): Review behavior. Note: diff previews forceshowAsDiff
in compare modemode?
('disabled' | 'review' | 'preview'
): Whether to review the changes before or after applying them.'disabled'
means no review,'review'
means review after applying,'preview'
means preview before applying. Default:'disabled'
displayOptions?
(DisplayOptions<{ suggestion: Suggestion }>
): Customize how suggestions are displayedshowAsDiff?
(boolean
): Whether to show the suggestion as a diff where inserted and original content are displayed side by side. Default:true
diffPosition?
('before' | 'after'
): The position of the diff relative to the suggestion. Default:'before'
attributes?
(Record<string, any>
): Extra HTML attributes to be added to the suggestionrenderDecorations?
(RenderDecorations<{ suggestion: Suggestion }>
): A function to render the suggestion as ProseMirror decorations
metadata?
(Record<string, any>
): Extra metadata for the suggestions that can be used to store additional information about them (e.g. their source or their category). It is not used internally by the extension but it may help developers customize how the suggestions are displayed in the UI.
Returns (ApplyHtmlDiffResult
)
errorMessage
(string | null
):null
when all diffs applied; error message otherwise
Example
// Replace "fine" with emphasized "great" in the first chunk
toolkit.applyHtmlDiff([{ context: '<p>This is ', delete: 'fine', insert: '<em>great</em>' }])
InsertPosition
(type)
The position where the content will be inserted. It can be one of the following values:
Range
: A range of the documentnumber
: A position in the document'selection'
: Replace the current selection with the new content'selectionStart'
: The start of the current selection'selectionEnd'
: The end of the current selection'document'
: Replace the entire document with the new content'documentStart'
: The start of the document'documentEnd'
: The end of the document