@witchcraft/editor 0.0.1

package/src/runtime/pm/features/DocumentApi/DocumentApi.ts

@@ -0,0 +1,272 @@
+import { debounce, type DebounceQueue } from "@alanscodelog/utils/debounce"
+import { unreachable } from "@alanscodelog/utils/unreachable"
+import { type Content, Editor, type EditorOptions } from "@tiptap/core"
+import type { Schema } from "@tiptap/pm/model"
+import type { EditorState, Plugin, Transaction } from "@tiptap/pm/state"
+import { toRaw } from "vue"
+
+import type { DocId, DocumentApiInterface, EmbedId, OnSaveDocumentCallback, OnUpdateDocumentCallback } from "./types.js"
+import { convertTransactionForFullState } from "./utils/convertTransactionForFullState.js"
+import { getEmbedJson } from "./utils/getEmbedJson.js"
+import { getEmbedNodeFromDoc } from "./utils/getEmbedNodeFromDoc.js"
+
+// IMPORTANT: We must be super careful to unwrap the state proxy with toRaw before passing it to anything or it can create painful to debug errors.
+
+/**
+ * Configures the document api which tells the editor how to load/unload/save/cache documents, including embedded ones.
+ *
+ * The cache implementation is left up to the user, hence why it's defined as a get/set interface. A load function must be provided for requesting uncached documents.
+ *
+ * `save` is optional, but you probably want to save. The function is automatically debounced the configured amount.
+ *
+ * **Any function that needs to return a document should return it unwrapped with toRaw if it was a ref or in a ref or reactive. **
+ *
+ * A `refCounter` object can be provided with the respective load/unload functions to be notified when embedded views load/unload documents to reference count them and unload them once no editors have them in use.
+ *
+ * It is safe to call load multiple times for the same document, the actual load function will only be called once per document, but the refCounter will be called multiple times.
+ *
+ * The `getTitle` function can be provided to customize the title of the embedded document. It's passed the full embed id and returns it as docId#blockId by default.
+ *
+ * If there are extensions that use onCreate to set state or have plugins that need to change the state on init with appendTransaction, they will not work since there is no view to initialize the plugins. To get around this, plugins can specify a stateInit function that will be called with a transaction from the initial loaded state which it can then modify while having access to `this` and the extension options.
+ *
+ * The api creates a default instance of the editor to copy plugins from, this can be replaced by passing your own editor instance.
+ *
+ * See {@link useTestDocumentApi} for an example of how to set things up.
+ */
+export class DocumentApi<
+	T extends Record<string, any> = Record<string, any>
+> implements DocumentApiInterface<T> {
+	private readonly _callbacks: {
+		update: OnUpdateDocumentCallback[]
+		saved: OnSaveDocumentCallback[]
+		saving: OnSaveDocumentCallback[]
+	} = { update: [], saved: [], saving: [] }
+
+	private readonly _load: (docId: string, schema: Schema, plugins: Plugin[]) => Promise<{ state: EditorState, data?: T }>
+
+	private readonly _save?: (docId: string) => Promise<void>
+
+	private readonly _saveQueue: DebounceQueue = {}
+
+	readonly save: DocumentApiInterface<T>["save"]
+
+	private readonly _cache: {
+		get: (docId: string) => EditorState | undefined
+		set: (docId: string, state: EditorState) => void
+	}
+
+	/**
+	 * The refCounter is called every time an editor loads or unloads a document. It's used to keep track of the number of editors that are using a document, and to unload it when no editors are using it.
+	 *
+	 * Note that you need not immediately unload the cached document. So long as the count is immediatly updated you can set a timeout to actually delete the cache entry (be sure to check the count it still 0 and you can delete it).
+	 */
+	private readonly _refCounter: {
+		load: (docId: string, loaded: { state: EditorState, data?: T }) => void
+		unload: (docId: string) => void
+	}
+
+	getSuggestions: DocumentApiInterface["getSuggestions"]
+
+	getEmbedTitle: DocumentApiInterface["getEmbedTitle"]
+
+	postEditorInit: DocumentApiInterface["postEditorInit"]
+
+	// editor + updateState does not work :/
+	preEditorInit: DocumentApiInterface["preEditorInit"] = (_docId, options, state) => {
+		options.content = state.doc.toJSON()
+		return options
+	}
+
+	updateFilter?: DocumentApiInterface["updateFilter"] = () => true
+
+	editor: Editor
+
+	constructor({
+		editorOptions,
+		getTitle,
+		getSuggestions,
+		load,
+		save,
+		saveDebounce = 1000,
+		cache,
+		refCounter,
+		postEditorInit,
+		preEditorInit,
+		updateFilter
+	}: {
+		/**
+		 * The editor options for the internal instance to use to keep track of the document state. It should include the same extensions as the root editor.
+		 */
+		editorOptions: Partial<EditorOptions>
+		getTitle?: (docId: string, blockId?: string) => string
+		getSuggestions: DocumentApiInterface["getSuggestions"]
+		load: (docId: string, schema: Schema, plugins: Plugin[]) => Promise<{ state: EditorState, data?: T }>
+		save?: DocumentApi["_save"]
+		saveDebounce?: number
+		cache: DocumentApi["_cache"]
+		refCounter: DocumentApi<T>["_refCounter"]
+		postEditorInit?: DocumentApi["postEditorInit"]
+		preEditorInit?: DocumentApi["preEditorInit"]
+		updateFilter?: DocumentApi["updateFilter"]
+	}) {
+		this.updateFilter = updateFilter
+		this.getEmbedTitle = getTitle
+			? ({ docId, blockId }: EmbedId) => getTitle(docId, blockId)
+			: ({ docId, blockId }: EmbedId) => `${docId}${blockId ? `#${blockId}` : ""}`
+		this._load = load
+		this._cache = cache
+		this._refCounter = refCounter
+		this._save = save
+		const debouncedSave = debounce(this._saveDocument.bind(this), saveDebounce, {
+			queue: this._saveQueue,
+			// even though save is async, promisified debounce is slightly more expensive because it creates a new function with every call
+			// and we don't really need that
+			promisify: false
+		}) as any
+
+		this.save = function save(docId: string): void {
+			for (const cb of this._callbacks.saving) {
+				cb(docId)
+			}
+			debouncedSave(docId)
+		}
+
+		this.postEditorInit = postEditorInit ?? (() => {})
+		if (preEditorInit) this.preEditorInit = preEditorInit
+		this.getSuggestions = getSuggestions
+		this.editor = new Editor({
+			...editorOptions,
+			extensions: [...editorOptions.extensions!],
+			injectCSS: false
+		})
+	}
+
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	async _saveDocument(docId: string): Promise<void> {
+		if (this._save) {
+			await this._save(docId)
+			for (const cb of this._callbacks.saved) {
+				cb(docId)
+			}
+		} else {
+			// eslint-disable-next-line no-console
+			console.warn("No save function provided, ignoring save request.")
+		}
+	}
+
+	updateDocument(
+		embedId: DocId,
+		tr: Transaction,
+		updaterSymbol?: symbol
+	): void {
+		if (this.updateFilter && this.updateFilter(tr) === false) return
+		const stateBefore = this.getFromCache(embedId, { errorIfNotFound: true })
+		const modifiedTr = convertTransactionForFullState(stateBefore, tr)
+		const newState = stateBefore.apply(modifiedTr)
+		this._cache.set(embedId.docId, newState)
+		for (const cb of this._callbacks.update) {
+			cb(embedId, modifiedTr, toRaw(stateBefore), toRaw(newState), updaterSymbol)
+		}
+	}
+
+	addEventListener(type: "saving" | "saved", cb: OnSaveDocumentCallback): void
+
+	addEventListener(type: "update", cb: OnUpdateDocumentCallback): void
+
+	addEventListener(
+		type: "update" | "saving" | "saved",
+		cb: OnUpdateDocumentCallback | OnSaveDocumentCallback
+	): void {
+		this._callbacks[type].push(cb as any)
+	}
+
+	removeEventListener(type: "saving" | "saved", cb: OnSaveDocumentCallback): void
+
+	removeEventListener(type: "update", cb: OnUpdateDocumentCallback): void
+
+	removeEventListener(
+		type: "update" | "saving" | "saved",
+		cb: OnUpdateDocumentCallback | OnSaveDocumentCallback
+	): void {
+		const cbIndex = this._callbacks[type].indexOf(cb as any)
+		if (cbIndex === -1) {
+			throw new Error("Tried to remove a callback that was not registered.")
+		}
+		this._callbacks[type].splice(cbIndex, 1)
+	}
+
+	unload({ docId }: DocId): void {
+		this._refCounter.unload(docId)
+	}
+
+	private readonly _loading: Record<string, Promise<{ state: EditorState, data?: T }> | undefined> = {}
+
+	async load({ docId }: DocId): Promise<{ state: EditorState, data?: T }> {
+		// prevent double loading of the same document
+		// this also prevents issues from non-determenistic plugin stateInit functions
+		this._loading[docId] ??= this._loadInternal({ docId })
+
+		const res = await this._loading[docId]
+		if (res === undefined) unreachable()
+		this._loading[docId] = undefined
+		this._refCounter.load(docId, res)
+		this._cache.set(docId, res.state)
+		return res
+	}
+
+	private async _loadInternal({ docId }: DocId): Promise<{ state: EditorState, data?: T }> {
+		const cachedState = this.getFromCache({ docId }, { errorIfNotFound: false })
+		if (cachedState) {
+			const res = { state: cachedState }
+			this._refCounter.load(docId, res)
+			return res
+		}
+
+		const schema = this.editor.schema
+		const loaded = await this._load(
+			docId,
+			schema,
+			[...this.editor.extensionManager.plugins]
+		)
+		let state = loaded.state
+		const tr = state.tr
+
+		tr.setMeta("addToHistory", false)
+		for (const plugin of state.plugins) {
+			if (plugin.spec.stateInit) {
+				plugin.spec.stateInit(tr)
+			}
+		}
+
+		state = state.apply(tr)
+		return { data: loaded.data, state }
+	}
+
+	getFullState(docId: DocId): EditorState {
+		return this.getFromCache(docId, { errorIfNotFound: true })
+	}
+
+	getFromCache(docId: DocId, options?: { errorIfNotFound: true }): EditorState
+
+	getFromCache(docId: DocId, options?: { errorIfNotFound?: boolean }): EditorState | undefined
+
+	getFromCache({ docId }: DocId, options?: { errorIfNotFound?: boolean }): EditorState | undefined {
+		const cached = this._cache.get(docId)
+		if (cached) return cached
+		if (options?.errorIfNotFound) {
+			throw new Error(`Could not find cached state for document ${docId}. Expected document to be loaded.`)
+		}
+		return undefined
+	}
+
+	getEmbeddedContent(embedId: EmbedId): Content | undefined {
+		const state = this.getFullState(embedId)
+		const json = state.doc.toJSON()
+		const nodeWanted = getEmbedNodeFromDoc(json, embedId.blockId)
+		if (embedId.blockId && !nodeWanted) {
+			return undefined
+		} else {
+			return getEmbedJson(nodeWanted) ?? json
+		}
+	}
+}

package/src/runtime/pm/features/DocumentApi/composables/useEditorContent.ts

@@ -0,0 +1,105 @@
+import type { Content, Editor, EditorOptions } from "@tiptap/core"
+import type { Transaction } from "@tiptap/pm/state"
+import { nextTick, onBeforeUnmount, type Ref, watch } from "vue"
+
+import type { DocumentApiInterface, OnUpdateDocumentCallback } from "../types.js"
+import { convertTrForInstance } from "../utils/convertTrForInstance.js"
+
+/**
+	* Provides two ways to load content into the editor.
+	*
+	* The simple one, which is just to provide a content ref.
+	*
+	* And the more advanced one which uses the document api to load the content. This requires passing the embed api and an id to load.
+	*
+	* The second option is usually the best, as multiple editors can load the same content and it's automatically kept in sync. See {@link DocumentApi} for more info.
+	*/
+export function useEditorContent(
+	editor: Ref<Editor | undefined>,
+	content: Ref<Content | undefined>,
+	id: Ref<string | undefined>,
+	documentApi: DocumentApiInterface | undefined,
+	recreate: (modifyOptions?: (options: Partial<EditorOptions>) => Partial<EditorOptions>) => void
+): void {
+	const selfSymbol = Symbol(`self${Math.random()}`)
+	function onTransaction({ transaction: tr }: { transaction: Transaction }): void {
+		if (!documentApi || !id.value || !tr.docChanged || tr.getMeta("ignore")) {
+			return
+		}
+		tr.setMeta("no-step-convert", true)
+		documentApi.updateDocument({ docId: id.value }, tr, selfSymbol)
+	}
+	const onUpdateDocument: OnUpdateDocumentCallback = (embedId, tr, __, ___, symbol) => {
+		if (symbol !== selfSymbol
+			&& !tr.getMeta("ignore")
+			&& tr.docChanged
+			&& embedId.docId === id.value
+		) {
+			tr.setMeta("ignore", true)
+			const convertedTr = convertTrForInstance(
+				tr,
+				editor.value!.state
+			)
+			editor.value?.view.dispatch(convertedTr)
+		}
+		if (tr.docChanged) {
+			void documentApi?.save(embedId.docId)
+		}
+	}
+	let attached = false
+
+	async function load(changed: boolean): Promise<void> {
+		if (content.value) {
+			editor.value?.commands.setContent(content.value)
+		} else if (documentApi) {
+			if (changed && id.value) {
+				await documentApi.load({ docId: id.value })
+				const state = documentApi.getFullState({ docId: id.value })
+
+				recreate(options => documentApi.preEditorInit?.(id.value!, { ...options }, state))
+				await nextTick(async () => {
+					editor.value!.on("transaction", onTransaction)
+					documentApi!.addEventListener("update", onUpdateDocument)
+					documentApi.postEditorInit(id.value!, editor.value!)
+					attached = true
+				})
+			}
+		}
+	}
+	function unload(oldId: string): void {
+		if (oldId !== undefined && documentApi) {
+			documentApi.unload({ docId: oldId })
+			if (attached) {
+				documentApi.removeEventListener("update", onUpdateDocument)
+				editor.value?.off("transaction", onTransaction)
+				attached = false
+			}
+		}
+	}
+
+	watch([content, id, editor], async ([_newContent, newId], [_oldContent, oldId]) => {
+		if (!editor.value) {
+			return
+		}
+		if (!content.value && (!id.value || !documentApi)) {
+			throw new Error("No content or id and document api provided.")
+		}
+		if (id.value && !documentApi) {
+			throw new Error("Id provided but no document api provided.")
+		}
+
+		if (oldId !== undefined && newId !== oldId && documentApi) {
+			unload(oldId)
+			await load(true)
+		} else if (_newContent) {
+			await load(false)
+		}
+	}, { deep: false })
+
+	void load(true)
+	onBeforeUnmount(() => {
+		if (id.value) {
+			unload(id.value)
+		}
+	})
+}

package/src/runtime/pm/features/DocumentApi/composables/useTestDocumentApi.ts

@@ -0,0 +1,95 @@
+import { delay } from "@alanscodelog/utils/delay"
+import { keys } from "@alanscodelog/utils/keys"
+import { unreachable } from "@alanscodelog/utils/unreachable"
+import type { EditorOptions } from "@tiptap/core"
+import { createDocument, generateJSON } from "@tiptap/core"
+import type { Schema } from "@tiptap/pm/model"
+import type { Plugin } from "@tiptap/pm/state"
+import { EditorState } from "@tiptap/pm/state"
+import { type Ref, ref, toRaw } from "vue"
+
+import { testExtensions } from "../../../testSchema.js"
+import { DocumentApi } from "../DocumentApi.js"
+import type { DocumentApiInterface } from "../types.js"
+
+type Cache = Record<string, { state?: EditorState, count: number }>
+
+/** Creates a simple instance of the DocumentApi for testing purposes. */
+export function useTestDocumentApi(
+	editorOptions: Partial<EditorOptions>,
+	embeds: Record<string, { content: any, title?: string }>,
+	{ loadDelay = 0 }: { loadDelay?: number } = { }
+): {
+	cache: Ref<Cache>
+	documentApi: DocumentApiInterface
+	embeds: Record<string, { content: any, title?: string }>
+} {
+	const cache = ref<Cache>({})
+
+	const documentApi = new DocumentApi({
+		editorOptions,
+
+		getSuggestions: async (searchString: string): Promise<{ title: string, docId: string }[]> => {
+			const res = []
+			for (const docId of keys(embeds)) {
+				const title = embeds[docId].title ?? docId
+				if (title.includes(searchString)) {
+					res.push({ title, docId })
+				}
+			}
+			if (loadDelay) {
+				await delay(loadDelay)
+			}
+			return res
+		},
+		getTitle: (docId, blockId) => (embeds[docId]?.title ?? docId) + (blockId ? `#${blockId}` : ""),
+		cache: {
+			get(docId: string): EditorState | undefined {
+				return toRaw(cache.value[docId]?.state)
+			},
+			set(docId: string, state: EditorState): void {
+				cache.value[docId].state = state
+			}
+		},
+		load: async (
+			docId: string,
+			schema: Schema,
+			plugins: Plugin[]
+		): Promise<{ state: EditorState }> => {
+			if (loadDelay) {
+				await delay(loadDelay)
+			}
+			// just so we catch errors where we're not correctly supplying the needed embeds for testing
+			if (!embeds[docId]) {
+				throw new Error(`No embed found for docId ${docId} in: ${JSON.stringify(embeds, null, "\t")}`)
+			}
+
+			const json = generateJSON(embeds[docId].content as any, testExtensions)
+			const doc = createDocument(json, schema)
+			const state = EditorState.create({
+				doc,
+				schema,
+				plugins
+			})
+			return { state }
+		},
+		refCounter: {
+			load(docId: string, loaded) {
+				cache.value[docId] ??= { ...loaded, count: 0 }
+				cache.value[docId].count++
+			},
+			unload: (docId: string) => {
+				if (cache.value[docId]) {
+					if (cache.value[docId].count === 1) {
+						delete cache.value[docId]
+					} else {
+						cache.value[docId].count--
+					}
+				} else {
+					unreachable()
+				}
+			}
+		}
+	})
+	return { documentApi, cache, embeds }
+}

package/src/runtime/pm/features/DocumentApi/types.ts

@@ -0,0 +1,143 @@
+import type { Content, Editor, EditorOptions } from "@tiptap/core"
+import type { EditorState, Transaction } from "@tiptap/pm/state"
+import type { InjectionKey } from "vue"
+
+export const documentApiInjectionKey = Symbol("documentApiInjectionKey") as InjectionKey<DocumentApiInterface>
+
+export type DocId = {
+	docId: string
+}
+export type BlockId = {
+	blockId?: string
+}
+/** When the user initially creates an embed, it's docId will be undefined. */
+export type MaybeEmbedId = Partial<DocId> & BlockId
+export type EmbedId = DocId & BlockId
+
+export type OnUpdateDocumentCallback = (
+	embedId: DocId,
+	tr: Transaction,
+	oldEditorState: EditorState,
+	newEditorState: EditorState,
+	selfSymbol?: symbol
+) => void
+export type OnSaveDocumentCallback = (docId: string) => void
+
+// todo separate internal documentation of api from the options that are also used int the default implementation to configure it.
+export type DocumentApiInterface<
+	T extends Record<string, any> = Record<string, any>
+> = {
+	/** Debounced save (to storage) function. Use the event listeners to get notified when saving finishes. */
+	save: (docId: string) => void
+	getEmbeddedContent: (embedId: EmbedId) => Content | undefined
+	getFromCache: (docId: DocId, options?: { errorIfNotFound?: boolean }) => EditorState | undefined
+	/** Load should be called the first time, before attempting to load the state. */
+	getFullState: (docId: DocId) => EditorState
+	/** Like {@link DocumentApi.preEditorInit}, but after initializing and loading the document (and before the transaction listeners are added). */
+	postEditorInit: (docId: string, editor: Editor) => void
+	/**
+	 * Sets options before initializing the editor. By default just does `options.content = state.doc.toJSON()`, but can be useful when managing the document state in some other way (e.g. collab.
+	 *
+	 * Also useful for creating per-doc instances for certain extensions, such as Collaboration.
+	 *
+	 * This is a bit tricky to do normally since the editor component initializes the editor before the document is loaded and is re-used (the wrapper Editor *component*, not the editor) when the document changes.
+	 *
+	 * So this hook can be used to add these additional per-doc instances of extensions. Be sure to clone the properties you are modifying. They are only shallow cloned before being passed to the function.
+	 *
+	 * ```ts
+	 * preEditorInit(docId, options: Partial<EditorOptions>, state: EditorState) {
+	 * 	// we do not need to set options.content when using collab
+	 * 	// so no options.content = state.doc.toJSON()
+	 * 	const ydoc = cache.value[docId].ydoc
+	 * 	// it's suggested you add the collab extension only here
+	 *		// otherwise you would have to initially configure it with a dummy document
+	 * 	const collabExt = Collaboration.configure({
+	 * 		document: ydoc
+	 * 	}) as any
+	 * 	options.extensions = [
+	 * 		...(options.extensions ?? []),
+	 * 		collabExt
+	 * 	]
+	 * 	return options
+	 * },
+	 * load: async (
+	 * 	docId: string,
+	 * 	schema: Schema,
+	 * 	plugins: Plugin[],
+	 * ) => {
+	 * 	if (cache.value[docId]?.state) {
+	 * 		return { state: toRaw(cache.value[docId].state) }
+	 * 	}
+	 * 	const doc = getFromYourDb(docId)
+	 * 	const decoded = toUint8Array(doc.contentBinary)
+	 * 	const yDoc = new Y.Doc()
+	 * 	Y.applyUpdate(yDoc, decoded)
+	 *
+	 * 	const yjs = initProseMirrorDoc(yDoc.getXmlFragment("prosemirror"), schema)
+	 * 	const state = EditorState.create({
+	 * 		doc: yjs.doc,
+	 * 		schema,
+	 * 		plugins:[
+	 * 			...plugins,
+	 * 			// the document api's yjs instance
+	 * 			ySyncPlugin(yDoc.getXmlFragment("prosemirror"), {mapping:yjs.mapping}),
+	 * 		]
+	 * 	})
+	 * 	// return the state and any additional data we want refCounter.load to be called with.
+	 * 	return { state, doc, yDoc }
+	 * },
+	 * updateFilter(tr:Transaction) {
+	 * 	const meta = tr.getMeta(ySyncPluginKey)
+	 * 	if (meta) return false
+	 * 	return true
+	 * },
+	 * ```
+	 * See {@link DocumentApi.updateFilter} for why yjs (and other syncronization mechanisms) might need to ignore transactions.
+	 */
+	preEditorInit: (docId: string, options: Partial<EditorOptions>, state: EditorState) => Partial<EditorOptions>
+	/**
+	 * Return false to ignore the transaction.
+	 *
+	 * This is useful when using a secondary syncronization mechanism, such as yjs.
+	 *
+	 * If you load all editors of a file with yjs's plugin and point to the same ydoc, yjs's plugin will sync them. But that means that when the DocumentApi tries to sync the transactions they will have already been applied and the document update will fail.
+	 *
+	 * So we have to ignore all of yjs's transactions, but NOT transactions from partially embedded docs => full state, as these do not pass through yjs.
+	 */
+	updateFilter?: (tr: Transaction) => boolean | undefined
+	updateDocument: (
+		embedId: DocId,
+		tr: Transaction,
+		selfSymbol?: symbol
+	) => void
+	addEventListener (type: "saving" | "saved", cb: OnSaveDocumentCallback): void
+	addEventListener (type: "update", cb: OnUpdateDocumentCallback): void
+	removeEventListener (type: "saving" | "saved", cb: OnSaveDocumentCallback): void
+	removeEventListener (type: "update", cb: OnUpdateDocumentCallback): void
+
+	/** For the embedded document picker, should return suggestions for the search string. */
+	getSuggestions: (searchString: string) => Promise<{ title: string, docId: string }[]>
+	/** How to format the title of the embedded document. Defaults to docId#blockId */
+	getEmbedTitle: (embedId: EmbedId) => string
+	/**
+	 * Tells the document api how to load an unloaded document and any additional data. Whatever this function returns will be passed to the refCounter.load option in the default DocumentApi implementation.
+	 *
+	 * ```ts
+	 *	 load: async ( docId: string, schema: Schema, plugins: Plugin[],) => {
+	 * 	const dbDoc = getFromYourDb(docId)
+	 *
+	 * 	const state = EditorState.create({
+	 * 		doc: yjs.doc,
+	 * 		schema,
+	 * 		plugins
+	 * 	})
+	 * 	// return the state and any additional data we want to cache
+	 * 	return { state, data: { dbDoc } }
+	 * },
+	 * ```
+	 * See {@link DocumentApi.preEditorInit} for how to set this up with sync (e.g. yjs).
+	 */
+	load: (docId: DocId) => Promise<{ state: EditorState, data?: T }>
+	/** Notifies the document api that an editor has unloaded the document. */
+	unload: (docId: DocId) => void
+}

package/src/runtime/pm/features/DocumentApi/utils/convertFullTransactionForPartialState.ts

@@ -0,0 +1,54 @@
+import type { EditorState, Transaction } from "@tiptap/pm/state"
+import { type ReplaceStep, Step } from "@tiptap/pm/transform"
+
+import { copyMeta } from "./copyMeta.js"
+import { getStateEmbedRange } from "./getStateEmbedRange.js"
+
+import { getDiffReplacementRange } from "../../../utils/getDiffReplacementRange.js"
+import type { EmbedId } from "../types.js"
+
+export function convertFullTransactionForPartialState(
+	state: EditorState,
+	tr: Transaction,
+	embedId: EmbedId
+): Transaction | undefined {
+	const blockId = embedId.blockId
+	if (!blockId) {
+		// see https://github.com/ueberdosis/tiptap/issues/1883
+		// and https://github.com/ueberdosis/tiptap/issues/74#issuecomment-460206175
+		const steps: ReplaceStep[] = JSON.parse(
+			JSON.stringify(tr.steps)
+		).map((step: any) => Step.fromJSON(state.schema, step))
+		// the documents are the same
+		const intTr = state.tr as Transaction
+		copyMeta(tr, intTr)
+		intTr.setMeta("ignore", true)
+		for (const step of steps) {
+			intTr.step(step)
+		}
+		return intTr
+	}
+
+	const { start: nodeStartExisting } = getStateEmbedRange(state.doc, embedId)
+	const { start: nodeStart } = getStateEmbedRange(
+		tr.doc,
+		embedId
+	)
+	if (nodeStart === undefined || nodeStartExisting === undefined) return undefined
+	const intTr = state.tr as Transaction
+	copyMeta(tr, intTr)
+
+	intTr.setMeta("ignore", true)
+	const existingNode = state.doc.nodeAt(nodeStartExisting)
+	const newNode = tr.doc.nodeAt(nodeStart)
+	const convertedNewNode = newNode ? state.schema.nodeFromJSON(newNode.toJSON()) : undefined
+	if (!existingNode || !convertedNewNode) return undefined
+
+	// when the change crosses a boundary it's way too hard to find the right steps
+	// so we just replace the whole different part
+	const diff = getDiffReplacementRange(existingNode, convertedNewNode, nodeStartExisting - 1)
+	if (diff) {
+		intTr.replace(2 + diff.start, 2 + diff.end, convertedNewNode.slice(diff.sliceStart, diff.sliceEnd))
+	}
+	return intTr
+}

package/src/runtime/pm/features/DocumentApi/utils/convertTrForInstance.ts

@@ -0,0 +1,24 @@
+import type { EditorState, Transaction } from "@tiptap/pm/state"
+import { Step } from "@tiptap/pm/transform"
+
+import { copyMeta } from "./copyMeta.js"
+
+/* The schemas are different between editor states, this converts a transaction for use from one instance to another. */
+export function convertTrForInstance(
+	tr: Transaction,
+	/** We convert to the schema from this state. */
+	otherState: EditorState
+): Transaction {
+	const extTr = otherState.tr as Transaction
+	copyMeta(tr, extTr)
+	// see https://github.com/ueberdosis/tiptap/issues/1883
+	// and https://github.com/ueberdosis/tiptap/issues/74#issuecomment-460206175
+	const steps = JSON.parse(
+		JSON.stringify(tr.steps)
+	).map((step: any) => Step.fromJSON(otherState.schema, step))
+	for (const step of steps) {
+		extTr.step(step)
+	}
+
+	return extTr
+}