@nativescript/vite 8.0.0-alpha.7 → 8.0.0-alpha.71

package/hmr/frameworks/angular/client/index.js

@@ -1,44 +1,23 @@
-// Opt-out flag for the apply-progress overlay (default: enabled).
-// Driven by `NS_VITE_PROGRESS_OVERLAY=0` (or `false`/`off`/`no`) on the
-// dev server; baked into the bundle via
-// `__NS_HMR_PROGRESS_OVERLAY_ENABLED__` at build time. We collapse the
-// build-time constant into a runtime boolean once so each call-site is
-// a single property check rather than a try/typeof. Tests that re-run
-// the angular client (via vitest) see `undefined` and default to
-// enabled — matching the production dev-server experience.
-const overlayEnabled = (() => {
-    try {
-        return typeof __NS_HMR_PROGRESS_OVERLAY_ENABLED__ === 'boolean' ? __NS_HMR_PROGRESS_OVERLAY_ENABLED__ : true;
-    }
-    catch {
-        return true;
-    }
-})();
-function getHmrOverlayApi() {
-    if (!overlayEnabled)
-        return null;
-    try {
-        return globalThis.__NS_HMR_DEV_OVERLAY__ || null;
-    }
-    catch { }
-    return null;
-}
+import { getGlobalScope } from '../../../shared/runtime/global-scope.js';
+import { getNsHotRegistry } from '../../../client/hot-context.js';
+import { getOverlayApi, resolveOverlayEnabled, setUpdateStage } from '../../../client/overlay-driver.js';
+import { handleCssUpdates } from '../../../client/css-handler.js';
+import { resolveHmrHttpOrigin } from '../../../client/utils.js';
+import { readNsRuntimeDevHostApi } from '../../../shared/runtime/browser-runtime-contract.js';
+// HMR-applying progress overlay, driven through `client/overlay-driver.ts`.
+// The opt-out gate is collapsed into a runtime boolean once at module load so
+// each call-site is a single property check rather than a try/typeof chain.
+const overlayEnabled = resolveOverlayEnabled();
 function setUpdateOverlayStage(stage, info) {
     if (!overlayEnabled)
         return;
-    try {
-        const api = getHmrOverlayApi();
-        if (api && typeof api.setUpdateStage === 'function') {
-            api.setUpdateStage(stage, info);
-        }
-    }
-    catch { }
+    setUpdateStage(stage, info);
 }
 function hideUpdateOverlay() {
     if (!overlayEnabled)
         return;
     try {
-        const api = getHmrOverlayApi();
+        const api = getOverlayApi();
         if (api && typeof api.hide === 'function') {
             api.hide('hmr-applied');
         }
@@ -79,12 +58,25 @@ export function installAngularHmrClientHooks() {
     }
     catch { }
 }
+async function applyDeferredCssUpdates(msg) {
+    const updates = Array.isArray(msg?.cssUpdates) ? msg.cssUpdates : [];
+    if (!updates.length)
+        return;
+    try {
+        await handleCssUpdates(updates, resolveHmrHttpOrigin(msg?.origin));
+    }
+    catch (error) {
+        // The Angular module refresh is still viable. Surface the CSS failure, but
+        // continue with the reboot so one fetch cannot strand the old application.
+        console.warn('[ns-hmr][angular] deferred app.css update failed:', error?.message || error);
+    }
+}
 // HMR cycle serialization mutex.
 //
 // A back-to-back save (e.g., the user holds Cmd+S, or `runOnSave`
 // saves a file twice during one tick) could overlap two HMR cycles:
 // the first cycle's `import(entry)` would still be resolving when the
-// second cycle's `__nsInvalidateModules` ran, leaving the registry in
+// second cycle's `invalidateModules` (ns:runtime) ran, leaving the registry in
 // a half-evicted state and producing flaky "module already evaluated"
 // errors.
 //
@@ -98,136 +90,272 @@ export function installAngularHmrClientHooks() {
 let inFlightHmrCycle = null;
 // Explicit module eviction.
 //
-// `__nsInvalidateModules` is a runtime-installed global that takes an
-// array of canonical /ns/m/<rel> URLs and removes each one from V8's
-// module registry (`g_moduleRegistry`). The runtime canonicalizer
-// strips legacy `__ns_hmr__/<tag>/` and `__ns_boot__/b1/` segments
-// before lookup, so the same URL evicts every cache entry historically
-// created for that module — even if a stale tagged URL is still around.
+// `invalidateModules` is an ns:runtime builtin member that takes an
+// array of canonical /ns/m/<rel> URLs, removes each one from V8's
+// module registry (`g_moduleRegistry`) and the prefetch cache, and
+// marks the keys "bust next fetch" so the runtime's next HTTP fetch
+// for them defeats OS-level caches with a one-shot query nonce.
 //
-// Soft-fails on older runtimes that don't expose the function. In that
-// case we fall through to the legacy URL-versioning path and emit a
-// one-time warning so the user knows the eviction protocol is
-// unavailable.
-function invalidateModules(urls, verbose) {
-    if (!urls || !urls.length)
-        return false;
-    const g = globalThis;
-    const fn = g.__nsInvalidateModules;
-    if (typeof fn !== 'function') {
-        if (verbose && envVerbose) {
-            try {
-                console.warn(`[hmr-angular] runtime missing __nsInvalidateModules; falling back to legacy URL versioning. evict=${urls.length}`);
-            }
-            catch { }
+// Soft-fails (with a loud warning) if the runtime is missing the
+// function — the eviction protocol is a required part of the runtime
+// contract, so that indicates a runtime/vite version mismatch.
+// Dispatch one of Vite's standard HMR lifecycle events through the JS
+// hot registry (`hot-context.ts`). The registry owns the listener map
+// that `import.meta.hot.on(event, cb)` populates; this function is the
+// producer side that lets the Angular HMR client emit the canonical
+// Vite events (`vite:beforeUpdate`, `vite:afterUpdate`,
+// `vite:beforeFullReload`, `vite:invalidate`, `vite:error`) at the
+// right moments. User code that does
+// `import.meta.hot.on('vite:beforeUpdate', cb)` only fires when this is
+// called.
+//
+// The registry is a `globalThis.__NS_HOT_REGISTRY__` singleton, so this
+// works even if this module and the served app modules were evaluated
+// from different URLs. Per-listener failures are swallowed inside the
+// registry, so a single bad listener can't break the HMR cycle.
+function dispatchHotEvent(_g, event, payload) {
+    try {
+        getNsHotRegistry().dispatchHotEvent(event, payload);
+    }
+    catch (err) {
+        // Defensive safety net for registry regressions. Log only under
+        // verbose to avoid noisy dev logs.
+        if (envVerbose) {
+            console.warn(`[ns-hmr][client] dispatchHotEvent('${event}') threw:`, err?.message ?? err);
+        }
+    }
+}
+// Trigger a JS-driven full app reload, dispatching `vite:beforeFullReload`
+// first so user-code listeners can react. The registry's full-reload path
+// evicts every loaded app module (ns:runtime `getLoadedModuleUrls` →
+// `invalidateModules`) and re-imports the dev entry; the
+// `Application.run` patch in root-placeholder converts re-entry into
+// `resetRootView`. Returns `true` if the reload was triggered. Used both
+// by `import.meta.hot.invalidate()` (handled inside the registry) AND by
+// the declined-module check below (where the JS layer makes the decision
+// and asks for the reload).
+function triggerFullReload(_g, message) {
+    dispatchHotEvent(_g, 'vite:beforeFullReload', { message });
+    try {
+        // Fire-and-forget — the reload path is async, but we don't await
+        // it here because the module graph is about to be torn down. The
+        // HMR cycle's caller treats this as terminal and short-circuits
+        // the rest of the cycle.
+        getNsHotRegistry().requestFullReload(message);
+    }
+    catch (err) {
+        if (envVerbose) {
+            console.warn('[ns-hmr][client] requestFullReload threw:', err?.message ?? err);
         }
         return false;
     }
+    return true;
+}
+// Check if any module being touched by this HMR update has called
+// `import.meta.hot.decline()`. If so, per Vite spec we MUST do a full
+// reload instead of a hot-update — declining means "I refuse to be
+// hot-updated". Returns `true` if a full reload was triggered (caller
+// should short-circuit the rest of the cycle).
+function checkDeclinedAndReload(g, msg, options) {
+    // `evictPaths` is the eviction set the dev server computed for this
+    // HMR cycle — every module that needs to be re-evaluated. If ANY of
+    // those modules declined HMR, the whole cycle has to convert to a
+    // full reload. Pass them through verbatim; the registry canonicalizes
+    // internally when matching against its declined set.
+    const evictPaths = Array.isArray(msg?.evictPaths) ? msg.evictPaths : [];
+    let declined = false;
     try {
-        fn.call(null, urls);
-        return true;
+        declined = getNsHotRegistry().hasDeclined(evictPaths);
     }
-    catch (error) {
-        if (verbose && envVerbose) {
-            try {
-                console.warn('[hmr-angular] __nsInvalidateModules threw', error?.message || error);
-            }
-            catch { }
+    catch (err) {
+        if (options.verbose && envVerbose) {
+            console.warn('[ns-hmr][client] hasDeclined threw:', err?.message ?? err);
         }
         return false;
     }
+    if (!declined)
+        return false;
+    const filePath = typeof msg?.path === 'string' ? msg.path : '<unknown>';
+    const message = `module declined HMR (file=${filePath}, evictPaths=${evictPaths.length})`;
+    console.info(`[ns-hmr][decline] ${message} — falling back to full reload`);
+    const reloaded = triggerFullReload(g, message);
+    if (!reloaded && options.verbose && envVerbose) {
+        console.warn('[ns-hmr][client] declined module detected but full reload unavailable; HMR will proceed');
+    }
+    return reloaded;
+}
+// Drain `import.meta.hot.dispose(cb)` callbacks via the JS hot
+// registry before Angular's reboot.
+//
+// The registry (`hot-context.ts`) owns the dispose map — every call to
+// `import.meta.hot.dispose(cb)` from user code lands there. We pass NO
+// key argument so the registry drains every registered callback across
+// every module, which matches the wholesale-reboot semantics of
+// `__reboot_ng_modules__`: when Angular tears down its component tree
+// and re-bootstraps, every module's accumulated side effects are
+// conceptually being thrown away. (A future per-module HMR client could
+// pass an explicit key list to limit the drain.)
+function runHmrDisposeCallbacks(_g, options) {
+    let executed = null;
+    try {
+        const result = getNsHotRegistry().runDispose();
+        executed = typeof result === 'number' ? result : 0;
+    }
+    catch (err) {
+        // Per-callback failures are swallowed inside the registry. If
+        // the registry itself throws we MUST NOT take down the HMR cycle.
+        if (options.verbose && envVerbose) {
+            console.warn('[ns-hmr][client] runDispose threw:', err?.message ?? err);
+        }
+        return;
+    }
+    // Surface ONE concise log per HMR cycle that actually had disposers
+    // to run. Quiet on cycles where no module had registered any.
+    if (executed && executed > 0) {
+        console.info(`[ns-hmr][dispose] ran ${executed} import.meta.hot.dispose callback${executed === 1 ? '' : 's'} before reboot`);
+    }
 }
-// Eviction-set size cap for the kickstart.
+// Terminate every live worker before Angular's reboot. Two-tier strategy:
+//
+//   1. PREFERRED — `require('ns:runtime').terminateAllWorkers()` (NS iOS runtime
+//      ≥ the version that ships `Worker::TerminateAllWorkersCallback`).
+//      Native code iterates `Caches::Workers` (the runtime's authoritative
+//      worker registry) and calls `WorkerWrapper::Terminate()` on each
+//      live entry. Universal: catches every worker regardless of how it
+//      was created — `new Worker(new URL(...))`, raw `Worker('~/x.js')`,
+//      dynamic-import-spawned workers, plugin-spawned workers, etc.
+//
+//   2. FALLBACK — drain `globalThis.__NS_HMR_WORKERS__` (a Set populated
+//      by `__nsHmrTrackWorker`, the helper that `workerHmrUrlPlugin`
+//      injects at the top of every dev module containing a
+//      `new Worker(new URL(...))` call). This keeps HMR worker cleanup
+//      working on runtimes that don't expose
+//      `terminateAllWorkers` on ns:runtime. It only catches workers spawned via
+//      the Vite-rewritten path, so the runtime API is strictly better
+//      coverage.
 //
-// `__NS_HMR_KICKSTART_MAX_URLS__` is a build-time literal injected
-// by `helpers/global-defines.ts` (default 32). It is a pure
-// performance gate: the kickstart never affects correctness, so
-// skipping it for large fan-out edits simply reverts the runtime to
-// sequential `HttpFetchText`. See the doc comment on
-// `resolveHmrKickstartMaxUrls` (in global-defines.ts) for the
-// rationale and the empirical numbers behind the default.
+// Either way: producer-side wraps are still useful as diagnostic
+// metadata (which user code spawned which worker), so we always clear
+// the JS Set after termination — irrespective of which tier ran — so
+// it doesn't grow unbounded across HMR cycles.
 //
-// The constant is read once at module load (the same pattern used
-// for `overlayEnabled`) so each call site is a single inequality
-// check rather than a try/typeof. Tests that re-import this module
-// see `undefined` and fall back to the default.
-const KICKSTART_DEFAULT_MAX_URLS = 32;
-const kickstartMaxUrls = (() => {
+// Tolerant of:
+//   * Missing globals — non-worker apps have neither global; we no-op.
+//   * `terminate()` throwing — the runtime can throw on already-dead
+//     workers; we catch per-entry so subsequent terminations and the
+//     reboot itself still proceed.
+//   * Native API throwing — wrapped in try/catch so a runtime regression
+//     can't take down the HMR cycle; we degrade to the JS-Set fallback.
+function terminateTrackedWorkers(g, options) {
+    let nativeApi;
     try {
-        const raw = __NS_HMR_KICKSTART_MAX_URLS__;
-        if (typeof raw !== 'number')
-            return KICKSTART_DEFAULT_MAX_URLS;
-        if (!Number.isFinite(raw))
-            return Number.POSITIVE_INFINITY;
-        if (raw < 0)
-            return KICKSTART_DEFAULT_MAX_URLS;
-        return Math.floor(raw);
+        const candidate = g && readNsRuntimeDevHostApi(g).terminateAllWorkers;
+        if (typeof candidate === 'function') {
+            nativeApi = candidate;
+        }
     }
     catch {
-        return KICKSTART_DEFAULT_MAX_URLS;
+        // Reading the global threw (extremely defensive — `globalThis`
+        // access shouldn't, but Proxy-wrapped globals can).
     }
-})();
-// Decide whether to run the kickstart for a given eviction set.
-// Exported for unit testing — callers in this module use the inline
-// `evictPaths.length` comparison below for a slightly cheaper
-// hot-path.
-//
-// Semantics:
-// - `0` urls   → no work to do; skip (returns false).
-// - `urls.length <= cap` → kickstart eligible (returns true).
-// - `urls.length > cap`  → skip kickstart (returns false). V8 falls
-//   back to per-module synchronous fetches inside its module walk.
-// - `cap === 0`           → kickstart disabled regardless of size.
-// - `cap === Infinity`    → kickstart always eligible (no cap).
-export function shouldRunKickstart(urlCount, maxUrls = kickstartMaxUrls) {
-    if (!Number.isFinite(urlCount) || urlCount <= 0)
-        return false;
-    if (!Number.isFinite(maxUrls))
-        return maxUrls > 0;
-    if (maxUrls <= 0)
-        return false;
-    return urlCount <= maxUrls;
-}
-function kickstartHmrPrefetch(urls, verbose) {
-    if (!urls || !urls.length)
-        return null;
-    const g = globalThis;
-    const fn = g.__nsKickstartHmrPrefetch;
-    if (typeof fn !== 'function') {
-        if (verbose && envVerbose) {
-            try {
-                console.info(`[hmr-angular] runtime missing __nsKickstartHmrPrefetch; serial fetches will be used. urls=${urls.length}`);
+    let nativeTerminated = null;
+    if (nativeApi) {
+        try {
+            const result = nativeApi.call(g);
+            // The native API returns the count of workers terminated;
+            // treat any non-number as "ran successfully, count unknown".
+            nativeTerminated = typeof result === 'number' ? result : 0;
+        }
+        catch (err) {
+            if (options.verbose && envVerbose) {
+                console.warn('[ns-hmr][client] ns:runtime terminateAllWorkers threw; falling back to JS-tracked Set:', err?.message ?? err);
             }
-            catch { }
+            nativeApi = undefined; // force fallback below
         }
-        return null;
     }
+    // Always touch the JS-tracked Set so producer-side bookkeeping
+    // doesn't outlive its workers across HMR cycles. If the native API
+    // already terminated everything, this is just a `.clear()`. If the
+    // runtime doesn't expose the primitive, this is the actual cleanup
+    // path.
+    let workers;
     try {
-        // Concurrency cap of 16 matches the runtime's documented
-        // default for the kickstart BFS. Timeout at 10s tracks the
-        // runtime's `HttpFetchText` retry envelope so we don't
-        // hold the JS thread forever on a stalled dev server.
-        const result = fn.call(null, urls.slice(), { maxConcurrent: 16, timeoutMs: 10000 });
-        if (result && typeof result === 'object') {
-            const ok = !!result.ok;
-            const fetched = typeof result.fetched === 'number' ? result.fetched : 0;
-            const ms = typeof result.ms === 'number' ? result.ms : 0;
-            return { ok, fetched, ms };
-        }
-        return null;
+        workers = g && g.__NS_HMR_WORKERS__;
     }
-    catch (error) {
-        if (verbose && envVerbose) {
+    catch {
+        // fall through with `workers === undefined`
+    }
+    let fallbackTerminated = 0;
+    let fallbackFailed = 0;
+    const fallbackTotal = workers && typeof workers.size === 'number' ? workers.size : 0;
+    if (!nativeApi && workers && fallbackTotal > 0) {
+        // No native API — drain the JS-tracked Set as the primary path.
+        for (const worker of workers) {
             try {
-                console.warn('[hmr-angular] __nsKickstartHmrPrefetch threw', error?.message || error);
+                if (worker && typeof worker.terminate === 'function') {
+                    worker.terminate();
+                    fallbackTerminated++;
+                }
             }
-            catch { }
+            catch {
+                fallbackFailed++;
+            }
+        }
+    }
+    if (workers) {
+        try {
+            workers.clear();
         }
-        return null;
+        catch { }
+    }
+    // Surface ONE concise log per HMR cycle when there was actually work
+    // to do. This isn't gated on `verbose` so the user can see in the
+    // dev terminal which cleanup tier ran without flipping a flag —
+    // it's a single line per HMR-cycle-with-workers, never per cycle
+    // when no workers exist. Filter on "actually did something" so we
+    // stay quiet on no-worker apps and on cycles where neither tier
+    // found anything.
+    if (nativeApi && (nativeTerminated ?? 0) > 0) {
+        console.info(`[ns-hmr][workers] terminated ${nativeTerminated} via the runtime's ns:runtime terminateAllWorkers before reboot`);
+    }
+    else if (!nativeApi && fallbackTerminated > 0) {
+        console.info(`[ns-hmr][workers] terminated ${fallbackTerminated}/${fallbackTotal} via JS-tracked Set before reboot (ns:runtime terminateAllWorkers not exposed by this runtime)`);
+    }
+}
+// Narrow an unknown eviction-list entry to a fetchable http(s) URL. Shared by
+// the reboot path (refreshAngularBootstrapOptions) and the leaf re-import
+// fallback so the two stay in lockstep on what counts as a valid evict URL.
+const isHttpUrl = (u) => typeof u === 'string' && /^https?:\/\//.test(u);
+function invalidateModules(urls, verbose) {
+    if (!urls || !urls.length)
+        return false;
+    const fn = readNsRuntimeDevHostApi(globalThis).invalidateModules;
+    if (typeof fn !== 'function') {
+        console.warn(`[ns-hmr][client] runtime missing ns:runtime invalidateModules (runtime/vite version mismatch?); update cannot apply. evict=${urls.length}`);
+        return false;
+    }
+    try {
+        if (verbose && envVerbose) {
+            console.info(`[ns-hmr][client] invalidateModules calling ns:runtime invalidateModules urls=${urls.length}`);
+        }
+        fn.call(null, urls.slice());
+        if (verbose && envVerbose) {
+            console.info(`[ns-hmr][client] invalidateModules OK urls=${urls.length}`);
+        }
+        return true;
+    }
+    catch (error) {
+        // Real exception path — the runtime hook itself threw. Always
+        // surfaced for the same reason as the missing-hook warn above.
+        console.warn('[ns-hmr][client] ns:runtime invalidateModules threw', error?.message || error);
+        return false;
     }
 }
 function getAngularBootstrapEntryCandidates(msg) {
-    const root = typeof __NS_APP_ROOT_VIRTUAL__ === 'string' && __NS_APP_ROOT_VIRTUAL__ ? __NS_APP_ROOT_VIRTUAL__ : '/src';
+    // Define substitution does not reach this raw-served file; prefer the
+    // globalThis seed from the entry's defines-seed module ('app/'-rooted
+    // projects would otherwise get the wrong '/src' default).
+    const root = (typeof __NS_APP_ROOT_VIRTUAL__ === 'string' && __NS_APP_ROOT_VIRTUAL__) || (typeof getGlobalScope().__NS_APP_ROOT_VIRTUAL__ === 'string' && getGlobalScope().__NS_APP_ROOT_VIRTUAL__) || '/src';
     // Server announces the canonical bootstrap entry as
     // `importerEntry`, computed from `package.json#main`. Fall back to
     // the legacy `entryCandidates` array (for older servers) and finally
@@ -275,7 +403,23 @@ export async function refreshAngularBootstrapOptions(msg, options) {
     // `g_moduleRegistry` so V8's subsequent `import(entry)` walks the
     // dep graph and re-fetches ONLY those modules. Everything else stays
     // hot in the cache.
-    const evictPaths = Array.isArray(msg?.evictPaths) ? msg.evictPaths.filter((u) => typeof u === 'string' && /^https?:\/\//.test(u)) : [];
+    const evictPaths = Array.isArray(msg?.evictPaths) ? msg.evictPaths.filter(isHttpUrl) : [];
+    // Diagnostic: log eviction set client-side so we can verify what
+    // the runtime is being asked to drop. Up to 32 entries are sampled
+    // so large constants edits don't swamp the console. Gated behind
+    // the standard `__NS_ENV_VERBOSE__` build define (`NS_VITE_VERBOSE`)
+    // so the lines stay silent on normal saves.
+    if (options.verbose && envVerbose) {
+        const _path = typeof msg?.path === 'string' ? msg.path : '(unknown)';
+        console.info(`[ns-hmr][client] received ns:angular-update path=${_path} evictPaths.length=${evictPaths.length} importerEntry=${msg?.importerEntry ?? '(none)'}`);
+        if (evictPaths.length) {
+            const sample = evictPaths.slice(0, 32);
+            console.info(`[ns-hmr][client] evictPaths firstN=`, sample);
+            if (evictPaths.length > sample.length) {
+                console.info(`[ns-hmr][client] evictPaths hidden=${evictPaths.length - sample.length}`);
+            }
+        }
+    }
     // Drive the apply-progress overlay through the 'evicting' frame
     // *before* the runtime invalidate call so the user sees the count
     // even on the cheapest stage. Eviction count also doubles as a
@@ -287,70 +431,19 @@ export async function refreshAngularBootstrapOptions(msg, options) {
     });
     const evicted = invalidateModules(evictPaths, options.verbose);
     if (options.verbose && envVerbose) {
-        try {
-            console.info(`[ns-hmr][angular] evict count=${evictPaths.length} ok=${evicted ? 'yes' : 'no'}`);
-        }
-        catch { }
+        console.info(`[ns-hmr][client] evict count=${evictPaths.length} ok=${evicted ? 'yes' : 'no'}`);
     }
-    // Parallel HTTP prefetch for the freshly-evicted modules.
-    //
-    // Order matters here: the kickstart MUST run after the eviction so
-    // that it actually re-populates `g_prefetchCache` for the modules
-    // V8 will ask for. If we kickstarted before the eviction, every URL
-    // would skip on the "already cached" check (the walk consumes
-    // destructively but the prior non-evicted modules sit in V8's
-    // `g_moduleRegistry`, not the prefetch cache).
-    //
-    // We only kickstart when the eviction succeeded, because the
-    // fallback path (legacy URL-versioning, see `useStableUrls = evicted`
-    // below) doesn't go through canonical /ns/m URLs and the runtime
-    // would not match its prefetch cache lookups against the version-
-    // prefixed forms V8 will end up requesting. Better to skip the
-    // optimization than risk a confusing partial cache hit.
-    //
-    // `shouldRunKickstart` gates large eviction sets out of the
-    // parallel wave. A `.ts` file with deep inverse-dep fan-in
-    // (constants files, design-system enums) can produce a
-    // 200–300-URL closure that overwhelms Vite's single-threaded
-    // transform pipeline. The kickstart fan-out then makes the cycle
-    // 5–8× slower than letting V8 fetch sequentially as it walks the
-    // real forward path. The cap (default 32, override with
-    // `NS_VITE_KICKSTART_MAX_URLS`) keeps component-shaped closures
-    // (typically 5–30 URLs) on the fast path. Correctness is
-    // unaffected — V8's per-module synchronous fetch is the same fall-
-    // back code path the runtime has always used.
-    if (evicted && evictPaths.length > 0) {
-        if (shouldRunKickstart(evictPaths.length)) {
-            const result = kickstartHmrPrefetch(evictPaths, options.verbose);
-            if (options.verbose && envVerbose && result) {
-                try {
-                    console.info(`[ns-hmr][angular] kickstart urls=${evictPaths.length} fetched=${result.fetched} ok=${result.ok ? 'yes' : 'no'} ms=${result.ms}`);
-                }
-                catch { }
-            }
-        }
-        else if (options.verbose && envVerbose) {
-            try {
-                console.info(`[ns-hmr][angular] kickstart skipped urls=${evictPaths.length} cap=${Number.isFinite(kickstartMaxUrls) ? kickstartMaxUrls : 'Infinity'} (eviction set too large; falling back to sequential fetch)`);
-            }
-            catch { }
-        }
-    }
-    // URL strategy:
-    //
-    // * `evicted=true`  → modern runtime accepted the eviction; we
-    //   re-import the entry under its STABLE canonical URL. V8's
-    //   registry no longer holds the evicted modules so the import
-    //   triggers fresh fetches for them; the rest of the graph is a
-    //   cache hit.
-    // * `evicted=false` → either we have no eviction set (older server)
-    //   or the runtime lacks `__nsInvalidateModules` (older runtime).
-    //   Fall back to the legacy `__ns_hmr__/v<version>/` URL pattern so
-    //   V8 sees a fresh URL and re-fetches the entry. The runtime
-    //   canonicalizer collapses the path back to the stable key, which
-    //   keeps cache identity consistent across saves.
-    const versionRaw = typeof msg?.version === 'number' ? msg.version : 0;
-    const useStableUrls = evicted;
+    // No client-side prefetch is needed after the eviction: the runtime's
+    // async module-graph walk fetches the evicted modules concurrently on
+    // background threads when the re-import below triggers it.
+    // URL strategy: always the STABLE canonical URL. The eviction removed
+    // the changed modules from V8's registry (and armed the runtime's
+    // bust-next-fetch nonce), so re-importing the entry under its
+    // canonical URL triggers fresh fetches for exactly the evicted
+    // modules; the rest of the graph is a cache hit. Never version or
+    // tag the URL — the runtime treats the literal URL as module
+    // identity, so a tagged re-import would mint a second module
+    // identity instead of refreshing the first.
     let lastError;
     // 'reimporting' is the entry point for the long tail of an HMR
     // cycle: V8 walks the freshly-evicted graph and the iOS runtime
@@ -361,7 +454,7 @@ export async function refreshAngularBootstrapOptions(msg, options) {
         detail: 'Re-importing Angular bootstrap entry',
     });
     for (const entry of getAngularBootstrapEntryCandidates(msg)) {
-        const url = useStableUrls ? `${origin}/ns/m${entry}` : versionRaw ? `${origin}/ns/m/__ns_hmr__/v${versionRaw}${entry}` : `${origin}/ns/m${entry}`;
+        const url = `${origin}/ns/m${entry}`;
         try {
             g.__NS_ANGULAR_HMR_REGISTER_ONLY__ = true;
             await importAngularBootstrapEntry(url);
@@ -375,10 +468,7 @@ export async function refreshAngularBootstrapOptions(msg, options) {
         }
     }
     if (options.verbose && envVerbose && lastError) {
-        try {
-            console.warn('[hmr-angular] failed to refresh Angular bootstrap entry', lastError?.message || lastError);
-        }
-        catch { }
+        console.warn('[hmr-angular] failed to refresh Angular bootstrap entry', lastError?.message || lastError);
     }
 }
 export async function handleAngularHotUpdateMessage(msg, options) {
@@ -410,15 +500,12 @@ export async function handleAngularHotUpdateMessage(msg, options) {
     let tEnd = t0;
     const filePath = typeof msg?.path === 'string' ? msg.path : '<unknown>';
     const emitTiming = (ok, errorMessage) => {
-        try {
-            const refreshMs = Math.max(0, tAfterRefresh - t0);
-            const rebootMs = Math.max(0, tEnd - tAfterRefresh);
-            const totalMs = Math.max(0, tEnd - t0);
-            const status = ok ? 'ok' : 'FAILED';
-            const suffix = errorMessage ? ` error=${errorMessage}` : '';
-            console.info(`[ns-hmr][angular] ${status} file=${filePath} refresh=${refreshMs}ms reboot=${rebootMs}ms total=${totalMs}ms${suffix}`);
-        }
-        catch { }
+        const refreshMs = Math.max(0, tAfterRefresh - t0);
+        const rebootMs = Math.max(0, tEnd - tAfterRefresh);
+        const totalMs = Math.max(0, tEnd - t0);
+        const status = ok ? 'ok' : 'FAILED';
+        const suffix = errorMessage ? ` error=${errorMessage}` : '';
+        console.info(`[ns-hmr][angular] ${status} file=${filePath} refresh=${refreshMs}ms reboot=${rebootMs}ms total=${totalMs}ms${suffix}`);
     };
     // Show the apply-progress overlay as soon as the
     // mutex unblocks us. Posting this *after* the awaited
@@ -432,6 +519,31 @@ export async function handleAngularHotUpdateMessage(msg, options) {
     setUpdateOverlayStage('received', { detail: overlayDetail });
     try {
         const g = globalThis;
+        // Vite-spec entry: `vite:beforeUpdate` fires as soon as the
+        // client receives an update message, BEFORE any work begins
+        // (refresh, dispose, reboot). User listeners can use this to
+        // pause animations, cancel in-flight requests, etc. Payload
+        // matches Vite's `Update[]` shape loosely — `path` is the
+        // canonical changed file, `evictPaths` is the eviction
+        // closure the server already computed.
+        const updatePayload = {
+            type: 'js-update',
+            path: typeof msg?.path === 'string' ? msg.path : null,
+            evictPaths: Array.isArray(msg?.evictPaths) ? msg.evictPaths : [],
+            timestamp: t0,
+        };
+        dispatchHotEvent(g, 'vite:beforeUpdate', { updates: [updatePayload] });
+        // Declined-module short-circuit. If any updated module called
+        // `import.meta.hot.decline()`, we MUST do a full reload per
+        // Vite spec rather than the hot-update path. `triggerFullReload`
+        // also dispatches `vite:beforeFullReload`. The reload tears the
+        // JS realm down so we don't need to do any further bookkeeping
+        // here — return early.
+        if (checkDeclinedAndReload(g, msg, options)) {
+            tEnd = Date.now();
+            emitTiming(true);
+            return true;
+        }
         // Prefer __reboot_ng_modules__ — it properly disposes existing modules,
         // re-bootstraps Angular inside NgZone, and sets the root view internally.
         // __NS_ANGULAR_BOOTSTRAP__ is exposed as a secondary signal that the
@@ -440,8 +552,23 @@ export async function handleAngularHotUpdateMessage(msg, options) {
         const reboot = g.__reboot_ng_modules__;
         if (typeof reboot === 'function') {
             if (options.verbose && envVerbose) {
-                console.log('[hmr-angular] rebooting Angular modules via __reboot_ng_modules__');
+                console.info('[ns-hmr][client] calling __reboot_ng_modules__');
             }
+            // Pre-import reset: clear Angular's `GENERATED_COMP_IDS` map BEFORE
+            // the changed component modules are re-imported. If we don't, every
+            // touched component's `ɵɵdefineComponent` call hashes to the same
+            // id as its predecessor (selectors + className haven't changed),
+            // hits a "previousCompDefType !== componentDef.type" collision, and
+            // surfaces NG0912 "Component ID generation collision detected".
+            // The map is cleared again post-reboot as a safety net, but doing
+            // it once here suppresses the warning at the source.
+            try {
+                const preResetCompiled = g.__reset_ng_compiled_components__;
+                if (typeof preResetCompiled === 'function') {
+                    preResetCompiled();
+                }
+            }
+            catch { }
             await refreshAngularBootstrapOptions(msg, options);
             tAfterRefresh = Date.now();
             try {
@@ -452,6 +579,42 @@ export async function handleAngularHotUpdateMessage(msg, options) {
                 g.__NS_DEV_RESET_IN_PROGRESS__ = true;
             }
             catch { }
+            // Two-step pre-reboot cleanup. Order matters: dispose runs
+            // FIRST so user-code disposers see a still-live runtime
+            // (sockets, workers, etc.) and can issue graceful "I'm
+            // going away" messages; then we hard-terminate any worker
+            // the user didn't manually clean up.
+            //
+            // Step 1 — `import.meta.hot.dispose(cb)` callbacks
+            // ────────────────────────────────────────────────
+            // The JS hot registry (`hot-context.ts`) walks its
+            // per-module dispose map — populated by
+            // `import.meta.hot.dispose(cb)` — and invokes every
+            // callback with that module's `hot.data` object, matching
+            // the Vite spec.
+            //
+            // This is the standards-compliant cleanup hook every Vite
+            // user already knows. Apps register their intervals,
+            // listeners, sockets, store subscriptions, etc. via
+            // `import.meta.hot.dispose(...)` and they're guaranteed to
+            // fire before the next Angular reboot — no NS-specific
+            // knowledge required.
+            runHmrDisposeCallbacks(g, options);
+            // Step 2 — worker auto-terminate (defence in depth)
+            // ───────────────────────────────────────────────────
+            // Even with perfect dispose() coverage, workers spawned
+            // from constructors that re-run on Angular reboot (e.g.
+            // `new Worker(...)` inside `AppComponent`'s constructor)
+            // don't fire dispose for `app.component.ts` when only
+            // `login.component.html` changes — `app.component.ts`
+            // isn't being replaced, so its disposers don't run per
+            // Vite spec. The runtime API
+            // (ns:runtime `terminateAllWorkers()`) doesn't care about module
+            // boundaries; it just kills every live worker in
+            // `Caches::Workers`. Falls back to the
+            // `__NS_HMR_WORKERS__` JS Set when the runtime doesn't
+            // expose the primitive.
+            terminateTrackedWorkers(g, options);
             // 'rebooting' marks the long tail of the cycle: NgZone
             // teardown, module re-instantiation, and resetRootView.
             // The detail line shows refresh-so-far ms so a user can
@@ -459,6 +622,12 @@ export async function handleAngularHotUpdateMessage(msg, options) {
             setUpdateOverlayStage('rebooting', {
                 detail: `Re-bootstrapping Angular (refresh ${Math.max(0, tAfterRefresh - t0)}ms)`,
             });
+            // Tailwind content CSS belongs to this same save. Fetch and install it
+            // inside the serialized Angular cycle, immediately before constructing
+            // the replacement tree. This prevents a standalone CSS message from
+            // racing teardown, while allowing the new views to resolve both existing
+            // bindings and newly generated utility selectors during construction.
+            await applyDeferredCssUpdates(msg);
             try {
                 reboot(true);
             }
@@ -470,6 +639,12 @@ export async function handleAngularHotUpdateMessage(msg, options) {
             }
             tEnd = Date.now();
             emitTiming(true);
+            // Vite-spec exit: `vite:afterUpdate` fires after the update
+            // has been successfully applied. User code can re-attach
+            // any state torn down by `vite:beforeUpdate` (resume
+            // animations, re-fetch, etc.). Same payload shape as
+            // `vite:beforeUpdate` so listeners can correlate.
+            dispatchHotEvent(g, 'vite:afterUpdate', { updates: [updatePayload] });
             // 'complete' surfaces the wall-clock total so a user gets a
             // single-glance confirmation matching the [ns-hmr][angular]
             // log line in the terminal. The overlay auto-hides shortly
@@ -479,24 +654,85 @@ export async function handleAngularHotUpdateMessage(msg, options) {
             });
             return true;
         }
+        // Reached only when the NgModule reboot path above was skipped — i.e.
+        // `g.__reboot_ng_modules__` was not a function at the time this update
+        // arrived, so no full re-bootstrap ran. (That handler is installed by
+        // `runNativeScriptAngularApp()`, so this is NOT about how the app boots;
+        // it covers the window where the handler isn't registered yet, or any
+        // update that never wires one up.) Fall back to the standard Vite
+        // leaf-module path: evict + re-import the changed module(s) so their
+        // top-level side-effects and `import.meta.hot.accept` callbacks re-run
+        // WITHOUT a full reboot. The server narrows leaf edits (no @Component/
+        // @Directive/@Pipe/@Injectable/@NgModule decorator) to just the changed
+        // file, so this is cheap. This is what makes self-accepting utility
+        // modules (e.g. a live-tuning module that posts values to native on
+        // evaluation) hot-reload at all — without it they were silently dropped
+        // here.
+        try {
+            const origin = (typeof g.__NS_HTTP_ORIGIN__ === 'string' ? g.__NS_HTTP_ORIGIN__ : '').replace(/\/$/, '');
+            let urls = Array.isArray(msg?.evictPaths) ? msg.evictPaths.filter(isHttpUrl) : [];
+            // Derive the canonical /ns/m/<rel> URL from msg.path when the server
+            // sent no evictPaths (V8 keys app modules by their extensionless URL).
+            if (!urls.length && typeof msg?.path === 'string' && origin) {
+                const rel = msg.path.replace(/^\//, '').replace(/\.(?:[mc]?[jt]sx?)$/i, '');
+                urls = [`${origin}/ns/m/${rel}`];
+            }
+            if (urls.length) {
+                setUpdateOverlayStage('reimporting', { detail: `Re-importing ${urls.length} module${urls.length === 1 ? '' : 's'}` });
+                invalidateModules(urls, options.verbose);
+                const nonce = (typeof g.__NS_HMR_IMPORT_NONCE__ === 'number' ? g.__NS_HMR_IMPORT_NONCE__ : 0) + 1;
+                g.__NS_HMR_IMPORT_NONCE__ = nonce;
+                let reimported = 0;
+                for (const u of urls) {
+                    try {
+                        await importAngularBootstrapEntry(`${u}${u.includes('?') ? '&' : '?'}hmr=${nonce}`);
+                        reimported++;
+                    }
+                    catch (e) {
+                        if (options.verbose) {
+                            console.warn('[ns-hmr][leaf] re-import failed', u, (e && e.message) || e);
+                        }
+                    }
+                }
+                const ok = reimported > 0;
+                tEnd = Date.now();
+                emitTiming(ok, ok ? 'leaf-reimport' : 'leaf-reimport-failed');
+                hideUpdateOverlay();
+                return ok;
+            }
+        }
+        catch (e) {
+            if (options.verbose) {
+                console.warn('[ns-hmr][leaf] fallback threw', (e && e.message) || e);
+            }
+        }
         if (options.verbose && envVerbose) {
             console.warn('[hmr-angular] No Angular HMR handler found. Ensure runNativeScriptAngularApp() has been called.');
         }
         tEnd = Date.now();
         emitTiming(false, 'no-reboot-handler');
-        // No reboot handler → we can't apply the update; hide the
-        // overlay rather than leaving stale progress on screen.
+        // No reboot handler and nothing to re-import → hide the overlay rather
+        // than leaving stale progress on screen.
         hideUpdateOverlay();
     }
     catch (error) {
         if (options.verbose) {
-            try {
-                console.warn('[hmr-angular] failed to handle update', (error && error.message) || error);
-            }
-            catch { }
+            console.warn('[hmr-angular] failed to handle update', (error && error.message) || error);
         }
         tEnd = Date.now();
-        emitTiming(false, (error && error.message) || String(error));
+        const errorMessage = (error && error.message) || String(error);
+        emitTiming(false, errorMessage);
+        // Vite-spec error event — fires on any HMR cycle that throws.
+        // Payload shape mirrors Vite's `ErrorPayload`: `err: { message,
+        // stack? }` plus optional `path`. Soft-fails if no listeners.
+        dispatchHotEvent(globalThis, 'vite:error', {
+            type: 'error',
+            err: {
+                message: errorMessage,
+                stack: (error && error.stack) || undefined,
+            },
+            path: typeof msg?.path === 'string' ? msg.path : undefined,
+        });
         // Errors → drop the overlay so the user isn't left looking
         // at indefinite progress; the underlying error is already
         // logged above (and surfaced via Vite's standard error