react-native-nitro-markdown 0.5.3 → 0.5.5

package/README.md

@@ -12,6 +12,9 @@ Native Markdown parsing and rendering for React Native, powered by [md4c](https:
 - **Full rendering pipeline** -- parser + renderer + streaming session in one package
 - **GFM support** -- tables, strikethrough, task lists, autolinks
 - **Math rendering** -- inline and block LaTeX via `react-native-mathjax-svg` (optional)
+- **Opt-in HTML AST nodes** -- preserve raw HTML as `html_inline` / `html_block` for custom renderers
+- **Large document support** -- top-level block virtualization and cached renderer styles
+- **Code highlighting** -- built-in JS/TS, Python, and Bash tokenizer with custom highlighter support
 - **Headless API** -- parse markdown and extract text without any UI
 - **Streaming** -- incremental rendering for chat/LLM token streams
 - **Customizable** -- themes, per-node style overrides, custom renderers, AST transforms, plugin pipeline
@@ -21,17 +24,26 @@ Native Markdown parsing and rendering for React Native, powered by [md4c](https:
 | Dependency | Version |
 |---|---|
 | React Native | `>=0.75.0` |
-| react-native-nitro-modules | `>=0.35.0` |
+| react-native-nitro-modules | `>=0.35.4` |
 | react-native-mathjax-svg *(optional)* | `>=0.9.0` |
 | react-native-svg *(optional, for math)* | `>=13.0.0` |
 
 ## Installation
 
+With npm:
+
 ```bash
 npm install react-native-nitro-markdown react-native-nitro-modules
 cd ios && pod install
 ```
 
+With Bun:
+
+```bash
+bun add react-native-nitro-markdown react-native-nitro-modules
+cd ios && pod install
+```
+
 For math rendering:
 
 ```bash
@@ -61,6 +73,22 @@ export function Example() {
 
 ## API Reference
 
+### Parser Options
+
+`ParserOptions` controls native parser extensions. Defaults are conservative for HTML and feature-complete for Markdown extensions.
+
+| Option | Default | Enables | Notes |
+|---|---:|---|---|
+| `gfm` | `true` | Tables, strikethrough, task lists, permissive autolinks | Set `false` for stricter CommonMark-style parsing |
+| `math` | `true` | Inline and display LaTeX spans | Rendering falls back to plain styled text unless optional math deps are installed |
+| `html` | `false` | `html_inline` and `html_block` AST nodes | Raw HTML is not rendered by default; provide custom renderers |
+
+```tsx
+<Markdown options={{ gfm: true, math: true, html: false }}>
+  {content}
+</Markdown>
+```
+
 ### `<Markdown>`
 
 The main component. Parses a markdown string and renders it.
@@ -72,9 +100,10 @@ import { Markdown } from "react-native-nitro-markdown";
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `string` | required | Markdown input string |
-| `options` | `ParserOptions` | -- | Parser flags (`gfm`, `math`) |
+| `options` | `ParserOptions` | -- | Parser flags (`gfm`, `math`, `html`) |
 | `plugins` | `MarkdownPlugin[]` | -- | Plugin hooks (`beforeParse`, `afterParse`) |
 | `sourceAst` | `MarkdownNode` | -- | Pre-parsed AST; skips native parse when provided |
+| `parseCache` | `boolean` | `true` | Enable internal parse result caching for repeated inputs |
 | `astTransform` | `AstTransform` | -- | Post-parse AST rewrite before render |
 | `renderers` | `CustomRenderers` | `{}` | Per-node custom renderer overrides |
 | `theme` | `PartialMarkdownTheme` | `defaultMarkdownTheme` | Theme token overrides |
@@ -93,6 +122,10 @@ import { Markdown } from "react-native-nitro-markdown";
 
 **Pipeline order:** `beforeParse` plugins (by priority desc) -> parse/sourceAst -> `afterParse` plugins (by priority desc) -> `astTransform` -> render.
 
+When `sourceAst` is provided, `beforeParse` plugins are skipped because no source string is parsed. `afterParse` plugins still run on the provided AST.
+
+`parseCache` defaults to `true` and caches parse results for repeated markdown inputs. Set `parseCache={false}` to force a fresh native parse on each input change. This flag has no effect when `sourceAst` is provided.
+
 ### `<MarkdownStream>`
 
 Renders markdown from a streaming session. Extends `MarkdownProps` (minus `children`).
@@ -174,7 +207,7 @@ import {
 
 | Function | Description |
 |---|---|
-| `parseMarkdown(text, options?)` | Parse to AST (options: `{ gfm?, math? }`) |
+| `parseMarkdown(text, options?)` | Parse to AST (options: `{ gfm?, math?, html? }`) |
 | `parseMarkdownWithOptions(text, options)` | Parse with explicit options |
 | `extractPlainText(text)` | Parse and return plain text from native parser |
 | `extractPlainTextWithOptions(text, options)` | Same with parser flags |
@@ -218,9 +251,41 @@ Renderers receive `EnhancedRendererProps` with `node`, `children`, and `Renderer
 | `code_inline` | `content` |
 | `list` | `ordered`, `start` |
 | `task_list_item` | `checked` |
+| `html_inline`, `html_block` | Read raw HTML from `node.content` |
 
 Return `undefined` to fall back to the built-in renderer, or `null` to render nothing.
 
+#### Rendering HTML Nodes
+
+HTML parsing is opt-in and produces raw AST nodes. The built-in renderer intentionally renders nothing for `html_inline` and `html_block`; applications decide what is safe to display.
+
+```tsx
+import { Text, View } from "react-native";
+import { Markdown } from "react-native-nitro-markdown";
+
+<Markdown
+  options={{ html: true }}
+  renderers={{
+    html_inline: ({ node }) => {
+      if (node.content === "<br>") return <Text>{"\n"}</Text>;
+      return null;
+    },
+    html_block: ({ node }) => {
+      if (!node.content?.includes('data-kind="release-note"')) return null;
+      return (
+        <View>
+          <Text>Release note</Text>
+        </View>
+      );
+    },
+  }}
+>
+  {content}
+</Markdown>;
+```
+
+Do not pass untrusted HTML directly into a WebView from a renderer. Sanitize or map known tags/attributes to native components.
+
 ### Theme API
 
 ```tsx
@@ -337,11 +402,17 @@ const plugins: MarkdownPlugin[] = [
 ```tsx
 import { Markdown, parseMarkdownWithOptions } from "react-native-nitro-markdown";
 
-const ast = parseMarkdownWithOptions(content, { gfm: true, math: true });
+const ast = parseMarkdownWithOptions(content, {
+  gfm: true,
+  math: true,
+  html: false,
+});
 
 <Markdown sourceAst={ast}>{"ignored when sourceAst is provided"}</Markdown>;
 ```
 
+With `sourceAst`, `beforeParse` plugins are skipped, while `afterParse` and `astTransform` still apply.
+
 ### Virtualization (large documents)
 
 ```tsx
@@ -363,6 +434,8 @@ Keep `Markdown` as the primary vertical scroller when virtualization is enabled
 ### Syntax Highlighting
 
 ```tsx
+import type { CodeHighlighter } from "react-native-nitro-markdown";
+
 // Built-in highlighter (JS/TS, Python, Bash)
 <Markdown highlightCode>{"```typescript\nconst x: number = 42;\n```"}</Markdown>
 
@@ -395,7 +468,7 @@ Default link behavior: trims href, calls `onLinkPress`, validates scheme (`http:
 
 `document`, `heading`, `paragraph`, `text`, `bold`, `italic`, `strikethrough`, `link`, `image`, `code_inline`, `code_block`, `blockquote`, `horizontal_rule`, `line_break`, `soft_break`, `table`, `table_head`, `table_body`, `table_row`, `table_cell`, `list`, `list_item`, `task_list_item`, `math_inline`, `math_block`, `html_block`, `html_inline`
 
-`html_inline` and `html_block` are parsed but not rendered by default.
+`html_inline` and `html_block` are parsed only when `options.html` is `true`; they are not rendered by default. Use a custom renderer to handle them, and read raw HTML from `node.content`.
 
 ## Package Exports
 
@@ -409,10 +482,11 @@ Parser and text utilities only -- no React dependencies. Use this for server-sid
 
 ## Performance Tips
 
-- Use `updateStrategy="raf"` for streaming
-- Batch `session.append()` calls (50-100ms intervals) rather than per-character
-- Enable `virtualize` for large documents
-- Use the headless API when you don't need built-in renderers
+- Use `updateStrategy="raf"` for streaming UI updates.
+- Batch `session.append()` calls at 50-100ms intervals rather than per-character.
+- Enable `virtualize="auto"` for long documents and keep `Markdown` as the primary vertical scroller.
+- Memoize custom `plugins`, `renderers`, `theme`, and `styles` objects when they are created inside a component.
+- Use the headless API when you only need parsing, plain text extraction, search indexing, or a custom renderer.
 
 ## Troubleshooting
 
@@ -432,9 +506,14 @@ The `apps/example` directory contains a full demo app with these screens:
 | Bench | `app/index.tsx` | Smoke tests + benchmark vs JS parsers |
 | Default | `app/render-default.tsx` | Built-in renderer defaults |
 | Styles | `app/render-default-styles.tsx` | Theme and style overrides |
-| Custom | `app/render-custom.tsx` | Custom renderers + AST transform |
+| Custom | `app/render-custom.tsx` | HTML AST rendering, custom renderers, AST transform |
 | Stream | `app/render-stream.tsx` | Live streaming with token append |
 
+## Release Checks
+
+- `bun run harness` runs lint, typecheck, JS coverage, benchmark checks, and C++ coverage.
+- `bun run publish-package -- --dry-run --yes` validates release docs, runs publish verification, builds the package, and performs an npm dry run.
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md).

package/android/CMakeLists.txt

@@ -13,6 +13,7 @@ set(CPP_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../cpp")
 file(GLOB MD4C_SOURCES "${CPP_ROOT}/md4c/*.c")
 file(GLOB CORE_SOURCES "${CPP_ROOT}/core/*.cpp")
 file(GLOB BINDING_SOURCES "${CPP_ROOT}/bindings/*.cpp")
+list(FILTER CORE_SOURCES EXCLUDE REGEX ".*Test\\.cpp$")
 
 # Create the shared library with our sources
 add_library(${PROJECT_NAME} SHARED
@@ -44,4 +45,3 @@ target_compile_options(${CMAKE_PROJECT_NAME} PRIVATE
     $<$<CONFIG:Release>:-O3 -DNDEBUG>
     $<$<CONFIG:Debug>:-O0 -g>
 )
-

package/android/src/main/java/com/margelo/nitro/com/nitromarkdown/HybridMarkdownSession.kt

@@ -62,7 +62,7 @@ class HybridMarkdownSession : HybridMarkdownSessionSpec() {
     }
 
     override fun getTextRange(from: Double, to: Double): String {
-        if (from.isNaN() || to.isNaN() || from < 0.0) return ""
+        if (!from.isFinite() || !to.isFinite() || from < 0.0 || to < 0.0 || from > to) return ""
         synchronized(lock) {
             val start = from.toLong().coerceIn(0L, buffer.length.toLong()).toInt()
             val end = to.toLong().coerceIn(start.toLong(), buffer.length.toLong()).toInt()
@@ -88,15 +88,21 @@ class HybridMarkdownSession : HybridMarkdownSessionSpec() {
     }
 
     override fun replace(from: Double, to: Double, text: String): Double {
-        require(from >= 0.0 && to >= from) { "Invalid range: from=$from must be >= 0 and to=$to must be >= from" }
+        require(from.isFinite() && to.isFinite() && from >= 0.0 && to >= 0.0 && to >= from) {
+            "Invalid range: from=$from and to=$to must be finite, from must be >= 0, and to must be >= from"
+        }
         val newLength: Double
+        val notifyFrom: Double
+        val notifyTo: Double
         synchronized(lock) {
             val start = from.toLong().coerceIn(0L, buffer.length.toLong()).toInt()
             val end = to.toLong().coerceIn(start.toLong(), buffer.length.toLong()).toInt()
             buffer.replace(start, end, text)
             newLength = buffer.length.toDouble()
+            notifyFrom = start.toDouble()
+            notifyTo = start.toDouble() + text.length.toDouble()
         }
-        notifyListeners(from, from + text.length.toDouble())
+        notifyListeners(notifyFrom, notifyTo)
         return newLength
     }
 

package/cpp/CMakeLists.txt

@@ -30,6 +30,7 @@ target_include_directories(MD4CCore PUBLIC
 # Preprocessor definitions
 target_compile_definitions(MD4CCore PRIVATE
     MD4C_USE_UTF8=1
+    NITRO_MARKDOWN_TESTING=1
 )
 
 # Create the test executable
@@ -43,4 +44,4 @@ target_link_libraries(MD4CParserTest PRIVATE MD4CCore)
 # Include directories for the test
 target_include_directories(MD4CParserTest PRIVATE
     "${CPP_ROOT}/core"
-)
+)

package/cpp/bindings/HybridMarkdownParser.cpp

@@ -249,7 +249,7 @@ std::string flattenNodeText(const std::shared_ptr<InternalMarkdownNode>& node) {
 } // namespace
 
 std::string HybridMarkdownParser::parse(const std::string& text) {
-    InternalParserOptions opts{.gfm = true, .math = true};
+    InternalParserOptions opts{.gfm = true, .math = true, .html = false};
 
     auto ast = parser_->parse(text, opts);
     return nodeToJson(ast);
@@ -259,13 +259,14 @@ std::string HybridMarkdownParser::parseWithOptions(const std::string& text, cons
     InternalParserOptions internalOpts;
     internalOpts.gfm = options.gfm.value_or(true);
     internalOpts.math = options.math.value_or(true);
+    internalOpts.html = options.html.value_or(false);
     
     auto ast = parser_->parse(text, internalOpts);
     return nodeToJson(ast);
 }
 
 std::string HybridMarkdownParser::extractPlainText(const std::string& text) {
-    InternalParserOptions opts{.gfm = true, .math = true};
+    InternalParserOptions opts{.gfm = true, .math = true, .html = false};
 
     auto ast = parser_->parse(text, opts);
     return flattenNodeText(ast);
@@ -275,6 +276,7 @@ std::string HybridMarkdownParser::extractPlainTextWithOptions(const std::string&
     InternalParserOptions internalOpts;
     internalOpts.gfm = options.gfm.value_or(true);
     internalOpts.math = options.math.value_or(true);
+    internalOpts.html = options.html.value_or(false);
 
     auto ast = parser_->parse(text, internalOpts);
     return flattenNodeText(ast);

package/cpp/core/MD4CParser.cpp

@@ -424,10 +424,28 @@ public:
 
             case MD_TEXT_HTML:
                 impl->flushText();
-                if (!impl->nodeStack.empty()) {
+                if (!impl->nodeStack.empty() && text && size > 0) {
+                    MD_OFFSET off = safeOffset(text, impl->inputText, impl->inputTextSize);
+                    if (off == 0 && text != impl->inputText) off = impl->lastTextEnd;
+
+                    if (impl->nodeStack.top()->type == NodeType::HtmlBlock) {
+                        auto htmlBlock = impl->nodeStack.top();
+                        if (htmlBlock->content.has_value()) {
+                            htmlBlock->content->append(text, size);
+                        } else {
+                            htmlBlock->content = std::string(text, size);
+                        }
+                        htmlBlock->end = off + size;
+                        impl->lastTextEnd = off + size;
+                        break;
+                    }
+
                     auto node = std::make_shared<MarkdownNode>(NodeType::HtmlInline);
                     node->content = std::string(text, size);
+                    node->beg = off;
+                    node->end = off + size;
                     impl->nodeStack.top()->addChild(node);
+                    impl->lastTextEnd = off + size;
                 }
                 break;
 
@@ -471,12 +489,20 @@ MD4CParser::MD4CParser() : impl_(std::make_unique<Impl>()) {}
 MD4CParser::~MD4CParser() = default;
 
 std::shared_ptr<MarkdownNode> MD4CParser::parse(const std::string& markdown, const ParserOptions& options) {
+    return parseWithFlags(markdown, options, 0);
+}
+
+std::shared_ptr<MarkdownNode> MD4CParser::parseWithFlags(
+    const std::string& markdown,
+    const ParserOptions& options,
+    unsigned int extraFlags
+) {
     impl_->reset();
     impl_->inputText = markdown.c_str();
     size_t inputSize = clampInputSize(markdown.size());
     impl_->inputTextSize = inputSize;
     
-    unsigned int flags = MD_FLAG_NOHTML;
+    unsigned int flags = options.html ? 0 : MD_FLAG_NOHTML;
     
     if (options.gfm) {
         flags |= MD_FLAG_TABLES;
@@ -488,6 +514,7 @@ std::shared_ptr<MarkdownNode> MD4CParser::parse(const std::string& markdown, con
     if (options.math) {
         flags |= MD_FLAG_LATEXMATHSPANS;
     }
+    flags |= extraFlags;
     
     MD_PARSER parser = {
         0,
@@ -515,4 +542,44 @@ std::shared_ptr<MarkdownNode> MD4CParser::parse(const std::string& markdown, con
     return impl_->root;
 }
 
+#ifdef NITRO_MARKDOWN_TESTING
+std::shared_ptr<MarkdownNode> MD4CParser::parseWithExtraFlagsForTest(
+    const std::string& markdown,
+    const ParserOptions& options,
+    unsigned int extraFlags
+) {
+    return parseWithFlags(markdown, options, extraFlags);
+}
+
+int MD4CParser::enterBlockNullUserdataForTest() {
+    return Impl::enterBlock(MD_BLOCK_DOC, nullptr, 0, nullptr);
+}
+
+int MD4CParser::leaveBlockNullUserdataForTest() {
+    return Impl::leaveBlock(MD_BLOCK_DOC, nullptr, 0, nullptr);
+}
+
+int MD4CParser::enterSpanNullUserdataForTest() {
+    return Impl::enterSpan(MD_SPAN_EM, nullptr, 0, nullptr);
+}
+
+int MD4CParser::leaveSpanNullUserdataForTest() {
+    return Impl::leaveSpan(MD_SPAN_EM, nullptr, 0, nullptr);
+}
+
+int MD4CParser::textNullUserdataForTest() {
+    return Impl::text(MD_TEXT_NORMAL, "x", 1, nullptr);
+}
+
+int MD4CParser::offsetBeforeBaseForTest() {
+    char buffer[2] = {'a', 'b'};
+    return safeOffset(buffer, buffer + 1, 1);
+}
+
+int MD4CParser::offsetPastBaseForTest() {
+    char buffer[2] = {'a', 'b'};
+    return safeOffset(buffer + 1, buffer, 0);
+}
+#endif
+
 } // namespace NitroMarkdown

package/cpp/core/MD4CParser.hpp

@@ -19,6 +19,18 @@ public:
     std::shared_ptr<MarkdownNode> parse(const std::string& markdown, const ParserOptions& options);
 
 #ifdef NITRO_MARKDOWN_TESTING
+    std::shared_ptr<MarkdownNode> parseWithExtraFlagsForTest(
+        const std::string& markdown,
+        const ParserOptions& options,
+        unsigned int extraFlags
+    );
+    static int enterBlockNullUserdataForTest();
+    static int leaveBlockNullUserdataForTest();
+    static int enterSpanNullUserdataForTest();
+    static int leaveSpanNullUserdataForTest();
+    static int textNullUserdataForTest();
+    static int offsetBeforeBaseForTest();
+    static int offsetPastBaseForTest();
     static size_t clampInputSizeForTest(size_t inputSize) {
         size_t maxSize = static_cast<size_t>(std::numeric_limits<MD_SIZE>::max());
         return inputSize > maxSize ? maxSize : inputSize;
@@ -27,6 +39,11 @@ public:
     
 private:
     class Impl;
+    std::shared_ptr<MarkdownNode> parseWithFlags(
+        const std::string& markdown,
+        const ParserOptions& options,
+        unsigned int extraFlags
+    );
     std::unique_ptr<Impl> impl_;
 };
 

package/cpp/core/MarkdownTypes.hpp

@@ -118,7 +118,7 @@ struct MarkdownNode {
 struct ParserOptions {
     bool gfm = true;
     bool math = true;
+    bool html = false;
 };
 
 } // namespace NitroMarkdown
-

package/lib/commonjs/headless.js

@@ -47,7 +47,7 @@ try {
 /**
  * Parse markdown text with custom options.
  * @param text - The markdown text to parse
- * @param options - Parser options (gfm, math)
+ * @param options - Parser options (gfm, math, html)
  * @returns The root node of the parsed AST
  */
 
@@ -72,7 +72,7 @@ function parseMarkdown(text, options) {
 /**
  * Parse markdown text with custom options.
  * @param text - The markdown text to parse
- * @param options - Parser options (gfm, math)
+ * @param options - Parser options (gfm, math, html)
  * @returns The root node of the parsed AST
  */
 function parseMarkdownWithOptions(text, options) {