react-native-alarms 0.0.6 → 0.0.8

package/README.md

@@ -1,6 +1,11 @@
 # React Native Alarms 🔔
 
-A powerful, cross-platform alarm management library for React Native. Schedule, manage, and control alarms on both Android and iOS with a unified API.
+A cross-platform native scheduling, reminder, and wake-up system for React Native. Schedule time-sensitive events on Android and iOS, deliver reminders, and present a registered custom React Native screen when a scheduled event fires—using one unified API.
+
+Although it can power a traditional alarm clock, react-native-alarms is also useful for exact-time reminders, scheduled check-ins, custom lock-screen experiences, and time-based app workflows. Build the experience around your own UI and event data instead of being limited to a standard alarm screen.
+
+> **Platform note:** The operating system controls background delivery and screen presentation. Exact timing, full-screen presentation, and behavior when an app is terminated depend on platform version, permissions, device settings, and the native scheduling mechanism. This library does not provide unrestricted background JavaScript execution.
+
 
 [![npm version](https://badge.fury.io/js/react-native-alarms.svg)](https://badge.fury.io/js/react-native-alarms)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -39,7 +44,7 @@ yarn add react-native-alarms
 
 ### Native Module Linking
 
-Since this is a native module, you'll need to link it:
+For a bare React Native app, install the iOS pods and rebuild:
 
 ```bash
 cd ios && pod install && cd ..
@@ -49,11 +54,32 @@ For Android, the native code auto-links, including the permissions, ring activit
 service and receivers in its manifest. No `MainApplication` or `AndroidManifest.xml`
 changes are needed. Rebuild the app after installing.
 
+### Expo
+
+The library works with Expo projects that generate and build native projects
+(prebuild, EAS Build, or a development build). It uses React Native autolinking and
+does not require an Expo config plugin:
+
+```bash
+npm install react-native-alarms
+npx expo prebuild
+npx expo run:android
+# or
+npx expo run:ios
+```
+
+Rebuild the native app after installing or upgrading the library. **Expo Go is not
+supported** because it cannot load this library's native alarm module. Existing bare
+React Native installation and setup remain unchanged.
+Register the `AlarmRing` component in your app's JavaScript entry point as described
+below; Expo Router apps should do this from a custom entry point before loading
+`expo-router/entry`.
+
 ### Register the ring screen
 
 When an alarm rings, both platforms show a full-screen React component registered as
 `AlarmRing`, with the alarm (`alarmId`, `title`, `body`, `snoozeEnabled`,
-`snoozeMinutes`, `data`) as props. Register your own component in `index.js`:
+`snoozeMinutes`, `data`, and optional `image`) as props. Register your own component in `index.js`:
 
 ```js
 import { AppRegistry } from 'react-native';
@@ -65,6 +91,44 @@ AppRegistry.registerComponent('AlarmRing', () => AlarmRingScreen);
 Call `Alarm.stopAlarm(alarmId)` or `Alarm.snoozeAlarm(alarmId, minutes)` from its
 buttons; the screen closes itself.
 
+#### Custom presentation component
+
+You can register **multiple** ring screens and choose which one fires per alarm using the `presentation` field in `AlarmConfig`:
+
+```js
+// index.js
+import { AppRegistry } from 'react-native';
+import { AlarmRingScreen } from './src/AlarmRingScreen';
+import { ReminderScreen } from './src/ReminderScreen';
+
+AppRegistry.registerComponent('AlarmRing', () => AlarmRingScreen);   // default
+AppRegistry.registerComponent('Reminder', () => ReminderScreen);     // custom
+```
+
+```ts
+import { AlarmRegistry, AlarmService } from 'react-native-alarms/service';
+
+// 1. Map your key to the registered component name
+AlarmRegistry.register('reminder', 'Reminder');
+
+// 2. Pass it when scheduling
+await AlarmService.scheduleAlarm({
+  timestamp: Date.now() + 60_000,
+  title: 'Standup',
+  presentation: {
+    type: 'reminder',           // resolves to the 'Reminder' component
+    props: { color: '#6200EE' } // forwarded to the screen as componentProps
+  },
+});
+```
+
+The native layer maps `presentation` to two internal fields:
+
+| Internal field | Type | Default | Description |
+|---|---|---|---|
+| `componentName` | `string` | `"AlarmRing"` | Registered `AppRegistry` component name shown when the alarm rings. |
+| `componentProps` / `componentPropsJSON` | `object` / `string` | `{}` | Key-value props forwarded to the ring screen on **both platforms**. On Android they arrive as top-level bundle extras and a nested `componentProps` map; on iOS as a parsed `[String: Any]` dictionary. |
+
 ### Direct module access
 
 ```ts
@@ -173,15 +237,53 @@ type AlarmConfig = {
   timestamp: number;          // Time in milliseconds (Date.now() format)
   title: string;              // Alarm title/label
   body?: string;              // Alarm description
+  image?: string;             // file:// or https:// image URI for ring screen/notifications
   sound?: string;             // 'default' or custom sound file name
   vibrate?: boolean;          // Enable vibration (Android only)
   snoozeEnabled?: boolean;    // Allow snoozing
   snoozeMinutes?: number;     // Snooze duration in minutes
   repeat?: AlarmRepeat;       // Repeat configuration
   data?: string;              // Custom JSON string payload
+  presentation?: AlarmPresentation; // Custom ring screen & props
+};
+
+type AlarmPresentation = {
+  /** Registered presentation type (key passed to AlarmRegistry.register). */
+  type?: string;
+  /**
+   * Props forwarded to the ring screen component.
+   * Available as `componentProps` on both Android and iOS.
+   */
+  props?: Record<string, unknown>;
 };
 ```
 
+Pass a URI string for `image`; for example:
+
+```ts
+await AlarmService.scheduleAlarm({
+  timestamp: Date.now() + 60_000,
+  title: 'Appointment',
+  image: 'https://example.com/appointment.jpg',
+});
+```
+
+When provided, `image` is returned with queried alarms and alarm events, passed to
+the registered ring screen as an initial prop, and used for the native notification
+image where supported. Android accepts `https://`, `file://`, and `content://` URIs.
+iOS notification attachments accept `https://` and `file://` URIs; the iOS 26+
+AlarmKit system alert itself does not display custom images, but the image URI is
+available to the React Native ring screen when it opens. Render it in that screen
+with React Native's `Image` component and `source={{ uri: image }}`.
+
+> **How the native layer stores these:** `AlarmConfig.presentation` is resolved by `AlarmService` before being handed off to the native module. The resulting fields stored in the native `AlarmData` model are:
+>
+> | Field | Type | Default | Description |
+> |---|---|---|---|
+> | `componentName` | `string` | `"AlarmRing"` | The `AppRegistry` name of the component shown at ring time. Derived from `AlarmRegistry.resolve(presentation.type)`. |
+> | `componentProps` | `object` | `{}` | Parsed props object (from `presentation.props`). Available on both platforms at ring time as `componentProps`. |
+> | `componentPropsJSON` | `string` | `"{}"` | JSON-serialised representation of `componentProps`, persisted alongside the alarm so props survive a device reboot. |
+
 #### `AlarmRepeat`
 Repeat configuration for recurring alarms.
 
@@ -202,6 +304,7 @@ type Alarm = {
   timestamp: number;
   title: string;
   body: string;
+  image?: string;
   sound: string;
   vibrate: boolean;
   snoozeEnabled: boolean;
@@ -433,27 +536,99 @@ For issues and questions, please visit:
 
 The library supports completely custom alarm UI screens with custom data payloads.
 
-### Basic Custom Screen Example
+### Using `componentName` and `componentProps`
+
+The `presentation` field lets you choose **which registered component** is displayed and pass **arbitrary props** directly to it — without encoding everything inside a JSON `data` string.
+
+#### 1. Register your screens
+
+```js
+// index.js
+import { AppRegistry } from 'react-native';
+import { AlarmRingScreen }   from './src/AlarmRingScreen';
+import { MeetingAlarmScreen } from './src/MeetingAlarmScreen';
+
+AppRegistry.registerComponent('AlarmRing',    () => AlarmRingScreen);    // default fallback
+AppRegistry.registerComponent('MeetingAlarm', () => MeetingAlarmScreen); // custom
+```
+
+#### 2. Map a key to the component name
+
+```ts
+import { AlarmRegistry } from 'react-native-alarms';
+
+AlarmRegistry.register('meeting', 'MeetingAlarm');
+```
+
+#### 3. Schedule with `presentation`
 
 ```typescript
-import { NativeModules } from 'react-native';
 import { AlarmService } from 'react-native-alarms/service';
 
-export function MyCustomAlarmScreen({ alarmId, title, data }) {
-  const customData = JSON.parse(data || '{}');
+await AlarmService.scheduleAlarm({
+  timestamp: Date.now() + 5 * 60 * 1000,
+  title: 'Team standup',
+  presentation: {
+    type: 'meeting',                    // resolves to 'MeetingAlarm'
+    props: {
+      roomName: 'Zoom Room A',
+      meetingUrl: 'https://zoom.us/j/123',
+      accentColor: '#6200EE',
+    },
+  },
+});
+```
+
+#### 4. Receive `componentProps` in your screen
+
+The props passed via `presentation.props` are forwarded to the ring screen on both platforms:
+
+```typescript
+// MeetingAlarmScreen.tsx
+type Props = {
+  alarmId: string;
+  title: string;
+  snoozeEnabled: boolean;
+  snoozeMinutes: number;
+  data?: string;
+  // componentProps fields arrive as top-level props:
+  roomName?: string;
+  meetingUrl?: string;
+  accentColor?: string;
+};
 
+export function MeetingAlarmScreen({
+  alarmId,
+  title,
+  snoozeEnabled,
+  snoozeMinutes,
+  roomName,
+  meetingUrl,
+  accentColor = '#007AFF',
+}: Props) {
   return (
-    <View style={{ backgroundColor: customData.color }}>
-      <Text>{title}</Text>
+    <View style={{ flex: 1, backgroundColor: accentColor }}>
+      <Text style={{ fontSize: 28, color: '#fff' }}>{title}</Text>
+      <Text style={{ color: '#fff' }}>{roomName}</Text>
+
+      {snoozeEnabled && (
+        <TouchableOpacity onPress={() => AlarmService.snoozeAlarm(alarmId, snoozeMinutes)}>
+          <Text>Snooze {snoozeMinutes} min</Text>
+        </TouchableOpacity>
+      )}
       <TouchableOpacity onPress={() => AlarmService.stopAlarm(alarmId)}>
-        <Text>Stop</Text>
+        <Text>Dismiss</Text>
       </TouchableOpacity>
     </View>
   );
 }
 ```
 
-### Passing Custom Data
+> **Platform behaviour**
+> - **Android**: `componentProps` entries are flattened into the launch `Bundle` alongside standard fields (`alarmId`, `title`, etc.), and also available as a nested `componentProps` bundle. The `AlarmRingActivity` uses `componentName` to resolve which registered React root to display.
+> - **iOS**: `componentProps` (parsed from `componentPropsJSON`) is merged into the surface's initial properties passed to the React component.
+
+### Passing Custom Data (legacy approach)
 
 ```typescript
 await AlarmService.scheduleAlarm({
@@ -468,4 +643,3 @@ await AlarmService.scheduleAlarm({
 ```
 
 **Full Guide:** See [CUSTOM_UI_GUIDE.md](./CUSTOM_UI_GUIDE.md) for complete examples and best practices.
-

package/android/app/src/main/java/com/reactnativealarm/alarm/AlarmData.kt

@@ -3,6 +3,7 @@ package com.alarm
 import android.os.Bundle
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableArray
 import com.facebook.react.bridge.WritableMap
 import org.json.JSONArray
 import org.json.JSONObject
@@ -13,6 +14,7 @@ data class AlarmData(
   val timestamp: Long,
   val title: String,
   val body: String,
+  val image: String,
   val sound: String,
   val vibrate: Boolean,
   val snoozeEnabled: Boolean,
@@ -21,8 +23,29 @@ data class AlarmData(
   val weekdays: List<Int>,
   val intervalMs: Long,
   val data: String,
-  var enabled: Boolean = true
+  var enabled: Boolean = true,
+  val componentName: String = "AlarmRing",
+  val componentPropsJSON: String = "{}"
 ) {
+  val componentProps: Map<String, Any>
+    get() {
+      return try {
+        val obj = JSONObject(componentPropsJSON)
+        val map = mutableMapOf<String, Any>()
+        val keys = obj.keys()
+        while (keys.hasNext()) {
+          val key = keys.next()
+          val value = obj.get(key)
+          if (value != JSONObject.NULL) {
+            map[key] = value
+          }
+        }
+        map
+      } catch (_: Exception) {
+        emptyMap()
+      }
+    }
+
   fun nextTrigger(from: Long = System.currentTimeMillis()): Long {
     if (!enabled) return 0
     return when (repeatType) {
@@ -55,10 +78,13 @@ data class AlarmData(
 
   fun toJson(): String = JSONObject().apply {
     put("id", id); put("timestamp", timestamp); put("title", title); put("body", body)
+    put("image", image)
     put("sound", sound); put("vibrate", vibrate); put("snoozeEnabled", snoozeEnabled)
     put("snoozeMinutes", snoozeMinutes); put("repeatType", repeatType)
     put("weekdays", JSONArray(weekdays)); put("intervalMs", intervalMs)
     put("data", data); put("enabled", enabled)
+    put("componentName", componentName)
+    put("componentPropsJSON", componentPropsJSON)
   }.toString()
 
   fun toWritableMap(): WritableMap = Arguments.createMap().apply {
@@ -66,6 +92,7 @@ data class AlarmData(
     putDouble("timestamp", timestamp.toDouble())
     putString("title", title)
     putString("body", body)
+    putString("image", image)
     putString("sound", sound)
     putBoolean("vibrate", vibrate)
     putBoolean("snoozeEnabled", snoozeEnabled)
@@ -78,6 +105,13 @@ data class AlarmData(
     putString("data", data)
     putBoolean("enabled", enabled)
     putDouble("nextTriggerAt", nextTrigger().toDouble())
+    putString("componentName", componentName)
+    putString("componentPropsJSON", componentPropsJSON)
+    try {
+      putMap("componentProps", jsonToWritableMap(JSONObject(componentPropsJSON)))
+    } catch (_: Exception) {
+      putMap("componentProps", Arguments.createMap())
+    }
   }
 
   /** Initial props for the React ring screen hosted by [AlarmRingActivity]. */
@@ -86,22 +120,75 @@ data class AlarmData(
     putDouble("timestamp", timestamp.toDouble())
     putString("title", title)
     putString("body", body)
+    putString("image", image)
     putBoolean("snoozeEnabled", snoozeEnabled)
     putInt("snoozeMinutes", snoozeMinutes)
     putString("data", data)
+    putString("componentName", componentName)
+    putString("componentPropsJSON", componentPropsJSON)
+    try {
+      val propsObj = JSONObject(componentPropsJSON)
+      val propsBundle = jsonToBundle(propsObj)
+      putBundle("componentProps", propsBundle)
+      for (key in propsBundle.keySet()) {
+        if (!containsKey(key)) {
+          val v = propsBundle.get(key)
+          when (v) {
+            is String -> putString(key, v)
+            is Boolean -> putBoolean(key, v)
+            is Int -> putInt(key, v)
+            is Long -> putLong(key, v)
+            is Double -> putDouble(key, v)
+            is Bundle -> putBundle(key, v)
+          }
+        }
+      }
+    } catch (_: Exception) {}
+  }
+
+  private fun jsonToBundle(jsonObject: JSONObject): Bundle {
+    val bundle = Bundle()
+    val iter = jsonObject.keys()
+    while (iter.hasNext()) {
+      val key = iter.next()
+      when (val value = jsonObject.opt(key)) {
+        is JSONObject -> bundle.putBundle(key, jsonToBundle(value))
+        is JSONArray -> bundle.putString(key, value.toString())
+        is Boolean -> bundle.putBoolean(key, value)
+        is Int -> bundle.putInt(key, value)
+        is Long -> bundle.putLong(key, value)
+        is Double -> bundle.putDouble(key, value)
+        is String -> bundle.putString(key, value)
+        else -> if (value != null && value != JSONObject.NULL) {
+          bundle.putString(key, value.toString())
+        }
+      }
+    }
+    return bundle
   }
 
   companion object {
     fun fromJson(s: String): AlarmData {
       val o = JSONObject(s)
       val wd = o.optJSONArray("weekdays")
+      val compName = o.optString("componentName", "AlarmRing").trim()
       return AlarmData(
-        o.getString("id"), o.getLong("timestamp"), o.optString("title"), o.optString("body"),
-        o.optString("sound", "default"), o.optBoolean("vibrate", true),
-        o.optBoolean("snoozeEnabled", true), o.optInt("snoozeMinutes", 5),
-        o.optString("repeatType", "none"),
-        if (wd == null) emptyList() else (0 until wd.length()).map { wd.getInt(it) },
-        o.optLong("intervalMs", 0), o.optString("data"), o.optBoolean("enabled", true)
+        id = o.getString("id"),
+        timestamp = o.getLong("timestamp"),
+        title = o.optString("title"),
+        body = o.optString("body"),
+        image = o.optString("image"),
+        sound = o.optString("sound", "default"),
+        vibrate = o.optBoolean("vibrate", true),
+        snoozeEnabled = o.optBoolean("snoozeEnabled", true),
+        snoozeMinutes = o.optInt("snoozeMinutes", 5),
+        repeatType = o.optString("repeatType", "none"),
+        weekdays = if (wd == null) emptyList() else (0 until wd.length()).map { wd.getInt(it) },
+        intervalMs = o.optLong("intervalMs", 0),
+        data = o.optString("data"),
+        enabled = o.optBoolean("enabled", true),
+        componentName = if (compName.isEmpty()) "AlarmRing" else compName,
+        componentPropsJSON = o.optString("componentPropsJSON", "{}").ifBlank { "{}" }
       )
     }
 
@@ -109,11 +196,30 @@ data class AlarmData(
       val r = if (m.hasKey("repeat") && !m.isNull("repeat")) m.getMap("repeat") else null
       val wd = r?.takeIf { it.hasKey("weekdays") }?.getArray("weekdays")
         ?.let { a -> (0 until a.size()).map { a.getInt(it) } } ?: emptyList()
+
+      val componentPropsStr = when {
+        m.hasKey("componentPropsJSON") && !m.isNull("componentPropsJSON") ->
+          m.getString("componentPropsJSON") ?: "{}"
+        m.hasKey("componentProps") && !m.isNull("componentProps") -> {
+          val propsMap = m.getMap("componentProps")
+          try {
+            val hashMap = propsMap?.toHashMap() ?: emptyMap<String, Any>()
+            JSONObject(hashMap).toString()
+          } catch (_: Exception) {
+            "{}"
+          }
+        }
+        else -> "{}"
+      }
+
+      val compName = m.str("componentName", "AlarmRing").trim()
+
       return AlarmData(
         id = id,
         timestamp = m.getDouble("timestamp").toLong(),
         title = m.str("title"),
         body = m.str("body"),
+        image = m.str("image"),
         sound = m.str("sound", "default"),
         vibrate = m.bool("vibrate", true),
         snoozeEnabled = m.bool("snoozeEnabled", true),
@@ -121,10 +227,56 @@ data class AlarmData(
         repeatType = r?.str("type", "none") ?: "none",
         weekdays = wd,
         intervalMs = if (r != null && r.hasKey("intervalMs")) r.getDouble("intervalMs").toLong() else 0,
-        data = m.str("data")
+        data = m.str("data"),
+        componentName = if (compName.isEmpty()) "AlarmRing" else compName,
+        componentPropsJSON = componentPropsStr
       )
     }
 
+    private fun jsonToWritableMap(jsonObject: JSONObject): WritableMap {
+      val map = Arguments.createMap()
+      val iter = jsonObject.keys()
+      while (iter.hasNext()) {
+        val key = iter.next()
+        when (val value = jsonObject.opt(key)) {
+          is JSONObject -> map.putMap(key, jsonToWritableMap(value))
+          is JSONArray -> map.putArray(key, jsonToWritableArray(value))
+          is Boolean -> map.putBoolean(key, value)
+          is Int -> map.putInt(key, value)
+          is Long -> map.putDouble(key, value.toDouble())
+          is Double -> map.putDouble(key, value)
+          is String -> map.putString(key, value)
+          else -> if (value == null || value == JSONObject.NULL) {
+            map.putNull(key)
+          } else {
+            map.putString(key, value.toString())
+          }
+        }
+      }
+      return map
+    }
+
+    private fun jsonToWritableArray(jsonArray: JSONArray): WritableArray {
+      val array = Arguments.createArray()
+      for (i in 0 until jsonArray.length()) {
+        when (val value = jsonArray.opt(i)) {
+          is JSONObject -> array.pushMap(jsonToWritableMap(value))
+          is JSONArray -> array.pushArray(jsonToWritableArray(value))
+          is Boolean -> array.pushBoolean(value)
+          is Int -> array.pushInt(value)
+          is Long -> array.pushDouble(value.toDouble())
+          is Double -> array.pushDouble(value)
+          is String -> array.pushString(value)
+          else -> if (value == null || value == JSONObject.NULL) {
+            array.pushNull()
+          } else {
+            array.pushString(value.toString())
+          }
+        }
+      }
+      return array
+    }
+
     private fun ReadableMap.str(k: String, d: String = "") =
       if (hasKey(k) && !isNull(k)) getString(k) ?: d else d
 

package/android/app/src/main/java/com/reactnativealarm/alarm/AlarmModule.kt

@@ -31,14 +31,14 @@ class AlarmModule(private val ctx: ReactApplicationContext) : ReactContextBaseJa
   private fun notificationsGranted(): Boolean =
     if (Build.VERSION.SDK_INT >= 33)
       ContextCompat.checkSelfPermission(ctx, Manifest.permission.POST_NOTIFICATIONS) ==
-        PackageManager.PERMISSION_GRANTED
+              PackageManager.PERMISSION_GRANTED
     else NotificationManagerCompat.from(ctx).areNotificationsEnabled()
 
   private fun canDrawOverlays(): Boolean = Settings.canDrawOverlays(ctx)
 
   private fun canUseFullScreenIntent(): Boolean =
     Build.VERSION.SDK_INT < 34 ||
-      ctx.getSystemService(NotificationManager::class.java).canUseFullScreenIntent()
+            ctx.getSystemService(NotificationManager::class.java).canUseFullScreenIntent()
 
   private fun permissionMap(): WritableMap = Arguments.createMap().apply {
     val ok = notificationsGranted()
@@ -241,6 +241,7 @@ class AlarmModule(private val ctx: ReactApplicationContext) : ReactContextBaseJa
       putDouble("timestamp", System.currentTimeMillis().toDouble())
       putString("title", a.title)
       putString("body", a.body)
+      putString("image", a.image)
       putString("data", a.data)
     }
     ctx.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java).emit(eventName, map)

package/android/app/src/main/java/com/reactnativealarm/alarm/AlarmRingActivity.kt

@@ -18,7 +18,8 @@ import java.lang.ref.WeakReference
  */
 class AlarmRingActivity : ReactActivity() {
 
-  override fun getMainComponentName(): String = COMPONENT_NAME
+  override fun getMainComponentName(): String =
+    AlarmService.current?.componentName?.takeIf { it.isNotBlank() } ?: COMPONENT_NAME
 
   override fun createReactActivityDelegate(): ReactActivityDelegate =
     object : DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled) {
@@ -45,7 +46,7 @@ class AlarmRingActivity : ReactActivity() {
       @Suppress("DEPRECATION")
       window.addFlags(
         WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED or
-          WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON
+                WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON
       )
     }
     window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)

package/android/app/src/main/java/com/reactnativealarm/alarm/AlarmService.kt

@@ -8,6 +8,8 @@ import android.app.Service
 import android.content.Context
 import android.content.Intent
 import android.content.pm.ServiceInfo
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
 import android.media.AudioAttributes
 import android.media.MediaPlayer
 import android.media.RingtoneManager
@@ -22,6 +24,9 @@ import android.os.Vibrator
 import android.util.Log
 import androidx.core.app.NotificationCompat
 import androidx.core.app.ServiceCompat
+import java.io.InputStream
+import java.net.URL
+import java.util.concurrent.Executors
 
 /**
  * Foreground service that actually rings: looping sound, vibration, a partial wake
@@ -39,6 +44,7 @@ class AlarmService : Service() {
   private var player: MediaPlayer? = null
   private var vibrator: Vibrator? = null
   private var wakeLock: PowerManager.WakeLock? = null
+  private val imageExecutor = Executors.newSingleThreadExecutor()
 
   override fun onBind(intent: Intent?): IBinder? = null
 
@@ -70,6 +76,7 @@ class AlarmService : Service() {
     Log.i(TAG, "Ringing alarm ${alarm.id}")
 
     startInForeground(buildNotification(alarm))
+    loadNotificationImage(alarm)
     acquireWakeLock()
     startSound(alarm)
     if (alarm.vibrate) startVibration()
@@ -139,6 +146,7 @@ class AlarmService : Service() {
 
   override fun onDestroy() {
     stopRinging()
+    imageExecutor.shutdownNow()
     super.onDestroy()
   }
 
@@ -217,7 +225,7 @@ class AlarmService : Service() {
       .build()
   }
 
-  private fun buildNotification(alarm: AlarmData): Notification {
+  private fun buildNotification(alarm: AlarmData, image: Bitmap? = null): Notification {
     ensureChannel()
     val ringIntent = Intent(this, AlarmRingActivity::class.java)
       .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
@@ -235,12 +243,58 @@ class AlarmService : Service() {
       .setFullScreenIntent(fullScreen, true)
       .setContentIntent(fullScreen)
       .addAction(0, "Stop", commandPI(ACTION_DISMISS, 2))
+    if (image != null) {
+      b.setStyle(
+        NotificationCompat.BigPictureStyle()
+          .bigPicture(image)
+          .setBigContentTitle(alarm.title.ifBlank { "Alarm" })
+          .setSummaryText(alarm.body.ifBlank { "Alarm is ringing" })
+      )
+    }
     if (alarm.snoozeEnabled) {
       b.addAction(0, "Snooze", commandPI(ACTION_SNOOZE, 3))
     }
     return b.build()
   }
 
+  private fun loadNotificationImage(alarm: AlarmData) {
+    if (alarm.image.isBlank()) return
+    imageExecutor.execute {
+      try {
+        val bitmap = decodeImage(Uri.parse(alarm.image)) ?: return@execute
+        handler.post {
+          if (current?.id == alarm.id) {
+            ensureChannel().notify(NOTIFICATION_ID, buildNotification(alarm, bitmap))
+          }
+        }
+      } catch (e: Exception) {
+        Log.w(TAG, "Could not load notification image for alarm ${alarm.id}", e)
+      }
+    }
+  }
+
+  private fun decodeImage(uri: Uri): Bitmap? {
+    fun openStream(): InputStream? = when (uri.scheme?.lowercase()) {
+      "https" -> URL(uri.toString()).openConnection().apply {
+        connectTimeout = 5_000
+        readTimeout = 5_000
+      }.getInputStream()
+      "file", "content", "android.resource" -> contentResolver.openInputStream(uri)
+      else -> throw IllegalArgumentException("Unsupported alarm image URI: $uri")
+    }
+
+    val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+    openStream()?.use { BitmapFactory.decodeStream(it, null, bounds) }
+    if (bounds.outWidth <= 0 || bounds.outHeight <= 0) return null
+
+    var sampleSize = 1
+    while (bounds.outWidth / sampleSize > 1024 || bounds.outHeight / sampleSize > 1024) {
+      sampleSize *= 2
+    }
+    val options = BitmapFactory.Options().apply { inSampleSize = sampleSize }
+    return openStream()?.use { BitmapFactory.decodeStream(it, null, options) }
+  }
+
   private fun commandPI(action: String, code: Int): PendingIntent =
     PendingIntent.getService(
       this, code, Intent(this, AlarmService::class.java).setAction(action),