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

* 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>

* fix(ag-ui): hide sidebar launcher hint when App mode is on

In App mode the Google Map is the full-bleed background and the chat
sidebar floats over it, so the placeholder "Use the launcher…" hint
(projected into chat-sidebar's default content slot) floated unreadably
over the map. Gate it on appMode !== 'on' so it only shows in plain
sidebar mode where the area behind the chat is genuinely empty.

Verified via DOM probe: /sidebar appMode off → hint present (1);
/sidebar?appmode=on with the map mounted → hint absent (0).

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

* feat(ag-ui): itinerary panel is App-mode-only (drop the sidebar panel)

The frontend-owned itinerary used to render twice: as a fixed 300px panel
beside the chat in plain embed/sidebar mode, and as the floating overlay
in App mode. Remove the former — the itinerary now appears only in App
mode, as the map overlay. Plain mode is just the chat; the App-mode toggle
reveals the map + itinerary.

Drops <app-itinerary-panel class="ag-ui-shell__itinerary"> from the
non-App-mode body and its now-dead two-column / responsive CSS. The
ItineraryPanelComponent import stays (still used by the overlay).

The itinerary-client-tools e2e suite drove the panel in default mode, so
point it at ?appmode=on — App mode is URL-driven regardless of the
key-gated toolbar toggle, and the overlay panel renders independent of the
map, so the same panel DOM is present even without GOOGLE_MAPS_API_KEY in CI.

Verified via DOM probe: clean default → 0 itinerary panels (just chat);
?appmode=on → overlay panel with the Louvre/Eiffel/Orsay seed + map mounted.

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

* fix(ag-ui): restore the App-mode cockpit route on reload

App mode persists via localStorage, but on a fresh load with it persisted
on the app rendered the itinerary overlay yet showed EmbedMode's full-bleed
chat over the map instead of the sidebar cockpit. Root cause: the knob
persist effect navigated with a route-relative `navigate([])`, which at
bootstrap resolves against the not-yet-settled initial navigation and lands
on the default /embed — so the router-outlet mounted EmbedMode (z-index
above the map) while appMode-gated chrome (overlay, map-canvas) still
rendered.

Navigate to the absolute `/sidebar` whenever App mode is on (the layout the
cockpit requires), keeping the route-relative `[]` only when it's off. Also
drop the now-redundant navigate in onAppModeChange — the effect is the
single source of routing truth for both the toggle and reload paths.

Verified: toggle on → /sidebar; reload from / → stays /sidebar with the
sidebar chat + map + overlay (was bouncing to /embed); toggle off keeps the
current route with plain chat; clean default still lands on /embed.

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

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: blove

examples/ag-ui/angular/e2e/itinerary-client-tools.spec.ts

@@ -8,6 +8,13 @@ import { attachBrowserHygiene, messageInput, openDemo, sendButton } from './test
 // the ToolMessage re-runs the graph, and the continuation streams back. Each
 // test starts from the store seed (Day 1: Louvre + Eiffel Tower, Day 2: Musée
 // d'Orsay) by clearing the persisted key before the page hydrates.
+//
+// The itinerary panel only renders in App mode (it's the floating map overlay;
+// plain embed/sidebar no longer shows it), so these tests open the demo with
+// `?appmode=on`. App mode is driven from the URL regardless of the key-gated
+// toolbar toggle, and the overlay panel renders independent of the map — so the
+// same panel DOM (region "Trip itinerary", section.itin__day, .itin__handle …)
+// is present even without a GOOGLE_MAPS_API_KEY in CI.
 const STORAGE_KEY = 'ag-ui-demo:itinerary';
 
 test.beforeEach(async ({ page }) => {
@@ -19,7 +26,7 @@ test.beforeEach(async ({ page }) => {
 });
 
 test('panel renders the seeded itinerary', async ({ page }) => {
-  await openDemo(page);
+  await openDemo(page, '/?appmode=on');
 
   const panel = page.getByRole('region', { name: 'Trip itinerary' });
   await expect(panel).toBeVisible();
@@ -31,7 +38,7 @@ test('panel renders the seeded itinerary', async ({ page }) => {
 test('read round-trip: get_itinerary executes in the browser and the run continues', async ({
   page,
 }) => {
-  await openDemo(page);
+  await openDemo(page, '/?appmode=on');
   const hygiene = attachBrowserHygiene(page);
 
   await messageInput(page).fill("What's on my itinerary?");
@@ -46,7 +53,7 @@ test('read round-trip: get_itinerary executes in the browser and the run continu
 });
 
 test('ask chain: clear_day confirm mutates the panel and resumes the run', async ({ page }) => {
-  await openDemo(page);
+  await openDemo(page, '/?appmode=on');
 
   await messageInput(page).fill('Clear my day 2 plans');
   await sendButton(page).click();
@@ -79,7 +86,7 @@ test('ask chain: clear_day confirm mutates the panel and resumes the run', async
 test('move_stop action: panel mutates — Eiffel Tower moves from day 1 to day 2', async ({
   page,
 }) => {
-  await openDemo(page);
+  await openDemo(page, '/?appmode=on');
 
   // Seed has Eiffel Tower under Day 1 — verify it's there before sending.
   const panel = page.getByRole('region', { name: 'Trip itinerary' });
@@ -112,7 +119,7 @@ test('move_stop action: panel mutates — Eiffel Tower moves from day 1 to day 2
 test('day_card view: component renders with model-filled props and run auto-continues', async ({
   page,
 }) => {
-  await openDemo(page);
+  await openDemo(page, '/?appmode=on');
 
   await messageInput(page).fill('Show me a recap card for day 1');
   await sendButton(page).click();
@@ -130,7 +137,7 @@ test('day_card view: component renders with model-filled props and run auto-cont
 });
 
 test('user can drag-reorder stops within a day', async ({ page }) => {
-  await openDemo(page);
+  await openDemo(page, '/?appmode=on');
 
   const panel = page.getByRole('region', { name: 'Trip itinerary' });
 
@@ -170,7 +177,7 @@ test('user can drag-reorder stops within a day', async ({ page }) => {
 });
 
 test('reorder_stop: agent puts Louvre last on day 1', async ({ page }) => {
-  await openDemo(page);
+  await openDemo(page, '/?appmode=on');
   const hygiene = attachBrowserHygiene(page);
 
   await messageInput(page).fill('Put Louvre last on day 1.');

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',

examples/ag-ui/angular/src/app/modes/sidebar-mode.component.ts

@@ -22,9 +22,13 @@ import { WelcomeSuggestionsComponent } from './welcome-suggestions.component';
       (selectedModelChange)="shell.onModelChange($event)"
     >
       <div class="sidebar-mode__background">
-        <p class="sidebar-mode__hint">
-          Use the launcher (right edge) to dismiss or re-open the chat panel.
-        </p>
+        <!-- In App mode the map is the background; this placeholder hint would
+             float unreadably over it, so only show it in plain sidebar mode. -->
+        @if (shell.appMode() !== 'on') {
+          <p class="sidebar-mode__hint">
+            Use the launcher (right edge) to dismiss or re-open the chat panel.
+          </p>
+        }
       </div>
       <welcome-suggestions chatWelcomeSuggestions (selected)="send($event)" />
     </chat-sidebar>

examples/ag-ui/angular/src/app/shell/ag-ui-shell.component.css

@@ -195,29 +195,11 @@
 }
 .ag-ui-shell__theme-toggle--toolbar { margin-left: auto; }
 
-/* Two-column body: frontend-owned itinerary panel beside the routed chat
- * (ported from the pre-shell layout that #655 introduced). */
+/* Non-App-mode body: the routed chat fills the area below the toolbar.
+ * The itinerary lives only in App mode now, as the floating map overlay. */
 .ag-ui-shell__body { flex: 1 1 auto; min-height: 0; display: flex; }
-.ag-ui-shell__itinerary {
-  flex: 0 0 300px;
-  min-height: 0;
-  overflow-y: auto;
-  border-right: 1px solid var(--ngaf-chat-separator);
-}
 .ag-ui-shell__body > .ag-ui-shell__main { flex: 1 1 auto; min-width: 0; min-height: 0; display: flex; flex-direction: column; }
 
-/* Stack to a single column on narrow viewports; the panel goes full-width
- * above the chat. */
-@media (max-width: 900px) {
-  .ag-ui-shell__body { flex-direction: column; }
-  .ag-ui-shell__itinerary {
-    flex: 0 0 auto;
-    max-height: 40dvh;
-    border-right: none;
-    border-bottom: 1px solid var(--ngaf-chat-separator);
-  }
-}
-
 .ag-ui-shell__app-toggle {
   display: inline-flex;
   align-items: center;

examples/ag-ui/angular/src/app/shell/ag-ui-shell.component.html

@@ -70,7 +70,6 @@
     </div>
   } @else {
     <div class="ag-ui-shell__body">
-      <app-itinerary-panel class="ag-ui-shell__itinerary" />
       <div class="ag-ui-shell__main">
         <router-outlet />
         @if (agent.interrupt && agent.interrupt()) {

examples/ag-ui/angular/src/app/shell/ag-ui-shell.component.ts

@@ -169,7 +169,15 @@ export class AgUiShell {
         scheme: this.colorScheme() === DEFAULTS.scheme ? null : this.colorScheme(),
         appmode: this.appMode() === 'off' ? null : this.appMode(),
       };
-      void this.router.navigate([], { queryParams: q, queryParamsHandling: 'merge', replaceUrl: true });
+      // App mode's layout requires the sidebar route (chat as the right rail
+      // beside the map). On a fresh load with App mode persisted on, a
+      // route-relative navigate([]) resolves against the not-yet-settled
+      // initial navigation and lands on the default /embed — mounting
+      // EmbedMode over the map. Navigate to the absolute /sidebar whenever
+      // App mode is on so a reload restores the cockpit; otherwise keep the
+      // current route ([]) and just sync query params.
+      const commands = this.appMode() === 'on' ? ['/', 'sidebar'] : [];
+      void this.router.navigate(commands, { queryParams: q, queryParamsHandling: 'merge', replaceUrl: true });
     });
   }
 
@@ -180,9 +188,8 @@ export class AgUiShell {
   onAppModeChange(v: 'on' | 'off'): void {
     this.appMode.set(v);
     this.persistence.write('appMode', v);
-    if (v === 'on' && this.mode() !== 'sidebar') {
-      void this.router.navigate(['/', 'sidebar'], { queryParamsHandling: 'preserve' });
-    }
+    // Routing is handled by the persist effect, which forces /sidebar whenever
+    // App mode is on (toggle and reload alike) and keeps the current route off.
   }
   onModelChange(v: string): void { this.model.set(v); this.persistence.write('model', v); }
   protected onEffortChange(v: string): void { this.effort.set(v); this.persistence.write('effort', v); }