@realitycollective/service-framework-iwsdk 1.0.1-preview.0 → 1.0.1-preview.2

package/CHANGELOG.md

@@ -6,10 +6,22 @@ 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 or changed in signature.
 
 ### 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.
+- 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.
 - 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,16 +30,21 @@ 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.
 
 ### Fixed
 
+- `@realitycollective/service-framework-iwsdk` could not be installed alongside `@iwsdk/core` 0.5.x. Its peer range was `>=0.4.0 <0.5.0`, which npm reports as `ERESOLVE` on a clean install and therefore on `npm ci`, regardless of the entry being optional. Consumers needed a local `overrides` block to install at all; that workaround can be deleted once this version is published.
 - `runtime-examples/*` white-screened with `Cannot read properties of null (reading 'useMemo')`. The Vite aliases point into `../../packages`, so the framework's React binding resolved React from the repository root while the app used its own copy. Two React instances leave the hook dispatcher null. Both example configs now set `resolve.dedupe`.
 
 ### Removed
 
+- The `@iwsdk/core` peer dependency on `@realitycollective/service-framework-iwsdk`, rather than widening it to `<0.6.0`. The bridge never imports `@iwsdk/core`: the primitives it needs (`World`, `createSystem`, `VisibilityState.Visible` and the visibility signal) are typed structurally and passed in by the consumer, and those four contracts are identical across 0.4.x and 0.5.x. A range that constrains nothing while still being able to fail a consumer's install is a liability, so there is now no entry of any kind. The package is verified against IWSDK 0.4.x and 0.5.x, and its example remains engine-free because it mocks those primitives.
 - Build output is no longer committed: 72 files under `packages/*/dist/` and 44 compiled `.js`, `.d.ts` and `.map` files that sat beside the sources in `packages/*/src/`. The test suite had been executing that committed JavaScript rather than the TypeScript, so coverage now measures `src/**/*.ts`.
 - The generated `coverage/` report, which every test run rewrote with a new timestamp.
 

package/README.md

@@ -24,21 +24,25 @@ ServiceBridgeSystem        ← the only place the engine touches services
    every update(delta, time):
      • visibilityState → manager.emitFocusChange / emitPauseChange
      • if focused: adapter.emitFrame(time, delta)
+     • if focused: scheduler.emit("renderTick", { source: "iwsdk", ... })
    ▼
-IWSDKAdapter (RuntimeAdapter)  →  onFrame fan-out  →  services
+IWSDKAdapter (RuntimeAdapter) → onFrame fan-out    → services
+ServiceManager.scheduler      → renderTick channel → services
    ▼
 ServiceManager  →  your SnapshotService graph
 ```
 
+Each focused frame goes out twice, on the two channels a service can be written against. `adapter.onFrame` is the adapter seam, and carries IWSDK's own units: `timestamp` in milliseconds, `delta` in seconds. `renderTick` is the scheduler channel the three.js and Babylon.js bridges emit, and carries a `LifecycleContext` in scheduler units: `timestamp` and `deltaTime` both in milliseconds, a frame counter, and `source: "iwsdk"`. A service written against `renderTick` therefore runs under IWSDK exactly as it does under three.js, with no change. Frames while the session is not focused are emitted on neither channel and do not advance the counter.
+
 **Invariant:** services depend only on `RuntimeAdapter`, never on `@iwsdk/core`. That is what keeps them unit-testable headless - swap `IWSDKAdapter` for `MockRuntimeAdapter`.
 
 ---
 
 ## No hard dependency on `@iwsdk/core`
 
-Like the three.js and Babylon.js bridges keep their renderer packages at arm's length, this package **never imports `@iwsdk/core`**. The IWSDK primitives the bridge needs - `createSystem` and the `VisibilityState.Visible` value - are passed in by the consumer (who owns IWSDK). This keeps the package tree-shakeable, version-tolerant across IWSDK `0.4.x`, and trivially mockable in unit tests.
+Like the three.js and Babylon.js bridges keep their renderer packages at arm's length, this package **never imports `@iwsdk/core`**. The IWSDK primitives the bridge needs - `createSystem` and the `VisibilityState.Visible` value - are passed in by the consumer (who owns IWSDK). This keeps the package tree-shakeable, version-tolerant across IWSDK `0.4.x` and `0.5.x`, and trivially mockable in unit tests.
 
-`@iwsdk/core` is declared as an **optional peer dependency**.
+`@iwsdk/core` is **not declared as a dependency of any kind** - not even an optional peer. Everything this package reads off the world is structurally typed in `iwsdk-host.ts` and passed in: `createSystem`, the `VisibilityState.Visible` value, the visibility signal, and - all optional - `visibilityState.subscribe`, the live `session`, `launchXR` and `exitXR`. Because the additions are optional, a world that carries nothing but the visibility signal still type-checks and still works; it simply reports no capabilities and no session. Those contracts are identical across 0.4.x and 0.5.x. A peer range here would constrain nothing while still being able to fail a consumer's clean install, so there is deliberately no entry.
 
 ---
 
@@ -77,10 +81,10 @@ Game logic ticks **only while the session is visible/focused** - in the browser
 
 ## Services own their state: `SnapshotService`
 
-`SnapshotService<TConfig, TSnapshot>` is the "services own state" base - one immutable snapshot plus pub/sub. Subscribers receive the current value immediately, then every publish. It has **no IWSDK dependency**.
+`SnapshotService<TConfig, TSnapshot>` is the "services own state" base - one immutable snapshot plus pub/sub. Subscribers receive the current value immediately, then every publish. It has **no IWSDK dependency**, which is why it now lives in the core package; this package re-exports it, so the older import still works.
 
 ```typescript
-import { SnapshotService, type ServiceContext, type RuntimeAdapter } from "@realitycollective/service-framework-iwsdk";
+import { SnapshotService, type ServiceContext, type RuntimeAdapter } from "@realitycollective/service-framework";
 
 interface EnergySnapshot { readonly energy: number; }
 
@@ -111,7 +115,7 @@ const unsubscribe = energy.subscribe(({ energy }) => hud.setEnergy(energy));
 Services run against `MockRuntimeAdapter` with no IWSDK / renderer / headset. Tests drive the loop by calling `emitFrame`:
 
 ```typescript
-import { MockRuntimeAdapter } from "@realitycollective/service-framework-iwsdk";
+import { MockRuntimeAdapter } from "@realitycollective/service-framework";
 
 const adapter = new MockRuntimeAdapter({ immersive: true });
 const service = new EnergyService(makeContext(), adapter);
@@ -123,32 +127,90 @@ expect(service.getSnapshot().energy).toBeLessThan(1);
 
 No `@iwsdk/core` import appears anywhere in the test.
 
+`MockRuntimeAdapter` implements the session facet in memory too: `simulateSessionStart()`, `simulateSessionEnd()` and `simulateVisibility(v)` drive it, and `request()` resolves `{ ok: true }` when a start is simulated before the timeout, `{ ok: false, reason: "timeout" }` otherwise. Both adapters run the same in-repo conformance suite, so a service that behaves one way headless behaves the same way on a headset.
+
 ---
 
 ## Capabilities
 
-`AdapterCapabilities` (`immersive`, `handTracking`, `planeDetection`, `passthrough`) is what gating services read (`adapter.getCapabilities()`) or subscribe to (`adapter.onCapabilitiesChange(cb)` - mirrors `onFrame`, so gates don't poll every frame). Refine them with `adapter.setCapabilities({ ... })`.
+`AdapterCapabilities` (`immersive`, `handTracking`, `planeDetection`, `passthrough`) is what gating services read (`adapter.getCapabilities()`) or subscribe to (`adapter.onCapabilitiesChange(cb)` - mirrors `onFrame`, so gates don't poll every frame).
+
+`IWSDKAdapter` derives all four from the live session through `deriveCapabilities(session)`, exported by `@realitycollective/service-framework`. The rules live in the core so that every host binding - this one, the three.js `WebXRRuntimeAdapter`, and whatever comes next - reports the same flags for the same session. It derives on construction, and again every time the world's visibility signal fires, which is when a session comes or goes:
+
+| Flag | Derived from |
+| --- | --- |
+| `immersive` | a session exists on the world |
+| `handTracking` | `"hand-tracking"` in `session.enabledFeatures`, or any `session.inputSources[i].hand` |
+| `planeDetection` | `"plane-detection"` in `session.enabledFeatures` |
+| `passthrough` | `session.environmentBlendMode` is present and is not `"opaque"` |
+
+With no session the adapter reports `DEFAULT_CAPABILITIES`, all false, so gating services behave conservatively before the player enters XR. Subscribers are notified only when a flag actually changes, so a signal that fires every visibility blip does not wake every gate.
+
+Two hosts need a nudge. If the world's `visibilityState` has no `subscribe`, nothing tells the adapter to re-derive: call `adapter.refreshCapabilities()` after the host changes something. Call it too if the host enables a feature mid-session without a visibility transition.
+
+### Overrides
+
+`adapter.setCapabilities({ ... })` still exists, and is now a layer on top of the derived values rather than the only source of them. An override wins for as long as it is set: it survives every later derivation, so forcing `passthrough: true` on a device that under-reports its blend mode keeps working when the session changes. Overrides are dropped by `adapter.clearCapabilityOverrides()`, which falls back to the derived values, or by `adapter.dispose()`.
+
+`adapter.dispose()` releases the visibility subscription, settles any in-flight session request, drops the overrides and clears every listener. Call it when tearing the world down.
+
+---
+
+## Sessions
+
+`adapter.session` is the optional session facet from `RuntimeAdapter`, implemented here over the world's `launchXR` and `exitXR`. It exists so a client can start, end and observe an XR session without reaching past the adapter into IWSDK - which is what a client had to do before, and the reason the "the adapter does not abstract sessions" position was reversed.
+
+```typescript
+const result = await adapter.session.request("immersive-vr", { timeoutMs: 8000 });
+
+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);
+}
+
+const stop = adapter.session.onStateChange((state) => hud.setSessionState(state));
+adapter.session.onVisibilityChange((visibility) => hud.setDimmed(visibility !== "visible"));
+
+await adapter.session.end();
+```
+
+- `getState()` walks `"none"` → `"requesting"` → `"active"` → `"ending"` → `"none"`.
+- `request(mode, options)` calls `launchXR` with `{ sessionMode: mode }` (the `XROptions` shape IWSDK accepts; its `SessionMode` enum values are the WebXR mode strings) and resolves once a session appears, whether the adapter learns that from the visibility signal or from its polling fallback. A synchronous throw from `launchXR` comes back as `{ ok: false, reason: "unsupported", error }`. Nothing appearing within `timeoutMs` (default 10000) comes back as `{ ok: false, reason: "timeout" }`.
+- `end()` calls `exitXR` and resolves once the session is gone.
+- `onVisibilityChange` maps IWSDK's signal onto `"visible"`, `"visible-blurred"`, `"hidden"` and `"non-immersive"`. 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.
 
-> **One gap still to close:** deriving capabilities from the live `XRSession` (enabled features, blend mode, hand input sources) is intentionally left to the host wiring because it needs IWSDK session internals. Until that is wired, the adapter reports `DEFAULT_CAPABILITIES` (all-false) and gating services behave conservatively. `IWSDKAdapter.getWorld()` exposes the bound world as the source for that derivation, and `onCapabilitiesChange` is the notification channel for when it lands.
+A world with no `launchXR` reports `{ ok: false, reason: "unsupported" }` rather than throwing, so a 2D preview build needs no special case.
 
 ---
 
 ## API surface
 
+Owned by this package:
+
 | Symbol | Kind | Purpose |
 | --- | --- | --- |
-| `RuntimeAdapter` | interface | The seam services depend on (`onFrame`, `getCapabilities`, `onCapabilitiesChange`). |
+| `IWSDKAdapter` | class | Production adapter; `emitFrame`, `refreshCapabilities`, `setCapabilities`, `clearCapabilityOverrides`, `session`, `getWorld`, `dispose`. |
+| `makeServiceBridgeSystem` | factory | Returns the IWSDK `ServiceBridgeSystem` class; pumps `onFrame` and `renderTick`. |
+| `ServiceBridgeSystemOptions` | interface | `{ adapter, manager, world, createSystem, visibleState }`. |
+| `startServiceRuntime` / `ServiceRuntime` | function / interface | Bootstraps `{ manager, adapter }` from a profile factory. |
+| `IWSDKWorldLike` / `IWSDKSignalLike` / `IWSDKSessionLike` / `IWSDKInputSourceLike` / `IWSDKSystemLike` / `IWSDKSystemConstructor` / `CreateSystemLike` | types | Structural `@iwsdk/core` contracts (no engine import). |
+
+Re-exported from `@realitycollective/service-framework`. None of these ever touched IWSDK, and every host binding needs them, so they moved into the core in 1.0.1. They are re-exported here unchanged, so importing them from this package keeps working; new code should import them from the core package.
+
+| Symbol | Kind | Purpose |
+| --- | --- | --- |
+| `RuntimeAdapter` | interface | The seam services depend on (`onFrame`, `getCapabilities`, `onCapabilitiesChange`, optional `session`). |
 | `FrameInfo` | interface | `{ timestamp, delta }`. |
 | `AdapterCapabilities` / `DEFAULT_CAPABILITIES` | interface / const | XR capability flags; all-false default. |
 | `Unsubscribe` / `FrameListener` / `CapabilitiesListener` | types | Callback / handle aliases. |
-| `IWSDKAdapter` | class | Production adapter; `emitFrame`, `setCapabilities`, `getWorld`. |
-| `MockRuntimeAdapter` | class | Headless adapter; `emitFrame(ts?, delta?)`, `setCapabilities`. |
+| `SessionFacet` | interface | `getState`, `request`, `end`, `onStateChange`, `onVisibilityChange`. |
+| `SessionMode` / `SessionState` / `SessionResult` / `SessionFailureReason` / `SessionVisibility` / `SessionRequestOptions` | types | The session facet's vocabulary. |
+| `DEFAULT_SESSION_TIMEOUT_MS` | const | 10000 - the default `request` timeout. |
+| `RUNTIME_ADAPTER_FACETS` / `RuntimeAdapterFacet` | const / type | Every optional facet an adapter can carry; walked by the conformance suite. |
+| `MockRuntimeAdapter` | class | Headless adapter; `emitFrame(ts?, delta?)`, `setCapabilities`, `simulateSessionStart`, `simulateSessionEnd`, `simulateVisibility`. |
 | `SnapshotService<C, S>` | abstract class | State-owning base (`subscribe` / `getSnapshot` / `publishSnapshot` / `updateSnapshot`). |
 | `ServiceContext<C>` / `SnapshotListener<S>` | types | Activation-context alias; snapshot callback. |
-| `makeServiceBridgeSystem` | factory | Returns the IWSDK `ServiceBridgeSystem` class. |
-| `ServiceBridgeSystemOptions` | interface | `{ adapter, manager, world, createSystem, visibleState }`. |
-| `startServiceRuntime` / `ServiceRuntime` | function / interface | Bootstraps `{ manager, adapter }` from a profile factory. |
-| `IWSDKWorldLike` / `CreateSystemLike` / … | types | Structural `@iwsdk/core` contracts (no engine import). |
 
 ---
 

package/dist/index.d.ts

@@ -1,10 +1,13 @@
-export { DEFAULT_CAPABILITIES } from "./runtime-adapter.js";
-export type { AdapterCapabilities, CapabilitiesListener, FrameInfo, FrameListener, RuntimeAdapter, Unsubscribe, } from "./runtime-adapter.js";
-export type { CreateSystemLike, IWSDKSignalLike, IWSDKSystemConstructor, IWSDKSystemLike, IWSDKWorldLike, } from "./iwsdk-host.js";
+/**
+ * The runtime-adapter contract, the snapshot service base and the headless mock
+ * moved into `@realitycollective/service-framework` in 1.0.1: none of them ever
+ * touched IWSDK, and every host binding needs them. They are re-exported here
+ * unchanged so existing imports from this package keep working.
+ */
+export { DEFAULT_CAPABILITIES, DEFAULT_SESSION_TIMEOUT_MS, MockRuntimeAdapter, RUNTIME_ADAPTER_FACETS, SnapshotService, } from "@realitycollective/service-framework";
+export type { AdapterCapabilities, CapabilitiesListener, FrameInfo, FrameListener, RuntimeAdapter, RuntimeAdapterFacet, ServiceContext, SessionFacet, SessionFailureReason, SessionMode, SessionRequestOptions, SessionResult, SessionState, SessionVisibility, SnapshotListener, Unsubscribe, } from "@realitycollective/service-framework";
+export type { CreateSystemLike, IWSDKInputSourceLike, IWSDKSessionLike, IWSDKSignalLike, IWSDKSystemConstructor, IWSDKSystemLike, IWSDKWorldLike, } from "./iwsdk-host.js";
 export { IWSDKAdapter } from "./iwsdk-adapter.js";
-export { MockRuntimeAdapter } from "./mock-runtime-adapter.js";
-export { SnapshotService } from "./snapshot-service.js";
-export type { ServiceContext, SnapshotListener } from "./snapshot-service.js";
 export { makeServiceBridgeSystem } from "./service-bridge-system.js";
 export type { ServiceBridgeSystemOptions } from "./service-bridge-system.js";
 export { startServiceRuntime } from "./bootstrap.js";

package/dist/index.js

@@ -1,7 +1,11 @@
-export { DEFAULT_CAPABILITIES } from "./runtime-adapter.js";
+/**
+ * The runtime-adapter contract, the snapshot service base and the headless mock
+ * moved into `@realitycollective/service-framework` in 1.0.1: none of them ever
+ * touched IWSDK, and every host binding needs them. They are re-exported here
+ * unchanged so existing imports from this package keep working.
+ */
+export { DEFAULT_CAPABILITIES, DEFAULT_SESSION_TIMEOUT_MS, MockRuntimeAdapter, RUNTIME_ADAPTER_FACETS, SnapshotService, } from "@realitycollective/service-framework";
 export { IWSDKAdapter } from "./iwsdk-adapter.js";
-export { MockRuntimeAdapter } from "./mock-runtime-adapter.js";
-export { SnapshotService } from "./snapshot-service.js";
 export { makeServiceBridgeSystem } from "./service-bridge-system.js";
 export { startServiceRuntime } from "./bootstrap.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAkB5D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAGrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["export { DEFAULT_CAPABILITIES } from \"./runtime-adapter.js\";\nexport type {\n  AdapterCapabilities,\n  CapabilitiesListener,\n  FrameInfo,\n  FrameListener,\n  RuntimeAdapter,\n  Unsubscribe,\n} from \"./runtime-adapter.js\";\n\nexport type {\n  CreateSystemLike,\n  IWSDKSignalLike,\n  IWSDKSystemConstructor,\n  IWSDKSystemLike,\n  IWSDKWorldLike,\n} from \"./iwsdk-host.js\";\n\nexport { IWSDKAdapter } from \"./iwsdk-adapter.js\";\nexport { MockRuntimeAdapter } from \"./mock-runtime-adapter.js\";\n\nexport { SnapshotService } from \"./snapshot-service.js\";\nexport type { ServiceContext, SnapshotListener } from \"./snapshot-service.js\";\n\nexport { makeServiceBridgeSystem } from \"./service-bridge-system.js\";\nexport type { ServiceBridgeSystemOptions } from \"./service-bridge-system.js\";\n\nexport { startServiceRuntime } from \"./bootstrap.js\";\nexport type { ServiceRuntime } from \"./bootstrap.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,sBAAsB,EACtB,eAAe,GAChB,MAAM,sCAAsC,CAAC;AA8B9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAGrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["/**\n * The runtime-adapter contract, the snapshot service base and the headless mock\n * moved into `@realitycollective/service-framework` in 1.0.1: none of them ever\n * touched IWSDK, and every host binding needs them. They are re-exported here\n * unchanged so existing imports from this package keep working.\n */\nexport {\n  DEFAULT_CAPABILITIES,\n  DEFAULT_SESSION_TIMEOUT_MS,\n  MockRuntimeAdapter,\n  RUNTIME_ADAPTER_FACETS,\n  SnapshotService,\n} from \"@realitycollective/service-framework\";\nexport type {\n  AdapterCapabilities,\n  CapabilitiesListener,\n  FrameInfo,\n  FrameListener,\n  RuntimeAdapter,\n  RuntimeAdapterFacet,\n  ServiceContext,\n  SessionFacet,\n  SessionFailureReason,\n  SessionMode,\n  SessionRequestOptions,\n  SessionResult,\n  SessionState,\n  SessionVisibility,\n  SnapshotListener,\n  Unsubscribe,\n} from \"@realitycollective/service-framework\";\n\nexport type {\n  CreateSystemLike,\n  IWSDKInputSourceLike,\n  IWSDKSessionLike,\n  IWSDKSignalLike,\n  IWSDKSystemConstructor,\n  IWSDKSystemLike,\n  IWSDKWorldLike,\n} from \"./iwsdk-host.js\";\n\nexport { IWSDKAdapter } from \"./iwsdk-adapter.js\";\n\nexport { makeServiceBridgeSystem } from \"./service-bridge-system.js\";\nexport type { ServiceBridgeSystemOptions } from \"./service-bridge-system.js\";\n\nexport { startServiceRuntime } from \"./bootstrap.js\";\nexport type { ServiceRuntime } from \"./bootstrap.js\";\n"]}

package/dist/iwsdk-adapter.d.ts

@@ -1,29 +1,80 @@
 /**
  * IWSDK implementation of {@link RuntimeAdapter}. IWSDK owns the render loop, so
- * the adapter is a passive fan-out: the `ServiceBridgeSystem` (a normal IWSDK
- * system) calls {@link IWSDKAdapter.emitFrame} once per frame and the adapter
- * notifies subscribed services. Capabilities are refined from the XR session via
- * {@link IWSDKAdapter.setCapabilities}.
+ * frames are pushed in rather than pulled: the `ServiceBridgeSystem` (a normal
+ * IWSDK system) calls {@link IWSDKAdapter.emitFrame} once per frame and the
+ * adapter notifies subscribed services.
+ *
+ * Capabilities are derived from the live session on construction and on every
+ * visibility change, through the core's shared `deriveCapabilities`, with a
+ * manual override layer on top. Session lifecycle is
+ * exposed through {@link IWSDKAdapter.session}, over the world's `launchXR` and
+ * `exitXR` entry points.
  */
-import { type AdapterCapabilities, type CapabilitiesListener, type FrameListener, type RuntimeAdapter, type Unsubscribe } from "./runtime-adapter.js";
+import { type AdapterCapabilities, type CapabilitiesListener, type FrameListener, type RuntimeAdapter, type SessionFacet, type Unsubscribe } from "@realitycollective/service-framework";
 import type { IWSDKWorldLike } from "./iwsdk-host.js";
 export declare class IWSDKAdapter implements RuntimeAdapter {
     private readonly world;
     private readonly frameListeners;
     private readonly capabilitiesListeners;
+    private readonly stateListeners;
+    private readonly visibilityListeners;
+    private readonly pendingWaits;
+    private derived;
+    private overrides;
     private capabilities;
+    private sessionState;
+    private unsubscribeVisibility;
+    /** Session lifecycle over the world's `launchXR` / `exitXR` entry points. */
+    readonly session: SessionFacet;
     constructor(world: IWSDKWorldLike);
     onFrame(listener: FrameListener): Unsubscribe;
     getCapabilities(): AdapterCapabilities;
     onCapabilitiesChange(listener: CapabilitiesListener): Unsubscribe;
+    /** The IWSDK `World` this adapter is bound to. */
+    getWorld(): IWSDKWorldLike;
     /**
-     * The IWSDK `World` this adapter is bound to. Reserved for capability
-     * derivation from the live XR session (see the package README "Capabilities"
-     * section) - the one piece still to be wired to the real IWSDK session API.
+     * Re-read the live session and publish any capability change. The adapter
+     * does this itself whenever the visibility signal fires; call it directly on
+     * a host whose signal has no `subscribe`, or after the host enables a feature
+     * mid-session.
+     */
+    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 IWSDKAdapter.clearCapabilityOverrides} or
+     * {@link IWSDKAdapter.dispose}. Subscribers are notified if the effective
+     * capabilities changed.
      */
-    getWorld(): IWSDKWorldLike;
-    /** Refine capabilities once the XR session reports them; notifies subscribers. */
     setCapabilities(capabilities: Partial<AdapterCapabilities>): void;
+    /** Drop every manual override and fall back to the derived capabilities. */
+    clearCapabilityOverrides(): void;
     /** Called once per frame by the ECS bridge system. */
     emitFrame(timestamp: number, delta: number): void;
+    /**
+     * Release everything the adapter holds: the visibility subscription, any
+     * in-flight session wait, the manual overrides and every listener.
+     */
+    dispose(): void;
+    private hasSession;
+    private publishCapabilities;
+    private handleVisibilityChange;
+    /**
+     * Follow the world when nothing local is mid-transition. `request()` and
+     * `end()` own the state while they run, so the signal does not fight them.
+     */
+    private syncSessionState;
+    private requestSession;
+    private endSession;
+    /**
+     * Resolve `true` once `predicate` holds, `false` on timeout. The visibility
+     * signal drives this where the host has one; the interval is the fallback for
+     * a host whose signal does not push, and for a session that appears without
+     * a visibility transition.
+     */
+    private waitFor;
+    private checkWaits;
+    private settleWait;
+    private setSessionState;
 }

package/dist/iwsdk-adapter.js

@@ -1,18 +1,73 @@
 /**
  * IWSDK implementation of {@link RuntimeAdapter}. IWSDK owns the render loop, so
- * the adapter is a passive fan-out: the `ServiceBridgeSystem` (a normal IWSDK
- * system) calls {@link IWSDKAdapter.emitFrame} once per frame and the adapter
- * notifies subscribed services. Capabilities are refined from the XR session via
- * {@link IWSDKAdapter.setCapabilities}.
+ * frames are pushed in rather than pulled: the `ServiceBridgeSystem` (a normal
+ * IWSDK system) calls {@link IWSDKAdapter.emitFrame} once per frame and the
+ * adapter notifies subscribed services.
+ *
+ * Capabilities are derived from the live session on construction and on every
+ * visibility change, through the core's shared `deriveCapabilities`, with a
+ * manual override layer on top. Session lifecycle is
+ * exposed through {@link IWSDKAdapter.session}, over the world's `launchXR` and
+ * `exitXR` entry points.
  */
-import { DEFAULT_CAPABILITIES, } from "./runtime-adapter.js";
+import { DEFAULT_CAPABILITIES, DEFAULT_SESSION_TIMEOUT_MS, deriveCapabilities, } from "@realitycollective/service-framework";
+/** How often the session waits re-check the world when the signal is silent. */
+const SESSION_POLL_INTERVAL_MS = 50;
+const SESSION_VISIBILITY_VALUES = new Set([
+    "visible",
+    "visible-blurred",
+    "hidden",
+    "non-immersive",
+]);
+/**
+ * IWSDK's visibility signal carries the WebXR visibility strings. Anything this
+ * adapter does not recognise 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";
+}
 export class IWSDKAdapter {
     world;
     frameListeners = new Set();
     capabilitiesListeners = new Set();
+    stateListeners = new Set();
+    visibilityListeners = new Set();
+    pendingWaits = new Set();
+    derived = DEFAULT_CAPABILITIES;
+    overrides = {};
     capabilities = DEFAULT_CAPABILITIES;
+    sessionState = "none";
+    unsubscribeVisibility;
+    /** Session lifecycle over the world's `launchXR` / `exitXR` entry points. */
+    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(world) {
         this.world = world;
+        this.unsubscribeVisibility = world.visibilityState.subscribe?.((value) => {
+            this.handleVisibilityChange(value);
+        });
+        this.derived = deriveCapabilities(this.world.session);
+        this.capabilities = this.derived;
+        this.sessionState = this.hasSession() ? "active" : "none";
     }
     onFrame(listener) {
         this.frameListeners.add(listener);
@@ -29,23 +84,170 @@ export class IWSDKAdapter {
             this.capabilitiesListeners.delete(listener);
         };
     }
-    /**
-     * The IWSDK `World` this adapter is bound to. Reserved for capability
-     * derivation from the live XR session (see the package README "Capabilities"
-     * section) - the one piece still to be wired to the real IWSDK session API.
-     */
+    /** The IWSDK `World` this adapter is bound to. */
     getWorld() {
         return this.world;
     }
-    /** Refine capabilities once the XR session reports them; notifies subscribers. */
+    /**
+     * Re-read the live session and publish any capability change. The adapter
+     * does this itself whenever the visibility signal fires; call it directly on
+     * a host whose signal has no `subscribe`, or after the host enables a feature
+     * mid-session.
+     */
+    refreshCapabilities() {
+        this.derived = deriveCapabilities(this.world.session);
+        this.publishCapabilities();
+    }
+    /**
+     * 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 IWSDKAdapter.clearCapabilityOverrides} or
+     * {@link IWSDKAdapter.dispose}. Subscribers are notified if the effective
+     * capabilities changed.
+     */
     setCapabilities(capabilities) {
-        this.capabilities = { ...this.capabilities, ...capabilities };
-        this.capabilitiesListeners.forEach((listener) => listener(this.capabilities));
+        this.overrides = { ...this.overrides, ...capabilities };
+        this.publishCapabilities();
+    }
+    /** Drop every manual override and fall back to the derived capabilities. */
+    clearCapabilityOverrides() {
+        this.overrides = {};
+        this.publishCapabilities();
     }
     /** Called once per frame by the ECS bridge system. */
     emitFrame(timestamp, delta) {
         const frame = { timestamp, delta };
         this.frameListeners.forEach((listener) => listener(frame));
     }
+    /**
+     * Release everything the adapter holds: the visibility subscription, any
+     * in-flight session wait, the manual overrides and every listener.
+     */
+    dispose() {
+        this.unsubscribeVisibility?.();
+        this.unsubscribeVisibility = undefined;
+        for (const wait of Array.from(this.pendingWaits)) {
+            this.settleWait(wait, false);
+        }
+        this.overrides = {};
+        this.frameListeners.clear();
+        this.capabilitiesListeners.clear();
+        this.stateListeners.clear();
+        this.visibilityListeners.clear();
+    }
+    hasSession() {
+        return Boolean(this.world.session);
+    }
+    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) {
+            return;
+        }
+        this.capabilities = next;
+        this.capabilitiesListeners.forEach((listener) => listener(next));
+    }
+    handleVisibilityChange(value) {
+        this.refreshCapabilities();
+        this.syncSessionState();
+        this.checkWaits();
+        const visibility = toSessionVisibility(value);
+        this.visibilityListeners.forEach((listener) => listener(visibility));
+    }
+    /**
+     * Follow the world when nothing local is mid-transition. `request()` and
+     * `end()` own the state while they run, so the signal does not fight them.
+     */
+    syncSessionState() {
+        if (this.sessionState === "requesting" || this.sessionState === "ending") {
+            return;
+        }
+        this.setSessionState(this.hasSession() ? "active" : "none");
+    }
+    async requestSession(mode, options) {
+        if (this.sessionState === "active") {
+            return { ok: true };
+        }
+        const launch = this.world.launchXR;
+        if (!launch) {
+            return { ok: false, reason: "unsupported" };
+        }
+        const timeoutMs = options?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+        this.setSessionState("requesting");
+        try {
+            // IWSDK reads `XROptions.sessionMode`; its `SessionMode` enum values are the
+            // WebXR mode strings, so the facet mode passes through unchanged.
+            launch.call(this.world, { sessionMode: mode });
+        }
+        catch (error) {
+            this.setSessionState("none");
+            return { ok: false, reason: "unsupported", error };
+        }
+        const started = await this.waitFor(() => this.hasSession(), timeoutMs);
+        if (!started) {
+            this.setSessionState("none");
+            return { ok: false, reason: "timeout" };
+        }
+        this.setSessionState("active");
+        this.refreshCapabilities();
+        return { ok: true };
+    }
+    async endSession() {
+        if (this.sessionState === "none") {
+            return;
+        }
+        const exit = this.world.exitXR;
+        this.setSessionState("ending");
+        if (exit) {
+            exit.call(this.world);
+        }
+        await this.waitFor(() => !this.hasSession(), DEFAULT_SESSION_TIMEOUT_MS);
+        this.setSessionState("none");
+        this.refreshCapabilities();
+    }
+    /**
+     * Resolve `true` once `predicate` holds, `false` on timeout. The visibility
+     * signal drives this where the host has one; the interval is the fallback for
+     * a host whose signal does not push, and for a session that appears without
+     * a visibility transition.
+     */
+    waitFor(predicate, timeoutMs) {
+        if (predicate()) {
+            return Promise.resolve(true);
+        }
+        return new Promise((resolve) => {
+            const wait = {
+                predicate,
+                resolve,
+                timer: setTimeout(() => this.settleWait(wait, false), timeoutMs),
+                interval: setInterval(() => this.checkWaits(), SESSION_POLL_INTERVAL_MS),
+            };
+            this.pendingWaits.add(wait);
+        });
+    }
+    checkWaits() {
+        for (const wait of Array.from(this.pendingWaits)) {
+            if (wait.predicate()) {
+                this.settleWait(wait, true);
+            }
+        }
+    }
+    settleWait(wait, settled) {
+        this.pendingWaits.delete(wait);
+        clearTimeout(wait.timer);
+        clearInterval(wait.interval);
+        wait.resolve(settled);
+    }
+    setSessionState(state) {
+        if (this.sessionState === state) {
+            return;
+        }
+        this.sessionState = state;
+        this.stateListeners.forEach((listener) => listener(state));
+    }
 }
 //# sourceMappingURL=iwsdk-adapter.js.map

package/dist/iwsdk-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"iwsdk-adapter.js","sourceRoot":"","sources":["../src/iwsdk-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,oBAAoB,GAOrB,MAAM,sBAAsB,CAAC;AAG9B,MAAM,OAAO,YAAY;IAKa;IAJnB,cAAc,GAAG,IAAI,GAAG,EAAiB,CAAC;IAC1C,qBAAqB,GAAG,IAAI,GAAG,EAAwB,CAAC;IACjE,YAAY,GAAwB,oBAAoB,CAAC;IAEjE,YAAoC,KAAqB;QAArB,UAAK,GAAL,KAAK,CAAgB;IAAG,CAAC;IAEtD,OAAO,CAAC,QAAuB;QACpC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClC,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvC,CAAC,CAAC;IACJ,CAAC;IAEM,eAAe;QACpB,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAEM,oBAAoB,CAAC,QAA8B;QACxD,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9C,CAAC,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACI,QAAQ;QACb,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,kFAAkF;IAC3E,eAAe,CAAC,YAA0C;QAC/D,IAAI,CAAC,YAAY,GAAG,EAAE,GAAG,IAAI,CAAC,YAAY,EAAE,GAAG,YAAY,EAAE,CAAC;QAC9D,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IAChF,CAAC;IAED,sDAAsD;IAC/C,SAAS,CAAC,SAAiB,EAAE,KAAa;QAC/C,MAAM,KAAK,GAAc,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAC9C,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7D,CAAC;CACF","sourcesContent":["/**\n * IWSDK implementation of {@link RuntimeAdapter}. IWSDK owns the render loop, so\n * the adapter is a passive fan-out: the `ServiceBridgeSystem` (a normal IWSDK\n * system) calls {@link IWSDKAdapter.emitFrame} once per frame and the adapter\n * notifies subscribed services. Capabilities are refined from the XR session via\n * {@link IWSDKAdapter.setCapabilities}.\n */\nimport {\n  DEFAULT_CAPABILITIES,\n  type AdapterCapabilities,\n  type CapabilitiesListener,\n  type FrameInfo,\n  type FrameListener,\n  type RuntimeAdapter,\n  type Unsubscribe,\n} from \"./runtime-adapter.js\";\nimport type { IWSDKWorldLike } from \"./iwsdk-host.js\";\n\nexport class IWSDKAdapter implements RuntimeAdapter {\n  private readonly frameListeners = new Set<FrameListener>();\n  private readonly capabilitiesListeners = new Set<CapabilitiesListener>();\n  private capabilities: AdapterCapabilities = DEFAULT_CAPABILITIES;\n\n  public constructor(private readonly world: IWSDKWorldLike) {}\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  /**\n   * The IWSDK `World` this adapter is bound to. Reserved for capability\n   * derivation from the live XR session (see the package README \"Capabilities\"\n   * section) - the one piece still to be wired to the real IWSDK session API.\n   */\n  public getWorld(): IWSDKWorldLike {\n    return this.world;\n  }\n\n  /** Refine capabilities once the XR session reports them; notifies subscribers. */\n  public setCapabilities(capabilities: Partial<AdapterCapabilities>): void {\n    this.capabilities = { ...this.capabilities, ...capabilities };\n    this.capabilitiesListeners.forEach((listener) => listener(this.capabilities));\n  }\n\n  /** Called once per frame by the ECS bridge system. */\n  public emitFrame(timestamp: number, delta: number): void {\n    const frame: FrameInfo = { timestamp, delta };\n    this.frameListeners.forEach((listener) => listener(frame));\n  }\n}\n"]}
+{"version":3,"file":"iwsdk-adapter.js","sourceRoot":"","sources":["../src/iwsdk-adapter.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * IWSDK implementation of {@link RuntimeAdapter}. IWSDK owns the render loop, so\n * frames are pushed in rather than pulled: the `ServiceBridgeSystem` (a normal\n * IWSDK system) calls {@link IWSDKAdapter.emitFrame} once per frame and the\n * adapter notifies subscribed services.\n *\n * Capabilities are derived from the live session on construction and on every\n * visibility change, through the core's shared `deriveCapabilities`, with a\n * manual override layer on top. Session lifecycle is\n * exposed through {@link IWSDKAdapter.session}, over the world's `launchXR` and\n * `exitXR` entry points.\n */\nimport {\n  DEFAULT_CAPABILITIES,\n  DEFAULT_SESSION_TIMEOUT_MS,\n  deriveCapabilities,\n  type AdapterCapabilities,\n  type CapabilitiesListener,\n  type FrameInfo,\n  type FrameListener,\n  type RuntimeAdapter,\n  type SessionFacet,\n  type SessionMode,\n  type SessionRequestOptions,\n  type SessionResult,\n  type SessionState,\n  type SessionVisibility,\n  type Unsubscribe,\n} from \"@realitycollective/service-framework\";\nimport type { IWSDKWorldLike } from \"./iwsdk-host.js\";\n\ntype SessionStateListener = (state: SessionState) => void;\ntype SessionVisibilityListener = (visibility: SessionVisibility) => void;\n\n/** How often the session waits re-check the world when the signal is silent. */\nconst SESSION_POLL_INTERVAL_MS = 50;\n\nconst SESSION_VISIBILITY_VALUES: ReadonlySet<string> = new Set([\n  \"visible\",\n  \"visible-blurred\",\n  \"hidden\",\n  \"non-immersive\",\n]);\n\n/**\n * IWSDK's visibility signal carries the WebXR visibility strings. Anything this\n * adapter does not recognise is reported as `\"hidden\"`, because treating an\n * unknown state as visible 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/** A `request()` or `end()` waiting for the world to reach some state. */\ninterface PendingWait {\n  readonly predicate: () => boolean;\n  readonly resolve: (settled: boolean) => void;\n  readonly timer: ReturnType<typeof setTimeout>;\n  readonly interval: ReturnType<typeof setInterval>;\n}\n\nexport class IWSDKAdapter 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 pendingWaits = new Set<PendingWait>();\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 unsubscribeVisibility: Unsubscribe | undefined;\n\n  /** Session lifecycle over the world's `launchXR` / `exitXR` entry points. */\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(private readonly world: IWSDKWorldLike) {\n    this.unsubscribeVisibility = world.visibilityState.subscribe?.((value) => {\n      this.handleVisibilityChange(value);\n    });\n\n    this.derived = deriveCapabilities(this.world.session);\n    this.capabilities = this.derived;\n    this.sessionState = this.hasSession() ? \"active\" : \"none\";\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 IWSDK `World` this adapter is bound to. */\n  public getWorld(): IWSDKWorldLike {\n    return this.world;\n  }\n\n  /**\n   * Re-read the live session and publish any capability change. The adapter\n   * does this itself whenever the visibility signal fires; call it directly on\n   * a host whose signal has no `subscribe`, or after the host enables a feature\n   * mid-session.\n   */\n  public refreshCapabilities(): void {\n    this.derived = deriveCapabilities(this.world.session);\n    this.publishCapabilities();\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 IWSDKAdapter.clearCapabilityOverrides} or\n   * {@link IWSDKAdapter.dispose}. Subscribers are notified if the effective\n   * capabilities changed.\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  /** Called once per frame by the ECS bridge system. */\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   * Release everything the adapter holds: the visibility subscription, any\n   * in-flight session wait, the manual overrides and every listener.\n   */\n  public dispose(): void {\n    this.unsubscribeVisibility?.();\n    this.unsubscribeVisibility = undefined;\n\n    for (const wait of Array.from(this.pendingWaits)) {\n      this.settleWait(wait, false);\n    }\n\n    this.overrides = {};\n    this.frameListeners.clear();\n    this.capabilitiesListeners.clear();\n    this.stateListeners.clear();\n    this.visibilityListeners.clear();\n  }\n\n  private hasSession(): boolean {\n    return Boolean(this.world.session);\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    ) {\n      return;\n    }\n\n    this.capabilities = next;\n    this.capabilitiesListeners.forEach((listener) => listener(next));\n  }\n\n  private handleVisibilityChange(value: unknown): void {\n    this.refreshCapabilities();\n    this.syncSessionState();\n    this.checkWaits();\n\n    const visibility = toSessionVisibility(value);\n    this.visibilityListeners.forEach((listener) => listener(visibility));\n  }\n\n  /**\n   * Follow the world when nothing local is mid-transition. `request()` and\n   * `end()` own the state while they run, so the signal does not fight them.\n   */\n  private syncSessionState(): void {\n    if (this.sessionState === \"requesting\" || this.sessionState === \"ending\") {\n      return;\n    }\n\n    this.setSessionState(this.hasSession() ? \"active\" : \"none\");\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 launch = this.world.launchXR;\n\n    if (!launch) {\n      return { ok: false, reason: \"unsupported\" };\n    }\n\n    const timeoutMs = options?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;\n    this.setSessionState(\"requesting\");\n\n    try {\n      // IWSDK reads `XROptions.sessionMode`; its `SessionMode` enum values are the\n      // WebXR mode strings, so the facet mode passes through unchanged.\n      launch.call(this.world, { sessionMode: mode });\n    } catch (error) {\n      this.setSessionState(\"none\");\n      return { ok: false, reason: \"unsupported\", error };\n    }\n\n    const started = await this.waitFor(() => this.hasSession(), timeoutMs);\n\n    if (!started) {\n      this.setSessionState(\"none\");\n      return { ok: false, reason: \"timeout\" };\n    }\n\n    this.setSessionState(\"active\");\n    this.refreshCapabilities();\n    return { ok: true };\n  }\n\n  private async endSession(): Promise<void> {\n    if (this.sessionState === \"none\") {\n      return;\n    }\n\n    const exit = this.world.exitXR;\n    this.setSessionState(\"ending\");\n\n    if (exit) {\n      exit.call(this.world);\n    }\n\n    await this.waitFor(() => !this.hasSession(), DEFAULT_SESSION_TIMEOUT_MS);\n    this.setSessionState(\"none\");\n    this.refreshCapabilities();\n  }\n\n  /**\n   * Resolve `true` once `predicate` holds, `false` on timeout. The visibility\n   * signal drives this where the host has one; the interval is the fallback for\n   * a host whose signal does not push, and for a session that appears without\n   * a visibility transition.\n   */\n  private waitFor(predicate: () => boolean, timeoutMs: number): Promise<boolean> {\n    if (predicate()) {\n      return Promise.resolve(true);\n    }\n\n    return new Promise<boolean>((resolve) => {\n      const wait: PendingWait = {\n        predicate,\n        resolve,\n        timer: setTimeout(() => this.settleWait(wait, false), timeoutMs),\n        interval: setInterval(() => this.checkWaits(), SESSION_POLL_INTERVAL_MS),\n      };\n\n      this.pendingWaits.add(wait);\n    });\n  }\n\n  private checkWaits(): void {\n    for (const wait of Array.from(this.pendingWaits)) {\n      if (wait.predicate()) {\n        this.settleWait(wait, true);\n      }\n    }\n  }\n\n  private settleWait(wait: PendingWait, settled: boolean): void {\n    this.pendingWaits.delete(wait);\n    clearTimeout(wait.timer);\n    clearInterval(wait.interval);\n    wait.resolve(settled);\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/dist/iwsdk-host.d.ts

@@ -7,14 +7,52 @@
  * works without bumping this package. Consumers pass the real `World`,
  * `createSystem` and `VisibilityState.Visible` value through
  * {@link makeServiceBridgeSystem}.
+ *
+ * Every member added here is optional, so a world that only carries the
+ * visibility signal - the shape the 1.0.x bridge accepted - still type-checks.
+ */
+import type { CapabilityInputSourceLike, CapabilitySessionLike } from "@realitycollective/service-framework";
+/**
+ * IWSDK exposes reactive values as `{ value }` signals. The bridge only reads
+ * `.value`; the adapter also subscribes when the signal supports it, which is
+ * how it learns that a session came or went without polling every frame.
  */
-/** IWSDK exposes reactive values as `{ value }` signals; the bridge only reads `.value`. */
 export interface IWSDKSignalLike<TValue> {
     readonly value: TValue;
+    /** Optional push notification. Returns an unsubscribe handle. */
+    subscribe?(listener: (value: TValue) => void): () => void;
+}
+/** One entry of `XRSession.inputSources`; `hand` is set for a tracked hand. */
+export type IWSDKInputSourceLike = CapabilityInputSourceLike;
+/**
+ * The slice of the live `XRSession` the adapter reads to derive capabilities.
+ * It is the core's {@link CapabilitySessionLike} with `inputSources` required,
+ * because an IWSDK world always carries the collection, and the adapter hands
+ * the session straight to the core's `deriveCapabilities`.
+ */
+export interface IWSDKSessionLike extends CapabilitySessionLike {
+    readonly inputSources: Iterable<IWSDKInputSourceLike>;
+}
+/**
+ * The slice of an IWSDK `World` the bridge and adapter read: the visibility
+ * signal, the live session, and the session entry points.
+ */
+/**
+ * The slice of IWSDK `XROptions` the session facet passes to `launchXR`.
+ * `sessionMode` carries the WebXR mode string ("immersive-vr", "immersive-ar",
+ * "inline"), which is also the value of IWSDK's `SessionMode` enum members.
+ */
+export interface IWSDKXROptionsLike {
+    readonly sessionMode?: string;
 }
-/** The slice of an IWSDK `World` the bridge reads: the visibility signal. */
 export interface IWSDKWorldLike<TVisibility = unknown> {
     readonly visibilityState: IWSDKSignalLike<TVisibility>;
+    /** The live XR session, or null/absent when the app is running in 2D. */
+    readonly session?: IWSDKSessionLike | null;
+    /** IWSDK's session entry point. Absent on a host that cannot start one. */
+    launchXR?(options?: IWSDKXROptionsLike): void;
+    /** IWSDK's session exit point. Absent on a host that cannot end one. */
+    exitXR?(): void;
 }
 /** The per-frame entry point IWSDK invokes on a registered system. */
 export interface IWSDKSystemLike {

package/dist/iwsdk-host.js

@@ -7,6 +7,9 @@
  * works without bumping this package. Consumers pass the real `World`,
  * `createSystem` and `VisibilityState.Visible` value through
  * {@link makeServiceBridgeSystem}.
+ *
+ * Every member added here is optional, so a world that only carries the
+ * visibility signal - the shape the 1.0.x bridge accepted - still type-checks.
  */
 export {};
 //# sourceMappingURL=iwsdk-host.js.map

package/dist/iwsdk-host.js.map

@@ -1 +1 @@
-{"version":3,"file":"iwsdk-host.js","sourceRoot":"","sources":["../src/iwsdk-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG","sourcesContent":["/**\n * Structural contracts for the slice of `@iwsdk/core` this shim touches.\n *\n * Mirrors the approach the three.js and Babylon.js bridges take with their\n * engine packages: the shim never imports `@iwsdk/core` directly, so it builds\n * and unit-tests with no IWSDK / WebXR / headset present, and any 0.4.x IWSDK\n * works without bumping this package. Consumers pass the real `World`,\n * `createSystem` and `VisibilityState.Visible` value through\n * {@link makeServiceBridgeSystem}.\n */\n\n/** IWSDK exposes reactive values as `{ value }` signals; the bridge only reads `.value`. */\nexport interface IWSDKSignalLike<TValue> {\n  readonly value: TValue;\n}\n\n/** The slice of an IWSDK `World` the bridge reads: the visibility signal. */\nexport interface IWSDKWorldLike<TVisibility = unknown> {\n  readonly visibilityState: IWSDKSignalLike<TVisibility>;\n}\n\n/** The per-frame entry point IWSDK invokes on a registered system. */\nexport interface IWSDKSystemLike {\n  update(delta: number, time: number): void;\n}\n\n/** Constructor shape of the base class IWSDK's `createSystem` returns. */\nexport type IWSDKSystemConstructor = new (...args: unknown[]) => IWSDKSystemLike;\n\n/**\n * Structural shape of IWSDK's `createSystem` factory. `createSystem(schema)`\n * returns a base system class that the bridge extends; the bridge passes an\n * empty schema because it queries no ECS components.\n */\nexport type CreateSystemLike = (schema?: Record<string, unknown>) => IWSDKSystemConstructor;\n"]}
+{"version":3,"file":"iwsdk-host.js","sourceRoot":"","sources":["../src/iwsdk-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG","sourcesContent":["/**\n * Structural contracts for the slice of `@iwsdk/core` this shim touches.\n *\n * Mirrors the approach the three.js and Babylon.js bridges take with their\n * engine packages: the shim never imports `@iwsdk/core` directly, so it builds\n * and unit-tests with no IWSDK / WebXR / headset present, and any 0.4.x IWSDK\n * works without bumping this package. Consumers pass the real `World`,\n * `createSystem` and `VisibilityState.Visible` value through\n * {@link makeServiceBridgeSystem}.\n *\n * Every member added here is optional, so a world that only carries the\n * visibility signal - the shape the 1.0.x bridge accepted - still type-checks.\n */\n\nimport type {\n  CapabilityInputSourceLike,\n  CapabilitySessionLike,\n} from \"@realitycollective/service-framework\";\n\n/**\n * IWSDK exposes reactive values as `{ value }` signals. The bridge only reads\n * `.value`; the adapter also subscribes when the signal supports it, which is\n * how it learns that a session came or went without polling every frame.\n */\nexport interface IWSDKSignalLike<TValue> {\n  readonly value: TValue;\n  /** Optional push notification. Returns an unsubscribe handle. */\n  subscribe?(listener: (value: TValue) => void): () => void;\n}\n\n/** One entry of `XRSession.inputSources`; `hand` is set for a tracked hand. */\nexport type IWSDKInputSourceLike = CapabilityInputSourceLike;\n\n/**\n * The slice of the live `XRSession` the adapter reads to derive capabilities.\n * It is the core's {@link CapabilitySessionLike} with `inputSources` required,\n * because an IWSDK world always carries the collection, and the adapter hands\n * the session straight to the core's `deriveCapabilities`.\n */\nexport interface IWSDKSessionLike extends CapabilitySessionLike {\n  readonly inputSources: Iterable<IWSDKInputSourceLike>;\n}\n\n/**\n * The slice of an IWSDK `World` the bridge and adapter read: the visibility\n * signal, the live session, and the session entry points.\n */\n/**\n * The slice of IWSDK `XROptions` the session facet passes to `launchXR`.\n * `sessionMode` carries the WebXR mode string (\"immersive-vr\", \"immersive-ar\",\n * \"inline\"), which is also the value of IWSDK's `SessionMode` enum members.\n */\nexport interface IWSDKXROptionsLike {\n  readonly sessionMode?: string;\n}\n\nexport interface IWSDKWorldLike<TVisibility = unknown> {\n  readonly visibilityState: IWSDKSignalLike<TVisibility>;\n  /** The live XR session, or null/absent when the app is running in 2D. */\n  readonly session?: IWSDKSessionLike | null;\n  /** IWSDK's session entry point. Absent on a host that cannot start one. */\n  launchXR?(options?: IWSDKXROptionsLike): void;\n  /** IWSDK's session exit point. Absent on a host that cannot end one. */\n  exitXR?(): void;\n}\n\n/** The per-frame entry point IWSDK invokes on a registered system. */\nexport interface IWSDKSystemLike {\n  update(delta: number, time: number): void;\n}\n\n/** Constructor shape of the base class IWSDK's `createSystem` returns. */\nexport type IWSDKSystemConstructor = new (...args: unknown[]) => IWSDKSystemLike;\n\n/**\n * Structural shape of IWSDK's `createSystem` factory. `createSystem(schema)`\n * returns a base system class that the bridge extends; the bridge passes an\n * empty schema because it queries no ECS components.\n */\nexport type CreateSystemLike = (schema?: Record<string, unknown>) => IWSDKSystemConstructor;\n"]}

package/dist/service-bridge-system.d.ts

@@ -1,8 +1,12 @@
 /**
  * The single ECS-services bridge. A normal IWSDK system that, each frame:
  *   - maps IWSDK `visibilityState` to manager focus/pause (auto-pause when the
- *     headset is removed), and
- *   - drives the adapter's per-frame fan-out via {@link IWSDKAdapter.emitFrame}.
+ *     headset is removed),
+ *   - drives the adapter's per-frame fan-out via {@link IWSDKAdapter.emitFrame},
+ *     and
+ *   - emits the scheduler's `renderTick` channel, the same one the three.js and
+ *     Babylon.js bridges emit, so a service written against the scheduler runs
+ *     unchanged under IWSDK.
  *
  * Game logic is only ticked while the session is visible/focused: in the
  * browser / 2D preview the host app shows its own gate (e.g. an "Enter VR"

package/dist/service-bridge-system.js

@@ -1,3 +1,5 @@
+/** Milliseconds per second, for the IWSDK seconds-to-scheduler-milliseconds conversion. */
+const MS_PER_SECOND = 1000;
 /**
  * Builds the IWSDK `ServiceBridgeSystem` class. Register the returned class with
  * the world (`world.registerSystem(makeServiceBridgeSystem({ ... }))`); IWSDK
@@ -6,6 +8,7 @@
 export function makeServiceBridgeSystem(options) {
     const { adapter, manager, world, createSystem, visibleState } = options;
     let lastFocused;
+    let frame = 0;
     return class ServiceBridgeSystem extends createSystem({}) {
         update(delta, time) {
             const focused = world.visibilityState.value === visibleState;
@@ -18,6 +21,15 @@ export function makeServiceBridgeSystem(options) {
             // preview and while the headset is removed (visible-blurred).
             if (focused) {
                 adapter.emitFrame(time, delta);
+                // IWSDK reports `delta` in seconds; LifecycleContext.deltaTime is in
+                // milliseconds, as the three.js and Babylon.js bridges emit it.
+                const context = {
+                    timestamp: time,
+                    deltaTime: delta * MS_PER_SECOND,
+                    frame: ++frame,
+                    source: "iwsdk",
+                };
+                manager.scheduler.emit("renderTick", context);
             }
         }
     };

package/dist/service-bridge-system.js.map

@@ -1 +1 @@
-{"version":3,"file":"service-bridge-system.js","sourceRoot":"","sources":["../src/service-bridge-system.ts"],"names":[],"mappings":"AAqCA;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAgD;IAEhD,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IACxE,IAAI,WAAgC,CAAC;IAErC,OAAO,MAAM,mBAAoB,SAAQ,YAAY,CAAC,EAAE,CAAC;QACvC,MAAM,CAAC,KAAa,EAAE,IAAY;YAChD,MAAM,OAAO,GAAG,KAAK,CAAC,eAAe,CAAC,KAAK,KAAK,YAAY,CAAC;YAE7D,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;gBAC5B,WAAW,GAAG,OAAO,CAAC;gBACtB,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;gBACjC,OAAO,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;YAChD,CAAC;YAED,oEAAoE;YACpE,8DAA8D;YAC9D,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The single ECS-services bridge. A normal IWSDK system that, each frame:\n *   - maps IWSDK `visibilityState` to manager focus/pause (auto-pause when the\n *     headset is removed), and\n *   - drives the adapter's per-frame fan-out via {@link IWSDKAdapter.emitFrame}.\n *\n * Game logic is only ticked while the session is visible/focused: in the\n * browser / 2D preview the host app shows its own gate (e.g. an \"Enter VR\"\n * overlay) and the services stay idle until the player enters VR.\n *\n * This is the only place the engine loop touches the service layer; services\n * themselves never see IWSDK. The IWSDK primitives (`createSystem` and the\n * `VisibilityState.Visible` value) are injected so this package never imports\n * `@iwsdk/core` - mirroring how the three.js / Babylon.js bridges keep their\n * engine packages at arm's length.\n */\nimport type { ServiceManager } from \"@realitycollective/service-framework\";\nimport type { IWSDKAdapter } from \"./iwsdk-adapter.js\";\nimport type { CreateSystemLike, IWSDKWorldLike } from \"./iwsdk-host.js\";\n\nexport interface ServiceBridgeSystemOptions<TVisibility = unknown> {\n  /** The passive frame source fanned out to services. */\n  readonly adapter: IWSDKAdapter;\n  /** The service manager whose focus/pause signals are driven by visibility. */\n  readonly manager: ServiceManager;\n  /** The IWSDK world whose `visibilityState` is read each frame. */\n  readonly world: IWSDKWorldLike<TVisibility>;\n  /** IWSDK's `createSystem` factory (from `@iwsdk/core`). */\n  readonly createSystem: CreateSystemLike;\n  /**\n   * The `VisibilityState` value that means the session is visible/focused\n   * (IWSDK `VisibilityState.Visible`). The bridge ticks services only while\n   * `world.visibilityState.value === visibleState`.\n   */\n  readonly visibleState: TVisibility;\n}\n\n/**\n * Builds the IWSDK `ServiceBridgeSystem` class. Register the returned class with\n * the world (`world.registerSystem(makeServiceBridgeSystem({ ... }))`); IWSDK\n * then calls its `update(delta, time)` once per frame.\n */\nexport function makeServiceBridgeSystem<TVisibility>(\n  options: ServiceBridgeSystemOptions<TVisibility>,\n) {\n  const { adapter, manager, world, createSystem, visibleState } = options;\n  let lastFocused: boolean | undefined;\n\n  return class ServiceBridgeSystem extends createSystem({}) {\n    public override update(delta: number, time: number): void {\n      const focused = world.visibilityState.value === visibleState;\n\n      if (focused !== lastFocused) {\n        lastFocused = focused;\n        manager.emitFocusChange(focused);\n        manager.emitPauseChange({ paused: !focused });\n      }\n\n      // Only run game logic while visible/focused; idle in the 2D/browser\n      // preview and while the headset is removed (visible-blurred).\n      if (focused) {\n        adapter.emitFrame(time, delta);\n      }\n    }\n  };\n}\n"]}
+{"version":3,"file":"service-bridge-system.js","sourceRoot":"","sources":["../src/service-bridge-system.ts"],"names":[],"mappings":"AAwBA,2FAA2F;AAC3F,MAAM,aAAa,GAAG,IAAI,CAAC;AAmB3B;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAgD;IAEhD,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IACxE,IAAI,WAAgC,CAAC;IACrC,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,OAAO,MAAM,mBAAoB,SAAQ,YAAY,CAAC,EAAE,CAAC;QACvC,MAAM,CAAC,KAAa,EAAE,IAAY;YAChD,MAAM,OAAO,GAAG,KAAK,CAAC,eAAe,CAAC,KAAK,KAAK,YAAY,CAAC;YAE7D,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;gBAC5B,WAAW,GAAG,OAAO,CAAC;gBACtB,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;gBACjC,OAAO,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;YAChD,CAAC;YAED,oEAAoE;YACpE,8DAA8D;YAC9D,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBAE/B,qEAAqE;gBACrE,gEAAgE;gBAChE,MAAM,OAAO,GAAqB;oBAChC,SAAS,EAAE,IAAI;oBACf,SAAS,EAAE,KAAK,GAAG,aAAa;oBAChC,KAAK,EAAE,EAAE,KAAK;oBACd,MAAM,EAAE,OAAO;iBAChB,CAAC;gBAEF,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The single ECS-services bridge. A normal IWSDK system that, each frame:\n *   - maps IWSDK `visibilityState` to manager focus/pause (auto-pause when the\n *     headset is removed),\n *   - drives the adapter's per-frame fan-out via {@link IWSDKAdapter.emitFrame},\n *     and\n *   - emits the scheduler's `renderTick` channel, the same one the three.js and\n *     Babylon.js bridges emit, so a service written against the scheduler runs\n *     unchanged under IWSDK.\n *\n * Game logic is only ticked while the session is visible/focused: in the\n * browser / 2D preview the host app shows its own gate (e.g. an \"Enter VR\"\n * overlay) and the services stay idle until the player enters VR.\n *\n * This is the only place the engine loop touches the service layer; services\n * themselves never see IWSDK. The IWSDK primitives (`createSystem` and the\n * `VisibilityState.Visible` value) are injected so this package never imports\n * `@iwsdk/core` - mirroring how the three.js / Babylon.js bridges keep their\n * engine packages at arm's length.\n */\nimport type { LifecycleContext, ServiceManager } from \"@realitycollective/service-framework\";\nimport type { IWSDKAdapter } from \"./iwsdk-adapter.js\";\nimport type { CreateSystemLike, IWSDKWorldLike } from \"./iwsdk-host.js\";\n\n/** Milliseconds per second, for the IWSDK seconds-to-scheduler-milliseconds conversion. */\nconst MS_PER_SECOND = 1000;\n\nexport interface ServiceBridgeSystemOptions<TVisibility = unknown> {\n  /** The passive frame source fanned out to services. */\n  readonly adapter: IWSDKAdapter;\n  /** The service manager whose focus/pause signals are driven by visibility. */\n  readonly manager: ServiceManager;\n  /** The IWSDK world whose `visibilityState` is read each frame. */\n  readonly world: IWSDKWorldLike<TVisibility>;\n  /** IWSDK's `createSystem` factory (from `@iwsdk/core`). */\n  readonly createSystem: CreateSystemLike;\n  /**\n   * The `VisibilityState` value that means the session is visible/focused\n   * (IWSDK `VisibilityState.Visible`). The bridge ticks services only while\n   * `world.visibilityState.value === visibleState`.\n   */\n  readonly visibleState: TVisibility;\n}\n\n/**\n * Builds the IWSDK `ServiceBridgeSystem` class. Register the returned class with\n * the world (`world.registerSystem(makeServiceBridgeSystem({ ... }))`); IWSDK\n * then calls its `update(delta, time)` once per frame.\n */\nexport function makeServiceBridgeSystem<TVisibility>(\n  options: ServiceBridgeSystemOptions<TVisibility>,\n) {\n  const { adapter, manager, world, createSystem, visibleState } = options;\n  let lastFocused: boolean | undefined;\n  let frame = 0;\n\n  return class ServiceBridgeSystem extends createSystem({}) {\n    public override update(delta: number, time: number): void {\n      const focused = world.visibilityState.value === visibleState;\n\n      if (focused !== lastFocused) {\n        lastFocused = focused;\n        manager.emitFocusChange(focused);\n        manager.emitPauseChange({ paused: !focused });\n      }\n\n      // Only run game logic while visible/focused; idle in the 2D/browser\n      // preview and while the headset is removed (visible-blurred).\n      if (focused) {\n        adapter.emitFrame(time, delta);\n\n        // IWSDK reports `delta` in seconds; LifecycleContext.deltaTime is in\n        // milliseconds, as the three.js and Babylon.js bridges emit it.\n        const context: LifecycleContext = {\n          timestamp: time,\n          deltaTime: delta * MS_PER_SECOND,\n          frame: ++frame,\n          source: \"iwsdk\",\n        };\n\n        manager.scheduler.emit(\"renderTick\", context);\n      }\n    }\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realitycollective/service-framework-iwsdk",
-  "version": "1.0.1-preview.0",
+  "version": "1.0.1-preview.2",
   "description": "Meta IWSDK (WebXR) frame-source bindings for the Reality Collective TypeScript Service Framework.",
   "author": "Reality Collective",
   "license": "MIT",
@@ -35,16 +35,8 @@
   "bugs": {
     "url": "https://github.com/realitycollective/com.realitycollective.service-framework.ts/issues"
   },
-  "peerDependencies": {
-    "@iwsdk/core": ">=0.4.0 <0.5.0"
-  },
-  "peerDependenciesMeta": {
-    "@iwsdk/core": {
-      "optional": true
-    }
-  },
   "dependencies": {
-    "@realitycollective/service-framework": "^1.0.1-preview.0"
+    "@realitycollective/service-framework": "^1.0.1-preview.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

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

@@ -1,20 +0,0 @@
-/**
- * Headless {@link RuntimeAdapter} for tests. Services run against this with no
- * IWSDK / renderer / headset; tests drive the loop by calling
- * {@link MockRuntimeAdapter.emitFrame} and refine gating with
- * {@link MockRuntimeAdapter.setCapabilities}.
- */
-import { type AdapterCapabilities, type CapabilitiesListener, type FrameListener, type RuntimeAdapter, type Unsubscribe } from "./runtime-adapter.js";
-export declare class MockRuntimeAdapter implements RuntimeAdapter {
-    private readonly frameListeners;
-    private readonly capabilitiesListeners;
-    private capabilities;
-    constructor(capabilities?: Partial<AdapterCapabilities>);
-    onFrame(listener: FrameListener): Unsubscribe;
-    getCapabilities(): AdapterCapabilities;
-    onCapabilitiesChange(listener: CapabilitiesListener): Unsubscribe;
-    /** Refine capabilities in tests; notifies subscribers. */
-    setCapabilities(capabilities: Partial<AdapterCapabilities>): void;
-    /** Drive a frame in tests. */
-    emitFrame(timestamp?: number, delta?: number): void;
-}

package/dist/mock-runtime-adapter.js

@@ -1,40 +0,0 @@
-/**
- * Headless {@link RuntimeAdapter} for tests. Services run against this with no
- * IWSDK / renderer / headset; tests drive the loop by calling
- * {@link MockRuntimeAdapter.emitFrame} and refine gating with
- * {@link MockRuntimeAdapter.setCapabilities}.
- */
-import { DEFAULT_CAPABILITIES, } from "./runtime-adapter.js";
-export class MockRuntimeAdapter {
-    frameListeners = new Set();
-    capabilitiesListeners = new Set();
-    capabilities;
-    constructor(capabilities = {}) {
-        this.capabilities = { ...DEFAULT_CAPABILITIES, ...capabilities };
-    }
-    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);
-        };
-    }
-    /** Refine capabilities in tests; notifies subscribers. */
-    setCapabilities(capabilities) {
-        this.capabilities = { ...this.capabilities, ...capabilities };
-        this.capabilitiesListeners.forEach((listener) => listener(this.capabilities));
-    }
-    /** Drive a frame in tests. */
-    emitFrame(timestamp = 0, delta = 1 / 72) {
-        this.frameListeners.forEach((listener) => listener({ timestamp, delta }));
-    }
-}
-//# sourceMappingURL=mock-runtime-adapter.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"mock-runtime-adapter.js","sourceRoot":"","sources":["../src/mock-runtime-adapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,oBAAoB,GAMrB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,OAAO,kBAAkB;IACZ,cAAc,GAAG,IAAI,GAAG,EAAiB,CAAC;IAC1C,qBAAqB,GAAG,IAAI,GAAG,EAAwB,CAAC;IACjE,YAAY,CAAsB;IAE1C,YAAmB,eAA6C,EAAE;QAChE,IAAI,CAAC,YAAY,GAAG,EAAE,GAAG,oBAAoB,EAAE,GAAG,YAAY,EAAE,CAAC;IACnE,CAAC;IAEM,OAAO,CAAC,QAAuB;QACpC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClC,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvC,CAAC,CAAC;IACJ,CAAC;IAEM,eAAe;QACpB,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAEM,oBAAoB,CAAC,QAA8B;QACxD,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9C,CAAC,CAAC;IACJ,CAAC;IAED,0DAA0D;IACnD,eAAe,CAAC,YAA0C;QAC/D,IAAI,CAAC,YAAY,GAAG,EAAE,GAAG,IAAI,CAAC,YAAY,EAAE,GAAG,YAAY,EAAE,CAAC;QAC9D,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IAChF,CAAC;IAED,8BAA8B;IACvB,SAAS,CAAC,SAAS,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,GAAG,EAAE;QAC5C,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAC5E,CAAC;CACF","sourcesContent":["/**\n * Headless {@link RuntimeAdapter} for tests. Services run against this with no\n * IWSDK / renderer / headset; tests drive the loop by calling\n * {@link MockRuntimeAdapter.emitFrame} and refine gating with\n * {@link MockRuntimeAdapter.setCapabilities}.\n */\nimport {\n  DEFAULT_CAPABILITIES,\n  type AdapterCapabilities,\n  type CapabilitiesListener,\n  type FrameListener,\n  type RuntimeAdapter,\n  type Unsubscribe,\n} from \"./runtime-adapter.js\";\n\nexport class MockRuntimeAdapter implements RuntimeAdapter {\n  private readonly frameListeners = new Set<FrameListener>();\n  private readonly capabilitiesListeners = new Set<CapabilitiesListener>();\n  private capabilities: AdapterCapabilities;\n\n  public constructor(capabilities: Partial<AdapterCapabilities> = {}) {\n    this.capabilities = { ...DEFAULT_CAPABILITIES, ...capabilities };\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  /** Refine capabilities in tests; notifies subscribers. */\n  public setCapabilities(capabilities: Partial<AdapterCapabilities>): void {\n    this.capabilities = { ...this.capabilities, ...capabilities };\n    this.capabilitiesListeners.forEach((listener) => listener(this.capabilities));\n  }\n\n  /** Drive a frame in tests. */\n  public emitFrame(timestamp = 0, delta = 1 / 72): void {\n    this.frameListeners.forEach((listener) => listener({ timestamp, delta }));\n  }\n}\n"]}

package/dist/runtime-adapter.d.ts

@@ -1,38 +0,0 @@
-/**
- * Runtime adapter contract (IWSDK-only, minimal frame-source).
- *
- * Trimmed to what an IWSDK-only client needs: a per-frame fan-out and
- * capability flags. IWSDK already owns sessions, input and rendering, so the
- * adapter deliberately does NOT re-abstract those. {@link MockRuntimeAdapter}
- * implements this same interface so services can be unit-tested headless.
- */
-export type Unsubscribe = () => void;
-export interface FrameInfo {
-    /** Frame timestamp in milliseconds (IWSDK system `time`). */
-    readonly timestamp: number;
-    /** Seconds elapsed since the previous frame (IWSDK system `delta`). */
-    readonly delta: number;
-}
-/** XR capabilities services gate on (e.g. passthrough requires `immersive`). */
-export interface AdapterCapabilities {
-    readonly immersive: boolean;
-    readonly handTracking: boolean;
-    readonly planeDetection: boolean;
-    readonly passthrough: boolean;
-}
-export declare const DEFAULT_CAPABILITIES: AdapterCapabilities;
-export type FrameListener = (frame: FrameInfo) => void;
-export type CapabilitiesListener = (capabilities: AdapterCapabilities) => void;
-export interface RuntimeAdapter {
-    /** Subscribe to per-frame updates; returns an unsubscribe handle. */
-    onFrame(listener: FrameListener): Unsubscribe;
-    /** Current XR capabilities (may change once a session is established). */
-    getCapabilities(): AdapterCapabilities;
-    /**
-     * Subscribe to capability changes; returns an unsubscribe handle. Mirrors
-     * {@link RuntimeAdapter.onFrame} so gating services can react to a session
-     * coming online instead of polling {@link RuntimeAdapter.getCapabilities}
-     * every frame.
-     */
-    onCapabilitiesChange(listener: CapabilitiesListener): Unsubscribe;
-}

package/dist/runtime-adapter.js

@@ -1,15 +0,0 @@
-/**
- * Runtime adapter contract (IWSDK-only, minimal frame-source).
- *
- * Trimmed to what an IWSDK-only client needs: a per-frame fan-out and
- * capability flags. IWSDK already owns sessions, input and rendering, so the
- * adapter deliberately does NOT re-abstract those. {@link MockRuntimeAdapter}
- * implements this same interface so services can be unit-tested headless.
- */
-export const DEFAULT_CAPABILITIES = {
-    immersive: false,
-    handTracking: false,
-    planeDetection: false,
-    passthrough: false,
-};
-//# sourceMappingURL=runtime-adapter.js.map

package/dist/runtime-adapter.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"runtime-adapter.js","sourceRoot":"","sources":["../src/runtime-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH,MAAM,CAAC,MAAM,oBAAoB,GAAwB;IACvD,SAAS,EAAE,KAAK;IAChB,YAAY,EAAE,KAAK;IACnB,cAAc,EAAE,KAAK;IACrB,WAAW,EAAE,KAAK;CACnB,CAAC","sourcesContent":["/**\n * Runtime adapter contract (IWSDK-only, minimal frame-source).\n *\n * Trimmed to what an IWSDK-only client needs: a per-frame fan-out and\n * capability flags. IWSDK already owns sessions, input and rendering, so the\n * adapter deliberately does NOT re-abstract those. {@link MockRuntimeAdapter}\n * implements this same interface so services can be unit-tested headless.\n */\n\nexport type Unsubscribe = () => void;\n\nexport interface FrameInfo {\n  /** Frame timestamp in milliseconds (IWSDK system `time`). */\n  readonly timestamp: number;\n  /** Seconds elapsed since the previous frame (IWSDK system `delta`). */\n  readonly delta: number;\n}\n\n/** XR capabilities services gate on (e.g. passthrough requires `immersive`). */\nexport interface AdapterCapabilities {\n  readonly immersive: boolean;\n  readonly handTracking: boolean;\n  readonly planeDetection: boolean;\n  readonly passthrough: boolean;\n}\n\nexport const DEFAULT_CAPABILITIES: AdapterCapabilities = {\n  immersive: false,\n  handTracking: false,\n  planeDetection: false,\n  passthrough: false,\n};\n\nexport type FrameListener = (frame: FrameInfo) => void;\nexport type CapabilitiesListener = (capabilities: AdapterCapabilities) => void;\n\nexport interface RuntimeAdapter {\n  /** Subscribe to per-frame updates; returns an unsubscribe handle. */\n  onFrame(listener: FrameListener): Unsubscribe;\n  /** Current XR capabilities (may change once a session is established). */\n  getCapabilities(): AdapterCapabilities;\n  /**\n   * Subscribe to capability changes; returns an unsubscribe handle. Mirrors\n   * {@link RuntimeAdapter.onFrame} so gating services can react to a session\n   * coming online instead of polling {@link RuntimeAdapter.getCapabilities}\n   * every frame.\n   */\n  onCapabilitiesChange(listener: CapabilitiesListener): Unsubscribe;\n}\n"]}

package/dist/snapshot-service.d.ts

@@ -1,27 +0,0 @@
-/**
- * `SnapshotService` base - the "services own state" pattern. A snapshot service
- * owns one immutable state object and a pub/sub list: consumers (other services,
- * or the ECS presentation layer) subscribe and receive the current value
- * immediately, then every subsequent publish.
- *
- * It has no IWSDK dependency - only `@realitycollective/service-framework` - so
- * services that extend it stay unit-testable headless against
- * {@link MockRuntimeAdapter}.
- */
-import { BaseService } from "@realitycollective/service-framework";
-/**
- * The activation-context type a service constructor receives. Aliased here so
- * every service uses one consistent, framework-correct shape (matches the
- * `useFactory(context)` parameter the ServiceManager passes).
- */
-export type ServiceContext<TConfig = unknown> = ConstructorParameters<typeof BaseService<TConfig>>[0];
-export type SnapshotListener<TSnapshot> = (snapshot: TSnapshot) => void;
-export declare abstract class SnapshotService<TConfig, TSnapshot> extends BaseService<TConfig> {
-    protected snapshot: TSnapshot;
-    private readonly listeners;
-    protected constructor(context: ServiceContext<TConfig>, initialSnapshot: TSnapshot);
-    getSnapshot(): TSnapshot;
-    subscribe(listener: SnapshotListener<TSnapshot>): () => void;
-    protected publishSnapshot(snapshot: TSnapshot): void;
-    protected updateSnapshot(partial: Partial<TSnapshot>): void;
-}

package/dist/snapshot-service.js

@@ -1,37 +0,0 @@
-/**
- * `SnapshotService` base - the "services own state" pattern. A snapshot service
- * owns one immutable state object and a pub/sub list: consumers (other services,
- * or the ECS presentation layer) subscribe and receive the current value
- * immediately, then every subsequent publish.
- *
- * It has no IWSDK dependency - only `@realitycollective/service-framework` - so
- * services that extend it stay unit-testable headless against
- * {@link MockRuntimeAdapter}.
- */
-import { BaseService } from "@realitycollective/service-framework";
-export class SnapshotService extends BaseService {
-    snapshot;
-    listeners = new Set();
-    constructor(context, initialSnapshot) {
-        super(context);
-        this.snapshot = initialSnapshot;
-    }
-    getSnapshot() {
-        return this.snapshot;
-    }
-    subscribe(listener) {
-        this.listeners.add(listener);
-        listener(this.snapshot);
-        return () => {
-            this.listeners.delete(listener);
-        };
-    }
-    publishSnapshot(snapshot) {
-        this.snapshot = snapshot;
-        this.listeners.forEach((listener) => listener(this.snapshot));
-    }
-    updateSnapshot(partial) {
-        this.publishSnapshot({ ...this.snapshot, ...partial });
-    }
-}
-//# sourceMappingURL=snapshot-service.js.map

package/dist/snapshot-service.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"snapshot-service.js","sourceRoot":"","sources":["../src/snapshot-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AAYnE,MAAM,OAAgB,eAAoC,SAAQ,WAAoB;IAC1E,QAAQ,CAAY;IACb,SAAS,GAAG,IAAI,GAAG,EAA+B,CAAC;IAEpE,YAAsB,OAAgC,EAAE,eAA0B;QAChF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,QAAQ,GAAG,eAAe,CAAC;IAClC,CAAC;IAEM,WAAW;QAChB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAEM,SAAS,CAAC,QAAqC;QACpD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxB,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC,CAAC;IACJ,CAAC;IAES,eAAe,CAAC,QAAmB;QAC3C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChE,CAAC;IAES,cAAc,CAAC,OAA2B;QAClD,IAAI,CAAC,eAAe,CAAC,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACzD,CAAC;CACF","sourcesContent":["/**\n * `SnapshotService` base - the \"services own state\" pattern. A snapshot service\n * owns one immutable state object and a pub/sub list: consumers (other services,\n * or the ECS presentation layer) subscribe and receive the current value\n * immediately, then every subsequent publish.\n *\n * It has no IWSDK dependency - only `@realitycollective/service-framework` - so\n * services that extend it stay unit-testable headless against\n * {@link MockRuntimeAdapter}.\n */\nimport { BaseService } from \"@realitycollective/service-framework\";\n\n/**\n * The activation-context type a service constructor receives. Aliased here so\n * every service uses one consistent, framework-correct shape (matches the\n * `useFactory(context)` parameter the ServiceManager passes).\n */\nexport type ServiceContext<TConfig = unknown> =\n  ConstructorParameters<typeof BaseService<TConfig>>[0];\n\nexport type SnapshotListener<TSnapshot> = (snapshot: TSnapshot) => void;\n\nexport abstract class SnapshotService<TConfig, TSnapshot> extends BaseService<TConfig> {\n  protected snapshot: TSnapshot;\n  private readonly listeners = new Set<SnapshotListener<TSnapshot>>();\n\n  protected constructor(context: ServiceContext<TConfig>, initialSnapshot: TSnapshot) {\n    super(context);\n    this.snapshot = initialSnapshot;\n  }\n\n  public getSnapshot(): TSnapshot {\n    return this.snapshot;\n  }\n\n  public subscribe(listener: SnapshotListener<TSnapshot>): () => void {\n    this.listeners.add(listener);\n    listener(this.snapshot);\n    return () => {\n      this.listeners.delete(listener);\n    };\n  }\n\n  protected publishSnapshot(snapshot: TSnapshot): void {\n    this.snapshot = snapshot;\n    this.listeners.forEach((listener) => listener(this.snapshot));\n  }\n\n  protected updateSnapshot(partial: Partial<TSnapshot>): void {\n    this.publishSnapshot({ ...this.snapshot, ...partial });\n  }\n}\n"]}