craft-native 0.0.168 → 0.0.169

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

@@ -26,6 +26,24 @@ export interface CraftAndroidConfig {
     enableGeolocation?: boolean;
     enableBackgroundLocation?: boolean;
     enableHealthConnect?: boolean;
+    /**
+     * The Health Connect data the app reads and writes, by the shared type
+     * names (`steps`, `sleep`, `workouts`...). The manifest declares only
+     * these, as Play's health permissions review requires; without it, the
+     * original set (steps, heart rate, energy, distance, workouts).
+     */
+    healthConnect?: {
+        read?: HealthConnectType[];
+        write?: HealthConnectType[];
+        /** Read while the app is in the background (a WorkManager refresh): Android 15's READ_HEALTH_DATA_IN_BACKGROUND. */
+        background?: boolean;
+        /** Read further back than the 30 days before the first grant: READ_HEALTH_DATA_HISTORY. */
+        history?: boolean;
+    };
+    enableHealthConnectBackground?: boolean;
+    enableHealthConnectHistory?: boolean;
+    /** The app's privacy policy, which Health Connect links to from its permission screen. */
+    privacyPolicyURL?: string;
     enableKeepAwake?: boolean;
     enableDeepLinks?: boolean;
     /** Reach the person's own devices on the local network over plain HTTP (a Mac companion). */
@@ -40,7 +58,37 @@ export interface CraftAndroidConfig {
     minSdk?: number;
     compileSdk?: number;
     targetSdk?: number;
+    /**
+     * Native renderer: the app's paths and the screen drawing each
+     * (`/m/workout/:id` → `Workout`), its tabs, and the bundle route of the
+     * script that runs beside the screens. The same keys as the iOS builder.
+     */
+    nativeScreens?: Record<string, string>;
+    tabs?: Array<{
+        id: string;
+        title: string;
+        symbol?: string;
+    }>;
+    nativeApp?: string;
+    /** Wake the app script every so often (`craftBackgroundRefresh`), through WorkManager. */
+    backgroundRefresh?: {
+        enabled?: boolean;
+        minimumIntervalMinutes?: number;
+    };
 }
+/** The shared health data types (the iOS builder's HealthKit names). */
+export type HealthConnectType = 'steps' | 'heartRate' | 'activeEnergy' | 'distance' | 'workouts' | 'restingHeartRate' | 'heartRateVariability' | 'bodyMass' | 'sleep' | 'mindful' | 'dietaryEnergy' | 'dietaryProtein' | 'dietaryCarbohydrates' | 'dietaryFat';
+/**
+ * The Health Connect permissions behind each type, for reading and for
+ * writing. CraftNativeHealth.kt asks for the same ones; a permission the
+ * manifest does not declare is refused without a prompt.
+ */
+export declare const HEALTH_CONNECT_PERMISSIONS: Record<HealthConnectType, {
+    read: string[];
+    write: string[];
+}>;
+/** Every `android.permission.health.*` the app's Health Connect types need. */
+export declare function healthConnectPermissions(config: Pick<CraftAndroidConfig, 'healthConnect'>): string[];
 export interface InitOptions {
     name: string;
     packageName?: string;
@@ -58,9 +106,23 @@ export interface InitOptions {
 export interface BuildOptions {
     htmlPath?: string;
     nativeBundlePath?: string;
+    /**
+     * Native renderer: the app's icons as vectors (`{ viewBox, strokeWidth,
+     * icons: { name: svgBody } }`, keyed by Iconify name and SF Symbol), which
+     * `<Icon>`, the tab bar and the bar buttons draw. Without it they fall
+     * back to the glyphs Android's fonts have.
+     */
+    iconsPath?: string;
     devServer?: string;
     output: string;
     release?: boolean;
+    /**
+     * An Android App Bundle (`bundleRelease`, `.aab`), what Google Play takes,
+     * rather than an APK. Signed with CRAFT_ANDROID_KEYSTORE,
+     * CRAFT_ANDROID_KEYSTORE_PASSWORD, CRAFT_ANDROID_KEY_ALIAS and
+     * CRAFT_ANDROID_KEY_PASSWORD when they are set.
+     */
+    bundle?: boolean;
     compile?: boolean;
     /** Same meaning as `InitOptions.runtimeDir`; refreshes what init installed. */
     runtimeDir?: string | null;

package/dist/android/src/index.js

@@ -111,6 +111,48 @@ var KOTLIN_KEYWORDS = new Set([
   "while"
 ]);
 var ANDROID_MIN_SDK = 26;
+var HEALTH_CONNECT_PERMISSIONS = {
+  steps: { read: ["READ_STEPS"], write: [] },
+  heartRate: { read: ["READ_HEART_RATE"], write: [] },
+  activeEnergy: { read: ["READ_ACTIVE_CALORIES_BURNED"], write: ["WRITE_ACTIVE_CALORIES_BURNED"] },
+  distance: { read: ["READ_DISTANCE"], write: ["WRITE_DISTANCE"] },
+  workouts: {
+    read: ["READ_EXERCISE", "READ_HEART_RATE", "READ_ACTIVE_CALORIES_BURNED", "READ_DISTANCE"],
+    write: ["WRITE_EXERCISE", "WRITE_ACTIVE_CALORIES_BURNED", "WRITE_DISTANCE"]
+  },
+  restingHeartRate: { read: ["READ_RESTING_HEART_RATE"], write: [] },
+  heartRateVariability: { read: ["READ_HEART_RATE_VARIABILITY"], write: [] },
+  bodyMass: { read: ["READ_WEIGHT"], write: [] },
+  sleep: { read: ["READ_SLEEP"], write: [] },
+  mindful: { read: ["READ_MINDFULNESS"], write: ["WRITE_MINDFULNESS"] },
+  dietaryEnergy: { read: ["READ_NUTRITION"], write: ["WRITE_NUTRITION"] },
+  dietaryProtein: { read: ["READ_NUTRITION"], write: ["WRITE_NUTRITION"] },
+  dietaryCarbohydrates: { read: ["READ_NUTRITION"], write: ["WRITE_NUTRITION"] },
+  dietaryFat: { read: ["READ_NUTRITION"], write: ["WRITE_NUTRITION"] }
+};
+var DEFAULT_HEALTH_CONNECT = { read: ["steps", "heartRate", "activeEnergy", "distance", "workouts"], write: ["workouts"] };
+function healthConnectPermissions(config) {
+  const read = config.healthConnect?.read ?? DEFAULT_HEALTH_CONNECT.read;
+  const write = config.healthConnect?.write ?? (config.healthConnect ? [] : DEFAULT_HEALTH_CONNECT.write);
+  const permissions = new Set;
+  for (const type of read) {
+    const known = HEALTH_CONNECT_PERMISSIONS[type];
+    if (!known)
+      throw new Error(`Unknown Health Connect type: ${type}`);
+    known.read.forEach((permission) => permissions.add(`android.permission.health.${permission}`));
+  }
+  for (const type of write) {
+    const known = HEALTH_CONNECT_PERMISSIONS[type];
+    if (!known)
+      throw new Error(`Unknown Health Connect type: ${type}`);
+    known.write.forEach((permission) => permissions.add(`android.permission.health.${permission}`));
+  }
+  if (config.healthConnect?.background)
+    permissions.add("android.permission.health.READ_HEALTH_DATA_IN_BACKGROUND");
+  if (config.healthConnect?.history)
+    permissions.add("android.permission.health.READ_HEALTH_DATA_HISTORY");
+  return [...permissions];
+}
 var DEFAULT_CONFIG = {
   renderer: "web",
   version: "1.0.0",
@@ -307,17 +349,77 @@ function renderAndroidPermissions(config) {
     permissions.add("android.permission.POST_NOTIFICATIONS");
   if (config.enableKeepAwake)
     permissions.add("android.permission.WAKE_LOCK");
+  if (config.enableHealthConnect)
+    healthConnectPermissions(config).forEach((permission) => permissions.add(permission));
+  if (config.renderer === "native" && config.backgroundRefresh?.enabled)
+    permissions.add("android.permission.RECEIVE_BOOT_COMPLETED");
+  return [...permissions].map((permission) => `    <uses-permission android:name="${permission}" />`).join(`
+`);
+}
+function writeNativeShellSources(output, packagePath, packageName, config) {
+  const javaDir = join(output, "app/src/main/java", packagePath);
+  const write = (template, file, replace = (source) => source) => {
+    const source = readFileSync(join(TEMPLATES_DIR, template), "utf-8").replace(/\{\{PACKAGE_NAME\}\}/g, packageName);
+    writeFileSync(join(javaDir, file), replace(source));
+  };
+  write("CraftNativeShell.kt.template", "CraftNativeShell.kt");
+  write("CraftNativeBackground.kt.template", "CraftNativeBackground.kt");
+  write(config.enableHealthConnect ? "CraftNativeHealth.kt.template" : "CraftNativeHealthStub.kt.template", "CraftNativeHealth.kt");
+  write("CraftNativeServices.kt.template", "CraftNativeServices.kt", (source) => source.replace("{{NATIVE_PUSH_IMPORTS}}", config.enablePushNotifications ? "import com.google.firebase.messaging.FirebaseMessaging" : "").replace("{{NATIVE_PUSH_REGISTER}}", config.enablePushNotifications ? `        try {
+            FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
+                val token = if (task.isSuccessful) task.result else null
+                if (token.isNullOrBlank()) done(failure("PUSH_UNAVAILABLE", task.exception?.message ?: "Firebase Cloud Messaging gave no token"))
+                else {
+                    context.getSharedPreferences("craft-native-push", Context.MODE_PRIVATE).edit().putString("token", token).apply()
+                    done(success(token))
+                }
+            }
+        } catch (error: Exception) {
+            done(failure("PUSH_UNAVAILABLE", error.message ?: "Firebase Cloud Messaging is not configured"))
+        }` : '        done(failure("CAPABILITY_DISABLED", "Push notifications are disabled"))'));
+  if (config.enablePushNotifications)
+    write("CraftNativeMessagingService.kt.template", "CraftNativeMessagingService.kt");
+  else
+    rmSync(join(javaDir, "CraftNativeMessagingService.kt"), { force: true });
+  mkdirSync(join(output, "app/src/main/res/xml"), { recursive: true });
+  writeFileSync(join(output, "app/src/main/res/xml/craft_file_paths.xml"), `<?xml version="1.0" encoding="utf-8"?>
+<paths>
+    <cache-path name="craft-files" path="craft-files/" />
+    <files-path name="craft-media" path="craft-media/" />
+</paths>
+`);
+}
+function renderNativeShellManifest(config) {
+  const parts = [
+    '        <receiver android:name=".CraftNativeNotificationReceiver" android:exported="false" />',
+    `        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${config.packageName}.craftfiles"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data android:name="android.support.FILE_PROVIDER_PATHS" android:resource="@xml/craft_file_paths" />
+        </provider>`
+  ];
+  if (config.enablePushNotifications) {
+    parts.push(`        <service android:name=".CraftNativeMessagingService" android:exported="false">
+            <intent-filter>
+                <action android:name="com.google.firebase.MESSAGING_EVENT" />
+            </intent-filter>
+        </service>`);
+  }
   if (config.enableHealthConnect) {
-    permissions.add("android.permission.health.READ_STEPS");
-    permissions.add("android.permission.health.READ_HEART_RATE");
-    permissions.add("android.permission.health.READ_ACTIVE_CALORIES_BURNED");
-    permissions.add("android.permission.health.READ_DISTANCE");
-    permissions.add("android.permission.health.READ_EXERCISE");
-    permissions.add("android.permission.health.WRITE_EXERCISE");
-    permissions.add("android.permission.health.WRITE_ACTIVE_CALORIES_BURNED");
-    permissions.add("android.permission.health.WRITE_DISTANCE");
+    parts.push(`        <activity-alias
+            android:name="ViewPermissionUsageActivity"
+            android:exported="true"
+            android:targetActivity=".MainActivity"
+            android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
+                <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
+            </intent-filter>
+        </activity-alias>`);
   }
-  return [...permissions].map((permission) => `    <uses-permission android:name="${permission}" />`).join(`
+  return parts.join(`
 `);
 }
 function renderAndroidDeepLinks(config) {
@@ -382,6 +484,9 @@ async function init(options) {
     config.enableGeolocation = true;
   if (config.enableHealthConnect) {
     config.compileSdk = Math.max(config.compileSdk ?? 36, 36);
+    config.enableHealthConnectBackground = Boolean(config.healthConnect?.background);
+    config.enableHealthConnectHistory = Boolean(config.healthConnect?.history);
+    healthConnectPermissions(config);
   }
   normalizeAndroidNetworkConfig(config);
   validateAndroidConfig(config);
@@ -433,6 +538,7 @@ async function init(options) {
     writeFileSync(join(output, "app/src/main/java", packagePath, "CraftNativeRefreshableFlatList.kt"), refreshableFlatListTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName));
     writeFileSync(join(output, "app/src/main/java", packagePath, "CraftNativeCapabilities.kt"), capabilityTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName));
     writeFileSync(join(output, "app/src/main/java", packagePath, "CraftNativeNotificationReceiver.kt"), notificationTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName));
+    writeNativeShellSources(output, packagePath, finalPackageName, config);
   }
   const craftBridgeTemplate = readFileSync(join(TEMPLATES_DIR, "CraftBridge.kt.template"), "utf-8");
   const craftBridge = craftBridgeTemplate.replace(/\{\{PROMISE_RUNTIME\}\}/g, () => renderAndroidPromiseRuntime("            ")).replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName).replace(/\{\{ENABLE_SPEECH\}\}/g, String(Boolean(config.enableSpeechRecognition))).replace(/\{\{ENABLE_HAPTICS\}\}/g, String(Boolean(config.enableHaptics))).replace(/\{\{ENABLE_SHARE\}\}/g, String(Boolean(config.enableShare))).replace(/\{\{ENABLE_CAMERA\}\}/g, String(Boolean(config.enableCamera))).replace(/\{\{ENABLE_BIOMETRIC\}\}/g, String(Boolean(config.enableBiometric))).replace(/\{\{ENABLE_PUSH\}\}/g, String(Boolean(config.enablePushNotifications))).replace(/\{\{ENABLE_SECURE_STORAGE\}\}/g, String(Boolean(config.enableSecureStorage))).replace(/\{\{ENABLE_GEOLOCATION\}\}/g, String(Boolean(config.enableGeolocation))).replace(/\{\{ENABLE_BACKGROUND_LOCATION\}\}/g, String(Boolean(config.enableBackgroundLocation))).replace(/\{\{ENABLE_KEEP_AWAKE\}\}/g, String(Boolean(config.enableKeepAwake))).replace(/\{\{ENABLE_DEEP_LINKS\}\}/g, String(Boolean(config.enableDeepLinks))).replace(/\{\{ENABLE_HEALTH_CONNECT\}\}/g, String(Boolean(config.enableHealthConnect))).replace(/\{\{FIREBASE_IMPORT\}\}/g, config.enablePushNotifications ? "import com.google.firebase.messaging.FirebaseMessaging" : "").replace(/\{\{REGISTER_PUSH_IMPLEMENTATION\}\}/g, config.enablePushNotifications ? `activity.runOnUiThread {
@@ -464,21 +570,24 @@ async function init(options) {
   const healthTemplate = readFileSync(join(TEMPLATES_DIR, config.enableHealthConnect ? "CraftHealthConnect.kt.template" : "CraftHealthConnectStub.kt.template"), "utf-8");
   writeFileSync(join(output, "app/src/main/java", packagePath, "CraftHealthConnect.kt"), healthTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName));
   const manifestTemplate = readFileSync(join(TEMPLATES_DIR, "AndroidManifest.xml.template"), "utf-8");
-  const manifest = manifestTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName).replace(/\{\{APP_NAME\}\}/g, name).replace(/\{\{PERMISSIONS\}\}/g, renderAndroidPermissions(config)).replace(/\{\{USES_CLEARTEXT\}\}/g, config.devServerURL?.startsWith("http://") || config.enableLocalNetwork ? "true" : "false").replace(/\{\{DEEP_LINK_INTENT_FILTERS\}\}/g, renderAndroidDeepLinks(config)).replace(/\{\{BACKGROUND_SERVICE\}\}/g, config.enableBackgroundLocation ? '        <service android:name="com.craft.runtime.LocationRecordingService" android:exported="false" android:foregroundServiceType="location" android:stopWithTask="false" />' : "").replace(/\{\{NATIVE_NOTIFICATION_RECEIVER\}\}/g, config.renderer === "native" ? '        <receiver android:name=".CraftNativeNotificationReceiver" android:exported="false" />' : "").replace(/\{\{HEALTH_CONNECT_QUERIES\}\}/g, config.enableHealthConnect ? `    <queries>
+  const manifest = manifestTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName).replace(/\{\{APP_NAME\}\}/g, name).replace(/\{\{PERMISSIONS\}\}/g, renderAndroidPermissions(config)).replace(/\{\{USES_CLEARTEXT\}\}/g, config.devServerURL?.startsWith("http://") || config.enableLocalNetwork ? "true" : "false").replace(/\{\{DEEP_LINK_INTENT_FILTERS\}\}/g, renderAndroidDeepLinks(config)).replace(/\{\{BACKGROUND_SERVICE\}\}/g, config.enableBackgroundLocation ? '        <service android:name="com.craft.runtime.LocationRecordingService" android:exported="false" android:foregroundServiceType="location" android:stopWithTask="false" />' : "").replace(/\{\{NATIVE_NOTIFICATION_RECEIVER\}\}/g, config.renderer === "native" ? renderNativeShellManifest(config) : "").replace(/\{\{HEALTH_CONNECT_QUERIES\}\}/g, config.enableHealthConnect ? `    <queries>
         <package android:name="com.google.android.apps.healthdata" />
     </queries>` : "").replace(/\{\{HEALTH_CONNECT_RATIONALE\}\}/g, config.enableHealthConnect ? `            <intent-filter>
                 <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
-            </intent-filter>
+            </intent-filter>${config.renderer === "native" ? "" : `
             <intent-filter>
                 <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
                 <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
-            </intent-filter>` : "");
+            </intent-filter>`}` : "");
   writeFileSync(join(output, "app/src/main/AndroidManifest.xml"), manifest);
   const projectGradleTemplate = readFileSync(join(TEMPLATES_DIR, "build.gradle.kts.project.template"), "utf-8");
   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(/\{\{REFRESH_LAYOUT_DEPENDENCY\}\}/g, config.renderer === "native" ? '    implementation("androidx.swiperefreshlayout:swiperefreshlayout:1.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")` : "").replace(/\{\{JAVASCRIPT_ENGINE_DEPENDENCY\}\}/g, config.renderer === "native" ? '    implementation("androidx.javascriptengine:javascriptengine:1.1.0")' : "");
+    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")
+    // The in-app browser (Custom Tabs) and background refresh (WorkManager).
+    implementation("androidx.browser:browser:1.8.0")
+    implementation("androidx.work:work-runtime-ktx:2.9.1")` : "");
   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));
@@ -630,7 +739,7 @@ zipStorePath=wrapper/dists
   console.log("");
 }
 async function build(options) {
-  const { htmlPath, nativeBundlePath, devServer, output, release, compile = true } = options;
+  const { htmlPath, nativeBundlePath, devServer, output, release, bundle, compile = true } = options;
   console.log(`
 \uD83D\uDCE6 Building Craft Android project...`);
   const configPath = join(output, "craft.config.json");
@@ -645,6 +754,12 @@ async function build(options) {
     const destination = join(output, "app/src/main/assets/native-screen.js");
     if (nativeBundlePath && resolve(nativeBundlePath) !== resolve(destination))
       cpSync(nativeBundlePath, destination);
+    const icons = join(output, "app/src/main/assets/craft-icons.json");
+    if (options.iconsPath) {
+      requireRegularFile(options.iconsPath, "Icon table");
+      if (resolve(options.iconsPath) !== resolve(icons))
+        cpSync(options.iconsPath, icons);
+    }
     if (!existsSync(destination)) {
       throw new Error("Native Android mode needs app/src/main/assets/native-screen.js. Compile a .stx screen with `stx native compile` first.");
     }
@@ -687,12 +802,15 @@ async function build(options) {
       throw new Error("Gradle is unavailable. Install Android Studio or Gradle before building Android.", { cause: error });
     }
   }
-  const buildType = release ? "assembleRelease" : "assembleDebug";
-  console.log(`   Building ${release ? "release" : "debug"} APK...`);
+  const variant = release ? "Release" : "Debug";
+  const buildType = `${bundle ? "bundle" : "assemble"}${variant}`;
+  console.log(`   Building ${release ? "release" : "debug"} ${bundle ? "app bundle" : "APK"}...`);
+  if (release && !process.env.CRAFT_ANDROID_KEYSTORE)
+    console.log("   CRAFT_ANDROID_KEYSTORE is not set: the release build is unsigned.");
   try {
     await $`cd ${output} && ./gradlew ${buildType}`;
-    const apkPath = release ? "app/build/outputs/apk/release/app-release.apk" : "app/build/outputs/apk/debug/app-debug.apk";
-    console.log(`\u2705 APK built: ${apkPath}`);
+    const artifact = bundle ? `app/build/outputs/bundle/${variant.toLowerCase()}/app-${variant.toLowerCase()}.aab` : release ? "app/build/outputs/apk/release/app-release.apk" : "app/build/outputs/apk/debug/app-debug.apk";
+    console.log(`\u2705 ${bundle ? "App bundle" : "APK"} built: ${artifact}`);
   } catch (error) {
     console.error("Build failed. Open in Android Studio for details.");
     throw error;
@@ -752,6 +870,8 @@ export {
   open,
   installRuntime,
   init,
+  healthConnectPermissions,
   build,
+  HEALTH_CONNECT_PERMISSIONS,
   ANDROID_MIN_SDK
 };

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

@@ -0,0 +1,296 @@
+package {{PACKAGE_NAME}}
+
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import androidx.core.content.ContextCompat
+import androidx.javascriptengine.JavaScriptConsoleCallback
+import androidx.javascriptengine.JavaScriptIsolate
+import androidx.javascriptengine.JavaScriptSandbox
+import androidx.work.Constraints
+import androidx.work.CoroutineWorker
+import androidx.work.ExistingPeriodicWorkPolicy
+import androidx.work.ExistingWorkPolicy
+import androidx.work.NetworkType
+import androidx.work.OneTimeWorkRequestBuilder
+import androidx.work.PeriodicWorkRequestBuilder
+import androidx.work.WorkManager
+import androidx.work.WorkerParameters
+import androidx.work.workDataOf
+import com.google.common.util.concurrent.ListenableFuture
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import kotlinx.coroutines.withTimeoutOrNull
+import org.json.JSONArray
+import org.json.JSONObject
+import java.util.UUID
+import java.util.concurrent.TimeUnit
+
+/**
+ * One JavaScriptSandbox for the process: the screens' isolates and a
+ * background refresh's all live in it, since an app may hold only one.
+ */
+internal object CraftNativeSandbox {
+    private val lock = Any()
+    private var sandbox: JavaScriptSandbox? = null
+    private var connecting: ListenableFuture<JavaScriptSandbox>? = null
+
+    fun connect(context: Context, done: (JavaScriptSandbox?, Throwable?) -> Unit) {
+        val existing = synchronized(lock) { sandbox }
+        if (existing != null) return done(existing, null)
+        val future = synchronized(lock) {
+            connecting ?: JavaScriptSandbox.createConnectedInstanceAsync(context.applicationContext).also { connecting = it }
+        }
+        future.addListener({
+            try {
+                val engine = future.get()
+                synchronized(lock) { sandbox = engine }
+                done(engine, null)
+            } catch (error: Exception) {
+                synchronized(lock) { connecting = null }
+                done(null, error)
+            }
+        }, ContextCompat.getMainExecutor(context))
+    }
+}
+
+/**
+ * Background refresh, as iOS's BGAppRefreshTask gives it: WorkManager wakes
+ * the app every `backgroundRefresh.minimumIntervalMinutes` (15 at the
+ * least, with a network) and the app script (`nativeApp`) hears
+ * `craftBackgroundRefresh` with an `id`, does its work and answers
+ * `craft.background.complete(ok, id)`. With the app open, the running app
+ * script hears it; otherwise a script is started for the refresh alone
+ * ([CraftNativeHeadlessApp]) and closed when it answers. A silent push
+ * (`craftSilentPush`) runs the same way, once.
+ */
+internal object CraftNativeBackground {
+    private const val PERIODIC = "craft-native-background-refresh"
+    private const val ONCE = "craft-native-background-once"
+
+    /** The running app's script, when the activity has one: delivers an event and hears its answer. */
+    @Volatile var foreground: ((event: String, id: String, done: (Boolean) -> Unit) -> Boolean)? = null
+
+    fun schedule(context: Context, config: JSONObject) {
+        val refresh = config.optJSONObject("backgroundRefresh")
+        val work = WorkManager.getInstance(context)
+        if (refresh?.optBoolean("enabled") != true || config.optString("nativeApp").isBlank()) {
+            work.cancelUniqueWork(PERIODIC)
+            return
+        }
+        val minutes = refresh.optLong("minimumIntervalMinutes", 120).coerceAtLeast(15)
+        val request = PeriodicWorkRequestBuilder<CraftNativeRefreshWorker>(minutes, TimeUnit.MINUTES)
+            .setConstraints(Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED).build())
+            .setInputData(workDataOf("event" to "craftBackgroundRefresh"))
+            .build()
+        work.enqueueUniquePeriodicWork(PERIODIC, ExistingPeriodicWorkPolicy.UPDATE, request)
+    }
+
+    /** One run now (a silent push). */
+    fun runOnce(context: Context, event: String) {
+        val request = OneTimeWorkRequestBuilder<CraftNativeRefreshWorker>()
+            .setConstraints(Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED).build())
+            .setInputData(workDataOf("event" to event))
+            .build()
+        WorkManager.getInstance(context).enqueueUniqueWork(ONCE, ExistingWorkPolicy.APPEND_OR_REPLACE, request)
+    }
+}
+
+internal class CraftNativeRefreshWorker(context: Context, parameters: WorkerParameters) : CoroutineWorker(context, parameters) {
+    override suspend fun doWork(): Result {
+        val event = inputData.getString("event") ?: "craftBackgroundRefresh"
+        val id = UUID.randomUUID().toString()
+        val answer = CompletableDeferred<Boolean>()
+        val running = withContext(Dispatchers.Main) {
+            CraftNativeBackground.foreground?.invoke(event, id) { ok -> answer.complete(ok) } == true
+        }
+        Log.i("CraftNativeAndroid", "$event $id: ${if (running) "the running app script" else "a background app script"}")
+        var headless: CraftNativeHeadlessApp? = null
+        if (!running) {
+            headless = withContext(Dispatchers.Main) { CraftNativeHeadlessApp(applicationContext, event, id) { ok -> answer.complete(ok) } }
+            withContext(Dispatchers.Main) { headless.start() }
+        }
+        // WorkManager stops a worker at ten minutes; answer before that.
+        val ok = withTimeoutOrNull(9 * 60 * 1000L) { answer.await() }
+        Log.i("CraftNativeAndroid", "$event $id answered ${ok ?: "nothing in time"}")
+        headless?.let { withContext(Dispatchers.Main) { it.close() } }
+        return if (ok == false) Result.retry() else Result.success()
+    }
+}
+
+/**
+ * The app script with no activity: a background refresh's. It gets the
+ * same bridge as a screen's (CraftNativePrelude), Craft's core capabilities
+ * and this host's services, minus everything a person would have to see.
+ */
+internal class CraftNativeHeadlessApp(
+    private val context: Context,
+    private val event: String,
+    private val id: String,
+    private val onDone: (Boolean) -> Unit,
+) {
+    private val config: JSONObject = runCatching {
+        context.assets.open("craft.config.json").bufferedReader().use { JSONObject(it.readText()) }
+    }.getOrDefault(JSONObject())
+    private val stores = CraftNativeStores.get(context, config)
+    private val capabilities = CraftNativeCapabilities(context, config)
+    private val services = CraftNativeServices(context, config) { null }
+    private val scope = UUID.randomUUID().toString()
+    private val prefix = "CRAFT_STX_$scope:"
+    private val main = Handler(Looper.getMainLooper())
+    private var isolate: JavaScriptIsolate? = null
+    private var closed = false
+    private val timers = mutableMapOf<Int, Runnable>()
+    private val chunks = CraftNativeChunks()
+
+    init {
+        capabilities.storeObserver = { store, key, value -> stores.changed(store, key, value, scope) }
+        services.onBackgroundComplete = { ok, answered -> if (answered == null || answered == id) finish(ok) }
+    }
+
+    fun start() {
+        val route = config.optString("nativeApp")
+        if (route.isBlank() || !JavaScriptSandbox.isSupported()) return finish(true)
+        val bundle = runCatching { context.assets.open("native-screen.js").bufferedReader().use { it.readText() } }.getOrNull()
+            ?: return finish(true)
+        CraftNativeSandbox.connect(context) { engine, error ->
+            if (closed) return@connect
+            if (engine == null || !engine.isFeatureSupported(JavaScriptSandbox.JS_FEATURE_CONSOLE_MESSAGING)) {
+                Log.w(TAG, "Background refresh has no JavaScript engine", error)
+                return@connect finish(true)
+            }
+            val created = engine.createIsolate()
+            isolate = created
+            created.setConsoleCallback(ContextCompat.getMainExecutor(context), JavaScriptConsoleCallback { entry ->
+                if (closed) return@JavaScriptConsoleCallback
+                if (entry.message.startsWith(prefix)) chunks.accept(entry.message.removePrefix(prefix))?.let(::receive)
+                else Log.i(TAG, "[background] ${entry.message}")
+            })
+            CraftNativeHub.register(scope) { type, payload -> send(type, payload) }
+            val names = capabilities.names().apply { services.names().forEach { put(it) } }
+            val bridgeFields = """
+                platform: 'android',
+                mutationProtocolVersion: 1,
+                capabilityProtocolVersion: $CRAFT_NATIVE_CAPABILITY_PROTOCOL_VERSION,
+                capabilityTimeoutMs: 30000,
+                capabilities: $names,
+                initialAppState: 'background',
+                colorScheme: 'light',
+                appURL: ${JSONObject.quote(config.optString("devServerURL"))},
+                appVersion: '',
+                appBuild: ''
+            """.trimIndent()
+            val prelude = CraftNativePrelude.script(
+                bridgeFields,
+                CraftNativeChunks.consolePost(prefix),
+                "globalThis.__stxNativeCallback = deliver;",
+                stores.preloadText(),
+                "globalThis.__stxNativeRoute = ${JSONObject.quote(route)};\nglobalThis.__stxNativeParams = {};",
+            )
+            val setup = created.evaluateJavaScriptAsync(prelude)
+            setup.addListener({
+                if (closed) return@addListener
+                try {
+                    setup.get()
+                    val load = created.evaluateJavaScriptAsync(bundle)
+                    load.addListener({
+                        try {
+                            load.get()
+                            send("CRAFT_EVENT", JSONObject().put("event", event).put("detail", JSONObject().put("id", id)))
+                        } catch (failure: Exception) {
+                            Log.e(TAG, "Background refresh script failed", failure)
+                            finish(false)
+                        }
+                    }, ContextCompat.getMainExecutor(context))
+                } catch (failure: Exception) {
+                    Log.e(TAG, "Background refresh bridge failed", failure)
+                    finish(false)
+                }
+            }, ContextCompat.getMainExecutor(context))
+        }
+    }
+
+    private fun receive(raw: String) {
+        val message = runCatching { JSONObject(raw) }.getOrNull() ?: return
+        val payload = message.optJSONObject("payload") ?: JSONObject()
+        when (message.optString("type")) {
+            "API_REQUEST" -> answer(message.optString("id"), payload)
+            "SYNC_WRITE" -> {
+                val key = payload.optString("key")
+                val value = if (payload.isNull("value")) null else payload.optString("value")
+                val reply: (Boolean) -> Unit = { ok ->
+                    payload.optString("id").takeIf { it.isNotBlank() }?.let { send("SYNC_RESULT", JSONObject().put("id", it).put("ok", ok)) }
+                }
+                when (payload.optString("store")) {
+                    "storage" -> if (key.isNotBlank()) stores.setStorage(key, value, scope)
+                    "snapshots" -> if (payload.optBoolean("clear")) {
+                        val keep = payload.optJSONArray("keep") ?: JSONArray()
+                        stores.clearSnapshots((0 until keep.length()).map { keep.optString(it) }.toSet(), reply)
+                    } else stores.setSnapshot(key, value, scope, reply)
+                }
+            }
+            "TIMER" -> {
+                val id = payload.optInt("id")
+                timers.remove(id)?.let(main::removeCallbacks)
+                val fire = Runnable {
+                    timers.remove(id)
+                    send("TIMER_FIRE", JSONObject().put("id", id))
+                }
+                timers[id] = fire
+                main.postDelayed(fire, payload.optLong("ms", 0).coerceAtLeast(0))
+            }
+            "TIMER_CLEAR" -> timers.remove(payload.optInt("id"))?.let(main::removeCallbacks)
+            // Nothing is drawn in the background: frames come at a calm pace.
+            "FRAME" -> main.postDelayed({ send("FRAME_FIRE", JSONObject().put("time", android.os.SystemClock.uptimeMillis().toDouble())) }, 100)
+            // A background refresh shows nothing: navigation waits for the app.
+        }
+    }
+
+    private fun answer(requestId: String, payload: JSONObject) {
+        if (requestId.isBlank()) return
+        val module = payload.optString("module")
+        val method = payload.optString("method")
+        val args = payload.optJSONArray("args") ?: JSONArray()
+        val reply: (CraftNativeCapabilityResult) -> Unit = { result ->
+            val response = JSONObject().put("version", CRAFT_NATIVE_CAPABILITY_PROTOCOL_VERSION).put("requestId", requestId)
+            if (result.code == null) response.put("data", result.data ?: JSONObject.NULL)
+            else response.put("code", result.code).put("message", result.message ?: "Native API failed")
+            send(if (result.code == null) "API_RESPONSE" else "API_ERROR", response, requestId)
+        }
+        if (services.handles(module)) services.perform(module, method, args, reply)
+        else capabilities.perform("$scope/$requestId", payload.optInt("version", CRAFT_NATIVE_CAPABILITY_PROTOCOL_VERSION), module, method, args, reply)
+    }
+
+    private fun send(type: String, payload: JSONObject, correlationId: String? = null) {
+        val target = isolate ?: return
+        if (closed) return
+        val message = JSONObject().put("type", type).put("payload", payload)
+        if (correlationId != null) message.put("correlationId", correlationId)
+        runCatching { target.evaluateJavaScriptAsync("globalThis.__stxNativeCallback && globalThis.__stxNativeCallback(${JSONObject.quote(message.toString())})") }
+    }
+
+    private fun finish(ok: Boolean) {
+        main.post { onDone(ok) }
+    }
+
+    fun close() {
+        if (closed) return
+        closed = true
+        CraftNativeHub.unregister(scope)
+        timers.values.forEach(main::removeCallbacks)
+        timers.clear()
+        services.close()
+        capabilities.close()
+        isolate?.let { target ->
+            runCatching { target.evaluateJavaScriptAsync("globalThis.__stxNativeUnmount && globalThis.__stxNativeUnmount()") }
+            main.postDelayed({ runCatching { target.close() } }, 500)
+        }
+        isolate = null
+    }
+
+    companion object {
+        private const val TAG = "CraftNativeAndroid"
+    }
+}