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

package/hmr/client/index.js

@@ -5,8 +5,9 @@
  * Always resolve core classes and Application from the vendor realm or globalThis at runtime.
  * The HMR client is evaluated via HTTP ESM on device; static imports would create secondary instances.
  */
-import { setHMRWsUrl, getHMRWsUrl, pendingModuleFetches, deriveHttpOrigin, setHttpOriginForVite, moduleFetchCache, requestModuleFromServer, getHttpOriginForVite, normalizeSpec, hmrMetrics, graph, setGraphVersion, getGraphVersion, getCurrentApp, getRootFrame, setCurrentApp, setRootFrame, getCore } from './utils.js';
+import { setHMRWsUrl, getHMRWsUrl, pendingModuleFetches, deriveHttpOrigin, setHttpOriginForVite, moduleFetchCache, requestModuleFromServer, getHttpOriginForVite, normalizeSpec, hmrMetrics, graph, setGraphVersion, getGraphVersion, getCurrentApp, getRootFrame, setCurrentApp, setRootFrame, getCore, hasExplicitEviction, invalidateModulesByUrls, buildEvictionUrls, emitHmrModeBannerOnce } from './utils.js';
 import { handleCssUpdates } from './css-handler.js';
+import { buildCssApplyingDetail, buildCssAppliedDetail } from './css-update-overlay.js';
 const VERBOSE = typeof __NS_ENV_VERBOSE__ !== 'undefined' && __NS_ENV_VERBOSE__;
 function resolveTargetFlavor() {
     try {
@@ -101,6 +102,79 @@ function hideConnectionOverlay() {
     }
     catch { }
 }
+function setUpdateOverlayStage(stage, info) {
+    try {
+        const api = getHmrOverlayApi();
+        if (api && typeof api.setUpdateStage === 'function') {
+            api.setUpdateStage(stage, info);
+        }
+    }
+    catch { }
+}
+// Store the listener registry on globalThis (rather than in a module-private
+// closure) because in NativeScript the HMR client module and the user app
+// modules can resolve to different module instances depending on how the
+// dev runtime loads them (HTTP client URL vs. the bundled vendor realm).
+// A module-local Set would not be shared across instances; the global one
+// is.
+function getNsSolidHmrListenerSet() {
+    const g = globalThis;
+    let set = g.__ns_solid_hmr_listener_set;
+    if (!set) {
+        set = new Set();
+        g.__ns_solid_hmr_listener_set = set;
+    }
+    return set;
+}
+function nsSolidHmrSubscribe(fn) {
+    const listeners = getNsSolidHmrListenerSet();
+    listeners.add(fn);
+    if (VERBOSE)
+        console.log('[hmr][solid] subscribe — listeners=', listeners.size);
+    return () => listeners.delete(fn);
+}
+function nsSolidHmrEmit(ev) {
+    const listeners = getNsSolidHmrListenerSet();
+    if (VERBOSE)
+        console.log('[hmr][solid] emit listeners=', listeners.size, 'changedFiles=', ev.changedFiles);
+    for (const fn of Array.from(listeners)) {
+        try {
+            fn(ev);
+        }
+        catch (err) {
+            if (VERBOSE)
+                console.warn('[hmr][solid] listener threw', err);
+        }
+    }
+}
+try {
+    const g = globalThis;
+    g.__ns_solid_hmr_subscribe = nsSolidHmrSubscribe;
+    // Eagerly create the listener set so the global exists at module load time.
+    getNsSolidHmrListenerSet();
+    if (VERBOSE)
+        console.log('[hmr][solid] HMR client loaded. global set=', typeof g.__ns_solid_hmr_subscribe, 'listenerSet=', typeof g.__ns_solid_hmr_listener_set);
+}
+catch (err) {
+    console.warn('[hmr][solid] could not install global __ns_solid_hmr_subscribe', err);
+}
+// Eagerly drive the HMR-applying overlay's 'received' frame as soon
+// as the server emits `ns:hmr-pending`, BEFORE the framework-specific
+// (`ns:angular-update` / `ns:css-updates`) payload arrives. The
+// flavor-specific handler later walks through 'evicting' →
+// 'reimporting' → 'rebooting' → 'complete'. Calling 'received' twice
+// in the same cycle is safe: the overlay preserves
+// `updateCycleStartedAt` when a 'received' frame replaces an existing
+// 'received' frame so the minimum-visible window is still timed
+// against the FIRST frame.
+//
+// Soft-fails when the overlay isn't installed (production builds,
+// vitest, etc.) or when the user opted out via
+// `__NS_HMR_PROGRESS_OVERLAY_ENABLED__ === false`.
+import { applyHmrPendingFrame } from './hmr-pending-overlay.js';
+function setHmrPendingOverlay(filePath) {
+    applyHmrPendingFrame(filePath, { getOverlay: getHmrOverlayApi });
+}
 let connectionOverlayTimer = null;
 let connectionOverlayVisible = false;
 let hasOpenedHmrSocket = false;
@@ -142,19 +216,19 @@ function markHmrConnectionHealthy() {
         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`] ?? mod.default);
+        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
@@ -317,39 +391,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 +402,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 +444,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;
@@ -483,21 +493,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 +566,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;
@@ -648,11 +652,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 (TARGET_FLAVOR) {
-        case 'vue':
-            ensureVueGlobals();
-            break;
-    }
+    CLIENT_STRATEGY?.beforeNavigateBuild?.();
     const AppFactory = g.createApp;
     const RootCtor = g.NSVRoot;
     if (typeof AppFactory !== 'function' || typeof RootCtor !== 'function') {
@@ -675,12 +675,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;
@@ -810,7 +812,42 @@ async function processQueue() {
                 return;
             if (VERBOSE)
                 console.log('[hmr][queue] processing changed ids', drained);
+            // Track wall-clock so the 'complete' frame can show a meaningful
+            // total. Only the Solid + TypeScript flavors drive the overlay
+            // from here; Angular has its own flow inside
+            // `frameworks/angular/client/index.ts`.
+            const tQueueStart = Date.now();
+            const driveSolidOverlay = TARGET_FLAVOR === 'solid';
+            // Explicit eviction step.
+            //
+            // On modern runtimes the URL canonicalizer collapses any
+            // `__ns_hmr__/<tag>/` segment back to a stable cache key, so
+            // without explicit eviction the upcoming `import(url)` would
+            // resolve via V8's `g_moduleRegistry` and return the cached
+            // stale module — making the queue drain a silent no-op for
+            // every save after the first.
+            //
+            // We hand the canonical eviction URLs to the runtime first;
+            // `invalidateModulesByUrls` is a no-op on older runtimes and
+            // `requestModuleFromServer` automatically falls back to the
+            // legacy `/ns/m/__ns_hmr__/v<N>/` URL versioning path in that
+            // case. node_modules and virtual specs are filtered out by
+            // `buildEvictionUrls` so vendor modules stay hot.
+            if (driveSolidOverlay) {
+                setUpdateOverlayStage('evicting', {
+                    detail: drained.length === 1 ? `Invalidating ${drained[0]}` : `Invalidating ${drained.length} modules`,
+                });
+            }
+            const evictUrls = buildEvictionUrls(drained);
+            const evicted = invalidateModulesByUrls(evictUrls);
+            if (VERBOSE)
+                console.log(`[hmr][queue] eviction count=${evictUrls.length} ok=${evicted}`);
             // Evaluate changed modules best-effort; failures shouldn't completely break HMR.
+            if (driveSolidOverlay) {
+                setUpdateOverlayStage('reimporting', {
+                    detail: drained.length === 1 ? `Re-importing ${drained[0]}` : `Re-importing ${drained.length} modules`,
+                });
+            }
             for (const id of drained) {
                 try {
                     const spec = normalizeSpec(id);
@@ -829,9 +866,16 @@ async function processQueue() {
             // 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.
+                    await CLIENT_STRATEGY?.refreshAfterBatch?.(drained, { setUpdateOverlayStage, startedAt: tQueueStart });
                     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 +894,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 +921,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.
@@ -924,6 +1015,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 +1035,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 +1092,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': {
@@ -1274,6 +1418,14 @@ function connectHmr() {
                     showConnectionOverlayNow('synchronizing', 'Connected. Synchronizing the HMR graph.');
                 }
                 VERBOSE && console.log('[hmr-client] Connected to HMR WebSocket');
+                // Print the active module reload mode once on first
+                // successful connect so the user can correlate HMR latency
+                // with runtime capability without grepping for protocol
+                // details. The banner is verbose-gated.
+                try {
+                    emitHmrModeBannerOnce();
+                }
+                catch { }
             };
             sock.onmessage = handleHmrMessage;
             sock.onerror = (error) => {
@@ -1333,6 +1485,22 @@ 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 {
@@ -1402,6 +1570,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);
@@ -1475,10 +1651,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 +1786,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,7 +1846,7 @@ function normalizeComponent(input, nameHint) {
         }
         // If provided a render function, wrap with defineComponent
         if (typeof input === 'function') {
-            ensureVueGlobals();
+            CLIENT_STRATEGY?.beforeNavigateBuild?.();
             const comp = globalThis.defineComponent
                 ? globalThis.defineComponent({
                     name: nameHint || input.name || 'AnonymousSFC',
@@ -1563,7 +1857,7 @@ function normalizeComponent(input, nameHint) {
         }
         // If object has a render function property
         if (input?.render && typeof input.render === 'function') {
-            ensureVueGlobals();
+            CLIENT_STRATEGY?.beforeNavigateBuild?.();
             const comp = globalThis.defineComponent
                 ? globalThis.defineComponent({
                     name: nameHint || input.name || 'AnonymousSFC',
@@ -1621,35 +1915,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;
                 }
@@ -1794,7 +2085,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,
@@ -1957,12 +2255,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)