feat: JavaScript API 1.0.0

works on the new study screen and the previewers

Author: BrayanDSO

.prettierignore

@@ -1 +1,2 @@
+AnkiDroid/src/main/assets/scripts/ankidroid-js-api.js
 AnkiDroid/build/

AnkiDroid/src/main/assets/scripts/ankidroid-js-api.js

@@ -33,6 +33,7 @@ class MediaErrorHandler {
     private var hasExecuted = false
 
     private var automaticTtsFailureCount = 0
+    private var hasShownInvalidContractMessage = false
 
     fun processFailure(
         request: WebResourceRequest,
@@ -103,4 +104,10 @@ class MediaErrorHandler {
 
         errorHandler.invoke(error)
     }
+
+    fun shouldShowJsApiExceptionMessage(): Boolean {
+        if (hasShownInvalidContractMessage) return false
+        hasShownInvalidContractMessage = true
+        return true
+    }
 }

AnkiDroid/src/main/java/com/ichi2/anki/cardviewer/MediaErrorHandler.kt

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2025 Brayan Oliveira <[email protected]>
+ *
+ * This program is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation; either version 3 of the License, or (at your option) any later
+ * version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+package com.ichi2.anki.jsapi
+
+import kotlinx.coroutines.CompletableDeferred
+import org.json.JSONObject
+
+data class UiRequest(
+    val endpoint: Endpoint,
+    val data: JSONObject?,
+    val result: CompletableDeferred<ByteArray>,
+)

AnkiDroid/src/main/java/com/ichi2/anki/jsapi/UiRequest.kt

@@ -38,17 +38,23 @@ import androidx.lifecycle.flowWithLifecycle
 import androidx.lifecycle.lifecycleScope
 import com.ichi2.anki.R
 import com.ichi2.anki.ViewerResourceHandler
+import com.ichi2.anki.common.utils.ext.getIntOrNull
 import com.ichi2.anki.dialogs.TtsVoicesDialogFragment
+import com.ichi2.anki.jsapi.Endpoint
+import com.ichi2.anki.jsapi.JsApi
+import com.ichi2.anki.jsapi.UiRequest
 import com.ichi2.anki.localizedErrorMessage
 import com.ichi2.anki.snackbar.showSnackbar
 import com.ichi2.anki.utils.ext.collectIn
 import com.ichi2.anki.utils.ext.packageManager
 import com.ichi2.anki.utils.openUrl
 import com.ichi2.compat.CompatHelper.Companion.resolveActivityCompat
 import com.ichi2.themes.Themes
+import com.ichi2.utils.NetworkUtils
 import com.ichi2.utils.show
 import kotlinx.coroutines.flow.launchIn
 import kotlinx.coroutines.flow.onEach
+import org.json.JSONObject
 import timber.log.Timber
 
 abstract class CardViewerFragment(
@@ -64,6 +70,7 @@ abstract class CardViewerFragment(
     ) {
         setupWebView(savedInstanceState)
         setupErrorListeners()
+        setupJsApi()
     }
 
     override fun onStart() {
@@ -132,6 +139,46 @@ abstract class CardViewerFragment(
         viewModel.onTtsError
             .onEach { showSnackbar(it.localizedErrorMessage(requireContext())) }
             .launchIn(lifecycleScope)
+
+        viewModel.onJsApiError.flowWithLifecycle(lifecycle).collectIn(lifecycleScope) { error ->
+            val errorMessage = error.localizedErrorMessage(resources)
+            AlertDialog
+                .Builder(requireContext())
+                .setTitle(R.string.vague_error)
+                .setMessage(errorMessage)
+                .show()
+        }
+    }
+
+    private fun setupJsApi() {
+        viewModel.apiRequestFlow.flowWithLifecycle(lifecycle).collectIn(lifecycleScope) { request ->
+            val result = handleJsUiRequest(request)
+            request.result.complete(result)
+        }
+    }
+
+    protected open fun handleJsUiRequest(request: UiRequest): ByteArray =
+        if (request.endpoint is Endpoint.Android) {
+            handleAndroidEndpoint(request.endpoint, request.data)
+        } else {
+            JsApi.fail("Unhandled endpoint")
+        }
+
+    private fun handleAndroidEndpoint(
+        endpoint: Endpoint.Android,
+        data: JSONObject?,
+    ): ByteArray {
+        return when (endpoint) {
+            Endpoint.Android.SHOW_SNACKBAR -> {
+                val data = data ?: return JsApi.fail("Missing request data")
+                val text = data.optString("text") ?: return JsApi.fail("Missing text")
+                val duration = data.getIntOrNull("duration") ?: return JsApi.fail("Missing duration")
+                showSnackbar(text, duration)
+                JsApi.success()
+            }
+            Endpoint.Android.IS_SYSTEM_IN_DARK_MODE -> JsApi.success(Themes.systemIsInNightMode(requireContext()))
+            Endpoint.Android.IS_NETWORK_METERED -> JsApi.success(NetworkUtils.isActiveNetworkMetered())
+        }
     }
 
     protected open fun onCreateWebViewClient(savedInstanceState: Bundle?): WebViewClient = CardViewerWebViewClient(savedInstanceState)

AnkiDroid/src/main/java/com/ichi2/anki/previewer/CardViewerFragment.kt

@@ -27,18 +27,26 @@ import com.ichi2.anki.cardviewer.CardMediaPlayer
 import com.ichi2.anki.cardviewer.MediaErrorBehavior
 import com.ichi2.anki.cardviewer.MediaErrorHandler
 import com.ichi2.anki.cardviewer.MediaErrorListener
+import com.ichi2.anki.jsapi.Endpoint
+import com.ichi2.anki.jsapi.InvalidContractException
+import com.ichi2.anki.jsapi.JsApi
+import com.ichi2.anki.jsapi.JsApi.getEndpoint
+import com.ichi2.anki.jsapi.UiRequest
 import com.ichi2.anki.launchCatchingIO
 import com.ichi2.anki.libanki.Card
 import com.ichi2.anki.libanki.TtsPlayer
 import com.ichi2.anki.multimedia.getAvTag
 import com.ichi2.anki.multimedia.replaceAvRefsWithPlayButtons
 import com.ichi2.anki.pages.AnkiServer
 import com.ichi2.anki.pages.PostRequestHandler
+import kotlinx.coroutines.CompletableDeferred
 import kotlinx.coroutines.Deferred
 import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.withTimeoutOrNull
 import kotlinx.serialization.json.Json
+import org.json.JSONObject
 import timber.log.Timber
 
 abstract class CardViewerViewModel :
@@ -48,9 +56,11 @@ abstract class CardViewerViewModel :
     override val onError = MutableSharedFlow<String>()
     val onMediaError = MutableSharedFlow<String>()
     val onTtsError = MutableSharedFlow<TtsPlayer.TtsError>()
+    val onJsApiError = MutableSharedFlow<InvalidContractException>()
     val mediaErrorHandler = MediaErrorHandler()
 
     val eval = MutableSharedFlow<String>()
+    val apiRequestFlow = MutableSharedFlow<UiRequest>()
 
     open val showingAnswer = MutableStateFlow(false)
 
@@ -200,7 +210,44 @@ abstract class CardViewerViewModel :
                 "i18nResources" -> withCol { i18nResourcesRaw(bytes) }
                 else -> throw IllegalArgumentException("Unhandled Anki request: $uri")
             }
+        } else if (uri.startsWith(JsApi.REQUEST_PREFIX)) {
+            handleJsRequest(uri, bytes)
         } else {
             throw IllegalArgumentException("Unhandled POST request: $uri")
         }
+
+    private suspend fun handleJsRequest(
+        uri: String,
+        bytes: ByteArray,
+    ): ByteArray {
+        val requestData =
+            try {
+                JsApi.parseRequest(bytes)
+            } catch (exception: InvalidContractException) {
+                if (mediaErrorHandler.shouldShowJsApiExceptionMessage()) {
+                    onJsApiError.emit(exception)
+                }
+                return JsApi.fail("Invalid contract")
+            }
+
+        val endpoint = getEndpoint(uri) ?: return JsApi.fail("Invalid endpoint")
+        return handleJsEndpoint(endpoint, requestData)
+    }
+
+    protected open suspend fun handleJsEndpoint(
+        endpoint: Endpoint,
+        data: JSONObject?,
+    ): ByteArray =
+        if (endpoint is Endpoint.Android) {
+            val result = CompletableDeferred<ByteArray>()
+            val request = UiRequest(endpoint, data, result)
+            apiRequestFlow.emit(request)
+            // there may be no listeners for the flow, so fail the result after some time
+            // e.g. the fragment uses flowWithLifecycle and is at a different lifecycleState
+            withTimeoutOrNull(2000L) {
+                result.await()
+            } ?: JsApi.fail("Method was not handled")
+        } else {
+            JsApi.handleEndpointRequest(endpoint, data, currentCard.await())
+        }
 }

AnkiDroid/src/main/java/com/ichi2/anki/previewer/CardViewerViewModel.kt

@@ -54,6 +54,7 @@ fun stdHtml(
             "backend/js/mathjax.js",
             "backend/js/vendor/mathjax/tex-chtml-full.js",
             "backend/js/reviewer.js",
+            "scripts/ankidroid-js-api.js",
         ) + extraJsAssets
     val jsTxt =
         jsAssets.joinToString("\n") {

AnkiDroid/src/main/java/com/ichi2/anki/previewer/PreviewerHelpers.kt

@@ -41,6 +41,7 @@ import androidx.constraintlayout.widget.ConstraintSet
 import androidx.coordinatorlayout.widget.CoordinatorLayout
 import androidx.core.content.ContextCompat
 import androidx.core.content.getSystemService
+import androidx.core.graphics.toColorInt
 import androidx.core.view.ViewCompat
 import androidx.core.view.WindowInsetsCompat
 import androidx.core.view.WindowInsetsControllerCompat
@@ -70,6 +71,9 @@ import com.ichi2.anki.common.utils.android.isRobolectric
 import com.ichi2.anki.dialogs.tags.TagsDialog
 import com.ichi2.anki.dialogs.tags.TagsDialogFactory
 import com.ichi2.anki.dialogs.tags.TagsDialogListener
+import com.ichi2.anki.jsapi.Endpoint
+import com.ichi2.anki.jsapi.JsApi
+import com.ichi2.anki.jsapi.UiRequest
 import com.ichi2.anki.libanki.sched.Counts
 import com.ichi2.anki.model.CardStateFilter
 import com.ichi2.anki.preferences.reviewer.ReviewerMenuView
@@ -663,6 +667,25 @@ class ReviewerFragment :
         stateFilter: CardStateFilter,
     ) = viewModel.onEditedTags(selectedTags)
 
+    override fun handleJsUiRequest(request: UiRequest): ByteArray {
+        val result: ByteArray? =
+            when (request.endpoint) {
+                Endpoint.StudyScreen.SET_BACKGROUND_COLOR -> {
+                    val colorHex = request.data?.optString("colorHex") ?: return JsApi.fail("Missing hex code")
+                    val color =
+                        try {
+                            colorHex.toColorInt()
+                        } catch (_: IllegalArgumentException) {
+                            return JsApi.fail("Invalid hex code")
+                        }
+                    view?.setBackgroundColor(color)
+                    JsApi.success()
+                }
+                else -> null
+            }
+        return result ?: super.handleJsUiRequest(request)
+    }
+
     override fun onCreateWebViewClient(savedInstanceState: Bundle?): WebViewClient = ReviewerWebViewClient(savedInstanceState)
 
     private inner class ReviewerWebViewClient(