fix(@angular/build): correct misleading error message for top-level await

[maruthang]

PR Checklist

• The commit message follows our guidelines: https://github.com/angular/angular-cli/blob/main/CONTRIBUTING.md#-commit-message-guidelines
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

PR Type

• Bugfix

What is the current behavior?

When using top-level await in an Angular app with Zone.js, esbuild reports "Top-level await is not available in the configured target environment" with a list of browser versions. This is misleading — all modern browsers support top-level await. The real issue is that Angular disables native async/await when Zone.js is in use (since Zone.js can't intercept it), and top-level await can't be downleveled.

Issue Number: #28904

What is the new behavior?

When the top-level await error occurs and Zone.js is active, the error is augmented with explanatory notes:

• "Top-level await is not supported in applications that use Zone.js. Consider removing Zone.js or moving this code into an async function."
• A link to the Angular zoneless documentation at https://angular.dev/guide/zoneless

Does this PR introduce a breaking change?

• Yes
• No

[gemini-code-assist]

Code Review

This pull request enhances the Angular build process by providing a more descriptive error message when top-level await is used in applications that still utilize Zone.js. The build logic now intercepts specific esbuild errors to add helpful notes and documentation links, and new behavior tests have been added to verify these changes. A review comment suggests extracting the hardcoded error string into a constant to improve maintainability.

[gemini-code-assist]

To improve maintainability and readability, it's a good practice to extract magic strings into constants. The error message from esbuild could change in the future, and having it as a constant makes it easier to update.

    if (!isZonelessApp(options.polyfills)) {
      const TLA_ERROR_MESSAGE =
        'Top-level await is not available in the configured target environment';
      for (const error of bundlingResult.errors) {
        if (error.text?.startsWith(TLA_ERROR_MESSAGE)) {
          error.notes = [
            {
              text:
                'Top-level await is not supported in applications that use Zone.js. ' +
                'Consider removing Zone.js or moving this code into an async function.',
              location: null,
            },
            {
              text: 'For more information about zoneless Angular applications, visit: https://angular.dev/guide/zoneless',
              location: null,
            },
            ...(error.notes ?? []),
          ];
        }
      }
    }