devframe 0.8.2 → 0.9.0-beta.1

package/dist/{devframe-mQ4qZAuo.d.mts → devframe-Bdd9YXTy.d.mts}

@@ -1,9 +1,8 @@
+import { d as RpcFunctionsCollectorBase } from "./index-DSCq4M4q.mjs";
 import { _ as RpcFunctionDefinition, v as RpcFunctionDefinitionAny } from "./types-CnJSgRVa.mjs";
-import { w as RpcFunctionsCollectorBase } from "./index-Dbw1p5ch.mjs";
-import { n as DevframeNodeRpcSessionMeta } from "./ws-server-uKQcClcJ.mjs";
+import { d as DevframeRpcConnection, u as DevframeNodeRpcSessionMeta } from "./ws-server-Ces08fjP.mjs";
 import { CAC } from "cac";
 import { StandardSchemaV1 } from "@standard-schema/spec";
-import { Peer } from "crossws";
 import { BirpcReturn } from "birpc";
 import { Diagnostic, DiagnosticDefinition, defineDiagnostics } from "nostics";
 //#region src/adapters/flags.d.ts
@@ -852,7 +851,7 @@ interface RpcStreamingHost {
   /**
    * Adapters call this when a session disconnects so the host can drop
    * subscribers and abort orphaned streams. Most users do not need this;
-   * it's wired by `startHttpAndWs` automatically.
+   * it's wired by the RPC server binding automatically.
    *
    * @internal
    */
@@ -948,7 +947,7 @@ interface DevframeHost {
    * base, so a devframe SPA mounted there can discover the RPC/WS endpoint
    * via `connectDevframe()`'s relative `./__connection.json` fetch.
    *
-   * Called by `mountDevframe` for each mounted devframe (alongside
+   * Called by `ctx.install` for each mounted devframe (alongside
    * `mountStatic`). Without it, an embedded SPA can only discover the
    * endpoint by inheriting it from a same-origin parent window — which fails
    * for cross-origin or sandboxed iframes. Implementations serve the same
@@ -1344,8 +1343,8 @@ interface DevframeNodeContext {
  */
 interface ConnectionMetaWebsocket {
   /**
-   * Path to the WS endpoint. Relative paths (the default, e.g. `__devframe_ws`) are
-   * resolved against `__connection.json`'s location; absolute paths (`/__devframe_ws`)
+   * Path to the WS endpoint. Relative paths (the default, e.g. `__ws`) are
+   * resolved against `__connection.json`'s location; absolute paths (`/__ws`)
    * resolve against the page origin.
    */
   path?: string;
@@ -1354,8 +1353,32 @@ interface ConnectionMetaWebsocket {
   /** Override the host (`hostname[:port]`). Use for a fully cross-origin endpoint. */
   host?: string;
 }
+/**
+ * Object form of {@link ConnectionMeta.sse} — the same proxy-safe shape and
+ * resolution rules as {@link ConnectionMetaWebsocket}, producing an
+ * `http(s)://` endpoint instead of a `ws(s)://` one. Set `port` (and/or
+ * `host`) only when the SSE endpoint genuinely lives on a different origin
+ * than the page, e.g. a side-car server on its own port.
+ */
+interface ConnectionMetaSse {
+  /**
+   * Path to the SSE endpoint. Relative paths (the default, e.g. `__sse`)
+   * are resolved against `__connection.json`'s location; absolute paths
+   * (`/__sse`) resolve against the page origin.
+   */
+  path?: string;
+  /** Override the port. Combined with the page hostname unless `host` is set. */
+  port?: number;
+  /** Override the host (`hostname[:port]`). Use for a fully cross-origin endpoint. */
+  host?: string;
+}
 interface ConnectionMeta {
-  backend: 'websocket' | 'static';
+  /**
+   * The server's primary live-RPC transport (`websocket` / `sse`), `static`
+   * for a pre-computed RPC dump with no live server, or `none` for a server
+   * exposing no RPC transport at all (e.g. an MCP-only deployment).
+   */
+  backend: 'websocket' | 'sse' | 'static' | 'none';
   /**
    * WebSocket endpoint, resolved by the client into a `ws(s)://` URL:
    *
@@ -1366,6 +1389,17 @@ interface ConnectionMeta {
    *     URL with its protocol swapped, or a path resolved same-origin.
    */
   websocket?: number | string | ConnectionMetaWebsocket;
+  /**
+   * SSE endpoint (`GET` opens the event stream, `POST` carries RPC calls),
+   * resolved by the client into an `http(s)://` URL with the same
+   * proxy-safe rules as {@link ConnectionMeta.websocket}:
+   *
+   *   - {@link ConnectionMetaSse} — the proxy-flexible default; a
+   *     same-origin path relative to `__connection.json`.
+   *   - `string` — a full `http(s)://` URL used verbatim, or a path
+   *     resolved same-origin.
+   */
+  sse?: string | ConnectionMetaSse;
   /**
    * Present when the dev server exposes a route-based MCP endpoint
    * (`cli.mcp`). Advertises the MCP Streamable-HTTP route so in-browser
@@ -1442,7 +1476,7 @@ type PartialWithoutId<T extends {
  * the handshake RPC functions, the resolver gate, the connect-time trust
  * hook, and the startup banner.
  *
- * `startHttpAndWs` accepts one of these directly via its `auth` option —
+ * `initDevframe` / `initHub` accept one of these directly via their `auth` option —
  * see {@link https://devfra.me | devframe}'s server docs — or a host can
  * wire the four pieces itself against a lower-level transport.
  */
@@ -1461,12 +1495,12 @@ interface DevframeAuthHandler {
    */
   authorize: (methodName: string, session: DevframeNodeRpcSession) => boolean;
   /**
-   * Connect-time trust: reads a bearer token off the peer's upgrade request
-   * (an `Authorization: Bearer <token>` header, or a static/pre-shared
-   * token from `clientAuthTokens`) and, when valid, marks the session
+   * Connect-time trust: reads a bearer token off the connection's initial
+   * request (a static/pre-shared token from `clientAuthTokens`, or a token
+   * minted by the code exchange) and, when valid, marks the session
    * trusted immediately — before the client's own handshake call.
    */
-  onConnect: (peer: Peer, session: DevframeNodeRpcSession) => void;
+  onConnect: (connection: DevframeRpcConnection, session: DevframeNodeRpcSession) => void;
   /**
    * Print the current one-time code and its magic-link URL. Devframe stays
    * headless — call this yourself once the server is listening. Safe to
@@ -1512,7 +1546,7 @@ type DevframeDuplicationStrategy = 'warn' | 'silent' | 'throw' | 'duplicate';
  *
  *   1. **Same server, different route** (default) — leave `port`/`url` unset.
  *      The socket shares the HTTP server's port and binds to `route`
- *      (`__devframe_ws`). The client connects to its own origin, so the link
+ *      (`__ws`). The client connects to its own origin, so the link
  *      survives a reverse proxy that rewrites the host/port/subpath.
  *
  *   2. **Different port** — set `port`. The socket binds on its own port on the
@@ -1524,20 +1558,43 @@ type DevframeDuplicationStrategy = 'warn' | 'silent' | 'throw' | 'duplicate';
 interface DevframeWsOptions {
   /**
    * Upgrade route segment the socket binds to and is advertised at, relative
-   * to the SPA base. Default: `__devframe_ws`.
+   * to the SPA base. Default: `__ws`.
    */
   route?: string;
   /**
    * Bind the socket on its own port instead of sharing the HTTP port. The
-   * browser connects to this port on the page's hostname.
+   * browser connects to this port on the page's hostname. Implies
+   * {@link DevframeWsOptions.sidecar}.
    */
   port?: number;
+  /**
+   * Start a side-car WebSocket server on a free port, for hosts whose request
+   * handlers can't accept upgrades (Next.js route handlers, Nitro, Rsbuild).
+   * The resolved port is advertised in `__connection.json`, so the browser
+   * finds it without any further wiring. Set `port` instead to pin it.
+   */
+  sidecar?: boolean;
   /**
    * Advertise a fixed, fully-qualified endpoint on another origin (a full
    * `ws://`/`wss://` URL). Takes precedence over `port`/`route` in the meta.
    */
   url?: string;
 }
+/**
+ * Controls the SSE RPC endpoint — the WebSocket-free transport for hosts
+ * and proxies where the upgrade isn't available. It rides whatever HTTP
+ * surface serves the instance (the same one serving `__connection.json`),
+ * so a relative `route` always resolves; there is no port plumbing of its
+ * own. Enabled by default alongside the WebSocket; pass `sse: false` to
+ * disable, or `ws: false` to run SSE-only (`backend: 'sse'`).
+ */
+interface DevframeSseOptions {
+  /**
+   * Route segment the SSE endpoint binds to and is advertised at, relative
+   * to the SPA base. Default: `__sse`.
+   */
+  route?: string;
+}
 /**
  * Configuration for the route-based MCP server mounted alongside the dev
  * server (opt-in via {@link DevframeCliOptions.mcp}). The endpoint speaks
@@ -1599,7 +1656,7 @@ interface DevframeCliOptions {
    *     The `--no-auth` CLI flag maps here for one-off runs.
    *   - A {@link DevframeAuthHandler} — a custom handler (e.g. a tuned
    *     `createInteractiveAuth`, or an entirely different scheme) passed
-   *     straight through to `startHttpAndWs`.
+   *     straight through to the RPC transport binding.
    *
    * Hosted adapters (`vite`, `embedded`) ignore this and defer to the host's
    * auth; `@vitejs/devtools` honors the equivalent `devtools.clientAuth`.
@@ -1627,10 +1684,17 @@ interface DevframeCliOptions {
   distDir?: string;
   /**
    * How the browser reaches the RPC WebSocket. Defaults to sharing the HTTP
-   * port on the `__devframe_ws` route. See {@link DevframeWsOptions} for the
-   * different-port and remote-origin variants.
+   * port on the `__ws` route. See {@link DevframeWsOptions} for the
+   * different-port and remote-origin variants. Pass `false` to serve no
+   * WebSocket at all — clients connect over SSE instead (`backend: 'sse'`).
+   */
+  ws?: DevframeWsOptions | false;
+  /**
+   * How the browser reaches the SSE RPC endpoint — enabled by default
+   * alongside the WebSocket as the more portable transport. Pass `false`
+   * to disable, or a {@link DevframeSseOptions} to change its route.
    */
-  ws?: DevframeWsOptions;
+  sse?: boolean | DevframeSseOptions;
   /**
    * Capability-side CAC hook. Called with the CAC instance after the
    * adapter registers its built-in commands (`build` / `spa` / `mcp`)
@@ -1669,7 +1733,7 @@ interface DevframeCliOptions {
 /**
  * Default dock attributes for the iframe entry a hub synthesizes when it
  * mounts this devframe. Framework-neutral metadata only — the hub layer
- * (`mountDevframe`) merges these beneath its per-mount `dock` overrides,
+ * (`ctx.install`) merges these beneath its per-mount `dock` overrides,
  * which in turn sit beneath the locked, derived `id` / `type` / `url`.
  *
  * Every field is optional. `title` / `icon` default to the definition's
@@ -1753,7 +1817,7 @@ interface DevframeDefinition {
   };
   /**
    * Default dock attributes applied when a hub mounts this devframe as an
-   * iframe dock entry. Consulted only by hub adapters (`mountDevframe`),
+   * iframe dock entry. Consulted only by the hub install path (`ctx.install`),
    * which merge these beneath the per-mount `dock` overrides; standalone
    * adapters (`cli` / `spa` / `build`) ignore it.
    *
@@ -1769,7 +1833,7 @@ interface DevframeDefinition {
   /**
    * How a hub reacts when another devframe sharing this one's `id` is
    * mounted onto the same hub. Consulted only by hub adapters
-   * (`mountDevframe`); standalone adapters (`cli` / `spa` / `build`)
+   * (`ctx.install`); standalone adapters (`cli` / `spa` / `build`)
    * ignore it.
    *
    * @default 'warn'
@@ -1797,6 +1861,5 @@ interface DevframeDefinition {
   cli?: DevframeCliOptions;
   spa?: DevframeSpaOptions;
 }
-declare function defineDevframe(d: DevframeDefinition): DevframeDefinition;
 //#endregion
-export { DevframeRpcServerFunctions as $, DevframeSettingsStore as A, DevframeAgentHostEvents as At, DevframeDefineDiagnosticsOptions as B, DevframeServicesHost as C, AgentResourceContent as Ct, DevframeScopedStreamingHost as D, AgentToolProvider as Dt, DevframeScopedNodeRpc as E, AgentToolInput as Et, ScopedSharedStates as F, InferCliFlags as Ft, RpcBroadcastOptions as G, DevframeDiagnosticsHost as H, SettingsForNamespace as I, defineCliFlags as It, RpcSharedStateHost as J, RpcFunctionsHost as K, DevframeViewHost as L, parseCliFlags as Lt, ScopedClientFunctions as M, EventUnsubscribe as Mt, ScopedRpcFn as N, EventsMap as Nt, DevframeSettings as O, AgentToolProviderHandle as Ot, ScopedServerFunctions as P, CliFlagsSchema as Pt, DevframeRpcClientFunctions as Q, DevframeHost as R, DevframeServiceOf as S, AgentResource as St, DevframeScopedNodeContext as T, AgentTool as Tt, DevframeDiagnosticsLogger as U, DevframeDiagnosticsDefinition as V, DevframeNodeRpcSession as W, RpcStreamingChannelOptions as X, RpcStreamingChannel as Y, RpcStreamingHost as Z, ConnectionMeta as _, SharedStateOptions as _t, DevframeDockDefaults as a, StreamReader as at, DevframeNodeContext as b, AgentHandle as bt, DevframeSetupInfo as c, createStreamReader as ct, McpRouteOptions as d, ImmutableArray as dt, DevframeRpcSharedStates as et, defineDevframe as f, ImmutableMap as ft, Thenable as g, SharedStateEvents as gt, PartialWithoutId as h, SharedState as ht, DevframeDeploymentKind as i, StreamErrorPayload as it, ScopedBroadcastOptions as j, EventEmitter as jt, DevframeSettingsRegistry as k, DevframeAgentHost as kt, DevframeSpaOptions as l, createStreamSink as lt, EntriesToObject as m, ImmutableSet as mt, DevframeCliOptions as n, CreateStreamReaderOptions as nt, DevframeDuplicationStrategy as o, StreamSink as ot, DevframeAuthHandler as p, ImmutableObject as pt, RpcSharedStateGetOptions as q, DevframeDefinition as r, CreateStreamSinkOptions as rt, DevframeRuntime as s, StreamSinkEvents as st, DevframeBrowserContext as t, BufferedChunk as tt, DevframeWsOptions as u, Immutable as ut, ConnectionMetaWebsocket as v, SharedStatePatch as vt, DevframeServicesRegistry as w, AgentResourceInput as wt, DevframeServiceId as x, AgentManifest as xt, DevframeCapabilities as y, createSharedState as yt, DevframeStorageScope as z };
+export { DevframeRpcClientFunctions as $, DevframeSettingsRegistry as A, DevframeAgentHost as At, DevframeStorageScope as B, DevframeServiceOf as C, AgentResource as Ct, DevframeScopedNodeRpc as D, AgentToolInput as Dt, DevframeScopedNodeContext as E, AgentTool as Et, ScopedServerFunctions as F, CliFlagsSchema as Ft, DevframeNodeRpcSession as G, DevframeDiagnosticsDefinition as H, ScopedSharedStates as I, InferCliFlags as It, RpcSharedStateGetOptions as J, RpcBroadcastOptions as K, SettingsForNamespace as L, defineCliFlags as Lt, ScopedBroadcastOptions as M, EventEmitter as Mt, ScopedClientFunctions as N, EventUnsubscribe as Nt, DevframeScopedStreamingHost as O, AgentToolProvider as Ot, ScopedRpcFn as P, EventsMap as Pt, RpcStreamingHost as Q, DevframeViewHost as R, parseCliFlags as Rt, DevframeServiceId as S, AgentManifest as St, DevframeServicesRegistry as T, AgentResourceInput as Tt, DevframeDiagnosticsHost as U, DevframeDefineDiagnosticsOptions as V, DevframeDiagnosticsLogger as W, RpcStreamingChannel as X, RpcSharedStateHost as Y, RpcStreamingChannelOptions as Z, ConnectionMeta as _, SharedStateEvents as _t, DevframeDockDefaults as a, StreamErrorPayload as at, DevframeCapabilities as b, createSharedState as bt, DevframeSetupInfo as c, StreamSinkEvents as ct, DevframeWsOptions as d, Immutable as dt, DevframeRpcServerFunctions as et, McpRouteOptions as f, ImmutableArray as ft, Thenable as g, SharedState as gt, PartialWithoutId as h, ImmutableSet as ht, DevframeDeploymentKind as i, CreateStreamSinkOptions as it, DevframeSettingsStore as j, DevframeAgentHostEvents as jt, DevframeSettings as k, AgentToolProviderHandle as kt, DevframeSpaOptions as l, createStreamReader as lt, EntriesToObject as m, ImmutableObject as mt, DevframeCliOptions as n, BufferedChunk as nt, DevframeDuplicationStrategy as o, StreamReader as ot, DevframeAuthHandler as p, ImmutableMap as pt, RpcFunctionsHost as q, DevframeDefinition as r, CreateStreamReaderOptions as rt, DevframeRuntime as s, StreamSink as st, DevframeBrowserContext as t, DevframeRpcSharedStates as tt, DevframeSseOptions as u, createStreamSink as ut, ConnectionMetaSse as v, SharedStateOptions as vt, DevframeServicesHost as w, AgentResourceContent as wt, DevframeNodeContext as x, AgentHandle as xt, ConnectionMetaWebsocket as y, SharedStatePatch as yt, DevframeHost as z };

package/dist/{diagnostics-D7wM2cwM.mjs → diagnostics-DLYH5oD3.mjs}

@@ -91,6 +91,22 @@ const diagnostics = defineDiagnostics({
 		DF0052: {
 			why: (p) => `Failed to listen on ${p.host}:${p.port}: ${p.reason}`,
 			fix: "The port is likely already taken by another process (often a previous devframe instance). Free it, or pick another via `--port`, `cli.port` / `cli.portRange` on the definition, or `devMiddleware.port` on `viteDevBridge`. The original node error is available as `error.cause`."
+		},
+		DF0054: {
+			why: (p) => `connectionMeta() was called before initDevframe("${p.id}") finished initializing.`,
+			fix: "Await `instance.ready` (or any request through `instance.handler`) before reading `connectionMeta()` — the WebSocket binding it describes is only known once initialization completes."
+		},
+		DF0055: {
+			why: (p) => `This instance already owns its WebSocket transport (${p.tier}), so it cannot take over the host's upgrade events.`,
+			fix: "Drop `handleUpgrade`/`attach` and let the configured transport serve the socket, or remove `server` / `ws.port` / `ws.sidecar` from the options so the instance leaves the binding to you."
+		},
+		DF0056: {
+			why: (p) => `This instance advertises an external WebSocket endpoint (${p.url}), so it serves no socket of its own.`,
+			fix: "The server behind `ws.url` owns the transport (and its auth). Drop `ws.url` to have the instance serve the socket, or pair it with `server` / `ws.port` / `ws.sidecar` for the tunnel pattern, where a local binding is advertised through the relay."
+		},
+		DF0057: {
+			why: () => "This instance disables its WebSocket transport (`ws: false`), so there is no socket to drive upgrades into.",
+			fix: "Clients connect over the SSE endpoint instead — no upgrade wiring is needed. Remove `ws: false` if the instance should serve a WebSocket after all."
 		}
 	}
 });

package/dist/dist-D8jAMwxU.mjs

@@ -0,0 +1,227 @@
+import { n as __exportAll } from "./rolldown-runtime-JspESFgx.mjs";
+import { createServer } from "node:net";
+import { networkInterfaces } from "node:os";
+//#region ../../node_modules/.pnpm/get-port-please@3.2.0/node_modules/get-port-please/dist/index.mjs
+var dist_exports = /* @__PURE__ */ __exportAll({
+	checkPort: () => checkPort,
+	getPort: () => getPort,
+	getRandomPort: () => getRandomPort,
+	isSafePort: () => isSafePort,
+	isUnsafePort: () => isUnsafePort
+});
+const unsafePorts = /* @__PURE__ */ new Set([
+	1,
+	7,
+	9,
+	11,
+	13,
+	15,
+	17,
+	19,
+	20,
+	21,
+	22,
+	23,
+	25,
+	37,
+	42,
+	43,
+	53,
+	69,
+	77,
+	79,
+	87,
+	95,
+	101,
+	102,
+	103,
+	104,
+	109,
+	110,
+	111,
+	113,
+	115,
+	117,
+	119,
+	123,
+	135,
+	137,
+	139,
+	143,
+	161,
+	179,
+	389,
+	427,
+	465,
+	512,
+	513,
+	514,
+	515,
+	526,
+	530,
+	531,
+	532,
+	540,
+	548,
+	554,
+	556,
+	563,
+	587,
+	601,
+	636,
+	989,
+	990,
+	993,
+	995,
+	1719,
+	1720,
+	1723,
+	2049,
+	3659,
+	4045,
+	5060,
+	5061,
+	6e3,
+	6566,
+	6665,
+	6666,
+	6667,
+	6668,
+	6669,
+	6697,
+	10080
+]);
+function isUnsafePort(port) {
+	return unsafePorts.has(port);
+}
+function isSafePort(port) {
+	return !isUnsafePort(port);
+}
+var GetPortError = class extends Error {
+	constructor(message, opts) {
+		super(message, opts);
+		this.message = message;
+	}
+	name = "GetPortError";
+};
+function _log(verbose, message) {
+	if (verbose) console.log(`[get-port] ${message}`);
+}
+function _generateRange(from, to) {
+	if (to < from) return [];
+	const r = [];
+	for (let index = from; index <= to; index++) r.push(index);
+	return r;
+}
+function _tryPort(port, host) {
+	return new Promise((resolve) => {
+		const server = createServer();
+		server.unref();
+		server.on("error", () => {
+			resolve(false);
+		});
+		server.listen({
+			port,
+			host
+		}, () => {
+			const { port: port2 } = server.address();
+			server.close(() => {
+				resolve(isSafePort(port2) && port2);
+			});
+		});
+	});
+}
+function _getLocalHosts(additional) {
+	const hosts = new Set(additional);
+	for (const _interface of Object.values(networkInterfaces())) for (const config of _interface || []) if (config.address && !config.internal && !config.address.startsWith("fe80::") && !config.address.startsWith("169.254")) hosts.add(config.address);
+	return [...hosts];
+}
+async function _findPort(ports, host) {
+	for (const port of ports) {
+		const r = await _tryPort(port, host);
+		if (r) return r;
+	}
+}
+function _fmtOnHost(hostname) {
+	return hostname ? `on host ${JSON.stringify(hostname)}` : "on any host";
+}
+const HOSTNAME_RE = /^(?!-)[\d.:A-Za-z-]{1,63}(?<!-)$/;
+function _validateHostname(hostname, _public, verbose) {
+	if (hostname && !HOSTNAME_RE.test(hostname)) {
+		const fallbackHost = _public ? "0.0.0.0" : "127.0.0.1";
+		_log(verbose, `Invalid hostname: ${JSON.stringify(hostname)}. Using ${JSON.stringify(fallbackHost)} as fallback.`);
+		return fallbackHost;
+	}
+	return hostname;
+}
+async function getPort(_userOptions = {}) {
+	if (typeof _userOptions === "number" || typeof _userOptions === "string") _userOptions = { port: Number.parseInt(_userOptions + "") || 0 };
+	const _port = Number(_userOptions.port ?? process.env.PORT);
+	const _userSpecifiedAnyPort = Boolean(_userOptions.port || _userOptions.ports?.length || _userOptions.portRange?.length);
+	const options = {
+		random: _port === 0,
+		ports: [],
+		portRange: [],
+		alternativePortRange: _userSpecifiedAnyPort ? [] : [3e3, 3100],
+		verbose: false,
+		..._userOptions,
+		port: _port,
+		host: _validateHostname(_userOptions.host ?? process.env.HOST, _userOptions.public, _userOptions.verbose)
+	};
+	if (options.random && !_userSpecifiedAnyPort) return getRandomPort(options.host);
+	const portsToCheck = [
+		options.port,
+		...options.ports,
+		..._generateRange(...options.portRange)
+	].filter((port) => {
+		if (!port) return false;
+		if (!isSafePort(port)) {
+			_log(options.verbose, `Ignoring unsafe port: ${port}`);
+			return false;
+		}
+		return true;
+	});
+	if (portsToCheck.length === 0) portsToCheck.push(3e3);
+	let availablePort = await _findPort(portsToCheck, options.host);
+	if (!availablePort && options.alternativePortRange.length > 0) {
+		availablePort = await _findPort(_generateRange(...options.alternativePortRange), options.host);
+		if (portsToCheck.length > 0) {
+			let message = `Unable to find an available port (tried ${portsToCheck.join("-")} ${_fmtOnHost(options.host)}).`;
+			if (availablePort) message += ` Using alternative port ${availablePort}.`;
+			_log(options.verbose, message);
+		}
+	}
+	if (!availablePort && _userOptions.random !== false) {
+		availablePort = await getRandomPort(options.host);
+		if (availablePort) _log(options.verbose, `Using random port ${availablePort}`);
+	}
+	if (!availablePort) {
+		const triedRanges = [
+			options.port,
+			options.portRange.join("-"),
+			options.alternativePortRange.join("-")
+		].filter(Boolean).join(", ");
+		throw new GetPortError(`Unable to find an available port ${_fmtOnHost(options.host)} (tried ${triedRanges})`);
+	}
+	return availablePort;
+}
+async function getRandomPort(host) {
+	const port = await checkPort(0, host);
+	if (port === false) throw new GetPortError(`Unable to find a random port ${_fmtOnHost(host)}`);
+	return port;
+}
+async function checkPort(port, host = process.env.HOST, verbose) {
+	if (!host) host = _getLocalHosts([void 0, "0.0.0.0"]);
+	if (!Array.isArray(host)) return _tryPort(port, host);
+	for (const _host of host) {
+		const _port = await _tryPort(port, _host);
+		if (_port === false) {
+			if (port < 1024 && verbose) _log(verbose, `Unable to listen to the privileged port ${port} ${_fmtOnHost(_host)}`);
+			return false;
+		}
+		if (port === 0 && _port !== 0) port = _port;
+	}
+	return port;
+}
+//#endregion
+export { getPort as n, dist_exports as t };

package/dist/helpers/vite.d.mts

@@ -1,4 +1,5 @@
-import { d as McpRouteOptions, p as DevframeAuthHandler, r as DevframeDefinition } from "../devframe-mQ4qZAuo.mjs";
+import { f as McpRouteOptions, p as DevframeAuthHandler, r as DevframeDefinition } from "../devframe-Bdd9YXTy.mjs";
+import { IncomingMessage, Server, ServerResponse } from "node:http";
 //#region src/helpers/vite.d.ts
 interface ViteDevBridgeOptions {
   /**
@@ -12,30 +13,36 @@ interface ViteDevBridgeOptions {
   base?: string;
   /**
    * Dev-time middleware mode. When set, the host app owns the SPA and
-   * devframe spins up a separate RPC + WS server on a resolved port,
-   * registering Vite middleware at `<base>__connection.json` so the
-   * host-served SPA can discover the WS endpoint.
+   * devframe serves the RPC surface through the Vite dev server itself —
+   * `<base>__connection.json` for discovery and the WebSocket upgrade at
+   * `<base>__ws` on Vite's own HTTP server (zero extra ports, proxy/HTTPS
+   * friendly). When Vite runs in middleware mode (no `httpServer`) — or a
+   * `port` is pinned — the socket falls back to a side-car server on its
+   * own port instead.
    *
    *  - `false` (default) — static-mount the SPA at `base` with SPA
    *    fallback. No RPC server is started.
-   *  - `true` — bridge mode with all defaults (port from
-   *    {@link resolveDevServerPort}, host from `def.cli?.host`).
+   *  - `true` — bridge mode with all defaults.
    *  - object — bridge mode with explicit overrides.
    */
   devMiddleware?: boolean | {
-    /** Override the bridge port. Default: {@link resolveDevServerPort}. */
+    /**
+     * Pin a side-car port for the RPC socket instead of sharing Vite's
+     * server. Default: share Vite's HTTP server (side-car only when Vite
+     * has none).
+     */
     port?: number;
-    /** Override the bridge bind host. Default: `def.cli?.host ?? 'localhost'`. */
+    /** Override the side-car bind host. Default: `def.cli?.host ?? 'localhost'`. */
     host?: string;
     /** Flag bag forwarded to `def.setup(ctx, { flags })`. */
     flags?: Record<string, unknown>;
   };
   /**
-   * Whether the bridged devframe runs its own auth gate. The side-car RPC
-   * server is reachable by anything that can open its socket, so it **gates by
-   * default**: when unset, authentication resolves through `createDevServer`
-   * (devframe's interactive OTP gate unless the definition's `cli.auth` opts
-   * out), and the side-car prints its code/link banner to stdout. Pass a
+   * Whether the bridged devframe runs its own auth gate. The RPC endpoint is
+   * reachable by anything that can open its socket, so it **gates by
+   * default**: when unset, authentication resolves through devframe's
+   * interactive OTP gate (unless the definition's `cli.auth` opts out), and
+   * the bridge prints its code/link banner to stdout. Pass a
    * {@link DevframeAuthHandler} to install a custom scheme, or `false` to opt
    * out for a single-user localhost host that owns the trust boundary another
    * way. Only applies in bridge mode (`devMiddleware`); the static-mount mode
@@ -45,30 +52,27 @@ interface ViteDevBridgeOptions {
    */
   auth?: boolean | DevframeAuthHandler;
   /**
-   * Expose the side-car's route-based MCP server (Streamable-HTTP) and
-   * advertise it in the bridge's `__connection.json`. Forwarded to
-   * {@link createDevServer}: overrides `def.cli?.mcp`, `undefined` falls
-   * through to it, `false` disables the route regardless. Only applies in
-   * bridge mode (`devMiddleware`); the static-mount mode starts no server.
-   *
-   * The endpoint lives on the side-car's own port, so the advertised meta
-   * carries `{ port, path }` — see `ConnectionMeta['mcp']`.
+   * Expose the bridge's route-based MCP server (Streamable-HTTP) at
+   * `<base>__mcp` — on the Vite app's own origin — and advertise it in the
+   * bridge's `__connection.json`. Overrides `def.cli?.mcp`, `undefined`
+   * falls through to it, `false` disables the route regardless. Only applies
+   * in bridge mode (`devMiddleware`); the static-mount mode starts no server.
    *
    * @experimental
    */
   mcp?: boolean | McpRouteOptions;
 }
+/** The slice of a Vite dev server the bridge plugin touches. */
+interface DevframeViteDevServerLike {
+  middlewares: {
+    use: ((path: string, handler: (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void) => void) & ((handler: (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void) => void);
+  };
+  httpServer?: Server | null;
+}
 interface DevframeVitePlugin {
   name: string;
   apply: 'serve';
-  configureServer: (server: {
-    middlewares: {
-      use: (path: string, handler: any) => void;
-    };
-    httpServer?: {
-      once: (event: 'close', cb: () => void) => void;
-    } | null;
-  }) => void | Promise<void>;
+  configureServer: (server: DevframeViteDevServerLike) => void | Promise<void>;
   closeBundle?: () => void | Promise<void>;
 }
 /**
@@ -79,16 +83,16 @@ interface DevframeVitePlugin {
  *     `options.base` with SPA fallback enabled. No RPC server is started.
  *
  *   - **bridge mode** (`devMiddleware: true | {…}`) — skips the static
- *     mount; the host app owns the SPA. Devframe starts a separate
- *     RPC + WS dev server (via {@link createDevServer} in bridge mode)
- *     and registers Vite middleware at `<base>__connection.json` so the
- *     host-served SPA can discover the WS endpoint via
- *     {@link connectDevframe}.
+ *     mount; the host app owns the SPA. Devframe serves discovery
+ *     (`<base>__connection.json`), the WebSocket RPC upgrade
+ *     (`<base>__ws`, shared on Vite's own HTTP server), and the optional
+ *     MCP route through {@link initDevframe}'s node middleware, so the
+ *     host-served SPA can discover the endpoint via {@link connectDevframe}.
  *
- * The side-car RPC server **gates by default** (devframe's interactive OTP
- * unless the definition's `cli.auth` opts out), printing its code/link banner
- * to stdout, so a bridged devframe isn't silently reachable by anything that
- * can open its socket. Pass `options.auth: false` to opt out for a single-user
+ * The bridge **gates by default** (devframe's interactive OTP unless the
+ * definition's `cli.auth` opts out), printing its code/link banner to stdout,
+ * so a bridged devframe isn't silently reachable by anything that can open
+ * its socket. Pass `options.auth: false` to opt out for a single-user
  * localhost host, or a {@link DevframeAuthHandler} for a custom scheme.
  *
  * Use bridge mode when integrating with frameworks that own the SPA
@@ -97,4 +101,4 @@ interface DevframeVitePlugin {
  */
 declare function viteDevBridge(d: DevframeDefinition, options?: ViteDevBridgeOptions): DevframeVitePlugin;
 //#endregion
-export { DevframeVitePlugin, ViteDevBridgeOptions, viteDevBridge };
+export { DevframeViteDevServerLike, DevframeVitePlugin, ViteDevBridgeOptions, viteDevBridge };