react-native-nitro-markdown 0.5.1 → 0.5.3

package/README.md

@@ -4,59 +4,45 @@
 
 # react-native-nitro-markdown
 
-Native Markdown parsing and rendering for React Native.
+Native Markdown parsing and rendering for React Native, powered by [md4c](https://github.com/mity/md4c) (C++) through [Nitro Modules](https://github.com/mrousavy/nitro) (JSI).
 
-`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.
+## Features
 
-## 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`
+- **Native C++ parser** -- synchronous parsing via JSI with minimal JS thread overhead
+- **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)
+- **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
 
 ## Requirements
 
-- React Native `>=0.75.0`
-- `react-native-nitro-modules >=0.35.0`
-
-Optional for math rendering:
-
-- `react-native-mathjax-svg >=0.9.0`
-- `react-native-svg >=13.0.0`
+| Dependency | Version |
+|---|---|
+| React Native | `>=0.75.0` |
+| react-native-nitro-modules | `>=0.35.0` |
+| react-native-mathjax-svg *(optional)* | `>=0.9.0` |
+| react-native-svg *(optional, for math)* | `>=13.0.0` |
 
 ## Installation
 
-### React Native
-
-```bash
-bun add react-native-nitro-markdown react-native-nitro-modules
-```
-
-Optional math support:
-
-```bash
-bun add react-native-mathjax-svg react-native-svg
-```
-
-iOS pods:
-
 ```bash
+npm install react-native-nitro-markdown react-native-nitro-modules
 cd ios && pod install
 ```
 
-### Expo (development build)
+For math rendering:
 
 ```bash
-bunx expo install react-native-nitro-markdown react-native-nitro-modules
-bunx expo prebuild
+npm install react-native-mathjax-svg react-native-svg
 ```
 
-Optional math support:
+**Expo** (development build):
 
 ```bash
-bunx expo install react-native-mathjax-svg react-native-svg
+npx expo install react-native-nitro-markdown react-native-nitro-modules
+npx expo prebuild
 ```
 
 ## Quick Start
@@ -73,343 +59,200 @@ export function Example() {
 }
 ```
 
-## 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 |
-| `onError` | Structured error reporting for parse and plugin failures | README examples |
-| `highlightCode` / `defaultHighlighter` | Opt-in syntax highlighting for code blocks | README examples |
-| `tableOptions` | Per-instance table column and measurement tuning | README examples |
-| `stripSourceOffsets` | Remove source position data from parsed AST | README examples |
-| `MarkdownSession.reset` / `MarkdownSession.replace` | Full and partial buffer mutation | 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`       |
-| Syntax highlighting      | `highlightCode`, `defaultHighlighter`, `codeTokenColors` | Opt-in token-colored code block rendering            | README examples                       |
-| Plugin priority          | `MarkdownPlugin.priority`                           | Control plugin execution order                            | README examples                       |
-| Error reporting          | `onError`                                           | Observe parse and plugin failures without crashing        | README examples                       |
-| Table tuning             | `tableOptions`                                      | Configure column width and measurement debounce           | README examples                       |
-| AST cleanup              | `stripSourceOffsets`                                | Remove source positions from AST for compact storage      | README examples                       |
-| Session mutation         | `MarkdownSession.reset`, `MarkdownSession.replace`  | Replace or partially edit the session text buffer         | README examples                       |
-| Low-level parser access  | `MarkdownParserModule`                              | Direct access to Nitro parser methods                     | README examples                       |
+## API Reference
 
-## Package Exports
+### `<Markdown>`
 
-### 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`
-- Syntax highlighting:
-  - `defaultHighlighter`
-  - `CodeHighlighter`, `HighlightedToken`, `TokenType`
-- 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`, `stripSourceOffsets`, types). Use this when you do not need built-in UI rendering.
-
-## Component API
-
-## `Markdown`
+The main component. Parses a markdown string and renders it.
 
 ```tsx
 import { Markdown } from "react-native-nitro-markdown";
 ```
 
-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. |
-| `onError`             | `(error, phase, pluginName?) => void` | `undefined`                           | Called when a parse or plugin error occurs. `phase` is `'parse'`, `'before-plugin'`, or `'after-plugin'`. |
-| `highlightCode`       | `boolean \| CodeHighlighter` | `undefined`                                      | Enables syntax highlighting for code blocks. Pass `true` for the built-in highlighter or a custom `CodeHighlighter` function. |
-| `tableOptions`        | `{ minColumnWidth?: number; measurementStabilizeMs?: number }` | `undefined`     | Table layout tuning. `minColumnWidth` defaults to `60`; `measurementStabilizeMs` defaults to `140`. |
-| `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` plugins (sorted by `priority` desc) -> parse/sourceAst -> `afterParse` plugins (sorted by `priority` desc) -> `astTransform` -> render.
-- `onError` is called per-failure; individual plugin failures do not abort the full pipeline.
-- 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)
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `string` | required | Markdown input string |
+| `options` | `ParserOptions` | -- | Parser flags (`gfm`, `math`) |
+| `plugins` | `MarkdownPlugin[]` | -- | Plugin hooks (`beforeParse`, `afterParse`) |
+| `sourceAst` | `MarkdownNode` | -- | Pre-parsed AST; skips native parse when provided |
+| `astTransform` | `AstTransform` | -- | Post-parse AST rewrite before render |
+| `renderers` | `CustomRenderers` | `{}` | Per-node custom renderer overrides |
+| `theme` | `PartialMarkdownTheme` | `defaultMarkdownTheme` | Theme token overrides |
+| `styles` | `NodeStyleOverrides` | -- | Per-node style overrides |
+| `stylingStrategy` | `"opinionated" \| "minimal"` | `"opinionated"` | Base styling preset |
+| `style` | `StyleProp<ViewStyle>` | -- | Container style |
+| `onLinkPress` | `LinkPressHandler` | -- | Intercept link presses; return `false` to block default open |
+| `onParsingInProgress` | `() => void` | -- | Called when parse inputs change |
+| `onParseComplete` | `(result) => void` | -- | Called with `{ raw, ast, text }` after parse |
+| `onError` | `(error, phase, pluginName?) => void` | -- | Error handler for parse/plugin failures |
+| `highlightCode` | `boolean \| CodeHighlighter` | -- | Enable syntax highlighting for code blocks |
+| `tableOptions` | `{ minColumnWidth?; measurementStabilizeMs? }` | -- | Table layout tuning |
+| `virtualize` | `boolean \| "auto"` | `false` | Top-level block virtualization |
+| `virtualizationMinBlocks` | `number` | `40` | Block threshold for `"auto"` virtualization |
+| `virtualization` | `MarkdownVirtualizationOptions` | -- | FlatList tuning (windowSize, batching, etc.) |
+
+**Pipeline order:** `beforeParse` plugins (by priority desc) -> parse/sourceAst -> `afterParse` plugins (by priority desc) -> `astTransform` -> render.
+
+### `<MarkdownStream>`
+
+Renders markdown from a streaming session. Extends `MarkdownProps` (minus `children`).
 
 ```tsx
-<Markdown
-  virtualize="auto"
-  virtualizationMinBlocks={30}
-  virtualization={{
-    initialNumToRender: 10,
-    maxToRenderPerBatch: 10,
-    windowSize: 8,
-    updateCellsBatchingPeriod: 16,
-    removeClippedSubviews: true,
-  }}
->
-  {content}
-</Markdown>
+import { MarkdownStream } from "react-native-nitro-markdown";
 ```
 
-Virtualization notes:
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `session` | `MarkdownSession` | required | Session supplying streamed text |
+| `updateIntervalMs` | `number` | `50` | Flush interval for `"interval"` strategy |
+| `updateStrategy` | `"interval" \| "raf"` | `"interval"` | Update cadence |
+| `useTransitionUpdates` | `boolean` | `false` | Wrap updates in `startTransition` |
+| `incrementalParsing` | `boolean` | `true` | Append-optimized incremental AST updates |
 
-- Keep `Markdown` as the primary vertical scroller when `virtualize` is enabled.
-- Avoid nesting it inside another vertical `ScrollView`, or virtualization effectiveness drops.
+### `MarkdownSession`
 
-### AST transform example
+A native text buffer with change listeners, used for streaming.
 
 ```tsx
-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);
-}, []);
+import { createMarkdownSession } from "react-native-nitro-markdown";
 
-<Markdown astTransform={astTransform}>{"Hello :wink:"}</Markdown>;
+const session = createMarkdownSession();
+session.append("# Hello\n");
+session.append("Streaming content...");
 ```
 
-### Plugin pipeline example (`beforeParse` + `afterParse`)
-
-```tsx
-import { Markdown, type MarkdownPlugin } from "react-native-nitro-markdown";
-
-const plugins: MarkdownPlugin[] = [
-  {
-    name: "rewrite-before-parse",
-    priority: 10, // runs before lower-priority plugins
-    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);
-    },
-  },
-];
+| Method | Signature | Description |
+|---|---|---|
+| `append` | `(chunk: string) => number` | Append text, returns new UTF-16 length |
+| `clear` | `() => void` | Clear buffer, emit reset event |
+| `reset` | `(text: string) => void` | Replace full buffer content |
+| `replace` | `(from, to, text) => number` | Partial buffer mutation |
+| `getAllText` | `() => string` | Get full session text |
+| `getLength` | `() => number` | Get UTF-16 length without copy |
+| `getTextRange` | `(from, to) => string` | Get substring range |
+| `addListener` | `(listener) => () => void` | Subscribe to mutation events; returns unsubscribe |
+| `highlightPosition` | `number` | Mutable cursor for stream highlight |
 
-<Markdown plugins={plugins}>{"Launch :rocket:"}</Markdown>;
-```
+### `useMarkdownSession()`
 
-### `onError` example
+Creates and owns a `MarkdownSession` for a component lifecycle.
 
 ```tsx
-import { Markdown } from "react-native-nitro-markdown";
+import { useMarkdownSession } from "react-native-nitro-markdown";
 
-<Markdown
-  onError={(error, phase, pluginName) => {
-    console.warn(`[markdown] ${phase} error`, { error, pluginName });
-  }}
-  plugins={plugins}
->
-  {content}
-</Markdown>;
+const { getSession, isStreaming, setIsStreaming, stop, clear, setHighlight } =
+  useMarkdownSession();
 ```
 
-### Syntax highlighting example
+### `useStream(timestamps?)`
 
-```tsx
-import { Markdown } from "react-native-nitro-markdown";
+Extends `useMarkdownSession` with timeline sync for timed playback.
 
-// Built-in highlighter (JS/TS, Python, Bash)
-<Markdown highlightCode>{"```typescript\nconst x: number = 42;\n```"}</Markdown>;
-
-// Custom highlighter
-import type { CodeHighlighter } from "react-native-nitro-markdown";
+```tsx
+import { useStream } from "react-native-nitro-markdown";
 
-const myHighlighter: CodeHighlighter = (language, code) => {
-  // return an array of { text, type } tokens
-  return [{ text: code, type: "default" }];
-};
+const stream = useStream({ 0: 0, 1: 500, 2: 1000 });
+stream.sync(currentTimeMs);
 
-<Markdown highlightCode={myHighlighter}>{content}</Markdown>;
+<MarkdownStream session={stream.getSession()} />;
 ```
 
-### `sourceAst` example (skip parsing in render)
+### Headless API
+
+Parse markdown without any UI. Available from both entry points.
 
 ```tsx
 import {
-  Markdown,
+  parseMarkdown,
   parseMarkdownWithOptions,
-} from "react-native-nitro-markdown";
+  extractPlainText,
+  getTextContent,
+  getFlattenedText,
+  stripSourceOffsets,
+} from "react-native-nitro-markdown/headless";
+```
 
-const sourceAst = parseMarkdownWithOptions(content, { gfm: true, math: true });
+| Function | Description |
+|---|---|
+| `parseMarkdown(text, options?)` | Parse to AST (options: `{ gfm?, math? }`) |
+| `parseMarkdownWithOptions(text, options)` | Parse with explicit options |
+| `extractPlainText(text)` | Parse and return plain text from native parser |
+| `extractPlainTextWithOptions(text, options)` | Same with parser flags |
+| `getTextContent(node)` | Concatenate text recursively (no normalization) |
+| `getFlattenedText(node)` | Normalized plain text with block separators |
+| `stripSourceOffsets(node)` | Remove `beg`/`end` fields from AST |
 
-<Markdown sourceAst={sourceAst}>
-  {"children is ignored when sourceAst is provided"}
-</Markdown>;
-```
+### Custom Renderers
 
-### Parse lifecycle callbacks example
+Override rendering for specific node types:
 
 ```tsx
-import { Markdown } from "react-native-nitro-markdown";
+import {
+  Markdown,
+  type HeadingRendererProps,
+  type CodeBlockRendererProps,
+} from "react-native-nitro-markdown";
 
 <Markdown
-  onParsingInProgress={() => setIsParsing(true)}
-  onParseComplete={({ raw, ast, text }) => {
-    setIsParsing(false);
-    setWordCount(text.trim().split(/\s+/).length);
-    setLastRaw(raw);
-    setLastAst(ast);
+  renderers={{
+    heading: ({ level, children }: HeadingRendererProps) => (
+      <MyHeading level={level}>{children}</MyHeading>
+    ),
+    code_block: ({ language, content }: CodeBlockRendererProps) => (
+      <MyCode language={language} content={content} />
+    ),
   }}
 >
   {content}
 </Markdown>;
 ```
 
-## `MarkdownStream`
+Renderers receive `EnhancedRendererProps` with `node`, `children`, and `Renderer` (for recursive rendering). Node-specific props are mapped automatically:
 
-```tsx
-import { MarkdownStream } from "react-native-nitro-markdown";
-```
+| 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` |
+
+Return `undefined` to fall back to the built-in renderer, or `null` to render nothing.
 
-`MarkdownStreamProps` extends `MarkdownProps` except `children`.
+### Theme API
 
-Demo usage:
+```tsx
+import {
+  Markdown,
+  defaultMarkdownTheme,
+  minimalMarkdownTheme,
+  mergeThemes,
+} from "react-native-nitro-markdown";
+
+const theme = mergeThemes(defaultMarkdownTheme, {
+  colors: { text: "#0f172a", link: "#1d4ed8" },
+  fontSizes: { m: 16 },
+});
 
-- `apps/example/app/render-stream.tsx`
+<Markdown theme={theme}>{content}</Markdown>;
+```
 
-| 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). |
+`MarkdownTheme` includes:
+- **colors** -- `text`, `heading`, `link`, `code`, `codeBackground`, `blockquote`, `border`, `surface`, table colors, and optional `codeTokenColors` for syntax highlighting
+- **spacing** -- `xs`, `s`, `m`, `l`, `xl`
+- **fontSizes** -- `xs` through `xl`, plus `h1`-`h6`
+- **fontFamilies** -- `regular`, `heading`, `mono`
+- **borderRadius** -- `s`, `m`, `l`
+- **headingWeight** -- optional font weight override
+- **showCodeLanguage** -- show/hide language label on code blocks
 
-Notes:
+Use `stylingStrategy="minimal"` for a bare baseline, or `NodeStyleOverrides` for per-node style overrides (text nodes accept `TextStyle`, container nodes accept `ViewStyle`).
 
-- 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.
+## Examples
 
-### Streaming Example
+### Streaming
 
 ```tsx
 import { useEffect } from "react";
@@ -425,7 +268,6 @@ export function StreamingExample() {
     const s = session.getSession();
     s.append("# Streaming\n");
     s.append("This text arrives in chunks.");
-
     return () => session.clear();
   }, [session]);
 
@@ -434,371 +276,107 @@ export function StreamingExample() {
       session={session.getSession()}
       options={{ gfm: true }}
       updateStrategy="raf"
-      useTransitionUpdates
     />
   );
 }
 ```
 
-## Hooks and Session API
-
-## `createMarkdownSession()`
-
-Creates and returns a native `MarkdownSession` instance.
-
-```tsx
-import { createMarkdownSession } from "react-native-nitro-markdown";
-
-const session = createMarkdownSession();
-session.append("hello");
-```
-
-`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`). |
-| `reset` | `(text: string) => void` | Replaces full buffer content and emits a full-range change event. |
-| `replace` | `(from: number, to: number, text: string) => number` | Partial buffer mutation; returns new total UTF-16 length. |
-| `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. |
-
-Demo usage:
-
-- Referenced in `apps/example/app/render-stream.tsx` sample markdown content and used directly in README examples.
-
-Manual session + stream rendering:
-
-```tsx
-import {
-  createMarkdownSession,
-  MarkdownStream,
-} from "react-native-nitro-markdown";
-
-const session = createMarkdownSession();
-session.append("# Hello\n");
-session.append("Streaming content...");
-
-<MarkdownStream session={session} updateStrategy="raf" />;
-```
-
-## `useMarkdownSession()`
-
-Creates and owns one `MarkdownSession` for a component lifecycle.
-
-Returns:
-
-| 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`.                             |
-
-Demo usage:
-
-- `apps/example/app/render-stream.tsx`
-
-## `useStream(timestamps?)`
-
-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. |
-
-Example:
-
-```tsx
-const stream = useStream({
-  0: 0,
-  1: 500,
-  2: 1000,
-});
-
-// e.g. in media time update callback:
-stream.sync(currentTimeMs);
-
-<MarkdownStream session={stream.getSession()} />;
-```
-
-Demo usage:
-
-- README examples (timed playback scenario)
-
-## Headless API
+### AST Transform
 
 ```tsx
-import {
-  parseMarkdown,
-  parseMarkdownWithOptions,
-  extractPlainText,
-  extractPlainTextWithOptions,
-  getTextContent,
-  getFlattenedText,
-  stripSourceOffsets,
-} from "react-native-nitro-markdown/headless";
-```
-
-| 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. |
-| `stripSourceOffsets`       | `(node: MarkdownNode) => MarkdownNode`                   | Recursively removes `beg`/`end` source position fields. Useful for compact serialization or snapshot testing. |
-
-### Parser Options
-
-```ts
-type ParserOptions = {
-  gfm?: boolean;
-  math?: boolean;
-};
-```
+import { useCallback } from "react";
+import { Markdown, type AstTransform } from "react-native-nitro-markdown";
 
-Example:
+const transform = useCallback<AstTransform>((ast) => {
+  const visit = (node: Parameters<AstTransform>[0]): typeof node => ({
+    ...node,
+    content:
+      node.type === "text"
+        ? (node.content ?? "").replace(/:wink:/g, "😉")
+        : node.content,
+    children: node.children?.map(visit),
+  });
+  return visit(ast);
+}, []);
 
-```tsx
-const ast = parseMarkdownWithOptions(markdown, {
-  gfm: true, // tables, task lists, strikethrough
-  math: true, // inline/block LaTeX
-});
+<Markdown astTransform={transform}>{"Hello :wink:"}</Markdown>;
 ```
 
-### `MarkdownParserModule` (low-level Nitro access)
-
-Use this only when you want direct method access (`parse`, `parseWithOptions`, `extractPlainText`, `extractPlainTextWithOptions`).
+### Plugin Pipeline
 
 ```tsx
-import {
-  MarkdownParserModule,
-  type ParserOptions,
-} from "react-native-nitro-markdown/headless";
-
-const options: ParserOptions = { gfm: true };
-const jsonAst = JSON.parse(
-  MarkdownParserModule.parseWithOptions("# Hello", options),
-);
-```
-
-## Custom Renderer API
-
-## `renderers` prop contract
+import { Markdown, type MarkdownPlugin } from "react-native-nitro-markdown";
 
-`CustomRenderers` is:
+const plugins: MarkdownPlugin[] = [
+  {
+    name: "rewrite-before-parse",
+    priority: 10,
+    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);
+    },
+  },
+];
 
-```ts
-type CustomRenderers = Partial<Record<MarkdownNode["type"], CustomRenderer>>;
+<Markdown plugins={plugins}>{"Launch :rocket:"}</Markdown>;
 ```
 
-`CustomRenderer` receives `EnhancedRendererProps` and returns:
-
-- React node to override default rendering
-- `undefined` to fallback to built-in renderer
-- `null` to render nothing
-
-`EnhancedRendererProps` always includes:
-
-- `node`: current `MarkdownNode`
-- `children`: pre-rendered node children
-- `Renderer`: recursive renderer component for nested custom rendering
-
-And conditionally includes mapped fields by node type:
-
-| 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`             |
-
-### Example: Custom heading + code block
+### Pre-parsed AST
 
 ```tsx
-import {
-  Markdown,
-  type HeadingRendererProps,
-  type CodeBlockRendererProps,
-} from "react-native-nitro-markdown";
+import { Markdown, parseMarkdownWithOptions } from "react-native-nitro-markdown";
 
-const renderers = {
-  heading: ({ level, children }: HeadingRendererProps) => (
-    <MyHeading level={level}>{children}</MyHeading>
-  ),
-  code_block: ({ language, content }: CodeBlockRendererProps) => (
-    <MyCode language={language} content={content} />
-  ),
-};
+const ast = parseMarkdownWithOptions(content, { gfm: true, math: true });
 
-<Markdown renderers={renderers}>{content}</Markdown>;
+<Markdown sourceAst={ast}>{"ignored when sourceAst is provided"}</Markdown>;
 ```
 
-### `useMarkdownContext` example (inside custom renderer tree)
+### Virtualization (large documents)
 
 ```tsx
-import { Text } from "react-native";
-import {
-  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>
-    ),
+  virtualize="auto"
+  virtualizationMinBlocks={30}
+  virtualization={{
+    initialNumToRender: 10,
+    maxToRenderPerBatch: 10,
+    windowSize: 8,
   }}
 >
   {content}
-</Markdown>;
-```
-
-## 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 {
-  MarkdownTheme,
-  PartialMarkdownTheme,
-} from "react-native-nitro-markdown";
+</Markdown>
 ```
 
-`MarkdownTheme` fields:
-
-- `colors`
-  - `text`, `textMuted`, `heading`, `link`, `code`, `codeBackground`, `codeLanguage`
-  - `blockquote`, `border`, `surface`, `surfaceLight`, `accent`
-  - `tableBorder`, `tableHeader`, `tableHeaderText`, `tableRowEven`, `tableRowOdd`
-  - `codeTokenColors?`: `{ keyword?, string?, comment?, number?, operator?, punctuation?, type?, default? }` — per-token colors used by `highlightCode`
-- `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 with type-safe shape checking:
-
-```ts
-// Text-type nodes accept TextStyle; view-type nodes accept ViewStyle.
-// TypeScript will catch mismatched style shapes at compile time.
-type NodeStyleOverrides = Partial<
-  {
-    text: TextStyle; bold: TextStyle; italic: TextStyle; /* ... */
-    document: ViewStyle; blockquote: ViewStyle; code_block: ViewStyle; /* ... */
-  }
->;
-```
+Keep `Markdown` as the primary vertical scroller when virtualization is enabled -- avoid nesting inside another `ScrollView`.
 
-Example with `mergeThemes`:
+### Syntax Highlighting
 
 ```tsx
-import {
-  Markdown,
-  defaultMarkdownTheme,
-  mergeThemes,
-} from "react-native-nitro-markdown";
+// Built-in highlighter (JS/TS, Python, Bash)
+<Markdown highlightCode>{"```typescript\nconst x: number = 42;\n```"}</Markdown>
 
-const theme = mergeThemes(defaultMarkdownTheme, {
-  colors: {
-    text: "#0f172a",
-    link: "#1d4ed8",
-  },
-  fontSizes: {
-    m: 16,
-  },
-});
+// Custom highlighter
+const myHighlighter: CodeHighlighter = (language, code) => {
+  return [{ text: code, type: "default" }];
+};
 
-<Markdown theme={theme}>{content}</Markdown>;
+<Markdown highlightCode={myHighlighter}>{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`
-
-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`
+### Link Interception
 
 ```tsx
-import { Markdown } from "react-native-nitro-markdown";
-
 <Markdown
   onLinkPress={(href) => {
     if (href.startsWith("/")) {
@@ -808,61 +386,58 @@ import { Markdown } from "react-native-nitro-markdown";
   }}
 >
   {content}
-</Markdown>;
+</Markdown>
 ```
 
-### Use headless mode to build search index
+Default link behavior: trims href, calls `onLinkPress`, validates scheme (`http:`, `https:`, `mailto:`, `tel:`, `sms:`), then opens via `Linking.openURL`. Relative URLs and anchors are ignored unless handled in `onLinkPress`.
 
-```tsx
-import {
-  parseMarkdown,
-  getFlattenedText,
-} from "react-native-nitro-markdown/headless";
+## Supported Node Types
 
-const ast = parseMarkdown(content);
-const searchableText = getFlattenedText(ast);
-```
+`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`
 
-### Minimal styling baseline
+`html_inline` and `html_block` are parsed but not rendered by default.
 
-```tsx
-import { Markdown } from "react-native-nitro-markdown";
+## Package Exports
 
-<Markdown
-  stylingStrategy="minimal"
-  theme={{
-    colors: {
-      text: "#0f172a",
-      link: "#1d4ed8",
-    },
-  }}
->
-  {content}
-</Markdown>;
-```
+### Main (`react-native-nitro-markdown`)
+
+Components, hooks, sessions, themes, built-in renderers, syntax highlighting, and all headless APIs.
+
+### Headless (`react-native-nitro-markdown/headless`)
 
-## Performance Guidance
+Parser and text utilities only -- no React dependencies. Use this for server-side processing, search indexing, or custom renderers.
 
-- 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.
+## 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
 
 ## 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"`).
+| Problem | Solution |
+|---|---|
+| Math renders as code-style fallback | Install `react-native-mathjax-svg` and `react-native-svg` |
+| iOS build fails after install | Run `pod install` in your iOS directory |
+| Expo app doesn't load native module | Use a development build (`expo prebuild` + `expo run`), not Expo Go |
+| Android heading font weight looks wrong | Set `theme.headingWeight` explicitly |
+
+## Example App
+
+The `apps/example` directory contains a full demo app with these screens:
+
+| Screen | File | Demonstrates |
+|---|---|---|
+| 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 |
+| Stream | `app/render-stream.tsx` | Live streaming with token append |
 
 ## Contributing
 
-See `CONTRIBUTING.md`.
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## License