@realitycollective/service-framework-three 1.0.1-preview.1 → 1.0.1-preview.3

package/CHANGELOG.md

@@ -6,10 +6,27 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [1.0.1]
 
-Packaging, tooling and documentation. No runtime behaviour changed, and no public API was added, removed or altered.
+Packaging, tooling and documentation, plus additive runtime API: the engine-free adapter contracts move into the core, the IWSDK adapter derives capabilities from the live session and gains a session facet, and the three.js and Babylon.js packages gain runtime adapters so a three.js, Babylon or desktop app reaches the same seam. Nothing that existed was removed, and one interface changed shape: `AdapterCapabilities` gains a required `environmentBlendMode` key, so code that builds the whole object by hand - an adapter of your own, or a test fake - has one more field to supply. Code that only reads capabilities is unaffected.
 
 ### Added
 
+- `@realitycollective/service-framework` now exports `RuntimeAdapter`, `FrameInfo`, `AdapterCapabilities`, `DEFAULT_CAPABILITIES`, `FrameListener`, `CapabilitiesListener`, `Unsubscribe`, `SnapshotService`, `ServiceContext`, `SnapshotListener` and `MockRuntimeAdapter`. All eleven arrived in `@realitycollective/service-framework-iwsdk`, and none of them ever touched IWSDK: the adapter contract is the seam every host binding needs, `SnapshotService` is a plain `BaseService` subclass, and the mock adapter is how any service is unit-tested headless. An app on three.js or Babylon.js had to depend on the IWSDK package to reach them. They now live in the core, and the IWSDK package re-exports every one of them unchanged, so existing imports keep resolving.
+- `deriveCapabilities(session)` in `@realitycollective/service-framework`, with its structural input types `CapabilitySessionLike` and `CapabilityInputSourceLike`. It reads `immersive`, `handTracking`, `planeDetection` and `passthrough` off a live XR session, and is the derivation `IWSDKAdapter` had been doing privately. A second adapter would have re-implemented the same four rules and then drifted from them, so they live in the core once and every host binding reports the same flags for the same session. `IWSDKAdapter` now calls it and reports exactly what it reported before, and `IWSDKSessionLike` is `CapabilitySessionLike` with `inputSources` required, so nothing changes for a consumer.
+- `WebXRRuntimeAdapter` in `@realitycollective/service-framework-three`, with the structural host types it is written against: `WebXRManagerLike` (`renderer.xr`), `WebXRSystemLike` (`navigator.xr`), `WebXRSessionLike`, `WebXRRuntimeAdapterOptions`, `WebXRManagerEventType`, `WebXRSessionEventType` and `WebXREventListener`. Until now only an IWSDK app could get a `RuntimeAdapter`, so a service written against that seam had no host on a plain three.js page or a desktop build. The adapter orchestrates the entry points the platform already provides - `navigator.xr` to negotiate a session, `renderer.xr` for the session the renderer presents, `setAnimationLoop` for frames - and publishes them through the same interface. It renders nothing, plays nothing and owns no scene state. Given a `host` it owns the animation loop, and given a `scheduler` as well it emits `renderTick` with `source: "three"` exactly as `ThreeRenderLoopBridge` does, so an app needs one loop owner rather than two; given no host, the app drives `emitFrame` itself. `sessionInit` supplies the `XRSessionInit` per mode. Capabilities come from the core's `deriveCapabilities` and are re-derived on the renderer's `sessionstart` and `sessionend` and the session's `inputsourceschange`, with the same override layer, `refreshCapabilities()` and `clearCapabilityOverrides()` the IWSDK adapter has. The same adapter serves a desktop build with no headset: `session.request` returns `{ ok: false, reason: "unsupported" }` where there is no `navigator.xr` or the mode is not supported, and capabilities stay at the all-false defaults.
+- `FIRST_FRAME_DELTA_MS` from the three.js package - the 16 ms the bridge and the adapter both report for a first frame that has no previous timestamp.
+- `BabylonRuntimeAdapter` in `@realitycollective/service-framework-babylon`, with the structural host types it is written against: `BabylonXRExperienceLike` (`WebXRDefaultExperience.baseExperience`), `BabylonSessionManagerLike`, `BabylonXRSessionLike`, `BabylonObservableLike`, `BabylonObserverLike`, `BabylonRuntimeAdapterOptions`, `BabylonXRSessionEventType`, `BabylonXREventListener` and `BabylonWebXRState`, plus the `BABYLON_WEBXR_STATE` and `DEFAULT_REFERENCE_SPACE_TYPE` constants. The package shipped a render-loop bridge and nothing else, so a Babylon app could emit `renderTick` but could not host a service written against `RuntimeAdapter`. The adapter orchestrates the entry points Babylon already provides - the experience helper to negotiate a session, the session manager for the live `XRSession`, `runRenderLoop` for frames - and publishes them through the same interface, with the same members and the same semantics as `WebXRRuntimeAdapter`, so a consumer moving between renderers sees no difference at this seam. Given a `host` it owns the render loop, and given a `scheduler` as well it emits `renderTick` with `source: "babylon"` exactly as `BabylonRenderLoopBridge` does, so an app needs one loop owner rather than two; given no host, the app drives `emitFrame` itself. `referenceSpaceType` defaults to `"local-floor"`, and `sessionInit` supplies the session creation options per mode. Capabilities come from the core's `deriveCapabilities` and are re-derived on `onXRSessionInit`, `onXRSessionEnded` and the session's `inputsourceschange`, with the same override layer, `refreshCapabilities()` and `clearCapabilityOverrides()` the other adapters have. A session started outside the adapter - by Babylon's own enter-XR UI, for instance - is followed through `onStateChangedObservable`, so the facet is correct either way. The same adapter serves a desktop build with no headset: `session.request` returns `{ ok: false, reason: "unsupported" }` where there is no experience or the mode is not supported, and capabilities stay at the all-false defaults. `@babylonjs/core` is still neither imported nor installed: every Babylon shape is structural, and anything a version might move or drop - the session manager, the observables, `isSessionSupportedAsync` - is optional and read through a guard.
+- `FIRST_FRAME_DELTA_MS` from the Babylon.js package - the same 16 ms, now shared by `BabylonRenderLoopBridge` and `BabylonRuntimeAdapter` instead of sitting inline in the bridge.
+- Capability derivation in `IWSDKAdapter`. It reads the live session on construction and on every visibility change: `immersive` when a session exists, `handTracking` from the `hand-tracking` enabled feature or any input source carrying a hand, `planeDetection` from the `plane-detection` enabled feature, and `passthrough` when `environmentBlendMode` is present and is not `opaque`. Subscribers are notified only when a flag actually changes. `setCapabilities` becomes a manual override layer on top, dropped by the new `clearCapabilityOverrides()` or by the new `dispose()`. `refreshCapabilities()` re-derives on demand, for a host whose visibility signal cannot push. Before this, the adapter reported all-false until the app called `setCapabilities` by hand.
+- `inputsourceschange` handling in `IWSDKAdapter`, closing a parity gap with the three.js and Babylon.js adapters, which both bound the event already. The IWSDK adapter re-derived only on the world's visibility signal and at session start and end, so an app that wanted `handTracking` to update when the player put the controllers down had to attach the listener itself. It now attaches one listener to the live session, moves it when a session is replaced, and drops it when the session goes or the adapter is disposed. `IWSDKSessionLike` gains optional `addEventListener` and `removeEventListener` for it, with the two new types `IWSDKSessionEventType` and `IWSDKSessionEventListener`. Both members are optional, so a world faked in a test still satisfies the type, and the adapter guards for their absence: such a host pushes nothing and `refreshCapabilities()` remains the way to nudge it. IWSDK's own world carries a real `XRSession`, so the event arrives there.
+- `requiredFeatures` and `optionalFeatures` on `SessionRequestOptions`, both optional arrays of WebXR feature strings, plus the `mergeSessionInit(init, options)` helper and its `SessionInitLike` type in the core. `SessionRequestOptions` carried only `timeoutMs`, so an app that swapped from `"immersive-vr"` to `"immersive-ar"` mid-session got whatever defaults the host binding was built with, which were chosen for the mode it was leaving. Each binding now folds the request's features over its own: the host's entries come first, the request's are appended, and a feature named twice appears once. A request that names none passes the host's init through untouched, identity included. The three.js and Babylon.js bindings share `mergeSessionInit` rather than writing the same merge twice.
+- `toIWSDKFeatures(options)`, `IWSDK_FEATURE_KEYS` and `IWSDKFeatureMapping` in `@realitycollective/service-framework-iwsdk`, with the structural `IWSDKXRFeatureOptionsLike`, `IWSDKFeatureFlagLike` and `IWSDKDepthSensingFlagLike` types and a `features` member on `IWSDKXROptionsLike`. IWSDK does not take WebXR feature strings: `launchXR` takes an `XROptions` whose `features` is a structured object, one key per feature. The adapter therefore maps `hand-tracking`, `anchors`, `hit-test`, `plane-detection`, `mesh-detection`, `depth-sensing`, `layers` and `unbounded` onto `handTracking`, `anchors`, `hitTest`, `planeDetection`, `meshDetection`, `depthSensing`, `layers` and `unbounded`, setting a required feature as `{ required: true }` and an optional one as `true`; a feature named in both lists comes out required. A string IWSDK has no key for - `local-floor` and `bounded-floor`, which it configures through `referenceSpace`, or `dom-overlay`, which it does not model - is dropped from the request rather than thrown, because the session is still one the host can serve. `toIWSDKFeatures` is exported so an app can read the `unmapped` list and decide for itself before asking. `launchXR` merges what it is given over the world's `xrDefaults`, so a request naming no features leaves the app's defaults alone.
+- `environmentBlendMode` on `AdapterCapabilities`, typed `EnvironmentBlendMode | null` where `EnvironmentBlendMode` is the new `"opaque" | "alpha-blend" | "additive"` union, plus `environmentBlendMode: null` in `DEFAULT_CAPABILITIES`. `deriveCapabilities` reduced the session's blend mode to the boolean `passthrough` and threw the string away, which says whether the world shows through but not how. The two passthrough modes behave oppositely: `"alpha-blend"` is video passthrough, as on a Quest, and composites normally, so black stays black; `"additive"` is a see-through optical display and adds the rendered image to the light already reaching the eye, so black is fully transparent. A service that dims the world must draw brighter on an additive display, not darker, and could not tell the two apart. The key is required rather than optional, mirroring the `presence` decision in `@realitycollective/webxr-input`, so the conformance suite's capability-key check stays meaningful. A value WebXR does not define derives as `null` rather than passing through, so a consumer switching on the mode never meets a string it has no rule for. `passthrough` keeps its exact meaning, still `true` for any blend mode other than `"opaque"`, including one that derives as `null`. Every adapter reports the new key and every adapter's change detection compares it.
+- `IWSDKXROptionsLike` is now exported from `@realitycollective/service-framework-iwsdk`. It was already the declared parameter type of `IWSDKWorldLike.launchXR`, so a consumer typing a world by hand could not name it.
+- An optional session facet on `RuntimeAdapter`: `session?: SessionFacet`, with `getState`, `request(mode, options)`, `end()`, `onStateChange` and `onVisibilityChange`, plus the `SessionMode`, `SessionState`, `SessionResult`, `SessionFailureReason`, `SessionVisibility` and `SessionRequestOptions` types and the `DEFAULT_SESSION_TIMEOUT_MS` constant. A request resolves with a result rather than throwing, because a host that cannot start a session is a normal runtime condition. `IWSDKAdapter` implements it over the world's `launchXR` and `exitXR`; `MockRuntimeAdapter` implements it in memory, driven by `simulateSessionStart()`, `simulateSessionEnd()` and `simulateVisibility()`.
+- `RUNTIME_ADAPTER_FACETS`, the list of optional facets an adapter can carry, and the `RuntimeAdapterFacet` type. A conformance test walks the list, so a facet added without a mock implementation fails the suite instead of being found by a consumer.
+- `renderTick` under IWSDK. `makeServiceBridgeSystem` now emits the scheduler's `renderTick` channel on every focused frame, with `source: "iwsdk"`, alongside the adapter's `onFrame` fan-out it already drove. A service written against the scheduler now runs under IWSDK exactly as it does under the three.js and Babylon.js bridges. IWSDK reports its frame delta in seconds and the scheduler's `LifecycleContext` is in milliseconds, so the bridge converts.
+- Structural contracts for the parts of an IWSDK world the adapter now reads: `IWSDKSessionLike`, `IWSDKInputSourceLike`, an optional `session` and `launchXR` / `exitXR` on `IWSDKWorldLike`, and an optional `subscribe` on `IWSDKSignalLike`. Every addition is optional, so a world carrying nothing but the visibility signal still type-checks and still works. `@iwsdk/core` remains undeclared as a dependency of any kind.
+- A shared runtime-adapter conformance suite, run against `MockRuntimeAdapter`, `IWSDKAdapter`, `WebXRRuntimeAdapter` and `BabylonRuntimeAdapter`, and published as `runtimeAdapterContractCases()` from `@realitycollective/service-framework` with the `RuntimeAdapterContractCase`, `RuntimeAdapterSubject` and `RuntimeAdapterDriver` types. It began as an in-repo vitest helper, which meant an adapter written outside this repository could not prove it conformed: the checks existed but were not shipped. Following `inputProviderContractCases()` in `@realitycollective/webxr-input`, the suite is now data rather than a runner - each case is a `{ name, run }` pair that returns silently on success and throws a plain `Error` on failure - so an adapter repository hosts the whole thing in three lines of its own runner. Some cases are asynchronous, so a runner must await what `run` returns, and each case needs a fresh subject because the session cases drive a session through its whole lifecycle. A subject whose adapter has no session facet passes the session cases without running them. Test coverage now measures `@realitycollective/service-framework-iwsdk`, `@realitycollective/service-framework-three` and `@realitycollective/service-framework-babylon` as well, at the same 100% thresholds as the core and client packages.
 - Updated documentation packs for all projects.
 - Improved release scripting and validation to improve delivery coherance.
 - `scripts/release.config.json` - names the core package and the publish order, so the release tooling is identical across every Reality Collective TypeScript repository.
@@ -18,6 +35,9 @@ Packaging, tooling and documentation. No runtime behaviour changed, and no publi
 
 ### Changed
 
+- The runtime adapter now abstracts session lifecycle. It previously did not, on the stated grounds that IWSDK already owns sessions, input and rendering. That held while every consumer was an IWSDK app. It stopped holding when a reference client needed to request a session, end one and read session visibility: with no seam for it, the client reached past the adapter into the host, which is the coupling the adapter exists to prevent. Sessions are now an optional facet, so a host that owns them can expose them and a host that does not can leave the property off. Input and rendering are still not abstracted.
+- `IWSDKAdapter.setCapabilities` now notifies subscribers only when at least one flag actually changes value. It previously notified on every call, including calls that set what was already set. The signature is unchanged; a consumer that relied on a callback per call will see fewer callbacks.
+- `ThreeRenderLoopBridge` moved out of the three.js package's `index.ts` into `three-render-loop-bridge.ts`, and `index.ts` is now a barrel that re-exports it unchanged beside the new adapter. Import paths are unaffected. The file-wide v8 coverage exclusion the package carried went with it: the bridge is tested against a fake host, and the whole package is measured.
 - CI and deployment merged into one workflow. They previously ran concurrently and repeated the same install, build, typecheck and test on every pull request. The deploy jobs now consume the artifacts the build job already produced.
 - CI runs on every pull request regardless of target branch, and reports through merge queues.
 - Published sourcemaps embed their sources (`inlineSources`), so stepping into the framework works for consumers. Declaration maps are no longer emitted, because they can only resolve against a `src` directory that is not shipped. Each package is roughly 12% smaller as a result.

package/README.md

@@ -1,14 +1,14 @@
 # @realitycollective/service-framework-three
 
-**three.js render-loop bridge** for the Reality Collective TypeScript Service Framework - connects `renderer.setAnimationLoop()` to the framework's `renderTick` scheduler channel.
+**three.js bindings** for the Reality Collective TypeScript Service Framework - a render-loop bridge that connects `renderer.setAnimationLoop()` to the framework's `renderTick` scheduler channel, and a WebXR runtime adapter that gives a three.js or desktop app the same `RuntimeAdapter` surface the IWSDK binding has.
 
 ```sh
 npm install @realitycollective/service-framework @realitycollective/service-framework-three
 ```
 
-Services written against `BaseService<TConfig>` run unchanged on three.js, Babylon.js or IWSDK - only the bridge differs.
+Services written against `BaseService<TConfig>` run unchanged on three.js, Babylon.js or IWSDK - only the bridge differs. `three` is not a dependency of this package: every host type is structural, so the bindings build and unit-test with no renderer, no WebXR and no headset.
 
-## Usage
+## Render loop
 
 ```ts
 import { ManualScheduler, ServiceManager, createServiceProfile } from "@realitycollective/service-framework";
@@ -29,6 +29,101 @@ bridge.start();
 
 `host` is anything with `setAnimationLoop` (the `AnimationLoopHostLike` interface), so a `WebGLRenderer`, `WebGPURenderer` or a test double all work.
 
+## WebXR runtime adapter
+
+`RuntimeAdapter` is the seam a service depends on to reach its host: per-frame updates, XR capability flags, and session lifecycle. `WebXRRuntimeAdapter` implements it over the entry points a browser already provides - `navigator.xr` to negotiate a session, `renderer.xr` for the session the renderer presents, and `setAnimationLoop` for frames. It orchestrates those; it renders nothing, plays nothing and owns no scene state.
+
+```ts
+import { ManualScheduler, ServiceManager } from "@realitycollective/service-framework";
+import { WebXRRuntimeAdapter } from "@realitycollective/service-framework-three";
+import { WebGLRenderer } from "three";
+
+const manager = new ServiceManager({ scheduler: new ManualScheduler() });
+const renderer = new WebGLRenderer({ canvas });
+renderer.xr.enabled = true;
+
+const adapter = new WebXRRuntimeAdapter({
+  xr: renderer.xr,
+  host: renderer,
+  scheduler: manager.scheduler,
+  sessionInit: () => ({ optionalFeatures: ["hand-tracking"] })
+});
+
+adapter.start();
+
+document.querySelector("#enter-vr")?.addEventListener("click", async () => {
+  const result = await adapter.session.request("immersive-vr");
+
+  if (!result.ok) {
+    // "unsupported" | "denied" | "timeout" | "error" - a normal runtime
+    // outcome, so it comes back as a result rather than a thrown error.
+    showEnterVrError(result.reason);
+  }
+});
+```
+
+Pass the adapter to your services (through their configuration, or a token you register it under) and they read `adapter.onFrame`, `adapter.getCapabilities` and `adapter.session` without knowing three.js exists.
+
+### Owning the loop
+
+Given a `host`, the adapter owns the animation loop: `start()` binds it, `stop()` releases it, and each callback becomes one `FrameInfo` - `timestamp` in milliseconds, `delta` in seconds. Given a `scheduler` as well, the same callback also emits `renderTick` with `source: "three"` and `deltaTime` in milliseconds, exactly as `ThreeRenderLoopBridge` does, so an app needs one loop owner rather than two. Use the adapter or the bridge, not both.
+
+three.js routes `setAnimationLoop` through the session's own `requestAnimationFrame` while presenting, so one call covers both the 2D page and the headset.
+
+Omit `host` to keep the loop yourself and call `adapter.emitFrame(timestamp, delta)` per frame.
+
+### Sessions
+
+`adapter.session` is the optional session facet from `RuntimeAdapter`. `request` never rejects - a headset that is absent, refused or broken is a normal runtime condition, so every outcome is a result:
+
+| Outcome | When |
+| --- | --- |
+| `{ ok: true }` | the session started, or one was already active |
+| `unsupported` | there is no `navigator.xr`, or `isSessionSupported(mode)` resolved false |
+| `denied` | the request failed with `NotAllowedError` or `SecurityError` - the user, the prompt or the permissions policy refused |
+| `timeout` | nothing arrived within `timeoutMs` (default 10000) |
+| `error` | anything else, with the original error attached |
+
+`getState()` walks `"none"` -> `"requesting"` -> `"active"` -> `"ending"` -> `"none"`. `end()` calls `session.end()` and resolves once the session is gone. `onVisibilityChange` maps the session's `visibilitychange` onto `"visible"`, `"visible-blurred"` and `"hidden"`, and reports `"non-immersive"` whenever there is no session. A value the adapter does not recognise is reported as `"hidden"`, because treating an unknown state as visible would keep game logic running when it should not.
+
+`sessionInit` supplies the `XRSessionInit` per mode - required and optional features - and is called once per request. The default sends none.
+
+One request can add features of its own through `SessionRequestOptions`, which matters when an app swaps mode mid-session and the host's defaults were chosen for the mode it is leaving:
+
+```typescript
+await adapter.session.request("immersive-ar", {
+  requiredFeatures: ["hit-test"],
+  optionalFeatures: ["plane-detection"],
+});
+```
+
+They are merged over what `sessionInit` returned rather than replacing it: host entries come first, the request's are appended, and a feature named twice appears once. A request that names none passes the hook's result through untouched. The merge is the core's `mergeSessionInit`, shared with the Babylon binding so the two cannot drift.
+
+### Capabilities
+
+The adapter derives `immersive`, `handTracking`, `planeDetection`, `passthrough` and `environmentBlendMode` from the live session with the core's shared `deriveCapabilities`, which is the same derivation the IWSDK adapter uses. It re-derives when the renderer raises `sessionstart` or `sessionend` and when the session raises `inputsourceschange`, and notifies subscribers only when a flag actually changes. `refreshCapabilities()` re-reads the renderer on demand, for a host that changes what it presents without raising anything.
+
+`setCapabilities({ ... })` is a manual override layer on top: an override wins for as long as it is set, survives every later derivation, and is dropped by `clearCapabilityOverrides()` or `dispose()`.
+
+### The same adapter on the desktop
+
+A desktop build with no headset needs no special case. `request` returns `{ ok: false, reason: "unsupported" }` where the browser has no `navigator.xr` or does not support the mode, capabilities stay at the all-false defaults, and frames keep arriving from the same loop. Services gate on `getCapabilities()` and run either way.
+
+### API surface
+
+| Symbol | Kind | Purpose |
+| --- | --- | --- |
+| `ThreeRenderLoopBridge` | class | `renderer.setAnimationLoop()` to `renderTick`; `start`, `stop`, `dispose`. |
+| `ThreeRenderLoopBridgeOptions` | interface | `{ scheduler, host }`. |
+| `AnimationLoopHostLike` | interface | Anything with `setAnimationLoop`. |
+| `FIRST_FRAME_DELTA_MS` | const | 16 - the delta reported for the first frame. |
+| `WebXRRuntimeAdapter` | class | `RuntimeAdapter` over WebXR; `start`, `stop`, `emitFrame`, `getSession`, `refreshCapabilities`, `setCapabilities`, `clearCapabilityOverrides`, `session`, `dispose`. |
+| `WebXRRuntimeAdapterOptions` | interface | `{ xr, xrSystem?, host?, scheduler?, sessionInit? }`. |
+| `WebXRManagerLike` | interface | The slice of `renderer.xr` the adapter drives. |
+| `WebXRSystemLike` | interface | The slice of `navigator.xr` it negotiates through. |
+| `WebXRSessionLike` | interface | The slice of `XRSession` it reads. |
+| `WebXRManagerEventType` / `WebXRSessionEventType` / `WebXREventListener` | types | The host events it subscribes to. |
+
 ## Live examples
 
 - Weather client walkthrough: **[service-framework-weather.pages.dev](https://service-framework-weather.pages.dev)**

package/dist/index.d.ts

@@ -1,18 +1,9 @@
-import type { IScheduler } from "@realitycollective/service-framework";
-export interface AnimationLoopHostLike {
-    setAnimationLoop(callback: ((timestamp: number) => void) | null): void;
-}
-export interface ThreeRenderLoopBridgeOptions {
-    readonly scheduler: IScheduler;
-    readonly host: AnimationLoopHostLike;
-}
-export declare class ThreeRenderLoopBridge {
-    private readonly options;
-    private animationLoopBound;
-    private frame;
-    private lastTimestamp;
-    constructor(options: ThreeRenderLoopBridgeOptions);
-    start(): void;
-    stop(): void;
-    dispose(): void;
-}
+/**
+ * Public entry point of the three.js binding: the render-loop bridge, and the
+ * WebXR runtime adapter that gives a three.js or desktop app the same
+ * `RuntimeAdapter` surface the IWSDK binding has.
+ */
+export { FIRST_FRAME_DELTA_MS, ThreeRenderLoopBridge } from "./three-render-loop-bridge.js";
+export type { AnimationLoopHostLike, ThreeRenderLoopBridgeOptions } from "./three-render-loop-bridge.js";
+export { WebXRRuntimeAdapter } from "./webxr-runtime-adapter.js";
+export type { WebXREventListener, WebXRManagerEventType, WebXRManagerLike, WebXRRuntimeAdapterOptions, WebXRSessionEventType, WebXRSessionLike, WebXRSystemLike } from "./webxr-runtime-adapter.js";

package/dist/index.js

@@ -1,36 +1,8 @@
-export class ThreeRenderLoopBridge {
-    options;
-    animationLoopBound = false;
-    frame = 0;
-    lastTimestamp = 0;
-    constructor(options) {
-        this.options = options;
-    }
-    start() {
-        if (this.animationLoopBound) {
-            return;
-        }
-        this.animationLoopBound = true;
-        this.options.host.setAnimationLoop((timestamp) => {
-            const context = {
-                timestamp,
-                deltaTime: this.lastTimestamp === 0 ? 16 : timestamp - this.lastTimestamp,
-                frame: ++this.frame,
-                source: "three"
-            };
-            this.lastTimestamp = timestamp;
-            this.options.scheduler.emit("renderTick", context);
-        });
-    }
-    stop() {
-        if (!this.animationLoopBound) {
-            return;
-        }
-        this.animationLoopBound = false;
-        this.options.host.setAnimationLoop(null);
-    }
-    dispose() {
-        this.stop();
-    }
-}
+/**
+ * Public entry point of the three.js binding: the render-loop bridge, and the
+ * WebXR runtime adapter that gives a three.js or desktop app the same
+ * `RuntimeAdapter` surface the IWSDK binding has.
+ */
+export { FIRST_FRAME_DELTA_MS, ThreeRenderLoopBridge } from "./three-render-loop-bridge.js";
+export { WebXRRuntimeAdapter } from "./webxr-runtime-adapter.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,MAAM,OAAO,qBAAqB;IAMb;IALX,kBAAkB,GAAG,KAAK,CAAC;IAC3B,KAAK,GAAG,CAAC,CAAC;IACV,aAAa,GAAG,CAAC,CAAC;IAE1B,YACmB,OAAqC;QAArC,YAAO,GAAP,OAAO,CAA8B;IACrD,CAAC;IAEG,KAAK;QACV,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAE/B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,SAAS,EAAE,EAAE;YAC/C,MAAM,OAAO,GAAqB;gBAChC,SAAS;gBACT,SAAS,EAAE,IAAI,CAAC,aAAa,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,aAAa;gBACzE,KAAK,EAAE,EAAE,IAAI,CAAC,KAAK;gBACnB,MAAM,EAAE,OAAO;aAChB,CAAC;YAEF,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;YAC/B,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;IACL,CAAC;IAEM,IAAI;QACT,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC7B,OAAO;QACT,CAAC;QAED,IAAI,CAAC,kBAAkB,GAAG,KAAK,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAEM,OAAO;QACZ,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;CACF","sourcesContent":["/* v8 ignore file */\nimport type { IScheduler, LifecycleContext } from \"@realitycollective/service-framework\";\n\nexport interface AnimationLoopHostLike {\n  setAnimationLoop(callback: ((timestamp: number) => void) | null): void;\n}\n\nexport interface ThreeRenderLoopBridgeOptions {\n  readonly scheduler: IScheduler;\n  readonly host: AnimationLoopHostLike;\n}\n\nexport class ThreeRenderLoopBridge {\n  private animationLoopBound = false;\n  private frame = 0;\n  private lastTimestamp = 0;\n\n  public constructor(\n    private readonly options: ThreeRenderLoopBridgeOptions\n  ) {}\n\n  public start(): void {\n    if (this.animationLoopBound) {\n      return;\n    }\n\n    this.animationLoopBound = true;\n\n    this.options.host.setAnimationLoop((timestamp) => {\n      const context: LifecycleContext = {\n        timestamp,\n        deltaTime: this.lastTimestamp === 0 ? 16 : timestamp - this.lastTimestamp,\n        frame: ++this.frame,\n        source: \"three\"\n      };\n\n      this.lastTimestamp = timestamp;\n      this.options.scheduler.emit(\"renderTick\", context);\n    });\n  }\n\n  public stop(): void {\n    if (!this.animationLoopBound) {\n      return;\n    }\n\n    this.animationLoopBound = false;\n    this.options.host.setAnimationLoop(null);\n  }\n\n  public dispose(): void {\n    this.stop();\n  }\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAM5F,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC","sourcesContent":["/**\n * Public entry point of the three.js binding: the render-loop bridge, and the\n * WebXR runtime adapter that gives a three.js or desktop app the same\n * `RuntimeAdapter` surface the IWSDK binding has.\n */\nexport { FIRST_FRAME_DELTA_MS, ThreeRenderLoopBridge } from \"./three-render-loop-bridge.js\";\nexport type {\n  AnimationLoopHostLike,\n  ThreeRenderLoopBridgeOptions\n} from \"./three-render-loop-bridge.js\";\n\nexport { WebXRRuntimeAdapter } from \"./webxr-runtime-adapter.js\";\nexport type {\n  WebXREventListener,\n  WebXRManagerEventType,\n  WebXRManagerLike,\n  WebXRRuntimeAdapterOptions,\n  WebXRSessionEventType,\n  WebXRSessionLike,\n  WebXRSystemLike\n} from \"./webxr-runtime-adapter.js\";\n"]}

package/dist/three-render-loop-bridge.d.ts

@@ -0,0 +1,28 @@
+/**
+ * three.js render-loop bridge: connects `renderer.setAnimationLoop()` to the
+ * framework's `renderTick` scheduler channel.
+ *
+ * The host is structural - anything with `setAnimationLoop` - so this package
+ * never imports `three` and builds with no renderer, no WebGL and no DOM.
+ */
+import type { IScheduler } from "@realitycollective/service-framework";
+/** The slice of a three.js renderer the bridge and the adapter drive. */
+export interface AnimationLoopHostLike {
+    setAnimationLoop(callback: ((timestamp: number) => void) | null): void;
+}
+export interface ThreeRenderLoopBridgeOptions {
+    readonly scheduler: IScheduler;
+    readonly host: AnimationLoopHostLike;
+}
+/** Delta reported for the first frame, where there is no previous timestamp. */
+export declare const FIRST_FRAME_DELTA_MS = 16;
+export declare class ThreeRenderLoopBridge {
+    private readonly options;
+    private animationLoopBound;
+    private frame;
+    private lastTimestamp;
+    constructor(options: ThreeRenderLoopBridgeOptions);
+    start(): void;
+    stop(): void;
+    dispose(): void;
+}

package/dist/three-render-loop-bridge.js

@@ -0,0 +1,38 @@
+/** Delta reported for the first frame, where there is no previous timestamp. */
+export const FIRST_FRAME_DELTA_MS = 16;
+export class ThreeRenderLoopBridge {
+    options;
+    animationLoopBound = false;
+    frame = 0;
+    lastTimestamp = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        if (this.animationLoopBound) {
+            return;
+        }
+        this.animationLoopBound = true;
+        this.options.host.setAnimationLoop((timestamp) => {
+            const context = {
+                timestamp,
+                deltaTime: this.lastTimestamp === 0 ? FIRST_FRAME_DELTA_MS : timestamp - this.lastTimestamp,
+                frame: ++this.frame,
+                source: "three"
+            };
+            this.lastTimestamp = timestamp;
+            this.options.scheduler.emit("renderTick", context);
+        });
+    }
+    stop() {
+        if (!this.animationLoopBound) {
+            return;
+        }
+        this.animationLoopBound = false;
+        this.options.host.setAnimationLoop(null);
+    }
+    dispose() {
+        this.stop();
+    }
+}
+//# sourceMappingURL=three-render-loop-bridge.js.map

package/dist/three-render-loop-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"three-render-loop-bridge.js","sourceRoot":"","sources":["../src/three-render-loop-bridge.ts"],"names":[],"mappings":"AAmBA,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC,MAAM,OAAO,qBAAqB;IAMb;IALX,kBAAkB,GAAG,KAAK,CAAC;IAC3B,KAAK,GAAG,CAAC,CAAC;IACV,aAAa,GAAG,CAAC,CAAC;IAE1B,YACmB,OAAqC;QAArC,YAAO,GAAP,OAAO,CAA8B;IACrD,CAAC;IAEG,KAAK;QACV,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAE/B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,SAAS,EAAE,EAAE;YAC/C,MAAM,OAAO,GAAqB;gBAChC,SAAS;gBACT,SAAS,EAAE,IAAI,CAAC,aAAa,KAAK,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,aAAa;gBAC3F,KAAK,EAAE,EAAE,IAAI,CAAC,KAAK;gBACnB,MAAM,EAAE,OAAO;aAChB,CAAC;YAEF,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;YAC/B,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;IACL,CAAC;IAEM,IAAI;QACT,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC7B,OAAO;QACT,CAAC;QAED,IAAI,CAAC,kBAAkB,GAAG,KAAK,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAEM,OAAO;QACZ,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;CACF","sourcesContent":["/**\n * three.js render-loop bridge: connects `renderer.setAnimationLoop()` to the\n * framework's `renderTick` scheduler channel.\n *\n * The host is structural - anything with `setAnimationLoop` - so this package\n * never imports `three` and builds with no renderer, no WebGL and no DOM.\n */\nimport type { IScheduler, LifecycleContext } from \"@realitycollective/service-framework\";\n\n/** The slice of a three.js renderer the bridge and the adapter drive. */\nexport interface AnimationLoopHostLike {\n  setAnimationLoop(callback: ((timestamp: number) => void) | null): void;\n}\n\nexport interface ThreeRenderLoopBridgeOptions {\n  readonly scheduler: IScheduler;\n  readonly host: AnimationLoopHostLike;\n}\n\n/** Delta reported for the first frame, where there is no previous timestamp. */\nexport const FIRST_FRAME_DELTA_MS = 16;\n\nexport class ThreeRenderLoopBridge {\n  private animationLoopBound = false;\n  private frame = 0;\n  private lastTimestamp = 0;\n\n  public constructor(\n    private readonly options: ThreeRenderLoopBridgeOptions\n  ) {}\n\n  public start(): void {\n    if (this.animationLoopBound) {\n      return;\n    }\n\n    this.animationLoopBound = true;\n\n    this.options.host.setAnimationLoop((timestamp) => {\n      const context: LifecycleContext = {\n        timestamp,\n        deltaTime: this.lastTimestamp === 0 ? FIRST_FRAME_DELTA_MS : timestamp - this.lastTimestamp,\n        frame: ++this.frame,\n        source: \"three\"\n      };\n\n      this.lastTimestamp = timestamp;\n      this.options.scheduler.emit(\"renderTick\", context);\n    });\n  }\n\n  public stop(): void {\n    if (!this.animationLoopBound) {\n      return;\n    }\n\n    this.animationLoopBound = false;\n    this.options.host.setAnimationLoop(null);\n  }\n\n  public dispose(): void {\n    this.stop();\n  }\n}\n"]}

package/dist/webxr-runtime-adapter.d.ts

@@ -0,0 +1,180 @@
+/**
+ * WebXR implementation of {@link RuntimeAdapter}, for a three.js app or any
+ * other page that owns its own renderer.
+ *
+ * The IWSDK binding gets its adapter from IWSDK. Everything else - a plain
+ * three.js app, a desktop build with no headset - had nothing, so a service
+ * written against `RuntimeAdapter` could not be hosted there. This adapter
+ * closes that gap: it orchestrates the entry points the platform already
+ * provides (`navigator.xr` for session negotiation, `renderer.xr` for the
+ * session the renderer presents, `setAnimationLoop` for frames) and publishes
+ * them through the same seam. It renders nothing, plays nothing and owns no
+ * scene state.
+ *
+ * Every host type here is structural, so this package still imports neither
+ * `three` nor any WebXR type, and the adapter unit-tests headless.
+ */
+import { type AdapterCapabilities, type CapabilitiesListener, type CapabilitySessionLike, type FrameListener, type IScheduler, type RuntimeAdapter, type SessionFacet, type SessionMode, type Unsubscribe } from "@realitycollective/service-framework";
+import { type AnimationLoopHostLike } from "./three-render-loop-bridge.js";
+/** The events an `XRSession` raises that this adapter listens for. */
+export type WebXRSessionEventType = "end" | "visibilitychange" | "inputsourceschange";
+/** The events three.js's `WebXRManager` raises that this adapter listens for. */
+export type WebXRManagerEventType = "sessionstart" | "sessionend";
+/** Host event callback. The adapter reads the host, not the event object. */
+export type WebXREventListener = (event?: unknown) => void;
+/**
+ * The slice of an `XRSession` the adapter reads. It extends the core's
+ * {@link CapabilitySessionLike}, so a live session goes straight to
+ * `deriveCapabilities` with no mapping.
+ */
+export interface WebXRSessionLike extends CapabilitySessionLike {
+    /** Ends the session. The `end` event is what the adapter acts on. */
+    end(): Promise<void>;
+    /** `"visible"`, `"visible-blurred"` or `"hidden"` on a live session. */
+    readonly visibilityState?: string;
+    addEventListener(type: WebXRSessionEventType, listener: WebXREventListener): void;
+    removeEventListener(type: WebXRSessionEventType, listener: WebXREventListener): void;
+}
+/** The slice of `navigator.xr` the session facet negotiates through. */
+export interface WebXRSystemLike {
+    isSessionSupported(mode: string): Promise<boolean>;
+    requestSession(mode: string, init?: unknown): Promise<WebXRSessionLike>;
+}
+/** The slice of a three.js `renderer.xr` (`WebXRManager`) the adapter drives. */
+export interface WebXRManagerLike {
+    /** Hands the renderer the session it should present. */
+    setSession(session: WebXRSessionLike): Promise<void> | void;
+    /** The session the renderer is presenting, or null in 2D. */
+    getSession(): WebXRSessionLike | null;
+    addEventListener(type: WebXRManagerEventType, listener: WebXREventListener): void;
+    removeEventListener(type: WebXRManagerEventType, listener: WebXREventListener): void;
+}
+export interface WebXRRuntimeAdapterOptions {
+    /** `renderer.xr` - the renderer's WebXR manager. */
+    readonly xr: WebXRManagerLike;
+    /**
+     * `navigator.xr`. Defaults to the global when omitted, and to `null` where
+     * there is no global, which is what a Node test sees. A null system reports
+     * every session request as `"unsupported"`.
+     */
+    readonly xrSystem?: WebXRSystemLike | null;
+    /**
+     * The renderer, or anything else with `setAnimationLoop`. Given one, the
+     * adapter owns the loop: {@link WebXRRuntimeAdapter.start} binds it and each
+     * callback becomes a frame. Omit it to drive frames yourself with
+     * {@link WebXRRuntimeAdapter.emitFrame}.
+     */
+    readonly host?: AnimationLoopHostLike;
+    /**
+     * Given a scheduler, each owned frame also emits the `renderTick` channel
+     * with `source: "three"`, exactly as `ThreeRenderLoopBridge` does, so an app
+     * needs one loop owner rather than two.
+     */
+    readonly scheduler?: IScheduler;
+    /**
+     * Supplies the `XRSessionInit` for a mode - required and optional features.
+     * Called once per request; the default sends no init at all.
+     */
+    readonly sessionInit?: (mode: SessionMode) => unknown;
+}
+export declare class WebXRRuntimeAdapter implements RuntimeAdapter {
+    private readonly frameListeners;
+    private readonly capabilitiesListeners;
+    private readonly stateListeners;
+    private readonly visibilityListeners;
+    private readonly endWaiters;
+    private readonly xr;
+    private readonly xrSystem;
+    private readonly host;
+    private readonly scheduler;
+    private readonly sessionInit;
+    private derived;
+    private overrides;
+    private capabilities;
+    private sessionState;
+    private boundSession;
+    private sessionListeners;
+    private animationLoopBound;
+    private frame;
+    private lastTimestamp;
+    private readonly onManagerSessionStart;
+    private readonly onManagerSessionEnd;
+    /** Session lifecycle over `navigator.xr` and the renderer's XR manager. */
+    readonly session: SessionFacet;
+    constructor(options: WebXRRuntimeAdapterOptions);
+    onFrame(listener: FrameListener): Unsubscribe;
+    getCapabilities(): AdapterCapabilities;
+    onCapabilitiesChange(listener: CapabilitiesListener): Unsubscribe;
+    /** The session the renderer is presenting, or null in 2D. */
+    getSession(): WebXRSessionLike | null;
+    /**
+     * Bind the animation loop, if this adapter was given a host. Each callback
+     * becomes one {@link FrameInfo} and, where a scheduler was supplied, one
+     * `renderTick`. With no host this does nothing: the app owns the loop and
+     * calls {@link WebXRRuntimeAdapter.emitFrame} itself.
+     *
+     * three.js routes `setAnimationLoop` through the session's own
+     * `requestAnimationFrame` while presenting, so one call covers both the 2D
+     * page and the headset.
+     */
+    start(): void;
+    /** Release the animation loop. Safe to call when it was never bound. */
+    stop(): void;
+    /** Push one frame to every subscriber. Call this when you own the loop. */
+    emitFrame(timestamp: number, delta: number): void;
+    /**
+     * Re-read the renderer's session and publish any capability change. The
+     * adapter does this itself on every session and input-source event; call it
+     * directly after the host enables a feature mid-session, or after a host that
+     * raises no events changes what it presents.
+     */
+    refreshCapabilities(): void;
+    /**
+     * Force capability flags regardless of what the session reports. Overrides
+     * are a layer on top of the derived values: they win for as long as they are
+     * set, survive every later derivation, and are dropped only by
+     * {@link WebXRRuntimeAdapter.clearCapabilityOverrides} or
+     * {@link WebXRRuntimeAdapter.dispose}.
+     */
+    setCapabilities(capabilities: Partial<AdapterCapabilities>): void;
+    /** Drop every manual override and fall back to the derived capabilities. */
+    clearCapabilityOverrides(): void;
+    /**
+     * Release everything the adapter holds: the animation loop, both sets of host
+     * event listeners, any in-flight `end()`, the manual overrides and every
+     * listener. It does not end the session - the app owns that decision.
+     */
+    dispose(): void;
+    private handleAnimationFrame;
+    /**
+     * Subscribe to one session's own events. The listeners close over the session
+     * they belong to, so nothing here has to re-check which session is live.
+     */
+    private attachSession;
+    private detachSession;
+    private handleSessionStart;
+    /**
+     * One session ending raises both the session's `end` event and the manager's
+     * `sessionend`, so this runs twice per session and is written to be
+     * idempotent.
+     */
+    private handleSessionEnd;
+    private updateDerived;
+    private publishCapabilities;
+    private requestSession;
+    /**
+     * Negotiate the session and hand it to the renderer. Nothing here throws at
+     * the caller: a headset that is absent, refused or broken is a normal runtime
+     * condition, so every outcome comes back as a {@link SessionResult}.
+     *
+     * The request's own features are merged over the `sessionInit` hook's result
+     * by the core's `mergeSessionInit`, so they add to the app's defaults rather
+     * than replacing them. A request that names none passes the hook's result
+     * through untouched.
+     */
+    private openSession;
+    private endSession;
+    private settleEndWaiters;
+    private notifyVisibility;
+    private setSessionState;
+}

package/dist/webxr-runtime-adapter.js

@@ -0,0 +1,393 @@
+/**
+ * WebXR implementation of {@link RuntimeAdapter}, for a three.js app or any
+ * other page that owns its own renderer.
+ *
+ * The IWSDK binding gets its adapter from IWSDK. Everything else - a plain
+ * three.js app, a desktop build with no headset - had nothing, so a service
+ * written against `RuntimeAdapter` could not be hosted there. This adapter
+ * closes that gap: it orchestrates the entry points the platform already
+ * provides (`navigator.xr` for session negotiation, `renderer.xr` for the
+ * session the renderer presents, `setAnimationLoop` for frames) and publishes
+ * them through the same seam. It renders nothing, plays nothing and owns no
+ * scene state.
+ *
+ * Every host type here is structural, so this package still imports neither
+ * `three` nor any WebXR type, and the adapter unit-tests headless.
+ */
+import { DEFAULT_CAPABILITIES, DEFAULT_SESSION_TIMEOUT_MS, deriveCapabilities, mergeSessionInit, } from "@realitycollective/service-framework";
+import { FIRST_FRAME_DELTA_MS } from "./three-render-loop-bridge.js";
+const SESSION_VISIBILITY_VALUES = new Set([
+    "visible",
+    "visible-blurred",
+    "hidden",
+]);
+/**
+ * Map `XRSession.visibilityState` onto the facet's vocabulary. An unrecognised
+ * value is reported as `"hidden"`, because treating an unknown state as visible
+ * would keep game logic running when it should not.
+ */
+function toSessionVisibility(value) {
+    if (typeof value === "string" && SESSION_VISIBILITY_VALUES.has(value)) {
+        return value;
+    }
+    return "hidden";
+}
+/**
+ * WebXR reports a blocked request through the error name: `NotAllowedError`
+ * when the user or the permission prompt refused, `SecurityError` when the
+ * permissions policy did. Both are a refusal rather than a fault.
+ */
+function toFailureReason(error) {
+    const name = error?.name;
+    if (name === "NotAllowedError" || name === "SecurityError") {
+        return "denied";
+    }
+    return "error";
+}
+/** `navigator.xr`, read defensively: there is no navigator in a Node test. */
+function defaultXRSystem() {
+    const globalNavigator = globalThis.navigator;
+    return globalNavigator?.xr ?? null;
+}
+export class WebXRRuntimeAdapter {
+    frameListeners = new Set();
+    capabilitiesListeners = new Set();
+    stateListeners = new Set();
+    visibilityListeners = new Set();
+    endWaiters = new Set();
+    xr;
+    xrSystem;
+    host;
+    scheduler;
+    sessionInit;
+    derived = DEFAULT_CAPABILITIES;
+    overrides = {};
+    capabilities = DEFAULT_CAPABILITIES;
+    sessionState = "none";
+    boundSession = null;
+    sessionListeners = [];
+    animationLoopBound = false;
+    frame = 0;
+    lastTimestamp = 0;
+    onManagerSessionStart = () => {
+        this.handleSessionStart();
+    };
+    onManagerSessionEnd = () => {
+        this.handleSessionEnd();
+    };
+    /** Session lifecycle over `navigator.xr` and the renderer's XR manager. */
+    session = {
+        getState: () => this.sessionState,
+        request: (mode, options) => this.requestSession(mode, options),
+        end: () => this.endSession(),
+        onStateChange: (listener) => {
+            this.stateListeners.add(listener);
+            return () => {
+                this.stateListeners.delete(listener);
+            };
+        },
+        onVisibilityChange: (listener) => {
+            this.visibilityListeners.add(listener);
+            return () => {
+                this.visibilityListeners.delete(listener);
+            };
+        },
+    };
+    constructor(options) {
+        this.xr = options.xr;
+        this.xrSystem = options.xrSystem === undefined ? defaultXRSystem() : options.xrSystem;
+        this.host = options.host;
+        this.scheduler = options.scheduler;
+        this.sessionInit = options.sessionInit;
+        this.xr.addEventListener("sessionstart", this.onManagerSessionStart);
+        this.xr.addEventListener("sessionend", this.onManagerSessionEnd);
+        const session = this.xr.getSession();
+        if (session) {
+            this.attachSession(session);
+            this.sessionState = "active";
+        }
+        this.derived = deriveCapabilities(session);
+        this.capabilities = this.derived;
+    }
+    onFrame(listener) {
+        this.frameListeners.add(listener);
+        return () => {
+            this.frameListeners.delete(listener);
+        };
+    }
+    getCapabilities() {
+        return this.capabilities;
+    }
+    onCapabilitiesChange(listener) {
+        this.capabilitiesListeners.add(listener);
+        return () => {
+            this.capabilitiesListeners.delete(listener);
+        };
+    }
+    /** The session the renderer is presenting, or null in 2D. */
+    getSession() {
+        return this.boundSession;
+    }
+    /**
+     * Bind the animation loop, if this adapter was given a host. Each callback
+     * becomes one {@link FrameInfo} and, where a scheduler was supplied, one
+     * `renderTick`. With no host this does nothing: the app owns the loop and
+     * calls {@link WebXRRuntimeAdapter.emitFrame} itself.
+     *
+     * three.js routes `setAnimationLoop` through the session's own
+     * `requestAnimationFrame` while presenting, so one call covers both the 2D
+     * page and the headset.
+     */
+    start() {
+        if (this.animationLoopBound) {
+            return;
+        }
+        this.animationLoopBound = true;
+        this.host?.setAnimationLoop((timestamp) => this.handleAnimationFrame(timestamp));
+    }
+    /** Release the animation loop. Safe to call when it was never bound. */
+    stop() {
+        if (!this.animationLoopBound) {
+            return;
+        }
+        this.animationLoopBound = false;
+        this.host?.setAnimationLoop(null);
+    }
+    /** Push one frame to every subscriber. Call this when you own the loop. */
+    emitFrame(timestamp, delta) {
+        const frame = { timestamp, delta };
+        this.frameListeners.forEach((listener) => listener(frame));
+    }
+    /**
+     * Re-read the renderer's session and publish any capability change. The
+     * adapter does this itself on every session and input-source event; call it
+     * directly after the host enables a feature mid-session, or after a host that
+     * raises no events changes what it presents.
+     */
+    refreshCapabilities() {
+        const session = this.xr.getSession();
+        if (session) {
+            this.attachSession(session);
+            this.updateDerived(session);
+            return;
+        }
+        if (this.boundSession) {
+            this.handleSessionEnd();
+            return;
+        }
+        this.updateDerived(null);
+    }
+    /**
+     * Force capability flags regardless of what the session reports. Overrides
+     * are a layer on top of the derived values: they win for as long as they are
+     * set, survive every later derivation, and are dropped only by
+     * {@link WebXRRuntimeAdapter.clearCapabilityOverrides} or
+     * {@link WebXRRuntimeAdapter.dispose}.
+     */
+    setCapabilities(capabilities) {
+        this.overrides = { ...this.overrides, ...capabilities };
+        this.publishCapabilities();
+    }
+    /** Drop every manual override and fall back to the derived capabilities. */
+    clearCapabilityOverrides() {
+        this.overrides = {};
+        this.publishCapabilities();
+    }
+    /**
+     * Release everything the adapter holds: the animation loop, both sets of host
+     * event listeners, any in-flight `end()`, the manual overrides and every
+     * listener. It does not end the session - the app owns that decision.
+     */
+    dispose() {
+        this.stop();
+        this.xr.removeEventListener("sessionstart", this.onManagerSessionStart);
+        this.xr.removeEventListener("sessionend", this.onManagerSessionEnd);
+        this.detachSession();
+        this.settleEndWaiters();
+        this.overrides = {};
+        this.frameListeners.clear();
+        this.capabilitiesListeners.clear();
+        this.stateListeners.clear();
+        this.visibilityListeners.clear();
+    }
+    handleAnimationFrame(timestamp) {
+        const deltaMs = this.lastTimestamp === 0 ? FIRST_FRAME_DELTA_MS : timestamp - this.lastTimestamp;
+        this.lastTimestamp = timestamp;
+        this.frame += 1;
+        // `FrameInfo.delta` is seconds; the scheduler's `LifecycleContext` is in
+        // milliseconds, which is the unit `ThreeRenderLoopBridge` already emits.
+        this.emitFrame(timestamp, deltaMs / 1000);
+        const context = {
+            timestamp,
+            deltaTime: deltaMs,
+            frame: this.frame,
+            source: "three",
+        };
+        this.scheduler?.emit("renderTick", context);
+    }
+    /**
+     * Subscribe to one session's own events. The listeners close over the session
+     * they belong to, so nothing here has to re-check which session is live.
+     */
+    attachSession(session) {
+        if (session === this.boundSession) {
+            return;
+        }
+        this.detachSession();
+        this.boundSession = session;
+        this.sessionListeners = [
+            { type: "end", listener: () => this.handleSessionEnd() },
+            {
+                type: "visibilitychange",
+                listener: () => this.notifyVisibility(toSessionVisibility(session.visibilityState)),
+            },
+            { type: "inputsourceschange", listener: () => this.updateDerived(session) },
+        ];
+        for (const entry of this.sessionListeners) {
+            session.addEventListener(entry.type, entry.listener);
+        }
+    }
+    detachSession() {
+        const session = this.boundSession;
+        if (!session) {
+            return;
+        }
+        for (const entry of this.sessionListeners) {
+            session.removeEventListener(entry.type, entry.listener);
+        }
+        this.sessionListeners = [];
+        this.boundSession = null;
+    }
+    handleSessionStart() {
+        const session = this.xr.getSession();
+        if (!session) {
+            return;
+        }
+        this.attachSession(session);
+        this.setSessionState("active");
+        this.updateDerived(session);
+        this.notifyVisibility(toSessionVisibility(session.visibilityState));
+    }
+    /**
+     * One session ending raises both the session's `end` event and the manager's
+     * `sessionend`, so this runs twice per session and is written to be
+     * idempotent.
+     */
+    handleSessionEnd() {
+        if (!this.boundSession && this.sessionState === "none") {
+            return;
+        }
+        this.detachSession();
+        this.setSessionState("none");
+        this.updateDerived(null);
+        this.notifyVisibility("non-immersive");
+        this.settleEndWaiters();
+    }
+    updateDerived(session) {
+        this.derived = deriveCapabilities(session);
+        this.publishCapabilities();
+    }
+    publishCapabilities() {
+        const next = { ...this.derived, ...this.overrides };
+        const current = this.capabilities;
+        if (next.immersive === current.immersive &&
+            next.handTracking === current.handTracking &&
+            next.planeDetection === current.planeDetection &&
+            next.passthrough === current.passthrough &&
+            next.environmentBlendMode === current.environmentBlendMode) {
+            return;
+        }
+        this.capabilities = next;
+        this.capabilitiesListeners.forEach((listener) => listener(next));
+    }
+    async requestSession(mode, options) {
+        if (this.sessionState === "active") {
+            return { ok: true };
+        }
+        const system = this.xrSystem;
+        if (!system) {
+            return { ok: false, reason: "unsupported" };
+        }
+        const timeoutMs = options?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+        this.setSessionState("requesting");
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve({ ok: false, reason: "timeout" }), timeoutMs);
+        });
+        const result = await Promise.race([this.openSession(system, mode, options), timeout]);
+        clearTimeout(timer);
+        if (!result.ok) {
+            this.setSessionState("none");
+            return result;
+        }
+        this.setSessionState("active");
+        return result;
+    }
+    /**
+     * Negotiate the session and hand it to the renderer. Nothing here throws at
+     * the caller: a headset that is absent, refused or broken is a normal runtime
+     * condition, so every outcome comes back as a {@link SessionResult}.
+     *
+     * The request's own features are merged over the `sessionInit` hook's result
+     * by the core's `mergeSessionInit`, so they add to the app's defaults rather
+     * than replacing them. A request that names none passes the hook's result
+     * through untouched.
+     */
+    async openSession(system, mode, options) {
+        try {
+            const supported = await system.isSessionSupported(mode);
+            if (!supported) {
+                return { ok: false, reason: "unsupported" };
+            }
+            const init = mergeSessionInit(this.sessionInit?.(mode), options);
+            const session = await system.requestSession(mode, init);
+            await this.xr.setSession(session);
+            // A manager that raises `sessionstart` has already attached this session;
+            // one that does not is attached here, so both host styles behave alike.
+            this.attachSession(session);
+            this.updateDerived(session);
+            return { ok: true };
+        }
+        catch (error) {
+            return { ok: false, reason: toFailureReason(error), error };
+        }
+    }
+    async endSession() {
+        const session = this.boundSession;
+        if (!session) {
+            return;
+        }
+        this.setSessionState("ending");
+        const ended = new Promise((resolve) => {
+            this.endWaiters.add(resolve);
+        });
+        try {
+            await session.end();
+        }
+        catch {
+            // Ending is best effort. The `end` event, not this promise, is what the
+            // adapter acts on, and a host that refuses still has to be reported.
+        }
+        // The event has normally arrived by now and this is a no-op. A host that
+        // raises none would otherwise leave the caller waiting forever, so the
+        // settled `end()` call is the fallback signal.
+        this.handleSessionEnd();
+        await ended;
+    }
+    settleEndWaiters() {
+        const waiters = Array.from(this.endWaiters);
+        this.endWaiters.clear();
+        waiters.forEach((resolve) => resolve());
+    }
+    notifyVisibility(visibility) {
+        this.visibilityListeners.forEach((listener) => listener(visibility));
+    }
+    setSessionState(state) {
+        if (this.sessionState === state) {
+            return;
+        }
+        this.sessionState = state;
+        this.stateListeners.forEach((listener) => listener(state));
+    }
+}
+//# sourceMappingURL=webxr-runtime-adapter.js.map

package/dist/webxr-runtime-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webxr-runtime-adapter.js","sourceRoot":"","sources":["../src/webxr-runtime-adapter.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * WebXR implementation of {@link RuntimeAdapter}, for a three.js app or any\n * other page that owns its own renderer.\n *\n * The IWSDK binding gets its adapter from IWSDK. Everything else - a plain\n * three.js app, a desktop build with no headset - had nothing, so a service\n * written against `RuntimeAdapter` could not be hosted there. This adapter\n * closes that gap: it orchestrates the entry points the platform already\n * provides (`navigator.xr` for session negotiation, `renderer.xr` for the\n * session the renderer presents, `setAnimationLoop` for frames) and publishes\n * them through the same seam. It renders nothing, plays nothing and owns no\n * scene state.\n *\n * Every host type here is structural, so this package still imports neither\n * `three` nor any WebXR type, and the adapter unit-tests headless.\n */\nimport {\n  DEFAULT_CAPABILITIES,\n  DEFAULT_SESSION_TIMEOUT_MS,\n  deriveCapabilities,\n  mergeSessionInit,\n  type AdapterCapabilities,\n  type CapabilitiesListener,\n  type CapabilitySessionLike,\n  type FrameInfo,\n  type FrameListener,\n  type IScheduler,\n  type LifecycleContext,\n  type RuntimeAdapter,\n  type SessionFacet,\n  type SessionFailureReason,\n  type SessionMode,\n  type SessionRequestOptions,\n  type SessionResult,\n  type SessionState,\n  type SessionVisibility,\n  type Unsubscribe,\n} from \"@realitycollective/service-framework\";\nimport { FIRST_FRAME_DELTA_MS, type AnimationLoopHostLike } from \"./three-render-loop-bridge.js\";\n\n/** The events an `XRSession` raises that this adapter listens for. */\nexport type WebXRSessionEventType = \"end\" | \"visibilitychange\" | \"inputsourceschange\";\n\n/** The events three.js's `WebXRManager` raises that this adapter listens for. */\nexport type WebXRManagerEventType = \"sessionstart\" | \"sessionend\";\n\n/** Host event callback. The adapter reads the host, not the event object. */\nexport type WebXREventListener = (event?: unknown) => void;\n\n/**\n * The slice of an `XRSession` the adapter reads. It extends the core's\n * {@link CapabilitySessionLike}, so a live session goes straight to\n * `deriveCapabilities` with no mapping.\n */\nexport interface WebXRSessionLike extends CapabilitySessionLike {\n  /** Ends the session. The `end` event is what the adapter acts on. */\n  end(): Promise<void>;\n  /** `\"visible\"`, `\"visible-blurred\"` or `\"hidden\"` on a live session. */\n  readonly visibilityState?: string;\n  addEventListener(type: WebXRSessionEventType, listener: WebXREventListener): void;\n  removeEventListener(type: WebXRSessionEventType, listener: WebXREventListener): void;\n}\n\n/** The slice of `navigator.xr` the session facet negotiates through. */\nexport interface WebXRSystemLike {\n  isSessionSupported(mode: string): Promise<boolean>;\n  requestSession(mode: string, init?: unknown): Promise<WebXRSessionLike>;\n}\n\n/** The slice of a three.js `renderer.xr` (`WebXRManager`) the adapter drives. */\nexport interface WebXRManagerLike {\n  /** Hands the renderer the session it should present. */\n  setSession(session: WebXRSessionLike): Promise<void> | void;\n  /** The session the renderer is presenting, or null in 2D. */\n  getSession(): WebXRSessionLike | null;\n  addEventListener(type: WebXRManagerEventType, listener: WebXREventListener): void;\n  removeEventListener(type: WebXRManagerEventType, listener: WebXREventListener): void;\n}\n\nexport interface WebXRRuntimeAdapterOptions {\n  /** `renderer.xr` - the renderer's WebXR manager. */\n  readonly xr: WebXRManagerLike;\n  /**\n   * `navigator.xr`. Defaults to the global when omitted, and to `null` where\n   * there is no global, which is what a Node test sees. A null system reports\n   * every session request as `\"unsupported\"`.\n   */\n  readonly xrSystem?: WebXRSystemLike | null;\n  /**\n   * The renderer, or anything else with `setAnimationLoop`. Given one, the\n   * adapter owns the loop: {@link WebXRRuntimeAdapter.start} binds it and each\n   * callback becomes a frame. Omit it to drive frames yourself with\n   * {@link WebXRRuntimeAdapter.emitFrame}.\n   */\n  readonly host?: AnimationLoopHostLike;\n  /**\n   * Given a scheduler, each owned frame also emits the `renderTick` channel\n   * with `source: \"three\"`, exactly as `ThreeRenderLoopBridge` does, so an app\n   * needs one loop owner rather than two.\n   */\n  readonly scheduler?: IScheduler;\n  /**\n   * Supplies the `XRSessionInit` for a mode - required and optional features.\n   * Called once per request; the default sends no init at all.\n   */\n  readonly sessionInit?: (mode: SessionMode) => unknown;\n}\n\ntype SessionStateListener = (state: SessionState) => void;\ntype SessionVisibilityListener = (visibility: SessionVisibility) => void;\n\nconst SESSION_VISIBILITY_VALUES: ReadonlySet<string> = new Set([\n  \"visible\",\n  \"visible-blurred\",\n  \"hidden\",\n]);\n\n/**\n * Map `XRSession.visibilityState` onto the facet's vocabulary. An unrecognised\n * value is reported as `\"hidden\"`, because treating an unknown state as visible\n * would keep game logic running when it should not.\n */\nfunction toSessionVisibility(value: unknown): SessionVisibility {\n  if (typeof value === \"string\" && SESSION_VISIBILITY_VALUES.has(value)) {\n    return value as SessionVisibility;\n  }\n\n  return \"hidden\";\n}\n\n/**\n * WebXR reports a blocked request through the error name: `NotAllowedError`\n * when the user or the permission prompt refused, `SecurityError` when the\n * permissions policy did. Both are a refusal rather than a fault.\n */\nfunction toFailureReason(error: unknown): SessionFailureReason {\n  const name = (error as { readonly name?: unknown } | null | undefined)?.name;\n\n  if (name === \"NotAllowedError\" || name === \"SecurityError\") {\n    return \"denied\";\n  }\n\n  return \"error\";\n}\n\n/** `navigator.xr`, read defensively: there is no navigator in a Node test. */\nfunction defaultXRSystem(): WebXRSystemLike | null {\n  const globalNavigator = (globalThis as { navigator?: { xr?: WebXRSystemLike } }).navigator;\n\n  return globalNavigator?.xr ?? null;\n}\n\nexport class WebXRRuntimeAdapter implements RuntimeAdapter {\n  private readonly frameListeners = new Set<FrameListener>();\n  private readonly capabilitiesListeners = new Set<CapabilitiesListener>();\n  private readonly stateListeners = new Set<SessionStateListener>();\n  private readonly visibilityListeners = new Set<SessionVisibilityListener>();\n  private readonly endWaiters = new Set<() => void>();\n\n  private readonly xr: WebXRManagerLike;\n  private readonly xrSystem: WebXRSystemLike | null;\n  private readonly host: AnimationLoopHostLike | undefined;\n  private readonly scheduler: IScheduler | undefined;\n  private readonly sessionInit: ((mode: SessionMode) => unknown) | undefined;\n\n  private derived: AdapterCapabilities = DEFAULT_CAPABILITIES;\n  private overrides: Partial<AdapterCapabilities> = {};\n  private capabilities: AdapterCapabilities = DEFAULT_CAPABILITIES;\n  private sessionState: SessionState = \"none\";\n  private boundSession: WebXRSessionLike | null = null;\n  private sessionListeners: {\n    readonly type: WebXRSessionEventType;\n    readonly listener: WebXREventListener;\n  }[] = [];\n  private animationLoopBound = false;\n  private frame = 0;\n  private lastTimestamp = 0;\n\n  private readonly onManagerSessionStart: WebXREventListener = () => {\n    this.handleSessionStart();\n  };\n\n  private readonly onManagerSessionEnd: WebXREventListener = () => {\n    this.handleSessionEnd();\n  };\n\n  /** Session lifecycle over `navigator.xr` and the renderer's XR manager. */\n  public readonly session: SessionFacet = {\n    getState: () => this.sessionState,\n    request: (mode, options) => this.requestSession(mode, options),\n    end: () => this.endSession(),\n    onStateChange: (listener) => {\n      this.stateListeners.add(listener);\n      return () => {\n        this.stateListeners.delete(listener);\n      };\n    },\n    onVisibilityChange: (listener) => {\n      this.visibilityListeners.add(listener);\n      return () => {\n        this.visibilityListeners.delete(listener);\n      };\n    },\n  };\n\n  public constructor(options: WebXRRuntimeAdapterOptions) {\n    this.xr = options.xr;\n    this.xrSystem = options.xrSystem === undefined ? defaultXRSystem() : options.xrSystem;\n    this.host = options.host;\n    this.scheduler = options.scheduler;\n    this.sessionInit = options.sessionInit;\n\n    this.xr.addEventListener(\"sessionstart\", this.onManagerSessionStart);\n    this.xr.addEventListener(\"sessionend\", this.onManagerSessionEnd);\n\n    const session = this.xr.getSession();\n\n    if (session) {\n      this.attachSession(session);\n      this.sessionState = \"active\";\n    }\n\n    this.derived = deriveCapabilities(session);\n    this.capabilities = this.derived;\n  }\n\n  public onFrame(listener: FrameListener): Unsubscribe {\n    this.frameListeners.add(listener);\n    return () => {\n      this.frameListeners.delete(listener);\n    };\n  }\n\n  public getCapabilities(): AdapterCapabilities {\n    return this.capabilities;\n  }\n\n  public onCapabilitiesChange(listener: CapabilitiesListener): Unsubscribe {\n    this.capabilitiesListeners.add(listener);\n    return () => {\n      this.capabilitiesListeners.delete(listener);\n    };\n  }\n\n  /** The session the renderer is presenting, or null in 2D. */\n  public getSession(): WebXRSessionLike | null {\n    return this.boundSession;\n  }\n\n  /**\n   * Bind the animation loop, if this adapter was given a host. Each callback\n   * becomes one {@link FrameInfo} and, where a scheduler was supplied, one\n   * `renderTick`. With no host this does nothing: the app owns the loop and\n   * calls {@link WebXRRuntimeAdapter.emitFrame} itself.\n   *\n   * three.js routes `setAnimationLoop` through the session's own\n   * `requestAnimationFrame` while presenting, so one call covers both the 2D\n   * page and the headset.\n   */\n  public start(): void {\n    if (this.animationLoopBound) {\n      return;\n    }\n\n    this.animationLoopBound = true;\n    this.host?.setAnimationLoop((timestamp) => this.handleAnimationFrame(timestamp));\n  }\n\n  /** Release the animation loop. Safe to call when it was never bound. */\n  public stop(): void {\n    if (!this.animationLoopBound) {\n      return;\n    }\n\n    this.animationLoopBound = false;\n    this.host?.setAnimationLoop(null);\n  }\n\n  /** Push one frame to every subscriber. Call this when you own the loop. */\n  public emitFrame(timestamp: number, delta: number): void {\n    const frame: FrameInfo = { timestamp, delta };\n    this.frameListeners.forEach((listener) => listener(frame));\n  }\n\n  /**\n   * Re-read the renderer's session and publish any capability change. The\n   * adapter does this itself on every session and input-source event; call it\n   * directly after the host enables a feature mid-session, or after a host that\n   * raises no events changes what it presents.\n   */\n  public refreshCapabilities(): void {\n    const session = this.xr.getSession();\n\n    if (session) {\n      this.attachSession(session);\n      this.updateDerived(session);\n      return;\n    }\n\n    if (this.boundSession) {\n      this.handleSessionEnd();\n      return;\n    }\n\n    this.updateDerived(null);\n  }\n\n  /**\n   * Force capability flags regardless of what the session reports. Overrides\n   * are a layer on top of the derived values: they win for as long as they are\n   * set, survive every later derivation, and are dropped only by\n   * {@link WebXRRuntimeAdapter.clearCapabilityOverrides} or\n   * {@link WebXRRuntimeAdapter.dispose}.\n   */\n  public setCapabilities(capabilities: Partial<AdapterCapabilities>): void {\n    this.overrides = { ...this.overrides, ...capabilities };\n    this.publishCapabilities();\n  }\n\n  /** Drop every manual override and fall back to the derived capabilities. */\n  public clearCapabilityOverrides(): void {\n    this.overrides = {};\n    this.publishCapabilities();\n  }\n\n  /**\n   * Release everything the adapter holds: the animation loop, both sets of host\n   * event listeners, any in-flight `end()`, the manual overrides and every\n   * listener. It does not end the session - the app owns that decision.\n   */\n  public dispose(): void {\n    this.stop();\n    this.xr.removeEventListener(\"sessionstart\", this.onManagerSessionStart);\n    this.xr.removeEventListener(\"sessionend\", this.onManagerSessionEnd);\n    this.detachSession();\n    this.settleEndWaiters();\n\n    this.overrides = {};\n    this.frameListeners.clear();\n    this.capabilitiesListeners.clear();\n    this.stateListeners.clear();\n    this.visibilityListeners.clear();\n  }\n\n  private handleAnimationFrame(timestamp: number): void {\n    const deltaMs =\n      this.lastTimestamp === 0 ? FIRST_FRAME_DELTA_MS : timestamp - this.lastTimestamp;\n\n    this.lastTimestamp = timestamp;\n    this.frame += 1;\n\n    // `FrameInfo.delta` is seconds; the scheduler's `LifecycleContext` is in\n    // milliseconds, which is the unit `ThreeRenderLoopBridge` already emits.\n    this.emitFrame(timestamp, deltaMs / 1000);\n\n    const context: LifecycleContext = {\n      timestamp,\n      deltaTime: deltaMs,\n      frame: this.frame,\n      source: \"three\",\n    };\n\n    this.scheduler?.emit(\"renderTick\", context);\n  }\n\n  /**\n   * Subscribe to one session's own events. The listeners close over the session\n   * they belong to, so nothing here has to re-check which session is live.\n   */\n  private attachSession(session: WebXRSessionLike): void {\n    if (session === this.boundSession) {\n      return;\n    }\n\n    this.detachSession();\n    this.boundSession = session;\n    this.sessionListeners = [\n      { type: \"end\", listener: () => this.handleSessionEnd() },\n      {\n        type: \"visibilitychange\",\n        listener: () => this.notifyVisibility(toSessionVisibility(session.visibilityState)),\n      },\n      { type: \"inputsourceschange\", listener: () => this.updateDerived(session) },\n    ];\n\n    for (const entry of this.sessionListeners) {\n      session.addEventListener(entry.type, entry.listener);\n    }\n  }\n\n  private detachSession(): void {\n    const session = this.boundSession;\n\n    if (!session) {\n      return;\n    }\n\n    for (const entry of this.sessionListeners) {\n      session.removeEventListener(entry.type, entry.listener);\n    }\n\n    this.sessionListeners = [];\n    this.boundSession = null;\n  }\n\n  private handleSessionStart(): void {\n    const session = this.xr.getSession();\n\n    if (!session) {\n      return;\n    }\n\n    this.attachSession(session);\n    this.setSessionState(\"active\");\n    this.updateDerived(session);\n    this.notifyVisibility(toSessionVisibility(session.visibilityState));\n  }\n\n  /**\n   * One session ending raises both the session's `end` event and the manager's\n   * `sessionend`, so this runs twice per session and is written to be\n   * idempotent.\n   */\n  private handleSessionEnd(): void {\n    if (!this.boundSession && this.sessionState === \"none\") {\n      return;\n    }\n\n    this.detachSession();\n    this.setSessionState(\"none\");\n    this.updateDerived(null);\n    this.notifyVisibility(\"non-immersive\");\n    this.settleEndWaiters();\n  }\n\n  private updateDerived(session: CapabilitySessionLike | null): void {\n    this.derived = deriveCapabilities(session);\n    this.publishCapabilities();\n  }\n\n  private publishCapabilities(): void {\n    const next: AdapterCapabilities = { ...this.derived, ...this.overrides };\n    const current = this.capabilities;\n\n    if (\n      next.immersive === current.immersive &&\n      next.handTracking === current.handTracking &&\n      next.planeDetection === current.planeDetection &&\n      next.passthrough === current.passthrough &&\n      next.environmentBlendMode === current.environmentBlendMode\n    ) {\n      return;\n    }\n\n    this.capabilities = next;\n    this.capabilitiesListeners.forEach((listener) => listener(next));\n  }\n\n  private async requestSession(\n    mode: SessionMode,\n    options?: SessionRequestOptions,\n  ): Promise<SessionResult> {\n    if (this.sessionState === \"active\") {\n      return { ok: true };\n    }\n\n    const system = this.xrSystem;\n\n    if (!system) {\n      return { ok: false, reason: \"unsupported\" };\n    }\n\n    const timeoutMs = options?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;\n    this.setSessionState(\"requesting\");\n\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    const timeout = new Promise<SessionResult>((resolve) => {\n      timer = setTimeout(() => resolve({ ok: false, reason: \"timeout\" }), timeoutMs);\n    });\n\n    const result = await Promise.race([this.openSession(system, mode, options), timeout]);\n    clearTimeout(timer);\n\n    if (!result.ok) {\n      this.setSessionState(\"none\");\n      return result;\n    }\n\n    this.setSessionState(\"active\");\n    return result;\n  }\n\n  /**\n   * Negotiate the session and hand it to the renderer. Nothing here throws at\n   * the caller: a headset that is absent, refused or broken is a normal runtime\n   * condition, so every outcome comes back as a {@link SessionResult}.\n   *\n   * The request's own features are merged over the `sessionInit` hook's result\n   * by the core's `mergeSessionInit`, so they add to the app's defaults rather\n   * than replacing them. A request that names none passes the hook's result\n   * through untouched.\n   */\n  private async openSession(\n    system: WebXRSystemLike,\n    mode: SessionMode,\n    options?: SessionRequestOptions,\n  ): Promise<SessionResult> {\n    try {\n      const supported = await system.isSessionSupported(mode);\n\n      if (!supported) {\n        return { ok: false, reason: \"unsupported\" };\n      }\n\n      const init = mergeSessionInit(this.sessionInit?.(mode), options);\n      const session = await system.requestSession(mode, init);\n      await this.xr.setSession(session);\n\n      // A manager that raises `sessionstart` has already attached this session;\n      // one that does not is attached here, so both host styles behave alike.\n      this.attachSession(session);\n      this.updateDerived(session);\n\n      return { ok: true };\n    } catch (error) {\n      return { ok: false, reason: toFailureReason(error), error };\n    }\n  }\n\n  private async endSession(): Promise<void> {\n    const session = this.boundSession;\n\n    if (!session) {\n      return;\n    }\n\n    this.setSessionState(\"ending\");\n\n    const ended = new Promise<void>((resolve) => {\n      this.endWaiters.add(resolve);\n    });\n\n    try {\n      await session.end();\n    } catch {\n      // Ending is best effort. The `end` event, not this promise, is what the\n      // adapter acts on, and a host that refuses still has to be reported.\n    }\n\n    // The event has normally arrived by now and this is a no-op. A host that\n    // raises none would otherwise leave the caller waiting forever, so the\n    // settled `end()` call is the fallback signal.\n    this.handleSessionEnd();\n\n    await ended;\n  }\n\n  private settleEndWaiters(): void {\n    const waiters = Array.from(this.endWaiters);\n    this.endWaiters.clear();\n    waiters.forEach((resolve) => resolve());\n  }\n\n  private notifyVisibility(visibility: SessionVisibility): void {\n    this.visibilityListeners.forEach((listener) => listener(visibility));\n  }\n\n  private setSessionState(state: SessionState): void {\n    if (this.sessionState === state) {\n      return;\n    }\n\n    this.sessionState = state;\n    this.stateListeners.forEach((listener) => listener(state));\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realitycollective/service-framework-three",
-  "version": "1.0.1-preview.1",
+  "version": "1.0.1-preview.3",
   "description": "three.js render-loop bindings for the Reality Collective TypeScript Service Framework.",
   "author": "Reality Collective",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "url": "https://github.com/realitycollective/com.realitycollective.service-framework.ts/issues"
   },
   "dependencies": {
-    "@realitycollective/service-framework": "^1.0.1-preview.1"
+    "@realitycollective/service-framework": "^1.0.1-preview.3"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",