@nativescript/vite 8.0.0-beta.0 → 8.0.0-rc.0

package/hmr/shared/runtime/boot-progress.js

@@ -0,0 +1,134 @@
+import { getGlobalScope } from './global-scope.js';
+// Pure helpers for the cold-boot "Importing the app entry" progress display.
+//
+// Pipeline:
+//   * Server-side `buildBootProgressSnippet` is injected at the top of
+//     every served app module and bumps the count / last-module globals
+//     while `__NS_HMR_BOOT_COMPLETE__` is falsy (self-gating — the
+//     snippet no-ops after boot; FULLY SYNCHRONOUS — see the snippet
+//     doc for why top-level await must stay out of served modules).
+//   * `startBrowserRuntimeSession` stamps the time origin
+//     (`__NS_HMR_BOOT_IMPORT_STARTED_AT__`) right before the client +
+//     entry dynamic-import walk.
+//   * `startBootImportHeartbeat` reads both signals every 250 ms and
+//     re-asserts `'importing-main'` so the bar climbs even across long
+//     vendor stretches that don't tick the count axis. The iOS runtime's
+//     `MaybePumpJSThreadDuringBoot` keeps the JS-thread CFRunLoop ticking
+//     between synchronous fetches so the heartbeat's `setInterval` timer
+//     can fire during the cold-boot module walk.
+//
+// Monotonic ratchet (`applyMonotonicBootProgress`,
+// `__NS_HMR_BOOT_LAST_PROGRESS__`): each tick can never undercut the
+// previous one, preventing visible stutter when the count axis briefly
+// wins over the time axis.
+/**
+ * `'importing-main'` is the long HTTP-module-load phase (5–10s for a
+ * real Angular app). The bar uses this range so the user sees ~62
+ * percentage points of motion during the phase that actually takes
+ * time, sandwiched between the cheap bootstrap stages
+ * ('configuring-import-map' = 26) and the post-import wait
+ * ('waiting-for-app' = 94 → 'app-root-committed' = 100).
+ */
+export const BOOT_IMPORT_PROGRESS_MIN = 30;
+export const BOOT_IMPORT_PROGRESS_MAX = 92;
+/** Ceiling guards against rounding into `'waiting-for-app'` (94). */
+export const BOOT_IMPORT_PROGRESS_CEILING = 94;
+const BOOT_IMPORT_PROGRESS_RANGE = BOOT_IMPORT_PROGRESS_MAX - BOOT_IMPORT_PROGRESS_MIN;
+/**
+ * Compute the percentage shown next to "Importing the app entry".
+ *
+ * Sum of two clamped contributions:
+ *   * `progressFromCount` — `__NS_HMR_BOOT_MODULE_COUNT__` bumped by the
+ *     boot snippet (1 unit per 2 modules, cap 40).
+ *   * `progressFromTime` — elapsed wall-clock since
+ *     `__NS_HMR_BOOT_IMPORT_STARTED_AT__` (1 unit per 250 ms, cap
+ *     matches the full 62-point range so time alone can drive the bar
+ *     30 → 92 if the count axis is starved).
+ *
+ * The count axis goes silent in long node_modules stretches and on
+ * Vite's rewrite chains where the served import URL skips the
+ * `__ns_boot__/b1` prefix; the time axis covers those gaps. Both
+ * contributions are summed, clamped to the 62-point range, then
+ * ceilinged so they cannot cross into 'waiting-for-app' (94+).
+ *
+ * Canonical values are pinned by `boot-progress.spec.ts`. The
+ * server-side snippet does NOT mirror this math — it only writes the
+ * counters; the heartbeat in `session-bootstrap.ts` is the sole caller.
+ */
+const BOOT_IMPORT_COUNT_CONTRIBUTION_MAX = 40;
+const BOOT_IMPORT_TIME_CONTRIBUTION_MAX = 62;
+const BOOT_IMPORT_COUNT_DIVISOR = 2;
+const BOOT_IMPORT_TIME_TICK_MS = 250;
+export function computeBootImportProgress(input) {
+    // Coerce NaN / ±Infinity / negatives to 0 — `Math.max(0, NaN)` is NaN.
+    const rawCount = Number(input?.count ?? 0);
+    const rawElapsed = Number(input?.elapsedMs ?? 0);
+    const count = Number.isFinite(rawCount) ? Math.max(0, rawCount) : 0;
+    const elapsedMs = Number.isFinite(rawElapsed) ? Math.max(0, rawElapsed) : 0;
+    const progressFromCount = Math.min(BOOT_IMPORT_COUNT_CONTRIBUTION_MAX, Math.floor(count / BOOT_IMPORT_COUNT_DIVISOR));
+    const progressFromTime = Math.min(BOOT_IMPORT_TIME_CONTRIBUTION_MAX, Math.floor(elapsedMs / BOOT_IMPORT_TIME_TICK_MS));
+    const combined = BOOT_IMPORT_PROGRESS_MIN + Math.min(BOOT_IMPORT_PROGRESS_RANGE, progressFromCount + progressFromTime);
+    return Math.min(BOOT_IMPORT_PROGRESS_CEILING, combined);
+}
+/**
+ * Render the second-line detail for the placeholder. Surfaces the
+ * count + last-loaded module path once the snippet has fired, or a
+ * generic "Loading the module graph…" line during the pre-snippet
+ * window.
+ *
+ * No elapsed-ms readout: the primary line's percentage is the progress
+ * signal, and the heartbeat's `elapsedMs` is wall-clock since the import
+ * started — not a per-module timing — so surfacing it next to the
+ * percentage read as a confusing, inaccurate duration.
+ */
+export function formatBootImportDetail(input) {
+    const count = Math.max(0, Number(input?.count ?? 0));
+    const lastModule = typeof input?.lastModule === 'string' ? input.lastModule : '';
+    if (count > 0) {
+        return lastModule ? `Evaluated ${count} modules\n${lastModule}` : `Evaluated ${count} modules`;
+    }
+    return 'Loading the module graph…';
+}
+/**
+ * Ratchet a candidate boot-import progress value against the highest
+ * value any consumer has emitted so far (stored on
+ * `globalThis.__NS_HMR_BOOT_LAST_PROGRESS__`). Reset by
+ * `clearBootProgressState` between sessions.
+ */
+export function applyMonotonicBootProgress(candidate) {
+    const g = getGlobalScope();
+    const previousRaw = g.__NS_HMR_BOOT_LAST_PROGRESS__;
+    const previous = typeof previousRaw === 'number' && Number.isFinite(previousRaw) ? previousRaw : 0;
+    const next = Math.max(previous, Math.max(0, Number(candidate) || 0));
+    try {
+        g.__NS_HMR_BOOT_LAST_PROGRESS__ = next;
+    }
+    catch { }
+    return next;
+}
+/**
+ * Reset every boot-progress global so a re-bootstrapped session (e.g.
+ * after `__reboot_ng_modules__`) starts a fresh ratchet rather than
+ * inheriting the previous cycle's terminal values.
+ */
+export function clearBootProgressState() {
+    const g = getGlobalScope();
+    for (const key of [
+        '__NS_HMR_BOOT_MODULE_COUNT__',
+        '__NS_HMR_BOOT_LAST_MODULE__',
+        '__NS_HMR_BOOT_LAST_PROGRESS__',
+        '__NS_HMR_BOOT_LAST_PROGRESS_AT__',
+        '__NS_HMR_BOOT_IMPORT_STARTED_AT__',
+        // Defensive: an earlier snippet shape used this to throttle a
+        // top-level await yield. Removed — top-level await in a boot-tagged
+        // module trips the iOS 10s async-module deadline. Cleared in case a
+        // stale boot left it behind.
+        '__NS_HMR_BOOT_LAST_YIELD_AT__',
+    ]) {
+        try {
+            delete g[key];
+        }
+        catch { }
+    }
+}
+//# sourceMappingURL=boot-progress.js.map

package/hmr/shared/runtime/boot-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-progress.js","sourceRoot":"","sources":["../../../../../../packages/vite/hmr/shared/runtime/boot-progress.ts"],"names":[],"mappings":"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"}

package/hmr/shared/runtime/boot-timeline.d.ts

@@ -0,0 +1,17 @@
+export type BootTraceSegment = {
+    ok?: boolean;
+    ms?: number;
+    meta?: Record<string, unknown>;
+};
+export type BootTrace = {
+    t0: number;
+    t1?: number;
+    session?: BootTraceSegment;
+    importMap?: BootTraceSegment;
+    entry?: BootTraceSegment;
+    error?: {
+        message: string;
+    };
+};
+export declare function formatBootTimeline(trace: BootTrace): string;
+export declare function publishBootTrace(trace: BootTrace): void;

package/hmr/shared/runtime/boot-timeline.js

@@ -0,0 +1,40 @@
+import { getGlobalScope } from './global-scope.js';
+// Pure formatter so we can unit-test the exact string shape without
+// touching `console.info` or `Date.now()`.
+//
+// Format:
+//   [ns-boot] ok total=1234ms session=45ms importMap=67ms entry=1100ms
+//   [ns-boot] FAILED total=230ms session=45ms ...: <message>
+//
+// Segment entries are only included when a numeric `ms` was recorded —
+// this keeps the log compact when a particular phase was skipped (e.g.
+// `__NS_IMPORT_MAP_CONFIGURED__` dedup) or never reached (early error).
+export function formatBootTimeline(trace) {
+    const status = trace.error ? 'FAILED' : 'ok';
+    const parts = [];
+    const push = (label, seg) => {
+        if (seg && typeof seg.ms === 'number' && Number.isFinite(seg.ms)) {
+            parts.push(`${label}=${Math.max(0, Math.round(seg.ms))}ms`);
+        }
+    };
+    const total = typeof trace.t0 === 'number' && typeof trace.t1 === 'number' ? trace.t1 - trace.t0 : undefined;
+    if (typeof total === 'number' && Number.isFinite(total)) {
+        parts.push(`total=${Math.max(0, Math.round(total))}ms`);
+    }
+    push('session', trace.session);
+    push('importMap', trace.importMap);
+    push('entry', trace.entry);
+    const suffix = trace.error?.message ? `: ${trace.error.message}` : '';
+    return `[ns-boot] ${status} ${parts.join(' ')}${suffix}`.replace(/\s+$/, '');
+}
+// Install the trace on `globalThis` so diagnostics can pick it up. The key
+// is distinct from the entry-runtime trace (`__NS_ENTRY_TRACE__`), which the
+// entry runtime writes for its own phases. Exported for tests; the runtime
+// path calls this from the session-bootstrap finally block.
+export function publishBootTrace(trace) {
+    try {
+        getGlobalScope().__NS_BOOT_TRACE__ = trace;
+    }
+    catch { }
+}
+//# sourceMappingURL=boot-timeline.js.map

package/hmr/shared/runtime/boot-timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-timeline.js","sourceRoot":"","sources":["../../../../../../packages/vite/hmr/shared/runtime/boot-timeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AA8BnD,oEAAoE;AACpE,2CAA2C;AAC3C,EAAE;AACF,UAAU;AACV,uEAAuE;AACvE,6DAA6D;AAC7D,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,wEAAwE;AACxE,MAAM,UAAU,kBAAkB,CAAC,KAAgB;IAClD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,GAAiC,EAAE,EAAE;QACjE,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAClE,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAC7D,CAAC;IACF,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAE7G,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,KAAK,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IACnC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAE3B,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAEtE,OAAO,aAAa,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED,2EAA2E;AAC3E,6EAA6E;AAC7E,2EAA2E;AAC3E,4DAA4D;AAC5D,MAAM,UAAU,gBAAgB,CAAC,KAAgB;IAChD,IAAI,CAAC;QACJ,cAAc,EAAE,CAAC,iBAAiB,GAAG,KAAK,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC,CAAA,CAAC;AACX,CAAC"}

package/hmr/shared/runtime/browser-runtime-contract.d.ts

@@ -0,0 +1,97 @@
+export type NsDevPlatform = 'ios' | 'android' | 'visionos';
+export type NsHostModuleId = `ns-host://${string}`;
+export declare const NS_HOST_RUNTIME_MODULE_ID: "ns-host://runtime";
+export declare const NS_HOST_STYLE_ADAPTER_MODULE_ID: "ns-host://style-adapter";
+export declare const NS_DEFAULT_HOST_MODULES: readonly ["ns-host://runtime", "ns-host://style-adapter"];
+export declare const NS_DEV_SESSION_REQUIRED_FIELDS: readonly ["sessionId", "origin", "entryUrl", "clientUrl", "wsUrl", "platform"];
+export interface NsDevFeatureFlags {
+    fullReload?: boolean;
+    cssHmr?: boolean;
+    errorOverlay?: boolean;
+    styleScopeHmr?: boolean;
+}
+export declare const NS_DEFAULT_DEV_FEATURE_FLAGS: Readonly<Required<Pick<NsDevFeatureFlags, 'fullReload' | 'cssHmr'>>>;
+export interface NsDevSessionDescriptor {
+    sessionId: string;
+    origin: string;
+    entryUrl: string;
+    clientUrl: string;
+    wsUrl: string;
+    platform: NsDevPlatform;
+    runtimeConfigUrl?: string;
+    hostModules?: NsHostModuleId[];
+    features?: NsDevFeatureFlags;
+}
+export interface NsRuntimeImportMap {
+    imports: Record<string, string>;
+}
+/**
+ * The URL vocabulary the runtime's canonical-key function applies when
+ * keying its module registry. The *mechanism* (fragment strip, cache-buster
+ * param drop, param sort) is native because it runs inside the engine's
+ * synchronous resolve walk; this vocabulary is server policy and lives here,
+ * next to the server code that defines the routes it names.
+ */
+export interface NsRuntimeCanonicalizationConfig {
+    /** Query param names that are pure cache busters and are dropped for dev endpoints (e.g. `t`, `v`, `import`). */
+    stripParams?: string[];
+    /** Path prefixes (StartsWith) identifying dev endpoints whose query may be normalized (e.g. `/ns/`, `/@id/`). */
+    forPathPrefixes?: string[];
+    /** Path substrings whose query IS the module identity and must be preserved verbatim (e.g. `/@ng/component`). */
+    preserveQueryFor?: string[];
+}
+export interface NsRuntimeConfigurePayload {
+    importMap: NsRuntimeImportMap;
+    volatilePatterns?: string[];
+    canonicalization?: NsRuntimeCanonicalizationConfig;
+}
+/**
+ * The native dev-host contract — mechanism only. The runtime exposes its
+ * mechanism primitives as the `ns:module` builtin module (reachable via
+ * `require("ns:module")`, `import ... from "ns:module"` and
+ * `import("ns:module")` — see the iOS runtime's docs/ns-builtin-modules.md);
+ * every policy concern (boot orchestration, import.meta.hot, full reload,
+ * CSS apply, worker teardown, WebSocket protocol) lives in JS inside
+ * @nativescript/vite. Worker teardown in particular is fully userland: the
+ * session bootstrap intercepts the global `Worker` constructor and the
+ * client sweeps tracked instances before framework reboots
+ * (`worker.terminate()` cascades to nested workers natively).
+ *
+ * Every member is optional: a non-dev environment (or a test) may expose
+ * none or only some of them, and callers degrade gracefully. Missing
+ * members are absent — never present-but-throwing — so feature checks work.
+ */
+export interface NsRuntimeDevHostApi {
+    /** `configureLoader` — import map + volatile URL patterns + canonicalization vocabulary for the sync resolver. */
+    configureLoader?: (config: NsRuntimeConfigurePayload) => void;
+    /** `invalidateModules` — registry eviction + bust-next-fetch nonce. */
+    invalidateModules?: (urls: string[]) => void;
+    /** `getLoadedModuleUrls` — registry introspection for JS-driven full reload. */
+    getLoadedModuleUrls?: () => string[];
+    /** `createRequire` — a CommonJS `require` resolving against a local file path or `file:` URL. */
+    createRequire?: (filenameOrURL: string | URL) => (specifier: string) => unknown;
+    /** `createPumpingRequire` — like `createRequire`, but settles top-level-await graphs by pumping V8 tasks; boot-only options. */
+    createPumpingRequire?: (filenameOrURL: string | URL, options?: {
+        deadlineSeconds?: number;
+        onTimeout?: 'throw' | 'return-pending';
+        pumpRunLoop?: boolean;
+    }) => (specifier: string) => unknown;
+    /**
+     * `setDevBootComplete` — flips the native cold-boot gate. Only runtimes that
+     * let the client arm that gate expose it; current runtimes scope the gate
+     * to entry evaluation natively and omit the member.
+     */
+    setDevBootComplete?: (value?: boolean) => void;
+}
+export declare function isNsDevPlatform(value: unknown): value is NsDevPlatform;
+export declare function assertNsDevSessionDescriptor(session: unknown): asserts session is NsDevSessionDescriptor;
+/**
+ * Resolve the dev host API from the `ns:module` builtin module via the
+ * runtime's global CJS `require` (installed on the global object by
+ * ModuleInternal). Always read through this function rather than requiring
+ * the builtin directly so every consumer resolves the contract identically —
+ * and degrades to an empty surface off-device (tests, non-NativeScript
+ * environments, runtimes without the builtin).
+ */
+export declare function readNsRuntimeDevHostApi(target?: Partial<typeof globalThis>): NsRuntimeDevHostApi;
+export {};

package/hmr/shared/runtime/browser-runtime-contract.js

@@ -0,0 +1,66 @@
+export const NS_HOST_RUNTIME_MODULE_ID = 'ns-host://runtime';
+export const NS_HOST_STYLE_ADAPTER_MODULE_ID = 'ns-host://style-adapter';
+export const NS_DEFAULT_HOST_MODULES = [NS_HOST_RUNTIME_MODULE_ID, NS_HOST_STYLE_ADAPTER_MODULE_ID];
+export const NS_DEV_SESSION_REQUIRED_FIELDS = ['sessionId', 'origin', 'entryUrl', 'clientUrl', 'wsUrl', 'platform'];
+export const NS_DEFAULT_DEV_FEATURE_FLAGS = {
+    fullReload: true,
+    cssHmr: true,
+};
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+export function isNsDevPlatform(value) {
+    return value === 'ios' || value === 'android' || value === 'visionos';
+}
+export function assertNsDevSessionDescriptor(session) {
+    if (!session || typeof session !== 'object') {
+        throw new Error('Invalid NativeScript dev session descriptor');
+    }
+    const candidate = session;
+    for (const key of NS_DEV_SESSION_REQUIRED_FIELDS) {
+        if (!isNonEmptyString(candidate[key])) {
+            throw new Error(`Missing dev session field: ${key}`);
+        }
+    }
+    if (!isNsDevPlatform(candidate.platform)) {
+        throw new Error(`Invalid dev session platform: ${String(candidate.platform)}`);
+    }
+    if (candidate.hostModules != null) {
+        if (!Array.isArray(candidate.hostModules) || candidate.hostModules.some((value) => !isNonEmptyString(value) || !String(value).startsWith('ns-host://'))) {
+            throw new Error('Invalid dev session hostModules');
+        }
+    }
+    if (candidate.runtimeConfigUrl != null && !isNonEmptyString(candidate.runtimeConfigUrl)) {
+        throw new Error('Invalid dev session runtimeConfigUrl');
+    }
+    if (candidate.features != null) {
+        if (typeof candidate.features !== 'object') {
+            throw new Error('Invalid dev session features');
+        }
+    }
+}
+/**
+ * Resolve the dev host API from the `ns:module` builtin module via the
+ * runtime's global CJS `require` (installed on the global object by
+ * ModuleInternal). Always read through this function rather than requiring
+ * the builtin directly so every consumer resolves the contract identically —
+ * and degrades to an empty surface off-device (tests, non-NativeScript
+ * environments, runtimes without the builtin).
+ */
+export function readNsRuntimeDevHostApi(target = globalThis) {
+    const requireFn = target.require;
+    if (typeof requireFn !== 'function') {
+        return {};
+    }
+    try {
+        const api = requireFn('ns:module');
+        return api && typeof api === 'object' ? api : {};
+    }
+    catch {
+        // No such built-in module — a runtime predating ns:module or a
+        // host whose require doesn't know the scheme.
+        return {};
+    }
+}
+export {};
+//# sourceMappingURL=browser-runtime-contract.js.map

package/hmr/shared/runtime/browser-runtime-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-runtime-contract.js","sourceRoot":"","sources":["../../../../../../packages/vite/hmr/shared/runtime/browser-runtime-contract.ts"],"names":[],"mappings":"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"}

package/hmr/shared/runtime/dev-overlay-ios.d.ts

@@ -0,0 +1,87 @@
+/**
+ * iOS UIWindow overlay backend. The live/connection/update overlay is
+ * promoted to its own UIWindow (above `UIWindowLevelAlert`) so the dev
+ * surface never gets obscured by modals, bottom sheets, or any other window
+ * presented by the host app. Falls back to null (→ in-tree backend) on
+ * Android, web, tests, or when scene/window construction fails.
+ *
+ * The layout math (`computeIosOverlayLayout`, `computeIosOverlayWindowLevel`)
+ * is pure and deterministic so the rules stay unit-testable without booting a
+ * simulator — see `dev-overlay.spec.ts`.
+ */
+import { type HmrOverlayPosition, type HmrOverlaySnapshot } from './dev-overlay-snapshots.js';
+import { type HmrOverlayRuntimeState, type IosOverlayRefs } from './dev-overlay-shared.js';
+/**
+ * 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 declare function computeIosOverlayWindowLevel(baseAlert?: number | null): number;
+export type IosSafeInsets = {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+};
+export type IosRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type IosOverlayLayout = {
+    backdrop: IosRect;
+    panel: IosRect;
+    title: IosRect;
+    status: IosRect;
+};
+/**
+ * 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, 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 declare function computeIosOverlayLayout(input: {
+    viewWidth: number;
+    viewHeight: number;
+    safeInsets?: IosSafeInsets | null;
+    titleHeight: number;
+    statusHeight: number;
+    maxPanelWidth?: number;
+    horizontalMargin?: number;
+    panelPadding?: number;
+    interLabelSpacing?: number;
+    minTopInset?: number;
+    position?: HmrOverlayPosition;
+    toastVerticalInset?: number;
+}): IosOverlayLayout;
+type IosOverlayHost = {
+    UIWindow: any;
+    UIViewController: any;
+    UIView: any;
+    UILabel: any;
+    UIColor: any;
+    UIFont: any;
+    UIApplication: any;
+    UIScreen: any;
+    UIWindowLevelAlert?: number;
+};
+/**
+ * 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.
+ */
+export declare function getIosOverlayHost(): IosOverlayHost | null;
+export declare function ensureIosOverlayRefs(state: HmrOverlayRuntimeState): IosOverlayRefs | null;
+export declare function applySnapshotToIosRefs(refs: IosOverlayRefs | null, snapshot: HmrOverlaySnapshot): boolean;
+export {};