craft-native 0.0.104 → 0.0.107

package/dist/android/src/index.d.ts

@@ -8,6 +8,7 @@ export declare const ANDROID_MIN_SDK = 26;
 export interface CraftAndroidConfig {
     appName: string;
     packageName: string;
+    renderer?: 'web' | 'native';
     version?: string;
     versionCode?: number;
     darkMode?: boolean;
@@ -51,6 +52,7 @@ export interface InitOptions {
 }
 export interface BuildOptions {
     htmlPath?: string;
+    nativeBundlePath?: string;
     devServer?: string;
     output: string;
     release?: boolean;

package/dist/android/src/index.js

@@ -112,6 +112,7 @@ var KOTLIN_KEYWORDS = new Set([
 ]);
 var ANDROID_MIN_SDK = 26;
 var DEFAULT_CONFIG = {
+  renderer: "web",
   version: "1.0.0",
   versionCode: 1,
   darkMode: true,
@@ -212,6 +213,9 @@ function normalizeAndroidNetworkConfig(config) {
 function validateAndroidConfig(config) {
   if (!config.appName.trim())
     throw new Error("Android app name must not be empty");
+  if (config.renderer !== undefined && config.renderer !== "web" && config.renderer !== "native") {
+    throw new Error(`Unknown Android renderer: ${config.renderer}. Expected web or native.`);
+  }
   const packageSegments = config.packageName.split(".");
   if (packageSegments.length < 2 || packageSegments.some((segment) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(segment) || KOTLIN_KEYWORDS.has(segment))) {
     throw new Error(`Invalid Android package name: ${config.packageName}`);
@@ -408,7 +412,7 @@ async function init(options) {
   if (config.googleServicesFile) {
     cpSync(config.googleServicesFile, join(output, "app/google-services.json"));
   }
-  const mainActivityTemplate = readFileSync(join(TEMPLATES_DIR, "MainActivity.kt.template"), "utf-8");
+  const mainActivityTemplate = readFileSync(join(TEMPLATES_DIR, config.renderer === "native" ? "MainActivityNative.kt.template" : "MainActivity.kt.template"), "utf-8");
   const mainActivity = mainActivityTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName).replace(/\{\{APP_NAME\}\}/g, name);
   writeFileSync(join(output, "app/src/main/java", packagePath, "MainActivity.kt"), mainActivity);
   const craftBridgeTemplate = readFileSync(join(TEMPLATES_DIR, "CraftBridge.kt.template"), "utf-8");
@@ -455,7 +459,7 @@ async function init(options) {
   writeFileSync(join(output, "build.gradle.kts"), projectGradleTemplate.replace(/\{\{GOOGLE_SERVICES_PLUGIN\}\}/g, hasGoogleServices ? '    id("com.google.gms.google-services") version "4.4.2" apply false' : ""));
   const appGradleTemplate = readFileSync(join(TEMPLATES_DIR, "build.gradle.kts.app.template"), "utf-8");
   const appGradle = appGradleTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName).replace(/\{\{VERSION_NAME\}\}/g, escapeKotlinString(config.version || "1.0.0")).replace(/\{\{VERSION_CODE\}\}/g, String(config.versionCode || 1)).replace(/\{\{MIN_SDK\}\}/g, String(config.minSdk ?? ANDROID_MIN_SDK)).replace(/\{\{COMPILE_SDK\}\}/g, String(config.compileSdk || 36)).replace(/\{\{TARGET_SDK\}\}/g, String(config.targetSdk || 35)).replace(/\{\{GOOGLE_SERVICES_PLUGIN\}\}/g, hasGoogleServices ? '    id("com.google.gms.google-services")' : "").replace(/\{\{FIREBASE_MESSAGING_DEPENDENCY\}\}/g, config.enablePushNotifications ? '    implementation("com.google.firebase:firebase-messaging:24.1.0")' : "").replace(/\{\{HEALTH_CONNECT_DEPENDENCIES\}\}/g, config.enableHealthConnect ? `    implementation("androidx.health.connect:connect-client:1.1.0")
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")` : "");
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")` : "").replace(/\{\{JAVASCRIPT_ENGINE_DEPENDENCY\}\}/g, config.renderer === "native" ? '    implementation("androidx.javascriptengine:javascriptengine:1.1.0")' : "");
   writeFileSync(join(output, "app/build.gradle.kts"), appGradle);
   const proguardTemplate = readFileSync(join(TEMPLATES_DIR, "proguard-rules.pro.template"), "utf-8");
   writeFileSync(join(output, "app/proguard-rules.pro"), proguardTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName));
@@ -519,7 +523,12 @@ zipStorePath=wrapper/dists
 </resources>
 `;
   writeFileSync(join(output, "app/src/main/res/values/themes.xml"), themesXml);
-  const activityMainXml = `<?xml version="1.0" encoding="utf-8"?>
+  const activityMainXml = config.renderer === "native" ? `<?xml version="1.0" encoding="utf-8"?>
+<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:id="@+id/native_root"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent" />
+` : `<?xml version="1.0" encoding="utf-8"?>
 <androidx.coordinatorlayout.widget.CoordinatorLayout
     xmlns:android="http://schemas.android.com/apk/res/android"
     android:layout_width="match_parent"
@@ -581,13 +590,18 @@ zipStorePath=wrapper/dists
   console.log("");
   console.log("Next steps:");
   console.log(`  1. cd ${output}`);
-  console.log("  2. Add your web content to app/src/main/assets/index.html");
-  console.log("  3. Run: craft android build");
+  if (config.renderer === "native") {
+    console.log("  2. Compile your screen: stx-native compile Screen.stx --format bundle --output screen.js");
+    console.log("  3. Run: craft android build --native-bundle screen.js");
+  } else {
+    console.log("  2. Add your web content to app/src/main/assets/index.html");
+    console.log("  3. Run: craft android build");
+  }
   console.log("  4. Run: craft android open");
   console.log("");
 }
 async function build(options) {
-  const { htmlPath, devServer, output, release, compile = true } = options;
+  const { htmlPath, nativeBundlePath, devServer, output, release, compile = true } = options;
   console.log(`
 \uD83D\uDCE6 Building Craft Android project...`);
   const configPath = join(output, "craft.config.json");
@@ -595,6 +609,19 @@ async function build(options) {
     throw new Error(`No craft.config.json found in ${output}. Run 'craft android init' first.`);
   }
   const config = JSON.parse(readFileSync(configPath, "utf-8"));
+  validateAndroidConfig(config);
+  if (config.renderer === "native") {
+    if (htmlPath || devServer)
+      throw new Error("A native Android screen cannot use --html-path or --dev-server.");
+    const destination = join(output, "app/src/main/assets/native-screen.js");
+    if (nativeBundlePath && resolve(nativeBundlePath) !== resolve(destination))
+      cpSync(nativeBundlePath, destination);
+    if (!existsSync(destination)) {
+      throw new Error("Native Android mode needs app/src/main/assets/native-screen.js. Compile a .stx screen with stx-native first.");
+    }
+  } else if (nativeBundlePath) {
+    throw new Error('--native-bundle requires renderer: "native" in craft.config.json.');
+  }
   if (existsSync(join(output, "app/src/main/jniLibs"))) {
     const runtimeDir = resolveRuntimeDir(options.runtimeDir);
     if (runtimeDir) {

package/dist/android/templates/MainActivityNative.kt.template

@@ -0,0 +1,390 @@
+package {{PACKAGE_NAME}}
+
+import android.content.ClipData
+import android.content.ClipboardManager
+import android.content.Context
+import android.graphics.Color
+import android.os.Build
+import android.os.Bundle
+import android.os.VibrationEffect
+import android.os.Vibrator
+import android.text.Editable
+import android.text.TextWatcher
+import android.util.Log
+import android.view.View
+import android.view.ViewGroup
+import android.widget.Button
+import android.widget.EditText
+import android.widget.FrameLayout
+import android.widget.LinearLayout
+import android.widget.TextView
+import androidx.appcompat.app.AppCompatActivity
+import androidx.core.content.ContextCompat
+import androidx.javascriptengine.JavaScriptIsolate
+import androidx.javascriptengine.JavaScriptConsoleCallback
+import androidx.javascriptengine.JavaScriptSandbox
+import androidx.javascriptengine.Message
+import androidx.javascriptengine.MessagePort
+import androidx.javascriptengine.MessagePortClient
+import org.json.JSONArray
+import org.json.JSONObject
+import java.util.UUID
+
+/** WebView-free host for a compiled stx-native route bundle. */
+class MainActivity : AppCompatActivity() {
+    private class Screen(
+        val route: String?,
+        val params: JSONObject,
+        val view: LinearLayout,
+        val isolate: JavaScriptIsolate,
+        val port: MessagePort?
+    ) {
+        val drafts = mutableMapOf<String, String>()
+        val controls = mutableMapOf<String, View>()
+        val handlers = mutableMapOf<View, String>()
+        var active = true
+
+        fun close() {
+            active = false
+            port?.close()
+            isolate.close()
+        }
+    }
+
+    private lateinit var root: FrameLayout
+    private var sandbox: JavaScriptSandbox? = null
+    private val screens = mutableListOf<Screen>()
+    private var bundle = ""
+    private var hapticsEnabled = false
+    private var defaultTextColor = Color.WHITE
+    private var useMessagePorts = false
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_main)
+        root = findViewById(R.id.native_root)
+        val config = runCatching {
+            assets.open("craft.config.json").bufferedReader().use {
+                JSONObject(it.readText())
+            }
+        }.getOrDefault(JSONObject())
+        hapticsEnabled = config.optBoolean("enableHaptics", false)
+        val background = color(config.optString("backgroundColor", "#1a1a2e"), Color.BLACK)
+        root.setBackgroundColor(background)
+        defaultTextColor = if (Color.luminance(background) < 0.5) Color.WHITE else Color.BLACK
+        bundle = runCatching {
+            assets.open("native-screen.js").bufferedReader().use { it.readText() }
+        }.getOrElse {
+            showError("Missing native-screen.js. Build with --native-bundle after compiling STX.")
+            return
+        }
+        if (!JavaScriptSandbox.isSupported()) {
+            showError("Native STX requires Android JavaScriptSandbox, which is unavailable on this device.")
+            return
+        }
+        val connection = JavaScriptSandbox.createConnectedInstanceAsync(this)
+        connection.addListener({
+            try {
+                val engine = connection.get()
+                if (isDestroyed) {
+                    engine.close()
+                    return@addListener
+                }
+                useMessagePorts = engine.isFeatureSupported(JavaScriptSandbox.JS_FEATURE_MESSAGE_PORTS)
+                    && engine.isFeatureSupported(JavaScriptSandbox.JS_FEATURE_PROMISE_RETURN)
+                if (!useMessagePorts && !engine.isFeatureSupported(JavaScriptSandbox.JS_FEATURE_CONSOLE_MESSAGING)) {
+                    engine.close()
+                    showError("Native STX requires JavaScript message ports or console messaging, unavailable on this device.")
+                    return@addListener
+                }
+                Log.i(TAG, "Native STX bridge: ${if (useMessagePorts) "message ports" else "console callback"}")
+                sandbox = engine
+                openScreen(null)
+            } catch (error: Exception) {
+                Log.e(TAG, "JavaScriptSandbox connection failed", error)
+                showError("Native STX JavaScript engine could not start: ${error.message}")
+            }
+        }, ContextCompat.getMainExecutor(this))
+    }
+
+    private fun openScreen(route: String?, params: JSONObject = JSONObject()) {
+        val engine = sandbox ?: return
+        val isolate = engine.createIsolate()
+        val view = LinearLayout(this).apply {
+            orientation = LinearLayout.VERTICAL
+            layoutParams = FrameLayout.LayoutParams(-1, -1)
+        }
+        var screen: Screen? = null
+        val executor = ContextCompat.getMainExecutor(this)
+        val token = UUID.randomUUID().toString()
+        val prefix = "CRAFT_STX_$token:"
+        val port = if (useMessagePorts) {
+            isolate.createMessageChannel("craft", executor, MessagePortClient { message ->
+                val current = screen ?: return@MessagePortClient
+                if (current.active && message.type == Message.TYPE_STRING) receive(current, message.string)
+            })
+        } else {
+            isolate.setConsoleCallback(executor, JavaScriptConsoleCallback { entry ->
+                val current = screen ?: return@JavaScriptConsoleCallback
+                if (current.active && entry.message.startsWith(prefix)) {
+                    receive(current, entry.message.removePrefix(prefix))
+                }
+            })
+            null
+        }
+        val activeScreen = Screen(route, params, view, isolate, port)
+        screen = activeScreen
+        screens.add(activeScreen)
+        show(activeScreen)
+        val routePrelude = """
+            globalThis.__stxNativeRoute = ${route?.let { JSONObject.quote(it) } ?: "undefined"};
+            globalThis.__stxNativeParams = ${params};
+        """.trimIndent()
+        val prelude = if (useMessagePorts) """
+            (async function() {
+              const port = await android.getNamedPort('craft');
+              $routePrelude
+              globalThis.__stxNativeBridge = {
+                postMessage: function(value) { port.postMessage(value); },
+                onMessage: function(callback) { port.onmessage = function(event) { callback(event.data); }; }
+              };
+            })()
+        """.trimIndent() else """
+            $routePrelude
+            globalThis.__stxNativeBridge = {
+              postMessage: function(value) { console.log(${JSONObject.quote(prefix)} + value); },
+              onMessage: function(callback) { globalThis.__stxNativeCallback = callback; }
+            };
+        """.trimIndent()
+        val setup = isolate.evaluateJavaScriptAsync(prelude)
+        setup.addListener({
+            if (!activeScreen.active) return@addListener
+            try {
+                setup.get()
+                val load = isolate.evaluateJavaScriptAsync(bundle)
+                load.addListener({
+                    try { load.get() } catch (error: Exception) {
+                        Log.e(TAG, "Native STX bundle failed", error)
+                        if (activeScreen.active) showError("Native STX bundle failed: ${error.message}")
+                    }
+                }, executor)
+            } catch (error: Exception) {
+                Log.e(TAG, "Native STX bridge failed", error)
+                showError("Native STX bridge failed: ${error.message}")
+            }
+        }, executor)
+    }
+
+    private fun show(screen: Screen) {
+        root.removeAllViews()
+        (screen.view.parent as? ViewGroup)?.removeView(screen.view)
+        root.addView(screen.view)
+    }
+
+    private fun receive(screen: Screen, raw: String) {
+        val message = runCatching { JSONObject(raw) }.getOrNull() ?: return
+        val payload = message.optJSONObject("payload") ?: JSONObject()
+        when (message.optString("type")) {
+            "RENDER" -> payload.optJSONObject("document")?.let { render(screen, it) }
+            "NAVIGATE", "NAVIGATE_REPLACE" -> {
+                if (screens.lastOrNull() !== screen) return
+                val route = payload.optString("screen").takeIf { it.isNotBlank() } ?: return
+                if (message.optString("type") == "NAVIGATE_REPLACE") {
+                    screens.removeAt(screens.lastIndex).close()
+                }
+                openScreen(route, payload.optJSONObject("params") ?: JSONObject())
+            }
+            "NAVIGATE_BACK" -> if (screens.lastOrNull() === screen) back()
+            "API_REQUEST" -> answerAPI(screen, message, payload)
+        }
+    }
+
+    private fun render(screen: Screen, document: JSONObject) {
+        // Keep live controls (especially the focused EditText) across renders.
+        val next = mutableMapOf<String, View>()
+        val tree = makeView(screen, document, "root", next)
+        if (screen.view.getChildAt(0) !== tree) {
+            (tree.parent as? ViewGroup)?.removeView(tree)
+            screen.view.removeAllViews()
+            screen.view.addView(tree)
+        }
+        screen.controls.clear()
+        screen.controls.putAll(next)
+        screen.handlers.keys.retainAll(next.values.toSet())
+    }
+
+    private fun makeView(screen: Screen, node: JSONObject, path: String, next: MutableMap<String, View>): View {
+        val type = node.optString("type", "View")
+        val props = node.optJSONObject("props") ?: JSONObject()
+        val style = node.optJSONObject("style") ?: JSONObject()
+        val events = node.optJSONObject("events") ?: JSONObject()
+        val children = node.optJSONArray("children") ?: JSONArray()
+        val explicitKey = listOf(node.optString("key"), props.optString("key"), props.optString("testID"))
+            .firstOrNull { it.isNotBlank() }
+        val identity = explicitKey?.let { "${path.substringBeforeLast('.', "")}/$it" } ?: path
+        val previous = screen.controls[identity]
+        val control = when (type) {
+            "Text" -> ((previous as? TextView)?.takeUnless { it is Button || it is EditText } ?: TextView(this)).apply {
+                text = childText(children)
+                setTextColor(color(style.optString("color"), defaultTextColor))
+                if (style.has("fontSize")) textSize = style.optDouble("fontSize").toFloat()
+            }
+            "Button" -> (previous as? Button ?: Button(this)).apply {
+                text = props.optString("title").ifBlank { childText(children) }
+                val handler = events.optString("onPress").ifBlank { events.optString("onClick") }
+                if (handler.isNotBlank()) screen.handlers[this] = handler else screen.handlers.remove(this)
+                setOnClickListener {
+                    val current = screen.handlers[this] ?: return@setOnClickListener
+                    send(screen, "EVENT", JSONObject().put("handlerName", current).put("nativeEvent", JSONObject()))
+                }
+            }
+            "TextInput" -> (previous as? EditText ?: EditText(this)).apply {
+                hint = props.optString("placeholder")
+                if (props.has("value") && text.toString() != props.optString("value")) setText(props.optString("value"))
+                else if (this !== previous && screen.drafts.containsKey(identity)) setText(screen.drafts[identity])
+                val handler = events.optString("onChange").ifBlank { events.optString("onChangeText") }
+                if (handler.isNotBlank()) screen.handlers[this] = handler else screen.handlers.remove(this)
+                if (this !== previous) addTextChangedListener(object : TextWatcher {
+                    override fun beforeTextChanged(s: CharSequence?, start: Int, count: Int, after: Int) {}
+                    override fun onTextChanged(s: CharSequence?, start: Int, before: Int, count: Int) {
+                        val updated = s?.toString().orEmpty()
+                        screen.drafts[identity] = updated
+                        val current = screen.handlers[this@apply] ?: return
+                        send(screen, "EVENT", JSONObject()
+                            .put("handlerName", current)
+                            .put("nativeEvent", JSONObject().put("text", updated)))
+                    }
+                    override fun afterTextChanged(s: Editable?) {}
+                })
+            }
+            else -> (previous as? LinearLayout ?: LinearLayout(this)).apply {
+                orientation = if (style.optString("flexDirection") == "row")
+                    LinearLayout.HORIZONTAL else LinearLayout.VERTICAL
+                val padding = style.optDouble("padding", 0.0)
+                setPadding(
+                    dp(style.optDouble("paddingLeft", padding)),
+                    dp(style.optDouble("paddingTop", padding)),
+                    dp(style.optDouble("paddingRight", padding)),
+                    dp(style.optDouble("paddingBottom", padding))
+                )
+                val desired = mutableListOf<View>()
+                for (index in 0 until children.length()) {
+                    val child = children.opt(index)
+                    val childView = when (child) {
+                        is JSONObject -> makeView(screen, child, "$path.$index", next)
+                        is String -> TextView(this@MainActivity).apply {
+                            text = child
+                            setTextColor(defaultTextColor)
+                        }
+                        else -> null
+                    }
+                    if (childView != null) desired.add(childView)
+                }
+                val desiredSet = desired.toSet()
+                for ((index, childView) in desired.withIndex()) {
+                    if (getChildAt(index) === childView) continue
+                    if (index < childCount && getChildAt(index) !in desiredSet) removeViewAt(index)
+                    (childView.parent as? ViewGroup)?.removeView(childView)
+                    addView(childView, index)
+                }
+                while (childCount > desired.size) removeViewAt(childCount - 1)
+            }
+        }
+        control.contentDescription = explicitKey ?: path
+        next[identity] = control
+        if (style.has("backgroundColor")) control.setBackgroundColor(color(style.optString("backgroundColor"), Color.TRANSPARENT))
+        control.layoutParams = LinearLayout.LayoutParams(
+            if (style.has("width")) dp(style.optDouble("width")) else ViewGroup.LayoutParams.MATCH_PARENT,
+            if (style.has("height")) dp(style.optDouble("height")) else ViewGroup.LayoutParams.WRAP_CONTENT
+        )
+        return control
+    }
+
+    private fun childText(children: JSONArray): String = buildString {
+        for (index in 0 until children.length()) {
+            val value = children.opt(index)
+            if (value is String) append(value)
+        }
+    }
+
+    private fun dp(value: Double) = (value * resources.displayMetrics.density).toInt()
+    private fun color(raw: String, fallback: Int) = runCatching { Color.parseColor(raw) }.getOrDefault(fallback)
+
+    private fun answerAPI(screen: Screen, message: JSONObject, payload: JSONObject) {
+        val id = message.optString("id")
+        if (id.isBlank()) return
+        val args = payload.optJSONArray("args") ?: JSONArray()
+        val response = JSONObject().put("requestId", id)
+        val result = when (payload.optString("module") to payload.optString("method")) {
+            "Device" to "getInfo" -> response.put("data", JSONObject()
+                .put("platform", "android")
+                .put("osVersion", Build.VERSION.RELEASE)
+                .put("model", Build.MODEL)
+                .put("manufacturer", Build.MANUFACTURER))
+            "Clipboard" to "write" -> {
+                val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
+                clipboard.setPrimaryClip(ClipData.newPlainText("", args.optString(0)))
+                response.put("data", JSONObject().put("ok", true))
+            }
+            "Clipboard" to "read" -> {
+                val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
+                response.put("data", clipboard.primaryClip?.getItemAt(0)?.coerceToText(this)?.toString() ?: "")
+            }
+            "Haptics" to "impact" -> {
+                if (!hapticsEnabled) response.put("code", "CAPABILITY_DISABLED")
+                    .put("message", "Haptics are disabled")
+                else {
+                    val vibrator = getSystemService(Context.VIBRATOR_SERVICE) as Vibrator
+                    vibrator.vibrate(VibrationEffect.createOneShot(30, VibrationEffect.DEFAULT_AMPLITUDE))
+                    response.put("data", JSONObject().put("ok", true))
+                }
+            }
+            else -> response.put("code", "UNKNOWN_ACTION").put("message", "Unsupported native API")
+        }
+        send(screen, if (result.has("code")) "API_ERROR" else "API_RESPONSE", result, id)
+    }
+
+    private fun send(screen: Screen, type: String, payload: JSONObject, correlationId: String? = null) {
+        if (!screen.active) return
+        val message = JSONObject().put("type", type).put("payload", payload)
+        if (correlationId != null) message.put("correlationId", correlationId)
+        if (screen.port != null) {
+            screen.port.postMessage(Message.createStringMessage(message.toString()))
+        } else {
+            val script = "globalThis.__stxNativeCallback && globalThis.__stxNativeCallback(${JSONObject.quote(message.toString())})"
+            screen.isolate.evaluateJavaScriptAsync(script)
+        }
+    }
+
+    private fun back() {
+        if (screens.size > 1) {
+            screens.removeAt(screens.lastIndex).close()
+            show(screens.last())
+        } else {
+            finish()
+        }
+    }
+
+    @Deprecated("Uses the activity back callback for native route navigation")
+    override fun onBackPressed() = back()
+
+    private fun showError(message: String) {
+        root.removeAllViews()
+        root.addView(TextView(this).apply {
+            text = message
+            setTextColor(Color.RED)
+            textSize = 16f
+            setPadding(24, 24, 24, 24)
+        })
+        Log.e(TAG, message)
+    }
+
+    override fun onDestroy() {
+        screens.forEach { it.close() }
+        screens.clear()
+        sandbox?.close()
+        super.onDestroy()
+    }
+
+    companion object { private const val TAG = "CraftNativeAndroid" }
+}

package/dist/android/templates/build.gradle.kts.app.template

@@ -59,6 +59,7 @@ dependencies {
     implementation("androidx.appcompat:appcompat:1.6.1")
     implementation("androidx.fragment:fragment-ktx:1.6.2")
     implementation("androidx.webkit:webkit:1.12.1")
+{{JAVASCRIPT_ENGINE_DEPENDENCY}}
     implementation("com.google.android.material:material:1.11.0")
     implementation("androidx.coordinatorlayout:coordinatorlayout:1.2.0")
 

package/dist/api/window.d.ts

@@ -140,9 +140,9 @@ export interface WindowCreateOptions {
     vibrancy?: 'appearance-based' | 'light' | 'dark' | 'titlebar' | 'selection' | 'menu' | 'popover' | 'sidebar' | 'header' | 'sheet' | 'window' | 'hud' | 'fullscreen-ui' | 'tooltip' | 'content' | 'under-window' | 'under-page';
     /** Background material (Windows 11) */
     backgroundMaterial?: 'auto' | 'none' | 'mica' | 'acrylic' | 'tabbed';
-    /** Parent window ID */
+    /** Native parent window: `main` means this page's own window, or use a named handle owned by this page. */
     parent?: string;
-    /** Whether this is a modal window */
+    /** Requires `parent`; blocks only that parent while visible, not every app window. */
     modal?: boolean;
     /** HTML content to load */
     html?: string;
@@ -167,9 +167,8 @@ export interface WindowEventMap {
     'restore': void;
     'resize': WindowSize;
     'move': WindowPosition;
-    'close': {
-        preventDefault: () => void;
-    };
+    /** Notification after native closing begins; this event cannot cancel it. */
+    'close': void;
     'closed': void;
     'enter-fullscreen': void;
     'leave-fullscreen': void;
@@ -404,17 +403,13 @@ export declare class Window {
      * Enable/disable window shadow (macOS)
      */
     setHasShadow(hasShadow: boolean): Promise<void>;
-    /**
-     * Set background material (Windows 11)
-     */
+    /** Reserved for Windows 11 material support; current desktop hosts reject this action. */
     setBackgroundMaterial(material: WindowCreateOptions['backgroundMaterial']): Promise<void>;
     /**
      * Flash window in taskbar (Windows)
      */
     flashFrame(flash: boolean): Promise<void>;
-    /**
-     * Set taskbar overlay icon (Windows)
-     */
+    /** Reserved for Windows taskbar overlay support; current desktop hosts reject this action. */
     setOverlayIcon(icon: string | null, description?: string): Promise<void>;
     /**
      * Load HTML content