[tvOS] focus navigation issue in series details page

[OlivierAlbertini]

Describe the bug

Issue summary

When navigating down from season buttons to episodes on the tvOS series details page, focus gets lost instead of moving to the first episode thumbnail. This creates a poor user experience where users have to manually search for focus or repeatedly attempt navigation.

Devices

Apple Tv 4k A1842
tvOS 18.5[22L572]

Apple TV (just before the 4k one)
tvOS 18.5[22L572]

Note: It seems not to happen on the simulator Apple Tv 4k 3rd generation (18.4)

Root cause investigation

Initial Symptoms

• Focus disappears when navigating from season selector to episodes section
• Sometimes focus navigation works, sometimes it doesn't
• User gets "stuck" around season buttons unable to proceed smoothly
• Issue does NOT occur in the old Swiftfin project

Technical details

The race condition

1. User navigates down from seasons to episodes
2. Focus guide onContentFocus fires → calls getContentFocus() → sets focusedEpisodeID
3. Season selection change fires → calls getContentFocus() again → overwrites focusedEpisodeID
4. Multiple rapid assignments cause SwiftUI focus system to fail
5. Result: focusedEpisodeID ends up as nil despite valid assignments

Debug logs showing the issue

🎯 EpisodeHStack: Focus guide onContentFocus triggered
🎯 EpisodeHStack: getContentFocus() called, state: content
🎯 EpisodeHStack: Setting focus to lastFocused: 78d37e0779f1a4671f6ac0c26a04f36a
🎯 EpisodeHStack: About to set focusedEpisodeID = 78d37e0779f1a4671f6ac0c26a04f36a
🎯 EpisodeHStack: After assignment, focusedEpisodeID = nil  ← BUG HERE

🎯 SeasonHStack: Focus guide onContentFocus triggered
🎯 SeasonHStack: focusedSeason changed
🎯 EpisodeHStack: Focus guide onContentFocus triggered  ← SECOND CALL CONFLICTS

My current solution

Simplified Natural Focus (Current Solution)

.focusGuide(focusGuide, tag: "episodes", onContentFocus: {
    if focusedEpisodeID == nil {
        focusedEpisodeID = viewModel.elements.first?.id
    }
})

Application version

latest on master branch

Where did you install the app from?

None

Device information

Apple Tv 4k A1842

OS version

18.5[22L572]

Jellyfin server version

10.10.7

---

Let me know if you want a PR

[JPKribs]

I believe this is already resolved in main and will be in our next tvOS release. For information about our next release please see: #1294

Resolved by: #1542

The issue was that, when continuing a series, focusing the episodes would focus you onto the next episode. The package we used for this HStack was not scrolling over on first appear. As a result, the cursor would try to jump to an element that did not exist.

If this is this still recreatable please let me know. In testing now, I am unable to recreate this. Would you be able to provide a video demonstrating how this is created on the non-4K tvOS? I could just be misunderstanding the steps you are taking to cause this to occur.

[OlivierAlbertini]

I believe this is already resolved in main and will be in our next tvOS release. For information about our next release please see: #1294

Resolved by: #1542

The issue was that, when continuing a series, focusing the episodes would focus you onto the next episode. The package we used for this HStack was not scrolling over on first appear. As a result, the cursor would try to jump to an element that did not exist.

If this is this still recreatable please let me know. In testing now, I am unable to recreate this. Would you be able to provide a video demonstrating how this is created on the non-4K tvOS? I could just be misunderstanding the steps you are taking to cause this to occur.

Hi, I can't do it for the non-4k tvOS as its busy, but here with the 4k
I just checkout the main branch.

test.4k.mp4

[JPKribs]

That appears to be related to our original issue where it wants to jump to S01E09 as this is the next up episode. It cannot jump there as it it's not in view. As a result, this locks up at the season picker. From my end, I am not able to recreate this on the emulator nor on hardware. Tested on 4K Gen 3 on 18.5, 4K @ 1080p Gen 3 on 18.5 on Main. Also tested on 4K Gen 2 on 18.5 on Main.

Are you pulling this from the Main branch or a specific commit? How are you entering the view? Is this bandwidth related, like the season contents load in much later after the view is set?

If you go to an show that is unwatched or where the resumable item is E01, E02, or E03, do you get this issue? From your video, this appears to be related to the scrolling. Can you confirm that the version you have pulled is using the correct branch:

Alternatively, please try manually mapping the branch to the following commits:

Change: CollectionVGrid Main -> 70db2318ce64d49aa8b536e0623b96cb323fbdf1
Change: CollectionHStack Main -> 03dc666e8b20ec216fda60f55ccc0eeaabbc5fad

And confirm that this is still persistent.

[OlivierAlbertini]

Are you pulling this from the Main branch or a specific commit?

It target the main branch and this is a fresh install

The issue is not hard to produce on the hardware, I can't reproduce on simulator (but simulators are on 18.4, not 18.5 on my side)

[JPKribs]

I rebuilt and tested this with several different entry points today. Apologies, but I am still not able to recreate this on real hardware. That being said, I am using the 3rd Gen 4K so there is a chance our experiences are different. If I had to guess, I would say that we need to increase the delay for older devices. However, I cannot test this on my end as I do not have a device that can recreate this issue. If you are able, can you test this by going to:

Swiftfin/Swiftfin tvOS/Views/ItemView/Components/EpisodeSelector/Components/HStacks/EpisodeHStack.swift

and changing line 59 from:

DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {

to something like:

DispatchQueue.main.asyncAfter(deadline: .now() + 0.25) {

Or a longer delay like 0.5 if 0.25 does not resolve this.

This all being said, the self-built version of Swiftfin can often differ from what we see in TestFlight or on the AppStore. The most common issue is that XCode will cache package versions, meaning you may be using a different version of an underlying package that the project has moved on from. There have been a few Issues generated like this that have not necessarily reflected the final product. I'm not saying your issue is necessarily related to that, but I cannot recreate this on what hardware is available to me and the simulator (as you also mentioned) works without issue.

Hopefully the change to the delay results in an improvement to what you are seeing! Otherwise, I will be unable to assist in troubleshooting. At that point, I would be need to lean on other individuals who can successfully test this to assist in a resolution.

I'm sorry I can't be more hopeful! Please let me know if the change above works!