@plasius/gpu-xr

Framework-agnostic WebXR session management for Plasius GPU rendering projects. This package isolates VR session lifecycle and capability probing so app layers can replace Three.js and still keep immersive workflows.

Apache-2.0. ESM + CJS builds.

Install

npm install @plasius/gpu-xr

Usage

import { createXrManager } from "@plasius/gpu-xr";

const xr = createXrManager();
await xr.probeSupport(["immersive-vr"]);

const session = await xr.enterVr({
  optionalFeatures: ["depth-sensing", "layers"],
});

// ... bind WebGPU render state to the session ...

await xr.exitSession();

Adaptive Performance Integration

@plasius/gpu-xr now exposes XR runtime frame-rate hints so @plasius/gpu-performance can negotiate platform-native frame targets while @plasius/gpu-renderer and @plasius/gpu-worker stay aligned on the xr worker budget profile.

import { createXrManager } from "@plasius/gpu-xr";

const xr = createXrManager();
await xr.enterVr();

const hint = xr.getPerformanceHint({ preferredFrameRates: [90, 72] });
console.log(hint.targetFrameRate, hint.workerBudget);

await xr.setTargetFrameRate(hint.targetFrameRate);

API

• isXrModeSupported(mode, options)
• requestXrSession(options)
• readXrFrameRateCapabilities(session, options)
• createXrPerformanceHint(options)
• updateXrTargetFrameRate(session, frameRate)
• createXrStore(initialState)
• createXrManager(options)
• mergeXrSessionInit(base, override)
• defaultVrSessionInit
• xrWorkerQueueClass
• xrWorkerSchedulerMode
• defaultXrWorkerBudgetProfile

Demo

Run the demo server from the repo root:

cd gpu-xr
npm run demo

Then open http://localhost:8000/gpu-xr/demo/.

The demo mounts the shared @plasius/gpu-shared 3D harbor surface and keeps XR capability, target mode, and worker-budget negotiation visible in context. It stays browser-safe by rendering on the shared scene while @plasius/gpu-xr continues to own XR support probing, frame-target hints, and session metadata instead of a package-local renderer copy.

Development Checks

npm run lint
npm run typecheck
npm run test:coverage
npm run build
npm run pack:check

Files

• src/index.js: XR runtime/session manager and store.
• src/index.d.ts: public API typings.
• tests/package.test.js: Unit tests for support probing and lifecycle handling.
• docs/adrs/*: XR architecture decisions.
• docs/tdrs/*: XR technical direction records.
• docs/design/*: XR integration design notes.