craft-native 0.0.451 → 0.0.467

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

@@ -1,3 +1,6 @@
+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';
@@ -64,6 +67,8 @@ export interface CraftAndroidConfig {
     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;
@@ -161,6 +166,7 @@ export interface CraftAndroidConfig {
      * 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;
@@ -348,3 +354,5 @@ 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/android/src/index.js

@@ -1,4 +1,212 @@
 // @bun
+// src/native-notifications.ts
+function nativeNotificationProblems(categories, nativeApp, renderer) {
+  if (categories === undefined)
+    return [];
+  if (!Array.isArray(categories))
+    return ["notificationCategories must be an array."];
+  const problems = [];
+  const categoryIds = new Set;
+  const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+  const text = (value) => typeof value === "string" && value.trim().length > 0;
+  for (const [index, category] of categories.entries()) {
+    const field = `notificationCategories[${index}]`;
+    if (!object(category) || !text(category.id)) {
+      problems.push(`${field} needs a nonempty id.`);
+      continue;
+    }
+    if (categoryIds.has(category.id))
+      problems.push(`${field}.id must be unique.`);
+    categoryIds.add(category.id);
+    if (!Array.isArray(category.actions) || category.actions.length < 1 || category.actions.length > 3) {
+      problems.push(`${field}.actions must contain 1\u20133 actions for both platforms.`);
+      continue;
+    }
+    const actionIds = new Set;
+    for (const [position, action] of category.actions.entries()) {
+      const path = `${field}.actions[${position}]`;
+      if (!object(action) || !text(action.id) || !text(action.title)) {
+        problems.push(`${path} needs a nonempty id and title.`);
+        continue;
+      }
+      if (action.id.startsWith("com.apple.") || actionIds.has(action.id))
+        problems.push(`${path}.id must be unique and must not use Apple's reserved prefix.`);
+      actionIds.add(action.id);
+      for (const flag of ["destructive", "foreground", "authenticationRequired"]) {
+        if (action[flag] !== undefined && typeof action[flag] !== "boolean")
+          problems.push(`${path}.${flag} must be a boolean.`);
+      }
+      if (!nativeApp?.trim() && (action.foreground !== true || renderer === "native"))
+        problems.push(`${path} requires nativeApp to receive native/background action events.`);
+      if (action.textInput !== undefined && (!object(action.textInput) || !text(action.textInput.buttonTitle) || action.textInput.placeholder !== undefined && typeof action.textInput.placeholder !== "string")) {
+        problems.push(`${path}.textInput needs a buttonTitle and an optional string placeholder.`);
+      }
+    }
+  }
+  return problems;
+}
+
+// src/native-routing.ts
+function applyNativeParameterConstraints(params, rules) {
+  if (rules === undefined)
+    return true;
+  if (!rules || typeof rules !== "object" || Array.isArray(rules))
+    return false;
+  for (const [name, rule] of Object.entries(rules)) {
+    let value = params[name];
+    if (typeof value !== "string" || !rule || typeof rule !== "object" || Array.isArray(rule))
+      return false;
+    if (Object.keys(rule).some((key) => !["pattern", "exclude", "normalize"].includes(key)))
+      return false;
+    if (rule.normalize !== undefined && rule.normalize !== "lowercase")
+      return false;
+    if (rule.normalize === "lowercase")
+      value = value.toLowerCase();
+    if (rule.exclude !== undefined) {
+      if (!Array.isArray(rule.exclude) || rule.exclude.some((item) => typeof item !== "string"))
+        return false;
+      if (rule.exclude.some((item) => (rule.normalize === "lowercase" ? item.toLowerCase() : item) === value))
+        return false;
+    }
+    if (rule.pattern !== undefined) {
+      if (typeof rule.pattern !== "string")
+        return false;
+      try {
+        const matched = new RegExp(`^(?:${rule.pattern})$`).exec(value);
+        if (!matched || matched[0] !== value)
+          return false;
+      } catch {
+        return false;
+      }
+    }
+    params[name] = value;
+  }
+  return true;
+}
+function nativeRouteConstraintProblems(screens, constraints) {
+  const problems = [];
+  if (constraints === undefined)
+    return problems;
+  if (!constraints || typeof constraints !== "object" || Array.isArray(constraints))
+    return ["nativeScreenConstraints must name route parameter constraints."];
+  for (const [route, rules] of Object.entries(constraints)) {
+    const prefix = `nativeScreenConstraints[${JSON.stringify(route)}]`;
+    if (!Object.prototype.hasOwnProperty.call(screens ?? {}, route))
+      problems.push(`${prefix} names no native screen route.`);
+    if (!rules || typeof rules !== "object" || Array.isArray(rules)) {
+      problems.push(`${prefix} must name parameter constraints.`);
+      continue;
+    }
+    const names = route.split("/").filter((part) => part.startsWith(":")).map((part) => part.slice(1));
+    for (const [name, rule] of Object.entries(rules)) {
+      const field = `${prefix}[${JSON.stringify(name)}]`;
+      if (!names.includes(name))
+        problems.push(`${field} names no path parameter.`);
+      if (!rule || typeof rule !== "object" || Array.isArray(rule)) {
+        problems.push(`${field} must be a parameter constraint.`);
+        continue;
+      }
+      if (Object.keys(rule).some((key) => !["pattern", "exclude", "normalize"].includes(key)))
+        problems.push(`${field} has an unknown constraint field.`);
+      if (rule.exclude !== undefined && (!Array.isArray(rule.exclude) || rule.exclude.some((value) => typeof value !== "string")))
+        problems.push(`${field}.exclude must contain strings.`);
+      if (rule.normalize !== undefined && rule.normalize !== "lowercase")
+        problems.push(`${field}.normalize must be lowercase.`);
+      if (rule.pattern !== undefined) {
+        try {
+          if (typeof rule.pattern !== "string")
+            throw new Error("not a string");
+          new RegExp(`^(?:${rule.pattern})$`);
+        } catch {
+          problems.push(`${field}.pattern must be a valid regular expression.`);
+        }
+      }
+    }
+  }
+  return problems;
+}
+function normalizeNativePath(raw) {
+  if (typeof raw !== "string")
+    return null;
+  let path = raw;
+  const cut = path.search(/[?#]/);
+  if (cut >= 0)
+    path = path.slice(0, cut);
+  if (!path.startsWith("/"))
+    return null;
+  path = path.replace(/\/{2,}/g, "/");
+  if (path.length > 1 && path.endsWith("/"))
+    path = path.slice(0, -1);
+  return path;
+}
+function routeSegments(path) {
+  return path === "/" ? [] : path.slice(1).split("/");
+}
+function matchNativePath(nativeScreens, raw, constraints) {
+  if (constraints !== undefined && (!constraints || typeof constraints !== "object" || Array.isArray(constraints)))
+    return null;
+  const path = normalizeNativePath(raw);
+  if (path === null)
+    return null;
+  const routes = Object.entries(nativeScreens ?? {}).map(([pattern, screen]) => ({ key: pattern, pattern: normalizeNativePath(pattern), screen })).filter((route) => route.pattern !== null && !!route.screen).map((route) => ({ ...route, segments: routeSegments(route.pattern) }));
+  const wild = (segments) => segments.at(-1) === "*" ? 1 : 0;
+  const fixed = (segments) => segments.filter((s) => s !== "*" && !s.startsWith(":")).length;
+  routes.sort((a, b) => wild(a.segments) - wild(b.segments) || fixed(b.segments) - fixed(a.segments) || b.segments.length - a.segments.length || (a.pattern < b.pattern ? -1 : a.pattern > b.pattern ? 1 : 0));
+  const decode = (value) => {
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  };
+  const parts = routeSegments(path);
+  for (const route of routes) {
+    const params = {};
+    let matched = true;
+    for (let i = 0;i < route.segments.length; i++) {
+      const segment = route.segments[i];
+      if (segment === "*") {
+        params["*"] = parts.slice(i).join("/");
+        break;
+      }
+      if (i >= parts.length) {
+        matched = false;
+        break;
+      }
+      if (segment.startsWith(":")) {
+        if (!parts[i]) {
+          matched = false;
+          break;
+        }
+        params[segment.slice(1)] = decode(parts[i]);
+      } else if (segment !== parts[i]) {
+        matched = false;
+        break;
+      }
+    }
+    if (!matched)
+      continue;
+    if (route.segments.at(-1) !== "*" && route.segments.length !== parts.length)
+      continue;
+    if (!applyNativeParameterConstraints(params, constraints?.[route.key]))
+      continue;
+    const query = raw.indexOf("?");
+    if (query >= 0) {
+      for (const item of raw.slice(query + 1).split("#")[0].split("&")) {
+        if (!item)
+          continue;
+        const [rawKey = "", ...rest] = item.split("=");
+        const key = decode(rawKey);
+        if (!key || key in params)
+          continue;
+        params[key] = decode(rest.join("=").replace(/\+/g, " "));
+      }
+    }
+    return { path, screen: route.screen, params };
+  }
+  return null;
+}
+
 // ../android/src/index.ts
 import { gzipSync } from "zlib";
 import { cpSync, existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, readdirSync, rmSync as rmSync2, statSync, writeFileSync } from "fs";
@@ -128,7 +336,7 @@ import { readFileSync } from "fs";
 import { mkdtemp, rm, writeFile } from "fs/promises";
 import { tmpdir } from "os";
 import { dirname, join } from "path";
-async function runKotlinFixture(source) {
+async function runKotlinFixture(source, libraries = []) {
   const gradle = Bun.which("gradle");
   if (!gradle)
     throw new Error("Gradle is required to run native Kotlin fixtures");
@@ -152,6 +360,8 @@ configurations {
 dependencies {
     kotlinCompiler 'org.jetbrains.kotlin:kotlin-compiler-embeddable:${version}'
     kotlinRuntime 'org.jetbrains.kotlin:kotlin-stdlib:${version}'
+${libraries.map((library) => `    kotlinRuntime ${JSON.stringify(library)}`).join(`
+`)}
 }
 tasks.register('compileFixture', JavaExec) {
     classpath = configurations.kotlinCompiler
@@ -932,32 +1142,8 @@ function normalizeNativeRoutePath(raw) {
 function nativeRouteSegments(path) {
   return path === "/" ? [] : path.slice(1).split("/");
 }
-function matchesNativeRoute(nativeScreens, raw) {
-  const path = normalizeNativeRoutePath(raw);
-  if (path === null)
-    return false;
-  const parts = nativeRouteSegments(path);
-  return Object.entries(nativeScreens ?? {}).some(([pattern, screen]) => {
-    if (!screen)
-      return false;
-    const normalized = normalizeNativeRoutePath(pattern);
-    if (normalized === null)
-      return false;
-    const route = nativeRouteSegments(normalized);
-    for (let index = 0;index < route.length; index++) {
-      const segment = route[index];
-      if (segment === "*")
-        return index === route.length - 1;
-      if (index >= parts.length)
-        return false;
-      if (segment.startsWith(":")) {
-        if (!parts[index])
-          return false;
-      } else if (segment !== parts[index])
-        return false;
-    }
-    return route.length === parts.length;
-  });
+function matchesNativeRoute(nativeScreens, raw, constraints) {
+  return matchNativePath(nativeScreens, raw, constraints) !== null;
 }
 function nativeStartPath(config) {
   if (!config.devServerURL)
@@ -970,6 +1156,15 @@ function nativeStartPath(config) {
   }
 }
 function validateNativeRouteConfig(config) {
+  const constraintProblems = [
+    ...nativeRouteConstraintProblems(config.nativeScreens, config.nativeScreenConstraints),
+    ...nativeNotificationProblems(config.notificationCategories, config.nativeApp, config.renderer)
+  ];
+  if ((config.notificationCategories?.length ?? 0) > 0 && config.renderer !== "native")
+    constraintProblems.push("notificationCategories currently requires the native Android renderer.");
+  if (constraintProblems.length)
+    throw new Error(constraintProblems.join(`
+`));
   const screens = Object.entries(config.nativeScreens ?? {});
   for (const [pattern, screen] of screens) {
     if (normalizeNativeRoutePath(pattern) !== pattern || /[?#]/.test(pattern))
@@ -989,11 +1184,11 @@ function validateNativeRouteConfig(config) {
   }
   if (config.renderer === "native" && screens.length > 0) {
     for (const id of ids) {
-      if (!matchesNativeRoute(config.nativeScreens, id))
+      if (!matchesNativeRoute(config.nativeScreens, id, config.nativeScreenConstraints))
         throw new Error(`Tab "${id}" is not a nativeScreens path; with renderer: "native" every tab must be a native screen.`);
     }
     const start = nativeStartPath(config);
-    if (!matchesNativeRoute(config.nativeScreens, start))
+    if (!matchesNativeRoute(config.nativeScreens, start, config.nativeScreenConstraints))
       throw new Error(`The start path "${start}" (from devServerURL) is not a nativeScreens path; with renderer: "native" the app must start on a native screen.`);
   }
   if (config.nativeApp !== undefined) {
@@ -1059,7 +1254,7 @@ function renderAndroidPermissions(config) {
     permissions.add("android.permission.FOREGROUND_SERVICE");
     permissions.add("android.permission.FOREGROUND_SERVICE_LOCATION");
   }
-  if (config.enablePushNotifications)
+  if (config.enablePushNotifications || config.enableLocalNotifications)
     permissions.add("android.permission.POST_NOTIFICATIONS");
   if (config.enableKeepAwake || config.enableBarometer && config.enableBackgroundLocation)
     permissions.add("android.permission.WAKE_LOCK");
@@ -1767,6 +1962,7 @@ async function run(options) {
     throw error;
   }
 }
+var nativeRouteConstraints = true;
 export {
   ANDROID_MIN_SDK,
   HEALTH_CONNECT_PERMISSIONS,
@@ -1781,6 +1977,7 @@ export {
   nativeMapProviders,
   nativeMessages,
   nativeRouteBundles,
+  nativeRouteConstraints,
   nativeRouteRuntime,
   nativeSensorCapabilities,
   open,

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

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

package/dist/android/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/dist/android/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/dist/android/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 {