fix: ensure headers always start on new lines

- Add ensureBlockStart() helper to check accumulated output
- Call before rendering block elements (HEADING, PARAGRAPH, CODE_BLOCK, LIST, BLOCKQUOTE, RULE)
- Add test case TestPerformMarkdownTaskHeadersOnNewlines
- Add HTML fixture reproducing inline-to-block transition edge case
- Verify no headers appear immediately after non-newline characters

Fixes #4

Author: mjc-gh

engine/js/markdown.js

@@ -303,6 +303,32 @@
         return result.replace(/\n{3,}/g, '\n\n').trim();
     }
 
+    /**
+     * Ensures a block-level element starts on a new line
+     * Block elements should be preceded by at least one newline character.
+     * If the last character in the output buffer is not a newline, add newlines.
+     * @param {Array} lines - Accumulator for output lines
+     */
+    function ensureBlockStart(lines) {
+        if (lines.length === 0) return;
+        
+        // Join all lines to get the current output
+        const output = lines.join('');
+        
+        // If output is empty or already ends with newline, no need to add more
+        if (output.length === 0 || output.endsWith('\n\n')) {
+            return;
+        }
+        
+        // If output ends with one newline, add one more for proper spacing
+        if (output.endsWith('\n')) {
+            lines.push('\n');
+        } else {
+            // If output doesn't end with newline, add two newlines
+            lines.push('\n\n');
+        }
+    }
+
     /**
      * Renders a single AST node
      * @param {Object} node - The AST node to render
@@ -317,12 +343,14 @@
                 break;
 
             case NodeType.HEADING:
+                ensureBlockStart(lines);
                 const hashes = '#'.repeat(node.attrs.level);
                 const headingText = renderInlineChildren(node.children);
                 lines.push(hashes + ' ' + headingText + '\n\n');
                 break;
 
             case NodeType.PARAGRAPH:
+                ensureBlockStart(lines);
                 const paraText = renderInlineChildren(node.children);
                 if (paraText.trim().length > 0) {
                     lines.push(paraText + '\n\n');
@@ -379,11 +407,13 @@
                 break;
 
             case NodeType.CODE_BLOCK:
+                ensureBlockStart(lines);
                 const lang = node.attrs.lang || '';
                 lines.push('```' + lang + '\n' + node.content + '\n```\n\n');
                 break;
 
             case NodeType.LIST:
+                ensureBlockStart(lines);
                 renderList(node, lines);
                 break;
 
@@ -392,6 +422,7 @@
                 break;
 
             case NodeType.BLOCKQUOTE:
+                ensureBlockStart(lines);
                 const quoteLines = [];
                 renderChildren(node.children, quoteLines);
                 const quoteText = quoteLines.join('').trim();
@@ -411,6 +442,7 @@
                 break;
 
             case NodeType.RULE:
+                ensureBlockStart(lines);
                 lines.push('---\n\n');
                 break;
         }

engine/task_markdown_test.go

@@ -201,3 +201,26 @@ func TestPerformMarkdownTaskBlockquoteWithNestedContent(t *testing.T) {
 	assert.Contains(t, mr.Content, "> ")
 	assert.Contains(t, mr.Content, "Quote with")
 }
+
+func TestPerformMarkdownTaskHeadersOnNewlines(t *testing.T) {
+	// Test that headers are always preceded by a newline (except at start)
+	// This tests that inline content followed by a header has proper separation
+	server := pagetest.NewTestWebServer("markdown")
+	task := NewTask("markdown", server.URL)
+
+	ctx, cancel := pagetest.NewTestContext()
+	defer cancel()
+
+	mr, err := performMarkdownTask(ctx, &task, virgo.Logger())
+
+	require.NoError(t, err)
+	assert.NotEmpty(t, mr.Content)
+
+	// Headers must always be preceded by a newline (except at start)
+	// This tests that inline content followed by a header has proper separation
+	assert.Contains(t, mr.Content, "text before heading\n\n# Inline to Block Test")
+
+	// Verify no headers appear immediately after inline content (single newline is not enough)
+	// Headers should have double newlines before them
+	assert.NotRegexp(t, `[^\n]\n#+ `, mr.Content)
+}

internal/pagetest/testdata/markdown/index.html

@@ -103,6 +103,14 @@ <h3>Complex Blockquote</h3>
                 <li>List in quote</li>
             </ul>
         </blockquote>
+
+        <!-- Inline content immediately before block element -->
+        <h3>Inline to Block Transition</h3>
+        <div>
+            <span>text before heading</span>
+            <h1>Inline to Block Test</h1>
+            <p>This paragraph follows the heading.</p>
+        </div>
     </main>
 
     <footer>