@nativescript/vite 8.0.0-alpha.4 → 8.0.0-alpha.41

package/hmr/client/index.js

@@ -5,9 +5,11 @@
  * 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, ENV_VERBOSE } from './utils.js';
 import { handleCssUpdates } from './css-handler.js';
-const VERBOSE = typeof __NS_ENV_VERBOSE__ !== 'undefined' && __NS_ENV_VERBOSE__;
+import { buildCssApplyingDetail, buildCssAppliedDetail } from './css-update-overlay.js';
+import { getGlobalScope } from '../shared/runtime/global-scope.js';
+const VERBOSE = ENV_VERBOSE;
 function resolveTargetFlavor() {
     try {
         if (typeof __NS_TARGET_FLAVOR__ !== 'undefined' && __NS_TARGET_FLAVOR__) {
@@ -16,7 +18,7 @@ function resolveTargetFlavor() {
     }
     catch { }
     try {
-        const g = globalThis;
+        const g = getGlobalScope();
         if (typeof g.__NS_TARGET_FLAVOR__ === 'string' && g.__NS_TARGET_FLAVOR__) {
             return g.__NS_TARGET_FLAVOR__;
         }
@@ -40,7 +42,11 @@ try {
     }
 }
 catch { }
-const APP_ROOT_VIRTUAL = typeof __NS_APP_ROOT_VIRTUAL__ === 'string' && __NS_APP_ROOT_VIRTUAL__ ? __NS_APP_ROOT_VIRTUAL__ : '/src';
+// Define substitution does NOT reach this file (served raw from node_modules),
+// so prefer the globalThis seed planted by the entry's defines-seed module —
+// the '/src' literal is a last-resort default and is WRONG for 'app/'-rooted
+// projects.
+const APP_ROOT_VIRTUAL = (typeof __NS_APP_ROOT_VIRTUAL__ === 'string' && __NS_APP_ROOT_VIRTUAL__) || (typeof getGlobalScope().__NS_APP_ROOT_VIRTUAL__ === 'string' && getGlobalScope().__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`;
 // Policy: by default, let the app's own main entry mount initially; HMR client handles updates/remounts only.
@@ -101,12 +107,101 @@ 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 = getGlobalScope();
+    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 = getGlobalScope();
+    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';
+function setHmrPendingOverlay(filePath) {
+    applyHmrPendingFrame(filePath, { getOverlay: getHmrOverlayApi });
+}
 let connectionOverlayTimer = null;
 let connectionOverlayVisible = false;
 let hasOpenedHmrSocket = false;
 let awaitingHealthyHmrMessage = false;
 let pendingConnectionOverlayStage = 'connecting';
 let pendingConnectionOverlayDetail = '';
+// The stage currently PAINTED on screen (set only when we actually show
+// the overlay, not when we merely schedule it). Used to suppress the
+// sub-perceptible offline↔reconnecting flicker during the reconnect
+// retry loop — see the deferral in `connectHmr`/`tryNext`.
+let shownConnectionOverlayStage = null;
+// While the terminal 'offline' frame is showing, a fresh reconnect
+// attempt that is refused near-instantly (the norm when the dev server
+// is down — especially on the Android emulator, where connection-refused
+// returns in ~1ms) would flip the overlay to 'reconnecting' and straight
+// back to 'offline', producing a jarring 1-frame flicker. We defer the
+// 'reconnecting' frame by this much so an instant failure (→ back to
+// 'offline') or a success (→ 'synchronizing') cancels it before it ever
+// paints; only a genuinely in-flight attempt surfaces 'reconnecting'.
+// On iOS real connect attempts exceed this threshold, so the behaviour
+// there is unchanged.
+const RECONNECTING_OVER_OFFLINE_DELAY_MS = 500;
 function clearConnectionOverlayTimer() {
     if (connectionOverlayTimer) {
         clearTimeout(connectionOverlayTimer);
@@ -114,9 +209,14 @@ function clearConnectionOverlayTimer() {
     }
 }
 function showConnectionOverlayNow(stage, detail) {
+    // Painting a stage now supersedes any scheduled (deferred) stage, so
+    // cancel the pending timer — otherwise a deferred 'reconnecting' could
+    // fire moments after we settle back on 'offline' and revive the flicker.
+    clearConnectionOverlayTimer();
     pendingConnectionOverlayStage = stage;
     pendingConnectionOverlayDetail = detail || '';
     connectionOverlayVisible = true;
+    shownConnectionOverlayStage = stage;
     setConnectionOverlayStage(stage, detail);
 }
 function scheduleConnectionOverlay(stage, detail, delayMs = 1200) {
@@ -137,24 +237,25 @@ function updateConnectionOverlay(stage, detail) {
 function markHmrConnectionHealthy() {
     awaitingHealthyHmrMessage = false;
     clearConnectionOverlayTimer();
+    shownConnectionOverlayStage = null;
     if (connectionOverlayVisible) {
         connectionOverlayVisible = false;
         hideConnectionOverlay();
     }
 }
-/**
- * Flavor hooks
- */
-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 (TARGET_FLAVOR) {
-    case 'vue':
-        installNsVueDevShims();
-        break;
-    case 'angular':
-        installAngularHmrClientHooks();
-        break;
-}
+let CLIENT_STRATEGY;
+const CLIENT_STRATEGY_READY = TARGET_FLAVOR === 'vue' || TARGET_FLAVOR === 'angular'
+    ? import(`../frameworks/${TARGET_FLAVOR}/client/strategy.js`)
+        .then((mod) => {
+        CLIENT_STRATEGY = mod && mod[`${TARGET_FLAVOR}ClientStrategy`];
+        if (VERBOSE)
+            console.log('[hmr-client] client strategy loaded for flavor:', TARGET_FLAVOR);
+        CLIENT_STRATEGY?.install();
+    })
+        .catch((err) => {
+        console.warn('[hmr-client] failed to load client strategy for', TARGET_FLAVOR, err);
+    })
+    : Promise.resolve();
 // Track whether we've mounted an initial app root yet in HTTP-only boot
 let initialMounted = !!globalThis.__NS_HMR_BOOT_COMPLETE__;
 // Prevent duplicate initial-mount scheduling across rapid full-graph broadcasts and re-evaluations
@@ -172,7 +273,7 @@ let processingPromise = null;
 // Detect whether the early placeholder root is still active on screen
 function isPlaceholderActive() {
     try {
-        const g = globalThis;
+        const g = getGlobalScope();
         if (g.__NS_DEV_PLACEHOLDER_ROOT_VIEW__)
             return true;
         if (g.__NS_DEV_PLACEHOLDER_ROOT_EARLY__)
@@ -202,7 +303,7 @@ function applyFullGraph(payload) {
     // 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 g = getGlobalScope();
         const bootDone = !!g.__NS_HMR_BOOT_COMPLETE__;
         if (!bootDone && !initialMounted && !initialMounting && !g.__NS_HMR_RESCUE_SCHEDULED__ && TARGET_FLAVOR !== 'typescript') {
             // simple snapshot helpers
@@ -317,39 +418,7 @@ function applyFullGraph(payload) {
                         }
                         return;
                     }
-                    let candidate = null;
-                    switch (TARGET_FLAVOR) {
-                        case 'vue': {
-                            const appEntry = graph.get(APP_MAIN_ENTRY_SPEC);
-                            if (appEntry && Array.isArray(appEntry.deps)) {
-                                const vueDep = appEntry.deps.find((d) => typeof d === 'string' && /\.vue$/i.test(d));
-                                if (vueDep)
-                                    candidate = vueDep;
-                            }
-                            if (!candidate) {
-                                for (const id of graph.keys()) {
-                                    if (/\.vue$/i.test(id)) {
-                                        candidate = id;
-                                        break;
-                                    }
-                                }
-                            }
-                            // 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;
-                        }
-                    }
+                    const candidate = CLIENT_STRATEGY?.selectMountCandidate?.({ graph, appMainEntrySpec: APP_MAIN_ENTRY_SPEC }) ?? null;
                     if (!candidate)
                         return;
                     initialMounting = true;
@@ -360,10 +429,8 @@ function applyFullGraph(payload) {
                     (async () => {
                         try {
                             let comp = null;
-                            switch (TARGET_FLAVOR) {
-                                case 'vue':
-                                    comp = await loadSfcComponent(candidate, 'initial_mount_rescue');
-                                    break;
+                            if (CLIENT_STRATEGY?.loadComponentForMount) {
+                                comp = await CLIENT_STRATEGY.loadComponentForMount(candidate, 'initial_mount_rescue');
                             }
                             if (!comp)
                                 return;
@@ -404,41 +471,11 @@ function applyFullGraph(payload) {
         // Only allow initial mount when explicitly enabled. Rely on the app's own main entry start() for the first mount
         // to avoid double-mount races that can cause duplicate navigation logs.
         if (ALLOW_INITIAL_MOUNT && !initialMounted && !bootDone && !bootInProgress && !getCurrentApp() && !getRootFrame()) {
-            let candidate = null;
-            switch (TARGET_FLAVOR) {
-                case 'vue': {
-                    const appEntry = graph.get(APP_MAIN_ENTRY_SPEC);
-                    if (appEntry && Array.isArray(appEntry.deps)) {
-                        const vueDep = appEntry.deps.find((d) => typeof d === 'string' && /\.vue$/i.test(d));
-                        if (vueDep)
-                            candidate = vueDep;
-                    }
-                    if (!candidate) {
-                        for (const id of graph.keys()) {
-                            if (/\.vue$/i.test(id)) {
-                                candidate = id;
-                                break;
-                            }
-                        }
-                    }
-                    // 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': {
-                    // For TS flavor, do not perform client-driven initial mount; rely on Application.run.
-                    return;
-                }
+            if (TARGET_FLAVOR === 'typescript') {
+                // For TS flavor, do not perform client-driven initial mount; rely on Application.run.
+                return;
             }
+            const candidate = CLIENT_STRATEGY?.selectMountCandidate?.({ graph, appMainEntrySpec: APP_MAIN_ENTRY_SPEC }) ?? null;
             if (candidate) {
                 // Mark initial-mount in progress (both module-local and global) BEFORE scheduling async work
                 initialMounting = true;
@@ -452,7 +489,7 @@ function applyFullGraph(payload) {
                             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;
+                            const g = getGlobalScope();
                             const App = getCore('Application') || g.Application;
                             const isAndroid = !!(App && App.android !== undefined);
                             if (isAndroid) {
@@ -483,21 +520,19 @@ function applyFullGraph(payload) {
                         }
                         catch { }
                         let comp = null;
-                        switch (TARGET_FLAVOR) {
-                            case 'vue':
-                                comp = await loadSfcComponent(candidate, 'initial_mount');
-                                break;
-                            case 'typescript':
-                                try {
-                                    const url = await requestModuleFromServer(candidate);
-                                    const mod = await import(/* @vite-ignore */ url);
-                                    comp = mod && (mod.default || mod);
-                                }
-                                catch (e) {
-                                    if (VERBOSE)
-                                        console.warn('[hmr][init] TS initial mount failed to import', candidate, e);
-                                }
-                                break;
+                        if (TARGET_FLAVOR === 'typescript') {
+                            try {
+                                const url = await requestModuleFromServer(candidate);
+                                const mod = await import(/* @vite-ignore */ url);
+                                comp = mod && (mod.default || mod);
+                            }
+                            catch (e) {
+                                if (VERBOSE)
+                                    console.warn('[hmr][init] TS initial mount failed to import', candidate, e);
+                            }
+                        }
+                        else if (CLIENT_STRATEGY?.loadComponentForMount) {
+                            comp = await CLIENT_STRATEGY.loadComponentForMount(candidate, 'initial_mount');
                         }
                         if (comp) {
                             const ok = await performResetRoot(comp);
@@ -558,11 +593,7 @@ function applyDelta(payload) {
         setGraphVersion(payload.newVersion);
     }
     const changed = payload.changed || [];
-    switch (TARGET_FLAVOR) {
-        case 'vue':
-            recordVuePayloadChanges(changed, getGraphVersion());
-            break;
-    }
+    CLIENT_STRATEGY?.recordPayloadChanges?.(changed, getGraphVersion());
     (payload.changed || []).forEach((m) => {
         if (!m || !m.id)
             return;
@@ -629,7 +660,7 @@ function applyDelta(payload) {
             }
             if (isAppMainEntryId(id)) {
                 try {
-                    const exists = globalThis.require?.(id) || globalThis.__nsGetModuleExports?.(id);
+                    const exists = getGlobalScope().require?.(id) || globalThis.__nsGetModuleExports?.(id);
                     if (!exists && VERBOSE)
                         console.log(`[hmr][delta] skipping unresolved ${APP_MAIN_ENTRY_SPEC} change`);
                     if (!exists)
@@ -645,14 +676,10 @@ function applyDelta(payload) {
             processQueue();
     }
 }
-// Deterministic navigation using the current Vue app instance rather than vendor-held rootApp
+// Deterministic navigation using the current Vue app instance rather than vendor-held rootApp.
 function __nsNavigateUsingApp(comp, opts = {}) {
-    const g = globalThis;
-    switch (TARGET_FLAVOR) {
-        case 'vue':
-            ensureVueGlobals();
-            break;
-    }
+    const g = getGlobalScope();
+    CLIENT_STRATEGY?.beforeNavigateBuild?.();
     const AppFactory = g.createApp;
     const RootCtor = g.NSVRoot;
     if (typeof AppFactory !== 'function' || typeof RootCtor !== 'function') {
@@ -675,12 +702,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 (TARGET_FLAVOR) {
-            case 'vue':
-                ensurePiniaOnApp(app);
-                break;
-        }
+        // 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);
+        CLIENT_STRATEGY?.onNavAppCreated?.(app);
         try {
             const registry = g.__nsVendorRegistry;
             const req = registry?.get ? g.__nsVendorRequire || g.__nsRequire || g.require : g.__nsRequire || g.require;
@@ -775,6 +804,184 @@ try {
     globalThis.__nsNavigateUsingApp = __nsNavigateUsingApp;
 }
 catch { }
+const openModalRecords = [];
+let modalTrackingInstalled = false;
+/**
+ * Map a served/graph module id (e.g. `/app/modal-page.xml`) to its app-root
+ * relative path (`modal-page.xml`). Single mapping point — the raw-asset
+ * re-registration, page-navigation targets, and modal matching all derive
+ * from this; keep them in sync by construction.
+ */
+function toAppRelativePath(id) {
+    try {
+        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);
+        return relPath || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** App-root relative module name (no extension) for page-shaped files, else null. */
+function toAppModuleName(id) {
+    const relPath = toAppRelativePath(id);
+    if (!relPath || !/\.(xml|ts|js)$/i.test(relPath))
+        return null;
+    return relPath.replace(/\.(xml|ts|js)$/i, '');
+}
+function ensureModalTracking() {
+    if (modalTrackingInstalled)
+        return;
+    try {
+        const View = getCore('View') || getGlobalScope().View;
+        const proto = View?.prototype;
+        if (!proto || typeof proto.showModal !== 'function')
+            return;
+        const orig = proto.showModal;
+        if (orig.__nsHmrModalTracked) {
+            modalTrackingInstalled = true;
+            return;
+        }
+        const wrapped = function (...args) {
+            const result = orig.apply(this, args);
+            try {
+                if (typeof args[0] === 'string' && result) {
+                    // Mirror core's getModalOptions arg shapes: (moduleName, options)
+                    // or the deprecated positional form.
+                    const options = args.length === 2 && args[1] && typeof args[1] === 'object' ? args[1] : { context: args[1], closeCallback: args[2], fullscreen: args[3], animated: args[4], stretched: args[5] };
+                    const moduleName = String(args[0])
+                        .replace(/^\.\//, '')
+                        .replace(/\.(xml|ts|js)$/i, '');
+                    openModalRecords.push({ moduleName, options, parent: this, modal: result });
+                    if (VERBOSE)
+                        console.log('[hmr][modal] tracked open modal', moduleName);
+                }
+            }
+            catch { }
+            return result;
+        };
+        wrapped.__nsHmrModalTracked = true;
+        proto.showModal = wrapped;
+        modalTrackingInstalled = true;
+    }
+    catch (e) {
+        if (VERBOSE)
+            console.warn('[hmr][modal] tracking install failed', e);
+    }
+}
+/**
+ * Enumerate the modals that are currently presented AND were opened by module
+ * name, with everything needed to re-present them.
+ *
+ * Source of truth is core's live modal stack (`_getRootModalViews()`):
+ *   - `modal._moduleName` — set by the Builder on every createViewFromEntry
+ *     view (longstanding, used by livesync), so available on any core.
+ *   - `modal._modalOptions` — the original ShowModalOptions, stored by core's
+ *     `_showNativeModalView` (newer cores). For older cores the showModal
+ *     wrap's records (see ensureModalTracking) fill the gap.
+ *   - `modal._modalParent` — the presenting view.
+ * Stale wrap records are pruned against the live stack while we're here.
+ */
+function getOpenStringModuleModals() {
+    const out = [];
+    try {
+        const App = getCore('Application');
+        const root = App?.getRootView?.() || App?._rootView;
+        const stack = root?._getRootModalViews?.() || [];
+        // Prune wrap records whose modal is gone (keeps the fallback list small).
+        for (let i = openModalRecords.length - 1; i >= 0; i--) {
+            if (!stack.includes(openModalRecords[i].modal)) {
+                openModalRecords.splice(i, 1);
+            }
+        }
+        for (const modal of stack) {
+            const record = openModalRecords.find((r) => r.modal === modal);
+            const rawModuleName = typeof modal?._moduleName === 'string' && modal._moduleName ? modal._moduleName : record?.moduleName;
+            const parent = modal?._modalParent || record?.parent;
+            const options = modal?._modalOptions || record?.options;
+            if (!rawModuleName || !parent)
+                continue;
+            const moduleName = String(rawModuleName)
+                .replace(/^\.\//, '')
+                .replace(/\.(xml|ts|js)$/i, '');
+            out.push({ moduleName, options, parent, modal });
+        }
+    }
+    catch (e) {
+        if (VERBOSE)
+            console.warn('[hmr][modal] open-modal enumeration failed', e);
+    }
+    return out;
+}
+/**
+ * Close and re-present an open modal so it rebuilds from the freshly
+ * re-registered XML/code-behind. Core clears the modal stack synchronously on
+ * close but the NATIVE dismissal completes asynchronously; iOS refuses a
+ * present while a dismissal is in flight. Newer cores fire `closedModally` on
+ * the modal at exactly that completion point — preferred signal. Older cores
+ * fall back to polling `isLoaded` (flipped by `_tearDownUI` in the same
+ * completion callback).
+ */
+async function reshowOpenModal(record) {
+    const { parent, modal, moduleName, options } = record;
+    await new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (!settled) {
+                settled = true;
+                resolve();
+            }
+        };
+        let eventArmed = false;
+        try {
+            if (typeof modal.once === 'function') {
+                modal.once('closedModally', finish);
+                eventArmed = true;
+            }
+        }
+        catch { }
+        // Poll fallback (also the safety net if the event never fires —
+        // e.g. an interactive-dismiss cancellation).
+        const deadline = Date.now() + 2000;
+        const poll = () => {
+            if (settled)
+                return;
+            let stillLoaded = false;
+            try {
+                stillLoaded = !!modal.isLoaded;
+            }
+            catch { }
+            if ((!eventArmed && !stillLoaded) || Date.now() > deadline) {
+                finish();
+                return;
+            }
+            setTimeout(poll, 50);
+        };
+        setTimeout(poll, 50);
+        try {
+            modal.closeModal();
+        }
+        catch (e) {
+            if (VERBOSE)
+                console.warn('[hmr][modal] close failed for', moduleName, e);
+            finish();
+        }
+    });
+    // One settle beat so the platform finishes releasing the presentation
+    // before the new present begins.
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    try {
+        parent.showModal(moduleName, { ...(options || {}), animated: false });
+        if (VERBOSE)
+            console.log('[hmr][modal] re-presented', moduleName);
+    }
+    catch (e) {
+        console.warn('[hmr][modal] re-present failed for', moduleName, e);
+    }
+}
 async function processQueue() {
     if (!globalThis.__NS_HMR_BOOT_COMPLETE__) {
         if (VERBOSE)
@@ -810,7 +1017,43 @@ 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`,
+                });
+            }
+            let reimportFailures = 0;
             for (const id of drained) {
                 try {
                     const spec = normalizeSpec(id);
@@ -820,18 +1063,56 @@ async function processQueue() {
                     if (VERBOSE)
                         console.log('[hmr][queue] re-import', { id, spec, url });
                     const mod = await import(/* @vite-ignore */ url);
+                    // TS/XML flavor: refresh the bundler module registry with the fresh
+                    // exports so Builder.createViewFromEntry / loadModule('<page>')
+                    // resolves the NEW code-behind (tap handlers, page events) instead
+                    // of the stale module captured in the boot bundle. Without this,
+                    // XML re-renders pick up new markup but keep old behavior.
+                    if (TARGET_FLAVOR === 'typescript' && mod && /\.(ts|js)$/i.test(id)) {
+                        try {
+                            const g = getGlobalScope();
+                            const moduleName = toAppModuleName(id);
+                            if (moduleName && typeof g.registerModule === 'function') {
+                                g.registerModule(moduleName, () => mod);
+                                g.registerModule('./' + moduleName, () => mod);
+                                if (VERBOSE)
+                                    console.log('[hmr][queue] re-registered code-behind', moduleName);
+                            }
+                        }
+                        catch (e) {
+                            if (VERBOSE)
+                                console.warn('[hmr][queue] code-behind re-register failed for', id, e);
+                        }
+                    }
                 }
                 catch (e) {
-                    if (VERBOSE)
-                        console.warn('[hmr][queue] re-import failed for', id, e);
+                    // Never silent: a failed re-import means the device may keep
+                    // running the previous module body, so always surface it (not
+                    // verbose-gated) — otherwise the overlay reports success while
+                    // the app runs stale code.
+                    reimportFailures++;
+                    console.warn('[hmr][queue] re-import FAILED for', id, '-', e?.message ?? e);
                 }
             }
+            if (reimportFailures > 0) {
+                console.warn(`[hmr][queue] ${reimportFailures}/${drained.length} module(s) failed to re-import; the applied update may be incomplete.`);
+            }
             // After evaluating the batch, perform flavor-specific UI refresh.
             switch (TARGET_FLAVOR) {
                 case 'vue':
-                    // Vue SFCs are handled via the registry update path; nothing to do here.
+                    // graph + performResetRoot + getOverlay let the Vue strategy
+                    // propagate non-SFC dep changes to the nearest `.vue` boundary
+                    // and remount it (see `propagateDepChangeToSfcBoundary`).
+                    await CLIENT_STRATEGY?.refreshAfterBatch?.(drained, { setUpdateOverlayStage, startedAt: tQueueStart, graph, performResetRoot, getOverlay: getHmrOverlayApi });
                     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
@@ -850,8 +1131,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
@@ -875,6 +1158,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.
@@ -885,7 +1213,7 @@ async function processQueue() {
                         const findRouter = () => {
                             if (discoveredRouter)
                                 return discoveredRouter;
-                            const g = globalThis;
+                            const g = getGlobalScope();
                             if (g.__ns_router?.routesById)
                                 return (discoveredRouter = g.__ns_router);
                             // Fallback: scan common global keys for router
@@ -924,6 +1252,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;
@@ -935,22 +1272,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);
@@ -986,6 +1329,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': {
@@ -993,7 +1374,7 @@ async function processQueue() {
                     // This preserves the shell (Frame, ActionBar, etc.) that the app's
                     // own bootstrapping wires up via `Application.run`.
                     try {
-                        const g = globalThis;
+                        const g = getGlobalScope();
                         const App = getCore('Application') || g.Application;
                         if (!App || typeof App.resetRootView !== 'function') {
                             if (VERBOSE)
@@ -1019,10 +1400,9 @@ async function processQueue() {
                                             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 relPath = toAppRelativePath(id);
+                                            if (!relPath)
+                                                continue;
                                             const nicknames = ['./' + relPath, relPath];
                                             // Also add without extension for CSS
                                             const extIdx = relPath.lastIndexOf('.');
@@ -1048,21 +1428,24 @@ async function processQueue() {
                                 }
                             }
                         }
+                        // Modal-aware refresh: pages currently PRESENTED AS MODALS must be
+                        // closed + re-presented in place — navigating the top frame to a
+                        // modal's page would push it as a frame page, and resetRootView
+                        // would dismiss the modal entirely. State comes from core's live
+                        // modal stack (_moduleName/_modalOptions/_modalParent); the
+                        // showModal wrap only backfills options on older cores.
+                        ensureModalTracking();
+                        const openModals = getOpenStringModuleModals();
+                        const changedModuleNames = new Set(drained.map(toAppModuleName).filter(Boolean));
+                        const modalsToReshow = openModals.filter((record) => changedModuleNames.has(record.moduleName));
+                        const reshowModuleNames = new Set(modalsToReshow.map((record) => record.moduleName));
                         // 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');
+                            .map((id) => toAppModuleName(id))
+                            .filter((m) => m && m !== 'app-root' && !reshowModuleNames.has(m));
                         // 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:
@@ -1098,7 +1481,7 @@ async function processQueue() {
                             catch { }
                         }
                         if (VERBOSE)
-                            console.log('[hmr][queue] TS: changedXmlPages=', changedXmlPages, 'topFrame=', !!topFrame);
+                            console.log('[hmr][queue] TS: changedXmlPages=', changedXmlPages, 'topFrame=', !!topFrame, 'modalsToReshow=', modalsToReshow.length);
                         if (changedXmlPages.length > 0 && topFrame) {
                             // Navigate the current frame to the changed page directly.
                             // Use the last changed XML page (most specific).
@@ -1113,15 +1496,32 @@ async function processQueue() {
                                 App.resetRootView({ moduleName: 'app-root' });
                             }
                         }
-                        else {
+                        else if (modalsToReshow.length === 0) {
+                            // No frame page to refresh and no open modal owns the change —
+                            // fall back to a full root reset. (Skipped when an open modal is
+                            // being re-presented below: resetRootView would dismiss it.)
                             if (VERBOSE)
                                 console.log('[hmr][queue] TS flavor: resetRootView(app-root) after changes');
                             App.resetRootView({ moduleName: 'app-root' });
                         }
+                        // Re-present any open modals whose XML/code-behind changed. The
+                        // modules were already re-registered above (raw XML assets + fresh
+                        // code-behind exports), so the re-presented modal rebuilds from
+                        // the new content while the page beneath it stays put.
+                        for (const record of modalsToReshow) {
+                            await reshowOpenModal(record);
+                        }
                     }
                     catch (e) {
                         console.warn('[hmr][queue] TS flavor: resetRootView(app-root) failed', e);
                     }
+                    // Tell the overlay the cycle is done — same as the solid path
+                    // above. Without this the applying overlay sticks at
+                    // 'received' (5%) forever even though the in-place navigate /
+                    // resetRootView already applied the update.
+                    setUpdateOverlayStage('complete', {
+                        detail: `Total ${Math.max(0, Date.now() - tQueueStart)}ms`,
+                    });
                     break;
                 }
             }
@@ -1129,11 +1529,37 @@ async function processQueue() {
         finally {
             processingQueue = false;
             processingPromise = null;
+            // If a delta arrived mid-cycle (pushed onto changedQueue while
+            // processingQueue was still true, so its processQueue() call early-
+            // returned), re-drain — otherwise that save is stranded until the next
+            // delta. Deferred via setTimeout to avoid synchronous re-entrancy as
+            // this promise settles.
+            if (changedQueue.length) {
+                setTimeout(() => {
+                    try {
+                        processQueue();
+                    }
+                    catch { }
+                }, 0);
+            }
         }
     })();
     return processingPromise;
 }
 let hmrSocket = null;
+// Single reconnect timer. Overlapping close/timeout events used to each schedule
+// their own `setTimeout(connectHmr, …)`, stacking multiple pending reconnects
+// that could spawn (and leak) duplicate sockets/listeners. Route all reconnect
+// scheduling through here so only one is ever pending.
+let reconnectTimer = null;
+function scheduleReconnect(delayMs) {
+    if (reconnectTimer)
+        clearTimeout(reconnectTimer);
+    reconnectTimer = setTimeout(() => {
+        reconnectTimer = null;
+        connectHmr();
+    }, delayMs);
+}
 // Track server-announced batches for each version so we can import in-order client-side
 const txnClientBatches = new Map();
 // Public hook for NativeScript runtime to call from ImportModuleDynamicallyCallback later.
@@ -1161,10 +1587,16 @@ function connectHmr() {
     if (hmrSocket?.readyState === WebSocket.OPEN)
         return;
     if (hmrSocket?.readyState === WebSocket.CONNECTING) {
-        if (__NS_ENV_VERBOSE__)
+        if (VERBOSE)
             console.log('[hmr-client] Already connecting to HMR WebSocket, skipping');
         return;
     }
+    // A reconnect fired (or a manual connect raced one) — cancel any other pending
+    // reconnect so we don't end up with overlapping connect attempts.
+    if (reconnectTimer) {
+        clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+    }
     try {
         globalThis.__NS_HMR_CLIENT_SOCKET_READY__ = false;
     }
@@ -1172,7 +1604,7 @@ function connectHmr() {
     const overlayStage = hasOpenedHmrSocket ? 'reconnecting' : 'connecting';
     const baseUrl = getHMRWsUrl() || 'ws://localhost:5173/ns-hmr';
     const buildCandidates = (url) => {
-        let candidates = [];
+        const candidates = [];
         try {
             const u = new URL(url);
             const proto = u.protocol === 'wss:' ? ['wss'] : ['ws'];
@@ -1180,7 +1612,7 @@ function connectHmr() {
             // Build ordered host candidates with preference to the active HTTP origin
             const orderedHosts = [];
             try {
-                const g = globalThis;
+                const g = getGlobalScope();
                 const httpOrigin = g && typeof g.__NS_HTTP_ORIGIN__ === 'string' ? g.__NS_HTTP_ORIGIN__ : undefined;
                 if (httpOrigin) {
                     try {
@@ -1231,19 +1663,29 @@ function connectHmr() {
         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);
+            scheduleReconnect(1500);
             return;
         }
         const url = candidates[idx++];
         const connectionDetail = `${overlayStage === 'reconnecting' ? 'Retrying' : 'Opening'} ${url}`;
-        if (connectionOverlayVisible) {
+        if (overlayStage === 'reconnecting' && shownConnectionOverlayStage === 'offline') {
+            // Don't flip the visible 'offline' frame to 'reconnecting' for an
+            // attempt that may fail instantly — defer it so only a genuinely
+            // in-flight attempt surfaces. The deferred show is cancelled by
+            // showConnectionOverlayNow (offline re-show / synchronizing) the
+            // moment this attempt resolves. Keeps 'offline' stable instead of
+            // flickering once per retry. (Checking the PAINTED stage, not the
+            // pending one, so every candidate in the loop keeps deferring.)
+            scheduleConnectionOverlay(overlayStage, connectionDetail, RECONNECTING_OVER_OFFLINE_DELAY_MS);
+        }
+        else if (connectionOverlayVisible) {
             updateConnectionOverlay(overlayStage, connectionDetail);
         }
         else {
             scheduleConnectionOverlay(overlayStage, connectionDetail);
         }
         try {
-            if (__NS_ENV_VERBOSE__)
+            if (VERBOSE)
                 console.log('[hmr-client] Connecting to HMR WebSocket:', url);
             const sock = new WebSocket(url);
             hmrSocket = sock;
@@ -1273,7 +1715,16 @@ function connectHmr() {
                 if (connectionOverlayVisible) {
                     showConnectionOverlayNow('synchronizing', 'Connected. Synchronizing the HMR graph.');
                 }
-                VERBOSE && console.log('[hmr-client] Connected to HMR WebSocket');
+                if (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) => {
@@ -1297,7 +1748,7 @@ function connectHmr() {
                         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);
+                    scheduleReconnect(1000);
                 }
             };
         }
@@ -1333,10 +1784,26 @@ 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;
+        }
+        // The per-flavor client strategy is loaded by a dynamic import(); make
+        // sure it has resolved (and `install()` has run) before any handler that
+        // delegates through it. After the first message this is an already-settled
+        // promise (microtask only); for Solid/TypeScript it is `Promise.resolve()`.
+        await CLIENT_STRATEGY_READY;
         if (msg.type === 'ns:hmr-full-graph') {
             // Bump a monotonic nonce so HTTP ESM imports can always be cache-busted per update.
             try {
-                const g = globalThis;
+                const g = getGlobalScope();
                 g.__NS_HMR_IMPORT_NONCE__ = (typeof g.__NS_HMR_IMPORT_NONCE__ === 'number' ? g.__NS_HMR_IMPORT_NONCE__ : 0) + 1;
             }
             catch { }
@@ -1402,6 +1869,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);
@@ -1453,7 +1928,7 @@ async function handleHmrMessage(ev) {
         if (msg.type === 'ns:hmr-delta') {
             // Bump a monotonic nonce so HTTP ESM imports can always be cache-busted per update.
             try {
-                const g = globalThis;
+                const g = getGlobalScope();
                 g.__NS_HMR_IMPORT_NONCE__ = (typeof g.__NS_HMR_IMPORT_NONCE__ === 'number' ? g.__NS_HMR_IMPORT_NONCE__ : 0) + 1;
             }
             catch { }
@@ -1475,10 +1950,108 @@ async function handleHmrMessage(ev) {
             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 })) {
+            if (CLIENT_STRATEGY?.handleHotUpdateMessage && (await CLIENT_STRATEGY.handleHotUpdateMessage(msg, { getCore, verbose: VERBOSE, performResetRoot, getOverlay: getHmrOverlayApi }))) {
                 return;
             }
         }
@@ -1512,27 +2085,47 @@ 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;
         }
     }
     if (msg.type === 'ns:vue-sfc-registry') {
-        handleVueSfcRegistry(msg);
+        CLIENT_STRATEGY?.handleSfcRegistry?.(msg);
         return;
     }
     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%). The Vue
+        // strategy walks 'evicting' → 'reimporting' → 'rebooting' → 'complete'
+        // around the SFC load + reset so the toast always lands on 'complete'
+        // (or a failure detail) and the auto-hide timer can dismiss it.
+        await CLIENT_STRATEGY?.handleSfcRegistryUpdate?.(msg, getGraphVersion(), { getCore, verbose: VERBOSE, performResetRoot, getOverlay: getHmrOverlayApi });
         return;
     }
 }
@@ -1552,9 +2145,9 @@ function normalizeComponent(input, nameHint) {
         }
         // If provided a render function, wrap with defineComponent
         if (typeof input === 'function') {
-            ensureVueGlobals();
-            const comp = globalThis.defineComponent
-                ? globalThis.defineComponent({
+            CLIENT_STRATEGY?.beforeNavigateBuild?.();
+            const comp = getGlobalScope().defineComponent
+                ? getGlobalScope().defineComponent({
                     name: nameHint || input.name || 'AnonymousSFC',
                     render: input,
                 })
@@ -1563,9 +2156,9 @@ function normalizeComponent(input, nameHint) {
         }
         // If object has a render function property
         if (input?.render && typeof input.render === 'function') {
-            ensureVueGlobals();
-            const comp = globalThis.defineComponent
-                ? globalThis.defineComponent({
+            CLIENT_STRATEGY?.beforeNavigateBuild?.();
+            const comp = getGlobalScope().defineComponent
+                ? getGlobalScope().defineComponent({
                     name: nameHint || input.name || 'AnonymousSFC',
                     render: input.render,
                 })
@@ -1621,35 +2214,32 @@ async function performResetRoot(newComponent) {
                 if (cachedRoot)
                     return cachedRoot;
                 try {
-                    switch (TARGET_FLAVOR) {
-                        case 'vue':
-                            cachedRoot = getRootForVue(newComponent, state);
-                            break;
-                        case 'typescript': {
-                            // For TS flavor, treat the component as a factory or direct NS view.
-                            let root = null;
-                            try {
-                                if (typeof newComponent === 'function') {
-                                    root = newComponent();
-                                }
-                                else {
-                                    root = newComponent;
-                                }
+                    if (CLIENT_STRATEGY?.createRoot) {
+                        cachedRoot = CLIENT_STRATEGY.createRoot(newComponent, state);
+                    }
+                    else if (TARGET_FLAVOR === 'typescript') {
+                        // For TS flavor, treat the component as a factory or direct NS view.
+                        let root = null;
+                        try {
+                            if (typeof newComponent === 'function') {
+                                root = newComponent();
                             }
-                            catch (e) {
-                                console.warn('[hmr-client][ts] root factory invocation failed', e);
+                            else {
+                                root = newComponent;
                             }
-                            cachedRoot = root || {};
-                            // Heuristic: if the root "looks" like a Frame, prefer frame semantics
-                            try {
-                                const name = String(cachedRoot?.constructor?.name || '').replace(/^_+/, '');
-                                if (/^Frame(\$\d+)?$/.test(name)) {
-                                    rootKind = 'frame';
-                                }
+                        }
+                        catch (e) {
+                            console.warn('[hmr-client][ts] root factory invocation failed', e);
+                        }
+                        cachedRoot = root || {};
+                        // Heuristic: if the root "looks" like a Frame, prefer frame semantics
+                        try {
+                            const name = String(cachedRoot?.constructor?.name || '').replace(/^_+/, '');
+                            if (/^Frame(\$\d+)?$/.test(name)) {
+                                rootKind = 'frame';
                             }
-                            catch { }
-                            break;
                         }
+                        catch { }
                     }
                     return cachedRoot;
                 }
@@ -1667,7 +2257,7 @@ async function performResetRoot(newComponent) {
         return factory;
     }
     // Android readiness before any root changes
-    const App = getCore('Application') || globalThis.Application;
+    const App = getCore('Application') || getGlobalScope().Application;
     const isAndroid = !!(App && App.android !== undefined);
     if (isAndroid) {
         const isReady = () => {
@@ -1769,7 +2359,7 @@ async function performResetRoot(newComponent) {
     }
     catch { }
     try {
-        const AppAny = getCore('Application') || globalThis.Application;
+        const AppAny = getCore('Application') || getGlobalScope().Application;
         isIOS = !!(AppAny && AppAny.ios !== undefined);
     }
     catch { }
@@ -1779,7 +2369,7 @@ async function performResetRoot(newComponent) {
     // - Otherwise (subsequent HMR updates with an authoritative Frame already in place), re-use the
     //   current app Frame and navigate to the new Page. This avoids a brief flash that can occur
     //   when swapping the entire root view on Android. The placeholder is never involved here.
-    const gAnyForPolicy = globalThis;
+    const gAnyForPolicy = getGlobalScope();
     const placeholderFrame = (() => {
         try {
             return gAnyForPolicy.__NS_DEV_PLACEHOLDER_ROOT_VIEW__ || null;
@@ -1794,7 +2384,14 @@ async function performResetRoot(newComponent) {
     }
     catch { }
     const isAuthoritativeFrame = !!existingAppFrame && existingAppFrame !== placeholderFrame;
-    if (!hadPlaceholder && !isFrameRoot && isAuthoritativeFrame && typeof existingAppFrame.navigate === 'function') {
+    // Vue: skip the in-place navigate path. After `app.mount(NSVRoot)` in getRootForVue the
+    // new Page already has a parent (the freshly-constructed NSVRoot), so an attempt to navigate
+    // the existing app Frame to that same Page completes silently without ever rebinding the
+    // page to the Frame — the screen keeps showing the previous render. resetRootView with a
+    // fresh Frame correctly reparents the Page and is the proven path that produces visible
+    // in-place updates for SFC HMR cycles. Non-Vue flavors keep the legacy navigate fast path.
+    const allowNavigateFastPath = CLIENT_STRATEGY?.allowNavigateFastPath ?? true;
+    if (allowNavigateFastPath && !hadPlaceholder && !isFrameRoot && isAuthoritativeFrame && typeof existingAppFrame.navigate === 'function') {
         try {
             const navEntry = {
                 create: () => preparedRoot,
@@ -1813,7 +2410,7 @@ async function performResetRoot(newComponent) {
         console.log('[hmr-client] full root replacement via resetRootView (placeholder will be discarded)', { isFrameRoot, isIOS, hadPlaceholder });
     // Fallback or preferred path: resetRootView with a creator that builds a fresh Frame and navigates to the new Page
     try {
-        const App2 = getCore('Application') || globalThis.Application;
+        const App2 = getCore('Application') || getGlobalScope().Application;
         if (!App2 || typeof App2.resetRootView !== 'function') {
             console.warn('[hmr-client] Application.resetRootView unavailable');
             return false;
@@ -1832,7 +2429,7 @@ async function performResetRoot(newComponent) {
                     if (VERBOSE)
                         console.warn('[hmr-client] iOS Application.window is boolean false; attempting to clear cached window');
                     try {
-                        const g = globalThis;
+                        const g = getGlobalScope();
                         const reg = g.__nsVendorRegistry;
                         const req = reg?.get ? g.__nsVendorRequire || g.__nsRequire || g.require : g.__nsRequire || g.require;
                         let helpers = null;
@@ -1936,6 +2533,20 @@ export function initHmrClient(opts) {
     }
     g.__NS_HMR_CLIENT_ACTIVE__ = true;
     ensureCoreAliasesOnGlobalThis();
+    // XML flavor: record string-module modals from the moment the client is up
+    // so an already-open modal can be re-presented when its files change.
+    // Installed at init (not first-update time) because the wrap can only
+    // observe showModal calls made AFTER it lands. Retried briefly because
+    // getCore('View') may not resolve until the vendor realm finishes booting.
+    if (TARGET_FLAVOR === 'typescript') {
+        const tryInstallModalTracking = (attempts) => {
+            ensureModalTracking();
+            if (!modalTrackingInstalled && attempts > 0) {
+                setTimeout(() => tryInstallModalTracking(attempts - 1), 250);
+            }
+        };
+        tryInstallModalTracking(40);
+    }
     // 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.
@@ -1957,12 +2568,9 @@ export function initHmrClient(opts) {
             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 (TARGET_FLAVOR) {
-        case 'vue':
-            ensureBackWrapperInstalled(performResetRoot, getCore);
-            break;
-    }
+    // Best-effort: install back wrapper even before first remount; original root may be captured later.
+    // Deferred until the dynamically-imported strategy resolves.
+    void CLIENT_STRATEGY_READY.then(() => CLIENT_STRATEGY?.installBackWrapper?.(performResetRoot, getCore));
 }
 export default function startViteHMR(opts) {
     if (VERBOSE)