Authored Changes

Suggestion is a behavior and presentation layer over authored changes. It does not define another change record, decision result, or persistence format.

Install authored changes

AuthoredPlugin resolves the author from the Plate editor's userId once per transaction:

An editor without a userId writes as the local user, 'local', so a solo editor needs no setup, AI suggestions included. Pass an authenticated, stable user ID whenever more than one person writes the document.

Capture changes

An editing view applies ordinary updates as written. Begin a proposal inside the transaction before applying its document mutation:

Pass { changeId } to name the proposal, or to add the transaction's writes to the pending change with that ID. An ID whose change was already decided starts a new change. IDs starting with ~edit: belong to Editing and are refused.

Import a compared revision

Compare a fixed draft with the accepted document, then publish its canonical change as one native proposal:

groupIds selects comparison groups and includes their required dependencies. The result maps selected group IDs to the native change ID. Import checks the schema, accepted content, and authored frontier before writing; handle stale, blocked, invalid, and unavailable without treating them as applied proposals. The comparison must be a two-way comparison against the live accepted document.

Configure a view

Set the starting intent on EditorRoot:

The editor must install an authored plugin, either directly or through SuggestionPlugin. Changing the authored prop updates this view. Rerendering with an equivalent value preserves later mode changes made through the mounted view's portal.

For an interactive mode control, let SuggestionPlugin change the intent:

To read the document with every pending change decided, switch the view to a preview:

A preview throws on a plain edit, but some other writes still change the stored document, such as an update that makes a decision, undo and redo, and remote collaboration changes.

Typing inside struck text splits the pending deletion around the new text. An edit view applies that text as written, and a propose view records it as an insertion. A propose view refuses a write it cannot record as a proposal, such as a change inside a table, and rolls it back; api.subscribeRefusals(listener) reports each refusal.

Deleting a block that owns a content root in a propose view strikes the block and leaves the root's content unchanged and unmarked, so style the root as deleted in the block's component. Typing or pasting inside that root writes nothing until someone decides the deletion. Accepting it removes the block and its root, and returns blocked while the root holds text another pending change inserted. Rejecting it keeps both. Rejecting a proposed block that owns a content root removes the root too. A propose view still refuses deleting a named root that no element owns.

A view's policy belongs to that exact view. Selection, clipboard input, commands, and anchors use that view's coordinates. Two mounted views over one document can use different policies.

Review changes

Read a page of pending changes, then decide the records you read:

Use action: 'reject' to reject changes. changes(query) reads pending changes in document order, 50 at a time by default and at most 200. Pass a non-null page cursor to read the next page; a cursor whose changes have all left throws as stale. Narrow a page to a place of the stored document with at, to one author with authorId, or to one card with group.

Each AuthoredChange has its id, authorId, createdAt, kind, current ranges, and a revision that differs whenever its marks or the content they mark differ. Use change(id) to read one change.

A decision names the changes as they were read, and a change whose revision moved since returns stale. Accepting a change can need other changes accepted with it, and rejecting one can need its dependants rejected. The result is then blocked, with names the changes it needs, and nothing applies. The editor never decides a change you did not name. Several decisions in one call decide together:

Read semantic detail when the reviewer opens one change:

details(id) returns the change and its parts. Content parts include before and after slices. Boundary parts distinguish paragraph splits from joins. Enclosure parts name wraps and unwraps. Property parts preserve exact before and after values.

Review cards

A review card groups one author's adjacent pending changes, such as a deletion and the insertion that replaces it:

groups({ at }) returns summaries of the cards touching a place of the stored document, in document order: id, authorId, createdAt, changeCount, and revision. A card's ID is its oldest change, so every peer and reload names it alike. The ID moves when the card splits or merges, or when that change leaves it. groupOf(changeId) returns the card that holds a change.

Deciding a card decides every change it holds at that moment. The decision reads as stale once the card's ID or revision moved, so read the card again with groupOf before retrying.

Decision results

Always inspect the result of decide:

Save the document

Save the complete result of editor.read.value(). It holds the content with each node's pending review marks, and the review records in the document's records. Saving only the node array loses those records.

Use the same content plugins and schema when loading a revision into a fresh editor. Loading validates the review marks, review records, and document schema before publishing the value. Leave the authored node property and the review records to the editor. Local undo starts empty.

If you install Comments, save editor.plugin(CommentsPlugin).api.toJSON() atomically with the document and its application revision and conversation generation. Verify that association, then pass the saved CommentsJSON to CommentsPlugin.configure({ initialState: { initialComments } }) in the fresh editor. Live thread targets contain semantic identities; attachment(id) reads their placement. Accepting, rejecting, and undoing a suggestion decision preserve its discussion. Resolving or reopening a thread stays outside document undo.

Historical previews and restores retain current conversations and use only the selected revision's proven targets. See Comments and versions.

Export explicit projections

Choose accepted or proposed for a clean document, or review when the format can preserve review records. Clean projections report diagnostics when they omit pending work. Every helper accepts or captures a complete document, including named roots and metadata. A clean projection leaves out a content root once it leaves out the root's owner, by the content root ownership rule.

HTML, Markdown, plain-text and static HTML exports of a document with pending changes throw a TypeError unless projection is accepted or proposed. A document without pending changes needs no projection. DOCX export always takes one.

JSON

Save editor.read.value() as JSON to keep the review. For a clean document, project it first:

projectAuthoredDocument returns the projected document, its diagnostics, and the number of pending changes it decided. Loading saved JSON into an editor applies the installed application schema and the review checks.

Plain text and Markdown

Plain text and Markdown carry visible content only. Feature-owned format mappings preserve the structures they can represent and report omitted roots, metadata, pending work, and unsupported nodes. Markdown does not contain a hidden Plate document and cannot restore exact review state.

HTML and DOCX

renderStaticHtml and exportDocx draw with the static kit passed as presentation, because a live editor's components are editing UI. Semantic HTML uses feature mappings and no application styling. Both HTML forms carry visible accepted or proposed content only. A successful DOCX result returns a Blob in docx.blob. Every serializer returns structured diagnostics.

A DOCX review file shows Word revisions and also stores each reviewed block and its review records in a custom XML part, bound to the block's Word paragraphs. Importing the file restores each block whose paragraphs Word left unchanged; an edited paragraph imports from its Word revisions. Named roots and document metadata stay out of the file, so save authored JSON beside it to keep them. DOCX review export reports lossy-content or unsupported-content when Word cannot express a native construct.

Collaboration

Install the authored plugin and Yjs on every peer, with matching document and schema identities. Plate supplies local History by default.

The Yjs binding applies content, review marks, and review records in one remote transaction.

See Collaboration for setup.

API Reference

AuthoredPlugin

Import the standard descriptor from platejs/authored. It records each change as the Plate editor's userId, or as the local user, 'local', when the editor has none. It takes no options. SuggestionPlugin and AIChatPlugin depend on this descriptor.

Transaction, reads, and updates

After const authored = editor.plugin(AuthoredPlugin), use these methods:

subscribeChanges passes { blocks, changed, groups, removed }: the blocks holding a change whose card ID changed, the changes that began or whose revision changed, the cards whose summary changed, began, or ended, and the changes no longer pending. It is a low-level integration hook; suggestion UI uses useSuggestionChanges(path) and useSuggestionGroups(blockKey) instead.

Types and format helpers

platejs/authored exports the authored plugin descriptor, the change, card, query, page, delta, decision, and result types, proposeAuthoredComparison, and the format helpers below.

projectAuthoredDocument(document, { projection }) returns { ok, document, diagnostics, pending } for an accepted or proposed projection. It is a pure document operation: it does not construct, activate, or subscribe an editor runtime. Pass editor as well to complete the result with that editor's schema; under a schema that generates property values, a document with pending changes returns an AuthoredProjectionRefusal instead.

projectAuthoredRange(document, projected, range) maps a range of the stored document onto one of its projections, or returns null when the projection keeps none of its content.