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'
  - 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 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'
  - 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 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'
  - 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 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 ReadableStream or 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'
  - 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 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>): 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 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'
  - 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 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)

`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 before delete to anchor the change
- delete (string): Exact HTML to remove
- insert (string): HTML to insert
options? (ApplyHtmlDiffOptions): Options for the applyHtmlDiff 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, 'showDiff'>): Review behavior. Note: diff previews force showAsDiff in compare mode
  - 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.

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 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

insertText

Parameters

Returns

Example

insertHtml

Parameters

Returns

Example

insertJson

Parameters

Returns

Example

streamText

Parameters

Returns

Example

streamHtml

Parameters

Returns

Example

applyHtmlDiff

Parameters

Returns (ApplyHtmlDiffResult)

Example

InsertPosition (type)

`insertText`

`insertHtml`

`insertJson`

`streamText`

`streamHtml`

`applyHtmlDiff`

Returns (`ApplyHtmlDiffResult`)

`InsertPosition` (type)