chore(docs): update code docs

Author: jellyrock[bot]

docs/components_ItemGrid_BaseGridView.bs.html

@@ -132,6 +132,12 @@
   ' Clear global backdrop - we handle our own backdrops
   m.global.sceneManager.callFunc("setBackgroundImage", "")
 
+  ' Re-activate voice capture — the voiceBox loses its active connection to the
+  ' Roku firmware when this screen is removed from the scene tree during pushScene.
+  if isValid(m.voiceBox)
+    m.voiceBox.active = true
+  end if
+
   if isValid(m.top.lastFocus)
     m.top.lastFocus.setFocus(true)
   else

docs/components_home_Home.bs.html

@@ -23,6 +23,11 @@
   m.homeRows.observeField("selectedItem", "onRowItemSelected")
   m.homeRows.observeField("quickPlayNode", "onQuickPlayNode")
 
+  ' Voice search setup — matches BaseGridView's pattern:
+  ' Set voiceEnabled once in init(), never set it to false.
+  ' Only toggle active on screen show/hide.
+  initVoiceBox()
+
   ' Tab configuration
   m.top.overhangTabs = [
     { title: tr("Home"), id: "home" },
@@ -86,8 +91,16 @@
     end if
   end if
 
-  ' Set focus to the active content
-  if isValid(m.top.lastFocus)
+  ' Re-activate voice capture — matching BaseGridView's OnScreenShown pattern.
+  ' Only toggle active; voiceEnabled was set once in init() and never changed.
+  if isValid(m.voiceBox)
+    m.voiceBox.active = true
+  end if
+
+  ' Set focus to the active content.
+  ' Skip voiceBox — SceneManager may save it as lastFocus when voice input
+  ' triggers a pushScene, but it's a hidden capture element, not a valid focus target.
+  if isValid(m.top.lastFocus) and m.top.lastFocus.id <> "homeVoiceBox"
     m.top.lastFocus.setFocus(true)
   else if isValid(m.activeContent)
     m.activeContent.setFocus(true)
@@ -114,6 +127,12 @@
 sub OnScreenHidden()
   m.log.info("OnScreenHidden")
 
+  ' Deactivate voice so other screens can claim the voice route.
+  ' Only toggle active — never set voiceEnabled=false (matches BaseGridView pattern).
+  if isValid(m.voiceBox)
+    m.voiceBox.active = false
+  end if
+
   scene = m.top.getScene()
   overhang = scene.findNode("overhang")
   if isValid(overhang)
@@ -122,6 +141,40 @@
   end if
 end sub
 
+' ============================================
+' VOICE SEARCH
+' ============================================
+
+' initVoiceBox: One-time voice setup in init() — matches BaseGridView's pattern.
+' Sets voiceEnabled=true ONCE and never sets it back to false. The firmware
+' silently manages voiceEnabled when other screens claim voice routing.
+' Only `active` is toggled on screen show/hide.
+sub initVoiceBox()
+  m.voiceBox = m.top.findNode("homeVoiceBox")
+  if not isValid(m.voiceBox)
+    m.log.error("initVoiceBox: homeVoiceBox not found!")
+    return
+  end if
+
+  m.voiceBox.opacity = 0.0001
+  m.voiceBox.hintText = tr("Use voice remote to search")
+  m.voiceBox.voiceEnabled = true
+  m.voiceBox.active = true
+  m.voiceBox.observeField("text", "onVoiceSearch")
+end sub
+
+' onVoiceSearch: Fires when voice input is captured by the hidden VoiceTextEditBox.
+' Signals Main.bs to open SearchResults with the spoken query pre-populated.
+sub onVoiceSearch()
+  voiceText = m.voiceBox.text
+  if voiceText = "" then return
+
+  ' Reset for next voice search
+  m.voiceBox.text = ""
+
+  m.top.voiceQuery = voiceText
+end sub
+
 ' ============================================
 ' TAB HANDLING
 ' ============================================
@@ -248,6 +301,13 @@
 
   m.top.unobserveField("selectedTabId")
 
+  ' Release voice box — match BaseGridView: never set voiceEnabled=false,
+  ' just unobserve and release the reference.
+  if isValid(m.voiceBox)
+    m.voiceBox.unobserveField("text")
+    m.voiceBox = invalid
+  end if
+
   ' Release tab bar observer
   if isValid(m.tabBar)
     m.tabBar.unobserveField("requestFocusReturn")

docs/components_search_SearchResults.bs.html

@@ -34,9 +34,17 @@
 
   ' Set initial focus for scene navigation
   m.top.lastFocus = searchBox
+
 end sub
 
 sub OnScreenShown()
+  if m.top.skipInitialFocus
+    m.top.skipInitialFocus = false
+    ' Caller will set focus after pushScene — skip here to avoid a double-focus
+    ' race on the DynamicMiniKeyboard that prevents the voice prompt overlay.
+    return
+  end if
+
   ' Restore focus for scene navigation
   if isValid(m.top.lastFocus)
     m.top.lastFocus.setFocus(true)
@@ -156,8 +164,18 @@
 sub destroy()
   m.log.verbose("destroy")
 
+  ' Fully release the voice route before teardown — the DynamicMiniKeyboard's
+  ' textEditBox claims the firmware's global voice route via voiceEnabled + active.
+  ' Both must be cleared: active=false stops input capture, voiceEnabled=false
+  ' releases the "only one voiceEnabled at a time" slot so the returning screen's
+  ' VoiceTextEditBox can reclaim it.
+  if isValid(m.searchAlphabox) and isValid(m.searchAlphabox.textEditBox)
+    m.searchAlphabox.textEditBox.voiceEnabled = false
+    m.searchAlphabox.textEditBox.active = false
+  end if
+
   ' Unobserve child node observers
-  m.searchAlphabox.unobserveField("focusedChild")
+  if isValid(m.searchAlphabox) then m.searchAlphabox.unobserveField("focusedChild")
   m.searchSelect.unobserveField("rowItemFocused")
 
   ' Stop and release task node (observer may already be cleared by loadResults())

docs/data/search.json

@@ -143,6 +143,26 @@
           end if
         end if
       end if
+    else if isNodeEvent(msg, "voiceQuery")
+      ' Voice search from Home screen — open SearchResults with spoken query pre-populated
+      voiceQuery = msg.getData()
+      if isValidAndNotEmpty(voiceQuery)
+        ' Guard: skip if a SearchResults is already the active scene (prevents duplicate pushes
+        ' when voice system fires multiple text changes for a single input)
+        activeScene = m.global.sceneManager.callFunc("getActiveScene")
+        if isValid(activeScene) and activeScene.subtype() = "SearchResults"
+          searchKey = activeScene.findNode("SearchBox").findNode("search_Key")
+          searchKey.text = voiceQuery
+          searchKey.textEditBox.setFocus(true)
+        else
+          group = CreateSearchPage()
+          group.skipInitialFocus = true
+          m.global.sceneManager.callFunc("pushScene", group)
+          searchKey = group.findNode("SearchBox").findNode("search_Key")
+          searchKey.text = voiceQuery
+          searchKey.textEditBox.setFocus(true)
+        end if
+      end if
     else if isNodeEvent(msg, "output")
       task = msg.getRoSGNode()
       if isValid(task) and task.subtype() = "QuickPlayTask"

docs/module-Home.html

@@ -633,6 +633,7 @@
 
   group.observeField("selectedItem", m.port)
   group.observeField("quickPlayNode", m.port)
+  group.observeField("voiceQuery", m.port)
 
   sidepanel = group.findNode("options")
   sidepanel.observeField("closeSidePanel", m.port)
@@ -708,7 +709,7 @@
 
 function CreateSearchPage()
   ' Search + Results Page
-  group = CreateObject("roSGNode", "searchResults")
+  group = CreateObject("roSGNode", "SearchResults")
   group.observeField("quickPlayNode", m.port)
   options = group.findNode("searchSelect")
   options.observeField("itemSelected", m.port)