feat(companion): mirror episode context

Author: LamPPKK

README.md

@@ -35,7 +35,7 @@ The two native mobile apps keep platform-specific UI and storage while sharing t
 - **Connect TMDb safely** through browser approval or TV QR without entering a password in SmartMovie. Browse paginated Movie/TV account recommendations, rate Movie/TV/Episode titles, and manage account library/lists with durable offline mutation retry.
 - **Manage mixed custom lists** by loading every list page, editing metadata, paging through Movie/TV contents, searching the catalog, and adding or removing titles with restart-safe optimistic synchronization.
 - **Build a local-first library** with independent Favorite and Watchlist actions. SwiftData keeps both readable offline; private CloudKit remains an Apple storage option.
-- **Move between Apple devices naturally** with five adaptive destinations, keyboard/pointer support, focus-driven TV navigation, multi-window Mac/visionOS details, and a safe Apple Watch companion remote.
+- **Move between Apple devices naturally** with five adaptive destinations, keyboard/pointer support, focus-driven TV navigation, multi-window Mac/visionOS details, and an Apple Watch companion that mirrors a safe title or exact episode and opens it back on iPhone.
 - **Use the app in six languages**: English, Vietnamese, Japanese, Korean, Simplified Chinese, and Traditional Chinese.
 - **Rely on accessible defaults** including Dynamic Type, VoiceOver labels, Increase Contrast, Reduce Motion, and platform-native focus behavior.
 
@@ -67,7 +67,7 @@ The universal app expands shelves and content density on iPad while retaining th
 <table>
   <tr>
     <td width="72%" align="center"><strong>Apple TV</strong><br><sub>10-foot catalog with focus and Siri Remote navigation</sub></td>
-    <td width="28%" align="center"><strong>Apple Watch</strong><br><sub>Remote for the title open on the paired iPhone</sub></td>
+    <td width="28%" align="center"><strong>Apple Watch</strong><br><sub>Safe title/episode context with exact-detail iPhone handoff</sub></td>
   </tr>
   <tr>
     <td align="center"><img src="docs/images/screenshots/apple-tv-home.png" alt="SmartMovie Home on Apple TV" width="760"></td>
@@ -86,7 +86,7 @@ Screenshots come from the real SwiftUI targets using deterministic local fixture
 | Mac Catalyst | macOS compatible with the iOS 17 target | Shared universal app with expanded navigation | `SmartMovie` |
 | Apple TV | tvOS 17 | 10-foot layout, focus-driven shelves, Siri Remote/D-pad navigation, and trailer handoff | `SmartMovieTV` |
 | Apple Vision Pro | visionOS 1 | Resizable catalog window and separate title-detail windows | `SmartMovieVision` |
-| Apple Watch | watchOS 10 | Non-standalone WatchConnectivity companion remote | `SmartMovieWatch` |
+| Apple Watch | watchOS 10 | Non-standalone WatchConnectivity companion for safe title/episode context and phone handoff | `SmartMovieWatch` |
 | Native Mac | macOS 14 | `NavigationSplitView`, menu commands, keyboard shortcuts, and multi-window details | `SmartMovieNativeMac` |
 
 The universal Apple product uses bundle ID `LamNDT.SmartMovie`, the embedded watch companion uses `LamNDT.SmartMovie.watchkitapp`, and the native Mac product uses `LamNDT.SmartMovie.NativeMac`. The catalog products share the private CloudKit container `iCloud.LamNDT.SmartMovie`.
@@ -203,7 +203,7 @@ cd ../..
 ./scripts/verify-release.sh
 ```
 
-The current verified local baseline contains 60 Swift tests and 92 Worker tests. Coverage includes canonical `/v1` and `/v2` fixture decoding, typed regional release/content-rating, Movie/TV alternative-title and translation metadata, configured capability/fixture equality, fail-closed browser/TV account rollout, malformed broker configuration and return-URI allowlists, cold-start callback deferral, stale completion invalidation, durable outbox isolation, capability-gated Advanced Discover and Profile provider regions with a fail-closed `/v1` fallback, complete Movie/TV Discover queries and regional provider configuration, External ID and Credit Detail source/path mapping, account recommendations, normalized/paginated custom mixed lists, restart-safe pending item snapshots, explicit adult age confirmation, six-digit PIN validation, five-attempt lockout, local adult filtering and in-flight request invalidation, metadata/item mutations, normalized person/title credit links, unknown and missing nullable fields, success/error schema validation, repeatable D1 migrations, encryption/callback/CSRF controls, durable idempotency, TMDb Changes pagination/backlog recovery, invalid cursor recovery, verified changing-page-count fallback, D1 parameter-bound chunking, monotonic revision and cache-bypass behavior, retries, cancellation, pagination, and data behavior without live personal credentials.
+The current verified local baseline contains 61 Swift tests and 92 Worker tests. Coverage includes canonical `/v1` and `/v2` fixture decoding, typed regional release/content-rating, Movie/TV alternative-title and translation metadata, configured capability/fixture equality, fail-closed browser/TV account rollout, malformed broker configuration and return-URI allowlists, cold-start callback deferral, stale completion invalidation, durable outbox isolation, capability-gated Advanced Discover and Profile provider regions with a fail-closed `/v1` fallback, complete Movie/TV Discover queries and regional provider configuration, External ID and Credit Detail source/path mapping, account recommendations, normalized/paginated custom mixed lists, restart-safe pending item snapshots, explicit adult age confirmation, six-digit PIN validation, five-attempt lockout, local adult filtering and in-flight request invalidation, metadata/item mutations, normalized person/title credit links, exact episode companion context, unknown and missing nullable fields, success/error schema validation, repeatable D1 migrations, encryption/callback/CSRF controls, durable idempotency, TMDb Changes pagination/backlog recovery, invalid cursor recovery, verified changing-page-count fallback, D1 parameter-bound chunking, monotonic revision and cache-bypass behavior, retries, cancellation, pagination, and data behavior without live personal credentials.
 
 CI independently builds and analyzes iOS, iPad/Catalyst, tvOS, native macOS, watchOS, and visionOS, then installs and launches the iOS app in Simulator. Read [Testing](docs/TESTING.md) for destination-specific commands and the manual device matrix.
 

SmartMovie/Apps/Universal/PhoneWatchRemoteController.swift

@@ -12,15 +12,23 @@ final class PhoneWatchRemoteController: NSObject, WatchRemoteSession {
     private struct RemoteCommand: Sendable {
         let action: WatchRemoteAction
         let libraryKey: String
+        let contextKey: String?
     }
 
     private enum Key {
         static let action = "action"
         static let artworkURL = "artworkURL"
+        static let cleared = "cleared"
+        static let contextKey = "contextKey"
+        static let contextKind = "contextKind"
+        static let episodeNumber = "episodeNumber"
         static let favorite = "favorite"
         static let hasTrailer = "hasTrailer"
         static let libraryKey = "libraryKey"
+        static let libraryActionsAvailable = "libraryActionsAvailable"
         static let mediaType = "mediaType"
+        static let seasonNumber = "seasonNumber"
+        static let seriesTitle = "seriesTitle"
         static let success = "ok"
         static let rating = "rating"
         static let title = "title"
@@ -47,29 +55,46 @@ final class PhoneWatchRemoteController: NSObject, WatchRemoteSession {
         publishCurrentContext()
     }
 
+    func clear(contextKey: String) {
+        guard currentContext?.contextKey == contextKey else { return }
+        currentContext = nil
+        publishCurrentContext()
+    }
+
     private func publishCurrentContext() {
-        guard let session, session.activationState == .activated, let currentContext else { return }
+        guard let session, session.activationState == .activated else { return }
+        let applicationContext = currentContext.map { payload(for: $0) } ?? [Key.cleared: true]
         do {
-            try session.updateApplicationContext(payload(for: currentContext))
+            try session.updateApplicationContext(applicationContext)
         } catch {
             // The next detail update or activation callback retries with fresh state.
         }
     }
 
     private func payload(for context: WatchRemoteContext) -> [String: Any] {
+        let episode = context.episode
         var payload: [String: Any] = [
-            Key.favorite: context.isFavorite,
-            Key.hasTrailer: context.hasTrailer,
+            Key.contextKey: context.contextKey,
+            Key.contextKind: episode == nil ? "title" : "episode",
+            Key.favorite: context.supportsLibraryActions && context.isFavorite,
+            Key.hasTrailer: episode == nil && context.hasTrailer,
             Key.libraryKey: context.title.libraryKey,
-            Key.mediaType: context.title.mediaType.rawValue,
-            Key.rating: context.title.voteAverage,
-            Key.title: context.title.displayTitle,
-            Key.watchlist: context.isWatchlisted
+            Key.libraryActionsAvailable: context.supportsLibraryActions,
+            Key.mediaType: episode == nil ? context.title.mediaType.rawValue : "episode",
+            Key.rating: episode?.voteAverage ?? context.title.voteAverage,
+            Key.title: episode?.name ?? context.title.displayTitle,
+            Key.watchlist: context.supportsLibraryActions && context.isWatchlisted
         ]
         if let artworkURL = context.artworkURL?.absoluteString {
             payload[Key.artworkURL] = artworkURL
         }
-        if let year = context.title.releaseYear {
+        if let episode {
+            payload[Key.episodeNumber] = episode.episodeNumber
+            payload[Key.seasonNumber] = episode.seasonNumber
+            payload[Key.seriesTitle] = context.title.displayTitle
+        }
+        let year = episode?.airDate.map { String($0.prefix(4)) } ?? context.title.releaseYear
+        if let year {
             payload[Key.year] = year
         }
         return payload
@@ -79,19 +104,28 @@ final class PhoneWatchRemoteController: NSObject, WatchRemoteSession {
         guard
             let command,
             let context = currentContext,
-            command.libraryKey == context.title.libraryKey
+            command.contextKey == context.contextKey || (
+                command.contextKey == nil && command.libraryKey == context.title.libraryKey
+            )
         else {
             return [Key.success: false]
         }
 
         switch command.action {
         case .openDetails:
-            coordinator.present(title: context.title, playsTrailer: false)
+            if let episode = context.episode {
+                coordinator.presentEpisode(series: context.title, episode: episode)
+            } else {
+                coordinator.present(title: context.title, playsTrailer: false)
+            }
         case .playTrailer:
+            guard context.episode == nil, context.hasTrailer else { return [Key.success: false] }
             coordinator.present(title: context.title, playsTrailer: true)
         case .toggleFavorite:
+            guard context.supportsLibraryActions else { return [Key.success: false] }
             guard toggle(.favorites, context: context) else { return [Key.success: false] }
         case .toggleWatchlist:
+            guard context.supportsLibraryActions else { return [Key.success: false] }
             guard toggle(.watchlist, context: context) else { return [Key.success: false] }
         }
         return replyPayload()
@@ -102,6 +136,7 @@ final class PhoneWatchRemoteController: NSObject, WatchRemoteSession {
             try library.toggle(context.title, in: collection)
             let refreshedContext = WatchRemoteContext(
                 title: context.title,
+                episode: context.episode,
                 artworkURL: context.artworkURL,
                 isFavorite: try library.contains(context.title, in: .favorites),
                 isWatchlisted: try library.contains(context.title, in: .watchlist),
@@ -162,7 +197,11 @@ extension PhoneWatchRemoteController: WCSessionDelegate {
             let action = WatchRemoteAction(rawValue: rawAction),
             let libraryKey = message[Key.libraryKey] as? String
         else { return nil }
-        return RemoteCommand(action: action, libraryKey: libraryKey)
+        return RemoteCommand(
+            action: action,
+            libraryKey: libraryKey,
+            contextKey: message[Key.contextKey] as? String
+        )
     }
 }
 #endif

SmartMovie/Apps/Watch/Localizable.xcstrings

@@ -1,6 +1,15 @@
 {
   "sourceLanguage" : "en",
   "strings" : {
+    "EPISODE" : {
+      "localizations" : {
+        "ja" : { "stringUnit" : { "state" : "translated", "value" : "エピソード" } },
+        "ko" : { "stringUnit" : { "state" : "translated", "value" : "에피소드" } },
+        "vi" : { "stringUnit" : { "state" : "translated", "value" : "TẬP PHIM" } },
+        "zh-Hans" : { "stringUnit" : { "state" : "translated", "value" : "剧集" } },
+        "zh-Hant" : { "stringUnit" : { "state" : "translated", "value" : "集數" } }
+      }
+    },
     "Favorite" : {
       "localizations" : {
         "ja" : { "stringUnit" : { "state" : "translated", "value" : "お気に入り" } },
@@ -55,6 +64,15 @@
         "zh-Hant" : { "stringUnit" : { "state" : "translated", "value" : "在 iPhone 上開啟一個影視項目即可開始控制。" } }
       }
     },
+    "Open a title or episode on your iPhone to start controlling it." : {
+      "localizations" : {
+        "ja" : { "stringUnit" : { "state" : "translated", "value" : "iPhoneで作品またはエピソードを開くと操作を開始できます。" } },
+        "ko" : { "stringUnit" : { "state" : "translated", "value" : "iPhone에서 작품이나 에피소드를 열어 제어를 시작하세요." } },
+        "vi" : { "stringUnit" : { "state" : "translated", "value" : "Mở một tựa phim hoặc tập phim trên iPhone để bắt đầu điều khiển." } },
+        "zh-Hans" : { "stringUnit" : { "state" : "translated", "value" : "在 iPhone 上打开影视条目或剧集即可开始控制。" } },
+        "zh-Hant" : { "stringUnit" : { "state" : "translated", "value" : "在 iPhone 上開啟影視項目或集數即可開始控制。" } }
+      }
+    },
     "Open iPhone app" : {
       "localizations" : {
         "ja" : { "stringUnit" : { "state" : "translated", "value" : "iPhoneアプリを開く" } },

SmartMovie/Apps/Watch/WatchRemoteModel.swift

@@ -5,12 +5,18 @@ import WatchKit
 
 struct WatchRemoteTitle: Equatable, Sendable {
     let libraryKey: String
+    let contextKey: String
+    let contextKind: String
     let title: String
     let mediaType: String
+    let seriesTitle: String?
+    let seasonNumber: Int?
+    let episodeNumber: Int?
     let year: String?
     let artworkURL: URL?
     let rating: Double
     let hasTrailer: Bool
+    let libraryActionsAvailable: Bool
     var isFavorite: Bool
     var isWatchlisted: Bool
 }
@@ -28,10 +34,17 @@ final class WatchRemoteModel: NSObject {
     private enum Key {
         static let action = "action"
         static let artworkURL = "artworkURL"
+        static let cleared = "cleared"
+        static let contextKey = "contextKey"
+        static let contextKind = "contextKind"
+        static let episodeNumber = "episodeNumber"
         static let favorite = "favorite"
         static let hasTrailer = "hasTrailer"
         static let libraryKey = "libraryKey"
+        static let libraryActionsAvailable = "libraryActionsAvailable"
         static let mediaType = "mediaType"
+        static let seasonNumber = "seasonNumber"
+        static let seriesTitle = "seriesTitle"
         static let success = "ok"
         static let rating = "rating"
         static let title = "title"
@@ -80,6 +93,7 @@ final class WatchRemoteModel: NSObject {
         }
         let message: [String: Any] = [
             Key.action: action.rawValue,
+            Key.contextKey: currentTitle.contextKey,
             Key.libraryKey: currentTitle.libraryKey
         ]
         session.sendMessage(message) { [weak self] reply in
@@ -119,12 +133,18 @@ final class WatchRemoteModel: NSObject {
 
         return WatchRemoteTitle(
             libraryKey: libraryKey,
+            contextKey: context[Key.contextKey] as? String ?? libraryKey,
+            contextKind: context[Key.contextKind] as? String ?? "title",
             title: title,
             mediaType: mediaType,
+            seriesTitle: context[Key.seriesTitle] as? String,
+            seasonNumber: context[Key.seasonNumber] as? Int,
+            episodeNumber: context[Key.episodeNumber] as? Int,
             year: context[Key.year] as? String,
             artworkURL: (context[Key.artworkURL] as? String).flatMap(URL.init(string:)),
             rating: context[Key.rating] as? Double ?? 0,
             hasTrailer: context[Key.hasTrailer] as? Bool ?? false,
+            libraryActionsAvailable: context[Key.libraryActionsAvailable] as? Bool ?? true,
             isFavorite: context[Key.favorite] as? Bool ?? false,
             isWatchlisted: context[Key.watchlist] as? Bool ?? false
         )
@@ -138,10 +158,14 @@ extension WatchRemoteModel: WCSessionDelegate {
         error: (any Error)?
     ) {
         let reachable = activationState == .activated && session.isReachable
-        let receivedTitle = Self.decode(context: session.receivedApplicationContext)
+        let applicationContext = session.receivedApplicationContext
+        let receivedTitle = Self.decode(context: applicationContext)
+        let shouldClear = applicationContext[Key.cleared] as? Bool == true
         Task { @MainActor [weak self] in
             self?.isReachable = reachable
-            if let receivedTitle {
+            if shouldClear {
+                self?.currentTitle = nil
+            } else if let receivedTitle {
                 self?.currentTitle = receivedTitle
             }
         }
@@ -156,8 +180,11 @@ extension WatchRemoteModel: WCSessionDelegate {
 
     nonisolated func session(_ session: WCSession, didReceiveApplicationContext applicationContext: [String: Any]) {
         let receivedTitle = Self.decode(context: applicationContext)
+        let shouldClear = applicationContext[Key.cleared] as? Bool == true
         Task { @MainActor [weak self] in
-            if let receivedTitle {
+            if shouldClear {
+                self?.currentTitle = nil
+            } else if let receivedTitle {
                 self?.currentTitle = receivedTitle
             }
         }