@angular/fire 20.1.0 → 21.0.0-canary.20260927232311.sha-38dfc3f

package/docs/install-and-setup.md

@@ -1,44 +1,62 @@
 # AngularFire Quickstart
 
+## Before you begin
+
+- **Firebase CLI**
+  - Setup uses the Firebase CLI (`firebase-tools`). Install it with `npm install -g firebase-tools`, then run `firebase login`. If `ng add` can't find a copy, it installs the newest version for you.
+  - Run `ng add` yourself, not through an AI agent.
+    - In AngularFire 21.0.0-rc.1 and earlier, `ng add` run by an agent with firebase-tools 15.26 or later stops after you choose features, with `Cannot read properties of undefined (reading 'email')`.
+    - If it already stopped, run `ng add @angular/fire@next` again yourself. The stopped run leaves only an empty `firebase.json`, which the second run reuses.
+  - A copy older than 14 stops setup with `firebase-tools version 14.0.0+ is required, please upgrade and run again`, and `ng add` does not upgrade a copy you already have.
+- **Harmless CLI noise.** The Firebase CLI may print a `punycode` deprecation warning or ask about enabling extra features (for example Gemini) during setup. These come from the CLI, not from AngularFire, and are safe to ignore.
+
 ### 1. Create a new project
 
 ```bash
 # Using yarn create
-yarn create @angular <project-name>
+yarn create @angular@21 <project-name>
 cd <project-name>
 ```
 or 
 
 ```bash
 # Using npm create
-npm create @angular <project-name>
+npm create @angular@21 <project-name>
 cd <project-name>
 ```
 
 optionally installing the tooling directly:
 ```bash
 # Installing the tooling directly
-npm install -g @angular/cli
+npm install -g @angular/cli@21
 ng new <project-name>
 cd <project-name>
 ```
 
-The Angular CLI's `new` command will set up the latest Angular build in a new project structure.
+These commands set up an Angular 21 project, the version AngularFire 21 supports.
 
 ### 2. Install AngularFire and Firebase
 
+AngularFire 21 is currently a release candidate, published under the `next` tag:
+
 ```bash
-ng add @angular/fire
+ng add @angular/fire@next
 ```
 
-Now that you have a new project setup, install AngularFire and Firebase from npm. This will complete the following tasks:
+This installs AngularFire and configures your project. `ng add` will:
 
-1. Add Firebase config to environments variables
-2. Configure `@NgModule` for the `AngularFireModule`
+1. Prompt you to select the features to enable and the Firebase project to use, signing you in to Firebase if needed.
+2. Add `provideFirebaseApp(...)`, along with a provider for each feature you select, to your app configuration (for example `app.config.ts`), with your Firebase configuration inlined. No environment files are created.
+
+`ng add` writes the version it installed into your `package.json`, and today that is a canary release such as `21.0.0-rc.1-canary.95b3de1` rather than the release candidate. To replace it with the release candidate, `21.0.0-rc.1`, run:
+
+```bash
+npm install --save-exact @angular/fire@next
+```
 
 ### 3. Inject `Firestore`
 
-Open `/src/app/app.component.ts`, and make the following changes to :
+Open `/src/app/app.ts` and make the following changes:
 
 ```ts
 import { Component, inject } from '@angular/core';
@@ -47,11 +65,11 @@ import { Firestore } from '@angular/fire/firestore';
 
 @Component({
   selector: 'app-root',
-  templateUrl: 'app.component.html',
-  styleUrls: ['app.component.css'],
+  templateUrl: './app.html',
+  styleUrl: './app.css',
   imports: [AsyncPipe],
 })
-export class AppComponent {
+export class App {
   firestore: Firestore = inject(Firestore);
 
   constructor() {
@@ -62,7 +80,7 @@ export class AppComponent {
 
 ### 4. Bind a Firestore collection to a list
 
-In `/src/app/app.component.ts`:
+In `/src/app/app.ts`:
 
 ```ts
 import { Component, inject } from '@angular/core';
@@ -70,25 +88,28 @@ import { AsyncPipe } from '@angular/common';
 import { Observable } from 'rxjs';
 import { Firestore, collection, collectionData } from '@angular/fire/firestore';
 
+interface Item {
+  name: string;
+}
+
 @Component({
   selector: 'app-root',
-  standalone: true,
   imports: [AsyncPipe],
-  templateUrl: 'app.component.html',
-  styleUrls: ['app.component.css']
+  templateUrl: './app.html',
+  styleUrl: './app.css'
 })
-export class AppComponent {
+export class App {
   firestore: Firestore = inject(Firestore);
-  items$: Observable<any[]>;
+  items$: Observable<Item[]>;
 
   constructor() {
     const aCollection = collection(this.firestore, 'items')
-    this.items$ = collectionData(aCollection);
+    this.items$ = collectionData<Item>(aCollection);
   }
 }
 ```
 
-Open `/src/app/app.component.html`:
+Open `/src/app/app.html`:
 
 ```html
 <ul>
@@ -112,8 +133,8 @@ Once you've created a `items` collection and are inserting documents, you should
 
 ### 6. Deploy your app
 
-Finally, we can deploy the application to Firebase hosting:
+How you deploy depends on whether your app uses server-side rendering (SSR), which the Angular CLI asks about when you create the project.
 
-```bash
-ng deploy
-```
+**Client-side rendered apps** (the default) build to static files, which you deploy to Firebase Hosting. Follow Firebase's [Hosting quickstart](https://firebase.google.com/docs/hosting/quickstart) to build and deploy your app.
+
+**Server-side rendered apps** run a Node server, so deploy them to [Firebase App Hosting](app-hosting.md), Firebase's recommended path for SSR. That guide also covers a common case where an SSR app silently falls back to client-side rendering after deploying.

package/docs/install-firebase-tools.md

@@ -1,5 +1,7 @@
 # Firebase Tools Install and Setup
 
+> Setting up AngularFire? Run `ng add @angular/fire` yourself, not through an AI agent. In AngularFire 21.0.0-rc.1 and earlier, `ng add` run by an agent with firebase-tools 15.26 or later stops after you choose AngularFire features, with `Cannot read properties of undefined (reading 'email')`.
+
 ### 1. Install package
 
 ```bash

package/docs/messaging.md

@@ -6,18 +6,16 @@
 
 # Cloud Messaging
 
-Firebase FCM allows you to register devices with unique FCM tokens, that you can later programtically send notifications to using Firebase Cloud Functions. It is up to the application to update these tokens in Firebase if you want to use them in other layers of your application, i.e send a notification to all administrators, etc. In that case, you would likely want to store your fcm tokens on your user collection, or a sub collection or another collection with different permissions.
+Firebase Cloud Messaging (FCM) allows you to register devices with unique FCM tokens, that you can later programatically send notifications to using Firebase Cloud Functions. It is up to the application to update these tokens in Firebase if you want to use them in other layers of your application, i.e send a notification to all administrators, etc. In that case, you would likely want to store your fcm tokens on your user collection, or a sub collection or another collection with different permissions.
 
 ## Dependency Injection
 
-As a prerequisite, ensure that `AngularFire` has been added to your project via
-```bash
-ng add @angular/fire
-```
+As a prerequisite, ensure that `AngularFire` has been added to your project as described in the [Quickstart](./install-and-setup.md).
 
 Provide a Cloud Messaging instance in the application's `app.config.ts`:
 
 ```ts
+import { ApplicationConfig } from '@angular/core';
 import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
 import { provideMessaging, getMessaging } from '@angular/fire/messaging';
 
@@ -28,7 +26,7 @@ export const appConfig: ApplicationConfig = {
     ...
   ],
   ...
-})
+}
 ```
 
 Next inject `Messaging` into your component:
@@ -46,7 +44,7 @@ export class AppComponent {
 
 # Create a Firebase Messaging Service Worker 
 
-There are two parts to Firebase Messaging, a Service Worker and the DOM API. Angular Fire Messaging allows you to request permission, get tokens, delete tokens, and subscribe to messages on the DOM side. To register to receive notifications you need to set up the Service Worker. [The official Firebase documentation for setting up the details exactly how to do that](https://firebase.google.com/docs/cloud-messaging/js/client).
+There are two parts to Firebase Messaging, a Service Worker and the DOM API. Angular Fire Messaging allows you to request permission, register this app instance, observe when it is registered or unregistered, and subscribe to messages on the DOM side. To register to receive notifications you need to set up the Service Worker. [The official Firebase documentation for setting up the details exactly how to do that](https://firebase.google.com/docs/cloud-messaging/js/client).
 
 #### Create your firebase-messaging-sw.js file in your src/assets folder
 
@@ -54,11 +52,12 @@ There are two parts to Firebase Messaging, a Service Worker and the DOM API. Ang
 
 It may be wise to use file replacements or environments here for different environments
 
-```
-// This sample application is using 9.22, make sure you are importing the same version
+```js
+/* Replace <firebase-version> with the firebase version in your package.json. The service
+ * worker and your application have to load the same version. */
 
-import { initializeApp } from "https://www.gstatic.com/firebasejs/9.22.0/firebase-app.js";
-import { getMessaging } from "https://www.gstatic.com/firebasejs/9.22.0/firebase-messaging-sw.js";
+import { initializeApp } from "https://www.gstatic.com/firebasejs/<firebase-version>/firebase-app.js";
+import { getMessaging } from "https://www.gstatic.com/firebasejs/<firebase-version>/firebase-messaging-sw.js";
 
 const firebaseApp = initializeApp({
   apiKey: "",
@@ -72,61 +71,92 @@ const firebaseApp = initializeApp({
 const messaging = getMessaging(firebaseApp);
 ```
 
+# Registering this app instance
+
+Firebase deprecated `getToken` and `deleteToken` in firebase 12.18 and will remove them. Use `register` with `onRegistered` in place of `getToken`, and `unregister` with `onUnregistered` in place of `deleteToken`. [Firebase's client guide](https://firebase.google.com/docs/cloud-messaging/js/client) describes the model and asks that you not mix the two sets.
+
+Three things to know before you copy the example below:
+
+- `onRegistered` has to be listening before `register` runs, which is why the example subscribes first. Otherwise `register` throws `No onRegistered callback handler was provided or registered.`
+- **Ask for notification permission yourself before calling `register`,** as the example does. Otherwise `register` asks for you from inside a call AngularFire wraps, which holds the client app unstable until the dialog is dismissed.
+  - That delays Angular event replay and clearing the server-rendered DOM, and logs a development-only warning after ten seconds. Asking first avoids all of it.
+  - This behavior may change in a future release.
+- The identifier reaches you through a callback rather than as a return value, and again whenever it changes, so store it from inside the callback rather than once at startup.
+
 # Example messaging service
 
-```
-import { Injectable } from "@angular/core";
-import { Messaging, getToken, onMessage, deleteToken } from "@angular/fire/messaging";
+```ts
+import { EnvironmentInjector, Injectable, inject, runInInjectionContext } from "@angular/core";
+import { Messaging, MessagePayload, onMessage, onRegistered, onUnregistered, register, unregister } from "@angular/fire/messaging";
 import { Observable, tap } from "rxjs";
 
-@Injectable({
-  providedIn: "root",
-})
+@Injectable({ providedIn: "root" })
 export class FcmService {
-  constructor(private msg: Messaging){
-    Notification.requestPermission().then(
-    (notificationPermissions: NotificationPermission) => {
-      if (notificationPermissions === "granted") {
-        console.log("Granted");
-      }
-      if (notificationPermissions === "denied") {
-        console.log("Denied");
-      }
+  private readonly injector = inject(EnvironmentInjector);
+  /* `onMessage` converted to an observable. Returns the unsubscribe function returned by
+   * `onMessage` to stop the listener when the last subscriber unsubscribes. */
+  message$ = new Observable<MessagePayload>(
+    subscriber => onMessage(this.msg, (msg) => subscriber.next(msg))
+  ).pipe(tap((msg) => console.log("My Firebase Cloud Message", msg)));
+
+  constructor(private msg: Messaging) {
+    // Set listeners before calling `register` to avoid throwing.
+    this.listenForRegistrationChanges();
+    this.registerForMessages();
+  }
+
+  private listenForRegistrationChanges() {
+    onRegistered(this.msg, (installationId) => {
+      /* This is a good place to store it in your database for each user.
+       * This callback fires whenever `installationId` changes. */
+      console.log("my installation id", installationId);
+    });
+
+    onUnregistered(this.msg, (installationId) => {
+      // Drop it from your database. Sending messages to an unregistered ID results in a 404.
+      console.log("no longer registered", installationId);
     });
-    navigator.serviceWorker
-      .register("/assets/firebase-messaging-sw.js", {
-        type: "module",
-      })
-      .then((serviceWorkerRegistration) => {
-        getToken(this.msg, {
-          vapidKey: `an optional key generated on Firebase for your fcm tokens`,
-          serviceWorkerRegistration: serviceWorkerRegistration,
-        }).then((x) => {
-          console.log('my fcm token', x);
-          // This is a good place to then store it on your database for each user
-        });
-	});  
+  }
+
+  private async registerForMessages() {
+    /* Request notification permission before calling `register`, otherwise
+     * `register` holds the app unstable until the user answers. */
+    if (
+      Notification.permission === "default" &&
+      await Notification.requestPermission() !== "granted"
+    ) {
+      return;
     }
-    this.message$ = new Observable((sub) => onMessage(this.msg, (msg) =>     
-      sub.next(msg))).pipe(
-	    tap((msg) => {
-	      console.log("My Firebase Cloud Message", msg);
-	    })
+
+    // Register the service worker.
+    const serviceWorkerRegistration = await navigator.serviceWorker
+      .register("/assets/firebase-messaging-sw.js", { type: "module" });
+
+    /* Run `register` inside an injection context. Outside one AngularFire cannot wrap it, and
+     * warns. See `zones.md` for what wrapping adds. */
+    runInInjectionContext(this.injector, () =>
+      register(this.msg, {
+        vapidKey: `an optional public VAPID key you generate for your Firebase project`,
+        serviceWorkerRegistration,
+      }).catch((error) => console.error("could not register for messages", error))
     );
-    }
-  deleteToken(){
-    // We can also delete fcm tokens, make sure to also update this on your firestore db if you are storing them as well
-    await deleteToken(this.msg);
   }
+
+  // Called from your app, for example when a user turns notifications off.
+  async unregister() {
+    // This calls the imported unregister, not this method. Class methods are not in lexical scope.
+    await unregister(this.msg);
+  }
+}
 ```
 
 # Testing and Sending Notifications
 
 Firebase will allow you to send a test notification under Engage > Messaging > New Campaign > Notifications. Here you can click send a test message. Additionally, you can send them programmatically through Firebase cloud functions. 
 
-Here is a barebones Node example:
+Here is a barebones Node example. Its `token` field still accepts a Firebase Installation ID during the migration, so it works whether you registered with `getToken` or with `register`. Firebase's [Admin SDK send guide](https://firebase.google.com/docs/cloud-messaging/send/admin-sdk) documents a dedicated `fid` field to move to.
 
-```
+```ts
 export const sendTestMessage = onRequest(async (_, res) => {
   try {
     const message = {
@@ -147,7 +177,7 @@ export const sendTestMessage = onRequest(async (_, res) => {
 
 Here is a Node example that listens for a new comment on a collection, then sends a notification, and also adds it to a cache on Firebase so users can click through them.
 
-```
+```ts
 exports.onPostReply =
   onDocumentCreated("comments/{commentId}", async (event) => {
     if (!event) throw new Error("No event found for document creation");
@@ -222,4 +252,5 @@ async function createNotificationAndCache(
     firestore.collection("notificationCache").add(notificationCacheValue));
 
   await Promise.all(promises);
-}  ```
+} 
+```

package/docs/performance.md

@@ -12,14 +12,12 @@ Firebase Performance Monitoring is a service that helps you to gain insight into
 
 ## Dependency Injection
 
-As a prerequisite, ensure that `AngularFire` has been added to your project via
-```bash
-ng add @angular/fire
-```
+As a prerequisite, ensure that `AngularFire` has been added to your project as described in the [Quickstart](./install-and-setup.md).
 
 Provide a Performance instance in the application's `app.config.ts`:
 
 ```ts
+import { ApplicationConfig } from '@angular/core';
 import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
 import { providePerformance, getPerformance } from '@angular/fire/performance';
 
@@ -30,7 +28,7 @@ export const appConfig: ApplicationConfig = {
     ...
   ],
   ...
-})
+}
 ```
 
 Next inject `Performance` into your component:

package/docs/remote-config.md

@@ -12,14 +12,12 @@ Firebase Remote Config is a cloud service that lets you change the behavior and
 
 ## Dependency Injection
 
-As a prerequisite, ensure that `AngularFire` has been added to your project via
-```bash
-ng add @angular/fire
-```
+As a prerequisite, ensure that `AngularFire` has been added to your project as described in the [Quickstart](./install-and-setup.md).
 
 Provide a Remote Config instance in the application's `app.config.ts`:
 
 ```ts
+import { ApplicationConfig } from '@angular/core';
 import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
 import { provideRemoteConfig, getRemoteConfig } from '@angular/fire/remote-config';
 
@@ -30,7 +28,7 @@ export const appConfig: ApplicationConfig = {
     ...
   ],
   ...
-})
+}
 ```
 
 Next inject `RemoteConfig` into your component:

package/docs/storage.md

@@ -14,14 +14,12 @@ Cloud Storage allows developers to upload and share user generated content such
 
 AngularFire allows you to work with Firebase Storage via Angular's Dependency Injection.
 
-As a prerequisite, ensure that `AngularFire` has been added to your project via
-```bash
-ng add @angular/fire
-```
+As a prerequisite, ensure that `AngularFire` has been added to your project as described in the [Quickstart](./install-and-setup.md).
 
 Provide a Cloud Storage instance in the application's `app.config.ts`:
 
 ```ts
+import { ApplicationConfig } from '@angular/core';
 import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
 import { provideStorage, getStorage } from '@angular/fire/storage';
 
@@ -32,7 +30,7 @@ export const appConfig: ApplicationConfig = {
     ...
   ],
   ...
-})
+}
 ```
 
 Next inject `Storage` into your component:

package/docs/version-21-upgrade.md

@@ -0,0 +1,90 @@
+# Upgrading to the AngularFire 21 Release Candidate
+
+AngularFire 21 targets **Angular 21** and the **Firebase JS SDK v12**. Most of the upgrade is handled for you by `ng update`.
+
+## Run the update
+
+The release candidate is published under the `next` tag. From an app on Angular 20 and AngularFire 20, run:
+
+```bash
+ng update @angular/core@21 @angular/cli@21 @angular/fire@next
+```
+
+`ng update` writes the range `^21.0.0-rc.1` into your `package.json`. That range also matches canary releases, and npm currently installs one of them, such as `21.0.0-rc.1-canary.95b3de1`, instead of the release candidate. To install the release candidate itself, and stop npm from picking a canary release on a later install, change the entry to the exact version `21.0.0-rc.1` by running:
+
+```bash
+npm install --save-exact @angular/fire@next
+```
+
+The AngularFire update runs a migration that:
+
+- **Aligns your `firebase` dependency to `^12.18.0`.** AngularFire 21 requires Firebase JS SDK 12, at 12.18 or later. If your app requested an older `firebase`, whether that is 11 or an earlier 12, npm would install both that copy and the one AngularFire needs side by side, and the two copies reject each other's objects at runtime. The migration updates the dependency and reinstalls so you end up with a single copy. Verify with `npm ls firebase`.
+- **Rewrites Vertex AI imports to AI Logic** (see below).
+
+## Vertex AI is now Firebase AI Logic
+
+The Vertex AI module has been renamed to Firebase AI Logic. The `@angular/fire/vertexai` entry point (and the older `@angular/fire/vertexai-preview`) are removed in favor of `@angular/fire/ai`:
+
+| Before (`@angular/fire/vertexai`) | After (`@angular/fire/ai`) |
+|---|---|
+| `getVertexAI(app?, { location? })` | `getAI(app, { backend: new AgentPlatformBackend(location?) })` |
+| `provideVertexAI` | `provideAI` |
+| `VertexAI` | `AI` |
+| `VertexAIError` | `AIError` |
+| `VertexAIErrorCode` | `AIErrorCode` |
+| `VertexAIModel` | `AIModel` |
+| `VertexAIInstances` | `AIInstances` |
+| `vertexAIInstance$` | `AIInstance$` |
+| `VertexAIModule` | `AIModule` |
+
+### `getVertexAI` is not a plain rename
+
+`getAI` already existed alongside it, and a plain `getAI()` call talks to the Gemini Developer API backend, not to the Agent Platform Gemini API (formerly Vertex AI). The equivalent of `getVertexAI()` is `getAI(app, { backend: new AgentPlatformBackend() })`, which is what the migration writes, so your app keeps calling the backend it was configured, enabled, and billed for. A `location` option moves into the `AgentPlatformBackend` constructor.
+
+### The default region changes
+
+`getVertexAI()` with no `location` resolved to `us-central1`. `AgentPlatformBackend` with no argument resolves to `global`. Firebase suggests `global` when your model supports it, and the Gemini 3.x models are only available there, which is why the migration writes it. To keep the region you had instead, write `new AgentPlatformBackend('us-central1')`.
+
+Review this before deploying if your project has a data residency requirement.
+
+#### Which calls move, and what the migration tells you
+
+- A call that passed a non-empty `location` string keeps it, so its region does not move.
+- A call that passed no `location`, or an empty one, moves to `global`. `getVertexAI` treated an empty value as `us-central1`, and `AgentPlatformBackend` treats it as `global`. The migration drops the empty value rather than writing it through, and warns.
+- A call whose `location` is an expression the migration cannot read gets its own warning, because only your runtime knows whether that value is empty.
+- A call whose options the migration cannot rewrite at all, such as a quoted `{ 'location': ... }` key, is left as written and warned about separately. Its import still moves, so it stops compiling until you migrate it by hand.
+
+Each of those warnings is emitted once per file, so a file that has both a moved region and an unreadable `location` produces two.
+
+#### If your app uses the Live API, do not stay on `global`
+
+Firebase does not support the `global` location for the Live API models, so `getLiveGenerativeModel` and `startAudioConversation` stop working there. When the migration sees either of them anywhere in your workspace it says so in the region warning. Pass `'us-central1'`, or another supported location, to `AgentPlatformBackend`.
+
+### What the migration rewrites for you
+
+The AngularFire update rewrites these imports and identifiers for you and logs every `getVertexAI` call it rewrites. `getGenerativeModel` keeps its name.
+
+Imports straight from the Firebase SDK (`firebase/vertexai`, gone in SDK 12) are rewritten to `firebase/ai` under the same rules. The rewrite parses your sources with the `typescript` package (an optional peer dependency of `@angular/fire`). Every Angular workspace already has it, but if the migration warns that it could not be resolved, install `typescript` and re-run. See [ai.md](./ai.md) for current usage.
+
+### What the migration will not rewrite
+
+Code the migration cannot rewrite safely is left in place with a warning. The import path itself still moves to the new entry point, so the leftover code fails to compile there. Nothing changes backends silently. It plays safe like this in four situations:
+
+- **Options it cannot read:** when the `getVertexAI` call's options are not a literal `{ location }` object, or that literal references other symbols the migration is also rewriting.
+- **The function used as a value:** when `getVertexAI` is stored or passed around rather than called directly.
+- **Name collisions:** when a local declaration in the file reuses an imported symbol's name, or the file already gets `getAI` or `AgentPlatformBackend` from a source other than AI Logic.
+- **Wildcard re-exports:** when a file has `export * from '@angular/fire/vertexai'`, that line stays as written, because rewriting it would silently rename your re-exported public symbols. Replace it with named re-exports by hand.
+
+A file where a named `getVertexAI` import is used in a way that cannot be rewritten keeps every use of its named `getVertexAI` imports in place (namespace-style `ns.getVertexAI(...)` calls are judged per call), and each skipped call is logged.
+
+### Removed symbols
+
+Two symbols were removed rather than renamed. The migration leaves their imports in place, which breaks loudly, and warns with guidance:
+
+- `VertexAIOptions`: the new `AIOptions` takes a `backend` instead of a `location`, so rebuild the options by hand using the table above.
+- `getImagenModel`: Firebase shut the Imagen models down in August 2026 and removed the API in firebase 12.18 (`@firebase/ai` 2.15), so move image generation to the Gemini image models through [`getGenerativeModel`](https://firebase.google.com/docs/ai-logic/generate-images-gemini).
+
+## Other notes
+
+- **Angular 21.2 is required.** AngularFire 21 peers `@angular/* ^21.2.0` and does not support Angular 22 (a future AngularFire 22 will).
+- The obsolete `@angular/platform-browser-dynamic` peer dependency was removed. No action is needed.

package/docs/zones.md

@@ -18,6 +18,50 @@ When an application is unstable change-detection, two-way binding, and rehydrati
 
 There are a number of situations where AngularFire's Zone wrapping is inconsequential such adding/deleting/updating a document in response to user-input, signing a user in, calling a Cloud Function, etc. So long as no long-lived side-effects are kicked off, your application should be ok. Most Promise based APIs are fairly safe without zone wrapping. 
 
+## Keeping calls inside an injection context
+
+A common way to trip the warning is calling an AngularFire API from inside an asynchronous callback, for example building a Firestore query inside a `switchMap` on the signed-in user. The surrounding service is created inside an injection context, but the callback runs *later*, after that context is gone, so AngularFire can no longer wrap the call.
+
+Capture an `EnvironmentInjector` while the context is still active (any field initializer or constructor), then re-establish it inside the callback with [`runInInjectionContext`](https://angular.dev/api/core/runInInjectionContext):
+
+```ts
+private readonly injector = inject(EnvironmentInjector);
+
+readonly todos$ = this.user$.pipe(
+  switchMap((user) =>
+    runInInjectionContext(this.injector, () =>
+      collectionData(collection(this.firestore, `users/${user.uid}/todos`)),
+    ),
+  ),
+);
+```
+
+Inside `runInInjectionContext`, AngularFire can wrap the call again, so the SSR/change-detection guarantees are restored and the warning goes away.
+
+If a call doesn't depend on the async value, prefer hoisting it out of the callback entirely and running it once where the injection context is still active:
+
+```ts
+// Built once where the context is live, then reused, so no wrapping is needed:
+private readonly items$ = collectionData(collection(this.firestore, "items"));
+
+readonly refreshed$ = this.refresh$.pipe(switchMap(() => this.items$));
+```
+
+Reach for `runInInjectionContext` only when the call genuinely must run inside the callback, as the per-user query above does (it needs the signed-in user's `uid`).
+
+### Why the injection context is required
+
+AngularFire cannot create an injection context, only borrow the one you are already in.
+
+When you call a wrapped API, the first thing AngularFire does is ask Angular for three things with `inject()`: its own scheduler service, Angular's `PendingTasks` register, and an `EnvironmentInjector`. `inject()` only works inside an injection context, so outside of one the first of them throws and the rest are never reached. AngularFire catches that, warns while in dev-mode as described under Logging below, and calls the Firebase API directly with nothing added.
+
+That division is worth knowing, because it explains what you are and are not responsible for:
+
+* **You** supply the context at the call site, from a field initializer, a constructor, or an explicit `runInInjectionContext`.
+* **AngularFire** re-enters the environment injector inside a callback you hand to the call itself, which is why you never wrap an `onSnapshot` handler yourself. That reaches anything provided at the application level, but not providers declared on a component, and it does not extend to subscribers of a returned Observable, which is what the `switchMap` and `runInInjectionContext` example above is for.
+
+What you lose depends on the call. A call that does asynchronous work, such as `onSnapshot`, `getDoc` or `collectionData`, is normally added to Angular's `PendingTasks` register, which is what server-side rendering waits on before it serializes the page. Called outside a context, it never is. A call that returns immediately, such as `getFirestore`, was never registered anyway, so it loses only the zone handling.
+
 ## Logging
 
 You may see a log warning, `Calling Firebase APIs outside of an Injection context may destabilize your application leading to subtle change-detection and hydration bugs. Find more at https://github.com/angular/angularfire/blob/main/docs/zones.md` when developing your application.
@@ -27,7 +71,7 @@ Instability can be difficult to track down. To help with debugging, AngularFire
 There are three logging levels in AngularFire:
 
 * **Silent**: when the logging level is set to silent only the above banner is displayed when AngularFire APIs are called outside of an injection context, this is the default when using Zoneless change-detection.
-* **Warn**: when the logging level is set to warn, only blocking reads, long-lived tasks, and APIs with high risk of destabilizing your application are called, this is the default when using ZoneJS.
+* **Warn**: when the logging level is set to warn, only blocking reads, long-lived tasks, and APIs with high risk of destabilizing your application are logged, this is the default when using ZoneJS.
 * **Verbose**: when the logging level is set to verbose, all AngularFire APIs called outside of an injection context are logged—helping you track down APIs that may be destabilizing your application
 
 You can change the log-level like so:

package/fesm2022/angular-fire-ai.mjs

@@ -6,7 +6,7 @@ import { InjectionToken, Optional, NgModule, makeEnvironmentProviders, NgZone, I
 import { FirebaseApp, FirebaseApps } from '@angular/fire/app';
 import { AppCheckInstances } from '@angular/fire/app-check';
 import { registerVersion } from 'firebase/app';
-import { getAI as getAI$1, getGenerativeModel as getGenerativeModel$1, getImagenModel as getImagenModel$1, getVertexAI as getVertexAI$1 } from 'firebase/ai';
+import { getAI as getAI$1, getGenerativeModel as getGenerativeModel$1, getLiveGenerativeModel as getLiveGenerativeModel$1, startAudioConversation as startAudioConversation$1 } from 'firebase/ai';
 export * from 'firebase/ai';
 
 class AI {
@@ -51,14 +51,14 @@ class AIModule {
     constructor() {
         registerVersion('angularfire', VERSION.full, 'ai');
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.0.0", ngImport: i0, type: AIModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
-    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "20.0.0", ngImport: i0, type: AIModule });
-    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "20.0.0", ngImport: i0, type: AIModule, providers: [
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: AIModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
+    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "21.2.22", ngImport: i0, type: AIModule });
+    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: AIModule, providers: [
             DEFAULT_AI_INSTANCE_PROVIDER,
             AI_INSTANCES_PROVIDER,
         ] });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.0.0", ngImport: i0, type: AIModule, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: AIModule, decorators: [{
             type: NgModule,
             args: [{
                     providers: [
@@ -91,12 +91,12 @@ function provideAI(fn, ...deps) {
 // DO NOT MODIFY, this file is autogenerated by tools/build.ts
 const getAI = _zoneWrap(getAI$1, true);
 const getGenerativeModel = _zoneWrap(getGenerativeModel$1, true);
-const getImagenModel = _zoneWrap(getImagenModel$1, true);
-const getVertexAI = _zoneWrap(getVertexAI$1, true);
+const getLiveGenerativeModel = _zoneWrap(getLiveGenerativeModel$1, true);
+const startAudioConversation = _zoneWrap(startAudioConversation$1, true);
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { AI, AIInstance$, AIInstances, AIModule, getAI, getGenerativeModel, getImagenModel, getVertexAI, provideAI };
+export { AI, AIInstance$, AIInstances, AIModule, getAI, getGenerativeModel, getLiveGenerativeModel, provideAI, startAudioConversation };
 //# sourceMappingURL=angular-fire-ai.mjs.map