fix(super-editor): preserve line breaks through DOCX export (SD-3278)

Multi-line text passed into text-mode mutations stored newlines as a raw
\n inside one <w:t>, which Word collapses on open while SuperDoc renders
it as a break. Convert newlines to lineBreak nodes at creation, and split
any residual raw newline into <w:t>/<w:br/> within one run on export, so
the break serializes as a Word-native <w:br/> (ECMA-376 17.3.3.1).

- buildTextWithTabs: normalize \n, \r\n, \r to lineBreak nodes, gated on
  parent admission for text*-only parents (e.g. total-page-number)
- materializeLineBreak: prefer lineBreak over hardBreak so a structural
  kind:'lineBreak' is a soft break, not a page break
- del-translator: rename every <w:t> in a split run to <w:delText>
  (17.3.3.7 requires delText for all deleted text)

Author: caio-pizzol

packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/del/del-translator.js

@@ -104,12 +104,18 @@ function decode(params) {
     return null;
   }
 
-  // ECMA-376 renames w:t → w:delText inside <w:del>. Other inline content —
-  // w:noBreakHyphen, w:tab, w:br, etc. — stays as-is; the deletion is
-  // conveyed by the <w:del> wrapper alone. Guard the rename so non-text
-  // atoms inside <w:del> don't crash.
-  const textNode = translatedTextNode.elements.find((n) => n.name === 'w:t');
-  if (textNode) textNode.name = 'w:delText';
+  // ECMA-376 (17.3.3.7) requires w:delText for ALL text runs inside <w:del>. A
+  // single run can now hold multiple <w:t> siblings, because the newline export
+  // safety net splits text around <w:br/> (e.g. <w:t>Alpha</w:t><w:br/><w:t>Beta</w:t>),
+  // so rename every direct w:t, not just the first; a leftover <w:t> inside
+  // <w:del> would not be treated as deleted. Other inline content
+  // (w:noBreakHyphen, w:tab, w:br, etc.) stays as-is; the <w:del> wrapper alone
+  // conveys the deletion.
+  (translatedTextNode.elements || [])
+    .filter((n) => n.name === 'w:t')
+    .forEach((n) => {
+      n.name = 'w:delText';
+    });
 
   return {
     name: 'w:del',

packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/del/del-translator.test.js

@@ -177,6 +177,37 @@ describe('w:del translator', () => {
       expect(result.elements[0].elements[0].name).toBe('w:delText');
     });
 
+    it('renames every <w:t> in a multi-segment run to <w:delText> (newline split)', () => {
+      const mockTrackedMark = {
+        type: 'trackDelete',
+        attrs: {
+          id: '789',
+          sourceId: '',
+          author: 'Test',
+          authorEmail: 'test@example.com',
+          date: '2025-10-09T12:00:00Z',
+        },
+      };
+
+      // The newline export safety net produces one run with interleaved w:t/w:br;
+      // every w:t inside <w:del> must become w:delText, not just the first.
+      exportSchemaToJson.mockReturnValue({
+        name: 'w:r',
+        elements: [
+          { name: 'w:t', elements: [{ text: 'Alpha', type: 'text' }] },
+          { name: 'w:br' },
+          { name: 'w:t', elements: [{ text: 'Beta', type: 'text' }] },
+        ],
+      });
+
+      const node = { type: 'text', text: 'Alpha\nBeta', marks: [mockTrackedMark] };
+      const result = config.decode({ node });
+
+      const run = result.elements[0];
+      expect(run.elements.map((n) => n.name)).toEqual(['w:delText', 'w:br', 'w:delText']);
+      expect(run.elements.some((n) => n.name === 'w:t')).toBe(false);
+    });
+
     it('writes sourceId to w:id for round-trip fidelity', () => {
       const mockTrackedMark = {
         type: 'trackDelete',

packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/t/helpers/translate-text-node.js

@@ -44,11 +44,38 @@ export function getTextNodeForExport(text, marks, params) {
     partPath: resolveExportPartPath(params),
   });
 
-  textNodes.push({
-    name: 'w:t',
-    elements: [{ text, type: 'text' }],
-    attributes: nodeAttrs,
-  });
+  const textValue = typeof text === 'string' ? text : '';
+  // Normalize CRLF/CR to LF so Windows line endings export Word-native breaks
+  // too, rather than leaving a stray carriage return inside <w:t>.
+  const normalizedText = textValue.includes('\r') ? textValue.replace(/\r\n?/g, '\n') : textValue;
+  if (normalizedText.includes('\n')) {
+    // Export safety net: a raw newline inside <w:t> is whitespace that Word
+    // collapses on open (it is not the OOXML representation of a line break),
+    // while SuperDoc still renders it as a break: the SD-3278
+    // divergence. Emit a Word-native <w:br/> between
+    // segments instead. Everything stays inside this single run so the
+    // surrounding <w:ins>/<w:del> wrappers keep wrapping exactly one run.
+    const segments = normalizedText.split('\n');
+    segments.forEach((segment, index) => {
+      if (segment.length > 0) {
+        const segmentNeedsSpace = /^\s|\s$/.test(segment);
+        textNodes.push({
+          name: 'w:t',
+          elements: [{ text: segment, type: 'text' }],
+          attributes: segmentNeedsSpace ? { 'xml:space': 'preserve' } : null,
+        });
+      }
+      if (index < segments.length - 1) {
+        textNodes.push({ name: 'w:br' });
+      }
+    });
+  } else {
+    textNodes.push({
+      name: 'w:t',
+      elements: [{ text: normalizedText, type: 'text' }],
+      attributes: nodeAttrs,
+    });
+  }
 
   // For custom mark export, we need to add a bookmark start and end tag
   // And store attributes in the bookmark name

packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/t/helpers/translate-text-node.test.js

@@ -134,4 +134,80 @@ describe('getTextNodeForExport', () => {
     const runPropertiesChange = runProperties.elements.find((element) => element.name === 'w:rPrChange');
     expect(runPropertiesChange.attributes['w:id']).toBe('7');
   });
+
+  // SD-3278 export safety net: a raw newline left inside a PM text
+  // node (e.g. from an imported .docx that stored breaks as literal '\n') must
+  // export as a Word-native <w:br/>, not a collapsed newline inside <w:t>.
+  describe('raw newline export safety net', () => {
+    const contentElements = (result) => result.elements.filter((el) => el.name === 'w:t' || el.name === 'w:br');
+
+    it('exports a single newline as <w:t>/<w:br/>/<w:t> within one run', () => {
+      const result = getTextNodeForExport('Alpha\nBeta', [], buildParams());
+      expect(result.name).toBe('w:r');
+      const content = contentElements(result);
+      expect(content.map((el) => el.name)).toEqual(['w:t', 'w:br', 'w:t']);
+      expect(content[0].elements[0].text).toBe('Alpha');
+      expect(content[2].elements[0].text).toBe('Beta');
+    });
+
+    it('never leaves a raw newline inside a <w:t>', () => {
+      const result = getTextNodeForExport('Alpha\nBeta', [], buildParams());
+      const texts = result.elements.filter((el) => el.name === 'w:t');
+      expect(texts.some((el) => el.elements[0].text.includes('\n'))).toBe(false);
+    });
+
+    it('emits a soft break (no w:type="page") for the <w:br/>', () => {
+      const result = getTextNodeForExport('Alpha\nBeta', [], buildParams());
+      const br = result.elements.find((el) => el.name === 'w:br');
+      expect(br).toBeDefined();
+      expect(br.attributes?.['w:type']).toBeUndefined();
+    });
+
+    it('leaves newline-free text as a single <w:t> (unchanged)', () => {
+      const result = getTextNodeForExport('hello world', [], buildParams());
+      const content = contentElements(result);
+      expect(content).toHaveLength(1);
+      expect(content[0].name).toBe('w:t');
+      expect(content[0].elements[0].text).toBe('hello world');
+    });
+
+    it('emits a <w:br/> for each newline including leading, trailing, and consecutive newlines', () => {
+      const result = getTextNodeForExport('\nA\n\nB\n', [], buildParams());
+      const content = contentElements(result);
+      expect(content.map((el) => el.name)).toEqual(['w:br', 'w:t', 'w:br', 'w:br', 'w:t', 'w:br']);
+      const texts = content.filter((el) => el.name === 'w:t').map((el) => el.elements[0].text);
+      expect(texts).toEqual(['A', 'B']);
+    });
+
+    it('sets xml:space="preserve" only on segments with edge whitespace', () => {
+      const result = getTextNodeForExport('Alpha \n Beta', [], buildParams());
+      const texts = result.elements.filter((el) => el.name === 'w:t');
+      expect(texts[0].elements[0].text).toBe('Alpha ');
+      expect(texts[0].attributes).toEqual({ 'xml:space': 'preserve' });
+      expect(texts[1].elements[0].text).toBe(' Beta');
+      expect(texts[1].attributes).toEqual({ 'xml:space': 'preserve' });
+    });
+
+    it('does not set xml:space on segments without edge whitespace', () => {
+      const result = getTextNodeForExport('Alpha\nBeta', [], buildParams());
+      const texts = result.elements.filter((el) => el.name === 'w:t');
+      expect(texts[0].attributes).toBeNull();
+      expect(texts[1].attributes).toBeNull();
+    });
+
+    it('normalizes CRLF to a <w:br/> on export', () => {
+      const content = contentElements(getTextNodeForExport('Alpha\r\nBeta', [], buildParams()));
+      expect(content.map((el) => el.name)).toEqual(['w:t', 'w:br', 'w:t']);
+      expect(content[0].elements[0].text).toBe('Alpha');
+      expect(content[2].elements[0].text).toBe('Beta');
+    });
+
+    it('normalizes a bare CR to a <w:br/> without leaving a stray carriage return in <w:t>', () => {
+      const result = getTextNodeForExport('Alpha\rBeta', [], buildParams());
+      const content = contentElements(result);
+      expect(content.map((el) => el.name)).toEqual(['w:t', 'w:br', 'w:t']);
+      const texts = result.elements.filter((el) => el.name === 'w:t');
+      expect(texts.some((el) => el.elements[0].text.includes('\r'))).toBe(false);
+    });
+  });
 });

packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-with-tabs.test.ts

@@ -2,7 +2,9 @@ import { describe, expect, it, vi } from 'vitest';
 import { Fragment, Schema } from 'prosemirror-model';
 import { buildTextWithTabs, parentAllowsNodeAt, textBetweenWithTabs } from './text-with-tabs.js';
 
-function makeRealSchema(options: { hasTab?: boolean; hasNoBreakHyphen?: boolean; hasGenericLeaf?: boolean } = {}) {
+function makeRealSchema(
+  options: { hasTab?: boolean; hasLineBreak?: boolean; hasNoBreakHyphen?: boolean; hasGenericLeaf?: boolean } = {},
+) {
   const nodes: Record<string, any> = {
     doc: { content: 'paragraph+' },
     paragraph: { group: 'block', content: 'inline*' },
@@ -13,6 +15,11 @@ function makeRealSchema(options: { hasTab?: boolean; hasNoBreakHyphen?: boolean;
     // Tab is non-leaf, which is why `textBetweenWithTabs` (not PM's built-in textBetween) is needed.
     nodes.tab = { group: 'inline', inline: true, atom: true, content: 'inline*' };
   }
+  if (options.hasLineBreak) {
+    // Mirrors the real extensions/line-break/line-break.js shape: inline atom
+    // that disallows marks (`marks: ''`) and renders to <br> / exports to <w:br/>.
+    nodes.lineBreak = { group: 'inline', inline: true, atom: true, marks: '' };
+  }
   if (options.hasNoBreakHyphen) {
     // Mirrors the real extensions/no-break-hyphen schema: inline leaf atom with leafText.
     nodes.noBreakHyphen = { group: 'inline', inline: true, atom: true, leafText: () => '‑' };
@@ -99,6 +106,108 @@ describe('buildTextWithTabs', () => {
     expect(result.child(2).text).toBe('y');
     expect(result.child(2).marks.some((m: any) => m.type.name === 'bold')).toBe(true);
   });
+
+  // SD-3278: a literal '\n' inside a text node exports as raw newline
+  // inside <w:t>, which Word collapses. It must become a `lineBreak` node so the
+  // exporter emits a Word-native <w:br/>.
+  it('splits text around a single newline into text + lineBreak + text', () => {
+    const schema = makeRealSchema({ hasLineBreak: true });
+    const result = buildTextWithTabs(schema, 'Alpha\nBeta', undefined);
+    expect(result).toBeInstanceOf(Fragment);
+    const fragment = result as Fragment;
+    expect(fragment.childCount).toBe(3);
+    expect(fragment.child(0).text).toBe('Alpha');
+    expect(fragment.child(1).type.name).toBe('lineBreak');
+    expect(fragment.child(2).text).toBe('Beta');
+  });
+
+  it('emits a lineBreak node even when the schema has no tab node type', () => {
+    const schema = makeRealSchema({ hasLineBreak: true });
+    const result = buildTextWithTabs(schema, 'Alpha\nBeta', undefined) as Fragment;
+    expect(result).toBeInstanceOf(Fragment);
+    expect(result.childCount).toBe(3);
+    expect(result.child(1).type.name).toBe('lineBreak');
+  });
+
+  it('keeps the raw newline in a single text node when the schema has no lineBreak node type', () => {
+    const schema = makeRealSchema({ hasTab: true });
+    const result = buildTextWithTabs(schema, 'Alpha\nBeta', undefined);
+    expect((result as any).isText).toBe(true);
+    expect((result as any).text).toBe('Alpha\nBeta');
+  });
+
+  it('does not attach marks to the lineBreak node (its schema disallows marks)', () => {
+    const schema = makeRealSchema({ hasLineBreak: true });
+    const boldMark = schema.marks.bold.create();
+    const result = buildTextWithTabs(schema, 'Alpha\nBeta', [boldMark]) as Fragment;
+    expect(result.child(0).marks.some((m: any) => m.type.name === 'bold')).toBe(true);
+    expect(result.child(1).type.name).toBe('lineBreak');
+    expect(result.child(1).marks.length).toBe(0);
+    expect(result.child(2).marks.some((m: any) => m.type.name === 'bold')).toBe(true);
+  });
+
+  it('omits empty segments around leading, trailing, and consecutive newlines', () => {
+    const schema = makeRealSchema({ hasLineBreak: true });
+    const lead = buildTextWithTabs(schema, '\nfoo', undefined) as Fragment;
+    expect(lead.childCount).toBe(2);
+    expect(lead.child(0).type.name).toBe('lineBreak');
+    expect(lead.child(1).text).toBe('foo');
+
+    const doubled = buildTextWithTabs(schema, 'a\n\nb', undefined) as Fragment;
+    expect(doubled.childCount).toBe(4);
+    expect(doubled.child(0).text).toBe('a');
+    expect(doubled.child(1).type.name).toBe('lineBreak');
+    expect(doubled.child(2).type.name).toBe('lineBreak');
+    expect(doubled.child(3).text).toBe('b');
+  });
+
+  it('interleaves tab and lineBreak nodes when both control characters are present', () => {
+    const schema = makeRealSchema({ hasTab: true, hasLineBreak: true });
+    const result = buildTextWithTabs(schema, 'a\tb\nc', undefined) as Fragment;
+    expect(result.childCount).toBe(5);
+    expect(result.child(0).text).toBe('a');
+    expect(result.child(1).type.name).toBe('tab');
+    expect(result.child(2).text).toBe('b');
+    expect(result.child(3).type.name).toBe('lineBreak');
+    expect(result.child(4).text).toBe('c');
+  });
+
+  it('keeps the raw tab literal but still splits the newline when tabs are disallowed', () => {
+    const schema = makeRealSchema({ hasTab: true, hasLineBreak: true });
+    const result = buildTextWithTabs(schema, 'a\tb\nc', undefined, { parentAllowsTab: false }) as Fragment;
+    expect(result.childCount).toBe(3);
+    expect(result.child(0).text).toBe('a\tb');
+    expect(result.child(1).type.name).toBe('lineBreak');
+    expect(result.child(2).text).toBe('c');
+  });
+
+  // Finding 4: generated/SDK text often uses CRLF; normalize CRLF and bare CR to
+  // line breaks so no stray carriage return survives in a text segment.
+  it('normalizes CRLF to a lineBreak node', () => {
+    const schema = makeRealSchema({ hasLineBreak: true });
+    const result = buildTextWithTabs(schema, 'Alpha\r\nBeta', undefined) as Fragment;
+    expect(result.childCount).toBe(3);
+    expect(result.child(0).text).toBe('Alpha');
+    expect(result.child(1).type.name).toBe('lineBreak');
+    expect(result.child(2).text).toBe('Beta');
+  });
+
+  it('normalizes a bare CR to a lineBreak node without leaving a stray carriage return', () => {
+    const schema = makeRealSchema({ hasLineBreak: true });
+    const result = buildTextWithTabs(schema, 'Alpha\rBeta', undefined) as Fragment;
+    expect(result.childCount).toBe(3);
+    expect(result.child(0).text).toBe('Alpha');
+    expect(result.child(1).type.name).toBe('lineBreak');
+    expect(result.child(2).text).toBe('Beta');
+  });
+
+  // Finding 1: a `text*`-only parent (e.g. total-page-number) rejects lineBreak.
+  it('keeps the raw newline in a single text node when parentAllowsLineBreak is false', () => {
+    const schema = makeRealSchema({ hasLineBreak: true });
+    const result = buildTextWithTabs(schema, 'Alpha\nBeta', undefined, { parentAllowsLineBreak: false });
+    expect((result as any).isText).toBe(true);
+    expect((result as any).text).toBe('Alpha\nBeta');
+  });
 });
 
 describe('parentAllowsNodeAt', () => {