Add limitToInstance parameter for App Group cross-process notification support

- Added `limitToInstance` parameter to @ObservableDefaults macro (default: true)
- When set to false, enables receiving UserDefaults notifications from all instances
- Essential for App Group scenarios where widgets/extensions modify shared UserDefaults
- Added comprehensive tests for cross-process notification behavior
- Maintains backward compatibility with default behavior unchanged

This fixes the issue where @default macro cannot trigger view refresh when App Group is enabled,
as it was only listening to notifications from the specific UserDefaults instance.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: fatbobman

Sources/ObservableDefaults/Macros.swift

@@ -146,13 +146,26 @@ public macro ObservableOnly() = #externalMacro(
 ///     ignoreExternalChanges: false,
 ///     suiteName: "group.myapp",
 ///     prefix: "myApp_",
-///     observeFirst: false
+///     observeFirst: false,
+///     limitToInstance: true
 /// )
 /// class Settings {
 ///     // Properties automatically managed
 /// }
 /// ```
 ///
+/// Cross-process synchronization (App Groups):
+/// ```swift
+/// @ObservableDefaults(
+///     suiteName: "group.myapp",
+///     prefix: "widget_",  // Use unique prefix to avoid key conflicts
+///     limitToInstance: false  // Enable cross-process notifications
+/// )
+/// class WidgetSettings {
+///     var sharedData: String = "shared"  // Syncs across app and widgets
+/// }
+/// ```
+///
 /// Observe First mode (prioritizes observation over persistence):
 /// ```swift
 /// @ObservableDefaults(observeFirst: true)
@@ -170,6 +183,7 @@ public macro ObservableOnly() = #externalMacro(
 /// - `suiteName`: Custom UserDefaults suite name (default: nil, uses standard)
 /// - `prefix`: Prefix for all UserDefaults keys (default: nil, must not contain '.')
 /// - `observeFirst`: Enables Observe First mode (default: false)
+/// - `limitToInstance`: Limits observations to the specific UserDefaults instance. Set to false for App Group cross-process synchronization (default: true)
 /// - `defaultIsolationIsMainActor`: Set to true when project's defaultIsolation is MainActor (default: false)
 ///
 /// Generated initializer (when autoInit is true):
@@ -213,6 +227,7 @@ public macro ObservableDefaults(
     suiteName: String = "",
     prefix: String = "",
     observeFirst: Bool = false,
+    limitToInstance: Bool = true,
     defaultIsolationIsMainActor: Bool = false) = #externalMacro(
     module: "ObservableDefaultsMacros",
     type: "ObservableDefaultsMacros")

Sources/ObservableDefaultsMacros/Macros/ObservableDefaultsMacro.swift

@@ -66,6 +66,8 @@ public enum ObservableDefaultsMacros {
     static let prefix: String = "prefix"
     /// Parameter for enabling Observe First mode
     static let observeFirst: String = "observeFirst"
+    /// Parameter for limiting observations to specific UserDefaults instance
+    static let limitToInstance: String = "limitToInstance"
     /// Parameter for indicating when project's defaultIsolation is set to MainActor
     static let defaultIsolationIsMainActor: String = "defaultIsolationIsMainActor"
 }
@@ -108,6 +110,7 @@ extension ObservableDefaultsMacros: MemberMacro {
             prefix,
             ignoreExternalChanges,
             _,
+            limitToInstance,
             defaultIsolationIsMainActor,
             suiteNameExpression
         ) = extractProperty(node)
@@ -351,7 +354,7 @@ extension ObservableDefaultsMacros: MemberMacro {
                     notificationObserver = NotificationCenter.default
                         .addObserver(
                             forName: UserDefaults.didChangeNotification,
-                            object: userDefaults,
+                            object: \(raw: limitToInstance ? "userDefaults" : "nil"),
                             queue: .main
                         ) { [weak host, prefix, observableKeysBlacklist] notification in
                             guard let host else { return }
@@ -412,7 +415,7 @@ extension ObservableDefaultsMacros: MemberMacro {
                     NotificationCenter.default
                         .addObserver(
                             forName: UserDefaults.didChangeNotification,
-                            object: userDefaults,
+                            object: \(raw: limitToInstance ? "userDefaults" : "nil"),
                             queue: nil,
                             using: userDefaultsDidChange
                         )
@@ -538,7 +541,7 @@ extension ObservableDefaultsMacros: MemberAttributeMacro {
         providingAttributesFor member: some DeclSyntaxProtocol,
         in _: some MacroExpansionContext) throws -> [SwiftSyntax.AttributeSyntax]
     {
-        let (_, _, _, _, observeFirst, _, _) = extractProperty(node)
+        let (_, _, _, _, observeFirst, _, _, _) = extractProperty(node)
         guard let varDecl = member.as(VariableDeclSyntax.self),
               varDecl.isObservable
         else {
@@ -583,6 +586,7 @@ extension ObservableDefaultsMacros {
         prefix: String,
         ignoreExternalChanges: Bool,
         observeFirst: Bool,
+        limitToInstance: Bool,
         defaultIsolationIsMainActor: Bool,
         invalidSuiteNameExpression: ExprSyntax?)
     {
@@ -591,6 +595,7 @@ extension ObservableDefaultsMacros {
         var prefix = ""
         var ignoreExternalChanges = false
         var observeFirst = false
+        var limitToInstance = true
         var defaultIsolationIsMainActor = false
         var invalidSuiteNameExpression: ExprSyntax?
 
@@ -622,14 +627,18 @@ extension ObservableDefaultsMacros {
                           let booleanLiteral = argument.expression.as(BooleanLiteralExprSyntax.self)
                 {
                     observeFirst = booleanLiteral.literal.text == "true"
+                } else if argument.label?.text == ObservableDefaultsMacros.limitToInstance,
+                          let booleanLiteral = argument.expression.as(BooleanLiteralExprSyntax.self)
+                {
+                    limitToInstance = booleanLiteral.literal.text == "true"
                 } else if argument.label?.text == ObservableDefaultsMacros.defaultIsolationIsMainActor,
                           let booleanLiteral = argument.expression.as(BooleanLiteralExprSyntax.self)
                 {
                     defaultIsolationIsMainActor = booleanLiteral.literal.text == "true"
                 }
             }
         }
-        return (autoInit, suiteName, prefix, ignoreExternalChanges, observeFirst, defaultIsolationIsMainActor, invalidSuiteNameExpression)
+        return (autoInit, suiteName, prefix, ignoreExternalChanges, observeFirst, limitToInstance, defaultIsolationIsMainActor, invalidSuiteNameExpression)
     }
 }
 

Tests/ObservableDefaultsTests/CrossProcessNotificationTests.swift

@@ -0,0 +1,121 @@
+//
+//  CrossProcessNotificationTests.swift
+//  ObservableDefaults
+//
+//  Tests for cross-process notification functionality with limitToInstance parameter
+//
+
+import Testing
+@testable import ObservableDefaults
+import Foundation
+
+@ObservableDefaults(
+    suiteName: "test.crossprocess.suite1",
+    prefix: "app_",
+    limitToInstance: false  // Enable cross-process notifications
+)
+class SettingsWithPrefix {
+    var userName: String = "InitialUser"
+    var counter: Int = 0
+}
+
+@ObservableDefaults(
+    suiteName: "test.crossprocess.suite2",
+    limitToInstance: false  // Enable cross-process notifications
+)
+class SettingsNoPrefix {
+    var userName: String = "OtherUser"
+    var counter: Int = 100
+}
+
+@Suite("Cross-Process Notification Tests", .serialized)
+struct CrossProcessNotificationTests {
+
+    func cleanupUserDefaults() {
+        // Clean up UserDefaults before each test
+        if let suite = UserDefaults(suiteName: "test.crossprocess.suite1") {
+            for key in suite.dictionaryRepresentation().keys {
+                suite.removeObject(forKey: key)
+            }
+            suite.synchronize()
+        }
+        if let suite = UserDefaults(suiteName: "test.crossprocess.suite2") {
+            for key in suite.dictionaryRepresentation().keys {
+                suite.removeObject(forKey: key)
+            }
+            suite.synchronize()
+        }
+    }
+
+    @Test("Only receive notifications for matching suite when limitToInstance is false")
+    func testCrossProcessNotificationFiltering() async throws {
+        cleanupUserDefaults()
+
+        // Create instances
+        let settingsWithPrefix = SettingsWithPrefix()
+        let settingsNoPrefix = SettingsNoPrefix()
+
+        // Verify initial values
+        #expect(settingsWithPrefix.userName == "InitialUser")
+        #expect(settingsWithPrefix.counter == 0)
+        #expect(settingsNoPrefix.userName == "OtherUser")
+        #expect(settingsNoPrefix.counter == 100)
+
+        // Modify the suite WITH prefix directly through UserDefaults
+        let suiteWithPrefix = UserDefaults(suiteName: "test.crossprocess.suite1")!
+        suiteWithPrefix.set("UpdatedUser", forKey: "app_userName")  // Has prefix
+        suiteWithPrefix.set(42, forKey: "app_counter")  // Has prefix
+
+        // Post notification to simulate external change
+        NotificationCenter.default.post(name: UserDefaults.didChangeNotification, object: nil)
+
+        // Allow time for notification processing
+        try await Task.sleep(nanoseconds: 200_000_000) // 0.2 seconds
+
+        // Values should be updated automatically due to limitToInstance: false
+        #expect(settingsWithPrefix.userName == "UpdatedUser")
+        #expect(settingsWithPrefix.counter == 42)
+
+        // Now modify the suite WITHOUT prefix (should NOT affect settingsWithPrefix)
+        let suiteNoPrefix = UserDefaults(suiteName: "test.crossprocess.suite2")!
+        suiteNoPrefix.set("ChangedOtherUser", forKey: "userName")  // No prefix
+        suiteNoPrefix.set(200, forKey: "counter")  // No prefix
+
+        // Post notification to simulate external change
+        NotificationCenter.default.post(name: UserDefaults.didChangeNotification, object: nil)
+
+        // Allow time for notification processing
+        try await Task.sleep(nanoseconds: 200_000_000) // 0.2 seconds
+
+        // settingsWithPrefix should remain unchanged (different suite, different keys)
+        #expect(settingsWithPrefix.userName == "UpdatedUser")  // Should stay the same
+        #expect(settingsWithPrefix.counter == 42)  // Should stay the same
+
+        // settingsNoPrefix should have new values when accessed
+        #expect(settingsNoPrefix.userName == "ChangedOtherUser")
+        #expect(settingsNoPrefix.counter == 200)
+    }
+
+    @Test("Verify prefix isolation between suites")
+    func testPrefixIsolation() async throws {
+        cleanupUserDefaults()
+
+        let settingsWithPrefix = SettingsWithPrefix()
+        let settingsNoPrefix = SettingsNoPrefix()
+
+        // Set values through the instances
+        settingsWithPrefix.userName = "PrefixUser"
+        settingsNoPrefix.userName = "NoPrefixUser"
+
+        // Check UserDefaults directly to verify keys
+        let suiteWithPrefix = UserDefaults(suiteName: "test.crossprocess.suite1")!
+        let suiteNoPrefix = UserDefaults(suiteName: "test.crossprocess.suite2")!
+
+        // Keys should be different due to prefix
+        #expect(suiteWithPrefix.string(forKey: "app_userName") == "PrefixUser")
+        #expect(suiteWithPrefix.string(forKey: "userName") == nil)  // No key without prefix
+
+        #expect(suiteNoPrefix.string(forKey: "userName") == "NoPrefixUser")
+        #expect(suiteNoPrefix.string(forKey: "app_userName") == nil)  // No key with prefix
+    }
+}