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

package/src/ImageLoadingPolicy.ts

@@ -0,0 +1,125 @@
+import { NativeEditorBoundaryError } from './NativeEditorBoundaryError';
+
+/**
+ * Bounds on the native image pipeline that fetches and decodes remote and
+ * data-URL images. Set it on `RichTextEditor.imageLoadingPolicy` or
+ * `RichTextViewer.imageLoadingPolicy`.
+ *
+ * Every field is optional; an omitted one uses
+ * {@link DEFAULT_EDITOR_IMAGE_LOADING_POLICY}. Each value must be a positive
+ * integer no greater than the matching
+ * {@link HARD_EDITOR_IMAGE_LOADING_POLICY} ceiling — anything else throws
+ * `NativeEditorBoundaryError` (`IMAGE_POLICY_INVALID`).
+ */
+export interface EditorImageLoadingPolicy {
+    /** Byte ceiling for one image source, applied to remote responses and decoded data-URL payloads alike. */
+    maxSourceBytes?: number;
+    /** Socket connect timeout for a remote image request, in milliseconds. */
+    connectTimeoutMs?: number;
+    /** Socket read timeout for a remote image request, in milliseconds. */
+    readTimeoutMs?: number;
+    /** Overall deadline for one image request, in milliseconds. */
+    requestTimeoutMs?: number;
+    /** Image requests allowed in flight at once. Further requests queue. */
+    maxConcurrentRequests?: number;
+    /** Queued requests allowed while the in-flight slots are full. Requests beyond this are dropped. */
+    maxPendingRequests?: number;
+    /** Ceiling on decoded image width and height, in pixels. Larger images are downsampled. */
+    maxDecodeDimensionPx?: number;
+    /** Decoded pixel bytes this editor or viewer may retain at once. */
+    maxDecodedBytes?: number;
+}
+
+/** {@link EditorImageLoadingPolicy} with every default filled in. */
+export interface ResolvedEditorImageLoadingPolicy {
+    maxSourceBytes: number;
+    connectTimeoutMs: number;
+    readTimeoutMs: number;
+    requestTimeoutMs: number;
+    maxConcurrentRequests: number;
+    maxPendingRequests: number;
+    maxDecodeDimensionPx: number;
+    maxDecodedBytes: number;
+}
+
+/** The value used for each {@link EditorImageLoadingPolicy} field left unset. */
+export const DEFAULT_EDITOR_IMAGE_LOADING_POLICY: Readonly<ResolvedEditorImageLoadingPolicy> = {
+    maxSourceBytes: 10 * 1024 * 1024,
+    connectTimeoutMs: 10_000,
+    readTimeoutMs: 20_000,
+    requestTimeoutMs: 60_000,
+    maxConcurrentRequests: 2,
+    maxPendingRequests: 64,
+    maxDecodeDimensionPx: 2_048,
+    maxDecodedBytes: 32 * 1024 * 1024,
+};
+
+/** The ceiling each {@link EditorImageLoadingPolicy} field may not exceed. */
+export const HARD_EDITOR_IMAGE_LOADING_POLICY: Readonly<ResolvedEditorImageLoadingPolicy> = {
+    maxSourceBytes: 64 * 1024 * 1024,
+    connectTimeoutMs: 600_000,
+    readTimeoutMs: 600_000,
+    requestTimeoutMs: 600_000,
+    maxConcurrentRequests: 16,
+    maxPendingRequests: 512,
+    maxDecodeDimensionPx: 8_192,
+    maxDecodedBytes: 256 * 1024 * 1024,
+};
+
+function resolveImagePolicyValue(
+    name: keyof ResolvedEditorImageLoadingPolicy,
+    value: number | undefined
+): number {
+    const resolved = value ?? DEFAULT_EDITOR_IMAGE_LOADING_POLICY[name];
+    if (
+        !Number.isSafeInteger(resolved) ||
+        resolved <= 0 ||
+        resolved > HARD_EDITOR_IMAGE_LOADING_POLICY[name]
+    ) {
+        throw new NativeEditorBoundaryError(
+            'IMAGE_POLICY_INVALID',
+            `${name} must be a positive integer no greater than ${HARD_EDITOR_IMAGE_LOADING_POLICY[name]}`,
+            HARD_EDITOR_IMAGE_LOADING_POLICY[name],
+            resolved
+        );
+    }
+    return resolved;
+}
+
+/**
+ * Fill in every unset {@link EditorImageLoadingPolicy} field from
+ * {@link DEFAULT_EDITOR_IMAGE_LOADING_POLICY}, validating each value against
+ * {@link HARD_EDITOR_IMAGE_LOADING_POLICY}.
+ *
+ * @throws NativeEditorBoundaryError `IMAGE_POLICY_INVALID` when a value is
+ * not a positive integer within its ceiling.
+ */
+export function resolveEditorImageLoadingPolicy(
+    policy?: EditorImageLoadingPolicy
+): ResolvedEditorImageLoadingPolicy {
+    return {
+        maxSourceBytes: resolveImagePolicyValue('maxSourceBytes', policy?.maxSourceBytes),
+        connectTimeoutMs: resolveImagePolicyValue('connectTimeoutMs', policy?.connectTimeoutMs),
+        readTimeoutMs: resolveImagePolicyValue('readTimeoutMs', policy?.readTimeoutMs),
+        requestTimeoutMs: resolveImagePolicyValue('requestTimeoutMs', policy?.requestTimeoutMs),
+        maxConcurrentRequests: resolveImagePolicyValue(
+            'maxConcurrentRequests',
+            policy?.maxConcurrentRequests
+        ),
+        maxPendingRequests: resolveImagePolicyValue(
+            'maxPendingRequests',
+            policy?.maxPendingRequests
+        ),
+        maxDecodeDimensionPx: resolveImagePolicyValue(
+            'maxDecodeDimensionPx',
+            policy?.maxDecodeDimensionPx
+        ),
+        maxDecodedBytes: resolveImagePolicyValue('maxDecodedBytes', policy?.maxDecodedBytes),
+    };
+}
+
+export function serializeEditorImageLoadingPolicy(
+    policy?: EditorImageLoadingPolicy
+): string | undefined {
+    return policy == null ? undefined : JSON.stringify(resolveEditorImageLoadingPolicy(policy));
+}

package/src/NativeEditorBoundaryError.ts

@@ -0,0 +1,345 @@
+import { normalizeNativeEditorV2U64 } from './NativeEditorV2Decimal';
+
+/** The boundary failure codes this package knows about at build time. */
+export const NATIVE_EDITOR_BOUNDARY_ERROR_CODES = [
+    'INVALID_RESOURCE_LIMIT',
+    'CONFIG_INVALID',
+    'INPUT_LIMIT_EXCEEDED',
+    'CONFIG_PARSE_FAILED',
+    'DOCUMENT_PARSE_FAILED',
+    'DOCUMENT_INVALID',
+    'DOCUMENT_LIMIT_EXCEEDED',
+    'POSITION_LIMIT_EXCEEDED',
+    'SCHEMA_INVALID',
+    'REQUIRED_ATTRIBUTE_MISSING',
+    'UNKNOWN_MARK',
+    'MAX_LENGTH_EXCEEDED',
+    'MUTATION_REJECTED',
+    'COLLABORATION_DECODE_FAILED',
+    'COLLABORATION_APPLY_FAILED',
+    'SESSION_NOT_FOUND',
+    'IMAGE_POLICY_INVALID',
+    'IMAGE_REQUEST_TIMEOUT',
+] as const;
+
+export type KnownNativeEditorBoundaryErrorCode =
+    (typeof NATIVE_EDITOR_BOUNDARY_ERROR_CODES)[number];
+
+/** Known codes remain suggested while future native codes can cross the boundary losslessly. */
+export type NativeEditorBoundaryErrorCode = KnownNativeEditorBoundaryErrorCode | (string & {});
+
+/** The subsystems a typed error can come from. Each maps to its own error class. */
+export const NATIVE_EDITOR_ERROR_DOMAINS = [
+    'boundary',
+    'document',
+    'operation',
+    'lifecycle',
+    'snapshot',
+    'transport',
+] as const;
+
+/**
+ * Which subsystem raised a failure:
+ *
+ * - `boundary` — the value never reached the engine (bad config, oversized input).
+ * - `document` — the document or schema was rejected.
+ * - `operation` — a mutation could not be applied (stale revision, invalid position).
+ * - `lifecycle` — the session was destroyed or is being destroyed.
+ * - `snapshot` — a room snapshot could not be exported or restored.
+ * - `transport` — collaboration transport failure.
+ */
+export type NativeEditorErrorDomain = (typeof NATIVE_EDITOR_ERROR_DOMAINS)[number];
+
+/** Codes carried by `operation`-domain failures. */
+export const NATIVE_EDITOR_OPERATION_ERROR_CODES = [
+    'ENGINE_NOT_READY',
+    'REVISION_MISMATCH',
+    'POSITION_INVALID',
+    'TRANSACTION_INVALID',
+    'OPERATION_INVALID',
+    'OPERATION_LIMIT_EXCEEDED',
+    'OPERATION_RESOURCE_EXHAUSTED',
+    'DOCUMENT_INVALID',
+    'DOCUMENT_LIMIT_EXCEEDED',
+    'ENGINE_INVARIANT_FAILED',
+] as const;
+
+/**
+ * A failure record from the native boundary, normalized for JavaScript. It is
+ * carried on every {@link NativeEditorErrorBase}; the numeric fields stay
+ * decimal strings because they span the full Rust `u64` range.
+ */
+export interface NativeEditorError {
+    domain: NativeEditorErrorDomain;
+    code: NativeEditorBoundaryErrorCode;
+    message: string;
+    /** Identity of the request that failed. */
+    requestId: string | null;
+    /** Index of the failing operation within a multi-operation transaction. */
+    operationIndex: string | null;
+    /** The bound that was exceeded, for limit failures. */
+    limit: string | null;
+    /** The value that exceeded it. */
+    actual: string | null;
+    /** Code-specific context, e.g. `expectedRevision`/`actualRevision` for `REVISION_MISMATCH`. */
+    details: Record<string, unknown> | null;
+}
+
+/**
+ * A value rejected before it reached the engine — an out-of-range resource
+ * limit, an invalid image policy, an oversized input. Thrown synchronously by
+ * the validating helpers in this package.
+ */
+export class NativeEditorBoundaryError extends Error {
+    constructor(
+        readonly code: NativeEditorBoundaryErrorCode,
+        message: string,
+        readonly limit?: number,
+        readonly actual?: number,
+        readonly details?: Record<string, unknown>
+    ) {
+        super(message);
+        this.name = 'NativeEditorBoundaryError';
+    }
+}
+
+/**
+ * Turn a raw native error envelope into a {@link NativeEditorBoundaryError},
+ * or null when the value is not one.
+ */
+export function parseNativeBoundaryError(value: unknown): NativeEditorBoundaryError | null {
+    const envelope = value as { error?: Record<string, unknown> };
+    const nativeError = envelope?.error;
+    const code = nativeError?.code;
+    if (typeof code !== 'string' || typeof nativeError?.message !== 'string') {
+        return null;
+    }
+    return new NativeEditorBoundaryError(
+        code,
+        nativeError.message,
+        typeof nativeError.limit === 'number' ? nativeError.limit : undefined,
+        typeof nativeError.actual === 'number' ? nativeError.actual : undefined,
+        nativeError.details != null && typeof nativeError.details === 'object'
+            ? (nativeError.details as Record<string, unknown>)
+            : undefined
+    );
+}
+
+function nullableCanonicalDecimal(value: unknown): string | null | undefined {
+    if (value == null) return null;
+    return normalizeNativeEditorV2U64(value) ?? undefined;
+}
+
+function parseDetails(
+    nativeError: Record<string, unknown>
+): Record<string, unknown> | null | undefined {
+    if (nativeError.details != null) {
+        if (typeof nativeError.details !== 'object' || Array.isArray(nativeError.details)) {
+            return undefined;
+        }
+        return nativeError.details as Record<string, unknown>;
+    }
+    if (nativeError.detailsJson == null) return null;
+    if (typeof nativeError.detailsJson !== 'string') return undefined;
+    try {
+        const details: unknown = JSON.parse(nativeError.detailsJson);
+        return details != null && typeof details === 'object' && !Array.isArray(details)
+            ? (details as Record<string, unknown>)
+            : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+function isCanonicalDecimalDetail(value: unknown): value is string {
+    return normalizeNativeEditorV2U64(value) != null;
+}
+
+/**
+ * Error details are otherwise forward-compatible, but known v2 structures
+ * carry u64 values and must not let JSON.parse silently admit rounded numbers.
+ */
+function hasValidKnownDetails(code: string, details: Record<string, unknown> | null): boolean {
+    switch (code) {
+        case 'REVISION_MISMATCH':
+            return (
+                details != null &&
+                isCanonicalDecimalDetail(details.expectedRevision) &&
+                isCanonicalDecimalDetail(details.actualRevision)
+            );
+        case 'TRANSPORT_STALE_GENERATION':
+            return (
+                details != null &&
+                isCanonicalDecimalDetail(details.presentedGeneration) &&
+                (details.liveGeneration === null ||
+                    isCanonicalDecimalDetail(details.liveGeneration))
+            );
+        default:
+            return true;
+    }
+}
+
+/** Normalize a raw FFI v2 error record without changing the legacy error parser contract. */
+export function normalizeNativeEditorV2Error(value: unknown): NativeEditorError | null {
+    const envelope = value as { error?: unknown };
+    const nativeError = envelope?.error as Record<string, unknown> | undefined;
+    if (nativeError == null || typeof nativeError !== 'object') return null;
+
+    const { domain, code, message } = nativeError;
+    if (
+        typeof domain !== 'string' ||
+        !NATIVE_EDITOR_ERROR_DOMAINS.includes(domain as NativeEditorErrorDomain) ||
+        typeof code !== 'string' ||
+        typeof message !== 'string'
+    ) {
+        return null;
+    }
+
+    const requestId = nullableCanonicalDecimal(nativeError.requestId);
+    const operationIndex = nullableCanonicalDecimal(nativeError.operationIndex);
+    const limit = nullableCanonicalDecimal(nativeError.limit);
+    const actual = nullableCanonicalDecimal(nativeError.actual);
+    const details = parseDetails(nativeError);
+    if (
+        requestId === undefined ||
+        operationIndex === undefined ||
+        limit === undefined ||
+        actual === undefined ||
+        details === undefined ||
+        !hasValidKnownDetails(code, details)
+    ) {
+        return null;
+    }
+
+    return {
+        domain: domain as NativeEditorErrorDomain,
+        code,
+        message,
+        requestId,
+        operationIndex,
+        limit,
+        actual,
+        details,
+    };
+}
+
+// FFI v2 typed imperative error classes (additive; the legacy parsing path
+// above is unchanged). Recoverable engine errors throw the structured
+// per-domain class; ENGINE_INVARIANT_FAILED and lifecycle-destroyed states
+// throw the distinct non-retryable class.
+
+/** Codes that mark a failure as permanently non-retryable for this handle. */
+export const NATIVE_EDITOR_NON_RETRYABLE_CODES = [
+    'ENGINE_INVARIANT_FAILED',
+    'ENGINE_DESTROYING',
+    'ENGINE_DESTROYED',
+] as const;
+
+export function isNativeEditorV2NonRetryableCode(code: string): boolean {
+    return (NATIVE_EDITOR_NON_RETRYABLE_CODES as readonly string[]).includes(code);
+}
+
+/** Base class for every typed error raised from a normalized FFI v2 error record. */
+export class NativeEditorErrorBase extends Error {
+    readonly domain: NativeEditorErrorDomain;
+    readonly code: NativeEditorBoundaryErrorCode;
+    readonly requestId: string | null;
+    readonly operationIndex: string | null;
+    readonly limit: string | null;
+    readonly actual: string | null;
+    readonly details: Record<string, unknown> | null;
+
+    constructor(
+        readonly error: NativeEditorError,
+        name: string
+    ) {
+        super(error.message);
+        this.name = name;
+        this.domain = error.domain;
+        this.code = error.code;
+        this.requestId = error.requestId;
+        this.operationIndex = error.operationIndex;
+        this.limit = error.limit;
+        this.actual = error.actual;
+        this.details = error.details;
+    }
+}
+
+/** A value the engine refused to admit. */
+export class NativeEditorEngineBoundaryError extends NativeEditorErrorBase {
+    constructor(error: NativeEditorError) {
+        super(error, 'NativeEditorEngineBoundaryError');
+    }
+}
+
+/** The document or schema was rejected. */
+export class NativeEditorDocumentError extends NativeEditorErrorBase {
+    constructor(error: NativeEditorError) {
+        super(error, 'NativeEditorDocumentError');
+    }
+}
+
+/**
+ * A mutation could not be applied. `REVISION_MISMATCH` is the routine one:
+ * the document moved on, so re-read it and retry against the fresh revision.
+ */
+export class NativeEditorOperationError extends NativeEditorErrorBase {
+    constructor(error: NativeEditorError) {
+        super(error, 'NativeEditorOperationError');
+    }
+}
+
+/** The session is not in a state that permits this call. */
+export class NativeEditorLifecycleError extends NativeEditorErrorBase {
+    constructor(error: NativeEditorError) {
+        super(error, 'NativeEditorLifecycleError');
+    }
+}
+
+/** A room snapshot could not be exported or restored. */
+export class NativeEditorSnapshotError extends NativeEditorErrorBase {
+    constructor(error: NativeEditorError) {
+        super(error, 'NativeEditorSnapshotError');
+    }
+}
+
+/** The collaboration transport failed. */
+export class NativeEditorTransportError extends NativeEditorErrorBase {
+    constructor(error: NativeEditorError) {
+        super(error, 'NativeEditorTransportError');
+    }
+}
+
+/**
+ * Distinct class for failures that can never succeed on retry for this
+ * handle: ENGINE_INVARIANT_FAILED and the lifecycle-destroyed states
+ * (ENGINE_DESTROYING / ENGINE_DESTROYED).
+ */
+export class NativeEditorNonRetryableError extends NativeEditorErrorBase {
+    constructor(error: NativeEditorError) {
+        super(error, 'NativeEditorNonRetryableError');
+    }
+}
+
+const NATIVE_EDITOR_V2_DOMAIN_ERROR_CLASSES: Record<
+    NativeEditorErrorDomain,
+    new (error: NativeEditorError) => NativeEditorErrorBase
+> = {
+    boundary: NativeEditorEngineBoundaryError,
+    document: NativeEditorDocumentError,
+    operation: NativeEditorOperationError,
+    lifecycle: NativeEditorLifecycleError,
+    snapshot: NativeEditorSnapshotError,
+    transport: NativeEditorTransportError,
+};
+
+/** Map a normalized FFI v2 error record to its typed imperative exception. */
+export function nativeEditorV2ErrorToException(
+    error: NativeEditorError
+): NativeEditorErrorBase {
+    if (isNativeEditorV2NonRetryableCode(error.code)) {
+        return new NativeEditorNonRetryableError(error);
+    }
+    const ErrorClass = NATIVE_EDITOR_V2_DOMAIN_ERROR_CLASSES[error.domain];
+    return new ErrorClass(error);
+}

package/src/NativeEditorBridge.ts

@@ -0,0 +1,93 @@
+export {
+    type Selection,
+    type NativeEditorLocalAwarenessSelection,
+    type NativeEditorLocalAwarenessIntent,
+    type ListContext,
+    type RenderMarkWithAttrs,
+    type RenderMark,
+    type RenderElement,
+    type RenderBlocksPatch,
+    type ActiveState,
+    type HistoryState,
+    type ReadonlyActiveState,
+    type NativeEditorAtomicRenderSnapshot,
+    type EditorUpdate,
+    type ContentSnapshot,
+    type DocumentJSON,
+    type CollaborationPeer,
+    type CommandBlockedReason,
+    type CommandBlockedInfo,
+    type NativeEditorHistoryMode,
+    type NativeEditorSnapshotMetadata,
+    type NativeEditorRoomSnapshot,
+    type NativeEditorInitialization,
+    type NativeEditorCreateConfig,
+    type NativeEditorInputRequest,
+    type NativeEditorCommandRequest,
+    type NativeEditorLocalApiRequest,
+    type NativeEditorOffsetKind,
+    type NativeEditorPositionAffinity,
+    type NativeEditorPositionEnvelope,
+    type NativeEditorSelectionEnvelope,
+    type NativeEditorSelectionRequest,
+    type NativeEditorReplaceDocumentRequest,
+} from './NativeEditorTypes';
+export {
+    _resetNativeModuleCache,
+    type NativeEditorModule,
+    type NativeEditorResult,
+} from './NativeEditorNativeModule';
+export {
+    normalizeNativeEditorV2Result,
+    parseNativeEditorV2JsonValue,
+    normalizeNativeEditorV2Bytes,
+    normalizeNativeEditorV2Unit,
+    normalizeNativeEditorV2DecimalId,
+    requireNativeEditorV2U32,
+    type NativeEditorDocumentState,
+    type NativeEditorTransportState,
+    type NativeEditorRenderState,
+    type NativeEditorDocumentOrigin,
+    type NativeEditorState,
+    normalizeNativeEditorV2StateValue,
+    type NativeEditorMutationOutcome,
+    normalizeNativeEditorV2MutationOutcomeValue,
+    type NativeEditorCommitInfo,
+    normalizeNativeEditorV2CommitValue,
+    normalizeNativeEditorV2ChangedValue,
+    normalizeNativeEditorV2HtmlValue,
+    normalizeNativeEditorV2PeersValue,
+    unwrapNativeEditorV2Result,
+} from './NativeEditorResultNormalization';
+export { validEditorMentionTheme } from './EditorMentionThemeValidation';
+export {
+    normalizeNativeEditorV2RenderUpdateValue,
+    normalizeNativeEditorV2DocumentJsonValue,
+    normalizeNativeEditorV2ContentSnapshotValue,
+    type NativeEditorSnapshotExport,
+    normalizeNativeEditorV2SnapshotExportValue,
+    normalizeNativeEditorV2CreateValue,
+} from './NativeEditorRenderNormalization';
+export {
+    type NativeEditorPeerInfo,
+    type NativeCollaborationProtocolFrame,
+    type NativeCollaborationProtocolAdapterAction,
+    type NativeCollaborationProtocolAdapterResult,
+    type NativeCollaborationProtocolAdapterContext,
+    type NativeCollaborationProtocolAdapter,
+    type NativeCollaborationTransportConfig,
+    type NativeCollaborationTransportDiagnostics,
+    type NativeCollaborationTransportStateEvent,
+    type NativeCollaborationTransportErrorEvent,
+    type NativeCollaborationProtocolAdapterEvent,
+    type NativeCollaborationTransportEvent,
+    normalizeNativeCollaborationTransportEvent,
+} from './NativeEditorCollaborationTransport';
+export { createNativeEditorLocalAwarenessSelection } from './NativeEditorLocalAwareness';
+export { NativeEditorDocumentBridge } from './NativeEditorDocumentBridge';
+export {
+    type NativeEditorDocumentHandle,
+    _getNativeEditorDocumentHandleDescriptor,
+    _assertNativeEditorDocumentHandle,
+    createNativeEditorDocumentHandle,
+} from './NativeEditorDocumentHandle';