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

package/docs/API_REFERENCE.md

@@ -69,6 +69,59 @@ Callback when a link is long pressed. Access URL via `event.url`. On iOS, automa
 />
 ```
 
+### `renderLinkDecoration`
+
+Renders a React Native view on top of each link — for example a badge or sparkle on a [link chip](STYLES.md#link-chips). Return `null` to leave a link undecorated.
+
+| Type                                                   | Default Value | Platform |
+| ------------------------------------------------------ | ------------- | -------- |
+| `(info: LinkDecorationInfo) => ReactNode \| null`       | -             | Both     |
+
+`LinkDecorationInfo`:
+
+| Field   | Type         | Description |
+| ------- | ------------ | ----------- |
+| `index` | `number`     | Position of the link in the document (0-based). Stable key for the link |
+| `url`   | `string`     | Link URL |
+| `text`  | `string`     | Visible link text |
+| `rect`  | `LinkRect`   | Anchor rect: the drawn chip (glyphs + horizontal/vertical padding) of the link's **last** line fragment |
+| `rects` | `LinkRect[]` | Every line fragment, in order (several when the link wraps) |
+
+`LinkRect` is `{ x, y, width, height }` in dp, relative to the component's content box (inside `containerStyle` padding).
+
+The returned node is placed inside an absolutely positioned box matching `rect`, with `pointerEvents="box-none"`, so position it relative to that box. Negative offsets let it overflow the chip:
+
+```tsx
+<EnrichedMarkdownText
+  markdown="Read the [guide](https://example.com/guide) first."
+  markdownStyle={{
+    link: {
+      backgroundColor: '#DCE2FF',
+      borderRadius: 5,
+      paddingHorizontal: 7,
+      underline: false,
+    },
+  }}
+  renderLinkDecoration={({ url }) =>
+    url.startsWith('https://') ? (
+      <View style={{ position: 'absolute', top: -8, right: -8 }}>
+        <SparkleIcon />
+      </View>
+    ) : null
+  }
+/>
+```
+
+Notes and limitations:
+
+- When this prop is not set the component renders exactly as before: no wrapper view and no layout events.
+- Setting it wraps the native view in a `View` (which takes `containerStyle`). Switching between set and unset remounts the native view.
+- Rects are measured natively after layout and sent to JS, so decorations appear one frame after the text. Updates are deduplicated — streaming does not re-render decorations unless a link actually moves.
+- Links inside tables (`flavor="github"`) are not reported.
+- On Android, parts of a decoration that overflow the component's bounds do not receive touches.
+- Web: `rect` is the link's whole inline box and `rects` is `[rect]`; for a wrapping link the decoration anchors to that box rather than the last line.
+- Not supported by `EnrichedMarkdownTextInput`.
+
 ### `onTaskListItemPress`
 
 Callback when a task list checkbox is tapped. Receives `index` (0-based), `checked` (new state after toggling), and `text` (item text).
@@ -77,6 +130,157 @@ 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);
+  }}
+/>
+```
+
+### `onCopy`
+
+Takes over the **Copy** item of the text selection menu and of the table, math and code block menus. When set, native does **not** write the clipboard: it calls `onCopy` with the copied content and your handler writes whatever it wants — for example with [`expo-clipboard`](https://docs.expo.dev/versions/latest/sdk/clipboard/). Use it to post-process what users copy (strip formatting, drop link targets…) without a native change.
+
+| Type                          | Default Value | Platform |
+| ----------------------------- | ------------- | -------- |
+| `(event: CopyEvent) => void`  | -             | Both     |
+
+```ts
+interface CopyEvent {
+  /** Which menu the Copy item belongs to. */
+  source: 'selection' | 'math' | 'table' | 'code';
+  /** What `copy.format: 'markdown'` would write. */
+  markdown: string;
+  /** Rendered text of the selection, or the block's raw content. */
+  text: string;
+  /** The selection spans the whole component (`markdown` is the source). Always true for blocks. */
+  whole: boolean;
+}
+```
+
+| `source`    | `markdown`                                                                 | `text`                        |
+| ----------- | -------------------------------------------------------------------------- | ----------------------------- |
+| `selection` | Original source when `whole`, otherwise rebuilt from the rendered styles   | Selected text as rendered     |
+| `math`      | `$$…$$`                                                                     | LaTeX                         |
+| `table`     | The table as Markdown                                                      | Tab-separated cells           |
+| `code`      | Fenced code block                                                          | Raw code                      |
+
+- `onCopy` overrides `selectionMenuConfig.copy.format`; `copy.enabled: false` still hides the item, so no event fires.
+- **Copy as Markdown**, the code block header copy button and the VoiceOver copy action are unaffected. `onCopyPress` does not fire for an intercepted Copy.
+- With `flavor="github"` the text is split into segments around blocks, so a selection is `whole` only when the markdown renders as a single text segment.
+- A rebuilt `markdown` wraps each styled run separately (`**a *****b***** c**`) and does not escape literal `*` / `_`.
+- Copying with a hardware keyboard (Cmd+C / Ctrl+C) does not go through the menu and is not intercepted.
+- Ignored on macOS. On web the prop is not this API: it reaches the container `div` as the DOM `onCopy` clipboard event.
+
+**Example:**
+
+```tsx
+import * as Clipboard from 'expo-clipboard';
+
+<EnrichedMarkdownText
+  markdown={content}
+  onCopy={({ source, markdown }) => {
+    Clipboard.setStringAsync(source === 'selection' ? stripFormatting(markdown) : markdown);
+  }}
+/>
+```
+
+### `onSelectionChange`
+
+Reports the text selection so the app can draw its own selection menu. Pair it with [`contextMenuHidden`](#contextmenuhidden) to replace the native menu entirely.
+
+| Type                                     | Default Value | Platform |
+| ---------------------------------------- | ------------- | -------- |
+| `(event: SelectionChangeEvent) => void`  | -             | Both     |
+
+```ts
+interface SelectionRect { x: number; y: number; width: number; height: number }
+
+interface SelectionChangeEvent {
+  /** `false` once the selection is gone; every other field is then empty / zero. */
+  active: boolean;
+  /** `'selection'` for text, or the kind of a long-pressed block. */
+  source: 'selection' | 'math' | 'table' | 'code';
+  /** Same as `CopyEvent.text` / `CopyEvent.markdown` / `CopyEvent.whole`. */
+  text: string;
+  markdown: string;
+  whole: boolean;
+  /** Bounding box (full content width when it spans several lines). */
+  rect: SelectionRect;
+  /** Selected part of the first / last line — anchor a menu above the start or below the end. */
+  startRect: SelectionRect;
+  endRect: SelectionRect;
+  /** `true` while a selection handle is dragged (iOS; always `false` on Android). */
+  adjusting: boolean;
+}
+```
+
+- Fires at most once per frame while the selection changes (payloads are deduplicated), and with `active: false` right away once it is gone — including when new `markdown` replaces the text.
+- Rects are in dp, relative to the component's native view: add the origin from `ref.current.measureInWindow` to get window coordinates. Re-measure after scrolling instead of waiting for a new event.
+- With `contextMenuHidden`, a long press on a table, math or code block (`flavor="github"`) fires the event with `source` set to the block kind, `whole: true` and every rect set to the block's frame. These blocks have no text selection, so without this they would offer no way to copy. Without `contextMenuHidden` the block menu shows as usual and no event fires.
+- On iOS the selection isn't reported while a handle is dragged: the event fires with `adjusting: true` (and the selection as it was) when the drag begins, and with `adjusting: false` and the new selection when the finger lifts. Hide your menu while `adjusting` is `true`. Android has no such flag (`adjusting` is always `false`) but reports every step of the drag, so debounce before showing the menu there too.
+- Within one component only one part holds a selection at a time: selecting in another text segment clears the previous one. To keep a single selection across several components, call `clearSelection()` on the previous one.
+- Ignored on macOS and web.
+
+**Imperative handle.** `ref` exposes `clearSelection()`, which clears the selection (and any long-pressed block) and fires `active: false`. It also forwards `measure`, `measureInWindow` and `measureLayout`.
+
+```tsx
+const ref = useRef<EnrichedMarkdownTextInstance>(null);
+
+<EnrichedMarkdownText
+  ref={ref}
+  markdown={content}
+  contextMenuHidden
+  onSelectionChange={(e) => {
+    if (!e.active || e.adjusting) return hideMenu();
+    ref.current?.measureInWindow((x, y) =>
+      showMenuDebounced({ x: x + e.startRect.x, y: y + e.startRect.y }, e.markdown)
+    );
+  }}
+/>;
+
+// After the menu action:
+ref.current?.clearSelection();
+```
+
 ### `enableLinkPreview`
 
 Controls the native link preview on long press (iOS only). Automatically set to `false` when `onLinkLongPress` is provided.
@@ -97,6 +301,16 @@ You can also control this behavior explicitly without providing a handler:
 />
 ```
 
+### `linkLongPressSelects`
+
+Long-pressing a link selects its label and shows the selection edit menu (the same one a manual selection gets), instead of the system link preview (iOS only). Takes precedence over `enableLinkPreview` and `onLinkLongPress`.
+
+| Type      | Default Value | Platform |
+| --------- | ------------- | -------- |
+| `boolean` | `false`       | iOS      |
+
+Only the link label is selected, not the chip padding; the selection handles can be dragged to extend it. Long-pressing inline math always behaves this way, without the prop.
+
 ### `selectable`
 
 Whether text can be selected.
@@ -105,6 +319,39 @@ 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`.
+- To show your own menu instead, use [`onSelectionChange`](#onselectionchange);
+  with this prop on, block long-presses are reported through it as well.
+
 ### `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 +374,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 +383,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 +398,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 +487,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 +495,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 +509,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 +531,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 +553,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 +640,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 +648,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 +664,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 +828,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 +882,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 +911,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 +938,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 +954,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 +1031,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 +1057,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 +1283,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 +1315,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.