Document and test UserDefaults fallback order

Author: fatbobman

README.md

@@ -600,7 +600,19 @@ This flag helps bypass macro validation in CI environments where the full macro
 
 ### Default Value Behavior for UserDefaults and iCloud Key-Value Store
 
-All persistent properties (those marked with @DefaultsBacked or @CloudBacked, either explicitly or implicitly) must be declared with default values. The framework captures these declaration-time defaults and maintains them as immutable fallback values throughout the object's lifetime. When keys are missing from the underlying storage (UserDefaults or iCloud Key-Value Store), properties automatically revert to these preserved default values, ensuring consistent behavior regardless of external storage modifications.
+All persistent properties (those marked with @DefaultsBacked or @CloudBacked, either explicitly or implicitly) must be declared with default values. The framework captures these declaration-time defaults and maintains them as immutable model defaults throughout the object's lifetime.
+
+Fallback order depends on the backing store:
+
+- `@ObservableDefaults` (`UserDefaults`)
+  1. Persisted value in the selected `UserDefaults` domain
+  2. Value provided by `UserDefaults.register(defaults:)`
+  3. Declaration-time model default captured by ObservableDefaults
+- `@ObservableCloud` (`NSUbiquitousKeyValueStore`)
+  1. Persisted cloud value
+  2. Declaration-time model default captured by ObservableDefaults
+
+This means `removeObject(forKey:)` does not always revert to the declaration default for `UserDefaults`. If the key has a registered default, that registered default is used first.
 
 ```swift
 @ObservableDefaults(autoInit: false) // @ObservableCloud(autoInit: false) is the same
@@ -625,12 +637,15 @@ let user = User(username: "alice", age: 25)
 
 user.username = "bob"  // Changes current value, default value stays "guest"
 
-// If UserDefaults keys are deleted externally:
-UserDefaults.standard.removeObject(forKey: "username")
-UserDefaults.standard.removeObject(forKey: "age")
+let defaults = UserDefaults.standard
+defaults.register(defaults: ["username": "registered-user"])
+defaults.set("bob", forKey: "username")
+defaults.set(25, forKey: "age")
+defaults.removeObject(forKey: "username")
+defaults.removeObject(forKey: "age")
 
-print(user.username)  // "guest" (reverts to declaration default)
-print(user.age)       // 18 (reverts to declaration default)
+print(user.username)  // "registered-user" (registered default wins)
+print(user.age)       // 18 (no registered default, so declaration default is used)
 ```
 
 > **Recommendation**: Unless you have specific requirements, use `autoInit: true` (default) to generate the standard initializer automatically. This helps avoid the misconception that default values can be modified through custom initializers.

README_zh.md

@@ -600,7 +600,19 @@ build_app(
 
 ### UserDefaults 和 iCloud Key-Value Store 的默认值行为
 
-所有持久化属性（那些明确或隐式标记为 @DefaultsBacked 或 @CloudBacked 的属性）必须用默认值声明。框架捕获这些声明时的默认值，并在对象的整个生命周期内将它们保持为不可变的回退值。当底层存储（UserDefaults 或 iCloud Key-Value Store）中缺少键时，属性会自动恢复到这些保留的默认值，确保行为一致，无论外部存储修改如何。
+所有持久化属性（那些明确或隐式标记为 @DefaultsBacked 或 @CloudBacked 的属性）都必须用默认值声明。框架会捕获这些声明时的默认值，并在对象整个生命周期内将其保持为不可变的模型默认值。
+
+回退顺序取决于底层存储：
+
+- `@ObservableDefaults`（`UserDefaults`）
+  1. 所选 `UserDefaults` 域中的持久化值
+  2. 通过 `UserDefaults.register(defaults:)` 注册的默认值
+  3. ObservableDefaults 捕获的声明时模型默认值
+- `@ObservableCloud`（`NSUbiquitousKeyValueStore`）
+  1. 云端持久化值
+  2. ObservableDefaults 捕获的声明时模型默认值
+
+这意味着对于 `UserDefaults`，`removeObject(forKey:)` 并不一定直接回退到声明默认值。如果该 key 存在 registered default，会优先使用 registered default。
 
 ```swift
 @ObservableDefaults(autoInit: false) // @ObservableCloud(autoInit: false) 相同
@@ -625,12 +637,15 @@ let user = User(username: "alice", age: 25)
 
 user.username = "bob"  // 更改当前值，默认值保持 "guest"
 
-// 如果 UserDefaults 键被外部删除：
-UserDefaults.standard.removeObject(forKey: "username")
-UserDefaults.standard.removeObject(forKey: "age")
+let defaults = UserDefaults.standard
+defaults.register(defaults: ["username": "registered-user"])
+defaults.set("bob", forKey: "username")
+defaults.set(25, forKey: "age")
+defaults.removeObject(forKey: "username")
+defaults.removeObject(forKey: "age")
 
-print(user.username)  // "guest"（恢复到声明默认值）
-print(user.age)       // 18（恢复到声明默认值）
+print(user.username)  // "registered-user"（优先使用 registered default）
+print(user.age)       // 18（没有 registered default，因此回退到声明默认值）
 ```
 
 > **建议**: 除非您有特定要求，否则使用 `autoInit: true`（默认）来自动生成标准初始化器。这有助于避免认为可以通过自定义初始化器修改默认值的误解。

Tests/ObservableDefaultsTests/ExternalChangeEqualityTests.swift

@@ -11,12 +11,16 @@ import ObservableDefaults
 import Observation
 import Testing
 
-@Suite("External Change Equality Check")
+@Suite("External Change Equality Check", .serialized)
 struct ExternalChangeEqualityTests {
+    private func makeUserDefaults(testName: String = #function) -> UserDefaults {
+        UserDefaults.getTestInstance(
+            suiteName: "ExternalChangeEqualityTests.\(testName).\(UUID().uuidString)")
+    }
 
     @Test("Unrelated property not notified when another property changes externally")
     func unrelatedPropertyNotNotified() {
-        let userDefaults = UserDefaults.getTestInstance(suiteName: #function)
+        let userDefaults = makeUserDefaults()
         let model = MockModel(userDefaults: userDefaults)
 
         // Track age - expect NO mutation when only name changes
@@ -26,7 +30,7 @@ struct ExternalChangeEqualityTests {
 
     @Test("Same value write does not notify for backed property")
     func sameValueWriteNotNotified() {
-        let userDefaults = UserDefaults.getTestInstance(suiteName: #function)
+        let userDefaults = makeUserDefaults()
         let model = MockModel(userDefaults: userDefaults)
 
         // Track name - expect NO mutation when writing the same value
@@ -37,7 +41,7 @@ struct ExternalChangeEqualityTests {
     @MainActor
     @Test("MainActor unrelated property not notified when another property changes externally")
     func mainActorUnrelatedPropertyNotNotified() async {
-        let userDefaults = UserDefaults.getTestInstance(suiteName: #function)
+        let userDefaults = makeUserDefaults()
         let model = MockModelMainActor(userDefaults: userDefaults)
 
         // Track count - expect NO mutation when only name changes
@@ -53,7 +57,7 @@ struct ExternalChangeEqualityTests {
     @MainActor
     @Test("MainActor same value write does not notify for backed property")
     func mainActorSameValueWriteNotNotified() async {
-        let userDefaults = UserDefaults.getTestInstance(suiteName: #function)
+        let userDefaults = makeUserDefaults()
         let model = MockModelMainActor(userDefaults: userDefaults)
 
         // Track name - expect NO mutation when writing the same value
@@ -69,7 +73,7 @@ struct ExternalChangeEqualityTests {
 
     @Test("Removing key from UserDefaults triggers mutation back to default value")
     func removingKeyTriggersMutation() {
-        let userDefaults = UserDefaults.getTestInstance(suiteName: #function)
+        let userDefaults = makeUserDefaults()
         let model = MockModel(userDefaults: userDefaults)
 
         // Set a non-default value first
@@ -83,7 +87,7 @@ struct ExternalChangeEqualityTests {
 
     @Test("Optional property: removing key triggers mutation back to nil")
     func optionalRemovingKeyTriggersMutation() {
-        let userDefaults = UserDefaults.getTestInstance(suiteName: #function)
+        let userDefaults = makeUserDefaults()
         let model = MockModelOptional(userDefaults: userDefaults)
 
         // Set a non-nil value first
@@ -94,4 +98,46 @@ struct ExternalChangeEqualityTests {
         userDefaults.removeObject(forKey: "optionalName")
         #expect(model.optionalName == nil)
     }
+
+    @Test("Removing key falls back to registered default before model default")
+    func removingKeyFallsBackToRegisteredDefault() {
+        let userDefaults = makeUserDefaults()
+        userDefaults.register(defaults: ["name": "Registered"])
+        let model = MockModel(userDefaults: userDefaults)
+
+        model.name = "Changed"
+
+        tracking(model, \.name, .userDefaults)
+        userDefaults.removeObject(forKey: "name")
+        #expect(model.name == "Registered")
+    }
+
+    @Test("Optional property falls back to registered default before nil")
+    func optionalRemovingKeyFallsBackToRegisteredDefault() {
+        let userDefaults = makeUserDefaults()
+        userDefaults.register(defaults: ["optionalName": "RegisteredOptional"])
+        let model = MockModelOptional(userDefaults: userDefaults)
+
+        model.optionalName = "Hello"
+
+        tracking(model, \.optionalName, .userDefaults)
+        userDefaults.removeObject(forKey: "optionalName")
+        #expect(model.optionalName == "RegisteredOptional")
+    }
+
+    @MainActor
+    @Test("MainActor removing key falls back to registered default")
+    func mainActorRemovingKeyFallsBackToRegisteredDefault() async {
+        let userDefaults = makeUserDefaults()
+        userDefaults.register(defaults: ["name": "MainActorRegistered"])
+        let model = MockModelMainActor(userDefaults: userDefaults)
+
+        model.name = "Changed"
+
+        tracking(model, \.name, .userDefaults)
+        userDefaults.removeObject(forKey: "name")
+
+        try? await Task.sleep(nanoseconds: 100_000_000)
+        #expect(model.name == "MainActorRegistered")
+    }
 }