3.0.0 release readiness: cross-platform Observation, Cache pin, docs (#153)

* Cross-platform observation delivery + WebAssembly build support

#149 (WASM): switch Combine/OSLog/SwiftUI-gated #if !os(Linux) && !os(Windows)
guards to their canImport(...) checks. os(WASI) is neither Linux nor Windows, so the
old guards pulled Combine/SwiftUI into the wasm build. Keychain/iCloud stay Apple-only.

#150 (observation off Apple): delivery was bridged through Combine's
consume(object: cache) (Apple-only), so withObservationTracking never fired on
Linux/Windows/wasm. Now every mutation path (State/StoredState/FileState/SyncState/
SecureState/DependencySlice) calls notifyChange() directly on all platforms, and the
Combine cache bridge is removed so Apple still fires exactly once.

163 tests pass on macOS. Observation tests stay gated off Linux/Windows: swift-corelibs
-xctest cannot discover synchronous @mainactor test methods there (it force-casts test
thunks to () -> () and aborts) — a test-harness limitation, not a runtime one. The #150
delivery code itself is cross-platform. Full wasm build + Linux collection-typed state
also need the Cache fix (0xLeif/Cache#30).

Addresses #149, #150.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Prepare 3.0.0 release: pure Observation delivery, Cache pin, docs

- Drop the unused Combine cache bridge from Application; document that
  notifyChange() must stay synchronous on the main thread
- Add CrossPlatformObservationTests (async @mainactor) so Linux/Windows CI
  exercises Observation delivery; keep the fuller Apple-gated suites
- Gate ObservedDependency on canImport(SwiftUI) for WebAssembly
- Pin Cache to the 0xLeif/Cache#30 commit for WASM + Linux collection casts
- Point installation guides at 3.0.0; remove stale Examples fledge lane

Co-authored-by: Leif <leif.algo@pm.me>

* Fix CrossPlatformObservationTests: mutate via local var state

Application.state(...).value is an immutable rvalue; assign through a
mutable local like the other AppStateTests.

Co-authored-by: Leif <leif.algo@pm.me>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: 3 people

Package.swift

@@ -26,7 +26,13 @@ let package = Package(
         )
     ],
     dependencies: [
-        .package(url: "https://github.com/0xLeif/Cache", from: "2.0.0"),
+        // Pin to the Cache commit that includes WebAssembly `canImport(Combine)` guards and the
+        // Linux/WASI collection-cast fix from 0xLeif/Cache#30. Switch back to a versioned
+        // `from:` pin once that PR is merged and tagged (e.g. 2.1.3+).
+        .package(
+            url: "https://github.com/0xLeif/Cache",
+            revision: "33ef0d77e144eaab0734b3da02c3fed6629166eb"
+        ),
         .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.4.0")
     ],
     targets: [

Sources/AppState/Application/Application+public.swift

@@ -1,5 +1,5 @@
 import Foundation
-#if !os(Linux) && !os(Windows)
+#if canImport(SwiftUI)
 import SwiftUI
 #endif
 
@@ -387,7 +387,7 @@ public extension Application {
     }
 }
 
-#if !os(Linux) && !os(Windows)
+#if canImport(SwiftUI)
 // MARK: - SwiftUI Preview Dependency Functions
 
 public extension Application {

Sources/AppState/Application/Application.swift

@@ -1,10 +1,8 @@
 import Cache
+import Foundation
 import Observation
-#if !os(Linux) && !os(Windows)
-import Combine
+#if canImport(OSLog)
 import OSLog
-#else
-import Foundation
 #endif
 
 /// `Application` is a class that can be observed for changes, keeping track of the states within the application.
@@ -14,7 +12,7 @@ open class Application: NSObject {
     @MainActor
     static var shared: Application = Application()
 
-    #if !os(Linux) && !os(Windows)
+    #if canImport(OSLog)
     /// Logger specifically for AppState
     public var logger: Dependency<Logger> {
         dependency(Logger(subsystem: "AppState", category: "Application"))
@@ -44,21 +42,16 @@ open class Application: NSObject {
     /// view body — as dependent on AppState, and mutating it (via ``notifyChange()``) tells those
     /// observers to update.
     ///
+    /// Delivery is cross-platform: every AppState mutation path calls ``notifyChange()`` directly.
+    /// There is no Combine/`ObservableObject` bridge involved in Observation delivery.
+    ///
     /// Thread-safety: every mutation funnels through ``notifyChange()``, which AppState only invokes
-    /// from its main-actor setters and from the cache observer below — and that observer fires
-    /// *synchronously* during those same main-actor cache mutations. Reads occur on the main actor
-    /// (SwiftUI bodies and the `@MainActor` property wrappers). The mutation itself is applied through
-    /// the synthesized `@Observable` registrar, which is `Sendable` and internally synchronized.
+    /// from its main-actor setters (and from `@MainActor` hooks such as
+    /// ``didChangeExternally(notification:)``). Reads occur on the main actor (SwiftUI bodies and the
+    /// `@MainActor` property wrappers). The mutation itself is applied through the synthesized
+    /// `@Observable` registrar, which is `Sendable` and internally synchronized.
     private var changeAnchor: Int = 0
 
-    #if !os(Linux) && !os(Windows)
-    /// A set to store cancellables for Combine subscriptions, ensuring they are properly managed and released.
-    @ObservationIgnored
-    private var bag: Set<AnyCancellable> = Set()
-
-    deinit { bag.removeAll() }
-    #endif
-
     /// Initializes a new instance of `Application`.
     ///
     /// This initializer is used for the default `Application.shared` instance and any custom `Application` subclasses.
@@ -77,10 +70,6 @@ open class Application: NSObject {
 
         setup(self)
         loadDefaultDependencies()
-
-        #if !os(Linux) && !os(Windows)
-        consume(object: cache)
-        #endif
     }
 
     /// Registers the current Observation tracking scope (such as a SwiftUI view body) as dependent on
@@ -106,6 +95,10 @@ open class Application: NSObject {
     ///   not `Sendable`, so the change cannot be hopped to the main thread on the caller's behalf — the
     ///   invariant is instead asserted here so off-main misuse surfaces in debug and CI. `Application`'s
     ///   setters and the `@MainActor` `didChangeExternally(notification:)` override already satisfy it.
+    ///
+    ///   Callers must not wrap this in an unconditional `DispatchQueue.main.async` hop: asynchronous
+    ///   delivery would break the synchronous `withObservationTracking` contract that AppState and
+    ///   SwiftUI rely on when already on the main thread.
     public func notifyChange() {
         assert(Thread.isMainThread, "Application.notifyChange() must be called on the main thread.")
 
@@ -151,35 +144,4 @@ open class Application: NSObject {
         load(dependency: \.userDefaults)
         load(dependency: \.fileManager)
     }
-
-    #if !os(Linux) && !os(Windows)
-    /// Consumes changes in the provided ObservableObject and sends updates before the object will change.
-    ///
-    /// - Parameter object: The ObservableObject to observe
-    private func consume<Object: ObservableObject>(
-        object: Object
-    ) {
-        bag.insert(
-            object.objectWillChange.sink(
-                receiveCompletion: { _ in },
-                receiveValue: { [weak self] _ in
-                    // Deliver synchronously when already on main (preserving the synchronous
-                    // observation contract `withObservationTracking` relies on), and only hop to main
-                    // when a dependency publishes off-main — `notifyChange()` asserts main-thread and
-                    // mutates `changeAnchor`, which must never be touched off the main thread.
-                    if Thread.isMainThread {
-                        self?.notifyChange()
-                    } else {
-                        DispatchQueue.main.async {
-                            MainActor.assumeIsolated {
-                                Application.shared.notifyChange()
-                            }
-                        }
-                    }
-                }
-            )
-        )
-    }
-    #endif
 }
-

Sources/AppState/Application/Types/Dependency/Slice/Application+DependencySlice.swift

@@ -34,9 +34,7 @@ extension Application.DependencySlice where SliceKeyPath == WritableKeyPath<Valu
     public var value: SliceValue {
         get { dependency.value[keyPath: keyPath] }
         set {
-            #if !os(Linux) && !os(Windows)
             Application.shared.notifyChange()
-            #endif
             dependency.value[keyPath: keyPath] = newValue
         }
     }

Sources/AppState/Application/Types/Helper/Application+ApplicationPreview.swift

@@ -1,4 +1,4 @@
-#if !os(Linux) && !os(Windows)
+#if canImport(SwiftUI)
 import SwiftUI
 
 extension Application {

Sources/AppState/Application/Types/State/Application+FileState.swift

@@ -74,7 +74,7 @@ extension Application {
                             )
                         }
 
-                        #if (!os(Linux) && !os(Windows))
+                        #if canImport(ObjectiveC)
                         if NSClassFromString("XCTest") == nil {
                             Task {
                                 await MainActor.run {
@@ -149,6 +149,8 @@ extension Application {
                         )
                     }
                 }
+
+                shared.notifyChange()
             }
         }
 

Sources/AppState/Application/Types/State/Application+State.swift

@@ -11,7 +11,7 @@ extension Application {
         }
 
         public static var emoji: Character {
-            #if !os(Linux) && !os(Windows)
+            #if canImport(OSLog)
             return "🔄"
             #else
             return "📦"
@@ -27,6 +27,21 @@ extension Application {
         private let initial: Value
 
         /// The current state value.
+        ///
+        /// - Note: **Issue #151 — Linux `_arrayForceCast` crash.**
+        ///   The `shared.cache.get(scope.key, as: State<Value>.self)` call below performs
+        ///   an `Any → State<Value>` dynamic cast inside `Dictionary+Cacheable.swift:18`
+        ///   (`self[key] as? Item`). On Linux, when `Value` is a collection type such as
+        ///   `[Element]`, the Swift runtime's `swift_dynamicCast` path invokes
+        ///   `_arrayForceCast` for the generic parameter, which crashes with a
+        ///   `swift_dynamicCastFailure`. This is a known Swift-on-Linux stdlib/runtime
+        ///   limitation (SR-4049 / swift#40956) affecting `as?` casts from `Any` to
+        ///   generic structs whose generic parameters are array types. A clean fix requires
+        ///   either: (a) replacing `Cache<String, Any>` with a type-index keyed store so
+        ///   `Any` is never the concrete container value type, or (b) filing a Cache library
+        ///   issue to store a type-erased wrapper that avoids the metatype dereference during
+        ///   cast. Until then, `State<[T]>` and `FileState<[T]?>` will crash on Linux when
+        ///   their value is read after being evicted from the in-memory cache.
         @MainActor
         public var value: Value {
             get {
@@ -47,7 +62,7 @@ extension Application {
                                 forKey: scope.key
                             )
                         }
-                        #if (!os(Linux) && !os(Windows))
+                        #if canImport(ObjectiveC)
                         if NSClassFromString("XCTest") == nil {
                             Task { @MainActor in
                                 setValue()
@@ -73,6 +88,7 @@ extension Application {
                     ),
                     forKey: scope.key
                 )
+                shared.notifyChange()
             }
         }
 

Sources/AppState/Application/Types/State/Application+StoredState.swift

@@ -82,6 +82,8 @@ extension Application {
                         userDefaults.set(newValue, forKey: scope.key)
                     }
                 }
+
+                shared.notifyChange()
             }
         }
 

Sources/AppState/Application/Types/State/Application+SyncState.swift

@@ -105,6 +105,8 @@ extension Application {
                         )
                     }
                 }
+
+                shared.notifyChange()
             }
         }
 

Sources/AppState/PropertyWrappers/Dependency/ObservedDependency.swift

@@ -1,4 +1,4 @@
-#if !os(Linux) && !os(Windows)
+#if canImport(SwiftUI)
 import SwiftUI
 
 /// The `@ObservedDependency` property wrapper is a feature provided by AppState, intended to simplify dependency handling throughout your application. It makes it easy to access, share, and manage dependencies in a neat and Swift idiomatic way. It works the same as `@AppDependency`, but comes with the power of the `@ObservedObject` property wrapper.