react-native-enriched-markdown-scaffold 0.7.4-scaffold.8 → 1.0.2-scaffold.1

package/docs/COPY_OPTIONS.md

@@ -1,6 +1,6 @@
 # Copy Options
 
-When text is selected, `react-native-enriched-markdown` provides enhanced copy functionality through the context menu on both platforms.
+When text is selected, `react-native-enriched-markdown-scaffold` provides enhanced copy functionality through the context menu on both platforms.
 
 ## Smart Copy
 
@@ -44,6 +44,19 @@ Use `selectionMenuConfig` to hide built-in selection menu actions while keeping
 />
 ```
 
+To turn the menu off entirely rather than item by item, use `contextMenuHidden`:
+
+```tsx
+// No selection menu at all — text is still selectable
+<EnrichedMarkdownText markdown={content} contextMenuHidden />
+```
+
+The two are complementary: `selectionMenuConfig` prunes individual built-in
+items and leaves the menu in place, while `contextMenuHidden` suppresses the
+menu as a whole — including `contextMenuItems` and the copy menus on table,
+code and math blocks. Note that `contextMenuHidden` applies to `EnrichedMarkdownText`
+only; it does not affect `EnrichedMarkdownTextInput`.
+
 `EnrichedMarkdownTextInput` supports the same `{ enabled, label }` shape. In addition to `copyAsMarkdown`, the input's `selectionMenuConfig` exposes the built-in **Format** submenu, and `formatMenuConfig` controls the items inside it:
 
 ```tsx
@@ -93,8 +106,13 @@ Notes:
   plural category (`zero`, `one`, `two`, `few`, `many`, `other`). Only `other` is
   required; any category left `undefined` falls back to it. The `{count}` token
   is replaced by the number of selected images.
-- The labels apply to the main text selection menu as well as the table and math
-  block copy menus.
+- The labels apply to the main text selection menu as well as the table, math,
+  and code block copy menus. With `flavor="github"`, the code block header's copy
+  button also reuses the copy label for assistive technologies (the CommonMark
+  flavor renders code inline with no header button): it is the button's
+  contentDescription on Android, and on iOS it names the VoiceOver custom
+  action that triggers the copy. To be notified when code is copied from a code
+  block, use the [`onCopyPress`](./API_REFERENCE.md#oncopypress) callback.
 - OS-provided actions (Look Up, Translate…) and the system **Cut / Paste /
   Select All** items are localized by the platform and are not affected by this
   config.

package/docs/ELEMENTS_STRUCTURE.md

@@ -1,10 +1,10 @@
 # Element Structure
 
-Markdown elements in `react-native-enriched-markdown` are organized into block and inline categories, each with distinct rendering behaviors.
+Markdown elements in `react-native-enriched-markdown-scaffold` are organized into block and inline categories, each with distinct rendering behaviors.
 
 ## Supported Markdown Elements
 
-`react-native-enriched-markdown` supports a comprehensive set of Markdown elements:
+`react-native-enriched-markdown-scaffold` supports a comprehensive set of Markdown elements:
 
 ### Block Elements
 
@@ -13,7 +13,7 @@ Markdown elements in `react-native-enriched-markdown` are organized into block a
 | Headings | `# H1` to `###### H6` | `h1` - `h6` | Six levels of headings |
 | Paragraphs | Plain text | `paragraph` | Default text container |
 | Blockquotes | `> Quote` | `blockquote` | Quoted content with accent bar, unlimited nesting |
-| Code Blocks | ` ``` code ``` ` | `codeBlock` | Multi-line code containers |
+| Code Blocks | ` ``` code ``` ` | `codeBlock` | Multi-line code containers; with `flavor="github"` rendered as a block component with a language header and copy-code button |
 | Unordered Lists | `- Item`, `* Item`, or `+ Item` | `list` | Bullet lists with unlimited nesting |
 | Ordered Lists | `1. Item` | `list` | Numbered lists with unlimited nesting |
 | Task Lists | `- [x] Done`, `- [ ] Todo` | `taskList` | Interactive checkboxes (requires `flavor="github"`) |
@@ -60,6 +60,22 @@ Markdown elements in `react-native-enriched-markdown` are organized into block a
 2. Second item
 ```
 
+### Lists with Block Content Example
+
+List items can contain block elements — fenced code blocks, nested lists, and multiple paragraphs:
+
+````markdown
+1. Install via npm:
+
+   ```
+   npm install
+   ```
+
+2. Verify the connection.
+````
+
+Code blocks indent to the item's content column, and the marker is drawn next to the first line even when a code block or nested list is the item's first child.
+
 ### Nested Blockquotes Example
 
 ```markdown
@@ -94,6 +110,38 @@ Block elements are structural containers that define the layout and establish th
 
 Inline elements modify text within blocks and apply additional styling on top of the block's typography.
 
+## Line Breaks
+
+Newlines follow standard CommonMark semantics by default:
+
+- **Blank line**: Starts a new paragraph.
+- **Single newline (soft break)**: Renders as a space — consecutive lines flow together into one wrapped paragraph, matching how GitHub and other CommonMark renderers display Markdown.
+- **Hard break**: Ends a line with two spaces or a backslash to force a line break within the paragraph.
+
+```markdown
+This line and
+this line render as one continuous sentence.
+
+A blank line starts a new paragraph.
+
+Two trailing spaces  
+or a trailing backslash\
+force a line break within the paragraph.
+```
+
+### Preserving single newlines
+
+When displaying content authored in `EnrichedMarkdownTextInput`, pressing Enter produces a single newline in the serialized markdown. By default, `EnrichedMarkdownText` collapses these to spaces (per CommonMark). To preserve them as visible line breaks, enable the `hardSoftBreaks` flag:
+
+```tsx
+<EnrichedMarkdownText
+  markdown={markdownFromInput}
+  md4cFlags={{ hardSoftBreaks: true }}
+/>
+```
+
+This forces the parser to treat every soft break as a hard break, so single newlines render as line breaks on all platforms.
+
 ## Images: Block vs Inline
 
 Images are automatically detected as block or inline based on context:
@@ -101,7 +149,7 @@ Images are automatically detected as block or inline based on context:
 - **Block images**: When an image is the only content in a paragraph (standalone), it's treated as a block image and uses block-level spacing
 - **Inline images**: When an image appears alongside other text content, it's treated as inline and aligns with the text baseline
 
-You don't need to specify which type—the renderer automatically determines this based on the image's position in the content.
+You don't need to specify which type—the renderer automatically determines this based on the image's position in the content. Note that a single newline doesn't split a paragraph, so an image on its own source line directly below text is still inline; separate it with a blank line to make it a block image.
 
 ## Nested Elements
 

package/docs/IMAGE_CACHING.md

@@ -2,6 +2,30 @@
 
 Images in Markdown content are loaded, cached, and reused automatically — no configuration required.
 
+## Supported Image Sources
+
+Markdown image URLs are strings, so bundled assets must be resolved to a URI before being interpolated into the markdown:
+
+```tsx
+import { Image } from 'react-native';
+
+const logoUri = Image.resolveAssetSource(require('./assets/logo.png')).uri;
+const markdown = `![Logo](${logoUri})`;
+```
+
+This works in every environment: in dev the URI is a Metro dev-server URL, while in a release build it resolves to a drawable resource name on Android and a bundle `file://` URL on iOS — all of which are supported. URIs from `expo-asset` (`asset.uri` / `asset.localUri`) work the same way.
+
+| Source | Android | iOS / macOS |
+|---|---|---|
+| `http://`, `https://` | Yes | Yes |
+| `file://` (including percent-encoded paths) | Yes | Yes |
+| Bare asset name (release builds, expo-asset `localUri`) | Yes (drawable/raw resource) | Yes (bundle resource) |
+| `file:///android_res/…`, `file:///android_asset/…` | Yes | No |
+| `asset://`, `res://`, `content://` | Yes | No |
+| `data:` (base64) | Yes | Yes |
+
+Local sources skip the HTTP layers below (disk cache, request headers, deduplication) but still use both memory cache tiers.
+
 ## Cache Layers
 
 The library uses a three-tier caching strategy on both platforms:
@@ -16,6 +40,12 @@ The library uses a three-tier caching strategy on both platforms:
 - **Processed cache** stores scaled and clipped variants keyed by URL + dimensions + border radius, so repeated layouts with the same geometry skip all image processing.
 - **Disk cache** persists raw HTTP responses across app launches, respecting standard HTTP cache headers.
 
+## Request Headers
+
+When `imageRequestHeaders` is set, the headers become part of the cache identity for both memory tiers and for request deduplication: the same URL requested with different headers is fetched and cached separately, and changing the prop re-fetches the images.
+
+One caveat: the disk cache is managed by the HTTP stack (OkHttp / `NSURLCache`) and keys responses by URL alone. A response fetched with one set of headers can be served from disk for a request with different headers, subject to standard HTTP caching semantics (`Cache-Control`, `Vary`).
+
 ## Request Deduplication
 
 When multiple components request the same image URL simultaneously (e.g. during a re-render), only one network request is made. All pending callbacks are coalesced and dispatched together once the download completes.

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:
@@ -122,6 +164,52 @@ The callback fires only for newly detected links — not for links that were alr
 
 When a manual link is applied (via `setLink` or `insertLink`) over an auto-detected link, the auto-detected link is replaced by the manual one. Auto-link detection skips ranges that already contain a manual link.
 
+## Preserving block syntax
+
+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. 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:
+
+```tsx
+<EnrichedMarkdownTextInput
+  blockSyntax={false}
+  defaultValue={markdown}
+  onChangeMarkdown={setMarkdown}
+/>
+```
+
+In this mode the parser never sees block structure, so markers stay in the text verbatim
+and `onChangeMarkdown` returns what was loaded, byte for byte. Inline syntax is unaffected:
+`**bold**`, `*italic*`, `~~strike~~`, `||spoiler||`, links and `$math$` all still parse and
+style as usual.
+
+What changes:
+
+- **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.
+- `\r\n` and `\r` are normalized to `\n`, and `U+000B` (vertical tab) is stripped from the
+  input. `U+000B` is used internally to hide line structure from the Markdown parser, so it
+  cannot be carried through as content.
+
+Three inline constructs are still lossy in this mode, exactly as they are with
+`blockSyntax={true}` — they are not regressions introduced by the flag:
+
+| Input | Saved as | Why |
+| --- | --- | --- |
+| `` gõ `x` vào `` | `gõ x vào` | The editor has no inline code style, so the backticks have nothing to round-trip through |
+| `Giá 5\$` | `Giá 5$` | The serializer does not re-escape `\$`, which can leave an unpaired `$` |
+| `A &amp;amp; B` | `A  B` | HTML entity nodes are dropped. A raw `&` is safe |
+
 ## Caret Position Tracking
 
 `EnrichedMarkdownTextInput` can report the caret's pixel position relative to the input, which is useful when the input is embedded in a scrollable container with `scrollEnabled={false}` and you need to keep the caret visible.
@@ -161,6 +249,45 @@ 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 and `KEYCODE_PASTE`. `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.
+
 ## Style Detection
 
 All of the above styles can be detected with the use of [onChangeState](API_REFERENCE.md#onchangestate) callback payload.
@@ -176,6 +303,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
 
@@ -205,7 +343,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.
 
@@ -219,6 +357,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' },
   }}
 />
 ```
@@ -231,7 +370,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`.
+