@real-router/angular 0.8.1 → 0.10.0

package/src/internal/install.ts

@@ -0,0 +1,77 @@
+import { ApplicationRef, DestroyRef, inject } from "@angular/core";
+
+import { createScrollRestoration, createViewTransitions } from "../dom-utils";
+import { ROUTER } from "../providers";
+
+import type { ScrollRestorationOptions } from "../dom-utils";
+
+/**
+ * Shared installation helpers for `provideRealRouter` and
+ * `provideRealRouterFactory`. Must be called inside the body of a
+ * `provideEnvironmentInitializer(() => { ... })` callback so the active
+ * injection context resolves `ROUTER`, `ApplicationRef`, and `DestroyRef`.
+ *
+ * Closes review-2026-05-10 §8.1 MED — eliminates duplicate wiring between
+ * `providers.ts` and `providersFactory.ts` (high drift risk noted in the
+ * audit: the comment blocks were identical down to the punctuation).
+ */
+
+export function installScrollRestoration(
+  options: ScrollRestorationOptions,
+): void {
+  const router = inject(ROUTER);
+  const sr = createScrollRestoration(router, options);
+
+  inject(DestroyRef).onDestroy(() => {
+    sr.destroy();
+  });
+}
+
+export function installViewTransitions(): void {
+  const router = inject(ROUTER);
+
+  // Feature-detect `document.startViewTransition` once at install time. The
+  // `appRef.tick()` listener exists ONLY to feed Angular's zoneless CD into
+  // the VT utility's `setTimeout(0)`-driven snapshot capture (see comment
+  // below). When `startViewTransition` is unavailable (Firefox as of 2026-04,
+  // SSR, older browsers), `createViewTransitions` short-circuits to its
+  // frozen NOOP_INSTANCE — no leave subscriber registered, no
+  // `setTimeout(0)` invariant to satisfy. Installing the per-navigation
+  // tick listener anyway would force a synchronous CD pass on every
+  // navigation with zero benefit, doubling CD work in zoneless apps.
+  // Closes review-2026-05-10 §8.2 MED (view-transitions hot path).
+  const vtAvailable =
+    typeof document !== "undefined" &&
+    typeof document.startViewTransition === "function";
+
+  let offTick: (() => void) | undefined;
+
+  if (vtAvailable) {
+    // Force synchronous change detection on every transition success BEFORE
+    // the VT utility resolves its deferred. The utility uses `setTimeout(0)`
+    // to release the new-snapshot capture, which is load-bearing because
+    // Chromium blocks rAF callbacks while VT sits in the
+    // `update-callback-called` phase. Angular's zoneless CD is rAF-driven by
+    // default — without this synchronous tick the new DOM is not committed
+    // when the browser captures the new snapshot, so old and new snapshots
+    // end up identical and animations finish in ~0 ms with no visible work
+    // (the inner-route `products.list ↔ products.detail` morph in the
+    // example app was the canary).
+    //
+    // Subscribers fire in registration order; this one runs BEFORE
+    // `createViewTransitions` registers its own subscriber, guaranteeing CD
+    // completes first.
+    const appRef = inject(ApplicationRef);
+
+    offTick = router.subscribe(() => {
+      appRef.tick();
+    });
+  }
+
+  const vt = createViewTransitions(router);
+
+  inject(DestroyRef).onDestroy(() => {
+    offTick?.();
+    vt.destroy();
+  });
+}

package/src/internal/subscribeSourceToSignal.ts

@@ -0,0 +1,48 @@
+import type { RouterSource } from "@real-router/sources";
+
+/**
+ * Subscribe a `RouterSource<T>` to a write-callback and return a cleanup
+ * function. The shape is the per-effect-run pattern that `RealLink`,
+ * `RealLinkActive`, and `RouteView` all share inside their constructor
+ * `effect(...)` (review-2026-05-16 §8a MEDIUM — identical 8-line block
+ * repeated in 3 directives):
+ *
+ *   1. Read initial snapshot and apply it via `onSnapshot(snap)`.
+ *   2. Subscribe — every subsequent emission calls `onSnapshot(snap)` again.
+ *   3. Return a cleanup that unsubscribes and destroys the source. For
+ *      cached factories from `@real-router/sources` (`createActiveRouteSource`,
+ *      `createRouteNodeSource`, `getTransitionSource`, `getErrorSource`,
+ *      `createDismissableError`) `destroy()` is a no-op on the shared
+ *      wrapper, so this helper is safe to invoke from rapid effect re-runs
+ *      under signal-input changes.
+ *
+ * Callers pass the result to `onCleanup(...)` from Angular's `effect()`.
+ *
+ * @example
+ * ```ts
+ * effect((onCleanup) => {
+ *   const source = createActiveRouteSource(router, routeName(), params());
+ *   onCleanup(
+ *     subscribeSourceToSignal(source, (snap) => {
+ *       this.isActive.set(snap);
+ *       this.updateDom();
+ *     }),
+ *   );
+ * });
+ * ```
+ */
+export function subscribeSourceToSignal<T>(
+  source: RouterSource<T>,
+  onSnapshot: (snapshot: T) => void,
+): () => void {
+  onSnapshot(source.getSnapshot());
+
+  const unsub = source.subscribe(() => {
+    onSnapshot(source.getSnapshot());
+  });
+
+  return () => {
+    unsub();
+    source.destroy();
+  };
+}

package/src/providers.ts

@@ -1,8 +1,5 @@
 import {
-  ApplicationRef,
-  DestroyRef,
   InjectionToken,
-  inject,
   makeEnvironmentProviders,
   provideEnvironmentInitializer,
   type EnvironmentProviders,
@@ -10,7 +7,10 @@ import {
 import { getNavigator, type Router, type Navigator } from "@real-router/core";
 import { createRouteSource } from "@real-router/sources";
 
-import { createScrollRestoration, createViewTransitions } from "./dom-utils";
+import {
+  installScrollRestoration,
+  installViewTransitions,
+} from "./internal/install";
 import { sourceToSignal } from "./sourceToSignal";
 
 import type { ScrollRestorationOptions } from "./dom-utils";
@@ -33,6 +33,11 @@ export function provideRealRouter(
 ): EnvironmentProviders {
   const navigator = getNavigator(router);
 
+  // `Parameters<typeof makeEnvironmentProviders>[0]` is the actual union
+  // `(Provider | EnvironmentProviders | EnvironmentProviders[])[]` —
+  // `provideEnvironmentInitializer()` returns `EnvironmentProviders`, so the
+  // narrower `Provider[]` would force a cast at every push (review §8a — the
+  // proposed Provider[] swap was retracted after discovering this).
   const providers: Parameters<typeof makeEnvironmentProviders>[0] = [
     { provide: ROUTER, useValue: router },
     { provide: NAVIGATOR, useValue: navigator },
@@ -50,45 +55,13 @@ export function provideRealRouter(
 
     providers.push(
       provideEnvironmentInitializer(() => {
-        const sr = createScrollRestoration(router, scrollOpts);
-
-        inject(DestroyRef).onDestroy(() => {
-          sr.destroy();
-        });
+        installScrollRestoration(scrollOpts);
       }),
     );
   }
 
   if (options?.viewTransitions === true) {
-    providers.push(
-      provideEnvironmentInitializer(() => {
-        const appRef = inject(ApplicationRef);
-
-        // Force synchronous change detection on every transition success
-        // BEFORE the VT utility resolves its deferred. The utility uses
-        // `setTimeout(0)` to release the new-snapshot capture, which is
-        // load-bearing because Chromium blocks rAF callbacks while VT sits
-        // in the `update-callback-called` phase. Angular's zoneless CD is
-        // rAF-driven by default — without this synchronous tick the new
-        // DOM is not committed when the browser captures the new snapshot,
-        // so old and new snapshots end up identical and animations finish
-        // in ~0 ms with no visible work (the inner-route `products.list ↔
-        // products.detail` morph in the example example was the canary).
-        // Subscribers fire in registration order; this one runs BEFORE
-        // `createViewTransitions` registers its own subscriber,
-        // guaranteeing CD completes first.
-        const offTick = router.subscribe(() => {
-          appRef.tick();
-        });
-
-        const vt = createViewTransitions(router);
-
-        inject(DestroyRef).onDestroy(() => {
-          offTick();
-          vt.destroy();
-        });
-      }),
-    );
+    providers.push(provideEnvironmentInitializer(installViewTransitions));
   }
 
   return makeEnvironmentProviders(providers);

package/src/providersFactory.ts

@@ -0,0 +1,298 @@
+import {
+  DestroyRef,
+  REQUEST,
+  TransferState,
+  inject,
+  makeEnvironmentProviders,
+  makeStateKey,
+  provideAppInitializer,
+  provideEnvironmentInitializer,
+  type EnvironmentProviders,
+} from "@angular/core";
+import {
+  getNavigator,
+  type DefaultDependencies,
+  type PluginFactory,
+  type Router,
+} from "@real-router/core";
+import { cloneRouter } from "@real-router/core/api";
+import { hydrateRouter, serializeRouterState } from "@real-router/core/utils";
+import { createRouteSource } from "@real-router/sources";
+
+import {
+  installScrollRestoration,
+  installViewTransitions,
+} from "./internal/install";
+import { NAVIGATOR, ROUTE, ROUTER } from "./providers";
+import { sourceToSignal } from "./sourceToSignal";
+
+import type { ScrollRestorationOptions } from "./dom-utils";
+import type { RouteSignals } from "./types";
+
+/**
+ * `TransferState` key carrying the SSR-resolved router state from server to
+ * client as an XSS-safe JSON string (produced by `serializeRouterState`).
+ * Populated server-side by the `provideAppInitializer` callback after
+ * `router.start()` resolves; consumed client-side after hydration. Mirrors the
+ * `<script>window.__SSR_STATE__ = …</script>` pattern used by every other
+ * adapter — Angular's idiomatic transport is `TransferState` (#599).
+ *
+ * Stored as `string`: `serializeRouterState(state)` already produces JSON;
+ * `hydrateRouter(router, json)` accepts a JSON string and parses it once
+ * internally. Storing the parsed object would force a double round-trip
+ * (TransferState wraps every value in JSON for transport).
+ *
+ * Internal implementation detail. Not re-exported.
+ */
+const ROUTER_STATE_KEY = makeStateKey<string>("@real-router/angular:ssrState");
+
+/**
+ * Factory function for deriving per-request dependencies from an SSR `Request`.
+ *
+ * - **Server:** receives the real `Request` exposed via Angular's `REQUEST` token.
+ * - **SSG:** receives a mocked `Request` injected via `platformProviders`.
+ * - **Client:** receives `null` — derive deps from `document.cookie` etc.
+ *
+ * The returned object becomes the second argument to
+ * `cloneRouter(baseRouter, deps)`. Returning `undefined` clones the router with
+ * no extra deps (cloneRouter accepts the optional 2nd argument).
+ */
+export type RequestDepsFactory<
+  TDeps extends DefaultDependencies = DefaultDependencies,
+> = (request: Request | null) => TDeps | undefined;
+
+/**
+ * Function form for conditional plugins (different sets server vs client).
+ *
+ * Use this when the plugin set must differ — typically because some plugins
+ * (e.g. `browser-plugin`, `navigation-plugin`, `hash-plugin`) touch
+ * `window.history` / `window.location` and cannot run on the server.
+ */
+export type RequestPluginsFactory<
+  TDeps extends DefaultDependencies = DefaultDependencies,
+> = (request: Request | null) => readonly PluginFactory<TDeps>[];
+
+export interface RealRouterFactoryOptions<
+  TDeps extends DefaultDependencies = DefaultDependencies,
+> {
+  /**
+   * Base router instance — created once at app bootstrap (typically inside
+   * `app.config.ts` module scope). Each request clones this router via
+   * `cloneRouter(baseRouter, deps?.(request))`, producing an isolated
+   * router with its own state, plugins, and subscriptions.
+   *
+   * **Important:** the `baseRouter` MUST NOT be started ahead of time —
+   * `provideAppInitializer` is responsible for calling `router.start(url)`
+   * inside the per-request DI scope.
+   */
+  baseRouter: Router<TDeps>;
+
+  /**
+   * Plugins applied to every per-request router clone.
+   *
+   * **Static form** — same plugins on both sides:
+   * ```ts
+   * plugins: [ssrDataPluginFactory(loaders)]
+   * ```
+   *
+   * **Function form** — conditional client vs server (recommended when any
+   * browser-only plugin is involved):
+   * ```ts
+   * plugins: (request) => request
+   *   ? [ssrDataPluginFactory(loaders)]
+   *   : [browserPluginFactory(), ssrDataPluginFactory(loaders)],
+   * ```
+   *
+   * Function form is required if the plugin list contains
+   * `browser-plugin`, `navigation-plugin`, or `hash-plugin` — those plugins
+   * read `window.history` / `window.location` and crash on the server.
+   */
+  plugins?: readonly PluginFactory<TDeps>[] | RequestPluginsFactory<TDeps>;
+
+  /**
+   * Derive request-scoped deps (e.g. `currentUser` from cookies). The result
+   * is passed to `cloneRouter(baseRouter, deps)` and merged with any deps
+   * already registered on the base router.
+   *
+   * Receives `request: Request | null`:
+   * - non-null on server (real `Request` from `@angular/ssr` runtime)
+   * - non-null on SSG (mocked `Request` via `platformProviders`)
+   * - null on client (derive deps externally — e.g. parse `document.cookie`)
+   */
+  deps?: RequestDepsFactory<TDeps>;
+
+  /** Optional scroll restoration — same semantics as `provideRealRouter`. */
+  scrollRestoration?: ScrollRestorationOptions;
+
+  /** Optional view transitions — same semantics as `provideRealRouter`. */
+  viewTransitions?: boolean;
+}
+
+/**
+ * `provideRealRouterFactory` — environment providers for SSR / SSG scenarios.
+ *
+ * Unlike `provideRealRouter(router)` (single instance via `useValue`), this
+ * factory uses `useFactory` to produce a per-request router clone:
+ *
+ * 1. Reads Angular's `REQUEST` token (`{ optional: true }`).
+ * 2. Calls `cloneRouter(baseRouter, deps?.(request))` to create a request-scoped clone.
+ * 3. Applies plugins (`plugins` array or `plugins(request)` factory).
+ * 4. Registers `provideAppInitializer` that calls `await router.start(url)`.
+ * 5. Schedules `router.dispose()` via `DestroyRef.onDestroy` — the request
+ *    Injector is destroyed after the response is sent, releasing all
+ *    subscriptions and plugins.
+ *
+ * Use cases:
+ * - Angular SSR with `@angular/ssr` (`outputMode: "server"`).
+ * - SSG build-time render via `renderApplication` + `platformProviders` `REQUEST` mock.
+ * - Multi-tenant request-scoped routing.
+ *
+ * Existing single-instance scenarios (SPA, SSG client after hydration) continue
+ * to use `provideRealRouter(router)` — both APIs ship in parallel.
+ *
+ * @param options - Factory configuration — see `RealRouterFactoryOptions`.
+ * @returns `EnvironmentProviders` to spread into `ApplicationConfig.providers`.
+ */
+export function provideRealRouterFactory<
+  TDeps extends DefaultDependencies = DefaultDependencies,
+>(options: RealRouterFactoryOptions<TDeps>): EnvironmentProviders {
+  const { baseRouter, plugins, deps, scrollRestoration, viewTransitions } =
+    options;
+
+  const providers: Parameters<typeof makeEnvironmentProviders>[0] = [
+    {
+      provide: ROUTER,
+      useFactory: (): Router => {
+        const request = inject(REQUEST, { optional: true });
+        const requestDeps = deps?.(request);
+        const router = cloneRouter(baseRouter, requestDeps);
+
+        const pluginList =
+          typeof plugins === "function" ? plugins(request) : plugins;
+
+        if (pluginList && pluginList.length > 0) {
+          // Variadic — `usePlugin` accepts `(PluginFactory<D> | false | null | undefined)[]`.
+          router.usePlugin(...pluginList);
+        }
+
+        // Per-request cleanup. The application Injector is destroyed:
+        // - On server: after `writeResponseToNodeResponse` finishes the response
+        //   (request scope ends).
+        // - On client: at `ApplicationRef.destroy` (rare in SPA, common in TestBed).
+        // - In SSG build: after each `renderApplication` resolves.
+        inject(DestroyRef).onDestroy(() => {
+          router.dispose();
+        });
+
+        return router as unknown as Router;
+      },
+    },
+    {
+      provide: NAVIGATOR,
+      useFactory: () => getNavigator(inject(ROUTER)),
+    },
+    {
+      provide: ROUTE,
+      useFactory: (): RouteSignals => {
+        const router = inject(ROUTER);
+
+        return {
+          routeState: sourceToSignal(createRouteSource(router)),
+          navigator: inject(NAVIGATOR),
+        };
+      },
+    },
+    // Async bootstrap — runs before the first component renders. Three
+    // branches based on TransferState population:
+    //
+    //   1. **Client after hydration** — server populated TransferState with
+    //      the SSR-resolved router state. Consume it via `hydrateRouter`,
+    //      which deposits the parsed state into the one-shot
+    //      `RouterInternals.hydrationState` scratchpad before invoking
+    //      `router.start(state.path)`. SSR loader plugins
+    //      (`@real-router/ssr-data-plugin`, `@real-router/rsc-server-plugin`)
+    //      read the scratchpad and skip the loader on first paint — parity
+    //      with the other 5 adapters that consume `<script>__SSR_STATE__</script>` (#596, #599).
+    //
+    //   2. **Server / SSG** — TransferState empty; run the regular
+    //      `router.start(path)`. After it resolves, write the serialized
+    //      state back into TransferState so the matching client run lands
+    //      in branch 1. Angular's `TransferState` infrastructure
+    //      (provided by `provideClientHydration()`) carries this blob to
+    //      the client as a `<script id="ng-state">` payload.
+    //
+    //   3. **Pure CSR** — TransferState empty (never populated by a server
+    //      pass), and `inject(REQUEST, { optional: true })` returns null.
+    //      Falls into the same `router.start(path)` branch as server-side
+    //      but skips the TransferState write (no client to hand off to).
+    //
+    // Errors propagate (Option A from RFC §10): the bootstrap fails and the
+    // server returns 500. Custom error pages should be wired via
+    // `RouterErrorBoundary` on subsequent renders.
+    provideAppInitializer(async () => {
+      const router = inject(ROUTER);
+      const request = inject(REQUEST, { optional: true });
+      const transferState = inject(TransferState);
+
+      const ssrJson = transferState.get(ROUTER_STATE_KEY, null);
+
+      if (ssrJson !== null) {
+        // Branch 1: client after hydration — reuse server-resolved state.
+        await hydrateRouter(router, ssrJson);
+        // One-shot semantic, parity with `delete window.__SSR_STATE__`.
+        transferState.remove(ROUTER_STATE_KEY);
+
+        return;
+      }
+
+      // Branches 2 & 3: regular start.
+      // Browser-plugin's `start` interceptor (when registered) wraps this call
+      // with location-derived path. We always pass an explicit string — the
+      // interceptor uses the explicit value because `next(path ?? location)`
+      // short-circuits when `path` is non-nullish.
+      const path = deriveStartPath(request);
+      const state = await router.start(path);
+
+      if (request !== null) {
+        // Branch 2: running inside `@angular/ssr`'s request handler — write
+        // serialized state to TransferState so the matching client run can
+        // skip the loader on first paint.
+        transferState.set(ROUTER_STATE_KEY, serializeRouterState(state));
+      }
+    }),
+  ];
+
+  if (scrollRestoration) {
+    providers.push(
+      provideEnvironmentInitializer(() => {
+        installScrollRestoration(scrollRestoration);
+      }),
+    );
+  }
+
+  if (viewTransitions === true) {
+    providers.push(provideEnvironmentInitializer(installViewTransitions));
+  }
+
+  return makeEnvironmentProviders(providers);
+}
+
+/**
+ * Derive the path passed to `router.start(path)`:
+ * - Server / SSG: `request.url` → pathname + search.
+ * - Client: `window.location` if available.
+ * - Fallback: `"/"` (only reachable in synthetic non-browser non-SSR setups).
+ */
+function deriveStartPath(request: Request | null): string {
+  if (request) {
+    const url = new URL(request.url);
+
+    return url.pathname + url.search;
+  }
+
+  if (typeof globalThis.window !== "undefined") {
+    return globalThis.location.pathname + globalThis.location.search;
+  }
+
+  return "/";
+}

package/src/sourceToSignal.ts

@@ -12,8 +12,16 @@ export function sourceToSignal<T>(source: RouterSource<T>): Signal<T> {
   });
 
   destroyRef.onDestroy(() => {
-    unsubscribe();
-    source.destroy();
+    // `try/finally` guarantees `source.destroy()` runs even if `unsubscribe`
+    // throws. Cached sources from `@real-router/sources` keep `destroy()` as
+    // a no-op (so they survive multi-consumer teardown), but non-cached
+    // sources rely on this call to release their router subscription —
+    // skipping it on an unsubscribe throw would leak the listener.
+    try {
+      unsubscribe();
+    } finally {
+      source.destroy();
+    }
   });
 
   return sig.asReadonly();

package/src/types.ts

@@ -1,8 +1,13 @@
 import type { Signal } from "@angular/core";
-import type { Navigator, Params } from "@real-router/core";
+import type { Navigator, Params, RouterError } from "@real-router/core";
 import type { RouteSnapshot } from "@real-router/sources";
 
 export interface RouteSignals<P extends Params = Params> {
   readonly routeState: Signal<RouteSnapshot<P>>;
   readonly navigator: Navigator;
 }
+
+export interface ErrorContext {
+  $implicit: RouterError;
+  resetError: () => void;
+}

package/ssr/components/ClientOnly.ts

@@ -0,0 +1,27 @@
+import { NgTemplateOutlet } from "@angular/common";
+import { afterNextRender, Component, input, signal } from "@angular/core";
+
+import type { TemplateRef } from "@angular/core";
+
+@Component({
+  selector: "client-only",
+  template: `
+    @if (mounted()) {
+      <ng-content />
+    } @else if (fallback()) {
+      <ng-container [ngTemplateOutlet]="fallback() ?? null" />
+    }
+  `,
+  imports: [NgTemplateOutlet],
+})
+export class ClientOnly {
+  readonly fallback = input<TemplateRef<unknown>>();
+
+  readonly mounted = signal(false);
+
+  constructor() {
+    afterNextRender(() => {
+      this.mounted.set(true);
+    });
+  }
+}

package/ssr/components/HttpStatusCode.ts

@@ -0,0 +1,106 @@
+import { Component, inject, input } from "@angular/core";
+
+import { HTTP_STATUS_SINK } from "../utils/createHttpStatusSink";
+
+import type { OnInit } from "@angular/core";
+
+/**
+ * Render-time HTTP status declaration. Mount inside a route component
+ * (typical use case: a glob `*` route's NotFound page) when the status is
+ * decided by the rendered tree rather than a loader.
+ *
+ * Writes `code` to the optionally injected `HTTP_STATUS_SINK` in `ngOnInit`
+ * (after the input binding has fired) and renders nothing. Without a provider
+ * registered (the standard client-side case) the component is a silent no-op
+ * — same component tree hydrates without touching the DOM or warning about
+ * mismatches.
+ *
+ * Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep
+ * working as before; this component covers render-time decisions only.
+ *
+ * Last write wins when several `<http-status-code />` instances mount in the
+ * same render pass — sink reflects the last component whose `ngOnInit` ran.
+ *
+ * ```ts
+ * // entry-server.ts
+ * import { bootstrapApplication } from "@angular/platform-browser";
+ * import {
+ *   createHttpStatusSink,
+ *   provideHttpStatusSink,
+ * } from "@real-router/angular/ssr";
+ *
+ * const sink = createHttpStatusSink();
+ * await bootstrapApplication(AppRoot, {
+ *   providers: [
+ *     provideRealRouterFactory({ ... }),
+ *     provideHttpStatusSink(sink),
+ *   ],
+ * });
+ * response.status(sink.code ?? 200).send(html);
+ * ```
+ *
+ * ```html
+ * <!-- inside not-found.component.ts template -->
+ * <http-status-code [code]="404" />
+ * ```
+ *
+ * **Per-request wiring with `AngularNodeAppEngine`:** the sink must be
+ * passed via the second arg of `handle(req, requestContext)` — Angular
+ * surfaces it through the `REQUEST_CONTEXT` token. Attaching to `req`
+ * directly does NOT work: `AngularNodeAppEngine.handle` constructs a fresh
+ * Web `Request` from the Express `IncomingMessage` and discards every
+ * custom property. See the `ssr/` example's `app.config.ts` factory for
+ * the canonical pattern (`inject(REQUEST_CONTEXT, { optional: true })`
+ * → `(ctx as { httpStatusSink? } | null)?.httpStatusSink`).
+ *
+ * **`@angular/ssr` streaming + `@defer` blocks:** `@defer` blocks hydrate
+ * lazily on the client; their server-side rendering is fully synchronous,
+ * so `<http-status-code />` inside or outside a `@defer` writes to the
+ * sink before `AngularNodeAppEngine.handle` resolves. No streaming
+ * ordering concern in Angular's current SSR model.
+ *
+ * **JIT vs AOT:** the `code` input is declared as `input<number>()` (not
+ * `input.required<number>()`) because `input.required` trips `NG0950` in
+ * JIT/TestBed even after `componentRef.setInput(...)`. `ngOnInit` skips
+ * the write when `code()` is `undefined`. AOT (production build) binds
+ * the value normally and the skip never fires.
+ *
+ * **Valid `code` range:** Node's `res.end()` throws `Invalid status code`
+ * on `NaN`, `0`, negative values, or values `> 999` — this surfaces as a
+ * 5xx / dropped connection, not silent corruption. Pass a real HTTP status
+ * integer (commonly 4xx/5xx; 100-999 is what Node accepts).
+ */
+@Component({
+  selector: "http-status-code",
+  template: "",
+})
+export class HttpStatusCode implements OnInit {
+  /**
+   * HTTP status to apply to the response. Common values: 404, 410, 451, 503.
+   *
+   * Declared as optional so the signal is safe to read in `ngOnInit` under
+   * both AOT (template binding fires before init hooks) and JIT/TestBed
+   * (`componentRef.setInput("code", N)` writes the value before the first
+   * change detection). `input.required` would trip `NG0950` in the JIT path
+   * because the required-flag is asserted independently of the runtime
+   * value. Consumers should always pass a value — `undefined` makes
+   * `ngOnInit` skip the sink write rather than throw.
+   */
+  readonly code = input<number>();
+
+  // Optional injection — when no `provideHttpStatusSink(...)` is registered
+  // (client side) the field is null and `ngOnInit` skips the write.
+  private readonly sink = inject(HTTP_STATUS_SINK, { optional: true });
+
+  ngOnInit(): void {
+    if (!this.sink) {
+      return;
+    }
+
+    const value = this.code();
+
+    if (value !== undefined) {
+      this.sink.code = value;
+    }
+  }
+}