@real-router/angular 0.8.1 → 0.10.0

package/src/components/RouteView.ts

@@ -3,11 +3,9 @@ import {
   Component,
   computed,
   contentChildren,
-  inject,
+  effect,
   input,
   signal,
-  DestroyRef,
-  type OnInit,
   type TemplateRef,
 } from "@angular/core";
 import { UNKNOWN_ROUTE } from "@real-router/core";
@@ -18,13 +16,14 @@ import { RouteMatch } from "../directives/RouteMatch";
 import { RouteNotFound } from "../directives/RouteNotFound";
 import { RouteSelf } from "../directives/RouteSelf";
 import { injectRouter } from "../functions/injectRouter";
+import { subscribeSourceToSignal } from "../internal/subscribeSourceToSignal";
 
 import type { RouteSnapshot } from "@real-router/sources";
 
-const EMPTY_SNAPSHOT: RouteSnapshot = Object.freeze({
+const EMPTY_SNAPSHOT: RouteSnapshot = {
   route: undefined,
   previousRoute: undefined,
-});
+};
 
 @Component({
   selector: "route-view",
@@ -35,52 +34,19 @@ const EMPTY_SNAPSHOT: RouteSnapshot = Object.freeze({
   `,
   imports: [NgTemplateOutlet],
 })
-export class RouteView implements OnInit {
+export class RouteView {
   readonly nodeName = input<string>("", { alias: "routeNode" });
 
   readonly matches = contentChildren(RouteMatch, { descendants: true });
   readonly selfs = contentChildren(RouteSelf, { descendants: true });
   readonly notFounds = contentChildren(RouteNotFound, { descendants: true });
 
-  readonly activeTemplate = computed<TemplateRef<unknown> | null>(() => {
-    const snapshot = this.routeState();
-    const route = snapshot.route;
+  readonly activeTemplate = computed<TemplateRef<unknown> | null>(
+    () => this.matchedTemplate() ?? this.fallbackTemplate(),
+  );
 
-    if (!route) {
-      return null;
-    }
-
-    const routeName = route.name;
-    const entries = this.matchEntries();
-
-    for (const { match, fullSegmentName } of entries) {
-      if (startsWithSegment(routeName, fullSegmentName)) {
-        return match.templateRef;
-      }
-    }
-
-    // Self has priority over NotFound. First-wins to mirror NotFound's
-    // last-wins inversion would be inconsistent with React/Preact/Solid/Vue
-    // adapters where Self is "first wins"; Angular's contentChildren returns
-    // declaration order, so picking [0] gives first-wins.
-    if (routeName === this.nodeName()) {
-      const first = this.selfs().at(0);
-
-      if (first) {
-        return first.templateRef;
-      }
-    }
-
-    if (routeName === UNKNOWN_ROUTE) {
-      const last = this.notFounds().at(-1);
-
-      if (last) {
-        return last.templateRef;
-      }
-    }
-
-    return null;
-  });
+  private readonly router = injectRouter();
+  private readonly routeState = signal<RouteSnapshot>(EMPTY_SNAPSHOT);
 
   private readonly matchEntries = computed(() => {
     const nodeName = this.nodeName();
@@ -95,22 +61,81 @@ export class RouteView implements OnInit {
     });
   });
 
-  private readonly router = injectRouter();
-  private readonly destroyRef = inject(DestroyRef);
-  private readonly routeState = signal<RouteSnapshot>(EMPTY_SNAPSHOT);
+  // The matched template (Match priority) is independent of the Self /
+  // NotFound fallback chain. Splitting the two paths into separate computeds
+  // localises re-runs: a change to `selfs()` / `notFounds()` no longer
+  // re-evaluates the Match loop (review §8a LOW — RouteView activeTemplate
+  // split).
+  private readonly matchedTemplate = computed<TemplateRef<unknown> | null>(
+    () => {
+      const route = this.routeState().route;
+
+      if (!route) {
+        return null;
+      }
 
-  ngOnInit(): void {
-    const source = createRouteNodeSource(this.router, this.nodeName());
+      const routeName = route.name;
 
-    this.routeState.set(source.getSnapshot());
+      for (const { match, fullSegmentName } of this.matchEntries()) {
+        if (startsWithSegment(routeName, fullSegmentName)) {
+          return match.templateRef;
+        }
+      }
 
-    const unsub = source.subscribe(() => {
-      this.routeState.set(source.getSnapshot());
-    });
+      return null;
+    },
+  );
+
+  // Fallback chain — only consulted when `matchedTemplate()` returned `null`.
+  // Template priority: Self → NotFound. Selection rules differ on purpose:
+  //   - **Self uses first-wins** (`.at(0)`) for parity with React / Preact /
+  //     Solid / Vue, where the first matching `<Self>` token in declaration
+  //     order wins.
+  //   - **NotFound uses last-wins** (`.at(-1)`) intentionally — the fallback
+  //     should be the most-recently-declared template so that consumers can
+  //     override an inherited `<ng-template routeNotFound>` simply by
+  //     re-declaring it lower in the projected content.
+  private readonly fallbackTemplate = computed<TemplateRef<unknown> | null>(
+    () => {
+      const route = this.routeState().route;
+
+      if (!route) {
+        return null;
+      }
 
-    this.destroyRef.onDestroy(() => {
-      unsub();
-      source.destroy();
+      const routeName = route.name;
+
+      if (routeName === this.nodeName()) {
+        const first = this.selfs().at(0);
+
+        if (first) {
+          return first.templateRef;
+        }
+      }
+
+      if (routeName === UNKNOWN_ROUTE) {
+        const last = this.notFounds().at(-1);
+
+        if (last) {
+          return last.templateRef;
+        }
+      }
+
+      return null;
+    },
+  );
+
+  constructor() {
+    // Reactive source-creation effect (#630 fix) — see
+    // `packages/angular/CLAUDE.md` → "Directives use constructor + effect()".
+    effect((onCleanup) => {
+      const source = createRouteNodeSource(this.router, this.nodeName());
+
+      onCleanup(
+        subscribeSourceToSignal(source, (snap) => {
+          this.routeState.set(snap);
+        }),
+      );
     });
   }
 }

package/src/components/RouterErrorBoundary.ts

@@ -5,15 +5,11 @@ import { createDismissableError } from "@real-router/sources";
 import { injectRouter } from "../functions/injectRouter";
 import { sourceToSignal } from "../sourceToSignal";
 
+import type { ErrorContext } from "../types";
 import type { TemplateRef } from "@angular/core";
 import type { RouterError, State } from "@real-router/core";
 import type { DismissableErrorSnapshot } from "@real-router/sources";
 
-export interface ErrorContext {
-  $implicit: RouterError;
-  resetError: () => void;
-}
-
 @Component({
   selector: "router-error-boundary",
   template: `
@@ -55,6 +51,12 @@ export class RouterErrorBoundary {
   );
 
   constructor() {
+    // `effect()` registers itself with the current injection context's
+    // `DestroyRef` and tears down automatically when the component is
+    // destroyed. The earlier manual `effectRef.destroy()` wired through
+    // `inject(DestroyRef).onDestroy(...)` duplicated that built-in cleanup
+    // (audit §8.1 LOW — confirmed: no behavior change without the manual
+    // path).
     effect(() => {
       const snap = this.snapshot();
 

package/src/directives/RealLink.ts

@@ -2,26 +2,29 @@ import {
   Directive,
   ElementRef,
   computed,
+  effect,
   inject,
   input,
   signal,
-  DestroyRef,
-  type OnInit,
 } from "@angular/core";
 import { createActiveRouteSource } from "@real-router/sources";
 
 import { buildHref, navigateWithHash, shouldNavigate } from "../dom-utils";
 import { injectRouter } from "../functions/injectRouter";
+import { buildActiveRouteOptions } from "../internal/buildActiveRouteOptions";
+import { subscribeSourceToSignal } from "../internal/subscribeSourceToSignal";
 
 import type { Params, NavigationOptions } from "@real-router/core";
 
+const NOOP_CATCH = (): void => {};
+
 @Directive({
   selector: "a[realLink]",
   host: {
     "(click)": "onClick($event)",
   },
 })
-export class RealLink implements OnInit {
+export class RealLink {
   readonly routeName = input<string>("");
   readonly routeParams = input<Params>({});
   readonly routeOptions = input<NavigationOptions>({});
@@ -37,10 +40,13 @@ export class RealLink implements OnInit {
   readonly hash = input<string | undefined>(undefined);
 
   private readonly router = injectRouter();
-  private readonly destroyRef = inject(DestroyRef);
   private readonly anchor = inject(ElementRef)
     .nativeElement as HTMLAnchorElement;
   private readonly isActive = signal(false);
+  // `href` is computed from signal inputs only — Angular's default Object.is
+  // equality already collapses repeated `string` results, so no custom
+  // comparator is required (review §8b note 3 — applies after verifying that
+  // `buildHref` returns a primitive).
   private readonly href = computed(() => {
     const hashValue = this.hash();
 
@@ -52,38 +58,48 @@ export class RealLink implements OnInit {
     );
   });
   private prevActiveClass = "";
-
-  ngOnInit(): void {
-    // Hash-aware active state (#532): pass `hash` so that tab-style links
-    // (same routeName, different `hash` input) only mark the active variant.
-    const hashValue = this.hash();
-    const source = createActiveRouteSource(
-      this.router,
-      this.routeName(),
-      this.routeParams(),
-      hashValue === undefined
-        ? {
-            strict: this.activeStrict(),
-            ignoreQueryParams: this.ignoreQueryParams(),
+  private prevHref: string | undefined = undefined;
+  // Skip-same-value: only re-touch the DOM `class` list when the active state
+  // actually flipped. Without this, every navigation that re-fires the active
+  // source still issues a `classList.toggle` no-op (review §8b MEDIUM).
+  private prevActive: boolean | undefined = undefined;
+
+  constructor() {
+    // Reactive source-creation effect (#630 fix) — see
+    // `packages/angular/CLAUDE.md` → "Directives use constructor + effect()".
+    // Reading signal inputs inside `effect()` re-creates the active-route
+    // source whenever any input changes; `onCleanup` tears the previous
+    // subscription down.
+    effect((onCleanup) => {
+      const source = createActiveRouteSource(
+        this.router,
+        this.routeName(),
+        this.routeParams(),
+        buildActiveRouteOptions(
+          this.activeStrict(),
+          this.ignoreQueryParams(),
+          this.hash(),
+        ),
+      );
+
+      onCleanup(
+        subscribeSourceToSignal(source, (snap) => {
+          // Pure-href refresh: when the active flag did not change, only the
+          // href may have moved (e.g. param-only update on a parent route).
+          // Skip the classList work in that branch (review §8b MEDIUM).
+          if (snap === this.prevActive) {
+            this.isActive.set(snap);
+            this.updateHref();
+
+            return;
           }
-        : {
-            strict: this.activeStrict(),
-            ignoreQueryParams: this.ignoreQueryParams(),
-            hash: hashValue,
-          },
-    );
-
-    this.isActive.set(source.getSnapshot());
-    this.updateDom();
-
-    const unsub = source.subscribe(() => {
-      this.isActive.set(source.getSnapshot());
-      this.updateDom();
-    });
 
-    this.destroyRef.onDestroy(() => {
-      unsub();
-      source.destroy();
+          this.prevActive = snap;
+          this.isActive.set(snap);
+          this.updateHref();
+          this.updateActiveClass();
+        }),
+      );
     });
   }
 
@@ -99,16 +115,20 @@ export class RealLink implements OnInit {
       this.routeParams(),
       this.hash(),
       this.routeOptions(),
-    ).catch(() => {});
+    ).catch(NOOP_CATCH);
   }
 
-  private updateDom(): void {
+  private updateHref(): void {
     const href = this.href();
 
-    if (href !== undefined) {
+    if (href !== undefined && href !== this.prevHref) {
       this.anchor.setAttribute("href", href);
     }
 
+    this.prevHref = href;
+  }
+
+  private updateActiveClass(): void {
     const activeClass = this.activeClassName();
 
     if (this.prevActiveClass && this.prevActiveClass !== activeClass) {

package/src/directives/RealLinkActive.ts

@@ -1,21 +1,22 @@
 import {
   Directive,
   ElementRef,
+  effect,
   inject,
   input,
   signal,
-  DestroyRef,
-  type OnInit,
 } from "@angular/core";
 import { createActiveRouteSource } from "@real-router/sources";
 
 import { applyLinkA11y } from "../dom-utils";
 import { injectRouter } from "../functions/injectRouter";
+import { buildActiveRouteOptions } from "../internal/buildActiveRouteOptions";
+import { subscribeSourceToSignal } from "../internal/subscribeSourceToSignal";
 
 import type { Params } from "@real-router/core";
 
 @Directive({ selector: "[realLinkActive]" })
-export class RealLinkActive implements OnInit {
+export class RealLinkActive {
   readonly realLinkActive = input<string>("");
   readonly routeName = input<string>("");
   readonly routeParams = input<Params>({});
@@ -23,36 +24,44 @@ export class RealLinkActive implements OnInit {
   readonly ignoreQueryParams = input(true);
 
   private readonly router = injectRouter();
-  private readonly destroyRef = inject(DestroyRef);
   private readonly element = inject(ElementRef).nativeElement as HTMLElement;
   private readonly isActive = signal(false);
+  // Skip-same-value: only touch `classList.toggle` when the active flag
+  // actually flipped. Saves one DOM write per RealLinkActive per unrelated
+  // navigation (review §8b MEDIUM).
+  private prevActive: boolean | undefined = undefined;
 
   constructor() {
+    // One-time a11y setup — doesn't depend on signal inputs, stays in
+    // constructor body. `applyLinkA11y` is idempotent so re-running would
+    // be safe, but we only need it once per element.
     applyLinkA11y(this.element);
-  }
-
-  ngOnInit(): void {
-    const source = createActiveRouteSource(
-      this.router,
-      this.routeName(),
-      this.routeParams(),
-      {
-        strict: this.activeStrict(),
-        ignoreQueryParams: this.ignoreQueryParams(),
-      },
-    );
 
-    this.isActive.set(source.getSnapshot());
-    this.updateClass();
+    // Reactive source-creation effect (#630 fix) — see
+    // `packages/angular/CLAUDE.md` → "Directives use constructor + effect()".
+    effect((onCleanup) => {
+      const source = createActiveRouteSource(
+        this.router,
+        this.routeName(),
+        this.routeParams(),
+        buildActiveRouteOptions(
+          this.activeStrict(),
+          this.ignoreQueryParams(),
+          undefined,
+        ),
+      );
 
-    const unsub = source.subscribe(() => {
-      this.isActive.set(source.getSnapshot());
-      this.updateClass();
-    });
+      onCleanup(
+        subscribeSourceToSignal(source, (snap) => {
+          if (snap === this.prevActive) {
+            return;
+          }
 
-    this.destroyRef.onDestroy(() => {
-      unsub();
-      source.destroy();
+          this.prevActive = snap;
+          this.isActive.set(snap);
+          this.updateClass();
+        }),
+      );
     });
   }
 

package/src/dom-utils/link-utils.ts

@@ -15,14 +15,41 @@ export function shouldNavigate(evt: MouseEvent): boolean {
   );
 }
 
+// Matches a single percent-escape triple (`%` + two hex digits). Used as
+// the "already-encoded" probe in `encodeFragmentInline` below — see the
+// idempotency rationale there.
+const PERCENT_ESCAPE_PROBE = /%[\dA-Fa-f]{2}/;
+
 /**
  * RFC 3986 fragment encoding: preserve sub-delims (`&`, `=`, `?`, `:`),
  * encode space, `%`, control chars, non-ASCII via encodeURI; defensively
  * escape `#` (encodeURI does not). Mirrors `encodeHashFragment` in
  * `shared/browser-env/url-context.ts` — duplicated here because the
  * shared/dom-utils symlink graph does not reach shared/browser-env.
+ *
+ * **Idempotency for pre-encoded input (audit-2026-05-17 §5 MEDIUM E.1).**
+ * The doc-comment on `<Link hash>` says the value is a "decoded fragment
+ * without leading #". But realistic consumers copy hashes out of
+ * `location.hash` (which is percent-encoded) and pass them back, so the
+ * naive `encodeURI("%20")` would double-encode into `"%2520"` and break
+ * anchor lookup. We detect a percent-escape triple in the input and, if
+ * present, decode + re-encode for idempotency. Malformed `%XX` (e.g.
+ * `"%2"` or `"%ZZ"`) makes `decodeURIComponent` throw — in that case we
+ * fall through to plain `encodeURI`, which never throws.
  */
 function encodeFragmentInline(decoded: string): string {
+  if (PERCENT_ESCAPE_PROBE.test(decoded)) {
+    try {
+      const roundtrip = decodeURIComponent(decoded);
+
+      return encodeURI(roundtrip).replaceAll("#", "%23");
+    } catch {
+      // Malformed `%XX` — fall through to the plain encoding path.
+      // encodeURI does not throw on malformed escapes; it treats the
+      // `%` as a literal and percent-encodes it (`%2` → `%252`).
+    }
+  }
+
   return encodeURI(decoded).replaceAll("#", "%23");
 }
 
@@ -68,13 +95,34 @@ export function buildHref(
         normHash === undefined ? undefined : { hash: normHash },
       );
 
-      if (url !== undefined) {
+      // Accept only non-empty strings. The BuildUrlFn type contract is
+      // `string | undefined`, but defensive against:
+      //   - `""` (empty string) → would render `<a href="">`, which resolves
+      //     to the current page URL → silent self-navigation on click.
+      //   - `null` (type-contract violation) → would render `<a href={null}>`,
+      //     stringified to `"null"` in some renderers.
+      // Either case falls through to the `router.buildPath` fallback below.
+      if (typeof url === "string" && url.length > 0) {
         return url;
       }
     }
 
     const path = router.buildPath(routeName, routeParams);
 
+    // Symmetric to the buildUrl guard above (#S1 audit, Invariant 12).
+    // `router.buildPath` is typed `string`, but defends against:
+    //   - `""` (empty string) — would render `<a href="">`, which resolves
+    //     to the current page URL → silent self-navigation on click.
+    //   - non-string type-contract violations from custom path-matchers.
+    // Both yield `undefined` (renderer drops the attribute) with a warning.
+    if (typeof path !== "string" || path.length === 0) {
+      console.error(
+        `[real-router] Route "${routeName}" yielded an empty path. The element will render without an href attribute.`,
+      );
+
+      return undefined;
+    }
+
     return normHash ? `${path}#${encodeFragmentInline(normHash)}` : path;
   } catch {
     console.error(
@@ -144,8 +192,28 @@ export function navigateWithHash(
   return router.navigate(routeName, routeParams, opts);
 }
 
+// Match-any-whitespace regex shared across calls. RegExp literals at
+// call-site recompile in some engines; lifting it avoids that microcost
+// for the slow-path branch.
+const WHITESPACE_PROBE = /\s/;
+const WHITESPACE_SPLIT = /\S+/g;
+
 function parseTokens(value: string | undefined): string[] {
-  return value ? (value.match(/\S+/g) ?? []) : [];
+  if (!value) {
+    return [];
+  }
+
+  // Hot-path fast-path (audit-2026-05-17 §8b #1): >99% of active-class
+  // inputs at `<Link>` emit are single-token strings like `"active"` or
+  // `"is-current"` — no whitespace, no leading/trailing pad. Skip the
+  // regex match and Array result allocation: a literal `[value]` works
+  // because the slow-path `match(/\S+/g)` would return exactly `[value]`
+  // for the same input. PBT lock: linkUtils.properties.ts Invariant 13.
+  if (!WHITESPACE_PROBE.test(value)) {
+    return [value];
+  }
+
+  return value.match(WHITESPACE_SPLIT) ?? [];
 }
 
 export function buildActiveClassName(
@@ -179,6 +247,29 @@ export function buildActiveClassName(
   return baseClassName ?? undefined;
 }
 
+/**
+ * One-level structural equality using `Object.is` per key.
+ *
+ * **String-keyed properties only (Mini-sprint E.3 — audit-5 §4.2 #3).**
+ * Implementation walks `Object.keys()` which by spec returns only
+ * enumerable own STRING keys. Symbol-keyed properties — created via
+ * `obj[Symbol("brand")] = value` or `{ [Symbol(...)]: value }` — are
+ * NOT compared. Two records that differ only in a Symbol-keyed value
+ * will compare as equal.
+ *
+ * This is intentional: route params and Link options are documented as
+ * string-keyed primitives (string | number | boolean) — Symbol-keyed
+ * metadata (e.g. brand markers, private state) doesn't belong in a
+ * cache-key comparison. Switching to `Reflect.ownKeys()` would extend
+ * the contract to symbols at the cost of one extra allocation per call
+ * (Reflect.ownKeys composes string-keys + symbol-keys arrays). If a
+ * consumer relies on symbol-keyed metadata for navigation
+ * disambiguation, they should encode it into a string key instead.
+ *
+ * Mirrors React's `shallowEqual` (packages/shared/shallowEqual.js) in
+ * both the string-keys-only semantics and the `hasOwnProperty` guard
+ * below.
+ */
 export function shallowEqual(
   prev: object | undefined,
   next: object | undefined,
@@ -200,7 +291,13 @@ export function shallowEqual(
   const nextRecord = next as Record<string, unknown>;
 
   for (const key of prevKeys) {
-    if (!Object.is(prevRecord[key], nextRecord[key])) {
+    // hasOwnProperty guard: without it, a key missing in `next` reads as
+    // `undefined` and falsely matches `prev[key] === undefined`. Same shape
+    // as React's shallowEqual (packages/shared/shallowEqual.js).
+    if (
+      !Object.prototype.hasOwnProperty.call(next, key) ||
+      !Object.is(prevRecord[key], nextRecord[key])
+    ) {
       return false;
     }
   }
@@ -212,10 +309,25 @@ export function applyLinkA11y(element: HTMLElement | null | undefined): void {
   if (!element) {
     return;
   }
-  if (
-    element instanceof HTMLAnchorElement ||
-    element instanceof HTMLButtonElement
-  ) {
+
+  // Cross-realm safety (audit-2026-05-17 §5 HIGH #4):
+  // `instanceof HTMLAnchorElement` compares against the constructor from
+  // the CURRENT realm. An element created in a different window (iframe
+  // contentDocument, micro-frontend, embedded widget) fails the check
+  // even when it IS a real anchor — the helper would then inject
+  // role="link" + tabindex="0" on top of native anchor semantics,
+  // breaking screen reader output ("link link") and focus order.
+  //
+  // tagName is realm-agnostic and is uppercase for HTML-namespaced
+  // elements in any document. SVG `<a>` has lowercase tagName plus a
+  // different prototype (SVGAElement) — skipping it here is wrong by
+  // accident: SVG anchors don't have keyboard activation semantics the
+  // helper would add. But they also don't reach this helper in
+  // practice (router Link components emit HTML anchors). Lock the
+  // uppercase compare to keep the contract narrow.
+  const tag = element.tagName;
+
+  if (tag === "A" || tag === "BUTTON") {
     return;
   }
   if (!element.hasAttribute("role")) {