Merge the Linux apps GUI (Add games entries, Linux badge/filter, game page summary + missing-library warning, Frame-only actions, change program)

CLAUDE.md

@@ -96,6 +96,11 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
     set: the name on a colour from the title hash + the APK icon, `steam_set_for`; 2D Android apps get no store lookups) and tags: how it runs, the original platform
     (Meta Quest / Oculus Rift), genres, user tags — merged with tags set in Steam (non-Steam shortcuts can't hold a
     description).
+  - Linux apps (GitHub #31, library kind `linux`, `linux.<slug>`): GUI = Add games → "Add a Linux app (arm64)…" /
+    "…folder…" (`app.add_linux` job → `pipeline.add_linux_app`); game page `linux_summary` (program + Change…, AppImage,
+    OpenXR, source) instead of recipe/patches, `C.missing_libraries` callout (Frame deployment, else last install);
+    no Analyze/Rebuild/recipe/share/Game settings actions, Frame only; platform "Linux" badge + library filter; Steam
+    tags "Linux app on Frame"/"Linux"; `_follow_catalog` skips them; local files of a lone AppImage = the file only.
   - Quest/Rift twins stay separate entries, shown and named in Steam "Title (Quest)"/"(Rift)" (`core/titles.py`).
   - `Recipe.as_is` = install unchanged (pre-patched libraries): `pipeline.prepare_as_is`; auto for APKs that already
     contain FrameBridge (`frame_patched`). For Rift it changes nothing (the dump is never modified; the Frame copy

README.md

@@ -28,6 +28,8 @@ Install games that target the Meta Quest, Android, or general PCVR onto your **V
   curved and 360° layers); game settings as simple switches.
 - **Beyond Quest:** Android apps as windows, PC VR via Proton or Revive, Windows (non-VR) games via Proton, a Files
   tab with drag and drop.
+- **Linux apps:** install arm64 Linux apps (AppImage, a folder, or a zip/tar archive) on the Frame with a Steam
+  shortcut; they run natively on SteamOS.
 - **Screenshots tab:** the screenshots you took in the headset, sorted by game (matched by play time) and day;
   view them and download them to your computer.
 - **Self-updating** releases, redacted diagnostics, one-click problem reports and working-config sharing.

docs/INSTALL.md

@@ -132,6 +132,20 @@ starts it if asked). FramePort installs it on the Frame and Proton runs it as a
 it shows up in the Frame's Steam library tagged "Windows game on Frame". Whether a game runs depends on Proton on ARM
 (x86 games run through emulation).
 
+## Linux apps (arm64)
+
+The Frame runs SteamOS on an arm64 CPU, so native Linux apps built for **aarch64/arm64** run on it directly (no
+Android container, no Proton). **Add games → Add a Linux app (arm64)…** takes an AppImage or a `.zip`/`.tar.gz`/
+`.tar.xz` archive; **Add a Linux app folder…** takes an unpacked app. FramePort finds the program that starts it (the
+game page's **Change…** picks another one) and whether it's a VR (OpenXR) app. **Install on Frame** uploads it
+unchanged and adds it to the Frame's Steam library, tagged "Linux app on Frame"; Play, launch tests and Uninstall
+work like for other games.
+
+- x86_64 builds can't run on the Frame: FramePort says so when you add one. Look for an aarch64/arm64 download.
+- The app must bring the libraries SteamOS doesn't have. If some are missing, the install reports them and the game
+  page lists them: look for a build that includes them.
+- From the command line: `frameport add-linux <AppImage, folder or archive> [--exe <program>]`.
+
 ## Files on the Frame (videos, documents, mods, saves)
 
 The **Files** tab manages files on the Frame over the same connection as installs; no other transfer app is needed.
@@ -167,6 +181,7 @@ and `frameport <command> --help` describe every option. The main ones:
 | Command | What it does |
 |---|---|
 | `scan <folder>` / `list` / `show <game>` | add games, list the library, show a game's analysis and patches |
+| `add-linux <path>` | add an arm64 Linux app (AppImage, folder or archive) |
 | `recipe <game> --enable/--disable <patch>` | change a game's patches (`patches` lists them all) |
 | `build <game>` / `install <game>` / `test <game>` | build, install on the Frame (`--to pc` for PC VR on this PC), launch test |
 | `frame discover` / `frame connect` / `frame info` | find, pair with and describe the Frame |

scripts/ui_smoke.py

@@ -3,6 +3,9 @@
 Chromium (Playwright). Any exception in a view shows up on stdout; screenshots land in --out.
 
     FRAMEPORT_HOME=<a test data dir> python scripts/ui_smoke.py --out /tmp/shots [--game <package>]
+
+--linux adds two pretend arm64 Linux apps (an AppImage and a VR folder app, tiny fake ELF files in FRAMEPORT_HOME)
+and renders their pages; with --fake-frame the AppImage is "installed" with a missing library.
 """
 from __future__ import annotations
 
@@ -144,6 +147,11 @@ class FakeTarget:
         self.games = [{"package": g["package"], "kind": "quest", "title": g.get("title"),
                        "apk_size": (g.get("data_bytes") or 0) + 2**28, "sha256": g["build"]["sha256"],
                        "recipe": {"patches": (g.get("recipe") or {}).get("patches", [])}} for g in works[:count]]
+        # --linux: the AppImage is on the Frame, but SteamOS lacks one of its libraries
+        self.games += [{"package": g["package"], "kind": "linux", "title": g.get("title"), "apk_size": 2**26,
+                        "apk_present": True, "recipe": None, "exe": g.get("exe"),
+                        "missing_libraries": ["libwebkit2gtk-4.1.so.0"]}
+                       for g in library.games() if g.get("kind") == "linux" and g["package"] == LINUX_APPIMAGE]
 
     def describe(self) -> dict:
         return {"hostname": "steamframe", "os": "SteamOS", "os_version": "3.8", "build_id": "20260922",
@@ -187,6 +195,36 @@ def open_type_dialog(app: FramePortApp) -> None:
     listener.on_key_down(SimpleNamespace(key="Enter"))
 
 
+LINUX_APPIMAGE = "linux.venera"  # --linux's packages
+LINUX_FOLDER = "linux.matineevr"
+
+
+def _elf(machine: int = 183, appimage: bool = False, extra: bytes = b"") -> bytes:
+    """A minimal ELF header (183 = aarch64): enough for FramePort's Linux app detection."""
+    head = bytearray(64)
+    head[:4], head[4], head[5] = b"\x7fELF", 2, 1
+    if appimage:
+        head[8:11] = b"AI\x02"
+    head[18:20] = machine.to_bytes(2, "little")
+    return bytes(head) + extra
+
+
+def add_fake_linux_apps() -> None:
+    """--linux: an AppImage and a VR app folder (with a helper program, so "Change program…" shows) in the library."""
+    from frameport import pipeline
+    from frameport.core.paths import user_data_dir
+
+    base = user_data_dir() / "smoke-linux"
+    app = base / "MatineeVR"
+    (app / "lib").mkdir(parents=True, exist_ok=True)
+    (base / "Venera-2.4.2-aarch64.AppImage").write_bytes(_elf(appimage=True, extra=b"\0" * 4096))
+    (app / "MatineeVR").write_bytes(_elf(extra=b"\0" * 8192))
+    (app / "crashpad_handler").write_bytes(_elf())
+    (app / "lib" / "libopenxr_loader.so.1").write_bytes(_elf(extra=b"xrCreateInstance"))
+    pipeline.add_linux_app(base / "Venera-2.4.2-aarch64.AppImage")
+    pipeline.add_linux_app(app)
+
+
 STEP_SECONDS = 4  # per screen (the screenshot is taken ~3 s in)
 
 
@@ -216,7 +254,10 @@ def main() -> int:
                     help="open the install questions for these games, then click each dialog's main button twice "
                          "(a double click must not duplicate dialogs); nothing is installed")
     ap.add_argument("--docs", action="store_true", help="only the screens used in the docs (Library, --game, Frame)")
+    ap.add_argument("--linux", action="store_true", help="add two pretend arm64 Linux apps and render their pages")
     args = ap.parse_args()
+    if args.linux:
+        add_fake_linux_apps()
     global STEP_SECONDS
     if args.hover:
         STEP_SECONDS = 7
@@ -251,6 +292,18 @@ def main() -> int:
         steps.append(("screenshot-viewer", lambda a: a.screenshots_view.viewer(0)))
         steps.append(("type-on-frame", lambda a: (a.page.pop_dialog(), open_type_dialog(a))))
         steps.append(("power-confirm", lambda a: (a.page.pop_dialog(), a.frame_power("restart"))))
+    if args.linux:
+        def linux_filter(a, value):
+            a.navigate(0)
+            time.sleep(2)
+            a.library_view._set("platform", value)
+        steps = [("library", lambda a: a.navigate(0)), ("library-linux", lambda a: linux_filter(a, "linux")),
+                 ("linux-appimage", lambda a: (a.library_view._set("platform", "all"), a.open_game(LINUX_APPIMAGE))),
+                 ("linux-folder", lambda a: a.open_game(LINUX_FOLDER)),
+                 ("linux-folder-customize", lambda a: a.open_game(LINUX_FOLDER, advanced=True)),
+                 ("linux-change-program", lambda a: a.choose_exe(LINUX_FOLDER)),
+                 ("frame", lambda a: (a.page.pop_dialog(), a.navigate(1))),
+                 ("linux-menu", lambda a: (a.navigate(0), time.sleep(3), a.library_view.open_menu(LINUX_APPIMAGE)))]
     if args.install_questions:
         queued: list[str] = []
 

src/frameport/artwork/steam.py

@@ -299,6 +299,8 @@ def _placeholder(out_dir: Path, title: str, icon_file: Path | None, apk) -> dict
 def original_platform(entry: dict) -> str:
     """What the game was made for (a Steam tag)."""
     extra = (entry.get("analysis") or {}).get("extra") or {}
+    if entry.get("kind") == "linux":
+        return "Linux"
     if entry.get("kind") == "rift":
         if extra.get("flat"):
             return "Windows"
@@ -315,7 +317,7 @@ def steam_tags(entry: dict, where: str = "frame") -> list[str]:
     kind = ((entry.get("analysis") or {}).get("extra") or {}).get("vr_kind") or "quest"
     flat = bool(((entry.get("analysis") or {}).get("extra") or {}).get("flat"))
     runs = TAG if where != "frame" else ("Windows game on Frame" if flat else "PC VR on Frame") \
-        if entry.get("kind") == "rift" else \
+        if entry.get("kind") == "rift" else "Linux app on Frame" if entry.get("kind") == "linux" else \
         "Quest on Frame" if kind == "quest" else "Android on Frame"
     base = [runs, original_platform(entry)]
     genres = ((entry.get("details") or {}).get("genres") or [])[:4]

src/frameport/core/library.py

@@ -58,6 +58,8 @@ def _follow_catalog(data: dict) -> bool:
     settings["recipes.app_version"] = __version__
     for pkg, g in (data.get("games") or {}).items():
         r, a = g.get("recipe"), g.get("analysis")
+        if g.get("kind") == "linux":  # installed as it is: no recipe to derive
+            continue
         if app_updated and isinstance(a, dict):
             changed |= _refresh_data_fields(g, a)
         if not isinstance(r, dict) or not isinstance(a, dict) or r.get("source") == "user":
@@ -223,7 +225,7 @@ def _migrate(data: dict) -> bool:
         # Android apps without VR gain the default-on "Hide Android's navigation bar" patch
         for g in (data.get("games") or {}).values():
             a, r = g.get("analysis") or {}, g.get("recipe")
-            if isinstance(r, dict) and (a.get("extra") or {}).get("vr_kind") == "none":
+            if isinstance(r, dict) and (a.get("extra") or {}).get("vr_kind") == "none" and g.get("kind") != "linux":
                 r.setdefault("patches", {}).setdefault("device.hide_navbar", {})
                 r.setdefault("reasons", {}).setdefault(
                     "device.hide_navbar", "2D app: Android's navigation buttons would cover the app's own controls.")

src/frameport/core/titles.py

@@ -16,7 +16,7 @@ def twins(games: list[dict]) -> set[str]:
     by_pkg = {g["package"]: g for g in games}
     quest_by_title = {}
     for g in games:
-        if g.get("kind") != "rift":
+        if g.get("kind") not in ("rift", "linux"):  # (Linux apps have no Quest/Rift twin)
             quest_by_title.setdefault(_norm(g.get("title") or ""), []).append(g["package"])
     out = set()
     for g in games:
@@ -41,11 +41,13 @@ def display_title(game: dict, twin_set: set[str] | None = None) -> str:
 
 def counterparts(game: dict, games: list[dict]) -> list[dict]:
     """The other-platform versions of this game in the library."""
+    if game.get("kind") == "linux":
+        return []
     rift = game.get("kind") == "rift"
     t = _norm(game.get("title") or "")
     out = []
     for g in games:
-        if g["package"] == game["package"] or (g.get("kind") == "rift") == rift:
+        if g["package"] == game["package"] or (g.get("kind") == "rift") == rift or g.get("kind") == "linux":
             continue
         linked = (rift and game.get("quest_package") == g["package"]) or \
             (not rift and g.get("quest_package") == game["package"])

src/frameport/diag/bundle.py

@@ -170,6 +170,18 @@ def package_listing(g: dict) -> dict[str, object]:
                     pe[rel] = {"error": str(exc)}
             out["pe.json"] = pe
         return out
+    if g.get("kind") == "linux":  # the app's file list (a lone AppImage: only it, not the folder it's in)
+        root, extra = Path(g.get("game_dir") or ""), (g.get("analysis") or {}).get("extra") or {}
+        paths = [root / f for f in extra["files"]] if extra.get("files") else \
+            sorted(root.rglob("*")) if root.is_dir() else []
+        files = []
+        for p in paths:
+            if p.is_file():
+                files.append([p.relative_to(root).as_posix(), p.stat().st_size])
+                if len(files) >= 20000:
+                    break
+        out["files.json"] = files
+        return out
     apk = Path(g.get("apk") or "")
     if not apk.is_file():
         return out

src/frameport/diag/issue.py

@@ -55,7 +55,7 @@ def working_config_url(g: dict, recipe_yaml: str, status: str, notes: str, env:
                        red: redact.Redactor | None = None) -> str:
     red = red or redact.Redactor()
     title = g.get("title") or g["package"]
-    kind = "Oculus Rift (PC VR)" if g.get("kind") == "rift" else "Meta Quest"
+    kind = {"rift": "Oculus Rift (PC VR)", "linux": "Linux app (arm64)"}.get(g.get("kind"), "Meta Quest")
     a = g.get("analysis") or {}
     game = f"{title} — {g['package']} ({kind}, version {a.get('version') or '?'}, {a.get('engine') or '?'} / " \
            f"{a.get('xr') or '?'})"

src/frameport/locales/template.json

@@ -54,7 +54,9 @@
  "A game is running on the Frame": "",
  "A game is running on the Frame. Close it in the headset first, then try again.": "",
  "a known blocker": "",
+ "A Linux app for arm64 (AppImage, .zip or .tar.gz)": "",
  "A Meta Quest game (APK). It's rebuilt for the Frame and runs in Lepton, Valve's Android container.": "",
+ "A native Linux program built for arm64 (aarch64), like the Frame's own CPU. It's installed unchanged and runs directly on SteamOS (no Android container, no Proton), started from the Frame's Steam library. VR apps use the Frame's OpenXR runtime.": "",
  "A new FramePort version is ready to install": "",
  "A recipe is the list of patches FramePort applies to a game before installing it. Known-good recipes were tested on a Frame; the others are suggested from the game's engine and VR API. Hover a patch for why it's there.": "",
  "A VR app made for another Android headset. OpenXR apps are translated like Quest games; apps built on a headset maker's own SDK (Pico, HTC Wave) can't run on the Frame.": "",
@@ -67,6 +69,8 @@
  "AC Nexus: no AppSW at 72 Hz": "",
  "AC Nexus: no AppSW at 90 Hz": "",
  "Activity": "",
+ "Add a Linux app (arm64)…": "",
+ "Add a Linux app folder…": "",
  "Add a tag": "",
  "Add an APK file": "",
  "Add an APK file…": "",
@@ -77,12 +81,15 @@
  "Add videos": "",
  "Add videos and files…": "",
  "Add your games": "",
+ "Add {name}": "",
  "Added automatically (engine, VR API or store genre)": "",
  "Added automatically when needed": "",
  "Added {n} game": [
   "",
   ""
  ],
+ "Added {title}": "",
+ "Added {title}: it starts with {exe}. Not the right program? Change it on its page.": "",
  "Adds a launcher entry point (Lepton additionally needs category LAUNCHER, see the Frame 'launcher' fix).": "",
  "Adds a real ovrMessageType_ToString (OVRPort's platform compat library) for games whose platform loader lacks it (e.g. The Climb 2). OVRPort 1.2.5+ adds the same library itself; then this is skipped.": "",
  "Adds a small piece of Meta's platform library that some games need to start.": "",
@@ -106,6 +113,8 @@
  "Also delete this game's files on this PC ({size})": "",
  "Also in your library: {value} version": "",
  "Also remove FramePort's games and files from the Frame": "",
+ "An AppImage is a Linux app packed into one file. FramePort unpacks it on the Frame once, so it starts without FUSE.": "",
+ "An AppImage, a folder or a .zip/.tar archive with a Linux program built for arm64 (aarch64). x86_64 builds can't run on the Frame. The app must bring the libraries SteamOS doesn't have.": "",
  "An ordinary Android app or game (no VR). It's installed unchanged and runs in Lepton, Valve's Android container.": "",
  "Analyze again": "",
  "Analyze {title} again": "",
@@ -117,6 +126,7 @@
  "Any": "",
  "APK": "",
  "Appearance": "",
+ "AppImage": "",
  "Apply the suggested patches and reinstall": "",
  "Apps that suggest controller bindings only for Meta's newer profiles (Touch Plus, Touch Pro), which the Frame's runtime rejects (XR_ERROR_PATH_UNSUPPORTED), get the same bindings as oculus/touch_controller instead (components Touch lacks are dropped). Without it such apps get no controller input.": "",
  "Artwork for {get}": "",
@@ -151,10 +161,12 @@
  "Ceiling height for scene_emul.": "",
  "Ceiling height of the pretend room.": "",
  "Change executable…": "",
+ "Change program…": "",
  "Change settings…": "",
  "Changes apply the next time FramePort starts.": "",
  "Changes apply to the next install. Hover a chip above for why it was suggested.": "",
  "Changes are used the next time the game starts. Not sure? Leave a setting as it is.": "",
+ "Change…": "",
  "Check": "",
  "Check exe": "",
  "Check for new versions automatically": "",
@@ -319,6 +331,7 @@
  "folder and everything in it": "",
  "Folder name": "",
  "Folder to upload to the Frame": "",
+ "Folder with a Linux app for arm64": "",
  "Folder with VR games (Android APKs or PC VR games)": "",
  "For apps that only know Quest 3/Pro controllers: without it they get no buttons.": "",
  "For games that crash right after you return to them (e.g. after the Steam menu).": "",
@@ -339,6 +352,7 @@
  "FramePort": "",
  "FramePort can't replace itself in {value} (no permission): opening the release page to download it": "",
  "FramePort checks GitHub for a new release every few hours and shows it in the sidebar and the Library. \"Update now\" downloads it, checks its checksum (and on Windows its signature), closes FramePort and opens the new version; your games, settings and Frame connection are kept. With automatic install, the download happens in the background and the new version starts next time.": "",
+ "FramePort found more than one arm64 program in this app. Pick the one that starts it (helpers such as crash reporters or updaters are the wrong choice).": "",
  "FramePort found more than one program that could start this game. Pick the one you'd double-click to play it. Oculus builds usually work better with Revive than Steam builds.": "",
  "FramePort has Steam on the Frame download Proton and the runtime it needs (about 1 GiB). Steam restarts once, which closes a running game.": "",
  "FramePort installs games on the Frame over your network": "",
@@ -439,6 +453,8 @@
  "Installed · launch test failed": "",
  "Installed, but it didn't start properly: ": "",
  "Installing": "",
+ "Installs the app as it is, unpacked on the Frame, with an entry in its Steam library": "",
+ "Installs the app as it is, with an entry in the Frame's Steam library": "",
  "Installs the game exactly as it is: no patches (your copy is already patched)": "",
  "into {value}": "",
  "It can't be reached (asleep, turned off or out of Wi-Fi). Wake it or turn it on: FramePort continues by itself, and uploads pick up where they stopped.": "",
@@ -449,6 +465,7 @@
  "It trusts this app, turns on Developer Mode and installs Lepton if needed. Turning on Developer Mode closes the desktop; the setup finishes on its own and FramePort connects by itself. You only do this once.": "",
  "It was removed from the library.": "",
  "It will be closed without saving. Continue?": "",
+ "It won't start on the Frame: SteamOS doesn't have these libraries and the app doesn't bring them. Look for a build of the app that includes them, then install that one.": "",
  "It works: share…": "",
  "Java runtime": "",
  "Java, OVRPort and apksigner are ready.": "",
@@ -496,6 +513,9 @@
  "Lets you read logs/attach. Some Unreal games abort under CheckJNI when debuggable; the Frame 'nodebug' fix undoes it.": "",
  "Lets you type into this app's text fields on the Frame (they'd close at once).": "",
  "Library": "",
+ "Linux": "",
+ "Linux app (arm64)": "",
+ "Linux VR app · OpenXR": "",
  "Loading…": "",
  "Loads FramePort's OpenXR layer under Proton on the Frame. The Frame's SteamVR runtime only accepts OpenXR 1.0 apps, but Proton's VR helper asks for 1.1, so without the layer VR never starts (the game shows as a flat window, or Revive fails with 'Unable to load LibOVRRT DLL'); the layer retries as 1.0. It also emulates xrConvertTimespecTimeToTimeKHR if a runtime refuses it. Ignored on this PC.": "",
  "Loads libglshim.so ahead of libEGL in every engine library that fetches GL through eglGetProcAddress. Fixes Quest-only leniency that Mesa/Zink rejects: #pragma before #extension, implicit int/float conversions (enables GL_EXT_shader_implicit_conversions), and multiview shaders used on single-view framebuffers (hides GL_OVR_multiview; gl_hide_multiview=0 turns that off). Logs every failed shader with its source lines (logcat tag GLShim). Symptom: black screen with working audio in a GLES game.": "",
@@ -543,6 +563,7 @@
  "New Frame? Run one command on it and FramePort does the rest. Did this once already? Your Frame appears under step 2.": "",
  "New name": "",
  "Next": "",
+ "No": "",
  "No activity": "",
  "no answer from the Frame": "",
  "No artwork could be downloaded from that {source} result; the current artwork stays. Try another one.": "",
@@ -555,6 +576,7 @@
  "No release notes.": "",
  "No screenshots yet": "",
  "No Unreal crash reporter": "",
+ "No: a 2D app": "",
  "None": "",
  "None found": "",
  "Normal": "",
@@ -657,6 +679,7 @@
  "Prevents a start-up crash in some Unreal games.": "",
  "Previous": "",
  "Problems and feedback": "",
+ "Program": "",
  "Proton couldn't run a test program (see the log)": "",
  "Proton debug log (Frame)": "",
  "Proton is Valve's Windows compatibility layer. On the Frame it runs PC VR games. Its ARM64 build isn't installed by default; FramePort can install it (Steam restarts once).": "",
@@ -755,6 +778,7 @@
  "Room width": "",
  "Rotate quads 180°": "",
  "Runs directly — no Revive needed": "",
+ "Runs natively on SteamOS, started from the Frame's Steam library": "",
  "Runs Oculus PC games on OpenXR": "",
  "Runs OVRPort and apksigner": "",
  "Runs the game directly": "",
@@ -1035,6 +1059,7 @@
  "Videos": "",
  "Videos, documents, mods and saves on your Steam Frame": "",
  "View screenshot": "",
+ "VR (OpenXR)": "",
  "VrApi → OpenXR adapter (OVRPort)": "",
  "VrApi → OpenXR bridge": "",
  "Vulkan shader fixes": "",
@@ -1076,6 +1101,8 @@
  "Writes liboverport.config.so with runtime options.": "",
  "Writes the conversion's settings into the game.": "",
  "XR_FB_passthrough via ALPHA_BLEND (Frame greyscale cameras).": "",
+ "Yes": "",
+ "Yes: uses the Frame's OpenXR runtime": "",
  "Yesterday": "",
  "You have the latest version as of the last check ({when}).": "",
  "You have {version}. {how}": "",
@@ -1111,6 +1138,7 @@
  "{len} selected": "",
  "{message} The Frame's Steam library still shows the old art.": "",
  "{n_pc} on this PC": "",
+ "{name} isn't a Linux app (an AppImage, a Linux program or a .zip/.tar archive)": "",
  "{n} file": [
   "",
   ""
@@ -1166,6 +1194,7 @@
  "{title}: launch test {verdict} (furthest: {value})": "",
  "{title}: Steam artwork updated on the Frame": "",
  "{user}@{host} · {get} {get2} (build {get3})": "",
+ "{value:.0f} MiB": "",
  "{value:.1f} GiB": "",
  "{value} didn't work out": "",
  "{value} failed ({returncode})": "",

src/frameport/pipeline.py

@@ -254,6 +254,12 @@ def fetch_details(package: str, reporter: Reporter | None = None) -> dict:
 def set_exe(package: str, exe: str) -> dict:
     """The user picked the program that starts a Rift game: re-analyze with it (keeps recipe choices and tags)."""
     entry = library.game(package)
+    if entry and is_linux(entry):  # a Linux app: the same source again, with this program
+        folder = Path(entry["game_dir"])
+        if not (folder / exe).is_file():
+            raise FileNotFoundError(folder / exe)
+        source = ((entry.get("analysis") or {}).get("extra") or {}).get("source") or entry["game_dir"]
+        return add_linux_app(source, exe=exe)
     if not entry or entry.get("kind") != "rift":
         raise ValueError(f"{package} is not a Rift game")
     folder = Path(entry["game_dir"])
@@ -301,16 +307,26 @@ def add_linux_app(path: Path | str, reporter: Reporter | None = None, exe: str |
                 else "none", "abis": ["arm64-v8a"], "libs": [], "extra": {**info, "vr_kind": "openxr" if info["openxr"]
                                                                             else "none", "source": str(path)}}
     old = library.game(package) or {}
+    root = Path(info["root"])
+    try:  # what an install uploads (the library's size sort, the Frame's free-space check)
+        size = sum((root / f).stat().st_size for f in info["files"]) if info["files"] else \
+            sum(f.stat().st_size for f in root.rglob("*") if f.is_file())
+    except OSError:
+        size = 0
     fields = dict(kind="linux", name=path.name, apk=None, game_dir=info["root"], exe=info["exe"], data_dir=None,
-                  origin=str(path.parent), analysis=analysis, suggested=library.recipe_to_dict(recipe))
+                  origin=str(path.parent), analysis=analysis, suggested=library.recipe_to_dict(recipe),
+                  data_bytes=size)
     if not old:
         fields.update(title=info["title"], recipe=library.recipe_to_dict(recipe), status="unknown")
     library.upsert_game(package, **fields)
     try:
         from .artwork import fetch
 
-        fetch.artwork_dir(package)  # placeholder art (name on a colour) until the user picks some
-    except Exception:  # noqa: BLE001
+        fetch.artwork_dir(package)
+        from .artwork import steam
+
+        steam.ensure_cover(package)  # placeholder art (name on a colour) until the user picks some
+    except Exception:  # noqa: BLE001 - artwork is optional
         pass
     return library.game(package)
 
@@ -541,13 +557,17 @@ def local_game_files(package: str) -> list[Path]:
     paths: list[Path] = []
     if g.get("kind") == "rift":
         paths += [Path(g["game_dir"])] if g.get("game_dir") else []
+    elif is_linux(g):
+        paths += linux_local_files(g)
     else:
         paths += [Path(p) for p in (g.get("apk"), g.get("data_dir")) if p]
     b = g.get("build") or {}
     out = output_dir().resolve()
     paths += [Path(b[k]) for k in ("apk", "alt_apk") if b.get(k) and out in Path(b[k]).resolve().parents]
     others = [o for o in library.games() if o.get("package") != package]
-    used = [Path(p).resolve() for o in others for p in (o.get("apk"), o.get("data_dir"), o.get("game_dir")) if p]
+    used = [Path(p).resolve() for o in others if not is_linux(o)
+            for p in (o.get("apk"), o.get("data_dir"), o.get("game_dir")) if p]
+    used += [p.resolve() for o in others if is_linux(o) for p in linux_local_files(o)]  # (lone AppImages: the file)
 
     def shared(p: Path) -> bool:  # the same path, a path inside it, or a folder around it belongs to another game
         rp = p.resolve()
@@ -555,6 +575,21 @@ def local_game_files(package: str) -> list[Path]:
     return [p for p in dict.fromkeys(paths) if p.exists() and not shared(p)]
 
 
+def linux_local_files(g: dict) -> list[Path]:
+    """A Linux app's own files: a lone AppImage/program (never the folder it sits in, e.g. Downloads), the app's
+    folder, or the archive it came from + FramePort's unpacked copy of it."""
+    extra = (g.get("analysis") or {}).get("extra") or {}
+    root = Path(g["game_dir"]) if g.get("game_dir") else None
+    if root is None:
+        return []
+    if extra.get("files"):
+        return [root / f for f in extra["files"]]
+    source = Path(extra["source"]) if extra.get("source") else None
+    if source is not None and source.is_file():  # an archive: it and its unpacked copy in FramePort's data folder
+        return [source, root]
+    return [root]
+
+
 def delete_local_files(package: str) -> tuple[list[str], int]:
     """Delete local_game_files(package), then the game's folder if that left it empty, and drop the library entry (the
     game can't be rebuilt without its files). Returns (deleted paths, bytes freed)."""
@@ -562,7 +597,8 @@ def delete_local_files(package: str) -> tuple[list[str], int]:
 
     files = local_game_files(package)
     freed, done = 0, []
-    parents = {p.parent for p in files}
+    # (not for Linux apps: a lone AppImage's folder is the user's, e.g. Downloads)
+    parents = set() if is_linux(library.game(package) or {}) else {p.parent for p in files}
     for p in files:
         size = sum(f.stat().st_size for f in p.rglob("*") if f.is_file()) if p.is_dir() else p.stat().st_size
         shutil.rmtree(p) if p.is_dir() else p.unlink()

src/frameport/ui/app.py

@@ -664,6 +664,7 @@ class FramePortApp:
         if not g:
             return []
         rift = g.get("kind") == "rift"
+        linux = g.get("kind") == "linux"  # installed as it is: nothing to analyze, convert or share as a recipe
         job = self.jobs.busy_with(pkg)
         out: list[tuple | None] = []
         if quick:
@@ -685,12 +686,12 @@ class FramePortApp:
                                 lambda e: self.test_game(pkg, "pc")))
                 if self.has_game_settings(g):
                     out.append((tr("Game settings…"), ft.Icons.TUNE_ROUNDED, lambda e: self.settings_dialog(pkg)))
-                if on_frame and not rift:
+                if on_frame and not rift and not linux:
                     out.append((tr("Add videos and files…"), ft.Icons.VIDEO_LIBRARY_OUTLINED,
                                 lambda e: self.go("files", pkg)))
                 if on_frame:
                     out.append((tr("Type on Frame…"), ft.Icons.KEYBOARD_ROUNDED, lambda e: self.type_on_frame()))
-                if not rift:
+                if not rift and not linux:
                     out.append((tr("Analyze again"), ft.Icons.MANAGE_SEARCH_ROUNDED, lambda e: self.reanalyze(pkg)))
                 if on_frame:
                     out.append((tr("Uninstall from Frame"), ft.Icons.DELETE_OUTLINE_ROUNDED,
@@ -705,6 +706,8 @@ class FramePortApp:
                             lambda e: (lv.selected.add(pkg), lv.set_select_mode(True))))
         if rift:
             out.append((tr("Change executable…"), ft.Icons.TERMINAL_ROUNDED, lambda e: self.choose_exe(pkg)))
+        if linux and self.linux_programs(g):
+            out.append((tr("Change program…"), ft.Icons.TERMINAL_ROUNDED, lambda e: self.choose_exe(pkg)))
         if self.frame_state == "connected":
             out.append((tr("Screenshots"), ft.Icons.PHOTO_LIBRARY_OUTLINED, lambda e: self.go("screenshots", pkg)))
         out.append((tr("Find artwork…"), ft.Icons.IMAGE_SEARCH_ROUNDED, lambda e: self.find_artwork(pkg)))
@@ -714,19 +717,27 @@ class FramePortApp:
             out.append((tr("Update Steam art on Frame"), ft.Icons.WALLPAPER_ROUNDED,
                         lambda e: self.update_steam_art(pkg)))
         out.append((tr("Refresh store details"), ft.Icons.SYNC_ROUNDED, lambda e: self.refresh_details(pkg)))
-        if not job:
+        if not job and not linux:
             out.append((tr("Rebuild only (no install)") if not rift else tr("Check game files"), ft.Icons.BUILD_ROUNDED,
                         lambda e: self.build_game(pkg)))
-        out += [(tr("Reset to suggested recipe"), ft.Icons.RESTART_ALT_ROUNDED,
-                 lambda e: (pipeline.reset_recipe(pkg), self.toast(tr("Recipe reset")), self.refresh_view())),
-                (tr("Save as known-good recipe"), ft.Icons.VERIFIED_ROUNDED, lambda e: self.save_known_good(pkg)),
-                (tr("Share working config…"), ft.Icons.SHARE_ROUNDED, lambda e: self.share_config_dialog(pkg)),
-                (tr("Collect logs"), ft.Icons.FOLDER_ZIP_OUTLINED, lambda e: self.collect_logs(pkg)),
+        if not linux:
+            out += [(tr("Reset to suggested recipe"), ft.Icons.RESTART_ALT_ROUNDED,
+                     lambda e: (pipeline.reset_recipe(pkg), self.toast(tr("Recipe reset")), self.refresh_view())),
+                    (tr("Save as known-good recipe"), ft.Icons.VERIFIED_ROUNDED, lambda e: self.save_known_good(pkg)),
+                    (tr("Share working config…"), ft.Icons.SHARE_ROUNDED, lambda e: self.share_config_dialog(pkg))]
+        out += [(tr("Collect logs"), ft.Icons.FOLDER_ZIP_OUTLINED, lambda e: self.collect_logs(pkg)),
                 (tr("Report a problem…"), ft.Icons.BUG_REPORT_OUTLINED, lambda e: self.report_problem_dialog(pkg)),
                 None,
                 (tr("Remove from library"), ft.Icons.DELETE_OUTLINE_ROUNDED, lambda e: self.remove_from_library(pkg))]
         return out
 
+    @staticmethod
+    def linux_programs(g: dict) -> list[str]:
+        """The other arm64 programs a Linux app could start with (empty for a lone AppImage/program)."""
+        extra = (g.get("analysis") or {}).get("extra") or {}
+        cands = [] if extra.get("files") else list(extra.get("candidates") or [])
+        return cands if len(cands) > 1 else []
+
     def install(self, pkg: str, to: str = "frame", confirmed: bool = False) -> Job | None:
         if confirmed:
             return self._submit_install(pkg, to)
@@ -1302,8 +1313,8 @@ class FramePortApp:
         """Quest games built with FramePort's adapter have game settings; PC VR games and 2D Android apps don't."""
         if not g:
             return True  # installed on the Frame but not in this library: a Quest game
-        if g.get("kind") == "rift" or not g.get("analysis"):
-            return g.get("kind") != "rift"
+        if g.get("kind") in ("rift", "linux") or not g.get("analysis"):
+            return g.get("kind") not in ("rift", "linux")
         return library.analysis_from_dict(g["analysis"]).vr_kind != "none"
 
     def settings_dialog(self, package: str) -> None:
@@ -1329,6 +1340,50 @@ class FramePortApp:
             if f.path:
                 self.scan(f.path)
 
+    async def pick_linux_app(self, e=None):
+        """An AppImage or an archive (.zip/.tar.*) with an arm64 Linux app. Any file can be picked: AppImages often
+        have no extension."""
+        from ..analysis import linux
+
+        files = await ft.FilePicker().pick_files(dialog_title=tr("A Linux app for arm64 (AppImage, .zip or .tar.gz)"),
+                                                 allow_multiple=True)
+        for f in files or []:
+            if not f.path:
+                continue
+            if linux.looks_like_linux_app(Path(f.path)):
+                self.add_linux(f.path)
+            else:
+                self.toast(tr("{name} isn't a Linux app (an AppImage, a Linux program or a .zip/.tar archive)")
+                           .format(name=Path(f.path).name), error=True)
+
+    async def pick_linux_folder(self, e=None):
+        path = await ft.FilePicker().get_directory_path(dialog_title=tr("Folder with a Linux app for arm64"))
+        if path:
+            self.add_linux(path)
+
+    def add_linux(self, path: str) -> Job:
+        """Add a native arm64 Linux app (GitHub #31) in the background, then open its page."""
+        name = Path(path).name
+
+        def run(job: Job):
+            job.reporter.stage("Looking at the app")
+            g = pipeline.add_linux_app(path, job.reporter)  # ValueError (e.g. an x86_64 build): the job fails with it
+            pkg = g["package"]
+            try:
+                from ..artwork import thumbs
+
+                thumbs.prewarm(pkg)  # the card's thumbnail of the placeholder cover
+            except Exception:  # noqa: BLE001 - artwork is optional
+                pass
+            library.set_setting("ui.welcome_done", True)
+            self.open_game(pkg)
+            extra = (g.get("analysis") or {}).get("extra") or {}
+            if len(extra.get("candidates") or []) > 1 and not extra.get("files"):  # (the page has "Change…")
+                return tr("Added {title}: it starts with {exe}. Not the right program? Change it on its page.").format(
+                    title=g.get("title"), exe=g.get("exe", "").rsplit("/", 1)[-1])
+            return tr("Added {title}").format(title=g.get("title"))
+        return self.submit(tr("Add {name}").format(name=name), run, None, "task")
+
     def scan_roots(self) -> list[str]:
         """Folders to rescan: the ones scanned before (remembered from now on), else the folders the library's games
         came from (one level up from each game folder)."""
@@ -1336,6 +1391,8 @@ class FramePortApp:
         if not roots:
             found = set()
             for g in library.load().get("games", {}).values():
+                if g.get("kind") == "linux":  # added one by one (its origin may be e.g. Downloads)
+                    continue
                 origin = g.get("origin") or (str(Path(g["apk"]).parent) if g.get("apk") else None)
                 if origin and Path(origin).parent.exists():
                     found.add(str(Path(origin).parent))

src/frameport/ui/components.py

@@ -49,6 +49,9 @@ def platform(g: dict) -> tuple[str, str, str]:
             return tr("Windows"), tr("Windows game (Proton)"), "platform_windows"
         oculus = extra.get("needs_revive") or extra.get("libovr")
         return tr("PC VR"), tr("PC VR · Oculus") if oculus else tr("PC VR"), "platform_pcvr"
+    if g.get("kind") == "linux":
+        vr = (((g.get("analysis") or {}).get("extra") or {}).get("openxr"))
+        return tr("Linux"), tr("Linux VR app · OpenXR") if vr else tr("Linux app (arm64)"), "platform_linux"
     kind = (((g.get("analysis") or {}).get("extra") or {}).get("vr_kind")) or "quest"
     if kind == "quest":
         return tr("Quest"), tr("Meta Quest"), "platform_quest"
@@ -58,6 +61,26 @@ def platform(g: dict) -> tuple[str, str, str]:
                           "android_xr": "Android XR"}.get(kind, "Android VR"), "platform_android_vr"
 
 
+def platform_icon(g: dict) -> str:
+    """The icon for a game's platform (card badge, artwork placeholder)."""
+    return ft.Icons.COMPUTER_ROUNDED if g.get("kind") == "rift" else \
+        ft.Icons.TERMINAL_ROUNDED if g.get("kind") == "linux" else ft.Icons.VIEW_IN_AR_ROUNDED
+
+
+def missing_libraries(game: dict, frame_info: dict | None) -> list[str]:
+    """A Linux app's shared libraries that the Frame lacks (the app won't start): from the Frame's install record when
+    connected, else from the last install FramePort did. Empty when the connected Frame doesn't have the app."""
+    dep = _deployment(game, frame_info)
+    if frame_info is not None and dep is None:
+        return []
+    if dep is not None and "missing_libraries" in dep:
+        return list(dep.get("missing_libraries") or [])
+    installs = [i for i in (game.get("installs") or {}).values() if isinstance(i, dict) and
+                isinstance(i.get("result"), dict)]
+    last = max(installs, key=lambda i: i.get("time") or 0, default=None)
+    return list((last or {}).get("result", {}).get("missing_libraries") or [])
+
+
 def install_state(game: dict, frame_info: dict | None) -> str | None:
     """None when no Frame is connected; else 'installed', 'outdated' (the local build, or the patch settings, differ
     from what the Frame runs) or 'missing'."""

src/frameport/ui/help.py

@@ -36,6 +36,13 @@ HELP: dict[str, str] = _Translated({
                         "Android container.",
     "platform_android_vr": "A VR app made for another Android headset. OpenXR apps are translated like Quest games; "
                            "apps built on a headset maker's own SDK (Pico, HTC Wave) can't run on the Frame.",
+    "platform_linux": "A native Linux program built for arm64 (aarch64), like the Frame's own CPU. It's installed "
+                      "unchanged and runs directly on SteamOS (no Android container, no Proton), started from the "
+                      "Frame's Steam library. VR apps use the Frame's OpenXR runtime.",
+    "linux_app": "An AppImage, a folder or a .zip/.tar archive with a Linux program built for arm64 (aarch64). x86_64 "
+                 "builds can't run on the Frame. The app must bring the libraries SteamOS doesn't have.",
+    "appimage": "An AppImage is a Linux app packed into one file. FramePort unpacks it on the Frame once, so it starts "
+                "without FUSE.",
     "select": "Pick several games and install them in one go. FramePort asks every question first, then works through "
               "the queue in the background.",
     "tags": "Your own tags (filled) can be anything you like. Outlined tags are added automatically from the engine, "

src/frameport/ui/views/exe_dialog.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 import flet as ft
@@ -21,11 +22,24 @@ def _size(n: int) -> str:
     return fmt_size(n)
 
 
+def _file_size(path: Path) -> int:
+    try:
+        return path.stat().st_size
+    except OSError:
+        return 0
+
+
 def show_exe_dialog(app: FramePortApp, package: str, remaining: int = 0,
                     on_done: Callable[[], None] | None = None) -> None:
     g = library.game(package)
     extra = (g.get("analysis") or {}).get("extra") or {}
-    cands = extra.get("exe_candidates") or [{"path": g.get("exe"), "score": 0, "reasons": [], "size": 0}]
+    linux = g.get("kind") == "linux"
+    if linux:  # a Linux app: its arm64 programs, best guess first
+        root = Path(g.get("game_dir") or ".")
+        cands = [{"path": c, "score": 0, "reasons": [], "size": _file_size(root / c)}
+                 for c in extra.get("candidates") or [g.get("exe")]]
+    else:
+        cands = extra.get("exe_candidates") or [{"path": g.get("exe"), "score": 0, "reasons": [], "size": 0}]
     current = g.get("exe") or cands[0]["path"]
     group = ft.RadioGroup(value=current, content=ft.Column(spacing=T.S2))
     for i, c in enumerate(cands):
@@ -70,8 +84,10 @@ def show_exe_dialog(app: FramePortApp, package: str, remaining: int = 0,
 
     pick = C.one_choice()
     title = tr("Which program starts {get}?").format(get=g.get('title'))
-    lead = (tr("FramePort found more than one program that could start this game. Pick the one you'd double-click to "
-            "play it. Oculus builds usually work better with Revive than Steam builds."))
+    lead = (tr("FramePort found more than one arm64 program in this app. Pick the one that starts it (helpers such "
+               "as crash reporters or updaters are the wrong choice).") if linux else
+            tr("FramePort found more than one program that could start this game. Pick the one you'd double-click to "
+               "play it. Oculus builds usually work better with Revive than Steam builds."))
     app.page.show_dialog(ft.AlertDialog(
         title=ft.Row([ft.Text(title, weight=ft.FontWeight.W_600, expand=True)]
                      + ([C.meta(tr("{remaining} more after this").format(remaining=remaining))] if remaining else [])),

src/frameport/ui/views/files.py

@@ -193,7 +193,7 @@ class FilesView:
 
         out = []
         for d in (self.app.frame_info or {}).get("installed", []):
-            if d.get("kind") == "pcvr":
+            if d.get("kind") in ("pcvr", "linux"):  # no Android storage
                 continue
             g = library.game(d["package"]) or {}
             out.append((d["package"], g.get("title") or d.get("title") or d["package"]))

src/frameport/ui/views/frame.py

@@ -119,7 +119,7 @@ class FrameView:
             size = d.get("apk_size", 0)
             in_lib = pkg in games
             sub = (tr("PC VR · Proton") + (tr(" + Revive") if d.get("revive") else "")) if pcvr else \
-                (C.platform(games[pkg])[0] if in_lib else tr("Quest"))
+                (C.platform(games[pkg])[0] if in_lib else tr("Linux") if d.get("kind") == "linux" else tr("Quest"))
             sub += (tr(" · {value:.1f} GiB").format(value=size / 2**30) if size >= 2**30
                     else tr(" · {value:.0f} MiB").format(value=size / 2**20))
             title = display_title(games[pkg], tw) if in_lib else (d.get("title") or pkg)

src/frameport/ui/views/game.py

@@ -49,7 +49,7 @@ def should_ask_to_share(g: dict, installed: bool) -> bool:
     """Invite the user to share a recipe the built-in catalog doesn't have yet: an untested Quest/Android game that
     they have installed, launch-tested or played, and haven't shared (or dismissed) already."""
     r = g.get("recipe") or {}
-    if g.get("kind") == "rift" or r.get("status", "unknown") != "unknown" or \
+    if g.get("kind") in ("rift", "linux") or r.get("status", "unknown") != "unknown" or \
             str(r.get("source", "")).startswith("catalog") or g.get("shared_config") or g.get("share_dismissed"):
         return False
     return installed or (g.get("last_test") or {}).get("verdict") == "pass" or bool(g.get("last_played"))
@@ -72,6 +72,7 @@ class GameView:
         self.games = library.games()
         self.twins = twins(self.games)
         self.rift = bool(self.g) and self.g.get("kind") == "rift"
+        self.linux = bool(self.g) and self.g.get("kind") == "linux"  # native arm64 app: installed as it is
 
     # ---------------------------------------------------------------- hero
     def hero(self) -> ft.Control:
@@ -81,7 +82,8 @@ class GameView:
         a = g["analysis"]
         art = thumbs.url(pkg, ("hero", "landscape", "portrait", "square", "banner"), 1280, wait=False)
         platform = C.platform(g)[1]
-        facts = " · ".join(x for x in (platform, a.get("engine"), a.get("xr")) if x and x != "?")
+        facts = " · ".join(x for x in (platform, *(() if self.linux else (a.get("engine"), a.get("xr"))))
+                           if x and x not in ("?", "none"))
         recipe = g.get("recipe") or {}
         chips = [C.status_chip(recipe.get("status", "unknown"))]
         st = C.install_state(g, app.frame_info)
@@ -93,7 +95,7 @@ class GameView:
         return ft.Container(
             ft.Stack([
                 C.art_fill(art, radius=T.px(16), hero=True, left=0, right=0, top=0, bottom=0,
-                           placeholder_icon=ft.Icons.COMPUTER_ROUNDED if self.rift else ft.Icons.VIEW_IN_AR_ROUNDED),
+                           placeholder_icon=C.platform_icon(g)),
                 ft.Container(left=0, right=0, top=0, bottom=0, border_radius=T.px(16), gradient=ft.LinearGradient(
                     begin=ft.Alignment.CENTER_LEFT, end=ft.Alignment.CENTER_RIGHT,
                     colors=[T.soft(T.BG, 0.97), T.soft(T.BG, 0.80), T.soft(T.BG, 0.25)], stops=[0.0, 0.45, 1.0])),
@@ -173,7 +175,8 @@ class GameView:
                      tr("Uses the repack's bundled Revive — experimental on the Frame") if rift_repack and not last else
                      tr("Last launch test: {get} · furthest: {value}")
                      .format(get=last.get('verdict'), value=last.get('milestone') or '—') if last
-                     else tr("Runs directly — no Revive needed") if self.rift else "")
+                     else tr("Runs directly — no Revive needed") if self.rift else
+                     tr("Runs natively on SteamOS, started from the Frame's Steam library") if self.linux else "")
         cards.append(self.target_card(
             ft.Icons.VIEW_IN_AR_ROUNDED, tr("Steam Frame"), frame_line, frame_color, frame_sub,
             [C.icon_btn(ft.Icons.SCIENCE_OUTLINED, C.tip(tr("Launch test on the Frame. ") + HELP["launch_test"]),
@@ -212,6 +215,14 @@ class GameView:
         entry = catalog.lookup(pkg)
         out = []
         extra = g["analysis"].get("extra", {})
+        missing = C.missing_libraries(g, self.app.frame_info) if self.linux else []
+        if missing:
+            out.append(C.callout(ft.Column([
+                C.body(tr("It won't start on the Frame: SteamOS doesn't have these libraries and the app doesn't bring "
+                          "them. Look for a build of the app that includes them, then install that one."),
+                       T.TEXT),
+                C.meta(", ".join(missing), T.TEXT_2, selectable=True)], spacing=T.px(4)), "error",
+                ft.Icons.EXTENSION_OFF_ROUNDED))
         if self.rift and g.get("exe_confirmed") is False:
             out.append(C.callout(ft.Row([
                 C.body(tr("FramePort picked {value} to start this game, but there are other candidates. "
@@ -395,7 +406,31 @@ class GameView:
         fill()
         return C.section(tr("Tags"), row, subtitle=tr("Use tags to group and filter your library"), help="tags")
 
+    def linux_summary(self) -> ft.Control:
+        """A Linux app has nothing to patch: what FramePort installs, and how it starts."""
+        g, pkg = self.g, self.package
+        extra = (g.get("analysis") or {}).get("extra") or {}
+        vr = bool(extra.get("openxr"))
+        lead = tr("Installs the app as it is, unpacked on the Frame, with an entry in its Steam library") \
+            if extra.get("appimage") else tr("Installs the app as it is, with an entry in the Frame's Steam library")
+        change = C.ghost(tr("Change…"), ft.Icons.TERMINAL_ROUNDED, lambda e: self.app.choose_exe(pkg)) \
+            if self.app.linux_programs(g) else None
+        rows = [
+            C.kv(tr("Program"), ft.Row([C.body(g.get("exe") or "", T.TEXT, selectable=True)]
+                                       + ([change] if change else []), spacing=T.S2, wrap=True)),
+            C.kv(tr("AppImage"), tr("Yes") if extra.get("appimage") else tr("No"), "appimage"),
+            C.kv(tr("VR (OpenXR)"), tr("Yes: uses the Frame's OpenXR runtime") if vr else
+                 tr("No: a 2D app")),
+            C.kv(tr("Source"), extra.get("source") or g.get("game_dir") or ""),
+        ]
+        return C.section(tr("What FramePort will do"), C.card(ft.Column([
+            ft.Row([ft.Icon(ft.Icons.TERMINAL_ROUNDED, color=T.PC, size=T.px(18)),
+                    C.body(lead, T.TEXT, weight=ft.FontWeight.W_500, expand=True)], spacing=T.S2),
+            *rows], spacing=T.S3)), help="linux_app")
+
     def recipe_summary(self) -> ft.Control:
+        if self.linux:
+            return self.linux_summary()
         recipe = library.recipe_from_dict(self.g["recipe"])
         entry = catalog.lookup(self.package)
         on = [base.get(pid) for pid in recipe.patches if pid in base.REGISTRY or _known(pid)]
@@ -596,6 +631,14 @@ class GameView:
     def details(self) -> ft.Control:
         g, a = self.g, self.g["analysis"]
         rows = [C.kv(tr("Package"), g["package"])]
+        if self.linux:
+            rows += [C.kv(tr("Folder"), g.get("game_dir") or ""),
+                     C.kv(tr("Size"), tr("{value:.1f} GiB").format(value=(g.get("data_bytes") or 0) / 2**30)
+                          if (g.get("data_bytes") or 0) >= 2**30 else
+                          tr("{value:.0f} MiB").format(value=(g.get("data_bytes") or 0) / 2**20))]
+            return ft.ExpansionTile(title=C.body(tr("Details"), T.TEXT, weight=ft.FontWeight.W_600), controls=[
+                ft.Container(ft.Column(rows, spacing=T.S2), padding=ft.Padding(T.S4, 0, T.S4, T.S4))],
+                bgcolor=T.SURFACE, collapsed_bgcolor=T.SURFACE)
         if self.rift:
             rows += [C.kv(tr("Folder"), g.get("game_dir") or ""), C.kv(tr("Executable"), g.get("exe") or ""),
                      C.kv(tr("Type"), f"{a['abis'][0]} · {a['graphics']}"),
@@ -623,7 +666,7 @@ class GameView:
         about = self.about()
         body = [self.hero(), *self.notes(), self.where(), *([about] if about else []), self.tags(),
                 self.recipe_summary()]
-        if self.advanced:
+        if self.advanced and not self.linux:  # (a Linux app has no patches)
             body.append(self.advanced_panel())
         body.append(self.details())
         app = self.app

src/frameport/ui/views/library.py

@@ -35,7 +35,7 @@ def auto_tags(game: dict) -> list[str]:
     if "patch_force_passthrough" in patches or "adapter.scene_emul" in patches:
         out.append(tr("Mixed reality"))
     out += ((game.get("details") or {}).get("genres") or [])[:4]  # from the store
-    return out
+    return list(dict.fromkeys(out))  # (a Linux app's platform and "engine" are both "Linux")
 
 
 def user_tags(game: dict) -> list[str]:
@@ -89,6 +89,26 @@ def location(game: dict, frame_info: dict | None, pc_installs: set[str]) -> set[
     return out
 
 
+def platform_matches(game: dict, platform: str) -> bool:
+    """The library's platform filter: all | quest (Android games and apps) | pcvr (PC VR and Windows) | linux."""
+    kind = game.get("kind") or "quest"
+    return platform == "all" or {"quest": kind not in ("rift", "linux"), "pcvr": kind == "rift",
+                                 "linux": kind == "linux"}.get(platform, True)
+
+
+def platform_filter_options(games: list[dict]) -> list[tuple[str, str]]:
+    """The platform filter's choices: only when the library has more than Android games; one per kind present."""
+    kinds = {g.get("kind") or "quest" for g in games}
+    if not kinds & {"rift", "linux"}:
+        return []
+    out = [("all", tr("All")), ("quest", tr("Android"))]
+    if "rift" in kinds:
+        out.append(("pcvr", tr("PC VR")))
+    if "linux" in kinds:
+        out.append(("linux", tr("Linux")))
+    return out
+
+
 def filter_games(games: list[dict], f: dict, frame_info: dict | None = None,
                  pc_installs: set[str] | frozenset = frozenset()) -> list[dict]:
     q = (f.get("q") or "").strip().lower()
@@ -99,8 +119,7 @@ def filter_games(games: list[dict], f: dict, frame_info: dict | None = None,
             continue
         if any(t.lower() not in tags for t in f.get("tags") or []):
             continue
-        rift = g.get("kind") == "rift"
-        if f.get("platform") == "quest" and rift or f.get("platform") == "pcvr" and not rift:
+        if not platform_matches(g, f.get("platform", "all")):
             continue
         if f.get("status", "all") != "all" and (g.get("recipe") or {}).get("status", "unknown") != f["status"]:
             continue
@@ -198,7 +217,12 @@ class LibraryView:
                    ft.PopupMenuItem(content=ft.Text(tr("Add one game folder…")),
                                     icon=ft.Icons.CREATE_NEW_FOLDER_ROUNDED, on_click=app.pick_game_folder),
                    ft.PopupMenuItem(content=ft.Text(tr("Add an APK file…")), icon=ft.Icons.ANDROID_ROUNDED,
-                                    on_click=app.pick_apk)],
+                                    on_click=app.pick_apk),
+                   ft.PopupMenuItem(),  # divider: native Linux apps (GitHub #31)
+                   ft.PopupMenuItem(content=ft.Text(tr("Add a Linux app (arm64)…")), icon=ft.Icons.TERMINAL_ROUNDED,
+                                    on_click=app.pick_linux_app),
+                   ft.PopupMenuItem(content=ft.Text(tr("Add a Linux app folder…")), icon=ft.Icons.FOLDER_ROUNDED,
+                                    on_click=app.pick_linux_folder)],
             bgcolor=T.SURFACE_2, tooltip="")
         self.rescan_btn = C.secondary(tr("Rescan folders"), ft.Icons.REFRESH_ROUNDED, app.rescan,
                                       tooltip=C.tip(HELP["rescan"]))
@@ -428,14 +452,14 @@ class LibraryView:
         C.update(self.update_all_btn)
         self._update_hint()
         has_rift = any(g.get("kind") == "rift" for g in games)
+        platforms = platform_filter_options(games)
         where = [("all", tr("All")), ("frame", tr("On Frame")), ("none", tr("Not installed"))]
         if has_rift:
             where.insert(2, ("pc", tr("On this PC")))
         # the filters wrap onto a second line in a narrow window; count and sort stay on the right
         left = ft.Row([
             self._seg("where", where),
-            *([self._seg("platform", [("all", tr("All")), ("quest", tr("Android")), ("pcvr", tr("PC VR"))])]
-              if has_rift else []),
+            *([self._seg("platform", platforms)] if platforms else []),
             C.with_help(self._menu_chip("status", tr("Status"), [("all", tr("Any")), ("works", tr("Works")),
                                                                  ("issues", tr("Works with issues")),
                                                                  ("unknown", tr("Untested")),
@@ -530,8 +554,7 @@ class LibraryView:
             badges.append(C.pill(tr("Check exe"), T.WARN, ft.Icons.HELP_OUTLINE_ROUNDED, overlay=True,
                                  tooltip=C.tip(HELP["check_exe"])))
         label, _, help_key = C.platform(g)
-        platform = C.pill(label, T.PC if rift else T.TEXT,
-                          ft.Icons.COMPUTER_ROUNDED if rift else ft.Icons.VIEW_IN_AR_ROUNDED, overlay=True,
+        platform = C.pill(label, T.PC if rift else T.TEXT, C.platform_icon(g), overlay=True,
                           tooltip=C.tip(HELP[help_key]))
         check = ft.Container(ft.Checkbox(value=pkg in self.selected, active_color=T.ACCENT, check_color=T.ON_ACCENT,
                                          on_change=lambda e: self.toggle_selected(pkg)),
@@ -554,7 +577,7 @@ class LibraryView:
         tile = ft.Container(
             ft.Stack([
                 C.art_fill(art, left=0, right=0, top=0, bottom=0, opacity=0.5 if dim else 1.0,
-                           placeholder_icon=ft.Icons.COMPUTER_ROUNDED if rift else ft.Icons.VIEW_IN_AR_ROUNDED),
+                           placeholder_icon=C.platform_icon(g)),
                 ft.Container(C.bottom_fade(None, 0.92), left=0, right=0, bottom=0, top=T.px(90)),
                 # platform + state badges in one row that wraps: on a narrow card "On Frame" covered "Android"
                 ft.Container(ft.Row([platform, *badges], spacing=T.px(4), run_spacing=T.px(4), wrap=True),

tests/test_linux_apps.py

@@ -70,3 +70,39 @@ def test_add_linux_app_library_entry(tmp_path):
     g = pipeline.add_linux_app(p)
     assert g["package"] == "linux.tool" and g["kind"] == "linux" and pipeline.is_linux(g)
     assert g["exe"] == p.name and g["analysis"]["extra"]["appimage"]
+
+
+def test_local_files_of_a_lone_appimage_never_include_its_folder(tmp_path):
+    a, b = tmp_path / "Tool-1.2-aarch64.AppImage", tmp_path / "Other-1.0-aarch64.AppImage"
+    a.write_bytes(elf(linux.EM_AARCH64, appimage=True))
+    b.write_bytes(elf(linux.EM_AARCH64, appimage=True))
+    (tmp_path / "keep.txt").write_text("the user's file")
+    g = pipeline.add_linux_app(a)
+    pipeline.add_linux_app(b)
+    assert g["data_bytes"] == a.stat().st_size
+    assert pipeline.local_game_files(g["package"]) == [a]  # another AppImage in the same folder doesn't block it
+    pipeline.delete_local_files(g["package"])
+    assert not a.exists() and b.exists() and (tmp_path / "keep.txt").exists()
+
+
+def test_change_program_of_a_linux_folder(tmp_path):
+    root = tmp_path / "Matinee"
+    root.mkdir()
+    (root / "Matinee").write_bytes(elf(linux.EM_AARCH64))
+    (root / "helper").write_bytes(elf(linux.EM_AARCH64))
+    g = pipeline.add_linux_app(root)
+    assert g["exe"] == "Matinee" and pipeline.local_game_files(g["package"]) == [root]
+    assert pipeline.set_exe(g["package"], "helper")["exe"] == "helper"
+
+
+def test_linux_recipes_dont_follow_the_catalog(tmp_path, monkeypatch):
+    from frameport.core import library
+
+    p = tmp_path / "Tool-1.2-aarch64.AppImage"
+    p.write_bytes(elf(linux.EM_AARCH64, appimage=True))
+    g = pipeline.add_linux_app(p)
+    monkeypatch.setattr(library, "REFRESH_ON_UPDATE", True)
+    data = library.load()
+    data["settings"]["recipes.app_version"] = "0.0.0"  # as after an app update
+    library._follow_catalog(data)
+    assert data["games"][g["package"]]["recipe"]["as_is"] is True

tests/test_ui_help.py

@@ -125,6 +125,81 @@ def test_untested_games_invite_sharing_their_recipe():
     assert not should_ask_to_share({**g, "kind": "rift"}, True)
 
 
+def _linux_app(**extra):
+    return {"package": "linux.tool", "kind": "linux", "title": "Tool", "apk": None, "game_dir": "/apps/tool",
+            "exe": "tool", "recipe": {"status": "unknown", "as_is": True, "overport": False},
+            "analysis": {"engine": "Linux", "xr": "none",
+                         "extra": {"vr_kind": "none", "appimage": False, "openxr": False, "files": None,
+                                   "candidates": ["tool"], **extra}}}
+
+
+def test_linux_app_menus_have_no_conversion_actions(monkeypatch):
+    g = _linux_app()
+    on_frame = {"installed": [{"package": "linux.tool", "kind": "linux"}]}
+    for quick in (True, False):
+        labels = _labels(_app(monkeypatch, g, on_frame).game_actions("linux.tool", quick=quick))
+        for gone in ("Analyze again", "Rebuild only (no install)", "Check game files", "Reset to suggested recipe",
+                     "Save as known-good recipe", "Share working config…", "Game settings…",
+                     "Add videos and files…", "Change program…"):
+            assert gone not in labels, gone
+        assert {"Find artwork…", "Report a problem…", "Collect logs", "Screenshots"} <= set(labels)
+        assert labels[-1] == "Remove from library"
+    quick = _labels(_app(monkeypatch, g, on_frame).game_actions("linux.tool"))
+    assert {"Play on Frame", "Reinstall on Frame", "Launch test on Frame", "Uninstall from Frame"} <= set(quick)
+    several = _linux_app(candidates=["tool", "tool-helper"])
+    assert "Change program…" in _labels(_app(monkeypatch, several, {"installed": []}).game_actions("linux.tool"))
+    lone = _linux_app(candidates=["a", "b"], files=["Tool.AppImage"])  # a lone AppImage: nothing to choose
+    assert "Change program…" not in _labels(_app(monkeypatch, lone, {"installed": []}).game_actions("linux.tool"))
+
+
+def test_linux_apps_install_on_the_frame_only(monkeypatch):
+    g = _linux_app()
+    app = _app(monkeypatch, g, {"installed": []})
+    assert [o[0] for o in app.install_options(g)] == ["Install on Frame"]
+    assert app.quick_action(g) == ("Install on Frame", "install")
+    assert not app.has_game_settings({**g, "analysis": {"extra": {"vr_kind": "openxr", "openxr": True}}})
+    installed = _app(monkeypatch, g, {"installed": [{"package": "linux.tool", "kind": "linux", "recipe": None}]})
+    assert C.install_state(g, installed.frame_info) == "installed"  # no build/recipe record: never "outdated"
+    assert installed.quick_action(g) == ("Play on Frame", "play")
+
+
+def test_linux_platform_badge_filter_and_tags():
+    from frameport.artwork.steam import steam_tags
+    from frameport.ui.views.library import filter_games, platform_filter_options
+
+    g, vr = _linux_app(), _linux_app(openxr=True, vr_kind="openxr")
+    assert C.platform(g)[0] == "Linux" and C.platform(g)[2] == "platform_linux"
+    assert "OpenXR" in C.platform(vr)[1]
+    q = {"package": "com.q", "title": "Q", "recipe": {}}
+    r = {"package": "rift.r", "kind": "rift", "title": "R", "recipe": {}}
+    assert platform_filter_options([q]) == []
+    assert [k for k, _ in platform_filter_options([q, g])] == ["all", "quest", "linux"]
+    assert [k for k, _ in platform_filter_options([q, r, g])] == ["all", "quest", "pcvr", "linux"]
+    games = [q, r, g]
+    pick = {p: [x["package"] for x in filter_games(games, {"platform": p})] for p in ("quest", "pcvr", "linux")}
+    assert pick == {"quest": ["com.q"], "pcvr": ["rift.r"], "linux": ["linux.tool"]}
+    assert steam_tags(g)[:2] == ["Linux app on Frame", "Linux"]
+
+
+def test_linux_missing_libraries_from_the_frame_or_the_last_install():
+    g = _linux_app()
+    assert C.missing_libraries(g, None) == []
+    dep = {"package": "linux.tool", "kind": "linux", "missing_libraries": ["libwebkit2gtk-4.1.so.0"]}
+    assert C.missing_libraries(g, {"installed": [dep]}) == ["libwebkit2gtk-4.1.so.0"]
+    assert C.missing_libraries(g, {"installed": []}) == []  # not on the connected Frame (any more)
+    rec = {**g, "installs": {"old": {"time": 1, "result": {"missing_libraries": ["libold.so"]}},
+                             "new": {"time": 2, "result": {"missing_libraries": ["libgtk-3.so.0"]}}}}
+    assert C.missing_libraries(rec, None) == ["libgtk-3.so.0"]  # offline: the last install's report
+
+
+def test_linux_apps_have_no_twins():
+    from frameport.core.titles import counterparts, twins
+
+    q = {"package": "com.tool", "title": "Tool", "recipe": {}}
+    g = _linux_app()
+    assert twins([q, g]) == set() and counterparts(g, [q, g]) == [] and counterparts(q, [q, g]) == []
+
+
 def test_patch_reasons_in_plain_words():
     from frameport.ui.views.game import plain_reason