react-native-nitro-markdown 0.4.3 → 0.5.1

package/README.md

@@ -1,6 +1,5 @@
 <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
@@ -20,7 +19,7 @@ Native Markdown parsing and rendering for React Native.
 ## Requirements
 
 - React Native `>=0.75.0`
-- `react-native-nitro-modules`
+- `react-native-nitro-modules >=0.35.0`
 
 Optional for math rendering:
 
@@ -74,6 +73,79 @@ 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                       |
+
 ## Package Exports
 
 ### Main Entry (`react-native-nitro-markdown`)
@@ -103,8 +175,12 @@ export function Example() {
   - `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`
@@ -116,7 +192,7 @@ export function Example() {
 
 ### Headless Entry (`react-native-nitro-markdown/headless`)
 
-Exports only parser-related API (`parseMarkdown`, `parseMarkdownWithOptions`, `getTextContent`, `getFlattenedText`, types). Use this when you do not need built-in UI rendering.
+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
 
@@ -126,23 +202,187 @@ Exports only parser-related API (`parseMarkdown`, `parseMarkdownWithOptions`, `g
 import { Markdown } from "react-native-nitro-markdown";
 ```
 
-| Prop                  | Type                   | Default                                          | Description                                                                               |
-| --------------------- | ---------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------- | -------------------- |
-| `children`            | `string`               | required                                         | Markdown input string.                                                                    |
-| `options`             | `ParserOptions`        | `undefined`                                      | Parser flags (`gfm`, `math`).                                                             |
-| `renderers`           | `CustomRenderers`      | `{}`                                             | Per-node custom renderers.                                                                |
-| `theme`               | `PartialMarkdownTheme` | `defaultMarkdownTheme` or `minimalMarkdownTheme` | Theme token overrides.                                                                    |
-| `styles`              | `NodeStyleOverrides`   | `undefined`                                      | Per-node style overrides.                                                                 |
-| `stylingStrategy`     | `"opinionated"         | "minimal"`                                       | `"opinionated"`                                                                           | Base styling preset. |
-| `style`               | `StyleProp<ViewStyle>` | `undefined`                                      | Container style for the root `View`.                                                      |
-| `onParsingInProgress` | `() => void`           | `undefined`                                      | Called when parse inputs change.                                                          |
-| `onParseComplete`     | `(result) => void`     | `undefined`                                      | Called with `{ raw, ast, text }` after successful parse.                                  |
-| `onLinkPress`         | `LinkPressHandler`     | `undefined`                                      | Intercepts link press before default open behavior. Return `false` to block default open. |
+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)
+
+```tsx
+<Markdown
+  virtualize="auto"
+  virtualizationMinBlocks={30}
+  virtualization={{
+    initialNumToRender: 10,
+    maxToRenderPerBatch: 10,
+    windowSize: 8,
+    updateCellsBatchingPeriod: 16,
+    removeClippedSubviews: true,
+  }}
+>
+  {content}
+</Markdown>
+```
+
+Virtualization notes:
+
+- Keep `Markdown` as the primary vertical scroller when `virtualize` is enabled.
+- Avoid nesting it inside another vertical `ScrollView`, or virtualization effectiveness drops.
+
+### AST transform example
+
+```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);
+}, []);
+
+<Markdown astTransform={astTransform}>{"Hello :wink:"}</Markdown>;
+```
+
+### 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);
+    },
+  },
+];
+
+<Markdown plugins={plugins}>{"Launch :rocket:"}</Markdown>;
+```
+
+### `onError` example
+
+```tsx
+import { Markdown } from "react-native-nitro-markdown";
+
+<Markdown
+  onError={(error, phase, pluginName) => {
+    console.warn(`[markdown] ${phase} error`, { error, pluginName });
+  }}
+  plugins={plugins}
+>
+  {content}
+</Markdown>;
+```
+
+### Syntax highlighting example
+
+```tsx
+import { Markdown } from "react-native-nitro-markdown";
+
+// 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";
+
+const myHighlighter: CodeHighlighter = (language, code) => {
+  // return an array of { text, type } tokens
+  return [{ text: code, type: "default" }];
+};
+
+<Markdown highlightCode={myHighlighter}>{content}</Markdown>;
+```
+
+### `sourceAst` example (skip parsing in render)
+
+```tsx
+import {
+  Markdown,
+  parseMarkdownWithOptions,
+} from "react-native-nitro-markdown";
+
+const sourceAst = parseMarkdownWithOptions(content, { gfm: true, math: true });
+
+<Markdown sourceAst={sourceAst}>
+  {"children is ignored when sourceAst is provided"}
+</Markdown>;
+```
+
+### Parse lifecycle callbacks example
+
+```tsx
+import { Markdown } 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);
+  }}
+>
+  {content}
+</Markdown>;
+```
 
 ## `MarkdownStream`
 
@@ -152,12 +392,22 @@ import { MarkdownStream } from "react-native-nitro-markdown";
 
 `MarkdownStreamProps` extends `MarkdownProps` except `children`.
 
-| 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.  |
+Demo usage:
+
+- `apps/example/app/render-stream.tsx`
+
+| 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
 
@@ -203,6 +453,39 @@ 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.
@@ -218,6 +501,10 @@ Returns:
 | `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.
@@ -234,14 +521,36 @@ Additional returned fields:
 | `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
 
 ```tsx
 import {
   parseMarkdown,
   parseMarkdownWithOptions,
+  extractPlainText,
+  extractPlainTextWithOptions,
   getTextContent,
   getFlattenedText,
+  stripSourceOffsets,
 } from "react-native-nitro-markdown/headless";
 ```
 
@@ -249,8 +558,11 @@ import {
 | -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------ |
 | `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
 
@@ -261,6 +573,31 @@ type ParserOptions = {
 };
 ```
 
+Example:
+
+```tsx
+const ast = parseMarkdownWithOptions(markdown, {
+  gfm: true, // tables, task lists, strikethrough
+  math: true, // inline/block LaTeX
+});
+```
+
+### `MarkdownParserModule` (low-level Nitro access)
+
+Use this only when you want direct method access (`parse`, `parseWithOptions`, `extractPlainText`, `extractPlainTextWithOptions`).
+
+```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
@@ -316,6 +653,32 @@ const renderers = {
 <Markdown renderers={renderers}>{content}</Markdown>;
 ```
 
+### `useMarkdownContext` example (inside custom renderer tree)
+
+```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>
+    ),
+  }}
+>
+  {content}
+</Markdown>;
+```
+
 ## Link Handling Behavior
 
 Default link renderer behavior:
@@ -350,6 +713,7 @@ import type {
   - `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`
@@ -363,14 +727,41 @@ Helpers:
 - `minimalMarkdownTheme`
 - `mergeThemes(base, partial)`
 
-`NodeStyleOverrides` lets you override per-node styles:
+`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<
-  Record<MarkdownNode["type"], ViewStyle | TextStyle>
+  {
+    text: TextStyle; bold: TextStyle; italic: TextStyle; /* ... */
+    document: ViewStyle; blockquote: ViewStyle; code_block: ViewStyle; /* ... */
+  }
 >;
 ```
 
+Example with `mergeThemes`:
+
+```tsx
+import {
+  Markdown,
+  defaultMarkdownTheme,
+  mergeThemes,
+} from "react-native-nitro-markdown";
+
+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.
@@ -455,6 +846,7 @@ import { Markdown } from "react-native-nitro-markdown";
 - 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
@@ -470,7 +862,7 @@ import { Markdown } from "react-native-nitro-markdown";
 
 ## Contributing
 
-See `/Users/jota/Workspace/Projects/RN-Packages/react-native-nitro-markdown/CONTRIBUTING.md`.
+See `CONTRIBUTING.md`.
 
 ## License
 

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

@@ -2,7 +2,7 @@ package com.margelo.nitro.com.nitromarkdown
 
 class HybridMarkdownSession : HybridMarkdownSessionSpec() {
     private var buffer = StringBuilder()
-    private val listeners = mutableMapOf<Long, () -> Unit>()
+    private val listeners = mutableMapOf<Long, (Double, Double) -> Unit>()
     private var nextListenerId = 0L
     private val lock = Any()
 
@@ -17,11 +17,16 @@ class HybridMarkdownSession : HybridMarkdownSessionSpec() {
     override val memorySize: Long
         get() = buffer.length.toLong()
 
-    override fun append(chunk: String) {
+    override fun append(chunk: String): Double {
+        val from: Int
+        val to: Int
         synchronized(lock) {
+            from = buffer.length
             buffer.append(chunk)
+            to = buffer.length
         }
-        notifyListeners()
+        notifyListeners(from.toDouble(), to.toDouble())
+        return to.toDouble()
     }
 
     override fun clear() {
@@ -29,7 +34,7 @@ class HybridMarkdownSession : HybridMarkdownSessionSpec() {
             buffer.clear()
             highlightPosition = 0.0
         }
-        notifyListeners()
+        notifyListeners(0.0, 0.0)
     }
 
     override fun getAllText(): String {
@@ -38,7 +43,21 @@ class HybridMarkdownSession : HybridMarkdownSessionSpec() {
         }
     }
 
-    override fun addListener(listener: () -> Unit): () -> Unit {
+    override fun getLength(): Double {
+        synchronized(lock) {
+            return buffer.length.toDouble()
+        }
+    }
+
+    override fun getTextRange(from: Double, to: Double): String {
+        synchronized(lock) {
+            val start = from.toInt().coerceIn(0, buffer.length)
+            val end = to.toInt().coerceIn(start, buffer.length)
+            return buffer.substring(start, end)
+        }
+    }
+
+    override fun addListener(listener: (Double, Double) -> Unit): () -> Unit {
         val id: Long
         synchronized(lock) {
             id = nextListenerId++
@@ -51,11 +70,30 @@ class HybridMarkdownSession : HybridMarkdownSessionSpec() {
         }
     }
 
-    private fun notifyListeners() {
-        val currentListeners: Collection<() -> Unit>
+    override fun reset(text: String) {
+        synchronized(lock) {
+            buffer.replace(0, buffer.length, text)
+        }
+        notifyListeners(0.0, text.length.toDouble())
+    }
+
+    override fun replace(from: Double, to: Double, text: String): Double {
+        val newLength: Double
+        synchronized(lock) {
+            val start = from.toInt().coerceIn(0, buffer.length)
+            val end = to.toInt().coerceIn(start, buffer.length)
+            buffer.replace(start, end, text)
+            newLength = buffer.length.toDouble()
+        }
+        notifyListeners(from, from + text.length.toDouble())
+        return newLength
+    }
+
+    private fun notifyListeners(from: Double, to: Double) {
+        val currentListeners: Collection<(Double, Double) -> Unit>
         synchronized(lock) {
             currentListeners = listeners.values.toList()
         }
-        currentListeners.forEach { it() }
+        currentListeners.forEach { it(from, to) }
     }
 }