docs: miscellaneous section

docs/docs/misc/comparison-with-other-libraries.md

@@ -4,4 +4,62 @@ sidebar_position: 2
 
 # Comparison with other libraries
 
-<!-- TODO: write content for this page -->
+React Native doesn't ship a built-in rich text component, so a number of
+community libraries exist. They fall into two broad categories: **native
+implementations** that render directly through the platform's text system, and
+**WebView wrappers** that embed a browser-based editor. This page compares
+React Native Enriched HTML with the most popular alternatives in each
+category.
+
+## Native solutions
+
+### React Native Aztec
+
+[React Native Aztec](https://github.com/wordpress-mobile/react-native-aztec)
+was WordPress's native rich text component for Gutenberg Mobile. The repository
+was **archived in March 2025** and the code folded into the
+[Gutenberg monorepo](https://github.com/WordPress/gutenberg), where activity
+is focused on the WordPress editor itself rather than the standalone React
+Native wrapper. Aztec **does not support the New Architecture (Fabric)** and is
+dual-licensed under **GPL-2.0 / MPL-2.0** - both are copyleft licenses that
+may require you to distribute your own source code under the same terms,
+which can be a deal-breaker for proprietary apps.
+
+### React Native Enriched Markdown
+
+[React Native Enriched Markdown](https://github.com/software-mansion/react-native-enriched-markdown)
+is another fully native library from [Software Mansion](https://swmansion.com) (MIT-licensed, New
+Architecture required). It focuses on **Markdown** rather than HTML:
+
+- **Text component** - renders a wide range of Markdown features natively,
+  including GFM tables, task lists, LaTeX math and spoiler text.
+- **Text input** - provides a rich editing experience with Markdown output.
+
+The key difference is the **content format**. Enriched Markdown targets apps
+that work with Markdown end-to-end, while Enriched HTML is built for apps that
+need an **HTML-based editor with advanced, customisable formatting
+capabilities** and a matching display component. The two libraries can coexist in one app if you need both formats.
+
+## WebView-based solutions
+
+### 10tap Editor
+
+[10tap Editor](https://github.com/10play/10tap-editor) wraps
+[TipTap](https://tiptap.dev) (ProseMirror) inside a React Native WebView.
+
+### React Native Pell Rich Editor
+
+[React Native Pell Rich Editor](https://github.com/wxik/react-native-rich-editor)
+is a lightweight WebView-based editor.
+
+### Why native matters
+
+All WebView-based editors share a set of inherent trade-offs compared to a
+fully native approach:
+
+|                          | Native (Enriched HTML)                                                                                                                                  | WebView editors                                                                                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Input latency**        | Text goes through the platform's native text system - every keystroke, selection change and style toggle is processed without leaving the native layer. | Every interaction crosses the React Native ↔ WebView bridge, adding measurable latency, especially on lower-end devices.                                        |
+| **Platform integration** | Full access to native APIs: system context menus, autocorrect / predictive text, VoiceOver / TalkBack, hardware keyboards.                              | Limited by what the WebView exposes; features like custom context-menu items or native accessibility trees require extra workarounds or are simply unavailable. |
+| **Memory & startup**     | No WebView process to spin up - the component is just another native view in the hierarchy.                                                             | Each editor instance spawns a WebView, increasing memory use and adding a visible loading delay on first render.                                                |
+| **Debugging**            | Standard React Native / native debugging tools.                                                                                                         | Requires separate WebView / browser dev-tools; bridge-related bugs can be hard to trace.                                                                        |

docs/docs/misc/compatibility.mdx

@@ -0,0 +1,88 @@
+---
+sidebar_position: 1
+---
+
+# Compatibility
+
+This page is the single source of truth for the React Native versions the
+library supports and for the small set of behaviours that differ between
+platforms.
+
+:::info
+
+React Native Enriched HTML works **only** with the
+[React Native New Architecture (Fabric)](https://reactnative.dev/architecture/landing-page).
+The New Architecture is enabled by default in recent React Native versions. If
+your app still uses the old architecture, you'll need to migrate to the New
+Architecture before installing the library.
+
+:::
+
+## Supported React Native versions
+
+The table assumes you're using the latest patch of each library minor version.
+
+<EnrichedCompatibility />
+
+## Platform differences
+
+Android, iOS and Web are built on different text systems, so a few APIs
+behave differently depending on the platform. These are platform
+characteristics, not library bugs, and they're collected here. For limitations that affect
+every platform, see [Known limitations](/misc/known-limitations) instead.
+
+### Justified text alignment (Android)
+
+On Android, `'justify'` is accepted in the type signature but has no justified
+layout effect - the paragraph is shown with its natural alignment, the same as
+`'auto'`. This applies both to `setTextAlignment('justify')` and to the `justify` value reported by
+`onChangeState`.
+
+### `ellipsizeMode` with multiple lines (Android)
+
+On Android, when `numberOfLines` is set to a value higher than `1`, only the
+`'tail'` value of `ellipsizeMode` works correctly. This matches React Native's
+built-in [`Text`](https://reactnative.dev/docs/text#ellipsizemode) component - it
+is an Android platform limitation, not something specific to this library.
+
+### Custom context menu (iOS 16+, ordering)
+
+Custom context-menu items (`contextMenuItems`) require **iOS 16 or newer** on
+iOS. On iOS, items appear in array order, before the system items
+(Copy/Paste/Cut). On Android there is no guaranteed order, and custom items may
+be shown in a submenu depending on the device manufacturer. On the Web the
+native editing menu isn't available at all, so the prop is ignored - build your
+own UI instead.
+
+### Return key behaviour
+
+These props follow the same platform rules as React Native's
+[`TextInput`](https://reactnative.dev/docs/textinput):
+
+- **`returnKeyType`** - behaves like on [`TextInput`](https://reactnative.dev/docs/textinput#returnkeytype)
+  on iOS. On Android it is accepted but has no effect, because the input is always
+  multiline and Android does not apply `returnKeyType` to multiline inputs - the
+  same long-standing behaviour as [`TextInput`](https://reactnative.dev/docs/textinput)
+  with `multiline={true}`. On the Web it maps to the browser's
+  [`enterkeyhint`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint).
+- **`returnKeyLabel`** - Android only, matching
+  [`returnKeyLabel`](https://reactnative.dev/docs/textinput#returnkeylabel-android)
+  on `TextInput`, where React Native recommends using it instead of
+  `returnKeyType`. Not available on iOS, and can't be set inside a browser, so
+  it is ignored on the Web.
+
+### Cursor / selection color
+
+The `cursorColor` prop is applied on Android and Web. On iOS the caret and
+selection color both follow the `selectionColor` prop.
+
+### HTML is not sanitized (Mobile)
+
+On iOS and Android, the library does not sanitize HTML. It makes no guarantees that the markup it accepts or produces is safe. You are fully responsible for sanitizing any HTML you persist, render elsewhere, or accept from untrusted sources.
+
+Sanitization **is** enforced on the web, as injecting unsafe HTML directly into the DOM poses severe security risks (like XSS).
+
+### React Native layout ref methods
+
+On Web those methods are no-ops. These include: `measure`,
+`measureInWindow`, `measureLayout` and `setNativeProps`.