@craft-native/android 0.0.158 → 0.0.161

package/README.md

@@ -96,10 +96,16 @@ stx native compile --config ../screens/native.config.json --format bundle --outp
 craft android build --native-bundle ../native-screen.js
 ```
 
-Native mode maps STX `View`, `SafeAreaView`, `Text`, `Button`, `Link`,
-`Pressable`, `TouchableOpacity`, `TouchableHighlight`, `TextInput`, `Picker`, `Modal`, `Switch`, `Slider`, `ActivityIndicator`, `Image`, `Video`, `ScrollView`,
-and `FlatList` to Android views. `Picker` renders `<select>`/`<option>` values
-with `onValueChange` or `onChange`. `Modal` is parent-scoped and supports
+Native mode maps STX `View`, `SafeAreaView`, `Text`, `Button`, `Link`, `Icon`,
+`Pressable`, `TouchableOpacity`, `TouchableHighlight`, `Checkbox`, `TextInput`, `Picker`, `DatePicker`, `Modal`, `Switch`, `Slider`, `ActivityIndicator`, `Image`, `Video`, `ScrollView`,
+`SectionList`, and `FlatList` to Android views. `SectionList` uses the same
+native scroll host for ordinary `.stx` slot children; grouped section data
+should use `FlatList` until the section-data protocol is available. The
+generated host routes both list names through `CraftNativeScrollView` for this
+slot-based contract. `Picker` renders `<select>`/`<option>` values
+with `onValueChange` or `onChange`. `DatePicker` uses the platform `DatePicker`
+and `TimePicker` controls for date, time, datetime, and countdown modes and
+emits local `value`, ISO, and millisecond `timestamp` fields. `Modal` is parent-scoped and supports
 `visible`, `transparent`, `animationType`, `onShow`, `onDismiss`, and
 `onRequestClose` for Android back handling. `Switch` supports state-aware `trackColor`
 and `thumbColor`, while `Slider` supports track/thumb tint props and `step`
@@ -108,6 +114,16 @@ non-animated when `animating={false}` and `hidesWhenStopped={false}`. `Image`
 reports load lifecycle events and structured failures. `Video` uses the native
 `VideoView` for URI playback with autoplay, pause, looping, mute, controls, and
 resize-mode props.
+`ImageBackground` loads an image behind ordinary native children while
+preserving the shared flex layout contract.
+`Icon` uses the shared symbol/name contract with a dependency-free Android
+glyph map; unknown symbols render a hollow-circle fallback instead of an empty
+native node.
+`KeyboardAvoidingView` responds to Android IME insets with `padding`,
+`position`, or `height` behavior and accepts `keyboardVerticalOffset`.
+`Checkbox` accepts controlled `checked`/`value` and `indeterminate`; mixed
+controls expose an Android accessibility state description of `mixed` and
+become checked on their first user toggle.
 `FlatList` uses
 `RecyclerView`, stable IDs, and `DiffUtil` for keyed recycling, grids,
 horizontal and inverted layouts, list chrome, and end-reached pagination.
@@ -142,6 +158,17 @@ after inset or orientation changes. The shared component, capability, list, styl
 image-source, event, accessibility, and reconciliation contract is documented in the
 [Native STX guide](../../docs/guides/native-stx.md).
 
+Native screens also expose `craft.files` when the host advertises the
+`files` capability. `pickImage` returns an app-owned file descriptor,
+`download` and `write` keep bytes on disk, and `remove` accepts only files
+created by that capability. `FormData` is available on this path; `fetch`
+builds its multipart body natively from text fields and those owned files, so
+image bytes do not cross the Android JavaScript bridge as base64. The browser
+renderer keeps using the ordinary web `File`/`FormData` implementations. Owned
+files survive Activity recreation and stale cache entries are swept after a day.
+`files.download` resolves a non-2xx response as `{ ok: false, status, body }`
+instead of turning the server's response into a transport error.
+
 `FlatList` item roots receive the same `onLayout` callback as ordinary native
 views when rows are materialized or recycled.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-native/android",
-  "version": "0.0.158",
+  "version": "0.0.161",
   "homepage": "https://github.com/craft-native/craft/tree/main/packages/android#readme",
   "repository": {
     "type": "git",

package/templates/CraftNative.kt.template

@@ -280,6 +280,61 @@ object CraftNative {
         margins: FloatArray,
         flags: FloatArray,
     ): FloatArray?
+    private external fun nativeGridAutoRows(
+        availableWidth: Float,
+        availableHeight: Float,
+        columns: Int,
+        columnGap: Float,
+        rowGap: Float,
+        autoRowHeight: Float,
+        intrinsicWidth: FloatArray,
+        intrinsicHeight: FloatArray,
+        explicitWidth: FloatArray,
+        explicitHeight: FloatArray,
+        minWidth: FloatArray,
+        maxWidth: FloatArray,
+        minHeight: FloatArray,
+        maxHeight: FloatArray,
+        margins: FloatArray,
+        flags: FloatArray,
+    ): FloatArray?
+    private external fun nativeGridAligned(
+        availableWidth: Float,
+        availableHeight: Float,
+        columns: Int,
+        columnGap: Float,
+        rowGap: Float,
+        alignContent: Int,
+        intrinsicWidth: FloatArray,
+        intrinsicHeight: FloatArray,
+        explicitWidth: FloatArray,
+        explicitHeight: FloatArray,
+        minWidth: FloatArray,
+        maxWidth: FloatArray,
+        minHeight: FloatArray,
+        maxHeight: FloatArray,
+        margins: FloatArray,
+        flags: FloatArray,
+    ): FloatArray?
+    private external fun nativeGridAutoRowsAligned(
+        availableWidth: Float,
+        availableHeight: Float,
+        columns: Int,
+        columnGap: Float,
+        rowGap: Float,
+        alignContent: Int,
+        autoRowHeight: Float,
+        intrinsicWidth: FloatArray,
+        intrinsicHeight: FloatArray,
+        explicitWidth: FloatArray,
+        explicitHeight: FloatArray,
+        minWidth: FloatArray,
+        maxWidth: FloatArray,
+        minHeight: FloatArray,
+        maxHeight: FloatArray,
+        margins: FloatArray,
+        flags: FloatArray,
+    ): FloatArray?
     private external fun nativeClipboardRead(activity: Activity): String?
     private external fun nativeClipboardWrite(activity: Activity, text: String): Boolean
     private external fun nativeOpenUrl(activity: Activity, url: String): Boolean
@@ -513,10 +568,16 @@ object CraftNative {
         maxHeight: FloatArray,
         margins: FloatArray,
         flags: FloatArray,
+        autoRowHeight: Float? = null,
+        alignContent: Int = 0,
     ): FloatArray? {
         if (!isAvailable) return null
         return try {
-            nativeGrid(availableWidth, availableHeight, columns, columnGap, rowGap, intrinsicWidth, intrinsicHeight, explicitWidth, explicitHeight, minWidth, maxWidth, minHeight, maxHeight, margins, flags)
+            if (autoRowHeight != null) {
+                nativeGridAutoRowsAligned(availableWidth, availableHeight, columns, columnGap, rowGap, alignContent, autoRowHeight, intrinsicWidth, intrinsicHeight, explicitWidth, explicitHeight, minWidth, maxWidth, minHeight, maxHeight, margins, flags)
+            } else {
+                nativeGridAligned(availableWidth, availableHeight, columns, columnGap, rowGap, alignContent, intrinsicWidth, intrinsicHeight, explicitWidth, explicitHeight, minWidth, maxWidth, minHeight, maxHeight, margins, flags)
+            }
                 ?.takeIf { it.size >= intrinsicWidth.size * 4 && it.all { value -> value.isFinite() } }
         } catch (e: UnsatisfiedLinkError) {
             null

package/templates/CraftNativeCapabilities.kt.template

@@ -12,8 +12,11 @@ import android.database.sqlite.SQLiteCursor
 import android.database.sqlite.SQLiteDatabase
 import android.database.sqlite.SQLiteQuery
 import android.database.sqlite.SQLiteStatement
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
 import android.os.Build
 import android.net.Uri
+import android.provider.MediaStore
 import android.util.Base64
 import androidx.core.content.ContextCompat
 import androidx.biometric.BiometricManager
@@ -25,15 +28,25 @@ import org.json.JSONArray
 import org.json.JSONObject
 import org.json.JSONTokener
 import java.io.ByteArrayOutputStream
+import java.io.File
+import java.io.FileOutputStream
 import java.net.HttpURLConnection
 import java.net.SocketTimeoutException
 import java.net.URL
+import java.net.URLConnection
 import java.util.UUID
 import java.util.concurrent.ConcurrentHashMap
 import java.util.concurrent.Executors
+import kotlin.math.max
+import kotlin.math.roundToInt
 
 private const val CRAFT_NATIVE_FETCH_MAX_RESPONSE_BYTES = 8 * 1024 * 1024
 private const val CRAFT_NATIVE_FETCH_TIMEOUT_MS = 30_000
+private const val CRAFT_NATIVE_FILE_PICK_REQUEST = 4101
+private const val CRAFT_NATIVE_FILE_DEFAULT_MAX_PIXELS = 2048
+private const val CRAFT_NATIVE_FILE_LARGEST_MAX_PIXELS = 8192
+private const val CRAFT_NATIVE_FILE_DEFAULT_QUALITY = 0.85
+private const val CRAFT_NATIVE_FILE_ERROR_BODY_BYTES = 64 * 1024
 
 internal const val CRAFT_NATIVE_CAPABILITY_PROTOCOL_VERSION = 1
 
@@ -68,13 +81,26 @@ internal class CraftNativeCapabilities(
     private val networkExecutor = Executors.newCachedThreadPool()
     private val cancelled = ConcurrentHashMap.newKeySet<String>()
     private val fetchConnections = ConcurrentHashMap<String, HttpURLConnection>()
+    private val fileRoot by lazy { File(activity.cacheDir, "craft-files").apply { mkdirs() } }
+    private var pendingFilePick: PendingFilePick? = null
     private var database: SQLiteDatabase? = null
     private val biometricPrompts = ConcurrentHashMap<String, BiometricPrompt>()
 
-    init { restoreNotifications() }
+    private data class PendingFilePick(
+        val requestToken: String,
+        val source: String,
+        val maxPixels: Int,
+        val quality: Float,
+        val completion: (CraftNativeCapabilityResult) -> Unit,
+    )
+
+    init {
+        restoreNotifications()
+        sweepFiles()
+    }
 
     fun names(): JSONArray = JSONArray().apply {
-        listOf("device", "clipboard", "haptics", "storage", "lifecycle", "fetch").forEach(::put)
+        listOf("device", "clipboard", "haptics", "storage", "lifecycle", "fetch", "files").forEach(::put)
         if (config.optBoolean("enableBiometric")) put("biometric")
         if (config.optBoolean("enableSecureStorage")) put("secureStorage")
         if (config.optBoolean("enableLocalDatabase")) put("database")
@@ -121,6 +147,13 @@ internal class CraftNativeCapabilities(
                     complete(requestToken, fetch(requestToken, args), completion)
                 }
             }
+            "Files" -> when (method) {
+                "pickImage" -> pickImage(requestToken, args, completion)
+                "download", "write", "remove" -> networkExecutor.execute {
+                    complete(requestToken, files(requestToken, method, args), completion)
+                }
+                else -> complete(requestToken, failure("UNKNOWN_ACTION", "Unsupported Files method"), completion)
+            }
             else -> complete(requestToken, activity.performImmediateCapability(module, method, args), completion)
         }
     }
@@ -128,6 +161,7 @@ internal class CraftNativeCapabilities(
     fun cancel(requestToken: String) {
         cancelled.add(requestToken)
         fetchConnections.remove(requestToken)?.disconnect()
+        if (pendingFilePick?.requestToken == requestToken) pendingFilePick = null
         biometricPrompts.remove(requestToken)?.cancelAuthentication()
     }
 
@@ -136,6 +170,7 @@ internal class CraftNativeCapabilities(
         networkExecutor.shutdownNow()
         fetchConnections.values.forEach(HttpURLConnection::disconnect)
         fetchConnections.clear()
+        pendingFilePick = null
         database?.close()
         database = null
         biometricPrompts.values.forEach { it.cancelAuthentication() }
@@ -155,15 +190,21 @@ internal class CraftNativeCapabilities(
         val method = options.optString("method", "GET").uppercase()
         if (method.isBlank() || method.any { !it.isLetter() || it.code > 127 })
             return failure("INVALID_ARGUMENT", "fetch method must be an HTTP token")
+        val form = options.optJSONArray("form")
         val bodyValue = options.opt("body")
+        if (form != null && bodyValue != null && bodyValue != JSONObject.NULL)
+            return failure("INVALID_ARGUMENT", "fetch cannot have both form and body")
         val body = when (bodyValue) {
             null, JSONObject.NULL -> null
             is String -> bodyValue
             else -> return failure("INVALID_ARGUMENT", "fetch body must be a string")
         }
-        if (body != null && method in setOf("GET", "HEAD"))
+        if ((body != null || form != null) && method in setOf("GET", "HEAD"))
             return failure("INVALID_ARGUMENT", "A GET or HEAD request cannot have a body")
 
+        val multipart = form?.let { multipart(it) }
+        if (multipart is FileResult.Failure) return failure(multipart.code, multipart.message)
+
         val connection = try {
             (url.openConnection() as HttpURLConnection).apply {
                 requestMethod = method
@@ -177,7 +218,8 @@ internal class CraftNativeCapabilities(
                         setRequestProperty(name, value)
                     }
                 }
-                if (body != null) doOutput = true
+                if (body != null || multipart is FileResult.Multipart) doOutput = true
+                if (multipart is FileResult.Multipart) setRequestProperty("Content-Type", "multipart/form-data; boundary=${multipart.boundary}")
             }
         } catch (error: IllegalArgumentException) {
             return failure("INVALID_ARGUMENT", error.message ?: "fetch request is invalid")
@@ -191,6 +233,7 @@ internal class CraftNativeCapabilities(
         }
         return try {
             if (body != null) connection.outputStream.use { it.write(body.toByteArray(Charsets.UTF_8)) }
+            if (multipart is FileResult.Multipart) connection.outputStream.use { it.write(multipart.body) }
             val status = connection.responseCode
             val input = if (status >= 400) connection.errorStream else connection.inputStream
             val output = ByteArrayOutputStream()
@@ -224,6 +267,270 @@ internal class CraftNativeCapabilities(
         }
     }
 
+    private sealed interface FileResult {
+        data class Multipart(val body: ByteArray, val boundary: String) : FileResult
+        data class Failure(val code: String, val message: String) : FileResult
+    }
+
+    private fun multipart(parts: JSONArray): FileResult {
+        val boundary = "craft-${UUID.randomUUID()}"
+        val body = ByteArrayOutputStream()
+        fun append(value: String) { body.write(value.toByteArray(Charsets.UTF_8)) }
+        for (index in 0 until parts.length()) {
+            val part = parts.optJSONObject(index) ?: return FileResult.Failure("INVALID_ARGUMENT", "A form part must be an object")
+            val name = part.optString("name")
+            if (name.isBlank()) return FileResult.Failure("INVALID_ARGUMENT", "A form part needs a name")
+            append("--$boundary\r\n")
+            val path = part.optString("path")
+            if (path.isNotBlank()) {
+                val file = ownedFile(path) ?: return FileResult.Failure("INVALID_ARGUMENT", "A form file must be one craft.files made, and still there")
+                val bytes = runCatching { file.readBytes() }.getOrElse {
+                    return FileResult.Failure("INVALID_ARGUMENT", "A form file could not be read")
+                }
+                val filename = safeFileName(part.optString("filename").ifBlank { file.name })
+                val type = part.optString("type").ifBlank { URLConnection.guessContentTypeFromName(filename) ?: "application/octet-stream" }
+                append("Content-Disposition: form-data; name=\"${quoted(name)}\"; filename=\"${quoted(filename)}\"\r\n")
+                append("Content-Type: ${headerValue(type)}\r\n\r\n")
+                body.write(bytes)
+                append("\r\n")
+            } else {
+                append("Content-Disposition: form-data; name=\"${quoted(name)}\"\r\n\r\n")
+                append(part.optString("value"))
+                append("\r\n")
+            }
+        }
+        append("--$boundary--\r\n")
+        return FileResult.Multipart(body.toByteArray(), boundary)
+    }
+
+    private fun files(requestToken: String, method: String, args: JSONArray): CraftNativeCapabilityResult {
+        return when (method) {
+        "write" -> {
+            val name = args.optString(0).trim()
+            if (name.isBlank()) return failure("INVALID_ARGUMENT", "files.write needs a file name")
+            val data = args.optString(1, "")
+            val options = args.optJSONObject(2) ?: JSONObject()
+            val bytes = when (options.optString("encoding", "utf8")) {
+                "utf8" -> data.toByteArray(Charsets.UTF_8)
+                "base64" -> runCatching { Base64.decode(data, Base64.DEFAULT) }
+                    .getOrElse { return failure("INVALID_ARGUMENT", "files.write base64 is invalid") }
+                else -> return failure("INVALID_ARGUMENT", "files.write encoding is 'utf8' or 'base64'")
+            }
+            store(bytes, name, options.optString("type").ifBlank { URLConnection.guessContentTypeFromName(name) ?: "application/octet-stream" })
+        }
+        "remove" -> {
+            val file = ownedFile(args.optString(0)) ?: return failure("INVALID_ARGUMENT", "files.remove needs a file made by craft.files")
+            success(file.delete())
+        }
+        "download" -> download(requestToken, args)
+            else -> failure("UNKNOWN_ACTION", "Unsupported Files method")
+        }
+    }
+
+    private fun download(requestToken: String, args: JSONArray): CraftNativeCapabilityResult {
+        val address = args.optString(0).trim()
+        val url = validURL(address) ?: return failure("INVALID_ARGUMENT", "files.download needs an absolute http or https URL")
+        val options = args.optJSONObject(1) ?: JSONObject()
+        val connection = try {
+            (url.openConnection() as HttpURLConnection).apply {
+                requestMethod = "GET"
+                connectTimeout = CRAFT_NATIVE_FETCH_TIMEOUT_MS
+                readTimeout = CRAFT_NATIVE_FETCH_TIMEOUT_MS
+                options.optJSONObject("headers")?.let { headers ->
+                    for (name in headers.keys()) {
+                        val value = headers.opt(name)
+                        if (value !is String) throw IllegalArgumentException("files.download header values must be strings")
+                        setRequestProperty(name, value)
+                    }
+                }
+            }
+        } catch (error: IllegalArgumentException) {
+            return failure("INVALID_ARGUMENT", error.message ?: "files.download request is invalid")
+        } catch (error: Exception) {
+            return failure("NETWORK_ERROR", error.message ?: "File download failed")
+        }
+        fetchConnections[requestToken] = connection
+        if (cancelled.contains(requestToken)) {
+            fetchConnections.remove(requestToken)?.disconnect()
+            return failure("CANCELLED", "File download was cancelled")
+        }
+        return try {
+            val status = connection.responseCode
+            if (status !in 200..299) return refusedDownload(connection, status, requestToken)
+            val name = options.optString("name").ifBlank { connection.url.path.substringAfterLast('/').ifBlank { "download" } }
+            val file = File(fileRoot, UUID.randomUUID().toString()).apply { mkdirs() }.resolve(safeFileName(name))
+            connection.inputStream.use { input -> FileOutputStream(file).use { output ->
+                val buffer = ByteArray(8192)
+                while (true) {
+                    if (cancelled.contains(requestToken)) return failure("CANCELLED", "File download was cancelled")
+                    val count = input.read(buffer)
+                    if (count < 0) break
+                    output.write(buffer, 0, count)
+                }
+            } }
+            success(descriptor(file, connection.contentType ?: "application/octet-stream"))
+        } catch (error: SocketTimeoutException) {
+            failure("TIMEOUT", error.message ?: "File download timed out")
+        } catch (error: Exception) {
+            if (cancelled.contains(requestToken)) failure("CANCELLED", "File download was cancelled")
+            else failure("NETWORK_ERROR", error.message ?: "File download failed")
+        } finally {
+            fetchConnections.remove(requestToken)?.disconnect()
+            connection.disconnect()
+        }
+    }
+
+    private fun refusedDownload(
+        connection: HttpURLConnection,
+        status: Int,
+        requestToken: String,
+    ): CraftNativeCapabilityResult {
+        if (cancelled.contains(requestToken)) return failure("CANCELLED", "File download was cancelled")
+        val body = ByteArrayOutputStream()
+        connection.errorStream?.use { input ->
+            val buffer = ByteArray(8192)
+            while (body.size() < CRAFT_NATIVE_FILE_ERROR_BODY_BYTES) {
+                val count = input.read(buffer, 0, minOf(buffer.size, CRAFT_NATIVE_FILE_ERROR_BODY_BYTES - body.size()))
+                if (count < 0) break
+                body.write(buffer, 0, count)
+            }
+        }
+        return success(JSONObject().put("ok", false).put("status", status).put("body", body.toString(Charsets.UTF_8.name())))
+    }
+
+    private fun pickImage(
+        requestToken: String,
+        args: JSONArray,
+        completion: (CraftNativeCapabilityResult) -> Unit,
+    ) {
+        activity.runOnUiThread {
+            if (pendingFilePick != null) {
+                complete(requestToken, failure("BUSY", "Another file picker is already open"), completion)
+                return@runOnUiThread
+            }
+            val options = args.optJSONObject(0) ?: JSONObject()
+            val source = options.optString("source", "library")
+            if (source != "library" && source != "camera") {
+                complete(requestToken, failure("INVALID_ARGUMENT", "files.pickImage source is 'library' or 'camera'"), completion)
+                return@runOnUiThread
+            }
+            val maxPixels = options.optInt("maxPixels", CRAFT_NATIVE_FILE_DEFAULT_MAX_PIXELS)
+                .coerceIn(64, CRAFT_NATIVE_FILE_LARGEST_MAX_PIXELS)
+            val quality = options.optDouble("quality", CRAFT_NATIVE_FILE_DEFAULT_QUALITY)
+                .coerceIn(0.1, 1.0).toFloat()
+            if (source == "camera" && !config.optBoolean("enableCamera")) {
+                complete(requestToken, failure("CAPABILITY_DISABLED", "Camera is disabled"), completion)
+                return@runOnUiThread
+            }
+            pendingFilePick = PendingFilePick(requestToken, source, maxPixels, quality, completion)
+            val intent = if (source == "camera") Intent(MediaStore.ACTION_IMAGE_CAPTURE)
+            else Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
+                addCategory(Intent.CATEGORY_OPENABLE)
+                type = "image/*"
+            }
+            try {
+                activity.startActivityForResult(intent, CRAFT_NATIVE_FILE_PICK_REQUEST)
+            } catch (error: Exception) {
+                pendingFilePick = null
+                complete(requestToken, failure("PICKER_UNAVAILABLE", error.message ?: "Image picker could not be opened"), completion)
+            }
+        }
+    }
+
+    fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?): Boolean {
+        if (requestCode != CRAFT_NATIVE_FILE_PICK_REQUEST) return false
+        val pending = pendingFilePick ?: return true
+        pendingFilePick = null
+        if (resultCode != android.app.Activity.RESULT_OK) {
+            complete(pending.requestToken, success(JSONObject.NULL), pending.completion)
+            return true
+        }
+        val descriptor = if (pending.source == "camera") {
+            val bitmap = data?.extras?.get("data") as? Bitmap
+            bitmap?.let { writeImage(it, pending.maxPixels, pending.quality, "photo.jpg") }
+        } else {
+            val uri = data?.data
+            uri?.let { copyUri(it, pending.maxPixels, pending.quality) }
+        }
+        complete(pending.requestToken, descriptor?.let(::success) ?: failure("PICKER_FAILED", "The selected image could not be read"), pending.completion)
+        return true
+    }
+
+    private fun copyUri(uri: Uri, maxPixels: Int, quality: Float): JSONObject? {
+        val name = activity.contentResolver.query(uri, arrayOf(android.provider.OpenableColumns.DISPLAY_NAME), null, null, null)?.use {
+            if (it.moveToFirst()) it.getString(0) else null
+        } ?: "photo"
+        val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+        activity.contentResolver.openInputStream(uri)?.use { BitmapFactory.decodeStream(it, null, bounds) } ?: return null
+        if (bounds.outWidth <= 0 || bounds.outHeight <= 0) return null
+        var sample = 1
+        while (max(bounds.outWidth / sample, bounds.outHeight / sample) > maxPixels * 2) sample *= 2
+        val options = BitmapFactory.Options().apply { inSampleSize = sample }
+        val bitmap = activity.contentResolver.openInputStream(uri)?.use { BitmapFactory.decodeStream(it, null, options) } ?: return null
+        return writeImage(bitmap, maxPixels, quality, jpegName(name))
+    }
+
+    private fun writeImage(bitmap: Bitmap, maxPixels: Int, quality: Float, name: String): JSONObject? {
+        val longest = max(bitmap.width, bitmap.height)
+        val scale = if (longest > maxPixels) maxPixels.toFloat() / longest else 1f
+        val output = if (scale < 1f) Bitmap.createScaledBitmap(
+            bitmap,
+            (bitmap.width * scale).roundToInt().coerceAtLeast(1),
+            (bitmap.height * scale).roundToInt().coerceAtLeast(1),
+            true,
+        ) else bitmap
+        val file = File(fileRoot, UUID.randomUUID().toString()).apply { mkdirs() }.resolve(safeFileName(name))
+        val width = output.width
+        val height = output.height
+        val written = runCatching {
+            FileOutputStream(file).use { output.compress(Bitmap.CompressFormat.JPEG, (quality * 100).roundToInt(), it) }
+        }.getOrDefault(false)
+        if (output !== bitmap) output.recycle()
+        bitmap.recycle()
+        return if (written) descriptor(file, "image/jpeg").put("width", width).put("height", height) else null
+    }
+
+    private fun store(bytes: ByteArray, name: String, type: String): CraftNativeCapabilityResult {
+        val file = File(fileRoot, UUID.randomUUID().toString()).apply { mkdirs() }.resolve(safeFileName(name))
+        return runCatching { file.writeBytes(bytes); success(descriptor(file, type)) }
+            .getOrElse { failure("WRITE_ERROR", it.message ?: "File could not be written") }
+    }
+
+    private fun descriptor(file: File, type: String): JSONObject = JSONObject()
+        .put("path", file.absolutePath)
+        .put("name", file.name)
+        .put("type", type)
+        .put("size", file.length())
+
+    private fun sweepFiles() {
+        val cutoff = System.currentTimeMillis() - 24L * 60L * 60L * 1000L
+        fileRoot.listFiles()?.forEach { file ->
+            if (file.lastModified() < cutoff) file.deleteRecursively()
+        }
+    }
+
+    private fun ownedFile(path: String): File? {
+        if (path.isBlank()) return null
+        val root = runCatching { fileRoot.canonicalFile }.getOrNull() ?: return null
+        val file = runCatching { File(path).canonicalFile }.getOrNull() ?: return null
+        return file.takeIf { it.path.startsWith(root.path + File.separator) }
+    }
+
+    private fun safeFileName(raw: String): String {
+        val name = raw.substringAfterLast('/').substringAfterLast('\\').trim()
+        return name.ifBlank { "file" }.replace(Regex("[\\\\/:*?\"<>|\\r\\n]"), "_")
+    }
+
+    private fun jpegName(raw: String): String {
+        val safe = safeFileName(raw)
+        val base = safe.substringBeforeLast('.', safe).ifBlank { "photo" }
+        return "$base.jpg"
+    }
+
+    private fun quoted(value: String): String = value.replace("\\", "%5C").replace("\"", "%22").replace("\r", "%0D").replace("\n", "%0A")
+    private fun headerValue(value: String): String = value.replace("\r", "").replace("\n", "")
+    private fun validURL(raw: String): URL? = runCatching { URL(raw) }.getOrNull()?.takeIf { it.protocol.lowercase() in setOf("http", "https") && it.host.isNotBlank() }
+
     private fun complete(
         requestToken: String,
         result: CraftNativeCapabilityResult,