feat: hmr handling with modals and route preservation

Author: NathanWalker

packages/angular/src/lib/application.ts

@@ -13,7 +13,7 @@ import {
   Utils,
   View,
 } from '@nativescript/core';
-import { Observable, Subject } from 'rxjs';
+import { Observable, ReplaySubject, Subject } from 'rxjs';
 import { filter, map, take } from 'rxjs/operators';
 import { AppHostView } from './app-host-view';
 import {
@@ -22,6 +22,8 @@ import {
   resetAngularHmrCompiledComponents,
   setAngularCoreForHmr,
 } from './hmr-compiled-components-core';
+import { _hmrDiagBumpCycle, installAngularHmrComponentRegistrar } from './hmr-class-registry';
+import { installHmrEagerRegistrar, runHmrEagerInstantiators } from './hmr-eager-services';
 import { NativeScriptLoadingService } from './loading.service';
 import { clearAngularHmrRouteConfigCaches } from './legacy/router/hmr-route-cache-core';
 import { NSLocationStrategy } from './legacy/router/ns-location-strategy';
@@ -35,8 +37,30 @@ import { NativeScriptDebug } from './trace';
 // We need to use the original one that has the registered LViews
 rememberAngularCoreForHmr(AngularCore as any, globalThis as any);
 
+// Install the cross-module HMR component registrar. The Vite plugin
+// `ns-component-hmr-register` injects a call to the global hook
+// `__NS_HMR_REGISTER_COMPONENT__` at the end of every user `.ts` file
+// that declares an `@Component`-decorated class. After an HMR reboot,
+// each re-evaluated module pushes its fresh class into the registry,
+// and HMR helpers (modal restore, route replay) read the registry via
+// `getFreshComponentClass` to re-attach to the *live* class instead of
+// a captured stale reference. Production short-circuits inside the
+// helper (the hook is never assigned).
+//
+// We install the registrar before any other module initialization can
+// reference the hook so a user module loaded synchronously alongside
+// `@nativescript/angular` always finds the function present.
+installAngularHmrComponentRegistrar();
+
+// Install the cross-module registration entry point used by HMR-aware
+// services (e.g. `NativeDialog`) to ask for eager construction after
+// every bootstrap. Idempotent: re-evaluations after HMR are no-ops.
+installHmrEagerRegistrar();
+
 const angularHmrGlobal = globalThis as any;
-angularHmrGlobal.__NS_REMEMBER_ANGULAR_CORE__ = (core: any) => setAngularCoreForHmr(core, angularHmrGlobal);
+angularHmrGlobal.__NS_REMEMBER_ANGULAR_CORE__ = (core: any) => {
+  setAngularCoreForHmr(core, angularHmrGlobal);
+};
 
 export interface AppLaunchView extends LayoutBase {
   // called when the animation is to begin
@@ -68,7 +92,17 @@ export type NgModuleEvent =
     };
 
 export const preAngularDisposal$ = new Subject<NgModuleEvent>();
-export const postAngularBootstrap$ = new Subject<NgModuleEvent>();
+/**
+ * Stream that emits when an Angular module finishes bootstrapping. Modeled
+ * as a `ReplaySubject(1)` so consumers (e.g. `NativeDialog`) instantiated
+ * lazily — *after* the bootstrap event has already fired — still receive
+ * the latest event and can react. Without buffering, a service that the
+ * user app injects on first need (after bootstrap) would silently miss the
+ * `hotreload` notification and skip HMR-only work like restoring captured
+ * modal state. The buffer size of 1 means each new HMR cycle replaces the
+ * cached event so cycle N's late subscribers don't see cycle N-1's event.
+ */
+export const postAngularBootstrap$ = new ReplaySubject<NgModuleEvent>(1);
 
 /**
  * @deprecated
@@ -127,17 +161,33 @@ function emitModuleBootstrapEvent<T>(
   name: 'main' | 'loading',
   reason: NgModuleReason,
 ) {
+  console.info(`[ns-hmr-diag][application] emitModuleBootstrapEvent name=${name} reason=${reason}`);
+  // Instantiate registered HMR-aware services *before* emitting so they
+  // attach their subscriptions in the same JS task and are guaranteed to
+  // observe the event being emitted. `postAngularBootstrap$` is also a
+  // `ReplaySubject(1)`, so a service injected later still receives the
+  // buffered event — the eager pass is the fast path that lets the
+  // restore work begin in the same task as bootstrap completion.
+  if (name === 'main') {
+    runHmrEagerInstantiators(
+      (ref as ApplicationRef | NgModuleRef<T>).injector,
+      (err) => NativeScriptDebug.bootstrapLogError(`HMR eager instantiator threw: ${(err as Error)?.message ?? err}`),
+    );
+  }
   postAngularBootstrap$.next({
     moduleType: name,
     reference: ref,
     reason,
   });
+  console.info(`[ns-hmr-diag][application] postAngularBootstrap$.next() emitted name=${name} reason=${reason}`);
 }
 
 function destroyRef<T>(ref: NgModuleRef<T> | ApplicationRef, name: 'main' | 'loading', reason: NgModuleReason): void;
 function destroyRef(ref: PlatformRef, reason: NgModuleReason): void;
 function destroyRef<T>(ref: PlatformRef | ApplicationRef | NgModuleRef<T>, name?: string, reason?: string): void {
   if (ref) {
+    const refKind = ref instanceof PlatformRef ? 'PlatformRef' : ref instanceof NgModuleRef ? 'NgModuleRef' : ref instanceof ApplicationRef ? 'ApplicationRef' : '(unknown)';
+    console.info(`[ns-hmr-diag][application] destroyRef kind=${refKind} name=${name ?? '(none)'} reason=${reason ?? '(none)'}`);
     if (ref instanceof PlatformRef) {
       preAngularDisposal$.next({
         moduleType: 'platform',
@@ -153,6 +203,7 @@ function destroyRef<T>(ref: PlatformRef | ApplicationRef | NgModuleRef<T>, name?
       });
     }
     ref.destroy();
+    console.info(`[ns-hmr-diag][application] destroyRef DONE kind=${refKind} name=${name ?? '(none)'}`);
   }
 }
 
@@ -690,6 +741,11 @@ export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
     disposePlatform('hotreload');
   };
   global['__reboot_ng_modules__'] = (shouldDisposePlatform: boolean = false) => {
+    // Diagnostic: bump the global HMR cycle counter so all subsequent
+    // log lines (class registry, dialog services) can be cross-
+    // referenced to a specific reboot.
+    const cycleNum = _hmrDiagBumpCycle();
+    console.info(`[ns-hmr-diag][application] __reboot_ng_modules__ called cycle=${cycleNum} shouldDisposePlatform=${shouldDisposePlatform} bootstrapId=${bootstrapId} hasMainModuleRef=${!!mainModuleRef}`);
     const traceEnabled = NativeScriptDebug.isLogEnabled();
     if (traceEnabled) {
       NativeScriptDebug.hmrLog(
@@ -700,6 +756,7 @@ export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
       global['__NS_CAPTURE_ANGULAR_HMR_ROUTE__']?.();
     } catch {}
     disposeLastModules('hotreload');
+    console.info(`[ns-hmr-diag][application] after disposeLastModules cycle=${cycleNum} bootstrapId=${bootstrapId}`);
     if (traceEnabled) {
       NativeScriptDebug.hmrLog(`after disposeLastModules bootstrapId=${bootstrapId}`);
     }
@@ -709,7 +766,9 @@ export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
     if (traceEnabled) {
       NativeScriptDebug.hmrLog('calling bootstrapRoot');
     }
+    console.info(`[ns-hmr-diag][application] calling bootstrapRoot cycle=${cycleNum}`);
     bootstrapRoot('hotreload');
+    console.info(`[ns-hmr-diag][application] bootstrapRoot returned cycle=${cycleNum} bootstrapId=${bootstrapId}`);
     if (traceEnabled) {
       NativeScriptDebug.hmrLog(`bootstrapRoot returned bootstrapId=${bootstrapId}`);
     }

packages/angular/src/lib/cdk/dialog/dialog-config.ts

@@ -49,5 +49,22 @@ export class NativeDialogConfig<D = any> {
 
   nativeOptions?: NativeShowModalOptions = {};
 
+  /**
+   * When true, this dialog will be re-opened automatically on Angular HMR
+   * reboots so the user does not lose context every time a related file
+   * changes. The new dialog reuses the same component class and `data` payload
+   * (provided via `data`); other config such as `nativeOptions` is preserved
+   * verbatim.
+   *
+   * The original `dialogRef.afterClosed()` subject is wired to the restored
+   * dialog so consumers `await openModal(...)` resolve normally when the user
+   * eventually closes the restored modal.
+   *
+   * Only opens via component class are restorable — `TemplateRef` openings
+   * carry references that don't survive an HMR reboot and are silently
+   * skipped. Has no effect outside of HMR.
+   */
+  preserveOnHmr?: boolean = false;
+
   // TODO(jelbourn): add configuration for lifecycle hooks, ARIA labelling.
 }

packages/angular/src/lib/cdk/dialog/dialog-hmr-animation.spec.ts

@@ -0,0 +1,123 @@
+import { NativeDialogConfig } from './dialog-config';
+import { buildNonAnimatedRestoreConfig, suppressNativeCloseAnimation } from './dialog-hmr-animation';
+import { HmrCandidateDialog } from './dialog-hmr';
+
+class StubComponent {}
+
+function makeCandidate(opts: {
+  parentView?: { _modalAnimatedOptions?: boolean[] };
+  preserveOnHmr?: boolean;
+}): HmrCandidateDialog {
+  const config = new NativeDialogConfig();
+  config.preserveOnHmr = opts.preserveOnHmr ?? true;
+  const ref: unknown = {
+    _nativeModalRef: opts.parentView ? { parentView: opts.parentView } : undefined,
+  };
+  return {
+    ref: ref as HmrCandidateDialog['ref'],
+    componentClass: StubComponent as unknown as HmrCandidateDialog['componentClass'],
+    config,
+  };
+}
+
+describe('NativeDialog HMR animation helpers', () => {
+  describe('suppressNativeCloseAnimation', () => {
+    it('flips the top of the parent view animated stack to false so the next dismiss is un-animated', () => {
+      const stack: boolean[] = [true];
+      const candidate = makeCandidate({ parentView: { _modalAnimatedOptions: stack } });
+
+      suppressNativeCloseAnimation(candidate);
+
+      expect(stack).toEqual([false]);
+    });
+
+    it('only mutates the top entry so deeper presentations stay untouched', () => {
+      const stack: boolean[] = [true, true];
+      const candidate = makeCandidate({ parentView: { _modalAnimatedOptions: stack } });
+
+      suppressNativeCloseAnimation(candidate);
+
+      // The dismiss reads `slice(-1)[0]`; deeper entries belong to other
+      // open modals on the same parent view and must stay animated.
+      expect(stack).toEqual([true, false]);
+    });
+
+    it('skips the mutation when the candidate did not opt into preservation', () => {
+      const stack: boolean[] = [true];
+      const candidate = makeCandidate({
+        parentView: { _modalAnimatedOptions: stack },
+        preserveOnHmr: false,
+      });
+
+      suppressNativeCloseAnimation(candidate);
+
+      expect(stack).toEqual([true]);
+    });
+
+    it('is a no-op when the underlying native modal ref is missing', () => {
+      const candidate = makeCandidate({ parentView: undefined });
+
+      expect(() => suppressNativeCloseAnimation(candidate)).not.toThrow();
+    });
+
+    it('is a no-op when the parent view exposes no animated stack', () => {
+      const candidate = makeCandidate({ parentView: {} });
+
+      expect(() => suppressNativeCloseAnimation(candidate)).not.toThrow();
+    });
+
+    it('is a no-op when the animated stack is present but empty', () => {
+      const candidate = makeCandidate({ parentView: { _modalAnimatedOptions: [] } });
+
+      expect(() => suppressNativeCloseAnimation(candidate)).not.toThrow();
+    });
+  });
+
+  describe('buildNonAnimatedRestoreConfig', () => {
+    it('returns a NativeDialogConfig with nativeOptions.animated forced to false', () => {
+      const original = new NativeDialogConfig();
+      original.nativeOptions = { animated: true, fullscreen: true } as never;
+
+      const restore = buildNonAnimatedRestoreConfig(original);
+
+      expect((restore.nativeOptions as Record<string, unknown>)?.animated).toBe(false);
+      expect((restore.nativeOptions as Record<string, unknown>)?.fullscreen).toBe(true);
+    });
+
+    it('does not mutate the original config so cached references stay intact', () => {
+      const original = new NativeDialogConfig();
+      original.nativeOptions = { animated: true } as never;
+
+      const restore = buildNonAnimatedRestoreConfig(original);
+
+      expect(restore).not.toBe(original);
+      expect((original.nativeOptions as Record<string, unknown>)?.animated).toBe(true);
+    });
+
+    it('synthesises a nativeOptions object when the original config has none', () => {
+      const original = new NativeDialogConfig();
+      // Default config initialiser sets nativeOptions to {}, replicate
+      // the shape projects produce when they explicitly set it to
+      // undefined for some opens.
+      original.nativeOptions = undefined;
+
+      const restore = buildNonAnimatedRestoreConfig(original);
+
+      expect(restore.nativeOptions).toEqual({ animated: false });
+      expect(original.nativeOptions).toBeUndefined();
+    });
+
+    it('preserves the rest of the captured config (data, id, preserveOnHmr) so the reopened modal looks identical to the user', () => {
+      const original = new NativeDialogConfig();
+      original.id = 'resource-modal';
+      original.data = { resourceId: 42 };
+      original.preserveOnHmr = true;
+
+      const restore = buildNonAnimatedRestoreConfig(original);
+
+      expect(restore.id).toBe('resource-modal');
+      expect(restore.data).toEqual({ resourceId: 42 });
+      expect(restore.preserveOnHmr).toBe(true);
+    });
+  });
+});

packages/angular/src/lib/cdk/dialog/dialog-hmr-animation.ts

@@ -0,0 +1,62 @@
+import { NativeDialogConfig } from './dialog-config';
+import { HmrCandidateDialog } from './dialog-hmr';
+
+/**
+ * Best-effort animation helpers used by the dialog HMR layer to make
+ * the close + reopen round-trip feel like an in-place content refresh.
+ *
+ * They live in a tiny standalone module on purpose:
+ *
+ * - `dialog-services.ts` pulls in `@angular/core`, which Jest cannot
+ *   load in our spec runner without an extra ESM transform. By
+ *   keeping these helpers free of `@angular/core` we can unit-test
+ *   them in isolation (`dialog-hmr-animation.spec.ts`) while
+ *   `dialog-services.ts` re-exports them at the public API layer.
+ * - The helpers are inherently best-effort: a missing
+ *   `_nativeModalRef`, a frozen `_modalAnimatedOptions` stack, or a
+ *   future `NativeDialogConfig` shape change must never break HMR
+ *   restore — we just fall back to the original animated behavior.
+ */
+
+/**
+ * Mutate the top of `parentView._modalAnimatedOptions` to `false` for
+ * the given candidate so the imminent native close runs un-animated.
+ *
+ * iOS reads `_modalAnimatedOptions.slice(-1)[0]` when dismissing a
+ * modal (see core `view-common.ts` / `view/index.ios.ts`). The
+ * Angular dialog service only pushes one entry per open call, so the
+ * top entry is the exact flag that controls the dismiss we're about
+ * to trigger as part of the HMR root-view replacement.
+ */
+export function suppressNativeCloseAnimation(candidate: HmrCandidateDialog): void {
+  if (!candidate.config?.preserveOnHmr) {
+    return;
+  }
+  try {
+    const modalRef = (candidate.ref as unknown as { _nativeModalRef?: { parentView?: unknown } })?._nativeModalRef;
+    const parentView = modalRef?.parentView as { _modalAnimatedOptions?: boolean[] } | undefined;
+    const stack = parentView?._modalAnimatedOptions;
+    if (Array.isArray(stack) && stack.length > 0) {
+      stack[stack.length - 1] = false;
+    }
+  } catch {
+    // Swallow: a missing `_nativeModalRef` / `_modalAnimatedOptions`
+    // is acceptable — we just lose the no-animation optimisation.
+  }
+}
+
+/**
+ * Build a `NativeDialogConfig` clone of `original` whose
+ * `nativeOptions.animated` is forced to `false`. Used when re-opening
+ * a captured modal so the open animation matches the suppressed
+ * close — together they make the HMR round-trip feel like a content
+ * refresh instead of a close/reopen.
+ */
+export function buildNonAnimatedRestoreConfig(original: NativeDialogConfig): NativeDialogConfig {
+  // Clone via `Object.assign` so consumers holding the original
+  // config (e.g. caching it for re-open) don't see mutations from
+  // the HMR pathway.
+  const cloned = Object.assign(new NativeDialogConfig(), original) as NativeDialogConfig;
+  cloned.nativeOptions = { ...(original?.nativeOptions || {}), animated: false };
+  return cloned;
+}