@nativescript/vite 8.0.0-alpha.2 → 8.0.0-alpha.20

package/helpers/dev-host.js

@@ -0,0 +1,491 @@
+/**
+ * Canonical resolver for the Vite dev-server origin that a NativeScript
+ * device or simulator can actually reach.
+ *
+ * Why this exists. The Vite dev server commonly binds to `0.0.0.0`
+ * (the wildcard "all interfaces" address) so both the host browser and
+ * a sibling mobile device can hit it. That bind address is fine for
+ * the LISTENING socket — but it is NOT a routable hostname:
+ *
+ *   - iOS Simulator shares the host's network stack, so `localhost` /
+ *     `127.0.0.1` work from inside the simulator and even `0.0.0.0`
+ *     sometimes resolves there. The simulator path is forgiving.
+ *
+ *   - Android Emulator runs inside a virtual NIC with NAT (QEMU
+ *     `slirp`). `0.0.0.0` and `localhost` / `127.0.0.1` refer to the
+ *     EMULATOR ITSELF, not the development host. Two routable paths
+ *     exist:
+ *
+ *       (a) `adb reverse tcp:<port> tcp:<port>` — multiplexes the
+ *           device-side `127.0.0.1:<port>` over the existing ADB
+ *           transport to the host. This is the PREFERRED path: slirp
+ *           is famously flaky under burst-connect load and drops
+ *           ~80% of cold-boot module-loader fetches with
+ *           `IOException: unexpected end of stream`. The ADB tunnel
+ *           bypasses slirp entirely and is reliable. We try this
+ *           automatically — see `tryEnableAdbReverse`. We emit the
+ *           IPv4 literal `127.0.0.1` instead of `localhost` because
+ *           Android API 36+ system images periodically ship without
+ *           a `localhost` mapping in the resolver, and
+ *           `UnknownHostException` fires before adb-reverse can do
+ *           its job.
+ *
+ *       (b) `10.0.2.2` (Genymotion: `10.0.3.2`) — slirp's host alias.
+ *           Used as a fallback when ADB isn't available or the user
+ *           opted out via `NS_HMR_NO_ADB_REVERSE=1`. Works, just less
+ *           reliable than the ADB tunnel.
+ *
+ *   - Physical Android devices over USB get the same automatic
+ *     `adb reverse` treatment as emulators. Over Wi-Fi (no ADB
+ *     tunnel), the user must opt out of adb reverse via
+ *     `NS_HMR_NO_ADB_REVERSE=1` and supply a routable host via
+ *     `NS_HMR_HOST=<ip>` or `NS_HMR_PREFER_LAN_HOST=1`.
+ *
+ * Without this normalization, `bundle.mjs` ships with statically
+ * embedded URLs like `http://0.0.0.0:5173/ns/core/xhr` and the very
+ * first dynamic import during Application boot fails with
+ * `status=0 (network unreachable)` on Android, killing the runtime
+ * before any user code runs.
+ *
+ * Resolution rules (highest precedence first):
+ *
+ *   1. `process.env.NS_HMR_HOST` — always wins. CI, tunneled setups,
+ *      and remote devices use this to point at a known-good origin.
+ *
+ *   2. A concrete non-wildcard, non-loopback `host` arg — trust the
+ *      developer's explicit choice (`server.host: '192.168.1.42'`
+ *      already routes from any device on the LAN).
+ *
+ *   3. `process.env.NS_HMR_PREFER_LAN_HOST` truthy AND a LAN NIC is
+ *      detected — emit the LAN IP. Opt-in for physical-device-over-
+ *      Wi-Fi dev. Also disables the adb-reverse path below so the
+ *      caller actually gets LAN routing.
+ *
+ *   4. Wildcard bind (`0.0.0.0`, `::`, `true`, empty) OR Android
+ *      loopback — emit the platform-appropriate routable address.
+ *      For Android, we first try `adb reverse tcp:<port> tcp:<port>`
+ *      and emit `127.0.0.1` on success (bypasses slirp NAT entirely
+ *      and avoids Android API 36+'s missing-`localhost`-from-resolver
+ *      bug); on failure we fall back to `10.0.2.2`. iOS/visionOS get
+ *      `localhost` directly. iOS/visionOS loopback passes through
+ *      unchanged.
+ *
+ * Every dev-mode emitter that bakes a URL into `bundle.mjs` or sends
+ * one to a device-side fetch site MUST run through this helper so the
+ * device receives a single canonical, reachable origin.
+ */
+import os from 'node:os';
+import { execSync as nodeExecSync } from 'node:child_process';
+const WILDCARD_HOSTS = new Set(['0.0.0.0', '::', '', 'true']);
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1']);
+const adbReverseCache = new Map();
+/**
+ * Returns the first non-internal IPv4 address on the host machine, or
+ * `undefined` if no LAN NIC is up. Pure wrapper around
+ * `os.networkInterfaces()` so callers and tests can stub it cleanly.
+ */
+export function guessLanHost() {
+    try {
+        const nets = os.networkInterfaces();
+        for (const name of Object.keys(nets)) {
+            const addrs = nets[name] || [];
+            for (const addr of addrs) {
+                if (!addr)
+                    continue;
+                // Node typings vary across versions; keep checks defensive.
+                const family = addr.family;
+                const internal = !!addr.internal;
+                const address = String(addr.address || '');
+                if (internal)
+                    continue;
+                if (family !== 'IPv4' && family !== 4)
+                    continue;
+                if (address && address !== '127.0.0.1')
+                    return address;
+            }
+        }
+    }
+    catch { }
+    return undefined;
+}
+function normalizeHostInput(host) {
+    if (host === true)
+        return '0.0.0.0';
+    if (host === false || host == null)
+        return '';
+    const s = String(host).trim();
+    return s;
+}
+/**
+ * Whether the given host string is a wildcard "all interfaces" bind
+ * address rather than a routable hostname. `host` may be the literal
+ * string from a Vite config (`'0.0.0.0'`), an empty string, or `'true'`
+ * (some older Vite/CLI surfaces stringify the boolean).
+ */
+export function isWildcardHost(host) {
+    return WILDCARD_HOSTS.has(host);
+}
+/**
+ * Whether the given host string is loopback. On Android the loopback
+ * address is the device itself, NOT the development host — so callers
+ * must remap it for Android consumers.
+ */
+export function isLoopbackHost(host) {
+    return LOOPBACK_HOSTS.has(host);
+}
+function isTruthyEnvFlag(value) {
+    if (typeof value !== 'string')
+        return false;
+    const v = value.trim().toLowerCase();
+    if (!v)
+        return false;
+    return v !== '0' && v !== 'false' && v !== 'off' && v !== 'no';
+}
+/**
+ * Read-only view of the current `adb reverse` status for a given
+ * dev-server port. Returns `undefined` if `tryEnableAdbReverse` has
+ * never been called for that port.
+ */
+export function getAdbReverseStatus(port) {
+    return adbReverseCache.get(port);
+}
+/**
+ * Test hook — clears the per-port cache so unit tests can exercise
+ * fresh "first call" behavior without leaking state between cases.
+ * NOT exported from the package barrel; spec files import via the
+ * file path directly.
+ */
+export function __resetAdbReverseCacheForTests() {
+    adbReverseCache.clear();
+}
+/**
+ * Try to set up `adb reverse tcp:<port> tcp:<port>` for every
+ * connected Android device / emulator so device-side `localhost:port`
+ * routes through the ADB transport to the host's dev server.
+ *
+ * Why this beats `10.0.2.2`. The Android emulator's stock NAT is
+ * QEMU's `slirp` user-mode network stack, which is well-known to
+ * drop bursts of concurrent TCP setups to the host. In practice this
+ * surfaces as ~80% of synchronous module-loader fetches failing with
+ * `IOException: unexpected end of stream` — the connection establishes,
+ * the request goes out, and then slirp drops the response before
+ * okhttp can read the status line. The failures are random per-module
+ * across runs, retries help but don't eliminate them, and the symptom
+ * masquerades as a server-side bug.
+ *
+ * `adb reverse` bypasses the emulator NIC entirely — the device-side
+ * connection is multiplexed over the existing ADB USB / TCP channel
+ * to the host. It's the same mechanism React Native, Expo, and
+ * Flutter use for Android dev, and it works for both emulators and
+ * USB-connected physical devices.
+ *
+ * Caching. The result is cached per-port so repeat callers don't
+ * fork extra subprocesses. The cache is keyed on port (not platform)
+ * because the wildcard "Android-ness" of the call is already implied
+ * by the caller — only Android consumers hit this path.
+ *
+ * Failure modes (all surface as a cached `succeeded: false`):
+ *   - `NS_HMR_NO_ADB_REVERSE=1` — explicit opt-out for unusual
+ *     setups (e.g. Wi-Fi-connected device with no ADB tunnel, CI
+ *     containers without ADB installed).
+ *   - `adb` not on PATH — common in fresh dev machines that have
+ *     the Android SDK installed but no shell init.
+ *   - No connected devices — user started Vite before booting the
+ *     emulator. We do NOT keep retrying after the first failure
+ *     because the URL is baked into bundle.mjs at config-load time
+ *     and there's no point in flipping it later.
+ *   - "more than one device" — fatal for unqualified `adb reverse`,
+ *     so we enumerate via `adb devices` and apply the reverse
+ *     individually with `-s <serial>`. As long as at least one
+ *     device gets the mapping we treat the whole call as a success.
+ */
+export function tryEnableAdbReverse(opts) {
+    const cached = adbReverseCache.get(opts.port);
+    if (cached)
+        return cached;
+    const env = opts.env || process.env;
+    // Test-safety guard. When we're running inside vitest / jest /
+    // any other test runner AND the caller did NOT inject an explicit
+    // exec stub, refuse to spawn a real `adb` subprocess. Spec files
+    // that pass `env: {}` aren't expecting us to mutate the dev's real
+    // device state (set up an actual `adb reverse` mapping on
+    // `port:5173` they didn't ask for) just by exercising the host
+    // resolver. We DO NOT cache this skip — a subsequent call with a
+    // real `exec` stub from the same suite should still run.
+    const ambient = process.env;
+    const inTestRunner = ambient.VITEST === 'true' || ambient.NODE_ENV === 'test' || typeof ambient.JEST_WORKER_ID === 'string';
+    if (!opts.exec && inTestRunner) {
+        return { attempted: false, succeeded: false, devices: [], error: 'test environment (auto-skip)' };
+    }
+    const exec = opts.exec || ((cmd, o) => nodeExecSync(cmd, { timeout: o.timeout, stdio: ['ignore', 'pipe', 'pipe'] }).toString());
+    if (isTruthyEnvFlag(env.NS_HMR_NO_ADB_REVERSE)) {
+        const status = { attempted: false, succeeded: false, devices: [], error: 'opt-out via NS_HMR_NO_ADB_REVERSE' };
+        adbReverseCache.set(opts.port, status);
+        return status;
+    }
+    // First enumerate. We need this to (a) bail cleanly when there's
+    // no device at all and (b) handle the multi-device case which
+    // makes unqualified `adb reverse` ambiguous and refuse the call.
+    let devices = [];
+    try {
+        const raw = exec('adb devices', { timeout: 5000 });
+        devices = parseAdbDevicesOutput(raw);
+    }
+    catch (err) {
+        const status = {
+            attempted: true,
+            succeeded: false,
+            devices: [],
+            error: `adb not available: ${String(err?.message || err)}`,
+        };
+        adbReverseCache.set(opts.port, status);
+        return status;
+    }
+    if (devices.length === 0) {
+        const status = {
+            attempted: true,
+            succeeded: false,
+            devices: [],
+            error: 'no connected Android devices',
+        };
+        adbReverseCache.set(opts.port, status);
+        try {
+            console.warn(`[NativeScript] adb reverse skipped — no Android devices connected yet. Bundle URLs will use 10.0.2.2 (emulator NAT). For best reliability boot the emulator BEFORE \`ns run android\` so adb reverse can wire 127.0.0.1:${opts.port} through ADB instead.`);
+        }
+        catch { }
+        return status;
+    }
+    // Apply per-device so multi-device setups don't hit the "more
+    // than one device" failure. We tolerate per-device failures so
+    // long as at least one mapping landed — the user's target device
+    // is almost always the first connected one.
+    const successes = [];
+    const errors = [];
+    for (const serial of devices) {
+        try {
+            exec(`adb -s ${serial} reverse tcp:${opts.port} tcp:${opts.port}`, { timeout: 5000 });
+            successes.push(serial);
+        }
+        catch (err) {
+            errors.push(`${serial}: ${String(err?.message || err)}`);
+        }
+    }
+    const status = {
+        attempted: true,
+        succeeded: successes.length > 0,
+        devices: successes,
+        error: successes.length === 0 ? errors.join('; ') || 'all devices failed' : undefined,
+    };
+    adbReverseCache.set(opts.port, status);
+    // One-line user-facing receipt so the dev knows why bundle.mjs
+    // suddenly switched from `10.0.2.2` to `localhost`. We only log
+    // outside test runners (covered above) so spec output stays
+    // clean.
+    try {
+        if (status.succeeded) {
+            console.log(`[NativeScript] adb reverse tcp:${opts.port} tcp:${opts.port} → ${successes.join(', ')} (Android device-side 127.0.0.1:${opts.port} now tunnels to host — bypasses emulator NAT)`);
+        }
+        else if (errors.length > 0) {
+            console.warn(`[NativeScript] adb reverse failed for tcp:${opts.port} — falling back to 10.0.2.2 (slirp NAT). Module fetches may hit IOException: unexpected end of stream under load. Reasons: ${status.error}`);
+        }
+    }
+    catch {
+        // Logging is best-effort. We never want a console misbehavior
+        // to take down dev-server boot.
+    }
+    return status;
+}
+/**
+ * Parse the line-oriented output of `adb devices`:
+ *
+ *   List of devices attached
+ *   emulator-5554\tdevice
+ *   ABCDEF12\tdevice
+ *   somemodel\tunauthorized
+ *
+ * We keep only entries whose second column is exactly `device`
+ * (skip `unauthorized`, `offline`, `recovery`, etc. — none of those
+ * can accept an `adb reverse` command).
+ */
+function parseAdbDevicesOutput(raw) {
+    const out = [];
+    const lines = String(raw || '').split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (trimmed.startsWith('List of devices'))
+            continue;
+        if (trimmed.startsWith('*'))
+            continue; // daemon startup chatter
+        const parts = trimmed.split(/\s+/);
+        if (parts.length < 2)
+            continue;
+        if (parts[1] !== 'device')
+            continue;
+        out.push(parts[0]);
+    }
+    return out;
+}
+/**
+ * Pick the host string a device or simulator can actually reach.
+ *
+ * See the file-level comment for the full resolution-precedence
+ * narrative. Returns the chosen host alongside a `source` tag so
+ * callers (and logs) can explain why a given URL was emitted.
+ */
+export function resolveDeviceReachableHost(opts) {
+    const env = opts.env || process.env;
+    const lanHostResolver = opts.lanHostResolver || guessLanHost;
+    // 1. Explicit env override always wins.
+    const envOverride = env.NS_HMR_HOST;
+    if (typeof envOverride === 'string' && envOverride.length > 0) {
+        return { host: envOverride, source: 'env' };
+    }
+    const raw = normalizeHostInput(opts.host);
+    // 2. Explicit non-wildcard, non-loopback host — trust the developer.
+    //    Loopback addresses on Android still need remapping (see step 4),
+    //    so we only short-circuit here for the truly routable case.
+    if (raw && !isWildcardHost(raw) && !isLoopbackHost(raw)) {
+        return { host: raw, source: 'explicit' };
+    }
+    // 3. Physical-device opt-in. The Android emulator default below
+    //    (`10.0.2.2`) doesn't reach a real device on the LAN, so users
+    //    running on hardware set `NS_HMR_PREFER_LAN_HOST=1` to pick up
+    //    the host's LAN IP at build time. iOS/visionOS rarely needs
+    //    this (the simulator stays on the loopback path) but the same
+    //    opt-in works on those platforms for parity.
+    //
+    //    `NS_HMR_PREFER_LAN_HOST` ALSO suppresses the adb-reverse path
+    //    below — when the user has explicitly asked for LAN routing
+    //    we don't want to silently bypass them with an ADB tunnel.
+    if (isTruthyEnvFlag(env.NS_HMR_PREFER_LAN_HOST)) {
+        const lan = lanHostResolver();
+        if (lan) {
+            return { host: lan, source: 'lan' };
+        }
+        // Fall through to the platform default when no LAN NIC was
+        // detected (e.g. running in a CI container) — better to fail
+        // at the always-works fallback than emit nothing.
+    }
+    // 4. Wildcard bind — fall back to the platform-appropriate routable
+    //    address. We DELIBERATELY do NOT auto-pick a LAN IP here on
+    //    Android: standard emulator NAT drops packets destined for the
+    //    host's LAN IP, even when those IPs resolve fine from the
+    //    host's own browser. `10.0.2.2` is the next-best fallback when
+    //    adb reverse isn't available; otherwise the emulator slirp NAT
+    //    drops a meaningful fraction of TCP setups under burst load and
+    //    cold-boot hits `IOException: unexpected end of stream` for
+    //    random modules each run.
+    if (isWildcardHost(raw)) {
+        return platformDefault(opts);
+    }
+    // 5. Loopback. iOS / visionOS keeps `localhost` (simulator network
+    //    stack reaches the host); Android remaps to `10.0.2.2` /
+    //    `localhost`-via-adb-reverse (loopback on Android refers to
+    //    the EMULATOR ITSELF, not the host).
+    if (isLoopbackHost(raw)) {
+        if (opts.platform === 'android') {
+            return platformDefault(opts);
+        }
+        return { host: raw, source: 'explicit' };
+    }
+    // 6. Empty / unrecognised — fall back to platform default.
+    return platformDefault(opts);
+}
+function platformDefault(opts) {
+    if (opts.platform === 'android') {
+        // Try to bring up an `adb reverse` tunnel first. When that
+        // succeeds, `localhost` on the device routes through the
+        // existing ADB channel to the host's dev server — which
+        // sidesteps the QEMU slirp NAT entirely (see
+        // `tryEnableAdbReverse` for why that matters). When adb is
+        // unavailable, the device is disconnected, or the user opted
+        // out via `NS_HMR_NO_ADB_REVERSE`, we fall through to
+        // `10.0.2.2` so the cold boot still has *some* working path.
+        //
+        // We only attempt adb reverse when we know the port — without
+        // it we can't issue a valid `adb reverse` command. Older
+        // fixtures that call `resolveDeviceReachableHost` without a
+        // port still get the legacy `10.0.2.2` answer.
+        if (typeof opts.port === 'number' && Number.isFinite(opts.port)) {
+            const status = tryEnableAdbReverse({ port: opts.port, env: opts.env, exec: opts.adbExec });
+            if (status.succeeded) {
+                // Emit `127.0.0.1` (IPv4 literal) instead of `localhost`.
+                // Android API 36+ system images periodically ship without
+                // a `localhost` entry in the resolver's `/etc/hosts`, so
+                // `getaddrinfo("localhost")` throws
+                // `UnknownHostException: No address associated with
+                // hostname` BEFORE the TCP connect even starts. The IPv4
+                // literal bypasses DNS entirely and ADB reverse intercepts
+                // loopback traffic regardless of how it's spelled. This is
+                // the same workaround React Native, Expo, and Chrome
+                // DevTools port forwarding all use.
+                return { host: '127.0.0.1', source: 'adb-reverse' };
+            }
+        }
+        // Stock Android emulator host alias. Physical devices that
+        // can't use `adb reverse` need NS_HMR_HOST=<LAN IP> or
+        // NS_HMR_PREFER_LAN_HOST=1.
+        return { host: '10.0.2.2', source: 'platform-default' };
+    }
+    return { host: 'localhost', source: 'platform-default' };
+}
+/**
+ * Convenience wrapper that returns the full `protocol://host:port`
+ * origin string alongside the host-resolution metadata. The vast
+ * majority of callers want the assembled origin to splice into a
+ * `/ns/...` URL, so this saves them the trivial template string.
+ *
+ * When the resolved host already includes a `:port` suffix (a common
+ * shape for `NS_HMR_HOST=tunnel.example.com:5173`), we split it back
+ * out so the assembled origin never doubles up the port.
+ */
+export function resolveDeviceReachableOrigin(opts) {
+    const protocol = opts.protocol === 'https' ? 'https' : 'http';
+    const requestedPort = typeof opts.port === 'number' && Number.isFinite(opts.port) ? opts.port : 5173;
+    // Forward the resolved port to the host resolver so the Android
+    // `platformDefault` step can attempt `adb reverse` for the same
+    // port the dev server is actually listening on.
+    const { host: rawHost, source } = resolveDeviceReachableHost({ ...opts, port: requestedPort });
+    const { host, port } = splitHostAndPort(rawHost, requestedPort);
+    return {
+        host,
+        source,
+        protocol,
+        port,
+        origin: `${protocol}://${host}:${port}`,
+    };
+}
+function splitHostAndPort(rawHost, fallbackPort) {
+    // Bracketed IPv6 — `[::1]:5173` — keep the brackets on the host so
+    // callers can splice it straight into a URL without re-escaping.
+    if (rawHost.startsWith('[')) {
+        const closing = rawHost.indexOf(']');
+        if (closing !== -1) {
+            const bracketed = rawHost.slice(0, closing + 1);
+            const rest = rawHost.slice(closing + 1);
+            if (rest.startsWith(':')) {
+                const parsed = Number(rest.slice(1));
+                if (Number.isFinite(parsed) && parsed > 0) {
+                    return { host: bracketed, port: parsed };
+                }
+            }
+            return { host: bracketed, port: fallbackPort };
+        }
+    }
+    // `host:port` for IPv4 / DNS names. We deliberately do NOT split on
+    // the first colon when more than one is present (that would
+    // misinterpret an unbracketed IPv6 literal), and we leave the host
+    // alone if the trailing segment isn't a positive integer.
+    const colonCount = (rawHost.match(/:/g) || []).length;
+    if (colonCount === 1) {
+        const idx = rawHost.indexOf(':');
+        const candidatePort = Number(rawHost.slice(idx + 1));
+        if (Number.isFinite(candidatePort) && candidatePort > 0) {
+            return { host: rawHost.slice(0, idx), port: candidatePort };
+        }
+    }
+    return { host: rawHost, port: fallbackPort };
+}
+//# sourceMappingURL=dev-host.js.map

package/helpers/dev-host.js.map

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

package/helpers/global-defines.d.ts

@@ -1,3 +1,50 @@
+/**
+ * Opt-out flag for the HMR-applying progress overlay.
+ *
+ * Default: enabled. Set `NS_VITE_PROGRESS_OVERLAY=0` (or `false`) in
+ * the environment to suppress the overlay if a developer finds it
+ * distracting. We accept the same falsy spellings webpack-era tooling
+ * used (`0`, `false`, `off`, `no`) and treat anything else as
+ * enabled-by-default; this avoids surprising users who pass quoted
+ * truthy strings ("1", "true").
+ */
+export declare function isHmrProgressOverlayEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Kickstart-eligibility threshold for the parallel HMR prefetch
+ * (`__nsKickstartHmrPrefetch`).
+ *
+ * Why a threshold exists. The kickstart fetches the SERVER-computed
+ * inverse-dep closure (`evictPaths`) in parallel before V8 starts
+ * its module walk, which is a clean win when the closure size is
+ * close to what V8 will actually re-evaluate on the next import. For
+ * a typical Angular component edit (`*.component.ts` / `.html`) the
+ * closure contains ~5–30 modules and almost all of them sit on the
+ * live forward path from the entry, so fan-out beats sequential
+ * `HttpFetchText` calls by 3–5×.
+ *
+ * The picture inverts for `.ts` files with deep inverse-dep fan-in
+ * (constants files, design-system enums, shared utilities). The
+ * server faithfully reports the entire inverse closure (often
+ * 100–300 importers), but V8's forward walk on re-import only
+ * re-evaluates the ~20–30 modules that sit on the currently-rendered
+ * route's path. The kickstart's parallel wave then over-fetches the
+ * other ~70–270 importers — and Vite's single-threaded transform
+ * pipeline cannot keep up with 16-way concurrent demand, so each
+ * fetch's tail latency balloons. Net result: a "should-be-200ms"
+ * HMR cycle becomes 6+ seconds.
+ *
+ * The threshold short-circuits the kickstart when `evictPaths.length`
+ * exceeds the configured cap. The HMR cycle still completes
+ * correctly — V8 falls back to per-module synchronous fetches.
+ *
+ * Default: 32. Empirically chosen so component-shaped closures
+ * (typically 5–30) keep the kickstart speed-up while wide-fan-in
+ * leaf edits (typically 100+) skip it. Override with
+ * `NS_VITE_KICKSTART_MAX_URLS=N` (any non-negative integer) — `0`
+ * disables the kickstart entirely; `Infinity` removes the cap.
+ */
+export declare const HMR_KICKSTART_DEFAULT_MAX_URLS = 32;
+export declare function resolveHmrKickstartMaxUrls(env?: NodeJS.ProcessEnv): number;
 export declare function getGlobalDefines(opts: {
     platform: string;
     targetMode: string;
@@ -9,11 +56,15 @@ export declare function getGlobalDefines(opts: {
     __IOS__: string;
     __VISIONOS__: string;
     __APPLE__: string;
+    'global.isAndroid': string;
+    'global.isIOS': string;
     __DEV__: string;
     __COMMONJS__: boolean;
     __NS_WEBPACK__: boolean;
     __NS_ENV_VERBOSE__: string;
     __NS_TARGET_FLAVOR__: string;
+    __NS_HMR_PROGRESS_OVERLAY_ENABLED__: string;
+    __NS_HMR_KICKSTART_MAX_URLS__: string;
     __CSS_PARSER__: string;
     __UI_USE_XML_PARSER__: boolean;
     __UI_USE_EXTERNAL_RENDERER__: boolean;

package/helpers/global-defines.js

@@ -1,6 +1,71 @@
 import { getProjectAppPath, getProjectAppVirtualPath } from './utils.js';
 const APP_ROOT_DIR = getProjectAppPath();
 const APP_ROOT_VIRTUAL = getProjectAppVirtualPath();
+/**
+ * Opt-out flag for the HMR-applying progress overlay.
+ *
+ * Default: enabled. Set `NS_VITE_PROGRESS_OVERLAY=0` (or `false`) in
+ * the environment to suppress the overlay if a developer finds it
+ * distracting. We accept the same falsy spellings webpack-era tooling
+ * used (`0`, `false`, `off`, `no`) and treat anything else as
+ * enabled-by-default; this avoids surprising users who pass quoted
+ * truthy strings ("1", "true").
+ */
+export function isHmrProgressOverlayEnabled(env = process.env) {
+    const raw = (env.NS_VITE_PROGRESS_OVERLAY ?? '').toString().trim().toLowerCase();
+    if (!raw)
+        return true;
+    return !['0', 'false', 'off', 'no'].includes(raw);
+}
+/**
+ * Kickstart-eligibility threshold for the parallel HMR prefetch
+ * (`__nsKickstartHmrPrefetch`).
+ *
+ * Why a threshold exists. The kickstart fetches the SERVER-computed
+ * inverse-dep closure (`evictPaths`) in parallel before V8 starts
+ * its module walk, which is a clean win when the closure size is
+ * close to what V8 will actually re-evaluate on the next import. For
+ * a typical Angular component edit (`*.component.ts` / `.html`) the
+ * closure contains ~5–30 modules and almost all of them sit on the
+ * live forward path from the entry, so fan-out beats sequential
+ * `HttpFetchText` calls by 3–5×.
+ *
+ * The picture inverts for `.ts` files with deep inverse-dep fan-in
+ * (constants files, design-system enums, shared utilities). The
+ * server faithfully reports the entire inverse closure (often
+ * 100–300 importers), but V8's forward walk on re-import only
+ * re-evaluates the ~20–30 modules that sit on the currently-rendered
+ * route's path. The kickstart's parallel wave then over-fetches the
+ * other ~70–270 importers — and Vite's single-threaded transform
+ * pipeline cannot keep up with 16-way concurrent demand, so each
+ * fetch's tail latency balloons. Net result: a "should-be-200ms"
+ * HMR cycle becomes 6+ seconds.
+ *
+ * The threshold short-circuits the kickstart when `evictPaths.length`
+ * exceeds the configured cap. The HMR cycle still completes
+ * correctly — V8 falls back to per-module synchronous fetches.
+ *
+ * Default: 32. Empirically chosen so component-shaped closures
+ * (typically 5–30) keep the kickstart speed-up while wide-fan-in
+ * leaf edits (typically 100+) skip it. Override with
+ * `NS_VITE_KICKSTART_MAX_URLS=N` (any non-negative integer) — `0`
+ * disables the kickstart entirely; `Infinity` removes the cap.
+ */
+export const HMR_KICKSTART_DEFAULT_MAX_URLS = 32;
+export function resolveHmrKickstartMaxUrls(env = process.env) {
+    const raw = (env.NS_VITE_KICKSTART_MAX_URLS ?? '').toString().trim();
+    if (!raw)
+        return HMR_KICKSTART_DEFAULT_MAX_URLS;
+    const lower = raw.toLowerCase();
+    if (lower === 'infinity' || lower === 'unlimited' || lower === 'none') {
+        return Number.POSITIVE_INFINITY;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        return HMR_KICKSTART_DEFAULT_MAX_URLS;
+    }
+    return Math.floor(parsed);
+}
 export function getGlobalDefines(opts) {
     return {
         // Define platform flags for runtime checks
@@ -8,11 +73,23 @@ export function getGlobalDefines(opts) {
         __IOS__: JSON.stringify(opts.platform === 'ios'),
         __VISIONOS__: JSON.stringify(opts.platform === 'visionos'),
         __APPLE__: JSON.stringify(opts.platform === 'ios' || opts.platform === 'visionos'),
+        'global.isAndroid': JSON.stringify(opts.platform === 'android'),
+        'global.isIOS': JSON.stringify(opts.platform === 'ios' || opts.platform === 'visionos'),
         __DEV__: JSON.stringify(opts.targetMode === 'development'),
         __COMMONJS__: false,
         __NS_WEBPACK__: false,
         __NS_ENV_VERBOSE__: JSON.stringify(opts.verbose),
         __NS_TARGET_FLAVOR__: JSON.stringify(opts.flavor),
+        // whether to show the HMR in-progress overlay.
+        __NS_HMR_PROGRESS_OVERLAY_ENABLED__: JSON.stringify(isHmrProgressOverlayEnabled()),
+        // Eviction-set size cap for the parallel HMR kickstart.
+        // `JSON.stringify(Number.POSITIVE_INFINITY)` is the string
+        // "null", so we serialize Infinity ourselves to keep the
+        // build-time literal readable in source maps.
+        __NS_HMR_KICKSTART_MAX_URLS__: (() => {
+            const n = resolveHmrKickstartMaxUrls();
+            return Number.isFinite(n) ? String(n) : 'Infinity';
+        })(),
         __CSS_PARSER__: JSON.stringify('css-tree'),
         __UI_USE_XML_PARSER__: true,
         __UI_USE_EXTERNAL_RENDERER__: false,