Description

When a HeadingNode (or any non-empty block ElementNode) sits directly after an empty ParagraphNode, pressing Backspace at the heading's start merges the heading's children into the empty paragraph and removes the heading. The heading's type gets discarded as part of the merge. Separately, when a non-empty HeadingNode is the first block in the document (no previous sibling), pressing Backspace at its start unconditionally replaces it with a brand-new HeadingNode of the same tag — the visible markup is unchanged but the node identity (__key) churns on every Backspace. The Google Docs convention many users expect is the opposite: in the first case, remove the empty previous block and preserve the heading; in the second, leave the heading untouched.

Breaking Change

Two scenarios change at Backspace at a block start:

• Heading-after-empty-paragraph. Previously the cross-block merge ran and discarded the heading's type. Now the empty paragraph is removed and the heading is preserved. Applies to any non-empty block ElementNode (Heading, Quote, list items, custom subclasses). Observable only in this exact shape; direct removeText() calls and selections spanning non-empty blocks are unchanged.
• Non-empty heading with no previous block. Previously HeadingNode.collapseAtStart self-replaced with a fresh HeadingNode of the same tag every time Backspace was pressed, churning the node __key and firing a phantom destroyed + created mutation pair even though the visible markup was unchanged. Now the heading is left in place: no __key churn, no mutation pair, no resulting history entry. Mutation listeners on HeadingNode (e.g. LexicalTableOfContentsPlugin) and any external code tracking heading keys stop seeing these phantom events; the visible DOM is unchanged in both old and new behavior.

Fix

Two narrow exceptions, both at the start of a block on Backspace.

1. Heading after an empty paragraph. RangeSelection.deleteCharacter reaches the merge-block branch with state.caret.origin pointing at the empty adjacent block and state.block pointing at the (non-empty) anchor block. The branch then calls removeText(), and the cross-block merge in $removeTextFromCaretRange always wins on the earlier block's type — that's where the heading is lost. A narrow exception is added at the top of the merge-block branch: when the adjacent block is empty and the anchor block is not, remove just that empty adjacent block and leave the selection where it is. removeText() isn't called, so the cross-block merge never runs and the anchor block's type is preserved. Type-agnostic: applies to Heading, Quote, list items, custom subclasses without per-type branching. The exception is also limited to adjacent blocks at the same nesting level (caret.origin.getParent() === block.getParent()), so a structural wrapper like a ListNode whose only child is an empty ListItemNode falls through to the default cross-block merge — the ListNode is not treated as empty just because its only child is. This mirrors Google Docs' Backspace-at-heading behavior next to an empty bullet (the heading text is pulled into the list item).

2. Non-empty heading with no previous block. RangeSelection.deleteCharacter falls through the merge logic (no previous block to merge with) and ultimately invokes $collapseAtStart, which walks ancestors calling collapseAtStart until one returns true. HeadingNode.collapseAtStart previously self-replaced with a fresh HeadingNode of the same tag (and moved children over) even when non-empty — semantically a no-op but observable as __key churn. The non-empty branch now just signals "handled" by returning true without replacing. The empty-heading branch (heading → paragraph) is unchanged. QuoteNode and ListItemNode collapseAtStart are intentionally untouched: they implement escape semantics ("Backspace at start escapes to paragraph" / list outdent), so the second exception stays Heading-specific, matching levensta's report.

Scope

Two adjacent cases are still out of scope:

• The general removeText merge policy. Changing the cross-block merge itself (e.g. "later block wins" or "non-empty wins") would also affect direct removeText() calls and user-initiated selections that span non-empty blocks. That's a broader observable behavior change for any caller relying on the current "earlier block's type wins" rule.
• The trailing LineBreakNode case. levensta noted on the issue thread that a non-empty paragraph ending in a LineBreakNode triggers the same merge. Treating that as "empty enough" to qualify for the exception is a judgment call about what counts as empty, and seems worth its own discussion.

If a broader scope is preferred, drop a comment and I'll fold either (or both) into this PR.

Refs #4359

Test plan

• pnpm vitest run --project unit — 113 files / 2493 tests pass. New Backspace at start of heading (#4359) describe block in LexicalHeadingNode.test.ts:
  • Five test.for cases for the merge-block exception: heading preserved after empty paragraph; quote preserved after empty paragraph (type-agnostic); only the empty paragraph is removed between two non-empty siblings; legacy cross-block merge still applies when previous block is non-empty (out-of-scope marker); a ListNode whose only child is an empty ListItemNode falls through to the default cross-block merge (heading text is pulled into the list item), pinning the same-nesting-level limit on the exception.
  • Four direct HeadingNode.collapseAtStart cases for the second exception: non-empty heading preserved with same getKey() (catches the recreate regression — the previous code self-replaced and the test fails without the fix); preserved when the heading is wrapped inside another ElementNode; preserved when the heading is followed by a non-paragraph sibling (e.g. a list); empty heading still converts to paragraph (existing behavior).
• pnpm tsc clean.
• e2e Headings/ on chromium — 4/4 pass. The existing '... stays as a heading when you backspace at the start of a heading with no previous sibling nodes present' test covers the DOM-level behavior of the second exception; the getKey() check sits in the unit suite because the regression is invisible at the DOM level. Firefox/webkit weren't re-run this revision — no e2e files changed.
• Manual playground sanity check:
  • empty paragraph + H1 ("Welcome") with caret at heading start, Backspace → empty paragraph removed, H1 preserved.
  • same shape with a Quote block instead of H1 → Quote preserved.
  • non-empty paragraph + H1 with caret at heading start, Backspace → existing behavior (merged into the previous paragraph, type discarded) — confirms no regression for the out-of-scope case.
  • heading-only at root start, caret at heading start, Backspace pressed multiple times → heading stays, no visible churn; typing afterwards prepends cleanly.

Note: the new direct HeadingNode.collapseAtStart tests invoke the method directly because jsdom doesn't implement Selection.modify, which deleteCharacter falls through to when no previous block exists. The end-to-end keyboard path is covered by the existing e2e test in the Headings/ suite.