feat(examples-chat): App-mode toggle + map-compatible routing (embed↔sidebar coercion)

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

Author: blove

examples/chat/angular/src/app/shell/demo-shell.component.css

@@ -177,3 +177,44 @@
 .demo-shell ::ng-deep .chat-sidebar__panel {
   top: 0;
 }
+
+/* App-mode toggle: pill button in the toolbar. Enabled only when a Google
+ * Maps key is configured (App mode renders the map cockpit). */
+.demo-shell__app-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 4px 10px 4px 8px;
+  border-radius: 999px;
+  border: 1px solid var(--tplane-chat-separator);
+  background: transparent;
+  color: var(--tplane-chat-text-muted);
+  cursor: pointer;
+  font: inherit;
+  font-size: var(--tplane-chat-font-size-sm);
+  flex: 0 0 auto;
+}
+.demo-shell__app-toggle:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+.demo-shell__app-toggle.is-on {
+  color: var(--tplane-chat-on-primary);
+  background: var(--tplane-chat-primary);
+  border-color: var(--tplane-chat-primary);
+}
+.demo-shell__app-toggle-icon {
+  font-family: 'Material Symbols Outlined', sans-serif;
+  font-size: 16px;
+  line-height: 1;
+}
+.demo-shell__app-toggle-thumb {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--tplane-chat-text-muted);
+}
+.demo-shell__app-toggle.is-on .demo-shell__app-toggle-thumb {
+  background: var(--tplane-chat-on-primary);
+}

examples/chat/angular/src/app/shell/demo-shell.component.html

@@ -21,6 +21,20 @@
       }
     </div>
 
+    <button
+      type="button"
+      class="demo-shell__app-toggle"
+      [class.is-on]="appMode() === 'on'"
+      [attr.aria-pressed]="appMode() === 'on'"
+      [disabled]="!hasMapsKey"
+      [attr.title]="hasMapsKey ? null : 'Set GOOGLE_MAPS_API_KEY to enable'"
+      (click)="onAppModeChange(appMode() === 'on' ? 'off' : 'on')"
+    >
+      <span class="demo-shell__app-toggle-icon" aria-hidden="true">map</span>
+      <span class="demo-shell__app-toggle-label">App mode</span>
+      <span class="demo-shell__app-toggle-thumb" aria-hidden="true"></span>
+    </button>
+
     <div class="demo-shell__field demo-shell__field--first" data-field="model">
       <chat-select
         [options]="modelOptions()"

examples/chat/angular/src/app/shell/demo-shell.component.spec.ts

@@ -387,6 +387,87 @@ describe('DemoShell — URL knob hydration', () => {
   });
 });
 
+describe('DemoShell — App mode routing', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    TestBed.configureTestingModule({
+      providers: [
+        threadsAdapterProvider,
+        ItineraryStore,
+        provideRouter([
+          { path: 'embed', component: DemoShell },
+          { path: 'popup', component: DemoShell },
+          { path: 'sidebar', component: DemoShell },
+          { path: '', pathMatch: 'full', redirectTo: 'embed' },
+          { path: '**', redirectTo: 'embed' },
+        ]),
+      ],
+    });
+  });
+
+  it('coerces embed → sidebar when App mode turns on', async () => {
+    const router = TestBed.inject(Router);
+    await router.navigateByUrl('/embed');
+    const fx = TestBed.createComponent(DemoShell);
+    fx.detectChanges();
+
+    const cmp = fx.componentInstance as unknown as {
+      appMode: () => 'on' | 'off';
+      onAppModeChange(v: 'on' | 'off'): void;
+    };
+    expect(cmp.appMode()).toBe('off');
+
+    cmp.onAppModeChange('on');
+    fx.detectChanges();
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+    expect(cmp.appMode()).toBe('on');
+    expect(router.url).toContain('/sidebar');
+  });
+
+  it('turning App mode off keeps the current route', async () => {
+    const router = TestBed.inject(Router);
+    await router.navigateByUrl('/sidebar');
+    const fx = TestBed.createComponent(DemoShell);
+    fx.detectChanges();
+
+    const cmp = fx.componentInstance as unknown as {
+      appMode: { (): 'on' | 'off'; set(v: 'on' | 'off'): void };
+      onAppModeChange(v: 'on' | 'off'): void;
+    };
+    cmp.appMode.set('on');
+    fx.detectChanges();
+
+    cmp.onAppModeChange('off');
+    fx.detectChanges();
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+    expect(cmp.appMode()).toBe('off');
+    expect(router.url).toContain('/sidebar');
+    expect(router.url).not.toContain('/embed');
+  });
+
+  it('selecting embed while App mode on turns App mode off', async () => {
+    const router = TestBed.inject(Router);
+    await router.navigateByUrl('/sidebar');
+    const fx = TestBed.createComponent(DemoShell);
+    fx.detectChanges();
+
+    const cmp = fx.componentInstance as unknown as {
+      appMode: { (): 'on' | 'off'; set(v: 'on' | 'off'): void };
+      onModeChange(next: string): void;
+    };
+    cmp.appMode.set('on');
+    fx.detectChanges();
+
+    cmp.onModeChange('embed');
+    fx.detectChanges();
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+    expect(cmp.appMode()).toBe('off');
+  });
+});
+
 // ── Itinerary ↔ checkpoint sync (Task 9) ────────────────────────────────────
 
 /** A FakeStreamTransport that records the payload of the most recent

examples/chat/angular/src/app/shell/demo-shell.component.ts

@@ -310,6 +310,38 @@ export class DemoShell {
 
   protected readonly mode = computed<DemoMode>(() => this.urlState().mode);
 
+  /** Whether the Google Maps key is configured — App mode needs the map,
+   *  so the toggle is disabled without it. */
+  readonly hasMapsKey = (environment.googleMapsApiKey as string).length > 0;
+
+  /** App mode: a presentational layer valid only in popup/sidebar (embed's
+   *  full-bleed chat would cover the map). Persisted across reloads and
+   *  mirrored to the `appmode` query param so shared links restore it. */
+  readonly appMode = signal<'on' | 'off'>(this.initialAppMode());
+
+  /** Mode parsed from the REAL browser path. Available immediately at
+   *  bootstrap (unlike router.url, which reads '/' before the initial
+   *  navigation settles), so App mode restores against the right route. */
+  private locationMode(): DemoMode {
+    const path = this.document.defaultView?.location.pathname ?? '';
+    const seg = path.split('/').filter(Boolean)[0];
+    return (MODES as readonly string[]).includes(seg) ? (seg as DemoMode) : 'embed';
+  }
+
+  /** App mode persists across reloads, but it can only run in popup/sidebar —
+   *  embed is full-chat with no background for the map. Reads the `appmode`
+   *  query param from the real browser URL (available at bootstrap, unlike
+   *  ActivatedRoute), falling back to persistence. Starts off when the value
+   *  isn't 'on' OR the current route is embed (e.g. a hand-typed
+   *  /embed?appmode=on). */
+  private initialAppMode(): 'on' | 'off' {
+    const search = this.document.defaultView?.location.search ?? '';
+    const raw = (new URLSearchParams(search).get('appmode') ??
+      this.persistence.read('appMode')) as 'on' | 'off' | null;
+    if (raw !== 'on') return 'off';
+    return this.locationMode() === 'embed' ? 'off' : 'on';
+  }
+
   /**
    * Source of truth for the model picker. The shell owns it; the
    * patched submit injects it into state on every send.
@@ -528,6 +560,13 @@ export class DemoShell {
   protected readonly _demoState: DemoState = this.agent.value();
 
   protected onModeChange(next: DemoMode | string): void {
+    // Embed can't coexist with App mode (its full-bleed chat covers the
+    // map), so selecting Embed while App mode is on turns App mode off.
+    // Popup and Sidebar layer over the map, so they leave App mode alone.
+    if (next === 'embed' && this.appMode() === 'on') {
+      this.appMode.set('off');
+      this.persistence.write('appMode', 'off');
+    }
     // Preserve the active thread across mode switches: /embed/abc →
     // /popup/abc keeps the conversation visible in the new chrome.
     // Preserve query params so knob state survives the mode hop.
@@ -538,6 +577,45 @@ export class DemoShell {
     );
   }
 
+  /**
+   * Toggle App mode. Enabling it needs a background area for the map —
+   * embed has none, so it coerces to the sidebar cockpit; popup/sidebar
+   * keep their current presentation. Unlike ag-ui-shell (which has a
+   * knob→URL effect that resolves routing), demo-shell is URL-as-truth,
+   * so this handler both navigates AND writes `appmode` to the query
+   * itself (merging so knob params survive).
+   */
+  onAppModeChange(v: 'on' | 'off'): void {
+    this.persistence.write('appMode', v);
+    if (v === 'on' && this.mode() === 'embed') {
+      // Navigate to the sidebar cockpit first (preserving query so the
+      // active thread + knobs survive), then flip the signal + stamp
+      // appmode=on into the URL.
+      const id = this.threadIdSignal();
+      void this.router
+        .navigate(id ? ['/', 'sidebar', id] : ['/', 'sidebar'], {
+          queryParamsHandling: 'preserve',
+        })
+        .then(() => {
+          this.appMode.set('on');
+          void this.router.navigate([], {
+            queryParams: { appmode: 'on' },
+            queryParamsHandling: 'merge',
+            replaceUrl: true,
+          });
+        });
+      return;
+    }
+    // popup/sidebar (or turning off): keep the current route, just update
+    // the appmode query param. 'off' → null drops it from the URL.
+    this.appMode.set(v);
+    void this.router.navigate([], {
+      queryParams: { appmode: v === 'off' ? null : 'on' },
+      queryParamsHandling: 'merge',
+      replaceUrl: true,
+    });
+  }
+
   /** Build the full knob → URL-value mapping. Default values become
    *  null so Angular's router drops them from the resulting URL when
    *  used with queryParamsHandling: 'merge'. */

examples/chat/angular/src/app/shell/palette-persistence.service.ts

@@ -12,6 +12,7 @@ interface PaletteState {
   sidenavMode?: 'expanded' | 'collapsed' | null;
   selectedProjectId?: string | null;
   colorScheme?: 'light' | 'dark' | null;
+  appMode?: 'on' | 'off' | null;
 }
 
 type PaletteKey = keyof PaletteState;
@@ -30,6 +31,7 @@ const ALLOWED = {
   theme:       new Set(['default-dark', 'default-light', 'material-dark', 'material-light']),
   colorScheme: new Set<string>(['light', 'dark']),
   sidenavMode: new Set<string>(['expanded', 'collapsed']),
+  appMode:     new Set<string>(['on', 'off']),
 } as const satisfies Partial<Record<PaletteKey, ReadonlySet<string>>>;
 
 type EnumKey = keyof typeof ALLOWED;