Breaking Changes

All slot machinery is opt-in and gated (an editor latches _slotsUsed on the first $setSlot), so editors that never use slots take identical code paths to before. The items below are the complete set of changes observable by existing consumers. Unless you hit one of these two specific scenarios there are no expected breaking changes:

• syncLexicalUpdateToYjsV2__EXPERIMENTAL takes a new dirtyLeaves parameter, inserted between dirtyElements and normalizedNodes. A DecoratorNode host's slot values surface as dirty leaves, so the recursive dirty walk needs the union of both sets.
• A NodeSelection containing an ElementNode now includes its children in copy / export on both clipboard channels. The previous behavior serialized a childless element shell, which made cut of an element NodeSelection silently lossy — this is really a bug fix, but the output of $getHtmlContent / $generateJSONFromSelectedNodes changes for any consumer copying element NodeSelections. Partial RangeSelections keep per-child slicing, and excludeFromCopy children remain excluded.

Description

Lexical's nested editors put each region in its own editorState, so moving nodes between regions and keeping history and collab in sync all need serialization and extra editor.update passes (#5930). Named slots keep those regions in the host's editorState as a second child channel rendered into the host's own DOM, so editing a slot is just editing the one tree.

Named slots let a single host node (ElementNode or DecoratorNode) own several isolated editable regions addressed by name (a Card's title, a PullQuote's quote and attribution) instead of sharing one child linked list. issue #5930 asks for exactly this: regions that each take their own caret and formatting, never merge across the boundary, and don't let Cmd+A spill into the rest of the document. The existing node kinds can't express it — plain ElementNode children are one undivided linked list, so backspace at a region start merges it into the previous region, and a DecoratorNode is atomic, so Lexical can't own selection / collab / serialization inside it.

The model: a host keeps a second child channel, __slots: Map<slotName, NodeKey>, separate from its __first/__last linked list. A slot value has __slotHost set and __parent === null, with exactly one of the two non-null, so getParent() stops at the slot boundary and you climb out only through $getSlotHost(). The slot link itself acts as a virtual invisible shadow root between the host and the value — isolation is structural rather than a convention: an accidental boundary crossing surfaces as a thrown invariant, not silent corruption. Slots render synchronously into keyless <div data-lexical-slot="<name>"> containers parked slots-first in the host DOM as hidden placeholders, in a canonical order derived from the host class (see below); nothing is visible until the host explicitly attaches a container somewhere.

This is @experimental. Three playground demos cover the host shapes, value shapes, and attachment means: Card (an ElementNode host with a single-line title slot — a bare ParagraphNode value — alongside ordinary linked-list body children, attached synchronously in-lexical via the render config), PullQuote (a DecoratorNode host with a multi-block quote slot wrapped in a shadow-root container and a single-line bare-paragraph attribution, attached from React decorate() chrome via useLexicalSlotRef), and Review (an ElementNode whose React presentation goes beyond static chrome: a contentEditable=false shell that portals in an interactive star-rating widget persisted to NodeState alongside two editable islands — the single-line named author slot attached with useLexicalSlotRef, and the linked-list body children attached through the same render-hidden-then-attach technique applied to its getDOMSlot element). All three round-trip through HTML copy/paste and behave like first-class blocks in the playground (arrow-key escape, empty-box deletion, chrome-click selection — see Playground host ergonomics below). The devtools tree view renders slot channels ([slot: name]) including in-slot selection annotations, and a new Named Slots concept page (docs/concepts/named-slots.md) documents the model, APIs (with examples for all three attachment means, linked to the API docs), and reserved names — including disambiguation from the unrelated DOMSlot rendering concept.

Design notes

• Map<string, NodeKey>, not a plain object. Slot names are arbitrary strings, and a plain object lets "__proto__" or "constructor" produce a false has(). Map has no prototype keys. ($setSlot additionally rejects the three reserved names outright, and the collab observers validate-and-skip them so a hostile peer can't crash clients.)
• Store only the __slotHost pointer; recover the name from the host's Map. One source of truth removes a whole sync-bug class, and slot counts are tiny so the reverse lookup is free ($getSlotNameWithinHost). Worth revisiting at hundreds of slots, not for cards.
• Slot values are any non-inline block (ElementNode or DecoratorNode) — the slot link is the shadow boundary, so the value itself doesn't have to be one. A bare ParagraphNode subclass works as a single-line field with no wrapper in the model, the JSON, or the DOM: its virtual scope holds exactly one block, so Enter is a no-op (hosts may map it to focus movement) and multi-block paste flattens to inline content the way an <input> sanitizes its value (line breaks stripped, block-only decorators dropped). Multi-block regions use a shadow-root container value (SlotContainerNode) and keep normal block editing inside. The rule lives at the single $setSlot chokepoint, so every create / restore path conforms, and inserting a node's own slot ancestor as a child is guarded in both directions (no isAttached/GC cycles).
• Slot order is canonical and derived, never stored. A host class declares its order in $config() (slots: ['quote', 'attribution']); undeclared names sort after in UTF16 code-unit order. $setSlot re-canonicalizes on every write, so documents normalize on load and concurrent collaborative additions converge to the same order on every client. Declared hosts also get their collab Y.Map eagerly at creation, so each name's first set merges per-entry instead of racing on attribute creation.
• The slot map is copy-on-write, mirroring NodeState: afterCloneFrom shares the map reference across versions and the mutators clone once per writable version (symbol owner mark stamped at construction), so a host cloned for any non-slot change pays no per-version Map copy.
• Slots are hidden placeholders until explicitly attached — the named-slot analog of getDOMSlot's control over where children render. The reconciler always renders every slot subtree synchronously, but into a display: none container parked slots-first in the host DOM; its ordering pass only manages placeholders still parked there, so an explicit mount is never yanked back. Three attachment means share one contract (move to the target if needed, reveal): a $getSlotTargetElement DOM render-config override (DOMRenderMatch via DOMRenderExtension/domOverride) for hosts implemented entirely in-lexical — consulted by the reconciler, synchronous within the commit (Card); the framework-independent mountSlotContainer/unmountSlotContainer (mountSlotContainer resolves the container against the committed editor state via editor.read('latest', ...), so the model it looks up matches the reconciled DOM it moves; unmountSlotContainer is DOM-only); and lexical-react's useLexicalSlotRef wrapping them (PullQuote). The revealed state is a normal block, deliberately not display: contents — Chromium cannot reliably edit inside a boxless contenteditable subtree (caret hit-testing resolves clicks into a neighboring box and native text insertion is dropped). A contentEditable=false ElementNode shell can host React chrome for both channels (the Review demo): slot containers opt into contentEditable=true inside any non-editable host DOM, such a shell marks itself setDOMUnmanaged in createDOM for decorator-parity with the mutation observer, and the observer's unknown-DOM eviction now skips keyless [data-lexical-slot] containers — they are reconciler scaffolding, and a flush observing one being parked or relocated must not remove it.
• Editable islands follow the editor's editable state. A slot rendered inside a non-editable host (a DecoratorNode, or a contentEditable=false element shell) becomes its own contentEditable island so it stays editable there, and it would not track editor.isEditable() on its own — so the reconciler sets the container's contentEditable explicitly from the editor's state and re-applies it on every reconcile. The reconciler owns this (no DOM-walking extension), so setEditable schedules a $fullReconcile — gated on _slotsUsed like the rest of the slot machinery — to flip every island on a read-only toggle, and a nested editor's islands stay correct because each editor reconciles its own tree. The shared helper $markSlotEditable(element, editor) applies the same rule to a non-slot editable island an app attaches itself (e.g. the Review demo's getDOMSlot children element inside its contentEditable=false shell), re-applied from updateDOM so a toggle reaches it. Slots always follow the editor; a per-slot editable override is intentionally out of scope for now — event handling isn't yet set up for editable islands inside a non-editable editor — and can return as a follow-up.
• isAttached is the GC linchpin. It now follows __slotHost when __parent is null, so a live slot is no longer seen as detached and reaped; fixing this one function carries slot-safety through GC. A second guard throws if a filled slot is dropped on export, as a data-loss tripwire.
• Traversal is intentionally asymmetric. Content reads include slots, slots-first (getTextContent, getAllTextNodes, $dfsWithSlots): "what is in this subtree" has to count slot content for search, copy, and accessibility. Navigation excludes them (getFirstDescendant and friends feed selectStart / selectEnd, so including slots would walk the caret into a slot and break isolation). getChildren() stays linked-list-only for backwards compatibility.
• isEmpty() is slot-aware (childrenSize === 0 && slotNames.length === 0). $removeNode cascade-prunes empty parents, so a slots-only host that lost its last linked-list child would otherwise be reaped and orphan its slots.
• Selection clamps at all three entry points: the DOM read ($internalResolveSelectionPoints), the API ($setSelection), and in-place point mutation. They share one helper with the direction test injected per caller. The clamp is anchor-frame, so a cross-boundary shift+arrow and a mouse drag land on the same result. The selection-driven exporters walk the anchor's slot frame ($getSlotFrame), so copy/cut of a selection inside a slot serializes correctly on both clipboard channels.
• SELECT_ALL scopes only inside slot frames by default. The rich-text/plain-text handlers keep the legacy whole-document behavior everywhere else (including table cells); progressive scoping is SelectBlockExtension's job, which is slot-aware ($isBlockFullySelected never compares across frames) and expands block → enclosing slot frame → document on repeated presses, with no dead press when the value is its own block. The playground enables it by default.
• Collab rides a reserved __slots Y.Map. __slots and __slotHost join the synced-property exclusions in both directions, and slots serialize through a per-slot-diffed Y.Map on the host attribute channel on both the V1 (_xmlText) and V2 (XmlElement) paths. (The attribute key reuses the host's own __slots field name: it can't be $-prefixed like the $slots JSON key below — $ breaks XmlElement.toDOM — and node properties sync under their __-prefixed names, so reusing the already-excluded __slots field name lets that single exclusion reserve the channel too, while a user field literally named slots keeps syncing.) The observers route first-set/undo transaction shapes (which surface as a changed __slots key, not a YMapEvent) to the slot reconcile, validate-and-skip malformed remote entries, and sweep deleted structs so remote host deletion doesn't leak collab-node map entries. Root-host slots sync like any other host's.
• JSON serializes slots under a reserved $slots key (declared on SerializedLexicalNode). The $ prefix mirrors the NodeState '$' key and keeps the framework-owned channel out of the namespace a third-party subclass may already use for a serialized slots property of its own. NodeKeys aren't serialized, so the name is the identity, and a dedicated key is the natural place for it.
• Whole-host copy carries the body. An ElementNode in a NodeSelection (e.g. a Card promoted whole-host from a chrome click) serializes with all of its children even though they aren't in the selection themselves — see Breaking Changes; the old shell-only output made cut silently lossy. The promotion only applies to NodeSelection — a partial RangeSelection over the host keeps per-child slicing, so drags never over-export unselected content.
• HTML slot serialization is opt-in per host, with no orphan heuristics on import. Like NodeState, the HTML exporter never descends into slots on its own; a host emits each slot as a <div data-lexical-slot="<name>"> inside its own wrapper from exportDOM (via $appendNodeToHTML), and its import rule maps those wrappers back through $setSlot with the slot names whitelisted per rule, so hostile markup can't reach $setSlot. Each demo host's import rule is collocated in the node's own extension (defineImportRule via DOMImportExtension, depending on CoreImportExtension so the paragraph/text rules exist and the host rule is ordered ahead of the generic block rules); the playground's always-on ClipboardDOMImportExtension routes pastes through it, so Card / Review / PullQuote round-trip through HTML copy/paste with their slots and per-host state (e.g. the Review's data-rating) intact. The exporter structurally can't emit a slot wrapper without its host (when a partially-selected host is dropped, its slot wrappers are dropped with it), so a bare orphaned wrapper only arises from browser-native serialization of an interior selection on surfaces Lexical doesn't control (e.g. copying from a published rendering of exported HTML); those degrade to content-only paste, the same convention as interior copies of any other container. Single-line slots import through the same inline projection as the paste path.
• Playground host ergonomics live entirely in lexical-playground. Small per-host helpers make the three boxes feel like first-class blocks without touching core. ArrowDown/Up at a host's bottom/top edge steps between its editable regions, or — when the host is the last/first block — inserts a paragraph so it is never a navigational dead end; the region order is read from the rendered DOM (a chrome may render children above, below, or between the slots). The browser performs those moves natively except across a contentEditable island boundary, which Firefox will not cross, so the step between islanded regions (Review body↔author, PullQuote quote↔attribution) is done with a programmatic selectStart/selectEnd there. Because arrow-escape re-creates a paragraph on demand, insertion no longer seeds a blank paragraph before the host. Backspace deletes an empty host (from the start of its first region, or from the block immediately after it), and a non-collapsed select-all that spans a first-block host re-anchors its start to before the host so the whole node is replaced by a paragraph in one press instead of only clearing its contents. A chrome click (the padding outside the slots) promotes Card / PullQuote to a whole-host NodeSelection; PullQuote additionally maps Escape from either slot → NodeSelection and Enter on the selected host → its quote.

Three gaps remain. First, the caret / NodeCaret APIs throw across a slot boundary ("no common ancestor"), so the clamp resolves its direction with a model comparator instead of the caret system. Second, nested slots (a slot whose host is itself slotted) are out of scope at the runtime layer here: the model comparator reduces a slot-internal point to its host only one level deep, and neither demo nests slots, so the deeper case is left for a follow-up. The static lookup side (e.g. $getSlotNameWithinHost) is already covered. Third, mixed-version collab: pre-slots V1 clients receiving slot data from upgraded peers will error rather than render it, so enabling slots in long-lived shared documents should be gated on all participants running this version (new clients tolerate unknown slot data going forward).

Closes #5930
Closes #6613

Test plan

• pnpm tsc --noEmit -p tsconfig.json / -p tsconfig.test.json clean
• pnpm flow — no errors
• pnpm vitest run --project unit — full unit suite green (slot suites + reconciler / selection / node / html / yjs-sync regression), including:
  • canonical slot order (declared / mixed / undeclared / subclass redeclaration, DOM + JSON order), copy-on-write slot maps, block-shaped slot values (Enter no-op, <input>-style paste flattening, boundary backspace, scope-root resolution)
  • hidden-placeholder rendering and explicit attachment: default-hidden containers for both host kinds, mountSlotContainer/unmountSlotContainer reveal/park round-trip, the $getSlotTargetElement render-config override (in-place reveal; reconciles keep mounted containers in their targets), and the mutation-observer scaffolding guard
  • editable-island state: a decorator-host island follows setEditable, the reconcile re-applying its contentEditable on a read-only toggle with no extension
  • collab two-doc relay tests through the real observer path: first slot set on a synced element / decorator host, Y.UndoManager undo convergence, concurrent first-sets and declared+undeclared adds converging in canonical order, hostile remote entries skipped, remote-deletion collab-map cleanup, root-host slots
  • clipboard: in-slot selection copy on both channels, whole-host NodeSelection child inclusion, partial-range over an element host never over-exports, excluded-slot-value guards
  • SelectBlockExtension × slots compose suite (block → slot → document escalation, frame-aware $isBlockFullySelected, disabled fallback to the scoped default)
• e2e (chromium / firefox / webkit × rich-text / plain-text / collab v1 / collab v2 as applicable):
  • CardSlot.spec.mjs / PullQuoteSlot.spec.mjs / SlotCollabConvergence.spec.mjs / SelectBlock.spec.mjs green; the Linux Firefox selectAll helper now presses the real shortcut (the E2E keyboardShortcuts/index.mjs -> selectAll(page) Linux selection should be normalized #4665 emulation is removed), so no firefox skips remain
  • ReviewSlot.spec.mjs (the React-chromed ElementNode demo — rating widget click/hover/persist, both editable islands isolated, HTML export→import round-trip, empty-box and rated-box backspace deletion, select-all replace) green on chromium and firefox
  • SlotHostArrowEscape.spec.mjs (ArrowDown/Up escape + cross-island field navigation across Card / Review / PullQuote, wrapped-line offset behavior) green on chromium and firefox
• Manual scenarios across Chrome / Firefox / Safari covering:
  • Card: typing in the title slot and body children, slot rendering order stays (title before body), <div data-lexical-slot> wrappers stable after re-render; title serializes as a bare paragraph ($slots.title.type === 'paragraph', no container level)
  • Card click / select: chrome click → whole-host NodeSelection; slot-text click → caret in that slot; Tab / Shift+Tab bridge title ↔ body
  • Card delete boundary: Backspace at title start of a non-empty Card → no-op; Delete (forward) at title end → no-op; Backspace / Delete inside a slot deletes only slot-internal characters; Enter in the title is a no-op (single-line slot)
  • PullQuote: typing in quote / attribution slots, slot isolation; Enter in attribution is a no-op; Backspace at the start of the quote's second paragraph merges within the quote slot, doesn't leak out
  • PullQuote click / select: chrome click → whole-host NodeSelection; slot click → caret in that slot; arrow keys from neighboring paragraphs → whole-host NodeSelection; Backspace on a selected host removes the host; Escape from a slot → whole-host NodeSelection, Enter on the selected host → caret in quote
  • Review: click/hover the star widget sets / previews the rating (persists to NodeState, rides undo / copy / collab); body children and author slot edit in isolation; the — author prefix shows in CSS; HTML export → external editor → paste back restores both regions and data-rating
  • Host ergonomics (Card / Review / PullQuote): inserting /card /review /pull seeds no leading blank paragraph; ArrowDown/Up at the bottom/top edge inserts a paragraph when the host is the last/first block and otherwise steps between regions (including across the Review/PullQuote contentEditable islands in Firefox); Backspace at the start of an empty host (or the block right after it) deletes it; a select-all spanning a first-block Review is replaced by a single paragraph in one press
  • Read-only: toggling the editor read-only flips the slot islands non-editable (Review author / body, PullQuote quote / attribution) and back; each editor reconciles its own islands, so a nested editor's islands are unaffected by the outer editor's state
  • HTML round-trip: Card / PullQuote / Review export → external editor → paste back restores slot text (single-line slots flatten multi-block input like an <input>); internal clipboard round-trips custom slot content, not the defaults; cut/copy of a selection inside a slot round-trips
  • Collab (both V1 and V2): per-slot typing replicates both ways for Card + PullQuote + Review; the first slot set on an already-synced host reaches peers; host delete propagates; both clients converge on host + slots and on slot order
  • Regression: existing rich-text features (LinkNode / CodeNode / Markdown / list / table / mention / hashtag / bold / inline-code) work inside and outside a slot
  • Equation: the root-level atomic decorator still works (a separate demo from PullQuote, not a slot host)
  • deleteLine + SELECT_ALL: Cmd+Backspace inside a slot deletes only slot-internal characters, on a NodeSelection deletes the host; Cmd+A inside a slot stays scoped to that slot (default), table cells keep legacy whole-document Cmd+A; with SelectBlockExtension (playground default) repeated Cmd+A expands block → slot → document
  • Edge cases: empty root Cmd+A; paste into an empty slot; nested host; undo / redo across host insert / delete and slot-internal typing; collab delete during IME composition; Korean composition inside a slot — no leak across slot boundary
• No invariant or console warnings throughout