saphid--frame-control/.claude/NOTES-vr-library.md

vr-library implementation notes

Scope: /tmp/vrapk/p1.md plus parent updates mandating all-entrypoint artwork, SteamGridDB, designed fallback art, settings/backfill and two visual iterations. Worktree /Users/saphid/projects/steam-frame-vrlib, branch vr-library. No delegation, push, PR or issue edits. Parent owns independent review and integration.

Implementation

• Initial commit c06b328: shared artwork, collection handling, launcher supervision, APK icon fallback and tests. Follow-up replaces its bitmap artwork implementation with Steam Chromium canvas + Motiva Sans.
• ui/frame_steamgriddb.py: optional API provider, exact title (or trailing VR) match, highest-scored returned static/non-NSFW artwork, separate portrait and wide requests. No key means no requests/warnings. Saved settings are atomic 0600 on POSIX; API never returns the key; auth redirects disabled.
• Precedence: provider, source slots/banner/feature graphic/screenshots, APK icon/generated art. All five outputs have fixed Steam sizes. Host Python stays stdlib-only and Python 3.9 compatible; Frame renders consistently regardless of host OS. Package filters include both new JS resources.
• frame/android/library_artwork.js: dominant-colour gradient, blurred icon backdrop, large icon/shadow, real font, no title in hero, transparent logo. Removes only opaque near-black matte connected to icon corners. Native icons remain original; opaque foreground app tiles have rounded corners.
• apply_library is mandatory for APK and native-title installs. CLI, upload, catalogue, versions, web install and source install seam share it. Native devkit executable/runtime is preserved. Failed initial art application removes a newly created shortcut; no success with incomplete art.
• Refresh CLI/API/settings button repairs installed Android entries without reinstalling/stopping, uses cached source art, queries SGDB again if enabled, repairs missing shortcuts, and reports batch errors independently.
• Details: name/icon/VR flag, sort-as, Android/Android VR collections or native Sideloaded, Installation details note preserving other notes. No supported arbitrary description/store-page/developer/achievement metadata found. Notes are keyed by sanitized name (Steam limitation: equal-name collisions).
• Device discovery: custom-art type 4 is broken on this Steam client: it logs Unknown asset type and overwrites wide art with the icon. Use types 0–3 and SetShortcutIcon separately. Confirmed actual cache after correction.
• Launcher retains its supervising shell under Steam, traps TERM/INT/HUP, stops only its own container, kills its child group, preserves exit status. Lock/pre-existing container guards prevent duplicate session cleanup.
• VR attribution discovery: Lepton uses SteamAppId for both stable context and Android SteamVR identity. New shortcut.id + LEPTON_ENV_SteamAppId separates them using Lepton's existing passthrough; container/data paths unchanged. On-device source mounting.sh applies LEPTON_ENV_* after its regular setenv.

Visual critique and iterations

Evidence /tmp/vrlib-evidence/design-v1, design-v2, design-v3 (15 PNGs each). Open Saber Plus/SuperTux icons came from authorized APKs. AntennaPod is a preview only using the official F-Droid icon; it was not installed/launched.

1. v1: real typography/gradient already improves over old bitmap output, but Open Saber has a black square matte, and SuperTux palette looks muddy.
2. v2: removed connected black matte; rounded the opaque AntennaPod foreground. Inspected all three posters. SuperTux still muted; title line balance weak.
3. v3: lifted sampled saturation and balanced two-line labels. Inspected all three posters plus final all-slot sheet. Large recognisable artwork, readable typography, richer colours, textless hero and transparent title logo. Icon source resolution still limits detail; source/SGDB art remains preferable.

Final sheet /tmp/vrlib-evidence/artwork-preview-final.png is an artwork preview, NOT a Steam UI screenshot. Rows: portrait, wide, hero, logo/icon.

Device verification (2026-09-28, build 20260925.6191901, SteamVR 2.18.1)

Steam was initially unavailable (old notes/evidence), then recovered. Both APKs were reinstalled and refreshed successfully with zero library warnings:

• Open Saber Plus: org.godotengine.open_saber_plus, instance 2802929330, shortcut 3346865537, game ID 14374678025558032384.
• SuperTux: org.supertux.supertux2, instance 2811892472, shortcut 2883168793, game ID 12383115674816348160.

steam-cache-final.log: both actual Steam cache sets are 600x900, 920x430, 3840x1240, 1280x480, with app icon 256x256. steam-details-targets.json: both correct names/sort-as, Android + Android VR, existing Played preserved. Native managed note readback result 1 (success), saved as steam-notes-final.json.

Open Saber first session: Steam tracked it for 32 seconds; process and container remained alive until only SteamClient TerminateApp was called. After identity fix, a second session remained alive at 22 seconds (Android PID 992), SteamVR identified steam.app.3346865537, and screenshot shows the actual game scene instead of blank Resume tile. Steam Stop removed tracked process and container within ~5 seconds. No direct podman-stop fallback was used for this verification. Same data paths; existing game play count shown in capture, but no separate save-file sentinel added to the real game. Evidence: opensaber-identity-session.log, opensaber-identity-headset.png, opensaber-running.log, opensaber-steam-stop.log, opensaber-headset-running.png.

SuperTux: Steam Play tracked the wrapper for ~17 seconds. SDLClipboardHandler crashes with NullPointerException on missing ClipboardManager during activity creation. Lepton and supervisor then cleaned up; it never reached a VR scene. Steam Stop was issued after the crash, so sustained SuperTux Stop is NOT proven. Evidence: supertux-running.log, supertux-lepton.log, supertux-shot.json.

Other test activity appeared on the device during checks (other Android container and Gravitas). Neither was stopped or modified. Final Open Saber preflight had no Android containers; other desktop overlays later appeared in its headset capture. No global VR standby/dashboard settings changed. Direct Steam UI Page.captureScreenshot timed out; no library UI screenshot.

Automated verification and limits

• Whole suite: python3 -m unittest discover -s tests, Python 3.9.6. Final result: 206 tests OK, 10.294 seconds, exit 0. Log: /tmp/vrlib-evidence/tests-final.log.
• Offline entrypoint tests exercise real shared install/render/configure flow with SSH/API mocked: CLI, upload, catalogue, versions, web download, source seam, native title and refresh. Provider ranking/failure/settings tests.
• Node contract test runs actual renderer against explicitly synthetic canvas, validates all PNG dimensions and hero/logo text placement. This canvas is also used by fakeframe; transparent fixture images are not visual evidence.
• Launcher tests assert stable context plus shortcut passthrough, signals, normal exit, duplicate guard and saved-data sentinel. Earlier real Linux setsid/flock fixture run: 3 tests OK (linux-launcher-tests.log).
• bash -n, Node syntax checks, Python AST feature_version=(3,9), diff checks.
• Docker E2E not run: docker info --format '{{.ServerVersion}}' exits 1; daemon socket /var/run/docker.sock does not exist.
• Authenticated SGDB lookup/download unverified (no key configured).
• Windows/Linux packaged binaries not built/launched; filters tested.
• Native devkit art uses shared tested seam; no additional native title was installed on device. Sibling source-search endpoint not in this worktree: only its public installer contract is tested.
• Independent review not spawned: explicit brief forbids delegation and assigns parent review/integration. No other provider/model participation claimed.