rotor-framework 0.7.1 → 0.7.3

package/README.md

@@ -96,7 +96,7 @@ You can find [🌱](./docs/ai/readme.opt.yaml) symbols in all documentation page
 
 ## 📚 Learn More
 
-![Version](https://img.shields.io/badge/version-v0.7.1-blue?label=Documents%20TAG)
+![Version](https://img.shields.io/badge/version-v0.7.3-blue?label=Documents%20TAG)
 
 ### Framework Core
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rotor-framework",
-	"version": "0.7.1",
+	"version": "0.7.3",
 	"description": "Roku toolkit library providing a ViewBuilder, full UI lifecycle with focus handling and many core features, plus MVI-based state management.",
 	"author": "Balázs Molnár",
 	"license": "Apache-2.0",

package/src/source/RotorFramework.bs

@@ -4,7 +4,7 @@
 ' ▐▛▀▚▖▐▌ ▐▌ █ ▐▌ ▐▌▐▛▀▚▖    ▐▛▀▀▘▐▛▀▚▖▐▛▀▜▌▐▌  ▐▌▐▛▀▀▘▐▌ ▐▌▐▌ ▐▌▐▛▀▚▖▐▛▚▖
 ' ▐▌ ▐▌▝▚▄▞▘ █ ▝▚▄▞▘▐▌ ▐▌    ▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌  ▐▌▐▙▄▄▖▐▙█▟▌▝▚▄▞▘▐▌ ▐▌▐▌ ▐▌
 ' Rotor Framework™
-' Version 0.7.1
+' Version 0.7.3
 ' © 2025 Balázs Molnár — Apache License 2.0
 ' =========================================================================
 
@@ -21,8 +21,8 @@ import "engine/animator/Animator.bs"
 
 ' base classes
 import "base/BaseWidget.bs"
-import "base/DispatcherCreator.bs"
-import "base/DispatcherExternal.bs"
+import "base/DispatcherOriginal.bs"
+import "base/DispatcherCrossThread.bs"
 import "base/BaseReducer.bs"
 import "base/BaseModel.bs"
 import "base/BaseStack.bs"
@@ -86,7 +86,7 @@ namespace Rotor
     class Framework
 
         name = "Rotor Framework"
-        version = "0.7.1"
+        version = "0.7.3"
 
         config = {
             tasks: invalid, ' @array    (optional)
@@ -118,23 +118,14 @@ namespace Rotor
         ttsService as object
         dispatcherProvider as object
         animatorProvider as object
-        info = {
-            device: {}
-        }
-
         ' plugin adapter workspace
         plugins = {}
 
-        ' sync
-        taskOperationalFlag = {}
-        taskSyncReadyFlag = {}
-        taskNodes = {}
+        ' sync - task tracking with phase: pending → operational → synced
+        tasks = {}                      ' taskId -> { node, phase, dispatchers[] }
 
         enableRendering = true
 
-        ' helper vars
-        deviceInfo as object
-
         '----------------------------------------------------------------------
         ' new - Initializes the Rotor Framework instance
         '
@@ -161,8 +152,6 @@ namespace Rotor
 
             m.builder.init(m)
 
-            m.initInfo()
-
             ' set root node
             if m.config.rootNode = invalid
                 rootNode = globalScope.top
@@ -325,15 +314,6 @@ namespace Rotor
             return m.animatorProvider.getFactory(animatorId, m)
         end function
 
-        ' ---------------------------------------------------------------------
-        ' getInfo - Gets framework and device information
-        '
-        ' @returns {object} Info object containing device details
-        '
-        public function getInfo() as object
-            return m.info
-        end function
-
         ' ---------------------------------------------------------------------
         ' getNodePoolInfo - Gets node pool statistics
         '
@@ -366,32 +346,6 @@ namespace Rotor
             m.builder.pluginAdapter.registerPlugins(plugins)
         end sub
 
-        ' ---------------------------------------------------------------------
-        ' initInfo - Initializes device and framework information
-        '
-        ' Collects device information (graphics platform, model, OS version, locale)
-        ' and stores it in m.info for later access.
-        '
-        sub initInfo()
-            ' Device info
-            di = CreateObject("roDeviceInfo")
-            ' Make it available on framework instance
-            m.deviceInfo = di
-            ' Generate app info
-            m.info.device.append({
-                graphicsPlatform: di.GetGraphicsPlatform(), ' ["opengl"|"directfb"]
-                modelDisplayName: di.GetModelDisplayName(),
-                OSVersion: di.GetOSVersion(),
-                currentLocale: di.GetCurrentLocale(), ' Example: "en_US"
-                countryCode: di.GetCountryCode() ' A value that indicates the Streaming Store associated with a user's Roku account.
-            })
-            #if debug
-                print `[DEVICEINFO] Graphics Platform: ${m.info.device.graphicsPlatform}`
-                print `[DEVICEINFO] modelDisplayName: ${m.info.device.modelDisplayName}`
-                print `[DEVICEINFO] OSVersion: ${m.info.device.OSVersion.major}.${m.info.device.OSVersion.minor}.${m.info.device.OSVersion.revision}.${m.info.device.OSVersion.build}`
-            #end if
-        end sub
-
         ' ---------------------------------------------------------------------
         ' setupTaskForSyncing - Prepares a task node for cross-thread syncing
         '
@@ -404,15 +358,17 @@ namespace Rotor
             taskNode = rootNode.createChild(taskName)
             taskId = Rotor.Utils.getUUIDHex(16)
 
-            m.taskNodes[taskId] = taskNode ' collection for later usage
-            m.taskOperationalFlag[taskId] = false ' collection for later usage
+            m.tasks[taskId] = {
+                node: taskNode,
+                phase: "pending",
+                dispatchers: []
+            }
 
             Rotor.Utils.setCustomFields(taskNode, {
                 taskId: taskId,
                 rootNode: rootNode
             })
 
-            ' taskNode.observeFieldScoped("rotorSync", "Rotor_syncCallback")
             taskNode.control = "RUN"
         end sub
 
@@ -422,136 +378,108 @@ namespace Rotor
         ' @param {object} taskList - Array of task names to set up
         '
         sub setupAdditionalTasks(taskList as object)
-            ' check additional tasks
             if taskList = invalid then return
-
-            taskNames = Rotor.Utils.ensureArray(taskList)
-            for each taskName in taskNames
+            for each taskName in Rotor.Utils.ensureArray(taskList)
                 m.setupTaskForSyncing(taskName)
             end for
         end sub
 
         ' ---------------------------------------------------------------------
-        ' areAllTasksOperational - Checks if all task threads are operational
+        ' allTasksInPhase - Checks if all tasks are in given phase
         '
-        ' @returns {boolean} True if all tasks have signaled operational status
+        ' @param {string} phase - Phase to check ("pending", "operational", "synced")
+        ' @returns {boolean} True if all tasks are in the given phase
         '
-        function areAllTasksOperational() as boolean
-            ' Check if all nodes ready (very basic logic (< future improvement)
-            if m.taskOperationalFlag.Count() = 0 then return false
-
-            for each flag in m.taskOperationalFlag.Items()
-                if flag.value <> true then return false
+        function allTasksInPhase(phase as string) as boolean
+            if m.tasks.Count() = 0 then return false
+            for each taskId in m.tasks
+                if m.tasks[taskId].phase <> phase then return false
             end for
-
             return true
         end function
 
         ' ---------------------------------------------------------------------
-        ' collectExternalDispatcherRegistrations - Collects external dispatcher info for tasks
-        '
-        ' Creates a map of which external dispatchers need to be registered in which tasks.
-        '
-        ' @returns {object} AA mapping taskId to array of dispatcher registration configs
-        '
-        function collectExternalDispatcherRegistrations() as object
-            registrations = {}
-            dispatcherIds = m.dispatcherProvider.getAll().keys()
-
-            for each taskEntry in m.taskNodes.Items()
-                taskNode = taskEntry.value
-
-                for each dispatcherId in dispatcherIds
-                    dispatcherInstance = m.dispatcherProvider.get(dispatcherId)
-                    externalTaskNode = dispatcherInstance.taskNode
-
-                    if not taskNode.isSameNode(externalTaskNode)
-                        m.taskSyncReadyFlag[taskNode.taskId] = false ' collection for later usage
-                        if registrations[taskNode.taskId] = invalid then registrations[taskNode.taskId] = []
-                        registrations[taskNode.taskId].push({
-                            dispatcherId: dispatcherId,
-                            externalTaskNode: externalTaskNode
-                        })
-                    end if
-                end for
+        ' getDispatchersNotOnTask - Gets dispatchers that are NOT on given task
+        '
+        ' @param {object} taskNode - Task node to exclude
+        ' @returns {object} Array of { dispatcherId, stateNode } for foreign dispatchers
+        '
+        function getDispatchersNotOnTask(taskNode as object) as object
+            result = []
+            for each dispatcherId in m.dispatcherProvider.getAll().keys()
+                stateNode = m.dispatcherProvider.get(dispatcherId).stateNode
+                if not taskNode.isSameNode(stateNode)
+                    result.push({ dispatcherId: dispatcherId, stateNode: stateNode })
+                end if
             end for
-
-            return registrations
+            return result
         end function
 
         ' ---------------------------------------------------------------------
-        ' dispatchExternalDispatcherRegistrations - Sends dispatcher registration to tasks
-        '
-        ' @param {object} registrations - Map of taskId to dispatcher registration configs
-        '
-        sub dispatchExternalDispatcherRegistrations(registrations as object)
-            for each taskId in registrations
-                taskNode = m.taskNodes[taskId]
-                taskNode.setField("rotorSync", {
-                    type: Rotor.Const.ThreadSyncType.REGISTER_EXTERNAL_DISPATCHER,
-                    externalDispatcherList: registrations[taskId]
-                })
-            end for
-        end sub
-
-        ' ---------------------------------------------------------------------
-        ' haveAllTasksSynced - Checks if all tasks have completed syncing
-        '
-        ' @returns {boolean} True if all tasks have synced successfully
-        '
-        function haveAllTasksSynced() as boolean
-            ' Check if all nodes ready (very basic logic (< future improvement)
-            if m.taskSyncReadyFlag.Count() = 0 then return false
-
-            for each flag in m.taskSyncReadyFlag.Items()
-                if flag.value <> true then return false
+        ' broadcastDispatchersToTasks - Sends foreign dispatchers to each task
+        '
+        ' For each task, sends list of dispatchers that exist on other threads.
+        '
+        sub broadcastDispatchersToTasks()
+            for each taskId in m.tasks
+                task = m.tasks[taskId]
+                foreignDispatchers = m.getDispatchersNotOnTask(task.node)
+
+                if foreignDispatchers.Count() > 0
+                    task.node.setField("rotorSync", {
+                        type: Rotor.Const.ThreadSyncType.REGISTER_CROSS_THREAD_DISPATCHER,
+                        crossThreadDispatcherList: foreignDispatchers
+                    })
+                else
+                    task.phase = "synced"
+                end if
             end for
 
-            return true
-        end function
+            ' If no tasks needed dispatchers, we're done
+            if m.allTasksInPhase("synced")
+                m.isReady()
+            end if
+        end sub
 
         ' ---------------------------------------------------------------------
         ' handleTaskSyncing - Handles task syncing phase
         '
-        ' Registers external dispatchers and sets up cross-thread communication.
+        ' Called when a task reports its dispatchers. Registers cross-thread
+        ' dispatchers and broadcasts dispatcher map when all tasks are ready.
         '
-        ' @param {object} sync - Sync payload from task thread
+        ' @param {object} sync - Sync payload { taskNode, dispatcherIds, tasks }
         '
         sub handleTaskSyncing(sync as object)
             taskNode = sync.taskNode
+            taskId = taskNode.taskId
 
+            ' Setup any additional tasks this task declared
             m.setupAdditionalTasks(sync.tasks)
 
-            ' register incoming dispatchers
-            dispatcherIds = sync.dispatcherIds
-            if dispatcherIds <> invalid
-                m.dispatcherProvider.registerExternalDispatchers(dispatcherIds, taskNode)
-            end if
+            ' Store dispatcher IDs for this task
+            m.tasks[taskId].dispatchers = sync.dispatcherIds ?? []
+            m.tasks[taskId].phase = "operational"
 
-            ' update task status
-            m.taskOperationalFlag[taskNode.taskId] = true
+            ' Register cross-thread dispatchers on render thread
+            if sync.dispatcherIds <> invalid
+                m.dispatcherProvider.registerCrossThreadDispatchers(sync.dispatcherIds, taskNode)
+            end if
 
-            if not m.areAllTasksOperational() then return
+            ' Wait for all tasks to be operational
+            if not m.allTasksInPhase("operational") then return
 
-            ' if allTasksRunning then create external dispatchers in all tasks
-            registrations = m.collectExternalDispatcherRegistrations()
-            if registrations.Count() > 0
-                m.dispatchExternalDispatcherRegistrations(registrations)
-            else
-                m.isReady()
-            end if
+            ' All tasks ready - broadcast dispatcher map
+            m.broadcastDispatchersToTasks()
         end sub
 
         ' ---------------------------------------------------------------------
         ' handleTaskSynced - Handles task synced confirmation
         '
-        ' Marks task as synced and checks if all tasks are ready.
-        '
         ' @param {string} taskId - ID of the task that has synced
         '
         sub handleTaskSynced(taskId as string)
-            m.taskSyncReadyFlag[taskId] = true
-            if m.haveAllTasksSynced()
+            m.tasks[taskId].phase = "synced"
+            if m.allTasksInPhase("synced")
                 m.isReady()
             end if
         end sub
@@ -593,15 +521,15 @@ namespace Rotor
         public sub destroy()
 
             rootNode = m.getRootNode()
-            for each taskId in m.taskNodes
-                taskNode = m.taskNodes[taskId]
-                taskNode.setField("rotorSync", {
+            for each taskId in m.tasks
+                task = m.tasks[taskId]
+                task.node.setField("rotorSync", {
                     type: Rotor.Const.ThreadSyncType.DESTROY
                 })
-                rootNode.removeChild(taskNode)
+                rootNode.removeChild(task.node)
             end for
 
-            m.taskNodes.Clear()
+            m.tasks.Clear()
 
             rootNode.unobserveFieldScoped("rotorSync")
 
@@ -619,9 +547,6 @@ namespace Rotor
             }
             m.config.rootNode = invalid
 
-            m.info.Clear()
-            m.deviceInfo = invalid
-
         end sub
 
     end class

package/src/source/RotorFrameworkTask.bs

@@ -4,7 +4,7 @@
 ' ▐▛▀▚▖▐▌ ▐▌ █ ▐▌ ▐▌▐▛▀▚▖    ▐▛▀▀▘▐▛▀▚▖▐▛▀▜▌▐▌  ▐▌▐▛▀▀▘▐▌ ▐▌▐▌ ▐▌▐▛▀▚▖▐▛▚▖
 ' ▐▌ ▐▌▝▚▄▞▘ █ ▝▚▄▞▘▐▌ ▐▌    ▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌  ▐▌▐▙▄▄▖▐▙█▟▌▝▚▄▞▘▐▌ ▐▌▐▌ ▐▌
 ' Rotor Framework™
-' Version 0.7.1
+' Version 0.7.3
 ' © 2025 Balázs Molnár — Apache License 2.0
 ' =========================================================================
 
@@ -16,8 +16,8 @@ import "engine/providers/DispatcherProvider.bs"
 import "engine/providers/Dispatcher.bs"
 
 ' base classes
-import "base/DispatcherCreator.bs"
-import "base/DispatcherExternal.bs"
+import "base/DispatcherOriginal.bs"
+import "base/DispatcherCrossThread.bs"
 import "base/BaseReducer.bs"
 import "base/BaseModel.bs"
 import "base/BaseStack.bs"
@@ -70,7 +70,7 @@ namespace Rotor
     class FrameworkTask
 
         name = "Rotor Framework"
-        version = "0.7.1"
+        version = "0.7.3"
 
         config = {
             tasks: invalid, ' optional
@@ -87,6 +87,7 @@ namespace Rotor
         dispatcherProvider as object
         port as object
         asyncTransferRegistry = {} ' transferId -> { dispatcherId, context }
+        deviceInfoRegistry = {} ' deviceInfoId -> { dispatcherId, context, deviceInfo }
         onTick as function
 
         ' ---------------------------------------------------------------------
@@ -148,6 +149,27 @@ namespace Rotor
             }
         end sub
 
+        ' ---------------------------------------------------------------------
+        ' registerDeviceInfo - Registers a roDeviceInfo for event listening
+        '
+        ' This method associates a roDeviceInfo object with a dispatcher ID.
+        ' When device info events occur (linkStatus, etc.), the framework will
+        ' route them to the correct dispatcher's asyncReducerCallback.
+        '
+        ' @param {string} deviceInfoId - Unique identifier for this registration
+        ' @param {string} dispatcherId - Dispatcher ID that will handle events
+        ' @param {object} deviceInfo - The roDeviceInfo object (must have SetMessagePort called)
+        ' @param {object} context - Optional user data to pass back in callback
+        '
+        public sub registerDeviceInfo(deviceInfoId as string, dispatcherId as string, deviceInfo as object, context = invalid as dynamic)
+            deviceInfo.SetMessagePort(m.port)
+            m.deviceInfoRegistry[deviceInfoId] = {
+                dispatcherId: dispatcherId,
+                deviceInfo: deviceInfo,
+                context: context
+            }
+        end sub
+
         ' ---------------------------------------------------------------------
         ' sync - Starts the message loop for cross-thread communication
         '
@@ -205,10 +227,10 @@ namespace Rotor
                                 ' taskIntent = Rotor.Utils.deepCopy(intent)
                                 dispatcherInstance.dispatch(intent)
 
-                            else if sync.type = Rotor.Const.ThreadSyncType.REGISTER_EXTERNAL_DISPATCHER
+                            else if sync.type = Rotor.Const.ThreadSyncType.REGISTER_CROSS_THREAD_DISPATCHER
 
-                                for each item in sync.externalDispatcherList
-                                    m.dispatcherProvider.registerExternalDispatchers(item.dispatcherId, item.externalTaskNode)
+                                for each item in sync.crossThreadDispatcherList
+                                    m.dispatcherProvider.registerCrossThreadDispatchers(item.dispatcherId, item.stateNode)
                                 end for
 
                                 m.notifySyncStatus(Rotor.Const.ThreadSyncType.TASK_SYNCED)
@@ -251,6 +273,22 @@ namespace Rotor
                             end if
 
                         end if
+                    else if msgType = "roDeviceInfoEvent"
+                        ' Handle device info events (ignore appFocused, etc.)
+                        if m.deviceInfoRegistry.count() > 0
+                            eventInfo = msg.GetInfo()
+                            ' Only process linkStatus events, ignore appFocused and other events
+                            if eventInfo?.linkStatus <> invalid
+                                ' Route to all registered device info dispatchers
+                                for each deviceInfoId in m.deviceInfoRegistry
+                                    registryEntry = m.deviceInfoRegistry[deviceInfoId]
+                                    dispatcherInstance = m.dispatcherProvider.get(registryEntry.dispatcherId)
+                                    if dispatcherInstance <> invalid
+                                        dispatcherInstance.asyncReducerCallback(eventInfo, registryEntry?.context as dynamic)
+                                    end if
+                                end for
+                            end if
+                        end if
                     end if
                 end if
             end while
@@ -317,6 +355,7 @@ namespace Rotor
         '
         public sub destroy()
             m.asyncTransferRegistry.clear()
+            m.deviceInfoRegistry.clear()
             m.dispatcherProvider.destroy()
 
             globalScope = GetGlobalAA()

package/src/source/base/BaseWidget.bs

@@ -87,22 +87,24 @@ namespace Rotor
         ' These are optionally injected by plugins
 
         ' Focus Plugin Methods (from FocusPlugin.bs)
-        optional enableFocusNavigation as function   ' Enable focus navigation
+        optional enableFocusNavigation as function    ' Enable focus navigation
         optional isFocusNavigationEnabled as function ' Check if focus enabled
-        optional setFocus as function                ' Set focus on widget
-        optional getFocusedWidget as function        ' Get currently focused widget
-        optional proceedLongPress as function        ' Trigger long press
-        optional isLongPressActive as function       ' Check if long press active
+        optional setFocus as function                 ' Set focus on widget
+        optional getFocusedWidget as function         ' Get currently focused widget
+        optional proceedLongPress as function         ' Trigger long press
+        optional isLongPressActive as function        ' Check if long press active
+        optional triggerKeyPress as function          ' Trigger key press event
+        optional setGroupLastFocusedId as function    ' Set the last focused widget ID within the current focus group (used to restore focus when re-entering the group)
 
         ' =============================================================
         ' PRIVATE PROPERTIES (Engine Use Only)
         ' =============================================================
 
-        private HID as string           ' Hierarchical ID (e.g., "0.header.logo")
-        private vmHID as string         ' Owning ViewModel's HID
-        private isRootChild as boolean  ' True if direct child of root
+        private HID as string             ' Hierarchical ID (e.g., "0.header.logo")
+        private vmHID as string           ' Owning ViewModel's HID
+        private isRootChild as boolean    ' True if direct child of root
         private childrenHIDhash as object ' Hash of child HIDs for fast lookup
-        private parentHID as string     ' Parent's HID
+        private parentHID as string       ' Parent's HID
 
     end class
 

package/src/source/base/{ListenerForDispatchers.bs → DispatcherCore.bs}

@@ -16,10 +16,15 @@ end interface
 namespace Rotor
 
     ' =====================================================================
-    ' ListenerForDispatchers - Base class for dispatcher state change listener management
+    ' DispatcherCore - Core base class for dispatcher implementations
     '
-    ' Provides listener registration, notification, and lifecycle management
-    ' for both internal and external dispatchers.
+    ' Provides shared properties and listener management for both
+    ' DispatcherOriginal and DispatcherCrossThread.
+    '
+    ' Shared Properties:
+    '   - dispatcherId: Unique identifier for this dispatcher
+    '   - stateNode: SceneGraph node for state exposure
+    '   - listeners: Array of registered state change listeners
     '
     ' Listener Features:
     '   - State mapping: mapStateToProps for updating widget props
@@ -33,12 +38,15 @@ namespace Rotor
     '   3. Invoke callback functions
     '   4. Remove 'once' listeners
     ' =====================================================================
-    class ListenerForDispatchers
+    class DispatcherCore
 
         ' =============================================================
         ' MEMBER VARIABLES
         ' =============================================================
 
+        dispatcherId as string          ' Dispatcher identifier
+        stateNode as object             ' Node for cross-thread state exposure
+
         listeners = []                  ' Array of listener configurations
 
         ' =============================================================