@craft-native/android 0.0.451 → 0.0.464

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

@@ -0,0 +1,358 @@
+import { type NativeNotificationCategory } from '../../typescript/src/native-notifications.js';
+export type { NativeNotificationCategory } from '../../typescript/src/native-notifications.js';
+import { type NativeRouteConstraints } from '../../typescript/src/native-routing.js';
+/** Store large native source assets compressed; the host decodes each once on demand. */
+export declare function compressNativeSources(target: string): void;
+import { type AndroidMapProvider } from './native-map.js';
+export type { AndroidMapProvider } from './native-map.js';
+/**
+ * The builder installs a directory of route bundles (stx's `routesDir`) as
+ * well as the one-file bundle, and the app runs each screen from its own
+ * route's file. Stacks asks for route bundles only when this is true.
+ */
+/** Build-time proof for Stacks capability mappings, including unreleased source builds. */
+export declare const nativeSensorCapabilities: readonly ['motionSensors', 'barometer', 'pedometer'];
+export declare const nativeRouteBundles = true;
+/**
+ * The app evaluates stx's shared runtime (`__runtime.js`, stx's
+ * `sharedRuntime`) in each screen's context before the route's own file.
+ * Stacks asks stx for it only when this is true: a route file built so
+ * refuses to run without it.
+ */
+export declare const nativeRouteRuntime = true;
+/**
+ * The app gives a screen its messages a language at a time (stx's
+ * `messages`, `native-screens/__messages/`): the areas its route uses,
+ * evaluated ahead of it (an isolate cannot read a file when asked). Stacks leaves the languages
+ * out of the screens' code only when this is true.
+ */
+export declare const nativeMessages = true;
+/** Providers this published builder can generate as real Android map views. */
+export declare const nativeMapProviders: readonly ['google', 'maplibre'];
+export { runKotlinFixture } from './testing.js';
+export { createAndroidEmulator } from './emulator.js';
+export type { AndroidEmulatorOptions, AndroidEmulatorSession } from './emulator.js';
+/** Package custom fonts and their licenses; removed fonts cannot linger in the app. */
+export declare function syncNativeFonts(fonts: CraftAndroidConfig['nativeFonts'], output: string): string[];
+/** Oldest Android API level supported by the generated Kotlin runtime. */
+export declare const ANDROID_MIN_SDK = 26;
+export interface CraftAndroidConfig {
+    /** Bundled font files keyed by their PostScript font name, used as native fontFamily. */
+    nativeFonts?: Record<string, {
+        src: string;
+        license?: string;
+    }>;
+    appName: string;
+    packageName: string;
+    renderer?: 'web' | 'native';
+    /** "system" follows the device; light/dark pin the generated host. */
+    appearance?: 'light' | 'dark' | 'system';
+    /** Static native tab-bar styling applied before the page's own tabBar.set call. */
+    tabBar?: CraftTabBarConfig;
+    /** Runs from the generated project root before Gradle compiles the app. */
+    postGenerate?: CraftPostGenerateHook;
+    version?: string;
+    versionCode?: number;
+    darkMode?: boolean;
+    backgroundColor?: string;
+    backgroundColorDark?: string;
+    enableSpeechRecognition?: boolean;
+    enableAudioRecording?: boolean;
+    enableHaptics?: boolean;
+    enableShare?: boolean;
+    enableCamera?: boolean;
+    enableBiometric?: boolean;
+    enablePushNotifications?: boolean;
+    /** Enable native SQLite queries and transactions. Disabled unless explicitly true. */
+    enableLocalDatabase?: boolean;
+    /** Enable native AlarmManager local notification scheduling. Disabled unless explicitly true. */
+    enableLocalNotifications?: boolean;
+    /** Notification buttons and inline replies registered at launch. */
+    notificationCategories?: NativeNotificationCategory[];
+    enableSecureStorage?: boolean;
+    enableGeolocation?: boolean;
+    enableBackgroundLocation?: boolean;
+    /** Foreground raw Android sensors on native screens; separate from iOS fused motion. */
+    enableMotionSensors?: boolean;
+    /** Foreground pressure and session-relative altitude; does not enable background recording. */
+    enableBarometer?: boolean;
+    /** Foreground hardware step counters/detectors; requires activity recognition on Android 10+. */
+    enablePedometer?: boolean;
+    enableBluetooth?: boolean;
+    /**
+     * A Bluetooth heart-rate strap, or a watch broadcasting its heart rate (the
+     * standard Heart Rate Service), through `craft.heartRate` on a page and the
+     * `HeartRate` module on a native screen (CraftHeartRate.kt): scan, connect,
+     * live readings as `craftHeartRate` events, and a recording kept natively,
+     * in the foreground (a connectedDevice service) while it runs. The iOS
+     * builder's flag of the same name.
+     */
+    enableHeartRate?: boolean;
+    enableHealthConnect?: boolean;
+    /** Android Health Services live exercise tracking for native screens. Requires minSdk 30. */
+    enableHealthServices?: boolean;
+    /** Google Wallet save-link or native SDK handoff for native screens. */
+    enableWallet?: 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). */
+    enableLocalNetwork?: boolean;
+    urlSchemes?: string[];
+    /** HTTPS hosts owned by the app; path rules are ordered, with `*` matching any path text. */
+    /** Ordered path rules: * matches zero or more characters, ? one, and ?* one or more. */
+    appLinks?: Array<{
+        host: string;
+        paths?: Array<{
+            pattern: string;
+            exclude?: boolean;
+        }>;
+    }>;
+    trustedOrigins?: string[];
+    appIconPath?: string;
+    /**
+     * The launch splash: a directory laid out as Android resources, holding
+     * `drawable-<density>/splash_icon.png` (Android 12's splash icon, 288dp
+     * with its content inside the 192dp circle) and `splash_logo.png` (the
+     * logo the window background centres before Android 12), with Dark Mode
+     * ones in `drawable-night-<density>`. ts-images' `generateSplashScreens`
+     * writes exactly this (`android.resources`). Both sit on `backgroundColor`
+     * (`backgroundColorDark` at night), the colour the first frame continues.
+     * Without it, Android 12 shows the launcher icon and older versions the
+     * background colour.
+     */
+    splashResources?: string;
+    /**
+     * The small icon in the status bar and on every notification the app
+     * shows, push or local: an Android vector drawable (`.xml`) or a `.png`,
+     * white on transparent, since Android draws only its shape. Without one,
+     * a white Craft mark. Never the launcher icon, which shows as a white
+     * square.
+     */
+    notificationIconPath?: string;
+    /** The `#RRGGBB` Android tints the notification icon and app name with. The system's own colour without it. */
+    notificationColor?: string;
+    googleServicesFile?: string;
+    /** Native map renderer. MapLibre needs no SDK key; Google remains the default for compatibility. */
+    mapProvider?: AndroidMapProvider;
+    /** Google Maps Android SDK key, used only by the Google native map host. */
+    mapsApiKey?: string;
+    devServerURL?: string;
+    hasBundledFallback?: boolean;
+    /** Android API level, at least ANDROID_MIN_SDK (26), or 30 with Health Services. */
+    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>;
+    nativeScreenConstraints?: NativeRouteConstraints;
+    tabs?: Array<{
+        id: string;
+        title: string;
+        symbol?: string;
+        /** Native selected-tab icon overrides, also supported by navigation.setOptions({ tabItem }). */
+        selectedSymbol?: string;
+        selectedIconTint?: string;
+        selectedIconPulse?: boolean;
+    }>;
+    nativeApp?: string;
+    /**
+     * The secure-storage key the signed-in account's token lives under
+     * (default `auth.token`). `craft.session` follows it on every native
+     * screen, and a change of it is `SESSION_CHANGED { key, token, previous }`.
+     */
+    sessionTokenKey?: string;
+    /** Wake the app script every so often (`craftBackgroundRefresh`), through WorkManager. */
+    backgroundRefresh?: {
+        enabled?: boolean;
+        minimumIntervalMinutes?: number;
+    };
+    /**
+     * Crash and error reporting to bughq (CraftCrashReporter.kt): uncaught JVM
+     * exceptions, ANRs and native crashes (ApplicationExitInfo), uncaught
+     * JavaScript errors, and what the page sends through `craft.crashReporter`.
+     * Queued on disk and sent when online. Release builds are minified: upload
+     * `app/build/outputs/mapping/release/mapping.txt` so bughq can retrace.
+     */
+    crashReporting?: {
+        /** The bughq project's public ingest key. */
+        key: string;
+        /** Default https://bughq.org. */
+        host?: string;
+        /** Default `production`. */
+        environment?: string;
+        /** Default `<versionName>+<versionCode>`, e.g. `1.0.0+41`. */
+        release?: string;
+        /** One session per launch, for crash-free sessions. Default on. */
+        sessions?: boolean;
+    };
+}
+export interface CraftTabBarConfig {
+    selection?: {
+        /** The selected tab indicator's corner radius in dp; omitted keeps the default. */
+        cornerRadius?: number;
+        /** The selected tab indicator fill as #RRGGBB. */
+        color?: string;
+    };
+}
+/** A declared command Craft runs after the native project has been generated. */
+export interface CraftPostGenerateHook {
+    command: string;
+    args?: string[];
+}
+/** 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' | 'bloodGlucose' | 'insulinDelivery';
+/**
+ * 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;
+    output: string;
+    config?: Partial<CraftAndroidConfig>;
+    /**
+     * Where to find the Zig runtime's `<abi>/libcraft.so`.
+     *
+     * `null` means no runtime regardless of the environment; `undefined` falls
+     * through to `CRAFT_ANDROID_RUNTIME`. Same shape as the iOS builder's
+     * `runtimeDir`.
+     */
+    runtimeDir?: string | null;
+}
+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;
+}
+/**
+ * Run the app's declared generator hook without invoking a shell.
+ *
+ * A hook gets the generated project as its cwd and explicit metadata so a
+ * patch can target the right platform and phase without guessing from paths.
+ */
+export declare function runPostGenerateHook(hook: CraftPostGenerateHook | undefined, output: string, phase?: 'build'): void;
+export interface OpenOptions {
+    output: string;
+}
+export interface RunOptions {
+    device?: string;
+    output: string;
+}
+/** A splash file, by its place under `res/` (`drawable-night-xxhdpi/splash_icon.png`). */
+export interface AndroidSplashFile {
+    folder: string;
+    name: 'splash_icon.png' | 'splash_logo.png';
+    path: string;
+}
+/**
+ * The splash files in a resources directory: `splash_icon.png` and
+ * `splash_logo.png` in each `drawable[-night][-<density>]` folder. A directory
+ * with neither is a mistake, not an app without a splash.
+ */
+export declare function androidSplashFiles(resources: string): AndroidSplashFile[];
+/**
+ * The launch theme the activity starts in, and the theme it swaps to before
+ * its first frame. Android 12 and later draw their splash from
+ * `windowSplashScreen*`; earlier versions draw the window background, here
+ * the logo centred on the background colour. Either way the colour is the
+ * app's own `background`, so nothing flashes when the first frame replaces it.
+ */
+export declare function androidLaunchThemes(splash: Pick<AndroidSplashFile, 'name'>[]): {
+    base: string;
+    v31: string;
+    background?: string;
+};
+export declare function syncAndroidWebAssets(source: string, output: string): void;
+export declare function renderAndroidPermissions(config: CraftAndroidConfig): string;
+export declare function renderAndroidDeepLinks(config: CraftAndroidConfig): string;
+/**
+ * Where the runtime directory comes from when the caller does not say.
+ *
+ * The same shape as `CRAFT_BIN` and the iOS builder's `CRAFT_IOS_RUNTIME`: an
+ * explicit override for the monorepo dev loop, not a lookup path. Shipping the
+ * runtime to real apps means putting these libraries in the pantry package
+ * beside the `craft` binary, which is a distribution decision this function
+ * does not make.
+ */
+export declare function resolveRuntimeDir(override?: string | null): string | null;
+/**
+ * Copy the Zig runtime into the generated project as
+ * `app/src/main/jniLibs/<abi>/libcraft.so`.
+ *
+ * That path is AGP's default `jniLibs.srcDirs`, so nothing in the Gradle
+ * templates has to know about it — the library is packaged into the APK and
+ * `System.loadLibrary("craft")` finds it because the file is named for the
+ * `craft` it asks for.
+ *
+ * Until this existed, nothing put the library anywhere. `CraftNative` caught
+ * the `UnsatisfiedLinkError`, set `isAvailable = false`, and every action fell
+ * through to the Kotlin shim — by design, so an app with no runtime still
+ * works, which is also why nobody noticed that *every* generated app was in
+ * that state and the whole Android half of the Zig bridge had never run.
+ *
+ * Returns true when a runtime was installed.
+ */
+export declare function installRuntime(output: string, runtimeDir: string): boolean;
+export declare function init(options: InitOptions): Promise<void>;
+/**
+ * Build Android project
+ */
+export declare function build(options: BuildOptions): Promise<void>;
+/**
+ * Open Android project in Android Studio
+ */
+export declare function open(options: OpenOptions): Promise<void>;
+/**
+ * Run on Android device or emulator
+ */
+export declare function run(options: RunOptions): Promise<void>;
+/** The native host enforces declared named-parameter constraints. */
+export declare const nativeRouteConstraints = true;

package/dist/internal/android/src/testing.d.ts

@@ -0,0 +1,2 @@
+/** Uses the Android builder's Kotlin version, including its transitive compiler dependencies. */
+export declare function runKotlinFixture(source: string, libraries?: readonly string[]): Promise<void>;

package/dist/internal/typescript/src/native-notifications.d.ts

@@ -0,0 +1,17 @@
+/** Registered before notification delivery; payloads reference category ids. */
+export interface NativeNotificationCategory {
+    id: string;
+    actions: {
+        id: string;
+        title: string;
+        destructive?: boolean;
+        /** Open the app. Otherwise nativeApp handles the action in the background. */
+        foreground?: boolean;
+        authenticationRequired?: boolean;
+        textInput?: {
+            buttonTitle: string;
+            placeholder?: string;
+        };
+    }[];
+}
+export declare function nativeNotificationProblems(categories: unknown, nativeApp?: string, renderer?: string): string[];

package/dist/internal/typescript/src/native-routing.d.ts

@@ -0,0 +1,26 @@
+/** Constraints on decoded named path parameters; query items cannot override them. */
+export interface NativeParameterConstraint {
+    /** A case-sensitive regular expression for the complete normalized value. */
+    pattern?: string;
+    exclude?: readonly string[];
+    /** Normalize decoded values and exclusions before case-sensitive grammar validation. */
+    normalize?: 'lowercase';
+}
+export type NativeRouteConstraints = Record<string, Record<string, NativeParameterConstraint>>;
+/** Validate and normalize the decoded parameter map before query binding. */
+export declare function applyNativeParameterConstraints(params: Record<string, string>, rules?: Record<string, NativeParameterConstraint>): boolean;
+export declare function nativeRouteConstraintProblems(screens?: Record<string, string>, constraints?: NativeRouteConstraints): string[];
+/** `/a//b/?q#h` → `/a/b`, the way the shell and the page compare paths. Null for a relative path. */
+export declare function normalizeNativePath(raw: string): string | null;
+export interface NativePathMatch {
+    path: string;
+    screen: string;
+    params: Record<string, string>;
+}
+export declare function routeSegments(path: string): string[];
+/**
+ * The native screen for a path, by the rules the shell (`CraftHybridRoutes`)
+ * and the page script apply: static segments win over `:params`, which win
+ * over a trailing `*`; query items become params under the path's own.
+ */
+export declare function matchNativePath(nativeScreens: Record<string, string> | undefined, raw: string, constraints?: NativeRouteConstraints): NativePathMatch | null;

package/package.json

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

package/templates/CraftNativeBackground.kt.template

@@ -132,12 +132,23 @@ internal object CraftNativeBundle {
  * ([CraftNativeHeadlessApp]) and closed when it answers. A silent push
  * (`craftSilentPush`) runs the same way, once.
  */
+/** WorkManager Data is capped at 10 KiB; keep replies in app-private storage. */
+internal object CraftNativeBackgroundPayload {
+    private fun storage(context: Context) = context.getSharedPreferences("craft-native-background-payloads", Context.MODE_PRIVATE)
+    fun write(context: Context, text: String): String? {
+        val id = UUID.randomUUID().toString()
+        return if (storage(context).edit().putString(id, text).commit()) id else null
+    }
+    fun read(context: Context, id: String): String? = storage(context).getString(id, null)
+    fun remove(context: Context, id: String) { storage(context).edit().remove(id).commit() }
+}
+
 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
+    @Volatile var foreground: ((event: String, id: String, detail: JSONObject, done: (Boolean) -> Unit) -> Boolean)? = null
 
     fun schedule(context: Context, config: JSONObject) {
         val refresh = config.optJSONObject("backgroundRefresh")
@@ -154,35 +165,63 @@ internal object CraftNativeBackground {
         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)
+    /** Persist action payloads before scheduling; enqueue completion releases a receiver's goAsync hold. */
+    fun runOnce(context: Context, event: String, detail: JSONObject? = null, queued: (() -> Unit)? = null) {
+        val payload = detail?.let { CraftNativeBackgroundPayload.write(context, it.toString()) }
+        if (detail != null && payload == null) {
+            Log.e("CraftNativeAndroid", "Could not persist $event")
+            queued?.invoke()
+            return
+        }
+        val builder = OneTimeWorkRequestBuilder<CraftNativeRefreshWorker>()
+            .setInputData(workDataOf("event" to event, "payload" to payload))
+        // A local action may work without a network connection. Silent push
+        // keeps its existing connected-network constraint.
+        if (detail == null) builder.setConstraints(Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED).build())
+        try {
+            val operation = WorkManager.getInstance(context).enqueueUniqueWork(ONCE, ExistingWorkPolicy.APPEND_OR_REPLACE, builder.build())
+            operation.result.addListener({
+                try { operation.result.get() }
+                catch (failure: Exception) { Log.e("CraftNativeAndroid", "Could not enqueue $event", failure) }
+                finally { queued?.invoke() }
+            }, ContextCompat.getMainExecutor(context))
+        } catch (failure: Exception) {
+            Log.e("CraftNativeAndroid", "Could not enqueue $event", failure)
+            queued?.invoke()
+        }
     }
 }
 
 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
+        val payload = inputData.getString("payload")
+        val detail = if (payload == null) JSONObject() else {
+            val raw = CraftNativeBackgroundPayload.read(applicationContext, payload)
+                ?: return Result.failure()
+            runCatching { JSONObject(raw) }.getOrElse { return Result.failure() }
         }
-        Log.i("CraftNativeAndroid", "$event $id: ${if (running) "the running app script" else "a background app script"}")
+        // Stable across retries so an app can deduplicate a side effect.
+        val id = payload ?: UUID.randomUUID().toString()
+        val answer = CompletableDeferred<Boolean>()
         var headless: CraftNativeHeadlessApp? = null
-        if (!running) {
-            headless = withContext(Dispatchers.Main) { CraftNativeHeadlessApp(applicationContext, event, id) { ok -> answer.complete(ok) } }
-            withContext(Dispatchers.Main) { headless.start() }
+        try {
+            val running = withContext(Dispatchers.Main) {
+                CraftNativeBackground.foreground?.invoke(event, id, detail) { ok -> answer.complete(ok) } == true
+            }
+            if (!running) {
+                headless = withContext(Dispatchers.Main) { CraftNativeHeadlessApp(applicationContext, event, id, detail) { ok -> answer.complete(ok) } }
+                withContext(Dispatchers.Main) { headless?.start() }
+            }
+            val ok = withTimeoutOrNull(9 * 60 * 1000L) { answer.await() }
+            // An unacknowledged action keeps its payload for retry; refresh
+            // retains its original timeout behavior.
+            if (ok == false || (payload != null && ok == null)) return Result.retry()
+            if (payload != null) CraftNativeBackgroundPayload.remove(applicationContext, payload)
+            return Result.success()
+        } finally {
+            withContext(kotlinx.coroutines.NonCancellable + Dispatchers.Main) { headless?.close() }
         }
-        // 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()
     }
 }
 
@@ -195,6 +234,7 @@ internal class CraftNativeHeadlessApp(
     private val context: Context,
     private val event: String,
     private val id: String,
+    private val detail: JSONObject,
     private val onDone: (Boolean) -> Unit,
 ) {
     private val config: JSONObject = runCatching {
@@ -218,13 +258,13 @@ internal class CraftNativeHeadlessApp(
 
     fun start() {
         val route = config.optString("nativeApp")
-        if (route.isBlank() || !JavaScriptSandbox.isSupported()) return finish(true)
-        val bundle = CraftNativeBundle.source(context, route) ?: return finish(true)
+        if (route.isBlank() || !JavaScriptSandbox.isSupported()) return finish(detail.length() == 0)
+        val bundle = CraftNativeBundle.source(context, route) ?: return finish(detail.length() == 0)
         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)
+                return@connect finish(detail.length() == 0)
             }
             val created = engine.createIsolate()
             isolate = created
@@ -264,7 +304,7 @@ internal class CraftNativeHeadlessApp(
                     load.addListener({
                         try {
                             load.get()
-                            send("CRAFT_EVENT", JSONObject().put("event", event).put("detail", JSONObject().put("id", id)))
+                            send("CRAFT_EVENT", JSONObject().put("event", event).put("detail", JSONObject(detail.toString()).put("id", id)))
                         } catch (failure: Exception) {
                             Log.e(TAG, "Background refresh script failed", failure)
                             finish(false)

package/templates/CraftNativeCapabilities.kt.template

@@ -1297,7 +1297,7 @@ internal class CraftNativeCapabilities(
             }
             "cancelAll" -> {
                 notificationStorage.all.keys.forEach(::cancelNotification)
-                (context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager).cancelAll()
+                CraftNativeNotifications.cancelAll(context)
                 complete(requestToken, success(true), completion)
             }
             "pending" -> complete(requestToken, success(JSONArray(notificationStorage.all.values.mapNotNull {
@@ -1317,6 +1317,7 @@ internal class CraftNativeCapabilities(
     private fun schedule(value: JSONObject?): CraftNativeCapabilityResult {
         val title = value?.optString("title").orEmpty()
         if (title.isEmpty()) return failure("INVALID_ARGUMENT", "Notifications.schedule needs a title")
+        CraftNativeNotifications.invalidOptions(value!!)?.let { return failure("INVALID_ARGUMENT", it) }
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU &&
             ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS) != PackageManager.PERMISSION_GRANTED) {
             return failure("PERMISSION_DENIED", "Notification permission denied")
@@ -1347,6 +1348,7 @@ internal class CraftNativeCapabilities(
     }
 
     private fun cancelNotification(id: String) {
+        CraftNativeNotifications.cancel(context, id)
         val alarm = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager
         val intent = notificationIntent(id)
         alarm.cancel(intent)

package/templates/CraftNativeMessagingService.kt.template

@@ -1,14 +1,6 @@
 package {{PACKAGE_NAME}}
 
-import android.app.NotificationChannel
-import android.app.NotificationManager
-import android.app.PendingIntent
 import android.content.Context
-import android.content.Intent
-import android.os.Build
-import androidx.core.app.NotificationCompat
-import androidx.core.app.NotificationManagerCompat
-import androidx.core.content.ContextCompat
 import com.google.firebase.messaging.FirebaseMessagingService
 import com.google.firebase.messaging.RemoteMessage
 import org.json.JSONObject
@@ -41,6 +33,10 @@ class CraftNativeMessagingService : FirebaseMessagingService() {
         if (notification == null) {
             if (message.data["content-available"] == "1" || message.data["contentAvailable"] == "true") {
                 CraftNativeBackground.runOnce(applicationContext, "craftSilentPush")
+            } else if (!message.data["categoryId"].isNullOrBlank()) {
+                // Use a data-only FCM payload for background action buttons;
+                // FCM owns notifications with a notification block itself.
+                show(message.data["title"].orEmpty(), message.data["body"].orEmpty(), message.data)
             }
             return
         }
@@ -49,26 +45,10 @@ class CraftNativeMessagingService : FirebaseMessagingService() {
     }
 
     private fun show(title: String, body: String, data: Map<String, String>) {
-        val manager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && manager.getNotificationChannel(CHANNEL) == null) {
-            manager.createNotificationChannel(NotificationChannel(CHANNEL, applicationInfo.loadLabel(packageManager), NotificationManager.IMPORTANCE_DEFAULT))
-        }
-        val open = Intent(this, MainActivity::class.java)
-            .addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP)
-            .putExtra("craft.notification", true)
-        data.forEach { (key, value) -> open.putExtra(key, value) }
-        val id = (data["notification_id"]?.toIntOrNull() ?: System.currentTimeMillis().toInt())
-        val tap = PendingIntent.getActivity(this, id, open, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE)
-        val built = NotificationCompat.Builder(this, CHANNEL)
-            .setSmallIcon(R.drawable.craft_notification_icon)
-            .setColor(ContextCompat.getColor(this, R.color.craft_notification_color))
-            .setContentTitle(title)
-            .setContentText(body)
-            .setStyle(NotificationCompat.BigTextStyle().bigText(body))
-            .setAutoCancel(true)
-            .setContentIntent(tap)
-            .build()
-        runCatching { NotificationManagerCompat.from(this).notify(id, built) }
+        val value = JSONObject().put("title", title).put("body", body).put("data", JSONObject(data))
+        for (key in listOf("categoryId", "threadIdentifier", "interruptionLevel")) data[key]?.let { value.put(key, it) }
+        val id = data["notification_id"] ?: java.util.UUID.randomUUID().toString()
+        CraftNativeNotifications.show(this, value, id, CHANNEL)
     }
 
     companion object {