build: require firebase ^12.18.0 and wrap the functions it adds

[armando-navarro]

Checklist

• Issue number for this PR: Raise the firebase version AngularFire is built against, so functions added since 12.4.0 are wrapped #3756 (required)
• Docs included?: yes (docs/version-21-upgrade.md, docs/messaging.md)
• Test units included?: no new ones, two existing ones rewritten, see Testing below
• In a clean directory, yarn install, yarn test run successfully? yes, via the npm equivalents

Description

tools/build.ts writes src/<module>/firebase.ts from the type declarations of whatever firebase is installed, so which functions @angular/fire wraps is decided by the version the build resolves rather than by a list anyone maintains. This raises that version, and regenerates. #3756 has the background.

Three things follow from the way the generator works:

• The version the build resolves has been 12.4.0 while npm latest reached 12.18.0.
• Everything Firebase added in between still reaches callers through the export * line, but arrives with none of the wrapper's behavior and nothing saying it is different.
• The range the repository builds against, the range the published package declares and the schematics constant all have to move together, or alignFirebaseVersion starts writing a range the library does not install against.

What regenerating changes

• src/messaging/firebase.ts is the only generated file that moves. It gains onRegistered, onUnregistered, register and unregister.
• Nothing else changes, because build: classify the firebase symbols a version raise would newly wrap #3759 already classified every other symbol the raise makes visible.
• Those entries keep their symbols out of the generated files while the export * line continues to carry them to callers.

What comes out

• getImagenModel carried an override entry so the generator would not emit a named import for a symbol firebase deleted in 12.18.0 (@angular/fire/ai fails to build against firebase 12.18, which removed getImagenModel #3749, fixed by fix(ai): drop the getImagenModel wrapper, removed in firebase 12.18 #3750).
• At this version the generator cannot see the symbol at all, so the entry has nothing left to do and goes.
• That empties overridesFirebaseDoesNotDeclare, which stays in place as the list the next unclassified name goes into.

What this means for someone upgrading

• @angular/fire declares firebase as a regular dependency rather than a peer, so a workspace holding an older firebase that upgrades @angular/fire without running a schematic now resolves two copies instead of one, and the two reject each other's objects at runtime. Measured under Testing rather than assumed.
• alignFirebaseVersion rewrites the declared range for anyone who runs ng add or ng update, and it picks up the new range with no further change.
• ng add should warn when the workspace has more than one version of firebase installed #3754 covers telling the people who run neither.

Specs

• Two alignFirebaseVersion specs used ^12.6.0 to stand for a range a workspace declares that is already inside what the library requires.
• ^12.6.0 stops being inside that range at 12.18.0, so both specs would have started asserting the opposite of what they say.
• They now derive that value from firebaseVersionRange, so the next raise cannot leave them wrong.

Docs

• docs/messaging.md wrote the firebase version into two gstatic service worker URLs, which is only correct on the day it is written. It now uses a placeholder, matching docs/compat/messaging/messaging.md.
• docs/version-21-upgrade.md names the new range, and no longer implies that only a firebase 11 workspace ends up with two copies.

Testing

npm run build && npm run build:jasmine && npm run test:node

• 227 specs, 0 failures.
• npx ng lint passes.
• The karma suite passes against the emulators: 107 executed, 48 skipped, 0 failures.

Two results are worth stating separately, because neither is visible in the diff.

The override entries are doing the work, not the version

• Every symbol build: classify the firebase symbols a version raise would newly wrap #3759 marked unwrapped is absent from every generated file.
• Each of those five is a live function in the installed firebase 12.18.0, so their absence is those entries working rather than the version simply not having them.
• getImagenModel is undefined there, which is why its entry could go.

The duplicate copy was measured, not assumed

A fresh ng new app, firebase set to 12.10.0, this build of @angular/fire installed, no schematic run:

├─┬ @angular/fire@21.0.0-rc.0
│ ├── firebase@12.18.0
│ └─┬ rxfire@6.2.0
│   └── firebase@12.10.0 deduped
└── firebase@12.10.0

The split runs through the library's own dependencies: @angular/fire gets 12.18.0 while rxfire, which @angular/fire depends on, gets the app's 12.10.0. The same app with no firebase of its own resolves a single 12.18.0 for everything.

One judgment call I would particularly like a second opinion on: register is wrapped with blockUntilFirst at its default, which means a call made before notification permission is granted holds the application unstable while the browser prompt is open. getToken has done the same for years, and setting false would drop zone and injection-context re-entry from the returned promise rather than just the pending task, so I left it alone. If you would rather that not ship, say so and I will take it out of this PR.

Fixes #3756

[tyler-reitz]

Approving. On your register question: leave it. The reason is stronger than "getToken has done the same for years": register and getToken have identical permission preambles in @firebase/messaging 12.18.0, both await Notification.requestPermission() when permission is default, then throw permission-blocked. It isn't a new hazard, it's the same one, now on the API that replaces the one already carrying it. Your reasoning about the alternative holds too: at blockUntilFirst: false a promise falls to zones.ts:153-161 and comes back bare, losing the runInInjectionContext re-entry that 169-180 gives it. There's no "re-enter but don't block" setting.

Ran the rest. npm ci at 12.18.0 then npm run generate reproduces the committed files byte for byte, so messaging really is the only one that moves. 227 specs, 0 failures. Forcing alreadyCompatible = false turns both rewritten specs red, so they're live; simulating the next raise to ^12.20.0 leaves them passing and trips only the pre-existing src/package.json drift guard, which is the right thing to fire.

One follow-up, not for this PR: 12.18.0 deprecates both getToken and deleteToken in favour of register/onRegistered/onUnregistered, and docs/messaging.md:81 still imports both. Worth an issue.

Also, this branch carries #3759's three commits, so it'll want a rebase once that squash-merges.

[armando-navarro]

On the docs point, I have updated the docs here rather than filing it, since the PR template asks whether docs are included and this is the change that makes the replacement calls available. Pushed as a follow-up commit.

Two things I found while writing it that are worth knowing:

• onRegistered has to be listening before register runs. register throws No onRegistered callback handler was provided or registered otherwise, so the old example could not simply have its imports swapped. The new section says so before the sample.
• Firebase's Admin SDK send guide says the token field still accepts an installation ID during the migration, so the guide's Node example keeps working unchanged. It recommends a dedicated fid field, which I deliberately did not put in the sample because firebase-admin 13.5.0 does not declare one.