@apollohg/react-native-rich-text-editor 2.0.0

package/src/NativeEditorDocumentHandle.ts

@@ -0,0 +1,168 @@
+import { type ResolvedDocumentSchema } from './schemas';
+import { NativeEditorErrorBase } from './NativeEditorBoundaryError';
+import { NativeEditorDocumentBridge } from './NativeEditorDocumentBridge';
+import {
+    type NativeCollaborationTransportConfig,
+    type NativeCollaborationTransportEvent,
+} from './NativeEditorCollaborationTransport';
+import {
+    type NativeEditorLocalAwarenessIntent,
+    type NativeEditorCreateConfig,
+} from './NativeEditorTypes';
+import {
+    invalidV2RequestError,
+    unwrapNativeEditorV2Result,
+} from './NativeEditorResultNormalization';
+import { buildV2CreateRequest } from './NativeEditorCreateConfig';
+import { invokeNativeEditorV2 } from './NativeEditorNativeModule';
+import { normalizeNativeEditorV2CreateValue } from './NativeEditorRenderNormalization';
+
+export const NATIVE_EDITOR_DOCUMENT_HANDLE_BRAND: unique symbol = Symbol(
+    'NativeEditorDocumentHandle.brand'
+);
+
+export const NATIVE_EDITOR_DOCUMENT_HANDLE_TOKEN = Object.freeze({});
+
+export const AUTHENTIC_NATIVE_EDITOR_DOCUMENT_HANDLES = new WeakSet<object>();
+
+export const NATIVE_EDITOR_DOCUMENT_HANDLE_DESCRIPTORS = new WeakMap<
+    object,
+    ResolvedDocumentSchema
+>();
+
+/**
+ * One native document session, shared by everything that touches the
+ * document: the editor view, the headless `useNativeEditorDocument` binding,
+ * and the collaboration controller. Obtain one from
+ * {@link createNativeEditorDocumentHandle} — it cannot be constructed
+ * directly — and `destroy()` it when its owner unmounts.
+ */
+export interface NativeEditorDocumentHandle {
+    readonly [NATIVE_EDITOR_DOCUMENT_HANDLE_BRAND]: true;
+    /** Decimal-string session id, shared with the native view. */
+    readonly editorId: string;
+    /** Typed imperative access to the engine. The React APIs use this for you. */
+    readonly bridge: NativeEditorDocumentBridge;
+    readonly isDestroyed: boolean;
+    /** Release the native session. Every later call fails as non-retryable. */
+    destroy(): void;
+    /** Observe engine failures raised outside a caller's own call. Returns an unsubscribe function. */
+    addErrorListener(listener: (error: NativeEditorErrorBase) => void): () => void;
+    /** Point the native transport at a server, or pass null to detach. */
+    configureCollaborationTransport(config: NativeCollaborationTransportConfig | null): void;
+    /** Publish local presence, or pass null to withdraw it. */
+    setLocalAwareness(intent: NativeEditorLocalAwarenessIntent | null): void;
+    /** Observe transport state, errors, and protocol-adapter requests. Returns an unsubscribe function. */
+    addCollaborationTransportListener(
+        listener: (event: NativeCollaborationTransportEvent) => void
+    ): () => void;
+}
+
+export class NativeEditorDocumentHandleImpl implements NativeEditorDocumentHandle {
+    readonly [NATIVE_EDITOR_DOCUMENT_HANDLE_BRAND] = true as const;
+
+    constructor(
+        token: typeof NATIVE_EDITOR_DOCUMENT_HANDLE_TOKEN,
+        public readonly editorId: string,
+        public readonly bridge: NativeEditorDocumentBridge,
+        documentDescriptor: ResolvedDocumentSchema
+    ) {
+        if (token !== NATIVE_EDITOR_DOCUMENT_HANDLE_TOKEN) {
+            throw invalidV2RequestError(
+                'NativeEditorBridge: NativeEditorDocumentHandle cannot be constructed directly'
+            );
+        }
+        AUTHENTIC_NATIVE_EDITOR_DOCUMENT_HANDLES.add(this);
+        NATIVE_EDITOR_DOCUMENT_HANDLE_DESCRIPTORS.set(this, documentDescriptor);
+    }
+
+    get isDestroyed(): boolean {
+        return this.bridge.isDestroyed;
+    }
+
+    destroy(): void {
+        this.bridge.destroy();
+    }
+
+    addErrorListener(listener: (error: NativeEditorErrorBase) => void): () => void {
+        return this.bridge.addErrorListener(listener);
+    }
+
+    configureCollaborationTransport(config: NativeCollaborationTransportConfig | null): void {
+        this.bridge.configureCollaborationTransport(config);
+    }
+
+    setLocalAwareness(intent: NativeEditorLocalAwarenessIntent | null): void {
+        this.bridge.setLocalAwareness(intent);
+    }
+
+    addCollaborationTransportListener(
+        listener: (event: NativeCollaborationTransportEvent) => void
+    ): () => void {
+        return this.bridge.addCollaborationTransportListener(listener);
+    }
+}
+
+/** @internal Handle-owned schema metadata for source-module view bindings. */
+export function _getNativeEditorDocumentHandleDescriptor(
+    handle: NativeEditorDocumentHandle
+): ResolvedDocumentSchema {
+    _assertNativeEditorDocumentHandle(handle);
+    const documentDescriptor = NATIVE_EDITOR_DOCUMENT_HANDLE_DESCRIPTORS.get(handle);
+    if (documentDescriptor === undefined) {
+        throw invalidV2RequestError(
+            'NativeEditorBridge: authentic NativeEditorDocumentHandle has no document descriptor'
+        );
+    }
+    return documentDescriptor;
+}
+
+/** @internal Source-module boundary assertion; intentionally absent from the package index. */
+export function _assertNativeEditorDocumentHandle(
+    value: unknown
+): asserts value is NativeEditorDocumentHandle {
+    if (
+        (typeof value !== 'object' && typeof value !== 'function') ||
+        value === null ||
+        !AUTHENTIC_NATIVE_EDITOR_DOCUMENT_HANDLES.has(value)
+    ) {
+        throw invalidV2RequestError(
+            'NativeEditorBridge: expected an authentic NativeEditorDocumentHandle'
+        );
+    }
+}
+
+/**
+ * Create the native document session every other API binds to. Create it once
+ * per document — `useMemo`, not on each render — and destroy it when its
+ * owner unmounts.
+ *
+ * @throws NativeEditorErrorBase when the config is rejected: a malformed
+ * schema, an out-of-range limit, or content the engine cannot parse.
+ *
+ * @example
+ * ```ts
+ * const documentHandle = useMemo(
+ *     () => createNativeEditorDocumentHandle({
+ *         initialization: { type: 'localHtml', html: '<p>Hello world</p>' },
+ *     }),
+ *     []
+ * );
+ * useEffect(() => () => documentHandle.destroy(), [documentHandle]);
+ * ```
+ */
+export function createNativeEditorDocumentHandle(
+    config: NativeEditorCreateConfig
+): NativeEditorDocumentHandle {
+    const { configJson, snapshotState, documentDescriptor } = buildV2CreateRequest(config);
+    const value = unwrapNativeEditorV2Result(
+        invokeNativeEditorV2('editorV2Create', configJson, snapshotState),
+        normalizeNativeEditorV2CreateValue
+    );
+    return new NativeEditorDocumentHandleImpl(
+        NATIVE_EDITOR_DOCUMENT_HANDLE_TOKEN,
+        value.editorId,
+        new NativeEditorDocumentBridge(value.editorId),
+        documentDescriptor
+    );
+}

package/src/NativeEditorLocalAwareness.ts

@@ -0,0 +1,168 @@
+import { NativeEditorEngineBoundaryError } from './NativeEditorBoundaryError';
+import { invalidV2RequestError, nativeEditorV2U32 } from './NativeEditorResultNormalization';
+import {
+    type NativeEditorLocalAwarenessSelection,
+    NativeEditorLocalAwarenessSelectionValue,
+} from './NativeEditorTypes';
+import { normalizeV2JsonValue, serializeV2CreateEnvelope } from './NativeEditorCreateJson';
+
+export const LOCAL_AWARENESS_INTENT_KEYS = new Set(['state', 'focused', 'selection']);
+
+export const LOCAL_AWARENESS_SELECTION_VALUES = new WeakMap<
+    object,
+    Readonly<{ anchor: number; head: number }>
+>();
+
+export function invalidLocalAwarenessIntent(message = 'invalid local awareness intent'): never {
+    throw invalidV2RequestError(`NativeEditorBridge: ${message}`);
+}
+
+/**
+ * Create the only caller-owned local-awareness selection accepted at the
+ * JavaScript-to-native boundary. The private WeakMap makes provenance an API
+ * capability instead of a structural object-shape check.
+ */
+export function createNativeEditorLocalAwarenessSelection(
+    anchor: number,
+    head: number
+): NativeEditorLocalAwarenessSelection {
+    const acceptedAnchor = nativeEditorV2U32(anchor);
+    const acceptedHead = nativeEditorV2U32(head);
+    if (acceptedAnchor == null || acceptedHead == null) invalidLocalAwarenessIntent();
+
+    const selection: NativeEditorLocalAwarenessSelection =
+        new NativeEditorLocalAwarenessSelectionValue(acceptedAnchor, acceptedHead);
+    Object.freeze(selection);
+    LOCAL_AWARENESS_SELECTION_VALUES.set(selection, selection);
+    return selection;
+}
+
+export function isLocalAwarenessRecord(value: unknown): value is Record<string, unknown> {
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+
+export function localAwarenessOwnDataValue(record: Record<string, unknown>, key: string): unknown {
+    const descriptor = Object.getOwnPropertyDescriptor(record, key);
+    if (descriptor === undefined || !('value' in descriptor) || descriptor.enumerable !== true) {
+        invalidLocalAwarenessIntent();
+    }
+    return descriptor.value;
+}
+
+export function validateLocalAwarenessSelection(selection: unknown): {
+    anchor: number;
+    head: number;
+} {
+    if (selection == null || typeof selection !== 'object') invalidLocalAwarenessIntent();
+
+    // Do not inspect caller-held values before provenance succeeds: a Proxy
+    // can imitate every structural and own-data check, but it cannot inherit
+    // this module's WeakMap identity.
+    const factoryValue = LOCAL_AWARENESS_SELECTION_VALUES.get(selection);
+    if (factoryValue === undefined) invalidLocalAwarenessIntent();
+
+    const anchor = nativeEditorV2U32(factoryValue.anchor);
+    const head = nativeEditorV2U32(factoryValue.head);
+    if (anchor == null || head == null) {
+        invalidLocalAwarenessIntent();
+    }
+    return { anchor, head };
+}
+
+/** Reject caller-owned sticky cursor data before a native call can occur. */
+export function rejectReservedAwarenessCursor(value: unknown): void {
+    const pending: unknown[] = [value];
+    const seen = new WeakSet<object>();
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current == null || typeof current !== 'object') continue;
+        if (seen.has(current)) continue;
+        seen.add(current);
+        for (const key of Reflect.ownKeys(current)) {
+            if (key === 'cursor') invalidLocalAwarenessIntent('reserved cursor key is not allowed');
+            const descriptor = Object.getOwnPropertyDescriptor(current, key);
+            if (descriptor == null || !('value' in descriptor)) invalidLocalAwarenessIntent();
+            pending.push(descriptor.value);
+        }
+    }
+}
+
+export function normalizeLocalAwarenessState(value: unknown): Record<string, unknown> {
+    try {
+        const normalized = normalizeV2JsonValue(value, 'local awareness state', {
+            seen: new WeakSet<object>(),
+            work: 0,
+        });
+        if (!isLocalAwarenessRecord(normalized) || Object.getPrototypeOf(normalized) !== null) {
+            invalidLocalAwarenessIntent();
+        }
+        rejectReservedAwarenessCursor(normalized);
+        return normalized;
+    } catch (error) {
+        if (error instanceof NativeEditorEngineBoundaryError) throw error;
+        invalidLocalAwarenessIntent();
+    }
+}
+
+export interface NativeEditorLocalAwarenessWireIntent {
+    state: Record<string, unknown>;
+    focused: boolean;
+    /** Absent retains the Rust-owned cursor; `null` clears it. */
+    selection?: { type: 'text'; anchor: number; head: number } | null;
+}
+
+export function validateLocalAwarenessIntent(
+    intent: unknown
+): NativeEditorLocalAwarenessWireIntent {
+    try {
+        if (
+            !isLocalAwarenessRecord(intent) ||
+            Reflect.ownKeys(intent).some(
+                (key) => typeof key !== 'string' || !LOCAL_AWARENESS_INTENT_KEYS.has(key)
+            ) ||
+            !Object.prototype.hasOwnProperty.call(intent, 'state') ||
+            !Object.prototype.hasOwnProperty.call(intent, 'focused')
+        ) {
+            invalidLocalAwarenessIntent();
+        }
+        const state = normalizeLocalAwarenessState(localAwarenessOwnDataValue(intent, 'state'));
+        const focused = localAwarenessOwnDataValue(intent, 'focused');
+        if (typeof focused !== 'boolean') invalidLocalAwarenessIntent();
+
+        if (!Object.prototype.hasOwnProperty.call(intent, 'selection')) {
+            // Absent: retain whatever cursor Rust already holds.
+            return { state, focused };
+        }
+        const rawSelection = localAwarenessOwnDataValue(intent, 'selection');
+        if (rawSelection === null) return { state, focused, selection: null };
+        const selection = validateLocalAwarenessSelection(rawSelection);
+        return { state, focused, selection: { type: 'text', ...selection } };
+    } catch (error) {
+        if (error instanceof NativeEditorEngineBoundaryError) throw error;
+        invalidLocalAwarenessIntent();
+    }
+}
+
+export function serializeLocalAwarenessIntent(
+    intent: NativeEditorLocalAwarenessWireIntent
+): string {
+    try {
+        const wire = Object.create(null) as Record<string, unknown>;
+        wire.state = intent.state;
+        wire.focused = intent.focused;
+        if (intent.selection === null) {
+            wire.selection = null;
+        } else if (intent.selection !== undefined) {
+            const selection = Object.create(null) as Record<string, unknown>;
+            selection.type = intent.selection.type;
+            selection.anchor = intent.selection.anchor;
+            selection.head = intent.selection.head;
+            wire.selection = selection;
+        }
+        return serializeV2CreateEnvelope(wire);
+    } catch {
+        invalidLocalAwarenessIntent();
+    }
+}

package/src/NativeEditorNativeModule.ts

@@ -0,0 +1,97 @@
+import { requireNativeModule } from 'expo-modules-core';
+import { type NativeEditorError } from './NativeEditorBoundaryError';
+
+export let _nativeModule: NativeEditorModule | null = null;
+
+export function getNativeModule(): NativeEditorModule {
+    if (!_nativeModule) {
+        _nativeModule = requireNativeModule<NativeEditorModule>('NativeEditor');
+    }
+    return _nativeModule;
+}
+
+/** @internal Reset the cached native module reference. For testing only. */
+export function _resetNativeModuleCache(): void {
+    _nativeModule = null;
+}
+
+// The only construction path. Consumes the frozen v2 result records
+// ({ value, error }, exactly one side set), normalizes them at the JS boundary
+// (decimal-string u64s, direct binaries, unsafe-integer rejection), and raises
+// typed per-domain errors with a non-retryable class for
+// ENGINE_INVARIANT_FAILED and destroyed lifecycles.
+
+export const ERR_V2_NATIVE_RESPONSE =
+    'NativeEditorBridge: invalid v2 result record from native module';
+
+export const ERR_V2_DESTROYED = 'NativeEditorBridge: v2 editor handle has been destroyed';
+
+export const V2_ENVELOPE_VERSION = 1;
+
+/**
+ * The v2 surface of the NativeEditor native module — the complete
+ * production ABI. Every call resolves the method lazily and fails clearly
+ * when the v2 surface is absent. Decimal-string identifiers keep full u64
+ * fidelity across the JavaScript boundary, and binaries travel as direct
+ * Uint8Array values (never JSON number arrays).
+ */
+export interface NativeEditorModule {
+    editorV2Create(configJson: string, snapshotState: Uint8Array | null): unknown;
+    editorV2Destroy(editorId: string): unknown;
+    editorV2GetState(editorId: string): unknown;
+    editorV2GetDocumentJson(editorId: string): unknown;
+    editorV2GetDocumentHtml(editorId: string): unknown;
+    editorV2GetContentSnapshot(editorId: string): unknown;
+    editorV2ReplaceDocument(editorId: string, requestJson: string): unknown;
+    editorV2ApplyInput(editorId: string, requestJson: string): unknown;
+    editorV2ApplyCommand(editorId: string, requestJson: string): unknown;
+    editorV2ApplyLocalApi(editorId: string, requestJson: string): unknown;
+    editorV2SetSelection(editorId: string, requestJson: string): unknown;
+    editorV2Undo(editorId: string, requestJson: string): unknown;
+    editorV2Redo(editorId: string, requestJson: string): unknown;
+    editorV2RenderUpdate(
+        editorId: string,
+        mirrorScalarAnchor: number | null,
+        mirrorScalarHead: number | null
+    ): unknown;
+    editorV2CollaborationConfigureTransport(
+        editorId: string,
+        configJsonOrNull: string | null
+    ): unknown;
+    editorV2CollaborationResolveProtocolAdapter(
+        editorId: string,
+        attemptId: string,
+        eventId: string,
+        responseJson: string
+    ): unknown;
+    editorV2CollaborationSetAwareness(editorId: string, awarenessJson: string): unknown;
+    editorV2SnapshotExport(editorId: string): unknown;
+    editorV2SnapshotRestore(
+        editorId: string,
+        metadataJson: string,
+        encodedState: Uint8Array
+    ): unknown;
+    addListener(
+        eventName: 'onCollaborationTransportEvent',
+        listener: (event: unknown) => void
+    ): { remove(): void };
+}
+
+export function invokeNativeEditorV2<K extends keyof NativeEditorModule>(
+    name: K,
+    ...args: Parameters<NativeEditorModule[K]>
+): unknown {
+    const nativeModule = getNativeModule() as unknown as Record<string, unknown>;
+    const method = nativeModule[name as string];
+    if (typeof method !== 'function') {
+        throw new Error(
+            `NativeEditorBridge: native module does not expose the v2 entry ${String(name)}`
+        );
+    }
+    return (method as (...fnArgs: unknown[]) => unknown).apply(nativeModule, args);
+}
+
+/** The discriminated envelope every v2 result record normalizes into. */
+export type NativeEditorResult<T> =
+    | { ok: true; value: T }
+    | { ok: false; error: NativeEditorError };