@3dsource/angular-unreal-module 0.0.177 → 0.0.181

package/README.md

@@ -9,18 +9,27 @@ command/callback APIs, reconnection, file transfer and telemetry.
 - 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`
+- `@3dsource/types-unreal >=0.0.14 <0.1.0`
 - `provideHttpClient()` in the host application
 
 ## Installation
 
 ```shell
-pnpm add @3dsource/angular-unreal-module @3dsource/types-unreal @3dsource/utils
+pnpm add @3dsource/angular-unreal-module @3dsource/types-unreal
 ```
 
 The package is standalone and does not expose an NgModule.
 
+### Entry points
+
+| Entry point                              | Contains                                                                             |
+| ---------------------------------------- | ------------------------------------------------------------------------------------ |
+| `@3dsource/angular-unreal-module`        | Everything — scene component, services, NgRx state, providers, helpers               |
+| `@3dsource/angular-unreal-module/config` | `UNREAL_CONFIG`, `UnrealInitialConfig`, `UnrealMode` only — no engine, 266 B of FESM |
+
+Import the token from `/config` in the application root and keep every other
+import behind a lazy route — see [Setup](#setup) for why.
+
 ### Styling
 
 The package ships its own styles and requires no UI library. Everything it draws
@@ -232,11 +241,11 @@ root. `UNREAL_CONFIG` is required, although all its fields are optional.
 import { provideHttpClient } from '@angular/common/http';
 import type { ApplicationConfig } from '@angular/core';
 import { provideStore } from '@ngrx/store';
+import { provideUnrealState } from '@3dsource/angular-unreal-module';
 import {
-  provideUnrealState,
   UNREAL_CONFIG,
   type UnrealInitialConfig,
-} from '@3dsource/angular-unreal-module';
+} from '@3dsource/angular-unreal-module/config';
 
 const unrealConfig = {
   regionsPingUrl: 'https://datacenter.3dsource.com/regions/',
@@ -257,6 +266,21 @@ export const appConfig: ApplicationConfig = {
 
 Omit `provideStore()` when the root NgRx store is already configured.
 
+`UNREAL_CONFIG` comes from the `/config` entry point on purpose. The token has to
+be provided in the **root** injector, because the module's services are
+`providedIn: 'root'` singletons and cannot see a route-level provider. The package
+itself ships as one FESM, and esbuild places a module in the common-ancestor chunk
+of its importers — so importing the token from the package root here pulls the
+whole engine into the application's eager bundle. On a metabox production build
+that was 180 kB raw (49 kB gzip) of `main` spent on pages that never stream.
+
+This pays off only while **nothing else** in the eager graph imports the package
+root. Following the example above literally does not qualify — the
+`provideUnrealState()` import next to it brings the FESM back. An app that wants
+the engine out of its initial bundle moves `provideUnrealState()` to the lazy
+route alongside `provideUnrealModule()` (step 2) and leaves only the
+`UNREAL_CONFIG` provider at the root.
+
 Available configuration fields:
 
 | Field                          | Purpose                                                                                                                                         |
@@ -353,6 +377,14 @@ export class StreamComponent {}
 
 Command packet types are provided by `@3dsource/types-unreal`.
 
+That package ships two type contours, prod and QA, and your application and
+this package must resolve the **same** one — the selection is a `tsconfig`
+path override on the bare specifier, never an import. A bundler that ignores
+`tsconfig` paths (plain Vite or webpack without a matching `resolve.alias`)
+takes the types from one contour and the enum values from the other, which
+fails at runtime rather than at compile time. See "Two contours: prod and QA"
+in the `@3dsource/types-unreal` README.
+
 Run `pnpm demo:start` from the repository root to see the scene component in
 the demo application.
 
@@ -405,31 +437,30 @@ required.
 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
+pnpm unreal-module:build
+pnpm unreal-module:build:watch
+pnpm unreal-module:lint
+pnpm unreal-module:test
+pnpm unreal-module:test:watch
+pnpm unreal-module:test:signalling
+pnpm unreal-module:test:signalling:leaks
 ```
 
-`unreal:build` builds the local `types-unreal` and `utils` dependencies before
-this package.
+`unreal-module:build` builds the local `types-unreal` dependency before this package.
 
 Release commands publish only this package:
 
 ```shell
-pnpm unreal:release:patch
-pnpm unreal:release:dev
+pnpm unreal-module:release:patch
+pnpm unreal-module: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
+pnpm unreal-module:purge-cdn -- latest
+pnpm unreal-module:purge-cdn -- dev
 ```
 
-Repository tooling requires Node.js 24.16.0 or newer and pnpm 11.22.0.
+Repository tooling requires Node.js 24.16.0 or newer and pnpm last version.