@eclosion-tech/react-native-yjs-text 0.1.0

package/SPEC.md

@@ -0,0 +1,346 @@
+# react-native-yjs-text
+
+**Status:** Draft spec, pre-implementation
+
+## Overview
+
+`react-native-yjs-text` is a React Native rich-text editor that uses `Y.Text` as its document model and renders natively on iOS and Android — no WebView, no `contenteditable` shim, no DOM.
+
+The library exists because there is currently no production-grade way to do rich text editing in React Native without paying the WebView tax (worse performance, broken keyboard behavior, gesture/scroll conflicts, accessibility regressions, platform-specific bugs that don't reproduce in browsers). Every existing option — `react-native-pell-rich-editor`, `@10play/tentap-editor`, `react-native-cn-quill` — is a WebView wrapper around a browser-based editor.
+
+The architectural bet: **Y.Text is already a platform-independent rich-text primitive.** It is a sequence of characters with arbitrary formatting attributes, which maps cleanly onto both `contenteditable` (via `y-prosemirror` on the web) and `NSAttributedString` / `Spannable` on native mobile. The model side is solved by upstream Yjs. The missing piece is the native bindings — the platform-specific adapters that translate user input into Y.Text operations and Y.Text state into rendered attributed text. That is what this library provides.
+
+## Non-goals
+
+Explicit, to keep scope honest:
+
+- **Not a multi-block document editor.** A `YTextInput` edits one `Y.Text` — one inline rich-text region, the equivalent of one paragraph or heading. Multi-block editing in a single view (Notion-style infinite-scroll-of-paragraphs in one editor) is *intentionally* out of scope. See "Document shape" below for why.
+- **Not a toolbar / formatting UI.** The library exposes the editor API; the consumer builds whatever toolbar, slash menu, or floating selection UI it wants.
+- **Not a Yjs port.** Yjs itself runs in JS via the existing `yjs` package. This library is the native-view side of the binding. (A native-side Yjs port is a possible future optimization but is explicitly v2+ territory.)
+- **Not a sync / persistence layer.** The library is agnostic to where the `Y.Doc` containing the `Y.Text` lives — it works equally well with `y-websocket`, `y-indexeddb`, a custom provider talking to a backend, or a Yjs doc embedded in another database's row. Wiring that up is the consumer's responsibility.
+- **Not a cross-platform abstraction layer for *all* text editing.** Plain text inputs are already cross-platform (React Native's `TextInput`). This library is for the specific case where you need formatting attributes and Yjs-backed collaborative semantics.
+- **Not a complete WYSIWYG suite.** No tables, no embedded media as block-level structure, no nested complex layouts. Those belong in the consuming application's block model.
+
+## Document shape: `Y.Text` per editor
+
+A library that binds Yjs to a native rich-text editor has two viable shapes for "what is a single editor instance editing":
+
+| | `Y.Text` per editor | `Y.XmlFragment` per editor |
+|---|---|---|
+| What you edit | One inline rich-text region (one paragraph-equivalent) | A multi-block document (paragraphs + headings + lists + ...) |
+| Block model lives where | The consuming application | Inside the editor |
+| Multi-paragraph editing in one view | No — one editor per block | Yes |
+| Editor surface area | Small (inline marks, selection within one run of text) | Large (block split/merge, multi-block selection, slash menus, cross-block keyboard nav) |
+| Native event model fit | Excellent — one contiguous text region maps directly to `UITextView` / `EditText` | Awkward — multi-block selection and split/merge across multiple native text views is full of edge cases |
+| Web equivalent | A `Y.Text` binding (custom) or TipTap with a one-block schema | Standard TipTap / `y-prosemirror` over `Y.XmlFragment` |
+
+**`react-native-yjs-text` commits to the `Y.Text`-per-editor shape.** Each editor instance edits one `Y.Text`. Block-level structure (paragraph vs. heading vs. list, the distinction between "this is a quote block" and "this is a code block") is the consuming application's responsibility — typically each block is its own `Y.Text` in a tree the consumer maintains.
+
+This is a deliberate scope decision, not a v0.1 limitation that we plan to grow out of. Reasons:
+
+1. **It's where modern block editors are converging.** Notion, Linear, ClickUp, Coda all use per-block rendering — independent permissions per block, independent collaboration cursors per block, independent AI mutations per block, simpler accessibility tree, native scroll behavior. The advantages outweigh the cost of managing block structure outside the editor. The `Y.XmlFragment`-in-one-editor pattern is the older paradigm; the industry is moving away from it.
+2. **It's the right fit for native mobile UX.** Single contiguous editable text regions map cleanly onto `UITextView` / `EditText`. Multi-block selection and split/merge across multiple native text views is a swamp of edge cases, especially on iOS.
+3. **It keeps the library small enough to actually ship.** The `Y.XmlFragment` shape adds a large surface area (block-level operations, slash menus, cross-block selection, split/merge keyboard handling) — features that double or triple the implementation cost.
+4. **It composes cleanly with any consumer block model.** A `ComponentNode` tree (Pear's case), a Slate-like document, a custom React Native list of blocks — all work the same way: each `Y.Text` is a leaf the consumer addresses, and the consumer handles tree-level operations on top.
+
+A consumer that genuinely wants multi-block editing in one view should reach for a different library, or build one. If demand for a `Y.XmlFragment`-shaped library ever materializes, it should ship as a separate package (something like `react-native-yjs-prose`) that depends on `react-native-yjs-text` for the inline-rich-text leaves. That's a clean architectural split rather than feature creep on this library.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│ Consumer application (e.g. Pear mobile) │
+│   - manages the Y.Doc / Y.Text          │
+│   - builds toolbar / slash menu UI      │
+│   - composes multiple YTextInputs into  │
+│     its own block model                 │
+└──────────────┬──────────────────────────┘
+               │ <YTextInput yText={...} schema={...} />
+               │
+┌──────────────▼──────────────────────────┐
+│ react-native-yjs-text (TS layer)        │
+│   - YTextInput component                 │
+│   - editor command API (commands.ts)     │
+│   - schema definitions / mark conventions│
+│   - Y.Text ↔ native view event bridge    │
+└──────────────┬──────────────────────────┘
+               │ React Native bridge / JSI
+               │
+┌──────────────▼──────────┬───────────────┐
+│ iOS native              │ Android native│
+│ - YTextInputView        │ - YTextInputView
+│   (subclass UITextView) │  (subclass AppCompatEditText)
+│ - NSAttributedString    │ - SpannableStringBuilder
+│ - UITextViewDelegate    │ - TextWatcher / InputConnection
+└─────────────────────────┴───────────────┘
+```
+
+The library *does not* own the `Y.Doc` or `Y.Text`. The consumer creates and owns them. The component subscribes to a passed-in `Y.Text` and renders/edits it.
+
+### Yjs object layering
+
+A note on terminology, since the question comes up:
+
+- **`Y.Doc`** is the *container* — the unit of synchronization and persistence. A consumer creates one `Y.Doc` per logical document (per page, per row, per editable cell — whatever granularity it wants) and arranges to sync it via whatever provider it prefers (`y-websocket`, `y-indexeddb`, a custom provider talking to a relational backend, etc.).
+- **Shared types** (`Y.Text`, `Y.Map`, `Y.Array`, `Y.XmlFragment`) live inside a `Y.Doc`. They are what you read and write. You access them by name: `doc.getText('body')`, `doc.getMap('properties')`, etc.
+- This library takes a `Y.Text` — one shared type out of one `Y.Doc`. The consumer chooses how many `Y.Doc`s exist, how they're synced, and which `Y.Text` inside which `Y.Doc` to plumb into each `YTextInput`.
+
+This means the library has no opinion on, and no awareness of, the persistence / sync architecture above it. A `Y.Doc` backed by `y-websocket` to a Node server, a `Y.Doc` backed by `y-indexeddb` for offline-first, or a `Y.Doc` whose update bytes are stored as a column in a relational database row and synced over a custom protocol — all are equivalent from this library's perspective. The library handles only the editor side of the Yjs binding.
+
+## Public API
+
+### Component
+
+```tsx
+import { YTextInput } from 'react-native-yjs-text';
+import * as Y from 'yjs';
+
+const doc = new Y.Doc();
+const yText = doc.getText('content');
+
+function MyEditor() {
+  return (
+    <YTextInput
+      yText={yText}
+      schema={defaultSchema}
+      style={styles.editor}
+      placeholder="Start typing..."
+      autoFocus
+      editable={true}
+      onSelectionChange={(selection) => {/* {from, to} as char offsets */}}
+      onFocus={() => {}}
+      onBlur={() => {}}
+    />
+  );
+}
+```
+
+### Editor commands (imperative API)
+
+For toolbar buttons and keyboard shortcuts:
+
+```ts
+import { useYTextEditor } from 'react-native-yjs-text';
+
+function Toolbar({ yText }) {
+  const editor = useYTextEditor(yText);
+
+  return (
+    <>
+      <Button onPress={() => editor.toggleMark('bold')} title="B" />
+      <Button onPress={() => editor.toggleMark('italic')} title="I" />
+      <Button
+        onPress={() => editor.setMark('link', { href: 'https://...' })}
+        title="Link"
+      />
+    </>
+  );
+}
+```
+
+Editor API surface (v0.1):
+
+```ts
+interface YTextEditor {
+  // selection
+  getSelection(): { from: number; to: number } | null;
+  setSelection(range: { from: number; to: number }): void;
+
+  // marks (formatting attributes)
+  toggleMark(name: string, attrs?: Record<string, unknown>): void;
+  setMark(name: string, attrs?: Record<string, unknown>): void;
+  removeMark(name: string): void;
+  marksAtSelection(): Record<string, unknown>;
+
+  // text content
+  insertText(text: string, attrs?: Record<string, unknown>): void;
+  deleteRange(from: number, to: number): void;
+
+  // focus
+  focus(): void;
+  blur(): void;
+  isFocused(): boolean;
+}
+```
+
+All commands operate at the current selection unless given explicit ranges.
+
+### Schema
+
+Schemas declare what marks are allowed and how each renders to native attributed text:
+
+```ts
+import type { Schema } from 'react-native-yjs-text';
+
+export const defaultSchema: Schema = {
+  marks: {
+    bold:      { renderStyle: { fontWeight: 'bold' } },
+    italic:    { renderStyle: { fontStyle: 'italic' } },
+    underline: { renderStyle: { textDecorationLine: 'underline' } },
+    strike:    { renderStyle: { textDecorationLine: 'line-through' } },
+    code:      { renderStyle: { fontFamily: 'Menlo', backgroundColor: '#f4f4f4' } },
+    link: {
+      attrs: { href: { type: 'string', required: true } },
+      renderStyle: { color: '#0066cc', textDecorationLine: 'underline' },
+      onTap: (attrs) => Linking.openURL(attrs.href),
+    },
+  },
+};
+```
+
+The schema is what makes the library safe for AI generation: typed marks, declared attributes, no schema-undeclared marks accepted. Consumers can register custom marks (e.g. `mention`, `highlight`) by extending the schema.
+
+### Mark conventions
+
+To stay interoperable with `y-prosemirror` (so that the same `Y.Text` content edits identically on web via ProseMirror and on mobile via this library), the library defines canonical mark names:
+
+| Mark name | Attributes | Semantics |
+|---|---|---|
+| `bold` | none | Bold text |
+| `italic` | none | Italic text |
+| `underline` | none | Underlined text |
+| `strike` | none | Strikethrough text |
+| `code` | none | Inline code |
+| `link` | `href: string` | Hyperlink |
+
+Custom marks are namespaced by the consumer (e.g. `pear.mention`, `pear.highlight`). The schema is the source of truth for what a given consumer accepts.
+
+### Read-only renderer
+
+A lightweight read-only component for displaying rich text without the editing machinery:
+
+```tsx
+import { YTextRenderer } from 'react-native-yjs-text';
+
+<YTextRenderer yText={yText} schema={defaultSchema} style={styles.body} />
+```
+
+This is a normal `Text` view under the hood with attributed spans — no `UITextView` / `EditText`, no event handling, no focus. Significantly cheaper than `YTextInput` and the right choice for lists of read-only content.
+
+## iOS implementation strategy
+
+- **`YTextInputView` subclasses `UITextView`.** Inherits accessibility, selection handles, keyboard, IME for free.
+- **Y.Text → `NSAttributedString` translation.** Walk the Y.Text content with formatting attributes, emit `NSAttributedString` runs with corresponding `NSAttributedString.Key` values (`.font`, `.foregroundColor`, `.underlineStyle`, `.link`).
+- **Edit capture via `textView(_:shouldChangeTextIn:replacementText:)`.** Each delta becomes a Y.Text `insert` / `delete` / `format` op. For v0.1 this is sufficient for non-IME input.
+- **Selection bridge.** `UITextView.selectedRange` is `NSRange` over character offsets, directly compatible with `Y.Text` offsets (with one caveat: `NSRange` is UTF-16-encoded, `Y.Text` is UTF-16-encoded in JS, so they agree by default).
+- **Remote-edit handling.** When the `Y.Text` is mutated remotely (or by the consuming app), the view updates `attributedText` and uses `Y.RelativePosition` to keep the local caret in the right place across concurrent insertions.
+
+iOS v0.1 known gaps: IME composition for CJK scripts uses `markedTextRange`, which doesn't fully integrate with `shouldChangeTextIn` in all edge cases. v0.1 will produce reasonable behavior for English/Latin; CJK IME correctness lands in v0.2.
+
+## Android implementation strategy
+
+- **`YTextInputView` subclasses `AppCompatEditText`.**
+- **Y.Text → `SpannableStringBuilder` translation.** Mark attributes map to standard `Span` types: `StyleSpan(BOLD)`, `StyleSpan(ITALIC)`, `UnderlineSpan`, `StrikethroughSpan`, `TypefaceSpan`, `URLSpan`, etc.
+- **Edit capture via `TextWatcher` + `InputFilter`.** Less precise than `shouldChangeTextIn`, but sufficient for v0.1. Long-term: implement a custom `InputConnection` for full IME correctness.
+- **Selection bridge.** `getSelectionStart()` / `getSelectionEnd()` ↔ Y.Text offsets, directly.
+- **Remote-edit handling.** Same Y.RelativePosition pattern as iOS.
+
+Android v0.1 known gaps: IME for CJK scripts and predictive text behave reasonably for short inputs but may have edge cases. v0.2 introduces a custom `InputConnection`.
+
+## JS ↔ native bridge
+
+For v0.1: use the React Native standard bridge (or Fabric / TurboModules under the new architecture). Edits flow:
+
+1. User types → native view receives input event
+2. Native view emits an event to JS with the delta (`insert`, `delete`, or `format`)
+3. JS applies the delta to the `Y.Text` (this triggers the existing Yjs sync layer)
+4. The `Y.Text` change event fires; the view receives a prop update
+5. View updates its attributed text — *taking care to no-op for changes that originated locally* (otherwise we'd lose the caret)
+
+This requires careful loop-breaking via origin tracking on Y.Text transactions, identical in shape to how `y-prosemirror` handles the same problem on web.
+
+Performance note: For deep `Y.Text` mutations, sending each character event over the bridge is fine for human typing speeds (low tens of events/sec) but inadequate for paste of long content or remote bulk edits. v0.2 introduces JSI direct calls for the hot path.
+
+## Versioning roadmap
+
+### v0.1 — Editable on both platforms
+
+- iOS + Android native views
+- Default schema: `bold`, `italic`, `underline`, `strike`, `code`, `link`
+- Editor command API (toggleMark, setMark, removeMark, getSelection, setSelection, insertText, deleteRange, focus/blur)
+- `YTextRenderer` read-only component
+- Yjs sync via standard bridge
+- English / Latin-script editing
+- Basic accessibility (inherited from `UITextView` / `EditText`)
+- Example app
+
+**Out of scope for v0.1:** CJK IME correctness, paste-from-clipboard with attribute preservation, hardware keyboard shortcuts.
+
+### v0.2 — Polish
+
+- Full IME correctness on iOS via custom `UITextInput` conformance
+- Full IME correctness on Android via custom `InputConnection`
+- Paste-from-clipboard with attribute preservation (web → native fidelity)
+- Hardware keyboard shortcuts (Cmd+B, Cmd+I, Cmd+K, etc.) with configurable bindings
+- Better accessibility audit (VoiceOver, TalkBack)
+- JSI direct calls for the typing hot path
+
+### v0.3 — Inline embeds
+
+Mentions, hashtags, emoji-as-image, and other inline non-text nodes. Probably implemented as zero-width characters with formatting attributes that the renderer treats as opaque embeds, with consumer-provided render callbacks.
+
+### v1.0 — Production grade
+
+Above + extended platform / accessibility / i18n testing matrix, performance benchmarks, full collaborative-cursor support, stable API.
+
+Multi-block editing in one view is not on the roadmap. See "Document shape" above.
+
+## Open questions
+
+These are unresolved and need decisions before or during implementation:
+
+1. **Inline non-text content (mentions, emoji-as-image).** Y.Text is fundamentally a sequence of characters with attribute spans. There are two viable encodings for inline embeds:
+   - **Sentinel character + attribute:** insert a zero-width or placeholder character with a `mention` formatting attribute carrying the data. Simple, works with Y.Text natively, breaks down for complex embed shapes.
+   - **Parallel Y.Array of inline nodes spliced in by offset:** richer, more like ProseMirror's inline node model, but requires the library to manage two structures in sync.
+
+   v0.1 will defer this; v0.3 needs a decision. The first option is likely correct for the 80% case.
+
+2. **Collaborative cursor / selection awareness.** Y.RelativePosition gives us the primitive. Should remote cursors be rendered by the library, or exposed as data for the consumer to render? Probably the latter (library exposes a `useRemoteCursors(yText)` hook, consumer renders them however they want — they may want avatars, names, etc.).
+
+3. **Selection persistence on remote insertion.** When a remote edit inserts characters before the local caret, the caret should shift to remain in "the same logical position." Y.RelativePosition handles this. Need to confirm the iOS / Android implementations preserve this correctly across the bridge.
+
+4. **Undo/redo semantics.** Yjs has `Y.UndoManager`. Should the library wire it into the platform's native undo (the "shake to undo" gesture on iOS, the system undo on Android), or expose `undo()` / `redo()` for the consumer to wire? Probably both — default platform undo wired by default, with an opt-out and an explicit `editor.undo()` available.
+
+5. **Schema validation timing.** Should marks that aren't in the schema be silently dropped on insert, throw, or warn? Likely: warn in dev, silently drop in prod, with an `onSchemaViolation` callback for consumers to plumb to error reporting.
+
+6. **Plain-text fallback.** If a consumer wants the editing surface but not formatting, is `YTextInput` with an empty mark set the right answer, or should there be a dedicated `YPlainTextInput`? Probably the former is fine — empty marks just gives you a Yjs-backed plain text input, which is itself a useful thing.
+
+7. **Web parity through `y-prosemirror`.** The library targets RN. The expectation is that consumers using both web and RN will use `y-prosemirror` + a Pear-defined ProseMirror schema on web, and `react-native-yjs-text` + an equivalent schema here, with the two schemas hand-aligned. Should we ship a *shared schema spec* (probably as a separate `yjs-text-schema` package) so the alignment is enforced rather than aspirational? Yes, probably, but not for v0.1.
+
+## License and governance
+
+MIT or Apache 2.0 (final pick on initial commit). The library is intentionally permissively licensed to maximize adoption — every React Native team that's wanted non-WebView rich text editing should be able to use it without license friction. Pear remains AGPL; the two licenses don't conflict because the library is a separate work.
+
+Governance: open-source maintainership from day one. Pear's interests are served by the library being healthy and widely used, not by exclusive control.
+
+## Relationship to Pear (and why this lives in pear-cloud temporarily)
+
+Pear's editing layer commits to:
+
+- `Y.Text` as the rich-text primitive within every text-bearing leaf of the `ComponentNode` tree
+- `y-prosemirror` (or a future custom `Y.Text` binding) + a Pear-defined schema as the web editor
+- `react-native-yjs-text` + the same schema as the mobile editor
+- A renderer (web and RN) over the `ComponentNode` tree, with `RichText` components delegating their content to either `YTextRenderer` (read-only) or `YTextInput` (edit-mode)
+
+### How Yjs and SpacetimeDB layer together in Pear
+
+This is the configuration the library has to work with in Pear, and is worth describing because it's a useful pattern for other consumers too:
+
+- **SpacetimeDB is the outer substrate.** Every typed row — pages, properties, component trees, access rules, snapshots — lives in SpacetimeDB. Reducers mediate every mutation. Subscriptions push row changes to clients in real time. Permissions are enforced at the database layer.
+- **Yjs is an inner substrate within specific cells.** The `Y.Doc` backing a `RichText` `ComponentNode` is serialized into a SpacetimeDB column (today: `PageYjsState`; in the merged architecture: per-`ComponentNode` Yjs state). SpacetimeDB does not try to merge the Yjs bytes — it stores them, fans out updates via subscription, and the client-side Yjs runtime handles the CRDT merge.
+- **The two layers do orthogonal work.** SpacetimeDB owns row identity, schema, access control, mediation, attribution, and cross-document queries. Yjs owns intra-cell concurrent editing semantics. Neither replaces the other; they compose.
+
+From this library's perspective, none of this matters — the library only sees a `Y.Text`. The fact that the `Y.Doc` containing that `Y.Text` is persisted and synced via a custom SpacetimeDB-backed provider is invisible to it. The same library, with the same API, can be used by a consumer running `y-websocket` to a Node server.
+
+### What this enables for Pear
+
+This setup means the merged `CUSTOM_VIEW_PRIMITIVES.md` / `PEAR_PROGRAMMING.md` document can credibly claim *"no WebView anywhere in the stack"* as a real long-term commitment rather than aspiration. v1 of Pear mobile can ship with read-only rich text rendering (`YTextRenderer`, available day one of `react-native-yjs-text`) and defer editing to a desktop session or open the rich-text block in a controlled WebView; v1.5 of Pear mobile ships native editing when `react-native-yjs-text` v0.1 lands.
+
+This spec lives in `pear-cloud` only until it's ready to move to its own repository. Implementation work will happen in the standalone repo from the start.
+
+## Next steps
+
+1. Review and revise this spec.
+2. Spike: 1-day proof-of-concept on iOS — `UITextView` subclass that renders a `Y.Text` with bold marks, captures typing, applies Y.Text ops, syncs back to the view. Confirms the architecture before committing to the repo split.
+3. If spike succeeds: create the standalone repository, copy this spec as the README, scaffold the package, ship v0.1 against the spec above.
+4. Update `PEAR_PROGRAMMING.md` / `CUSTOM_VIEW_PRIMITIVES.md` (in their merged form) to reference this library as Pear's rich-text editing primitive on mobile.

package/android/build.gradle

@@ -0,0 +1,26 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'tech.eclosion.yjstext'
+version = '0.1.0'
+
+android {
+  namespace "tech.eclosion.yjstext"
+  defaultConfig {
+    versionCode 1
+    versionName "0.1.0"
+  }
+  lintOptions {
+    abortOnError false
+  }
+}
+
+dependencies {
+  // AppCompatEditText: the editable surface inside YjsTextView. AppCompat is
+  // usually present transitively in any RN app, but we depend on it
+  // explicitly so the library can be consumed by a non-AppCompat-using host
+  // (rare but possible in greenfield Compose apps).
+  implementation 'androidx.appcompat:appcompat:1.7.0'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest>
+</manifest>

package/android/src/main/java/tech/eclosion/yjstext/YjsTextModule.kt

@@ -0,0 +1,77 @@
+package tech.eclosion.yjstext
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+/**
+ * Expo Module registration for `@eclosion-tech/react-native-yjs-text` on Android.
+ *
+ * Mirrors `YjsTextModule.swift` — same view name (`YjsText`), same set of
+ * events, same set of props, same imperative methods. The JS side talks to
+ * either platform indifferently as long as the contract stays in sync.
+ */
+class YjsTextModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("YjsText")
+
+    View(YjsTextView::class) {
+      Events(
+        "onContentChange",
+        "onNativeSelectionChange",
+        "onFocusChange",
+        "onMarkTap"
+      )
+
+      // MARK: - Props
+
+      Prop("runs") { view: YjsTextView, value: List<YjsTextRunRecord> ->
+        view.runs = value
+      }
+      Prop("renderSpec") { view: YjsTextView, value: Map<String, YjsTextMarkStyleRecord> ->
+        view.renderSpec = value
+      }
+      Prop("pendingSelection") { view: YjsTextView, value: YjsTextSelectionRecord? ->
+        view.pendingSelection = value
+      }
+      Prop("editable") { view: YjsTextView, value: Boolean ->
+        view.editable = value
+      }
+      Prop("placeholder") { view: YjsTextView, value: String? ->
+        view.placeholder = value
+      }
+      Prop("placeholderColor") { view: YjsTextView, value: String? ->
+        view.placeholderColor = YjsTextColor.parse(value)
+      }
+      Prop("baseFontSize") { view: YjsTextView, value: Double? ->
+        view.baseFontSize = value
+      }
+      Prop("baseFontFamily") { view: YjsTextView, value: String? ->
+        view.baseFontFamily = value
+      }
+      Prop("baseColor") { view: YjsTextView, value: String? ->
+        view.baseColor = YjsTextColor.parse(value)
+      }
+      Prop("baseFontWeight") { view: YjsTextView, value: String? ->
+        view.baseFontWeight = value
+      }
+      Prop("baseFontStyle") { view: YjsTextView, value: String? ->
+        view.baseFontStyle = value
+      }
+
+      // MARK: - View methods (callable via the view's React ref)
+
+      AsyncFunction("focus") { view: YjsTextView ->
+        view.focusInput()
+      }
+      AsyncFunction("blur") { view: YjsTextView ->
+        view.blurInput()
+      }
+      AsyncFunction("isFocused") { view: YjsTextView ->
+        view.isInputFocused()
+      }
+      AsyncFunction("setSelection") { view: YjsTextView, from: Int, to: Int ->
+        view.setSelection(from, to)
+      }
+    }
+  }
+}

package/android/src/main/java/tech/eclosion/yjstext/YjsTextSupport.kt

@@ -0,0 +1,135 @@
+package tech.eclosion.yjstext
+
+import android.graphics.Color
+import expo.modules.kotlin.records.Field
+import expo.modules.kotlin.records.Record
+import java.io.Serializable
+
+/**
+ * Bridge records mirroring the iOS `YjsTextSupport.swift` shapes. Keep the
+ * field names byte-for-byte identical to their iOS counterparts and the JS
+ * `SerializedRun` / `CompiledRenderSpec` types — Expo Modules deserialises
+ * by field name.
+ */
+
+class YjsTextRunRecord : Record, Serializable {
+  @Field var text: String = ""
+  @Field var marksJson: String = "{}"
+}
+
+class YjsTextMarkStyleRecord : Record, Serializable {
+  @Field var fontWeight: String? = null
+  @Field var fontStyle: String? = null
+  @Field var fontFamily: String? = null
+  @Field var fontSize: Double? = null
+  @Field var color: String? = null
+  @Field var backgroundColor: String? = null
+  @Field var textDecorationLine: String? = null
+}
+
+/**
+ * JS-pushed selection bundle. `version` is a monotonic counter bumped every
+ * time the JS side wants the native view to (re-)apply a selection — we
+ * re-apply only when it changes from the last value we observed.
+ *
+ * Bundled into a single Record (rather than two separate props) so the
+ * setter is atomic. With separate `selection` + `selectionVersion` props,
+ * Expo Modules' prop setter ordering on Fabric is unspecified, so the
+ * version setter could fire before the value setter and read a stale
+ * selection — producing a "selection jumps to previously selected text"
+ * bug. Bundling sidesteps that race.
+ */
+class YjsTextSelectionRecord : Record, Serializable {
+  @Field var from: Int = 0
+  @Field var to: Int = 0
+  @Field var version: Int = -1
+}
+
+class YjsTextContentChangePayload : Record, Serializable {
+  @Field var type: String = "replace"
+  @Field var from: Int = 0
+  @Field var to: Int = 0
+  @Field var text: String = ""
+}
+
+class YjsTextSelectionEventPayload : Record, Serializable {
+  @Field var from: Int = 0
+  @Field var to: Int = 0
+}
+
+class YjsTextFocusEventPayload : Record, Serializable {
+  @Field var focused: Boolean = false
+}
+
+class YjsTextMarkTapPayload : Record, Serializable {
+  @Field var mark: String = ""
+  @Field var attrsJson: String = "{}"
+}
+
+/**
+ * CSS-flavoured colour parser used to turn `style.color` / `backgroundColor`
+ * strings sent from JS into Android `@ColorInt` integers.
+ *
+ * Android's `Color.parseColor` accepts `#rrggbb` / `#aarrggbb` (alpha-first)
+ * and a small set of named colours, but the web / iOS convention is
+ * `#rrggbbaa` (alpha-last). We translate alpha-last hex to the alpha-first
+ * form before delegating, and fall back to `null` (caller uses default) on
+ * any parse failure.
+ */
+object YjsTextColor {
+  fun parse(raw: String?): Int? {
+    val s = raw?.trim().orEmpty()
+    if (s.isEmpty()) return null
+    return try {
+      when {
+        s.startsWith("#") -> parseHex(s.substring(1))
+        s.startsWith("rgb", ignoreCase = true) -> parseRgb(s)
+        else -> when (s.lowercase()) {
+          "black" -> Color.BLACK
+          "white" -> Color.WHITE
+          "transparent" -> Color.TRANSPARENT
+          else -> Color.parseColor(s)
+        }
+      }
+    } catch (_: Throwable) {
+      null
+    }
+  }
+
+  private fun parseHex(hex: String): Int? {
+    val upper = hex.uppercase()
+    val normalised = when (upper.length) {
+      3 -> {
+        val r = upper[0].toString().repeat(2)
+        val g = upper[1].toString().repeat(2)
+        val b = upper[2].toString().repeat(2)
+        "FF$r$g$b"
+      }
+      6 -> "FF$upper"
+      8 -> {
+        // Web convention: #rrggbbaa. Android expects #aarrggbb.
+        val rrggbb = upper.substring(0, 6)
+        val aa = upper.substring(6, 8)
+        "$aa$rrggbb"
+      }
+      else -> return null
+    }
+    val value = normalised.toLong(16)
+    return value.toInt()
+  }
+
+  private fun parseRgb(raw: String): Int? {
+    val inner = raw
+      .replace(" ", "")
+      .replace("rgba(", "")
+      .replace("rgb(", "")
+      .replace(")", "")
+    val parts = inner.split(",")
+    if (parts.size !in 3..4) return null
+    val r = parts[0].toIntOrNull() ?: return null
+    val g = parts[1].toIntOrNull() ?: return null
+    val b = parts[2].toIntOrNull() ?: return null
+    val a = if (parts.size == 4) ((parts[3].toDoubleOrNull() ?: 1.0) * 255).toInt() else 255
+    return Color.argb(a.coerceIn(0, 255), r.coerceIn(0, 255), g.coerceIn(0, 255), b.coerceIn(0, 255))
+  }
+}