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

package/android/src/main/java/com/apollohg/editor/EditorV2AdapterSelection.kt

@@ -0,0 +1,203 @@
+package com.apollohg.editor
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+internal sealed interface SelectionSyncOutcome {
+    object Ok : SelectionSyncOutcome
+    data class Refreshed(val updateJson: String) : SelectionSyncOutcome
+    object Failed : SelectionSyncOutcome
+}
+
+internal fun EditorV2Adapter.clampScalar(scalar: Int): Int {
+    val extent = cachedScalarLength ?: return scalar
+    return scalar.coerceIn(0, extent)
+}
+
+internal fun EditorV2Adapter.selectAtomNode(docPos: Int): String? {
+    val selection = JSONObject().put("type", "atom").put("docPos", docPos).put("edge", "node")
+    return when (
+        val result = callWithEnvelope(JSONObject().put("selection", selection)) {
+            backend.setSelection(editorId, it)
+        }
+    ) {
+        is EditorV2CallResult.Err -> handleMutationError(result.error)
+
+        is EditorV2CallResult.Ok -> {
+            invalidateCachedAtomicState(null)
+            recoverNativeRender()
+        }
+    }
+}
+
+internal fun EditorV2Adapter.invalidateCachedAtomicState(selection: IntArray?) {
+    cachedAuthoritativeScalarSelection = selection?.copyOf()
+    cachedScalarLength = null
+    cachedActiveState = null
+    cachedHistoryState = null
+    cachedViewUpdateJson = null
+    cachedAtomicRenderJson = null
+    cachedAtomicRenderDocumentRevision = null
+}
+
+internal fun EditorV2Adapter.ensureSelection(anchor: Int, head: Int): SelectionSyncOutcome {
+    val clampedAnchor = clampScalar(anchor)
+    val clampedHead = clampScalar(head)
+    val last = lastSyncedScalarSelection
+    if (last != null && last[0] == clampedAnchor && last[1] == clampedHead) {
+        return SelectionSyncOutcome.Ok
+    }
+    // Affinity policy mirrors the engine's own cursor resolution: a
+    // collapsed caret prefers After with a deterministic Before fallback
+    // at text-boundary positions; a range uses Before. The fallback
+    // changes only the stickiness of the SAME position.
+    val collapsed = clampedAnchor == clampedHead
+    var result = callWithEnvelope(
+        selectionEnvelope(clampedAnchor, clampedHead, if (collapsed) "after" else "before")
+    ) { requestJson ->
+        backend.setSelection(editorId, requestJson)
+    }
+    if (collapsed &&
+        result is EditorV2CallResult.Err &&
+        result.error.code == "POSITION_INVALID"
+    ) {
+        result =
+            callWithEnvelope(
+                selectionEnvelope(clampedAnchor, clampedHead, "before")
+            ) { requestJson ->
+                backend.setSelection(editorId, requestJson)
+            }
+    }
+    return when (result) {
+        is EditorV2CallResult.Ok -> {
+            parseMutationOutcome(result.value)?.let { outcome ->
+                if (outcome is MutationOutcome.Transaction) {
+                    baseDocumentRevision = outcome.revision
+                }
+            }
+            val synchronizedSelection = intArrayOf(clampedAnchor, clampedHead)
+            lastSyncedScalarSelection = synchronizedSelection
+            cachedAuthoritativeScalarSelection = synchronizedSelection.copyOf()
+            // Selection changes can affect active state and state revision,
+            // but retain the last atomic history result until a document
+            // mutation supplies its next locked snapshot.
+            cachedActiveState = null
+            cachedViewUpdateJson = null
+            cachedAtomicRenderJson = null
+            cachedAtomicRenderDocumentRevision = null
+            SelectionSyncOutcome.Ok
+        }
+
+        is EditorV2CallResult.Err -> {
+            if (result.error.code == "REVISION_MISMATCH") {
+                val update = refreshInternal(null, stripViewSelection = false)
+                if (update != null) {
+                    SelectionSyncOutcome.Refreshed(update)
+                } else {
+                    SelectionSyncOutcome.Failed
+                }
+            } else {
+                emit(result.error)
+                SelectionSyncOutcome.Failed
+            }
+        }
+    }
+}
+
+internal fun EditorV2Adapter.textDocumentSelection(updateJson: String): IntArray? {
+    return try {
+        val selection = JSONObject(updateJson).getJSONObject("selection")
+        if (selection.optString("type") != "text") return null
+        intArrayOf(
+            scalarField(selection, "anchor") ?: return null,
+            scalarField(selection, "head") ?: return null
+        )
+    } catch (error: Exception) {
+        null
+    }
+}
+
+internal fun EditorV2Adapter.resolveSelectionMapping(anchor: Int, head: Int): IntArray? {
+    // Engine-authoritative scalar→doc selection mapping for the delegate
+    // callback's doc positions (v2 accessor).
+    val resolved = when (val result = backend.resolveScalarSelection(editorId, anchor, head)) {
+        is EditorV2CallResult.Err -> {
+            debugNotes.add("resolveScalarSelection ${result.error.domain}/${result.error.code}")
+            return null
+        }
+
+        is EditorV2CallResult.Ok -> result.value
+    }
+    return try {
+        val selection = JSONObject(resolved)
+        intArrayOf(
+            scalarField(selection, "anchor") ?: return null,
+            scalarField(selection, "head") ?: return null
+        )
+    } catch (error: Exception) {
+        null
+    }
+}
+
+internal fun EditorV2Adapter.publishCachedCollaborationSelection() {
+    if (!roomBound) return
+    val selection = cachedAuthoritativeScalarSelection ?: return
+    val mapping = resolveSelectionMapping(selection[0], selection[1]) ?: return
+    publishCollaborationSelection(mapping[0], mapping[1])
+}
+
+internal fun EditorV2Adapter.publishCollaborationSelection(docAnchor: Int, docHead: Int) {
+    if (!roomBound) return
+    val selectionJson = JSONObject()
+        .put("type", "text")
+        .put("anchor", docAnchor)
+        .put("head", docHead)
+        .toString()
+    when (
+        val result = backend.collaborationSetAwarenessSelection(
+            editorId,
+            selectionJson
+        )
+    ) {
+        is EditorV2CallResult.Err -> emit(result.error)
+
+        is EditorV2CallResult.Ok -> {
+            val outboundChanged = try {
+                val value = JSONObject(result.value)
+                if (value.length() != 1 ||
+                    !value.has("outboundChanged") ||
+                    value.opt("outboundChanged") !is Boolean
+                ) {
+                    null
+                } else {
+                    value.getBoolean("outboundChanged")
+                }
+            } catch (error: Exception) {
+                null
+            }
+            if (outboundChanged == null) {
+                emit(
+                    EditorV2Adapter.contractError(
+                        "awareness selection result violates the frozen shape"
+                    )
+                )
+            } else if (outboundChanged) {
+                collaborationWake(editorId, CollaborationWakeReason.AWARENESS)
+            }
+        }
+    }
+}
+
+internal fun EditorV2Adapter.mapPosition(result: EditorV2CallResult<String>, key: String): Int? =
+    when (result) {
+        is EditorV2CallResult.Err -> {
+            emit(result.error)
+            null
+        }
+
+        is EditorV2CallResult.Ok -> try {
+            scalarField(JSONObject(result.value), key)
+        } catch (error: Exception) {
+            null
+        }
+    }

package/android/src/main/java/com/apollohg/editor/EditorV2Backend.kt

@@ -0,0 +1,120 @@
+package com.apollohg.editor
+
+/**
+ * The v2 backend contract: the v2 engine verbs plus the v2
+ * render/selection/position accessor. The production implementation
+ * (`UniffiEditorV2Backend`) calls the real `editorV2*` UniFFI entries;
+ * tests substitute `FakeEditorV2Backend`.
+ */
+internal data class EditorV2Error(
+    val domain: String,
+    val code: String,
+    val message: String,
+    val requestId: String? = null,
+    val operationIndex: String? = null,
+    val limit: String? = null,
+    val actual: String? = null,
+    val detailsJson: String? = null
+)
+
+internal sealed interface EditorV2CallResult<out T> {
+    data class Ok<T>(val value: T) : EditorV2CallResult<T>
+    data class Err(val error: EditorV2Error) : EditorV2CallResult<Nothing>
+}
+
+internal data class EditorV2OutboundLease(val leaseId: String, val frame: ByteArray)
+
+internal sealed interface EditorV2LeaseResult {
+    data class Value(val lease: EditorV2OutboundLease) : EditorV2LeaseResult
+    data object Empty : EditorV2LeaseResult
+    data class Err(val error: EditorV2Error) : EditorV2LeaseResult
+}
+
+internal interface EditorV2Backend {
+    fun create(configJson: String, snapshotState: ByteArray?): EditorV2CallResult<String>
+    fun destroy(editorId: String): EditorV2Error?
+    fun getState(editorId: String): EditorV2CallResult<String>
+    fun getDocumentJson(editorId: String): EditorV2CallResult<String>
+    fun getDocumentHtml(editorId: String): EditorV2CallResult<String>
+    fun getContentSnapshot(editorId: String): EditorV2CallResult<String>
+    fun applyInput(editorId: String, requestJson: String): EditorV2CallResult<String>
+    fun applyCommand(editorId: String, requestJson: String): EditorV2CallResult<String>
+    fun applyLocalApi(editorId: String, requestJson: String): EditorV2CallResult<String>
+    fun replaceDocument(editorId: String, requestJson: String): EditorV2CallResult<String>
+    fun setSelection(editorId: String, requestJson: String): EditorV2CallResult<String>
+    fun undo(editorId: String, requestJson: String): EditorV2CallResult<String>
+    fun redo(editorId: String, requestJson: String): EditorV2CallResult<String>
+    fun collaborationDrive(editorId: String, nowMillis: String): EditorV2CallResult<String>
+    fun collaborationSocketOpen(
+        editorId: String,
+        generation: String,
+        nowMillis: String
+    ): EditorV2CallResult<String>
+    fun collaborationReceive(
+        editorId: String,
+        generation: String,
+        message: ByteArray,
+        nowMillis: String
+    ): EditorV2CallResult<String>
+    fun collaborationSocketClose(
+        editorId: String,
+        generation: String,
+        code: UInt?,
+        reason: String?,
+        nowMillis: String
+    ): EditorV2CallResult<String>
+    fun collaborationLeaseOutbound(editorId: String, generation: String): EditorV2LeaseResult
+    fun collaborationAckOutbound(
+        editorId: String,
+        generation: String,
+        leaseId: String
+    ): EditorV2CallResult<String>
+    fun collaborationNackOutbound(
+        editorId: String,
+        generation: String,
+        leaseId: String
+    ): EditorV2CallResult<String>
+    fun collaborationDetach(editorId: String): EditorV2Error?
+    fun collaborationReattach(editorId: String): EditorV2Error?
+    fun collaborationPeers(editorId: String): EditorV2CallResult<String>
+    fun collaborationSetAwarenessSelection(
+        editorId: String,
+        selectionJson: String
+    ): EditorV2CallResult<String>
+    fun snapshotExport(editorId: String): EditorV2CallResult<Pair<String, ByteArray>>
+
+    /**
+     * The v2 render accessor: from the LIVE v2 session produce the
+     * complete locked atomic snapshot: render blocks/patch, selection,
+     * active/history state, canonical document/state revisions, and scalar
+     * extent. The adapter must parse and adopt this one result as-is; it
+     * must never stitch it to a separate `getState` response.
+     */
+    fun renderUpdate(
+        editorId: String,
+        mirrorAnchor: Int?,
+        mirrorHead: Int?
+    ): EditorV2CallResult<String>
+    fun renderNative(
+        editorId: String,
+        ownerId: String,
+        mirrorAnchor: Int?,
+        mirrorHead: Int?
+    ): EditorV2CallResult<String>
+    fun pinPositionEpoch(
+        editorId: String,
+        ownerId: String,
+        documentRevision: String
+    ): EditorV2CallResult<String>
+    fun applyNativeIntent(editorId: String, requestJson: String): EditorV2CallResult<String>
+    fun releaseNativeBinding(editorId: String, ownerId: String): EditorV2Error?
+
+    /** Engine-authoritative scalar→doc selection resolution for one session. */
+    fun resolveScalarSelection(editorId: String, anchor: Int, head: Int): EditorV2CallResult<String>
+
+    /** Lenient doc→scalar mapping (clamps at the document extent). */
+    fun docToScalar(editorId: String, docPos: Int): EditorV2CallResult<String>
+
+    /** Lenient scalar→doc mapping (clamps at the document extent). */
+    fun scalarToDoc(editorId: String, scalar: Int): EditorV2CallResult<String>
+}

package/android/src/main/java/com/apollohg/editor/EditorV2Driver.kt

@@ -0,0 +1,87 @@
+package com.apollohg.editor
+
+/**
+ * Render returned by a block-split request. A refresh-only render keeps the
+ * native view coherent but must not be treated as a locally committed split.
+ */
+internal data class EditorV2SplitRender(val updateJson: String, val committed: Boolean)
+
+internal data class EditorV2SelectionSync(
+    val docAnchor: Int,
+    val docHead: Int,
+    val refreshedUpdateJson: String?
+)
+
+internal data class EditorV2NativeMutationRender(
+    val updateJson: String,
+    val changed: Boolean,
+    val documentChanged: Boolean
+)
+
+internal sealed interface EditorV2NativeIntentResult {
+    data class Applied(val render: EditorV2NativeMutationRender) : EditorV2NativeIntentResult
+    data class Recovered(val updateJson: String) : EditorV2NativeIntentResult
+    data object Rejected : EditorV2NativeIntentResult
+}
+
+/**
+ * The v2 driver: the ONLY engine path for views.
+ *
+ * The views call this interface for every engine interaction; the legacy
+ * UniFFI free functions are gone. `EditorV2Adapter` supplies the
+ * implementation, whose typed v2 transactions/results are the only engine
+ * traffic for paired editors.
+ */
+internal interface EditorV2Driver {
+    fun insertText(text: String, atScalarPos: Int): String?
+    fun replaceTextRange(scalarFrom: Int, scalarTo: Int, text: String): String?
+    fun deleteScalarRange(scalarFrom: Int, scalarTo: Int): String?
+    fun replaceTextRangeNative(
+        scalarFrom: Int,
+        scalarTo: Int,
+        text: String
+    ): EditorV2NativeIntentResult
+    fun deleteScalarRangeNative(scalarFrom: Int, scalarTo: Int): EditorV2NativeIntentResult
+    fun deleteBackwardAtSelection(anchor: Int, head: Int): String?
+    fun splitBlockAt(scalarPos: Int): EditorV2SplitRender?
+    fun deleteAndSplit(scalarFrom: Int, scalarTo: Int): EditorV2SplitRender?
+    fun moveSelection(anchor: Int, head: Int, destination: Int): String?
+
+    fun insertNode(nodeType: String, anchor: Int, head: Int): String?
+    fun insertContentHtmlAtSelection(html: String, anchor: Int, head: Int): String?
+    fun insertContentJsonAtSelection(json: String, anchor: Int, head: Int): String?
+    fun toggleMark(markName: String, anchor: Int, head: Int): String?
+    fun setMark(markName: String, attrsJson: String, anchor: Int, head: Int): String?
+    fun unsetMark(markName: String, anchor: Int, head: Int): String?
+    fun toggleHeading(level: Int, anchor: Int, head: Int): String?
+    fun toggleCodeBlock(anchor: Int, head: Int): String?
+    fun toggleBlockquote(anchor: Int, head: Int): String?
+    fun wrapInList(listType: String, anchor: Int, head: Int): String?
+    fun unwrapFromList(anchor: Int, head: Int): String?
+    fun indentListItem(anchor: Int, head: Int): String?
+    fun outdentListItem(anchor: Int, head: Int): String?
+    fun toggleTaskItemCheckedAtSelection(anchor: Int, head: Int): String?
+    fun resizeImageAtDocPos(docPos: Int, width: Int, height: Int): String?
+
+    fun undo(): String?
+    fun redo(): String?
+
+    fun syncSelection(anchor: Int, head: Int): EditorV2SelectionSync?
+    fun syncSelectionQuiet(anchor: Int, head: Int): String?
+    fun scalarPositionForDoc(docPos: Int): Int?
+    fun docPositionForScalar(scalar: Int): Int?
+
+    fun currentStateJson(): String?
+    fun documentHtml(): String?
+    fun documentJson(): String?
+    fun contentSnapshotJson(): String?
+    fun historyCanUndo(): Boolean?
+    fun historyCanRedo(): Boolean?
+    fun selectionJson(): String?
+
+    fun setContentHtml(html: String): String?
+    fun setContentJson(json: String): String?
+
+    /** Stale-revision recovery: refresh from Rust state, never retry the failed op. */
+    fun refreshFromRustState(mirrorSelection: IntArray?): String?
+}

package/android/src/main/java/com/apollohg/editor/EditorV2Registry.kt

@@ -0,0 +1,97 @@
+package com.apollohg.editor
+
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicLong
+
+internal enum class EditorV2DestroyReservationResult {
+    RESERVED,
+    ALREADY_IN_PROGRESS
+}
+
+internal fun <T> invokeDestroyTestingHook(hook: ((T) -> Unit)?, value: T) {
+    try {
+        hook?.invoke(value)
+    } catch (_: Throwable) {
+        // Destroy test hooks are observational and cannot alter the transaction.
+    }
+}
+
+/**
+ * The v2 pairing registry keeps the public editor handle as its canonical
+ * decimal string. A separate, opaque view token exists only for the Android
+ * widget lifecycle; it never crosses the JS/native or native/Rust boundary.
+ */
+internal object EditorV2Registry {
+    private data class Pairing(
+        val handle: String,
+        val viewToken: Long,
+        val adapter: EditorV2Adapter
+    )
+
+    private val pairingsByHandle = ConcurrentHashMap<String, Pairing>()
+    private val pairingsByViewToken = ConcurrentHashMap<Long, Pairing>()
+    private val destroyingHandles = ConcurrentHashMap.newKeySet<String>()
+    private val nextViewToken = AtomicLong(0)
+
+    @Volatile
+    internal var onHandleDestroyReservationAcquiredForTesting: ((String) -> Unit)? = null
+
+    @Volatile
+    internal var onDestroyFfiResultReceivedForTesting: ((String) -> Unit)? = null
+
+    @Volatile
+    internal var onPairRemovedBeforeDestroyFinalizationForTesting: ((String) -> Unit)? = null
+
+    fun register(adapter: EditorV2Adapter): Long {
+        val token = nextViewToken.incrementAndGet()
+        check(token > 0L) { "native editor view token overflow" }
+        val pairing = Pairing(adapter.editorId, token, adapter)
+        pairingsByHandle[adapter.editorId] = pairing
+        pairingsByViewToken[token] = pairing
+        return token
+    }
+
+    fun viewTokenForHandle(handle: String): Long? = pairingsByHandle[handle]?.viewToken
+
+    /**
+     * The public v2 handle owns the destroy transaction. It is deliberately
+     * separate from the mutable pairing so contenders still observe the
+     * transaction after the owner has removed that pairing.
+     */
+    fun acquireHandleDestroyReservation(handle: String): EditorV2DestroyReservationResult {
+        if (!destroyingHandles.add(handle)) {
+            return EditorV2DestroyReservationResult.ALREADY_IN_PROGRESS
+        }
+        invokeDestroyTestingHook(onHandleDestroyReservationAcquiredForTesting, handle)
+        return EditorV2DestroyReservationResult.RESERVED
+    }
+
+    fun releaseHandleDestroyReservation(handle: String) {
+        destroyingHandles.remove(handle)
+    }
+
+    internal fun isHandleDestroyReservedForTesting(handle: String): Boolean =
+        destroyingHandles.contains(handle)
+
+    fun adapterForViewToken(viewToken: Long): EditorV2Adapter? =
+        pairingsByViewToken[viewToken]?.adapter
+
+    fun handleForViewToken(viewToken: Long): String? = pairingsByViewToken[viewToken]?.handle
+
+    /** Cancel view-owned callbacks without releasing the pairing itself. */
+    fun cancelAutonomousErrorOwner(handle: String) {
+        pairingsByHandle[handle]?.adapter?.releaseAutonomousErrorOwner()
+    }
+
+    fun remove(handle: String): EditorV2Adapter? {
+        val pairing = pairingsByHandle.remove(handle) ?: return null
+        pairingsByViewToken.remove(pairing.viewToken)
+        pairing.adapter.releaseAutonomousErrorOwner()
+        return pairing.adapter
+    }
+
+    /** Drop a pairing after the public v2 destroy entry has handled its session. */
+    fun dropPair(handle: String) {
+        remove(handle)
+    }
+}