How the Rust port of Lexical is built and what comes next. It follows the
Swift port (swift/DESIGN.md) and wevm/zero's Rust client (rust/ in
wevm/zero). Changing a decision here means updating this file in the same
pull request.
- A pure-Rust port of Lexical's model and headless packages: Tier 1 only. The same inputs give the same editor state and the same JSON bytes, in both the legacy and compact forms, the same HTML and the same Markdown.
- Swift's feature set first. tmm's target is parity with what the
Swift port supports; Swift and Rust move toward the rest of JS later, as
apps need it. So
@lexical/yjs,@lexical/y,@lexical/table,@lexical/code-shiki,@lexical/mdastand@lexical/offsetare not planned: Swift has none of them either. - The editing UI (Swift's Tier 2: views, input, the reconciler's rendering half, the WebKit scenarios) is out of scope.
- JS is the reference. A difference from upstream is a Rust bug, except the documented exceptions in PARITY.md.
- Conforms to the upstream release in
lexical_ui::UPSTREAM_VERSION, which must match the vectors'meta.json(checked by the conformance runner).
| Path | Crate | Published | What |
|---|---|---|---|
rust/lexical-ui |
lexical-ui |
crates.io | The port: core, and one feature per upstream package |
rust/conformance |
lexical-conformance |
never | The conformance runner: replays every vector file |
rust/apps/lexical-playground-core |
lexical-playground-core |
never | The playgrounds' binding to lexical-ui |
rust/apps/lexical-playground-rune |
lexical-playground-rune |
never | The playground on Rune (a workspace of its own) |
rust/apps/lexical-playground-gpui |
lexical-playground-gpui |
never | The playground on GPUI (a workspace of its own) |
rust/ is developed in wevm/lexical, with its own CI
(.github/workflows/rust.yml), and mirrored to wevm/lexical-rust on
release the way swift/ is mirrored to wevm/lexical-swift (see Releases).
The crate is lexical-ui (lexical_ui in code): tmm chose it on
2026-11-16 over the provisional lexical-editor, lexikal and lexica. It
was free on crates.io then, and stays changeable until tmm's first publish
(see Releases). The name lives in few places: name in
lexical-ui/Cargo.toml, the package of the lexical entry in the
workspace's [workspace.dependencies], the
directory, the doc example in lib.rs, the cargo tree and cargo publish checks in rust.yml, rust-release.yml,
scripts/version-packages.sh and the changesets' frontmatter. Every other
crate in the workspace depends on it as lexical, so a rename doesn't touch
their code.
One crate, with a feature per upstream package, as zero-client does. The
core (lexical) is always built. Planned features, each enabling those it
depends on as the upstream package depends on them:
| Feature | Upstream package | Needs |
|---|---|---|
| (core) | lexical, @lexical/headless |
|
extension |
@lexical/extension, with lexical's extension-core |
utils (for TabIndentationExtension's $handleIndentAndOutdent); with another package's feature, that package's extensions (RichTextExtension, HistoryExtension, ClickableLinkExtension, BlockWithAlignableContents...) |
selection |
@lexical/selection |
|
utils |
@lexical/utils |
selection |
rich-text |
@lexical/rich-text, with @lexical/react's table of contents |
selection, utils, clipboard |
plain-text |
@lexical/plain-text |
clipboard (upstream also lists dragon, extension, selection and utils; the model handlers use none of them) |
clipboard |
@lexical/clipboard |
selection, utils (upstream also lists extension and html; the HTML paths and the extensions come with those features) |
list |
@lexical/list |
utils (upstream also lists extension and html; ListExtension and CheckListExtension come with extension, and the DOM parts with html) |
link |
@lexical/link |
utils (upstream also lists extension and html; LinkExtension, and with autolink AutoLinkExtension, come with extension, and the DOM parts with html) |
autolink |
@lexical/link's registerAutoLink |
link, regex |
code |
@lexical/code-core |
(upstream lists extension, html and utils; CodeExtension and CodeIndentExtension come with extension, the DOM parts with html; utils is for the arrow-key handlers) |
code-highlight |
@lexical/code-prism's highlighting loop (CodeHighlighterPrism.ts), over a Tokenizer the app supplies |
code (upstream also lists extension, for CodePrismExtension, which comes with it, and prismjs, whose grammars aren't ported) |
mark |
@lexical/mark |
utils (upstream also lists extension and html; with extension, MarkExtension, MarkStateExtension and the mark flavors, and with html too their HTML export and import of the ids) |
overflow |
@lexical/overflow, with @lexical/react's character limit |
text, utils (for the character limit's $rootTextContent, $dfsWithSlots and $unwrapNode) |
text |
@lexical/text |
|
hashtag |
@lexical/hashtag |
text (upstream also lists extension and utils; HashtagExtension comes with extension, and mergeRegister is the core's) |
history |
@lexical/history |
(upstream lists utils, but uses nothing from it) |
html |
@lexical/html, with dom (a DOM in place of the browser's, which the nodes' DOM hooks use) |
selection |
markdown |
@lexical/markdown |
rich-text, list, link, code |
file |
@lexical/file |
|
a11y |
@lexical/a11y's announcements; with rich-text and link, their HeadingAnnounceExtension and AutoLinkAnnounceExtension |
extension, utils |
decorator-block |
@lexical/react's DecoratorBlockNode |
(upstream @lexical/react lists most packages, for its other modules; the node needs none) |
menu |
@lexical/react's typeahead and node menus without their views (LexicalTypeaheadMenuPluginUtils.ts, shared/LexicalMenu.tsx) |
|
auto-embed |
@lexical/react's auto-embed (LexicalAutoEmbedPluginUtils.ts, the logic of LexicalAutoEmbedPlugin.tsx) |
link, menu, utils |
devtools |
@lexical/devtools-core's generateContent |
(upstream lists html, link, mark and table; its HTML form is built with html, its link branch with link and its mark branch with mark, and its table branch isn't ported) |
Each module is lexical_ui::<package> (lexical_ui::rich_text).
Names may change as packages land; this table is updated with them.
- No third-party dependencies in the default build:
cargo tree -e normal,buildoflexical-uishows the crate alone, with the default features and with every feature butautolink, and CI fails otherwise. A dependency comes only behind an opt-in feature:autolinkneedsregex(withregex-automataandregex-syntax, which CI checks are all it brings), forregisterAutoLink's matchers, whose\p{L}and\p{N}need Unicode tables.@lexical/link's nodes andregisterLinkstay inlink, without it. The crate has its own JSON (json), because the output must be byte-identical toJSON.stringify(JS property order,1e+21,-0as0), whichserde_jsondoesn't promise. - Port, don't invent. Modules mirror the upstream files
(
LexicalGeneratedJSON.tsisgenerated_json.rs,nodes/LexicalTextNode.tsisnodes/text.rs), and functions keep their JS names in snake case without the$:$getRoot()isget_root(). Doc comments name the JS function in backticks so a search for the JS name finds the port. $functions read a thread-local active editor state, as JS reads module-scope variables (updates.rs), and only work inside a read or an update. The editor is neitherSendnorSync.- Nodes. JS's class hierarchy is the
LexicalNodetrait plus the data each base class adds (ElementData,TextData). A node is a value behind anRcin its editor state's node map;getWritableclones it unless nothing else shares it (utils::get_writable), so an earlier editor state never sees a change. TheRc's uniqueness stands in for JS's_cloneNotNeeded.getWritablealso marks the node dirty, as in JS, and helpers that take "writable" nodes expect their callers to have called it in JS's order, because update listeners see nodes in the order they were marked. Code outside a node reads it throughNodeRef, a key that resolves the latest version on every call, as JS node methods callgetLatest(). Base class behavior a subclass overrides with asupercall is a free function in the base class's module. - Schemas.
LexicalSchema.tsis theschemamodule, type-erased over the crate'sjson::Valueas Swift's is overJSONValue(Value::Undefinedis JS'sundefined), so a schema is oneSerializationSchemawhatever it parses to and a node field converts throughSchemaValue. A node declares its$configjsonschema inLexicalNode::json_schema_chain, most derived class first, andexport_jsonandupdate_from_jsondefault to the walk of the composed schema ($exportNodeJSONOnce,$applyJSONSetters). A Rust node has no methods to find by name, so every property names its accessors:with_fieldtakes the field's two accessor functions,with_accessorstwo closures, and a class that overrides an accessor a field stands in for gives its base's schema withNodeSchema::with_setter(where JS resolvesSchemaFieldBase.methodalong the prototype chain). A clone carries every field throughClone, so$config's synthesizedafterCloneFromhas nothing to do. JS checks in generated code for the core nodes (LexicalGeneratedJSON.ts), and the port keeps that code by hand in thegenerated_export_jsonandgenerated_update_from_jsonhooks; the conformance runner checks it against the walk for every node of every serialization and property case, both forms, asLexicalGeneratedJSON.test.tsdoes, and a unit test does so for hostile values. - Numbers a document can set are
f64. JS stores whatever finite number a document carries informat,detail,indentandtextFormat, and writes it back. Rust keeps the samef64, so unlike Swift (which keeps anInt, itsmodel/integer-propertiesdeviation) such documents need no exception. Bitwise reads go throughToInt32as in JS. - Offsets are UTF-16 code units, as in JS, but a Rust
Stringis UTF-8. The model stores text asStringand converts offsets where they are used (splitText,spliceText, selection points), with ASCII as the fast path. If the M1 benchmarks show the conversion matters, text nodes cache their UTF-16 length. A lone surrogate half is the one Tier 1 exception, inherited from Swift (PARITY.md). - Errors. A JS
invarianta document or a caller can break returns aLexicalErrorwith the same message; one only a bug in a node implementation can break panics, asRefCelldoes. A failed update returns its error fromEditor::update(JS reports it toonError) after discarding the update and notifying listeners, as JS does. - The update cycle (
updates.rs) follows$beginUpdateand$commitPendingUpdatesline by line: nested and queued updates, normalization, transforms (leaves first, the root last), GC, the selection check, discarding a failed update, and the text content and update listeners. The dirty sets are insertion-ordered like JS'sMapandSet(ordered.rs), including iteration that sees entries added meanwhile. Without a root element nothing reconciles, so mutation listeners and selection-change notifications never fire, as in JS's headless editor (create_headless_editorandHeadlessExtensionrefuse a root element, and their editor never reconciles); with one (set_root_element), the reconciler's model half (reconciler.rs) reports created, updated and destroyed nodes to mutation listeners, collects what decorators decorate to (an app'sRc<dyn Any>, compared by identity, forgetDecorators()and the decorator listeners), and sets each reconciled element'stextFormatandtextStylefrom its first text, as JS's does. JS commits a non-discrete update in a microtask; with no event loop, Rust commits it at the nextreador discrete update, which JS also does when one comes first. Update closures that may be queued are'static.
createDOM, exportDOM, importDOM and HTML export and import need a
DOM, which a browser or (in upstream's unit tests) jsdom gives JS. The
html feature brings one, lexical_ui::dom, ported from the Swift
port's (swift/Sources/Lexical/DOM, swift/DESIGN.md, "The DOM is a small
model of jsdom's"), since the vectors record what jsdom does:
- One node type.
DomNodeis a shared handle (Rc) compared by identity, as JS compares node objects, standing forNodeand every interface Lexical reads through it (Element,Text,Comment,DocumentFragment,Document); an element's methods answer as empty values on other nodes. A node holds its children; its parent and document are weak links.get_document()is onedocumentper thread, as JS has one globaldocument. - The inline style declaration normalizes as jsdom's does for what
Lexical writes (colors to
rgb(), trimmed numbers,0px, lower-case keywords,calc()of a product, CSS-wide keywords), and is read from thestyleattribute lazily and written back ascssText, as jsdom's is. The accepted properties and how each normalizes are a table generated from thecss/propertiesvectors (rust/scripts/generate-dom-tables.mjs, which also writes the entity table fromhtml/entities); the runner checks both the tables and the declaration's behavior against them. Unlike jsdom it keeps most values it can't parse, collapsing their whitespace, as Swift's does; it rejects a shadow of nothing but identifiers, as jsdom does. - The nodes' DOM hooks are
LexicalNodemethods behind the feature:create_dom(this, config, editor),export_dom(this, editor)andimport_dom()(the class's staticimportDOM, read from a default value when the class registers). Like the other hooks they get the node's value and its handle, so an export can run on a value that isn't in the editor state (the text a selection cuts short). The base classes' behavior is the hooks' defaults (TextNoderenders its text,ElementNodeadds the indent and direction), as forget_text_content. A node package's DOM parts build when both its feature andhtmlare on, so the package doesn't pull in the DOM. The theme is the JSON ofEditorThemeClasses(CreateEditorArgs.theme), and aDOMConversionMapis a list of name and importer pairs in the order JS's object keys would be. - The render config has the hooks export reaches. An editor's
EditorDomRenderConfig(createEditor'sdom, JSEditorDOMRenderConfig) holds$createDOM,$exportDOM,$extractWithChild,$shouldIncludeand$shouldExcludeas shared closures, andDOMRenderExtensionlayers its overrides over them. The reconciler's hooks ($updateDOM,$decorateDOM,$getDOMSlot,$getSlotTargetElement) are left out, as there is no DOM to reconcile. Nodes have no class hierarchy to test withinstanceof, so an override of a class matches by node type and byLexicalNode::super_types, the types of the classes a node's class extends (textfor a node withTextNodefields,linkforAutoLinkNode); JS's dispatch throughgetRegisteredSubtypeMapcomposes the same way and is only faster. DOMParseris a WHATWG tokenizer and tree builder, checked against jsdom's by thehtml/parseandhtml/entitiesvectors. As in Swift it leaves out templates, framesets, the<select>and<ruby>insertion modes and the case adjustments of SVG and MathML names; their content parses as body content.
cargo run -p lexical-conformance replays every file in
packages/lexical-conformance/vectors and prints a table: cases per file,
how many match JS exactly, how many match only under a documented
exception, how many wait on a package not ported yet, and how many fail.
- Every vector file is listed. A file no suite replays yet is reported as not implemented, and a case that needs an unported package is counted apart, never as passing.
- Each case is checked alone; a failing or panicking case is counted and
the rest still run. CI fails on any failing case.
cargo test -p lexical-conformanceasserts the same, and checks that doctored vectors fail. - Vectors are never edited or skipped to get to green, and never generated
by Rust:
packages/lexical-conformanceruns the real upstream code. New vectors the port needs (for@lexical/mark, say) are added there, in JS, as the Swift port adds its own. - The mirror has
rust/without the vectors, so there the conformance tests skip;LEXICAL_CONFORMANCE_VECTORSpoints the runner elsewhere.
The counterpart of Swift's (swift/parity/, @Test(.upstream(...))),
checked by the same script, packages/lexical-conformance's
scripts/ledger.mjs:
- The list of upstream unit tests is Swift's
swift/parity/upstream-tests.json, whichpnpm run ledgerregenerates for the packages either port tracks; both ledgers read it. rust/parity/packages.json: each tracked package,"enforced"or"pending", as Swift's statuses. A package is enforced once each of its tests is ported or skipped; then CI fails on any new upstream test that is neither.rust/parity/skips.json: id →reasonandnote, with Swift's reasons (dom-only,react-only,out-of-scope-packagewith thepackagesit needs,covered-by-vector,deviation). The note says why in Rust's terms: a Swift skip is not a Rust skip unless its reason holds for Rust. So a test Swift skips as DOM-only that thehtmlfeature's DOM can run (setDOMStyleFromCSS,$getDocumentwithout a root element) is not skipped, nor are Swift's deviations that Rust doesn't share (the generated JSON code Rust keeps, a fractional indent, which anf64holds), nor@lexical/code, which re-exports thecode-coreRust ports;covered-by-vectornames what the Rust runner checks of the vector.- A ported test has a
// upstream: <id>line directly above its#[test](other attributes may come between), one id per line, several for a test that ports several; an id a line comment can't hold as written (leading or trailing whitespace) is a JSON string literal. The script reads the comments in every.rsfile underrust/; nothing in the crate depends on the ledger. An id is marked once. pnpm run check-ledgerfails, for both ports, on an unknown id in a marker or a skip, a key listed twice, a skip of a test that is also ported, a skip without a note or with an unknown reason, anout-of-scope-packageskip whose packages are all enforced, and an enforced package with a test neither ported nor skipped; it prints each port's counts per package. CI runs it inswift.yml(with--fresh, which reruns the upstream tests to check the list is current) and inrust.yml.
Each milestone ends with green CI and a report to the Space. Three Amp
threads share the work and rebase onto main as pull requests land: the
Rust port thread
owns M1, M3, M6 and the merges, the
HTML thread
owns M4, and the
Markdown thread
owns M5. A change one of them needs in the core goes through the Rust port
thread.
| Milestone | Scope | Vectors that pass when done | Status |
|---|---|---|---|
| M0 | The rust/ workspace, JSON as JS writes it, the core nodes (root, paragraph, text, tab, line break), parseEditorState and toJSON in both forms, the conformance runner, CI |
meta, serialization/core, the core-only cases of property/documents (JSON and text) |
done |
| M1 | The core model: editor.update and the commit (dirty nodes, normalization, transforms, listeners, commands, tags), node creation and methods (splitText, mergeWithSibling, spliceText, insertAfter, remove, replace...) with UTF-16 offsets, RangeSelection and NodeSelection editing, carets, NodeState, slots, the schema facility, DecoratorNode, the extension API (buildEditorFromExtensions), the parity ledger |
scripts/*, fuzz/core, file/* |
done (every vector it names passes): the update cycle, setEditorState, commands, transforms, listeners, the node methods, carets, selection reading and RangeSelection/NodeSelection editing are done (scripts/* and fuzz/core pass), and the platform's Selection.modify is an editor hook (SelectionMovement); NodeState is done (createState, $getState, $setState, $getStateChange, the "$" key and flat states in node JSON, unknown keys kept, clones, $copyNode, splits and merges, scripts/node-state), and its schema builders came with the schema facility; DecoratorNode is done (its hooks, block and inline decorators in insertNodes, deletion, modify, text content and formatting, $setBlocksType across one, scripts/decorator), and so are editor._decorators and the decorator listener, which the reconciler fills once the editor has a root element (scripts/reconciler); the extension API is done (buildEditorFromExtensions, the extension-core types, dependency and peer resolution, config merging, the four phases, disposal, the dependency lookups, a port of @preact/signals-core with namedSignals and watchedSignal, and InitialStateExtension, ClearEditorExtension, EditorStateExtension and DecoratorTextExtension; scripts/extensions passes), and so are the packages' model-level extensions (RichTextExtension, PlainTextExtension, HistoryExtension, SharedHistoryExtension, ListExtension, CheckListExtension, LinkExtension, AutoLinkExtension, HashtagExtension, OverflowExtension, CodeExtension, CodeIndentExtension, NormalizeInlineElementsExtension; scripts/package-extensions passes), less their key, DOM and HTML import handlers (rust/PARITY.md); slots are done (LexicalSlot.ts and its call sites in the core: node methods, both JSON forms, GC, selection clamping, carets across slots, insertion and deletion at a slot boundary; and in the packages; scripts/slots and the named slots case of serialization/core pass), except the 'deletion' mode of $setPointAtSlotBoundary, which needs Selection.modify to cross a frame (rust/PARITY.md); the schema facility is done (schema, the core and package nodes' $config schemas, NodeState's schema builders; serialization/schema and serialization/schema-node pass), less what rust/PARITY.md lists; and the parity ledger is done (rust/parity, the // upstream: markers, checked with Swift's by check-ledger; see Parity ledger) |
| P | Desktop playgrounds (apps/): lexical-playground-rune on Rune, then lexical-playground-gpui on GPUI, sharing lexical-playground-core; they grow with each milestone below |
the vectors, replayed in the app; a session exported from the app replays in JS (replay.test.ts); in CI, a GPUI session typed in a real window replays in JS |
both apps run on macOS with typing, Return, deletion, formatting, input methods and the Parity panel; they grow with each milestone |
| M2 | rich-text (headings, quotes, and the command handlers a text surface dispatches: typing, Enter, Backspace, formatting) and history (undo), which the playgrounds need first; then the node packages list, link, code, overflow, hashtag, with selection and utils |
serialization/*, property/documents (JSON and text), entities/hashtag-*, scripts/history |
done (every vector it names passes): history is done (scripts/history passes); rich-text's nodes and registerRichText's model command handlers are done (scripts/rich-text and scripts/rich-text-commands pass, with the heading and quote cases of property/documents); plain-text's model command handlers are done (scripts/plain-text passes); list's nodes, registerList and the model part of registerCheckList are done (scripts/list and serialization/list pass, with the list cases of property/documents); link's nodes, $toggleLink and registerLink's model handlers are done (scripts/link and serialization/link pass, with the link cases of property/documents that need no other package), registerAutoLink and its matchers are done behind autolink (scripts/autolink and entities/autolink-match pass); selection's $setBlocksType is done (scripts/set-blocks-type passes); code's nodes, FlatStructureUtils.ts, CodeExtension's transform and registerCodeIndentation's model handlers are done (scripts/code and serialization/code pass, with the code cases of property/documents that need no other package); overflow's OverflowNode is done (scripts/overflow and serialization/overflow pass, with the overflow cases of property/documents that need no other package); hashtag's HashtagNode, its matcher (generated character tables, no regex) and registerLexicalHashtag, with text's registerLexicalTextEntity, are done (entities/hashtag-match, entities/hashtag-documents and entities/hashtag-typing pass, with the last waiting cases of property/documents), so M2's node packages are done |
| M3 | The commands property/sequences dispatches |
property/sequences |
done (all 81 cases match JS): the suite builds sequenceEditor's editor with build_editor_from_extensions and the ported package extensions, in JS's order; the commands M2 ported needed two fixes, NormalizeInlineElementsExtension's transform (register_normalize_inline_elements, removing empty links) and $extendSelectionForDeletion and modify stopping where the window gives no DOM selection (SelectionMovement::has_dom_selection) |
| M4 | html: a DOM abstraction over an HTML parser, CSS declarations, export and import; with it @lexical/clipboard's HTML path ($getHtmlContent, the text/html importer) |
html/*, css/*, property/documents (HTML) |
done (HTML thread): the DOM (dom: nodes, DOMParser, the serializer, the inline style declaration and its tables), getStyleObjectFromCSS, the core nodes' and the node packages' DOM hooks, and @lexical/html's export and import, are done (every html/* and css/* file and property/documents' HTML pass), and so are the DOMImportExtension pipeline with CoreImportRules and $inlineStylesFromStyleSheets (html/import-extension passes) the DOMRenderExtension pipeline (html/export-render passes) the packages' import rules (html/import-packages passes), clipboard's HTML path with its extensions (html/clipboard passes) and BlockIdHTMLExtension (html/block-id passes) (clipboard's JSON and plain-text paths are done, see M6) |
| M5 | markdown, and Markdown shortcuts in both playgrounds |
markdown/import-export, property/documents (Markdown), scripts/markdown-shortcuts |
done (Markdown thread): import, export, the transformers and registerMarkdownShortcuts (markdown/import-export, the Markdown of property/documents and scripts/markdown-shortcuts pass), registered in lexical-playground-core, whose Return dispatches KEY_ENTER_COMMAND, so both desktop playgrounds have the shortcuts |
| M6 | The rest of Swift's feature set: the extension API's bundled extensions (ClearEditor, InitialState, EditorState, TabIndentation, NodeStructure, SelectBlock and the others Swift has), clipboard (JSON copy and paste first, HTML once M4 lands), the rest of selection and utils (style helpers, $wrapNodes, $splitNode, $dfs...), mark, file, the devtools tree view, text's root helpers, a11y's announcements, code highlighting (Swift uses tree-sitter where JS uses Prism), the character limit, the menu, auto-embed, decorator block and table of contents logic, the remaining built-in commands, slots, node schemas and editable mode |
file/*, devtools/tree, scripts/text, scripts/extensions, scripts/mark, scripts/mark-extension, serialization/mark, html/mark-state, scripts/clipboard, scripts/package-extensions, scripts/selection-utils, scripts/nested-editor, scripts/character-limit, scripts/table-of-contents, scripts/code-highlight, and new JS vectors for the rest |
in progress (this thread's owner: the Rust port thread, which also owns M1's extension API and the merges): file, the devtools tree view and text's root helpers are done (file/*, devtools/tree and scripts/text pass); mark's model is done (MarkNode and its generated JSON, $wrapSelectionInMarkNode, $unwrapMarkNode, $getMarkIDs, and the MarkStateExtension.ts functions that need no extension; scripts/mark and serialization/mark pass), and so are MarkExtension, MarkStateExtension, MarkBaseExtension and the mark flavors of defineMarkExtension (markableNodes, disabled, the markIDNodeKeys output, registerMarkIDsListener, the inserted-text rule with composition, and the HTML export and import of the ids; scripts/mark-extension and html/mark-state pass), less the renderer's $decorateMarkIDs and isMarkIDShown (rust/PARITY.md); the model of selection and utils is done (the style helpers, $wrapNodes, $splitNode, $dfs and the rest Swift has but what needs the DOM, computed styles or File, with $dfsWithSlots and its forms since slots landed; scripts/selection-utils and scripts/slots pass); clipboard's JSON and plain-text paths are done (scripts/clipboard passes, with registerRichText's and registerPlainText's copy, cut and paste handlers), and its HTML path comes with M4; of the bundled extensions, ClearEditor, InitialState, EditorState, NormalizeInlineElements, TabIndentation, SelectBlock, PreventSelectAll's config and BlockId (ids, their repair, positional and derived ids, handles; scripts/block-id passes) are done (scripts/extensions, scripts/package-extensions); the character limit is done (useCharacterLimit.ts under overflow, with grapheme clusters from generated Unicode tables; scripts/character-limit passes), and so is the table of contents (LexicalTableOfContentsPlugin.tsx under rich-text, on the core's root element and mutation listeners; scripts/table-of-contents passes); NodeStructure is done (LexicalStructure.ts with its core and package call sites and NodeStructureExtension; scripts/node-structure passes, and BlockId's peer on it resolves); NestedEditor is done (the core's parent editor, command propagation to it and read(mode), NestedEditorExtension, and with them $isEditorIsNestedEditor, SharedHistoryExtension's default parent and SelectBlockExtension's cascadeSelection; scripts/nested-editor passes); NodeSelection and HorizontalRule are done (scripts/horizontal-rule passes), less the rule's selected class, which needs its DOM; the input extensions are done on the commands an app's view sends (KeyboardShortcuts with formatKeyboardShortcut, ClickAfterLastBlock, NormalizeTripleClickSelection, IME, AutoFocus, @lexical/link's ClickableLink with an app's LinkWindow, and the builder's namespace and disposal; scripts/input-extensions passes), and so is BlockWithAlignableContents as an extension, as Swift has it; a11y's announcements are done (the live region model with an app's LiveRegionHost, AriaLiveRegionExtension, HistoryAnnounceExtension, EditorModeAnnounceExtension, HeadingAnnounceExtension and AutoLinkAnnounceExtension, on the core's new root element, mutation listeners, the reconciler's model half, editable listeners and $onUpdate; scripts/a11y passes), and so are DecoratorBlockNode (scripts/decorator-block, serialization/decorator-block), the menu's text matching and state (scripts/menu) and auto-embed (scripts/auto-embed), less the a11y focus helpers (rust/PARITY.md); code highlighting's loop is done (code-highlight: registerCodeHighlighting, registerHighlightingOnly and CodePrismExtension over a Tokenizer trait, with Shiki's lazy languages; scripts/code-highlight passes), without a tokenizer: Prism's grammars and Swift's tree-sitter would be third-party dependencies, so apps supply one; the remaining built-in commands are done (the DOM event commands and their payloads, LexicalKeyboardShortcuts.ts, and LexicalEvents.ts' keydown, beforeinput and composition handlers with composition through the core; scripts/events and scripts/events-apple pass), and so are the packages' handlers of them that Swift has at the model level (rich and plain text's keys, clicks, pastes of files and drag and drop with RichTextConfig, the list's Backspace, code indentation's keys, TabIndentationExtension's Tab, the link's paste of a URL and the menus' keys; scripts/key-handlers passes), less the check list's focus keys (rust/PARITY.md) |
| M7 | Releases: the mirror, changesets, a name tmm settles | the release process is in (see Releases); waiting on tmm's one-time steps and first publish |
The scenarios/* vectors, recorded from a real browser, need a text
layout behind Selection.modify; the playgrounds' binding replays them once
rich-text is in.
tmm asked for desktop playgrounds, as wevm/zero has zbugs on GPUI and on
Rune, rather than a web one: the Rust port is meant for native apps. Each
app is its own Cargo workspace under apps/ (Rune needs Rust 1.90 or
later; the crate stays on 1.88), and both depend on
apps/lexical-playground-core, which is in this workspace:
- Lexical owns the document and the selection; the app draws them, lays
them out, hit-tests and moves the caret, as a browser does for
contenteditableand TextKit does for the Swift port.- Rune: its
text_inputdraws a mirror of the document. Keys that edit run as Lexical updates before the field sees them (a shortcut as aKEY_DOWN_COMMANDthe core's handler maps to its command), and a change the field makes itself (an input method's commit, a cut) is replayed into Lexical as the text it replaced; then the mirror is rebuilt, as Lexical's reconciler rebuilds the DOM. - GPUI: an element of its own draws the document, and is the window's
text input client (
EntityInputHandler) throughSurfacein the core crate, which maps UTF-16 ranges to Lexical points and keeps an input method's composition outside Lexical until it commits, as a browser does. Keys are GPUI actions bound as macOS binds them. - Deleting by character, word or line extends the selection in the core
crate (graphemes, words, the paragraph) before the step runs, so the
step is what JS runs once the browser's
Selection.modifyhas moved.SelectionMovementlets an app answer that from its own layout instead.
- Rune: its
- The editor has a root element (the core crate's session root), as the
JS playground's has its
contenteditable, so the reconciler's model half runs and mutation listeners hear of each node: code blocks' line numbers come fromregister_code_gutter, which the GPUI app draws in a gutter as the web playground's theme drawsdata-gutter. A selection the app's view makes reaches the editor throughon_selection_change(theselectionChangeaction), as a browser'sselectionchangerunsonSelectionChange, before the edit that follows it. - Every edit is a step of the conformance script language, run by the same
interpreter that replays
scripts/*. Export session writes the steps and their results as a vector file that JS replays and compares (packages/lexical-conformance/src/replay.test.ts); Replay vectors runs the conformance report in the app. - The GPUI app has an end-to-end mode for CI (
--features e2e), as zbugs-gpui does: it types, composes and deletes in its own window through the input handler and key bindings, then exports the session, which JS replays in the same job. - To try one:
cargo run --releasein its directory. On macOS abundle.shrunner makes a.appthat stays in the Dock, as zbugs' do.
As the Swift port releases (swift/AGENTS.md, Releases), with crates.io on
top:
-
Changesets. A user-facing change to
lexical-uiadds a changeset inrust/.changeset/(its README has the format; bodies are in the past tense). The crate's version is the one inlexical-ui/Cargo.toml;CHANGELOG.mdhas a section per release, namingUPSTREAM_VERSION. Neither is edited by hand. The other crates stay at the workspace's0.0.0and are never published. -
The version pull request. While changesets are pending,
.github/workflows/rust-release.ymlkeeps achore(rust): version packagespull request open, made byscripts/version-packages.sh(which also bumps the crate's entry inCargo.lockand the playgrounds' lockfiles), and starts the Rust workflow on it. It merges, squashed, once that run is green; no one approves it. -
The release. On the merge, the workflow pushes a subtree split of
rust/to wevm/lexical-rust (github-sts, with the policy inrust/.github/sts/mirror.sts.yamland therust-releaseenvironment), tags the version there, creates a GitHub release from the version'sCHANGELOG.mdsection, then publishes the crate withcargo publishthrough crates.io's trusted publishing:rust-lang/crates-io-auth-actiontrades the job's GitHub OIDC token for a crates.io token that lasts 30 minutes and is revoked when the job ends, so no crates.io secret is stored. The crate's trusted publisher on crates.io names wevm/lexical,rust-release.ymland therust-releaseenvironment, so renaming the workflow file or the environment needs the same change there. Trusted publishing can't create a crate, so until the first publish the step is skipped with a notice. Each step is skipped when it has happened, so a failed run can be rerun.rust.ymlpackages the crate on every run (cargo publish --dry-run --all-features). -
The first release (0.1.0, from
rust/.changeset/first-release.md) needs tmm first, once:- Create the
rust-releaseenvironment on wevm/lexical, with deployments limited tomainand no reviewers, asswift-release. - Create wevm/lexical-rust, public and empty (no README or license), and add it to the GitHub STS app's installation, as wevm/lexical-swift is.
- Push the first split by hand, from a
mainthat hasrust/.github/sts/mirror.sts.yaml(the STS policy is read from the mirror'smain, so the workflow can't push the first one):git clone https://github.com/wevm/lexical.git && cd lexical && git subtree split --prefix=rust -b rust-mirror && git push git@github.com:wevm/lexical-rust.git rust-mirror:main. - Then the version pull request merges, and the workflow tags 0.1.0 on the mirror and creates its release; the crate step is skipped with a notice, as the crate doesn't exist yet. Until step 2 is done, the workflow fails with an error naming the missing mirror.
- Publish 0.1.0 by hand, so the crate is registered to tmm. crates.io
only creates a crate from an API token, so
cargo logintakes one with thepublish-newscope (and crates.io needs a verified email); revoke it afterwards, as CI needs none:git clone --branch 0.1.0 https://github.com/wevm/lexical-rust.git && cd lexical-rust && cargo login && cargo publish -p lexical-ui --locked. - On crates.io, open the crate's Settings → Trusted Publishing, Add,
GitHub, with repository owner
wevm, repository namelexical, workflow filenamerust-release.ymland environmentrust-release, and save. From then on, CI publishes each release. Once one release has published from CI, the crate settings' "Trusted Publishing only" setting can turn off publishing with API tokens.
A rename comes before step 5 (see The name).
- Create the