@3dsource/angular-unreal-module 0.0.165 → 0.0.167

package/LICENSE

@@ -1,14 +1,14 @@
-Copyright (c) 2025 3dsource
-All Rights Reserved.
-
-This software and associated documentation files (the “Software”) are proprietary
-and confidential. Unauthorized copying, modification, distribution, or any other
-use of the Software, in whole or in part, without the prior written consent of
-the copyright holder is strictly prohibited.
-
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
-COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2025 3dsource
+All Rights Reserved.
+
+This software and associated documentation files (the “Software”) are proprietary
+and confidential. Unauthorized copying, modification, distribution, or any other
+use of the Software, in whole or in part, without the prior written consent of
+the copyright holder is strictly prohibited.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,224 +1,228 @@
-# @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.
-
-> `UNREAL_CONFIG` on a route's `providers` does **not** work: the engine
-> services are `providedIn: 'root'`, so they are created by the root injector
-> and read the token from there. A route-level value is invisible to them and
-> `inject(UNREAL_CONFIG, { optional: true })` resolves to `null` — e.g. region
-> pinging is skipped entirely (empty `regionsPingUrl`), the orchestration
-> `requestStream` goes out without a region and the post-connection re-ping
-> never runs. Importing only the token at the root does not pull the module into
-> the initial bundle (the package is `sideEffects: false`).
-
-### 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.
-It also forwards the orchestration-issued `streamRequestId` from the polling
-response to Cirrus on the WebSocket URL (the session `connectionId`) and parks it
-for the Angular side to adopt.
-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.18.0.
+# @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/types-unreal >=0.0.7`
+- `@3dsource/utils >=1.0.21`
+- `provideHttpClient()` in the host application
+
+## Installation
+
+```shell
+pnpm add @3dsource/angular-unreal-module @3dsource/types-unreal @3dsource/utils
+```
+
+The package is standalone and does not expose an NgModule.
+
+### Styling
+
+The package ships its own styles and does not require any UI library. Its
+components read `--src-*` design tokens where available, but every token has a
+built-in fallback, so `@3dsource/source-ui-native` is entirely optional: install
+it in the host application only if you want the components to follow that theme.
+
+## 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.
+
+> `UNREAL_CONFIG` on a route's `providers` does **not** work: the engine
+> services are `providedIn: 'root'`, so they are created by the root injector
+> and read the token from there. A route-level value is invisible to them and
+> `inject(UNREAL_CONFIG, { optional: true })` resolves to `null` — e.g. region
+> pinging is skipped entirely (empty `regionsPingUrl`), the orchestration
+> `requestStream` goes out without a region and the post-connection re-ping
+> never runs. Importing only the token at the root does not pull the module into
+> the initial bundle (the package is `sideEffects: false`).
+
+### 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.
+
+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.
+It also forwards the orchestration-issued `streamRequestId` from the polling
+response to Cirrus on the WebSocket URL (the session `connectionId`) and parks it
+for the Angular side to adopt.
+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 `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.18.0.