@nativescript/vite 8.0.0-alpha.7 → 8.0.0-alpha.71

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

@@ -1,1029 +1,38 @@
-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: '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,
-    };
-}
-// 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).
+ * Dev overlay public API: boot / connection / update stage setters plus the
+ * auto-hide timing policy. Rendering is delegated to two backends behind the
+ * shared snapshot/state model (`dev-overlay-shared.ts`):
+ *
+ * - `dev-overlay-ios.ts` — dedicated UIWindow above `UIWindowLevelAlert`, so
+ *   the overlay stacks above modals/sheets/system alerts (preferred on iOS)
+ * - `dev-overlay-tree.ts` — boot placeholder + in-tree toast chip (Android,
+ *   and the fallback when the iOS window can't be built)
  */
-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,
-    };
-}
+import { DEFAULT_SNAPSHOT, createBootOverlaySnapshot, createConnectionOverlaySnapshot, createUpdateOverlaySnapshot } from './dev-overlay-snapshots.js';
+import { getHmrDevOverlayPosition, getOverlayGlobal, getRuntimeState } from './dev-overlay-shared.js';
+import { applySnapshotToBootRefs, applySnapshotToLiveRefs, buildBootOverlayRefs, ensureLiveOverlayRefs, updateBootStatusLabel } from './dev-overlay-tree.js';
+import { applySnapshotToIosRefs, ensureIosOverlayRefs, getIosOverlayHost } from './dev-overlay-ios.js';
+import { resolveOverlayEnabled } from './overlay-flag.js';
+// Re-export the snapshot model and backend pure helpers so existing
+// `./dev-overlay.js` importers keep working.
+export { createBootOverlaySnapshot, createConnectionOverlaySnapshot, createUpdateOverlaySnapshot } from './dev-overlay-snapshots.js';
+export { getHmrDevOverlayPosition } from './dev-overlay-shared.js';
+export { computeAndroidToastMargin } from './dev-overlay-tree.js';
+export { computeIosOverlayLayout, computeIosOverlayWindowLevel } from './dev-overlay-ios.js';
 /**
- * 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).
+ * 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.
  */
-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) {
-            try {
-                console.info('[ns-hmr-overlay] no active UIWindowScene; skipping iOS overlay promotion');
-            }
-            catch { }
-        }
-        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) {
-        try {
-            console.warn('[ns-hmr-overlay] iOS overlay construction failed:', err?.message || err);
-        }
-        catch { }
-        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) {
-        try {
-            console.warn('[ns-hmr-overlay] iOS overlay layout failed:', err?.message || err);
-        }
-        catch { }
-    }
-}
-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) {
-        try {
-            console.warn('[ns-hmr-overlay] iOS overlay apply failed:', err?.message || err);
-        }
-        catch { }
-        return false;
+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 applyRuntimeSnapshot(snapshot) {
     const state = getRuntimeState();
@@ -1155,7 +164,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();
@@ -1215,12 +234,37 @@ function createOverlayApi() {
         },
     };
 }
+// 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__ = resolveOverlayEnabled() ? createOverlayApi() : createNoopOverlayApi();
     }
     return g.__NS_HMR_DEV_OVERLAY__;
 }