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

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

@@ -0,0 +1,1236 @@
+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',
+};
+function getOverlayGlobal() {
+    return globalThis;
+}
+function getRuntimeState() {
+    const g = getOverlayGlobal();
+    if (!g.__NS_HMR_DEV_OVERLAY_STATE__) {
+        g.__NS_HMR_DEV_OVERLAY_STATE__ = {
+            snapshot: { ...DEFAULT_SNAPSHOT },
+            bootRefs: null,
+            liveRefs: null,
+            iosRefs: null,
+            iosBuildFailed: false,
+            verbose: false,
+            updateAutoHideTimer: null,
+            updateCycleStartedAt: 0,
+        };
+    }
+    const state = g.__NS_HMR_DEV_OVERLAY_STATE__;
+    // Backfill newer fields for legacy state objects (e.g. after hot reload)
+    // so we never observe an undefined iosRefs/iosBuildFailed at runtime.
+    if (typeof state.iosRefs === 'undefined')
+        state.iosRefs = null;
+    if (typeof state.iosBuildFailed === 'undefined')
+        state.iosBuildFailed = false;
+    if (typeof state.updateAutoHideTimer === 'undefined')
+        state.updateAutoHideTimer = null;
+    if (typeof state.updateCycleStartedAt !== 'number')
+        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: 'Trying to reconnect 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,
+    };
+}
+// 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 {
+        const reg = g.__nsVendorRegistry;
+        if (reg && typeof reg.get === 'function') {
+            const mod = reg.get('@nativescript/core');
+            const ns = (mod && (mod.default ?? mod)) || mod;
+            if (ns && ns[name]) {
+                return ns[name];
+            }
+        }
+    }
+    catch { }
+    try {
+        if (g && g[name]) {
+            return g[name];
+        }
+    }
+    catch { }
+    try {
+        const req = g.__nsVendorRequire || g.__nsRequire || g.require;
+        if (typeof req === 'function') {
+            const mod = req('@nativescript/core');
+            const ns = (mod && (mod.default ?? mod)) || mod;
+            if (ns && ns[name]) {
+                return ns[name];
+            }
+        }
+    }
+    catch { }
+    try {
+        const nativeReq = g.__nativeRequire;
+        if (typeof nativeReq === 'function') {
+            const mod = nativeReq('@nativescript/core', '/');
+            const ns = (mod && (mod.default ?? mod)) || mod;
+            if (ns && ns[name]) {
+                return ns[name];
+            }
+        }
+    }
+    catch { }
+    return undefined;
+}
+function asColor(value) {
+    try {
+        const Color = resolveCoreExport('Color');
+        if (Color) {
+            return new Color(value);
+        }
+    }
+    catch { }
+    return value;
+}
+function formatStatusText(snapshot) {
+    const progressText = typeof snapshot.progress === 'number' ? ` (${Math.round(Number(snapshot.progress))}%)` : '';
+    const primary = `${snapshot.phase || ''}${progressText}`.trim();
+    return [primary, snapshot.detail].filter(Boolean).join('\n');
+}
+function buildBootOverlayRefs(snapshot) {
+    const Page = resolveCoreExport('Page');
+    const StackLayout = resolveCoreExport('StackLayout');
+    const Label = resolveCoreExport('Label');
+    const ActivityIndicator = resolveCoreExport('ActivityIndicator');
+    if (!Page || !StackLayout || !Label) {
+        return null;
+    }
+    const page = new Page();
+    page.actionBarHidden = true;
+    const root = new StackLayout();
+    root.padding = 24;
+    root.verticalAlignment = 'middle';
+    root.horizontalAlignment = 'stretch';
+    const titleLabel = new Label();
+    titleLabel.text = BOOT_TITLE;
+    titleLabel.textAlignment = 'center';
+    titleLabel.textWrap = true;
+    titleLabel.fontSize = 22;
+    titleLabel.fontWeight = '600';
+    const statusLabel = new Label();
+    statusLabel.textAlignment = 'center';
+    statusLabel.textWrap = true;
+    statusLabel.fontSize = 14;
+    statusLabel.marginTop = 12;
+    const activityIndicator = ActivityIndicator
+        ? (() => {
+            const indicator = new ActivityIndicator();
+            indicator.marginTop = 16;
+            indicator.width = 28;
+            indicator.height = 28;
+            indicator.horizontalAlignment = 'center';
+            return indicator;
+        })()
+        : null;
+    root.addChild(titleLabel);
+    root.addChild(statusLabel);
+    if (activityIndicator) {
+        root.addChild(activityIndicator);
+    }
+    page.content = root;
+    const refs = {
+        page,
+        root,
+        titleLabel,
+        statusLabel,
+        activityIndicator,
+    };
+    applySnapshotToBootRefs(refs, snapshot);
+    return refs;
+}
+function applySnapshotToBootRefs(refs, snapshot) {
+    if (!refs) {
+        return;
+    }
+    refs.page.actionBarHidden = true;
+    refs.page.backgroundColor = asColor(snapshot.tone === 'error' ? '#b4181068' : '#a1771683');
+    refs.root.visibility = snapshot.visible && snapshot.mode === 'boot' ? 'visible' : 'collapse';
+    refs.titleLabel.text = BOOT_TITLE;
+    refs.titleLabel.color = asColor(snapshot.tone === 'error' ? '#b41810e6' : '#563e3fb1');
+    refs.statusLabel.text = formatStatusText(snapshot) || 'Preparing the HTTP HMR bootstrap (4%)';
+    refs.statusLabel.color = asColor(snapshot.tone === 'error' ? '#b41810e6' : '#563e3fb1');
+    if (refs.activityIndicator) {
+        refs.activityIndicator.busy = !!snapshot.busy;
+        refs.activityIndicator.visibility = snapshot.visible && snapshot.mode === 'boot' && snapshot.busy ? 'visible' : 'collapse';
+    }
+}
+function findBootActivityIndicator() {
+    const g = getOverlayGlobal();
+    if (g.__NS_DEV_BOOT_ACTIVITY_INDICATOR__) {
+        return g.__NS_DEV_BOOT_ACTIVITY_INDICATOR__;
+    }
+    try {
+        const frame = g.__NS_DEV_PLACEHOLDER_ROOT_VIEW__;
+        if (!frame)
+            return null;
+        const page = frame.currentPage || frame._currentEntry?.resolvedPage;
+        const content = page?.content;
+        const children = content?.getChildrenCount?.() || 0;
+        if (children >= 3) {
+            const indicator = content.getChildAt?.(2);
+            if (indicator && typeof indicator.busy !== 'undefined') {
+                g.__NS_DEV_BOOT_ACTIVITY_INDICATOR__ = indicator;
+                return indicator;
+            }
+        }
+    }
+    catch { }
+    return null;
+}
+function findBootStatusLabel() {
+    const g = getOverlayGlobal();
+    // Try direct reference first
+    if (g.__NS_DEV_BOOT_STATUS_LABEL__) {
+        return g.__NS_DEV_BOOT_STATUS_LABEL__;
+    }
+    // Fallback: walk from placeholder root view
+    try {
+        const frame = g.__NS_DEV_PLACEHOLDER_ROOT_VIEW__;
+        if (!frame)
+            return null;
+        const page = frame.currentPage || frame._currentEntry?.resolvedPage;
+        if (!page)
+            return null;
+        const content = page.content;
+        if (!content)
+            return null;
+        // StackLayout with children: titleLabel, statusLabel
+        const children = content.getChildrenCount?.() || 0;
+        if (children >= 2) {
+            const label = content.getChildAt?.(1);
+            if (label && typeof label.text !== 'undefined') {
+                // Cache for next time
+                g.__NS_DEV_BOOT_STATUS_LABEL__ = label;
+                return label;
+            }
+        }
+    }
+    catch { }
+    return null;
+}
+function updateBootStatusLabel(snapshot) {
+    const newText = formatStatusText(snapshot) || 'Preparing the HTTP HMR bootstrap (4%)';
+    const statusLabel = findBootStatusLabel();
+    const activityIndicator = findBootActivityIndicator();
+    if (!statusLabel) {
+        if (activityIndicator) {
+            try {
+                activityIndicator.busy = !!snapshot.busy;
+                activityIndicator.visibility = snapshot.visible && snapshot.mode === 'boot' && snapshot.busy ? 'visible' : 'collapse';
+            }
+            catch { }
+        }
+        return;
+    }
+    try {
+        statusLabel.text = newText;
+        statusLabel.color = asColor(snapshot.tone === 'error' ? '#b41810e6' : '#563e3fb1');
+        if (typeof statusLabel.requestLayout === 'function') {
+            statusLabel.requestLayout();
+        }
+        const parent = statusLabel.parent;
+        if (parent && typeof parent.requestLayout === 'function') {
+            parent.requestLayout();
+        }
+    }
+    catch { }
+    if (activityIndicator) {
+        try {
+            activityIndicator.busy = !!snapshot.busy;
+            activityIndicator.visibility = snapshot.visible && snapshot.mode === 'boot' && snapshot.busy ? 'visible' : 'collapse';
+        }
+        catch { }
+    }
+}
+function resolveActivePage() {
+    try {
+        const Frame = resolveCoreExport('Frame');
+        const frame = Frame?.topmost?.() || null;
+        const currentPage = frame?.currentPage || frame?._currentEntry?.resolvedPage || null;
+        if (currentPage) {
+            return currentPage;
+        }
+    }
+    catch { }
+    try {
+        const Application = resolveCoreExport('Application');
+        const rootView = Application?.getRootView?.() || null;
+        if (rootView?.currentPage) {
+            return rootView.currentPage;
+        }
+        if (typeof rootView?.content !== 'undefined') {
+            return rootView;
+        }
+    }
+    catch { }
+    return null;
+}
+function buildLiveOverlayView(snapshot) {
+    const GridLayout = resolveCoreExport('GridLayout');
+    const StackLayout = resolveCoreExport('StackLayout');
+    const Label = resolveCoreExport('Label');
+    if (!GridLayout || !StackLayout || !Label) {
+        return null;
+    }
+    const overlay = new GridLayout();
+    overlay.visibility = 'collapse';
+    overlay.width = '100%';
+    overlay.height = '100%';
+    overlay.horizontalAlignment = 'stretch';
+    overlay.verticalAlignment = 'stretch';
+    const panel = new StackLayout();
+    panel.horizontalAlignment = 'center';
+    panel.verticalAlignment = 'middle';
+    panel.width = 320;
+    panel.margin = 24;
+    panel.padding = 16;
+    const titleLabel = new Label();
+    titleLabel.textAlignment = 'center';
+    titleLabel.textWrap = true;
+    titleLabel.fontSize = 18;
+    titleLabel.fontWeight = '600';
+    const statusLabel = new Label();
+    statusLabel.textAlignment = 'center';
+    statusLabel.textWrap = true;
+    statusLabel.fontSize = 13;
+    statusLabel.marginTop = 10;
+    panel.addChild(titleLabel);
+    panel.addChild(statusLabel);
+    overlay.addChild(panel);
+    const refs = {
+        overlay,
+        titleLabel,
+        statusLabel,
+    };
+    applySnapshotToLiveRefs(refs, snapshot);
+    return refs;
+}
+function ensureLiveOverlayRefs(snapshot) {
+    const state = getRuntimeState();
+    const page = resolveActivePage();
+    if (!page) {
+        return null;
+    }
+    if (state.liveRefs) {
+        if (state.liveRefs.page === page && state.liveRefs.overlay?.parent) {
+            return state.liveRefs;
+        }
+        try {
+            state.liveRefs.overlay.visibility = 'collapse';
+        }
+        catch { }
+        state.liveRefs = null;
+    }
+    const GridLayout = resolveCoreExport('GridLayout');
+    if (!GridLayout || typeof page.content === 'undefined') {
+        return null;
+    }
+    let wrapper = page.content;
+    if (!wrapper || !wrapper.__ns_hmr_overlay_wrapper__) {
+        const currentContent = page.content || null;
+        wrapper = new GridLayout();
+        wrapper.width = '100%';
+        wrapper.height = '100%';
+        wrapper.__ns_hmr_overlay_wrapper__ = true;
+        try {
+            page.content = null;
+        }
+        catch { }
+        if (currentContent) {
+            wrapper.addChild(currentContent);
+        }
+        page.content = wrapper;
+    }
+    const liveView = buildLiveOverlayView(snapshot);
+    if (!liveView) {
+        return null;
+    }
+    wrapper.addChild(liveView.overlay);
+    state.liveRefs = {
+        page,
+        wrapper,
+        ...liveView,
+    };
+    return state.liveRefs;
+}
+function applySnapshotToLiveRefs(refs, snapshot) {
+    if (!refs) {
+        return;
+    }
+    // '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.
+    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);
+    refs.titleLabel.text = snapshot.title;
+    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);
+    try {
+        const 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;
+            panel.padding = 16;
+            try {
+                panel.borderRadius = 12;
+            }
+            catch { }
+        }
+    }
+    catch { }
+}
+// pure helpers for iOS window promotion. Factored out so the layout
+// math and window-level selection stay unit-testable without booting a
+// simulator. See `dev-overlay.spec.ts`.
+/**
+ * Returns the UIWindow level we use for the live/connection overlay. We lift
+ * above `UIWindowLevelAlert` so system alerts (and any app-presented modal)
+ * stack underneath. When the platform does not expose `UIWindowLevelAlert`
+ * we fall back to the documented constant value (2000).
+ */
+export function computeIosOverlayWindowLevel(baseAlert) {
+    if (typeof baseAlert === 'number' && Number.isFinite(baseAlert)) {
+        return baseAlert + 1;
+    }
+    return 2000 + 1;
+}
+/**
+ * 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.
+ */
+export function computeIosOverlayLayout(input) {
+    const viewWidth = Math.max(0, Number(input.viewWidth) || 0);
+    const viewHeight = Math.max(0, Number(input.viewHeight) || 0);
+    const safeInsets = {
+        top: Math.max(0, Number(input.safeInsets?.top ?? 0) || 0),
+        bottom: Math.max(0, Number(input.safeInsets?.bottom ?? 0) || 0),
+        left: Math.max(0, Number(input.safeInsets?.left ?? 0) || 0),
+        right: Math.max(0, Number(input.safeInsets?.right ?? 0) || 0),
+    };
+    const titleHeight = Math.max(0, Number(input.titleHeight) || 0);
+    const statusHeight = Math.max(0, Number(input.statusHeight) || 0);
+    const horizontalMargin = Math.max(0, Number(input.horizontalMargin ?? 24));
+    const maxPanelWidth = Math.max(0, Number(input.maxPanelWidth ?? 340));
+    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));
+    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);
+    return {
+        backdrop: { x: 0, y: 0, width: viewWidth, height: viewHeight },
+        panel: { x: panelX, y: panelY, width: panelWidth, height: panelHeight },
+        title: { x: panelPadding, y: panelPadding, width: innerWidth, height: titleHeight },
+        status: {
+            x: panelPadding,
+            y: panelPadding + titleHeight + spacing,
+            width: innerWidth,
+            height: statusHeight,
+        },
+    };
+}
+/**
+ * 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
+ * tests so callers can gracefully fall back to the in-tree overlay.
+ */
+function getIosOverlayHost() {
+    const g = getOverlayGlobal();
+    if (typeof g.UIWindow === 'undefined' || typeof g.UIApplication === 'undefined' || typeof g.UIViewController === 'undefined' || typeof g.UIView === 'undefined' || typeof g.UILabel === 'undefined' || typeof g.UIColor === 'undefined' || typeof g.UIFont === 'undefined' || typeof g.UIScreen === 'undefined') {
+        return null;
+    }
+    return {
+        UIWindow: g.UIWindow,
+        UIViewController: g.UIViewController,
+        UIView: g.UIView,
+        UILabel: g.UILabel,
+        UIColor: g.UIColor,
+        UIFont: g.UIFont,
+        UIApplication: g.UIApplication,
+        UIScreen: g.UIScreen,
+        UIWindowLevelAlert: typeof g.UIWindowLevelAlert === 'number' ? g.UIWindowLevelAlert : undefined,
+    };
+}
+/**
+ * Walks UIApplication.sharedApplication windows and returns the first active
+ * UIWindowScene we can locate. On iOS 13+ every UIWindow is attached to a
+ * scene, and we must initialise our overlay window the same way or the OS
+ * will silently refuse to render it. Returns null when no scene is found
+ * (older iOS versions or non-UI environments).
+ */
+function findActiveWindowScene(host) {
+    try {
+        const app = host.UIApplication.sharedApplication;
+        const windows = app?.windows;
+        if (!windows || typeof windows.count !== 'number')
+            return null;
+        for (let i = 0; i < windows.count; i++) {
+            const w = windows.objectAtIndex(i);
+            const scene = w && w.windowScene;
+            if (scene)
+                return scene;
+        }
+    }
+    catch { }
+    return null;
+}
+function buildIosOverlayRefs(state) {
+    const host = getIosOverlayHost();
+    if (!host)
+        return null;
+    // Without a scene we can't build a modern UIWindow that actually renders.
+    // Fall back to the in-tree overlay rather than show nothing.
+    const scene = findActiveWindowScene(host);
+    if (!scene) {
+        if (state.verbose) {
+            console.info('[ns-hmr-overlay] no active UIWindowScene; skipping iOS overlay promotion');
+        }
+        return null;
+    }
+    try {
+        const { UIWindow, UIViewController, UIView, UILabel, UIColor, UIFont } = host;
+        const window = UIWindow.alloc().initWithWindowScene(scene);
+        window.windowLevel = computeIosOverlayWindowLevel(host.UIWindowLevelAlert ?? null);
+        window.backgroundColor = UIColor.clearColor;
+        window.hidden = true;
+        const controller = UIViewController.new();
+        controller.view.backgroundColor = UIColor.clearColor;
+        window.rootViewController = controller;
+        // UIViewAutoresizing bit masks. We mirror the UIKit constants here to
+        // avoid depending on symbols the metadata bridge does not always
+        // expose as top-level globals.
+        const FLEXIBLE_LEFT_MARGIN = 1 << 0;
+        const FLEXIBLE_WIDTH = 1 << 1;
+        const FLEXIBLE_RIGHT_MARGIN = 1 << 2;
+        const FLEXIBLE_TOP_MARGIN = 1 << 3;
+        const FLEXIBLE_HEIGHT = 1 << 4;
+        const FLEXIBLE_BOTTOM_MARGIN = 1 << 5;
+        const backdrop = UIView.new();
+        backdrop.backgroundColor = UIColor.colorWithRedGreenBlueAlpha(0, 0, 0, 0.35);
+        backdrop.autoresizingMask = FLEXIBLE_WIDTH | FLEXIBLE_HEIGHT;
+        controller.view.addSubview(backdrop);
+        const panel = UIView.new();
+        panel.backgroundColor = UIColor.whiteColor;
+        panel.autoresizingMask = FLEXIBLE_LEFT_MARGIN | FLEXIBLE_RIGHT_MARGIN | FLEXIBLE_TOP_MARGIN | FLEXIBLE_BOTTOM_MARGIN;
+        try {
+            panel.layer.cornerRadius = 14;
+            panel.layer.masksToBounds = true;
+        }
+        catch { }
+        controller.view.addSubview(panel);
+        const titleLabel = UILabel.new();
+        titleLabel.numberOfLines = 0;
+        titleLabel.textAlignment = 1; // NSTextAlignmentCenter
+        titleLabel.font = UIFont.boldSystemFontOfSize(16);
+        titleLabel.textColor = UIColor.blackColor;
+        panel.addSubview(titleLabel);
+        const statusLabel = UILabel.new();
+        statusLabel.numberOfLines = 0;
+        statusLabel.textAlignment = 1;
+        statusLabel.font = UIFont.systemFontOfSize(13);
+        statusLabel.textColor = UIColor.darkGrayColor;
+        panel.addSubview(statusLabel);
+        return { window, controller, backdrop, panel, titleLabel, statusLabel };
+    }
+    catch (err) {
+        console.warn('[ns-hmr-overlay] iOS overlay construction failed:', err?.message || err);
+        return null;
+    }
+}
+function ensureIosOverlayRefs(state) {
+    if (state.iosRefs)
+        return state.iosRefs;
+    if (state.iosBuildFailed)
+        return null;
+    const built = buildIosOverlayRefs(state);
+    if (built) {
+        state.iosRefs = built;
+    }
+    else {
+        // Remember failure so we don't hammer construction on every snapshot
+        // update — the in-tree path will take over for this session.
+        state.iosBuildFailed = true;
+    }
+    return state.iosRefs;
+}
+function layoutIosOverlayRefs(refs) {
+    try {
+        const bounds = refs.controller.view.bounds;
+        const viewWidth = Number(bounds?.size?.width) || 0;
+        const viewHeight = Number(bounds?.size?.height) || 0;
+        const raw = refs.controller.view.safeAreaInsets;
+        const safeInsets = raw
+            ? {
+                top: Number(raw.top) || 0,
+                bottom: Number(raw.bottom) || 0,
+                left: Number(raw.left) || 0,
+                right: Number(raw.right) || 0,
+            }
+            : { top: 0, bottom: 0, left: 0, right: 0 };
+        // Ask UIKit what the labels want given the panel inner width. We use a
+        // generous height bound so nothing clips on long reconnect strings.
+        const panelPadding = 16;
+        const horizontalMargin = 24;
+        const maxPanelWidth = 340;
+        const innerWidth = Math.max(0, Math.min(maxPanelWidth, viewWidth - 2 * horizontalMargin - safeInsets.left - safeInsets.right) - 2 * panelPadding);
+        const titleFit = refs.titleLabel.sizeThatFits({ width: innerWidth, height: 10000 }) || { height: 0 };
+        const statusFit = refs.statusLabel.sizeThatFits({ width: innerWidth, height: 10000 }) || { height: 0 };
+        const layout = computeIosOverlayLayout({
+            viewWidth,
+            viewHeight,
+            safeInsets,
+            titleHeight: Number(titleFit.height) || 0,
+            statusHeight: Number(statusFit.height) || 0,
+            maxPanelWidth,
+            horizontalMargin,
+            panelPadding,
+        });
+        const toCgRect = (rect) => ({
+            origin: { x: rect.x, y: rect.y },
+            size: { width: rect.width, height: rect.height },
+        });
+        refs.backdrop.frame = toCgRect(layout.backdrop);
+        refs.panel.frame = toCgRect(layout.panel);
+        refs.titleLabel.frame = toCgRect(layout.title);
+        refs.statusLabel.frame = toCgRect(layout.status);
+    }
+    catch (err) {
+        console.warn('[ns-hmr-overlay] iOS overlay layout failed:', err?.message || err);
+    }
+}
+function applySnapshotToIosRefs(refs, snapshot) {
+    if (!refs)
+        return false;
+    try {
+        // '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)
+            return true;
+        refs.titleLabel.text = snapshot.title || '';
+        refs.statusLabel.text = formatStatusText(snapshot);
+        const host = getIosOverlayHost();
+        if (host) {
+            const { UIColor } = host;
+            const isError = snapshot.tone === 'error';
+            const isSuccess = snapshot.tone === 'success';
+            try {
+                if (isError) {
+                    // Red panel + dark red text (existing UX).
+                    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
+                    // text. The previous 0.94/0.99/0.95 background was
+                    // nearly indistinguishable from white on most
+                    // devices; this bump keeps long detail strings
+                    // readable while making the apply event obviously
+                    // "happening right now".
+                    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;
+                    refs.backdrop.backgroundColor = UIColor.colorWithRedGreenBlueAlpha(0, 0, 0, 0.35);
+                }
+            }
+            catch { }
+        }
+        layoutIosOverlayRefs(refs);
+        return true;
+    }
+    catch (err) {
+        console.warn('[ns-hmr-overlay] iOS overlay apply failed:', err?.message || err);
+        return false;
+    }
+}
+function applyRuntimeSnapshot(snapshot) {
+    const state = getRuntimeState();
+    state.snapshot = snapshot;
+    // Update the boot status label created by root-placeholder.ts
+    if (snapshot.mode === 'boot') {
+        updateBootStatusLabel(snapshot);
+    }
+    applySnapshotToBootRefs(state.bootRefs, snapshot);
+    // prefer the dedicated UIWindow
+    // path so the live/update overlays always stack on top of modals,
+    // sheets, and other windows. Fall back to the in-tree overlay when
+    // iOS APIs aren't available (Android, tests, or when scene
+    // construction fails).
+    let handledByIos = false;
+    // Both 'connection' and 'update' use the small-panel surface
+    // (UIWindow on iOS, in-tree overlay everywhere else). 'boot' uses
+    // the placeholder root via applySnapshotToBootRefs above; 'hidden'
+    // hides everything.
+    const wantsOverlay = snapshot.visible && (snapshot.mode === 'connection' || snapshot.mode === 'update');
+    if (getIosOverlayHost()) {
+        if (wantsOverlay) {
+            const iosRefs = ensureIosOverlayRefs(state);
+            handledByIos = applySnapshotToIosRefs(iosRefs, snapshot);
+        }
+        else if (state.iosRefs) {
+            handledByIos = applySnapshotToIosRefs(state.iosRefs, snapshot);
+        }
+    }
+    if (!handledByIos) {
+        if (wantsOverlay) {
+            const liveRefs = ensureLiveOverlayRefs(snapshot);
+            applySnapshotToLiveRefs(liveRefs, snapshot);
+        }
+        else {
+            applySnapshotToLiveRefs(state.liveRefs, snapshot);
+        }
+    }
+    return state.snapshot;
+}
+// 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;
+// 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) {
+        try {
+            clearTimeout(state.updateAutoHideTimer);
+        }
+        catch { }
+        state.updateAutoHideTimer = null;
+    }
+}
+function scheduleUpdateAutoHide(state) {
+    clearUpdateAutoHideTimer(state);
+    // Compute how much longer we need to hold the overlay so that the
+    // total cycle visibility is at least UPDATE_MIN_VISIBLE_MS. For
+    // fast cycles (50ms reboot) this stretches the hide; for slow
+    // cycles (>UPDATE_MIN_VISIBLE_MS) it falls back to the standard
+    // UPDATE_AUTO_HIDE_MS so we don't truncate the celebratory hold.
+    const startedAt = state.updateCycleStartedAt || 0;
+    const elapsed = startedAt > 0 ? Math.max(0, Date.now() - startedAt) : 0;
+    const minRemainder = elapsed > 0 ? Math.max(0, UPDATE_MIN_VISIBLE_MS - elapsed) : UPDATE_MIN_VISIBLE_MS;
+    const holdMs = Math.max(UPDATE_AUTO_HIDE_MS, minRemainder);
+    try {
+        state.updateAutoHideTimer = setTimeout(() => {
+            state.updateAutoHideTimer = null;
+            // Critical: only auto-hide if we're still on the 'complete'
+            // frame. If a new HMR cycle has rotated the snapshot back
+            // to 'update' / 'received' (e.g., user saved twice in
+            // quick succession), the new cycle owns the overlay and
+            // our timer must not steal it.
+            const current = state.snapshot;
+            if (current.mode === 'update' && current.tone === 'success' && current.progress === 100) {
+                state.updateCycleStartedAt = 0;
+                applyRuntimeSnapshot({ ...DEFAULT_SNAPSHOT });
+            }
+        }, holdMs);
+    }
+    catch {
+        // setTimeout missing (extremely rare; some test envs). Fall
+        // back to immediate hide so we never leave the overlay visible
+        // forever after a 'complete'.
+        state.updateCycleStartedAt = 0;
+        applyRuntimeSnapshot({ ...DEFAULT_SNAPSHOT });
+    }
+}
+function logUpdateStageTransition(state, stage, info) {
+    if (!state.verbose)
+        return;
+    try {
+        const detail = info?.detail || '';
+        const progress = typeof info?.progress === 'number' ? info.progress : null;
+        const progressTag = progress !== null ? ` (${Math.round(progress)}%)` : '';
+        // Single-line breadcrumb so a developer can correlate
+        // overlay frames with the [ns-hmr][angular] timing log when
+        // debugging "I don't see the overlay" reports.
+        console.info(`[ns-hmr-overlay] update stage=${stage}${progressTag}${detail ? ` detail=${detail}` : ''}`);
+    }
+    catch { }
+}
+function createOverlayApi() {
+    return {
+        ensureBootPage(verbose) {
+            const state = getRuntimeState();
+            state.verbose = state.verbose || !!verbose;
+            if (!state.snapshot.visible || state.snapshot.mode !== 'boot') {
+                state.snapshot = createBootOverlaySnapshot('placeholder');
+            }
+            if (!state.bootRefs) {
+                state.bootRefs = buildBootOverlayRefs(state.snapshot);
+            }
+            applySnapshotToBootRefs(state.bootRefs, state.snapshot);
+            return state.bootRefs?.page || null;
+        },
+        setBootStage(stage, info) {
+            // A boot transition cancels any pending HMR auto-hide so
+            // the boot phase always wins.
+            const state = getRuntimeState();
+            clearUpdateAutoHideTimer(state);
+            state.updateCycleStartedAt = 0;
+            return applyRuntimeSnapshot(createBootOverlaySnapshot(stage, info));
+        },
+        setConnectionStage(stage, info) {
+            const state = getRuntimeState();
+            clearUpdateAutoHideTimer(state);
+            state.updateCycleStartedAt = 0;
+            return applyRuntimeSnapshot(createConnectionOverlaySnapshot(stage, info));
+        },
+        setUpdateStage(stage, info) {
+            const state = getRuntimeState();
+            // Each new in-progress stage cancels any pending auto-hide
+            // from a previous cycle. Without this, two saves in quick
+            // succession could see cycle-2's progress overlay yanked
+            // off by cycle-1's already-scheduled hide.
+            clearUpdateAutoHideTimer(state);
+            // Stamp the cycle start on 'received', but distinguish
+            // between two cases:
+            //
+            //   (a) Re-assertion of the SAME cycle (e.g., the server
+            //       emits both `ns:hmr-pending` AND `ns:angular-update`,
+            //       both of which call `setUpdateStage('received')`).
+            //       We must PRESERVE the original timestamp so the
+            //       minimum-visible-window math measures the FIRST
+            //       'received' the user actually saw.
+            //
+            //   (b) Genuinely-new cycle starting either from a hidden
+            //       overlay OR while the previous cycle is still on
+            //       its 'complete' frame (pre auto-hide). In both
+            //       sub-cases we MUST stamp a fresh start so the
+            //       new cycle's auto-hide math is sane.
+            //
+            // We treat the previous snapshot as "in-progress for the
+            // same cycle" iff mode==='update' AND progress!==100.
+            // 'complete' frames are a sign that the cycle finished;
+            // any subsequent 'received' is a NEW cycle.
+            if (stage === 'received') {
+                const prev = state.snapshot;
+                const isMidCycleReassertion = prev.mode === 'update' && prev.progress !== 100;
+                if (!isMidCycleReassertion) {
+                    state.updateCycleStartedAt = Date.now();
+                }
+            }
+            logUpdateStageTransition(state, stage, info);
+            const snapshot = applyRuntimeSnapshot(createUpdateOverlaySnapshot(stage, info));
+            if (stage === 'complete') {
+                scheduleUpdateAutoHide(state);
+            }
+            return snapshot;
+        },
+        hide() {
+            const state = getRuntimeState();
+            clearUpdateAutoHideTimer(state);
+            state.updateCycleStartedAt = 0;
+            applyRuntimeSnapshot({ ...DEFAULT_SNAPSHOT });
+        },
+        getSnapshot() {
+            return getRuntimeState().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();
+    }
+    return g.__NS_HMR_DEV_OVERLAY__;
+}
+export function createHmrBootOverlayPage(verbose) {
+    return ensureHmrDevOverlayRuntimeInstalled(verbose).ensureBootPage(verbose);
+}
+export function setHmrBootStage(stage, info) {
+    return ensureHmrDevOverlayRuntimeInstalled().setBootStage(stage, info);
+}
+export function setHmrConnectionStage(stage, info) {
+    return ensureHmrDevOverlayRuntimeInstalled().setConnectionStage(stage, info);
+}
+// 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);
+}
+export function hideHmrDevOverlay(reason) {
+    void reason;
+    ensureHmrDevOverlayRuntimeInstalled().hide(reason);
+}
+//# sourceMappingURL=dev-overlay.js.map