fix(ag-ui): gate <google-map> on Maps API load (blank-page-on-reload crash)

Reloading the demo with App mode persisted on rendered a blank page (only
the toolbar). Root cause (confirmed against @angular/google-maps
google-maps.mjs:136): the GoogleMap constructor throws "Namespace google
not found" when window.google is absent — and the Maps script loads
async, so on a fresh load it loses the race, the map throws during the
shell's initial render, and the whole shell render aborts (dev-mode only,
ngDevMode-gated, which is why #732 CI/smoke missed it; the P2 smoke only
toggled App mode at runtime, never reloaded with it persisted on).

Fix: a GoogleMapsLoader service exposing a `loaded` signal (owns the
script injection, flips on script.onload); gate <google-map> with
@if (loader.loaded()) so it never constructs before the API is present.
app.config loads eagerly through the same service so the GeocodingService
keeps working. markerOptions uses the numeric SymbolPath literal (0) as
defense-in-depth against eager google.* reads.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: blove

examples/ag-ui/angular/src/app/app.config.ts

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: MIT
 import {
   ApplicationConfig,
+  inject,
   provideBrowserGlobalErrorListeners,
   provideEnvironmentInitializer,
   provideZonelessChangeDetection,
@@ -13,6 +14,7 @@ import { environment } from '../environments/environment';
 import { routes } from './app.routes';
 import { ItineraryStore } from './itinerary-store';
 import { ITINERARY_AGENT } from './client-tools';
+import { GoogleMapsLoader } from './google-maps-loader';
 
 export const appConfig: ApplicationConfig = {
   providers: [
@@ -35,21 +37,12 @@ export const appConfig: ApplicationConfig = {
     // Typed agent provider: flows ItineraryState through DI so every
     // injectAgent(ITINERARY_AGENT) call returns AgUiAgent<ItineraryState>.
     provideAgent(ITINERARY_AGENT, { url: environment.agentUrl }),
-    // Load the Google Maps JS API once at bootstrap so the map canvas and the
-    // GeocodingService both run against the same loaded script. Skips cleanly
-    // when no key is configured (the googleMapsApiKey is '' in that case).
-    provideEnvironmentInitializer(() => {
-      const key = (environment.googleMapsApiKey as string) ?? '';
-      if (!key) return;
-      const g = globalThis as { google?: unknown };
-      if (g.google) return;
-      if (document.querySelector('script[data-google-maps]')) return;
-      const script = document.createElement('script');
-      script.src = `https://maps.googleapis.com/maps/api/js?key=${encodeURIComponent(key)}&libraries=geocoding`;
-      script.async = true;
-      script.setAttribute('data-google-maps', '');
-      document.head.appendChild(script);
-    }),
+    // Eagerly load the Google Maps JS API at bootstrap via the loader service,
+    // which owns the single `loaded` signal the map canvas gates its
+    // <google-map> on. Loading early lets the GeocodingService work before App
+    // mode is opened; the map still waits for `loaded()` so its component never
+    // constructs before the API is present. Skips cleanly with no key.
+    provideEnvironmentInitializer(() => inject(GoogleMapsLoader).ensureLoaded()),
     provideChat({ license: environment.license }),
     // The frontend-owned itinerary is a single shared instance: the panel,
     // the App component, and the client-tool ask component all inject it, so

examples/ag-ui/angular/src/app/google-maps-loader.ts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+import { Injectable, signal } from '@angular/core';
+import { environment } from '../environments/environment';
+
+/**
+ * Loads the Google Maps JS API on demand and exposes a `loaded` signal.
+ *
+ * Why this exists: `<google-map>` (from `@angular/google-maps`) THROWS in its
+ * constructor when `window.google` is absent ("Namespace google not found…",
+ * dev-mode only). The Maps script loads asynchronously, so rendering the map
+ * before it resolves aborts the host component's change-detection pass — which
+ * (on a fresh load with App mode persisted on) blanks the whole shell. The fix
+ * is the documented `@angular/google-maps` contract: only render `<google-map>`
+ * once the API is present. Consumers gate their template on `loaded()` and call
+ * `ensureLoaded()` once.
+ */
+@Injectable({ providedIn: 'root' })
+export class GoogleMapsLoader {
+  /** Becomes true once `window.google.maps` is available. */
+  readonly loaded = signal(false);
+  private started = false;
+
+  /** Idempotent: injects the Maps script once (if a key is present) and flips
+   *  `loaded` when ready. Safe to call from multiple components. */
+  ensureLoaded(): void {
+    if (this.loaded() || this.started) return;
+    const w = globalThis as { google?: { maps?: unknown }; document?: Document };
+    if (w.google?.maps) {
+      this.loaded.set(true);
+      return;
+    }
+    this.started = true;
+
+    const key = (environment.googleMapsApiKey as string) ?? '';
+    if (!key) return; // No key → map stays gated off (the toolbar toggle is also disabled).
+
+    const doc = w.document;
+    if (!doc) return;
+
+    const existing = doc.querySelector('script[data-google-maps]');
+    if (existing) {
+      // A load is already in flight (e.g. a prior instance). Poll for readiness.
+      const poll = setInterval(() => {
+        if ((globalThis as { google?: { maps?: unknown } }).google?.maps) {
+          clearInterval(poll);
+          this.loaded.set(true);
+        }
+      }, 100);
+      return;
+    }
+
+    const script = doc.createElement('script');
+    script.src = `https://maps.googleapis.com/maps/api/js?key=${encodeURIComponent(key)}&libraries=geocoding`;
+    script.async = true;
+    script.setAttribute('data-google-maps', '');
+    script.addEventListener('load', () => this.loaded.set(true));
+    doc.head.appendChild(script);
+  }
+}

examples/ag-ui/angular/src/app/map-canvas.component.ts

@@ -12,6 +12,7 @@ import {
 } from '@angular/core';
 import { GoogleMap, MapInfoWindow, MapMarker, MapPolyline } from '@angular/google-maps';
 import { ItineraryStop, ItineraryStore } from './itinerary-store';
+import { GoogleMapsLoader } from './google-maps-loader';
 
 const DARK_STYLE: google.maps.MapTypeStyle[] = [
   { elementType: 'geometry', stylers: [{ color: '#1d2c4d' }] },
@@ -37,36 +38,41 @@ const PARIS_CENTER: google.maps.LatLngLiteral = { lat: 48.8566, lng: 2.3522 };
   imports: [GoogleMap, MapInfoWindow, MapMarker, MapPolyline],
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: `
-    <google-map
-      width="100%"
-      height="100%"
-      [center]="center()"
-      [zoom]="zoom()"
-      [options]="mapOptions"
-    >
-      @for (s of stopsWithCoords(); track s.id) {
-        <map-marker
-          #marker
-          [position]="{ lat: s.lat!, lng: s.lng! }"
-          [options]="markerOptions(s)"
-          (mapClick)="onMarkerClick(s)"
-        />
-      }
-      @for (line of polylines(); track line.day) {
-        <map-polyline [path]="line.path" [options]="polylineOptions(line.day)" />
-      }
-      <map-info-window>
-        @if (focused(); as f) {
-          <div class="info">
-            <strong>{{ f.place }}</strong>
-            @if (f.note) {
-              <div class="info__note">{{ f.note }}</div>
-            }
-            <button type="button" class="info__remove" (click)="removeFocused()">Remove</button>
-          </div>
+    <!-- Render <google-map> ONLY after the Maps API has loaded. Its constructor
+         throws "Namespace google not found" when window.google is absent, which
+         would abort the host shell's render on a fresh load with App mode on. -->
+    @if (loader.loaded()) {
+      <google-map
+        width="100%"
+        height="100%"
+        [center]="center()"
+        [zoom]="zoom()"
+        [options]="mapOptions"
+      >
+        @for (s of stopsWithCoords(); track s.id) {
+          <map-marker
+            #marker
+            [position]="{ lat: s.lat!, lng: s.lng! }"
+            [options]="markerOptions(s)"
+            (mapClick)="onMarkerClick(s)"
+          />
         }
-      </map-info-window>
-    </google-map>
+        @for (line of polylines(); track line.day) {
+          <map-polyline [path]="line.path" [options]="polylineOptions(line.day)" />
+        }
+        <map-info-window>
+          @if (focused(); as f) {
+            <div class="info">
+              <strong>{{ f.place }}</strong>
+              @if (f.note) {
+                <div class="info__note">{{ f.note }}</div>
+              }
+              <button type="button" class="info__remove" (click)="removeFocused()">Remove</button>
+            </div>
+          }
+        </map-info-window>
+      </google-map>
+    }
   `,
   styles: [
     `
@@ -83,6 +89,7 @@ const PARIS_CENTER: google.maps.LatLngLiteral = { lat: 48.8566, lng: 2.3522 };
 })
 export class MapCanvasComponent {
   protected readonly store = inject(ItineraryStore);
+  protected readonly loader = inject(GoogleMapsLoader);
   protected readonly center = signal<google.maps.LatLngLiteral>(PARIS_CENTER);
   protected readonly zoom = signal<number>(12);
   protected readonly mapOptions: google.maps.MapOptions = {
@@ -104,6 +111,8 @@ export class MapCanvasComponent {
   );
 
   constructor() {
+    this.loader.ensureLoaded();
+
     effect(() => {
       const f = this.focused();
       if (!f || f.lat == null || f.lng == null) return;
@@ -140,7 +149,9 @@ export class MapCanvasComponent {
   protected markerOptions(s: ItineraryStop): google.maps.MarkerOptions {
     return {
       icon: {
-        path: google.maps.SymbolPath.CIRCLE,
+        // Numeric literal for google.maps.SymbolPath.CIRCLE (=0) — avoids an
+        // eager google.* value read (defense-in-depth alongside the loader gate).
+        path: 0,
         fillColor: DAY_COLORS[(s.day - 1) % DAY_COLORS.length],
         fillOpacity: 1,
         strokeColor: '#fff',