[lexical][lexical-html] Bug Fix: gate trailing <br> import drop on managed line breaks

packages/lexical-html/src/import/coreImportRules.ts

@@ -30,6 +30,7 @@ import {
   isBlockDomNode,
   isDOMTextNode,
   isLastChildInBlockNode,
+  isManagedLineBreak,
   isOnlyChildInBlockNode,
   type LexicalNode,
   setNodeIndentFromDOM,
@@ -446,14 +447,17 @@ const IgnoreScriptStyleRule = /* @__PURE__ */ defineImportRule({
 });
 
 const LineBreakRule = /* @__PURE__ */ defineImportRule({
-  // Mirror the legacy LineBreakNode.importDOM filter: stray `<br>` that
-  // are the sole or trailing child of a block parent (e.g. Apple's
-  // `<br class="Apple-interchange-newline">` clipboard sentinel, or the
-  // trailing `<br>` browsers insert after the last text in a `<div>`)
-  // would otherwise survive as a LineBreakNode and tack an extra blank
-  // line onto the imported content.
+  // Mirror the LineBreakNode.importDOM filter: drop `<br>` that are only a
+  // rendering artifact rather than authored content. The sole child of a
+  // block is dropped (empty `<li>`/`<p>` round-trips as an empty element),
+  // and a trailing `<br>` is dropped only when it is a managed line break —
+  // Lexical's own `data-lexical-managed-linebreak` terminator or Safari's
+  // `<br class="Apple-interchange-newline">` clipboard sentinel. An ordinary
+  // authored trailing `<br>` is preserved so round-trip serialization to
+  // HTML stays lossless.
   $import: (_ctx, el) =>
-    isOnlyChildInBlockNode(el) || isLastChildInBlockNode(el)
+    isOnlyChildInBlockNode(el) ||
+    (isLastChildInBlockNode(el) && isManagedLineBreak(el))
       ? []
       : [$createLineBreakNode()],
   match: sel.tag('br'),

packages/lexical-utils/src/__tests__/unit/LexicalEventHelpers.test.tsx

@@ -737,9 +737,25 @@ describe('LexicalEventHelpers', () => {
         },
         {
           expectedHTML:
-            '<p class="editor-paragraph" dir="auto"><span data-lexical-text="true">1</span></p><p class="editor-paragraph" dir="auto"><span data-lexical-text="true">2</span></p><p class="editor-paragraph" dir="auto"><span data-lexical-text="true">3</span></p>',
+            '<p class="editor-paragraph" dir="auto"><span data-lexical-text="true">1</span></p><p class="editor-paragraph" dir="auto"><span data-lexical-text="true">2</span><br><br data-lexical-managed-linebreak="true"></p><p class="editor-paragraph" dir="auto"><span data-lexical-text="true">3</span></p>',
           inputs: [pasteHTML('1<p>2<br /></p>3')],
-          name: 'last br in a block node is ignored',
+          name: 'authored trailing br in a block node is preserved',
+        },
+        {
+          expectedHTML:
+            '<p class="editor-paragraph" dir="auto"><span data-lexical-text="true">1</span></p><p class="editor-paragraph" dir="auto"><span data-lexical-text="true">2</span></p><p class="editor-paragraph" dir="auto"><span data-lexical-text="true">3</span></p>',
+          inputs: [
+            pasteHTML('1<p>2<br data-lexical-managed-linebreak="true" /></p>3'),
+          ],
+          name: 'managed trailing br in a block node is ignored',
+        },
+        {
+          expectedHTML:
+            '<p class="editor-paragraph" dir="auto"><span data-lexical-text="true">1</span></p><p class="editor-paragraph" dir="auto"><span data-lexical-text="true">2</span></p><p class="editor-paragraph" dir="auto"><span data-lexical-text="true">3</span></p>',
+          inputs: [
+            pasteHTML('1<p>2<br class="Apple-interchange-newline" /></p>3'),
+          ],
+          name: 'apple-interchange trailing br in a block node is ignored',
         },
       ];
 

packages/lexical/src/LexicalMutations.ts

@@ -55,7 +55,13 @@ function initTextEntryListener(editor: LexicalEditor): void {
   }
 }
 
-function isManagedLineBreak(
+// True when `dom` is a line break the editor is actively managing in the
+// live DOM — identified by the `__lexicalLineBreak` slot reference or by
+// having a node key. This is distinct from `isManagedLineBreak` in
+// LexicalLineBreakNode, which inspects serialized markup (the
+// `data-lexical-managed-linebreak` attribute / Apple-interchange class)
+// to decide whether a parsed `<br>` should be dropped on import.
+function isEditorManagedLineBreak(
   dom: Node,
   target: Node & LexicalPrivateDOM,
   editor: LexicalEditor,
@@ -202,7 +208,7 @@ function flushMutations(
               parentDOM != null &&
               addedDOM !== blockCursorElement &&
               node === null &&
-              !isManagedLineBreak(addedDOM, parentDOM, editor) &&
+              !isEditorManagedLineBreak(addedDOM, parentDOM, editor) &&
               // @experimental named-slots. Slot containers are keyless
               // reconciler scaffolding: a flush that observes one being
               // parked in its host or relocated by an explicit mount must
@@ -243,7 +249,7 @@ function flushMutations(
               const removedDOM = removedDOMs[s];
 
               if (
-                isManagedLineBreak(removedDOM, targetDOM, editor) ||
+                isEditorManagedLineBreak(removedDOM, targetDOM, editor) ||
                 blockCursorElement === removedDOM
               ) {
                 targetDOM.appendChild(removedDOM);
@@ -289,7 +295,7 @@ function flushMutations(
             if (
               parentDOM != null &&
               addedDOM.nodeName === 'BR' &&
-              !isManagedLineBreak(addedDOM, target, editor)
+              !isEditorManagedLineBreak(addedDOM, target, editor)
             ) {
               parentDOM.removeChild(addedDOM);
             }

packages/lexical/src/index.ts

@@ -391,6 +391,7 @@ export {
   $createLineBreakNode,
   $isLineBreakNode,
   isLastChildInBlockNode,
+  isManagedLineBreak,
   isOnlyChildInBlockNode,
   LineBreakNode,
 } from './nodes/LexicalLineBreakNode';

packages/lexical/src/nodes/LexicalLineBreakNode.ts

@@ -19,6 +19,7 @@ import {
   $applyNodeReplacement,
   isBlockDomNode,
   isDOMTextNode,
+  isHTMLElement,
 } from '../LexicalUtils';
 
 export type SerializedLineBreakNode = SerializedLexicalNode;
@@ -58,7 +59,10 @@ export class LineBreakNode extends LexicalNode {
   static importDOM(): DOMConversionMap | null {
     return {
       br: (node: Node) => {
-        if (isOnlyChildInBlockNode(node) || isLastChildInBlockNode(node)) {
+        if (
+          isOnlyChildInBlockNode(node) ||
+          (isLastChildInBlockNode(node) && isManagedLineBreak(node))
+        ) {
           return null;
         }
         return {
@@ -154,3 +158,33 @@ export function isLastChildInBlockNode(node: Node): boolean {
 function isWhitespaceDomTextNode(node: Node): boolean {
   return isDOMTextNode(node) && /^( |\t|\r?\n)+$/.test(node.textContent || '');
 }
+
+/**
+ * True when `node` is a `<br>` that exists only as a rendering artifact
+ * rather than authored content, and therefore should be dropped on import
+ * to avoid a phantom trailing line break:
+ *
+ * - `data-lexical-managed-linebreak="true"`: the terminating `<br>` that
+ *   Lexical's reconciler injects so a trailing line break is not collapsed
+ *   by the parent block element (see `LexicalDOMSlot.setManagedLineBreak`).
+ *   Re-importing Lexical's own exported HTML must not turn this into a real
+ *   `LineBreakNode`.
+ * - `class="Apple-interchange-newline"`: the trailing `<br>` WebKit/Safari
+ *   appends to clipboard HTML as a transport artifact.
+ *
+ * An ordinary authored trailing `<br>` carries neither marker and is
+ * preserved so that round-trip serialization to HTML stays lossless.
+ *
+ * Note: this inspects *serialized markup* and is distinct from
+ * `isEditorManagedLineBreak` in `LexicalMutations`, which identifies a
+ * line break the editor is actively managing in the live DOM.
+ */
+export function isManagedLineBreak(node: Node): boolean {
+  if (node.nodeName !== 'BR' || !isHTMLElement(node)) {
+    return false;
+  }
+  return (
+    node.getAttribute('data-lexical-managed-linebreak') === 'true' ||
+    node.getAttribute('class') === 'Apple-interchange-newline'
+  );
+}