Updating Documentation (#66)

leogdion · claude · leogdion · commit 068011f610cf · 2025-11-24T14:39:15.000-05:00
* docs: update DocC documentation for v2.0.0 architecture - Add DocC landing pages for SundialKitCombine and SundialKitStream plugins - Update main Documentation.md to reflect v2.0.0 three-layer architecture - Remove deprecated ConnectivityObserver.md and NetworkObserver.md (moved to plugins) - Add .gitignore to exclude .docc-build directories - Mark tasks 9 (Swift Testing migration) and 13 (demo app) as complete 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(docs): add DocC preview script with auto-rebuild Adds preview-docs.sh script to enable local DocC documentation preview with automatic rebuilding on file changes. The script uses xcrun docc preview for serving and fswatch for monitoring Swift source changes, avoiding the need to add swift-docc as a package dependency. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * git subrepo push Packages/SundialKitCombine subrepo: subdir: "Packages/SundialKitCombine" merged: "899c22a" upstream: origin: "git@github.com:brightdigit/SundialKitCombine.git" branch: "v1.0.0" commit: "899c22a" git-subrepo: version: "0.4.9" origin: "https://github.com/Homebrew/brew" commit: "e8b7739de9" * git subrepo push Packages/SundialKitStream subrepo: subdir: "Packages/SundialKitStream" merged: "7bc90df" upstream: origin: "git@github.com:brightdigit/SundialKitStream.git" branch: "v1.0.0" commit: "7bc90df" git-subrepo: version: "0.4.9" origin: "https://github.com/Homebrew/brew" commit: "e8b7739de9" * docs: rewrite DocC overview to focus on use cases - Lead with practical use cases (cross-device communication, network-aware apps) - Add "What Can You Build?" section with real-world examples - Add "Available Packages" section with placeholder links to targets - Remove architectural details from overview (not relevant to new users) - Remove mentions of Heartwitch, Swift 6.1 concurrency details - Focus on developer capabilities rather than technical implementation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * removing enum * docs(docc): fix API examples and add improvement TODOs Major documentation corrections: - Fix NWPathMonitorAdapter → NWPathMonitor (adapter class doesn't exist) - Fix sendMessage(dict) → send(message) to use typed Messagable API - Fix Messagable: init? → init throws with Sendable parameters - Fix BinaryMessagable: binaryData/from → encode/init methods - Reorder sections: explain Messagable/BinaryMessagable before WatchConnectivity - Add typed message receiving examples (typedMessageReceived, typedMessageStream) Improvements: - Add TODO warnings as DocC asides for future enhancements - TODOs cover: explanatory text, default initializers, protocol details Also fixes: - ColorMessageExtensions: serializedData → serializedBytes (correct protobuf API) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs(docc): address TODOs and add NetworkObserver default initializers - Add default init() to NetworkObserver in SundialKitStream and SundialKitCombine - Simplify Network Monitoring section with Quick Start and Advanced subsections - Streamline Type-Safe Messaging section with key behavior as brief note - Improve Binary Messaging section with real protobuf examples and swift-protobuf link - Update WatchConnectivity examples to show both Messagable and BinaryMessagable types - Add message size limit note (65KB) with link to Apple's WatchConnectivity docs - Remove all 9 TODO warnings from Documentation.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs(docc): add DocC documentation and improve preview script Documentation improvements: - Add SundialKitCore.docc with comprehensive package overview - Document all core protocols, types, and error types - Clean up structure by removing redundant content - Add SundialError to Error Types section Script enhancements: - Improve preview-docs.sh with better error handling - Add support for multiple .docc catalogs - Update Makefile with new documentation targets API documentation additions: - Add detailed docs to ActivationState enum - Add comprehensive docs to ConnectivityMessage typealias - Enhance Interfaceable protocol documentation - Expand PathStatus documentation with all cases 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs(docc): enhance documentation with narrative flow and remove advanced sections - Remove Architecture sections (redundant with main SundialKit docs) - Remove Advanced Usage sections (not needed for typical users) - Add Getting Started sections explaining plugin selection - Add introductory text before code examples explaining use cases - Add concluding text after examples summarizing key concepts - Enhance inline documentation for result/context types Changes focus documentation on practical usage patterns and improve readability with better narrative structure. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fixing Makefile for Network and Connectivity * git subrepo push Packages/SundialKitCombine subrepo: subdir: "Packages/SundialKitCombine" merged: "0b8ae65" upstream: origin: "git@github.com:brightdigit/SundialKitCombine.git" branch: "v1.0.0" commit: "0b8ae65" git-subrepo: version: "0.4.9" origin: "https://github.com/Homebrew/brew" commit: "e8b7739de9" * git subrepo push Packages/SundialKitStream subrepo: subdir: "Packages/SundialKitStream" merged: "8234353" upstream: origin: "git@github.com:brightdigit/SundialKitStream.git" branch: "v1.0.0" commit: "8234353" git-subrepo: version: "0.4.9" origin: "https://github.com/Homebrew/brew" commit: "e8b7739de9" * docs(docc): remove MainActor references and transport selection details - Remove @mainactor mentions from SundialKitCombine descriptions - Remove "all updates happen on main thread" explanations - Remove automatic transport selection details from connectivity docs - Preserve actor-based descriptions for SundialKitStream - Simplify plugin comparison focusing on observation patterns 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * git subrepo push Packages/SundialKitCombine subrepo: subdir: "Packages/SundialKitCombine" merged: "cbcd2cc" upstream: origin: "git@github.com:brightdigit/SundialKitCombine.git" branch: "v1.0.0" commit: "cbcd2cc" git-subrepo: version: "0.4.9" origin: "https://github.com/Homebrew/brew" commit: "e8b7739de9" * Fixing CI Unit Test Issues with watchOS and iOS (#67) * fix(connectivity): eliminate observer registration race condition Convert observer management methods to async to fix intermittent CI test failures. ## Problem ConnectivityManager Observer Tests were failing intermittently (62% failure rate) due to race conditions: - addObserver() used nonisolated + unstructured Task pattern - Tests called addObserver() then immediately triggered state changes - Observers weren't registered when notifications fired - Tests timed out after ~35 seconds waiting for events ## Changes - Make addObserver/removeObserver/removeObservers async in protocol - Remove nonisolated modifier and Task wrappers from actor extension - Add await to all test call sites (7 locations) - Pattern now matches NetworkMonitor (already async) ## Impact - Eliminates race condition entirely - Observers guaranteed registered before returning - Tests will pass reliably on iOS/watchOS simulators - Breaking API change (callers must use await) Fixes #<issue-number> 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix(connectivity): eliminate remaining observer notification race conditions **Problem:** Previous fix addressed race in observer registration, but tests still failed on CI (62% failure rate) with 10-second timeouts. Root cause was TWO layers of unstructured Tasks creating race conditions: 1. Delegate handlers (e.g., handleReachabilityChange) used nonisolated + Task 2. observerRegistry.notify() used nonisolated + Task This created a three-layer Task cascade where notifications could fire before observers received them, causing CI timeouts despite passing locally. **Solution:** - Made ObserverRegistry.notify() actor-isolated (removed nonisolated + Task) - Made all notify*() methods in ConnectivityObserverManaging async - Made isolated delegate handlers await notification completion - Made NetworkMonitor.handlePathUpdate() async to match pattern - Updated ObserverRegistry tests to await notify() calls - Removed unnecessary Task.sleep() from tests (proper awaiting eliminates need) **Impact:** - All ConnectivityManagerObserverTests now pass in ~0.055s (previously timed out after 10s) - Tests pass reliably on both iOS and watchOS simulators - Pattern now consistent across Network and Connectivity modules - Breaking API change: notify() now requires await, but only affects internal code **Testing:** - iOS simulator: 7 observer tests pass ✓ - watchOS simulator: 6 observer tests pass ✓ - All existing core and network tests pass ✓ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fixing unneeded async task * test(watchconnectivity): eliminate waitUntil race conditions in observer tests Replace observer notification waits with direct manager state checks to eliminate timing issues. Since MockSession calls delegate methods synchronously and the notification chain is now fully async/await, the manager's state is updated immediately when mock properties change. Changes: - Check manager state directly instead of waiting for observer notifications - Eliminates all waitUntil calls that were timing out on CI - Reduces test time by removing unnecessary delays - Tests now verify manager state rather than observer timing Fixes 6 failing tests on CI (watchOS, Xcode 26.0): - observerReceivesActivationStateChanges - observerReceivesReachabilityChanges - observerReceivesCompanionAppInstalledChanges - observerReceivesPairedStatusChanges - reachabilityUpdatesFromDelegate - multipleObserversReceiveNotifications 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * test(watchconnectivity): add Task.yield() before checking manager state The delegate handlers use nonisolated+Task pattern, which means the Task is unstructured and may not execute immediately when MockSession calls the delegate synchronously. Adding Task.yield() gives the Task scheduler a chance to run the pending Task before we check the manager's state. Changes: - Add await Task.yield() after setting MockSession properties - This allows the unstructured Task in handleReachabilityChange() etc. to run - Ensures manager state is updated before assertions run 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com> * docs(docc): enhance plugin documentation and add new logo - Add comprehensive prose to SundialKitStream documentation - "Why Choose SundialKitStream" section with actor-based benefits - Getting Started with installation instructions - Detailed explanations of network monitoring and WatchConnectivity - SwiftUI integration patterns and architecture benefits - Add comprehensive prose to SundialKitCombine documentation - "Why Choose SundialKitCombine" section with Combine benefits - Getting Started with installation instructions - Advanced Combine patterns and reactive programming examples - SwiftUI integration and @mainactor thread safety - Replace logo across all four DocC packages - Use new Sundial-Base Default logo at 256x256 resolution - Replace logo.svg with logo.png in all Resources directories - Update markdown references in all Documentation.md files - Packages: SundialKitStream, SundialKitCombine, SundialKitNetwork, SundialKitConnectivity 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * git subrepo push Packages/SundialKitCombine subrepo: subdir: "Packages/SundialKitCombine" merged: "0825dc3" upstream: origin: "git@github.com:brightdigit/SundialKitCombine.git" branch: "v1.0.0" commit: "0825dc3" git-subrepo: version: "0.4.9" origin: "https://github.com/Homebrew/brew" commit: "e8b7739de9" * git subrepo push Packages/SundialKitStream subrepo: subdir: "Packages/SundialKitStream" merged: "1c16d63" upstream: origin: "git@github.com:brightdigit/SundialKitStream.git" branch: "v1.0.0" commit: "1c16d63" git-subrepo: version: "0.4.9" origin: "https://github.com/Homebrew/brew" commit: "e8b7739de9" * docs(docc): address PR review feedback - Remove unnecessary @mainactor isolation mentions from both plugins - Add SundialKitCombine and SundialKitStream package dependencies to installation examples - Fix "or/and" wording in SundialKitCombine overview - Move Ping Integration section to Network Monitoring area in SundialKitCombine - Remove "Advanced Combine Patterns" section from SundialKitCombine - Remove "@mainactor and Thread Safety" section from SundialKitCombine - Change "thread safety" to "concurrency safety" in SundialKitStream tagline - Remove "Actor-Based Architecture Benefits" section from SundialKitStream - Remove paragraph about @mainactor annotation in SundialKitStream SwiftUI section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs(docc): add comprehensive Messagable documentation to plugins Add Type-Safe Messaging section to both SundialKitCombine and SundialKitStream: - Messagable protocol documentation with ColorMessage example - BinaryMessagable documentation with Protobuf and custom binary examples - Complete SwiftUI integration examples showing: - SundialKitCombine: @published properties with Combine - SundialKitStream: AsyncStreams with @observable macro - MessageDecoder usage for automatic message routing - Full working examples with color messaging between iPhone and Watch - Important notes about 65KB message size limits This addresses the missing Messagable content that was present in the main SundialKit documentation but missing from the plugin documentation files. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fixing Linting Issues --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/Sources/SundialKitCombine/SundialKitCombine.docc/Documentation.md b/Sources/SundialKitCombine/SundialKitCombine.docc/Documentation.md
@@ -10,7 +10,7 @@ SundialKitCombine provides observers that deliver state updates via @Published p
 
 ### Why Choose SundialKitCombine
 
-If you're building a SwiftUI application or need to support iOS 13+, SundialKitCombine is the perfect choice. It leverages Combine's publisher infrastructure to provide reactive state updates that bind naturally to SwiftUI views. The @Published properties work seamlessly with SwiftUI's observation system, automatically triggering view updates when network or connectivity state changes.
+If you're building a SwiftUI application and need to support iOS 13+, SundialKitCombine is the perfect choice. It leverages Combine's publisher infrastructure to provide reactive state updates that bind naturally to SwiftUI views. The @Published properties work seamlessly with SwiftUI's observation system, automatically triggering view updates when network or connectivity state changes.
 
 **Choose SundialKitCombine when you:**
 - Building SwiftUI applications with reactive data binding
@@ -40,13 +40,14 @@ Add SundialKit to your `Package.swift`:
 
 ```swift
 dependencies: [
-  .package(url: "https://github.com/brightdigit/SundialKit.git", from: "2.0.0")
+  .package(url: "https://github.com/brightdigit/SundialKit.git", from: "2.0.0"),
+  .package(url: "https://github.com/brightdigit/SundialKitCombine.git", from: "1.0.0")
 ],
 targets: [
   .target(
     name: "YourTarget",
     dependencies: [
-      .product(name: "SundialKitCombine", package: "SundialKit"),
+      .product(name: "SundialKitCombine", package: "SundialKitCombine"),
       .product(name: "SundialKitNetwork", package: "SundialKit"),  // For network monitoring
       .product(name: "SundialKitConnectivity", package: "SundialKit")  // For WatchConnectivity
     ]
@@ -56,7 +57,7 @@ targets: [
 
 ## Network Monitoring
 
-Monitor network connectivity changes using the @MainActor-based ``NetworkObserver``. The observer provides @Published properties for network state that automatically update your SwiftUI views, plus Combine publishers for advanced reactive patterns.
+Monitor network connectivity changes using ``NetworkObserver``. The observer provides @Published properties for network state that automatically update your SwiftUI views, plus Combine publishers for advanced reactive patterns.
 
 ### Basic Network Monitoring
 
@@ -124,8 +125,6 @@ struct NetworkStatusView: View {
 }
 ```
 
-Because both `NetworkConnectivityObject` and the observer use @MainActor isolation, all updates happen on the main thread automatically - no manual dispatch needed.
-
 ### Understanding PathStatus
 
 The ``PathStatus`` enum represents the current state of the network path:
@@ -135,44 +134,64 @@ The ``PathStatus`` enum represents the current state of the network path:
 - **`.requiresConnection`** - Network may be available but requires user action (e.g., connecting to WiFi)
 - **`.unknown`** - Initial state before first update
 
-### Advanced Combine Patterns
+### Ping Integration
 
-Because the observer provides Combine publishers, you can use the full power of Combine operators:
+Monitor network connectivity with periodic pings to verify actual internet access beyond path availability:
 
 ```swift
-// Debounce rapid network changes
-observer.$pathStatus
-  .debounce(for: .seconds(1), scheduler: DispatchQueue.main)
-  .sink { status in
-    print("Stable network status: \(status)")
-  }
-  .store(in: &cancellables)
+import SundialKitCombine
+import SundialKitNetwork
+
+struct IpifyPing: NetworkPing, Sendable {
+  typealias StatusType = String?
+
+  let session: URLSession
+  let timeInterval: TimeInterval
 
-// Combine multiple signals
-Publishers.CombineLatest(observer.$isExpensive, observer.$isConstrained)
-  .sink { isExpensive, isConstrained in
-    if isExpensive || isConstrained {
-      print("Network conditions suggest reducing data usage")
+  func shouldPing(onStatus status: PathStatus) -> Bool {
+    switch status {
+    case .unknown, .unsatisfied:
+      return false
+    case .requiresConnection, .satisfied:
+      return true
     }
   }
-  .store(in: &cancellables)
 
-// React to specific transitions
-observer.$pathStatus
-  .removeDuplicates()
-  .sink { status in
-    if status == .satisfied {
-      print("Network became available - sync data")
-    }
+  func onPing(_ closure: @escaping (String?) -> Void) {
+    let url = URL(string: "https://api.ipify.org")!
+    session.dataTask(with: url) { data, _, _ in
+      closure(data.flatMap { String(data: $0, encoding: .utf8) })
+    }.resume()
   }
-  .store(in: &cancellables)
+}
+
+@MainActor
+class PingNetworkObject: ObservableObject {
+  let observer: NetworkObserver<NWPathMonitorAdapter, IpifyPing>
+
+  @Published var ipAddress: String?
+
+  init() {
+    observer = NetworkObserver(
+      monitor: NWPathMonitorAdapter(),
+      ping: IpifyPing(session: .shared, timeInterval: 10.0)
+    )
+
+    observer.$pingStatus
+      .assign(to: &$ipAddress)
+  }
+
+  func start() {
+    observer.start()
+  }
+}
 ```
 
-This reactive approach makes it easy to build sophisticated network-aware behaviors.
+The ping verifies actual internet connectivity by making a real network request. This catches cases where the network path is technically satisfied but internet access is blocked (captive portals, DNS issues, etc.).
 
 ## WatchConnectivity Communication
 
-Communicate between iPhone and Apple Watch using the @MainActor-based ``ConnectivityObserver``. The observer provides @Published properties for session state and Combine publishers for incoming messages, making WatchConnectivity straightforward in SwiftUI apps.
+Communicate between iPhone and Apple Watch using ``ConnectivityObserver``. The observer provides @Published properties for session state and Combine publishers for incoming messages, making WatchConnectivity straightforward in SwiftUI apps.
 
 ### Session Activation and State
 
@@ -300,71 +319,216 @@ observer.messageReceived
 
 Combine's operators give you fine-grained control over how messages are processed and delivered to your app.
 
-## Ping Integration
+## Type-Safe Messaging
 
-Monitor network connectivity with periodic pings to verify actual internet access beyond path availability:
+SundialKitConnectivity provides two protocols for defining custom message types: ``Messagable`` for dictionary-based messages and ``BinaryMessagable`` for efficient binary serialization. Both work seamlessly with ConnectivityObserver to provide compile-time type safety for your iPhone-Apple Watch communication.
+
+### Dictionary-Based Messages with Messagable
+
+The ``Messagable`` protocol enables type-safe message encoding and decoding. Instead of working with raw dictionaries, you define custom message types that are automatically serialized and deserialized:
 
 ```swift
-import SundialKitCombine
-import SundialKitNetwork
+import SundialKitConnectivity
 
-struct IpifyPing: NetworkPing, Sendable {
-  typealias StatusType = String?
+struct ColorMessage: Messagable {
+  static let key = "color"  // Identifier for this message type
 
-  let session: URLSession
-  let timeInterval: TimeInterval
+  let red: Double
+  let green: Double
+  let blue: Double
 
-  func shouldPing(onStatus status: PathStatus) -> Bool {
-    switch status {
-    case .unknown, .unsatisfied:
-      return false
-    case .requiresConnection, .satisfied:
-      return true
+  init(red: Double, green: Double, blue: Double) {
+    self.red = red
+    self.green = green
+    self.blue = blue
+  }
+
+  init(from parameters: [String: any Sendable]) throws {
+    guard let red = parameters["red"] as? Double,
+          let green = parameters["green"] as? Double,
+          let blue = parameters["blue"] as? Double else {
+      throw SerializationError.missingField("color components")
     }
+    self.red = red
+    self.green = green
+    self.blue = blue
   }
 
-  func onPing(_ closure: @escaping (String?) -> Void) {
-    let url = URL(string: "https://api.ipify.org")!
-    session.dataTask(with: url) { data, _, _ in
-      closure(data.flatMap { String(data: $0, encoding: .utf8) })
-    }.resume()
+  func parameters() -> [String: any Sendable] {
+    ["red": red, "green": green, "blue": blue]
   }
 }
+```
+
+The `key` property identifies the message type, allowing the receiver to route it to the correct handler. The `parameters()` method converts your type to a dictionary, and the `init(from:)` initializer reconstructs it from received data.
+
+### Binary Serialization with BinaryMessagable
+
+For larger datasets or complex data structures, ``BinaryMessagable`` provides efficient binary serialization. This approach works seamlessly with Protocol Buffers, MessagePack, or any custom binary format:
+
+```swift
+import SundialKitConnectivity
+import SwiftProtobuf
+
+// Extend your Protobuf-generated type
+extension UserProfile: BinaryMessagable {
+  // key defaults to "UserProfile" (type name)
+
+  public init(from data: Data) throws {
+    try self.init(serializedData: data)  // SwiftProtobuf decoder
+  }
+
+  public func encode() throws -> Data {
+    try serializedData()  // SwiftProtobuf encoder
+  }
+
+  // init(from parameters:) and parameters() auto-implemented!
+}
+```
+
+**Custom binary format example:**
+
+```swift
+struct TemperatureReading: BinaryMessagable {
+  let celsius: Float
+  let timestamp: UInt64
+
+  init(celsius: Float, timestamp: UInt64) {
+    self.celsius = celsius
+    self.timestamp = timestamp
+  }
+
+  public init(from data: Data) throws {
+    guard data.count == 12 else {  // 4 + 8 bytes
+      throw SerializationError.invalidDataSize
+    }
+    celsius = data.withUnsafeBytes { $0.load(as: Float.self) }
+    timestamp = data.dropFirst(4).withUnsafeBytes { $0.load(as: UInt64.self) }
+  }
+
+  public func encode() throws -> Data {
+    var data = Data()
+    withUnsafeBytes(of: celsius) { data.append(contentsOf: $0) }
+    withUnsafeBytes(of: timestamp) { data.append(contentsOf: $0) }
+    return data
+  }
+}
+```
+
+### SwiftUI Integration with Type-Safe Messages
+
+Here's a complete example showing how to use custom message types with SwiftUI and Combine:
+
+```swift
+import SwiftUI
+import SundialKitCombine
+import SundialKitConnectivity
+import Combine
 
 @MainActor
-class PingNetworkObject: ObservableObject {
-  let observer: NetworkObserver<NWPathMonitorAdapter, IpifyPing>
+class WatchMessenger: ObservableObject {
+  let observer: ConnectivityObserver
 
-  @Published var ipAddress: String?
+  @Published var receivedColor: Color?
+  @Published var isReachable: Bool = false
+  @Published var activationState: ActivationState = .notActivated
+
+  private var cancellables = Set<AnyCancellable>()
 
   init() {
-    observer = NetworkObserver(
-      monitor: NWPathMonitorAdapter(),
-      ping: IpifyPing(session: .shared, timeInterval: 10.0)
+    // Create observer with message decoder supporting multiple types
+    observer = ConnectivityObserver(
+      messageDecoder: MessageDecoder(messagableTypes: [
+        ColorMessage.self,
+        TemperatureReading.self
+      ])
     )
 
-    observer.$pingStatus
-      .assign(to: &$ipAddress)
+    // Bind session state
+    observer.$isReachable
+      .assign(to: &$isReachable)
+
+    observer.$activationState
+      .assign(to: &$activationState)
+
+    // Listen for typed messages
+    observer.typedMessageReceived
+      .sink { [weak self] message in
+        if let colorMessage = message as? ColorMessage {
+          self?.receivedColor = Color(
+            red: colorMessage.red,
+            green: colorMessage.green,
+            blue: colorMessage.blue
+          )
+        } else if let temp = message as? TemperatureReading {
+          print("Temperature: \(temp.celsius)°C at \(temp.timestamp)")
+        }
+      }
+      .store(in: &cancellables)
   }
 
-  func start() {
-    observer.start()
+  func activate() throws {
+    try observer.activate()
+  }
+
+  func sendColor(red: Double, green: Double, blue: Double) async throws {
+    let message = ColorMessage(red: red, green: green, blue: blue)
+    let result = try await observer.send(message)
+    print("Sent via: \(result.context)")
   }
 }
-```
 
-The ping verifies actual internet connectivity by making a real network request. This catches cases where the network path is technically satisfied but internet access is blocked (captive portals, DNS issues, etc.).
+struct WatchColorView: View {
+  @StateObject var messenger = WatchMessenger()
+
+  var body: some View {
+    VStack(spacing: 20) {
+      Text("WatchConnectivity")
+        .font(.headline)
+
+      Text("Session: \(messenger.activationState.description)")
+      Text("Reachable: \(messenger.isReachable ? "Yes" : "No")")
+
+      if let color = messenger.receivedColor {
+        Rectangle()
+          .fill(color)
+          .frame(width: 100, height: 100)
+          .cornerRadius(10)
 
-### @MainActor and Thread Safety
+        Text("Received Color")
+          .font(.caption)
+      }
+
+      Button("Send Red") {
+        Task {
+          try? await messenger.sendColor(red: 1.0, green: 0.0, blue: 0.0)
+        }
+      }
+      .disabled(!messenger.isReachable)
 
-All SundialKitCombine observers use @MainActor isolation, ensuring:
+      Button("Send Blue") {
+        Task {
+          try? await messenger.sendColor(red: 0.0, green: 0.0, blue: 1.0)
+        }
+      }
+      .disabled(!messenger.isReachable)
+    }
+    .padding()
+    .onAppear {
+      try? messenger.activate()
+    }
+  }
+}
+```
 
-- **Main Thread Updates**: All @Published property changes happen on the main thread automatically
-- **SwiftUI Safety**: No need to manually dispatch to main queue before updating UI
-- **Compile-Time Guarantees**: Swift 6.1 strict concurrency prevents threading issues at compile time
-- **Zero @unchecked Sendable**: Everything is properly isolated without workarounds
+This example demonstrates:
+- Creating a `MessageDecoder` with multiple custom message types
+- Binding `@Published` properties from the observer to SwiftUI state
+- Receiving typed messages and converting them to SwiftUI views
+- Sending type-safe messages from button actions
+- Automatic UI updates when messages arrive or session state changes
 
-This makes it safe to bind observer properties directly to SwiftUI views without additional synchronization code.
+> Important: Dictionary-based messages have a size limit of approximately 65KB. For larger data, use ``BinaryMessagable`` for efficient serialization or consider file transfer methods.
 
 ## Topics
 
