feat(@angular/ssr): export AngularAppEngine as public API

Added `AngularAppEngine` to the public API of `@angular/ssr`, allowing users to access it directly for enhanced server-side rendering functionality.

Author: alan-agius4

goldens/public-api/angular/ssr/index.api.md

@@ -4,6 +4,17 @@
 
 ```ts
 
+// @public
+export interface AngularServerAppManager {
+    render(request: Request, requestContext?: unknown): Promise<Response | null>;
+}
+
+// @public
+export function destroyAngularAppEngine(): void;
+
+// @public
+export function getOrCreateAngularAppEngine(): AngularServerAppManager;
+
 // (No @packageDocumentation comment for this package)
 
 ```

packages/angular/ssr/private_export.ts

@@ -17,4 +17,6 @@ export {
   setAngularAppEngineManifest as ɵsetAngularAppEngineManifest,
 } from './src/manifest';
 
+export { AngularAppEngine as ɵAngularAppEngine } from './src/app-engine';
+
 export { InlineCriticalCssProcessor as ɵInlineCriticalCssProcessor } from './src/utils/inline-critical-css';

packages/angular/ssr/public_api.ts

@@ -7,3 +7,9 @@
  */
 
 export * from './private_export';
+
+export {
+  type AngularServerAppManager,
+  getOrCreateAngularAppEngine,
+  destroyAngularAppEngine,
+} from './src/app-engine';

packages/angular/ssr/src/app-engine.ts

@@ -10,20 +10,45 @@ import { Hooks } from './hooks';
 import { getPotentialLocaleIdFromUrl } from './i18n';
 import { EntryPointExports, getAngularAppEngineManifest } from './manifest';
 
+/**
+ * Angular server application engine.
+ * Manages Angular server applications (including localized ones) and handles rendering requests.
+
+ * @developerPreview
+ */
+export interface AngularServerAppManager {
+  /**
+   * Renders a response for the given HTTP request using the server application.
+   *
+   * This method processes the request, determines the appropriate route and rendering context,
+   * and returns an HTTP response.
+   *
+   * If the request URL appears to be for a file (excluding `/index.html`), the method returns `null`.
+   * A request to `https://www.example.com/page/index.html` will render the Angular route
+   * corresponding to `https://www.example.com/page`.
+   *
+   * @param request - The incoming HTTP request object to be rendered.
+   * @param requestContext - Optional additional context for the request, such as metadata.
+   * @returns A promise that resolves to a Response object, or `null` if the request URL represents a file (e.g., `./logo.png`)
+   * rather than an application route.
+   */
+  render(request: Request, requestContext?: unknown): Promise<Response | null>;
+}
+
 /**
  * Angular server application engine.
  * Manages Angular server applications (including localized ones), handles rendering requests,
  * and optionally transforms index HTML before rendering.
  */
-export class AngularAppEngine {
+export class AngularAppEngine implements AngularServerAppManager {
   /**
    * Hooks for extending or modifying the behavior of the server application.
    * These hooks are used by the Angular CLI when running the development server and
    * provide extensibility points for the application lifecycle.
    *
-   * @internal
+   * @private
    */
-  static hooks = new Hooks();
+  static ɵhooks = new Hooks();
 
   /**
    * Provides access to the hooks for extending or modifying the server application's behavior.
@@ -32,7 +57,7 @@ export class AngularAppEngine {
    * @internal
    */
   get hooks(): Hooks {
-    return AngularAppEngine.hooks;
+    return AngularAppEngine.ɵhooks;
   }
 
   /**
@@ -92,3 +117,32 @@ export class AngularAppEngine {
     return entryPoints.get(potentialLocale);
   }
 }
+
+let angularAppEngine: AngularAppEngine | undefined;
+
+/**
+ * Retrieves an existing `AngularAppEngine` instance or creates a new one if none exists.
+ *
+ * This method ensures that only a single instance of `AngularAppEngine` is created and reused across
+ * the application lifecycle, providing efficient resource management. If the instance does not exist,
+ * it will be instantiated upon the first call.
+ *
+ * @developerPreview
+ * @returns The existing or newly created instance of `AngularAppEngine`.
+ */
+export function getOrCreateAngularAppEngine(): AngularServerAppManager {
+  return (angularAppEngine ??= new AngularAppEngine());
+}
+
+/**
+ * Destroys the current `AngularAppEngine` instance, releasing any associated resources.
+ *
+ * This method resets the reference to the `AngularAppEngine` instance to `undefined`, allowing
+ * a new instance to be created on the next call to `getOrCreateAngularAppEngine()`. It is typically
+ * used when reinitializing the server environment or refreshing the application state is necessary.
+ *
+ * @developerPreview
+ */
+export function destroyAngularAppEngine(): void {
+  angularAppEngine = undefined;
+}