craft-native 0.0.276 → 0.0.290

package/README.md

@@ -668,3 +668,19 @@ Browser audio assigns one owner per sound ID. A newer play or stop invalidates
 pending media resolution for that ID; stopping all sounds, changing accounts,
 aborting a call or disposing the host also releases active audio. Superseded
 play calls reject with `AbortError`.
+
+### Packaging sandboxed macOS apps
+
+Pass `macos.appBundlePath` to package a complete STX app without discarding its
+resources. Distribution options also apply to prebuilt bundles: `buildNumber`,
+`provisioningProfile`, `privacyManifest`, and the icon are embedded before signing.
+Craft signs nested Mach-O code before the main bundle and verifies the result.
+Use `helperEntitlements` for a compiled backend's runtime permissions; App Store
+helpers inherit the main sandbox by default. `signingKeychain` selects the
+keychain for both application and installer identities.
+
+Craft's bundled-backend host reads `backend: { executable: 'stx-backend' }` from
+`Contents/Resources/craft.json`. The native app remains the main process, starts
+the helper with `--serve --managed`, and consumes its authenticated loopback URL.
+The helper's standard input is a lifetime lease: it must stop when that pipe
+closes. `craft --capabilities` advertises `bundleBackend` on macOS.

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

@@ -10,6 +10,10 @@ export interface AndroidEmulatorOptions {
     acceptLicenses?: boolean;
     /** Defaults to 10 minutes; hardware is capped there, software cold provisioning at 20 minutes. */
     bootTimeoutMs?: number;
+    /** Requested guest RAM, 1536–8192 MB (Android emulator limits); defaults to 2048. */
+    memoryMb?: number;
+    /** Requested guest CPU count, 1–8; defaults to 2. */
+    virtualCpus?: number;
     env?: Record<string, string | undefined>;
 }
 export interface AndroidEmulatorSession {

package/dist/android/src/index.js

@@ -198,6 +198,12 @@ async function createAndroidEmulator(options) {
   const maximumBootTimeoutMs = options.acceleration === "software" ? 1200000 : 600000;
   if (!Number.isSafeInteger(bootTimeoutMs) || bootTimeoutMs < 1000 || bootTimeoutMs > maximumBootTimeoutMs)
     throw new Error(`Android bootTimeoutMs must be an integer between 1000 and ${maximumBootTimeoutMs} milliseconds`);
+  const memoryMb = options.memoryMb ?? 2048;
+  if (!Number.isSafeInteger(memoryMb) || memoryMb < 1536 || memoryMb > 8192)
+    throw new Error("Android memoryMb must be an integer between 1536 and 8192 megabytes");
+  const virtualCpus = options.virtualCpus ?? 2;
+  if (!Number.isSafeInteger(virtualCpus) || virtualCpus < 1 || virtualCpus > 8)
+    throw new Error("Android virtualCpus must be an integer between 1 and 8");
   const port = options.port ?? 5558;
   if (!Number.isInteger(port) || port < 5554 || port > 5682 || port % 2 !== 0)
     throw new Error("Android console ports must be even and between 5554 and 5682");
@@ -299,7 +305,7 @@ async function createAndroidEmulator(options) {
     const hostCpus = cpus();
     cpuStart = hostCpus.reduce((total, cpu) => total + Object.values(cpu.times).reduce((sum, value) => sum + value, 0), 0);
     idleStart = hostCpus.reduce((total, cpu) => total + cpu.times.idle, 0);
-    child = Bun.spawn([executable, "-avd", name, "-port", String(port), "-no-window", "-no-snapshot", "-no-audio", "-no-boot-anim", "-gpu", "software", "-memory", "2048", "-cores", "2", "-accel", options.acceleration === "software" ? "off" : "on"], { env, stdout: log, stderr: log });
+    child = Bun.spawn([executable, "-avd", name, "-port", String(port), "-no-window", "-no-snapshot", "-no-audio", "-no-boot-anim", "-gpu", "software", "-memory", String(memoryMb), "-cores", String(virtualCpus), "-accel", options.acceleration === "software" ? "off" : "on"], { env, stdout: log, stderr: log });
     identity = {
       image: options.image,
       acceleration: options.acceleration,
@@ -307,8 +313,8 @@ async function createAndroidEmulator(options) {
       bootTimeoutMs,
       bootStartedAt: new Date(bootStartedAt).toISOString(),
       host: { cpuModel: hostCpus[0]?.model, logicalCpus: hostCpus.length, availableParallelism: availableParallelism(), memoryBytes: totalmem() },
-      virtualCpus: 2,
-      memoryMb: 2048,
+      virtualCpus,
+      memoryMb,
       serial,
       avdDirectory: env.ANDROID_AVD_HOME,
       emulatorPid: child.pid
@@ -335,11 +341,13 @@ async function createAndroidEmulator(options) {
           const packages = await run([adb, "-s", serial, "shell", "pm", "path", "android"], undefined, probeTimeout(), true);
           const playStore = requiresPlayStore ? await run([adb, "-s", serial, "shell", "pm", "path", "com.android.vending"], undefined, probeTimeout(), true) : undefined;
           const systemUi = await run([adb, "-s", serial, "shell", "pidof", "com.android.systemui"], undefined, probeTimeout(), true);
-          const events = await run([adb, "-s", serial, "logcat", "-b", "events", "-d", "-t", "1"], undefined, probeTimeout(), true);
+          const events = await run([adb, "-s", serial, "logcat", "-b", "events", "-d", "-v", "threadtime"], undefined, probeTimeout(), true);
           const home = await run([adb, "-s", serial, "shell", "cmd", "package", "resolve-activity", "--brief", "-a", "android.intent.action.MAIN", "-c", "android.intent.category.HOME"], undefined, probeTimeout(), true);
           const homeActivity = home.stdout.trim().split(/\r?\n/).at(-1) ?? "";
-          const temporaryHome = homeActivity.startsWith("com.android.sdksetup/") || /^com\.android\.settings\/(?:\.|com\.android\.settings\.)FallbackHome$/.test(homeActivity) || /^android\/.*(?:Resolver|Chooser)Activity$/.test(homeActivity);
-          booted = settings.code === 0 && packages.code === 0 && systemUi.code === 0 && events.code === 0 && /^package:\/\S+/m.test(packages.stdout) && /^\d+(?:\s+\d+)*$/.test(systemUi.stdout.trim()) && (!requiresPlayStore || playStore?.code === 0 && /^package:\/\S+/m.test(playStore.stdout)) && home.code === 0 && /^[\w.]+\/[\w.$]+$/.test(homeActivity) && !temporaryHome;
+          const temporaryHome = homeActivity.startsWith("com.android.sdksetup/") || homeActivity.startsWith("com.google.android.googlesdksetup/") || /^com\.android\.settings\/(?:\.|com\.android\.settings\.)FallbackHome$/.test(homeActivity) || /^android\/.*(?:Resolver|Chooser)Activity$/.test(homeActivity);
+          const windows = await run([adb, "-s", serial, "shell", "dumpsys", "window"], undefined, probeTimeout(), true);
+          const focusedPackage = windows.stdout.match(/^\s*mCurrentFocus\s*=\s*Window\{[^}\r\n]*\bu\d+\s+([\w.]+)\//m)?.[1];
+          booted = settings.code === 0 && packages.code === 0 && systemUi.code === 0 && events.code === 0 && /^package:\/\S+/m.test(packages.stdout) && /^\d+(?:\s+\d+)*$/.test(systemUi.stdout.trim()) && (!requiresPlayStore || playStore?.code === 0 && /^package:\/\S+/m.test(playStore.stdout)) && home.code === 0 && /^[\w.]+\/[\w.$]+$/.test(homeActivity) && !temporaryHome && windows.code === 0 && focusedPackage === homeActivity.split("/")[0];
         }
       }
       const checkedAt = Date.now();
@@ -845,6 +853,7 @@ function writeNativeShellSources(output, packagePath, packageName, config) {
   };
   write("CraftBluetooth.kt.template", "CraftBluetooth.kt");
   write("CraftNativeShell.kt.template", "CraftNativeShell.kt");
+  write("CraftSnapshotFile.kt.template", "CraftSnapshotFile.kt");
   write("CraftNativeImageCache.kt.template", "CraftNativeImageCache.kt");
   write("CraftNativeHaptics.kt.template", "CraftNativeHaptics.kt");
   write("CraftNativeBackground.kt.template", "CraftNativeBackground.kt");

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

@@ -119,6 +119,10 @@ class CraftNativeMutationDocument {
                         // be reconciled so the host can move its existing view.
                         requiresFullRender = true
                     }
+                    "replaceChildren" -> {
+                        val parentId = replaceChildren(operation, candidateNodes)
+                        if (parentId !in affectedNodeIds) affectedNodeIds.add(parentId)
+                    }
                     "removeNode" -> {
                         val parent = candidateNodes[operation.optString("id")]?.parent
                         if (parent == null) requiresFullRender = true
@@ -257,6 +261,37 @@ class CraftNativeMutationDocument {
         return previousParentId
     }
 
+    /** Replaces a container's ordered child snapshot in one atomic mutation. */
+    private fun replaceChildren(operation: JSONObject, nodes: MutableMap<String, Node>): String {
+        val parentId = requiredId(operation, "parentId", "replaceChildren")
+        val parent = nodes[parentId] ?: fail("UNKNOWN_PARENT", "node $parentId does not exist")
+        if (!acceptsChildren(parent.type)) fail("INVALID_PARENT", "node $parentId cannot contain child nodes")
+        val values = operation.optJSONArray("children")
+            ?: fail("INVALID_CHILDREN", "replaceChildren.children must be an array")
+        val childIds = mutableListOf<String>()
+        for (index in 0 until values.length()) {
+            val childId = values.opt(index) as? String
+            if (childId.isNullOrBlank()) {
+                fail("INVALID_CHILDREN", "replaceChildren.children must contain non-empty ids")
+            }
+            if (childId in childIds) fail("DUPLICATE_CHILD", "child $childId appears more than once")
+            val child = nodes[childId] ?: fail("UNKNOWN_NODE", "node $childId does not exist")
+            if (childId == parentId || parentId in descendants(childId, nodes)) {
+                fail("CYCLE", "attaching node $childId would create a cycle")
+            }
+            if (child.parent != null && child.parent != parentId) {
+                fail("NODE_ATTACHED", "node $childId already has a parent")
+            }
+            childIds.add(childId)
+        }
+        parent.children.filterNot { it in childIds }.forEach { childId ->
+            (descendants(childId, nodes) + childId).forEach { nodes.remove(it) }
+        }
+        parent.children = childIds
+        childIds.forEach { nodes[it]?.parent = parentId }
+        return parentId
+    }
+
     private fun removeNode(
         operation: JSONObject,
         nodes: MutableMap<String, Node>,

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

@@ -270,7 +270,12 @@ internal object CraftNativeStorage {
 
 }
 
-internal class CraftNativeStores private constructor(context: Context, private val secureEnabled: Boolean) {
+internal class CraftNativeStores private constructor(
+    context: Context,
+    private val secureEnabled: Boolean,
+    private val snapshotFiles: CraftSnapshotFile,
+) {
+    private constructor(context: Context, secureEnabled: Boolean) : this(context, secureEnabled, CraftSnapshotFile())
     private val appContext = context.applicationContext
     private val storage: SharedPreferences = appContext.getSharedPreferences("craft-native-storage", Context.MODE_PRIVATE)
     private val snapshotsDir = File(appContext.filesDir, "craft-snapshots").apply { mkdirs() }
@@ -355,20 +360,22 @@ internal class CraftNativeStores private constructor(context: Context, private v
     fun setSnapshot(name: String, json: String?, from: String?, done: (Boolean) -> Unit) {
         writer.execute {
             val file = snapshotFile(name)
+            val previous = snapshotCache[name]
             val ok = runCatching {
                 if (json == null) {
                     !file.exists() || file.delete()
                 } else {
-                    val temporary = File(file.parentFile, "${file.name}.tmp")
-                    temporary.writeText(json)
-                    temporary.renameTo(file) || run { file.writeText(json); temporary.delete(); true }
+                    snapshotFiles.set(file, json)
+                    true
                 }
             }.getOrDefault(false)
             if (ok) {
                 if (json == null) snapshotCache.remove(name) else snapshotCache[name] = json
             }
             main.post {
-                if (ok) changed("snapshots", name, json, null)
+                // Isolates optimistically display their write. Restore the
+                // confirmed value before rejecting an unsuccessful checkpoint.
+                changed("snapshots", name, if (ok) json else previous, null)
                 done(ok)
             }
         }

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

@@ -0,0 +1,26 @@
+package {{PACKAGE_NAME}}
+
+import java.io.File
+import java.io.FileOutputStream
+import java.nio.file.Files
+import java.nio.file.StandardCopyOption
+import java.util.UUID
+
+/** One checkpoint replacement. Filesystem failures must leave the previous checkpoint intact. */
+internal class CraftSnapshotFile(
+    private val write: (File, ByteArray) -> Unit = { file, bytes ->
+        FileOutputStream(file).use { stream -> stream.write(bytes); stream.fd.sync() }
+    },
+    private val replace: (File, File) -> Unit = { source, destination ->
+        Files.move(source.toPath(), destination.toPath(), StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING)
+    },
+) {
+    fun set(destination: File, json: String) {
+        val temporary = File(destination.parentFile, ".craft-snapshot-${UUID.randomUUID()}.tmp")
+        val bytes = json.toByteArray(Charsets.UTF_8)
+        try {
+            write(temporary, bytes)
+            replace(temporary, destination)
+        } finally { temporary.delete() }
+    }
+}

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

@@ -4661,6 +4661,7 @@ class MainActivity : AppCompatActivity() {
             capabilities: ${capabilityNames()},
             initialAppState: ${JSONObject.quote(nativeAppState)},
             colorScheme: ${JSONObject.quote(colorScheme())},
+            viewportWidth: ${resources.configuration.screenWidthDp},
             appearance: ${appearance()},
             appURL: ${JSONObject.quote(config.optString("devServerURL"))},
             appVersion: ${JSONObject.quote(appVersion().first)},
@@ -4909,6 +4910,21 @@ class MainActivity : AppCompatActivity() {
     override fun onConfigurationChanged(newConfig: Configuration) {
         super.onConfigurationChanged(newConfig)
         publishAppearance()
+        publishViewport(newConfig)
+    }
+
+    /// The width the screens last heard, in dp (a web page's CSS pixels).
+    private var reportedViewportWidth = -1
+
+    /// Rotation, split screen or a resized window: the bundle's width classes
+    /// (`md:`, `lg:`) follow the window's new width.
+    private fun publishViewport(config: Configuration) {
+        val width = config.screenWidthDp
+        if (width <= 0 || width == reportedViewportWidth) return
+        reportedViewportWidth = width
+        if (!::root.isInitialized) return
+        val payload = JSONObject().put("width", width).put("height", config.screenHeightDp)
+        allScreens().forEach { screen -> if (!screen.headless) send(screen, "VIEWPORT", payload) }
     }
 
     private fun publishAppearance() {

package/dist/api/index.d.ts

@@ -17,8 +17,8 @@ export type { HttpClientOptions, RequestOptions, HttpResponse, WebSocketOptions
 export { crypto, uuid, randomString, hmac, timingSafeEqual, hashPassword, verifyPassword } from './crypto.js';
 export { env, getPlatform, isDesktop, isMobile, isCraft, getSystemInfo, exec, spawn, ChildProcess, cwd, homeDir, tempDir, exit, argv, open } from './process.js';
 export type { Platform, SystemInfo, ExecOptions, ExecResult, SpawnOptions } from './process.js';
-export { device, haptics, permissions, camera, biometrics, secureStorage, storage, location, share, lifecycle, notifications, notifications as notification } from './mobile.js';
-export type { DeviceInfo, DeviceCapabilities, HapticStyle, HapticNotificationType, PermissionType, PermissionStatus, CameraOptions as MobileCameraOptions, PhotoResult, BiometricType, Location, LocationOptions, ShareOptions, AppState, NotificationOptions as MobileNotificationOptions } from './mobile.js';
+export { device, haptics, permissions, camera, files, biometrics, secureStorage, storage, location, share, lifecycle, notifications, notifications as notification } from './mobile.js';
+export type { DeviceInfo, DeviceCapabilities, HapticStyle, HapticNotificationType, PermissionType, PermissionStatus, CameraOptions as MobileCameraOptions, PhotoResult, FileInfo, PickFileOptions, BiometricType, Location, LocationOptions, ShareOptions, AppState, NotificationOptions as MobileNotificationOptions } from './mobile.js';
 export { carplay, appClips, liveActivities, sharePlay, storeKit, appIntents, tipKit, focusFilters } from './ios-advanced.js';
 export type { CarPlayTemplateType, CarPlayListItem, CarPlayGridItem, CarPlayTemplate, AppClipInvocation, LiveActivityContentState, LiveActivityAttributes, LiveActivityConfig, LiveActivityHandle, SharePlaySessionState, SharePlayParticipant, SharePlayActivity, ProductType, Product, Transaction, IntentParameterType, IntentParameter, AppIntent, TipDisplayFrequency, Tip, FocusStatus, FocusFilter } from './ios-advanced.js';
 export { materialYou, photoPicker, workManager, foregroundService, predictiveBack, appLanguage, widgets as androidWidgets, playBilling } from './android-advanced.js';

package/dist/api/mobile.d.ts

@@ -314,6 +314,30 @@ export interface PhotoResult {
     /** MIME type */
     mimeType: string;
 }
+/** A file copied into the app-owned native file area. */
+export interface FileInfo {
+    /** App-owned path suitable for `fetch` FormData and sharing. */
+    path: string;
+    /** Original (sanitized) file name. */
+    name: string;
+    /** Preferred MIME type, or `application/octet-stream` when unknown. */
+    type: string;
+    /** Number of bytes in the copied file. */
+    size: number;
+}
+/** General document picker options. */
+export interface PickFileOptions {
+    /** MIME types, UTIs, or filename extensions (for example `pdf` or `public.data`). */
+    contentTypes?: string[];
+    /** Maximum number of documents; native hosts clamp this to 1–20. */
+    maxSelections?: number;
+    /** Maximum size of each document in bytes; native hosts default to 512 MiB. */
+    maxBytes?: number;
+}
+/** General document picker API. */
+export declare const files: {
+    pickFile(options?: PickFileOptions): Promise<FileInfo[]>;
+};
 /**
  * Camera and image picker API.
  *
@@ -1835,6 +1859,7 @@ declare const mobile: {
     haptics: typeof haptics;
     permissions: typeof permissions;
     camera: typeof camera;
+    files: typeof files;
     biometrics: typeof biometrics;
     secureStorage: typeof secureStorage;
     location: typeof location;

package/dist/browser/storage.d.ts

@@ -17,8 +17,10 @@ export interface BrowserStorageOptions {
      * or in another tab: called once the new account's storage is in place.
      */
     sessionChanged?: (token: string | null, previous: string | null) => void;
-    /** A host lock primitive; browsers use their native Web Locks implementation. */
-    lock?: (<T>(name: string, operation: () => T | Promise<T>) => Promise<T>) | null;
+    /** A host lock primitive; honor signal cancellation while queued, as native Web Locks do. */
+    lock?: (<T>(name: string, operation: () => T | Promise<T>, options?: {
+        signal?: AbortSignal;
+    }) => Promise<T>) | null;
 }
 export interface BrowserStorage {
     atomicStorage: boolean;
@@ -37,7 +39,7 @@ export interface BrowserStorage {
             keys: () => string[];
         };
     };
-    call: (module: string, method: string, args: unknown[]) => Promise<unknown>;
+    call: (module: string, method: string, args: unknown[], signal?: AbortSignal) => Promise<unknown>;
     accountChanged: () => Promise<void>;
     scope: () => string;
 }

package/dist/browser.d.ts

@@ -18,6 +18,7 @@ export interface BrowserPlatformOptions {
 export interface BrowserPlatform {
     craft: Record<string, unknown>;
     capabilities: string[];
+    /** Queued storage calls abort without writing; cancellation cannot undo an already committed synchronous write. */
     call: (module: string, method: string, args: unknown[], signal: AbortSignal) => Promise<unknown>;
     navigate: (path: string, replace?: boolean) => void;
     emit: (listener: (type: string, payload: unknown) => void) => () => void;

package/dist/browser.js

@@ -63,12 +63,35 @@ function secureUUID() {
 }
 
 // src/browser/storage.ts
+async function waitForAccount(operation, signal) {
+  if (!signal)
+    return operation;
+  let abort;
+  try {
+    return await Promise.race([operation, new Promise((resolve, reject) => {
+      abort = () => reject(signal.reason);
+      if (signal.aborted)
+        abort();
+      else
+        signal.addEventListener("abort", abort, { once: true });
+    })]);
+  } finally {
+    signal.removeEventListener("abort", abort);
+  }
+}
 async function createBrowserStorage(options) {
   const { storage, namespace, tokenKey, changed } = options;
   const sessionTokenKey = options.sessionTokenKey || "auth.token";
   const prefix = `${namespace}:`;
-  const lock = options.lock === null ? undefined : options.lock ?? (typeof navigator !== "undefined" && typeof navigator.locks?.request === "function" ? (name, operation) => navigator.locks.request(name, operation) : undefined);
-  const exclusive = (operation) => lock ? lock(`${namespace}:storage`, operation) : Promise.resolve().then(operation);
+  const lock = options.lock === null ? undefined : options.lock ?? (typeof navigator !== "undefined" && typeof navigator.locks?.request === "function" ? (name, operation, settings) => navigator.locks.request(name, settings ?? {}, operation) : undefined);
+  const exclusive = (operation, signal) => {
+    const guarded = () => {
+      signal?.throwIfAborted();
+      return operation();
+    };
+    signal?.throwIfAborted();
+    return lock ? lock(`${namespace}:storage`, guarded, { signal }) : Promise.resolve().then(guarded);
+  };
   const scopeChanged = () => Object.assign(new Error("The storage account changed"), { code: "STORAGE_SCOPE_CHANGED" });
   const pending = new Map;
   let token = storage.getItem(tokenKey);
@@ -215,10 +238,11 @@ async function createBrowserStorage(options) {
         keys: () => available() ? keys(key("snapshot:")).map((name) => name.slice(key("snapshot:").length)) : []
       }
     },
-    async call(module, method, args) {
+    async call(module, method, args, signal) {
+      signal?.throwIfAborted();
       const captured = capture();
       const wasAvailable = available();
-      await accountChanged();
+      await waitForAccount(accountChanged(), signal);
       const name = String(args[0] ?? "");
       if (module === "Storage") {
         if (!wasAvailable)
@@ -259,7 +283,7 @@ async function createBrowserStorage(options) {
             return true;
           }
           throw Object.assign(new Error(`Unsupported browser storage operation ${method}`), { code: "UNSUPPORTED" });
-        });
+        }, signal);
       }
       if (module === "SecureStorage") {
         if (!wasAvailable)
@@ -284,7 +308,7 @@ async function createBrowserStorage(options) {
             return true;
           }
           throw Object.assign(new Error(`Unsupported browser storage operation ${module}.${method}`), { code: "UNSUPPORTED" });
-        });
+        }, signal);
         if (method === "clear" || name === sessionTokenKey && (method === "set" || method === "remove"))
           await accountChanged();
         return result;
@@ -608,7 +632,7 @@ async function createBrowserPlatform(options = {}) {
       const first = object(args[0]);
       if (module === "Storage" || module === "SecureStorage") {
         const before = persistence.craft.secureStorage.getSync(sessionTokenKey);
-        const answer = await persistence.call(module, method, args);
+        const answer = await persistence.call(module, method, args, signal);
         if (before !== persistence.craft.secureStorage.getSync(sessionTokenKey))
           await resetAccount();
         return answer;