feat(parser): preserve soft line breaks as newlines in paragraphs

src/Node/Inline/SoftBreakNode.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpMarkdown\Node\Inline;
+
+use PhpMarkdown\Node\InlineNodeInterface;
+
+final readonly class SoftBreakNode implements InlineNodeInterface
+{
+}

src/Parser/Parser.php

@@ -25,7 +25,6 @@
 use PhpMarkdown\Node\Block\TableNode;
 use PhpMarkdown\Node\Block\TableRowNode;
 use PhpMarkdown\Node\Inline\HardBreakNode;
-use PhpMarkdown\Node\Inline\TextNode;
 use PhpMarkdown\Node\InlineNodeInterface;
 
 /**
@@ -215,16 +214,27 @@ private function buildParagraphChildren(array $tokens): array
     {
         $result = [];
         $lastIdx = count($tokens) - 1;
+        $group = [];
 
         foreach ($tokens as $idx => $token) {
-            $inlineNodes = $this->inlineParser->parse($token->content, $this->linkRefs, $this->footnoteDefs);
-            array_push($result, ...$inlineNodes);
-
-            if ($idx < $lastIdx) {
-                // Hard break on last token is stripped per CommonMark §6.7.
-                $result[] = ($token->meta['hard_break'] ?? false) === true
-                    ? new HardBreakNode()
-                    : new TextNode(' ');
+            $content = preg_replace('/^(?:[ ]{1,3}|\t)/', '', $token->content) ?? $token->content;
+            $isHardBreak = ($token->meta['hard_break'] ?? false) === true;
+            $isLast = ($idx === $lastIdx);
+
+            if (!$isLast && !$isHardBreak) {
+                $content = rtrim($content, ' ');
+            }
+
+            $group[] = $content;
+
+            if ($isHardBreak || $isLast) {
+                $nodes = $this->inlineParser->parse(implode("\n", $group), $this->linkRefs, $this->footnoteDefs);
+                array_push($result, ...$nodes);
+                $group = [];
+
+                if ($isHardBreak && !$isLast) {
+                    $result[] = new HardBreakNode();
+                }
             }
         }
 

src/Renderer/HtmlRenderer.php

@@ -26,6 +26,7 @@
 use PhpMarkdown\Node\Inline\EmphasisNode;
 use PhpMarkdown\Node\Inline\FootnoteRefNode;
 use PhpMarkdown\Node\Inline\HardBreakNode;
+use PhpMarkdown\Node\Inline\SoftBreakNode;
 use PhpMarkdown\Node\Inline\HtmlEntityNode;
 use PhpMarkdown\Node\Inline\ImageNode;
 use PhpMarkdown\Node\Inline\LinkNode;
@@ -76,6 +77,7 @@ private function renderNode(NodeInterface $node): string
                     ? $this->sanitizer->sanitize($node->content) . "\n"
                     : $this->esc($node->content) . "\n",
             $node instanceof HardBreakNode    => "<br />\n",
+            $node instanceof SoftBreakNode    => "\n",
             // HTML entities pass through verbatim — validated by InlineParser, no esc() needed.
             $node instanceof HtmlEntityNode   => $node->entity,
             $node instanceof TextNode         => $this->esc($node->text),

tests/Integration/MarkdownParserTest.php

@@ -493,9 +493,9 @@ public function testBackslashLineBreakProducesBr(): void
 
     public function testNoTrailingSpacesProducesSoftBreak(): void
     {
-        // Without trailing spaces the lines are soft-joined with a space.
+        // Without trailing spaces the lines are soft-joined with a newline (CommonMark §6.7).
         $html = $this->parser->parse("foo\nbar");
-        $this->assertSame("<p>foo bar</p>\n", $html);
+        $this->assertSame("<p>foo\nbar</p>\n", $html);
     }
 
     public function testHardBreakInsideInlineContent(): void
@@ -560,9 +560,9 @@ public function testBlockquoteLineWithTrailingSpacesNoHardBreak(): void
 
     public function testSoftBreakBetweenParagraphLinesUnchanged(): void
     {
-        // Pre-existing soft-break behavior must not regress.
+        // Soft-break renders as newline per CommonMark §6.7.
         $html = $this->parser->parse("line one\nline two\nline three");
-        $this->assertSame("<p>line one line two line three</p>\n", $html);
+        $this->assertSame("<p>line one\nline two\nline three</p>\n", $html);
     }
 
     public function testBlankLineSeparatesParagraphs(): void

tests/Integration/fixtures/hard-line-breaks.html

@@ -2,7 +2,8 @@
 bar</p>
 <p>foo<br />
 bar</p>
-<p>foo bar</p>
+<p>foo
+bar</p>
 <p><strong>bold</strong><br />
 text</p>
 <p>a<br />

tests/Unit/Renderer/SoftLineBreakTest.php

@@ -0,0 +1,91 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpMarkdown\Tests\Unit\Renderer;
+
+use PhpMarkdown\MarkdownParser;
+use PhpMarkdown\Node\Block\DocumentNode;
+use PhpMarkdown\Node\Block\ParagraphNode;
+use PhpMarkdown\Node\Inline\SoftBreakNode;
+use PhpMarkdown\Renderer\HtmlRenderer;
+use PHPUnit\Framework\TestCase;
+
+final class SoftLineBreakTest extends TestCase
+{
+    private MarkdownParser $parser;
+
+    protected function setUp(): void
+    {
+        $this->parser = new MarkdownParser();
+    }
+
+    private function parseAndRender(string $markdown): string
+    {
+        return $this->parser->parse($markdown);
+    }
+
+    public function testSingleNewlineInParagraphPreservedAsSoftBreak(): void
+    {
+        $this->assertSame("<p>foo\nbaz</p>\n", $this->parseAndRender("foo\nbaz"));
+    }
+
+    public function testTrailingSpacesBeforeNewlineStrippedNotHardBreak(): void
+    {
+        $this->assertSame("<p>foo<br />\nbaz</p>\n", $this->parseAndRender("foo   \nbaz"));
+    }
+
+    public function testSingleTrailingSpaceBeforeNewlineIsSoftBreak(): void
+    {
+        $this->assertSame("<p>foo\nbaz</p>\n", $this->parseAndRender("foo \nbaz"));
+    }
+
+    public function testTwoLineParagraphPreservesInternalNewline(): void
+    {
+        $this->assertSame("<p>aaa\nbbb</p>\n<p>ccc\nddd</p>\n", $this->parseAndRender("aaa\nbbb\n\nccc\nddd"));
+    }
+
+    public function testLeadingSpacesOnFirstLineStripped(): void
+    {
+        $this->assertSame("<p>aaa\nbbb</p>\n", $this->parseAndRender("  aaa\nbbb"));
+    }
+
+    public function testLeadingSpacesOnContinuationLineStripped(): void
+    {
+        $this->assertSame("<p>aaa\nbbb</p>\n", $this->parseAndRender("  aaa\n bbb"));
+    }
+
+    public function testEmphasisSpanningSoftLineBreak(): void
+    {
+        $this->assertSame("<p><em>foo\nbar</em></p>\n", $this->parseAndRender("*foo\nbar*"));
+    }
+
+    public function testStrongEmphasisSpanningSoftLineBreak(): void
+    {
+        $this->assertSame("<p><strong>foo\nbar</strong></p>\n", $this->parseAndRender("**foo\nbar**"));
+    }
+
+    public function testTabBeforeContinuationTextStripped(): void
+    {
+        $this->assertSame("<p>foo\nbaz</p>\n", $this->parseAndRender("foo\n\tbaz"));
+    }
+
+    public function testSoftBreakNodeRendersAsNewlineNotSpace(): void
+    {
+        $renderer = new HtmlRenderer();
+        $document = new DocumentNode([
+            new ParagraphNode([new SoftBreakNode()]),
+        ]);
+        $this->assertSame("<p>\n</p>\n", $renderer->render($document));
+    }
+
+    public function testHardBreakWithTwoTrailingSpacesUnaffectedBySoftBreak(): void
+    {
+        $this->assertSame("<p>foo<br />\nbar</p>\n", $this->parseAndRender("foo  \nbar"));
+    }
+
+    public function testNoBreakNodeInsertedInSingleLineParagraph(): void
+    {
+        $this->assertSame("<p>foo bar</p>\n", $this->parseAndRender("foo bar"));
+    }
+}