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

package/README.md

@@ -1,412 +1,422 @@
-# @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 --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
+# @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)