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

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,80 @@ function hideConnectionOverlay() {
     }
     catch { }
 }
+function setUpdateOverlayStage(stage, info) {
+    try {
+        const api = getHmrOverlayApi();
+        if (api && typeof api.setUpdateStage === 'function') {
+            api.setUpdateStage(stage, info);
+        }
+    }
+    catch { }
+}
+// Store the listener registry on globalThis (rather than in a module-private
+// closure) because in NativeScript the HMR client module and the user app
+// modules can resolve to different module instances depending on how the
+// dev runtime loads them (HTTP client URL vs. the bundled vendor realm).
+// A module-local Set would not be shared across instances; the global one
+// is.
+function getNsSolidHmrListenerSet() {
+    const g = globalThis;
+    let set = g.__ns_solid_hmr_listener_set;
+    if (!set) {
+        set = new Set();
+        g.__ns_solid_hmr_listener_set = set;
+    }
+    return set;
+}
+function nsSolidHmrSubscribe(fn) {
+    const listeners = getNsSolidHmrListenerSet();
+    listeners.add(fn);
+    if (VERBOSE)
+        console.log('[hmr][solid] subscribe — listeners=', listeners.size);
+    return () => listeners.delete(fn);
+}
+function nsSolidHmrEmit(ev) {
+    const listeners = getNsSolidHmrListenerSet();
+    if (VERBOSE)
+        console.log('[hmr][solid] emit listeners=', listeners.size, 'changedFiles=', ev.changedFiles);
+    for (const fn of Array.from(listeners)) {
+        try {
+            fn(ev);
+        }
+        catch (err) {
+            if (VERBOSE)
+                console.warn('[hmr][solid] listener threw', err);
+        }
+    }
+}
+try {
+    const g = globalThis;
+    g.__ns_solid_hmr_subscribe = nsSolidHmrSubscribe;
+    // Eagerly create the listener set so the global exists at module load time.
+    getNsSolidHmrListenerSet();
+    if (VERBOSE)
+        console.log('[hmr][solid] HMR client loaded. global set=', typeof g.__ns_solid_hmr_subscribe, 'listenerSet=', typeof g.__ns_solid_hmr_listener_set);
+}
+catch (err) {
+    console.warn('[hmr][solid] could not install global __ns_solid_hmr_subscribe', err);
+}
+// Eagerly drive the HMR-applying overlay's 'received' frame as soon
+// as the server emits `ns:hmr-pending`, BEFORE the framework-specific
+// (`ns:angular-update` / `ns:css-updates`) payload arrives. The
+// flavor-specific handler later walks through 'evicting' →
+// 'reimporting' → 'rebooting' → 'complete'. Calling 'received' twice
+// in the same cycle is safe: the overlay preserves
+// `updateCycleStartedAt` when a 'received' frame replaces an existing
+// 'received' frame so the minimum-visible window is still timed
+// against the FIRST frame.
+//
+// Soft-fails when the overlay isn't installed (production builds,
+// vitest, etc.) or when the user opted out via
+// `__NS_HMR_PROGRESS_OVERLAY_ENABLED__ === false`.
+import { applyHmrPendingFrame } from './hmr-pending-overlay.js';
+import { driveVueSfcUpdateOverlay } from './vue-sfc-update-overlay.js';
+function setHmrPendingOverlay(filePath) {
+    applyHmrPendingFrame(filePath, { getOverlay: getHmrOverlayApi });
+}
 let connectionOverlayTimer = null;
 let connectionOverlayVisible = false;
 let hasOpenedHmrSocket = false;
@@ -675,7 +750,13 @@ 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)));
+        // Forward `opts.props` as Vue's rootProps so `$navigateTo(Comp, { props: { … } })`
+        // reaches the destination component. nativescript-vue's stock `$navigateTo`
+        // does the same via `createNativeView(target, options?.props, …)` →
+        // `renderer.createApp(component, props)`. Dropping props here would surface
+        // at the destination as `[Vue warn]: Missing required prop` and any
+        // required-prop component would render with `undefined` bindings.
+        const app = AppFactory(normalizeComponent(comp, comp && (comp.__name || comp.name)), opts && opts.props);
         switch (TARGET_FLAVOR) {
             case 'vue':
                 ensurePiniaOnApp(app);
@@ -810,7 +891,42 @@ async function processQueue() {
                 return;
             if (VERBOSE)
                 console.log('[hmr][queue] processing changed ids', drained);
+            // Track wall-clock so the 'complete' frame can show a meaningful
+            // total. Only the Solid + TypeScript flavors drive the overlay
+            // from here; Angular has its own flow inside
+            // `frameworks/angular/client/index.ts`.
+            const tQueueStart = Date.now();
+            const driveSolidOverlay = TARGET_FLAVOR === 'solid';
+            // Explicit eviction step.
+            //
+            // On modern runtimes the URL canonicalizer collapses any
+            // `__ns_hmr__/<tag>/` segment back to a stable cache key, so
+            // without explicit eviction the upcoming `import(url)` would
+            // resolve via V8's `g_moduleRegistry` and return the cached
+            // stale module — making the queue drain a silent no-op for
+            // every save after the first.
+            //
+            // We hand the canonical eviction URLs to the runtime first;
+            // `invalidateModulesByUrls` is a no-op on older runtimes and
+            // `requestModuleFromServer` automatically falls back to the
+            // legacy `/ns/m/__ns_hmr__/v<N>/` URL versioning path in that
+            // case. node_modules and virtual specs are filtered out by
+            // `buildEvictionUrls` so vendor modules stay hot.
+            if (driveSolidOverlay) {
+                setUpdateOverlayStage('evicting', {
+                    detail: drained.length === 1 ? `Invalidating ${drained[0]}` : `Invalidating ${drained.length} modules`,
+                });
+            }
+            const evictUrls = buildEvictionUrls(drained);
+            const evicted = invalidateModulesByUrls(evictUrls);
+            if (VERBOSE)
+                console.log(`[hmr][queue] eviction count=${evictUrls.length} ok=${evicted}`);
             // Evaluate changed modules best-effort; failures shouldn't completely break HMR.
+            if (driveSolidOverlay) {
+                setUpdateOverlayStage('reimporting', {
+                    detail: drained.length === 1 ? `Re-importing ${drained[0]}` : `Re-importing ${drained.length} modules`,
+                });
+            }
             for (const id of drained) {
                 try {
                     const spec = normalizeSpec(id);
@@ -829,9 +945,34 @@ 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.
+                    // Vue SFCs are handled via the registry update path
+                    // (which drives its own overlay completion through
+                    // `driveVueSfcUpdateOverlay`); nothing else to do
+                    // for the view-tree refresh here.
+                    //
+                    // However, when a non-SFC file (e.g. a `.ts`
+                    // utility module imported by an SFC) is the only
+                    // changed entry, no `ns:vue-sfc-registry-update`
+                    // will follow — and without an explicit 'complete'
+                    // the overlay would stick on "Preparing update
+                    // (5%)". Drive the closing frame here so the
+                    // auto-hide timer can dismiss the toast in the
+                    // pure-TS-change case. The detail surfaces the
+                    // changed count so a user can correlate the
+                    // overlay with the server-side `[hmr-ws][update]`
+                    // log.
+                    setUpdateOverlayStage('complete', {
+                        detail: drained.length === 1 ? `Updated ${drained[0]} in ${Math.max(0, Date.now() - tQueueStart)}ms` : `Updated ${drained.length} modules in ${Math.max(0, Date.now() - tQueueStart)}ms`,
+                    });
                     break;
                 case 'solid': {
+                    // Boundaries discovered in this HMR cycle (tsx files reachable
+                    // via the reverse import graph from any changed file, plus route
+                    // files reachable from any tsx start point). Declared at the top
+                    // of the case block so the emit step below can include the
+                    // complete set in the listener event — framework integrations
+                    // use it to map route boundaries → fresh component references.
+                    const boundaries = new Set();
                     // Solid .tsx components are self-accepting via solid-refresh's inline
                     // patchRegistry — re-importing them is sufficient. For non-component
                     // .ts utility modules, we must propagate up the import graph to find
@@ -850,8 +991,10 @@ async function processQueue() {
                                 arr.push(id);
                             }
                         }
-                        // BFS from each non-tsx changed module up to tsx/jsx boundaries
-                        const boundaries = new Set();
+                        // Pass 1: BFS from each non-tsx changed module up to tsx/jsx
+                        // boundaries. These get re-imported below so solid-refresh's
+                        // inline patchRegistry runs and (best-effort) swaps the proxy
+                        // signals for any components defined in those tsx boundaries.
                         for (const id of drained) {
                             if (/\.(tsx|jsx)$/i.test(id))
                                 continue; // already self-accepting
@@ -875,6 +1018,51 @@ async function processQueue() {
                                 }
                             }
                         }
+                        // Pass 2: walk further from any tsx starting point (a tsx file
+                        // in `drained` OR a tsx boundary discovered in pass 1) to find
+                        // route files (`/src/routes/*.{tsx,jsx}`) that transitively
+                        // import them. Re-importing a route file refreshes its
+                        // `Route.options.component` to the freshly-imported reference
+                        // and the existing boundary loop below patches the live router
+                        // with that fresh reference.
+                        //
+                        // This is the key fix for "edit home.tsx → save → no visual
+                        // update": the old BFS skipped tsx files in `drained` (assuming
+                        // solid-refresh's in-place proxy patch was sufficient), but in
+                        // the universal-renderer + nested-context configuration that
+                        // patch does not always propagate to the visible page tree.
+                        // Adding the route file as a boundary lets us patch
+                        // `route.options.component` directly to a fresh module export,
+                        // which the framework subscriber then passes through to the
+                        // page remount — making the cycle robust to the proxy patch
+                        // silently failing.
+                        const tsxStarts = new Set();
+                        for (const id of drained) {
+                            if (/\.(tsx|jsx)$/i.test(id))
+                                tsxStarts.add(id);
+                        }
+                        for (const b of boundaries)
+                            tsxStarts.add(b);
+                        const ROUTE_FILE_RE = /\/src\/routes\/.+\.(tsx|jsx)$/i;
+                        for (const start of tsxStarts) {
+                            const visited = new Set();
+                            const queue = [start];
+                            while (queue.length) {
+                                const cur = queue.shift();
+                                if (visited.has(cur))
+                                    continue;
+                                visited.add(cur);
+                                if (cur !== start && ROUTE_FILE_RE.test(cur)) {
+                                    boundaries.add(cur);
+                                }
+                                const importers = reverseIndex.get(cur);
+                                if (!importers)
+                                    continue;
+                                for (const imp of importers) {
+                                    queue.push(imp);
+                                }
+                            }
+                        }
                         // Re-import each boundary so solid-refresh patchRegistry fires.
                         // For route files (TanStack Router), capture the new Route export
                         // and patch the router's existing route with the fresh loader.
@@ -924,6 +1112,15 @@ async function processQueue() {
                             }
                             return null;
                         };
+                        // Evict the boundary set so re-importing each .tsx
+                        // component actually picks up the new transitive
+                        // dependency code; without this V8 returns the
+                        // cached boundary module unchanged.
+                        const boundaryIds = Array.from(boundaries);
+                        const solidEvictUrls = buildEvictionUrls(boundaryIds);
+                        const solidEvicted = invalidateModulesByUrls(solidEvictUrls);
+                        if (VERBOSE)
+                            console.log(`[hmr][solid] eviction count=${solidEvictUrls.length} ok=${solidEvicted}`);
                         for (const id of boundaries) {
                             if (seen.has(id))
                                 continue;
@@ -935,22 +1132,28 @@ async function processQueue() {
                                 if (VERBOSE)
                                     console.log('[hmr][solid] propagated to boundary', { id, url });
                                 const mod = await import(/* @vite-ignore */ url);
-                                // Patch TanStack Router route loaders
+                                // Patch TanStack Router route options for any module
+                                // that exports a `Route`. We patch BOTH the component
+                                // and the loader (when present); components-only routes
+                                // were previously skipped because the gate required a
+                                // loader, which left their `options.component` pointing
+                                // at the stale module's exports after HMR.
                                 try {
                                     const newRoute = mod?.Route;
-                                    if (newRoute?.options?.loader) {
+                                    if (newRoute?.options) {
                                         const router = findRouter();
                                         const fullPath = boundaryToFullPath(id);
                                         if (VERBOSE)
-                                            console.log('[hmr][solid][diag] route patch attempt', { id, fullPath, hasRouter: !!router, routesByIdKeys: router?.routesById ? Object.keys(router.routesById) : 'none' });
+                                            console.log('[hmr][solid][diag] route patch attempt', { id, fullPath, hasRouter: !!router, hasLoader: !!newRoute.options.loader, hasComponent: !!newRoute.options.component });
                                         const existingRoute = fullPath && router ? findRouteByFullPath(router, fullPath) : null;
                                         if (existingRoute?.options) {
-                                            existingRoute.options.loader = newRoute.options.loader;
+                                            if (newRoute.options.loader)
+                                                existingRoute.options.loader = newRoute.options.loader;
                                             if (newRoute.options.component)
                                                 existingRoute.options.component = newRoute.options.component;
                                             routesPatchCount++;
                                             if (VERBOSE)
-                                                console.log('[hmr][solid] patched route loader', existingRoute.id, 'fullPath=', fullPath);
+                                                console.log('[hmr][solid] patched route', existingRoute.id, 'fullPath=', fullPath);
                                         }
                                         else if (VERBOSE) {
                                             console.log('[hmr][solid] no matching route for fullPath', fullPath);
@@ -986,6 +1189,44 @@ async function processQueue() {
                         if (VERBOSE)
                             console.warn('[hmr][solid] propagation failed', e);
                     }
+                    // Notify any framework integrations (e.g.
+                    // `@nativescript/tanstack-router`) that a Solid HMR
+                    // cycle has completed. They use this signal to perform
+                    // framework-specific UI refresh (e.g. remount the active
+                    // router page) when solid-refresh's own reactive
+                    // propagation does not reach the visible tree under
+                    // the current renderer/context configuration.
+                    //
+                    // Boundaries include both the directly-changed tsx files
+                    // AND every tsx ancestor reachable via the reverse import
+                    // graph (route files in particular). The framework
+                    // listener uses the route-file boundaries to look up the
+                    // freshly-patched `route.options.component` and pass it
+                    // through to the page remount.
+                    try {
+                        const tsxChangedInDrained = drained.filter((id) => /\.(tsx|jsx)$/i.test(id));
+                        const allBoundaries = Array.from(new Set([...tsxChangedInDrained, ...boundaries]));
+                        nsSolidHmrEmit({
+                            kind: 'solid',
+                            changedFiles: drained.slice(),
+                            boundaries: allBoundaries,
+                        });
+                    }
+                    catch (err) {
+                        if (VERBOSE)
+                            console.warn('[hmr][solid] emit failed', err);
+                    }
+                    // Tell the overlay the cycle is done. solid-refresh's
+                    // inline patchRegistry has already flushed the new
+                    // component bodies into the live tree (the `case
+                    // 'solid'` block above re-imports each .tsx
+                    // boundary), so by the time we get here the user is
+                    // already looking at the new render. The 'complete'
+                    // frame surfaces the wall-clock total and triggers
+                    // the overlay's auto-hide.
+                    setUpdateOverlayStage('complete', {
+                        detail: `Total ${Math.max(0, Date.now() - tQueueStart)}ms`,
+                    });
                     break;
                 }
                 case 'typescript': {
@@ -1274,6 +1515,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 +1582,17 @@ async function handleHmrMessage(ev) {
         catch { }
     }
     if (msg) {
+        // `ns:hmr-pending` is a fire-and-forget UX hint emitted by the
+        // server at the START of handleHotUpdate. We drive the
+        // HMR-applying overlay's 'received' frame here (synchronously),
+        // well before the authoritative payload (`ns:angular-update` /
+        // `ns:css-updates`) lands. Skip running any other handlers —
+        // the pending message has no module payload and intentionally
+        // does not bump the graph version.
+        if (msg.type === 'ns:hmr-pending' && typeof msg.path === 'string') {
+            setHmrPendingOverlay(msg.path);
+            return;
+        }
         if (msg.type === 'ns:hmr-full-graph') {
             // Bump a monotonic nonce so HTTP ESM imports can always be cache-busted per update.
             try {
@@ -1402,6 +1662,14 @@ async function handleHmrMessage(ev) {
                 });
                 if (toReimport.length && VERBOSE)
                     console.log('[hmr][full-graph] inferred changed modules; re-importing', toReimport);
+                // Evict the inferred changed set before re-importing.
+                // See `processQueue` for the architectural rationale; the
+                // full-graph code path is the resync fallback (server chose
+                // not to send a delta) and shares the same V8 cache pitfall.
+                const fgEvictUrls = buildEvictionUrls(toReimport);
+                const fgEvicted = invalidateModulesByUrls(fgEvictUrls);
+                if (VERBOSE)
+                    console.log(`[hmr][full-graph] eviction count=${fgEvictUrls.length} ok=${fgEvicted}`);
                 for (const id of toReimport) {
                     try {
                         const spec = normalizeSpec(id);
@@ -1475,6 +1743,104 @@ 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));
             }
@@ -1512,13 +1878,32 @@ async function handleHmrMessage(ev) {
         return;
     }
     if (msg.type === 'ns:css-updates' && Array.isArray(msg.updates)) {
+        // Drive the HMR-applying overlay past the 'received' (5%) frame
+        // that `ns:hmr-pending` set earlier in the cycle. Without this
+        // the overlay sticks at "Preparing update" forever for CSS-only
+        // edits because `handleCssUpdates` is a leaf — there's no
+        // downstream module-evaluation path that would hit the queue's
+        // 'complete' transition.
+        const cssCount = msg.updates.length;
+        try {
+            setUpdateOverlayStage('reimporting', { detail: buildCssApplyingDetail(cssCount) });
+        }
+        catch { }
         try {
             const origin = msg.origin || getHttpOriginForVite() || deriveHttpOrigin(getHMRWsUrl());
             await handleCssUpdates(msg.updates, origin);
+            try {
+                setUpdateOverlayStage('complete', { detail: buildCssAppliedDetail(cssCount) });
+            }
+            catch { }
             return;
         }
         catch (e) {
             console.warn('[hmr-client] CSS updates handling failed:', e);
+            try {
+                setUpdateOverlayStage('complete', { detail: 'CSS update failed' });
+            }
+            catch { }
             return;
         }
     }
@@ -1529,10 +1914,22 @@ async function handleHmrMessage(ev) {
     if (msg.type === 'ns:vue-sfc-registry-update') {
         if (typeof msg.version === 'number')
             setGraphVersion(msg.version);
-        const comp = await handleVueSfcRegistryUpdate(msg, getGraphVersion());
-        if (comp) {
-            await performResetRoot(comp);
-        }
+        // `ns:hmr-pending` already set the overlay to 'received' (5%).
+        // Without the explicit stage walk below the overlay would stick
+        // at "Preparing update" forever after a successful SFC swap —
+        // the Vue path was missing the framework-specific completion
+        // hooks that Angular drives via `handleAngularHotUpdateMessage`
+        // and CSS drives inline above. `driveVueSfcUpdateOverlay` is a
+        // thin orchestrator that walks 'evicting' → 'reimporting' →
+        // 'rebooting' → 'complete' around the load + reset steps and
+        // always lands on 'complete' (or a failure detail) so the
+        // auto-hide timer can dismiss the toast.
+        const sfcFilePath = typeof msg.path === 'string' ? msg.path : undefined;
+        await driveVueSfcUpdateOverlay({
+            filePath: sfcFilePath,
+            loadComponent: () => handleVueSfcRegistryUpdate(msg, getGraphVersion()),
+            applyComponent: (component) => performResetRoot(component),
+        }, { getOverlay: getHmrOverlayApi });
         return;
     }
 }
@@ -1794,7 +2191,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 = TARGET_FLAVOR !== 'vue';
+    if (allowNavigateFastPath && !hadPlaceholder && !isFrameRoot && isAuthoritativeFrame && typeof existingAppFrame.navigate === 'function') {
         try {
             const navEntry = {
                 create: () => preparedRoot,