Initial Beta build
All checks were successful
Validate and publish Kaleido / android (push) Successful in 2m27s

This commit is contained in:
Elijah 2026-10-24 09:09:55 -07:00
commit 2b585badac
65 changed files with 3535 additions and 0 deletions

41
docs/design-system.md Normal file
View file

@ -0,0 +1,41 @@
# Kaleido visual system
The interface gives artwork priority. App chrome uses neutral near-black, charcoal, and white. Color belongs to the user's media. Navigation, cards, and player controls share the same restrained focus language.
## Layout and typography
- Horizontal safe gutter: 44 dp. Navigation: 62 dp, with centered text destinations and independent search/settings icons.
- Home retains a large cinematic feature: an 80 percent stage with original title artwork, synopsis, playback and information actions. The scene continues beneath Continue Watching; entering the rail scrolls the feature away and the backdrop follows focused titles. Features interleave recently released, highly rated unwatched, and Plex-suggested movies/shows, excluding Continue Watching. They shuffle per refresh and rotate every 12 seconds while the hero is active, pausing during row browsing.
- Movies uses a compact fixed preview above poster rows, with the backdrop and synopsis following focused titles. Recently released films and movie recommendations lead. TV uses a shorter preview, larger episode thumbnails, next episodes, newly added seasons, and then new episodes and show recommendations. Redundant TV hubs are omitted when their episode lists match exactly. These are deliberately different compositions.
- Library: title and discovery/full-library navigation share a 64 dp header. A 43 dp filter row sits immediately above the six-column poster grid.
- Browsing card widths: landscape 214 dp, TV episodes 264 dp, posters 120 dp. Landscape artwork uses 16:9; posters use 2:3. The full grid scales six columns to available width. Captions reserve a fixed height.
- Search uses three columns of landscape results. Episodes use their actual stills, preserving their native proportions instead of cropping them into posters.
- Features use original Plex clear-logo artwork within 264 × 80 dp, falling back to title text. Detail title: 34/37 sp. Library title: 29/34 sp. Discovery rail heading: 17/22 sp. Supporting information: 10/14 sp.
- Poster and thumbnail corners: 6 dp. Compact action corners: 5 dp. Cards have no idle border; a compact bottom-right check marks watched titles, or a number shows remaining episodes for a show/season when Plex provides counts. Unwatched movies have no badge. Resumed movies/episodes only show a check after the configured playback threshold (80 percent by default), even if Plex retains a historical watched flag. Completed titles with no resume position retain Plex's watched state. Progress uses a two-dp inset line.
- The abstract six-facet aperture mark is shared by the header, sign-in, app icon, TV banner, and a short cold-start splash. It uses muted sea-glass and warm ivory facets around a dark center, with no letterform or sparkle.
- Audience ratings display Rotten Tomatoes as a percentage beside a local popcorn-bucket vector, and IMDb on its native ten-point scale beside the gold IMDb logo. Both appear when Plex exposes both; TVDB is retained as a fallback when neither is available. Critic scores and unsupported providers are omitted. Stable preview focus hydrates detail metadata, where Plex exposes the full provider list. The popcorn bucket tips for audience scores below 60 percent. The IMDb vector uses the official gold primary mark and supplied clear space from the [IMDb brand toolkit](https://brand.imdb.com/imdb).
## Focus and motion
- Discovery cards keep fixed bounds and use a two-dp white focus outline. No scale or shadow changes trigger lazy-row layout or move a neighboring row.
- Text actions scale to 1.025 over 160 ms. Navigation uses text, an understated selected underline, and a translucent charcoal focus surface.
- Navigation contrast comes from a gradient extending past the controls and fading to transparent. Home/Movies/TV activate on focus. Explicit row and column links prevent beyond-bounds focus searches when holding a remote direction.
- A D-pad move predicts the actual row/column destination before starting its scroll or focus change. The target backdrop is fetched and contrast-processed through the same Coil request/cache as the visible scene. Speculative artwork uses one low-priority worker so it cannot flood normal decode workers during a burst of input. Metadata starts in parallel; the visible preview and details page share that in-flight request. Rapid navigation replaces the queued metadata target and cancels superseded artwork prefetches. Full metadata uses a 64-item LRU with a 30-second lifetime, cleared on account/server changes and refreshed after watched updates. Neutral library/search grids prefetch metadata without fetching an unused full-screen backdrop.
- Section previews settle for 120 ms (Home artwork for 90 ms), overlapping the navigation animation, and retain previous artwork until replacement data is ready. Contrast gradients are baked into a cached bitmap on a worker thread, reducing GPU overdraw. Hero recommendation changes crossfade the artwork over 220 ms, including cache hits, and fade the title/summary out for 100 ms and back in over 180 ms. Rotation pauses on the information/next controls and preserves their focus. Vertical row changes animate to explicit row/column targets; page entrances fade and slide 28 dp over 280 ms. The cold-start logo reveals over 1.1 seconds; the cover lasts 1.6 seconds with up to 600 ms extra for loading, then fades over 240 ms. It does not replay when returning from background.
- Returning from details restores the library's mode, scroll position, and previously focused title.
## Player
Controls occupy a shallow bottom gradient. A compact title, slim timeline, small time labels, central transport icons, and right-aligned track icons replace the rectangular button grid. The timeline is a true D-pad focus target: Up from transport reaches it, Left/Right seek, and Down returns to Play/Pause. Holding a direction increases the seek step. Dedicated media keys remain supported.
The controls fade and slide away after five seconds during playback. OK reveals them; Back hides them before exiting. Audio and subtitle panels open above their icons and restore focus when dismissed. A gear exposes playback mode, audio, subtitles, speed, transcode quality, and chapters. Direct stream is the saved default. The timeline includes buffered progress and server-generated video/chapter previews. Skip actions have opaque contrast surfaces.
Episode endings and Skip credits open a five-second, cancellable next-episode countdown with season episodes and related shows. Each player session has a unique Media3 session ID so overlapping Compose disposal and next-episode creation cannot collide.
Settings includes a persistent watched percentage. Timeline reporting scrobbles the item in Plex once the selected percentage is reached, retries a failed write, and avoids repeated scrobbles within the same player session. This preference belongs to Kaleido and does not change the Plex server's global settings. Explicit watched changes refresh the title and parent episode counts across browsing caches.
## Device review
Use `scripts/verify_ui.py browse` and `scripts/verify_ui.py player` with the authorized ADB connection. These drive the actual UI with remote key events, assert focus and navigation, and capture screens into the ignored `evidence/private/` directory. The player check uses the live Plex server's existing conversion mode. Run `Build.ps1 -Test` for compilation, unit tests, and lint. Inspect the optimized release APK on the TV before judging startup or animation performance.
Visual references: [Netflix's TV experience](https://about.netflix.com/en/news/unveiling-our-innovative-new-tv-experience), [Netflix's current TV layout guidance](https://help.netflix.com/en/node/321880164349028), and [Apple TV](https://www.apple.com/apple-tv-app/). The layout and artwork remain independent and Plex-backed.

View file

@ -0,0 +1,46 @@
# Browsing composition rebuild
The supplied Apple TV and Netflix references were studied before this implementation. The relevant area is the TV screen itself, excluding the surrounding television frame and Netflix's promotional page text.
## Principles observed
The scene is the page, not a banner at its top. Both references preserve a broad cinematic frame, with the principal subject in the center or right and a restrained information area on the left. The artwork continues behind the first content heading and thumbnails. Gradients provide local text contrast and a gradual lower transition without dividing the screen into an image region and a solid catalog region.
The title identity, short synopsis, and playback action form one visual group inside the artwork. Metadata is secondary, and descriptive text stays narrow enough to leave the subject visible. Title artwork supplies character that a repeated generic text heading cannot.
The first row enters close to the bottom of the viewport, inviting downward exploration. Its relationship to the hero matters more than fitting a complete catalog row into the initial screen. Subsequent discovery sections vary scale and aspect ratio; the A–Z library is a different browsing task and remains a compact poster grid.
## What the preceding implementation missed
The old home artwork ended around 57 percent of the screen, followed by black catalog space. It also cropped a 16:9 backdrop into a shallow banner. Movies and TV discovery opened with a utility heading and uniformly sized rows rather than a featured scene. Making those elements smaller did not change their composition.
## New structure and review targets
- Home, Movies Discover, and TV Discover share a full-viewport backdrop canvas with light parallax and a localized left contrast gradient.
- The first rail overlaps the lower portion of that same canvas. The artwork does not end before the rail.
- Original Plex clear-logo artwork supplies title identity, with a real text fallback. Episode stills, scene backdrops, and portrait posters have separate contexts.
- Continue Watching uses compact landscape cards; recently added films use posters; larger featured recommendations and other landscape rails provide discovery variation.
- Navigation floats over the scene. Entering the dedicated A–Z view restores compact catalog chrome and the six-column filtered/sorted grid.
- Screen changes use a short entrance fade. Focus changes use bounded scale, a thin image outline, and debounced backdrop previews.
Validate screenshots from the onn against the supplied references for scene prominence, subject framing, title hierarchy, row overlap, and lack of a horizontal banner/catalog boundary. Record actual remaining shortcomings and iterate before delivery. The player is outside this redesign's scope.
## Device iterations
The first rebuilt composition made the scene dominant, but its title treatment was too large and the first row entered too low. The second reduced the logo to 264 dp and the hero stage to 77.5 percent of the viewport. Continue Watching identity moved toward the center of each thumbnail so it remains recognizable as the row enters the screen.
Movies retains the live Matchbox feature and leads with recently released posters, followed by larger movie recommendations. TV leads with resume-ready episodes, then newly aired episodes and series recommendations. These use the server's real hub contents; a duplicate recently-added episode hub is omitted when it exactly matches the newly-aired hub. Home remains a mixed destination.
Remote testing exposed focus boundaries between floating chrome and lazy content. Explicit focus links now connect primary navigation, section controls, and hero actions. Entering the full library focuses its Library control, and returning from details restores the selected discovery card.
A solid backing behind scrolled navigation proved too visually heavy in device review. It was replaced with an extended gradient that fades into the content. Section controls retreat while browsing lower rails and reappear when returning to the top; D-pad navigation scrolls the hero into place before requesting focus.
The optimized APK was installed on the authorized onn at 192.168.50.195. Five remote-driven browsing checks passed: live Home composition, card focus restoration after details, separate Movies discovery and filtered A–Z library, TV next/new episode rows, and section Back navigation. Release compilation, unit tests, and lint passed with no lint errors. Captures remain in the ignored evidence/private directory. The player was not part of this browsing review.
## Current direction after performance and usability review
Home again uses the large cinematic feature and playback actions. The compact fixed preview is specific to Movies, following focused posters above recently released films and movie recommendations. TV uses a shorter preview and larger episode thumbnails, with next episodes, newly added seasons, then new episodes and show recommendations. Full libraries retain their separate filtered A-Z poster grid.
Fixed card geometry, explicit D-pad row/column targets, cached backdrop contrast and debounced preview changes replace scaling cards, repeated lazy focus searches and full-screen gradient overdraw. Startup server discovery runs independently of tab requests: a cold-start tab switch previously cancelled initialization and left Movies/TV blank. Section data now updates atomically and empty discovery results offer a library action.
The earlier device-review paragraphs describe previous iterations, not the current test status. Current evidence and regression results are recorded under evidence/private; use scripts/repro_runtime.py sections, browse, episode, credits and postplay, plus scripts/verify_ui.py, for the applicable live device loops.

View file

@ -0,0 +1,29 @@
# Device regression review - 2026-10-23
Target: the authorized onn at `192.168.50.195:5555`, package `tv.kaleido.app`. Other applications and the launcher were not modified. Screenshots, traces, UI dumps and server-specific logs stay in ignored `evidence/private/`.
## Browsing
- Cold-start switching to Movies reproduced an empty page: tab loading cancelled server initialization before library discovery finished. Initialization now has its own job; section requests update their cache and visible results atomically. `scripts/repro_runtime.py sections` passes the same startup switch, TV loading and cached Movies return.
- Home again has the large cinematic feature with Play/Resume, information and feature navigation. Movies has the compact focused-title preview with recent-release posters and recommendations. TV has wider next-episode thumbnails, newly added seasons and new episodes. A-Z remains a separate filtered poster grid.
- All six `scripts/verify_ui.py browse` checks passed, including primary tab activation on focus, details/card focus restoration, library navigation and a live Plex PIN with cancellation preserving the connection.
- Fixed card geometry and explicit row/column navigation remove horizontal vertical drift. Cached bitmap contrast reduces backdrop GPU work. API JSON parsing is off the main thread.
- Profiling found substantial interpreted Compose/layout work immediately after ADB installation. Android reported `status=verify`, not profile-guided compilation. Installing the bundled baseline profile and compiling **only Kaleido** with `speed-profile` changed the measured browsing loop from p95 65 ms to 20 ms, median 14 ms, GPU p95 5 ms. Horizontal card bounds retained the same Y coordinate. This is a device stress measurement, not a guarantee of zero dropped frames. Baseline rules now also include app browsing paths.
For reproducible performance checks, install the release, send `androidx.profileinstaller.action.INSTALL_PROFILE` to Kaleido's ProfileInstallReceiver, compile its package with `cmd package compile -f -m speed-profile tv.kaleido.app`, then run `scripts/repro_runtime.py browse`. Do not benchmark debug builds or compare different compilation states. Ordinary sideloads receive profile-guided optimization through Android's background dex optimization; immediate first-run measurements can therefore be slower.
## Playback and account connection
- Six live Android integration tests passed: encrypted session persistence, library paging/filter/search/details/hubs, show/season/episode access, a real Plex PIN, generated JPEG previews/new seasons, and a server decision copying the supported HEVC test episode's video.
- Next episode previously crashed with `Session ID must be unique`. Each controller now owns a unique Media3 session ID. The actual episode replacement loop passes and reaches the expected next title.
- Plex HLS uses an absolute timeline. Removing the duplicate seek-start offset fixes resume/progress and credits-marker positions.
- Natural episode completion reached post-play, waited five seconds and reached READY on the next episode. Credits skipping also opened season/related rows and its autoplay cancellation test passed.
- Player tests exercised real video, scrubbing previews, audio/subtitle panels, speed changes and Direct stream selection. A separate targeted regression verifies that one Back hides controls, OK reveals them, playback auto-hides them and Back exits. Explicit preview-key handling fixes Back clearing focus before reaching the player handler.
- Direct stream is the default preference. The client augments the existing Plex HEVC target instead of supplying competing transcode targets. The server can still choose conversion for media it cannot remux using the negotiated profile. Original-file and compatibility playback remain available.
- The onn's ADB screen captures omit the tested HEVC picture even while Media3 reports rendered frames. The user confirmed that the actual TV displays the video. Do not treat that capture alone as a black-video failure or silently force transcoding.
- Skip actions use an opaque contrast surface. The timeline draws buffered and played ranges separately and shows generated server previews or chapter artwork when available.
- The release ZIP was checked for the actual private test token and `.env`: neither is present. The test connection is encrypted private device data. Settings exposes Plex account linking and server discovery.
Release compilation, unit tests and lint passed with zero lint errors (existing warnings remain). Temporary debugging log tags were removed.
The final release recheck after adding the app baseline rules passed again: median 15 ms, p95 27 ms, GPU p95 5 ms, stable row Y coordinates. Results remain dependent on device compilation state; some frames still miss a 60 Hz deadline under the burst test.