@apollohg/react-native-prose-editor 0.5.16 → 0.5.17

package/dist/NativeRichTextEditor.js

@@ -61,6 +61,9 @@ function mapToolbarItemsForNative(items, activeState, editable, onRequestLink, o
 function isImageDataUrl(value) {
     return /^data:image\//i.test(value.trim());
 }
+function isRetryableNativeCommandBlock(reason) {
+    return reason === 'composition' || (react_native_1.Platform.OS === 'android' && reason === 'pendingUpdate');
+}
 function isPromiseLike(value) {
     return (value != null &&
         typeof value === 'object' &&
@@ -398,15 +401,34 @@ function didContentChange(previousDocumentVersion, update) {
         typeof update.documentVersion !== 'number' ||
         update.documentVersion !== previousDocumentVersion);
 }
+function documentVersionFromUpdateJson(json) {
+    try {
+        const parsed = JSON.parse(json);
+        return typeof parsed.documentVersion === 'number' ? parsed.documentVersion : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isCurrentNativeEditorEvent(event, bridge) {
+    if (react_native_1.Platform.OS === 'android') {
+        return typeof event.editorId === 'number' && bridge?.editorId === event.editorId;
+    }
+    if (typeof event.editorId !== 'number')
+        return true;
+    return event.editorId === 0 || bridge?.editorId === event.editorId;
+}
 function computeRenderedTextLength(elements) {
     let len = 0;
     let blockCount = 0;
     for (const el of elements) {
         if (el.type === 'blockStart' && el.listContext) {
-            len += el.listContext.ordered ? `${el.listContext.index}. `.length : '• '.length;
+            len += el.listContext.ordered
+                ? unicodeScalarCount(`${el.listContext.index}. `)
+                : unicodeScalarCount('• ');
         }
         else if (el.type === 'textRun' && el.text) {
-            len += el.text.length;
+            len += unicodeScalarCount(el.text);
         }
         else if (el.type === 'voidInline' ||
             el.type === 'voidBlock' ||
@@ -414,7 +436,7 @@ function computeRenderedTextLength(elements) {
             el.type === 'opaqueBlockAtom') {
             if (el.type === 'opaqueInlineAtom' || el.type === 'opaqueBlockAtom') {
                 const visibleText = el.nodeType === 'mention' ? (el.label ?? '?') : `[${el.label ?? '?'}]`;
-                len += visibleText.length;
+                len += unicodeScalarCount(visibleText);
             }
             else {
                 // U+FFFC placeholder / hard break
@@ -508,6 +530,19 @@ function useSerializedValue(value, serialize, revision) {
     };
     return serialized;
 }
+function doesLiveMentionQueryConflictWithNativeSelectRequest(request, currentQuery, requestDocumentVersion, currentDocumentVersion) {
+    if (currentQuery == null)
+        return false;
+    const currentQueryDocumentVersion = typeof currentQuery.documentVersion === 'number' ? currentQuery.documentVersion : null;
+    const isSameDocument = currentQueryDocumentVersion != null
+        ? currentQueryDocumentVersion === requestDocumentVersion
+        : requestDocumentVersion == null || requestDocumentVersion === currentDocumentVersion;
+    if (!isSameDocument)
+        return false;
+    return (currentQuery.trigger !== request.trigger ||
+        currentQuery.range.anchor !== request.range.anchor ||
+        currentQuery.range.head !== request.range.head);
+}
 exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEditor({ initialContent, initialJSON, value, valueJSON, valueJSONRevision, schema, placeholder, editable = true, maxLength, autoFocus = false, autoCapitalize, autoCorrect, keyboardType, heightBehavior = 'autoGrow', showToolbar = true, toolbarPlacement = 'keyboard', toolbarItems = EditorToolbar_1.DEFAULT_EDITOR_TOOLBAR_ITEMS, onToolbarAction, onRequestLink, onRequestImage, autoDetectLinks = false, onContentChange, onContentChangeJSON, onSelectionChange, onActiveStateChange, onHistoryStateChange, onFocus, onBlur, style, containerStyle, theme, addons, remoteSelections, allowBase64Images = false, allowImageResizing = true, }, ref) {
     const bridgeRef = (0, react_1.useRef)(null);
     const nativeViewRef = (0, react_1.useRef)(null);
@@ -519,8 +554,20 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
     const registeredToolbarFrames = (0, EditorToolbar_1.useEditorToolbarFrames)();
     const [pendingNativeUpdate, setPendingNativeUpdate] = (0, react_1.useState)({
         json: undefined,
+        editorId: undefined,
         revision: 0,
     });
+    const pendingNativeUpdateRef = (0, react_1.useRef)(pendingNativeUpdate);
+    pendingNativeUpdateRef.current = pendingNativeUpdate;
+    const pendingNativeUpdateInFlightRef = (0, react_1.useRef)(null);
+    const [blockedNativeCommandRetry, setBlockedNativeCommandRetry] = (0, react_1.useState)(0);
+    const [detachedControlledSyncRetry, setDetachedControlledSyncRetry] = (0, react_1.useState)(0);
+    const [controlledNativeUpdateRetry, setControlledNativeUpdateRetry] = (0, react_1.useState)(0);
+    const pendingDetachedControlledSyncRef = (0, react_1.useRef)(false);
+    const pendingControlledSyncAfterNativeUpdateRef = (0, react_1.useRef)(false);
+    const pendingBlockedNativeCommandRetryRef = (0, react_1.useRef)(false);
+    const pendingNativeCommandRetryRef = (0, react_1.useRef)(null);
+    const blockedNativeCommandRetryTimerRef = (0, react_1.useRef)(null);
     const [autoGrowHeight, setAutoGrowHeight] = (0, react_1.useState)(null);
     // Toolbar state from EditorUpdate events
     const [activeState, setActiveState] = (0, react_1.useState)({
@@ -531,6 +578,8 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
         allowedMarks: [],
         insertableNodes: [],
     });
+    const activeStateRef = (0, react_1.useRef)(activeState);
+    activeStateRef.current = activeState;
     const [historyState, setHistoryState] = (0, react_1.useState)({
         canUndo: false,
         canRedo: false,
@@ -540,9 +589,28 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
     const selectionRef = (0, react_1.useRef)({ type: 'text', anchor: 0, head: 0 });
     const renderedTextLengthRef = (0, react_1.useRef)(0);
     const documentVersionRef = (0, react_1.useRef)(null);
+    const controlledHtmlSyncRef = (0, react_1.useRef)({
+        value: undefined,
+        documentVersion: null,
+    });
+    const controlledJsonSyncRef = (0, react_1.useRef)({
+        value: undefined,
+        documentVersion: null,
+    });
     const toolbarRef = (0, react_1.useRef)(null);
     const mentionQueryEventRef = (0, react_1.useRef)(null);
+    const mentionQueryEditorIdRef = (0, react_1.useRef)(null);
     mentionQueryEventRef.current = mentionQueryEvent;
+    const setMentionQueryEventState = (0, react_1.useCallback)((nextEvent, editorId) => {
+        mentionQueryEventRef.current = nextEvent;
+        mentionQueryEditorIdRef.current =
+            nextEvent == null
+                ? null
+                : typeof editorId === 'number'
+                    ? editorId
+                    : (bridgeRef.current?.editorId ?? null);
+        setMentionQueryEvent(nextEvent);
+    }, []);
     const toolbarItemsSerializationCacheRef = (0, react_1.useRef)(null);
     // Stable callback refs to avoid re-renders
     const onContentChangeRef = (0, react_1.useRef)(onContentChange);
@@ -574,27 +642,81 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
     const themeJson = useSerializedValue(theme, EditorTheme_1.serializeEditorTheme);
     const addonsJson = useSerializedValue(addons, addons_1.serializeEditorAddons);
     const remoteSelectionsJson = useSerializedValue(remoteSelections, (selections) => serializeRemoteSelections(selections));
+    const clearBlockedNativeCommandRetryTimer = (0, react_1.useCallback)(() => {
+        const timer = blockedNativeCommandRetryTimerRef.current;
+        if (timer == null)
+            return;
+        clearTimeout(timer);
+        blockedNativeCommandRetryTimerRef.current = null;
+    }, []);
+    const flushBlockedNativeCommandRetry = (0, react_1.useCallback)(() => {
+        const hadPendingRetry = pendingBlockedNativeCommandRetryRef.current ||
+            blockedNativeCommandRetryTimerRef.current != null;
+        if (!hadPendingRetry)
+            return;
+        pendingBlockedNativeCommandRetryRef.current = false;
+        clearBlockedNativeCommandRetryTimer();
+        setBlockedNativeCommandRetry((revision) => revision + 1);
+    }, [clearBlockedNativeCommandRetryTimer]);
+    const scheduleBlockedNativeCommandRetry = (0, react_1.useCallback)(() => {
+        pendingBlockedNativeCommandRetryRef.current = true;
+        if (blockedNativeCommandRetryTimerRef.current != null)
+            return;
+        blockedNativeCommandRetryTimerRef.current = setTimeout(() => {
+            blockedNativeCommandRetryTimerRef.current = null;
+            if (!pendingBlockedNativeCommandRetryRef.current)
+                return;
+            pendingBlockedNativeCommandRetryRef.current = false;
+            setBlockedNativeCommandRetry((revision) => revision + 1);
+        }, 50);
+    }, []);
+    const enqueueBlockedNativeCommandRetry = (0, react_1.useCallback)((retry) => {
+        pendingNativeCommandRetryRef.current = retry;
+        scheduleBlockedNativeCommandRetry();
+    }, [scheduleBlockedNativeCommandRetry]);
+    const clearStaleMentionQueryForDocumentVersion = (0, react_1.useCallback)((documentVersion) => {
+        const currentMentionQuery = mentionQueryEventRef.current;
+        if (currentMentionQuery != null &&
+            (typeof currentMentionQuery.documentVersion !== 'number' ||
+                currentMentionQuery.documentVersion < documentVersion)) {
+            setMentionQueryEventState(null);
+        }
+    }, [setMentionQueryEventState]);
     const syncStateFromUpdate = (0, react_1.useCallback)((update) => {
         if (!update)
             return;
+        activeStateRef.current = update.activeState;
         setActiveState(update.activeState);
         setHistoryState(update.historyState);
         selectionRef.current = update.selection;
         renderedTextLengthRef.current = computeRenderedTextLength(update.renderElements);
         if (typeof update.documentVersion === 'number') {
+            const previousDocumentVersion = documentVersionRef.current;
             documentVersionRef.current = update.documentVersion;
+            if (previousDocumentVersion == null ||
+                update.documentVersion > previousDocumentVersion) {
+                clearStaleMentionQueryForDocumentVersion(update.documentVersion);
+            }
         }
-    }, []);
+        flushBlockedNativeCommandRetry();
+    }, [clearStaleMentionQueryForDocumentVersion, flushBlockedNativeCommandRetry]);
     const syncSelectionStateFromUpdate = (0, react_1.useCallback)((update) => {
         if (!update)
             return;
+        activeStateRef.current = update.activeState;
         setActiveState(update.activeState);
         setHistoryState(update.historyState);
         selectionRef.current = update.selection;
         if (typeof update.documentVersion === 'number') {
+            const previousDocumentVersion = documentVersionRef.current;
             documentVersionRef.current = update.documentVersion;
+            if (previousDocumentVersion == null ||
+                update.documentVersion > previousDocumentVersion) {
+                clearStaleMentionQueryForDocumentVersion(update.documentVersion);
+            }
         }
-    }, []);
+        flushBlockedNativeCommandRetry();
+    }, [clearStaleMentionQueryForDocumentVersion, flushBlockedNativeCommandRetry]);
     const emitContentCallbacksForUpdate = (0, react_1.useCallback)((update, previousDocumentVersion) => {
         if (!update || !bridgeRef.current || bridgeRef.current.isDestroyed)
             return;
@@ -620,85 +742,222 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
             onContentChangeJSONRef.current?.(bridgeRef.current.getJson());
         }
     }, []);
+    const clearPendingNativeUpdateForCurrentEditor = (0, react_1.useCallback)(() => {
+        if (react_native_1.Platform.OS !== 'android')
+            return;
+        const editorId = bridgeRef.current?.editorId;
+        if (typeof editorId !== 'number')
+            return;
+        const inFlight = pendingNativeUpdateInFlightRef.current;
+        if (inFlight != null && inFlight.editorId === editorId) {
+            pendingNativeUpdateInFlightRef.current = null;
+        }
+        setPendingNativeUpdate((current) => {
+            if (current.json == null && current.editorId === editorId) {
+                return current;
+            }
+            const next = {
+                json: undefined,
+                editorId,
+                revision: current.revision + 1,
+            };
+            pendingNativeUpdateRef.current = next;
+            return next;
+        });
+    }, []);
+    const consumeBlockedCommandInfoForRetry = (0, react_1.useCallback)((bridge) => {
+        const blockedInfo = bridge.consumeLastCommandBlockedInfo();
+        if (!blockedInfo.blocked)
+            return blockedInfo;
+        if (blockedInfo.reason === 'detached') {
+            pendingDetachedControlledSyncRef.current = true;
+        }
+        else if (blockedInfo.reason === 'destroyed') {
+            pendingDetachedControlledSyncRef.current = false;
+            pendingBlockedNativeCommandRetryRef.current = false;
+            pendingNativeCommandRetryRef.current = null;
+            clearBlockedNativeCommandRetryTimer();
+            clearPendingNativeUpdateForCurrentEditor();
+        }
+        else {
+            scheduleBlockedNativeCommandRetry();
+        }
+        return blockedInfo;
+    }, [
+        clearBlockedNativeCommandRetryTimer,
+        clearPendingNativeUpdateForCurrentEditor,
+        scheduleBlockedNativeCommandRetry,
+    ]);
+    const consumeBlockedCommandForRetry = (0, react_1.useCallback)((bridge) => consumeBlockedCommandInfoForRetry(bridge).blocked, [consumeBlockedCommandInfoForRetry]);
+    (0, react_1.useEffect)(() => {
+        const retry = pendingNativeCommandRetryRef.current;
+        if (retry == null)
+            return;
+        pendingNativeCommandRetryRef.current = null;
+        retry();
+    }, [blockedNativeCommandRetry]);
+    const hasPendingNativeUpdateInFlightForCurrentEditor = (0, react_1.useCallback)(() => {
+        if (react_native_1.Platform.OS !== 'android')
+            return false;
+        const editorId = bridgeRef.current?.editorId;
+        if (typeof editorId !== 'number')
+            return false;
+        const inFlight = pendingNativeUpdateInFlightRef.current;
+        return inFlight != null && inFlight.editorId === editorId;
+    }, []);
     const applyUpdateToNativeView = (0, react_1.useCallback)((update, previousDocumentVersion, skipNativeApplyIfContentUnchanged = false) => {
         const contentChanged = didContentChange(previousDocumentVersion, update);
+        const handleApplyResult = (result) => {
+            if (result === false) {
+                setBlockedNativeCommandRetry((revision) => revision + 1);
+                return false;
+            }
+            return true;
+        };
         if (!skipNativeApplyIfContentUnchanged || contentChanged) {
             const updateJson = JSON.stringify(update);
             if (react_native_1.Platform.OS === 'android') {
-                setPendingNativeUpdate((current) => ({
-                    json: updateJson,
-                    revision: current.revision + 1,
-                }));
+                const editorId = bridgeRef.current?.editorId;
+                setPendingNativeUpdate((current) => {
+                    const revision = current.revision + 1;
+                    const next = {
+                        json: updateJson,
+                        editorId,
+                        revision,
+                    };
+                    pendingNativeUpdateRef.current = next;
+                    pendingNativeUpdateInFlightRef.current = { editorId, revision };
+                    return next;
+                });
             }
             else {
                 try {
                     const applyResult = nativeViewRef.current?.applyEditorUpdate(updateJson);
                     if (isPromiseLike(applyResult)) {
-                        void applyResult.catch(() => {
+                        void applyResult
+                            .then((result) => {
+                            handleApplyResult(result);
+                        })
+                            .catch(() => {
                             // The native view may already be torn down during navigation.
                         });
                     }
+                    else {
+                        return handleApplyResult(applyResult);
+                    }
                 }
                 catch {
                     // The native view may already be torn down during navigation.
                 }
             }
         }
-        return contentChanged;
+        return true;
     }, []);
     const maybeApplyAutoDetectedLink = (0, react_1.useCallback)((update, previousDocumentVersion) => {
-        if (!autoDetectLinks ||
-            !update ||
-            !didContentChange(previousDocumentVersion, update) ||
-            !bridgeRef.current ||
-            bridgeRef.current.isDestroyed ||
-            !update.activeState.allowedMarks.includes('link') ||
-            update.selection.type !== 'text' ||
-            update.selection.anchor == null ||
-            update.selection.head == null ||
-            update.selection.anchor !== update.selection.head) {
-            return update;
-        }
-        const cursorDocPos = update.selection.head;
-        const candidate = findAutoLinkCandidateInDocument(bridgeRef.current.getJson(), cursorDocPos);
-        if (!candidate) {
-            return update;
-        }
-        const scalarFrom = bridgeRef.current.docToScalar(candidate.docFrom);
-        const scalarTo = bridgeRef.current.docToScalar(candidate.docTo);
-        if (!(scalarTo > scalarFrom)) {
-            return update;
-        }
-        const autoLinkUpdate = bridgeRef.current.setMarkAtSelectionScalar(scalarFrom, scalarTo, 'link', { href: candidate.href });
-        if (!autoLinkUpdate) {
-            return update;
-        }
-        bridgeRef.current.setSelection(update.selection.anchor, update.selection.head);
-        const selectionState = bridgeRef.current.getSelectionState();
-        if (selectionState) {
-            autoLinkUpdate.selection = selectionState.selection;
-            autoLinkUpdate.activeState = selectionState.activeState;
-            autoLinkUpdate.historyState = selectionState.historyState;
-            if (typeof selectionState.documentVersion === 'number') {
-                autoLinkUpdate.documentVersion = selectionState.documentVersion;
+        const applyAutoLink = (candidateUpdate, allowPreflightRetry) => {
+            if (!autoDetectLinks ||
+                !candidateUpdate ||
+                !didContentChange(previousDocumentVersion, candidateUpdate) ||
+                !bridgeRef.current ||
+                bridgeRef.current.isDestroyed ||
+                !candidateUpdate.activeState.allowedMarks.includes('link') ||
+                candidateUpdate.selection.type !== 'text' ||
+                candidateUpdate.selection.anchor == null ||
+                candidateUpdate.selection.head == null ||
+                candidateUpdate.selection.anchor !== candidateUpdate.selection.head) {
+                return candidateUpdate;
+            }
+            const cursorDocPos = candidateUpdate.selection.head;
+            const candidate = findAutoLinkCandidateInDocument(bridgeRef.current.getJson(), cursorDocPos);
+            if (!candidate) {
+                return candidateUpdate;
+            }
+            const scalarFrom = bridgeRef.current.docToScalar(candidate.docFrom);
+            const scalarTo = bridgeRef.current.docToScalar(candidate.docTo);
+            if (!(scalarTo > scalarFrom)) {
+                return candidateUpdate;
+            }
+            const autoLinkUpdate = bridgeRef.current.setMarkAtSelectionScalar(scalarFrom, scalarTo, 'link', { href: candidate.href });
+            if (!autoLinkUpdate) {
+                const preflightUpdate = bridgeRef.current.consumeLastCommandPreflightUpdate();
+                if (preflightUpdate) {
+                    return allowPreflightRetry
+                        ? applyAutoLink(preflightUpdate, false)
+                        : preflightUpdate;
+                }
+                consumeBlockedCommandForRetry(bridgeRef.current);
+                return candidateUpdate;
+            }
+            bridgeRef.current.setSelection(candidateUpdate.selection.anchor, candidateUpdate.selection.head);
+            const selectionState = bridgeRef.current.getSelectionState();
+            if (selectionState) {
+                autoLinkUpdate.selection = selectionState.selection;
+                autoLinkUpdate.activeState = selectionState.activeState;
+                autoLinkUpdate.historyState = selectionState.historyState;
+                if (typeof selectionState.documentVersion === 'number') {
+                    autoLinkUpdate.documentVersion = selectionState.documentVersion;
+                }
             }
+            else {
+                autoLinkUpdate.selection = candidateUpdate.selection;
+            }
+            return autoLinkUpdate;
+        };
+        return applyAutoLink(update, true);
+    }, [autoDetectLinks, consumeBlockedCommandForRetry]);
+    const syncNativeUpdateFromBridge = (0, react_1.useCallback)((nativeUpdate, previousDocumentVersion, options) => {
+        const update = maybeApplyAutoDetectedLink(nativeUpdate, previousDocumentVersion);
+        if (!update)
+            return null;
+        if (update !== nativeUpdate) {
+            applyUpdateToNativeView(update, previousDocumentVersion, options?.skipNativeApplyIfContentUnchanged);
         }
-        else {
-            autoLinkUpdate.selection = update.selection;
+        syncStateFromUpdate(update);
+        onActiveStateChangeRef.current?.(update.activeState);
+        onHistoryStateChangeRef.current?.(update.historyState);
+        if (!options?.suppressContentCallbacks) {
+            emitContentCallbacksForUpdate(update, previousDocumentVersion);
         }
-        return autoLinkUpdate;
-    }, [autoDetectLinks]);
+        onSelectionChangeRef.current?.(update.selection);
+        return update;
+    }, [
+        applyUpdateToNativeView,
+        emitContentCallbacksForUpdate,
+        maybeApplyAutoDetectedLink,
+        syncStateFromUpdate,
+    ]);
     // Warn if both value and valueJSON are set
     if (__DEV__ && value != null && valueJSON != null) {
         console.warn('NativeRichTextEditor: value and valueJSON are mutually exclusive. ' +
             'Only value will be used.');
     }
     const runAndApply = (0, react_1.useCallback)((mutate, options) => {
+        if (hasPendingNativeUpdateInFlightForCurrentEditor()) {
+            if (options?.retryBlockedCommand != null) {
+                enqueueBlockedNativeCommandRetry(options.retryBlockedCommand);
+                options.onBlockedCommandRetryQueued?.();
+            }
+            return null;
+        }
         const previousDocumentVersion = documentVersionRef.current;
         const preservedSelection = options?.preserveLiveTextSelection === true ? selectionRef.current : null;
         let update = mutate();
-        if (!update)
+        if (!update) {
+            const bridge = bridgeRef.current;
+            if (bridge != null && !bridge.isDestroyed) {
+                const preflightUpdate = bridge.consumeLastCommandPreflightUpdate();
+                if (preflightUpdate) {
+                    syncNativeUpdateFromBridge(preflightUpdate, previousDocumentVersion);
+                }
+                const blockedInfo = consumeBlockedCommandInfoForRetry(bridge);
+                if (options?.retryBlockedCommand != null &&
+                    isRetryableNativeCommandBlock(blockedInfo.reason)) {
+                    enqueueBlockedNativeCommandRetry(options.retryBlockedCommand);
+                    options.onBlockedCommandRetryQueued?.();
+                }
+            }
             return null;
+        }
         if (!options?.skipAutoDetectLinks) {
             update = maybeApplyAutoDetectedLink(update, previousDocumentVersion);
             if (!update) {
@@ -708,6 +967,7 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
         if (preservedSelection?.type === 'text' &&
             typeof preservedSelection.anchor === 'number' &&
             typeof preservedSelection.head === 'number' &&
+            !didContentChange(previousDocumentVersion, update) &&
             bridgeRef.current != null &&
             !bridgeRef.current.isDestroyed) {
             bridgeRef.current.setSelection(preservedSelection.anchor, preservedSelection.head);
@@ -728,10 +988,56 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
         return update;
     }, [
         applyUpdateToNativeView,
+        consumeBlockedCommandInfoForRetry,
+        enqueueBlockedNativeCommandRetry,
         emitContentCallbacksForUpdate,
+        hasPendingNativeUpdateInFlightForCurrentEditor,
         maybeApplyAutoDetectedLink,
+        syncNativeUpdateFromBridge,
         syncStateFromUpdate,
     ]);
+    const prepareBridgeForExternalContentRead = (0, react_1.useCallback)((options) => {
+        const bridge = bridgeRef.current;
+        if (!bridge || bridge.isDestroyed)
+            return false;
+        const previousDocumentVersion = documentVersionRef.current;
+        const ready = bridge.prepareForNativeCommand();
+        const preflightUpdate = bridge.consumeLastCommandPreflightUpdate();
+        if (preflightUpdate) {
+            syncNativeUpdateFromBridge(preflightUpdate, previousDocumentVersion);
+        }
+        if (!ready) {
+            consumeBlockedCommandForRetry(bridge);
+            return false;
+        }
+        return (options?.skipWhenContentChanged !== true ||
+            !didContentChange(previousDocumentVersion, preflightUpdate));
+    }, [consumeBlockedCommandForRetry, syncNativeUpdateFromBridge]);
+    const syncPreflightUpdateFromNativeEvent = (0, react_1.useCallback)((updateJson) => {
+        if (typeof updateJson !== 'string' || updateJson.length === 0) {
+            return true;
+        }
+        const bridge = bridgeRef.current;
+        if (!bridge || bridge.isDestroyed)
+            return false;
+        const previousDocumentVersion = documentVersionRef.current;
+        try {
+            const parsed = JSON.parse(updateJson);
+            if (react_native_1.Platform.OS === 'android' &&
+                typeof previousDocumentVersion === 'number' &&
+                typeof parsed.documentVersion !== 'number') {
+                return false;
+            }
+            const update = bridge.parseUpdateJson(updateJson);
+            if (!update)
+                return false;
+            syncNativeUpdateFromBridge(update, previousDocumentVersion);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, [syncNativeUpdateFromBridge]);
     (0, react_1.useEffect)(() => {
         const bridgeConfig = maxLength != null || serializedSchemaJson || allowBase64Images
             ? {
@@ -762,39 +1068,159 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
             bridge.destroy();
             bridgeRef.current = null;
             nativeViewRef.current = null;
+            pendingNativeUpdateInFlightRef.current = null;
+            pendingDetachedControlledSyncRef.current = false;
+            pendingControlledSyncAfterNativeUpdateRef.current = false;
+            pendingBlockedNativeCommandRetryRef.current = false;
+            pendingNativeCommandRetryRef.current = null;
+            documentVersionRef.current = null;
+            mentionQueryEventRef.current = null;
+            mentionQueryEditorIdRef.current = null;
+            clearBlockedNativeCommandRetryTimer();
+            setMentionQueryEvent(null);
+            setPendingNativeUpdate((current) => {
+                const next = {
+                    json: undefined,
+                    editorId: undefined,
+                    revision: current.revision + 1,
+                };
+                pendingNativeUpdateRef.current = next;
+                return next;
+            });
             setEditorInstanceId(0);
             setIsReady(false);
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [maxLength, syncStateFromUpdate, allowBase64Images, serializedSchemaJson]);
+    }, [
+        maxLength,
+        syncStateFromUpdate,
+        allowBase64Images,
+        serializedSchemaJson,
+        clearBlockedNativeCommandRetryTimer,
+    ]);
     (0, react_1.useEffect)(() => {
         if (value == null)
             return;
         if (!bridgeRef.current || bridgeRef.current.isDestroyed)
             return;
+        const previousSync = controlledHtmlSyncRef.current;
+        const didControlledValueChange = previousSync.value !== value;
+        const didDocumentAdvanceForSameValue = !didControlledValueChange &&
+            previousSync.documentVersion !== documentVersionRef.current;
+        if (!prepareBridgeForExternalContentRead({
+            skipWhenContentChanged: !didControlledValueChange,
+        })) {
+            controlledHtmlSyncRef.current = {
+                value,
+                documentVersion: documentVersionRef.current,
+            };
+            return;
+        }
+        if (didDocumentAdvanceForSameValue) {
+            controlledHtmlSyncRef.current = {
+                value,
+                documentVersion: documentVersionRef.current,
+            };
+            return;
+        }
         const currentHtml = bridgeRef.current.getHtml();
-        if (currentHtml === value)
+        if (currentHtml === value) {
+            clearPendingNativeUpdateForCurrentEditor();
+            controlledHtmlSyncRef.current = {
+                value,
+                documentVersion: documentVersionRef.current,
+            };
+            return;
+        }
+        if (hasPendingNativeUpdateInFlightForCurrentEditor()) {
+            pendingControlledSyncAfterNativeUpdateRef.current = true;
             return;
-        runAndApply(() => bridgeRef.current.replaceHtml(value), {
+        }
+        const update = runAndApply(() => bridgeRef.current.replaceHtml(value), {
             suppressContentCallbacks: true,
             preserveLiveTextSelection: true,
             skipAutoDetectLinks: true,
         });
-    }, [value, runAndApply]);
+        if (!update && hasPendingNativeUpdateInFlightForCurrentEditor()) {
+            pendingControlledSyncAfterNativeUpdateRef.current = true;
+            return;
+        }
+        controlledHtmlSyncRef.current = {
+            value,
+            documentVersion: documentVersionRef.current,
+        };
+    }, [
+        value,
+        runAndApply,
+        blockedNativeCommandRetry,
+        controlledNativeUpdateRetry,
+        detachedControlledSyncRetry,
+        prepareBridgeForExternalContentRead,
+        clearPendingNativeUpdateForCurrentEditor,
+        hasPendingNativeUpdateInFlightForCurrentEditor,
+    ]);
     (0, react_1.useEffect)(() => {
         if (serializedValueJson == null || value != null)
             return;
         if (!bridgeRef.current || bridgeRef.current.isDestroyed)
             return;
+        const previousSync = controlledJsonSyncRef.current;
+        const didControlledValueChange = previousSync.value !== serializedValueJson;
+        const didDocumentAdvanceForSameValue = !didControlledValueChange &&
+            previousSync.documentVersion !== documentVersionRef.current;
+        if (!prepareBridgeForExternalContentRead({
+            skipWhenContentChanged: !didControlledValueChange,
+        })) {
+            controlledJsonSyncRef.current = {
+                value: serializedValueJson,
+                documentVersion: documentVersionRef.current,
+            };
+            return;
+        }
+        if (didDocumentAdvanceForSameValue) {
+            controlledJsonSyncRef.current = {
+                value: serializedValueJson,
+                documentVersion: documentVersionRef.current,
+            };
+            return;
+        }
         const currentJson = bridgeRef.current.getJsonString();
-        if (currentJson === serializedValueJson)
+        if (currentJson === serializedValueJson) {
+            clearPendingNativeUpdateForCurrentEditor();
+            controlledJsonSyncRef.current = {
+                value: serializedValueJson,
+                documentVersion: documentVersionRef.current,
+            };
+            return;
+        }
+        if (hasPendingNativeUpdateInFlightForCurrentEditor()) {
+            pendingControlledSyncAfterNativeUpdateRef.current = true;
             return;
-        runAndApply(() => bridgeRef.current.replaceJsonString(serializedValueJson), {
+        }
+        const update = runAndApply(() => bridgeRef.current.replaceJsonString(serializedValueJson), {
             suppressContentCallbacks: true,
             preserveLiveTextSelection: true,
             skipAutoDetectLinks: true,
         });
-    }, [serializedValueJson, value, runAndApply]);
+        if (!update && hasPendingNativeUpdateInFlightForCurrentEditor()) {
+            pendingControlledSyncAfterNativeUpdateRef.current = true;
+            return;
+        }
+        controlledJsonSyncRef.current = {
+            value: serializedValueJson,
+            documentVersion: documentVersionRef.current,
+        };
+    }, [
+        serializedValueJson,
+        value,
+        runAndApply,
+        blockedNativeCommandRetry,
+        controlledNativeUpdateRetry,
+        detachedControlledSyncRetry,
+        prepareBridgeForExternalContentRead,
+        clearPendingNativeUpdateForCurrentEditor,
+        hasPendingNativeUpdateInFlightForCurrentEditor,
+    ]);
     const updateToolbarFrame = (0, react_1.useCallback)(() => {
         const toolbar = toolbarRef.current;
         if (!toolbar) {
@@ -826,62 +1252,96 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
         }
     }, [heightBehavior]);
     const handleUpdate = (0, react_1.useCallback)((event) => {
-        if (!bridgeRef.current || bridgeRef.current.isDestroyed)
+        const bridge = bridgeRef.current;
+        if (!bridge || bridge.isDestroyed)
+            return;
+        if (!isCurrentNativeEditorEvent(event.nativeEvent, bridge))
             return;
         try {
             const previousDocumentVersion = documentVersionRef.current;
-            const nativeUpdate = bridgeRef.current.parseUpdateJson(event.nativeEvent.updateJson);
+            if (react_native_1.Platform.OS === 'android' && typeof previousDocumentVersion === 'number') {
+                const parsed = JSON.parse(event.nativeEvent.updateJson);
+                if (typeof parsed.documentVersion !== 'number') {
+                    return;
+                }
+            }
+            const nativeUpdate = bridge.parseUpdateJson(event.nativeEvent.updateJson, { rejectSameDocumentVersion: true });
             if (!nativeUpdate)
                 return;
-            const update = maybeApplyAutoDetectedLink(nativeUpdate, previousDocumentVersion);
-            if (!update)
-                return;
-            if (update !== nativeUpdate) {
-                applyUpdateToNativeView(update, previousDocumentVersion);
-            }
-            syncStateFromUpdate(update);
-            onActiveStateChangeRef.current?.(update.activeState);
-            onHistoryStateChangeRef.current?.(update.historyState);
-            emitContentCallbacksForUpdate(update, previousDocumentVersion);
-            onSelectionChangeRef.current?.(update.selection);
+            syncNativeUpdateFromBridge(nativeUpdate, previousDocumentVersion);
         }
         catch {
             // Invalid JSON from native — skip
         }
-    }, [
-        applyUpdateToNativeView,
-        emitContentCallbacksForUpdate,
-        maybeApplyAutoDetectedLink,
-        syncStateFromUpdate,
-    ]);
+    }, [syncNativeUpdateFromBridge]);
     const handleSelectionChange = (0, react_1.useCallback)((event) => {
-        if (!bridgeRef.current || bridgeRef.current.isDestroyed)
+        const bridge = bridgeRef.current;
+        if (!bridge || bridge.isDestroyed)
+            return;
+        if (!isCurrentNativeEditorEvent(event.nativeEvent, bridge))
+            return;
+        const { anchor, head, stateJson, documentVersion } = event.nativeEvent;
+        const currentDocumentVersion = documentVersionRef.current;
+        if (typeof documentVersion === 'number' &&
+            typeof currentDocumentVersion === 'number' &&
+            documentVersion < currentDocumentVersion) {
             return;
-        const { anchor, head, stateJson } = event.nativeEvent;
-        let selection;
-        if (anchor === 0 &&
-            head >= renderedTextLengthRef.current &&
-            renderedTextLengthRef.current > 0) {
-            selection = { type: 'all' };
-        }
-        else {
-            selection = { type: 'text', anchor, head };
         }
-        bridgeRef.current.updateSelectionFromNative(anchor, head);
         let currentState = null;
         if (typeof stateJson === 'string' && stateJson.length > 0) {
+            if (react_native_1.Platform.OS === 'android' &&
+                typeof currentDocumentVersion === 'number') {
+                const stateDocumentVersion = documentVersionFromUpdateJson(stateJson);
+                if (typeof stateDocumentVersion !== 'number' ||
+                    stateDocumentVersion < currentDocumentVersion) {
+                    return;
+                }
+            }
             try {
-                currentState = bridgeRef.current.parseUpdateJson(stateJson);
+                currentState = bridge.parseUpdateJson(stateJson);
+                if (!currentState)
+                    return;
             }
             catch {
-                currentState = bridgeRef.current.getSelectionState();
+                currentState = bridge.getSelectionState();
             }
         }
         else {
-            currentState = bridgeRef.current.getSelectionState();
+            currentState = bridge.getSelectionState();
+        }
+        if (currentState != null &&
+            typeof currentState.documentVersion === 'number' &&
+            typeof currentDocumentVersion === 'number' &&
+            currentState.documentVersion < currentDocumentVersion) {
+            return;
+        }
+        if (currentState != null &&
+            react_native_1.Platform.OS === 'android' &&
+            typeof currentDocumentVersion === 'number' &&
+            typeof currentState.documentVersion !== 'number') {
+            return;
+        }
+        if (currentState == null &&
+            react_native_1.Platform.OS === 'android' &&
+            typeof currentDocumentVersion === 'number') {
+            return;
+        }
+        let selection;
+        const selectionStart = Math.min(anchor, head);
+        const selectionEnd = Math.max(anchor, head);
+        if (selectionStart === 0 &&
+            selectionEnd >= renderedTextLengthRef.current &&
+            renderedTextLengthRef.current > 0) {
+            selection = { type: 'all' };
+        }
+        else {
+            selection = { type: 'text', anchor, head };
         }
-        syncSelectionStateFromUpdate(currentState);
         const nextSelection = selection.type === 'all' ? selection : (currentState?.selection ?? selection);
+        if (currentState == null) {
+            bridge.updateSelectionFromNative(anchor, head);
+        }
+        syncSelectionStateFromUpdate(currentState);
         selectionRef.current = nextSelection;
         if (currentState) {
             onActiveStateChangeRef.current?.(currentState.activeState);
@@ -899,6 +1359,8 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
         }, 50);
     }, []);
     const handleFocusChange = (0, react_1.useCallback)((event) => {
+        if (!isCurrentNativeEditorEvent(event.nativeEvent, bridgeRef.current))
+            return;
         const { isFocused: focused } = event.nativeEvent;
         if (!focused &&
             editable &&
@@ -912,7 +1374,7 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
         isFocusedRef.current = focused;
         setIsFocused(focused);
         if (!focused) {
-            setMentionQueryEvent(null);
+            setMentionQueryEventState(null);
         }
         if (focused) {
             if (!wasFocused) {
@@ -922,14 +1384,16 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
         else if (wasFocused) {
             onBlurRef.current?.();
         }
-    }, [editable, refocusAfterToolbarInteraction]);
+    }, [editable, refocusAfterToolbarInteraction, setMentionQueryEventState]);
     (0, react_1.useEffect)(() => {
         if (addons?.mentions != null) {
             return;
         }
-        setMentionQueryEvent(null);
-    }, [addons?.mentions]);
+        setMentionQueryEventState(null);
+    }, [addons?.mentions, setMentionQueryEventState]);
     const handleContentHeightChange = (0, react_1.useCallback)((event) => {
+        if (!isCurrentNativeEditorEvent(event.nativeEvent, bridgeRef.current))
+            return;
         if (heightBehavior !== 'autoGrow')
             return;
         const density = react_native_1.Platform.OS === 'android' ? react_native_1.PixelRatio.get() : 1;
@@ -938,6 +1402,47 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
             return;
         setAutoGrowHeight((prev) => (prev === nextHeight ? prev : nextHeight));
     }, [autoGrowHeight, heightBehavior]);
+    const handleEditorReady = (0, react_1.useCallback)((event) => {
+        if (!isCurrentNativeEditorEvent(event.nativeEvent, bridgeRef.current))
+            return;
+        const editorId = bridgeRef.current?.editorId;
+        const acknowledgedRevision = event.nativeEvent.editorUpdateRevision;
+        const inFlight = pendingNativeUpdateInFlightRef.current;
+        let didClearInFlight = false;
+        if (inFlight != null) {
+            const matchesRevision = typeof acknowledgedRevision === 'number' &&
+                inFlight.editorId === editorId &&
+                inFlight.revision === acknowledgedRevision;
+            if (!matchesRevision) {
+                return;
+            }
+            pendingNativeUpdateInFlightRef.current = null;
+            didClearInFlight = true;
+            setPendingNativeUpdate((current) => {
+                if (current.editorId !== editorId ||
+                    current.revision !== acknowledgedRevision ||
+                    current.json == null) {
+                    return current;
+                }
+                const next = {
+                    json: undefined,
+                    editorId,
+                    revision: current.revision,
+                };
+                pendingNativeUpdateRef.current = next;
+                return next;
+            });
+        }
+        flushBlockedNativeCommandRetry();
+        if (didClearInFlight && pendingControlledSyncAfterNativeUpdateRef.current) {
+            pendingControlledSyncAfterNativeUpdateRef.current = false;
+            setControlledNativeUpdateRetry((revision) => revision + 1);
+        }
+        if (!pendingDetachedControlledSyncRef.current)
+            return;
+        pendingDetachedControlledSyncRef.current = false;
+        setDetachedControlledSyncRetry((revision) => revision + 1);
+    }, [flushBlockedNativeCommandRetry]);
     const restoreSelection = (0, react_1.useCallback)((selection) => {
         if (selection.type === 'text') {
             const { anchor, head } = selection;
@@ -955,6 +1460,134 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
             bridgeRef.current?.setSelection(pos, pos);
         }
     }, []);
+    const isAsyncRequestCurrent = (0, react_1.useCallback)((requestEditorId, requestDocumentVersion) => {
+        const bridge = bridgeRef.current;
+        return (bridge != null &&
+            !bridge.isDestroyed &&
+            bridge.editorId === requestEditorId &&
+            documentVersionRef.current === requestDocumentVersion);
+    }, []);
+    const scalarRangeFromSelection = (0, react_1.useCallback)((selection) => {
+        const bridge = bridgeRef.current;
+        if (!bridge || bridge.isDestroyed)
+            return null;
+        if (selection.type === 'text') {
+            const anchor = selection.anchor ?? 0;
+            const head = selection.head ?? anchor;
+            return {
+                anchor: bridge.docToScalar(anchor),
+                head: bridge.docToScalar(head),
+            };
+        }
+        if (selection.type === 'node' && typeof selection.pos === 'number') {
+            const scalar = bridge.docToScalar(selection.pos);
+            return { anchor: scalar, head: scalar };
+        }
+        return null;
+    }, []);
+    const isCommandRetryScopeCurrent = (0, react_1.useCallback)((scope) => {
+        const bridge = bridgeRef.current;
+        if (!bridge || bridge.isDestroyed || bridge.editorId !== scope.editorId) {
+            return false;
+        }
+        const currentDocumentVersion = documentVersionRef.current;
+        const hasMentionScope = scope.mentionQuery != null ||
+            scope.mentionRange != null ||
+            scope.nativeMentionSelectRequest != null;
+        if (currentDocumentVersion !== scope.documentVersion) {
+            if (!hasMentionScope) {
+                return false;
+            }
+            if (typeof currentDocumentVersion === 'number' &&
+                typeof scope.documentVersion === 'number' &&
+                currentDocumentVersion > scope.documentVersion) {
+                return false;
+            }
+        }
+        if (hasMentionScope &&
+            typeof currentDocumentVersion === 'number' &&
+            scope.documentVersion == null) {
+            return false;
+        }
+        if (typeof scope.scalarAnchor === 'number' &&
+            typeof scope.scalarHead === 'number') {
+            const currentRange = scalarRangeFromSelection(selectionRef.current);
+            if (currentRange?.anchor !== scope.scalarAnchor ||
+                currentRange?.head !== scope.scalarHead) {
+                return false;
+            }
+        }
+        if (scope.mentionQuery) {
+            const mentionQueryEditorId = mentionQueryEditorIdRef.current;
+            if (mentionQueryEditorId != null &&
+                mentionQueryEditorId !== scope.editorId) {
+                return false;
+            }
+            const currentQuery = mentionQueryEventRef.current;
+            if (currentQuery == null ||
+                currentQuery.trigger !== scope.mentionQuery.trigger ||
+                currentQuery.query !== scope.mentionQuery.query ||
+                currentQuery.range.anchor !== scope.mentionQuery.range.anchor ||
+                currentQuery.range.head !== scope.mentionQuery.range.head ||
+                currentQuery.documentVersion !== scope.mentionQuery.documentVersion) {
+                return false;
+            }
+        }
+        if (scope.mentionRange) {
+            const mentionQueryEditorId = mentionQueryEditorIdRef.current;
+            if (mentionQueryEditorId != null &&
+                mentionQueryEditorId !== scope.editorId) {
+                return false;
+            }
+            const currentQuery = mentionQueryEventRef.current;
+            if (currentQuery == null ||
+                currentQuery.range.anchor !== scope.mentionRange.anchor ||
+                currentQuery.range.head !== scope.mentionRange.head ||
+                (currentQuery.documentVersion ?? null) !== scope.documentVersion) {
+                return false;
+            }
+        }
+        if (scope.nativeMentionSelectRequest) {
+            const mentionQueryEditorId = mentionQueryEditorIdRef.current;
+            if (mentionQueryEditorId != null &&
+                mentionQueryEditorId !== scope.editorId) {
+                return false;
+            }
+            if (doesLiveMentionQueryConflictWithNativeSelectRequest(scope.nativeMentionSelectRequest, mentionQueryEventRef.current, scope.documentVersion, currentDocumentVersion)) {
+                return false;
+            }
+        }
+        return true;
+    }, [scalarRangeFromSelection]);
+    const runAndApplyWithCommandRetry = (0, react_1.useCallback)((scope, mutate, options, onApplied) => {
+        let didQueueRetry = false;
+        let run = null;
+        const runIfScopeCurrent = () => {
+            if (!isCommandRetryScopeCurrent(scope))
+                return null;
+            return run?.() ?? null;
+        };
+        const retry = () => {
+            const update = runIfScopeCurrent();
+            if (update) {
+                onApplied?.(update);
+            }
+            return update != null;
+        };
+        run = () => runAndApply(mutate, {
+            ...options,
+            retryBlockedCommand: retry,
+            onBlockedCommandRetryQueued: () => {
+                didQueueRetry = true;
+                options?.onBlockedCommandRetryQueued?.();
+            },
+        });
+        const update = runIfScopeCurrent();
+        if (update) {
+            onApplied?.(update);
+        }
+        return { update, queued: didQueueRetry };
+    }, [isCommandRetryScopeCurrent, runAndApply]);
     const insertImage = (0, react_1.useCallback)((src, attrs, selection) => {
         const trimmedSrc = src.trim();
         if (!trimmedSrc)
@@ -974,38 +1607,116 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
     }, [allowBase64Images, restoreSelection, runAndApply]);
     const openLinkRequest = (0, react_1.useCallback)(() => {
         const requestSelection = selectionRef.current;
+        const requestDocumentVersion = documentVersionRef.current;
+        const requestEditorId = bridgeRef.current?.editorId ?? null;
+        const linkState = activeStateRef.current;
+        const requestLinkHref = typeof linkState.markAttrs?.link?.href === 'string'
+            ? linkState.markAttrs.link.href
+            : undefined;
         onRequestLink?.({
-            href: currentLinkHref,
-            isActive: activeState.marks.link === true,
+            href: requestLinkHref,
+            isActive: linkState.marks.link === true,
             selection: requestSelection,
             setLink: (href) => {
                 const trimmedHref = href.trim();
                 if (!trimmedHref)
                     return;
-                runAndApply(() => {
-                    restoreSelection(requestSelection);
-                    return (bridgeRef.current?.setMark('link', {
-                        href: trimmedHref,
-                    }) ?? null);
-                }, { skipNativeApplyIfContentUnchanged: true });
+                if (!isAsyncRequestCurrent(requestEditorId, requestDocumentVersion))
+                    return;
+                const bridge = bridgeRef.current;
+                if (!bridge || bridge.isDestroyed)
+                    return;
+                const scalarSelection = scalarRangeFromSelection(requestSelection);
+                if (!scalarSelection)
+                    return;
+                runAndApplyWithCommandRetry({
+                    editorId: bridge.editorId,
+                    documentVersion: requestDocumentVersion,
+                    scalarAnchor: scalarSelection.anchor,
+                    scalarHead: scalarSelection.head,
+                }, () => bridgeRef.current?.setMarkAtSelectionScalar(scalarSelection.anchor, scalarSelection.head, 'link', { href: trimmedHref }) ?? null, { skipNativeApplyIfContentUnchanged: true });
             },
             unsetLink: () => {
-                runAndApply(() => {
-                    restoreSelection(requestSelection);
-                    return bridgeRef.current?.unsetMark('link') ?? null;
-                }, { skipNativeApplyIfContentUnchanged: true });
+                if (!isAsyncRequestCurrent(requestEditorId, requestDocumentVersion))
+                    return;
+                const bridge = bridgeRef.current;
+                if (!bridge || bridge.isDestroyed)
+                    return;
+                const scalarSelection = scalarRangeFromSelection(requestSelection);
+                if (!scalarSelection)
+                    return;
+                runAndApplyWithCommandRetry({
+                    editorId: bridge.editorId,
+                    documentVersion: requestDocumentVersion,
+                    scalarAnchor: scalarSelection.anchor,
+                    scalarHead: scalarSelection.head,
+                }, () => bridgeRef.current?.unsetMarkAtSelectionScalar(scalarSelection.anchor, scalarSelection.head, 'link') ?? null, { skipNativeApplyIfContentUnchanged: true });
             },
         });
-    }, [activeState.marks.link, currentLinkHref, onRequestLink, restoreSelection, runAndApply]);
+    }, [
+        isAsyncRequestCurrent,
+        onRequestLink,
+        runAndApplyWithCommandRetry,
+        scalarRangeFromSelection,
+    ]);
     const openImageRequest = (0, react_1.useCallback)(() => {
         const requestSelection = selectionRef.current;
+        const requestDocumentVersion = documentVersionRef.current;
+        const requestEditorId = bridgeRef.current?.editorId ?? null;
         onRequestImage?.({
             selection: requestSelection,
             allowBase64: allowBase64Images,
-            insertImage: (src, attrs) => insertImage(src, attrs, requestSelection),
+            insertImage: (src, attrs) => {
+                const trimmedSrc = src.trim();
+                if (!trimmedSrc)
+                    return;
+                if (!allowBase64Images && isImageDataUrl(trimmedSrc))
+                    return;
+                if (!isAsyncRequestCurrent(requestEditorId, requestDocumentVersion))
+                    return;
+                const bridge = bridgeRef.current;
+                if (!bridge || bridge.isDestroyed)
+                    return;
+                const scalarSelection = scalarRangeFromSelection(requestSelection);
+                if (!scalarSelection)
+                    return;
+                runAndApplyWithCommandRetry({
+                    editorId: bridge.editorId,
+                    documentVersion: requestDocumentVersion,
+                    scalarAnchor: scalarSelection.anchor,
+                    scalarHead: scalarSelection.head,
+                }, () => bridgeRef.current?.insertContentJsonAtSelectionScalar(scalarSelection.anchor, scalarSelection.head, (0, schemas_1.buildImageFragmentJson)({
+                    src: trimmedSrc,
+                    ...(attrs ?? {}),
+                })) ?? null);
+            },
         });
-    }, [allowBase64Images, insertImage, onRequestImage]);
+    }, [
+        allowBase64Images,
+        isAsyncRequestCurrent,
+        onRequestImage,
+        runAndApplyWithCommandRetry,
+        scalarRangeFromSelection,
+    ]);
     const handleToolbarAction = (0, react_1.useCallback)((event) => {
+        if (!isCurrentNativeEditorEvent(event.nativeEvent, bridgeRef.current))
+            return;
+        const currentDocumentVersion = documentVersionRef.current;
+        const eventDocumentVersion = event.nativeEvent.documentVersion;
+        if (typeof eventDocumentVersion === 'number' &&
+            typeof currentDocumentVersion === 'number' &&
+            eventDocumentVersion < currentDocumentVersion) {
+            return;
+        }
+        if (react_native_1.Platform.OS === 'android' &&
+            typeof currentDocumentVersion === 'number' &&
+            typeof eventDocumentVersion !== 'number' &&
+            typeof event.nativeEvent.updateJson !== 'string') {
+            return;
+        }
+        if (!syncPreflightUpdateFromNativeEvent(event.nativeEvent.updateJson)) {
+            return;
+        }
         if (event.nativeEvent.key === LINK_TOOLBAR_ACTION_KEY) {
             openLinkRequest();
             return;
@@ -1015,7 +1726,12 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
             return;
         }
         onToolbarAction?.(event.nativeEvent.key);
-    }, [onToolbarAction, openImageRequest, openLinkRequest]);
+    }, [
+        onToolbarAction,
+        openImageRequest,
+        openLinkRequest,
+        syncPreflightUpdateFromNativeEvent,
+    ]);
     const resolveMentionSelectionAttrs = (0, react_1.useCallback)((selectionEvent) => {
         let resolvedAttrs;
         try {
@@ -1056,23 +1772,88 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
             bridgeRef.current.isDestroyed) {
             return;
         }
-        const attrs = resolveMentionInsertionAttrs({
-            trigger: mentionQuery.trigger,
-            suggestion,
-            attrs: resolveMentionSuggestionAttrs(suggestion, mentionQuery.trigger),
-            range: mentionQuery.range,
-        });
-        const update = runAndApply(() => bridgeRef.current?.insertContentJsonAtSelectionScalar(mentionQuery.range.anchor, mentionQuery.range.head, (0, addons_1.buildMentionFragmentJson)(attrs)) ?? null);
-        if (update) {
-            setMentionQueryEvent(null);
+        const currentDocumentVersion = documentVersionRef.current;
+        if (typeof mentionQuery.documentVersion === 'number' &&
+            typeof currentDocumentVersion === 'number' &&
+            mentionQuery.documentVersion < currentDocumentVersion) {
+            setMentionQueryEventState(null);
+            return;
+        }
+        let attrs = null;
+        const requestDocumentVersion = typeof mentionQuery.documentVersion === 'number'
+            ? mentionQuery.documentVersion
+            : currentDocumentVersion;
+        const retryScope = {
+            editorId: bridgeRef.current.editorId,
+            documentVersion: requestDocumentVersion,
+            mentionQuery,
+        };
+        let queuedRetry = false;
+        let retry = null;
+        const finishSelection = (selectedAttrs) => {
+            setMentionQueryEventState(null);
             mentions.onSelect?.({
                 trigger: mentionQuery.trigger,
                 suggestion,
-                attrs,
+                attrs: selectedAttrs,
+                ...(typeof mentionQuery.documentVersion === 'number'
+                    ? { documentVersion: mentionQuery.documentVersion }
+                    : {}),
+            });
+        };
+        const attemptInsertion = () => {
+            if (!isCommandRetryScopeCurrent(retryScope))
+                return false;
+            attrs = null;
+            const update = runAndApply(() => bridgeRef.current?.insertContentJsonAtSelectionScalarLazy(mentionQuery.range.anchor, mentionQuery.range.head, () => {
+                attrs = resolveMentionInsertionAttrs({
+                    trigger: mentionQuery.trigger,
+                    suggestion,
+                    attrs: resolveMentionSuggestionAttrs(suggestion, mentionQuery.trigger),
+                    range: mentionQuery.range,
+                    ...(typeof mentionQuery.documentVersion === 'number'
+                        ? { documentVersion: mentionQuery.documentVersion }
+                        : {}),
+                });
+                return (0, addons_1.buildMentionFragmentJson)(attrs);
+            }) ?? null, {
+                retryBlockedCommand: () => retry?.() === true,
+                onBlockedCommandRetryQueued: () => {
+                    queuedRetry = true;
+                },
             });
+            if (update && attrs) {
+                finishSelection(attrs);
+                return true;
+            }
+            return false;
+        };
+        retry = attemptInsertion;
+        if (attemptInsertion()) {
+            return;
+        }
+        if (queuedRetry) {
+            return;
         }
-    }, [resolveMentionInsertionAttrs, runAndApply]);
+        const latestMentionQuery = mentionQueryEventRef.current;
+        if (latestMentionQuery == null ||
+            (latestMentionQuery.trigger === mentionQuery.trigger &&
+                latestMentionQuery.query === mentionQuery.query &&
+                latestMentionQuery.range.anchor === mentionQuery.range.anchor &&
+                latestMentionQuery.range.head === mentionQuery.range.head &&
+                latestMentionQuery.documentVersion === mentionQuery.documentVersion)) {
+            setMentionQueryEventState(null);
+        }
+    }, [
+        isCommandRetryScopeCurrent,
+        resolveMentionInsertionAttrs,
+        runAndApply,
+        setMentionQueryEventState,
+    ]);
     const handleAddonEvent = (0, react_1.useCallback)((event) => {
+        const bridge = bridgeRef.current;
+        if (!isCurrentNativeEditorEvent(event.nativeEvent, bridge))
+            return;
         let parsed = null;
         try {
             parsed = JSON.parse(event.nativeEvent.eventJson);
@@ -1082,44 +1863,105 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
         }
         if (!parsed)
             return;
+        let parsedDocumentVersion = typeof parsed.documentVersion === 'number' ? parsed.documentVersion : undefined;
+        if (typeof parsedDocumentVersion !== 'number' &&
+            parsed.type === 'mentionsSelectRequest' &&
+            typeof parsed.updateJson === 'string') {
+            try {
+                const parsedUpdate = JSON.parse(parsed.updateJson);
+                if (typeof parsedUpdate.documentVersion === 'number') {
+                    parsedDocumentVersion = parsedUpdate.documentVersion;
+                }
+            }
+            catch {
+                return;
+            }
+        }
+        const currentDocumentVersion = documentVersionRef.current;
+        const isStaleAddonEvent = typeof parsedDocumentVersion === 'number' &&
+            typeof currentDocumentVersion === 'number' &&
+            parsedDocumentVersion < currentDocumentVersion;
+        const isVersionlessAndroidAddonEvent = react_native_1.Platform.OS === 'android' &&
+            typeof currentDocumentVersion === 'number' &&
+            typeof parsedDocumentVersion !== 'number';
         if (parsed.type === 'mentionsQueryChange') {
+            if (isStaleAddonEvent || isVersionlessAndroidAddonEvent)
+                return;
             const nextEvent = {
                 query: parsed.query,
                 trigger: parsed.trigger,
                 range: parsed.range,
                 isActive: parsed.isActive,
+                documentVersion: parsedDocumentVersion,
             };
-            setMentionQueryEvent(parsed.isActive ? nextEvent : null);
+            setMentionQueryEventState(parsed.isActive ? nextEvent : null, event.nativeEvent.editorId ?? bridgeRef.current?.editorId ?? null);
             addonsRef.current?.mentions?.onQueryChange?.({
                 query: nextEvent.query,
                 trigger: nextEvent.trigger,
                 range: nextEvent.range,
                 isActive: nextEvent.isActive,
+                ...(typeof nextEvent.documentVersion === 'number'
+                    ? { documentVersion: nextEvent.documentVersion }
+                    : {}),
             });
             return;
         }
         if (parsed.type === 'mentionsSelectRequest') {
-            const suggestion = mentionSuggestionsByKeyRef.current.get(parsed.suggestionKey);
-            if (!suggestion || !bridgeRef.current || bridgeRef.current.isDestroyed)
+            if (isStaleAddonEvent || isVersionlessAndroidAddonEvent)
                 return;
-            const selectionEvent = {
+            const requestDocumentVersion = typeof parsedDocumentVersion === 'number'
+                ? parsedDocumentVersion
+                : currentDocumentVersion;
+            const nativeMentionSelectRequest = {
                 trigger: parsed.trigger,
-                suggestion,
-                attrs: parsed.attrs,
+                suggestionKey: parsed.suggestionKey,
                 range: parsed.range,
             };
-            const finalAttrs = resolveMentionInsertionAttrs(selectionEvent);
-            const update = runAndApply(() => bridgeRef.current?.insertContentJsonAtSelectionScalar(parsed.range.anchor, parsed.range.head, (0, addons_1.buildMentionFragmentJson)(finalAttrs)) ?? null);
-            if (update) {
+            if (doesLiveMentionQueryConflictWithNativeSelectRequest(nativeMentionSelectRequest, mentionQueryEventRef.current, requestDocumentVersion, currentDocumentVersion)) {
+                return;
+            }
+            if (!syncPreflightUpdateFromNativeEvent(parsed.updateJson))
+                return;
+            const suggestion = mentionSuggestionsByKeyRef.current.get(parsed.suggestionKey);
+            if (!suggestion || !bridgeRef.current || bridgeRef.current.isDestroyed)
+                return;
+            let finalAttrs = null;
+            runAndApplyWithCommandRetry({
+                editorId: bridgeRef.current.editorId,
+                documentVersion: requestDocumentVersion,
+                nativeMentionSelectRequest,
+            }, () => {
+                return (bridgeRef.current?.insertContentJsonAtSelectionScalarLazy(parsed.range.anchor, parsed.range.head, () => {
+                    const selectionEvent = {
+                        trigger: parsed.trigger,
+                        suggestion,
+                        attrs: parsed.attrs,
+                        range: parsed.range,
+                        ...(typeof parsedDocumentVersion === 'number'
+                            ? { documentVersion: parsedDocumentVersion }
+                            : {}),
+                    };
+                    const attrs = resolveMentionInsertionAttrs(selectionEvent);
+                    finalAttrs = attrs;
+                    return (0, addons_1.buildMentionFragmentJson)(attrs);
+                }) ?? null);
+            }, undefined, () => {
+                if (!finalAttrs)
+                    return;
                 addonsRef.current?.mentions?.onSelect?.({
                     trigger: parsed.trigger,
                     suggestion,
                     attrs: finalAttrs,
+                    ...(typeof parsedDocumentVersion === 'number'
+                        ? { documentVersion: parsedDocumentVersion }
+                        : {}),
                 });
-            }
+            });
             return;
         }
         if (parsed.type === 'mentionsSelect') {
+            if (isStaleAddonEvent || isVersionlessAndroidAddonEvent)
+                return;
             const suggestion = mentionSuggestionsByKeyRef.current.get(parsed.suggestionKey);
             if (!suggestion)
                 return;
@@ -1127,9 +1969,17 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
                 trigger: parsed.trigger,
                 suggestion,
                 attrs: parsed.attrs,
+                ...(typeof parsedDocumentVersion === 'number'
+                    ? { documentVersion: parsedDocumentVersion }
+                    : {}),
             });
         }
-    }, [resolveMentionInsertionAttrs, runAndApply]);
+    }, [
+        resolveMentionInsertionAttrs,
+        runAndApplyWithCommandRetry,
+        setMentionQueryEventState,
+        syncPreflightUpdateFromNativeEvent,
+    ]);
     (0, react_1.useImperativeHandle)(ref, () => ({
         focus() {
             nativeViewRef.current?.focus?.();
@@ -1192,16 +2042,25 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
         getContent() {
             if (!bridgeRef.current || bridgeRef.current.isDestroyed)
                 return '';
+            if (!prepareBridgeForExternalContentRead()) {
+                return bridgeRef.current.getCachedHtml() ?? '';
+            }
             return bridgeRef.current.getHtml();
         },
         getContentJson() {
             if (!bridgeRef.current || bridgeRef.current.isDestroyed)
                 return {};
+            if (!prepareBridgeForExternalContentRead()) {
+                return bridgeRef.current.getCachedJson() ?? {};
+            }
             return bridgeRef.current.getJson();
         },
         getTextContent() {
             if (!bridgeRef.current || bridgeRef.current.isDestroyed)
                 return '';
+            if (!prepareBridgeForExternalContentRead()) {
+                return (bridgeRef.current.getCachedHtml() ?? '').replace(/<[^>]+>/g, '');
+            }
             return bridgeRef.current.getHtml().replace(/<[^>]+>/g, '');
         },
         async getCaretRect() {
@@ -1227,7 +2086,7 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
                 return false;
             return bridgeRef.current.canRedo();
         },
-    }), [insertImage, runAndApply]);
+    }), [insertImage, prepareBridgeForExternalContentRead, runAndApply]);
     const activeMentionTrigger = mentionQueryEvent?.trigger || resolveMentionTrigger(addons);
     const activeMentionSuggestions = (0, react_1.useMemo)(() => isFocused && mentionQueryEvent != null && addons?.mentions != null
         ? filterMentionSuggestions(addons.mentions.suggestions ?? [], mentionQueryEvent.query, activeMentionTrigger)
@@ -1247,6 +2106,9 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
                 suggestion,
                 attrs: resolveMentionSuggestionAttrs(suggestion, activeMentionTrigger),
                 range: mentionQueryEvent.range,
+                ...(typeof mentionQueryEvent.documentVersion === 'number'
+                    ? { documentVersion: mentionQueryEvent.documentVersion }
+                    : {}),
             };
             const attrs = resolveMentionSelectionAttrs(selectionEvent);
             let resolvedTheme;
@@ -1414,8 +2276,7 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
                                         'rgba(0, 122, 255, 0.12)')
                                     : (suggestionTheme?.backgroundColor ??
                                         '#F2F2F7'),
-                                borderColor: suggestionTheme?.borderColor ??
-                                    'transparent',
+                                borderColor: suggestionTheme?.borderColor ?? 'transparent',
                                 borderWidth: suggestionTheme?.borderWidth ?? 0,
                                 borderRadius: suggestionTheme?.borderRadius ?? 12,
                             },
@@ -1465,7 +2326,7 @@ exports.NativeRichTextEditor = (0, react_1.forwardRef)(function NativeRichTextEd
             }), onToggleStrike: () => runAndApply(() => bridgeRef.current?.toggleMark('strike') ?? null, {
                 skipNativeApplyIfContentUnchanged: true,
             }), onToggleBulletList: () => runAndApply(() => bridgeRef.current?.toggleList('bulletList') ?? null), onToggleOrderedList: () => runAndApply(() => bridgeRef.current?.toggleList('orderedList') ?? null), onIndentList: () => runAndApply(() => bridgeRef.current?.indentListItem() ?? null), onOutdentList: () => runAndApply(() => bridgeRef.current?.outdentListItem() ?? null), onInsertHorizontalRule: () => runAndApply(() => bridgeRef.current?.insertNode('horizontalRule') ?? null), onInsertLineBreak: () => runAndApply(() => bridgeRef.current?.insertNode('hardBreak') ?? null), onUndo: () => runAndApply(() => bridgeRef.current?.undo() ?? null), onRedo: () => runAndApply(() => bridgeRef.current?.redo() ?? null) })) }));
-    return ((0, jsx_runtime_1.jsxs)(react_native_1.View, { style: [styles.container, containerStyle], children: [(0, jsx_runtime_1.jsx)(NativeEditorView, { ref: nativeViewRef, style: nativeViewStyle, editorId: editorInstanceId, placeholder: placeholder, editable: editable, autoFocus: autoFocus, autoCapitalize: autoCapitalize, autoCorrect: autoCorrect, keyboardType: keyboardType, showToolbar: showToolbar, toolbarPlacement: toolbarPlacement, heightBehavior: heightBehavior, allowImageResizing: allowImageResizing, themeJson: themeJson, addonsJson: addonsJson, toolbarItemsJson: toolbarItemsJson, remoteSelectionsJson: remoteSelectionsJson, toolbarFrameJson: toolbarFrameJson, editorUpdateJson: pendingNativeUpdate.json, editorUpdateRevision: pendingNativeUpdate.revision, onEditorUpdate: handleUpdate, onSelectionChange: handleSelectionChange, onFocusChange: handleFocusChange, onContentHeightChange: handleContentHeightChange, onToolbarAction: handleToolbarAction, onAddonEvent: handleAddonEvent }, DEV_NATIVE_VIEW_KEY), shouldRenderJsToolbar && jsToolbar] }));
+    return ((0, jsx_runtime_1.jsxs)(react_native_1.View, { style: [styles.container, containerStyle], children: [(0, jsx_runtime_1.jsx)(NativeEditorView, { ref: nativeViewRef, style: nativeViewStyle, editorId: editorInstanceId, placeholder: placeholder, editable: editable, autoFocus: autoFocus, autoCapitalize: autoCapitalize, autoCorrect: autoCorrect, keyboardType: keyboardType, showToolbar: showToolbar, toolbarPlacement: toolbarPlacement, heightBehavior: heightBehavior, allowImageResizing: allowImageResizing, themeJson: themeJson, addonsJson: addonsJson, toolbarItemsJson: toolbarItemsJson, remoteSelectionsJson: remoteSelectionsJson, toolbarFrameJson: toolbarFrameJson, editorUpdateJson: pendingNativeUpdate.json, editorUpdateEditorId: pendingNativeUpdate.editorId, editorUpdateRevision: pendingNativeUpdate.revision, onEditorUpdate: handleUpdate, onSelectionChange: handleSelectionChange, onFocusChange: handleFocusChange, onContentHeightChange: handleContentHeightChange, ...(react_native_1.Platform.OS === 'android' ? { onEditorReady: handleEditorReady } : {}), onToolbarAction: handleToolbarAction, onAddonEvent: handleAddonEvent }, DEV_NATIVE_VIEW_KEY), shouldRenderJsToolbar && jsToolbar] }));
 });
 const styles = react_native_1.StyleSheet.create({
     container: {