testomatio-editor-blocks 0.4.51 → 0.4.52

package/package/editor/blocks/step.js

@@ -400,7 +400,7 @@ export const stepBlock = createReactBlockSpec({
             writeExpectedCollapsedPreference(true);
             editor.updateBlock(block.id, { props: { expectedResult: "" } });
         }, [editor, block.id]);
-        const viewToggleButton = (_jsx("button", { type: "button", className: `bn-teststep__view-toggle${!effectiveVertical ? " bn-teststep__view-toggle--horizontal" : ""}${forceVertical ? " bn-teststep__view-toggle--disabled" : ""}`, "data-tooltip": forceVertical ? "Not enough space for horizontal view" : "Switch step view", "aria-label": forceVertical ? "Not enough space for horizontal view" : "Switch step view", onClick: forceVertical ? undefined : handleToggleView, "aria-disabled": forceVertical, children: _jsxs("svg", { width: "16", height: "16", viewBox: "0 0 16 16", fill: "none", "aria-hidden": "true", children: [_jsx("mask", { id: "mask-toggle", style: { maskType: "alpha" }, maskUnits: "userSpaceOnUse", x: "0", y: "0", width: "16", height: "16", children: _jsx("rect", { width: "16", height: "16", fill: "#D9D9D9" }) }), _jsx("g", { mask: "url(#mask-toggle)", children: _jsx("path", { d: "M12.6667 2C13.0333 2 13.3472 2.13056 13.6083 2.39167C13.8694 2.65278 14 2.96667 14 3.33333L14 12.6667C14 13.0333 13.8694 13.3472 13.6083 13.6083C13.3472 13.8694 13.0333 14 12.6667 14L10 14C9.63333 14 9.31944 13.8694 9.05833 13.6083C8.79722 13.3472 8.66667 13.0333 8.66667 12.6667L8.66667 3.33333C8.66667 2.96667 8.79722 2.65278 9.05833 2.39167C9.31945 2.13055 9.63333 2 10 2L12.6667 2ZM6 2C6.36667 2 6.68056 2.13055 6.94167 2.39167C7.20278 2.65278 7.33333 2.96667 7.33333 3.33333L7.33333 12.6667C7.33333 13.0333 7.20278 13.3472 6.94167 13.6083C6.68055 13.8694 6.36667 14 6 14L3.33333 14C2.96667 14 2.65278 13.8694 2.39167 13.6083C2.13056 13.3472 2 13.0333 2 12.6667L2 3.33333C2 2.96667 2.13056 2.65278 2.39167 2.39167C2.65278 2.13055 2.96667 2 3.33333 2L6 2ZM3.33333 12.6667L6 12.6667L6 3.33333L3.33333 3.33333L3.33333 12.6667Z", fill: "currentColor" }) })] }) }));
+        const viewToggleButton = (_jsx("button", { type: "button", className: `bn-teststep__view-toggle${!effectiveVertical ? " bn-teststep__view-toggle--horizontal" : ""}${forceVertical ? " bn-teststep__view-toggle--disabled" : ""}`, "data-tooltip": forceVertical ? "Not enough space for horizontal view" : "Switch step view", "aria-label": forceVertical ? "Not enough space for horizontal view" : "Switch step view", onClick: forceVertical ? undefined : handleToggleView, "aria-disabled": forceVertical, tabIndex: -1, children: _jsxs("svg", { width: "16", height: "16", viewBox: "0 0 16 16", fill: "none", "aria-hidden": "true", children: [_jsx("mask", { id: "mask-toggle", style: { maskType: "alpha" }, maskUnits: "userSpaceOnUse", x: "0", y: "0", width: "16", height: "16", children: _jsx("rect", { width: "16", height: "16", fill: "#D9D9D9" }) }), _jsx("g", { mask: "url(#mask-toggle)", children: _jsx("path", { d: "M12.6667 2C13.0333 2 13.3472 2.13056 13.6083 2.39167C13.8694 2.65278 14 2.96667 14 3.33333L14 12.6667C14 13.0333 13.8694 13.3472 13.6083 13.6083C13.3472 13.8694 13.0333 14 12.6667 14L10 14C9.63333 14 9.31944 13.8694 9.05833 13.6083C8.79722 13.3472 8.66667 13.0333 8.66667 12.6667L8.66667 3.33333C8.66667 2.96667 8.79722 2.65278 9.05833 2.39167C9.31945 2.13055 9.63333 2 10 2L12.6667 2ZM6 2C6.36667 2 6.68056 2.13055 6.94167 2.39167C7.20278 2.65278 7.33333 2.96667 7.33333 3.33333L7.33333 12.6667C7.33333 13.0333 7.20278 13.3472 6.94167 13.6083C6.68055 13.8694 6.36667 14 6 14L3.33333 14C2.96667 14 2.65278 13.8694 2.39167 13.6083C2.13056 13.3472 2 13.0333 2 12.6667L2 3.33333C2 2.96667 2.13056 2.65278 2.39167 2.39167C2.65278 2.13055 2.96667 2 3.33333 2L6 2ZM3.33333 12.6667L6 12.6667L6 3.33333L3.33333 3.33333L3.33333 12.6667Z", fill: "currentColor" }) })] }) }));
         if (!effectiveVertical) {
             return (_jsx(StepHorizontalView, { ref: containerRef, blockId: block.id, stepNumber: stepNumber, stepValue: combinedStepValue, expectedResult: expectedResult, onStepChange: handleCombinedStepChange, onExpectedChange: handleExpectedChange, onInsertNextStep: handleInsertNextStep, onFieldFocus: handleFieldFocus, viewToggle: viewToggleButton }));
         }

package/package/editor/customMarkdownConverter.d.ts

@@ -6,8 +6,7 @@ export type CustomPartialBlock = PartialBlock<Schema["blockSchema"], Schema["inl
 export declare function blocksToMarkdown(blocks: CustomEditorBlock[]): string;
 export declare function fixMalformedImageBlocks(blocks: CustomPartialBlock[]): CustomPartialBlock[];
 export interface MarkdownToBlocksOptions {
-    /** When true, every blank line produces an empty paragraph block. */
     preserveBlankLines?: boolean;
 }
-export declare function markdownToBlocks(markdown: string, options?: MarkdownToBlocksOptions): CustomPartialBlock[];
+export declare function markdownToBlocks(markdown: string, _options?: MarkdownToBlocksOptions): CustomPartialBlock[];
 export {};

package/package/editor/customMarkdownConverter.js

@@ -23,6 +23,7 @@ const headingPrefixes = {
     6: "######",
 };
 const SPECIAL_CHAR_REGEX = /([*_`~\[\]()<\\])/g;
+const HTML_COMMENT_REGEX = /<!--[\s\S]*?-->/g;
 const HTML_SPAN_REGEX = /<\/?span[^>]*>/g;
 const HTML_UNDERLINE_REGEX = /<\/?u>/g;
 const EXPECTED_LABEL_REGEX = /^(?:[*_`]*\s*)?(expected(?:\s+result)?)\s*(?:[*_`]*\s*)?\s*[:\-–—]\s*/i;
@@ -30,7 +31,17 @@ const EXPECTED_LABEL_REGEX = /^(?:[*_`]*\s*)?(expected(?:\s+result)?)\s*(?:[*_`]
 const STEP_DATA_LINE_REGEX = /^(?!\s*(?:[*_`]*\s*)?(?:expected(?:\s+result)?)\b).+/i;
 const NUMBERED_STEP_REGEX = /^\d+[.)]\s+/;
 function escapeMarkdown(text) {
-    return text.replace(SPECIAL_CHAR_REGEX, "\\$1");
+    let result = "";
+    let lastIndex = 0;
+    HTML_COMMENT_REGEX.lastIndex = 0;
+    let match;
+    while ((match = HTML_COMMENT_REGEX.exec(text)) !== null) {
+        result += text.slice(lastIndex, match.index).replace(SPECIAL_CHAR_REGEX, "\\$1");
+        result += match[0];
+        lastIndex = match.index + match[0].length;
+    }
+    result += text.slice(lastIndex).replace(SPECIAL_CHAR_REGEX, "\\$1");
+    return result;
 }
 function stripHtmlWrappers(text) {
     return text
@@ -206,12 +217,6 @@ function serializeChildren(block, ctx) {
     const childCtx = { ...ctx, listDepth: ctx.listDepth + 1 };
     return serializeBlocks(block.children, childCtx);
 }
-function flattenWithBlankLine(lines, appendBlank = false) {
-    if (appendBlank && (lines.length === 0 || lines.at(-1) !== "")) {
-        return [...lines, ""];
-    }
-    return lines;
-}
 function serializeBlock(block, ctx, orderedIndex, stepIndex) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
     const lines = [];
@@ -219,17 +224,21 @@ function serializeBlock(block, ctx, orderedIndex, stepIndex) {
     switch (block.type) {
         case "paragraph": {
             const text = inlineToMarkdown(block.content);
-            if (text.length > 0) {
-                lines.push(ctx.insideQuote ? `> ${text}` : text);
+            if (text.length === 0) {
+                // Empty paragraph = one blank line in the output. Under the 1:1
+                // block model, this is the only mechanism that produces blank lines
+                // between top-level blocks.
+                return [""];
             }
-            return flattenWithBlankLine(lines, !ctx.insideQuote);
+            lines.push(ctx.insideQuote ? `> ${text}` : text);
+            return lines;
         }
         case "heading": {
             const level = (_a = block.props.level) !== null && _a !== void 0 ? _a : 1;
             const prefix = (_b = headingPrefixes[level]) !== null && _b !== void 0 ? _b : headingPrefixes[3];
             const text = inlineToMarkdown(block.content);
             lines.push(`${prefix} ${text}`.trimEnd());
-            return flattenWithBlankLine(lines, true);
+            return lines;
         }
         case "quote": {
             const quoteContent = serializeBlocks((_c = block.children) !== null && _c !== void 0 ? _c : [], {
@@ -244,7 +253,7 @@ function serializeBlock(block, ctx, orderedIndex, stepIndex) {
                 lines.push(...quoteText);
             }
             lines.push(...quoteContent.map((line) => (line ? `> ${line}` : ">")));
-            return flattenWithBlankLine(lines, true);
+            return lines;
         }
         case "codeBlock": {
             const language = block.props.language || "";
@@ -255,7 +264,7 @@ function serializeBlock(block, ctx, orderedIndex, stepIndex) {
                 lines.push(body);
             }
             lines.push("```");
-            return flattenWithBlankLine(lines, true);
+            return lines;
         }
         case "bulletListItem": {
             const text = inlineToMarkdown(block.content);
@@ -287,7 +296,7 @@ function serializeBlock(block, ctx, orderedIndex, stepIndex) {
                 const size = width ? ` =${width}x*` : "";
                 lines.push(`![${caption}](${url}${size})`);
             }
-            return flattenWithBlankLine(lines, true);
+            return lines;
         }
         case "file":
         case "video":
@@ -299,7 +308,7 @@ function serializeBlock(block, ctx, orderedIndex, stepIndex) {
                 const displayUrl = caption || resolveFileDisplayUrl(url);
                 lines.push(`[![${name}](${displayUrl})](${url})`);
             }
-            return flattenWithBlankLine(lines, true);
+            return lines;
         }
         case "testStep":
         case "snippet": {
@@ -327,7 +336,7 @@ function serializeBlock(block, ctx, orderedIndex, stepIndex) {
                 if (snippetId) {
                     lines.push(`<!-- end snippet #${snippetId} -->`);
                 }
-                return flattenWithBlankLine(lines, true);
+                return lines;
             }
             const normalizedTitle = stepTitle
                 .split(/\r?\n/)
@@ -370,28 +379,25 @@ function serializeBlock(block, ctx, orderedIndex, stepIndex) {
                     }
                 });
             }
-            if (lines.length === 0) {
-                return lines;
-            }
-            return flattenWithBlankLine(lines, false);
+            return lines;
         }
         case "table": {
             const tableContent = block.content;
             if (!tableContent || tableContent.type !== "tableContent") {
-                return flattenWithBlankLine(lines, true);
+                return lines;
             }
             const rows = Array.isArray(tableContent.rows)
                 ? tableContent.rows
                 : [];
             if (rows.length === 0) {
-                return flattenWithBlankLine(lines, true);
+                return lines;
             }
             const columnCount = rows.reduce((max, row) => {
                 const length = Array.isArray(row.cells) ? row.cells.length : 0;
                 return Math.max(max, length);
             }, 0);
             if (columnCount === 0) {
-                return flattenWithBlankLine(lines, true);
+                return lines;
             }
             const headerRowCount = rows.length
                 ? Math.min(rows.length, Math.max((_o = tableContent.headerRows) !== null && _o !== void 0 ? _o : 1, 1))
@@ -468,7 +474,7 @@ function serializeBlock(block, ctx, orderedIndex, stepIndex) {
             formattedRows.slice(bodyStartIndex).forEach((row) => {
                 lines.push(`| ${row.map((cell) => formatCell(cell)).join(" | ")} |`);
             });
-            return flattenWithBlankLine(lines, true);
+            return lines;
         }
     }
     const fallbackBlock = block;
@@ -479,7 +485,7 @@ function serializeBlock(block, ctx, orderedIndex, stepIndex) {
         }
     }
     lines.push(...serializeChildren(fallbackBlock, ctx));
-    return flattenWithBlankLine(lines, false);
+    return lines;
 }
 function serializeBlocks(blocks, ctx) {
     const lines = [];
@@ -1172,8 +1178,8 @@ export function fixMalformedImageBlocks(blocks) {
     }
     return result;
 }
-export function markdownToBlocks(markdown, options) {
-    var _a, _b, _c;
+export function markdownToBlocks(markdown, _options) {
+    var _a, _b;
     const normalized = markdown.replace(/\r\n/g, "\n");
     const lines = normalized.split("\n");
     const blocks = [];
@@ -1182,22 +1188,12 @@ export function markdownToBlocks(markdown, options) {
     while (index < lines.length) {
         const line = lines[index];
         if (!line.trim()) {
-            if (options === null || options === void 0 ? void 0 : options.preserveBlankLines) {
+            // Drop blank lines until we've emitted at least one block, so leading
+            // blanks don't produce a ghost empty paragraph at the top of the doc.
+            if (blocks.length > 0) {
                 blocks.push({ type: "paragraph", content: [], children: [] });
-                index += 1;
-                continue;
             }
             index += 1;
-            // Count consecutive blank lines
-            let blankCount = 1;
-            while (index < lines.length && !lines[index].trim()) {
-                blankCount++;
-                index++;
-            }
-            // Create empty paragraph for each extra blank line beyond the first
-            for (let i = 1; i < blankCount; i++) {
-                blocks.push({ type: "paragraph", content: [], children: [] });
-            }
             continue;
         }
         const snippetWrapper = stepsHeadingLevel !== null
@@ -1293,15 +1289,15 @@ export function markdownToBlocks(markdown, options) {
         blocks.push(paragraph.block);
         index = paragraph.nextIndex;
     }
-    // Insert empty paragraphs between consecutive headings so users can type between them
-    const result = [];
-    for (let i = 0; i < blocks.length; i++) {
-        result.push(blocks[i]);
-        if (blocks[i].type === "heading" && ((_c = blocks[i + 1]) === null || _c === void 0 ? void 0 : _c.type) === "heading") {
-            result.push({ type: "paragraph", content: [], children: [] });
-        }
+    // Drop trailing empty paragraphs so a trailing blank line in the source
+    // doesn't leave a ghost empty block at the end of the document.
+    while (blocks.length > 0 &&
+        blocks[blocks.length - 1].type === "paragraph" &&
+        (!blocks[blocks.length - 1].content ||
+            blocks[blocks.length - 1].content.length === 0)) {
+        blocks.pop();
     }
-    return fixMalformedImageBlocks(result);
+    return fixMalformedImageBlocks(blocks);
 }
 function splitTableRow(line) {
     let value = line.trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testomatio-editor-blocks",
-  "version": "0.4.51",
+  "version": "0.4.52",
   "description": "Custom BlockNote schema, markdown conversion helpers, and UI for Testomatio-style test cases and steps.",
   "type": "module",
   "main": "./package/index.js",

package/src/App.tsx

@@ -11,6 +11,7 @@ import {
   filterSuggestionItems,
   insertOrUpdateBlock,
 } from "@blocknote/core";
+import { autoPlacement, offset, shift, size } from "@floating-ui/react";
 import {
   blocksToMarkdown,
   markdownToBlocks,
@@ -354,7 +355,28 @@ function CustomSlashMenu() {
     return filterSuggestionItems(items, query);
   };
 
-  return <SuggestionMenuController triggerCharacter="/" getItems={getItems} />;
+  return (
+    <SuggestionMenuController
+      triggerCharacter="/"
+      getItems={getItems}
+      floatingOptions={{
+        middleware: [
+          offset(10),
+          autoPlacement({
+            allowedPlacements: ["bottom-start", "top-start"],
+          }),
+          shift(),
+          size({
+            apply({ availableHeight, elements }) {
+              Object.assign(elements.floating.style, {
+                maxHeight: `${Math.max(availableHeight - 10, 0)}px`,
+              });
+            },
+          }),
+        ],
+      }}
+    />
+  );
 }
 
 function App() {

package/src/editor/blocks/step.tsx

@@ -463,6 +463,7 @@ export const stepBlock = createReactBlockSpec(
           aria-label={forceVertical ? "Not enough space for horizontal view" : "Switch step view"}
           onClick={forceVertical ? undefined : handleToggleView}
           aria-disabled={forceVertical}
+          tabIndex={-1}
         >
           <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
             <mask id="mask-toggle" style={{maskType: "alpha"}} maskUnits="userSpaceOnUse" x="0" y="0" width="16" height="16">

package/src/editor/customMarkdownConverter.test.ts

@@ -46,6 +46,38 @@ describe("blocksToMarkdown", () => {
     expect(blocksToMarkdown(blocks)).toBe("Hello **world**_!_");
   });
 
+  it("preserves HTML comments without escaping", () => {
+    const blocks: CustomEditorBlock[] = [
+      {
+        id: "c1",
+        type: "paragraph",
+        props: baseProps,
+        content: [
+          { type: "text", text: "<!-- ai/agent generated description -->", styles: {} },
+        ],
+        children: [],
+      },
+    ];
+
+    expect(blocksToMarkdown(blocks)).toBe("<!-- ai/agent generated description -->");
+  });
+
+  it("preserves HTML comments inline among text and still escapes stray angle brackets", () => {
+    const blocks: CustomEditorBlock[] = [
+      {
+        id: "c2",
+        type: "paragraph",
+        props: baseProps,
+        content: [
+          { type: "text", text: "before <!-- note --> after <div>", styles: {} },
+        ],
+        children: [],
+      },
+    ];
+
+    expect(blocksToMarkdown(blocks)).toBe("before <!-- note --> after \\<div>");
+  });
+
   it("places bold markers outside leading/trailing spaces", () => {
     const blocks: CustomEditorBlock[] = [
       {
@@ -1082,6 +1114,11 @@ describe("markdownToBlocks", () => {
         content: [{ type: "text", text: "Preconditions", styles: {} }],
         children: [],
       },
+      {
+        type: "paragraph",
+        content: [],
+        children: [],
+      },
       {
         type: "bulletListItem",
         props: baseProps,
@@ -2525,3 +2562,121 @@ describe("steps require Steps heading", () => {
     expect((stepBlocks[0].props as any).stepTitle).toBe("next 22");
   });
 });
+
+describe("blank line <-> empty paragraph mapping", () => {
+  const isEmptyParagraph = (block: CustomPartialBlock | CustomEditorBlock) =>
+    block.type === "paragraph" &&
+    (!block.content || (block.content as any[]).length === 0);
+
+  it("parses a single blank line between headings as one empty paragraph", () => {
+    const blocks = markdownToBlocks("### A\n\n### B");
+    expect(blocks).toHaveLength(3);
+    expect(blocks[0].type).toBe("heading");
+    expect(isEmptyParagraph(blocks[1])).toBe(true);
+    expect(blocks[2].type).toBe("heading");
+  });
+
+  it("parses two blank lines between headings as two empty paragraphs", () => {
+    const blocks = markdownToBlocks("### A\n\n\n### B");
+    expect(blocks).toHaveLength(4);
+    expect(blocks[0].type).toBe("heading");
+    expect(isEmptyParagraph(blocks[1])).toBe(true);
+    expect(isEmptyParagraph(blocks[2])).toBe(true);
+    expect(blocks[3].type).toBe("heading");
+  });
+
+  it("drops leading and trailing blank lines", () => {
+    const blocks = markdownToBlocks("\n\n### A\n\n");
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0].type).toBe("heading");
+  });
+
+  it("serializes an empty paragraph between two blocks as one blank line", () => {
+    const blocks: CustomEditorBlock[] = [
+      {
+        id: "h1",
+        type: "heading",
+        props: { ...baseProps, level: 3 } as any,
+        content: [{ type: "text", text: "A", styles: {} }],
+        children: [],
+      },
+      {
+        id: "p1",
+        type: "paragraph",
+        props: baseProps,
+        content: [],
+        children: [],
+      },
+      {
+        id: "h2",
+        type: "heading",
+        props: { ...baseProps, level: 3 } as any,
+        content: [{ type: "text", text: "B", styles: {} }],
+        children: [],
+      },
+    ];
+    expect(blocksToMarkdown(blocks)).toBe("### A\n\n### B");
+  });
+
+  it("round-trips a single blank line between headings", () => {
+    const markdown = "### A\n\n### B";
+    const blocks = markdownToBlocks(markdown);
+    expect(blocksToMarkdown(blocks as CustomEditorBlock[])).toBe(markdown);
+  });
+
+  it("round-trips two blank lines between headings", () => {
+    const markdown = "### A\n\n\n### B";
+    const blocks = markdownToBlocks(markdown);
+    expect(blocksToMarkdown(blocks as CustomEditorBlock[])).toBe(markdown);
+  });
+
+  it("round-trips headings adjacent with no blank line", () => {
+    const markdown = "### A\n### B";
+    const blocks = markdownToBlocks(markdown);
+    expect(blocks.some(isEmptyParagraph)).toBe(false);
+    expect(blocksToMarkdown(blocks as CustomEditorBlock[])).toBe(markdown);
+  });
+
+  it("deleting an empty paragraph removes the blank line from the output", () => {
+    const blocks = markdownToBlocks("### A\n\n### B") as CustomEditorBlock[];
+    const withoutEmpty = blocks.filter((block) => !isEmptyParagraph(block));
+    expect(withoutEmpty).toHaveLength(2);
+    expect(blocksToMarkdown(withoutEmpty)).toBe("### A\n### B");
+  });
+
+  it("inserting an empty paragraph adds a blank line to the output", () => {
+    const blocks = markdownToBlocks("### A\n### B") as CustomEditorBlock[];
+    const withEmpty: CustomEditorBlock[] = [
+      blocks[0],
+      {
+        id: "inserted",
+        type: "paragraph",
+        props: baseProps,
+        content: [],
+        children: [],
+      },
+      blocks[1],
+    ];
+    expect(blocksToMarkdown(withEmpty)).toBe("### A\n\n### B");
+  });
+
+  it("preserves blank lines between a heading and a bullet list", () => {
+    const markdown = "### Steps\n\n* first\n* second";
+    const blocks = markdownToBlocks(markdown);
+    expect(isEmptyParagraph(blocks[1])).toBe(true);
+    expect(blocksToMarkdown(blocks as CustomEditorBlock[])).toBe(markdown);
+  });
+
+  it("preserves blank lines across the user-reported screenshot example", () => {
+    const markdown = [
+      "### Requirements",
+      "",
+      "### Steps",
+      "",
+      "* *open* **webiste**",
+      "  step data with `image`",
+    ].join("\n");
+    const blocks = markdownToBlocks(markdown);
+    expect(blocksToMarkdown(blocks as CustomEditorBlock[])).toBe(markdown);
+  });
+});

package/src/editor/customMarkdownConverter.ts

@@ -61,6 +61,7 @@ const headingPrefixes: Record<number, string> = {
 };
 
 const SPECIAL_CHAR_REGEX = /([*_`~\[\]()<\\])/g;
+const HTML_COMMENT_REGEX = /<!--[\s\S]*?-->/g;
 const HTML_SPAN_REGEX = /<\/?span[^>]*>/g;
 const HTML_UNDERLINE_REGEX = /<\/?u>/g;
 const EXPECTED_LABEL_REGEX = /^(?:[*_`]*\s*)?(expected(?:\s+result)?)\s*(?:[*_`]*\s*)?\s*[:\-–—]\s*/i;
@@ -70,7 +71,17 @@ const STEP_DATA_LINE_REGEX =
 const NUMBERED_STEP_REGEX = /^\d+[.)]\s+/;
 
 function escapeMarkdown(text: string): string {
-  return text.replace(SPECIAL_CHAR_REGEX, "\\$1");
+  let result = "";
+  let lastIndex = 0;
+  HTML_COMMENT_REGEX.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = HTML_COMMENT_REGEX.exec(text)) !== null) {
+    result += text.slice(lastIndex, match.index).replace(SPECIAL_CHAR_REGEX, "\\$1");
+    result += match[0];
+    lastIndex = match.index + match[0].length;
+  }
+  result += text.slice(lastIndex).replace(SPECIAL_CHAR_REGEX, "\\$1");
+  return result;
 }
 
 function stripHtmlWrappers(text: string): string {
@@ -273,13 +284,6 @@ function serializeChildren(block: CustomEditorBlock, ctx: MarkdownContext): stri
   return serializeBlocks(block.children, childCtx);
 }
 
-function flattenWithBlankLine(lines: string[], appendBlank = false): string[] {
-  if (appendBlank && (lines.length === 0 || lines.at(-1) !== "")) {
-    return [...lines, ""];
-  }
-  return lines;
-}
-
 function serializeBlock(
   block: CustomEditorBlock,
   ctx: MarkdownContext,
@@ -292,17 +296,21 @@ function serializeBlock(
   switch (block.type) {
     case "paragraph": {
       const text = inlineToMarkdown(block.content);
-      if (text.length > 0) {
-        lines.push(ctx.insideQuote ? `> ${text}` : text);
+      if (text.length === 0) {
+        // Empty paragraph = one blank line in the output. Under the 1:1
+        // block model, this is the only mechanism that produces blank lines
+        // between top-level blocks.
+        return [""];
       }
-      return flattenWithBlankLine(lines, !ctx.insideQuote);
+      lines.push(ctx.insideQuote ? `> ${text}` : text);
+      return lines;
     }
     case "heading": {
       const level = (block.props as any).level ?? 1;
       const prefix = headingPrefixes[level] ?? headingPrefixes[3];
       const text = inlineToMarkdown(block.content);
       lines.push(`${prefix} ${text}`.trimEnd());
-      return flattenWithBlankLine(lines, true);
+      return lines;
     }
     case "quote": {
       const quoteContent = serializeBlocks(block.children ?? [], {
@@ -317,7 +325,7 @@ function serializeBlock(
         lines.push(...quoteText);
       }
       lines.push(...quoteContent.map((line) => (line ? `> ${line}` : ">")));
-      return flattenWithBlankLine(lines, true);
+      return lines;
     }
     case "codeBlock": {
       const language = (block.props as any).language || "";
@@ -328,7 +336,7 @@ function serializeBlock(
         lines.push(body);
       }
       lines.push("```");
-      return flattenWithBlankLine(lines, true);
+      return lines;
     }
     case "bulletListItem": {
       const text = inlineToMarkdown(block.content);
@@ -361,7 +369,7 @@ function serializeBlock(
         const size = width ? ` =${width}x*` : "";
         lines.push(`![${caption}](${url}${size})`);
       }
-      return flattenWithBlankLine(lines, true);
+      return lines;
     }
     case "file":
     case "video":
@@ -373,7 +381,7 @@ function serializeBlock(
         const displayUrl = caption || resolveFileDisplayUrl(url);
         lines.push(`[![${name}](${displayUrl})](${url})`);
       }
-      return flattenWithBlankLine(lines, true);
+      return lines;
     }
     case "testStep":
     case "snippet": {
@@ -405,7 +413,7 @@ function serializeBlock(
           lines.push(`<!-- end snippet #${snippetId} -->`);
         }
 
-        return flattenWithBlankLine(lines, true);
+        return lines;
       }
 
       const normalizedTitle = stepTitle
@@ -453,16 +461,12 @@ function serializeBlock(
         });
       }
 
-      if (lines.length === 0) {
-        return lines;
-      }
-
-      return flattenWithBlankLine(lines, false);
+      return lines;
     }
     case "table": {
       const tableContent = block.content as any;
       if (!tableContent || tableContent.type !== "tableContent") {
-        return flattenWithBlankLine(lines, true);
+        return lines;
       }
 
       const rows: any[] = Array.isArray(tableContent.rows)
@@ -470,7 +474,7 @@ function serializeBlock(
         : [];
 
       if (rows.length === 0) {
-        return flattenWithBlankLine(lines, true);
+        return lines;
       }
 
       const columnCount = rows.reduce((max, row) => {
@@ -479,7 +483,7 @@ function serializeBlock(
       }, 0);
 
       if (columnCount === 0) {
-        return flattenWithBlankLine(lines, true);
+        return lines;
       }
 
       const headerRowCount = rows.length
@@ -570,7 +574,7 @@ function serializeBlock(
         lines.push(`| ${row.map((cell) => formatCell(cell)).join(" | ")} |`);
       });
 
-      return flattenWithBlankLine(lines, true);
+      return lines;
     }
   }
 
@@ -582,7 +586,7 @@ function serializeBlock(
     }
   }
   lines.push(...serializeChildren(fallbackBlock, ctx));
-  return flattenWithBlankLine(lines, false);
+  return lines;
 }
 
 function serializeBlocks(blocks: CustomEditorBlock[], ctx: MarkdownContext): string[] {
@@ -1394,12 +1398,16 @@ export function fixMalformedImageBlocks(blocks: CustomPartialBlock[]): CustomPar
   return result;
 }
 
+// The `preserveBlankLines` option is retained for backwards compatibility
+// but is now a no-op: blank lines in the source markdown always produce
+// empty paragraph blocks (except for leading/trailing blanks, which are
+// dropped). This gives a 1:1 mapping between blank lines and blocks so the
+// Rich editor can render and delete each blank line individually.
 export interface MarkdownToBlocksOptions {
-  /** When true, every blank line produces an empty paragraph block. */
   preserveBlankLines?: boolean;
 }
 
-export function markdownToBlocks(markdown: string, options?: MarkdownToBlocksOptions): CustomPartialBlock[] {
+export function markdownToBlocks(markdown: string, _options?: MarkdownToBlocksOptions): CustomPartialBlock[] {
   const normalized = markdown.replace(/\r\n/g, "\n");
   const lines = normalized.split("\n");
   const blocks: CustomPartialBlock[] = [];
@@ -1409,22 +1417,12 @@ export function markdownToBlocks(markdown: string, options?: MarkdownToBlocksOpt
   while (index < lines.length) {
     const line = lines[index];
     if (!line.trim()) {
-      if (options?.preserveBlankLines) {
+      // Drop blank lines until we've emitted at least one block, so leading
+      // blanks don't produce a ghost empty paragraph at the top of the doc.
+      if (blocks.length > 0) {
         blocks.push({ type: "paragraph", content: [], children: [] } as CustomPartialBlock);
-        index += 1;
-        continue;
       }
       index += 1;
-      // Count consecutive blank lines
-      let blankCount = 1;
-      while (index < lines.length && !lines[index].trim()) {
-        blankCount++;
-        index++;
-      }
-      // Create empty paragraph for each extra blank line beyond the first
-      for (let i = 1; i < blankCount; i++) {
-        blocks.push({ type: "paragraph", content: [], children: [] } as CustomPartialBlock);
-      }
       continue;
     }
 
@@ -1540,16 +1538,18 @@ export function markdownToBlocks(markdown: string, options?: MarkdownToBlocksOpt
     index = paragraph.nextIndex;
   }
 
-  // Insert empty paragraphs between consecutive headings so users can type between them
-  const result: CustomPartialBlock[] = [];
-  for (let i = 0; i < blocks.length; i++) {
-    result.push(blocks[i]);
-    if (blocks[i].type === "heading" && blocks[i + 1]?.type === "heading") {
-      result.push({ type: "paragraph", content: [], children: [] } as CustomPartialBlock);
-    }
+  // Drop trailing empty paragraphs so a trailing blank line in the source
+  // doesn't leave a ghost empty block at the end of the document.
+  while (
+    blocks.length > 0 &&
+    blocks[blocks.length - 1].type === "paragraph" &&
+    (!blocks[blocks.length - 1].content ||
+      (blocks[blocks.length - 1].content as any[]).length === 0)
+  ) {
+    blocks.pop();
   }
 
-  return fixMalformedImageBlocks(result);
+  return fixMalformedImageBlocks(blocks);
 }
 
 function splitTableRow(line: string): string[] {