rotor-framework 0.7.5 → 0.7.7

package/LICENSE

@@ -175,7 +175,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2025 Balazs Molnar
+   Copyright © 2025-2026 Balazs Molnar
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

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.5-blue?label=Documents%20TAG)
+![Version](https://img.shields.io/badge/version-v0.7.7-blue?label=Documents%20TAG)
 
 ### Framework Core
 
@@ -185,6 +185,6 @@ This helps others discover the project and supports the open source community. T
 
 ---
 
-**Copyright 2025 Balazs Molnar**
+**Copyright © 2025-2026 Balazs Molnar**
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rotor-framework",
-	"version": "0.7.5",
+	"version": "0.7.7",
 	"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,8 +4,8 @@
 ' ▐▛▀▚▖▐▌ ▐▌ █ ▐▌ ▐▌▐▛▀▚▖    ▐▛▀▀▘▐▛▀▚▖▐▛▀▜▌▐▌  ▐▌▐▛▀▀▘▐▌ ▐▌▐▌ ▐▌▐▛▀▚▖▐▛▚▖
 ' ▐▌ ▐▌▝▚▄▞▘ █ ▝▚▄▞▘▐▌ ▐▌    ▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌  ▐▌▐▙▄▄▖▐▙█▟▌▝▚▄▞▘▐▌ ▐▌▐▌ ▐▌
 ' Rotor Framework™
-' Version 0.7.5
-' © 2025 Balázs Molnár — Apache License 2.0
+' Version 0.7.7
+' © 2025-2026 Balázs Molnár — Apache License 2.0
 ' =========================================================================
 
 ' constants
@@ -86,7 +86,7 @@ namespace Rotor
     class Framework
 
         name = "Rotor Framework"
-        version = "0.7.5"
+        version = "0.7.7"
 
         config = {
             tasks: invalid, ' @array    (optional)

package/src/source/RotorFrameworkTask.bs

@@ -4,8 +4,8 @@
 ' ▐▛▀▚▖▐▌ ▐▌ █ ▐▌ ▐▌▐▛▀▚▖    ▐▛▀▀▘▐▛▀▚▖▐▛▀▜▌▐▌  ▐▌▐▛▀▀▘▐▌ ▐▌▐▌ ▐▌▐▛▀▚▖▐▛▚▖
 ' ▐▌ ▐▌▝▚▄▞▘ █ ▝▚▄▞▘▐▌ ▐▌    ▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌  ▐▌▐▙▄▄▖▐▙█▟▌▝▚▄▞▘▐▌ ▐▌▐▌ ▐▌
 ' Rotor Framework™
-' Version 0.7.5
-' © 2025 Balázs Molnár — Apache License 2.0
+' Version 0.7.7
+' © 2025-2026 Balázs Molnár — Apache License 2.0
 ' =========================================================================
 
 ' constants
@@ -70,7 +70,7 @@ namespace Rotor
     class FrameworkTask
 
         name = "Rotor Framework"
-        version = "0.7.5"
+        version = "0.7.7"
 
         config = {
             tasks: invalid, ' optional

package/src/source/base/BaseViewModel.bs

@@ -21,10 +21,10 @@ namespace Rotor
         ' MEMBER VARIABLES
         ' =============================================================
 
-        isViewModel = true              ' Identifies this as a ViewModel
+        isViewModel = true ' Identifies this as a ViewModel
 
-        viewModelState = {}             ' Mutable state shared across ViewModel's widgets
-        props = {}                      ' Immutable props shared across ViewModel's widgets
+        viewModelState = {} ' Mutable state shared across ViewModel's widgets
+        props = {} ' Immutable props shared across ViewModel's widgets
 
         ' =============================================================
         ' PROPS MANAGEMENT
@@ -82,6 +82,8 @@ namespace Rotor
         ' Called automatically when setProps() is invoked.
         '
         sub onUpdateView()
+            ' Re-render template
+            m.render()
         end sub
 
         ' ---------------------------------------------------------------------

package/src/source/engine/builder/WidgetCreate.bs

@@ -91,26 +91,34 @@ namespace Rotor.ViewBuilder
             return m.getFrameworkInstance().builder.widgetTree.getSubtreeClone(searchPattern, configIncludeFilter, m.parentHID)
         end function
 
-       ' Get i18n service
+        ' Get i18n service
         widget.i18n = function() as object
             return m.getFrameworkInstance().i18nService
         end function
 
         ' render - Renders widget updates (self, descendants, or children) *'
         widget.render = sub(payloads as dynamic, params = {} as object)
-            for each payload in Rotor.Utils.ensureArray(payloads)
-                if payload.DoesExist("id") = false
-                    ' Self update
-                    payload.id = m.id
-                    payload.HID = m.HID
-                else if payload.id <> m.id
-                    ' Update descendants starting from this widget
-                    payload.parentHID = m.HID
-                else
-                    ' Update descendants starting from parent widget
-                    payload.parentHID = m.parentHID
-                end if
-            end for
+            if payloads = invalid and m.isViewModel = true
+                ' Self update (only for viewModels)
+                payloads = m.template()
+                ' Self update
+                payloads.id = m.id
+                payloads.HID = m.HID
+            else
+                for each payload in Rotor.Utils.ensureArray(payloads)
+                    if payload.DoesExist("id") = false
+                        ' Self update
+                        payload.id = m.id
+                        payload.HID = m.HID
+                    else if payload.id <> m.id
+                        ' Update descendants starting from this widget
+                        payload.parentHID = m.HID
+                    else
+                        ' Update descendants starting from parent widget
+                        payload.parentHID = m.parentHID
+                    end if
+                end for
+            end if
             if Rotor.Utils.isValid(params.callback) then params.callbackScope = m
             m.getFrameworkInstance().builder.render(payloads, params)
         end sub

package/src/source/engine/services/Tts.bs

@@ -117,7 +117,7 @@ namespace Rotor.ViewBuilder
             #if not unittest
                 if m.audioGuide = invalid
                     #if debug
-                        ? "[TTS_SERVICE][ERROR] Failed to create roAudioGuide instance"
+                        ' ? "[TTS_SERVICE][ERROR] Failed to create roAudioGuide instance"
                     #end if
                     m.isEnabled = false
                     return
@@ -132,13 +132,13 @@ namespace Rotor.ViewBuilder
             m.timerNode.observeFieldScoped("fire", "Rotor_ViewBuilder_ttsDebounceCallback")
             ' Note: Timer is NOT started here, only when pending speech is added
             #if debug
-                ? "[TTS_SERVICE][INFO] Threshold timer created (one-shot, "; m.debounceDelay; "ms)"
+                ' ? "[TTS_SERVICE][INFO] Threshold timer created (one-shot, "; m.debounceDelay; "ms)"
             #end if
 
             ' Check device AudioGuide status dynamically
             if not m.getIsDeviceAudioGuideEnabled()
                 #if debug
-                    ? "[TTS_SERVICE][INFO] Device AudioGuide is disabled, TTS service disabled"
+                    ' ? "[TTS_SERVICE][INFO] Device AudioGuide is disabled, TTS service disabled"
                 #end if
                 m.isEnabled = false
                 return
@@ -177,7 +177,7 @@ namespace Rotor.ViewBuilder
             if Rotor.Utils.isString(onceKey)
                 if m.skipCache.DoesExist(onceKey)
                     #if debug
-                        ? "[TTS_SERVICE] Skipping speech with onceKey (already spoken): "; onceKey
+                        ' ? "[TTS_SERVICE] Skipping speech with onceKey (already spoken): "; onceKey
                     #end if
                     return
                 end if
@@ -197,7 +197,7 @@ namespace Rotor.ViewBuilder
             ' Check if we should skip duplicate speech
             if dontRepeat and textToSpeak = m.lastSpeech
                 #if debug
-                    ? "[TTS_SERVICE] Skipping duplicate speech: "; textToSpeak
+                    ' ? "[TTS_SERVICE] Skipping duplicate speech: "; textToSpeak
                 #end if
                 return
             end if
@@ -206,7 +206,7 @@ namespace Rotor.ViewBuilder
             ' This means: bypass threshold immediately AND set flag to protect from next flush
             if shouldPreventNextFlush
                 #if debug
-                    ? "[TTS_SERVICE][OVERRIDE] Current speech bypassing threshold: "; textToSpeak
+                    ' ? "[TTS_SERVICE][OVERRIDE] Current speech bypassing threshold: "; textToSpeak
                 #end if
 
                 ' Track if there was pending speech
@@ -215,7 +215,7 @@ namespace Rotor.ViewBuilder
                 ' IMPORTANT: Execute pending speech FIRST if it exists (maintains correct order)
                 if m.pendingSpeech <> invalid
                     #if debug
-                        ? "[TTS_SERVICE][OVERRIDE] Executing pending speech first: '"; m.pendingSpeech.textToSpeak; "'"
+                        ' ? "[TTS_SERVICE][OVERRIDE] Executing pending speech first: '"; m.pendingSpeech.textToSpeak; "'"
                     #end if
                     pendingToExecute = m.pendingSpeech
                     m.pendingSpeech = invalid
@@ -247,7 +247,7 @@ namespace Rotor.ViewBuilder
             ' This allows rapid menu navigation to filter properly (threshold replaces pending)
             if m.preventNextFlushFlag or m.isPendingProtected
                 #if debug
-                    ? "[TTS_SERVICE][OVERRIDE] Flush blocked, speech goes to threshold: "; textToSpeak
+                    ' ? "[TTS_SERVICE][OVERRIDE] Flush blocked, speech goes to threshold: "; textToSpeak
                 #end if
                 if m.preventNextFlushFlag
                     m.preventNextFlushFlag = false ' Clear flag after first use
@@ -266,11 +266,11 @@ namespace Rotor.ViewBuilder
             ' If new request comes within 300ms, replace pending (filter rapid changes)
             #if debug
                 if m.pendingSpeech <> invalid
-                    ? "[TTS_SERVICE][THRESHOLD] Replacing pending: '"; m.pendingSpeech.textToSpeak; "' with: '"; textToSpeak; "'"
+                    ' ? "[TTS_SERVICE][THRESHOLD] Replacing pending: '"; m.pendingSpeech.textToSpeak; "' with: '"; textToSpeak; "'"
                 else
                     flushLabel = ""
                     if shouldFlush then flushLabel = " (will flush)"
-                    ? "[TTS_SERVICE][THRESHOLD] Pending: '"; textToSpeak; "' ("; m.debounceDelay; "ms)"; flushLabel
+                    ' ? "[TTS_SERVICE][THRESHOLD] Pending: '"; textToSpeak; "' ("; m.debounceDelay; "ms)"; flushLabel
                 end if
             #end if
             m.pendingSpeech = {
@@ -321,7 +321,7 @@ namespace Rotor.ViewBuilder
 
             ' Execute pending speech after threshold passed
             #if debug
-                ? "[TTS_SERVICE][THRESHOLD] Timer fired, executing: '"; pendingToExecute.textToSpeak; "'"
+                ' ? "[TTS_SERVICE][THRESHOLD] Timer fired, executing: '"; pendingToExecute.textToSpeak; "'"
             #end if
 
             ' IMPORTANT: Clear protection flag BEFORE executing pending speech
@@ -350,7 +350,7 @@ namespace Rotor.ViewBuilder
             if isLongText or isMultiSentence
                 shouldFlush = true
                 #if debug
-                    ? "[TTS_SERVICE] Forcing flush for long/multi-sentence text (len: "; Len(textToSpeak); ", multi: "; isMultiSentence; ")"
+                    ' ? "[TTS_SERVICE] Forcing flush for long/multi-sentence text (len: "; Len(textToSpeak); ", multi: "; isMultiSentence; ")"
                 #end if
             end if
 
@@ -372,7 +372,7 @@ namespace Rotor.ViewBuilder
             ' Handle flush with prevention protection
             if shouldFlush and m.preventNextFlushFlag
                 #if debug
-                    ? "[TTS_SERVICE] Flush blocked by preventNextFlush protection"
+                    ' ? "[TTS_SERVICE] Flush blocked by preventNextFlush protection"
                 #end if
                 shouldFlush = false ' Prevent flush in Say() call too!
                 m.preventNextFlushFlag = false
@@ -391,7 +391,7 @@ namespace Rotor.ViewBuilder
             end if
 
             #if debug
-                ? "[TTS_SERVICE] Speaking (ID: "; speechId; "): "; text; " (flush: "; shouldFlush; ", dontRepeat: "; dontRepeat; ")"
+                ' ? "[TTS_SERVICE] Speaking (ID: "; speechId; "): "; text; " (flush: "; shouldFlush; ", dontRepeat: "; dontRepeat; ")"
             #end if
 
             return speechId
@@ -560,7 +560,7 @@ namespace Rotor.ViewBuilder
             end if
 
             #if debug
-                ? "[TTS_SERVICE] Stop speech - flushed all speech and canceled pending"
+                ' ? "[TTS_SERVICE] Stop speech - flushed all speech and canceled pending"
             #end if
         end sub
 
@@ -585,7 +585,7 @@ namespace Rotor.ViewBuilder
             if m.skipCache.DoesExist(key)
                 m.skipCache.Delete(key)
                 #if debug
-                    ? "[TTS_SERVICE] Removed onceKey from cache: "; key
+                    ' ? "[TTS_SERVICE] Removed onceKey from cache: "; key
                 #end if
             end if
         end sub
@@ -596,7 +596,7 @@ namespace Rotor.ViewBuilder
         public sub enable()
             if not m.getIsDeviceAudioGuideEnabled()
                 #if debug
-                    ? "[TTS_SERVICE][WARNING] Cannot enable - device AudioGuide is disabled"
+                    ' ? "[TTS_SERVICE][WARNING] Cannot enable - device AudioGuide is disabled"
                 #end if
                 return
             end if
@@ -608,7 +608,7 @@ namespace Rotor.ViewBuilder
             if rootNode <> invalid and not m.allowNativeAudioGuide
                 rootNode.muteAudioGuide = true
                 #if debug
-                    ? "[TTS_SERVICE][INFO] Enabled TTS, muted native AudioGuide"
+                    ' ? "[TTS_SERVICE][INFO] Enabled TTS, muted native AudioGuide"
                 #end if
             end if
         end sub
@@ -626,7 +626,7 @@ namespace Rotor.ViewBuilder
                 if rootNode <> invalid
                     rootNode.muteAudioGuide = false
                     #if debug
-                        ? "[TTS_SERVICE][INFO] Disabled TTS, unmuted native AudioGuide"
+                        ' ? "[TTS_SERVICE][INFO] Disabled TTS, unmuted native AudioGuide"
                     #end if
                 end if
             end if
@@ -638,7 +638,7 @@ namespace Rotor.ViewBuilder
         public sub clearOnceCache()
             m.skipCache = {}
             #if debug
-                ? "[TTS_SERVICE] Once cache cleared"
+                ' ? "[TTS_SERVICE] Once cache cleared"
             #end if
         end sub
 

package/src/source/plugins/FocusPlugin.bs

@@ -77,9 +77,11 @@ namespace Rotor
     '   3. BubblingFocus (ask parent groups)
     '
     ' RULE #4: Spatial Navigation Scope
-    '   - ONLY works within a single group
-    '   - Cannot cross into sibling or parent groups
-    '   - Searches only possibleFocusItems from group.getGroupMembersHIDs()
+    '   - Works within parent group scope
+    '   - Participants: FocusItems AND direct child Groups with enableSpatialNavigation: true
+    '   - enableSpatialNavigation default is FALSE (opt-in)
+    '   - When Group is selected via spatial nav, capturing focus starts into that group
+    '   - Searches possibleFocusItems + Groups from group.getGroupMembersHIDs()
     '
     ' RULE #5: Group Direction Activation
     '   Group direction triggers ONLY when:
@@ -121,13 +123,6 @@ namespace Rotor
     '   2. group.defaultFocusId [CONFIGURED]
     '   3. Deep search (if defaultFocusId not found immediately)
     '
-    ' RULE #11b: Deep Focus Tracking (trackDescendantFocus: true)
-    '   When a FocusGroup has trackDescendantFocus: true, it stores lastFocusedHID
-    '   for ANY descendant FocusItem (not just direct children).
-    '   - Immediate parent ALWAYS stores lastFocusedHID (default behavior)
-    '   - Ancestor groups with trackDescendantFocus: true ALSO store it
-    '   - Enables "deep focus memory" - returning to deeply nested items
-    '
     ' RULE #12: DefaultFocusId Targets
     '   - FocusItem node ID → Focus goes directly to it
     '   - Group node ID → Capturing continues on that group
@@ -244,13 +239,17 @@ namespace Rotor
             ' ---------------------------------------------------------------------
             ' beforeDestroy - Hook executed before a widget is destroyed
             '
-            ' Removes focus config.
+            ' Removes focus config. Clears global focus if this widget had it.
             '
             ' @param {object} scope - The plugin scope (this instance)
             ' @param {object} widget - The widget being destroyed
             '
             beforeDestroy: sub(scope as object, widget as object)
+                hadFocus = scope.globalFocusHID = widget.HID
                 scope.removeFocusConfig(widget.HID)
+                if hadFocus
+                    scope.storeGlobalFocusHID("", "")
+                end if
             end sub
         }
 
@@ -391,6 +390,7 @@ namespace Rotor
         ' State tracking
         globalFocusHID = ""
         globalFocusId = ""
+        lastNavigationDirection = ""
         isLongPress = false
         longPressKey = ""
 
@@ -404,6 +404,26 @@ namespace Rotor
         distanceCalculator = new Rotor.FocusPluginHelper.ClosestSegmentToPointCalculatorClass()
         longPressTimer = CreateObject("roSGNode", "Timer")
 
+        ' Spatial navigation direction validators (reused across calls)
+        spatialValidators = {
+            "left": function(segments as object, refSegmentLeft as object, refSegmentRight as object) as object
+                right = segments[Rotor.Const.Segment.RIGHT]
+                return right.x2 <= refSegmentLeft.x1 ? { isValid: true, segment: right } : { isValid: false }
+            end function,
+            "up": function(segments as object, refSegmentTop as object, refSegmentBottom as object) as object
+                bottom = segments[Rotor.Const.Segment.BOTTOM]
+                return bottom.y2 <= refSegmentTop.y1 ? { isValid: true, segment: bottom } : { isValid: false }
+            end function,
+            "right": function(segments as object, refSegmentLeft as object, refSegmentRight as object) as object
+                left = segments[Rotor.Const.Segment.LEFT]
+                return left.x1 >= refSegmentRight.x2 ? { isValid: true, segment: left } : { isValid: false }
+            end function,
+            "down": function(segments as object, refSegmentTop as object, refSegmentBottom as object) as object
+                top = segments[Rotor.Const.Segment.TOP]
+                return top.y1 >= refSegmentBottom.y2 ? { isValid: true, segment: top } : { isValid: false }
+            end function
+        }
+
         ' ---------------------------------------------------------------------
         ' init - Initializes the plugin instance
         '
@@ -511,6 +531,11 @@ namespace Rotor
             ' Create and register the FocusItem instance
             newFocusItem = new Rotor.FocusPluginHelper.FocusItemClass(config)
             m.focusItemStack.set(HID, newFocusItem)
+
+            ' Restore focus state if this widget had global focus
+            if m.globalFocusHID = HID
+                newFocusItem.isFocused = true
+            end if
         end sub
 
         '
@@ -585,7 +610,8 @@ namespace Rotor
                     group = m.groupStack.get(ref) ?? m.groupStack.getByNodeId(ref)
                     if group <> invalid
                         ' If group found, find its default/entry focus item recursively.
-                        HID = m.capturingFocus_recursively(group.HID)
+                        ' Use lastNavigationDirection so enableSpatialEnter groups can pick the right entry point
+                        HID = m.capturingFocus_recursively(group.HID, m.lastNavigationDirection)
                         focusItem = m.focusItemStack.get(HID) ' May still be invalid if capture fails
                         ' else: ref is not a known FocusItem HID or Group identifier
                     end if
@@ -642,16 +668,18 @@ namespace Rotor
                 if lastFocused <> invalid ' Check if the last focused widget hasn't been destroyed
                     ' Record the last focused item within its parent group for potential future use (e.g., returning focus)
                     lastFocusChainingGroups = m.findAncestorGroups(m.globalFocusHID)
-                    if lastFocusChainingGroups.Count() > 0
-                        ' Always set on immediate parent (index 0)
-                        parentGroupHID = lastFocusChainingGroups[0]
-                        if parentGroupHID <> invalid and parentGroupHID <> ""
-                            group = m.groupStack.get(parentGroupHID)
-                            if group <> invalid
-                                group.setLastFocusedHID(m.globalFocusHID)
+                    for i = 0 to lastFocusChainingGroups.Count() - 1
+                        ancestorGroupHID = lastFocusChainingGroups[i]
+                        ancestorGroup = m.groupStack.get(ancestorGroupHID)
+                        if ancestorGroup <> invalid
+                            ' For immediate parent (index 0): set if enableLastFocusId is true (default)
+                            ' For other ancestors: set if enableDeepLastFocusId is enabled
+                            shouldSetLastFocusId = (i = 0 and ancestorGroup.enableLastFocusId) or (i > 0 and ancestorGroup.enableDeepLastFocusId)
+                            if shouldSetLastFocusId
+                                ancestorGroup.setLastFocusedHID(m.globalFocusHID)
                             end if
                         end if
-                    end if
+                    end for
                 end if
             end if
 
@@ -667,14 +695,6 @@ namespace Rotor
                 if -1 = Rotor.Utils.findInArray(allAffectedGroups, groupHID)
                     allAffectedGroups.unshift(groupHID)
                 end if
-
-                ' Deep remember (skip index 0 - immediate parent is handled separately)
-                if i > 0 and lastFocused <> invalid
-                    ancestorGroup = m.groupStack.get(groupHID)
-                    if ancestorGroup <> invalid and ancestorGroup.trackDescendantFocus = true
-                        ancestorGroup.setLastFocusedHID(m.globalFocusHID)
-                    end if
-                end if
             end for
 
             ' Notify all ancestor groups BEFORE applying focus (from highest ancestor to closest parent)
@@ -743,8 +763,9 @@ namespace Rotor
             m.notifyLongPressAtAncestorGroups(isLongPress, key, focused.HID, focusChainGroups)
         end sub
 
-        function spatialNavigation(focused as object, direction as string, focusItemsHIDlist as object) as string
-            if focused.enableSpatialNavigation = false then return ""
+        function spatialNavigation(focused as object, direction as string, focusItemsHIDlist as object, bypassFocusedCheck = false as boolean) as string
+            ' Skip if focused item doesn't participate in spatial nav (unless bypassed for cross-group nav)
+            if not bypassFocusedCheck and focused.enableSpatialNavigation = false then return ""
             if direction = Rotor.Const.Direction.BACK then return ""
 
             ' Remove current focused item from candidates
@@ -752,9 +773,10 @@ namespace Rotor
             if index >= 0 then focusItemsHIDlist.delete(index)
 
             ' Find closest focusable item in direction
-            segments = m.collectSegments(focused, direction, focusItemsHIDlist)
+            focusedMetrics = focused.refreshBounding()
+            segments = m.collectSegments(focusedMetrics, direction, focusItemsHIDlist, focused.HID)
             if segments.Count() > 0
-                return m.findClosestSegment(segments, focused.metrics.middlePoint)
+                return m.findClosestSegment(segments, focusedMetrics.middlePoint)
             end if
 
             return ""
@@ -796,18 +818,34 @@ namespace Rotor
             if group = invalid then group = m.groupStack.getByNodeId(identifier, ancestorHID)
             if group = invalid then return ""
 
-            ' Get fallback identifier for this group
-            newHID = group.getFallbackIdentifier()
+            newHID = ""
 
-            ' Check if we found a FocusItem
-            if m.focusItemStack.has(newHID)
-                ' Apply spatial enter feature if enabled
-                if group.enableSpatialEnter = true and direction <> ""
+            ' enableSpatialEnter: use spatialNavigation to find closest member
+            if group.isSpatialEnterEnabledForDirection(direction)
+                if direction <> "" and m.globalFocusHID <> ""
                     focused = m.focusItemStack.get(m.globalFocusHID)
-                    newSpatialHID = m.spatialNavigation(focused, direction, group.getGroupMembersHIDs())
-                    if newSpatialHID <> "" then newHID = newSpatialHID
+                    if focused <> invalid
+                        ' Get group members and use spatial navigation to find closest
+                        members = group.getGroupMembersHIDs()
+                        if members.count() > 0
+                            newHID = m.spatialNavigation(focused, direction, members, true)
+                            ' If spatial nav found a group (not a focus item), recursively resolve it
+                            if newHID <> "" and m.groupStack.has(newHID)
+                                newHID = m.capturingFocus_recursively(newHID, direction, group.HID)
+                            end if
+                        end if
+                    end if
                 end if
+            end if
+
+            ' Fallback to getFallbackIdentifier if spatial enter didn't find anything
+            if newHID = ""
+                newHID = group.getFallbackIdentifier(m.globalFocusHID, direction)
+            end if
 
+            ' Check if we found a FocusItem
+            if m.focusItemStack.has(newHID)
+                ' noop — direct focusItem resolved
             else if newHID <> ""
                 ' Try to find as group first, then deep search
                 newHID = m.capturingFocus_recursively(newHID, direction, group.HID)
@@ -819,7 +857,8 @@ namespace Rotor
             end if
 
             ' Prevent capturing by fallback in the same group where original focus was
-            if newHID <> "" and m.globalFocusHID <> ""
+            ' Skip this guard for enableSpatialEnter groups (spatial enter explicitly targets a sibling group's member)
+            if not group.isSpatialEnterEnabledForDirection(direction) and newHID <> "" and m.globalFocusHID <> ""
                 currentAncestors = m.findAncestorGroups(m.globalFocusHID)
                 newAncestors = m.findAncestorGroups(newHID)
                 if currentAncestors.Count() > 0 and newAncestors.Count() > 0
@@ -883,6 +922,9 @@ namespace Rotor
             ancestorGroupsCount = ancestorGroups.Count()
             ancestorIndex = 0
 
+            ' Get currently focused item for spatial navigation
+            focused = m.focusItemStack.get(m.globalFocusHID)
+
             ' Bubble up through ancestor groups until we find a target or reach the top
             while Rotor.Utils.isString(newHID) and newHID = "" and ancestorIndex < ancestorGroupsCount
                 ' Get next ancestor group
@@ -906,6 +948,34 @@ namespace Rotor
                         if otherGroup <> invalid
                             newHID = m.capturingFocus_recursively(otherGroup.HID, direction)
                         end if
+                    else
+                        ' No explicit direction - try spatial navigation at this group level
+                        ' This allows navigation between sibling child groups with enableSpatialNavigation
+                        ' Skip during long press to allow bubbling up to parent carousel for continuous scrolling
+                        ' Skip for "back" direction - spatial navigation doesn't apply
+                        if focused <> invalid and m.isLongPress = false and direction <> Rotor.Const.Direction.BACK
+                            groupMembers = group.getGroupMembersHIDs()
+                            ' Check if this group has any child groups with spatial nav enabled
+                            hasSpatialNavGroups = false
+                            for each memberHID in groupMembers
+                                if m.groupStack.has(memberHID)
+                                    memberGroup = m.groupStack.get(memberHID)
+                                    if memberGroup.enableSpatialNavigation = true
+                                        hasSpatialNavGroups = true
+                                        exit for
+                                    end if
+                                end if
+                            end for
+                            ' If there are spatial-nav-enabled child groups, try spatial navigation
+                            ' Use bypassFocusedCheck=true since we're navigating between groups, not within
+                            if hasSpatialNavGroups
+                                newHID = m.spatialNavigation(focused, direction, groupMembers, true)
+                                ' If spatial nav found a group, use capturing focus to enter it
+                                if newHID <> "" and m.groupStack.has(newHID)
+                                    newHID = m.capturingFocus_recursively(newHID, direction)
+                                end if
+                            end if
+                        end if
                     end if
                 end if
 
@@ -923,7 +993,6 @@ namespace Rotor
             end if
             ' Prevent any navigation if it is disabled
             #if debug
-                if m.enableFocusNavigation = false and press = true then print "[PLUGIN][FOCUS][INFO] Focus navigation is disabled. Call enableFocusNavigation(true) to make it enabled"
             #end if
             if m.enableFocusNavigation = false then return m.parseOnKeyEventResult(key, false, false)
             ' Execute action according to key press
@@ -944,6 +1013,7 @@ namespace Rotor
 
                     newHID = ""
                     direction = key
+                    m.lastNavigationDirection = direction
 
                     ' (1) Pick up current focused item
 
@@ -1053,56 +1123,44 @@ namespace Rotor
         end sub
 
         function proceedLongPress() as object
+            if m.enableFocusNavigation = false then return m.parseOnKeyEventResult(m.longPressKey, false, false)
             return m.executeNavigationAction(m.longPressKey, true)
         end function
 
         ' Find all the relevant(closest in direction) segments that are in the same group as the focused item.
-        function collectSegments(focused as object, direction as string, focusItemsHIDlist as object) as object
-            focused.refreshBounding()
-
-            refSegmentTop = focused.metrics.segments[Rotor.Const.Segment.TOP]
-            refSegmentRight = focused.metrics.segments[Rotor.Const.Segment.RIGHT]
-            refSegmentLeft = focused.metrics.segments[Rotor.Const.Segment.LEFT]
-            refSegmentBottom = focused.metrics.segments[Rotor.Const.Segment.BOTTOM]
-            referencePoint = { x: (refSegmentTop.x1 + refSegmentRight.x2) / 2, y: (refSegmentTop.y1 + refSegmentRight.y2) / 2 }
-
-            validators = {
-
-                "left": function(referencePoint as object, segments as object, refSegmentLeft as object, refSegmentRight as object) as object
-                    right = segments[Rotor.Const.Segment.RIGHT]
-                    ' Candidate's right edge must be strictly left of focused element's left edge
-                    return right.x2 <= refSegmentLeft.x1 ? { isValid: true, segment: right } : { isValid: false }
-                end function,
-
-                "up": function(referencePoint as object, segments as object, refSegmentTop as object, refSegmentBottom as object) as object
-                    bottom = segments[Rotor.Const.Segment.BOTTOM]
-                    ' Candidate's bottom edge must be strictly above focused element's top edge
-                    return bottom.y2 <= refSegmentTop.y1 ? { isValid: true, segment: bottom } : { isValid: false }
-                end function,
-
-                "right": function(referencePoint as object, segments as object, refSegmentLeft as object, refSegmentRight as object) as object
-                    left = segments[Rotor.Const.Segment.LEFT]
-                    ' Candidate's left edge must be strictly right of focused element's right edge
-                    return left.x1 >= refSegmentRight.x2 ? { isValid: true, segment: left } : { isValid: false }
-                end function,
-
-                "down": function(referencePoint as object, segments as object, refSegmentTop as object, refSegmentBottom as object) as object
-                    top = segments[Rotor.Const.Segment.TOP]
-                    ' Candidate's top edge must be strictly below focused element's bottom edge
-                    return top.y1 >= refSegmentBottom.y2 ? { isValid: true, segment: top } : { isValid: false }
-                end function
-            }
+        ' @param focusedMetrics - The metrics object from focused.refreshBounding()
+        ' @param focusedHID - The HID of the focused item (to exclude from candidates)
+        function collectSegments(focusedMetrics as object, direction as string, focusItemsHIDlist as object, focusedHID as string) as object
+            refSegments = focusedMetrics.segments
+            refSegmentTop = refSegments[Rotor.Const.Segment.TOP]
+            refSegmentRight = refSegments[Rotor.Const.Segment.RIGHT]
+            refSegmentLeft = refSegments[Rotor.Const.Segment.LEFT]
+            refSegmentBottom = refSegments[Rotor.Const.Segment.BOTTOM]
+
             segments = {}
-            validator = validators[direction]
+            validator = m.spatialValidators[direction]
             for each HID in focusItemsHIDlist
-                if HID <> focused.HID
-                    focusItem = m.focusItemStack.get(HID)
-                    focusItem.refreshBounding()
+                if HID <> focusedHID
+                    ' Try to get as FocusItem first, then as Group
+                    candidate = m.focusItemStack.get(HID)
+                    isGroup = false
+                    if candidate = invalid
+                        candidate = m.groupStack.get(HID)
+                        isGroup = true
+                    end if
+                    if candidate = invalid then continue for
+
+                    ' Skip disabled items - they should not be candidates for spatial navigation
+                    if not isGroup and candidate.isEnabled = false then continue for
+
+                    candidateMetrics = candidate.refreshBounding()
+                    candidateLeft = candidateMetrics.segments[Rotor.Const.Segment.LEFT]
+                    candidateTop = candidateMetrics.segments[Rotor.Const.Segment.TOP]
                     ' Pass appropriate reference segments based on direction
                     if direction = "left" or direction = "right"
-                        result = validator(referencePoint, focusItem.metrics.segments, refSegmentLeft, refSegmentRight)
+                        result = validator(candidateMetrics.segments, refSegmentLeft, refSegmentRight)
                     else ' up or down
-                        result = validator(referencePoint, focusItem.metrics.segments, refSegmentTop, refSegmentBottom)
+                        result = validator(candidateMetrics.segments, refSegmentTop, refSegmentBottom)
                     end if
                     if result.isValid
                         segments[HID] = result.segment
@@ -1215,6 +1273,7 @@ namespace Rotor
                 m.autoSetIsFocusedState = config.autoSetIsFocusedState ?? true
 
                 m.isEnabled = config.isEnabled ?? true
+                m.enableSpatialNavigation = config.enableSpatialNavigation ?? false
                 m.staticDirection = {}
                 m.staticDirection[Rotor.Const.Direction.UP] = config.up ?? ""
                 m.staticDirection[Rotor.Const.Direction.RIGHT] = config.right ?? ""
@@ -1242,6 +1301,7 @@ namespace Rotor
             idByKeys as object
             isEnabled as boolean
             isFocused as boolean
+            enableSpatialNavigation as boolean
             onFocusChanged as dynamic
             onFocus as dynamic
             onBlur as dynamic
@@ -1249,6 +1309,47 @@ namespace Rotor
             node as object
             widget as object
 
+            protected metrics = {
+                segments: {}
+            }
+
+            function refreshBounding() as object
+                b = m.node.sceneBoundingRect()
+                rotation = m.node.rotation
+
+                if rotation = 0
+                    if b.y = 0 and b.x = 0
+                        t = m.node.translation
+                        b.x += t[0]
+                        b.y += t[1]
+                    end if
+
+                    m.metrics.append(b)
+                    m.metrics.segments[Rotor.Const.Segment.LEFT] = {
+                        x1: b.x, y1: b.y,
+                        x2: b.x, y2: b.y + b.height
+                    }
+                    m.metrics.segments[Rotor.Const.Segment.TOP] = {
+                        x1: b.x, y1: b.y,
+                        x2: b.x + b.width, y2: b.y
+                    }
+                    m.metrics.segments[Rotor.Const.Segment.RIGHT] = {
+                        x1: b.x + b.width, y1: b.y,
+                        x2: b.x + b.width, y2: b.y + b.height
+                    }
+                    m.metrics.segments[Rotor.Const.Segment.BOTTOM] = {
+                        x1: b.x, y1: b.y + b.height,
+                        x2: b.x + b.width, y2: b.y + b.height
+                    }
+                    m.metrics.middlePoint = {
+                        x: b.x + b.width / 2,
+                        y: b.y + b.height / 2
+                    }
+                end if
+
+                return m.metrics
+            end function
+
             function getStaticNodeIdInDirection(direction as dynamic) as dynamic
                 direction = m.staticDirection[direction]
                 if Rotor.Utils.isFunction(direction)
@@ -1298,16 +1399,32 @@ namespace Rotor
                 m.defaultFocusId = config.defaultFocusId ?? ""
                 m.lastFocusedHID = config.lastFocusedHID ?? ""
                 m.enableSpatialEnter = config.enableSpatialEnter ?? false
-                m.trackDescendantFocus = config.trackDescendantFocus ?? false
+                m.enableLastFocusId = config.enableLastFocusId ?? true
+                m.enableDeepLastFocusId = config.enableDeepLastFocusId ?? false
             end sub
 
             defaultFocusId as string
             lastFocusedHID as string
-            enableSpatialEnter as boolean
-            trackDescendantFocus as boolean
+            enableSpatialEnter as dynamic ' boolean | { up?: boolean, down?: boolean, left?: boolean, right?: boolean }
+            enableLastFocusId as boolean
+            enableDeepLastFocusId as boolean
+
+            '
+            ' isSpatialEnterEnabledForDirection - Checks if spatial enter is enabled for a specific direction
+            '
+            ' @param {string} direction - The direction to check (up, down, left, right)
+            ' @returns {boolean} True if spatial enter is enabled for the direction
+            '
+            function isSpatialEnterEnabledForDirection(direction as string) as boolean
+                if Rotor.Utils.isBoolean(m.enableSpatialEnter)
+                    return m.enableSpatialEnter
+                else if Rotor.Utils.isAssociativeArray(m.enableSpatialEnter)
+                    return m.enableSpatialEnter[direction] = true
+                end if
+                return false
+            end function
             focusItemsRef as object
             groupsRef as object
-
             isFocusItem = false
             isGroup = true
 
@@ -1318,6 +1435,7 @@ namespace Rotor
             function getGroupMembersHIDs()
                 ' Collect all focusItems that are descendants of this group
                 ' Exclude items that belong to nested sub-groups
+                ' Also include direct child groups with enableSpatialNavigation: true
                 focusItems = m.focusItemsRef.getAll()
                 groups = m.groupsRef.getAll()
                 HIDlen = Len(m.HID)
@@ -1325,6 +1443,7 @@ namespace Rotor
                 groupsKeys = groups.keys()
                 groupsCount = groups.Count()
 
+                ' Collect focusItems (existing logic)
                 for each focusItemHID in focusItems
                     ' Check if focusItem is a descendant of this group
                     isDescendant = Left(focusItemHID, HIDlen) = m.HID
@@ -1344,6 +1463,36 @@ namespace Rotor
                     end if
                 end for
 
+                ' Collect direct child groups with enableSpatialNavigation: true
+                for i = 0 to groupsCount - 1
+                    childGroupHID = groupsKeys[i]
+                    childGroupHIDlen = Len(childGroupHID)
+
+                    ' Check if it's a descendant of this group (but not this group itself)
+                    if childGroupHIDlen > HIDlen and Left(childGroupHID, HIDlen) = m.HID
+                        childGroup = groups[childGroupHID]
+
+                        ' Only include if enableSpatialNavigation is true
+                        if childGroup.enableSpatialNavigation = true
+                            ' Check if it's a DIRECT child (no intermediate groups)
+                            isDirectChild = true
+                            for j = 0 to groupsCount - 1
+                                intermediateHID = groupsKeys[j]
+                                intermediateLen = Len(intermediateHID)
+                                ' Check if there's a group between this group and the child
+                                if intermediateLen > HIDlen and intermediateLen < childGroupHIDlen
+                                    if Left(childGroupHID, intermediateLen) = intermediateHID
+                                        isDirectChild = false
+                                        exit for
+                                    end if
+                                end if
+                            end for
+
+                            if isDirectChild then collection.push(childGroupHID)
+                        end if
+                    end if
+                end for
+
                 return collection
             end function
 
@@ -1368,34 +1517,40 @@ namespace Rotor
                 end if
             end function
 
-            function getFallbackIdentifier() as string
+            function getFallbackIdentifier(globalFocusHID = "" as string, direction = "" as string) as string
                 HID = ""
-                if m.lastFocusedHID <> ""
-                    return m.lastFocusedHID
-                else
-                    if Rotor.Utils.isFunction(m.defaultFocusId)
-                        defaultFocusId = Rotor.Utils.callbackScoped(m.defaultFocusId, m.widget) ?? ""
-                    else
-                        defaultFocusId = m.defaultFocusId
+                ' enableSpatialEnter is handled by capturingFocus_recursively using spatialNavigation
+                ' Here we only handle lastFocusedHID and defaultFocusId fallbacks
+
+                ' Use lastFocusedHID if available AND still exists (check both focusItems and groups)
+                if not m.isSpatialEnterEnabledForDirection(direction) and m.lastFocusedHID <> ""
+                    if m.focusItemsRef.has(m.lastFocusedHID) or m.groupsRef.has(m.lastFocusedHID)
+                        return m.lastFocusedHID
                     end if
+                end if
 
-                    if defaultFocusId <> ""
-                        focusItemsHIDlist = m.getGroupMembersHIDs()
-                        if focusItemsHIDlist.Count() > 0
+                ' Default: use defaultFocusId expression
+                if Rotor.Utils.isFunction(m.defaultFocusId)
+                    defaultFocusId = Rotor.Utils.callbackScoped(m.defaultFocusId, m.widget) ?? ""
+                else
+                    defaultFocusId = m.defaultFocusId
+                end if
 
-                            ' Try find valid HID in focusItems by node id
-                            focusItemHID = m.findHIDinFocusItemsByNodeId(defaultFocusId, focusItemsHIDlist)
-                            if focusItemHID <> ""
-                                HID = focusItemHID
-                            end if
+                if defaultFocusId <> ""
+                    focusItemsHIDlist = m.getGroupMembersHIDs()
+                    if focusItemsHIDlist.Count() > 0
 
-                        else
+                        ' Try find valid HID in focusItems by node id
+                        focusItemHID = m.findHIDinFocusItemsByNodeId(defaultFocusId, focusItemsHIDlist)
+                        if focusItemHID <> ""
+                            HID = focusItemHID
+                        end if
+
+                    else
 
-                            return defaultFocusId
+                        return defaultFocusId
 
-                        end if
                     end if
-
                 end if
 
                 return HID
@@ -1441,7 +1596,6 @@ namespace Rotor
                 super(config)
 
                 m.onSelect = config.onSelect ?? ""
-                m.enableSpatialNavigation = config.enableSpatialNavigation ?? true
                 m.enableNativeFocus = config.enableNativeFocus ?? false
             end sub
 
@@ -1453,16 +1607,12 @@ namespace Rotor
             isFocusItem = true
             isGroup = false
             enableNativeFocus as boolean
-            enableSpatialNavigation as boolean
             onSelect as dynamic
 
-            private metrics = {
-                segments: {}
-            }
             private bounding as object
 
 
-            sub refreshBounding()
+            override function refreshBounding() as object
                 b = m.node.sceneBoundingRect()
                 rotation = m.node.rotation
 
@@ -1529,7 +1679,9 @@ namespace Rotor
                     m.metrics.middlePoint = { x: rotatedMiddlePoint.x1, y: rotatedMiddlePoint.y1 }
 
                 end if
-            end sub
+
+                return m.metrics
+            end function
 
             override sub destroy()
                 m.onSelect = invalid