@nativescript/vite 8.0.0-alpha.3 → 8.0.0-alpha.30

package/helpers/bundler-context.js

@@ -0,0 +1,71 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+/** Recursively collect every file under `dir` (posix paths), tolerating unreadable entries. */
+export function walkAppFiles(dir, out = []) {
+    let entries = [];
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        const full = path.posix.join(dir, entry);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            walkAppFiles(full, out);
+        else
+            out.push(full);
+    }
+    return out;
+}
+/** Skip partials (`_`-prefixed), `.d.ts`, worker modules, and platform-mismatched files. */
+export function shouldExcludePlatformFile(p, platform) {
+    const file = p.split('/').pop() || '';
+    if (file.startsWith('_'))
+        return true;
+    if (/\.d\.ts$/.test(p))
+        return true;
+    if (/([.-]worker)\.(ts|js)$/.test(file))
+        return true;
+    const isAndroidTagged = /\.android\./.test(p);
+    const isIosTagged = /\.ios\./.test(p) || /\.visionos\./.test(p);
+    if (platform === 'android' && isIosTagged)
+        return true;
+    if ((platform === 'ios' || platform === 'visionos') && isAndroidTagged)
+        return true;
+    return false;
+}
+/** Absolute app path → root-anchored import specifier the dev server can serve. */
+export function toContextImportSpecifier(abs) {
+    return '/' + abs.replace(/^\/+/, '');
+}
+/** Loads `.xml` files as default-exported strings (shared by the JS and TS configs). */
+export function createXmlLoaderPlugin(name) {
+    return {
+        name,
+        enforce: 'pre',
+        load(id) {
+            if (!id.endsWith('.xml'))
+                return null;
+            try {
+                const src = readFileSync(id, 'utf-8');
+                const xml = JSON.stringify(src)
+                    .replace(/\u2028/g, '\\u2028')
+                    .replace(/\u2029/g, '\\u2029');
+                const code = `const ___XML___ = ${xml};\nexport default ___XML___;`;
+                return { code, map: null };
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=bundler-context.js.map

package/helpers/bundler-context.js.map

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

package/helpers/config-as-json.js

@@ -27,6 +27,16 @@ export default function nsConfigAsJsonPlugin() {
         // 3. After Rollup has generated all chunks, emit a package.json asset
         //    into the output directory (dist/ by default)
         generateBundle(_options, _bundle) {
+            // Lazy-init in case no module in the graph imported '~/package.json'
+            // this build. (Under HMR with @nativescript/core external, the
+            // `~/package.json` import that lived inside core's graph is gone, so
+            // `load()` never fires. Without this guard, `configObject` is
+            // undefined, `JSON.stringify` returns undefined, and rolldown's
+            // emitFile rejects it with "Missing field `inner` on
+            // BindingEmittedAsset.source".)
+            if (!configObject) {
+                configObject = nsConfigToJson();
+            }
             const json = JSON.stringify(configObject, null, 2);
             this.emitFile({
                 type: 'asset',

package/helpers/config-as-json.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-as-json.js","sourceRoot":"","sources":["../../../../packages/vite/helpers/config-as-json.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,iBAAiB,GAAG,wBAAwB,CAAC;AAEnD,MAAM,CAAC,OAAO,UAAU,oBAAoB;IAC3C,sCAAsC;IACtC,IAAI,YAAiC,CAAC;IAEtC,OAAO;QACN,IAAI,EAAE,yBAAyB;QAE/B,2CAA2C;QAC3C,SAAS,CAAC,MAAM;YACf,IAAI,MAAM,KAAK,gBAAgB,EAAE,CAAC;gBACjC,OAAO,iBAAiB,CAAC;YAC1B,CAAC;YACD,OAAO,IAAI,CAAC;QACb,CAAC;QAED,kDAAkD;QAClD,IAAI,CAAC,EAAE;YACN,IAAI,EAAE,KAAK,iBAAiB,EAAE,CAAC;gBAC9B,YAAY,GAAG,cAAc,EAAE,CAAC;gBAEhC,+DAA+D;gBAC/D,OAAO;oBACN,IAAI,EAAE,kBAAkB,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG;oBACvD,UAAU,EAAE,IAAI;iBAChB,CAAC;YACH,CAAC;YACD,OAAO,IAAI,CAAC;QACb,CAAC;QAED,sEAAsE;QACtE,kDAAkD;QAClD,cAAc,CAAC,QAAQ,EAAE,OAAO;YAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YACnD,IAAI,CAAC,QAAQ,CAAC;gBACb,IAAI,EAAE,OAAO;gBACb,QAAQ,EAAE,cAAc;gBACxB,MAAM,EAAE,IAAI;aACZ,CAAC,CAAC;QACJ,CAAC;KACD,CAAC;AACH,CAAC"}
+{"version":3,"file":"config-as-json.js","sourceRoot":"","sources":["../../../../packages/vite/helpers/config-as-json.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,iBAAiB,GAAG,wBAAwB,CAAC;AAEnD,MAAM,CAAC,OAAO,UAAU,oBAAoB;IAC3C,sCAAsC;IACtC,IAAI,YAAiC,CAAC;IAEtC,OAAO;QACN,IAAI,EAAE,yBAAyB;QAE/B,2CAA2C;QAC3C,SAAS,CAAC,MAAM;YACf,IAAI,MAAM,KAAK,gBAAgB,EAAE,CAAC;gBACjC,OAAO,iBAAiB,CAAC;YAC1B,CAAC;YACD,OAAO,IAAI,CAAC;QACb,CAAC;QAED,kDAAkD;QAClD,IAAI,CAAC,EAAE;YACN,IAAI,EAAE,KAAK,iBAAiB,EAAE,CAAC;gBAC9B,YAAY,GAAG,cAAc,EAAE,CAAC;gBAEhC,+DAA+D;gBAC/D,OAAO;oBACN,IAAI,EAAE,kBAAkB,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG;oBACvD,UAAU,EAAE,IAAI;iBAChB,CAAC;YACH,CAAC;YACD,OAAO,IAAI,CAAC;QACb,CAAC;QAED,sEAAsE;QACtE,kDAAkD;QAClD,cAAc,CAAC,QAAQ,EAAE,OAAO;YAC/B,qEAAqE;YACrE,+DAA+D;YAC/D,qEAAqE;YACrE,8DAA8D;YAC9D,gEAAgE;YAChE,qDAAqD;YACrD,gCAAgC;YAChC,IAAI,CAAC,YAAY,EAAE,CAAC;gBACnB,YAAY,GAAG,cAAc,EAAE,CAAC;YACjC,CAAC;YACD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YACnD,IAAI,CAAC,QAAQ,CAAC;gBACb,IAAI,EAAE,OAAO;gBACb,QAAQ,EAAE,cAAc;gBACxB,MAAM,EAAE,IAAI;aACZ,CAAC,CAAC;QACJ,CAAC;KACD,CAAC;AACH,CAAC"}

package/helpers/dev-host.d.ts

@@ -0,0 +1,341 @@
+/**
+ * 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 type { Platform } from './platform-types.js';
+export type DevHostPlatform = Platform;
+/**
+ * Per-port cache of `adb reverse` setup attempts. Keyed by port so
+ * dev servers that switch ports across restarts get a clean attempt
+ * each time. The cache is required because every entry point that
+ * embeds a device-reachable URL (the bundle.mjs boot path, the
+ * `/ns/core/*` external resolver, the websocket URL emitter, the
+ * served-module rewriter) hits `resolveDeviceReachable*` — if we
+ * spawned `adb reverse` on every call we'd fork ~half a dozen
+ * subprocesses per Vite startup and the cold-boot would slow
+ * noticeably.
+ *
+ * The cache also gives us a stable answer across all consumers: once
+ * the first caller learns that adb reverse is available, every later
+ * caller in the same process gets the same `localhost`/`10.0.2.2`
+ * decision. URL identity is what keeps the iOS HTTP ESM realm from
+ * splitting and what keeps the Android HMR client and bundle.mjs
+ * pointing at the same origin.
+ */
+interface AdbReverseStatus {
+    attempted: boolean;
+    succeeded: boolean;
+    error?: string;
+    /** Device serials that successfully received the reverse mapping. */
+    devices: string[];
+    /**
+     * Set when the mapping was established by the NativeScript CLI (it
+     * exported `NS_ADB_REVERSE_READY=1`) rather than by this plugin.
+     * In that case the plugin never spawned `adb` at all — it simply
+     * trusts that `127.0.0.1:<port>` already tunnels to the host. See
+     * the CLI-handoff note in `tryEnableAdbReverse`.
+     */
+    viaCli?: boolean;
+}
+/**
+ * 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 declare function guessLanHost(): string | undefined;
+/**
+ * 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 declare function isWildcardHost(host: string): boolean;
+/**
+ * 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 declare function isLoopbackHost(host: string): boolean;
+export interface DeviceHostResolution {
+    /** Final host string baked into the device-side URL. */
+    host: string;
+    /**
+     * How the value was chosen. `'env'` / `'explicit'` mean the result
+     * is locked-in; `'lan'`, `'adb-reverse'`, and `'platform-default'`
+     * are fallbacks selected by this helper.
+     */
+    source: 'env' | 'explicit' | 'lan' | 'adb-reverse' | 'platform-default';
+}
+export interface ResolveDeviceHostOptions {
+    /** The raw host value from the Vite config (`server.host`). */
+    host?: unknown;
+    /** Target device platform. Drives the loopback / wildcard fallback. */
+    platform: DevHostPlatform;
+    /**
+     * Override for `process.env`. Tests pass a fixture object; runtime
+     * callers omit this and pick up the ambient process environment.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Override for `guessLanHost()`. Tests stub a fixed return value;
+     * runtime callers omit this and the helper hits real NICs.
+     */
+    lanHostResolver?: () => string | undefined;
+    /**
+     * Dev-server port. When set AND `platform === 'android'`, this
+     * helper will lazily attempt `adb reverse tcp:<port> tcp:<port>`
+     * on first call and, if it succeeds, emit `localhost` instead of
+     * `10.0.2.2`. See `tryEnableAdbReverse` for the full rationale.
+     *
+     * Optional for backwards compatibility — callers that already have
+     * the port (which is everyone except a couple of legacy test
+     * fixtures) should pass it so Android emulator users get the
+     * reliable ADB tunnel path instead of QEMU slirp's flaky NAT.
+     */
+    port?: number;
+    /**
+     * Test seam for the adb-reverse subprocess. When passed, this
+     * helper uses the injected exec function instead of spawning
+     * `child_process.execFileSync`. Runtime callers omit this and pick
+     * up the SDK-resolved adb binary (see `resolveAdbPath`).
+     */
+    adbExec?: AdbExec;
+}
+/**
+ * Subprocess shim used by `tryEnableAdbReverse`. Production code
+ * routes through `child_process.execFileSync` — argv form, NO
+ * `/bin/sh -c` wrapper. That matters for two reasons:
+ *
+ *   1. On timeout, `execFileSync` signals the actual `adb` child
+ *      directly. The old `execSync('adb …')` form spawned a shell
+ *      that spawned adb; killing the shell on timeout ORPHANED the
+ *      adb grandchild, and a half-handshaked orphan can wedge the
+ *      adb daemon out from under the CLI's device tracker.
+ *
+ *   2. No shell means no quoting / `$PATH` surprises — we invoke an
+ *      absolute, SDK-resolved adb binary (see `resolveAdbPath`) with
+ *      a literal argv.
+ *
+ * Tests stub this so the suite can exercise success / failure /
+ * "multiple devices" / "no ADB" paths without touching a real
+ * Android emulator. The shim receives the resolved adb path and the
+ * argv array (e.g. `['-s', 'emulator-5554', 'reverse', …]`).
+ */
+export type AdbExec = (adbPath: string, args: string[], opts: {
+    timeout: number;
+}) => string;
+/**
+ * Resolve the `adb` executable the way the Android SDK tooling does,
+ * so the plugin and the NativeScript CLI drive the *same* adb client.
+ *
+ * Why this is load-bearing. A bare `adb` from `$PATH` is frequently a
+ * DIFFERENT version than the one the CLI resolves from the SDK. When
+ * two adb *clients* of differing versions talk to the one global adb
+ * server (port 5037), the newer client prints
+ * `adb server version (NN) doesn't match this client (MM); killing...`
+ * and restarts the daemon — severing the CLI's `track-devices` stream
+ * and hanging it at "Searching for devices…" forever. Resolving the
+ * exact SDK adb eliminates that mismatch.
+ *
+ * Precedence:
+ *   1. `NS_ADB_PATH` — the CLI exports the absolute path to the adb it
+ *      itself uses. Always wins so the two processes are byte-identical.
+ *   2. `$ANDROID_HOME/platform-tools/adb` (+ `.exe` on Windows).
+ *   3. `$ANDROID_SDK_ROOT/platform-tools/adb`.
+ *   4. Bare `adb` — last-resort PATH lookup (kept only so a machine
+ *      with adb on PATH but no SDK env still limps along).
+ *
+ * Candidates from (2)/(3) are existence-checked; a stale env var that
+ * points at a missing binary falls through rather than guaranteeing a
+ * spawn failure.
+ */
+export declare function resolveAdbPath(env?: NodeJS.ProcessEnv): string;
+export interface TryEnableAdbReverseOptions {
+    /** Port to forward on both sides of the ADB bridge. */
+    port: number;
+    /** Override for `process.env`; tests pass a fixture object. */
+    env?: NodeJS.ProcessEnv;
+    /** Test seam — see `AdbExec`. */
+    exec?: AdbExec;
+}
+/**
+ * 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 declare function getAdbReverseStatus(port: number): AdbReverseStatus | undefined;
+/**
+ * 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 declare function __resetAdbReverseCacheForTests(): void;
+/**
+ * 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.
+ *
+ * CLI handoff (the preferred path). When the NativeScript CLI drives
+ * the run it already owns device discovery, install, and launch — it
+ * knows the exact target serial and exactly when the device is ready.
+ * In that mode the CLI performs the `adb reverse` itself, with its own
+ * SDK-resolved adb, AFTER the device is up, and exports
+ * `NS_ADB_REVERSE_READY=1`. Seeing that flag, this function returns a
+ * synthetic success WITHOUT spawning adb at all — removing the second,
+ * racing adb owner that used to collide with the CLI's device search
+ * during cold start. `NS_DEVICE_SERIAL` (the CLI's deploy target) and
+ * `NS_ADB_PATH` (the CLI's adb) are honored in the self-managed
+ * fallback below for setups where the CLI did NOT pre-wire the reverse.
+ *
+ * Self-managed hardening (fallback). When `NS_ADB_REVERSE_READY` is
+ * absent we still set the mapping ourselves, but defensively:
+ *   - resolve adb from the SDK (`resolveAdbPath`) — never a bare PATH
+ *     `adb` that could version-mismatch and kill the CLI's daemon;
+ *   - `adb start-server` once up front so a cold daemon is owned by a
+ *     single, version-matched client before anything else touches it;
+ *   - argv `execFileSync` (no shell) with a child-killing timeout so a
+ *     hung adb is reaped rather than orphaned;
+ *   - `wait-for-device` per serial so we don't issue `reverse` against
+ *     an emulator whose `adbd` hasn't finished coming up.
+ *
+ * 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 resolvable / not runnable.
+ *   - 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 target each serial individually with `-s <serial>`. As
+ *     long as at least one device gets the mapping we treat the whole
+ *     call as a success.
+ */
+export declare function tryEnableAdbReverse(opts: TryEnableAdbReverseOptions): AdbReverseStatus;
+/**
+ * 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 declare function resolveDeviceReachableHost(opts: ResolveDeviceHostOptions): DeviceHostResolution;
+export interface ResolveDeviceOriginOptions extends ResolveDeviceHostOptions {
+    /** Wire protocol; usually 'http' unless `server.https` is set. */
+    protocol?: 'http' | 'https';
+    /** Server port; defaults to 5173 to match the Vite dev default. */
+    port?: number;
+}
+export interface DeviceOriginResolution extends DeviceHostResolution {
+    /** Fully assembled `protocol://host:port` string. */
+    origin: string;
+    protocol: 'http' | 'https';
+    port: number;
+}
+/**
+ * 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 declare function resolveDeviceReachableOrigin(opts: ResolveDeviceOriginOptions): DeviceOriginResolution;
+export {};