@realitycollective/service-framework-three 1.0.2-preview.2 → 1.0.2

package/CHANGELOG.md

@@ -4,12 +4,15 @@ Change log for the Reality Collective Service Framework for TypeScript. All pack
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Preview builds are not listed separately. The entry for a version accumulates while its previews are published, and is dated when that version is released.
 
-## [1.0.2]
+## [1.0.2] - 2026-10-01
 
 A native platform, beside IWSDK, three.js and Babylon.js, and byte I/O that works the same on the web and on a native host.
 
 ### Added
 
+- A native test harness in `harness/native`, a small app for the conversion pipeline that runs on a Quest headset. In `kits` mode it runs `runtimeAdapterContractCases()`, `renderTickContractCases()` and `hostIOContractCases()` over `NativeRuntimeAdapter` and `createNativeHostIO`, plus a boot with no global `AbortController`, against the shell's test host, or this repository's reference fake under Node. In `play` mode it logs session, visibility, pause, focus, capability and telemetry changes from the live host, and reads a packed file through `HostIO`. `npm run harness:compile` typechecks and bundles it through the engine and browser-global gates and compiles it to Hermes bytecode; CI compiles it and never runs it.
+- `@realitycollective/service-framework-iwsdk` - IWSDK 1.0.0's player rig: `world.player` is the `XROrigin` itself (an `Object3D` with the head as its `head` child), not an entity carrying `object3D`. `IWSDKPlayerLike` now accepts both shapes (`IWSDKPlayerEntityLike`, `IWSDKXROriginLike`), `playerRig` and `playerHead` read either, and `recentre()` moves a 1.0 rig; an IWSDK 1.0 `World` type-checks against `IWSDKWorldLike` again.
+- `@realitycollective/service-framework` - `RuntimeAdapterDriver.sessionStart` states the mode-switch semantics the contract case relies on: called while a session is live, the host hands over the new session once the adapter has ended the old one itself, so a driver whose host starts sessions at once queues the start until the adapter's `endSession` completes or its next request arrives.
 - `FrameInfo.frame`, the binding's frame count from 1: the same number the `renderTick` context carries for that frame. The native host's frames, the IWSDK bridge and the three.js and Babylon.js owned loops all set it from the one counter they already kept for `renderTick`, and `emitFrame` takes it as an optional third argument, so a client that needs a frame number reads one clock instead of counting frames again. Additive: a frame an app emits itself without one carries none.
 - `@realitycollective/service-framework-native` - `NativeSessionInfo.features`, the WebXR feature names the session enabled (`"hand-tracking"`, `"plane-detection"` and the rest), which the capabilities read as the IWSDK adapter reads `enabledFeatures`; `NativeHost.input`, the `input` slice's `onSourcesChanged` signal and source kinds; `NativeHost.onSessionRefused`, the app's way to say it will not start a requested session; and the `manager` option, the service manager whose focus and pause signals follow the session.
 - `@realitycollective/service-framework-native`, the binding for a native XR app that embeds a JavaScript engine such as Hermes. The app owns the session, the frame loop, rendering and physics, and installs one host object, `globalThis.__rcHost`, before it evaluates the bundle. Everything crosses that object as plain values. `NativeRuntimeAdapter` publishes the app's frames and session through the same `RuntimeAdapter` seam as the other bindings, with the session facet, and passes `runtimeAdapterContractCases()`. It derives capabilities from the OpenXR session state, the enabled extensions, system hand tracking support and the blend mode. It keeps the same sticky `setCapabilities` override, `clearCapabilityOverrides()` and `refreshCapabilities()` the other adapters have. Given a `scheduler`, it emits `renderTick` with `source: "native"`. `createNativeHostIO()` returns a `HostIO` over the host's `io` slice. The host object's shape was proven on a Quest 3 and in the visionOS Simulator by the team that built the first native host. The package README documents it, including the slices the other families' native packages read.
@@ -35,6 +38,7 @@ A native platform, beside IWSDK, three.js and Babylon.js, and byte I/O that work
 - `@realitycollective/service-framework-native` - a refused session request resolves with the app's reason, `"denied"`, `"unsupported"` or `"error"`, at once. Before this only `"timeout"` and `"error"` could be reached, so a dismissed permission prompt waited ten seconds and read as a timeout.
 - `@realitycollective/service-framework-native` - every member of `NativeHost` and `NativeSessionInfo` states its units and meaning: milliseconds and seconds on `onFrame`, what counts as live, what the blend mode must reflect, and what each signal triggers.
 - **Behaviour change on every platform:** `session.request(mode)` while a session is already active is now a no-op only when `mode` matches the live session. A different mode ends the live session first and then requests the new one ("end-and-request"), instead of the previous no-op that always resolved `{ ok: true }` regardless of the mode asked for. A session the adapter did not itself request - already active at construction, or started through a host's own UI - has no known mode, so a request against it is treated as a switch and goes through the same end-and-request path.
+- Dependencies on other Reality Collective repositories now follow one rule, checked by `scripts/rc-dependencies.mjs`. Going into `main`, each names the release npm tags `latest` and never a preview. Going into any other branch, each names the newest version on npm, release or preview. The rule covers every `package.json` in the repository (published packages, demos, harnesses and examples) and every copy `package-lock.json` records. A range passes only when its lowest version is the target, so `^0.1.8` passes for 0.1.8 and `^0.1.4` does not. CI runs it before the install, against the branch a pull request targets, and the publish workflow runs it before publishing. `release.mjs status` reports it. `release.mjs prepare` stops before cutting a release when a dependency names an unreleased preview of another repository, because that repository has to release first, and moves any range that is only behind. Other dependencies are out of scope. The script stays identical across the Reality Collective repositories.
 
 ### Fixed
 
@@ -110,5 +114,6 @@ First release. Six packages, published together.
 - `@realitycollective/service-framework-iwsdk` - Meta IWSDK (WebXR) bindings. IWSDK owns its own render loop, so this package is a passive frame source: one system relays each frame to services and maps `visibilityState` onto focus and pause, so services pause when the headset comes off. Services depend only on `RuntimeAdapter`, never on `@iwsdk/core`.
 - A worked example in every package's `Examples/` folder, and two runnable Vite apps in `runtime-examples/`.
 
+[1.0.2]: https://github.com/realitycollective/com.realitycollective.service-framework.ts/releases/tag/v1.0.2
 [1.0.1]: https://github.com/realitycollective/com.realitycollective.service-framework.ts/releases/tag/v1.0.1
 [1.0.0]: https://github.com/realitycollective/com.realitycollective.service-framework.ts/releases/tag/v1.0.0

package/README.md

@@ -90,7 +90,9 @@ This differs from IWSDK and native, which serve nothing but a live XR session: t
 | `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.
+`getState()` walks `"none"` -> `"requesting"` -> `"active"` -> `"ending"` -> `"none"`. `isSupported(mode)` reads `navigator.xr.isSessionSupported`, and resolves `false` where there is no `navigator.xr`. `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.
+
+`recentre()` makes the viewer's current floor position and yaw the new origin by offsetting the renderer's reference space, using the core's `recentreOffset` rule. It does nothing when there is no live frame or reference space, or no `XRRigidTransform` to build the offset with (the `rigidTransform` option supplies one outside a browser).
 
 `sessionInit` supplies the `XRSessionInit` per mode - required and optional features - and is called once per request. The default sends none.
 
@@ -124,7 +126,7 @@ A desktop build with no headset needs no special case. `request` returns `{ ok:
 | `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`, `tick`, `emitFrame`, `getSession`, `refreshCapabilities`, `setCapabilities`, `clearCapabilityOverrides`, `session`, `dispose`. |
-| `WebXRRuntimeAdapterOptions` | interface | `{ xr, xrSystem?, host?, scheduler?, sessionInit?, manager? }`. |
+| `WebXRRuntimeAdapterOptions` | interface | `{ xr, xrSystem?, host?, scheduler?, sessionInit?, manager?, rigidTransform? }`. |
 | `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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realitycollective/service-framework-three",
-  "version": "1.0.2-preview.2",
+  "version": "1.0.2",
   "description": "three.js render-loop bindings for the Reality Collective TypeScript Service Framework.",
   "author": "Reality Collective",
   "license": "MIT",
@@ -24,7 +24,10 @@
     "threejs",
     "render-loop",
     "realitycollective",
-    "typescript"
+    "typescript",
+    "webxr",
+    "runtime-adapter",
+    "session"
   ],
   "repository": {
     "type": "git",
@@ -35,7 +38,7 @@
     "url": "https://github.com/realitycollective/com.realitycollective.service-framework.ts/issues"
   },
   "dependencies": {
-    "@realitycollective/service-framework": "^1.0.2-preview.2"
+    "@realitycollective/service-framework": "^1.0.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",