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

package/docs/API_REFERENCE.md

@@ -77,6 +77,51 @@ Callback when a task list checkbox is tapped. Receives `index` (0-based), `check
 | ----------------------------------------------- | ------------- | -------- |
 | `(event: TaskListItemPressEvent) => void`      | -             | Both     |
 
+### `enableTaskListItemToggle`
+
+Controls whether tapping a task list checkbox toggles its checked state.
+
+When `false`, the checkbox renders its markdown state read-only and the tap is **fully inert** — there is no visual toggle and `onTaskListItemPress` does not fire. Text selection and links in the same row are unaffected.
+
+| Type      | Default Value | Platform          |
+| --------- | ------------- | ----------------- |
+| `boolean` | `true`        | Both, Web         |
+
+**Example:**
+
+```tsx
+// Render checkboxes that reflect the markdown but cannot be toggled by the user
+<EnrichedMarkdownText
+  markdown={content}
+  flavor="github"
+  enableTaskListItemToggle={false}
+/>
+```
+
+> **Note:** On web the checkbox keeps its normal appearance and is marked `readOnly` / `aria-disabled` rather than `disabled`, so it stays visually consistent with iOS and Android. It is also made pointer-inert (`pointer-events: none`), so the browser paints no hover or active state on a checkbox that cannot be toggled.
+
+### `onCopyPress`
+
+Callback when code is copied from a fenced code block, via the header copy button, the long-press context-menu **Copy** action, or the VoiceOver copy action. Receives `code` (the copied code) and `language` (the fence language, or `""` if none). Does not fire for **Copy as Markdown**.
+
+Only fires when `flavor="github"` — the copy button is part of the GitHub flavor's code block renderer.
+
+| Type                                  | Default Value | Platform         |
+| ------------------------------------- | ------------- | ---------------- |
+| `(event: CopyPressEvent) => void`     | -             | Both, macOS      |
+
+**Example:**
+
+```tsx
+<EnrichedMarkdownText
+  flavor="github"
+  markdown={"```ts\nconst x = 1;\n```"}
+  onCopyPress={({ code, language }) => {
+    console.log(`Copied ${language} code:`, code);
+  }}
+/>
+```
+
 ### `enableLinkPreview`
 
 Controls the native link preview on long press (iOS only). Automatically set to `false` when `onLinkLongPress` is provided.
@@ -105,6 +150,37 @@ Whether text can be selected.
 | --------- | ------------- | -------- |
 | `boolean` | `true`         | Both     |
 
+### `contextMenuHidden`
+
+Hides the text selection context menu. Text stays selectable — only the menu is
+suppressed. This is deliberately different from `selectable={false}`, which
+disables selection altogether and, on Android, also removes the text from the
+TalkBack focus order.
+
+| Type      | Default Value | Platform    |
+| --------- | ------------- | ----------- |
+| `boolean` | `false`       | Both, macOS |
+
+```tsx
+// Text can still be selected, but long-press shows no menu
+<EnrichedMarkdownText markdown={content} contextMenuHidden />
+```
+
+Notes:
+
+- It hides the **whole** menu. The custom items from `contextMenuItems` and the
+  built-in items from `selectionMenuConfig` share that same menu, so they are
+  hidden too. To drop individual items instead, use `selectionMenuConfig`.
+- It also covers the separate copy menus on table, code and math blocks (which
+  appear with `flavor="github"`), not just the text selection menu. The copy
+  button in a code block's header is a visible control, not a menu, and stays.
+- It does **not** suppress the system "Save to Camera Roll / Copy" sheet that
+  UIKit shows when long-pressing an image — that sheet is owned by UIKit.
+- On macOS the menu opens on click-with-selection rather than long-press; the
+  prop suppresses it the same way.
+- Applies to `EnrichedMarkdownText` only — it does not affect
+  `EnrichedMarkdownTextInput`.
+
 ### `selectionColor`
 
 Color of the text selection highlight. On iOS, this also affects the caret and selection handle colors (they share a single tint). On macOS, only the selection background is affected. On Android, use `selectionHandleColor` to override the handle color independently.
@@ -127,7 +203,7 @@ Configuration for md4c parser extension flags.
 
 | Type          | Default Value            | Platform |
 | ------------- | ------------------------ | -------- |
-| `Md4cFlags`   | `{ underline: false, superscript: false, subscript: false, highlight: false, latexMath: true }` | Both |
+| `Md4cFlags`   | `{ underline: false, superscript: false, subscript: false, highlight: false, latexMath: true, hardSoftBreaks: false }` | Both |
 
 **Properties:**
 
@@ -136,6 +212,7 @@ Configuration for md4c parser extension flags.
 - **`subscript`**: When `true`, parses `~text~` as subscript. When disabled, single and double tildes remain strikethrough markers. Visual appearance can be tuned with the `subscript` style prop — see [Subscript-specific](./STYLES.md#subscript-specific).
 - **`highlight`**: When `true`, parses `==text==` as highlighted spans. When disabled, double equals signs are treated as plain text. Visual appearance can be tuned with the `highlight` style prop — see [Highlight-specific](./STYLES.md#highlight-specific).
 - **`latexMath`**: When `true`, parses `$...$` and `$$...$$` as LaTeX math spans.
+- **`hardSoftBreaks`**: When `true`, treats single newlines (soft breaks) as hard breaks, rendering them as visible line breaks instead of collapsing them to spaces. Useful when displaying content authored in `EnrichedMarkdownTextInput`, where pressing Enter produces a single newline. See [Line Breaks](./ELEMENTS_STRUCTURE.md#line-breaks) for details.
 
 **Example:**
 
@@ -150,6 +227,12 @@ Configuration for md4c parser extension flags.
   markdown="This is _underlined_ and *italic* text"
   md4cFlags={{ underline: true }}
 />
+
+// Preserve single newlines as visible line breaks
+<EnrichedMarkdownText
+  markdown={markdownFromInput}
+  md4cFlags={{ hardSoftBreaks: true }}
+/>
 ```
 
 ### `allowFontScaling`
@@ -233,7 +316,7 @@ Code blocks are always rendered left-to-right regardless of this prop. Per-parag
 
 ### `flavor`
 
-Markdown flavor. Set to `'github'` to enable GitHub Flavored Markdown table support.
+Markdown flavor. Set to `'github'` to enable GitHub Flavored Markdown features: tables and block-style code blocks.
 
 | Type                              | Default Value   | Platform |
 | --------------------------------- | --------------- | -------- |
@@ -241,7 +324,9 @@ Markdown flavor. Set to `'github'` to enable GitHub Flavored Markdown table supp
 
 > **Note:** 
 > - **`'commonmark'`**: All Markdown content is rendered as a single TextView. Selecting text will select all content in the view.
-> - **`'github'`**: The Markdown AST is split into segments. Consecutive text blocks (paragraphs, headings, lists, etc.) are grouped into separate TextView segments, while tables are rendered as separate table views. This allows for granular text selection within each segment and enables interactive table features (horizontal scrolling, context menus). Text selection cannot span across segments.
+> - **`'github'`**: The Markdown AST is split into segments. Consecutive text blocks (paragraphs, headings, lists, etc.) are grouped into separate TextView segments, while tables, fenced code blocks, and math blocks are rendered as separate block views. This allows for granular text selection within each segment and enables interactive block features (horizontal table scrolling, context menus, the code block header). Text selection cannot span across segments.
+>
+> With `'github'`, a fenced code block renders as a dedicated component: a header bar with the language display name (` ```python ` shows "Python") and a copy-code button, a divider, and the code below. Long lines do not wrap — the code pane scrolls horizontally while the header stays fixed. Long-pressing the block opens the Copy / Copy as Markdown menu. With `'commonmark'`, code blocks stay inside the single TextView, styled via spans, and long lines wrap.
 
 ### `streamingAnimation`
 
@@ -253,11 +338,11 @@ When `true`, newly appended content fades in during streaming updates. Only the
 
 ### `streamingConfig`
 
-Configuration for streaming behavior. Currently controls how incomplete tables are handled during streaming with `flavor="github"`.
+Configuration for streaming behavior. Controls how incomplete tables and fenced code blocks are handled during streaming with `flavor="github"`.
 
-| Type                    | Default Value            | Platform |
-| ----------------------- | ------------------------ | -------- |
-| `{ tableMode: string }` | `{ tableMode: 'progressive' }` | Both     |
+| Type                                        | Default Value                                          | Platform |
+| ------------------------------------------- | ------------------------------------------------------ | -------- |
+| `{ tableMode?: string, codeBlockMode?: string }` | `{ tableMode: 'progressive', codeBlockMode: 'progressive' }` | Both     |
 
 #### `tableMode`
 
@@ -275,6 +360,15 @@ Controls how incomplete (still-streaming) tables are rendered:
 />
 ```
 
+#### `codeBlockMode`
+
+Controls how a fenced code block whose closing fence has not arrived yet is rendered:
+
+- **`'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 until the closing fence arrives, so it applies once instead of flickering on every 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`.
+
 ### `spoilerOverlay`
 
 Controls how spoiler text (`||hidden text||`) is displayed before being revealed.
@@ -288,6 +382,29 @@ Controls how spoiler text (`||hidden text||`) is displayed before being revealed
 
 Both modes support tap-to-reveal.
 
+### `imageRequestHeaders`
+
+HTTP headers attached to remote image requests, e.g. a `Referer` required by CDN hotlink protection or an `Authorization` token.
+
+| Type                     | Default Value | Platform |
+| ------------------------ | ------------- | -------- |
+| `Record<string, string>` | -             | Both     |
+
+Headers participate in image cache identity, so the same URL requested with different headers is fetched and cached separately — see [Image Caching](./IMAGE_CACHING.md).
+
+> **Web**: Not supported — browsers don't allow custom headers on `<img>` requests.
+
+**Example:**
+
+```tsx
+<EnrichedMarkdownText
+  markdown={markdown}
+  imageRequestHeaders={{
+    Referer: 'https://example.com',
+  }}
+/>
+```
+
 ### `contextMenuItems`
 
 Custom items to add to the text selection context menu. Items appear before the system actions (Copy, etc.). Items with `visible: false` are hidden from the menu.
@@ -352,7 +469,7 @@ Controls built-in actions added to the native text selection menu. Custom app-pr
 | -------------------- | ---------------------------------------------- | -------- |
 | `SelectionMenuConfig` | `{}` (see shape below for per-field defaults) | iOS, Android, macOS |
 
-Each item takes an object: `{ enabled }` toggles visibility (the system `copy` item can't be hidden — only relabeled) and `label` overrides the English default. The labels apply to the main text selection menu as well as the table and math block copy menus.
+Each item takes an object: `{ enabled }` toggles visibility and `label` overrides the English default. Items and labels apply to the main text selection menu as well as the table, math and code block copy menus. `copy.enabled`, `copy.format` and `systemItems` are ignored on macOS.
 
 > **Deprecation:** the previous boolean shape (`copyAsMarkdown: false`) is still accepted at runtime for backward compatibility but logs a one-time warning. It will be removed in 0.8 — migrate to `{ enabled: false }`.
 
@@ -360,9 +477,13 @@ Each item takes an object: `{ enabled }` toggles visibility (the system `copy` i
 
 ```ts
 interface SelectionMenuConfig {
-  /** System "Copy" item — can't be hidden, only relabeled. @default { label: "Copy" } */
-  copy?: { label?: string };
-  /** "Copy as Markdown" action. @default { enabled: true, label: "Copy as Markdown" } */
+  /**
+   * "Copy" item. `format: 'markdown'` copies Markdown as plain text instead of
+   * rich text (text selections) or the raw content (blocks).
+   * @default { enabled: true, label: "Copy", format: "rich" }
+   */
+  copy?: { enabled?: boolean; label?: string; format?: 'rich' | 'markdown' };
+  /** "Copy as Markdown" action, in the text and block menus. @default { enabled: true, label: "Copy as Markdown" } */
   copyAsMarkdown?: { enabled?: boolean; label?: string };
   /** "Copy Image URL" action, shown when the selection contains images. */
   copyImageUrl?: {
@@ -372,6 +493,10 @@ interface SelectionMenuConfig {
     /** Forms for multiple images, chosen with Intl.PluralRules. @default { other: "Copy {count} Image URLs" } */
     pluralLabels?: SelectionMenuPluralLabels;
   };
+  /** `'none'` drops every system item (Select All, Look Up, Share, Translate…). @default 'default' */
+  systemItems?: 'default' | 'none';
+  /** Copy button in the code block header. @default { enabled: true } */
+  codeBlockCopyButton?: { enabled?: boolean };
 }
 
 interface SelectionMenuPluralLabels {
@@ -532,6 +657,18 @@ Auto-capitalization behavior.
 | -------- | -------------- | -------- |
 | `string` | `'sentences'`  | Both     |
 
+### `interceptPaste`
+
+Reports pastes through [`onPaste`](#onpaste) instead of inserting them. Only takes effect when `onPaste` is also set — otherwise native would swallow every paste with nobody left to resolve it, so the library keeps the prop off.
+
+See [Intercepting paste](./INPUT.md#intercepting-paste).
+
+| Type      | Default Value | Platform      |
+| --------- | ------------- | ------------- |
+| `boolean` | `false`       | iOS, Android  |
+
+macOS ignores this prop and always pastes inline.
+
 ### `multiline`
 
 Whether the input supports multiple lines.
@@ -574,6 +711,8 @@ Style configuration for formatted text in the input.
 - `linkVariants` — per-URL-pattern style overrides. Each key is a regex tested against the link URL. See [Mentions — Link Variants](MENTIONS.md#link-variants-mention-styling).
 - `spoiler.color` — text color for spoiler text.
 - `spoiler.backgroundColor` — background color for spoiler text.
+- `h1`–`h6` — per-level heading styling, each accepting `fontSize`, `fontWeight`, and `color`. Defaults match the read-only renderer (sizes `30/24/20/18/16/14`, bold).
+- `list.itemSpacing` — vertical spacing (points) added above each list item (bullet and numbered alike) so items read as separate rows; defaults to `0`. iOS applies it via `paragraphSpacingBefore`; Android via a `LineHeightSpan`.
 
 ### `mentionIndicators`
 
@@ -601,6 +740,15 @@ Fires when the plain text content changes. Returns the text without Markdown syn
 | ------------------------------- | ------------- | -------- |
 | `(text: string) => void`       | -             | Both     |
 
+> [!NOTE]
+> A LaTeX formula appears in this string as a single `U+FFFC` (object replacement
+> character), not as its source. That keeps the string index-compatible with
+> [`onChangeSelection`](#onchangeselection), [`onCaretRectChange`](#oncaretrectchange)
+> and the `insertMath` / `updateMath` / `removeMath` methods, which all address the
+> buffer by offset and count a formula as one character. Use
+> [`onChangeMarkdown`](#onchangemarkdown) when you need the `$...$` source.
+> See [LaTeX math](LATEX_MATH.md).
+
 ### `onChangeMarkdown`
 
 Fires when the Markdown representation changes. Returns the full Markdown string. Only active when the callback is provided — omitting it skips the serialization for better performance.
@@ -619,7 +767,7 @@ Fires when the text selection changes.
 
 ### `onChangeState`
 
-Fires when the active style state changes. The payload provides a nested object for each style with an `isActive` property.
+Fires when the active style state changes. The payload provides a nested object for each style with an `isActive` property; `heading` additionally carries the cursor paragraph's `level` (`0` when it is not a heading) and `unorderedList` / `orderedList` their 0-based nesting `depth`.
 
 | Type                              | Default Value | Platform |
 | --------------------------------- | ------------- | -------- |
@@ -635,9 +783,35 @@ interface StyleState {
   strikethrough: { isActive: boolean };
   spoiler: { isActive: boolean };
   link: { isActive: boolean };
+  // Heading level of the cursor's paragraph: 0 = none, 1-6 = H1-H6.
+  heading: { isActive: boolean; level: number };
+  // `depth` is the 0-based nesting level while `isActive` is true, and is
+  // always `0` when `isActive` is false (i.e. the cursor is not in a list).
+  // This differs from `heading.level`, where `0` is itself a meaningful value
+  // (no heading); read `depth` only when `isActive` is true.
+  unorderedList: { isActive: boolean; depth: number };
+  orderedList: { isActive: boolean; depth: number };
 }
 ```
 
+### `onKeyPress`
+
+Fires on every keystroke, before the change is applied to the input content — mirroring React Native TextInput's `onKeyPress`. `nativeEvent.key` is the pressed character, or a named key: `Backspace`, `Enter`, `Tab` (iOS additionally reports `Escape`). On Android the key reported for soft keyboard input may lag actual typing when autocomplete suggestions are involved. Paste operations do not fire the event.
+
+| Type                                                          | Default Value | Platform |
+| ------------------------------------------------------------- | ------------- | -------- |
+| `(e: NativeSyntheticEvent<{ key: string }>) => void`          | -             | Both     |
+
+**Example:**
+
+```tsx
+<EnrichedMarkdownTextInput
+  onKeyPress={({ nativeEvent: { key } }) => {
+    console.log('Pressed key:', key);
+  }}
+/>
+```
+
 ### `onCaretRectChange`
 
 Fires when the caret's pixel position changes (typing, selection change, content reflow). The rect is relative to the input's top-left corner, in density-independent pixels. The native side diffs the rect before emitting, so redundant events are suppressed.
@@ -686,6 +860,8 @@ Fires when the input loses focus.
 | -------------- | ------------- | -------- |
 | `() => void`   | -             | Both     |
 
+The input participates in React Native's text-input focus tracking (`TextInput.State`), so blur also happens through the platform's standard keyboard-dismiss paths: taps outside the input inside a `ScrollView` (per its `keyboardShouldPersistTaps` setting) and `Keyboard.dismiss()`. See [Keyboard Dismissal](INPUT.md#keyboard-dismissal).
+
 ### `onStartMention`
 
 Fires when a new mention flow starts. See [Mentions](MENTIONS.md#events).
@@ -710,6 +886,18 @@ Fires when the active mention flow ends.
 | ---- | ------------- | -------- |
 | `(event: { indicator: string }) => void` | - | Both |
 
+### `onPaste`
+
+Fires instead of the insert when [`interceptPaste`](#interceptpaste) is on. Native reads the clipboard and leaves the buffer untouched, so the handler owns the paste from that point: it must call [`resolvePaste`](#resolvepastetext-string-markdown-string) exactly once, on every path including failures, or the paste is silently dropped.
+
+| Type | Default Value | Platform |
+| ---- | ------------- | -------- |
+| `(event: { text: string; markdown: string }) => void` | - | iOS, Android |
+
+`markdown` is non-empty only on iOS, when the copy source was an `EnrichedMarkdownTextInput`. Android always reports `''` and `resolvePaste` there inserts `text` verbatim.
+
+See [Intercepting paste](./INPUT.md#intercepting-paste).
+
 ### `writingDirection`
 
 Paragraph writing direction in the input. iOS only — Android's `EditText` already resolves direction per paragraph via `TEXT_DIRECTION_FIRST_STRONG` and is unaffected by this prop.
@@ -924,6 +1112,26 @@ Toggles strikethrough on the current selection or cursor.
 
 Toggles spoiler on the current selection or cursor.
 
+### `toggleHeading(level: number)`
+
+Toggles a heading of the given level (`1`–`6`) on the cursor's paragraph. Calling it with the level already applied turns the paragraph back into regular text. Unlike the inline `toggle*` methods, this operates on the whole paragraph, not a character range.
+
+### `toggleUnorderedList()`
+
+Turns the cursor's paragraph(s) into bullet list items, or back into regular paragraphs if they already are. Operates on the whole paragraph. List items are single-line — each item is exactly one paragraph, and Markdown imported with multi-paragraph (loose) items keeps only each item's first line as a list item.
+
+### `toggleOrderedList()`
+
+Turns the cursor's paragraph(s) into numbered list items, or back into regular paragraphs if they already are. Numbering derives from an item's position among its adjacent same-depth siblings. Toggling one list type on a line carrying the other replaces it, keeping the item's nesting depth.
+
+### `indentList()`
+
+Nests the current list item one level deeper (up to a maximum depth). Called on a non-list paragraph, it starts a bullet list at depth 0. Equivalent to pressing **Tab** with a hardware keyboard.
+
+### `outdentList()`
+
+Lifts the current list item out one nesting level. Outdenting a depth-0 item removes the bullet, turning it back into a regular paragraph. Equivalent to **Shift+Tab**.
+
 ### `setLink(url: string)`
 
 Applies a link URL to the currently selected text.
@@ -936,12 +1144,26 @@ Inserts a link with the given text and URL at the current cursor position. Usefu
 
 Removes the link from the current selection.
 
+### `insertText(text: string)`
+
+Parses the given string as Markdown and inserts it literally at the current cursor position, replacing the selection if there is one. Leading and trailing newlines are preserved, so wrap block content (lists, headings) in newlines to keep it on its own lines when inserting mid-paragraph — `insertText('\n- item\n')` in the middle of `test` yields `te`, a `- item` bullet, and `st` on separate lines. Calling it with an empty string is a no-op.
+
 ### `copyToClipboard()`
 
 Copies the input's full content to the system clipboard, matching the result of selecting all text and pressing the context menu's copy action. The selection is left unchanged, and calling it on an empty input is a no-op.
 
 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.
 
+### `resolvePaste(text: string, markdown?: string)`
+
+Completes a paste reported through [`onPaste`](#onpaste). Call it exactly once per event:
+
+- `resolvePaste(text, markdown)` — inserts, restoring the copied formatting when `markdown` is non-empty.
+- `resolvePaste(text)` — inserts `text` verbatim.
+- `resolvePaste('', '')` — drops the clipboard content, replacing the current selection. With an empty selection this is a no-op that still emits `onChangeText` with unchanged content.
+
+Anything that replaces a selection replaces it here too, so a paste over selected text behaves the same on every branch.
+
 ### `startMention(indicator: string)`
 
 Programmatically triggers a mention flow by inserting the indicator character at the current cursor position. The indicator must be listed in the `mentionIndicators` prop. Useful for toolbar buttons.

package/docs/BREAKING_CHANGES.md

@@ -0,0 +1,129 @@
+# Breaking changes
+
+This file tracks breaking changes and how to migrate for each. Entries are newest first. Deprecations
+(things that still work but are slated for removal) are noted alongside the change that introduces them.
+
+## Unreleased
+
+### `EnrichedMarkdownTextInput` math style keys renamed to match the renderer
+
+The editor's `markdownStyle` used `math` for the **inline** chip and `mathBlock` for the **block**
+chip — the exact opposite of `EnrichedMarkdownText`, where `math` is the block style and `inlineMath`
+the inline one. The same key name meant two different things depending on which component you were
+styling. The editor now follows the renderer.
+
+**Migrate:**
+
+| Before (input) | After (input) | Renderer equivalent |
+|---|---|---|
+| `markdownStyle.math` | `markdownStyle.inlineMath` | `markdownStyle.inlineMath` |
+| `markdownStyle.mathBlock` | `markdownStyle.math` | `markdownStyle.math` |
+| `markdownStyle.mathBlock.alignment` | `markdownStyle.math.textAlign` | `markdownStyle.math.textAlign` |
+
+```diff
+ <EnrichedMarkdownTextInput
+   markdownStyle={{
+-    math: { color: '#0F172A', backgroundColor: '#EEF2FF' },
+-    mathBlock: { fontSize: 22, alignment: 'center' },
++    inlineMath: { color: '#0F172A', backgroundColor: '#EEF2FF' },
++    math: { fontSize: 22, textAlign: 'center' },
+   }}
+ />
+```
+
+`markdownStyle.math` additionally accepts `padding` as a shorthand for both axes, matching the
+renderer's `math.padding`; `paddingHorizontal` / `paddingVertical` still override it per axis.
+
+The accompanying types are exported for the first time under names that say which surface they belong
+to: `InputInlineMathStyle` and `InputMathStyle` (the renderer's own math style types stay internal to
+`MarkdownStyle`).
+
+
+## v1.0.2
+
+### The Expo config plugin was removed
+
+The built-in Expo config plugin (`app.plugin.js` and the `plugin/` folder) has been removed. Feature
+configuration now lives entirely in your app's `package.json`, read directly by the native build and by
+`postinstall` — the same approach `react-native-worklets` uses for its static feature flags.
+
+Why: the plugin only wrote the (now deprecated) Podfile `ENV` / `gradle.properties` channels, it could
+never influence the install-time asset download (it runs during `expo prebuild`, _after_ `npm install`),
+and its option shape diverged from the `package.json` block. The `package.json` block supersedes it for
+both the download and the build, and it survives `expo prebuild`.
+
+**Migrate:** remove the plugin entry from `app.json` / `app.config.js` and move the options into the
+`enriched-markdown` block of your `package.json`.
+
+Before (`app.json`):
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "react-native-enriched-markdown-scaffold",
+        {
+          "enableMath": false,
+          "codeHighlight": {
+            "enabled": true,
+            "languages": ["javascript", "tsx"]
+          }
+        }
+      ]
+    ]
+  }
+}
+```
+
+After (`package.json`):
+
+```json
+{
+  "enriched-markdown": {
+    "enableMath": false,
+    "enableCodeHighlight": true,
+    "codeHighlightLanguages": ["javascript", "tsx"]
+  }
+}
+```
+
+Note the key renames: the plugin's `codeHighlight.enabled` / `codeHighlight.languages` become
+`enableCodeHighlight` / `codeHighlightLanguages`. Then run `pod install` (iOS) or rebuild (Android).
+These are compile/link-time settings, so they apply only in builds you compile yourself (a custom dev
+client or `expo prebuild`) — they cannot be changed in Expo Go, which ships a fixed prebuilt binary.
+
+The `@expo/config-plugins` peer dependency was dropped as part of this removal.
+
+### Feature config moved to `package.json`; ENV vars and gradle properties are deprecated
+
+The `enriched-markdown` block in your app's `package.json` is now the single source of truth for
+`enableMath`, `enableCodeHighlight`, and `codeHighlightLanguages` on both platforms — the native build
+reads it directly at `pod install` / Gradle configuration time. The previous build flags still work as a
+fallback but are deprecated, print a warning, and are ignored when the matching `package.json` key is set:
+
+| Deprecated flag                                                                                                | Replaced by (`package.json` `enriched-markdown`) |
+| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| Podfile `ENV['ENRICHED_MARKDOWN_ENABLE_MATH']` / gradle `enrichedMarkdown.enableMath`                          | `enableMath`                                     |
+| Podfile `ENV['ENRICHED_MARKDOWN_ENABLE_CODE_HIGHLIGHT']` / gradle `enrichedMarkdown.enableCodeHighlight`       | `enableCodeHighlight`                            |
+| Podfile `ENV['ENRICHED_MARKDOWN_CODE_HIGHLIGHT_LANGUAGES']` / gradle `enrichedMarkdown.codeHighlightLanguages` | `codeHighlightLanguages`                         |
+
+In a monorepo the _build_ flag is read from the app's `package.json` (the one beside `ios/`/`android/`),
+so each app configures independently. The _download_ opt-out is read where the install runs — usually the
+workspace root — so put it in the root `package.json` to skip a download for the whole repo. See
+[Native assets](./NATIVE_ASSETS.md).
+
+### Explicitly enabling a feature whose assets are missing now fails the build
+
+Previously, a missing native asset (the RaTeX XCFramework, or the tree-sitter grammars) always silently
+disabled the feature. Now, if you **explicitly** set `enableMath: true` or `enableCodeHighlight: true` but
+the asset was not downloaded (for example an install with `--ignore-scripts`, or a monorepo root opt-out
+that an app overrides), the build fails with an actionable error instead of degrading. Features left on by
+default still degrade to a clean build. To fix, restore the assets:
+
+```sh
+node node_modules/react-native-enriched-markdown-scaffold/postinstall.mjs
+# or: npm rebuild react-native-enriched-markdown-scaffold
+```
+
+then re-run `pod install` (iOS) / rebuild (Android).

package/docs/CODE_HIGHLIGHT.md

@@ -0,0 +1,133 @@
+# Code-block syntax highlighting
+
+Fenced code blocks are syntax-highlighted natively via [tree-sitter](https://tree-sitter.github.io/).
+Highlighting is **foreground-only** (it recolors tokens and never changes text metrics), so a code
+block's measured height always matches its drawn height. It is enabled by default on iOS and Android
+with a curated set of languages, and can be trimmed or disabled to reduce binary size.
+
+## Usage
+
+Highlighting activates automatically for a fenced block whose info string names a supported language:
+
+````tsx
+<EnrichedMarkdownText
+  flavor="github"
+  markdown={String.raw`
+\`\`\`python
+def greet(name: str) -> str:
+    return f"Hello, {name}!"  # a comment
+\`\`\`
+`}
+  markdownStyle={{
+    codeBlock: {
+      syntaxColors: {
+        keyword: '#C678DD',
+        string: '#98C379',
+        number: '#D19A66',
+        comment: '#7F848E',
+        function: '#61AFEF',
+        type: '#E5C07B',
+        // ...any of the 14 token types
+      },
+    },
+  }}
+/>
+````
+
+Token colors are set through `codeBlock.syntaxColors`. The 14 token types are: `keyword`,
+`operator`, `punctuation`, `string`, `number`, `constant`, `comment`, `function`, `type`,
+`variable`, `property`, `tag`, `attribute`, `embedded`. Any type left unset is drawn in the normal
+code color.
+
+## Copy button
+
+With `flavor="github"`, each code block's header shows a copy button (and a long-press context
+menu with **Copy** / **Copy as Markdown**). The CommonMark flavor renders code blocks inline with
+no header, so it has no copy button. To observe when a user copies code, pass
+[`onCopyPress`](./API_REFERENCE.md#oncopypress) — it fires with the copied `code` and its
+`language` for the header button, the context-menu **Copy** action, and the VoiceOver copy action.
+The copy label shown to assistive technologies is configurable via
+[`selectionMenuConfig`](./COPY_OPTIONS.md).
+
+## Supported languages
+
+Fence info strings map to a grammar (for example `js` and `jsx` both select JavaScript). The **curated default
+set** is compiled in unless you override it. It is defined by `default:true` in
+`vendor/grammar-versions.json` (the single source of truth the iOS podspec and Android build both
+derive from), so the table below tracks that manifest:
+
+| Default (on) | Opt-in (heavier) |
+|---|---|
+| json, html, css, markdown, yaml, go, java, javascript, python, c, rust, bash, typescript, tsx | cpp, swift, php, ruby, c-sharp |
+
+The default set is the smaller-footprint tier (~32 MB of grammar C source across the whole set).
+The opt-in grammars are larger (17-29 MB each) and are only compiled when you list them explicitly.
+A block whose language is not compiled in simply renders as plain (uncolored) code.
+
+## Choosing languages / reducing binary size
+
+Only the grammars you compile end up in your binary, so trimming the list is the main size lever.
+The seam degrades to plain code whenever a grammar is absent, so nothing breaks when you remove one.
+
+Configure everything through the `enriched-markdown` block of your app's `package.json` — it is the
+single source of truth for both platforms and both the install-time download and the build:
+
+```json
+{
+  "enriched-markdown": {
+    "enableCodeHighlight": true,
+    "codeHighlightLanguages": ["javascript", "tsx", "json", "bash"]
+  }
+}
+```
+
+How the two keys interact:
+
+- **`enableCodeHighlight`** (default `true`) is the master switch. When `false`, the grammar download is
+  skipped **and** the tree-sitter runtime is excluded from the native build. In that state
+  **`codeHighlightLanguages` is ignored — it is a no-op**, because there is no highlighter compiled in for
+  languages to feed.
+- **`codeHighlightLanguages`** selects which grammars to compile *when highlighting is enabled*. Omit it
+  for the curated default set, or pass a subset to shrink the binary. An empty array (`[]`) compiles no
+  grammars, which disables highlighting entirely — equivalent to `enableCodeHighlight: false`.
+
+Re-run `pod install` (iOS) / rebuild (Android) after changing these. The same block works with Expo —
+`node_modules` survives `npx expo prebuild`, so no config plugin is needed (highlighting is compiled in,
+so it can't be changed in **Expo Go**; use a dev client or `expo prebuild`). See
+[Skipping the download](./NATIVE_ASSETS.md#skipping-the-download-opt-out).
+
+> [!NOTE]
+> **Deprecated:** the `ENV['ENRICHED_MARKDOWN_*']` Podfile variables and the `enrichedMarkdown.*` gradle
+> properties still work as a fallback but are deprecated and print a warning; they are ignored when the
+> corresponding `package.json` key is set. The Expo config plugin was removed — see
+> [Breaking changes](./BREAKING_CHANGES.md). Prefer the `package.json` block above.
+
+## How it works
+
+Grammars are **vendored** into `packages/core/cpp/highlight/vendor/` (only each grammar's
+`parser.c`/`scanner.c` + `highlights.scm`, never whole npm packages), so the native build itself is
+fully offline and deterministic. The stable tree-sitter runtime is vendored the same way and compiled
+with WebAssembly support left out. A build-time codegen emits a registry for exactly the selected
+languages, so the binary and link step only ever reference compiled grammars.
+
+The entire `vendor/` tree is **gitignored** to keep the repo and PRs small — nothing generated lives
+in git. `vendor/vendor-grammars.mjs` restores all of it from the pins in `vendor/grammar-versions.json`:
+the tree-sitter runtime (`vendor/tree-sitter/`) is fetched and sha256-verified from the pinned GitHub
+release tarball, the ~178 MB of grammar `parser.c` tables (`vendor/grammars/`) are copied from the
+pinned grammar devDependencies, and the default registry (`vendor/generated/`) is codegen'd from them.
+It is wired into the package `prepare` script (so a plain `yarn install` restores everything, with
+`.stamp` guards making repeats a no-op).
+
+The published npm tarball ships only the small default registry, **not** the heavy grammar/runtime
+source — that would bloat every install to ~230 MB. Instead a `postinstall` script downloads the
+grammar sources (from the npm registry) and the tree-sitter runtime (from the pinned GitHub release)
+into the installed package, sha256-verified and idempotent. See [Native assets](./NATIVE_ASSETS.md)
+for the install-time behavior, network requirements, and how to recover an offline/pnpm install.
+
+Highlighting runs synchronously when a code block is applied and is cached per block, with a size cap
+(~50 KB / ~2000 lines) that falls back to plain rendering for pathological inputs. Maintainers re-pin
+by editing `vendor/grammar-versions.json` (for a runtime bump, also update `runtime.sha256` — a full
+`node vendor/vendor-grammars.mjs --force` run prints the correct digest on mismatch) and re-running
+the script; there is nothing generated to commit. To vendor the runtime from a local tree-sitter
+checkout instead of the network, pass `--runtime-src <path to tree-sitter/lib>` (or set
+`TREE_SITTER_SRC`).