chore(docs): update code docs

Author: jellyrock[bot]

docs/components_ItemDetails.bs.html

@@ -367,6 +367,76 @@
   displayToast(translate(translationKeys.ErrorFailedToUpdateFavorite), "error")
 end sub
 
+' callFunc entry — toggles the watched/played state of the current item. Invoked from main.bs's
+' button router; Movie/Episode call it directly, while Series route through the "mark all
+' episodes" confirmation dialog first (main.bs keeps that dialog routing and re-invokes this on
+' confirm — #550 sgRouter territory). Because callFunc rendezvouses to this render-thread-owned
+' node, the body (and the fetchAsync().then() promise delivery + auto-abandon) runs on this
+' component's render thread, where the named-observer adapter works. This is the deferred twin of
+' toggleFavorite() — the Phase-3c "main thread → render thread delegation" pattern (see
+' docs/dev/promises.md). It moves the LAST raw submitApiRequest + isDone flow off main.bs's god-loop.
+sub toggleWatched()
+  watchedButton = m.top.findNode("watchedButton")
+  item = m.top.itemContent
+  if not (isValid(item) and isValidAndNotEmpty(item.id) and isValid(watchedButton)) then return
+  if watchedButton.isLoading then return ' already in-flight
+
+  isSeries = (item.type = "Series")
+  ' Read the desired state from the button (writing itemContent would trigger a full rebuild).
+  newState = not watchedButton.isButtonSelected
+  if newState
+    req = GetApi().BuildMarkPlayedRequest(item.id)
+  else
+    req = GetApi().BuildUnmarkPlayedRequest(item.id)
+  end if
+  watchedButton.isLoading = true
+
+  ' Show the resume button as loading while the toggle is in flight: always for a Series (its
+  ' next-up episode is re-fetched on success), and on mark-watched for a Movie/Episode (its now
+  ' stale resume button is removed on success).
+  if isSeries or newState
+    resumeButton = m.top.findNode("resumeButton")
+    if isValid(resumeButton) then resumeButton.isLoading = true
+  end if
+
+  ' Carry the button + intended state + itemType through the promise context (no closures in BS).
+  promises.chain(fetchAsync(req, "watchedToggle-" + item.id), { button: watchedButton, newState: newState, isSeries: isSeries }).then(sub(res as object, ctx as object)
+    ok = res.ok
+    ' Debug error injection — compiled out in production (bs_const=debug=false).
+    #if debug
+      if isValid(m.global.debug) and m.global.debug.shouldForceWatchedFail then ok = false
+    #end if
+    if ok
+      ctx.button.isButtonSelected = ctx.newState
+      if ctx.isSeries
+        ' Series: re-fetch next-up episode (may change or disappear).
+        m.top.refreshResumeData = not m.top.refreshResumeData
+      else if ctx.newState
+        ' Non-Series marking watched: server clears playback position — drop the stale resume button.
+        removeResumeButtonWithFocus(m.top.findNode("resumeButton"))
+      end if
+    else
+      ' 4xx/5xx resolve under the error contract — the server rejected the change.
+      onWatchedToggleFailed(ctx.button, ctx.newState)
+    end if
+    ctx.button.isLoading = false
+  end sub).catch(sub(err as object, ctx as object)
+    ' Transport failure / timeout / pool-unavailable — the request never completed.
+    m.log.warn("watched toggle failed", err.reason)
+    onWatchedToggleFailed(ctx.button, ctx.newState)
+    ctx.button.isLoading = false
+  end sub)
+end sub
+
+' Reverts the watched button to its pre-press state, clears the resume button's loading
+' state, and surfaces an error toast.
+sub onWatchedToggleFailed(watchedButton as object, attemptedState as boolean)
+  if isValid(watchedButton) then watchedButton.isButtonSelected = not attemptedState
+  resumeButton = m.top.findNode("resumeButton")
+  if isValid(resumeButton) then resumeButton.isLoading = false
+  displayToast(translate(translationKeys.ErrorFailedToUpdateWatchedStatus), "error")
+end sub
+
 ' Triggered by refreshResumeData field toggle (watched toggle on Series).
 ' Re-fetches ONLY the next-up/resume episode — no full rebuild, no setupButtons().
 ' The existing onNextUpEpisodeChanged() handles adding/removing/updating the resume button.

docs/data/search.json

@@ -192,11 +192,6 @@
       if isValid(task) and task.subtype() = "RecordProgramTask"
         handleRecordResult(task)
       end if
-    else if isNodeEvent(msg, "isDone")
-      resultNode = msg.getRoSGNode()
-      if isValid(resultNode) and resultNode.isSameNode(m.watchedResultNode)
-        handleWatchedToggleDone()
-      end if
     else if isNodeEvent(msg, "selectedItem")
       ' If you select a library from ANYWHERE, follow this flow
       selectedItem = msg.getData()
@@ -540,55 +535,29 @@
         else if btn.id = "watchedButton"
           item = group.itemContent
           if isValid(item) and isValidAndNotEmpty(item.id)
-            ' Series: confirm before marking all episodes watched/unwatched (can affect hundreds of episodes)
+            ' Series: confirm before marking all episodes watched/unwatched (can affect hundreds of
+            ' episodes). The dialog routing stays here (#550 sgRouter territory); the fetch itself is
+            ' delegated to ItemDetails.toggleWatched() on confirm (see the isDataReturned handler).
             if item.type = "Series"
               watchedButton = group.findNode("watchedButton")
-              m.pendingWatchedItemId = item.id
               ' Read current state from button — writing to itemContent triggers a full rebuild
-              m.pendingWatchedIsCurrentlyWatched = isValid(watchedButton) and watchedButton.isButtonSelected
-              if m.pendingWatchedIsCurrentlyWatched
+              isCurrentlyWatched = isValid(watchedButton) and watchedButton.isButtonSelected
+              if isCurrentlyWatched
                 confirmMsg = translate(translationKeys.MessageMarkAllEpisodesInThisSeries)
                 confirmBtn = translate(translationKeys.ButtonMarkUnwatched)
               else
                 confirmMsg = translate(translationKeys.MessageMarkAllEpisodesInThisSeries2)
                 confirmBtn = translate(translationKeys.ButtonMarkWatched)
               end if
+              m.pendingWatchedConfirmation = true
               m.global.sceneManager.callFunc("showConfirmationDialog", translate(translationKeys.LabelWatched), [confirmMsg], [translate(translationKeys.ButtonCancel), confirmBtn])
             else
-              watchedButton = group.findNode("watchedButton")
-              if isValid(watchedButton) and watchedButton.isLoading then continue while ' Already in-flight
-              ' Read current state from button — writing to itemContent triggers a full rebuild
-              isCurrentlyWatched = isValid(watchedButton) and watchedButton.isButtonSelected
-              if isCurrentlyWatched
-                req = GetApi().BuildUnmarkPlayedRequest(item.id)
-              else
-                req = GetApi().BuildMarkPlayedRequest(item.id)
-              end if
-              newWatchedState = not isCurrentlyWatched
-              if isValid(watchedButton) then watchedButton.isLoading = true
-              ' Set resume button to loading while we wait for async response
-              if newWatchedState
-                resumeButton = group.findNode("resumeButton")
-                if isValid(resumeButton) then resumeButton.isLoading = true
-              end if
-              resultNode = submitApiRequest(req, "watchedToggle")
-              if isValid(resultNode)
-                m.watchedResultNode = resultNode
-                m.pendingWatchedButton = watchedButton
-                m.pendingWatchedNewState = newWatchedState
-                m.pendingWatchedItemType = item.type
-                m.watchedResultNode.observeField("isDone", m.port)
-              else
-                ' Pool not ready — fall back to fire-and-forget + direct update
-                SubmitSideEffect(req)
-                if isValid(watchedButton)
-                  watchedButton.isButtonSelected = newWatchedState
-                  watchedButton.isLoading = false
-                end if
-                ' Remove stale resume button when marking as watched
-                if newWatchedState
-                  removeResumeButtonFromGroup(group)
-                end if
+              ' Movie/Episode: toggle immediately on the active screen's render-thread method
+              ' (callFunc rendezvouses there, where the toggle runs as a promise). The in-flight
+              ' guard, optimistic state, stale-resume removal, and error contract all live in
+              ' ItemDetails.toggleWatched().
+              if isValid(group)
+                group.callFunc("toggleWatched")
               end if
             end if
           end if
@@ -884,50 +853,17 @@
             m.pendingDeleteItemId = invalid
           end if
           ' Handle watched confirmation dialog (Series only)
-        else if isValid(m.pendingWatchedItemId)
+        else if m.pendingWatchedConfirmation = true
+          m.pendingWatchedConfirmation = false
           if popupNode.returnData.indexSelected = 1
-            ' User confirmed — mark/unmark all episodes
-            if m.pendingWatchedIsCurrentlyWatched
-              req = GetApi().BuildUnmarkPlayedRequest(m.pendingWatchedItemId)
-            else
-              req = GetApi().BuildMarkPlayedRequest(m.pendingWatchedItemId)
-            end if
-            newWatchedState = not m.pendingWatchedIsCurrentlyWatched
-            m.pendingWatchedItemId = invalid
-            m.pendingWatchedIsCurrentlyWatched = invalid
+            ' User confirmed — delegate the mark/unmark of all episodes to the active screen's
+            ' render-thread method (callFunc rendezvouses there, where it runs as a promise).
+            ' toggleWatched() re-reads the button state to pick mark vs unmark, so no fetch state
+            ' needs threading through the dialog.
             activeGroup = m.global.sceneManager.callFunc("getActiveScene")
-            watchedButton = invalid
             if isValid(activeGroup)
-              watchedButton = activeGroup.findNode("watchedButton")
+              activeGroup.callFunc("toggleWatched")
             end if
-            if isValid(watchedButton) then watchedButton.isLoading = true
-            ' Set resume button to loading while we wait for async data
-            resumeButton = invalid
-            if isValid(activeGroup) then resumeButton = activeGroup.findNode("resumeButton")
-            if isValid(resumeButton) then resumeButton.isLoading = true
-            resultNode = submitApiRequest(req, "watchedToggle")
-            if isValid(resultNode)
-              m.watchedResultNode = resultNode
-              m.pendingWatchedButton = watchedButton
-              m.pendingWatchedNewState = newWatchedState
-              m.pendingWatchedItemType = "Series"
-              m.watchedResultNode.observeField("isDone", m.port)
-            else
-              ' Pool not ready — fall back to fire-and-forget + direct update
-              SubmitSideEffect(req)
-              if isValid(watchedButton)
-                watchedButton.isButtonSelected = newWatchedState
-                watchedButton.isLoading = false
-              end if
-              ' Series: refresh resume data to reflect new watched state
-              if isValid(activeGroup)
-                activeGroup.refreshResumeData = not activeGroup.refreshResumeData
-              end if
-            end if
-          else
-            ' User cancelled
-            m.pendingWatchedItemId = invalid
-            m.pendingWatchedIsCurrentlyWatched = invalid
           end if
         else
           selectedItem = m.global.queueManager.callFunc("getHold")
@@ -1145,55 +1081,6 @@
   end if
 end sub
 
-sub handleWatchedToggleDone()
-  res = m.watchedResultNode.result
-  m.watchedResultNode.unobserveField("isDone")
-  m.watchedResultNode = invalid
-
-  ' Debug error injection — compiled out in production (bs_const=debug=false)
-  #if debug
-    if isValid(m.global.debug) and m.global.debug.shouldForceWatchedFail
-      res = { ok: false }
-    end if
-  #end if
-
-  if isValid(res) and res.ok
-    if isValid(m.pendingWatchedButton)
-      m.pendingWatchedButton.isButtonSelected = m.pendingWatchedNewState
-    end if
-    ' Update resume button to reflect new watched state
-    activeGroup = m.global.sceneManager.callFunc("getActiveScene")
-    if isValid(activeGroup)
-      if m.pendingWatchedItemType = "Series"
-        ' Series: re-fetch next-up episode (may change or disappear)
-        activeGroup.refreshResumeData = not activeGroup.refreshResumeData
-      else if m.pendingWatchedNewState
-        ' Non-Series marking watched: server clears playback position, remove stale resume button
-        removeResumeButtonFromGroup(activeGroup)
-      end if
-    end if
-  else
-    ' Revert button to original state on failure
-    if isValid(m.pendingWatchedButton)
-      m.pendingWatchedButton.isButtonSelected = not m.pendingWatchedNewState
-    end if
-    ' Revert resume button loading state on failure
-    activeGroup = m.global.sceneManager.callFunc("getActiveScene")
-    if isValid(activeGroup)
-      resumeButton = activeGroup.findNode("resumeButton")
-      if isValid(resumeButton) then resumeButton.isLoading = false
-    end if
-    displayToast(translate(translationKeys.ErrorFailedToUpdateWatchedStatus), "error")
-  end if
-
-  if isValid(m.pendingWatchedButton)
-    m.pendingWatchedButton.isLoading = false
-  end if
-  m.pendingWatchedButton = invalid
-  m.pendingWatchedNewState = invalid
-  m.pendingWatchedItemType = invalid
-end sub
-
 sub handleRecordResult(task as object)
   res = task.result
   task.unobserveField("result")
@@ -1235,42 +1122,6 @@
   m.pendingRecordIsCancel = invalid
 end sub
 
-' removeResumeButtonFromGroup: Remove the resume button from an ItemDetails button group.
-' Used after marking an item as watched — the server clears playback position so the
-' resume button is stale. Focus is preserved on the nearest remaining button.
-sub removeResumeButtonFromGroup(group as object)
-  resumeButton = group.findNode("resumeButton")
-  if not isValid(resumeButton) then return
-
-  buttonGrp = group.findNode("buttons")
-  if not isValid(buttonGrp) then return
-
-  currentFocusIndex = buttonGrp.buttonFocused
-  resumeIndex = -1
-  for i = 0 to buttonGrp.getChildCount() - 1
-    child = buttonGrp.getChild(i)
-    if isValid(child) and child.isSameNode(resumeButton)
-      resumeIndex = i
-      exit for
-    end if
-  end for
-
-  wasFocused = resumeButton.isInFocusChain()
-  buttonGrp.removeChild(resumeButton)
-
-  if resumeIndex >= 0 and currentFocusIndex >= resumeIndex
-    focusIdx = currentFocusIndex - 1
-    if focusIdx < 0 then focusIdx = 0
-    buttonGrp.buttonFocused = focusIdx
-  end if
-  if wasFocused
-    nextButton = buttonGrp.getChild(buttonGrp.buttonFocused)
-    if isValid(nextButton)
-      nextButton.setFocus(true)
-    end if
-  end if
-end sub
-
 ' Shared handler for menu actions from both the OptionsSlider and the user dropdown.
 ' Returns true if the caller should goto appStart (session-ending actions).
 function handleMenuAction(actionId as string) as boolean