EmendAi Extension

EmendAi is the Tiptap extension that lets emend work with your editor. Every editor that uses an emend AI component needs it. It does two things:

It keeps a version number for your document, so emend knows when a suggestion is out of date.
It draws the highlight and the suggestion preview on top of your text, without saving them into the document.

import { EmendAi } from "@emend/ai/tiptap"

Setup

import { EmendAi } from "@emend/ai/tiptap"
import { Markdown } from "@tiptap/markdown"
import StarterKit from "@tiptap/starter-kit"

const extensions = [StarterKit, Markdown, EmendAi]

It has no options. Add it to the same editor you pass to your AI component or to useEditorAi.

Editor commands

Most apps never call these. The AI components and useEditorAi call them for you.

Shows a suggestion preview over a range of text. It returns false if the extension is missing, the range is invalid, another suggestion is already showing, or the document has changed since the request.

`clearEmendProposal(options?)`

Removes the suggestion preview. Pass { proposalId } to remove only that suggestion, or pass nothing to remove whichever one is showing.

editor.commands.clearEmendProposal({ proposalId })

State helpers

`getEmendAiEditorState(editor)`

Returns what emend knows about the editor right now, or null if the editor is missing, destroyed, or does not have the extension.

Field	Meaning
`revisionCounter`	The document version. Goes up by one on every change.
`activeProposalId`	The ID of the suggestion being previewed.
`targetRange`	Where in the document the suggestion will go.
`sourceRevision`	The document version when the request was sent.
`stale`	`true` if the document changed while the suggestion was showing.
`previewKind`	`supported-markdown`, `plain-text-fallback`, or `null`.

`setEmendSelectionDecoration(editor, range)`

Highlights the selected text while the AI is working, so it stays visible after the editor loses focus. Pass null to remove it. Returns false if the range is invalid, the editor is missing, or a suggestion is already showing.

When a suggestion goes out of date

Every change to the document raises the version number. If a suggestion is showing when that happens, emend removes the preview and marks it out of date. Moving the cursor or changing the selection does not count as a change.

Using emend without React

createEmendTiptapAdapter(editor, options?) gives you the building blocks that useEditorAi uses: reading text, checking the answer, showing and hiding the preview, and Accept and Reject. Only use it if you are not using React, or you need full control over each step.

import { createEmendTiptapAdapter } from "@emend/ai/tiptap"

const adapter = createEmendTiptapAdapter(editor, {
  limits: { maxTargetMarkdownLength: 4_000 },
  linkProtocols: ["notion"],
  contextProjection: (context) =>
    editor.schema.nodeFromJSON(context).textContent,
})

contextProjection is plain text to send to the AI when part of your document cannot be turned into Markdown. Pass a string, or a function that builds the text from the document when each request starts.

For React apps, use useEditorAi instead.