craft-native 0.0.222 → 0.0.223

package/README.md

@@ -536,6 +536,35 @@ it does not change the application's animations or test assertions.
 
 We love contributions! Please see our [contributing guide](../../CONTRIBUTING.md).
 
+### Offline video storage failures
+
+On iOS and Android native screens, `craft.media.keep(url)` rejects with
+`code: 'NO_SPACE'` when the filesystem runs out of room, including wrapped
+URLSession and Android write errors. Treat that separately from connectivity:
+stop downloading and let the person free space before retrying the same URL.
+A failed transfer is never published as a playable cached video.
+`craft.media.prune(keepUrls)` removes only unwanted files in the media cache;
+it does not clear app storage, workout progress, snapshots or databases.
+
+The Bun-only testing entrypoint verifies those guarantees on native devices:
+
+```ts
+import { verifyMobileMediaCache } from 'craft-native/testing'
+
+await verifyMobileMediaCache({ platform: 'ios' }) // creates and deletes its own simulator
+await verifyMobileMediaCache({ platform: 'android', device: 'emulator-5554', online: true })
+```
+
+Android requires an explicitly selected rootable AOSP emulator and an installed
+Gradle CLI. Xcode and an available simulator runtime are required for iOS. The
+probe uses a bounded 16 MB disk image on iOS and a 16 MB tmpfs mounted only over
+the probe's cache on Android. The Android cache keeps its app UID and SELinux
+label; enforcement stays on. It never fills the host disk or an athlete's data partition. It
+checks `NO_SPACE`, partial-file cleanup, preserved state outside the cache,
+redownloading, interrupted transfers and decoding a local video frame. Set
+`storageOnly: true` for only the disk-full cases, or `sourceRoot` to Craft's
+absolute `packages` path during upstream development before publication.
+
 ## License
 
 MIT © [Chris Breuer](https://github.com/chrisbbreuer)

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

@@ -1093,7 +1093,10 @@ internal object CraftNativeMedia {
                     connection.disconnect()
                 }
             }.getOrElse { error ->
-                CraftNativeCapabilityResult(code = if (error is java.net.SocketTimeoutException) "TIMEOUT" else "NETWORK_ERROR", message = error.message ?: "media.keep failed")
+                val full = generateSequence(error) { it.cause }.take(16).any {
+                    it is android.system.ErrnoException && it.errno == android.system.OsConstants.ENOSPC
+                }
+                CraftNativeCapabilityResult(code = if (full) "NO_SPACE" else if (error is java.net.SocketTimeoutException) "TIMEOUT" else "NETWORK_ERROR", message = error.message ?: "media.keep failed")
             }
             val waiting = synchronized(inFlight) { inFlight.remove(address) ?: mutableListOf() }
             main.post { waiting.forEach { it(result) } }

package/dist/cli.js

@@ -3424,7 +3424,7 @@ function pinCraftNativeDependency(packagePath, craftVersion) {
 `);
 }
 // package.json
-var version = "0.0.222";
+var version = "0.0.223";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];

package/dist/index.cjs

@@ -309,7 +309,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.222";
+var version = "0.0.223";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/index.js

@@ -57,7 +57,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.222";
+var version = "0.0.223";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/ios/templates/CraftNativeActions.swift

@@ -794,7 +794,7 @@ enum CraftNativeActions {
                     return
                 }
                 let code = (error as? URLError)?.code == .timedOut ? "TIMEOUT" : "NETWORK_ERROR"
-                CraftNativeMedia.finish(address, failure(code, error.localizedDescription))
+                CraftNativeMedia.finish(address, failure(CraftNativeMedia.errorCode(error, fallback: code), error.localizedDescription))
                 return
             }
             guard let http = response as? HTTPURLResponse, let location else {

package/dist/ios/templates/CraftNativeFiles.swift

@@ -492,6 +492,20 @@ enum CraftNativeFiles {
 // JavaScript. The screen decides what to keep (`keep`) and what to drop
 // (`prune`); nothing is evicted behind its back.
 enum CraftNativeMedia {
+    /// Foundation often wraps ENOSPC inside a URL or Cocoa file error.
+    static func errorCode(_ error: Error, fallback: String) -> String {
+        var cause: NSError? = error as NSError
+        var seen = Set<ObjectIdentifier>()
+        while let current = cause, seen.insert(ObjectIdentifier(current)).inserted {
+            if (current.domain == NSCocoaErrorDomain && current.code == NSFileWriteOutOfSpaceError)
+                || (current.domain == NSPOSIXErrorDomain && current.code == Int(POSIXError.Code.ENOSPC.rawValue)) {
+                return "NO_SPACE"
+            }
+            cause = current.userInfo[NSUnderlyingErrorKey] as? NSError
+        }
+        return fallback
+    }
+
     static var root: URL {
         let base = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask).first
             ?? FileManager.default.temporaryDirectory
@@ -578,7 +592,7 @@ enum CraftNativeMedia {
             return .success(describe(address, target))
         }
         catch {
-            return .failure(CraftNativeActionError(code: "IO_ERROR", message: "media.keep could not store the file: \(error.localizedDescription)"))
+            return .failure(CraftNativeActionError(code: errorCode(error, fallback: "IO_ERROR"), message: "media.keep could not store the file: \(error.localizedDescription)"))
         }
     }
 

package/dist/mobile-media-testing.d.ts

@@ -0,0 +1,18 @@
+export interface MobileMediaCacheTestOptions {
+    platform: 'ios' | 'android';
+    /** An owned simulator UUID, or emulator serial. iOS creates a disposable simulator when omitted. */
+    device?: string;
+    /** Unpublished Craft's packages directory; installed SDK templates are used by default. */
+    sourceRoot?: string;
+    storageOnly?: boolean;
+    /** Installed Gradle CLI (8.11.1 or compatible). */
+    gradle?: string;
+    /** Allow Gradle to resolve build dependencies. Defaults to offline. */
+    online?: boolean;
+    log?: (line: string) => void;
+}
+/** Real ENOSPC, cache cleanup, retry, coalescing and offline video decode on an isolated native probe. */
+export declare function verifyMobileMediaCache(options: MobileMediaCacheTestOptions): Promise<{
+    platform: string;
+    requests: Record<string, number>;
+}>;

package/dist/mobile-testing.d.ts

@@ -1,3 +1,5 @@
+export { verifyMobileMediaCache } from './mobile-media-testing.js';
+export type { MobileMediaCacheTestOptions } from './mobile-media-testing.js';
 export type MobileTestDeviceOptions = {
     platform: 'ios';
     device: string;

package/dist/mobile-testing.js

@@ -1,14 +1,270 @@
 // @bun
 // src/mobile-testing.ts
 import { access } from "fs/promises";
+import { isAbsolute as isAbsolute2, join as join2 } from "path";
+
+// src/mobile-media-testing.ts
+import { existsSync } from "fs";
+import { mkdir, mkdtemp, rm } from "fs/promises";
+import { homedir, tmpdir } from "os";
 import { isAbsolute, join } from "path";
+async function verifyMobileMediaCache(options) {
+  if (options.platform !== "ios" && options.platform !== "android")
+    throw new Error("Choose ios or android");
+  if (options.platform === "android" && !/^emulator-\d+$/.test(options.device || ""))
+    throw new Error("An explicit disposable Android emulator serial is required");
+  if (options.platform === "ios" && options.device && !/^[a-f\d]{8}(?:-[a-f\d]{4}){3}-[a-f\d]{12}$/i.test(options.device))
+    throw new Error("An explicit iOS simulator UUID is required");
+  if (options.sourceRoot && !isAbsolute(options.sourceRoot))
+    throw new Error("sourceRoot must be an absolute local path");
+  const root = options.sourceRoot || import.meta.dir;
+  const packagedFixtures = join(import.meta.dir, "testing/media-cache");
+  const fixtures = existsSync(packagedFixtures) ? packagedFixtures : join(import.meta.dir, "../fixtures/media-cache");
+  const print = options.log || console.log;
+  const storageOnly = options.storageOnly === true;
+  const scratch = await mkdtemp(join(tmpdir(), "craft-media-probe-"));
+  const bytes = new Uint8Array(await Bun.file(join(fixtures, "demo.mp4")).arrayBuffer());
+  const counts = new Map;
+  const timers = new Set;
+  const server = Bun.listen({
+    hostname: "0.0.0.0",
+    port: 0,
+    socket: {
+      open(socket) {
+        socket.data = { request: "", answered: false };
+      },
+      data(socket, input) {
+        socket.data.request += new TextDecoder().decode(input);
+        if (socket.data.answered || !socket.data.request.includes(`\r
+\r
+`))
+          return;
+        socket.data.answered = true;
+        const path = socket.data.request.split(" ")[1];
+        const n = (counts.get(path) || 0) + 1;
+        counts.set(path, n);
+        const empty = path.endsWith("/empty.mp4");
+        const partial = path.endsWith("/partial.mp4");
+        const cut = (path.endsWith("/broken.mp4") || path.endsWith("/restart.mp4")) && n === 1;
+        const slow = path.endsWith("/slow.mp4") || path.endsWith("/restart.mp4") && n === 1;
+        socket.write(`HTTP/1.1 ${partial ? "206 Partial Content" : "200 OK"}\r
+Content-Type: video/mp4\r
+Content-Length: ${empty ? 0 : bytes.length}\r
+Connection: close\r
+\r
+`);
+        if (empty) {
+          socket.end();
+          return;
+        }
+        socket.write(bytes.subarray(0, Math.floor(bytes.length / 2)));
+        if (cut && !slow) {
+          socket.end();
+          return;
+        }
+        const finish = () => {
+          if (!cut)
+            socket.write(bytes.subarray(Math.floor(bytes.length / 2)));
+          socket.end();
+        };
+        if (slow) {
+          const timer = setTimeout(() => {
+            timers.delete(timer);
+            finish();
+          }, cut ? 60000 : 700);
+          timers.add(timer);
+        } else
+          finish();
+      },
+      error() {},
+      drain() {}
+    }
+  });
+  async function run(args, cwd = scratch, allowedFailure = false) {
+    const proc = Bun.spawn(args, { cwd, env: { ...process.env, ANDROID_HOME: process.env.ANDROID_HOME || join(homedir(), "Library/Android/sdk") }, stdout: "pipe", stderr: "pipe", timeout: 180000 });
+    const [output, errors, status] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+    if (status && !allowedFailure)
+      throw new Error(`${args[0]} failed (${status}):
+${output}
+${errors}`);
+    return output + errors;
+  }
+  let simulator = "";
+  let ownsSimulator = false;
+  const packageName = "dev.craft.mediaprobe";
+  const sdk = process.env.ANDROID_HOME || join(homedir(), "Library/Android/sdk");
+  const adb = join(sdk, "platform-tools/adb");
+  let serial = "";
+  let mountedVolume = "";
+  let mountedAndroidCache = "";
+  try {
+    if (options.platform === "ios") {
+      const files = await Bun.file(join(root, "ios/templates/CraftNativeFiles.swift")).text();
+      const media = files.slice(files.indexOf("enum CraftNativeMedia {"));
+      if (!media.startsWith("enum CraftNativeMedia"))
+        throw new Error("iOS media implementation missing");
+      const source = join(scratch, "main.swift");
+      const isolated = media.replace(/static var root: URL \{[\s\S]*?\n    \}/, 'static var root: URL { CommandLine.arguments.count > 3 ? URL(fileURLWithPath: CommandLine.arguments[3]) : URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent("hq-download-probe-media") }');
+      await Bun.write(source, `import Foundation
+import CryptoKit
+struct CraftNativeActionError: Error { let code: String;
+  let message: String }
+${isolated}
+${await Bun.file(join(fixtures, "media-cache.swift.fixture")).text()}`);
+      const iosSDK = (await run(["xcrun", "--sdk", "iphonesimulator", "--show-sdk-path"])).trim();
+      const executable = join(scratch, "CraftMediaProbe");
+      const architecture = process.arch === "arm64" ? "arm64" : "x86_64";
+      await run(["xcrun", "swiftc", "-sdk", iosSDK, "-target", `${architecture}-apple-ios17.0-simulator`, source, "-o", executable]);
+      await run(["codesign", "--force", "--sign", "-", executable]);
+      simulator = options.device || "";
+      if (!simulator) {
+        const runtimes = JSON.parse(await run(["xcrun", "simctl", "list", "runtimes", "-j"])).runtimes;
+        const runtime = runtimes.filter((r) => r.isAvailable && /^com\.apple\.CoreSimulator\.SimRuntime\.iOS-/.test(r.identifier)).sort((a, b) => b.version.localeCompare(a.version, undefined, { numeric: true }))[0];
+        if (!runtime)
+          throw new Error("Install an available iOS simulator runtime");
+        simulator = (await run(["xcrun", "simctl", "create", "Craft Media Cache QA", "com.apple.CoreSimulator.SimDeviceType.iPhone-16", runtime.identifier])).trim();
+        ownsSimulator = true;
+        await run(["xcrun", "simctl", "boot", simulator]);
+        await run(["xcrun", "simctl", "bootstatus", simulator, "-b"]);
+      }
+      const base = `http://127.0.0.1:${server.port}/ios`;
+      const image = join(scratch, "cache-pressure.sparseimage");
+      const volume = join(scratch, "cache-volume");
+      await mkdir(volume);
+      await run(["hdiutil", "create", "-size", "16m", "-fs", "HFS+", "-volname", "HQCachePressure", "-type", "SPARSE", image]);
+      await run(["hdiutil", "attach", "-nobrowse", "-mountpoint", volume, image]);
+      mountedVolume = volume;
+      print(await run(["xcrun", "simctl", "spawn", simulator, executable, base, "storage", join(volume, "craft-media")]));
+      await run(["hdiutil", "detach", mountedVolume]);
+      mountedVolume = "";
+      print("PASS: iOS native ENOSPC, cache cleanup, progress preservation and video redownload");
+      if (!storageOnly) {
+        print(await run(["xcrun", "simctl", "spawn", simulator, executable, base, "normal"]));
+        const interrupted = await run(["xcrun", "simctl", "spawn", simulator, executable, base, "interrupt"], scratch, true);
+        print(interrupted);
+        if (!interrupted.includes("KILLING"))
+          throw new Error("iOS probe did not reach process-death checkpoint");
+        if (counts.get("/ios/restart.mp4") !== 1)
+          throw new Error("iOS process did not start interrupted download");
+        print(await run(["xcrun", "simctl", "spawn", simulator, executable, base, "recover"]));
+        if (counts.get("/ios/slow.mp4") !== 1)
+          throw new Error("iOS duplicate fetch: keep did not coalesce");
+        print("PASS: iOS simulator interruption, restart, retry, prune and cached video decode");
+      }
+    }
+    if (options.platform === "android") {
+      serial = options.device || "";
+      if (!/^emulator-\d+$/.test(serial))
+        throw new Error("Select a disposable Android emulator with ANDROID_SERIAL");
+      const shell = await Bun.file(join(root, "android/templates/CraftNativeShell.kt.template")).text();
+      const media = shell.match(/internal object CraftNativeMedia \{[\s\S]*?\n\}/)?.[0];
+      if (!media)
+        throw new Error("Android media implementation missing");
+      const android = join(scratch, "android");
+      const app = join(android, "app");
+      const sources = join(app, "src/main/java/dev/craft/mediaprobe");
+      await mkdir(sources, { recursive: true });
+      await Bun.write(join(android, "settings.gradle.kts"), `pluginManagement { repositories { google(); mavenCentral(); gradlePluginPortal() } }
+dependencyResolutionManagement { repositories { google(); mavenCentral() } }
+rootProject.name = "HQDownloadProbe"
+include(":app")`);
+      await Bun.write(join(android, "build.gradle.kts"), 'plugins { id("com.android.application") version "8.9.1" apply false; id("org.jetbrains.kotlin.android") version "2.0.21" apply false }');
+      await Bun.write(join(android, "local.properties"), `sdk.dir=${sdk}
+`);
+      await Bun.write(join(android, "gradle.properties"), `org.gradle.jvmargs=-Xmx768m
+org.gradle.workers.max=2
+`);
+      await Bun.write(join(app, "build.gradle.kts"), `plugins { id("com.android.application");
+  id("org.jetbrains.kotlin.android") }
+android { namespace = "${packageName}";
+  compileSdk = 36;
+  defaultConfig { applicationId = "${packageName}";
+  minSdk = 26;
+  targetSdk = 35 };
+  compileOptions { sourceCompatibility = JavaVersion.VERSION_17;
+  targetCompatibility = JavaVersion.VERSION_17 };
+  kotlinOptions { jvmTarget = "17" } }`);
+      await Bun.write(join(app, "src/main/AndroidManifest.xml"), `<manifest xmlns:android="http://schemas.android.com/apk/res/android"><uses-permission android:name="android.permission.INTERNET"/><uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/><application android:usesCleartextTraffic="true" android:label="HQ Download Probe"/><instrumentation android:name=".DownloadProbe" android:targetPackage="${packageName}"/></manifest>`);
+      await Bun.write(join(sources, "DownloadProbe.kt"), `package ${packageName}
+import android.content.Context
+import android.net.Uri
+import android.os.Handler
+import android.os.Looper
+import org.json.JSONObject
+import java.io.File
+import java.util.concurrent.Executors
+internal data class CraftNativeCapabilityResult(val data: Any? = null, val code: String? = null, val message: String? = null)
+${media}
+${await Bun.file(join(fixtures, "media-cache.kt")).text()}`);
+      await run([options.gradle || process.env.GRADLE_EXECUTABLE || "gradle", ...options.online ? [] : ["--offline"], "--no-daemon", ":app:assembleDebug"], android);
+      print(await run([adb, "-s", serial, "install", "-r", join(app, "build/outputs/apk/debug/app-debug.apk")]));
+      const base = `http://10.0.2.2:${server.port}/android`;
+      const probe = async (phase, interrupted = false) => {
+        const result = await run([adb, "-s", serial, "shell", "am", "instrument", "-w", "-e", "base", base, "-e", "phase", phase, `${packageName}/.DownloadProbe`], scratch, interrupted);
+        if (!interrupted && (!result.includes("PASS:") || result.includes("FAIL:")))
+          throw new Error(result);
+        print(result);
+      };
+      await run([adb, "-s", serial, "root"]);
+      await run([adb, "-s", serial, "wait-for-device"]);
+      if ((await run([adb, "-s", serial, "shell", "id", "-u"])).trim() !== "0")
+        throw new Error("Storage fault tests require a rootable disposable AOSP emulator");
+      await run([adb, "-s", serial, "shell", "run-as", packageName, "mkdir", "-p", "files/craft-media"]);
+      const cache = `/data/user/0/${packageName}/files/craft-media`;
+      const owner = (await run([adb, "-s", serial, "shell", "stat", "-c", "%u:%g", cache])).trim();
+      const label = (await run([adb, "-s", serial, "shell", "ls", "-Zd", cache])).trim().split(/\s+/)[0];
+      if (!/^\d+:\d+$/.test(owner) || !/^u:object_r:app_data_file:s0(?::c\d+(?:,c\d+)*)?$/.test(label))
+        throw new Error("Unexpected probe cache ownership or SELinux label");
+      const [uid, gid] = owner.split(":");
+      await run([adb, "-s", serial, "shell", "mount", "-t", "tmpfs", "-o", `size=16m,mode=700,uid=${uid},gid=${gid}`, "tmpfs", cache]);
+      mountedAndroidCache = cache;
+      await run([adb, "-s", serial, "shell", "chcon", label, cache]);
+      await probe("storage");
+      await run([adb, "-s", serial, "shell", "am", "force-stop", packageName]);
+      await run([adb, "-s", serial, "shell", "umount", mountedAndroidCache]);
+      mountedAndroidCache = "";
+      print("PASS: Android native ENOSPC, cache cleanup, progress preservation and video redownload");
+      if (!storageOnly) {
+        await probe("normal");
+        await probe("interrupt", true);
+        if (counts.get("/android/restart.mp4") !== 1)
+          throw new Error("Android process did not start interrupted download");
+        await probe("recover");
+        if (counts.get("/android/slow.mp4") !== 1)
+          throw new Error("Android duplicate fetch: keep did not coalesce");
+        print("PASS: Android emulator interruption, restart, retry, prune and cached video decode");
+      }
+    }
+  } finally {
+    print(JSON.stringify({ requests: Object.fromEntries(counts) }));
+    if (mountedVolume)
+      await run(["hdiutil", "detach", mountedVolume]);
+    if (mountedAndroidCache) {
+      await run([adb, "-s", serial, "shell", "am", "force-stop", packageName], scratch, true);
+      await run([adb, "-s", serial, "shell", "umount", mountedAndroidCache]);
+    }
+    if (simulator && ownsSimulator) {
+      await run(["xcrun", "simctl", "shutdown", simulator], scratch, true);
+      await run(["xcrun", "simctl", "delete", simulator], scratch, true);
+    }
+    if (serial)
+      await run([adb, "-s", serial, "uninstall", packageName], scratch, true);
+    for (const timer of timers)
+      clearTimeout(timer);
+    server.stop(true);
+    await rm(scratch, { recursive: true, force: true });
+  }
+  return { platform: options.platform, requests: Object.fromEntries(counts) };
+}
+
+// src/mobile-testing.ts
 function requireIosSimulator(device) {
   if (!/^[a-f\d]{8}(?:-[a-f\d]{4}){3}-[a-f\d]{12}$/i.test(device))
     throw new Error("An explicit iOS simulator UUID is required");
 }
 async function recordIosSimulatorVideo(options) {
   requireIosSimulator(options.device);
-  if (!isAbsolute(options.path))
+  if (!isAbsolute2(options.path))
     throw new Error("A local absolute recording path is required");
   const timeout = options.timeoutMs ?? 30000;
   if (!Number.isSafeInteger(timeout) || timeout < 1)
@@ -120,7 +376,7 @@ ${errors || output}`);
   async function installedBuild() {
     if (options.platform === "ios") {
       const app = await ios("get_app_container", options.device, options.appId, "app");
-      return run(["/usr/libexec/PlistBuddy", "-c", "Print :CFBundleVersion", join(app, "Info.plist")]);
+      return run(["/usr/libexec/PlistBuddy", "-c", "Print :CFBundleVersion", join2(app, "Info.plist")]);
     }
     const result = await android("shell", "dumpsys", "package", options.appId);
     const version = result.match(/\bversionCode=(\d+)/)?.[1];
@@ -154,7 +410,7 @@ ${errors || output}`);
   async function installUpdate(artifact) {
     const previousBuild = await installedBuild();
     if (options.platform === "ios") {
-      const id = await run(["/usr/libexec/PlistBuddy", "-c", "Print :CFBundleIdentifier", join(artifact, "Info.plist")]);
+      const id = await run(["/usr/libexec/PlistBuddy", "-c", "Print :CFBundleIdentifier", join2(artifact, "Info.plist")]);
       if (id !== options.appId)
         throw new Error("Update bundle identifier differs from the installed app");
       await ios("install", options.device, artifact);
@@ -167,6 +423,7 @@ ${errors || output}`);
   return { restart, installUpdate, installedBuild };
 }
 export {
+  verifyMobileMediaCache,
   recordIosSimulatorVideo,
   createMobileTestDevice
 };

package/dist/testing/media-cache/media-cache.kt

@@ -0,0 +1,123 @@
+class DownloadProbe : android.app.Instrumentation() {
+    override fun onCreate(arguments: android.os.Bundle?) {
+        super.onCreate(arguments)
+        args = arguments ?: android.os.Bundle()
+        start()
+    }
+    private var args = android.os.Bundle()
+    private var latestErrorCode: String? = null
+    private val proof = StringBuilder()
+    private fun check(yes: Boolean, message: String) {
+        if (!yes) throw IllegalStateException(message)
+        proof.append("PASS: ").append(message).append('\n')
+        android.util.Log.i("CraftMediaProbe", "PASS: $message")
+    }
+    private fun keep(address: String): Boolean {
+        val done = java.util.concurrent.CountDownLatch(1)
+        var ok = false
+        CraftNativeMedia.keep(targetContext, address, JSONObject(), true) {
+            latestErrorCode = it.code
+            ok = (it.data as? JSONObject)?.optBoolean("ok") == true
+            done.countDown()
+        }
+        check(done.await(25, java.util.concurrent.TimeUnit.SECONDS), "operation settled")
+        return ok
+    }
+    override fun onStart() {
+        val result = android.os.Bundle()
+        try {
+            val base = args.getString("base")!!
+            val restart = "$base/restart.mp4"
+            when (args.getString("phase")) {
+                "storage" -> {
+                    CraftNativeMedia.prune(targetContext, emptyList())
+                    val prefs = targetContext.getSharedPreferences("workout-recovery-probe", Context.MODE_PRIVATE)
+                    val progress = """{"sets":["A1"],"note":"Keep this workout","rpe":7}"""
+                    check(prefs.edit().putString("progress", progress).commit(), "workout progress is durable before storage failure")
+                    val prefsDisk = File(targetContext.applicationInfo.dataDir, "shared_prefs/workout-recovery-probe.xml")
+                    val savedPrefs = prefsDisk.readBytes()
+                    val retained = "$base/retained.mp4"
+                    check(keep(retained), "existing video is kept before storage pressure")
+                    val original = CraftNativeMedia.local(targetContext, retained)!!.readBytes()
+                    val fresh = "$base/storage.mp4"
+                    val staging = File(CraftNativeMedia.file(targetContext, fresh).absolutePath + ".part")
+                    val root = staging.parentFile!!
+                    check(root.totalSpace in 1..(32L * 1024 * 1024), "storage pressure is confined to a bounded disposable volume")
+                    val pressure = File(root, "pressure.mp4")
+                    var written = 0L
+                    pressure.outputStream().use { output ->
+                        for (size in listOf(65536, 1024)) {
+                            val chunk = ByteArray(size) { 0x5A.toByte() }
+                            while (written < 32L * 1024 * 1024) {
+                                try { output.write(chunk); written += size }
+                                catch (error: java.io.IOException) { break }
+                            }
+                        }
+                    }
+                    check(written > 0 && root.usableSpace < 1024, "the probe cache filesystem is actually full")
+                    check(!keep(fresh), "out-of-space write refuses a new video")
+                    check(latestErrorCode == "NO_SPACE", "a full disk is reported as NO_SPACE, not a network failure")
+                    check(CraftNativeMedia.local(targetContext, fresh) == null, "storage failure never publishes a partial video")
+                    check(!staging.exists(), "storage failure removes staging files")
+                    check(CraftNativeMedia.local(targetContext, retained)!!.readBytes().contentEquals(original), "storage failure preserves an existing video")
+                    check(CraftNativeMedia.prune(targetContext, listOf(retained)) == 1, "cache cleanup frees the obsolete file and preserves the retained video")
+                    check(prefs.getString("progress", null) == progress && prefsDisk.readBytes().contentEquals(savedPrefs), "cache cleanup preserves workout progress and feedback on disk")
+                    check(keep(fresh), "same missing video downloads after cleanup")
+                    val decoder = android.media.MediaMetadataRetriever()
+                    try {
+                        decoder.setDataSource(CraftNativeMedia.local(targetContext, fresh)!!.absolutePath)
+                        check(decoder.getFrameAtTime(1000000) != null, "downloaded replacement plays from its local file")
+                    } finally { decoder.release() }
+                    check(prefs.getString("progress", null) == progress && prefsDisk.readBytes().contentEquals(savedPrefs), "redownloading leaves workout progress and feedback unchanged on disk")
+                    CraftNativeMedia.prune(targetContext, emptyList())
+                    prefs.edit().clear().commit()
+                }
+                "interrupt" -> {
+                    CraftNativeMedia.prune(targetContext, emptyList())
+                    CraftNativeMedia.keep(targetContext, restart, JSONObject(), true) {}
+                    val part = File(CraftNativeMedia.file(targetContext, restart).absolutePath + ".part")
+                    val until = System.currentTimeMillis() + 25000
+                    while ((!part.exists() || part.length() == 0L) && System.currentTimeMillis() < until) Thread.sleep(25)
+                    check(part.length() > 0, "download is in progress before process death")
+                    android.os.Process.killProcess(android.os.Process.myPid())
+                }
+                "recover" -> {
+                    check(CraftNativeMedia.local(targetContext, restart) == null, "interrupted process never published a partial video")
+                    check(keep(restart), "retry after process death downloads a complete video")
+                    val media = android.media.MediaMetadataRetriever()
+                    try {
+                        media.setDataSource(CraftNativeMedia.local(targetContext, restart)!!.absolutePath)
+                        check(media.getFrameAtTime(1000000) != null, "recovered local video decodes a frame without network")
+                    } finally { media.release() }
+                    CraftNativeMedia.prune(targetContext, emptyList())
+                }
+                else -> {
+                    CraftNativeMedia.prune(targetContext, emptyList())
+                    val broken = "$base/broken.mp4"
+                    check(!keep(broken), "truncated transfer fails")
+                    check(CraftNativeMedia.local(targetContext, broken) == null, "truncated transfer is not playable cache")
+                    val root = CraftNativeMedia.file(targetContext, broken).parentFile!!
+                    check(root.listFiles()?.none { it.name.endsWith(".part") } != false, "failed transfer cleans staging files")
+                    check(keep(broken), "same URL retries successfully")
+                    check(!keep("$base/partial.mp4"), "unsolicited partial response is refused")
+                    check(!keep("$base/empty.mp4"), "empty file is refused")
+                    val slow = "$base/slow.mp4"
+                    val done = java.util.concurrent.CountDownLatch(2)
+                    val answers = java.util.Collections.synchronizedList(mutableListOf<Boolean>())
+                    repeat(2) { CraftNativeMedia.keep(targetContext, slow, JSONObject(), true) { answers.add((it.data as? JSONObject)?.optBoolean("ok") == true); done.countDown() } }
+                    Thread.sleep(150)
+                    CraftNativeMedia.prune(targetContext, emptyList())
+                    check(done.await(25, java.util.concurrent.TimeUnit.SECONDS), "coalesced downloads settled")
+                    check(answers.size == 2 && answers.all { it }, "concurrent downloads coalesce and survive prune")
+                    check(root.listFiles()?.none { it.name.endsWith(".part") } != false, "no abandoned staging files remain")
+                    CraftNativeMedia.prune(targetContext, emptyList())
+                }
+            }
+            result.putString("stream", "${proof}PASS: ${args.getString("phase")} native download probe")
+            finish(-1, result)
+        } catch (error: Throwable) {
+            result.putString("stream", "${proof}FAIL: ${error.stackTraceToString()}")
+            finish(1, result)
+        }
+    }
+}

package/dist/testing/media-cache/media-cache.swift.fixture

@@ -0,0 +1,118 @@
+// Compiled with the released CraftNativeMedia into an iOS simulator process.
+import AVFoundation
+
+let base = CommandLine.arguments[1]
+let phase = CommandLine.arguments[2]
+let fm = FileManager.default
+func check(_ yes: @autoclosure () -> Bool, _ message: String) {
+    guard yes() else { print("FAIL: \(message)"); exit(1) }
+    print("PASS: \(message)")
+}
+func wait(_ ready: () -> Bool) {
+    let limit = Date().addingTimeInterval(25)
+    while !ready() && Date() < limit { RunLoop.current.run(until: Date().addingTimeInterval(0.01)) }
+    check(ready(), "operation settled")
+}
+var latestTask: URLSessionTask?
+var latestErrorCode: String?
+func start(_ address: String, _ done: @escaping (Bool) -> Void) {
+    if let local = CraftNativeMedia.local(address) { done((CraftNativeMedia.describe(address, local)["size"] as? Int ?? 0) > 0); return }
+    if CraftNativeMedia.join(address, { result in
+        if case .success(let data) = result { done((data as? [String: Any])?["ok"] as? Bool == true) }
+        else if case .failure(let error) = result { latestErrorCode = error.code; done(false) }
+    }) { return }
+    let task = URLSession.shared.downloadTask(with: URL(string: address)!) { location, response, error in
+        let result: Result<Any, CraftNativeActionError>
+        if error != nil { result = .failure(CraftNativeActionError(code: "NETWORK_ERROR", message: "Interrupted")) }
+        else if let location, let response = response as? HTTPURLResponse { result = CraftNativeMedia.store(address, at: location, response: response) }
+        else { result = .failure(CraftNativeActionError(code: "NETWORK_ERROR", message: "No file")) }
+        CraftNativeMedia.finish(address, result)
+    }
+    latestTask = task
+    task.resume()
+}
+func keep(_ address: String) -> Bool {
+    var result: Bool?
+    start(address) { result = $0 }
+    wait { result != nil }
+    return result!
+}
+let restart = base + "/restart.mp4"
+if phase == "storage" {
+    let volume = CraftNativeMedia.root.deletingLastPathComponent()
+    let capacity = try volume.resourceValues(forKeys: [.volumeTotalCapacityKey]).volumeTotalCapacity ?? 0
+    check(capacity > 0 && capacity <= 32 * 1024 * 1024, "storage pressure is confined to a bounded disposable volume")
+    let progress = volume.appendingPathComponent("workout-progress.json")
+    let saved = Data(#"{"sets":["A1"],"note":"Keep this workout","rpe":7}"#.utf8)
+    try saved.write(to: progress)
+    let pressure = volume.appendingPathComponent("pressure")
+    defer { try? fm.removeItem(at: pressure); try? fm.removeItem(at: progress) }
+    let retained = base + "/retained.mp4"
+    check(keep(retained), "existing video is kept before storage pressure")
+    let original = try Data(contentsOf: CraftNativeMedia.local(retained)!)
+    fm.createFile(atPath: pressure.path, contents: nil)
+    let writer = try FileHandle(forWritingTo: pressure)
+    var written = 0
+    for size in [65536, 1024] {
+        let chunk = Data(repeating: 0x5A, count: size)
+        while written < 32 * 1024 * 1024 {
+            do { try writer.write(contentsOf: chunk); written += size }
+            catch { break }
+        }
+    }
+    try writer.close()
+    let fresh = base + "/storage.mp4"
+    check(!keep(fresh), "full cache volume refuses a new video")
+    check(latestErrorCode == "NO_SPACE", "a full disk is reported as NO_SPACE, not a network failure")
+    check(CraftNativeMedia.local(fresh) == nil, "storage failure never publishes a partial video")
+    check((try? Data(contentsOf: CraftNativeMedia.local(retained)!)) == original, "storage failure preserves an existing video")
+    check(((try? fm.contentsOfDirectory(atPath: CraftNativeMedia.root.path)) ?? []).allSatisfy { !$0.hasSuffix(".part") }, "storage failure removes staging files")
+    check(CraftNativeMedia.prune(keep: []) == 1, "cache cleanup frees only the retained video")
+    check((try? Data(contentsOf: progress)) == saved, "cache cleanup preserves workout progress and feedback")
+    check(keep(fresh), "same missing video downloads after cache cleanup frees space")
+    let generator = AVAssetImageGenerator(asset: AVURLAsset(url: CraftNativeMedia.local(fresh)!))
+    do { _ = try generator.copyCGImage(at: CMTime(seconds: 1, preferredTimescale: 600), actualTime: nil) }
+    catch { check(false, "downloaded replacement decodes: \(error)") }
+    check(true, "downloaded replacement plays from its local file")
+    check((try? Data(contentsOf: progress)) == saved, "redownloading leaves workout progress and feedback unchanged")
+    _ = CraftNativeMedia.prune(keep: [])
+    exit(0)
+}
+if phase == "interrupt" {
+    _ = CraftNativeMedia.prune(keep: [])
+    start(restart) { _ in }
+    print("INTERRUPTING"); fflush(stdout)
+    wait { (latestTask?.countOfBytesReceived ?? 0) > 0 }
+    print("KILLING"); fflush(stdout)
+    raise(SIGKILL)
+    exit(2)
+}
+if phase == "recover" {
+    check(CraftNativeMedia.local(restart) == nil, "interrupted process never published a partial video")
+    check(keep(restart), "retry after process death downloads a complete video")
+    let local = CraftNativeMedia.local(restart)!
+    let generator = AVAssetImageGenerator(asset: AVURLAsset(url: local))
+    do { _ = try generator.copyCGImage(at: CMTime(seconds: 1, preferredTimescale: 600), actualTime: nil) }
+    catch { check(false, "recovered video decodes offline: \(error)") }
+    check(true, "recovered local video decodes a frame without network")
+    _ = CraftNativeMedia.prune(keep: [])
+    exit(0)
+}
+_ = CraftNativeMedia.prune(keep: [])
+let broken = base + "/broken.mp4"
+check(!keep(broken), "truncated transfer fails")
+check(CraftNativeMedia.local(broken) == nil, "truncated transfer is not playable cache")
+check(keep(broken), "same URL retries successfully")
+check(!keep(base + "/partial.mp4"), "unsolicited partial response is refused")
+check(!keep(base + "/empty.mp4"), "empty file is refused")
+let slow = base + "/slow.mp4"
+var answers = [Bool]()
+start(slow) { answers.append($0) }
+start(slow) { answers.append($0) }
+RunLoop.current.run(until: Date().addingTimeInterval(0.15))
+_ = CraftNativeMedia.prune(keep: [])
+wait { answers.count == 2 }
+check(answers == [true, true], "concurrent downloads coalesce and survive prune")
+let parts = (try? fm.contentsOfDirectory(atPath: CraftNativeMedia.root.path))?.filter { $0.hasSuffix(".part") } ?? []
+check(parts.isEmpty, "no abandoned staging files remain")
+_ = CraftNativeMedia.prune(keep: [])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craft-native",
-  "version": "0.0.222",
+  "version": "0.0.223",
   "type": "module",
   "description": "Build desktop apps with web languages - TypeScript SDK for Craft",
   "author": "Chris Breuer <chris@stacksjs.org>",