@3dsource/angular-unreal-module 0.0.154 → 0.0.156-dev.0

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

package/fesm2022/3dsource-angular-unreal-module.mjs

@@ -6,7 +6,6 @@ import { createAction, props, createReducer, on, createFeature, Store, createSel
 import { whereNot, Falsy, Logger, calculateMedian, clampf, lerp, getCanvasCached, getSnapshot, fitIntoRectangle, generateUuid, Truthy, tapLog, Semaphore, COLOR_CODES, where, KeyboardNumericCode, InvertedKeyMap, HEXtoRGB, RGBtoHSV, inverseLerp, HSVtoRGB, RGBtoHEX, fpIsASameAsB } from '@3dsource/utils';
 import { filter, map as map$1, distinctUntilChanged, takeWhile, takeUntil, catchError, tap, timeout, finalize, first, switchMap as switchMap$1, withLatestFrom, exhaustMap, debounceTime as debounceTime$1, take as take$1, startWith as startWith$1 } from 'rxjs/operators';
 import { Actions, ofType, createEffect, provideEffects } from '@ngrx/effects';
-import { concatLatestFrom } from '@ngrx/operators';
 import { DialogRef, DIALOG_DATA, Dialog } from '@angular/cdk/dialog';
 import { HttpClient } from '@angular/common/http';
 import { ScrollStrategyOptions } from '@angular/cdk/overlay';
@@ -3329,7 +3328,8 @@ class WebRtcPlayerService extends SubService {
      * (`pc.onicecandidate`, `dc.onmessage`, …) and buffered inbound DC messages;
      * here we detach those, wire our own (addEventListener-based) handlers, replay
      * the buffer in order, then drive `onDataChannelConnected` manually because the
-     * DataChannel is already open (its `open` event won't fire again).
+     * DataChannel is already open. A native `open` event may still be queued, so the
+     * adopted channel deliberately does not subscribe to it.
      */
     adopt(pc, dc, stream, config, dcBuffer) {
         // No prior pc/dc should exist on a fresh boot; closePC is idempotent.
@@ -3354,7 +3354,9 @@ class WebRtcPlayerService extends SubService {
         dc.onmessage = null;
         dc.onopen = null;
         dc.onclose = null;
-        this.dcClient = this.setupDataChannelCallbacks(dc);
+        // Adoption announces the already-open channel manually below. Do not
+        // subscribe to a native `open` event that may still be queued.
+        this.dcClient = this.setupDataChannelCallbacks(dc, false);
         for (const buffered of dcBuffer) {
             this.onDataChannelMessage$.next(buffered);
         }
@@ -3498,7 +3500,7 @@ class WebRtcPlayerService extends SubService {
             }
         }
     }
-    setupDataChannelCallbacks(datachannel) {
+    setupDataChannelCallbacks(datachannel, subscribeToOpen = true) {
         try {
             Logger.log(`[DATACHANNEL] Setting up datachannel "${datachannel.label}" callbacks...`);
             this.commandTelemetryService.trackStartCommand('EXT-DataChannel Connection');
@@ -3521,14 +3523,16 @@ class WebRtcPlayerService extends SubService {
                 const message = `[DATACHANNEL] Data channel "${datachannel.label}" error. id:${datachannel.id}`;
                 Logger.error(message, e);
             });
-            fromEvent(datachannel, 'open')
-                .pipe(tap$1(() => {
-                Logger.info(`[DATACHANNEL] Data channel "${datachannel.label}" connected. id:${datachannel.id}`);
-            }), takeUntil(merge(this.disconnect$, this.destroy$)))
-                .subscribe(() => {
-                this.commandTelemetryService.trackStopCommand('EXT-DataChannel Connection');
-                this.onDataChannelConnected();
-            });
+            if (subscribeToOpen) {
+                fromEvent(datachannel, 'open')
+                    .pipe(tap$1(() => {
+                    Logger.info(`[DATACHANNEL] Data channel "${datachannel.label}" connected. id:${datachannel.id}`);
+                }), takeUntil(merge(this.disconnect$, this.destroy$)))
+                    .subscribe(() => {
+                    this.commandTelemetryService.trackStopCommand('EXT-DataChannel Connection');
+                    this.onDataChannelConnected();
+                });
+            }
             fromEvent(datachannel, 'message')
                 .pipe(
             /* tap((e: MessageEvent) => {
@@ -4058,10 +4062,10 @@ class UnrealEffects {
          * a visible flicker (video flashing to black).
          */
         this.forceViewportNotReady$ = createEffect(() => {
-            return this.actions$.pipe(ofType(destroyRemoteConnections), concatLatestFrom(() => this.store.select(unrealFeature.selectViewportReady)), filter(([, viewportReady]) => viewportReady), map(() => setViewportNotReady()));
+            return this.actions$.pipe(ofType(destroyRemoteConnections), withLatestFrom(this.store.select(unrealFeature.selectViewportReady)), filter(([, viewportReady]) => viewportReady), map(() => setViewportNotReady()));
         });
         this.resetCirrusOnDestroy$ = createEffect(() => {
-            return this.actions$.pipe(ofType(destroyRemoteConnections), concatLatestFrom(() => this.store.select(unrealFeature.selectCirrusConnected)), filter(([, cirrusConnected]) => cirrusConnected), map(() => setCirrusDisconnected()));
+            return this.actions$.pipe(ofType(destroyRemoteConnections), withLatestFrom(this.store.select(unrealFeature.selectCirrusConnected)), filter(([, cirrusConnected]) => cirrusConnected), map(() => setCirrusDisconnected()));
         });
         this.destroyRemoteConnections$ = createEffect(() => {
             return this.actions$.pipe(ofType(destroyRemoteConnections), tap(({ reason }) => {
@@ -4069,7 +4073,7 @@ class UnrealEffects {
             }), filter(({ reason }) => reason === DisconnectReason.DropConnection), map(() => dropConnection()));
         });
         this.destroyConnectionAndRestart$ = createEffect(() => {
-            return this.actions$.pipe(ofType(setCirrusDisconnected), concatLatestFrom(() => this.store.select(unrealFeature.selectDisconnectReason)), filter(([, reason]) => reason === DisconnectReason.DataChannelTimeout), map(() => initSignalling()));
+            return this.actions$.pipe(ofType(setCirrusDisconnected), withLatestFrom(this.store.select(unrealFeature.selectDisconnectReason)), filter(([, reason]) => reason === DisconnectReason.DataChannelTimeout), map(() => initSignalling()));
         });
         this.showUnrealError$ = createEffect(() => {
             return this.actions$.pipe(ofType(showUnrealErrorMessage), map(({ code }) => getRtcErrorMessage(code)), distinctUntilChanged(), filter(Truthy), switchMap((content) => this.dialog.open(UnrealErrorModalComponent, {
@@ -4078,7 +4082,7 @@ class UnrealEffects {
             }).closed), map(() => showUnrealErrorMessage({ code: null })));
         });
         this.unrealReceiverReady$ = createEffect(() => {
-            return this.actions$.pipe(ofType(dataChannelConnected), concatLatestFrom(() => this.store.select(unrealFeature.selectIsReconnecting)), filter(([, isReconnecting]) => !isReconnecting), map(() => dataChannelReady()));
+            return this.actions$.pipe(ofType(dataChannelConnected), withLatestFrom(this.store.select(unrealFeature.selectIsReconnecting)), filter(([, isReconnecting]) => !isReconnecting), map(() => dataChannelReady()));
         });
         this.initAppByDataChannelReady$ = createEffect(() => {
             return this.actions$.pipe(ofType(dataChannelReady), tap(() => {