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 insert
options? (InsertTextOptions): Options for the insertText method
- position? (InsertPosition): Where to insert. See options. Default: 'selection'
- reviewOptions? (ReviewOptions): Control preview/review behavior
  - mode? ('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'
  - diffMode? ('detailed' | 'full'): How to display the difference between the original and the modified content, when review mode is enabled. 'detailed' compares the documents before and after the change and displays the deleted content and added content as a rich diff. 'full' displays the deleted content and added content in a whole block, as a single change containing the deleted and added content. Default: 'detailed'
  - displayOptions? (DisplayOptions<{ suggestion: Suggestion }>): Customize how suggestions are displayed
    - showAsDiff? (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 suggestion
    - renderDecorations? (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 insert
options? (InsertHtmlOptions): Options for the insertHtml method
- position? (InsertPosition): Where to insert. See options. Default: 'selection'
- reviewOptions? (ReviewOptions): Control preview/review behavior
  - mode? ('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'
  - diffMode? ('detailed' | 'full'): How to display the difference between the original and the modified content, when review mode is enabled. 'detailed' compares the documents before and after the change and displays the deleted content and added content as a rich diff. 'full' displays the deleted content and added content in a whole block, as a single change containing the deleted and added content. Default: 'detailed'
  - displayOptions? (DisplayOptions<{ suggestion: Suggestion }>): Customize how suggestions are displayed
    - showAsDiff? (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 suggestion
    - renderDecorations? (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 slice
options? (InsertJsonOptions): Options for the insertJson method
- position? (InsertPosition): Where to insert. See options. Default: 'selection'
- reviewOptions? (ReviewOptions): Control preview/review behavior
  - mode? ('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'
  - diffMode? ('detailed' | 'full'): How to display the difference between the original and the modified content, when review mode is enabled. 'detailed' compares the documents before and after the change and displays the deleted content and added content as a rich diff. 'full' displays the deleted content and added content in a whole block, as a single change containing the deleted and added content. Default: 'detailed'
  - displayOptions? (DisplayOptions<{ suggestion: Suggestion }>): Customize how suggestions are displayed
    - showAsDiff? (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 suggestion
    - renderDecorations? (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 generator.
options? (StreamTextOptions): Options for the streamText method
- position? (InsertPosition): Where to insert. See options. Default: 'selection'
- reviewOptions? (ReviewOptions): Control preview/review behavior
  - mode? ('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'
  - diffMode? ('detailed' | 'full'): How to display the difference between the original and the modified content, when review mode is enabled. 'detailed' compares the documents before and after the change and displays the deleted content and added content as a rich diff. 'full' displays the deleted content and added content in a whole block, as a single change containing the deleted and added content. Default: 'detailed'
  - displayOptions? (DisplayOptions<{ suggestion: Suggestion }>): Customize how suggestions are displayed
    - showAsDiff? (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 suggestion
    - renderDecorations? (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. Returns true if the chunk has an error, false otherwise. If true, the stream will be stopped and a StreamingChunkCheckFailedError 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> | ReadableStream<string | Uint8Array>): The stream of HTML content. It can be any object that implements the Async Iterable protocol, such as a ReadableStream or a generator.
options? (StreamHtmlOptions): Options for the streamHtml method
- position? (InsertPosition): Where to insert. See options. Default: 'selection'
- reviewOptions? (ReviewOptions): Control preview/review behavior
  - mode? ('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'
  - diffMode? ('detailed' | 'full'): How to display the difference between the original and the modified content, when review mode is enabled. 'detailed' compares the documents before and after the change and displays the deleted content and added content as a rich diff. 'full' displays the deleted content and added content in a whole block, as a single change containing the deleted and added content. Default: 'detailed'
  - displayOptions? (DisplayOptions<{ suggestion: Suggestion }>): Customize how suggestions are displayed
    - showAsDiff? (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 suggestion
    - renderDecorations? (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. Returns true if the chunk has an error, false otherwise. If true, the stream will be stopped and a StreamingChunkCheckFailedError 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)

`applyHtmlPatch`

Apply context-aware HTML diffs to a chunk or the whole document.

Parameters

operations (PatchOperation[]): A list of patch operations.
options? (ApplyHtmlPatchOptions): Options for the applyHtmlPatch method
- chunkIndex? (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, 'diffMode'>): Control preview/review behavior.
  - mode? ('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 displayed
    - showAsDiff? (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 suggestion
    - renderDecorations? (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.

`PatchOperation` (type)

A PatchOperation can be one of two types:

JumpOperation: A navigation operation that moves the cursor to a specific context in the document.

type ('jump'): The operation type identifier
context (string): The context string to search for and position the cursor after

ReplaceOperation: A replace operation that deletes and inserts text at the current cursor position.

Replace operations perform the actual content modifications by removing specified text and replacing it with new text. The delete text must be found at the current cursor position for the operation to succeed.

type ('replace'): The operation type identifier
delete (string): The exact text to delete from the document (can be empty for pure insertions)
insert (string): The text to insert in place of the deleted text

Returns (`ApplyHtmlPatchResult`)

docChanged (boolean): Whether the document was modified
error (ApplyPatchError | null): Error if the diff application failed because not all diffs could be applied, null if successful

The method can edit the document but return an error at the same time. This happens when some operations are applied but some fail.

`ApplyPatchError` (type)

Error thrown when applying a Universal Patch Format operation fails. This error provides comprehensive context about the failure, including which operation failed, what operations succeeded before it, and the current state of the content.

operationIndex (number): The zero-based index of the operation that failed
previousOperations (PatchOperation[]): Array of operations that were successfully applied before the failure
operation (PatchOperation): The operation that failed to apply
contentAfterCursor (string): The content after the current cursor position when the error occurred

Example

// Replace "fine" with emphasized "great" in the first chunk
toolkit.applyHtmlPatch([{ type: 'replace', 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 document
number: 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

PreviouslyRead the document

Next upSchema awareness

insertText

Parameters

Returns

Example

insertHtml

Parameters

Returns

Example

insertJson

Parameters

Returns

Example

streamText

Parameters

Returns

Example

streamHtml

Parameters

Returns

Example

applyHtmlPatch

Parameters

PatchOperation (type)

Returns (ApplyHtmlPatchResult)

ApplyPatchError (type)

Example

InsertPosition (type)

`insertText`

`insertHtml`

`insertJson`

`streamText`

`streamHtml`

`applyHtmlPatch`

`PatchOperation` (type)

Returns (`ApplyHtmlPatchResult`)

`ApplyPatchError` (type)

`InsertPosition` (type)