@real-router/angular 0.11.1 → 0.11.2

package/src/internal/install.ts

@@ -1,90 +0,0 @@
-import { ApplicationRef, DestroyRef, inject } from "@angular/core";
-
-import {
-  createScrollRestoration,
-  createScrollSpy,
-  createViewTransitions,
-} from "../dom-utils";
-import { ROUTER } from "../providers";
-
-import type { ScrollRestorationOptions, ScrollSpyOptions } 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 installScrollSpy(options: ScrollSpyOptions): void {
-  const router = inject(ROUTER);
-  const spy = createScrollSpy(router, options);
-
-  inject(DestroyRef).onDestroy(() => {
-    spy.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

@@ -1,48 +0,0 @@
-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,80 +0,0 @@
-import {
-  InjectionToken,
-  makeEnvironmentProviders,
-  provideEnvironmentInitializer,
-  type EnvironmentProviders,
-} from "@angular/core";
-import { getNavigator, type Router, type Navigator } from "@real-router/core";
-import { createRouteSource } from "@real-router/sources";
-
-import {
-  installScrollRestoration,
-  installScrollSpy,
-  installViewTransitions,
-} from "./internal/install";
-import { sourceToSignal } from "./sourceToSignal";
-
-import type { ScrollRestorationOptions, ScrollSpyOptions } from "./dom-utils";
-import type { RouteSignals } from "./types";
-
-export const ROUTER = new InjectionToken<Router>("ROUTER");
-
-export const NAVIGATOR = new InjectionToken<Navigator>("NAVIGATOR");
-
-export const ROUTE = new InjectionToken<RouteSignals>("ROUTE");
-
-export interface RealRouterOptions {
-  scrollRestoration?: ScrollRestorationOptions;
-  scrollSpy?: ScrollSpyOptions;
-  viewTransitions?: boolean;
-}
-
-export function provideRealRouter(
-  router: Router,
-  options?: RealRouterOptions,
-): 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 },
-    {
-      provide: ROUTE,
-      useFactory: (): RouteSignals => ({
-        routeState: sourceToSignal(createRouteSource(router)),
-        navigator,
-      }),
-    },
-  ];
-
-  if (options?.scrollRestoration) {
-    const scrollOpts = options.scrollRestoration;
-
-    providers.push(
-      provideEnvironmentInitializer(() => {
-        installScrollRestoration(scrollOpts);
-      }),
-    );
-  }
-
-  if (options?.scrollSpy && options.scrollSpy.selector !== "") {
-    const spyOpts = options.scrollSpy;
-
-    providers.push(
-      provideEnvironmentInitializer(() => {
-        installScrollSpy(spyOpts);
-      }),
-    );
-  }
-
-  if (options?.viewTransitions === true) {
-    providers.push(provideEnvironmentInitializer(installViewTransitions));
-  }
-
-  return makeEnvironmentProviders(providers);
-}

package/src/providersFactory.ts

@@ -1,316 +0,0 @@
-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,
-  installScrollSpy,
-  installViewTransitions,
-} from "./internal/install";
-import { NAVIGATOR, ROUTE, ROUTER } from "./providers";
-import { sourceToSignal } from "./sourceToSignal";
-
-import type { ScrollRestorationOptions, ScrollSpyOptions } 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 scroll spy — same semantics as `provideRealRouter`. */
-  scrollSpy?: ScrollSpyOptions;
-
-  /** 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,
-    scrollSpy,
-    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 (scrollSpy && scrollSpy.selector !== "") {
-    providers.push(
-      provideEnvironmentInitializer(() => {
-        installScrollSpy(scrollSpy);
-      }),
-    );
-  }
-
-  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

@@ -1,28 +0,0 @@
-import { signal, type Signal, inject, DestroyRef } from "@angular/core";
-
-import type { RouterSource } from "@real-router/sources";
-
-/** Must be called within an injection context (constructor, field initializer, runInInjectionContext). */
-export function sourceToSignal<T>(source: RouterSource<T>): Signal<T> {
-  const sig = signal<T>(source.getSnapshot());
-  const destroyRef = inject(DestroyRef);
-
-  const unsubscribe = source.subscribe(() => {
-    sig.set(source.getSnapshot());
-  });
-
-  destroyRef.onDestroy(() => {
-    // `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,13 +0,0 @@
-import type { Signal } from "@angular/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;
-}