npm - @real-router/angular - Versions diffs - 0.8.0 → 0.9.0 - Mend

@real-router/angular 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (43) hide show

package/README.md +183 -4
package/dist/README.md +183 -4
package/dist/fesm2022/real-router-angular-ssr.mjs +323 -0
package/dist/fesm2022/real-router-angular-ssr.mjs.map +1 -0
package/dist/fesm2022/real-router-angular.mjs +759 -173
package/dist/fesm2022/real-router-angular.mjs.map +1 -1
package/dist/types/real-router-angular-ssr.d.ts +227 -0
package/dist/types/real-router-angular-ssr.d.ts.map +1 -0
package/dist/types/real-router-angular.d.ts +119 -20
package/dist/types/real-router-angular.d.ts.map +1 -1
package/package.json +18 -11
package/src/components/RouteView.ts +81 -56
package/src/components/RouterErrorBoundary.ts +7 -5
package/src/directives/RealLink.ts +57 -37
package/src/directives/RealLinkActive.ts +34 -25
package/src/dom-utils/link-utils.ts +119 -7
package/src/dom-utils/route-announcer.ts +58 -2
package/src/dom-utils/scroll-restore.ts +160 -12
package/src/functions/injectIsActiveRoute.ts +9 -8
package/src/functions/injectNavigator.ts +4 -0
package/src/functions/injectOrThrow.ts +5 -1
package/src/functions/injectRoute.ts +17 -8
package/src/functions/injectRouteEnter.ts +5 -10
package/src/functions/injectRouteNode.ts +3 -0
package/src/functions/injectRouteUtils.ts +3 -0
package/src/functions/injectRouter.ts +4 -0
package/src/functions/injectRouterTransition.ts +3 -0
package/src/index.ts +14 -3
package/src/internal/buildActiveRouteOptions.ts +20 -0
package/src/internal/install.ts +77 -0
package/src/internal/subscribeSourceToSignal.ts +48 -0
package/src/providers.ts +11 -38
package/src/providersFactory.ts +298 -0
package/src/sourceToSignal.ts +10 -2
package/src/types.ts +6 -1
package/ssr/components/ClientOnly.ts +27 -0
package/ssr/components/HttpStatusCode.ts +106 -0
package/ssr/components/ServerOnly.ts +27 -0
package/ssr/functions/injectDeferred.ts +92 -0
package/ssr/functions/provideHttpStatusSink.ts +43 -0
package/ssr/ng-package.json +6 -0
package/ssr/public_api.ts +35 -0
package/ssr/utils/createHttpStatusSink.ts +61 -0

package/src/dom-utils/route-announcer.ts CHANGED Viewed

@@ -12,10 +12,29 @@ export interface RouteAnnouncerOptions {
   getAnnouncementText?: (route: State) => string;
 }
+const NOOP_INSTANCE: { destroy: () => void } = Object.freeze({
+  destroy: () => {
+    /* no-op */
+  },
+});
 export function createRouteAnnouncer(
   router: Router,
   options?: RouteAnnouncerOptions,
 ): { destroy: () => void } {
+  // Defensive SSR / non-browser guard: in SSR (Node.js) or non-DOM
+  // environments, `document` is undefined and the announcer cannot
+  // attach its aria-live region. Return a frozen NOOP_INSTANCE — same
+  // pattern as `createDirectionTracker`, `createScrollRestoration`, and
+  // `createViewTransitions`. Without this guard, `NavigationAnnouncer`
+  // component construction would throw `ReferenceError: document is not
+  // defined` under `@angular/ssr` rendering, tearing down the whole SSR
+  // bootstrap. Closes review-2026-05-10 §5.10 ⛔ "NavigationAnnouncer
+  // SSR mode" MED.
+  if (typeof document === "undefined") {
+    return NOOP_INSTANCE;
+  }
   const prefix = options?.prefix ?? "Navigated to ";
   const getCustomText = options?.getAnnouncementText;
@@ -117,7 +136,21 @@ function getOrCreateAnnouncer(): HTMLElement {
   element.setAttribute("aria-atomic", "true");
   element.setAttribute(ANNOUNCER_ATTR, "");
-  document.body.prepend(element);
+  // Defensive SSR / pre-`<body>` guard: in some environments (early
+  // injection, deferred-body documents, certain SSR rehydration paths)
+  // `document.body` can be null when the announcer is constructed.
+  // `document.body.prepend(...)` would throw `TypeError: Cannot read
+  // properties of null`, tearing down the consumer's RouterProvider /
+  // NavigationAnnouncer mount. Fallback to `documentElement` keeps the
+  // announcer working for SR users; visual-hidden styling means there is
+  // no visible artifact regardless of mount point.
+  //
+  // TS dom lib types `document.body` as `HTMLElement` (non-null), but
+  // runtime can return null per spec. The `as` cast narrows the type to
+  // include null so the `??` short-circuit is type-safe.
+  ((document.body as HTMLElement | null) ?? document.documentElement).prepend(
+    element,
+  );
   return element;
 }
@@ -133,7 +166,30 @@ function resolveText(
   h1: HTMLElement | null,
 ): string {
   if (getCustomText) {
-    return getCustomText(route);
+    try {
+      const customText = getCustomText(route);
+      // Mini-sprint E.4 (audit-5 §4.2 #4) — empty-string fallback.
+      // A consumer pattern like
+      //   getAnnouncementText: (route) => myMap[route.name] ?? ""
+      // returns `""` for routes outside the map. The subscribe loop
+      // then sees an empty text and silently no-announces — screen
+      // readers stay quiet without any signal to the developer. Treat
+      // a falsy custom result (`""` / `null` / `undefined`) as
+      // "consumer doesn't have a name for this route" and fall through
+      // to the default resolution chain (h1 → title → route name).
+      if (customText) {
+        return customText;
+      }
+    } catch (error) {
+      // A throwing consumer callback inside the router's subscribe loop
+      // would tear down sibling listeners — log and fall through to the
+      // built-in resolution chain so the announcer keeps working.
+      console.error(
+        "[real-router] getAnnouncementText threw; falling back to default resolution.",
+        error,
+      );
+    }
   }
   const h1Text = (h1?.textContent ?? "").trim();

package/src/dom-utils/scroll-restore.ts CHANGED Viewed

@@ -67,22 +67,42 @@ export function createScrollRestoration(
   const behavior: ScrollBehavior = options?.behavior ?? "auto";
   const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
+  // Write-through in-memory cache: parse sessionStorage once per provider
+  // mount, then mutate in-memory. Avoids a JSON.parse + JSON.stringify pair
+  // on every subscribeLeave / pagehide event.
+  let store: Record<string, number> | undefined;
   const loadStore = (): Record<string, number> => {
+    if (store !== undefined) {
+      return store;
+    }
     try {
       const raw = sessionStorage.getItem(storageKey);
-      return raw ? (JSON.parse(raw) as Record<string, number>) : {};
+      store = raw ? (JSON.parse(raw) as Record<string, number>) : {};
     } catch {
-      return {};
+      store = {};
     }
+    return store;
   };
   const putPos = (key: string, pos: number): void => {
     try {
-      const store = loadStore();
+      const cached = loadStore();
+      // Skip-same-value: when a route is left at the same scroll position it
+      // already holds in the cache (e.g. tab-switching without scrolling),
+      // both the in-memory write and the JSON.stringify + setItem pair are
+      // no-ops. Eliminates redundant serialization on the navigation hot
+      // path for the common "click tabs without scrolling" case.
+      if (cached[key] === pos) {
+        return;
+      }
-      store[key] = pos;
-      sessionStorage.setItem(storageKey, JSON.stringify(store));
+      cached[key] = pos;
+      sessionStorage.setItem(storageKey, JSON.stringify(cached));
     } catch {
       // Ignore quota / security errors.
     }
@@ -169,6 +189,30 @@ export function createScrollRestoration(
   };
   let destroyed = false;
+  let unserializableWarned = false;
+  // `keyOf` defers to `canonicalJson` which calls `JSON.stringify`. Two
+  // realistic inputs blow up the serializer and would otherwise crash the
+  // subscribe callback (taking scroll-restore offline for the whole session):
+  //   - `BigInt` params → `TypeError: Do not know how to serialize a BigInt`
+  //   - cyclic params (reactive proxies, DOM-ref back-pointers) → stack
+  //     overflow.
+  // The defensive wrapper drops capture/restore for that specific navigation
+  // and warns once per provider — the rest of the cache stays usable.
+  const safeKeyOf = (state: State): string | null => {
+    try {
+      return keyOf(state);
+    } catch {
+      if (!unserializableWarned) {
+        unserializableWarned = true;
+        console.error(
+          `[real-router] scroll-restore: route "${state.name}" has params that cannot be canonicalized (e.g. BigInt or cyclic structure). Scroll position will not be captured or restored for this route.`,
+        );
+      }
+      return null;
+    }
+  };
   const unsubscribe = router.subscribe(({ route, previousRoute }) => {
     const nav = (route.context as { navigation?: NavigationContext })
@@ -178,7 +222,11 @@ export function createScrollRestoration(
     // previousRoute is undefined and capture is naturally skipped. The
     // pre-refresh position was already persisted via pagehide.
     if (previousRoute) {
-      putPos(keyOf(previousRoute), readPos());
+      const prevKey = safeKeyOf(previousRoute);
+      if (prevKey !== null) {
+        putPos(prevKey, readPos());
+      }
     }
     // Single rAF so DOM is committed before we read anchors / write scroll.
@@ -203,7 +251,9 @@ export function createScrollRestoration(
         nav.navigationType === "traverse" ||
         nav.navigationType === "reload"
       ) {
-        writePos(loadStore()[keyOf(route)] ?? 0);
+        const key = safeKeyOf(route);
+        writePos(key === null ? 0 : (loadStore()[key] ?? 0));
         return;
       }
@@ -216,7 +266,11 @@ export function createScrollRestoration(
     const current = router.getState();
     if (current) {
-      putPos(keyOf(current), readPos());
+      const key = safeKeyOf(current);
+      if (key !== null) {
+        putPos(key, readPos());
+      }
     }
   };
@@ -241,17 +295,111 @@ export function createScrollRestoration(
   };
 }
-function keyOf(state: State): string {
-  return `${state.name}:${canonicalJson(state.params)}`;
+/**
+ * Internal cache-key builder for scroll-position storage.
+ *
+ * **Exported for testing only — not part of the public API** (intentionally
+ * excluded from `index.ts` barrel). Adapter property tests import it via
+ * the direct path to lock the `(name, canonicalJson(params))` key shape
+ * as a regression guard (§8b H20 / audit-2026-05-16 #S3). A change to
+ * key format would silently lose scroll positions across an upgrade —
+ * the test set is the contract.
+ *
+ * ## Identity-based memoization (audit-2026-05-17 §8b #2)
+ *
+ * `State` objects emitted by core are frozen per-navigation: their
+ * `name` / `params` are immutable for the lifetime of the snapshot, and
+ * any change produces a new `State` reference. A `WeakMap<State, string>`
+ * therefore safely caches the canonicalised key by identity — repeat
+ * `keyOf(state)` calls on the same snapshot (typical on
+ * back/forward/traverse where the same prior `State` is re-emitted)
+ * skip the recursive `canonicalJson` pass entirely.
+ *
+ * The cache key is the `State` reference, so entries auto-release when
+ * the snapshot is GC'd — no eviction needed.
+ */
+const KEY_CACHE = new WeakMap<State, string>();
+export function keyOf(state: State): string {
+  const cached = KEY_CACHE.get(state);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const key = `${state.name}:${canonicalJson(state.params)}`;
+  KEY_CACHE.set(state, key);
+  return key;
 }
-function canonicalJson(value: unknown): string {
+/**
+ * Stable JSON serializer with sorted object keys.
+ *
+ * **Exported for testing only — not part of the public API** (intentionally
+ * excluded from `index.ts` barrel). Adapter property tests import it via
+ * the direct path to lock the key-order-insensitive property
+ * (`canonicalJson({a:1,b:2}) === canonicalJson({b:2,a:1})`).
+ *
+ * ## Divergence from `@real-router/sources/canonicalJson` — by design
+ *
+ * Two independent implementations live in the monorepo:
+ *
+ * - **`shared/dom-utils/scroll-restore.canonicalJson`** (this file) — scroll
+ *   cache key builder. Uses `localeCompare` and a plain-object accumulator;
+ *   tolerates `__proto__`-keyed inputs only insofar as `JSON.stringify`'s
+ *   replacer happens to sort them; relies on `JSON.stringify`'s native cycle
+ *   detector. Designed to be cheap on the navigation hot path. The
+ *   surrounding [[safeKeyOf]] wrapper catches the two crash inputs (`BigInt`,
+ *   cyclic) and skips the offending capture/restore.
+ *
+ * - **`@real-router/sources/canonicalJson`** — sources cache key builder.
+ *   Uses byte-order compare (`< / >`) for locale-independence, a
+ *   `Object.create(null)` accumulator to prevent prototype pollution, and a
+ *   bespoke path-based cycle detector (the native one cannot see the cloned
+ *   graph). Throws eagerly on `Map`/`Set`/`RegExp`/cycles — the caller falls
+ *   back to a non-cached source.
+ *
+ * **They are intentionally NOT interchangeable.** Aligning them would either
+ * regress scroll-restore performance (byte-order + recursive clone is heavier
+ * per call) or weaken the sources cache (locale dependence breaks
+ * deterministic cache keys across machines). No cross-package equivalence
+ * test exists or should be added; the relationship is "different invariants,
+ * different costs, different consumers." Audit-2 / audit-2026-05-17 §2
+ * documents the choice.
+ */
+export function canonicalJson(value: unknown): string {
   return JSON.stringify(value, canonicalReplacer);
 }
 function canonicalReplacer(_key: string, val: unknown): unknown {
+  // audit-2026-05-17 §5 MEDIUM (Sprint A.3) — function/Symbol marker.
+  // `JSON.stringify` silently drops function and symbol values from
+  // object output. Two routes that differ ONLY in a function/Symbol
+  // value would canonicalize to the same string → silent scroll-cache
+  // key collision (positions clobber each other). Replacing the value
+  // with a sentinel string breaks the collision while keeping the
+  // canonical form deterministic. The sentinels are intentionally
+  // ASCII-only and lexically distinct from valid JSON-stringified
+  // values; consumers will see `"<fn>"` / `"<sym>"` if they ever
+  // round-trip the cache key, signalling the substitution clearly.
+  if (typeof val === "function") {
+    return "<fn>";
+  }
+  if (typeof val === "symbol") {
+    return "<sym>";
+  }
   if (val !== null && typeof val === "object" && !Array.isArray(val)) {
-    const sorted: Record<string, unknown> = {};
+    // Null-prototype accumulator: a plain `{}` would interpret
+    // `sorted["__proto__"] = x` as a prototype assignment (silently dropped
+    // from JSON.stringify output AND a prototype-pollution vector). Mirrors
+    // the same guard in `@real-router/sources/canonicalJson`. The two
+    // implementations are still intentionally divergent (see the doc-block
+    // on [[canonicalJson]] above), but prototype-safety is non-negotiable
+    // on both. Lock-test: scrollRestoreKey.properties.ts Invariant 11.
+    const sorted = Object.create(null) as Record<string, unknown>;
     // eslint-disable-next-line unicorn/no-array-sort -- ng-packagr uses pre-ES2023 lib; toSorted unavailable
     const keys = Object.keys(val as Record<string, unknown>).sort(
       (left: string, right: string) => left.localeCompare(right),

package/src/functions/injectIsActiveRoute.ts CHANGED Viewed

@@ -1,5 +1,7 @@
+import { assertInInjectionContext } from "@angular/core";
 import { createActiveRouteSource } from "@real-router/sources";
+import { buildActiveRouteOptions } from "../internal/buildActiveRouteOptions";
 import { sourceToSignal } from "../sourceToSignal";
 import { injectRouter } from "./injectRouter";
@@ -11,19 +13,18 @@ export function injectIsActiveRoute(
   params?: Params,
   options?: { strict?: boolean; ignoreQueryParams?: boolean; hash?: string },
 ): Signal<boolean> {
+  assertInInjectionContext(injectIsActiveRoute);
   const router = injectRouter();
-  const strict = options?.strict ?? false;
-  const ignoreQueryParams = options?.ignoreQueryParams ?? true;
-  const hash = options?.hash;
-  // exactOptionalPropertyTypes forbids `{ hash: undefined }` literally — pass
-  // the field only when a value was provided. (#532)
   const source = createActiveRouteSource(
     router,
     routeName,
     params,
-    hash === undefined
-      ? { strict, ignoreQueryParams }
-      : { strict, ignoreQueryParams, hash },
+    buildActiveRouteOptions(
+      options?.strict ?? false,
+      options?.ignoreQueryParams ?? true,
+      options?.hash,
+    ),
   );
   return sourceToSignal(source);

package/src/functions/injectNavigator.ts CHANGED Viewed

@@ -1,8 +1,12 @@
+import { assertInInjectionContext } from "@angular/core";
 import { injectOrThrow } from "./injectOrThrow";
 import { NAVIGATOR } from "../providers";
 import type { Navigator } from "@real-router/core";
 export function injectNavigator(): Navigator {
+  assertInInjectionContext(injectNavigator);
   return injectOrThrow(NAVIGATOR, "injectNavigator");
 }

package/src/functions/injectOrThrow.ts CHANGED Viewed

@@ -5,7 +5,11 @@ import type { InjectionToken } from "@angular/core";
 export function injectOrThrow<T>(token: InjectionToken<T>, fnName: string): T {
   const value = inject(token, { optional: true });
-  if (!value) {
+  // Explicit null / undefined check — falsy guard would misfire on
+  // legitimately falsy values (`0`, `""`, `false`) if the token were ever
+  // typed for primitives. Today all our tokens hold object instances, but
+  // pinning the check keeps the function safe for future typing changes.
+  if (value === null || value === undefined) {
     throw new Error(
       `${fnName} must be used within a provideRealRouter context`,
     );

package/src/functions/injectRoute.ts CHANGED Viewed

@@ -1,3 +1,5 @@
+import { assertInInjectionContext } from "@angular/core";
 import { injectOrThrow } from "./injectOrThrow";
 import { ROUTE } from "../providers";
@@ -6,25 +8,32 @@ import type { Signal } from "@angular/core";
 import type { Params, State } from "@real-router/core";
 import type { RouteSnapshot } from "@real-router/sources";
-export function injectRoute<P extends Params = Params>(): Omit<
+type NonNullRouteSignals<P extends Params> = Omit<
   RouteSignals<P>,
   "routeState"
 > & {
   readonly routeState: Signal<
     Omit<RouteSnapshot<P>, "route"> & { route: State<P> }
   >;
-} {
+};
+export function injectRoute<
+  P extends Params = Params,
+>(): NonNullRouteSignals<P> {
+  assertInInjectionContext(injectRoute);
   const signals = injectOrThrow(ROUTE, "injectRoute") as RouteSignals<P>;
-  if (!signals.routeState().route) {
+  // Read the snapshot once: the signal is reactive, but the throw-guard
+  // and any future use of the snapshot within this call should observe the
+  // SAME value to avoid races.
+  const snapshot = signals.routeState();
+  if (!snapshot.route) {
     throw new Error(
       "injectRoute called with no active route. Did you forget to await router.start() before rendering, or is the router stopped/disposed?",
     );
   }
-  return signals as Omit<RouteSignals<P>, "routeState"> & {
-    readonly routeState: Signal<
-      Omit<RouteSnapshot<P>, "route"> & { route: State<P> }
-    >;
-  };
+  return signals as NonNullRouteSignals<P>;
 }

package/src/functions/injectRouteEnter.ts CHANGED Viewed

@@ -87,7 +87,6 @@ export function injectRouteEnter(
   const { routeState } = injectRoute();
   const skipSameRoute = options?.skipSameRoute ?? true;
-  let lastHandledRoute: State | null = null;
   effect(() => {
     const { route, previousRoute } = routeState();
@@ -99,24 +98,20 @@ export function injectRouteEnter(
     //   - **Skip-same-route**: query-only navigations have
     //     `transition.from === route.name`. Opt-out via
     //     `skipSameRoute: false`.
-    //   - **Defensive dedupe + missing `previousRoute`**: same `route`
-    //     ref between effect re-runs is unexpected on Angular (the
-    //     signal only fires on real reference changes); `!previousRoute`
-    //     is unreachable once `transition.from` is set (core populates
-    //     them together). Both kept for parity with React; v8-ignored.
     if (!route.transition.from) {
       return;
     }
     if (skipSameRoute && route.transition.from === route.name) {
       return;
     }
-    /* v8 ignore start */
-    if (lastHandledRoute === route || !previousRoute) {
+    // `previousRoute` is guaranteed populated whenever `route.transition.from`
+    // is set — core writes them together. The dead-code throw-guard that used
+    // to live here (review §8a LOW) is removed; the narrowing below is the
+    // type-safe equivalent and avoids the no-non-null-assertion lint.
+    if (!previousRoute) {
       return;
     }
-    /* v8 ignore stop */
-    lastHandledRoute = route;
     handler({ route, previousRoute });
   });
 }

package/src/functions/injectRouteNode.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+import { assertInInjectionContext } from "@angular/core";
 import { getNavigator } from "@real-router/core";
 import { createRouteNodeSource } from "@real-router/sources";
@@ -7,6 +8,8 @@ import { injectRouter } from "./injectRouter";
 import type { RouteSignals } from "../types";
 export function injectRouteNode(nodeName: string): RouteSignals {
+  assertInInjectionContext(injectRouteNode);
   const router = injectRouter();
   const navigator = getNavigator(router);
   const source = createRouteNodeSource(router, nodeName);

package/src/functions/injectRouteUtils.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+import { assertInInjectionContext } from "@angular/core";
 import { getPluginApi } from "@real-router/core/api";
 import { getRouteUtils } from "@real-router/route-utils";
@@ -6,6 +7,8 @@ import { injectRouter } from "./injectRouter";
 import type { RouteUtils } from "@real-router/route-utils";
 export function injectRouteUtils(): RouteUtils {
+  assertInInjectionContext(injectRouteUtils);
   const router = injectRouter();
   return getRouteUtils(getPluginApi(router).getTree());

package/src/functions/injectRouter.ts CHANGED Viewed

@@ -1,8 +1,12 @@
+import { assertInInjectionContext } from "@angular/core";
 import { injectOrThrow } from "./injectOrThrow";
 import { ROUTER } from "../providers";
 import type { Router } from "@real-router/core";
 export function injectRouter(): Router {
+  assertInInjectionContext(injectRouter);
   return injectOrThrow(ROUTER, "injectRouter");
 }

package/src/functions/injectRouterTransition.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+import { assertInInjectionContext } from "@angular/core";
 import { getTransitionSource } from "@real-router/sources";
 import { sourceToSignal } from "../sourceToSignal";
@@ -7,6 +8,8 @@ import type { Signal } from "@angular/core";
 import type { RouterTransitionSnapshot } from "@real-router/sources";
 export function injectRouterTransition(): Signal<RouterTransitionSnapshot> {
+  assertInInjectionContext(injectRouterTransition);
   const router = injectRouter();
   const source = getTransitionSource(router);

package/src/index.ts CHANGED Viewed

@@ -1,7 +1,20 @@
 export { provideRealRouter, ROUTER, NAVIGATOR, ROUTE } from "./providers";
+export type { RealRouterOptions } from "./providers";
+export { provideRealRouterFactory } from "./providersFactory";
+export type {
+  RealRouterFactoryOptions,
+  RequestDepsFactory,
+  RequestPluginsFactory,
+} from "./providersFactory";
 export { sourceToSignal } from "./sourceToSignal";
+// Note: SSR-feature exports (`ClientOnly`, `ServerOnly`, `injectDeferred`)
+// have moved to the `/ssr` subpath — import them from
+// `@real-router/angular/ssr` to opt into the SSR-feature surface.
 export {
   injectRouter,
   injectNavigator,
@@ -27,8 +40,6 @@ export { RouteView } from "./components/RouteView";
 export { RouterErrorBoundary } from "./components/RouterErrorBoundary";
-export type { ErrorContext } from "./components/RouterErrorBoundary";
 export { NavigationAnnouncer } from "./components/NavigationAnnouncer";
 export { RouteMatch } from "./directives/RouteMatch";
@@ -41,7 +52,7 @@ export { RealLink } from "./directives/RealLink";
 export { RealLinkActive } from "./directives/RealLinkActive";
-export type { RouteSignals } from "./types";
+export type { RouteSignals, ErrorContext } from "./types";
 export type {
   RouteSnapshot,

package/src/internal/buildActiveRouteOptions.ts ADDED Viewed

@@ -0,0 +1,20 @@
+import type { ActiveRouteSourceOptions } from "@real-router/sources";
+/**
+ * Build the `options` literal for `createActiveRouteSource` while honoring
+ * `exactOptionalPropertyTypes` — the type forbids passing `{ hash: undefined }`
+ * literally (#532), so callers must conditionally include the `hash` key only
+ * when a value was provided.
+ *
+ * Used by `RealLink`, `RealLinkActive`, and `injectIsActiveRoute` — extracted
+ * from three identical ternaries (review-2026-05-16 §8a LOW).
+ */
+export function buildActiveRouteOptions(
+  strict: boolean,
+  ignoreQueryParams: boolean,
+  hash: string | undefined,
+): ActiveRouteSourceOptions {
+  return hash === undefined
+    ? { strict, ignoreQueryParams }
+    : { strict, ignoreQueryParams, hash };
+}

package/src/internal/install.ts ADDED Viewed

@@ -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();
+  });
+}