feat(client/android): add Android TV support by vad612 · Pull Request #2864 · OutlineFoundation/outline-apps

vad612 · 2026-09-26T10:49:13Z

Closes #735

Why

The Android client can already run on Android TV, but its portrait-only manifest and pointer-oriented web UI make it impractical to use with a TV remote. Users cannot reliably move focus, activate controls, navigate dialogs and menus, or use the server list without a mouse.

What changes

Keep a single Android APK and the existing org.outline.android.client application ID for phones, tablets, and TVs.
Advertise an optional Leanback launcher and optional touchscreen support, and package a correctly sized TV banner.
Detect Android TV at runtime through the Cordova plugin and lazily enable TV-only navigation behavior.
Add D-pad spatial navigation across nested Shadow DOM, dialogs, menus, the navigation drawer, server cards, and text-entry boundaries.
Add visible keyboard/remote focus states and keyboard activation semantics to interactive controls.
Let Android use the device's natural orientation, so TV devices render in landscape.
Document the shared Android/TV build behavior.

The navigation module is loaded only on detected Android TV devices, so the regular phone/tablet interaction path remains unchanged.

Testing

Automated:

npm run action client/web/build
npm run action client/web/test — 75 tests passed
ESLint on all changed JavaScript and TypeScript files
GTS lint on all changed TypeScript files
npm run lint:lit — 0 errors (three pre-existing CSS container-query warnings)
License-header check on all changed source files
Android debug APK build

Manual:

Android Studio Television (1080p) emulator
Xiaomi Mi TV (MiTV_MOOQ1) over ADB
Verified D-pad traversal and activation for the server list, connect/disconnect control, navigation drawer, settings lists, add-access-key dialog, and server overflow/delete menu
Verified closing the navigation drawer with Right and closing/reselecting drawer destinations
Verified installation under the existing package ID, TV launcher banner, access-key import, and a successful VPN connection

Long access keys can be entered with the Android TV remote keyboard or another external keyboard; the D-pad can then move from the text field to the dialog actions.

greptile-apps · 2026-09-26T10:53:49Z

Confidence Score: 5/5

[Medium risk] Adds Android TV support with D-pad navigation.

The PR appears safe to merge based on the reviewed changes.

Summary

The PR adds Android TV launcher resources and runtime detection to both Android hosts, then enables D-pad navigation in the shared client UI.

The changes since the previous review extend TV setup to Capacitor, adjust off-screen focus and dialog navigation, and guard errored connection controls.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Android app starts] --> B{Cordova or Capacitor}
  B --> C[Native Android TV detection]
  C --> D[Set TV flag and dispatch ready event]
  D --> E{TV device?}
  E -- Yes --> F[Load shared D-pad navigation]
  E -- No --> G[Keep standard interaction]

_{Reviews (2) · Last reviewed commit: "fix(client/android): address Android TV ..."}

fortuna · 2026-09-26T10:56:33Z

A big question for tv is how to enter the access key. How do you propose we do that? Topping the whole thing is not practical.

vad612 · 2026-09-26T11:09:28Z

Thanks for raising this. I don’t expect users to type the full access key with the D-pad. The intended MVP flow is Android TV’s standard remote text input: focus the field, open the keyboard in a phone’s TV remote app, and paste the complete Outline key there. I verified this end to end on a Xiaomi TV using an iOS remote keyboard — I copied the key on the iPhone and pasted it directly into the TV field. The existing ss:// intent is also available when the link can be opened on the TV.

I intentionally left a QR-code or phone-pairing flow out of this PR to keep its scope focused on making the existing client usable with a remote. If you consider a first-party quick-transfer flow necessary for Android TV support, I can implement it, either in this PR or as a follow-up.

fortuna · 2026-09-28T09:46:49Z

Thanks. I think a QR code flow would be helpful, but I agree it should be a separate change.

@vad612 can you please share screenshots of how it looks like so we know the layout is not broken?

@ohnorobo please review.

vad612 · 2026-09-28T11:26:23Z

ohnorobo · 2026-10-07T10:29:11Z

@vad612 thanks so much for this contribution and all the testing on Android TV!

Currently in CI the client-web test is failing, which is causing some of the other CI not to run. I think the fix should be small. Could you fix that and see that the web tests are all passing, then I'll re-run the full CI?

Alternatively, if you make a vad612:master<-vad612:feat/android-tv PR within your repo fork you should be able to check the full set if CI runs without having to wait for me to approve them.

fortuna · 2026-10-07T17:53:18Z

This file is a red flag to me. Why are we rolling our our own navigation? I'm sure other TV apps don't need to do that. What's the proper way to do this? We should not reinvent the wheel.

I investigated native and web spatial-navigation libraries. They can select the next element, but do not replace the integration needed for this WebView UI’s Shadow DOM, Material components, dialogs, and focus restoration. Our earlier Norigin attempt still required most of that integration code, so I kept the tested module rather than adding a dependency without substantially reducing it

fortuna · 2026-10-07T18:03:12Z

+        if (this.tvNavigationLoad !== navigationLoad || !this.isConnected) {
+          return;
+        }
+        this.removeTvNavigation = installTvNavigation(this.shadowRoot);


What does installTvNavigation do?

Can't we always install it? Please explain the tradeoff.

It installs D-pad, activation, Back, and focus handlers and returns a cleanup function. Enabling those handlers on phones or desktop would interfere with normal keyboard navigation, so installation is limited to Android TV

vad612 · 2026-10-07T19:57:46Z

Thank you for the thoughtful review and for recognizing the Android TV testing. I’ve been actively using Outline on my own Xiaomi TV for about two weeks, and I’d be happy to keep refining both the implementation and the remote-control experience until they meet the project’s quality bar.
I also took your CI guidance on board. Before updating this PR, I now validate changes in a PR within my fork; the latest revision passed the full CI there. I appreciate your help and feedback as we work toward a solid result.

vad612 requested a review from a team as a code owner September 26, 2026 10:49

greptile-apps Bot reviewed Sep 26, 2026

View reviewed changes

Comment thread client/web/ui_components/tv-navigation.js

Comment thread client/web/views/root_view/add_access_key_dialog/index.ts Outdated

Comment thread client/web/views/servers_view/server_list_item/server_card/legacy.ts

Comment thread client/web/ui_components/app-root.js Outdated

fortuna requested a review from ohnorobo September 28, 2026 09:45

fortuna reviewed Sep 28, 2026

View reviewed changes

Comment thread client/capacitor/plugins/capacitor-plugin-outline/src/web.ts

Comment thread client/web/views/servers_view/server_connection_indicator/index.ts

fortuna reviewed Sep 28, 2026

View reviewed changes

Comment thread client/package.json Outdated

vad612 added 3 commits October 6, 2026 21:10

feat: add Android TV client support

666351b

fix(client/android): address Android TV review feedback

fc653d1

fix(client/android): simplify Android TV focus navigation

c53c193

vad612 force-pushed the feat/android-tv branch from 89991c3 to c53c193 Compare October 6, 2026 18:18

vad612 mentioned this pull request Oct 7, 2026

Android TV support (fork CI validation) vad612/outline-apps#1

Closed

test(client): stabilize Android TV menu focus test

c1246af

vad612 mentioned this pull request Oct 7, 2026

fix(client/android): validate Android TV support vad612/outline-apps#2

Draft

fix(client/tv): simplify banner resources and navigation markup

cd26068

vad612 force-pushed the feat/android-tv branch from 6c53d34 to cd26068 Compare October 7, 2026 17:20

fortuna requested changes Oct 7, 2026

View reviewed changes

refactor(client): pass Android TV state through platform

207f26c

vad612 requested a review from fortuna October 8, 2026 14:35

Conversation

vad612 commented Sep 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What changes

Testing

Uh oh!

greptile-apps Bot commented Sep 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 5/5

Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fortuna commented Sep 26, 2026

Uh oh!

vad612 commented Sep 26, 2026

Uh oh!

fortuna commented Sep 28, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vad612 commented Sep 28, 2026

Uh oh!

ohnorobo commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

fortuna Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

vad612 Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fortuna Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

vad612 Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

vad612 commented Oct 7, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vad612 commented Sep 26, 2026 •

edited

Loading

greptile-apps Bot commented Sep 26, 2026 •

edited

Loading

ohnorobo commented Oct 7, 2026 •

edited

Loading