@realitycollective/service-framework-react 1.0.1-preview.2 → 1.0.1-preview.4

package/CHANGELOG.md

@@ -6,7 +6,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [1.0.1]
 
-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 or changed in signature.
+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
 
@@ -17,11 +17,16 @@ Packaging, tooling and documentation, plus additive runtime API: the engine-free
 - `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`. It is an in-repo test helper, not a published entry point. 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.
+- 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realitycollective/service-framework-react",
-  "version": "1.0.1-preview.2",
+  "version": "1.0.1-preview.4",
   "description": "React bindings for the Reality Collective TypeScript Service Framework.",
   "author": "Reality Collective",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "url": "https://github.com/realitycollective/com.realitycollective.service-framework.ts/issues"
   },
   "dependencies": {
-    "@realitycollective/service-framework": "^1.0.1-preview.2"
+    "@realitycollective/service-framework": "^1.0.1-preview.4"
   },
   "peerDependencies": {
     "react": "^19.2.0"