@3dsource/angular-unreal-module 0.0.157 → 0.0.159-dev.0

package/README.md

@@ -1,422 +1,212 @@
-# @3dsource/angular-unreal-module
-
-A set of standalone Angular components, services, and providers for integrating Unreal Engine (WebRTC) scenes into Angular applications. It facilitates communication between Angular and Unreal Engine and enables interactive 3D experiences.
-
-## Overview
-
-This package provides:
-
-- Standalone Unreal scene component to embed UE stream
-- Communication bridge (commands, UI interactions, input data)
-- Callback listener for Unreal events and command responses
-- NgRx state and effects for 3D stream lifecycle
-- Config and utilities for telemetry, errors, and regions ping
-- Auto-reconnection support for WebRTC/DataChannel failures
-- File receiving from Unreal Engine
-- Analytics, FPS monitoring, and stream status telemetry
-- Playwright testing mode with mock services
-
-## Installation
-
-### Prerequisites
-
-- 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:
-
-```json
-{
-  "@3dsource/source-ui-native": ">=1.0.9",
-  "@3dsource/types-unreal": ">=0.0.7",
-  "@3dsource/utils": ">=1.0.21",
-  "@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"
-}
-```
-
-### Library Installation
-
-```shell
-npm i @3dsource/angular-unreal-module
-```
-
-## Usage
-
-The API is fully standalone (no NgModule). Use providers and components as shown below.
-
-### 1) Provide the state and config at the application root
-
-Add providers in your application bootstrap (e.g., `app.config.ts`):
-
-> **⚠️ Important:** `UNREAL_CONFIG` is **required** — multiple internal services inject it without `{ optional: true }`. Omitting it will cause a `NullInjectorError` at runtime. You can provide it with an empty object `{}` as a minimum.
-
-```ts
-import { ApplicationConfig } from '@angular/core';
-import { provideRouter } from '@angular/router';
-import { provideHttpClient } from '@angular/common/http';
-import { provideStore } from '@ngrx/store';
-import { provideUnrealState, UNREAL_CONFIG } from '@3dsource/angular-unreal-module';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideRouter([]),
-    provideHttpClient(),
-
-    // Root NgRx (if not already added in your app)
-    provideStore(),
-    provideUnrealState(),
-
-    // Required: Unreal initial configuration
-    {
-      provide: UNREAL_CONFIG,
-      useValue: {
-        customErrorsEndpoint: '', // Endpoint for custom error reporting
-        commandTelemetryReceiver: '', // Endpoint for command telemetry
-        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
-      },
-    },
-  ],
-};
-```
-
-#### Minimal configuration
-
-If you don't need custom endpoints, provide `UNREAL_CONFIG` with an empty object:
-
-```ts
-{ provide: UNREAL_CONFIG, useValue: {} },
-provideUnrealState(),
-```
-
-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.
-
-```ts
-import { Component } from '@angular/core';
-import { UnrealSceneComponent } from '@3dsource/angular-unreal-module';
-
-@Component({
-  selector: 'app-root',
-  standalone: true,
-  imports: [UnrealSceneComponent],
-  template: ` <app-unreal-scene [isStudio]="false" [useContainerAsSizeProvider]="true" [resolutionSize]="{ width: 1920, height: 1080 }" (changeMouseOverScene)="onHover($event)" /> `,
-})
-export class AppComponent {
-  onHover(isOver: boolean) {
-    // handle mouse over scene
-  }
-}
-```
-
-Component selector: `<app-unreal-scene>`
-
-Inputs:
-
-| Input                        | Type                                | Default                         |
-| ---------------------------- | ----------------------------------- | ------------------------------- |
-| `isStudio`                   | `boolean`                           | `false`                         |
-| `useContainerAsSizeProvider` | `boolean`                           | `true`                          |
-| `resolutionSize`             | `{ width: number; height: number }` | `{ width: 1920, height: 1080 }` |
-
-Outputs:
-
-| Output                 | Type                        |
-| ---------------------- | --------------------------- |
-| `changeMouseOverScene` | `OutputEmitterRef<boolean>` |
-
-### 4) Send commands / interactions to Unreal
-
-Inject `UnrealCommunicatorService` to send commands or UI interactions. Types for command packets are provided by `@3dsource/types-unreal`.
-
-There are three sending methods — choose based on your needs:
-
-| Method                | Description                                                                                                                                |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `sendCommandToUnreal` | Full pipeline: adds `correlationId`, records telemetry, dispatches NgRx `commandStarted` action. **Recommended for application commands.** |
-| `emitUIInteraction`   | Sends the packet as a raw `UIInteraction` message. No telemetry or store dispatch.                                                         |
-| `emitCommand`         | Sends the packet as a raw `Command` message (for console commands, resolution changes, etc.).                                              |
-
-```ts
-import { Component, inject } from '@angular/core';
-import { UnrealCommunicatorService } from '@3dsource/angular-unreal-module';
-import { MetaBoxCommand } from '@3dsource/types-unreal';
-import type { MetaBoxCommandPacket } from '@3dsource/types-unreal';
-
-@Component({ standalone: true, template: '' })
-export class MyComponent {
-  private unreal = inject(UnrealCommunicatorService);
-
-  sendSomeCommand() {
-    // Recommended: use sendCommandToUnreal for full telemetry + store tracking
-    this.unreal.sendCommandToUnreal({
-      command: MetaBoxCommand.FChangeResolutionCommand,
-      payload: { resolution: { x: 1920, y: 1080 } },
-    });
-  }
-
-  sendRawUIInteraction() {
-    // Low-level: sends UIInteraction message without telemetry tracking
-    const packet = {
-      command: 'CustomCommand',
-      payload: { key: 'value' },
-    } as MetaBoxCommandPacket;
-    this.unreal.emitUIInteraction(packet);
-  }
-}
-```
-
-### 5) Store integration (actions & selectors)
-
-`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 { disconnectStream, selectShowLoader, selectTotalProgress, setConfig, setOrchestrationContext, startStream, unrealFeature } from '@3dsource/angular-unreal-module';
-
-// Dispatch actions
-const store = inject(Store);
-store.dispatch(startStream({ config: { autoStart: true, warnTimeout: 120 } }));
-
-// Select state
-const progress = store.selectSignal(selectTotalProgress);
-const isVideoPlaying = store.selectSignal(unrealFeature.selectIsVideoPlaying);
-const dataChannelConnected = store.selectSignal(unrealFeature.selectDataChannelConnected);
-```
-
-**Key selectors:**
-
-- `selectTotalProgress` — Scene load progress (0–1 float)
-- `selectShowLoader` — Whether loader screen should be visible
-- `selectShowReconnectPopup` — Whether reconnect popup should be shown
-- `selectIsVideoPlayingAndDataChannelConnected` — Combined readiness check
-- `selectStreamConfig` — Current stream configuration
-- `unrealFeature.selectCirrusConnected` — Signalling server connection status
-- `unrealFeature.selectDataChannelConnected` — Data channel status
-- `unrealFeature.selectViewportReady` — Viewport readiness
-
-**Key actions:**
-
-- `startStream` — Start streaming with config
-- `setConfig` — Update stream configuration
-- `setOrchestrationContext` — Set orchestration URLs and environment
-- `disconnectStream` — Disconnect with reason
-- `destroyUnrealScene` — Full teardown
-- `reconnectPeer` — Trigger peer reconnection
-
-### 6) Listen for Unreal callbacks
-
-Inject `UnrealCallbackService` to listen for callback events from Unreal Engine and to observe command responses.
-
-There are two methods:
-
-| Method                   | Description                                                                                                                                                            |
-| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fromUnrealCallback`     | Listens for callbacks matching a command or event key. Supports MetaBox commands and custom Unreal callback events. Returns `Observable<UnrealCallbackDescriptor[K]>`. |
-| `observeCommandResponse` | Sends a command and waits for its matching response by `correlationId`. Returns `Observable<MetaBoxCommandList[K]>`. Includes timeout and error handling.              |
-
-**Custom Unreal callback events** (defined in `UnrealCallbackEventMap`):
-
-| Event                      | Payload Type                                        |
-| -------------------------- | --------------------------------------------------- |
-| `onSceneState`             | `FSceneState`                                       |
-| `onFocusObject`            | `FProductPayload`                                   |
-| `cameraChanged`            | `FCameraChangedPayload`                             |
-| `onObjectTransformChanged` | `{ objectName: string; transform: FTransformJson }` |
-| `onChangeSequence`         | `unknown`                                           |
-| `onFinishedSequence`       | `unknown`                                           |
-
-```ts
-import { Component, inject } from '@angular/core';
-import { UnrealCallbackService } from '@3dsource/angular-unreal-module';
-import { UnrealCommunicatorService } from '@3dsource/angular-unreal-module';
-import { MetaBoxCommand } from '@3dsource/types-unreal';
-
-@Component({ standalone: true, template: '' })
-export class MyComponent {
-  private callbackService = inject(UnrealCallbackService);
-  private communicator = inject(UnrealCommunicatorService);
-
-  listenForCallbacks() {
-    // Listen for a MetaBox command callback
-    this.callbackService.fromUnrealCallback(MetaBoxCommand.FLoadProductCommand).subscribe((data) => console.log('Product loaded:', data));
-
-    // Listen for a custom Unreal event
-    this.callbackService.fromUnrealCallback('cameraChanged').subscribe((data) => console.log('Camera changed:', data));
-  }
-
-  sendAndObserve() {
-    // Send a command and observe its response (with correlationId matching)
-    this.callbackService
-      .observeCommandResponse(
-        { command: MetaBoxCommand.FLoopBackCommand },
-        (data) => this.communicator.sendCommandToUnreal(data),
-        60000, // timeout in ms (default: 60000)
-        true, // emit on timeout (default: true)
-      )
-      .subscribe((response) => console.log('Response:', response));
-  }
-}
-```
-
-## Exported API
-
-### 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            |
-| `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
-
-| Service                        | Description                                                     |
-| ------------------------------ | --------------------------------------------------------------- |
-| `UnrealCommunicatorService`    | Send commands and UI interactions to Unreal                     |
-| `UnrealCallbackService`        | Listen for Unreal callback events and observe command responses |
-| `AggregatorService`            | Aggregates data channel messages from Unreal                    |
-| `SignallingService`            | Manages WebSocket signalling connection                         |
-| `VideoService`                 | Manages video element and stats                                 |
-| `WebRtcPlayerService`          | Manages WebRTC peer connection                                  |
-| `FreezeFrameService`           | Handles freeze frame images                                     |
-| `AFKService`                   | AFK (away from keyboard) detection and timeout                  |
-| `DevModeService`               | Toggle dev mode for debugging                                   |
-| `FileReceiverService`          | Receives files from Unreal via data channel                     |
-| `FileHandlerService`           | Processes received files                                        |
-| `RegionsPingService`           | Pings regions to determine latency                              |
-| `CommandTelemetryService`      | Records command telemetry                                       |
-| `StreamStatusTelemetryService` | Reports stream status telemetry                                 |
-| `AnalyticsService`             | Analytics event tracking                                        |
-| `FpsMonitorService`            | FPS monitoring                                                  |
-
-### Pipes
-
-| Pipe       | Description                                                  |
-| ---------- | ------------------------------------------------------------ |
-| `SafePipe` | Sanitizes a value for the requested Angular security context |
-
-### Interfaces
-
-| Interface                  | Description                                                                  |
-| -------------------------- | ---------------------------------------------------------------------------- |
-| `UnrealInitialConfig`      | Shape for `UNREAL_CONFIG` injection token                                    |
-| `StreamConfig`             | Stream configuration (autoStart, warnTimeout)                                |
-| `StreamResolutionProps`    | Stream resolution width/height                                               |
-| `UnrealCallbackEventMap`   | Custom Unreal callback events pushed from Unreal via data channel            |
-| `UnrealCallbackDescriptor` | Combined map of MetaBoxCommandList and UnrealCallbackEventMap callback types |
-
-## Features
-
-- Standalone Unreal Scene Component
-- Command and UI Interaction API via `UnrealCommunicatorService`
-- Callback listener and command response observer via `UnrealCallbackService`
-- Event-driven status UI (freeze frame, video stats, play overlay, AFK, low bandwidth)
-- NgRx-powered state management and effects
-- **Required** initial configuration via `UNREAL_CONFIG` injection token
-- Auto-reconnection on WebRTC/DataChannel failures (configurable)
-- File receiving from Unreal Engine via data channel
-- Analytics and FPS monitoring
-- Playwright testing mode with mock service substitution
-
-## Examples
-
-Check the demo application for complete usage examples:
-
-```shell
-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 unreal:build
-pnpm unreal:build:watch
-pnpm unreal:lint
-pnpm unreal:test
-pnpm unreal:test:watch
-pnpm unreal:test:signalling
-pnpm unreal:test:signalling:leaks
-```
-
-`unreal:build` builds `source-ui-native`, `types-unreal` and `utils` before this
-package. `unreal:build:watch` performs that initial build automatically and then
-watches `angular-unreal-module`.
-
-To version and publish:
-
-```shell
-pnpm unreal:release:patch
-pnpm unreal:release:dev
-```
-
-The release command publishes to npm. After verifying the npm release, purge
-the matching jsDelivr tag explicitly:
-
-```shell
-pnpm unreal:purge-cdn -- latest
-```
-
-## Engine requirements
-
-- Node.js: >=24.16.0
-- pnpm: 11.17.0 (activated from the root `packageManager` field via Corepack)
+# @3dsource/angular-unreal-module
+
+Standalone Angular integration for Unreal Engine Pixel Streaming. The package
+provides the scene component, WebRTC and signalling lifecycle, NgRx state,
+command/callback APIs, reconnection, file transfer and telemetry.
+
+## Requirements
+
+- Angular, Angular CDK and Angular Forms `>=19.0.0 <23.0.0`
+- NgRx Store and Effects `>=19.0.0 <23.0.0`
+- RxJS `>=7.8.0 <8.0.0`
+- `@3dsource/source-ui-native >=1.0.9`
+- `@3dsource/types-unreal >=0.0.7`
+- `@3dsource/utils >=1.0.21`
+- `provideHttpClient()` in the host application
+
+## Installation
+
+```shell
+pnpm add @3dsource/angular-unreal-module @3dsource/source-ui-native @3dsource/types-unreal @3dsource/utils
+```
+
+The package is standalone and does not expose an NgModule.
+
+## Setup
+
+### 1. Register state and configuration once
+
+Add the Unreal feature state, HTTP client and configuration at the application
+root. `UNREAL_CONFIG` is required, although all its fields are optional.
+
+<!-- prettier-ignore -->
+```typescript
+import { provideHttpClient } from '@angular/common/http';
+import type { ApplicationConfig } from '@angular/core';
+import { provideStore } from '@ngrx/store';
+import {
+  provideUnrealState,
+  UNREAL_CONFIG,
+  type UnrealInitialConfig,
+} from '@3dsource/angular-unreal-module';
+
+const unrealConfig = {
+  regionsPingUrl: 'https://datacenter.3dsource.com/regions/',
+  dataChannelConnectionTimeout: 8000,
+  fpsMonitor: false,
+  autoHighResolution: false,
+} satisfies UnrealInitialConfig;
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(),
+    provideStore(),
+    provideUnrealState(),
+    { provide: UNREAL_CONFIG, useValue: unrealConfig },
+  ],
+};
+```
+
+Omit `provideStore()` when the root NgRx store is already configured.
+
+Available configuration fields:
+
+| Field                          | Purpose                                        |
+| ------------------------------ | ---------------------------------------------- |
+| `regionsPingUrl`               | Region latency endpoint                        |
+| `dataChannelConnectionTimeout` | DataChannel connection timeout in ms           |
+| `customErrorsEndpoint`         | Custom error reporting endpoint                |
+| `commandTelemetryReceiver`     | Command telemetry endpoint                     |
+| `streamTelemetryV2Url`         | Stream lifecycle telemetry endpoint            |
+| `screenLockerContainerId`      | Container used by the screen-locker overlay    |
+| `fpsMonitor`                   | Enables FPS monitoring                         |
+| `autoHighResolution`           | Raises resolution after the scene becomes idle |
+| `playwright`                   | Enables the test-specific service behaviour    |
+
+Use `{ provide: UNREAL_CONFIG, useValue: {} }` for the minimal configuration.
+
+### 2. Boot the engine on a lazy route
+
+Lazy-load the route file from the application router:
+
+<!-- prettier-ignore -->
+```typescript
+import type { Routes } from '@angular/router';
+
+export const APP_ROUTES: Routes = [
+  {
+    path: 'stream',
+    loadChildren: () =>
+      import('./stream/stream.routes').then((module) => module.STREAM_ROUTES),
+  },
+];
+```
+
+Register `provideUnrealModule()` inside that lazy route file:
+
+<!-- prettier-ignore -->
+```typescript
+import type { Routes } from '@angular/router';
+import { provideUnrealModule } from '@3dsource/angular-unreal-module';
+import { StreamComponent } from './stream.component';
+
+export const STREAM_ROUTES: Routes = [
+  {
+    path: '',
+    component: StreamComponent,
+    providers: [provideUnrealModule()],
+  },
+];
+```
+
+Keep `provideUnrealState()` and `UNREAL_CONFIG` at the application root.
+The `loadChildren()` boundary keeps the streaming engine out of the initial
+bundle. Route-scoping `provideUnrealModule()` tears down its effects when the
+route is left.
+
+### 3. Render the scene
+
+```typescript
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { UnrealSceneComponent } from '@3dsource/angular-unreal-module';
+
+@Component({
+  selector: 'app-stream',
+  imports: [UnrealSceneComponent],
+  template: `<app-unreal-scene />`,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class StreamComponent {}
+```
+
+`UnrealSceneComponent` also accepts `isStudio`,
+`useContainerAsSizeProvider` and `resolutionSize` inputs, and emits
+`changeMouseOverScene`.
+
+## Main API
+
+- `provideUnrealState()` — registers the `unrealFeature` NgRx state.
+- `provideUnrealModule()` — registers effects and boots streaming services.
+- `UnrealSceneComponent` — renders and manages the Pixel Streaming scene.
+- `UnrealCommunicatorService` — sends commands and UI interactions.
+- `UnrealCallbackService` — observes Unreal callbacks and command responses.
+- `unrealFeature`, exported selectors and actions — expose connection and scene
+  lifecycle state.
+- `FileReceiverService` and `FileHandlerService` — receive files over the
+  DataChannel.
+
+Command packet types are provided by `@3dsource/types-unreal`.
+
+Run `pnpm demo:start` from the repository root to see the scene component in
+the demo application.
+
+## Optional prefetch scripts
+
+The package publishes two dependency-free scripts for use in the document
+`<head>` before Angular starts:
+
+- `region-ping-prefetch.js` measures regions early and caches the closest one.
+- `stream-prefetch.js` opens and parks an eligible WebRTC connection so Angular
+  can adopt it after bootstrap.
+
+<!-- prettier-ignore -->
+```html
+<script
+  src="https://cdn.jsdelivr.net/npm/@3dsource/angular-unreal-module/js/region-ping-prefetch.js"
+  async
+></script>
+<script
+  src="https://cdn.jsdelivr.net/npm/@3dsource/angular-unreal-module/js/stream-prefetch.js"
+  async
+></script>
+```
+
+`stream-prefetch.js` runs by default only on
+`metabox-configurator/{modular|basic}/...` routes. It reads the same-origin
+`assets/config.json`; override that path with `data-config-url` when needed.
+Pin an exact package version in production when deterministic CDN assets are
+required.
+
+## Repository development
+
+Run commands from the repository root:
+
+```shell
+pnpm unreal:build
+pnpm unreal:build:watch
+pnpm unreal:lint
+pnpm unreal:test
+pnpm unreal:test:watch
+pnpm unreal:test:signalling
+pnpm unreal:test:signalling:leaks
+```
+
+`unreal:build` builds the local `source-ui-native`, `types-unreal` and `utils`
+dependencies before this package.
+
+Release commands publish only this package:
+
+```shell
+pnpm unreal:release:patch
+pnpm unreal:release:dev
+```
+
+After a successful publish, the release automatically purges the matching
+jsDelivr tag. Retry a failed purge without rerunning the release:
+
+```shell
+pnpm unreal:purge-cdn -- latest
+pnpm unreal:purge-cdn -- dev
+```
+
+Repository tooling requires Node.js 24.16.0 or newer and pnpm 11.17.0.