Changelog
What each pre-release changed, breaking changes first, how to upgrade from 0.0.11, and every public change since.
Edytor is pre-1.0: a release keeps no compatibility shim beyond the deprecated aliases it names.
- Upgrading from one pre-release to a later one? Read Upgrading between pre-releases, from the section named after your current version up. Each section lists what the next release changed: breaking changes first, then what is new, then what was fixed.
- Upgrading from 0.0.11? Start with Upgrading from 0.0.11. The complete list names every public change since, by area.
- Documents stored by 0.0.11’s v13 engine no longer import: export their JSON with 0.0.11 and create the document from it.
Upgrading between pre-releases
Unreleased
Nothing yet.
From 7.0.3
Fixed
- The editor works in an app that turns on Svelte’s async mode. With
compilerOptions.experimental.async(a setting that switches every component’s scheduling, the editor’s included), formatting a range in the middle or at the end of a text duplicated the text after it (hello worldworld),insertFlowof several runs scrambled them, and removing a block with its handle shown could break the render. The editor no longer reads a render Svelte has only half written.
From 7.0.2
Fixed
- Two quotes a blank line apart stay two.
fromMarkdownandtextToBlocksread> a, a blank line, then> bas one quote (bits child), and a GitHub alert right after a quote as part of it (its[!TIP]line as text, no callout). A blank line now ends a quote, as in CommonMark.
From 7.0.1
Fixed
- A shared answer streamed live keeps its code blocks whole. Each
updateof a shared suggestion replaces the blocks that changed; a code block growing across updates left its earlier lines behind as paragraphs, so the answer showed the wrong blocks and accepting it kept them. The replaced blocks now go with their children. - A shared suggestion added with its content is listed.
add(at, blocks)returned a suggestion that never wrote its content, so it had no bar and nothing to accept. It is now written at once and listed,ready(or thestatusyou pass). Your own suggestion stays listed until its changes are decided: added with no content (or[]), it waits for anupdate. Added again under itsid, it replaces what the earlier one wrote instead of writing beside it. - A suggestion a member typed has no agent.
viaread'ai'for every suggestion this view did not add, those typed in suggesting mode included. It is now the suggestion’s own:undefinedunless an agent wrote it. - A shared answer’s code block grows in place. A live
updatethat adds to a code block now extends its last line and adds the new ones, as it extends a paragraph’s text, instead of writing the whole code block again: a long code block syncs only what changed. - Typing works in a test DOM without
reportError. An async input handler’s promise was chained to the globalreportErrorat once, so in a DOM emulation without it (happy-dom) every key threw. It is now read only when a handler fails; define it in your test setup to see that failure’s own error (test DOMs).
From 7.0.0
Fixed
- A shortcut right after a quick Shift+arrow selection acts on all of it. Pressing Bold (or any key) right after several fast Shift+→ presses, as with the key held down, could act on the selection as it stood after the first press. A key now reads the selection the browser moved before it acts.
- A long word no longer widens the editor. A word longer than the line (a pasted URL) wrapped, but an editor without the Notion theme, in a flex or grid layout sized by its content, grew to the word’s whole width and the page scrolled sideways. The editor now lets such a word break anywhere (
overflow-wrap: anywhere, a rule any of yours overrides). - On a touch screen, only the selection’s block shows its handle. Every handle used to show at once on a phone or tablet (there is no hover to reveal one). Now the block the caret or selection is in shows its handle, as in Notion’s mobile editor, and a hidden handle takes no tap. A touch on another block no longer reveals its handle either, so the first tap on a to-do’s checkbox acts at once (iOS Safari took a tap that revealed content for a hover, and a second tap was needed).
- A tap on a code block’s header acts at once on a touch screen. The code block’s Copy showed only while the block was hovered, and iOS Safari takes a tap that reveals content for a hover: the first tap on the language button opened nothing. On a touch screen, Copy now always shows, as does the dim
+of a callout without an icon. - One Return on an iPhone adds one block. On iOS’s software keyboard, Return added two blocks, and Backspace at the start of a block merged it into the block above and then deleted a character there: the keyboard announces these keys a moment after their key press, and the editor ran them for the key press, then again for the announcement. Each now runs once.
- A phone’s keyboard capitalizes sentences. The editor no longer turns the virtual keyboard’s capitalization off:
autocapitalizeis unset by default, so iOS and Android capitalize the first letter after a period or a Return, as in Notes or Notion. Passautocapitalize="none"to keep the keyboard lowercase (iOS reads it for the whole editor, so a code line starts capitalized too). - On iOS, the first letter typed into an empty block is a capital. An empty block held an invisible zero-width character, and iOS’s keyboard, finding a character before the caret, saw no sentence start when you tapped into the block. An empty block now holds a
<br>, as in ProseMirror, Lexical and CodeMirror: the first letter is capitalized whether you tap into the block or press Return. An empty text beside an inline atom (a mention) keeps the zero-width character, and a composition (Japanese, Chinese, Korean input) started in an empty block still composes into a text node of the editor’s. If your tests or styles read an empty block’s text, itstextContentis now'', and its caret is the text element’s own start rather than a point in a text node. - A double tap on a word keeps the word selected on a phone. iOS selects the word at the second tap, and the editor then put a caret at the tap point, collapsing it. A tap’s caret and a double tap’s word are now the platform’s: a tap also leaves the caret where iOS puts it (the word’s edge), as in other iOS apps. A mouse click still places the caret at the pointer.
- Selecting an image on a phone opens no keyboard. A tapped image (any block selection) used to bring up the virtual keyboard over the page. While blocks are selected, the editor asks for none (
inputmode="none"on its root); a tap in text brings the keyboard back, and a hardware keyboard’s keys still act on the selected blocks. - The ready-made menus keep clear of a sticky header. A menu that flipped above its button (on a phone, the keyboard leaves little room below) could sit under the app’s sticky header. The menus now stay below what the root’s
scroll-padding-topsays the header hides: set it to your header’s height (a caret scrolled into view then stays below the header too).
From 6.0.0
Breaking changes
- A room that re-seeds refuses the clients before this release. The room now rebuilds a document that grew past half its quota from its content (see New). A client names its document’s epoch when it dials; one before this release names none, and a room that re-seeded refuses it (
1008,refused: epoch), its edits kept in its local copy. Update the clients before the rooms: the new clients work with rooms that never re-seeded. To keep the previous behavior, setreseed: false(EDYTOR_RESEED=off). - The dial names the document’s epoch. The provider’s URL carries
epoch=<n>(epoch=newfor a document that holds nothing yet) afterreplica, before yourparams(a param of yours namedepochdoes not replace it). A host Worker that builds its own upgrade request must keep the dial’s query string;routeDocumentSocketforwards the request’s URL. - With a local copy, the socket dials once the copy has loaded.
createWebsocketSyncopens the socket after its IndexedDB store answered (or failed), so the epoch the dial names is the copy’s. A first dial comes a few milliseconds later; the readiness bound still counts from the socket’s open. - A re-seed is a
4410refusal of the document. When the room re-seeds, every socket is closed4410, its reason the new epoch; a provider with unsaved edits first dials once more to hand them over. Then the provider stops and reports aSyncRefusedErrorwithcode4410(refused,onSyncRefused,document.syncRefusal), andcreateWebsocketSyncdeletes its local copy.<Edytor>that owns its document builds itself again on a new one; if you pass your owndocument, create a new one whenonSyncRefusedreports4410. The room also closes4410a copy it cannot rebase (older than the 30 days it keeps, or of a later epoch than its own), and a socket of the current epoch that sends an older epoch’s content. SuggestContext.basetakes a reader. The shared suggestions’ base view, whichtoJSON()reads, is nowbase(read): it builds the document without its pending suggestions and answers whatreadreads of it. A part built over a facade that setbasepasses its own reader.
New
- Re-seeding. A document that grew past half its quota is rebuilt from its content, with fresh identities, once nobody wrote for ten minutes and when that gives back at least 40 % (past 80 % of the quota without waiting): the same blocks, data, text, marks and block attribution, stored at what its content takes. Clients reload it (a view built again waits for the room’s document, never seeding its
value); an offline client’s edits are merged into it when it comes back, for 30 days, as an update of its user (the quotas, its access,validateand the locks hold), its pending suggestions dropped; the users’ names and colors come along. Thereseedoption (ReseedOptions:at,idleMs,gain,force,graceDays;falsenever re-seeds; defaultsDEFAULT_RESEED_IDLE,DEFAULT_RESEED_GAIN,DEFAULT_RESEED_FORCE,DEFAULT_RESEED_GRACE_DAYS),DocumentRoom.reseeding()andEDYTOR_RESEED;reseed()(also over RPC) runs one now; the room’sepochandmetrics().epoch; thereseedandrebaselog entries, the refusal reasonepoch, thereseedalarm task and thecutstable. See re-seeding. - The re-seed’s protocol (
edytor/protocol):messageEpochandwriteEpoch(the room’s epoch, auth subtype3),messageRebase(the client’s old document, message type7), andCLOSE.reseeded(4410). See re-seeds. clipUpdate(update, sv, ds)(edytor/crdt): an update as it read at an earlier state, the counterpart ofdiffUpdate.bindCrdt(Y).doc.restoreTotakes options (rewrite, andsuggestions: 'keep'to keep the pending suggestions).
Fixed
- The protocol page’s wire word reads
14011, this release’s.
From 5.0.0
Breaking changes
- The providers’ own listener members are one teardown.
IndexeddbPersistenceandWebsocketProviderno longer carry_storeUpdate,_updateHandleror_awarenessUpdateHandler(their document and presence listeners, never meant to be called): one_unlistenremoves both listeners, asdestroy()does. Nothing else of the providers changes.
From 4.0.0
Breaking changes
- Schema generation 11: stored documents and rooms start over. Shared suggestions are stored in the document: a root of their own, and a deletion record that, inside a suggestion, holds nothing back but names the text it proposes to delete (wire word
14011, browser databaseedytor-v14-g11:<name>). Rooms, browser stores, history versions and peers of generation 10 are refused (GenerationMismatchError,schema-mismatch), never converted: a browser’s local copy is not read and the page fetches the room’s state again; re-create a room or a stored state of generation 10 from its JSON (toJSONwith the previous release, thencreateDocument({ value })). Update every client and the room together. toJSON()leaves pending suggestions out, once they are built over the document. With the shared suggestions plugin in a view of it (oradoptSharedSuggestions(document)on a document without a view),document.toJSON(),edytor.valueandonChange’s value are the document without its pending shared suggestions, and so are the room’sonSavevalue, a version in the history and the blocks a cross-document move exports (the room builds them over its document): the document on a copy with every pending one rejected (their inserted text and blocks left out, their proposed deletions not applied). While a suggestion is pending, each such read costs a copy of the whole document (about a load of it);onChangereads it at every change.toJSON({ suggestions: true })is the document as shown. A document without pending suggestions reads as before, and so does one nobody built them over: their text reads as plain content.- A press on a void block selects it. A click on an image, a bookmark’s card, a file’s row, an embed around its player, a divider, an equation, a table of contents or your own void kind selects the block, as in Notion: no caret goes to its caption any more, and Delete, the arrows, Enter, copy and Escape act on the selected block. A click in the caption still puts the caret there. Controls inside a block keep their whole press (native controls, links such as a bookmark’s card or a file’s row, interactive roles, focusable elements); mark any other interactive element of your markup
data-edytor-controlso a press on it neither selects the block nor starts a text selection. See presses on chrome. - A block’s parts carry their display range.
edytor.idToBlock.parts(id)answers the parts the editor renders, read-only: a text part hasstartandend(display offsets, an inline atom counting 1),text,runs(its text runs and their marks),keyandsegOrd(its position among the block’s texts); an atom part hasstart,end,id,typeanddata. It answeredstartanditems/lengthfor a text,startanditemfor an atom. Therunsof a text segment in a selection’s projection are read-only too. edytor.suggestions.listlists shared suggestions too, with the shared suggestions plugin. Its items areSuggestion | SharedSuggestion, told apart byshared: a view-localSuggestionkeeps itsat, and aSharedSuggestionanother view made has no position of its own (itsatisnull; read itschangesfor where it is). TypeScript now asks code that reads a shared one’s members to checksuggestion.sharedfirst.
New
- Shared suggestions, a plugin:
createSharedSuggestionsPlugin(). List it and the view’s edits are written as a suggestion of its user’s while its controller’ssuggestingis set (sharedSuggestionsController(edytor)), which every collaborator sees with its author and a writer accepts or rejects, as in Google Docs: typed and pasted text shows as an inserted run, deleted text and deleted blocks stay struck until a decision, new blocks are marked. Only text and blocks are suggested: merges, retypes, data changes, formats, moves, nests and outdents are refused while suggesting (written directly on the user’s own pending blocks), announced with the newsuggestions.notSuggestedlabel (thesuggestionssection ofLabels,SuggestionsLabels). One suggestion per contiguous edit; the suggester’s undo withdraws what it suggested. Without the plugin, a view ships none of their code and reads a document’s suggestions as plain content. See shared suggestions.- A
SharedSuggestionis in the one list (shared: true), withby(its author),via('ai'),changes(SuggestedChange[]:insert,delete,block,splitorremove),canDecide,mineandreject();discard()on it rejects it, which its author may do even without the right to decide.AnySuggestionis either kind. - The controller’s
changes(),decide(changes, accept),acceptAll()andrejectAll()review them: one command each (acceptSuggestionwith{ changes }, the newrejectSuggestion) and one undo step; only a view whose user may write decides. Read-only views with the plugin show pending suggestions. adoptSharedSuggestions(document)(edytor/crdt/edytor) builds them over a document without a view, whosetoJSON()then leaves the pending ones out.
- A
- AI answers shared live. The controller’s
add(at, content, { via })writes the answer into the document as it streams, so collaborators watch it being written; it is one suggestion, attributed to the user who asked, withvia: 'ai'(or theviayou pass). Each chunk writes only what changed. See AI answers shared live. - Access levels.
authorizereturnsaccess:read,comment,suggestorwrite(DocumentAccessLevel, exported byedytor/cloudflare;readOnly: trueisread). Asuggestuser writes only suggestions (anything else is stripped and refusedsuggest-only, the socket kept) and decides nothing; acommentuser comments from a read-only view, the room writing the thread’s anchor.setAccesstakes every level. The room tells each socket its level as it joins, and again when it makes a writer read-only in place: the provider’s newaccessevent,document.access(which the shared suggestions and comments plugins read) and the sync payload’saccess. See access levels. - Review chrome. The suggestion bar shows under a shared suggestion’s last changed block; its payload gains
reject,canDecideandauthor. The ready-made bar shows the author (“Ada (AI)”), Accept and Reject, Withdraw for the author and “Suggested” in a read-only view, and the starter’s newreviewprop draws the Editing and Suggesting switch with Accept all and Reject all (its newsharedSuggestionsplugin key, on by default, lists the plugin). The Notion theme marks inserted and deleted runs in the author’s colour ([data-edytor-suggestion-inserted],[data-edytor-suggestion-deleted],--edytor-range-color) and suggested blocks (data-edytor-suggested). - A suggestion’s delete in the engine.
edytor/crdtexportsunhide(andEngineSymbollists it), andEngineNode.deletetakes an optional fifth argument,propose: a suggestion’s record and how each unit is treated (held, proposed or stepped over); what it proposes reads deleted untilunhide(transaction). - Suggestions in the room’s history. A version restore drops the pending suggestions (its undo brings them back), and the purge removes a suggestion decided before its horizon with its decision trail (
metrics().purge.suggestions).
Fixed
- An input method over text selected across blocks. Composing with an input method over a selection that spans several blocks no longer leaves an empty block behind or loses a line’s text in Firefox (where a script’s
insertTextcomposes too). The selection is now replaced as the composition starts, as it already was over selected blocks, and the input method writes at a caret: the result is the same, the composed text in place of the selection, in one undo step. A composition canceled before it shows anything now leaves the selection deleted (one undo step), as over selected blocks. - A script or an extension deleting across blocks. When a page script or a browser extension deletes a range from one block into the next (
Range.deleteContents()on the page’s selection), each block keeps its remaining text, as before, and the editor’s later changes to those blocks render: deleting either one no longer leaves its element on the page, and a block nested under the first one shows. - Which races keep the text order. The concurrent editing page, the document API’s ordering section and the limitations now list what 4.0.0 does: a new line beside a block, a paste of whole blocks or over selected blocks, two Enters (or a duplicate and an Enter) before a sync, Turn into over several list items, Tab next to a new line, and a split after an edit past its own split point keep the text order whatever the client ids. Two races still follow the client ids: two pastes into one gap from both sides, and one
unNestBlockscall over items that are not adjacent. - A click in an image’s caption. Clicking in the middle of a caption (an image’s, or any block’s whose text sits inside non-editable chrome) puts the caret at the click at once. It used to land at the caption’s start first, then jump to the click.
- The caret after a block vanished, between blocks of one rank. When a block the selection was in disappeared (a peer deleted it) and its siblings shared one rank, the caret could land beside another block than the one shown after it. The children list, the caret’s fallback and the root’s last blocks now order such siblings one way, by their ids’ characters, which is also the same on every device whatever its language.
- Presence in Safari. Safari can drop the departure a closing page sends; the room announces it when the socket closes. Presence says so: behind a server that announces nothing at a socket’s close, a closed Safari tab’s caret stays until it expires.
From 3.0.0
Breaking changes
- Schema generation 10: stored documents and rooms start over. A text delete is now its writer’s own record, kept in the document; a merge is one item in the text of the block it joins, so a block no longer carries a list of the blocks merged into it; a block’s place is its slot in its parent’s order, written once when the block is created, with a move one record naming the moved blocks — the engine orders them, nothing is ranked; and the engine’s update encoding writes each string and each client id once per update, a block’s id is only its key (its node no longer repeats it, nor does its attribution record’s key), and a formatting mark is written in a few bytes (wire word
14010, browser databaseedytor-v14-g10:<name>). Rooms, browser stores, history versions and peers of generation 6 to 9 are refused (GenerationMismatchError,schema-mismatch), never converted: a browser’s local copy is not read and the page fetches the room’s state again; a room or a stored state of an earlier generation must be re-created from its JSON (toJSONwith the previous release, thencreateDocument({ value })). Update every client and the room together. - An update of another encoding is refused before it is read. A stored state of generation 6 to 9 handed to
loadDocumentis refused as undecodable (UndecodableUpdateError, “an update of another encoding”), where it was aSchemaMismatchError; an update written by upstream Yjs (oryjs13) is refused the same way, even inside an edytor frame, where it used to be applied to roots edytor does not read. - Merge claims in
edytor/crdt/edytorandedytor/protocol. A merge claim is an item of a block’s text:MergeClaimis{ m }, andClaimis{ m, stamp }(noseqIndex,a,rorholder;ItemRefis gone).TextBlockReclosesclaimsNodeandlistClaimsand gainsimplicit(the claims no item stores); itsclaimsare the claim items of the block’s stream, after them.Ownership.claimsOfis gone andOwnershipgainsclaimIndex(holder, m). The text binding’sclaimInto(own, from, into)writes the claim item ininto’s stream (give a block without one its own text first,ownText),splitAt(doc, blocks, own, b, offset, newId, n)writes the claims that follow the split itself and returns nothing, anddeleteClaims(doc, claims)deletes claim items.RunView.track()also returnsquiet(write). - A plan’s steps carry places, not ranks. In
edytor/crdt/edytor,PlanStep‘sinsertBlocksandmoveBlockssteps loseranks(amoveBlocksstep may carryside:1when the blocks leave a block for the gap before it,at: the block its record stands at, andpart: its order among the records standing there; aninsertBlocksstep may carrysplit: the split-born block of the plan whose boundary keys the new blocks’ slots, a paste’s lines),splitBlockcarriesindexinstead ofrank, andpatchDatacarrieswrites(DataWrite[]: leaf writes and slot writes) instead ofleaves. A hook that read a step’sranksreads itsindex. - The placement model’s write primitives changed.
bindCrdt(Y).doc.modellistsplaceBlocks,moveBlocksTo,insertSpecsAtandrecordsOf;ranksAt,writePlacement,materializeSpec,candidatesOfandresolvePlacementsare gone (the document’s index decides every placement, one block at a time; there is no from-scratch resolution to call),writeSplittakes a parent and an index, and aBlockReccarrieshome(its slot) instead ofcands.dataLeaves/writeLeavesaredataWrites/writeData.EngineNode(the structural view of the engine’s node inedytor/crdt/edytorandedytor/protocol) gainshold(ids),move(index, ids, side, part, at)and theintoandfresharguments ofdelete: an object you pass as anEngineNodemust have them (the engine’s nodes do).EngineSymbolno longer listsContentAny, andedytor/crdtexportsContentMove. ABlockSlotmay carrys, the split’s boundary id. Inmove(index, ids, side, part, at),atis the chain of units the record stands at, outermost first (for a block: its ancestors’ home slots, then its own). bindCrdt(Y).doc.keepCopiesis removed. A room’s document needs no collection rule for deleted text any more: create it withcreateDoc()and apply updates. Remove the call.PurgeReport.recordsandmetrics().purge.recordsreplacecandidates. The purge has no restoration records and no placement candidates to delete;markscounts the text delete records it removed, with the text they held, andrecordsthe move records no block shows at any more (lost moves, moves of removed blocks).- Deleting a block, turning one into a divider or an image, and a column emptied write no move. The children of a deleted block, of a block turned into a kind that shows no children, of a dissolved layout’s last column and of a deleted column keep their place in the document; the editor shows them in the block’s slot when it reads. The plan of
deleteBlock/deleteBlocksand of such asetBlockTypehas nomoveBlocksstep and itseffect.moveslists no children (a hook that counted on it readseffect.removesand the read-time rules). A reader that lacks thelayoutrole (a tool without the columns plugin) now sees a deleted column’s blocks inside the layout, at the column’s place, where the write used to put them after the layout. - A document that took updates before edytor adopted it is refused.
attachDocument(doc)and the view throw aTypeErrorfor an engine document created withnew Y.Doc()that already holds state: the engine decides what a replaced value keeps when an update arrives, so such a document could have dropped what its peers keep. Create the document withcreateDoc()(fromedytor/crdt),createDocumentorloadDocument, then apply updates; an emptynew Y.Doc()is still adopted. - A move writes nothing inside the moved block. A move is one record in the destination’s order; the moved block’s node is untouched, so an observer of that node’s changes hears nothing from a move (it heard the placement write before). Edits inside the block still reach it.
- A client’s actor binding is written with its first edit.
document.attribution.actorOf(document.clientID)isundefined, anddocument.attribution.actorsdoes not list the local actor, until the document’s first edit (orattribution.setProfile, itself an edit): the binding of the client id to its actor and the actor’s profile are written inside that edit, in its one update, no longer when the document is created or opened. Read the local actor fromdocument.actor, or read the binding after an edit. The room’s checks of bindings are unchanged; they meet a client’s binding in its first edit. - A purge of a closed session’s deletes reports no horizon.
DocumentRoom.purge()and the room’spurgelog entry havehorizon: number | null:nullfor a run that purged what closed sessions deleted with no epoch past the purge horizon (see New). Handlenullwhere you read it as a number.
New
- Documents are smaller, and stay small. A block no longer carries a placement map (about 38 bytes) and no key grows with the number of lines inserted at one spot (300 Enters at one place no longer leave 39-character keys behind); a move costs a few bytes. The update encoding writes each string and each client id once: a typed page of 1,000 paragraphs edited over ten sessions stores 32 % less (16 % less compressed), a page heavily edited and deleted over many sessions 37 % less, and one a room has purged 64 % less (38 % compressed); bold on a word sends 63 bytes instead of 92. The room holds the same live document in about a tenth less memory. The numbers are in the repository’s engine-move and storage-diet design records.
- A page that is only read writes nothing. Opening a document, syncing it, sharing a caret and leaving, without an edit, leaves the stored document byte for byte as it was, where every such page load added 50 bytes of actor records for good; the room stores nothing for its socket. A client’s binding and profile are written with its first edit (see Breaking changes).
- A closed page’s deletes go at the room’s next purge. When a page leaves for good (a
pagehidethe back/forward cache keeps nothing of), its view ends its session’s history,document.endHistory(), which you can also call yourself without a view: the steps are released, the text the session deleted is removed at once, and the room’s next daily purge removes the blocks it deleted without waiting forpurgeAfterDays, since only that session’s undo could have brought them back (a version restore still does, from the version). A page heavily edited and deleted over four sessions, each closing its page, stores 1.17 MB at once instead of 1.27 MB, and 0.46 MB a day later instead of a month later. Open sessions, a page kept in the back/forward cache and a tab that only lost its connection keep their history. From Firefox, which closes a page’s sockets beforepagehide, the release reaches the room only through another open tab of the document; otherwise the deletes wait for the purge horizon, as before.PurgeReportandmetrics().purgegainreleased, the release records the horizon covered and the purge dropped. - The room’s document quota keeps its 2 MiB default. Every document a room admitted before is admitted, and stored smaller. The memory it may take grew with the new encoding: at worst, a long list of one-line blocks (about 23,000 at 2 MiB) takes about 150 to 160 MB of heap in Node, where 2 MiB took about 100 MB before (a Worker takes less). Set
EDYTOR_MAX_DOCUMENT_BYTESto 1.25 MiB to keep the old bound; see quotas. - The purge removes deleted lines that share a paragraph’s text. A line made by Enter shares the text of the paragraph it was split from; once deleted and past the purge horizon, it is now removed with its formatting, where it used to keep its bare structure for good. A heavily edited page stores about a fifth less after its purge than when those lines stayed.
- Lines typed after your own line stay together. When you press Enter after a line you wrote and keep typing lines while someone else inserts a line right after that first line, your lines stay together, before or after theirs — whatever the two clients’ ids.
- Concurrent splits, outdents, lifts and pastes keep the text’s order. Two people pressing Enter in one paragraph, pasting lines into it, outdenting or lifting items of one list — nested or not — into the same gap, or turning items into headings, dividers or code at the same time read the lines in the document’s order on every client-id pair, as if one had acted after the other, whatever each typed or deleted after their split point; a divider or a code block inserted after an item follows that item’s text. Several of those races used to read in the order of the clients’ ids (the editor’s own pinned residuals); the two outcomes that remain are a block a peer adds among the items an outdent moves into a new list, and a lift out of two nested lists racing a move at the other level.
Fixed
- Undo brings back the very text that was deleted. Undoing a text delete shows the same characters again, where they were, instead of copies: a caret, a selection or a comment anchored inside the deleted text resolves where it was after the undo, and a peer who split or typed next to the deleted text sees it come back in the same place on every replica, whatever the order the edits arrive in.
- A peer’s delete holds as soon as it arrives. When two people delete the same text and one undoes before the other’s delete reached them, the text is hidden again the moment that delete arrives, on every replica; it no longer waited for the other person’s next edit.
- Deleting text a room lost is saved. A delete of text the room no longer holds (after a restore from an older snapshot) is stored and acknowledged at once, and holds the text when its author brings it back.
- Two people nesting blocks into each other no longer re-places every block. The race is resolved on the two blocks alone, on a 5,000-block page as on a 1,000-block one.
- A line added where deleted lines were shows before them when they come back. Press Enter at the end of a line whose following pasted lines a peer deleted, type, and the peer undoes: the restored lines come back after your new line, as restored text comes back after text typed in its place (they came back before it).
- Your gestures win or lose together. Two edits you make between syncs (turning two items into headings, outdenting two groups) and a peer’s concurrent move of the same blocks no longer end with half the blocks placed by you and half by the peer.
- Syncing after a lost message no longer fails on a deleted section. A client that had missed one message (a gap in what it holds of a peer) failed when it then received the full state of a peer who had deleted a whole section: the deleted section was taken whole over the part the client already had, and the sync threw. The engine now trims an arriving update to exactly what the client lacks, gap by gap. The failure was in the engine before this release too; it is reachable more often now that a move is one record.
- The room’s purge no longer brings deleted blocks back. When the purge removed old text deletes whose writer had also deleted a block in the same session, it could delete that block’s delete record with them: the block came back, empty, on every replica, a month after it was deleted. The purge now removes only the text deletes and what they hid.
- The caret stays put when a code block’s highlighting arrives. A code block loads its language’s highlighting the first time one of its lines shows, after you pick the language or as the page opens. When it arrived while the caret was in one of those lines, the line was drawn again under the caret and the browser moved the caret to the line’s start, so the next character typed went there. The caret now stays where it was. The same holds for any kind whose
transformTextdecorations change on their own. - Code highlighting on TanStack Highlight 1.1. The code block’s grammars come from
@tanstack/highlight1.1 (was 0.1); the languages, tokens and theme classes are the same.
From 2.0.0
Breaking changes
- Menus and popups place themselves. The package no longer positions the slash, trigger, block and URL paste menus, the toolbar and its link card, the find bar, the table grip menu, the image toolbar, the code language list, the callout icon picker or the equation editor: your snippet places its element by its controller’s new
anchor(a virtual element read live, Floating UI’s shape:computePosition(controller.anchor, element, …)withautoUpdate, or bits-ui’scustomAnchor={controller.anchor}); the toolbar’s link card bycardAnchor. Their hosts no longer carryleft/top, the language list, the picker and the equation editor lose their placed wrappers (data-edytor-code-language-panel,data-edytor-callout-icons,data-edytor-equation-panel), the table menu’s host its place, and the block menu no longer places its flyout. The ready-made menus do it with Floating UI (@floating-ui/dom, added to theedytor-chromeregistry item). - One caret form for a command.
dispatcher.carettakes only{ block, offset }in block offsets (dispatcher.caret({ block, offset }, ops?)); the text segment formcaret(text, offset, ops?)is gone. A segment offset is{ block: text.parent, offset: text.segStart + offset }. - A view takes its document one way. The
docandawarenessoptions ofnew Edytor(…)and<Edytor>are removed: compose the document first,attachDocument(doc, { awareness }), and pass it asdocument(the view then borrows it: destroy it yourself). Withoutdocumentthe view owns a fresh one, whichactorandrequireHydrationstill configure.edytor.ownsDocumentis gone. - One error per meaning.
EdytorDocDisposedErroris gone: an operation on a destroyed document, or on a disposed facade, throwsDocumentDestroyedError.ChunkLimitError(edytor/protocol) is nowChunkError, thrown for a sequence over the limit (withtotalandlimit) and for a part or end with no start. The errors’ messages are one line. - No v13 document check.
UnsupportedDocErrorandassertUsableDocare removed:attachDocumentno longer tests for a document of another engine (a v13yjsdocument), which no supported path produces.SchemaMismatchError’s message is one line naming the problem, the version and the manifest name it found. selection.hiddenandselection.shownare removed. They were a second path to the editor’s own visibility rule. A block hidden by view state (a closed toggle’s body) is one whose element is inside[hidden], details:not([open]) > :not(summary).ImageToolbarhas no public constructor. The image toolbar plugin builds the one per view and hands it to yourtoolbarsnippet; the toolbar renders inside the image chrome, at the image’s top right, as before.
New
- The starter editor, a shadcn-svelte registry.
npx shadcn-svelte@latest add https://edytor.dev/r/starter.jsoncopies<StarterEditor />into your app:<Edytor>with every useful bundled plugin, the Notion-style menus, handles, toolbars and panels, comments (with acommentsclient), and the page around the blocks: a cover, an icon, a title and typed page properties (text, number, select, multi-select, a date shown in your locale and picked from a calendar, checkbox, URL, person), all stored in the document’s data so they sync in a room and undo like the blocks. Hiding a property keeps its value, under the hidden properties. It is built with shadcn-svelte components and reads your shadcn theme’s tokens, so the page, the blocks and every menu follow.dark. The files are yours to edit;<Edytor />fromedytoris unchanged. See Starter editor. - The ready-made menus, a shadcn-svelte registry item.
npx shadcn-svelte@latest add https://edytor.dev/r/edytor-chrome.jsoncopies each bundled plugin drawn with them (slashMenuPlugin,toolbarPlugin,blockHandlesPlugin,codePlugin…), their snippets (chrome), their words (setWords) and the version history panel (HistoryPanel) into your app. See Ready-made menus. - Import and export,
edytor/export.toHTML(doc, { kinds? }),toMarkdown(doc, { kinds? })andfromHTML(html, { kinds?, DOMParser? })turn a document into HTML or Markdown and HTML into a document, by each kind’s own forms, the ones the clipboard writes and reads (textToBlocksreads Markdown, and is there too). The entry loads no Svelte, so it runs in Node and in Workers;fromHTMLtakes aDOMParserthere (linkedom’s, say).fromHTMLis safe: only the kinds and marks you read survive, links and sources go through the editor’s sanitizers, and nothing in the HTML runs. Withoutkindsthey read the bundled kinds (bundledForms); pass a view (kinds: edytor) or forms by name to read yours. See Import and export. - A
markdownform on kind, mark and atom records.markdown(block, content, children, context)on a block kind,markdown: [open, close](or a function of the value) on a mark,markdown(data)on an atom: whattoMarkdownwrites. Every bundled kind has one, kept inedytor/exportby name (the editor ships none): headings, nested lists, to-dos, quotes, code with its language, GFM tables, dividers, images, links and marks (bold and italic together, bold links), callouts as> [!NOTE]alerts, toggles as<details>, equations as$$. See Custom blocks. - A full markdown reader in
edytor/export, on TanStack Markdown. ItstextToBlocks(andfromMarkdown, the same reading as a document) parses with@tanstack/markdown, a small dependency onlyedytor/exportloads, and reads GFM tables as a table block (the first row its header), a fence’s language as the code block’sdata.language, nested marks (**[a bold link](url)**,***both***),~~strike~~,<https://…>links, backslash escapes, a line holding only an image as an image block,> [!NOTE]as a callout,<details>as a toggle,$$as an equation, reference links ([text][ref]) and footnotes as text. Raw HTML stays text.textToBlocks(text, { streaming: true })reads a model’s answer still arriving: an unfinished line’s block marker or unclosed inline marker waits for the next chunk, so the preview never flashes raw markdown.textToBlocksfromedytor, which a markdown paste and a string suggestion read, is unchanged: tables, code languages, nested marks and streaming need the one fromedytor/export. See Suggestions. - MDX-lite components in Markdown.
fromMarkdown(source, { components: { Endpoint: 'endpoint', Callout: 'callout' } })reads JSX-like tags,<Endpoint operationId="getPet" />or<Callout type="warning">text</Callout>, as blocks of the kinds they name: literal attributes (strings, numbers,true,false) become the block’s data, the tag’s markdown its text and children. Expressions, imports, exports and tags you did not list stay text and are told toonUnknown.toMarkdown(doc, { components })writes the same tags back, andmdxComponent(name, data, content, children)writes one from a kind’s ownmarkdownform. See Import and export. - CORS for the room’s HTTP routes.
routeDocumentComments,routeDocumentHistoryand the probes ofrouteDocumentSockettakecors: true | { credentials?, maxAge? }: a page on another origin gets its preflight answered and every answer carriesAccess-Control-Allow-Origin(the originsallowedOriginslists, echoed, with cookies whencredentialsis set;*without a list). See Server comments.
Fixed
- Files dragged from your desktop scroll the page. While files are dragged over the editor, the page and the editor’s scroller scroll near their edges, as in a block drag, and the drop line clears as soon as the drag moves off the editor or leaves the window.
- A table in a suggestion’s preview lays out its cells in columns. Before Accept, its cells were stacked on top of each other.
- Live comments with the documented Worker.
createCommentsClientwithoutsocketnow hears the room’s changes on the websocket sync the page already holds for that room, whatever its route: a comments route on/commentsbeside sockets on/roomsneeds nosocketany more (before, the client listened on/commentsand heard nothing). - The comments docs. The starter’s “With a room” example passes the
userthe documentedauthorizereads, and the comments page states the width rule: the cards show beside the text, without a click, once the editor ends 328 px before the window’s right edge. edytor/exportis smaller per function. Each conversion reads only its own direction of the kinds’ forms:toHTMLalone ships about half of what it did,toMarkdownandfromHTMLless too, with the same output. The plugin forms factories (codeForms(),mediaForms(), …) return records typed asBlockFormsrows; their fields and values are unchanged.
From 1.0.0
Breaking changes
-
<Edytor>’s defaults are rich text and the suggestion keys only. Images and block moves from the keyboard are no longer added for you. An app with images listscreateImagePlugin({ upload })(orcreateImagePlugin()for links only); without it, the slash menu has no Image, image files are not claimed, and a pasted<img>is dropped with its alt text (the text around it is kept). An app that moves blocks with Mod + ↑/↓ and Mod + Shift + ↑/↓ listscreateArrowMovePlugin(); without it, those keys keep their text meaning (the caret, or the selection, to the start or end of the document). The block handles, the block menu and the slash menu were never defaults.- Nesting is off unless
allowNesting:<Edytor allowNesting>(ornew Edytor({ allowNesting: true })) lets users nest blocks, as before: Tab and Shift + Tab nest and unnest, a handle drag or Alt + → may drop a block inside another. Without it, Tab is left to the browser, which moves the focus out of the editor (a code line, a table cell and a suggestion still take it), and no gesture places a block under a block that is not made to hold children. Lists, toggles, callouts and columns keep their bodies, and nested blocks already in a document still show and edit. - Dropping files needs a media plugin with
upload: the drop line and the blocks dropped files become come with the first image, file, video or audio plugin given anupload; without one, a file dropped on the editor is ignored (the browser does not open it).
// Before: images, block moves and nesting without asking <Edytor /> // After <Edytor plugins={[createImagePlugin({ upload }), createArrowMovePlugin()]} allowNesting /> - Nesting is off unless
-
createUploadsPluginis removed: each media plugin takes its ownupload. Pass your uploader to the image, file, video and audio plugins you list (createImagePlugin({ upload }),createFilePlugin({ row, upload }),createVideoPlugin({ upload }),createAudioPlugin({ upload });ImagePluginOptions,VideoPluginOptions,AudioPluginOptions). A plugin without one takes no files: no Upload in its empty block, no drop line for its files, and its pasted or dropped files are not claimed (an image goes to the file block when the file plugin uploads). Pasted and dropped files still pick their kind, one block per file, one undo step.UploadsOptionsis gone, and a kind record’supload(KindUpload) now needssend(the uploader) and has nopreview. A fullmedialabels section you pass now needsuploading.// Before plugins: [createUploadsPlugin({ upload }), createImagePlugin(), createFilePlugin()]; // After plugins: [createImagePlugin({ upload }), createFilePlugin({ upload })];
New
- A pasted reference becomes a page link.
createPageLinkPlugin({ fromPaste })reads a pasted text, your app’s URL for a page or any text you recognize, and answers the page (ornull, at once or as a promise): the paste becomes a page link, an undo step of its own that gives the plain text back. It wins over the pasted link and the URL menu for the texts it recognizes. See Pasted references. - Who is online is one property.
edytor.presence.peerslists the other people in the document (every client but yours, by client id), each{ clientId, name?, color?, … }with the fields of itsuserstate. It is reactive, so{#each edytor.presence.peers as person (person.clientId)}follows joins, leaves and name changes, and it listens to the awareness only while something reads it. Theawareness.getStates()filter andchangesubscription you wrote can go. See Who is online. - Properties are plain Svelte state.
block.data,atom.dataandedytor.dataare writable at any depth:block.data.color = 'red',block.data.meta.author.name = 'Ada',block.data.tags.push('x'),delete block.data.draft. Each write patches only the property or the array items it changes, so it merges with collaborators’ edits of the others; the writes of one task are onepatchData(one undo step, one transaction, seen by hooks), and read back at once. Reads are reactive at any depth, a property deleted by a collaborator disappears, andJSON.stringifyor$state.snapshotgive plain JSON. A readonly view refuses an assignment without throwing (dispatcher.lastisrefused). A snippet’sblock.datais typed by the kind and writable (it wasReadonly), and bound inputs work:bind:value={block.data.title}. A bare document hasdocument.data, whose writes are the rawpatchData.edytor.patchData(target, patches)stays, for a list of patches at once. See Properties. - A file shows at once while it uploads. An image appears from a local object URL (this view’s only, never stored, released once the upload ends; peers see the empty block until the URL arrives), a file, video or audio block shows the file’s name and size, each with the progress, for a pasted, dropped or picked file. Your
emptysnippet draws it with the controller’spreview(the object URL, ornull) andprogress(0to1, ornull), andpendingwhile uploading also hasnameandsize; without the media empty plugin the block’s own markup shows it. A filerowsnippet getsuploadingandprogress(srcis the object URL meanwhile). The labels gainuploading(“Uploading…”). - Files dropped from your desktop land where you drop them. While image, video, audio or other files are dragged over the editor, it shows the drop line a block drag shows (between blocks, inside one, or beside one as a new column), with or without the block handles, and the drop places one block per file there, uploading through the
uploadof the kind’s plugin as before, one undo step. They used to land at the caret position under the pointer, splitting its text. A readonly view shows no line and takes no drop. A plugin’sonPastehook gets that place asat({ block, position }). See Pasted and dropped files. - An editable editor renders on the server (documentation).
<Edytor>given avalue, or nothing, server-renders its blocks and hydrates in the browser, so it needs noonMountguard and noexport const ssr = false;. An editor connected to a room needs none either: it server-renders itssnapshot(or nothing) and opens IndexedDB and its socket in the browser; load the snapshot in your serverloadto have the document in the first HTML (SvelteKit). A mounted flag you wrote around<Edytor>can go. No Vite setting is needed either: a SvelteKit or Vite Svelte app’s default config builds, server-renders and hydrates the editor, sossr.noExternal: ['edytor']andresolve.dedupe: ['svelte']can go from yourvite.config. The quick start is shorter: one plugin, and the document kept in a$statefromonChange. Copying the demo’s menus and handles has its own page, Ready-made menus. Nothing in the package changed. - Mentions with several triggers.
createMentionPlugin({ kind })names the inline kind its atoms are (defaultmention): list the plugin once per thing to mention, ascreateMentionPlugin({ char: '$', kind: 'ticker', items: tickers })beside the@people. Each instance opens its own menu, and its atoms render and copy with its ownchar($AAPL). A menu snippet reads its trigger’s kind ascontroller.trigger.name(a trigger’s newname). The atom’sdata-edytor-mentionattribute now holds the kind ([data-edytor-mention]still matches every one), and a mention copies as HTML as its span, which pastes back as the same mention. Two instances of one kind: the first listed defines it. See Several triggers.
Fixed
- Undo after an input rule gives the typed text back. Typing
(c)gave©, but undo left(c: the last typed character went with the replacement. The typed text now goes in first, as typed, and the replacement is a step of its own, so the first undo gives back exactly what you typed ((c),->,:smile:), the caret after it, and the next undo removes the typing. Markdown shortcuts do the same: undo after##gives a paragraph##, and aftersay **b**the textsay **b**. A rule’sreplacenow runs with the typed text in the document:ctx.tois after it, andctx.removeremoves it with the rest of the match. - Columns are spaced as in Notion. The resize line stood at the left edge of the gap between two columns, and the Notion theme kept a little space inside the layout and each column. The line and its band are now centered in the 46px gap, a column’s
+and grip stand in the gap’s right part, flush with the column, and every block in a column (text, a table, a code block, an image) starts at the column’s own edge. Column 1’s handles stay in the page margin. - A scrolled table’s row grip stays beside its row. In a table wider than its place (in a narrow column, say) and scrolled sideways, the row grip and its menu stood at the table’s hidden left edge, sometimes over the column beside it. They now stand at the left edge of the part that shows and follow the scroll.
- Image alignment works in a built app. Left, center and right moved nothing: an app’s bundler dropped the image plugin’s own CSS (and the equation, mention, page link and rich text plugins’ few rules) because those plugins are used without rendering their component. Their CSS now ships with the plugin.
- ArrowDown from the title of an open toggle, or of a callout, goes into its empty body (a first block inside, the caret in it, one undo step), as clicking the “Empty toggle” hint does. It used to skip the body and go to the block after it.
- With two code plugins listed, the first one draws the whole code block, its header included, as with every kind (the first plugin listed wins). The header used to come from the last one while the language list came from the first.
From 1.0.0-rc.3
This release makes the editor smaller: an app with <Edytor /> ships about 40% less of the editor’s own JavaScript, and an app with every plugin about 30% less (701.5 → 429.1 KB and 909.5 → 651.8 KB minified, the Svelte runtime excluded). It gets there by keeping one way to do each thing. The chrome is headless: the package draws no menu, handle, panel or card, each one is a snippet you pass its plugin (the controls inside blocks keep a default your snippet replaces), and the ready-made menus is markup you can copy. There is one write API (the document’s operations, under the same names on the view; handles only read), one update encoding and one undo manager. Browsers are Baseline 2024, and stored data of earlier generations is refused instead of converted. Each change below states what the release ships and what an app must do; most apps act first on Plugins and chrome.
Breaking changes
Browsers
- Baseline 2024 only. Edytor supports Chrome and Edge 120, Firefox 125, Safari 17.4 and Chrome on Android 120, or later (Platform support). The code paths for older engines are gone: a caret step and Backspace always read graphemes through
Intl.Segmenter, and the chrome’s layer needsResizeObserver,Element.checkVisibilityandrequestAnimationFrame. - Storage needs
CompressionStream. The browser store and the room compress every snapshot withCompressionStreamandDecompressionStream, which every supported browser, Node and Workers have; a platform without them can no longer store or load a document.
Storage, sync and the engine
-
Schema generation 6: one update encoding, earlier data refused. The engine, the wire, the browser store and the room use one update encoding, the columnar one upstream Yjs calls v2 (a stored snapshot is still gzip-compressed). The wire word is
14006, andSCHEMA_VERSIONandbindCrdt(Y).versionare6. Documents, browser stores, history versions and peers of generation 5 (1.0.0-rc.3) and earlier are refused, never converted: to keep a document, export its JSON with the earlier release and create the document from it.- The browser database is
edytor-v14-g6:<name>.createIndexeddbSyncandIndexeddbPersistenceread no earlier store (edytor-v14-g5:<name>,edytor-v14:<name>) and leave it as it was; theconvertPreviousoption is removed. A document a room keeps takes its state from the room. - A room refuses a container of an earlier generation until
reset()starts it again fromonLoad:attachRoomno longer answers{ kind: 'converted' }, theconvertlog entry is gone andStoredRecordhas nov2field. - A server of your own:
STORED_GENERATION_RECORD,STORAGE_FORMAT,StorageFormat,PREVIOUS_SCHEMAandisPreviousGenerationRecordare removed fromedytor/protocol(a container record isGENERATION_RECORD, with nostoragefield),bindCrdt(Y).generationsis removed, andbindCrdt(Y).admission.admitUpdatetakes update bytes only (no{ v2 }form).
- The browser database is
-
One inbound path for sync payloads.
bindCrdt(Y).sync.readSyncStep1,readSyncStep2,readUpdate,readSyncMessageandstep2Updateare removed: apply a received SyncStep2’s or Update’s payload as it is withsync.applyRemote(doc, payload, origin), which refuses a forged schema stamp and reports it, and answer a SyncStep1 withsync.writeSyncStep2(encoder, doc, stateVector).modifyAwarenessUpdateis removed fromedytor/protocol: rewrite entries withwriteAwarenessEntries(readAwarenessEntries(update).map(…)). -
v13 documents no longer import.
bindCrdt(Y).migration,isLegacyDocand theMigration,MigrationStatus,MigrationRecord,MigrationPhase,MigrateResultandMigrateOptionstypes are removed, andUnsupportedDocErrorhas only the reasonforeign: this engine does not decode a v13 document’s bytes (loadDocumentthrowsUndecodableUpdateError). Export a v13 document’s JSON with 0.0.11 and create the document from it. -
Old stored data is no longer read. A block’s or inline block’s whole
dataattribute, as documents written before 0.1.0-next.6 stored it, reads as empty (only the per-property format reads; arrays stored as one value by 0.1.0-next.6 still read, and the first write through one converts it into items).document.attribution.legacy()is removed: thea/records of early builds stay in the document byte for byte, unread (read them from theattributionroot if you keep a decoder of your own). -
The per-block lineage ring is gone. The
lineage: { depth }option ofcreateDocument,loadDocumentandattachDocument,attribution.history(id)and theBlockLineageEntrytype are removed; per-block attribution (attribution.block(id):createdBy,contributors,lastChangedBy) is unchanged. Remove the option (an untyped caller passing it is ignored). Rings stored earlier stay in the document, unread. -
The document’s undo manager is edytor’s own.
document.historyandfacade.createUndoManager({ trackedOrigins, captureTimeout, limit, captureTransaction })return it (theYUndoManagertype), withundo(),redo(),stopCapturing(),canUndo(),canRedo(),clear(),destroy(),undoStack,redoStack,captureTimeout,trackedOriginsandcaptureTransaction. What changes:- Its events are one
observe(f), which returns the unsubscribe:f({ stackItem, origin, type }, added)runs for every step taken into a stack, in place ofon('stack-item-added' | 'stack-item-updated').stack-item-poppedandstack-clearedare gone:undo()andredo()return the step they replayed. addToScope,addTrackedOriginandremoveTrackedOrigin(add totrackedOrigins),deleteFilterandignoreRemoteAttributeChangesare gone, andfacade.releaseHistory(um)isum.clear().
- Its events are one
-
The raw engine (
edytor/crdt) ships only what the editor calls. It keeps documents, nodes, transactions, the update encoding, id sets andRangeCursor, and gainsdiffUpdate,idAtIndex,indexOfId,keepItemandfollowRedone. If your code calls it:Removed Use applyUpdateV2,encodeStateAsUpdateV2,mergeUpdatesV2,diffUpdateV2,decodeUpdateV2,readUpdateV2,convertUpdateFormatV2ToV1, theupdateV2eventapplyUpdate,encodeStateAsUpdate,mergeUpdates,diffUpdate,decodeUpdateand theupdateevent, which read and write the one encoding (bytes stored in the v1 encoding no longer read)UpdateEncoderV1,UpdateEncoderV2,UpdateDecoderV1,UpdateDecoderV2UpdateEncoder,UpdateDecoderY.UndoManageredytor’s undo manager, above; redoItem’s last arguments are(…, itemsToDelete, deletedByHistory?)node.format(…),insert’s format argument,Y.cleanupYTextFormattinga mark: node.mark(index, length, name, value, startSide, endSide); read marks withnew Y.RangeCursor(node).read(from, to)(a plain format another engine writes is ignored)observe,observeDeep,unobserve,unobserveDeep,Y.YEvent, thebeforeObserverCallsandafterTransactionCleanupeventsdoc.on('commit', (transaction) => …), once per transaction beforeafterTransaction:transaction.changedmaps each node it changed to the keys (null: its content) that changedtoDelta,toDeltaDeep,node.delta,applyDelta,node.change,Node.from,clearCache, the'delta'event, a delta inserted as contentwrite with insert,delete,mark,setAttranddeleteAttr(insert anew Y.Node()you filled)toJSON,toString,toArray,get,slice,getAttrs,hasAttr,attrValues,attrEntries,attrSize,map,forEach,push,unshift,clone,clearAttrs,parentread with getAttr,forEachAttr,attrKeysandRangeCursor; for a document, the document API (toJSON(),project(),runs(id))createRelativePositionFromTypeIndex,createRelativePositionFromJSON,createAbsolutePositionFromRelativePosition,relativePositionToJSON,RelativePosition,AbsolutePositionY.idAtIndex(node, index, assoc), the id a position binds (nullat an end), andY.indexOfId(doc, id, assoc), its live index and node ({ type, index }, ornull)subdocuments and load state: Doc’sguid,collectionid,meta,autoLoad,shouldLoad,load(),getSubdocs(),getSubdocGuids(),toJSON(),isLoaded,isSynced,whenLoaded,whenSynced, theload,syncandsubdocsevents,ContentDoc,ContentEmbed,ContentJSONnew Y.Doc({ gc, gcFilter }); an update holding one of these contents no longer decodesa transaction’s beforeState,afterState,metaandcleanUpsnothing the renderer ( AbstractRenderer,$renderer,useRenderer, therendererargument ofRangeCursor) and the schemas$doc,$nodeAny,$idSet,$idMapAny,$contentIds,$contentMapinstanceof Y.Doc,instanceof Y.Node,instanceof Y.IdSetid maps and content maps ( IdMap,createIdMap,insertIntoIdMap,readIdMap,writeIdMap,encodeIdMap,decodeIdMap,ContentAttribute,createContentAttribute,ContentMap,createContentMap,readContentMap,writeContentMap,encodeContentMap,decodeContentMap),IdSet#forEach,covers,coveredLengthandslice,equalIdSetsnothing A write past the end of a node that is not in a document yet throws when you make it. The
EngineDeepEventtype is removed fromedytor/crdt/edytorandedytor/protocol. -
ProviderStackno longer hasprefetch,lastUpdatedanddocumentSnapshot. Import them fromedytoras before, or read them frombindCrdt(Y).providers, which still carries them.
Writes and handles
-
One write API. Every write is one of the document’s operations, with the same names and arguments on the view and on the bare document (
DOCUMENT_WRITES, fromedytor/crdt/edytor, lists them).edytor.insertText(id, offset, text)is dispatched (plugin hooks and vetoes, normalization, one undo step, the result caret, refused on a readonly view);edytor.document.insertText(id, offset, text)writes directly. Both answer anOpResult(status, theidswritten). See Editing programmatically and Operations. -
Handles only read.
Block,TextandInlineBlockkeep their reads and lose every write; pass their ids to the view’s operations:Removed Use block.insertBlockAfter({ block }),insertBlockBefore,addChildBlock({ block, index }),addChildBlocks,block.insertChildren(index, blocks)edytor.insertBlocks({ parent, index }, [block])(parent: nullis the root;edytor.document.positionOf(id)is a block’s own place)block.splitBlock({ index, text }),duplicateBlock(),removeBlock({ keepChildren }),nestBlock(),unNestBlock(),mergeBlockBackward(),mergeBlockForward()edytor.splitBlock(id, offset, newId, tail?),duplicateBlock(id),deleteBlock(id, { keepChildren }),nestBlock(id, parentId),unNestBlock(id),mergeBackward(id),mergeForward(id)block.setBlock({ value }),block.type = …,block.pushContentIntoBlockedytor.setBlock(id, value)(itscontentandchildrentake JSON),edytor.setBlock(id, { type })block.setData(data),atom.setData(data),block.patchData({ ops, atom })edytor.patchData(id, [{ path: [], value: data }]),edytor.patchData({ block: id, atom }, ops);nulltargets the document’s own datablock.moveBlock({ path }),block.moveBlocks({ blocks, path })edytor.moveBlocks(ids, { parent, index }), oredytor.move(request)block.addInlineBlock({ offset, block }),block.removeInlineBlock({ index })edytor.insertInline(id, offset, atom)(anidis minted when you leave it out),edytor.removeInline(id, atomId)block.deleteContentAtRange({ start, end }),text.insertText({ value, start, end }),text.deleteText(…),text.splitText,text.setText,text.insertAt,text.deleteAtedytor.deleteText(id, offset, length),edytor.insertText(id, offset, text, marks?),edytor.deleteRange(from, to),edytor.replaceRange(from, to)(block offsets: a text’s offset plustext.segStart)text.markText({ mark, value, toggle }),text.removeMarksFromText(),text.formatAtedytor.formatRange(id, offset, length, { [mark]: value })(nullremoves it),edytor.clearMarks(id, offset, length); the toggle over the selection isrichTextOperations(edytor).setMarkAtRange(mark)block.normalizeContent(),block.normalizeChildren()nothing: the view runs them after every operation block.model(aDocBlock),document.block(id), theDocBlockandNodeReftypesthe document’s operations and reads, given the id ( document.insertText(id, 0, '> '),document.deleteBlock(id),document.contentItems(id)) -
One name per write. The document’s and the view’s alias writes are removed, with their
prepareforms and hook operation names:Removed Use insertBlock(dest, spec)insertBlocks(dest, [spec])moveBlock(id, dest)moveBlocks([id], dest)setBlockData(id, data)patchData(id, [{ path: [], value: data }])setInlineData(id, atom, data)patchData({ block: id, atom }, [{ path: [], value: data }])setMark(id, offset, length, name, value),unsetMark(id, offset, length, name)formatRange(id, offset, length, { [name]: value }),formatRange(id, offset, length, { [name]: null })A comments client’s document (
CommentDocument) writes withformatRangein place ofunsetMark. -
Table operations are the table plugin’s. The document no longer has
insertTableRow,deleteTableRows,insertTableColumn,deleteTableColumn,moveTableColumn,moveTableRowsandfillTableCell(nor theirprepareforms): import them fromedytorand give them the document first,document.apply(insertTableRow(document, table, 1))fordocument.insertTableRow(table, 1). They answer the same plans and results; deleting a table’s last column also removes a container the table leaves empty, as every other delete does. The table reads (tableGrid,tableColumns,isTable, …) stay on the document. See Table. -
Data is read, not assigned.
block.data,atom.dataandedytor.dataare read-only (typedReadonly): an assignment such asblock.data.done = trueorbind:value={block.data.title}no longer writes. Write withedytor.patchData(block.id, [{ path: ['done'], value: true }]); for a bound field, a function binding:bind:value={() => block.data.title, (title) => edytor.patchData(block.id, [{ path: ['title'], value: title }])}. Typing into one string property still joins one undo step. -
Moves and range writes.
edytor.moveBlocks(request)andedytor.canMoveBlocks(request)(a target and position, or a direction) are replaced byedytor.move(request)andedytor.canMove(request);edytor.moveBlocks(ids, destination)is the document’s operation.edytor.deleteBlocks({ blocks })isedytor.deleteBlocks(ids)andedytor.insertFlow({ flow, target })isedytor.insertFlow(target, flow).edytor.deleteContentWithinSelectionis removed (useedytor.deleteRange(from, to)), and so isedytor.edytor. -
Hooks see the operation’s arguments. In
onBeforeOperationandonAfterOperation, an operation’spayloadis its argument list ([id, offset, text, marks]forinsertText, typed byChangePayload), andblockis the block it writes (forinsertBlocks, their parent). A command keeps its object payload, typed by the newCommands:acceptSuggestion,replaceMatches,addComment,moveText,inlineMarkdown,insertDividerand the table commands (ReplaceMatchesisCommands['replaceMatches']). A command’s steps are shown as the operations they perform:insertBlocks,moveBlocks,deleteBlock,splitBlock,mergeBlocks,setBlockType,patchData,insertText,insertInline,deleteText,removeInlineandformatRange. -
The old operation names are gone. Hooks no longer see
insertBlock,insertBlockAfter,insertBlockBefore,addChildBlock(s),removeBlock,mergeBlockBackward,mergeBlockForward,moveBlock,setBlockData,setInlineData,setMark,unsetMark,deleteContentAtRange,deleteContentWithinSelection,addInlineBlock,removeInlineBlock,pushContentIntoBlock,markText,removeMarksFromText,splitText,setTextorwrapBlocks: Enter runssplitBlock,insertBlocks,unNestBlockorsetBlock, BackspacemergeBackward,deleteText,deleteRangeordeleteBlocks, Turn into columnswrapInLayout, and a move beside a blockplaceBeside([ids, target, side]; thebesidepayload and theBlockBesidetype are gone). -
Normalization runs after every write.
normalizeContentruns on every block whose content, kind or data an operation wrote (typing included) and on a block it inserted;normalizeChildrenon the parents whose children changed. -
Results.
CommandResult.valueis removed: an operation answers itsOpResult, whoseidsname what it created, anddispatcher.caret(…)’s body answers one too.dispatcher.plan(operation, payload, prepare, block?)runs a plan you prepare as one named command.TextOperations,BlockOperationsandTextInsertionPayloadare removed; a trigger controller’shandleTextInsertion(text, block, start, value)takes the offset and the text.
Selection
-
The selection has one view, its projection.
selection.state(and theSelectionStatetype) and the setterssetAtTextOffset,setAtRange,setAtTextsRange,setAtBlockRange,selectBlocks,addBlockToSelectionandremoveBlockFromSelectionare removed. Read the selection fromselection.projection(startandendas{ block, offset },isCollapsed,isReversed,blocks,marks,content), the caret fromselection.caret({ block, offset }) and the blocks fromselection.selectedBlocks; the text segment that shows an offset isblock.textAtOffset(offset). Write it withselection.setCaret({ block, offset }), orselection.select(value)for anything else:Removed Use state.startBlockselection.caret?.block, oredytor.idToBlock.get(selection.projection.start?.block ?? '')for the start of a rangesetAtTextOffset(text, offset)setCaret({ block: text.parent, offset: text.segStart + offset })setAtRange(…),setAtTextsRange(…),setAtBlockRange(block)select(selection.textValue(startText, startOffset, endText, endOffset, isReversed)), orselect({ kind: 'text', anchor, focus })with anchors fromedytor.document.anchorAt(blockId, offset, affinity)selectBlocks(a, b),addBlockToSelection,removeBlockFromSelectionselect({ kind: 'blocks', ids: [a.id, b.id] }), with or without the id to add or remove;selectBlocks()with no block has no replacement (select the range you want)
Plugins and chrome
-
Every bundled plugin is a factory. The plugin constants are removed: call the factory, with or without options.
isImagePlugin,isSuggestionsPlugin,isColumnsPluginandisTablePluginare removed: any instance of a default plugin’s factory you list replaces that default.Removed Use richTextPlugin,codePlugin,imagePlugin,suggestionsPlugin,columnsPlugin,tablePlugin,marqueePlugincreateRichTextPlugin(),createCodePlugin(),createImagePlugin(),createSuggestionsPlugin(),createColumnsPlugin(),createTablePlugin(),createMarqueePlugin()embedPlugin,bookmarkPlugin,filePlugin,videoPlugin,audioPlugin,pagePlugin,tocPlugincreateEmbedPlugin(),createBookmarkPlugin(),createFilePlugin(),createVideoPlugin(),createAudioPlugin(),createPagePlugin(),createTocPlugin()markdownShortcutsPlugin,arrowMovePlugincreateMarkdownShortcutsPlugin(),createArrowMovePlugin()slashMenuPlugin,blockMenuPlugin,toolbarPlugin,findPlugin,blockHandlesPlugintheir factories with your snippets (below) -
The chrome is headless. The package draws no menu, popup, block handle, panel or card: every surface is the snippet you pass its plugin, and a surface without its snippet renders nothing while its controller still works (
/dividerand Enter still insert a divider with no menu shown). Copy the ready-made menus for the Notion-style markup (chrome.svelteholds every snippet,plugins.tspasses them to each factory). See Menus and handles. Each surface and its snippet:Surface Plugin and option The snippet receives Slash menu createSlashMenuPlugin({ menu })SlashMenuControllerA trigger’s menu createMentionPlugin({ menu }),createPageLinkPlugin({ menu }), aTrigger’smenuTriggerMenuControllerBlock menu createBlockMenuPlugin({ menu })BlockMenuControllerBlock handles createBlockHandlesPlugin({ handle, draggable })BlockHandleSnippetPayloadToolbar and link card createToolbarPlugin({ toolbar, card })ToolbarControllerPasted-URL menu createEmbedPlugin({ menu }),createBookmarkPlugin({ menu })UrlPasteControllerEvery empty image and media block createMediaEmptyPlugin({ empty })MediaEmptyController(readcontroller.kind)Image toolbar createImageToolbarPlugin({ toolbar })ImageToolbarCallout icon picker createCalloutIconsPlugin({ picker, icons })CalloutIconPickerTable grips, menu and +barscreateTablePlugin({ grip, menu, add })TableGripPayload,TableChrome,TableAddPayloadCode header and language list createCodePlugin({ header, menu })CodeHeader,LanguageMenuEquation panel createEquationPlugin({ panel })EquationEditorComment cards and the margin’s top createCommentsPlugin({ card, header })CommentCardPayload,CommentsControllerFind bar createFindPlugin({ bar })FindControllerSuggestion bar createSuggestionBarPlugin({ bar })SuggestionBarPayloadMarquee rectangle createMarqueePlugin({ box })MarqueeBoxPayloadVersion history new VersionHistory(options)in your componentthe controller itself -
Chrome moved to plugins of its own. An app lists only the chrome it uses, and
<Edytor />ships none of it:Removed Use <Edytor blockHandles>createBlockHandlesPlugin({ handle, draggable }); without ahandle, no handle showscreateImagePlugin({ upload, toolbar, empty }),ImagePluginOptionscreateImagePlugin()(the kind and its resize handles),createImageToolbarPlugin({ toolbar }),createMediaEmptyPlugin({ empty }),createUploadsPlugin({ upload })emptyon the embed, bookmark, file, video and audio pluginscreateMediaEmptyPlugin({ empty })once, for every kinduploadon the file, video and audio plugins;MediaPluginOptionscreateUploadsPlugin({ upload })once (the empty blocks’ Upload and pasted or dropped files, each placed as a block of the kind that takes it);createFilePlugin(),createVideoPlugin()andcreateAudioPlugin()take no optionscreateRichTextPlugin({ callout: { icon, icons, picker } })createRichTextPlugin({ callout: { icon } })(the default icon) andcreateCalloutIconsPlugin({ picker, icons })(CALLOUT_ICONSby default), which also adds the block menu’s Change icon row; without it, a callout’s icon is no buttoncreateSuggestionsPlugin({ bar }),SuggestionsOptionscreateSuggestionsPlugin()(the keys, a default plugin) andcreateSuggestionBarPlugin({ bar })(SuggestionBarOptions)<HistoryPanel>,HistoryPanelProps,HistoryVersionItem,defaultHistoryLabelsnew VersionHistory({ client, document, plugins, locale }); draw the list (versions,option(index),keys,select(key)), the preview (<Edytor readonly value={history.preview} plugins={history.previewPlugins}>, keyed bypreviewKey) and Restore (restore(),undo(),status). See History panelA kind takes files through its record’s
upload(KindUpload:accepts,fallback,data,filled,preview); your uploader may branch on the file’s type. -
What the snippets receive changed.
- One surface, one snippet: the row snippets are removed (the slash menu’s and a trigger’s
item, withSlashMenuItemandTriggerItemPayload); yourmenudraws its rows. The+menu no longer wraps yourmenu: put{@attach controller.keys}on the element that holds its keyboard (a field, or the menu itself). The toolbar’slinkCardis removed: withoutcard, no card shows. - The block handle’s payload drops
addable(alwaystrue) andlabels, and gainsbeside(Alt+click adds a column). The drop indicator and the nest backdrop are still placed by the plugin ([data-edytor-drop-indicator],[data-edytor-drop-backdrop]), and now painted by the Notion theme (below).BlockHandleController.registerHandlereturns() => void. - A grip click is answered by its event only:
createBlockHandlesPlugin({ onActivate })and theBlockHandleActivationtype are removed. A grip click dispatchesedytor-block-activate(BLOCK_ACTIVATE_EVENT,detail: BlockActivation, cancelable) on the editor’s root, which the block menu plugin, or your own listener, answers withpreventDefault(). - The image toolbar’s snippet receives an
ImageToolbar(box,align,alt,setAlt,editing,toggleAlt,closeAlt,bar,altField,readonly), no longerImageControls. - Empty blocks share one controller:
ImageEmptyControllerandImageEmptyFailureare removed, and an empty image receives aMediaEmptyControllerwhosekindisimage.MediaEmptyFailuregainsinline(an inline image overMAX_INLINE_IMAGE_BYTES),failedisnullwhen nothing failed (it wasfalsefor media), andtoggle(),label,kindLabelsand the image’sinlineLimitare removed (setopen). An uploading pasted or dropped image is youremptysnippet’s to show (pending:status,progress,preview):[data-edytor-image-uploading]is gone, and the Notion theme no longer styles the empty states. - A comment card is your
cardfor a thread and for the comment being written (thread: null:comments.submit(body),comments.cancel()); the margin’s top (“Resolved (n)”) is yourheader. Withoutcard, no sidebar shows. - The table menu names its row or column by id:
TableMenuis{ kind, table, id }(the row’s block id or the column’s id;rowandcolumnare gone) andTableMenuRowis{ id }.TableChrome‘sopen,rows,runRow,rowId(row),menuId,addRowandaddColumnare removed: yourmenudrawschrome.items(each withrun,disabled,danger,option; an item’siconis gone, name it byitem.item.id), youraddcalls its payload’sadd. A grip’s drag shows the blocks’ ghost ([data-edytor-drag-preview], the row’s or column’s cells as they look);[data-edytor-table-drag-preview]is gone. - The suggestion bar’s payload gains
macand the callout pickercolumns.
- One surface, one snippet: the row snippets are removed (the slash menu’s and a trigger’s
-
One way to write a piece: attach what the editor needs, render the rest. Every payload gives what the editor needs of an element (its id and role, the ARIA it keeps in step, its keys, its presses, its marker) as an attachment, and everything else as values you render and functions you call; nothing is spread. A custom checkbox is written as a custom menu row is. What changes (Menus and handles):
- A row’s
option(index), and a row payload’soption, is an attachment: write{@attach menu.option(index)}for{...menu.option(index)}. It no longer setsdata-selected: an attachment’s attributes are set after your markup, so a scoped style cannot see them; draw the keyboard’s row from its value (data-selected={item.selected},menu.index === index).OptionAttributesis removed. - The block handle’s
gripis an attachment ({@attach grip}foruse:grip), and the newplusis the+’s ({@attach plus}: its click callsaddunder it, its press keeps the focus). Each keeps the ARIA of the menu it opened, so the payload’sexpanded,controlsandhaspopupare removed; the grip also sets itsaria-keyshortcuts. - The find bar’s fields take
{@attach find.field}and{@attach find.replaceField}(wasuse:), and the version list{@attach history.keys}(wasonkeydown={history.keys}).
- A row’s
-
Every chrome list is one list model. The slash, trigger, language, callout, pasted-link and table menus share it: the keyboard’s row is
index(wasselectedIndex, the block menu’s too),move(step)moves it (was the menus’moveSelection(step)), and a row’s element id is the list’slistIdand its position,rowId(index). The slash menu’soptionId(command), a trigger menu’s and the URL paste menu’soptionId(index), the callout picker’soptionId(index)andid, the language list’srowId(row)and the table menu’smenuIdare removed.- The callout picker’s rows are every menu’s rows:
{@attach picker.option(i)}(its id, role,aria-selected,aria-checked, no handlers); runpicker.pick(i)on a row’s click.CalloutIconOptionand thedata-active,data-edytor-callout-icon-choiceanddata-edytor-callout-icon-removeattributes are removed. The picker’s panel is placed, and closed on a press or focus outside, as the code language list’s is.
- The callout picker’s rows are every menu’s rows:
-
Controllers lose their dead and duplicate members. The block menu runs a row with
run(row)(a row of the menu or of its flyout; Enter runs the highlighted one):runSelected()andrunFlyout()are removed, andduplicate(block)andduplicateAll(blocks)are oneduplicate(blocks, select).CodeHeader.setLanguageandCodeHeader.languagesare removed (the language list’spicksets a block’s language; yourlanguagesare your rows), and so areBlockMenuController.publish, the trigger and slash menus’publish,ToolbarController.publish(each surface’spopupattachment publishes it) andMarqueeController.pressing. Members only their own class read are private:BlockHandleController.activateBlockandhandleKeyDown,BlockMenuController.matchingKinds, the trigger menus’activeRange,InlineBlock._defand about a hundred undocumented ones. -
A kind is restyled by a plugin;
<Edytor>takes no snippet props and noplaceholder. The<type>Block,<type>Markand<type>InlineBlocksnippets passed to<Edytor>(andEdytorOptions.snippets, with theSnippetstype) are removed: list a plugin before the one that defines the kind, naming only its snippet (plugins={[() => ({ blocks: { quote: quoteSnippet } }), …]}). Definitions are first-wins field by field, so that plugin replaces the snippet and keeps the kind’s element, roles, presets and hooks. Theplaceholderprop and option are removed: returnplaceholderfrom a plugin (plugins={[() => ({ placeholder: richTextPlaceholder })]}); a placeholder function receives the view as its second argument. A retired prop or option an untyped caller still passes (hotKeys,blockDnd) is ignored without a warning. -
The plugins’ stylesheets keep only what makes their blocks work; every look is the Notion theme’s. Without
edytor/themes/notion.cssthe blocks work and are unstyled. An app without the theme that relied on those looks styles the same selectors (Without the theme).- What moved to the theme: the code panel, its header’s place over it, the code font and the syntax colours (
--edytor-code-background,--edytor-code-colornow read by the theme); a table’s borders, its cells’ padding and a header cell’s shade (--edytor-table-border,--edytor-table-header-background); a column’s flush edges and the highlight of a selected layout (--edytor-block-selectionis no longer read: the theme uses--notion-block-selection); an equation’s hover, padding, centring, placeholder panel and source font; the callout icon button’s reset and the empty body hint’s colour and cursor; a callout title’s weight; the page block’s link and the table of contents’ entries (their button resets and indent); the mention and page link atoms’ colour, weight and selection (nowdata-selected="true", was aselectedclass). - What the plugins keep: the layout (columns side by side, a table’s grid, a code block’s spaces and sideways scroll, a wide equation’s scroll, an embed’s frame size), what is never selected (a code header, an empty body’s hint), and where the overlay’s cues stand and when they show.
- What moved to the theme: the code panel, its header’s place over it, the code font and the syntax colours (
-
The overlay’s visual cues are placed by the plugins and painted by the theme. A block drag’s drop line and nest backdrop, a table’s drop line and column resize line, a layout gap’s resize guides, an image’s resize pills and other users’ carets, ranges and name pills keep their place, size, layer, pointer and visibility in the plugins (states as
data-shownanddata-dragging); every colour, radius, opacity, fade, shadow and font is the Notion theme’s, whose rules reach the overlay whether its class is on the editor or around it. Without the theme they are unpainted, as the drop line already was; to paint them yourself, style their elements (Without the theme).- A user’s colour is no longer a background baked on their caret, range and label: it is the variable
--edytor-remote-coloron the caret and the ranges, which a theme paints with. - A focused column or table resize band keeps the browser’s focus outline without the theme (the theme replaces it with the blue line).
- The variables
--edytor-columns-resize-color,--edytor-column-resize-color,--edytor-table-resize-color,--edytor-table-drop-colorand--edytor-image-handle-colorare read by the theme; the demo’s handle markup no longer paints the drop line and backdrop.
- A user’s colour is no longer a background baked on their caret, range and label: it is the variable
-
Input rules and triggers are wired by the plugin that declares them. A plugin’s definitions no longer take
inputRulesandtriggers: returnwithRulesAndTriggers(edytor, definitions, { inputRules, triggers })from the plugin ((edytor) => withRulesAndTriggers(edytor, { inlineBlocks }, { triggers: [mention] })). The bundled mention, page link, markdown shortcuts and equation plugins do.
Labels
- The chrome’s words are your markup’s; the package keeps only its own. The controllers carry no words and name none of your elements: give your menus, bars and fields their
aria-label, and write their text.- No plugin factory takes
labelsorkeywords:<Edytor labels>(EdytorOptions.labels) takes any entry of any section ({ richText: { kinds: { … } }, table: { … } }) andkeywordsby command id, for every plugin of the view.PartialLabelsis that whole dictionary (no section parameter). - The dictionary keeps only the words the package shows, says or searches: the
toolbar,slashMenu,blockHandles,find,suggestions,mentionandhistorysections are removed, with their types (ToolbarLabels,SlashMenuLabels,BlockHandlesLabels,FindLabels,SuggestionsLabels,MentionLabels,HistoryPanelLabels), and so are the chrome entries of the other sections (the block menu’s search field, headings and empty state, the image’s and media blocks’ empty panels and toolbar, the pasted-link menu, the code header and language list, the callout picker’s name and Remove icon, the comment cards’, the table grips’ menus,+and names, the equation panel’s, the trigger menus’triggerMenu,searchingandnoResults). A media kind’s entry is its name (media.videois “Video”,MediaKindLabelsis removed), andcode.languagesis gone: name a language in yourlanguagesrows. controller.labelsis removed from every controller and payload.SlashMenuController.groupName,ToolbarController.colorName,MediaEmptyController.labelandkindLabels, the rows’ and payloads’label(MenuItemPayload,TableMenuRow,TableGripPayload,TableAddPayload,UrlPasteOption,UrlPasteOffer; name a row by itsitem.id), a trigger’sname,emptyandsearchingand its controller’s, andTOOLBAR_COLORSare removed: your palette is your markup’s (setColortakes any CSS colour).VersionHistorytakes nolabels:statusis a code (VersionHistoryStatus),dateOfnames the day (version.slotits half), and the editors areversion.editorsandversion.more.CommentsController.userOfnames a user without anameby their id (“You” is your card’s).createRichTextPlaceholder(labels)isrichTextPlaceholder, a placeholder that reads the view’srichTextlabels.
- No plugin factory takes
Removed kinds and dependencies
- The
detailsandhorizontalRulekinds are removed (andrichTextKinds.horizontalRule): they were other names fortoggleanddivider. Stored ones render as unknown kinds; HTML import already read<details>and<hr>as those. - No drag-and-drop dependencies. The editor no longer depends on Atlassian’s drag-and-drop packages (
@atlaskit/pragmatic-drag-and-dropand its hitbox and auto-scroll packages): it carries a copy of the parts its drags use, unchanged, and dragging behaves as before. An app that uses Pragmatic drag and drop itself installs it on its own; its drags and the editor’s no longer share one adapter. - Two misuse checks run in development only.
new Edytor({ document, doc })(adocumentwithdoc,awareness,actororrequireHydration) anddispatcher.outside(body)called inside a transaction still throw in development; a production build no longer checks (thedocumentwins; the body’s writes join the open transaction).
New
- The controls inside blocks take your markup. Each keeps its markup as the default, and an option of its plugin replaces it with your snippet, typed by an exported payload that carries its state, its action (written through the document as before, or your callback), its words and URLs, which you render, and an attachment for your element (
{@attach payload.control}, a media link’s{@attach payload.link}: its marker, ARIA, press and click), as a menu’s row takes its own:createRichTextPlugin({ checkbox, calloutIcon, emptyBody })(TodoCheckboxPayload,CalloutIconPayload,EmptyBodyPayload),createEquationPlugin({ placeholder, error })(EquationPlaceholderPayload,EquationErrorPayload),createBookmarkPlugin({ card })(BookmarkCardPayload),createFilePlugin({ row })(FilePluginOptions,FileRowPayload),createEmbedPlugin({ fallback })(EmbedFallbackPayload),createTocPlugin({ entry, empty })(TocEntryPayload,TocEmptyPayload) andcreatePagePlugin({ link })(PageBlockLinkPayload).- The default markup renders its links’
hrefand its markers too, so a server-rendered readonly view is styled and links before it runs. See Controls inside blocks.
- The default markup renders its links’
Fixed
- The Notion theme’s page block rule no longer reaches a page link in a line: it applied to the page link atom too, laying it out as a full-width row.
- A text delete no longer throws in a Node process run with
NODE_ENV=development: the engine froze the values it stored in that mode, and the editor’s delete records cannot be frozen. The engine no longer freezes them. - A semantics conflict names the declarations as given. A
SemanticConflictErrorfromadoptSemantics(a view’s plugin, or a reattach, disagreeing with the document) carries the two declarations inexistingandincomingas they were written, asmergeSemanticsreports them, instead of their normalized form. Itssubjectand its class are unchanged. - A key typed right after a menu, toolbar, panel or the find bar gives the keys back lands at the caret, never at the start of the editor: every piece of chrome now returns the focus the way
edytor.focus()does, so the caret the browser places for that focus is never taken for the user’s. - The callout icon picker’s
popupkeeps a custom picker’s own role and name, as every other menu’spopupdoes, and a press on the picker keeps the focus where it is. - A kind’s HTML export escapes its attributes and text as the rest of the copied HTML does (
&,"): the image, callout, embed, bookmark, file, video and audio exports wrote numeric references (&), which read back the same.
From 1.0.0-rc.2
Breaking changes
- Long pages: one switch, any theme. The
edytor-long-pageclass on the editor or an element around it turns on skipping off-screen blocks, with their remembered height; it replaces the Notion theme’s--edytor-block-visibility: auto(replace the variable with the class). Without the switch, top-level blocks no longer carry a remembered height, which saved nothing and cost a long page about 2.5 ms a frame. - Lighter markup. A block leaves far fewer of the renderer’s hidden nodes in the page (the empty comments and empty text nodes Svelte places content with): a paragraph 10 where it left 33, and no whitespace between tags. The browser walks these nodes after every key, so a key on a long page costs less: at 5,000 blocks a character takes 16 ms where it took 37, Enter 35 where it took 68, a block move 29 where it took 70, a paste of 50 lines 44 where it took 76, and the view mounts a quarter faster (in our measurements; at 1,000 blocks each key takes about 30 % less). The text, the elements and their attributes are unchanged; a block’s
textContentno longer has a space between its own text and its nested blocks’. - Equations load KaTeX from a CDN by default.
createEquationPlugin()with nokatexoption now loads KaTeX from jsDelivr the first time an equation shows in a browser (its module and its stylesheet, added once to the page’s head; the version pinned,KATEX_VERSION, atKATEX_CDN). Apps no longer need to installkatex, importkatex/dist/katex.min.cssor passkatex: () => import('katex'): drop them to keep KaTeX out of your bundle.katexalso takes a URL (another copy of KaTeX’sdistfolder) orfalse(no drawing, the TeX source shows); your own loader still works as before. A page with a Content Security Policy allowshttps://cdn.jsdelivr.netinscript-src,style-srcandfont-src, or keeps its own loader. See where KaTeX comes from. - The code block’s language is a searchable list. The header’s language is a button with a chevron that opens a list of the languages under it, with a search field: type to filter, click a row or press Enter; Alt+F10 in a code line moves the focus to it. It replaces the native
<select data-edytor-code-language>, which read as plain text and which the keyboard could not reach: a theme rule forselect[data-edytor-code-language]now targetsbutton[data-edytor-code-language], the Copy button is[data-edytor-code-copy], and the panel’s colors are custom properties (--edytor-code-backgroundand others). A complete label dictionary of your own (satisfies Labels) addscode.searchandcode.noResults. See languages. - A callout is an icon, a title and a content. Its own text is its title, semibold, with the placeholder “Callout title” (it was “Type something…”, only while focused); its children are its content, any blocks. Enter at the end of the title now goes into the content (it used to start a paragraph after a callout without children). Copied, a callout is
<div data-edytor-callout="💡"><p>Title</p>…</div>and pastes back as a callout.
New
- A click outside ends a block selection. Pressing anywhere outside the editor and its menus clears the selected blocks, as in Notion. Shift or Mod keeps them, and so does a press inside an element marked
data-edytor-keep-selection: add it to your own toolbar if its buttons act on the selected blocks. - Select blocks with a rectangle. The new opt-in
marqueePlugin(createMarqueePlugin({ container, threshold, box })) is Notion’s rubber band: press in the editor’s margins (the gutter around the block handles, the editor’s own padding, the page around it withcontainer) or below the last block and drag; a rectangle follows the pointer and the blocks it touches are selected while you drag, a block with its children, in columns the blocks of the columns it crosses, a closed toggle without its hidden content. Shift or Mod adds to the selection, Escape gives the previous one back, the page scrolls near its top and bottom edges, and on release the keys act on the selected blocks. A click below the last block still adds the trailing paragraph. The rectangle takes aboxsnippet (MarqueeBoxPayload) and the--edytor-marquee-background,--edytor-marquee-borderand--edytor-marquee-radiusvariables. No dependency is added. See Marquee selection. - Block drops outside the blocks. While you drag a block, a pointer left or right of the editor’s blocks (within its height) still drops on the row at that height, up to 240px past the handle column and past the blocks’ right edge: on the left before or after that row, on the right as at the row’s own right edge; over columns, the nearest column’s row. With the columns plugin the first 120px of each margin stay the beside bands (a new column). Set the reach with
--edytor-drop-reach(Dropping outside the blocks). - Table rows and columns drag by their grips. Drag a row’s grip up or down, or a column’s grip left or right: a blue line shows where it lands, and the drop moves it (its cells with it) in one undo step. A click on a grip still opens its menu, whose Move items stay the keyboard’s way. A grip no longer keeps the focus in the editor while pressed (that would stop its drag): Escape on it, or in its menu, gives the keys back. See Table.
- A table stays inside the page. Resizing a column grows it into the room the table leaves free, then into the column on its right (which narrows by as much, both widths one undo step), never past the room at its place (the text column, or a layout’s column), in the preview and in the width written. A table already wider (widths set on a wider screen) keeps its widths and scrolls sideways in its own box, which no longer widens a page that sizes the editor by its content; its column edges, grips and
+show only over the part in view. The new--edytor-table-drop-colorsets the drop line’s colour. - Leaving the last nested block. ↓ on the last line of the document’s last block, when that block is not a top-level paragraph (a toggle’s body or header, a callout, a quote, a nested list item, a column, a table’s last row, a code block’s last line, a heading), puts the caret in an empty paragraph after the document’s last block, created as one undo step. A click below the last block does the same, as in Notion. The code block’s own ↓ rule is replaced by this one: in a code block nested in a toggle at the end of the document, the new paragraph now goes after the toggle, not inside it. The root has a bottom padding to click in,
--edytor-trailing-space(2em); set it, or your own padding on the root, to change it. - Toggles and callouts show where their content goes. An open toggle with no content, and a callout with none, show “Empty toggle. Click or drop blocks inside.” (or “Empty callout…”); clicking it starts the content, and a block dragged onto it goes inside. A toggle you create (the slash menu,
>, Turn into a block without children) opens, so Enter after its title goes into it. The words are the rich text labels’emptyBody. - Callout icons. Click a callout’s icon to pick another, or Remove icon (
data.iconis then''; unset, the callout shows the editor’s default).createRichTextPlugin({ callout: { icon, icons, picker } })sets the default icon, the picker’s choices (CALLOUT_ICONSby default) and your own picker markup (a snippet receivingCalloutIconPicker). The block menu of a callout has a Change icon row. The words are the rich text labels’calloutIcon. bodyon kind records. A container whose body shows even while empty: Enter at the end of its header opens its first child, as the callout’s does.- The room logs
sizeonce when a document reaches 80 % of its quota (EDYTOR_DOCUMENT_WARNING,documentWarning), andmetrics()reports the quota asdocumentLimit: watch for documents nearing the maximum size you chose. - Every built-in popup, menu, toolbar and panel takes a typed snippet that keeps the keyboard and the ARIA (Menus and handles). The keys and the accessibility now live on the controllers as attachments, which the built-in markup uses too, so a snippet that uses them behaves the same:
popup(the list’s id, role and name, its publication to the editor’s root),keys(the element that holds the keyboard),option(index)(a row’s id, role and state), the block menu’sflyoutMenu, the toolbar’slinkField, the image toolbar’sbarandaltField, an empty block’sfield. Existing snippets keep their payloads. New:- snippet options: a trigger’s
menu(andcreateMentionPlugin({ menu }),createPageLinkPlugin({ menu })),createToolbarPlugin({ card })for the link card,menuandemptyon the embed and bookmark plugins (the menu a pasted URL opens, the empty block),emptyon the file, video and audio plugins,createImagePlugin({ toolbar, empty }), and<HistoryPanel item>(a whole version row, one object argument); - row payloads share one shape,
MenuItemPayload({ item, id, selected, run, select, option }):SlashMenuItemgainsitem,labelandoption,TriggerItemPayloadgainsrun(the same aspick) andoption;SuggestionBarPayloadgainslabels; - exported types:
MenuItemPayload,OptionAttributes,UrlPasteController,UrlPasteOption,UrlPasteOffer,ImageControls,ImageBox,ImageEmptyController,ImageEmptyFailure,MediaEmptyController,MediaEmptyFailure,MediaKind,CommentCardPayload,HistoryVersionItem; the block menu’s controller gainssearch(query), the toolbar’slinkFieldId.
- snippet options: a trigger’s
- Tables, code blocks and equations take your markup too (Menus and handles):
createTablePlugin({ grip, menu, add }): a row’s or column’s grip (TableGripPayload;{@attach payload.grip}keeps its drag, the click that opens its menu, its keys and its ARIA), a grip’s menu (TableChrome: its rowsitems, each aTableMenuItem, and thepopup,keysandoption(index)attachments) and the+under and beside the table (TableAddPayload);createCodePlugin({ header, menu }): a code block’s header (CodeHeader: the language,setLanguage,copy,copied, and thebuttonattachment that opens the list) and the language list (LanguageMenu: its rowsitems, each aLanguageMenuItem, and thekeys,popupandoption(index)attachments);createEquationPlugin({ panel }): the equation editor (EquationEditor, whosefieldattachment gives your source field the focus and the keys);- the block handle’s payload gains
expandedandcontrols(what its+and grip opened, for theiraria-expandedandaria-controls) andlabels, andadd(alt, anchor)opens the menu under your+; - exported types:
TableChrome,TableMenu,TableMenuRow,TableMenuItem,TableGripPayload,TableAddPayload,CodeHeader,LanguageMenu,LanguageMenuItem,LanguageRow,EquationEditor,EquationTarget;OptionAttributesgainsaria-disabled.
- A table grip’s menu takes the keys. It now takes the focus as it opens and is a real menu: ↓/↑ walk the items that can run (Move up on the first row cannot,
aria-disabled), Home/End reach the ends, Enter or Space runs the item, Escape or Tab closes it and gives the keys back to the editor; ↓ on a grip opens its menu. The editor’s root names the open menu (aria-controls,aria-haspopup) and the grip says so (aria-controls). A grip, a+bar and a menu now stand in a host each ([data-edytor-table-grip-host],[data-edytor-table-add-host],[data-edytor-table-menu-host]), which places them: a theme rule that positioned[data-edytor-table-grip]or[data-edytor-table-add]itself should style their host instead.
Fixed
- A new block paints before its handle. After Enter or a paste on a long page, the new blocks’ text shows in the key’s own frame and their handles mount right after it, so the key’s frame no longer waits for them.
- A key on a long page no longer costs the editor more. A caret that moves to another block (Enter, an arrow key, a click) and a block selection render again only the blocks they enter and leave, not every block of the page; a block added or moved is checked alone, not with every other block; the block handles and the chrome look only at the blocks near the screen, and a block’s size is watched only there. The editor’s own work for a key is the same at 5,000 blocks as at 1,000: at 5,000 blocks, Enter takes less than half the time it took (120 → 54 ms in our measurements), a paste of 50 lines too (137 → 60 ms), a block move a third less (72 → 47 ms). Typing a character is mostly the browser’s own work on a long page and barely changes; Long pages says what grows and why.
block.nextBlockandblock.previousBlockanswernullpast either end, as their types say (they answeredundefined). - An HTML paste takes one leading paragraph of an element as its text, empty or not: the paragraphs after it are its children.
- the menu a pasted URL opens is named by the editor’s root (
aria-controls,aria-haspopup,aria-activedescendant), as the other menus are. The toolbar’s link field has an id of its own per editor (it was the same on every editor of a page, so two editors’ labels named one field).
From 1.0.0-rc.1
Breaking changes
document.facadeis gone. Deprecated in1.0.0-rc.1, it is no longer in the published types: call the operations on the document itself (document.insertBlock(…),document.toJSON()).
New
- An API reference. The docs list every name each entry point exports, with its declaration and documentation, generated from the published types:
edytor,edytor/cloudflare,edytor/protocolandedytor/crdt/edytor.
From 0.1.0-next.44
1.0.0-rc.1 is the 1.0 release candidate, published under latest (pnpm add edytor; the next tag keeps the pre-releases). Its API is frozen: the published types are the 1.0 contract, and a change to them before 1.0 comes with a note under Breaking changes. document.facade, deprecated here, is the one exception: it goes in the next release.
Breaking changes
selection.select(value)takes the value only. Its second argument named an internal cause (how the projector should treat the change); pass the value alone. TheSelectCausetype is no longer exported.- The document’s operations are its own;
document.facadeis deprecated. Call them on the document:document.insertBlock(…),document.toJSON(),document.prepare.splitBlock(…),document.onChange(…)(theDocumentOperationsinterface).document.facadereturns the same operations and goes in the next release. What it held besides them (the index, the engine hooks, the history factory) is internal.edytorno longer exportsEdytorDoc(the full binding, still inedytor/crdt/edytor): nameDocumentOperationsinstead. A room’stransactcallback, itsfacadeandvalidate’sfacadeare typedDocumentOperationstoo. - The dispatcher’s plumbing is internal.
edytor.dispatcherkeepslast,permits(),run,each,dispatch,lead,caretandoutside; its normalization queue (defer,request,drain,write), its undo cut (cut), its prevention scopes (scope,intercept),authoringandpendingLeadare no longer in the published types.permits()is now documented: whether the view accepts writes.
New
DocumentOperations, and the document’s vocabulary exported.edytorexportsDocumentOperations(withDocumentWritesandDocumentReads) and the types its operations take and answer:BlockId,BlockSpec,ContentItem,Destination,InlineSpec,ProjectedBlock,ProjectedDoc,SplitTail,DocPosition,RangeView,FlowView,ContentRun,DataTarget,OrderPolicy,PlanEffect,PlanStep,DocBlock,NodeRef,MarkEdge, the semantics’ (DocumentSemanticsConfig,KindRecord,MergedSemantics,SchemaProblem), the awareness’s (Awareness,AwarenessStates,AwarenessUpdate,MetaClientState) and the chrome’s (Overlay,Measure,Cells,Cell,Popups,Popup,PopupOpener,Announcer,Handles).document.transact(fn, origin?)takes an origin.
Fixed
- A drag released where the page cannot see it ends. Releasing a text selection drag over an embed (a frame of another site) left the editor waiting for the release, so it stopped showing its selection until the next click. The next pointer move ends it.
- Typing on a very long page does less work. The block handles found the blocks near the screen by watching every block, which the browser rechecked after each keystroke (about 6 ms a key at 10,000 blocks). They now look up the few blocks near the screen directly.
From 0.1.0-next.43
New
- Pasted and dropped files become their blocks. With an
upload, the video, audio and file plugins take pasted and dropped files as the image plugin does: one block per file, each of the kind that takes it (the file block takes what no other kind does), in order, as one undo step, each showing its upload.uploadreceives a second argument,report, whoseprogress(fraction)fills the block’s bar (the image block’s too); anuploadthat ignores it keeps working. TheUploaderandUploadReporttypes are exported. See Pasted and dropped files. - Pasting markdown makes blocks. A plain-text paste (no HTML) with a line of block markdown (a heading, a list or to-do item, a quote, a fence, a divider) becomes the blocks it reads as, with its inline bold, italic, code and links, as one undo step, as in Notion. Text with no block markdown, a paste into a code block and Shift+paste are unchanged. See Pasting markdown.
From 0.1.0-next.42
0.1.0-next.42 was never published to npm: upgrading from 0.1.0-next.41, read the notes of both sections.
Breaking changes
- Single-owner state is read-only.
edytor.selection.value,selection.selectedBlocks,selection.focusedBlocksandedytor.dispatcher.lastcan no longer be assigned (the sets areReadonlySets). Assigningselection.valueused to leave the selected blocks behind; useselection.select(value)or a setter (setCaret,setAtTextOffset, …), which keep them in step.
New
-
edytor.focus(). Focuses the editor without scrolling, keeping its selection, or with none putting the caret at the start of the first text. It replacesedytor.node?.focus()after setting a selection from a menu button. -
The types you meet are exported.
edytornow exports the types its props, options, members and callbacks use, so an app can name them:EdytorProps,EdytorOptions,Snippets, every plugin’s labels type (RichTextLabels,TableLabels, …),Dispatcher, the selection’s (SelectionValue,SelectionPoint,SelectionSegment,SelectionProjection,SelectionState,SelectCause,PresenceSelection,TextAnchor), a hotkey’sKey,ModifierandModifiers, the plugin author’s (BlockView,InlineBlockView,BlockElement,InitializedPlugin,PluginDefinitions,PluginOperations,TextOperations,BlockOperations,BlockBeside,TriggerRange,TextInsertionPayload,RichTextLink,RichTextMark), the document’s (EdytorDoc,DocumentOptions,DataPatch,TextRange,BlockRole,DocAnchor,AnchorAffinity,Flow,FlowLine,FlowTarget, the attribution types) and the sync’s (PrefetchOptions,PrefetchResult,LastUpdatedOptions,EdytorSyncCleanup,WebsocketTarget,ProtocolMismatch,SchemaMismatchDetail,CommentMessage,AwarenessLike,PresenceWriter).
From 0.1.0-next.41
Breaking changes
- Comments have quotas. Comments are on in every room, so the room now bounds them: their stored bytes (
maxBytes,EDYTOR_MAX_COMMENT_BYTES, 4 MiB by default; past it a new thread or reply answers413) and their request rate (maxRequestsPerSecond,EDYTOR_MAX_COMMENT_REQUESTS_PER_SECOND, 2 a second with a ten-second burst, per user over HTTP: past it429; per socket for its subscribes, which are dropped past it). A subscribe on a socket already subscribed no longer sends a second snapshot, androuteDocumentCommentsreads a body no further than 64 KiB even without aContent-Length. Raise the limits if your pages hold more; a client that posts in bursts should retry a429. See Server comments.
New
- Comment quota exports.
edytor/cloudflareexportsDEFAULT_MAX_COMMENT_BYTES,DEFAULT_MAX_COMMENT_REQUESTS_PER_SECOND,COMMENT_ROW_BYTESandcommentBytes;decideCommenttakesbytesandmaxBytes; the refusal reasoncommentsis logged and counted inrefusalCounts.
Fixed
- Typing in a table no longer slows down with its size squared. Each cell worked out its column by reading every cell of the table, so a keystroke re-rendered every cell, each reading every other one. A cell now reads only its table’s column list; a keystroke costs the cell and one pass of the table’s chrome.
From 0.1.0-next.40
Breaking changes
- The handles’ raw write primitives are internal.
Text.insertAt,deleteAtandformatAt, andBlock.insertChildren,deleteChildrenandinsertParts, wrote to the shared document directly: no hooks, no undo step of their own, and they wrote even on a readonly view. They are no longer in the published types, and on a view that refuses writes (readonly, a read-only document) they write nothing. Use the commands instead (text.insertText,text.markText,block.deleteContentAtRange,block.insertBlockAfter…), oredytor.document.facadefor a deliberate raw write outside every view.
From 0.1.0-next.39
No package change: 0.1.0-next.39 was tagged but not published (a test of its CI run failed); this release carries it. Upgrading from 0.1.0-next.38, read the section below.
From 0.1.0-next.38
Breaking changes
-
The deprecated aliases are gone. Each had its release; rename before you upgrade:
Removed Use hotKeys(the<Edytor>prop and theEdytoroption)hotkeysblockDnd(the<Edytor>prop)blockHandles(blockHandles={false}hides the handles)serverUrl,roomName(createWebsocketSync,prefetch,lastUpdated,documentSnapshot)server,roomattachDocument(this, options),AttachDocumentOptions(edytor/cloudflare)attachRoom(this, options),AttachRoomOptionsmoveBlocks(namespace, move)(edytor/cloudflare)moveBlocksBetweenRooms(namespace, move)A KV namespace itself as history.storekvHistory(namespace)block.suggestText({ value }),block.suggestions,block.acceptSuggestedText()edytor.suggestions.add({ end: block.id }, content),edytor.suggestions.at(block.id).end,suggestion.accept()MigrateOptions.leaseMs,waitMs,pollMs,ownerandwaitForSettled(name, options)’s options (no-ops)nothing: leave them out - A
hotKeysorblockDndprop (or ahotKeysoption tonew Edytor) is ignored, whatever its value: no binding is registered and the handles stay. In development it warns, naming the replacement. createWebsocketSync({ serverUrl, roomName })throws aTypeErrorthat namesserverandroom.- A room whose
history.storeis a bare KV namespace keeps no history: it notes ahistoryrefusal (history.store: not a HistoryStore) at its first use of the history, listing versions answers404and a restore throws. Nothing else fails, so check the room’s refusals after upgrading. TheEDYTOR_HISTORYbinding is unchanged: the room still wraps a KV binding inkvHistoryitself.kvHistorywrites what earlier releases wrote, so their versions list, preview and restore as before.
- A
-
Pre-release stored formats still load (nothing to do). Documents stored by 0.1.0-next.6 (atomic array leaves, the whole-
dataattribute), containers written by 0.1.0-next.22 (no storage format) and alarms armed by 0.1.0-next.23 all load as before. They are all schema generation 4, so they reach this release through the generation cutover, which reads them with this build’s reader: that reader is kept.
From 0.1.0-next.37
Fixed
- Chrome follows the blocks when they move with no edit. Block handles and the other chrome were measured again only on an edit, a scroll or a resize of the editor or the window. A block laid out again without one (a font or a stylesheet that loads late, an equation KaTeX draws after the first render, an editor whose height the page fixes) left every handle beside its block’s old place. The overlay now also measures again when a block’s element changes size. Nothing to change in your code.
- ↑ at the end of a wrapped cell’s first line stays in the table’s column. Where a cell’s first line wraps, the caret at that line’s end is also the next line’s start, and the browser does not say on which line it shows it. The arrow was left to the browser there, which moved the caret to the row’s other cell (the line before it in the page’s order), not the cell above; ↓ at the start of the last line did the same with the next cell. The key now moves the caret to that edge line: the next press leaves the cell. Nothing to change in your code.
From 0.1.0-next.36
Breaking changes
Doc.keepReplacedis per document. Binding the engine no longer sets the engine’s class default:Y.Doc.keepReplacedstaysnull(upstream’s behavior) for every other document of the engine in your app. Each edytor document carries the rule on itself (doc.keepReplaced):createDocument,attachDocument,bindCrdt(Y).createDoc(), the newbindEdytorDoc(Y).newDoc(), and any document a facade binds (create(doc); a rule you set yourself stays).- A document must carry it before it integrates edytor content. A server or a script that built its document with
new Y.Doc()and applied stored updates before binding builds it withcreateDoc()instead (Protocol).
- A document must carry it before it integrates edytor content. A server or a script that built its document with
DocChangeis read-only. Its collections are typedReadonlyMap/ReadonlySet: the report is one object shared by every subscriber of the document (each view over it, its cells included). Code that changed it in place copies it first (new Map(change.added)).- New bundled roles:
table,tableRow,tableCellandequation. They are indefaultSemantics, so the room and headless documents read tables and equations as views with the plugins do. An app that defined its own kind of one of these names with other roles gets aSemanticConflictErroragainstdefaultSemantics: rename the kind, or give the document its ownsemantics. - The
commentmark has a bundled edge.defaultSemanticsgives thecommentmark theexclusiveedge (commentMarks, a new export ofedytor/crdt/edytor). Acommentmark record of your own (the earlier recipe) that declares anotheredgenow conflicts with it when the view mounts (SemanticConflictError): remove itsedge, or use the comments plugin. - The history panel’s count words are functions.
added,removed,changedandmoreEditorswere'{n} added since'-style templates and are now(count) => string, so a language inflects them. Replace a template with a function:added: (count) => \${count} ajoutés depuis``. - A complete label dictionary has new sections. A dictionary of your own typed
Labels(satisfies Labels) adds thecomments,table,mention,historyandequationsections, theeditorsection’striggerMenu,searchingandnoResults. The slash menu’sgroupslabels have two new keys to translate,ColorandInline. See Localization.
New
- Comments (opt-in).
createCommentsPlugin({ client, user, users?, onComment?, card?, labels? })adds Notion’s comment threads: select text, press Comment in the toolbar (or Mod + Shift + M), and the thread shows in a sidebar beside the text (under it on a narrow screen), with replies, Resolve and Re-open. See Comments.- A thread’s text is highlighted while it is open. Its anchor is a
comment:<id>mark (oneaddCommentcommand and undo step), kept through splits and merges,exclusiveat its edges, and not copied. - Threads are kept by a client:
createCommentsClient({ server, room, socket?, params?, fetch? })over the room, orcreateMemoryCommentsClient({ user })in memory (client.as(user)for another user of the same threads). - The room stores threads in two new tables,
threadsandcomments, and the last change’s sequence number inmeta(comments).routeDocumentComments(request, rooms, id, authorize, options?)answersGET(every thread) andPOST(add,reply,resolve,reopen,delete), authorized likerouteDocumentHistory;listComments()andcomment(request, { user, readOnly?, moderator? })are the same over RPC. See Server comments. - The room removes a removed thread’s anchor marks. Override
onComment(change)(or passattachRoom(this, { comments: { onComment, maxLength } })) for notifications;EDYTOR_COMMENTS=off(orcomments: false) keeps none. - A new message type,
messageComments(6), carries a socket’s subscribe and the room’s snapshot and changes. The room sends it only to a socket that subscribed, so the generation is unchanged and older clients are unaffected. The shipped provider subscribes while a listener watches its room (the protocol). - A room of an earlier pre-release closes a socket that subscribes (
1008): upgrade the room before listing the plugin. - New exports:
createCommentsPlugin,commentsController,createCommentsClient,createMemoryCommentsClient,CommentRequestError,commentAnchors, and the typesCommentsPluginOptions,CommentsController,CommentDraft,CommentNotice,CommentUser,PlacedThread,CommentsClient,CommentsClientOptions,MemoryCommentsClient,MemoryCommentsClientOptions,CommentDocument,CommentFeed,CommentResult,CommentChange,CommentRequest,CommentRun,CommentSnapshot,CommentThread,ThreadComment. - From
edytor/cloudflare:routeDocumentComments,CommentOptions,COMMENT_STATUS,MAX_COMMENT_LENGTH,MAX_COMMENTS_PER_THREAD,MAX_THREADS,commentAnchors,decideCommentand the comment types (CommentActor,CommentOutcome,CommentRefusal). - From
edytor/protocol:messageComments,commentsSubscribe,commentsSnapshot,commentsChange,writeCommentsSubscribe,writeCommentsSnapshot,writeCommentsChange,readCommentsMessage,CommentMessage,CommentSnapshot,CommentChange,CommentThread,ThreadComment.
- A thread’s text is highlighted while it is open. Its anchor is a
- Marks. A mark record’s new
copy: falseleaves the mark out of copy and cut;toolbar.runmakes its toolbar button callruninstead of toggling it. - Tables (opt-in).
tablePlugin,createTablePlugin({ rows, columns, columnWidth, minColumnWidth, labels, keywords }),isTablePlugin,TablePluginOptions: Notion’s simple table, atableoftableRows oftableCells, each cell a text island whose lines are line breaks. See Table.- Keys: Tab and Shift+Tab walk the cells (Tab in the last one adds a row; Shift+Tab in the first leaves the caret), ↑/↓ go up and down a column from a cell’s first or last line as it wraps on screen, Enter is a line break in a cell and Backspace at a cell’s start does nothing.
- Hovering a table shows a
+under it (a row) and beside it (a column), a row’s and a column’s grip with their menus (insert, move, delete) and a resize band on each column’s edge. The table’s block menu inserts and deletes rows and columns at the caret’s cell and has Header row and Header column switches. - Undoing a column insert keeps a cell holding another person’s text, in a column shown last. HTML
<table>paste and copy. An empty cell shows no placeholder, whatever the editor’splaceholder. tableBlock(options)(root andedytor/crdt/edytor) builds a table as JSON with ids derived from its value;TableBlockOptionsis its type.
- The
tablerole.BlockRole.tableandBlockDefinition.table: a kind displays only its rows (itsdefaultChild), a row only its cells (the row’sdefaultChild), in the order of the table’sdata.columns({ id, width? }, each cell naming its column indata.column).tableKindsandtableSemanticsare onedytor/crdt/edytor.- A cell of no listed column, a second cell for one, a row showing no cell and a table showing no row do not show; a row showing no cell for a column is padded by the view.
- Table operations.
insertTableRow,deleteTableRows,insertTableColumn,deleteTableColumn,moveTableColumn,moveTableRows,fillTableCell, exported with the table plugin: each takes a document first and prepares one plan itsapplywrites. The document’s readsisTable,isTableRow,isTableCell,tableOf,tableColumns,tableGrid(the listed columns, then any shown unlisted: an undone insert’s, holding someone’s text).- A cell never moves as a block, never merges and never splits (
canPlace,canMerge,splitBlockrefuse it); a row moves only within its table. - A text range with an end in a cell deletes each crossed cell’s covered text and removes no cell; a flow pasted into a cell joins its text.
- Hooks see the view’s table commands under the same names (
BlockOperations).
- A cell never moves as a block, never merges and never splits (
- Kind rows in the block menu.
BlockDefinition.menu(block)returns rows (KindMenuAction:id,label,icon?,checked?,isEnabled?,run) the block menu shows for a block of that kind opened alone, after Color. A row withcheckedis a switch (menuitemcheckbox, the menu stays open); any other row closes the menu after it runs (a caret its action placed stays).BlockMenuActiongainedchecked. - Equations (opt-in).
createEquationPlugin({ katex, macros, labels, keywords })adds Notion’s block equation (equation, void, its TeX indata.expression) and inline equation atom (inlineEquation), drawn by KaTeX. See Equation.- Your app loads KaTeX lazily (
katex: () => import('katex'));katexis an optional peer dependency, and its stylesheet is yours to import. - A click, or Enter on a selected equation, opens its source in an editor under it, the equation the live preview. “Block equation” and “Inline equation” are slash commands;
$$…$$typed in text and Mod+Shift+E make inline equations. - Copy writes MathML with a TeX annotation, and HTML import reads KaTeX’s markup and
<math>back. equationKindsandequationSemanticsare onedytor/crdt/edytor. New root names:createEquationPlugin,EquationPluginOptions,EquationData,KatexLike,KatexLoader.
- Your app loads KaTeX lazily (
- Inline atoms in HTML.
InlineBlockDefinitiontakeshtml(data)(its clipboard HTML; the default is still the emptydata-edytor-inline-blockspan) andparse(element)(HTML import claims an element inside a line as the atom, its contents not read as text). HTML import also offers a kind’s or an atom’sparsehook elements outside the HTML namespace, such as MathML’s<math>. - Dragging selected text moves it. A text range dragged inside the editor used to drop nothing; it now moves to the drop point as one command,
moveText({ from: { start, end }, to, copy }), and one undo step. See Dragging text.- Its content is placed at the drop point as a paste places it, then the range is deleted, both prepared before any write: hooks see the steps of both, and a drop either refuses writes nothing. The moved text is selected after.
- Alt at the drop copies instead, and a drop inside the range changes nothing.
- The drag carries the range as a copy does (the Edytor fragment, HTML and plain text) for a drop elsewhere. Block-handle drags are unchanged; an internal drag with no selected range still drops nothing.
- Colours by name. With the block menu listed, the slash menu offers Notion’s colours once a query names one:
/redlists “Red text” and “Red background” (groupColor, commandscolor.<name>andbackground.<name>), painting the caret’s block and removing/redin one undo step.- The block menu’s search lists them too, after the kinds (
controller.matchingColors;rowsmay now holdBlockMenuColorrows, andrunSelected()paints one). - New
EditorCommand.searchOnly: a command listed only once a query names it.
- The block menu’s search lists them too, after the kinds (
- Block colours in copied HTML. A copy’s
text/htmlnames a block’s colours as Notion’s export does, a class on the block’s element (block-color-red,block-color-red_background), and a paste of HTML reads them back on its text blocks (Notion’stealasgreen). - Opening a page block.
createPagePlugin({ open })is called asopen(pageId, { newTab }):newTabis true for a modified click (Mod, Shift) or a middle click without anhref(with one, those clicks stay the browser’s), so your app can open a new tab as Notion does. Enter over a page block selected alone opens it. Anopenthat takes only the id keeps working. - Localized history panel, mentions and trigger menus.
Labelshas ahistorysection (englishLabels.history;defaultHistoryLabelsis the same object) and<HistoryPanel labels>takesPartialLabels<'history'>.createMentionPlugin({ labels })takes the newmentionsection (menu,searching,noResults; EnglishPeople,Searching…,No results). A trigger that names noname,emptyorsearchingsays the view’s neweditorlabelstriggerMenu,noResultsandsearching(<Edytor labels>), English as before. onDocChange. New<Edytor onDocChange>prop,EdytorOptions.onDocChangeand plugin hook: each commit’s change report (DocChange), with no whole-document export, whereonChangeexports the document every commit. EachonDocChangeandonChangeconsumer (the prop, each plugin) is isolated: one that throws is logged and the others still run.- Handle getters are reactive. A template,
$derivedor$effectthat reads aBlock,TextorInlineBlockgetter (block.type,block.children,block.content,block.parent,block.index,block.isInTree,text.stringContent,atom.type, …) re-runs when a commit changes it, asblock.dataalready did. Read elsewhere, a getter is the same plain read of the document. A template that readedytor.cellsonly to make a handle getter update can read the getter. See Handles. - Presence within a budget. The room relays presence within
EDYTOR_MAX_PRESENCE_FANOUTframes a second over all its sockets (maxPresenceFanoutwithattachRoom, 2,000 by default,DEFAULT_MAX_PRESENCE_FANOUT, a new export ofedytor/cloudflare). See the room’s presence.- Within it nothing changes: each entry goes out at once. Past it, the entries wait per recipient, the newest of each client, and go out together in one frame per recipient at the end of a later message. A departure still goes out at once.
- In the soak’s worst case (50 clients all at 20 Hz) acknowledgements went from p99 16 s to 43 ms.
- The purge drops merged blocks’ attribution. A block merged into another before the purge horizon keeps its structure but loses its own attribution record (who created it, its contributors, its lineage); the block it merged into already holds its contributors.
PurgeReportandmetrics().purgehave a newmergedcount. In documents 50 people edited, the purge gives back 12 to 17 % of the stored size instead of 5 %. See The purge. - Documentation. This changelog lists each release’s breaking changes, new features and fixes, and importing v13 documents had a page of its own. The room’s Load section has the soak re-run with these changes, and what a client’s heap is made of.
Fixed
- A storage outage rebuilds the room once. After a failed append the room rebuilds its document from its rows as before, then, until storage takes an append again (a probe append, rolled back), closes each frame that would write with
1011before applying it, without rebuilding again. Frames that write nothing are served meanwhile. See Storage. - A key right after a click acts at the click. A key the editor handles at keydown (Tab, the arrows’ own moves, Enter’s fallback, a binding) pressed before the browser reported the press’s new caret acted at the previous caret on a busy main thread, most often after a right-click (no release reads the caret again). The key now reads the caret the press left first.
From 0.1.0-next.35
Fixed
- A mention selected with Shift+arrow stays selected in Chromium. An inline atom (a mention) that Shift+←/→ selected could lose its selection, at the next key, to the caret Chromium places at the editor’s start, so the next Shift+arrow extended from the start of the document instead of from the atom. That caret is now the browser’s own, as it already was for a clicked atom. Nothing to change in your code.
From 0.1.0-next.34
Breaking changes
pageandtocare bundled roles. They are void kinds that show no text (pageKinds,tocKinds,pageSemantics,tocSemanticsonedytor/crdt/edytor), indefaultSemantics, so the room and headless documents read them as views with the plugins do. An app that defined its ownpageortockind with other roles gets aSemanticConflictErroragainstdefaultSemantics: rename the kind, or give the document its ownsemantics.- Block menu controller.
flyoutisfalse | 'turn' | 'color'(was a boolean;falsestill closes it, and a truthy check still means a flyout is open),openFlyout(which?)opens Turn into by default, andBlockMenuAction.submenuis'turn' | 'color'(wastrue).- A custom menu that set
flyout = truesets'turn'. - The keyboard’s rows move by one: Color follows Turn into.
- New:
colors,colorable,isCurrentColor(row),paint(row),flyoutRows,runFlyout().
- A custom menu that set
New
- Input rules. A plugin’s new
inputRulesfield (InputRule:{ find, replace(match, ctx) }) replaces text typed at the caret that completesfind. See Input rules and triggers.- A string replaces the match; the matched text’s removal and the replacement are one command and one undo step. A refused or declined rule types the text as typed.
- Rules do not run in a code block’s lines, nor on a paste or a drop.
- The context reads block offsets (
from,to,block,typed,caret(offset),remove(then?)). markdownShortcutsPluginis now two input rules, with the same behavior.
- Triggers. A plugin’s new
triggersfield (Trigger:{ char, items(query), onPick }, pluslabel,key,item,name,empty,searching,enabled) opens a menu at the caret whencharis typed at a text’s start or after whitespace.- The query filters it.
itemsmay answer a promise: the newest query wins, and Enter during a pending search waits for its rows. - ↑/↓/Enter/Escape are its keys, the root names it for screen readers, and
onPickreplaces the trigger and its query in one undo step. - The slash menu is built on the same controller (
TriggerMenuControlleris exported as a type).
- The query filters it.
- Mentions and page links. New opt-in plugins:
createMentionPlugin({ items })(@people, amentionatom{ id, label }) andcreatePageLinkPlugin({ search, href })([[pages, apageLinkatom rendered as a sanitized<a>). See Mention and Page link. The repository’s unexported reference mention plugin (a typed@became an empty atom) is gone. - A caret in block offsets.
edytor.selection.caretis the collapsed caret as{ block, offset }(an inline atom counting 1;nullfor anything else),selection.setCaret({ block, offset })selects one,dispatcher.caret({ block, offset }, ops?)takes one, andblock.addInlineBlock({ offset, block })inserts at a block offset. TheCarettype is exported. The docs no longer use the text segments’ own offsets (state.yStart,text.segStart), which stay as they were. richTextOperations(edytor).setMarkAtRange(mark)accepts any mark name the editor defines, not only the rich text ones (their names are still typed).- New exported types:
InputRule,InputRuleContext,Trigger,TriggerContext,TriggerItemPayload,TextRuleContext,Caret,MentionItem,MentionData,MentionPluginOptions,PageLinkItem,PageLinkData,PageLinkPluginOptions,TriggerMenuController. - Localization. Every word the chrome shows or says comes from a labels dictionary, English by default (Localization). Nothing changes in English.
labelsis a new option ofcreateToolbarPlugin,createSlashMenuPlugin,createBlockMenuPlugin,createBlockHandlesPlugin(and theblockHandlesprop),createImagePlugin,createEmbedPlugin,createBookmarkPlugin,createFilePlugin,createVideoPlugin,createAudioPlugin,createCodePlugin,createFindPlugin,createSuggestionsPlugin,createColumnsPlugin,createPagePlugin,createTocPluginandcreatePageLinkPlugin.<Edytor labels>takes the view’s own words (its announcements, a suggestion’s accessible name).- New exports:
Labels(the dictionary’s type, one section per plugin),PartialLabels<section>(an option’s type: any entries, nested groups included) andenglishLabels. The controllers carry them for custom markup (controller.labels,find.labels). - Group names and colors are keys. A preset’s
group(Basic blocks,Advanced blocks,Media,Layout) is shown through the slash menu’sgroupslabels, aTOOLBAR_COLORSname through the toolbar’scolors, and aBLOCK_COLORSname (defaultfor none) through the block menu’scolors(its Color flyout’s rows arecolorText/colorBackgroundof it). The stored and compared values are unchanged.
createRichTextPlugin({ labels, keywords })builds the rich text plugin in another language:labelsnames its presets, mark buttons and to-do checkbox;keywordsreplaces a preset’s slash keywords by command id (block.heading1).richTextPluginiscreateRichTextPlugin(). Any listed instance replaces the default rich text plugin, as an image or suggestions plugin instance already did. The image, code, media, columns, page and table of contents plugins take the samekeywordsoption (page.new,block.toc); the toggle headings’ areblock.toggle-heading1to3.createRichTextPlaceholder(labels)builds the Notion placeholders in another language;richTextPlaceholderiscreateRichTextPlaceholder().- Block colours. The block menu has a Color row after Turn into: a flyout of Notion’s “Text color” and “Background color” rows, painting the blocks it acts on (a list’s items, never a void or a code block) as one undo step.
- A block stores them in
data.coloranddata.background, by palette name (BLOCK_COLORS), each one property, kept by Turn into. - The core renders a valid name as
data-edytor-coloranddata-edytor-backgroundon every block element (owned attributes) and paints the nine names from the tokens--edytor-color-<name>and--edytor-background-<name>, with Notion’s values as fallbacks. The Notion theme declares the tokens, and a callout given a background shows it in place of its panel (Styling). - New exports:
BLOCK_COLORS,setBlockColor,BlockColorField,BlockMenuColor. - A block that already held a
colororbackgroundpalette name now shows it.
- A block stores them in
- Toggle headings. The rich text plugin has a
toggle-headingkind, Notion’s “Toggle heading 1” to “3” (block.toggle-heading1to3,data.levelas on a heading): adetailswhosesummaryholds theh1–h3, a container like the toggle.- Markdown as Notion:
>at a heading’s start,#,##or###at a toggle’s, so> #is a toggle heading 1. - The slash menu and Turn into list the three after Toggle list, so a search for
heador/heading 2now also lists them (after the headings: Enter still takes the heading);/h1to/h3do not. richTextPlaceholdernames them “Toggle heading N”.
- Markdown as Notion:
KindPreset.markdownFrom. A preset may convert blocks of named kinds by prefixes of their own ({ toggle: ['# '] }); in a block of a named kind they come before every preset’smarkdown, the preset sharing the most data with the block winning (Markdown shortcuts).- Page block (opt-in).
createPagePlugin({ open, title, href, create }),pagePlugin,PagePluginOptions: Notion’s subpage block, a voidpagelinking to another document (data.pageId,data.title, a cache yourtitlelookup refreshes outside the undo history), and withcreatea “Page” command (page.new) that makes a page and opens it (Page). - Table of contents (opt-in).
tocPlugin,createTocPlugin({ headingLevel }),TocPluginOptions,TocHeadingLevel: a voidtocblock listing the headings and toggle headings live, each scrolling to its heading (Table of contents). - Version history panel. New component
HistoryPanel: the room’s versions with their editors and times, a read-only preview of the selected one with the blocks added, removed and changed since highlighted against the page (document), and Restore version and Undo restore. See History panel.- It reads through a
HistoryClient(list,read,restore,undo):createHistoryClient({ server, room, params, fetch })speaks the requestsrouteDocumentHistoryanswers and throwsHistoryRequestErroron a refusal.versionDiff(version, current)is the comparison alone. - New root names:
HistoryPanel,createHistoryClient,HistoryRequestError,versionDiff,defaultHistoryLabelsand the typesHistoryClient,HistoryClientOptions,HistoryVersion,HistoryRestoreResult,HistoryUndoResult,HistoryPanelProps,HistoryPanelLabels,VersionDiff,VersionChange.
- It reads through a
- Load numbers for the room (documentation). The room has a Load section: a 20-minute soak of 50 clients with injected faults (hibernation, eviction, reset, storage outages, failing compactions). Nothing in the package changed.
- It records ack latency (edits made while connected and while disconnected), heap per stored byte measured in workerd, compaction times, convergence and what the stored size is made of.
- It lists what it found: the stored size follows edits (CRDT structure, about 72 bytes an edit, which a purge barely reduces: raise
EDYTOR_MAX_DOCUMENT_BYTESfor busy documents), presence fan-out is quadratic, and the heap peaks before collection after a storage outage. - Last, how to run the multi-hour soak on staging.
Fixed
- Limitations. Limitations now lists what is not built (tables, comments, a version history UI) and what localization leaves to you.
From 0.1.0-next.33
0.1.0-next.33 was tagged but never published to npm (its CI run failed on the room lane’s setup): the next release carries the same package, so there is no package change. Upgrading from 0.1.0-next.32, read the section below.
From 0.1.0-next.32
Breaking changes
- A curated root, and a new
edytor/protocolentry.edytorlists its exports one by one (132 names, down from 268): the component, the handles, the plugin records and bundled plugins, the document factories and class with their errors (SemanticConflictError,DocumentNotReadyError,DocumentDestroyedError,SchemaMismatchError,UndecodableUpdateError,UnsupportedDocError,SyncRefusedError),defaultSemantics,semanticsOf,KindSemantics, the JSON types,OpResult,Plan,Prepared,DocChange, and the sync factories. Every list is in the API report the repository keeps (entry points). What left the root:- To
edytor/crdt/edytor(still there, import it from that entry):bindCrdt,toBlockSpec, the bundled kinds’ tables (richTextSemantics,codeSemantics,imageSemantics,layoutSemantics,layoutKinds,richTextMarks,facadeConfigOf),markName,MarkEdge,DocumentOptions,DocumentSemanticsConfig,DEFAULT_READINESS_BOUND,DEFAULT_HISTORY_LIMIT,EdytorDocDisposedError,Awarenessand its types,EdytorSyncCleanup,ProviderStack,PrefetchOptions,PrefetchResult,LastUpdatedOptions, the attribution types, the migration types andisLegacyDoc,Crdtand the engine typings (YDoc,YUndoManager,EngineApi, …). - Also to
edytor/crdt/edytor, the facade vocabulary:EdytorDoc,BlockSpec,Destination,ProjectedDoc,ProjectedBlock,DocBlock,DocAnchor,DocPosition,RangeView,FlowView,BlockRole,BlockId,ContentItem,InlineSpec,ContentRun,DataPatch,DataTarget,OrderPolicy,AnchorAffinity,SerializableContent. - To
edytor/protocol(and offedytor/crdt/edytortoo): the frame contract (frame,GENERATION,generationWord,PROTOCOL_VERSION,SCHEMA_VERSION,META_KEY,readProtocolVersion,GENERATION_RECORD,STORED_GENERATION_RECORD,STORAGE_FORMAT,PREVIOUS_SCHEMA,isPreviousGenerationRecord,GenerationMismatchError), the message types and their writers (messageSync…messageChunk,messageYjsSyncStep1/2,messageYjsUpdate,messagePermissionDenied,messageReadOnly,writePermissionDenied,writeReadOnly),CLOSE, and the chunk codec (chunkFrame,createChunkReader,ChunkLimitError,MAX_FRAME_BYTES). - Also to
edytor/protocol: the awareness codec (readAwarenessEntries,writeAwarenessEntries,applyAwarenessUpdate,encodeAwarenessUpdate,modifyAwarenessUpdate), the lib0 helpers (createDecoder,readVarUint,readVarUint8Array,writeVarUint8Array,Decoder,Encoder), the admission gates (assertAdmission,inspectAdmission,assertSchema,assertUsableDoc,checkSchema,isInitialized,registryEmpty,schemaVersionand their types), and the raw provider classesIndexeddbPersistenceandWebsocketProviderwith their option and event types, andstoreState.edytor/protocolalso exportsbindCrdt. - No longer public:
PresenceWriter(a view’sedytor.presence, still typed),isSuggestionsPlugin,oversizedInlineImage(storableImageSrcanswersnullfor what it flagged).
- To
- Plumbing is out of the declarations. Members of the editor instance, the selection and the handles that only the editor’s own layers call are marked
@internaland stripped from the published.d.ts. They still exist at run time; nothing about them is supported.- On the instance:
projector,surface,pin,composition,attempts,history,undoManager,crdt,plugins,docData,valueRevision,sync,placeholderAt,textAt,segmentOf,deltasOf,atomAt,insertFlow,attach,destroyed,ownsDocument,presenceKey,transaction,nodeToText,nodeToInlineBlock, the event handlers (onBeforeInput,onInput,onCopy,onCut,onPaste,onCompositionStart,onCompositionEnd) and the gesture bookkeeping (intentSerial,markUserGesture,userInput,isHandlingUserInput,suppressCaretScrollDepth,expectInternalFocus,consumeInternalFocus,lastUserGestureOutsideEditor,stabilizeCompositionSelection). Undo and redo arehistoryUndo()/historyRedo();isComposingstays. - On the selection: the DOM and pointer handlers (
onSelectionChange,onSelectStart,applySelectionSnapshot,mint,init,destroy,display,observed, the pointer and triple-click handlers, the node lookups) and its display bookkeeping (epoch,request,requestSerial,cause,scrollOnDisplay,placedOver, …). - On
Block,TextandInlineBlock:attach, andBlock.firstEditableText/lastEditableText.
- On the instance:
edytor.hotKeysis gone. The instance field holding the view’s keymap is now the internalkeymap, soedytor.hotKeysisundefinedat run time andedytor.hotKeys.run(chord)throws. Thehotkeysoption and prop keephotKeysas an alias (below); the instance field does not. Bind keys through the prop or a plugin’shotkeys.hotkeys, nothotKeys. The<Edytor>prop (and theEdytoroption) ishotkeys, as a plugin’s field is.hotKeysstill works as a deprecated alias for one release.preventrecords and returns. In every hook and key binding,prevent()andprevent(cb)record the veto and return: the code after it in your hook now runs (it used to throw), soreturnafter it where nothing else should happen. The first call in a hook decides. Atry/catcharound it no longer swallows the veto. A hook that throws aPreventionErroritself still vetoes;PreventionError,isPrevention(error)and thePreventtype are exported fromedytor(the prevent function).onAfterOperationnarrows. Its payload isAfterOperationPayload(exported), aChangePayloadwithoutpreventper operation, sochange.operation === 'insertText'narrowschange.payloadandchange.text. The hook is no longer generic: a hook typed<C extends …>(change: C)becomes(change: AfterOperationPayload).- One result channel.
edytor.dispatcher.lastis aCommandResult(exported):{ operation, status, value? }, recorded afteronAfterOperation.valueis what a handle mutator returned (block.insertBlockAfter‘s block,undefinedwhen refused; when a plugin’sprevent(cb)runs the same operation in its place, the replacement’s result and value). The mutators’ types name their payload only (the plan parameter the dispatcher passes was never the caller’s). - The raw path is
edytor.document.facade.edytor.facade(the view’s lens) is internal; read and write the document directly throughedytor.document.facade, which skips hooks, normalization, the undo policy andreadonly. While the document is empty, the view’s virtual paragraph isedytor.root.children[0](edytor.facade.virtual()is gone from the declarations).facade.insertBlock/insertBlocks(and theirprepareforms) take aJSONBlocktoo ({ type, content: [{ text }] }, ids kept, minted where missing), sotoBlockSpecis only needed to mint fresh ids. - Room names. In
edytor/cloudflare,attachDocument(this, options)isattachRoom(this, options)(options typeAttachRoomOptions) and the cross-roommoveBlocks(namespace, move)ismoveBlocksBetweenRooms(namespace, move), so neither shares a name with the client’sattachDocumentoredytor.moveBlocks. The old names stay as deprecated aliases for one release.attachRoomon something that is not a Durable Object throwsattachRoom(this): …. valueandonChangeare one type.onChange(the prop, theEdytoroption and a plugin’s hook) receives aJSONDoc, andedytor.valueis aJSONDoc: the type thevalueprop takes, so a saved value opens as it is. The object is unchanged at run time (it still carriestype: 'root'); code that typed itJSONBlocktypes itJSONDoc.- Snippet overrides must name a kind. A
<type>Block,<type>Markor<type>InlineBlocksnippet whose type no plugin registers used to register a phantom kind; it now overrides nothing and warns in development. - A readonly view connects to its room.
<Edytor readonly>givenroomandserver(orsync) now attaches it, as an editable view does: it loads the room’s content and shows every collaborator’s edit (a live viewer).- Switching
readonlykeeps that connection, so a view created readonly that becomes editable saves its edits. - It also waits for its room like an editable view: it no longer shows
valueat once, and its server render shows onlysnapshot;valueseeds a room that has nothing yet. - A room id no dial can carry is reported through
onSyncRefused(4400) by a readonly view too. - Action. A readonly page that passed
roomorserverbut wanted the staticvalueshould drop them; one that created the document and attached the sync itself to get a live viewer can passroomandserverinstead.
- Switching
- A headless document holds the bundled roles.
createDocumentandloadDocumentwithoutsemanticsnow adoptdefaultSemantics, as the room does: a merge into a divider, a split of an image or a code line moved out of its code block is refused there too. Passsemantics: {}for the old behaviour (no roles).- A view whose plugins redefine a bundled kind (an
imagethat is not void, acodethat is no island) now throwsSemanticConflictErroron a document you created withoutsemantics: pass that view’s rules, or{}. attachDocumentand a view’s own document are unchanged.
- A view whose plugins redefine a bundled kind (an
semanticsOfreads only structural fields. It reads plugin kind records: only their structural fields (void,island,lines,layout,atomic,rendersContent,defaultChild) become roles, where any other field (a snippet, an element) used to land inroles, and a bare snippet is a plain kind.- Room quotas fit the room’s memory. A room holds its live document in an isolate of 128 MB, where it takes 18 to 46 times its stored size, so the old default document quota (64 MiB) could only be reached by crashing the room.
- The defaults are now
EDYTOR_MAX_DOCUMENT_BYTES2 MiB (was 64 MiB) andEDYTOR_MAX_INBOUND_FRAME_BYTES4 MiB (was 64 MiB).DEFAULT_MAX_DOCUMENT_BYTESandDEFAULT_MAX_INBOUND_FRAME_BYTESchange with them. - A room whose document is already past 2 MiB keeps it and serves it, but refuses a write that adds content (
4413,quota: document; a delete still applies). SetEDYTOR_MAX_DOCUMENT_BYTES(and the frame quota with it) to what your documents need and your memory allows, measured in quotas. - Inline images count at their size: without an
upload, the image plugin stores each one in the document (up to 1 MiB ofdata:URL), so two or three reach the new default. Action for documents with images: givecreateImagePluginanupload, or raise the document and frame quotas by the images’ size (see quotas).
- The defaults are now
- The room verifies attribution (security). A client could bind its edits to another user or rewrite another user’s name and color. The room now checks the attribution root against the socket’s verified user. See attribution trust.
- A
c/<clientID>binding written under another client id, or of another user’s client id, and au/<id>profile of another user are removed from the update (the rest applies), and a delete of one is dropped (a relayed id’s binding to another user too, until the author’s dial claims the id). - A binding of the sender’s own client id to another actor, or of an id a writer claims, is rewritten by the room to the user; a binding that names the client id’s registered owner stands, whoever wrote it (the room’s own rewrite, relayed by a replica).
- Each is logged with the new refusal reason
forged({ user, keys }). Relayed presence states that name anactorcarry the verified user asactor.id. - Action: make the document’s
actor.idtheuserIdyourauthorizereturns. With another actor id, the room rebinds your client ids to the user id and refuses the client’s own profile.
- A
- Presence quotas. The room ignores a presence entry whose state, as JSON, is over 16 KiB (
EDYTOR_MAX_PRESENCE_BYTES,maxPresenceBytes,DEFAULT_MAX_PRESENCE_BYTES). A presence state carrying more than a caret, a name and a color (a thumbnail, say) is no longer relayed: keep it small. See presence.- It also limits presence messages to 50 a second per socket on a bucket of their own (
EDYTOR_MAX_PRESENCE_PER_SECOND,maxPresencePerSecond,DEFAULT_MAX_PRESENCE_PER_SECOND; a ten-second burst): past it, queries are dropped and entries coalesced, the newest relayed once the rate allows. - Neither closes the socket; both are logged with the new refusal reason
presence, a burst past the rate as one entry (refusalCounts.presencecounts every message).
- It also limits presence messages to 50 a second per socket on a bucket of their own (
- The room’s alarm is always installed.
attachDocumentnow always installsalarm: a class that defines its own must calldocument.alarm(), as before. defaultSemanticsholds the media kinds.embed,bookmark,file,videoandaudioare void indefaultSemantics(andmediaSemantics,mediaKinds), so the room and headless documents treat them as views with the plugins do. If your own plugins define one of those kind names with other roles (a non-voidvideo), give your kind another name, or pass your semantics to the room and documents instead ofdefaultSemantics.- Accessibility: roles, names and colors moved. See Accessibility.
- The slash menu’s rows are now a
listbox(.slash-items, with an id) ofgroups, one per section;.slash-menuitself is presentational. - The block menu’s
role="menu"and its “Block actions” name moved from[data-edytor-block-menu]to its rows’ container (.block-menu-rows), and its rows are no longer Tab stops. A+menu’s field is acombobox. Tests that read these roles from the old elements need the new ones. - Handles are named after the kind’s preset label: the grip “Heading 1 block: drag to move, click for actions” (was “Move heading block”), the
+“Add a block below Heading 1 (Alt: above)”. - The list kinds’
li,ulandolelements haverole="none"(a list’s items are sibling blocks, never one list’s children). A selector onroleor a test reading list roles changes. - Grays the chrome uses for text are
#73726e(was#7d7a75and#a19e99),--notion-text-secondaryincluded, and the code block’s syntax colors are darkened to a 4.5:1 contrast (WCAG AA).
- The slash menu’s rows are now a
- Autolink. With the rich text plugin, a URL typed before a space becomes a link when the space is typed, and a URL pasted at a caret is inserted as a link; each link is an undo step of its own, so undo gives the plain text back (links).
- A test that types a URL followed by a space now finds a
linkmark on it. - Mod+click on a link opens it in a new tab.
richTextOperationsaddslinkText(text, start, end, href)andunlinkText(text, start, end).
- A test that types a URL followed by a space now finds a
- Image: pasted and dropped files.
createImagePlugin({ upload })now claims a paste or a drop that carries image files: each becomes an image block at once (one undo step), shown uploading, and the URLuploadanswers fills itssrcoutside the history (dispatcher.outside), so undoing the paste removes the image whole (pasting and dropping files).- A paste whose HTML shows text is still imported as HTML.
- If your own
onPastehook uploaded pasted images, list it before the image plugin (yours is first by default) or drop it.
New
- One source for roles.
mergeSemantics(...configs)merges configs field by field (roles,rendersContent,defaultChild,marks,defaultType) and throwsSemanticConflictErroron a kind two configs declare differently:mergeSemantics(defaultSemantics, semanticsOf(myKinds))replaces the field-by-field spread. The bundled kind tablesrichTextKinds,codeKindsandimageKindsare exported besidelayoutKindsandrichTextMarks.SemanticConflictErroris still exported from the same entries. - Roles check in development. In development builds a document publishes a digest of its roles in its presence (the
semanticsfield,semanticsDigest), and the room logs{ edytor: 'semantics', user, kinds }naming the kinds it reads otherwise (semanticsMismatch), once per digest;RoomLogEntryhas that variant. Nothing is refused, and production builds publish nothing. allowedOrigins.routeDocumentSocketandrouteDocumentHistorytake a lastoptionsargument (RouteDocumentOptions, exported):allowedOrigins, a list of page origins or a predicate, refuses a request from anotherOriginbeforeauthorize(4403origin not allowedfor a dial,403for HTTP). Set it whenauthorizereads a cookie. See origins and cookies.- Revoking access and expiring credentials. See revoking access.
- New RPC methods on the room (and
AttachedDocument):closeUser(userId, code?, reason?)closes every socket of a user (4403access revokedby default), andsetAccess(userId, 'write' | 'read' | 'none')downgrades write sockets in place (the read-only notice; writes denied), closes read-only ones1012(access changed, the newCLOSE.accessChanged, redialed) to upgrade them, or closes them all. closeUserthrows aRangeErrorfor a close code a socket cannot be closed with (only1000,1011,1012and3000to4999can) or a reason over 123 UTF-8 bytes, before touching any socket.authorizemay returnexpiresAt(ms since the epoch): the router closes a dial past it4401, and the room closes the socket4401(expired) at its first message past it or on its alarm, so the provider redials with freshparams.- The identity reaches the room in the new
X-Edytor-Expiresheader (IDENTITY_HEADERS.expires);SocketIdentitygainsexpiresAt; refusals gain theaccessentry.
- New RPC methods on the room (and
- Chunked frames are bounded room-wide. New
EDYTOR_MAX_BUFFERED_BYTES(maxBufferedBytes,DEFAULT_MAX_BUFFERED_BYTES; twice the frame quota by default): the chunk sequences in flight on all sockets share it, and one that would pass it closes its socket1011(room busy), redialed. See catch-up.- A sequence is assembled into one buffer of its announced size, a read-only socket’s sequences are denied (
read-only) and never buffered, and a sequence’s start counts against the update rate. createChunkReader(maxBytes?, admit?)takes theadmithook and exposesbuffered;metrics()reportsbuffered: { sequences, bytes }.
- A sequence is assembled into one buffer of its announced size, a read-only socket’s sequences are denied (
- Index work counters. The debugging surface
facade.runsView.debugalso counts, read-only, the index’s fold passes (folds), the changed(type, key)pairs they folded (foldedPairs) and the structs the reads inside a transaction folded (foldedStructs);debug.reset()clears them with the others. Nothing else changes. The test suite uses them to state “stays fast” as operation counts instead of timings. - Long pages:
--edytor-block-visibilitystays opt-in. Profiled again at 5,000 and 10,000 blocks: it shortens the first layout but not the first paint, slows scroll frames two to four times, leaves typing unchanged and makes Enter, moves and pastes about a quarter slower; the numbers are under long pages. Nothing changes. - Toolbar: Mod+K and the link card. Mod+K opens the toolbar’s link panel (keyboard); the link field takes the focus when the panel opens, and Enter or Escape in it gives the editor its focus back. An app binding Mod+K itself keeps it: consumer bindings come first.
- Hovering a link shows a card with Open, Edit and Remove (link card), mounted in the overlay as
data-edytor-link-card-host;createToolbarPlugin({ linkCard: false })shows none. ToolbarControlleraddsopenLinkPanel(),closePanel(focus?),takeFieldFocus()andhovered.
- Hovering a link shows a card with Open, Edit and Remove (link card), mounted in the overlay as
- Code languages. A code block’s language is its
data.language, picked in its header (a<select data-edytor-code-language>where a<span>was) and named by its label; a block without one is JavaScript, as before (languages).- Lines are highlighted with their language’s grammar, loaded the first time one renders: JSX ships with the plugin, the others are chunks of their own.
- New exports:
createCodePlugin({ languages, defaultLanguage }),CODE_LANGUAGES,loadCodeLanguage, and the typesCodeLanguageandCodePluginOptions. - A theme rule for
[data-edytor-code-language]now styles aselectin editable views.
- Image: alt text, width and alignment. The image block reads
data.alt(itsalt,""without one),data.width(CSS px) anddata.align('left','center'by default,'right'). Hovering an image, or selecting its block, shows resize handles and a toolbar (alignment, alt text) in the overlay (resize, alignment and alt text).- The wrapper
[data-edytor-image]is now a flex row carryingdata-align, and the copied HTML carries thealt, awidthand the figure’sdata-align. - New exports:
MIN_IMAGE_WIDTHand the typesImageDataandImageAlign.
- The wrapper
- HTML import: a bare
<img>. Animgwith an acceptedsrcis imported as an image block (with itsaltandwidth), not only one inside afigure. An image inside a line (<p>a<img>b</p>, or wrapped in aspanas Google Docs writes it) ends the line there:a, the image, thenb(HTML import). Before, such an image was dropped. edytor.dispatcher.outside(body)runs commands outside the undo history (admitted, shown to hooks, recorded indispatcher.last, but they start and join no step), for a write that completes a step already taken (History). It throws when called inside another transaction.- Embeds and files. Five new opt-in plugins, void kinds like the image with an editable caption. Each adds a slash-menu row under
Media, andrichTextPlaceholdergives their captions “Write a caption…”.embedPlugin/createEmbedPlugin({ providers }): a YouTube, Vimeo, Loom, Figma, CodePen or Spotify player in a sandboxediframe, from theEMBED_PROVIDERSallowlist (embedSourceOf,EMBED_SANDBOX,EMBED_ALLOW,EmbedProvider).bookmarkPlugin/createBookmarkPlugin({ unfurl })(BookmarkPreview).filePlugin/createFilePlugin({ upload }),videoPlugin/createVideoPlugin({ upload })andaudioPlugin/createAudioPlugin({ upload })(MediaPluginOptions), withsafeWebUrlandsafeMediaSrc.
- Pasting a link on an empty line. With the embed or bookmark plugin listed, pasting one
http(s)URL on a line that holds nothing writes it as a link and opens a menu offering Link (kept), Embed and Bookmark (clipboard). Without those plugins the paste is unchanged. - Accessibility. See Accessibility.
- While a menu or the toolbar is open, the root carries
aria-controls,aria-haspopup,aria-activedescendant(the/menu’s highlighted row) andaria-keyshortcuts(Alt+F10for the toolbar); a+or grip that opened a menu hasaria-expanded="true". New:edytor.popups(what the root names) andedytor.announcer(say(message)). SlashMenuItemhas anidto set on a custom row;BlockHandleSnippetPayloadhaslabel, the block’s kind as people read it.- Alt+F10 moves the focus into the selection toolbar, which is one tab stop walked by the arrows; Escape returns.
- A column resize band is a focusable
separatorthe arrows resize (one undo step per press); it is no longeraria-hidden, and the bands of the layout holding the caret are rendered without a hover. - Block moves and deletes made in a view are announced in a polite live region,
[data-edytor-live], in the overlay.
- While a menu or the toolbar is open, the root carries
- Right-to-left text. A block element carries
dir="rtl"ordir="ltr"from its own text’s first strong character, and none when it holds none (it keeps its parent’s): a Hebrew or Arabic line in a left-to-right page is right to left, its arrows included. The attribute is owned by the core (a foreign change is healed). A theme rule keyed on[dir]now matches blocks. - Find and replace. New opt-in plugin,
findPlugin(createFindPlugin({ bar })): Mod + F opens a find and replace bar that searches the whole document (a closed toggle’s body included, opened when a match there becomes current), highlights the matches in the overlay, and replaces one or all as one command,replaceMatches, and one undo step. See Find and replace.findController(edytor)drives it from code andfindMatches(edytor, query)is the search alone.- Without the plugin, Mod + F is unchanged.
- New pages. Platform support lists the browsers, versions, devices and runtimes the lanes run, the oldest browsers the code needs (Chrome and Edge 111, Firefox 119, Safari 16.4: the code uses
String.prototype.toWellFormedand a regular expression with lookbehind) and the status of real phones and IMEs. Room internals lists the room’s five alarm tasks (forwardincluded, which the history page left out) and every storage table.
Fixed
- Mod + F in a readonly view is no longer blocked: the browser’s find opens, as for Mod + C and Mod + A.
- A readonly view never rewinds.
historyUndo()/historyRedo()stay the view’s history API (they already refused on a readonly view); the view’s own history object refuses too now, so no path the view holds replays a step while it is readonly. <Edytor>keeps its ARIA attributes. It forwardsaria-label,aria-labelledby,aria-describedbyandidto its root textbox. They used to be taken for snippets and dropped.- Declarations without ticket codes. The published JSDoc no longer cites internal review codes, and the
voidandislandfields ofBlockDefinitiondescribe what the roles do. - A whole array assignment takes time linear in the array’s length.
block.data.tasks = next(andsetData, a rootpatchData) compared every old item with every new one, so a 6,000-item array took 0.7 s and a 20,000-item one 10.6 s. The same reassignments now take 0.17 s and 0.6 s, and write only what differs (properties).order(sort,reverse) uses the same rule.- It keeps the items equal at the start and the end, then the longest run between them, exactly as before whenever the old values are distinct or few repeat.
- Past 262,144 pairs of equal values (thousands of repeated flags), the items between the kept start and end pair by position.
- A failed upload from the Upload button now shows
data-edytor-image-error="upload"(“The upload failed…”) instead of"invalid". - A dropped file over a block selection is offered to the plugins at the drop point; before, a plugin placing it at the selection replaced the selected blocks.
- HTML import: emoji drawn as images stay text. An
imgwhosealtis emoji only, whose class names an emoji or that hasdata-emoji, or whosewidthandheightare 32 px or less, is imported as itsalttext in the line, so a paste from X, Gmail, Slack or WordPress keeps each paragraph whole (and an email’s tracking pixel adds nothing). Other images inside a line still end it (HTML import). - HTML import of voids. A void kind with a
parsehook (the image and the media kinds) is found by its hook only, never by its tag alone: a pastedfigurewith noimgis no longer an empty image block, its caption pastes as text. A claimed void takes only itsfigcaption’s text as its caption.iframe,videoandaudioare imported when the embed, video or audio plugin claims them, and dropped otherwise, as before. - Mount editable editors in the browser (documentation). The quick start and installation pages now mount the editable editor after hydration, or turn SSR off for the route, as SvelteKit always advised: server-rendering an editable
<Edytor>is not tested. If you copied the earlier quick start into a server-rendered route, wrap the editor in theonMountguard. Nothing in the package changed. - Corrections (documentation). The version history is kept in the store you choose (KV, R2, the room’s own storage or yours), not only KV, as the limitations and room pages said;
tablePrefixprefixes every room table, not two.
From 0.1.0-next.31
Fixed
- Security fix: links. A link whose
hrefstarted with an ASCII control character or a space beforejavascript:(for example\u0001javascript:…) passedsanitizeLinkHrefas a relative link, and browsers, which strip those characters, would run it when clicked. Upgrade.- The sanitizer now reads an
hrefas the browser’s URL parser does: it strips control characters and spaces at both ends and tabs and newlines anywhere, resolves it, and keeps it only when its scheme ishttp:,https:,mailto:ortel:(a relative link resolves to none of its own). - Links already stored with such an
hrefrender without one.
- The sanitizer now reads an
- License. The package now carries its MIT license (
LICENSE, and"license": "MIT"inpackage.json).
From 0.1.0-next.30
New
- Pasting a link over selected text links it. With the rich text plugin, a paste whose plain text is one URL (
http:,https:ormailto:) over a text range outside a code block now sets thelinkmark on the selected text instead of replacing it, as in Notion (pasting a link). Other pastes are unchanged. A plugin of yours that claims such pastes in its ownonPastestill wins when it is listed before the rich text plugin (the default plugins come after yours).
From 0.1.0-next.29
Breaking changes
- No count badge beside the drop indicator. Dragging several blocks now shows the drop indicator as the bar alone, like the preview since 0.1.0-next.29: no
[data-edytor-drag-count]badge is rendered anywhere. The count stays asdata-counton[data-edytor-drop-indicator]and on[data-edytor-drag-preview]. A theme rule that styled the badge no longer matches anything.
From 0.1.0-next.28
Breaking changes
- The drag preview has no count badge. Dragging several blocks shows their copies only (
data-countstays on[data-edytor-drag-preview]). A theme rule that styled the badge inside the preview no longer matches anything.
From 0.1.0-next.27
New
- Selecting across columns selects blocks from more gestures. A mouse selection with one end in a column and the other outside that column now becomes a block selection of the blocks between, in reading order, as in Notion. Nothing to change in your code.
- It applies to a drag from one column into another (as before), a drag that starts above or below a layout and enters a column, a drag that starts in a column and leaves the layout, and a Shift+click in another column or outside the layout. Earlier these last three stayed one text range in reading order.
- A range that runs over a whole layout from above it to below it, and Shift+arrows, stay text ranges.
From 0.1.0-next.26
Fixed
- Clicking a mention keeps it selected in Chromium. In every 0.1.0 pre-release so far, a click on an inline atom (a mention) selected it and then, a frame later, lost it to the caret Chromium places at the editor’s start for that click, so typing or Backspace right after the click could act at the start of the document instead of on the mention. That caret is now the browser’s own and never replaces the atom selection. Nothing to change in your code.
From 0.1.0-next.25
Breaking changes
- A bare KV namespace as the history store is deprecated. Passing the namespace itself (
store: env.HISTORY, or theEDYTOR_HISTORYbinding) still works, wrapped inkvHistory: writekvHistory(env.HISTORY). Versions stored by earlier releases list, preview and restore as they are. - An id holding the character U+0000 is now refused when a block is created.
New
- The history store is yours to choose.
history.storeis now aHistoryStore(see a store of your own). Nothing to change for KV.roomHistory()keeps the versions in the room’s own Durable Object storage (no binding; set the variableEDYTOR_HISTORYto"room"withDocumentRoom),kvHistory(namespace)in KV as before,r2History(bucket)in R2 (bind it asEDYTOR_HISTORY), or any object withmaxValueBytes,put,get,listanddelete.- The room owns retention: nothing past a version’s
expiresAtis listed or read, and for a store without a TTL of its own its alarm deletes each version when it expires (a fourth alarm task,retention).HistoryEntrygainsexpiresAt.
- Per-block locks are built in.
lockedBlocks({ key, subtree, bypass })is a ready-madevalidatehook (the room’slocksoption,DocumentRoom.locks(), or theEDYTOR_LOCKSvariable): a block whose data names a user is that user’s alone, and withsubtreeso is everything under it (per-block locks). A room that overrodevalidatefor locks can keep it, or switch. - Moving blocks between documents.
moveBlocks(namespace, { from, to, ids, dest })moves blocks from one room to another without losing a concurrent edit: the destination writes them, the source deletes them only once the destination acknowledged, and edits that reach the source late follow the blocks (moving blocks between documents). The room has new methods (exportBlocks,importBlocks,commitMove,abortMove,lateEdits,ackLateEdits,applyLateEdits), two new tables (moves,late) and a fifth alarm task,forward. - First paint from a snapshot.
<Edytor snapshot={json}>shows the document read-only until the view’s own document is ready, then the live view: a first visit to a room no longer waits for the room to paint.documentSnapshot({ server, room, params })fetches it (GET <room>?snapshot, authorized byrouteDocumentSocketlike?lastUpdated). See first paint from a snapshot. - Long pages, opt-in. The Notion theme reads
--edytor-block-visibility: set it toautoforcontent-visibility: autoon top-level blocks (faster first layout, slower scrolling; long pages). Off by default: nothing changes unless you set it.
Fixed
- Two creations of one block id keep both texts. When two people create a block with the same id at once (your app chose the id), the copy of the larger client id still wins (its type, data and place), but the other copy’s text now shows at the end of the winner’s instead of being lost, and both can edit it (concurrent editing). Two different templates seeding one id still keep one version. This needs every client on this release: an older client deletes the losing copy’s text when it sees the race, and that delete reaches everyone.
- A merge follows a concurrent split. Backspace joining “world” into “hello” while someone presses Enter after “he” now gives “he” and “lloworld” (both serial orders’ result) instead of “heworld” and “llo”. Merges are written with an anchor (the end of the block they join), which a client of an earlier release ignores: until every client upgrades, a client of 0.1.0-next.25 shows such a race’s merged text after the first piece, as before. Nothing to change in your code.
From 0.1.0-next.24
This release is schema generation 5 (wire word 14005). It changes what a document stores, so a document, a browser store and a peer of generation 4 (0.1.0-next.24 and earlier pre-releases back to generation 4) never exchange bytes with this one: each converts once, through its JSON.
Breaking changes
- Rooms. A room of this release converts a container of generation 4 the first time it loads it: its document is read as JSON and seeded as generation 5’s, and replaces the container (logged
{ "edytor": "convert", … }).- Blocks keep their ids, kinds, data, content and marks; undo history, attribution and edits a client never sent before the cutover do not cross.
- History versions written before it still read and restore.
onLoadreturning JSON works as before, andreset()still replaces a container of any other generation.
- Servers of your own. A SyncStep2 is v2 on the wire; updates stay v1 (the protocol). A server of your own must convert a SyncStep2 before applying it (
sync.step2Update(payload)) and write it withsync.writeSyncStep2. - Browser stores. This release stores documents in
edytor-v14-g5:<name>; the generation-4 databaseedytor-v14:<name>is left as it was.- A document stored only in the browser (
createIndexeddbSync) converts its generation-4 store into the new one the first time it opens (IndexeddbPersistenceoptionconvertPrevious). - A document a room keeps (
createWebsocketSync,<Edytor server room>) starts its new store from the room, which converted it: an edit made offline on 0.1.0-next.24 that never reached the room stays only in the old database.
- A document stored only in the browser (
- Clients of the other generation. A 0.1.0-next.24 client dialing a room of this release is closed
1008(refused: generation) at its first frame: its provider stops dialing and the app sees it throughonSyncRefused(<Edytor onSyncRefused>,document.syncRefusal). A client of this release dialing an older room is refused the same way. Neither writes anything to the other. - Deploy order.
- Ask users to let open documents sync (or rely on the room’s
onSavemirror being current): an edit made offline on the old release is not converted. - Deploy the room Worker. Each room converts its container the first time it wakes; old clients still open are refused (
1008) and should reload. ShowonSyncRefusedas “a new version is available, reload”. - Deploy the app (the site). A reloaded tab runs this release, opens its new browser store and syncs from the room.
- Roll back only together with the data: a 0.1.0-next.24 room refuses a converted container (
refused: container), and its clients read their oldedytor-v14:stores, which miss what was written since.
- Ask users to let open documents sync (or rely on the room’s
New
- Marks are paired operations. A mark set over a range is one operation with a start and an end that closes only its own start, and a timestamp later than every mark its writer saw. See how concurrent marks merge.
- Overlapping marks of one value union (two collaborators bolding overlapping words get the union), a later mark wins only where it covers, and nothing clears the end of another mark any more.
- The mark record’s
edgealso decides where text a collaborator types at a mark’s edge lands while the mark is being set: a link set while someone types right after it no longer swallows their text, on every replica.
- Ranks are shorter (variable-length digits, a client tie only where it is needed): about half as long after many Enters in one place.
- Text delete records fold: a backspace run writes one record instead of one per key, so a long-edited document stores and wakes several times faster (on the
automerge-papertrace: 274 KB instead of 1.34 MB stored, 23 ms instead of 110 ms to wake a room). - API.
DocumentSemanticsConfig.marks({ [mark]: { edge } }) gives a document without a view its marks’ edges;defaultSemanticsandrichTextSemanticscarryrichTextMarks(the link’s). A mark keyname:<id>reads thenamemark record, so a comment per thread (comment:<id>) is a mark of its own.- New exports:
richTextMarks,markName,MarkEdge,facadeConfigOf(a facade configuration from semantics),PREVIOUS_SCHEMA,isPreviousGenerationRecord,bindCrdt(Y).generations(previousJSON,previousJSONWith,seedOf) andbindCrdt(Y).sync.step2Update.
- New exports:
From 0.1.0-next.23
Breaking changes
- Deleted content is purged after 30 days. Every room now purges content deleted more than 30 days ago (the history’s retention when it has one;
EDYTOR_PURGE_AFTER_DAYSorpurgeAfterDaysto change it,off/falseto keep everything).- Deleted blocks, deleted text and undone creations leave the room’s storage and every client, which apply the purge as an edit.
- An undo of a step older than that restores nothing, and a device offline longer keeps its edits to what still exists and loses those to purged content. No stale-device close code: it reconnects as any device.
- To purge, the room needs its alarm: it now sets one a day while a document changes, so a class that defines its own
alarm()must calldocument.alarm()(orsuper.alarm()), as it already had to withonSave.attachDocumentinstallsalarmunlessonSave,historyand the purge are all absent.
- One alarm, several tasks. The room’s alarm runs
onSave, the history’s slots and the purge’s daily tick, the earliest due first; each task’s due time is stored in the meta table (an alarm armed by 0.1.0-next.23 counts as a due save). A test that ran the alarm to see that nothing is left due now finds the purge’s tick.
New
- Version history in KV. Bind a KV namespace as
EDYTOR_HISTORY(or passhistory: { store }toattachDocument, or overridehistory()in aDocumentRoomsubclass) and the room writes two versions of its document a day (local noon and midnight inEDYTOR_HISTORY_TIME_ZONE, UTC by default), only when it changed, kept 30 days. Without a binding nothing changes.listHistory(),readHistory(key),restoreHistory(key, { user })andundoRestore()(also over RPC), androuteDocumentHistoryover HTTP, list, preview, restore and undo a restore.- A restore is an ordinary edit every client receives, keeping block ids. See History and purge.
- Three more tables (
epochs,editors,restore;edytor_prefixed withattachDocument).reset()drops them with the others.
From 0.1.0-next.22
Breaking changes
- Downgrade only with the data. 0.1.0-next.22 refuses a room container compacted by this release (
1008,refused: container) and fails to load (load-error) an IndexedDB store this release compacted, so roll back only together with the data. - Room quotas. The room refuses a write that would take the document past 64 MiB (
EDYTOR_MAX_DOCUMENT_BYTES), a socket sending more than 50 sync messages a second sustained (EDYTOR_MAX_UPDATES_PER_SECOND, a ten-second burst allowed) and a frame over 64 MiB (EDYTOR_MAX_INBOUND_FRAME_BYTES). See quotas.- It closes the socket with the new code
4413(quota: document | rate | frame), which the provider reports as a refusal (refused,onSyncRefused) and does not redial. - Raise them for larger documents; a delete that frees more than it adds still applies to a full document.
- It closes the socket with the new code
- Inline images are capped at 1 MiB. The image plugin refuses a larger
data:URL in its link field (pointing to Upload) and does not import one from an HTML paste (MAX_INLINE_IMAGE_BYTES,storableImageSrc); give it anuploadfor large images. Documents that already hold one still show it.
New
- Snapshots are stored in the v2 encoding, compressed. The room’s compaction snapshot and the IndexedDB store’s are v2 (
encodeStateAsUpdateV2) and gzip-compressed where the platform hasCompressionStream(on theautomerge-papertrace: 224 KB stored instead of 6.7 MB). Update rows stay v1, and the wire is unchanged (v1).- Each container’s generation record says
storage: 'v2'; containers written by 0.1.0-next.22 load as they are and are rewritten by their next compaction. - The room’s
records()marks a v2 snapshot (v2: true) and returns it inflated, takes an optional kind, andcompressed()resolves once a compaction’s compression is stored.
- Each container’s generation record says
- Validate client edits on the server. A
validateoption (attachDocument) or avalidate(frame)override (DocumentRoom) is asked after each client frame that changed blocks, with the blocks it touched and their state before and after;falsemakes the room undo that frame as its own edit, which every client receives. See validate edits (per-block locks as the example). - Large offline backlogs are delivered. The provider sends a frame larger than 32 MiB (its new
maxFrameBytesoption, also oncreateWebsocketSync) as chunks, which the room reassembles: an offline backlog of 40 MB reaches the room at reconnect, where it used to be undeliverable. A room of an earlier release refuses such chunks (refused: malformed): deploy the room first. - Room metrics and log.
metrics()(also over RPC) returns the room’s counters: document and stored bytes, records and rows, sockets, compaction and fold times, fan-out, quota hits and validation denials. The room logs one JSON line per compaction, quota hit, denial and fault (EDYTOR_LOG=offsilences it). See metrics and log. - Offline coverage. See prefetch and last updated and require hydration.
prefetch({ server, room, params })syncs a document’s local copy with its room once and closes (keep documents fresh before going offline).lastUpdated({ server, room, params })asks the room when it last stored a change with one HTTP request thatrouteDocumentSocketanswers (GET <room>?lastUpdated, authorized like a dial).createDocument({ requireHydration: true })and<Edytor requireHydration>seed nothing, and keep the view read-only, until the document was fetched once.- The room keeps a third table,
meta(edytor_meta).
Fixed
- The room stores its live document when it compacts.
DocumentRoom(andattachDocument) used to merge its stored updates into one snapshot, which kept every keystroke’s struct and every deleted character; it now stores the live document’s state, healed and with deleted content collected (on theautomerge-papertrace, 1.6 MB instead of 6.7 MB, and a woken room loads it about six times faster). No API change; rows written by 0.1.0-next.22 load as before. - A joining client gets restorable text. The room’s document also keeps text a peer’s undo may copy back, as an editing replica does: before, a client that joined a room was sent such a deleted copy without its text.
- Per-writer block marks are the writer’s. The room strips a frame that writes another client’s per-writer block mark (
del.<n>,wd.<n>) and drops a delete of another user’s mark: no client can delete or restore a block under someone else’s name.
From 0.1.0-next.21
Breaking changes
- The undo history keeps 200 steps. The undo stack used to grow without bound and kept every deleted character for its undo. It now keeps the newest 200 steps; an older step is dropped and its deleted content released. Pass
history: { limit }tocreateDocument,loadDocumentorattachDocumentto keep more (Infinity: every step);document.historyLimitreads it, and a reattach naming another limit throwsSemanticConflictError. - Turn into keeps a block’s properties. A change of kind (Turn into, a markdown shortcut, the slash menu, Backspace at the start of a heading or a to-do,
block.setBlock({ value: { type, data } })) sets the properties the new kind’s preset names and keeps the others, as Notion does: a checked to-do turned into a heading keepschecked(hidden) and gainslevel.- It used to replace the block’s whole
data, so a hook that matched apatchDatawith an emptypathfor Turn into now sees one patch per property. - To clear properties, delete them or replace the object with
block.setData.
- It used to replace the block’s whole
- Presence is throttled to 50 ms by default. A view writes its selection to presence at most once every 50 ms (the first change at once, the newest at the window’s end), where it used to write every change. Peers see the same final caret; a held arrow key or a drag sends about 20 writes a second instead of one per change. Pass
presence={{ throttle: 0 }}for the previous behavior.
New
- Atomic data paths. A kind can declare
atomic: ['link'](in its block definition, and insemanticsOffor headless documents and the room):block.data.link, and anything written inside it, is stored as one value, so two people setting it at once end with one of their two values, never a mix of both. Nothing changes for kinds that declare none.
Fixed
- Faster editing on large documents. A keystroke no longer rescans the text it lands in, and a structural edit (Enter, a move, a delete) no longer recomputes every block’s placement: a keystroke costs about the same in a document of 2,000 blocks split from one paragraph as in a small one, and Enter, a move or a delete about the same at 20,000 blocks as at 1,000. No API change. A write made inside another transaction’s
updatelistener now shows in that transaction’s change report, not only in its own. - Lines one person adds one after another stay together. A block inserted right after a block the same replica ranked (Enter at the end of a line, Duplicate, the + button, a paste of whole lines) extends that replica’s run there, so when two people each press Enter at the end of the same line and type several lines, each person’s lines stay together (before, they could interleave by client id). Moves are unchanged. No API change; ranks of the earlier data-array run form are still read and extended.
From 0.1.0-next.20
Fixed
- The resize guide no longer jumps when a drag starts. While a column resize drags, the blue guide is drawn where the gray hover guide showed (the band’s middle after the dragged edge), not in the middle of the gap, where it fell on the next column’s
+.
From 0.1.0-next.19
New
- A mouse selection that crosses into another column selects blocks, as in Notion. A text selection dragged from a column into another column of the same layout (into its text, or past the middle of the gap between them) becomes a block selection of every block from the one the drag started in to the one under the pointer, in reading order, with no text highlight. See Columns.
- Back in its own column it is a text range again, and released, the blocks stay selected for Backspace, copy, cut or typing. It used to stay a text range across the columns (the rest of column 1 and column 2’s rows above the pointer).
- A drag that starts outside the layout, a Shift+click and Shift+arrows keep text ranges.
- The editor’s root carries
data-edytor-selection="blocks"while the selection is a block selection, and the core hides the native highlight under it.
Fixed
- A press on the formatting toolbar’s background keeps the editor’s focus. The toolbar plugin now cancels the
mousedownof every press in its host but in a field (aninput, atextarea, aselect): in Firefox and Safari a press on the bar between its buttons used to blur the editor, so the next typing went nowhere. A customtoolbarsnippet’s buttons no longer need their ownmousedownhandler.
From 0.1.0-next.18
Fixed
- The first press after a drag-and-drop also counts on the chrome in Safari. Since 0.1.0-next.18 the editor takes WebKit’s lone
mousedown(the first press after a native drag, which sends nopointerdown) as the press inside the editor. The column resize band and the menus’ press outside now take it too: after a block drop, the first press on a resize band and a drag resize the columns (it took a second press), and the first press outside an open block menu closes it (the+menu’s press outside reads the same press). No API change.
From 0.1.0-next.17
Fixed
- The first click after a drag-and-drop counts in Safari. WebKit fires no
pointercancelwhen a native drag starts (a block handle’s drag) and then nopointerdownfor the next press, only itsmousedown(WebKit bugs 202287, 222632, 279749). The editor now takes a primarymousedownthat nopointerdowncame before as the press, once (apointerdownand itsmousedownstill count once; a script’smousedownis no press). No API change.- After a drop, a click elsewhere places the caret there and replaces the dropped block’s selection (typing used to replace the dropped block).
- After a drop then Mod+Z, the first click places a caret that types (it took a second click since 0.1.0-next.17).
From 0.1.0-next.16
Columns arrive, opt-in, with the changes they needed elsewhere.
Breaking changes
defaultSemanticsholds the layout rows.layoutKindsandlayoutSemanticsare new, anddefaultSemanticsnow includes them, so a headless document and the room (DocumentRoom,attachDocument) show a layout as a view with the plugin does and refuse what it refuses (a block moved directly into a layout). A document with nocolumnsblock is unchanged.- If kinds of your own are named
columnsorcolumn, the room and a headless document now read them as a layout and its columns. - A view whose plugins give
columnsanotherdefaultChildthrowsSemanticConflictErroron a document created withdefaultSemantics: rename them, or pass asemanticswithout those rows.
- If kinds of your own are named
- Nothing selected, nothing written. With the selection
none(after a drop or a column resize, an undo that gives back no selection, Escape, a closed menu), typing, Backspace, Delete, Enter and an IME composition write nothing, even over the caret a browser parks at the editor’s start (Chromium typed there).dispatcher.lastreportsrefused, and what an IME showed is taken back (edytor.composition.targetless).- The navigation keys do nothing then (no caret is invented); PageUp/PageDown still scroll and Mod+A selects every block.
- A click, a tap or a focus from outside the editor places the caret.
- Undo grouping. Typing joins the step before only when that step was typing or a text deletion: typing right after a column resize, a data change, a paste or a conversion is a step of its own, even at the caret that step left.
BLOCK_ACTIVATE_EVENTis cancelable. A menu that answers a grip click and takes the keyboard callsevent.preventDefault()(the bundled block menu does). Unanswered, the editor takes the focus after the click, so Backspace and Shift+arrows act on the selected block. A custom block menu that listens for the event must callpreventDefault()to keep the keys.
New
- The columns plugin.
columnsPlugin,createColumnsPlugin({ minWidth }),isColumnsPluginandColumnsPluginOptionsadd Notion’s multi-column layouts: the kindscolumns(a layout) andcolumn(data.width, a weight), made by dragging a block beside another or with the commandscolumns.2tocolumns.5, resized by dragging the gap. See Columns.- It is not a default plugin: list it in
plugins, in every view that may open a document holding layouts (a view without it shows a layout as unknown kinds, one block under the other).
- It is not a default plugin: list it in
- The
layoutrole.BlockDefinition.layout(andlayoutin asemanticsrole row,BlockRole.layout): a layout’sdefaultChildis its item kind, shown side by side.- The document shows it by its role on every replica: only its items show (another block stored in it shows right after it), an empty item does not show, a layout showing one item or none shows as that item’s blocks, an item outside a layout shows as its blocks.
- Edits write the same (an emptied item goes, then a one-item layout dissolves), in the same undo step.
fits: a container holds containers of its items only when the item renders content (a list still holds a nested list; a layout holds no layout).
- Document operations.
facade.placeBeside(ids, target, side, kind?)(andprepare.placeBeside) places blocks beside a block, in a new column or a new layout;facade.wrapInLayout(ids, kind?, columns?)wraps sibling blocks in a layout (Turn into → N columns);facade.isLayout(id),isLayoutItem(id)andbesideAt(id, kind?)read the role. Deleting a column puts its blocks right after the layout; deleting a layout keeps its blocks in its place, with their kinds (a column is no longer retyped to a paragraph holding children). - Merges cross columns (Notion).
mergeBackwardof a column’s first block merges into the previous shown line in reading order (the previous column’s last line, or the line before the layout) instead of being refused;mergeForwardat a column’s last line pulls the next column’s first line; Backspace after a layout joins its last column’s last line. The outdent of a column’s direct block stays refused. - Moves beside.
BlockMovePositiongains'left'and'right'(edytor.moveBlocks({ blocks, target, position: 'right' }), throughplaceBeside; refused without a layout kind); hooks seemoveBlock/moveBlockswith abeside: { target, side }payload, typedBlockBeside. A moveupfrom a column’s first block, ordownfrom its last (Mod+Shift+↑/↓), leaves the layout. - Turn into commands.
EditorCommand.turnsInto(blocks)makes a command a row of the block menu’s Turn into over those blocks (KindRow.command);turnCommands,wrappableandwrapBlocksare exported, and the operation hooks seewrapBlocks({ blocks, kind, columns }). - A block selection covering a whole layout stands for it: drag, Alt+arrows, Mod+Shift+arrows, Duplicate, Delete, cut and copy act on the layout. The block-selection arrows step over a layout and its columns, never selecting a column.
- Typing over blocks in a column keeps the column. Typing, a composition or a paste over a block selection in a column replaces the blocks in place: the column and its layout stay.
- The editor holds the keys after a drop or a resize. Its root takes the focus without scrolling and without a caret, so Mod+Z and Mod+Shift+Z work right after a mouse-only gesture; a history step that gives back no selection clears the DOM range.
edytor.selection.draggingis reactive: while a text selection is dragged, the block handles and the column resize bands take no pointer (their hosts carrydata-selecting).elementandcontentElementfunctions receive the block’s id:(data, id) => …, for view state a kind keeps per block (the columns plugin’s resize preview); reactive state they read re-renders the element. HTML import passes no id.BlockHandleSnippetPayload.addableis alwaystrue: every handled block has its+, a block in a column too (its Alt+click,add(true), adds a column right of the block’s column). Layouts and columns have no handle.- The handle column reorders. Dragging in the band left of the blocks’ text (the drag’s handle width) places the dragged blocks before or after the row at the pointer’s height, never inside; over a container list where they do not fit, the list is one row. A handle’s box covers its block’s row, so a pointer anywhere in it hovers the block.
- Block menu. The Turn into flyout lists the turning commands (“N columns”) and stays in the viewport, moved up and scrolling inside when needed (
[data-edytor-block-menu-flyout]); the menu and its flyout are placed by their layout size.
Fixed
- A typed-over list keeps its only item. When a block selection holding a list’s only item is typed or pasted over, the list stays and the new line is its item (it used to land where the list was, which went).
- Paste over a block selection lands at a collapsed DOM caret only when a press in the editor or a script put it there; the caret a browser makes up at the editable’s start (after Mod+A twice) no longer takes the paste: the selected blocks are replaced.
From 0.1.0-next.15
New
- Install from npm. The pre-release is published under the
nexttag:pnpm add edytor@next(replace the tarball URL in yourpackage.json). No API change; the tarball URLs this site served keep working.
From 0.1.0-next.14
New
- Leaving a code block by keyboard. Enter in a code block’s empty last line (not its only line) removes the line and puts the caret in a new paragraph after the block, one undo step (the rule for an island of lines,
insertParagraph); ArrowDown in the last line with nothing after the block creates a paragraph there (code plugin). An empty line in the middle is still a new line. facade.isLines(id): whether a block is an island of lines (a code block).
Fixed
richTextPlaceholdershows nothing in an empty code line.
From 0.1.0-next.13
New
- Published to npm. The package names its repository (
repositoryinpackage.json) and a version tag publishes it from CI with provenance: pre-releases under thenextdist-tag (npm install edytor@next),lateststays on0.0.11until a stable release. No API change.
From 0.1.0-next.12
New
- Presence can be throttled and narrowed to blocks. New
presenceprop ({ share?: 'caret' | 'block' | 'none'; throttle?: number }, alsonew Edytor({ presence })and the settableedytor.presence, aPresenceWriter). See Sharing less at scale.throttlespaces a view’s presence writes (first at once, the newest at the window’s end).share: 'block'publishes only the focused block, so moves inside it publish nothing;'none'publishes nothing.
- Peers that share blocks are drawn. A client whose freshest entry is a block set (a block selection, or
share: 'block') shows as a bar beside the blocks with its label ([data-edytor-remote-cursor][data-edytor-remote-block]); before, block selections drew nothing. publishPresencenow returns whether it wrote.
Fixed
- The freshest presence entry wins. The freshest entry of a client now wins whatever its kind, where an older text entry used to win over a newer block selection.
From 0.1.0-next.11
Breaking changes
- The Notion theme’s suggestion preview has no left accent any more: a tinted background only.
--edytor-suggestion-accentnow colors only the bar’s label.
From 0.1.0-next.10
New
- A suggestion that replaces an empty line shows in its place. A
replacewhose blocks all hold nothing (Ask AI on an empty line) folds them (data-edytor-suggestion-replaced="empty", a core style) and the content shows where they were, instead of below an empty, struck-through row.suggestions.at(id)gainsinPlace. Typing in the folded line unfolds it.
From 0.1.0-next.9
Breaking changes
BlockView.handleisBlock | undefined. A suggestion’s preview renders your block snippets with no handle. TypeScript now flagsblock.handle.xin a snippet: guard it (block.handle?.setBlock(…),block.handle && toggle(block.handle)). The bundled kinds already do (the to-do box, the image’s add panel, the code block’s Copy).- The block suggestion API is deprecated.
block.suggestText({ value }),block.suggestionsandblock.acceptSuggestedText()still work, as wrappers over an{ end: block.id }suggestion.edytor.selection.suggestionsis removed: readedytor.suggestions. Three changes:- the suggestion stays when the selection leaves the block (it went before);
- accepting it runs the
acceptSuggestioncommand, which hooks see instead ofacceptSuggestedText, and moves the caret to its end; suggestTextis no command any more (it writes nothing, so hooks do not see it).
New
- Suggestions (AI). New:
edytor.suggestions, a view’s session-only layer of proposed content at a position (after,before,inside,end,replaceof blocks or of the selection). See Suggestions.- It is streamed with
update/append/done, shown in place with the kinds’ own rendering and written byaccept()as one command (acceptSuggestion) and one undo step;textToBlocksturns a string or markdown into blocks. suggestionsPlugin(its bar, Mod+Enter, Escape and Tab) is a new default plugin:<Edytor>adds it after yours; listcreateSuggestionsPlugin({ bar })to render your own bar.
- It is streamed with
- The code plugin’s Tab accepts the line’s
endsuggestion and its Escape discards it, throughedytor.suggestions.
From 0.1.0-next.8
Breaking changes
- Dependencies:
@atlaskit/pragmatic-drag-and-drop4.0.0 (was 1.7.10),@atlaskit/pragmatic-drag-and-drop-hitbox3.0.0 (was 1.1.0) and the new@atlaskit/pragmatic-drag-and-drop-auto-scroll3.2.1. If your app uses Pragmatic drag and drop itself, upgrade it to 4.x too, so both share one adapter (drags of one are invisible to the other’s monitors).
New
- A block drag scrolls the page and its scrolling containers as the pointer nears an edge, with Atlassian’s auto-scroll package (see Auto-scroll). It used to rely on the browser’s own drag scrolling, which only acts at the window’s very edge and never scrolled a container around the editor in Firefox or Safari. Nothing to change in your code.
From 0.1.0-next.7
Fixed
- A to-do’s checkbox shows its click in the view that clicked it. The box toggled the document (peers saw it) but stayed unchanged where it was clicked. Nothing to change in your code.
- If a kind of yours renders its own
<input type="checkbox">(or radio) bound toblock.data, do notpreventDefault()its click: the browser reverts a canceled click after its handlers, over the re-render your write made. - Write the data, then set the box to what the document holds (
event.currentTarget.checked = Boolean(block.data.done)), so a refused write shows unchanged.
- If a kind of yours renders its own
From 0.1.0-next.6
Breaking changes
patchDatatakes array ops. A patch is{ path, value? },{ path, splice }or{ path, order }, and a path addresses an array item by its index or by its id (~…; the proxy of an object in an item writes its id, andfacade.dataItemIds(target, path)lists an array’s ids).- The proxies write them:
push,pop,shift,unshift,spliceand alengthassignment are onesplice,sortandreverseoneorder,tags[1] = 'b'andtasks[0].done = truea write of that item; they used to write the whole array. - A hook that read a whole array’s new value from
valueshould also handlespliceandorder(or readblock.datainonAfterOperation). delete tags[1]now removes the item.- A path segment that is
~and a lowercase letter names an item, so a headlesspatchDatapath writes a key that starts with~as~0…(['~0abc']for the key~abc; the proxies do it for you), and a write to an item whose array was deleted or replaced is refused.
- The proxies write them:
- Upgrade every client together. Arrays written by next.6 read unchanged and become items at the first write that needs it, but a next.6 client reads an array a current client wrote as an object keyed by its items’ ids.
New
- Arrays in properties merge item by item. An array used to be one value, replaced as a whole by every write inside it. Each item is now stored on its own with an id and a position, like a
Y.Array. See Properties.- Two people editing different items, or pushing to the same array, both keep their change, and a removed item stays removed even if someone edited inside it meanwhile.
- Assigning a whole array keeps the items it keeps equal; two views assigning the same array where there was none leave one copy.
- What one person inserts right after their own item in the same session stays next to it, even across separate writes.
- Key
{#each}rows bound into items by the item ({#each tasks as task (task)}): an item’s object is the same proxy wherever collaborators move it.
From 0.1.0-next.5
Breaking changes
- Upgrade every client of a document together. Properties are now stored one entry per property (below); an older client reads only the old whole value, so it does not see properties written by a current client.
block.data,atom.dataand the newedytor.dataare live proxies. Assign to write (block.data.done = true,bind:value={block.data.title}); reads follow the document and are reactive in templates.block.dataused to return a copy: code that kept it to compare later now sees the current value, so copy it ({ ...block.data }or$state.snapshot(block.data)).structuredClone(block.data)throws on a proxy; use$state.snapshot.
- Every data write is the
patchDataoperation.block.setData(data)(wassetBlock),atom.setData(data)(wassetInlineData, now removed fromBlockOperationsand fromBlock) and every proxy write dispatchpatchDatawith{ ops, atom? };setBlockwithdataand Turn into show apatchDatastep.- A hook that matched
setBlockorsetInlineDatafor data changes should matchpatchData, and look inside a replace’svalue(an emptypath). - Writes that type into the same string properties (each new string inserts or deletes one run in the previous one) join one undo step within the capture window, like typing; any other write, a string set to another value included (a status, a select’s option), is its own step.
- A hook that matched
New
- Properties sync per property. A block’s, an inline block’s and now the document’s
datais stored one entry per property, so two people editing different properties of the same block both keep their change (it used to be one value, last writer wins). See Properties. A document written by an earlier version reads unchanged; a block’s old value stays under the properties set over it, and is split into properties at the first delete or replace of what it holds. - Document properties.
JSONDoctakes an optionaldata:createDocument({ value }),<Edytor {value}>and a room’sonLoadseed it,toJSON(), the room’sread()andonSavereturn it, andedytor.valuecarries it as the root’sdata. Headless:facade.patchData(target, ops),facade.docData(), andDocChange.data. Typeedytor.databy augmentingEdytorDocData.
Fixed
- A kind’s controls keep their own keys and clipboard. Any form control inside a block (an
<input>of any type, such as a date field bound toblock.data, a<textarea>, a<select>, a<button>) and any nested editable receive their keys,beforeinput, paste, copy, cut and drops from the browser even while blocks are selected.- Backspace there no longer deletes the selected blocks, Enter and Tab no longer act on them, and a paste there no longer lands in the document.
- A file dropped on one is still swallowed. The editor never moves its caret over a focused one.
- A Turn into that changes nothing is
noop. Giving a block without stored datadata: {}used to write an empty object and reportapplied; empty and absent data are now the same, soconvertToKindanswersfalsefor it.
From 0.1.0-next.4
Fixed
- A drop below the document’s last block keeps its placement. Dragging past the end of the document keeps the last block’s “after” placement, and the pointer’s x still picks the level; it used to show nothing and drop nowhere.
From 0.1.0-next.3
Breaking changes
- The lower half of a block with shown children places before its first child, as Pragmatic drag and drop’s tree guidance asks; it used to place after the whole block, with the line under its last descendant. A closed toggle still takes after.
New
- Drop zones are built on Atlassian’s list-item hitbox.
@atlaskit/pragmatic-drag-and-drop-hitbox(1.1.0) is a new dependency. The halves and nesting by x are unchanged. - Outdent by x to any level. Below the last block of a nested group, the pointer’s x picks the ancestor level, down to the root; the fixed 20px left strip is gone.
From 0.1.0-next.2
Breaking changes
- Nested blocks sit in one indented container. Every kind that renders children puts them in a
div[data-edytor-children], indented by--edytor-nest-indent(24px). A block nested under a paragraph, heading or quote is now indented, as in Notion. CSS that indented children itself should target[data-edytor-children]or set the variable (see Styling). - Drop zones follow Notion. The top half of a block’s row drops before it and the bottom half after it; a drop nests only when the pointer is also more than one nest step right of the block’s text.
New
- Every drag shows a preview of the blocks it moves, a scaled-down copy of them as rendered, with a count badge when several move.
From 0.1.0-next.1
Breaking changes
- Heading and quote text sits in its own
h1/h2/h3/blockquote. The block element is now adiv, and its nested blocks render beside the heading tag instead of inside it, so a page’s heading styles no longer reach them. Selectors written against the old markup (h2[data-edytor-type='heading']) now match nothing: target[data-edytor-type='heading'] > h2instead (see Styling). - The block handle’s + inserts nothing until a pick. It opens the insert menu with its own filter field; a block is added only when a row is picked, and Escape leaves the document and the undo history as they were. Without a slash menu, + adds an empty block as before.
New
- Dragging a handle moves the whole selection. When the dragged block is part of a block selection or of a text range across blocks, every block the selection covers moves, as one undo step; a block outside the selection moves alone.
- A nest drop tints its future parent. The backdrop is themed with
--edytor-drop-backdrop-color.
From 0.1.0-next.0
Breaking changes
block.isEmptyandblock.hasContentcount inline atoms. A block holding only a mention is no longer empty; 0.0.11 and 0.1.0-next.0 counted text only. To test for text only, useblock.content.every((part) => !(part instanceof Text) || part.isEmpty)(the old!hasContent; add&& !block.children.lengthfor the oldisEmpty), withTextfromedytor.onDeleteSelectedBlocksruns whenever a block selection is replaced. Typing, a composition or a paste over a block selection now runs it first, as Backspace, Delete, a cut and the block menu’s Delete do:prevent()keeps the blocks and inserts nothing.- A word or line delete (Alt, Mod or Ctrl with Backspace or Delete) over a block selection now deletes the blocks as Backspace does, hook first and children promoted.
- It used to skip the hook and delete them as a text range in Chromium (a selected parent alone kept its block and lost its text), and did nothing in Firefox and Safari.
- Enter or Shift+Enter over a block selection edits the text, as in Notion. It leaves the selection and puts the caret at the end of the first selected block’s line, as Escape does; nothing changes, nothing is removed and
onDeleteSelectedBlocksdoes not run.- Enter used to empty the first selected block, keep it and remove the others (a checked to-do became an empty paragraph, a heading an empty heading), and Shift+Enter replaced the blocks with an empty paragraph holding a line break.
- Over selected dividers alone either key inserts a line after them (Enter did before; Shift+Enter replaced them).
- Over a selected image the caret now goes to the end of its caption (the image’s line), so text typed right after Enter goes into the caption and a second Enter adds the line; Enter used to insert a line after the image.
- Mod+Enter never splits. As in Notion, it only modifies the blocks it is in: a toggle opens or closes, and with the rich text plugin a to-do checks or unchecks: each shown block among the selected ones (a to-do in a collapsed toggle stays), or the caret’s. Elsewhere it now does nothing, where it used to split the block at the end of the caret’s text node (moving a container’s children out, or an inline atom and the text after it to a new block). To keep a Mod+Enter action of your own, bind
mod+enterinhotKeys. - Room ids are percent-encoded. A 0.1.0-next.0 client put the room id into the URL unchanged; since 0.1.0-next.1 the provider sends it through
encodeURIComponent, soa:bdials…/rooms/a%3Ab.- A Worker that decodes the segment, as the quick start does, routes both forms of an id to the same room unless it holds
/,\,%,?,#, a tab or a line break. - Those ids never reached their room from 0.1.0-next.0, as the URL rewrote them:
/and\(aws:orwss:URL reads it as/) split the path (the quick start’s route answers 404),?and#cut the id short (q?xopened roomq),%read as an escape (a%41bopenedaAb, and50%offdoes not decode, so it is refused4400), and a tab, LF or CR was stripped (a<tab>bopenedab). - Upgraded clients reach the full id, so for those ids the two groups edit different rooms whatever the Worker does: reload every client onto the new version, then move what 0.1.0-next.0 clients wrote under the cut, decoded or stripped name to the full id.
- A Worker that routes on the raw segment (the last path segment, not decoded) sends an id holding
$,%,&,+,,,:,;,=,@,[,]or|(whatencodeURIComponentescapes and a URL path keeps, so50%offdials50%25off; a space or a non-ASCII letter is escaped alike by both, and Chromium already escaped|) to a different, empty Durable Object, while clients still on 0.1.0-next.0 keep editing the old one. No edit is lost, but the two groups stop seeing each other’s edits. - What to do. Decode the segment in your Worker, closing one that does not decode with
closedSocket(4400, 'invalid document id'), and deploy the Worker together with the upgraded clients. A raw-routing Worker stored an id the URL itself escapes (a space arrives as%20) under its escaped form, so after you add the decode those rooms open under the plain id: map the old names in the Worker, or move those documents.
- A Worker that decodes the segment, as the quick start does, routes both forms of an id to the same room unless it holds
- User ids reach the room as
authorizereturns them.routeDocumentSocketnow percent-encodes theuserIdintoX-Edytor-User, so an id with a non-Latin-1 character (which a header could not carry) gets in, spaces around an id are kept (a header dropped them) and an id with a lone surrogate is closed4403. An idauthorizereturned with spaces around it is now another user than the trimmed one its client ids were bound to, so those clients are refused (4409, or1008refused: replicawhenauthorizepasses noreplica): trim the id inauthorizeto keep them. <Edytor server room actor>names its local store without the trailing slashes ofserver. A view with anactornamed its IndexedDB store fromserveras written, sowss://x/rooms/andwss://x/roomskept two stores (and two cross-tab channels, which the store carries); the socket,createWebsocketSyncand a view withoutactoralready removed them.- An app whose
serverends in/now opens a new store,edytor:<actor.id>@wss://x/rooms/<room>: what the room stored comes back from the room, but an edit made offline that never reached it stays in the old store. - To keep the old store, build the sync with its old name:
sync={createWebsocketSync({ server, room, params: dialParams, onExpired: (state) => refreshToken(state), persistName: `edytor:${actor.id}@${server}/${room}` })}, withserverstill ending in/. Oncesyncis passed, the view wires nothing itself:onSyncExpireddoes not apply (passonExpired, which puts a fresh token indialParams),paramsis read at each dial from the object you pass (keep one object and change its fields, asdialParamshere; a new object is never seen), and a room id no URL can carry throws aTypeErrorinstead of reachingonSyncRefused.
- An app whose
.,..and lone surrogates are refused. A URL collapses those segments, and turns a lone surrogate into U+FFFD, so those ids never reached their room; the provider andcreateWebsocketSyncnow throw aTypeErrorfor them (and for an empty id or one over 256 characters), androuteDocumentSocketcloses them4400.<Edytor server room>does not throw: an editable view gets the4400refusal throughonSyncRefusedwithout dialing, and a readonly view renders itsvalue.
Fixed
- Formatting keys keep a block selection. Mod+B and the other mark keys over selected blocks format their text and leave the blocks selected, as in Notion; they used to turn the selection into a text range.
- Over selected dividers alone, the mark keys, Home, End and the word keys keep the dividers selected, and Escape puts the caret at the start of the next line (else the end of the line before); each used to put the caret inside the divider, where typing wrote hidden text into it.
- The word keys over a block selection that starts or ends in a divider, a list or a code block now land on its first or last shown line; they used to put the caret in that block’s hidden text too.
- A composition over a block or inline-atom selection replaces it. An IME composition (Japanese, Chinese or Korean input) over selected blocks now starts in the one empty block that takes their place (a paragraph; inside a list, an item), and over a selected mention in its place, as typing does; it used to write its text at the start of the document’s first paragraph.
edytor.moveBlockswithdirection: 'in'or'out'keeps the text in order. Siblings with another block between them now move as separate runs of adjacent siblings, as Tab and Shift+Tab do:[a, c]out of a listatoeleavesbbetween them, where it used to readb a c. A run that cannot move stays, and the result lists only the blocks that moved. The headlessunNestBlocks(ids)still moves its blocks together (document API).- A throwing
edytor.transact(fn)normalizes the writes it keeps. The normalization the writes before the throw requested now runs before the error leavestransact; it used to be skipped, leaving those writes committed and synced unnormalized.
Upgrading from 0.0.11
The current release rewrites the editor’s internals around one owner per fact. The changes most apps hit first are summarized here; the complete list below names every public change. Documents stored by 0.0.11’s v13 engine do not import: export their JSON with 0.0.11 and create the document from it.
Editor and plugins
valueis the initial content and is no longer bindable:bind:valuefails type-checking. Follow edits withonChangeoredytor.value.Block,TextandInlineBlockare non-reactive handles over the document, and their constructors are gone. Snippets receive aBlockView({ id, type, data, selected, focused, handle, void }), not aBlock: reads go throughblock.handle, and writes are the view’s operations, given the ids.- Selection is a value set with
selection.select(value)orselection.setCaret({ block, offset }). The marks at the caret areselection.projection.marks(wasselection.state.currentMarks); marks for the next insertion areselection.stage(marks)/selection.pending(text.markOnNextInsertis gone). - The
hotkeysmodule and theHotKeysclass are gone. Declare bindings in thehotkeysprop or a plugin’shotkeys(see Hotkeys);HotKeyandHotKeyCombinationcome from the package root. The editor’s keymap is internal (edytor.hotKeysis gone) and itsKeymapclass is not exported. Unknown chord tokens (cmd,esc, …) fail type-checking. - Block kinds declare
defaultChild; thedefaultBlockhook,Edytor.getDefaultBlockandEdytor.defaultTypeare gone (useedytor.defaultChild(parent)).Edytor.getBlockDefinitionis replaced byedytor.definitionOf(type), which never throws: a kind no plugin registers renders as a plain block. - Plugin hooks run on the prepared command before anything is written; a veto refuses the whole command (a gesture over several blocks issues one command per part, see Refusing an edit). Several operation names changed, errors are reported as
refusedinstead of thrown, and the first definition of a kind wins. - Marks render by
tag(<strong data-edytor-mark="bold">), which changes CSS selectors. A placeholder is a plugin’splaceholder, a string or a function. HTML paste is built in. - A block selection holds exactly its members, and an emptied document shows a virtual paragraph.
See the editor and plugins sections for the current APIs.
Collaboration and providers
attachDocumentSyncis removed: usedocument.attachSync. The presence format changed (one entry per view inselections), so old and new clients do not see each other’s carets.createWebsocketSynctakes{ server, room }, the names of the<Edytor server room>props (serverUrlandroomNamewere removed after a deprecation). It keeps a local IndexedDB copy by default (persist,persistName) and syncs tabs by default (disableBc). It no longer takesconnect,protocolsorresyncInterval; pass tokens inparams.- The provider sends the room id percent-encoded as one path segment (
acme/roadmapdials…/rooms/acme%2Froadmap): a server that routes on the path must decode it. The ids.and..throw, as a URL collapses those segments, and so do an empty id, one over 256 characters and one with a lone surrogate. WebsocketProviderlost theprotocolsoption, thesyncevent (usesynced) andwsconnecting(use thestatusevent). It gainedsaved,unsaved,readOnly(the room’s read-only notice), the'saved'event, therefused,expiredandunreachableevents, and theconnectTimeoutoption.IndexeddbPersistencelostget,setanddel.- The document decides readiness itself:
syncFailed,onSyncSettledandEdytorDocSyncPendingErrorare gone; see readiness. A document keeps one provider per target. - Content with a foreign schema makes the document read-only (
document.writable) instead of throwing on every edit. edytor/cloudflareis new: the Durable Object room replaces a coordinator you wrote yourself.
Document API
- Every facade operation returns an
OpResult(applied,nooporrefused) instead of a boolean. Operations on deleted or missing blocks are refused. - Operations have a two-phase form:
facade.prepare.<op>(),facade.apply(plan),facade.compose(...plans). New operations:deleteRange,replaceRange,deleteBlocks,insertFlow,insertBlocks,liftOut.toBlockSpec(json)turns canonical JSON into theBlockSpecthat inserts take. - New queries:
order,compare,next,previous,canPlace,canMerge,defaultChild,fits,nestParent. facade.onChangereports oneDocChangeper commit. The per-block subscription API (subscribeBlock,subscribe,blockVersion,snapshot),decorateRunsand thebind*building blocks are no longer exported: useonChangewithruns(id), a block kind’stransformTextfor decorations, andbindCrdt(Y)for engine injection.deleteBlock(id)anddeleteBlocks(ids)delete only the named blocks; children take their place. Pass{ keepChildren: false }for the old whole-subtree delete.- Undoing a block’s creation keeps the block while it holds another person’s content;
hasBlock(id)staystrue, and re-creating an undone id is refused. - A document edited without a view adopts the bundled block roles (
defaultSemantics) unless you pass othersemantics. - Selection anchors are
{ b, a };toJSON()gives inline blocksdata: {}when they have none. duplicateBlock(id, freshId)callsfreshId(oldId, kind)for every copied block (kind'block') and inline atom ('inline'). A callback that returns nothing for an atom gets a fresh atom id; returning nothing for a block refuses the copy.
Stored documents
- Documents, IndexedDB stores and peers from earlier development builds of the v14 engine are refused (
GenerationMismatchError,'schema-mismatch'): re-import them from JSON, v13 documents too. - Seeding a
valueis deterministic, so replicas seeding the same template converge.BOOTSTRAP_BLOCK_IDis gone, and seeded blocks have nocreatedBy.
Complete list of changes
Every public change since 0.0.11, by area.
Stored documents
- Properties are stored per leaf. A block’s, an inline block’s and the document’s (root
docdata) data is one attribute per leaf,d/and its JSON pointer; the older wholedataattribute is no longer read. - Array items are stored per item. An array is a
[]leaf and its items: itemid’s value under~id, its position (a rank) in~id#, or in~id>once moved. An array of the previous pre-release is read as items with ids derived from their indexes and split into them by the first write that removes one. A client of that pre-release reads such an array as an object, so upgrade every client together. - Schema generation 8 (wire word
14008): a merge is an item of the text it joins, a text delete is its writer’s record in the document, and one update encoding, the columnar one, on the wire and in storage (since generation 6). Documents, containers, browser stores, history versions and peers of every earlier generation are refused by the generation gate (GenerationMismatchError,schema-mismatch), never converted: re-import them from JSON. The browser database isedytor-v14-g8:<name>; the databases of earlier generations (edytor-v14:<name>,edytor-v14-g5:<name>,edytor-v14-g6:<name>,edytor-v14-g7:<name>) are left as they were, unread. Behind the bumps since 0.0.11: per-writer delete marks (a deleted block is not read as live), the replicated block noncen(attribution records keyed by it), text ownership as streams delimited by boundary items (theslicesattribute is gone; a merge is an item in the text, theclaimslist is gone), paired marks, shorter ranks and per-writer text deletes that an undo takes back. - Schema generation 11 (wire word
14011, browser databaseedytor-v14-g11:<name>): shared suggestions in the document, a rootsuggestof suggestion records. Every earlier generation is refused by the generation gate, never converted. - v13 (
yjs) documents no longer import (they did before 1.0.0). - Deterministic seeds.
createDocument({ value })and<Edytor {value}>write the value under a writer id hashed from it, so two replicas seeding the same template converge and a late identical seed never erases an edit. See deterministic seeds.- Missing ids are derived from that hash. Seed writer ids sit below 2^26, so a seed never displaces a block a live replica wrote.
- Seeded blocks carry no attribution stamp (
createdByis absent).BOOTSTRAP_BLOCK_IDis gone.
Document and CRDT API (edytor, edytor/crdt/edytor)
- Operation results. Every document operation returns
OpResult{ status: 'applied' | 'noop' | 'refused', ids, reason? }instead of a boolean. An empty op (insertText(''), an empty range,moveBlocks([]), a same-value format) isnoopand writes nothing; a reused child id isrefused(id-collision); an absent target isrefused.moveBlocksanswers the moved ids in request order. - Two-phase operations.
facade.prepare.<op>(…)returns a plan (steps, effect, ids) or the refusal without writing;facade.apply(plan)writes it in one transaction;facade.compose(...plans)joins plans prepared at one version. A plan applied at another version throws. Positions areDocPosition { block, offset }. See the document API.- New ops:
prepare.deleteRange(start, end, view?),replaceRange(start, end, view?),deleteBlocks(ids),insertFlow(target, flow, view?),insertBlocks,liftOut(id, kind, { keep?, after? })(places a block where a kind fits, out of every list it does not fit, as Turn into does). - The optional
view({ hidden(id, removed?) },RangeView) names the blocks a view hides, such as a closed toggle’s body, which a range leaves alone and a paste keeps with its first line.insertFlow’s (FlowView) also takesitemKind(parent), a list’s flat item kind, whose pasted lines become the list’s items. The editor passes it. - New helper:
toBlockSpec(json, { freshIds? }).
- New ops:
- Liveness. Deleting a block that is not live (already deleted, merged away, under a deleted parent) is refused (was
true);blockTextof a block under a deleted parent isnull. - Order and capability. New
facade.order(),compare(a, b),next(id, policy?),previous(id, policy?)(one document order;{ sealed: true }never enters an island it did not start in),canPlace(ids, parent?),canMerge(from, into),defaultChild(parentId),rendersContent(type),fits(parent, kind)(the container rule: may a block ofkindsit directly underparent) andnestParent(ids, parent)(where Tab nests them:parent, or a container’s last item).- A list holds only its items:
canPlaceanswersfalseandmoveBlocksis refused where blocks would sit directly in a container they are no items of (a block already in it, such as an image a merge left there, still reorders among its items). nestBlockinto a list nests under its last item (refused when the list ends with a block that holds no children, such as an image).- A paragraph stored directly in a list (an explicit write, a concurrent race) shows as its item.
- A list holds only its items:
- Block roles as data.
createDocument({ semantics })takes block roles, content-less kinds and default children; views still adopt roles from their plugins. See the document API.defaultSemantics,richTextSemantics,codeSemantics,imageSemanticsandlayoutSemanticshold the bundled plugins’ rows (defaultSemanticsthe other four: the columns plugin’s layout rows too, though it is not a default plugin;layoutKindsis the columns plugin’s kind table) and are deeply frozen.semanticsOf(...tables)(with theKindSemanticsrow type) builds a config from kind rows. To extend a bundled config, mergeroles,rendersContentanddefaultChildfield by field, since a top-level spread drops the bundled rows.- A document adopts roles as
mergeSemanticsmerges them: a view’s or a reattach’s declaration that disagrees with the document’s is aSemanticConflictErrorwhoseexistingandincomingare the two declarations as written.
- Properties. One data operation,
patchData(target, ops), which only writes the properties and array items it changes; a patch of the root ([{ path: [], value }]) replaces the whole object (the aliasessetBlockDataandsetInlineDataare removed). See Properties.targetis a block id,{ block, atom }, ornullfor the document;opsare{ path, value? },{ path, splice }and{ path, order }, a path naming array items by index or id and a key that starts with~as~0…;facade.dataItemIdslists the ids.facade.docData()reads the document’s own data,JSONDoc.dataholds it (seeded, exported bytoJSONonly when present), andSerializableContentincludes arrays.
- Atomic data paths. A kind’s role (
BlockRole, a block definition, asemanticsOfrow) may declareatomicpaths: a write there writes the whole value as one property, so concurrent assignments never merge into a mix of both. Roles compare theiratomicsets when adopted. - A retype keeps the properties.
setBlockwithdata(Turn into, a markdown shortcut, the slash menu, Backspace at the start of a kind) sets the properties it names, onepatchDatapatch each, and removes none: a to-do turned into a heading keepscheckedand gainslevel. It used to replace the whole object. UsepatchData(id, [{ path: [], value: data }])to replace it. - Block runs. A block inserted right after a block this replica ranked (
insertBlocks, Duplicate, a whole-line paste; never a move) is ranked in the replica’s run there (the rule data arrays use, now one segment per run), so concurrent Enters at the end of one line never interleave the two people’s lines. - History limit. The undo stack keeps the newest
history.limitsteps (DEFAULT_HISTORY_LIMIT, 200;Infinitykeeps every step); a dropped step releases the deleted content it kept.document.historyLimitreads it; a reattach naming another limit is aSemanticConflictError. - A session’s end.
document.endHistory()ends the session’s history: every step released, and what the session deleted the room’s at its next purge (a release record in the rootreleased). The view calls it when its page leaves for good. See history. - Change report.
facade.onChange(cb)delivers oneDocChangeper commit that changed the visible document or its data:{ added, removed, moved, meta, content, order, data?, origin, local, version }(data: the document’s, when it changed). A block that moves into a subtree added in the same commit is reported inmoved/meta/content, not folded into the subtree. A write made while another transaction’s change is being reported (in anupdatelistener or an observer) is folded before the report reads the document, so it shows in that report too. - Retired exports. Use
bindCrdt(Y)(.doc,.providers,.sync,.admission,.attribution) for engine injection,facade.onChange+facade.runs(id)for reads, and a kind’stransformTextfor local decorations. Gone:- the per-block subscriber API (
subscribeBlock,subscribe,blockVersion,snapshoton the facade and the index),decorateRunsand its types (LocalDecoration,DecoratedRun); - the “advanced internals” tier:
bindEdytorDoc,bindDocument,bindNodes,bindModel,bindRuns,bindIndexeddbProvider,bindWebsocketProvider,bindProviders,bindSync,bindAdmission,bindAttribution,bindBlockAttribution,bindMigration,bindLegacyReader,setDocRand/randOf, the rank functions; - the constants and helpers
REGISTRY_KEY,SCHEMA,SCHEMA_NAME, the attribution root constants,migrationBcRoom,PREFERRED_TRIM_SIZE,GENERATION_PREFIX,generationDbName,GENERATION_KEY,writeProtocolVersion,removeAwarenessStates,outdatedTimeout,readAuthMessage, and their types.
- the per-block subscriber API (
- Kept for a server coordinator (see the protocol):
bindCrdt(Y),SCHEMA_VERSION,META_KEY,GENERATION,generationWord,frame,PROTOCOL_VERSION,readProtocolVersion,GENERATION_RECORD,GenerationMismatchError, the message types, the lib0 frame helpers, the awareness codec (readAwarenessEntries,writeAwarenessEntries,applyAwarenessUpdate,encodeAwarenessUpdate;modifyAwarenessUpdateis removed) andmessagePermissionDenied/writePermissionDenied. New:messageReadOnly/writeReadOnly,messageSaved,messageChunk,MAX_FRAME_BYTES,chunkFrame,createChunkReader. - The raw engine (
edytor/crdt) ships only what the editor calls: documents, nodes, transactions, the one update encoding, id sets andRangeCursor. Edytor never called the rest; it is removed from the vendored engine (with lib0’s delta and schema libraries):- the delta layer (
toDelta,toDeltaDeep,applyDelta, the maintainednode.deltaandclearCache,node.change, a node’s'delta'event,Node.from, a delta inserted as content, andevent.delta,event.deltaDeep,event.getDelta), the renderers (AbstractRenderer,$renderer,useRenderer,AttributionsRenderer,createAttributionsRenderer,DiffRenderer,createDiffRenderer,SnapshotRenderer,createSnapshotRenderer) and the schemas ($doc,$node,$nodeAny,$idSet,$idMap,$idMapAny,$contentIds,$contentMap); - plain formats (
node.format,insert’s format argument,cleanupYTextFormatting: a node writes marks,node.mark), observers (observe,observeDeep,unobserve,unobserveDeep,YEvent, thebeforeObserverCallsandafterTransactionCleanupevents: the document’scommitevent, thenafterTransaction, tell a commit) and a node’s renderings and conveniences (toJSON,toString,toArray,get,slice,getAttrs,hasAttr,attrValues,attrEntries,attrSize,map,forEach,push,unshift,clone,clearAttrs,parent); - relative-position objects (
RelativePosition,AbsolutePosition,createRelativePositionFromTypeIndex,createRelativePositionFromJSON,createAbsolutePositionFromRelativePosition,relativePositionToJSON,encodeRelativePosition,decodeRelativePosition,compareRelativePositionsand the delta-position helpers):idAtIndexandindexOfIdare a position’s id and live index; - subdocuments, the load state and the JSON, embed and subdocument contents (
ContentDoc,ContentEmbed,ContentJSON), a transaction’sbeforeState,afterState,metaandcleanUps; - snapshots (
Snapshot,snapshot,createSnapshot,emptySnapshot,createDocFromSnapshot,encodeSnapshot,encodeSnapshotV2,decodeSnapshot,decodeSnapshotV2,equalSnapshots,snapshotContainsUpdate,nodeMapGetSnapshot,nodeMapGetAllSnapshot, thesnapshotargument ofnode.getAttrs); - update helpers (
logUpdate,logUpdateV2,obfuscateUpdate,obfuscateUpdateV2,encodeStateVectorFromUpdate,encodeStateVectorFromUpdateV2,convertUpdateFormatV1ToV2,createContentIdsFromUpdate,createContentIdsFromUpdateV2,intersectUpdateWithContentIds,intersectUpdateWithContentIdsV2,readUpdate,createDocFromUpdate,createDocFromUpdateV2,cloneDoc,diffDocsToDelta,logNode); - id-set algebra beyond the basics (
gcIdSet,createInsertSetFromStructStore,encodeIdSet,decodeIdSet,equalIdSets,IdSet#forEach,covers,coveredLength,slice), id maps and content maps (IdMap,createIdMap,insertIntoIdMap,readIdMap,writeIdMap,encodeIdMap,decodeIdMap,mergeIdMaps,diffIdMap,intersectMaps,filterIdMap,createIdMapFromIdSet,createIdSetFromIdMap,ContentAttribute,createContentAttribute,ContentMap,createContentMap,readContentMap,writeContentMap,encodeContentMap,decodeContentMap), the content-id helpers (createContentIds,createContentIdsFromContentMap,createContentIdsFromDoc,createContentIdsFromDocDiff,excludeContentIds,excludeContentMap,mergeContentIds,mergeContentMaps,createContentMapFromContentIds,intersectContentIds,intersectContentMap,filterContentMap,writeContentIds,readContentIds,encodeContentIds,decodeContentIds), andgetNodeChildren,getPathTo,tryGc,undoContentIds, withdocument.attribution.legacy(): thea/records of early builds stay in the document, unread. - A document built with
createDocFromUpdate(u)is a new document +Y.applyUpdate(doc, u)(for edytor content,bindCrdt(Y).createDoc(), seeDoc.keepReplaced).
- the delta layer (
- Anchors are
{ b, a }: theoowner facet and thea: -2form are gone from the selection value, the presence wire and history entries. - Attribution. Undo and redo keep a block’s record (
createdBysurvives an undo/redo of its creation on every replica). The opt-in per-block lineage ring (thelineagedocument option,attribution.history(id),BlockLineageEntry) is gone. A client’s actor binding (c/<clientID>) and its actor’s profile are written with its first edit, never when the document is created or opened:actorOfresolves a client id that wrote,actorslists the actors whose clients wrote. facade.toJSON()inline atoms carrydata: {}when they have no data (the shapeedytor.valuealready had).- Block deletes promote children.
deleteBlocks(ids)anddeleteBlock(id)delete only the named blocks: each one’s unselected children take its place (a deleted island’s children take the default child type).deleteBlock(id, { keepChildren: false })is the whole-subtree delete (was the default). Promotion is read-time: a block a peer adds, moves or splits off under a concurrently deleted block also takes that block’s slot, so nothing is hidden with a deleted subtree. - Void blocks hold no children. Retyping a block to a void kind moves its children right after it; a child that still lands under a void block (a concurrent nest) is shown in its slot.
- Undo of a creation withdraws. The history no longer deletes a block node it created: it writes a per-writer withdraw mark
wd.<writer>, and the block is shown while it holds another writer’s content.hasBlock(id)staystruefor a withdrawn block, and re-creating an undone id is refused.- Old clients of the same schema generation ignore the marks and show a withdrawn block (empty, or with the other writer’s text); an old client’s own undo still deletes the node.
- A withdrawn block costs its node in storage (about 100 bytes) instead of a tombstone.
- Text delete records. Every text delete writes a record naming its writer (root
textdel, in the history’s scope); the text it deletes stays in the document, hidden while a record holds it, and an undo removes the undoer’s record, so the same text shows again where it was (no copy, no restoration record). An undo step that leaves the history (past its limit, or dropped by a new edit after an undo) deletes for good the text its records held.document.historyis created byfacade.createUndoManageras before.- Old clients of the same schema generation ignore both and keep the previous undo behavior (a double delete undone by both peers can show the character twice).
- A text delete update is about 21 bytes larger and a stored document about 12 bytes per delete.
- Conflicting type changes. An undo returns a block to the type you replaced, never to no type.
- Paired marks. A mark write is one operation; overlapping marks of one value union, a later mark wins where it covers, no end clears another mark’s tail; a mark’s
edgedecides where a concurrent insert at its ends lands.DocumentSemanticsConfig.marksholds mark edges for a document without a view (richTextMarks, indefaultSemantics); views adopt their mark records’edge. A keyname:<id>reads thenamerecord (one mark per comment).markName,MarkEdge,facadeConfigOf. - The document’s own undo manager. The engine has no undo manager;
document.historyandcreateUndoManager({ trackedOrigins, captureTimeout, limit, captureTransaction })are edytor’s (YUndoManager):observe(f)for its steps,undo()/redo()returning the step,clear()(wasfacade.releaseHistory(um)); the engine exportskeepItemandfollowRedone, andredoItemtakes(…, itemsToDelete, deletedByHistory?). - One update encoding (generation 6).
edytor/crdtreads and writes one update encoding, the columnar one (applyUpdate,encodeStateAsUpdate,mergeUpdates,diffUpdate,decodeUpdate,UpdateEncoder,UpdateDecoder, theupdateevent);applyUpdateV2,encodeStateAsUpdateV2,mergeUpdatesV2,diffUpdateV2,decodeUpdateV2,readUpdateV2, the v1 and v2 encoder and decoder classes,convertUpdateFormatV2ToV1and theupdateV2event are gone. The cutover from earlier generations (bindCrdt(Y).generations,PREVIOUS_SCHEMA,isPreviousGenerationRecord,STORED_GENERATION_RECORD,STORAGE_FORMAT,sync.step2Update) is removed with it: an earlier generation is refused, never converted. One inbound sync path:sync.applyRemote(doc, payload, origin)andsync.writeSyncStep2(readSyncStep1,readSyncStep2,readUpdateandreadSyncMessageare removed). - Layouts. A kind whose role says
layout(BlockRole.layout) shows its items side by side and is shown by read-time rules on every replica: only its items show (another block stored in it shows right after it), an empty item does not show, a layout showing one item or none shows as that item’s blocks, an item outside a layout shows as its blocks. Edits write the same in the same step (an emptied item goes, a one-item layout dissolves).- New
placeBeside(ids, target, side, kind?),wrapInLayout(ids, kind?, columns?),isLayout(id),isLayoutItem(id)andbesideAt(id, kind?). mergeBackwardof an item’s first block merges into the previous shown line in reading order andmergeForwardcrosses items; deleting an item puts its blocks after the layout, deleting a layout keeps its blocks in its place with their kinds.fits: a container holds containers of its items only when the item renders content (a layout holds no layout).
- New
Editor view, selection and commands
-
Development-only misuse checks. Combining
documentwithdoc/awareness/actor/requireHydration, anddispatcher.outsideinside a transaction, throw in development builds only. -
A key reads a selection the browser moved before it. A press, an arrow or Shift+arrow the model has not adopted yet (its
selectionchangestill queued) is read first, so a shortcut right after them acts on the selection the user sees. -
One write API.
EdytorDocumentcarriesDocumentOperations(document.insertBlocks(…)), and the view carries the same writes under the same names (edytor.insertBlocks(…)), dispatched: hooks, vetoes, normalization, one undo step, the result caret,readonly. Handles only read.document.facadeis deprecated; the types the operations use are exported fromedytor.document.block(id)(DocBlock) is removed. -
selection.select(value)takes the value only; the dispatcher publisheslast,permits(),run,each,dispatch,lead,caretandoutside, the rest is internal. -
edytor.focus()focuses the editor, keeping its selection or putting the caret at the start;selection.value,selectedBlocks,focusedBlocksanddispatcher.lastare read-only. -
Pasted and dropped files. Each media plugin takes its own
upload(createImagePlugin({ upload }), and the file, video and audio plugins); a pasted or dropped file is placed as a block of the kind that takes it (a kind record’supload,KindUpload, with itssend) and sent with that kind’s uploader; a plugin without one takes no files.upload(file, report)reports progress (Uploader,UploadReport); the block shows the file at once while it uploads (an image’s local preview, a file’s name and size, the progress: the empty controller’spreviewandprogress, the file row’suploadingandprogress). Files dragged from outside show the block drag’s drop line and land there, the page scrolling near its edges;onPastegets that place asat. The file drop comes with the first media plugin given anupload: without one, the editor ignores a drop carrying files. -
Markdown paste. A
text/plainpaste holding block markdown is placed as its blocks (textToBlocks); see Pasting markdown. -
Import and export.
edytor/export(Svelte-free: browser, Node, Workers):toHTML,toMarkdown,fromHTML(safe, aDOMParsergiven on a server),textToBlocks(the full reader: GFM tables, code languages, nested marks,streaming: true;edytor’s, which paste reads, is unchanged),bundledFormsand each bundled plugin’s forms (richTextForms,codeForms,tableForms, …); kind, mark and atom records take amarkdownform. See Import and export. -
Exported types. The types the root entry’s props, options, members and callbacks use are exported from
edytor(EdytorProps,EdytorOptions, the labels types,Dispatcher, the selection, hotkey, plugin, document and sync types); see the note of the release that added them. -
valueis not bindable.<Edytor value>is the initial content;bind:valuefails type-checking. Read edits withonChangeoredytor.value. -
Component props. New:
document(anEdytorDocumentto render; several views can share one),actor(the local author),room,serverandparams(the view builds its IndexedDB copy and its websocket sync from them),onSyncExpired(the room closed with4401; refreshparamsbefore the redial) andonSyncRefused(a refusal standing at mount, then each new one),defaultPlugins, and the root attributestranslate,spellcheck,autocorrect,autocomplete,autocapitalize,inputmodeandenterkeyhint.synctakes anEdytorSync(a factory fromcreateIndexeddbSync/createWebsocketSync, or your own) and overridesroom/server.hotkeysis typed (see Keymap below). See the component. -
Handles.
Block,TextandInlineBlockare read-only, id-only handles over the document index: getters read the document (inside a command they see its writes); they are not reactive (exceptdata, a reactive read). Templates read the snippet’s view object oredytor.cells. Every write is an operation of the view, given their ids.new Block({block}),new Text({…content})andnew InlineBlock({block})are gone: useedytor.insertBlocks(destination, blocks),edytor.insertTextandedytor.insertInline.- A
Textis theordinal-th segment of its block (text.id=t:<block>:<ordinal>) with no identity across commits; key extension state by block id and anchor. - Liveness:
block.isInTree,text.isInDocument,atom.isInDocument(_live,_bound,_blockId,_segOrd,_itemsare gone; a dead block’sparentisundefined). edytor.idToBlockis the handle registry (get(id),block(id),text(blockId, ordinal),atom(blockId, atomId),parts(id));edytor.idToText,edytor.idToInlineBlock,Edytor.getTextById,Block.partOffsetOf/atomOffsetOfPartIndex/projectedPartsare removed (a text’s display offset istext.segStart, a block’s partsedytor.idToBlock.parts(id): read-only, each with its displaystartandend, a text’stext,runsandsegOrd, an atom’sid,typeanddata).InlineBlock.typehas no setter.Block.firstText/lastTextareundefinedfor a kind that renders no content.- New getters:
Block.isContainer(a block that shows only its children, such as a list),Block.isListItemandBlock.list(the list an item shows in);Block.convertibleisfalsefor a list container (its items convert).
-
Emptiness counts inline atoms.
block.isEmpty(no content and no children) andblock.hasContentcount inline atoms as content, so a block holding only a mention is not empty (0.0.11 counted text only). To test for text only, useblock.content.every((part) => !(part instanceof Text) || part.isEmpty)(the old!hasContent; add&& !block.children.lengthfor the oldisEmpty). -
Data writes are operations.
edytor.patchData(target, ops)writes block, atom ({ block, atom }) and document (null) data: refused on a readonly view, shown toonBeforeOperation, recorded indispatcher.last, its own undo step (typing into the same string properties joins one).block.data,atom.dataandedytor.dataare plain state: an assignment, a delete or an array method at any depth is apatchData, and the writes of one task are one. -
Definitions.
edytor.definitionOf(type)is the one lookup and never throws (getBlockDefinitionis removed). A kind no plugin registers renders as a plain block (its text and children), with one development warning per kind, instead of throwing.edytor.containeris removed: useedytor.node. -
Op results. Every operation of the view answers its
OpResult(refusedwhen a hook vetoed it or the view is readonly), also inside an outeredytor.transact;idsname what it created. -
Selection is a value.
selection.value(none,text { anchor, focus, pending? },atom { blockId, atomId, from },blocks { ids }),selection.select(value, cause)(the only writer),projection,epoch,cause,textValue,stage(marks)/pending.onSelectionChangefires only when the value changed (a remote edit that moves the projection does not emit).-
The selection has one view,
selection.projection;selection.state(SelectionState) and the setterssetAtTextOffset,setAtRange,setAtTextsRange,setAtBlockRange,selectBlocks,addBlockToSelectionandremoveBlockFromSelectionare removed: readprojectionandcaret, writesetCaret({ block, offset })andselect(value). -
The projection facts moved to
selection.projection:content(and itslength),marks(wasstate.currentMarks),isAtStartOfText/isAtEndOfText/isAtStartOfBlock/isAtEndOfBlock,isTextSpanning,islandRoot/voidRoot(block ids;isIsland/isVoidare!== null). -
The caret anchors are the value’s (
relativePosition/endPosition→selection.value.anchor/focus);contentParts,startNode,endNodeandyTextContentare gone. -
setRangeStateAtTextOffsetsandsetCollapsedStateAtTextOffsetare removed with the setters above:setCaret({ block, offset })andselect(value)select in the caller’s turn. -
Removed:
hasSelectedAll,focusBlocks,deadEndpointRecoveryPending,notifyTextMounted,Edytor.getTextNode,ignoreNextSelectionChange,Edytor.mirrorRevision.
-
-
Pending marks are
selection.pending/selection.stage(marks)(Text.markOnNextInsertis gone); a move clears them, an insertion at the caret consumes them, and they hold valued marks (links, colors) as a full set. -
Default children. The plugin
defaultBlockhook,Edytor.getDefaultBlockandEdytor.defaultTypeare removed: a kind declaresdefaultChild;edytor.defaultChild(parent)answers. -
Deletion and paste follow one rule each:
- blocks after the range end inside a dying container, and a dying tail’s children, survive; an emptied list container dies;
- a range from inside an island never merges out of it, and a range inside one
linesisland never removes it (its first line stays, emptied: a code block’s Mod+A, then Backspace, Delete or cut); - a list or a table row never merges as a whole (
canMergerefuses it): Delete at the end of the block above a list pulls the first item’s text up and the list keeps the rest, and Backspace at the start of a list’s first item lifts it out of the list, as its new parent’s default child; - multi-line plain paste and drop split the block per line; copied fragments keep their ids and paste always mints fresh ones.
-
Moves.
BlockMoveRequestis{ blocks } & ({ target, position } | { direction: 'up' | 'down' | 'in' | 'out' });BlockMoveDirectionand the move types come from the package root (the deep import of the old block-move module is gone).- A move is its own undo step, and a move that lands in or under a closed toggle opens it (
edytor.move,edytor.moveBlocks,edytor.nestBlockandedytor.unNestBlocktoo, as the handles and keys do). - Arrow-move never nests;
Mod+↑moves a selected group; the handle claims every Alt+arrow key. - Outdent (Shift+Tab,
unNestBlock, directionout) hands the following siblings to the outdented block, as in any outliner; an item of a list container leaves the list instead, without the items after it (a middle item splits the list). BlockMovePositiongainsleftandright: beside the target, in a new column of the layout it is in, else in a new layout wrapping it (prepare.placeBeside; refused without a layout kind); hooks see theplaceBesideoperation.
- A move is its own undo step, and a move that lands in or under a closed toggle opens it (
-
Keymap. The
hotkeysmodule is deleted: the types move to the package root (HotKey,HotKeyCombination;HotKeyModifier,Single/DoubleModifierCombinationremoved).HotKeys→ the editor’s internal keymap, whoseKeymapclass is not exported (isHotkey→handle,run(chord),offered; noinit).- A
HotKeypayload’seventis optional. A key binding runs once per occurrence. - Chords take up to three modifiers in any order, plus punctuation and
f1–f12;spacematches the space bar. Unknown tokens (cmd,esc,return, …) fail type-checking and warn in development. - The
hotkeysprop is typedPartial<Record<HotKeyCombination, HotKey>>.
- A
-
Navigation. Shift+Home/End/PageUp/PageDown, Shift+↑/↓ and Mod+Shift+↑/↓ move the focus and keep the anchor (Mod+Shift+↑/↓ only where the arrow move plugin is not listed or has no block to move; otherwise it moves the caret’s block); word keys are visual under RTL; arrows skip a collapsed toggle’s body; an atom selection carries the side it was anchored on (
from). -
The end of the document. ↓ at the document’s last place, when that is not a top-level paragraph, and a click below the last block put the caret in an empty paragraph after the last block, created when needed (one undo step); the code block’s own ↓ rule is gone. See navigation.
-
Input and IME.
edytor.attempts(the input attempts) andedytor.composition(the session:live,phase,host,owns(node),ended(fn),restructured(change)) are new;edytor.isComposingis read-only.- Removed:
compositionState,compositionStartReplacementState,hasHandledCompositionInput,compositionText,resolveCompositionRegion,shouldIgnoreCompositionKeyDown,Text.toCompositionDomOffset, and the input-fallback flags and timers onEdytor. - A composition is one undo step with its ending; no timer ends it; a commit that re-places the composing block (a peer deletes, retypes, moves or re-parents it) commits what the IME shows first.
- A composition over a block selection, a selected atom or a text range across blocks replaces it as it starts and composes at a caret in its place; over a range inside one block, the range is replaced at the first preview.
onBeforeInputno longer sees fabricated paste, drop or keydown-fallback events.preventUnsupportedDrop(event, edytor?).
- Removed:
-
History.
edytor.historyUndo()/historyRedo()restore the selection each step recorded for this view (before on undo, after on redo); the undo-snapshot queue and its helpers are gone. See history.- The dispatcher owns undo grouping: structural edits, deletions, menu, toolbar and
+actions, and markdown or slash conversions are each their own step, however soon they follow typing. - Typing joins the step before only when that step was typing or a text deletion (typing right after a column resize, a data change, a paste or a conversion is its own step).
- The dispatcher owns undo grouping: structural edits, deletions, menu, toolbar and
-
Nothing selected, nothing written. With the selection
none, typing, Backspace, Delete, Enter and an IME composition write nothing (dispatcher.lastisrefused;edytor.composition.targetless), even over a caret the browser parks; the navigation keys do nothing (PageUp/PageDown scroll) and Mod+A selects every block. After a drop or a column resize the editor’s root takes the focus without a caret, so Mod+Z works at once. A paste over a block selection lands at a collapsed DOM caret only when a press or a script put it there.edytor.selection.draggingis reactive. -
Block selection is exactly its members. Select-all selects every block (was the root’s children); Shift+↑/↓ adds each block it passes; a block copy or cut carries the selected blocks only, a selected list or code block with everything in it (
selection.selectedMembers;selectedBlocksholds the blocks as clicked).- Deleting or cutting a block selection, or the block menu’s Delete, puts the caret at the start of a child promoted into its place, else at the end of the nearest line before it (else at the start of the nearest line after it).
- Escape, Enter or Shift+Enter (which remove nothing) put it at the end of the first selected block’s line in document order.
- Mod+Enter only opens or closes toggles and checks to-dos (Notion); it no longer splits.
edytor.deleteBlock(id)promotes the children (deleteBlock(id, { keepChildren: false })deletes the subtree).
-
Virtual paragraph. A view reads its document through a lens:
edytor.facadeis a per-view object whose prototype isdocument.facade, andedytor.facade.virtual()names the virtual paragraph while the document shows no block (edytor.root.childrenthen holds its handle;edytor.value.childrenis empty). Every facade op the view issues on it creates it first, in the same plan. An emptied root no longer gets a replacement paragraph written by normalization. -
Dragging text (
moveText). Selected text dragged inside the editor moves to the drop point, one command and one undo step (Alt: a copy); the drag carries the range’s fragment, HTML and plain text. -
Input handlers in a test DOM. An async input handler’s failure goes to the platform’s
reportError, read only when a handler fails: a DOM emulation without it (happy-dom) types normally. -
Svelte’s async mode. The editor runs in an app compiled with
compilerOptions.experimental.async: it reads what a render would overwrite before Svelte writes it, whatever the order Svelte runs its effects in.
Plugins and the extension API
- Mention kinds.
createMentionPlugin({ kind })(defaultmention) defines one inline kind per instance, rendered and copied with itschar, with the kind indata-edytor-mentionand an HTML form that pastes back;Trigger.namenames a trigger’s menu (controller.trigger.name). - Private plumbing. A controller’s or handle’s member read only inside its own class is a
#privatefield (BlockHandleController.activateBlockandhandleKeyDown,BlockMenuController.matchingKinds, the trigger menus’activeRange,InlineBlock._defamong them). - One factory per plugin. Every bundled plugin is a factory, called with or without options (
createRichTextPlugin(),createMarkdownShortcutsPlugin(), …); the plugin constants andisImagePlugin,isSuggestionsPlugin,isColumnsPluginandisTablePluginare gone. - One list model for the chrome. The slash, trigger, language, callout, pasted-link and table menus share one list: the keyboard’s row
index,move(step),listId,rowId(index)andoption(index). - One way to write a piece. A snippet attaches what the editor needs of an element (
{@attach menu.popup},{@attach menu.option(index)},{@attach handle.grip},{@attach box.control}) and renders the payload’s values; nothing is spread. A row’s highlight is the markup’s, fromselected. - Table operations are the table plugin’s:
insertTableRow,deleteTableRows,insertTableColumn,deleteTableColumn,moveTableColumn,moveTableRowsandfillTableCellare exported fromedytorand take the document first (document.apply(insertTableRow(document, table, 1))); the table reads stay on the document. - The
detailsandhorizontalRulekinds are gone: they were other names fortoggleanddivider. - Empty image and media blocks are drawn by one plugin,
createMediaEmptyPlugin({ empty }): one snippet for every kind (controller.kind). - Uploads are each media plugin’s
uploadoption (ImagePluginOptions,FilePluginOptions,VideoPluginOptions,AudioPluginOptions): that kind’s uploader for its empty block’s Upload and its pasted and dropped files; a kind’s recordupload(KindUpload) says which files it takes and sends them. - Callout icons are their own plugin,
createCalloutIconsPlugin({ picker, icons }): the picker and the block menu’s Change icon row;createRichTextPlugin({ callout: { icon } })keeps the default icon. - Restyling a kind is a plugin listed first that names its
snippet: definitions are first-wins field by field, so the rest of the kind’s definition stays. A placeholder is a plugin’splaceholder(the first plugin that declares one).<Edytor>takes no snippet orplaceholderprop. - Input rules and triggers (
InputRule,Trigger) run through the hooks of the plugin that returnswithRulesAndTriggers(edytor, definitions, { inputRules, triggers }): its rules after its ownonBeforeOperation, its trigger menus’ keys before its ownhotkeys. The typed text goes in as typed before a rule replaces it, so the first undo gives it back. See Input rules and triggers. - Hooks run on the prepared command before any write.
onBeforeOperationsees the command, then each planned step as the operation it performs (insertBlocks,moveBlocks,deleteBlock,splitBlock,mergeBlocks,setBlockType,patchData,insertText,insertInline,deleteText,removeInline,formatRange), with the operation’s arguments aspayloadandeffecton the change.onAfterOperationfires once per command. See Refusing an edit.- A veto of any step refuses the whole command (no write, no undo step); a gesture over several blocks (Turn into, Tab, formatting, Duplicate) issues one command per part, so a veto skips only its part.
prevent(cb)or a returned command replaces it once per extension; a payload returned for a nested step is ignored with a development warning.- Nested operations and normalization are not shown as operations. Commands the document refuses are still shown (no steps), so an extension may replace them.
onDeleteSelectedBlocksruns before every gesture that removes a block selection: Backspace or Delete (a word or line delete too), a cut, the block menu’s Delete, and typing, a composition or a paste over it (Enter, Shift+Enter and a drop remove nothing, so they never run it).prevent()keeps the blocks (a cut still writes the clipboard; typing and paste insert nothing) anddispatcher.lastreportsrefused.- Operation names. Hooks see the document’s operation names with their arguments (
deleteBlocks(ids),insertFlow(target, flow)for paste and drop,deleteRange,patchData, …) and the commands ofCommands(insertDivider,moveText, …); Enter’s lift issplitBlock; markdown and slash conversions aresetBlockwith adeleteTextstep; word deletes aredeleteRangeordeleteText; handle in/out aremoveBlocksorunNestBlocks. Browser-typed text is adopted asinsertText/deleteTextand can be vetoed (the text re-renders). - Errors. Top-level operations report
refused(edytor.dispatcher.last.status) instead of throwingPreventionError; text operations refuse in readonly; a read-only (quarantined) document refuses instead of throwingSchemaMismatchError; async handler errors are reported, not swallowed.edytor.clear()is a command (one undo step, refused on a readonly view) and answers whether it applied;historyUndo()andhistoryRedo()setdispatcher.lasttoo:applied,noopon an empty stack,refusedon a readonly view. - Normalization (
normalizeContent/normalizeChildren) runs at the end of the command’s transaction, inside it, with handles that read the command’s writes (at most 51 passes per normalizer and block); its work is part of the same update and undo step. - Definitions: first wins (was last), field by field: an extension that extends another’s definition lists itself first, and a field it leaves out is the other’s.
- Kind records.
BlockDefinitiongainselement,contentElement,viewState,lines,layout,rendersContent,defaultChild,itemKind,continues,container,presets,empty,html,plain,parse;snippetis optional (schemais removed). One label per kind (Text,To-do list,Toggle list).elementandcontentElementtake a tag,{ tag, attributes }, or a function(data, id) => …of the block’s data and id (for view state a kind keeps per block; reactive state it reads re-renders the element).lines: true(withislandanddefaultChild) makes an island of lines, like the code block: its direct children show as its line kind and hold no children. A custom island of lines needs it, and an island without it keeps its children’s kinds and nesting (block roles insemanticstakelinestoo).layout: true(withdefaultChild, its column kind) makes a layout, like the columns plugin’scolumns: it shows its columns side by side, an empty column does not show, and a layout showing one column shows as that column’s blocks (block roles insemanticstakelayouttoo:layoutSemantics).itemKindon a list container names the flat kind its items show as (numbered-list-itemforordered-list): the menus name an item by it, and turning an item into it keeps the item in its list.- With
empty, a conversion turns only a block that holds nothing into the kind; a block with text or children stays and the new block is inserted after it. MarkDefinitiongainsedge,toolbar,tag,attributes,parse;InlineBlockDefinitiongainsplain.convertToKind,KindRow,KindPresetare exported;edytor.kindsis the catalogue the slash menu, markdown shortcuts and menus read.
- Snippets render inner markup. The core renders, registers and marks void the block element (
use:block.attachandBlockView.attach/InlineBlockView.attachare removed;use:block.voidstill marks inner chrome). Block snippets receiveblock: BlockView={ id, type, data, selected, focused, handle, void }; inline-atom snippetsblock: InlineBlockView={ id, type, data, selected, handle }(handleisundefinedfor a suggested atom). Document reads go throughblock.handle; writes are the view’s operations, given the ids.onBlockAttachedruns once per element, and the attach hooks may return a cleanup. Identity attributes are declarative (present in server-rendered HTML). transformTextreceives declared values{ text: { stringContent, value }, block: { id, type, data }, content }, not handles.- Marks at insertion follow one rule (explicit → a replaced range’s common marks → pending → the neighbour → the mark’s
edge);insertTextwithout marks resolves them by that rule; plain paste inherits the caret’s marks; Mod+B at the start of a bold run toggles bold off. - Presses on chrome. A press on a void block’s chrome selects the block (Shift or Mod adds it); a control there (a native control, a link, an interactive role,
tabindex,data-edytor-control,data-edytor-keep-selection) owns its whole press, keys and input; a press in a caption is the browser’s caret at the press. - Shared suggestions. The plugin
createSharedSuggestionsPlugin()and its controllersharedSuggestionsController(edytor)(SharedSuggestionsController):suggesting(suggesting mode: the view’s writes are a suggestion in the document, of text and blocks only, the rest refused with thesuggestions.notSuggestedannouncement,SuggestionsLabels),add(at, content, { via })(an AI answer written live),changes(),decide(changes, accept),acceptAll(),rejectAll();edytor.suggestions.listholdsSharedSuggestions (shared: true,by,via,changes,canDecide,mine,reject();discard()rejects it, its author’s too) beside the view-localSuggestions (shared: false),AnySuggestioneither; the commandsacceptSuggestion({ changes }for a shared one) andrejectSuggestion;SuggestedChange;adoptSharedSuggestions(document)inedytor/crdt/edytor. With them built over the document,toJSON(options?)andedytor.valueleave pending suggestions out ({ suggestions: true }keeps them). See shared suggestions. - A shared answer’s live updates. Each
updatekeeps the equal blocks and grows the last one in place (its text extended, or a code block’s lines: the last extended, the new ones added); the replaced blocks go with their children.add(at, content)writes the content at once; this view’s own suggestion is listed until its changes are decided, and added again under itsidit continues what the earlier one wrote.viais the suggestion’s record’s:undefinedfor one a member typed. - Markdown blockquotes. A blank line ends a quote (CommonMark): two quotes a blank line apart, or an alert after a quote, read as written.
- Suggestions.
edytor.suggestionsproposes content at a position, session-only untilaccept()(one command,acceptSuggestion, one undo step), with the default suggestions plugin’s keys,createSuggestionBarPlugin’s bar andtextToBlocks(Suggestions);BlockView.handleisundefinedin a suggestion’s preview. An{ end }suggestion survives selection changes.block.suggestText,block.suggestions,block.acceptSuggestedText,edytor.selection.suggestions,rawSuggestionsand the readonly Proxy wrappers are removed. - HTML import is core. The HTML paste plugin (never exported) and its hand-written parser are gone; external HTML paste and drop are imported by the core through the browser’s parser and the records (
parsehooks on kind and mark records; see clipboard). A plugin’sonPastestill runs first. The code plugin highlights through TanStack Highlight, and the package declaressideEffectsso it (and its CSS) ships only in apps that importcreateCodePlugin. - Notion behavior. See Enter and Backspace by role.
- Markdown
>makes a toggle and"a quote;+,a.,i.and inline markdown are new, and a prefix converts at the caret, keeping the text after it. - The to-do checkbox writes
data.checked. The callout’s default icon is💡(was!). Headings areh1–h3; a missing level ish1and any other renders and copies ash3. - Lists, to-dos and toggles continue on Enter; toggles, callouts and quotes are containers; Backspace at the start of a kind other than its parent’s default child turns it into that default first.
- The paragraph and code block elements no longer carry Tailwind classes.
KindPreset.groupandEditorCommand.hintare new;richTextOperations(edytor).removeMarkAtRange(mark)is new.
- Markdown
- Columns (opt-in).
createColumnsPlugin({ minWidth })andColumnsPluginOptions: Notion’s multi-column layouts (the kindscolumnsandcolumn, a column’sdata.widtha weight), not a default plugin; see Columns.- The layout commands are
columns.2…columns.5(“2 columns” …, groupLayout, found by/col3,/columns3and/column 3too), disabled inside a column. EditorCommand.turnsInto(blocks)makes a command a row of the block menu’s Turn into over those blocks (KindRow.command;turnCommands,wrappableandwrapBlocksare exported; the operation hooks seewrapInLayout): “2 columns” to “5 columns” over one block, or “N columns” over N sibling blocks.- A block selection covering every block of a layout stands for it (drag, Alt and Mod+Shift arrows, Duplicate, Delete, cut, copy).
- A drop’s beside bands (right edge, left page margin, a column’s gap) place blocks in a new column or wrap the target in a new layout; resizing is live, view-only until the release, which writes two weights in one undo step.
- Typing, a composition or a paste over a block selection in a column replaces the blocks in place.
- A mouse selection (a drag, a Shift+click) with one end in a column and the other outside that column (another column, or outside the layout) is a block selection of the blocks it covers, in reading order; the root’s
data-edytor-selection="blocks"marks a block selection, under which the native highlight is hidden.
- The layout commands are
BLOCK_ACTIVATE_EVENTis cancelable: a menu that answers a grip click and takes the keyboard callspreventDefault(); unanswered, the editor takes the focus after the click, so Backspace and Shift+arrows act on the selected block.- Default plugins.
<Edytor>appendscreateSuggestionsPlugin()andcreateRichTextPlugin(), in that order, after yourpluginsunless the list already has an instance of that factory;defaultPlugins={false}opts out. Your plugins therefore win over both (the app lists the image plugin,createImagePlugin({ upload }), block moves,createArrowMovePlugin()itself; nesting is theallowNestingoption, off by default, so Tab is then the browser’s and moves the focus on); to let a default win over one of yours, list it yourself before your plugin. - Image plugin.
createImagePlugin()(the kind and its resize handles) andcreateImageToolbarPlugin({ toolbar })are exported. Theimagekind storesdata.src, has an “Image” preset in theMediagroup, and exports and imports<figure><img><figcaption>. - Container bodies and callout icons. An open toggle’s or a callout’s empty body shows a hint whose click starts it (a drop on it nests inside); a toggle the editor creates opens; a callout is an icon, a title and a content, Enter at its title’s end going into the content; its icon (
data.icon,''for none) is picked in your picker,createRichTextPlugin({ callout: { icon } })andcreateCalloutIconsPlugin({ picker, icons }),CALLOUT_ICONS,CalloutIconPicker; labelsemptyBodyandcalloutIcon; kind records takebody. - Block colours, toggle headings, page block, table of contents. Blocks store
data.coloranddata.background(palette names the block menu’s Color sets, rendered asdata-edytor-color/data-edytor-backgroundand painted from--edytor-color-<name>/--edytor-background-<name>;BLOCK_COLORS,setBlockColor); the rich texttoggle-headingkind (Toggle heading 1 to 3, markdown>in a heading and#in a toggle, throughKindPreset.markdownFrom);createPagePlugin(a voidpagelinking to another document) andcreateTocPlugin(a voidtoclisting the headings), their roles indefaultSemantics. - Tables.
createTablePlugin(opt-in): rows and columns added from the table’s edges, moved by dragging their grips or from the grips’ menus, deleted from those menus; columns resized within the room at the table’s place, a wider table scrolling sideways in its own box (Table). - Media plugins.
createEmbedPlugin({ providers }),createBookmarkPlugin({ unfurl }),createFilePlugin(),createVideoPlugin()andcreateAudioPlugin()add voidembed,bookmark,file,videoandaudiokinds (opt-in,Mediapresets, roles indefaultSemantics/mediaSemantics).- Exports:
EMBED_PROVIDERS,embedSourceOf,EMBED_SANDBOX,EMBED_ALLOW,safeWebUrl,safeMediaSrcand the typesEmbedProvider,EmbedPluginOptions,BookmarkPluginOptions,BookmarkPreview. - An embed’s frame plays only an allowlisted provider’s
https:player, sandboxed, neversrcdoc. With the embed or bookmark plugin, a URL pasted on an empty line is a link and a menu offers Embed or Bookmark. - HTML import maps
iframe,videoandaudiowhen one of them claims them; a void kind with aparsehook is found by its hook only and takes only itsfigcaption’s text.
- Exports:
- Headless chrome. The package draws no menu, popup, handle, panel or card: each surface is a snippet option of its plugin, and without it the surface renders nothing while its controller works.
createSlashMenuPlugin({ menu }),createToolbarPlugin({ toolbar, card }),createBlockMenuPlugin({ menu })andcreateBlockHandlesPlugin({ handle }), with the typesSlashMenuOptions,SlashMenuController,ToolbarOptions,ToolbarController,BlockMenuController,BlockMenuAction,BlockHandleSnippetPayload(beside: Alt+click adds a column right of a column block’s;haspopup) andBlockHandleController; theslashMenuPlugin,toolbarPlugin,blockMenuPlugin,findPluginandblockHandlesPlugininstances and theblockHandlesprop are gone. The Notion-style markup is the ready-made menus. The toolbar and block menu place the element markeddata-edytor-toolbar-bar/data-edytor-block-menu(was theirdata-testid). A press in the toolbar’s host never takes the editor’s focus (itsmousedownis cancelled but in a field), so a toolbar snippet’s buttons need nomousedownhandler. - Controls inside blocks. The package draws a to-do’s checkbox, a callout’s icon, an empty body’s hint, an equation’s placeholder and error, a bookmark’s card, a file’s row, an unplayable embed’s link, a table of contents’ entries and a page block’s link; each plugin option takes your snippet in its place (
checkbox,calloutIcon,emptyBody,placeholder,error,card,row,fallback,entry,empty,link), typed by its payload (TodoCheckboxPayload,CalloutIconPayload,EmptyBodyPayload,EquationPlaceholderPayload,EquationErrorPayload,BookmarkCardPayload,FileRowPayload,EmbedFallbackPayload,TocEntryPayload,TocEmptyPayload,PageBlockLinkPayload), whoseattributesorlink(ControlAttributes,MediaLinkAttributes) carry the marker, the ARIA and the action.createFilePlugintakesFilePluginOptions. - Chrome snippets with the keyboard and the ARIA. Every surface is a snippet option of its plugin, typed
Snippet<[Payload]>with one exported object payload, its controller (a controller’s rows areMenuItemPayloads,{ item, id, selected, run, select, option }).- The controllers’ attachments carry the keys and the ARIA:
popup,keys,option(index), the block menu’sflyoutMenu, the toolbar’slinkField(an id unique per editor), the image toolbar’sbarandaltField, an empty block’sfield. - The options: the slash menu’s
menu, a trigger’smenu(mention, page link), the block menu’smenu, the toolbar’stoolbarandcard, the embed and bookmark plugins’menu(the menu a pasted URL opens, named by the root),createMediaEmptyPlugin’sempty(every empty image and media block),createImageToolbarPlugin’stoolbar,createCalloutIconsPlugin‘spicker, the comments’card(CommentCardPayload, a thread or the one being written) andheader,createSuggestionBarPlugin’sbar(withmac), the find bar, the marquee’sbox. The version history is a controller,VersionHistory. - Types:
OptionAttributes,UrlPasteController,UrlPasteOption,UrlPasteOffer,ImageToolbar,ImageControls,ImageBox,MediaEmptyController,MediaEmptyFailure,MediaKind,KindUpload. - The table’s
grip,menuandadd(TableGripPayloadwith itsgripattachment,TableChromewithitems,popup,keys,option(index),TableAddPayload); the code block’sheaderandmenu(CodeHeaderwith itsbuttonattachment,LanguageMenuwithitems,keys,popup,option(index)); the equation’spanel(EquationEditorwith itsfieldattachment); the block handle’sexpanded,controls,haspopup,besideandadd(alt, anchor). Types:TableChrome,TableMenu,TableMenuRow,TableMenuItem,TableGripPayload,TableAddPayload,CodeHeader,LanguageMenu,LanguageMenuItem,LanguageRow,EquationEditor,EquationTarget. - A table grip’s menu is a WAI-ARIA menu that holds the keys (arrows over the items that can run, Home/End, Enter, Escape) and is named by the editor’s root; grips,
+bars and menus stand in hosts ([data-edytor-table-grip-host],[data-edytor-table-add-host],[data-edytor-table-menu-host]).
- The controllers’ attachments carry the keys and the ARIA:
- Heading and quote block elements are
divs. The rich textheadingandquoteused to render as the block element itself (<h2 data-edytor-block … data-edytor-type="heading">,<blockquote data-edytor-block …>), with nested blocks inside the tag. The block element is now adiv; theh1–h3orblockquoteis the kinds’ newcontentElement, which wraps only the block’s own text, and nested blocks follow it in a siblingdiv. The copied HTML is unchanged.- Rewrite selectors:
h2[data-edytor-type='heading']becomes[data-edytor-type='heading'] > h2,blockquote[data-edytor-block]becomes[data-edytor-type='quote'] > blockquote; drop resets for adivinside a heading, and a test locatingh1[data-edytor-id=…]locates[data-edytor-id=…] > h1. - A plugin that restyles
headingorquotekeeps the tag:content()renders inside it.
- Rewrite selectors:
- Slash menu, hotkeys and the code plugin.
- The slash menu opens only at the start of a text or after whitespace, matches word prefixes of labels and keywords, claims Enter only with a match, and closes when a non-empty query matches nothing or the query starts with a space.
- A replacing kind (divider, image, code) converts a block in place only when the block holds nothing but the slash query, and is otherwise inserted after it.
- A hotkey whose value is not a function is skipped with a development warning.
- The code plugin’s Shift+Enter runs
insertParagraphas an intent, its auto-pair is a returned payload (after-hooks see the typed character), and a typed closer steps over the same character.
- Links. A URL typed before a space, or pasted at a caret, becomes a link as an undo step of its own; Mod+click opens a link in a new tab; Mod+K opens the toolbar’s link panel, and hovering a link shows your link card (
createToolbarPlugin({ card }): Open, Edit, Remove).richTextOperationsgainslinkTextandunlinkText;ToolbarControllergainsopenLinkPanel,closePanel,takeFieldFocusandhovered. See links. - Pasted page links.
createPageLinkPlugin({ fromPaste })turns a pasted one-line text your app recognizes (its URL for a page,page:roadmap) into a page link, at once or when a promise answers, an undo step of its own that gives the text back; it wins over the pasted link and the URL menu for the texts it recognizes. - Code languages.
createCodePlugin({ languages, defaultLanguage }),CODE_LANGUAGES,loadCodeLanguage,CodeLanguageandCodePluginOptionsare exported; a code block’s language is itsdata.language(JavaScript when unset), picked in your header (its button opens your searchable list of the languages, reached from a code line with Alt+F10), and its lines are highlighted with that language’s grammar, loaded the first time one renders. See languages. - Equations.
createEquationPlugin({ katex, macros, panel }): a block equation (equation, void, indefaultSemanticsasequationKinds) and an inline equation atom (inlineEquation), TeX drawn by KaTeX loaded on demand (from jsDelivr by default,KATEX_VERSIONatKATEX_CDN; or from a URL, or your bundle through a loader,katexbeing an optional peer dependency), edited in a field under the equation with a live preview; slash commands,$$…$$, Mod+Shift+E; MathML on copy, KaTeX and MathML read by HTML import.InlineBlockDefinitiontakeshtmlandparse. - Marquee selection (opt-in).
createMarqueePlugin({ container, threshold, box }),MarqueePluginOptionsandMarqueeBoxPayload: a rectangle dragged from the editor’s empty area selects the blocks it touches, live (Shift or Mod adds, Escape restores, auto-scroll near the edges); see Marquee selection. - Localization. The package’s own words (kind and command names, placeholders, announcements, its own elements’ accessible names) come from one dictionary,
Labels, English by default (englishLabels);<Edytor labels>replaces any entry of any section and the commands’ slashkeywordsby id. The chrome’s words are the app’s markup (Localization). data-edytor-keep-selection. A press outside the editor and its overlay ends a block selection unless Shift or Mod is held or the press is inside an element carrying this attribute.
Rendering, placeholder and chrome
-
The shadcn-svelte registry at
https://edytor.dev/r/:starter(StarterEditor: every bundled plugin, the ready-made chrome, comments, the page’s cover, icon, title and properties in the document’s data, dates in alocale, hidden properties kept) andedytor-chrome(the ready-made chrome’s plugins, snippets, words andHistoryPanel), on the app’s shadcn tokens. -
Baseline 2024 browsers. Chrome and Edge 120, Firefox 125, Safari 17.4 and Chrome on Android 120 are the oldest supported (they were 111, 119 and 16.4 as floors the code happened to need); code kept only for older engines is gone.
-
A placeholder is a plugin’s
placeholder(the<Edytor placeholder>prop and option are removed): a string or(view: { type, data, focused, empty }, edytor) => string | null; the snippet form is gone. It renders asdata-placeholderon the empty text element with a shipped::beforerule (style[data-placeholder]::before);[data-edytor-text-placeholder]and its click handlers are gone.edytor.placeholderRepairis removed. -
Chrome lives in
[data-edytor-overlay], a sibling after the host: block handles (in document order), the drop indicator (position: absolute, not indocument.body), menus (position: fixedinside the layer) and layer-relative remote carets.--edytor-handle-offset-yis gone.edytor.overlay(layer,add(measure),mount(…),invalidate()) is new. -
A key’s view work does not grow with the page. Each block’s selected and focused attributes follow that block alone; the DOM observer checks the nodes a change added to the page, not every block; the block handles, the suggestion bars and the overlay’s resize watch look only near the screen. A character, Enter, a move or a caret moving between blocks does the same editor work at 5,000 blocks as at 1,000 (what still grows is the browser’s, see Long pages).
block.nextBlock/previousBlockanswernullpast either end. -
Fewer render markers. A block’s render leaves few of the renderer’s anchors in the host (a paragraph: 9 empty comments and one empty text node, where it left 23, 9 and a whitespace text node; a long page of mixed kinds about 11 nodes a block, where it left 34) and no whitespace text between tags, which the browser walks after every key. A block’s
textContenthas no space between its own text and its nested blocks’. -
Typing, formatting, Tab and block moves never remount the element under the caret; a moved block’s element is re-created where it moved.
edytor.cellsis new (the view’s render cells);refreshEditorDom/editorDomRevisionare removed. -
The DOM observer restores what the editor owns and leaves an extension’s markup around the slots alone: a foreign node inside a block’s text run is removed, a node beside it stays; foreign text inside a content is adopted; attributes the core does not own (an extension’s
idon a block element,openon a toggle) are never reverted. A foreign delete across blocks (an extension’s or a script’sRange.deleteContents()) gives back the render’s markers it took between and inside the blocks, so the blocks’ later changes render. -
A kind’s own control (any form control or nested editable inside a block) owns its keys,
beforeinput, paste, copy, cut and drops, even over a block selection; the editor never writes its caret over a focused form control.patchDatawrites join one undo step only when they type into the same string properties (one run inserted or deleted); a string set to another value, such as a status, is its own step. -
A “
[data-edytor-block]exists” check no longer means hydrated; wait for a registered text element. -
A block suggestion’s preview renders inside the host as
[data-edytor-suggestion](non-editable,data-status), its blocks withdata-edytor-blockanddata-edytor-typebut nodata-edytor-idor text elements. Select live blocks with[data-edytor-id]. The Notion theme styles them (--edytor-suggestion-*).- A
replacemarks its blocksdata-edytor-suggestion-replaced(="empty"when they all hold nothing: folded, the preview in their place) and a replaced text range with[data-edytor-suggestion-range]rectangles in the overlay, where your bar ([data-edytor-suggestion-bar]) lives too.
- A
-
Block handles in layouts. Layouts and columns have no handle; a block in a column has its
+and grip in the gap, right of the column resize band (the gap’s left 10px, the layout’s height, above the handles). A handle’s box covers its block’s row. The handle column left of the blocks’ text reorders (before or after the row at the pointer’s height, never inside; a container list is one row there). Past it, and right of the blocks, a drag still drops on the row at the pointer’s height up to--edytor-drop-reach(240px; with a layout kind the first 120px are the beside bands); past the reach nothing drops. While a text selection is dragged, handles and resize bands take no pointer (data-selecting). The block menu’s Turn into flyout stays in the viewport ([data-edytor-block-menu-flyout]). -
Block handles on a touch screen. With no hover, the handle of the block the selection is in shows (Notion’s mobile editor), and a hidden handle takes no tap; a touch on another block reveals none.
-
autocapitalizeis unset by default (it was'none'): a phone’s keyboard capitalizes sentences. -
A touch press keeps the platform’s selection. A tap’s caret and a double tap’s word are never re-placed at the pointer; a mouse or pen click still is.
-
An empty block holds a
<br>. A text alone in its block renders a<br>when empty (itstextContentis''), so iOS capitalizes its first letter; an empty text beside an atom or an inline suggestion keeps the zero-width space, and a composition started in an empty block composes into a zero-width text node the editor renders at its start. -
Keys on iOS’s software keyboard. A key the keyboard announces after its key press (Return, Backspace at a block’s start) runs once. A block selection sets the root’s
inputmodetonone(no virtual keyboard over selected blocks), over theinputmodeprop. -
Chrome on a touch screen. What a hover reveals inside a block shows on a touch screen instead (the code block’s Copy, an icon-less callout’s
+): a tap that reveals content is a hover only on iOS Safari. The ready-made menus keep below the root’sscroll-padding-top(a sticky header). -
Long words. The editor sets
overflow-wrap: anywhere(no specificity): a word longer than the line breaks anywhere and never widens an editor in a flex or grid layout. -
A kind’s element (
element) is the block element and wraps its children;contentElementwraps only its own text (content()), and a snippet override keeps both. The rich text heading is adivholding anh1–h3, a quote adivholding ablockquote, their nested blocks after that tag: style[data-edytor-type='heading'] > h2, noth2[data-edytor-type='heading']. -
Marks by tag. A mark record declares
tag(andattributesfrom its value); the core renders the tag itself as the mark element (<strong data-edytor-mark="bold">, was<span data-edytor-mark="bold"><b>), and the clipboard exports the same element.MarkDefinition.htmlis replaced bytag/attributes;snippetis optional (a snippet still renders inside a core<span data-edytor-mark>). Selectors such as[data-edytor-mark="link"] abecomea[data-edytor-mark="link"].- Built-ins: bold
strong, italicem, underlineu, strikes, codecode, linka(sanitizedhref,target), superscriptsup, subscriptsub, color and highlightspanwith a sanitizedstyle.
- Built-ins: bold
-
Looks are the theme’s. The plugins’ stylesheets keep what makes their blocks work (layouts, scrolling, the frame sizes, what is never selected, where the overlay’s cues stand and when they show); the code panel and syntax colours, a table’s borders and padding, the equations’, the callout’s, the page block’s, the table of contents’ and the atoms’ looks, and the overlay’s drop lines, backdrop, resize guides, image pills and other users’ carets (each in
--edytor-remote-color) are the Notion theme’s. Atoms mark their selectiondata-selected="true". -
--edytor-trailing-space. The root has a bottom padding (2emby default, no specificity) where a click puts the caret in a trailing paragraph. See styling. -
edytor-long-page. The class on the editor or an ancestor gives top-level blockscontent-visibility: autoandcontain-intrinsic-block-size: auto 32px, under any theme (it replaced the Notion theme’s--edytor-block-visibility); the block handles and remote carets measure a skipped block through its nearest rendered ancestor. -
Drag and drop without dependencies. The block handles and table grips run Atlassian’s Pragmatic drag and drop from a copy inside the editor (the element adapter, its drag preview, the list item hitbox and the auto-scroll), no longer from its packages.
Collaboration and providers
- Presence wire.
selections[viewKey] = { start, end, collapsed, reversed, t }for text (DocAnchors),{ blocks, t }for a block set,{ atom, block, t }for an atom; the legacyselectionmirror,startTextId/yStartfields and numeric fallbacks are gone. A view writes only its own key and clears it on destroy.publishPresencereplacescreateAwarenessSelection/publishAwarenessSelection/clearAwarenessSelection;attachDocumentSyncis removed (usedocument.attachSync). A lost socket clears remote carets in that tab only. - Who is online.
edytor.presence.peers(PresencePeer): the other clients by client id,{ clientId, …user }, reactive, listening only while read. - Presence throttle default. A view writes its presence at most once every 50 ms (
DEFAULT_PRESENCE_THROTTLE; it was0, every change):presence={{ throttle: 0 }}restores every write. - Presence cost. The
presenceprop ({ share: 'caret' | 'block' | 'none', throttle },edytor.presence,PresenceWriter) throttles a view’s presence writes and can share only the focused block or nothing; peers sharing blocks are drawn as a bar beside them ([data-edytor-remote-block]), and a client’s freshest entry wins whatever its kind (presence). createWebsocketSynctakesserver,room,params,maxBackoffTime,connectTimeout,onExpired,WebSocketPolyfill,disableBc,persistandpersistName(connect,protocols,resyncInterval,serverUrlandroomNameare removed).- It persists locally by default: an IndexedDB store beside the socket (
persist: falseopts out,persistNamerenames it fromedytor:<server>/<room>; the returned sync’spersistNameis the name to pass toclearDocument), skipped where there is noindexedDB, attached through the newEdytorSyncPayload.attach. While the store exists it carries the cross-tab channel;disableBcturns both off (IndexeddbPersistencegains adisableBcoption). connectTimeout(default 10 000 ms,Infinityfor no limit) closes a dial that neither opens nor fails, like a failed one.- The room name is percent-encoded into one path segment of the URL (
encodeURIComponent), so a server that routes on the raw path must decode it:acme/roadmapdials…/rooms/acme%2Froadmap. An id a URL cannot carry ('',.,.., over 256 characters, or with a lone surrogate) throws aTypeErrorat construction. onExpired(state)runs on each4401close ({ reason, attempts, nextRetryMs }): put a fresh token inparamsbefore the redial.
- It persists locally by default: an IndexedDB store beside the socket (
WebsocketProvider: removed theprotocolsoption and field (pass tokens inparams, read at every dial), thesyncevent (usesynced),wsconnecting(thestatusevent carries it) and the settle window (syncSettleMs).resyncIntervalstays a provider option only. The BroadcastChannel leg stays and is on by default (disableBcopts out); it relays other tabs’ edits to the server. New:saved,unsavedand the'saved'event (the room’smessageSavedacknowledgements), andreadOnly(trueonce the room’s read-only notice arrives, with no event; a read-only socket counts nothing as unsaved, so checkreadOnlyto learn that edits were never stored: see saved state);messageChunkreassembly;- the
refusedevent (aSyncRefusedErroron a1008close or a4xxxclose other than4401, after which it stops dialing), theexpiredevent (a4401close: expired credentials; the provider redials after the backoff with the re-readparams) and theunreachableevent (the backoff cap grows to 30 s after 8 dials that never synced); - the
connectTimeoutoption. - A room fault (
1011) after a sync also grows the backoff, until the room acknowledges every local update again. The provider sends a textpingafter 15 s of silence, and a textpongcounts as liveness.
- Readiness. The document decides readiness itself:
syncFailed,onSyncSettledandEdytorDocSyncPendingErrorare gone;whenSyncedexists on both providers andsyncedis the lifetime claim.- A lone first client is ready after
DEFAULT_READINESS_BOUND(1 s, per factoryEdytorSync.bound;createWebsocketSyncarms it from the socket’s open or first failed dial through the newEdytorSyncPayload.armBound);historyrefuses whilepending. - A refusal never seeds:
document.syncRefusalanddocument.onSyncRefused(fn)are new. A refusal belongs to the provider that reported it: releasing that provider, or its next sync, lifts it. - A sync factory’s payload carries
EdytorSyncPayload.failed(error, provider)besidesynced: the provider’s terminal failure, reported once when it never synced (destroyed before any handshake, refused, or denied). EdytorSyncPayload.holdBound()stops a provider’s bound until the nextarmBound(): a4401before the first sync holds it, so an empty document waits for a dial that gets in instead of seeding.
- A lone first client is ready after
- Access.
EdytorDocument.access(DocumentAccess:'write','suggest','comment'or'read', what the room said as the document joined, and at a change in place);EdytorSyncPayload.access(level), called bycreateWebsocketSyncfrom theWebsocketProvider’s newaccessevent; asuggest-onlypermission-deniedis not a failure. The comments plugin lets acommentorsuggestuser comment from a read-only view (CommentRequest’sanchors,CommentActor.anchors: the room writes the anchor). - One provider per target.
EdytorSync.target(indexeddb:<name>,websocket:<server>/<room>); attaching a target already attached is a no-op returning nothing; attaching on a destroyed document throwsDocumentDestroyedError. - Admission. Unversioned content is not refused at ingress: the document is read-only and quarantined until admission accepts it (
document.writable,onWritableChange). IndexeddbPersistence:get/set/delare removed (thecustomstore holds only the generation record).- Provider listeners.
IndexeddbPersistenceandWebsocketProviderkeep one_unlisten(their document and presence listeners’ teardown) instead of_storeUpdate,_updateHandlerand_awarenessUpdateHandler. - SSR.
<Edytor>releases the document it created inonDestroy, which also runs after a server render. - First paint from a snapshot.
EdytorProps.snapshot(JSONDoc, rendered read-only inside[data-edytor-snapshot]while the document is pending);documentSnapshot(options: LastUpdatedOptions): Promise<JSONDoc | null>(package root,edytor/collaborationandbindCrdt(Y).providers);routeDocumentSocketanswersGET <room>?snapshotand the room’sPROBE_HEADERtakessnapshot({ lastUpdated, document },503while the room has no document). - Offline coverage.
prefetch(options: PrefetchOptions): Promise<PrefetchResult>andlastUpdated(options: LastUpdatedOptions)(package root andbindCrdt(Y).providers);DocumentOptions.requireHydration,EdytorDocument.requireHydration,EdytorOptions.requireHydrationand the<Edytor requireHydration>prop; the room’slastUpdated()(RPC), itsmetatable andPROBE_HEADER;routeDocumentSocketanswersGET <room>?lastUpdated. - Outbound chunking.
WebsocketProviderandcreateWebsocketSynctakemaxFrameBytes(defaultMAX_FRAME_BYTES) and chunk larger frames; the room readsmessageChunkinbound (closing1011chunk sequence loston a part without a start). The image plugin exportsMAX_INLINE_IMAGE_BYTESandstorableImageSrc.
The room (edytor/cloudflare)
edytor/cloudflare(new).DocumentRoom,attachRoomandrouteDocumentSocket(request, namespace, documentId, authorize)replace the coordinator you wrote yourself; see the room.- The entry also exports
AttachedDocument(whatattachRoomreturns: the socket handlers plustransact,read,compact,dropWaitingDeletes,resetand the diagnostics; forward the ones you call over RPC),SOCKET_TAG,noTimers,ROOM_ORIGIN(the origin of the room’s own edits),IDENTITY_HEADERS, the defaultsDEFAULT_MAX_ROW_BYTES,DEFAULT_COMPACT_AFTERandDEFAULT_SAVE_AFTER, and the capsMAX_REFUSALSandMAX_WAITING_DELETES(the delete ranges the room keeps waiting for items it does not hold). - Its types:
AttachRoomOptions,Attachment,DocumentRoomEnv,LoadedDocument,Refusal,ReplicaOwner,SavedDocument,SocketIdentity,AuthorizeDocumentSocket,ExpiredCredential,DocumentNamespaceandDocumentIdentity. requestedReplica(request)reads the dial’s client id forauthorize, andclosedSocket(code, reason)turns a dial away from your own Worker with a close the provider understands (an HTTP error reaches the browser as1006, which it redials forever).- The room binds
{ user, replica, readOnly }to each socket, strips the content of updates under another user’s client ids, and appliesdefaultSemanticsto server edits. - Access levels.
DocumentIdentity.access(DocumentAccessLevel:read,comment,suggest,write), carried byX-Edytor-AccessandSocketIdentity.access; the room tells each socket its level as it joins (the auth messagemessageAccess,writeAccessinedytor/protocol). Asuggestsocket’s frames keep only suggestions (refusalsuggest-only); acommentsocket’s comments get their anchor from the room; restores needwrite.setAccess(user, level)takes every level and'none'.
- The entry also exports
Close codes the room and its router send (the CLOSE table; see the room for each reason), and what the provider does:
| Code | When | The provider |
|---|---|---|
4400 |
An empty document id, ., .., one over 256 characters or one with a lone surrogate (authorize is not called). |
Stops. |
4401 |
authorize returns { expired: true } (ExpiredCredential), or the expiresAt it returned passed. |
Redials, reading params again. |
4403 |
authorize returns null or an invalid identity (a userId empty, not a string, over 256 characters or with a lone surrogate, an invalid replica), the page’s origin is not in allowedOrigins, or the room revoked the user’s access (closeUser, setAccess(user, 'none')). |
Stops. |
4409 |
A replica id another user holds. | Stops. |
4410 |
The room re-seeded the document, or cannot rebase it (an epoch past the cuts it keeps, or a later one), or the socket sent an older epoch’s content; the reason is the room’s epoch. | With unsaved edits, dials once more to hand them over; then stops (a refusal of the document) and createWebsocketSync deletes its local copy. |
4413 |
A room quota (quota: document, quota: rate, quota: frame): the write is not applied. |
Stops. |
1008 |
refused: <reason>: a frame of another generation (generation), a replica the dial does not own (replica), a forged schema stamp (schema), undecodable bytes (malformed), a socket the room holds no user for (identity), a stored document the room refuses (container), or a dial naming no epoch to a room that re-seeded (epoch). |
Stops. |
1011 |
A fault of the room itself (storage failure, internal error, room busy, room unavailable). |
Retries, backing off while it repeats. |
1012 |
access changed: the room changed the user’s access level (setAccess), other than a writer’s down to read. |
Redials at once. |
- Room compaction. The room’s compaction stores the live document (
encodeStateAsUpdatewithout what waits), never a merge of the stored updates, and keeps a deleted text’s content while a delete record holds it (no collection rule of its own:bindCrdt(Y).doc.keepCopiescame and went).bindCrdt(Y).admission.admitUpdatetakes several updates (applied in one transaction) and{ prepare }. - Compressed snapshots. Every stored record holds an update in the one encoding; snapshots (room compaction, the IndexedDB store’s
storeState) are gzip-compressed (CompressionStreamis required). The generation record isGenerationRecord(engine,protocol,schema), with no storage format. An IndexedDB row is anArrayBuffer. The room’srecords(kind?)returnsStoredRecords,{ kind, record, bytes }(a compressed snapshot inflated) andcompressed()is new (also over RPC). - Room quotas.
maxDocumentBytes,maxUpdatesPerSecondandmaxInboundFrameBytes(EDYTOR_MAX_DOCUMENT_BYTES,EDYTOR_MAX_UPDATES_PER_SECOND,EDYTOR_MAX_INBOUND_FRAME_BYTES; defaultsDEFAULT_MAX_DOCUMENT_BYTES,DEFAULT_MAX_UPDATES_PER_SECOND,DEFAULT_MAX_INBOUND_FRAME_BYTES); a write past one closes its socket4413(CLOSE.quota; the close-code tableCLOSEis now exported fromedytor/crdt/edytor), refusal reasonquota.createChunkReader(maxBytes?)throwsChunkLimitErrorfor a sequence announcing more. - Document size warning.
documentWarning(EDYTOR_DOCUMENT_WARNING, defaultDEFAULT_DOCUMENT_WARNING, 0.8): the room logs{ edytor: 'size', bytes, limit, share }once when the document reaches that share ofmaxDocumentBytes;metrics()reportsdocumentLimit. - Room validation.
AttachRoomOptions.validate(frame)andDocumentRoom.validate, with aFrameValidation:{ user, replica, touched, dataChanged, before, after, facade },before/afterreturning aValidatedBlock({ id, type, data, content, parent }) ornull;falseor a throw denies, and the room undoes the frame (refusal entrydenied). Per-writer marks of another writer are stripped (refusal reasonmark).um.clear()drops every step of a historycreateUndoManagermade and releases what they kept, by the history limit’s rule. - Room metrics and log.
metrics(),RoomMetricsandTiming; thelogoption,DocumentRoom.log,RoomLogEntryandEDYTOR_LOG. - Re-seeding. The room rebuilds a document that grew from its content as a new epoch (the
reseedoption,ReseedOptions,DocumentRoom.reseeding(),EDYTOR_RESEED,reseed(),epoch,metrics().epoch, theDEFAULT_RESEED_*defaults, thereseedandrebaselog entries); the dial names the document’s epoch (epoch=), the room answers an earlier one withmessageEpochand reads itsmessageRebase, admits what the rebase writes as the user’s update, and closes4410(CLOSE.reseeded);createWebsocketSyncdials once its local copy has loaded and deletes it after a re-seed;<Edytor>builds itself again on a new document. See re-seeding. - Version history. The room keeps two versions a day (first in a KV namespace; see the history stores below): the
historyoption ofattachDocument(HistoryOptions:{ store, retentionDays, timeZone, maxValueBytes }),DocumentRoom.history()(theEDYTOR_HISTORYbinding withEDYTOR_HISTORY_RETENTION_DAYSandEDYTOR_HISTORY_TIME_ZONEby default);DEFAULT_RETENTION_DAYSandHISTORY_MAX_VALUE_BYTES. See History and purge.- The room’s
listHistory()(HistoryEntry[]),readHistory(key),restoreHistory(key, { user })(RestoreResult, originRESTORE_ORIGIN),undoRestore({ user })andhistoryWritten(), also over RPC, androuteDocumentHistory(request, namespace, documentId, authorize)for HTTP. - Refusal reason
history;RoomMetrics.history; log entrieshistoryandrestore.bindCrdt(Y).doc.restoreTo(doc, facade, json)is the restore itself.
- The room’s
- History stores.
HistoryOptions.storetakes aHistoryStore(maxValueBytes,nativeTtl,put(key, value, { expiresAt, metadata }),get(key),list(prefix, cursor)ofHistoryStoreRecords,delete(key)), or aHistoryStoreFactoryover the room’s storage (HistoryRoomStorage); a KV namespace (KVLike) goes throughkvHistory.- Adapters
kvHistory(namespace),r2History(bucket)(anR2BucketLike) androomHistory({ maxBytes, maxValueBytes }), withR2_HISTORY_MAX_VALUE_BYTES,ROOM_HISTORY_MAX_BYTESandROOM_HISTORY_MAX_VALUE_BYTES;HistoryMetadatais exported;HistoryEntry.expiresAt. EDYTOR_HISTORYtakes a KV or R2 binding or"room"; the alarm’sretentiontask deletes expired versions.
- Adapters
- Concurrent creations of one id. The losing node of a concurrent creation of one block id keeps its subtree (
isKeptReplacedexported fromedytor/crdt,Doc.keepReplaced), and its text shows at the end of the winner’s (an implicit merge claim);insertBlocks,splitBlockand pastes refuse an id holding U+0000. - Merges are items of the text. A merge claim is one item
{ m }at the end of the stream of the block it joins, so a concurrent split leaves it in the split’s last piece (MergeClaimis{ m },Claimis{ m, stamp }); a record’sclaimsare its implicit ones (TextBlockRec.implicit), then the claim items of its stream. The text binding’sclaimInto(own, from, into),splitAt(doc, …)anddeleteClaims(doc, claims)write them. - Comment quotas.
CommentOptions.maxBytesandmaxRequestsPerSecond(EDYTOR_MAX_COMMENT_BYTES,EDYTOR_MAX_COMMENT_REQUESTS_PER_SECOND; defaultsDEFAULT_MAX_COMMENT_BYTES,DEFAULT_MAX_COMMENT_REQUESTS_PER_SECOND),COMMENT_ROW_BYTES,commentBytes,decideComment’sbytesandmaxBytes, the refusal reasoncommentsand the429ofrouteDocumentComments. - Per-block locks.
lockedBlocks(options)andLockOptions(key,subtree,bypass); thelocksoption ofattachDocument,DocumentRoom.locks()and theEDYTOR_LOCKSvariable. - Cross-document moves.
moveBlocksBetweenRooms(namespace, move)andforwardLateEdits(namespace, from); theroomsoption,DocumentRoom.rooms()and theEDYTOR_ROOMSbinding;DEFAULT_MOVE_GRACE_DAYS. See moving blocks between documents.- The room’s
exportBlocks(ids),importBlocks(request),commitMove(moveId, receipt),abortMove(moveId),lateEdits(),ackLateEdits(moveId, seq)andapplyLateEdits(batch), also over RPC. - The types
MoveNamespace,MoveRoom,MoveDestination,ExportedBlocks,ImportRequest,ImportReceipt,CommitResult,LateEdit,LateEditBatchandMovedState. - Log entries
moveandlate; the alarm’sforwardtask; tablesmovesandlate.
- The room’s
- Purge. The room purges content deleted before its horizon (
purgeAfterDays,EDYTOR_PURGE_AFTER_DAYS; default the retention, else 30 days) as its own transaction (originPURGE_ORIGIN). A document’s histories drop the steps below the horizon.bindCrdt(Y).doc.purge(doc, facade, horizon)(PurgeReport;horizonnullpurges what closed sessions released alone) andbindCrdt(Y).doc.horizonOf(doc); the room’spurge()(also over RPC),RoomMetrics.purgeand thepurgelog entry (horizon: nullfor a run with no epoch due,releasedthe release records it dropped).- A session whose page closed (
document.endHistory()) has its deletes purged at the next tick, whatever their age. - A suggestion decided before the horizon loses its record and decision trail (
PurgeReport.suggestions,RoomMetrics.purge.suggestions); a restore rejects the pending suggestions. - The room’s alarm runs
onSave, the history and the purge, each due time stored;attachDocumentinstallsalarmunless none applies; thenowoption andDocumentRoom.now()set the room’s clock.
Migration
- The v13 import (
bindCrdt(Y).migrationand its types,isLegacyDoc,UnsupportedDocError’s reasonlegacy) is removed: a v13 document’s JSON, exported with 0.0.11, creates the document.