devframe 0.8.2 → 0.9.0-beta.1

package/dist/_shared-CttmCMBi.mjs

@@ -0,0 +1,70 @@
+import "./constants.mjs";
+import { n as getPort } from "./dist-D8jAMwxU.mjs";
+import { cleanDoubleSlashes, withLeadingSlash, withTrailingSlash, withoutLeadingSlash } from "ufo";
+//#region src/adapters/_shared.ts
+const DEFAULT_PORT = 9999;
+/**
+* Resolve the mount base path for a devframe's SPA. Hosted adapters
+* (`vite`, `embedded`) default to `/__<id>/` so they don't collide
+* with the host app; standalone adapters (`cli`, `spa`, `build`)
+* default to `/` because they own the origin.
+*
+* The devframe author can override with `basePath` on the definition.
+*/
+function resolveBasePath(def, kind) {
+	if (def.basePath) return normalizeBasePath(def.basePath);
+	return kind === "standalone" ? "/" : `/__${def.id}/`;
+}
+function normalizeBasePath(base) {
+	return cleanDoubleSlashes(withTrailingSlash(withLeadingSlash(base)));
+}
+/**
+* Resolve the listening port for `createDevServer` (and `createHandler`'s
+* side-car tiers), honoring the definition's `cli.port` / `cli.portRange` /
+* `cli.random` settings. Exposed separately so authors who run their own
+* argv parsing can resolve a port up-front (to print it, log it, etc.)
+* before starting the server.
+*/
+async function resolveDevServerPort(def, options = {}) {
+	const host = options.host ?? def.cli?.host ?? "localhost";
+	const portOptions = {
+		port: options.defaultPort ?? def.cli?.port ?? DEFAULT_PORT,
+		host
+	};
+	if (def.cli?.portRange) portOptions.portRange = def.cli.portRange;
+	if (def.cli?.random) portOptions.random = def.cli.random;
+	return getPort(portOptions);
+}
+/**
+* Normalize the `cli.mcp` / `mcp` option (`boolean | McpRouteOptions`) into
+* concrete options, or `undefined` when the MCP route is disabled.
+*/
+function resolveMcpConfig(mcp) {
+	if (!mcp) return void 0;
+	return mcp === true ? {} : mcp;
+}
+/**
+* Resolve the `mcp` entry a `__connection.json` should advertise for a dev
+* server started with the given `mcp` option (falling back to `def.cli?.mcp`,
+* exactly like `createDevServer`), or `undefined` when the route is
+* disabled.
+*
+* Hosted bridges that hand-roll their connection meta pass the side-car
+* `port`: the advertised path becomes absolute (the side-car mounts at `/`)
+* and the client dials `<page-host>:<port><path>`. Without `port` the path
+* stays relative, resolved against `__connection.json`'s own location (the
+* same-server default).
+*
+* @experimental
+*/
+function resolveMcpConnectionMeta(def, mcp, port) {
+	const config = resolveMcpConfig(mcp ?? def.cli?.mcp);
+	if (!config) return void 0;
+	const route = withoutLeadingSlash(config.path ?? "__mcp");
+	return port != null ? {
+		path: withLeadingSlash(route),
+		port
+	} : { path: route };
+}
+//#endregion
+export { resolveMcpConnectionMeta as i, resolveBasePath as n, resolveDevServerPort as r, normalizeBasePath as t };

package/dist/_shared-DmpWW-HH.d.mts

@@ -0,0 +1,43 @@
+import { _ as ConnectionMeta, f as McpRouteOptions, i as DevframeDeploymentKind, r as DevframeDefinition } from "./devframe-Bdd9YXTy.mjs";
+//#region src/adapters/_shared.d.ts
+/**
+ * Resolve the mount base path for a devframe's SPA. Hosted adapters
+ * (`vite`, `embedded`) default to `/__<id>/` so they don't collide
+ * with the host app; standalone adapters (`cli`, `spa`, `build`)
+ * default to `/` because they own the origin.
+ *
+ * The devframe author can override with `basePath` on the definition.
+ */
+declare function resolveBasePath(def: DevframeDefinition, kind: DevframeDeploymentKind): string;
+declare function normalizeBasePath(base: string): string;
+interface ResolveDevServerPortOptions {
+  /** Bind host (passed to `get-port-please` for in-use detection). */
+  host?: string;
+  /** Override the preferred port. Default: `def.cli?.port ?? 9999`. */
+  defaultPort?: number;
+}
+/**
+ * Resolve the listening port for `createDevServer` (and `createHandler`'s
+ * side-car tiers), honoring the definition's `cli.port` / `cli.portRange` /
+ * `cli.random` settings. Exposed separately so authors who run their own
+ * argv parsing can resolve a port up-front (to print it, log it, etc.)
+ * before starting the server.
+ */
+declare function resolveDevServerPort(def: DevframeDefinition, options?: ResolveDevServerPortOptions): Promise<number>;
+/**
+ * Resolve the `mcp` entry a `__connection.json` should advertise for a dev
+ * server started with the given `mcp` option (falling back to `def.cli?.mcp`,
+ * exactly like `createDevServer`), or `undefined` when the route is
+ * disabled.
+ *
+ * Hosted bridges that hand-roll their connection meta pass the side-car
+ * `port`: the advertised path becomes absolute (the side-car mounts at `/`)
+ * and the client dials `<page-host>:<port><path>`. Without `port` the path
+ * stays relative, resolved against `__connection.json`'s own location (the
+ * same-server default).
+ *
+ * @experimental
+ */
+declare function resolveMcpConnectionMeta(def: DevframeDefinition, mcp: boolean | McpRouteOptions | undefined, port?: number): ConnectionMeta['mcp'];
+//#endregion
+export { resolveMcpConnectionMeta as a, resolveDevServerPort as i, normalizeBasePath as n, resolveBasePath as r, ResolveDevServerPortOptions as t };

package/dist/adapters/build.d.mts

@@ -1,4 +1,4 @@
-import { r as DevframeDefinition } from "../devframe-mQ4qZAuo.mjs";
+import { r as DevframeDefinition } from "../devframe-Bdd9YXTy.mjs";
 //#region src/adapters/build.d.ts
 interface CreateBuildOptions {
   /** Output directory. Defaults to `dist-static`. */

package/dist/adapters/build.mjs

@@ -1,11 +1,12 @@
-import { t as collectStaticRpcDump } from "../dump-CgZShDRB.mjs";
 import { n as colors } from "../diagnostics-reporter-CsIG85Q5.mjs";
+import { n as strictJsonStringify } from "../serialization-BHY8M5NQ.mjs";
 import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME } from "../constants.mjs";
-import { n as strictJsonStringify } from "../serialization-C8Mnw9hK.mjs";
+import { t as collectStaticRpcDump } from "../static-CvjkO8QE.mjs";
 import { n as structuredCloneStringify } from "../structured-clone-CbAV5rFI.mjs";
-import { n as createHostContext, t as createH3DevframeHost } from "../host-h3-D2hYZvDK.mjs";
-import { t as diagnostics } from "../diagnostics-D7wM2cwM.mjs";
-import { n as resolveBasePath } from "../_shared-bWRzeSa0.mjs";
+import { t as diagnostics } from "../diagnostics-DLYH5oD3.mjs";
+import { t as createHostContext } from "../context-Du11TLcO.mjs";
+import { n as resolveBasePath } from "../_shared-CttmCMBi.mjs";
+import { t as createH3DevframeHost } from "../host-h3-CzCZwtuV.mjs";
 import { existsSync } from "node:fs";
 import { dirname, resolve } from "pathe";
 import process from "node:process";

package/dist/adapters/cac.d.mts

@@ -1,4 +1,4 @@
-import { Ft as InferCliFlags, It as defineCliFlags, Lt as parseCliFlags, Pt as CliFlagsSchema, r as DevframeDefinition } from "../devframe-mQ4qZAuo.mjs";
+import { Ft as CliFlagsSchema, It as InferCliFlags, Lt as defineCliFlags, Rt as parseCliFlags, r as DevframeDefinition } from "../devframe-Bdd9YXTy.mjs";
 import { CAC } from "cac";
 import { H3 } from "h3";
 //#region src/adapters/cac.d.ts

package/dist/adapters/cac.mjs

@@ -1,2 +1,158 @@
-import { n as defineCliFlags, r as parseCliFlags, t as createCac } from "../cac-D4_9ok0z.mjs";
+import { n as colors } from "../diagnostics-reporter-CsIG85Q5.mjs";
+import { r as resolveDevServerPort } from "../_shared-CttmCMBi.mjs";
+import { createBuild } from "./build.mjs";
+import { t as createDevServer } from "../dev-BEveeA5H.mjs";
+import process from "node:process";
+import cac$1 from "cac";
+//#region src/adapters/flags.ts
+/**
+* Identity helper that preserves the literal schema-map type — use this
+* so `InferCliFlags<typeof myFlags>` resolves to the right object shape.
+*
+* ```ts
+* const appFlags = defineCliFlags({
+*   depth: v.pipe(v.number(), v.integer()),
+*   config: v.optional(v.string()),
+* })
+*
+* defineDevframe({
+*   cli: { flags: appFlags },
+*   setup(ctx, info) {
+*     const flags = info.flags as InferCliFlags<typeof appFlags>
+*     flags.depth // number
+*     flags.config // string | undefined
+*   },
+* })
+* ```
+*/
+function defineCliFlags(flags) {
+	return flags;
+}
+/**
+* Best-effort, dependency-free probe of a schema to decide whether the
+* corresponding CAC option takes a value. Duck-types the `type` /
+* `wrapped` / `inner` / `pipe` fields exposed by valibot and by devframe's
+* built-in `s` builder, unwrapping `optional` / `nullable` / `nullish` /
+* `pipe` wrappers then matching on the inner kind. Validators that don't
+* expose these fields (e.g. zod) fall through to a value-taking option.
+*/
+function getSchemaKind(schema) {
+	let current = schema;
+	while (current) {
+		const kind = current.type;
+		if (kind === "optional" || kind === "nullable" || kind === "nullish" || kind === "undefined") {
+			current = current.wrapped ?? current.inner;
+			continue;
+		}
+		if (kind === "pipe" && Array.isArray(current.pipe) && current.pipe.length > 0) {
+			current = current.pipe[0];
+			continue;
+		}
+		return kind ?? "unknown";
+	}
+	return "unknown";
+}
+/** Whether the CAC option for this schema should be a boolean flag. */
+function isBooleanFlag(schema) {
+	return getSchemaKind(schema) === "boolean";
+}
+/** Validate the raw cac-parsed bag against a {@link CliFlagsSchema}. */
+function parseCliFlags(schema, raw) {
+	const flags = {};
+	const issues = [];
+	for (const [key, fieldSchema] of Object.entries(schema)) {
+		const result = fieldSchema["~standard"].validate(raw[key]);
+		if (result instanceof Promise) {
+			issues.push(`--${toKebab(key)}: async flag validation is not supported`);
+			continue;
+		}
+		if (result.issues) issues.push(`--${toKebab(key)}: ${result.issues.map((i) => i.message).join(", ")}`);
+		else flags[key] = result.value;
+	}
+	for (const [key, value] of Object.entries(raw)) if (!(key in schema) && !(key in flags)) flags[key] = value;
+	return issues.length ? {
+		flags,
+		issues
+	} : { flags };
+}
+function toKebab(camel) {
+	return camel.replaceAll(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/** Kebab-case a schema key for CAC option registration. */
+function flagKeyToOption(camel) {
+	return toKebab(camel);
+}
+//#endregion
+//#region src/adapters/cac.ts
+/**
+* Wrap a {@link DevframeDefinition} in a `cac`-powered command-line
+* interface exposing `dev` / `build` / `mcp` subcommands.
+*
+* Requires the optional `cac` peer dependency.
+*/
+function createCac(d, options = {}) {
+	const defaultPort = options.defaultPort ?? d.cli?.port ?? 9999;
+	const defaultHost = d.cli?.host ?? "localhost";
+	const cli = cac$1(d.cli?.command ?? d.id);
+	const devCommand = cli.command("[...args]", "Start a local dev server").option("--port <port>", "Port to listen on").option("--host <host>", "Host to bind to", { default: defaultHost }).option("--open", "Open the browser on start").option("--no-open", "Do not open the browser").option("--no-auth", "Disable the interactive authentication gate").option("--mcp", "Expose an MCP server over HTTP at /__mcp (use --no-mcp to disable) [experimental]");
+	if (d.cli?.flags) for (const [key, schema] of Object.entries(d.cli.flags)) {
+		const optionName = flagKeyToOption(key);
+		const description = schema.description ?? "";
+		if (isBooleanFlag(schema)) devCommand.option(`--${optionName}`, description);
+		else devCommand.option(`--${optionName} <value>`, description);
+	}
+	devCommand.action(async (_args, rawFlags) => {
+		const flags = resolveTypedFlags(d, rawFlags);
+		const host = flags.host ?? defaultHost;
+		const port = flags.port ?? await resolveDevServerPort(d, {
+			host,
+			defaultPort
+		});
+		const mcp = flags.mcp;
+		await createDevServer(d, {
+			host,
+			port,
+			flags,
+			mcp,
+			onReady: options.onReady
+		});
+	});
+	if (d.capabilities?.build !== false) cli.command("build", "Build a self-contained static deploy of the devframe").option("--out-dir <outDir>", "Output directory", { default: "dist-static" }).option("--base <base>", "URL base", { default: "/" }).option("--pretty", "Pretty-print dump JSON (larger on disk)").action(async (flags) => {
+		await createBuild(d, {
+			outDir: flags.outDir,
+			base: flags.base,
+			pretty: flags.pretty
+		});
+	});
+	cli.command("mcp", "Start an MCP server exposing agent-facing tools (stdio) [experimental]").action(async () => {
+		const { createMcpServer } = await import("./mcp.mjs");
+		await createMcpServer(d, {
+			transport: "stdio",
+			onReady: ({ transport }) => {
+				console.error(`[devframe] "${d.id}" MCP server ready (${transport})`);
+			}
+		});
+	});
+	d.cli?.configure?.(cli);
+	options.configureCli?.(cli);
+	cli.help();
+	cli.version("0.0.0");
+	return {
+		cli,
+		async parse(argv = process.argv) {
+			cli.parse(argv, { run: false });
+			await cli.runMatchedCommand();
+		}
+	};
+}
+function resolveTypedFlags(d, raw) {
+	if (!d.cli?.flags) return raw;
+	const { flags, issues } = parseCliFlags(d.cli.flags, raw);
+	if (issues?.length) {
+		for (const issue of issues) console.error(colors.red`[devframe] invalid flag — ${issue}`);
+		process.exit(1);
+	}
+	return flags;
+}
+//#endregion
 export { createCac, defineCliFlags, parseCliFlags };

package/dist/adapters/dev.d.mts

@@ -1,7 +1,7 @@
-import { W as DevframeNodeRpcSession, _ as ConnectionMeta, d as McpRouteOptions, p as DevframeAuthHandler, r as DevframeDefinition, u as DevframeWsOptions } from "../devframe-mQ4qZAuo.mjs";
-import { n as DevframeNodeRpcSessionMeta } from "../ws-server-uKQcClcJ.mjs";
-import { n as StartedServer } from "../server-UHWae43Q.mjs";
-import { Peer } from "crossws";
+import { G as DevframeNodeRpcSession, d as DevframeWsOptions, f as McpRouteOptions, p as DevframeAuthHandler, r as DevframeDefinition, u as DevframeSseOptions } from "../devframe-Bdd9YXTy.mjs";
+import { d as DevframeRpcConnection, u as DevframeNodeRpcSessionMeta } from "../ws-server-Ces08fjP.mjs";
+import { c as StartedServer } from "../instance-shell-DBTXTSjN.mjs";
+import { a as resolveMcpConnectionMeta, i as resolveDevServerPort, t as ResolveDevServerPortOptions } from "../_shared-DmpWW-HH.mjs";
 import { H3 } from "h3";
 //#region src/adapters/dev.d.ts
 interface CreateDevServerOptions {
@@ -35,9 +35,16 @@ interface CreateDevServerOptions {
   /**
    * Override how the browser reaches the RPC WebSocket (`def.cli?.ws`).
    * See {@link DevframeWsOptions}: same-server route (default), a dedicated
-   * port, or a remote origin.
+   * port, or a remote origin. Pass `false` to serve no WebSocket at all —
+   * clients connect over the SSE endpoint instead (`backend: 'sse'`).
    */
-  ws?: DevframeWsOptions;
+  ws?: DevframeWsOptions | false;
+  /**
+   * Override the SSE RPC endpoint control (`def.cli?.sse`) — enabled by
+   * default at `<base>__sse`. Pass `false` to disable, or a
+   * {@link DevframeSseOptions} to rename the route.
+   */
+  sse?: boolean | DevframeSseOptions;
   /**
    * h3 app to mount the SPA + connection-meta routes on. When omitted
    * a fresh app is created. Pass a pre-configured app to attach custom
@@ -71,16 +78,16 @@ interface CreateDevServerOptions {
    */
   mcp?: boolean | McpRouteOptions;
   /**
-   * Called once per new WS connection, right after its session is created.
-   * Forwarded verbatim to the underlying `startHttpAndWs`.
+   * Called once per new RPC connection, right after its session is created.
+   * Forwarded verbatim to the underlying transport binding.
    */
-  onPeerConnect?: (peer: Peer, session: DevframeNodeRpcSession) => void;
+  onPeerConnect?: (connection: DevframeRpcConnection, session: DevframeNodeRpcSession) => void;
   /**
-   * Called once per closed WS connection, right after its session's
+   * Called once per closed RPC connection, right after its session's
    * disconnect bookkeeping runs. Forwarded verbatim to the underlying
-   * `startHttpAndWs`.
+   * transport binding.
    */
-  onPeerDisconnect?: (peer: Peer, meta: DevframeNodeRpcSessionMeta) => void;
+  onPeerDisconnect?: (connection: DevframeRpcConnection, meta: DevframeNodeRpcSessionMeta) => void;
   /**
    * Called once the WS server is bound. Devframe stays headless
    * otherwise — wire this if you want a startup banner.
@@ -91,20 +98,6 @@ interface CreateDevServerOptions {
     app: H3;
   }) => void | Promise<void>;
 }
-interface ResolveDevServerPortOptions {
-  /** Bind host (passed to `get-port-please` for in-use detection). */
-  host?: string;
-  /** Override the preferred port. Default: `def.cli?.port ?? 9999`. */
-  defaultPort?: number;
-}
-/**
- * Resolve the listening port for {@link createDevServer}, honoring the
- * definition's `cli.port` / `cli.portRange` / `cli.random` settings.
- * Exposed separately so authors who run their own argv parsing can
- * resolve a port up-front (to print it, log it, etc.) before starting
- * the server.
- */
-declare function resolveDevServerPort(def: DevframeDefinition, options?: ResolveDevServerPortOptions): Promise<number>;
 /**
  * Start a devframe dev server for a {@link DevframeDefinition} —
  * h3 + WebSocket RPC + (optionally) the author's SPA mounted at the
@@ -124,20 +117,5 @@ declare function resolveDevServerPort(def: DevframeDefinition, options?: Resolve
  * `dev` / `build` / `mcp` shell, reach for {@link createCac} instead.
  */
 declare function createDevServer(def: DevframeDefinition, options?: CreateDevServerOptions): Promise<StartedServer>;
-/**
- * Resolve the `mcp` entry a `__connection.json` should advertise for a dev
- * server started with the given `mcp` option (falling back to `def.cli?.mcp`,
- * exactly like {@link createDevServer}), or `undefined` when the route is
- * disabled.
- *
- * Hosted bridges that hand-roll their connection meta (`viteDevBridge`,
- * `@devframes/next`'s handler) pass the side-car `port`: the advertised path
- * becomes absolute (the side-car mounts at `/`) and the client dials
- * `<page-host>:<port><path>`. Without `port` the path stays relative, resolved
- * against `__connection.json`'s own location (the same-server default).
- *
- * @experimental
- */
-declare function resolveMcpConnectionMeta(def: DevframeDefinition, mcp: boolean | McpRouteOptions | undefined, port?: number): ConnectionMeta['mcp'];
 //#endregion
-export { CreateDevServerOptions, ResolveDevServerPortOptions, createDevServer, resolveDevServerPort, resolveMcpConnectionMeta };
+export { CreateDevServerOptions, type ResolveDevServerPortOptions, createDevServer, resolveDevServerPort, resolveMcpConnectionMeta };

package/dist/adapters/dev.mjs

@@ -1,2 +1,3 @@
-import { n as resolveDevServerPort, r as resolveMcpConnectionMeta, t as createDevServer } from "../dev-Bc49u3qg.mjs";
+import { i as resolveMcpConnectionMeta, r as resolveDevServerPort } from "../_shared-CttmCMBi.mjs";
+import { t as createDevServer } from "../dev-BEveeA5H.mjs";
 export { createDevServer, resolveDevServerPort, resolveMcpConnectionMeta };

package/dist/adapters/embedded.d.mts

@@ -1,4 +1,4 @@
-import { b as DevframeNodeContext, r as DevframeDefinition } from "../devframe-mQ4qZAuo.mjs";
+import { r as DevframeDefinition, x as DevframeNodeContext } from "../devframe-Bdd9YXTy.mjs";
 //#region src/adapters/embedded.d.ts
 interface CreateEmbeddedOptions {
   /** Target context the devframe is registered into. Required. */

package/dist/adapters/initiate.d.mts

@@ -0,0 +1,223 @@
+import { B as DevframeStorageScope, G as DevframeNodeRpcSession, _ as ConnectionMeta, d as DevframeWsOptions, f as McpRouteOptions, p as DevframeAuthHandler, r as DevframeDefinition, u as DevframeSseOptions, x as DevframeNodeContext } from "../devframe-Bdd9YXTy.mjs";
+import { d as DevframeRpcConnection, n as WsOriginRegistry, u as DevframeNodeRpcSessionMeta } from "../ws-server-Ces08fjP.mjs";
+import { c as StartedServer, f as DevframeInstanceRecord } from "../instance-shell-DBTXTSjN.mjs";
+import { Buffer } from "node:buffer";
+import { IncomingMessage, Server, ServerResponse } from "node:http";
+import { Duplex } from "node:stream";
+import { H3 } from "h3";
+//#region src/adapters/initiate.d.ts
+interface InitDevframeOptions {
+  /**
+   * Mount base the handler answers under (e.g. `/__my-tool/`) — required so
+   * the mount path is explicit at the call site. A handler is by definition
+   * mounted *inside* a host app's origin; the resolved value is echoed back
+   * as {@link DevframeInstance.base} so route/middleware code references it
+   * instead of repeating the string. `resolveBasePath(def, 'hosted')` gives
+   * the conventional `def.basePath ?? /__<id>/`.
+   */
+  base: string;
+  /**
+   * Override `def.cli?.distDir`. When neither is set — or `false` is passed
+   * to suppress the definition's own `distDir` — the handler runs in
+   * **bridge mode**: only `__connection.json`, the WS endpoint, and the MCP
+   * route (when enabled) are served; the SPA is hosted elsewhere.
+   */
+  distDir?: string | false;
+  /**
+   * Share the host's `node:http` server for the WebSocket RPC endpoint: the
+   * upgrade listener binds to `<base>__ws` on this server, so no extra port
+   * is needed and the socket follows the app through proxies/HTTPS. Hosts
+   * whose handlers never see upgrades (Next.js route handlers, Nitro,
+   * Rsbuild) ask for a side-car instead with `ws: { sidecar: true }`; hosts
+   * that own their upgrade routing wire {@link DevframeInstance.attach} /
+   * {@link DevframeInstance.handleUpgrade} themselves.
+   */
+  server?: Server;
+  /**
+   * Explicit control over how the browser reaches the RPC WebSocket —
+   * advertised in `__connection.json`. The **local binding** resolves in
+   * precedence order `ws.port` (pinned side-car) > `server` (shared upgrade)
+   * > `ws.sidecar` (auto-port side-car) > none (the host drives the socket
+   * through {@link DevframeInstance.attach}). `ws.url` controls the
+   * advertisement* only: the browser dials it verbatim (a tunnel/relay),
+   * while the local binding keeps following the options above — and on its
+   * own it means an external server owns both the transport and its auth.
+   * Pass `false` to serve no WebSocket at all — clients connect over the
+   * SSE endpoint instead (`backend: 'sse'`).
+   */
+  ws?: DevframeWsOptions | false;
+  /**
+   * SSE RPC endpoint control — enabled by default at `<base>__sse` as the
+   * more portable transport alongside the WebSocket. Pass `false` to
+   * disable, or a {@link DevframeSseOptions} to rename the route.
+   */
+  sse?: boolean | DevframeSseOptions;
+  /**
+   * Bind host for a side-car WebSocket server (default: `def.cli?.host ??
+   * 'localhost'`). Irrelevant for the `server` / `ws.url` tiers.
+   */
+  host?: string;
+  /**
+   * Authentication for the RPC endpoint. A handler mounted inside an app
+   * server is reachable by anything that can open its socket, so it **gates
+   * by default**: when unset (or `true`), devframe's interactive OTP handler
+   * is wired and its code/link banner prints once the public origin is known
+   * (derived from the first request, or `origin`). Pass a
+   * {@link DevframeAuthHandler} for a custom scheme, or `false` to opt out
+   * for a single-user localhost setup that owns the trust boundary another
+   * way. Ignored for the `ws.url` tier — the server behind that URL owns auth.
+   */
+  auth?: boolean | DevframeAuthHandler;
+  /**
+   * Expose a route-based MCP server (Streamable-HTTP) at `<base>__mcp` and
+   * advertise it in `__connection.json`. Overrides `def.cli?.mcp`;
+   * `undefined` falls through to it. See {@link McpRouteOptions}.
+   */
+  mcp?: boolean | McpRouteOptions;
+  /**
+   * Public origin the host app is reachable at (e.g. `http://localhost:3000`),
+   * or a getter for hosts that resolve it late. When omitted (or the getter
+   * returns a falsy value), it is derived lazily from the first request the
+   * handler serves — used for the auth banner's magic link and absolute dock
+   * URLs.
+   */
+  origin?: string | (() => string);
+  /**
+   * Publish this instance in the global registry (`~/.devframe/instances/`)
+   * so discovery tooling (`devframe connect`, the inspect plugin's Instances
+   * tab) finds it without port guessing. Registration is a dynamic import
+   * that fires once the public origin resolves and is torn down on
+   * {@link DevframeInstance.close}. Defaults to off; pass `true` to enable, or
+   * an object to override individual record fields (`id`, `name`, `mcp`, …).
+   */
+  register?: boolean | Partial<DevframeInstanceRecord>;
+  /** Parsed flag bag forwarded to `def.setup(ctx, { flags })`. */
+  flags?: Record<string, unknown>;
+  /**
+   * Extra origins to accept on the WS upgrade beyond the loopback default.
+   * Add your LAN/tunnel origin here when reaching the tool from another
+   * host. Pass `false` to disable origin checking entirely (not
+   * recommended). Default: loopback-only.
+   */
+  allowedOrigins?: readonly string[] | WsOriginRegistry | false;
+  /**
+   * h3 app to mount the handler's routes on. When omitted a fresh internal
+   * app is created — the common middleware case. An adapter that owns the
+   * whole server (e.g. `createDevServer`) passes its own app so callers can
+   * compose custom routes ahead of devframe's.
+   */
+  app?: H3;
+  /**
+   * Override where persisted devframe state lives, per
+   * `DevframeHost.getStorageDir`. Defaults to the standalone host layout
+   * (`.devframe/`, `node_modules/.<id>/devframe/`, `~/.<id>/devframe/`).
+   */
+  getStorageDir?: (scope: DevframeStorageScope) => string;
+  /**
+   * Destroy upgrade requests on a shared `server` that don't match the WS
+   * route, instead of leaving them for the host's own upgrade handlers.
+   * Enable when devframe's adapter owns the server outright (nothing else
+   * handles its upgrades) so off-route clients are rejected promptly.
+   * Default: `false` (coexist-friendly).
+   */
+  destroyUnmatchedUpgrades?: boolean;
+  /**
+   * Called once per new RPC connection, right after its session is created.
+   * Forwarded verbatim to the underlying transport.
+   */
+  onPeerConnect?: (connection: DevframeRpcConnection, session: DevframeNodeRpcSession) => void;
+  /**
+   * Called once per closed RPC connection, right after the transport's own
+   * disconnect bookkeeping runs.
+   */
+  onPeerDisconnect?: (connection: DevframeRpcConnection, meta: DevframeNodeRpcSessionMeta) => void;
+}
+interface DevframeInstance {
+  /**
+   * The normalized mount base this instance answers under (leading and
+   * trailing slash, e.g. `/__my-tool/`). Reference it when wiring the mount
+   * — route guards, middleware path checks — instead of repeating the
+   * string.
+   */
+  base: string;
+  /**
+   * Web-standard request handler — mount it on a catch-all route under
+   * {@link DevframeInstance.base} (Next.js route handler, SvelteKit
+   * `+server.ts`, Hono `c.req.raw`, Nitro `toWebRequest(event)`, …).
+   * Requests outside the base 404.
+   */
+  handler: (request: Request) => Promise<Response>;
+  /**
+   * Connect/Express-style middleware over the same surface — for
+   * `viteServer.middlewares.use(handler.nodeMiddleware)` or any other
+   * node middleware stack. Mount it un-prefixed: paths outside the base
+   * call `next()` so the rest of the stack keeps working.
+   */
+  nodeMiddleware: (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void;
+  /**
+   * Route a host server's `upgrade` events to the RPC socket, returning a
+   * detach function — the manual counterpart to the `server` option, for
+   * hosts that get their `node:http` server only after the instance exists.
+   * Available on the default tier; a configured transport (`server`,
+   * `ws.port`, `ws.sidecar`, `ws.url`) already owns the socket and reports
+   * `DF0055` / `DF0056` instead.
+   */
+  attach: (server: Server) => () => void;
+  /**
+   * Complete a single `upgrade` event on the RPC socket, for hosts that
+   * already own an `upgrade` listener: `server.on('upgrade',
+   * instance.handleUpgrade)`. Same availability as
+   * {@link DevframeInstance.attach}.
+   */
+  handleUpgrade: (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+  /**
+   * Resolves once `def.setup` has run and the WebSocket binding is live.
+   * `handler`/`nodeMiddleware` await it internally, so hosts never race
+   * initialization — await it yourself only when you need the timing.
+   */
+  ready: Promise<void>;
+  /** The node context, once initialized — for advanced wiring (own WS transport, extra RPC registration). */
+  context: Promise<DevframeNodeContext>;
+  /**
+   * The `ConnectionMeta` this handler serves at `<base>__connection.json`.
+   * Only readable after initialization (`DF0054` otherwise).
+   */
+  connectionMeta: () => ConnectionMeta;
+  /** Tear down: WS transport/side-car, MCP sessions. */
+  close: () => Promise<void>;
+}
+/**
+ * Live internals of a handler, for the first-party adapters built on it
+ * (`createDevServer` exposes the transport's `ws`/`rpcGroup` through its
+ * `StartedServer` contract).
+ *
+ * @internal
+ */
+interface DevframeInstanceInternals {
+  /** The bound HTTP+WS server handle backing the side-car / shared-server WS tiers. */
+  readonly started?: StartedServer;
+  /** The resolved auth handler when the gate is active. */
+  readonly authHandler?: DevframeAuthHandler;
+}
+/** @internal */
+declare function getInstanceInternals(handler: object): DevframeInstanceInternals;
+/**
+ * Serve a devframe through one framework-agnostic, web-standard handler —
+ * the SPA, `__connection.json` discovery, the WebSocket RPC endpoint, the
+ * auth gate, and the optional MCP route, all under a single mount base.
+ * Mount `handler` on any framework's catch-all route (or `nodeMiddleware` on
+ * a connect stack) and the devframe is live inside that app.
+ *
+ * The factory is synchronous and kicks off initialization eagerly;
+ * `handler`/`nodeMiddleware` await readiness internally. Nothing binds a port
+ * on its own: the WebSocket resolves in precedence order — `ws.port` (pinned
+ * side-car) > `server` (shared upgrade at `<base>__ws`) > `ws.sidecar`
+ * (auto-port side-car) > the host driving upgrades itself through
+ * {@link DevframeInstance.attach} — while `ws.url`, when set, overrides the
+ * advertised* endpoint (the tunnel pattern) and on its own hands the whole
+ * transport to an external server. `__connection.json` reflects whichever
+ * combination is active.
+ */
+declare function initDevframe(def: DevframeDefinition, options: InitDevframeOptions): DevframeInstance;
+//#endregion
+export { DevframeInstance, DevframeInstanceInternals, InitDevframeOptions, getInstanceInternals, initDevframe };

package/dist/adapters/initiate.mjs

@@ -0,0 +1,2 @@
+import { n as getInstanceInternals, r as initDevframe } from "../dev-BEveeA5H.mjs";
+export { getInstanceInternals, initDevframe };