@nativescript/vite 8.0.0-alpha.2 → 8.0.0-alpha.20

package/hmr/client/index.js

@@ -5,9 +5,42 @@
  * Always resolve core classes and Application from the vendor realm or globalThis at runtime.
  * The HMR client is evaluated via HTTP ESM on device; static imports would create secondary instances.
  */
-import { setHMRWsUrl, getHMRWsUrl, pendingModuleFetches, deriveHttpOrigin, setHttpOriginForVite, moduleFetchCache, requestModuleFromServer, getHttpOriginForVite, normalizeSpec, hmrMetrics, graph, setGraphVersion, getGraphVersion, getCurrentApp, getRootFrame, setCurrentApp, setRootFrame, getCore } from './utils.js';
+import { setHMRWsUrl, getHMRWsUrl, pendingModuleFetches, deriveHttpOrigin, setHttpOriginForVite, moduleFetchCache, requestModuleFromServer, getHttpOriginForVite, normalizeSpec, hmrMetrics, graph, setGraphVersion, getGraphVersion, getCurrentApp, getRootFrame, setCurrentApp, setRootFrame, getCore, hasExplicitEviction, invalidateModulesByUrls, buildEvictionUrls, emitHmrModeBannerOnce } from './utils.js';
 import { handleCssUpdates } from './css-handler.js';
+import { buildCssApplyingDetail, buildCssAppliedDetail } from './css-update-overlay.js';
 const VERBOSE = typeof __NS_ENV_VERBOSE__ !== 'undefined' && __NS_ENV_VERBOSE__;
+function resolveTargetFlavor() {
+    try {
+        if (typeof __NS_TARGET_FLAVOR__ !== 'undefined' && __NS_TARGET_FLAVOR__) {
+            return __NS_TARGET_FLAVOR__;
+        }
+    }
+    catch { }
+    try {
+        const g = globalThis;
+        if (typeof g.__NS_TARGET_FLAVOR__ === 'string' && g.__NS_TARGET_FLAVOR__) {
+            return g.__NS_TARGET_FLAVOR__;
+        }
+        if (typeof g.__NS_HMR_BROWSER_RUNTIME_TARGET_FLAVOR__ === 'string' && g.__NS_HMR_BROWSER_RUNTIME_TARGET_FLAVOR__) {
+            return g.__NS_HMR_BROWSER_RUNTIME_TARGET_FLAVOR__;
+        }
+        if (typeof g.__reboot_ng_modules__ === 'function') {
+            return 'angular';
+        }
+        if (g.__VUE_HMR_RUNTIME__ || g.__NS_HMR_VUE_SFC_REGISTRY__) {
+            return 'vue';
+        }
+    }
+    catch { }
+    return undefined;
+}
+const TARGET_FLAVOR = resolveTargetFlavor();
+try {
+    if (TARGET_FLAVOR && !globalThis.__NS_TARGET_FLAVOR__) {
+        globalThis.__NS_TARGET_FLAVOR__ = TARGET_FLAVOR;
+    }
+}
+catch { }
 const APP_ROOT_VIRTUAL = typeof __NS_APP_ROOT_VIRTUAL__ === 'string' && __NS_APP_ROOT_VIRTUAL__ ? __NS_APP_ROOT_VIRTUAL__ : '/src';
 const APP_VIRTUAL_WITH_SLASH = APP_ROOT_VIRTUAL.endsWith('/') ? APP_ROOT_VIRTUAL : `${APP_ROOT_VIRTUAL}/`;
 const APP_MAIN_ENTRY_SPEC = `${APP_VIRTUAL_WITH_SLASH}app.ts`;
@@ -29,8 +62,9 @@ function ensureCoreAliasesOnGlobalThis() {
         }
         catch { }
         try {
-            if (A && !g.Application)
+            if (A && (!g.Application || typeof g.Application.run !== 'function' || typeof g.Application.on !== 'function' || typeof g.Application.resetRootView !== 'function')) {
                 g.Application = A;
+            }
         }
         catch { }
         try {
@@ -68,6 +102,80 @@ function hideConnectionOverlay() {
     }
     catch { }
 }
+function setUpdateOverlayStage(stage, info) {
+    try {
+        const api = getHmrOverlayApi();
+        if (api && typeof api.setUpdateStage === 'function') {
+            api.setUpdateStage(stage, info);
+        }
+    }
+    catch { }
+}
+// Store the listener registry on globalThis (rather than in a module-private
+// closure) because in NativeScript the HMR client module and the user app
+// modules can resolve to different module instances depending on how the
+// dev runtime loads them (HTTP client URL vs. the bundled vendor realm).
+// A module-local Set would not be shared across instances; the global one
+// is.
+function getNsSolidHmrListenerSet() {
+    const g = globalThis;
+    let set = g.__ns_solid_hmr_listener_set;
+    if (!set) {
+        set = new Set();
+        g.__ns_solid_hmr_listener_set = set;
+    }
+    return set;
+}
+function nsSolidHmrSubscribe(fn) {
+    const listeners = getNsSolidHmrListenerSet();
+    listeners.add(fn);
+    if (VERBOSE)
+        console.log('[hmr][solid] subscribe — listeners=', listeners.size);
+    return () => listeners.delete(fn);
+}
+function nsSolidHmrEmit(ev) {
+    const listeners = getNsSolidHmrListenerSet();
+    if (VERBOSE)
+        console.log('[hmr][solid] emit listeners=', listeners.size, 'changedFiles=', ev.changedFiles);
+    for (const fn of Array.from(listeners)) {
+        try {
+            fn(ev);
+        }
+        catch (err) {
+            if (VERBOSE)
+                console.warn('[hmr][solid] listener threw', err);
+        }
+    }
+}
+try {
+    const g = globalThis;
+    g.__ns_solid_hmr_subscribe = nsSolidHmrSubscribe;
+    // Eagerly create the listener set so the global exists at module load time.
+    getNsSolidHmrListenerSet();
+    if (VERBOSE)
+        console.log('[hmr][solid] HMR client loaded. global set=', typeof g.__ns_solid_hmr_subscribe, 'listenerSet=', typeof g.__ns_solid_hmr_listener_set);
+}
+catch (err) {
+    console.warn('[hmr][solid] could not install global __ns_solid_hmr_subscribe', err);
+}
+// Eagerly drive the HMR-applying overlay's 'received' frame as soon
+// as the server emits `ns:hmr-pending`, BEFORE the framework-specific
+// (`ns:angular-update` / `ns:css-updates`) payload arrives. The
+// flavor-specific handler later walks through 'evicting' →
+// 'reimporting' → 'rebooting' → 'complete'. Calling 'received' twice
+// in the same cycle is safe: the overlay preserves
+// `updateCycleStartedAt` when a 'received' frame replaces an existing
+// 'received' frame so the minimum-visible window is still timed
+// against the FIRST frame.
+//
+// Soft-fails when the overlay isn't installed (production builds,
+// vitest, etc.) or when the user opted out via
+// `__NS_HMR_PROGRESS_OVERLAY_ENABLED__ === false`.
+import { applyHmrPendingFrame } from './hmr-pending-overlay.js';
+import { driveVueSfcUpdateOverlay } from './vue-sfc-update-overlay.js';
+function setHmrPendingOverlay(filePath) {
+    applyHmrPendingFrame(filePath, { getOverlay: getHmrOverlayApi });
+}
 let connectionOverlayTimer = null;
 let connectionOverlayVisible = false;
 let hasOpenedHmrSocket = false;
@@ -114,7 +222,7 @@ function markHmrConnectionHealthy() {
  */
 import { installNsVueDevShims, ensureBackWrapperInstalled, getRootForVue, loadSfcComponent, ensureVueGlobals, ensurePiniaOnApp, addSfcMapping, recordVuePayloadChanges, handleVueSfcRegistry, handleVueSfcRegistryUpdate, sfcArtifactMap } from '../frameworks/vue/client/index.js';
 import { handleAngularHotUpdateMessage, installAngularHmrClientHooks } from '../frameworks/angular/client/index.js';
-switch (__NS_TARGET_FLAVOR__) {
+switch (TARGET_FLAVOR) {
     case 'vue':
         installNsVueDevShims();
         break;
@@ -171,7 +279,7 @@ function applyFullGraph(payload) {
     try {
         const g = globalThis;
         const bootDone = !!g.__NS_HMR_BOOT_COMPLETE__;
-        if (!bootDone && !initialMounted && !initialMounting && !g.__NS_HMR_RESCUE_SCHEDULED__ && __NS_TARGET_FLAVOR__ !== 'typescript') {
+        if (!bootDone && !initialMounted && !initialMounting && !g.__NS_HMR_RESCUE_SCHEDULED__ && TARGET_FLAVOR !== 'typescript') {
             // simple snapshot helpers
             const getTopmost = () => {
                 try {
@@ -244,7 +352,7 @@ function applyFullGraph(payload) {
                     if (VERBOSE)
                         console.log('[hmr][init] placeholder persists after delay; evaluating rescue policy');
                     // Flavor-specific rescue handling
-                    if (__NS_TARGET_FLAVOR__ === 'typescript') {
+                    if (TARGET_FLAVOR === 'typescript') {
                         // For TS apps, perform a one-time resetRootView to the conventional
                         // app root module. This mimics what Application.run would do and
                         // replaces the placeholder with the real UI without trying to
@@ -285,7 +393,7 @@ function applyFullGraph(payload) {
                         return;
                     }
                     let candidate = null;
-                    switch (__NS_TARGET_FLAVOR__) {
+                    switch (TARGET_FLAVOR) {
                         case 'vue': {
                             const appEntry = graph.get(APP_MAIN_ENTRY_SPEC);
                             if (appEntry && Array.isArray(appEntry.deps)) {
@@ -327,7 +435,7 @@ function applyFullGraph(payload) {
                     (async () => {
                         try {
                             let comp = null;
-                            switch (__NS_TARGET_FLAVOR__) {
+                            switch (TARGET_FLAVOR) {
                                 case 'vue':
                                     comp = await loadSfcComponent(candidate, 'initial_mount_rescue');
                                     break;
@@ -372,7 +480,7 @@ function applyFullGraph(payload) {
         // to avoid double-mount races that can cause duplicate navigation logs.
         if (ALLOW_INITIAL_MOUNT && !initialMounted && !bootDone && !bootInProgress && !getCurrentApp() && !getRootFrame()) {
             let candidate = null;
-            switch (__NS_TARGET_FLAVOR__) {
+            switch (TARGET_FLAVOR) {
                 case 'vue': {
                     const appEntry = graph.get(APP_MAIN_ENTRY_SPEC);
                     if (appEntry && Array.isArray(appEntry.deps)) {
@@ -416,7 +524,7 @@ function applyFullGraph(payload) {
                 (async () => {
                     try {
                         if (VERBOSE)
-                            console.log('[hmr][init] mounting initial root from', candidate, 'flavor=', __NS_TARGET_FLAVOR__);
+                            console.log('[hmr][init] mounting initial root from', candidate, 'flavor=', TARGET_FLAVOR);
                         // Android-only: avoid racing entry-runtime reset and Activity bring-up
                         try {
                             const g = globalThis;
@@ -450,7 +558,7 @@ function applyFullGraph(payload) {
                         }
                         catch { }
                         let comp = null;
-                        switch (__NS_TARGET_FLAVOR__) {
+                        switch (TARGET_FLAVOR) {
                             case 'vue':
                                 comp = await loadSfcComponent(candidate, 'initial_mount');
                                 break;
@@ -499,7 +607,7 @@ function applyFullGraph(payload) {
                 })();
             }
             else if (VERBOSE) {
-                console.warn('[hmr][init] no component found in graph to mount initially for flavor', __NS_TARGET_FLAVOR__);
+                console.warn('[hmr][init] no component found in graph to mount initially for flavor', TARGET_FLAVOR);
             }
         }
     }
@@ -525,7 +633,7 @@ function applyDelta(payload) {
         setGraphVersion(payload.newVersion);
     }
     const changed = payload.changed || [];
-    switch (__NS_TARGET_FLAVOR__) {
+    switch (TARGET_FLAVOR) {
         case 'vue':
             recordVuePayloadChanges(changed, getGraphVersion());
             break;
@@ -615,7 +723,7 @@ function applyDelta(payload) {
 // Deterministic navigation using the current Vue app instance rather than vendor-held rootApp
 function __nsNavigateUsingApp(comp, opts = {}) {
     const g = globalThis;
-    switch (__NS_TARGET_FLAVOR__) {
+    switch (TARGET_FLAVOR) {
         case 'vue':
             ensureVueGlobals();
             break;
@@ -642,8 +750,14 @@ function __nsNavigateUsingApp(comp, opts = {}) {
     const buildTarget = () => {
         const existingApp = getCurrentApp();
         const baseProvides = (existingApp && existingApp._context && existingApp._context.provides) || {};
-        const app = AppFactory(normalizeComponent(comp, comp && (comp.__name || comp.name)));
-        switch (__NS_TARGET_FLAVOR__) {
+        // Forward `opts.props` as Vue's rootProps so `$navigateTo(Comp, { props: { … } })`
+        // reaches the destination component. nativescript-vue's stock `$navigateTo`
+        // does the same via `createNativeView(target, options?.props, …)` →
+        // `renderer.createApp(component, props)`. Dropping props here would surface
+        // at the destination as `[Vue warn]: Missing required prop` and any
+        // required-prop component would render with `undefined` bindings.
+        const app = AppFactory(normalizeComponent(comp, comp && (comp.__name || comp.name)), opts && opts.props);
+        switch (TARGET_FLAVOR) {
             case 'vue':
                 ensurePiniaOnApp(app);
                 break;
@@ -777,7 +891,42 @@ async function processQueue() {
                 return;
             if (VERBOSE)
                 console.log('[hmr][queue] processing changed ids', drained);
+            // Track wall-clock so the 'complete' frame can show a meaningful
+            // total. Only the Solid + TypeScript flavors drive the overlay
+            // from here; Angular has its own flow inside
+            // `frameworks/angular/client/index.ts`.
+            const tQueueStart = Date.now();
+            const driveSolidOverlay = TARGET_FLAVOR === 'solid';
+            // Explicit eviction step.
+            //
+            // On modern runtimes the URL canonicalizer collapses any
+            // `__ns_hmr__/<tag>/` segment back to a stable cache key, so
+            // without explicit eviction the upcoming `import(url)` would
+            // resolve via V8's `g_moduleRegistry` and return the cached
+            // stale module — making the queue drain a silent no-op for
+            // every save after the first.
+            //
+            // We hand the canonical eviction URLs to the runtime first;
+            // `invalidateModulesByUrls` is a no-op on older runtimes and
+            // `requestModuleFromServer` automatically falls back to the
+            // legacy `/ns/m/__ns_hmr__/v<N>/` URL versioning path in that
+            // case. node_modules and virtual specs are filtered out by
+            // `buildEvictionUrls` so vendor modules stay hot.
+            if (driveSolidOverlay) {
+                setUpdateOverlayStage('evicting', {
+                    detail: drained.length === 1 ? `Invalidating ${drained[0]}` : `Invalidating ${drained.length} modules`,
+                });
+            }
+            const evictUrls = buildEvictionUrls(drained);
+            const evicted = invalidateModulesByUrls(evictUrls);
+            if (VERBOSE)
+                console.log(`[hmr][queue] eviction count=${evictUrls.length} ok=${evicted}`);
             // Evaluate changed modules best-effort; failures shouldn't completely break HMR.
+            if (driveSolidOverlay) {
+                setUpdateOverlayStage('reimporting', {
+                    detail: drained.length === 1 ? `Re-importing ${drained[0]}` : `Re-importing ${drained.length} modules`,
+                });
+            }
             for (const id of drained) {
                 try {
                     const spec = normalizeSpec(id);
@@ -794,11 +943,36 @@ async function processQueue() {
                 }
             }
             // After evaluating the batch, perform flavor-specific UI refresh.
-            switch (__NS_TARGET_FLAVOR__) {
+            switch (TARGET_FLAVOR) {
                 case 'vue':
-                    // Vue SFCs are handled via the registry update path; nothing to do here.
+                    // Vue SFCs are handled via the registry update path
+                    // (which drives its own overlay completion through
+                    // `driveVueSfcUpdateOverlay`); nothing else to do
+                    // for the view-tree refresh here.
+                    //
+                    // However, when a non-SFC file (e.g. a `.ts`
+                    // utility module imported by an SFC) is the only
+                    // changed entry, no `ns:vue-sfc-registry-update`
+                    // will follow — and without an explicit 'complete'
+                    // the overlay would stick on "Preparing update
+                    // (5%)". Drive the closing frame here so the
+                    // auto-hide timer can dismiss the toast in the
+                    // pure-TS-change case. The detail surfaces the
+                    // changed count so a user can correlate the
+                    // overlay with the server-side `[hmr-ws][update]`
+                    // log.
+                    setUpdateOverlayStage('complete', {
+                        detail: drained.length === 1 ? `Updated ${drained[0]} in ${Math.max(0, Date.now() - tQueueStart)}ms` : `Updated ${drained.length} modules in ${Math.max(0, Date.now() - tQueueStart)}ms`,
+                    });
                     break;
                 case 'solid': {
+                    // Boundaries discovered in this HMR cycle (tsx files reachable
+                    // via the reverse import graph from any changed file, plus route
+                    // files reachable from any tsx start point). Declared at the top
+                    // of the case block so the emit step below can include the
+                    // complete set in the listener event — framework integrations
+                    // use it to map route boundaries → fresh component references.
+                    const boundaries = new Set();
                     // Solid .tsx components are self-accepting via solid-refresh's inline
                     // patchRegistry — re-importing them is sufficient. For non-component
                     // .ts utility modules, we must propagate up the import graph to find
@@ -817,8 +991,10 @@ async function processQueue() {
                                 arr.push(id);
                             }
                         }
-                        // BFS from each non-tsx changed module up to tsx/jsx boundaries
-                        const boundaries = new Set();
+                        // Pass 1: BFS from each non-tsx changed module up to tsx/jsx
+                        // boundaries. These get re-imported below so solid-refresh's
+                        // inline patchRegistry runs and (best-effort) swaps the proxy
+                        // signals for any components defined in those tsx boundaries.
                         for (const id of drained) {
                             if (/\.(tsx|jsx)$/i.test(id))
                                 continue; // already self-accepting
@@ -842,6 +1018,51 @@ async function processQueue() {
                                 }
                             }
                         }
+                        // Pass 2: walk further from any tsx starting point (a tsx file
+                        // in `drained` OR a tsx boundary discovered in pass 1) to find
+                        // route files (`/src/routes/*.{tsx,jsx}`) that transitively
+                        // import them. Re-importing a route file refreshes its
+                        // `Route.options.component` to the freshly-imported reference
+                        // and the existing boundary loop below patches the live router
+                        // with that fresh reference.
+                        //
+                        // This is the key fix for "edit home.tsx → save → no visual
+                        // update": the old BFS skipped tsx files in `drained` (assuming
+                        // solid-refresh's in-place proxy patch was sufficient), but in
+                        // the universal-renderer + nested-context configuration that
+                        // patch does not always propagate to the visible page tree.
+                        // Adding the route file as a boundary lets us patch
+                        // `route.options.component` directly to a fresh module export,
+                        // which the framework subscriber then passes through to the
+                        // page remount — making the cycle robust to the proxy patch
+                        // silently failing.
+                        const tsxStarts = new Set();
+                        for (const id of drained) {
+                            if (/\.(tsx|jsx)$/i.test(id))
+                                tsxStarts.add(id);
+                        }
+                        for (const b of boundaries)
+                            tsxStarts.add(b);
+                        const ROUTE_FILE_RE = /\/src\/routes\/.+\.(tsx|jsx)$/i;
+                        for (const start of tsxStarts) {
+                            const visited = new Set();
+                            const queue = [start];
+                            while (queue.length) {
+                                const cur = queue.shift();
+                                if (visited.has(cur))
+                                    continue;
+                                visited.add(cur);
+                                if (cur !== start && ROUTE_FILE_RE.test(cur)) {
+                                    boundaries.add(cur);
+                                }
+                                const importers = reverseIndex.get(cur);
+                                if (!importers)
+                                    continue;
+                                for (const imp of importers) {
+                                    queue.push(imp);
+                                }
+                            }
+                        }
                         // Re-import each boundary so solid-refresh patchRegistry fires.
                         // For route files (TanStack Router), capture the new Route export
                         // and patch the router's existing route with the fresh loader.
@@ -891,6 +1112,15 @@ async function processQueue() {
                             }
                             return null;
                         };
+                        // Evict the boundary set so re-importing each .tsx
+                        // component actually picks up the new transitive
+                        // dependency code; without this V8 returns the
+                        // cached boundary module unchanged.
+                        const boundaryIds = Array.from(boundaries);
+                        const solidEvictUrls = buildEvictionUrls(boundaryIds);
+                        const solidEvicted = invalidateModulesByUrls(solidEvictUrls);
+                        if (VERBOSE)
+                            console.log(`[hmr][solid] eviction count=${solidEvictUrls.length} ok=${solidEvicted}`);
                         for (const id of boundaries) {
                             if (seen.has(id))
                                 continue;
@@ -902,22 +1132,28 @@ async function processQueue() {
                                 if (VERBOSE)
                                     console.log('[hmr][solid] propagated to boundary', { id, url });
                                 const mod = await import(/* @vite-ignore */ url);
-                                // Patch TanStack Router route loaders
+                                // Patch TanStack Router route options for any module
+                                // that exports a `Route`. We patch BOTH the component
+                                // and the loader (when present); components-only routes
+                                // were previously skipped because the gate required a
+                                // loader, which left their `options.component` pointing
+                                // at the stale module's exports after HMR.
                                 try {
                                     const newRoute = mod?.Route;
-                                    if (newRoute?.options?.loader) {
+                                    if (newRoute?.options) {
                                         const router = findRouter();
                                         const fullPath = boundaryToFullPath(id);
                                         if (VERBOSE)
-                                            console.log('[hmr][solid][diag] route patch attempt', { id, fullPath, hasRouter: !!router, routesByIdKeys: router?.routesById ? Object.keys(router.routesById) : 'none' });
+                                            console.log('[hmr][solid][diag] route patch attempt', { id, fullPath, hasRouter: !!router, hasLoader: !!newRoute.options.loader, hasComponent: !!newRoute.options.component });
                                         const existingRoute = fullPath && router ? findRouteByFullPath(router, fullPath) : null;
                                         if (existingRoute?.options) {
-                                            existingRoute.options.loader = newRoute.options.loader;
+                                            if (newRoute.options.loader)
+                                                existingRoute.options.loader = newRoute.options.loader;
                                             if (newRoute.options.component)
                                                 existingRoute.options.component = newRoute.options.component;
                                             routesPatchCount++;
                                             if (VERBOSE)
-                                                console.log('[hmr][solid] patched route loader', existingRoute.id, 'fullPath=', fullPath);
+                                                console.log('[hmr][solid] patched route', existingRoute.id, 'fullPath=', fullPath);
                                         }
                                         else if (VERBOSE) {
                                             console.log('[hmr][solid] no matching route for fullPath', fullPath);
@@ -953,6 +1189,44 @@ async function processQueue() {
                         if (VERBOSE)
                             console.warn('[hmr][solid] propagation failed', e);
                     }
+                    // Notify any framework integrations (e.g.
+                    // `@nativescript/tanstack-router`) that a Solid HMR
+                    // cycle has completed. They use this signal to perform
+                    // framework-specific UI refresh (e.g. remount the active
+                    // router page) when solid-refresh's own reactive
+                    // propagation does not reach the visible tree under
+                    // the current renderer/context configuration.
+                    //
+                    // Boundaries include both the directly-changed tsx files
+                    // AND every tsx ancestor reachable via the reverse import
+                    // graph (route files in particular). The framework
+                    // listener uses the route-file boundaries to look up the
+                    // freshly-patched `route.options.component` and pass it
+                    // through to the page remount.
+                    try {
+                        const tsxChangedInDrained = drained.filter((id) => /\.(tsx|jsx)$/i.test(id));
+                        const allBoundaries = Array.from(new Set([...tsxChangedInDrained, ...boundaries]));
+                        nsSolidHmrEmit({
+                            kind: 'solid',
+                            changedFiles: drained.slice(),
+                            boundaries: allBoundaries,
+                        });
+                    }
+                    catch (err) {
+                        if (VERBOSE)
+                            console.warn('[hmr][solid] emit failed', err);
+                    }
+                    // Tell the overlay the cycle is done. solid-refresh's
+                    // inline patchRegistry has already flushed the new
+                    // component bodies into the live tree (the `case
+                    // 'solid'` block above re-imports each .tsx
+                    // boundary), so by the time we get here the user is
+                    // already looking at the new render. The 'complete'
+                    // frame surfaces the wall-clock total and triggers
+                    // the overlay's auto-hide.
+                    setUpdateOverlayStage('complete', {
+                        detail: `Total ${Math.max(0, Date.now() - tQueueStart)}ms`,
+                    });
                     break;
                 }
                 case 'typescript': {
@@ -1132,6 +1406,10 @@ function connectHmr() {
             console.log('[hmr-client] Already connecting to HMR WebSocket, skipping');
         return;
     }
+    try {
+        globalThis.__NS_HMR_CLIENT_SOCKET_READY__ = false;
+    }
+    catch { }
     const overlayStage = hasOpenedHmrSocket ? 'reconnecting' : 'connecting';
     const baseUrl = getHMRWsUrl() || 'ws://localhost:5173/ns-hmr';
     const buildCandidates = (url) => {
@@ -1176,7 +1454,7 @@ function connectHmr() {
                     if (seen.has(key))
                         continue;
                     seen.add(key);
-                    const cand = `${p}://${host}:${port}${u.pathname || '/ns-hmr'}`;
+                    const cand = `${p}://${host}:${port}${u.pathname || '/ns-hmr'}${u.search || ''}`;
                     candidates.push(cand);
                 }
             }
@@ -1229,10 +1507,22 @@ function connectHmr() {
                 clearConnectionOverlayTimer();
                 hasOpenedHmrSocket = true;
                 awaitingHealthyHmrMessage = true;
+                try {
+                    globalThis.__NS_HMR_CLIENT_SOCKET_READY__ = true;
+                }
+                catch { }
                 if (connectionOverlayVisible) {
                     showConnectionOverlayNow('synchronizing', 'Connected. Synchronizing the HMR graph.');
                 }
                 VERBOSE && console.log('[hmr-client] Connected to HMR WebSocket');
+                // Print the active module reload mode once on first
+                // successful connect so the user can correlate HMR latency
+                // with runtime capability without grepping for protocol
+                // details. The banner is verbose-gated.
+                try {
+                    emitHmrModeBannerOnce();
+                }
+                catch { }
             };
             sock.onmessage = handleHmrMessage;
             sock.onerror = (error) => {
@@ -1241,6 +1531,10 @@ function connectHmr() {
             };
             sock.onclose = (ev) => {
                 clearTimeout(timeout);
+                try {
+                    globalThis.__NS_HMR_CLIENT_SOCKET_READY__ = false;
+                }
+                catch { }
                 if (!opened) {
                     // immediate failure during connect → try another candidate
                     if (VERBOSE)
@@ -1274,6 +1568,9 @@ async function handleHmrMessage(ev) {
     if (awaitingHealthyHmrMessage && msg) {
         markHmrConnectionHealthy();
     }
+    if (VERBOSE && msg?.type) {
+        console.log('[hmr-client] received message', msg.type);
+    }
     // Notify optional app-level hook after an HMR batch is applied.
     function notifyAppHmrUpdate(kind, changedIds) {
         try {
@@ -1285,6 +1582,17 @@ async function handleHmrMessage(ev) {
         catch { }
     }
     if (msg) {
+        // `ns:hmr-pending` is a fire-and-forget UX hint emitted by the
+        // server at the START of handleHotUpdate. We drive the
+        // HMR-applying overlay's 'received' frame here (synchronously),
+        // well before the authoritative payload (`ns:angular-update` /
+        // `ns:css-updates`) lands. Skip running any other handlers —
+        // the pending message has no module payload and intentionally
+        // does not bump the graph version.
+        if (msg.type === 'ns:hmr-pending' && typeof msg.path === 'string') {
+            setHmrPendingOverlay(msg.path);
+            return;
+        }
         if (msg.type === 'ns:hmr-full-graph') {
             // Bump a monotonic nonce so HTTP ESM imports can always be cache-busted per update.
             try {
@@ -1354,6 +1662,14 @@ async function handleHmrMessage(ev) {
                 });
                 if (toReimport.length && VERBOSE)
                     console.log('[hmr][full-graph] inferred changed modules; re-importing', toReimport);
+                // Evict the inferred changed set before re-importing.
+                // See `processQueue` for the architectural rationale; the
+                // full-graph code path is the resync fallback (server chose
+                // not to send a delta) and shares the same V8 cache pitfall.
+                const fgEvictUrls = buildEvictionUrls(toReimport);
+                const fgEvicted = invalidateModulesByUrls(fgEvictUrls);
+                if (VERBOSE)
+                    console.log(`[hmr][full-graph] eviction count=${fgEvictUrls.length} ok=${fgEvicted}`);
                 for (const id of toReimport) {
                     try {
                         const spec = normalizeSpec(id);
@@ -1426,8 +1742,111 @@ async function handleHmrMessage(ev) {
             notifyAppHmrUpdate('delta', deltaIds);
             return;
         }
-        else if (handleAngularHotUpdateMessage(msg, { getCore, verbose: VERBOSE })) {
-            return;
+        else {
+            // Vite custom-event dispatch.
+            //
+            // `server.ws.send('event-name', payload)` from any Vite plugin lands
+            // on the wire as `{ type: 'custom', event: 'event-name', data: payload }`.
+            // On the web, Vite's stock client owns a `customListenersMap` that
+            // fires every `import.meta.hot.on('event-name', cb)` callback. We
+            // don't run Vite's stock client on device — the iOS runtime owns
+            // the listener registry via `__NS_DISPATCH_HOT_EVENT__` (the
+            // counterpart to `import.meta.hot.on` populated by user code +
+            // compiled Angular components). Forwarding `type: 'custom'` here
+            // is the only thing standing between server-emitted events and
+            // the listeners they were meant for.
+            //
+            // `angular:component-update` is the canonical example. Analog's
+            // plugin sends it on `.html` / component-style edits; the
+            // compiled component `.mjs` registered a listener that
+            // dynamic-imports `/@ng/component?c=<id>&t=<ts>` and calls
+            // `ɵɵreplaceMetadata` on the live class — swapping the template
+            // definition AND walking live `LView`s to recreate matching views
+            // in-place. The page stays mounted and only the changed bits
+            // re-render. We MUST `return` after dispatch so the reboot path
+            // (`handleAngularHotUpdateMessage` → `__reboot_ng_modules__`)
+            // never runs for these updates — that's the whole point of the
+            // component-replacement pipeline.
+            //
+            // All other custom events are forwarded but NOT short-circuited
+            // (Vite spec: custom events are additive — they don't replace
+            // any framework-specific handling). The reboot path falls through
+            // for `ns:angular-update` (the legacy/`.ts`-edit broadcast) and
+            // for any framework not yet using the in-place replacement path.
+            if (msg.type === 'custom' && typeof msg.event === 'string') {
+                // Dispatch every Vite "custom" event through the runtime's
+                // `__NS_DISPATCH_HOT_EVENT__` bridge so `import.meta.hot.on(event, cb)`
+                // callbacks fire on the device. Critical contract: this is the
+                // ONLY route by which Analog's `angular:component-update` reaches
+                // the compiled component's `(d) => d.id === id && Component_HmrLoad(...)`
+                // listener — without it, server-side broadcasts log green
+                // (`(client) hmr update`) while the device sees nothing happen.
+                //
+                // Diagnostic policy: log "no dispatcher" loud (boot-time rt-bridge
+                // failure), and listener exceptions loud (compiled HmrLoad
+                // fetch/parse error). Successful dispatches are silent — the
+                // runtime's `[import.meta.hot] dispatch summary` line carries
+                // the per-event match-count diagnostic.
+                try {
+                    const dispatch = globalThis.__NS_DISPATCH_HOT_EVENT__;
+                    if (typeof dispatch === 'function') {
+                        dispatch(msg.event, msg.data);
+                    }
+                    else {
+                        console.warn(`[hmr-client][custom] no __NS_DISPATCH_HOT_EVENT__ available for '${msg.event}'`);
+                    }
+                }
+                catch (err) {
+                    console.warn('[hmr-client][custom] dispatch threw for', msg.event, err);
+                }
+                if (msg.event === 'angular:component-update') {
+                    if (VERBOSE)
+                        console.log('[hmr-client][custom] dispatched angular:component-update — skipping reboot path');
+                    // Walk the apply-progress overlay through its
+                    // remaining stages for the in-place template-swap
+                    // path. The full reboot path
+                    // (`handleAngularHotUpdateMessage`) drives the
+                    // overlay itself ('received' → 'evicting' →
+                    // 'reimporting' → 'rebooting' → 'complete'); the
+                    // in-place path bypasses that handler entirely
+                    // because the work happens inside Angular's
+                    // `ɵɵreplaceMetadata` after the runtime forwards the
+                    // `angular:component-update` event to the compiled
+                    // component's listener. Without this update the
+                    // overlay would freeze at 5% ('received') even
+                    // though the visual swap completes a few frames
+                    // later — exactly the "Preparing update (5%)" stuck
+                    // frame we have been chasing.
+                    //
+                    // We transition straight to 'reimporting' to
+                    // communicate that metadata is being fetched (the
+                    // runtime listener fires `__ns_import('/@ng/component?c=...&t=...')`),
+                    // then schedule 'complete' on the next macrotask so
+                    // the auto-hide timer kicks in. The actual
+                    // template swap is fire-and-forget from this point;
+                    // the user sees the overlay close at the same time
+                    // as Angular re-renders the bound text/structure.
+                    try {
+                        const filePath = typeof msg.data?.id === 'string' ? decodeURIComponent(msg.data.id).split('@')[0] : undefined;
+                        const detail = filePath ? `Applying template update to ${filePath}` : 'Applying template update';
+                        setUpdateOverlayStage('reimporting', { detail });
+                        setTimeout(() => {
+                            try {
+                                setUpdateOverlayStage('complete', { detail: filePath ? `Updated ${filePath}` : 'Update applied' });
+                            }
+                            catch { }
+                        }, 16);
+                    }
+                    catch { }
+                    return;
+                }
+            }
+            if (msg.type === 'ns:angular-update' && typeof msg.version === 'number') {
+                setGraphVersion(Number(msg.version || getGraphVersion() || 0));
+            }
+            if (await handleAngularHotUpdateMessage(msg, { getCore, verbose: VERBOSE })) {
+                return;
+            }
         }
     }
     // On-demand module fetch response (Option A)
@@ -1459,13 +1878,32 @@ async function handleHmrMessage(ev) {
         return;
     }
     if (msg.type === 'ns:css-updates' && Array.isArray(msg.updates)) {
+        // Drive the HMR-applying overlay past the 'received' (5%) frame
+        // that `ns:hmr-pending` set earlier in the cycle. Without this
+        // the overlay sticks at "Preparing update" forever for CSS-only
+        // edits because `handleCssUpdates` is a leaf — there's no
+        // downstream module-evaluation path that would hit the queue's
+        // 'complete' transition.
+        const cssCount = msg.updates.length;
+        try {
+            setUpdateOverlayStage('reimporting', { detail: buildCssApplyingDetail(cssCount) });
+        }
+        catch { }
         try {
             const origin = msg.origin || getHttpOriginForVite() || deriveHttpOrigin(getHMRWsUrl());
             await handleCssUpdates(msg.updates, origin);
+            try {
+                setUpdateOverlayStage('complete', { detail: buildCssAppliedDetail(cssCount) });
+            }
+            catch { }
             return;
         }
         catch (e) {
             console.warn('[hmr-client] CSS updates handling failed:', e);
+            try {
+                setUpdateOverlayStage('complete', { detail: 'CSS update failed' });
+            }
+            catch { }
             return;
         }
     }
@@ -1476,10 +1914,22 @@ async function handleHmrMessage(ev) {
     if (msg.type === 'ns:vue-sfc-registry-update') {
         if (typeof msg.version === 'number')
             setGraphVersion(msg.version);
-        const comp = await handleVueSfcRegistryUpdate(msg, getGraphVersion());
-        if (comp) {
-            await performResetRoot(comp);
-        }
+        // `ns:hmr-pending` already set the overlay to 'received' (5%).
+        // Without the explicit stage walk below the overlay would stick
+        // at "Preparing update" forever after a successful SFC swap —
+        // the Vue path was missing the framework-specific completion
+        // hooks that Angular drives via `handleAngularHotUpdateMessage`
+        // and CSS drives inline above. `driveVueSfcUpdateOverlay` is a
+        // thin orchestrator that walks 'evicting' → 'reimporting' →
+        // 'rebooting' → 'complete' around the load + reset steps and
+        // always lands on 'complete' (or a failure detail) so the
+        // auto-hide timer can dismiss the toast.
+        const sfcFilePath = typeof msg.path === 'string' ? msg.path : undefined;
+        await driveVueSfcUpdateOverlay({
+            filePath: sfcFilePath,
+            loadComponent: () => handleVueSfcRegistryUpdate(msg, getGraphVersion()),
+            applyComponent: (component) => performResetRoot(component),
+        }, { getOverlay: getHmrOverlayApi });
         return;
     }
 }
@@ -1568,7 +2018,7 @@ async function performResetRoot(newComponent) {
                 if (cachedRoot)
                     return cachedRoot;
                 try {
-                    switch (__NS_TARGET_FLAVOR__) {
+                    switch (TARGET_FLAVOR) {
                         case 'vue':
                             cachedRoot = getRootForVue(newComponent, state);
                             break;
@@ -1905,7 +2355,7 @@ export function initHmrClient(opts) {
         setTimeout(waitForBoot, 100);
     }
     // Best-effort: install back wrapper even before first remount; original root may be captured later
-    switch (__NS_TARGET_FLAVOR__) {
+    switch (TARGET_FLAVOR) {
         case 'vue':
             ensureBackWrapperInstalled(performResetRoot, getCore);
             break;