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

package/src/internal/NativeYTextInputView.tsx

@@ -0,0 +1,126 @@
+import { requireNativeView } from 'expo';
+import * as React from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import type { CompiledRenderSpec } from '../schema';
+import type { MarkAttrs, Run, SelectionRange } from '../types';
+
+/**
+ * Selection bundle pushed to native as a single atomic prop.
+ *
+ * Bundling `from`/`to`/`version` into one Record (rather than two separate
+ * props on the native side) sidesteps Expo Modules' unspecified prop-setter
+ * ordering on Fabric: if the version prop were applied before the value,
+ * the native side would re-apply a stale selection and the user would see
+ * the previous selection "jump back" after every format toggle.
+ */
+export interface SerializedPendingSelection {
+  from: number;
+  to: number;
+  version: number;
+}
+
+/**
+ * A single run as it goes over the bridge to native. Marks are JSON-serialised
+ * because Expo Module `Record` fields don't cleanly accept heterogeneous
+ * `[String: Any]` dictionaries (mark attrs are arbitrary per the schema), and
+ * the cost of a JSON round-trip per run on every render is negligible compared
+ * to the layout work native then does.
+ */
+export interface SerializedRun {
+  text: string;
+  /** JSON-stringified `Record<string, unknown>` of mark name -> attrs. */
+  marksJson: string;
+}
+
+/** Serialise a public {@link Run} into the bridge representation. */
+export function serializeRun(run: Run): SerializedRun {
+  return {
+    text: run.text,
+    marksJson: JSON.stringify(run.marks ?? {}),
+  };
+}
+
+/**
+ * Props sent to the native `YjsText` view across the bridge. Keep this shape
+ * stable — the iOS and Android sides parse it; adding a key requires native
+ * changes on both sides.
+ */
+export interface NativeYTextInputViewProps {
+  /**
+   * Attributed runs to render. Native always rebuilds when this prop
+   * changes — we used to ship a sibling `contentVersion: number` prop to
+   * force re-apply on attr-only changes, but Expo Modules' Fabric setter
+   * ordering didn't guarantee `runs` was applied before `contentVersion`,
+   * which caused every toggle to render the *previous* runs. Collapsing
+   * to a single trigger sidesteps the race entirely. The JS side prevents
+   * redundant pushes by memoising this array on a `contentVersion` state
+   * that bumps only on real Y.Text changes.
+   */
+  runs: SerializedRun[];
+  /**
+   * Per-mark style spec. Inner keys are bounded by `RENDERABLE_TEXT_STYLE_KEYS`
+   * so this serialises cleanly into a typed Swift / Kotlin Record.
+   */
+  renderSpec: CompiledRenderSpec;
+  /**
+   * Atomic selection bundle. Native re-applies whenever the embedded
+   * `version` differs from the last value it observed. `null` means "no
+   * JS-driven selection yet" — native leaves the in-flight user selection
+   * alone.
+   */
+  pendingSelection: SerializedPendingSelection | null;
+  editable: boolean;
+  placeholder?: string;
+  placeholderColor?: string;
+  baseFontSize?: number;
+  baseFontFamily?: string;
+  baseColor?: string;
+  baseFontWeight?: string;
+  baseFontStyle?: string;
+  style?: StyleProp<ViewStyle>;
+
+  onContentChange?: (event: {
+    nativeEvent: { type: 'replace'; from: number; to: number; text: string };
+  }) => void;
+  onNativeSelectionChange?: (event: { nativeEvent: { from: number; to: number } }) => void;
+  onFocusChange?: (event: { nativeEvent: { focused: boolean } }) => void;
+  onMarkTap?: (event: { nativeEvent: { mark: string; attrsJson: string } }) => void;
+}
+
+/** Parse a mark-tap event payload from native back into a `MarkAttrs` object. */
+export function parseMarkTapAttrs(attrsJson: string): MarkAttrs {
+  if (!attrsJson) return {};
+  try {
+    const parsed = JSON.parse(attrsJson);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Direct handle to the underlying native `UITextView` / `AppCompatEditText`.
+ * Exposed via {@link React.useImperativeHandle} so the JS layer can call
+ * focus/blur/setSelection without going through props.
+ *
+ * Implemented as Expo Modules `AsyncFunction`s on the native side that take a
+ * view tag and dispatch to the matching view instance.
+ */
+export interface NativeYTextInputViewRef {
+  focus(): void;
+  blur(): void;
+  setSelection(range: SelectionRange): void;
+  isFocused(): boolean;
+}
+
+/** Resolved at module load: the Expo native view registered as `YjsText`. */
+const NativeView: React.ComponentType<NativeYTextInputViewProps & { ref?: React.Ref<unknown> }> =
+  requireNativeView('YjsText');
+
+export const NativeYTextInputView = React.forwardRef<
+  NativeYTextInputViewRef,
+  NativeYTextInputViewProps
+>(function NativeYTextInputView(props, ref) {
+  return <NativeView {...props} ref={ref} />;
+});

package/src/internal/editorRegistry.ts

@@ -0,0 +1,50 @@
+import type * as Y from 'yjs';
+
+import type { MarkAttrs, SelectionRange } from '../types';
+
+/**
+ * The slice of editor state a {@link YTextInput} contributes to the registry
+ * when it mounts. Lets the imperative {@link useYTextEditor} hook reach into
+ * the native view for focus / selection / etc. without prop-drilling refs.
+ */
+export interface EditorHandle {
+  /** Current absolute selection, or `null` if the view isn't focused. */
+  getSelection(): SelectionRange | null;
+  /** Pending marks set by `toggleMark` while the caret is collapsed. */
+  getPendingMarks(): MarkAttrs;
+  setPendingMarks(marks: MarkAttrs): void;
+  /** Imperative view operations forwarded to the native view. */
+  focus(): void;
+  blur(): void;
+  isFocused(): boolean;
+  setSelection(range: SelectionRange): void;
+}
+
+/**
+ * The registry is keyed by Y.Text identity so that any consumer holding a
+ * reference to the same Y.Text can resolve the live editor handle without
+ * prop-drilling. A {@link Y.Text} maps to one handle at most — there's one
+ * active editor per logical text region by design (the per-block model
+ * documented in the spec).
+ *
+ * We use a `WeakMap` so unmounted editors don't pin their Y.Texts in memory
+ * forever.
+ */
+const REGISTRY = new WeakMap<Y.Text, EditorHandle>();
+
+export function registerEditor(yText: Y.Text, handle: EditorHandle): void {
+  REGISTRY.set(yText, handle);
+}
+
+export function unregisterEditor(yText: Y.Text, handle: EditorHandle): void {
+  // Only unregister if the current entry is still us — protects against the
+  // race where a new editor for the same Y.Text mounts before the old one's
+  // cleanup runs.
+  if (REGISTRY.get(yText) === handle) {
+    REGISTRY.delete(yText);
+  }
+}
+
+export function getEditor(yText: Y.Text): EditorHandle | undefined {
+  return REGISTRY.get(yText);
+}

package/src/schema.ts

@@ -0,0 +1,157 @@
+import type { TextStyle } from 'react-native';
+
+import type { MarkAttrs, Schema } from './types';
+
+/**
+ * The default schema covering the v0.1 canonical mark set documented in the
+ * spec. Consumers can use this as-is, extend it, or replace it entirely.
+ *
+ * Mark names and semantics match the y-prosemirror schema convention so that a
+ * Y.Text edited on web via ProseMirror and on mobile via this library renders
+ * identically.
+ */
+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',
+      },
+    },
+  },
+};
+
+/**
+ * Subset of `TextStyle` keys forwarded to the native side. Keys outside this
+ * list are silently ignored — they may make sense on the web but have no
+ * cross-platform native equivalent, or require per-platform work we haven't
+ * done yet.
+ *
+ * If you need a key not listed here, open an issue. Adding one usually means
+ * teaching both the iOS NSAttributedString and Android Spannable layers how to
+ * apply it.
+ */
+export const RENDERABLE_TEXT_STYLE_KEYS = [
+  'fontWeight',
+  'fontStyle',
+  'fontFamily',
+  'fontSize',
+  'color',
+  'backgroundColor',
+  'textDecorationLine',
+] as const satisfies readonly (keyof TextStyle)[];
+
+/**
+ * The compiled-down render spec sent over the bridge.
+ *
+ * One entry per mark, containing only the keys the native renderer knows how
+ * to handle. We compile once when the schema prop changes rather than parsing
+ * the whole `MarkSpec` on every render of every run.
+ */
+export type CompiledRenderSpec = Record<
+  string,
+  Partial<Record<(typeof RENDERABLE_TEXT_STYLE_KEYS)[number], unknown>>
+>;
+
+/**
+ * Reduce a {@link Schema} to its renderable subset. Strips function callbacks
+ * (`onTap`), strips attribute schemas, normalises `textDecorationLine` to a
+ * single canonical string. Stable for memoisation: same input → equal output.
+ */
+export function compileRenderSpec(schema: Schema): CompiledRenderSpec {
+  const out: CompiledRenderSpec = {};
+  for (const [name, spec] of Object.entries(schema.marks)) {
+    const style = spec.renderStyle;
+    if (!style) {
+      out[name] = {};
+      continue;
+    }
+    const compiled: CompiledRenderSpec[string] = {};
+    for (const key of RENDERABLE_TEXT_STYLE_KEYS) {
+      const value = style[key];
+      if (value !== undefined) {
+        compiled[key] = value;
+      }
+    }
+    out[name] = compiled;
+  }
+  return out;
+}
+
+/**
+ * Validate that every mark in `attrs` is declared in the schema and that its
+ * attributes match the declared shape. Returns the sanitised attrs (with
+ * undeclared marks stripped) and the list of violations.
+ *
+ * Used on insert paths (programmatic `insertText`, future paste handlers) to
+ * keep AI-generated or pasted content from smuggling in unknown marks.
+ */
+export function validateMarks(
+  marks: MarkAttrs,
+  schema: Schema
+): {
+  sanitised: MarkAttrs;
+  violations: { mark: string; attrs: MarkAttrs }[];
+} {
+  const sanitised: MarkAttrs = {};
+  const violations: { mark: string; attrs: MarkAttrs }[] = [];
+  for (const [markName, attrs] of Object.entries(marks)) {
+    const spec = schema.marks[markName];
+    if (!spec) {
+      violations.push({ mark: markName, attrs: (attrs as MarkAttrs) ?? {} });
+      continue;
+    }
+    if (!spec.attrs) {
+      sanitised[markName] = attrs ?? {};
+      continue;
+    }
+    const incoming = (attrs ?? {}) as MarkAttrs;
+    const validated: MarkAttrs = {};
+    let ok = true;
+    for (const [attrName, attrSpec] of Object.entries(spec.attrs)) {
+      const value = incoming[attrName];
+      if (value === undefined) {
+        if (attrSpec.required && attrSpec.default === undefined) {
+          ok = false;
+          break;
+        }
+        if (attrSpec.default !== undefined) {
+          validated[attrName] = attrSpec.default;
+        }
+        continue;
+      }
+      if (typeof value !== attrSpec.type) {
+        ok = false;
+        break;
+      }
+      validated[attrName] = value;
+    }
+    if (ok) {
+      sanitised[markName] = validated;
+    } else {
+      violations.push({ mark: markName, attrs: incoming });
+    }
+  }
+  return { sanitised, violations };
+}

package/src/types.ts

@@ -0,0 +1,194 @@
+import type { StyleProp, TextStyle } from 'react-native';
+import type * as Y from 'yjs';
+
+/**
+ * A formatting attribute attached to a span of text inside a {@link Y.Text}.
+ *
+ * Marks are the unit of inline formatting. They have a name (`bold`, `italic`,
+ * `link`, etc.) and an optional bag of attributes (`href` for links, `level` for
+ * headings if you ever invent one, etc.). They mirror the y-prosemirror mark
+ * convention so the same Y.Text content edits identically on web (via
+ * y-prosemirror over a ProseMirror schema) and on mobile (via this library).
+ */
+export type MarkAttrs = Record<string, unknown>;
+
+/**
+ * Declaration of a single mark in a {@link Schema}.
+ *
+ * @property attrs Optional schema for the mark's attributes. Validated on insert.
+ *   If a mark takes no attributes (e.g. `bold`, `italic`), omit this entirely.
+ * @property renderStyle The style applied to spans bearing this mark when the
+ *   editor renders to native text. Only a subset of RN's `TextStyle` is honoured
+ *   on native (see {@link RENDERABLE_TEXT_STYLE_KEYS}); other keys are ignored.
+ * @property onTap Optional handler invoked when the user taps a span bearing
+ *   this mark. The classic use case is `link` opening a URL. The handler runs in
+ *   JS regardless of which platform fired the tap.
+ */
+export interface MarkSpec {
+  attrs?: Record<
+    string,
+    {
+      type: 'string' | 'number' | 'boolean';
+      required?: boolean;
+      default?: unknown;
+    }
+  >;
+  renderStyle?: TextStyle;
+  onTap?: (attrs: MarkAttrs) => void;
+}
+
+/**
+ * The set of marks an editor instance accepts.
+ *
+ * The schema is the contract between the consuming application and the editor.
+ * Marks not declared here are dropped on insert (with an optional warning, see
+ * {@link YTextInputProps.onSchemaViolation}). This is what makes the editor safe
+ * for AI-generated content: an LLM cannot smuggle in `<script>`-equivalent
+ * marks that the consumer hasn't explicitly opted into.
+ */
+export interface Schema {
+  marks: Record<string, MarkSpec>;
+}
+
+/**
+ * A contiguous run of text bearing the same formatting marks.
+ *
+ * This is the wire format used to push attributed text down to the native view.
+ * A {@link Y.Text} is converted to `Run[]` via {@link ytextToRuns}; the native
+ * side renders each run with the styles declared in its schema's marks.
+ */
+export interface Run {
+  text: string;
+  marks: MarkAttrs;
+}
+
+/**
+ * A character-offset range inside a {@link Y.Text}.
+ *
+ * Offsets are UTF-16 code units, matching `Y.Text`'s native offsets, RN's
+ * `TextInput` selection, iOS `NSRange`, and Android `Editable.getSelectionStart`.
+ * A collapsed cursor is represented by `from === to`.
+ */
+export interface SelectionRange {
+  from: number;
+  to: number;
+}
+
+/**
+ * The shape of an edit emitted by the native view when the user types, pastes,
+ * or deletes.
+ *
+ * v0.1 uses a single `replace`-shaped edit that subsumes insert (`from === to`),
+ * delete (`text === ''`), and replace. This matches iOS's
+ * `textView(_:shouldChangeTextIn:replacementText:)` directly.
+ *
+ * @internal
+ */
+export interface ReplaceEdit {
+  type: 'replace';
+  from: number;
+  to: number;
+  text: string;
+}
+
+/**
+ * Props for the {@link YTextInput} editable component.
+ */
+export interface YTextInputProps {
+  /** The Y.Text whose content this editor displays and mutates. */
+  yText: Y.Text;
+  /** The set of marks accepted by this editor. See {@link Schema}. */
+  schema: Schema;
+  /** RN text style applied as the baseline (font family, size, default color). */
+  style?: StyleProp<TextStyle>;
+  /** Placeholder text shown when the Y.Text is empty. */
+  placeholder?: string;
+  /** Colour for the placeholder text. Defaults to a muted grey. */
+  placeholderTextColor?: string;
+  /** Auto-focus on mount (raises the keyboard). Defaults to `false`. */
+  autoFocus?: boolean;
+  /** Whether the editor accepts input. Defaults to `true`. */
+  editable?: boolean;
+  /** Fires whenever the user moves the caret or changes the selected range. */
+  onSelectionChange?: (selection: SelectionRange) => void;
+  /** Fires when the editor gains focus. */
+  onFocus?: () => void;
+  /** Fires when the editor loses focus. */
+  onBlur?: () => void;
+  /**
+   * Fires when an insert contains a mark not declared in the schema.
+   * The mark is dropped silently regardless; this is your hook to log the
+   * violation (e.g. when an LLM generates an unrecognised mark).
+   */
+  onSchemaViolation?: (info: { mark: string; attrs: MarkAttrs }) => void;
+}
+
+/**
+ * Props for the {@link YTextRenderer} read-only component.
+ */
+export interface YTextRendererProps {
+  /** The Y.Text to render. */
+  yText: Y.Text;
+  /** The schema describing how to render each mark. */
+  schema: Schema;
+  /** RN text style applied as the baseline. */
+  style?: StyleProp<TextStyle>;
+  /** Maximum lines to render before truncation. */
+  numberOfLines?: number;
+}
+
+/**
+ * The imperative editor API returned by {@link useYTextEditor}.
+ *
+ * All commands operate at the current selection unless given explicit ranges.
+ * Commands that mutate (`toggleMark`, `insertText`, ...) wrap the mutation in a
+ * Y.Doc transaction tagged with the {@link ORIGIN_LOCAL_VIEW} origin so the
+ * native view doesn't re-render itself in response.
+ */
+export interface YTextEditor {
+  /** Current selection, or `null` if the editor isn't focused. */
+  getSelection(): SelectionRange | null;
+  /** Move the cursor / select a range. No-op if the editor isn't mounted. */
+  setSelection(range: SelectionRange): void;
+
+  /**
+   * Toggle the mark across the current selection. If the entire selection
+   * already has the mark, removes it; otherwise applies it.
+   */
+  toggleMark(name: string, attrs?: MarkAttrs): void;
+  /** Force-apply the mark across the current selection. */
+  setMark(name: string, attrs?: MarkAttrs): void;
+  /** Remove the mark from the current selection. */
+  removeMark(name: string): void;
+  /**
+   * Marks currently active at the selection's start.
+   *
+   * For a collapsed selection this is the marks of the character to the left,
+   * plus any `pending marks` (marks toggled while the selection was collapsed,
+   * which apply to the next character typed).
+   */
+  marksAtSelection(): MarkAttrs;
+
+  /** Insert text at the current selection, replacing any selected range. */
+  insertText(text: string, attrs?: MarkAttrs): void;
+  /** Delete the given range. Offsets are in UTF-16 code units. */
+  deleteRange(from: number, to: number): void;
+
+  /** Raise the keyboard / programmatically focus the editor. */
+  focus(): void;
+  /** Dismiss the keyboard / blur the editor. */
+  blur(): void;
+  /** Whether the editor currently has keyboard focus. */
+  isFocused(): boolean;
+}
+
+/**
+ * The Yjs transaction origin used by this library when applying user edits
+ * captured from the native view, or programmatic edits from {@link YTextEditor}.
+ *
+ * Consumers can read `transaction.origin === ORIGIN_LOCAL_VIEW` to distinguish
+ * edits coming from the editor itself from edits coming from sync providers
+ * (`y-websocket`, your custom backend, etc.). The library uses it internally to
+ * avoid re-rendering the view in response to its own writes.
+ */
+export const ORIGIN_LOCAL_VIEW = Symbol('@eclosion-tech/react-native-yjs-text/local-view');

package/src/useYTextEditor.ts

@@ -0,0 +1,171 @@
+import { useMemo } from 'react';
+import type * as Y from 'yjs';
+
+import { formatRange, inheritedMarksAt, marksInRange, transactProgrammatic } from './bridge';
+import { getEditor } from './internal/editorRegistry';
+import { validateMarks } from './schema';
+import type { MarkAttrs, Schema, SelectionRange, YTextEditor } from './types';
+
+/**
+ * Build a stable imperative editor handle bound to `yText`.
+ *
+ * Returns the same `YTextEditor` instance across re-renders so that consumers
+ * can pass commands to event handlers without re-binding. The commands resolve
+ * the *current* live native view at call time via the editor registry — so
+ * unmounting and remounting the `YTextInput` doesn't break a toolbar that's
+ * holding the editor handle.
+ *
+ * If no `YTextInput` is currently mounted for this Y.Text, commands that need
+ * a live view (focus, selection-dependent mark toggles) gracefully no-op. Pure
+ * Y.Text mutations (`insertText` with explicit ranges via `deleteRange`,
+ * `setMark` on a known selection) still work — useful for programmatic edits.
+ *
+ * @param yText The Y.Text this editor mutates.
+ * @param schema The schema declaring which marks are valid.
+ */
+export function useYTextEditor(yText: Y.Text, schema: Schema): YTextEditor {
+  return useMemo<YTextEditor>(() => {
+    function currentSelection(): SelectionRange | null {
+      const handle = getEditor(yText);
+      return handle?.getSelection() ?? null;
+    }
+
+    function pendingMarks(): MarkAttrs {
+      return getEditor(yText)?.getPendingMarks() ?? {};
+    }
+
+    function setPendingMarks(marks: MarkAttrs): void {
+      getEditor(yText)?.setPendingMarks(marks);
+    }
+
+    return {
+      getSelection: currentSelection,
+
+      setSelection(range) {
+        getEditor(yText)?.setSelection(range);
+      },
+
+      toggleMark(name, attrs) {
+        const sel = currentSelection();
+        if (!sel) return;
+        // Validate first — if the mark isn't in the schema, we drop on the floor.
+        const { sanitised, violations } = validateMarks({ [name]: attrs ?? {} }, schema);
+        if (violations.length > 0 || !(name in sanitised)) return;
+        const normalisedAttrs = sanitised[name] as MarkAttrs;
+
+        if (sel.from === sel.to) {
+          // Collapsed selection: toggle pending mark. The next typed
+          // character will adopt it (or strip it if turning off).
+          const pending = pendingMarks();
+          const inherited = inheritedMarksAt(yText, sel.from);
+          const isOnInherited = name in inherited;
+          const isOnPending = name in pending;
+          const isOn = isOnPending ? Boolean(pending[name]) : isOnInherited;
+          const next: MarkAttrs = { ...pending };
+          if (isOn) {
+            // Mark is currently on for the next-character — turn it off.
+            // We have to distinguish: if it's on via inheritance, set
+            // `false` so the insert path overrides; if only via pending,
+            // delete the pending entry.
+            if (isOnInherited) next[name] = false;
+            else delete next[name];
+          } else {
+            next[name] = normalisedAttrs;
+          }
+          setPendingMarks(next);
+          return;
+        }
+
+        // Range selection: format the range. Turn on unless every char
+        // already has the mark, in which case turn off.
+        const common = marksInRange(yText, sel.from, sel.to);
+        const allHaveIt = name in common;
+        formatRange(yText, sel.from, sel.to, name, allHaveIt ? null : normalisedAttrs);
+      },
+
+      setMark(name, attrs) {
+        const sel = currentSelection();
+        if (!sel) return;
+        const { sanitised, violations } = validateMarks({ [name]: attrs ?? {} }, schema);
+        if (violations.length > 0 || !(name in sanitised)) return;
+        if (sel.from === sel.to) {
+          setPendingMarks({ ...pendingMarks(), [name]: sanitised[name] as MarkAttrs });
+          return;
+        }
+        formatRange(yText, sel.from, sel.to, name, sanitised[name] as MarkAttrs);
+      },
+
+      removeMark(name) {
+        const sel = currentSelection();
+        if (!sel) return;
+        if (sel.from === sel.to) {
+          const pending = pendingMarks();
+          const inherited = inheritedMarksAt(yText, sel.from);
+          const next: MarkAttrs = { ...pending };
+          if (name in inherited) {
+            next[name] = false;
+          } else {
+            delete next[name];
+          }
+          setPendingMarks(next);
+          return;
+        }
+        formatRange(yText, sel.from, sel.to, name, null);
+      },
+
+      marksAtSelection() {
+        const sel = currentSelection();
+        if (!sel) return {};
+        const base =
+          sel.from === sel.to
+            ? inheritedMarksAt(yText, sel.from)
+            : marksInRange(yText, sel.from, sel.to);
+        // Overlay pending marks: `false` removes, anything truthy replaces.
+        const pending = pendingMarks();
+        const merged: MarkAttrs = { ...base };
+        for (const [name, value] of Object.entries(pending)) {
+          if (value === false) delete merged[name];
+          else merged[name] = value;
+        }
+        return merged;
+      },
+
+      insertText(text, attrs) {
+        const sel = currentSelection() ?? { from: yText.length, to: yText.length };
+        transactProgrammatic(yText, () => {
+          if (sel.from !== sel.to) {
+            yText.delete(sel.from, sel.to - sel.from);
+          }
+          if (text.length === 0) return;
+          const inherited = inheritedMarksAt(yText, sel.from);
+          const combined: MarkAttrs = {
+            ...inherited,
+            ...pendingMarks(),
+            ...(attrs ?? {}),
+          };
+          const { sanitised } = validateMarks(combined, schema);
+          yText.insert(sel.from, text, Object.keys(sanitised).length > 0 ? sanitised : undefined);
+        });
+      },
+
+      deleteRange(from, to) {
+        if (to <= from) return;
+        transactProgrammatic(yText, () => {
+          yText.delete(from, to - from);
+        });
+      },
+
+      focus() {
+        getEditor(yText)?.focus();
+      },
+
+      blur() {
+        getEditor(yText)?.blur();
+      },
+
+      isFocused() {
+        return getEditor(yText)?.isFocused() ?? false;
+      },
+    };
+  }, [yText, schema]);
+}