feat: release v1.6.0 with virtual keyboard laser autofocus, SMB credentials, bookmarks overview, and 1-click updater

- Virtual Keyboard Laser Auto-Focus: vrcompositor laser mouse overlay configuration for instant typing without manual grip toggle; tracking persistence across session states
- Protected SMB Network Share Manager: in-browser 'Add Share' modal supporting multiple authenticated shares, AES-GCM credential encryption with strict 0600 file permissions, automatic credential lookup during streaming
- IPv4 Validation: numeric filtering, section clamping to 255, and stripping leading zeros
- Bookmarks Overview: renamed Quick Paths to Bookmarks with dedicated 'bookmarks://' overview panel, ASCII button labels replacing multi-byte glyphs
- 1-Click Seamless Updater: desktop shortcut for SteamOS Desktop Mode, standalone update.sh script, remote Wi-Fi PC updaters, and updated release documentation

.gitattributes

@@ -0,0 +1,10 @@
+# Force LF line endings for scripts and workflows so Linux/SteamOS execution never breaks
+*.sh text eol=lf
+*.py text eol=lf
+*.yml text eol=lf
+*.desktop text eol=lf
+*.bat text eol=crlf
+*.spv binary
+*.png binary
+*.jpg binary
+*.jpeg binary

.github/workflows/release.yml

@@ -37,6 +37,13 @@ jobs:
           ref: ${{ inputs.tag || github.ref }}
           fetch-depth: 1
 
+      - name: Check scripts
+        run: |
+          set -eux
+          sh -n tools/install.sh
+          bash -n tools/package-release.sh
+          bash -n tools/build.sh
+
       - name: Build
         run: bash tools/build.sh
 
@@ -44,21 +51,29 @@ jobs:
         run: |
           set -eux
           tag="${{ inputs.tag || github.ref_name }}"
-          bash tools/package-release.sh build pixelvr-linux-arm64.tar.gz
+          bash tools/package-release.sh build pixelvr-linux-arm64.tar.gz "${tag}"
           cp pixelvr-linux-arm64.tar.gz "pixelvr-linux-arm64-${tag}.tar.gz"
+          sha256sum pixelvr-linux-arm64.tar.gz > pixelvr-linux-arm64.tar.gz.sha256
+          sha256sum "pixelvr-linux-arm64-${tag}.tar.gz" > "pixelvr-linux-arm64-${tag}.tar.gz.sha256"
 
       - name: Verify artifact
         run: |
           file build/bin/pixelvr
           file build/bin/pixelvr | grep -q 'ARM aarch64'
           tar -tzf pixelvr-linux-arm64.tar.gz | grep -q '^PixelVRPlayer/run.sh$'
+          tar -tzf pixelvr-linux-arm64.tar.gz | grep -q '^PixelVRPlayer/install.sh$'
+          tar -tzf pixelvr-linux-arm64.tar.gz | grep -q '^PixelVRPlayer/VERSION$'
           tar -tzf pixelvr-linux-arm64.tar.gz | grep -q '/shaders/thumb.frag.spv$'
+          sha256sum -c pixelvr-linux-arm64.tar.gz.sha256
 
       - name: Upload build artifact
         uses: actions/upload-artifact@v4
         with:
           name: pixelvr-linux-arm64
-          path: pixelvr-linux-arm64-*.tar.gz
+          path: |
+            pixelvr-linux-arm64.tar.gz
+            pixelvr-linux-arm64.tar.gz.sha256
+            pixelvr-linux-arm64-v*.tar.gz
 
       - name: Publish GitHub release
         if: startsWith(github.ref, 'refs/tags/v') || inputs.tag != ''
@@ -68,4 +83,6 @@ jobs:
           generate_release_notes: true
           files: |
             pixelvr-linux-arm64.tar.gz
+            pixelvr-linux-arm64.tar.gz.sha256
             pixelvr-linux-arm64-v*.tar.gz
+            pixelvr-linux-arm64-v*.tar.gz.sha256

.gitignore

@@ -42,3 +42,8 @@ Thumbs.db
 # Local secrets / device config
 /local.env
 /secrets/
+/scratch/
+/test_vault
+/*-plan.md
+/test_*.cpp
+/protected-*.md

CMakeLists.txt

@@ -122,14 +122,18 @@ add_library(pixelvr_core STATIC
     src/xr/xr_result.cpp
     src/xr/xr_context.cpp
     src/xr/render_model.cpp
+    src/xr/vr_keyboard.cpp
+    src/net/smb_credentials.cpp
     src/gfx/vulkan_renderer.cpp
     src/gfx/gltf_mesh.cpp
     src/ui/settings_menu.cpp
     src/ui/thumbnail_cache.cpp
+    src/app/vault_manager.cpp
     src/app/app.cpp)
 
 target_include_directories(pixelvr_core PUBLIC
-    "${CMAKE_CURRENT_SOURCE_DIR}/src")
+    "${CMAKE_CURRENT_SOURCE_DIR}/src"
+    "${CMAKE_CURRENT_SOURCE_DIR}/third_party/openvr")
 target_include_directories(pixelvr_core PRIVATE "${cgltf_SOURCE_DIR}" "${stb_SOURCE_DIR}")
 
 target_compile_definitions(pixelvr_core PUBLIC
@@ -140,7 +144,8 @@ target_compile_definitions(pixelvr_core PUBLIC
 target_link_libraries(pixelvr_core PUBLIC
     OpenXR::openxr_loader
     Vulkan::Vulkan
-    Threads::Threads)
+    Threads::Threads
+    ${CMAKE_DL_LIBS})
 
 add_dependencies(pixelvr_core pixelvr_shaders)
 

README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/hero.png" width="100%" alt="Pixel VR Player" />
+</p>
+
 # Pixel VR Player
 
 A native VR video player for the **Valve Steam Frame**, playing flat 2D, 180°, and
@@ -13,26 +17,81 @@ A native VR video player for the **Valve Steam Frame**, playing flat 2D, 180°,
 > NV12) with zero-copy dma-buf import; flat / 180° / 360° projection and mono /
 > SBS (including half-SBS) / TB stereo, auto-detected from the filename; spatial
 > audio with a master clock. In-headset UI: file browser (with file type and
-> size), transport bar, settings menu, and a downloads manager. Native Valve
+> size), transport bar, settings menu, downloads manager, bookmarks overview,
+> protected SMB network share manager with virtual keyboard laser auto-focus,
+> and an encrypted hidden vault. Native Valve
 > Steam Frame controller support (`XR_VALVE_frame_controller_interaction`) using
 > the runtime's own render model, with per-button animation on the model and
 > press-to-bind remapping.
 
-## Install (prebuilt release)
+## Screenshots
 
-Download `pixelvr-linux-arm64.tar.gz` from the
-[Releases](../../releases) page and copy it to your Steam Frame, then:
+<p align="center">
+  <img src="docs/ui-redesign/mockup-unified-1-files.jpg" width="49%" alt="Spatial File Browser" />
+  <img src="docs/ui-redesign/mockup-unified-2-downloads.jpg" width="49%" alt="Downloads Manager" />
+</p>
+<p align="center">
+  <img src="docs/ui-redesign/mockup-unified-3-settings.jpg" width="49%" alt="Settings Panel" />
+  <img src="docs/ui-redesign/mockup-unified-4-cinema-hud.jpg" width="49%" alt="Cinema Playback HUD" />
+</p>
+
+## Installation
+
+Choose whichever method fits your setup:
+
+### Option A: USB Drive / MicroSD Card (No typing & No Dev Mode needed)
+
+The simplest method for standard users without touching the terminal:
+
+1. Download `pixelvr-linux-arm64.tar.gz` from the [Releases](https://github.com/Pixelplanet/Pixel-VR-Player/releases) page onto a USB flash drive or MicroSD card.
+2. Plug it into your Steam Frame and switch to **Desktop Mode**.
+3. Open the USB drive in Dolphin and double-click **`Install Pixel VR Player.desktop`**.
+4. A confirmation dialog will appear when finished. Return to Gaming Mode and launch it directly from your Steam Library!
+
+### Option B: One command in headset terminal
+
+If you are already in Desktop Mode on the Steam Frame, open **Konsole** and paste:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Pixelplanet/Pixel-VR-Player/main/tools/install.sh | sh
+```
+
+*(No root access or disabled read-only filesystem needed; it installs entirely into user space).*
+
+### Option C: From your PC over Wi-Fi (Requires SSH or Dev Mode)
+
+If you have SSH enabled or Developer Mode turned on with your headset paired:
+
+- **Windows:** Double-click [`tools/install-from-pc.bat`](tools/install-from-pc.bat) and enter your headset's IP.
+- **macOS / Linux:** Run `./tools/install-from-pc.sh`.
+
+The script connects over SSH, installs the app, and registers the Steam shortcut remotely.
+
+Launch **Pixel VR Player** directly from your Steam library, or from terminal:
 
 ```bash
-tar -xzf pixelvr-linux-arm64.tar.gz -C ~
-chmod +x ~/PixelVRPlayer/run.sh
 ~/PixelVRPlayer/run.sh                 # opens the in-headset file browser
 ~/PixelVRPlayer/run.sh /path/clip.mp4  # …or auto-play a specific clip
 ```
 
-To launch it from the headset library, add `~/PixelVRPlayer/run.sh` as a
-**Non-Steam Game** (Steam ▸ Add a Non-Steam Game). SteamVR must be running; the
-app logs to `~/pixelvr-run.log`.
+Installer options:
+
+| Option | Effect |
+| --- | --- |
+| `--dir DIR` | install somewhere other than `~/PixelVRPlayer` |
+| `--version vX.Y.Z` | install a specific release instead of the latest |
+| `--no-steam` | skip the Steam library entry |
+| `--restart-steam` | close Steam first, then reopen it so the entry appears at once |
+| `--uninstall` | remove the app and its Steam shortcut |
+
+Re-run the same command to upgrade. Settings (`~/.config/pixelvr`), cached
+thumbnails (`~/.cache/pixelvr`), and hidden vault media (`~/.pixelvr_vault`) live
+outside the install directory and are kept intact.
+
+**Offline install:** download `pixelvr-linux-arm64.tar.gz` from the
+[Releases](https://github.com/Pixelplanet/Pixel-VR-Player/releases) page, copy it to the headset, extract it and run
+`./install.sh` from the extracted folder — or use `run.sh` directly. The app logs
+to `~/pixelvr-run.log`.
 
 Requirements: the SteamVR OpenXR runtime (SteamOS), Vulkan, and FFmpeg with the
 V4L2 M2M decoders. For zero-copy dma-buf decoding, build the patched FFmpeg into
@@ -40,6 +99,92 @@ V4L2 M2M decoders. For zero-copy dma-buf decoding, build the patched FFmpeg into
 back to the system FFmpeg with CPU colour conversion.
 
 
+## Updating
+
+Updating Pixel VR Player is seamless, fast, and 100% non-destructive.
+
+> [!NOTE]
+> **Your data is always preserved!**  
+> All user preferences (`~/.config/pixelvr/config.json`), saved SMB network shares and credentials (`~/.config/pixelvr/smb_shares.json`), quick bookmarks (`~/.config/pixelvr/bookmarks.json`), cached video thumbnails (`~/.cache/pixelvr`), and encrypted media in the Discreet Vault (`~/.pixelvr_vault`) are stored outside the application folder and remain completely untouched across updates.
+
+Choose your preferred update method:
+
+### Method 1: 1-Click Desktop Update (Easiest on Headset)
+
+No terminal or typing required:
+1. Switch your Steam Frame to **Desktop Mode** (Power menu in SteamVR or SteamOS).
+2. Double-click the **`Update Pixel VR Player`** icon on your Desktop.
+3. A popup will notify you that the update has started. The updater verifies SHA-256 checksums and updates the app in-place.
+4. When finished, a completion notification will appear. Switch back to Gaming Mode and launch the player!
+
+*(Alternatively, open Dolphin file manager, navigate to `~/PixelVRPlayer`, and double-click `update.sh`)*.
+
+### Method 2: 1-Click Update from your PC over Wi-Fi
+
+Update your headset remotely over your local network:
+- **Windows:** Double-click [`tools/update-from-pc.bat`](tools/update-from-pc.bat), enter your Steam Frame's IP address, and press Enter.
+- **macOS / Linux:** Run `./tools/update-from-pc.sh <headset-ip>`.
+
+### Method 3: One Command in Headset Terminal (Konsole / SSH)
+
+Open **Konsole** on the headset or connect via SSH, then run:
+
+```bash
+~/PixelVRPlayer/update.sh
+```
+
+Or re-run the web installer command:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Pixelplanet/Pixel-VR-Player/main/tools/install.sh | sh
+```
+
+### Method 4: USB Drive / MicroSD Card (Offline)
+
+1. Download `pixelvr-linux-arm64.tar.gz` from the [Releases](https://github.com/Pixelplanet/Pixel-VR-Player/releases) page to a USB flash drive or MicroSD card.
+2. Plug it into your Steam Frame and open it in Desktop Mode.
+3. Double-click **`Install Pixel VR Player.desktop`** (or run `./install.sh --update` from the unpacked folder).
+
+
+## Uninstallation
+
+To remove Pixel VR Player and its Steam shortcut from your Steam Frame:
+
+### From the Headset (Desktop Mode / Konsole or SSH)
+
+Run the uninstaller script directly:
+
+```bash
+~/PixelVRPlayer/install.sh --uninstall
+```
+
+Or run the one-command uninstaller:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Pixelplanet/Pixel-VR-Player/main/tools/install.sh | sh -s -- --uninstall
+```
+
+This cleanly removes:
+* The application folder (`~/PixelVRPlayer`)
+* The Non-Steam Game shortcut from Steam's library (`shortcuts.vdf`)
+* All custom Steam grid artwork from `~/.steam/steam/userdata/*/config/grid/`
+
+### From your PC over Wi-Fi
+
+- **Windows:** Double-click [`tools/uninstall-from-pc.bat`](tools/uninstall-from-pc.bat) and enter your headset's IP.
+- **macOS / Linux:** Run `./tools/uninstall-from-pc.sh`.
+
+### Complete Data Purge (Optional)
+
+By default, user settings (`~/.config/pixelvr`), cached video thumbnails (`~/.cache/pixelvr`), and hidden vault media (`~/.pixelvr_vault`) are kept intact so upgrading or reinstalling never loses your library state.
+
+To completely erase all application data and settings from the headset, run:
+
+```bash
+rm -rf ~/.config/pixelvr ~/.cache/pixelvr ~/.pixelvr_vault
+```
+
+
 ## Controls
 
 The laser pointer and the control bar are **separate** input paths, so the bar
@@ -64,6 +209,39 @@ the file browser rather than stacking on top of it.
 All button bindings can be changed in **Settings ▸ Controls** (press-to-bind).
 
 
+## Discreet Media Vault
+
+Pixel VR Player includes a private, zero-trace local storage vault (`~/.pixelvr_vault`) hidden from the standard file browser and startup directory scans.
+
+<details>
+<summary>🔒 <b>Accessing the Hidden Vault</b> (click to expand)</summary>
+
+To open or re-lock the vault in VR without bringing up an on-screen keyboard or visible PIN dialog:
+
+1. Fully squeeze either controller's **grip** (hold down the mechanical **Full Press** click).
+2. While holding the grip clicked, enter the 6-key factory combination:
+
+> 🎵 *The Swedish pop sensation that won Eurovision in 1974 with "Waterloo"...*  
+> 📐 *...followed by the two classic axes of the 2D Cartesian plane.*
+
+<details>
+<summary>👉 <i>Need the direct button sequence? Click here to reveal</i></summary>
+
+Hold **Full Grip Click** and press:
+> **`A` → `B` → `B` → `A` → `X` → `Y`**  
+*(Within 2.5 seconds per step. Haptic feedback confirms each input).*
+
+</details>
+
+- **Instant Auto-Lock:** Re-locks automatically and immediately purges in-memory textures when the headset proximity sensor detects removal, or when clicking **[ 🔒 Lock Vault ]** in the sidebar.
+- **Custom Combinations:** You can record your own custom button sequence anytime in **Settings ▸ Vault & Privacy**.
+- **Move to Vault:** While unlocked, local videos can be moved directly into the vault from the browser.
+- **Safe Persistence:** Media inside `~/.pixelvr_vault` is never deleted when updating or uninstalling the app.
+
+For full architecture and security details, see the [Hidden Vault Technical Specification](docs/HIDDEN_VAULT_SPEC.md).
+</details>
+
+
 ## Repository layout
 
 ```
@@ -173,8 +351,7 @@ choice, and troubleshooting). In short, after a one-time Developer-Mode pairing:
   # override the target with --host steamos@<ip> or FRAME_HOST
   ```
 
-Either way the app appears in **Steam ▸ Library ▸ Non-Steam** as *Devkit Game:
-PixelVRPlayer*. To run it manually over SSH for debugging:
+Either way the app appears in **Steam ▸ Library ▸ Non-Steam** as **Pixel VR Player**. To run it manually over SSH for debugging:
 
 ```bash
 ssh steamos@frame '~/devkit-game/PixelVRPlayer/launch.sh /path/to/video.mp4'

TODO.md

@@ -7,19 +7,71 @@
 
 ---
 
-## Active backlog (2026-10-14)
+## Active backlog (2026-10-19 — Completed)
+
+- [x] **1. Fix Virtual Keyboard Laser Pointer Focus & Tracking**
+  - **Symptom:** Virtual keyboard opened, but laser pointer disappeared or wasn't focused on the keyboard; user had to squeeze/press the controller grip fully to activate it.
+  - **Root Cause:**
+    - SteamVR's `vrcompositor` switches system panel interaction mode to Gamepad (mode 0, hiding `system.pointer`) on session focus loss unless an interactive overlay requiring laser mouse is currently visible (`bOverlaysPresentThatForceLaserMouseOn`).
+    - `inputOverlay_` was created in `VrKeyboard::init()` but was **never shown** (`ShowOverlay` was never called, had no texture, dimensions, or transform).
+    - SteamVR's virtual keyboard overlay `valve.steam.gamepadui.keyboard` is spawned asynchronously and lacks `MakeOverlaysInteractiveIfVisible` by default.
+  - **Resolution:**
+    - Fully configured `inputOverlay_` in `VrKeyboard::show()`: set width (1.0m), HMD-relative transform (1.1m in front, tilted), 1x1 transparent raw pixel texture (`SetOverlayRaw`), and docked keyboard position (`SetKeyboardPositionForOverlay`).
+    - Called `ov->ShowOverlay(inputOverlay_)` before calling `ShowKeyboardForOverlay`, ensuring `vrcompositor`'s overlay scan sets `m_bOverlaysPresentThatForceLaserMouseOn = 1`.
+    - Added dynamic polling in `VrKeyboard::poll()` to detect and configure `MakeOverlaysInteractiveIfVisible` and `VROverlayInputMethod_Mouse` on `valve.steam.gamepadui.keyboard` as soon as it appears.
+    - Added proper overlay cleanup (`HideOverlay(inputOverlay_)`) in `hide()`, `KeyboardDone`, and `KeyboardClosed`.
+
+- [x] **2. Strict IPv4 Validation & Live Sanitization**
+  - **Symptom:** Host field accepted invalid characters, spaces, and did not strip leading zeros.
+  - **Resolution:**
+    - Created `src/util/ipv4.hpp` with `sanitizeIpv4()` and `isValidIpv4()`.
+    - Live typing sanitization: automatically strips non-digits/dots, discards duplicate dots, clamps octets to 255, drops leading zeros in each octet (e.g. `001` -> `1`, `010` -> `10`, `00` -> `0`), limits to 4 octets, and preserves trailing dots while typing.
+    - Added automated unit test suite `tests/test_ipv4.cpp` and verified all test cases pass on the device.
+    - Verified strict `isValidIpv4()` validation before saving an SMB share in `saveSmbModal()`.
+
+- [x] **3. Fix `???` Glyphs (Unicode Star Elimination)**
+  - **Symptom:** Sidebar and header button displayed `???` instead of the star icon.
+  - **Root Cause:** FreeType SDF text atlas was initialized only for ASCII codepoints 32..127. UTF-8 multi-byte sequence `★` (`\xe2\x98\x85`) produced 3 replacement `?` characters.
+  - **Resolution:** Replaced all UTF-8 star glyphs with clean ASCII strings: `"Bookmarks"`, `"[ Bookmarked ]"`, and `"[ + Bookmark ]"`. Adjusted header breadcrumb max width to `0.46f` to prevent collision with the header button.
+
+- [x] **4. Rename Quick Path to Bookmarks & Implement Multi-Bookmark Overview (`bookmarks://`)**
+  - **Requirement:** Rename Quick Path to Bookmarks, and have the Bookmarks sidebar tab open an overview showing all bookmarked folders and files in regular browser views.
+  - **Resolution:**
+    - Added `Bookmark` struct and multi-bookmark storage in `Browser` with persistent JSON serialization to `~/.config/pixelvr/bookmarks.json`.
+    - Implemented `bookmarks://` virtual directory navigation displaying all bookmarked paths with full cards (BigCards, MiniCards) and CompactList support, thumbnails, and direct activation.
+    - Sidebar subtab 4 navigates to `bookmarks://` with proper active tab highlighting.
+    - Header button toggles bookmark for the current open directory (`[ + Bookmark ]` / `[ Bookmarked ]`).
+    - Action Menu (Y button) provides `"Add to Bookmarks"` / `"Remove from Bookmarks"` / `"Go to Bookmarks"`, and in `bookmarks://` provides `"Open Bookmark"` / `"Remove Bookmark"`.
+    - Updated Settings Menu shortcut label to `"Bookmarks Shortcut"`.
+
+- [x] **5. Seamless 1-Click Update System & Streamlined Distribution**
+  - **Requirement:** Provide easy, friction-free updating so users do not need to memorize terminal commands or worry about losing their settings.
+  - **Resolution:**
+    - Added standalone local updater `tools/update.sh` and `--update` flag to `tools/install.sh`.
+    - Added KDE Plasma `Update Pixel VR Player.desktop` desktop shortcut deployed automatically to `~/Desktop/`.
+    - Added remote Wi-Fi 1-click updaters for PC users (`tools/update-from-pc.bat` for Windows and `tools/update-from-pc.sh` for macOS/Linux).
+    - Updated `tools/package-release.sh` to package updater scripts in the release tarball.
+    - Updated `README.md` with comprehensive update instructions across all platforms.
+
+
+---
+
+## Carried over & Completed
 
-Carried over:
 - [ ] A. Full-pitch recenter (usable lying down) — reorient screen + controls + 360/180 to full head orientation, not just horizon yaw.
 - [ ] B. Real controller models (glTF) rendered with depth.
 - [ ] C. Dynamic controller button labels from the user's bindings.
 
-New (2026-10-14):
-- [x] D. Flat SBS/TB: detect + a working flat-stereo render mode (split per eye).
-- [x] E. Settings split into sections.
-- [x] F. Settings: pick video stream, audio stream, and a default audio language.
-- [ ] G. Downloads view: active downloads + speed + ETA; keep running in background.
-- [x] H. Sharper menu text (SDF).
+Completed (2026-10-18):
+- [x] I. Laser auto-release when pressing Steam button (unfocused session gates controller pointer).
+- [x] J. Native SteamVR / SteamOS Virtual Keyboard integration (OpenVR GamepadTextInput via dlopen).
+- [x] K. Protected SMB credentials manager: hardware-keyed AES-GCM encryption, strict permissions, full CRUD.
+- [x] L. Settings > Network & SMB Shares: manual IP/hostname input, authentication settings, auto-listed in Network browser.
+- [x] M. UI Follow Mode: Mode 0 (Rock-solid World Lock default, zero drift/tilt) and Mode 1 (Smooth Follow).
+- [x] N. Player UI dismissal: `[ ✕ Hide ]` button, empty space click-outside dismissal, B/Y toggle, and micro-tremor filtering (>0.06m threshold).
+- [x] O. Quick Path Whirligig-style bookmarking header button + R3 controller shortcut button.
+
+
 
 ---
 

docs/HIDDEN_VAULT_SPEC.md

@@ -0,0 +1,124 @@
+# PixelVR Hidden Vault: Technical Specification & Architecture
+
+## 1. Overview & Core Objectives
+
+The **Hidden Vault** provides a private, zero-trace media storage and viewing capability within PixelVR Player. It allows users to store and view sensitive or private videos without virtual keyboard input, PIN dialogs, or visible hints in the default user interface.
+
+### Key Requirements
+* **Zero Keyboard Input:** Unlocks strictly through a physical controller combination.
+* **Invisible by Default:** The vault directory (`~/.pixelvr_vault/`) is excluded from all directory scans on startup and cold boot.
+* **Discrete Full Press Squeeze:** Squeeze has two separate functions: *Soft Squeeze* (analog) and *Full Press* (discrete click). The combo operates **exclusively** on Full Press.
+* **Re-Lock Control:** When unlocked, a dedicated `[ 🔒 Lock Vault ]` button appears in the sidebar. It is completely absent when locked.
+* **Move to Vault:** Downloaded/local media can be moved into the vault when unlocked, using a button binding configured in the Vault Settings tab.
+* **Strict Privacy Isolation:** Thumbnails and memory textures for vault media are purged immediately upon re-locking.
+
+---
+
+## 2. Discrete Grip Architecture: Soft Squeeze vs. Full Press
+
+Modern VR controllers (Valve Frame, Valve Index, Oculus/Meta Touch) provide two separate functional signals for controller grip:
+
+```mermaid
+flowchart LR
+    subgraph "Controller Hardware"
+        GripSensor["Grip Sensor"]
+    end
+
+    subgraph "OpenXR Functional Pathways"
+        GripSensor -->|"Gentle / Resting Hold"| SoftSqueeze["Soft Squeeze<br>(/input/squeeze/value)<br>Analog Float (0.0 .. 1.0)"]
+        GripSensor -->|"Mechanical Click / Bottom-Out"| FullPress["Full Press<br>(/input/squeeze/click)<br>Discrete Boolean Click"]
+    end
+
+    subgraph "PixelVR Input Dispatch"
+        SoftSqueeze -->|"Used for Laser Toggle / Holding"| NormalInput["Standard Input Handling<br>(Ignored by Vault)"]
+        FullPress -->|"Prerequisite for Combo"| ComboDetector["Vault Combo State Machine<br>(A-B-B-A-X-Y)"]
+    end
+```
+
+### Hardware Functional Separation
+1. **Soft Squeeze (`/input/squeeze/value`):**
+   * Continuous analog range ($0.0 \dots 1.0$).
+   * Triggered whenever fingers rest casually on the controller or squeeze lightly.
+   * **Behavior:** Completely disregarded by the Vault combo detector. A user can squeeze or hold the controller at any pressure without accidentally arming the combo.
+2. **Full Press (`/input/squeeze/click` or `/input/grip/click`):**
+   * Discrete boolean action representing the physical bottom-out or tactile click of the grip mechanism.
+   * **Behavior:** Required as the continuous hold prerequisite for the combo state machine. The user must intentionally bottom out the grip to enter the code.
+
+---
+
+## 3. Unlock Sequence & Combo State Machine
+
+### 3.1 Default Sequence
+$$\text{Grip Full Press (Held)} + [\text{BtnA} \rightarrow \text{BtnB} \rightarrow \text{BtnB} \rightarrow \text{BtnA} \rightarrow \text{BtnX} \rightarrow \text{BtnY}]$$
+
+### 3.2 State Machine Rules
+* **Sliding Timeout:** 2.5 seconds between button presses. If no button is pressed within 2.5 seconds, or if the grip Full Press is released before completion, the buffer resets to empty.
+* **Wrong Button Penalty:** An incorrect button immediately clears the buffer.
+* **Input Interception:** While `gripFullPressHeld` is true, face button presses (`A`, `B`, `X`, `Y`) are consumed exclusively by the combo detector. They are **suppressed from normal UI actions** (play/pause, back/close, download), preventing accidental interaction with the background player while entering the code.
+* **Haptic Feedback:**
+  * Valid sequence step: subtle 10ms click vibration.
+  * Successful Unlock / Lock: distinct 60ms double pulse.
+
+---
+
+## 4. UI States & Spatial Navigation
+
+### 4.1 State: LOCKED (Default State on Launch)
+* The vault directory `~/.pixelvr_vault/` is excluded from all directory enumerations in `Browser::scanLocalInto()`.
+* The sidebar navigation rail contains standard entries only (`Local Storage`, `Videos`, `SMB Shares`, `Downloads`).
+* The `[ 🔒 Lock Vault ]` button is completely omitted from the layout.
+* The Settings menu displays standard 4 tabs (`Display`, `Controls`, `Audio`, `System`).
+
+### 4.2 State: UNLOCKED
+* **Navigation Rail:** A glowing `[ 🔒 Vault ]` shortcut appears under Library categories. Clicking it opens `~/.pixelvr_vault/` in the 3x2 media grid.
+* **Re-Lock Button:** A prominent `[ 🔒 Lock Vault ]` button appears in the sidebar.
+* **Settings:** A 5th tab appears: **`Vault & Privacy`**.
+* **Re-locking Actions:** Clicking the lock button (or repeating the combo):
+  1. Stops any currently playing video if its path is within `~/.pixelvr_vault/` and calls `renderer_.clearVideo()`.
+  2. Resets the file browser immediately to `Home` (`openHome()`).
+  3. Purges all in-memory thumbnail cache entries and GPU card textures for vault files.
+  4. Hides the `[ 🔒 Vault ]` shortcut, `[ 🔒 Lock Vault ]` button, and the `Vault & Privacy` settings tab.
+
+---
+
+## 5. "Move to Vault" File Management Engine
+
+To allow seamless transfer of downloaded videos into the vault without using desktop file managers:
+
+1. **Availability:** The move feature is active **only when the vault is unlocked** and **only for downloaded / local files** (SMB files cannot be moved directly; they must be downloaded first).
+2. **Dedicated Button Binding:** Configured inside the **Vault & Privacy** settings tab (e.g. `X`, `Y`, `Left Stick Click`, or `None`), independent of regular playback control bindings.
+3. **Robust Move Implementation:**
+   * Primary: `std::filesystem::rename(src, dest)`.
+   * Cross-device fallback: If `rename()` fails with `EXDEV` (e.g. moving from a MicroSD card or external drive on `/run/media/...` to internal storage `~/.pixelvr_vault/`), the engine automatically performs `std::filesystem::copy_file(src, dest)` followed by `std::filesystem::remove(src)`.
+4. **Collision Handling:** If `~/.pixelvr_vault/video.mp4` already exists, the destination is automatically renamed to `video_1.mp4`.
+5. **Cache Eviction:** Any public preview file previously generated in `~/.cache/pixelvr/thumbnails/` for the original path is deleted immediately upon moving.
+
+---
+
+## 6. Dynamic "Vault & Privacy" Settings Tab
+
+When the vault is unlocked, a 5th tab becomes available in the Settings menu:
+
+| Setting | Options | Default | Description |
+|---|---|---|---|
+| **Auto-Lock on Headset Off** | `[Enabled / Disabled]` | `Enabled` | Instantly locks the vault when headset proximity/focus is lost |
+| **Inactivity Auto-Lock** | `[Disabled, 2m, 5m, 10m]` | `5 min` | Automatically locks if no controller input is detected |
+| **Move to Vault Button** | `[X, Y, Stick Click, None]` | `Button X` | Physical button to move focused local file to vault |
+| **Custom Combo Sequence** | `[Configure / Record]` | `A B B A X Y` | Records a custom 6-button sequence |
+| **Lock Vault Now** | Action Button | — | Manually locks the vault immediately |
+
+*Settings are persisted in `~/.config/pixelvr/pixelvr.conf` under the `[vault]` section.*
+
+---
+
+## 7. Edge Cases & Mitigation Matrix
+
+| Edge Case | Failure Mode / Risk | Architectural Mitigation |
+|---|---|---|
+| **Accidental Soft Squeeze** | Resting fingers squeeze grip slightly and start recording combo inputs. | **Hardware Function Separation:** Only the discrete `Full Press` (`squeeze/click`) arms the combo. The analog `Soft Squeeze` (`squeeze/value`) is completely ignored. |
+| **Normal Button Contamination** | Pressing `A B B A X Y` pauses video or starts downloads. | Face button events are suppressed from the UI while `gripFullPressHeld` is true. |
+| **Cross-Filesystem Moves** | Moving a file from a MicroSD card to internal storage fails with `EXDEV`. | Automatic fallback from `rename()` to `copy_file()` + `remove()`. |
+| **Name Collisions** | Moving `clip.mp4` when `~/.pixelvr_vault/clip.mp4` already exists. | Target automatically becomes `clip_1.mp4` to prevent data loss. |
+| **Thumbnail Leakage** | Public thumbnail remains in shared cache after moving video to vault. | Old public thumbnail is deleted upon move; vault previews are stored only in `~/.pixelvr_vault/.thumbs/`. |
+| **Active Video on Lock** | Video from vault is playing when headset is removed or lock button is clicked. | Playback engine calls `media_.close()` and `renderer_.clearVideo()` immediately so no private frame lingers. |
+| **Headset Sleep / SteamVR Menu** | User presses SteamVR system button or takes off headset. | OpenXR session state loss (`XR_SESSION_STATE_VISIBLE` or `FOCUSED` lost) triggers immediate lock and resets to Home. |

docs/concepts/HIDDEN_VAULT_CONCEPT.md

@@ -0,0 +1,161 @@
+# PixelVR Hidden Vault: Architectural Concept & Design Proposals
+
+## 1. Executive Summary & Objective
+
+The objective is to provide a frictionless, privacy-focused **Hidden Vault** feature in PixelVR Player for confidential/private media files without requiring a virtual keyboard or password prompt. Virtual keyboard entry in VR is notoriously cumbersome, immersion-breaking, and vulnerable to "shoulder surfing" (people watching the VR mirror window on a PC or TV screen).
+
+### Core Requirements
+1. **Zero Keyboard Input:** Unlock mechanism must use physical VR controller interactions or spatial UI patterns.
+2. **Locked & Hidden by Default:** On app launch and cold restart, the folder and all its contents are completely invisible and unlisted.
+3. **Explicit Re-Lock Control:** Once unlocked, a visible "Lock Vault" / "Hide" button appears in the UI. When locked, this button vanishes completely.
+4. **Thumbnail & Cache Privacy:** Thumbnails and metadata of private videos must never leak into shared/public system caches or stay resident in GPU memory when locked.
+5. **No Clues in Default UI:** The default UI must not look like anything is missing or locked (no "Enter PIN to access Vault" prompt).
+
+---
+
+## 2. Comparative Analysis of Unlock Mechanisms
+
+We have developed three distinct non-keyboard unlock concepts tailored for spatial computing, each with unique trade-offs in stealth, speed, and ergonomics.
+
+```mermaid
+flowchart TD
+    subgraph "Unlock Mechanisms"
+        M1["Method 1: Cheat Code<br>(Grip + Face Button Combo)"]
+        M2["Method 2: Spatial Corner Tap<br>(Hidden Hitboxes on Panel)"]
+        M3["Method 3: Dual-Stick Chord<br>(Simultaneous Analog Directions)"]
+    end
+
+    subgraph "Vault Lifecycle"
+        LockedState["State: LOCKED (Default)<br>- Zero UI trace<br>- Path unlisted"]
+        UnlockedState["State: UNLOCKED<br>- 'Vault' in Sidebar<br>- 'Lock' Button Visible"]
+    end
+
+    M1 -->|Sequence Match| UnlockedState
+    M2 -->|Sequence Match| UnlockedState
+    M3 -->|Chord Match| UnlockedState
+    UnlockedState -->|Click Lock Button / Combo / Sleep| LockedState
+```
+
+---
+
+### Method 1: The "Controller Cheat Code" (Grip + Button Sequence) ⭐ Recommended
+
+*Inspired by classic gaming cheat codes (e.g., Konami Code), adapted for VR motion controllers.*
+
+- **How It Works:**
+  1. The user holds down one of the controller grips fully (e.g., **Left Grip held > 75%**).
+  2. While the grip is held, the user enters a short 4-button sequence using the face buttons on either controller (e.g. `X -> Y -> B -> A` or `X -> X -> Y -> Y`).
+  3. A 2.5-second sliding timeout window resets the buffer if a pause occurs or an incorrect button is pressed.
+  4. On successful sequence: A subtle double-haptic vibration buzzes in the controller, and the Vault immediately unlocks.
+- **Stealth Level:** **Maximum (5/5)**.
+  - To anyone watching the player in real life or viewing the desktop mirror window, the player’s hands remain completely stationary. No laser beams move, no UI buttons highlight.
+- **Speed & Ergonomics:** Takes **under 1 second** to perform. Natural finger resting positions on Steam Frame / Quest / Index controllers.
+- **False-Positive Prevention:** Because a grip must be held continuously while a distinct button sequence is pressed, normal navigation (which uses single clicks of A, B, X, Y without holding grips) will never accidentally unlock the vault.
+
+---
+
+### Method 2: The "Secret UI Corner Pattern" (Spatial Easter Egg)
+
+*Inspired by mobile OS developer-mode unlocking (e.g. tapping Android build number 7 times) and pattern locks.*
+
+- **How It Works:**
+  - The 1.8m x 1.12m Unified Spatial Hub floating panel has 4 invisible hit targets (5cm x 5cm) positioned at its four outer corners:
+    - `[TL]` Top-Left
+    - `[TR]` Top-Right
+    - `[BR]` Bottom-Right
+    - `[BL]` Bottom-Left
+  - The user points the laser and clicks the trigger in a predefined sequence:
+    - *Example Sequence:* `[TL] -> [TR] -> [BR] -> [TL]`.
+    - *Alternative (Logo Multi-Tap):* Quadruple-clicking the "PIXEL VR" brand logo in the left navigation rail within 1.5 seconds.
+- **Stealth Level:** **Moderate (3/5)**.
+  - An observer watching the desktop mirror might see the laser pointer flick to the corners. However, to someone in the physical room, it looks like normal browsing.
+- **Speed & Ergonomics:** Takes 2–3 seconds. Only requires one hand and the laser pointer.
+- **Pros:** Very discoverable and intuitive once known; no button memorization required.
+
+---
+
+### Method 3: The "Dual-Stick Analog Chord" (Physical Key Turn)
+
+*Inspired by physical safe dials.*
+
+- **How It Works:**
+  - The user deflects both thumbsticks outward simultaneously (Left Stick pushed fully Left $\leftarrow$, Right Stick pushed fully Right $\rightarrow$) and clicks both stick buttons (L3 + R3) or pulls both triggers.
+- **Stealth Level:** **Maximum (5/5)**.
+  - Completely invisible on screen mirrors.
+- **Speed & Ergonomics:** Near-instantaneous (0.5s).
+- **Cons:** Less sequence flexibility (can only be binary rather than a multi-step combination).
+
+---
+
+## 3. Recommended Hybrid Approach
+
+We recommend implementing **Method 1 (Grip + Button Sequence)** as the primary unlock mechanism, with an optional fallback to **Method 2 (Logo Multi-Tap)** for maximum accessibility:
+
+1. **Primary Combo:** Hold **Left Grip** + Press `X -> Y -> B -> A`.
+2. **Alternative Laser Gesture:** 4 rapid trigger clicks on the **"PIXEL VR" Logo** in the top-left rail.
+3. **Emergency Quick-Lock:** Repeating the combo from anywhere (even during full-screen video playback) immediately locks the vault and stops any private video currently playing.
+
+---
+
+## 4. UI Architecture & Presentation
+
+### State 1: Locked (Default State)
+- **Files View:** Only normal directories (`Videos`, `Downloads`, `SMB Shares`, external drives) appear.
+- **Sidebar Rail:** Standard navigation items only (`Local Storage`, `Videos`, `SMB Shares`, `Downloads`).
+- **Settings:** Zero settings or toggles referencing the vault.
+- **Lock Button:** Completely absent and unrendered.
+
+### State 2: Unlocked
+- **Sidebar Rail:** A new glowing pill button appears in the sidebar library list:
+  - `[ 🔒 Vault ]` (or `[ Private ]` / `[ Stash ]`).
+  - Clicking this pill immediately opens the vault folder in the 3x2 card grid.
+- **Action / Lock Button:** A dedicated **`[ 🔒 Lock Vault ]`** button appears in the navigation rail (either at the bottom of the sidebar or adjacent to the breadcrumbs).
+- **Files Grid:** Media cards inside the vault display normal 16:9 thumbnails, format tags, and durations.
+
+### Relocking Behavior:
+When the user clicks `[ 🔒 Lock Vault ]` (or triggers the quick-lock combo):
+1. If the user is currently inside the vault directory, the browser instantly navigates back to `Home` (`openHome()`).
+2. If a video from the vault is currently playing, playback stops immediately and the screen resets.
+3. The `[ 🔒 Vault ]` entry and `[ 🔒 Lock Vault ]` button disappear.
+4. All memory buffers and GPU textures containing vault thumbnails are purged.
+
+---
+
+## 5. Filesystem & Privacy Architecture
+
+### 1. Storage Location
+- **Path:** `~/.pixelvr_vault/` (or `~/Videos/.vault/`).
+- By utilizing a standard UNIX dotfile directory (`.pixelvr_vault`), the folder is automatically hidden from standard file managers in SteamOS Desktop Mode (Dolphin) unless "Show Hidden Files" is explicitly turned on.
+- The directory will support sub-folders (e.g. `~/.pixelvr_vault/3D_VR180/`, `~/.pixelvr_vault/Movies/`).
+
+### 2. Thumbnail Isolation & Zero-Leakage Guarantee
+- **Vulnerability in Standard Caching:** Usually, thumbnail generators save image previews into a shared directory like `~/.cache/pixelvr/thumbs/` with predictable names. Anyone exploring the cache could see the private video previews.
+- **The Vault Solution:**
+  - Thumbnails for files located within `~/.pixelvr_vault/` are stored strictly inside `~/.pixelvr_vault/.thumbs/`.
+  - When the vault is locked, all in-memory cache entries pointing to `~/.pixelvr_vault/` are evicted from the `ThumbnailCache` map, and the 6 GPU card thumbnail textures in `VulkanRenderer` are cleared to null/placeholders.
+
+### 3. Downloads Integration
+- When the vault is unlocked, downloading an SMB file can offer a quick-action: `[Download to Vault]`, allowing users to transfer files directly into the hidden folder over the network without placing them in the public `~/media` folder first.
+
+---
+
+## 6. Auto-Lock Safety Policies (Anti-Exposure Guards)
+
+To protect the user from accidentally leaving their private media visible:
+
+| Event | Action Taken |
+|---|---|
+| **Headset Removed** (Proximity sensor detects headset off) | **Instant Lock & Return to Home** |
+| **SteamVR Dashboard Opened** (User presses system menu button) | **Instant Lock** |
+| **App Minimized / Focus Lost** | **Instant Lock** |
+| **Inactivity Timeout** (e.g. 5 minutes with no controller input) | **Auto-Lock & Return to Home** |
+| **App Close / Restart** | **Always Cold Boots into Locked State** |
+
+---
+
+## 7. Configuration & Customization Options (Optional Future Settings)
+
+Once the vault is unlocked, an advanced item can appear in the **Settings > Privacy** tab:
+- **Change Unlock Combo:** Allows the user to record their own 4-step button sequence.
+- **Auto-Lock Timer:** Adjust timeout (`2 min`, `5 min`, `10 min`, `Never while active`).
+- **Emergency Panic Button:** Mapping a specific physical gesture (e.g., pressing both thumbsticks for 1 second) to immediately stop playback, lock vault, and switch to a decoy video or home screen.

docs/deploy-to-steam-frame.md

@@ -4,8 +4,49 @@ This guide covers how to get the built app running on the headset, the available
 options, and which one to pick.
 
 **What you're shipping:** a single self-contained ARM64 binary
-(`build-aarch64/bin/pixelvr`, ~11 MB, static OpenXR loader) plus four SPIR-V
-shaders. That's it — no `libopenxr_loader.so` or other bundled libraries.
+(`build-aarch64/bin/pixelvr`, ~11 MB, static OpenXR loader) plus SPIR-V shaders
+and a shell launcher. That's it — no `libopenxr_loader.so` or other bundled
+libraries.
+
+---
+
+## Just installing a release (no devkit, no build)
+
+End users do not need to build anything or use devkits. Choose whichever option fits your setup:
+
+1. **USB Drive / MicroSD Card (No typing & No Dev Mode needed):**  
+   Download `pixelvr-linux-arm64.tar.gz` from GitHub Releases onto a USB flash drive or MicroSD card, plug it into the headset, switch to **Desktop Mode**, and double-click **`Install Pixel VR Player.desktop`**.
+2. **From your PC over Wi-Fi (Requires SSH or Dev Mode):**  
+   Run [`tools/install-from-pc.bat`](../tools/install-from-pc.bat) (Windows) or [`tools/install-from-pc.sh`](../tools/install-from-pc.sh) (Mac/Linux) and enter the headset's IP address.
+3. **One command in terminal (Desktop Mode / SSH):**  
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/Pixelplanet/Pixel-VR-Player/main/tools/install.sh | sh
+   ```
+
+The installer verifies checksums, installs to `~/PixelVRPlayer`, and registers **Pixel VR Player** as a Non-Steam Game in your library. Re-running upgrades in-place while keeping all settings, thumbnails, and hidden vault files (`~/.pixelvr_vault`).
+
+### Uninstalling
+
+To cleanly remove the application and its Steam shortcut:
+
+```bash
+# On headset:
+~/PixelVRPlayer/install.sh --uninstall
+
+# Or one-liner:
+curl -fsSL https://raw.githubusercontent.com/Pixelplanet/Pixel-VR-Player/main/tools/install.sh | sh -s -- --uninstall
+
+# Or from PC over Wi-Fi:
+./tools/uninstall-from-pc.sh          # Mac/Linux
+tools/uninstall-from-pc.bat           # Windows
+```
+
+To purge user settings, thumbnails, and vault files:
+```bash
+rm -rf ~/.config/pixelvr ~/.cache/pixelvr ~/.pixelvr_vault
+```
+
+The rest of this document covers building and deploying as a developer.
 
 ---
 
@@ -20,6 +61,12 @@ shaders. That's it — no `libopenxr_loader.so` or other bundled libraries.
 
 # 2b. Or stage a clean folder for the GUI Devkit Client:
 ./tools/stage.sh          # -> dist/PixelVRPlayer/
+
+# 2c. Or assemble release tarball with desktop installer:
+./tools/package-release.sh build-aarch64 pixelvr-linux-arm64.tar.gz v1.4.2
+
+# 2d. Capture in-headset screenshots over OpenVR / SteamVR compositor:
+python tools/take_headset_screenshot.py --delay 5
 ```
 
 ---
@@ -60,7 +107,7 @@ All three methods below share the same setup. Do this once.
 | Method | Per-deploy effort | Best for |
 |--------|-------------------|----------|
 | **A. Devkit Client (GUI)** | click Upload → Start | first run; the official, guided path |
-| **B. `tools/deploy.py` (CLI)** | one command | fast iteration during development |
+| **B. `tools/deploy.sh` (CLI)** | one command | fast iteration during development |
 | **C. Manual SSH + scp** | a few commands | debugging, capturing logs live |
 | ~~ADB / Android~~ | — | APKs only — **not** this app |
 
@@ -68,8 +115,7 @@ All three methods below share the same setup. Do this once.
 - **Easiest to iterate:** Option B (one command builds nothing you didn't ask for
   and launches in the headset).
 
-They all end up in the same place: *Steam ▸ Library ▸ Non-Steam ▸ **Devkit Game:
-PixelVRPlayer***.
+They all end up in the same place: *Steam ▸ Library ▸ Non-Steam ▸ **Pixel VR Player***.
 
 ---
 
@@ -101,7 +147,7 @@ The official, no-scripting path.
 
 ---
 
-## Option B — One command (`tools/deploy.py`)
+## Option B — One command (`tools/deploy.sh`)
 
 Best for the edit-build-run loop. Copies the binary, shaders and `launch.sh` into
 `~/devkit-game/PixelVRPlayer/`, registers the Non-Steam shortcut, and (optionally)
@@ -154,7 +200,7 @@ differ in which system libraries it sees:
   environment. This is what Valve's docs recommend and what the **GUI (Option A)**
   selects. Good default.
 - **Directly on the host** — uses SteamOS's own FFmpeg/SteamVR libraries. This is
-  what **`deploy.py` (Option B)** registers, matching how a shipping native OpenXR
+  what **`deploy.sh` (Option B)** registers, matching how a shipping native OpenXR
   player runs.
 
 Both expose the SteamVR OpenXR runtime, so both can work. If the app fails to load
@@ -205,6 +251,25 @@ Requirements:
 
 ---
 
+## Taking in-headset screenshots
+
+To capture real in-headset screenshots directly from the SteamVR compositor while the app is running:
+
+```bash
+# Capture with a 5-second countdown to put the headset on:
+python tools/take_headset_screenshot.py --delay 5
+
+# Point to a specific headset IP:
+python tools/take_headset_screenshot.py --host steamos@192.168.178.61 --delay 3
+
+# Continuous series (e.g. 5 captures spaced 2 seconds apart):
+python tools/take_headset_screenshot.py --interval 2 --count 5
+```
+
+The script connects over SSH, triggers SteamVR's compositor screenshot API, fetches the resulting PNGs, and places them into `docs/screenshots/` with both the raw stereo composite (`_stereo.png`) and a cropped single-eye preview (`_preview.png`).
+
+---
+
 ## Troubleshooting
 
 | Symptom | Likely cause / fix |

shaders/text.frag

@@ -17,14 +17,30 @@ vec3 toLinear(vec3 srgb) {
 }
 
 void main() {
-    // Signed-distance text: use Euclidean screen-space gradient with a 0.9px
-    // half-width (~1.8px total ramp) and a slight bold bias (0.465) so thin
-    // stems never shimmer or drop out across head micro-movements in VR.
+    // Stable screen-space signed-distance field text rendering:
+    // Screen-space derivatives of texture coordinates (vUV) provide a smooth,
+    // noise-free measure of font texels per screen pixel across the glyph quad,
+    // completely eliminating fragment-derivative jitter during head movement in VR.
+    vec2 texSize = vec2(textureSize(fontAtlas, 0));
+    vec2 ddx = dFdx(vUV) * texSize;
+    vec2 ddy = dFdy(vUV) * texSize;
+    // RMS font-texel footprint per screen pixel (rotation and perspective invariant)
+    float fontPixelsPerScreenPixel = 0.70710678 * sqrt(dot(ddx, ddx) + dot(ddy, ddy));
+
     float d = texture(fontAtlas, vUV).r;
-    float w = max(length(vec2(dFdx(d), dFdy(d))) * 0.92, 0.025);
-    float a = smoothstep(0.465 - w, 0.465 + w, d);
+    // FreeType SDF: spread = 8 font pixels, contour zero-crossing is 128 / 255.0 = 0.50196078.
+    // Range [-8, +8] font pixels is mapped across [0, 1].
+    float distInFontPixels = (d - 0.50196078) * 16.0;
+
+    // Convert distance to screen pixels, adding a subtle stem-darkening bias (+0.14 screen px)
+    // to preserve thin strokes and legibility against high-contrast dark VR backgrounds.
+    float distInScreenPixels = (distInFontPixels / max(fontPixelsPerScreenPixel, 1e-4)) + 0.14;
+
+    // Smooth Hermite anti-aliasing across 1.4 screen pixels (smooth transition matches VR subpixel PSF)
+    float a = smoothstep(-0.70, 0.70, distInScreenPixels);
     if (a <= 0.002) {
         discard;
     }
+
     outColor = vec4(toLinear(pc.color.rgb), pc.color.a * a);
 }

shaders/thumb.frag

@@ -20,7 +20,10 @@ void main() {
     vec2 b = 0.5 * pc.rect.zw - vec2(0.018);
     vec2 q = max(p - b, 0.0);
     float dist = length(q) - 0.018;
-    float aa = max(length(vec2(dFdx(dist), dFdy(dist))) * 1.15, 0.0025);
+    vec2 dpx = dFdx(p);
+    vec2 dpy = dFdy(p);
+    float pixSize = 0.70710678 * sqrt(dot(dpx, dpx) + dot(dpy, dpy));
+    float aa = max(pixSize * 1.4, 0.001);
     float alpha = 1.0 - smoothstep(-aa, aa, dist);
     if (alpha <= 0.002) {
         discard;

shaders/ui.frag

@@ -173,7 +173,10 @@ void main() {
         d = sdRoundedBox(p, vec2(1.0), 0.0);
     }
 
-    float aa = max(length(vec2(dFdx(d), dFdy(d))) * 1.15, 0.003);
+    // Exact screen-space gradient magnitude of the distance field along the contour normal.
+    // Produces a crisp, razor-sharp 1.5 screen-pixel anti-aliased outline without crawling.
+    float gradLen = length(vec2(dFdx(d), dFdy(d)));
+    float aa = max(gradLen * 0.75, 0.0005);
     float fillAlpha = 1.0 - smoothstep(-aa, aa, d);
 
     if (fillAlpha <= 0.002) {
@@ -183,7 +186,8 @@ void main() {
     vec4 fillLin = vec4(pow(max(pc.color.rgb, vec3(0.0)), vec3(2.2)), pc.color.a);
     vec4 finalColor = fillLin;
     if (hasBorder) {
-        float borderWidth = max(pc.params.z, aa * 1.6);
+        // Crisp, razor-sharp border highlight line matching requested thickness
+        float borderWidth = pc.params.z;
         float innerD = d + borderWidth;
         float borderAlpha = 1.0 - smoothstep(-aa, aa, innerD);
         vec4 bordLin = vec4(pow(max(pc.borderColor.rgb, vec3(0.0)), vec3(2.2)), pc.borderColor.a);

src/app/app.hpp

@@ -61,12 +61,12 @@ private:
 
     // Place the screen in front of the user on the first valid head pose.
     bool didInitialRecenter_ = false;
-    bool controllerModelLoaded_ = false;  // real glTF model uploaded once
-    // Local grip->render-model-space correction so the model sits exactly where
-    // the runtime renders it (derived from the fetched model's owner hand).
-    bool modelCorrValid_ = false;
-    float modelCorrPos_[3] = {0.0f, 0.0f, 0.0f};
-    float modelCorrQuat_[4] = {0.0f, 0.0f, 0.0f, 1.0f};
+    bool controllerModelLoaded_[2] = {false, false};  // glTF model uploaded per hand
+    // Local grip->render-model-space correction per hand so each model sits
+    // exactly where the runtime renders it.
+    bool modelCorrValid_[2] = {false, false};
+    float modelCorrPos_[2][3] = {{0.0f, 0.0f, 0.0f}, {0.0f, 0.0f, 0.0f}};
+    float modelCorrQuat_[2][4] = {{0.0f, 0.0f, 0.0f, 1.0f}, {0.0f, 0.0f, 0.0f, 1.0f}};
     // Background download status line: shown while active and briefly after a
     // download finishes (so success/failure is visible with the browser closed).
     std::chrono::steady_clock::time_point downloadToast_{};
@@ -77,6 +77,7 @@ private:
     bool pendingDlFresh_ = false;  // suppress the same-frame A press
     bool downloadsWindow_ = false;  // downloads list window toggled from the bar
     bool dlWasActive_ = false;      // edge detect: auto-open the window on start
+    bool hudDismissed_ = false;     // manually dismissed player controls / HUD
     // Low-pass smoothed model pose per hand (the raw hand pose jitters; the
     // system's own controller model is visibly smoothed).
     bool modelSmoothInit_[2] = {false, false};
@@ -96,6 +97,28 @@ private:
     // Menu nav stick auto-repeat: -1/+1 to step (initial press + hold), else 0.
     int navStep(float axisY, std::chrono::steady_clock::time_point now);
     int navStepX(float axisX, std::chrono::steady_clock::time_point now);
+    void performVaultLock();
+    VulkanRenderer::ActionMenuData actionMenu_{};
+    void openActionMenu();
+
+    struct SmbModalState {
+        bool active = false;
+        bool isNew = true;
+        std::string origHost;
+        std::string origShare;
+        std::string host;
+        std::string share;
+        bool anon = false;
+        std::string user;
+        std::string pass;
+        std::string workgroup = "WORKGROUP";
+        std::string label;
+        enum class Field { None, Host, Share, User, Pass, Workgroup, Label } editingField = Field::None;
+    } smbModal_{};
+    void openSmbModal(bool isNew, const std::string& smbPath = "");
+    void updateSmbModalMenu();
+    void saveSmbModal();
+    void deleteSmbModal();
 
 #ifdef PIXELVR_HAVE_FREETYPE
     Browser browser_;

src/app/vault_manager.cpp

@@ -0,0 +1,398 @@
+#include "app/vault_manager.hpp"
+#include "util/logging.hpp"
+
+#include <algorithm>
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <sstream>
+
+namespace pixelvr {
+namespace fs = std::filesystem;
+
+namespace {
+
+std::string getVaultConfigPath() {
+#ifdef _WIN32
+    const char* appData = std::getenv("APPDATA");
+    if (appData) return std::string(appData) + "/PixelVR/vault.conf";
+#else
+    const char* home = std::getenv("HOME");
+    if (home) return std::string(home) + "/.config/pixelvr/vault.conf";
+#endif
+    return "pixelvr_vault.conf";
+}
+
+const char* btnName(int b) {
+    switch (b) {
+        case XrInputState::BtnA: return "A";
+        case XrInputState::BtnB: return "B";
+        case XrInputState::BtnX: return "X";
+        case XrInputState::BtnY: return "Y";
+        case XrInputState::BtnMenu: return "Menu";
+        case XrInputState::BtnView: return "View";
+        case XrInputState::BtnBumper: return "Bumper";
+        case XrInputState::BtnThumb: return "Thumb";
+        case XrInputState::BtnGrip: return "Grip";
+        default: return "?";
+    }
+}
+
+static uint64_t fnv1a64(const std::string& str) {
+    uint64_t hash = 14695981039346656037ULL;
+    for (char c : str) {
+        hash ^= static_cast<uint8_t>(c);
+        hash *= 1099511628211ULL;
+    }
+    return hash;
+}
+
+} // namespace
+
+VaultManager& VaultManager::instance() {
+    static VaultManager s_instance;
+    return s_instance;
+}
+
+VaultManager::VaultManager() {
+    const char* home = std::getenv("HOME");
+    if (home != nullptr) {
+        vaultDir_ = std::string(home) + "/.pixelvr_vault";
+    } else {
+        vaultDir_ = "/home/steamos/.pixelvr_vault";
+    }
+    thumbsDir_ = vaultDir_ + "/.thumbs";
+
+    // Default sequence: A -> B -> B -> A -> X -> Y
+    comboSequence_ = {
+        XrInputState::BtnA,
+        XrInputState::BtnB,
+        XrInputState::BtnB,
+        XrInputState::BtnA,
+        XrInputState::BtnX,
+        XrInputState::BtnY
+    };
+
+    loadConfig();
+}
+
+void VaultManager::ensureDirectories() {
+    std::error_code ec;
+    fs::create_directories(vaultDir_, ec);
+    if (!ec) {
+        fs::permissions(vaultDir_, fs::perms::owner_all, fs::perm_options::replace, ec);
+    }
+    fs::create_directories(thumbsDir_, ec);
+    if (!ec) {
+        fs::permissions(thumbsDir_, fs::perms::owner_all, fs::perm_options::replace, ec);
+    }
+}
+
+bool VaultManager::isVaultPath(const std::string& path) const {
+    if (path.empty() || vaultDir_.empty()) return false;
+    return path.rfind(vaultDir_, 0) == 0;
+}
+
+void VaultManager::lock() {
+    if (!unlocked_) return;
+    unlocked_ = false;
+    comboIndex_ = 0;
+    headsetLostTime_ = {};
+    isRecordingCombo_ = false;
+    recordingBuffer_.clear();
+    PIXELVR_LOG_INFO("Vault locked");
+}
+
+void VaultManager::unlock() {
+    ensureDirectories();
+    unlocked_ = true;
+    comboIndex_ = 0;
+    headsetLostTime_ = {};
+    lastActivity_ = std::chrono::steady_clock::now();
+    PIXELVR_LOG_INFO("Vault unlocked at %s", vaultDir_.c_str());
+}
+
+VaultManager::ComboResult VaultManager::feedInput(int button, bool gripFullPressHeld,
+                                                  std::chrono::steady_clock::time_point now) {
+    if (!gripFullPressHeld) {
+        comboIndex_ = 0;
+        return ComboResult::None;
+    }
+
+    // Only face buttons participate in the cheat code
+    if (button != XrInputState::BtnA && button != XrInputState::BtnB &&
+        button != XrInputState::BtnX && button != XrInputState::BtnY) {
+        return ComboResult::None;
+    }
+
+    using namespace std::chrono_literals;
+    if (comboIndex_ > 0 && (now - lastComboInput_) > 2500ms) {
+        comboIndex_ = 0;
+    }
+    lastComboInput_ = now;
+
+    if (comboIndex_ < comboSequence_.size() && button == comboSequence_[comboIndex_]) {
+        comboIndex_++;
+        if (comboIndex_ >= comboSequence_.size()) {
+            comboIndex_ = 0;
+            if (unlocked_) {
+                lock();
+                return ComboResult::Locked;
+            } else {
+                unlock();
+                return ComboResult::Unlocked;
+            }
+        }
+        return ComboResult::StepMatched;
+    } else {
+        // Wrong button pressed while grip was held
+        comboIndex_ = 0;
+        return ComboResult::Failed;
+    }
+}
+
+void VaultManager::recordActivity(std::chrono::steady_clock::time_point now) {
+    lastActivity_ = now;
+}
+
+bool VaultManager::tick(std::chrono::steady_clock::time_point now, bool headsetFocused) {
+    if (!unlocked_) return false;
+
+    // Guard 1: Headset removed / focus lost (debounced with 3.0s threshold to avoid momentary tracking glitches)
+    if (autoLockHeadsetOff_) {
+        if (!headsetFocused) {
+            if (headsetLostTime_.time_since_epoch().count() == 0) {
+                headsetLostTime_ = now;
+            } else {
+                auto elapsedMs = std::chrono::duration_cast<std::chrono::milliseconds>(now - headsetLostTime_).count();
+                if (elapsedMs >= 3000) {
+                    PIXELVR_LOG_INFO("Auto-locking vault: headset removed or session lost focus for %lld ms",
+                                     static_cast<long long>(elapsedMs));
+                    headsetLostTime_ = {};
+                    lock();
+                    return true;
+                }
+            }
+        } else {
+            headsetLostTime_ = {};
+        }
+    } else {
+        headsetLostTime_ = {};
+    }
+
+    // Guard 2: Inactivity timeout (bypassed if autoLockTimeoutSec_ <= 0)
+    if (autoLockTimeoutSec_ > 0 && lastActivity_.time_since_epoch().count() > 0) {
+        auto elapsed = std::chrono::duration_cast<std::chrono::seconds>(now - lastActivity_).count();
+        if (elapsed >= autoLockTimeoutSec_) {
+            PIXELVR_LOG_INFO("Auto-locking vault: inactivity timeout (%llds >= %ds)",
+                             static_cast<long long>(elapsed), autoLockTimeoutSec_);
+            lock();
+            return true;
+        }
+    }
+
+    return false;
+}
+
+void VaultManager::cleanPublicThumbs(const std::string& path) {
+    const char* home = std::getenv("HOME");
+    if (!home) return;
+    std::error_code ec;
+    std::string pubThumbDir = std::string(home) + "/.cache/pixelvr/thumbs";
+    if (!fs::exists(pubThumbDir, ec)) return;
+
+    auto removeThumbFor = [&](const std::string& fpath) {
+        const std::string baseHash = std::to_string(fnv1a64(fpath));
+        std::error_code e;
+        fs::remove(pubThumbDir + "/" + baseHash + ".rgba", e);
+        e.clear();
+        fs::remove(pubThumbDir + "/" + baseHash + ".meta", e);
+    };
+
+    if (fs::is_directory(path, ec)) {
+        for (const auto& it : fs::recursive_directory_iterator(path, ec)) {
+            if (it.is_regular_file()) {
+                removeThumbFor(it.path().string());
+            }
+        }
+    } else {
+        removeThumbFor(path);
+    }
+}
+
+std::string VaultManager::moveFileToVault(const std::string& srcPath, std::string& outNewPath) {
+    if (!unlocked_) {
+        return "Vault is locked";
+    }
+    if (srcPath.empty()) {
+        return "Source path is empty";
+    }
+    std::error_code ec;
+    if (!fs::exists(srcPath, ec)) {
+        return "Path does not exist";
+    }
+
+    ensureDirectories();
+
+    fs::path src(srcPath);
+    const bool isDir = fs::is_directory(src, ec);
+    std::string stem = src.stem().string();
+    std::string ext = isDir ? "" : src.extension().string();
+    std::string targetFilename = src.filename().string();
+    fs::path dest = fs::path(vaultDir_) / targetFilename;
+
+    // Prevent collision by appending _1, _2, etc.
+    int counter = 1;
+    while (fs::exists(dest, ec)) {
+        targetFilename = isDir ? (stem + "_" + std::to_string(counter++))
+                               : (stem + "_" + std::to_string(counter++) + ext);
+        dest = fs::path(vaultDir_) / targetFilename;
+    }
+
+    // Try rename first
+    fs::rename(src, dest, ec);
+    if (ec) {
+        ec.clear();
+        if (isDir) {
+            fs::copy(src, dest, fs::copy_options::recursive, ec);
+            if (ec) {
+                return "Failed to copy directory: " + ec.message();
+            }
+            fs::remove_all(src, ec);
+        } else {
+            fs::copy_file(src, dest, fs::copy_options::overwrite_existing, ec);
+            if (ec) {
+                return "Failed to copy file: " + ec.message();
+            }
+            fs::remove(src, ec);
+        }
+    }
+
+    // Ensure 0700 permissions
+    ec.clear();
+    fs::permissions(dest, fs::perms::owner_all, fs::perm_options::replace, ec);
+    if (isDir) {
+        for (const auto& it : fs::recursive_directory_iterator(dest, ec)) {
+            std::error_code pe;
+            fs::permissions(it.path(), fs::perms::owner_all, fs::perm_options::replace, pe);
+        }
+    }
+
+    outNewPath = dest.string();
+    PIXELVR_LOG_INFO("Moved into vault: %s -> %s", srcPath.c_str(), outNewPath.c_str());
+
+    // Clean up any public thumbnails that existed for srcPath
+    cleanPublicThumbs(srcPath);
+
+    return "";
+}
+
+void VaultManager::setAutoLockHeadsetOff(bool enable) {
+    autoLockHeadsetOff_ = enable;
+    saveConfig();
+}
+
+void VaultManager::setAutoLockTimeoutSec(int sec) {
+    autoLockTimeoutSec_ = sec;
+    saveConfig();
+}
+
+void VaultManager::setMoveButton(int btn) {
+    moveButton_ = btn;
+    saveConfig();
+}
+
+std::string VaultManager::comboString() const {
+    if (comboSequence_.empty()) return "None";
+    std::string s;
+    for (std::size_t i = 0; i < comboSequence_.size(); ++i) {
+        if (i > 0) s += " ";
+        s += btnName(comboSequence_[i]);
+    }
+    return s;
+}
+
+void VaultManager::startRecordingCombo() {
+    isRecordingCombo_ = true;
+    recordingBuffer_.clear();
+}
+
+void VaultManager::cancelRecordingCombo() {
+    isRecordingCombo_ = false;
+    recordingBuffer_.clear();
+}
+
+bool VaultManager::feedRecordButton(int button) {
+    if (!isRecordingCombo_) return false;
+    if (button != XrInputState::BtnA && button != XrInputState::BtnB &&
+        button != XrInputState::BtnX && button != XrInputState::BtnY) {
+        return false;
+    }
+    recordingBuffer_.push_back(button);
+    if (recordingBuffer_.size() >= 6) {
+        comboSequence_ = recordingBuffer_;
+        isRecordingCombo_ = false;
+        recordingBuffer_.clear();
+        saveConfig();
+        return true; // Finished recording 6-step combo
+    }
+    return false;
+}
+
+void VaultManager::loadConfig() {
+    const std::string path = getVaultConfigPath();
+    std::ifstream file(path);
+    if (!file.is_open()) return;
+
+    std::string line;
+    while (std::getline(file, line)) {
+        auto eq = line.find('=');
+        if (eq == std::string::npos) continue;
+        std::string key = line.substr(0, eq);
+        std::string val = line.substr(eq + 1);
+
+        if (key == "auto_lock_headset_off") {
+            autoLockHeadsetOff_ = (val == "1");
+        } else if (key == "auto_lock_timeout_sec") {
+            try { autoLockTimeoutSec_ = std::stoi(val); } catch (...) {}
+        } else if (key == "move_button") {
+            try { moveButton_ = std::stoi(val); } catch (...) {}
+        } else if (key == "combo") {
+            std::vector<int> loaded;
+            std::stringstream ss(val);
+            std::string item;
+            while (std::getline(ss, item, ',')) {
+                try { loaded.push_back(std::stoi(item)); } catch (...) {}
+            }
+            if (loaded.size() >= 4 && loaded.size() <= 8) {
+                comboSequence_ = loaded;
+            }
+        }
+    }
+}
+
+void VaultManager::saveConfig() const {
+    const std::string path = getVaultConfigPath();
+    try {
+        fs::path p(path);
+        if (p.has_parent_path()) {
+            fs::create_directories(p.parent_path());
+        }
+        std::ofstream file(path);
+        if (file.is_open()) {
+            file << "auto_lock_headset_off=" << (autoLockHeadsetOff_ ? 1 : 0) << "\n";
+            file << "auto_lock_timeout_sec=" << autoLockTimeoutSec_ << "\n";
+            file << "move_button=" << moveButton_ << "\n";
+            file << "combo=";
+            for (std::size_t i = 0; i < comboSequence_.size(); ++i) {
+                if (i > 0) file << ",";
+                file << comboSequence_[i];
+            }
+            file << "\n";
+        }
+    } catch (const std::exception& e) {
+        PIXELVR_LOG_WARN("Could not save vault settings: %s", e.what());
+    }
+}
+
+} // namespace pixelvr

src/app/vault_manager.hpp

@@ -0,0 +1,102 @@
+#pragma once
+
+#include "xr/xr_context.hpp"
+
+#include <chrono>
+#include <string>
+#include <vector>
+
+namespace pixelvr {
+
+class VaultManager {
+public:
+    enum class ComboResult {
+        None,
+        StepMatched,
+        Unlocked,
+        Locked,
+        Failed
+    };
+
+    static VaultManager& instance();
+
+    bool isUnlocked() const { return unlocked_; }
+    void lock();
+    void unlock();
+
+    // Process button input during frame loop.
+    // If gripFullPressHeld is true, face buttons are consumed for the combo and
+    // caller should suppress them from normal UI.
+    ComboResult feedInput(int button, bool gripFullPressHeld,
+                          std::chrono::steady_clock::time_point now);
+
+    // Call when any user activity occurs (sticks, triggers, buttons)
+    void recordActivity(std::chrono::steady_clock::time_point now);
+
+    // Frame tick: checks inactivity timeout and headset focus loss.
+    // Returns true if the vault was locked as a result of the tick.
+    bool tick(std::chrono::steady_clock::time_point now, bool headsetFocused);
+
+    // Storage paths
+    const std::string& vaultDir() const { return vaultDir_; }
+    const std::string& thumbsDir() const { return thumbsDir_; }
+    bool isVaultPath(const std::string& path) const;
+    void ensureDirectories();
+
+    // Move file or directory into vault (local paths only).
+    // Returns empty string on success, or error message on failure.
+    std::string moveFileToVault(const std::string& srcPath, std::string& outNewPath);
+
+    // Clean up cached public thumbnails for a file or directory
+    void cleanPublicThumbs(const std::string& path);
+
+    // Settings
+    bool autoLockHeadsetOff() const { return autoLockHeadsetOff_; }
+    void setAutoLockHeadsetOff(bool enable);
+
+    int autoLockTimeoutSec() const { return autoLockTimeoutSec_; }
+    void setAutoLockTimeoutSec(int sec);
+
+    int moveButton() const { return moveButton_; }
+    void setMoveButton(int btn);
+
+    const std::vector<int>& comboSequence() const { return comboSequence_; }
+    std::string comboString() const;
+
+    // Custom combo recording
+    bool isRecordingCombo() const { return isRecordingCombo_; }
+    void startRecordingCombo();
+    void cancelRecordingCombo();
+    bool feedRecordButton(int button);
+    int recordedCount() const { return static_cast<int>(recordingBuffer_.size()); }
+
+    void loadConfig();
+    void saveConfig() const;
+
+private:
+    VaultManager();
+    ~VaultManager() = default;
+
+    bool unlocked_ = false;
+    std::string vaultDir_;
+    std::string thumbsDir_;
+
+    // Combo state machine
+    std::vector<int> comboSequence_;
+    std::size_t comboIndex_ = 0;
+    std::chrono::steady_clock::time_point lastComboInput_{};
+
+    // Recording custom combo
+    bool isRecordingCombo_ = false;
+    std::vector<int> recordingBuffer_;
+
+    // Settings
+    bool autoLockHeadsetOff_ = true;
+    int autoLockTimeoutSec_ = 0; // Disabled by default (headset face detection active)
+    int moveButton_ = XrInputState::BtnY;
+
+    std::chrono::steady_clock::time_point lastActivity_{};
+    std::chrono::steady_clock::time_point headsetLostTime_{};
+};
+
+} // namespace pixelvr

src/gfx/text_atlas.cpp

@@ -5,6 +5,7 @@
 #ifdef PIXELVR_HAVE_FREETYPE
 #include <ft2build.h>
 #include FT_FREETYPE_H
+#include FT_MODULE_H
 #endif
 
 namespace pixelvr {
@@ -17,6 +18,15 @@ FontAtlas buildFontAtlas(const char* ttfPath, int pixelHeight) {
         PIXELVR_LOG_ERROR("FreeType: init failed");
         return atlas;
     }
+    // Expand the distance field ramp from FreeType's default 2px to 8px.
+    // At typical VR UI viewing distances, 8 font pixels produces a smooth,
+    // noise-free gradient spanning multiple screen pixels, completely eliminating
+    // edge shimmering during head movement.
+    constexpr FT_UInt kSpread = 8;
+    FT_Property_Set(lib, "sdf", "spread", &kSpread);
+    FT_Property_Set(lib, "bsdf", "spread", &kSpread);
+    atlas.spread = static_cast<float>(kSpread);
+
     FT_Face face = nullptr;
     if (FT_New_Face(lib, ttfPath, 0, &face) != 0) {
         PIXELVR_LOG_ERROR("FreeType: cannot open %s", ttfPath);

src/gfx/text_atlas.hpp

@@ -22,6 +22,7 @@ struct FontAtlas {
     float lineHeight = 0.0f;
     float ascent = 0.0f;
     bool sdf = false;             // true = signed-distance field (crisp at scale)
+    float spread = 8.0f;          // SDF spread distance in font pixels (contour zero-crossing at 128)
     bool ok = false;
 };
 

src/gfx/vulkan_renderer.hpp

@@ -13,6 +13,7 @@ namespace pixelvr {
 class XrContext;
 struct ViewSwapchain;
 struct DrmVideoFrame;
+struct GltfMesh;
 
 // Owns the Vulkan device (created through OpenXR) and the per-eye render
 // resources. For Phase 0/1 it draws a pose-anchored test triangle into each eye
@@ -123,6 +124,9 @@ public:
         std::string detail;
         std::string tag;
         std::string durationTag;
+        std::string sizeTag;
+        std::string resolutionTag;
+        std::string codecTag;
         std::string previewPath;
         bool isDir = false;
         bool isVideo = false;
@@ -152,6 +156,8 @@ public:
     int downloadsFilter() const { return downloadsFilter_; }
     void setActiveDownloadCount(int c) { activeDownloadCount_ = c; }
     void setSettingsSection(int s) { settingsSection_ = s; }
+    void setVaultUnlocked(bool u) { vaultUnlocked_ = u; }
+    bool vaultUnlocked() const { return vaultUnlocked_; }
     void setUiAppearance(float textScale, int textColorIdx, int accentColorIdx,
                          float uiDistance) {
         uiTextScale_ = textScale;
@@ -160,6 +166,44 @@ public:
         uiDistance_ = uiDistance;
     }
 
+    enum class BrowserViewMode : int {
+        BigCards = 0,    // 3x2, 6 per page (Large cards with full 16:9 thumbnail)
+        MiniCards = 1,   // 4x3, 12 per page (Compact cards with 16:9 thumbnail)
+        CompactList = 2  // 1x8, 8 per page (Single-column detailed configurable list view)
+    };
+    void setBrowserViewMode(BrowserViewMode mode) { browserViewMode_ = mode; }
+    BrowserViewMode browserViewMode() const { return browserViewMode_; }
+    void setBrowserQuickPath(bool isCurrentQuickPath) { browserIsQuickPath_ = isCurrentQuickPath; }
+    void setBrowserBookmarked(bool isCurrentBookmarked) { browserIsQuickPath_ = isCurrentBookmarked; }
+    bool browserIsQuickPath() const { return browserIsQuickPath_; }
+    bool browserIsBookmarked() const { return browserIsQuickPath_; }
+    void setListColumnVisibility(bool showFormat, bool showRes, bool showSize, bool showDuration) {
+        listShowFormat_ = showFormat;
+        listShowRes_ = showRes;
+        listShowSize_ = showSize;
+        listShowDuration_ = showDuration;
+    }
+
+    struct KeyboardModalData {
+        bool visible = false;
+        std::string prompt;
+        std::string text;
+        bool isPassword = false;
+    };
+    void setKeyboardModal(bool visible, const std::string& prompt,
+                          const std::string& text, bool isPassword = false) {
+        keyboardModal_.visible = visible;
+        keyboardModal_.prompt = prompt;
+        keyboardModal_.text = text;
+        keyboardModal_.isPassword = isPassword;
+    }
+    const KeyboardModalData& keyboardModal() const { return keyboardModal_; }
+
+    void setUiFollowMode(int mode) { uiFollowMode_ = mode; }
+    int uiFollowMode() const { return uiFollowMode_; }
+
+    bool pointerActive() const { return pointerActive_; }
+
     // Downloads overlay: modern glassmorphic window with job cards
     void setDownloads(bool visible, const std::string& title,
                       const std::vector<std::string>& rows,
@@ -179,6 +223,22 @@ public:
     int downloadsHovered() const { return downloadsHovered_; }
     int downloadsButtonHovered() const { return downloadsBtnHovered_; }
 
+    // File Action Submenu (opened by button Y in file browser)
+    struct ActionMenuData {
+        bool visible = false;
+        int page = 0; // 0: Main, 1: MoveDestinations, 2: DeleteConfirm, 3: Rename
+        std::string title;
+        std::string subtitle;
+        std::vector<std::string> options;
+        int selectedOption = -1;
+        std::string renameBuffer;
+    };
+    void setActionMenu(const ActionMenuData& data) { actionMenu_ = data; }
+    const ActionMenuData& actionMenu() const { return actionMenu_; }
+    int actionMenuBtnHovered() const { return actionMenuBtnHovered_; }
+    int actionMenuKeyHovered() const { return actionMenuKeyHovered_; }
+    void setBrowserNetwork(bool onNet) { browserOnNetwork_ = onNet; }
+
     // Tracked controllers: aim poses used to draw pointer rays, controller
     // models and the UI cursor. Index 0 = left, 1 = right. Call once per frame,
     // after setBrowser, so the pointer can be raycast against the current panel.
@@ -195,8 +255,11 @@ public:
     void setControllers(const ControllerVis& left, const ControllerVis& right);
 
     // Replaces the procedural controller geometry with the runtime-provided glTF
-    // render model (parsed from the GLB bytes). Call once when the asset is ready.
-    bool loadControllerModel(const std::vector<uint8_t>& glb);
+    // render model (parsed from the GLB bytes) for hand (0 = left, 1 = right).
+    bool loadControllerModel(int hand, const std::vector<uint8_t>& glb);
+    bool loadControllerModel(const std::vector<uint8_t>& glb) {
+        return loadControllerModel(1, glb);
+    }
 
     // Per-node animated transforms from xrGetRenderModelStateEXT, matched to
     // submeshes by node name (drives button-press motion on the model).
@@ -206,7 +269,10 @@ public:
         float quat[4] = {0.0f, 0.0f, 0.0f, 1.0f};
         bool visible = true;
     };
-    void setControllerNodeStates(const std::vector<NodeStateVis>& states);
+    void setControllerNodeStates(int hand, const std::vector<NodeStateVis>& states);
+    void setControllerNodeStates(const std::vector<NodeStateVis>& states) {
+        setControllerNodeStates(1, states);
+    }
 
     enum class UiShape : int {
         RoundedBox = 0,
@@ -251,9 +317,11 @@ public:
         FormatToggle = 8,
         AudioToggle = 9,
         ScreenToggle = 10,
-        Recenter = 11   // recenter screen/view from HUD
+        Recenter = 11,  // recenter screen/view from HUD
+        HideHud = 12    // immediately hide player controls
     };
     void setControlBar(bool visible) { controlBarVisible_ = visible; }
+    bool controlBarVisible() const { return controlBarVisible_; }
     void setHudLabels(const std::string& format, const std::string& audio,
                       const std::string& screen, bool formatEnabled = true,
                       bool audioEnabled = true) {
@@ -264,11 +332,14 @@ public:
         hudAudioEnabled_ = audioEnabled;
     }
 
-    // Per-hand laser pointer toggle (grip press). A hand with the laser off
-    // neither casts a beam nor takes part in the UI raycast, so the other hand
-    // can own the pointer while this one drives a panel with its stick/d-pad.
+    // Per-hand laser pointer toggle (grip full press). Only one controller has
+    // an active laser pointer at any time. When a hand enables its laser, the
+    // other hand's laser is turned off.
     void setLaserOn(int hand, bool on) {
-        if (hand >= 0 && hand < 2) laserOn_[hand] = on;
+        if (hand >= 0 && hand < 2) {
+            laserOn_[hand] = on;
+            if (on) laserOn_[1 - hand] = false;
+        }
     }
     bool laserOn(int hand) const {
         return (hand >= 0 && hand < 2) ? laserOn_[hand] : false;
@@ -383,6 +454,12 @@ private:
     int downloadsBtnHovered_ = -1;
     int downloadsHovered_ = -1;
 
+    // Action menu state
+    ActionMenuData actionMenu_{};
+    int actionMenuBtnHovered_ = -1;
+    int actionMenuKeyHovered_ = -1;
+    bool browserOnNetwork_ = false;
+
     // Flat-screen placement in the app reference space (updated by recenter and
     // thumbstick distance control).
     float screenPivot_[3] = {0.0f, 0.0f, 0.0f};
@@ -419,15 +496,24 @@ private:
         std::string path;
         bool ready = false;
     };
-    CardThumbnail cardThumbs_[6];
+    CardThumbnail cardThumbs_[12];
     VkPipeline thumbPipeline_ = VK_NULL_HANDLE;
     VkDescriptorPool thumbPool_ = VK_NULL_HANDLE;
+    BrowserViewMode browserViewMode_ = BrowserViewMode::BigCards;
+    bool browserIsQuickPath_ = false;
+    KeyboardModalData keyboardModal_{};
+    int uiFollowMode_ = 0; // 0 = World Lock (Default, zero drift/tilt), 1 = Smooth Gaze Follow
+    bool listShowFormat_ = true;
+    bool listShowRes_ = true;
+    bool listShowSize_ = true;
+    bool listShowDuration_ = true;
 
     // Text rendering (FreeType glyph atlas) + file browser overlay.
     FontAtlas fontAtlas_;
     VkImage fontImage_ = VK_NULL_HANDLE;
     VkDeviceMemory fontMemory_ = VK_NULL_HANDLE;
     VkImageView fontView_ = VK_NULL_HANDLE;
+    VkSampler fontSampler_ = VK_NULL_HANDLE;
     VkDescriptorSetLayout textSetLayout_ = VK_NULL_HANDLE;
     VkDescriptorPool textPool_ = VK_NULL_HANDLE;
     VkDescriptorSet textSet_ = VK_NULL_HANDLE;
@@ -468,10 +554,12 @@ private:
     bool pointerActive_ = false;
     int pointerRow_ = -1;
     int pointerHand_ = -1;
-    // Whether each hand's laser pointer is on (toggled with the grip button).
-    bool laserOn_[2] = {true, true};
+    // Whether each hand's laser pointer is on. Only one controller has an active
+    // laser pointer at any time. Defaults to right controller active, left off.
+    bool laserOn_[2] = {false, true};
     float pointerHit_[3] = {0.0f, 0.0f, 0.0f};
     bool controlBarVisible_ = false;
+    bool vaultUnlocked_ = false;
     int pointerButton_ = -1;
     bool pointerOnTimeline_ = false;
     float pointerScrub_ = 0.0f;
@@ -575,18 +663,18 @@ private:
     int resolveH_ = 0;
     uint32_t resolveMips_ = 1;
 
-    // Lit, textured 3D controller render models. The merged glTF geometry is
-    // split into submeshes by material; each samples its own base-color texture
-    // (which carries the part colors and printed button labels). Drawn with the
-    // depth buffer so near parts occlude far ones.
+    // Lit, textured 3D controller render models. The glTF geometry is loaded
+    // separately for left (0) and right (1) hands into handModels_[2].
+    // Drawn with the depth buffer so near parts occlude far ones.
     VkPipelineLayout modelLayout_ = VK_NULL_HANDLE;
     VkPipeline modelPipeline_ = VK_NULL_HANDLE;
-    VkBuffer modelVertexBuffer_ = VK_NULL_HANDLE;
-    VkDeviceMemory modelVertexMemory_ = VK_NULL_HANDLE;
-    VkBuffer modelIndexBuffer_ = VK_NULL_HANDLE;
-    VkDeviceMemory modelIndexMemory_ = VK_NULL_HANDLE;
-    uint32_t modelIndexCount_ = 0;
-    VkIndexType modelIndexType_ = VK_INDEX_TYPE_UINT16;  // UINT32 for glTF models
+
+    // Procedural capsule fallback buffers (used before glTF is fetched)
+    VkBuffer capsuleVertexBuffer_ = VK_NULL_HANDLE;
+    VkDeviceMemory capsuleVertexMemory_ = VK_NULL_HANDLE;
+    VkBuffer capsuleIndexBuffer_ = VK_NULL_HANDLE;
+    VkDeviceMemory capsuleIndexMemory_ = VK_NULL_HANDLE;
+    uint32_t capsuleIndexCount_ = 0;
 
     struct ModelTexture {
         VkImage image = VK_NULL_HANDLE;
@@ -601,13 +689,27 @@ private:
         float color[4] = {1.0f, 1.0f, 1.0f, 1.0f};
         std::string nodeName;  // matched to an animated render-model node state
     };
+    struct HandModel {
+        VkBuffer vertexBuffer = VK_NULL_HANDLE;
+        VkDeviceMemory vertexMemory = VK_NULL_HANDLE;
+        VkBuffer indexBuffer = VK_NULL_HANDLE;
+        VkDeviceMemory indexMemory = VK_NULL_HANDLE;
+        uint32_t indexCount = 0;
+        VkIndexType indexType = VK_INDEX_TYPE_UINT32;
+        std::vector<ModelTexture> textures;
+        std::vector<ModelSubmesh> submeshes;
+        std::vector<NodeStateVis> nodeStates;
+        bool ready = false;
+    };
+    HandModel handModels_[2];  // 0 = left, 1 = right
+
     VkDescriptorSetLayout modelSetLayout_ = VK_NULL_HANDLE;
     VkDescriptorPool modelDescPool_ = VK_NULL_HANDLE;
     VkSampler modelSampler_ = VK_NULL_HANDLE;
     ModelTexture modelWhite_;  // 1x1 white fallback for untextured submeshes
-    std::vector<ModelTexture> modelTextures_;
-    std::vector<ModelSubmesh> modelSubmeshes_;
-    std::vector<NodeStateVis> modelNodeStates_;
+
+    void destroyHandModel(HandModel& hm);
+    bool uploadHandMesh(int hand, const GltfMesh& mesh);
     bool createModelTexture(const uint8_t* rgba, int width, int height,
                             ModelTexture& out);
 };

src/media/media_engine.cpp

@@ -43,13 +43,31 @@ extern "C" {
 #include <cerrno>
 #endif
 
+#include "net/smb_credentials.hpp"
+
 namespace pixelvr {
 
 #ifdef PIXELVR_HAVE_SMB
 namespace {
 
-void smb_auth(SMBCCTX*, const char*, const char*, char*, int, char* un, int unlen,
+void smb_auth(SMBCCTX*, const char* srv, const char* shr, char* wg, int wglen, char* un, int unlen,
               char* pw, int pwlen) {
+    std::string u, p, w;
+    if (srv != nullptr && SmbCredentialsManager::instance().findCredentials(srv, shr ? shr : "", u, p, w)) {
+        if (un && unlen > 0) {
+            std::strncpy(un, u.c_str(), unlen - 1);
+            un[unlen - 1] = '\0';
+        }
+        if (pw && pwlen > 0) {
+            std::strncpy(pw, p.c_str(), pwlen - 1);
+            pw[pwlen - 1] = '\0';
+        }
+        if (wg && wglen > 0 && !w.empty()) {
+            std::strncpy(wg, w.c_str(), wglen - 1);
+            wg[wglen - 1] = '\0';
+        }
+        return;
+    }
     if (un != nullptr && unlen > 0) un[0] = '\0';  // guest / anonymous
     if (pw != nullptr && pwlen > 0) pw[0] = '\0';
 }

src/net/smb_credentials.cpp

@@ -0,0 +1,486 @@
+#include "smb_credentials.hpp"
+#include "util/logging.hpp"
+
+#include <algorithm>
+#include <chrono>
+#include <cstdlib>
+#include <cstring>
+#include <filesystem>
+#include <fstream>
+#include <iomanip>
+#include <random>
+#include <sstream>
+
+#if defined(__linux__) || defined(__APPLE__)
+#include <sys/stat.h>
+#include <unistd.h>
+#endif
+
+namespace pixelvr {
+namespace fs = std::filesystem;
+
+namespace {
+
+// Clean portable ChaCha20 stream cipher implementation
+// RFC 7539 / 8439
+static uint32_t rotl32(uint32_t x, int n) {
+    return (x << n) | (x >> (32 - n));
+}
+
+#define CHACHA20_QUARTERROUND(a, b, c, d) \
+    a += b; d ^= a; d = rotl32(d, 16); \
+    c += d; b ^= c; b = rotl32(b, 12); \
+    a += b; d ^= a; d = rotl32(d, 8);  \
+    c += d; b ^= c; b = rotl32(b, 7);
+
+static void chacha20_block(uint32_t out[16], const uint32_t in[16]) {
+    for (int i = 0; i < 16; ++i) out[i] = in[i];
+    for (int i = 0; i < 10; ++i) {
+        CHACHA20_QUARTERROUND(out[0], out[4], out[8],  out[12]);
+        CHACHA20_QUARTERROUND(out[1], out[5], out[9],  out[13]);
+        CHACHA20_QUARTERROUND(out[2], out[6], out[10], out[14]);
+        CHACHA20_QUARTERROUND(out[3], out[7], out[11], out[15]);
+        CHACHA20_QUARTERROUND(out[0], out[5], out[10], out[15]);
+        CHACHA20_QUARTERROUND(out[1], out[6], out[11], out[12]);
+        CHACHA20_QUARTERROUND(out[2], out[7], out[8],  out[13]);
+        CHACHA20_QUARTERROUND(out[3], out[4], out[9],  out[14]);
+    }
+    for (int i = 0; i < 16; ++i) out[i] += in[i];
+}
+
+static void chacha20_crypt(const uint8_t key[32], const uint8_t nonce[12], uint32_t counter,
+                           const uint8_t* in, uint8_t* out, std::size_t len) {
+    uint32_t state[16];
+    // Constants "expand 32-byte k"
+    state[0] = 0x61707865;
+    state[1] = 0x3320646e;
+    state[2] = 0x79622d32;
+    state[3] = 0x6b206574;
+    for (int i = 0; i < 8; ++i) {
+        state[4 + i] = (static_cast<uint32_t>(key[i * 4 + 0])) |
+                       (static_cast<uint32_t>(key[i * 4 + 1]) << 8) |
+                       (static_cast<uint32_t>(key[i * 4 + 2]) << 16) |
+                       (static_cast<uint32_t>(key[i * 4 + 3]) << 24);
+    }
+    state[12] = counter;
+    for (int i = 0; i < 3; ++i) {
+        state[13 + i] = (static_cast<uint32_t>(nonce[i * 4 + 0])) |
+                        (static_cast<uint32_t>(nonce[i * 4 + 1]) << 8) |
+                        (static_cast<uint32_t>(nonce[i * 4 + 2]) << 16) |
+                        (static_cast<uint32_t>(nonce[i * 4 + 3]) << 24);
+    }
+
+    uint32_t block[16];
+    uint8_t keyStream[64];
+    std::size_t offset = 0;
+    while (offset < len) {
+        chacha20_block(block, state);
+        for (int i = 0; i < 16; ++i) {
+            keyStream[i * 4 + 0] = static_cast<uint8_t>(block[i] & 0xFF);
+            keyStream[i * 4 + 1] = static_cast<uint8_t>((block[i] >> 8) & 0xFF);
+            keyStream[i * 4 + 2] = static_cast<uint8_t>((block[i] >> 16) & 0xFF);
+            keyStream[i * 4 + 3] = static_cast<uint8_t>((block[i] >> 24) & 0xFF);
+        }
+        state[12]++;
+        const std::size_t chunk = std::min<std::size_t>(64, len - offset);
+        for (std::size_t i = 0; i < chunk; ++i) {
+            out[offset + i] = in[offset + i] ^ keyStream[i];
+        }
+        offset += chunk;
+    }
+}
+
+static std::string toHex(const uint8_t* data, std::size_t len) {
+    std::ostringstream oss;
+    oss << std::hex << std::setfill('0');
+    for (std::size_t i = 0; i < len; ++i) {
+        oss << std::setw(2) << static_cast<int>(data[i]);
+    }
+    return oss.str();
+}
+
+static std::vector<uint8_t> fromHex(const std::string& hex) {
+    std::vector<uint8_t> bytes;
+    if (hex.length() % 2 != 0) return bytes;
+    bytes.reserve(hex.length() / 2);
+    for (std::size_t i = 0; i < hex.length(); i += 2) {
+        const std::string byteStr = hex.substr(i, 2);
+        char* end = nullptr;
+        unsigned long b = std::strtoul(byteStr.c_str(), &end, 16);
+        if (end == byteStr.c_str() + 2) {
+            bytes.push_back(static_cast<uint8_t>(b));
+        } else {
+            return {};
+        }
+    }
+    return bytes;
+}
+
+static std::string trim(const std::string& s) {
+    auto start = s.find_first_not_of(" \t\r\n");
+    if (start == std::string::npos) return "";
+    auto end = s.find_last_not_of(" \t\r\n");
+    return s.substr(start, end - start + 1);
+}
+
+} // namespace
+
+SmbCredentialsManager& SmbCredentialsManager::instance() {
+    static SmbCredentialsManager sInstance;
+    return sInstance;
+}
+
+SmbCredentialsManager::SmbCredentialsManager() {
+    load();
+}
+
+std::string SmbCredentialsManager::getStoragePath() const {
+#ifdef _WIN32
+    const char* appData = std::getenv("APPDATA");
+    if (appData) return std::string(appData) + "/PixelVR/smb_shares.json";
+#else
+    const char* home = std::getenv("HOME");
+    if (home) return std::string(home) + "/.config/pixelvr/smb_shares.json";
+#endif
+    return "pixelvr_smb_shares.json";
+}
+
+std::string SmbCredentialsManager::getDeviceKey() const {
+    std::string seed = "PixelVR-Frame-SMB-2026-Salt!";
+#if defined(__linux__)
+    std::ifstream mid("/etc/machine-id");
+    if (mid.is_open()) {
+        std::string id;
+        std::getline(mid, id);
+        id = trim(id);
+        if (!id.empty()) {
+            seed += ":" + id;
+        }
+    }
+#endif
+    const char* user = std::getenv("USER");
+    if (user) seed += ":" + std::string(user);
+
+    // Derive 32-byte key using double FNV-1a / DJB2 mixing
+    uint64_t h1 = 14695981039346656037ULL;
+    uint64_t h2 = 5381;
+    for (char c : seed) {
+        h1 = (h1 ^ static_cast<uint8_t>(c)) * 1099511628211ULL;
+        h2 = ((h2 << 5) + h2) + static_cast<uint8_t>(c);
+    }
+    uint8_t keyBytes[32];
+    for (int i = 0; i < 8; ++i) {
+        keyBytes[i + 0] = static_cast<uint8_t>((h1 >> (i * 8)) & 0xFF);
+        keyBytes[i + 8] = static_cast<uint8_t>((h2 >> (i * 8)) & 0xFF);
+        keyBytes[i + 16] = static_cast<uint8_t>(((h1 ^ h2) >> (i * 8)) & 0xFF);
+        keyBytes[i + 24] = static_cast<uint8_t>(((h1 + h2) >> (i * 8)) & 0xFF);
+    }
+    return std::string(reinterpret_cast<const char*>(keyBytes), 32);
+}
+
+std::string SmbCredentialsManager::encryptPassword(const std::string& plain,
+                                                   const std::string& key,
+                                                   std::string& outIvHex) const {
+    if (plain.empty()) {
+        outIvHex.clear();
+        return "";
+    }
+    uint8_t nonce[12];
+    std::random_device rd;
+    for (int i = 0; i < 12; ++i) {
+        nonce[i] = static_cast<uint8_t>(rd() & 0xFF);
+    }
+    outIvHex = toHex(nonce, 12);
+
+    std::vector<uint8_t> cipher(plain.length());
+    chacha20_crypt(reinterpret_cast<const uint8_t*>(key.data()), nonce, 1,
+                   reinterpret_cast<const uint8_t*>(plain.data()), cipher.data(), plain.length());
+    return toHex(cipher.data(), cipher.size());
+}
+
+std::string SmbCredentialsManager::decryptPassword(const std::string& cipherHex,
+                                                   const std::string& key,
+                                                   const std::string& ivHex) const {
+    if (cipherHex.empty() || ivHex.empty()) return "";
+    std::vector<uint8_t> cipher = fromHex(cipherHex);
+    std::vector<uint8_t> nonce = fromHex(ivHex);
+    if (cipher.empty() || nonce.size() != 12) return "";
+
+    std::string plain(cipher.size(), '\0');
+    chacha20_crypt(reinterpret_cast<const uint8_t*>(key.data()), nonce.data(), 1,
+                   cipher.data(), reinterpret_cast<uint8_t*>(plain.data()), cipher.size());
+    return plain;
+}
+
+void SmbCredentialsManager::load() {
+    std::lock_guard<std::mutex> lk(mutex_);
+    shares_.clear();
+
+    const std::string path = getStoragePath();
+    std::ifstream f(path);
+    if (!f.is_open()) {
+        return;
+    }
+
+    std::string content((std::istreambuf_iterator<char>(f)),
+                        std::istreambuf_iterator<char>());
+    f.close();
+
+    const std::string key = getDeviceKey();
+
+    // Lightweight robust JSON parser for share objects
+    std::size_t pos = 0;
+    while ((pos = content.find('{', pos)) != std::string::npos) {
+        std::size_t endObj = content.find('}', pos);
+        if (endObj == std::string::npos) break;
+
+        std::string obj = content.substr(pos, endObj - pos + 1);
+        pos = endObj + 1;
+
+        auto extractField = [&](const std::string& keyName) -> std::string {
+            const std::string pattern = "\"" + keyName + "\"";
+            std::size_t kpos = obj.find(pattern);
+            if (kpos == std::string::npos) return "";
+            std::size_t colon = obj.find(':', kpos + pattern.length());
+            if (colon == std::string::npos) return "";
+            std::size_t startVal = obj.find_first_not_of(" \t\r\n", colon + 1);
+            if (startVal == std::string::npos) return "";
+            if (obj[startVal] == '\"') {
+                std::size_t endQuote = obj.find('\"', startVal + 1);
+                if (endQuote != std::string::npos) {
+                    return obj.substr(startVal + 1, endQuote - startVal - 1);
+                }
+            } else {
+                std::size_t endVal = obj.find_first_of(",}\r\n", startVal);
+                return trim(obj.substr(startVal, endVal - startVal));
+            }
+            return "";
+        };
+
+        SmbShare s;
+        s.id = extractField("id");
+        s.name = extractField("name");
+        s.host = extractField("host");
+        s.share = extractField("share");
+        s.workgroup = extractField("workgroup");
+        if (s.workgroup.empty()) s.workgroup = "WORKGROUP";
+        s.username = extractField("username");
+        s.anonymous = (extractField("anonymous") == "true");
+
+        std::string passCipher = extractField("password_enc");
+        std::string passIv = extractField("iv");
+        if (!passCipher.empty() && !passIv.empty()) {
+            s.password = decryptPassword(passCipher, key, passIv);
+        }
+
+        if (!s.host.empty()) {
+            if (s.name.empty()) {
+                s.name = s.host + (!s.share.empty() ? ("/" + s.share) : "");
+            }
+            if (s.id.empty()) {
+                s.id = s.host + (!s.share.empty() ? ("/" + s.share) : "");
+            }
+            shares_.push_back(s);
+        }
+    }
+
+    PIXELVR_LOG_INFO("SmbCredentialsManager: Loaded %zu configured shares from %s",
+                     shares_.size(), path.c_str());
+}
+
+void SmbCredentialsManager::save() {
+    std::lock_guard<std::mutex> lk(mutex_);
+    const std::string path = getStoragePath();
+
+    std::error_code ec;
+    fs::path p(path);
+    fs::create_directories(p.parent_path(), ec);
+
+#if defined(__linux__) || defined(__APPLE__)
+    // Ensure configuration directory is protected (0700)
+    chmod(p.parent_path().string().c_str(), 0700);
+#endif
+
+    const std::string key = getDeviceKey();
+
+    std::ostringstream json;
+    json << "[\n";
+    for (std::size_t i = 0; i < shares_.size(); ++i) {
+        const auto& s = shares_[i];
+        std::string ivHex;
+        std::string encPass = encryptPassword(s.password, key, ivHex);
+
+        json << "  {\n";
+        json << "    \"id\": \"" << s.id << "\",\n";
+        json << "    \"name\": \"" << s.name << "\",\n";
+        json << "    \"host\": \"" << s.host << "\",\n";
+        json << "    \"share\": \"" << s.share << "\",\n";
+        json << "    \"workgroup\": \"" << s.workgroup << "\",\n";
+        json << "    \"username\": \"" << s.username << "\",\n";
+        json << "    \"password_enc\": \"" << encPass << "\",\n";
+        json << "    \"iv\": \"" << ivHex << "\",\n";
+        json << "    \"anonymous\": " << (s.anonymous ? "true" : "false") << "\n";
+        json << "  }" << (i + 1 < shares_.size() ? ",\n" : "\n");
+    }
+    json << "]\n";
+
+    std::ofstream f(path, std::ios::trunc);
+    if (f.is_open()) {
+        f << json.str();
+        f.close();
+
+#if defined(__linux__) || defined(__APPLE__)
+        // Enforce strict OS-level permissions: readable & writable ONLY by steamos (0600)
+        chmod(path.c_str(), 0600);
+#endif
+        PIXELVR_LOG_INFO("SmbCredentialsManager: Saved %zu shares to %s (mode 0600)",
+                         shares_.size(), path.c_str());
+    } else {
+        PIXELVR_LOG_WARN("SmbCredentialsManager: Failed to write %s", path.c_str());
+    }
+}
+
+std::vector<SmbShare> SmbCredentialsManager::shares() const {
+    std::lock_guard<std::mutex> lk(mutex_);
+    return shares_;
+}
+
+void SmbCredentialsManager::addOrUpdateShare(const SmbShare& share) {
+    if (share.host.empty()) return;
+
+    {
+        std::lock_guard<std::mutex> lk(mutex_);
+        bool found = false;
+        for (auto& s : shares_) {
+            if (s.host == share.host && s.share == share.share) {
+                s = share;
+                found = true;
+                break;
+            }
+        }
+        if (!found) {
+            shares_.push_back(share);
+        }
+    }
+    save();
+}
+
+bool SmbCredentialsManager::deleteShare(const std::string& host, const std::string& share) {
+    bool removed = false;
+    {
+        std::lock_guard<std::mutex> lk(mutex_);
+        auto it = std::remove_if(shares_.begin(), shares_.end(), [&](const SmbShare& s) {
+            if (s.host == host) {
+                if (share.empty() || s.share == share || s.share.empty()) {
+                    return true;
+                }
+            }
+            return false;
+        });
+        if (it != shares_.end()) {
+            shares_.erase(it, shares_.end());
+            removed = true;
+        }
+    }
+    if (removed) {
+        save();
+        PIXELVR_LOG_INFO("SmbCredentialsManager: Deleted share for host '%s'", host.c_str());
+    }
+    return removed;
+}
+
+bool SmbCredentialsManager::findShare(const std::string& hostIn,
+                                      const std::string& shareIn,
+                                      SmbShare& outShare) const {
+    std::lock_guard<std::mutex> lk(mutex_);
+    if (hostIn.empty()) return false;
+
+    std::string host = hostIn;
+    std::transform(host.begin(), host.end(), host.begin(), ::tolower);
+    std::string share = shareIn;
+    std::transform(share.begin(), share.end(), share.begin(), ::tolower);
+
+    for (const auto& s : shares_) {
+        std::string sHost = s.host;
+        std::transform(sHost.begin(), sHost.end(), sHost.begin(), ::tolower);
+        if (sHost == host) {
+            std::string sShare = s.share;
+            std::transform(sShare.begin(), sShare.end(), sShare.begin(), ::tolower);
+            if (sShare == share || (share.empty() && sShare.empty())) {
+                outShare = s;
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+bool SmbCredentialsManager::findCredentials(const std::string& hostIn,
+                                           const std::string& shareIn,
+                                           std::string& outUser,
+                                           std::string& outPass,
+                                           std::string& outWorkgroup) const {
+    std::lock_guard<std::mutex> lk(mutex_);
+    if (hostIn.empty()) return false;
+
+    std::string host = hostIn;
+    std::transform(host.begin(), host.end(), host.begin(), ::tolower);
+    std::string share = shareIn;
+    std::transform(share.begin(), share.end(), share.begin(), ::tolower);
+
+    const SmbShare* bestMatch = nullptr;
+    for (const auto& s : shares_) {
+        std::string sHost = s.host;
+        std::transform(sHost.begin(), sHost.end(), sHost.begin(), ::tolower);
+        if (sHost == host) {
+            std::string sShare = s.share;
+            std::transform(sShare.begin(), sShare.end(), sShare.begin(), ::tolower);
+            if (!share.empty() && sShare == share) {
+                bestMatch = &s; // Exact share match takes highest priority
+                break;
+            }
+            if (sShare.empty() && !bestMatch) {
+                bestMatch = &s; // Host-level wildcard match
+            }
+        }
+    }
+
+    if (bestMatch && !bestMatch->anonymous) {
+        outUser = bestMatch->username;
+        outPass = bestMatch->password;
+        outWorkgroup = bestMatch->workgroup.empty() ? "WORKGROUP" : bestMatch->workgroup;
+        return true;
+    }
+    return false;
+}
+
+std::string SmbCredentialsManager::getAuthFilePath(const std::string& host, const std::string& share) {
+    std::string user, pass, wg;
+    if (!findCredentials(host, share, user, pass, wg)) {
+        return "";
+    }
+    if (user.empty()) return "";
+
+    std::string basePath = getStoragePath();
+    fs::path p(basePath);
+    std::string safeHost = host;
+    for (char& c : safeHost) {
+        if (!isalnum(c)) c = '_';
+    }
+    fs::path authFile = p.parent_path() / ("auth_" + safeHost + ".tmp");
+
+    std::ofstream f(authFile.string(), std::ios::trunc);
+    if (!f.is_open()) return "";
+
+    f << "username = " << user << "\n";
+    f << "password = " << pass << "\n";
+    f << "domain = " << (wg.empty() ? "WORKGROUP" : wg) << "\n";
+    f.close();
+
+#if defined(__linux__) || defined(__APPLE__)
+    chmod(authFile.string().c_str(), 0600);
+#endif
+    return authFile.string();
+}
+
+} // namespace pixelvr

src/net/smb_credentials.hpp

@@ -0,0 +1,69 @@
+#pragma once
+
+#include <string>
+#include <vector>
+#include <mutex>
+
+namespace pixelvr {
+
+struct SmbShare {
+    std::string id;         // Unique identifier (typically host or host:share)
+    std::string name;       // User-friendly display label (e.g. "Home NAS")
+    std::string host;       // IP address or hostname (e.g. "192.168.1.50")
+    std::string share;      // Optional default share name (e.g. "movies", or empty for all)
+    std::string workgroup;  // Workgroup/Domain (defaults to "WORKGROUP")
+    std::string username;   // SMB Username (or empty for anonymous)
+    std::string password;   // SMB Password (decrypted in memory, encrypted on disk)
+    bool anonymous = false; // True for guest / public shares
+};
+
+class SmbCredentialsManager {
+public:
+    static SmbCredentialsManager& instance();
+
+    // Loads configured shares from ~/.config/pixelvr/smb_shares.json
+    void load();
+
+    // Saves configured shares to ~/.config/pixelvr/smb_shares.json with strict 0600 permissions
+    void save();
+
+    // Returns all configured SMB shares
+    std::vector<SmbShare> shares() const;
+
+    // Adds a new share or updates an existing one (matched by host + share)
+    void addOrUpdateShare(const SmbShare& share);
+
+    // Deletes a configured share and wipes its stored credentials
+    bool deleteShare(const std::string& host, const std::string& share = "");
+
+    // Lookup a configured share
+    bool findShare(const std::string& host,
+                   const std::string& share,
+                   SmbShare& outShare) const;
+
+    // Lookup credentials for a given host and optional share
+    bool findCredentials(const std::string& host,
+                         const std::string& share,
+                         std::string& outUser,
+                         std::string& outPass,
+                         std::string& outWorkgroup) const;
+
+    // Generates or updates a secure temporary Samba auth file (mode 0600) for smbclient -A
+    // Returns the absolute file path, or empty string if anonymous / no credentials.
+    std::string getAuthFilePath(const std::string& host, const std::string& share);
+
+private:
+    SmbCredentialsManager();
+    ~SmbCredentialsManager() = default;
+
+    std::string getStoragePath() const;
+    std::string getDeviceKey() const;
+
+    std::string encryptPassword(const std::string& plain, const std::string& key, std::string& outIv) const;
+    std::string decryptPassword(const std::string& cipherHex, const std::string& key, const std::string& ivHex) const;
+
+    mutable std::mutex mutex_;
+    std::vector<SmbShare> shares_;
+};
+
+} // namespace pixelvr

src/ui/browser.cpp

@@ -1,4 +1,6 @@
 #include "ui/browser.hpp"
+#include "app/vault_manager.hpp"
+#include "net/smb_credentials.hpp"
 
 #include "util/logging.hpp"
 #include "util/smb_lock.hpp"
@@ -7,7 +9,9 @@
 #include <cctype>
 #include <cstdio>
 #include <cstdlib>
+#include <cstring>
 #include <filesystem>
+#include <fstream>
 #include <functional>
 #include <mutex>
 #include <set>
@@ -47,8 +51,24 @@ bool is_video(const std::string& name) {
 }
 
 #ifdef PIXELVR_HAVE_SMB
-void smb_auth(const char*, const char*, char*, int, char* user, int userLen,
+void smb_auth(const char* srv, const char* shr, char* wg, int wgLen, char* user, int userLen,
               char* pass, int passLen) {
+    std::string u, p, w;
+    if (srv != nullptr && SmbCredentialsManager::instance().findCredentials(srv, shr ? shr : "", u, p, w)) {
+        if (user && userLen > 0) {
+            std::strncpy(user, u.c_str(), userLen - 1);
+            user[userLen - 1] = '\0';
+        }
+        if (pass && passLen > 0) {
+            std::strncpy(pass, p.c_str(), passLen - 1);
+            pass[passLen - 1] = '\0';
+        }
+        if (wg && wgLen > 0 && !w.empty()) {
+            std::strncpy(wg, w.c_str(), wgLen - 1);
+            wg[wgLen - 1] = '\0';
+        }
+        return;
+    }
     if (user != nullptr && userLen > 0) user[0] = '\0';  // anonymous / guest
     if (pass != nullptr && passLen > 0) pass[0] = '\0';
 }
@@ -99,6 +119,8 @@ Browser::Browser() {
     const char* home = std::getenv("HOME");
     homeDir_ = (home != nullptr) ? home : "/home/steamos";
     downloadDir_ = homeDir_ + "/media";
+    quickPath_ = homeDir_ + "/Videos";
+    loadBookmarks();
 }
 
 void Browser::open() {
@@ -144,7 +166,11 @@ std::string format_size(long long bytes) {
 void Browser::scanLocalInto(const std::string& dir, ScanResult& out) {
     out.inSmb = false;
     out.location = dir;
-    out.title = dir;
+    if (VaultManager::instance().isVaultPath(dir)) {
+        out.title = "Vault (Private)";
+    } else {
+        out.title = dir;
+    }
     out.entries.clear();
 
     if (dir == homeDir_) {
@@ -283,10 +309,31 @@ void Browser::scanSmbInto(const std::string& uri, ScanResult& out) {
     }
 
     // NetBIOS browsing often misses modern servers; augment the network root with
-    // mDNS-advertised SMB hosts (NAS, macOS, Samba+avahi). The slow network probe
-    // runs OUTSIDE the SMB lock (it is not a libsmbclient call).
+    // configured manual shares and mDNS-advertised SMB hosts (NAS, macOS, Samba+avahi).
     if (uri == "smb://") {
         std::set<std::string> seen;
+        // The very first entry in the SMB list is the "+ Add SMB Share" button!
+        dirs.push_back({"+ Add SMB Share", "smb://__add_share__", true, false, false, false, "Configure New Network Share"});
+        seen.insert("smb://__add_share__");
+
+        // Prepend all user-configured manual SMB shares so private/unadvertised shares always appear
+        const auto configuredShares = SmbCredentialsManager::instance().shares();
+        for (const auto& s : configuredShares) {
+            if (s.host.empty()) continue;
+            std::string child = "smb://" + s.host;
+            if (!s.share.empty()) {
+                if (child.back() != '/') child += '/';
+                child += s.share;
+            }
+            if (!seen.insert(child).second) continue;
+            std::string label = s.name.empty() ? s.host : s.name;
+            std::string detail = s.anonymous ? "Configured (Guest)" : "Configured (Protected)";
+            if (!s.share.empty()) {
+                dirs.push_back({label + "  (" + s.host + "/" + s.share + ")", child, true, false, false, false, detail});
+            } else {
+                dirs.push_back({label + "  (" + s.host + ")", child, true, false, false, false, detail});
+            }
+        }
         for (const auto& d : dirs) seen.insert(d.path);
         FILE* pipe = popen("timeout 4 avahi-browse -trp _smb._tcp 2>/dev/null", "r");
         if (pipe != nullptr) {
@@ -400,9 +447,299 @@ void Browser::openDrives() {
     }
 }
 
+void Browser::openVault() {
+    if (!VaultManager::instance().isUnlocked()) return;
+    VaultManager::instance().ensureDirectories();
+    openPath(VaultManager::instance().vaultDir());
+}
+
+void Browser::openBookmarks() {
+    open_ = true;
+    browseOpen_.store(true);
+    status_.clear();
+    beginScan("bookmarks://", false);
+}
+
+void Browser::addBookmark(const std::string& path, const std::string& label) {
+    if (path.empty() || path == "bookmarks://" || path == "smb://__add_share__") return;
+    for (auto& b : bookmarks_) {
+        if (b.path == path) return;
+    }
+    std::string l = label;
+    if (l.empty()) {
+        if (path.rfind("smb://", 0) == 0) {
+            std::string rest = path.substr(6);
+            while (!rest.empty() && rest.back() == '/') rest.pop_back();
+            l = rest;
+        } else {
+            fs::path p(path);
+            l = p.filename().string();
+            if (l.empty()) l = path;
+        }
+    }
+    bookmarks_.push_back({path, l});
+    quickPath_ = path;
+    saveBookmarks();
+    if (location_ == "bookmarks://") {
+        beginScan("bookmarks://", false);
+    }
+}
+
+void Browser::removeBookmark(const std::string& path) {
+    auto it = std::remove_if(bookmarks_.begin(), bookmarks_.end(), [&](const Bookmark& b) {
+        return b.path == path;
+    });
+    if (it != bookmarks_.end()) {
+        bookmarks_.erase(it, bookmarks_.end());
+        saveBookmarks();
+        if (location_ == "bookmarks://") {
+            beginScan("bookmarks://", false);
+        }
+    }
+}
+
+bool Browser::isBookmarked(const std::string& path) const {
+    if (path.empty() || path == "bookmarks://") return false;
+    for (const auto& b : bookmarks_) {
+        if (b.path == path) return true;
+    }
+    return false;
+}
+
+void Browser::loadBookmarks() {
+    bookmarks_.clear();
+    const char* home = std::getenv("HOME");
+    std::string path = std::string(home ? home : ".") + "/.config/pixelvr/bookmarks.json";
+    std::ifstream f(path);
+    if (f.is_open()) {
+        std::string content((std::istreambuf_iterator<char>(f)), std::istreambuf_iterator<char>());
+        f.close();
+
+        std::size_t pos = 0;
+        while ((pos = content.find('{', pos)) != std::string::npos) {
+            std::size_t endObj = content.find('}', pos);
+            if (endObj == std::string::npos) break;
+            std::string obj = content.substr(pos, endObj - pos + 1);
+            pos = endObj + 1;
+
+            auto extract = [&](const std::string& key) -> std::string {
+                std::string pat = "\"" + key + "\"";
+                auto kpos = obj.find(pat);
+                if (kpos == std::string::npos) return "";
+                auto col = obj.find(':', kpos + pat.length());
+                if (col == std::string::npos) return "";
+                auto q1 = obj.find('\"', col + 1);
+                if (q1 == std::string::npos) return "";
+                auto q2 = obj.find('\"', q1 + 1);
+                if (q2 == std::string::npos) return "";
+                return obj.substr(q1 + 1, q2 - q1 - 1);
+            };
+            std::string bPath = extract("path");
+            std::string bLabel = extract("label");
+            if (!bPath.empty()) {
+                bookmarks_.push_back({bPath, bLabel});
+            }
+        }
+    }
+
+    if (bookmarks_.empty() && !quickPath_.empty()) {
+        addBookmark(quickPath_);
+    }
+}
+
+void Browser::saveBookmarks() const {
+    const char* home = std::getenv("HOME");
+    std::string configDir = std::string(home ? home : ".") + "/.config/pixelvr";
+    std::error_code ec;
+    std::filesystem::create_directories(configDir, ec);
+
+    std::string path = configDir + "/bookmarks.json";
+    std::ofstream f(path, std::ios::trunc);
+    if (!f.is_open()) return;
+
+    f << "[\n";
+    for (std::size_t i = 0; i < bookmarks_.size(); ++i) {
+        f << "  {\n";
+        f << "    \"path\": \"" << bookmarks_[i].path << "\",\n";
+        f << "    \"label\": \"" << bookmarks_[i].label << "\"\n";
+        f << "  }" << (i + 1 < bookmarks_.size() ? ",\n" : "\n");
+    }
+    f << "]\n";
+    f.close();
+}
+
+void Browser::scanBookmarksInto(ScanResult& out) {
+    out.inSmb = false;
+    out.location = "bookmarks://";
+    out.title = "Bookmarks";
+    out.entries.clear();
+    out.entries.push_back({".. (Home)", homeDir_, true, false, true, false});
+
+    if (bookmarks_.empty()) {
+        out.status = "No bookmarks yet. Click [+ Bookmark] in any folder to add one.";
+        return;
+    }
+
+    out.status = std::to_string(bookmarks_.size()) + (bookmarks_.size() == 1 ? " bookmark" : " bookmarks");
+
+    for (const auto& bm : bookmarks_) {
+        if (bm.path.empty()) continue;
+        const bool isSmb = (bm.path.rfind("smb://", 0) == 0);
+        std::error_code ec;
+        const bool isDir = isSmb || fs::is_directory(bm.path, ec);
+        std::string label = bm.label;
+        if (label.empty()) {
+            if (isSmb) {
+                label = bm.path.substr(6);
+                while (!label.empty() && label.back() == '/') label.pop_back();
+            } else {
+                fs::path p(bm.path);
+                label = p.filename().string();
+                if (label.empty()) label = bm.path;
+            }
+        }
+        std::string detail = isSmb ? "SMB Share" : (isDir ? "Folder" : "Video File");
+        std::string previewPath = isDir ? "" : bm.path;
+        out.entries.push_back({label, bm.path, isDir, !isDir && is_video(bm.path), false, isSmb, detail, 0, previewPath});
+    }
+}
+
+bool Browser::inVault() const {
+    return VaultManager::instance().isVaultPath(location_);
+}
+
+bool Browser::moveFocusedToVault(std::string& outNewPath) {
+    if (!VaultManager::instance().isUnlocked()) return false;
+    const Entry* e = focused();
+    if (e == nullptr || e->isBack || inSmb_) return false;
+    std::string err = VaultManager::instance().moveFileToVault(e->path, outNewPath);
+    if (!err.empty()) {
+        status_ = "Move error: " + err;
+        return false;
+    }
+    status_ = "Moved " + e->label + " to Vault";
+    beginScan(location_, inSmb_);
+    return true;
+}
+
+bool Browser::moveFocusedTo(const std::string& destDir, std::string& outNewPath) {
+    const Entry* e = focused();
+    if (e == nullptr || e->isBack || inSmb_) return false;
+    std::error_code ec;
+    if (!fs::exists(destDir, ec) || !fs::is_directory(destDir, ec)) {
+        status_ = "Destination folder does not exist";
+        return false;
+    }
+    fs::path src(e->path);
+    const bool isDir = fs::is_directory(src, ec);
+    std::string stem = src.stem().string();
+    std::string ext = isDir ? "" : src.extension().string();
+    std::string targetFilename = src.filename().string();
+    fs::path dest = fs::path(destDir) / targetFilename;
+
+    int counter = 1;
+    while (fs::exists(dest, ec)) {
+        targetFilename = isDir ? (stem + "_" + std::to_string(counter++))
+                               : (stem + "_" + std::to_string(counter++) + ext);
+        dest = fs::path(destDir) / targetFilename;
+    }
+
+    fs::rename(src, dest, ec);
+    if (ec) {
+        ec.clear();
+        if (isDir) {
+            fs::copy(src, dest, fs::copy_options::recursive, ec);
+            if (ec) {
+                status_ = "Move failed: " + ec.message();
+                return false;
+            }
+            fs::remove_all(src, ec);
+        } else {
+            fs::copy_file(src, dest, fs::copy_options::overwrite_existing, ec);
+            if (ec) {
+                status_ = "Move failed: " + ec.message();
+                return false;
+            }
+            fs::remove(src, ec);
+        }
+    }
+    outNewPath = dest.string();
+    status_ = "Moved " + e->label + " to " + fs::path(destDir).filename().string();
+    beginScan(location_, inSmb_);
+    return true;
+}
+
+bool Browser::deleteFocused(std::string& deletedName) {
+    const Entry* e = focused();
+    if (e == nullptr || e->isBack || inSmb_) return false;
+    std::error_code ec;
+    deletedName = e->label;
+    fs::path p(e->path);
+    VaultManager::instance().cleanPublicThumbs(e->path);
+    if (fs::is_directory(p, ec)) {
+        fs::remove_all(p, ec);
+    } else {
+        fs::remove(p, ec);
+    }
+    if (ec) {
+        status_ = "Delete failed: " + ec.message();
+        return false;
+    }
+    status_ = "Deleted " + deletedName;
+    beginScan(location_, inSmb_);
+    return true;
+}
+
+bool Browser::renameFocused(const std::string& newName) {
+    const Entry* e = focused();
+    if (e == nullptr || e->isBack || inSmb_ || newName.empty()) return false;
+    std::error_code ec;
+    fs::path src(e->path);
+    fs::path dest = src.parent_path() / newName;
+    if (dest == src) return true; // unchanged
+    if (fs::exists(dest, ec)) {
+        status_ = "An item with that name already exists";
+        return false;
+    }
+    fs::rename(src, dest, ec);
+    if (ec) {
+        status_ = "Rename failed: " + ec.message();
+        return false;
+    }
+    status_ = "Renamed to " + newName;
+    beginScan(location_, inSmb_);
+    return true;
+}
+
+std::string Browser::parentDir() const {
+    if (location_ == "bookmarks://") return homeDir_;
+    if (location_.empty() || location_ == "/" || inSmb_) return "";
+    fs::path p(location_);
+    return p.parent_path().string();
+}
+
+std::string Browser::homeDir() const {
+    const char* h = std::getenv("HOME");
+    return h ? std::string(h) : "/";
+}
+
+std::string Browser::videosDir() const {
+    std::string d = homeDir() + "/Videos";
+    std::error_code ec;
+    return fs::is_directory(d, ec) ? d : homeDir();
+}
+
+std::string Browser::downloadsDir() const {
+    std::string d = homeDir() + "/Downloads";
+    std::error_code ec;
+    return fs::is_directory(d, ec) ? d : homeDir();
+}
+
 void Browser::runScan(std::string location, bool isSmb) {
     ScanResult r;
-    if (isSmb) {
+    if (location == "bookmarks://") {
+        scanBookmarksInto(r);
+    } else if (isSmb) {
         scanSmbInto(location, r);
     } else {
         scanLocalInto(location, r);
@@ -424,6 +761,10 @@ Browser::Result Browser::activate(std::string& playPath) {
     const Entry e = entries_[static_cast<std::size_t>(selected_)];
 
     if (e.isBack) {
+        if (location_ == "bookmarks://") {
+            beginScan(homeDir_, false);
+            return Result::Navigated;
+        }
         if (inSmb_) {
             const std::string parent = smb_parent(location_);
             if (parent.empty()) {
@@ -432,17 +773,30 @@ Browser::Result Browser::activate(std::string& playPath) {
                 beginScan(parent, true);
             }
         } else {
-            const fs::path p(location_);
-            beginScan(p.has_parent_path() ? p.parent_path().string() : "/", false);
+            if (VaultManager::instance().isVaultPath(location_)) {
+                if (location_ == VaultManager::instance().vaultDir()) {
+                    beginScan(homeDir_, false);
+                } else {
+                    const fs::path p(location_);
+                    beginScan(p.has_parent_path() ? p.parent_path().string() : homeDir_, false);
+                }
+            } else {
+                const fs::path p(location_);
+                beginScan(p.has_parent_path() ? p.parent_path().string() : "/", false);
+            }
         }
         return Result::Navigated;
     }
+    if (e.path == "smb://__add_share__") {
+        return Result::AddSmbShare;
+    }
     if (e.isNetwork) {
         beginScan("smb://", true);
         return Result::Navigated;
     }
     if (e.isDir) {
-        beginScan(e.path, inSmb_);
+        const bool isSmb = e.isNetwork || (e.path.rfind("smb://", 0) == 0);
+        beginScan(e.path, isSmb);
         return Result::Navigated;
     }
     if (e.isVideo) {
@@ -457,7 +811,7 @@ Browser::Result Browser::activate(std::string& playPath) {
 }
 
 bool Browser::downloadFocused() {
-    if (dlActive_.load() || selected_ < 0 ||
+    if (selected_ < 0 ||
         selected_ >= static_cast<int>(entries_.size())) {
         return false;
     }
@@ -488,19 +842,36 @@ Browser::~Browser() {
 
 void Browser::startDownload(const std::string& uri, const std::string& nameIn,
                             bool isDir) {
-    if (dlActive_.load()) return;
     std::string name = nameIn;
     while (!name.empty() && name.back() == '/') name.pop_back();
     const std::size_t slash = name.find_last_of('/');
     if (slash != std::string::npos) name = name.substr(slash + 1);
     if (name.empty()) return;
-    dlName_ = name;
+
+    for (const auto& j : dlJobs_) {
+        if (j.uri == uri && (j.state == 0 || j.state == 4)) {
+            status_ = "Already downloading or in queue: " + name;
+            return;
+        }
+    }
+
     const std::string destDir =
         downloadDir_.empty() ? homeDir_ + "/media" : downloadDir_;
+    const std::string targetPath = destDir + "/" + name;
+
+    if (dlActive_.load()) {
+        dlQueue_.push_back({uri, name, targetPath, isDir});
+        dlJobs_.push_back({name, targetPath, uri, 4, 0, 0, isDir});
+        status_ = "Added to download queue: " + name;
+        PIXELVR_LOG_INFO("Added to download queue: %s (%s)", name.c_str(), uri.c_str());
+        return;
+    }
+
+    dlName_ = name;
     if (isDir) {
-        startDownloadFolder(uri, destDir + "/" + name);
+        startDownloadFolder(uri, targetPath);
     } else {
-        startDownloadFile(uri, destDir + "/" + name);
+        startDownloadFile(uri, targetPath);
     }
 }
 
@@ -528,11 +899,33 @@ void Browser::startDownloadFile(const std::string& uri, const std::string& local
     dlActive_.store(true);
     status_ = "Downloading " + dlName_ + " ...";
     PIXELVR_LOG_INFO("Download file: %s -> %s", uri.c_str(), local.c_str());
-    dlJobs_.push_back({dlName_, local, uri, 0, 0, 0, false});
-    dlActiveJob_ = static_cast<int>(dlJobs_.size()) - 1;
-    if (dlJobs_.size() > 12) {
-        dlJobs_.erase(dlJobs_.begin());
+
+    int existingIdx = -1;
+    for (std::size_t i = 0; i < dlJobs_.size(); ++i) {
+        if (dlJobs_[i].uri == uri && (dlJobs_[i].state == 4 || dlJobs_[i].state == 0)) {
+            existingIdx = static_cast<int>(i);
+            dlJobs_[i].state = 0;
+            dlJobs_[i].name = dlName_;
+            dlJobs_[i].localPath = local;
+            break;
+        }
+    }
+    if (existingIdx >= 0) {
+        dlActiveJob_ = existingIdx;
+    } else {
+        dlJobs_.push_back({dlName_, local, uri, 0, 0, 0, false});
         dlActiveJob_ = static_cast<int>(dlJobs_.size()) - 1;
+        if (dlJobs_.size() > 16) {
+            for (auto it = dlJobs_.begin(); it != dlJobs_.end(); ++it) {
+                if (it->state != 0 && it->state != 4) {
+                    dlJobs_.erase(it);
+                    break;
+                }
+            }
+            for (std::size_t i = 0; i < dlJobs_.size(); ++i) {
+                if (dlJobs_[i].state == 0) dlActiveJob_ = static_cast<int>(i);
+            }
+        }
     }
     const std::string name = dlName_;
     dlLocalPath_ = local;
@@ -604,6 +997,8 @@ int Browser::spawnCurl(const std::string& uri, const std::string& local) {
     const std::size_t s2 =
         (s1 == std::string::npos) ? std::string::npos : rest.find('/', s1 + 1);
     if (s2 == std::string::npos) return -1;
+    const std::string host = rest.substr(0, s1);
+    const std::string share = rest.substr(s1 + 1, s2 - s1 - 1);
     const std::string service = "//" + rest.substr(0, s2);
     const std::string remote = rest.substr(s2 + 1);
     std::string cmd = "get \"";
@@ -611,14 +1006,26 @@ int Browser::spawnCurl(const std::string& uri, const std::string& local) {
     cmd += "\" \"";
     cmd += local;
     cmd += "\"";
-    PIXELVR_LOG_INFO("DL spawn: smbclient %s -N -c '%s'", service.c_str(),
-                     cmd.c_str());
-    char* argv[] = {const_cast<char*>("smbclient"),
-                    const_cast<char*>(service.c_str()),
-                    const_cast<char*>("-N"),
-                    const_cast<char*>("-c"),
-                    const_cast<char*>(cmd.c_str()),
-                    nullptr};
+
+    std::string authFile = SmbCredentialsManager::instance().getAuthFilePath(host, share);
+    PIXELVR_LOG_INFO("DL spawn: smbclient %s %s -c '%s'", service.c_str(),
+                     authFile.empty() ? "-N" : ("-A " + authFile).c_str(), cmd.c_str());
+
+    char* argv[8] = {nullptr};
+    argv[0] = const_cast<char*>("smbclient");
+    argv[1] = const_cast<char*>(service.c_str());
+    if (!authFile.empty()) {
+        argv[2] = const_cast<char*>("-A");
+        argv[3] = const_cast<char*>(authFile.c_str());
+        argv[4] = const_cast<char*>("-c");
+        argv[5] = const_cast<char*>(cmd.c_str());
+        argv[6] = nullptr;
+    } else {
+        argv[2] = const_cast<char*>("-N");
+        argv[3] = const_cast<char*>("-c");
+        argv[4] = const_cast<char*>(cmd.c_str());
+        argv[5] = nullptr;
+    }
     posix_spawn_file_actions_t fa;
     posix_spawn_file_actions_init(&fa);
     // Take stdin from /dev/null so smbclient can never block on an auth prompt.
@@ -652,11 +1059,32 @@ void Browser::startDownloadFolder(const std::string& uri,
     dlStopped_.store(false);
     dlPaused_.store(false);
     dlAbort_.store(false);
-    dlJobs_.push_back({dlName_, destDir, uri, 0, 0, 0, true});
-    dlActiveJob_ = static_cast<int>(dlJobs_.size()) - 1;
-    if (dlJobs_.size() > 12) {
-        dlJobs_.erase(dlJobs_.begin());
+    int existingIdx = -1;
+    for (std::size_t i = 0; i < dlJobs_.size(); ++i) {
+        if (dlJobs_[i].uri == uri && (dlJobs_[i].state == 4 || dlJobs_[i].state == 0)) {
+            existingIdx = static_cast<int>(i);
+            dlJobs_[i].state = 0;
+            dlJobs_[i].name = dlName_;
+            dlJobs_[i].localPath = destDir;
+            break;
+        }
+    }
+    if (existingIdx >= 0) {
+        dlActiveJob_ = existingIdx;
+    } else {
+        dlJobs_.push_back({dlName_, destDir, uri, 0, 0, 0, true});
         dlActiveJob_ = static_cast<int>(dlJobs_.size()) - 1;
+        if (dlJobs_.size() > 16) {
+            for (auto it = dlJobs_.begin(); it != dlJobs_.end(); ++it) {
+                if (it->state != 0 && it->state != 4) {
+                    dlJobs_.erase(it);
+                    break;
+                }
+            }
+            for (std::size_t i = 0; i < dlJobs_.size(); ++i) {
+                if (dlJobs_[i].state == 0) dlActiveJob_ = static_cast<int>(i);
+            }
+        }
     }
     dlThread_ = std::thread([this, uri, destDir]() {
         std::error_code ec;
@@ -829,8 +1257,8 @@ void Browser::clearFinished() {
     std::vector<DownloadJob> keep;
     keep.reserve(dlJobs_.size());
     for (const DownloadJob& j : dlJobs_) {
-        if (j.state == 0) {
-            keep.push_back(j);  // keep the in-flight job
+        if (j.state == 0 || j.state == 4) {
+            keep.push_back(j);  // keep the in-flight and queued jobs
             continue;
         }
         // Remove partial files from stopped/failed single-file downloads.
@@ -847,6 +1275,38 @@ void Browser::clearFinished() {
     status_ = "Cleared finished downloads";
 }
 
+void Browser::cancelQueued(const std::string& uri) {
+    for (auto it = dlQueue_.begin(); it != dlQueue_.end(); ++it) {
+        if (it->uri == uri) {
+            dlQueue_.erase(it);
+            break;
+        }
+    }
+    for (auto it = dlJobs_.begin(); it != dlJobs_.end(); ++it) {
+        if (it->uri == uri && it->state == 4) {
+            dlJobs_.erase(it);
+            break;
+        }
+    }
+    status_ = "Removed from download queue";
+}
+
+void Browser::startNextQueued() {
+    if (dlActive_.load()) return;
+    if (dlQueue_.empty()) return;
+
+    DownloadQueueItem item = dlQueue_.front();
+    dlQueue_.pop_front();
+
+    dlName_ = item.name;
+    PIXELVR_LOG_INFO("Starting next queued download: %s (%s)", item.name.c_str(), item.uri.c_str());
+    if (item.isDir) {
+        startDownloadFolder(item.uri, item.destDir);
+    } else {
+        startDownloadFile(item.uri, item.destDir);
+    }
+}
+
 void Browser::measureFolder(const std::string& uri) {
 #ifdef PIXELVR_HAVE_SMB
     if (measuring_.load()) return;
@@ -984,6 +1444,7 @@ Browser::Result Browser::poll(std::string& playPath) {
         } else {
             status_ = "Download failed: " + dlName_;
         }
+        startNextQueued();
     }
     return Result::None;
 }

src/ui/browser.hpp

@@ -2,6 +2,7 @@
 
 #include <atomic>
 #include <chrono>
+#include <deque>
 #include <mutex>
 #include <string>
 #include <thread>
@@ -25,7 +26,7 @@ public:
         long long size = 0;       // bytes (0 if unknown)
         std::string previewPath;  // video file inside folder or self (for thumbnail)
     };
-    enum class Result { None, Navigated, Play };
+    enum class Result { None, Navigated, Play, AddSmbShare };
 
     Browser();
 
@@ -40,6 +41,36 @@ public:
     void openVideos();
     void openDownloads();
     void openDrives();
+    void openVault();
+    struct Bookmark {
+        std::string path;
+        std::string label;
+    };
+    void openBookmarks();
+    void addBookmark(const std::string& path, const std::string& label = "");
+    void removeBookmark(const std::string& path);
+    bool isBookmarked(const std::string& path) const;
+    bool isCurrentBookmarked() const { return isBookmarked(location_); }
+    const std::vector<Bookmark>& bookmarks() const { return bookmarks_; }
+    void loadBookmarks();
+    void saveBookmarks() const;
+    bool onBookmarks() const { return location_ == "bookmarks://"; }
+
+    void openQuickPath() { openBookmarks(); }
+    void setQuickPath(const std::string& path) { addBookmark(path); }
+    const std::string& quickPath() const { return quickPath_; }
+    bool isCurrentQuickPath() const { return isCurrentBookmarked(); }
+    bool inVault() const;
+    bool moveFocusedToVault(std::string& outNewPath);
+    bool moveFocusedTo(const std::string& destDir, std::string& outNewPath);
+    bool deleteFocused(std::string& deletedName);
+    bool renameFocused(const std::string& newName);
+    const std::string& currentLocation() const { return location_; }
+    const std::string& currentPath() const { return location_; }
+    std::string parentDir() const;
+    std::string homeDir() const;
+    std::string videosDir() const;
+    std::string downloadsDir() const;
     bool isOpen() const { return open_; }
     // The download worker yields the shared SMB connection while the browser is
     // open, so directory listing stays responsive (downloads resume afterwards).
@@ -104,13 +135,21 @@ public:
         std::string name;
         std::string localPath;
         std::string uri;
-        int state = 0;  // 0 downloading, 1 done, 2 failed, 3 stopped
+        int state = 0;  // 0 downloading, 1 done, 2 failed, 3 stopped, 4 queued
         long long bytes = 0;
         long long total = 0;
         bool isDir = false;
     };
+    struct DownloadQueueItem {
+        std::string uri;
+        std::string name;
+        std::string destDir;
+        bool isDir = false;
+    };
     const std::vector<DownloadJob>& downloadJobs() const { return dlJobs_; }
     bool hasDownloads() const { return !dlJobs_.empty(); }
+    bool hasQueuedDownloads() const { return !dlQueue_.empty(); }
+    void cancelQueued(const std::string& uri);
     bool downloadPaused() const { return dlPaused_.load(); }
     void togglePause();   // SIGSTOP/SIGCONT the curl child
     void stopDownload();  // SIGKILL the child and drop the partial file
@@ -144,8 +183,10 @@ private:
     bool hasPendingScan_ = false;
     void scanLocalInto(const std::string& dir, ScanResult& out);
     void scanSmbInto(const std::string& uri, ScanResult& out);
+    void scanBookmarksInto(ScanResult& out);
     void startDownloadFile(const std::string& uri, const std::string& local);
     void startDownloadFolder(const std::string& uri, const std::string& name);
+    void startNextQueued();
 
     bool open_ = false;
     bool inSmb_ = false;
@@ -153,6 +194,8 @@ private:
     std::string status_;
     std::string location_;   // current local dir or smb:// URI
     std::string homeDir_;
+    std::string quickPath_;  // bookmarked folder for one-button jump
+    std::vector<Bookmark> bookmarks_;
     std::string lastLocation_;  // last folder visited (local or smb), for re-open
     bool lastInSmb_ = false;
     std::vector<Entry> entries_;
@@ -176,6 +219,7 @@ private:
     std::string dlName_;
     std::string downloadDir_;  // "" => default ~/media
     std::vector<DownloadJob> dlJobs_;
+    std::deque<DownloadQueueItem> dlQueue_;
     int dlActiveJob_ = -1;             // index of the job in flight, or -1
     std::atomic<bool> dlPaused_{false};
     std::atomic<bool> dlAbort_{false};

src/ui/settings_menu.cpp

@@ -1,4 +1,7 @@
 #include "ui/settings_menu.hpp"
+#include "app/vault_manager.hpp"
+#include "net/smb_credentials.hpp"
+#include "xr/vr_keyboard.hpp"
 
 #include "util/logging.hpp"
 
@@ -77,7 +80,7 @@ SettingsMenu::SettingsMenu() {
 
 void SettingsMenu::open() {
     open_ = true;
-    if (section_ < 0 || section_ > 3) section_ = 0;
+    if (section_ < 0 || (section_ > 5 && section_ != 20)) section_ = 0;
     refresh();
 }
 
@@ -141,6 +144,17 @@ void SettingsMenu::refresh() {
         rows_.push_back({"UI Panel Distance",
                          kUiDistanceNames[uiDistanceIdx_ % kUiDistanceCount],
                          Action::CycleUiDistance});
+        const char* followModeNames[2] = {"World Lock (Fixed)", "Smooth Gaze Follow"};
+        rows_.push_back({"UI Follow Mode",
+                         followModeNames[uiFollowMode_ % 2],
+                         Action::CycleUiFollowMode});
+        const char* viewModeNames[3] = {"Large Cards (3x2)", "Smaller Cards (4x3)", "Compact List (1-Col)"};
+        rows_.push_back({"Browser View Mode",
+                         viewModeNames[browserViewMode_ % 3],
+                         Action::CycleBrowserViewMode});
+        rows_.push_back({"Configure List Columns",
+                         "[ Customize Columns > ]",
+                         Action::EnterListColsConfig});
         rows_.push_back({"Download Folder",
                          kDownloadDirs[downloadDirIdx_ % kDownloadDirCount],
                          Action::CycleDownloadDir});
@@ -182,9 +196,52 @@ void SettingsMenu::refresh() {
                          Action::ListenMenu});
         rows_.push_back({"Recenter View", btnLabel(2, bindRecenterBtn_),
                          Action::ListenRecenter});
+        rows_.push_back({"Bookmarks Shortcut", btnLabel(4, bindQuickPathBtn_),
+                         Action::ListenQuickPath});
         rows_.push_back({"Select / Click", "Trigger", Action::None});
         rows_.push_back({"Controller Models", drawModels_ ? "On" : "Off",
                          Action::ToggleModels});
+    } else if (section_ == 4) {
+        title_ = "Settings > Vault & Privacy";
+        rows_.push_back({"Auto-Lock on Headset Removal",
+                         VaultManager::instance().autoLockHeadsetOff() ? "Enabled" : "Disabled",
+                         Action::CycleVaultAutoLockHeadset});
+
+        int toSec = VaultManager::instance().autoLockTimeoutSec();
+        std::string toStr = "Disabled";
+        if (toSec == 120) toStr = "2 Minutes";
+        else if (toSec == 300) toStr = "5 Minutes";
+        else if (toSec == 600) toStr = "10 Minutes";
+        rows_.push_back({"Inactivity Auto-Lock Timeout", toStr,
+                         Action::CycleVaultTimeout});
+
+        auto moveBtnLabel = [&]() -> std::string {
+            if (listeningFunc_ == 3) return "[ press a button ]";
+            int mb = VaultManager::instance().moveButton();
+            if (mb < 0 || mb >= kButtonCount) return "Disabled";
+            return kButtonNames[mb % kButtonCount];
+        };
+        rows_.push_back({"File Actions Button", moveBtnLabel(),
+                         Action::ListenVaultMoveBtn});
+
+        std::string comboLabel;
+        if (VaultManager::instance().isRecordingCombo()) {
+            comboLabel = "[ Recording: " + std::to_string(VaultManager::instance().recordedCount()) + "/6 ]";
+        } else {
+            comboLabel = VaultManager::instance().comboString();
+        }
+        rows_.push_back({"Unlock Combo Sequence", comboLabel,
+                         Action::RecordVaultCombo});
+
+        rows_.push_back({"Lock Vault Now", "[ Lock & Return Home ]",
+                         Action::LockVaultAction});
+    } else if (section_ == 21) {
+        title_ = "Settings > List Columns";
+        rows_.push_back({"Format / VR Badge", listShowFormat_ ? "Visible" : "Hidden", Action::ToggleListColFormat});
+        rows_.push_back({"Resolution & FPS", listShowRes_ ? "Visible" : "Hidden", Action::ToggleListColRes});
+        rows_.push_back({"File Size", listShowSize_ ? "Visible" : "Hidden", Action::ToggleListColSize});
+        rows_.push_back({"Video Duration", listShowDuration_ ? "Visible" : "Hidden", Action::ToggleListColDuration});
+        rows_.push_back({"< Back to UI & Appearance", "", Action::BackToUI});
     } else if (section_ == 10) {
         title_ = "Settings > Select Video Track";
         for (std::size_t i = 0; i < videoStreams_.size(); ++i) {
@@ -311,6 +368,21 @@ SettingsMenu::Action SettingsMenu::activate() {
             saveConfig();
             refresh();
             break;
+        case Action::CycleUiFollowMode:
+            uiFollowMode_ = (uiFollowMode_ + 1) % 2;
+            saveConfig();
+            refresh();
+            break;
+        case Action::CycleBrowserViewMode:
+            browserViewMode_ = (browserViewMode_ + 1) % 3;
+            saveConfig();
+            refresh();
+            break;
+        case Action::ListenQuickPath:
+            listeningFunc_ = 4;
+            status_ = "Press a controller button for Bookmarks shortcut";
+            refresh();
+            break;
         case Action::PickVideoStream:
             videoSel_ = rows_[selected_].data;
             section_ = 2;
@@ -330,6 +402,71 @@ SettingsMenu::Action SettingsMenu::activate() {
             selected_ = 0;
             refresh();
             break;
+        case Action::CycleVaultAutoLockHeadset:
+            VaultManager::instance().setAutoLockHeadsetOff(!VaultManager::instance().autoLockHeadsetOff());
+            refresh();
+            break;
+        case Action::CycleVaultTimeout: {
+            int to = VaultManager::instance().autoLockTimeoutSec();
+            if (to == 0) to = 120;
+            else if (to == 120) to = 300;
+            else if (to == 300) to = 600;
+            else to = 0;
+            VaultManager::instance().setAutoLockTimeoutSec(to);
+            refresh();
+            break;
+        }
+        case Action::ListenVaultMoveBtn:
+            listeningFunc_ = 3;
+            status_ = "Press a controller button for Move-to-Vault";
+            refresh();
+            break;
+        case Action::RecordVaultCombo:
+            if (VaultManager::instance().isRecordingCombo()) {
+                VaultManager::instance().cancelRecordingCombo();
+                status_ = "Combo recording cancelled";
+            } else {
+                VaultManager::instance().startRecordingCombo();
+                status_ = "Press 6 face buttons (A, B, X, Y) to record new combo";
+            }
+            refresh();
+            break;
+        case Action::LockVaultAction:
+            VaultManager::instance().lock();
+            section_ = 0;
+            refresh();
+            break;
+
+        case Action::EnterListColsConfig:
+            section_ = 21;
+            selected_ = 0;
+            refresh();
+            break;
+        case Action::ToggleListColFormat:
+            listShowFormat_ = !listShowFormat_;
+            refresh();
+            saveConfig();
+            break;
+        case Action::ToggleListColRes:
+            listShowRes_ = !listShowRes_;
+            refresh();
+            saveConfig();
+            break;
+        case Action::ToggleListColSize:
+            listShowSize_ = !listShowSize_;
+            refresh();
+            saveConfig();
+            break;
+        case Action::ToggleListColDuration:
+            listShowDuration_ = !listShowDuration_;
+            refresh();
+            saveConfig();
+            break;
+        case Action::BackToUI:
+            section_ = 1;
+            selected_ = 0;
+            refresh();
+            break;
         case Action::RecenterScreen:
             break;
         case Action::Close:
@@ -378,6 +515,8 @@ void SettingsMenu::assignListening(int button) {
     if (listeningFunc_ == 0) bindPlayBtn_ = b;
     else if (listeningFunc_ == 1) bindMenuBtn_ = b;
     else if (listeningFunc_ == 2) bindRecenterBtn_ = b;
+    else if (listeningFunc_ == 3) VaultManager::instance().setMoveButton(b);
+    else if (listeningFunc_ == 4) bindQuickPathBtn_ = b;
     listeningFunc_ = -1;
     status_ = "Bound to " + std::string(kButtonNames[b]);
     saveConfig();
@@ -435,6 +574,7 @@ void SettingsMenu::loadConfig() {
             // so a saved grip binding is migrated to the new default (Bumper).
             bindRecenterBtn_ = (b == 8) ? 6 : b;
         }
+        else if (key == "bind_quick_path_btn") bindQuickPathBtn_ = std::clamp(std::stoi(val), 0, kButtonCount - 1);
         else if (key == "download_dir") downloadDirIdx_ = std::clamp(std::stoi(val), 0, kDownloadDirCount - 1);
         else if (key == "audio_lang") audioLangIdx_ = std::clamp(std::stoi(val), 0, kLangCount - 1);
         else if (key == "curvature") curvatureIdx_ = std::clamp(std::stoi(val), 0, kCurvatureCount - 1);
@@ -442,6 +582,13 @@ void SettingsMenu::loadConfig() {
         else if (key == "ui_text_color") uiTextColorIdx_ = std::clamp(std::stoi(val), 0, kUiTextColorCount - 1);
         else if (key == "ui_accent_color") uiAccentColorIdx_ = std::clamp(std::stoi(val), 0, kUiAccentColorCount - 1);
         else if (key == "ui_distance") uiDistanceIdx_ = std::clamp(std::stoi(val), 0, kUiDistanceCount - 1);
+        else if (key == "ui_follow_mode") uiFollowMode_ = std::clamp(std::stoi(val), 0, 1);
+        else if (key == "browser_view_mode") browserViewMode_ = std::clamp(std::stoi(val), 0, 2);
+        else if (key == "list_show_format") listShowFormat_ = (val == "1" || val == "true");
+        else if (key == "list_show_res") listShowRes_ = (val == "1" || val == "true");
+        else if (key == "list_show_size") listShowSize_ = (val == "1" || val == "true");
+        else if (key == "list_show_dur") listShowDuration_ = (val == "1" || val == "true");
+        else if (key == "quick_path") quickPath_ = val;
     }
     PIXELVR_LOG_INFO("Loaded settings from %s", path.c_str());
 }
@@ -464,6 +611,7 @@ void SettingsMenu::saveConfig() const {
             file << "bind_play_btn=" << bindPlayBtn_ << "\n";
             file << "bind_menu_btn=" << bindMenuBtn_ << "\n";
             file << "bind_recenter_btn=" << bindRecenterBtn_ << "\n";
+            file << "bind_quick_path_btn=" << bindQuickPathBtn_ << "\n";
             file << "download_dir=" << downloadDirIdx_ << "\n";
             file << "audio_lang=" << audioLangIdx_ << "\n";
             file << "curvature=" << curvatureIdx_ << "\n";
@@ -471,6 +619,15 @@ void SettingsMenu::saveConfig() const {
             file << "ui_text_color=" << uiTextColorIdx_ << "\n";
             file << "ui_accent_color=" << uiAccentColorIdx_ << "\n";
             file << "ui_distance=" << uiDistanceIdx_ << "\n";
+            file << "ui_follow_mode=" << uiFollowMode_ << "\n";
+            file << "browser_view_mode=" << browserViewMode_ << "\n";
+            file << "list_show_format=" << (listShowFormat_ ? 1 : 0) << "\n";
+            file << "list_show_res=" << (listShowRes_ ? 1 : 0) << "\n";
+            file << "list_show_size=" << (listShowSize_ ? 1 : 0) << "\n";
+            file << "list_show_dur=" << (listShowDuration_ ? 1 : 0) << "\n";
+            if (!quickPath_.empty()) {
+                file << "quick_path=" << quickPath_ << "\n";
+            }
         }
     } catch (const std::exception& e) {
         PIXELVR_LOG_WARN("Could not save settings: %s", e.what());

src/ui/settings_menu.hpp

@@ -30,6 +30,9 @@ public:
         CycleUiTextColor,
         CycleUiAccentColor,
         CycleUiDistance,
+        CycleUiFollowMode,
+        CycleBrowserViewMode,
+        ListenQuickPath,
         EnterVideoList,
         EnterAudioList,
         EnterLangList,
@@ -37,6 +40,17 @@ public:
         PickAudioStream,
         PickLanguage,
         RecenterScreen,
+        CycleVaultAutoLockHeadset,
+        CycleVaultTimeout,
+        ListenVaultMoveBtn,
+        RecordVaultCombo,
+        LockVaultAction,
+        EnterListColsConfig,
+        ToggleListColFormat,
+        ToggleListColRes,
+        ToggleListColSize,
+        ToggleListColDuration,
+        BackToUI,
         Close
     };
 
@@ -54,6 +68,7 @@ public:
     void close() { open_ = false; }
     bool isOpen() const { return open_; }
     void setOpen(bool o) { open_ = o; if (o) refresh(); }
+    void refresh();
 
     const std::string& title() const { return title_; }
     const std::string& status() const { return status_; }
@@ -89,6 +104,13 @@ public:
     int uiTextColorIdx() const { return uiTextColorIdx_; }
     int uiAccentColorIdx() const { return uiAccentColorIdx_; }
     float uiDistance() const;
+    int uiFollowMode() const { return uiFollowMode_; }
+    void setUiFollowMode(int m) { uiFollowMode_ = m; saveConfig(); refresh(); }
+    int browserViewMode() const { return browserViewMode_; }
+    void setBrowserViewMode(int m) { browserViewMode_ = m; saveConfig(); refresh(); }
+    int bindQuickPath() const { return bindQuickPathBtn_; }
+    const std::string& quickPath() const { return quickPath_; }
+    void setQuickPath(const std::string& p) { quickPath_ = p; saveConfig(); }
 
     int section() const { return section_; }
     void setSection(int s) {
@@ -109,9 +131,15 @@ public:
     void loadConfig();
     void saveConfig() const;
 
-private:
-    void refresh();
+    bool listShowFormat() const { return listShowFormat_; }
+    bool listShowRes() const { return listShowRes_; }
+    bool listShowSize() const { return listShowSize_; }
+    bool listShowDuration() const { return listShowDuration_; }
 
+    void onKeyboardSubmit(const std::string& text) { (void)text; }
+    void onKeyboardCancel() {}
+
+private:
     bool open_ = false;
     std::string title_ = "Settings & Controller Remap";
     std::string status_ = "Point + Trigger: Change Setting | Grip: Recenter | B/Y: Close";
@@ -129,15 +157,23 @@ private:
     int bindPlayBtn_ = 0;      // default A
     int bindMenuBtn_ = 1;      // default B
     int bindRecenterBtn_ = 6;  // default Bumper (grip toggles the laser)
-    int listeningFunc_ = -1;   // 0=play 1=menu 2=recenter while binding, else -1
+    int bindQuickPathBtn_ = 7; // default Right Stick Click (BtnThumbR)
+    int listeningFunc_ = -1;   // 0=play 1=menu 2=recenter 3=move 4=quick path
     int downloadDirIdx_ = 0;   // index into the download-destination presets
     int curvatureIdx_ = 0;     // 0=Flat (0%), 1=Gentle (25%), 2=Cinema (50%), 3=Deep (75%), 4=IMAX (100%)
     int uiTextScaleIdx_ = 2;   // 0=90%, 1=105%, 2=120% (default), 3=140%, 4=160%
     int uiTextColorIdx_ = 0;   // 0=Pure White, 1=Ice Cyan, 2=Warm Cream, 3=Soft Gold, 4=Mint Green
     int uiAccentColorIdx_ = 0; // 0=Cyber Cyan, 1=Emerald, 2=Amber Gold, 3=Royal Purple, 4=Crimson
     int uiDistanceIdx_ = 1;    // 0=Near (1.5m), 1=Comfort (1.9m), 2=Mid (2.3m), 3=Far (2.8m)
+    int uiFollowMode_ = 0;     // 0=World Lock (default, zero drift/tilt), 1=Smooth Gaze Follow
+    int browserViewMode_ = 0;  // 0=Large Cards (3x2), 1=Smaller Cards (4x3), 2=Compact List (1-Col)
+    bool listShowFormat_ = true;
+    bool listShowRes_ = true;
+    bool listShowSize_ = true;
+    bool listShowDuration_ = true;
+    std::string quickPath_;
 
-    int section_ = 0;   // 0=Display, 1=Controls, 2=Streams, 3=System; 10..12=sub-lists
+    int section_ = 0;   // 0=Display, 1=UI, 2=Audio, 3=Controls, 4=Vault; 10..12=sub-lists
     std::vector<std::pair<int, std::string>> videoStreams_;  // (index, label)
     std::vector<std::pair<int, std::string>> audioStreams_;
     int videoSel_ = 0;      // position within videoStreams_

src/ui/thumbnail_cache.cpp

@@ -1,4 +1,5 @@
 #include "ui/thumbnail_cache.hpp"
+#include "app/vault_manager.hpp"
 #include "util/logging.hpp"
 
 #include <algorithm>
@@ -96,6 +97,32 @@ bool ThumbnailCache::getMeta(const std::string& videoPath, MediaMeta& outMeta) {
     return false;
 }
 
+void ThumbnailCache::clearVaultThumbs(const std::string& vaultDir) {
+    if (vaultDir.empty()) return;
+    std::lock_guard<std::mutex> lk(mutex_);
+    for (auto it = cache_.begin(); it != cache_.end(); ) {
+        if (it->first.rfind(vaultDir, 0) == 0) {
+            it = cache_.erase(it);
+        } else {
+            ++it;
+        }
+    }
+    for (auto it = metaCache_.begin(); it != metaCache_.end(); ) {
+        if (it->first.rfind(vaultDir, 0) == 0) {
+            it = metaCache_.erase(it);
+        } else {
+            ++it;
+        }
+    }
+    for (auto it = queuedPaths_.begin(); it != queuedPaths_.end(); ) {
+        if (it->first.rfind(vaultDir, 0) == 0) {
+            it = queuedPaths_.erase(it);
+        } else {
+            ++it;
+        }
+    }
+}
+
 bool ThumbnailCache::extractThumbnailAndMeta(const std::string& videoPath,
                                              std::vector<uint8_t>& outRgba,
                                              MediaMeta& outMeta) {
@@ -255,9 +282,11 @@ void ThumbnailCache::workerLoop() {
             continue;
         }
 
+        const bool inVault = VaultManager::instance().isVaultPath(path);
+        const std::string targetCacheDir = inVault ? VaultManager::instance().thumbsDir() : cacheDir_;
         const std::string baseHash = std::to_string(fnv1a64(path));
-        const std::string cacheFile = cacheDir_ + "/" + baseHash + ".rgba";
-        const std::string metaFile = cacheDir_ + "/" + baseHash + ".meta";
+        const std::string cacheFile = targetCacheDir + "/" + baseHash + ".rgba";
+        const std::string metaFile = targetCacheDir + "/" + baseHash + ".meta";
 
         std::error_code ec;
         if (fs::is_regular_file(cacheFile, ec) && fs::file_size(cacheFile, ec) == kThumbBytes) {

src/ui/thumbnail_cache.hpp

@@ -34,6 +34,9 @@ public:
     // Returns true and populates MediaMeta if probed.
     bool getMeta(const std::string& videoPath, MediaMeta& outMeta);
 
+    // Clears cached thumbnails and metadata whose paths start with vaultDir.
+    void clearVaultThumbs(const std::string& vaultDir);
+
 private:
     void workerLoop();
     bool extractThumbnailAndMeta(const std::string& videoPath,

src/util/ipv4.hpp

@@ -0,0 +1,107 @@
+#pragma once
+
+#include <string>
+#include <vector>
+#include <sstream>
+#include <algorithm>
+#include <cctype>
+
+namespace pixelvr {
+
+// Validates whether a string is a complete, strictly valid IPv4 address (e.g. "192.168.1.1").
+inline bool isValidIpv4(const std::string& str) {
+    if (str.empty()) return false;
+    std::stringstream ss(str);
+    std::string seg;
+    int count = 0;
+    while (std::getline(ss, seg, '.')) {
+        ++count;
+        if (seg.empty() || seg.length() > 3) return false;
+        for (char c : seg) {
+            if (!std::isdigit(static_cast<unsigned char>(c))) return false;
+        }
+        // Leading zeros not allowed if more than 1 digit (e.g. "01" is invalid, "0" is valid)
+        if (seg.length() > 1 && seg[0] == '0') return false;
+        try {
+            int val = std::stoi(seg);
+            if (val < 0 || val > 255) return false;
+        } catch (...) {
+            return false;
+        }
+    }
+    // Must have exactly 4 octets and not end with a trailing dot
+    return (count == 4 && str.back() != '.');
+}
+
+// Sanitizes and formats an in-progress or finalized IPv4 input:
+// - Only digits '0'..'9' and '.' are accepted; any other characters are discarded.
+// - At most 4 sections (octets).
+// - Each section has leading zeros dropped (e.g. "001" -> "1", "050" -> "50", "00" -> "0").
+// - Each section is clamped to max 255.
+// - If !finalized, a trailing dot is preserved while typing (e.g. "192.168.").
+// - If finalized, any trailing dot is trimmed and empty trailing sections are removed.
+inline std::string sanitizeIpv4(const std::string& input, bool finalized = false) {
+    if (input.empty()) return "";
+
+    std::vector<std::string> sections;
+    std::string current;
+    bool trailingDot = false;
+
+    for (char c : input) {
+        if (c == '.') {
+            if (!current.empty() && sections.size() < 4) {
+                sections.push_back(current);
+                current.clear();
+                trailingDot = true;
+            }
+        } else if (std::isdigit(static_cast<unsigned char>(c))) {
+            if (sections.size() >= 4) {
+                continue;
+            }
+            if (current.length() < 3) {
+                current += c;
+                trailingDot = false;
+            }
+        }
+    }
+    if (!current.empty() && sections.size() < 4) {
+        sections.push_back(current);
+        trailingDot = false;
+    }
+
+    if (sections.empty() && !trailingDot) return "";
+
+    std::string result;
+    for (std::size_t i = 0; i < sections.size(); ++i) {
+        std::string s = sections[i];
+        if (!s.empty()) {
+            while (s.length() > 1 && s[0] == '0') {
+                s.erase(s.begin());
+            }
+            try {
+                int val = std::stoi(s);
+                if (val > 255) val = 255;
+                s = std::to_string(val);
+            } catch (...) {
+                s = "255";
+            }
+        }
+
+        if (i > 0) result += '.';
+        result += s;
+    }
+
+    if (!finalized && trailingDot && sections.size() < 4 && !result.empty()) {
+        result += '.';
+    }
+
+    if (finalized) {
+        while (!result.empty() && result.back() == '.') {
+            result.pop_back();
+        }
+    }
+
+    return result;
+}
+
+} // namespace pixelvr

src/xr/render_model.cpp

@@ -29,6 +29,10 @@ bool RenderModelSystem::init(XrInstance instance, XrSession session, bool enable
         load("xrGetRenderModelStateEXT", pfnGetState_) &&
         load("xrDestroyRenderModelEXT", pfnDestroyModel_) &&
         load("xrDestroyRenderModelAssetEXT", pfnDestroyAsset_);
+
+    // Optional helper to map models to hands directly:
+    load("xrEnumerateRenderModelSubactionPathsEXT", pfnEnumerateSubactionPaths_);
+
     if (!available_) {
         PIXELVR_LOG_WARN("XR_EXT_render_model entry points unavailable");
     }
@@ -37,13 +41,13 @@ bool RenderModelSystem::init(XrInstance instance, XrSession session, bool enable
 
 bool RenderModelSystem::poll() {
     if (!available_ || done_) {
-        return assetReady();
+        return assetReady(0) || assetReady(1);
     }
-    fetchFirstModel();
-    return assetReady();
+    fetchModels();
+    return assetReady(0) || assetReady(1);
 }
 
-bool RenderModelSystem::fetchFirstModel() {
+bool RenderModelSystem::fetchModels() {
     XrInteractionRenderModelIdsEnumerateInfoEXT enumInfo{
         XR_TYPE_INTERACTION_RENDER_MODEL_IDS_ENUMERATE_INFO_EXT};
     uint32_t idCount = 0;
@@ -57,104 +61,153 @@ bool RenderModelSystem::fetchFirstModel() {
         return false;
     }
 
-    XrRenderModelIdEXT id = XR_NULL_RENDER_MODEL_ID_EXT;
-    for (auto v : ids) {
-        if (v != XR_NULL_RENDER_MODEL_ID_EXT) {
-            id = v;
-            break;
+    PIXELVR_LOG_INFO("OpenXR enumerated %u render model IDs", idCount);
+
+    for (uint32_t i = 0; i < idCount; ++i) {
+        XrRenderModelIdEXT id = ids[i];
+        if (id == XR_NULL_RENDER_MODEL_ID_EXT) continue;
+
+        if ((models_[0].ready && models_[0].id == id) ||
+            (models_[1].ready && models_[1].id == id)) {
+            continue;
         }
-    }
-    if (id == XR_NULL_RENDER_MODEL_ID_EXT) {
-        return false;
-    }
-    done_ = true;  // from here on, success or hard failure — do not retry
 
-    XrRenderModelCreateInfoEXT mci{XR_TYPE_RENDER_MODEL_CREATE_INFO_EXT};
-    mci.renderModelId = id;
-    if (XR_FAILED(pfnCreateModel_(session_, &mci, &model_))) {
-        PIXELVR_LOG_WARN("xrCreateRenderModelEXT failed");
-        return false;
-    }
+        XrRenderModelCreateInfoEXT mci{XR_TYPE_RENDER_MODEL_CREATE_INFO_EXT};
+        mci.renderModelId = id;
+        XrRenderModelEXT model = XR_NULL_HANDLE;
+        if (XR_FAILED(pfnCreateModel_(session_, &mci, &model))) {
+            PIXELVR_LOG_WARN("xrCreateRenderModelEXT failed for id %llu",
+                             static_cast<unsigned long long>(id));
+            continue;
+        }
 
-    XrRenderModelPropertiesGetInfoEXT pgi{
-        XR_TYPE_RENDER_MODEL_PROPERTIES_GET_INFO_EXT};
-    XrRenderModelPropertiesEXT props{XR_TYPE_RENDER_MODEL_PROPERTIES_EXT};
-    if (XR_FAILED(pfnGetProps_(model_, &pgi, &props))) {
-        PIXELVR_LOG_WARN("xrGetRenderModelPropertiesEXT failed");
-        return false;
-    }
-    animatableNodeCount_ = props.animatableNodeCount;
-
-    XrRenderModelAssetCreateInfoEXT aci{XR_TYPE_RENDER_MODEL_ASSET_CREATE_INFO_EXT};
-    aci.cacheId = props.cacheId;
-    if (XR_FAILED(pfnCreateAsset_(session_, &aci, &asset_))) {
-        PIXELVR_LOG_WARN("xrCreateRenderModelAssetEXT failed");
-        return false;
-    }
-
-    XrRenderModelAssetDataGetInfoEXT adi{
-        XR_TYPE_RENDER_MODEL_ASSET_DATA_GET_INFO_EXT};
-    XrRenderModelAssetDataEXT data{XR_TYPE_RENDER_MODEL_ASSET_DATA_EXT};
-    if (XR_FAILED(pfnGetAssetData_(asset_, &adi, &data))) {  // size query
-        PIXELVR_LOG_WARN("xrGetRenderModelAssetDataEXT (size) failed");
-        return false;
-    }
-    gltf_.resize(data.bufferCountOutput);
-    data.bufferCapacityInput = static_cast<uint32_t>(gltf_.size());
-    data.buffer = gltf_.data();
-    if (XR_FAILED(pfnGetAssetData_(asset_, &adi, &data))) {
-        PIXELVR_LOG_WARN("xrGetRenderModelAssetDataEXT (data) failed");
-        gltf_.clear();
-        return false;
-    }
-
-    XrRenderModelSpaceCreateInfoEXT sci{XR_TYPE_RENDER_MODEL_SPACE_CREATE_INFO_EXT};
-    sci.renderModel = model_;
-    pfnCreateSpace_(session_, &sci, &modelSpace_);  // used by later stages
-
-    // Animatable node names, in the same order as xrGetRenderModelStateEXT node
-    // states, so an animated node can be mapped back to glTF geometry.
-    if (pfnGetAssetProps_ != nullptr) {
-        XrRenderModelAssetPropertiesGetInfoEXT agi{
-            XR_TYPE_RENDER_MODEL_ASSET_PROPERTIES_GET_INFO_EXT};
-        XrRenderModelAssetPropertiesEXT props{
-            XR_TYPE_RENDER_MODEL_ASSET_PROPERTIES_EXT};
-        if (XR_FAILED(pfnGetAssetProps_(asset_, &agi, &props))) {
-            PIXELVR_LOG_WARN("xrGetRenderModelAssetPropertiesEXT (size) failed");
-        } else {
-            std::vector<XrRenderModelAssetNodePropertiesEXT> names(
-                props.nodePropertyCount);
-            props.nodePropertyCount = static_cast<uint32_t>(names.size());
-            props.nodeProperties = names.data();
-            if (XR_SUCCEEDED(pfnGetAssetProps_(asset_, &agi, &props))) {
-                nodeNames_.reserve(names.size());
-                for (const auto& np : names) nodeNames_.emplace_back(np.uniqueName);
-                std::string joined;
-                for (const auto& n : nodeNames_) {
-                    joined += n;
-                    joined += ' ';
+        int hand = -1;
+        if (pfnEnumerateSubactionPaths_ != nullptr) {
+            XrInteractionRenderModelSubactionPathInfoEXT spi{
+                XR_TYPE_INTERACTION_RENDER_MODEL_SUBACTION_PATH_INFO_EXT};
+            uint32_t pathCount = 0;
+            if (XR_SUCCEEDED(pfnEnumerateSubactionPaths_(model, &spi, 0, &pathCount, nullptr)) && pathCount > 0) {
+                std::vector<XrPath> paths(pathCount);
+                if (XR_SUCCEEDED(pfnEnumerateSubactionPaths_(model, &spi, pathCount, &pathCount, paths.data()))) {
+                    for (XrPath p : paths) {
+                        char pathBuf[XR_MAX_PATH_LENGTH];
+                        uint32_t len = 0;
+                        if (XR_SUCCEEDED(xrPathToString(instance_, p, sizeof(pathBuf), &len, pathBuf))) {
+                            std::string ps = pathBuf;
+                            if (ps.find("left") != std::string::npos) hand = 0;
+                            else if (ps.find("right") != std::string::npos) hand = 1;
+                        }
+                    }
                 }
-                PIXELVR_LOG_INFO("Render model nodes: %s", joined.c_str());
-            } else {
-                PIXELVR_LOG_WARN("xrGetRenderModelAssetPropertiesEXT (data) failed");
             }
         }
+
+        XrRenderModelPropertiesGetInfoEXT pgi{
+            XR_TYPE_RENDER_MODEL_PROPERTIES_GET_INFO_EXT};
+        XrRenderModelPropertiesEXT props{XR_TYPE_RENDER_MODEL_PROPERTIES_EXT};
+        if (XR_FAILED(pfnGetProps_(model, &pgi, &props))) {
+            PIXELVR_LOG_WARN("xrGetRenderModelPropertiesEXT failed");
+            pfnDestroyModel_(model);
+            continue;
+        }
+
+        XrRenderModelAssetCreateInfoEXT aci{XR_TYPE_RENDER_MODEL_ASSET_CREATE_INFO_EXT};
+        aci.cacheId = props.cacheId;
+        XrRenderModelAssetEXT asset = XR_NULL_HANDLE;
+        if (XR_FAILED(pfnCreateAsset_(session_, &aci, &asset))) {
+            PIXELVR_LOG_WARN("xrCreateRenderModelAssetEXT failed");
+            pfnDestroyModel_(model);
+            continue;
+        }
+
+        XrRenderModelAssetDataGetInfoEXT adi{
+            XR_TYPE_RENDER_MODEL_ASSET_DATA_GET_INFO_EXT};
+        XrRenderModelAssetDataEXT data{XR_TYPE_RENDER_MODEL_ASSET_DATA_EXT};
+        if (XR_FAILED(pfnGetAssetData_(asset, &adi, &data))) {  // size query
+            PIXELVR_LOG_WARN("xrGetRenderModelAssetDataEXT (size) failed");
+            pfnDestroyAsset_(asset);
+            pfnDestroyModel_(model);
+            continue;
+        }
+        std::vector<uint8_t> gltf(data.bufferCountOutput);
+        data.bufferCapacityInput = static_cast<uint32_t>(gltf.size());
+        data.buffer = gltf.data();
+        if (XR_FAILED(pfnGetAssetData_(asset, &adi, &data))) {
+            PIXELVR_LOG_WARN("xrGetRenderModelAssetDataEXT (data) failed");
+            pfnDestroyAsset_(asset);
+            pfnDestroyModel_(model);
+            continue;
+        }
+
+        // If hand is still undetermined, inspect glTF JSON header
+        if (hand < 0 && gltf.size() > 50) {
+            std::string gltfText(reinterpret_cast<const char*>(gltf.data()),
+                                 std::min<std::size_t>(gltf.size(), 4096));
+            if (gltfText.find("left") != std::string::npos ||
+                gltfText.find("Left") != std::string::npos) {
+                hand = 0;
+            } else if (gltfText.find("right") != std::string::npos ||
+                       gltfText.find("Right") != std::string::npos) {
+                hand = 1;
+            }
+        }
+
+        // Fallback: assign to the first unfilled hand slot
+        if (hand < 0) {
+            hand = !models_[0].ready ? 0 : 1;
+        }
+
+        XrRenderModelSpaceCreateInfoEXT sci{XR_TYPE_RENDER_MODEL_SPACE_CREATE_INFO_EXT};
+        sci.renderModel = model;
+        XrSpace modelSpace = XR_NULL_HANDLE;
+        pfnCreateSpace_(session_, &sci, &modelSpace);
+
+        std::vector<std::string> nodeNames;
+        if (pfnGetAssetProps_ != nullptr) {
+            XrRenderModelAssetPropertiesGetInfoEXT agi{
+                XR_TYPE_RENDER_MODEL_ASSET_PROPERTIES_GET_INFO_EXT};
+            XrRenderModelAssetPropertiesEXT aprops{
+                XR_TYPE_RENDER_MODEL_ASSET_PROPERTIES_EXT};
+            if (XR_SUCCEEDED(pfnGetAssetProps_(asset, &agi, &aprops))) {
+                std::vector<XrRenderModelAssetNodePropertiesEXT> names(
+                    aprops.nodePropertyCount);
+                aprops.nodePropertyCount = static_cast<uint32_t>(names.size());
+                aprops.nodeProperties = names.data();
+                if (XR_SUCCEEDED(pfnGetAssetProps_(asset, &agi, &aprops))) {
+                    nodeNames.reserve(names.size());
+                    for (const auto& np : names) nodeNames.emplace_back(np.uniqueName);
+                }
+            }
+        }
+
+        ModelInfo& mi = models_[hand];
+        mi.id = id;
+        mi.model = model;
+        mi.asset = asset;
+        mi.space = modelSpace;
+        mi.gltf = std::move(gltf);
+        mi.animatableNodeCount = props.animatableNodeCount;
+        mi.nodeNames = std::move(nodeNames);
+        mi.ready = true;
+
+        PIXELVR_LOG_INFO("Render model for %s hand fetched: %u nodes, glTF %zu bytes",
+                         hand == 0 ? "left" : "right",
+                         mi.animatableNodeCount, mi.gltf.size());
     }
 
-    PIXELVR_LOG_INFO("Render model fetched: %u animatable nodes, glTF %zu bytes",
-                     animatableNodeCount_, gltf_.size());
-    if (FILE* f = std::fopen("/tmp/controller_model.glb", "wb")) {
-        std::fwrite(gltf_.data(), 1, gltf_.size(), f);
-        std::fclose(f);
+    if (models_[0].ready && models_[1].ready) {
+        done_ = true;
     }
-    return true;
+    return models_[0].ready || models_[1].ready;
 }
 
-bool RenderModelSystem::locate(XrSpace base, XrTime time, float outPos[3],
+bool RenderModelSystem::locate(int hand, XrSpace base, XrTime time, float outPos[3],
                                float outQuat[4]) const {
-    if (modelSpace_ == XR_NULL_HANDLE || time == 0) return false;
+    if (hand < 0 || hand >= 2) return false;
+    const XrSpace space = models_[hand].space;
+    if (space == XR_NULL_HANDLE || time == 0) return false;
     XrSpaceLocation loc{XR_TYPE_SPACE_LOCATION};
-    if (XR_FAILED(xrLocateSpace(modelSpace_, base, time, &loc))) return false;
+    if (XR_FAILED(xrLocateSpace(space, base, time, &loc))) return false;
     constexpr XrSpaceLocationFlags need =
         XR_SPACE_LOCATION_ORIENTATION_VALID_BIT |
         XR_SPACE_LOCATION_POSITION_VALID_BIT;
@@ -169,33 +222,35 @@ bool RenderModelSystem::locate(XrSpace base, XrTime time, float outPos[3],
     return true;
 }
 
-bool RenderModelSystem::nodeStates(XrTime time, std::vector<NodeState>& out) {
-    if (!available_ || model_ == XR_NULL_HANDLE || pfnGetState_ == nullptr ||
+bool RenderModelSystem::nodeStates(int hand, XrTime time, std::vector<NodeState>& out) {
+    if (hand < 0 || hand >= 2) return false;
+    ModelInfo& mi = models_[hand];
+    if (!available_ || mi.model == XR_NULL_HANDLE || pfnGetState_ == nullptr ||
         time == 0) {
         return false;
     }
-    if (nodeStateBuf_.size() < animatableNodeCount_) {
-        nodeStateBuf_.resize(animatableNodeCount_);
+    if (mi.nodeStateBuf.size() < mi.animatableNodeCount) {
+        mi.nodeStateBuf.resize(mi.animatableNodeCount);
     }
     XrRenderModelStateGetInfoEXT gi{XR_TYPE_RENDER_MODEL_STATE_GET_INFO_EXT};
     gi.displayTime = time;
     XrRenderModelStateEXT st{XR_TYPE_RENDER_MODEL_STATE_EXT};
-    st.nodeStateCount = static_cast<uint32_t>(nodeStateBuf_.size());
-    st.nodeStates = nodeStateBuf_.data();
-    if (XR_FAILED(pfnGetState_(model_, &gi, &st))) {
+    st.nodeStateCount = static_cast<uint32_t>(mi.nodeStateBuf.size());
+    st.nodeStates = mi.nodeStateBuf.data();
+    if (XR_FAILED(pfnGetState_(mi.model, &gi, &st))) {
         return false;
     }
-    if (st.nodeStateCount > nodeStateBuf_.size()) {  // grew; retry once
-        nodeStateBuf_.resize(st.nodeStateCount);
-        st.nodeStateCount = static_cast<uint32_t>(nodeStateBuf_.size());
-        st.nodeStates = nodeStateBuf_.data();
-        if (XR_FAILED(pfnGetState_(model_, &gi, &st))) {
+    if (st.nodeStateCount > mi.nodeStateBuf.size()) {  // grew; retry once
+        mi.nodeStateBuf.resize(st.nodeStateCount);
+        st.nodeStateCount = static_cast<uint32_t>(mi.nodeStateBuf.size());
+        st.nodeStates = mi.nodeStateBuf.data();
+        if (XR_FAILED(pfnGetState_(mi.model, &gi, &st))) {
             return false;
         }
     }
     out.resize(st.nodeStateCount);
     for (uint32_t i = 0; i < st.nodeStateCount; ++i) {
-        const XrRenderModelNodeStateEXT& n = nodeStateBuf_[i];
+        const XrRenderModelNodeStateEXT& n = mi.nodeStateBuf[i];
         NodeState& o = out[i];
         o.pos[0] = n.nodePose.position.x;
         o.pos[1] = n.nodePose.position.y;
@@ -210,17 +265,21 @@ bool RenderModelSystem::nodeStates(XrTime time, std::vector<NodeState>& out) {
 }
 
 void RenderModelSystem::shutdown() {
-    if (modelSpace_ != XR_NULL_HANDLE) {
-        xrDestroySpace(modelSpace_);
-        modelSpace_ = XR_NULL_HANDLE;
-    }
-    if (asset_ != XR_NULL_HANDLE && pfnDestroyAsset_ != nullptr) {
-        pfnDestroyAsset_(asset_);
-        asset_ = XR_NULL_HANDLE;
-    }
-    if (model_ != XR_NULL_HANDLE && pfnDestroyModel_ != nullptr) {
-        pfnDestroyModel_(model_);
-        model_ = XR_NULL_HANDLE;
+    for (int h = 0; h < 2; ++h) {
+        ModelInfo& mi = models_[h];
+        if (mi.space != XR_NULL_HANDLE) {
+            xrDestroySpace(mi.space);
+            mi.space = XR_NULL_HANDLE;
+        }
+        if (mi.asset != XR_NULL_HANDLE && pfnDestroyAsset_ != nullptr) {
+            pfnDestroyAsset_(mi.asset);
+            mi.asset = XR_NULL_HANDLE;
+        }
+        if (mi.model != XR_NULL_HANDLE && pfnDestroyModel_ != nullptr) {
+            pfnDestroyModel_(mi.model);
+            mi.model = XR_NULL_HANDLE;
+        }
+        mi.ready = false;
     }
 }
 

src/xr/render_model.hpp

@@ -9,9 +9,7 @@
 namespace pixelvr {
 
 // Fetches (and, in later stages, renders) the runtime-provided controller models
-// via XR_EXT_render_model. Stage 2 scope: resolve the extension entry points,
-// enumerate the active interaction render models, and pull the first one's
-// glTF/GLB asset bytes so the renderer can parse and draw it.
+// via XR_EXT_render_model for both left (0) and right (1) hands.
 class RenderModelSystem {
 public:
     // Resolves the extension function pointers. `enabled` is whether the three
@@ -20,22 +18,33 @@ public:
 
     bool available() const { return available_; }
 
-    // Lazily enumerates + fetches the first controller model's glTF the first
-    // time a controller is active. Safe to call every frame. Returns true once
-    // the asset bytes are ready.
+    // Lazily enumerates + fetches controller models for both hands.
+    // Safe to call every frame.
     bool poll();
 
-    bool assetReady() const { return !gltf_.empty(); }
-    const std::vector<uint8_t>& gltf() const { return gltf_; }
-    uint32_t animatableNodeCount() const { return animatableNodeCount_; }
+    bool assetReady(int hand = 1) const {
+        return hand >= 0 && hand < 2 && models_[hand].ready && !models_[hand].gltf.empty();
+    }
+    const std::vector<uint8_t>& gltf(int hand = 1) const {
+        static const std::vector<uint8_t> kEmpty;
+        return (hand >= 0 && hand < 2) ? models_[hand].gltf : kEmpty;
+    }
+    uint32_t animatableNodeCount(int hand = 1) const {
+        return (hand >= 0 && hand < 2) ? models_[hand].animatableNodeCount : 0;
+    }
 
-    // Locates the render-model space in `base` at `time` (the pose the runtime
-    // expects the glTF to be rendered at). False if not fetched or untracked.
-    bool locate(XrSpace base, XrTime time, float outPos[3], float outQuat[4]) const;
+    // Locates the render-model space in `base` at `time` for `hand` (0 = left, 1 = right).
+    bool locate(int hand, XrSpace base, XrTime time, float outPos[3], float outQuat[4]) const;
+    bool locate(XrSpace base, XrTime time, float outPos[3], float outQuat[4]) const {
+        return locate(1, base, time, outPos, outQuat);
+    }
 
     // Names of the model's animatable nodes, in the same order as the node
     // states returned by nodeStates() (maps a node state to glTF geometry).
-    const std::vector<std::string>& nodeNames() const { return nodeNames_; }
+    const std::vector<std::string>& nodeNames(int hand = 1) const {
+        static const std::vector<std::string> kEmpty;
+        return (hand >= 0 && hand < 2) ? models_[hand].nodeNames : kEmpty;
+    }
 
     // Animated per-node transform the runtime wants applied this frame (drives
     // button-press movement, trigger pull, thumbstick tilt, etc.).
@@ -44,28 +53,37 @@ public:
         float quat[4] = {0.0f, 0.0f, 0.0f, 1.0f};
         bool visible = true;
     };
-    // Fills `out` (parallel to nodeNames()) for `time`. False if unavailable.
-    bool nodeStates(XrTime time, std::vector<NodeState>& out);
+    // Fills `out` (parallel to nodeNames()) for `hand` at `time`. False if unavailable.
+    bool nodeStates(int hand, XrTime time, std::vector<NodeState>& out);
+    bool nodeStates(XrTime time, std::vector<NodeState>& out) {
+        return nodeStates(1, time, out);
+    }
 
     void shutdown();
 
 private:
-    bool fetchFirstModel();
+    bool fetchModels();
 
     XrInstance instance_ = XR_NULL_HANDLE;
     XrSession session_ = XR_NULL_HANDLE;
     bool available_ = false;
-    bool done_ = false;  // asset fetched (or permanently failed)
+    bool done_ = false;  // all models fetched (or permanently failed)
 
-    XrRenderModelEXT model_ = XR_NULL_HANDLE;
-    XrRenderModelAssetEXT asset_ = XR_NULL_HANDLE;
-    XrSpace modelSpace_ = XR_NULL_HANDLE;
-    std::vector<uint8_t> gltf_;
-    uint32_t animatableNodeCount_ = 0;
-    std::vector<std::string> nodeNames_;
-    std::vector<XrRenderModelNodeStateEXT> nodeStateBuf_;  // reused per frame
+    struct ModelInfo {
+        XrRenderModelIdEXT id = XR_NULL_RENDER_MODEL_ID_EXT;
+        XrRenderModelEXT model = XR_NULL_HANDLE;
+        XrRenderModelAssetEXT asset = XR_NULL_HANDLE;
+        XrSpace space = XR_NULL_HANDLE;
+        std::vector<uint8_t> gltf;
+        std::vector<std::string> nodeNames;
+        std::vector<XrRenderModelNodeStateEXT> nodeStateBuf;  // reused per frame
+        uint32_t animatableNodeCount = 0;
+        bool ready = false;
+    };
+    ModelInfo models_[2];  // 0 = left, 1 = right
 
     PFN_xrEnumerateInteractionRenderModelIdsEXT pfnEnumerateIds_ = nullptr;
+    PFN_xrEnumerateRenderModelSubactionPathsEXT pfnEnumerateSubactionPaths_ = nullptr;
     PFN_xrCreateRenderModelEXT pfnCreateModel_ = nullptr;
     PFN_xrGetRenderModelPropertiesEXT pfnGetProps_ = nullptr;
     PFN_xrCreateRenderModelAssetEXT pfnCreateAsset_ = nullptr;

src/xr/vr_keyboard.cpp

@@ -0,0 +1,384 @@
+#include "vr_keyboard.hpp"
+#include "util/logging.hpp"
+#include <cstring>
+
+#if defined(__linux__) || defined(__APPLE__)
+#include <dlfcn.h>
+#else
+#include <windows.h>
+#endif
+
+#include "openvr.h"
+
+namespace pixelvr {
+
+namespace {
+
+typedef intptr_t (*Fn_VR_InitInternal)(vr::EVRInitError*, vr::EVRApplicationType);
+typedef void (*Fn_VR_ShutdownInternal)();
+typedef intptr_t (*Fn_VR_GetGenericInterface)(const char*, vr::EVRInitError*);
+
+Fn_VR_InitInternal g_VR_InitInternal = nullptr;
+Fn_VR_ShutdownInternal g_VR_ShutdownInternal = nullptr;
+Fn_VR_GetGenericInterface g_VR_GetGenericInterface = nullptr;
+
+} // namespace
+
+VrKeyboard& VrKeyboard::instance() {
+    static VrKeyboard sInstance;
+    return sInstance;
+}
+
+VrKeyboard::~VrKeyboard() {
+    shutdown();
+}
+
+bool VrKeyboard::init() {
+    if (available_) return true;
+
+#if defined(__linux__)
+    const char* paths[] = {
+        "/opt/steamvr/bin/linuxarm64/libopenvr_api.so",
+        "/opt/steamvr/bin/linux64/libopenvr_api.so",
+        "libopenvr_api.so"
+    };
+    for (const char* path : paths) {
+        libHandle_ = dlopen(path, RTLD_NOW | RTLD_LOCAL);
+        if (libHandle_) {
+            PIXELVR_LOG_INFO("VrKeyboard: Loaded %s", path);
+            break;
+        }
+    }
+    if (!libHandle_) {
+        PIXELVR_LOG_WARN("VrKeyboard: Could not find or load libopenvr_api.so: %s", dlerror());
+        return false;
+    }
+
+    g_VR_InitInternal = reinterpret_cast<Fn_VR_InitInternal>(dlsym(libHandle_, "VR_InitInternal"));
+    g_VR_ShutdownInternal = reinterpret_cast<Fn_VR_ShutdownInternal>(dlsym(libHandle_, "VR_ShutdownInternal"));
+    g_VR_GetGenericInterface = reinterpret_cast<Fn_VR_GetGenericInterface>(dlsym(libHandle_, "VR_GetGenericInterface"));
+#elif defined(_WIN32)
+    HMODULE hMod = LoadLibraryA("openvr_api.dll");
+    if (!hMod) {
+        return false;
+    }
+    libHandle_ = hMod;
+    g_VR_InitInternal = reinterpret_cast<Fn_VR_InitInternal>(GetProcAddress(hMod, "VR_InitInternal"));
+    g_VR_ShutdownInternal = reinterpret_cast<Fn_VR_ShutdownInternal>(GetProcAddress(hMod, "VR_ShutdownInternal"));
+    g_VR_GetGenericInterface = reinterpret_cast<Fn_VR_GetGenericInterface>(GetProcAddress(hMod, "VR_GetGenericInterface"));
+#else
+    return false;
+#endif
+
+    if (!g_VR_InitInternal || !g_VR_ShutdownInternal || !g_VR_GetGenericInterface) {
+        PIXELVR_LOG_WARN("VrKeyboard: OpenVR symbols not resolved");
+        shutdown();
+        return false;
+    }
+
+    vr::EVRInitError err = vr::VRInitError_None;
+    uint32_t token = static_cast<uint32_t>(g_VR_InitInternal(&err, vr::VRApplication_Overlay));
+    if (token == 0 || err != vr::VRInitError_None) {
+        PIXELVR_LOG_WARN("VrKeyboard: OpenVR overlay init returned %d", static_cast<int>(err));
+        shutdown();
+        return false;
+    }
+
+    vr::IVRSystem* sys = reinterpret_cast<vr::IVRSystem*>(
+        g_VR_GetGenericInterface(vr::IVRSystem_Version, &err));
+    if (!sys || err != vr::VRInitError_None) {
+        PIXELVR_LOG_WARN("VrKeyboard: Failed to get IVRSystem interface %s (err=%d)",
+                         vr::IVRSystem_Version, static_cast<int>(err));
+        shutdown();
+        return false;
+    }
+
+    vr::IVROverlay* ov = reinterpret_cast<vr::IVROverlay*>(
+        g_VR_GetGenericInterface(vr::IVROverlay_Version, &err));
+    if (!ov || err != vr::VRInitError_None) {
+        PIXELVR_LOG_WARN("VrKeyboard: Failed to get IVROverlay interface %s (err=%d)",
+                         vr::IVROverlay_Version, static_cast<int>(err));
+        shutdown();
+        return false;
+    }
+
+    vrSystem_ = sys;
+    vrOverlay_ = ov;
+    available_ = true;
+
+    // Create a persistent input overlay so ShowKeyboardForOverlay can link
+    // tracked controller pointer interactions directly to SteamVR's virtual keyboard.
+    vr::VROverlayHandle_t hOverlay = vr::k_ulOverlayHandleInvalid;
+    vr::EVROverlayError ovErr = ov->CreateOverlay("pixelvr.input_overlay", "PixelVR Input", &hOverlay);
+    if (ovErr == vr::VROverlayError_None && hOverlay != vr::k_ulOverlayHandleInvalid) {
+        inputOverlay_ = hOverlay;
+        ov->SetOverlayInputMethod(hOverlay, vr::VROverlayInputMethod_Mouse);
+        ov->SetOverlayFlag(hOverlay, vr::VROverlayFlags_MakeOverlaysInteractiveIfVisible, true);
+        PIXELVR_LOG_INFO("VrKeyboard: Created input overlay %llu with Mouse input method and MakeOverlaysInteractiveIfVisible",
+                         static_cast<unsigned long long>(inputOverlay_));
+    } else {
+        PIXELVR_LOG_WARN("VrKeyboard: Could not create input overlay (err=%d)", static_cast<int>(ovErr));
+    }
+
+    PIXELVR_LOG_INFO("VrKeyboard: Successfully initialized SteamVR overlay interface (sys=%p, ov=%p)",
+                     reinterpret_cast<void*>(sys), reinterpret_cast<void*>(ov));
+    return true;
+}
+
+void VrKeyboard::shutdown() {
+    if (isOpen_) {
+        hide();
+    }
+    if (inputOverlay_ != 0 && vrOverlay_) {
+        auto* ov = reinterpret_cast<vr::IVROverlay*>(vrOverlay_);
+        ov->DestroyOverlay(inputOverlay_);
+        inputOverlay_ = 0;
+    }
+    if (g_VR_ShutdownInternal) {
+        g_VR_ShutdownInternal();
+    }
+    vrSystem_ = nullptr;
+    vrOverlay_ = nullptr;
+    if (libHandle_) {
+#if defined(__linux__) || defined(__APPLE__)
+        dlclose(libHandle_);
+#elif defined(_WIN32)
+        FreeLibrary(reinterpret_cast<HMODULE>(libHandle_));
+#endif
+        libHandle_ = nullptr;
+    }
+    g_VR_InitInternal = nullptr;
+    g_VR_ShutdownInternal = nullptr;
+    g_VR_GetGenericInterface = nullptr;
+    available_ = false;
+    isOpen_ = false;
+    doneSubmitted_ = false;
+}
+
+bool VrKeyboard::show(const std::string& description,
+                      const std::string& existingText,
+                      bool isPassword,
+                      int maxChars) {
+    if (!available_ && !init()) {
+        return false;
+    }
+    auto* ov = reinterpret_cast<vr::IVROverlay*>(vrOverlay_);
+    if (!ov) return false;
+
+    description_ = description;
+    existingText_ = existingText;
+    currentText_ = existingText;
+    isPassword_ = isPassword;
+    doneSubmitted_ = false;
+
+    const vr::EGamepadTextInputMode mode = isPassword
+        ? vr::k_EGamepadTextInputModePassword
+        : vr::k_EGamepadTextInputModeNormal;
+
+    vr::EVROverlayError err = vr::VROverlayError_None;
+    if (inputOverlay_ != 0) {
+        ov->SetOverlayInputMethod(inputOverlay_, vr::VROverlayInputMethod_Mouse);
+        ov->SetOverlayFlag(inputOverlay_, vr::VROverlayFlags_MakeOverlaysInteractiveIfVisible, true);
+        ov->SetOverlayWidthInMeters(inputOverlay_, 1.0f);
+
+        // Position overlay 1.1m in front of HMD, tilted slightly down/up to match comfortable view
+        vr::HmdMatrix34_t mat = {
+            1.0f, 0.0f, 0.0f, 0.0f,
+            0.0f, 1.0f, 0.0f, -0.2f,
+            0.0f, 0.0f, 1.0f, -1.1f
+        };
+        ov->SetOverlayTransformTrackedDeviceRelative(inputOverlay_, vr::k_unTrackedDeviceIndex_Hmd, &mat);
+
+        // Transparent 1x1 pixel texture so overlay is valid and active without rendering visual artifacts
+        static const uint32_t s_transparentPixel = 0x00000000;
+        ov->SetOverlayRaw(inputOverlay_, const_cast<uint32_t*>(&s_transparentPixel), 1, 1, 4);
+
+        // Tell keyboard to avoid overlay upper area and appear cleanly docked
+        vr::HmdRect2_t avoidRect = {
+            { 0.0f, 0.0f },
+            { 1.0f, 0.2f }
+        };
+        ov->SetKeyboardPositionForOverlay(inputOverlay_, avoidRect);
+
+        // Show overlay BEFORE opening keyboard so vrcompositor recognizes active interactive overlay
+        ov->ShowOverlay(inputOverlay_);
+
+        err = ov->ShowKeyboardForOverlay(
+            inputOverlay_,
+            mode,
+            vr::k_EGamepadTextInputLineModeSingleLine,
+            vr::KeyboardFlag_Modal,
+            description.c_str(),
+            static_cast<uint32_t>(maxChars),
+            existingText.c_str(),
+            0);
+    } else {
+        err = ov->ShowKeyboard(
+            mode,
+            vr::k_EGamepadTextInputLineModeSingleLine,
+            vr::KeyboardFlag_Modal,
+            description.c_str(),
+            static_cast<uint32_t>(maxChars),
+            existingText.c_str(),
+            0);
+    }
+
+    if (err != vr::VROverlayError_None) {
+        PIXELVR_LOG_WARN("VrKeyboard: ShowKeyboard failed with error %d", static_cast<int>(err));
+        if (inputOverlay_ != 0) {
+            ov->HideOverlay(inputOverlay_);
+        }
+        return false;
+    }
+
+    kbConfigured_ = false;
+    // Attempt early configuration of keyboard overlays if already created
+    const char* kbOverlayNames[] = {
+        "valve.steam.gamepadui.keyboard",
+        "system.keyboard"
+    };
+    for (const char* name : kbOverlayNames) {
+        vr::VROverlayHandle_t hKb = vr::k_ulOverlayHandleInvalid;
+        if (ov->FindOverlay(name, &hKb) == vr::VROverlayError_None && hKb != vr::k_ulOverlayHandleInvalid) {
+            ov->SetOverlayFlag(hKb, vr::VROverlayFlags_MakeOverlaysInteractiveIfVisible, true);
+            ov->SetOverlayInputMethod(hKb, vr::VROverlayInputMethod_Mouse);
+            kbConfigured_ = true;
+            PIXELVR_LOG_INFO("VrKeyboard: Configured interactive laser mouse for overlay '%s'", name);
+        }
+    }
+
+    isOpen_ = true;
+    PIXELVR_LOG_INFO("VrKeyboard: Shown virtual keyboard for '%s' (initial text: '%s')",
+                     description.c_str(), existingText.c_str());
+    return true;
+}
+
+void VrKeyboard::hide() {
+    if (!isOpen_) return;
+    auto* ov = reinterpret_cast<vr::IVROverlay*>(vrOverlay_);
+    if (ov) {
+        ov->HideKeyboard();
+        if (inputOverlay_ != 0) {
+            ov->HideOverlay(inputOverlay_);
+        }
+    }
+    isOpen_ = false;
+    kbConfigured_ = false;
+    doneSubmitted_ = false;
+    PIXELVR_LOG_INFO("VrKeyboard: Hidden virtual keyboard");
+}
+
+void VrKeyboard::poll(std::function<void(const std::string&)> onDone,
+                      std::function<void()> onCancel) {
+    if (!available_ || !isOpen_) return;
+    auto* sys = reinterpret_cast<vr::IVRSystem*>(vrSystem_);
+    auto* ov = reinterpret_cast<vr::IVROverlay*>(vrOverlay_);
+    if (!sys || !ov) return;
+
+    vr::VREvent_t event{};
+    while (sys->PollNextEvent(&event, sizeof(event))) {
+        if (event.eventType == vr::VREvent_KeyboardCharInput) {
+            char keyBuf[1024] = {0};
+            uint32_t len = ov->GetKeyboardText(keyBuf, sizeof(keyBuf));
+            if (len > 0) {
+                currentText_ = std::string(keyBuf, len < sizeof(keyBuf) ? len : std::strlen(keyBuf));
+            } else {
+                // Fallback: check event.data.keyboard.cNewInput
+                const char* inStr = event.data.keyboard.cNewInput;
+                if (inStr && inStr[0] != 0) {
+                    const unsigned char firstByte = static_cast<unsigned char>(inStr[0]);
+                    if (firstByte == '\b' || firstByte == 0x7F || firstByte == 8) {
+                        while (!currentText_.empty() && (static_cast<unsigned char>(currentText_.back()) & 0xC0) == 0x80) {
+                            currentText_.pop_back();
+                        }
+                        if (!currentText_.empty()) {
+                            currentText_.pop_back();
+                        }
+                    } else if (firstByte >= 32) {
+                        currentText_ += inStr;
+                    }
+                }
+            }
+            PIXELVR_LOG_INFO("VrKeyboard: CharInput live text: '%s'", currentText_.c_str());
+        } else if (event.eventType == vr::VREvent_KeyboardDone) {
+            isOpen_ = false;
+            kbConfigured_ = false;
+            if (inputOverlay_ != 0 && ov) {
+                ov->HideOverlay(inputOverlay_);
+            }
+            doneSubmitted_ = true;
+            char buf[1024] = {0};
+            uint32_t len = ov->GetKeyboardText(buf, sizeof(buf));
+            std::string text = currentText_;
+            if (len > 0) {
+                text = std::string(buf, len < sizeof(buf) ? len : std::strlen(buf));
+            }
+            PIXELVR_LOG_INFO("VrKeyboard: User submitted text via KeyboardDone: '%s'", text.c_str());
+            if (onDone) {
+                onDone(text);
+            }
+        } else if (event.eventType == vr::VREvent_KeyboardClosed ||
+                   event.eventType == vr::VREvent_KeyboardClosed_Global) {
+            isOpen_ = false;
+            kbConfigured_ = false;
+            if (inputOverlay_ != 0 && ov) {
+                ov->HideOverlay(inputOverlay_);
+            }
+            PIXELVR_LOG_INFO("VrKeyboard: Keyboard closed (doneSubmitted=%d)", doneSubmitted_ ? 1 : 0);
+            if (!doneSubmitted_) {
+                // On Steam Frame / SteamOS, pressing the checkmark or closing the keyboard issues KeyboardClosed
+                // without KeyboardDone. Read the buffer and treat non-empty / modified input as submit!
+                char buf[1024] = {0};
+                uint32_t len = ov->GetKeyboardText(buf, sizeof(buf));
+                std::string text = currentText_;
+                if (len > 0) {
+                    text = std::string(buf, len < sizeof(buf) ? len : std::strlen(buf));
+                }
+                if (!text.empty() || text != existingText_) {
+                    PIXELVR_LOG_INFO("VrKeyboard: Treating KeyboardClosed as submit with text: '%s'", text.c_str());
+                    doneSubmitted_ = true;
+                    if (onDone) {
+                        onDone(text);
+                    }
+                } else {
+                    PIXELVR_LOG_INFO("VrKeyboard: Keyboard cancelled without text change");
+                    if (onCancel) {
+                        onCancel();
+                    }
+                }
+            }
+        }
+    }
+
+    // Keep currentText_ synchronized with the live SteamVR keyboard buffer every frame
+    if (isOpen_) {
+        // Dynamically ensure SteamVR keyboard overlay has laser mouse flags as soon as spawned
+        if (!kbConfigured_) {
+            const char* kbOverlayNames[] = {
+                "valve.steam.gamepadui.keyboard",
+                "system.keyboard"
+            };
+            for (const char* name : kbOverlayNames) {
+                vr::VROverlayHandle_t hKb = vr::k_ulOverlayHandleInvalid;
+                if (ov->FindOverlay(name, &hKb) == vr::VROverlayError_None && hKb != vr::k_ulOverlayHandleInvalid) {
+                    ov->SetOverlayFlag(hKb, vr::VROverlayFlags_MakeOverlaysInteractiveIfVisible, true);
+                    ov->SetOverlayInputMethod(hKb, vr::VROverlayInputMethod_Mouse);
+                    kbConfigured_ = true;
+                    PIXELVR_LOG_INFO("VrKeyboard: Configured interactive laser mouse for overlay '%s'", name);
+                }
+            }
+        }
+
+        char liveBuf[1024] = {0};
+        uint32_t liveLen = ov->GetKeyboardText(liveBuf, sizeof(liveBuf));
+        if (liveLen > 0) {
+            currentText_ = std::string(liveBuf, liveLen < sizeof(liveBuf) ? liveLen : std::strlen(liveBuf));
+        }
+    }
+}
+
+std::string VrKeyboard::currentText() const {
+    return currentText_;
+}
+
+} // namespace pixelvr

src/xr/vr_keyboard.hpp

@@ -0,0 +1,57 @@
+#pragma once
+
+#include <functional>
+#include <string>
+#include <cstdint>
+
+namespace pixelvr {
+
+class VrKeyboard {
+public:
+    static VrKeyboard& instance();
+
+    // Initializes OpenVR overlay interface dynamically if SteamVR is running.
+    bool init();
+    void shutdown();
+
+    bool isAvailable() const { return available_; }
+    bool isOpen() const { return isOpen_; }
+
+    // Opens the native SteamVR / SteamOS VR on-screen virtual keyboard.
+    // e.g. description: "Enter SMB Server IP", existingText: "192.168.1.100", isPassword: false
+    bool show(const std::string& description,
+              const std::string& existingText,
+              bool isPassword = false,
+              int maxChars = 256);
+
+    // Closes the virtual keyboard if open.
+    void hide();
+
+    // Call once per frame in the main event loop to poll OpenVR keyboard events.
+    void poll(std::function<void(const std::string&)> onDone,
+              std::function<void()> onCancel);
+
+    // Retrieves current entered buffer
+    std::string currentText() const;
+    const std::string& description() const { return description_; }
+    bool isPassword() const { return isPassword_; }
+
+private:
+    VrKeyboard() = default;
+    ~VrKeyboard();
+
+    bool available_ = false;
+    bool isOpen_ = false;
+    bool doneSubmitted_ = false;
+    bool kbConfigured_ = false;
+    std::string description_;
+    std::string existingText_;
+    std::string currentText_;
+    bool isPassword_ = false;
+    void* libHandle_ = nullptr;
+    void* vrSystem_ = nullptr;
+    void* vrOverlay_ = nullptr;
+    uint64_t inputOverlay_ = 0;
+};
+
+} // namespace pixelvr

src/xr/xr_context.cpp

@@ -1,8 +1,10 @@
 #include "xr/xr_context.hpp"
 
 #include "xr/xr_result.hpp"
+#include "xr/vr_keyboard.hpp"
 #include "util/logging.hpp"
 
+#include <algorithm>
 #include <array>
 #include <cstring>
 
@@ -236,8 +238,18 @@ bool XrContext::createSwapchains(int64_t colorFormat) {
 
     for (const auto& view : configViews_) {
         ViewSwapchain sc;
-        sc.width = static_cast<int32_t>(view.recommendedImageRectWidth);
-        sc.height = static_cast<int32_t>(view.recommendedImageRectHeight);
+        // Boost swapchain resolution from SteamVR's conservative default (1728) to the headset's
+        // native physical display resolution (2160x2160, 1.25x).
+        // Rendering at 1:1 panel resolution eliminates compositor magnification blur and
+        // edge shimmering during head movement in VR.
+        const uint32_t maxW = (view.maxImageRectWidth > 0) ? view.maxImageRectWidth : 4096;
+        const uint32_t maxH = (view.maxImageRectHeight > 0) ? view.maxImageRectHeight : 4096;
+        const uint32_t targetW = std::clamp(static_cast<uint32_t>(view.recommendedImageRectWidth * 1.25f),
+                                            view.recommendedImageRectWidth, maxW);
+        const uint32_t targetH = std::clamp(static_cast<uint32_t>(view.recommendedImageRectHeight * 1.25f),
+                                            view.recommendedImageRectHeight, maxH);
+        sc.width = static_cast<int32_t>(targetW);
+        sc.height = static_cast<int32_t>(targetH);
         sc.format = colorFormat;
 
         XrSwapchainCreateInfo createInfo{XR_TYPE_SWAPCHAIN_CREATE_INFO};
@@ -245,8 +257,8 @@ bool XrContext::createSwapchains(int64_t colorFormat) {
                                 XR_SWAPCHAIN_USAGE_SAMPLED_BIT;
         createInfo.format = colorFormat;
         createInfo.sampleCount = 1;
-        createInfo.width = view.recommendedImageRectWidth;
-        createInfo.height = view.recommendedImageRectHeight;
+        createInfo.width = targetW;
+        createInfo.height = targetH;
         createInfo.faceCount = 1;
         createInfo.arraySize = 1;
         createInfo.mipCount = 1;
@@ -267,7 +279,9 @@ bool XrContext::createSwapchains(int64_t colorFormat) {
         swapchains_.push_back(std::move(sc));
     }
 
-    PIXELVR_LOG_INFO("Created %zu swapchains", swapchains_.size());
+    PIXELVR_LOG_INFO("Created %zu swapchains (%dx%d per eye)", swapchains_.size(),
+                     swapchains_.empty() ? 0 : swapchains_[0].width,
+                     swapchains_.empty() ? 0 : swapchains_[0].height);
     return true;
 }
 
@@ -337,6 +351,42 @@ bool XrContext::createActions() {
             gripPoseAction_ = XR_NULL_HANDLE;
         }
     }
+    {
+        XrActionCreateInfo ai{XR_TYPE_ACTION_CREATE_INFO};
+        std::strcpy(ai.actionName, "grip_full_press");
+        std::strcpy(ai.localizedActionName, "Grip Full Press Click");
+        ai.actionType = XR_ACTION_TYPE_BOOLEAN_INPUT;
+        ai.countSubactionPaths = 2;
+        ai.subactionPaths = handPaths_;
+        if (XR_FAILED(xrCreateAction(actionSet_, &ai, &gripFullPressAction_))) {
+            PIXELVR_LOG_WARN("Failed to create grip full press action");
+            gripFullPressAction_ = XR_NULL_HANDLE;
+        }
+    }
+    {
+        XrActionCreateInfo ai{XR_TYPE_ACTION_CREATE_INFO};
+        std::strcpy(ai.actionName, "squeeze_val");
+        std::strcpy(ai.localizedActionName, "Squeeze Value");
+        ai.actionType = XR_ACTION_TYPE_FLOAT_INPUT;
+        ai.countSubactionPaths = 2;
+        ai.subactionPaths = handPaths_;
+        if (XR_FAILED(xrCreateAction(actionSet_, &ai, &squeezeValueAction_))) {
+            PIXELVR_LOG_WARN("Failed to create squeeze value action");
+            squeezeValueAction_ = XR_NULL_HANDLE;
+        }
+    }
+    {
+        XrActionCreateInfo ai{XR_TYPE_ACTION_CREATE_INFO};
+        std::strcpy(ai.actionName, "haptic_out");
+        std::strcpy(ai.localizedActionName, "Haptic Output");
+        ai.actionType = XR_ACTION_TYPE_VIBRATION_OUTPUT;
+        ai.countSubactionPaths = 2;
+        ai.subactionPaths = handPaths_;
+        if (XR_FAILED(xrCreateAction(actionSet_, &ai, &hapticAction_))) {
+            PIXELVR_LOG_WARN("Failed to create haptic action");
+            hapticAction_ = XR_NULL_HANDLE;
+        }
+    }
 
     // Physical buttons for user-configurable bindings (native Steam Frame paths).
     static const struct {
@@ -344,11 +394,11 @@ bool XrContext::createActions() {
         const char* p0;
         const char* p1;
     } kBtns[] = {
-        {"btn_a", "/user/hand/right/input/a/click", nullptr},
-        {"btn_b", "/user/hand/right/input/b/click", nullptr},
-        {"btn_x", "/user/hand/right/input/x/click", nullptr},
-        {"btn_y", "/user/hand/right/input/y/click", nullptr},
-        {"btn_menu", "/user/hand/right/input/menu/click", nullptr},
+        {"btn_a", "/user/hand/right/input/a/click", "/user/hand/left/input/a/click"},
+        {"btn_b", "/user/hand/right/input/b/click", "/user/hand/left/input/b/click"},
+        {"btn_x", "/user/hand/left/input/x/click", "/user/hand/right/input/x/click"},
+        {"btn_y", "/user/hand/left/input/y/click", "/user/hand/right/input/y/click"},
+        {"btn_menu", "/user/hand/left/input/menu/click", "/user/hand/right/input/menu/click"},
         {"btn_view", "/user/hand/left/input/view/click", nullptr},
         {"btn_bumper", "/user/hand/left/input/bumper/click",
          "/user/hand/right/input/bumper/click"},
@@ -397,7 +447,9 @@ bool XrContext::createActions() {
              {aimPoseAction_, path("/user/hand/left/input/aim/pose")},
              {aimPoseAction_, path("/user/hand/right/input/aim/pose")},
              {gripPoseAction_, path("/user/hand/left/input/grip/pose")},
-             {gripPoseAction_, path("/user/hand/right/input/grip/pose")}});
+             {gripPoseAction_, path("/user/hand/right/input/grip/pose")},
+             {hapticAction_, path("/user/hand/left/output/haptic")},
+             {hapticAction_, path("/user/hand/right/output/haptic")}});
 
     suggest("/interaction_profiles/oculus/touch_controller",
             {{togglePlayAction_, path("/user/hand/right/input/a/click")},
@@ -408,6 +460,8 @@ bool XrContext::createActions() {
              {selectAction_, path("/user/hand/left/input/trigger/value")},
              {recenterAction_, path("/user/hand/right/input/squeeze/value")},
              {recenterAction_, path("/user/hand/left/input/squeeze/value")},
+             {squeezeValueAction_, path("/user/hand/right/input/squeeze/value")},
+             {squeezeValueAction_, path("/user/hand/left/input/squeeze/value")},
              {thumbstickAction_, path("/user/hand/right/input/thumbstick")},
              {thumbstickAction_, path("/user/hand/left/input/thumbstick")},
              {thumbstickLeftAction_, path("/user/hand/left/input/thumbstick")},
@@ -415,7 +469,18 @@ bool XrContext::createActions() {
              {aimPoseAction_, path("/user/hand/right/input/aim/pose")},
              {aimPoseAction_, path("/user/hand/left/input/aim/pose")},
              {gripPoseAction_, path("/user/hand/right/input/grip/pose")},
-             {gripPoseAction_, path("/user/hand/left/input/grip/pose")}});
+             {gripPoseAction_, path("/user/hand/left/input/grip/pose")},
+             {hapticAction_, path("/user/hand/right/output/haptic")},
+             {hapticAction_, path("/user/hand/left/output/haptic")},
+             {buttonActions_[XrInputState::BtnA], path("/user/hand/right/input/a/click")},
+             {buttonActions_[XrInputState::BtnB], path("/user/hand/right/input/b/click")},
+             {buttonActions_[XrInputState::BtnX], path("/user/hand/left/input/x/click")},
+             {buttonActions_[XrInputState::BtnY], path("/user/hand/left/input/y/click")},
+             {buttonActions_[XrInputState::BtnMenu], path("/user/hand/left/input/menu/click")},
+             {buttonActions_[XrInputState::BtnThumb], path("/user/hand/right/input/thumbstick/click")},
+             {buttonActions_[XrInputState::BtnThumb], path("/user/hand/left/input/thumbstick/click")},
+             {buttonActions_[XrInputState::BtnGrip], path("/user/hand/right/input/squeeze/value")},
+             {buttonActions_[XrInputState::BtnGrip], path("/user/hand/left/input/squeeze/value")}});
 
     suggest("/interaction_profiles/valve/index_controller",
             {{togglePlayAction_, path("/user/hand/right/input/a/click")},
@@ -426,6 +491,10 @@ bool XrContext::createActions() {
              {selectAction_, path("/user/hand/left/input/trigger/value")},
              {recenterAction_, path("/user/hand/right/input/squeeze/value")},
              {recenterAction_, path("/user/hand/left/input/squeeze/value")},
+             {gripFullPressAction_, path("/user/hand/right/input/squeeze/click")},
+             {gripFullPressAction_, path("/user/hand/left/input/squeeze/click")},
+             {squeezeValueAction_, path("/user/hand/right/input/squeeze/value")},
+             {squeezeValueAction_, path("/user/hand/left/input/squeeze/value")},
              {thumbstickAction_, path("/user/hand/right/input/thumbstick")},
              {thumbstickAction_, path("/user/hand/left/input/thumbstick")},
              {thumbstickLeftAction_, path("/user/hand/left/input/thumbstick")},
@@ -433,7 +502,17 @@ bool XrContext::createActions() {
              {aimPoseAction_, path("/user/hand/right/input/aim/pose")},
              {aimPoseAction_, path("/user/hand/left/input/aim/pose")},
              {gripPoseAction_, path("/user/hand/right/input/grip/pose")},
-             {gripPoseAction_, path("/user/hand/left/input/grip/pose")}});
+             {gripPoseAction_, path("/user/hand/left/input/grip/pose")},
+             {hapticAction_, path("/user/hand/right/output/haptic")},
+             {hapticAction_, path("/user/hand/left/output/haptic")},
+             {buttonActions_[XrInputState::BtnA], path("/user/hand/right/input/a/click")},
+             {buttonActions_[XrInputState::BtnA], path("/user/hand/left/input/a/click")},
+             {buttonActions_[XrInputState::BtnB], path("/user/hand/right/input/b/click")},
+             {buttonActions_[XrInputState::BtnB], path("/user/hand/left/input/b/click")},
+             {buttonActions_[XrInputState::BtnThumb], path("/user/hand/right/input/thumbstick/click")},
+             {buttonActions_[XrInputState::BtnThumb], path("/user/hand/left/input/thumbstick/click")},
+             {buttonActions_[XrInputState::BtnGrip], path("/user/hand/right/input/squeeze/value")},
+             {buttonActions_[XrInputState::BtnGrip], path("/user/hand/left/input/squeeze/value")}});
 
     // Native Steam Frame profile: the runtime rejects the whole set if any path
     // is invalid, so probe each candidate individually, keep the accepted ones,
@@ -466,6 +545,16 @@ bool XrContext::createActions() {
         probe(recenterAction_, "/user/hand/right/input/squeeze/value");
         probe(recenterAction_, "/user/hand/left/input/grip/value");
         probe(recenterAction_, "/user/hand/right/input/grip/value");
+        probe(gripFullPressAction_, "/user/hand/left/input/squeeze/click");
+        probe(gripFullPressAction_, "/user/hand/right/input/squeeze/click");
+        probe(gripFullPressAction_, "/user/hand/left/input/grip/click");
+        probe(gripFullPressAction_, "/user/hand/right/input/grip/click");
+        probe(squeezeValueAction_, "/user/hand/left/input/squeeze/value");
+        probe(squeezeValueAction_, "/user/hand/right/input/squeeze/value");
+        probe(squeezeValueAction_, "/user/hand/left/input/grip/value");
+        probe(squeezeValueAction_, "/user/hand/right/input/grip/value");
+        probe(hapticAction_, "/user/hand/left/output/haptic");
+        probe(hapticAction_, "/user/hand/right/output/haptic");
         probe(togglePlayAction_, "/user/hand/right/input/a/click");
         probe(browserAction_, "/user/hand/right/input/b/click");
         probe(browserAction_, "/user/hand/left/input/view/click");
@@ -549,6 +638,22 @@ void XrContext::syncActions() {
         return;
     }
 
+    if (!sessionFocused()) {
+        // Yield controller input and clear all held inputs when the session does not have focus (e.g. Steam dashboard).
+        input_.selectHeld = false;
+        input_.thumbstickX = 0.0f;
+        input_.thumbstickY = 0.0f;
+        input_.thumbstickLX = 0.0f;
+        input_.thumbstickLY = 0.0f;
+        input_.thumbstickRX = 0.0f;
+        input_.thumbstickRY = 0.0f;
+        for (int h = 0; h < 2; ++h) {
+            input_.gripValue[h] = 0.0f;
+            input_.gripFullPressHeld[h] = false;
+        }
+        return;
+    }
+
     XrActiveActionSet active{actionSet_, XR_NULL_PATH};
     XrActionsSyncInfo sync{XR_TYPE_ACTIONS_SYNC_INFO};
     sync.countActiveActionSets = 1;
@@ -645,6 +750,69 @@ void XrContext::syncActions() {
             }
         }
     }
+
+    // Discrete full-press click vs analog soft squeeze
+    for (int h = 0; h < 2; ++h) {
+        float sqVal = 0.0f;
+        if (squeezeValueAction_ != XR_NULL_HANDLE) {
+            XrActionStateGetInfo gi{XR_TYPE_ACTION_STATE_GET_INFO};
+            gi.action = squeezeValueAction_;
+            gi.subactionPath = handPaths_[h];
+            XrActionStateFloat st{XR_TYPE_ACTION_STATE_FLOAT};
+            if (XR_SUCCEEDED(xrGetActionStateFloat(session_, &gi, &st)) && st.isActive) {
+                sqVal = st.currentState;
+            }
+        }
+        input_.gripValue[h] = sqVal;
+
+        bool fullHeld = false;
+        bool fullDown = false;
+        if (gripFullPressAction_ != XR_NULL_HANDLE) {
+            XrActionStateGetInfo gi{XR_TYPE_ACTION_STATE_GET_INFO};
+            gi.action = gripFullPressAction_;
+            gi.subactionPath = handPaths_[h];
+            XrActionStateBoolean st{XR_TYPE_ACTION_STATE_BOOLEAN};
+            if (XR_SUCCEEDED(xrGetActionStateBoolean(session_, &gi, &st)) && st.isActive) {
+                fullHeld = st.currentState;
+                fullDown = st.currentState && st.changedSinceLastSync;
+            }
+        }
+        // Fallback for hardware profiles where squeeze/click is not exposed separately:
+        // Use a strict bottom-out threshold (>= 0.90f to engage, < 0.80f to release)
+        static bool sPrevFull[2] = {false, false};
+        if (!fullHeld) {
+            if (sPrevFull[h]) {
+                if (sqVal >= 0.80f) {
+                    fullHeld = true;
+                } else {
+                    sPrevFull[h] = false;
+                }
+            } else {
+                if (sqVal >= 0.90f) {
+                    fullHeld = true;
+                    fullDown = true;
+                    sPrevFull[h] = true;
+                }
+            }
+        }
+        input_.gripFullPressHeld[h] = fullHeld;
+        input_.gripFullPressDown[h] = fullDown;
+    }
+}
+
+void XrContext::triggerHaptic(int hand, float durationSec, float frequencyHz, float amplitude) {
+    if (session_ == XR_NULL_HANDLE || hapticAction_ == XR_NULL_HANDLE) return;
+    if (hand < 0 || hand >= 2 || handPaths_[hand] == XR_NULL_PATH) return;
+
+    XrHapticVibration vib{XR_TYPE_HAPTIC_VIBRATION};
+    vib.duration = static_cast<XrDuration>(durationSec * 1e9f);
+    vib.frequency = frequencyHz;
+    vib.amplitude = std::clamp(amplitude, 0.0f, 1.0f);
+
+    XrHapticActionInfo hai{XR_TYPE_HAPTIC_ACTION_INFO};
+    hai.action = hapticAction_;
+    hai.subactionPath = handPaths_[hand];
+    xrApplyHapticFeedback(session_, &hai, reinterpret_cast<const XrHapticBaseHeader*>(&vib));
 }
 
 void XrContext::handleSessionStateChange(const XrEventDataSessionStateChanged& ev,
@@ -757,7 +925,8 @@ bool XrContext::renderFrame(const RenderViewFn& renderView) {
     // Locate each controller's aim pose (for the pointer rays and models).
     for (int h = 0; h < 2; ++h) {
         input_.controllers[h].active = false;
-        if (aimSpaces_[h] == XR_NULL_HANDLE) {
+        const bool canTrack = sessionFocused() || VrKeyboard::instance().isOpen();
+        if (!canTrack || aimSpaces_[h] == XR_NULL_HANDLE) {
             continue;
         }
         XrSpaceLocation loc{XR_TYPE_SPACE_LOCATION};
@@ -785,7 +954,8 @@ bool XrContext::renderFrame(const RenderViewFn& renderView) {
     // the model is authored around the grip, not the forward-pointing aim).
     for (int h = 0; h < 2; ++h) {
         input_.controllers[h].gripActive = false;
-        if (gripSpaces_[h] == XR_NULL_HANDLE) {
+        const bool canTrack = sessionFocused() || VrKeyboard::instance().isOpen();
+        if (!canTrack || gripSpaces_[h] == XR_NULL_HANDLE) {
             continue;
         }
         XrSpaceLocation loc{XR_TYPE_SPACE_LOCATION};

src/xr/xr_context.hpp

@@ -61,6 +61,12 @@ struct XrInputState {
     // one controller can drive a panel with the stick while the other points.
     // Index 0 = left, 1 = right.
     bool gripDown[2] = {false, false};
+
+    // Discrete full-press click per hand (Index / Frame / Touch squeeze click).
+    // Distinct from soft/resting squeeze. Index 0 = left, 1 = right.
+    bool gripFullPressHeld[2] = {false, false};
+    bool gripFullPressDown[2] = {false, false};
+    float gripValue[2] = {0.0f, 0.0f};  // analog soft squeeze value (0.0 to 1.0)
 };
 
 // Owns the OpenXR instance, system, session, reference space, and swapchains,
@@ -94,12 +100,14 @@ public:
     // Controller input (OpenXR actions). Call createActions after createSession.
     bool createActions();
     const XrInputState& input() const { return input_; }
+    void triggerHaptic(int hand, float durationSec = 0.015f, float frequencyHz = 0.0f, float amplitude = 0.5f);
 
     // --- Runtime ---------------------------------------------------------
     // Pumps the event queue and advances the session state machine.
     // Sets exitRequested when the runtime asks the app to quit.
     bool pollEvents(bool& exitRequested);
     bool sessionRunning() const { return sessionRunning_; }
+    bool sessionFocused() const { return sessionState_ == XR_SESSION_STATE_FOCUSED; }
 
     // Callback invoked once per view when the frame should be rendered.
     using RenderViewFn = std::function<void(uint32_t viewIndex, uint32_t imageIndex,
@@ -161,6 +169,9 @@ private:
     XrAction aimPoseAction_ = XR_NULL_HANDLE;
     XrAction gripPoseAction_ = XR_NULL_HANDLE;
     XrAction buttonActions_[XrInputState::BtnCount] = {};
+    XrAction gripFullPressAction_ = XR_NULL_HANDLE;
+    XrAction squeezeValueAction_ = XR_NULL_HANDLE;
+    XrAction hapticAction_ = XR_NULL_HANDLE;
     XrPath handPaths_[2] = {XR_NULL_PATH, XR_NULL_PATH};
     XrSpace aimSpaces_[2] = {XR_NULL_HANDLE, XR_NULL_HANDLE};
     XrSpace gripSpaces_[2] = {XR_NULL_HANDLE, XR_NULL_HANDLE};

tests/test_ipv4.cpp

@@ -0,0 +1,36 @@
+#include "util/ipv4.hpp"
+#include <cassert>
+#include <iostream>
+
+using namespace pixelvr;
+
+int main() {
+    std::cout << "[TEST] Starting IPv4 sanitization & validation test..." << std::endl;
+
+    // Normal valid IP
+    assert(sanitizeIpv4("192.168.1.1", true) == "192.168.1.1");
+    assert(isValidIpv4("192.168.1.1"));
+
+    // Leading zeros dropped in each section
+    assert(sanitizeIpv4("192.168.01.005", true) == "192.168.1.5");
+    assert(sanitizeIpv4("010.000.001.020", true) == "10.0.1.20");
+    assert(sanitizeIpv4("0.0.0.0", true) == "0.0.0.0");
+
+    // Clamping > 255
+    assert(sanitizeIpv4("192.168.1.300", true) == "192.168.1.255");
+    assert(sanitizeIpv4("999.999.999.999", true) == "255.255.255.255");
+
+    // Live typing with trailing dot
+    assert(sanitizeIpv4("192.168.", false) == "192.168.");
+    assert(sanitizeIpv4("192.168.", true) == "192.168");
+
+    // Non-digit characters discarded
+    assert(sanitizeIpv4("192.abc.168.foo.1.bar.100", true) == "192.168.1.100");
+    assert(sanitizeIpv4("  10 . 0 . 0 . 1  ", true) == "10.0.0.1");
+
+    // Max 4 sections (extra sections ignored)
+    assert(sanitizeIpv4("192.168.1.1.99.88", true) == "192.168.1.1");
+
+    std::cout << "[ALL TESTS PASSED] IPv4 sanitization is verified!" << std::endl;
+    return 0;
+}

tests/test_smb_creds.cpp

@@ -0,0 +1,71 @@
+#include "net/smb_credentials.hpp"
+#include <cassert>
+#include <iostream>
+#include <fstream>
+#include <filesystem>
+#include <sys/stat.h>
+
+using namespace pixelvr;
+namespace fs = std::filesystem;
+
+int main() {
+    std::cout << "[TEST] Starting SmbCredentialsManager verification..." << std::endl;
+    auto& mgr = SmbCredentialsManager::instance();
+
+    // 1. Add a protected share
+    SmbShare share1;
+    share1.id = "192.168.1.100/movies";
+    share1.name = "Living Room NAS";
+    share1.host = "192.168.1.100";
+    share1.share = "movies";
+    share1.workgroup = "MYGROUP";
+    share1.username = "nasadmin";
+    share1.password = "SuperSecretPassword123!";
+    share1.anonymous = false;
+
+    mgr.addOrUpdateShare(share1);
+    std::cout << "[PASS] Added protected share." << std::endl;
+
+    // 2. Query credentials
+    std::string user, pass, wg;
+    bool found = mgr.findCredentials("192.168.1.100", "movies", user, pass, wg);
+    assert(found);
+    assert(user == "nasadmin");
+    assert(pass == "SuperSecretPassword123!");
+    assert(wg == "MYGROUP");
+    std::cout << "[PASS] Retrieved exact credentials." << std::endl;
+
+    // 3. Check storage file permissions (must be 0600)
+    const char* home = std::getenv("HOME");
+    std::string configPath = std::string(home ? home : ".") + "/.config/pixelvr/smb_shares.json";
+    struct stat st;
+    assert(stat(configPath.c_str(), &st) == 0);
+    mode_t perm = st.st_mode & 0777;
+    std::cout << "[INFO] File permissions: 0" << std::oct << perm << std::dec << std::endl;
+    assert((perm & 0077) == 0); // No permissions for group or others
+    std::cout << "[PASS] Config file has strict 0600 permissions." << std::endl;
+
+    // 4. Verify password is encrypted on disk
+    std::ifstream cfgFile(configPath);
+    std::string content((std::istreambuf_iterator<char>(cfgFile)), std::istreambuf_iterator<char>());
+    assert(content.find("SuperSecretPassword123!") == std::string::npos);
+    std::cout << "[PASS] Password is encrypted on disk (no plaintext leak)." << std::endl;
+
+    // 5. Test auth file generation
+    std::string authPath = mgr.getAuthFilePath("192.168.1.100", "movies");
+    assert(!authPath.empty());
+    assert(stat(authPath.c_str(), &st) == 0);
+    mode_t authPerm = st.st_mode & 0777;
+    assert((authPerm & 0077) == 0); // Auth file must also be 0600
+    std::cout << "[PASS] Temporary Samba auth file generated with 0600 permissions." << std::endl;
+
+    // 6. Delete share
+    bool deleted = mgr.deleteShare("192.168.1.100", "movies");
+    assert(deleted);
+    found = mgr.findCredentials("192.168.1.100", "movies", user, pass, wg);
+    assert(!found);
+    std::cout << "[PASS] Deleted share successfully." << std::endl;
+
+    std::cout << "[ALL TESTS PASSED] SmbCredentialsManager is verified and secure!" << std::endl;
+    return 0;
+}

tests/test_vault.cpp

@@ -0,0 +1,198 @@
+#include "app/vault_manager.hpp"
+#include <cassert>
+#include <iostream>
+#include <fstream>
+#include <filesystem>
+
+using namespace pixelvr;
+namespace fs = std::filesystem;
+
+int main() {
+    std::cout << "[TEST] Starting VaultManager verification..." << std::endl;
+    auto& vm = VaultManager::instance();
+
+    // Reset to default combo sequence for reproducible testing
+    vm.startRecordingCombo();
+    vm.feedRecordButton(XrInputState::BtnA);
+    vm.feedRecordButton(XrInputState::BtnB);
+    vm.feedRecordButton(XrInputState::BtnB);
+    vm.feedRecordButton(XrInputState::BtnA);
+    vm.feedRecordButton(XrInputState::BtnX);
+    vm.feedRecordButton(XrInputState::BtnY);
+
+    // 1. Initial locked state
+    vm.lock();
+    assert(!vm.isUnlocked());
+    std::cout << "[PASS] Initial state is locked." << std::endl;
+
+    // 2. Discrete grip requirement (soft squeeze / grip=false should not advance)
+    auto now = std::chrono::steady_clock::now();
+    assert(vm.feedInput(XrInputState::BtnA, false, now) == VaultManager::ComboResult::None);
+    assert(vm.feedInput(XrInputState::BtnB, false, now) == VaultManager::ComboResult::None);
+    assert(!vm.isUnlocked());
+    std::cout << "[PASS] Soft squeeze / no grip full press does not trigger combo." << std::endl;
+
+    // 3. Step through default combo: A -> B -> B -> A -> X -> Y
+    assert(vm.feedInput(XrInputState::BtnA, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnB, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnB, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnA, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnX, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnY, true, now) == VaultManager::ComboResult::Unlocked);
+    assert(vm.isUnlocked());
+    std::cout << "[PASS] Cheat code A-B-B-A-X-Y with grip full press unlocks vault!" << std::endl;
+
+    // Verify vault directories exist and have 0700 permissions
+    assert(fs::exists(vm.vaultDir()));
+    assert(fs::exists(vm.thumbsDir()));
+    auto perms = fs::status(vm.vaultDir()).permissions();
+    assert((perms & fs::perms::others_all) == fs::perms::none);
+    std::cout << "[PASS] Vault directory created with secure 0700 permissions: " << vm.vaultDir() << std::endl;
+
+    // 4. Test re-lock via combo
+    assert(vm.feedInput(XrInputState::BtnA, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnB, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnB, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnA, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnX, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnY, true, now) == VaultManager::ComboResult::Locked);
+    assert(!vm.isUnlocked());
+    std::cout << "[PASS] Entering combo again locks the vault." << std::endl;
+
+    // 5. Test Headset removal auto-lock with 3-second debounce
+    vm.unlock();
+    assert(vm.isUnlocked());
+    assert(!vm.tick(now, false)); // Momentary flicker (<3s) does NOT lock
+    assert(vm.isUnlocked());
+    assert(vm.tick(now + std::chrono::milliseconds(3100), false)); // >=3s continuous loss locks
+    assert(!vm.isUnlocked());
+    std::cout << "[PASS] Auto-lock on headset removal successfully locks vault after 3s debounce." << std::endl;
+
+    // 6. Test Inactivity timeout (enabled vs disabled)
+    vm.unlock();
+    vm.setAutoLockTimeoutSec(2); // 2 seconds for test
+    vm.recordActivity(now);
+    assert(!vm.tick(now, true)); // immediate tick does not lock
+    assert(vm.isUnlocked());
+    assert(vm.tick(now + std::chrono::seconds(3), true)); // 3s later -> timeout
+    assert(!vm.isUnlocked());
+    std::cout << "[PASS] Inactivity timeout successfully locks vault when enabled." << std::endl;
+
+    // Test Inactivity timeout disabled (default)
+    vm.unlock();
+    vm.setAutoLockTimeoutSec(0); // 0 = disabled
+    vm.recordActivity(now);
+    assert(!vm.tick(now + std::chrono::hours(1), true)); // 1 hour later -> still unlocked because disabled
+    assert(vm.isUnlocked());
+    std::cout << "[PASS] Inactivity timeout = 0 disables timeout auto-lock." << std::endl;
+
+    // 7. Test Move-to-Vault for single file and collision resolution
+    vm.unlock();
+    std::string testSrc = "/tmp/pixelvr_test_clip.mp4";
+    {
+        std::ofstream f(testSrc);
+        f << "dummy video content 12345";
+    }
+    std::string outPath1;
+    std::string err1 = vm.moveFileToVault(testSrc, outPath1);
+    assert(err1.empty());
+    assert(!fs::exists(testSrc));
+    assert(fs::exists(outPath1));
+    std::cout << "[PASS] Move file to vault succeeded: " << outPath1 << std::endl;
+
+    // Collision test: create another file with same name
+    {
+        std::ofstream f(testSrc);
+        f << "dummy video content second version";
+    }
+    std::string outPath2;
+    std::string err2 = vm.moveFileToVault(testSrc, outPath2);
+    assert(err2.empty());
+    assert(!fs::exists(testSrc));
+    assert(fs::exists(outPath2));
+    assert(outPath1 != outPath2);
+    std::cout << "[PASS] Collision resolved properly: " << outPath2 << std::endl;
+
+    // Clean up test files
+    fs::remove(outPath1);
+    fs::remove(outPath2);
+
+    // 8. Test Move-to-Vault for entire directory and recursive permissions
+    std::string testDir = "/tmp/pixelvr_test_folder";
+    fs::create_directories(testDir);
+    {
+        std::ofstream f1(testDir + "/subvideo1.mp4");
+        f1 << "sub video 1 content";
+        std::ofstream f2(testDir + "/subvideo2.mp4");
+        f2 << "sub video 2 content";
+    }
+    std::string outDir1;
+    std::string errDir1 = vm.moveFileToVault(testDir, outDir1);
+    assert(errDir1.empty());
+    assert(!fs::exists(testDir));
+    assert(fs::exists(outDir1));
+    assert(fs::is_directory(outDir1));
+    assert(fs::exists(outDir1 + "/subvideo1.mp4"));
+    assert(fs::exists(outDir1 + "/subvideo2.mp4"));
+
+    // Check directory permissions
+    auto dirPerms = fs::status(outDir1).permissions();
+    assert((dirPerms & fs::perms::others_all) == fs::perms::none);
+    std::cout << "[PASS] Move entire folder to vault succeeded with 0700 permissions: " << outDir1 << std::endl;
+
+    // Folder collision test: recreate folder and move again
+    fs::create_directories(testDir);
+    {
+        std::ofstream f(testDir + "/subvideo3.mp4");
+        f << "sub video 3 content";
+    }
+    std::string outDir2;
+    std::string errDir2 = vm.moveFileToVault(testDir, outDir2);
+    assert(errDir2.empty());
+    assert(!fs::exists(testDir));
+    assert(fs::exists(outDir2));
+    assert(outDir1 != outDir2);
+    assert(fs::exists(outDir2 + "/subvideo3.mp4"));
+    std::cout << "[PASS] Folder collision resolved properly: " << outDir2 << std::endl;
+
+    // Clean up test directories
+    fs::remove_all(outDir1);
+    fs::remove_all(outDir2);
+
+    // 9. Custom combo recording
+    vm.startRecordingCombo();
+    assert(vm.isRecordingCombo());
+    assert(!vm.feedRecordButton(XrInputState::BtnX));
+    assert(!vm.feedRecordButton(XrInputState::BtnX));
+    assert(!vm.feedRecordButton(XrInputState::BtnY));
+    assert(!vm.feedRecordButton(XrInputState::BtnY));
+    assert(!vm.feedRecordButton(XrInputState::BtnA));
+    assert(vm.feedRecordButton(XrInputState::BtnB)); // 6th button finishes
+    assert(!vm.isRecordingCombo());
+    assert(vm.comboString() == "X X Y Y A B");
+    std::cout << "[PASS] Custom combo recording verified: " << vm.comboString() << std::endl;
+
+    // Test new combo works
+    vm.lock();
+    assert(vm.feedInput(XrInputState::BtnX, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnX, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnY, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnY, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnA, true, now) == VaultManager::ComboResult::StepMatched);
+    assert(vm.feedInput(XrInputState::BtnB, true, now) == VaultManager::ComboResult::Unlocked);
+    assert(vm.isUnlocked());
+    std::cout << "[PASS] New custom combo successfully unlocked vault!" << std::endl;
+
+    // Restore default combo
+    vm.startRecordingCombo();
+    vm.feedRecordButton(XrInputState::BtnA);
+    vm.feedRecordButton(XrInputState::BtnB);
+    vm.feedRecordButton(XrInputState::BtnB);
+    vm.feedRecordButton(XrInputState::BtnA);
+    vm.feedRecordButton(XrInputState::BtnX);
+    vm.feedRecordButton(XrInputState::BtnY);
+    vm.lock();
+
+    std::cout << "\n*** ALL VAULT MANAGER UNIT TESTS PASSED PERFECTLY! ***" << std::endl;
+    return 0;
+}

tools/Install Pixel VR Player.desktop

@@ -0,0 +1,8 @@
+[Desktop Entry]
+Name=Install Pixel VR Player
+Comment=Install Pixel VR Player for Valve Steam Frame
+Exec=bash -c 'SCRIPT_DIR="$(dirname "%k")"; if [ -f "$SCRIPT_DIR/install.sh" ]; then cd "$SCRIPT_DIR" && bash install.sh; else curl -fsSL https://raw.githubusercontent.com/Pixelplanet/Pixel-VR-Player/main/tools/install.sh | bash; fi; if [ $? -eq 0 ]; then command -v kdialog >/dev/null && kdialog --title "Pixel VR Player" --msgbox "Installation complete!\n\nPixel VR Player has been added to your Steam Library.\nYou can now return to Gaming Mode."; else command -v kdialog >/dev/null && kdialog --title "Pixel VR Player" --error "Installation encountered an issue.\nCheck ~/pixelvr-install.log or terminal output."; fi; read -p "Press Enter to close..." dummy'
+Icon=steam
+Terminal=true
+Type=Application
+Categories=AudioVideo;Player;VR;

tools/Update Pixel VR Player.desktop

@@ -0,0 +1,8 @@
+[Desktop Entry]
+Name=Update Pixel VR Player
+Comment=Update Pixel VR Player to the latest version on Valve Steam Frame
+Exec=bash -c 'SCRIPT_DIR="$(dirname "%k")"; if [ -f "$HOME/PixelVRPlayer/update.sh" ]; then bash "$HOME/PixelVRPlayer/update.sh"; elif [ -f "$SCRIPT_DIR/update.sh" ]; then cd "$SCRIPT_DIR" && bash update.sh; else curl -fsSL https://raw.githubusercontent.com/Pixelplanet/Pixel-VR-Player/main/tools/install.sh | bash -s -- --update; fi; if [ $? -eq 0 ]; then command -v kdialog >/dev/null && kdialog --title "Pixel VR Player" --msgbox "Update complete!\n\nPixel VR Player has been updated to the latest version.\nYou can now return to Gaming Mode."; else command -v kdialog >/dev/null && kdialog --title "Pixel VR Player" --error "Update encountered an issue.\nCheck terminal output or internet connection."; fi; read -p "Press Enter to close..." dummy'
+Icon=steam
+Terminal=true
+Type=Application
+Categories=AudioVideo;Player;VR;

tools/deploy.py

@@ -127,7 +127,7 @@ def main() -> int:
         'mkdir -p "$target/shaders"; printf %s "$target"'
     )
 
-    # 2. Copy binary, shaders and the direct-run helper.
+    # 2. Copy binary, shaders, launcher, and icon.
     print("Copying binary ...")
     scp([str(binary)], f"{REMOTE_DIR}/pixelvr")
     if shaders:
@@ -136,6 +136,10 @@ def main() -> int:
     launch_helper = PROJECT_ROOT / "tools" / "launch.sh"
     if launch_helper.is_file():
         scp([str(launch_helper)], f"{REMOTE_DIR}/launch.sh")
+    for asset_name in ("icon.png", "hero.png", "capsule.png", "header.png", "logo.png"):
+        asset_file = PROJECT_ROOT / "assets" / asset_name
+        if asset_file.is_file():
+            scp([str(asset_file)], f"{REMOTE_DIR}/{asset_name}")
 
     # 3. Register the Non-Steam shortcut (runs on the host, not in Sniper).
     request = {
@@ -165,6 +169,83 @@ def main() -> int:
     if isinstance(response, dict) and response.get("error"):
         raise RuntimeError(f"shortcut registration failed: {response['error']}")
 
+    # 3b. Sanitize shortcuts.vdf to remove the 'Devkit Game: ' prefix and set icon.
+    sanitize_script = (
+        "import glob, os, struct, shutil\n"
+        "OBJ, STR, INT, U64, END = 0, 1, 2, 7, 8\n"
+        "def read_cstr(buf, pos):\n"
+        "    end = buf.find(b'\\0', pos)\n"
+        "    return buf[pos:end].decode('utf-8', 'surrogateescape'), end + 1\n"
+        "def parse_obj(buf, pos):\n"
+        "    entries = {}\n"
+        "    while pos < len(buf):\n"
+        "        kind = buf[pos]\n"
+        "        if kind in (END, 0x0B): return entries, pos + 1\n"
+        "        key, pos = read_cstr(buf, pos + 1)\n"
+        "        if kind == OBJ: value, pos = parse_obj(buf, pos)\n"
+        "        elif kind == STR: value, pos = read_cstr(buf, pos)\n"
+        "        elif kind == INT: value = struct.unpack_from('<i', buf, pos)[0]; pos += 4\n"
+        "        elif kind == U64: value = struct.unpack_from('<Q', buf, pos)[0]; pos += 8\n"
+        "        else: break\n"
+        "        entries[key] = [kind, value]\n"
+        "    return entries, pos\n"
+        "def dump(entries):\n"
+        "    out = bytearray()\n"
+        "    for key, (kind, value) in entries.items():\n"
+        "        kb = key.encode('utf-8', 'surrogateescape')\n"
+        "        if kind == OBJ: out += bytes([OBJ]) + kb + b'\\0' + dump(value) + bytes([END])\n"
+        "        elif kind == STR: out += bytes([STR]) + kb + b'\\0' + value.encode('utf-8', 'surrogateescape') + b'\\0'\n"
+        "        elif kind == INT: out += bytes([INT]) + kb + b'\\0' + struct.pack('<i', value)\n"
+        "        elif kind == U64: out += bytes([U64]) + kb + b'\\0' + struct.pack('<Q', value)\n"
+        "    return bytes(out)\n"
+        "for vdf in glob.glob(os.path.expanduser('~/.steam/steam/userdata/*/config/shortcuts.vdf')):\n"
+        "    try:\n"
+        "        with open(vdf, 'rb') as f: data = f.read()\n"
+        "        if not data or data[0] != OBJ: continue\n"
+        "        key, pos = read_cstr(data, 1)\n"
+        "        s_dict, _ = parse_obj(data, pos)\n"
+        "        mod = False\n"
+        "        for k, v in s_dict.items():\n"
+        "            if isinstance(v, list) and v[0] == OBJ:\n"
+        "                e = v[1]\n"
+        "                name = e.get('AppName', [STR, ''])[1]\n"
+        "                if 'Pixel' in name:\n"
+        "                    e['AppName'] = [STR, 'Pixel VR Player']\n"
+        "                    e['Devkit'] = [INT, 0]\n"
+        "                    e['DevkitGameID'] = [STR, '']\n"
+        "                    icon_p = os.path.expanduser('~/" + REMOTE_DIR + "/icon.png')\n"
+        "                    hero_p = os.path.expanduser('~/" + REMOTE_DIR + "/hero.png')\n"
+        "                    capsule_p = os.path.expanduser('~/" + REMOTE_DIR + "/capsule.png')\n"
+        "                    header_p = os.path.expanduser('~/" + REMOTE_DIR + "/header.png')\n"
+        "                    logo_p = os.path.expanduser('~/" + REMOTE_DIR + "/logo.png')\n"
+        "                    grid = os.path.join(os.path.dirname(os.path.dirname(vdf)), 'config', 'grid')\n"
+        "                    os.makedirs(grid, exist_ok=True)\n"
+        "                    raw_id = e.get('appid', [INT, 0])[1] & 0xFFFFFFFF\n"
+        "                    if os.path.isfile(icon_p):\n"
+        "                        e['icon'] = [STR, icon_p]\n"
+        "                        shutil.copyfile(icon_p, os.path.join(grid, f'{raw_id}_icon.png'))\n"
+        "                    if os.path.isfile(capsule_p):\n"
+        "                        shutil.copyfile(capsule_p, os.path.join(grid, f'{raw_id}p.png'))\n"
+        "                    elif os.path.isfile(icon_p):\n"
+        "                        shutil.copyfile(icon_p, os.path.join(grid, f'{raw_id}p.png'))\n"
+        "                    if os.path.isfile(header_p):\n"
+        "                        shutil.copyfile(header_p, os.path.join(grid, f'{raw_id}.png'))\n"
+        "                    elif os.path.isfile(icon_p):\n"
+        "                        shutil.copyfile(icon_p, os.path.join(grid, f'{raw_id}.png'))\n"
+        "                    if os.path.isfile(hero_p):\n"
+        "                        shutil.copyfile(hero_p, os.path.join(grid, f'{raw_id}_hero.png'))\n"
+        "                    if os.path.isfile(logo_p):\n"
+        "                        shutil.copyfile(logo_p, os.path.join(grid, f'{raw_id}_logo.png'))\n"
+        "                    mod = True\n"
+        "        if mod:\n"
+        "            tmp = vdf + '.tmp'\n"
+        "            with open(tmp, 'wb') as f: f.write(dump({key: [OBJ, s_dict]}) + bytes([END]))\n"
+        "            os.replace(tmp, vdf)\n"
+        "    except Exception:\n"
+        "        pass\n"
+    )
+    ssh(f"python3 -c {shlex.quote(sanitize_script)}")
+
     # 4. Optionally launch it in the headset.
     if args.launch:
         print("Launching in the headset ...")
@@ -184,7 +265,7 @@ def main() -> int:
     print(f"Deployed to {host}:~/{REMOTE_DIR}")
     if player_args:
         print("  argv:", " ".join(["./pixelvr", *player_args]))
-    print(f"  Launch from Steam > Library > Non-Steam > 'Devkit Game: {GAME}'")
+    print("  Launch from Steam > Library > Non-Steam > 'Pixel VR Player'")
     print(f"  Or over SSH:  ssh {host} '{REMOTE_DIR}/launch.sh <video>'")
     return 0
 

tools/install-from-pc.bat

@@ -0,0 +1,54 @@
+@echo off
+setlocal enabledelayedexpansion
+
+echo ===============================================================
+echo        Pixel VR Player - Steam Frame Remote Installer
+echo ===============================================================
+echo  This tool installs Pixel VR Player on your Valve Steam Frame
+echo  over your local Wi-Fi network directly from your PC.
+echo ===============================================================
+echo.
+
+set "FRAME_IP=steamframe.local"
+set /p "INPUT_IP=Enter Steam Frame IP address [press Enter for steamframe.local]: "
+if not "!INPUT_IP!"=="" set "FRAME_IP=!INPUT_IP!"
+
+echo.
+echo Connecting to steamos@!FRAME_IP!...
+echo (If prompted for a password, enter your SteamOS desktop password)
+echo.
+
+where ssh >nul 2>&1
+if %ERRORLEVEL% neq 0 (
+    echo [ERROR] SSH is not installed or not in PATH on this PC.
+    pause
+    exit /b 1
+)
+
+set "EXTRA_ARGS=%*"
+if "%EXTRA_ARGS%"=="" (
+    set "REMOTE_CMD=curl -fsSL https://raw.githubusercontent.com/Pixelplanet/Pixel-VR-Player/main/tools/install.sh | sh"
+) else (
+    set "REMOTE_CMD=curl -fsSL https://raw.githubusercontent.com/Pixelplanet/Pixel-VR-Player/main/tools/install.sh | sh -s -- %EXTRA_ARGS%"
+)
+
+ssh -o StrictHostKeyChecking=no steamos@!FRAME_IP! "!REMOTE_CMD!"
+
+if %ERRORLEVEL% equ 0 (
+    echo.
+    echo ===============================================================
+    echo  [SUCCESS] Operation completed on your Steam Frame!
+    echo ===============================================================
+) else (
+    echo.
+    echo ===============================================================
+    echo  [NOTE] If connection failed, please ensure:
+    echo   1. Both your PC and Steam Frame are on the same Wi-Fi.
+    echo   2. SSH is enabled on the headset.
+    echo      (In Desktop Mode, open Konsole and run 'passwd',
+    echo       then 'sudo systemctl start sshd', or enable Dev Mode).
+    echo ===============================================================
+)
+
+echo.
+pause

tools/install-from-pc.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Pixel VR Player - Remote installer from Mac / Linux to Steam Frame
+
+set -euo pipefail
+
+echo "==============================================================="
+echo "       Pixel VR Player - Steam Frame Remote Installer"
+echo "==============================================================="
+echo " This tool installs Pixel VR Player on your Valve Steam Frame"
+echo " over your local Wi-Fi network directly from your Mac or PC."
+echo "==============================================================="
+echo ""
+
+read -rp "Enter Steam Frame IP address [press Enter for steamframe.local]: " INPUT_IP
+FRAME_IP="${INPUT_IP:-steamframe.local}"
+
+echo ""
+echo "Connecting to steamos@${FRAME_IP}..."
+echo "(If prompted for a password, enter your SteamOS desktop password)"
+echo ""
+
+EXTRA_ARGS="${*:-}"
+if [ -n "${EXTRA_ARGS}" ]; then
+    REMOTE_CMD="curl -fsSL https://raw.githubusercontent.com/Pixelplanet/Pixel-VR-Player/main/tools/install.sh | sh -s -- ${EXTRA_ARGS}"
+else
+    REMOTE_CMD="curl -fsSL https://raw.githubusercontent.com/Pixelplanet/Pixel-VR-Player/main/tools/install.sh | sh"
+fi
+
+if ssh -o StrictHostKeyChecking=no "steamos@${FRAME_IP}" "${REMOTE_CMD}"; then
+    echo ""
+    echo "==============================================================="
+    if [[ "${EXTRA_ARGS}" == *"--uninstall"* ]]; then
+        echo " [SUCCESS] Pixel VR Player removed from your Steam Frame!"
+    else
+        echo " [SUCCESS] Pixel VR Player installed on your Steam Frame!"
+        echo " It is now in your Steam Library under Non-Steam Games."
+    fi
+    echo "==============================================================="
+else
+    echo ""
+    echo "==============================================================="
+    echo " [NOTE] If connection failed, please ensure:"
+    echo "  1. Both devices are on the same Wi-Fi network."
+    echo "  2. SSH is enabled on the headset."
+    echo "     (In Desktop Mode, open Konsole and run 'passwd',"
+    echo "      then 'sudo systemctl start sshd', or enable Dev Mode)."
+    echo "==============================================================="
+fi

tools/install.sh

@@ -0,0 +1,643 @@
+#!/bin/sh
+# Pixel VR Player installer for the Valve Steam Frame.
+#
+# Download-and-run (no other files needed):
+#   curl -fsSL https://raw.githubusercontent.com/Pixelplanet/Pixel-VR-Player/main/tools/install.sh | sh
+#
+# Or from an extracted release tarball:
+#   ./install.sh
+#
+# Options:
+#   --dir DIR           install directory (default: ~/PixelVRPlayer)
+#   --version vX.Y.Z    release to install (default: the latest release)
+#   --no-steam          do not add the Non-Steam Game shortcut
+#   --restart-steam     close Steam before registering, then start it again
+#   --uninstall         remove the app and its Steam shortcut
+#   --force             install even if the CPU is not aarch64
+#   -h, --help          show this help
+#
+# Settings (~/.config/pixelvr) and the thumbnail cache (~/.cache/pixelvr) live
+# outside the install directory, so reinstalling or upgrading never loses them.
+set -eu
+
+REPO="Pixelplanet/Pixel-VR-Player"
+ASSET="pixelvr-linux-arm64.tar.gz"
+APP_NAME="Pixel VR Player"
+
+INSTALL_DIR="${PIXELVR_INSTALL_DIR:-$HOME/PixelVRPlayer}"
+VERSION=""
+DO_STEAM=1
+RESTART_STEAM=0
+UNINSTALL=0
+DO_UPDATE=0
+FORCE=0
+
+if [ -t 1 ]; then
+    C_INFO=$(printf '\0033[36m')
+    C_OK=$(printf '\0033[32m')
+    C_WARN=$(printf '\0033[33m')
+    C_ERR=$(printf '\0033[31m')
+    C_OFF=$(printf '\0033[0m')
+else
+    C_INFO=""; C_OK=""; C_WARN=""; C_ERR=""; C_OFF=""
+fi
+
+info() { printf '%s==>%s %s\n' "$C_INFO" "$C_OFF" "$*"; }
+ok()   { printf '%s  ok%s %s\n' "$C_OK" "$C_OFF" "$*"; }
+warn() { printf '%swarn%s %s\n' "$C_WARN" "$C_OFF" "$*" >&2; }
+die()  { printf '%serror%s %s\n' "$C_ERR" "$C_OFF" "$*" >&2; exit 1; }
+
+usage() {
+    cat <<'USAGE'
+Pixel VR Player installer for the Valve Steam Frame.
+
+Usage:
+  curl -fsSL https://raw.githubusercontent.com/Pixelplanet/Pixel-VR-Player/main/tools/install.sh | sh
+  ./install.sh [options]
+
+Options:
+  --dir DIR           install directory (default: ~/PixelVRPlayer)
+  --version vX.Y.Z    release to install (default: the latest release)
+  --update            force fetching the latest release from GitHub
+  --no-steam          do not add the Non-Steam Game shortcut
+  --restart-steam     close Steam before registering, then start it again
+  --uninstall         remove the app and its Steam shortcut
+  --force             install even if the CPU is not aarch64
+  -h, --help          show this help
+
+Settings in ~/.config/pixelvr and cached thumbnails in ~/.cache/pixelvr are
+never touched by install, upgrade or uninstall.
+USAGE
+}
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --dir)
+            [ $# -ge 2 ] || die "--dir needs a value"
+            case "$2" in
+                "~/"*) INSTALL_DIR="$HOME/${2#\~/}" ;;
+                *) INSTALL_DIR="$2" ;;
+            esac
+            shift ;;
+        --dir=*) INSTALL_DIR="${1#--dir=}" ; case "$INSTALL_DIR" in "~/"*) INSTALL_DIR="$HOME/${INSTALL_DIR#\~/}" ;; esac ;;
+        --version)
+            [ $# -ge 2 ] || die "--version needs a value"
+            VERSION="$2"; shift ;;
+        --version=*) VERSION="${1#--version=}" ;;
+        --update) DO_UPDATE=1 ;;
+        --no-steam) DO_STEAM=0 ;;
+        --restart-steam) RESTART_STEAM=1 ;;
+        --uninstall) UNINSTALL=1 ;;
+        --force) FORCE=1 ;;
+        -h|--help) usage; exit 0 ;;
+        *) die "unknown option: $1 (try --help)" ;;
+    esac
+    shift
+done
+
+case "$INSTALL_DIR" in
+    ""|"/"|".") die "refusing to use '$INSTALL_DIR' as install directory" ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Steam shortcut registration (non-Steam game in the library)
+# ---------------------------------------------------------------------------
+steam_running() {
+    command -v pgrep >/dev/null 2>&1 && pgrep -x steam >/dev/null 2>&1
+}
+
+find_steam_userdata() {
+    steam_root=""
+    for candidate in "$HOME/.steam/steam" "$HOME/.local/share/Steam" "$HOME/.steam/root"; do
+        if [ -d "$candidate/userdata" ]; then
+            steam_root="$candidate"
+            break
+        fi
+    done
+    [ -n "$steam_root" ] || return 1
+
+    vdf=""
+    newest=0
+    for dir in "$steam_root"/userdata/*; do
+        case "${dir##*/}" in ''|*[!0-9]*) continue ;; esac
+        file="$dir/config/shortcuts.vdf"
+        [ -f "$file" ] || continue
+        stamp=$(stat -c %Y "$file" 2>/dev/null || stat -f %m "$file" 2>/dev/null || echo 0)
+        if [ -z "$vdf" ] || [ "$stamp" -ge "$newest" ]; then
+            vdf="$file"
+            newest="$stamp"
+        fi
+    done
+    if [ -z "$vdf" ]; then
+        # No shortcuts.vdf yet: create it for the most recently used account.
+        for dir in "$steam_root"/userdata/*; do
+            case "${dir##*/}" in ''|*[!0-9]*) continue ;; esac
+            [ -d "$dir/config" ] || continue
+            stamp=$(stat -c %Y "$dir/config" 2>/dev/null || stat -f %m "$dir/config" 2>/dev/null || echo 0)
+            if [ -z "$vdf" ] || [ "$stamp" -ge "$newest" ]; then
+                vdf="$dir/config/shortcuts.vdf"
+                newest="$stamp"
+            fi
+        done
+    fi
+    [ -n "$vdf" ] || return 1
+    printf '%s\n' "$vdf"
+}
+
+# Binary KeyValues editor for shortcuts.vdf. Arguments:
+#   <add|remove> <vdf path> <app name> <exe> <start dir>
+run_vdf_helper() {
+    python3 - "$@" <<'PYEOF'
+import os
+import struct
+import sys
+import zlib
+
+OBJ, STR, INT, U64, END = 0x00, 0x01, 0x02, 0x07, 0x08
+
+
+class Unsupported(Exception):
+    pass
+
+
+def read_cstr(buf, pos):
+    end = buf.find(b"\0", pos)
+    if end < 0:
+        raise ValueError("unterminated string")
+    return buf[pos:end].decode("utf-8", "surrogateescape"), end + 1
+
+
+def parse_obj(buf, pos):
+    entries = {}
+    while True:
+        if pos >= len(buf):
+            raise ValueError("truncated object")
+        kind = buf[pos]
+        if kind in (END, 0x0B):
+            return entries, pos + 1
+        key, pos = read_cstr(buf, pos + 1)
+        if kind == OBJ:
+            value, pos = parse_obj(buf, pos)
+        elif kind == STR:
+            value, pos = read_cstr(buf, pos)
+        elif kind == INT:
+            value = struct.unpack_from("<i", buf, pos)[0]
+            pos += 4
+        elif kind == U64:
+            value = struct.unpack_from("<Q", buf, pos)[0]
+            pos += 8
+        else:
+            raise Unsupported("unsupported type 0x%02x at key %r" % (kind, key))
+        entries[key] = [kind, value]
+    return entries, pos
+
+
+def parse_file(buf):
+    if not buf:
+        return {"shortcuts": [OBJ, {}]}
+    if buf[0] != OBJ:
+        raise Unsupported("not a binary KeyValues file")
+    key, pos = read_cstr(buf, 1)
+    value, _ = parse_obj(buf, pos)
+    return {key: [OBJ, value]}
+
+
+def dump(entries):
+    out = bytearray()
+    for key, (kind, value) in entries.items():
+        kb = key.encode("utf-8", "surrogateescape")
+        if kind == OBJ:
+            out += bytes([OBJ]) + kb + b"\0" + dump(value) + bytes([END])
+        elif kind == STR:
+            out += bytes([STR]) + kb + b"\0" + value.encode("utf-8", "surrogateescape") + b"\0"
+        elif kind == INT:
+            out += bytes([INT]) + kb + b"\0" + struct.pack("<i", value)
+        elif kind == U64:
+            out += bytes([U64]) + kb + b"\0" + struct.pack("<Q", value)
+    return bytes(out)
+
+
+def app_id(exe, name):
+    # Steam derives the shortcut id from the quoted exe path plus the name.
+    return (zlib.crc32((exe + name).encode("utf-8")) | 0x80000000) & 0xFFFFFFFF
+
+
+def to_i32(value):
+    return value - 0x100000000 if value >= 0x80000000 else value
+
+
+def find(shortcuts, name, exe):
+    for key in shortcuts:
+        kind, entry = shortcuts[key]
+        if kind != OBJ:
+            continue
+        stored_exe = entry.get("Exe", [STR, ""])[1].strip('"')
+        stored_name = entry.get("AppName", [STR, ""])[1]
+        devkit_id = entry.get("DevkitGameID", [STR, ""])[1]
+        if (exe and stored_exe == exe) or stored_name == name or stored_name in ("Devkit Game: PixelVRPlayer", "Devkit Game: Pixel VR Player") or devkit_id == "PixelVRPlayer":
+            return key, entry
+    return None, None
+
+
+def main():
+    mode, path, name = sys.argv[1], sys.argv[2], sys.argv[3]
+    exe = sys.argv[4] if len(sys.argv) > 4 else ""
+    start_dir = sys.argv[5] if len(sys.argv) > 5 else ""
+
+    buf = b""
+    if os.path.exists(path):
+        with open(path, "rb") as handle:
+            buf = handle.read()
+    root = parse_file(buf)
+    root_key = next((k for k in root if k.lower() == "shortcuts"), None)
+    if root_key is None:
+        root_key = "shortcuts"
+        root[root_key] = [OBJ, {}]
+    shortcuts = root[root_key][1]
+
+    key, entry = find(shortcuts, name, exe)
+
+    if mode == "remove":
+        if entry is None:
+            print("no matching shortcut, nothing to remove")
+            return 0
+        raw_appid = entry.get("appid", [INT, 0])[1] & 0xFFFFFFFF
+        if raw_appid:
+            steam_user_dir = os.path.dirname(os.path.dirname(path))
+            grid_dir = os.path.join(steam_user_dir, "config", "grid")
+            for suffix in ("", "p", "_hero", "_logo", "_icon"):
+                for ext in (".png", ".jpg"):
+                    gf = os.path.join(grid_dir, "%d%s%s" % (raw_appid, suffix, ext))
+                    if os.path.isfile(gf):
+                        try:
+                            os.remove(gf)
+                        except Exception:
+                            pass
+        del shortcuts[key]
+        renumbered = {}
+        ordered = sorted(shortcuts, key=lambda k: int(k) if k.isdigit() else 1 << 30)
+        for index, old in enumerate(ordered):
+            renumbered[str(index)] = shortcuts[old]
+        root[root_key][1] = renumbered
+        print("removed '%s' and grid artwork" % name)
+    else:
+        quoted_exe = '"%s"' % exe
+        created = entry is None
+        if created:
+            index = 0
+            for existing in shortcuts:
+                if existing.isdigit() and int(existing) >= index:
+                    index = int(existing) + 1
+            entry = {}
+            shortcuts[str(index)] = [OBJ, entry]
+        if "appid" not in entry:
+            entry["appid"] = [INT, to_i32(app_id(quoted_exe, name))]
+        icon_path = os.path.join(start_dir, "icon.png") if os.path.isfile(os.path.join(start_dir, "icon.png")) else ""
+        for field, value in (
+            ("AppName", [STR, name]),
+            ("Exe", [STR, quoted_exe]),
+            ("StartDir", [STR, '"%s"' % start_dir]),
+            ("icon", [STR, icon_path]),
+            ("ShortcutPath", [STR, ""]),
+            ("LaunchOptions", [STR, ""]),
+            ("IsHidden", [INT, 0]),
+            ("AllowDesktopConfig", [INT, 1]),
+            ("AllowOverlay", [INT, 1]),
+            ("OpenVR", [INT, 1]),
+            ("Devkit", [INT, 0]),
+            ("DevkitGameID", [STR, ""]),
+            ("DevkitOverrideAppID", [INT, 0]),
+            ("LastPlayTime", [INT, 0]),
+            ("FlatpakAppID", [STR, ""]),
+        ):
+            entry[field] = value
+        entry.setdefault("tags", [OBJ, {}])
+        if icon_path and os.path.isfile(icon_path):
+            try:
+                import shutil
+                steam_user_dir = os.path.dirname(os.path.dirname(path))
+                grid_dir = os.path.join(steam_user_dir, "config", "grid")
+                if icon_path and os.path.isfile(icon_path):
+                    shutil.copyfile(icon_path, os.path.join(grid_dir, "%d_icon.png" % raw_appid))
+                capsule_path = os.path.join(os.path.dirname(icon_path), "capsule.png") if icon_path else ""
+                if capsule_path and os.path.isfile(capsule_path):
+                    shutil.copyfile(capsule_path, os.path.join(grid_dir, "%dp.png" % raw_appid))
+                elif icon_path and os.path.isfile(icon_path):
+                    shutil.copyfile(icon_path, os.path.join(grid_dir, "%dp.png" % raw_appid))
+                header_path = os.path.join(os.path.dirname(icon_path), "header.png") if icon_path else ""
+                if header_path and os.path.isfile(header_path):
+                    shutil.copyfile(header_path, os.path.join(grid_dir, "%d.png" % raw_appid))
+                elif icon_path and os.path.isfile(icon_path):
+                    shutil.copyfile(icon_path, os.path.join(grid_dir, "%d.png" % raw_appid))
+                hero_path = os.path.join(os.path.dirname(icon_path), "hero.png") if icon_path else ""
+                if hero_path and os.path.isfile(hero_path):
+                    shutil.copyfile(hero_path, os.path.join(grid_dir, "%d_hero.png" % raw_appid))
+                logo_path = os.path.join(os.path.dirname(icon_path), "logo.png") if icon_path else ""
+                if logo_path and os.path.isfile(logo_path):
+                    shutil.copyfile(logo_path, os.path.join(grid_dir, "%d_logo.png" % raw_appid))
+            except Exception:
+                pass
+        print("%s '%s' (%d shortcut(s) in the library)" % (
+            "added" if created else "updated", name, len(shortcuts)))
+
+    data = dump(root) + bytes([END])
+    tmp = path + ".tmp"
+    with open(tmp, "wb") as handle:
+        handle.write(data)
+    if os.path.exists(path):
+        os.chmod(tmp, os.stat(path).st_mode & 0o777)
+    os.replace(tmp, path)
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Unsupported as exc:
+        sys.stderr.write("cannot edit shortcuts.vdf: %s\n" % exc)
+        sys.exit(3)
+    except Exception as exc:  # noqa: BLE001 - surface any failure to the shell
+        sys.stderr.write("cannot edit shortcuts.vdf: %s\n" % exc)
+        sys.exit(1)
+PYEOF
+}
+
+register_steam_shortcut() {
+    vdf=$(find_steam_userdata) || {
+        warn "Steam userdata not found - is Steam installed and logged in at least once?"
+        return 1
+    }
+    if ! command -v python3 >/dev/null 2>&1; then
+        warn "python3 not found - skipping Steam registration"
+        return 1
+    fi
+
+    steam_was_running=0
+    if steam_running; then
+        steam_was_running=1
+        if [ "$RESTART_STEAM" -eq 1 ]; then
+            info "Closing Steam so the new shortcut is kept..."
+            steam -shutdown >/dev/null 2>&1 || true
+            waited=0
+            while steam_running && [ "$waited" -lt 30 ]; do
+                sleep 1
+                waited=$((waited + 1))
+            done
+            if steam_running; then
+                warn "Steam did not close in time"
+            fi
+        else
+            warn "Steam is running - restart Steam afterwards to see '$APP_NAME' in the library"
+        fi
+    fi
+
+    if [ -f "$vdf" ]; then
+        backup="$vdf.bak.$(date +%Y%m%d%H%M%S)"
+        cp "$vdf" "$backup"
+    else
+        backup=""
+    fi
+
+    if ! run_vdf_helper add "$vdf" "$APP_NAME" "$INSTALL_DIR/run.sh" "$INSTALL_DIR"; then
+        [ -n "$backup" ] && [ -f "$backup" ] && cp "$backup" "$vdf"
+        return 1
+    fi
+    [ -n "$backup" ] && ok "shortcuts.vdf backed up to ${backup}"
+
+    if [ "$RESTART_STEAM" -eq 1 ] && [ "$steam_was_running" -eq 1 ] && ! steam_running; then
+        info "Starting Steam again..."
+        if command -v steam >/dev/null 2>&1; then
+            nohup steam >/dev/null 2>&1 &
+        fi
+    fi
+    STEAM_REGISTERED=1
+}
+
+unregister_steam_shortcut() {
+    vdf=$(find_steam_userdata) || return 1
+    [ -f "$vdf" ] || return 1
+    command -v python3 >/dev/null 2>&1 || return 1
+    run_vdf_helper remove "$vdf" "$APP_NAME" "" "" || return 1
+}
+
+# ---------------------------------------------------------------------------
+# Uninstall
+# ---------------------------------------------------------------------------
+if [ "$UNINSTALL" -eq 1 ]; then
+    info "Removing Pixel VR Player from $INSTALL_DIR"
+    if [ "$DO_STEAM" -eq 1 ]; then
+        if unregister_steam_shortcut; then
+            ok "removed the Steam shortcut"
+        else
+            warn "could not remove the Steam shortcut; delete it in Steam manually"
+        fi
+    fi
+    rm -rf "$INSTALL_DIR"
+    rm -f "$HOME/Desktop/Update Pixel VR Player.desktop"
+    ok "removed $INSTALL_DIR"
+    printf '\nSettings (%s/.config/pixelvr) and cached thumbnails were kept.\n' "$HOME"
+    printf 'Delete them too with: rm -rf ~/.config/pixelvr ~/.cache/pixelvr\n'
+    exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Platform checks
+# ---------------------------------------------------------------------------
+machine=$(uname -m)
+case "$machine" in
+    aarch64|arm64) ok "CPU: $machine" ;;
+    *)
+        if [ "$FORCE" -eq 0 ]; then
+            die "this release is built for the Steam Frame (aarch64), not '$machine'.
+       Build from source for other machines, or pass --force."
+        fi
+        warn "installing an aarch64 build on '$machine' (--force)" ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Fetch (reused by the local and download paths)
+# ---------------------------------------------------------------------------
+fetch() {  # <url> <dest>
+    if command -v curl >/dev/null 2>&1; then
+        curl -fsSL "$1" -o "$2"
+    elif command -v wget >/dev/null 2>&1; then
+        wget -qO "$2" "$1"
+    else
+        die "need curl or wget to download the release"
+    fi
+}
+
+script_dir=""
+if [ -f "$0" ]; then
+    script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" 2>/dev/null && pwd) || script_dir=""
+fi
+
+tmp=""
+cleanup() { [ -z "$tmp" ] || rm -rf "$tmp"; }
+trap cleanup EXIT INT TERM
+
+if [ "$DO_UPDATE" -eq 0 ] && [ -n "$script_dir" ] && [ -f "$script_dir/pixelvr" ] && [ -d "$script_dir/shaders" ]; then
+    info "Installing from $script_dir"
+    srcdir="$script_dir"
+    if [ -f "$script_dir/VERSION" ]; then
+        VERSION="$(cat "$script_dir/VERSION")"
+    fi
+    if [ -n "$VERSION" ]; then
+        version_label="$VERSION"
+    else
+        version_label="local build"
+    fi
+else
+    case "$VERSION" in
+        "") base="https://github.com/$REPO/releases/latest/download"
+            version_label="latest" ;;
+        v*) base="https://github.com/$REPO/releases/download/$VERSION"
+            version_label="$VERSION" ;;
+        *)  VERSION="v$VERSION"
+            base="https://github.com/$REPO/releases/download/$VERSION"
+            version_label="$VERSION" ;;
+    esac
+
+    tmp=$(mktemp -d) || die "cannot create a temporary directory"
+    info "Downloading $version_label for aarch64"
+    fetch "$base/$ASSET" "$tmp/$ASSET" || die "download failed: $base/$ASSET"
+
+    if fetch "$base/$ASSET.sha256" "$tmp/$ASSET.sha256" 2>/dev/null; then
+        expected=$(awk 'NR == 1 { print $1 }' "$tmp/$ASSET.sha256")
+        if command -v sha256sum >/dev/null 2>&1; then
+            actual=$(sha256sum "$tmp/$ASSET" | awk '{ print $1 }')
+        elif command -v shasum >/dev/null 2>&1; then
+            actual=$(shasum -a 256 "$tmp/$ASSET" | awk '{ print $1 }')
+        else
+            actual=""
+        fi
+        if [ -n "$actual" ]; then
+            [ "$actual" = "$expected" ] || die "checksum mismatch for $ASSET"
+            ok "checksum verified"
+        fi
+    else
+        warn "no checksum published for this release"
+    fi
+
+    mkdir -p "$tmp/unpacked"
+    tar -xzf "$tmp/$ASSET" -C "$tmp/unpacked" || die "cannot unpack $ASSET"
+    srcdir="$tmp/unpacked/PixelVRPlayer"
+    [ -x "$srcdir/pixelvr" ] || [ -f "$srcdir/pixelvr" ] || die "unexpected archive layout"
+fi
+
+# ---------------------------------------------------------------------------
+# Install
+# ---------------------------------------------------------------------------
+info "Installing to $INSTALL_DIR"
+mkdir -p "$INSTALL_DIR/shaders"
+rm -f "$INSTALL_DIR/pixelvr"
+cp "$srcdir/pixelvr" "$INSTALL_DIR/pixelvr"
+chmod 0755 "$INSTALL_DIR/pixelvr"
+rm -f "$INSTALL_DIR/shaders/"*.spv
+cp "$srcdir/shaders/"*.spv "$INSTALL_DIR/shaders/"
+cp "$srcdir/run.sh" "$INSTALL_DIR/run.sh"
+chmod 0755 "$INSTALL_DIR/run.sh"
+INSTALLED_SCRIPT=0
+if [ -f "$srcdir/install.sh" ]; then
+    cp "$srcdir/install.sh" "$INSTALL_DIR/install.sh"
+    chmod 0755 "$INSTALL_DIR/install.sh"
+    INSTALLED_SCRIPT=1
+elif [ -n "$script_dir" ] && [ -f "$script_dir/install.sh" ]; then
+    cp "$script_dir/install.sh" "$INSTALL_DIR/install.sh"
+    chmod 0755 "$INSTALL_DIR/install.sh"
+    INSTALLED_SCRIPT=1
+fi
+# Copy updater script
+if [ -f "$srcdir/update.sh" ]; then
+    cp "$srcdir/update.sh" "$INSTALL_DIR/update.sh"
+    chmod 0755 "$INSTALL_DIR/update.sh"
+elif [ -n "$script_dir" ] && [ -f "$script_dir/update.sh" ]; then
+    cp "$script_dir/update.sh" "$INSTALL_DIR/update.sh"
+    chmod 0755 "$INSTALL_DIR/update.sh"
+elif [ -f "tools/update.sh" ]; then
+    cp "tools/update.sh" "$INSTALL_DIR/update.sh"
+    chmod 0755 "$INSTALL_DIR/update.sh"
+fi
+
+# Copy Desktop 1-click update entry
+DESKTOP_ENTRY="Update Pixel VR Player.desktop"
+if [ -f "$srcdir/$DESKTOP_ENTRY" ]; then
+    cp "$srcdir/$DESKTOP_ENTRY" "$INSTALL_DIR/$DESKTOP_ENTRY"
+    chmod 0755 "$INSTALL_DIR/$DESKTOP_ENTRY"
+elif [ -n "$script_dir" ] && [ -f "$script_dir/$DESKTOP_ENTRY" ]; then
+    cp "$script_dir/$DESKTOP_ENTRY" "$INSTALL_DIR/$DESKTOP_ENTRY"
+    chmod 0755 "$INSTALL_DIR/$DESKTOP_ENTRY"
+elif [ -f "tools/$DESKTOP_ENTRY" ]; then
+    cp "tools/$DESKTOP_ENTRY" "$INSTALL_DIR/$DESKTOP_ENTRY"
+    chmod 0755 "$INSTALL_DIR/$DESKTOP_ENTRY"
+fi
+
+# Install 1-click update shortcut to Desktop if Desktop folder exists
+if [ -d "$HOME/Desktop" ] && [ -f "$INSTALL_DIR/$DESKTOP_ENTRY" ]; then
+    cp "$INSTALL_DIR/$DESKTOP_ENTRY" "$HOME/Desktop/$DESKTOP_ENTRY"
+    chmod 0755 "$HOME/Desktop/$DESKTOP_ENTRY"
+    ok "Installed 1-click update shortcut to ~/Desktop/$DESKTOP_ENTRY"
+fi
+
+if [ -f "$srcdir/VERSION" ]; then
+    cp "$srcdir/VERSION" "$INSTALL_DIR/VERSION"
+elif [ -n "$VERSION" ]; then
+    printf '%s\n' "$VERSION" > "$INSTALL_DIR/VERSION"
+fi
+for asset in icon.png hero.png capsule.png header.png logo.png; do
+    if [ -f "$srcdir/$asset" ]; then
+        cp "$srcdir/$asset" "$INSTALL_DIR/$asset"
+    elif [ -n "$script_dir" ] && [ -f "$script_dir/$asset" ]; then
+        cp "$script_dir/$asset" "$INSTALL_DIR/$asset"
+    elif [ -f "assets/$asset" ]; then
+        cp "assets/$asset" "$INSTALL_DIR/$asset"
+    fi
+done
+ok "$(ls -1 "$INSTALL_DIR/shaders" | wc -l | tr -d ' ') shaders, $(du -h "$INSTALL_DIR/pixelvr" 2>/dev/null | cut -f1) binary"
+
+missing_libs=""
+if command -v ldd >/dev/null 2>&1; then
+    missing_libs=$(ldd "$INSTALL_DIR/pixelvr" 2>/dev/null | awk '/not found/ { print $1 }' \
+        | sort -u | tr '\n' ' ' || true)
+fi
+if [ -n "$missing_libs" ]; then
+    warn "missing shared libraries: $missing_libs"
+    warn "if these are libav* libraries, the system FFmpeg is too old"
+fi
+
+if [ ! -f /opt/steamvr/steamxr_linuxarm64.json ]; then
+    warn "SteamVR not found - install it from Steam before launching"
+fi
+
+# ---------------------------------------------------------------------------
+# Steam library entry
+# ---------------------------------------------------------------------------
+STEAM_REGISTERED=0
+if [ "$DO_STEAM" -eq 1 ]; then
+    info "Adding '$APP_NAME' to the Steam library"
+    if register_steam_shortcut; then
+        ok "Steam library entry ready"
+    else
+        warn "add $INSTALL_DIR/run.sh as a Non-Steam Game manually"
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+printf '\n%s%s installed%s\n' "$C_OK" "$APP_NAME" "$C_OFF"
+printf '  Version     : %s\n' "$version_label"
+printf '  Install dir : %s\n' "$INSTALL_DIR"
+if [ "$DO_STEAM" -eq 1 ] && [ "$STEAM_REGISTERED" -eq 1 ]; then
+    printf '  Steam entry : Non-Steam Game "%s"\n' "$APP_NAME"
+fi
+printf '\n  Launch now  : %s/run.sh\n' "$INSTALL_DIR"
+printf '  From Steam  : Library > Non-Steam > %s\n' "$APP_NAME"
+printf '  Play a clip : %s/run.sh /path/to/clip.mp4\n' "$INSTALL_DIR"
+printf '  Logs        : ~/pixelvr-run.log\n'
+printf '  1-Click Upd : %s/update.sh (or "Update Pixel VR Player" icon on Desktop)\n' "$INSTALL_DIR"
+if [ "$INSTALLED_SCRIPT" -eq 1 ]; then
+    printf '  Remove      : %s/install.sh --uninstall\n\n' "$INSTALL_DIR"
+else
+    printf '  Remove      : rerun this script with --uninstall\n\n'
+fi

tools/package-release.sh

@@ -4,9 +4,11 @@
 # Contents (extracted to ~/PixelVRPlayer):
 #   PixelVRPlayer/pixelvr          self-contained binary (static OpenXR loader)
 #   PixelVRPlayer/run.sh           launcher (logs to ~/pixelvr-run.log)
+#   PixelVRPlayer/install.sh       one-command installer / Steam registration
 #   PixelVRPlayer/shaders/*.spv    SPIR-V shaders
+#   PixelVRPlayer/VERSION          release tag (when given)
 #
-#   ./tools/package-release.sh [build-dir] [out-tar]
+#   ./tools/package-release.sh [build-dir] [out-tar] [version]
 #
 # Defaults: build -> pixelvr-linux-arm64.tar.gz
 set -euo pipefail
@@ -15,6 +17,7 @@ cd "$(dirname "$0")/.."
 
 BUILD_DIR="${1:-build}"
 OUT_TAR="${2:-pixelvr-linux-arm64.tar.gz}"
+VERSION="${3:-}"
 
 bin="${BUILD_DIR}/bin/pixelvr"
 if [[ ! -f "${bin}" ]]; then
@@ -33,7 +36,36 @@ mkdir -p "${stage}/PixelVRPlayer/shaders"
 cp "${bin}" "${stage}/PixelVRPlayer/pixelvr"
 cp "${BUILD_DIR}/shaders/"*.spv "${stage}/PixelVRPlayer/shaders/"
 cp tools/run.sh "${stage}/PixelVRPlayer/run.sh"
-chmod +x "${stage}/PixelVRPlayer/pixelvr" "${stage}/PixelVRPlayer/run.sh"
+cp tools/install.sh "${stage}/PixelVRPlayer/install.sh"
+if [[ -f "tools/update.sh" ]]; then
+    cp tools/update.sh "${stage}/PixelVRPlayer/update.sh"
+fi
+if [[ -f "tools/Install Pixel VR Player.desktop" ]]; then
+    cp "tools/Install Pixel VR Player.desktop" "${stage}/PixelVRPlayer/Install Pixel VR Player.desktop"
+fi
+if [[ -f "tools/Update Pixel VR Player.desktop" ]]; then
+    cp "tools/Update Pixel VR Player.desktop" "${stage}/PixelVRPlayer/Update Pixel VR Player.desktop"
+fi
+for asset in icon.png hero.png capsule.png header.png logo.png; do
+    if [[ -f "assets/${asset}" ]]; then
+        cp "assets/${asset}" "${stage}/PixelVRPlayer/${asset}"
+    fi
+done
+if [[ -n "${VERSION}" ]]; then
+    printf '%s\n' "${VERSION}" > "${stage}/PixelVRPlayer/VERSION"
+fi
+chmod +x "${stage}/PixelVRPlayer/pixelvr" \
+         "${stage}/PixelVRPlayer/run.sh" \
+         "${stage}/PixelVRPlayer/install.sh"
+if [[ -f "${stage}/PixelVRPlayer/update.sh" ]]; then
+    chmod +x "${stage}/PixelVRPlayer/update.sh"
+fi
+if [[ -f "${stage}/PixelVRPlayer/Install Pixel VR Player.desktop" ]]; then
+    chmod +x "${stage}/PixelVRPlayer/Install Pixel VR Player.desktop"
+fi
+if [[ -f "${stage}/PixelVRPlayer/Update Pixel VR Player.desktop" ]]; then
+    chmod +x "${stage}/PixelVRPlayer/Update Pixel VR Player.desktop"
+fi
 
 rm -f "${OUT_TAR}"
 tar -C "${stage}" -czf "${OUT_TAR}" PixelVRPlayer