react-native-alarms 0.0.4 → 0.0.6

package/.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit $1

package/AGENTS.md

@@ -0,0 +1,291 @@
+# AGENTS.md
+
+## Project Overview
+
+`react-native-alarms` is a React Native library designed to provide reliable alarm functionality across Android and iOS.
+
+The library may include JavaScript/TypeScript APIs, native Android and iOS implementations, alarm scheduling, notifications, event handling, and custom alarm interfaces.
+
+The primary goals are:
+
+- Reliability across supported platforms and operating-system versions.
+- Predictable alarm scheduling, cancellation, and lifecycle behavior.
+- Efficient resource and battery usage.
+- A consistent developer experience for React Native applications.
+- Backward compatibility and maintainable native code.
+
+**Important:** Treat the existing implementation and documented behavior as the source of truth. Do not assume that a feature is supported on both platforms until you have verified the implementation.
+
+## Instructions for AI Coding Agents
+
+Before making changes:
+
+1. Inspect the repository structure and `package.json`.
+2. Read `README.md`, `CONTRIBUTING.md`, and relevant documentation.
+3. Inspect the existing implementation before proposing a replacement.
+4. Identify whether the requested change affects JavaScript/TypeScript, Android, iOS, or multiple layers.
+5. Review related tests, configuration files, and existing patches.
+6. Understand the expected behavior and platform-specific constraints before editing code.
+
+Do not make broad or unrelated changes when a focused fix is sufficient.
+
+### General Rules
+
+- Preserve existing project conventions and architecture.
+- Keep changes small, focused, and easy to review.
+- Prefer existing dependencies and utilities over introducing new ones.
+- Avoid unnecessary public API changes.
+- Preserve TypeScript type safety.
+- Handle errors and edge cases explicitly.
+- Do not silently swallow errors.
+- Do not modify generated files unless required by the project's build process.
+- Never commit secrets, credentials, signing keys, or local environment files.
+- Do not claim a test, build, or device scenario passed unless it was actually verified.
+- Clearly identify any behavior that remains untested.
+
+## Repository Exploration
+
+Before changing files, inspect the available project scripts and directory layout.
+
+Useful commands:
+
+```bash
+cat package.json
+find . -maxdepth 3 -type f | sort
+git status --short
+```
+
+Review the repository's actual structure rather than assuming specific directories, frameworks, or build commands exist.
+
+Do not overwrite user changes or discard uncommitted work.
+
+## JavaScript and TypeScript Guidelines
+
+- Follow the existing formatting and naming conventions.
+- Use explicit types for public APIs and event payloads.
+- Keep platform-independent business logic separate from native implementation details.
+- Validate inputs before invoking native modules.
+- Maintain consistent error handling.
+- Clean up event subscriptions and listeners when no longer required.
+- Avoid memory leaks, duplicated listeners, and unnecessary re-renders.
+- Document public methods, configuration options, and callbacks.
+
+### Public API Compatibility
+
+Before changing an exported method, event, property, or type:
+
+1. Search for all usages in the repository.
+2. Review the documented public API.
+3. Check whether existing consumers could be affected.
+4. Add or update tests.
+5. Document any breaking changes and migration steps.
+
+Do not rename or remove public exports without a clear requirement.
+
+## Android Development Guidelines
+
+When modifying Android native code:
+
+- Follow the existing Java or Kotlin conventions used by the project.
+- Respect Android application and activity lifecycle requirements.
+- Check the minimum SDK and supported Android versions before using APIs.
+- Handle notification and exact-alarm permissions where applicable.
+- Respect Android background-execution and battery-management restrictions.
+- Avoid unnecessary wake locks and background resource consumption.
+- Ensure pending intents and alarm identifiers behave predictably.
+- Handle cancellation, rescheduling, and duplicate requests correctly.
+- Clean up receivers, callbacks, and other resources when appropriate.
+- Follow applicable Android security and platform policies.
+
+### Android Alarm Behavior
+
+When modifying alarm scheduling or delivery, consider:
+
+- Scheduling and cancellation.
+- Repeated alarms.
+- Device reboot behavior, if supported.
+- Application foreground and background states.
+- Process termination.
+- Notification delivery.
+- Full-screen intent restrictions and permissions.
+- Doze mode and battery optimization.
+- Android version and manufacturer differences.
+
+Do not promise guaranteed delivery under every system condition. Verify the actual implementation and account for platform restrictions.
+
+## iOS Development Guidelines
+
+When modifying iOS native code:
+
+- Follow the existing Swift or Objective-C conventions.
+- Respect UIKit and application lifecycle requirements.
+- Use the deployment target defined by the project.
+- Handle notification authorization and scheduling correctly.
+- Manage observers, callbacks, timers, and native resources safely.
+- Avoid retain cycles and resource leaks.
+- Handle app foreground and background transitions.
+- Preserve compatibility with supported iOS versions.
+- Respect system restrictions on background execution and alarm-like behavior.
+
+### iOS Alarm Behavior
+
+When working on alarm functionality, consider:
+
+- Alarm scheduling and cancellation.
+- Notification authorization.
+- Application lifecycle transitions.
+- Audio session configuration, where applicable.
+- Repeated alarms and rescheduling.
+- Device restart behavior, where supported.
+- System-managed alarm capabilities, where available.
+- Custom alarm interfaces and their presentation constraints.
+
+Do not assume an application can execute arbitrary code or present a custom interface while suspended or terminated. Verify platform capabilities and use supported APIs.
+
+## Cross-Platform Behavior
+
+Android and iOS do not provide identical capabilities.
+
+When implementing a cross-platform feature:
+
+1. Define the expected public API.
+2. Identify platform-specific behavior.
+3. Implement each platform using its supported mechanisms.
+4. Return consistent results where practical.
+5. Document differences and limitations.
+6. Test both platforms when the change affects shared behavior.
+
+Never simulate unsupported operating-system guarantees through misleading documentation or API responses.
+
+## Event and Lifecycle Management
+
+For alarm-related events and callbacks:
+
+- Preserve the documented event names and payload structure.
+- Avoid firing the same event multiple times for one logical transition.
+- Ensure cancellation and dismissal are handled consistently.
+- Clean up native and JavaScript listeners appropriately.
+- Avoid race conditions between scheduling, firing, dismissal, and snoozing.
+- Ensure callbacks do not unintentionally retain obsolete objects.
+- Consider repeated initialization and application lifecycle transitions.
+
+Test event sequences, not just individual callbacks.
+
+## Dependencies and Configuration
+
+Before adding or upgrading dependencies:
+
+- Verify React Native compatibility.
+- Review peer dependencies.
+- Check Android and iOS requirements.
+- Consider bundle size and runtime overhead.
+- Avoid unnecessary native dependencies.
+- Update lockfiles when required by the project's package manager.
+- Document any additional setup steps.
+
+Do not change the package manager or lockfile format without a clear reason.
+
+## Testing Requirements
+
+Inspect `package.json` and existing project configuration to determine which checks are available.
+
+Run the applicable checks before completing a change, such as:
+
+- Linting.
+- Type checking.
+- Unit tests.
+- Example application builds.
+- Android native compilation.
+- iOS native compilation.
+- Manual device or emulator tests.
+
+Do not invent npm scripts or assume a test framework is installed.
+
+### Alarm-Specific Test Scenarios
+
+Where relevant, verify:
+
+- Creating and scheduling an alarm.
+- Cancelling a scheduled alarm.
+- Rescheduling an existing alarm.
+- Handling duplicate scheduling requests.
+- Triggering the correct event.
+- Dismissing and snoozing alarms.
+- Handling denied permissions.
+- Managing foreground and background transitions.
+- Releasing resources and event listeners.
+- Handling supported reboot and process-restart scenarios.
+
+Test on real devices when system-level behavior cannot be reliably validated in a simulator.
+
+If only one platform is tested, state which platform remains unverified.
+
+## Build and Debugging
+
+When investigating build failures:
+
+1. Capture the complete error message.
+2. Identify the failing project, target, task, or script.
+3. Determine whether the failure is caused by the current change or the existing environment.
+4. Make the smallest appropriate fix.
+5. Re-run the failing check.
+6. Inspect the final diff.
+
+Avoid destructive cleanup commands unless necessary. Never delete project files, signing configuration, or user changes simply to make a build pass.
+
+## Documentation Requirements
+
+Update documentation whenever a change affects:
+
+- Installation or native setup.
+- Public methods and configuration options.
+- Permissions or platform requirements.
+- Supported operating-system versions.
+- Events and callback payloads.
+- Alarm scheduling semantics.
+- Known limitations.
+- Troubleshooting instructions.
+
+Examples must match the actual implementation.
+
+## Git and Code Review
+
+Before committing changes:
+
+```bash
+git status --short
+git diff --check
+git diff
+```
+
+Follow the commit conventions in `CONTRIBUTING.md`.
+
+Prefer focused commits and pull requests. Do not rewrite Git history, force-push, or amend existing commits unless explicitly requested.
+
+Never include unrelated changes in a pull request.
+
+## Security and Privacy
+
+- Do not hardcode credentials or API keys.
+- Do not log sensitive information unnecessarily.
+- Validate data crossing the JavaScript/native boundary.
+- Use appropriate Android permissions and iOS authorization mechanisms.
+- Follow platform security requirements.
+- Report security-sensitive issues through the repository's designated private reporting channel.
+
+## Completion Checklist
+
+Before declaring a task complete:
+
+- [ ] The requested behavior is implemented.
+- [ ] Existing functionality and public APIs are preserved where possible.
+- [ ] Relevant platform-specific requirements are respected.
+- [ ] Tests or builds have been run where available.
+- [ ] Changes have been reviewed with `git diff`.
+- [ ] Documentation has been updated where needed.
+- [ ] Limitations and untested scenarios are clearly stated.
+- [ ] No unrelated changes, credentials, or generated artifacts were added.
+
+## Final Response Requirements
+
+When reporting completed

package/AlarmService.d.ts

@@ -107,6 +107,11 @@ export class AlarmService {
    * Check if an alarm is scheduled
    */
   static isScheduled(alarmId: string): Promise<boolean>;
+
+  /**
+   * Opens the vendor Autostart screen on Android; resolves false on iOS.
+   */
+  static openAutoStartSettings(): Promise<boolean>;
 }
 
 export default AlarmService;

package/AlarmService.ts

@@ -45,13 +45,19 @@ export class AlarmService {
     if (!alarmEmitter || !this.subscriptions.length) {
       this.subscriptions = [
         alarmEmitter?.addListener('onAlarmFired', (data: any) => {
-          this.listeners.fired.forEach(listener => listener(data as AlarmEvent));
+          this.listeners.fired.forEach(listener =>
+            listener(data as AlarmEvent),
+          );
         }),
         alarmEmitter?.addListener('onAlarmDismissed', (data: any) => {
-          this.listeners.dismissed.forEach(listener => listener(data as AlarmEvent));
+          this.listeners.dismissed.forEach(listener =>
+            listener(data as AlarmEvent),
+          );
         }),
         alarmEmitter?.addListener('onAlarmSnoozed', (data: any) => {
-          this.listeners.snoozed.forEach(listener => listener(data as AlarmEvent));
+          this.listeners.snoozed.forEach(listener =>
+            listener(data as AlarmEvent),
+          );
         }),
       ].filter(Boolean);
     }
@@ -190,6 +196,12 @@ export class AlarmService {
     if (!alarm) throw new Error('Alarm module not linked');
     return alarm.isScheduled(alarmId);
   }
+
+  /** Opens the vendor Autostart screen on Android; resolves false on iOS. */
+  static async openAutoStartSettings(): Promise<boolean> {
+    if (!alarm) throw new Error('Alarm module not linked');
+    return alarm.openAutoStartSettings();
+  }
 }
 
 // Export a singleton instance

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 react-native-alarm contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -361,6 +361,22 @@ const styles = StyleSheet.create({
 });
 ```
 
+## 📸 Screenshots, Demos & Examples
+
+Explore how `react-native-alarms` works on Android and iOS.
+
+### 🖼️ Screenshots
+
+| Sample 1 | Sample 2 | Sample 3 |
+|---|---|---|
+| <img src="src/assets/sample-1.png" width="180" alt="Sample 1" /> | <img src="src/assets/sample-2.png" width="180" alt="Sample 2" /> | <img src="src/assets/sample-3.png" width="180" alt="Sample 3" /> |
+
+### 🎥 Demo Video
+
+Watch the library in action, including alarm scheduling, ringing, and Stop/Snooze interactions.
+
+[▶️ Watch the React Native Alarms Demo](src/assets/recording.mp4)
+
 ## Troubleshooting
 
 ### "Alarm Native module is not linked"

package/commitlint.config.mjs

@@ -0,0 +1 @@
+export default { extends: ['@commitlint/config-conventional'] };

package/ios/alarm/AlarmKitBackend.swift

@@ -5,11 +5,34 @@ import SwiftUI
 #if canImport(AlarmKit)
 import ActivityKit
 import AlarmKit
+import AppIntents
 
 /// Metadata type required by `AlarmAttributes`; extend it if you add a Live Activity widget.
 @available(iOS 26.0, *)
 struct RNAlarmMetadata: AlarmMetadata {}
 
+/// Backs the "Open" button on the AlarmKit alert. An AlarmKit alert ignores taps on
+/// its body, so this intent (run in the app process, `openAppWhenRun`) is the only
+/// way the alert can open the app and show the React ring screen.
+@available(iOS 26.0, *)
+struct OpenAlarmAppIntent: LiveActivityIntent {
+  static let title: LocalizedStringResource = "Open Alarm"
+  static let description = IntentDescription("Opens the ringing alarm's screen")
+  static let openAppWhenRun: Bool = true
+  static let isDiscoverable: Bool = false
+
+  @Parameter(title: "alarmID")
+  var alarmID: String
+
+  init() {}
+  init(alarmID: String) { self.alarmID = alarmID }
+
+  func perform() async throws -> some IntentResult {
+    AlarmKitBackend.shared.openFromAlert(alarmID)
+    return .result()
+  }
+}
+
 /// Real alarms on iOS 26+: ring through silent mode and Focus with the system alarm UI.
 /// Only compiled with an SDK that ships AlarmKit (Xcode 26+); older toolchains build
 /// the app with the notification fallback only.
@@ -26,6 +49,10 @@ final class AlarmKitBackend {
   /// Alarms we are stopping as part of a programmatic snooze (so the observer
   /// reports "snoozed" instead of "dismissed").
   private var snoozing: Set<UUID> = []
+  /// Alarms stopped only to silence the system sound while the in-app ring screen
+  /// (with its own TTS) is showing. The ring session stays alive until JS calls
+  /// stop/snooze, so the observer must not report these as dismissed.
+  private var silenced: [UUID: AlarmData] = [:]
 
   private static let allWeekdays: [Locale.Weekday] = [
     .sunday, .monday, .tuesday, .wednesday, .thursday, .friday, .saturday,
@@ -98,23 +125,16 @@ final class AlarmKitBackend {
   {
     let title = LocalizedStringResource(stringLiteral: a.title.isEmpty ? "Alarm" : a.title)
     let stop = AlarmButton(text: "Stop", textColor: .white, systemImageName: "stop.fill")
-
-    let alert: AlarmPresentation.Alert
-    var countdown: AlarmPresentation.Countdown?
-    var duration: Alarm.CountdownDuration?
-    if a.snoozeEnabled {
-      let snooze = AlarmButton(text: "Snooze", textColor: .white, systemImageName: "zzz")
-      alert = AlarmPresentation.Alert(
-        title: title, stopButton: stop, secondaryButton: snooze, secondaryButtonBehavior: .countdown
-      )
-      countdown = AlarmPresentation.Countdown(title: "Snoozed", pauseButton: nil)
-      duration = Alarm.CountdownDuration(preAlert: nil, postAlert: Double(max(1, a.snoozeMinutes)) * 60)
-    } else {
-      alert = AlarmPresentation.Alert(title: title, stopButton: stop)
-    }
+    // The alert's body ignores taps and it allows a single secondary button, so it
+    // must be "Open" (via OpenAlarmAppIntent): the React ring screen it opens has
+    // its own Snooze/Finish. The system countdown-snooze button is dropped for it.
+    let open = AlarmButton(text: "Open", textColor: .white, systemImageName: "arrow.up.forward.app")
+    let alert = AlarmPresentation.Alert(
+      title: title, stopButton: stop, secondaryButton: open, secondaryButtonBehavior: .custom
+    )
 
     let attributes = AlarmAttributes<RNAlarmMetadata>(
-      presentation: AlarmPresentation(alert: alert, countdown: countdown),
+      presentation: AlarmPresentation(alert: alert),
       metadata: RNAlarmMetadata(),
       tintColor: .blue
     )
@@ -122,16 +142,18 @@ final class AlarmKitBackend {
       (a.sound.isEmpty || a.sound == "default") ? .default : .named(a.sound)
 
     return AlarmManager.AlarmConfiguration(
-      countdownDuration: duration,
       schedule: schedule,
       attributes: attributes,
+      secondaryIntent: OpenAlarmAppIntent(alarmID: a.id),
       sound: sound
     )
   }
 
   func cancel(_ id: String) {
-    try? manager.cancel(id: Self.uuid(for: id))
-    try? manager.cancel(id: Self.uuid(for: id, snooze: true))
+    for uuid in [Self.uuid(for: id), Self.uuid(for: id, snooze: true)] {
+      try? manager.cancel(id: uuid)
+      silenced.removeValue(forKey: uuid)
+    }
   }
 
   func cancelAll() {
@@ -139,19 +161,60 @@ final class AlarmKitBackend {
   }
 
   func stop(_ id: String) {
-    try? manager.stop(id: Self.uuid(for: id))
-    try? manager.stop(id: Self.uuid(for: id, snooze: true))
+    for uuid in [Self.uuid(for: id), Self.uuid(for: id, snooze: true)] {
+      try? manager.stop(id: uuid)
+      // Ended a session we had silenced earlier: the observer saw nothing change,
+      // so report the dismissal (and re-arm intervals) here instead.
+      if let a = silenced.removeValue(forKey: uuid) {
+        onEvent?(AlarmModule.eventDismissed, a)
+        if a.repeatType == "interval" { Task { try? await self.schedule(a) } }
+      }
+    }
   }
 
-  /// Silences the ringing alarm (if any) and re-rings once in `minutes`,
-  /// equivalent to Android's `AlarmScheduler.scheduleSnooze`.
-  func snooze(_ a: AlarmData, minutes: Int) async throws {
+  /// "Open" tapped on the system alert (OpenAlarmAppIntent). The tap stops the
+  /// AlarmKit alarm, so adopt the session as `silenced` — still ringing as far as
+  /// JS is concerned — and show the React ring screen once the app is frontmost.
+  func openFromAlert(_ id: String) {
+    guard let a = AlarmStore.get(id) else { return }
     let current = (try? manager.alarms) ?? []
     for uuid in [Self.uuid(for: a.id), Self.uuid(for: a.id, snooze: true)]
     where current.contains(where: { $0.id == uuid && $0.state == .alerting }) {
-      snoozing.insert(uuid)
+      silenced[uuid] = a
+      try? manager.stop(id: uuid)
+    }
+    // The system may have stopped it before we ran; the session is still ours.
+    if !silenced.values.contains(where: { $0.id == a.id }) {
+      silenced[Self.uuid(for: a.id)] = a
+    }
+    DispatchQueue.main.async { AlarmRingPresenter.present(a, bridge: nil) }
+  }
+
+  /// Stops the system alert's sound/UI while the in-app ring screen takes over.
+  /// The session stays "ringing" (see `silenced`) until JS stops or snoozes it.
+  func silence(_ id: String) {
+    let current = (try? manager.alarms) ?? []
+    for uuid in [Self.uuid(for: id), Self.uuid(for: id, snooze: true)]
+    where current.contains(where: { $0.id == uuid && $0.state == .alerting }) {
+      silenced[uuid] = stored(for: uuid)
       try? manager.stop(id: uuid)
     }
+  }
+
+  /// Silences the ringing alarm (if any) and re-rings once in `minutes`,
+  /// equivalent to Android's `AlarmScheduler.scheduleSnooze`.
+  func snooze(_ a: AlarmData, minutes: Int) async throws {
+    let current = (try? manager.alarms) ?? []
+    var wasSilenced = false
+    for uuid in [Self.uuid(for: a.id), Self.uuid(for: a.id, snooze: true)] {
+      if silenced.removeValue(forKey: uuid) != nil { wasSilenced = true }
+      if current.contains(where: { $0.id == uuid && $0.state == .alerting }) {
+        snoozing.insert(uuid)
+        try? manager.stop(id: uuid)
+      }
+    }
+    // Snoozed a session we had silenced: the observer saw nothing change, report it here.
+    if wasSilenced { onEvent?(AlarmModule.eventSnoozed, a) }
     let date = Date().addingTimeInterval(Double(max(1, minutes)) * 60)
     _ = try await manager.schedule(
       id: Self.uuid(for: a.id, snooze: true),
@@ -161,10 +224,11 @@ final class AlarmKitBackend {
   }
 
   func ringingAlarm() -> AlarmData? {
-    guard let alerting = ((try? manager.alarms) ?? []).first(where: { $0.state == .alerting }) else {
-      return nil
+    if let alerting = ((try? manager.alarms) ?? []).first(where: { $0.state == .alerting }) {
+      return stored(for: alerting.id)
     }
-    return stored(for: alerting.id)
+    // Sound silenced for the in-app ring screen, but the session is still live.
+    return silenced.values.first
   }
 
   // MARK: - Events
@@ -187,14 +251,17 @@ final class AlarmKitBackend {
     for (uuid, state) in states where lastStates[uuid] != state {
       guard let a = stored(for: uuid) else { continue }
       if state == .alerting {
+        silenced.removeValue(forKey: uuid) // ringing again supersedes any old silence
         onEvent?(AlarmModule.eventFired, a)
       } else if lastStates[uuid] == .alerting {
+        if silenced[uuid] != nil { continue } // silenced for the ring screen, not over yet
         onEvent?(state == .countdown ? AlarmModule.eventSnoozed : AlarmModule.eventDismissed, a)
       }
     }
 
     // One-off (`.fixed`) alarms disappear once stopped.
     for (uuid, previous) in lastStates where states[uuid] == nil && previous == .alerting {
+      if silenced[uuid] != nil { continue } // silenced for the ring screen, not over yet
       guard let a = stored(for: uuid) else { continue }
       if snoozing.remove(uuid) != nil {
         onEvent?(AlarmModule.eventSnoozed, a)

package/ios/alarm/AlarmModule.swift

@@ -16,6 +16,7 @@ final class AlarmModule: RCTEventEmitter {
   static let eventSnoozed = "onAlarmSnoozed"
 
   private var hasListeners = false
+  private var activeObserver: NSObjectProtocol?
 
   override init() {
     super.init()
@@ -27,10 +28,26 @@ final class AlarmModule: RCTEventEmitter {
       AlarmKitBackend.shared.startObserving()
     }
     #endif
-    // App launched by tapping the alarm notification before this module existed.
-    if let ringing = NotificationBackend.shared.ringing {
-      DispatchQueue.main.async { [weak self] in AlarmRingPresenter.present(ringing, bridge: self?.bridge) }
-    }
+    // App launched by tapping the alarm notification/alert before this module existed.
+    DispatchQueue.main.async { [weak self] in self?.presentIfRinging() }
+    // Tapping an AlarmKit alert (and some notification taps on a warm start) only
+    // foregrounds the app without any delegate callback, so also check on activation.
+    activeObserver = NotificationCenter.default.addObserver(
+      forName: UIApplication.didBecomeActiveNotification, object: nil, queue: .main
+    ) { [weak self] _ in self?.presentIfRinging() }
+  }
+
+  deinit {
+    if let activeObserver { NotificationCenter.default.removeObserver(activeObserver) }
+  }
+
+  /// Shows the ring screen when a backend says an alarm is ringing right now.
+  private func presentIfRinging() {
+    var ringing = NotificationBackend.shared.ringing
+    #if canImport(AlarmKit)
+    if #available(iOS 26.0, *), ringing == nil { ringing = AlarmKitBackend.shared.ringingAlarm() }
+    #endif
+    if let ringing { AlarmRingPresenter.present(ringing, bridge: bridge) }
   }
 
   private func handle(_ name: String, _ alarm: AlarmData) {

package/ios/alarm/AlarmRingPresenter.swift

@@ -15,12 +15,17 @@ final class AlarmRingPresenter {
 
   static func present(_ alarm: AlarmData, bridge: RCTBridge?, attempt: Int = 0) {
     DispatchQueue.main.async {
-      if controller != nil, alarmId == alarm.id { return }
-      // Cold start from a notification tap: the root surface or window may not be
-      // ready yet, so retry briefly.
+      if controller != nil, alarmId == alarm.id {
+        // Already showing (e.g. presented while backgrounded, now foregrounded):
+        // still make sure the native sound yields to the screen's own TTS.
+        silenceIfActive(alarm.id)
+        return
+      }
+      // Cold start from a notification tap or the AlarmKit "Open" button: the root
+      // surface or window may not be ready yet, so retry for up to ~15 s.
       guard let surface = makeSurface(bridge, props: alarm.toDictionary()),
             let top = topViewController() else {
-        if attempt < 20 {
+        if attempt < 60 {
           DispatchQueue.main.asyncAfter(deadline: .now() + 0.25) {
             present(alarm, bridge: bridge, attempt: attempt + 1)
           }
@@ -42,6 +47,7 @@ final class AlarmRingPresenter {
         top.present(vc, animated: true)
         controller = vc
         alarmId = alarm.id
+        silenceIfActive(alarm.id)
       }
       if let existing = controller {
         existing.dismiss(animated: false, completion: show)
@@ -51,6 +57,18 @@ final class AlarmRingPresenter {
     }
   }
 
+  /// The ring screen speaks the task via TTS, and iOS won't play it over the
+  /// notification / AlarmKit sound, so stop that sound once the screen is up.
+  /// Only while the app is frontmost: in the background the system alert is the
+  /// only thing the user can hear, so it must keep ringing.
+  private static func silenceIfActive(_ id: String) {
+    guard UIApplication.shared.applicationState == .active else { return }
+    NotificationBackend.shared.silence(id)
+    #if canImport(AlarmKit)
+    if #available(iOS 26.0, *) { AlarmKitBackend.shared.silence(id) }
+    #endif
+  }
+
   /// Called when ringing ends for any reason (stop, snooze, cancel).
   static func dismiss(_ id: String? = nil) {
     DispatchQueue.main.async {

package/ios/alarm/NotificationBackend.swift

@@ -169,6 +169,12 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
     if ringing?.id == a.id { ringing = nil }
   }
 
+  /// Stops the notification's sound (by clearing the delivered notification) while the
+  /// in-app ring screen takes over; `ringing` stays set so the session is still live.
+  func silence(_ id: String) {
+    center.removeDeliveredNotifications(withIdentifiers: ids(for: id))
+  }
+
   func cancel(_ id: String) {
     center.removePendingNotificationRequests(withIdentifiers: ids(for: id))
     center.removeDeliveredNotifications(withIdentifiers: ids(for: id))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-alarms",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "A powerful, cross-platform alarm management library for React Native",
   "private": false,
   "main": "index.ts",
@@ -22,7 +22,7 @@
     "lint": "eslint .",
     "start": "react-native start",
     "test": "jest",
-    "prepare": "npm run build",
+    "prepare": "husky",
     "build": "tsc",
     "clean": "rm -rf dist types *.d.ts"
   },
@@ -56,6 +56,8 @@
     "@babel/core": "^7.25.2",
     "@babel/preset-env": "^7.25.3",
     "@babel/runtime": "^7.25.0",
+    "@commitlint/cli": "^21.2.4",
+    "@commitlint/config-conventional": "^21.2.4",
     "@react-native-community/cli": "20.2.0",
     "@react-native-community/cli-platform-android": "20.2.0",
     "@react-native-community/cli-platform-ios": "20.2.0",
@@ -68,6 +70,7 @@
     "@types/react": "^19.2.0",
     "@types/react-test-renderer": "^19.1.0",
     "eslint": "^8.19.0",
+    "husky": "^9.1.7",
     "jest": "^29.6.3",
     "prettier": "2.8.8",
     "react": "19.3.0",