[lexical] Bug Fix: Normalize non-inline nodes when inserting into inline-only parents

[etrepum]

Description

RangeSelection.insertNodes could throw, or produce an invalid document
structure, when the destination block cannot legally contain the inserted
non-inline content.

• Inserting a DecoratorNode into the block cursor inside an ElementNode threw an exception (Bug: Inserting a DecoratorNode into the block cursor inside an ElementNode throws an exception #8713).
• Pasting a non-inline node (e.g. a HorizontalRuleNode) into an inline-only parent such as a collapsible title produced an invalid tree: a non-inline child nested inside an element that may only contain inline children (Bug: Paste doesn't properly normalize non-inline nodes when the destination shouldn't contain them #8724).

The document structure rules being enforced are:

• RootNode and shadow-root ElementNodes may only have non-inline children.
• Other non-inline ElementNodes may only contain inline children.
• Inline ElementNodes may only contain inline children.
• ListNode/ListItemNode have their own containment rules and relocate themselves via isParentRequired().

This PR makes insertNodes keep the tree valid by splitting/relocating, or dropping content that has no valid inline form, instead of crashing or nesting nodes illegally. Two cases are added:

• No enclosing block (firstBlock === null) — each top-level inserted block is placed relative to the nearest root using $insertNodeToNearestRootAtCaret, rather than splicing a block into a context that cannot hold it.
• Inline-only enclosing block — when the enclosing block is a non-inline, non-shadow-root ElementNode whose parent is not a root/shadow root and which does not require a specific parent, the inserted nodes are reduced to their inline content and spliced in. Non-inline nodes with no inline form (e.g. HorizontalRuleNode) are dropped rather than nested illegally. isParentRequired() leaves list structures on the existing code path so list paste behavior is unchanged.

The fix lives entirely in the lexical core package and requires no changes to node implementations or their extensions.

This PR also includes preparatory/hygiene changes:

• Moves $insertNodeToNearestRootAtCaret from @lexical/utils into the lexical core package (caret/LexicalCaretUtils), exports it from lexical, and re-exports it from @lexical/utils for backwards compatibility. This lets insertNodes use the helper without a circular dependency on @lexical/utils.
• Switches internal consumers to import core re-exports directly from lexical (e.g. $insertNodeToNearestRootAtCaret, addClassNamesToElement, removeClassNamesFromElement, mergeRegister, $findMatchingParent, isHTMLElement, isHTMLAnchorElement, $splitNode, isBlockDomNode, isInlineDomNode, $getAdjacentSiblingOrParentSiblingCaret), and replaces relative test imports with package imports where the symbol is public. The examples/ projects are intentionally left on the published-package imports.

Closes #8713
Closes #8724

Test plan

Before

• Following the repro (clear editor → /divider, Enter → Backspace, Cut →
  /collapsible, Enter → Paste) crashes / leaves the editor with a
  non-inline HorizontalRuleNode nested inside the inline-only
  CollapsibleTitleNode.
• Inserting a DecoratorNode into a block cursor inside an ElementNode
  throws.

After

• New Issue8724Repro unit tests cover the no-block and inline-only-parent
  cases with shadow-root, inline-only element, and list parents, using
  decorator and element nodes.
• New Issue8724Collapsible playground unit test reproduces the paste-into-
  collapsible-title repro and asserts the collapsible is left intact and the
  block is dropped.
• tsc, eslint, and prettier are clean across the workspace; full unit
  and e2e suites (including the lists and copy/paste suites) pass.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
lexical	Ready	Preview, Comment	Jun 20, 2026 4:37pm
lexical-playground	Ready	Preview, Comment	Jun 20, 2026 4:37pm