@covas-labs/electron-vr 0.3.2 → 0.5.0

package/README.md

@@ -53,6 +53,7 @@ app.on("ready", async () => {
   overlay = await VROverlay.openWindow(window, {
     name: "Status_HUD",
     sizeMeters: 1,
+    curvature: 0,
     placement: {
       mode: "head",
       position: { x: 0, y: 0, z: -1.2 },
@@ -62,12 +63,50 @@ app.on("ready", async () => {
 });
 ```
 
-You can also reposition the overlay later with `overlay.setPlacement(...)`, toggle it with `overlay.setVisible(...)`, and resize it in meters with `overlay.setSizeMeters(...)`.
+You can also reposition the overlay later with `overlay.setPlacement(...)`, toggle it with `overlay.setVisible(...)`, resize it in meters with `overlay.setSizeMeters(...)`, and curve it with `overlay.setCurvature(...)`.
 
-`sizeMeters` must be greater than zero, and placement values should be finite numbers.
+`sizeMeters` must be greater than zero, `curvature` must be between `0` and `1`, and placement values should be finite numbers. `curvature: 0` keeps the overlay flat. Positive curvature uses OpenVR overlay curvature on OpenVR and `XR_KHR_composition_layer_cylinder` cylinder layers on OpenXR.
 
-On Linux, runtime selection prefers `openxr`, then falls back to `openvr`, then to `mock`. Linux OpenVR is treated as a best-effort alternate backend when a compatible OpenVR runtime is installed but the OpenXR overlay path is unavailable or disabled. It is not currently validated end to end on the main development machine or in CI.
+On Linux, runtime selection prefers `openxr`, then falls back to `openvr`, then to `mock`. Linux OpenVR automatically uses public `TextureType_Vulkan`, regardless of the game's graphics API, with bitmap-to-Vulkan fallback when direct DMA-BUF import is unavailable. `ELECTRON_VR_DISABLE_OPENVR_VULKAN=1` disables it; `ELECTRON_VR_OPENVR_GL_UPLOAD=1` explicitly selects the slower OpenGL diagnostic path.
 
-On Windows, runtime probing reports OpenXR overlay and D3D11 graphics-binding capability, but the default backend remains `openvr` during rollout. Set `ELECTRON_VR_ENABLE_OPENXR=1` to opt into the Windows OpenXR path when a compatible runtime exposes `XR_EXTX_overlay` and `XR_KHR_D3D11_enable`. This path is not currently validated end to end on the main development machine or in CI.
+When `XR_EXTX_overlay` is unavailable, Linux x64 can use the explicitly installed API layer before falling back to OpenVR:
 
-`getRuntimeInfo()` also includes `openvrRuntimeInstalled`, `openvrRuntimePath`, and platform-specific OpenXR capability details such as `openxrWindowsD3D11BindingAvailable`, so runtime diagnostics do not need to initialize OpenVR just to check availability. It now also surfaces live session/app details when the runtime exposes them, including `openxrSessionState`, `openxrSessionRunning`, and the current OpenVR scene app fields (`openvrSceneApplicationState`, `openvrSceneProcessId`, `openvrSceneApplicationKey`, `openvrSceneApplicationName`, `openvrSceneApplicationBinaryPath`). OpenXR does not expose a standard cross-runtime "current app" query, so those app-level fields are currently OpenVR-specific. `probeMode` includes the backend-selection decision as well, which makes fallback behavior easier to diagnose even when Linux OpenVR or Windows OpenXR cannot be validated on the current host.
+```bash
+npx electron-vr-openxr-layer install
+```
+
+The Linux layer supports Vulkan and desktop OpenGL Xlib sessions with one single-plane linear RGB DMA-BUF overlay. Vulkan DMA-BUF import is currently validated for Ubuntu 24.04 AMD RADV with Monado and `hello_xr -g Vulkan`; GLX retains its software snapshot fallback. Xcb, native Wayland host bindings, modifier-backed or multiplane buffers, and curvature are not yet supported.
+
+On Windows x64, selection prefers a direct `XR_EXTX_overlay` session, then an installed implicit API layer for D3D11 or D3D12 hosts, then OpenVR, then mock. API-layer installation is explicit:
+
+```powershell
+npx electron-vr-openxr-layer install
+npx electron-vr-openxr-layer status
+```
+
+Use the same command with `enable`, `disable`, or `uninstall`. `npm install` does not register the layer. `ELECTRON_VR_DISABLE_OPENXR_API_LAYER=1` disables it for a process. The API layer supports one flat quad for D3D11 and D3D12 hosts; elevated applications and positive curvature are not yet supported.
+
+Applications can manage the same per-user installation through the public API:
+
+```ts
+const installed = await VROverlay.installOpenXRApiLayer();
+console.log(installed.installed, installed.enabled, installed.manifestPath);
+
+const status = await VROverlay.getOpenXRApiLayerStatus();
+await VROverlay.disableOpenXRApiLayer();
+await VROverlay.enableOpenXRApiLayer();
+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.
+
+For product UI, prefer the combined readiness report instead of interpreting raw probe fields:
+
+```ts
+const report = await VROverlay.getCompatibilityReport();
+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.

package/dist/VROverlay.d.ts

@@ -1,6 +1,8 @@
 import { BrowserWindow } from "electron";
 import type { BrowserWindowConstructorOptions } from "electron";
 import { type BackendKind, type RuntimeInfo, type Quat, type Vec3 } from "./bridge.js";
+import { type OpenXRApiLayerStatus } from "./openxrApiLayer.js";
+import { type VRCompatibilityReport } from "./compatibility.js";
 type OverlayWindowOptions = Omit<BrowserWindowConstructorOptions, "width" | "height" | "webPreferences"> & {
     webPreferences?: BrowserWindowConstructorOptions["webPreferences"];
 };
@@ -12,6 +14,7 @@ export interface VROverlayOptions {
     frameRate?: number;
     windowOptions?: OverlayWindowOptions;
     sizeMeters?: number;
+    curvature?: number;
     visible?: boolean;
     placement?: {
         mode: "head" | "world";
@@ -23,6 +26,7 @@ export interface ExistingWindowVROverlayOptions {
     name?: string;
     frameRate?: number;
     sizeMeters?: number;
+    curvature?: number;
     visible?: boolean;
     placement?: VROverlayOptions["placement"];
 }
@@ -34,6 +38,7 @@ export declare class VROverlay {
     readonly frameRate: number;
     readonly windowOptions?: VROverlayOptions["windowOptions"];
     private sizeMeters;
+    private curvature;
     private visible;
     private placement;
     private readonly vrBridge;
@@ -44,6 +49,12 @@ export declare class VROverlay {
     static getRuntimeInfo(): RuntimeInfo;
     static isAvailable(runtimeInfo?: RuntimeInfo): boolean;
     static hasRealVRRuntime(runtimeInfo?: RuntimeInfo): boolean;
+    static getCompatibilityReport(): Promise<VRCompatibilityReport>;
+    static installOpenXRApiLayer(): Promise<OpenXRApiLayerStatus>;
+    static getOpenXRApiLayerStatus(): Promise<OpenXRApiLayerStatus>;
+    static enableOpenXRApiLayer(): Promise<OpenXRApiLayerStatus>;
+    static disableOpenXRApiLayer(): Promise<OpenXRApiLayerStatus>;
+    static uninstallOpenXRApiLayer(): Promise<OpenXRApiLayerStatus>;
     static openWindow(window: BrowserWindow, options?: ExistingWindowVROverlayOptions): Promise<VROverlay | null>;
     getRuntimeInfo(): RuntimeInfo;
     getSelectedBackend(): BackendKind;
@@ -54,6 +65,7 @@ export declare class VROverlay {
     setPlacement(placement: VROverlayOptions["placement"]): boolean;
     setVisible(visible: boolean): boolean;
     setSizeMeters(sizeMeters: number): boolean;
+    setCurvature(curvature: number): boolean;
     private initializeBridgeForWindow;
     private readonly onWindowClosed;
 }

package/dist/VROverlay.js

@@ -1,6 +1,8 @@
 import { app, BrowserWindow } from "electron";
 import { createVrBridge } from "./bridge.js";
-import { assertSizeMeters, normalizePlacement } from "./overlayOptions.js";
+import { disableOpenXRApiLayer, enableOpenXRApiLayer, getOpenXRApiLayerStatus, installOpenXRApiLayer, uninstallOpenXRApiLayer } from "./openxrApiLayer.js";
+import { assertCurvature, assertSizeMeters, normalizePlacement } from "./overlayOptions.js";
+import { getVRCompatibilityReport } from "./compatibility.js";
 function mergeWindowOptions(width, height, windowOptions) {
     const requestedOffscreen = windowOptions?.webPreferences?.offscreen;
     const normalizedOffscreen = typeof requestedOffscreen === "object"
@@ -35,6 +37,7 @@ export class VROverlay {
     frameRate;
     windowOptions;
     sizeMeters;
+    curvature;
     visible;
     placement;
     vrBridge = createVrBridge();
@@ -50,6 +53,8 @@ export class VROverlay {
         this.windowOptions = options.windowOptions;
         this.sizeMeters = options.sizeMeters ?? 1.0;
         assertSizeMeters(this.sizeMeters);
+        this.curvature = options.curvature ?? 0.0;
+        assertCurvature(this.curvature);
         this.visible = options.visible ?? true;
         this.placement = normalizePlacement(options.placement);
     }
@@ -62,6 +67,24 @@ export class VROverlay {
     static hasRealVRRuntime(runtimeInfo = VROverlay.getRuntimeInfo()) {
         return runtimeInfo.selectedBackend === "openxr" || runtimeInfo.selectedBackend === "openvr";
     }
+    static getCompatibilityReport() {
+        return getVRCompatibilityReport();
+    }
+    static installOpenXRApiLayer() {
+        return installOpenXRApiLayer();
+    }
+    static getOpenXRApiLayerStatus() {
+        return getOpenXRApiLayerStatus();
+    }
+    static enableOpenXRApiLayer() {
+        return enableOpenXRApiLayer();
+    }
+    static disableOpenXRApiLayer() {
+        return disableOpenXRApiLayer();
+    }
+    static uninstallOpenXRApiLayer() {
+        return uninstallOpenXRApiLayer();
+    }
     static async openWindow(window, options = {}) {
         const [width, height] = window.getContentSize();
         const overlay = new VROverlay({
@@ -70,6 +93,7 @@ export class VROverlay {
             height,
             frameRate: options.frameRate,
             sizeMeters: options.sizeMeters,
+            curvature: options.curvature,
             visible: options.visible,
             placement: options.placement
         });
@@ -174,12 +198,25 @@ export class VROverlay {
         }
         return success;
     }
+    setCurvature(curvature) {
+        assertCurvature(curvature);
+        this.curvature = curvature;
+        if (!this.isInitialized()) {
+            return true;
+        }
+        const success = this.vrBridge.setOverlayCurvature(curvature);
+        if (!success) {
+            console.error("Failed to update VR overlay curvature:", this.vrBridge.getLastError());
+        }
+        return success;
+    }
     initializeBridgeForWindow(window, width, height) {
         const initialized = this.vrBridge.initialize({
             name: this.overlayName,
             width,
             height,
             sizeMeters: this.sizeMeters,
+            curvature: this.curvature,
             visible: this.visible,
             placement: this.placement
         });

package/dist/bridge.d.ts

@@ -1,18 +1,32 @@
 import type { BrowserWindow } from "electron";
 export type BackendKind = "none" | "openxr" | "openvr" | "mock";
+export type OpenXRMode = "none" | "overlay-session" | "api-layer" | "standard-test-session";
 export interface RuntimeInfo {
     platform: string;
     probeMode: string;
     openxrAvailable: boolean;
     openxrOverlayExtensionAvailable: boolean;
     openxrLinuxEglBindingAvailable: boolean;
+    openxrLinuxOpenGlesBindingAvailable: boolean;
     openxrWindowsD3D11BindingAvailable: boolean;
+    openxrWindowsD3D12BindingAvailable: boolean;
+    openxrMacosMetalBindingAvailable: boolean;
     openxrRuntimeName: string;
     openxrRuntimeManifestPath: string;
     openxrRuntimeLibraryPath: string;
     openxrLoaderPath: string;
     openxrSessionState: string;
     openxrSessionRunning: boolean;
+    openxrMode: OpenXRMode;
+    openxrApiLayerInstalled: boolean;
+    openxrApiLayerEnabled: boolean;
+    openxrApiLayerManifestPath: string;
+    openxrCompanionConnected: boolean;
+    openxrHostProcessId: number;
+    openxrHostApplicationName: string;
+    openxrHostGraphicsApi: string;
+    openxrHostAdapterLuid: string;
+    openxrProtocolVersion: number;
     openvrAvailable: boolean;
     openvrRuntimeInstalled: boolean;
     openvrRuntimePath: string;
@@ -45,6 +59,7 @@ export interface InitializeVROptions {
     width: number;
     height: number;
     sizeMeters: number;
+    curvature?: number;
     visible: boolean;
     placement: OverlayPlacement;
 }
@@ -91,12 +106,20 @@ export declare class VrBridge {
     private warnedAboutMissingSharedTexture;
     private warnedAboutSoftwareFallback;
     private warnedAboutWindowsSoftwareFallback;
+    private warnedAboutEmptyLinuxBitmap;
     private loggedFirstPaint;
     private loggedFirstWindowsHandle;
     private loggedFirstWindowsSubmit;
     private loggedFirstWindowsSoftwareSubmit;
+    private loggedFirstLinuxOpenGLSubmit;
+    private loggedFirstLinuxOpenXRSoftwareSubmit;
+    private loggedFirstLinuxOpenVRVulkanSoftwareSubmit;
+    private linuxOpenVRVisibleTexture;
     private windowsReadbackInFlight;
     private windowsReadbackPending;
+    private linuxReadbackInFlight;
+    private linuxReadbackPending;
+    private invalidationTimer;
     attachWindow(window: BrowserWindow, options?: AttachWindowOptions): void;
     detachWindow(): void;
     getRuntimeInfo(): RuntimeInfo;
@@ -105,10 +128,15 @@ export declare class VrBridge {
     setOverlayPlacement(placement: OverlayPlacement): boolean;
     setOverlayVisible(visible: boolean): boolean;
     setOverlaySizeMeters(sizeMeters: number): boolean;
+    setOverlayCurvature(curvature: number): boolean;
     shutdown(): void;
     isInitialized(): boolean;
     getLastError(): string | null;
     private submitWindowsSoftwareFrame;
+    private submitLinuxBitmapFrame;
+    private submitLinuxOpenGLFrame;
+    private submitLinuxOpenXRSoftwareFrame;
+    private scheduleLinuxCaptureFallback;
     private useWindowsSoftwareFallback;
     private scheduleWindowsCaptureFallback;
     private readonly onPaint;

package/dist/bridge.js

@@ -110,6 +110,17 @@ function sanitizeRuntimeInfo(runtimeInfo) {
         ...runtimeInfo,
         openxrSessionState: runtimeInfo.openxrSessionState ?? "unknown",
         openxrSessionRunning: runtimeInfo.openxrSessionRunning ?? false,
+        openxrWindowsD3D12BindingAvailable: runtimeInfo.openxrWindowsD3D12BindingAvailable ?? false,
+        openxrMode: runtimeInfo.openxrMode ?? "none",
+        openxrApiLayerInstalled: runtimeInfo.openxrApiLayerInstalled ?? false,
+        openxrApiLayerEnabled: runtimeInfo.openxrApiLayerEnabled ?? false,
+        openxrApiLayerManifestPath: runtimeInfo.openxrApiLayerManifestPath ?? "",
+        openxrCompanionConnected: runtimeInfo.openxrCompanionConnected ?? false,
+        openxrHostProcessId: runtimeInfo.openxrHostProcessId ?? 0,
+        openxrHostApplicationName: runtimeInfo.openxrHostApplicationName ?? "",
+        openxrHostGraphicsApi: runtimeInfo.openxrHostGraphicsApi ?? "",
+        openxrHostAdapterLuid: runtimeInfo.openxrHostAdapterLuid ?? "",
+        openxrProtocolVersion: runtimeInfo.openxrProtocolVersion ?? 0,
         openvrSceneApplicationState: runtimeInfo.openvrSceneApplicationState ?? "",
         openvrSceneProcessId: runtimeInfo.openvrSceneProcessId ?? 0,
         openvrSceneApplicationKey: runtimeInfo.openvrSceneApplicationKey ?? "",
@@ -141,6 +152,25 @@ function bgraToRgba(source) {
     }
     return result;
 }
+function bgraToVerticallyFlippedRgba(source, width, height) {
+    const result = Buffer.allocUnsafe(source.length);
+    const rowBytes = width * 4;
+    for (let sourceRow = 0; sourceRow < height; sourceRow += 1) {
+        const sourceOffset = sourceRow * rowBytes;
+        const targetOffset = (height - sourceRow - 1) * rowBytes;
+        for (let columnOffset = 0; columnOffset < rowBytes; columnOffset += 4) {
+            result[targetOffset + columnOffset] = source[sourceOffset + columnOffset + 2];
+            result[targetOffset + columnOffset + 1] = source[sourceOffset + columnOffset + 1];
+            result[targetOffset + columnOffset + 2] = source[sourceOffset + columnOffset];
+            result[targetOffset + columnOffset + 3] = source[sourceOffset + columnOffset + 3];
+        }
+    }
+    return result;
+}
+function isTruthyEnvironmentVariable(name) {
+    const value = process.env[name]?.toLowerCase();
+    return value !== undefined && value !== "" && value !== "0" && value !== "false" && value !== "off";
+}
 function releaseTexture(texture) {
     if (texture && typeof texture.release === "function") {
         texture.release();
@@ -170,23 +200,48 @@ export class VrBridge {
     warnedAboutMissingSharedTexture = false;
     warnedAboutSoftwareFallback = false;
     warnedAboutWindowsSoftwareFallback = false;
+    warnedAboutEmptyLinuxBitmap = false;
     loggedFirstPaint = false;
     loggedFirstWindowsHandle = false;
     loggedFirstWindowsSubmit = false;
     loggedFirstWindowsSoftwareSubmit = false;
+    loggedFirstLinuxOpenGLSubmit = false;
+    loggedFirstLinuxOpenXRSoftwareSubmit = false;
+    loggedFirstLinuxOpenVRVulkanSoftwareSubmit = false;
+    linuxOpenVRVisibleTexture = null;
     windowsReadbackInFlight = false;
     windowsReadbackPending = false;
+    linuxReadbackInFlight = false;
+    linuxReadbackPending = false;
+    invalidationTimer = null;
     attachWindow(window, options = {}) {
         this.detachWindow();
         const offscreenContents = window.webContents;
-        offscreenContents.setFrameRate(options.frameRate ?? 60);
+        const frameRate = options.frameRate ?? 60;
+        offscreenContents.setFrameRate(frameRate);
         offscreenContents.on("paint", this.onPaint);
         this.attachedWindow = window;
+        if (this.getSelectedBackend() === "openxr" ||
+            (process.platform === "linux" &&
+                (isTruthyEnvironmentVariable("ELECTRON_VR_OPENVR_GL_UPLOAD") ||
+                    (this.getSelectedBackend() === "openvr" &&
+                        !isTruthyEnvironmentVariable("ELECTRON_VR_DISABLE_OPENVR_VULKAN"))))) {
+            this.invalidationTimer = setInterval(() => {
+                if (this.attachedWindow && !this.attachedWindow.isDestroyed()) {
+                    this.attachedWindow.webContents.invalidate();
+                }
+            }, 1000 / frameRate);
+        }
     }
     detachWindow() {
+        if (this.invalidationTimer) {
+            clearInterval(this.invalidationTimer);
+            this.invalidationTimer = null;
+        }
         if (!this.attachedWindow) {
             return;
         }
+        this.linuxReadbackPending = false;
         const offscreenContents = this.attachedWindow.webContents;
         offscreenContents.removeListener("paint", this.onPaint);
         this.attachedWindow = null;
@@ -198,7 +253,13 @@ export class VrBridge {
         return this.getRuntimeInfo().selectedBackend;
     }
     initialize(options) {
-        return this.addon.initializeVR(options);
+        try {
+            return this.addon.initializeVR(options);
+        }
+        finally {
+            releaseTexture(this.linuxOpenVRVisibleTexture);
+            this.linuxOpenVRVisibleTexture = null;
+        }
     }
     setOverlayPlacement(placement) {
         return this.addon.setOverlayPlacement(placement);
@@ -209,9 +270,18 @@ export class VrBridge {
     setOverlaySizeMeters(sizeMeters) {
         return this.addon.setOverlaySizeMeters(sizeMeters);
     }
+    setOverlayCurvature(curvature) {
+        return this.addon.setOverlayCurvature(curvature);
+    }
     shutdown() {
         this.detachWindow();
-        this.addon.shutdownVR();
+        try {
+            this.addon.shutdownVR();
+        }
+        finally {
+            releaseTexture(this.linuxOpenVRVisibleTexture);
+            this.linuxOpenVRVisibleTexture = null;
+        }
     }
     isInitialized() {
         return this.addon.isInitialized();
@@ -241,6 +311,118 @@ export class VrBridge {
         }
         return true;
     }
+    submitLinuxBitmapFrame(nativeImage, verticallyFlip, allowCaptureFallback = true) {
+        const openvrVulkanSoftware = !verticallyFlip && this.getSelectedBackend() === "openvr";
+        const transportName = verticallyFlip
+            ? "OpenVR OpenGL upload"
+            : openvrVulkanSoftware
+                ? "OpenVR Vulkan software upload"
+                : "OpenXR API-layer software transport";
+        if (!nativeImage) {
+            if (!this.warnedAboutMissingSharedTexture) {
+                this.warnedAboutMissingSharedTexture = true;
+                console.warn(`Linux ${transportName} requires Electron bitmap paint data.`);
+            }
+            if (allowCaptureFallback) {
+                this.scheduleLinuxCaptureFallback();
+            }
+            return false;
+        }
+        const { width, height } = nativeImage.getSize();
+        if (width === 0 || height === 0) {
+            if (!this.warnedAboutEmptyLinuxBitmap) {
+                this.warnedAboutEmptyLinuxBitmap = true;
+                console.warn(`Linux ${transportName} paint bitmap was empty (width=${width}, height=${height}); using capturePage readback.`);
+            }
+            if (allowCaptureFallback) {
+                this.scheduleLinuxCaptureFallback();
+            }
+            return false;
+        }
+        const bitmap = nativeImage.toBitmap();
+        if (bitmap.length === 0) {
+            if (!this.warnedAboutEmptyLinuxBitmap) {
+                this.warnedAboutEmptyLinuxBitmap = true;
+                console.warn(`Linux ${transportName} paint bitmap contained no pixels; using capturePage readback.`);
+            }
+            if (allowCaptureFallback) {
+                this.scheduleLinuxCaptureFallback();
+            }
+            return false;
+        }
+        const submitted = this.addon.submitSoftwareFrame({
+            width,
+            height,
+            rgbaPixels: verticallyFlip ? bgraToVerticallyFlippedRgba(bitmap, width, height) : bgraToRgba(bitmap)
+        });
+        if (!submitted) {
+            console.error("Failed to submit Linux frame to VR bridge:", this.addon.getLastError());
+            return false;
+        }
+        if (verticallyFlip && !this.loggedFirstLinuxOpenGLSubmit) {
+            this.loggedFirstLinuxOpenGLSubmit = true;
+            console.log("VR overlay submitted first Linux frame through OpenGL upload.");
+        }
+        else if (openvrVulkanSoftware && !this.loggedFirstLinuxOpenVRVulkanSoftwareSubmit) {
+            this.loggedFirstLinuxOpenVRVulkanSoftwareSubmit = true;
+            console.log("VR overlay submitted first Linux frame through OpenVR Vulkan software upload.");
+        }
+        else if (!openvrVulkanSoftware && !verticallyFlip && !this.loggedFirstLinuxOpenXRSoftwareSubmit) {
+            this.loggedFirstLinuxOpenXRSoftwareSubmit = true;
+            console.log("VR overlay submitted first Linux frame through OpenXR API-layer software transport.");
+        }
+        return true;
+    }
+    submitLinuxOpenGLFrame(nativeImage, allowCaptureFallback = true) {
+        return this.submitLinuxBitmapFrame(nativeImage, true, allowCaptureFallback);
+    }
+    submitLinuxOpenXRSoftwareFrame(nativeImage, allowCaptureFallback = true) {
+        return this.submitLinuxBitmapFrame(nativeImage, false, allowCaptureFallback);
+    }
+    scheduleLinuxCaptureFallback() {
+        if (!this.attachedWindow) {
+            return;
+        }
+        if (this.linuxReadbackInFlight) {
+            this.linuxReadbackPending = true;
+            return;
+        }
+        this.linuxReadbackInFlight = true;
+        const window = this.attachedWindow;
+        const offscreenContents = window.webContents;
+        const [width, height] = window.getContentSize();
+        void offscreenContents.capturePage({ x: 0, y: 0, width, height })
+            .then((image) => {
+            if (this.attachedWindow !== window || !this.isInitialized()) {
+                return;
+            }
+            const runtimeInfo = this.getRuntimeInfo();
+            if (runtimeInfo.selectedBackend === "openxr" && runtimeInfo.openxrMode === "api-layer") {
+                if (runtimeInfo.openxrCompanionConnected && runtimeInfo.openxrHostGraphicsApi === "opengl-xlib") {
+                    this.submitLinuxOpenXRSoftwareFrame(image, false);
+                }
+                return;
+            }
+            if (runtimeInfo.selectedBackend === "openvr" &&
+                !isTruthyEnvironmentVariable("ELECTRON_VR_DISABLE_OPENVR_VULKAN") &&
+                !isTruthyEnvironmentVariable("ELECTRON_VR_OPENVR_GL_UPLOAD")) {
+                this.submitLinuxBitmapFrame(image, false, false);
+            }
+            else {
+                this.submitLinuxOpenGLFrame(image, false);
+            }
+        })
+            .catch((error) => {
+            console.error("Failed to capture Linux OpenGL upload frame:", error);
+        })
+            .finally(() => {
+            this.linuxReadbackInFlight = false;
+            if (this.linuxReadbackPending) {
+                this.linuxReadbackPending = false;
+                this.scheduleLinuxCaptureFallback();
+            }
+        });
+    }
     useWindowsSoftwareFallback(nativeImage, warning) {
         if (!this.warnedAboutWindowsSoftwareFallback) {
             this.warnedAboutWindowsSoftwareFallback = true;
@@ -289,7 +471,43 @@ export class VrBridge {
             this.loggedFirstPaint = true;
             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 === "linux" &&
+            runtimeInfo.selectedBackend === "openvr" &&
+            isTruthyEnvironmentVariable("ELECTRON_VR_OPENVR_VULKAN_SOFTWARE")) {
+            try {
+                this.submitLinuxBitmapFrame(nativeImage, false);
+            }
+            finally {
+                releaseTexture(texture);
+            }
+            return;
+        }
+        if (process.platform === "linux" &&
+            runtimeInfo.selectedBackend === "openxr" &&
+            runtimeInfo.openxrMode === "api-layer" &&
+            (!runtimeInfo.openxrCompanionConnected || runtimeInfo.openxrHostGraphicsApi === "opengl-xlib")) {
+            try {
+                if (runtimeInfo.openxrCompanionConnected) {
+                    this.submitLinuxOpenXRSoftwareFrame(nativeImage);
+                }
+            }
+            finally {
+                releaseTexture(texture);
+            }
+            return;
+        }
         if (!texture) {
+            if (process.platform === "linux" &&
+                this.getSelectedBackend() === "openvr") {
+                if (isTruthyEnvironmentVariable("ELECTRON_VR_OPENVR_GL_UPLOAD")) {
+                    this.submitLinuxOpenGLFrame(nativeImage);
+                }
+                else if (!isTruthyEnvironmentVariable("ELECTRON_VR_DISABLE_OPENVR_VULKAN")) {
+                    this.submitLinuxBitmapFrame(nativeImage, false);
+                }
+                return;
+            }
             if (process.platform === "win32" && this.getSelectedBackend() === "openvr") {
                 this.useWindowsSoftwareFallback(nativeImage, "Windows shared texture payload was unavailable; falling back to software RGBA upload.");
                 return;
@@ -313,6 +531,7 @@ export class VrBridge {
             }
             return;
         }
+        let releaseCurrentTexture = true;
         try {
             const textureInfo = texture.textureInfo;
             const handle = textureInfo?.sharedTextureHandle;
@@ -344,24 +563,54 @@ export class VrBridge {
                 return;
             }
             if (process.platform === "linux") {
-                if (textureInfo?.planes?.length) {
+                if (this.getSelectedBackend() === "openvr" &&
+                    isTruthyEnvironmentVariable("ELECTRON_VR_OPENVR_GL_UPLOAD")) {
+                    this.submitLinuxOpenGLFrame(nativeImage);
+                }
+                else if (textureInfo?.planes?.length) {
                     const textureInfoSnapshot = cloneLinuxTextureInfo(textureInfo);
                     const submitted = this.addon.submitSharedTexture(textureInfoSnapshot);
                     if (!submitted) {
                         console.error("Failed to submit Linux frame to VR bridge:", this.addon.getLastError());
+                        if (this.getSelectedBackend() === "openvr" &&
+                            !isTruthyEnvironmentVariable("ELECTRON_VR_DISABLE_OPENVR_VULKAN")) {
+                            this.submitLinuxBitmapFrame(nativeImage, false);
+                        }
+                    }
+                    else if (this.getSelectedBackend() === "openvr" &&
+                        isTruthyEnvironmentVariable("ELECTRON_VR_DISABLE_OPENVR_VULKAN")) {
+                        const previousTexture = this.linuxOpenVRVisibleTexture;
+                        this.linuxOpenVRVisibleTexture = texture;
+                        releaseCurrentTexture = false;
+                        releaseTexture(previousTexture);
                     }
                 }
                 else if (!this.warnedAboutMissingSharedTexture) {
                     this.warnedAboutMissingSharedTexture = true;
                     console.warn("Shared texture metadata was unavailable on paint; preview submission was skipped.");
                 }
+                return;
+            }
+            if (process.platform === "darwin") {
+                if (Buffer.isBuffer(handle) && textureInfo?.codedSize) {
+                    const submitted = this.addon.submitSharedTexture(textureInfo);
+                    if (!submitted) {
+                        console.error("Failed to submit macOS frame to VR bridge:", this.addon.getLastError());
+                    }
+                }
+                else if (!this.warnedAboutMissingSharedTexture) {
+                    this.warnedAboutMissingSharedTexture = true;
+                    console.warn("IOSurface metadata was unavailable on paint; OpenXR submission was skipped.");
+                }
             }
         }
         catch (error) {
             console.error("Error while forwarding frame to VR bridge:", error);
         }
         finally {
-            releaseTexture(texture);
+            if (releaseCurrentTexture) {
+                releaseTexture(texture);
+            }
         }
     };
 }

package/dist/compatibility.d.ts

@@ -0,0 +1,56 @@
+import { type BackendKind, type OpenXRMode, type RuntimeInfo } from "./bridge.js";
+import { type OpenXRApiLayerStatus } from "./openxrApiLayer.js";
+export type VRReadiness = "ready" | "setup-required" | "waiting-for-host" | "fallback-only" | "unavailable" | "development-only";
+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 interface VRFeatureCompatibility {
+    flatOverlay: VRFeatureSupport;
+    curvature: VRFeatureSupport;
+    headLockedPlacement: VRFeatureSupport;
+    worldLockedPlacement: VRFeatureSupport;
+    alphaTransparency: VRFeatureSupport;
+    multipleOverlays: VRFeatureSupport;
+    softwareFrameFallback: VRFeatureSupport;
+}
+export interface VRCompatibilityIssue {
+    code: string;
+    severity: VRIssueSeverity;
+    title: string;
+    message: string;
+    action: VRSetupAction;
+    diagnosticDetails?: string;
+}
+export interface VRLaunchAssessment {
+    verdict: VRLaunchVerdict;
+    wouldWorkNow: boolean;
+    fundamentalIncompatibility: boolean;
+    message: string;
+    requiredActions: VRSetupAction[];
+}
+export interface VRCompatibilityReport {
+    readiness: VRReadiness;
+    backend: BackendKind;
+    openxrMode: OpenXRMode;
+    backendLabel: string;
+    summary: string;
+    launch: VRLaunchAssessment;
+    canRenderOverlay: boolean;
+    isRealVrBackend: boolean;
+    requiresApiLayer: boolean;
+    requiresOpenXRAppRestart: boolean;
+    apiLayer: OpenXRApiLayerStatus | null;
+    compatibleHostGraphicsApis: string[];
+    features: VRFeatureCompatibility;
+    issues: VRCompatibilityIssue[];
+    recommendedAction: VRSetupAction;
+    diagnostics: RuntimeInfo;
+}
+export interface VRCompatibilityContext {
+    architecture?: string;
+    apiLayer?: OpenXRApiLayerStatus | null;
+    apiLayerStatusError?: string;
+}
+export declare function analyzeVRCompatibility(runtime: RuntimeInfo, context?: VRCompatibilityContext): VRCompatibilityReport;
+export declare function getVRCompatibilityReport(): Promise<VRCompatibilityReport>;

package/dist/compatibility.js

@@ -0,0 +1,210 @@
+import { createVrBridge } from "./bridge.js";
+import { getOpenXRApiLayerStatus } from "./openxrApiLayer.js";
+const realFeatures = {
+    flatOverlay: "supported",
+    curvature: "unsupported",
+    headLockedPlacement: "supported",
+    worldLockedPlacement: "supported",
+    alphaTransparency: "supported",
+    multipleOverlays: "unsupported",
+    softwareFrameFallback: "unsupported"
+};
+function issue(code, severity, title, message, action = "none", diagnosticDetails) {
+    return { code, severity, title, message, action, ...(diagnosticDetails ? { diagnosticDetails } : {}) };
+}
+function directOpenXRFeatures() {
+    return { ...realFeatures, curvature: "runtime-dependent" };
+}
+function openVRFeatures() {
+    return { ...realFeatures, curvature: "supported", softwareFrameFallback: "supported" };
+}
+function unavailableFeatures(platform, backend) {
+    const linuxMock = platform === "linux" && backend === "mock";
+    return {
+        flatOverlay: linuxMock ? "supported" : "unsupported",
+        curvature: "unsupported",
+        headLockedPlacement: "unsupported",
+        worldLockedPlacement: "unsupported",
+        alphaTransparency: linuxMock ? "supported" : "unsupported",
+        multipleOverlays: "unsupported",
+        softwareFrameFallback: linuxMock ? "supported" : "unsupported"
+    };
+}
+export function analyzeVRCompatibility(runtime, context = {}) {
+    const { apiLayer = null, apiLayerStatusError } = context;
+    const issues = [];
+    const platformSupportsLayer = (runtime.platform === "win32" || runtime.platform === "linux") &&
+        (context.architecture ?? process.arch) === "x64";
+    const layerInstalled = apiLayer?.installed ?? runtime.openxrApiLayerInstalled;
+    const layerEnabled = apiLayer?.enabled ?? runtime.openxrApiLayerEnabled;
+    let readiness = "unavailable";
+    let backendLabel = "No compatible VR backend";
+    let summary = "No compatible XR runtime is ready.";
+    let features = unavailableFeatures(runtime.platform, runtime.selectedBackend);
+    let compatibleHostGraphicsApis = [];
+    let requiresApiLayer = false;
+    let recommendedAction = "none";
+    if (runtime.selectedBackend === "openxr" && runtime.openxrMode === "overlay-session") {
+        readiness = "ready";
+        backendLabel = "OpenXR direct overlay";
+        summary = "The active OpenXR runtime supports a direct overlay session.";
+        features = directOpenXRFeatures();
+        compatibleHostGraphicsApis = runtime.platform === "win32" ? ["D3D11"] : ["EGL/OpenGL ES"];
+    }
+    else if (runtime.selectedBackend === "openxr" && runtime.openxrMode === "api-layer") {
+        requiresApiLayer = true;
+        features = { ...realFeatures };
+        compatibleHostGraphicsApis = runtime.platform === "win32" ? ["D3D11", "D3D12"] : ["Vulkan", "OpenGL Xlib/GLX"];
+        backendLabel = "OpenXR application integration";
+        if (runtime.openxrCompanionConnected) {
+            readiness = "ready";
+            summary = `Connected to ${runtime.openxrHostApplicationName || "an OpenXR application"} using ${runtime.openxrHostGraphicsApi || "a supported graphics API"}.`;
+        }
+        else if (!layerEnabled) {
+            readiness = "setup-required";
+            summary = "OpenXR application integration is installed but disabled.";
+            recommendedAction = "enable-openxr-api-layer";
+            issues.push(issue("openxr-api-layer-disabled", "warning", "OpenXR integration is disabled", "Enable the per-user integration and restart OpenXR applications.", "enable-openxr-api-layer"));
+        }
+        else {
+            readiness = "waiting-for-host";
+            summary = "OpenXR integration is ready. Start or restart a compatible OpenXR application.";
+            recommendedAction = "start-openxr-app";
+            issues.push(issue("openxr-host-not-connected", "info", "Waiting for a VR application", `Start a compatible ${compatibleHostGraphicsApis.join(" or ")} OpenXR application. If it was already running when integration was enabled, restart it.`, "start-openxr-app"));
+        }
+    }
+    else if (runtime.selectedBackend === "openxr" && runtime.openxrMode === "standard-test-session") {
+        readiness = "development-only";
+        backendLabel = "OpenXR test session";
+        summary = "OpenXR is available as a development test session, not as a production coexistence overlay.";
+        features = directOpenXRFeatures();
+        issues.push(issue("openxr-test-session-only", "warning", "Development mode only", "This session cannot place the overlay above an unrelated OpenXR application."));
+    }
+    else if (runtime.selectedBackend === "openvr") {
+        readiness = "ready";
+        backendLabel = "SteamVR/OpenVR overlay";
+        summary = "A registered OpenVR runtime is ready for native overlays.";
+        features = openVRFeatures();
+        compatibleHostGraphicsApis = runtime.platform === "win32" ? ["SteamVR/OpenVR"] : ["SteamVR/OpenVR with single-plane RGB DMA-BUF"];
+        if (runtime.openxrAvailable && platformSupportsLayer && !layerInstalled) {
+            issues.push(issue("openxr-api-layer-optional", "info", "OpenXR application support is optional", "SteamVR overlays are ready. Install OpenXR application integration only if overlays are also needed in OpenXR applications without native overlay support.", "install-openxr-api-layer"));
+        }
+    }
+    else {
+        const canInstallLayer = platformSupportsLayer && runtime.openxrAvailable &&
+            (runtime.platform === "linux" || runtime.openxrWindowsD3D11BindingAvailable || runtime.openxrWindowsD3D12BindingAvailable);
+        if (canInstallLayer && !layerInstalled) {
+            readiness = "setup-required";
+            backendLabel = "Desktop preview";
+            summary = "OpenXR is installed, but application integration must be enabled before overlays can appear in compatible OpenXR applications.";
+            requiresApiLayer = true;
+            recommendedAction = "install-openxr-api-layer";
+            compatibleHostGraphicsApis = runtime.platform === "win32" ? ["D3D11", "D3D12"] : ["Vulkan", "OpenGL Xlib/GLX"];
+            issues.push(issue("openxr-api-layer-not-installed", "warning", "Enable OpenXR application integration", "Install the per-user integration after asking for permission. Restart OpenXR applications afterward.", "install-openxr-api-layer"));
+        }
+        else if (canInstallLayer && !layerEnabled) {
+            readiness = "setup-required";
+            backendLabel = "Desktop preview";
+            summary = "OpenXR application integration is installed but disabled.";
+            requiresApiLayer = true;
+            recommendedAction = "enable-openxr-api-layer";
+            compatibleHostGraphicsApis = runtime.platform === "win32" ? ["D3D11", "D3D12"] : ["Vulkan", "OpenGL Xlib/GLX"];
+            issues.push(issue("openxr-api-layer-disabled", "warning", "OpenXR integration is disabled", "Enable the per-user integration and restart OpenXR applications.", "enable-openxr-api-layer"));
+        }
+        else if (runtime.selectedBackend === "mock") {
+            readiness = "fallback-only";
+            backendLabel = runtime.platform === "linux" ? "Desktop preview" : "No visible VR output";
+            summary = runtime.platform === "linux"
+                ? "No real XR backend is ready. The overlay can only be previewed on the desktop."
+                : "No real XR backend or visible desktop preview is available.";
+            issues.push(issue("no-real-xr-backend", "error", "No compatible VR runtime", "Install and configure a supported OpenXR or SteamVR runtime, then check again.", "install-xr-runtime"));
+            recommendedAction = "install-xr-runtime";
+        }
+    }
+    if (apiLayerStatusError) {
+        issues.push(issue("openxr-api-layer-status-unavailable", "warning", "Could not inspect OpenXR integration", "OpenXR integration status could not be checked. Retry the check or repair the application installation.", "none", apiLayerStatusError));
+    }
+    const canRenderOverlay = readiness === "ready" || readiness === "waiting-for-host" ||
+        (readiness === "fallback-only" && runtime.platform === "linux" && runtime.selectedBackend === "mock");
+    let launch;
+    if (readiness === "ready" && (runtime.selectedBackend === "openxr" || runtime.selectedBackend === "openvr")) {
+        launch = {
+            verdict: "works-now",
+            wouldWorkNow: true,
+            fundamentalIncompatibility: false,
+            message: "Launching the browser overlay now is expected to produce real VR output.",
+            requiredActions: []
+        };
+    }
+    else if (readiness === "setup-required") {
+        const actions = recommendedAction === "none" ? [] : [recommendedAction];
+        if (requiresApiLayer)
+            actions.push("restart-openxr-apps");
+        launch = {
+            verdict: "action-required",
+            wouldWorkNow: false,
+            fundamentalIncompatibility: false,
+            message: "The overlay is compatible, but setup must be completed before launching it.",
+            requiredActions: actions
+        };
+    }
+    else if (readiness === "waiting-for-host") {
+        launch = {
+            verdict: "action-required",
+            wouldWorkNow: false,
+            fundamentalIncompatibility: false,
+            message: `The overlay is ready, but real VR output requires a compatible ${compatibleHostGraphicsApis.join(" or ")} OpenXR application to be started or restarted.`,
+            requiredActions: ["start-openxr-app"]
+        };
+    }
+    else if ((readiness === "fallback-only" || readiness === "unavailable") && platformSupportsLayer) {
+        launch = {
+            verdict: "action-required",
+            wouldWorkNow: false,
+            fundamentalIncompatibility: false,
+            message: "Launching now would not produce real VR output. Install and configure a supported OpenXR or SteamVR runtime first.",
+            requiredActions: ["install-xr-runtime"]
+        };
+    }
+    else {
+        launch = {
+            verdict: "incompatible",
+            wouldWorkNow: false,
+            fundamentalIncompatibility: true,
+            message: "This platform or execution mode cannot provide a production VR overlay with the current implementation.",
+            requiredActions: []
+        };
+    }
+    return {
+        readiness,
+        backend: runtime.selectedBackend,
+        openxrMode: runtime.openxrMode,
+        backendLabel,
+        summary,
+        launch,
+        canRenderOverlay,
+        isRealVrBackend: runtime.selectedBackend === "openxr" || runtime.selectedBackend === "openvr",
+        requiresApiLayer,
+        requiresOpenXRAppRestart: requiresApiLayer && (!runtime.openxrCompanionConnected || !layerEnabled),
+        apiLayer,
+        compatibleHostGraphicsApis,
+        features,
+        issues,
+        recommendedAction,
+        diagnostics: runtime
+    };
+}
+export async function getVRCompatibilityReport() {
+    const runtime = createVrBridge().getRuntimeInfo();
+    if ((runtime.platform !== "win32" && runtime.platform !== "linux") || process.arch !== "x64") {
+        return analyzeVRCompatibility(runtime);
+    }
+    try {
+        return analyzeVRCompatibility(runtime, { apiLayer: await getOpenXRApiLayerStatus() });
+    }
+    catch (error) {
+        return analyzeVRCompatibility(runtime, {
+            apiLayerStatusError: error instanceof Error ? error.message : String(error)
+        });
+    }
+}

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 export { VrBridge, createVrBridge, type AttachWindowOptions, type BackendKind, type InitializeVROptions, type OverlayPlacement, type Quat, type RuntimeInfo, type Vec3 } from "./bridge.js";
+export { analyzeVRCompatibility, getVRCompatibilityReport, type VRCompatibilityIssue, type VRCompatibilityContext, type VRCompatibilityReport, type VRFeatureCompatibility, type VRFeatureSupport, type VRLaunchAssessment, type VRLaunchVerdict, type VRIssueSeverity, type VRReadiness, type VRSetupAction } from "./compatibility.js";
+export { disableOpenXRApiLayer, enableOpenXRApiLayer, getOpenXRApiLayerStatus, installOpenXRApiLayer, uninstallOpenXRApiLayer, type OpenXRApiLayerStatus } from "./openxrApiLayer.js";
 export { VROverlay, type ExistingWindowVROverlayOptions, type VROverlayOptions } from "./VROverlay.js";

package/dist/index.js

@@ -1,2 +1,4 @@
 export { VrBridge, createVrBridge } from "./bridge.js";
+export { analyzeVRCompatibility, getVRCompatibilityReport } from "./compatibility.js";
+export { disableOpenXRApiLayer, enableOpenXRApiLayer, getOpenXRApiLayerStatus, installOpenXRApiLayer, uninstallOpenXRApiLayer } from "./openxrApiLayer.js";
 export { VROverlay } from "./VROverlay.js";

package/dist/openxrApiLayer.d.ts

@@ -0,0 +1,13 @@
+export interface OpenXRApiLayerStatus {
+    installed: boolean;
+    enabled: boolean;
+    registered: boolean | null;
+    manifestPath: string;
+    scope: string;
+}
+export declare function parseOpenXRApiLayerStatus(output: string): OpenXRApiLayerStatus;
+export declare function getOpenXRApiLayerStatus(): Promise<OpenXRApiLayerStatus>;
+export declare function installOpenXRApiLayer(): Promise<OpenXRApiLayerStatus>;
+export declare function enableOpenXRApiLayer(): Promise<OpenXRApiLayerStatus>;
+export declare function disableOpenXRApiLayer(): Promise<OpenXRApiLayerStatus>;
+export declare function uninstallOpenXRApiLayer(): Promise<OpenXRApiLayerStatus>;

package/dist/openxrApiLayer.js

@@ -0,0 +1,109 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const PREBUILT_PACKAGES = {
+    linux: "@covas-labs/electron-vr-prebuilt-linux-x64",
+    win32: "@covas-labs/electron-vr-prebuilt-win32-x64"
+};
+function assertSupportedPlatform() {
+    if ((process.platform !== "linux" && process.platform !== "win32") || process.arch !== "x64") {
+        throw new Error(`OpenXR API-layer management is not supported on ${process.platform}-${process.arch}.`);
+    }
+}
+function resolvePrebuiltCli() {
+    const packageName = PREBUILT_PACKAGES[process.platform];
+    if (!packageName)
+        return null;
+    const requires = [
+        createRequire(import.meta.url),
+        createRequire(resolve(process.cwd(), "package.json"))
+    ];
+    for (const require of requires) {
+        try {
+            const packageEntry = require.resolve(packageName);
+            const cli = resolve(dirname(packageEntry), "openxr-layer-cli.js");
+            if (existsSync(cli))
+                return cli;
+        }
+        catch {
+            // Try the next package resolution context.
+        }
+    }
+    return null;
+}
+function resolveCli() {
+    assertSupportedPlatform();
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    const repositoryCli = resolve(currentDir, "..", "..", "..", "tools", "openxr-layer-cli.mjs");
+    if (existsSync(repositoryCli))
+        return repositoryCli;
+    const prebuiltCli = resolvePrebuiltCli();
+    if (prebuiltCli)
+        return prebuiltCli;
+    throw new Error("The OpenXR API-layer utility is unavailable. Rebuild the repository native addon or install the platform prebuilt package.");
+}
+function runCommand(command) {
+    const cli = resolveCli();
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn(process.execPath, [cli, command], {
+            env: {
+                ...process.env,
+                ELECTRON_RUN_AS_NODE: "1"
+            },
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        child.once("error", reject);
+        child.once("close", (code, signal) => {
+            if (code === 0) {
+                resolvePromise(stdout);
+                return;
+            }
+            const details = [stdout.trim(), stderr.trim()].filter(Boolean).join("\n");
+            reject(new Error(`OpenXR API-layer ${command} failed with ${signal ? `signal ${signal}` : `exit code ${code ?? "unknown"}`}${details ? `:\n${details}` : "."}`));
+        });
+    });
+}
+export function parseOpenXRApiLayerStatus(output) {
+    const values = new Map();
+    for (const line of output.split(/\r?\n/)) {
+        const separator = line.indexOf("=");
+        if (separator > 0)
+            values.set(line.slice(0, separator).trim(), line.slice(separator + 1).trim());
+    }
+    return {
+        installed: values.get("installed") === "true",
+        enabled: values.get("enabled") === "true",
+        registered: values.has("registered") ? values.get("registered") === "true" : null,
+        manifestPath: values.get("manifest") ?? "",
+        scope: values.get("scope") ?? "current-user"
+    };
+}
+export async function getOpenXRApiLayerStatus() {
+    return parseOpenXRApiLayerStatus(await runCommand("status"));
+}
+async function runLifecycleCommand(command) {
+    await runCommand(command);
+    return getOpenXRApiLayerStatus();
+}
+export function installOpenXRApiLayer() {
+    return runLifecycleCommand("install");
+}
+export function enableOpenXRApiLayer() {
+    return runLifecycleCommand("enable");
+}
+export function disableOpenXRApiLayer() {
+    return runLifecycleCommand("disable");
+}
+export function uninstallOpenXRApiLayer() {
+    return runLifecycleCommand("uninstall");
+}

package/dist/overlayOptions.d.ts

@@ -8,4 +8,5 @@ export declare function isFiniteNumber(value: number): boolean;
 export declare function assertVec3(value: Vec3, context: string): void;
 export declare function assertQuat(value: Quat, context: string): void;
 export declare function assertSizeMeters(sizeMeters: number): void;
+export declare function assertCurvature(curvature: number): void;
 export declare function normalizePlacement(placement?: OverlayPlacementInput): OverlayPlacement;

package/dist/overlayOptions.js

@@ -16,6 +16,11 @@ export function assertSizeMeters(sizeMeters) {
         throw new RangeError("sizeMeters must be a finite number greater than zero.");
     }
 }
+export function assertCurvature(curvature) {
+    if (!isFiniteNumber(curvature) || curvature < 0 || curvature > 1) {
+        throw new RangeError("curvature must be a finite number between 0 and 1.");
+    }
+}
 export function normalizePlacement(placement) {
     const mode = placement?.mode ?? "head";
     if (mode !== "head" && mode !== "world") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@covas-labs/electron-vr",
-  "version": "0.3.2",
+  "version": "0.5.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.3.2",
-    "@covas-labs/electron-vr-prebuilt-win32-x64": "0.3.2"
+    "@covas-labs/electron-vr-prebuilt-linux-x64": "0.5.0",
+    "@covas-labs/electron-vr-prebuilt-win32-x64": "0.5.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",