akanjs 3.0.0-beta.20 → 3.0.0-beta.21

package/vendor/@akanjs/native/plugins/keyboard/android/KeyboardPlugin.kt

@@ -0,0 +1,77 @@
+package com.akanjs.plugins.keyboard
+
+import android.app.Activity
+import android.os.Build
+import android.view.WindowInsets
+import android.view.inputmethod.InputMethodManager
+import com.akanjs.runtime.AkanNativeInsets
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeReply
+import com.akanjs.runtime.AkanNativeVoidReply
+
+/**
+ * Soft keyboard from the IME window insets the shell tracks. height = ime.bottom − systemBars.bottom
+ * in dp (react-native ReactRootView uses the same definition). The shell pads the WebView by the
+ * IME, so the page itself is not covered.
+ * The result and event types come from the generated KeyboardPluginSpec (PL-10).
+ */
+class KeyboardPlugin(private val context: AkanNativePluginContext) : KeyboardPluginSpec {
+    private var listening = false
+    private var last: KeyboardState? = null
+    private val events = KeyboardEvents(context)
+
+    /** Events the page listens to (change, willShow, didShow, willHide, didHide). */
+    private val listened = HashSet<String>()
+
+    init {
+        context.onInsetsChanged { insets ->
+            val next = state(insets)
+            if (next == last) return@onInsetsChanged
+            last = next
+            if (listening) events.change(next)
+        }
+        context.onKeyboardTransition { t ->
+            if (t.phase !in listened) return@onKeyboardTransition
+            val data = KeyboardTransition(height = Math.round(t.height).toDouble(), duration = t.durationMs.toDouble())
+            when (t.phase) {
+                "willShow" -> events.willShow(data)
+                "didShow" -> events.didShow(data)
+                "willHide" -> events.willHide(data)
+                "didHide" -> events.didHide(data)
+            }
+        }
+    }
+
+    override fun setResizeMode(args: KeyboardSetResizeModeArgs, reply: AkanNativeVoidReply) {
+        context.setImeResize(args.mode == KeyboardResizeMode.RESIZE)
+        reply.resolve()
+    }
+
+    private fun state(insets: AkanNativeInsets) = KeyboardState(visible = insets.imeVisible, height = Math.round(insets.imeHeight).toDouble())
+
+    override fun getState(reply: AkanNativeReply<KeyboardState>) = reply.resolve(state(context.insets))
+
+    override fun hide(reply: AkanNativeVoidReply) {
+        val activity = context.activity
+        activity.getSystemService(InputMethodManager::class.java)?.hideSoftInputFromWindow(context.webView.windowToken, 0)
+        // API 29 has no insets controller; hideSoftInputFromWindow is what androidx does there.
+        if (Build.VERSION.SDK_INT >= 30) Api30.hideIme(activity)
+        // Hiding the IME keeps DOM focus; blur so the next tap reopens it.
+        context.webView.evaluateJavascript("document.activeElement&&document.activeElement.blur&&document.activeElement.blur()", null)
+        reply.resolve()
+    }
+
+    override fun startListening(event: String) {
+        if (event == "change") listening = true else listened.add(event)
+    }
+
+    override fun stopListening(event: String) {
+        if (event == "change") listening = false else listened.remove(event)
+    }
+
+    private object Api30 {
+        fun hideIme(activity: Activity) {
+            activity.window.insetsController?.hide(WindowInsets.Type.ime())
+        }
+    }
+}

package/vendor/@akanjs/native/plugins/keyboard/ios/KeyboardPlugin.swift

@@ -0,0 +1,93 @@
+import UIKit
+
+/// Soft keyboard: the part of the web view the keyboard covers, in points (== CSS px).
+/// Measured from keyboardWillChangeFrame converted from screen to web view coordinates, so
+/// floating/undocked iPad keyboards and other apps' keyboards come out right
+/// (react-native RCTKeyboardObserver converts the same way).
+/// The result and event types come from the generated KeyboardPluginSpec (PL-10).
+final class KeyboardPlugin: KeyboardPluginSpec {
+    static let id = "keyboard"
+    private let context: AkanNativePluginContext
+    private var observers: [NSObjectProtocol] = []
+    private var state: (visible: Bool, height: Int) = (false, 0)
+    private lazy var events = KeyboardEvents(context)
+
+    init(context: AkanNativePluginContext) {
+        self.context = context
+        // Tracked from launch so getState() is right before anyone listens. The plugin lives as long as
+        // the app, so the observers are never removed.
+        for name in [UIResponder.keyboardWillChangeFrameNotification, UIResponder.keyboardWillHideNotification] {
+            observers.append(NotificationCenter.default.addObserver(forName: name, object: nil, queue: .main) { [weak self] note in
+                let info = UncheckedBox(note.userInfo ?? [:])
+                MainActor.assumeIsolated { self?.update(name, info.value) }
+            })
+        }
+        // O6-1: the transitions, before and after the keyboard's animation.
+        let phases: [(Notification.Name, String)] = [
+            (UIResponder.keyboardWillShowNotification, "willShow"), (UIResponder.keyboardDidShowNotification, "didShow"),
+            (UIResponder.keyboardWillHideNotification, "willHide"), (UIResponder.keyboardDidHideNotification, "didHide"),
+        ]
+        for (name, phase) in phases {
+            observers.append(NotificationCenter.default.addObserver(forName: name, object: nil, queue: .main) { [weak self] note in
+                let info = UncheckedBox(note.userInfo ?? [:])
+                MainActor.assumeIsolated { self?.transition(phase, info.value) }
+            })
+        }
+    }
+
+    /// The covered height, measured against the shell's root view: in "resize" mode the web view itself
+    /// ends at the keyboard, so it is never covered.
+    private func cover(_ info: [AnyHashable: Any], hiding: Bool) -> CGFloat {
+        if let shell = context.viewController as? AkanNativeViewController { return shell.keyboardCover(info, hiding: hiding) }
+        guard !hiding, let webView = context.webView, let window = webView.window,
+              let end = (info[UIResponder.keyboardFrameEndUserInfoKey] as? NSValue)?.cgRectValue else { return 0 }
+        return max(0, webView.bounds.intersection(webView.convert(end, from: window.screen.coordinateSpace)).height)
+    }
+
+    private func update(_ name: Notification.Name, _ info: [AnyHashable: Any]) {
+        let covered = cover(info, hiding: name == UIResponder.keyboardWillHideNotification)
+        let next = (visible: covered > 0, height: Int(covered.rounded()))
+        guard next.visible != state.visible || next.height != state.height else { return } // hide sends two notifications
+        state = next
+        let duration = (info[UIResponder.keyboardAnimationDurationUserInfoKey] as? NSNumber)?.doubleValue ?? 0
+        // The event carries the animation duration too, which KeyboardEvents.change (KeyboardState) has no field for.
+        var data = current.akanNativeJSON
+        data["duration"] = duration
+        context.emit("change", data)
+    }
+
+    private func transition(_ phase: String, _ info: [AnyHashable: Any]) {
+        let hiding = phase == "willHide" || phase == "didHide"
+        let height = Double(Int(cover(info, hiding: hiding).rounded()))
+        let duration = ((info[UIResponder.keyboardAnimationDurationUserInfoKey] as? NSNumber)?.doubleValue ?? 0) * 1000
+        // A floating iPad keyboard covers nothing: no show or hide for the page.
+        if !hiding && height == 0 { return }
+        let data = KeyboardTransition(height: height, duration: duration.rounded())
+        switch phase {
+        case "willShow": events.willShow(data)
+        case "didShow": events.didShow(data)
+        case "willHide": events.willHide(data)
+        default: events.didHide(data)
+        }
+    }
+
+    private var current: KeyboardState {
+        KeyboardState(visible: state.visible, height: Double(state.height))
+    }
+
+    func getState(_ reply: AkanNativeReply<KeyboardState>) {
+        reply.resolve(current)
+    }
+
+    func hide(_ reply: AkanNativeReply<Void>) {
+        // endEditing hides the keyboard but keeps DOM focus on the input (verified): blur too.
+        context.webView?.evaluateJavaScript("document.activeElement && document.activeElement.blur && document.activeElement.blur()")
+        context.webView?.endEditing(true)
+        reply.resolve()
+    }
+
+    func setResizeMode(_ args: KeyboardSetResizeModeArgs, _ reply: AkanNativeReply<Void>) {
+        (context.viewController as? AkanNativeViewController)?.keyboardResizes = args.mode == .resize
+        reply.resolve()
+    }
+}

package/vendor/@akanjs/native/plugins/keyboard/native-plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "keyboard",
+  "apiVersion": 1,
+  "methods": ["getState", "hide", "setResizeMode"],
+  "events": ["change", "willShow", "didShow", "willHide", "didHide"],
+  "coalesce": ["change"],
+  "codegen": true,
+  "web": "./src/web.ts",
+  "desktop": null,
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "KeyboardPlugin"
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.keyboard.KeyboardPlugin"
+  }
+}

package/vendor/@akanjs/native/plugins/keyboard/src/index.ts

@@ -0,0 +1,78 @@
+import { createLiveValue, definePlugin, shallowEqual } from "../../../packages/core/src/index.ts";
+import { useLiveValue } from "../../../packages/react/src/index.ts";
+import { web } from "./web.ts";
+
+/** Soft (on-screen) keyboard state. `height` is in CSS pixels and covers the bottom of the page. */
+export interface KeyboardState {
+  visible: boolean;
+  height: number;
+}
+
+/**
+ * What the keyboard does to the page (akanjs readiness O6-1):
+ * - "resize" (default, or the app config's keyboard.resize): the page's viewport shrinks by the keyboard, so bottom-fixed UI stays above it
+ *   (Android pads the WebView's container, iOS shortens the web view with the keyboard's animation).
+ * - "none": the page keeps its full size and the keyboard covers its bottom; the app moves its UI
+ *   itself with the heights of the events. iOS still scrolls a focused field into view.
+ */
+export type KeyboardResizeMode = "resize" | "none";
+
+/** A keyboard transition: its height in CSS pixels once it ends (0 when hiding) and its animation length in ms. */
+export interface KeyboardTransition {
+  height: number;
+  duration: number;
+}
+
+export interface KeyboardApi {
+  getState(): Promise<KeyboardState>;
+  /** Dismisses the soft keyboard. */
+  hide(): Promise<void>;
+  /** "resize" or "none"; until the app ends (not stored). The app config's keyboard.resize is the mode at launch. */
+  setResizeMode(args: { mode: KeyboardResizeMode }): Promise<void>;
+}
+
+export interface KeyboardEvents {
+  change: KeyboardState;
+  /** The keyboard starts to show (Android 11+ and iOS: before its animation; Android 10 and the web: together with didShow). */
+  willShow: KeyboardTransition;
+  didShow: KeyboardTransition;
+  willHide: KeyboardTransition;
+  didHide: KeyboardTransition;
+}
+
+export const keyboard = definePlugin<KeyboardApi, KeyboardEvents>("keyboard", {
+  methods: ["getState", "hide", "setResizeMode"],
+  events: ["change", "willShow", "didShow", "willHide", "didHide"],
+  web,
+});
+
+const hidden: KeyboardState = { visible: false, height: 0 };
+
+const current = createLiveValue<KeyboardState>(
+  hidden,
+  (set) => {
+    if (keyboard.eventImplementation("change") === "none") return;
+    let live = true;
+    const stop = keyboard.listen("change", set);
+    keyboard
+      .getState()
+      .then((state) => live && set(state))
+      .catch(() => {});
+    return () => {
+      live = false;
+      stop();
+    };
+  },
+  shallowEqual,
+);
+
+export interface UseKeyboard extends KeyboardState {
+  /** False where the platform has no soft keyboard support (desktop). */
+  supported: boolean;
+  hide(): Promise<void>;
+}
+
+export function useKeyboard(): UseKeyboard {
+  const state = useLiveValue(current);
+  return { ...state, supported: keyboard.isSupported("getState"), hide: keyboard.hide };
+}

package/vendor/@akanjs/native/plugins/keyboard/src/web.ts

@@ -0,0 +1,57 @@
+import { defineWebPlugin } from "../../../packages/core/src/index.ts";
+import type { KeyboardApi, KeyboardEvents, KeyboardState } from "./index.ts";
+
+const MIN_KEYBOARD_HEIGHT = 100;
+
+let last: KeyboardState = { visible: false, height: 0 };
+
+function read(): KeyboardState {
+  const vv = window.visualViewport;
+  if (!vv) return last;
+  
+  if (Math.abs(vv.scale - 1) > 0.01) return last;
+  const covered = Math.max(0, Math.round(window.innerHeight - vv.height));
+  last = covered >= MIN_KEYBOARD_HEIGHT ? { visible: true, height: covered } : { visible: false, height: 0 };
+  return last;
+}
+
+/** Calls `onChange(previous, next)` whenever the visual viewport shows another keyboard state. */
+function watch(onChange: (previous: KeyboardState, next: KeyboardState) => void): () => void {
+  const vv = window.visualViewport;
+  if (!vv) return () => {};
+  let previous = read();
+  const check = () => {
+    const next = read();
+    if (next.visible === previous.visible && next.height === previous.height) return;
+    const before = previous;
+    previous = next;
+    onChange(before, next);
+  };
+  vv.addEventListener("resize", check);
+  return () => vv.removeEventListener("resize", check);
+}
+
+/** Browsers tell when the keyboard has changed, not before: will and did come together. */
+const transition = (showing: boolean) => (emit: (t: { height: number; duration: number }) => void) =>
+  watch((previous, next) => {
+    if (next.visible === showing && previous.visible !== showing) emit({ height: next.height, duration: 0 });
+  });
+
+export const web = defineWebPlugin<KeyboardApi, KeyboardEvents>({
+  methods: {
+    getState: async () => read(),
+    async hide() {
+      const el = document.activeElement;
+      if (el instanceof HTMLElement) el.blur();
+    },
+    
+    async setResizeMode() {},
+  },
+  events: {
+    change: (emit) => watch((_, next) => emit(next)),
+    willShow: transition(true),
+    didShow: transition(true),
+    willHide: transition(false),
+    didHide: transition(false),
+  },
+});

package/vendor/@akanjs/native/plugins/local-notifications/android/LocalNotificationReceiver.kt

@@ -0,0 +1,38 @@
+package com.akanjs.plugins.localnotifications
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+
+/**
+ * Declared in the manifest (android.applicationXml, exported="false": only the system and this app
+ * reach it). It runs without the Activity, on the Context the system gives it:
+ * - FIRE: an alarm of LocalNotifications.arm went off
+ * - BOOT_COMPLETED: alarms do not survive a reboot (capacitor-plugins/local-notifications/android/
+ *   .../LocalNotificationRestoreReceiver.java). LOCKED_BOOT_COMPLETED is not used: the store is in
+ *   credential-encrypted storage, which is locked until the user unlocks (Capacitor listens for it
+ *   and then returns early when the user is locked, :16-17).
+ * - MY_PACKAGE_REPLACED: re-arm after an update, in case the alarms went with the old version
+ * - RESTORE: the plugin creates one reflectively and calls onReceive with it on every app start
+ *   (a force stop also clears alarms). That also keeps the constructor and onReceive in R8 release
+ *   builds, which do not read the manifest (packages/cli/src/platforms/android.ts PROGUARD).
+ */
+class LocalNotificationReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        try {
+            when (intent.action) {
+                LocalNotifications.ACTION_FIRE -> {
+                    val id = intent.getIntExtra(LocalNotifications.EXTRA_ID, Int.MIN_VALUE)
+                    if (id != Int.MIN_VALUE || intent.hasExtra(LocalNotifications.EXTRA_ID)) LocalNotifications.fire(context, id)
+                }
+                Intent.ACTION_BOOT_COMPLETED, Intent.ACTION_MY_PACKAGE_REPLACED, LocalNotifications.ACTION_RESTORE ->
+                    LocalNotifications.restore(context)
+            }
+        } catch (e: RuntimeException) {
+            Log.e(LocalNotifications.TAG, "local-notifications: ${intent.action} failed", e)
+        } catch (e: LinkageError) { // an API this Android lacks, reached without a version check
+            Log.e(LocalNotifications.TAG, "local-notifications: ${intent.action} needs a newer Android", e)
+        }
+    }
+}

package/vendor/@akanjs/native/plugins/local-notifications/android/LocalNotifications.kt

@@ -0,0 +1,284 @@
+package com.akanjs.plugins.localnotifications
+
+import android.app.ActivityManager
+import android.app.AlarmManager
+import android.app.Notification
+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 android.os.Bundle
+import android.util.Log
+import java.util.Calendar
+import org.json.JSONObject
+
+/**
+ * Scheduling shared by the plugin (Activity running) and the receiver (maybe no Activity at all:
+ * an alarm or a boot wakes only the process). Everything takes the Context it is given.
+ *
+ * - Scheduled items live in SharedPreferences, because alarms are gone after a reboot or a force
+ *   stop; the receiver re-arms them on BOOT_COMPLETED and the plugin on every app start
+ *   (capacitor-plugins/local-notifications/android/.../LocalNotificationRestoreReceiver.java:30-40).
+ *   The alarm intent carries only the id and the receiver reads the item from the store, instead of
+ *   a parceled Notification in the extras as Capacitor does (TimedNotificationPublisher.java:35):
+ *   one source of truth, and a cancelled item cannot fire from a stale intent.
+ * - Exact alarms only when canScheduleExactAlarms() (SCHEDULE_EXACT_ALARM is not requested, and is
+ *   denied by default for new installs targeting API 33+); otherwise setAndAllowWhileIdle
+ *   (LocalNotificationManager.java:374-396 falls back the same way). Its delivery window is 75% of
+ *   the lead time, capped at one hour (dumpsys alarm on the API 37 emulator): a reminder set 20 s
+ *   ahead came 15 s late, a minute repeat up to 45 s late.
+ * - Repeats are chains of one-shot alarms: each delivery arms the next occurrence, so they can be
+ *   exact, getPending knows the next time, and day/week keep the local time across DST. Capacitor
+ *   and Tauri use setRepeating(RTC, ...), which is always inexact (LocalNotificationManager.java:357).
+ * - Framework Notification.Builder (no NotificationCompat). The APK has no resources, so the small
+ *   icon is a framework drawable (ic_popup_reminder); Capacitor falls back to ic_dialog_info.
+ */
+internal object LocalNotifications {
+    const val TAG = "AkanNative"
+    const val DEFAULT_CHANNEL = "default"
+    const val ACTION_FIRE = "com.akanjs.plugins.localnotifications.FIRE"
+    const val ACTION_RESTORE = "com.akanjs.plugins.localnotifications.RESTORE"
+    const val EXTRA_ID = "akan-native.ln.id"
+    /** On the tap intent: the notification as JSON (the "action" event). */
+    const val EXTRA_TAP = "akan-native.ln.tap"
+    /**
+     * On the tap intent: a random token issued when the notification was posted and taken back by
+     * the tap. The launcher activity is exported, so any app can send it an intent with EXTRA_TAP;
+     * without a token on record that is no tap of ours. Single use: one tap is reported once.
+     */
+    const val EXTRA_TOKEN = "akan-native.ln.token"
+    private const val TOKENS = "akan-native.localNotifications.taps"
+    private const val MAX_TOKENS = 64
+    /** In the notification extras: marks our notifications and keeps their data. */
+    const val EXTRA_MARKER = "akan-native.ln"
+    const val EXTRA_DATA = "akan-native.ln.data"
+    private const val STORE = "akan-native.localNotifications"
+
+    data class Item(
+        val id: Int,
+        val title: String,
+        val body: String,
+        val at: Long,
+        val every: String?,
+        val channelId: String?,
+        /** JSON object text. */
+        val data: String?,
+    ) {
+        fun json(): JSONObject = JSONObject().put("id", id).put("title", title).put("body", body).put("at", at).apply {
+            if (every != null) put("every", every)
+            if (channelId != null) put("channelId", channelId)
+            if (data != null) put("data", JSONObject(data))
+        }
+
+        /** The "received" / "action" event. */
+        fun event(): JSONObject = JSONObject().put("id", id).put("title", title).put("body", body).apply {
+            if (data != null) put("data", JSONObject(data))
+        }
+
+        companion object {
+            fun from(json: JSONObject): Item = Item(
+                id = json.getInt("id"),
+                title = json.getString("title"),
+                body = json.optString("body", ""),
+                at = json.getLong("at"),
+                every = json.optString("every").ifEmpty { null },
+                channelId = json.optString("channelId").ifEmpty { null },
+                data = json.optJSONObject("data")?.toString(),
+            )
+        }
+    }
+
+    private fun store(context: Context) = context.getSharedPreferences(STORE, Context.MODE_PRIVATE)
+
+    fun pending(context: Context): List<Item> = store(context).all.values.mapNotNull { text ->
+        runCatching { Item.from(JSONObject(text as String)) }.getOrNull()
+    }.sortedBy { it.at }
+
+    private fun save(context: Context, item: Item) = store(context).edit().putString(item.id.toString(), item.json().toString()).apply()
+
+    private fun forget(context: Context, id: Int) = store(context).edit().remove(id.toString()).apply()
+
+    // ------------------------------------------------------------ schedule
+
+    fun schedule(context: Context, items: List<Item>) {
+        for (item in items) {
+            unarm(context, item.id)
+            if (item.every == null && item.at <= System.currentTimeMillis()) {
+                forget(context, item.id)
+                post(context, item)
+            } else {
+                save(context, item)
+                arm(context, item)
+            }
+        }
+    }
+
+    fun cancel(context: Context, ids: List<Int>) {
+        for (id in ids) {
+            unarm(context, id)
+            forget(context, id)
+        }
+    }
+
+    /** An alarm went off: show the item and arm its next occurrence. */
+    fun fire(context: Context, id: Int) {
+        val text = store(context).getString(id.toString(), null) ?: return // cancelled meanwhile
+        val item = runCatching { Item.from(JSONObject(text)) }.getOrNull() ?: return forget(context, id)
+        val now = System.currentTimeMillis()
+        if (item.at > now + 1000) return arm(context, item) // a stale alarm of an item scheduled again for later
+        post(context, item)
+        if (item.every == null) {
+            forget(context, id)
+        } else {
+            val next = item.copy(at = nextOccurrence(item.at, item.every, now))
+            save(context, next)
+            arm(context, next)
+        }
+    }
+
+    /**
+     * After a boot, a force stop or an update: arm everything again. One-shots that came due while
+     * the alarms were gone are shown now (Capacitor shows them 15 s after boot,
+     * LocalNotificationRestoreReceiver.java:33-38); missed repeats are skipped to the next occurrence.
+     */
+    fun restore(context: Context) {
+        val now = System.currentTimeMillis()
+        for (item in pending(context)) {
+            when {
+                item.every != null -> {
+                    val next = if (item.at > now) item else item.copy(at = nextOccurrence(item.at, item.every, now)).also { save(context, it) }
+                    arm(context, next)
+                }
+                item.at > now -> arm(context, item)
+                else -> {
+                    forget(context, item.id)
+                    post(context, item)
+                }
+            }
+        }
+    }
+
+    private fun alarmIntent(context: Context, id: Int, flags: Int): PendingIntent? =
+        PendingIntent.getBroadcast(
+            context,
+            id,
+            Intent(context, LocalNotificationReceiver::class.java).setAction(ACTION_FIRE).putExtra(EXTRA_ID, id),
+            flags or PendingIntent.FLAG_IMMUTABLE,
+        )
+
+    private fun arm(context: Context, item: Item) {
+        val alarms = context.getSystemService(AlarmManager::class.java) ?: return
+        val pi = alarmIntent(context, item.id, PendingIntent.FLAG_UPDATE_CURRENT) ?: return
+        try {
+            // Exact alarms need no permission before API 31 (Capacitor LocalNotificationManager.java:374-397).
+            if (Build.VERSION.SDK_INT < 31 || Api31.canScheduleExactAlarms(alarms)) {
+                alarms.setExactAndAllowWhileIdle(AlarmManager.RTC_WAKEUP, item.at, pi)
+                return
+            }
+        } catch (e: SecurityException) { // revoked between the check and the call
+            Log.w(TAG, "local-notifications: exact alarm refused, using an inexact one", e)
+        }
+        alarms.setAndAllowWhileIdle(AlarmManager.RTC_WAKEUP, item.at, pi)
+    }
+
+    private fun unarm(context: Context, id: Int) {
+        val pi = alarmIntent(context, id, PendingIntent.FLAG_NO_CREATE) ?: return
+        context.getSystemService(AlarmManager::class.java)?.cancel(pi)
+        pi.cancel()
+    }
+
+    /** Minute and hour are fixed lengths; day and week keep the local time of day (schedule.ts addInterval). */
+    fun nextOccurrence(at: Long, every: String, after: Long): Long {
+        if (at > after) return at
+        val fixed = when (every) {
+            "minute" -> 60_000L
+            "hour" -> 3_600_000L
+            else -> 0L
+        }
+        if (fixed > 0) return at + ((after - at) / fixed + 1) * fixed
+        val days = if (every == "week") 7 else 1
+        val start = Calendar.getInstance().apply { timeInMillis = at }
+        var k = maxOf(1L, (after - at) / (days * 86_400_000L)).toInt()
+        fun nth(n: Int): Long = (start.clone() as Calendar).apply { add(Calendar.DAY_OF_MONTH, n * days) }.timeInMillis
+        while (k > 1 && nth(k - 1) > after) k--
+        while (nth(k) <= after) k++
+        return nth(k)
+    }
+
+    // ------------------------------------------------------------ notifications
+
+    fun ensureDefaultChannel(manager: NotificationManager) {
+        if (manager.getNotificationChannel(DEFAULT_CHANNEL) != null) return
+        manager.createNotificationChannel(NotificationChannel(DEFAULT_CHANNEL, "Notifications", NotificationManager.IMPORTANCE_DEFAULT))
+    }
+
+    @Synchronized
+    private fun issueToken(context: Context): String {
+        val prefs = context.getSharedPreferences(TOKENS, Context.MODE_PRIVATE)
+        val token = java.util.UUID.randomUUID().toString()
+        // Oldest first ("<time> <token>"): the notifications behind old tokens are long gone.
+        val kept = (prefs.getStringSet("issued", emptySet()) ?: emptySet()).sorted().takeLast(MAX_TOKENS - 1)
+        prefs.edit().putStringSet("issued", (kept + "${System.currentTimeMillis()} $token").toSet()).apply()
+        return token
+    }
+
+    /** Whether [token] was issued for a notification and not taken yet; takes it. */
+    @Synchronized
+    fun redeemToken(context: Context, token: String): Boolean {
+        val prefs = context.getSharedPreferences(TOKENS, Context.MODE_PRIVATE)
+        val issued = prefs.getStringSet("issued", emptySet()) ?: emptySet()
+        val entry = issued.firstOrNull { it.substringAfter(' ') == token } ?: return false
+        prefs.edit().putStringSet("issued", issued - entry).commit()
+        return true
+    }
+
+    fun post(context: Context, item: Item) {
+        val manager = context.getSystemService(NotificationManager::class.java) ?: return
+        if (!manager.areNotificationsEnabled()) {
+            Log.w(TAG, "local-notifications: notifications are off, ${item.id} not shown")
+            return
+        }
+        // A channel deleted since scheduling would drop the notification silently.
+        val channel = item.channelId?.takeIf { manager.getNotificationChannel(it) != null } ?: DEFAULT_CHANNEL.also { ensureDefaultChannel(manager) }
+        val postedAt = System.currentTimeMillis()
+
+        // Tap: the launcher activity (launchMode singleTask, so a running app gets onNewIntent)
+        // with the event in the extras. Immutable: nothing needs to fill it in (Capacitor uses
+        // FLAG_MUTABLE only for RemoteInput actions).
+        val launch = context.packageManager.getLaunchIntentForPackage(context.packageName)
+        val tap = launch?.let {
+            it.putExtra(EXTRA_TAP, item.event().toString()).putExtra(EXTRA_TOKEN, issueToken(context))
+            PendingIntent.getActivity(context, item.id, it, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE)
+        }
+        val extras = Bundle().apply {
+            putBoolean(EXTRA_MARKER, true)
+            if (item.data != null) putString(EXTRA_DATA, item.data)
+        }
+        val notification = Notification.Builder(context, channel)
+            .setSmallIcon(android.R.drawable.ic_popup_reminder)
+            .setContentTitle(item.title)
+            .setContentText(item.body)
+            .setStyle(Notification.BigTextStyle().bigText(item.body))
+            .setCategory(Notification.CATEGORY_REMINDER)
+            .setAutoCancel(true)
+            .setWhen(postedAt)
+            .setShowWhen(true)
+            .addExtras(extras)
+            .apply { if (tap != null) setContentIntent(tap) }
+            .build()
+        manager.notify(item.id, notification)
+        LocalNotificationsPlugin.delivered(context, item)
+    }
+
+    fun isForeground(): Boolean {
+        val info = ActivityManager.RunningAppProcessInfo()
+        ActivityManager.getMyMemoryState(info)
+        return info.importance == ActivityManager.RunningAppProcessInfo.IMPORTANCE_FOREGROUND
+    }
+
+    private object Api31 {
+        fun canScheduleExactAlarms(alarms: AlarmManager): Boolean = alarms.canScheduleExactAlarms()
+    }
+}