@3dsource/angular-unreal-module 0.0.152 → 0.0.155

package/README.md

@@ -20,26 +20,29 @@ This package provides:
 
 ### Prerequisites
 
-- Angular 18+
-- NgRx store and effects (v18+)
-- Angular CDK (v18+) — used for dialog overlays
+- Angular `>=19.0.0 <23.0.0`
+- NgRx store and effects `>=19.0.0 <23.0.0`
+- Angular CDK `>=19.0.0 <23.0.0` — used for dialog overlays
+- RxJS `>=7.8.0 <8.0.0`
 - `provideHttpClient()` — required by internal services (telemetry, signalling, regions ping, error reporting)
 
 ### Peer Dependencies
 
-This library requires the following peer dependencies (match or exceed versions):
+This library requires the following peer dependencies:
 
 ```json
 {
   "@3dsource/source-ui-native": ">=1.0.9",
   "@3dsource/types-unreal": ">=0.0.7",
   "@3dsource/utils": ">=1.0.21",
-  "@angular/cdk": ">=19.0.0",
-  "@angular/common": ">=19.0.0",
-  "@angular/core": ">=19.0.0",
-  "@angular/forms": ">=19.0.0",
-  "@ngrx/effects": ">=19.0.0",
-  "@ngrx/store": ">=19.0.0"
+  "@angular/cdk": ">=19.0.0 <23.0.0",
+  "@angular/common": ">=19.0.0 <23.0.0",
+  "@angular/core": ">=19.0.0 <23.0.0",
+  "@angular/forms": ">=19.0.0 <23.0.0",
+  "@angular/platform-browser": ">=19.0.0 <23.0.0",
+  "@ngrx/effects": ">=19.0.0 <23.0.0",
+  "@ngrx/store": ">=19.0.0 <23.0.0",
+  "rxjs": ">=7.8.0 <8.0.0"
 }
 ```
 
@@ -53,7 +56,7 @@ npm i @3dsource/angular-unreal-module
 
 The API is fully standalone (no NgModule). Use providers and components as shown below.
 
-### 1) Provide the module services and store slice
+### 1) Provide the state and config at the application root
 
 Add providers in your application bootstrap (e.g., `app.config.ts`):
 
@@ -64,8 +67,7 @@ import { ApplicationConfig } from '@angular/core';
 import { provideRouter } from '@angular/router';
 import { provideHttpClient } from '@angular/common/http';
 import { provideStore } from '@ngrx/store';
-import { provideEffects } from '@ngrx/effects';
-import { provideUnrealModule, UNREAL_CONFIG } from '@3dsource/angular-unreal-module';
+import { provideUnrealState, UNREAL_CONFIG } from '@3dsource/angular-unreal-module';
 
 export const appConfig: ApplicationConfig = {
   providers: [
@@ -74,7 +76,7 @@ export const appConfig: ApplicationConfig = {
 
     // Root NgRx (if not already added in your app)
     provideStore(),
-    provideEffects(),
+    provideUnrealState(),
 
     // Required: Unreal initial configuration
     {
@@ -85,14 +87,12 @@ export const appConfig: ApplicationConfig = {
         regionsPingUrl: '', // URL prefix for regions latency ping
         screenLockerContainerId: '', // DOM container id for screen locker overlay
         dataChannelConnectionTimeout: 8000, // Timeout in ms for data channel connection (default: 8000)
+        streamTelemetryV2Url: '', // Endpoint for stream-status telemetry
+        fpsMonitor: false, // Enable FPS monitoring
+        autoHighResolution: false, // Raise resolution after the scene becomes idle
         playwright: false, // Mirrors the provider flag for services/effects
       },
     },
-
-    // Core Unreal providers (adds feature state + effects internally).
-    // playwright/testing mode is set via UNREAL_CONFIG above.
-    // Opt into extra features as needed — see "Bundle size & features" below.
-    provideUnrealModule(),
   ],
 };
 ```
@@ -103,10 +103,38 @@ If you don't need custom endpoints, provide `UNREAL_CONFIG` with an empty object
 
 ```ts
 { provide: UNREAL_CONFIG, useValue: {} },
-provideUnrealModule(),
+provideUnrealState(),
 ```
 
-### 2) Use the Unreal scene component
+Every `UnrealInitialConfig` field is optional, but the `UNREAL_CONFIG` provider
+itself is required. Available fields are `playwright`,
+`customErrorsEndpoint`, `commandTelemetryReceiver`, `regionsPingUrl`,
+`screenLockerContainerId`, `dataChannelConnectionTimeout`,
+`streamTelemetryV2Url`, `fpsMonitor` and `autoHighResolution`.
+
+### 2) Boot the engine in each lazy 3D route
+
+`provideUnrealModule()` registers the effects and initializes the streaming
+services. Put it on every lazy route that renders a 3D scene:
+
+```ts
+import { Routes } from '@angular/router';
+import { provideUnrealModule } from '@3dsource/angular-unreal-module';
+
+export const STREAM_ROUTES: Routes = [
+  {
+    path: ':id',
+    loadComponent: () => import('./stream.component').then((module) => module.StreamComponent),
+    providers: [provideUnrealModule()],
+  },
+];
+```
+
+Keep `provideUnrealState()` and `UNREAL_CONFIG` at the root. Keeping
+`provideUnrealModule()` in lazy routes also keeps the streaming engine out of
+the initial application bundle.
+
+### 3) Use the Unreal scene component
 
 Import the component into a standalone component and use it in the template.
 
@@ -118,7 +146,7 @@ import { UnrealSceneComponent } from '@3dsource/angular-unreal-module';
   selector: 'app-root',
   standalone: true,
   imports: [UnrealSceneComponent],
-  template: ` <app-unreal-scene [isStudio]="false" [useContainerAsSizeProvider]="true" [studioResolutionSize]="{ width: 1920, height: 1080 }" (changeMouseOverScene)="onHover($event)"> </app-unreal-scene> `,
+  template: ` <app-unreal-scene [isStudio]="false" [useContainerAsSizeProvider]="true" [resolutionSize]="{ width: 1920, height: 1080 }" (changeMouseOverScene)="onHover($event)" /> `,
 })
 export class AppComponent {
   onHover(isOver: boolean) {
@@ -135,7 +163,7 @@ Inputs:
 | ---------------------------- | ----------------------------------- | ------------------------------- |
 | `isStudio`                   | `boolean`                           | `false`                         |
 | `useContainerAsSizeProvider` | `boolean`                           | `true`                          |
-| `studioResolutionSize`       | `{ width: number; height: number }` | `{ width: 1920, height: 1080 }` |
+| `resolutionSize`             | `{ width: number; height: number }` | `{ width: 1920, height: 1080 }` |
 
 Outputs:
 
@@ -143,7 +171,7 @@ Outputs:
 | ---------------------- | --------------------------- |
 | `changeMouseOverScene` | `OutputEmitterRef<boolean>` |
 
-### 3) Send commands / interactions to Unreal
+### 4) Send commands / interactions to Unreal
 
 Inject `UnrealCommunicatorService` to send commands or UI interactions. Types for command packets are provided by `@3dsource/types-unreal`.
 
@@ -184,14 +212,15 @@ export class MyComponent {
 }
 ```
 
-### 4) Store integration (actions & selectors)
+### 5) Store integration (actions & selectors)
 
-The module registers an NgRx feature state `commandsFeature`. You can dispatch actions and select state in your components:
+`provideUnrealState()` registers the NgRx feature state `unrealFeature`. You
+can dispatch actions and select state in your components:
 
 ```ts
 import { inject } from '@angular/core';
 import { Store } from '@ngrx/store';
-import { startStream, setConfig, setOrchestrationContext, disconnectStream, selectTotalProgress, selectShowLoader, commandsFeature } from '@3dsource/angular-unreal-module';
+import { disconnectStream, selectShowLoader, selectTotalProgress, setConfig, setOrchestrationContext, startStream, unrealFeature } from '@3dsource/angular-unreal-module';
 
 // Dispatch actions
 const store = inject(Store);
@@ -199,8 +228,8 @@ store.dispatch(startStream({ config: { autoStart: true, warnTimeout: 120 } }));
 
 // Select state
 const progress = store.selectSignal(selectTotalProgress);
-const isVideoPlaying = store.selectSignal(commandsFeature.selectIsVideoPlaying);
-const dataChannelConnected = store.selectSignal(commandsFeature.selectDataChannelConnected);
+const isVideoPlaying = store.selectSignal(unrealFeature.selectIsVideoPlaying);
+const dataChannelConnected = store.selectSignal(unrealFeature.selectDataChannelConnected);
 ```
 
 **Key selectors:**
@@ -210,9 +239,9 @@ const dataChannelConnected = store.selectSignal(commandsFeature.selectDataChanne
 - `selectShowReconnectPopup` — Whether reconnect popup should be shown
 - `selectIsVideoPlayingAndDataChannelConnected` — Combined readiness check
 - `selectStreamConfig` — Current stream configuration
-- `commandsFeature.selectCirrusConnected` — Signalling server connection status
-- `commandsFeature.selectDataChannelConnected` — Data channel status
-- `commandsFeature.selectViewportReady` — Viewport readiness
+- `unrealFeature.selectCirrusConnected` — Signalling server connection status
+- `unrealFeature.selectDataChannelConnected` — Data channel status
+- `unrealFeature.selectViewportReady` — Viewport readiness
 
 **Key actions:**
 
@@ -223,7 +252,7 @@ const dataChannelConnected = store.selectSignal(commandsFeature.selectDataChanne
 - `destroyUnrealScene` — Full teardown
 - `reconnectPeer` — Trigger peer reconnection
 
-### 5) Listen for Unreal callbacks
+### 6) Listen for Unreal callbacks
 
 Inject `UnrealCallbackService` to listen for callback events from Unreal Engine and to observe command responses.
 
@@ -282,18 +311,18 @@ export class MyComponent {
 
 ### Components
 
-| Component                        | Selector           | Description                            |
-| -------------------------------- | ------------------ | -------------------------------------- |
-| `UnrealSceneComponent`           | `app-unreal-scene` | Main scene container with video stream |
-| `AfkTimeoutModalComponent`       | —                  | AFK timeout warning modal              |
-| `FreezeFrameComponent`           | —                  | Freeze frame overlay                   |
-| `LowBandwidthModalComponent`     | —                  | Low bandwidth warning modal            |
-| `LowBandwidthIndicatorComponent` | —                  | Low bandwidth indicator                |
-| `ImageLoadingSrcComponent`       | —                  | Loading image overlay                  |
-| `IntroSrcComponent`              | —                  | Intro image/video overlay              |
-| `VideoStatsComponent`            | —                  | Video statistics display               |
-| `StatGraphComponent`             | —                  | Statistics graph                       |
-| `WebrtcErrorModalComponent`      | —                  | WebRTC error modal                     |
+| Component                       | Selector           | Description                            |
+| ------------------------------- | ------------------ | -------------------------------------- |
+| `UnrealSceneComponent`          | `app-unreal-scene` | Main scene container with video stream |
+| `AfkTimeoutModalComponent`      | —                  | AFK timeout warning modal              |
+| `FreezeFrameComponent`          | —                  | Freeze frame overlay                   |
+| `LowBandwidthModalComponent`    | —                  | Low bandwidth warning modal            |
+| `LowBandwidthDetectorComponent` | —                  | Low bandwidth detector                 |
+| `ImageLoadingSrcComponent`      | —                  | Loading image overlay                  |
+| `IntroSrcComponent`             | —                  | Intro image/video overlay              |
+| `VideoStatsComponent`           | —                  | Video statistics display               |
+| `StatGraphComponent`            | —                  | Statistics graph                       |
+| `WebrtcErrorModalComponent`     | —                  | WebRTC error modal                     |
 
 ### Services
 
@@ -318,9 +347,9 @@ export class MyComponent {
 
 ### Pipes
 
-| Pipe           | Description                     |
-| -------------- | ------------------------------- |
-| `SafeHtmlPipe` | Bypasses Angular HTML sanitizer |
+| Pipe       | Description                                                  |
+| ---------- | ------------------------------------------------------------ |
+| `SafePipe` | Sanitizes a value for the requested Angular security context |
 
 ### Interfaces
 
@@ -350,12 +379,34 @@ export class MyComponent {
 Check the demo application for complete usage examples:
 
 ```shell
-npm run demo:start
+pnpm demo:start
 ```
 
 See also: `projects/demo/src/app/demo-layout/info-pages/unreal-scene-demo/constants/unreal.routes.ts` for a real-world provider configuration example.
 
+## Repository development
+
+Run package commands from the repository root:
+
+```shell
+pnpm --filter @3dsource/angular-unreal-module build
+pnpm --filter @3dsource/angular-unreal-module build:watch
+pnpm --filter @3dsource/angular-unreal-module test:signalling
+```
+
+To version and publish:
+
+```shell
+pnpm release:package -- angular-unreal-module patch latest
+```
+
+The release command publishes to npm. After verifying the npm release, purge
+the matching jsDelivr tag explicitly:
+
+```shell
+pnpm --filter @3dsource/angular-unreal-module purge-cdn -- latest
+```
+
 ## Engine requirements
 
 - Node.js: >=20
-- npm: >9