react-native-enriched-markdown-scaffold 0.7.4-scaffold.9 → 1.0.2-scaffold.10

package/docs/INPUT.md

@@ -13,7 +13,7 @@ import {
   EnrichedMarkdownTextInput,
   type EnrichedMarkdownTextInputInstance,
   type StyleState,
-} from 'react-native-enriched-markdown';
+} from 'react-native-enriched-markdown-scaffold';
 
 export default function App() {
   const ref = useRef<EnrichedMarkdownTextInputInstance>(null);
@@ -66,6 +66,48 @@ Each call toggles the style within the current text selection. They are being to
 
 Styles are also available through the built-in native format bar that appears on text selection, and through the system context menu.
 
+## Headings
+
+Supported heading levels: H1–H6.
+
+Headings are block-level: a heading applies to the whole paragraph the cursor (or selection) touches, unlike [inline styles](#inline-styles) which apply to a character range. Toggle a heading by calling `toggleHeading(level)` on the component ref with a level from `1` to `6`:
+
+```tsx
+<Button title="H1" onPress={() => ref.current?.toggleHeading(1)} />
+```
+
+Calling `toggleHeading` with the level already applied to the cursor's paragraph turns the heading back into a regular paragraph. The cursor's current heading level is reported through the [`onChangeState`](API_REFERENCE.md#onchangestate) payload as `heading: { isActive, level }` (`level` is `0` when the paragraph is not a heading), so you can highlight the active level in your toolbar.
+
+Behavior notes:
+
+- An emptied heading line stays a heading until you toggle it off, so characters you type next continue at the heading size.
+- Pressing Enter at the end of a heading starts a regular paragraph on the next line (headings do not continue like list items).
+
+Heading font sizes, weights, and colors are configurable per level — see [Customizing Styles](#customizing-enrichedmarkdowntextinput--styles).
+
+## Lists
+
+`EnrichedMarkdownTextInput` supports nested unordered (bullet) and ordered (numbered) lists, serialized to Markdown as `- ` / `1. ` with three spaces of indentation per nesting level. Ordered items are numbered by their position among adjacent same-depth siblings, so numbering stays correct as items are added, removed, or reordered. Like headings, list items are block-level — they apply to whole paragraphs. Manage them through the component ref:
+
+- [`toggleUnorderedList()`](API_REFERENCE.md#toggleunorderedlist) — turns the cursor's paragraph(s) into bullet items, or back into regular paragraphs if they already are.
+- [`toggleOrderedList()`](API_REFERENCE.md#toggleorderedlist) — same for numbered items; toggling one list type on the other replaces it.
+- [`indentList()`](API_REFERENCE.md#indentlist) — nests the current item one level deeper. On a non-list paragraph it starts a bullet list.
+- [`outdentList()`](API_REFERENCE.md#outdentlist) — lifts the current item out one level. Outdenting a top-level (depth 0) item removes the bullet.
+
+On a hardware keyboard, **Tab** and **Shift+Tab** indent and outdent the current item.
+
+Behavior notes:
+
+- **Return continues the list** — pressing Return inside an item starts a new bullet at the same depth on the next line. Pressing Return on an empty item exits the list (the line becomes a regular paragraph).
+- **Backspace at the start of an item** outdents it; at depth 0 it removes the bullet.
+- An emptied list line stays a list item (its bullet keeps showing) until you toggle it off or Backspace out of it, so text you type next continues in the list.
+- The bullet marker exists only in the serialized Markdown and the rendered glyph — it is never part of the editor's text, so it won't collide with `-`-prefixed text such as mentions.
+- **List items are single-line.** Each item is exactly one paragraph. Importing or pasting Markdown with *loose* list items (an item containing multiple paragraphs) keeps only the item's first line as a list item — continuation paragraphs become regular paragraphs, not list-styled blocks.
+
+Whether the cursor's paragraph is a list item, and its nesting depth, are reported through the [`onChangeState`](API_REFERENCE.md#onchangestate) payload as `unorderedList` / `orderedList` (`{ isActive, depth }`), so you can highlight the list buttons in your toolbar.
+
+Use [`markdownStyle.list.itemSpacing`](API_REFERENCE.md#markdownstyle) to add vertical spacing between list items (bullet and numbered alike) so they read as separate rows.
+
 ## Links
 
 Links are a piece of text with a URL attributed to it. They can be managed by calling methods on the input ref:
@@ -126,10 +168,11 @@ When a manual link is applied (via `setLink` or `insertLink`) over an auto-detec
 
 By default the input interprets block-level Markdown: a line starting with `1) `, `- `,
 `# ` or `> ` is consumed as list, heading or quote *structure*, and the marker itself is
-not part of the text. The editor has no block styles to render that structure with and
-the serializer has no way to write the marker back, so the marker is lost on save. Two
-adjacent list items can end up with their formulas touching — `1) $a+b$` and `2) $c+d$`
-save as `$a+b$$c+d$`, where the `$$` now reads as display math.
+not part of the text. Headings and lists are written back on save, but in the editor's
+own form rather than the source's: `1) ` comes back as `1. ` and `* ` as `- `. Other block
+syntax — blockquotes, code blocks, tables, thematic breaks, setext headings — is not
+modeled by the editor and is not guaranteed to survive: depending on the platform its
+marker is either dropped or left in the text.
 
 Set `blockSyntax={false}` when the text must survive the round trip unchanged:
 
@@ -148,8 +191,9 @@ style as usual.
 
 What changes:
 
-- **Typing `3) ` no longer starts a list**, and `# ` no longer makes a heading. Nothing
-  block-level is interpreted while typing either — that is the point of the mode.
+- **Loaded or pasted markers stay text**: `3) ` or `# ` coming in through `defaultValue`,
+  `setValue` or a paste is not turned into a list or heading. Blocks applied explicitly
+  through the toolbar commands still work, and are written back with their markers.
 - The text is displayed with its markers showing, so an editor with `blockSyntax={false}`
   and a `EnrichedMarkdownText` rendering the same source look different, even though the
   stored string is identical.
@@ -205,6 +249,47 @@ The input's content can be copied to the system clipboard from a ref, without re
 
 On iOS and macOS the clipboard receives both plain text and a private Markdown pasteboard type, so pasting back into an `EnrichedMarkdownTextInput` restores the formatting; external apps receive plain text only. On Android the clipboard receives plain text only — inline styles are not preserved for any paste target.
 
+## Intercepting paste
+
+By default a paste goes straight into the buffer. Set [`interceptPaste`](API_REFERENCE.md#interceptpaste) together with [`onPaste`](API_REFERENCE.md#onpaste) to decide what a paste means before any text lands — turning a long paste into an attachment chip, stripping it, or inserting it unchanged.
+
+```tsx
+const inputRef = useRef<EnrichedMarkdownTextInputInstance>(null);
+
+<EnrichedMarkdownTextInput
+  ref={inputRef}
+  interceptPaste
+  onPaste={({ text, markdown }) => {
+    if (text.length > 2000) {
+      attachAsFile(text);
+      inputRef.current?.resolvePaste('', ''); // drops it, and replaces the selection
+      return;
+    }
+    inputRef.current?.resolvePaste(text, markdown);
+  }}
+/>
+```
+
+Native reads the clipboard and **does not touch the buffer**. That makes the handler the only thing that can complete the paste, so the contract is strict:
+
+- Call [`resolvePaste`](API_REFERENCE.md#resolvepastetext-string-markdown-string) **exactly once per event, on every path including failures**. A handler that throws before resolving leaves the paste dropped — the user sees nothing happen.
+- Pass `markdown` back through when inserting. It is the copied formatting; dropping it turns a copy-then-paste inside your app into flat text.
+- `interceptPaste` is ignored unless `onPaste` is set, so switching the prop on alone cannot make the input swallow pastes.
+
+Because nothing is written until you resolve, an async decision is safe: the selection is still there, and the user sees an unchanged input rather than text that vanished.
+
+### Platform behavior
+
+| | Behavior |
+| --- | --- |
+| **iOS** | Context menu and hardware ⌘V. `markdown` is set when the copy source was an `EnrichedMarkdownTextInput`. |
+| **Android** | Context menu, hardware Ctrl+V, `KEYCODE_PASTE`, and a keyboard clipboard chip (Gboard, Samsung Keyboard) — see below. `markdown` is always `''`, and `resolvePaste` inserts `text` verbatim — so an intercepted copy-then-paste inside the app lands as plain text, even though the un-intercepted paste restores the formatting. |
+| **macOS** | `interceptPaste` is ignored, `onPaste` never fires, and pastes insert inline as usual. |
+
+Only clipboard content is intercepted. Drag-and-drop, autofill and IME content insertion bypass `onPaste` on both platforms and insert normally — on Android they are filtered out explicitly, so an autofill never arrives looking like a paste.
+
+On Android a keyboard clipboard chip does not paste through the menu: the keyboard types the text in through the input connection. The input reports it as a paste when the committed text is exactly the current clipboard text and is at least 16 characters long or spans more than one line. Shorter single-line chip pastes, entries from the keyboard's clipboard history other than the current clip, and text the keyboard changes on the way insert inline without `onPaste`.
+
 ## Style Detection
 
 All of the above styles can be detected with the use of [onChangeState](API_REFERENCE.md#onchangestate) callback payload.
@@ -220,6 +305,17 @@ You can find some examples in the [usage section](#usage) or in the example app.
 - [onChangeText](API_REFERENCE.md#onchangetext) - returns the input's plain text (without Markdown syntax) anytime it changes.
 - [onChangeMarkdown](API_REFERENCE.md#onchangemarkdown) - returns the Markdown string parsed from current input text and styles anytime it would change. As parsing the Markdown on each input change can be expensive, not assigning the event's callback will skip the serialization for better performance.
 - [onChangeSelection](API_REFERENCE.md#onchangeselection) - returns `{ start, end }` of the current selection, useful for working with [links](#links).
+- [onKeyPress](API_REFERENCE.md#onkeypress) - returns `{ nativeEvent: { key } }` for every keystroke before it is applied to the content, mirroring React Native TextInput's `onKeyPress`.
+
+## Keyboard Dismissal
+
+`EnrichedMarkdownTextInput` registers with React Native's text-input focus tracking (`TextInput.State`), so scroll containers treat it exactly like the built-in `TextInput`. No props on the input are involved — the behavior is controlled by the surrounding `ScrollView` / `FlatList`:
+
+- With the soft keyboard open, tapping outside the focused input blurs it and dismisses the keyboard, following the scroll container's [`keyboardShouldPersistTaps`](https://reactnative.dev/docs/scrollview#keyboardshouldpersisttaps) setting. In the default `'never'` mode the dismissing tap is consumed (the classic first-tap-dismisses, second-tap-presses behavior); `'handled'` dismisses only on taps no child handles; `'always'` never auto-dismisses.
+- Scrolling does not dismiss the keyboard unless the container sets [`keyboardDismissMode`](https://reactnative.dev/docs/scrollview#keyboarddismissmode).
+- [`Keyboard.dismiss()`](https://reactnative.dev/docs/keyboard#dismiss) blurs the input when it is the focused field.
+
+Matching `TextInput`, none of this applies while a hardware keyboard is in use (for example the iOS Simulator with **Connect Hardware Keyboard** enabled): with no soft keyboard on screen there is nothing to dismiss, so outside taps intentionally leave the input focused.
 
 ## RTL Support
 
@@ -249,7 +345,7 @@ No setup is required. Both platforms autodetect direction per paragraph out of t
 
 - **Placeholder** follows the host view's layout direction, not the prop. If you need an RTL placeholder, wrap the input in `<View style={{ direction: 'rtl' }}>` or set `I18nManager.forceRTL(true)`.
 - **Mixed paragraphs while typing** — newly inserted characters in an empty paragraph briefly inherit the previous paragraph's direction; the first-strong pass corrects this on the next input event.
-- **Code blocks, tables, blockquotes, lists** are not supported in the input (it's a flat inline-formatting surface). For those, use [`EnrichedMarkdownText`](TEXT.md).
+- **Code blocks, tables, blockquotes** are not supported in the input. Headings and bullet lists are; other block elements require [`EnrichedMarkdownText`](TEXT.md).
 
 See [RTL Support](RTL.md) for the full per-element behavior on the rendered output side.
 
@@ -263,6 +359,7 @@ See [RTL Support](RTL.md) for the full per-element behavior on the rendered outp
     strong: { color: '#1D4ED8' },
     em: { color: '#7C3AED' },
     link: { color: '#2563EB', underline: true },
+    h1: { fontSize: 28, fontWeight: 'bold', color: '#111827' },
   }}
 />
 ```
@@ -275,7 +372,9 @@ Available style properties:
 - `link.underline` — whether links are underlined (defaults to `true`).
 - `spoiler.color` — text color for spoiler text.
 - `spoiler.backgroundColor` — background color for spoiler text.
-- `math.fontWeight` — `'bold'` | `'normal'` (default `'normal'`); typesets inline formula chips
+- `h1`–`h6` — per-level heading styling, each accepting `fontSize`, `fontWeight`, and `color`. Defaults match the read-only `EnrichedMarkdownText` renderer (sizes `30/24/20/18/16/14`, bold) so headings look the same in the editor and a rendered preview. Omitted levels (or fields) fall back to those defaults.
+- `inlineMath` / `math` — chip styling for inline (`$...$`) and block (`$$...$$`) LaTeX. Same key names and shared field names as the read-only renderer's `markdownStyle`, so one palette drives both. See [LaTeX Math](LATEX_MATH.md#styling-math-in-the-editor).
+- `inlineMath.fontWeight` — `'bold'` | `'normal'` (default `'normal'`); typesets inline formula chips
   (`$...$`) at bold weight. See [LATEX_MATH.md](./LATEX_MATH.md#bold-formulas).
-- `mathBlock.fontWeight` — same for block formula chips (`$$...$$`); inherits from
-  `math.fontWeight` when unset.
+- `math.fontWeight` — same for block formula chips (`$$...$$`); inherits from
+  `inlineMath.fontWeight` when unset.

package/docs/LATEX_MATH.md

@@ -47,6 +47,39 @@ what pushes those lines apart. It affects only lines that actually contain inlin
 the line height they had. Set it to `0` to get the old flush behaviour back. Block math (`$$...$$`) has its own
 `math.padding` instead.
 
+### Styling math in the editor
+
+`EnrichedMarkdownTextInput` renders each formula as a chip and takes its style
+under the **same two keys**, with the same meaning: `markdownStyle.inlineMath`
+for `$...$` and `markdownStyle.math` for `$$...$$`.
+
+```tsx
+<EnrichedMarkdownTextInput
+  markdownStyle={{
+    inlineMath: { color: '#0F172A', backgroundColor: '#EEF2FF' },
+    math: { fontSize: 22, padding: 12, textAlign: 'center' },
+  }}
+/>
+```
+
+Fields shared with the renderer (`color`, `fontSize`, `backgroundColor`,
+`padding`, `marginTop`, `marginBottom`, `textAlign`) mean the same thing on both
+surfaces, so one palette can drive an editor and its preview. The chip adds
+`borderColor`, `borderWidth`, `borderRadius`, `selectedBackgroundColor` and
+`selectedBorderColor`, which the read-only renderer has no counterpart for, and
+it splits `padding` into `paddingHorizontal` / `paddingVertical` — either of
+which overrides the `padding` shorthand for its axis.
+
+`math` inherits the chip look (colors, border, selection) from `inlineMath`, so
+setting `inlineMath` alone styles both; `math` then overrides what differs.
+
+A formula is **atomic** in the editor: it occupies one character (`U+FFFC`) in the
+buffer, and the LaTeX lives on the chip rather than in the text. That is what makes
+the caret, selection and IME step over a formula in one move — and it is why
+`onChangeText` reports a `U+FFFC` where the formula is, while `onChangeMarkdown`
+reports the `$...$` source. Offsets in `onChangeSelection`, `onCaretRectChange` and
+`updateMath` / `removeMath` count a formula as that one character.
+
 ### Bold formulas
 
 `math.fontWeight` / `inlineMath.fontWeight` (`'normal'` | `'bold'`, default `'normal'`) typeset a
@@ -74,15 +107,16 @@ bold face, so the browser synthesizes one there too. Treat web as synthetic as w
 reference for how heavy bold "should" look.
 
 `EnrichedMarkdownTextInput` honours the same prop for the formula chips typed into the editor, under
-its own style keys — `math.fontWeight` for inline chips (`$...$`) and `mathBlock.fontWeight` for
-block chips (`$$...$$`). `mathBlock` inherits the weight from `math` when it does not set one of its
-own, the way it already inherits `color` and the border props:
+the same two keys as the rest of [Styling math in the editor](#styling-math-in-the-editor) —
+`inlineMath.fontWeight` for inline chips (`$...$`) and `math.fontWeight` for block chips
+(`$$...$$`). `math` inherits the weight from `inlineMath` when it does not set one of its own, the
+way it already inherits `color` and the border props:
 
 ```tsx
 <EnrichedMarkdownTextInput
   markdownStyle={{
-    math: { fontWeight: 'bold' },       // inline chips bold…
-    mathBlock: { fontWeight: 'normal' }, // …block chips opt back out
+    inlineMath: { fontWeight: 'bold' }, // inline chips bold…
+    math: { fontWeight: 'normal' },     // …block chips opt back out
   }}
 />
 ```
@@ -142,57 +176,65 @@ Set `latexMath: false` in `md4cFlags` so the parser treats `$` as plain text:
 
 This alone prevents math rendering without any native changes. The steps below go further by removing the native math libraries from your binary entirely.
 
-### 2. Remove the native iOS dependency
+### 2. Remove the native dependency
 
-Add the following to your Podfile and re-run `pod install`:
+Set `enableMath` to `false` in the `enriched-markdown` block of your app's `package.json`:
 
-```ruby
-ENV['ENRICHED_MARKDOWN_ENABLE_MATH'] = '0'
+```json
+{
+  "enriched-markdown": {
+    "enableMath": false
+  }
+}
 ```
 
-This excludes **RaTeX** from the build. Rebuild the app after running `pod install`.
+This is the single source of truth for both platforms: `postinstall` skips the install-time RaTeX
+download, and the native build reads the same block directly to exclude **RaTeX** from the binary — no
+Podfile or `gradle.properties` edit needed. Re-run `pod install` (iOS) / rebuild (Android) after
+changing it. See [Skipping the download](./NATIVE_ASSETS.md#skipping-the-download-opt-out).
 
 > [!NOTE]
-> When math is **enabled** (the default), your Podfile must use dynamic frameworks:
-> ```ruby
-> use_frameworks! :linkage => :dynamic
-> ```
-> This is required for CocoaPods to resolve the RaTeX Swift Package dependency.
+> **Deprecated:** the `ENV['ENRICHED_MARKDOWN_ENABLE_MATH']` Podfile variable and the
+> `enrichedMarkdown.enableMath` gradle property still work as a fallback but are deprecated and print a
+> warning; they are ignored when the `package.json` block sets `enableMath`.
 
 > [!NOTE]
-> **macOS**: LaTeX math is currently not supported on macOS because `react-native-macos` does not support `use_frameworks!` ([microsoft/react-native-macos#1969](https://github.com/microsoft/react-native-macos/issues/1969)). Math is automatically disabled in the macOS example app.
-
-### 3. Remove the native Android dependency
-
-Add the following to your project's `gradle.properties`:
-
-```properties
-enrichedMarkdown.enableMath=false
-```
-
-This excludes **RaTeX** from the Android build. Rebuild the app after changing this property.
+> When math is **enabled** (the default), no special Podfile configuration is required.
+> RaTeX ships as a prebuilt static XCFramework vendored into the pod, so it links under
+> CocoaPods default static linkage — you do **not** need `use_frameworks!`. (Earlier
+> versions required `use_frameworks! :linkage => :dynamic` to resolve RaTeX as a Swift
+> Package; that is no longer the case.)
 
-### 4. Expo config plugin
+> [!NOTE]
+> The RaTeX XCFramework is **not** bundled in the npm tarball — it is downloaded at install time by
+> a `postinstall` script (see [Native assets](./NATIVE_ASSETS.md)). If `ios/vendor/RaTeX.xcframework`
+> is missing (offline install, `--ignore-scripts`, pnpm, or a `package.json` opt-out) and math is only
+> on by default, `pod install` auto-disables math and prints a warning instead of failing. If you
+> **explicitly** set `"enableMath": true`, a missing framework is a hard error instead. Either way, run
+> `node node_modules/react-native-enriched-markdown-scaffold/postinstall.mjs` and re-run `pod install` to restore it.
 
-If you are using Expo, you can use the built-in config plugin to disable LaTeX math rendering on both platforms at once.
+> [!IMPORTANT]
+> **Upgrading from a version that used `use_frameworks! :linkage => :dynamic` for math?**
+> The pod changed from a dynamic framework to a static library. After `pod install`,
+> do a one-time clean build (Xcode: Product > Clean Build Folder, or delete the app's
+> DerivedData) — a stale build folder otherwise fails with
+> `ReactNativeEnrichedMarkdown.framework/Modules/module.modulemap not found`. Fresh
+> installs are unaffected.
 
-Add the following to your `app.json` or `app.config.js`:
+> [!NOTE]
+> **macOS**: LaTeX math is not yet enabled on macOS and remains off in the macOS example
+> app. The previous blocker (`use_frameworks!` was required for the RaTeX Swift Package)
+> no longer applies now that RaTeX is a vendored XCFramework with a macOS slice, so macOS
+> support is a possible future follow-up.
 
-```json
-{
-  "expo": {
-    "plugins": [
-      [
-        "react-native-enriched-markdown",
-        {
-          "enableMath": false
-        }
-      ]
-    ]
-  }
-}
-```
+### 3. Expo
 
-This will automatically apply both the [iOS](#2-remove-the-native-ios-dependency) and [Android](#3-remove-the-native-android-dependency) native changes listed above during `npx expo prebuild`.
+The `package.json` block above works with Expo too — `node_modules` (and the resolved config) survive
+`npx expo prebuild`, so no config plugin is needed. Set `"enriched-markdown": { "enableMath": false }` in
+your app's `package.json` and rebuild.
 
-If you later re-enable math (e.g. remove the plugin or set `enableMath: true`), run `npx expo prebuild --clean` so native projects are regenerated without the disable flags, then rebuild.
+> [!NOTE]
+> Because `enableMath` is a compile/link-time decision, it only applies in builds you compile yourself
+> (a custom dev client or `expo prebuild`). It **cannot** be changed in **Expo Go**, which ships a fixed
+> prebuilt binary. A dedicated config plugin was removed in favor of the `package.json` block — see
+> [Breaking changes](./BREAKING_CHANGES.md).

package/docs/MACOS.md

@@ -1,6 +1,6 @@
 # macOS Support
 
-`react-native-enriched-markdown` supports macOS via [react-native-macos](https://github.com/microsoft/react-native-macos). The native layer shares code with iOS through a platform abstraction header (`ENRMUIKit.h`), with macOS-specific implementations for context menus, text selection, and clipboard handling.
+`react-native-enriched-markdown-scaffold` supports macOS via [react-native-macos](https://github.com/microsoft/react-native-macos). The native layer shares code with iOS through a platform abstraction header (`ENRMUIKit.h`), with macOS-specific implementations for context menus, text selection, and clipboard handling.
 
 The macOS implementation supports the same rendering elements as iOS — CommonMark, GitHub Flavored Markdown (tables, task lists, strikethrough), images, code blocks, blockquotes, and all other supported elements. `EnrichedMarkdownTextInput` is also available on macOS with full support for inline styles, links, and the native context menu.
 

package/docs/MARKDOWN_STREAMING.md

@@ -1,6 +1,6 @@
 # Markdown Streaming
 
-If you need to render markdown that streams token-by-token from an LLM, check out [react-native-streamdown](https://github.com/software-mansion-labs/react-native-streamdown) — a streaming-ready markdown component built on top of `react-native-enriched-markdown`.
+If you need to render markdown that streams token-by-token from an LLM, check out [react-native-streamdown](https://github.com/software-mansion-labs/react-native-streamdown) — a streaming-ready markdown component built on top of `react-native-enriched-markdown-scaffold`.
 
 It combines [remend](https://www.npmjs.com/package/remend) for fixing incomplete markdown on the fly with [react-native-worklets](https://docs.swmansion.com/react-native-worklets/) **Bundle Mode** to run all processing off the JS thread, keeping your UI responsive while tokens arrive.
 
@@ -34,3 +34,29 @@ The `streamingConfig` prop controls this behavior:
 | `'progressive'` (default) | Renders the table row-by-row as content arrives. New rows fade in when `streamingAnimation` is enabled. Incomplete trailing rows are automatically trimmed. |
 | `'hidden'` | The table is completely hidden until it is followed by a blank line, indicating the table is complete. Prevents visual jank from partially formed tables. |
 
+## Code Block Streaming (GFM)
+
+Fenced code blocks are also block-level elements. While a block's closing fence
+(```` ``` ````) has not arrived, its content is still changing, which would
+otherwise make syntax highlighting flicker on every token.
+
+The `codeBlockMode` field of `streamingConfig` controls this:
+
+```tsx
+<EnrichedMarkdownText
+  markdown={streamingMarkdown}
+  flavor="github"
+  streamingAnimation
+  streamingConfig={{ codeBlockMode: 'progressive' }}
+/>
+```
+
+### Code Block Modes
+
+| Mode | Behavior |
+|---|---|
+| `'progressive'` (default) | The code streams in line-by-line with its header (language label + copy button) visible but non-interactive — copying is disabled until the block completes. Syntax highlighting is deferred so it applies once when the closing fence arrives instead of flickering per token. |
+| `'hidden'` | The entire code block is hidden until its closing fence arrives, then it appears complete (the same all-or-nothing behavior block math uses). |
+
+Both modes only take effect when `streamingAnimation` is `true`.
+

package/docs/MENTIONS.md

@@ -69,7 +69,14 @@ linkVariants: {
 }
 ```
 
-Each key is a regex tested against the link URL. First match wins. Unspecified properties inherit from the base `link` style. Patterns are auto-sorted longest-first.
+Each key is a regex tested against the link URL. First match wins. Patterns are auto-sorted longest-first.
+
+Inheritance from the base `link` style is split in two groups:
+
+- **Text** (`color`, `underline`): unspecified properties inherit from `link`.
+- **Box** (`backgroundColor`, `borderRadius`, `paddingHorizontal`, `paddingVertical`, `borderColor`, `borderWidth`): never inherited. A variant that sets none of them renders without a chip, even when `link` is a chip.
+
+`fontFamily` is only configurable on `link` and applies to every variant. See [Link chips](STYLES.md#link-chips) for the box properties.
 
 ## Positioning the Suggestion List
 

package/docs/NATIVE_ASSETS.md

@@ -0,0 +1,127 @@
+# Native assets (install-time download)
+
+Two pieces of the library's native layer are large prebuilt/vendored assets: the
+tree-sitter runtime and grammar sources used for [code-block highlighting](./CODE_HIGHLIGHT.md)
+(~170 MB of C source across every supported grammar) and the RaTeX static XCFramework used for
+[iOS LaTeX math](./LATEX_MATH.md) (~47 MB). Shipping them inside the npm tarball would make every
+install download ~230 MB even for apps that use neither feature.
+
+Instead they are **downloaded once at install time** by a `postinstall` script, keeping the
+published package small (~1 MB packed / ~7.5 MB unpacked). The download is verified by sha256 and is
+idempotent — a `.stamp` fingerprint in each vendor directory makes repeated installs a no-op.
+
+## What gets downloaded, and from where
+
+| Asset | Source | Used by |
+|---|---|---|
+| tree-sitter runtime | GitHub release tarball (`github.com/tree-sitter/tree-sitter`) | code highlighting (iOS + Android) |
+| grammar sources (`parser.c`/`scanner.c`/`highlights.scm`) | npm registry (`registry.npmjs.org`) | code highlighting (iOS + Android) |
+| RaTeX XCFramework + fonts | GitHub release (`github.com/erweixin/RaTeX`) | LaTeX math (iOS only) |
+
+The pins live in `grammar-versions.json` and `ratex-version.json` inside the installed package. The
+pre-built highlight registry for the default language set **is** shipped in the tarball, so the only
+thing fetched for a default build is the grammar C source it compiles.
+
+Files land under `node_modules/react-native-enriched-markdown-scaffold/` in
+`cpp/highlight/vendor/` (grammars + runtime) and `ios/vendor/` (RaTeX). Because this runs during
+`npm install` / `yarn add`, the assets are in place before `pod install` or the Android build reads
+them.
+
+## Requirements
+
+- **Network access at install time** to `registry.npmjs.org` and `github.com`.
+- `tar` (present on macOS, Linux, and Windows 10+). RaTeX also needs `unzip`; it is absent on stock
+  Windows, but RaTeX is iOS-only so this only affects Windows dev machines and is non-fatal.
+
+The postinstall step **never fails the install**: if a download does not complete it prints a warning
+and exits successfully. What the native build does when an asset is missing depends on whether you
+**explicitly enabled** the feature in your app `package.json`:
+
+- **On by default** (no `enriched-markdown` entry for it): the build treats the feature as disabled —
+  code highlighting compiles a no-op stub, iOS math is skipped with a CocoaPods warning — so the build
+  stays green.
+- **Explicitly enabled** (`"enableMath": true` / `"enableCodeHighlight": true`): the build **fails with
+  an actionable error** telling you to re-run postinstall, because you asked for a feature whose assets
+  are not present.
+
+To fix a missing download, re-run the recovery command below.
+
+## Re-running or recovering
+
+If a download didn't complete (offline, behind a firewall, or with scripts disabled), reinstall the
+package to re-fetch the assets:
+
+```sh
+npm rebuild react-native-enriched-markdown-scaffold
+```
+
+If your package manager blocks or skips that (pnpm, Yarn PnP, `--ignore-scripts`), run the vendor script
+directly from your project root as a fallback:
+
+```sh
+node node_modules/react-native-enriched-markdown-scaffold/postinstall.mjs
+```
+
+Then re-run `pod install` (iOS) or rebuild (Android).
+
+## Package-manager notes
+
+- **npm / Yarn Classic / Yarn Berry (node-modules linker)**: works out of the box.
+- **pnpm**: recent pnpm blocks dependency lifecycle scripts by default. Allow this package to run its
+  `postinstall` so the assets download — for example:
+
+  ```yaml
+  # pnpm-workspace.yaml (or package.json "pnpm" field)
+  onlyBuiltDependencies:
+    - react-native-enriched-markdown-scaffold
+  ```
+
+  Without this the native build fails until you run the recovery command above.
+- **Yarn PnP** is not supported for this package — PnP stores dependencies as read-only archives, so
+  the postinstall cannot write the vendored assets into the package. Use the `node-modules` linker
+  (`nodeLinker: node-modules`), which is the norm for React Native projects anyway.
+- **`--ignore-scripts`**: the assets will not download. Run the recovery command above afterward.
+
+## Skipping the download (opt out)
+
+If you don't use a feature, opt out in **your app's `package.json`** so the postinstall never
+downloads its assets. Add an `enriched-markdown` block (both fields default to `true`):
+
+```json
+{
+  "enriched-markdown": {
+    "enableCodeHighlight": false,
+    "enableMath": false
+  }
+}
+```
+
+`enableCodeHighlight: false` skips the tree-sitter runtime + grammar download (iOS and Android);
+`enableMath: false` skips the RaTeX download (iOS; Android math uses a Maven dependency and is
+unaffected). The native build reads the same `enriched-markdown` block directly (iOS podspec /
+Android `build.gradle`), so a `package.json` opt-out **also disables the feature at build time** — no
+Podfile or `gradle.properties` edit needed. Disabling takes effect on the next `pod install` / native
+rebuild; re-enabling also needs a reinstall so the assets download again.
+
+> [!IMPORTANT]
+> **Applying a change on iOS.** The podspec reads `package.json` at `pod install` time, not at build
+> time, so a plain rebuild (`run-ios` / Xcode build) reuses the previously resolved pod — you must run
+> `pod install` after editing the `enriched-markdown` block. And when you **change a feature that was
+> already compiled in** (disabling it, or narrowing `codeHighlightLanguages`), also do a **clean build**
+> (`Product > Clean Build Folder`, or delete the app's DerivedData): Xcode's incremental build does not
+> reliably rebuild the pod's static library when only its source list changes, so it can otherwise link a
+> stale copy that still contains the old code. Android reconfigures on every build and needs neither step.
+
+**Which `package.json`?** The *download* opt-out is read from wherever the install runs (via `INIT_CWD`)
+— in a monorepo that is the workspace root, and there is one shared `node_modules`, so the download
+opt-out is global. The *build* flag is read from the **app's** `package.json` (the one beside `ios/` /
+`android/`), so each app in a monorepo enables or disables features independently. Neither has any
+effect inside this repo's own monorepo development.
+
+## Disabling the features at build time
+
+You can also disable a feature purely at build time (assets stay downloaded but are never
+compiled/linked):
+
+- Code highlighting: see [Choosing languages / reducing binary size](./CODE_HIGHLIGHT.md#choosing-languages--reducing-binary-size).
+- LaTeX math: see [Disabling LaTeX Math](./LATEX_MATH.md#disabling-latex-math-reducing-bundle-size).

package/docs/RTL.md

@@ -1,6 +1,6 @@
 # RTL Support
 
-`react-native-enriched-markdown` resolves writing direction **per paragraph** on both platforms: each paragraph picks its own base direction from its first strong directional character. Arabic, Hebrew, and Persian content right-aligns automatically, even inside an LTR app and even when mixed with English paragraphs in the same document.
+`react-native-enriched-markdown-scaffold` resolves writing direction **per paragraph** on both platforms: each paragraph picks its own base direction from its first strong directional character. Arabic, Hebrew, and Persian content right-aligns automatically, even inside an LTR app and even when mixed with English paragraphs in the same document.
 
 This document describes the read-only [`EnrichedMarkdownText`](TEXT.md) renderer. The rich [`EnrichedMarkdownTextInput`](INPUT.md#rtl-support) follows the same per-paragraph rules — see its [RTL section](INPUT.md#rtl-support) for input-specific caveats (placeholder, code blocks, etc.).