@nativescript/vite 8.0.0-alpha.1 → 8.0.0-alpha.3

package/hmr/client/index.js

@@ -8,6 +8,38 @@
 import { setHMRWsUrl, getHMRWsUrl, pendingModuleFetches, deriveHttpOrigin, setHttpOriginForVite, moduleFetchCache, requestModuleFromServer, getHttpOriginForVite, normalizeSpec, hmrMetrics, graph, setGraphVersion, getGraphVersion, getCurrentApp, getRootFrame, setCurrentApp, setRootFrame, getCore } from './utils.js';
 import { handleCssUpdates } from './css-handler.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 +61,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 {
@@ -43,12 +76,78 @@ function ensureCoreAliasesOnGlobalThis() {
 }
 // Apply once on module evaluation
 ensureCoreAliasesOnGlobalThis();
+function getHmrOverlayApi() {
+    try {
+        return globalThis.__NS_HMR_DEV_OVERLAY__ || null;
+    }
+    catch { }
+    return null;
+}
+function setConnectionOverlayStage(stage, detail) {
+    try {
+        const api = getHmrOverlayApi();
+        if (api && typeof api.setConnectionStage === 'function') {
+            api.setConnectionStage(stage, { detail });
+        }
+    }
+    catch { }
+}
+function hideConnectionOverlay() {
+    try {
+        const api = getHmrOverlayApi();
+        if (api && typeof api.hide === 'function') {
+            api.hide('healthy');
+        }
+    }
+    catch { }
+}
+let connectionOverlayTimer = null;
+let connectionOverlayVisible = false;
+let hasOpenedHmrSocket = false;
+let awaitingHealthyHmrMessage = false;
+let pendingConnectionOverlayStage = 'connecting';
+let pendingConnectionOverlayDetail = '';
+function clearConnectionOverlayTimer() {
+    if (connectionOverlayTimer) {
+        clearTimeout(connectionOverlayTimer);
+        connectionOverlayTimer = null;
+    }
+}
+function showConnectionOverlayNow(stage, detail) {
+    pendingConnectionOverlayStage = stage;
+    pendingConnectionOverlayDetail = detail || '';
+    connectionOverlayVisible = true;
+    setConnectionOverlayStage(stage, detail);
+}
+function scheduleConnectionOverlay(stage, detail, delayMs = 1200) {
+    pendingConnectionOverlayStage = stage;
+    pendingConnectionOverlayDetail = detail || '';
+    clearConnectionOverlayTimer();
+    connectionOverlayTimer = setTimeout(() => {
+        showConnectionOverlayNow(pendingConnectionOverlayStage, pendingConnectionOverlayDetail);
+    }, delayMs);
+}
+function updateConnectionOverlay(stage, detail) {
+    pendingConnectionOverlayStage = stage;
+    pendingConnectionOverlayDetail = detail || '';
+    if (connectionOverlayVisible) {
+        showConnectionOverlayNow(stage, detail);
+    }
+}
+function markHmrConnectionHealthy() {
+    awaitingHealthyHmrMessage = false;
+    clearConnectionOverlayTimer();
+    if (connectionOverlayVisible) {
+        connectionOverlayVisible = false;
+        hideConnectionOverlay();
+    }
+}
 /**
  * Flavor hooks
  */
-import { installNsVueDevShims, ensureBackWrapperInstalled, getRootForVue, loadSfcComponent, ensureVueGlobals, ensurePiniaOnApp, addSfcMapping, recordVuePayloadChanges, handleVueSfcRegistry, handleVueSfcRegistryUpdate } from '../frameworks/vue/client/index.js';
+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;
@@ -60,6 +159,10 @@ switch (__NS_TARGET_FLAVOR__) {
 let initialMounted = !!globalThis.__NS_HMR_BOOT_COMPLETE__;
 // Prevent duplicate initial-mount scheduling across rapid full-graph broadcasts and re-evaluations
 let initialMounting = !!globalThis.__NS_HMR_INITIAL_MOUNT_IN_PROGRESS__;
+// Track whether the first full-graph has been received. Before the full-graph,
+// delta messages are just the server discovering modules during initial boot —
+// NOT actual code changes. Re-imports must be gated behind this flag.
+let hasReceivedFullGraph = false;
 // TypeScript flavor: track registry modules and inferred main id
 let tsModuleSet = null;
 let tsMainId = null;
@@ -94,10 +197,14 @@ function applyFullGraph(payload) {
         console.log('[hmr][graph] full graph applied version', getGraphVersion(), 'modules=', graph.size);
     // Guarded initial mount rescue: if app hasn't replaced the placeholder shortly after graph arrives,
     // perform a one-time mount. This waits briefly to let the app's main entry start() run first to avoid double mounts.
+    // TypeScript flavor: skip the rescue entirely. The HTTP boot will load main.ts which
+    // calls Application.run() (patched to resetRootView) — the rescue is redundant and
+    // causes a double-mount race (rescue fires at 450ms, then main.ts fires ~1s later,
+    // causing a visual flash and leaving the app in an inconsistent state).
     try {
         const g = globalThis;
         const bootDone = !!g.__NS_HMR_BOOT_COMPLETE__;
-        if (!bootDone && !initialMounted && !initialMounting && !g.__NS_HMR_RESCUE_SCHEDULED__) {
+        if (!bootDone && !initialMounted && !initialMounting && !g.__NS_HMR_RESCUE_SCHEDULED__ && TARGET_FLAVOR !== 'typescript') {
             // simple snapshot helpers
             const getTopmost = () => {
                 try {
@@ -170,7 +277,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
@@ -211,7 +318,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)) {
@@ -227,6 +334,19 @@ function applyFullGraph(payload) {
                                     }
                                 }
                             }
+                            // Fallback: when the module graph is empty (Vite 7+ may not populate it
+                            // before the first full-graph broadcast), check the SFC artifact registry
+                            // which is populated from the ns:vue-sfc-registry message.
+                            if (!candidate && sfcArtifactMap.size > 0) {
+                                for (const id of sfcArtifactMap.keys()) {
+                                    if (/\.vue$/i.test(id)) {
+                                        candidate = id;
+                                        if (VERBOSE)
+                                            console.log('[hmr][init] rescue candidate from SFC registry:', id);
+                                        break;
+                                    }
+                                }
+                            }
                             break;
                         }
                     }
@@ -240,7 +360,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;
@@ -285,7 +405,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)) {
@@ -301,6 +421,17 @@ function applyFullGraph(payload) {
                             }
                         }
                     }
+                    // Fallback: SFC registry (same as rescue mount above)
+                    if (!candidate && sfcArtifactMap.size > 0) {
+                        for (const id of sfcArtifactMap.keys()) {
+                            if (/\.vue$/i.test(id)) {
+                                candidate = id;
+                                if (VERBOSE)
+                                    console.log('[hmr][init] initial mount candidate from SFC registry:', id);
+                                break;
+                            }
+                        }
+                    }
                     break;
                 }
                 case 'typescript': {
@@ -318,7 +449,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;
@@ -352,7 +483,7 @@ function applyFullGraph(payload) {
                         }
                         catch { }
                         let comp = null;
-                        switch (__NS_TARGET_FLAVOR__) {
+                        switch (TARGET_FLAVOR) {
                             case 'vue':
                                 comp = await loadSfcComponent(candidate, 'initial_mount');
                                 break;
@@ -401,7 +532,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);
             }
         }
     }
@@ -427,7 +558,7 @@ function applyDelta(payload) {
         setGraphVersion(payload.newVersion);
     }
     const changed = payload.changed || [];
-    switch (__NS_TARGET_FLAVOR__) {
+    switch (TARGET_FLAVOR) {
         case 'vue':
             recordVuePayloadChanges(changed, getGraphVersion());
             break;
@@ -445,6 +576,16 @@ function applyDelta(payload) {
         console.log('[hmr][graph] delta applied newVersion', getGraphVersion(), 'changed=', (payload.changed || []).length, 'removed=', (payload.removed || []).length, 'baseVersion=', payload.baseVersion);
     // Queue evaluation of changed modules (placeholder pipeline)
     if (payload.changed?.length) {
+        // Gate: Before the first full-graph is received, delta messages are the server
+        // discovering modules during initial boot — NOT actual code changes. The entry-runtime
+        // already loaded all modules; re-importing them would cause duplicate Application.run(),
+        // router initialization, and modal conflicts. Only queue re-imports after the first
+        // full-graph confirms the graph is synced and subsequent deltas are real changes.
+        if (!hasReceivedFullGraph) {
+            if (VERBOSE)
+                console.log('[hmr][delta] skipping re-import queue (initial graph build, no full-graph yet)');
+            return;
+        }
         // HARD SUPPRESS: the very first delta (baseVersion 0) commonly includes the app main entry which is already evaluated during bootstrap.
         // Importing it again with a cache-bust often produces a spurious module-not-found (timestamp param treated as distinct file).
         const isInitial = payload.baseVersion === 0;
@@ -507,7 +648,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;
@@ -535,7 +676,7 @@ function __nsNavigateUsingApp(comp, opts = {}) {
         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__) {
+        switch (TARGET_FLAVOR) {
             case 'vue':
                 ensurePiniaOnApp(app);
                 break;
@@ -686,10 +827,167 @@ 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.
                     break;
+                case 'solid': {
+                    // 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
+                    // the .tsx/.jsx component boundaries and re-import those so their
+                    // solid-refresh proxies pick up the new dependency values.
+                    try {
+                        // Build reverse index: dep id → list of importer ids
+                        const reverseIndex = new Map();
+                        for (const [id, mod] of graph) {
+                            for (const dep of mod.deps) {
+                                let arr = reverseIndex.get(dep);
+                                if (!arr) {
+                                    arr = [];
+                                    reverseIndex.set(dep, arr);
+                                }
+                                arr.push(id);
+                            }
+                        }
+                        // BFS from each non-tsx changed module up to tsx/jsx boundaries
+                        const boundaries = new Set();
+                        for (const id of drained) {
+                            if (/\.(tsx|jsx)$/i.test(id))
+                                continue; // already self-accepting
+                            const visited = new Set();
+                            const queue = [id];
+                            while (queue.length) {
+                                const cur = queue.shift();
+                                if (visited.has(cur))
+                                    continue;
+                                visited.add(cur);
+                                const importers = reverseIndex.get(cur);
+                                if (!importers)
+                                    continue;
+                                for (const imp of importers) {
+                                    if (/\.(tsx|jsx)$/i.test(imp)) {
+                                        boundaries.add(imp);
+                                    }
+                                    else {
+                                        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.
+                        let routesPatchCount = 0;
+                        let discoveredRouter = null;
+                        // Discover router: try __ns_router global (set by createNativeScriptRouter),
+                        // then scan globalThis for any router-shaped object with routesById.
+                        const findRouter = () => {
+                            if (discoveredRouter)
+                                return discoveredRouter;
+                            const g = globalThis;
+                            if (g.__ns_router?.routesById)
+                                return (discoveredRouter = g.__ns_router);
+                            // Fallback: scan common global keys for router
+                            for (const key of ['__ns_router', 'router', '__router']) {
+                                if (g[key]?.routesById && g[key]?.invalidate)
+                                    return (discoveredRouter = g[key]);
+                            }
+                            return null;
+                        };
+                        // Convert boundary file path to TanStack Router fullPath.
+                        // e.g. /src/routes/posts.$postId.tsx → /posts/$postId
+                        const boundaryToFullPath = (bid) => {
+                            const m = bid.match(/\/src\/routes\/(.+)\.(tsx|jsx|ts|js)$/i);
+                            if (!m)
+                                return null;
+                            let p = m[1];
+                            // Replace dots between segments with slashes (posts.$postId → posts/$postId)
+                            p = p.replace(/\./g, '/');
+                            // Handle index files
+                            if (p === 'index')
+                                return '/';
+                            if (p.endsWith('/index'))
+                                p = p.slice(0, -6);
+                            // Strip leading - (TanStack pathless layout convention)
+                            p = p.replace(/(^|\/)-([\w])/g, '$1$2');
+                            return '/' + p;
+                        };
+                        // Find existing route by fullPath (since new Route has no id yet)
+                        const findRouteByFullPath = (router, fp) => {
+                            if (!router?.routesById)
+                                return null;
+                            for (const rid of Object.keys(router.routesById)) {
+                                const r = router.routesById[rid];
+                                if (r?.fullPath === fp)
+                                    return r;
+                            }
+                            return null;
+                        };
+                        for (const id of boundaries) {
+                            if (seen.has(id))
+                                continue;
+                            try {
+                                const spec = normalizeSpec(id);
+                                const url = await requestModuleFromServer(spec);
+                                if (!url)
+                                    continue;
+                                if (VERBOSE)
+                                    console.log('[hmr][solid] propagated to boundary', { id, url });
+                                const mod = await import(/* @vite-ignore */ url);
+                                // Patch TanStack Router route loaders
+                                try {
+                                    const newRoute = mod?.Route;
+                                    if (newRoute?.options?.loader) {
+                                        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' });
+                                        const existingRoute = fullPath && router ? findRouteByFullPath(router, fullPath) : null;
+                                        if (existingRoute?.options) {
+                                            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);
+                                        }
+                                        else if (VERBOSE) {
+                                            console.log('[hmr][solid] no matching route for fullPath', fullPath);
+                                        }
+                                    }
+                                }
+                                catch (e) {
+                                    if (VERBOSE)
+                                        console.warn('[hmr][solid] route patch error', id, e);
+                                }
+                            }
+                            catch (e) {
+                                if (VERBOSE)
+                                    console.warn('[hmr][solid] boundary re-import failed', id, e);
+                            }
+                        }
+                        // Route loaders were patched with fresh closures. The data is
+                        // correct in router.state.matches[].loaderData (confirmed via
+                        // diagnostics), but the currently visible page doesn't re-render
+                        // because the NativeScriptRouterProvider's Solid store flush only
+                        // fires through history.subscribe. TODO: find the right mechanism
+                        // to trigger a Solid reactive update for the active match stores.
+                        if (routesPatchCount > 0 && VERBOSE) {
+                            console.log('[hmr][solid] patched', routesPatchCount, 'route loaders (data correct in match state, pending UI refresh mechanism)');
+                        }
+                        if (VERBOSE) {
+                            if (boundaries.size)
+                                console.log('[hmr][solid] propagated non-component change to', boundaries.size, 'boundaries', Array.from(boundaries));
+                            console.log('[hmr][queue] Solid: modules re-imported, solid-refresh handles reactive update', drained);
+                        }
+                    }
+                    catch (e) {
+                        if (VERBOSE)
+                            console.warn('[hmr][solid] propagation failed', e);
+                    }
+                    break;
+                }
                 case 'typescript': {
                     // For TS apps, always reset back to the conventional app root.
                     // This preserves the shell (Frame, ActionBar, etc.) that the app's
@@ -702,9 +1000,124 @@ async function processQueue() {
                                 console.warn('[hmr][queue] TS flavor: Application.resetRootView unavailable; skipping UI refresh');
                             break;
                         }
+                        // Re-fetch changed XML/CSS files and update the bundled module registry
+                        // so Builder.createViewFromEntry picks up fresh content.
+                        const rawAssetIds = drained.filter((id) => /\.(xml|css|scss|sass|less)$/i.test(id));
+                        if (rawAssetIds.length && typeof g.registerModule === 'function') {
+                            const origin = getHttpOriginForVite() || deriveHttpOrigin(getHMRWsUrl());
+                            if (origin) {
+                                for (const id of rawAssetIds) {
+                                    try {
+                                        const spec = normalizeSpec(id);
+                                        // Fetch the raw file content directly from Vite's dev server.
+                                        // Use the project-relative path which Vite serves as static files.
+                                        const fetchUrl = origin + (spec.startsWith('/') ? spec : '/' + spec);
+                                        if (VERBOSE)
+                                            console.log('[hmr][queue] fetching raw asset', { id, fetchUrl });
+                                        const resp = await fetch(fetchUrl);
+                                        if (resp.ok) {
+                                            const rawContent = await resp.text();
+                                            // Register under all nickname variants the module registry uses.
+                                            // The bundler context registers XML as e.g., './main-page.xml' and 'main-page.xml'
+                                            const appVirtual = APP_VIRTUAL_WITH_SLASH.replace(/^\//, '');
+                                            let relPath = spec.startsWith('/') ? spec.slice(1) : spec;
+                                            if (relPath.startsWith(appVirtual))
+                                                relPath = relPath.slice(appVirtual.length);
+                                            const nicknames = ['./' + relPath, relPath];
+                                            // Also add without extension for CSS
+                                            const extIdx = relPath.lastIndexOf('.');
+                                            if (extIdx > 0) {
+                                                const baseName = relPath.slice(0, extIdx);
+                                                if (!relPath.endsWith('.xml'))
+                                                    nicknames.push(baseName, './' + baseName);
+                                            }
+                                            for (const name of nicknames) {
+                                                if (VERBOSE)
+                                                    console.log('[hmr][queue] re-registering module', name);
+                                                g.registerModule(name, () => rawContent);
+                                            }
+                                        }
+                                        else if (VERBOSE) {
+                                            console.warn('[hmr][queue] raw asset fetch failed', id, resp.status);
+                                        }
+                                    }
+                                    catch (e) {
+                                        if (VERBOSE)
+                                            console.warn('[hmr][queue] raw asset refresh failed for', id, e);
+                                    }
+                                }
+                            }
+                        }
+                        // Determine if we can navigate in-place to a changed page
+                        // instead of resetting all the way back to app-root.
+                        // This keeps the user on the page they're editing for faster iteration.
+                        const changedXmlPages = drained
+                            .filter((id) => /\.xml$/i.test(id))
+                            .map((id) => {
+                            const spec = normalizeSpec(id);
+                            const appVirtual = APP_VIRTUAL_WITH_SLASH.replace(/^\//, '');
+                            let relPath = spec.startsWith('/') ? spec.slice(1) : spec;
+                            if (relPath.startsWith(appVirtual))
+                                relPath = relPath.slice(appVirtual.length);
+                            // Strip .xml extension to get the moduleName (e.g., 'pages/status-bar')
+                            return relPath.replace(/\.xml$/i, '');
+                        })
+                            .filter((m) => m && m !== 'app-root');
+                        // Resolve the topmost Frame from the bundled realm.
+                        // Frame.topmost() relies on an internal frameStack array, so we must
+                        // call it on the bundled-realm class. Multiple strategies to find it:
+                        const FrameClass = getCore('Frame') || g.Frame;
+                        let topFrame = null;
+                        // 1) Try the vendor-realm static topmost()
+                        try {
+                            topFrame = FrameClass?.topmost?.();
+                        }
+                        catch { }
+                        // 2) Try getting the root view from Application — if it's a Frame, use it
+                        if (!topFrame) {
+                            try {
+                                const rootView = App.getRootView?.() || App._rootView;
+                                if (rootView) {
+                                    // rootView could be a Frame itself, or contain a Frame
+                                    const isFrame = rootView.constructor?.name === 'Frame' || rootView.navigate;
+                                    if (isFrame) {
+                                        topFrame = rootView;
+                                    }
+                                    else if (rootView.getChildAt) {
+                                        // Walk direct children looking for a Frame
+                                        for (let i = 0; i < (rootView.getChildrenCount?.() || 0); i++) {
+                                            const child = rootView.getChildAt(i);
+                                            if (child?.constructor?.name === 'Frame' || child?.navigate) {
+                                                topFrame = child;
+                                                break;
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                            catch { }
+                        }
                         if (VERBOSE)
-                            console.log('[hmr][queue] TS flavor: resetRootView(app-root) after changes');
-                        App.resetRootView({ moduleName: 'app-root' });
+                            console.log('[hmr][queue] TS: changedXmlPages=', changedXmlPages, 'topFrame=', !!topFrame);
+                        if (changedXmlPages.length > 0 && topFrame) {
+                            // Navigate the current frame to the changed page directly.
+                            // Use the last changed XML page (most specific).
+                            const moduleName = changedXmlPages[changedXmlPages.length - 1];
+                            if (VERBOSE)
+                                console.log('[hmr][queue] TS: navigating in-place to', moduleName);
+                            try {
+                                topFrame.navigate({ moduleName, clearHistory: false, animated: false });
+                            }
+                            catch (navErr) {
+                                console.warn('[hmr][queue] TS flavor: in-place navigate failed, falling back to resetRootView', navErr);
+                                App.resetRootView({ moduleName: 'app-root' });
+                            }
+                        }
+                        else {
+                            if (VERBOSE)
+                                console.log('[hmr][queue] TS flavor: resetRootView(app-root) after changes');
+                            App.resetRootView({ moduleName: 'app-root' });
+                        }
                     }
                     catch (e) {
                         console.warn('[hmr][queue] TS flavor: resetRootView(app-root) failed', e);
@@ -752,6 +1165,11 @@ 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) => {
         let candidates = [];
@@ -795,7 +1213,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);
                 }
             }
@@ -811,10 +1229,19 @@ function connectHmr() {
     let idx = 0;
     const tryNext = () => {
         if (idx >= candidates.length) {
+            showConnectionOverlayNow('offline', 'Waiting for the Vite websocket to come back.');
             console.warn('[hmr-client] All WS candidates failed:', candidates.join(', '));
+            setTimeout(connectHmr, 1500);
             return;
         }
         const url = candidates[idx++];
+        const connectionDetail = `${overlayStage === 'reconnecting' ? 'Retrying' : 'Opening'} ${url}`;
+        if (connectionOverlayVisible) {
+            updateConnectionOverlay(overlayStage, connectionDetail);
+        }
+        else {
+            scheduleConnectionOverlay(overlayStage, connectionDetail);
+        }
         try {
             if (__NS_ENV_VERBOSE__)
                 console.log('[hmr-client] Connecting to HMR WebSocket:', url);
@@ -836,6 +1263,16 @@ function connectHmr() {
             sock.onopen = () => {
                 opened = true;
                 clearTimeout(timeout);
+                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');
             };
             sock.onmessage = handleHmrMessage;
@@ -845,6 +1282,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)
@@ -854,6 +1295,7 @@ function connectHmr() {
                 else {
                     if (VERBOSE)
                         console.log('[hmr-client] WebSocket closed (code', ev?.code, '), will reconnect…');
+                    scheduleConnectionOverlay('reconnecting', 'The websocket closed. Waiting to reconnect.', 700);
                     // try to reconnect with full candidate list again
                     setTimeout(connectHmr, 1000);
                 }
@@ -874,6 +1316,12 @@ async function handleHmrMessage(ev) {
     catch {
         return;
     }
+    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 {
@@ -896,6 +1344,34 @@ async function handleHmrMessage(ev) {
             const prevGraph = new Map(graph);
             setGraphVersion(Number(msg.version || getGraphVersion() || 0));
             applyFullGraph(msg);
+            hasReceivedFullGraph = true;
+            // Gate: On first boot, the entry-runtime handles all initial module loading
+            // (with the import map already configured). Don't re-import here — the graph
+            // is stored above for future HMR delta comparisons, but modules are already
+            // loaded correctly via the entry-runtime boot sequence.
+            //
+            // Two cases to catch:
+            // 1. Boot still in progress (__NS_HMR_BOOT_COMPLETE__ is false)
+            // 2. Boot already finished but this is the FIRST full-graph (prevGraph was
+            //    empty). The WebSocket often connects after entry-runtime finishes, so
+            //    boot is "complete" but we still shouldn't re-import — all modules were
+            //    just loaded fresh. Only re-import on subsequent full-graphs (reconnect
+            //    scenarios) where prevGraph already has entries.
+            if (!globalThis.__NS_HMR_BOOT_COMPLETE__) {
+                if (VERBOSE)
+                    console.info('[hmr][full-graph] skipping initial re-import (boot in progress)');
+                const fullIds = Array.isArray(msg.modules) ? msg.modules.map((m) => m?.id).filter(Boolean) : [];
+                notifyAppHmrUpdate('full-graph', fullIds);
+                return;
+            }
+            if (prevGraph.size === 0) {
+                if (VERBOSE)
+                    console.info('[hmr][full-graph] skipping re-import on first graph after boot (modules already fresh)');
+                const fullIds = Array.isArray(msg.modules) ? msg.modules.map((m) => m?.id).filter(Boolean) : [];
+                notifyAppHmrUpdate('full-graph', fullIds);
+                return;
+            }
+            // Reconnect / resync case — re-import changed modules as normal.
             // In some cases (e.g. server chooses full-graph resync / page reload), we won't
             // receive a delta queue to re-import changed TS modules. Without re-import,
             // HTTP ESM caching means module bodies (and side effects) won't re-run.
@@ -998,8 +1474,13 @@ async function handleHmrMessage(ev) {
             notifyAppHmrUpdate('delta', deltaIds);
             return;
         }
-        else if (handleAngularHotUpdateMessage(msg, { getCore, verbose: VERBOSE })) {
-            return;
+        else {
+            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)
@@ -1140,7 +1621,7 @@ async function performResetRoot(newComponent) {
                 if (cachedRoot)
                     return cachedRoot;
                 try {
-                    switch (__NS_TARGET_FLAVOR__) {
+                    switch (TARGET_FLAVOR) {
                         case 'vue':
                             cachedRoot = getRootForVue(newComponent, state);
                             break;
@@ -1455,9 +1936,29 @@ export function initHmrClient(opts) {
     }
     g.__NS_HMR_CLIENT_ACTIVE__ = true;
     ensureCoreAliasesOnGlobalThis();
-    connectHmr();
+    // Defer WebSocket connection until boot completes to avoid native V8 crashes
+    // caused by concurrent WebSocket message handling + HTTP fetch during early startup.
+    // The WebSocket is only needed for HMR updates, not the initial boot sequence.
+    if (g.__NS_HMR_BOOT_COMPLETE__) {
+        connectHmr();
+    }
+    else {
+        const waitForBoot = () => {
+            if (globalThis.__NS_HMR_BOOT_COMPLETE__) {
+                if (VERBOSE)
+                    console.log('[hmr-client] boot complete, connecting HMR WebSocket');
+                connectHmr();
+            }
+            else {
+                setTimeout(waitForBoot, 100);
+            }
+        };
+        if (VERBOSE)
+            console.log('[hmr-client] deferring WebSocket connection until boot completes');
+        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;