axiom-tvos（公理电视）

tvOS Development

Overview

tvOS shares UIKit and SwiftUI with iOS but diverges in critical ways that catch every iOS developer. The three most dangerous assumptions: (1) local files persist, (2) WebView exists, (3) focus works like @FocusState.

Core principle tvOS is not "iOS on TV." It has a dual focus system, no persistent local storage, no WebView, and a remote with two incompatible generations. Treat it as its own platform.

tvOS 26 Adopts Liquid Glass design language with new app icon system. See axiom-liquid-glass for implementation patterns.

tvOS Porting Triage

Before shipping a tvOS port, verify these five areas — they account for 90% of tvOS-specific bugs:

"It compiles on tvOS" means nothing. These five areas compile fine and fail at runtime.

When to Use This Skill

• Building a new tvOS app or adding tvOS target
• Porting an iOS app to tvOS
• Debugging focus, remote input, or storage issues on tvOS
• Working with AVPlayer, TVUIKit, or text input on tvOS

Example Prompts

These are real questions developers ask that this skill answers:

1. "I'm porting my iOS app to tvOS and focus navigation doesn't work"

-> The skill explains the dual focus system (UIKit Focus Engine vs @FocusState) and common traps

2. "My tvOS app loses all data between launches"

-> The skill explains there is no persistent local storage and shows the iCloud-first pattern

3. "How do I handle Siri Remote input in SwiftUI on tvOS?"

-> The skill covers both generations of remote and the three input layers (SwiftUI, UIKit gestures, GameController)

4. "WebView doesn't work on tvOS, how do I display web content?"

-> The skill shows JavaScriptCore for parsing and native rendering alternatives

Red Flags

If ANY of these appear, STOP:

• "I'll just use the same storage code as iOS" — tvOS has no Document directory
• "WebView will work for this" — No WebView on tvOS at all (Apple HIG: "Not supported in tvOS")
• "@FocusState handles focus" — tvOS has a dual focus system; @FocusState alone is incomplete
• "I'll save to Application Support" — It's Cache-only; the system deletes files when app is not running
• "Standard UITextField will work" — tvOS text input triggers a fullscreen keyboard; consider the shadow input pattern
• "I'll just use the same AVPlayer code" — tvOS needs.ambient audio session on launch, custom Menu button handling, and buffer tuning. Default iOS AVPlayer setup causes audio session conflicts and broken back navigation.

1. Focus Engine vs @FocusState

tvOS has two focus systems that must coexist. This is the #1 source of confusion for iOS developers.

The Dual System

When Each Applies

User swipes on remote → UIKit Focus Engine handles it (always)
Code sets @FocusState → SwiftUI handles it (sometimes overridden by Focus Engine)

The trap: @FocusState can set focus programmatically, but the UIKit Focus Engine is the ultimate authority. If the Focus Engine considers a view unfocusable, @FocusState assignments are silently ignored.

UIKit Focus Engine API

The UIFocusEnvironment protocol (implemented by UIView, UIViewController, UIWindow) provides:

class MyViewController: UIViewController {
    // Priority-ordered list of where focus should go
    override var preferredFocusEnvironments: [UIFocusEnvironment] {
        [preferredButton, fallbackButton]
    }

    // Validate proposed focus changes
    override func shouldUpdateFocus(
        in context: UIFocusUpdateContext
    ) -> Bool {
        // Return false to block focus movement
        return context.nextFocusedView != disabledButton
    }

    // Respond to completed focus changes
    override func didUpdateFocus(
        in context: UIFocusUpdateContext,
        with coordinator: UIFocusAnimationCoordinator
    ) {
        coordinator.addCoordinatedAnimations {
            context.nextFocusedView?.transform = CGAffineTransform(scaleX: 1.1, y: 1.1)
            context.previouslyFocusedView?.transform = .identity
        }
    }

    // Request focus update (async)
    func moveFocusToPreferred() {
        setNeedsFocusUpdate()      // Schedule update
        updateFocusIfNeeded()       // Execute immediately
    }
}

UIFocusGuide — Bridging Navigation Gaps

When focusable views aren't in a direct grid layout, the Focus Engine can't find them by scanning directionally. UIFocusGuide creates invisible focusable regions that redirect to real views:

let focusGuide = UIFocusGuide()
view.addLayoutGuide(focusGuide)

// Position the guide between two non-adjacent views
NSLayoutConstraint.activate([
    focusGuide.leadingAnchor.constraint(equalTo: leftButton.trailingAnchor),
    focusGuide.trailingAnchor.constraint(equalTo: rightButton.leadingAnchor),
    focusGuide.topAnchor.constraint(equalTo: leftButton.topAnchor),
    focusGuide.heightAnchor.constraint(equalTo: leftButton.heightAnchor)
])

// When focus enters the guide, redirect to the target view
focusGuide.preferredFocusEnvironments = [rightButton]

SwiftUI Focus API

struct ContentView: View {
    @FocusState private var focusedItem: MenuItem?

    var body: some View {
        VStack {
            ForEach(MenuItem.allCases) { item in
                Button(item.title) { select(item) }
                    .focused($focusedItem, equals: item)
            }
        }
        .focusSection()       // Group focusable items for navigation
        .defaultFocus($focusedItem, .home)  // Set initial focus
    }
}

Key SwiftUI focus modifiers for tvOS:

• .focused(_:equals:) — Bind focus to a value
• .focusable() — Make custom views focusable
• .focusSection() — Group related items for directional navigation
• .defaultFocus(_:_:) — Set where focus starts in a scope

Default Focusable Elements

UIButton, UITextField, UITableViewCell, and UICollectionViewCell are focusable by default. Custom views need canBecomeFocused (UIKit) or .focusable() (SwiftUI). The top-left item receives initial focus at launch.

Common Focus Gotchas

2. Siri Remote Input

Two generations with different hardware — your code must handle both.

Generation Differences

Standard SwiftUI Modifiers (Preferred)

For most UI, SwiftUI handles remote input automatically through the focus system:

Button("Play") { startPlayback() }
    .focused($isFocused)  // Automatically responds to remote navigation

List(items) { item in
    Text(item.title)
}
// List navigation works automatically with remote
// Note: First item receives focus by default on tvOS — use .defaultFocus() to override

Gesture Recognizers (UIKit)

Detect specific button presses and gestures via UIKit recognizers:

// Detect Play/Pause button
let playPause = UITapGestureRecognizer(target: self, action: #selector(handlePlayPause))
playPause.allowedPressTypes = [NSNumber(value: UIPress.PressType.playPause.rawValue)]
view.addGestureRecognizer(playPause)

// Detect swipe on touchpad
let swipe = UISwipeGestureRecognizer(target: self, action: #selector(handleSwipe))
swipe.direction = .right
view.addGestureRecognizer(swipe)

Available UIPress.PressType values: .menu, .playPause, .select, .upArrow, .downArrow, .leftArrow, .rightArrow, .pageUp, .pageDown

Low-Level Press Handling

For fine-grained control, override UIResponder press methods:

override func pressesBegan(_ presses: Set<UIPress>, with event: UIPressesEvent?) {
    for press in presses {
        if press.type == .select {
            handleSelectDown()
        }
    }
}

override func pressesEnded(_ presses: Set<UIPress>, with event: UIPressesEvent?) {
    for press in presses {
        if press.type == .select {
            handleSelectUp()
        }
    }
}

// Always implement all four: pressesBegan, pressesEnded, pressesChanged, pressesCancelled

Game Controller Framework (Raw Input)

For custom interactions (scrubbing, games), access the Siri Remote as a GCMicroGamepad:

import GameController

NotificationCenter.default.addObserver(
    forName: .GCControllerDidConnect, object: nil, queue: .main
) { notification in
    guard let controller = notification.object as? GCController,
          let micro = controller.microGamepad else { return }

    // Touchpad as analog D-pad (-1.0 to 1.0)
    micro.dpad.valueChangedHandler = { _, xValue, yValue in
        handleRemoteInput(x: xValue, y: yValue)
    }

    // reportsAbsoluteDpadValues: true = absolute position, false = relative movement
    micro.reportsAbsoluteDpadValues = false

    // allowsRotation: true = values adjust when remote is rotated
    micro.allowsRotation = false

    // Face buttons
    micro.buttonA.pressedChangedHandler = { _, _, pressed in }
    micro.buttonX.pressedChangedHandler = { _, _, pressed in }
    micro.buttonMenu.pressedChangedHandler = { _, _, pressed in }
}

Progress Bar Scrubbing

UIPanGestureRecognizer with virtual damping for smooth seeking:

let panGesture = UIPanGestureRecognizer(target: self, action: #selector(handlePan))

@objc func handlePan(_ gesture: UIPanGestureRecognizer) {
    let velocity = gesture.velocity(in: view)
    let dampingFactor: CGFloat = 0.002  // Tune for feel

    switch gesture.state {
    case .changed:
        let seekDelta = velocity.x * dampingFactor
        player.seek(to: currentTime + seekDelta)
    default:
        break
    }
}

3. Storage Constraints

This is the most dangerous iOS assumption on tvOS. tvOS has no Document directory. All local storage is Cache that the system can delete at any time. Skipping iCloud integration means 2-3 weeks debugging intermittent "data disappears" bugs that only happen on real devices between app launches.

From Apple's App Programming Guide for tvOS: "Every app developed for the new Apple TV must be able to store data in iCloud and retrieve it in a way that provides a great customer experience."

What tvOS Has

Size Limits

• App bundle: 4 GB maximum
• NSUserDefaults / UserDefaults: 500 KB maximum (Apple docs; not the 4 MB iOS gets). Available but subject to system purge — not guaranteed persistent between sessions
• On-demand resources: Available for read-only assets the OS manages
• Local cache: No guaranteed size; system can purge while app is not running

What This Means

• Every local file can vanish between app launches
• SQLite databases stored locally will be deleted
• Your app must survive with zero local data
• Downloaded data is NOT deleted while the app is running — only between sessions

Recommended Pattern

// ✅ CORRECT: iCloud as primary, local as cache only
func loadData() async throws -> [Item] {
    // 1. Try iCloud first (persistent)
    if let cloudData = try? await fetchFromICloud() {
        // Cache locally for offline use
        try? cacheLocally(cloudData)
        return cloudData
    }

    // 2. Fall back to local cache (may not exist)
    if let cached = try? loadFromLocalCache() {
        return cached
    }

    // 3. Start fresh — this is normal on tvOS
    return []
}

Database Recommendations

See axiom-sqlitedata for CloudKit SyncEngine patterns, axiom-storage for full storage decision tree.

4. No WebView

tvOS has no WKWebView, no SFSafariViewController, no WebView. Apple HIG explicitly states: web views are "Not supported in tvOS."

What You Can Do

JavaScriptCore for Parsing

JavaScriptCore provides a JavaScript execution engine without DOM or web rendering. Available on tvOS.

import JavaScriptCore

let context = JSContext()!

// Evaluate scripts
context.evaluateScript("""
    function parsePlaylist(m3u8Text) {
        return m3u8Text.split('\\n')
            .filter(line => !line.startsWith('#'))
            .filter(line => line.trim().length > 0);
    }
""")

// Pass data safely via setObject (avoids injection)
context.setObject(m3u8Content, forKeyedSubscript: "rawContent" as NSString)
let result = context.evaluateScript("parsePlaylist(rawContent)")

// Convert back to Swift types
let segments = result?.toArray() as? [String] ?? []

Key classes: JSVirtualMachine (execution environment), JSContext (script evaluation), JSValue (type bridging)

Limitation: No DOM, no web rendering, no fetch/XMLHttpRequest. Pure JavaScript execution only.

Local HTTP Server for HLS

When you need to serve modified m3u8 playlists to AVPlayer:

// Use Swifter (httpswift/swifter) or GCDWebServer
// Serve rewritten m3u8 on localhost, point AVPlayer to it
let localURL = URL(string: "http://localhost:8080/playlist.m3u8")!
let playerItem = AVPlayerItem(url: localURL)

5. TVUIKit Components

tvOS-exclusive UIKit components. Bridge to SwiftUI via UIViewRepresentable.

TVPosterView

Media content display with built-in focus expansion and parallax:

import TVUIKit

let poster = TVPosterView(image: UIImage(named: "moviePoster"))
poster.title = "Movie Title"
poster.subtitle = "2024"

// Focus expansion and parallax happen automatically
// Access the underlying image view:
poster.imageView.adjustsImageWhenAncestorFocused = true

TVLockupView

Base class for TVPosterView — a flexible container managing content with focus behavior:

let lockup = TVLockupView()
lockup.contentView.addSubview(customView)
lockup.headerView = headerFooter   // TVLockupHeaderFooterView
lockup.footerView = footerFooter
// showsOnlyWhenAncestorFocused: header/footer visibility on focus

Other TVUIKit Components

TVDigitEntryViewController

System-provided passcode/PIN entry (tvOS 12+):

let digitEntry = TVDigitEntryViewController()
digitEntry.numberOfDigits = 4
digitEntry.titleText = "Enter PIN"
digitEntry.promptText = "Enter your parental control code"
digitEntry.isSecureDigitEntry = true

present(digitEntry, animated: true)

digitEntry.entryCompletionHandler = { pin in
    guard let pin else { return }  // User cancelled
    authenticate(with: pin)
}

// Reset entry
digitEntry.clearEntry(animated: true)

6. Text Input on tvOS

tvOS text input is fundamentally different from iOS. Apple recommends minimizing text input in your UI.

Three Approaches

UITextField (Fullscreen Keyboard)

The primary text input method. Calling becomeFirstResponder() presents a fullscreen keyboard:

let textField = UITextField()
textField.placeholder = "Enter name"
textField.becomeFirstResponder()  // Presents keyboard immediately
// Done button returns user to previous page
// Built-in Next/Previous buttons navigate between text fields

Shadow Input Pattern (SwiftUI)

When you want a custom-styled input trigger in SwiftUI:

struct TVTextInput: View {
    @State private var text = ""
    @State private var isEditing = false

    var body: some View {
        Button {
            isEditing = true
        } label: {
            HStack {
                Text(text.isEmpty ? "Search..." : text)
                    .foregroundStyle(text.isEmpty ? .secondary : .primary)
                Spacer()
                Image(systemName: "keyboard")
            }
            .padding()
            .background(.quaternary)
            .clipShape(RoundedRectangle(cornerRadius: 10))
        }
        .sheet(isPresented: $isEditing) {
            TVKeyboardSheet(text: $text)
        }
    }
}

UISearchController (Inline Keyboard)

For search interfaces — all input on a single line, but very limited customization:

let searchController = UISearchController(searchResultsController: resultsVC)
searchController.searchResultsUpdater = self
// Cannot customize text traits or add input accessories

SwiftUI .searchable()

SwiftUI's .searchable() modifier works on tvOS and presents the system search keyboard. Use it for standard search patterns:

NavigationStack {
    List(filteredItems) { item in
        Text(item.title)
    }
    .searchable(text: $searchText, prompt: "Search movies")
}

For custom search UI beyond what .searchable() offers, fall back to the shadow input pattern above.

7. AVPlayer Tuning

tvOS media apps need specific AVPlayer configuration for good UX.

Essential Settings

let player = AVPlayer(url: streamURL)

// automaticallyWaitsToMinimizeStalling defaults to true (iOS 10+/tvOS 10+)
// Set false for immediate playback when synchronizing players
// or when you want playback to start ASAP from a non-empty buffer
player.automaticallyWaitsToMinimizeStalling = false

// Buffer hint — 0 means system chooses automatically
// Higher values reduce stalling risk but consume more memory
player.currentItem?.preferredForwardBufferDuration = 30

// Audio session — don't interrupt other apps' audio on launch
try AVAudioSession.sharedInstance().setCategory(.ambient)
// Switch to .playback when user presses play

Custom Dismiss Logic

The default swipe-down gesture dismisses the player. Override for media apps:

class PlayerViewController: AVPlayerViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        // Handle Menu button for custom back navigation
        let menuPress = UITapGestureRecognizer(
            target: self, action: #selector(handleMenu)
        )
        menuPress.allowedPressTypes = [
            NSNumber(value: UIPress.PressType.menu.rawValue)
        ]
        view.addGestureRecognizer(menuPress)
    }

    @objc func handleMenu() {
        if isShowingControls {
            hideControls()
        } else {
            dismiss(animated: true)
        }
    }
}

8. Menu Button State Machine

The Siri Remote Menu button doubles as "back" and "dismiss." Media apps need a state machine to handle it correctly.

The Problem

State: Playing with controls visible
  Menu press → Hide controls (not dismiss)

State: Playing with controls hidden
  Menu press → Show "are you sure?" or dismiss

State: In submenu/settings overlay
  Menu press → Close overlay (not dismiss player)

Pattern

enum PlayerState {
    case loading        // Buffering / loading content
    case playing        // Controls hidden
    case controlsShown  // Controls visible
    case submenu        // Settings/subtitles overlay
}

func handleMenuPress(in state: PlayerState) -> PlayerState {
    switch state {
    case .submenu:
        dismissSubmenu()
        return .controlsShown
    case .controlsShown:
        hideControls()
        return .playing
    case .playing:
        dismiss(animated: true)
        return .playing
    case .loading:
        cancelLoading()
        dismiss(animated: true)
        return .loading
    }
}

9. Network Differences

IPv6 Priority

Apple TV strongly prefers IPv6. All App Store apps must support IPv6-only networks (DNS64/NAT64). If your backend is IPv4-only, connections may be slower or fail on some networks.

Device Performance Variance

Test on older hardware. The Apple TV HD is still in use and dramatically slower than 4K models.

10. Developer Experience

Debug-Only Input Macros

Test without Siri Remote in Simulator using keyboard shortcuts:

#if DEBUG
extension View {
    func debugOnlyModifier() -> some View {
        self.onKeyPress(.space) {
            print("Space pressed — simulating select")
            return .handled
        }
    }
}
#endif

View Inspection Helper

#if DEBUG
extension View {
    func debugBorder() -> some View {
        border(.red, width: 1)
    }
}
#endif

Simulator Limitations

• Simulator does not accurately simulate Focus Engine behavior
• Always test focus navigation on a real Apple TV device
• Simulator keyboard input!= Siri Remote input
• Performance profiling must happen on device (especially Apple TV HD)

Anti-Rationalization

Resources

Source: "Surviving tvOS" (Ronnie Wong, 2026) — tvOS engineering log for Syncnext media player

Apple Docs: /tvuikit, /uikit/uifocusenvironment, /uikit/uifocusguide, /swiftui/focus, /gamecontroller/gcmicrogamepad, /avfoundation/avplayer, /javascriptcore

Apple Guides: App Programming Guide for tvOS (storage, input, gestures), HIG Web Views (tvOS exclusion)

WWDC: 2016-215, 2017-224, 2021-10023, 2021-10081, 2021-10191, 2023-10162, 2025-219

Skills: axiom-storage, axiom-sqlitedata, axiom-avfoundation-ref, axiom-hig-ref, axiom-liquid-glass