fix: improve route handling on hmr updates

Author: NathanWalker

packages/angular/src/lib/legacy/router/hmr-route-state-core.ts

@@ -222,6 +222,27 @@ export function clearAngularHmrRouteHistory(): void {
   delete g[HISTORY_KEY];
 }
 
+/**
+ * Replace the entire live back-stack mirror with a single URL. Mirrors
+ * NativeScript's `clearHistory: true` navigation option, which collapses
+ * the native page stack down to the destination — without this, the HMR
+ * snapshot would still carry every URL the user passed through before
+ * the reset (e.g. login screens that auth-gates now hide), and the next
+ * reboot would walk through every one of them as a forward navigation.
+ *
+ * An empty / unparseable `value` clears the mirror entirely.
+ */
+export function resetAngularHmrRouteHistoryToUrl(value: unknown): string | null {
+  const url = normalizeAngularHmrRouteUrl(value);
+  if (!url) {
+    writeHistoryArray(HISTORY_KEY, []);
+    return null;
+  }
+
+  writeHistoryArray(HISTORY_KEY, [url]);
+  return url;
+}
+
 /**
  * Snapshot the live back-stack mirror under the pending-history slot so the
  * next bootstrap can read it. Called from the HMR capture hook.

packages/angular/src/lib/legacy/router/hmr-route-state-tracker.spec.ts

@@ -46,22 +46,37 @@ interface RouterEvent {
 interface RouterMock {
   events: Subject<RouterEvent>;
   url: string;
+  // Mirrors `Router.getCurrentNavigation()` enough that the tracker can read
+  // `extras.clearHistory` off it — the same hook NS's page-router-outlet uses
+  // to enable `clearHistory: true` end-to-end.
+  currentNavigation: { extras?: { clearHistory?: boolean } } | null;
+  getCurrentNavigation(): { extras?: { clearHistory?: boolean } } | null;
   emitNavigationEnd(url: string): void;
   emitNavigationStart(
     url: string,
     options?: {
       trigger?: 'imperative' | 'popstate' | 'hashchange';
       restoredState?: { navigationId: number } | null;
+      clearHistory?: boolean;
     },
   ): void;
 }
 
 function createRouterMock(initialUrl: string): RouterMock {
   const events = new Subject<RouterEvent>();
-  return {
+  const router: RouterMock = {
     events,
     url: initialUrl,
+    currentNavigation: null,
+    getCurrentNavigation() {
+      return this.currentNavigation;
+    },
     emitNavigationStart(url, options) {
+      // Mirror Angular: `getCurrentNavigation()` returns the active navigation
+      // between NavigationStart and NavigationEnd, then is cleared.
+      this.currentNavigation = {
+        extras: options?.clearHistory ? { clearHistory: true } : {},
+      };
       events.next(
         new MockNavigationStart(
           1,
@@ -74,8 +89,10 @@ function createRouterMock(initialUrl: string): RouterMock {
     emitNavigationEnd(url) {
       this.url = url;
       events.next(new MockNavigationEnd(1, url, url) as unknown as RouterEvent);
+      this.currentNavigation = null;
     },
   };
+  return router;
 }
 
 describe('NativeScriptAngularHmrRouteTracker', () => {
@@ -170,6 +187,74 @@ describe('NativeScriptAngularHmrRouteTracker', () => {
     });
   });
 
+  describe('clearHistory navigation extra', () => {
+    it('collapses the live mirror to the destination URL when clearHistory is set', () => {
+      // Reproduces the canonical HeyKiddo auth flow: user passes through
+      // /signup-landing, /login on the way to a clearHistory navigation
+      // that drops the iOS back-stack down to /talk. Without mirroring
+      // that on the HMR side, a subsequent .ts edit replays NavigationEnd
+      // for every URL the user passed through — including login pages
+      // that the auth-gate now redirects away from.
+      const router = createRouterMock('/');
+
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const tracker = new NativeScriptAngularHmrRouteTracker(router as never);
+
+      router.emitNavigationStart('/signup-landing');
+      router.emitNavigationEnd('/signup-landing');
+      router.emitNavigationStart('/login');
+      router.emitNavigationEnd('/login');
+
+      expect(readAngularHmrRouteHistory()).toEqual(['/signup-landing', '/login']);
+
+      router.emitNavigationStart('/talk/(todayTab:today)', { clearHistory: true });
+      router.emitNavigationEnd('/talk/(todayTab:today)');
+
+      expect(readAngularHmrRouteHistory()).toEqual(['/talk/(todayTab:today)']);
+    });
+
+    it('keeps subsequent non-clearHistory navigations on top of the destination after a reset', () => {
+      // After a clearHistory reset, normal forward navigation (e.g. tab
+      // switches) should still grow the mirror so the back-stack is
+      // restored across HMR cycles for the post-reset session.
+      const router = createRouterMock('/');
+
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const tracker = new NativeScriptAngularHmrRouteTracker(router as never);
+
+      router.emitNavigationStart('/login');
+      router.emitNavigationEnd('/login');
+      router.emitNavigationStart('/talk/(todayTab:today)', { clearHistory: true });
+      router.emitNavigationEnd('/talk/(todayTab:today)');
+      router.emitNavigationStart('/talk/(progressTab:progress//todayTab:today)');
+      router.emitNavigationEnd('/talk/(progressTab:progress//todayTab:today)');
+
+      expect(readAngularHmrRouteHistory()).toEqual([
+        '/talk/(todayTab:today)',
+        '/talk/(progressTab:progress//todayTab:today)',
+      ]);
+    });
+
+    it('does not throw when the router mock omits getCurrentNavigation', () => {
+      // Defensive: the tracker should fall back to the legacy push path on
+      // routers that don't expose `getCurrentNavigation()`. This protects
+      // older Angular versions, edge-case mocks, and hardened proxy wrappers
+      // that strip non-public methods.
+      const router = createRouterMock('/');
+      // Force a router shape without the API; the tracker must treat it
+      // as "no clearHistory".
+      (router as { getCurrentNavigation?: unknown }).getCurrentNavigation = undefined;
+
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const tracker = new NativeScriptAngularHmrRouteTracker(router as never);
+
+      router.emitNavigationStart('/login', { clearHistory: true });
+      router.emitNavigationEnd('/login');
+
+      expect(readAngularHmrRouteHistory()).toEqual(['/login']);
+    });
+  });
+
   describe('clear-after-snapshot integration', () => {
     it('a snapshot during HMR reboot leaves the live mirror empty for the next bootstrap to rebuild', () => {
       // Cycle 1: real boot, walk forward to /profile.

packages/angular/src/lib/legacy/router/hmr-route-state.spec.ts

@@ -16,6 +16,7 @@ import {
   readAngularHmrPendingStartPath,
   readAngularHmrRouteHistory,
   replaceAngularHmrRouteHistoryTop,
+  resetAngularHmrRouteHistoryToUrl,
   snapshotAngularHmrRouteHistory,
   writeAngularHmrRouteState,
 } from './hmr-route-state-core';
@@ -101,6 +102,26 @@ describe('Angular HMR route state', () => {
       expect(readAngularHmrRouteHistory()).toEqual(['/talk/(todayTab:today)', '/profile?tab=goals']);
     });
 
+    it('collapses the live mirror to a single URL on a clearHistory navigation', () => {
+      // Mirrors NativeScript's `clearHistory: true` extra: the user-visible
+      // back-stack is reset to just the destination, so the HMR mirror
+      // must follow suit.
+      pushAngularHmrRouteHistoryEntry('/');
+      pushAngularHmrRouteHistoryEntry('/signup-landing');
+      pushAngularHmrRouteHistoryEntry('/login');
+
+      expect(resetAngularHmrRouteHistoryToUrl('/talk/(todayTab:today)')).toBe('/talk/(todayTab:today)');
+      expect(readAngularHmrRouteHistory()).toEqual(['/talk/(todayTab:today)']);
+    });
+
+    it('clears the live mirror entirely when reset is called with an unparseable URL', () => {
+      pushAngularHmrRouteHistoryEntry('/talk/(todayTab:today)');
+      pushAngularHmrRouteHistoryEntry('/profile');
+
+      expect(resetAngularHmrRouteHistoryToUrl(undefined)).toBeNull();
+      expect(readAngularHmrRouteHistory()).toEqual([]);
+    });
+
     it('snapshots the live mirror into the pending slot for the next bootstrap', () => {
       pushAngularHmrRouteHistoryEntry('/talk/(todayTab:today)');
       pushAngularHmrRouteHistoryEntry('/profile');

packages/angular/src/lib/legacy/router/hmr-route-state.ts

@@ -9,6 +9,7 @@ import {
   pushAngularHmrRouteHistoryEntry,
   readAngularHmrPendingStartPath,
   replaceAngularHmrRouteHistoryTop,
+  resetAngularHmrRouteHistoryToUrl,
   snapshotAngularHmrRouteHistory,
   writeAngularHmrRouteState,
 } from './hmr-route-state-core';
@@ -29,10 +30,41 @@ export {
   readAngularHmrPendingRouteHistory,
   readAngularHmrRouteHistory,
   replaceAngularHmrRouteHistoryTop,
+  resetAngularHmrRouteHistoryToUrl,
   snapshotAngularHmrRouteHistory,
 } from './hmr-route-state-core';
 export { readAngularHmrPendingStartPath } from './hmr-route-state-core';
 
+/**
+ * Read NativeScript's `clearHistory: true` navigation extra off the active
+ * Angular navigation. Defensive against test mocks and bare `Router`-like
+ * shapes that don't expose `getCurrentNavigation` (e.g. earlier Angular
+ * versions and the unit-test mocks in `hmr-route-state-tracker.spec.ts`).
+ *
+ * `clearHistory` is the NativeScript-only signal that
+ * `NSLocationStrategy._beginPageNavigation` uses to collapse the native page
+ * stack down to the destination. We mirror that on the HMR side so a
+ * subsequent reboot doesn't replay URLs the user can no longer reach (the
+ * canonical example: `/`, `/signup-landing`, `/login` after the auth flow
+ * navigated to `/talk/(todayTab:today)` with `clearHistory: true`).
+ */
+function readClearHistoryFromRouter(router: Router): boolean {
+  const getCurrentNavigation = (router as { getCurrentNavigation?: () => unknown }).getCurrentNavigation;
+  if (typeof getCurrentNavigation !== 'function') {
+    return false;
+  }
+
+  let navigation: unknown;
+  try {
+    navigation = getCurrentNavigation.call(router);
+  } catch {
+    return false;
+  }
+
+  const extras = (navigation as { extras?: { clearHistory?: unknown } } | null | undefined)?.extras;
+  return !!extras?.clearHistory;
+}
+
 @Injectable()
 export class NativeScriptAngularHmrRouteTracker implements OnDestroy {
   private subscription?: Subscription;
@@ -42,6 +74,12 @@ export class NativeScriptAngularHmrRouteTracker implements OnDestroy {
   // `NavigationEnd` we can pop our mirror instead of pushing a duplicate entry.
   private currentNavigationIsPopstate = false;
   private currentNavigationReplaceUrl = false;
+  // Tracks whether the active navigation was started with NativeScript's
+  // `clearHistory: true` extra (read off `router.getCurrentNavigation()` at
+  // `NavigationStart`). When set, the matching `NavigationEnd` collapses the
+  // mirror down to just the destination URL — see
+  // `resetAngularHmrRouteHistoryToUrl` for the rationale.
+  private currentNavigationClearsHistory = false;
 
   constructor(private readonly router: Router) {
     if (!isAngularHmrEnabled()) {
@@ -54,6 +92,7 @@ export class NativeScriptAngularHmrRouteTracker implements OnDestroy {
       if (event instanceof NavigationStart) {
         this.currentNavigationIsPopstate = event.navigationTrigger === 'popstate';
         this.currentNavigationReplaceUrl = !!event.restoredState;
+        this.currentNavigationClearsHistory = readClearHistoryFromRouter(this.router);
         return;
       }
 
@@ -63,7 +102,13 @@ export class NativeScriptAngularHmrRouteTracker implements OnDestroy {
           source: 'navigation-end',
         });
 
-        if (this.currentNavigationIsPopstate) {
+        if (this.currentNavigationClearsHistory) {
+          // NativeScript collapsed the native page stack to this single
+          // destination. Mirror that on the HMR side so a future reboot
+          // replays only what the user can still navigate back through —
+          // not every URL they passed through before the reset.
+          resetAngularHmrRouteHistoryToUrl(url);
+        } else if (this.currentNavigationIsPopstate) {
           // The user (or NSLocationStrategy.back()) walked the back-stack down
           // by one page; mirror that by dropping the top of our snapshot so a
           // subsequent HMR reboot doesn't carry the popped page back into view.
@@ -76,6 +121,7 @@ export class NativeScriptAngularHmrRouteTracker implements OnDestroy {
 
         this.currentNavigationIsPopstate = false;
         this.currentNavigationReplaceUrl = false;
+        this.currentNavigationClearsHistory = false;
       }
     });
   }