@nativescript/vite 8.0.0-alpha.6 → 8.0.0-alpha.61

package/hmr/shared/runtime/dev-overlay.js

@@ -1,18 +1,42 @@
-const BOOT_TITLE = 'NativeScript Vite preparing dev session...';
-const DEFAULT_SNAPSHOT = {
-    visible: false,
-    mode: 'hidden',
-    badge: 'HMR',
-    title: BOOT_TITLE,
-    phase: '',
-    detail: '',
-    progress: null,
-    busy: false,
-    blocking: false,
-    tone: 'info',
-};
+import { BOOT_PLACEHOLDER_MOTION, computeBootProgressFillScale, formatBootDetailLine, formatBootPrimaryLine } from './boot-placeholder-ui.js';
+import { BOOT_TITLE, DEFAULT_SNAPSHOT, createBootOverlaySnapshot, createConnectionOverlaySnapshot, createUpdateOverlaySnapshot } from './dev-overlay-snapshots.js';
+import { getGlobalScope } from './global-scope.js';
+// Re-export the snapshot model so existing `./dev-overlay.js` importers keep working.
+export { createBootOverlaySnapshot, createConnectionOverlaySnapshot, createUpdateOverlaySnapshot } from './dev-overlay-snapshots.js';
+const DEFAULT_OVERLAY_POSITION = 'top';
 function getOverlayGlobal() {
-    return globalThis;
+    return getGlobalScope();
+}
+/**
+ * Resolve the configured live-overlay position.
+ *
+ * Reads `globalThis.__NS_HMR_OVERLAY_POSITION__` so a project can
+ * override the default at boot time (e.g. inside `app.ts` before the
+ * Vite session bootstraps). Falls back to 'top' which gives the
+ * toast-style chip with a slide-in animation and safe-area padding.
+ */
+export function getHmrDevOverlayPosition() {
+    const g = getOverlayGlobal();
+    const stored = g.__NS_HMR_OVERLAY_POSITION__;
+    if (stored === 'top' || stored === 'bottom' || stored === 'center') {
+        return stored;
+    }
+    return DEFAULT_OVERLAY_POSITION;
+}
+/**
+ * Imperative setter for the live-overlay position. Re-applies the
+ * current snapshot so the change is visible without waiting for the
+ * next HMR cycle. Useful during dev to A/B between top/bottom/center
+ * without restarting the app.
+ */
+export function setHmrDevOverlayPosition(position) {
+    if (position !== 'top' && position !== 'bottom' && position !== 'center') {
+        return;
+    }
+    const g = getOverlayGlobal();
+    g.__NS_HMR_OVERLAY_POSITION__ = position;
+    const state = getRuntimeState();
+    applyRuntimeSnapshot(state.snapshot);
 }
 function getRuntimeState() {
     const g = getOverlayGlobal();
@@ -41,319 +65,6 @@ function getRuntimeState() {
         state.updateCycleStartedAt = 0;
     return state;
 }
-function describeAttempt(info) {
-    const attempt = Number(info?.attempt || 0);
-    const attempts = Number(info?.attempts || 0);
-    if (!attempt || !attempts) {
-        return '';
-    }
-    return `Attempt ${attempt}/${attempts}`;
-}
-export function createBootOverlaySnapshot(stage, info) {
-    const attemptText = describeAttempt(info);
-    const phaseInfo = {
-        placeholder: {
-            visible: true,
-            mode: 'boot',
-            badge: 'BOOT',
-            title: BOOT_TITLE,
-            phase: 'Preparing the HTTP HMR bootstrap',
-            progress: 4,
-            busy: true,
-            blocking: true,
-            tone: 'info',
-        },
-        'probing-origin': {
-            visible: true,
-            mode: 'boot',
-            badge: 'BOOT',
-            title: BOOT_TITLE,
-            phase: 'Contacting the Vite dev server',
-            progress: 8,
-            busy: true,
-            blocking: true,
-            tone: 'info',
-        },
-        'loading-entry-runtime': {
-            visible: true,
-            mode: 'boot',
-            badge: 'BOOT',
-            title: BOOT_TITLE,
-            phase: 'Loading the entry runtime bridge',
-            progress: 16,
-            busy: true,
-            blocking: true,
-            tone: 'info',
-        },
-        'configuring-import-map': {
-            visible: true,
-            mode: 'boot',
-            badge: 'BOOT',
-            title: BOOT_TITLE,
-            phase: 'Configuring the import map',
-            progress: 26,
-            busy: true,
-            blocking: true,
-            tone: 'info',
-        },
-        'loading-runtime-bridge': {
-            visible: true,
-            mode: 'boot',
-            badge: 'BOOT',
-            title: BOOT_TITLE,
-            phase: 'Loading the NativeScript runtime bridge',
-            progress: 40,
-            busy: true,
-            blocking: true,
-            tone: 'info',
-        },
-        'loading-core-bridge': {
-            visible: true,
-            mode: 'boot',
-            badge: 'BOOT',
-            title: BOOT_TITLE,
-            phase: 'Loading the unified core bridge',
-            progress: 54,
-            busy: true,
-            blocking: true,
-            tone: 'info',
-        },
-        'preloading-style-scope': {
-            visible: true,
-            mode: 'boot',
-            badge: 'BOOT',
-            title: BOOT_TITLE,
-            phase: 'Preparing the shared style scope',
-            progress: 62,
-            busy: true,
-            blocking: true,
-            tone: 'info',
-        },
-        'installing-css': {
-            visible: true,
-            mode: 'boot',
-            badge: 'BOOT',
-            title: BOOT_TITLE,
-            phase: 'Applying the app stylesheet',
-            progress: 70,
-            busy: true,
-            blocking: true,
-            tone: 'info',
-        },
-        'importing-main': {
-            visible: true,
-            mode: 'boot',
-            badge: 'BOOT',
-            title: BOOT_TITLE,
-            phase: 'Importing the app entry',
-            progress: 82,
-            busy: true,
-            blocking: true,
-            tone: 'info',
-        },
-        'waiting-for-app': {
-            visible: true,
-            mode: 'boot',
-            badge: 'BOOT',
-            title: BOOT_TITLE,
-            phase: 'Waiting for the app root view',
-            progress: 94,
-            busy: true,
-            blocking: true,
-            tone: 'info',
-        },
-        'app-root-committed': {
-            visible: true,
-            mode: 'boot',
-            badge: 'READY',
-            title: BOOT_TITLE,
-            phase: 'Real app root committed',
-            progress: 100,
-            busy: false,
-            blocking: true,
-            tone: 'info',
-        },
-        ready: {
-            visible: true,
-            mode: 'boot',
-            badge: 'READY',
-            title: BOOT_TITLE,
-            phase: 'Boot complete',
-            progress: 100,
-            busy: false,
-            blocking: true,
-            tone: 'info',
-        },
-        error: {
-            visible: true,
-            mode: 'boot',
-            badge: 'RETRY',
-            title: BOOT_TITLE,
-            phase: 'Retrying after a boot failure',
-            progress: null,
-            busy: true,
-            blocking: true,
-            tone: 'error',
-        },
-    };
-    const base = phaseInfo[stage];
-    let detail = info?.detail || '';
-    if (!detail && stage === 'probing-origin' && info?.origin) {
-        detail = `Trying ${info.origin}`;
-    }
-    if (attemptText) {
-        detail = detail ? `${detail}  ${attemptText}` : attemptText;
-    }
-    return {
-        ...base,
-        detail,
-        progress: typeof info?.progress === 'number' || info?.progress === null ? info.progress : base.progress,
-    };
-}
-export function createConnectionOverlaySnapshot(stage, info) {
-    if (stage === 'healthy') {
-        return { ...DEFAULT_SNAPSHOT };
-    }
-    const phaseInfo = {
-        connecting: {
-            visible: true,
-            mode: 'connection',
-            badge: 'SOCKET',
-            title: 'Waiting for Vite dev server',
-            phase: 'Opening websocket connection',
-            detail: 'Live updates are paused until the connection is healthy.',
-            progress: null,
-            busy: true,
-            blocking: false,
-            tone: 'warn',
-        },
-        reconnecting: {
-            visible: true,
-            mode: 'connection',
-            badge: 'SOCKET',
-            title: 'HMR connection lost',
-            phase: 'Reconnecting Vite websocket',
-            detail: 'The app may be stale until the dev server reconnects.',
-            progress: null,
-            busy: true,
-            blocking: false,
-            tone: 'warn',
-        },
-        synchronizing: {
-            visible: true,
-            mode: 'connection',
-            badge: 'SYNC',
-            title: 'HMR connection restored',
-            phase: 'Synchronizing live-update state',
-            detail: 'Finalizing the module graph before dismissing the overlay.',
-            progress: 95,
-            busy: true,
-            blocking: false,
-            tone: 'info',
-        },
-        offline: {
-            visible: true,
-            mode: 'connection',
-            badge: 'OFFLINE',
-            title: 'Vite dev server offline',
-            phase: 'Please check your terminal.',
-            detail: 'The websocket and HTTP HMR path are both unavailable right now.',
-            progress: null,
-            busy: true,
-            blocking: false,
-            tone: 'error',
-        },
-    };
-    const base = phaseInfo[stage];
-    return {
-        ...base,
-        detail: info?.detail || base.detail,
-        progress: typeof info?.progress === 'number' || info?.progress === null ? info.progress : base.progress,
-    };
-}
-// Round-eleven.3 (alpha.62) — Snapshot factory for the HMR-applying
-// overlay. Each stage owns a fixed phase string, badge, and progress
-// %. We pick the percentages so users see continuous forward motion:
-// the cheap stages (mutex acquire, eviction call) advance fast; the
-// long tail (entry re-import + Angular reboot) sits at 60→90 so the
-// bar keeps moving even when the V8 ESM walk dominates wall time.
-//
-// The 'complete' stage holds for a brief moment (the API auto-hides
-// it via setUpdateStage) so the user gets visual closure ("the update
-// landed") without staring at a frozen overlay; tone stays 'success'
-// throughout so the colour scheme never flickers between phases.
-const HMR_UPDATE_TITLE = 'HMR update applying...';
-const HMR_UPDATE_DONE_TITLE = 'HMR update applied';
-export function createUpdateOverlaySnapshot(stage, info) {
-    const phaseInfo = {
-        received: {
-            visible: true,
-            mode: 'update',
-            badge: 'HMR',
-            title: HMR_UPDATE_TITLE,
-            phase: 'Preparing update',
-            detail: '',
-            progress: 5,
-            busy: true,
-            blocking: false,
-            tone: 'success',
-        },
-        evicting: {
-            visible: true,
-            mode: 'update',
-            badge: 'HMR',
-            title: HMR_UPDATE_TITLE,
-            phase: 'Invalidating module cache',
-            detail: '',
-            progress: 30,
-            busy: true,
-            blocking: false,
-            tone: 'success',
-        },
-        reimporting: {
-            visible: true,
-            mode: 'update',
-            badge: 'HMR',
-            title: HMR_UPDATE_TITLE,
-            phase: 'Re-importing entry',
-            detail: '',
-            progress: 60,
-            busy: true,
-            blocking: false,
-            tone: 'success',
-        },
-        rebooting: {
-            visible: true,
-            mode: 'update',
-            badge: 'HMR',
-            title: HMR_UPDATE_TITLE,
-            phase: 'Rebooting Angular',
-            detail: '',
-            progress: 90,
-            busy: true,
-            blocking: false,
-            tone: 'success',
-        },
-        complete: {
-            visible: true,
-            mode: 'update',
-            badge: 'HMR',
-            title: HMR_UPDATE_DONE_TITLE,
-            phase: 'Update applied',
-            detail: '',
-            progress: 100,
-            busy: false,
-            blocking: false,
-            tone: 'success',
-        },
-    };
-    const base = phaseInfo[stage];
-    return {
-        ...base,
-        detail: info?.detail || base.detail,
-        progress: typeof info?.progress === 'number' || info?.progress === null ? info.progress : base.progress,
-    };
-}
 function resolveCoreExport(name) {
     const g = getOverlayGlobal();
     try {
@@ -533,10 +244,28 @@ function findBootStatusLabel() {
     catch { }
     return null;
 }
+function findBootDetailLabel() {
+    const g = getOverlayGlobal();
+    return g.__NS_DEV_BOOT_DETAIL_LABEL__ || null;
+}
+function findBootProgressFill() {
+    const g = getOverlayGlobal();
+    return g.__NS_DEV_BOOT_PROGRESS_FILL__ || null;
+}
 function updateBootStatusLabel(snapshot) {
-    const newText = formatStatusText(snapshot) || 'Preparing the HTTP HMR bootstrap (4%)';
     const statusLabel = findBootStatusLabel();
+    const detailLabel = findBootDetailLabel();
+    const progressFill = findBootProgressFill();
     const activityIndicator = findBootActivityIndicator();
+    // New (card) layout: phase line + detail line live in separate
+    // labels so the typography can differ. Legacy (single-label)
+    // layout: keep the original combined "phase (X%)\ndetail" text so
+    // nothing visually regresses for runtimes still attached to the
+    // older placeholder shape.
+    const hasSplitLabels = !!detailLabel;
+    const phaseLine = formatBootPrimaryLine(snapshot);
+    const detailLine = formatBootDetailLine(snapshot);
+    const combinedText = formatStatusText(snapshot) || 'Preparing the HTTP HMR bootstrap (4%)';
     if (!statusLabel) {
         if (activityIndicator) {
             try {
@@ -545,11 +274,16 @@ function updateBootStatusLabel(snapshot) {
             }
             catch { }
         }
+        applyBootProgressFill(progressFill, snapshot);
         return;
     }
     try {
-        statusLabel.text = newText;
-        statusLabel.color = asColor(snapshot.tone === 'error' ? '#b41810e6' : '#563e3fb1');
+        statusLabel.text = hasSplitLabels ? phaseLine || 'Preparing the HTTP HMR bootstrap' : combinedText;
+        // Card layout uses the calibrated phase-text colour from the
+        // palette; legacy single-label layout keeps the original muted
+        // brown so we don't visually regress mid-session.
+        const phaseColorHex = snapshot.tone === 'error' ? '#B91C1C' : hasSplitLabels ? '#475569' : '#563e3fb1';
+        statusLabel.color = asColor(phaseColorHex);
         if (typeof statusLabel.requestLayout === 'function') {
             statusLabel.requestLayout();
         }
@@ -559,6 +293,15 @@ function updateBootStatusLabel(snapshot) {
         }
     }
     catch { }
+    if (detailLabel) {
+        try {
+            detailLabel.text = detailLine;
+            detailLabel.color = asColor(snapshot.tone === 'error' ? '#DC2626' : '#94A3B8');
+            detailLabel.visibility = detailLine ? 'visible' : 'collapse';
+        }
+        catch { }
+    }
+    applyBootProgressFill(progressFill, snapshot);
     if (activityIndicator) {
         try {
             activityIndicator.busy = !!snapshot.busy;
@@ -567,6 +310,50 @@ function updateBootStatusLabel(snapshot) {
         catch { }
     }
 }
+// Drive the progress fill scaleX from the snapshot. Uses NS's view
+// animate API for a smooth 220 ms easeOut between heartbeat ticks; a
+// monotonic ratchet on `globalThis.__NS_DEV_BOOT_PROGRESS_LAST_SCALE__`
+// guards against the fill snapping backwards if a less-progressed
+// snapshot ever lands between ticks (mirrors the JS-side
+// `applyMonotonicBootProgress` contract).
+function applyBootProgressFill(progressFill, snapshot) {
+    if (!progressFill)
+        return;
+    const g = getOverlayGlobal();
+    const isError = snapshot.tone === 'error';
+    progressFill.backgroundColor = asColor(isError ? '#B41810' : '#3B6FE5');
+    const targetScale = computeBootProgressFillScale(snapshot.progress ?? null);
+    const previousRaw = Number(g.__NS_DEV_BOOT_PROGRESS_LAST_SCALE__);
+    const previous = Number.isFinite(previousRaw) ? previousRaw : 0;
+    const next = Math.max(previous, targetScale);
+    g.__NS_DEV_BOOT_PROGRESS_LAST_SCALE__ = next;
+    try {
+        // NS view.animate scales around `originX`/`originY`; the
+        // placeholder builder pins `originX = 0` so the fill grows
+        // rightward. animate() may be unavailable in some headless
+        // test environments — fall through to a direct property set.
+        if (typeof progressFill.animate === 'function') {
+            progressFill
+                .animate({
+                scale: { x: next, y: 1 },
+                duration: BOOT_PLACEHOLDER_MOTION.progressDurationMs,
+                curve: 'easeOut',
+            })
+                .catch(() => {
+                try {
+                    progressFill.scaleX = next;
+                }
+                catch { }
+            });
+        }
+        else {
+            progressFill.scaleX = next;
+        }
+    }
+    catch {
+        progressFill.scaleX = next;
+    }
+}
 function resolveActivePage() {
     try {
         const Frame = resolveCoreExport('Frame');
@@ -590,6 +377,87 @@ function resolveActivePage() {
     catch { }
     return null;
 }
+function readCachedAndroidSafeAreaInsets() {
+    const g = getOverlayGlobal();
+    const cached = g.__NS_HMR_ANDROID_SAFE_INSETS__;
+    if (cached && typeof cached.top === 'number') {
+        return cached;
+    }
+    return null;
+}
+/**
+ * Read the Android system-bar safe-area insets (status bar / navigation
+ * bar / display cutout) in device-independent pixels.
+ *
+ * NativeScript runs every Android activity edge-to-edge, so the overlay
+ * wrapper fills the whole window — we need these insets to keep the toast
+ * chip out from under the system bars (see `computeAndroidToastMargin`).
+ *
+ * Returns null on non-Android runtimes (iOS / web / vitest) so callers
+ * fall back to base margins. The last good reading is cached on the
+ * global so a transient null (e.g. insets queried before the decor view
+ * is attached) reuses the previous value instead of snapping the chip
+ * back under the status bar.
+ */
+function readAndroidSafeAreaInsets() {
+    const g = getOverlayGlobal();
+    // `android.*` is exposed as a global only on the NativeScript Android
+    // runtime; its absence means iOS, web, or a test environment.
+    const androidNs = g.android || (typeof globalThis.android !== 'undefined' ? globalThis.android : undefined);
+    if (!androidNs) {
+        return null;
+    }
+    try {
+        const Application = resolveCoreExport('Application');
+        const activity = Application?.android?.foregroundActivity || Application?.android?.startActivity;
+        const decorView = activity?.getWindow?.()?.getDecorView?.();
+        const rootInsets = decorView?.getRootWindowInsets?.();
+        if (!rootInsets) {
+            return readCachedAndroidSafeAreaInsets();
+        }
+        let density = 1;
+        try {
+            const metricsDensity = Number(activity?.getResources?.()?.getDisplayMetrics?.()?.density);
+            if (Number.isFinite(metricsDensity) && metricsDensity > 0) {
+                density = metricsDensity;
+            }
+        }
+        catch { }
+        let px = { top: 0, bottom: 0, left: 0, right: 0 };
+        const WindowInsets = androidNs.view?.WindowInsets;
+        const Type = WindowInsets?.Type;
+        if (typeof rootInsets.getInsets === 'function' && Type && typeof Type.systemBars === 'function') {
+            // API 30+: query the system bars + display cutout so notches /
+            // camera holes are respected in landscape.
+            let mask = Type.systemBars();
+            if (typeof Type.displayCutout === 'function') {
+                mask = mask | Type.displayCutout();
+            }
+            const i = rootInsets.getInsets(mask);
+            px = { top: Number(i?.top) || 0, bottom: Number(i?.bottom) || 0, left: Number(i?.left) || 0, right: Number(i?.right) || 0 };
+        }
+        else {
+            // API < 30 fallback.
+            px = {
+                top: Number(rootInsets.getSystemWindowInsetTop?.()) || 0,
+                bottom: Number(rootInsets.getSystemWindowInsetBottom?.()) || 0,
+                left: Number(rootInsets.getSystemWindowInsetLeft?.()) || 0,
+                right: Number(rootInsets.getSystemWindowInsetRight?.()) || 0,
+            };
+        }
+        const insets = {
+            top: px.top / density,
+            bottom: px.bottom / density,
+            left: px.left / density,
+            right: px.right / density,
+        };
+        g.__NS_HMR_ANDROID_SAFE_INSETS__ = insets;
+        return insets;
+    }
+    catch {
+        return readCachedAndroidSafeAreaInsets();
+    }
+}
 function buildLiveOverlayView(snapshot) {
     const GridLayout = resolveCoreExport('GridLayout');
     const StackLayout = resolveCoreExport('StackLayout');
@@ -603,8 +471,18 @@ function buildLiveOverlayView(snapshot) {
     overlay.height = '100%';
     overlay.horizontalAlignment = 'stretch';
     overlay.verticalAlignment = 'stretch';
+    // Toast mode lets touches reach the underlying app. We flip
+    // isUserInteractionEnabled in applySnapshotToLiveRefs based on
+    // the resolved position, but keep it false here as a safe default
+    // (the panel itself is purely informational).
+    try {
+        overlay.isUserInteractionEnabled = false;
+    }
+    catch { }
     const panel = new StackLayout();
     panel.horizontalAlignment = 'center';
+    // Vertical alignment is overridden in applySnapshotToLiveRefs
+    // based on getHmrDevOverlayPosition(); 'middle' is the default
     panel.verticalAlignment = 'middle';
     panel.width = 320;
     panel.margin = 24;
@@ -626,6 +504,8 @@ function buildLiveOverlayView(snapshot) {
         overlay,
         titleLabel,
         statusLabel,
+        wasVisible: false,
+        currentPosition: getHmrDevOverlayPosition(),
     };
     applySnapshotToLiveRefs(refs, snapshot);
     return refs;
@@ -682,33 +562,43 @@ function applySnapshotToLiveRefs(refs, snapshot) {
     if (!refs) {
         return;
     }
-    // Round-eleven.3 — 'update' mode shares the live (in-tree) overlay
-    // chrome with 'connection'. Both render a centered panel inside the
-    // page; only the colours and text change with the snapshot's tone.
+    // 'update' mode shares the live (in-tree) overlay chrome with
+    // 'connection'. Both render a small panel inside the page; only
+    // the colours, text, and (now) panel position change with the
+    // snapshot's tone and the configured overlay position.
     const visible = snapshot.visible && (snapshot.mode === 'connection' || snapshot.mode === 'update');
-    refs.overlay.visibility = visible ? 'visible' : 'collapse';
-    // Backdrop tints by tone:
-    //   error   → red wash (matches existing UX)
-    //   success → richer green wash; the previous 18% alpha was so
-    //             subtle on light app backgrounds that users couldn't
-    //             tell the overlay had even fired. 50% alpha keeps the
-    //             underlying app legible while making the apply event
-    //             unmistakable during the (often <300ms) cycle.
-    //   default → warm orange (existing connection-overlay look)
-    const overlayBg = snapshot.tone === 'error' ? '#b4181068' : snapshot.tone === 'success' ? '#1f883d80' : '#a1771683';
-    refs.overlay.backgroundColor = asColor(overlayBg);
+    const wasVisible = !!refs.wasVisible;
+    const position = getHmrDevOverlayPosition();
+    const previousPosition = refs.currentPosition || position;
+    const isToast = position !== 'center';
     refs.titleLabel.text = snapshot.title;
+    refs.statusLabel.text = formatStatusText(snapshot);
     const textColor = snapshot.tone === 'error' ? '#b41810e6' : snapshot.tone === 'success' ? '#0e6e2fff' : '#563e3fb1';
     refs.titleLabel.color = asColor(textColor);
-    refs.statusLabel.text = formatStatusText(snapshot);
     refs.statusLabel.color = asColor(textColor);
+    // Backdrop tints (centered modal only). Toast modes use a fully
+    // transparent backdrop so the rest of the app stays visible AND
+    // reachable; the panel itself carries enough colour to stand out.
+    if (isToast) {
+        refs.overlay.backgroundColor = asColor('transparent');
+    }
+    else {
+        // Original wash-by-tone for centered:
+        //   error   → red wash (matches existing UX)
+        //   success → richer green wash so the apply event is visible
+        //             on bright app backgrounds
+        //   default → warm orange (existing connection-overlay look)
+        const overlayBg = snapshot.tone === 'error' ? '#b4181068' : snapshot.tone === 'success' ? '#1f883d80' : '#a1771683';
+        refs.overlay.backgroundColor = asColor(overlayBg);
+    }
+    // Panel chrome — toast and centered share the same chip look,
+    // just position differs. We keep the slightly richer green tint
+    // for the HMR success state so it pops without needing the
+    // backdrop wash.
+    let panel = null;
     try {
-        const panel = refs.titleLabel.parent;
+        panel = refs.titleLabel.parent;
         if (panel) {
-            // Slightly richer green-tinted panel for HMR-apply so the
-            // title/status text reads at a glance against the brighter
-            // backdrop wash. White panel for connection/error keeps
-            // existing UX intact.
             const panelBg = snapshot.tone === 'success' ? '#E6F8E9FF' : '#FFFFFFFF';
             panel.backgroundColor = asColor(panelBg);
             panel.opacity = 1;
@@ -717,9 +607,169 @@ function applySnapshotToLiveRefs(refs, snapshot) {
                 panel.borderRadius = 12;
             }
             catch { }
+            // Position-aware alignment. The wrapper GridLayout fills the
+            // page content area. NativeScript runs every Android activity
+            // edge-to-edge, so that area extends under the status bar and
+            // navigation bar — we fold the system-bar safe-area insets into
+            // the chip's margin (via computeAndroidToastMargin) so a top
+            // chip clears the status bar and a bottom chip clears the nav
+            // bar instead of being clipped behind them. readAndroidSafeAreaInsets
+            // returns null off-Android, so the margins collapse to their base
+            // values (no behavioural change on iOS's in-tree fallback / tests).
+            try {
+                if (position === 'top' || position === 'bottom') {
+                    const m = computeAndroidToastMargin({ position, safeInsets: readAndroidSafeAreaInsets() });
+                    panel.verticalAlignment = position;
+                    panel.margin = `${m.top} ${m.right} ${m.bottom} ${m.left}`;
+                }
+                else {
+                    panel.verticalAlignment = 'middle';
+                    panel.margin = 24;
+                }
+            }
+            catch { }
+            // Force a tight re-measure so the StackLayout panel hugs the
+            // CURRENT title+status text. Connection stages can swap between
+            // frames whose text wraps to a different number of lines (e.g. a
+            // long 'reconnecting' "Retrying ws://…" detail vs. the short
+            // 'offline' message). Without an explicit relayout the panel can
+            // retain the tallest height it ever measured, leaving an oversized
+            // gap between title and message. Mirrors updateBootStatusLabel.
+            try {
+                refs.titleLabel.requestLayout?.();
+                refs.statusLabel.requestLayout?.();
+                panel.requestLayout?.();
+            }
+            catch { }
         }
     }
     catch { }
+    // Touch passthrough for toast; centered mode keeps the
+    // blocking modal so the dim backdrop is meaningful.
+    try {
+        refs.overlay.isUserInteractionEnabled = !isToast;
+    }
+    catch { }
+    const positionChanged = previousPosition !== position;
+    const justAppeared = visible && (!wasVisible || positionChanged);
+    const justDismissed = !visible && wasVisible;
+    if (justAppeared) {
+        refs.overlay.visibility = 'visible';
+        if (isToast && panel && typeof panel.animate === 'function') {
+            animateLivePanelIn(panel, position);
+        }
+        else if (panel) {
+            try {
+                panel.translateY = 0;
+                panel.opacity = 1;
+            }
+            catch { }
+        }
+    }
+    else if (justDismissed) {
+        if (isToast && panel && typeof panel.animate === 'function') {
+            animateLivePanelOut(panel, previousPosition, () => {
+                try {
+                    refs.overlay.visibility = 'collapse';
+                }
+                catch { }
+            });
+        }
+        else {
+            refs.overlay.visibility = 'collapse';
+        }
+    }
+    else {
+        // Steady-state refresh (e.g. offline → reconnecting → offline while
+        // already visible): no slide animation fires here, so clear any
+        // transform residue a previously-interrupted slide-in/out may have
+        // left on the panel. Otherwise the chip can appear shifted or
+        // faded across rapid connection-stage swaps.
+        if (visible && panel) {
+            try {
+                panel.translateY = 0;
+                panel.opacity = 1;
+            }
+            catch { }
+        }
+        refs.overlay.visibility = visible ? 'visible' : 'collapse';
+    }
+    if (typeof refs.wasVisible !== 'undefined')
+        refs.wasVisible = visible;
+    if (typeof refs.currentPosition !== 'undefined')
+        refs.currentPosition = position;
+}
+/**
+ * Slide-in animation for the in-tree toast panel.
+ *
+ * NativeScript's `View.animate({ translate, opacity, duration, curve })`
+ * is widely available across Core versions, so we don't depend on any
+ * specific curve enum being importable here. We use a moderate-to-snappy
+ * 320ms ease-out which feels close to a UIView spring without needing
+ * platform-specific APIs.
+ */
+function animateLivePanelIn(panel, position) {
+    if (!panel || typeof panel.animate !== 'function')
+        return;
+    try {
+        const startY = position === 'bottom' ? 80 : -80;
+        panel.translateY = startY;
+        panel.opacity = 0;
+        const result = panel.animate({
+            translate: { x: 0, y: 0 },
+            opacity: 1,
+            duration: 320,
+            curve: 'easeOut',
+        });
+        if (result && typeof result.catch === 'function') {
+            result.catch(() => {
+                try {
+                    panel.translateY = 0;
+                    panel.opacity = 1;
+                }
+                catch { }
+            });
+        }
+    }
+    catch {
+        try {
+            panel.translateY = 0;
+            panel.opacity = 1;
+        }
+        catch { }
+    }
+}
+function animateLivePanelOut(panel, position, onComplete) {
+    if (!panel || typeof panel.animate !== 'function') {
+        onComplete();
+        return;
+    }
+    try {
+        const targetY = position === 'bottom' ? 80 : -80;
+        const result = panel.animate({
+            translate: { x: 0, y: targetY },
+            opacity: 0,
+            duration: 220,
+            curve: 'easeIn',
+        });
+        const finish = () => {
+            try {
+                panel.translateY = 0;
+                panel.opacity = 1;
+            }
+            catch { }
+            onComplete();
+        };
+        if (result && typeof result.then === 'function') {
+            result.then(finish, finish);
+        }
+        else {
+            finish();
+        }
+    }
+    catch {
+        onComplete();
+    }
 }
 // pure helpers for iOS window promotion. Factored out so the layout
 // math and window-level selection stay unit-testable without booting a
@@ -739,8 +789,17 @@ export function computeIosOverlayWindowLevel(baseAlert) {
 /**
  * Layout math for the live overlay when it runs inside its own UIWindow.
  * Pure, deterministic and independent of UIKit so we can verify the rules
- * (max panel width, centered placement, safe-area clamping, sane defaults)
- * from tests.
+ * (max panel width, position-aware placement, safe-area clamping, sane
+ * defaults) from tests.
+ *
+ * `position` controls where the panel sits vertically:
+ *   - 'top':    hugs `safeInsets.top + toastVerticalInset` so the chip
+ *               sits just below the notch / Dynamic Island.
+ *   - 'bottom': hugs `viewHeight - safeInsets.bottom - panelHeight -
+ *               toastVerticalInset` so the chip sits just above the
+ *               home indicator / nav bar.
+ *   - 'center': original modal placement (vertically centered, clamped
+ *               so it never crosses the top safe-area inset).
  */
 export function computeIosOverlayLayout(input) {
     const viewWidth = Math.max(0, Number(input.viewWidth) || 0);
@@ -758,15 +817,41 @@ export function computeIosOverlayLayout(input) {
     const panelPadding = Math.max(0, Number(input.panelPadding ?? 16));
     const interLabelSpacing = Math.max(0, Number(input.interLabelSpacing ?? 10));
     const minTopInset = Math.max(0, Number(input.minTopInset ?? 20));
+    // Default to 'center' on the pure function so the existing
+    // snapshot/layout tests remain stable; the runtime call site
+    // (layoutIosOverlayRefs) reads the configured position from
+    // `getHmrDevOverlayPosition()` and forwards it explicitly.
+    const position = input.position ?? 'center';
+    // Distance between the panel and the safe-area edge in toast
+    // modes. 8pt mirrors the typical iOS notification chip inset and
+    // keeps the chip from hugging the notch / home indicator.
+    const toastVerticalInset = Math.max(0, Number(input.toastVerticalInset ?? 8));
     const available = Math.max(0, viewWidth - 2 * horizontalMargin - safeInsets.left - safeInsets.right);
     const panelWidth = Math.min(maxPanelWidth, available);
     const innerWidth = Math.max(0, panelWidth - 2 * panelPadding);
     const spacing = titleHeight > 0 && statusHeight > 0 ? interLabelSpacing : 0;
     const panelHeight = panelPadding * 2 + titleHeight + spacing + statusHeight;
     const panelX = Math.max(0, (viewWidth - panelWidth) / 2);
-    // Center vertically, but never cross the top safe-area inset (notch/Dynamic Island).
-    const centered = (viewHeight - panelHeight) / 2;
-    const panelY = Math.max(safeInsets.top + minTopInset, centered);
+    let panelY;
+    if (position === 'top') {
+        // Pin to the top safe-area inset (just below notch / Dynamic
+        // Island). Clamp non-negative for fully-NaN input.
+        panelY = Math.max(0, safeInsets.top + toastVerticalInset);
+    }
+    else if (position === 'bottom') {
+        // Pin to the bottom safe-area inset (just above home indicator
+        // / nav bar). If the panel can't fit between the safe-area
+        // insets we fall back to the top safe-area edge so the chip is
+        // always visible (rather than getting clipped off-screen).
+        const desired = viewHeight - safeInsets.bottom - panelHeight - toastVerticalInset;
+        panelY = Math.max(safeInsets.top + minTopInset, desired);
+    }
+    else {
+        // Center vertically, but never cross the top safe-area inset
+        // (notch/Dynamic Island). Original modal placement.
+        const centered = (viewHeight - panelHeight) / 2;
+        panelY = Math.max(safeInsets.top + minTopInset, centered);
+    }
     return {
         backdrop: { x: 0, y: 0, width: viewWidth, height: viewHeight },
         panel: { x: panelX, y: panelY, width: panelWidth, height: panelHeight },
@@ -779,6 +864,59 @@ export function computeIosOverlayLayout(input) {
         },
     };
 }
+/**
+ * Margin math for the in-tree (Android) live/update toast chip.
+ *
+ * NativeScript enables edge-to-edge on every Android activity
+ * (`@nativescript/core` → `application.android.ts` → `enableEdgeToEdge`),
+ * so the page content — and therefore the overlay wrapper we inject into
+ * it — extends underneath the status bar and navigation bar. A fixed
+ * top/bottom margin leaves the chip tucked behind the system bars, where
+ * it gets clipped (Android 15 / API 35 enforces edge-to-edge, so this is
+ * now the norm rather than the exception).
+ *
+ * This pure helper folds the system-bar safe-area insets into the chip's
+ * margin so the toast always clears the status bar (top position) /
+ * navigation bar (bottom position). It is deterministic and free of
+ * native deps so the rules stay unit-testable — the runtime reads the
+ * live insets via `readAndroidSafeAreaInsets()` and forwards them here.
+ *
+ *   - 'top':    margin.top    = baseVerticalInset + safeInsets.top
+ *   - 'bottom': margin.bottom = baseVerticalInset + safeInsets.bottom
+ *   - 'center': fixed `centerMargin` all around (vertically centered, so
+ *               it never approaches the system bars on normal viewports).
+ *
+ * Horizontal margins always include the relevant safe-area inset so a
+ * landscape display cutout / gesture pill doesn't clip the chip edge.
+ */
+export function computeAndroidToastMargin(input) {
+    // Clamp to a finite, non-negative number; fall back to `fallback`
+    // for missing/NaN input so a glitched measurement can't produce a
+    // negative or NaN margin (which NativeScript would silently drop).
+    const clamp = (value, fallback) => {
+        const n = Number(value);
+        return Number.isFinite(n) && n >= 0 ? n : fallback;
+    };
+    const safe = {
+        top: clamp(input.safeInsets?.top, 0),
+        bottom: clamp(input.safeInsets?.bottom, 0),
+        left: clamp(input.safeInsets?.left, 0),
+        right: clamp(input.safeInsets?.right, 0),
+    };
+    const baseVerticalInset = clamp(input.baseVerticalInset, 8);
+    const baseHorizontalInset = clamp(input.baseHorizontalInset, 16);
+    const centerMargin = clamp(input.centerMargin, 24);
+    if (input.position === 'center') {
+        return { top: centerMargin, right: centerMargin, bottom: centerMargin, left: centerMargin };
+    }
+    const left = Math.round(baseHorizontalInset + safe.left);
+    const right = Math.round(baseHorizontalInset + safe.right);
+    if (input.position === 'bottom') {
+        return { top: 0, right, bottom: Math.round(baseVerticalInset + safe.bottom), left };
+    }
+    // 'top' (and any unexpected value) hugs the status-bar safe area.
+    return { top: Math.round(baseVerticalInset + safe.top), right, bottom: 0, left };
+}
 /**
  * Returns the iOS UIKit symbols we rely on if we're running on an iOS runtime
  * with the metadata bridge available. Returns null on Android, web, or in
@@ -833,10 +971,7 @@ function buildIosOverlayRefs(state) {
     const scene = findActiveWindowScene(host);
     if (!scene) {
         if (state.verbose) {
-            try {
-                console.info('[ns-hmr-overlay] no active UIWindowScene; skipping iOS overlay promotion');
-            }
-            catch { }
+            console.info('[ns-hmr-overlay] no active UIWindowScene; skipping iOS overlay promotion');
         }
         return null;
     }
@@ -883,13 +1018,35 @@ function buildIosOverlayRefs(state) {
         statusLabel.font = UIFont.systemFontOfSize(13);
         statusLabel.textColor = UIColor.darkGrayColor;
         panel.addSubview(statusLabel);
-        return { window, controller, backdrop, panel, titleLabel, statusLabel };
-    }
-    catch (err) {
+        // Subtle drop-shadow so the toast chip reads against light app
+        // content (white-on-white is invisible). The error / centered
+        // branches still get the dim backdrop, so the shadow is mostly
+        // a no-op for them — but it's a one-time setup.
         try {
-            console.warn('[ns-hmr-overlay] iOS overlay construction failed:', err?.message || err);
+            panel.layer.shadowColor = UIColor.blackColor.CGColor;
+            panel.layer.shadowOpacity = 0.18;
+            panel.layer.shadowRadius = 8;
+            panel.layer.shadowOffset = { width: 0, height: 2 };
+            panel.layer.masksToBounds = false;
         }
         catch { }
+        // `wasVisible` / `currentPosition` are mutated by
+        // applySnapshotToIosRefs when the snapshot triggers a slide-in
+        // or slide-out. They start in the "hidden" state so the very
+        // first visible snapshot animates in cleanly.
+        return {
+            window,
+            controller,
+            backdrop,
+            panel,
+            titleLabel,
+            statusLabel,
+            wasVisible: false,
+            currentPosition: getHmrDevOverlayPosition(),
+        };
+    }
+    catch (err) {
+        console.warn('[ns-hmr-overlay] iOS overlay construction failed:', err?.message || err);
         return null;
     }
 }
@@ -909,7 +1066,7 @@ function ensureIosOverlayRefs(state) {
     }
     return state.iosRefs;
 }
-function layoutIosOverlayRefs(refs) {
+function layoutIosOverlayRefs(refs, position) {
     try {
         const bounds = refs.controller.view.bounds;
         const viewWidth = Number(bounds?.size?.width) || 0;
@@ -940,6 +1097,7 @@ function layoutIosOverlayRefs(refs) {
             maxPanelWidth,
             horizontalMargin,
             panelPadding,
+            position,
         });
         const toCgRect = (rect) => ({
             origin: { x: rect.x, y: rect.y },
@@ -949,27 +1107,156 @@ function layoutIosOverlayRefs(refs) {
         refs.panel.frame = toCgRect(layout.panel);
         refs.titleLabel.frame = toCgRect(layout.title);
         refs.statusLabel.frame = toCgRect(layout.status);
+        return layout;
     }
     catch (err) {
+        console.warn('[ns-hmr-overlay] iOS overlay layout failed:', err?.message || err);
+        return null;
+    }
+}
+/**
+ * Slide-in animation for the iOS toast panel. Off-screen start frame
+ * lives just above (top) or below (bottom) the visible area; the panel
+ * snaps to its target frame with a spring so the motion feels physical
+ * without the heavy "settle" overshoot of a hard spring (damping 0.85
+ * lands quickly with a small overshoot).
+ */
+function animateIosPanelIn(refs, position, layout) {
+    const g = getOverlayGlobal();
+    const UIView = g?.UIView;
+    if (!UIView)
+        return;
+    try {
+        const targetFrame = {
+            origin: { x: layout.panel.x, y: layout.panel.y },
+            size: { width: layout.panel.width, height: layout.panel.height },
+        };
+        // Off-screen start: distance includes a small fudge so the
+        // shadow blur tail isn't visible at t=0.
+        const startY = position === 'bottom' ? layout.backdrop.height + 24 : -(layout.panel.height + 24);
+        refs.panel.frame = {
+            origin: { x: layout.panel.x, y: startY },
+            size: { width: layout.panel.width, height: layout.panel.height },
+        };
+        refs.panel.alpha = 0;
+        try {
+            if (typeof UIView.animateWithDurationDelayUsingSpringWithDampingInitialSpringVelocityOptionsAnimationsCompletion === 'function') {
+                UIView.animateWithDurationDelayUsingSpringWithDampingInitialSpringVelocityOptionsAnimationsCompletion(0.42, 0, 0.85, 0.7, 0, () => {
+                    refs.panel.frame = targetFrame;
+                    refs.panel.alpha = 1;
+                }, null);
+            }
+            else if (typeof UIView.animateWithDurationAnimations === 'function') {
+                UIView.animateWithDurationAnimations(0.32, () => {
+                    refs.panel.frame = targetFrame;
+                    refs.panel.alpha = 1;
+                });
+            }
+            else {
+                refs.panel.frame = targetFrame;
+                refs.panel.alpha = 1;
+            }
+        }
+        catch {
+            refs.panel.frame = targetFrame;
+            refs.panel.alpha = 1;
+        }
+    }
+    catch { }
+}
+/**
+ * Slide-out animation for the iOS toast panel. Mirrors animateIosPanelIn:
+ * the panel travels to the nearest off-screen edge while fading out so
+ * the dismissal still feels intentional even on fast HMR cycles.
+ */
+function animateIosPanelOut(refs, position, onComplete) {
+    const g = getOverlayGlobal();
+    const UIView = g?.UIView;
+    const currentFrame = refs.panel?.frame;
+    if (!UIView || !currentFrame) {
+        onComplete();
+        return;
+    }
+    try {
+        const bounds = refs.controller?.view?.bounds;
+        const viewHeight = Number(bounds?.size?.height) || 0;
+        const targetY = position === 'bottom' ? viewHeight + 24 : -(Number(currentFrame.size?.height) + 24);
+        const startFrame = currentFrame;
+        const targetFrame = {
+            origin: { x: Number(startFrame.origin?.x) || 0, y: targetY },
+            size: startFrame.size,
+        };
         try {
-            console.warn('[ns-hmr-overlay] iOS overlay layout failed:', err?.message || err);
+            if (typeof UIView.animateWithDurationDelayOptionsAnimationsCompletion === 'function') {
+                // UIViewAnimationOptionCurveEaseIn = 1 << 16 — accelerate
+                // out so the dismissal doesn't drag on screen.
+                UIView.animateWithDurationDelayOptionsAnimationsCompletion(0.22, 0, 1 << 16, () => {
+                    refs.panel.frame = targetFrame;
+                    refs.panel.alpha = 0;
+                }, () => onComplete());
+            }
+            else if (typeof UIView.animateWithDurationAnimationsCompletion === 'function') {
+                UIView.animateWithDurationAnimationsCompletion(0.22, () => {
+                    refs.panel.frame = targetFrame;
+                    refs.panel.alpha = 0;
+                }, () => onComplete());
+            }
+            else {
+                refs.panel.alpha = 0;
+                onComplete();
+            }
+        }
+        catch {
+            refs.panel.alpha = 0;
+            onComplete();
         }
-        catch { }
+    }
+    catch {
+        onComplete();
     }
 }
 function applySnapshotToIosRefs(refs, snapshot) {
     if (!refs)
         return false;
     try {
-        // Round-eleven.3 — 'update' mode rides the same dedicated
-        // UIWindow as 'connection' so the HMR apply overlay always
-        // stacks above modals/sheets/system alerts. The window is
-        // constructed lazily (ensureIosOverlayRefs) and reused for the
-        // lifetime of the dev session.
+        // 'update' mode rides the same dedicated UIWindow as
+        // 'connection' so the HMR apply overlay always stacks above
+        // modals/sheets/system alerts. The window is constructed
+        // lazily (ensureIosOverlayRefs) and reused for the lifetime of
+        // the dev session.
         const visible = snapshot.visible && (snapshot.mode === 'connection' || snapshot.mode === 'update');
-        refs.window.hidden = !visible;
-        if (!visible)
+        const wasVisible = !!refs.wasVisible;
+        const position = getHmrDevOverlayPosition();
+        const previousPosition = refs.currentPosition;
+        const isToast = position !== 'center';
+        // Touches pass through the overlay window in toast mode so
+        // the user can keep tapping the app while the HMR chip is
+        // shown. In centered mode we keep the blocking
+        // behaviour (the dim backdrop is itself a hint to wait).
+        try {
+            refs.window.userInteractionEnabled = !isToast;
+        }
+        catch { }
+        if (!visible) {
+            // Animate out before hiding the window so the dismissal
+            // has a discoverable motion. Only animate when previously
+            // visible and in toast mode — centered modal hides instantly.
+            if (wasVisible && isToast) {
+                animateIosPanelOut(refs, previousPosition, () => {
+                    try {
+                        refs.window.hidden = true;
+                    }
+                    catch { }
+                });
+            }
+            else {
+                refs.window.hidden = true;
+            }
+            refs.wasVisible = false;
+            refs.currentPosition = position;
             return true;
+        }
+        refs.window.hidden = false;
         refs.titleLabel.text = snapshot.title || '';
         refs.statusLabel.text = formatStatusText(snapshot);
         const host = getIosOverlayHost();
@@ -983,9 +1270,6 @@ function applySnapshotToIosRefs(refs, snapshot) {
                     refs.panel.backgroundColor = UIColor.colorWithRedGreenBlueAlpha(1, 0.96, 0.96, 1);
                     refs.titleLabel.textColor = UIColor.colorWithRedGreenBlueAlpha(0.7, 0.1, 0.06, 1);
                     refs.statusLabel.textColor = UIColor.colorWithRedGreenBlueAlpha(0.7, 0.1, 0.06, 0.9);
-                    // Slightly stronger dimming on errors; users need to
-                    // notice these.
-                    refs.backdrop.backgroundColor = UIColor.colorWithRedGreenBlueAlpha(0, 0, 0, 0.35);
                 }
                 else if (isSuccess) {
                     // Slightly more saturated green panel + dark-green
@@ -997,31 +1281,56 @@ function applySnapshotToIosRefs(refs, snapshot) {
                     refs.panel.backgroundColor = UIColor.colorWithRedGreenBlueAlpha(0.9, 0.97, 0.91, 1);
                     refs.titleLabel.textColor = UIColor.colorWithRedGreenBlueAlpha(0.05, 0.43, 0.18, 1);
                     refs.statusLabel.textColor = UIColor.colorWithRedGreenBlueAlpha(0.05, 0.43, 0.18, 1);
-                    // Bumped from 0.12 to 0.28. The 0.12 wash was so
-                    // faint on bright app backgrounds that the overlay
-                    // was effectively invisible during a fast cycle.
-                    // 0.28 still keeps the app readable underneath but
-                    // makes the HMR event visually unmistakable.
-                    refs.backdrop.backgroundColor = UIColor.colorWithRedGreenBlueAlpha(0, 0.15, 0.05, 0.28);
                 }
                 else {
                     // Default (info / warn) — existing connection look.
                     refs.panel.backgroundColor = UIColor.whiteColor;
                     refs.titleLabel.textColor = UIColor.blackColor;
                     refs.statusLabel.textColor = UIColor.darkGrayColor;
+                }
+                // Backdrop dims only in centered mode; toast mode keeps
+                // the rest of the app fully visible/usable. Errors get
+                // a slightly stronger dim in centered mode because the
+                // user MUST notice them.
+                if (isToast) {
+                    refs.backdrop.backgroundColor = UIColor.clearColor;
+                }
+                else if (isError) {
                     refs.backdrop.backgroundColor = UIColor.colorWithRedGreenBlueAlpha(0, 0, 0, 0.35);
                 }
+                else if (isSuccess) {
+                    refs.backdrop.backgroundColor = UIColor.colorWithRedGreenBlueAlpha(0, 0.15, 0.05, 0.28);
+                }
+                else {
+                    refs.backdrop.backgroundColor = UIColor.colorWithRedGreenBlueAlpha(0, 0, 0, 0.35);
+                }
+            }
+            catch { }
+        }
+        const layout = layoutIosOverlayRefs(refs, position);
+        // Slide-in animation only fires on the actual hidden→visible
+        // transition (or on a position swap — e.g. dev toggling top
+        // to bottom mid-cycle). Subsequent updates within the same
+        // visible cycle just refresh text/colours without re-animating.
+        const positionChanged = previousPosition !== position;
+        const justAppeared = !wasVisible || positionChanged;
+        if (justAppeared && isToast && layout) {
+            animateIosPanelIn(refs, position, layout);
+        }
+        else if (justAppeared && !isToast) {
+            // Centered modal: ensure alpha is reset to 1 in case a
+            // previous toast-mode dismissal left it at 0.
+            try {
+                refs.panel.alpha = 1;
             }
             catch { }
         }
-        layoutIosOverlayRefs(refs);
+        refs.wasVisible = true;
+        refs.currentPosition = position;
         return true;
     }
     catch (err) {
-        try {
-            console.warn('[ns-hmr-overlay] iOS overlay apply failed:', err?.message || err);
-        }
-        catch { }
+        console.warn('[ns-hmr-overlay] iOS overlay apply failed:', err?.message || err);
         return false;
     }
 }
@@ -1064,21 +1373,19 @@ function applyRuntimeSnapshot(snapshot) {
     }
     return state.snapshot;
 }
-// Round-eleven.3 — How long the 'complete' frame stays on screen
-// before we auto-hide. The original 350ms was too tight: many HMR
-// cycles complete in 50–250ms, so the *total* overlay lifetime
-// (received → complete + 350ms) was often under 500ms, which is
-// faster than the human eye can comfortably register. 600ms gives
-// the user time to read the "Total Xms" line and confirm visually
-// that something happened.
+// How long the 'complete' frame stays on screen before we auto-hide.
+// The original 350ms was too tight: many HMR cycles complete in
+// 50–250ms, so the *total* overlay lifetime (received → complete +
+// 350ms) was often under 500ms, which is faster than the human eye
+// can comfortably register. 600ms gives the user time to read the
+// "Total Xms" line and confirm visually that something happened.
 const UPDATE_AUTO_HIDE_MS = 600;
-// Round-eleven.3 (alpha.62 follow-up) — Minimum perceptible duration
-// for an entire update overlay cycle (from 'received' to hide). If
-// the cycle finished in 50ms (e.g., a tiny HTML edit on a warm
-// cache), we still hold for ~MIN_VISIBLE_MS total before hiding so
-// the overlay is actually seen. Combined with UPDATE_AUTO_HIDE_MS,
-// the *effective* hold-after-complete = max(UPDATE_AUTO_HIDE_MS,
-// MIN_VISIBLE_MS - elapsed-since-received).
+// Minimum perceptible duration for an entire update overlay cycle
+// (from 'received' to hide). If the cycle finished in 50ms (e.g., a
+// tiny HTML edit on a warm cache), we still hold for ~MIN_VISIBLE_MS
+// total before hiding so the overlay is actually seen. Combined with
+// UPDATE_AUTO_HIDE_MS, the *effective* hold-after-complete =
+// max(UPDATE_AUTO_HIDE_MS, MIN_VISIBLE_MS - elapsed-since-received).
 const UPDATE_MIN_VISIBLE_MS = 800;
 function clearUpdateAutoHideTimer(state) {
     if (state.updateAutoHideTimer) {
@@ -1157,7 +1464,17 @@ function createOverlayApi() {
             const state = getRuntimeState();
             clearUpdateAutoHideTimer(state);
             state.updateCycleStartedAt = 0;
-            return applyRuntimeSnapshot(createBootOverlaySnapshot(stage, info));
+            const next = createBootOverlaySnapshot(stage, info);
+            // Monotonic boot-progress ratchet: boot stages can fire out of
+            // order across boot paths (JS session bootstrap vs the
+            // http-bootloader fallback) and individual bases were tuned
+            // independently, so clamp boot→boot transitions to never go
+            // backwards. Non-boot snapshots (error/ready) bypass — they
+            // genuinely want to reset the visual.
+            if (next.mode === 'boot' && state.snapshot.mode === 'boot' && typeof next.progress === 'number' && typeof state.snapshot.progress === 'number' && next.progress < state.snapshot.progress) {
+                next.progress = state.snapshot.progress;
+            }
+            return applyRuntimeSnapshot(next);
         },
         setConnectionStage(stage, info) {
             const state = getRuntimeState();
@@ -1217,12 +1534,54 @@ function createOverlayApi() {
         },
     };
 }
+// The NS_VITE_PROGRESS_OVERLAY opt-out. Read the build-time define (const-substituted
+// into served modules) first, then fall back to the globalThis seed, defaulting to
+// enabled — mirrors the gate used by the per-framework update overlays.
+function isHmrProgressOverlayEnabled() {
+    try {
+        if (typeof __NS_HMR_PROGRESS_OVERLAY_ENABLED__ === 'boolean')
+            return __NS_HMR_PROGRESS_OVERLAY_ENABLED__;
+    }
+    catch { }
+    try {
+        const seeded = getGlobalScope().__NS_HMR_PROGRESS_OVERLAY_ENABLED__;
+        if (typeof seeded === 'boolean')
+            return seeded;
+    }
+    catch { }
+    return true;
+}
+// When the overlay is opted out, every surface (boot / connection / update / pending)
+// becomes a no-op so nothing is ever drawn. The boot placeholder root and the
+// `__NS_HMR_BOOT_COMPLETE__` signal are owned by `root-placeholder.ts` and are
+// unaffected, so boot + HMR keep working — the user just sees no progress UI.
+function createNoopOverlayApi() {
+    const snapshot = () => getRuntimeState().snapshot;
+    return {
+        ensureBootPage() {
+            return null;
+        },
+        setBootStage() {
+            return snapshot();
+        },
+        setConnectionStage() {
+            return snapshot();
+        },
+        setUpdateStage() {
+            return snapshot();
+        },
+        hide() { },
+        getSnapshot() {
+            return snapshot();
+        },
+    };
+}
 export function ensureHmrDevOverlayRuntimeInstalled(verbose) {
     const g = getOverlayGlobal();
     const state = getRuntimeState();
     state.verbose = state.verbose || !!verbose;
     if (!g.__NS_HMR_DEV_OVERLAY__) {
-        g.__NS_HMR_DEV_OVERLAY__ = createOverlayApi();
+        g.__NS_HMR_DEV_OVERLAY__ = isHmrProgressOverlayEnabled() ? createOverlayApi() : createNoopOverlayApi();
     }
     return g.__NS_HMR_DEV_OVERLAY__;
 }
@@ -1235,11 +1594,11 @@ export function setHmrBootStage(stage, info) {
 export function setHmrConnectionStage(stage, info) {
     return ensureHmrDevOverlayRuntimeInstalled().setConnectionStage(stage, info);
 }
-// Round-eleven.3 — Public entry point for driving the HMR-applying
-// overlay. Callers walk through stages (received → evicting →
-// reimporting → rebooting → complete); 'complete' auto-hides after a
-// short interval. Soft-fails (no-op) if the runtime overlay was never
-// installed (e.g., production builds, test environments).
+// Public entry point for driving the HMR-applying overlay. Callers
+// walk through stages (received → evicting → reimporting → rebooting
+// → complete); 'complete' auto-hides after a short interval.
+// Soft-fails (no-op) if the runtime overlay was never installed
+// (e.g., production builds, test environments).
 export function setHmrUpdateStage(stage, info) {
     return ensureHmrDevOverlayRuntimeInstalled().setUpdateStage(stage, info);
 }