Transformers Beyond Reality (UE5, FMallocBinned3) reserves 76 GiB with one
mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS) while libUnreal.so's
static constructors run. Quest grants it; the Frame's kernel (overcommit mode 0) refuses a
writable private mapping larger than RAM + swap, and Unreal's out-of-memory handler then
dereferences its not yet created log: SIGSEGV fault addr 0x10 inside System.loadLibrary.
The patch adds MAP_NORESERVE to every anonymous read/write mmap call site of the engine
library (mov w3, #0x22 -> #0x4022 before a bl to mmap's PLT stub, with x0 = 0 and w2 = 3
in the window), suggested from analysis unreal_binned3 (ANALYSIS_VERSION 22 on main). Triage
unreal-reserve-refused, PLAYBOOK row, tests. Headless on the dev Frame the game now gets
past loading to its OpenXR session and first frames.
ELF helpers find .dynsym/.dynstr/.dynamic by section type and link instead of by name: this
game's libOVRPlugin.so has a scrambled section name table, so add_needed raised
"produced NEEDED=[...]" and the build failed in frame.unreal_ovrp_entrypoints, and
dyn_symbols returned nothing (every ovrp_* lookup then counted as missing).
# Conflicts:
# docs/PATCHES.md
# src/frameport/analysis/detect.py
The Frame's runtime has no XR_FB_display_refresh_rate (-7); OVRPort's dispatcher still
offers it and answered 0 Hz. Team Beef's idTech 4 ports run USERCMD_MSEC = 1000 / refresh,
so PreyVR had 0 ms tics: the async thread spun (~1.9M tics/s), com_frameTime stayed 0 and
the main menu's timeline never got past its first step (black backdrop + cursor only).
FrameBridge now always answers with 1 / predictedDisplayPeriod (else the refresh_rate
setting, else 72 Hz). Headless: menu drawn (snapshot mean 68 vs 0.1 before), clocks advance.
- glmv: gl_mv_debug=2 traces draws (state, GL errors per framebuffer), failed texture
uploads/copies/compiles and idTech 4 clocks; how this was found
- triage: a single xrEndFrame -16 is info, not the black-menu error it was blamed for
- PLAYBOOK row, CLAUDE.md fact, host test for the fallback rate
Frames without a projection layer (e.g. PreyVR's menu, a cylinder layer only) gave no snapshot. The snapshot now
takes the first quad/cylinder layer's image instead and logs the layer type, image area, array index and the mean/max
brightness of the submitted area, so a black image shows in the log without fetching the file (#306).
Scared By Squares (Unreal 4.27, OpenXR) creates two actions named "turn"
(an action mapping and an axis mapping called Turn). The Frame's runtime
accepts the duplicate, then vrserver fails to load the input manifest it
builds ("SetXrInputConfig failed. Failed to load manifest"), drops the
app's connection and treats it as exited: black, then the home environment
while the game keeps running with sound. Headless the app reconnected as a
plain OpenXR instance, got throttled to 10 fps and the compositor received
no presents.
- action_dedup (adapter setting, default on): a later duplicate action name
or localized name in a set is created as "<name>_N" / "<Localized> N"
(native/adapter/action_names.h, host-tested). Headless on the dev Frame:
manifest loads, 72 fps, 2808 presents in 45 s (before: 10 fps, none).
- input_diag logs every action set and action (escaped names).
- force_render (hidden diagnostic): xrWaitFrame reports shouldRender=TRUE so
headless runs exercise engines that skip layers when not visible; FrameBridge
logs shouldRender changes.
- Triage: space-warp-used only on the motion-vector swapchain (format 97);
D24S8 (129) eye depth falsely matched. New info finding duplicate-action-renamed.
- Catalog entry (status unknown, min_app 1.2.1), PLAYBOOK row.
Meta's Unity OpenXR features add Detached Touch/Touch Plus/Pro devices on
/user/detached_controller_meta/left|right. Unity merges same-named actions of all devices, so the
first such action (thumbstick) failed with XR_ERROR_PATH_UNSUPPORTED on the Frame (no
XR_META_detached_controllers), Unity attached no action set and neither Unity nor OVRPlugin got
controller input: hands on the floor (Spatial Zombies). Without the extension in the runtime, these
paths are now left out of xrCreateAction subaction paths and suggested bindings, and
xrGetCurrentInteractionProfile answers no profile for them. Headless: actions created, Touch
bindings accepted, action spaces created, no ACTIONSET_NOT_ATTACHED.
Games that suggest controller bindings only for Meta's Touch Plus/Pro profiles got them moved to
oculus/touch_controller, but xrGetCurrentInteractionProfile then answered oculus/touch_controller,
a profile they never suggested. Unity's OpenXR input creates its devices by the reported profile,
found none and left the controllers unconnected: hands lying on the floor, no buttons (Hotel
Infinity). Such hands are now reported with the game's own (last remapped) profile; games that
suggest Touch themselves are unchanged. Logic moved to profile_report.c with a host test.
Unity's Oculus XR plugin asks for SUBSAMPLED eye images through
XR_META_vulkan_swapchain_create_info. With device.foveation on, Valve's
injected FDM leaves their coarse areas in the subsampled layout and the
compositor shows them as garbage around the sharp area (Medieval
Dynasty: black with scattered coloured blocks). foveation_fix=1 only
dropped the XrSwapchainCreateInfoFoveationFB nodes.
The adapter's storage fix (clear SUBSAMPLED from the META node) now runs
whenever foveation_storage_fix is set, also with foveation_fix, and
device.foveation tracked/fixed sets it. Generic form of Batman's
OVRPlugin allocation fix. Adapter rebuilt; revision not bumped.
Star Wars: Beyond Victory's mixed reality showed the room on the game's
objects and black where the room should be. Unreal keeps 1 - coverage in
the scene alpha, and OVRPlugin chains XrCompositionLayerAlphaBlendFB
(colour ONE_MINUS_SRC_ALPHA / SRC_ALPHA) to the eye layer; the Frame's
runtime ignores the struct and blends with the plain texture alpha.
New adapter setting alpha_blend_emul (default on, Vulkan): while
passthrough is emulated and the projection layer asks for inverse
blending, the alpha of the eye image rectangles is inverted in place
(alpha-only blend pass, once per acquired image, queued ahead of the
runtime's submission). layer_debug now also logs the blend factors.
Headless on the Frame: factors (3,2/3,2) seen, inversion runs, 72 fps,
no rejected frames. Not yet checked in the headset.
- il2cpp._run: a non-zero exit or no .cs file under DiffableCs is an unreadable game. The release Cpp2IL dies on
BattleTalent (Unity 2021.3.45f2, exit 134, IndexOutOfRangeException in CsFileUtils.GetTypeName) after making the
folder tree; every class was recorded "missing" and cached.
- find_methods: any release failure gets one try with the development build (it reads BattleTalent), not only an
unsupported metadata version; never with a caller's Cpp2IL or FRAMEPORT_CPP2IL. Errors are cached as errors,
never as missing classes; cache entries with no class found and every wanted class missing are run again.
- Il2cppReturnPatch: Cpp2IL failures become the same WARN check as "code not found" but with Cpp2IL's error line;
the method list in the WARN has no duplicates.
- triage: logcat times include the date (logcat replays kernel lines dated days earlier ahead of the game's; by time
of day the "past midnight" guess gave a healthy run frames-stopped 83261 s). Year wrap handled.
- Il2cppReturnPatch (unity_runtime_msaa_off, unity_multipass, unity_text_input, ...): a patch that is turned on
but whose methods Cpp2IL doesn't find in the game now logs it and adds a WARN build check naming the patch
("not applied (<id>): code not found in this game ...") instead of skipping silently. ApkContext.checks =
checks a patch reports while applying; apply_frame_fixes adds them to the build's checks (job/CLI output,
build record). WARN only: the build still succeeds.
- FrameBridge rect_clamp: an empty projection/quad image rect (BattleTalent's first frames: 0,0 0x0 ->
xrEndFrame -25 twice, then OVRPlugin stops submitting) becomes the whole swapchain image when its size is
known; counted as swapped, logged ("rect_clamp: view N empty image rect -> full swapchain WxH"). Adapter
revision unchanged; artifacts rebuilt.
- triage swapchain-rect-invalid, PLAYBOOK row, setting texts, PATCHES.md, i18n template.
Apply saved refresh rates through SteamVR before Lepton starts, preserve launcher upgrade ordering, and cover the behavior with regression tests. Update the setting documentation and fix repository lint errors blocking CI.
The four fix branches each set ANALYSIS_VERSION 20, which main already used for google_vr (#335); one bump re-analyses older library entries for all their new fields.
Pinball FX2 VR (32-bit, through the a32 bridge) died ~2 s after its loading
screen with "a32: block at 0xf68587a0 overflowed the code buffer" (exit 127):
OpenSSL's sha1_block_data_order_armv8 (reached from RAND_poll) has ~60 SHA-1
crypto instructions in a row, each translated through the interpreter with
its own exit stub, and the block loop only stopped at 96 instructions or half
the code buffer, so the 64-entry stub table overflowed and fatal() ended the
process. The loop now also ends a block while 8 stubs are left.
Headless on the dev Frame the game now runs on past that point (menu-size
swapchains, recenter, its save files written) instead of exiting.
tests/programs/sha1ce.c (72 crypto instructions in a row + an unrolled SHA-1)
failed with the old a32run and passes with the new one, JIT = interpreter.
Triage signature a32-jit-overflow, PLAYBOOK row; frame.a32_bridge marks only
Pinball FX2 VR "Update on Frame" (package_revisions).
Titan Isles (#310) died on GoogleApiHandler with NoSuchMethodError permitUnsafeIntentLaunch(): not the
missing Play services but play-services-basement's PlatformVersion.isAtLeastS()/isAtLeastSv2(), which R8
folded to `return true` in this minSdk 32 build. frame.gms_platform_version makes such constant checks for
Android 12+ return false again (analysis gms_folded_sdk_checks, triage gms-android12-call). Headless on the
dev Frame: runs, 72 fps, no crash.
PianoVision (#297), after frame.unity_appui_vibrator, crashed on MidiDeviceConnectionWatchThread: kshoji's
USB MIDI driver polls UsbManager, and Lepton has no USB service (null). frame.usb_midi_watcher makes
checkConnectedDevices return at once (analysis usb_midi_watcher, triage usb-midi-watcher). Host-tested.
PianoVision quit about a second after start on the Frame: Unity App UI's activity
(com.unity3d.player.appui.AppUIGameActivity) calls getSystemService("vibrator_manager") and casts to
android.os.VibratorManager in onCreate without a version check; Lepton runs Android 11, so
NoClassDefFoundError before Unity starts. The sequence now leaves its registers null (the field store and
the rest of onCreate stay) and the activity's methods that read the vibrator return at once (in-place dex
edit). Suggested by analysis unity_appui_vibrator (ANALYSIS_VERSION 20) and triage unity-appui-vibrator.
Escaping Wonderland's Meta start-up (OculusPlatform.<Initialize>d__13) awaits
Users.GetOrgScopedID after the licence check and the logged-in user, when on
Wi-Fi, only for its analytics id. OVRPort's ovr_User_GetOrgScopedID returns
request id 0, Meta's C# wrapper logs "An unknown error occurred. Request
failed." and never calls back, so the game waits forever. The patch takes the
game's own no-Wi-Fi path for that request (b.ne after cmp w0,#2 on
get_internetReachability -> b, found with Cpp2IL). Analysis flag
cortopia_org_id (ANALYSIS_VERSION 20), triage cortopia-org-id-wait, PLAYBOOK
row, tests. Headless on the dev Frame: past the loading screen into the intro
scene (adventurer spawned), 72 fps.
Photon Voice's AudioInAEC.updateAudioDevice calls getAvailableCommunicationDevices/setCommunicationDevice with no version check; on Lepton's Android 11 the microphone thread dies with NoSuchMethodError (Table Troopers at the tutorial). New patch frame.photon_voice_audio_route (analysis photon_voice_api31, ANALYSIS_VERSION 20) makes it return at once, sharing vivox_audio_route's helper; Vivox's patch is unchanged. Triage vivox-api31 / photon-voice-api31 now look for the SDK in the stack; other libraries fall to audio-api31 (report).
Unity games log 'An unknown error occurred. Request failed.' from
Oculus.Platform.Request.OnComplete when a Meta call gets no usable answer
(Thief Simulator #368, Eleven #346, Spectre #360): warning + report. Games with
their own copy of Meta's platform loader abort with 'DisplayErrorAndExit:
Failed to launch SystemActivities' (Breachers #357): fatal, replaces the
generic native crash. PLAYBOOK rows, tests from the reporters' logs.
The reporter's read-before-write fix for module 16800_8dbab031 (12 int Function
variables loaded before any store, the same bug as Vader Immortal's lightspeed
shaders), headset-verified: past the loading screen, ~28 min at 72 fps.
Sections now run from what most users need to what only some need:
Updates, Installing, Library folders, Appearance, Data, Problems and
feedback, Install links, Tools, This PC, About, Uninstall. Updates gains a
Games part: game recipes from GitHub (moved from Data) and the new
"Check games from install links for new versions" switch with its last
check and Check now. Inside sections the common options come first
(Installing: parallel uploads and video before keep-copies; Updates: dev
build last; Appearance: language first when a translation exists).
The demo manifest (site + built-in copy) names version 1.0.0 as an example;
the demo link is still never fetched or checked (test).
A manifest may name its build's version (top-level "version" or
"frameport": {"version"}). FramePort keeps it with the game's link record
and, at start (at most every 6 h), fetches remembered web manifests again;
a newer version marks the game link_update. The Library bar and the game
page offer to download and install it (one confirmation, same download path
as a first install, a name the user gave is kept). CLI: frameport
link-updates [--install]. Docs: INSTALL_BUTTON.md.
From working-recipe issues #378, #377, #376, #375, #364, #363 (validated with
scripts/catalog_from_issue.py). The 7th Guest VR: the foveation darkening
diagnostic (foveation_test) left out, title spaced, notes shortened to the
game-specific findings. FGO VR: scale rounded to 1.2.
Closes#378Closes#377Closes#376Closes#375Closes#364Closes#363
Analysis extra.google_vr (ANALYSIS_VERSION 20): manifest DAYDREAM/CARDBOARD
categories, enableVrMode=com.google.vr.vrcore, libgvr.so / Cardboard SDK libs,
GVR Java classes, Unity vr-device-list (not libgvraudio.so, which Quest games
ship too). A build without Oculus support gets a warning (recipe notes, CLI,
game page); never unsupported from the manifest. Triage gvr-not-supported for
Unity's 'Google VR Error', the bridge's missing CardboardViewNativeImpl and
VrCore binds. PLAYBOOK row, tests.
CLAUDE.md was ~150k characters (over Claude Code's instruction-file limit together with CLAUDE.local.md). The dated investigation narratives move verbatim into docs/DEVICE_NOTES.md; CLAUDE.md keeps a one-line pointer per block with the key fact and the patch/setting names.
Doom3Quest's shader sources start with a newline before #version (raw string literals). GL drivers accept that, but
glslangValidator's ES profile rejects it, so the optional validator step failed wherever glslang is installed.
The copy it checks now starts at #version; the rewriter output itself is unchanged.
Agent v94: _backup_saves / _restore_saves stream a tar.gz of a game's internal
and external Android storage over the SSH exec channel (caches, IL2CPP and
shader caches, FrameBridge files, videos/OBBs and files over 64 MiB left out;
manifest with sha256 last). File work runs in podman unshare, holds the
launch lock and is refused while the game runs. Restore treats the archive as
untrusted (confined paths, no links/devices, size limits, hashes checked,
staged first), keeps the replaced saves as saves-before-restore.tar.gz (undo)
and puts them back if swapping fails.
PC: install/saves.py (save-backups/<pkg>/, keep 10 by default), game menu
section Saves (back up, restore..., open backups folder), Frame page
"Back up all saves", back up before deleting saves on uninstall, Settings ->
Data keep count, CLI frameport saves backup|list|restore|undo.
Settings -> Library folders lists the folders Rescan scans (scan.roots: status,
games from each, remove, Add folder...), CLI frameport folders / rescan.
A scan that finds a library game elsewhere whose own files are gone and that
is the same build points the entry at the new place (title, tags, art, user
recipe, builds and installs stay); another version is taken only by Scan a
folder... (as Update with a newer APK/version), Rescan reports it; a second
copy leaves the existing one. A full scan no longer overwrites a user recipe.
bootstrap.sh and Frame.install_key appended with echo >> after an exact-line grep; a file whose last key had no
newline got FramePort's key glued onto it, which sshd never matches, so OpenSSH uploads were refused while Paramiko
logged in with the user's own key. Both now add the missing newline first (one shared install_key_command).
Source of truth: announcements/current.md on main (front matter: id, title,
date, optional image/button/expires; Markdown body), read from raw GitHub every
6 h like the catalog, so a push reaches users without a release. Ships
switched off (active: false).
Shown only to people who used FramePort before the announcement's date, never
on a first start; any close (X, click outside, Escape) dismisses that id for
good, and a new announcement = a new id. Centred over the content area, right
of the sidebar. announcements/README.md explains the file;
ui_smoke.py --announcement renders it.
Follow-up to "Update with a newer APK…": Linux apps take their new AppImage/archive or folder (a file or a folder
picker, like the app was added), PC VR games their new game folder. pipeline.replace_linux_app / replace_rift_game
re-run the add path (add_linux_app(replace=) / add_rift_game(replace=)): the entry keeps its package (so the Steam
shortcut), name, artwork, tags, switches and the user's recipe; a folder keeps the program chosen before if it's still
there, else FramePort picks again (and asks, for ambiguous PC VR games). A name that looks like another app's is
allowed with a heads-up.
The entry gets a new source_id, recorded in the deployment's recipe at install (no agent change):
components.source_replaced shows the Frame copy (and a PC install, pc_outdated) as outdated until then. Such an
install also re-sends same-size files changed after the last install (installer.changed_since), since uploads
otherwise skip files the Frame has with the same size. The old PC VR folder is left out of later scans
(replaced_dirs). CLI: frameport new-version <game> <path> (APKs too). Docs: INSTALL.md.
A Frame that only authorizes the user's own key refused OpenSSH, which
offered FramePort's keys alone (IdentitiesOnly), so every upload fell back
to Paramiko. The connection now records which login worked (Frame.auth):
after a login with this PC's own keys/agent OpenSSH also offers private
copies of ~/.ssh/id_* (OpenSSH skips its defaults once -i is given) and the
agent; a refused strict login is retried that way once. FramePort doesn't
add its key to the Frame for this.
New: Settings > Installing > SSH keys (library ssh.extra_keys, CLI
frameport frame ssh-keys): extra private key files for the connection and
OpenSSH, checked with Paramiko (passphrase keys: use the agent). OpenSSH
runs with -v and a refused login's error lists the keys offered and its
warnings. whoami's SID is read from bytes (non-ASCII user names).
Checked with Windows ssh.exe/sftp.exe against the Frame.
sftp escapes * ? [ inside double quotes itself, so FramePort's extra
backslash became part of the path: a folder named "... [ENG] ..." failed
every OpenSSH upload (on Linux too) and fell back to Paramiko. On Windows
the local path now goes with forward slashes: Win32-OpenSSH turned every
backslash, escapes included, into '/' ("C://Users", "/[ENG]").
Checked with Windows sftp.exe and Linux sftp against the Frame (put and
reput, sha256 match).
Deadly Delivery 1.0.30 renders (72 fps), then its lobby's Meta entitlement check
fails four times and it quits. The oculus-entitlement signature is PC VR only,
so the Quest log had no finding. New Quest signature meta-entitlement (error:
offline games may log it and play on; an online game's exit fails the test).
FramePort doesn't get around entitlement checks. docs/GAMES.md regenerated
(it was also behind on other catalog entries).
Consolidates the reusable mechanics: issue templates/labels, the
working-recipe -> catalog path (scripts/catalog_from_issue.py), handling
diagnostics zips (and the attachment-vs-placeholder gotcha), how a change
reaches users (catalog ~6 h vs code needing a release/dev build, and not
bumping a shared revision for a narrow fix), and verifying a device fix
headless. Identity/credentials stay in CLAUDE.local.md.
Doom3Quest-based ports (PreyVR, #306) draw their menu on a curved
cylinder layer submitted once per eye. The Frame's runtime has no
cylinder layers, so FrameBridge shows each as ~7 flat quad strips; a
per-eye pair is ~14 quad layers in one frame, which the runtime rejects
whole (xrEndFrame -> XR_ERROR_LAYER_INVALID, -16). The menu then stays
black while the game runs at 72 fps.
Collapse the pair: drop the right-eye cylinder and show the left eye's
strips to both eyes (the runtime composites a quad to both eyes anyway).
That halves the layer count and drops the per-eye eyeVisibility, and the
runtime accepts the frame. Only frames with per-eye cylinders change --
exactly the ones that were being rejected; mono (BOTH) cylinder games
such as 4XVR are untouched.
Verified on the dev Frame (headless): PreyVR v1.2.4 rebuilt + installed,
the menu frame now submits (one transient -16 on the first frame before
the space is locatable, then clean), 72 fps. Visual confirmation of the
menu needs the headset. Triage signature cylinder-menu-layers-rejected.
No adapter revision bump (installed games are not marked outdated).
Diagnostics only (no behaviour change): the "new layer ... usable=0"
line prints a layer's swapchain pointer, but creation logged only the
result, so a dropped layer couldn't be matched to the xrCreateSwapchain
that made (or failed to make) its swapchain. Needed to pin why a quad
"screen layer" is dropped (#306 PreyVR: menu rendered to a quad whose
swapchain FrameBridge reports as not usable).
Headset-confirmed working configs shared through the issue form:
Tea For God (#295), Ghost Town (#299), Eye of the Temple (#302),
Ocean Rift (#304), Quantum Void (#307), AugmentedEmpire (#311),
Battlemarked (#312), Demeo (#313), Homeworld: Vast Reaches (#314),
Moss (#315), Maestro (#316), Mini Motor Racing X (#317),
Operation Wolf Returns (#318), Ragnarock (#319), Smash Drums (#320),
Vendetta Forever (#321).
Quantum Void, Homeworld: Vast Reaches and Ragnarock go in as status: issues.
Version 1.2.0; catalog min_app 1.1.2 -> 1.2.0 for the entries that need this release (Shadow Point, Medal of Honor, Assassin's Creed Nexus, Journey of the Gods).
Turns on frame.unreal_skip_obb_delivery (and keeps frame.hw_video_decode) so
the fix applies without the user finding the toggle. Not device-verified (the
game is ~41 GB); status unknown, min_app 1.1.2 so only builds that recognise
the obfuscated DownloaderActivity get it.
Medal of Honor (com.Virtuos.R6DLM) keeps Epic's DownloaderActivity and log text but renames the delivery predicates
and OBBData, so expansionFilesDelivered wasn't found and frame.unreal_skip_obb_delivery was never offered. Detection
now also matches a boolean method in the package's DownloaderActivity, called from onCreate, that carries Epic's
"Checking for file : " log and calls the expansion-downloader helpers; the patch rewrites those too. ANALYSIS_VERSION
18 -> 19. Heuristics eval unchanged (10/66); no existing recipe affected.
The GLES-only stand-in left Vulkan games (UNDERDOGS: VkFormat 43, faces=6) with the runtime's refusal, so OVRPlugin
crashed in ovrp_EndFrame4. When there's no GLES context, the adapter now makes a cube-compatible VkImage (6 layers,
the requested format/size/mips, usage from the XR flags) with the app's device/queue and a private transient pool,
transitions it to COLOR_ATTACHMENT_OPTIMAL, and enumerates it as a Vulkan image; its cube layers are still dropped.
GLES behaviour is unchanged. Adapter rebuilt deterministically (both ABIs).
Pre-#263 agents left shortcuts.vdf entries with both appname and AppName; vdf_decode then refused the file
("duplicate VDF key") and Add to Steam library failed. Duplicates are now merged into one key: Steam's capitalized
spelling kept, the last value taken. Clean files still round-trip unchanged.
Only big files (>=8 MiB) used OpenSSH; games made mostly of small files stayed on Paramiko and were slow on a fast
link. native_upload.put_tar streams the same tar batch through system ssh with the paired key and pinned host key;
on any failure the install falls back to Paramiko's put_tar and logs it, and doesn't retry OpenSSH for later batches.
The job log now names the transport for each part. upload_bench gains app-small / paramiko-small comparisons.
- unreal-obb-check-stuck names frame.unreal_skip_obb_check (CRC, needs bVerifyOBBOnStartUp) and
frame.unreal_skip_obb_delivery (the Java name/size gate), and says neither is a guaranteed fix.
- cube-swapchain-refused: the stand-in is GLES-only; a Vulkan game can't use it yet.
- A game that submitted projection frames but then logged no pacing summary for 20 s (process alive) is reported as
frames-stopped (info), so a hang like SKYBOX's signature check isn't a false pass. Headless no-tracking ends are
excluded.
Play on the Steam Frame tab for a game no longer in the library wrote last_played with upsert_game, which created an
entry with only that field: listed under its package name, "Update ready", and Update / Game settings failed with
KeyError 'recipe'. library.set_fields updates existing entries only (last played, test and session results, tags,
toggles); a one-time migration drops entries made of side notes alone.
After "Waiting for app", a failure line or 20 s without a logcat line start FramePort's own reader, from the
launcher's start (logcat -T <epoch>) when the mirror never wrote, else from just before its last line. The reader
restarts from where it ended, stops when Lepton's lines come back, the container's log buffer is 16 MiB, and every
decision goes to logcat-keeper.log.
Merged main (agent 90, ANALYSIS_VERSION 17/18 after main's 15/16) and rebuilt the bridge, foveation and a32
libraries from source (deterministic, no local paths).
Fixes on top:
- a32 loader: apply DT_ANDROID_RELR relocations (Journey of the Gods crashed at start)
- VrApi bridge: vrapi_Get/SetTrackingTransform (floor-level tracking; Shadow Point's player was below the floor)
- a32: never submit an untracked default head pose (hold up to 100 ms, repair or drop); pose consistency per display
time; submit/tracking counters
- VrApi bridge: wait again when xrWaitFrame gives a display time in the refresh just submitted (the runtime rejected
the second frame with AlreadySubmitted; Journey of the Gods ran at ~120 fps on a 90 Hz display and the scene slid
and snapped back); pacing counters
- VrApi bridge: GLES re-entry polls events before reusing the kept session (a lost or exiting session is replaced, a
stopped one waits for READY)
- VrApi bridge: STAGE is the runtime's STAGE space (play-area centre and orientation, unchanged by recentering);
LOCAL_FLOOR keeps the head-based origin
- signer certificate: pick the certificate the SignerInfo names, not the first in the PKCS#7 block
- flat 32-bit apps keep the bridge (it isn't a VR-only fix)
- Frida gadget loads are stripped before translation
- launcher restart test fixed; native/.cache is no longer committed
- catalog: Shadow Point and Journey of the Gods work (headset, 2026-10-14; min_app 1.1.2)
Rebuilt libvrapi.so and libvrapi_foveation.so without the local NDK paths a worktree build left in their debug info; a test checks that no artifact contains a local path.
On Frames whose Steam drops FramePort's shortcuts.vdf entries on every restart
(GitHub #41/#42), "Add to Steam library" restarted Steam twice and then failed
with "Steam removed the new library entry again after restarting". Play's
fallback (the devkit entry, the one Steam keeps) was never reached because
_add_then_play gave up first.
After the second loss the shortcuts worker now adds the devkit entry while
Steam runs, so the game ends up in the library as "Devkit Game: <title>" and
the job succeeds. Agent v89.
- Check the Steam shortcut on every update, also when nothing else changed: a connection lost during
"Add to Steam" or Steam putting its old shortcuts.vdf back left games without a library entry. The
agent restarts Steam only when the entry really changes.
- Artwork updates for installs without a recorded artwork manifest start from a clean folder again
(an old portrait.jpg next to a new portrait.png was picked at random for the Steam grid).
- OpenSSH uploads only rename .part files that are already complete (sftp's reput refuses them, which
sent every resume to the Paramiko fallback).
- frame.tbxr_vendor revision 2: GL4ES ports get "Update on Frame" for the #191 draw fix.
- Configuration-only updates send the library's current Steam tags.
- finalize drops fingerprints and the artwork record an older app didn't send.
- set_settings: malformed numbers are refused before anything is written; int settings keep a
fractional value.
- Display diagnostics use Windows PowerShell 5.1 without pwsh's PSModulePath; window diagnostics and
the instance owner file can't stop the GUI from starting.
Holding the Frame's menu button turned 32-bit (and other VrApi bridge)
games 90-120 degrees to the side. The bridge's app space is LOCAL plus
the head's yaw at the start; the runtime's recenter moves LOCAL to the
head, so that old yaw was applied again. On a LOCAL reference space
change (and on vrapi_RecenterPose, ignored before) the origin is taken
from the head again in the first frame after the change, and VrApi's
recenter count goes up. Owner-verified with Gunjack.
The upstream patches are regenerated against OVRPort 5e7df52 (they
were missing the FOV cache changes).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Moving the mouse over the Library right after its cards were rebuilt (e.g.
the library changed at start, or a view switch) could deliver a hover event
for a card that was already off the page. Its handler called tile.update(),
Flet 1.0 raised "Container(…) Control must be added to the page first", and
an error in an event handler takes the whole app down to Flet's error
screen.
- Library grid and shelf card hover handlers use the safe C.update(tile),
which skips controls that aren't on the page any more (the convention
everywhere else in ui/)
- Settings' index: scroll_to on a page that has already left the screen
(or a closed window: "Session closed") is ignored instead of raising in
the task callback
Seen on the desktop app (Linux) while testing the a32 branch; the code is
the same on main. No automated reproduction (needs a real hover during a
redraw).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Recipes the user edited (source "user") are never re-derived, so a 32-bit
game whose recipe was saved before the bridge existed kept OVRPort and the
64-bit fixes and no bridge. Since 95c5de9 such a recipe can't be built at
all (build.check_a32), so it needed fixing by hand.
The one-time migration a32_bridge_on (library._migrate, after
quest_binary_fixes_v2, which adds frame.vk_sanitize to every Quest recipe)
goes over every 32-bit-only game once:
- adds frame.a32_bridge with the patch's own reason, unless the game's
catalog entry removes it (frame_remove)
- then engine.a32_recipe as for a bridge just turned on: OVRPort and the
64-bit fixes off, device.text_input_window for Unity, a pre-bridge
"unsupported" becomes "unknown"; the recipe stays the user's
- recipes that already have the bridge only lose what it replaces
- skips 64-bit games, PC VR / Linux entries and "install unchanged" games
It runs once per library, so a bridge the user switches off afterwards
stays off.
Tests: a user recipe from before the bridge is migrated, a catalog
frame_remove and a 64-bit game are left alone, switching the bridge off
afterwards sticks; the game page switch test now starts from a migrated
library.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Two ways a 32-bit game ended up with a recipe that couldn't work:
- Catalog entries written before the bridge existed (Journey of the Gods,
Shadow Point: "unsupported: the Frame has no AArch32") dropped the
heuristic bridge suggestion like any other patch the entry didn't choose.
- Turning the bridge on by hand kept OVRPort and the 64-bit-only fixes
(e.g. frame.vk_sanitize) on; they then failed in the build.
Now:
- A catalog entry for a 32-bit game that neither names nor removes
frame.a32_bridge counts as older than the bridge: the bridge stays in,
"unsupported" becomes "unknown" and the note says it's untested with the
bridge (quoting the old verdict). Entries that name the bridge keep their
own verdict.
- engine.a32_recipe (was _a32) also runs in pipeline.set_recipe (game page,
CLI `recipe --enable`, Game settings dialog) and before every build. When
the bridge has just been turned on it also adds what it needs (Unity:
device.text_input_window) and lifts a pre-bridge "unsupported"; later
saves only remove, so a patch the user turns off stays off.
- Which patches work on the bridge is declared per patch instead of two
lists in the engine: Patch.a32 / base.works_on_a32. OVRPort and Frame
fixes are off unless they say a32 = True (the bridge, the adapter, the
launcher entry); FrameBridge settings work unless they need the xrshim
(settings.XRSHIM_SETTINGS, the same list frame.adapter's needs_xrshim
reads now, so a new xrshim setting is excluded by itself). Such patches
are hidden for 32-bit games, also in the Game settings dialog.
- build.check_a32 refuses a 32-bit build without the bridge, or with OVRPort
or a 64-bit fix on, with a plain message instead of failing inside a tool
or producing an APK the Frame rejects (INSTALL_FAILED_NO_MATCHING_ABIS).
engine.warnings(recipe, analysis) says the same on the game page.
- The game page redraws the patch list when the bridge switch changed other
patches; its save uses C.update (warn.update raised when not mounted).
- Parity: a bridge build whose known-good APK is from before the bridge gets
"new build (no baseline)" (no alt check either) and is listed apart from
the games at parity, instead of UNEXPLAINED.
Tests: catalog verdict old vs tested, bridge turned on by hand (incl. a
later switch-off staying off), the lifted status, works_on_a32 per category,
check_a32, warnings, parity baseline + report, and the game page's switch
driven headless (no browser). Not yet built for or run on the Frame with
Journey of the Gods / Shadow Point.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sports Scramble (a 32-bit Santa Cruz build: UE 4.21, OVRPlugin on VrApi 1.21)
now plays in the headset with both controllers.
a32 bridge:
- AAsset_getBuffer: the host buffer lies above 4 GiB, so the guest gets a
copy in its own memory, freed in AAsset_close (Unreal read its
UE4CommandLine.txt this way and aborted on the NULL it got before)
- AKeyEvent_getFlags and the remaining AConfiguration getters
- Touch controllers for Quest builds: apps that require 6DoF head tracking
(uses-feature android.hardware.vr.headtracking version 1) get
assets/fp_a32_headset.txt = "quest" at conversion; the bridge then passes
both Frame controllers through (input devices, caps, state, tracking,
vibration; struct tails per VrApi minor) and sends no synthetic touchpad
events. Gear VR / Go games keep the remote emulation. A32_TOUCH=1/0
overrides.
Analysis: detect.requires_6dof, headset "quest" for such 32-bit apps
(ANALYSIS_VERSION 13).
Agent 82: Unreal restarts the app once after its first-run shader precompile
(the "optimizing" screen): it starts its own launcher activity and exits, and
Lepton ends the container with the first process. Skipping the restart or
turning it off (r.ProgramBinaryCache.RestartAndroidAfterPrecompile=0) left
the game on that screen for good. launch.sh now starts Lepton once more when
the system log shows the app's own LAUNCHER start right before its
System.exit(0) (_restart_requested; first run kept as
launch-before-restart.log; FRAMEPORT_NO_RESTART=1 turns it off).
upgrade_launchers adds it to existing launchers. Crashes, quitting from the
game and Steam's Exit game don't match.
Catalog: Sports Scramble works (owner, headset, 2026-10-13).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Profiled Gunjack and Spunky Dungeon on the Frame with perf and a new
A32_PERFMAP option (a perf map of the translated code: block bodies, exit
stubs, FPCR writes). FPCR switches turned out negligible (8 of 86k samples,
none in Gunjack). The cost was elsewhere:
- The run loop took the translation mutex on every dispatch and walked a hash
chain under it (Gunjack: jit_run 23.6 % of all samples, pthread_mutex_*
about 7 %, plus futex time in the kernel).
- The inline lookup table for indirect branches was only written at
translation, so a hot return target lost its slot for good to any block
translated later into the same slot and went through the run loop ever after.
- Every dispatch did an atomic add/sub on a counter all threads share (4.7 %).
- jit_invalidate scanned every block on each cacheflush that touched a code
page: Unity's Mono JIT does that constantly (72 % of Spunky Dungeon's main
thread in one run).
Now:
- the run loop looks blocks up without the lock (inline table first, then
the hash chains, published with release stores); the lock is only taken to
translate or to chain the exit it came from
- it refills the inline table with every block it dispatches; the refill and
invalidate_block are fenced against each other, so an invalidated block
never stays reachable
- HASH_BITS / LTAB_BITS 16 -> 18 (Gunjack translates well over 100k blocks)
- a per-thread in_jit_section flag + fence instead of the shared counter;
flush_cache sets flush_pending and waits for the flags (threads_any_in_jit)
- per-guest-page block lists: an invalidation visits only the blocks on the
affected pages and drops invalid ones from the lists on the way
Results on the Frame (same build otherwise, same launch conditions):
- Gunjack, 25-45 s after start with OVP_HEADLESS_TEST: 100,462 -> about
45,000 samples in 20 s (about 55 % less CPU), jit_run 23.6 % -> 1.6 %,
pthread_mutex_lock about 7 % -> 0.4 %
- Gunjack, 12-27 s: 72 fps in both, 11,306 -> 9,801 samples, jit_run
10.4 % -> 1.0 %
- Spunky Dungeon, 12-27 s: 72 fps in both; translated code is only 2-3 %
there, so no change. The jit_invalidate phase wasn't reproducible headless
under identical conditions: not yet measured in a played session.
- bench.c (single thread, few dispatches): unchanged.
Tests: run_programs.py (jit + interp, and A32_CACHE_KB=300), bridge harness,
fuzz.py arm-dp / t32 / arm-vfp / arm-neon (0 mismatches), pytest. Both games
pass their launch tests at 72 fps with the final build.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Gunjack (CCP, Unreal Engine 4.10 NativeActivity, VrApi, GLES) runs on the
Frame through frame.a32_bridge, confirmed in the headset by the owner
(2026-10-12). The recipe needs only frame.a32_bridge: the engine adds the
adapter and the LAUNCHER fix and turns OVRPort off, the same patch set as
the build now on the dev Frame.
Notes give the controls (right controller): trigger = fire, A = tap, stick
down = reload (swipe back), stick up = special weapon (swipe forward),
B = back. GAMES.md and the patch docs regenerated.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Gunjack (UE 4.10, Gear VR) has no separate reload or special-weapon input on
the touchpad: every swipe goes to UE4's Gesture_Flick, and
ATDPlayerController::OnFlick reads the flick angle. Below 45 or above 315
degrees (+X, a swipe towards the back of the Gear VR touchpad) it reloads;
135 to 225 degrees (-X, a swipe forward) fires the special weapon. Up and down
swipes do nothing. The bridge sent the stick's up/down as Y swipes, so in
Gunjack those directions did nothing.
For games that read their AInputQueue (NativeActivity), the right stick's
up/down now swipe along the touchpad's own X axis: up = swipe forward
(special weapon), down = swipe back (reload). Left/right are unchanged.
Unity games (AFFECTED, Spunky Dungeon) keep their mapping.
Rebuilt liba32bridge.so. Gunjack was rebuilt and installed on the dev Frame;
the headless launch test passes. Not yet tried in the headset.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Gunjack (UE 4.10, Gear VR) imports no vrapi input functions: it reads the
Gear VR touchpad and back button as Android input events from its
AInputQueue (native_app_glue). The bridge delivered its controller events
through Activity.dispatchKeyEvent, which never reaches native code, so no
control worked at all.
input.c now queues synthetic events in front of the game's AInputQueue:
- AInputQueue_attachLooper (without a callback) registers the queue;
ALooper_pollAll/pollOnce return its ident while a synthetic event waits
(ALooper_wake ends a blocking poll), AInputQueue_getEvent hands it out,
finishEvent frees it.
- The AInputQueue/AInputEvent/AKeyEvent/AMotionEvent imports are written
by hand ("!" in imports.txt) and answer for synthetic events; real
events go to libandroid as before.
- Touch positions are scaled to the activity's window size
(native_activity.c records it).
Mapping (right controller, as for AFFECTED: The Manor): trigger = hold
the touchpad, A = tap, right stick = swipe, B / left menu = back. Unity
and other Java-delivered games are unchanged. A new input_start (VR
re-entry) ends the previous poll thread.
Also: the libandroid functions the host side calls directly are weak
references again, so the PC test harness links (it broke with the
AAsset calls of the signature loader); bridge/test/run.py passes.
Headless on the Frame: "controllers: the game reads its AInputQueue",
72 fps. Not yet verified in the headset.
Gunjack (CCP, UE 4.10, Gear VR) quit after loading because AndroidMain compares
GameActivity.AndroidThunkJava_GetSignature() with the original signing
certificate, and then crashed in the Frame's runtime when it entered VR again.
a32 bridge:
- frame.a32_bridge: original_signature() = Base64.DEFAULT(SHA-1(signing
certificate DER)) of the original APK (META-INF/*.RSA|DSA|EC), stored as
assets/fp_a32_signature.txt for libUE4.so games (convert(), shared with
bridge/convert.py)
- the bridge loads it at activity creation and answers guest calls on the
method ID of AndroidThunkJava_GetSignature()Ljava/lang/String; with it
(replaces the unused hex/OpenSSL prototype)
VrApi bridge: after loading, Unreal leaves VR mode and enters it again on the
same GL context; the first frame of a second OpenXR session there aborted in
vrclient (CSharedSemaphoreLinux::WaitFromGPU from the GL binding's
PreBeginFrame). vrapi_LeaveVrMode now keeps a running GLES session and
vrapi_EnterVrMode reuses it for the same context (another context still gets
a new session; Vulkan unchanged). upstream-patches/runtime.cpp.patch updated,
libvrapi.so and liba32bridge.so rebuilt.
Verified on the Frame: headless launch test passes (72 fps after re-entry);
owner-verified in the headset.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
32-bit-only APKs (Gear VR / Oculus Go games) are no longer "unsupported": the
recipe engine suggests frame.a32_bridge, which converts the APK with the
translator bridge (convert() shared with bridge/convert.py) and ships
liba32bridge.so / liba32rt.so / liba32stub.so (native/build.py --only a32).
FramePort:
- engine._a32: overport off (OVRPort is 64-bit only; the patch ships OVRPort's
loader chain + its 32-bit platform dispatcher, overport.ensure_runtime_lib),
only frame.a32_bridge/adapter/launcher of the frame patches, 64-bit-only
adapter settings dropped, device.text_input_window for Unity; such patches
are hidden in the UI
- analysis extra.headset (ANALYSIS_VERSION 9): quest / go / gearvr ->
"Gear VR" / "Oculus Go" platform + Steam tag; catalog `headset:` field
- expects_obb ignores Unreal's OBB-inside-the-APK (assets/main.obb.png)
- catalog: com.fallen.affected, net.mobilemischief.spunkydungeon
Bridge / translator:
- VrApi 1.31 + Unity 2019 (no-config EGL contexts, LOCAL_FLOOR/STAGE tracking
space), GL buffer mappings per buffer object (fixes a ~10 MB/s guest leak and
garbled vertices), Go controller mapped to the right Frame controller
- native_app_glue imports (ALooper/AInputQueue/AConfiguration/AAsset*) for
UE4 NativeActivity games (Gunjack: runs, then quits on its own APK signature
check, which FramePort doesn't defeat)
- debugging aids: A32_BREAK, A32_STRACE to logcat, lifecycle/LeaveVrMode logs
vrapi-bridge: honours LOCAL_FLOOR/STAGE, picks a window/RGBA8 ES3 config for
no-config contexts; upstream patch updated, libvrapi.so rebuilt.
Verified on the Frame: Spunky Dungeon (Unity 2019.2, OVRPlugin 1.46) plays at
72 fps; AFFECTED The Manor still runs.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
32-bit ARM (armeabi-v7a) libraries run inside a normal 64-bit Android app on the
Steam Frame, without Android's native-bridge mechanism (no Lepton changes): each
libX.so becomes libX.a32.so plus a 64-bit stub, next to liba32bridge.so (the
translator + host glue) and liba32rt.so (a 32-bit static-PIE runtime with bionic's
libc/libm/libz/libstdc++ and a loader for the game's libraries). Guest and host
talk through hypercalls (SVC 0, r7 = 0x0a32xxxx).
Bridge (native/a32translator/bridge):
- JNI both ways: generated + hand-written JNIEnv/JavaVM, RegisterNatives and
Java_* exports through AAPCS64 -> AAPCS32 trampolines, handles for references,
arrays/strings shared when below 4 GiB, else copied
- NativeActivity glue, libandroid imports (weak, generated from imports.txt)
- GLES 3.2 + extensions + EGL: 996 functions generated from the NDK headers
- OpenSL ES output implemented in the guest, played through AAudio
- VrApi 1.x (Gear VR era) translated to the 64-bit VrApi -> OpenXR bridge,
including OVRPlugin 1.12's frame layout and its wrapped (app texture) chains
- controller input as Gear VR touchpad/back/gamepad events (UnityPlayer.injectEvent)
- convert.py: prototype of the APK conversion (FramePort patch to follow)
- PC harness with a fake JVM (32 checks, qemu or native) and an on-device test APK
Translator fixes found on the way: guest signals during blocking system calls
and in host code (Boehm GC deadlock in Unity's Mono), static-PIE start files and
PT_TLS/PT_GNU_RELRO bias, host fault chaining, stderr to logcat in bridge mode.
vrapi-bridge: OVP_HEADLESS_TEST=1 skips the wait for a tracked head (automated
tests without a worn headset); upstream-patches/runtime.cpp.patch updated.
Verified on the Frame (2026-10-10): AFFECTED The Manor (Unity 5.6 + Mono,
OVRPlugin 1.12) runs in the headset with picture and sound; controls in progress.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Interpreter + JIT for ARM, Thumb-2, VFPv4 and NEON, ARM EABI syscall
translation, signals, threads and self-modifying code. Runs static bionic
programs on the Frame. Tests: A64 encoders vs llvm-mc, a differential
instruction fuzzer and program tests against qemu-arm. Not shipped; the
README lists the steps towards running 32-bit-only APKs.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Agent 85: the game's container gets the host's /dev/input at /dev/fp-input (Lepton's /dev/input holds its own Wayland
input pipes) and the launcher's _gamepad_links worker keeps /dev/input/eventN links to Steam Input's virtual pads in
step while the game runs: controllers switched off and on again (Steam makes a new pad) work without a restart.
Android's EventHub adds and removes the links through inotify (dev Frame, uinput stand-in pad created after boot:
New device, Device removed, added again). Older launchers get the new gamepad line through upgrade_launchers.
The key layout also maps BTN_DPAD_* (a Steam Input layout that sends the D-pad as buttons, e.g. a stick set to
D-pad; the Frame's controllers have no D-pad of their own).
Pick the new APK from the game's right-click or … menu: pipeline.replace_apk checks it's the same app (refuses
another package, warns when its versionCode is older), points the entry at it and analyses it again; title, art, tags
and the user's own recipe stay, the game data stays unless the new APK's folder has its own. The game page then
offers Update on Frame.
- HostKeyChanged (paramiko BadHostKeyException): not treated as "can't reach" (jobs don't pause and retry); the
Steam Frame page explains it and offers Trust the new key (forget_host_key + reconnect); CLI frameport frame trust-key.
- Uninstall from the running app: instance.release() drops gui.lock before the data folder goes, and files still in
use are reported as left over instead of stopping the uninstall (Windows).
Both from Reddit reports (2026-10-12).
bHaptics' vest SDK asks for BLUETOOTH_CONNECT at start; on Lepton's Android 11 the permission screen takes the
foreground for a moment and the game pauses (Yupitergrad froze on its loading screen in the reporter's session).
PermissionUtils.requestBluetoothPermission returns at once (Dex.return_early). Suggested by analysis
bhaptics_permission (ANALYSIS_VERSION 14) and triage bhaptics-permission-prompt. On the dev Frame the prompt is gone;
whether it was the whole cause of the freeze is for the reporter to confirm.
Opt-in game setting (Picture -> Draw fades over the picture). Batman: Arkham Shadow fades by dimming its projection
layer with XR_KHR_composition_layer_color_scale_bias; with fade_quad=1 FrameBridge adds a black, alpha-blended quad
right after the dimmed layer (VIEW space, 1 m ahead), opacity = 1 - scale in 16 steps. One 8x8 swapchain, refilled
only when the step changes (Vulkan clear on the app's queue / GLES clear in its context); one swapchain per step hit
XR_ERROR_LIMIT_REACHED. fade_quad=2 also removes the layer's own scale. Device (headless, Batman): swapchain created,
level 16/16 on the first frame, no xrEndFrame errors, 72 fps.
The game showed a canvas being painted as its own compositor layer, which the Frame draws in front of everything.
PaintableMesh.HasCompositorLayerAvailable and ShouldUseCompositorOverlay return false (Cpp2IL), so the game's own
fallback draws the canvas in the scene (Klownicle's finding). Catalog recipe, PLAYBOOK row, test.
No Cpp2IL release reads Unity 6.5's metadata yet ("We support 23-106, got 107"), so the text-field and MSAA
fixes were skipped for Wander 0.3570 (#198). When the release reports an unsupported metadata version, the
development branch's CI build (nightly.link, as Cpp2IL's README links it) is fetched into tools/cpp2il-nightly/
and used; cached errors of that kind get one retry with it. Checked with Wander 0.3570: it reads the v107
metadata and writes TMP_InputField, OVRDisplay and OculusLoader.
Bionic allows 128 pthread keys per process. Unity 6 takes about 40, and with Gecko, Firebase and the Frame's own
libraries Wander 0.3570 ran out: Firestore aborted at start ("cannot create thread specific key for
__cxa_get_globals()", #198, #202). Opt-in patch, suggested for Unity 6 with Firebase C++ or Gecko: libunity.so's
pthread_key_create/_delete and pthread_get/setspecific imports are renamed in place to fp_tkey_* (new
elf.rename_imports: undefined symbols only, shared names refused, versions set global) and libfp_tkeys.so
(native/tlskeys) is added to its DT_NEEDED; keys without a destructor become generation-tagged slots behind one
real key, everything else keeps real keys. Approach and the first helper by Klownicle (#198), reimplemented here.
Triage signature pthread-keys-exhausted, PLAYBOOK row, Wander's recipe updated to 0.3570.
Installs the new build and leaves the game data on the Frame as it is (the CLI's --apk-only): a normal update
re-sends every OBB whose size differs from the PC's copy, which replaced OBBs changed on the Frame (mods). Asks
first; Quest games on the Frame only. Resume after a failure keeps the kind of update.
New games are checked against the drive chosen on the Frame page, installed ones against their own drive, from
the drive list fetched at connect and after install jobs (app.frame_drives). Internal storage's free space only
counts when no drive list is known. drives.target_drive/space_shortfalls are pure helpers with tests.
Flet's Linux picker asks the XDG desktop portal; window managers without one (IceWM, bare X11) answer
NameHasNoOwner and every pick raised. C.pick_files / C.pick_dir now fall back to zenity or kdialog (kdialog
first on KDE; core/pickers.py, run off the UI loop), and without either to a "type the full path" box. All
twelve pickers go through them.
Agent 83: deployment.json desktop_icon (default on); refresh_desktop_entries only updates a desktop copy that is
there; desktop_entry takes icon=. Game page: "In the app menu" and "On the desktop" switches.
- Agent 83: Valve's Lepton pastes the game's paths unquoted into shell commands (liblepton mounting.sh), so a game on
a card named "Steam Frame 512g" never got its internal storage (no saves, no SharedPreferences). The Quest launcher
now links the game folder to ~/.local/share/frameport/lepton-paths/<pkg> at every start and gives Lepton that path;
upgrade_launchers converts existing launchers, move and uninstall handle the link (#213, #214, #215, #221).
- frame.eos_keychain_loop (opt-in, offered by triage): Epic Online Services' resetKeychain returns at once, so a
keychain it can't write no longer loops forever (Beyond Sandbox, #214).
- Triage lepton-data-link-failed and eos-keychain-loop.
- CryEngine also from libAndroidLauncher.so + a .cryproject (Climb 1, #238); ANALYSIS_VERSION 12.
- Plain words: patch titles lose bracketed internals unless Show technical details is on (C.patch_title); a passed launch test just says so, how far it got shows only when it fails (C.test_line); Frame page readiness says Quest games / PC VR games and storage drops the file system (reason in a tooltip); the failure pop-up says where it stopped, that Resume continues and that saves and signing keys are kept. Engine and VR API stay on the game page; the OpenXR runtime and game launch capacity checks stay; the first start still names its tools.
- Readable dim text: TEXT_3 is #868A96 (Portal, Portal OLED) and #868B9C (Original), at least 4.5:1 on the window, sidebar, cards and raised panels (was 3.6-4.4:1); a test keeps the built-in themes there.
- Quieter empty tabs: the not-connected Files, Screenshots, Live view, Type on Frame and Monitor tabs show one sentence and Connect above a faint sketch of the tab (C.ghost_preview) instead of three feature cards; the Live view shows one Start button and no feature cards.
- The connect page has one way in: "Set up your Frame" up front (no password, nothing changes until you allow it), "Already set up?" below, the address and password behind "Connect by address…"; no 1/2/3 numbers.
- Consistency: every switch is C.switch, with the portal gradient painted under a transparent track (the real Switch keeps keyboard, focus and semantics), a dark thumb with a check when on and a grey one with a cross when off (the same size); where a patch came from is blue information, not orange; the platform filter says "Quest/Android"; the welcome screen says "Set up your Frame".
- Showcase: the live-view shot waits for "Ready when you are"; the install video clicks "Set up your Frame".
- Section labels name what you do there ("See how it works", "See what runs", "Get started") instead of 01-07; plain headlines ("What happens when you click Install on Frame", "FramePort patches the games that don't run as they are"); the hero's eyebrow is gone; nav "Install" -> "Get started" (no clash with the /install/ link page)
- Phones and narrow windows (below 1120 px) get a Menu panel instead of a hidden or wrapping nav; on phones the download buttons say "Get it on your PC"; no three.js on data saver or 2G/3G; the install log drops its detail column under 600 px
- The download page says why Windows and macOS warn on first start (self-signed) and where the SHA-256 sums are; Get started step 3 says nothing changes on the Frame until you click Allow, with a link to the script
- The app tour's screenshots and videos sit behind one disclosure; the game-maker panel shows the demo button on its own stage with the HTML behind "Show the HTML"; Compare without icon tiles, Free and open source stays the emphasized card
- Quieter motion: no cursor light, pointer-lit heading gradient or film grain; sections settle in with a 10 px rise, heading words rise without the tilt, labels decode once, a faint click ripple, a gentler hero lean, a lighter spring (--ease-spring); the warp field, the contributor dock and the gradient changelog version stay
- Readability: dim text #868a96 (4.77:1+), themed placeholders, pending install-log stages stay readable, no labels under 11px, the walkthrough shows each platform's real file and program (was "?os=linux" and FramePort.exe)
- Impeccable design-tool files (PRODUCT.md, DESIGN.md, .impeccable/) are ignored: they stay local
The title's grid-column 2 / -1 from the wide layout added an implicit second column in the one-column layout,
squeezing FramePort's text to one word per line beside the other tool's.
The search and buttons sat in an auto column that took the width and left "Libr" and one word per line for the
title. Narrow (icon rail): title, full-width search, buttons and Add games each wrap below. Tablet widths: the title
keeps its own width.
Stacked (<= 900 px) the scene sits below the hero text, so --sp measured from the page's scroll had it blurred and
enlarged by the time it reached the middle of the screen. There it now follows its own position (0 until its middle
passes 40 % of the screen height). Wide layouts keep the old mapping. The empty-space click rings and the install
badge's press ripple skip touch pointers.
Epic's DownloaderActivity checks the OBB's name and size and, with the manifest's
bVerifyOBBOnStartUp=true, CRC-checks the whole file; its screens are invisible in Lepton,
so games like Contractors seem to hang at 'Displayed .../.DownloaderActivity'. The patch
flips that manifest boolean (axml.set_meta_data_bool, one 4-byte value); analysis
unreal_verify_obb (ANALYSIS_VERSION 11) suggests it. Triage unreal-obb-check-stuck (fatal)
fails such launch tests; triage keeps system_server's lines about the game's own activities.
Game menu (Library right-click, game page "Name and artwork") and CLI 'frameport rename <pkg> "<name>"|--reset'.
The title is locked (title_locked + auto_title for the reset); rescans, Rift store matches and install links only
update auto_title; a chosen name gets no Quest/Rift twin suffix. Installed copies: the Frame's deployment.json title
changes and the shortcut is rewritten with the same appid (matched by Exe), one Steam restart; PC VR installs on this
PC keep their appid too (reinstalls and library updates now record the shortcut's real appid). A Frame that isn't
connected shows "Update name on Frame" on the game page until then or the next install.
SteamVR's auto-launch flag (SetApplicationAutoLaunch) didn't persist on the dev
Frame and a registered watch didn't start by itself. The deployment's overlay
autostart flag is now the source of truth: ensure_host_fixes installs the user
service frameport-vr-overlays.service while an installed overlay app has
autostart on (removed when none has, on uninstall/purge, or with the kill switch
~/.local/share/frameport/vr-overlays.disabled / FRAMEPORT_NO_OVERLAY_AUTOSTART).
It polls every 5 s for a new vrserver (pid + start time, remembered across agent
updates), waits until SteamVR answers, gives SteamVR's own auto-launch 15 s and
starts each autostart overlay app that isn't running (process of its folder or
GetApplicationProcessId) through LaunchApplication, in a child process with a
timeout. Log: ~/.local/share/frameport/vr-overlays.log (capped).
Godot 4.2-4.4's Kotlin code casts getSystemService(CLIPBOARD_SERVICE) with a
non-null 'as ClipboardManager'; Lepton has no clipboard service, so the app
crashes with a NullPointerException in Godot.<init> (4.3/4.4) or on first use
(4.2's lazy property). In place in classes*.dex, matched exactly: the
Intrinsics.checkNotNull before that check-cast becomes nops (older kotlinc
branch forms: the branch is fixed), and Godot's getClipboard/hasClipboard/
setClipboard return at once (Dex.return_early gains String -> "").
Analysis field godot_clipboard (ANALYSIS_VERSION 10), triage
godot-no-clipboard, PLAYBOOK row, unit tests on synthetic dex. Checked against
godot-lib 4.1.4-4.7.2 from Maven Central and the 4.3/4.4.1 export templates:
4.2.2, 4.3.0, 4.4.1 patched (D8 re-reads the result), the others untouched.
Host OpenVR overlays are composited over Lepton (Quest) games on the Frame;
Windows overlay apps register through Proton's vrclient. Detect overlay apps
(bundled .vrmanifest with is_dashboard_overlay, or OpenVR + IVROverlay +
self-registration), patch pcvr.vr_overlay and the Linux entry fields
vr_overlay/vr_overlay_autostart, agent register/unregister/launch_vr_overlay
(IVRApplications through SteamVR's libopenvr_api.so; manifest with
binary_path_linux_arm, the only key the Frame's vrserver reads). Overlay apps
skip launch tests and the Linux Steam-parent watchdog and don't count as a
running game. Probe sources in native/vroverlay_probe.
Some browsers (Flatpak ones on Linux) opened the issue form with the
title but every field empty. The issue links now also come as the
Markdown body GitHub's forms write (### sections, the recipe as a yaml
block, which catalog_from_issue.py reads) and a plain issue link with
that body, trimmed to the same URL limit. The GUI copies the body to the
clipboard when it opens the form and offers "Form empty? Open a plain
issue"; the CLI prints the plain link. A shared recipe is marked shared
only after the link was opened.
The {"modules": …} message and take_screenshot reached main with agent 73 (the ui-refresh
branch's v63-v66 numbers collided with main's). MIN_AGENT_MODULES was 65, so agents 65-72
were sent a message they ignore.
Network scans for Valve's pairing port now leave out docker/bridge/veth/tun/tap/wg/tailscale/
zerotier/vEthernet/utun-style interfaces and loopback, link-local and 100.64/10 addresses
(discovery.local_subnets, also used by the Frame search). Each scan that finds nothing doubles
the wait (30 s up to 5 min); another set of networks or opening the Frame page starts over.
Architecture: the module overview and the self-update flow are SVG diagrams
(docs/images, shown on GitHub and the site); the update details the old drawing
carried are a short list under it. FAQ: the game-folder layout is a tree block
the site draws as a real file tree (scripts/filetree.ts). Diagrams scroll sideways
on phones instead of shrinking. Docs pages on phones: the sidebar no longer kept
its desktop offset, which pushed it over the page title.
Open requests whose /wait polling stopped for more than 2 x WAIT and decided ones older than
DECIDED_KEEP are dropped (on /hello and every few seconds); the Frame page shows only open,
unexpired requests and redraws when one expires. setup.sh tells a full queue apart from an
unreachable PC. The fallback Frame name in a request is translated.
Agent v74: with an index.txt, collect_diag sends every module named in the
newest session (after the last '# start'), deduplicated, last used first,
each up to 4 MB and up to 30 MB in all, plus that session's index lines.
A reporter's GPU hang came ~10 s after the last new module, so the newest
written modules missed the culprit. Without an index (fp_spirv) nothing
changes. The bundle drops the least recently used modules last when the
zip would pass its size limit.
Cloudflare Web Analytics (cookieless) runs when the CF_ANALYTICS_TOKEN repo
variable is set. Google Analytics (GA_MEASUREMENT_ID) loads only after the
visitor clicks Allow on a small card with equal Allow/Decline buttons; the choice
is remembered, Cookie settings in the footer asks again, Decline removes the
_ga cookies and Global Privacy Control counts as Decline. Downloads are counted
as file_download events. New privacy page. Without the variables the site has
no analytics.
Conflicts kept main's features with the site branch's wording: the uninstall
dialog's new delete-saves option, hardware video decoding and last-session help,
new Game settings (plain labels), agent 73 (main's 72 plus the Take screenshot
command from v66). Main's new texts follow docs/STYLE.md (for example, patch/setting
instead of fix). Pages rebuilds on docs changes and daily; the CNAME file is
gone (the domain is a Pages setting).
Sitemap and robots.txt, complete Open Graph and Twitter tags, JSON-LD
(the app as a free SoftwareApplication with its current version; docs as
articles with breadcrumbs), a written description for each docs page, a
releases Atom feed, a 404 page, and titles that say what people search for.
/changelog/ shows every release's What's new part (the same parts the app's
changelog shows): the dev build as Coming next, the latest release large,
then a timeline; the home page shows the latest changes. Release jobs
restart the pages workflow so a new release appears on the site.
Plain words on every page, one label per action, no jargon on the home
page. The site moves to the custom domain frameport.app (CNAME, no
/frameport base); the setup line is curl -sL frameport.app/s | bash.
README is a short overview that links to the install guide; repeated
sections are said once; Share working recipe everywhere; the setup
script names the real buttons; a shorter notice, the same as the site's.
Dialogs, help texts and tooltips cut to what the user does or gets, one
name per action (Start setup, Uninstall FramePort, Update art on Frame,
Rebuild only), plain launch-test results (C.test_result), plain summaries
for every Game setting. The setup line now points at frameport.app.
Lepton's Android only gets keyboard, pointer and touch from the Wayland seat. The opt-in patch (2D apps; suggested
when the manifest declares android.hardware.gamepad or LEANBACK_LAUNCHER, ANALYSIS_VERSION 9) makes the agent record
steam_gamepad in deployment.json and give the launcher a line that exports SDL's hint
(LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD) and puts FramePort's own Podman wrapper (agent/bin/podman,
written by ensure_host_fixes, independent of the video codec) first on PATH. For the game's podman run it bind-mounts
Steam's virtual pads (uinput, 28de, gamepad buttons) at /dev/input/eventN plus an Xbox 360 key layout, then hands on
to the next Podman after itself (the codec wrapper or Podman), so both wrappers chain in either order.
FRAMEPORT_NO_GAMEPAD=1 turns it off for one start; failures keep the arguments unchanged. Verified headless on the
dev Frame with a uinput stand-in pad: Android's EventHub opens it with our layout and dispatches BUTTON_A.
Adapter setting vk_shader_dump=1: every distinct module once to files/fp_vk_shaders/<size>_<sha256>.spv, each
vkCreateShaderModule as one index.txt line (order, time), to find the shader behind a GPU hang for a vk_shader_fix.
Agent v72 collect_diag returns the newest dumped modules (Vulkan and OpenGL ES dumps); diagnostics bundle them.
Triage gpu-hang suggests the dump for the session's graphics API (FrameBridge's swapchain formats).
- Two more Frame-side worlds (envs-neon.ts): a rain-soaked neon megacity, and a Tron-like arena with light cycles.
- A game's world comes from a hash of its title (FNV-1a): with seven worlds the old palette mix gave every
title the same remainder, so one world never came up and another four times in ten.
- Download page: no round countdown ring; the countdown runs round the portal's own rim, a tunnel of rings
sinks away inside it (the rim is a masked band, so the way through stays dark).
- The trial's live view shows one eye, as the app's does.
- Headings reveal slower again.
The Steam Frame (or This PC) card gets a log button when the game's last launch test ran there: it opens the
saved log (last_test.log_path) in the launch log viewer. The showcase's demo library writes a short made-up log for
each passed test so the button shows in the docs pictures.
- Docs: search across every page (highlights where you land), definitions for jargon on hover, tables you can
filter and sort, step lists you can tick off, the tutorial video in place, zoomable pictures, section links that
copy, / [ ] keys, a reading path per goal on the overview and a mark on pages you've read.
- /download/: every Download button leads here; a countdown while the package goes through the portal, then the
download starts; a manual button stays, with version, size and SHA-256 from the release and the next steps.
- Two more Frame-side worlds: an aurora over a frozen lake, and a reef. Shared helpers moved to envkit.ts.
- Asteroids and floating islands no longer tear: corners shared by several faces move together (moveCorners).
- Built on: every project links to its page. Compare: no update row; Rift games not supported by the others.
- Headings reveal a little slower.
- The Frame side of the hero picks one of three worlds per game (grid, islands, space); the particles option is gone.
- The trial's Live view shows the same worlds through two lenses (vrscene.ts), one scene per stream, CSS fallback without WebGL.
- The trial looks more like the app: window bar, Library header/filters/shelf, game page, Frame card with now playing and power.
- The install log follows the game: package, conversion, its patches, version and note; the recipe opens under board rows.
- Calmer motion: no button drift, smaller click ring and cursor light; the gallery carousel shows the real screenshots again.
- Install tutorial video (docs/showcase/videos/install.yaml, re-recorded by record_video.py): Start setup, a card
for the setup line on the Frame (with the Developer Mode route in its note), the Frame asking and Allow clicked,
a card for what the Frame then does by itself. Showcase: the fake pairing server takes asks; hook `frame_asks`.
- Site: the Install section is a six-step walkthrough (download, Start setup, the line or Developer Mode on the
Frame, Allow, it sets itself up, add games and play), each step with a small live scene: the download unpacks,
Start setup shows the line, Konsole types it and finds FramePort, Allow moves on, the setup ticks off, a game
installs. The other ways link to /setup.
While no Frame is connected, FramePort watches for Frames in Developer Mode (Valve's devkit mDNS, else a scan every
30 s for Valve's pairing port, one entry per Frame by host key). One that already lets FramePort in is connected; one
that doesn't is offered FramePort's key through Valve's pairing every few seconds (refused at once until "Pair new
host" is open on the Frame, then the request shows in the headset; a 45 s pause after an unanswered one). So the user
only opens Pair new host and approves in the headset.
- frame/autopair.py (no Flet, callbacks), app._start_auto_pair, setting frame.auto_pair (switch on the Steam Frame
page, default on); never with FRAMEPORT_HOME or FRAMEPORT_NO_AUTO_PAIR (tests, screenshots).
- Checked on the dev Frame: found by the scan (this WSL PC doesn't hear its mDNS), FramePort's key recognized, no
pairing request sent. The headset approval path needs a Frame that doesn't know FramePort yet.
Iris returns an empty capture buffer (bytesused 0, no LAST flag, time 0) for every VP9 frame that isn't shown
(alt-ref frames split from superframes). FFmpeg's V4L2 wrapper takes any empty capture buffer during a drain
for the end of the stream, so the first hidden frame decoded after EOS ended it and the pictures still in the
driver were lost (two-pass VP9 4K: 573/600 and 617/640, always the last frames); outside a drain the empty
buffers were returned as pictures, which the component then guessed away by counting hidden frames.
build.py now patches v4l2_context.c to requeue empty capture buffers without LAST/ERROR; the drain ends at the
LAST buffer, or after a skipped empty buffer at one silent second, so it can't block. The component's
hidden-frame counting is removed. Dev Frame (Batman's container): two-pass VP9 4K 600/600 and 640/640 in
hardware with the same Y hashes as OMX.google.vp9.decoder (seek phase too), VP9 without hidden frames,
H.264 4K and HEVC 4K 600/600, VP9 surface output 600/600. Two builds (different dirs and NDK copies) give the
same libstagefrighthw.so 141de01f.
- Opt-in per game: only launchers of games whose recipe has frame.hw_video_decode (install stage, no APK change;
suggested from analysis media_codec, ANALYSIS_VERSION 8) get the codec line (deployment.json hw_video_decode,
finalize + upgrade_launchers). Games that had agent 70's per-game codec (Batman) keep it; their old
<base>/frameport-codec folders are removed afterwards. Batman: catalog + migration batman_video_patches
(frame.hw_video_decode + the hidden adapter setting surface_native, no more package check); 4XVR catalog.
- Off switch: Settings -> Installing "Hardware video decoding" (library video.hw_decode, default on) -> agent
video_codec_switch (video-codec/disabled, checked by the launcher line and the wrapper); FRAMEPORT_NO_HW_VIDEO=1
for one game.
- Connection: the codec is checked once per connection, also after a failed install; a Frame keeps the same or a
newer revision built elsewhere (logged) instead of flip-flopping between PCs.
- Wrapper: the merged media_codecs.xml goes to $XDG_RUNTIME_DIR/frameport-video, never into the version directory.
- Decoder: refused (busy) Iris sessions retry until 20 s after the plugin loaded (SteamVR's link holds a session
~12 s at game start), else 2 s, before the software fallback; VP9 capped at 4096x2304 (XML + component, larger
decodes in software); hidden VP9 frames' pictures dropped. Manifest revision 7.
- build.py builds from paths with spaces and from freshly extracted FFmpeg sources. Artifacts rebuilt here, identical
from two trees (ext4 and the NTFS repo path, two NDK copies); PR #128's own sources rebuild to its binary.
- AGENT_VERSION 71 (matches the connection's gate); triage hw-video-decoder-busy, PLAYBOOK row, docs.
INSTALL and FRAME_SETUP describe the setup line, the Allow step and the announcement; the setup command, USB cable
and Valve's pairing stay. FRAME_RUNTIME records what was checked on the dev Frame (Chromium via Steam's +, mDNS from
the Frame only on port 5353, avahi-browse not usable over SSH). README's quick start uses the line.
- /setup: the three steps (Start setup on the PC, the line on the Frame with Copy, Allow), a terminal that plays what
the script prints, what it changes, and every other way (setup command, USB cable, Valve's pairing, address).
- The site serves bootstrap/setup.sh as /s and /setup.sh (copied at build time; the workflow rebuilds when it changes).
- Install step 2 starts with a "Setup page" tab; the trial's Steam Frame page and guided tour use the same flow
(the Frame asks, matching code, Allow).
One line for every Frame and PC, served by the project page: curl -sL spoopyghosty0.github.io/frameport/s | bash.
- bootstrap/setup.sh finds FramePort (stdlib mDNS on 5353 for _frameport-pair._tcp; else the USB cable's address and
a /24 scan of /ping), asks with /hello, shows 4 digits, waits for Allow, then runs exactly the typed line's
`curl -fsS <pc>/<code> | bash`: bootstrap.sh is unchanged.
- PairingServer (no second server): /ping, /hello (max 3 open asks), /wait (long poll; code only once allowed),
decide(); announces itself over zeroconf while running (name, port, two words for this PC's key; never the code).
- Connect page: "Start setup" shows the static line, incoming asks as Allow / Deny cards (a toast elsewhere);
"Use the setup command" keeps the address + code line; USB setup unchanged.
- The app key is created under a lock (the announcement and the page asked for it at once on a first start).
- Tests: approval/deny/limits/timeouts, the code never in the announcement, setup.sh end to end against a real server
with a stub bootstrap (allowed and denied), digits match. ui_smoke --setup-url drives the page.
Checked on the dev Frame with a stub bootstrap: found by mDNS and by the scan fallback, allowed, code handed over.
- Hero, Frame side: the card is gone; the game opens into an abstract VR world (three.js, look around by dragging or
tilting the phone) or into particles that gather into a shape for the game. A TEMPORARY toggle under the scene
switches between the two for comparison. three.js loads only when the hero is on screen.
- A Steam Frame you can turn (the logo's visor, extruded) next to "Connect the Frame".
- No pictures of the app on the page: the carousel's slides are live copies of its screens (type, drop a file, end a
process, switch themes), the video tiles play short silent loops (made at build time with ffmpeg), the install
button is a live control.
- Scroll story: the hero flies toward its portal, the install log completes line by line, section lines draw in.
- Everything reacts: a portal light follows the pointer, clicks on empty space ripple blue then orange, headings rise
in word by word and light up under the pointer, labels unscramble, numbers count up, each icon moves its own way.
- Hero: the Frame-side card is the game running in the headset (one view per eye, the scene moving), switching on
as it lands while its frame rate climbs to 72 and the pacing line draws.
- App demo: working search, right-click menu, select several and install them (queued), install from a link (the
app's link rules), Screenshots tab with a viewer, Settings with the real themes switching live, Files that take
real files from the desktop (they never leave the tab), process table with End, Live view quality, launch-test
result, technical patch ids, toasts; Wi-Fi or USB cable when connecting. Progress ticks no longer rebuild the page.
- Screenshots: a carousel (arrows, keys, swipe, thumbnails, autoplay that pauses for the reader, full screen).
- Compared: four headline differences (free and open source first), every difference as user questions behind
"Show all differences"; the README says the same.
- Wi-Fi or USB cable said everywhere; the setup command explains itself part by part; first-start steps per system.
- Field notes removed, the notice kept in its own band.
- Built on: contributors wall (code, pull requests, issues; scripts/contributors.mjs, saved list as fallback).
- Docs: user-facing docs/*.md as pages (links rewritten, GitHub heading ids, contents with scroll position, copy
buttons).
- Games board rows open to show the recipe; the install log replays with another tested game.
- "Meta Quest" only as a description (headline about the Steam Frame), trademark line in the footer.
- Hero cards: generated covers in the style of the app's placeholder art (hue from the title), the same app icon on
both sides of the portal, a one-line APK name, stage ticker and progress, Play ripple, sparks; titles sized so
words never break. Click the portal for the next game; the scene leans toward the pointer.
- "The app": a clickable, simplified FramePort window (Library, game page with patch switches, Steam Frame, Files,
Live view, Type on Frame, Monitor with live sparklines) and a guided tour from a fresh start: connect the Frame,
scan a folder, install, play. The showcase videos play in a lightbox.
- Compared: FramePort, FrameDrop and Valve's own tools, from their own pages (checked 2026-10-09); the same table in
the README.
- record_video.py --size WxH (e.g. 2560x1440): films at that many device pixels; postprod reads the size at call
time and draws cards at the 1920 layout scaled up. Default output unchanged.
site/ (Astro 7, static, served at spoopyghosty0.github.io/frameport/) takes the Portal look of the UI refresh:
- Hero: a catalog game crosses the logo's tilted portal, from an APK on the PC's (blue) side to a game in the
Steam library on the Frame's (orange) side; reduced motion holds it halfway, like the logo.
- How it works as one real recipe's install log (PC stages blue, Frame stages orange), the showcase tour and
screenshots (synced from docs/ at build time, never by hand), field notes on what doesn't work, install steps,
credits.
- Games board from catalog/games: prebuilt at build time, then refreshed in the browser from main (one contents
API call, only changed files fetched, 6 h localStorage cache); any failure keeps the built list.
- /install/?manifest=…|?url=…: where an "Install with FramePort" button lands; opens frameport://install, and if
FramePort didn't take it, says how to get it (download for this OS, try again, copy the link). Link rules mirror
deeplink.check_url; node tests cover them and the board's rows.
.github/workflows/pages.yml builds and deploys on main (Settings → Pages → Source: GitHub Actions, once).
- Screenshots tab: Copy image (a button on the card under the pointer, the right-click menu and the viewer) puts
the full-size screenshot on this PC's clipboard (core/clipboard.py: Windows/WSL PowerShell bitmap + file,
macOS osascript, Linux wl-copy/xclip; Flet's set_image in web mode)
- Clicking a holiday badge showers the window: New Year confetti, winter snow, Valentine hearts, digits of pi,
clovers, hopping eggs, bouncing pumpkins (moved like the confetti: one page update per phase)
- Perfect pacing after 2.5 minutes on target; the Perfect pacing pill and line stay until the rate slips
- Full charge: only the ring pulses (with a glow behind it), the percentage stays put
- Upload hop a little slower
- Seven logo clicks: the glow, rings and the tossed cover come out of the wordmark's portal (between Frame and Port)
- Holiday badges dance on hover again: the logo's box grows to hold the badge on holidays (Flutter only hit-tests
inside a control's bounds); spins grow while they turn, bigger wobble and hop
- Perfect pacing: the game card glows and pulses blue/orange on an opaque card, the number grows in the portal
gradient, a Perfect pacing pill
- The logo's spin (searching for FramePort) is slower
- Hello: a headset peeks up from the window's corner and waves, outside the typing box
- Full charge: the battery ring pulses instead of sparkling
- Upload hop: a little lower and quicker, after 2.5 minutes instead of 5
- The fps mood tooltip opens above the number, clear of the pointer
- Seven logo clicks: the portal glows and rings, a cover is tossed out and falls across the window on a random arc
- Holiday badges dance on hover; new: Valentine's, Pi Day, St Patrick's, Easter weekend, April 1 (upside-down
logo until hovered), New Year's party popper
- Monitor: a minute within 0.5 fps of target turns the fps chart into the portal gradient
- Library search "frameport": the logo spins and says "That's me!"
- Type on Frame: typing "hello" makes a headset wave (keys still go to the Frame)
- The battery ring sparkles on reaching 100 % on the charger
- Uploads over five minutes: the transit cover hops now and then
- Live view tab: a blinking ON AIR sign while streaming
- Showcase hooks perfect_pacing, battery, long_upload, press_keys
Adapter rebuilt here; the codec plugin rebuilt here with native/hevc/build.py (NDK r27c, Lepton SoftOMX fingerprint 456e912c) is byte-identical to the contributed one (c1c2a73e). Agent version 70 -> 69 (main was at 68).
- ui/easter.py: seven quick clicks on the sidebar logo send a game's cover out of its portal for a somersault over
the wordmark; the Monitor's frame rate has a mood tooltip; holiday badges on the logo (a pumpkin Oct 24-31, a
snowflake Dec 20 - Jan 2); install milestones (confetti in the portal colours and a message at the 1st, 10th and
100th different game on the Frame). Milestones show once ever: they count different games (updates and
reinstalls don't), are stored as shown before they're shown, and the first use seeds from the games already on a
Frame (no "first game" after an app update). Off with setting ui.easter_eggs; Reduce motion keeps the words only.
- C.kv puts control values on the left; C.link (no indent) for the About page's source link.
- Showcase: the demo library has the easter eggs off; steps hooks easter_eggs / fps_dip and a clicks action;
record_video.py takes a storyboard file path (demos outside docs/).
- The install tutorial (app screen and card) shows curl -fsS <your-PC-address>:8765/<one-time-code> | bash, so
nobody takes the example for their own command; the card says FramePort fills them in.
- Videos: opening the Monitor tab no longer replays two minutes of samples (its charts raced to catch up); the
charts start there and grow live, as in the app. The pretend frame rate holds ~72 fps with a short, shallow dip
now and then (it sat at 55-61 fps for seconds). Both videos re-recorded.
Mesa enforces OVR_multiview's rule that a draw's program declares as many views as the draw framebuffer has and drops the draw silently; Doom3Quest compiles every vertex shader with layout(num_views=2) and draws its HUD/PDA into 2D-texture FBOs, which stay black on the Frame.
native/glmv (libfpglmv.so, same length as libGLESv3.so): the engine library's dlopen string is rewritten to it and it becomes the first DT_NEEDED. It records stage sources at link time and, when a multiview program draws into a framebuffer without views, draws with a lazily built single-view twin (num_views layout blanked, gl_ViewID_OVR -> 0u; attribute locations, block bindings and uniform values copied), then rebinds the original. Opt-in and experimental (analysis gl_multiview_libs, ANALYSIS_VERSION 6), setting gl_mv_debug, triage gl-multiview-twin-failed.
Host tests: the rewriter on Doom3Quest's 19 shaders (GPL-3.0 fixtures) and glmv.c against a stand-in GL that applies Mesa's rule. Untested on the device.
- record_video.py replaces record_tour.py: one storyboard per video with its output, a start state (demo or
fresh profile, Frame connected or not, start page, live or frozen stream), setup steps before filming, filmed
scenes and instruction cards (eyebrow, heading, numbered steps, a command, a note) for what happens outside
FramePort. --changed-since records the videos whose storyboard (or the recorder) changed; several videos record
in separate processes.
- videos/install.yaml: download, first start, the welcome screen's tool download, the setup command, the command
on the Frame (card), connected, scanning a folder, installing and playing a game (81 s).
- demo_home profile "fresh": FramePort's first start (empty library, welcome screen, nothing on the Frame); its
games wait for the pretend folder scan. Fakes for a first start: no Frame discovery on the real network, the setup
command shows the docs' example address, a pretend tool download, steps hooks first_run and pairing_done.
- CI records changed (or named) videos; releases attach every docs/media/frameport-<name>.mp4 as
FramePort-<name>.mp4. INSTALL.md and README link the tutorial; SHOWCASE.md documents the storyboard format.
- Cards are opened by their title in both videos (a card's middle is its Install button).
Klownicle's five fixes for Vader Immortal: Episode I, reimplemented as FramePort patches (found by Klownicle,
GitHub #49; their prebuilt APK is not used):
- frame.unreal_quest_precompile: UVRUtils::GetQuestShaderPrecompilePercent returned 0.0 on its non-Quest branch, so
the menu waited forever on the loading card; that branch now returns 1.0. Located by symbol, every instruction
around it checked (bl IsRunningOnSantaCruz; tbz w0,#0; fmov s0,wzr; ldp; ret); other builds stay untouched.
- frame.unreal_quest_keymap: the RPOC key selector (shared by AddAxisMapping and AddActionMapping, so both mapping
kinds were affected) picked the empty Gear VR key set for an Oculus HMD; the tbz to it becomes a nop. Located as
the common callee of both functions, pattern-checked.
- frame.zink_shader_fix + native/zinkfix (libVkLayer_fp_shaderfix.so): a Vulkan layer under Zink for GLES games
that applies zink_shader_fix entries (vk_shader_fix format) to the SPIR-V Zink generates; it adds itself to
GraphicsEnv's debug layer list from a constructor (the engine library loads it first). zink_shader_dump=1
captures modules. Vader's recipe carries the two lightspeed-shader fixes (12 OpStores each).
- adapter proximity_emul (FrameBridge): OVRPlugin's thumb/index proximity actions get bindings to the capacitive
touch inputs when the runtime lacks XR_FB_touch_controller_proximity (OVRPort offers the extension anyway):
generic replacement for the libUE4 ThumbUp patch.
- Vader's recipe: pose_time_fix + proximity_emul, status unknown (to test in the headset), min_app 0.12.1.
Analysis records unreal_quest_gates (ANALYSIS_VERSION 4). Star Wars: Tales from the Galaxy's Edge (same studio)
has neither gate (different engine build) and gets a catalog entry with pose_time_fix + proximity_emul.
Headless on the dev Frame (Lepton 3.0.5): the layer loads into Zink's instances, the proximity bindings are
accepted, and the game passes the loading card to the "guardian smaller than recommended, press any button" screen.
Newer Vivox builds (Green Hell VR) call AudioManager communication-device methods (API 31) from com.vivox.sdk.AudioChangeListener without a version check; Lepton is Android 11 -> NoSuchMethodError. The methods that call them now return at once (in-place dex edit, Dex.return_early). Detected by analysis vivox_api31 (ANALYSIS_VERSION 4), triage vivox-api31. Verified headless: Green Hell starts, Vivox initialises, ~65-70 fps.
Budget Cuts Ultimate asks for a 2048x2048 cube swapchain (faces=6); the Frame's runtime has no cube layers and refuses it (-2), OVRPlugin carries on with no images and crashes in ovrp_EndFrame4 (memset). cube_standin (default on, GLES) serves it as a GL cube map in the game's context and drops its layers. Triage cube-swapchain-refused (supersedes unity-render-crash/native-crash). Verified headless: the game runs on at ~70 fps.
- Library: an "All games" label and a 2 px rule (blue→orange in Portal themes) between the shelf and the grid,
hidden with the shelf.
- The pretend Frame's screenshots are the games' own in-game store screenshots (never cover art), installed games
first; the running demo game is BONELAB (it has screenshots, so Take screenshot adds a real one).
- render_docs: a shot whose steps fail is retried in a fresh window and never written (a window that didn't connect
had produced an empty Library); every shot is rendered twice in fresh windows and kept only when both agree (a
misdrawn glyph, "7.θ W", slipped through once); changes from 0.04 % of the pixels count (the sidebar card
showing another game is 0.12 %, run-to-run noise under 0.007 %). --fast renders once.
- record_tour: SHOWCASE_DEBUG=1 prints each step's start time. Docs images and the tour re-rendered.
Flet packs a patch by iterating each control's _values dict; Prop.__set__ adds/removes keys there without a lock.
A property set on a background thread (the live Frame card's sample, job progress, the library loader) while the
event loop packed a patch raised "dictionary changed size during iteration" and the update was lost (seen in CI:
a sidebar click left the old page showing). serialize_flet_updates() now makes property writes take the same
re-entrant lock as patches (app.FLET_LOCK). Reproduced with Flet's own encoder: 16 failures in 4 s before, none
after; test_property_writes_wait_for_a_patch_being_packed. The showcase server and ui_smoke serialize like the app.
Tour re-recorded with the fix (clean, no fallback clicks).
.github/workflows/showcase.yml renders the docs screenshots on UI pushes to main (and the tour when its storyboard or
scripts change, or on Run workflow), keeps every render as an artifact and opens/updates the PR showcase/update
when a picture visibly changed. Releases attach the tour as FramePort-tour.mp4. docs/SHOWCASE.md explains running
it, the step language and the CI flow; README opens with the teaser (link to the full MP4). Renders refuse
placeholder art (--allow-missing-art). tests/test_showcase.py: demo library, privacy scan, image threshold,
manifests (every docs image has a shot), step validation, element picking, pointer paths, ffmpeg graphs.
scripts/demo_record.py is replaced by the tour.
One window on the demo library, driven by name like a person would (drawn pointer, eased curved paths, a ring on
each click), filmed with Chrome's screencast (1080p, constant 30 fps from the frame timestamps), then captioned
(lower thirds in the app's colours), given title/end cards and crossfaded by postprod.py (ffmpeg only). Writes
docs/media/frameport-tour.mp4 (+ poster, best quality within 12 MB) and the README teaser docs/images/tour-teaser.webp.
Installs in the tour run a scripted job through the real queue; --draft for quick storyboard checks, --names lists
the clickable names. Element finding prefers the innermost match (a list's text includes its rows').
scripts/showcase/: the fakes split out of ui_smoke (the pretend Frame now reads the demo library's state, fixed
dates, a Take screenshot fake, a frozen monitor stream for stills), web.py (the GUI in web mode driven by name
through Flutter's semantics tree, drawn cursor, eased pointer paths, settle detection, one browser per window),
steps.py (the step language shared by screenshots and the tour), demo_home.py (21 catalog games from
docs/showcase/demo-library.yaml + demo-analyses.json, art and store details fetched once and cached) and
render_docs.py (docs/showcase/shots.yaml -> docs/images, rewritten only on a visible change; --check for CI).
BattleSisters' hands lagged behind the controllers (also with ovrp_hold_physics on or off). pose_debug=1 (new,
FrameBridge: per 5 s and per located space, the requested time minus the predicted display time) showed on the dev
Frame (SteamOS 0.4.5): XrTime runs 2.56 s ahead of CLOCK_MONOTONIC, the hand spaces were located at -2564 ms (the
monotonic "now" passed on as an XrTime: OVRPort's dispatcher converts XR_KHR_convert_timespec_time 1:1 and
FrameBridge's emulation is never asked) and the head at XrTime 0.1 s (~1450 xrLocateViews/xrLocateSpace per 5 s).
pose_time_fix (default off; suggested for Unity built-in OVRPlugin games): in xrLocateSpace(s)/xrLocateViews a time
nearer the monotonic clock than XrTime's "now" is moved by the offset measured at xrWaitFrame, one more than 0.5 s
before the display time goes to "now". Headless with it on: every far-past request moved, located times -9.8..0 ms
from the display time. Host unit test for the time rules; PLAYBOOK row.
frame.slz_vulkan_hooks: Stress Level Zero's plugin no longer intercepts Unity's Vulkan start-up and samplers (it called an invalid function right after OVRPlugin's pre-init instance was destroyed). Test fixture rebuilt by us, byte-identical. Owner's headset test: BONELAB 1.2974 plays well.
Closes#82
# Conflicts:
# docs/GAMES.md
# tests/test_patches.py
# tests/test_triage.py
ui/live_players.py: embedded_available (win/mac with flet_video; Linux only with Flet's full client + libmpv), find_mpv, order (pick first, browser last), low-latency mpv properties, MpvWindow (fails over when mpv quits at once). flet-video==1.0.2 only off Linux (its Linux plugin links libmpv.so.1: the bundle wouldn't start without it). Relay unchanged: native players read /stream.mp4 (checked with ffprobe/ffmpeg, from the start and mid-stream).
C.CoverButton (grid + shelf), library.card_hover/hover_motion/scrim, game page Play shows Starting on … with a spinner; glyphs.solid + frame-solid.svg for primary buttons; reduce motion skips lift/zoom/rings. ui_smoke: card hover, button hover and launch frames.
Main's microSD drives (agent v63), Linux app icons (agent v64), OBB detection, re-analysis and catalog entries,
on top of the UI refresh. Our monitor modules ({"modules": [...]}) move to agent v65 (MIN_AGENT_MODULES = 65).
Main's new UI uses the refreshed components: "Move to…" is in the game page's sectioned menu (MenuState.movable),
the .obb question and the Move dialog use C.dialog, the Frame page's drive picker C.dropdown, line-style icons.
The portal is drawn as two layers around the cover (portal_back: shadow, hole, PC half; portal_front: Frame half), arcs of one ellipse in a shared viewBox. The track is taller than the cover so the ring shows above and below it. Shadow faked with stacked translucent outlines (flutter_svg has no filters). TRANSIT_REV 2.
analysis/unity_split.py: an XR-plugin build (Oculus XR Plugin / Unity OpenXR library) without assets/bin/Data/UnitySubsystems/ in the APK (zip names only), or BuildSettings listing more scenes than the APK has levelN files (globalgamemanagers loose, or its node read from the head of data.unity3d: only the blocks up to it). Exact on the 48 Unity APKs of both dump folders: all 13 split builds flagged, none of the 17 full builds (whose OBBs are asset bundles or sound banks). The missing-OBB warning and launch-test finding now cover them; existing entries are re-analysed at the next start.
quest_dump.find_data: after the folder-layout checks, search the APK's folder, its parent and up to 3 levels below each (folders with their own APKs are other games) for the package's expansion files; the folder with the APK's own versionCode wins, per kind the newest file not newer than it, else any version. When that folder holds other things too (the APK, other games' OBBs), the entry gets data_files and only those files are uploaded, counted and deleted with the game; no language-pack/content-file lookup there. Both dump folders scan identically (62/47 games).
The agent copies an AppImage's .DirIcon / the bundled .desktop file's Icon= (hicolor, pixmaps; symlinks resolved
and kept inside the app folder) to <anchor>/artwork/app-icon.{png,svg} at finalize_linux and when menu entries are
refreshed, and uses it for the menu entry's Icon= and the Steam shortcut (PNG only) unless the user chose an icon
(artwork/.icon-source = custom, sent by the PC with every art upload). StartupWMClass comes from the app's .desktop
file. A PNG goes back to the PC and becomes the library icon when there is no pick or store icon (no .picked;
.app-icon marker); folder apps get it at add time.
Closes#99
- transit.position(): Analyze/Patch/Sign bring the cover up to the portal (fixed at PORTAL_AT = 0.5), Upload carries it across under the portal (drawn on top), Install/Test on to the headset; steps row weighted so Upload sits under the portal
- menus.quick_menu: Play · Open game page · Select · Install/Update · Game settings… · More actions… · Uninstall · Remove; job: Show progress · Cancel · Open game page
- More actions… opens the game page and its full '…' menu (a ContextMenu around the button, opened from code: app.open_game_menu)
- tests for the position mapping and the short menu; help text and CLAUDE.md updated
detect.ANALYSIS_VERSION (stored as analysis.extra.analysis_version, bumped
whenever analyze() gains a field): Quest/Android entries below it whose APK
still exists are analysed again in a background thread at the GUI's start
and before a build (pipeline.refresh_analyses). Only analysis and suggested
change; recipes the user didn't edit follow the new suggestion (e.g. an SDL
app gets frame.sdl_clipboard once sdl_java exists), user recipes, tags, art,
titles and builds stay. An unreadable APK keeps its entry and is marked
analysis_failed (not retried until the next bump); a missing one is tried at
a later start. Analyze again sets the version too. Rift/Linux entries skipped.
PLAYBOOK row + CLAUDE.md note.
- One Playwright context per clip (record_video), web mode with ui_smoke's fake Frame; MP4 (x264) + poster JPG via ffmpeg, blank start trimmed
- ui_smoke: install_fakes()/attach_fake_frame() factored out so the recorder reuses them (behaviour unchanged)
- driver/shooter hand-off: the driver runs a step, signals ready, then waits (240 s max) for the shooter's screenshot + mouse actions before the next step; fixed STEP_SECONDS and the compensating sleeps (library-typed/-cleared, --hover, --gestures, --links) removed
- new step library-shelf-hover (the shelf's first card hovered: its Play button); hover positions per step
- mouse actions that save their own picture (menus) skip the duplicate -mouse shot; the -mouse shot waits the paint delay (typed search showed half-faded results)
- --links keeps the 1440x900 Add games click; --gestures positions updated for the shelf, fake screenshots keep the same day layout at any hour
- C.checklist/C.Check replace status_row: Frame 'Ready to play' (Install Lepton, Install Proton, Test, Restart the Frame when kernel keys run high), Settings Tools (Install per missing tool) and This PC
- Views fade in (150 ms AnimatedSwitcher, same-route redraws swap in place); the wordmark portal pulses once on connect; Settings > Appearance 'Reduce motion' (ui.reduce_motion) turns both off
- Settings: fixed index column (Appearance first, Remove FramePort last) that scrolls to sections; ui_smoke step settings-index
- Tests: checklist items, section order, reduce-motion default
- Library: 'On your Frame' row above the grid (installed/outdated games on the connected Frame, most recently used first, max 8, wide covers, Update ready pill, Play on hover, click opens, right-click = the game menu); hidden while searching/filtering, in select mode or without a Frame; cards reused, updated with the grid
- Game page: cover tint (thumbs.compute_tint: Pillow quantize, most common colourful entry, clamped to lightness 0.35-0.55 / saturation <= 0.55, cached as t_tint_<sha8>.json next to the thumbnails, computed in prewarm or in the background) as a glow around/inside the hero and a faint wash at the top of the page
- C.empty_state: the transit portal + the context icon on a soft glow (C.portal_scene) for every empty state
- Tests: shelf selection, tint helpers, compute_tint cache; radius-token test ignores RadialGradient fractions
- C.quiet/C.reveal: row/tile actions + checkboxes at opacity 0 until hover, keyboard focus or selection (space kept)
- Files rows: checkbox shows on hover/focus/select mode, actions on hover/focus or when the row is selected; selected rows get C.selected_style
- Screenshots: checkbox on hover/focus or while anything is selected; selected tiles get a 2 px accent border + subtle fade; labelled "Select all"
- Library select mode: selected cards get the 2 px accent border + subtle fade (hover scale/shadow unchanged)
- selected_style(subtle=True) for overlays on pictures
- Live view: one help line + help icon, status/Quality/Start in one bar, portal + headset empty-state hint while not streaming
- Type on Frame: the repeated callout replaced by one line + help icon under the input
- Transit: Monotonic keeps the bar from moving back within a run (a new stage cleared the job's fraction); cover 1.4x larger and placed just before the portal; tests
- glyphs.transit_parts: the logo's monitor, portal and headset drawn whole (same paths/strokes), per theme colours, cached by TRANSIT_REV
- ui/transit.py: pure stage-name mapper (Analyze/Patch/Sign/Upload/Install/Test, overall fraction, waiting/failed, frame/pc) + tests
- components.Transit: created once, set() updates properties; cover rides into the portal at the progress head
- sidebar activity card (compact), game hero (updated from _on_job, no re-render), Activity running tile
- ui_smoke: a pretend running install (transit-game, transit-activity)
- app owns one MonitorHub; the Monitor tab subscribes (all modules) instead of owning a MonitorSession; the hub reconnects, _poll retries an error
- sidebar Frame card: battery ring (C.gauge), name + connection line; now-playing row (art, title, playing time, fps by level, 2-min sparkline) opens the Monitor
- card subscribes to games + battery every 5 s while connected, paused during uploads; setting ui.live_frame_card in Settings > Appearance
- ui/frame_card.py pure helpers + tests; ui_smoke injects FakeMonitorSession into the hub
The game page's "What FramePort will do" for a Linux app gets a Desktop Mode switch ("In the menu and on the
desktop", default on): kept in the library entry (desktop_entry; patches don't apply to Linux apps), passed to
finalize_linux at install and applied at once on the Frame through the agent's desktop_entry command when the app is
installed. The agent side (menu + desktop .desktop files, launcher with FRAMEPORT_DESKTOP=1, refresh for existing
installs, removal on uninstall/purge) came with agent v63. Help text desktop_entry, INSTALL/FRAME_RUNTIME/PLAYBOOK,
CLAUDE.md. Game Mode's Steam Input problem from the report is separate.
Closes#84
The Steam Frame page lists the Frame's drives (filesystem, free space, games on each; exFAT/NTFS cards say why they
can't hold games) and sets where new games go (library setting install.drive, default internal storage). Game menu
→ "Move to…" (Frame-installed games, agent v63) picks a drive in a dialog and queues a Frame job that follows the
agent's copy with progress (cancellable until the copy starts). The game page and the Frame page's installed list
show "on SD Card" / "SD Card not inserted"; a game whose card is out counts as installed, not "Not installed".
Help texts install_drive / move_game, ui_smoke --fake-frame drives + the Move dialog, docs (FRAME_RUNTIME "Where
FramePort keeps games", INSTALL, PLAYBOOK row, CLAUDE.md).
Closes#90
#90: `drives` lists internal storage, the drives under /run/media (from /proc/mounts) and the drives of Steam
library folders, with free space and whether they can hold games (vfat/exfat/ntfs can't: Lepton data and Proton
prefixes need Unix permissions and symlinks; read-only mounts neither). Games on a drive live in
<mount>/FramePort/<pkg>; the anchor stays internal, so the Steam shortcut never changes. prepare/prepare_pcvr/
prepare_linux take dest (free space from it); a drive that isn't mounted is an error, never a silent fallback to
internal storage, and an installed game keeps its folder. `move` (refused while the game runs, free-space check)
renames on the same drive, else copies with cp -a (in podman's user namespace when podman is there: container-owned
files), checks file count + bytes, retargets symlinks into the old folder (LibOVRRT redirect), points launch.sh at
the new folder (Quest: the app_dir line; Linux/PC VR: written again from the install record, which now keeps env and
game args) and rewrites deployment.json before removing the old copy; detached via systemd-run with a status file
(move_status). list_installed adds drive + drive_missing; launch refuses a game whose card is out; cleanup may remove
leftovers in a drive's FramePort folder (never an installed game); purge/uninstall remove an empty FramePort folder.
PC: install/drives.py (list, setting install.drive, move with progress, picks a running move up again), targets
pass dest for Quest/PC VR/Linux installs, CLI `frameport frame drives`, `frameport frame move <pkg> --to`,
`frameport install --dest`.
#84: finalize_linux writes ~/.local/share/applications/frameport-<slug>.desktop (+ an executable copy on ~/Desktop
when it exists; Exec quoted per the Desktop Entry spec, X-FramePort-Package marks ours) unless desktop_entry is off;
`desktop_entry` command switches it per app; ensure_host_fixes adds entries for existing Linux installs and drops
stale ones; uninstall/purge remove them. The Linux launcher with FRAMEPORT_DESKTOP=1 skips the Steam-parent
watchdog and Steam's display (upgrade_launchers updates existing launchers).
- Keys typed on the Library (no dialog open, search not focused) go into the search and focus it, cursor at the end; Backspace removes the last character; Esc in a non-empty search clears it
- Pure helpers library.typed_char / should_capture (tested); C.dialog_open reads Flet's page._dialogs (snack bars don't count)
- Search hint "Type to search games and tags"
- "Add a PC VR game folder…" is now "Add a PC game folder…" (it adds Windows games too)
- ui_smoke: library-typed step types "arc" after clicking the header
- ui/menus.py (no controls): menu_sections() builds a game's menu for the Library right-click and the game page's "…" (Header entries for Artwork/Recipe/Troubleshoot, destructive items last after a divider; the page leaves out what its hero and Where-it's-installed cards offer; Type on Frame left the game menu; "Run launch test on …"; Analyze again also on the page); process_menu() for Monitor (Copy first, End…/Force quit… with distinct icons, End game… last, disabled "Protected by SteamOS")
- C.menu_items: 32 px rows, small-caps headers (dropped when empty), ICON_S icons, disabled items without a handler; C.menu_button/C.check_item; menus get a BORDER_STRONG border + shadow (PopupMenuButton and theme popup_menu_theme for ContextMenus)
- Add games menu: new labels/icons, Rescan folders at the end (toolbar button kept); docs/help updated
- Icons whose ROUNDED variant is filled are OUTLINED again (Monitor nav, Sleep, file types, …); the consistency test checks an explicit line-style allow-list
- Library Tags chip: the tag icon no longer overlaps its label
- tests/test_menus.py; ui_smoke shoots the Add games and game page menus
The PCM conversion is preventive (Sniper Elite VR and Hyper Clinic send envelopes), and revision 3 would show
'Update on Frame' for every build with adapter.haptic_fix (suggested for every OVRPlugin game), including builds
where upstream.py already left the workaround out. Same reasoning as rect_clamp. New builds get the PCM conversion
anyway (the artifact is rebuilt).
- native/ovrpshim: libunity.so's ovrp_BeginFrame/ovrp_EndFrame go through the shim; the frame wait waits <= 50 ms
for the last waited frame to begin and skips otherwise (the game deadlocked at its Init scene when Unity skipped a
begin); a begin/end of another index while a wait is outstanding gets the waited index. The physics-step
ovrp_Update2 is held back (prediction 0 located the controllers in the past on the Frame: the hands lagged).
frame.unity_oculus_check revision 5.
- native/xrshim: PCM vibrations (XrHapticPcmVibrationFB) become one plain vibration too; haptic_fix revision 3.
- Catalog: works with frame.unity_oculus_check + haptic_fix, min_app 0.12.1. Triage unity-frame-not-begun (info),
PLAYBOOK rows and how to get all-thread backtraces with gdbserver64 inside the container, test.
Stress Level Zero's graphics plugin (libSLZQuestNative.so) hooks Unity's Vulkan start-up and vkCreateSampler; on
the Frame its vkCreateInstance wrapper calls an invalid pointer right after OVRPlugin's pre-init instance is
destroyed (pc 0, a jump into an unloaded library, or a hang). The new patch turns the plugin's two registrations into
no-ops (found through its exported functions, 4 bytes each), so Unity starts Vulkan itself; ~35 s of shader
prewarming without the plugin's pipeline cache, then 72 fps (headless). One BONELAB recipe serves 1.2068 and 1.2974.
Triage slz-vulkan-hook-crash, PLAYBOOK row, tests with a fixture built from tests/fixtures/src/fakeslz.S.
- updates.snooze()/hidden(): the update banner's "Not now" hides a version for 24 h (update.snoozed); "Skip this version" unchanged
- Frame page: "Switch Frame…" opens a picker of remembered Frames (+ "Find another Frame…"); separate Disconnect button
- Labels: Update Steam art on Frame, Reset to suggested recipe… (asks first; pipeline.reset_recipe without the duplicated Rift branch), Uninstall from this PC…, Change program…, Share working recipe…, Force quit/End game…, ellipsis on everything that opens a dialog/picker or asks
- One Developer Mode path (Settings → System → Enable Developer Mode / Settings → Developer → Pair new host); linux_app help points to FEX
- tr() for the remaining visible strings (install status, job stages, update dialog, settings, files); this PC, recipe, program, for example, 50%, US spelling, Steam IDs, arm64
- Long callouts (live view, Type on Frame, pairing, library empty state) shortened, details in help texts
- tests/test_ui_text.py: untranslated literals, "..."/"e.g.", vocabulary, Switch Frame not wired to disconnect; snooze expiry test
- agent: {"modules": [...]} control message, monitor_plan(); default = all (older clients unchanged); GPU busy needs the process scan
- frame/monitor_hub.py (no Flet): subscribers with modules + interval, one session for the union and the fastest interval, fan-out, pause, reconnect, filter/pause/kill/end_game pass-throughs
- MonitorSession.set_modules (agent >= 63); tests/test_monitor_hub.py
Each build probes OVRPort's output for registered upstream fixes and leaves out the workarounds they make
unnecessary (recipes unchanged: builds with an older runtime keep them). Logged ("not needed: ..."), recorded in
build.superseded, left out of settings.conf at install, shown on the game page and in `frameport show`;
FRAMEPORT_KEEP_WORKAROUNDS=1 turns it off. Registered: ovrport.haptic_envelope (-> adapter.haptic_fix) and
ovrport.microphone_stream (-> frame.ovr_microphone), both fixed in OVRPort runtime 3.4.3-aa54c3f (ovrport/app#73;
haptics verified in the headset with Lucky's Tale). Probes checked against both real runtimes; fixtures in
tests/fixtures/src/fakeruntime.S.
- Monitor: its colour maps (levels, process groups, CPU clusters, power split) refill on a theme change; restyle()
stops and drops the Monitor view like the other kept views
- Sparkline's default colour is read when it's built (it was captured at import)
- Portal themes: INFO is a cyan of its own (#5CD0E6); it equalled PC's blue, so the Monitor showed Steam and SteamVR
processes, and CPU and memory, in one colour
- Translation template regenerated after the rebase
- Dual themes: "Frame" (accent), a small tilted portal (rim from the accent into SECONDARY around a dark hole,
generated in the active theme's colours, also for installed themes: glyphs.portal_mark), "Port" (SECONDARY)
- Glyphs: stroke 2 (was 1.75, lighter than Material's icons); menu items tint them TEXT like Material's own icons
- ui_smoke: waits until the web server listens (a fixed 6 s failed with a second smoke run on the machine)
- Built-ins: Portal (default), Portal (OLED) (true black) and Original (the former violet; "classic" still maps to it)
- Portal now uses both of the logo's portals: orange stays the main action and selection; the new SECONDARY token
(blue) colours outlined buttons, progress bars and switch tracks; "dual" themes add the blue-to-orange sidebar
edge, the two-colour wordmark and the selected tab's fade. Original looks exactly as before
- Theme files: <data>/themes/*.json (name, base, dual, any subset of the colour tokens), checked on install (dark
background, readable text, known colours; T.ThemeError says why). Settings -> Appearance: "Install theme file...",
"Copy this theme as a file" (a template), a bin icon removes an installed theme
- docs/THEMES.md + docs/themes/example-theme.json (kept valid by a test); ui_smoke --themes includes installed themes
- Logo (a monitor that goes through a tilted portal and comes out as the Steam Frame) in the sidebar and welcome
screen; src/assets/icon.png is the bundles' app icon (flet build; PyInstaller fallback via --icon)
- 24 px line glyphs (ui/icons/glyphs, ui/glyphs.py) replace Material icons for FramePort's own concepts: Frame,
launch test, PC, live view, screenshots, Type on Frame, verified recipe, rebuild; shown as tinted images through
C.as_icon and the button/menu helpers (same size as the Material icons next to them)
- Colour themes, dark only: "portal" (default; orange accent, blue PC side, status colours chosen so warnings never
read as the accent) and "classic" (the previous violet). Settings -> Appearance theme cards switch live:
app.restyle() rebuilds the shell and drops cached views (setting ui.theme)
- Theme colours are read when building: default arguments no longer capture tokens, module-level colour maps refill
through T.on_change; tests/test_theme.py checks both
- ui_smoke.py --themes renders the picker and every theme after a live switch
Owner's headset test (720p): heavy compression artifacts and many dropped-looking frames.
- Frames stamped on arrival (wall clock) bunched when ffmpeg read several at once (gaps of 0-10 ms and 45+ ms). The
input stays on the wall clock (read in step with pulse's audio; setts alone held output ~7 s), and setts now
numbers the output frames on fp_venc's fps grid: every gap exactly 1/fps on the Frame, audio aligned.
- fp_venc --peak: VBR capped at the peak (else CBR as before), level picked for the peak. The hardware path uses
1.5x peaks and higher targets (360p 1.5, 480p 2.5, 720p 5, 1080p 8, Full 10 Mbit/s); 3 Mbit/s CBR blurred every
head turn. The x264 fallback keeps its rates.
- fp_venc's info/stats lines go to the app log (late/skipped frames next time); its errors still explain a stop.
Verified on the Frame: probe with VBR (no refused control); end to end through livestream.start at 720p32: 403
frames all 31 ms apart, audio 0-12.57 s next to video 0-12.58 s, late viewer on its keyframe at once, nothing left
after stop. Picture quality with motion still needs the headset.
The box boxes repeat every 3 source pixels at these ratios, so the averages become rounding shifts (3:2: block
sizes 1, 2, 4) or an exact multiply (3:1: x7282 >> 16 = /9 for every sum), with no per-pixel scalar loop. Same
bytes as the generic path; 480p (852 px wide, irregular) keeps the generic path. Self-test adds 1158x648 -> 432/216
(columns left over after the 48-pixel steps) and times all four qualities.
Frame (2026-10-07): selftest ok (184 cases); 1920x1080 -> 720: 1.3-1.65 ms (was 5.6), -> 360: 0.7 ms,
-> 1080: 0.6-1.0 ms, -> 480: 2.8 ms.
- fp_venc: accept the source's buffer count (the Frame's v4l2loopback has max_buffers=2; asking for 3 failed the
probe); OUTPUT buffers remember which picture they hold, so repeats (standby, still scenes) skip the conversion
(720p: 35% -> 2.5% of a core with the headset asleep).
- Pipeline: raw H.264 stamped on arrival (-use_wallclock_as_timestamps, same clock as pulse) with a 32-byte probe:
-framerate was ignored, -fflags nobuffer lost the first seconds, frames numbered from 0 held all output ~7 s next
to the sound. frag_keyframe so a requested keyframe starts a fragment (a joining viewer starts there).
Verified on the Frame (headset asleep): selftest ok (104 cases), probe at 360p-1080p, end to end through
livestream.start: 720p36 + AAC in 0.1 s fragments, audio and video spans match, a second viewer starts on its
requested keyframe at once, nothing left running after stop; FP_VENC_DISABLE=1 falls back to x264.
native/venc/fp_venc: own clean-room driver of the Frame's iris encoder (V4L2 stateful encoder interface, written from
native/venc/SPEC.md = kernel docs + values measured on the Frame). Reads SteamVR's headset-view webcam, box-scales and
converts RGB24 to NV12 (NEON, bit-identical scalar reference), CBR H.264 with SPS/PPS on every IDR, one frame per slot
of an even fraction of the panel rate read through DRM (96 Hz -> 32 fps). stdin "k" = keyframe, EOF = stop;
--probe/--selftest. Static freestanding aarch64 binary in artifacts/linux-arm64-bin (reproducible).
livestream: the script probes fp_venc and pipes it into ffmpeg (-c:v copy + AAC), else the old x264 30 fps path; the
helper is synced to ~/.local/share/frameport/bin by sha256 at stream start (no agent change); a new viewer asks for a
keyframe and waits for it; the status line shows the encoder and fps. Tests: hardware/fallback script branches,
keyframe-on-join, helper sync; tests/test_venc.py compares convert.c with a Python reference (native marker).
Not yet run on the device.
- deeplink.py: framedrop:// and frameport:// links and the pasted https://framedropvr.com/install?manifest=|url= link; manifest framedrop.install/v1; https only (http on loopback), no credentials, no LAN addresses (also after DNS and redirects), sha256 checked, cancel/mismatch leave no .part
- urlhandler.py: per-scheme registration (Settings → Install links, links.framedrop / links.frameport, default on; another program's scheme only taken on request) through a handler script that queues the link and starts FramePort (a flet build bundle can't take a URL argument); the GUI's heartbeat + link inbox
- GUI: Add games → Install from a link… and Add a Windows program (.exe)…; confirmation before any download; files dropped on the Library (packaged app); CLI frameport open-link
- patch device.display_mode (Automatic / VR / Flat window), verified on the Frame with 4XVR
- x86_64 Linux apps run through FEX (agent v61: FEX installed unattended, STEAM_COMPAT_DATA_PATH set, RootFS from SteamOS's /usr/share/guestos/fex-mesa); verified on the Frame with an x86_64 test program; triage linux-x86-no-fex
- Sound: the default output's pulse monitor (what the headset plays) as AAC in the same fMP4; the
player starts muted (browser autoplay rules) with a Sound on button. Video timestamps go to the
wall clock (-ts mono2abs) instead of forcing it on the pulse input, which gave bursts of AAC packets
one shared timestamp; aresample=async=1 keeps the sound continuous.
- Late viewers start at a keyframe of the video track (audio samples are all sync).
- Qualities 360p/480p/720p/1080p scale down only; 'full' sends SteamVR's headset view at its own
size (1920x1080 today; v4l2cam has no size option, so 2K/4K would only upscale).
- Player keeps a 0.3 s cushion and catches up at 1.1x; it seeks only when >2 s behind (seeking to the
very edge starved playback).
Source: SteamVR's built-in v4l2cam headset view (steamvr-v4l2cam.service -> v4l2loopback 'SteamVR'),
encoded with x264 on the Frame (fps=30 before scaling, nice 10, 3 threads) as fragmented MP4 over an
SSH exec channel; ffmpeg stops when the channel closes. A relay on 127.0.0.1 keeps the init segment and
the fragments since the last keyframe for late viewers and serves an MSE player page, opened in the
default browser (Flet can't show video outside flet build bundles). Verified on the dev Frame: 30 fps
in Edge, ~0.1 s behind the newest frame, 0.34 core at 720p with a quiet picture.
Agent v45: list_screenshots (screenshots.vdf + folders, every account; the Frame files headset shots under SteamVR
250820, so launch.sh now logs start/end to <anchor>/plays.log and upgrade_launchers adds it to existing launchers) and
delete_screenshots (only images in userdata/<id>/760/remote/<appid>/screenshots, links refused, vdf left to Steam).
PC: install/screenshots.py (thumbnail/full-image cache under screenshots-cache/<frame>, cancellable download).
GUI: Screenshots nav item (grid by day, game filter, viewer with prev/next, multi-select download/delete), game menu
entry; ui_smoke --fake-frame sample shots.
base, dual, any subset of `T.TOKENS`; refused if light/unreadable, `T.ThemeError`), Settings → Appearance: cards
switch live via `app.restyle()` (rebuilds the shell, drops cached views; setting `ui.theme`), "Install theme
file…", "Copy this theme as a file", bin icon removes. Read tokens as `T.NAME` when building — never as a default argument or module-level constant (they
keep the import-time theme; module maps refill through `T.on_change`, `tests/test_theme.py` checks defaults)),
`glyphs.py` + `icons/` (the logo `logo.svg`/`logo-solid.svg` = a monitor that comes out of a tilted portal as the
Frame, and 24 px line glyphs `fp:frame|port|patch|container|test|pc|sync|live|shot|keys|recipe|link`, copied into
the assets dir and shown as tinted `ft.Image`s: pass `G.FRAME` … wherever an icon goes, `C.as_icon` / the button
helpers handle both kinds; `src/assets/icon.png` = the bundles' app icon), `components.py` (pill, card, callout,
checklist, art_fill, confirm, `update()` = safe update: in Flet 1.0 reading `.page` of an unmounted control
raises), `jobs.py` (background FIFO job queue, one at a time, cancel via Reporter; no Flet), `views/`
(library: search/filters/tags/sort as pure tested helpers; game: hero + one-click install, patches under
"Customize"; frame: device + readiness + installed, or connect wizard; files: the Frame's file manager (persistent
@@ -21,8 +34,73 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
the "Send files" dialog, game menu → "Add videos & files…" = `go("files", pkg)`; multi-select bar (download/
delete); drag-and-drop from the OS via the `flet-dropzone` extension (Apache-2.0, Flutter `desktop_drop`), which
only a `flet build` bundle contains: `files.dropzone_available()` keeps it out of source runs and the PyInstaller
fallback, which would show an unknown control); settings; welcome; activity panel).
fallback, which would show an unknown control); screenshots (Steam screenshots on the Frame, `install/screenshots.py`
+ agent v46 `list_screenshots`/`delete_screenshots`: the Frame files every headset shot under SteamVR 250820, so
bitmap + file via %TEMP%, macOS osascript PNG, Linux wl-copy/xclip; Flet's set_image only in web mode)); live view (`views/live.py` + `install/livestream.py`: the Frame's built-in SteamVR "headset view" webcam
(`steamvr-v4l2cam.service` → v4l2loopback "SteamVR" /dev/video99, see docs/FRAME_RUNTIME.md) + the default
output's pulse monitor (sound) → `fp_venc` (`native/venc`, own clean-room V4L2 driver of the Frame's iris
hardware encoder: RGB24→NV12 box downscale with NEON, H.264 CBR, one frame per slot of an even fraction of the
heart, Pi Day, St Patrick's clover, Easter Sat-Mon egg (computus), April 1 = the logo upside down until hovered,
Halloween pumpkin, Dec 31-Jan 1 party popper, else Dec 20-Jan 2 snowflake; on those days the logo's box grows to
hold the badge: Flutter only hit-tests inside a control's bounds; `FRAMEPORT_TODAY` pretends a date),
Library search "frameport" (logo spins, "That's me!"), Type on Frame "hello" (keys still go to the Frame; a
headset peeks up from the window's corner and waves), the battery ring (only the ring, with a glow behind
it; not the percentage) empties at once and spins while its bar refills, then pulses, on reaching 100 % plugged (`charged_now`, `ring_pulse`, `ring_glow`), a long upload (>2.5 min, `HOP_AFTER`) makes the transit cover hop, the Live view
message at the 1st/10th/100th *different* game: settings `fun.installed` = game ids, `fun.milestones` = shown;
each milestone shows once ever, recorded before it's shown; updates/reinstalls never count; the first use seeds
from games already on a Frame and marks passed milestones shown). Setting `ui.easter_eggs` (no UI) turns them
off; the showcase demo library has them off (steps hook `easter_eggs` for egg demos). Reduce motion: no animation.
**Performance rules** (the app froze before): never put image bytes in controls — artwork is served by URL from the
GUI assets dir (= user data dir; `ft.run(assets_dir=…)`), as thumbnails (`artwork/thumbs.py`, Pillow); the
library view is persistent, streams cards in batches from a background thread and filters by toggling visibility;
@@ -30,16 +108,47 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
**Never recreate clickable controls on progress ticks** (sidebar, activity tiles): update their properties —
replacing them 5×/s swallowed clicks (couldn't leave the Library during an upload).
Labelled switches: `C.switch(label, …)` (Material's default label colour is dark on our dark theme).
Cover cards (Library grid + shelf): `library.card_hover`/`hover_motion` (lift, art zoom inside the clipped frame,
radial `scrim`, accent-tinted shadow) and `C.CoverButton` (frosted round button, accent under the pointer; Play =
blue then orange ring ripple + "Starting on Frame…" pill for STARTING_S; its `.status` layer must sit *below*
the button in the Stack, else it takes the clicks); the game page's Play turns into "Starting on …" with a spinner
(`GameView._starting`). Reduce motion: no lift/zoom/rings. Filled buttons use a glyph's `-solid` variant
(`glyphs.solid`, e.g. `frame-solid.svg`: the outline glyph faded into the orange).
Empty states (`C.empty_state(..., features=[(icon, heading, sentence)])`): with features the portal is bigger, a
soft portal light (`C.portal_glow`) fills the screen and `C.feature_row` says what the screen will show (the
not-connected Files/Screenshots/Live/Type/Monitor tabs and the empty Library); the idle Live view is a framed
"screen" with its own Start button + `live_features()`, Type on Frame shows `keyboard_tips()` under the box.
Setup checklists (Frame → Ready to play, Settings → Tools / This PC) = `C.checklist([C.Check(ok, title, detail,
help, fix=(label, icon, handler), extra=control)])`: ok True/False/"warn"/None (= spinner); the fix button shows
inline only while an item isn't ready — wire existing actions only. Motion: `app.body` holds an
`ft.AnimatedSwitcher` (`app._show_view`): a new route gets a new wrapper (150 ms fade), a same-route redraw swaps
the wrapper's content (no animation; persistent views just remount); the wordmark's portal (`wordmark().data`)
pulses once when frame_state turns "connected"; both off with setting `ui.reduce_motion` (Settings → Appearance
"Reduce motion", `app.reduce_motion`). Settings has a fixed index column (`settings.SECTIONS` order: most users'
needs first (Updates, which also holds game recipe + install-link updates, Installing, Library folders,
Appearance), niche ones later (Install links, Tools, This PC), Remove FramePort last): entries scroll the section column via `scroll_to(scroll_key=…)` (sections wrapped
in Containers with `ft.ScrollKey`), the header stays; `app.settings_view.show_section(key)` (ui_smoke
`settings-index`).
Help hints: wording for non-obvious terms lives in `ui/help.py` (`HELP`); show it with `C.help_icon(key)` or the
`help=` argument of `section`/`status_row`/`kv`, tooltips via `C.tip()` (wraps). Game actions for the Library
right-click menu (one `ft.ContextMenu` around the grid, filled on right-click) and the game page's "…" menu come
from `app.game_actions()`. Picking art (`sources.apply_choice`) downloads into a staging dir and keeps the old
`help=` argument of `section`/`kv` (`C.Check` help key), tooltips via `C.tip()` (wraps). Game actions for the Library
right-click menu (one `ft.ContextMenu` around the grid, filled on right-click; short: `menus.quick_menu`, key actions
+ "More actions…" = the game page with its full "…" menu opened from code, `app.open_game_menu`) and the game
page's "…" menu (`menus.menu_sections` quick=False, sectioned) come from `app.game_actions()`. Picking art (`sources.apply_choice`) downloads into a staging dir and keeps the old
art if nothing came back; "Update Steam art on Frame" re-sends the art set to the game's anchor (agent ≥ 12).
Patch descriptions/reasons describe the general case, naming games only as "e.g. …".
uploads are interruptible (Cancel checked per MiB) and resumable (big files via SFTP `.part` append, small files
streamed in tar batches; the agent counts files already in `incoming/`). Multi-select in the Library queues
installs after asking every needed question up front. Failures end in one pop-up (Resume / Uninstall / log).
- Library folders (GitHub discussion #351): `core/folders.py` (no Flet) owns setting `scan.roots` (remember/add/remove/status/rescan_roots; the origin-based fallback only while the setting was never set, so removing every folder doesn't guess them back), Settings → Library folders (`settings.library_folders`, status read via run_bg), CLI `frameport folders [--add/--remove/--json]` + `frameport rescan`. Scans relink moved games (`pipeline.ScanReport`: a library game found elsewhere whose own files are gone and the copy is the same build (Quest: source_sha256, else versionName; Rift: same program path + size from the fingerprint, matched by game id or, renamed, by program) → only paths change (`relink_quest`/`_relink_rift`), user fields/builds/installs stay; another version → Scan a folder… takes it via `replace_apk(found=)`/`replace_rift_game`, Rescan only reports it; the old copy still there → kept). `add_game` no longer overwrites a user recipe (refreshes `suggested` only). Linux apps aren't scanned. PC installs of a moved Rift game (Steam shortcut path) untested.
- Other drives (GitHub #90, agent v63): anchors stay in ~/Applications/quest-frame, a game's files may live in
drives; vfat/exfat/ntfs/read-only refused), prepare*/finalize_linux `dest` (unmounted = error, never a fallback;
installed games keep their base), `move` (detached systemd-run + `move_status`; cp -a under podman unshare,
count+bytes check, symlink retarget, launch.sh: Quest app_dir line / Linux+PC VR rewritten from the record's
`launcher` field, else text swap), list_installed `drive`/`drive_missing` (install_state keeps such games
"installed"). PC: `install/drives.py`, library setting `install.drive` (Frame page → Storage), game menu
"Move to…" (job kind tool-frame), CLI `frame drives`/`frame move`/`install --dest`. Untested on the device.
- **PC VR repacks are pre-patched to run directly** (proven: Rick and Morty, Vader Immortal run when the exe is
launched directly; Revive breaks them). So Rift games default to `as_is` = install the copy unchanged and launch
the exe directly (`pcvr.xr_timefix` for the Frame OpenXR-1.1→1.0 fix, `pcvr.no_crash_reporter` for Unreal).
@@ -52,7 +161,11 @@ Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRA
doesn't do). `VD.bat` is Virtual Desktop's launcher: ignore it except as an exe-location hint. Library migration
`rift_run_direct` resets existing recipes.
Auto launch-test is skipped on PC installs (it would start the game on the user's desktop). Launch tests collect the Unreal
game log + crash summaries from the Proton prefix; triage `unreal-crash`. Lies Beneath via Proton without Revive
game log + crash summaries from the Proton prefix; triage `unreal-crash`. Agent v67 adds Unity's logs (LocalLow/<Company>/<Product>/Player(-prev).log via `<Name>_Data/app.info`,
`output_log.txt`, Temp/…/Crashes/*/error.log; `unity_logs`) to launch tests and diagnostics; triage `unity-vr-init` /
`unity-crash`. A catalog recipe verified with another build (catalog `xr` ≠ the build's) keeps the build's own
- Own artwork (0.8.0): game menu → "Use your own artwork…" (also from the Find artwork dialog) =
`views/art_dialog.show_custom_art_dialog`: one slot per kind (portrait/landscape/hero/logo/icon), FilePicker →
`sources.apply_custom` (Pillow check, ≥64 px, ≤40 MB, scaled to ≤3840 px, PNG if alpha/logo/icon else JPEG,
replaces only that kind + its thumbnails, drops the generated cover/banner, writes `.picked` = "custom") /
`remove_custom`; Steam shapes are still composed from what exists (`steam.py` PREFER).
- Art for Rift games: `artwork/sources.py` — Quest version package (OculusDB packageName, exact name or +
"Unplugged"-type suffix, never sequels) → Meta art; OculusDB square cover; Steam (exact names only); exe icon.
- Store details (`artwork/details.py`, entry `details`): OculusDB (description, genres, publisher, website; by Quest
@@ -86,7 +204,35 @@ 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>`; x86_64 builds run through FEX (app 3127680, no SLR:
RootFS /usr/share/guestos/fex-mesa from the OS image; needs `STEAM_COMPAT_DATA_PATH`, see docs/FRAME_RUNTIME.md):
`app-releases.json`, same 6 h cache, offline → cached / []) → `ChangelogEntry` (`whats_new()` keeps only the tag
message's "What's new" part: CI's intro, update hint and release-footer.md stripped); `between`/`changelog_for`
(installed < v ≤ offered, dev entry only when on/choosing dev, skipped versions included), `recent_history`;
the update/dev dialogs show one collapsible section per version (`_changes_column`, newest open); after an update
`pending_news` (setting `update.last_seen_version`; first start only records it; offline → retried next start)
→ Library "was updated" bar → "See what's new…"; Settings → Updates "What's new…" = recent history. CLI: `--version`, `frameport update [--check (exit 10)]
[--yes]`, once-a-day stderr hint read from the cache only (`refresh_cache()` in a daemon thread writes no
settings, to avoid read-modify-write races). `scripts/update_smoke.py <archive>` runs the real extract + swap script
(no relaunch) — CI runs it on all three OS with the archive it just built.
@@ -146,12 +323,44 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
by hand: the "Update now" button path (same apply(), called from the running app). macOS: CI smoke only.
- `agent/frameport_agent.py` — runs **on the Frame** (python3 stdlib only), JSON over SSH. Owns the install layout,
launch.sh template, Steam shortcuts (binary VDF), launch tests. Bump `AGENT_VERSION` when changing it.
- `bootstrap/bootstrap.sh` — one-time Frame setup served by the pairing server (sshd, app key, avahi service, Lepton).
- `catalog/games/<package>.yaml` — 38 recipes (34 verified 2026-09-28; Deadpool VR, 4XVR, NEX Player and AC Nexus's
- `bootstrap/bootstrap.sh` — one-time Frame setup served by the pairing server (app key, podman fix, Developer Mode, Lepton).
`bootstrap/setup.sh` — the setup URL (`curl -fsSL https://frameport.app/s | bash`, copied to the site by
`site/scripts/sync-media.mjs`): finds the PC (stdlib mDNS on 5353 for `_frameport-pair._tcp`, which the pairing
server announces while open; else the USB address and a /24 scan of `/ping`), `/hello` → the user clicks Allow (4
digits on both sides, `ask_digits`) → `/wait` hands over the code → runs bootstrap.sh exactly like the typed line.
Checked on the dev Frame 2026-10-10 (mDNS and scan paths) with a stub bootstrap; tests/test_setup_url.py.
Auto-pairing (`frame/autopair.py`, `app._start_auto_pair`, setting `frame.auto_pair`, default on; off with
FRAMEPORT_HOME/FRAMEPORT_NO_AUTO_PAIR): while no Frame is connected, Frames in Developer Mode (devkit mDNS, else a
30 s scan of the /24s for :32000/login-name, deduped by host key) are connected if FramePort's key works, else
offered the key via devkit.register every 4 s (refused at once until Pair new host is open; 45 s back-off after an
unanswered request). This WSL dev PC never hears the Frame's mDNS (Hyper-V firewall): the scan finds it.
- `catalog/games/<package>.yaml` (installed apps also fetch these from GitHub `main`, see "Catalog updates") — 38 recipes (34 verified 2026-09-28; Deadpool VR, 4XVR, NEX Player and AC Nexus's
90 Hz default confirmed later by the owner); `catalog/triage.yaml` — log signatures → fixes.
- `native/` — sources of the prebuilt binaries in `artifacts/` (adapter, VrApi bridge patches, GL shim, stubs).
`native/build.py` rebuilds them with NDK r27c (downloaded on demand into `native/.cache`, git-ignored; uses
`-ffile-prefix-map` so no local paths get embedded; zip symlinks are restored as copies). Users never need the NDK.
`native/a32translator/` (not an artifact, not shipped) = `a32run`, an AArch32 → AArch64 user-mode translator
(interpreter + JIT, ARM/Thumb-2/VFP/NEON) for running 32-bit ARM Linux programs on the Frame; its README has the
design, the qemu-arm differential fuzzer and program tests. `native/a32translator/bridge/` = the in-APK Android
bridge (32-bit JNI/NativeActivity libraries in a 64-bit app: stub + liba32bridge.so + guest runtime liba32rt.so;
harness with a fake JVM; test APK org.frameport.a32test passes in Lepton; GLES/EGL, OpenSL ES via AAudio, VrApi 1.x
-> the 64-bit VrApi bridge, controller input as Gear VR touchpad/back events; `bridge/convert.py` converts an APK).
First game: AFFECTED The Manor (Gear VR, Unity 5.6 + Mono) runs in the headset with picture and sound
(2026-10-10); Spunky Dungeon (Unity 2019.2, OVRPlugin 1.46 on VrApi 1.31, Platform SDK) plays at 72 fps.
In FramePort: patch `frame.a32_bridge` (`patches/frame/a32_bridge.py`: `convert()` is shared with the dev script
`bridge/convert.py`; artifacts `liba32bridge.so`/`liba32rt.so`/`liba32stub.so` from `native/build.py --only a32`)
is suggested for every 32-bit-only APK; the recipe then has `overport: False` (OVRPort is 64-bit only; the patch
ships OVRPort's loader chain + its 32-bit platform dispatcher itself, `overport.ensure_runtime_lib`), only
frame.a32_bridge/adapter/launcher of the frame patches, and `device.text_input_window` for Unity (`engine.a32_recipe`,
also run by `pipeline.set_recipe` + builds, so a bridge turned on by hand drops OVRPort & the 64-bit fixes; which
patches work there = `base.works_on_a32` (`Patch.a32`; overport/frame off unless `a32 = True`, adapter settings in
- No AArch32: 32-bit-only APKs fail with `INSTALL_FAILED_NO_MATCHING_ABIS`. Unfixable; point to Rift + Revive.
- No AArch32: 32-bit-only APKs fail with `INSTALL_FAILED_NO_MATCHING_ABIS` → `frame.a32_bridge` (the a32 translator inside the app, see native/a32translator below).
- GLES swapchains: only `GL_SRGB8_ALPHA8`/`GL_SRGB8` (35907/35905), no MSAA. Vulkan: format 43 (sRGB) but not 37 (UNORM).
- Missing: XR_FB_passthrough (emulate via ALPHA_BLEND), XR_FB_scene/spatial entities (emulated room from STAGE bounds),
XR_KHR_composition_layer_equirect2/cylinder, XR_FB_composition_layer_image_layout (flip emulated by Vulkan blit).
(offset = predictedDisplayTime − period − CLOCK_MONOTONIC, sampled in xrWaitFrame).
- No XR_FB_display_refresh_rate (`xrGetDisplayRefreshRateFB` -7), yet OVRPort's dispatcher offers it and answered 0 Hz
→ FrameBridge always answers with the measured rate (1/predictedDisplayPeriod, else 72). PreyVR (#306, idTech 4:
`USERCMD_MSEC = 1000 / GetRefresh()`) had 0 ms tics: async thread spinning, `com_frameTime` stuck at 0, menu black.
- Guardian STAGE bounds report 1×1 m (scene emulation uses ≥1.5 m).
- GL goes through **Zink** (Mesa GL on Vulkan). Mesa GLSL is strict: `#pragma` before `#extension` fails, implicit
int/float conversions fail (enable `GL_EXT_shader_implicit_conversions`), num_views=2 shaders on single-view FBOs
@@ -241,7 +475,10 @@ The Frame runs firewalld (22 and 32000 open). PC side: the setup server needs in
firewall blocks it silently (`DefaultInboundAction Block`): `pairing.ensure_reachable` adds a temporary rule via one
UAC prompt, removed when the server stops (flag file in %TEMP%, max 35 min); hints per OS after 45 s without a request
(`pairing.firewall_hint`). Flet 1.0 patches aren't thread-safe → `app.serialize_flet_updates()` (a dialog shown while a
scan redraw ran never closed: "dropped a patch for unknown control").
scan redraw ran never closed: "dropped a patch for unknown control"); it also makes property writes (Flet's
`Prop.__set__`) take the same `app.FLET_LOCK`: a property set on a background thread while the loop packed a patch
changed the control's `_values` mid-iteration ("dictionary changed size during iteration", a sidebar click's page
change died while the live Frame card took a sample). Anything that serves the app (ui_smoke, showcase) calls it too.
**Lepton:** needs an activity with category **LAUNCHER** (Quest apps often only have INFO → "APP_ACTIVITY is empty").
**2D apps:** Lepton runs every app headless (`lepton.headless=true`, only OpenXR output reaches the headset) unless the app folder (`<base>/lepton-app/`) has a `lepton-show-flatscreen` file (liblepton/app_metadata.sh) → Waydroid window on gamescope; agent v28 `set_flatscreen` at finalize for `vr_kind == "none"`. Android 11's navbar covered the
app's controls → patch `device.hide_navbar` (default on for vr_kind none, migration `flat_hide_navbar`) exports
@@ -283,28 +520,14 @@ Launch tests ignore log files older than the launch (stale Proton/game logs used
(`\\wsl$` is unreliable), so PC mode copies Revive to `%LOCALAPPDATA%\FramePort`.
FramePort never bypasses Oculus entitlement checks (Platform SDK games: flagged, PC mode with the Oculus app only).
**Upload speed (measured 2026-09-29):** via the home router (PC Wi-Fi → router → Frame wlan0) only 15-18 MB/s, the
same for paramiko, OpenSSH and 4 parallel streams, so the network path is the limit, not the SSH code. Direct to the
Frame's hotspot (`wlanap` 10.35.78.1; the owner's PC has Valve's USB Wi-Fi dongle on it) 83 MB/s OpenSSH / 97 MB/s
paramiko; reading dumps from D: via WSL drvfs is then the cap (~82 MB/s). `Frame.fast_link()` (installer
`transfer_link`, uploads ≥64 MiB) uses usb0 > wlanap when reachable **and** the host key matches the paired Frame.
**Upload speed:** home Wi-Fi caps uploads at ~11-18 MB/s whatever the SSH method; the Frame's hotspot (`wlanap`) ~83-97 MB/s; `Frame.fast_link()` (installer `transfer_link`, uploads ≥64 MiB) prefers usb0 > wlanap when the host key matches. → docs/DEVICE_NOTES.md#upload-speed
**Platform SDK detection** must include delay imports (`PEInfo.delay_imports`), modular Unreal's
`*-OnlineSubsystemOculus-*.dll` and Ready At Dawn's `pnsovr.dll`: Robo Recall, Lies Beneath and Lone Echo I/II all use
it; without the Oculus app they crash with 0xc06d007e (triage `delayload-missing`) — not fixable legitimately.
GUI: Frame → Installed → folder icon = file browser (agent `list_files`, flags files missing vs the install
manifest); Settings → About shows the bundled agent version and the Frame's.
**Revive under Proton arm64 (Lone Echo, 2026-09-29):** Revive's Detours hooks (LoadLibraryW/ExW, OpenEventW, the
signature check) don't take effect: Wine's kernelbase is ARM64EC. The LibOVR shim in the game then does a plain
`LoadLibrary("LibOVRRT64_1.dll")` search (exe dir, cwd, system32, windows, PATH — no registry, `OculusBase` or
`LIBOVR_DLL_DIR` used by this build) → `Failed to initialize Oculus API (-3001)` (= Lies Beneath's "Unable to load
LibOVRRT DLL"). A symlink `pfx/drive_c/windows/system32/LibOVRRT64_1.dll -> <base>/revive/LibReviveXR64.dll` (Wine
maps a symlink to the already-loaded module) gets past it to **-3021 = ovrError_LibSignCheck**: the shim only accepts
an Oculus-signed runtime. Next step (not done): make the runtime check pass without Detours, e.g. an injected helper
that patches the game's import table (IAT) for LoadLibrary*/WinVerifyTrust, or a prefix-level override. This is
runtime interop (what Revive does), not the Platform SDK licence check (which FramePort never touches).
Uninstall (Quest, saves kept) used to leave `deployment.json` → still "installed"; fixed (agent v16).
**Revive under Proton arm64:** Revive's Detours hooks don't take effect (Wine's kernelbase is ARM64EC); a system32 `LibOVRRT64_1.dll` symlink gets past -3001 to -3021 = ovrError_LibSignCheck (Oculus-signed runtime required; not bypassed). → docs/DEVICE_NOTES.md#revive-under-proton-arm64-lone-echo
`frame.vrapi_bridge`; those two changes are upstream candidates. 1.2.5 builds (its platform compat, new permissions)
work. AC Nexus: `patch_ac_nexus_no_appsw_90` is the catalog default (owner preferred 90 Hz); `STRICT` patches are only
taken from a catalog recipe where `applies()` holds (the AC Nexus ones need build MAIN.450412.207706.final, else the
whole overport run fails).
**OVRPort 1.2.5 (2026-10-01):** `patch` rejects unknown/duplicate args, unknown ids and an empty `--patches=`; it adds `libovrplatformcompat.so` itself (`frame.ovrplatformcompat` then skips). New patches `patch_ac_nexus_no_appsw_72/_90` (AC Nexus build 207706 only; `_90` = catalog default; STRICT patches only from a catalog recipe where `applies()` holds), `patch_disable_meta_xr_audio_telemetry`, `patch_vrapi_openxr` (OVRPort's VrApi translator fails on the Frame → keep `frame.vrapi_bridge`). The owner prefers OVRPort's fixes over ours where they work as well. `frameport install <pkg> --apk <file>` installs a test build. → docs/DEVICE_NOTES.md#ovrport-125
**Patching gotchas:**
- UnityPy re-serialization breaks scene loading → patch QualitySettings ints in place.
- LIEF's DT_NEEDED injection shifts segments; our `elf.add_needed` appends a new PT_LOAD (reuses PT_NOTE, else moves the
@@ -346,162 +553,65 @@ whole overport run fails).
- VrApi-direct engines (CryEngine Climb 2, POTW) need the VrApi bridge; the bridge drops whole frames on unknown layer
types (→ black screen with audio).
**Steam Frame controller models (2026-09-30, not yet seen in a game):** adapter setting `controller_models`
(`native/adapter/render_model.c`) emulates XR_FB_render_model and serves `files/framebridge/controller_{left,right}.glb`;
(folder name matching "frame" + left/right, OBJ+PNG, `openxr_grip` component → grip space) at finalize/set_settings.
Valve's models are never committed or copied off the Frame. Only games that use Meta's runtime controller models
benefit (manifest `RENDER_MODEL` permission/feature → suggested); **none of the 34 catalog games do** (they ship their
own meshes: that would need per-game asset replacement). Model discovery and conversion
checked on the device 2026-09-30: `/opt/steamvr/drivers/frame_controller/resources/rendermodels/frame_controller_{left,right}`
(component OBJs in model space = the whole `<name>.obj`, one `_color.png` 2048² near-black, `openxr_grip` rotates about
X only; hidden-by-default components like `status` are skipped) → ~2 MB glb each, ~1 s. Not yet seen in a game (none
of the installed builds has the new adapter, and none requests runtime models), so whether Meta's SDK attaches runtime models at the grip pose is unverified.
**Steam Frame controller models:** adapter setting `controller_models` (`native/adapter/render_model.c`, emulates XR_FB_render_model) + agent `install_controller_models` (Frame's SteamVR models → glb at finalize); no catalog game uses runtime models; Valve's models are never committed or copied off the Frame. → docs/DEVICE_NOTES.md#steam-frame-controller-models
**overport's dispatcher (`libopenxr_loader.so`) only forwards functions in its own table** (`overportOXR: Unknown
proc addr: …`), so adapter emulations of functions it doesn't know are unreachable. For XR_FB_render_model,
`native/xrshim` fills the gap: OVRPlugin's `dlopen("libopenxr_loader.so")` string is rewritten to the shim (see
native/README). Verified on the device with Toy Master (2026-09-30): `extension shim: xrLoadRenderModelFB -> FrameBridge`.
Toy Master doesn't request a model after that (it uses its own), so the glb loading path is only unit-tested.
**Crash backtraces (2026-09-30):** Lepton writes tombstones only to `lepton-logcats/steamlaunch-<appid>/logcat-crash.log` (after "Dumping logcat"), not launch.log; agent v23 launch tests wait for it and return `crash_log`, triage gets it via `triage(..., crash=)` (not pid-filtered: tombstones come from crash_dump's pid). The guest is `userdebug` (`ro.debuggable=1`), so Lepton's Fossilize layer loads into every app whatever the APK's debuggable flag; it has no off switch. Fossilize crashed Deadpool VR on uninitialized attachment-reference pNexts (several, in FVulkanRenderPass and the render-target layout) → `frame.vk_sanitize` = `native/vkshim` (engine's `dlopen("libvulkan.so")` string → `libfp_vk.so`, wraps vkCreateRenderPass2/KHR, drops unreadable/wrong-sType pNexts; verified: game runs). overport's dispatcher aborts on swapchains > 4096 px (`cmp wN,#4096` in xrCreateSwapchain) → `frame.swapchain_limit` (verified with 4XVR, 7680×3840 accepted by the runtime). Both are default-on (parity classifies their rewrites as
"expected"; library migration `quest_binary_fixes_v2`). The adapter shows cylinder layers (4XVR's movie screen) as ~15° quad strips (`cylinder_strips`, setting
`cylinder_strips`); the runtime composites them at full resolution. Equirect (360°) layers are dropped: drawing
them ourselves (GLES renderer in xrEndFrame: stutter, never showed 4XVR's VR video; Vulkan renderer: hung the
Frame's GPU in AC Nexus; reading the newest *released* image broke 4XVR's theatre) was removed again on the owner's
request — don't retry without a new approach. Converted layers must count as "swapped" or the original layer list
is submitted (runtime returns -2 for every frame). A focus debounce (hiding the Frame's brief
FOCUSED→VISIBLE→SYNCHRONIZED dips, which make 4XVR recenter) was also removed: AC Nexus stayed black with it (it
hid 521 ms focus changes at start). The new approach (below) is per-game, off the app's render thread, GLES-only.
never starts VR on the Frame (no OVRPlugin/OpenXR lines; runs as a 2D app), which is why its "controller setup"
screen can't be passed — Unity 2017's Oculus device check, not the controller profiles. Cpp2IL can't read Unity 2017.
The Frame's Android runtime (vrclient.so) knows oculus/touch_controller but not Meta's Touch Plus/Pro profiles
(OVRPlugin suggests those too, routinely) → adapter `profile_remap`.
Headset round 2 (2026-10-04): the Frame drops focus often (ms to 7 s; only some are presence/standby) → games pause
or recentre (B&S Player.OnVRPresence → Teleport, BattleGlide/Unreal pauses); focus_hold now 1 s focused / 1 s max dip
(longer must still pause). Myst crash = vrclient xrSyncActions race after FOCUSED → `sync_guard` (confirmed); its
object glitches: app space warp suspected (FB_space_warp is advertised and used) → recipe `patch_disable_space_warp`.
I Am Cat multipass: poses/times consistent, but every frame is submitted after the next xrWaitFrame (one period late;
Zink + doubled draws) and the game clamps its physics step to 10 ms → judder while still; testing scale 0.8. Roblox's
newest crash is on Fossilize's recording thread → vk_sanitize extended to own-engine libs (engine "Other").
Accounting+: unity_oculus_check + native/ovrpshim (libfp_ovrp.so waits via ovrp_WaitToBeginFrame before Unity
2017's ovrp_Update2) → VR in the headset at ~72 fps (2026-10-04), but stuck at "press any button" although input
reaches its OVRInput cleanly (probe: both Touch connected 0x63, individual buttons, input focus 1) → works with issues.
"outside of frame bounds" warnings stay (~2/frame) and are harmless.
Steam library (GitHub #4/#21/#27, agent v38): shortcuts go to every Steam account (signed-in first; MostRecent isn't
always the account on the Frame); stop_steam also waits for Steam's helpers; after the restart the agent re-reads
shortcuts.vdf and writes once more if Steam put its old copy back (`shortcuts_lost`), else reports it. 0.6.3's Play
auto-repair (`_add_then_play`) crashed (its job got a Job, not a reporter). Uploads resume on a transient OSError.
Lepton's Android 11 has no clipboard service (134 services; checked with `podman exec … service check clipboard`):
SDL/LÖVE apps crashed at start → `frame.sdl_clipboard` (`apk/dex.py`: in-place dex edit, nops one invoke, fixes
the header checksum/signature; verified with LÖVE for Android 11.5, GitHub #24 Dramatic Shape). 2D apps (vr_kind none)
keep every suggested patch that isn't about VR (`needs_vr = False`), not a fixed list. FramePort on the Frame:
`frame/local.py` (127.0.0.1, own key authorized; "This Frame (experimental)"; app data in
~/.local/share/frameport-app because ~/.local/share/frameport is the agent's) and Steam library changes wait while
Desktop Mode is open. Verified on the device 2026-10-04 (install + launch test from the Frame). Library updates on the
Frame run one at a time (agent v40 flock): two quick uninstalls used to bring a removed shortcut back (Roblox).
Headset round 3 (owner's verdicts, 2026-10-04): Blade & Sorcery works — its freezes were the headset's wear sensor
flickering off while worn (vrserver.txt "HMD off/on" 0.5-2 s) → per-game `focus_hold_ms=2500` (only this game reacts;
not a default). BattleGlide works (focus_hold). Myst works with issues (object glitches; space warp ruled out, its
recipe keeps it on). I Am Cat works with issues (judder; scale 0.8 no help). Roblox unsupported (je_free in
libroblox, also with the Vulkan shim). Installs skip the Steam restart when the shortcut is unchanged and wait while a
game runs (agent v37). New default fixes in FramePort's code reach games already in a library: after every app update
`library._follow_catalog` re-derives each non-user recipe once (setting `recipes.app_version`; tests switch it off via
`library.REFRESH_ON_UPDATE`); analysis fields added later still need a re-analysis. Troubleshooting techniques: docs/PLAYBOOK.md "Debugging techniques". Unity `boot.config` "vulkan" substring mislabels GLES games as Vulkan
(I Am Cat ran GLES); OVRPlugin's "Unavailable OpenXR extension: XR_FB_scene" is routine (no longer triaged).
**Round 4 (2026-10-04):** XR_KHR_android_surface_swapchain is listed by the Frame's runtime but returns
FUNCTION_UNSUPPORTED → adapter `surface_emul` (default on, `native/adapter/surface_swapchain.c`): an ordinary runtime
swapchain is returned, the game gets a Surface from a SurfaceTexture on a worker thread (own EGL context, JavaVM from
XrInstanceCreateInfoAndroidKHR), frames are read back (glReadPixels) and uploaded in xrEndFrame (Vulkan: own command
buffer + fence per panel, never waits; GLES: glTexSubImage2D). I Am Monkey's intro works (owner-confirmed). SUPERHOT
(Quest) quit at start: its cloud save folder was mode 1700 and Lepton's app writes through the folder's group →
DATA/ → external files/WiiCompiledOpenXRVR/DATA, MOD/ → .../RetroRewind6 (decompiled with jadx). Lepton has no
picker at all: a FramePort fix would be an injected picker activity. Generated cover/banner art used to suppress the
Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
**Steam library failures (GitHub #21/#30, open):** on 0.7.0 some Frames have FramePort's shortcut in shortcuts.vdf (so the install skips the Steam restart) yet Steam answers Play with "Game configuration unavailable" (= `Steam_AppUpdateError_9`; console_log: `LaunchGameAction: launch error 9 <appid>`). Not reproducible on the dev Frame (same SteamOS build). Agent v42: `launch` returns `steam` = what Steam's console_log says about that launch (started / error + code / silent; the app logs it and offers Report a problem on an error) and `collect_diag` adds `steam_library` (real Steam dir behind ~/.steam, client beta, Steam start vs shortcuts.vdf write time, FramePort's entries per account) + `steam-console.txt`. Verified on the dev Frame 2026-10-04 (Play → `started` within ~1 s). The dev Frame runs Steam's **arm64 beta** client (`package/beta` = linux_arm64_beta_…): check whether reporters are on the stable client. Next: read those from a reporter's zip.
**Lepton storage (2026-09-30):** each app's /sdcard (= /storage/emulated/0 → `<base>/lepton-data/external`) has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (liblepton/mounting.sh, only if they exist at start); agent v24 `storage_targets` reads that mapping. Android's MediaProvider canonicalises paths to /home/steamos/... and rejects every file ("doesn't appear under [/system/media...]"), `sm list-volumes` is empty: the media index never works, apps must browse folders. Lepton installs with `adb install -g` (runtime permissions granted, MANAGE_EXTERNAL_STORAGE too). Files: `install/files.py`, `frameport frame send|storage`, GUI Files tab (formerly Frame → Send files).
**SteamVR per-app settings (2026-09-30):** editing steamvr.vrsettings while SteamVR runs is lost; the web API (127.0.0.1:27062 /app/setsettings) needs `x-steamvr-secret`. `native/vrsettings` = `fp_vrsettings.exe` (freestanding, OpenVR `FnTable:IVRSettings_003` as a Utility app, loads SteamVR's bin/win64/openvr_api.dll) sets them live and SteamVR persists them: section `steam.app.<shortcut appid>`, keys `preferredRefreshRate` (float) and `motionSmoothingOverride` (0 global, 1 on, 2 off, 3 always). Steam Link (vrlink) lists the Frame's rates 72/80/90/96/108/120/144 in vrserver.txt and follows the per-app preference ("host preferred N Hz"; whether the key is honoured is unverified in-headset yet). Judder metric: vrcompositor.txt session summary dropped + "Timed out. N total" (Stormland: 0 dropped but 313 timeouts in 2 min); fpsVR (`%LOCALAPPDATA%\fpsVR\*.json`, 0.1 ms histograms) gives p99 CPU/GPU ms. `pcvr.steamvr_tuning` (default on, PC only) applies on Play: highest rate whose budget ≥ p99×1.05, at least one step down, smoothing on.
**Language packs (merged from PR #20, 2026-10-04):** overport's `libovrplatformloader.so` is a dispatcher that `dlopen`s Meta's own loader (`libovrplatformloader_meta.so` / `_meta_q1.so`, also `libpxrplatformloader.so`) and keeps its own message queue; `ovr_LanguagePack_GetCurrent/SetCurrent` are 8-byte `return 0` stubs in it, `ovr_AssetFile_GetList` forwards to Meta's loader. `frame.langpacks` (opt-in, `native/langpack`) serves `<tag>.lang` files from the game's data; `elf.hide_exports` marks the loader's exports STB_LOCAL (bionic and glibc only match GLOBAL/WEAK; verified for glibc, bionic's `is_symbol_global_and_defined` is from memory). `libfp_langpack.so` is built here (`python native/build.py --only langpack`) and committed. Owner-verified 2026-10-04: Deadpool VR with only `en.lang` and the patch on plays English dialogue and runs normally (headless launch tests show 2-6 fps while it loads: not a regression sign). A dispatcher answer that arrives after we answered the timed-out GetList is dropped (one answer per request); games already in a library get `lang_packs` filled after an app update (`library._refresh_data_fields`). The library logs to logcat under the tag `fp_langpack` (dirs looked in, packs found, every language-pack call), so it shows up in the game's `launch.log`; an `ovr_AssetFile_GetList` the dispatcher leaves unanswered for 1.5 s is answered with our packs alone. Deadpool VR (Unreal) accepts a pack only when its `Metadata` equals the game's own version string (`ULanguagePacksSubsystem` compares it with `%s.%s.%s.%s.%s` built from the build info, e.g. `1.0.40.356975.Quest` = versionName; found by disassembling `libUE4.so`): the patch writes the APK's versionName into the library (`@FPMETA@` slot, `with_metadata`), `FRAMEPORT_LANGPACK_META` overrides it. Deadpool VR (2026-10-04, headset): German became selectable with that Metadata, but dialogue stayed silent (even English once reported as a pack) while the path was spelled `/sdcard/Android/obb/<pkg>/x.lang`; with the `/storage/emulated/0/Android/obb/<pkg>/x.lang` spelling (Unreal's own, now listed first in `scan_dirs`) German dialogue plays. `FRAMEPORT_LANGPACK_SKIP=<tags>` or a file `fp_langpack_skip` in the obb folder leaves packs out of the list (experiments).
**Crash backtraces:** Lepton writes tombstones only to `lepton-logcats/steamlaunch-<appid>/logcat-crash.log` (launch tests return `crash_log`). Fossilize loads into every app (userdebug guest) → `frame.vk_sanitize` (`native/vkshim`); overport's dispatcher aborts on swapchains > 4096 px → `frame.swapchain_limit`; cylinder layers → quad strips (`cylinder_strips`). Drawing equirect layers ourselves and a focus debounce were tried and removed: don't retry without a new approach. → docs/DEVICE_NOTES.md#crash-backtraces-fossilize-swapchain-limit-cylinder-and-equirect-layers
**360° layers / 4XVR:** the Frame's Android runtime composites only quad + projection layers (quads always above projection layers). Per-game adapter settings (off by default): `equirect_emul` (GLES), `equirect_flip/face/res/fps/stereo`, `stable_local`, `focus_hold` (default on), `aim_pitch/aim_yaw/aim_forward`, `refresh_rate`, `layer_debug`; agent `link_media` / `app_media_dirs` put sent files into a player's own folder. → docs/DEVICE_NOTES.md#360-layers--4xvr
**Companion apps / intents:** a second APK can run inside a game's Lepton container, but Lepton turns every `android.intent.action.VIEW` with data into `steam://openurl` → "open in external player" hand-offs can't work; Lepton installs exactly one `*.apk` per app folder. → docs/DEVICE_NOTES.md#companion-apps--intents-stremio--4xvr
**Text input:** Lepton's Android has no IME and VR apps run headless (no focused window); `lepton-show-flatscreen` keeps VR and gives focus + Steam's keyboard (`device.text_input_window`); `frame.unity_text_input` patches Unity's TMP_InputField/InputField at Cpp2IL offsets; agent `_keyboard` = uinput "Type on Frame". `pm install` of a second APK corrupts the main app (`cmd_real package install` skips the hook). → docs/DEVICE_NOTES.md#text-input-stremio-vr
**User reports #4-#10:** shortcuts go to the signed-in account (agent `library_users`), `launch` errors `NOT_IN_LIBRARY`; shared Cpp2IL run (`unity_text_input.Il2cppReturnPatch`) for `frame.unity_runtime_msaa_off` and `frame.unity_multipass`; VR4 → catalog `use_alt`. **Catalog changes reach existing games**: recipes store `catalog_rev`, `library._follow_catalog` re-derives non-user recipes. → docs/DEVICE_NOTES.md#user-reports-2026-10-04-issues-4-10
**Round 2 of reports / headset rounds 2-3 (2026-10-04):** vkshim `vk_shader_fix` (VR4); `Il2cppReturnPatch.field_loads` (I Am Cat); builds record `recipe_fp` (changed recipe/revised patch → "Update on Frame"); `Frame.relocate`; adapter `profile_remap` (Touch Plus/Pro); `sync_guard` (Myst); `focus_hold` tuning; ovrpshim for Unity 2017 (Accounting+); Steam library to every account, `shortcuts_lost` / `add_devkit_entry`; no clipboard service → `frame.sdl_clipboard`, `frame.godot_clipboard`; 2D apps keep non-VR patches (`needs_vr = False`); `frame/local.py` (FramePort on the Frame); after every app update `library._follow_catalog` re-derives non-user recipes once (`recipes.app_version`, `library.REFRESH_ON_UPDATE`). Analysis fields added later: **bump `analysis/detect.ANALYSIS_VERSION`** (re-analysis at GUI start + `pipeline.refresh_analyses`; `analysis_failed`). Roblox and BONELAB crash (unsupported). → docs/DEVICE_NOTES.md#round-2-of-reports-headset-rounds-2-3-2026-10-04
**Round 4:** XR_KHR_android_surface_swapchain is listed but unsupported → adapter `surface_emul` (default on, `native/adapter/surface_swapchain.c`); save folders without u/g+rwx → launch.sh `fix_perms`; Lucky's Tale OOM (no fix); `perf` works as steamos (gdb blocked); QuestCraft JRE, WiiCompiled import by hand (Lepton has no document picker). → docs/DEVICE_NOTES.md#round-4-2026-10-04-surface-swapchains-save-folder-permissions
**Steam library failures (GitHub #21/#30/#41/#42):** on some Frames Steam never loads FramePort's shortcuts.vdf entries (Play → AppError_9) → fallback: register through Steam's devkit interface (`devkit-1 … create-shortcut`, `~/devkit-game/<id>/`; `devkit_appid`, `devkit_appid_from_log`, `devkit_unregister`, `copy_grid_art`; ids: letter first, letters/digits/_ only); `collect_diag` adds `steam_library`. Cause still unknown. → docs/DEVICE_NOTES.md#steam-library-failures-and-the-devkit-fallback-github-21304142
**Exit game (GitHub #36):** `Apps.TerminateApp` (Steam CEF devtools on 127.0.0.1:8080) closes games; launch.sh ends the game when its parent reaper is gone (`upgrade_launchers` adds it). → docs/DEVICE_NOTES.md#exit-game-github-36
**SteamVR dashboard at game start:** launch.sh's `_dashboard_worker` hides the dashboard via `SteamClient.OpenVR.VROverlay` (agent `steam_js`) from the first FrameBridge `new layer:` line (120 s, ≤10 times, stops after `toggle_dashboard_action`); log `<base>/dashboard.log`, opt out `FRAMEPORT_KEEP_DASHBOARD=1`. → docs/DEVICE_NOTES.md#steamvr-dashboard-at-game-start
**Heuristics eval (2026-10-04):** 19/44 recipes exact (superseded by the 2026-10-15 numbers under Heuristics). → docs/DEVICE_NOTES.md#heuristics-eval-2026-10-04
**Power (0.9, agent v47):** sidebar bar below the Frame card: Sleep / Restart / Shut down, each confirmed (`app.frame_power`, a running game asks again). logind answers CanSuspend/CanReboot/CanPowerOff = "challenge" for an SSH session but "yes" inside a user unit, so agent `power` runs `systemctl suspend|reboot|poweroff` from a transient `systemd-run --user --on-active=3` timer (the command answers first). Restart verified on the device (back in ~84 s, new boot id).
**USB cable link:** `usb0` is a USB NCM gadget (Developer Mode only); Frame 10.86.200.233, PC **10.86.200.234** (`frame/usb.py`); ~37 MB/s; `scripts/usb_autotest.py`, `frameport frame usb-check`; discovery prefers USB > hotspot > network (`discovery.dedupe`). → docs/DEVICE_NOTES.md#usb-cable-link
**Catalog updates without a release (2026-10-05):** apps fetch `catalog/games/*.yaml` from GitHub `main` (`recommend/catalog.refresh_remote`: one API call `git/trees/main?recursive=1` + raw.githubusercontent downloads of changed blobs, cached as `catalog-gh-<sha>.yaml`, every 6 h; GUI at start + Settings → Data "Check now"; CLI background thread + `frameport catalog-update`). `catalog.load()` only reads the cache. A remote entry is skipped (`unusable_reason`) when it names a patch/adapter key this app doesn't register, has a field `CatalogEntry` doesn't know, or `min_app` > this version: add `min_app` (or rely on new patch ids) when a config needs an unreleased FramePort. Remote beats bundled unless the bundled entry has a later updated/verified date; the user's own entries still win as before. Off: setting `catalog.auto_update`, env FRAMEPORT_NO_CATALOG_UPDATE; FRAMEPORT_CATALOG_URL still overrides the source. So: **pushing a catalog change to main reaches users within 6 h** (their recipes follow via catalog_rev → Update on Frame).
**Start activity / QuestCraft / ITR2 pop-in:** `frame.start_activity` (analysis `extra.vr_activity`, `axml.set_start_activity`; OVRPort gives every MAIN activity LAUNCHER, so take the VR activity from the original APK); Unreal reads user config from **internal** storage; Lepton passes `LEPTON_ENV_<NAME>` to the app as `<NAME>` (QuestCraft `LIBGL_NOERROR`); vkshim `vk_query_slots` left off. → docs/DEVICE_NOTES.md#start-activity--questcraft--itr2-pop-in
**Vulkan validation / ITR2 solved:** bundle Khronos' `libVkLayer_khronos_validation.so` into a test APK + vkshim `vk_validation=1` (logcat tag VALIDATION); `vk_spec_fixes=1` drops ITR2's invalid depth resolve; VALVE_rpo removed its fog (catalog `lepton_env: VK_INSTANCE_LAYERS`). Agent `not_started` waits 30 s for "Boot complete!". → docs/DEVICE_NOTES.md#vulkan-validation--itr2-solved
**GitHub #38/#39:** SteamVR rejects image rects past their swapchain (-25) → FrameBridge `rect_clamp` (default on), triage `swapchain-rect-invalid`; The Room VR MSAA crash in libgallium. → docs/DEVICE_NOTES.md#github-3839-powerwash-simulator-the-room-vr
**Headset round 2026-10-05:** FrameBridge `pose_consistency` (I Am Cat judder), xrshim `haptic_fix` (Lucky's Tale), **`focus_hold` on by default with 5 s** (wear-sensor dips, `logs/eyetracking.txt`), `unity_no_overlay_copy` (The Room VR), ovrpshim frame wait for Unity 2019 (`UnityOculusCheck.legacy_loop`), `frame.ovr_trace` (opt-in, `native/ovrtrace`, logcat `fp_ovrtrace`). → docs/DEVICE_NOTES.md#headset-round-2026-10-05-evening
**Unity built-in VR input:** probe builds `FRAMEPORT_INPUT_PROBE=1`; ovrpshim adds a `GetMouseButtonDown` icall click (Accounting+); libunity 2019 only polls Touch when the device model starts with "Oculus" → `unity_oculus_check` revision 4 `oculus_model_checks` (BattleSisters); `haptic_fix` suggested for every game with libOVRPlugin.so. → docs/DEVICE_NOTES.md#unity-built-in-vr-input-accounting-battlesisters
**Vader Immortal (GitHub #49):** stuck on its loading card and leaked GPU mappings (solved below: `gl_error_clear`); diagnostics FrameBridge `layer_debug`, `strip_color_bias`, `frame_balance`, `snapshot=N` (`snapshot_gl.c`: saves the submitted left-eye image as `files/fb_snap_*.ppm`). → docs/DEVICE_NOTES.md#vader-immortal-headless-investigation
**SteamVR overlay apps:** host OpenVR overlays composite over Lepton games; detection `analysis/vroverlay.py`, patch `pcvr.vr_overlay`, Linux fields `vr_overlay`/`vr_overlay_autostart`, agent `register_vr_overlay`/`unregister_vr_overlay`/`launch_vr_overlay`; SteamVR on the Frame reads only `binary_path_linux_arm`; FramePort's own autostart (`ensure_overlay_service`, `frameport-vr-overlays.service`). See also docs/FRAME_RUNTIME.md "Overlay apps". → docs/DEVICE_NOTES.md#steamvr-overlay-apps
**Vader's leak solved / AC Nexus flips:** stale GL errors broke SteamVR's GL interop → adapter `gl_error_clear` (GLES, catalog for Vader ep1-3); read `xrclient_<pkg>.txt` in Steam's logs for runtime errors; the runtime caps swapchains per session (~15) → flip emulation in place; adapter `flip_dump`. → docs/DEVICE_NOTES.md#vaders-leak-solved--ac-nexus-flips
**Unreal's self-restart:** UE 4.21+ restarts itself after the first shader precompile and Lepton ends the container → launch.sh RESTART_BLOCK starts Lepton once more (`upgrade_launchers`; `FRAMEPORT_NO_RESTART=1` off). → docs/DEVICE_NOTES.md#unreals-self-restart
**xrWaitFrame runs ahead:** the runtime sometimes returns a display time <1 refresh after the last submit and rejects the second submission (`VRCompositorError_AlreadySubmitted`) → the VrApi bridge re-waits (`pacing 2s:` counters). → docs/DEVICE_NOTES.md#xrwaitframe-runs-ahead-journey-of-the-gods
**Double launch:** launch.sh takes `flock` on `<base>/.launch.lock` (fd 9); a second launch exits 0 and logs to `<base>/launch-dup.log` (`upgrade_launchers` adds it). → docs/DEVICE_NOTES.md#double-launch
**Issue triage round 2026-10-06:** FrameBridge turns haptic amplitude 0 into xrStopHapticFeedback, per-game `haptic_scale`; Lambda1VR → `frame.tbxr_vendor`; Jurassic World → `frame.vrapi_stub`; Metro Awakening / Pinball FX → `hide_space_warp`; `frame.ovr_trace` can't trace Unity games; the VrApi bridge's 30 s head-pose deadline ends headless VR mode. → docs/DEVICE_NOTES.md#issue-triage-round-2026-10-06
**Lepton storage:** each app's /sdcard has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (agent `storage_targets`); the media index never works; Lepton grants all runtime permissions. → docs/DEVICE_NOTES.md#lepton-storage
**SteamVR per-app settings:** `native/vrsettings` = `fp_vrsettings.exe` sets `steam.app.<appid>` `preferredRefreshRate` / `motionSmoothingOverride` live; `pcvr.steamvr_tuning` (default on, PC only). → docs/DEVICE_NOTES.md#steamvr-per-app-settings
**Language packs:** `frame.langpacks` (opt-in, `native/langpack`, `elf.hide_exports`, logcat tag `fp_langpack`) serves `<tag>.lang` files; Unreal needs the pack's Metadata = the game's version (`with_metadata`, `FRAMEPORT_LANGPACK_META`) and the `/storage/emulated/0/...` path spelling; `FRAMEPORT_LANGPACK_SKIP`. → docs/DEVICE_NOTES.md#language-packs
**Cube swapchains:** the runtime refuses `faceCount=6` → FrameBridge `cube_standin` (default on, GLES only, `native/adapter/cube_standin.c`). → docs/DEVICE_NOTES.md#cube-swapchains
**Hardware video decoding:** `native/hevc` OMX plugin (`OMX.frameport.{avc,hevc,vp9}.decoder`), installed once per Frame (`ensure_video_codec`, agent `video_codec_status`/`install_video_codec`/`video_codec_switch`); **bump `revision` in native/hevc/build.py with every artifact change**; per game `frame.hw_video_decode` (analysis `media_codec`), Settings `video.hw_decode`, `FRAMEPORT_NO_HW_VIDEO=1`; Batman migration `batman_video_patches` + `surface_native`. → docs/DEVICE_NOTES.md#hardware-video-decoding
**Issue round 2026-10-12:** Lepton breaks on unquoted paths with spaces → launchers give Lepton a `~/.local/share/frameport/lepton-paths/<pkg>` link (`app_dir_lines`/`set_app_dir`/`launcher_base`); `frame.eos_keychain_loop`, `frame.unity_tls_key_pool` (`libfp_tkeys.so`, `elf.rename_imports`), `frame.vermillion_scene_canvas`; `tools/cpp2il.py` falls back to Cpp2IL's dev build for metadata v107; Linux `desktop_icon`; `scripts/upload_bench.py`. → docs/DEVICE_NOTES.md#issue-round-2026-10-12
**OpenSSH uploads (#324/#242):** `native_upload.quote` escapes only backslash and `"`, Win32 local paths go as `C:/…`; `Frame.auth` records the login that worked (app_key / user_key from `ssh.extra_keys`, `frame ssh-keys`, agent, password); strict IdentitiesOnly first, relaxed retry. → docs/DEVICE_NOTES.md#openssh-uploads
**Meta user id (#182):** OVRPort's platform loader makes up a new user id every start → `frame.ovr_stable_user` (default on) returns a stable per-game, per-user id. → docs/DEVICE_NOTES.md#meta-user-id
**Install link updates:** manifest `version` → library `link.version`; `pipeline.check_link_updates` (GUI start, 6 h, setting `links.check_updates` = Settings → Updates → Games) marks `link_update` → Library bar / game page → `link_dialog.update_from_link`; CLI `frameport link-updates`; the demo link is never checked. → docs/DEVICE_NOTES.md#install-links--framedrop-button-protocol
## Releases, CI, GitHub
Maintainer-only notes (accounts, credentials, key locations) live in the git-ignored `CLAUDE.local.md`.
Public repo `github.com/spoopyghosty0/frameport` (branch `main`). Push a `v*` tag → CI (`.github/workflows/build.yml`)
@@ -510,6 +620,12 @@ tests, builds Windows x64 / macOS arm64 / Linux x64 bundles, signs, attests and
`FramePort-selfsigned.cer`; notes = "What's new" from the annotated tag message + the short `packaging/release-footer.md`; owner: keep release
notes short — a few "What's new" bullets, nothing long after them).
Installed apps find the release themselves (self-update), so the notes are what users see in the update dialog.
- **Dev builds (for testers, no release):** Actions → build → Run workflow (main), "dev" ticked, optional "notes"
(what to test). The bundles get version `<next patch>.dev<run number>` (`scripts/dev_version.py`, not committed) and
replace the rolling `dev` pre-release (`dev-release` job; same assets + SHA256SUMS). Automatic update checks ignore
pre-releases; testers use Settings → Updates → "Install the latest dev build…" (`updates.check_dev`,
`Updater.install_dev`). `parse_version` sorts 0.9.0 < 0.9.1.devN < 0.9.1, so testers get the next release normally.
- **Upstream trackers:** issues labelled `upstream` (#73 microphone, #74 haptics, #75 VrApi bridge) list our workarounds for OVRPort bugs and how to drop them; check them against OVRPort's latest release before each release.
- **Release checklist:** bump `src/frameport/_version.py` (the only version; `scripts/package.py` fails a tag build
whose tag ≠ `v<_version>`), commit, `git tag -a vX.Y.Z -m "FramePort X.Y.Z" -m "<What's new, Markdown bullets>"`,
push the commit and the tag. Never publish a release without its `SHA256SUMS.txt` (the updater refuses it) and keep
@@ -525,6 +641,11 @@ Installed apps find the release themselves (self-update), so the notes are what
Windows console) plus PYTHONUTF8; macOS builds need `--python-version 3.12 --arch arm64` (cryptography has no wheels
for flet's default Python / x86_64 cross-build), with a PyInstaller fallback step; `astral-sh/setup-uv` has no
floating major tags after v7 → pin the exact version; force-moving a tag starts duplicate runs (cancel one).
- `jni` (2026-10-06): jni_flutter 1.0.4/1.0.4+1 generate bindings that require jni ^1.1.0 while Flet's build template
Install games that target the Meta Quest, Android, or general PCVR onto your**Valve Steam Frame**. FramePort handles everything from uploading game files, setting up your Frame, injecting compatibility patches, and adding shortcuts to your Steam library. FramePort aims to be as simple as possible by taking advantage of the fact that the Steam Frame runs on Linux.
Install Quest games, Android apps, Linux apps and PCVR games on the**Valve Steam Frame**. FramePort sets up the
Frame, patches each game so it runs there, uploads it and adds it to your Steam library with artwork.
**Tested something? Share it.** In FramePort open the game → **…** → **Share working config…** (it fills in the
recipe for you) or **Report a problem…** (attaches a diagnostics zip with personal data removed). Without the app:
[share a working config](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml) · [report a problem](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml). Shared configs become built-in recipes for everyone.
FrameDrop and Valve's own tools install an app as it is. FramePort differs in four ways:
- **Free and open source** (GPL-3.0). FrameDrop is free (donationware) without published source.
- **Quest games that don't run on the Frame as they are** get converted and patched, with a tested recipe for 120+
games. The others install the game unchanged.
- **Windows, macOS and Linux.** FrameDrop is for Windows.
- **Wi-Fi or a USB cable**, and no **Pair new host** step.
<details>
<summary>All differences</summary>
| | **FramePort** | **FrameDrop** | **By hand with Valve's tools** |
|---|---|---|---|
| Cost and source code | Free, open source (GPL-3.0) | Free (donationware), source not published | Free, from Valve |
| Runs on | Windows, macOS, Linux | Windows | Depends on the tool |
| First connection | One line in the Frame's terminal; it turns on Developer Mode itself. No password | Turn on Developer Mode, then **Pair new host** | Turn on Developer Mode and pair, or use Android's debug tool (adb) |
| Wireless or cable | Wi-Fi, the Frame's hotspot or a USB cable | Same Wi-Fi network | Wi-Fi, or adb |
| Quest games that don't run as they are | Converted and patched for the Frame | Installed as they are | Installed as they are |
| Knows which patches a game needs | Tested recipes for 120+ games, updated without an app update | Not stated | No |
| In the Steam library | Yes, with artwork and tags | As a "Devkit Game" shortcut | As "Devkit Game: <title>"; not with adb |
| Android apps, Linux apps, Windows programs | All three; Proton (runs Windows programs) is installed for you | All three; install Proton first | Yes; 2D Android apps need an extra file |
| PC VR games | On your PC; some also on the Frame | Not supported | Not supported |
| "Install with …" buttons on websites | Yes ([frameport.app](https://frameport.app) links) | Its own | No |
| A game doesn't start | A launch test reads the logs and suggests a patch | A log viewer | No help |
| Use the Frame from your PC | Live view, Monitor, Files, Screenshots, Type on Frame | Not stated | No |
</details>
Other tools as described on their own pages, checked 2026-10-09:
@@ -104,8 +138,9 @@ uv run frameport --help # command line
uv run pytest # tests
```
## AI Usage Notice
While I would like to program everything manually, I no longer have much free time for personal projects. As a result I make use of AI tools to make it significantly quicker to debug compatibility issues.
## AI usage
I don't have much free time for this project, so I use AI tools to debug compatibility problems faster.
@@ -5,12 +5,15 @@ FramePort is GPL-3.0-only (see `LICENSE`). It includes or downloads the followin
## Included in this repository / the release bundles
| Component | Where | License |
|---|---|---|
| LuaJIT (Lua engine for verified xLua pointer compatibility, github.com/LuaJIT/LuaJIT) | `artifacts/arm64-v8a/libfp_luajit.so`; pinned build in `native/luajit/build.py` | MIT (`native/luajit/COPYRIGHT`, included in bundles as `artifacts/licenses/LuaJIT.txt`) |
notes:'GPU hang (zink:DEVICE LOST) even with MSAA off.'
details:Legacy VrApi via OVRPlugin.
status:works
notes:Plays with controllers that follow the hands (owner's headset test, Quest 1 build 35713).
details:'Unity 2019.4 on its built-in Oculus VR (no Oculus XR Plugin). Its legacy frame loop never waited for frames
(GPU hang, zink: DEVICE LOST) and Unity reported only Go controllers: frame.unity_oculus_check. Its frame wait then
deadlocked at the Init scene (Unity skipped beginning a frame) and the physics-step pose update located the
controllers in the past (hands lagged): both fixed in that patch (revision 5), switched on for this game by ovrp_begin_gate and ovrp_hold_physics. Grabbing an object in the tutorial
vibrates the controller; OVRPort''s envelope conversion then allocated ~1 GB/s until the memory cap ended the game:
haptic_fix. The Quest 1 build has no arraysources_assets.hd, which the game loads on the Frame (it detects a Quest
2) and then skips the .sd bundle:textures are missing unless the .sd file is also present under the .hd name in the
game''s obb folder.'
frame:
- frame.unity_no_msaa
- frame.unity_oculus_check
adapter:
haptic_fix:1
ovrp_begin_gate:1
ovrp_hold_physics:1
pcvr_alternative:Sniper Elite VR (Steam PC VR). Winter Warrior (Quest) works on the Frame.
notes:Crashes while starting its graphics (Vulkan); no fix yet.
details:SIGSEGV in vkCreateInstance, called from the game's own Vulkanhooks (libSLZQuestNative.so) into code that no
longer exists, right after OVRPlugin's pre-initialization creates and destroys an OpenXR instance. Keeping the
runtime (vrclient.so) and Steam's Fossilize layer loaded didn't help, so the stale pointer is to memory freed with
that first instance.
status:works
notes:Builds 1.2068 and 1.2974 play (owner's headset tests). One recipe serves both builds - 1.2068 needs frame.unity_user_presence (head tracking and controls); 1.2974 also needs
frame.slz_vulkan_hooks (72 fps after about 35 s of shader prewarming), which changes nothing on 1.2068.
details:Both builds - the game runs (72 fps), but its player body stayed frozen - no head tracking, the controllers stuck to the
model, no buttons - although OpenXR input and OVRPlugin's poses were fine. A few seconds after start (when Unity
switches XR loaders) OVRPlugin reports the worn headset as not worn (ovrp_GetUserPresent2 -> 0), and BONELAB's
Marrow rig only follows the player while Unity's HMD device reports UserPresence (OpenControllerRig checks
XRHMD.IsUserPresent every frame). frame.unity_user_presence reports the headset as worn. Build 1.2974 only - it adds Stress
no_appsw_90:'2026-10-02, OVRPort 1.2.5 (owner:90Hz felt better than 72 Hz; same known issues)'
flip_in_place:'2026-10-14, owner in the headset:launch warnings and tutorial pop-ups upright (GitHub#138)'
updated:'2026-10-15'
min_app:1.2.0
Loaded 100 of 990 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
spoopyghosty0