@3dsource/angular-unreal-module 0.0.161 → 0.0.162

package/README.md

@@ -114,6 +114,15 @@ 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

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

@@ -1538,6 +1538,16 @@ class RegionsPingService {
                     pingsMs: data.result,
                 }))), map$1((data) => data.region_code));
             }
+            // No regions URL and no cache: there is nothing to ping. Bail out loudly
+            // instead of letting `HttpClient.get('')` request the current document
+            // (which yields HTML, fails to parse and silently resolves an empty
+            // region). The usual cause is `UNREAL_CONFIG` provided on a lazy route
+            // rather than at the application root — this service is
+            // `providedIn: 'root'`, so a route-level value never reaches it.
+            if (!regionListUrl) {
+                Logger.warn('RegionsPingService: regionsPingUrl is empty — skipping region discovery. Provide UNREAL_CONFIG at the APPLICATION ROOT (a route-level provider is invisible to root-scoped services).');
+                return of(undefined).pipe(tap(() => this.store.dispatch(regionPingFetchEnd())), tap(() => this.store.dispatch(regionResolved({ region: '', pingsMs: [] }))));
+            }
             return this.getProviders(regionListUrl).pipe(tap(() => this.store.dispatch(regionPingFetchEnd())), switchMap((providers) => this.getPingResult(providers)), catchError(() => of(null)), tapLog('PingResult'), 
             // Warm the cache with the live result so the next connection (and any
             // reload within the TTL) can skip pinging even if the prefetch script
@@ -1558,9 +1568,11 @@ class RegionsPingService {
      * All access is guarded — `localStorage` can throw (private mode, disabled
      * storage) or be absent (non-browser).
      *
-     * Public so adopted connections (which skip `getFastest`) can replay the
+     * Public so adopted connections (which skip `getFastest`) can still report a
      * region-resolving telemetry phase from the same cached winner — see
-     * `UnrealEffects.regionTelemetryOnAdopt$`.
+     * `StreamStatusTelemetryService2.emitAdoptedConnection`. Returns `null` when
+     * the region-ping prefetch never ran or its cache expired; that phase then
+     * carries no region and no ping samples.
      */
     readCachedWinner() {
         try {
@@ -1606,6 +1618,10 @@ class RegionsPingService {
      * connection handshake. Aborts with the injector via `destroyController`.
      */
     refreshCacheInBackground(regionListUrl = this.unrealConfig?.regionsPingUrl || '') {
+        if (!regionListUrl) {
+            Logger.warn('RegionsPingService: regionsPingUrl is empty — skipping the background region re-ping.');
+            return of(null);
+        }
         return defer(() => this.getProviders(regionListUrl)).pipe(switchMap((providers) => from(this.measureAccurate(providers.regions, providers.timeout ?? this.config.ping_timeout))), tap((winner) => {
             if (winner) {
                 this.writeCachedWinner(winner.region_code, winner.result);
@@ -2198,9 +2214,18 @@ class SignallingService extends SubService {
             },
         }));
     }
+    /**
+     * Status message for the connect branch. It does NOT dispatch
+     * `setEstablishingConnection` — `UnrealEffects.connectToSignaling$` already
+     * emits that once per logical attempt via `startWith(...)`, covering BOTH
+     * branches (prefetch adoption and a fresh connect). Dispatching it here as
+     * well fired the boundary twice on every cold start, and since
+     * `StreamStatusTelemetryService2` starts a session on that boundary, the
+     * first session was killed 2 ms in as `restart` — losing the only honest
+     * page-load measurement and the prefetch adoption with it.
+     */
     startEstablishingConnection() {
         this.showStatusMessage(UnrealStatusMessage.STARTING_YOUR_SESSION);
-        this.store.dispatch(setEstablishingConnection({ value: true }));
     }
     adaptUrlsToRegion(urlList, region) {
         return urlList.map((url) => {
@@ -3688,11 +3713,12 @@ class StreamAdoptionService {
      *
      * Wrapped in `defer` so the `tryAdopt()` side effect (which dispatches
      * `streamAdopted`) runs at SUBSCRIPTION time, not when the observable is
-     * built. The effect prepends `startWith(setEstablishingConnection(true))`,
-     * which starts the telemetry session and subscribes its phase catalog; that
-     * must happen BEFORE `streamAdopted` → `regionTelemetryOnAdopt$` replays
-     * `regionResolved`, or the region phase fires into a session that doesn't
-     * exist yet and is lost. `defer` guarantees that ordering.
+     * built. The effect prepends `startWith(setEstablishingConnection(true))` —
+     * the single dispatch site for that boundary — which starts the telemetry
+     * session and subscribes its phase catalog; that must happen BEFORE
+     * `streamAdopted`, or `emitAdoptedConnection` fires into a session that does
+     * not exist yet and the whole connection waterfall is lost. `defer`
+     * guarantees that ordering.
      */
     awaitAndAdopt$() {
         return defer(() => {
@@ -5880,10 +5906,14 @@ class StreamStatusTelemetryService2 {
                     // CLOSER — the `regionResolved` action carries the raw ping
                     // samples (one per probe) from `RegionsPingService`; the
                     // catalog flattens them to a comma-separated string since
-                    // `toPhaseParams` only accepts primitives. Adopted connections never
-                    // run `getRegion`, but `UnrealEffects.regionTelemetryOnAdopt$` replays
-                    // the region waterfall (start → end → resolved) from the cached winner,
-                    // so this phase still appears with its ping samples.
+                    // `toPhaseParams` only accepts primitives.
+                    //
+                    // Adopted connections never run `getRegion`, so this closer never
+                    // fires for them (and is suppressed anyway via PREFETCHED_PHASE_IDS).
+                    // Their region phase comes from {@link emitAdoptedConnection}, which
+                    // reports `duration: 0`, no milestones, and reads the winner + samples
+                    // out of the ping cache — so it is EMPTY when the region-ping prefetch
+                    // never ran or its cache expired.
                     {
                         id: 'region-resolved',
                         event: this.actions$.pipe(ofType(regionResolved), take(1), map(({ region, pingsMs }) => ({
@@ -6053,12 +6083,17 @@ class StreamStatusTelemetryService2 {
         // times per page load (the unreal-scene effect, `startStream`, the
         // reconnect effect), but the connection layer collapses them into one
         // attempt via `connectToSignaling$` (`exhaustMap` + `!cirrusConnected`
-        // filter). `setEstablishingConnection(true)` is dispatched exactly
-        // once per real attempt from `SignallingService.startEstablishingConnection()`,
-        // downstream of that guard — so binding here yields one session per
-        // attempt instead of a burst of `restart` churn sessions. Genuine
+        // filter). `setEstablishingConnection(true)` is dispatched exactly once
+        // per real attempt, by that effect's `startWith(...)` — the SINGLE
+        // dispatch site, downstream of the guard and ahead of both branches
+        // (prefetch adoption / fresh connect). So binding here yields one session
+        // per attempt instead of a burst of `restart` churn sessions. Genuine
         // reconnects (e.g. DataChannelTimeout) re-enter the same path and
         // correctly end the prior session as `restart` + start a new one.
+        //
+        // Do NOT add a second dispatch site: this binding turns every extra
+        // `true` into `endSession('restart')` + a new session, which throws away
+        // the first session's page-load measurement and its prefetch adoption.
         this.actions$
             .pipe(ofType(setEstablishingConnection), filter$1(({ value }) => value === true), takeUntil$1(this.destroy$))
             .subscribe(() => this.startSession());