Document native player UX baseline audit

docs/native-player-ux-audit.md

@@ -0,0 +1,124 @@
+# Native Player UX Baseline Audit
+
+Date: 2026-05-26 21:49 EDT  
+Issue: `dreamio-ee1`
+
+## Scope
+
+This audit covers the current VLC-backed native playback experience before Liquid Glass and broader UX changes. The primary implementation is `Dreamio/NativePlayerViewController.swift`, backed by `Dreamio/NativePlaybackBackend.swift` and `Dreamio/VLCNativePlaybackBackend.swift`.
+
+## Current Experience Summary
+
+Dreamio presents native playback as a full-screen black video surface with a compact bottom control tray, a top-right close button, a loading spinner, and a simple centered failure label. Controls are built directly in UIKit and are intentionally lightweight.
+
+Current user-facing controls:
+
+- Top-right close button.
+- Bottom compact blur-backed tray capped at 430 points wide.
+- Elapsed time, scrubber, and remaining time row.
+- Audio menu button.
+- 15-second jump back.
+- Play/pause.
+- 15-second jump forward.
+- Captions menu button with subtitle delay controls.
+- Tap anywhere on the playback surface to reveal or hide controls.
+- Auto-hide while playing after 3 seconds.
+
+## Existing Strengths
+
+- **Minimal interruption:** The player is full-screen and hides chrome while playback is active.
+- **Compact controls:** Recent work reduced the overlay footprint so video content stays dominant.
+- **Core playback affordances exist:** Play/pause, seeking, jump controls, elapsed/remaining time, audio tracks, captions, and subtitle delay are present.
+- **Backend-aware disabling:** Seek and jump controls disable when VLC reports a non-seekable stream.
+- **Track menus are cached:** Audio and captions menus avoid unnecessary rebuilds through signature values.
+- **Subtitle handoff exists:** The native player can receive subtitle candidates from the Stremio Web bridge and attach them through the backend.
+- **Safe-area aware:** Close and controls are anchored to safe-area guides.
+
+## Current UX Gaps
+
+### Visual Treatment
+
+- The control surface uses `UIBlurEffect(style: .systemUltraThinMaterialDark)` plus manual tint/border styling, not iOS 26 Liquid Glass.
+- Buttons are individual translucent wells rather than an intentional grouped glass system.
+- There is no bottom readability scrim; bright video frames could reduce time label and icon contrast.
+- Loading and failure states are plain compared with the rest of the player chrome.
+
+### Touch Targets and Hierarchy
+
+- Secondary controls are 36×36 points, below Apple’s recommended 44×44 point minimum target.
+- The play/pause button is only 42×42 points, so the primary action is not dominant enough.
+- Audio and captions have the same visual weight as transport controls even when unavailable or secondary.
+- Disabled captions do not currently mirror the explicit alpha treatment used by audio.
+
+### Scrubbing
+
+- The scrubber has a compact thumb and row, but no preview/target time bubble.
+- During scrubbing, the elapsed label updates, but the user does not get a larger focused scrubbing affordance.
+- There is no haptic feedback on scrub begin/end or jump actions.
+
+### Gestures
+
+- Single tap toggles controls, but no richer playback gestures exist.
+- There is no double-tap left/right jump behavior.
+- There is no center tap play/pause behavior separate from chrome visibility.
+- Gesture conflict handling will need care because `tap.cancelsTouchesInView = false` currently allows control touches to pass through.
+
+### Auto-Hide
+
+- Controls hide after 3 seconds while playing, which can feel short for subtitle/audio menu interactions or careful scrubbing.
+- The auto-hide timer only checks `backend.isPlaying`; future changes should explicitly protect menu presentation, scrubbing, loading, paused, and failure states.
+
+### Loading and Failure
+
+- Startup loading is only a white `UIActivityIndicatorView` over black.
+- Failure is a plain text label with no retry, close action, or debug affordance.
+- The 20-second startup timeout is useful, but the user receives little guidance after it fires.
+
+### Accessibility
+
+- Buttons have accessibility labels, but no accessibility hints.
+- The scrubber has no dynamic accessibility value describing elapsed and remaining time.
+- Jump actions are not exposed as custom accessibility actions on the player surface.
+- Motion preferences are not checked before animations.
+- Dynamic Type behavior for the compact controls has not been explicitly protected.
+
+### Device Adaptation
+
+- The bottom tray is capped at 430 points, which is good for phones but underuses iPad/large landscape space.
+- Button sizing and row spacing are fixed; orientation-specific density has not been tuned.
+- The supported orientations allow all but upside down, so landscape crowding should be part of validation.
+
+## Implementation Constraints
+
+- `NativePlaybackBackend` currently exposes no thumbnail/preview frames, so scrub previews should begin as a time bubble rather than video thumbnails.
+- The backend exposes seekability, duration, position, audio tracks, subtitle tracks, and subtitle delay, which is enough for richer controls without backend changes.
+- The app must preserve compatibility with builds where MobileVLCKit is unavailable through the existing fallback backend behavior.
+- Liquid Glass APIs should be gated with iOS availability checks and keep the current blur/material implementation as fallback.
+- Multiple glass controls should be grouped with container effects where possible to avoid expensive standalone glass rendering.
+
+## Recommended Next Implementation Slice
+
+Start with a low-risk visual and ergonomics pass:
+
+1. Add iOS 26 Liquid Glass availability-gated styling for the main controls tray and interactive buttons, preserving the current blur fallback.
+2. Increase button targets to at least 44×44 points and make play/pause 54–58 points.
+3. Add a subtle bottom gradient scrim behind controls for contrast.
+4. Extend auto-hide timing from 3 seconds to about 4.5 seconds and prevent hiding while scrubbing.
+5. Add missing accessibility hints and scrubber accessibility value.
+
+Defer until the second implementation slice:
+
+- Scrubber target time bubble.
+- Double-tap jump gestures.
+- Center tap play/pause behavior.
+- Glass-backed loading and failure cards with retry.
+- iPad-specific wider layout.
+
+## Validation Targets for Future Changes
+
+- Build the workspace with Xcode command-line tools.
+- Test seekable and non-seekable streams.
+- Test streams with one audio track, multiple audio tracks, no captions, embedded captions, and external captions.
+- Verify controls remain usable in portrait and landscape.
+- Verify VoiceOver labels, hints, and scrubber values.
+- Verify older iOS fallback styling still works when Liquid Glass is unavailable.