@covas-labs/electron-vr 0.0.0-bootstrap.0 → 0.3.2

package/README.md

@@ -1,3 +1,73 @@
 # @covas-labs/electron-vr
 
-Bootstrap placeholder package for npm trusted publishing setup.
+Electron-facing VR overlay bridge package for OpenXR or OpenVR overlays, with native mock preview fallback when no real XR runtime is usable.
+
+Published Windows and Linux packages bundle the OpenVR runtime library they need, so consumers do not need to configure `OPENVR_SDK_DIR` for normal usage.
+
+## Install
+
+This package is published on GitHub Packages.
+
+```ini
+@covas-labs:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
+```
+
+```bash
+npm install @covas-labs/electron-vr
+```
+
+## Example
+
+```ts
+import { app, BrowserWindow } from "electron";
+import { VROverlay } from "@covas-labs/electron-vr";
+
+let overlay: VROverlay | null = null;
+
+app.on("ready", async () => {
+  const runtimeInfo = VROverlay.getRuntimeInfo();
+  if (!VROverlay.isAvailable(runtimeInfo)) {
+    return;
+  }
+
+  const window = new BrowserWindow({
+    width: 1280,
+    height: 720,
+    show: false,
+    frame: false,
+    transparent: true,
+    backgroundColor: "#00000000",
+    webPreferences: {
+      offscreen: {
+        useSharedTexture: true
+      },
+      contextIsolation: true,
+      nodeIntegration: false,
+      backgroundThrottling: false
+    }
+  });
+
+  await window.loadURL("file:///absolute/path/to/overlay.html");
+
+  overlay = await VROverlay.openWindow(window, {
+    name: "Status_HUD",
+    sizeMeters: 1,
+    placement: {
+      mode: "head",
+      position: { x: 0, y: 0, z: -1.2 },
+      rotation: { x: 0, y: 0, z: 0, w: 1 }
+    }
+  });
+});
+```
+
+You can also reposition the overlay later with `overlay.setPlacement(...)`, toggle it with `overlay.setVisible(...)`, and resize it in meters with `overlay.setSizeMeters(...)`.
+
+`sizeMeters` must be greater than zero, and placement values should be finite numbers.
+
+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 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.
+
+`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.

package/dist/VROverlay.d.ts

@@ -0,0 +1,60 @@
+import { BrowserWindow } from "electron";
+import type { BrowserWindowConstructorOptions } from "electron";
+import { type BackendKind, type RuntimeInfo, type Quat, type Vec3 } from "./bridge.js";
+type OverlayWindowOptions = Omit<BrowserWindowConstructorOptions, "width" | "height" | "webPreferences"> & {
+    webPreferences?: BrowserWindowConstructorOptions["webPreferences"];
+};
+export interface VROverlayOptions {
+    name?: string;
+    width?: number;
+    height?: number;
+    url?: string;
+    frameRate?: number;
+    windowOptions?: OverlayWindowOptions;
+    sizeMeters?: number;
+    visible?: boolean;
+    placement?: {
+        mode: "head" | "world";
+        position?: Vec3;
+        rotation?: Quat;
+    };
+}
+export interface ExistingWindowVROverlayOptions {
+    name?: string;
+    frameRate?: number;
+    sizeMeters?: number;
+    visible?: boolean;
+    placement?: VROverlayOptions["placement"];
+}
+export declare class VROverlay {
+    readonly width: number;
+    readonly height: number;
+    readonly url: string;
+    readonly overlayName: string;
+    readonly frameRate: number;
+    readonly windowOptions?: VROverlayOptions["windowOptions"];
+    private sizeMeters;
+    private visible;
+    private placement;
+    private readonly vrBridge;
+    private window;
+    private ownsWindow;
+    private initialized;
+    constructor(options?: VROverlayOptions);
+    static getRuntimeInfo(): RuntimeInfo;
+    static isAvailable(runtimeInfo?: RuntimeInfo): boolean;
+    static hasRealVRRuntime(runtimeInfo?: RuntimeInfo): boolean;
+    static openWindow(window: BrowserWindow, options?: ExistingWindowVROverlayOptions): Promise<VROverlay | null>;
+    getRuntimeInfo(): RuntimeInfo;
+    getSelectedBackend(): BackendKind;
+    isInitialized(): boolean;
+    init(): Promise<boolean>;
+    initWithWindow(window: BrowserWindow): Promise<boolean>;
+    destroy(): void;
+    setPlacement(placement: VROverlayOptions["placement"]): boolean;
+    setVisible(visible: boolean): boolean;
+    setSizeMeters(sizeMeters: number): boolean;
+    private initializeBridgeForWindow;
+    private readonly onWindowClosed;
+}
+export {};

package/dist/VROverlay.js

@@ -0,0 +1,199 @@
+import { app, BrowserWindow } from "electron";
+import { createVrBridge } from "./bridge.js";
+import { assertSizeMeters, normalizePlacement } from "./overlayOptions.js";
+function mergeWindowOptions(width, height, windowOptions) {
+    const requestedOffscreen = windowOptions?.webPreferences?.offscreen;
+    const normalizedOffscreen = typeof requestedOffscreen === "object"
+        ? { useSharedTexture: true, ...requestedOffscreen }
+        : { useSharedTexture: true };
+    return {
+        width,
+        height,
+        show: false,
+        frame: false,
+        transparent: true,
+        backgroundColor: "#00000000",
+        ...windowOptions,
+        webPreferences: {
+            offscreen: normalizedOffscreen,
+            contextIsolation: true,
+            nodeIntegration: false,
+            backgroundThrottling: false,
+            ...windowOptions?.webPreferences
+        }
+    };
+}
+function isOffscreenWindow(window) {
+    const webContents = window.webContents;
+    return typeof webContents.isOffscreen === "function" ? webContents.isOffscreen() : false;
+}
+export class VROverlay {
+    width;
+    height;
+    url;
+    overlayName;
+    frameRate;
+    windowOptions;
+    sizeMeters;
+    visible;
+    placement;
+    vrBridge = createVrBridge();
+    window = null;
+    ownsWindow = false;
+    initialized = false;
+    constructor(options = {}) {
+        this.width = options.width ?? 1024;
+        this.height = options.height ?? 1024;
+        this.url = options.url ?? "about:blank";
+        this.overlayName = options.name ?? "Electron_VR_Overlay";
+        this.frameRate = options.frameRate ?? 60;
+        this.windowOptions = options.windowOptions;
+        this.sizeMeters = options.sizeMeters ?? 1.0;
+        assertSizeMeters(this.sizeMeters);
+        this.visible = options.visible ?? true;
+        this.placement = normalizePlacement(options.placement);
+    }
+    static getRuntimeInfo() {
+        return createVrBridge().getRuntimeInfo();
+    }
+    static isAvailable(runtimeInfo = VROverlay.getRuntimeInfo()) {
+        return runtimeInfo.selectedBackend !== "none";
+    }
+    static hasRealVRRuntime(runtimeInfo = VROverlay.getRuntimeInfo()) {
+        return runtimeInfo.selectedBackend === "openxr" || runtimeInfo.selectedBackend === "openvr";
+    }
+    static async openWindow(window, options = {}) {
+        const [width, height] = window.getContentSize();
+        const overlay = new VROverlay({
+            name: options.name,
+            width,
+            height,
+            frameRate: options.frameRate,
+            sizeMeters: options.sizeMeters,
+            visible: options.visible,
+            placement: options.placement
+        });
+        return await overlay.initWithWindow(window) ? overlay : null;
+    }
+    getRuntimeInfo() {
+        return this.vrBridge.getRuntimeInfo();
+    }
+    getSelectedBackend() {
+        return this.vrBridge.getSelectedBackend();
+    }
+    isInitialized() {
+        return this.initialized && this.vrBridge.isInitialized();
+    }
+    async init() {
+        await app.whenReady();
+        if (this.initialized) {
+            return true;
+        }
+        const window = new BrowserWindow(mergeWindowOptions(this.width, this.height, this.windowOptions));
+        this.ownsWindow = true;
+        this.window = window;
+        window.once("closed", this.onWindowClosed);
+        const initialized = this.initializeBridgeForWindow(window, this.width, this.height);
+        if (!initialized) {
+            window.removeListener("closed", this.onWindowClosed);
+            this.window = null;
+            this.ownsWindow = false;
+            window.close();
+            return false;
+        }
+        await window.loadURL(this.url);
+        this.initialized = true;
+        return true;
+    }
+    async initWithWindow(window) {
+        await app.whenReady();
+        if (this.initialized) {
+            return true;
+        }
+        if (!isOffscreenWindow(window)) {
+            console.error("Existing BrowserWindow is not offscreen-enabled. Create it with offscreen rendering enabled before moving it into VR.");
+            return false;
+        }
+        const [width, height] = window.getContentSize();
+        this.window = window;
+        this.ownsWindow = false;
+        window.once("closed", this.onWindowClosed);
+        const initialized = this.initializeBridgeForWindow(window, width, height);
+        if (!initialized) {
+            window.removeListener("closed", this.onWindowClosed);
+            this.window = null;
+            return false;
+        }
+        this.initialized = true;
+        return true;
+    }
+    destroy() {
+        this.vrBridge.shutdown();
+        if (this.window) {
+            this.window.removeListener("closed", this.onWindowClosed);
+            if (this.ownsWindow && !this.window.isDestroyed()) {
+                this.window.close();
+            }
+            this.window = null;
+        }
+        this.ownsWindow = false;
+        this.initialized = false;
+    }
+    setPlacement(placement) {
+        const normalizedPlacement = normalizePlacement(placement);
+        this.placement = normalizedPlacement;
+        if (!this.isInitialized()) {
+            return true;
+        }
+        const success = this.vrBridge.setOverlayPlacement(normalizedPlacement);
+        if (!success) {
+            console.error("Failed to update VR overlay placement:", this.vrBridge.getLastError());
+        }
+        return success;
+    }
+    setVisible(visible) {
+        this.visible = visible;
+        if (!this.isInitialized()) {
+            return true;
+        }
+        const success = this.vrBridge.setOverlayVisible(visible);
+        if (!success) {
+            console.error("Failed to update VR overlay visibility:", this.vrBridge.getLastError());
+        }
+        return success;
+    }
+    setSizeMeters(sizeMeters) {
+        assertSizeMeters(sizeMeters);
+        this.sizeMeters = sizeMeters;
+        if (!this.isInitialized()) {
+            return true;
+        }
+        const success = this.vrBridge.setOverlaySizeMeters(sizeMeters);
+        if (!success) {
+            console.error("Failed to update VR overlay size:", this.vrBridge.getLastError());
+        }
+        return success;
+    }
+    initializeBridgeForWindow(window, width, height) {
+        const initialized = this.vrBridge.initialize({
+            name: this.overlayName,
+            width,
+            height,
+            sizeMeters: this.sizeMeters,
+            visible: this.visible,
+            placement: this.placement
+        });
+        if (!initialized) {
+            console.error("Failed to initialize VR bridge:", this.vrBridge.getLastError());
+            return false;
+        }
+        this.vrBridge.attachWindow(window, { frameRate: this.frameRate });
+        return true;
+    }
+    onWindowClosed = () => {
+        this.vrBridge.shutdown();
+        this.window = null;
+        this.ownsWindow = false;
+        this.initialized = false;
+    };
+}

package/dist/bridge.d.ts

@@ -0,0 +1,116 @@
+import type { BrowserWindow } from "electron";
+export type BackendKind = "none" | "openxr" | "openvr" | "mock";
+export interface RuntimeInfo {
+    platform: string;
+    probeMode: string;
+    openxrAvailable: boolean;
+    openxrOverlayExtensionAvailable: boolean;
+    openxrLinuxEglBindingAvailable: boolean;
+    openxrWindowsD3D11BindingAvailable: boolean;
+    openxrRuntimeName: string;
+    openxrRuntimeManifestPath: string;
+    openxrRuntimeLibraryPath: string;
+    openxrLoaderPath: string;
+    openxrSessionState: string;
+    openxrSessionRunning: boolean;
+    openvrAvailable: boolean;
+    openvrRuntimeInstalled: boolean;
+    openvrRuntimePath: string;
+    openvrSceneApplicationState: string;
+    openvrSceneProcessId: number;
+    openvrSceneApplicationKey: string;
+    openvrSceneApplicationName: string;
+    openvrSceneApplicationBinaryPath: string;
+    selectedBackend: BackendKind;
+}
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface Quat {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+export type PlacementMode = "head" | "world";
+export interface OverlayPlacement {
+    mode: PlacementMode;
+    position: Vec3;
+    rotation: Quat;
+}
+export interface InitializeVROptions {
+    name: string;
+    width: number;
+    height: number;
+    sizeMeters: number;
+    visible: boolean;
+    placement: OverlayPlacement;
+}
+export interface LinuxTexturePlane {
+    fd: number;
+    stride: number;
+    offset: number;
+    size: number;
+}
+export interface LinuxTextureInfo {
+    codedSize?: {
+        width: number;
+        height: number;
+    };
+    pixelFormat?: "rgba" | "bgra";
+    modifier?: string;
+    planes?: LinuxTexturePlane[];
+}
+export interface SoftwareFrameInfo {
+    width: number;
+    height: number;
+    rgbaPixels: Buffer;
+}
+export interface SharedTextureInfo extends LinuxTextureInfo {
+    sharedTextureHandle?: Buffer;
+}
+export interface SharedTexturePayload {
+    textureInfo?: SharedTextureInfo;
+    release(): void;
+}
+export interface NativeImageLike {
+    getSize(): {
+        width: number;
+        height: number;
+    };
+    toBitmap(): Buffer;
+}
+export interface AttachWindowOptions {
+    frameRate?: number;
+}
+export declare class VrBridge {
+    private readonly addon;
+    private attachedWindow;
+    private warnedAboutMissingSharedTexture;
+    private warnedAboutSoftwareFallback;
+    private warnedAboutWindowsSoftwareFallback;
+    private loggedFirstPaint;
+    private loggedFirstWindowsHandle;
+    private loggedFirstWindowsSubmit;
+    private loggedFirstWindowsSoftwareSubmit;
+    private windowsReadbackInFlight;
+    private windowsReadbackPending;
+    attachWindow(window: BrowserWindow, options?: AttachWindowOptions): void;
+    detachWindow(): void;
+    getRuntimeInfo(): RuntimeInfo;
+    getSelectedBackend(): BackendKind;
+    initialize(options: InitializeVROptions): boolean;
+    setOverlayPlacement(placement: OverlayPlacement): boolean;
+    setOverlayVisible(visible: boolean): boolean;
+    setOverlaySizeMeters(sizeMeters: number): boolean;
+    shutdown(): void;
+    isInitialized(): boolean;
+    getLastError(): string | null;
+    private submitWindowsSoftwareFrame;
+    private useWindowsSoftwareFallback;
+    private scheduleWindowsCaptureFallback;
+    private readonly onPaint;
+}
+export declare function createVrBridge(): VrBridge;

package/dist/bridge.js

@@ -0,0 +1,370 @@
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+let cachedAddon = null;
+const PREBUILT_ADDON_PACKAGES = {
+    linux: {
+        x64: "@covas-labs/electron-vr-prebuilt-linux-x64"
+    },
+    win32: {
+        x64: "@covas-labs/electron-vr-prebuilt-win32-x64"
+    }
+};
+function resolvePrebuiltPackageName() {
+    const packagesForPlatform = PREBUILT_ADDON_PACKAGES[process.platform];
+    if (!packagesForPlatform) {
+        return null;
+    }
+    return packagesForPlatform[process.arch] ?? null;
+}
+function prependLibrarySearchPath(directory) {
+    if (!existsSync(directory)) {
+        return;
+    }
+    if (process.platform === "win32") {
+        const currentPath = process.env.PATH ?? "";
+        const pathEntries = currentPath.split(";").filter(Boolean);
+        if (!pathEntries.includes(directory)) {
+            process.env.PATH = currentPath ? `${directory};${currentPath}` : directory;
+        }
+        return;
+    }
+    if (process.platform === "linux") {
+        const currentLdLibraryPath = process.env.LD_LIBRARY_PATH ?? "";
+        const pathEntries = currentLdLibraryPath.split(":").filter(Boolean);
+        if (!pathEntries.includes(directory)) {
+            process.env.LD_LIBRARY_PATH = currentLdLibraryPath ? `${directory}:${currentLdLibraryPath}` : directory;
+        }
+        return;
+    }
+}
+function ensureOpenVRLibraryPath(currentDir) {
+    const localAddonDir = resolve(currentDir, "..", "..", "native-addon", "build", "Release");
+    prependLibrarySearchPath(localAddonDir);
+    const prebuiltPackageName = resolvePrebuiltPackageName();
+    if (prebuiltPackageName) {
+        const require = createRequire(import.meta.url);
+        try {
+            const prebuiltEntry = require.resolve(prebuiltPackageName);
+            prependLibrarySearchPath(dirname(prebuiltEntry));
+        }
+        catch {
+            // Ignore and fall back to application resolution or SDK lookup.
+        }
+        try {
+            const applicationRequire = createRequire(resolve(process.cwd(), "package.json"));
+            const prebuiltEntry = applicationRequire.resolve(prebuiltPackageName);
+            prependLibrarySearchPath(dirname(prebuiltEntry));
+        }
+        catch {
+            // Ignore and fall back to SDK lookup.
+        }
+    }
+    const sdkDir = process.env.OPENVR_SDK_DIR;
+    if (!sdkDir) {
+        return;
+    }
+    if (process.platform === "win32") {
+        prependLibrarySearchPath(resolve(sdkDir, "bin", "win64"));
+    }
+    else if (process.platform === "linux") {
+        prependLibrarySearchPath(resolve(sdkDir, "lib", "linux64"));
+    }
+}
+function loadVrBridgeAddon() {
+    if (cachedAddon) {
+        return cachedAddon;
+    }
+    const require = createRequire(import.meta.url);
+    const applicationRequire = createRequire(resolve(process.cwd(), "package.json"));
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    const localAddonPath = resolve(currentDir, "..", "..", "native-addon", "build", "Release", "vr_bridge.node");
+    ensureOpenVRLibraryPath(currentDir);
+    try {
+        cachedAddon = require(localAddonPath);
+        return cachedAddon;
+    }
+    catch (localError) {
+        const prebuiltPackageName = resolvePrebuiltPackageName();
+        if (!prebuiltPackageName) {
+            throw new Error(`No supported prebuilt Electron addon is available for ${process.platform}-${process.arch}. Local addon load failed: ${String(localError)}`);
+        }
+        try {
+            cachedAddon = require(prebuiltPackageName);
+            return cachedAddon;
+        }
+        catch (packageRequireError) {
+            try {
+                cachedAddon = applicationRequire(prebuiltPackageName);
+                return cachedAddon;
+            }
+            catch (applicationRequireError) {
+                throw new Error(`Failed to load the Electron VR addon from ${localAddonPath} or ${prebuiltPackageName}. Local error: ${String(localError)}. Package-local prebuilt error: ${String(packageRequireError)}. Application-level prebuilt error: ${String(applicationRequireError)}`);
+            }
+        }
+    }
+}
+function sanitizeRuntimeInfo(runtimeInfo) {
+    return {
+        ...runtimeInfo,
+        openxrSessionState: runtimeInfo.openxrSessionState ?? "unknown",
+        openxrSessionRunning: runtimeInfo.openxrSessionRunning ?? false,
+        openvrSceneApplicationState: runtimeInfo.openvrSceneApplicationState ?? "",
+        openvrSceneProcessId: runtimeInfo.openvrSceneProcessId ?? 0,
+        openvrSceneApplicationKey: runtimeInfo.openvrSceneApplicationKey ?? "",
+        openvrSceneApplicationName: runtimeInfo.openvrSceneApplicationName ?? "",
+        openvrSceneApplicationBinaryPath: runtimeInfo.openvrSceneApplicationBinaryPath ?? ""
+    };
+}
+function isSharedTexturePayload(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.release === "function" || typeof candidate.textureInfo === "object";
+}
+function isNativeImageLike(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.getSize === "function" && typeof candidate.toBitmap === "function";
+}
+function bgraToRgba(source) {
+    const result = Buffer.allocUnsafe(source.length);
+    for (let index = 0; index < source.length; index += 4) {
+        result[index] = source[index + 2];
+        result[index + 1] = source[index + 1];
+        result[index + 2] = source[index];
+        result[index + 3] = source[index + 3];
+    }
+    return result;
+}
+function releaseTexture(texture) {
+    if (texture && typeof texture.release === "function") {
+        texture.release();
+    }
+}
+function cloneLinuxTextureInfo(textureInfo) {
+    return {
+        codedSize: textureInfo.codedSize
+            ? {
+                width: textureInfo.codedSize.width,
+                height: textureInfo.codedSize.height
+            }
+            : undefined,
+        pixelFormat: textureInfo.pixelFormat,
+        modifier: textureInfo.modifier,
+        planes: textureInfo.planes?.map((plane) => ({
+            fd: plane.fd,
+            stride: plane.stride,
+            offset: plane.offset,
+            size: plane.size
+        }))
+    };
+}
+export class VrBridge {
+    addon = loadVrBridgeAddon();
+    attachedWindow = null;
+    warnedAboutMissingSharedTexture = false;
+    warnedAboutSoftwareFallback = false;
+    warnedAboutWindowsSoftwareFallback = false;
+    loggedFirstPaint = false;
+    loggedFirstWindowsHandle = false;
+    loggedFirstWindowsSubmit = false;
+    loggedFirstWindowsSoftwareSubmit = false;
+    windowsReadbackInFlight = false;
+    windowsReadbackPending = false;
+    attachWindow(window, options = {}) {
+        this.detachWindow();
+        const offscreenContents = window.webContents;
+        offscreenContents.setFrameRate(options.frameRate ?? 60);
+        offscreenContents.on("paint", this.onPaint);
+        this.attachedWindow = window;
+    }
+    detachWindow() {
+        if (!this.attachedWindow) {
+            return;
+        }
+        const offscreenContents = this.attachedWindow.webContents;
+        offscreenContents.removeListener("paint", this.onPaint);
+        this.attachedWindow = null;
+    }
+    getRuntimeInfo() {
+        return sanitizeRuntimeInfo(this.addon.getRuntimeInfo());
+    }
+    getSelectedBackend() {
+        return this.getRuntimeInfo().selectedBackend;
+    }
+    initialize(options) {
+        return this.addon.initializeVR(options);
+    }
+    setOverlayPlacement(placement) {
+        return this.addon.setOverlayPlacement(placement);
+    }
+    setOverlayVisible(visible) {
+        return this.addon.setOverlayVisible(visible);
+    }
+    setOverlaySizeMeters(sizeMeters) {
+        return this.addon.setOverlaySizeMeters(sizeMeters);
+    }
+    shutdown() {
+        this.detachWindow();
+        this.addon.shutdownVR();
+    }
+    isInitialized() {
+        return this.addon.isInitialized();
+    }
+    getLastError() {
+        return this.addon.getLastError();
+    }
+    submitWindowsSoftwareFrame(nativeImage) {
+        const { width, height } = nativeImage.getSize();
+        const bitmap = nativeImage.toBitmap();
+        if (width === 0 || height === 0 || bitmap.length === 0) {
+            console.warn(`Windows software frame readback was empty (width=${width}, height=${height}, bytes=${bitmap.length}).`);
+            return false;
+        }
+        const submitted = this.addon.submitSoftwareFrame({
+            width,
+            height,
+            rgbaPixels: bgraToRgba(bitmap)
+        });
+        if (!submitted) {
+            console.error("Failed to submit Windows software frame to VR bridge:", this.addon.getLastError());
+            return false;
+        }
+        if (!this.loggedFirstWindowsSoftwareSubmit) {
+            this.loggedFirstWindowsSoftwareSubmit = true;
+            console.log("VR overlay submitted first Windows software frame to the native bridge.");
+        }
+        return true;
+    }
+    useWindowsSoftwareFallback(nativeImage, warning) {
+        if (!this.warnedAboutWindowsSoftwareFallback) {
+            this.warnedAboutWindowsSoftwareFallback = true;
+            console.warn(warning);
+        }
+        if (nativeImage && this.submitWindowsSoftwareFrame(nativeImage)) {
+            return;
+        }
+        this.scheduleWindowsCaptureFallback();
+    }
+    scheduleWindowsCaptureFallback() {
+        if (!this.attachedWindow) {
+            return;
+        }
+        if (this.windowsReadbackInFlight) {
+            this.windowsReadbackPending = true;
+            return;
+        }
+        this.windowsReadbackInFlight = 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) => {
+            this.submitWindowsSoftwareFrame(image);
+        })
+            .catch((error) => {
+            console.error("Failed to capture Windows software fallback frame:", error);
+        })
+            .finally(() => {
+            this.windowsReadbackInFlight = false;
+            if (this.windowsReadbackPending) {
+                this.windowsReadbackPending = false;
+                this.scheduleWindowsCaptureFallback();
+            }
+        });
+    }
+    onPaint = (event, _dirty, paintResult) => {
+        const nativeImage = isNativeImageLike(paintResult) ? paintResult : null;
+        const texture = isSharedTexturePayload(event.texture)
+            ? event.texture
+            : isSharedTexturePayload(paintResult)
+                ? paintResult
+                : null;
+        if (!this.loggedFirstPaint) {
+            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"}).`);
+        }
+        if (!texture) {
+            if (process.platform === "win32" && this.getSelectedBackend() === "openvr") {
+                this.useWindowsSoftwareFallback(nativeImage, "Windows shared texture payload was unavailable; falling back to software RGBA upload.");
+                return;
+            }
+            if (this.getSelectedBackend() === "mock" && nativeImage) {
+                const { width, height } = nativeImage.getSize();
+                this.addon.submitSoftwareFrame({
+                    width,
+                    height,
+                    rgbaPixels: bgraToRgba(nativeImage.toBitmap())
+                });
+                if (!this.warnedAboutSoftwareFallback) {
+                    this.warnedAboutSoftwareFallback = true;
+                    console.warn("Shared texture payload was unavailable; using software bitmap upload for mock preview.");
+                }
+                return;
+            }
+            if (!this.warnedAboutMissingSharedTexture) {
+                this.warnedAboutMissingSharedTexture = true;
+                console.warn("Shared texture payload was unavailable on paint; Electron provided a bitmap instead.");
+            }
+            return;
+        }
+        try {
+            const textureInfo = texture.textureInfo;
+            const handle = textureInfo?.sharedTextureHandle;
+            if (process.platform === "win32") {
+                if (Buffer.isBuffer(handle)) {
+                    if (!this.loggedFirstWindowsHandle) {
+                        this.loggedFirstWindowsHandle = true;
+                        console.log(`VR overlay received Windows shared texture handle (${handle.byteLength} bytes).`);
+                    }
+                    const submitted = this.addon.submitSharedTexture(handle);
+                    if (!submitted) {
+                        console.error("Failed to submit Windows frame to VR bridge:", this.addon.getLastError());
+                        if (this.getSelectedBackend() === "openvr") {
+                            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 (this.getSelectedBackend() === "openvr") {
+                    this.useWindowsSoftwareFallback(nativeImage, "Windows shared texture handle was unavailable; falling back to software RGBA upload.");
+                }
+                else if (!this.warnedAboutMissingSharedTexture) {
+                    this.warnedAboutMissingSharedTexture = true;
+                    console.warn("Shared texture handle was unavailable on Windows; VR submission was skipped.");
+                }
+                return;
+            }
+            if (process.platform === "linux") {
+                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());
+                    }
+                }
+                else if (!this.warnedAboutMissingSharedTexture) {
+                    this.warnedAboutMissingSharedTexture = true;
+                    console.warn("Shared texture metadata was unavailable on paint; preview submission was skipped.");
+                }
+            }
+        }
+        catch (error) {
+            console.error("Error while forwarding frame to VR bridge:", error);
+        }
+        finally {
+            releaseTexture(texture);
+        }
+    };
+}
+export function createVrBridge() {
+    return new VrBridge();
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { VrBridge, createVrBridge, type AttachWindowOptions, type BackendKind, type InitializeVROptions, type OverlayPlacement, type Quat, type RuntimeInfo, type Vec3 } from "./bridge.js";
+export { VROverlay, type ExistingWindowVROverlayOptions, type VROverlayOptions } from "./VROverlay.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { VrBridge, createVrBridge } from "./bridge.js";
+export { VROverlay } from "./VROverlay.js";

package/dist/overlayOptions.d.ts

@@ -0,0 +1,11 @@
+import type { Quat, OverlayPlacement, Vec3 } from "./bridge.js";
+export interface OverlayPlacementInput {
+    mode: "head" | "world";
+    position?: Vec3;
+    rotation?: Quat;
+}
+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 normalizePlacement(placement?: OverlayPlacementInput): OverlayPlacement;

package/dist/overlayOptions.js

@@ -0,0 +1,42 @@
+export function isFiniteNumber(value) {
+    return Number.isFinite(value);
+}
+export function assertVec3(value, context) {
+    if (!isFiniteNumber(value.x) || !isFiniteNumber(value.y) || !isFiniteNumber(value.z)) {
+        throw new TypeError(`${context} must contain finite x, y, and z values.`);
+    }
+}
+export function assertQuat(value, context) {
+    if (!isFiniteNumber(value.x) || !isFiniteNumber(value.y) || !isFiniteNumber(value.z) || !isFiniteNumber(value.w)) {
+        throw new TypeError(`${context} must contain finite x, y, z, and w values.`);
+    }
+}
+export function assertSizeMeters(sizeMeters) {
+    if (!isFiniteNumber(sizeMeters) || sizeMeters <= 0) {
+        throw new RangeError("sizeMeters must be a finite number greater than zero.");
+    }
+}
+export function normalizePlacement(placement) {
+    const mode = placement?.mode ?? "head";
+    if (mode !== "head" && mode !== "world") {
+        throw new RangeError("placement.mode must be 'head' or 'world'.");
+    }
+    const position = {
+        x: placement?.position?.x ?? 0,
+        y: placement?.position?.y ?? 0,
+        z: placement?.position?.z ?? -1.2
+    };
+    const rotation = {
+        x: placement?.rotation?.x ?? 0,
+        y: placement?.rotation?.y ?? 0,
+        z: placement?.rotation?.z ?? 0,
+        w: placement?.rotation?.w ?? 1
+    };
+    assertVec3(position, "placement.position");
+    assertQuat(rotation, "placement.rotation");
+    return {
+        mode,
+        position,
+        rotation
+    };
+}

package/package.json

@@ -1,22 +1,29 @@
 {
   "name": "@covas-labs/electron-vr",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Bootstrap placeholder package for npm trusted publishing setup.",
+  "version": "0.3.2",
+  "description": "Electron VR overlay bridge with OpenXR, OpenVR, and mock fallback backends.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/COVAS-Labs/electron-vr.git"
   },
-  "main": "index.js",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "files": [
-    "index.js",
-    "README.md"
+    "dist"
   ],
+  "peerDependencies": {
+    "electron": ">=37"
+  },
   "optionalDependencies": {
-    "@covas-labs/electron-vr-prebuilt-linux-x64": "0.0.0-bootstrap.0",
-    "@covas-labs/electron-vr-prebuilt-win32-x64": "0.0.0-bootstrap.0"
+    "@covas-labs/electron-vr-prebuilt-linux-x64": "0.3.2",
+    "@covas-labs/electron-vr-prebuilt-win32-x64": "0.3.2"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/index.js

@@ -1,4 +0,0 @@
-module.exports = {
-  bootstrap: true,
-  message: "Bootstrap placeholder package. Configure trusted publishing, then publish a real tagged release."
-};