@covas-labs/electron-vr 0.5.2 → 0.7.0

package/README.md

@@ -88,6 +88,10 @@ Use the same command with `enable`, `disable`, or `uninstall`. `npm install` doe
 
 Set `ELECTRON_VR_DISABLE_OPENVR=1` to prevent the OpenVR/SteamVR fallback while diagnosing OpenXR. When no usable OpenXR overlay path is available, the bridge selects `mock` and includes `openvr-disabled-by-env` in `probeMode`.
 
+When Virtual Desktop VDXR is the active Windows OpenXR runtime, the bridge automatically avoids the OpenVR fallback and does not initialize OpenVR during probing, because that can start SteamVR and disrupt an OpenXR game. Install and enable the OpenXR API layer to use the OpenXR application-integration path, then restart the game.
+
+OpenComposite does not implement the OpenVR overlay API required by this package. When OpenComposite is the registered OpenVR runtime, the bridge reports it in diagnostics but does not select the OpenVR backend; use a compatible OpenXR runtime with the API layer instead.
+
 Applications can manage the same per-user installation through the public API:
 
 ```ts
@@ -102,6 +106,8 @@ await VROverlay.uninstallOpenXRApiLayer();
 
 The methods return `Promise<OpenXRApiLayerStatus>` and reject when the platform is unsupported or the utility fails. Installation should require explicit user consent. It affects subsequently started OpenXR applications, so restart an already running game after installing, enabling, disabling, or uninstalling the layer. These methods support Linux x64 and Windows x64 and do not require administrator/root access for the normal per-user installation.
 
+`getOpenXRApiLayerStatus()` reports `requiresUpdate: true` when the installed layer assets differ from those bundled with the package. Re-run `installOpenXRApiLayer()` after confirmation to update them.
+
 For product UI, prefer the combined readiness report instead of interpreting raw probe fields:
 
 ```ts
@@ -111,4 +117,4 @@ console.log(report.launch.verdict, report.launch.requiredActions);
 
 `report.launch.wouldWorkNow` answers whether launching a browser overlay now is expected to produce real VR output. Otherwise, the verdict distinguishes an actionable setup/runtime/host requirement from a fundamental incompatibility. The report also exposes detailed readiness states, actionable issues, and per-feature support. See `PRODUCT_INTEGRATION.md` in the repository for the recommended consent, IPC, restart, recovery, diagnostics, and production UI flow.
 
-`getRuntimeInfo()` also includes `openvrRuntimeInstalled`, `openvrRuntimePath`, `openxrMode`, API-layer installation and connection state, protocol version, and connected OpenXR host metadata. `probeMode` includes the backend-selection decision.
+`getRuntimeInfo()` also includes `openvrRuntimeInstalled`, `openvrRuntimePath`, `openxrMode`, API-layer installation state, `openxrHostDetected`, companion connection state, protocol version, and OpenXR host metadata. `openxrHostDetected` can become true before the overlay companion connects. `probeMode` includes the backend-selection decision.

package/dist/bridge.d.ts

@@ -22,11 +22,14 @@ export interface RuntimeInfo {
     openxrApiLayerEnabled: boolean;
     openxrApiLayerManifestPath: string;
     openxrCompanionConnected: boolean;
+    openxrHostDetected: boolean;
     openxrHostProcessId: number;
     openxrHostApplicationName: string;
     openxrHostGraphicsApi: string;
     openxrHostAdapterLuid: string;
     openxrProtocolVersion: number;
+    openxrSubmittedFrameSequence: number;
+    openxrConsumedFrameSequence: number;
     openvrAvailable: boolean;
     openvrRuntimeInstalled: boolean;
     openvrRuntimePath: string;
@@ -117,6 +120,7 @@ export declare class VrBridge {
     private linuxOpenVRVisibleTexture;
     private windowsReadbackInFlight;
     private windowsReadbackPending;
+    private windowsOpenXRTextures;
     private linuxReadbackInFlight;
     private linuxReadbackPending;
     private invalidationTimer;

package/dist/bridge.js

@@ -116,11 +116,14 @@ function sanitizeRuntimeInfo(runtimeInfo) {
         openxrApiLayerEnabled: runtimeInfo.openxrApiLayerEnabled ?? false,
         openxrApiLayerManifestPath: runtimeInfo.openxrApiLayerManifestPath ?? "",
         openxrCompanionConnected: runtimeInfo.openxrCompanionConnected ?? false,
+        openxrHostDetected: runtimeInfo.openxrHostDetected ?? false,
         openxrHostProcessId: runtimeInfo.openxrHostProcessId ?? 0,
         openxrHostApplicationName: runtimeInfo.openxrHostApplicationName ?? "",
         openxrHostGraphicsApi: runtimeInfo.openxrHostGraphicsApi ?? "",
         openxrHostAdapterLuid: runtimeInfo.openxrHostAdapterLuid ?? "",
         openxrProtocolVersion: runtimeInfo.openxrProtocolVersion ?? 0,
+        openxrSubmittedFrameSequence: runtimeInfo.openxrSubmittedFrameSequence ?? 0,
+        openxrConsumedFrameSequence: runtimeInfo.openxrConsumedFrameSequence ?? 0,
         openvrSceneApplicationState: runtimeInfo.openvrSceneApplicationState ?? "",
         openvrSceneProcessId: runtimeInfo.openvrSceneProcessId ?? 0,
         openvrSceneApplicationKey: runtimeInfo.openvrSceneApplicationKey ?? "",
@@ -211,6 +214,7 @@ export class VrBridge {
     linuxOpenVRVisibleTexture = null;
     windowsReadbackInFlight = false;
     windowsReadbackPending = false;
+    windowsOpenXRTextures = [];
     linuxReadbackInFlight = false;
     linuxReadbackPending = false;
     invalidationTimer = null;
@@ -242,6 +246,9 @@ export class VrBridge {
             return;
         }
         this.linuxReadbackPending = false;
+        for (const retained of this.windowsOpenXRTextures)
+            releaseTexture(retained.texture);
+        this.windowsOpenXRTextures = [];
         const offscreenContents = this.attachedWindow.webContents;
         offscreenContents.removeListener("paint", this.onPaint);
         this.attachedWindow = null;
@@ -472,6 +479,19 @@ export class VrBridge {
             console.log(`VR overlay received first paint event (platform=${process.platform}, backend=${this.getSelectedBackend()}, hasTexture=${texture ? "yes" : "no"}, hasBitmap=${nativeImage ? "yes" : "no"}).`);
         }
         const runtimeInfo = this.getRuntimeInfo();
+        if (process.platform === "win32" && this.windowsOpenXRTextures.length > 0) {
+            const consumedSequence = runtimeInfo.openxrConsumedFrameSequence;
+            const pending = [];
+            for (const retained of this.windowsOpenXRTextures) {
+                if (retained.sequence <= consumedSequence) {
+                    releaseTexture(retained.texture);
+                }
+                else {
+                    pending.push(retained);
+                }
+            }
+            this.windowsOpenXRTextures = pending;
+        }
         if (process.platform === "linux" &&
             runtimeInfo.selectedBackend === "openvr" &&
             isTruthyEnvironmentVariable("ELECTRON_VR_OPENVR_VULKAN_SOFTWARE")) {
@@ -548,9 +568,22 @@ export class VrBridge {
                             this.useWindowsSoftwareFallback(nativeImage, "Windows shared texture submission failed; falling back to software RGBA upload.");
                         }
                     }
-                    else if (!this.loggedFirstWindowsSubmit) {
-                        this.loggedFirstWindowsSubmit = true;
-                        console.log("VR overlay submitted first Windows frame to the native bridge.");
+                    else {
+                        if (runtimeInfo.selectedBackend === "openxr" && runtimeInfo.openxrMode === "api-layer" &&
+                            runtimeInfo.openxrHostGraphicsApi === "d3d11") {
+                            const updatedRuntimeInfo = this.getRuntimeInfo();
+                            if (updatedRuntimeInfo.openxrSubmittedFrameSequence > runtimeInfo.openxrSubmittedFrameSequence) {
+                                this.windowsOpenXRTextures.push({
+                                    sequence: updatedRuntimeInfo.openxrSubmittedFrameSequence,
+                                    texture
+                                });
+                                releaseCurrentTexture = false;
+                            }
+                        }
+                        if (!this.loggedFirstWindowsSubmit) {
+                            this.loggedFirstWindowsSubmit = true;
+                            console.log("VR overlay submitted first Windows frame to the native bridge.");
+                        }
                     }
                 }
                 else if (this.getSelectedBackend() === "openvr") {

package/dist/compatibility.d.ts

@@ -4,7 +4,7 @@ export type VRReadiness = "ready" | "setup-required" | "waiting-for-host" | "fal
 export type VRLaunchVerdict = "works-now" | "action-required" | "incompatible";
 export type VRFeatureSupport = "supported" | "unsupported" | "runtime-dependent";
 export type VRIssueSeverity = "info" | "warning" | "error";
-export type VRSetupAction = "install-openxr-api-layer" | "enable-openxr-api-layer" | "restart-openxr-apps" | "start-openxr-app" | "install-xr-runtime" | "use-supported-openxr-host" | "none";
+export type VRSetupAction = "install-openxr-api-layer" | "reinstall-openxr-api-layer" | "enable-openxr-api-layer" | "restart-openxr-apps" | "start-openxr-app" | "install-xr-runtime" | "use-supported-openxr-host" | "none";
 export interface VRFeatureCompatibility {
     flatOverlay: VRFeatureSupport;
     curvature: VRFeatureSupport;

package/dist/compatibility.js

@@ -37,6 +37,7 @@ export function analyzeVRCompatibility(runtime, context = {}) {
         (context.architecture ?? process.arch) === "x64";
     const layerInstalled = apiLayer?.installed ?? runtime.openxrApiLayerInstalled;
     const layerEnabled = apiLayer?.enabled ?? runtime.openxrApiLayerEnabled;
+    const layerRequiresUpdate = apiLayer?.requiresUpdate ?? false;
     let readiness = "unavailable";
     let backendLabel = "No compatible VR backend";
     let summary = "No compatible XR runtime is ready.";
@@ -56,9 +57,15 @@ export function analyzeVRCompatibility(runtime, context = {}) {
         features = { ...realFeatures };
         compatibleHostGraphicsApis = runtime.platform === "win32" ? ["D3D11", "D3D12"] : ["Vulkan", "OpenGL Xlib/GLX"];
         backendLabel = "OpenXR application integration";
-        if (runtime.openxrCompanionConnected) {
+        if (layerRequiresUpdate) {
+            readiness = "setup-required";
+            summary = "OpenXR application integration must be updated before overlays can appear.";
+            recommendedAction = "reinstall-openxr-api-layer";
+            issues.push(issue("openxr-api-layer-update-required", "warning", "Update OpenXR integration", "Reinstall the per-user integration and restart OpenXR applications.", "reinstall-openxr-api-layer"));
+        }
+        else if (runtime.openxrCompanionConnected || runtime.openxrHostDetected) {
             readiness = "ready";
-            summary = `Connected to ${runtime.openxrHostApplicationName || "an OpenXR application"} using ${runtime.openxrHostGraphicsApi || "a supported graphics API"}.`;
+            summary = `${runtime.openxrCompanionConnected ? "Connected to" : "Detected"} ${runtime.openxrHostApplicationName || "an OpenXR application"} using ${runtime.openxrHostGraphicsApi || "a supported graphics API"}.`;
         }
         else if (!layerEnabled) {
             readiness = "setup-required";
@@ -185,7 +192,7 @@ export function analyzeVRCompatibility(runtime, context = {}) {
         canRenderOverlay,
         isRealVrBackend: runtime.selectedBackend === "openxr" || runtime.selectedBackend === "openvr",
         requiresApiLayer,
-        requiresOpenXRAppRestart: requiresApiLayer && (!runtime.openxrCompanionConnected || !layerEnabled),
+        requiresOpenXRAppRestart: requiresApiLayer && (!(runtime.openxrHostDetected || runtime.openxrCompanionConnected) || !layerEnabled),
         apiLayer,
         compatibleHostGraphicsApis,
         features,

package/dist/openxrApiLayer.d.ts

@@ -2,6 +2,7 @@ export interface OpenXRApiLayerStatus {
     installed: boolean;
     enabled: boolean;
     registered: boolean | null;
+    requiresUpdate: boolean;
     manifestPath: string;
     scope: string;
 }

package/dist/openxrApiLayer.js

@@ -84,6 +84,7 @@ export function parseOpenXRApiLayerStatus(output) {
         installed: values.get("installed") === "true",
         enabled: values.get("enabled") === "true",
         registered: values.has("registered") ? values.get("registered") === "true" : null,
+        requiresUpdate: values.get("requires_update") === "true",
         manifestPath: values.get("manifest") ?? "",
         scope: values.get("scope") ?? "current-user"
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@covas-labs/electron-vr",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Electron VR overlay bridge with OpenXR, OpenVR, and mock fallback backends.",
   "repository": {
     "type": "git",
@@ -22,8 +22,8 @@
     "electron": ">=37"
   },
   "optionalDependencies": {
-    "@covas-labs/electron-vr-prebuilt-linux-x64": "0.5.2",
-    "@covas-labs/electron-vr-prebuilt-win32-x64": "0.5.2"
+    "@covas-labs/electron-vr-prebuilt-linux-x64": "0.7.0",
+    "@covas-labs/electron-vr-prebuilt-win32-x64": "0.7.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",