@nativescript/angular 21.0.1-alpha.2 → 21.0.1-alpha.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nativescript/angular",
-  "version": "21.0.1-alpha.2",
+  "version": "21.0.1-alpha.4",
   "homepage": "https://nativescript.org/",
   "repository": {
     "type": "git",

package/types/nativescript-angular.d.ts

@@ -4,7 +4,7 @@ import * as i0 from '@angular/core';
 import { InjectionToken, EmbeddedViewRef, ComponentRef, NgModuleRef, ApplicationRef, Provider, EnvironmentProviders, PlatformRef, ɵNgModuleFactory as _NgModuleFactory, Type, CompilerOptions, NgZone, Injector, NgModuleFactory, StaticProvider, Sanitizer, ApplicationConfig as ApplicationConfig$1, ViewContainerRef, ComponentFactoryResolver, TemplateRef, ElementRef, OnInit, OnDestroy, Renderer2, EventEmitter, ChangeDetectorRef, ComponentFactory, AfterViewInit, OnChanges, SimpleChanges, DoCheck, AfterContentInit, IterableDiffer, IterableDiffers, ErrorHandler, RendererStyleFlags2, RendererType2, RendererFactory2, QueryList, EnvironmentInjector, ModuleWithProviders, NgZoneOptions } from '@angular/core';
 import * as _nativescript_angular from '@nativescript/angular';
 import * as rxjs from 'rxjs';
-import { Observable, Subject, BehaviorSubject } from 'rxjs';
+import { Observable, ReplaySubject, Subject, BehaviorSubject } from 'rxjs';
 import * as i1 from '@angular/common';
 import { LocationStrategy, XhrFactory } from '@angular/common';
 import * as i1$2 from '@angular/router';
@@ -170,7 +170,17 @@ type NgModuleEvent = {
     reason: NgModuleReason | string;
 };
 declare const preAngularDisposal$: Subject<NgModuleEvent>;
-declare const postAngularBootstrap$: 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.
+ */
+declare const postAngularBootstrap$: ReplaySubject<NgModuleEvent>;
 /**
  * @deprecated
  */
@@ -1084,6 +1094,22 @@ declare class NativeDialogConfig<D = any> {
     /** Alternate `ComponentFactoryResolver` to use when resolving the associated component. */
     componentFactoryResolver?: ComponentFactoryResolver;
     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;
 }
 
 declare class FrameService {
@@ -1195,6 +1221,16 @@ declare class NativeModalRef {
     portalOutlet: NativeScriptDomPortalOutlet;
     detachedLoaderRef: ComponentRef<DetachedLoader>;
     modalViewRef: NgViewRef<any>;
+    /**
+     * The actual NativeScript view passed to `parentView.showModal(...)`.
+     *
+     * For component portals this is the stable `targetView` ContentView
+     * wrapper that owns the Angular host PVC. For template portals it
+     * remains `modalViewRef.firstNativeLikeView` (the historical
+     * behavior). Keeping a direct reference avoids walking parent
+     * chains when programmatically closing the modal.
+     */
+    modalView?: View;
     private _closeCallback;
     private _isDismissed;
     constructor(_config: NativeDialogConfig, _injector: Injector, location?: NSLocationStrategy);
@@ -1283,9 +1319,24 @@ declare const NATIVE_DIALOG_DEFAULT_OPTIONS: InjectionToken<NativeDialogConfig<a
  * for arbitrary dialog refs and dialog container components.
  */
 declare class NativeDialog implements OnDestroy {
+    /**
+     * Diagnostic instance id. We tag each constructor with a number so
+     * the logs make it obvious when a stale `NativeDialog` keeps
+     * receiving events after a reboot (e.g. due to a leaked subscription
+     * or a service from a previous realm being kept alive).
+     */
+    private readonly _diagInstanceId;
     private _openDialogsAtThisLevel;
     private readonly _afterAllClosedAtThisLevel;
     private readonly _afterOpenedAtThisLevel;
+    /**
+     * Maps each open dialog ref back to the `(componentClass, config)` pair it
+     * was opened with so the HMR snapshot can replay the call later. Dialogs
+     * opened with a `TemplateRef` are tracked with `componentClass: undefined`
+     * — the HMR layer skips them automatically.
+     */
+    private readonly _openDialogMetadata;
+    private _hmrSubscriptions;
     /**
      * Stream that emits when all open dialog have finished closing.
      * Will emit on subscribe if there are no open dialogs to begin with.
@@ -1303,6 +1354,8 @@ declare class NativeDialog implements OnDestroy {
     private _nativeModalType;
     private _dialogDataToken;
     private locationStrategy;
+    private _diagInstanceIdAssign;
+    private _hmrInitMarker;
     /**
      * Opens a modal dialog containing the given component.
      * @param component Type of the component to load into the dialog.
@@ -1328,6 +1381,128 @@ declare class NativeDialog implements OnDestroy {
      */
     getDialogById(id: string): NativeDialogRef<any> | undefined;
     ngOnDestroy(): void;
+    /**
+     * Tracks whether a restore has already been scheduled for this
+     * `NativeDialog` instance's lifetime. We only need to restore once
+     * per HMR cycle — the rxjs `ReplaySubject(1)` for
+     * `postAngularBootstrap$` delivers both the *previous* cycle's
+     * cached event (replay on subscribe) **and** the *current* cycle's
+     * fresh event, and the constructor stash peek can independently
+     * notice pending work. Without this guard each of those triggers
+     * would queue its own `setTimeout` and the logs would show two or
+     * three "scheduling restore" lines per save.
+     *
+     * The guard is per-instance and the stash itself is the source of
+     * truth: `_restorePendingDialogs` calls `consumePendingHmrDialogs()`
+     * which atomically clears the stash, so even if the guard somehow
+     * fired twice, only the first call would do real work.
+     */
+    private _restoreScheduledForThisInstance;
+    /**
+     * Wires up HMR capture/restore. Only the root-level dialog manages the
+     * stash so a stack of `NativeDialog` instances inside a child injector
+     * doesn't fight for it.
+     *
+     * Production short-circuit: `isAngularHmrEnabled()` returns `false` in
+     * release builds and when no NS Vite / webpack HMR runtime is present,
+     * so the long-lived subscriptions below never attach in shipping apps.
+     *
+     * `postAngularBootstrap$` is a `ReplaySubject(1)` (see `application.ts`)
+     * which means a `NativeDialog` instantiated *after* the bootstrap event
+     * has already fired (typical when the user app injects `NativeDialog`
+     * lazily via a service like `view.service.ts`) still receives the
+     * buffered event and runs the restore path.
+     */
+    private _initHmrLifecycle;
+    /**
+     * Schedule a restore exactly once per `NativeDialog` instance.
+     *
+     * The work is deferred to the next macrotask for two reasons:
+     *
+     *  1. `postAngularBootstrap$.next(...)` is fired from inside
+     *     `emitModuleBootstrapEvent`, which itself runs inside the
+     *     `bootstrapApplication` callback — so the call stack still
+     *     contains Angular's ApplicationRef bootstrap pipeline. Doing
+     *     `this.open(...)` synchronously re-entered Angular DI while a
+     *     `providedIn: 'root'` factory could still be on the resolution
+     *     stack, which surfaced as `NG0200: Circular dependency detected
+     *     for NativeDialog`. Yielding to a macrotask lets the bootstrap
+     *     stack fully unwind first.
+     *  2. The eventual `parent.showModal(...)` cannot present onto a
+     *     view controller whose view is not yet in the iOS window
+     *     hierarchy (see `_scheduleRestoreOpenWhenReady` for the second
+     *     wait stage); a synchronous attempt would silently no-op
+     *     because iOS rejects the present without throwing.
+     */
+    private _maybeScheduleRestore;
+    private _captureOpenDialogsForHmr;
+    /**
+     * Per-cycle guard to keep `_restorePendingDialogs` idempotent if more
+     * than one subscriber fires for the same bootstrap event. The
+     * regression we have seen (`postAngularBootstrap$ → restore` logged
+     * twice in the same hot reload) was caused by the `NativeDialogModule`
+     * also listing `NativeDialog` in its `providers` array. That has been
+     * removed, but we keep this flag as a defensive net so a future stray
+     * subscription does not consume the stash twice. The flag is reset
+     * after the consume so subsequent HMR cycles can run their own
+     * restore.
+     */
+    private _restoreInFlight;
+    private _restorePendingDialogs;
+    /**
+     * Resolve the freshest known class object for the captured component
+     * name and re-open the dialog through the normal `open` path, but
+     * only once the new root view is actually attached to the iOS window
+     * hierarchy.
+     *
+     * Why a class lookup at all: an HMR reboot calls
+     * `ɵresetCompiledComponents()` which clears each component's `ɵcmp`
+     * field but **leaves the class identity unchanged**. The patched
+     * `ɵɵdefineComponent` then re-registers the same class object under
+     * the same source name when Angular re-renders the component. A
+     * fresh-class lookup therefore returns either the same object the
+     * stash captured (most common) or, on the rare occasion that the
+     * source file's `@Component` decorator was re-evaluated into a brand
+     * new class object (e.g. the user added `@Component(...)` to a new
+     * exported symbol), the live one. Either way, a single check is
+     * enough — the previous retry schedule was a no-op in 100 % of
+     * observed cycles because the captured class IS the live class.
+     */
+    private _restoreSingleDialog;
+    /**
+     * Maximum time we'll wait for the new root view to attach to the
+     * iOS window before giving up and trying the open anyway. NS Vite's
+     * worst observed reboot-to-rootview-loaded gap is ~250 ms; one
+     * second leaves headroom for slower devices without leaving the
+     * captured dialog stuck in the stash if something genuinely goes
+     * wrong.
+     */
+    private static readonly _ROOT_VIEW_LOADED_TIMEOUT_MS;
+    /**
+     * Defer the actual `this.open(...)` call until the new root view's
+     * underlying iOS `UIViewController.view` is in the window hierarchy.
+     *
+     * iOS silently rejects `presentViewControllerAnimatedCompletion` if
+     * the parent controller's view is not yet attached to a `UIWindow`
+     * (see `view/index.ios.ts::_showNativeModalView`, which logs to
+     * `Trace` and returns without throwing). In dev that would surface
+     * as a vanished modal with no actionable error.
+     *
+     * NS marks a view as `isLoaded === true` from
+     * `UILayoutViewController.viewWillAppear`, which fires once iOS has
+     * decided to add the view to its window. Listening for the
+     * `loadedEvent` (one-shot) plus an extra macrotask gives UIKit a
+     * chance to finish window attachment before we present.
+     */
+    private _scheduleRestoreOpenWhenReady;
+    private _pollForRootView;
+    private _performRestoreOpen;
+    /**
+     * Test/debug helper: discard any captured modals without restoring them.
+     * Mostly useful when projects want to opt out of restoration without
+     * recompiling. Public callers should prefer `preserveOnHmr: false` instead.
+     */
+    static _clearPendingHmrDialogs(): void;
     /**
      * Attaches the user-provided component to the already-created dialog container.
      * @param componentOrTemplateRef The type of component being loaded into the dialog,
@@ -1383,6 +1558,32 @@ declare class NativeDialogCloseDirective implements OnInit, OnChanges {
     static ɵdir: i0.ɵɵDirectiveDeclaration<NativeDialogCloseDirective, "[native-dialog-close], [nativeDialogClose]", ["nativeDialogClose"], { "dialogResult": { "alias": "native-dialog-close"; "required": false; }; "_matDialogClose": { "alias": "nativeDialogClose"; "required": false; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * Convenience module that re-exports the `NativeDialogCloseDirective` for
+ * template-driven `[nativeDialogClose]` usage.
+ *
+ * **Important**: `NativeDialog` itself is **not** listed in this module's
+ * `providers` array. The service is `@Injectable({ providedIn: 'root' })`,
+ * which already registers a single root-level instance and is fully
+ * tree-shakeable. Listing it here as well caused Angular to treat the
+ * module-level provider and the `providedIn: 'root'` factory as
+ * *separate* registrations once the module was pulled into a standalone
+ * app via `importProvidersFrom(NativeDialogModule, ...)`. The duplicate
+ * registration triggered:
+ *
+ *  - Two `NativeDialog` instances in the same root environment injector,
+ *    each subscribing to `postAngularBootstrap$`, which produced
+ *    duplicate restore attempts during HMR.
+ *  - `NG0200: Circular dependency detected for NativeDialog` while a
+ *    captured modal was being re-opened during HMR restore, because the
+ *    second resolution started while the first was still in progress.
+ *
+ * Removing the redundant entry collapses both providers back into a
+ * single root-level instance, which is what `providedIn: 'root'`
+ * documents. App authors who explicitly wire `NativeDialog` themselves
+ * (e.g. in a feature module's `providers`) keep working unchanged
+ * because they're targeting the same class symbol.
+ */
 declare class NativeDialogModule {
     static ɵfac: i0.ɵɵFactoryDeclaration<NativeDialogModule, never>;
     static ɵmod: i0.ɵɵNgModuleDeclaration<NativeDialogModule, never, [typeof NativeDialogCloseDirective], [typeof NativeDialogCloseDirective]>;
@@ -1448,6 +1649,344 @@ declare function generateNativeScriptView<T>(typeOrTemplate: Type<T> | TemplateR
     detachedLoaderRef?: ComponentRef<DetachedLoader>;
 }): NgViewRef<T>;
 
+/**
+ * Framework-agnostic Hot-Module-Replacement state cache.
+ *
+ * The {@link HmrCacheStore} class is intentionally free of any Angular
+ * imports so a future `@nativescript/solid` (or any other framework
+ * binding) can lift this file as-is and wrap it with its own DI
+ * primitive. The Angular DI wrapper lives in
+ * `./hmr-cache.service.ts`.
+ *
+ * # What it does
+ *
+ * The NativeScript iOS runtime exposes a Vite-spec compliant
+ * `import.meta.hot` on every imported module (see
+ * `@nativescript/ios` →
+ * `runtime/HMRSupport.{h,mm}::InitializeImportMetaHot`). The runtime
+ * keeps a per-module persistent `data` object alive in C++ across V8
+ * evaluation cycles and canonicalizes the module path so the same
+ * bucket survives the URL variations Vite cycles through during a
+ * save (HMR boot/live tags, versioned bridge paths, common script
+ * extensions). When `@nativescript/vite`'s Angular HMR client calls
+ * `globalThis.__nsRunHmrDispose()` before `__reboot_ng_modules__`,
+ * every registered `dispose(cb)` fires and is handed the same `data`
+ * object the next module evaluation will read from.
+ *
+ * `HmrCacheStore` rides on top of that primitive:
+ *
+ *   1. On construction, it copies any previously-stashed entries out
+ *      of `import.meta.hot.data['ns-hmr-cache']` (or whatever
+ *      `storageKey` the caller picked) into an in-memory `Map`.
+ *   2. It registers a single `import.meta.hot.dispose` callback that
+ *      writes the in-memory `Map` back as a plain object before the
+ *      next reboot.
+ *   3. Every `set` re-orders the key to the end of the `Map` (LRU);
+ *      when `size > maxEntries`, the oldest entry is evicted. This
+ *      stops a long dev session from accumulating unbounded state for
+ *      features the developer no longer touches.
+ *   4. It subscribes to a custom HMR event (default
+ *      `'ns:cache-invalidate'`) so a Vite plugin or dev server can
+ *      push targeted cache evictions — e.g. "the OData schema for
+ *      `/safety/forms` changed, drop anything that depends on it".
+ *
+ * In production / `--no-hmr` builds `import.meta.hot` is `undefined`,
+ * the store collapses to a pure in-memory cache that lives for the
+ * lifetime of the process, and the public API is identical so callers
+ * never need to special-case build modes.
+ *
+ * # Why a class and not a plain object
+ *
+ * Encapsulating the LRU bookkeeping behind named methods (`get`,
+ * `set`, `invalidate`, `scope`) lets us evolve the eviction policy
+ * (e.g. add TTLs, weighted entries, structured-clone enforcement)
+ * without touching every call site. The framework wrappers expose
+ * the same surface so app authors learn one API regardless of which
+ * framework they use.
+ */
+interface HmrCacheStoreOptions {
+    /**
+     * Maximum number of entries to keep before LRU-evicting the
+     * oldest. Set to `0` (or any non-positive number) for unlimited.
+     * Default: `256`.
+     *
+     * Sized for the empirical "depth of features a developer touches in
+     * one dev session" — large enough that a working set of ~30 pages,
+     * each with a handful of cached fields, never trips eviction during
+     * normal hacking; small enough that a runaway producer (e.g. a
+     * scroll-driven loop that mints new keys) gets capped instead of
+     * leaking memory until the simulator OOMs.
+     */
+    maxEntries?: number;
+    /**
+     * Key under which the cache is stashed on `import.meta.hot.data`.
+     * Apps that run multiple isolated cache stores (e.g. a feature-
+     * isolation plugin) can pick distinct keys to keep their state
+     * separate. Default: `'ns-hmr-cache'`.
+     */
+    storageKey?: string;
+    /**
+     * Custom HMR event name the store listens for. Payload schema:
+     *
+     * ```ts
+     * { key?: string }
+     * ```
+     *
+     * If `key` is provided, only that entry is dropped. If omitted, the
+     * entire cache is cleared. A Vite plugin sends events via the dev
+     * server's WebSocket (Vite spec
+     * [`server.ws.send`](https://vite.dev/guide/api-plugin.html#server-ws-send-and-server-ws-on));
+     * the runtime's `__NS_DISPATCH_HOT_EVENT__` then forwards them to
+     * every `import.meta.hot.on` listener. Default:
+     * `'ns:cache-invalidate'`.
+     */
+    invalidateEventName?: string;
+    /**
+     * Optional logger for diagnostic output. The store calls this with
+     * a single string per significant event (rehydrate, dispose, LRU
+     * evict, server-side invalidate). Default: no-op.
+     */
+    log?: (message: string) => void;
+}
+/**
+ * A namespaced view of an {@link HmrCacheStore}. Keys are
+ * automatically prefixed with `<scope>:`, so callers don't have to
+ * negotiate global key names. Returned by {@link HmrCacheStore.scope}.
+ */
+interface HmrCacheScope {
+    readonly prefix: string;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): void;
+    /** Drop every entry whose key starts with this scope's prefix. */
+    clear(): void;
+    /** Number of entries owned by this scope. */
+    size(): number;
+}
+declare class HmrCacheStore {
+    private readonly _map;
+    private readonly _maxEntries;
+    private readonly _log;
+    /**
+     * @param initialEntries Entries to seed the store with (typically
+     *   the previous session's snapshot read from
+     *   `import.meta.hot.data`).
+     * @param options See {@link HmrCacheStoreOptions}.
+     */
+    constructor(initialEntries?: Iterable<[string, unknown]>, options?: HmrCacheStoreOptions);
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): void;
+    /**
+     * Drop a specific entry, or every entry when `key` is omitted.
+     * Equivalent to {@link delete} (with key) or {@link clear} (without)
+     * — exposed as a single method so callers and event handlers can
+     * forward an optional key without branching.
+     */
+    invalidate(key?: string): void;
+    /** Drop every cached entry. */
+    clear(): void;
+    /** Total number of cached entries across all scopes. */
+    size(): number;
+    /** Snapshot of every key currently in the cache. */
+    keys(): string[];
+    /**
+     * Returns a namespaced view of this store. All keys passed to the
+     * returned object are auto-prefixed with `<prefix>:`. Useful so
+     * each feature module can avoid stomping on neighbours' keys
+     * without repeating the prefix at every call site.
+     *
+     * @example
+     * ```ts
+     * const cache = createDefaultHmrCacheStore();
+     * const submissions = cache.scope('page-my-submissions');
+     * submissions.set('items', [...]); // stored under 'page-my-submissions:items'
+     * ```
+     */
+    scope(prefix: string): HmrCacheScope;
+    /**
+     * Serialize every entry into a plain object suitable for stashing
+     * on `import.meta.hot.data`. Used by the dispose callback in
+     * {@link createDefaultHmrCacheStore} and re-exported for callers
+     * that want to integrate with another persistence layer (e.g. a
+     * test harness that snapshots between cases).
+     */
+    toObject(): Record<string, unknown>;
+    private _enforceMaxEntries;
+}
+/**
+ * Build an {@link HmrCacheStore} bound to the current module's
+ * `import.meta.hot` context — i.e. the store's data survives HMR
+ * reboots and listens for the `'ns:cache-invalidate'` custom event.
+ *
+ * Caller responsibility: invoke this from the module that "owns" the
+ * cache. `import.meta` is per-module, so the dispose callback will be
+ * registered against whichever module physically calls this function.
+ * In `@nativescript/angular` the canonical owner is
+ * `hmr-cache.service.ts`; in `@nativescript/solid` it would be the
+ * equivalent solid-side module.
+ *
+ * Returns a freshly-constructed store. Callers should treat it as a
+ * singleton — calling this twice from the same module yields two
+ * independent stores, which is almost never what you want.
+ */
+declare function createDefaultHmrCacheStore(options?: HmrCacheStoreOptions): HmrCacheStore;
+
+/**
+ * Skip the API call your component already paid for last save.
+ *
+ * Inject {@link HmrCacheService} from any Angular component or service
+ * to read and write a per-app key/value cache that **survives the
+ * `__reboot_ng_modules__` cycle** triggered by every HMR file save.
+ * Backed by `@nativescript/ios`'s native `import.meta.hot.data`
+ * (`runtime/HMRSupport.{h,mm}`) and drained via
+ * `@nativescript/vite`'s `globalThis.__nsRunHmrDispose()` hook before
+ * Angular tears down its realm, so the same value the previous
+ * component instance produced is handed straight to the freshly-
+ * instantiated one — no network round-trip, no spinner flash.
+ *
+ * In production / `--no-hmr` builds `import.meta.hot` is `undefined`
+ * and the cache collapses to a plain in-memory object that lives for
+ * the lifetime of the process. The public API is identical, so callers
+ * never need to special-case build modes.
+ *
+ * @example Skip the initial fetch on save
+ * ```ts
+ * import { HmrCacheService } from '@nativescript/angular';
+ *
+ * @Component({...})
+ * export class MyComponent implements OnInit {
+ *   private hmrCache = inject(HmrCacheService);
+ *
+ *   ngOnInit() {
+ *     const cached = this.hmrCache.get<MyResult>('my-feature:items');
+ *     if (cached) {
+ *       this.applyResult(cached);
+ *       return;
+ *     }
+ *     this.api.load().subscribe((result) => {
+ *       this.hmrCache.set('my-feature:items', result);
+ *       this.applyResult(result);
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Namespaced via {@link scope}
+ * ```ts
+ * private cache = inject(HmrCacheService).scope('page-my-submissions');
+ * // …
+ * this.cache.set('items', items);   // → 'page-my-submissions:items'
+ * this.cache.get('items');          // ← 'page-my-submissions:items'
+ * ```
+ *
+ * @example Server-side invalidation from a Vite plugin
+ * ```ts
+ * // vite.config.ts
+ * export default defineConfig({
+ *   plugins: [
+ *     {
+ *       name: 'my-schema-watcher',
+ *       configureServer(server) {
+ *         server.watcher.on('change', (path) => {
+ *           if (path.endsWith('schema.json')) {
+ *             server.ws.send({
+ *               type: 'custom',
+ *               event: 'ns:cache-invalidate',
+ *               data: { key: 'my-feature:items' },
+ *             });
+ *           }
+ *         });
+ *       },
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * Memory ceiling: the cache LRU-evicts at 256 entries by default. Pass
+ * a custom ceiling via {@link configureHmrCache} if your app churns
+ * through more keys than that in a typical dev session, or set `0` for
+ * unlimited (unbounded growth — only safe for short-lived dev work).
+ *
+ * @see HmrCacheStore — the framework-agnostic engine. Stable enough to
+ *   lift into `@nativescript/solid` / other framework bindings without
+ *   modification.
+ */
+declare class HmrCacheService {
+    private readonly _store;
+    /**
+     * `true` when `import.meta.hot` is wired (i.e. NativeScript Vite HMR
+     * is active and `@nativescript/ios` is recent enough to expose
+     * `import.meta.hot.data`). `false` in production / `--no-hmr` /
+     * legacy webpack builds.
+     *
+     * Most callers should NOT branch on this — the public API works
+     * identically in both cases. Use it only when you want to opt OUT
+     * of caching in production (e.g. always fetch fresh data when not
+     * developing).
+     */
+    readonly isHmr: boolean;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): void;
+    /**
+     * Drop a single entry, or every entry when `key` is omitted. Same
+     * shape as the `'ns:cache-invalidate'` HMR-event payload the store
+     * listens for, so application code can call this directly to mirror
+     * a server-side eviction.
+     */
+    invalidate(key?: string): void;
+    /** Drop every cached entry. Equivalent to `invalidate()` with no key. */
+    clear(): void;
+    /** Total number of entries across every scope. */
+    size(): number;
+    /** Snapshot of every key currently cached. Useful for debug overlays. */
+    keys(): string[];
+    /**
+     * Returns a namespaced view of the cache. All `get` / `set` /
+     * `has` / `delete` calls on the returned object are auto-prefixed
+     * with `<scopeName>:`. Recommended over global keys so feature
+     * modules don't accidentally collide.
+     *
+     * @example
+     * ```ts
+     * private cache = inject(HmrCacheService).scope('page-my-submissions');
+     * // …
+     * this.cache.set('items', items); // → 'page-my-submissions:items'
+     * ```
+     */
+    scope(scopeName: string): HmrCacheScope;
+    static ɵfac: i0.ɵɵFactoryDeclaration<HmrCacheService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<HmrCacheService>;
+}
+/**
+ * Override the default cache configuration. Must be called BEFORE the
+ * first injection of {@link HmrCacheService} (i.e. before Angular
+ * bootstrap, or as the very first statement in `main.ts`); otherwise
+ * the call is a no-op because the singleton store has already been
+ * built with the previous (or default) options.
+ *
+ * Typical use case: bumping `maxEntries` for a large multi-feature
+ * monorepo dev session, or pointing a custom `invalidateEventName` at
+ * a Vite plugin that prefixes its events with the project name.
+ *
+ * Returns `true` if the configuration was applied, `false` if the
+ * store had already been instantiated by an earlier injection.
+ */
+declare function configureHmrCache(options: HmrCacheStoreOptions): boolean;
+/**
+ * Read-only access to the underlying {@link HmrCacheStore}. Exposed
+ * for advanced integrations that want to reuse the LRU + dispose +
+ * server-side-invalidate plumbing without going through Angular's
+ * dependency injection (e.g. a non-component utility that's loaded
+ * before the Angular platform has bootstrapped). Application code
+ * should prefer {@link HmrCacheService}.
+ */
+declare function getHmrCacheStore(): HmrCacheStore;
+
 declare function registerNativeScriptViewComponents(): void;
 
 type ViewResolver = () => any;
@@ -2076,6 +2615,35 @@ declare class NativeScriptRouterModule {
 declare function rootRoute(router: Router): ActivatedRoute;
 declare function provideNativeScriptRouter(routes: Routes, ...features: RouterFeatures[]): i0.EnvironmentProviders;
 
+/**
+ * True while the Angular HMR layer is restoring a captured route stack
+ * onto the freshly-bootstrapped router. The window opens just before
+ * `START_PATH` resolves to a deep URL and closes once the router has
+ * walked the entire forward navigation list (or aborted it).
+ *
+ * User-app code that runs default navigations on component init (e.g. a
+ * bottom-nav defaulting to its first tab) can consult this flag to skip
+ * its default navigation so the framework's restored route survives:
+ *
+ * ```ts
+ * if (isAngularHmrRestoringRoute()) {
+ *   return; // framework is restoring a deeper route — leave it alone.
+ * }
+ * defaultTabNavigation();
+ * ```
+ *
+ * Returns `false` outside of HMR or after the replay window has closed.
+ * Production builds always see `false` because the framework never
+ * opens the window there.
+ */
+declare function isAngularHmrRestoringRoute(): boolean;
+/**
+ * The target route the framework is currently restoring, or `null` when
+ * no replay is in progress. Useful when the consumer wants to compare
+ * against the current router URL.
+ */
+declare function getAngularHmrRestoringRoute(): string | null;
+
 declare class NativeScriptDebug {
     static readonly animationsTraceCategory = "ns-animations";
     static readonly rendererTraceCategory = "ns-renderer";
@@ -2260,5 +2828,5 @@ declare class NativeScriptNgZone implements NgZone {
 }
 declare function provideNativeScriptNgZone(options?: NgZoneOptions): i0.StaticProvider[];
 
-export { APP_ROOT_VIEW, ActionBarComponent, ActionBarScope, ActionItemDirective, AndroidFilterComponent, AppHostAsyncView, AppHostView, AppleFilterComponent, BasePortalOutlet, BaseValueAccessor, COMMON_PROVIDERS, CdkPortal, CdkPortalOutlet, CheckedValueAccessor, CommentNode, ComponentPortal, DEVICE, DISABLE_ROOT_VIEW_HANDLING, DateValueAccessor, DetachedLoader, DomPortal, ENABLE_REUSABE_VIEWS, EmulatedRenderer, FrameDirective, FramePageComponent, FramePageModule, FrameService, IOSFilterComponent, InjectableAnimationEngine, InvisibleNode, ItemContext, ListViewComponent, ModalDialogParams, ModalDialogService, NAMESPACE_FILTERS, NATIVESCRIPT_MODULE_PROVIDERS, NATIVESCRIPT_MODULE_STATIC_PROVIDERS, NATIVESCRIPT_ROOT_MODULE_ID, NATIVE_DIALOG_DATA, NATIVE_DIALOG_DEFAULT_OPTIONS, NSEmptyOutletComponent, NSFileSystem, NSLocationStrategy, NSRouteReuseStrategy, NSRouterLink, NSRouterLinkActive, NativeDialog, NativeDialogCloseDirective, NativeDialogConfig, NativeDialogModule, NativeDialogRef, NativeDialog as NativeDialogService, NativeDialogState, NativeModalRef, NativeScriptAnimationDriver, NativeScriptAnimationPlayer, NativeScriptAnimationsModule, NativeScriptCommonModule, NativeScriptDocument, NativeScriptDomPortalOutlet, NativeScriptFormsModule, NativeScriptHttpClientModule, NativeScriptLoadingService, NativeScriptModule, NativeScriptNgSafeEvent, NativeScriptNgZone, NativeScriptRendererFactory, NativeScriptRendererHelperService, NativeScriptRouterModule, NativeScriptSanitizer, NativescriptXhrFactory, NavigationButtonDirective, NgViewRef, NsHttpBackEnd, NsTemplatedItem, NumberValueAccessor, Outlet, PAGE_FACTORY, PREVENT_CHANGE_EVENTS_DURING_CD, PREVENT_SPECIFIC_EVENTS_DURING_CD, PageDirective, PageRoute, PageRouterOutlet, PageService, PlatformNamespaceFilter, Portal, PortalModule, RootCompositeModule, RootViewProxy, RouterExtensions, START_PATH, SelectedIndexValueAccessor, TEMPLATED_ITEMS_COMPONENT, TabViewDirective, TabViewItemDirective, TemplateKeyDirective, TemplatePortal, TextNode, TextValueAccessor, TimeValueAccessor, VisionOSFilterComponent, bootstrapApplication, createKeyframeAnimation, customFrameComponentFactory, customFrameDirectiveFactory, customPageFactory, customPageFactoryFromFrame, dashCaseToCamelCase, defaultNavOptions, defaultPageFactory, defaultPageFactoryProvider, detachViewFromParent, disableRootViewHanding, errorHandler, extractSingleViewRecursive, frameMeta, generateDetachedLoader, generateFallbackRootView, generateNativeScriptView, generateRandomId, generateRootLayoutAndProxy, getFirstNativeLikeView, getItemViewRoot, getSingleViewRecursive, getViewClass, getViewMeta, instantiateDefaultStyleNormalizer, instantiateSupportedAnimationDriver, isBlank, isContentView, isDetachedElement, isInvisibleNode, isJsObject, isKnownView, isLayout, isListLikeIterable, isPresent, isView, onAfterLivesync, onBeforeLivesync, once, platformNativeScript, platformNativeScriptDynamic, postAngularBootstrap$, preAngularDisposal$, provideLocationStrategy, provideNativeScriptHttpClient, provideNativeScriptNgZone, provideNativeScriptRouter, registerElement, registerNativeScriptViewComponents, rootRoute, runNativeScriptAngularApp, throwIfAlreadyLoaded, throwNoPortalAttachedError, throwNullPortalError, throwNullPortalOutletError, throwPortalAlreadyAttachedError, throwPortalOutletAlreadyDisposedError, throwUnknownPortalTypeError, COMPONENT_VARIABLE as ɵCOMPONENT_VARIABLE, CONTENT_ATTR as ɵCONTENT_ATTR, HOST_ATTR as ɵHOST_ATTR, NativeScriptDebug as ɵNativeScriptAngularDebug, viewUtil_d as ɵViewUtil, actionBarMeta as ɵactionBarMeta, elementMap as ɵelementMap, isActionItem as ɵisActionItem, isNavigationButton as ɵisNavigationButton };
-export type { AppLaunchView, AppOptions, AppRunOptions, ApplicationConfig, BaseShowModalOptions, CdkPortalOutletAttachedRef, ComponentType, HmrOptions, Keyframe, LocationState, ModalDialogOptions, NamespaceFilter, NativeShowModalOptions, NavigationOptions, NgModuleEvent, NgModuleReason, NgView, NgViewTemplate, PageFactory, PageFactoryOptions, PortalOutlet, RootLocator, SelectableView, SetupItemViewArgs, ShowDialogOptions, TabViewItemDef, TemplatedItemsHost, TextView, ViewClass, ViewClassMeta, ViewExtensions, ViewResolver };
+export { APP_ROOT_VIEW, ActionBarComponent, ActionBarScope, ActionItemDirective, AndroidFilterComponent, AppHostAsyncView, AppHostView, AppleFilterComponent, BasePortalOutlet, BaseValueAccessor, COMMON_PROVIDERS, CdkPortal, CdkPortalOutlet, CheckedValueAccessor, CommentNode, ComponentPortal, DEVICE, DISABLE_ROOT_VIEW_HANDLING, DateValueAccessor, DetachedLoader, DomPortal, ENABLE_REUSABE_VIEWS, EmulatedRenderer, FrameDirective, FramePageComponent, FramePageModule, FrameService, HmrCacheService, HmrCacheStore, IOSFilterComponent, InjectableAnimationEngine, InvisibleNode, ItemContext, ListViewComponent, ModalDialogParams, ModalDialogService, NAMESPACE_FILTERS, NATIVESCRIPT_MODULE_PROVIDERS, NATIVESCRIPT_MODULE_STATIC_PROVIDERS, NATIVESCRIPT_ROOT_MODULE_ID, NATIVE_DIALOG_DATA, NATIVE_DIALOG_DEFAULT_OPTIONS, NSEmptyOutletComponent, NSFileSystem, NSLocationStrategy, NSRouteReuseStrategy, NSRouterLink, NSRouterLinkActive, NativeDialog, NativeDialogCloseDirective, NativeDialogConfig, NativeDialogModule, NativeDialogRef, NativeDialog as NativeDialogService, NativeDialogState, NativeModalRef, NativeScriptAnimationDriver, NativeScriptAnimationPlayer, NativeScriptAnimationsModule, NativeScriptCommonModule, NativeScriptDocument, NativeScriptDomPortalOutlet, NativeScriptFormsModule, NativeScriptHttpClientModule, NativeScriptLoadingService, NativeScriptModule, NativeScriptNgSafeEvent, NativeScriptNgZone, NativeScriptRendererFactory, NativeScriptRendererHelperService, NativeScriptRouterModule, NativeScriptSanitizer, NativescriptXhrFactory, NavigationButtonDirective, NgViewRef, NsHttpBackEnd, NsTemplatedItem, NumberValueAccessor, Outlet, PAGE_FACTORY, PREVENT_CHANGE_EVENTS_DURING_CD, PREVENT_SPECIFIC_EVENTS_DURING_CD, PageDirective, PageRoute, PageRouterOutlet, PageService, PlatformNamespaceFilter, Portal, PortalModule, RootCompositeModule, RootViewProxy, RouterExtensions, START_PATH, SelectedIndexValueAccessor, TEMPLATED_ITEMS_COMPONENT, TabViewDirective, TabViewItemDirective, TemplateKeyDirective, TemplatePortal, TextNode, TextValueAccessor, TimeValueAccessor, VisionOSFilterComponent, bootstrapApplication, configureHmrCache, createDefaultHmrCacheStore, createKeyframeAnimation, customFrameComponentFactory, customFrameDirectiveFactory, customPageFactory, customPageFactoryFromFrame, dashCaseToCamelCase, defaultNavOptions, defaultPageFactory, defaultPageFactoryProvider, detachViewFromParent, disableRootViewHanding, errorHandler, extractSingleViewRecursive, frameMeta, generateDetachedLoader, generateFallbackRootView, generateNativeScriptView, generateRandomId, generateRootLayoutAndProxy, getAngularHmrRestoringRoute, getFirstNativeLikeView, getHmrCacheStore, getItemViewRoot, getSingleViewRecursive, getViewClass, getViewMeta, instantiateDefaultStyleNormalizer, instantiateSupportedAnimationDriver, isAngularHmrRestoringRoute, isBlank, isContentView, isDetachedElement, isInvisibleNode, isJsObject, isKnownView, isLayout, isListLikeIterable, isPresent, isView, onAfterLivesync, onBeforeLivesync, once, platformNativeScript, platformNativeScriptDynamic, postAngularBootstrap$, preAngularDisposal$, provideLocationStrategy, provideNativeScriptHttpClient, provideNativeScriptNgZone, provideNativeScriptRouter, registerElement, registerNativeScriptViewComponents, rootRoute, runNativeScriptAngularApp, throwIfAlreadyLoaded, throwNoPortalAttachedError, throwNullPortalError, throwNullPortalOutletError, throwPortalAlreadyAttachedError, throwPortalOutletAlreadyDisposedError, throwUnknownPortalTypeError, COMPONENT_VARIABLE as ɵCOMPONENT_VARIABLE, CONTENT_ATTR as ɵCONTENT_ATTR, HOST_ATTR as ɵHOST_ATTR, NativeScriptDebug as ɵNativeScriptAngularDebug, viewUtil_d as ɵViewUtil, actionBarMeta as ɵactionBarMeta, elementMap as ɵelementMap, isActionItem as ɵisActionItem, isNavigationButton as ɵisNavigationButton };
+export type { AppLaunchView, AppOptions, AppRunOptions, ApplicationConfig, BaseShowModalOptions, CdkPortalOutletAttachedRef, ComponentType, HmrCacheScope, HmrCacheStoreOptions, HmrOptions, Keyframe, LocationState, ModalDialogOptions, NamespaceFilter, NativeShowModalOptions, NavigationOptions, NgModuleEvent, NgModuleReason, NgView, NgViewTemplate, PageFactory, PageFactoryOptions, PortalOutlet, RootLocator, SelectableView, SetupItemViewArgs, ShowDialogOptions, TabViewItemDef, TemplatedItemsHost, TextView, ViewClass, ViewClassMeta, ViewExtensions, ViewResolver };