react-native-nitro-markdown 0.4.1 → 0.4.3

package/README.md

@@ -3,468 +3,475 @@
   <img src="./readme/stream-demo.gif" alt="react-native-nitro-markdown stream demo" width="300" />
 </p>
 
-# react-native-nitro-markdown 🚀
+# react-native-nitro-markdown
 
-> The fastest Markdown parser for React Native. Period.
+Native Markdown parsing and rendering for React Native.
 
-[![npm version](https://img.shields.io/npm/v/react-native-nitro-markdown?style=flat-square)](https://www.npmjs.com/package/react-native-nitro-markdown)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Nitro Modules](https://img.shields.io/badge/Powered%20by-Nitro%20Modules-blueviolet?style=flat-square)](https://nitro.margelo.com)
+`react-native-nitro-markdown` uses `md4c` (C++) through Nitro Modules (JSI) to parse Markdown synchronously into a typed AST, then render it with customizable React Native components.
 
-**react-native-nitro-markdown** is a high-performance Markdown parser built on **[md4c](https://github.com/mity/md4c)** (C++) and **[Nitro Modules](https://nitro.margelo.com)**. It parses complex Markdown, GFM, and LaTeX Math into a structured AST **synchronously** via JSI, bypassing the React Native Bridge entirely.
+## Why use it
 
----
+- Native parser (`md4c`) for lower JS thread overhead on large documents
+- End-to-end solution: parser + renderer + streaming session API
+- Headless API for custom rendering and text processing
+- GFM support (tables, strikethrough, task lists, autolinks)
+- Optional math rendering with `react-native-mathjax-svg`
 
-## ⚡ Why Nitro? (Benchmarks)
+## Requirements
 
-We benchmarked this library against the most popular JavaScript parsers on a real mobile device (iPhone 15 Pro, Release Mode) using a heavy **237KB** Markdown document.
+- React Native `>=0.75.0`
+- `react-native-nitro-modules`
 
-| Parser                      | Time (ms)  | Speedup           | Frame Drops (60fps)   |
-| :-------------------------- | :--------- | :---------------- | :-------------------- |
-| **🚀 Nitro Markdown (C++)** | **~29 ms** | **1x (Baseline)** | **~1 frame** (Smooth) |
-| 📋 CommonMark (JS)          | ~82 ms     | 2.8x slower       | ~5 frames (Jank)      |
-| 🏗️ Markdown-It (JS)         | ~118 ms    | 4.0x slower       | ~7 frames (Jank)      |
-| 💨 Marked (JS)              | ~400 ms    | 13.5x slower      | ~24 frames (Freeze)   |
+Optional for math rendering:
 
-> **Takeaway:** JavaScript parsers trigger Garbage Collection pauses. Nitro uses C++ to parse efficiently with zero-copy overhead, keeping your UI thread responsive.
+- `react-native-mathjax-svg >=0.9.0`
+- `react-native-svg >=13.0.0`
 
----
+## Installation
 
-## 📦 Installation
-
-Choose your preferred package manager to install the package and its core dependency (`react-native-nitro-modules`).
-
-### **1. Install Dependencies**
-
-**npm**
-
-```bash
-npm install react-native-nitro-markdown react-native-nitro-modules
-```
-
-> **Note:** If you want to use **Math** (LaTeX) or certain **Image** features, you should also install the optional peer dependencies:
-> `npm install react-native-svg react-native-mathjax-svg`
-
-**Yarn**
-
-```bash
-yarn add react-native-nitro-markdown react-native-nitro-modules
-```
-
-**Bun**
+### React Native
 
 ```bash
 bun add react-native-nitro-markdown react-native-nitro-modules
 ```
 
-**pnpm**
+Optional math support:
 
 ```bash
-pnpm add react-native-nitro-markdown react-native-nitro-modules
+bun add react-native-mathjax-svg react-native-svg
 ```
 
-### **2. Install Native Pods (iOS)**
-
-**Standard**
+iOS pods:
 
 ```bash
 cd ios && pod install
 ```
 
-### **3. Expo Users**
-
-If you are using Expo, you must run a **Prebuild** (Development Build) because this package contains native C++ code.
+### Expo (development build)
 
 ```bash
 bunx expo install react-native-nitro-markdown react-native-nitro-modules
 bunx expo prebuild
 ```
 
----
-
-## 💻 Usage
+Optional math support:
 
-### Option 1: Batteries Included (Simplest)
+```bash
+bunx expo install react-native-mathjax-svg react-native-svg
+```
 
-Use the `Markdown` component with clean, neutral styling that stays out of the way:
+## Quick Start
 
 ```tsx
 import { Markdown } from "react-native-nitro-markdown";
 
-export function MyComponent() {
+export function Example() {
   return (
     <Markdown options={{ gfm: true }}>
-      {"# Hello World\nThis is **bold** text."}
+      {"# Hello\nThis is **native** markdown."}
     </Markdown>
   );
 }
 ```
 
-If you're rendering on a dark surface, override `theme.colors.text` (or use the `styles` prop) to match your app's palette.
-
-### Option 2: Style Overrides per Node Type
-
-Apply quick style overrides to specific node types without writing custom renderers:
+## Package Exports
+
+### Main Entry (`react-native-nitro-markdown`)
+
+- Parser and headless helpers:
+  - `parseMarkdown`
+  - `parseMarkdownWithOptions`
+  - `getTextContent`
+  - `getFlattenedText`
+  - `MarkdownParserModule`
+- Components:
+  - `Markdown`
+  - `MarkdownStream`
+- Hooks and sessions:
+  - `useMarkdownSession`
+  - `useStream`
+  - `createMarkdownSession`
+- Context:
+  - `MarkdownContext`
+  - `useMarkdownContext`
+- Theme:
+  - `defaultMarkdownTheme`
+  - `minimalMarkdownTheme`
+  - `mergeThemes`
+- Built-in renderers:
+  - `Heading`, `Paragraph`, `Link`, `Blockquote`, `HorizontalRule`
+  - `CodeBlock`, `InlineCode`
+  - `List`, `ListItem`, `TaskListItem`
+  - `TableRenderer`, `Image`, `MathInline`, `MathBlock`
+- Types:
+  - `MarkdownNode`, `ParserOptions`, `MarkdownParser`
+  - `CustomRenderers`, `CustomRenderer`, `CustomRendererProps`
+  - `NodeRendererProps`, `BaseCustomRendererProps`, `EnhancedRendererProps`
+  - `HeadingRendererProps`, `LinkRendererProps`, `ImageRendererProps`
+  - `CodeBlockRendererProps`, `InlineCodeRendererProps`
+  - `ListRendererProps`, `TaskListItemRendererProps`
+  - `LinkPressHandler`, `MarkdownContextValue`
+  - `MarkdownTheme`, `PartialMarkdownTheme`, `NodeStyleOverrides`, `StylingStrategy`
+  - `MarkdownSession`
+
+### Headless Entry (`react-native-nitro-markdown/headless`)
+
+Exports only parser-related API (`parseMarkdown`, `parseMarkdownWithOptions`, `getTextContent`, `getFlattenedText`, types). Use this when you do not need built-in UI rendering.
+
+## Component API
+
+## `Markdown`
 
 ```tsx
-<Markdown
-  styles={{
-    heading: { color: "#0ea5e9", fontWeight: "900" },
-    code_block: { backgroundColor: "#e2e8f0", borderRadius: 16 },
-    blockquote: { borderLeftColor: "#0ea5e9" },
-  }}
->
-  {markdown}
-</Markdown>
+import { Markdown } from "react-native-nitro-markdown";
 ```
 
-### Option 3: Custom Renderers
-
-Override specific node types with full control. Custom renderers receive **pre-mapped props** for common values:
+| Prop                  | Type                   | Default                                          | Description                                                                               |
+| --------------------- | ---------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------- | -------------------- |
+| `children`            | `string`               | required                                         | Markdown input string.                                                                    |
+| `options`             | `ParserOptions`        | `undefined`                                      | Parser flags (`gfm`, `math`).                                                             |
+| `renderers`           | `CustomRenderers`      | `{}`                                             | Per-node custom renderers.                                                                |
+| `theme`               | `PartialMarkdownTheme` | `defaultMarkdownTheme` or `minimalMarkdownTheme` | Theme token overrides.                                                                    |
+| `styles`              | `NodeStyleOverrides`   | `undefined`                                      | Per-node style overrides.                                                                 |
+| `stylingStrategy`     | `"opinionated"         | "minimal"`                                       | `"opinionated"`                                                                           | Base styling preset. |
+| `style`               | `StyleProp<ViewStyle>` | `undefined`                                      | Container style for the root `View`.                                                      |
+| `onParsingInProgress` | `() => void`           | `undefined`                                      | Called when parse inputs change.                                                          |
+| `onParseComplete`     | `(result) => void`     | `undefined`                                      | Called with `{ raw, ast, text }` after successful parse.                                  |
+| `onLinkPress`         | `LinkPressHandler`     | `undefined`                                      | Intercepts link press before default open behavior. Return `false` to block default open. |
 
-```tsx
-import {
-  Markdown,
-  CodeBlock,
-  type HeadingRendererProps,
-  type CodeBlockRendererProps,
-} from "react-native-nitro-markdown";
+Notes:
 
-const renderers = {
-  // Pre-mapped `level` prop - no need for node.level!
-  heading: ({ level, children }: HeadingRendererProps) => (
-    <MyHeading level={level}>{children}</MyHeading>
-  ),
+- Parse failures are caught and rendered as a fallback message (`Error parsing markdown`).
+- `text` in `onParseComplete` is produced by `getFlattenedText(ast)`.
 
-  // Pre-mapped `content` and `language` - no getTextContent() needed!
-  code_block: ({ content, language }: CodeBlockRendererProps) => (
-    <CodeBlock
-      content={content}
-      language={language}
-      style={{ borderWidth: 2 }}
-    />
-  ),
-};
+## `MarkdownStream`
 
-<Markdown renderers={renderers} options={{ gfm: true }}>
-  {markdown}
-</Markdown>;
+```tsx
+import { MarkdownStream } from "react-native-nitro-markdown";
 ```
 
-**Pre-mapped Props by Node Type:**
-
-- `heading` → `level` (1-6)
-- `link` → `href`, `title`
-- `image` → `url`, `alt`, `title`
-- `code_block` → `content`, `language`
-- `code_inline` → `content`
-- `list` → `ordered`, `start`
-- `task_list_item` → `checked`
+`MarkdownStreamProps` extends `MarkdownProps` except `children`.
 
-### Option 4: Token Overrides (Theme)
+| Prop                   | Type              | Default  | Description                                        |
+| ---------------------- | ----------------- | -------- | -------------------------------------------------- | --------------------------------------------------------- |
+| `session`              | `MarkdownSession` | required | Session object that supplies streamed text chunks. |
+| `updateIntervalMs`     | `number`          | `50`     | Flush interval when `updateStrategy="interval"`.   |
+| `updateStrategy`       | `"interval"       | "raf"`   | `"interval"`                                       | Update cadence (`setTimeout` vs `requestAnimationFrame`). |
+| `useTransitionUpdates` | `boolean`         | `false`  | Applies `startTransition` to streamed UI updates.  |
 
-Customize the look and feel by passing a partial `theme` object:
+### Streaming Example
 
 ```tsx
-import { Markdown } from "react-native-nitro-markdown";
-
-const myTheme = {
-  colors: {
-    text: "#0f172a",
-    heading: "#0f172a",
-    link: "#0ea5e9",
-    codeBackground: "#e2e8f0",
-  },
-  showCodeLanguage: false,
-};
+import { useEffect } from "react";
+import {
+  MarkdownStream,
+  useMarkdownSession,
+} from "react-native-nitro-markdown";
 
-<Markdown theme={myTheme}>{"# Custom Themed Markdown"}</Markdown>;
-```
+export function StreamingExample() {
+  const session = useMarkdownSession();
 
-Defaults live in `defaultMarkdownTheme` and are intentionally neutral so you can layer your own palette on top.
+  useEffect(() => {
+    const s = session.getSession();
+    s.append("# Streaming\n");
+    s.append("This text arrives in chunks.");
 
-**Theme Properties:**
+    return () => session.clear();
+  }, [session]);
 
-- `colors` - All color tokens (text, heading, link, code, codeBackground, codeLanguage, etc.)
-- `spacing` - Spacing tokens (xs, s, m, l, xl)
-- `fontSizes` - Font sizes (xs, s, m, l, xl, h1-h6)
-- `fontFamilies` - Font families for regular, heading, and mono text
-- `headingWeight` - Optional weight for headings (useful for Android custom fonts)
-- `borderRadius` - Border radius tokens (s, m, l)
-- `showCodeLanguage` - Show/hide code block language labels
+  return (
+    <MarkdownStream
+      session={session.getSession()}
+      options={{ gfm: true }}
+      updateStrategy="raf"
+      useTransitionUpdates
+    />
+  );
+}
+```
 
-**Android custom fonts note:**
-If you use a custom heading font on Android and don’t load a bold variant, set
-`headingWeight: "normal"` (or use the `styles` prop) to avoid fallback to a
-system serif font.
+## Hooks and Session API
 
-### Option 5: Minimal Styling Strategy
+## `createMarkdownSession()`
 
-Start with a clean slate using the `stylingStrategy` prop:
+Creates and returns a native `MarkdownSession` instance.
 
 ```tsx
-<Markdown stylingStrategy="minimal" theme={myLightTheme}>
-  {content}
-</Markdown>
+import { createMarkdownSession } from "react-native-nitro-markdown";
+
+const session = createMarkdownSession();
+session.append("hello");
 ```
 
-This zeros out all spacing and removes opinionated colors, letting you build up from scratch.
+## `useMarkdownSession()`
 
-### Option 6: Style Props on Individual Renderers
+Creates and owns one `MarkdownSession` for a component lifecycle.
 
-All built-in renderers accept a `style` prop for fine-grained overrides:
+Returns:
 
-```tsx
-import { Heading, CodeBlock, InlineCode } from "react-native-nitro-markdown";
+| Field            | Type                         | Description                                                   |
+| ---------------- | ---------------------------- | ------------------------------------------------------------- |
+| `getSession`     | `() => MarkdownSession`      | Returns the stable native session instance.                   |
+| `isStreaming`    | `boolean`                    | Stateful flag for app-level streaming UI.                     |
+| `setIsStreaming` | `(value: boolean) => void`   | Setter for `isStreaming`.                                     |
+| `stop`           | `() => void`                 | Sets `isStreaming` to `false`.                                |
+| `clear`          | `() => void`                 | Clears session content and resets `highlightPosition` to `0`. |
+| `setHighlight`   | `(position: number) => void` | Sets `session.highlightPosition`.                             |
 
-// Works in custom renderers
-<Heading level={1} style={{ color: "hotpink" }}>Title</Heading>
-<CodeBlock content={code} style={{ borderRadius: 0 }} />
-<InlineCode style={{ backgroundColor: "#ff0" }}>code</InlineCode>
-```
+## `useStream(timestamps?)`
 
-### Option 7: Auto Content Extraction for Code
+Builds on `useMarkdownSession` and adds timeline sync helpers.
 
-The `CodeBlock` and `InlineCode` components now accept a `node` prop for automatic content extraction:
+- `timestamps` type: `Record<number, number>` where key = word/token index, value = timestamp in ms.
+- `sync(currentTimeMs)` computes highlight position from timestamp map.
+- Uses optimized lookup for monotonic timelines and handles non-monotonic maps safely.
 
-```tsx
-// Before: Manual extraction required
-code_block: ({ node }) => (
-  <CodeBlock content={getTextContent(node)} language={node.language} />
-);
-
-// After: Just pass the node
-code_block: ({ node }) => <CodeBlock node={node} />;
-
-// Or use the pre-mapped content prop (recommended)
-code_block: ({ content, language }) => (
-  <CodeBlock content={content} language={language} />
-);
-```
+Additional returned fields:
 
-### Option 8: Headless (Minimal Bundle)
+| Field          | Type                              | Description                               |
+| -------------- | --------------------------------- | ----------------------------------------- |
+| `isPlaying`    | `boolean`                         | Playback state for timed streaming.       |
+| `setIsPlaying` | `(value: boolean) => void`        | Setter for `isPlaying`.                   |
+| `sync`         | `(currentTimeMs: number) => void` | Applies timeline-based highlight updates. |
 
-For maximum control, data processing, or minimal JS overhead:
+## Headless API
 
 ```tsx
 import {
   parseMarkdown,
+  parseMarkdownWithOptions,
   getTextContent,
   getFlattenedText,
 } from "react-native-nitro-markdown/headless";
-
-const ast = parseMarkdown("# Hello World");
-const text = getTextContent(ast); // "Hello World"
-const fullText = getFlattenedText(ast); // "Hello World\n\n" (Normalized with line breaks)
 ```
 
-### Option 9: High-Performance Streaming (LLMs)
+| Function                   | Signature                                                | Description                                                        |
+| -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------ |
+| `parseMarkdown`            | `(text: string) => MarkdownNode`                         | Parses markdown using default parser settings.                     |
+| `parseMarkdownWithOptions` | `(text: string, options: ParserOptions) => MarkdownNode` | Parses markdown with `gfm` and/or `math` flags.                    |
+| `getTextContent`           | `(node: MarkdownNode) => string`                         | Concatenates text recursively without layout normalization.        |
+| `getFlattenedText`         | `(node: MarkdownNode) => string`                         | Returns normalized plain text with paragraph and block separators. |
 
-When streaming text token-by-token (e.g., from ChatGPT or Gemini), you should batch UI updates to avoid re-rendering on every token:
+### Parser Options
 
-```tsx
-import {
-  MarkdownStream,
-  useMarkdownSession,
-} from "react-native-nitro-markdown";
+```ts
+type ParserOptions = {
+  gfm?: boolean;
+  math?: boolean;
+};
+```
 
-export function AIResponseStream() {
-  const session = useMarkdownSession();
+## Custom Renderer API
 
-  useEffect(() => {
-    session.getSession().append("Hello **Nitro**!");
-    return () => session.clear();
-  }, [session]);
+## `renderers` prop contract
 
-  return (
-    <MarkdownStream
-      session={session.getSession()}
-      options={{ gfm: true }}
-      updateIntervalMs={60}
-      updateStrategy="raf"
-      useTransitionUpdates
-    />
-  );
-}
+`CustomRenderers` is:
+
+```ts
+type CustomRenderers = Partial<Record<MarkdownNode["type"], CustomRenderer>>;
 ```
 
-**Recommended defaults for token streaming:**
-- `updateStrategy="raf"` for smooth, frame-aligned updates
-- `updateIntervalMs={50–100}` when using `updateStrategy="interval"`
-- Avoid per-token UI updates by batching token appends
+`CustomRenderer` receives `EnhancedRendererProps` and returns:
 
-**Streaming props:**
+- React node to override default rendering
+- `undefined` to fallback to built-in renderer
+- `null` to render nothing
 
-| Prop | Type | Default | Description |
-| :-- | :-- | :-- | :-- |
-| `updateIntervalMs` | `number` | `50` | Throttle UI updates when using interval strategy |
-| `updateStrategy` | `"interval" \| "raf"` | `"interval"` | Interval batching or frame-aligned updates |
-| `useTransitionUpdates` | `boolean` | `false` | Use React transitions to keep input responsive |
+`EnhancedRendererProps` always includes:
 
-### Option 10: Extracting Plain Text
+- `node`: current `MarkdownNode`
+- `children`: pre-rendered node children
+- `Renderer`: recursive renderer component for nested custom rendering
 
-You can extract the plain text representation (with proper line breaks) using the `onParseComplete` callback. This is useful for "Copy All" buttons or TTS.
+And conditionally includes mapped fields by node type:
 
-```tsx
-<Markdown
-  onParseComplete={(result) => {
-    console.log(result.text); // "Hello World\n\nThis is bold text."
-    console.log(result.ast); // Full AST
-  }}
->
-  {markdown}
-</Markdown>
-```
-
----
-
-## 🎨 Using Context in Custom Renderers
+| Node type        | Extra mapped fields   |
+| ---------------- | --------------------- |
+| `heading`        | `level`               |
+| `link`           | `href`, `title`       |
+| `image`          | `url`, `alt`, `title` |
+| `code_block`     | `content`, `language` |
+| `code_inline`    | `content`             |
+| `list`           | `ordered`, `start`    |
+| `task_list_item` | `checked`             |
 
-Access theme and context in custom renderers:
+### Example: Custom heading + code block
 
 ```tsx
 import {
-  useMarkdownContext,
-  MarkdownContext,
+  Markdown,
+  type HeadingRendererProps,
+  type CodeBlockRendererProps,
 } from "react-native-nitro-markdown";
 
-const MyCustomRenderer = ({ children }) => {
-  const { theme, stylingStrategy } = useMarkdownContext();
-
-  return <View style={{ padding: theme.spacing.m }}>{children}</View>;
+const renderers = {
+  heading: ({ level, children }: HeadingRendererProps) => (
+    <MyHeading level={level}>{children}</MyHeading>
+  ),
+  code_block: ({ language, content }: CodeBlockRendererProps) => (
+    <MyCode language={language} content={content} />
+  ),
 };
+
+<Markdown renderers={renderers}>{content}</Markdown>;
 ```
 
----
+## Link Handling Behavior
 
-## 🛠️ Exported Utilities
+Default link renderer behavior:
 
-```tsx
-// Parser and utilities
-export {
-  parseMarkdown,
-  parseMarkdownWithOptions,
-  getTextContent,
-  getFlattenedText,
-} from "./headless";
+1. Trims incoming href.
+2. Calls `onLinkPress(href)` if provided.
+3. Stops if handler returns `false`.
+4. Allows only protocol-based links with these schemes:
+   - `http:`
+   - `https:`
+   - `mailto:`
+   - `tel:`
+   - `sms:`
+5. Uses `Linking.canOpenURL` before `Linking.openURL`.
 
-// Theme tokens
-export {
-  defaultMarkdownTheme,
-  minimalMarkdownTheme,
-  mergeThemes,
-};
+Relative URLs and anchors are ignored by default open behavior, but you can handle them in `onLinkPress`.
 
-// Context
-export { useMarkdownContext, MarkdownContext };
-
-// Individual renderers
-export {
-  Heading,
-  Paragraph,
-  Link,
-  Blockquote,
-  HorizontalRule,
-  CodeBlock,
-  InlineCode,
-  List,
-  ListItem,
-  TaskListItem,
-  TableRenderer,
-  Image,
-  MathInline,
-  MathBlock,
-};
-```
+## Theme API
 
----
+## `MarkdownTheme`
 
-## 🛠️ Headless vs. Non-Headless
+```tsx
+import type {
+  MarkdownTheme,
+  PartialMarkdownTheme,
+} from "react-native-nitro-markdown";
+```
 
-| Feature         | **Headless** (`/headless`)  | **Non-Headless** (`default`)       |
-| :-------------- | :-------------------------- | :--------------------------------- |
-| **Logic**       | Raw C++ md4c Parser         | Parser + Full UI Renderer          |
-| **Output**      | JSON AST Tree               | React Native Views                 |
-| **Best For**    | Search Indexing, Custom UIs | Fast Implementation, Documentation |
-| **JS Overhead** | ~4 KB                       | ~60 KB                             |
+`MarkdownTheme` fields:
 
----
+- `colors`
+  - `text`, `textMuted`, `heading`, `link`, `code`, `codeBackground`, `codeLanguage`
+  - `blockquote`, `border`, `surface`, `surfaceLight`, `accent`
+  - `tableBorder`, `tableHeader`, `tableHeaderText`, `tableRowEven`, `tableRowOdd`
+- `spacing`: `xs`, `s`, `m`, `l`, `xl`
+- `fontSizes`: `xs`, `s`, `m`, `l`, `xl`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`
+- `fontFamilies`: `regular`, `heading`, `mono`
+- `headingWeight?`
+- `borderRadius`: `s`, `m`, `l`
+- `showCodeLanguage`
 
-### Basic Parsing API
+Helpers:
 
-The parsing is synchronous and instant. It returns a fully typed JSON AST:
+- `defaultMarkdownTheme`
+- `minimalMarkdownTheme`
+- `mergeThemes(base, partial)`
 
-```typescript
-import { parseMarkdown } from "react-native-nitro-markdown/headless";
+`NodeStyleOverrides` lets you override per-node styles:
 
-const ast = parseMarkdown(`
-# Hello World
-This is **bold** text and a [link](https://github.com).
-`);
+```ts
+type NodeStyleOverrides = Partial<
+  Record<MarkdownNode["type"], ViewStyle | TextStyle>
+>;
 ```
 
-### Options
+## Built-in Renderer Components
 
-| Option | Type      | Default | Description                                                                    |
-| :----- | :-------- | :------ | :----------------------------------------------------------------------------- |
-| `gfm`  | `boolean` | `false` | Enable GitHub Flavored Markdown (Tables, Strikethrough, Autolinks, TaskLists). |
-| `math` | `boolean` | `false` | Enable LaTeX Math support (`$` and `$$`).                                      |
+Use these when composing custom renderer maps.
 
----
+| Component        | Key props                                        |
+| ---------------- | ------------------------------------------------ |
+| `Heading`        | `level`, `children`, `style`                     |
+| `Paragraph`      | `children`, `inListItem`, `style`                |
+| `Link`           | `href`, `children`, `style`                      |
+| `Blockquote`     | `children`, `style`                              |
+| `HorizontalRule` | `style`                                          |
+| `CodeBlock`      | `language`, `content`, `node`, `style`           |
+| `InlineCode`     | `content`, `node`, `children`, `style`           |
+| `List`           | `ordered`, `start`, `depth`, `children`, `style` |
+| `ListItem`       | `children`, `index`, `ordered`, `start`, `style` |
+| `TaskListItem`   | `children`, `checked`, `style`                   |
+| `TableRenderer`  | `node`, `Renderer`, `style`                      |
+| `Image`          | `url`, `title`, `alt`, `Renderer`, `style`       |
+| `MathInline`     | `content`, `style`                               |
+| `MathBlock`      | `content`, `style`                               |
 
-## 📐 AST Structure
+## Supported AST Node Types
 
-The parser returns a `MarkdownNode` tree:
+`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`
 
-```typescript
-export interface MarkdownNode {
-  type: NodeType;
-  content?: string;
-  children?: MarkdownNode[];
-  level?: number;
-  href?: string;
-  checked?: boolean;
-  language?: string;
-  align?: "left" | "center" | "right";
-  isHeader?: boolean;
-}
-```
+Notes:
+
+- `html_inline` and `html_block` are parsed but not rendered by default.
+- Table internals (`table_head`, `table_body`, `table_row`, `table_cell`) are renderer internals; override `table` for custom table UI.
+
+## Recipes
 
----
+### Intercept links with `onLinkPress`
 
-## 🧮 LaTeX Math Support
+```tsx
+import { Markdown } from "react-native-nitro-markdown";
 
-We parse math delimiters (`$` and `$$`) natively using the `MD_FLAG_LATEXMATHSPANS` flag in `md4c`.
+<Markdown
+  onLinkPress={(href) => {
+    if (href.startsWith("/")) {
+      router.push(href);
+      return false;
+    }
+  }}
+>
+  {content}
+</Markdown>;
+```
 
-To render the math, use a library like `react-native-mathjax-svg`:
+### Use headless mode to build search index
 
 ```tsx
-case 'math_inline':
-  return <MathView math={node.content} style={styles.math} />;
-case 'math_block':
-  return <MathView math={node.content} style={styles.mathBlock} />;
+import {
+  parseMarkdown,
+  getFlattenedText,
+} from "react-native-nitro-markdown/headless";
+
+const ast = parseMarkdown(content);
+const searchableText = getFlattenedText(ast);
 ```
 
----
+### Minimal styling baseline
+
+```tsx
+import { Markdown } from "react-native-nitro-markdown";
 
-## 📊 Package Size
+<Markdown
+  stylingStrategy="minimal"
+  theme={{
+    colors: {
+      text: "#0f172a",
+      link: "#1d4ed8",
+    },
+  }}
+>
+  {content}
+</Markdown>;
+```
 
-| Metric               | Size    |
-| :------------------- | :------ |
-| **Packed (tarball)** | ~75 kB  |
-| **Unpacked**         | ~325 kB |
-| **Total files**      | 55      |
+## Performance Guidance
 
----
+- For streaming text, prefer `updateStrategy="raf"`.
+- If you use interval strategy, `updateIntervalMs` between `50` and `100` is a good baseline.
+- Batch `session.append(...)` calls instead of appending one character at a time.
+- Use the headless API if you do not need built-in renderers.
 
-## 🤝 Contributing
+## Troubleshooting
 
-See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
+- Math appears as plain code-style fallback:
+  - Install `react-native-mathjax-svg` and `react-native-svg`.
+- iOS native build issues after install:
+  - Run `pod install` in your iOS project.
+- Expo app does not load native module:
+  - Use a development build (`expo prebuild` + `expo run`), not Expo Go.
+- Android heading font weight looks wrong:
+  - Set `theme.headingWeight` explicitly (for custom fonts without bold variants, use `"normal"`).
 
-## 📄 License
+## Contributing
 
-MIT
+See `/Users/jota/Workspace/Projects/RN-Packages/react-native-nitro-markdown/CONTRIBUTING.md`.
 
----
+## License
 
-Built with ❤️ using [Nitro Modules](https://nitro.margelo.com) and [md4c](https://github.com/mity/md4c).
+MIT