@realitycollective/service-framework-three 1.0.0 → 1.0.1-preview.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+Change log for the Reality Collective Service Framework for TypeScript. All packages in this repository are versioned and released together; the version below is the one carried by the `v<version>` release tag.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Preview builds are not listed separately. The entry for a version accumulates while its previews are published, and is dated when that version is released.
+
+## [1.0.1]
+
+Packaging, tooling and documentation. No runtime behaviour changed, and no public API was added, removed or altered.
+
+### Added
+
+- 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.
+- A deploy stage in CI for `runtime-examples/*`, which were never built by CI before.
+- `.gitattributes`, pinning the repository to LF and marking lockfiles as generated.
+
+### Changed
+
+- 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
+
+- `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
+
+- 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.
+
+## [1.0.0] - 2026-06-18
+
+First release. Six packages, published together.
+
+### Added
+
+- `@realitycollective/service-framework` - the core runtime: `ServiceManager` with dependency-ordered start and stop, `BaseService` and `BaseServiceModule`, type-safe resolution through `createServiceToken`, the scheduler channels, an event service for service-to-service messaging, profile-based configuration and environment description.
+- `@realitycollective/service-framework-react` - `ServiceFrameworkProvider` plus the `useServiceManager`, `useService` and `useServices` hooks.
+- `@realitycollective/service-framework-three` - `ThreeRenderLoopBridge`, connecting `renderer.setAnimationLoop()` to the `renderTick` channel. Accepts anything with `setAnimationLoop`, so a renderer or a test double both work.
+- `@realitycollective/service-framework-client` - the React and three.js pieces wired together, so an app starts from a working runtime instead of assembling the scheduler and bridge by hand.
+- `@realitycollective/service-framework-babylon` - Babylon.js bindings, connecting `engine.runRenderLoop()` to the same `renderTick` channel the three.js bridge uses. A service written against `BaseService<TConfig>` runs unchanged on either renderer.
+- `@realitycollective/service-framework-iwsdk` - Meta IWSDK (WebXR) bindings. IWSDK owns its own render loop, so this package is a passive frame source: one system relays each frame to services and maps `visibilityState` onto focus and pause, so services pause when the headset comes off. Services depend only on `RuntimeAdapter`, never on `@iwsdk/core`.
+- A worked example in every package's `Examples/` folder, and two runnable Vite apps in `runtime-examples/`.
+
+[1.0.1]: https://github.com/realitycollective/com.realitycollective.service-framework.ts/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/realitycollective/com.realitycollective.service-framework.ts/releases/tag/v1.0.0

package/README.md

@@ -0,0 +1,43 @@
+# @realitycollective/service-framework-three
+
+**three.js render-loop bridge** for the Reality Collective TypeScript Service Framework - connects `renderer.setAnimationLoop()` to the framework's `renderTick` scheduler channel.
+
+```sh
+npm install @realitycollective/service-framework @realitycollective/service-framework-three
+```
+
+Services written against `BaseService<TConfig>` run unchanged on three.js, Babylon.js or IWSDK - only the bridge differs.
+
+## Usage
+
+```ts
+import { ManualScheduler, ServiceManager, createServiceProfile } from "@realitycollective/service-framework";
+import { ThreeRenderLoopBridge } from "@realitycollective/service-framework-three";
+import { WebGLRenderer } from "three";
+
+const scheduler = new ManualScheduler();
+const manager = new ServiceManager({ scheduler });
+
+manager.initializeProfile(createServiceProfile("my-app", [/* your service registrations */]));
+manager.start();
+
+const renderer = new WebGLRenderer({ canvas });
+const bridge = new ThreeRenderLoopBridge({ scheduler, host: renderer });
+bridge.start();
+// Every three.js frame now emits renderTick to all registered services.
+```
+
+`host` is anything with `setAnimationLoop` (the `AnimationLoopHostLike` interface), so a `WebGLRenderer`, `WebGPURenderer` or a test double all work.
+
+## Live examples
+
+- Weather client walkthrough: **[service-framework-weather.pages.dev](https://service-framework-weather.pages.dev)**
+- Client runtime reference: **[service-framework-client-app.pages.dev](https://service-framework-client-app.pages.dev)**
+
+## Documentation
+
+See the [repository README](https://github.com/realitycollective/com.realitycollective.service-framework.ts#readme) and this package's `Examples/` folder.
+
+## License
+
+MIT - see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -16,4 +16,3 @@ export declare class ThreeRenderLoopBridge {
     stop(): void;
     dispose(): void;
 }
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,MAAM,OAAO,qBAAqB;IAMb;IALX,kBAAkB,GAAG,KAAK,CAAC;IAC3B,KAAK,GAAG,CAAC,CAAC;IACV,aAAa,GAAG,CAAC,CAAC;IAE1B,YACmB,OAAqC;QAArC,YAAO,GAAP,OAAO,CAA8B;IACrD,CAAC;IAEG,KAAK;QACV,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAE/B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,SAAS,EAAE,EAAE;YAC/C,MAAM,OAAO,GAAqB;gBAChC,SAAS;gBACT,SAAS,EAAE,IAAI,CAAC,aAAa,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,aAAa;gBACzE,KAAK,EAAE,EAAE,IAAI,CAAC,KAAK;gBACnB,MAAM,EAAE,OAAO;aAChB,CAAC;YAEF,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;YAC/B,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;IACL,CAAC;IAEM,IAAI;QACT,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC7B,OAAO;QACT,CAAC;QAED,IAAI,CAAC,kBAAkB,GAAG,KAAK,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAEM,OAAO;QACZ,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;CACF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,MAAM,OAAO,qBAAqB;IAMb;IALX,kBAAkB,GAAG,KAAK,CAAC;IAC3B,KAAK,GAAG,CAAC,CAAC;IACV,aAAa,GAAG,CAAC,CAAC;IAE1B,YACmB,OAAqC;QAArC,YAAO,GAAP,OAAO,CAA8B;IACrD,CAAC;IAEG,KAAK;QACV,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAE/B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,SAAS,EAAE,EAAE;YAC/C,MAAM,OAAO,GAAqB;gBAChC,SAAS;gBACT,SAAS,EAAE,IAAI,CAAC,aAAa,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,aAAa;gBACzE,KAAK,EAAE,EAAE,IAAI,CAAC,KAAK;gBACnB,MAAM,EAAE,OAAO;aAChB,CAAC;YAEF,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;YAC/B,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;IACL,CAAC;IAEM,IAAI;QACT,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC7B,OAAO;QACT,CAAC;QAED,IAAI,CAAC,kBAAkB,GAAG,KAAK,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAEM,OAAO;QACZ,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;CACF","sourcesContent":["/* v8 ignore file */\nimport type { IScheduler, LifecycleContext } from \"@realitycollective/service-framework\";\n\nexport interface AnimationLoopHostLike {\n  setAnimationLoop(callback: ((timestamp: number) => void) | null): void;\n}\n\nexport interface ThreeRenderLoopBridgeOptions {\n  readonly scheduler: IScheduler;\n  readonly host: AnimationLoopHostLike;\n}\n\nexport class ThreeRenderLoopBridge {\n  private animationLoopBound = false;\n  private frame = 0;\n  private lastTimestamp = 0;\n\n  public constructor(\n    private readonly options: ThreeRenderLoopBridgeOptions\n  ) {}\n\n  public start(): void {\n    if (this.animationLoopBound) {\n      return;\n    }\n\n    this.animationLoopBound = true;\n\n    this.options.host.setAnimationLoop((timestamp) => {\n      const context: LifecycleContext = {\n        timestamp,\n        deltaTime: this.lastTimestamp === 0 ? 16 : timestamp - this.lastTimestamp,\n        frame: ++this.frame,\n        source: \"three\"\n      };\n\n      this.lastTimestamp = timestamp;\n      this.options.scheduler.emit(\"renderTick\", context);\n    });\n  }\n\n  public stop(): void {\n    if (!this.animationLoopBound) {\n      return;\n    }\n\n    this.animationLoopBound = false;\n    this.options.host.setAnimationLoop(null);\n  }\n\n  public dispose(): void {\n    this.stop();\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realitycollective/service-framework-three",
-  "version": "1.0.0",
+  "version": "1.0.1-preview.0",
   "description": "three.js render-loop bindings for the Reality Collective TypeScript Service Framework.",
   "author": "Reality Collective",
   "license": "MIT",
@@ -15,7 +15,8 @@
   },
   "files": [
     "dist",
-    "Examples"
+    "Examples",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "service-framework",
@@ -34,7 +35,7 @@
     "url": "https://github.com/realitycollective/com.realitycollective.service-framework.ts/issues"
   },
   "dependencies": {
-    "@realitycollective/service-framework": "^1.0.0"
+    "@realitycollective/service-framework": "^1.0.1-preview.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAoB,MAAM,sCAAsC,CAAC;AAEzF,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CAAC,QAAQ,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;CACxE;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;CACtC;AAED,qBAAa,qBAAqB;IAM9B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,aAAa,CAAK;gBAGP,OAAO,EAAE,4BAA4B;IAGjD,KAAK,IAAI,IAAI;IAoBb,IAAI,IAAI,IAAI;IASZ,OAAO,IAAI,IAAI;CAGvB"}