@realitycollective/service-framework-react 1.0.0-preview.2 → 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,53 @@
+# @realitycollective/service-framework-react
+
+**React bindings** for the Reality Collective TypeScript Service Framework - a provider that owns the `ServiceManager` and hooks that resolve services by token.
+
+```sh
+npm install @realitycollective/service-framework @realitycollective/service-framework-react
+```
+
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `ServiceFrameworkProvider` | Owns a `ServiceManager` for the React tree below it |
+| `useServiceManager()` | The manager itself, for imperative work |
+| `useService(token, name?)` | Resolve a single service by token |
+| `useServices(token)` | Resolve every service registered under a token |
+
+## Usage
+
+```tsx
+import { ServiceFrameworkProvider, useService } from "@realitycollective/service-framework-react";
+import { weatherToken } from "./tokens";
+
+function Forecast() {
+  const weather = useService(weatherToken);
+  return <p>{weather.summary}</p>;
+}
+
+export function App() {
+  return (
+    <ServiceFrameworkProvider profile={myProfile}>
+      <Forecast />
+    </ServiceFrameworkProvider>
+  );
+}
+```
+
+## Peer dependency
+
+`react ^19.2.0`.
+
+## 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

@@ -13,4 +13,3 @@ export declare function ServiceFrameworkProvider({ children, manager, profile, a
 export declare function useServiceManager(): ServiceManager;
 export declare function useService<TService extends IService>(token: ServiceToken<TService>, name?: string): TService;
 export declare function useServices<TService extends IService>(token: ServiceToken<TService>): readonly TService[];
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":";AAAA,oBAAoB;AACpB,OAAc,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAOlE,OAAO,EAAE,cAAc,EAAgB,MAAM,sCAAsC,CAAC;AAWpF,MAAM,uBAAuB,GAAG,aAAa,CAAwB,IAAI,CAAC,CAAC;AAE3E,MAAM,UAAU,wBAAwB,CAAC,EACvC,QAAQ,EACR,OAAO,EACP,OAAO,EACP,SAAS,GAAG,IAAI,EAChB,SAAS,EACT,WAAW,EACmB;IAC9B,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,EAAE;QACnC,MAAM,QAAQ,GAAG,OAAO,IAAI,IAAI,cAAc,CAAC;YAC7C,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxC,CAAC,CAAC;QAEH,IAAI,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;YACvC,QAAQ,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;QAED,IAAI,SAAS,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;YACrC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IAE1D,OAAO,CACL,KAAC,uBAAuB,CAAC,QAAQ,IAAC,KAAK,EAAE,eAAe,YACrD,QAAQ,GACwB,CACpC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,MAAM,OAAO,GAAG,UAAU,CAAC,uBAAuB,CAAC,CAAC;IAEpD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;IAC5F,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,UAAU,CAA4B,KAA6B,EAAE,IAAa;IAChG,OAAO,iBAAiB,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,WAAW,CAA4B,KAA6B;IAClF,OAAO,iBAAiB,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":";AAAA,oBAAoB;AACpB,OAAc,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAOlE,OAAO,EAAE,cAAc,EAAgB,MAAM,sCAAsC,CAAC;AAWpF,MAAM,uBAAuB,GAAG,aAAa,CAAwB,IAAI,CAAC,CAAC;AAE3E,MAAM,UAAU,wBAAwB,CAAC,EACvC,QAAQ,EACR,OAAO,EACP,OAAO,EACP,SAAS,GAAG,IAAI,EAChB,SAAS,EACT,WAAW,EACmB;IAC9B,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,EAAE;QACnC,MAAM,QAAQ,GAAG,OAAO,IAAI,IAAI,cAAc,CAAC;YAC7C,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxC,CAAC,CAAC;QAEH,IAAI,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;YACvC,QAAQ,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;QAED,IAAI,SAAS,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;YACrC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IAE1D,OAAO,CACL,KAAC,uBAAuB,CAAC,QAAQ,IAAC,KAAK,EAAE,eAAe,YACrD,QAAQ,GACwB,CACpC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,MAAM,OAAO,GAAG,UAAU,CAAC,uBAAuB,CAAC,CAAC;IAEpD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;IAC5F,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,UAAU,CAA4B,KAA6B,EAAE,IAAa;IAChG,OAAO,iBAAiB,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,WAAW,CAA4B,KAA6B;IAClF,OAAO,iBAAiB,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;AAC/C,CAAC","sourcesContent":["/* v8 ignore file */\nimport React, { createContext, useContext, useMemo } from \"react\";\nimport type {\n  IEnvironmentDescriptor,\n  IScheduler,\n  IService,\n  ServiceProfile\n} from \"@realitycollective/service-framework\";\nimport { ServiceManager, ServiceToken } from \"@realitycollective/service-framework\";\n\nexport interface ServiceFrameworkProviderProps {\n  readonly children?: React.ReactNode;\n  readonly manager?: ServiceManager;\n  readonly profile?: ServiceProfile;\n  readonly autoStart?: boolean;\n  readonly scheduler?: IScheduler;\n  readonly environment?: IEnvironmentDescriptor;\n}\n\nconst ServiceFrameworkContext = createContext<ServiceManager | null>(null);\n\nexport function ServiceFrameworkProvider({\n  children,\n  manager,\n  profile,\n  autoStart = true,\n  scheduler,\n  environment\n}: ServiceFrameworkProviderProps): React.JSX.Element {\n  const resolvedManager = useMemo(() => {\n    const instance = manager ?? new ServiceManager({\n      ...(scheduler ? { scheduler } : {}),\n      ...(environment ? { environment } : {})\n    });\n\n    if (profile && !instance.isInitialized) {\n      instance.initializeProfile(profile);\n    }\n\n    if (autoStart && !instance.isStarted) {\n      instance.start();\n    }\n\n    return instance;\n  }, [autoStart, environment, manager, profile, scheduler]);\n\n  return (\n    <ServiceFrameworkContext.Provider value={resolvedManager}>\n      {children}\n    </ServiceFrameworkContext.Provider>\n  );\n}\n\nexport function useServiceManager(): ServiceManager {\n  const manager = useContext(ServiceFrameworkContext);\n\n  if (!manager) {\n    throw new Error(\"ServiceFrameworkProvider is required before calling useServiceManager.\");\n  }\n\n  return manager;\n}\n\nexport function useService<TService extends IService>(token: ServiceToken<TService>, name?: string): TService {\n  return useServiceManager().resolve(token, name);\n}\n\nexport function useServices<TService extends IService>(token: ServiceToken<TService>): readonly TService[] {\n  return useServiceManager().resolveAll(token);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realitycollective/service-framework-react",
-  "version": "1.0.0-preview.2",
+  "version": "1.0.1-preview.0",
   "description": "React 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",
@@ -33,7 +34,7 @@
     "url": "https://github.com/realitycollective/com.realitycollective.service-framework.ts/issues"
   },
   "dependencies": {
-    "@realitycollective/service-framework": "file:../service-framework"
+    "@realitycollective/service-framework": "^1.0.1-preview.0"
   },
   "peerDependencies": {
     "react": "^19.2.0"

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AACA,OAAO,KAA6C,MAAM,OAAO,CAAC;AAClE,OAAO,KAAK,EACV,sBAAsB,EACtB,UAAU,EACV,QAAQ,EACR,cAAc,EACf,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEpF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,sBAAsB,CAAC;CAC/C;AAID,wBAAgB,wBAAwB,CAAC,EACvC,QAAQ,EACR,OAAO,EACP,OAAO,EACP,SAAgB,EAChB,SAAS,EACT,WAAW,EACZ,EAAE,6BAA6B,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAuBnD;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAQlD;AAED,wBAAgB,UAAU,CAAC,QAAQ,SAAS,QAAQ,EAAE,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,CAE5G;AAED,wBAAgB,WAAW,CAAC,QAAQ,SAAS,QAAQ,EAAE,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,GAAG,SAAS,QAAQ,EAAE,CAEzG"}