Skip to content
Edytor
Esc
↑↓navigate↵open⌘Jpreview
On this page

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), insertFlow of 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. fromMarkdown and textToBlocks read > a, a blank line, then > b as one quote (b its 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 update of 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 the status you pass). Your own suggestion stays listed until its changes are decided: added with no content (or []), it waits for an update. Added again under its id, it replaces what the earlier one wrote instead of writing beside it.
  • A suggestion a member typed has no agent. via read 'ai' for every suggestion this view did not add, those typed in suggesting mode included. It is now the suggestion’s own: undefined unless an agent wrote it.
  • A shared answer’s code block grows in place. A live update that 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 global reportError at 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: autocapitalize is unset by default, so iOS and Android capitalize the first letter after a period or a Return, as in Notes or Notion. Pass autocapitalize="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, its textContent is 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-top says 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, set reseed: false (EDYTOR_RESEED=off).
  • The dial names the document’s epoch. The provider’s URL carries epoch=<n> (epoch=new for a document that holds nothing yet) after replica, before your params (a param of yours named epoch does not replace it). A host Worker that builds its own upgrade request must keep the dial’s query string; routeDocumentSocket forwards the request’s URL.
  • With a local copy, the socket dials once the copy has loaded. createWebsocketSync opens 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 4410 refusal of the document. When the room re-seeds, every socket is closed 4410, its reason the new epoch; a provider with unsaved edits first dials once more to hand them over. Then the provider stops and reports a SyncRefusedError with code 4410 (refused, onSyncRefused, document.syncRefusal), and createWebsocketSync deletes its local copy. <Edytor> that owns its document builds itself again on a new one; if you pass your own document, create a new one when onSyncRefused reports 4410. The room also closes 4410 a 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.base takes a reader. The shared suggestions’ base view, which toJSON() reads, is now base(read): it builds the document without its pending suggestions and answers what read reads of it. A part built over a facade that set base passes 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, validate and the locks hold), its pending suggestions dropped; the users’ names and colors come along. The reseed option (ReseedOptions: at, idleMs, gain, force, graceDays; false never re-seeds; defaults DEFAULT_RESEED_IDLE, DEFAULT_RESEED_GAIN, DEFAULT_RESEED_FORCE, DEFAULT_RESEED_GRACE_DAYS), DocumentRoom.reseeding() and EDYTOR_RESEED; reseed() (also over RPC) runs one now; the room’s epoch and metrics().epoch; the reseed and rebase log entries, the refusal reason epoch, the reseed alarm task and the cuts table. See re-seeding.
  • The re-seed’s protocol (edytor/protocol): messageEpoch and writeEpoch (the room’s epoch, auth subtype 3), messageRebase (the client’s old document, message type 7), and CLOSE.reseeded (4410). See re-seeds.
  • clipUpdate(update, sv, ds) (edytor/crdt): an update as it read at an earlier state, the counterpart of diffUpdate. bindCrdt(Y).doc.restoreTo takes options (rewrite, and suggestions: '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. IndexeddbPersistence and WebsocketProvider no longer carry _storeUpdate, _updateHandler or _awarenessUpdateHandler (their document and presence listeners, never meant to be called): one _unlisten removes both listeners, as destroy() 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 database edytor-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 (toJSON with the previous release, then createDocument({ 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 (or adoptSharedSuggestions(document) on a document without a view), document.toJSON(), edytor.value and onChange’s value are the document without its pending shared suggestions, and so are the room’s onSave value, 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); onChange reads 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-control so 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 has start and end (display offsets, an inline atom counting 1), text, runs (its text runs and their marks), key and segOrd (its position among the block’s texts); an atom part has start, end, id, type and data. It answered start and items/length for a text, start and item for an atom. The runs of a text segment in a selection’s projection are read-only too.
  • edytor.suggestions.list lists shared suggestions too, with the shared suggestions plugin. Its items are Suggestion | SharedSuggestion, told apart by shared: a view-local Suggestion keeps its at, and a SharedSuggestion another view made has no position of its own (its at is null; read its changes for where it is). TypeScript now asks code that reads a shared one’s members to check suggestion.shared first.

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’s suggesting is 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 new suggestions.notSuggested label (the suggestions section of Labels, 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 SharedSuggestion is in the one list (shared: true), with by (its author), via ('ai'), changes (SuggestedChange[]: insert, delete, block, split or remove), canDecide, mine and reject(); discard() on it rejects it, which its author may do even without the right to decide. AnySuggestion is either kind.
    • The controller’s changes(), decide(changes, accept), acceptAll() and rejectAll() review them: one command each (acceptSuggestion with { changes }, the new rejectSuggestion) 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, whose toJSON() then leaves the pending ones out.
  • 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, with via: 'ai' (or the via you pass). Each chunk writes only what changed. See AI answers shared live.
  • Access levels. authorize returns access: read, comment, suggest or write (DocumentAccessLevel, exported by edytor/cloudflare; readOnly: true is read). A suggest user writes only suggestions (anything else is stripped and refused suggest-only, the socket kept) and decides nothing; a comment user comments from a read-only view, the room writing the thread’s anchor. setAccess takes 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 new access event, document.access (which the shared suggestions and comments plugins read) and the sync payload’s access. See access levels.
  • Review chrome. The suggestion bar shows under a shared suggestion’s last changed block; its payload gains reject, canDecide and author. 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 new review prop draws the Editing and Suggesting switch with Accept all and Reject all (its new sharedSuggestions plugin 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/crdt exports unhide (and EngineSymbol lists it), and EngineNode.delete takes 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 until unhide(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 insertText composes 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 unNestBlocks call 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 database edytor-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 (toJSON with the previous release, then createDocument({ 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 loadDocument is refused as undecodable (UndecodableUpdateError, “an update of another encoding”), where it was a SchemaMismatchError; an update written by upstream Yjs (or yjs 13) 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/edytor and edytor/protocol. A merge claim is an item of a block’s text: MergeClaim is { m }, and Claim is { m, stamp } (no seqIndex, a, r or holder; ItemRef is gone). TextBlockRec loses claimsNode and listClaims and gains implicit (the claims no item stores); its claims are the claim items of the block’s stream, after them. Ownership.claimsOf is gone and Ownership gains claimIndex(holder, m). The text binding’s claimInto(own, from, into) writes the claim item in into’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, and deleteClaims(doc, claims) deletes claim items. RunView.track() also returns quiet(write).
  • A plan’s steps carry places, not ranks. In edytor/crdt/edytor, PlanStep‘s insertBlocks and moveBlocks steps lose ranks (a moveBlocks step may carry side: 1 when the blocks leave a block for the gap before it, at: the block its record stands at, and part: its order among the records standing there; an insertBlocks step may carry split: the split-born block of the plan whose boundary keys the new blocks’ slots, a paste’s lines), splitBlock carries index instead of rank, and patchData carries writes (DataWrite[]: leaf writes and slot writes) instead of leaves. A hook that read a step’s ranks reads its index.
  • The placement model’s write primitives changed. bindCrdt(Y).doc.model lists placeBlocks, moveBlocksTo, insertSpecsAt and recordsOf; ranksAt, writePlacement, materializeSpec, candidatesOf and resolvePlacements are gone (the document’s index decides every placement, one block at a time; there is no from-scratch resolution to call), writeSplit takes a parent and an index, and a BlockRec carries home (its slot) instead of cands. dataLeaves/writeLeaves are dataWrites/writeData. EngineNode (the structural view of the engine’s node in edytor/crdt/edytor and edytor/protocol) gains hold(ids), move(index, ids, side, part, at) and the into and fresh arguments of delete: an object you pass as an EngineNode must have them (the engine’s nodes do). EngineSymbol no longer lists ContentAny, and edytor/crdt exports ContentMove. A BlockSlot may carry s, the split’s boundary id. In move(index, ids, side, part, at), at is the chain of units the record stands at, outermost first (for a block: its ancestors’ home slots, then its own).
  • bindCrdt(Y).doc.keepCopies is removed. A room’s document needs no collection rule for deleted text any more: create it with createDoc() and apply updates. Remove the call.
  • PurgeReport.records and metrics().purge.records replace candidates. The purge has no restoration records and no placement candidates to delete; marks counts the text delete records it removed, with the text they held, and records the 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/deleteBlocks and of such a setBlockType has no moveBlocks step and its effect.moves lists no children (a hook that counted on it reads effect.removes and the read-time rules). A reader that lacks the layout role (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 a TypeError for an engine document created with new 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 with createDoc() (from edytor/crdt), createDocument or loadDocument, then apply updates; an empty new 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) is undefined, and document.attribution.actors does not list the local actor, until the document’s first edit (or attribution.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 from document.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’s purge log entry have horizon: number | null: null for a run that purged what closed sessions deleted with no epoch past the purge horizon (see New). Handle null where 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 pagehide the 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 for purgeAfterDays, 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 before pagehide, the release reaches the room only through another open tab of the document; otherwise the deletes wait for the purge horizon, as before. PurgeReport and metrics().purge gain released, 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_BYTES to 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 transformText decorations change on their own.
  • Code highlighting on TanStack Highlight 1.1. The code block’s grammars come from @tanstack/highlight 1.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, …) with autoUpdate, or bits-ui’s customAnchor={controller.anchor}); the toolbar’s link card by cardAnchor. Their hosts no longer carry left/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 the edytor-chrome registry item).
  • One caret form for a command. dispatcher.caret takes only { block, offset } in block offsets (dispatcher.caret({ block, offset }, ops?)); the text segment form caret(text, offset, ops?) is gone. A segment offset is { block: text.parent, offset: text.segStart + offset }.
  • A view takes its document one way. The doc and awareness options of new Edytor(…) and <Edytor> are removed: compose the document first, attachDocument(doc, { awareness }), and pass it as document (the view then borrows it: destroy it yourself). Without document the view owns a fresh one, which actor and requireHydration still configure. edytor.ownsDocument is gone.
  • One error per meaning. EdytorDocDisposedError is gone: an operation on a destroyed document, or on a disposed facade, throws DocumentDestroyedError. ChunkLimitError (edytor/protocol) is now ChunkError, thrown for a sequence over the limit (with total and limit) and for a part or end with no start. The errors’ messages are one line.
  • No v13 document check. UnsupportedDocError and assertUsableDoc are removed: attachDocument no longer tests for a document of another engine (a v13 yjs document), which no supported path produces. SchemaMismatchError’s message is one line naming the problem, the version and the manifest name it found.
  • selection.hidden and selection.shown are 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).
  • ImageToolbar has no public constructor. The image toolbar plugin builds the one per view and hands it to your toolbar snippet; 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.json copies <StarterEditor /> into your app: <Edytor> with every useful bundled plugin, the Notion-style menus, handles, toolbars and panels, comments (with a comments client), 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 /> from edytor is unchanged. See Starter editor.
  • The ready-made menus, a shadcn-svelte registry item. npx shadcn-svelte@latest add https://edytor.dev/r/edytor-chrome.json copies 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? }) and fromHTML(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 (textToBlocks reads Markdown, and is there too). The entry loads no Svelte, so it runs in Node and in Workers; fromHTML takes a DOMParser there (linkedom’s, say). fromHTML is safe: only the kinds and marks you read survive, links and sources go through the editor’s sanitizers, and nothing in the HTML runs. Without kinds they read the bundled kinds (bundledForms); pass a view (kinds: edytor) or forms by name to read yours. See Import and export.
  • A markdown form 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: what toMarkdown writes. Every bundled kind has one, kept in edytor/export by 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. Its textToBlocks (and fromMarkdown, the same reading as a document) parses with @tanstack/markdown, a small dependency only edytor/export loads, and reads GFM tables as a table block (the first row its header), a fence’s language as the code block’s data.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. textToBlocks from edytor, which a markdown paste and a string suggestion read, is unchanged: tables, code languages, nested marks and streaming need the one from edytor/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 to onUnknown. toMarkdown(doc, { components }) writes the same tags back, and mdxComponent(name, data, content, children) writes one from a kind’s own markdown form. See Import and export.
  • CORS for the room’s HTTP routes. routeDocumentComments, routeDocumentHistory and the probes of routeDocumentSocket take cors: true | { credentials?, maxAge? }: a page on another origin gets its preflight answered and every answer carries Access-Control-Allow-Origin (the origins allowedOrigins lists, echoed, with cookies when credentials is 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. createCommentsClient without socket now hears the room’s changes on the websocket sync the page already holds for that room, whatever its route: a comments route on /comments beside sockets on /rooms needs no socket any more (before, the client listened on /comments and heard nothing).
  • The comments docs. The starter’s “With a room” example passes the user the documented authorize reads, 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/export is smaller per function. Each conversion reads only its own direction of the kinds’ forms: toHTML alone ships about half of what it did, toMarkdown and fromHTML less too, with the same output. The plugin forms factories (codeForms(), mediaForms(), …) return records typed as BlockForms rows; 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 lists createImagePlugin({ upload }) (or createImagePlugin() 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 + ↑/↓ lists createArrowMovePlugin(); 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> (or new 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 an upload; 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 />
  • createUploadsPlugin is removed: each media plugin takes its own upload. 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. UploadsOptions is gone, and a kind record’s upload (KindUpload) now needs send (the uploader) and has no preview. A full media labels section you pass now needs uploading.

    // 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 (or null, 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.peers lists the other people in the document (every client but yours, by client id), each { clientId, name?, color?, … } with the fields of its user state. 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. The awareness.getStates() filter and change subscription you wrote can go. See Who is online.
  • Properties are plain Svelte state. block.data, atom.data and edytor.data are 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 one patchData (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, and JSON.stringify or $state.snapshot give plain JSON. A readonly view refuses an assignment without throwing (dispatcher.last is refused). A snippet’s block.data is typed by the kind and writable (it was Readonly), and bound inputs work: bind:value={block.data.title}. A bare document has document.data, whose writes are the raw patchData. 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 empty snippet draws it with the controller’s preview (the object URL, or null) and progress (0 to 1, or null), and pending while uploading also has name and size; without the media empty plugin the block’s own markup shows it. A file row snippet gets uploading and progress (src is the object URL meanwhile). The labels gain uploading (“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 upload of 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’s onPaste hook gets that place as at ({ block, position }). See Pasted and dropped files.
  • An editable editor renders on the server (documentation). <Edytor> given a value, or nothing, server-renders its blocks and hydrates in the browser, so it needs no onMount guard and no export const ssr = false;. An editor connected to a room needs none either: it server-renders its snapshot (or nothing) and opens IndexedDB and its socket in the browser; load the snapshot in your server load to 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, so ssr.noExternal: ['edytor'] and resolve.dedupe: ['svelte'] can go from your vite.config. The quick start is shorter: one plugin, and the document kept in a $state from onChange. 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 (default mention): list the plugin once per thing to mention, as createMentionPlugin({ char: '$', kind: 'ticker', items: tickers }) beside the @ people. Each instance opens its own menu, and its atoms render and copy with its own char ($AAPL). A menu snippet reads its trigger’s kind as controller.trigger.name (a trigger’s new name). The atom’s data-edytor-mention attribute 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 after say **b** the text say **b**. A rule’s replace now runs with the typed text in the document: ctx.to is after it, and ctx.remove removes 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 needs ResizeObserver, Element.checkVisibility and requestAnimationFrame.
  • Storage needs CompressionStream. The browser store and the room compress every snapshot with CompressionStream and DecompressionStream, 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, and SCHEMA_VERSION and bindCrdt(Y).version are 6. 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>. createIndexeddbSync and IndexeddbPersistence read no earlier store (edytor-v14-g5:<name>, edytor-v14:<name>) and leave it as it was; the convertPrevious option 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 from onLoad: attachRoom no longer answers { kind: 'converted' }, the convert log entry is gone and StoredRecord has no v2 field.
    • A server of your own: STORED_GENERATION_RECORD, STORAGE_FORMAT, StorageFormat, PREVIOUS_SCHEMA and isPreviousGenerationRecord are removed from edytor/protocol (a container record is GENERATION_RECORD, with no storage field), bindCrdt(Y).generations is removed, and bindCrdt(Y).admission.admitUpdate takes update bytes only (no { v2 } form).
  • One inbound path for sync payloads. bindCrdt(Y).sync.readSyncStep1, readSyncStep2, readUpdate, readSyncMessage and step2Update are removed: apply a received SyncStep2’s or Update’s payload as it is with sync.applyRemote(doc, payload, origin), which refuses a forged schema stamp and reports it, and answer a SyncStep1 with sync.writeSyncStep2(encoder, doc, stateVector). modifyAwarenessUpdate is removed from edytor/protocol: rewrite entries with writeAwarenessEntries(readAwarenessEntries(update).map(…)).

  • v13 documents no longer import. bindCrdt(Y).migration, isLegacyDoc and the Migration, MigrationStatus, MigrationRecord, MigrationPhase, MigrateResult and MigrateOptions types are removed, and UnsupportedDocError has only the reason foreign: this engine does not decode a v13 document’s bytes (loadDocument throws UndecodableUpdateError). 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 data attribute, 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: the a/ records of early builds stay in the document byte for byte, unread (read them from the attribution root if you keep a decoder of your own).

  • The per-block lineage ring is gone. The lineage: { depth } option of createDocument, loadDocument and attachDocument, attribution.history(id) and the BlockLineageEntry type 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.history and facade.createUndoManager({ trackedOrigins, captureTimeout, limit, captureTransaction }) return it (the YUndoManager type), with undo(), redo(), stopCapturing(), canUndo(), canRedo(), clear(), destroy(), undoStack, redoStack, captureTimeout, trackedOrigins and captureTransaction. 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 of on('stack-item-added' | 'stack-item-updated'). stack-item-popped and stack-cleared are gone: undo() and redo() return the step they replayed.
    • addToScope, addTrackedOrigin and removeTrackedOrigin (add to trackedOrigins), deleteFilter and ignoreRemoteAttributeChanges are gone, and facade.releaseHistory(um) is um.clear().
  • The raw engine (edytor/crdt) ships only what the editor calls. It keeps documents, nodes, transactions, the update encoding, id sets and RangeCursor, and gains diffUpdate, idAtIndex, indexOfId, keepItem and followRedone. If your code calls it:

    Removed Use
    applyUpdateV2, encodeStateAsUpdateV2, mergeUpdatesV2, diffUpdateV2, decodeUpdateV2, readUpdateV2, convertUpdateFormatV2ToV1, the updateV2 event applyUpdate, encodeStateAsUpdate, mergeUpdates, diffUpdate, decodeUpdate and the update event, which read and write the one encoding (bytes stored in the v1 encoding no longer read)
    UpdateEncoderV1, UpdateEncoderV2, UpdateDecoderV1, UpdateDecoderV2 UpdateEncoder, UpdateDecoder
    Y.UndoManager edytor’s undo manager, above; redoItem’s last arguments are (…, itemsToDelete, deletedByHistory?)
    node.format(…), insert’s format argument, Y.cleanupYTextFormatting a mark: node.mark(index, length, name, value, startSide, endSide); read marks with new Y.RangeCursor(node).read(from, to) (a plain format another engine writes is ignored)
    observe, observeDeep, unobserve, unobserveDeep, Y.YEvent, the beforeObserverCalls and afterTransactionCleanup events doc.on('commit', (transaction) => …), once per transaction before afterTransaction: transaction.changed maps each node it changed to the keys (null: its content) that changed
    toDelta, toDeltaDeep, node.delta, applyDelta, node.change, Node.from, clearCache, the 'delta' event, a delta inserted as content write with insert, delete, mark, setAttr and deleteAttr (insert a new Y.Node() you filled)
    toJSON, toString, toArray, get, slice, getAttrs, hasAttr, attrValues, attrEntries, attrSize, map, forEach, push, unshift, clone, clearAttrs, parent read with getAttr, forEachAttr, attrKeys and RangeCursor; for a document, the document API (toJSON(), project(), runs(id))
    createRelativePositionFromTypeIndex, createRelativePositionFromJSON, createAbsolutePositionFromRelativePosition, relativePositionToJSON, RelativePosition, AbsolutePosition Y.idAtIndex(node, index, assoc), the id a position binds (null at an end), and Y.indexOfId(doc, id, assoc), its live index and node ({ type, index }, or null)
    subdocuments and load state: Doc’s guid, collectionid, meta, autoLoad, shouldLoad, load(), getSubdocs(), getSubdocGuids(), toJSON(), isLoaded, isSynced, whenLoaded, whenSynced, the load, sync and subdocs events, ContentDoc, ContentEmbed, ContentJSON new Y.Doc({ gc, gcFilter }); an update holding one of these contents no longer decodes
    a transaction’s beforeState, afterState, meta and cleanUps nothing
    the renderer (AbstractRenderer, $renderer, useRenderer, the renderer argument of RangeCursor) and the schemas $doc, $nodeAny, $idSet, $idMapAny, $contentIds, $contentMap instanceof Y.Doc, instanceof Y.Node, instanceof Y.IdSet
    id maps and content maps (IdMap, createIdMap, insertIntoIdMap, readIdMap, writeIdMap, encodeIdMap, decodeIdMap, ContentAttribute, createContentAttribute, ContentMap, createContentMap, readContentMap, writeContentMap, encodeContentMap, decodeContentMap), IdSet#forEach, covers, coveredLength and slice, equalIdSets nothing

    A write past the end of a node that is not in a document yet throws when you make it. The EngineDeepEvent type is removed from edytor/crdt/edytor and edytor/protocol.

  • ProviderStack no longer has prefetch, lastUpdated and documentSnapshot. Import them from edytor as before, or read them from bindCrdt(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, from edytor/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 an OpResult (status, the ids written). See Editing programmatically and Operations.

  • Handles only read. Block, Text and InlineBlock keep 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: null is 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.pushContentIntoBlock edytor.setBlock(id, value) (its content and children take 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); null targets the document’s own data
    block.moveBlock({ path }), block.moveBlocks({ blocks, path }) edytor.moveBlocks(ids, { parent, index }), or edytor.move(request)
    block.addInlineBlock({ offset, block }), block.removeInlineBlock({ index }) edytor.insertInline(id, offset, atom) (an id is 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.deleteAt edytor.deleteText(id, offset, length), edytor.insertText(id, offset, text, marks?), edytor.deleteRange(from, to), edytor.replaceRange(from, to) (block offsets: a text’s offset plus text.segStart)
    text.markText({ mark, value, toggle }), text.removeMarksFromText(), text.formatAt edytor.formatRange(id, offset, length, { [mark]: value }) (null removes it), edytor.clearMarks(id, offset, length); the toggle over the selection is richTextOperations(edytor).setMarkAtRange(mark)
    block.normalizeContent(), block.normalizeChildren() nothing: the view runs them after every operation
    block.model (a DocBlock), document.block(id), the DocBlock and NodeRef types the 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 prepare forms 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 with formatRange in place of unsetMark.

  • Table operations are the table plugin’s. The document no longer has insertTableRow, deleteTableRows, insertTableColumn, deleteTableColumn, moveTableColumn, moveTableRows and fillTableCell (nor their prepare forms): import them from edytor and give them the document first, document.apply(insertTableRow(document, table, 1)) for document.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.data and edytor.data are read-only (typed Readonly): an assignment such as block.data.done = true or bind:value={block.data.title} no longer writes. Write with edytor.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) and edytor.canMoveBlocks(request) (a target and position, or a direction) are replaced by edytor.move(request) and edytor.canMove(request); edytor.moveBlocks(ids, destination) is the document’s operation. edytor.deleteBlocks({ blocks }) is edytor.deleteBlocks(ids) and edytor.insertFlow({ flow, target }) is edytor.insertFlow(target, flow). edytor.deleteContentWithinSelection is removed (use edytor.deleteRange(from, to)), and so is edytor.edytor.

  • Hooks see the operation’s arguments. In onBeforeOperation and onAfterOperation, an operation’s payload is its argument list ([id, offset, text, marks] for insertText, typed by ChangePayload), and block is the block it writes (for insertBlocks, their parent). A command keeps its object payload, typed by the new Commands: acceptSuggestion, replaceMatches, addComment, moveText, inlineMarkdown, insertDivider and the table commands (ReplaceMatches is Commands['replaceMatches']). A command’s steps are shown as the operations they perform: insertBlocks, moveBlocks, deleteBlock, splitBlock, mergeBlocks, setBlockType, patchData, insertText, insertInline, deleteText, removeInline and formatRange.

  • 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, setText or wrapBlocks: Enter runs splitBlock, insertBlocks, unNestBlock or setBlock, Backspace mergeBackward, deleteText, deleteRange or deleteBlocks, Turn into columns wrapInLayout, and a move beside a block placeBeside ([ids, target, side]; the beside payload and the BlockBeside type are gone).

  • Normalization runs after every write. normalizeContent runs on every block whose content, kind or data an operation wrote (typing included) and on a block it inserted; normalizeChildren on the parents whose children changed.

  • Results. CommandResult.value is removed: an operation answers its OpResult, whose ids name what it created, and dispatcher.caret(…)’s body answers one too. dispatcher.plan(operation, payload, prepare, block?) runs a plan you prepare as one named command. TextOperations, BlockOperations and TextInsertionPayload are removed; a trigger controller’s handleTextInsertion(text, block, start, value) takes the offset and the text.

Selection
  • The selection has one view, its projection. selection.state (and the SelectionState type) and the setters setAtTextOffset, setAtRange, setAtTextsRange, setAtBlockRange, selectBlocks, addBlockToSelection and removeBlockFromSelection are removed. Read the selection from selection.projection (start and end as { block, offset }, isCollapsed, isReversed, blocks, marks, content), the caret from selection.caret ({ block, offset }) and the blocks from selection.selectedBlocks; the text segment that shows an offset is block.textAtOffset(offset). Write it with selection.setCaret({ block, offset }), or selection.select(value) for anything else:

    Removed Use
    state.startBlock selection.caret?.block, or edytor.idToBlock.get(selection.projection.start?.block ?? '') for the start of a range
    setAtTextOffset(text, offset) setCaret({ block: text.parent, offset: text.segStart + offset })
    setAtRange(…), setAtTextsRange(…), setAtBlockRange(block) select(selection.textValue(startText, startOffset, endText, endOffset, isReversed)), or select({ kind: 'text', anchor, focus }) with anchors from edytor.document.anchorAt(blockId, offset, affinity)
    selectBlocks(a, b), addBlockToSelection, removeBlockFromSelection select({ 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, isColumnsPlugin and isTablePlugin are removed: any instance of a default plugin’s factory you list replaces that default.

    Removed Use
    richTextPlugin, codePlugin, imagePlugin, suggestionsPlugin, columnsPlugin, tablePlugin, marqueePlugin createRichTextPlugin(), createCodePlugin(), createImagePlugin(), createSuggestionsPlugin(), createColumnsPlugin(), createTablePlugin(), createMarqueePlugin()
    embedPlugin, bookmarkPlugin, filePlugin, videoPlugin, audioPlugin, pagePlugin, tocPlugin createEmbedPlugin(), createBookmarkPlugin(), createFilePlugin(), createVideoPlugin(), createAudioPlugin(), createPagePlugin(), createTocPlugin()
    markdownShortcutsPlugin, arrowMovePlugin createMarkdownShortcutsPlugin(), createArrowMovePlugin()
    slashMenuPlugin, blockMenuPlugin, toolbarPlugin, findPlugin, blockHandlesPlugin their 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 (/divider and Enter still insert a divider with no menu shown). Copy the ready-made menus for the Notion-style markup (chrome.svelte holds every snippet, plugins.ts passes them to each factory). See Menus and handles. Each surface and its snippet:

    Surface Plugin and option The snippet receives
    Slash menu createSlashMenuPlugin({ menu }) SlashMenuController
    A trigger’s menu createMentionPlugin({ menu }), createPageLinkPlugin({ menu }), a Trigger’s menu TriggerMenuController
    Block menu createBlockMenuPlugin({ menu }) BlockMenuController
    Block handles createBlockHandlesPlugin({ handle, draggable }) BlockHandleSnippetPayload
    Toolbar and link card createToolbarPlugin({ toolbar, card }) ToolbarController
    Pasted-URL menu createEmbedPlugin({ menu }), createBookmarkPlugin({ menu }) UrlPasteController
    Every empty image and media block createMediaEmptyPlugin({ empty }) MediaEmptyController (read controller.kind)
    Image toolbar createImageToolbarPlugin({ toolbar }) ImageToolbar
    Callout icon picker createCalloutIconsPlugin({ picker, icons }) CalloutIconPicker
    Table grips, menu and + bars createTablePlugin({ grip, menu, add }) TableGripPayload, TableChrome, TableAddPayload
    Code header and language list createCodePlugin({ header, menu }) CodeHeader, LanguageMenu
    Equation panel createEquationPlugin({ panel }) EquationEditor
    Comment cards and the margin’s top createCommentsPlugin({ card, header }) CommentCardPayload, CommentsController
    Find bar createFindPlugin({ bar }) FindController
    Suggestion bar createSuggestionBarPlugin({ bar }) SuggestionBarPayload
    Marquee rectangle createMarqueePlugin({ box }) MarqueeBoxPayload
    Version history new VersionHistory(options) in your component the 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 a handle, no handle shows
    createImagePlugin({ upload, toolbar, empty }), ImagePluginOptions createImagePlugin() (the kind and its resize handles), createImageToolbarPlugin({ toolbar }), createMediaEmptyPlugin({ empty }), createUploadsPlugin({ upload })
    empty on the embed, bookmark, file, video and audio plugins createMediaEmptyPlugin({ empty }) once, for every kind
    upload on the file, video and audio plugins; MediaPluginOptions createUploadsPlugin({ upload }) once (the empty blocks’ Upload and pasted or dropped files, each placed as a block of the kind that takes it); createFilePlugin(), createVideoPlugin() and createAudioPlugin() take no options
    createRichTextPlugin({ callout: { icon, icons, picker } }) createRichTextPlugin({ callout: { icon } }) (the default icon) and createCalloutIconsPlugin({ picker, icons }) (CALLOUT_ICONS by default), which also adds the block menu’s Change icon row; without it, a callout’s icon is no button
    createSuggestionsPlugin({ bar }), SuggestionsOptions createSuggestionsPlugin() (the keys, a default plugin) and createSuggestionBarPlugin({ bar }) (SuggestionBarOptions)
    <HistoryPanel>, HistoryPanelProps, HistoryVersionItem, defaultHistoryLabels new 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 by previewKey) and Restore (restore(), undo(), status). See History panel

    A 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, with SlashMenuItem and TriggerItemPayload); your menu draws its rows. The + menu no longer wraps your menu: put {@attach controller.keys} on the element that holds its keyboard (a field, or the menu itself). The toolbar’s linkCard is removed: without card, no card shows.
    • The block handle’s payload drops addable (always true) and labels, and gains beside (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.registerHandle returns () => void.
    • A grip click is answered by its event only: createBlockHandlesPlugin({ onActivate }) and the BlockHandleActivation type are removed. A grip click dispatches edytor-block-activate (BLOCK_ACTIVATE_EVENT, detail: BlockActivation, cancelable) on the editor’s root, which the block menu plugin, or your own listener, answers with preventDefault().
    • The image toolbar’s snippet receives an ImageToolbar (box, align, alt, setAlt, editing, toggleAlt, closeAlt, bar, altField, readonly), no longer ImageControls.
    • Empty blocks share one controller: ImageEmptyController and ImageEmptyFailure are removed, and an empty image receives a MediaEmptyController whose kind is image. MediaEmptyFailure gains inline (an inline image over MAX_INLINE_IMAGE_BYTES), failed is null when nothing failed (it was false for media), and toggle(), label, kindLabels and the image’s inlineLimit are removed (set open). An uploading pasted or dropped image is your empty snippet’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 card for a thread and for the comment being written (thread: null: comments.submit(body), comments.cancel()); the margin’s top (“Resolved (n)”) is your header. Without card, no sidebar shows.
    • The table menu names its row or column by id: TableMenu is { kind, table, id } (the row’s block id or the column’s id; row and column are gone) and TableMenuRow is { id }. TableChrome‘s open, rows, runRow, rowId(row), menuId, addRow and addColumn are removed: your menu draws chrome.items (each with run, disabled, danger, option; an item’s icon is gone, name it by item.item.id), your add calls its payload’s add. 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 mac and the callout picker columns.
  • 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’s option, is an attachment: write {@attach menu.option(index)} for {...menu.option(index)}. It no longer sets data-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). OptionAttributes is removed.
    • The block handle’s grip is an attachment ({@attach grip} for use:grip), and the new plus is the +’s ({@attach plus}: its click calls add under it, its press keeps the focus). Each keeps the ARIA of the menu it opened, so the payload’s expanded, controls and haspopup are removed; the grip also sets its aria-keyshortcuts.
    • The find bar’s fields take {@attach find.field} and {@attach find.replaceField} (was use:), and the version list {@attach history.keys} (was onkeydown={history.keys}).
  • 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 (was selectedIndex, the block menu’s too), move(step) moves it (was the menus’ moveSelection(step)), and a row’s element id is the list’s listId and its position, rowId(index). The slash menu’s optionId(command), a trigger menu’s and the URL paste menu’s optionId(index), the callout picker’s optionId(index) and id, the language list’s rowId(row) and the table menu’s menuId are removed.

    • The callout picker’s rows are every menu’s rows: {@attach picker.option(i)} (its id, role, aria-selected, aria-checked, no handlers); run picker.pick(i) on a row’s click. CalloutIconOption and the data-active, data-edytor-callout-icon-choice and data-edytor-callout-icon-remove attributes are removed. The picker’s panel is placed, and closed on a press or focus outside, as the code language list’s is.
  • 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() and runFlyout() are removed, and duplicate(block) and duplicateAll(blocks) are one duplicate(blocks, select). CodeHeader.setLanguage and CodeHeader.languages are removed (the language list’s pick sets a block’s language; your languages are your rows), and so are BlockMenuController.publish, the trigger and slash menus’ publish, ToolbarController.publish (each surface’s popup attachment publishes it) and MarqueeController.pressing. Members only their own class read are private: BlockHandleController.activateBlock and handleKeyDown, BlockMenuController.matchingKinds, the trigger menus’ activeRange, InlineBlock._def and about a hundred undocumented ones.

  • A kind is restyled by a plugin; <Edytor> takes no snippet props and no placeholder. The <type>Block, <type>Mark and <type>InlineBlock snippets passed to <Edytor> (and EdytorOptions.snippets, with the Snippets type) 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. The placeholder prop and option are removed: return placeholder from 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.css the 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-color now 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-selection is 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 (now data-selected="true", was a selected class).
    • 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.
  • 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-shown and data-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-color on 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-color and --edytor-image-handle-color are read by the theme; the demo’s handle markup no longer paints the drop line and backdrop.
  • Input rules and triggers are wired by the plugin that declares them. A plugin’s definitions no longer take inputRules and triggers: return withRulesAndTriggers(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 labels or keywords: <Edytor labels> (EdytorOptions.labels) takes any entry of any section ({ richText: { kinds: { … } }, table: { … } }) and keywords by command id, for every plugin of the view. PartialLabels is that whole dictionary (no section parameter).
    • The dictionary keeps only the words the package shows, says or searches: the toolbar, slashMenu, blockHandles, find, suggestions, mention and history sections 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, searching and noResults). A media kind’s entry is its name (media.video is “Video”, MediaKindLabels is removed), and code.languages is gone: name a language in your languages rows.
    • controller.labels is removed from every controller and payload. SlashMenuController.groupName, ToolbarController.colorName, MediaEmptyController.label and kindLabels, the rows’ and payloads’ label (MenuItemPayload, TableMenuRow, TableGripPayload, TableAddPayload, UrlPasteOption, UrlPasteOffer; name a row by its item.id), a trigger’s name, empty and searching and its controller’s, and TOOLBAR_COLORS are removed: your palette is your markup’s (setColor takes any CSS colour).
    • VersionHistory takes no labels: status is a code (VersionHistoryStatus), dateOf names the day (version.slot its half), and the editors are version.editors and version.more. CommentsController.userOf names a user without a name by their id (“You” is your card’s).
    • createRichTextPlaceholder(labels) is richTextPlaceholder, a placeholder that reads the view’s richText labels.
Removed kinds and dependencies
  • The details and horizontalRule kinds are removed (and richTextKinds.horizontalRule): they were other names for toggle and divider. 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-drop and 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 }) (a document with doc, awareness, actor or requireHydration) and dispatcher.outside(body) called inside a transaction still throw in development; a production build no longer checks (the document wins; 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) and createPagePlugin({ link }) (PageBlockLinkPayload).
    • The default markup renders its links’ href and its markers too, so a server-rendered readonly view is styled and links before it runs. See Controls inside blocks.

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 SemanticConflictError from adoptSemantics (a view’s plugin, or a reattach, disagreeing with the document) carries the two declarations in existing and incoming as they were written, as mergeSemantics reports them, instead of their normalized form. Its subject and 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 popup keeps a custom picker’s own role and name, as every other menu’s popup does, 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 (&amp;, &quot;): the image, callout, embed, bookmark, file, video and audio exports wrote numeric references (&#38;), which read back the same.

From 1.0.0-rc.2

Breaking changes

  • Long pages: one switch, any theme. The edytor-long-page class 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 textContent no longer has a space between its own text and its nested blocks’.
  • Equations load KaTeX from a CDN by default. createEquationPlugin() with no katex option 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, at KATEX_CDN). Apps no longer need to install katex, import katex/dist/katex.min.css or pass katex: () => import('katex'): drop them to keep KaTeX out of your bundle. katex also takes a URL (another copy of KaTeX’s dist folder) or false (no drawing, the TeX source shows); your own loader still works as before. A page with a Content Security Policy allows https://cdn.jsdelivr.net in script-src, style-src and font-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 for select[data-edytor-code-language] now targets button[data-edytor-code-language], the Copy button is [data-edytor-code-copy], and the panel’s colors are custom properties (--edytor-code-background and others). A complete label dictionary of your own (satisfies Labels) adds code.search and code.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 with container) 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 a box snippet (MarqueeBoxPayload) and the --edytor-marquee-background, --edytor-marquee-border and --edytor-marquee-radius variables. 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-color sets 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.icon is then ''; unset, the callout shows the editor’s default). createRichTextPlugin({ callout: { icon, icons, picker } }) sets the default icon, the picker’s choices (CALLOUT_ICONS by default) and your own picker markup (a snippet receiving CalloutIconPicker). The block menu of a callout has a Change icon row. The words are the rich text labels’ calloutIcon.
  • body on 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 size once when a document reaches 80 % of its quota (EDYTOR_DOCUMENT_WARNING, documentWarning), and metrics() reports the quota as documentLimit: 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’s flyoutMenu, the toolbar’s linkField, the image toolbar’s bar and altField, an empty block’s field. Existing snippets keep their payloads. New:
    • snippet options: a trigger’s menu (and createMentionPlugin({ menu }), createPageLinkPlugin({ menu })), createToolbarPlugin({ card }) for the link card, menu and empty on the embed and bookmark plugins (the menu a pasted URL opens, the empty block), empty on 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 }): SlashMenuItem gains item, label and option, TriggerItemPayload gains run (the same as pick) and option; SuggestionBarPayload gains labels;
    • exported types: MenuItemPayload, OptionAttributes, UrlPasteController, UrlPasteOption, UrlPasteOffer, ImageControls, ImageBox, ImageEmptyController, ImageEmptyFailure, MediaEmptyController, MediaEmptyFailure, MediaKind, CommentCardPayload, HistoryVersionItem; the block menu’s controller gains search(query), the toolbar’s linkFieldId.
  • 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 rows items, each a TableMenuItem, and the popup, keys and option(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 the button attachment that opens the list) and the language list (LanguageMenu: its rows items, each a LanguageMenuItem, and the keys, popup and option(index) attachments);
    • createEquationPlugin({ panel }): the equation editor (EquationEditor, whose field attachment gives your source field the focus and the keys);
    • the block handle’s payload gains expanded and controls (what its + and grip opened, for their aria-expanded and aria-controls) and labels, and add(alt, anchor) opens the menu under your +;
    • exported types: TableChrome, TableMenu, TableMenuRow, TableMenuItem, TableGripPayload, TableAddPayload, CodeHeader, LanguageMenu, LanguageMenuItem, LanguageRow, EquationEditor, EquationTarget; OptionAttributes gains aria-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.nextBlock and block.previousBlock answer null past either end, as their types say (they answered undefined).
  • 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.facade is gone. Deprecated in 1.0.0-rc.1, it is no longer in the published types: call the operations on the document itself (document.insertBlock(…), document.toJSON()).

New

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. The SelectCause type is no longer exported.
  • The document’s operations are its own; document.facade is deprecated. Call them on the document: document.insertBlock(…), document.toJSON(), document.prepare.splitBlock(…), document.onChange(…) (the DocumentOperations interface). document.facade returns the same operations and goes in the next release. What it held besides them (the index, the engine hooks, the history factory) is internal. edytor no longer exports EdytorDoc (the full binding, still in edytor/crdt/edytor): name DocumentOperations instead. A room’s transact callback, its facade and validate’s facade are typed DocumentOperations too.
  • The dispatcher’s plumbing is internal. edytor.dispatcher keeps last, permits(), run, each, dispatch, lead, caret and outside; its normalization queue (defer, request, drain, write), its undo cut (cut), its prevention scopes (scope, intercept), authoring and pendingLead are no longer in the published types. permits() is now documented: whether the view accepts writes.

New

  • DocumentOperations, and the document’s vocabulary exported. edytor exports DocumentOperations (with DocumentWrites and DocumentReads) 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. upload receives a second argument, report, whose progress(fraction) fills the block’s bar (the image block’s too); an upload that ignores it keeps working. The Uploader and UploadReport types 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.focusedBlocks and edytor.dispatcher.last can no longer be assigned (the sets are ReadonlySets). Assigning selection.value used to leave the selected blocks behind; use selection.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 replaces edytor.node?.focus() after setting a selection from a menu button.

  • The types you meet are exported. edytor now 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’s Key, Modifier and Modifiers, 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 answers 413) and their request rate (maxRequestsPerSecond, EDYTOR_MAX_COMMENT_REQUESTS_PER_SECOND, 2 a second with a ten-second burst, per user over HTTP: past it 429; per socket for its subscribes, which are dropped past it). A subscribe on a socket already subscribed no longer sends a second snapshot, and routeDocumentComments reads a body no further than 64 KiB even without a Content-Length. Raise the limits if your pages hold more; a client that posts in bursts should retry a 429. See Server comments.

New

  • Comment quota exports. edytor/cloudflare exports DEFAULT_MAX_COMMENT_BYTES, DEFAULT_MAX_COMMENT_REQUESTS_PER_SECOND, COMMENT_ROW_BYTES and commentBytes; decideComment takes bytes and maxBytes; the refusal reason comments is logged and counted in refusalCounts.

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, deleteAt and formatAt, and Block.insertChildren, deleteChildren and insertParts, 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…), or edytor.document.facade for 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 the Edytor option) hotkeys
    blockDnd (the <Edytor> prop) blockHandles (blockHandles={false} hides the handles)
    serverUrl, roomName (createWebsocketSync, prefetch, lastUpdated, documentSnapshot) server, room
    attachDocument(this, options), AttachDocumentOptions (edytor/cloudflare) attachRoom(this, options), AttachRoomOptions
    moveBlocks(namespace, move) (edytor/cloudflare) moveBlocksBetweenRooms(namespace, move)
    A KV namespace itself as history.store kvHistory(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, owner and waitForSettled(name, options)’s options (no-ops) nothing: leave them out
    • A hotKeys or blockDnd prop (or a hotKeys option to new 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 a TypeError that names server and room.
    • A room whose history.store is a bare KV namespace keeps no history: it notes a history refusal (history.store: not a HistoryStore) at its first use of the history, listing versions answers 404 and a restore throws. Nothing else fails, so check the room’s refusals after upgrading. The EDYTOR_HISTORY binding is unchanged: the room still wraps a KV binding in kvHistory itself. kvHistory writes what earlier releases wrote, so their versions list, preview and restore as before.
  • Pre-release stored formats still load (nothing to do). Documents stored by 0.1.0-next.6 (atomic array leaves, the whole-data attribute), 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.keepReplaced is per document. Binding the engine no longer sets the engine’s class default: Y.Doc.keepReplaced stays null (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 new bindEdytorDoc(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 with createDoc() instead (Protocol).
  • DocChange is read-only. Its collections are typed ReadonlyMap/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, tableCell and equation. They are in defaultSemantics, 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 a SemanticConflictError against defaultSemantics: rename the kind, or give the document its own semantics.
  • The comment mark has a bundled edge. defaultSemantics gives the comment mark the exclusive edge (commentMarks, a new export of edytor/crdt/edytor). A comment mark record of your own (the earlier recipe) that declares another edge now conflicts with it when the view mounts (SemanticConflictError): remove its edge, or use the comments plugin.
  • The history panel’s count words are functions. added, removed, changed and moreEditors were '{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 the comments, table, mention, history and equation sections, the editor section’s triggerMenu, searching and noResults. The slash menu’s groups labels have two new keys to translate, Color and Inline. 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 (one addComment command and undo step), kept through splits and merges, exclusive at its edges, and not copied.
    • Threads are kept by a client: createCommentsClient({ server, room, socket?, params?, fetch? }) over the room, or createMemoryCommentsClient({ user }) in memory (client.as(user) for another user of the same threads).
    • The room stores threads in two new tables, threads and comments, and the last change’s sequence number in meta (comments). routeDocumentComments(request, rooms, id, authorize, options?) answers GET (every thread) and POST (add, reply, resolve, reopen, delete), authorized like routeDocumentHistory; listComments() and comment(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 pass attachRoom(this, { comments: { onComment, maxLength } })) for notifications; EDYTOR_COMMENTS=off (or comments: 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 types CommentsPluginOptions, 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, decideComment and the comment types (CommentActor, CommentOutcome, CommentRefusal).
    • From edytor/protocol: messageComments, commentsSubscribe, commentsSnapshot, commentsChange, writeCommentsSubscribe, writeCommentsSnapshot, writeCommentsChange, readCommentsMessage, CommentMessage, CommentSnapshot, CommentChange, CommentThread, ThreadComment.
  • Marks. A mark record’s new copy: false leaves the mark out of copy and cut; toolbar.run makes its toolbar button call run instead of toggling it.
  • Tables (opt-in). tablePlugin, createTablePlugin({ rows, columns, columnWidth, minColumnWidth, labels, keywords }), isTablePlugin, TablePluginOptions: Notion’s simple table, a table of tableRows of tableCells, 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’s placeholder.
    • tableBlock(options) (root and edytor/crdt/edytor) builds a table as JSON with ids derived from its value; TableBlockOptions is its type.
  • The table role. BlockRole.table and BlockDefinition.table: a kind displays only its rows (its defaultChild), a row only its cells (the row’s defaultChild), in the order of the table’s data.columns ({ id, width? }, each cell naming its column in data.column). tableKinds and tableSemantics are on edytor/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 its apply writes. The document’s reads isTable, 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, splitBlock refuse 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).
  • 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 with checked is a switch (menuitemcheckbox, the menu stays open); any other row closes the menu after it runs (a caret its action placed stays). BlockMenuAction gained checked.
  • Equations (opt-in). createEquationPlugin({ katex, macros, labels, keywords }) adds Notion’s block equation (equation, void, its TeX in data.expression) and inline equation atom (inlineEquation), drawn by KaTeX. See Equation.
    • Your app loads KaTeX lazily (katex: () => import('katex')); katex is 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.
    • equationKinds and equationSemantics are on edytor/crdt/edytor. New root names: createEquationPlugin, EquationPluginOptions, EquationData, KatexLike, KatexLoader.
  • Inline atoms in HTML. InlineBlockDefinition takes html(data) (its clipboard HTML; the default is still the empty data-edytor-inline-block span) and parse(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’s parse hook 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: /red lists “Red text” and “Red background” (group Color, commands color.<name> and background.<name>), painting the caret’s block and removing /red in one undo step.
    • The block menu’s search lists them too, after the kinds (controller.matchingColors; rows may now hold BlockMenuColor rows, and runSelected() paints one).
    • New EditorCommand.searchOnly: a command listed only once a query names it.
  • Block colours in copied HTML. A copy’s text/html names 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’s teal as green).
  • Opening a page block. createPagePlugin({ open }) is called as open(pageId, { newTab }): newTab is true for a modified click (Mod, Shift) or a middle click without an href (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. An open that takes only the id keeps working.
  • Localized history panel, mentions and trigger menus. Labels has a history section (englishLabels.history; defaultHistoryLabels is the same object) and <HistoryPanel labels> takes PartialLabels<'history'>. createMentionPlugin({ labels }) takes the new mention section (menu, searching, noResults; English People, Searching…, No results). A trigger that names no name, empty or searching says the view’s new editor labels triggerMenu, noResults and searching (<Edytor labels>), English as before.
  • onDocChange. New <Edytor onDocChange> prop, EdytorOptions.onDocChange and plugin hook: each commit’s change report (DocChange), with no whole-document export, where onChange exports the document every commit. Each onDocChange and onChange consumer (the prop, each plugin) is isolated: one that throws is logged and the others still run.
  • Handle getters are reactive. A template, $derived or $effect that reads a Block, Text or InlineBlock getter (block.type, block.children, block.content, block.parent, block.index, block.isInTree, text.stringContent, atom.type, …) re-runs when a commit changes it, as block.data already did. Read elsewhere, a getter is the same plain read of the document. A template that read edytor.cells only to make a handle getter update can read the getter. See Handles.
  • Presence within a budget. The room relays presence within EDYTOR_MAX_PRESENCE_FANOUT frames a second over all its sockets (maxPresenceFanout with attachRoom, 2,000 by default, DEFAULT_MAX_PRESENCE_FANOUT, a new export of edytor/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. PurgeReport and metrics().purge have a new merged count. 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 1011 before 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

  • page and toc are bundled roles. They are void kinds that show no text (pageKinds, tocKinds, pageSemantics, tocSemantics on edytor/crdt/edytor), in defaultSemantics, so the room and headless documents read them as views with the plugins do. An app that defined its own page or toc kind with other roles gets a SemanticConflictError against defaultSemantics: rename the kind, or give the document its own semantics.
  • Block menu controller. flyout is false | 'turn' | 'color' (was a boolean; false still closes it, and a truthy check still means a flyout is open), openFlyout(which?) opens Turn into by default, and BlockMenuAction.submenu is 'turn' | 'color' (was true).
    • A custom menu that set flyout = true sets 'turn'.
    • The keyboard’s rows move by one: Color follows Turn into.
    • New: colors, colorable, isCurrentColor(row), paint(row), flyoutRows, runFlyout().

New

  • Input rules. A plugin’s new inputRules field (InputRule: { find, replace(match, ctx) }) replaces text typed at the caret that completes find. 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?)).
    • markdownShortcutsPlugin is now two input rules, with the same behavior.
  • Triggers. A plugin’s new triggers field (Trigger: { char, items(query), onPick }, plus label, key, item, name, empty, searching, enabled) opens a menu at the caret when char is typed at a text’s start or after whitespace.
    • The query filters it. items may 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 onPick replaces the trigger and its query in one undo step.
    • The slash menu is built on the same controller (TriggerMenuController is exported as a type).
  • Mentions and page links. New opt-in plugins: createMentionPlugin({ items }) (@ people, a mention atom { id, label }) and createPageLinkPlugin({ search, href }) ([[ pages, a pageLink atom 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.caret is the collapsed caret as { block, offset } (an inline atom counting 1; null for anything else), selection.setCaret({ block, offset }) selects one, dispatcher.caret({ block, offset }, ops?) takes one, and block.addInlineBlock({ offset, block }) inserts at a block offset. The Caret type 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.
    • labels is a new option of createToolbarPlugin, createSlashMenuPlugin, createBlockMenuPlugin, createBlockHandlesPlugin (and the blockHandles prop), createImagePlugin, createEmbedPlugin, createBookmarkPlugin, createFilePlugin, createVideoPlugin, createAudioPlugin, createCodePlugin, createFindPlugin, createSuggestionsPlugin, createColumnsPlugin, createPagePlugin, createTocPlugin and createPageLinkPlugin.
    • <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) and englishLabels. 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’s groups labels, a TOOLBAR_COLORS name through the toolbar’s colors, and a BLOCK_COLORS name (default for none) through the block menu’s colors (its Color flyout’s rows are colorText/colorBackground of it). The stored and compared values are unchanged.
  • createRichTextPlugin({ labels, keywords }) builds the rich text plugin in another language: labels names its presets, mark buttons and to-do checkbox; keywords replaces a preset’s slash keywords by command id (block.heading1). richTextPlugin is createRichTextPlugin(). 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 same keywords option (page.new, block.toc); the toggle headings’ are block.toggle-heading1 to 3.
  • createRichTextPlaceholder(labels) builds the Notion placeholders in another language; richTextPlaceholder is createRichTextPlaceholder().
  • 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.color and data.background, by palette name (BLOCK_COLORS), each one property, kept by Turn into.
    • The core renders a valid name as data-edytor-color and data-edytor-background on 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 color or background palette name now shows it.
  • Toggle headings. The rich text plugin has a toggle-heading kind, Notion’s “Toggle heading 1” to “3” (block.toggle-heading1 to 3, data.level as on a heading): a details whose summary holds the h1–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 head or /heading 2 now also lists them (after the headings: Enter still takes the heading); /h1 to /h3 do not.
    • richTextPlaceholder names them “Toggle heading N”.
  • 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’s markdown, 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 void page linking to another document (data.pageId, data.title, a cache your title lookup refreshes outside the undo history), and with create a “Page” command (page.new) that makes a page and opens it (Page).
  • Table of contents (opt-in). tocPlugin, createTocPlugin({ headingLevel }), TocPluginOptions, TocHeadingLevel: a void toc block 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 requests routeDocumentHistory answers and throws HistoryRequestError on a refusal. versionDiff(version, current) is the comparison alone.
    • New root names: HistoryPanel, createHistoryClient, HistoryRequestError, versionDiff, defaultHistoryLabels and the types HistoryClient, HistoryClientOptions, HistoryVersion, HistoryRestoreResult, HistoryUndoResult, HistoryPanelProps, HistoryPanelLabels, VersionDiff, VersionChange.
  • 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_BYTES for 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/protocol entry. edytor lists 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, Awareness and its types, EdytorSyncCleanup, ProviderStack, PrefetchOptions, PrefetchResult, LastUpdatedOptions, the attribution types, the migration types and isLegacyDoc, Crdt and 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 off edytor/crdt/edytor too): 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, schemaVersion and their types), and the raw provider classes IndexeddbPersistence and WebsocketProvider with their option and event types, and storeState. edytor/protocol also exports bindCrdt.
    • No longer public: PresenceWriter (a view’s edytor.presence, still typed), isSuggestionsPlugin, oversizedInlineImage (storableImageSrc answers null for what it flagged).
  • 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 @internal and 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 are historyUndo()/historyRedo(); isComposing stays.
    • 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, Text and InlineBlock: attach, and Block.firstEditableText/lastEditableText.
  • edytor.hotKeys is gone. The instance field holding the view’s keymap is now the internal keymap, so edytor.hotKeys is undefined at run time and edytor.hotKeys.run(chord) throws. The hotkeys option and prop keep hotKeys as an alias (below); the instance field does not. Bind keys through the prop or a plugin’s hotkeys.
  • hotkeys, not hotKeys. The <Edytor> prop (and the Edytor option) is hotkeys, as a plugin’s field is. hotKeys still works as a deprecated alias for one release.
  • prevent records and returns. In every hook and key binding, prevent() and prevent(cb) record the veto and return: the code after it in your hook now runs (it used to throw), so return after it where nothing else should happen. The first call in a hook decides. A try/catch around it no longer swallows the veto. A hook that throws a PreventionError itself still vetoes; PreventionError, isPrevention(error) and the Prevent type are exported from edytor (the prevent function).
  • onAfterOperation narrows. Its payload is AfterOperationPayload (exported), a ChangePayload without prevent per operation, so change.operation === 'insertText' narrows change.payload and change.text. The hook is no longer generic: a hook typed <C extends …>(change: C) becomes (change: AfterOperationPayload).
  • One result channel. edytor.dispatcher.last is a CommandResult (exported): { operation, status, value? }, recorded after onAfterOperation. value is what a handle mutator returned (block.insertBlockAfter‘s block, undefined when refused; when a plugin’s prevent(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 through edytor.document.facade, which skips hooks, normalization, the undo policy and readonly. While the document is empty, the view’s virtual paragraph is edytor.root.children[0] (edytor.facade.virtual() is gone from the declarations). facade.insertBlock/insertBlocks (and their prepare forms) take a JSONBlock too ({ type, content: [{ text }] }, ids kept, minted where missing), so toBlockSpec is only needed to mint fresh ids.
  • Room names. In edytor/cloudflare, attachDocument(this, options) is attachRoom(this, options) (options type AttachRoomOptions) and the cross-room moveBlocks(namespace, move) is moveBlocksBetweenRooms(namespace, move), so neither shares a name with the client’s attachDocument or edytor.moveBlocks. The old names stay as deprecated aliases for one release. attachRoom on something that is not a Durable Object throws attachRoom(this): ….
  • value and onChange are one type. onChange (the prop, the Edytor option and a plugin’s hook) receives a JSONDoc, and edytor.value is a JSONDoc: the type the value prop takes, so a saved value opens as it is. The object is unchanged at run time (it still carries type: 'root'); code that typed it JSONBlock types it JSONDoc.
  • Snippet overrides must name a kind. A <type>Block, <type>Mark or <type>InlineBlock snippet 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> given room and server (or sync) now attaches it, as an editable view does: it loads the room’s content and shows every collaborator’s edit (a live viewer).
    • Switching readonly keeps 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 value at once, and its server render shows only snapshot; value seeds 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 room or server but wanted the static value should drop them; one that created the document and attached the sync itself to get a live viewer can pass room and server instead.
  • A headless document holds the bundled roles. createDocument and loadDocument without semantics now adopt defaultSemantics, 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. Pass semantics: {} for the old behaviour (no roles).
    • A view whose plugins redefine a bundled kind (an image that is not void, a code that is no island) now throws SemanticConflictError on a document you created without semantics: pass that view’s rules, or {}.
    • attachDocument and a view’s own document are unchanged.
  • semanticsOf reads 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 in roles, 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_BYTES 2 MiB (was 64 MiB) and EDYTOR_MAX_INBOUND_FRAME_BYTES 4 MiB (was 64 MiB). DEFAULT_MAX_DOCUMENT_BYTES and DEFAULT_MAX_INBOUND_FRAME_BYTES change 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). Set EDYTOR_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 of data: URL), so two or three reach the new default. Action for documents with images: give createImagePlugin an upload, or raise the document and frame quotas by the images’ size (see quotas).
  • 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 a u/<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 an actor carry the verified user as actor.id.
    • Action: make the document’s actor.id the userId your authorize returns. With another actor id, the room rebinds your client ids to the user id and refuses the client’s own profile.
  • 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.presence counts every message).
  • The room’s alarm is always installed. attachDocument now always installs alarm: a class that defines its own must call document.alarm(), as before.
  • defaultSemantics holds the media kinds. embed, bookmark, file, video and audio are void in defaultSemantics (and mediaSemantics, 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-void video), give your kind another name, or pass your semantics to the room and documents instead of defaultSemantics.
  • Accessibility: roles, names and colors moved. See Accessibility.
    • The slash menu’s rows are now a listbox (.slash-items, with an id) of groups, one per section; .slash-menu itself 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 a combobox. 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, ul and ol elements have role="none" (a list’s items are sibling blocks, never one list’s children). A selector on role or a test reading list roles changes.
    • Grays the chrome uses for text are #73726e (was #7d7a75 and #a19e99), --notion-text-secondary included, and the code block’s syntax colors are darkened to a 4.5:1 contrast (WCAG AA).
  • 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 link mark on it.
    • Mod+click on a link opens it in a new tab.
    • richTextOperations adds linkText(text, start, end, href) and unlinkText(text, start, end).
  • 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 URL upload answers fills its src outside 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 onPaste hook 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 throws SemanticConflictError on a kind two configs declare differently: mergeSemantics(defaultSemantics, semanticsOf(myKinds)) replaces the field-by-field spread. The bundled kind tables richTextKinds, codeKinds and imageKinds are exported beside layoutKinds and richTextMarks. SemanticConflictError is 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 semantics field, semanticsDigest), and the room logs { edytor: 'semantics', user, kinds } naming the kinds it reads otherwise (semanticsMismatch), once per digest; RoomLogEntry has that variant. Nothing is refused, and production builds publish nothing.
  • allowedOrigins. routeDocumentSocket and routeDocumentHistory take a last options argument (RouteDocumentOptions, exported): allowedOrigins, a list of page origins or a predicate, refuses a request from another Origin before authorize (4403 origin not allowed for a dial, 403 for HTTP). Set it when authorize reads 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 (4403 access revoked by default), and setAccess(userId, 'write' | 'read' | 'none') downgrades write sockets in place (the read-only notice; writes denied), closes read-only ones 1012 (access changed, the new CLOSE.accessChanged, redialed) to upgrade them, or closes them all.
    • closeUser throws a RangeError for a close code a socket cannot be closed with (only 1000, 1011, 1012 and 3000 to 4999 can) or a reason over 123 UTF-8 bytes, before touching any socket.
    • authorize may return expiresAt (ms since the epoch): the router closes a dial past it 4401, and the room closes the socket 4401 (expired) at its first message past it or on its alarm, so the provider redials with fresh params.
    • The identity reaches the room in the new X-Edytor-Expires header (IDENTITY_HEADERS.expires); SocketIdentity gains expiresAt; refusals gain the access entry.
  • 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 socket 1011 (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 the admit hook and exposes buffered; metrics() reports buffered: { sequences, bytes }.
  • Index work counters. The debugging surface facade.runsView.debug also 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-visibility stays 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.
    • ToolbarController adds openLinkPanel(), closePanel(focus?), takeFieldFocus() and hovered.
  • 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 types CodeLanguage and CodePluginOptions.
    • A theme rule for [data-edytor-code-language] now styles a select in editable views.
  • Image: alt text, width and alignment. The image block reads data.alt (its alt, "" without one), data.width (CSS px) and data.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 carrying data-align, and the copied HTML carries the alt, a width and the figure’s data-align.
    • New exports: MIN_IMAGE_WIDTH and the types ImageData and ImageAlign.
  • HTML import: a bare <img>. An img with an accepted src is imported as an image block (with its alt and width), not only one inside a figure. An image inside a line (<p>a<img>b</p>, or wrapped in a span as Google Docs writes it) ends the line there: a, the image, then b (HTML import). Before, such an image was dropped.
  • edytor.dispatcher.outside(body) runs commands outside the undo history (admitted, shown to hooks, recorded in dispatcher.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, and richTextPlaceholder gives their captions “Write a caption…”.
  • 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) and aria-keyshortcuts (Alt+F10 for the toolbar); a + or grip that opened a menu has aria-expanded="true". New: edytor.popups (what the root names) and edytor.announcer (say(message)).
    • SlashMenuItem has an id to set on a custom row; BlockHandleSnippetPayload has label, 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 separator the arrows resize (one undo step per press); it is no longer aria-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.
  • Right-to-left text. A block element carries dir="rtl" or dir="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 and findMatches(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.toWellFormed and a regular expression with lookbehind) and the status of real phones and IMEs. Room internals lists the room’s five alarm tasks (forward included, 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 forwards aria-label, aria-labelledby, aria-describedby and id to 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 void and island fields of BlockDefinition describe what the roles do.
  • A whole array assignment takes time linear in the array’s length. block.data.tasks = next (and setData, a root patchData) 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 img whose alt is emoji only, whose class names an emoji or that has data-emoji, or whose width and height are 32 px or less, is imported as its alt text 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 parse hook (the image and the media kinds) is found by its hook only, never by its tag alone: a pasted figure with no img is no longer an empty image block, its caption pastes as text. A claimed void takes only its figcaption’s text as its caption. iframe, video and audio are 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 the onMount guard. 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; tablePrefix prefixes every room table, not two.

From 0.1.0-next.31

Fixed

  • Security fix: links. A link whose href started with an ASCII control character or a space before javascript: (for example \u0001javascript:…) passed sanitizeLinkHref as a relative link, and browsers, which strip those characters, would run it when clicked. Upgrade.
    • The sanitizer now reads an href as 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 is http:, https:, mailto: or tel: (a relative link resolves to none of its own).
    • Links already stored with such an href render without one.
  • License. The package now carries its MIT license (LICENSE, and "license": "MIT" in package.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: or mailto:) over a text range outside a code block now sets the link mark 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 own onPaste still 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 as data-count on [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-count stays 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 the EDYTOR_HISTORY binding) still works, wrapped in kvHistory: write kvHistory(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.store is now a HistoryStore (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 variable EDYTOR_HISTORY to "room" with DocumentRoom), kvHistory(namespace) in KV as before, r2History(bucket) in R2 (bind it as EDYTOR_HISTORY), or any object with maxValueBytes, put, get, list and delete.
    • The room owns retention: nothing past a version’s expiresAt is 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). HistoryEntry gains expiresAt.
  • Per-block locks are built in. lockedBlocks({ key, subtree, bypass }) is a ready-made validate hook (the room’s locks option, DocumentRoom.locks(), or the EDYTOR_LOCKS variable): a block whose data names a user is that user’s alone, and with subtree so is everything under it (per-block locks). A room that overrode validate for 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 by routeDocumentSocket like ?lastUpdated). See first paint from a snapshot.
  • Long pages, opt-in. The Notion theme reads --edytor-block-visibility: set it to auto for content-visibility: auto on 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. onLoad returning JSON works as before, and reset() 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 with sync.writeSyncStep2.
  • Browser stores. This release stores documents in edytor-v14-g5:<name>; the generation-4 database edytor-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 (IndexeddbPersistence option convertPrevious).
    • 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.
  • 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 through onSyncRefused (<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.
    1. Ask users to let open documents sync (or rely on the room’s onSave mirror being current): an edit made offline on the old release is not converted.
    2. Deploy the room Worker. Each room converts its container the first time it wakes; old clients still open are refused (1008) and should reload. Show onSyncRefused as “a new version is available, reload”.
    3. Deploy the app (the site). A reloaded tab runs this release, opens its new browser store and syncs from the room.
    4. 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 old edytor-v14: stores, which miss what was written since.

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 edge also 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-paper trace: 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; defaultSemantics and richTextSemantics carry richTextMarks (the link’s). A mark key name:<id> reads the name mark 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) and bindCrdt(Y).sync.step2Update.

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_DAYS or purgeAfterDays to change it, off / false to 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 call document.alarm() (or super.alarm()), as it already had to with onSave. attachDocument installs alarm unless onSave, history and 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 pass history: { store } to attachDocument, or override history() in a DocumentRoom subclass) and the room writes two versions of its document a day (local noon and midnight in EDYTOR_HISTORY_TIME_ZONE, UTC by default), only when it changed, kept 30 days. Without a binding nothing changes.
    • listHistory(), readHistory(key), restoreHistory(key, { user }) and undoRestore() (also over RPC), and routeDocumentHistory over 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 with attachDocument). 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.
  • 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 an upload for 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 has CompressionStream (on the automerge-paper trace: 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, and compressed() resolves once a compaction’s compression is stored.
  • Validate client edits on the server. A validate option (attachDocument) or a validate(frame) override (DocumentRoom) is asked after each client frame that changed blocks, with the blocks it touched and their state before and after; false makes 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 maxFrameBytes option, also on createWebsocketSync) 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=off silences 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 that routeDocumentSocket answers (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 (and attachDocument) 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 the automerge-paper trace, 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 } to createDocument, loadDocument or attachDocument to keep more (Infinity: every step); document.historyLimit reads it, and a reattach naming another limit throws SemanticConflictError.
  • 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 keeps checked (hidden) and gains level.
    • It used to replace the block’s whole data, so a hook that matched a patchData with an empty path for Turn into now sees one patch per property.
    • To clear properties, delete them or replace the object with block.setData.
  • 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 in semanticsOf for 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 update listener 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 mousedown of every press in its host but in a field (an input, a textarea, a select): in Firefox and Safari a press on the bar between its buttons used to blur the editor, so the next typing went nowhere. A custom toolbar snippet’s buttons no longer need their own mousedown handler.

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 no pointerdown) 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 pointercancel when a native drag starts (a block handle’s drag) and then no pointerdown for the next press, only its mousedown (WebKit bugs 202287, 222632, 279749). The editor now takes a primary mousedown that no pointerdown came before as the press, once (a pointerdown and its mousedown still count once; a script’s mousedown is 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

  • defaultSemantics holds the layout rows. layoutKinds and layoutSemantics are new, and defaultSemantics now 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 no columns block is unchanged.
    • If kinds of your own are named columns or column, the room and a headless document now read them as a layout and its columns.
    • A view whose plugins give columns another defaultChild throws SemanticConflictError on a document created with defaultSemantics: rename them, or pass a semantics without those rows.
  • 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.last reports refused, 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_EVENT is cancelable. A menu that answers a grip click and takes the keyboard calls event.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 call preventDefault() to keep the keys.

New

  • The columns plugin. columnsPlugin, createColumnsPlugin({ minWidth }), isColumnsPlugin and ColumnsPluginOptions add Notion’s multi-column layouts: the kinds columns (a layout) and column (data.width, a weight), made by dragging a block beside another or with the commands columns.2 to columns.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).
  • The layout role. BlockDefinition.layout (and layout in a semantics role row, BlockRole.layout): a layout’s defaultChild is 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?) (and prepare.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) and besideAt(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). mergeBackward of 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; mergeForward at 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. BlockMovePosition gains 'left' and 'right' (edytor.moveBlocks({ blocks, target, position: 'right' }), through placeBeside; refused without a layout kind); hooks see moveBlock/moveBlocks with a beside: { target, side } payload, typed BlockBeside. A move up from a column’s first block, or down from 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, wrappable and wrapBlocks are exported, and the operation hooks see wrapBlocks ({ 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.dragging is reactive: while a text selection is dragged, the block handles and the column resize bands take no pointer (their hosts carry data-selecting).
  • element and contentElement functions 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.addable is always true: 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 next tag: pnpm add edytor@next (replace the tarball URL in your package.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

  • richTextPlaceholder shows nothing in an empty code line.

From 0.1.0-next.13

New

  • Published to npm. The package names its repository (repository in package.json) and a version tag publishes it from CI with provenance: pre-releases under the next dist-tag (npm install edytor@next), latest stays on 0.0.11 until a stable release. No API change.

From 0.1.0-next.12

New

  • Presence can be throttled and narrowed to blocks. New presence prop ({ share?: 'caret' | 'block' | 'none'; throttle?: number }, also new Edytor({ presence }) and the settable edytor.presence, a PresenceWriter). See Sharing less at scale.
    • throttle spaces 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.
  • publishPresence now 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-accent now 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 replace whose 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) gains inPlace. Typing in the folded line unfolds it.

From 0.1.0-next.9

Breaking changes

  • BlockView.handle is Block | undefined. A suggestion’s preview renders your block snippets with no handle. TypeScript now flags block.handle.x in 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.suggestions and block.acceptSuggestedText() still work, as wrappers over an { end: block.id } suggestion. edytor.selection.suggestions is removed: read edytor.suggestions. Three changes:
    • the suggestion stays when the selection leaves the block (it went before);
    • accepting it runs the acceptSuggestion command, which hooks see instead of acceptSuggestedText, and moves the caret to its end;
    • suggestText is 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, replace of blocks or of the selection). See Suggestions.
    • It is streamed with update/append/done, shown in place with the kinds’ own rendering and written by accept() as one command (acceptSuggestion) and one undo step; textToBlocks turns a string or markdown into blocks.
    • suggestionsPlugin (its bar, Mod+Enter, Escape and Tab) is a new default plugin: <Edytor> adds it after yours; list createSuggestionsPlugin({ bar }) to render your own bar.
  • The code plugin’s Tab accepts the line’s end suggestion and its Escape discards it, through edytor.suggestions.

From 0.1.0-next.8

Breaking changes

  • Dependencies: @atlaskit/pragmatic-drag-and-drop 4.0.0 (was 1.7.10), @atlaskit/pragmatic-drag-and-drop-hitbox 3.0.0 (was 1.1.0) and the new @atlaskit/pragmatic-drag-and-drop-auto-scroll 3.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 to block.data, do not preventDefault() 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.

From 0.1.0-next.6

Breaking changes

  • patchData takes 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, and facade.dataItemIds(target, path) lists an array’s ids).
    • The proxies write them: push, pop, shift, unshift, splice and a length assignment are one splice, sort and reverse one order, tags[1] = 'b' and tasks[0].done = true a write of that item; they used to write the whole array.
    • A hook that read a whole array’s new value from value should also handle splice and order (or read block.data in onAfterOperation).
    • delete tags[1] now removes the item.
    • A path segment that is ~ and a lowercase letter names an item, so a headless patchData path 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.
  • 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.data and the new edytor.data are live proxies. Assign to write (block.data.done = true, bind:value={block.data.title}); reads follow the document and are reactive in templates.
    • block.data used 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 patchData operation. block.setData(data) (was setBlock), atom.setData(data) (was setInlineData, now removed from BlockOperations and from Block) and every proxy write dispatch patchData with { ops, atom? }; setBlock with data and Turn into show a patchData step.
    • A hook that matched setBlock or setInlineData for data changes should match patchData, and look inside a replace’s value (an empty path).
    • 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.

New

  • Properties sync per property. A block’s, an inline block’s and now the document’s data is 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. JSONDoc takes an optional data: createDocument({ value }), <Edytor {value}> and a room’s onLoad seed it, toJSON(), the room’s read() and onSave return it, and edytor.value carries it as the root’s data. Headless: facade.patchData(target, ops), facade.docData(), and DocChange.data. Type edytor.data by augmenting EdytorDocData.

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 to block.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 data data: {} used to write an empty object and report applied; empty and absent data are now the same, so convertToKind answers false for 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 a div, 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'] > h2 instead (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.isEmpty and block.hasContent count 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, use block.content.every((part) => !(part instanceof Text) || part.isEmpty) (the old !hasContent; add && !block.children.length for the old isEmpty), with Text from edytor.
  • onDeleteSelectedBlocks runs 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 onDeleteSelectedBlocks does 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+enter in hotKeys.
  • 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, so a:b dials …/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 \ (a ws: or wss: URL reads it as /) split the path (the quick start’s route answers 404), ? and # cut the id short (q?x opened room q), % read as an escape (a%41b opened aAb, and 50%off does not decode, so it is refused 4400), and a tab, LF or CR was stripped (a<tab>b opened ab).
    • 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 | (what encodeURIComponent escapes and a URL path keeps, so 50%off dials 50%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.
  • User ids reach the room as authorize returns them. routeDocumentSocket now percent-encodes the userId into X-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 closed 4403. An id authorize returned with spaces around it is now another user than the trimmed one its client ids were bound to, so those clients are refused (4409, or 1008 refused: replica when authorize passes no replica): trim the id in authorize to keep them.
  • <Edytor server room actor> names its local store without the trailing slashes of server. A view with an actor named its IndexedDB store from server as written, so wss://x/rooms/ and wss://x/rooms kept two stores (and two cross-tab channels, which the store carries); the socket, createWebsocketSync and a view without actor already removed them.
    • An app whose server ends 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}` })}, with server still ending in /. Once sync is passed, the view wires nothing itself: onSyncExpired does not apply (pass onExpired, which puts a fresh token in dialParams), params is read at each dial from the object you pass (keep one object and change its fields, as dialParams here; a new object is never seen), and a room id no URL can carry throws a TypeError instead of reaching onSyncRefused.
  • ., .. 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 and createWebsocketSync now throw a TypeError for them (and for an empty id or one over 256 characters), and routeDocumentSocket closes them 4400. <Edytor server room> does not throw: an editable view gets the 4400 refusal through onSyncRefused without dialing, and a readonly view renders its value.

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.moveBlocks with direction: '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 list a to e leaves b between them, where it used to read b a c. A run that cannot move stays, and the result lists only the blocks that moved. The headless unNestBlocks(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 leaves transact; 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

  • value is the initial content and is no longer bindable: bind:value fails type-checking. Follow edits with onChange or edytor.value.
  • Block, Text and InlineBlock are non-reactive handles over the document, and their constructors are gone. Snippets receive a BlockView ({ id, type, data, selected, focused, handle, void }), not a Block: reads go through block.handle, and writes are the view’s operations, given the ids.
  • Selection is a value set with selection.select(value) or selection.setCaret({ block, offset }). The marks at the caret are selection.projection.marks (was selection.state.currentMarks); marks for the next insertion are selection.stage(marks) / selection.pending (text.markOnNextInsert is gone).
  • The hotkeys module and the HotKeys class are gone. Declare bindings in the hotkeys prop or a plugin’s hotkeys (see Hotkeys); HotKey and HotKeyCombination come from the package root. The editor’s keymap is internal (edytor.hotKeys is gone) and its Keymap class is not exported. Unknown chord tokens (cmd, esc, …) fail type-checking.
  • Block kinds declare defaultChild; the defaultBlock hook, Edytor.getDefaultBlock and Edytor.defaultType are gone (use edytor.defaultChild(parent)). Edytor.getBlockDefinition is replaced by edytor.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 refused instead 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’s placeholder, 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

  • attachDocumentSync is removed: use document.attachSync. The presence format changed (one entry per view in selections), so old and new clients do not see each other’s carets.
  • createWebsocketSync takes { server, room }, the names of the <Edytor server room> props (serverUrl and roomName were removed after a deprecation). It keeps a local IndexedDB copy by default (persist, persistName) and syncs tabs by default (disableBc). It no longer takes connect, protocols or resyncInterval; pass tokens in params.
  • The provider sends the room id percent-encoded as one path segment (acme/roadmap dials …/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.
  • WebsocketProvider lost the protocols option, the sync event (use synced) and wsconnecting (use the status event). It gained saved, unsaved, readOnly (the room’s read-only notice), the 'saved' event, the refused, expired and unreachable events, and the connectTimeout option.
  • IndexeddbPersistence lost get, set and del.
  • The document decides readiness itself: syncFailed, onSyncSettled and EdytorDocSyncPendingError are 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/cloudflare is new: the Durable Object room replaces a coordinator you wrote yourself.

Document API

  • Every facade operation returns an OpResult (applied, noop or refused) 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 the BlockSpec that inserts take.
  • New queries: order, compare, next, previous, canPlace, canMerge, defaultChild, fits, nestParent.
  • facade.onChange reports one DocChange per commit. The per-block subscription API (subscribeBlock, subscribe, blockVersion, snapshot), decorateRuns and the bind* building blocks are no longer exported: use onChange with runs(id), a block kind’s transformText for decorations, and bindCrdt(Y) for engine injection.
  • deleteBlock(id) and deleteBlocks(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) stays true, and re-creating an undone id is refused.
  • A document edited without a view adopts the bundled block roles (defaultSemantics) unless you pass other semantics.
  • Selection anchors are { b, a }; toJSON() gives inline blocks data: {} when they have none.
  • duplicateBlock(id, freshId) calls freshId(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 value is deterministic, so replicas seeding the same template converge. BOOTSTRAP_BLOCK_ID is gone, and seeded blocks have no createdBy.

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 whole data attribute is no longer read.
  • Array items are stored per item. An array is a [] leaf and its items: item id’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 is edytor-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 nonce n (attribution records keyed by it), text ownership as streams delimited by boundary items (the slices attribute is gone; a merge is an item in the text, the claims list is gone), paired marks, shorter ranks and per-writer text deletes that an undo takes back.
  • Schema generation 11 (wire word 14011, browser database edytor-v14-g11:<name>): shared suggestions in the document, a root suggest of 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 (createdBy is absent). BOOTSTRAP_BLOCK_ID is 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) is noop and writes nothing; a reused child id is refused (id-collision); an absent target is refused. moveBlocks answers 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 are DocPosition { 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 takes itemKind(parent), a list’s flat item kind, whose pasted lines become the list’s items. The editor passes it.
    • New helper: toBlockSpec(json, { freshIds? }).
  • Liveness. Deleting a block that is not live (already deleted, merged away, under a deleted parent) is refused (was true); blockText of a block under a deleted parent is null.
  • 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 of kind sit directly under parent) and nestParent(ids, parent) (where Tab nests them: parent, or a container’s last item).
    • A list holds only its items: canPlace answers false and moveBlocks is 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).
    • nestBlock into 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.
  • 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, imageSemantics and layoutSemantics hold the bundled plugins’ rows (defaultSemantics the other four: the columns plugin’s layout rows too, though it is not a default plugin; layoutKinds is the columns plugin’s kind table) and are deeply frozen.
    • semanticsOf(...tables) (with the KindSemantics row type) builds a config from kind rows. To extend a bundled config, merge roles, rendersContent and defaultChild field by field, since a top-level spread drops the bundled rows.
    • A document adopts roles as mergeSemantics merges them: a view’s or a reattach’s declaration that disagrees with the document’s is a SemanticConflictError whose existing and incoming are 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 aliases setBlockData and setInlineData are removed). See Properties.
    • target is a block id, { block, atom }, or null for the document; ops are { 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.dataItemIds lists the ids.
    • facade.docData() reads the document’s own data, JSONDoc.data holds it (seeded, exported by toJSON only when present), and SerializableContent includes arrays.
  • Atomic data paths. A kind’s role (BlockRole, a block definition, a semanticsOf row) may declare atomic paths: a write there writes the whole value as one property, so concurrent assignments never merge into a mix of both. Roles compare their atomic sets when adopted.
  • A retype keeps the properties. setBlock with data (Turn into, a markdown shortcut, the slash menu, Backspace at the start of a kind) sets the properties it names, one patchData patch each, and removes none: a to-do turned into a heading keeps checked and gains level. It used to replace the whole object. Use patchData(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.limit steps (DEFAULT_HISTORY_LIMIT, 200; Infinity keeps every step); a dropped step releases the deleted content it kept. document.historyLimit reads it; a reattach naming another limit is a SemanticConflictError.
  • 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 root released). The view calls it when its page leaves for good. See history.
  • Change report. facade.onChange(cb) delivers one DocChange per 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 in moved/meta/content, not folded into the subtree. A write made while another transaction’s change is being reported (in an update listener 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’s transformText for local decorations. Gone:
    • the per-block subscriber API (subscribeBlock, subscribe, blockVersion, snapshot on the facade and the index), decorateRuns and 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.
  • 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; modifyAwarenessUpdate is removed) and messagePermissionDenied/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 and RangeCursor. 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 maintained node.delta and clearCache, node.change, a node’s 'delta' event, Node.from, a delta inserted as content, and event.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, the beforeObserverCalls and afterTransactionCleanup events: the document’s commit event, then afterTransaction, 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, compareRelativePositions and the delta-position helpers): idAtIndex and indexOfId are a position’s id and live index;
    • subdocuments, the load state and the JSON, embed and subdocument contents (ContentDoc, ContentEmbed, ContentJSON), a transaction’s beforeState, afterState, meta and cleanUps;
    • snapshots (Snapshot, snapshot, createSnapshot, emptySnapshot, createDocFromSnapshot, encodeSnapshot, encodeSnapshotV2, decodeSnapshot, decodeSnapshotV2, equalSnapshots, snapshotContainsUpdate, nodeMapGetSnapshot, nodeMapGetAllSnapshot, the snapshot argument of node.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), and getNodeChildren, getPathTo, tryGc, undoContentIds, with document.attribution.legacy(): the a/ 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(), see Doc.keepReplaced).
  • Anchors are { b, a }: the o owner facet and the a: -2 form are gone from the selection value, the presence wire and history entries.
  • Attribution. Undo and redo keep a block’s record (createdBy survives an undo/redo of its creation on every replica). The opt-in per-block lineage ring (the lineage document 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: actorOf resolves a client id that wrote, actors lists the actors whose clients wrote.
  • facade.toJSON() inline atoms carry data: {} when they have no data (the shape edytor.value already had).
  • Block deletes promote children. deleteBlocks(ids) and deleteBlock(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) stays true for 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.history is created by facade.createUndoManager as 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 edge decides where a concurrent insert at its ends lands. DocumentSemanticsConfig.marks holds mark edges for a document without a view (richTextMarks, in defaultSemantics); views adopt their mark records’ edge. A key name:<id> reads the name record (one mark per comment). markName, MarkEdge, facadeConfigOf.
  • The document’s own undo manager. The engine has no undo manager; document.history and createUndoManager({ trackedOrigins, captureTimeout, limit, captureTransaction }) are edytor’s (YUndoManager): observe(f) for its steps, undo()/redo() returning the step, clear() (was facade.releaseHistory(um)); the engine exports keepItem and followRedone, and redoItem takes (…, itemsToDelete, deletedByHistory?).
  • One update encoding (generation 6). edytor/crdt reads and writes one update encoding, the columnar one (applyUpdate, encodeStateAsUpdate, mergeUpdates, diffUpdate, decodeUpdate, UpdateEncoder, UpdateDecoder, the update event); applyUpdateV2, encodeStateAsUpdateV2, mergeUpdatesV2, diffUpdateV2, decodeUpdateV2, readUpdateV2, the v1 and v2 encoder and decoder classes, convertUpdateFormatV2ToV1 and the updateV2 event 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) and sync.writeSyncStep2 (readSyncStep1, readSyncStep2, readUpdate and readSyncMessage are 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) and besideAt(id, kind?).
    • mergeBackward of an item’s first block merges into the previous shown line in reading order and mergeForward crosses 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).

Editor view, selection and commands

  • Development-only misuse checks. Combining document with doc/awareness/actor/requireHydration, and dispatcher.outside inside 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 selectionchange still queued) is read first, so a shortcut right after them acts on the selection the user sees.

  • One write API. EdytorDocument carries DocumentOperations (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.facade is deprecated; the types the operations use are exported from edytor. document.block(id) (DocBlock) is removed.

  • selection.select(value) takes the value only; the dispatcher publishes last, permits(), run, each, dispatch, lead, caret and outside, the rest is internal.

  • edytor.focus() focuses the editor, keeping its selection or putting the caret at the start; selection.value, selectedBlocks, focusedBlocks and dispatcher.last are 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’s upload, KindUpload, with its send) 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’s preview and progress, the file row’s uploading and progress). Files dragged from outside show the block drag’s drop line and land there, the page scrolling near its edges; onPaste gets that place as at. The file drop comes with the first media plugin given an upload: without one, the editor ignores a drop carrying files.

  • Markdown paste. A text/plain paste 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, a DOMParser given on a server), textToBlocks (the full reader: GFM tables, code languages, nested marks, streaming: true; edytor’s, which paste reads, is unchanged), bundledForms and each bundled plugin’s forms (richTextForms, codeForms, tableForms, …); kind, mark and atom records take a markdown form. 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.

  • value is not bindable. <Edytor value> is the initial content; bind:value fails type-checking. Read edits with onChange or edytor.value.

  • Component props. New: document (an EdytorDocument to render; several views can share one), actor (the local author), room, server and params (the view builds its IndexedDB copy and its websocket sync from them), onSyncExpired (the room closed with 4401; refresh params before the redial) and onSyncRefused (a refusal standing at mount, then each new one), defaultPlugins, and the root attributes translate, spellcheck, autocorrect, autocomplete, autocapitalize, inputmode and enterkeyhint. sync takes an EdytorSync (a factory from createIndexeddbSync/createWebsocketSync, or your own) and overrides room/server. hotkeys is typed (see Keymap below). See the component.

  • Handles. Block, Text and InlineBlock are read-only, id-only handles over the document index: getters read the document (inside a command they see its writes); they are not reactive (except data, a reactive read). Templates read the snippet’s view object or edytor.cells. Every write is an operation of the view, given their ids.

    • new Block({block}), new Text({…content}) and new InlineBlock({block}) are gone: use edytor.insertBlocks(destination, blocks), edytor.insertText and edytor.insertInline.
    • A Text is the ordinal-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, _items are gone; a dead block’s parent is undefined).
    • edytor.idToBlock is the handle registry (get(id), block(id), text(blockId, ordinal), atom(blockId, atomId), parts(id)); edytor.idToText, edytor.idToInlineBlock, Edytor.getTextById, Block.partOffsetOf/atomOffsetOfPartIndex/projectedParts are removed (a text’s display offset is text.segStart, a block’s parts edytor.idToBlock.parts(id): read-only, each with its display start and end, a text’s text, runs and segOrd, an atom’s id, type and data).
    • InlineBlock.type has no setter. Block.firstText/lastText are undefined for a kind that renders no content.
    • New getters: Block.isContainer (a block that shows only its children, such as a list), Block.isListItem and Block.list (the list an item shows in); Block.convertible is false for a list container (its items convert).
  • Emptiness counts inline atoms. block.isEmpty (no content and no children) and block.hasContent count 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, use block.content.every((part) => !(part instanceof Text) || part.isEmpty) (the old !hasContent; add && !block.children.length for the old isEmpty).

  • Data writes are operations. edytor.patchData(target, ops) writes block, atom ({ block, atom }) and document (null) data: refused on a readonly view, shown to onBeforeOperation, recorded in dispatcher.last, its own undo step (typing into the same string properties joins one). block.data, atom.data and edytor.data are plain state: an assignment, a delete or an array method at any depth is a patchData, and the writes of one task are one.

  • Definitions. edytor.definitionOf(type) is the one lookup and never throws (getBlockDefinition is 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.container is removed: use edytor.node.

  • Op results. Every operation of the view answers its OpResult (refused when a hook vetoed it or the view is readonly), also inside an outer edytor.transact; ids name 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. onSelectionChange fires 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 setters setAtTextOffset, setAtRange, setAtTextsRange, setAtBlockRange, selectBlocks, addBlockToSelection and removeBlockFromSelection are removed: read projection and caret, write setCaret({ block, offset }) and select(value).

    • The projection facts moved to selection.projection: content (and its length), marks (was state.currentMarks), isAtStartOfText/isAtEndOfText/isAtStartOfBlock/isAtEndOfBlock, isTextSpanning, islandRoot/voidRoot (block ids; isIsland/isVoid are !== null).

    • The caret anchors are the value’s (relativePosition/endPosition → selection.value.anchor/focus); contentParts, startNode, endNode and yTextContent are gone.

    • setRangeStateAtTextOffsets and setCollapsedStateAtTextOffset are removed with the setters above: setCaret({ block, offset }) and select(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.markOnNextInsert is 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 defaultBlock hook, Edytor.getDefaultBlock and Edytor.defaultType are removed: a kind declares defaultChild; 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 lines island 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 (canMerge refuses 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. BlockMoveRequest is { blocks } & ({ target, position } | { direction: 'up' | 'down' | 'in' | 'out' }); BlockMoveDirection and 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.nestBlock and edytor.unNestBlock too, 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, direction out) 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).
    • BlockMovePosition gains left and right: 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 the placeBeside operation.
  • Keymap. The hotkeys module is deleted: the types move to the package root (HotKey, HotKeyCombination; HotKeyModifier, Single/DoubleModifierCombination removed). HotKeys → the editor’s internal keymap, whose Keymap class is not exported (isHotkey → handle, run(chord), offered; no init).

    • A HotKey payload’s event is optional. A key binding runs once per occurrence.
    • Chords take up to three modifiers in any order, plus punctuation and f1–f12; space matches the space bar. Unknown tokens (cmd, esc, return, …) fail type-checking and warn in development.
    • The hotkeys prop is typed Partial<Record<HotKeyCombination, HotKey>>.
  • 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) and edytor.composition (the session: live, phase, host, owns(node), ended(fn), restructured(change)) are new; edytor.isComposing is read-only.

    • Removed: compositionState, compositionStartReplacementState, hasHandledCompositionInput, compositionText, resolveCompositionRegion, shouldIgnoreCompositionKeyDown, Text.toCompositionDomOffset, and the input-fallback flags and timers on Edytor.
    • 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.
    • onBeforeInput no longer sees fabricated paste, drop or keydown-fallback events. preventUnsupportedDrop(event, edytor?).
  • 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).
  • Nothing selected, nothing written. With the selection none, typing, Backspace, Delete, Enter and an IME composition write nothing (dispatcher.last is refused; 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.dragging is 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; selectedBlocks holds 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.facade is a per-view object whose prototype is document.facade, and edytor.facade.virtual() names the virtual paragraph while the document shows no block (edytor.root.children then holds its handle; edytor.value.children is 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 }) (default mention) defines one inline kind per instance, rendered and copied with its char, with the kind in data-edytor-mention and an HTML form that pastes back; Trigger.name names a trigger’s menu (controller.trigger.name).
  • Private plumbing. A controller’s or handle’s member read only inside its own class is a #private field (BlockHandleController.activateBlock and handleKeyDown, BlockMenuController.matchingKinds, the trigger menus’ activeRange, InlineBlock._def among them).
  • One factory per plugin. Every bundled plugin is a factory, called with or without options (createRichTextPlugin(), createMarkdownShortcutsPlugin(), …); the plugin constants and isImagePlugin, isSuggestionsPlugin, isColumnsPlugin and isTablePlugin are 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) and option(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, from selected.
  • Table operations are the table plugin’s: insertTableRow, deleteTableRows, insertTableColumn, deleteTableColumn, moveTableColumn, moveTableRows and fillTableCell are exported from edytor and take the document first (document.apply(insertTableRow(document, table, 1))); the table reads stay on the document.
  • The details and horizontalRule kinds are gone: they were other names for toggle and divider.
  • 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 upload option (ImagePluginOptions, FilePluginOptions, VideoPluginOptions, AudioPluginOptions): that kind’s uploader for its empty block’s Upload and its pasted and dropped files; a kind’s record upload (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’s placeholder (the first plugin that declares one). <Edytor> takes no snippet or placeholder prop.
  • Input rules and triggers (InputRule, Trigger) run through the hooks of the plugin that returns withRulesAndTriggers(edytor, definitions, { inputRules, triggers }): its rules after its own onBeforeOperation, its trigger menus’ keys before its own hotkeys. 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. onBeforeOperation sees 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 as payload and effect on the change. onAfterOperation fires 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.
  • onDeleteSelectedBlocks runs 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) and dispatcher.last reports refused.
  • 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 of Commands (insertDivider, moveText, …); Enter’s lift is splitBlock; markdown and slash conversions are setBlock with a deleteText step; word deletes are deleteRange or deleteText; handle in/out are moveBlocks or unNestBlocks. Browser-typed text is adopted as insertText/deleteText and can be vetoed (the text re-renders).
  • Errors. Top-level operations report refused (edytor.dispatcher.last.status) instead of throwing PreventionError; text operations refuse in readonly; a read-only (quarantined) document refuses instead of throwing SchemaMismatchError; 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() and historyRedo() set dispatcher.last too: applied, noop on an empty stack, refused on 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. BlockDefinition gains element, contentElement, viewState, lines, layout, rendersContent, defaultChild, itemKind, continues, container, presets, empty, html, plain, parse; snippet is optional (schema is removed). One label per kind (Text, To-do list, Toggle list).
    • element and contentElement take 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 (with island and defaultChild) 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 in semantics take lines too).
    • layout: true (with defaultChild, its column kind) makes a layout, like the columns plugin’s columns: 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 in semantics take layout too: layoutSemantics).
    • itemKind on a list container names the flat kind its items show as (numbered-list-item for ordered-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.
    • MarkDefinition gains edge, toolbar, tag, attributes, parse; InlineBlockDefinition gains plain. convertToKind, KindRow, KindPreset are exported; edytor.kinds is 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.attach and BlockView.attach/InlineBlockView.attach are removed; use:block.void still marks inner chrome). Block snippets receive block: BlockView = { id, type, data, selected, focused, handle, void }; inline-atom snippets block: InlineBlockView = { id, type, data, selected, handle } (handle is undefined for a suggested atom). Document reads go through block.handle; writes are the view’s operations, given the ids. onBlockAttached runs once per element, and the attach hooks may return a cleanup. Identity attributes are declarative (present in server-rendered HTML).
  • transformText receives 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); insertText without 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 controller sharedSuggestionsController(edytor) (SharedSuggestionsController): suggesting (suggesting mode: the view’s writes are a suggestion in the document, of text and blocks only, the rest refused with the suggestions.notSuggested announcement, SuggestionsLabels), add(at, content, { via }) (an AI answer written live), changes(), decide(changes, accept), acceptAll(), rejectAll(); edytor.suggestions.list holds SharedSuggestions (shared: true, by, via, changes, canDecide, mine, reject(); discard() rejects it, its author’s too) beside the view-local Suggestions (shared: false), AnySuggestion either; the commands acceptSuggestion ({ changes } for a shared one) and rejectSuggestion; SuggestedChange; adoptSharedSuggestions(document) in edytor/crdt/edytor. With them built over the document, toJSON(options?) and edytor.value leave pending suggestions out ({ suggestions: true } keeps them). See shared suggestions.
  • A shared answer’s live updates. Each update keeps 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 its id it continues what the earlier one wrote. via is the suggestion’s record’s: undefined for 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.suggestions proposes content at a position, session-only until accept() (one command, acceptSuggestion, one undo step), with the default suggestions plugin’s keys, createSuggestionBarPlugin’s bar and textToBlocks (Suggestions); BlockView.handle is undefined in a suggestion’s preview. An { end } suggestion survives selection changes. block.suggestText, block.suggestions, block.acceptSuggestedText, edytor.selection.suggestions, rawSuggestions and 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 (parse hooks on kind and mark records; see clipboard). A plugin’s onPaste still runs first. The code plugin highlights through TanStack Highlight, and the package declares sideEffects so it (and its CSS) ships only in apps that import createCodePlugin.
  • 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 are h1–h3; a missing level is h1 and any other renders and copies as h3.
    • 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.group and EditorCommand.hint are new; richTextOperations(edytor).removeMarkAtRange(mark) is new.
  • Columns (opt-in). createColumnsPlugin({ minWidth }) and ColumnsPluginOptions: Notion’s multi-column layouts (the kinds columns and column, a column’s data.width a weight), not a default plugin; see Columns.
    • The layout commands are columns.2 … columns.5 (“2 columns” …, group Layout, found by /col3, /columns3 and /column 3 too), 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, wrappable and wrapBlocks are exported; the operation hooks see wrapInLayout): “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.
  • BLOCK_ACTIVATE_EVENT is cancelable: a menu that answers a grip click and takes the keyboard calls preventDefault(); unanswered, the editor takes the focus after the click, so Backspace and Shift+arrows act on the selected block.
  • Default plugins. <Edytor> appends createSuggestionsPlugin() and createRichTextPlugin(), in that order, after your plugins unless 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 the allowNesting option, 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) and createImageToolbarPlugin({ toolbar }) are exported. The image kind stores data.src, has an “Image” preset in the Media group, 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 } }) and createCalloutIconsPlugin({ picker, icons }), CALLOUT_ICONS, CalloutIconPicker; labels emptyBody and calloutIcon; kind records take body.
  • Block colours, toggle headings, page block, table of contents. Blocks store data.color and data.background (palette names the block menu’s Color sets, rendered as data-edytor-color/data-edytor-background and painted from --edytor-color-<name>/--edytor-background-<name>; BLOCK_COLORS, setBlockColor); the rich text toggle-heading kind (Toggle heading 1 to 3, markdown > in a heading and # in a toggle, through KindPreset.markdownFrom); createPagePlugin (a void page linking to another document) and createTocPlugin (a void toc listing the headings), their roles in defaultSemantics.
  • 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() and createAudioPlugin() add void embed, bookmark, file, video and audio kinds (opt-in, Media presets, roles in defaultSemantics/mediaSemantics).
    • Exports: EMBED_PROVIDERS, embedSourceOf, EMBED_SANDBOX, EMBED_ALLOW, safeWebUrl, safeMediaSrc and the types EmbedProvider, EmbedPluginOptions, BookmarkPluginOptions, BookmarkPreview.
    • An embed’s frame plays only an allowlisted provider’s https: player, sandboxed, never srcdoc. 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, video and audio when one of them claims them; a void kind with a parse hook is found by its hook only and takes only its figcaption’s text.
  • 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 }) and createBlockHandlesPlugin({ handle }), with the types SlashMenuOptions, SlashMenuController, ToolbarOptions, ToolbarController, BlockMenuController, BlockMenuAction, BlockHandleSnippetPayload (beside: Alt+click adds a column right of a column block’s; haspopup) and BlockHandleController; the slashMenuPlugin, toolbarPlugin, blockMenuPlugin, findPlugin and blockHandlesPlugin instances and the blockHandles prop are gone. The Notion-style markup is the ready-made menus. The toolbar and block menu place the element marked data-edytor-toolbar-bar / data-edytor-block-menu (was their data-testid). A press in the toolbar’s host never takes the editor’s focus (its mousedown is cancelled but in a field), so a toolbar snippet’s buttons need no mousedown handler.
  • 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), whose attributes or link (ControlAttributes, MediaLinkAttributes) carry the marker, the ARIA and the action. createFilePlugin takes FilePluginOptions.
  • 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 are MenuItemPayloads, { item, id, selected, run, select, option }).
    • The controllers’ attachments carry the keys and the ARIA: popup, keys, option(index), the block menu’s flyoutMenu, the toolbar’s linkField (an id unique per editor), the image toolbar’s bar and altField, an empty block’s field.
    • The options: the slash menu’s menu, a trigger’s menu (mention, page link), the block menu’s menu, the toolbar’s toolbar and card, the embed and bookmark plugins’ menu (the menu a pasted URL opens, named by the root), createMediaEmptyPlugin’s empty (every empty image and media block), createImageToolbarPlugin’s toolbar, createCalloutIconsPlugin‘s picker, the comments’ card (CommentCardPayload, a thread or the one being written) and header, createSuggestionBarPlugin’s bar (with mac), the find bar, the marquee’s box. The version history is a controller, VersionHistory.
    • Types: OptionAttributes, UrlPasteController, UrlPasteOption, UrlPasteOffer, ImageToolbar, ImageControls, ImageBox, MediaEmptyController, MediaEmptyFailure, MediaKind, KindUpload.
    • The table’s grip, menu and add (TableGripPayload with its grip attachment, TableChrome with items, popup, keys, option(index), TableAddPayload); the code block’s header and menu (CodeHeader with its button attachment, LanguageMenu with items, keys, popup, option(index)); the equation’s panel (EquationEditor with its field attachment); the block handle’s expanded, controls, haspopup, beside and add(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]).
  • Heading and quote block elements are divs. The rich text heading and quote used 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 a div; the h1–h3 or blockquote is the kinds’ new contentElement, which wraps only the block’s own text, and nested blocks follow it in a sibling div. 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 a div inside a heading, and a test locating h1[data-edytor-id=…] locates [data-edytor-id=…] > h1.
    • A plugin that restyles heading or quote keeps the tag: content() renders inside it.
  • 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 insertParagraph as 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). richTextOperations gains linkText and unlinkText; ToolbarController gains openLinkPanel, closePanel, takeFieldFocus and hovered. 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, CodeLanguage and CodePluginOptions are exported; a code block’s language is its data.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, in defaultSemantics as equationKinds) and an inline equation atom (inlineEquation), TeX drawn by KaTeX loaded on demand (from jsDelivr by default, KATEX_VERSION at KATEX_CDN; or from a URL, or your bundle through a loader, katex being 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. InlineBlockDefinition takes html and parse.
  • Marquee selection (opt-in). createMarqueePlugin({ container, threshold, box }), MarqueePluginOptions and MarqueeBoxPayload: 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’ slash keywords by 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 a locale, hidden properties kept) and edytor-chrome (the ready-made chrome’s plugins, snippets, words and HistoryPanel), 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 as data-placeholder on the empty text element with a shipped ::before rule (style [data-placeholder]::before); [data-edytor-text-placeholder] and its click handlers are gone. edytor.placeholderRepair is removed.

  • Chrome lives in [data-edytor-overlay], a sibling after the host: block handles (in document order), the drop indicator (position: absolute, not in document.body), menus (position: fixed inside the layer) and layer-relative remote carets. --edytor-handle-offset-y is 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/previousBlock answer null past 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 textContent has 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.cells is new (the view’s render cells); refreshEditorDom/editorDomRevision are 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 id on a block element, open on a toggle) are never reverted. A foreign delete across blocks (an extension’s or a script’s Range.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. patchData writes 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 with data-edytor-block and data-edytor-type but no data-edytor-id or text elements. Select live blocks with [data-edytor-id]. The Notion theme styles them (--edytor-suggestion-*).

    • A replace marks its blocks data-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.
  • 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.

  • autocapitalize is 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 (its textContent is ''), 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 inputmode to none (no virtual keyboard over selected blocks), over the inputmode prop.

  • 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’s scroll-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; contentElement wraps only its own text (content()), and a snippet override keeps both. The rich text heading is a div holding an h1–h3, a quote a div holding a blockquote, their nested blocks after that tag: style [data-edytor-type='heading'] > h2, not h2[data-edytor-type='heading'].

  • Marks by tag. A mark record declares tag (and attributes from 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.html is replaced by tag/attributes; snippet is optional (a snippet still renders inside a core <span data-edytor-mark>). Selectors such as [data-edytor-mark="link"] a become a[data-edytor-mark="link"].

    • Built-ins: bold strong, italic em, underline u, strike s, code code, link a (sanitized href, target), superscript sup, subscript sub, color and highlight span with a sanitized style.
  • 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 selection data-selected="true".

  • --edytor-trailing-space. The root has a bottom padding (2em by 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 blocks content-visibility: auto and contain-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 legacy selection mirror, startTextId/yStart fields and numeric fallbacks are gone. A view writes only its own key and clears it on destroy. publishPresence replaces createAwarenessSelection/publishAwarenessSelection/clearAwarenessSelection; attachDocumentSync is removed (use document.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 was 0, every change): presence={{ throttle: 0 }} restores every write.
  • Presence cost. The presence prop ({ 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).
  • createWebsocketSync takes server, room, params, maxBackoffTime, connectTimeout, onExpired, WebSocketPolyfill, disableBc, persist and persistName (connect, protocols, resyncInterval, serverUrl and roomName are removed).
    • It persists locally by default: an IndexedDB store beside the socket (persist: false opts out, persistName renames it from edytor:<server>/<room>; the returned sync’s persistName is the name to pass to clearDocument), skipped where there is no indexedDB, attached through the new EdytorSyncPayload.attach. While the store exists it carries the cross-tab channel; disableBc turns both off (IndexeddbPersistence gains a disableBc option).
    • connectTimeout (default 10 000 ms, Infinity for 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/roadmap dials …/rooms/acme%2Froadmap. An id a URL cannot carry ('', ., .., over 256 characters, or with a lone surrogate) throws a TypeError at construction.
    • onExpired(state) runs on each 4401 close ({ reason, attempts, nextRetryMs }): put a fresh token in params before the redial.
  • WebsocketProvider: removed the protocols option and field (pass tokens in params, read at every dial), the sync event (use synced), wsconnecting (the status event carries it) and the settle window (syncSettleMs). resyncInterval stays a provider option only. The BroadcastChannel leg stays and is on by default (disableBc opts out); it relays other tabs’ edits to the server. New:
    • saved, unsaved and the 'saved' event (the room’s messageSaved acknowledgements), and readOnly (true once the room’s read-only notice arrives, with no event; a read-only socket counts nothing as unsaved, so check readOnly to learn that edits were never stored: see saved state);
    • messageChunk reassembly;
    • the refused event (a SyncRefusedError on a 1008 close or a 4xxx close other than 4401, after which it stops dialing), the expired event (a 4401 close: expired credentials; the provider redials after the backoff with the re-read params) and the unreachable event (the backoff cap grows to 30 s after 8 dials that never synced);
    • the connectTimeout option.
    • A room fault (1011) after a sync also grows the backoff, until the room acknowledges every local update again. The provider sends a text ping after 15 s of silence, and a text pong counts as liveness.
  • Readiness. The document decides readiness itself: syncFailed, onSyncSettled and EdytorDocSyncPendingError are gone; whenSynced exists on both providers and synced is the lifetime claim.
    • A lone first client is ready after DEFAULT_READINESS_BOUND (1 s, per factory EdytorSync.bound; createWebsocketSync arms it from the socket’s open or first failed dial through the new EdytorSyncPayload.armBound); history refuses while pending.
    • A refusal never seeds: document.syncRefusal and document.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) beside synced: 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 next armBound(): a 4401 before the first sync holds it, so an empty document waits for a dial that gets in instead of seeding.
  • 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 by createWebsocketSync from the WebsocketProvider’s new access event; a suggest-only permission-denied is not a failure. The comments plugin lets a comment or suggest user comment from a read-only view (CommentRequest’s anchors, 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 throws DocumentDestroyedError.
  • 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/del are removed (the custom store holds only the generation record).
  • Provider listeners. IndexeddbPersistence and WebsocketProvider keep one _unlisten (their document and presence listeners’ teardown) instead of _storeUpdate, _updateHandler and _awarenessUpdateHandler.
  • SSR. <Edytor> releases the document it created in onDestroy, 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/collaboration and bindCrdt(Y).providers); routeDocumentSocket answers GET <room>?snapshot and the room’s PROBE_HEADER takes snapshot ({ lastUpdated, document }, 503 while the room has no document).
  • Offline coverage. prefetch(options: PrefetchOptions): Promise<PrefetchResult> and lastUpdated(options: LastUpdatedOptions) (package root and bindCrdt(Y).providers); DocumentOptions.requireHydration, EdytorDocument.requireHydration, EdytorOptions.requireHydration and the <Edytor requireHydration> prop; the room’s lastUpdated() (RPC), its meta table and PROBE_HEADER; routeDocumentSocket answers GET <room>?lastUpdated.
  • Outbound chunking. WebsocketProvider and createWebsocketSync take maxFrameBytes (default MAX_FRAME_BYTES) and chunk larger frames; the room reads messageChunk inbound (closing 1011 chunk sequence lost on a part without a start). The image plugin exports MAX_INLINE_IMAGE_BYTES and storableImageSrc.

The room (edytor/cloudflare)

  • edytor/cloudflare (new). DocumentRoom, attachRoom and routeDocumentSocket(request, namespace, documentId, authorize) replace the coordinator you wrote yourself; see the room.
    • The entry also exports AttachedDocument (what attachRoom returns: the socket handlers plus transact, read, compact, dropWaitingDeletes, reset and 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 defaults DEFAULT_MAX_ROW_BYTES, DEFAULT_COMPACT_AFTER and DEFAULT_SAVE_AFTER, and the caps MAX_REFUSALS and MAX_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, DocumentNamespace and DocumentIdentity.
    • requestedReplica(request) reads the dial’s client id for authorize, and closedSocket(code, reason) turns a dial away from your own Worker with a close the provider understands (an HTTP error reaches the browser as 1006, 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 applies defaultSemantics to server edits.
    • Access levels. DocumentIdentity.access (DocumentAccessLevel: read, comment, suggest, write), carried by X-Edytor-Access and SocketIdentity.access; the room tells each socket its level as it joins (the auth message messageAccess, writeAccess in edytor/protocol). A suggest socket’s frames keep only suggestions (refusal suggest-only); a comment socket’s comments get their anchor from the room; restores need write. setAccess(user, level) takes every level and 'none'.

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 (encodeStateAsUpdate without 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.keepCopies came and went). bindCrdt(Y).admission.admitUpdate takes 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 (CompressionStream is required). The generation record is GenerationRecord (engine, protocol, schema), with no storage format. An IndexedDB row is an ArrayBuffer. The room’s records(kind?) returns StoredRecords, { kind, record, bytes } (a compressed snapshot inflated) and compressed() is new (also over RPC).
  • Room quotas. maxDocumentBytes, maxUpdatesPerSecond and maxInboundFrameBytes (EDYTOR_MAX_DOCUMENT_BYTES, EDYTOR_MAX_UPDATES_PER_SECOND, EDYTOR_MAX_INBOUND_FRAME_BYTES; defaults DEFAULT_MAX_DOCUMENT_BYTES, DEFAULT_MAX_UPDATES_PER_SECOND, DEFAULT_MAX_INBOUND_FRAME_BYTES); a write past one closes its socket 4413 (CLOSE.quota; the close-code table CLOSE is now exported from edytor/crdt/edytor), refusal reason quota. createChunkReader(maxBytes?) throws ChunkLimitError for a sequence announcing more.
  • Document size warning. documentWarning (EDYTOR_DOCUMENT_WARNING, default DEFAULT_DOCUMENT_WARNING, 0.8): the room logs { edytor: 'size', bytes, limit, share } once when the document reaches that share of maxDocumentBytes; metrics() reports documentLimit.
  • Room validation. AttachRoomOptions.validate(frame) and DocumentRoom.validate, with a FrameValidation: { user, replica, touched, dataChanged, before, after, facade }, before/after returning a ValidatedBlock ({ id, type, data, content, parent }) or null; false or a throw denies, and the room undoes the frame (refusal entry denied). Per-writer marks of another writer are stripped (refusal reason mark). um.clear() drops every step of a history createUndoManager made and releases what they kept, by the history limit’s rule.
  • Room metrics and log. metrics(), RoomMetrics and Timing; the log option, DocumentRoom.log, RoomLogEntry and EDYTOR_LOG.
  • Re-seeding. The room rebuilds a document that grew from its content as a new epoch (the reseed option, ReseedOptions, DocumentRoom.reseeding(), EDYTOR_RESEED, reseed(), epoch, metrics().epoch, the DEFAULT_RESEED_* defaults, the reseed and rebase log entries); the dial names the document’s epoch (epoch=), the room answers an earlier one with messageEpoch and reads its messageRebase, admits what the rebase writes as the user’s update, and closes 4410 (CLOSE.reseeded); createWebsocketSync dials 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 history option of attachDocument (HistoryOptions: { store, retentionDays, timeZone, maxValueBytes }), DocumentRoom.history() (the EDYTOR_HISTORY binding with EDYTOR_HISTORY_RETENTION_DAYS and EDYTOR_HISTORY_TIME_ZONE by default); DEFAULT_RETENTION_DAYS and HISTORY_MAX_VALUE_BYTES. See History and purge.
    • The room’s listHistory() (HistoryEntry[]), readHistory(key), restoreHistory(key, { user }) (RestoreResult, origin RESTORE_ORIGIN), undoRestore({ user }) and historyWritten(), also over RPC, and routeDocumentHistory(request, namespace, documentId, authorize) for HTTP.
    • Refusal reason history; RoomMetrics.history; log entries history and restore. bindCrdt(Y).doc.restoreTo(doc, facade, json) is the restore itself.
  • History stores. HistoryOptions.store takes a HistoryStore (maxValueBytes, nativeTtl, put(key, value, { expiresAt, metadata }), get(key), list(prefix, cursor) of HistoryStoreRecords, delete(key)), or a HistoryStoreFactory over the room’s storage (HistoryRoomStorage); a KV namespace (KVLike) goes through kvHistory.
    • Adapters kvHistory(namespace), r2History(bucket) (an R2BucketLike) and roomHistory({ maxBytes, maxValueBytes }), with R2_HISTORY_MAX_VALUE_BYTES, ROOM_HISTORY_MAX_BYTES and ROOM_HISTORY_MAX_VALUE_BYTES; HistoryMetadata is exported; HistoryEntry.expiresAt.
    • EDYTOR_HISTORY takes a KV or R2 binding or "room"; the alarm’s retention task deletes expired versions.
  • Concurrent creations of one id. The losing node of a concurrent creation of one block id keeps its subtree (isKeptReplaced exported from edytor/crdt, Doc.keepReplaced), and its text shows at the end of the winner’s (an implicit merge claim); insertBlocks, splitBlock and 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 (MergeClaim is { m }, Claim is { m, stamp }); a record’s claims are its implicit ones (TextBlockRec.implicit), then the claim items of its stream. The text binding’s claimInto(own, from, into), splitAt(doc, …) and deleteClaims(doc, claims) write them.
  • Comment quotas. CommentOptions.maxBytes and maxRequestsPerSecond (EDYTOR_MAX_COMMENT_BYTES, EDYTOR_MAX_COMMENT_REQUESTS_PER_SECOND; defaults DEFAULT_MAX_COMMENT_BYTES, DEFAULT_MAX_COMMENT_REQUESTS_PER_SECOND), COMMENT_ROW_BYTES, commentBytes, decideComment’s bytes and maxBytes, the refusal reason comments and the 429 of routeDocumentComments.
  • Per-block locks. lockedBlocks(options) and LockOptions (key, subtree, bypass); the locks option of attachDocument, DocumentRoom.locks() and the EDYTOR_LOCKS variable.
  • Cross-document moves. moveBlocksBetweenRooms(namespace, move) and forwardLateEdits(namespace, from); the rooms option, DocumentRoom.rooms() and the EDYTOR_ROOMS binding; 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) and applyLateEdits(batch), also over RPC.
    • The types MoveNamespace, MoveRoom, MoveDestination, ExportedBlocks, ImportRequest, ImportReceipt, CommitResult, LateEdit, LateEditBatch and MovedState.
    • Log entries move and late; the alarm’s forward task; tables moves and late.
  • Purge. The room purges content deleted before its horizon (purgeAfterDays, EDYTOR_PURGE_AFTER_DAYS; default the retention, else 30 days) as its own transaction (origin PURGE_ORIGIN). A document’s histories drop the steps below the horizon.
    • bindCrdt(Y).doc.purge(doc, facade, horizon) (PurgeReport; horizon null purges what closed sessions released alone) and bindCrdt(Y).doc.horizonOf(doc); the room’s purge() (also over RPC), RoomMetrics.purge and the purge log entry (horizon: null for a run with no epoch due, released the 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; attachDocument installs alarm unless none applies; the now option and DocumentRoom.now() set the room’s clock.

Migration

  • The v13 import (bindCrdt(Y).migration and its types, isLegacyDoc, UnsupportedDocError’s reason legacy) is removed: a v13 document’s JSON, exported with 0.0.11, creates the document.

Was this page helpful?