react-native-nitro-markdown 0.4.2 → 0.5.0

package/README.md

@@ -1,58 +1,40 @@
 <p align="center">
-  <img src="./readme/demo.gif" alt="react-native-nitro-markdown demo" width="300" />
-  <img src="./readme/stream-demo.gif" alt="react-native-nitro-markdown stream demo" width="300" />
+  <img src="./readme/demo.gif" alt="react-native-nitro-markdown demo" width="400" />
 </p>
 
 # react-native-nitro-markdown
 
-Fast, native Markdown parsing and rendering for React Native. Built on md4c (C++) and Nitro Modules (JSI), it turns Markdown into a typed AST synchronously and renders it with a batteries-included React Native renderer.
+Native Markdown parsing and rendering for React Native.
 
----
+`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.
 
-## Why this package exists
+## Why use it
 
-JavaScript Markdown parsers do a lot of work on the JS thread and often trigger GC pauses on large documents. This package moves parsing to native C++ and uses JSI to return the AST without going through the RN bridge.
-
-**How it works:**
-
-Markdown string -> md4c C++ parser -> JSON AST -> React Native renderers
-
----
-
-## Features
-
-- Native C++ parser with JSI access (fast, synchronous parsing)
-- Full renderer included (Markdown component)
-- Headless API for custom renderers or processing
+- 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)
-- LaTeX math parsing (inline and block)
-- Streaming support for token-by-token updates
-- Theming and per-node style overrides
-- Built-in renderers exposed for reuse
-
----
+- Optional math rendering with `react-native-mathjax-svg`
 
 ## Requirements
 
-- React Native >= 0.75
-- react-native-nitro-modules
-
-Optional (for math rendering):
+- React Native `>=0.75.0`
+- `react-native-nitro-modules`
 
-- react-native-mathjax-svg
-- react-native-svg
+Optional for math rendering:
 
----
+- `react-native-mathjax-svg >=0.9.0`
+- `react-native-svg >=13.0.0`
 
 ## Installation
 
-Install the package and Nitro Modules:
+### React Native
 
 ```bash
 bun add react-native-nitro-markdown react-native-nitro-modules
 ```
 
-Optional math dependencies:
+Optional math support:
 
 ```bash
 bun add react-native-mathjax-svg react-native-svg
@@ -64,168 +46,333 @@ iOS pods:
 cd ios && pod install
 ```
 
-Expo (requires a development build):
+### Expo (development build)
 
 ```bash
 bunx expo install react-native-nitro-markdown react-native-nitro-modules
 bunx expo prebuild
 ```
 
----
+Optional math support:
+
+```bash
+bunx expo install react-native-mathjax-svg react-native-svg
+```
 
 ## 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>
   );
 }
 ```
 
----
-
-## Feature Guide
+## Demo App Tour
+
+The example app in `apps/example` now maps each major feature to a screen:
+
+- `Bench` (`app/index.tsx`)
+  - Nitro benchmark + JS parser comparisons
+- `Default` (`app/render-default.tsx`)
+  - Built-in renderer defaults
+- `Styles` (`app/render-default-styles.tsx`)
+  - `styles` prop and theme token overrides
+- `Custom` (`app/render-custom.tsx`)
+  - `renderers` overrides + `astTransform`
+- `Stream` (`app/render-stream.tsx`)
+  - streaming UX with live token append
+
+## Runtime API Coverage (Demo + Docs)
+
+This table maps each runtime API to where it is demonstrated.
+
+| API | Purpose | Demo usage |
+| --- | --- | --- |
+| `Markdown` | Parse + render markdown component | `apps/example/app/render-default.tsx` |
+| `Markdown` `options` | Enable parser flags (`gfm`, `math`) | `apps/example/app/render-default.tsx` |
+| `Markdown` `styles` | Per-node style overrides | `apps/example/app/render-default-styles.tsx` |
+| `Markdown` `renderers` | Custom node renderer overrides | `apps/example/app/render-custom.tsx` |
+| `Markdown` `astTransform` | Post-parse AST transform hook | `apps/example/app/render-custom.tsx` |
+| `Markdown` `virtualize` / `virtualization*` | Large-document block virtualization | README examples |
+| `MarkdownStream` | Stream rendering from session text | `apps/example/app/render-stream.tsx` |
+| `useMarkdownSession` | Own and reuse a native markdown session | `apps/example/app/render-stream.tsx` |
+| `createMarkdownSession` | Create a manual session instance | README examples |
+| `useStream` | Timed playback sync + highlighting | README examples |
+| `parseMarkdown` | Headless parse/benchmark pipeline | `apps/example/app/index.tsx` |
+| `parseMarkdownWithOptions` | Headless parse with parser flags | README examples |
+| `getTextContent` | Extract raw text from AST subtree | README examples |
+| `getFlattenedText` | Normalize AST text for indexing/search | README examples |
+| `MarkdownParserModule` | Low-level Nitro parser access | README examples |
+| `mergeThemes` / `defaultMarkdownTheme` / `minimalMarkdownTheme` | Theme composition and style presets | `apps/example/app/render-default-styles.tsx` + README examples |
+| `useMarkdownContext` / `MarkdownContext` | Access theme/renderer/link handlers inside custom trees | README examples |
+| Built-in renderer components (`CodeBlock`, `TableRenderer`, etc.) | Compose renderer overrides with built-ins | `apps/example/app/render-custom.tsx` |
+| `onLinkPress`, `onParsingInProgress`, `onParseComplete`, `plugins`, `sourceAst` | Advanced lifecycle/link/pipeline control | README examples |
+
+## Feature Index
+
+Use this table as a quick map from feature -> API -> demo usage.
+
+| Feature                  | API                                                 | What it does                                              | Demo                                  |
+| ------------------------ | --------------------------------------------------- | --------------------------------------------------------- | ------------------------------------- |
+| Basic markdown rendering | `Markdown`                                          | Parse and render markdown in one component                | `app/render-default.tsx`              |
+| Parser flags             | `options` (`gfm`, `math`)                           | Enable GFM and math parsing                               | `app/render-default.tsx`              |
+| Plugin pipeline          | `plugins` (`beforeParse`, `afterParse`)             | Rewrite markdown input or AST around parse                | README examples                       |
+| AST transform            | `astTransform`                                      | Post-parse AST rewrite before render                      | `app/render-custom.tsx`               |
+| Pre-parsed AST render    | `sourceAst`                                         | Skip parsing during render and render existing AST        | README examples                       |
+| Parse lifecycle          | `onParsingInProgress`, `onParseComplete`            | Observe parse start/finish and consume normalized text    | README examples                       |
+| Link interception        | `onLinkPress`                                       | Override default URL open behavior                        | README examples                       |
+| Large doc virtualization | `virtualize`, `virtualizationMinBlocks`             | Virtualizes top-level blocks for very large markdown docs | README examples                       |
+| Streaming markdown       | `MarkdownStream` + `createMarkdownSession`          | Render incrementally appended markdown content            | `app/render-stream.tsx`               |
+| Timed highlight sync     | `useStream(timestamps)`                             | Sync highlight position to playback timeline              | README examples                       |
+| Headless parsing         | `parseMarkdown`, `parseMarkdownWithOptions`         | Parse markdown without built-in UI                        | `app/index.tsx` + README examples     |
+| Custom node rendering    | `renderers` + built-in renderer components          | Replace specific node UI while preserving parser behavior | `app/render-custom.tsx`               |
+| Styling and theme        | `theme`, `styles`, `stylingStrategy`, `mergeThemes` | Control visual tokens and per-node styles                 | `app/render-default-styles.tsx`       |
+| Low-level parser access  | `MarkdownParserModule`                              | Direct access to Nitro parser methods                     | README examples                       |
+
+## 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`
+  - `MarkdownProps`, `AstTransform`, `MarkdownPlugin`, `MarkdownStreamProps`, `MarkdownVirtualizationOptions`
+  - `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`, `extractPlainText`, `extractPlainTextWithOptions`, `getTextContent`, `getFlattenedText`, types). Use this when you do not need built-in UI rendering.
+
+## Component API
+
+## `Markdown`
 
-Start here (pick the approach that matches your use case):
-
-- `Markdown` for static or preloaded content
-- `MarkdownStream` + `useMarkdownSession` for streaming tokens
-- `headless` API for custom rendering or data processing
-
-### 1) Parsing options (GFM and Math)
+```tsx
+import { Markdown } from "react-native-nitro-markdown";
+```
 
-Parsing options are passed using the `options` prop.
+Demo usage:
+
+- `apps/example/app/render-default.tsx`
+- `apps/example/app/render-default-styles.tsx`
+- `apps/example/app/render-custom.tsx`
+
+| Prop                  | Type                         | Default                                          | Description                                                                               |
+| --------------------- | ---------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| `children`            | `string`                     | required                                         | Markdown input string.                                                                    |
+| `options`             | `ParserOptions`              | `undefined`                                      | Parser flags (`gfm`, `math`).                                                             |
+| `plugins`             | `MarkdownPlugin[]`           | `undefined`                                      | Optional parser plugin hooks (`beforeParse`, `afterParse`).                               |
+| `sourceAst`           | `MarkdownNode`               | `undefined`                                      | Pre-parsed AST. When provided, native parse is skipped.                                   |
+| `astTransform`        | `AstTransform`               | `undefined`                                      | Transform hook applied after plugins, before rendering and `onParseComplete`.             |
+| `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. |
+| `virtualize`          | `boolean \| "auto"`          | `false`                                          | Enables top-level block virtualization. Use `"auto"` to activate by block threshold.       |
+| `virtualizationMinBlocks` | `number`                 | `40`                                             | Minimum top-level block count before virtualization activates.                             |
+| `virtualization`      | `MarkdownVirtualizationOptions` | `undefined`                                   | Optional FlatList tuning (`windowSize`, `initialNumToRender`, batching, clipping).        |
+
+Notes:
+
+- Parse failures are caught and rendered as a fallback message (`Error parsing markdown`).
+- `text` in `onParseComplete` is produced by `getFlattenedText(ast)`.
+- `astTransform` should be wrapped with `useCallback` to avoid unnecessary re-parses.
+- `astTransform` is a post-parse AST rewrite hook. It does not add parser syntax support and is not a markdown-it plugin API.
+- Plugin pipeline order is: `beforeParse` -> parse/sourceAst -> `afterParse` -> `astTransform` -> render.
+- Tables render immediately with estimated column widths, then refine widths after layout measurement to improve reliability on slower layout cycles.
+- For very large markdown content, enable `virtualize` to avoid mounting all top-level blocks at once.
+- `virtualize="auto"` enables threshold-driven virtualization while keeping small markdown renders on plain `View` trees.
+
+### Virtualization example (large docs)
 
 ```tsx
-<Markdown options={{ gfm: true, math: true }}>{content}</Markdown>
+<Markdown
+  virtualize="auto"
+  virtualizationMinBlocks={30}
+  virtualization={{
+    initialNumToRender: 10,
+    maxToRenderPerBatch: 10,
+    windowSize: 8,
+    updateCellsBatchingPeriod: 16,
+    removeClippedSubviews: true,
+  }}
+>
+  {content}
+</Markdown>
 ```
 
-- `gfm` enables GitHub Flavored Markdown features supported by md4c.
-- `math` enables `$...$` and `$$...$$` parsing into math nodes.
+Virtualization notes:
 
-### 2) Styling and themes
+- Keep `Markdown` as the primary vertical scroller when `virtualize` is enabled.
+- Avoid nesting it inside another vertical `ScrollView`, or virtualization effectiveness drops.
 
-You can override tokens using the `theme` prop. Only provide the tokens you want to change.
+### AST transform example
 
 ```tsx
-import { Markdown } from "react-native-nitro-markdown";
-
-const theme = {
-  colors: {
-    text: "#0f172a",
-    heading: "#0f172a",
-    link: "#2563eb",
-    codeBackground: "#f1f5f9",
-  },
-  showCodeLanguage: true,
-};
-
-<Markdown theme={theme}>{content}</Markdown>;
+import { useCallback } from "react";
+import { Markdown, type AstTransform } from "react-native-nitro-markdown";
+
+const astTransform = useCallback<AstTransform>((ast) => {
+  const transformNode = (node: Parameters<AstTransform>[0]) => ({
+    ...node,
+    content:
+      node.type === "text"
+        ? (node.content ?? "").replace(/:wink:/g, "😉")
+        : node.content,
+    children: node.children?.map(transformNode),
+  });
+
+  return transformNode(ast);
+}, []);
+
+<Markdown astTransform={astTransform}>{"Hello :wink:"}</Markdown>;
 ```
 
-If you use a custom heading font on Android and do not load a bold variant, set `headingWeight: "normal"` to avoid font fallback.
+### Plugin pipeline example (`beforeParse` + `afterParse`)
 
-### 3) Per-node style overrides
+```tsx
+import { Markdown, type MarkdownPlugin } from "react-native-nitro-markdown";
 
-Override the styles for specific node types with `styles`.
+const plugins: MarkdownPlugin[] = [
+  {
+    name: "rewrite-before-parse",
+    beforeParse: (input) => input.replace(/:rocket:/g, "ROCKET_TOKEN"),
+  },
+  {
+    name: "rewrite-after-parse",
+    afterParse: (ast) => {
+      const visit = (node: typeof ast): typeof ast => ({
+        ...node,
+        content:
+          node.type === "text"
+            ? (node.content ?? "").replace(/ROCKET_TOKEN/g, "🚀")
+            : node.content,
+        children: node.children?.map(visit),
+      });
+      return visit(ast);
+    },
+  },
+];
 
-```tsx
-<Markdown
-  styles={{
-    heading: { color: "#0ea5e9", fontWeight: "900" },
-    code_block: { backgroundColor: "#e2e8f0", borderRadius: 16 },
-    blockquote: { borderLeftColor: "#0ea5e9" },
-  }}
->
-  {content}
-</Markdown>
+<Markdown plugins={plugins}>{"Launch :rocket:"}</Markdown>;
 ```
 
-### 4) Custom renderers
-
-Provide a custom renderer for any node type. You get pre-mapped props for common values.
+### `sourceAst` example (skip parsing in render)
 
 ```tsx
 import {
   Markdown,
-  CodeBlock,
-  type HeadingRendererProps,
-  type CodeBlockRendererProps,
+  parseMarkdownWithOptions,
 } from "react-native-nitro-markdown";
 
-const renderers = {
-  heading: ({ level, children }: HeadingRendererProps) => (
-    <MyHeading level={level}>{children}</MyHeading>
-  ),
-  code_block: ({ content, language }: CodeBlockRendererProps) => (
-    <CodeBlock content={content} language={language} />
-  ),
-};
+const sourceAst = parseMarkdownWithOptions(content, { gfm: true, math: true });
 
-<Markdown renderers={renderers}>{content}</Markdown>;
+<Markdown sourceAst={sourceAst}>
+  {"children is ignored when sourceAst is provided"}
+</Markdown>;
 ```
 
-Custom renderer behavior:
-
-- Return `undefined` to fall back to the built-in renderer.
-- Return `null` to render nothing for that node.
-- The `Renderer` prop lets you render nested children the same way the default renderer does.
+### Parse lifecycle callbacks example
 
-Pre-mapped props by node type:
-
-| Node type | Extra props |
-| --- | --- |
-| `heading` | `level` |
-| `link` | `href`, `title` |
-| `image` | `url`, `alt`, `title` |
-| `code_block` | `content`, `language` |
-| `code_inline` | `content` |
-| `list` | `ordered`, `start` |
-| `task_list_item` | `checked` |
+```tsx
+import { Markdown } from "react-native-nitro-markdown";
 
-### 5) Built-in renderers
+<Markdown
+  onParsingInProgress={() => setIsParsing(true)}
+  onParseComplete={({ raw, ast, text }) => {
+    setIsParsing(false);
+    setWordCount(text.trim().split(/\s+/).length);
+    setLastRaw(raw);
+    setLastAst(ast);
+  }}
+>
+  {content}
+</Markdown>;
+```
 
-All built-in renderers are exported so you can reuse them in custom renderers.
+## `MarkdownStream`
 
 ```tsx
-import { Heading, CodeBlock, InlineCode } from "react-native-nitro-markdown";
+import { MarkdownStream } from "react-native-nitro-markdown";
 ```
 
-Available renderers:
+`MarkdownStreamProps` extends `MarkdownProps` except `children`.
 
-- `Heading`
-- `Paragraph`
-- `Link`
-- `Blockquote`
-- `HorizontalRule`
-- `CodeBlock`
-- `InlineCode`
-- `List`
-- `ListItem`
-- `TaskListItem`
-- `TableRenderer`
-- `Image`
-- `MathInline`
-- `MathBlock`
+Demo usage:
 
-### 6) Streaming (LLM tokens)
+- `apps/example/app/render-stream.tsx`
 
-Use `MarkdownStream` plus `useMarkdownSession` to stream updates efficiently.
+| 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.                                        |
+| `incrementalParsing`   | `boolean`             | `true`       | Enables append-optimized incremental AST updates (falls back to full parse when unsafe). |
+
+Notes:
+
+- If any plugin defines `beforeParse`, `MarkdownStream` disables incremental AST mode for correctness.
+- `MarkdownStream` consumes native session change ranges (`from`, `to`) and uses `getTextRange()` for contiguous appends to avoid full-buffer copies during token streams.
+
+### Streaming Example
 
 ```tsx
 import { useEffect } from "react";
-import { MarkdownStream, useMarkdownSession } from "react-native-nitro-markdown";
+import {
+  MarkdownStream,
+  useMarkdownSession,
+} from "react-native-nitro-markdown";
 
-export function AIResponseStream() {
+export function StreamingExample() {
   const session = useMarkdownSession();
 
   useEffect(() => {
-    session.getSession().append("Hello **Nitro**!");
+    const s = session.getSession();
+    s.append("# Streaming\n");
+    s.append("This text arrives in chunks.");
+
     return () => session.clear();
   }, [session]);
 
@@ -240,279 +387,419 @@ export function AIResponseStream() {
 }
 ```
 
-Recommended streaming defaults:
-
-- `updateStrategy="raf"` for frame-aligned updates
-- `updateIntervalMs` between `50` and `100` when using interval strategy
-- Avoid per-token UI updates by batching appends
+## Hooks and Session API
 
-### 7) Headless parsing
+## `createMarkdownSession()`
 
-Use the headless entry when you only need the AST or want to build your own renderer.
+Creates and returns a native `MarkdownSession` instance.
 
 ```tsx
-import {
-  parseMarkdown,
-  parseMarkdownWithOptions,
-  getTextContent,
-  getFlattenedText,
-} from "react-native-nitro-markdown/headless";
+import { createMarkdownSession } from "react-native-nitro-markdown";
 
-const ast = parseMarkdown("# Hello World");
-const text = getTextContent(ast);
-const normalized = getFlattenedText(ast);
+const session = createMarkdownSession();
+session.append("hello");
 ```
 
-### 8) Plain text extraction
+`MarkdownSession` methods:
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `append` | `(chunk: string) => number` | Appends text and returns new UTF-16 length. |
+| `clear` | `() => void` | Clears buffer and emits a reset range event (`0, 0`). |
+| `getAllText` | `() => string` | Returns full session text. |
+| `getLength` | `() => number` | Returns current UTF-16 text length without materializing a copy. |
+| `getTextRange` | `(from: number, to: number) => string` | Returns a substring range for delta-driven streaming updates. |
+| `addListener` | `(listener: (from: number, to: number) => void) => () => void` | Subscribes to mutation range events and returns an unsubscribe function. |
+| `highlightPosition` | `number` | Mutable cursor used by stream highlight workflows. |
 
-If you are already using the `Markdown` component, you can get the plain text during parse.
+Demo usage:
+
+- Referenced in `apps/example/app/render-stream.tsx` sample markdown content and used directly in README examples.
+
+Manual session + stream rendering:
 
 ```tsx
-<Markdown
-  onParseComplete={(result) => {
-    console.log(result.text);
-  }}
->
-  {content}
-</Markdown>
+import {
+  createMarkdownSession,
+  MarkdownStream,
+} from "react-native-nitro-markdown";
+
+const session = createMarkdownSession();
+session.append("# Hello\n");
+session.append("Streaming content...");
+
+<MarkdownStream session={session} updateStrategy="raf" />;
 ```
 
-### 9) Tables, images, and math
+## `useMarkdownSession()`
 
-- Tables are rendered with a horizontal scroll view and measured column widths.
-- Images use React Native `Image` and try to preserve the real aspect ratio.
-- Math nodes render with `react-native-mathjax-svg` if installed; otherwise they fall back to a code-style look.
+Creates and owns one `MarkdownSession` for a component lifecycle.
 
----
+Returns:
 
-## Common Recipes
+| 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`.                             |
 
-### Open links with custom behavior
+Demo usage:
 
-```tsx
-import { Markdown, type LinkRendererProps } from "react-native-nitro-markdown";
-import { Text, Linking } from "react-native";
+- `apps/example/app/render-stream.tsx`
 
-const renderers = {
-  link: ({ href, children }: LinkRendererProps) => (
-    <Text
-      style={{ textDecorationLine: "underline" }}
-      onPress={async () => {
-        if (href && (await Linking.canOpenURL(href))) {
-          Linking.openURL(href);
-        }
-      }}
-    >
-      {children}
-    </Text>
-  ),
-};
+## `useStream(timestamps?)`
 
-<Markdown renderers={renderers}>{content}</Markdown>;
-```
+Builds on `useMarkdownSession` and adds timeline sync helpers.
+
+- `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.
+
+Additional returned fields:
+
+| 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. |
 
-### Custom image renderer (placeholder + fixed height)
+Example:
 
 ```tsx
-import { Markdown, type ImageRendererProps } from "react-native-nitro-markdown";
-import { View, Image, Text } from "react-native";
+const stream = useStream({
+  0: 0,
+  1: 500,
+  2: 1000,
+});
 
-const renderers = {
-  image: ({ url, title, alt }: ImageRendererProps) => (
-    <View>
-      <Image source={{ uri: url }} style={{ height: 220, borderRadius: 12 }} />
-      {(title || alt) && (
-        <Text style={{ marginTop: 6, opacity: 0.6 }}>{title || alt}</Text>
-      )}
-    </View>
-  ),
-};
+// e.g. in media time update callback:
+stream.sync(currentTimeMs);
+
+<MarkdownStream session={stream.getSession()} />;
 ```
 
-### Render HTML nodes as code (opt-in)
+Demo usage:
+
+- README examples (timed playback scenario)
+
+## Headless API
 
 ```tsx
-import { Markdown, CodeBlock, InlineCode } from "react-native-nitro-markdown";
+import {
+  parseMarkdown,
+  parseMarkdownWithOptions,
+  extractPlainText,
+  extractPlainTextWithOptions,
+  getTextContent,
+  getFlattenedText,
+} from "react-native-nitro-markdown/headless";
+```
 
-const renderers = {
-  html_block: ({ node }) => <CodeBlock content={node.content ?? \"\"} />,
-  html_inline: ({ node }) => <InlineCode content={node.content ?? \"\"} />,
+| 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.                    |
+| `extractPlainText`         | `(text: string) => string`                               | Parses and returns normalized plain text directly from native parser. |
+| `extractPlainTextWithOptions` | `(text: string, options: ParserOptions) => string`   | Same as above with parser flags.                                   |
+| `getTextContent`           | `(node: MarkdownNode) => string`                         | Concatenates text recursively without layout normalization.        |
+| `getFlattenedText`         | `(node: MarkdownNode) => string`                         | Returns normalized plain text with paragraph and block separators. |
+
+### Parser Options
+
+```ts
+type ParserOptions = {
+  gfm?: boolean;
+  math?: boolean;
 };
 ```
 
-### Minimal styling + custom palette
+Example:
 
 ```tsx
-import { Markdown } from "react-native-nitro-markdown";
-
-<Markdown
-  stylingStrategy="minimal"
-  theme={{ colors: { text: "#e2e8f0", link: "#38bdf8" } }}
->
-  {content}
-</Markdown>;
+const ast = parseMarkdownWithOptions(markdown, {
+  gfm: true, // tables, task lists, strikethrough
+  math: true, // inline/block LaTeX
+});
 ```
 
-### Build a search index (headless)
+### `MarkdownParserModule` (low-level Nitro access)
+
+Use this only when you want direct method access (`parse`, `parseWithOptions`, `extractPlainText`, `extractPlainTextWithOptions`).
 
 ```tsx
-import { parseMarkdown, getFlattenedText } from "react-native-nitro-markdown/headless";
+import {
+  MarkdownParserModule,
+  type ParserOptions,
+} from "react-native-nitro-markdown/headless";
 
-const ast = parseMarkdown(content);
-const plainText = getFlattenedText(ast);
+const options: ParserOptions = { gfm: true };
+const jsonAst = JSON.parse(
+  MarkdownParserModule.parseWithOptions("# Hello", options),
+);
 ```
 
----
+## Custom Renderer API
 
-## API Reference
+## `renderers` prop contract
 
-### Markdown component
+`CustomRenderers` is:
 
-```tsx
-import { Markdown } from "react-native-nitro-markdown";
+```ts
+type CustomRenderers = Partial<Record<MarkdownNode["type"], CustomRenderer>>;
 ```
 
-Props:
+`CustomRenderer` receives `EnhancedRendererProps` and returns:
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `children` | `string` | required | Markdown string to parse and render |
-| `options` | `{ gfm?: boolean; math?: boolean }` | `undefined` | Parser options |
-| `renderers` | `CustomRenderers` | `{}` | Custom renderers by node type |
-| `theme` | `PartialMarkdownTheme` | `defaultMarkdownTheme` | Theme token overrides |
-| `styles` | `NodeStyleOverrides` | `undefined` | Per-node style overrides |
-| `stylingStrategy` | `"opinionated" \| "minimal"` | `"opinionated"` | Styling baseline |
-| `style` | `StyleProp<ViewStyle>` | `undefined` | Container style |
-| `onParsingInProgress` | `() => void` | `undefined` | Called when parsing starts |
-| `onParseComplete` | `(result) => void` | `undefined` | Called with `{ raw, ast, text }` |
+- React node to override default rendering
+- `undefined` to fallback to built-in renderer
+- `null` to render nothing
 
-### MarkdownStream
+`EnhancedRendererProps` always includes:
 
-```tsx
-import { MarkdownStream } from "react-native-nitro-markdown";
-```
+- `node`: current `MarkdownNode`
+- `children`: pre-rendered node children
+- `Renderer`: recursive renderer component for nested custom rendering
 
-Props (in addition to all `Markdown` props except `children`):
+And conditionally includes mapped fields by node type:
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `session` | `MarkdownSession` | required | Active session for streaming text |
-| `updateIntervalMs` | `number` | `50` | Throttle interval for updates |
-| `updateStrategy` | `"interval" \| "raf"` | `"interval"` | Update strategy |
-| `useTransitionUpdates` | `boolean` | `false` | Use React transitions |
+| 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`             |
 
-### Hooks and sessions
+### Example: Custom heading + code block
 
 ```tsx
-import { useMarkdownSession, createMarkdownSession, useStream } from "react-native-nitro-markdown";
-```
-
-- `useMarkdownSession()` returns a managed session and helpers: `getSession`, `setIsStreaming`, `stop`, `clear`, `setHighlight`.
-- `createMarkdownSession()` creates a session without React hooks.
-- `useStream(timestamps)` adds a simple sync helper for time-based streaming.
+import {
+  Markdown,
+  type HeadingRendererProps,
+  type CodeBlockRendererProps,
+} from "react-native-nitro-markdown";
 
-### Headless API
+const renderers = {
+  heading: ({ level, children }: HeadingRendererProps) => (
+    <MyHeading level={level}>{children}</MyHeading>
+  ),
+  code_block: ({ language, content }: CodeBlockRendererProps) => (
+    <MyCode language={language} content={content} />
+  ),
+};
 
-```tsx
-import { parseMarkdown, parseMarkdownWithOptions, getTextContent, getFlattenedText } from "react-native-nitro-markdown/headless";
+<Markdown renderers={renderers}>{content}</Markdown>;
 ```
 
-### Theme utilities
+### `useMarkdownContext` example (inside custom renderer tree)
 
 ```tsx
+import { Text } from "react-native";
 import {
-  defaultMarkdownTheme,
-  minimalMarkdownTheme,
-  mergeThemes,
+  Markdown,
+  useMarkdownContext,
+  type CustomRendererProps,
 } from "react-native-nitro-markdown";
+
+function ThemedParagraph({ children }: Pick<CustomRendererProps, "children">) {
+  const { theme } = useMarkdownContext();
+  return <Text style={{ color: theme.colors.text }}>{children}</Text>;
+}
+
+<Markdown
+  renderers={{
+    paragraph: ({ children }: CustomRendererProps) => (
+      <ThemedParagraph>{children}</ThemedParagraph>
+    ),
+  }}
+>
+  {content}
+</Markdown>;
 ```
 
-### Types
+## Link Handling Behavior
+
+Default link renderer behavior:
+
+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`.
+
+Relative URLs and anchors are ignored by default open behavior, but you can handle them in `onLinkPress`.
+
+## Theme API
+
+## `MarkdownTheme`
 
 ```tsx
 import type {
-  CustomRenderers,
-  NodeStyleOverrides,
   MarkdownTheme,
   PartialMarkdownTheme,
 } from "react-native-nitro-markdown";
 ```
 
----
+`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`
+
+Helpers:
+
+- `defaultMarkdownTheme`
+- `minimalMarkdownTheme`
+- `mergeThemes(base, partial)`
+
+`NodeStyleOverrides` lets you override per-node styles:
+
+```ts
+type NodeStyleOverrides = Partial<
+  Record<MarkdownNode["type"], ViewStyle | TextStyle>
+>;
+```
+
+Example with `mergeThemes`:
 
-## Supported Node Types
+```tsx
+import {
+  Markdown,
+  defaultMarkdownTheme,
+  mergeThemes,
+} from "react-native-nitro-markdown";
 
-You can customize any of these node types with `renderers` or `styles`.
+const theme = mergeThemes(defaultMarkdownTheme, {
+  colors: {
+    text: "#0f172a",
+    link: "#1d4ed8",
+  },
+  fontSizes: {
+    m: 16,
+  },
+});
+
+<Markdown theme={theme}>{content}</Markdown>;
+```
+
+## Built-in Renderer Components
+
+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`                               |
+
+## Supported AST Node Types
 
 `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`
 
-Note: `html_inline` and `html_block` are parsed but not rendered by default.
+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.
 
-## AST Shape
+## Recipes
 
-The headless API returns a typed AST. This is the core shape used by the renderer.
+### Intercept links with `onLinkPress`
 
-```ts
-export interface MarkdownNode {
-  type:
-    | "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";
-  content?: string;
-  children?: MarkdownNode[];
-  level?: number;
-  href?: string;
-  title?: string;
-  alt?: string;
-  language?: string;
-  ordered?: boolean;
-  start?: number;
-  checked?: boolean;
-  align?: string;
-  isHeader?: boolean;
-}
+```tsx
+import { Markdown } from "react-native-nitro-markdown";
+
+<Markdown
+  onLinkPress={(href) => {
+    if (href.startsWith("/")) {
+      router.push(href);
+      return false;
+    }
+  }}
+>
+  {content}
+</Markdown>;
 ```
 
----
+### Use headless mode to build search index
 
-## Troubleshooting
+```tsx
+import {
+  parseMarkdown,
+  getFlattenedText,
+} from "react-native-nitro-markdown/headless";
 
-- Math renders as plain text: install `react-native-mathjax-svg` and `react-native-svg`.
-- iOS build errors: run `pod install` after installing dependencies.
-- Expo: you must use a development build (`expo prebuild` + `expo run`), not Expo Go.
-- Android heading font looks wrong: set `headingWeight: "normal"` when your font has no bold variant.
+const ast = parseMarkdown(content);
+const searchableText = getFlattenedText(ast);
+```
+
+### Minimal styling baseline
+
+```tsx
+import { Markdown } from "react-native-nitro-markdown";
+
+<Markdown
+  stylingStrategy="minimal"
+  theme={{
+    colors: {
+      text: "#0f172a",
+      link: "#1d4ed8",
+    },
+  }}
+>
+  {content}
+</Markdown>;
+```
+
+## 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.
+- For large markdown documents, enable `virtualize` and tune `virtualization.windowSize` / `maxToRenderPerBatch`.
+- Use the headless API if you do not need built-in renderers.
+
+## Troubleshooting
 
----
+- 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"`).
 
 ## Contributing
 
-See `CONTRIBUTING.md` for the workflow and development commands.
+See `CONTRIBUTING.md`.
 
 ## License