react-native-enriched-markdown-scaffold 0.7.4-scaffold.8 → 1.0.2-scaffold.1

package/ios/input/ENRMInputParser.mm

@@ -1,20 +1,26 @@
 #import "ENRMInputParser.h"
+#import "ENRMBlockSyntaxSentinel.h"
+#import "ENRMFeatureFlags.h"
 #import "ENRMFormattingRange.h"
 #import "ENRMInputRemend.h"
 #include "md4c.h"
+#include <algorithm>
 #include <string>
 #include <vector>
 
 @interface ENRMParseResult ()
 @property (nonatomic, strong, readwrite) NSString *plainText;
 @property (nonatomic, strong, readwrite) NSArray<ENRMFormattingRange *> *formattingRanges;
+@property (nonatomic, strong, readwrite) NSArray<ENRMBlockRange *> *blockRanges;
 @property (nonatomic, strong, readwrite) NSArray<ENRMMathAtom *> *mathAtoms;
 @end
 
 @implementation ENRMParseResult
 @end
 
-@implementation ENRMMathAtom
+@interface ENRMInputParser ()
+/// Shared body of both public entry points. `remend` gates `ENRMInputRemendComplete`.
+- (ENRMParseResult *)parseToPlainTextAndRanges:(NSString *)markdown remend:(BOOL)remend;
 @end
 
 namespace {
@@ -44,6 +50,46 @@ static bool isSupportedSpan(MD_SPANTYPE md4cType, ENRMInputStyleType &outStyleTy
   return false;
 }
 
+// Block-type mapping mirrors kSupportedSpans for the inline pipeline. A block
+// handler extends recognition by adding its md4c block here and, if leveled,
+// reading its detail in resolveBlockLevel below. MD_BLOCK_P maps to the
+// implicit Paragraph default and produces no stored block range.
+struct BlockTypeMapping {
+  MD_BLOCKTYPE md4cType;
+  ENRMInputBlockType blockType;
+};
+
+static const BlockTypeMapping kSupportedBlocks[] = {
+    {MD_BLOCK_P, ENRMInputBlockTypeParagraph},
+    // MD_BLOCK_H maps to a representative heading type; onEnterBlock resolves the
+    // level (via resolveBlockLevel) and rewrites the type to the level-specific
+    // ENRMInputBlockTypeHeadingN.
+    {MD_BLOCK_H, ENRMInputBlockTypeHeading1},
+};
+static const size_t kSupportedBlockCount = sizeof(kSupportedBlocks) / sizeof(kSupportedBlocks[0]);
+
+static bool isSupportedBlock(MD_BLOCKTYPE md4cType, ENRMInputBlockType &outBlockType)
+{
+  for (size_t index = 0; index < kSupportedBlockCount; index++) {
+    if (kSupportedBlocks[index].md4cType == md4cType) {
+      outBlockType = kSupportedBlocks[index].blockType;
+      return true;
+    }
+  }
+  return false;
+}
+
+// Per-block integer payload (heading level, list depth). md4c exposes this in
+// the block's MD_BLOCK_*_DETAIL struct. Headings read MD_BLOCK_H_DETAIL.level
+// (1-6); other blocks have no level and return 0.
+static NSInteger resolveBlockLevel(MD_BLOCKTYPE blockType, void *detail)
+{
+  if (blockType == MD_BLOCK_H && detail) {
+    return (NSInteger)(static_cast<MD_BLOCK_H_DETAIL *>(detail)->level);
+  }
+  return 0;
+}
+
 struct InlineSpanInfo {
   ENRMInputStyleType type;
   size_t openingDelimiterByteOffset;
@@ -52,11 +98,38 @@ struct InlineSpanInfo {
   std::string linkURL;
 };
 
+struct BlockInfo {
+  ENRMInputBlockType type;
+  NSInteger level;
+  size_t contentStartByteOffset = kByteOffsetUnset;
+  size_t contentEndByteOffset = kByteOffsetUnset;
+};
+
+// A `$...$` / `$$...$$` run. Unlike an inline span, math is not styled text: the
+// whole formula collapses to one atomic character in the plain text, so only the
+// raw syntax extent and the LaTeX source matter. The extent is derived from the
+// content bytes plus the delimiter width rather than from `lastTextEnd`, which
+// would be wrong for math opening a span (e.g. "**$x$**", where no text has been
+// emitted since the bold marker).
 struct MathSpanInfo {
   bool displayMode;
-  size_t openingDelimiterByteOffset;
+  size_t contentStartByteOffset = kByteOffsetUnset;
   size_t contentEndByteOffset = kByteOffsetUnset;
   std::string latex;
+
+  size_t delimiterLength() const
+  {
+    return displayMode ? 2 : 1;
+  }
+  size_t syntaxStartByteOffset() const
+  {
+    size_t delimiter = delimiterLength();
+    return contentStartByteOffset >= delimiter ? contentStartByteOffset - delimiter : 0;
+  }
+  size_t syntaxEndByteOffset() const
+  {
+    return contentEndByteOffset + delimiterLength();
+  }
 };
 
 struct ParseContext {
@@ -65,9 +138,16 @@ struct ParseContext {
   size_t originalLength;
   std::vector<InlineSpanInfo> openStack;
   std::vector<InlineSpanInfo> resolved;
+  std::vector<BlockInfo> openBlockStack;
+  std::vector<BlockInfo> resolvedBlocks;
   std::vector<MathSpanInfo> openMathStack;
   std::vector<MathSpanInfo> resolvedMath;
+  std::vector<size_t> textStartOffsets;
   size_t lastTextEnd = 0;
+  // Open list containers, innermost last (true = ordered). An item's depth is
+  // the stack size - 1 and its type the innermost container's; md4c carries no
+  // per-item depth, so both derive from the open UL/OL ancestors.
+  std::vector<bool> listContainerStack;
 };
 
 static std::vector<NSUInteger> buildByteToUTF16Map(const char *utf8, size_t byteLength)
@@ -108,55 +188,119 @@ static inline NSUInteger mapByteOffset(const std::vector<NSUInteger> &map, size_
   return map[std::min(offset, maxOffset)];
 }
 
-static const size_t kClosingDelimiterByteLength[] = {
-    [ENRMInputStyleTypeStrong] = 2,        [ENRMInputStyleTypeEmphasis] = 1, [ENRMInputStyleTypeUnderline] = 1,
-    [ENRMInputStyleTypeStrikethrough] = 2, [ENRMInputStyleTypeSpoiler] = 2,
-};
-
-static size_t closingDelimiterEndByte(const InlineSpanInfo &span, const char *utf8, size_t bufferLength)
+static size_t closingDelimiterEndByte(const ParseContext &context, const InlineSpanInfo &span)
 {
   size_t position = span.contentEndByteOffset;
 
   if (span.type == ENRMInputStyleTypeLink) {
-    while (position < bufferLength && utf8[position] != ')') {
+    while (position < context.bufferLength && context.buffer[position] != ')') {
       position++;
     }
-    return (position < bufferLength) ? position + 1 : position;
+    return (position < context.bufferLength) ? position + 1 : position;
   }
 
-  return position + kClosingDelimiterByteLength[span.type];
+  // Markdown delimiter bytes occupy the gap between content end and the next emitted text run
+  // (md4c never emits syntax bytes as text). Anchoring here — rather than adding a
+  // fixed per-type length — keeps stacked closers of co-terminating spans (e.g.
+  // "***", "**~~x~~**") from overlapping and leaking a trailing marker.
+  auto next = std::lower_bound(context.textStartOffsets.begin(), context.textStartOffsets.end(), position);
+  return (next != context.textStartOffsets.end()) ? *next : context.bufferLength;
 }
 
-// TODO: onEnterBlock/onLeaveBlock are no-ops, so lastTextEnd never advances
-// past inter-block whitespace. This causes onEnterSpan to set
-// openingDelimiterByteOffset to a position that includes \n\n (or other
-// block-separator characters) in the syntax range. The newline-stripping
-// workaround in parseToPlainTextAndRanges only handles \n/\r — it won't
-// catch block-level syntax like list markers, blockquote '>', or heading '#'
-// if those elements are added in the future.
-//
-// A proper fix would advance lastTextEnd here (or retroactively adjust
-// openingDelimiterByteOffset for spans opened since the last block
-// transition). md4c's enter_block doesn't provide a byte offset, so this
-// likely requires tracking a "new block" flag and correcting span offsets
-// in onText when the first text inside a new block arrives.
-static int onEnterBlock(MD_BLOCKTYPE, void *, void *)
+// Block tracking. md4c's enter_block gives no byte offset, so a block's content
+// range is bounded by the text spans it encloses: onText records the first/last
+// text offset into the currently open block(s). On leave_block the block is
+// resolved with whatever text range it accumulated; empty blocks (no text) are
+// discarded later when building results.
+static int onEnterBlock(MD_BLOCKTYPE blockType, void *detail, void *userdata)
 {
+  auto *context = static_cast<ParseContext *>(userdata);
+
+  // List nesting is tracked by the container stack, not stored as its own
+  // block: the UL/OL container only frames the items that read it.
+  if (blockType == MD_BLOCK_UL || blockType == MD_BLOCK_OL) {
+    context->listContainerStack.push_back(blockType == MD_BLOCK_OL);
+    return 0;
+  }
+
+  // Tag the item itself, not its inner paragraph: md4c emits MD_BLOCK_P inside
+  // items only for *loose* lists, so a tight list has no paragraph to tag. The
+  // item's range is clipped back to its own first line when building results.
+  if (blockType == MD_BLOCK_LI) {
+    BlockInfo blockInfo;
+    BOOL ordered = !context->listContainerStack.empty() && context->listContainerStack.back();
+    blockInfo.type = ordered ? ENRMInputBlockTypeOrderedListItem : ENRMInputBlockTypeUnorderedListItem;
+    // Clamp to the shared max depth (matches Android's parser): markdown can
+    // nest deeper than the editor represents, and downstream metadata passes
+    // size their counters by kENRMMaxListDepth.
+    blockInfo.level = context->listContainerStack.empty()
+                          ? 0
+                          : MIN((NSInteger)context->listContainerStack.size() - 1, kENRMMaxListDepth);
+    context->openBlockStack.push_back(blockInfo);
+    return 0;
+  }
+
+  ENRMInputBlockType mappedType;
+  if (!isSupportedBlock(blockType, mappedType)) {
+    return 0;
+  }
+
+  BlockInfo blockInfo;
+  blockInfo.level = resolveBlockLevel(blockType, detail);
+  // Headings share one md4c block type but split into six ENRMInputBlockTypes by
+  // level; map the resolved level onto the concrete heading type.
+  blockInfo.type = (blockType == MD_BLOCK_H) ? ENRMBlockTypeForHeadingLevel(blockInfo.level) : mappedType;
+  context->openBlockStack.push_back(blockInfo);
   return 0;
 }
-static int onLeaveBlock(MD_BLOCKTYPE, void *, void *)
+
+static int onLeaveBlock(MD_BLOCKTYPE blockType, void *, void *userdata)
 {
+  auto *context = static_cast<ParseContext *>(userdata);
+
+  if (blockType == MD_BLOCK_UL || blockType == MD_BLOCK_OL) {
+    if (!context->listContainerStack.empty()) {
+      context->listContainerStack.pop_back();
+    }
+    return 0;
+  }
+
+  // List items are tagged in onEnterBlock (not via isSupportedBlock); resolve
+  // them here the same way as supported blocks.
+  if (blockType == MD_BLOCK_LI) {
+    if (!context->openBlockStack.empty()) {
+      context->resolvedBlocks.push_back(context->openBlockStack.back());
+      context->openBlockStack.pop_back();
+    }
+    return 0;
+  }
+
+  ENRMInputBlockType mappedType;
+  if (!isSupportedBlock(blockType, mappedType)) {
+    return 0;
+  }
+
+  if (context->openBlockStack.empty()) {
+    return 0;
+  }
+
+  context->resolvedBlocks.push_back(context->openBlockStack.back());
+  context->openBlockStack.pop_back();
   return 0;
 }
 
+static inline bool isMathSpan(MD_SPANTYPE spanType)
+{
+  return spanType == MD_SPAN_LATEXMATH || spanType == MD_SPAN_LATEXMATH_DISPLAY;
+}
+
 static int onEnterSpan(MD_SPANTYPE spanType, void *detail, void *userdata)
 {
   auto *context = static_cast<ParseContext *>(userdata);
 
-  if (spanType == MD_SPAN_LATEXMATH || spanType == MD_SPAN_LATEXMATH_DISPLAY) {
+  if (isMathSpan(spanType)) {
     MathSpanInfo mathInfo;
     mathInfo.displayMode = (spanType == MD_SPAN_LATEXMATH_DISPLAY);
-    mathInfo.openingDelimiterByteOffset = context->lastTextEnd;
     context->openMathStack.push_back(mathInfo);
     return 0;
   }
@@ -185,7 +329,7 @@ static int onLeaveSpan(MD_SPANTYPE spanType, void *, void *userdata)
 {
   auto *context = static_cast<ParseContext *>(userdata);
 
-  if (spanType == MD_SPAN_LATEXMATH || spanType == MD_SPAN_LATEXMATH_DISPLAY) {
+  if (isMathSpan(spanType)) {
     if (context->openMathStack.empty()) {
       return 0;
     }
@@ -208,25 +352,56 @@ static int onLeaveSpan(MD_SPANTYPE spanType, void *, void *userdata)
   return 0;
 }
 
-static int onText(MD_TEXTTYPE textType, const MD_CHAR *text, MD_SIZE size, void *userdata)
+static int onText(MD_TEXTTYPE, const MD_CHAR *text, MD_SIZE size, void *userdata)
 {
   if (!text || size == 0) {
     return 0;
   }
   auto *context = static_cast<ParseContext *>(userdata);
 
-  // Inside a math span, md4c emits the latex source (typically MD_TEXT_LATEXMATH).
-  // Accumulate it into the open math info and do not propagate to regular spans.
+  // Inside `$...$` md4c emits the LaTeX source as text. It is never document
+  // text — the whole formula becomes one placeholder character — so it is
+  // collected here and never appended to the plain text. What the enclosing
+  // span/block does see is the formula's full *syntax* extent (delimiters
+  // included): without that a heading holding only math ("# $x$") would resolve
+  // with no content range at all and lose its block prefix.
   if (!context->openMathStack.empty()) {
-    (void)textType;
-    MathSpanInfo &top = context->openMathStack.back();
-    top.latex.append(text, size);
+    MathSpanInfo &math = context->openMathStack.back();
+    math.latex.append(text, size);
+
     bool insideBuffer = (text >= context->buffer && text < context->buffer + context->bufferLength);
-    if (insideBuffer) {
-      size_t textStart = text - context->buffer;
-      top.contentEndByteOffset = textStart + size;
-      context->lastTextEnd = textStart + size;
+    if (!insideBuffer) {
+      // A synthetic token (soft break inside display math) carries no offset;
+      // its characters still belong to the formula, collected above.
+      return 0;
     }
+
+    size_t textStart = text - context->buffer;
+    size_t textEnd = textStart + size;
+    bool isFirstChunk = (math.contentStartByteOffset == kByteOffsetUnset);
+    if (isFirstChunk) {
+      math.contentStartByteOffset = textStart;
+    }
+    math.contentEndByteOffset = textEnd;
+
+    size_t syntaxStart = math.syntaxStartByteOffset();
+    size_t syntaxEnd = math.syntaxEndByteOffset();
+    if (isFirstChunk) {
+      context->textStartOffsets.push_back(syntaxStart);
+    }
+    for (auto &openSpan : context->openStack) {
+      if (openSpan.contentStartByteOffset == kByteOffsetUnset) {
+        openSpan.contentStartByteOffset = syntaxStart;
+      }
+      openSpan.contentEndByteOffset = syntaxEnd;
+    }
+    for (auto &openBlock : context->openBlockStack) {
+      if (openBlock.contentStartByteOffset == kByteOffsetUnset) {
+        openBlock.contentStartByteOffset = syntaxStart;
+      }
+      openBlock.contentEndByteOffset = syntaxEnd;
+    }
+    context->lastTextEnd = syntaxEnd;
     return 0;
   }
 
@@ -234,10 +409,9 @@ static int onText(MD_TEXTTYPE textType, const MD_CHAR *text, MD_SIZE size, void
   // (e.g. MD_TEXT_SOFTBR, MD_TEXT_BR use a string literal "\n").
   // Pointer arithmetic against context->buffer would underflow, corrupting offsets.
   //
-  // TODO: Skipping out-of-buffer tokens means lastTextEnd doesn't advance past
-  // newlines. Fine for inline spans, but if block-level input formatting is
-  // added later, openingDelimiterByteOffset will include newline chars in the
-  // syntax range. See the related TODO above onEnterBlock.
+  // Skipping out-of-buffer tokens means lastTextEnd doesn't advance past
+  // synthetic newlines. Inline-span offsets stay correct because spans never
+  // straddle a synthetic break; block offsets are derived from real text below.
   bool insideBuffer = (text >= context->buffer && text < context->buffer + context->bufferLength);
   if (!insideBuffer) {
     return 0;
@@ -245,6 +419,7 @@ static int onText(MD_TEXTTYPE textType, const MD_CHAR *text, MD_SIZE size, void
 
   size_t textStart = text - context->buffer;
   size_t textEnd = textStart + size;
+  context->textStartOffsets.push_back(textStart);
 
   for (auto &openSpan : context->openStack) {
     if (openSpan.contentStartByteOffset == kByteOffsetUnset) {
@@ -252,13 +427,29 @@ static int onText(MD_TEXTTYPE textType, const MD_CHAR *text, MD_SIZE size, void
     }
     openSpan.contentEndByteOffset = textEnd;
   }
+  for (auto &openBlock : context->openBlockStack) {
+    if (openBlock.contentStartByteOffset == kByteOffsetUnset) {
+      openBlock.contentStartByteOffset = textStart;
+    }
+    openBlock.contentEndByteOffset = textEnd;
+  }
   context->lastTextEnd = textEnd;
   return 0;
 }
 
-static bool runMd4cParse(NSString *markdown, ParseContext &context)
+// The one place math recognition is switched off in a math-disabled build: with
+// the flag clear md4c never opens a LATEXMATH span, so no atom is produced and
+// "$x$" stays literal text — mirroring Android, where `Md4cFlags.latexMath`
+// defaults from `FeatureFlags.IS_MATH_ENABLED`.
+#if ENRICHED_MARKDOWN_MATH
+static const unsigned kMathSpanFlags = MD_FLAG_LATEXMATHSPANS;
+#else
+static const unsigned kMathSpanFlags = 0;
+#endif
+
+static bool runMd4cParse(NSString *markdown, ParseContext &context, bool remend)
 {
-  NSString *completed = ENRMInputRemendComplete(markdown);
+  NSString *completed = remend ? ENRMInputRemendComplete(markdown) : markdown;
   const char *completedUTF8 = [completed UTF8String];
   size_t completedLength = strlen(completedUTF8);
   size_t originalLength = [markdown lengthOfBytesUsingEncoding:NSUTF8StringEncoding];
@@ -269,7 +460,7 @@ static bool runMd4cParse(NSString *markdown, ParseContext &context)
 
   MD_PARSER parser = {
       .abi_version = 0,
-      .flags = MD_FLAG_NOHTML | MD_FLAG_UNDERLINE | MD_FLAG_STRIKETHROUGH | MD_FLAG_SPOILERS | MD_FLAG_LATEXMATHSPANS,
+      .flags = MD_FLAG_NOHTML | MD_FLAG_UNDERLINE | MD_FLAG_STRIKETHROUGH | MD_FLAG_SPOILERS | kMathSpanFlags,
       .enter_block = onEnterBlock,
       .leave_block = onLeaveBlock,
       .enter_span = onEnterSpan,
@@ -282,25 +473,12 @@ static bool runMd4cParse(NSString *markdown, ParseContext &context)
   return md_parse(completedUTF8, (MD_SIZE)completedLength, &parser, &context) == 0;
 }
 
-struct ParsedSpans {
-  std::vector<MathSpanInfo> mathSpans;
-};
-
-static NSArray<ENRMInputStyledRange *> *runParseInternal(NSString *markdown, ParsedSpans &out)
+// Builds inline styled ranges (raw-markdown UTF-16 coords) from a completed
+// parse. Split out so parseToPlainTextAndRanges: can derive inline and block
+// ranges from ONE md4c run instead of parsing twice.
+static NSArray<ENRMInputStyledRange *> *styledRangesFromContext(const ParseContext &context,
+                                                                const std::vector<NSUInteger> &byteMap)
 {
-  if (markdown.length == 0) {
-    return @[];
-  }
-
-  ParseContext context;
-  if (!runMd4cParse(markdown, context)) {
-    return @[];
-  }
-
-  out.mathSpans = context.resolvedMath;
-
-  auto byteMap = buildByteToUTF16Map(context.buffer, context.bufferLength);
-
   NSMutableArray<ENRMInputStyledRange *> *results = [NSMutableArray arrayWithCapacity:context.resolved.size()];
 
   for (const auto &spanInfo : context.resolved) {
@@ -323,8 +501,7 @@ static NSArray<ENRMInputStyledRange *> *runParseInternal(NSString *markdown, Par
     NSUInteger openStart = mapByteOffset(byteMap, spanInfo.openingDelimiterByteOffset, context.bufferLength);
     NSRange openingRange = NSMakeRange(openStart, contentStart - openStart);
 
-    size_t closingEndByte =
-        std::min(closingDelimiterEndByte(spanInfo, context.buffer, context.bufferLength), context.bufferLength);
+    size_t closingEndByte = std::min(closingDelimiterEndByte(context, spanInfo), context.bufferLength);
     NSUInteger closingStart = mapByteOffset(byteMap, spanInfo.contentEndByteOffset, context.bufferLength);
     NSUInteger closingEnd = mapByteOffset(byteMap, closingEndByte, context.bufferLength);
     NSRange closingRange = NSMakeRange(closingStart, closingEnd - closingStart);
@@ -348,75 +525,221 @@ static NSArray<ENRMInputStyledRange *> *runParseInternal(NSString *markdown, Par
   return results;
 }
 
+// Builds block-level ranges (raw-markdown UTF-16 coords) from the same
+// completed parse, mirroring styledRangesFromContext for inline spans.
+// Paragraph blocks (the implicit default) are omitted — only blocks a handler
+// claims are returned.
+static NSArray<ENRMBlockRange *> *blockRangesFromContext(const ParseContext &context,
+                                                         const std::vector<NSUInteger> &byteMap, NSString *markdown)
+{
+  NSMutableArray<ENRMBlockRange *> *results = [NSMutableArray arrayWithCapacity:context.resolvedBlocks.size()];
+
+  for (const auto &blockInfo : context.resolvedBlocks) {
+    if (blockInfo.type == ENRMInputBlockTypeParagraph) {
+      continue;
+    }
+    if (blockInfo.contentStartByteOffset == kByteOffsetUnset || blockInfo.contentEndByteOffset == kByteOffsetUnset ||
+        blockInfo.contentStartByteOffset > context.originalLength) {
+      continue;
+    }
+
+    NSUInteger contentStart = mapByteOffset(byteMap, blockInfo.contentStartByteOffset, context.bufferLength);
+    NSUInteger contentEnd = mapByteOffset(byteMap, blockInfo.contentEndByteOffset, context.bufferLength);
+    if (contentEnd <= contentStart) {
+      continue;
+    }
+
+    // A list item accumulates all text in its subtree, so a parent item's range
+    // runs through its nested sublist. Clip each item to its own first line so
+    // nested items keep their own (deeper) depth rather than being overwritten
+    // by the parent's range. Input list items are single-line.
+    if (ENRMBlockTypeIsListItem(blockInfo.type) && contentEnd <= markdown.length) {
+      NSRange newline = [markdown rangeOfString:@"\n"
+                                        options:0
+                                          range:NSMakeRange(contentStart, contentEnd - contentStart)];
+      if (newline.location != NSNotFound) {
+        contentEnd = newline.location;
+      }
+      if (contentEnd <= contentStart) {
+        continue;
+      }
+    }
+
+    [results addObject:[ENRMBlockRange rangeWithType:blockInfo.type
+                                               range:NSMakeRange(contentStart, contentEnd - contentStart)
+                                               level:blockInfo.level]];
+  }
+
+  return results;
+}
+
+// A resolved math chip in raw-markdown UTF-16 coords: the full `$...$` extent to
+// replace, plus what to replace it with.
+struct MathChip {
+  NSRange rawRange;
+  NSString *latex;
+  BOOL displayMode;
+};
+
+// Builds math chips from the same completed parse, mirroring the two functions
+// above. A formula whose closing delimiter exists only because ENRMInputRemend
+// completed the buffer is dropped: while "$x" is still being typed it must stay
+// literal text, the same way an unclosed "**" does (see `isComplete`).
+static std::vector<MathChip> mathChipsFromContext(const ParseContext &context, const std::vector<NSUInteger> &byteMap,
+                                                  NSUInteger rawLength)
+{
+  std::vector<MathChip> chips;
+  chips.reserve(context.resolvedMath.size());
+
+  for (const auto &math : context.resolvedMath) {
+    // No content bytes at all ("$$"): not a formula, leave it as text.
+    if (math.contentStartByteOffset == kByteOffsetUnset || math.contentEndByteOffset == kByteOffsetUnset) {
+      continue;
+    }
+    size_t syntaxEnd = math.syntaxEndByteOffset();
+    if (syntaxEnd > context.originalLength) {
+      continue;
+    }
+
+    NSUInteger start = mapByteOffset(byteMap, math.syntaxStartByteOffset(), context.bufferLength);
+    NSUInteger end = mapByteOffset(byteMap, syntaxEnd, context.bufferLength);
+    if (end <= start || end > rawLength) {
+      continue;
+    }
+
+    MathChip chip;
+    chip.rawRange = NSMakeRange(start, end - start);
+    chip.latex = [[NSString alloc] initWithBytes:math.latex.data()
+                                          length:math.latex.size()
+                                        encoding:NSUTF8StringEncoding]
+                     ?: @"";
+    chip.displayMode = math.displayMode ? YES : NO;
+    chips.push_back(chip);
+  }
+
+  std::sort(chips.begin(), chips.end(), [](const MathChip &first, const MathChip &second) {
+    return first.rawRange.location < second.rawRange.location;
+  });
+  return chips;
+}
+
 } // namespace
 
 @implementation ENRMInputParser
 
 - (NSArray<ENRMInputStyledRange *> *)parse:(NSString *)markdown
 {
-  ParsedSpans spans;
-  return runParseInternal(markdown, spans);
+  if (markdown.length == 0) {
+    return @[];
+  }
+
+  ParseContext context;
+  if (!runMd4cParse(markdown, context, /* remend */ true)) {
+    return @[];
+  }
+
+  auto byteMap = buildByteToUTF16Map(context.buffer, context.bufferLength);
+  return styledRangesFromContext(context, byteMap);
 }
 
 - (ENRMParseResult *)parseToPlainTextAndRanges:(NSString *)markdown
 {
-  ENRMParseResult *parseResult = [[ENRMParseResult alloc] init];
+  return [self parseToPlainTextAndRanges:markdown remend:YES];
+}
 
-  if (markdown.length == 0) {
-    parseResult.plainText = @"";
-    parseResult.formattingRanges = @[];
-    parseResult.mathAtoms = @[];
-    return parseResult;
+- (ENRMParseResult *)parseToPlainTextAndRanges:(NSString *)markdown blockSyntax:(BOOL)blockSyntax
+{
+  if (blockSyntax) {
+    return [self parseToPlainTextAndRanges:markdown];
   }
 
-  ParsedSpans parsedSpans;
-  NSArray<ENRMInputStyledRange *> *styledRanges = runParseInternal(markdown, parsedSpans);
+  ENRMParseResult *result = [[ENRMParseResult alloc] init];
+  // Block ranges stay empty on every path below: with block syntax off there are
+  // no blocks. Under the sentinel md4c sees one paragraph, which yields no range, so
+  // this is a guard rather than a fix — a range that did leak would reach the block
+  // store and the serializer would prefix it, breaking the byte-for-byte round trip.
+  result.blockRanges = @[];
+
+  NSString *canonical = ENRMBlockSyntaxCanonicalize(markdown);
+  if (canonical.length == 0) {
+    result.plainText = @"";
+    result.formattingRanges = @[];
+    result.mathAtoms = @[];
+    return result;
+  }
 
-  // Compute byte map + raw byte ranges for math spans so we can strip the
-  // entire `$...$` (or `$$...$$`) syntax and inject a single `` at each.
-  size_t rawByteLength = [markdown lengthOfBytesUsingEncoding:NSUTF8StringEncoding];
-  const char *rawUTF8 = [markdown UTF8String];
-  std::vector<NSUInteger> rawByteMap = buildByteToUTF16Map(rawUTF8, rawByteLength);
+  // Remending is skipped too: its speculative closing delimiters are the other
+  // source of characters the serializer cannot replay.
+  ENRMParseResult *encoded = [self parseToPlainTextAndRanges:ENRMBlockSyntaxEncode(canonical) remend:NO];
 
-  struct MathChip {
-    NSRange rawSyntaxRange; // UTF-16 range in the original markdown to strip
-    NSString *latex;
-    BOOL displayMode;
-  };
-  std::vector<MathChip> mathChips;
-  mathChips.reserve(parsedSpans.mathSpans.size());
-  for (const auto &mathInfo : parsedSpans.mathSpans) {
-    if (mathInfo.contentEndByteOffset == kByteOffsetUnset)
-      continue;
-    size_t closingByteEnd = mathInfo.contentEndByteOffset + (mathInfo.displayMode ? 2 : 1);
-    if (closingByteEnd > rawByteLength)
-      closingByteEnd = rawByteLength;
-    if (mathInfo.openingDelimiterByteOffset > rawByteLength)
-      continue;
-    if (closingByteEnd > rawByteLength)
-      continue;
+  NSString *decoded = ENRMBlockSyntaxDecode(encoded.plainText);
+  if (decoded == nil) {
+    result.plainText = canonical;
+    result.formattingRanges = @[];
+    result.mathAtoms = @[];
+    return result;
+  }
+
+  // Only the leading sentinel was removed, so every offset shifts by exactly one.
+  NSUInteger decodedLength = decoded.length;
 
-    NSUInteger rawStart = rawByteMap[mathInfo.openingDelimiterByteOffset];
-    NSUInteger rawEnd = rawByteMap[closingByteEnd];
-    if (rawEnd <= rawStart)
+  NSMutableArray<ENRMFormattingRange *> *shiftedRanges =
+      [NSMutableArray arrayWithCapacity:encoded.formattingRanges.count];
+  for (ENRMFormattingRange *range in encoded.formattingRanges) {
+    NSRange r = range.range;
+    if (r.location == 0 || r.length == 0 || NSMaxRange(r) - 1 > decodedLength) {
       continue;
+    }
+    [shiftedRanges addObject:[ENRMFormattingRange rangeWithType:range.type
+                                                          range:NSMakeRange(r.location - 1, r.length)
+                                                            url:range.url]];
+  }
 
-    MathChip chip;
-    chip.rawSyntaxRange = NSMakeRange(rawStart, rawEnd - rawStart);
-    chip.latex = [[NSString alloc] initWithBytes:mathInfo.latex.data()
-                                          length:mathInfo.latex.size()
-                                        encoding:NSUTF8StringEncoding]
-                     ?: @"";
-    chip.displayMode = mathInfo.displayMode ? YES : NO;
-    mathChips.push_back(chip);
+  NSMutableArray<ENRMMathAtom *> *shiftedAtoms = [NSMutableArray arrayWithCapacity:encoded.mathAtoms.count];
+  for (ENRMMathAtom *atom in encoded.mathAtoms) {
+    if (atom.position == 0 || atom.position - 1 >= decodedLength) {
+      continue;
+    }
+    ENRMMathAtom *shifted = [[ENRMMathAtom alloc] init];
+    shifted.position = atom.position - 1;
+    shifted.latex = atom.latex;
+    shifted.displayMode = atom.displayMode;
+    [shiftedAtoms addObject:shifted];
   }
 
-  // Sort math chips by raw position so we process left-to-right.
-  std::sort(mathChips.begin(), mathChips.end(),
-            [](const MathChip &a, const MathChip &b) { return a.rawSyntaxRange.location < b.rawSyntaxRange.location; });
+  result.plainText = decoded;
+  result.formattingRanges = shiftedRanges;
+  result.mathAtoms = shiftedAtoms;
+  return result;
+}
+
+- (ENRMParseResult *)parseToPlainTextAndRanges:(NSString *)markdown remend:(BOOL)remend
+{
+  ENRMParseResult *parseResult = [[ENRMParseResult alloc] init];
+
+  if (markdown.length == 0) {
+    parseResult.plainText = @"";
+    parseResult.formattingRanges = @[];
+    parseResult.blockRanges = @[];
+    parseResult.mathAtoms = @[];
+    return parseResult;
+  }
 
   NSUInteger rawLength = markdown.length;
 
+  // One md4c run feeds all three pipelines: inline styled ranges, block ranges
+  // and math chips are derived from the same ParseContext.
+  ParseContext context;
+  NSArray<ENRMInputStyledRange *> *styledRanges = @[];
+  NSArray<ENRMBlockRange *> *rawBlockRanges = @[];
+  std::vector<MathChip> mathChips;
+  if (runMd4cParse(markdown, context, remend)) {
+    auto byteMap = buildByteToUTF16Map(context.buffer, context.bufferLength);
+    styledRanges = styledRangesFromContext(context, byteMap);
+    rawBlockRanges = blockRangesFromContext(context, byteMap, markdown);
+    mathChips = mathChipsFromContext(context, byteMap, rawLength);
+  }
+
   NSMutableIndexSet *syntaxIndexes = [NSMutableIndexSet indexSet];
   for (ENRMInputStyledRange *styledRange in styledRanges) {
     if (!styledRange.isComplete)
@@ -432,19 +755,28 @@ static NSArray<ENRMInputStyledRange *> *runParseInternal(NSString *markdown, Par
     }
   }
 
-  // Add math full ranges (delimiters + latex) to the strip set.
-  for (const auto &chip : mathChips) {
-    NSRange r = chip.rawSyntaxRange;
-    if (NSMaxRange(r) > rawLength) {
-      r.length = (r.location < rawLength) ? rawLength - r.location : 0;
+  // Strip block markers (e.g. "# ") from plain text — same as inline delimiters.
+  // Without this the marker survives and the serializer doubles it ("# # ").
+  for (ENRMBlockRange *rawBlock in rawBlockRanges) {
+    NSUInteger contentStart = rawBlock.range.location;
+    if (contentStart == 0 || contentStart > rawLength) {
+      continue;
+    }
+    NSUInteger lineStart = contentStart;
+    while (lineStart > 0) {
+      unichar previous = [markdown characterAtIndex:lineStart - 1];
+      if (previous == '\n' || previous == '\r') {
+        break;
+      }
+      lineStart--;
     }
-    if (r.length > 0) {
-      [syntaxIndexes addIndexesInRange:r];
+    if (contentStart > lineStart) {
+      [syntaxIndexes addIndexesInRange:NSMakeRange(lineStart, contentStart - lineStart)];
     }
   }
 
   // Strip \n/\r from syntax ranges — newlines are structural content, not
-  // markdown syntax (included due to no-op onEnterBlock/onLeaveBlock).
+  // markdown syntax, and must survive into the plain text.
   NSMutableIndexSet *newlineIndexes = [NSMutableIndexSet indexSet];
   [syntaxIndexes enumerateIndexesUsingBlock:^(NSUInteger index, BOOL *stop) {
     if (index < rawLength) {
@@ -456,32 +788,73 @@ static NSArray<ENRMInputStyledRange *> *runParseInternal(NSString *markdown, Par
   }];
   [syntaxIndexes removeIndexes:newlineIndexes];
 
+  // Build the plain text and the raw→plain map in one pass. Three kinds of raw
+  // index: a math chip's extent collapses to one placeholder character, a syntax
+  // index is dropped, everything else is copied verbatim.
+  //
+  // The math substitution happens *here*, not as an insertion afterwards, and
+  // that is the whole point: `rawToPlainMap` stays the single authority, so the
+  // inline ranges AND the block ranges below both map through it unchanged.
+  // Shifting only one of the two is the silent failure this ordering prevents —
+  // one placeholder is n raw characters, so every block boundary after a chip
+  // would land a line off and "# "/"- "/"1. " would prefix the wrong line.
   NSMutableString *plainText = [NSMutableString stringWithCapacity:rawLength];
-  __block std::vector<NSUInteger> rawToPlainMap(rawLength + 1, 0);
+  std::vector<NSUInteger> rawToPlainMap(rawLength + 1, 0);
+  NSMutableArray<ENRMMathAtom *> *mathAtoms = [NSMutableArray arrayWithCapacity:mathChips.size()];
 
-  __block NSUInteger plainPosition = 0;
-  __block NSUInteger previousEnd = 0;
+  NSUInteger plainPosition = 0;
+  NSUInteger verbatimStart = 0;
+  size_t nextChip = 0;
+
+  // Copies the pending verbatim run [from, to) into the plain text.
+  auto flushVerbatim = [&](NSUInteger from, NSUInteger to) {
+    if (to <= from) {
+      return;
+    }
+    [plainText appendString:[markdown substringWithRange:NSMakeRange(from, to - from)]];
+    for (NSUInteger rawIndex = from; rawIndex < to; rawIndex++) {
+      rawToPlainMap[rawIndex] = plainPosition++;
+    }
+  };
 
-  [syntaxIndexes enumerateRangesUsingBlock:^(NSRange syntaxRange, BOOL *stop) {
-    if (syntaxRange.location > previousEnd) {
-      NSRange visibleRange = NSMakeRange(previousEnd, syntaxRange.location - previousEnd);
-      [plainText appendString:[markdown substringWithRange:visibleRange]];
-      for (NSUInteger rawIndex = previousEnd; rawIndex < syntaxRange.location; rawIndex++) {
-        rawToPlainMap[rawIndex] = plainPosition++;
+  NSUInteger rawIndex = 0;
+  while (rawIndex < rawLength) {
+    if (nextChip < mathChips.size() && mathChips[nextChip].rawRange.location == rawIndex) {
+      const MathChip &chip = mathChips[nextChip];
+      NSUInteger chipEnd = MIN(NSMaxRange(chip.rawRange), rawLength);
+      flushVerbatim(verbatimStart, rawIndex);
+
+      ENRMMathAtom *atom = [[ENRMMathAtom alloc] init];
+      atom.position = plainPosition;
+      atom.latex = chip.latex;
+      atom.displayMode = chip.displayMode;
+      [mathAtoms addObject:atom];
+
+      [plainText appendString:ENRMObjectReplacementString()];
+      // Every character of the formula — delimiters included — collapses onto the
+      // placeholder, so a range that starts inside it starts at the chip.
+      for (NSUInteger index = rawIndex; index < chipEnd; index++) {
+        rawToPlainMap[index] = plainPosition;
       }
+      plainPosition++;
+
+      rawIndex = chipEnd;
+      verbatimStart = rawIndex;
+      nextChip++;
+      continue;
     }
-    for (NSUInteger rawIndex = syntaxRange.location; rawIndex < NSMaxRange(syntaxRange); rawIndex++) {
+
+    if ([syntaxIndexes containsIndex:rawIndex]) {
+      flushVerbatim(verbatimStart, rawIndex);
       rawToPlainMap[rawIndex] = plainPosition;
+      rawIndex++;
+      verbatimStart = rawIndex;
+      continue;
     }
-    previousEnd = NSMaxRange(syntaxRange);
-  }];
 
-  if (previousEnd < rawLength) {
-    [plainText appendString:[markdown substringFromIndex:previousEnd]];
-    for (NSUInteger rawIndex = previousEnd; rawIndex < rawLength; rawIndex++) {
-      rawToPlainMap[rawIndex] = plainPosition++;
-    }
+    rawIndex++;
   }
+  flushVerbatim(verbatimStart, rawLength);
   rawToPlainMap[rawLength] = plainPosition;
 
   NSMutableArray<ENRMFormattingRange *> *formattingRanges = [NSMutableArray arrayWithCapacity:styledRanges.count];
@@ -509,46 +882,29 @@ static NSArray<ENRMInputStyledRange *> *runParseInternal(NSString *markdown, Par
     [formattingRanges addObject:formattingRange];
   }
 
-  // Inject `` (U+FFFC, NSAttachmentCharacter) at each math chip's plain
-  // position and emit ENRMMathAtom records pointing at the inserted character.
-  NSMutableArray<ENRMMathAtom *> *mathAtoms = [NSMutableArray arrayWithCapacity:mathChips.size()];
-  static unichar attachmentChar = (unichar)0xFFFC;
-  NSString *attachmentString = [NSString stringWithCharacters:&attachmentChar length:1];
-  NSUInteger insertionsSoFar = 0;
-  for (const auto &chip : mathChips) {
-    NSUInteger rawStart = chip.rawSyntaxRange.location;
-    if (rawStart > rawLength)
+  // Map block content ranges (raw-markdown coords) onto plain-text coords. The
+  // block's marker syntax was stripped above, so the content range maps cleanly
+  // onto the post-strip text and the block no longer covers the marker.
+  NSMutableArray<ENRMBlockRange *> *blockRanges = [NSMutableArray arrayWithCapacity:rawBlockRanges.count];
+  for (ENRMBlockRange *rawBlock in rawBlockRanges) {
+    NSUInteger contentStart = rawBlock.range.location;
+    NSUInteger contentEnd = NSMaxRange(rawBlock.range);
+    if (contentStart > rawLength || contentEnd > rawLength)
+      continue;
+
+    NSUInteger plainStart = rawToPlainMap[contentStart];
+    NSUInteger plainEnd = rawToPlainMap[contentEnd];
+    if (plainEnd <= plainStart)
       continue;
-    NSUInteger basePlain = rawToPlainMap[rawStart];
-    NSUInteger insertAt = basePlain + insertionsSoFar;
-    if (insertAt > plainText.length)
-      insertAt = plainText.length;
-    [plainText insertString:attachmentString atIndex:insertAt];
-
-    ENRMMathAtom *atom = [[ENRMMathAtom alloc] init];
-    atom.position = insertAt;
-    atom.latex = chip.latex ?: @"";
-    atom.displayMode = chip.displayMode;
-    [mathAtoms addObject:atom];
-
-    // Shift existing formatting ranges that start at or after this insertion.
-    for (NSUInteger idx = 0; idx < formattingRanges.count; idx++) {
-      ENRMFormattingRange *fr = formattingRanges[idx];
-      NSRange r = fr.range;
-      if (r.location >= insertAt) {
-        r.location += 1;
-        formattingRanges[idx] = [ENRMFormattingRange rangeWithType:fr.type range:r url:fr.url];
-      } else if (NSMaxRange(r) > insertAt) {
-        r.length += 1;
-        formattingRanges[idx] = [ENRMFormattingRange rangeWithType:fr.type range:r url:fr.url];
-      }
-    }
 
-    insertionsSoFar++;
+    [blockRanges addObject:[ENRMBlockRange rangeWithType:rawBlock.type
+                                                   range:NSMakeRange(plainStart, plainEnd - plainStart)
+                                                   level:rawBlock.level]];
   }
 
   parseResult.plainText = plainText;
   parseResult.formattingRanges = formattingRanges;
+  parseResult.blockRanges = blockRanges;
   parseResult.mathAtoms = mathAtoms;
   return parseResult;
 }