devframe 0.8.2 → 0.9.0-beta.10

package/dist/node/hub-internals.d.mts

@@ -1,15 +1,3 @@
-import { i as DevframeDeploymentKind, r as DevframeDefinition } from "../devframe-mQ4qZAuo.mjs";
-import { a as internalContextMap, i as getInternalContext, n as InternalAnonymousAuthStorage, r as RemoteTokenRecord, t as DevframeInternalContext } from "../context-DoSozfvx.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;
-//#endregion
+import { a as internalContextMap, i as getInternalContext, n as InternalAnonymousAuthStorage, r as RemoteTokenRecord, t as DevframeInternalContext } from "../context-B3YUu_95.mjs";
+import { n as normalizeBasePath, r as resolveBasePath } from "../_shared-BPmX9fqK.mjs";
 export { type DevframeInternalContext, type InternalAnonymousAuthStorage, type RemoteTokenRecord, getInternalContext, internalContextMap, normalizeBasePath, resolveBasePath };

package/dist/node/hub-internals.mjs

@@ -1,3 +1,3 @@
-import { n as internalContextMap, t as getInternalContext } from "../context-CBg8iRbQ.mjs";
-import { n as resolveBasePath, t as normalizeBasePath } from "../_shared-bWRzeSa0.mjs";
+import { n as resolveBasePath, t as normalizeBasePath } from "../_shared-CbZ_yhbz.mjs";
+import { n as internalContextMap, t as getInternalContext } from "../context-xdynGSLP.mjs";
 export { getInternalContext, internalContextMap, normalizeBasePath, resolveBasePath };

package/dist/node/index.d.mts

@@ -1,38 +1,7 @@
-import { At as DevframeAgentHostEvents, C as DevframeServicesHost, Ct as AgentResourceContent, Dt as AgentToolProvider, Et as AgentToolInput, H as DevframeDiagnosticsHost$1, J as RpcSharedStateHost, K as RpcFunctionsHost, L as DevframeViewHost$1, O as DevframeSettings, Ot as AgentToolProviderHandle, R as DevframeHost, S as DevframeServiceOf, St as AgentResource, T as DevframeScopedNodeContext, Tt as AgentTool, U as DevframeDiagnosticsLogger, Z as RpcStreamingHost, b as DevframeNodeContext, bt as AgentHandle, ht as SharedState, jt as EventEmitter, kt as DevframeAgentHost$1, wt as AgentResourceInput, x as DevframeServiceId, xt as AgentManifest } from "../devframe-mQ4qZAuo.mjs";
-import { v as RpcFunctionDefinitionAny } from "../types-CnJSgRVa.mjs";
-import "../index-Dbw1p5ch.mjs";
-import { n as StartedServer, r as startHttpAndWs, t as StartHttpAndWsOptions } from "../server-UHWae43Q.mjs";
+import { B as RpcFunctionsHost, P as DevframeHost, g as DevframeNodeContext, lt as SharedState } from "../devframe-DJMg0WLe.mjs";
+import "../index-tdrk1bzV.mjs";
+import { v as RpcFunctionDefinitionAny } from "../types-Djq7CBXh.mjs";
 import { BirpcGroup } from "birpc";
-//#region src/node/agent-args.d.ts
-/**
- * How {@link coerceAgentPositionalArgs} treats an args object that carries
- * neither declared schemas nor `arg0`/`arg1`/… keys:
- *
- * - `'wrap'` — pass the object itself as the single positional argument.
- *   RPC-backed tools use this: an untyped RPC may take one raw object.
- * - `'drop'` — call with zero arguments. Command-backed tools use this:
- *   a handler's positional parameters come solely from its declared
- *   `agent.args` schemas, so undeclared payload is ignored.
- */
-type AgentArgsFallback = 'wrap' | 'drop';
-/**
- * Map the args payload an agent surface receives (MCP sends an object
- * keyed `arg0`/`arg1`/…, matching the schema the adapter advertises) onto
- * a handler's positional parameters. Shared by the agent host's RPC
- * bridge and the hub's command-derived tools so the coercion cannot
- * drift between them.
- *
- * - an array passes through as-is
- * - `null`/`undefined` become a zero-argument call
- * - with declared schemas, each schema reads its own `argN` key, in order
- * - without schemas, `arg0`/`arg1`/… keys are collected when present
- * - an empty object becomes a zero-argument call
- * - anything else follows the {@link AgentArgsFallback}
- *
- * @experimental
- */
-declare function coerceAgentPositionalArgs(args: unknown, schemas: readonly unknown[] | undefined, fallback?: AgentArgsFallback): unknown[];
-//#endregion
 //#region src/node/context.d.ts
 interface CreateHostContextOptions {
   cwd: string;
@@ -56,231 +25,6 @@ interface CreateHostContextOptions {
  */
 declare function createHostContext(options: CreateHostContextOptions): Promise<DevframeNodeContext>;
 //#endregion
-//#region src/node/host-agent.d.ts
-/**
- * Framework-neutral host aggregating the agent-exposed surface of a
- * devframe. Auto-discovers RPC functions with an `agent` field from
- * `ctx.rpc.definitions`, and accepts plugin-registered tools /
- * resources via `registerTool` / `registerResource`.
- *
- * @experimental
- */
-declare class DevframeAgentHost implements DevframeAgentHost$1 {
-  readonly context: DevframeNodeContext;
-  readonly events: EventEmitter<DevframeAgentHostEvents>;
-  private readonly tools;
-  private readonly resources;
-  private readonly providers;
-  private _rpcUnsubscribe;
-  constructor(context: DevframeNodeContext);
-  registerTool(input: AgentToolInput): AgentHandle;
-  unregisterTool(id: string): boolean;
-  registerToolProvider(provider: AgentToolProvider): AgentToolProviderHandle;
-  registerResource(input: AgentResourceInput): AgentHandle;
-  unregisterResource(id: string): boolean;
-  list(): AgentManifest;
-  getTool(id: string): AgentTool | undefined;
-  getResource(id: string): AgentResource | undefined;
-  invoke(id: string, args: unknown): Promise<unknown>;
-  read(id: string): Promise<AgentResourceContent>;
-  /** @internal */
-  _dispose(): void;
-  private _validateToolId;
-  private _projectTool;
-  /** Query every registered provider, projecting inputs to serializable tools. */
-  private _collectProviderTools;
-  private _collectRpcTools;
-  private _findRpcDefinition;
-}
-//#endregion
-//#region src/node/host-diagnostics.d.ts
-declare class DevframeDiagnosticsHost implements DevframeDiagnosticsHost$1 {
-  readonly context: DevframeNodeContext;
-  private _registry;
-  readonly logger: DevframeDiagnosticsLogger;
-  readonly defineDiagnostics: DevframeDiagnosticsHost$1['defineDiagnostics'];
-  constructor(context: DevframeNodeContext, initialDefinitions?: Array<Record<string, unknown>>);
-  register(diagnostics: Record<string, unknown>): void;
-}
-//#endregion
-//#region src/node/host-h3.d.ts
-interface CreateH3DevframeHostOptions {
-  /** The h3 app instance — registered once the CLI adapter lands. */
-  app?: unknown;
-  /**
-   * Host the standalone server listens on, e.g. `http://localhost:9999`.
-   * Consumed by `resolveOrigin` for dock entries that need an absolute URL.
-   */
-  origin: string;
-  /**
-   * Register a static-file handler at `base` serving files from `distDir`.
-   * Wired into the h3 app once the CLI adapter lands (commit 5). For now
-   * the CLI isn't running, so the default is a no-op.
-   */
-  mount?: (base: string, distDir: string) => void | Promise<void>;
-  /**
-   * Namespace for storage paths returned by `getStorageDir`. Workspace
-   * state (committable) lives under `${workspaceRoot}/.devframe/`, project
-   * state under `${workspaceRoot}/node_modules/.<appName>/devframe/`, and
-   * global state under `${homedir()}/.<appName>/devframe/`. Pick the
-   * devtool's id (or another stable, filesystem-safe identifier) so the
-   * standalone host doesn't collide with other tools' storage.
-   */
-  appName: string;
-  /**
-   * Workspace root used as the parent of the per-project storage
-   * directory. Defaults to `process.cwd()`.
-   */
-  workspaceRoot?: string;
-}
-/**
- * h3-backed {@link DevframeHost} — used by the standalone CLI adapter.
- */
-declare function createH3DevframeHost(options: CreateH3DevframeHostOptions): DevframeHost;
-//#endregion
-//#region src/node/host-services.d.ts
-/**
- * Cross-plugin service registry (see `types/services.ts` for the contract).
- * Values are held per context instance; `whenAvailable` subscriptions make
- * the mechanism robust against setup ordering between provider and consumer.
- */
-declare class DevframeServicesHostImpl implements DevframeServicesHost {
-  private services;
-  private listeners;
-  provide<ID extends DevframeServiceId>(id: ID, service: DevframeServiceOf<ID>): () => void;
-  get<ID extends DevframeServiceId>(id: ID): DevframeServiceOf<ID> | undefined;
-  has(id: DevframeServiceId): boolean;
-  whenAvailable<ID extends DevframeServiceId>(id: ID, callback: (service: DevframeServiceOf<ID>) => void): () => void;
-  keys(): string[];
-}
-//#endregion
-//#region src/node/host-views.d.ts
-declare class DevframeViewHost implements DevframeViewHost$1 {
-  readonly context: DevframeNodeContext;
-  /**
-   * @internal
-   */
-  buildStaticDirs: {
-    baseUrl: string;
-    distDir: string;
-  }[];
-  constructor(context: DevframeNodeContext);
-  hostStatic(baseUrl: string, distDir: string): void;
-}
-//#endregion
-//#region src/node/instance-registry.d.ts
-/**
- * One running devframe instance, as recorded in the instance registry.
- * Records are self-describing JSON — additive fields are safe.
- *
- * @experimental The agent-native surface is experimental and may change
- * without a major version bump until it stabilizes.
- */
-interface DevframeInstanceRecord {
-  /** Process id of the dev server. */
-  pid: number;
-  /** Listening port. */
-  port: number;
-  /** Dialable HTTP origin, e.g. `http://127.0.0.1:9876`. */
-  origin: string;
-  /** Base path the devframe is mounted at (trailing slash). */
-  basePath: string;
-  /** Definition id. */
-  id: string;
-  /** Definition display name. */
-  name?: string;
-  /** Working directory the instance was started from. */
-  rootDir: string;
-  /**
-   * Absolute URL path of the MCP Streamable-HTTP endpoint on `origin`, or
-   * `null` when the instance runs without an MCP route.
-   */
-  mcp: {
-    path: string;
-  } | null;
-  /** Epoch-ms timestamp of registration. */
-  startedAt: number;
-}
-/**
- * Handle returned by {@link registerDevframeInstance}.
- *
- * @experimental
- */
-interface DevframeInstanceRegistration {
-  /** The registry file backing this registration. */
-  readonly file: string;
-  /** Remove the record (idempotent). Call on server close. */
-  unregister: () => void;
-}
-/**
- * Record a running devframe instance in the global instance registry so
- * discovery tooling (`devframe connect`, editor integrations) can find it
- * without port guessing.
- *
- * `createDevServer` registers automatically; custom hosts that serve a
- * devframe in-process (e.g. `@devframes/next`'s host inside a Next dev
- * server) call this explicitly with the origin they are reachable at.
- *
- * The record is written atomically to `<dir>/<pid>-<port>.json` and removed
- * by {@link DevframeInstanceRegistration.unregister}. Records surviving a
- * crash are pruned by readers whose liveness probe fails. Registration never
- * throws — a write failure degrades to a coded warning (`DF0045`), since a
- * dev server must not die over discovery metadata.
- *
- * @experimental
- */
-declare function registerDevframeInstance(record: DevframeInstanceRecord, options?: {
-  instancesDir?: string;
-}): DevframeInstanceRegistration;
-/**
- * Read the registry and split records into live and dead by probing each
- * one's `__connection.json`, deleting dead records (prune-on-read). Live
- * records carry the dialable origin the probe confirmed (a `localhost`
- * record may come back as `127.0.0.1` / `[::1]`).
- *
- * A liveness probe only proves *something* answers on the record's port, so
- * records left behind by killed processes shadow the server currently bound
- * there: per `(port, basePath)` only the newest record survives, older
- * ghosts are pruned with the dead.
- *
- * @experimental
- */
-declare function listLiveDevframeInstances(options?: {
-  instancesDir?: string;
-  timeoutMs?: number;
-}): Promise<{
-  live: DevframeInstanceRecord[];
-  pruned: DevframeInstanceRecord[];
-}>;
-//#endregion
-//#region src/node/rpc-shared-state.d.ts
-declare function createRpcSharedStateServerHost(rpc: RpcFunctionsHost): RpcSharedStateHost;
-//#endregion
-//#region src/node/rpc-streaming.d.ts
-/**
- * Build the server-side streaming host. Mirrors the layout of
- * `createRpcSharedStateServerHost` — registers a fixed set of internal
- * RPC methods (`subscribe` / `unsubscribe` / `cancel`) once, then per-channel
- * state lives in a `Map<channelName, ChannelState>`.
- */
-declare function createRpcStreamingServerHost(rpc: RpcFunctionsHost): RpcStreamingHost;
-//#endregion
-//#region src/node/scope.d.ts
-/**
- * Build a namespace-scoped view of a {@link DevframeNodeContext}. Every
- * RPC id, shared-state key, and streaming channel passed through the
- * returned `rpc` surface is auto-namespaced with `<namespace>:`.
- */
-declare function createScopedNodeContext<NS extends string = string>(context: DevframeNodeContext, namespace: NS): DevframeScopedNodeContext<NS>;
-//#endregion
-//#region src/node/settings.d.ts
-/**
- * Build the node-side `settings` surface for a scope namespace. `project`
- * persists under the host's `workspace` storage dir, `global` under its
- * `global` dir. Each is a file-backed, client-synced key-value store.
- */
-declare function createNodeSettings<T extends Record<string, any> = Record<string, any>>(context: DevframeNodeContext, namespace: string): DevframeSettings<T>;
-//#endregion
 //#region src/node/storage.d.ts
 interface CreateStorageOptions<T extends object> {
   filepath: string;
@@ -290,12 +34,4 @@ interface CreateStorageOptions<T extends object> {
 }
 declare function createStorage<T extends object>(options: CreateStorageOptions<T>): SharedState<T>;
 //#endregion
-//#region src/node/utils.d.ts
-declare function isObject(value: unknown): value is Record<string, any>;
-/** Map a bind host to a host a client can actually connect to. */
-declare function toDialableHost(host: string): string;
-/** Format a bind host for use in a URL authority (dialable, IPv6-bracketed). */
-declare function formatHostForUrl(host: string): string;
-declare function normalizeHttpServerUrl(host: string, port: number | string): string;
-//#endregion
-export { AgentArgsFallback, CreateH3DevframeHostOptions, CreateHostContextOptions, CreateStorageOptions, DevframeAgentHost, DevframeDiagnosticsHost, type DevframeInstanceRecord, type DevframeInstanceRegistration, DevframeServicesHostImpl, DevframeViewHost, type RpcFunctionsHost, StartHttpAndWsOptions, StartedServer, coerceAgentPositionalArgs, createH3DevframeHost, createHostContext, createNodeSettings, createRpcSharedStateServerHost, createRpcStreamingServerHost, createScopedNodeContext, createStorage, formatHostForUrl, isObject, listLiveDevframeInstances, normalizeHttpServerUrl, registerDevframeInstance, startHttpAndWs, toDialableHost };
+export { CreateHostContextOptions, CreateStorageOptions, type RpcFunctionsHost, createHostContext, createStorage };

package/dist/node/index.mjs

@@ -1,5 +1,3 @@
-import { a as DevframeViewHost, c as createRpcSharedStateServerHost, d as coerceAgentPositionalArgs, i as createNodeSettings, l as DevframeDiagnosticsHost, n as createHostContext, o as DevframeServicesHostImpl, r as createScopedNodeContext, s as createRpcStreamingServerHost, t as createH3DevframeHost, u as DevframeAgentHost } from "../host-h3-D2hYZvDK.mjs";
-import { t as createStorage } from "../storage-CTNVbuFB.mjs";
-import { r as registerDevframeInstance, t as listLiveDevframeInstances } from "../instance-registry-BnnA2Eoh.mjs";
-import { a as toDialableHost, i as normalizeHttpServerUrl, n as formatHostForUrl, r as isObject, t as startHttpAndWs } from "../server-CD8XmBXl.mjs";
-export { DevframeAgentHost, DevframeDiagnosticsHost, DevframeServicesHostImpl, DevframeViewHost, coerceAgentPositionalArgs, createH3DevframeHost, createHostContext, createNodeSettings, createRpcSharedStateServerHost, createRpcStreamingServerHost, createScopedNodeContext, createStorage, formatHostForUrl, isObject, listLiveDevframeInstances, normalizeHttpServerUrl, registerDevframeInstance, startHttpAndWs, toDialableHost };
+import { t as createHostContext } from "../context-CEe4PBz1.mjs";
+import { t as createStorage } from "../storage-CYye7P7L.mjs";
+export { createHostContext, createStorage };

package/dist/nostics-CzECRXpE.mjs

@@ -0,0 +1,59 @@
+import { Diagnostic, createConsoleReporter, defineDiagnostics, defineProdDiagnostics, formatDiagnostic } from "nostics";
+import { ansiFormatter, ansiFormatter as ansiFormatter$1 } from "nostics/formatters/ansi";
+//#region src/utils/colors.ts
+function makeColor(open, close) {
+	const o = `\x1B[${open}m`;
+	const c = `\x1B[${close}m`;
+	return ((arg, ...values) => {
+		if (Array.isArray(arg) && "raw" in arg) {
+			const strings = arg;
+			let out = "";
+			for (let i = 0; i < strings.length; i++) {
+				out += strings[i];
+				if (i < values.length) out += String(values[i]);
+			}
+			return `${o}${out}${c}`;
+		}
+		return `${o}${String(arg)}${c}`;
+	});
+}
+const colors = {
+	blue: makeColor(34, 39),
+	cyan: makeColor(36, 39),
+	gray: makeColor(90, 39),
+	green: makeColor(32, 39),
+	red: makeColor(31, 39),
+	yellow: makeColor(33, 39),
+	bold: makeColor(1, 22),
+	dim: makeColor(2, 22),
+	reset: makeColor(0, 0),
+	underline: makeColor(4, 24)
+};
+//#endregion
+//#region src/utils/nostics.ts
+const formatAnsi = ansiFormatter(colors);
+/**
+* The reporter every {@link defineDiagnostics} call below wires in ahead of
+* any caller-supplied ones: prints the diagnostic through devframe's own
+* ANSI colors via `console[method]` (default `'warn'`).
+*/
+function devframeReporter(d, { method = "warn" } = {}) {
+	console[method](formatAnsi(d));
+}
+/**
+* Drop-in replacement for `nostics`'s `defineDiagnostics()` with devframe's
+* ANSI console reporter pre-wired ahead of any `reporters` passed in. Every
+* `diagnostics.ts` in devframe core, `@devframes/hub`, `@devframes/json-render`,
+* and the built-in plugins defines its codes through this instead of
+* `nostics`'s own `defineDiagnostics` — the reporter registration lives
+* here, once, so none of them need to build their own reporter (`colors`,
+* `ansiFormatter`) or take a direct dependency on `nostics` themselves.
+*/
+function defineDiagnostics$1(options) {
+	return defineDiagnostics({
+		...options,
+		reporters: [devframeReporter, ...options.reporters ?? []]
+	});
+}
+//#endregion
+export { defineProdDiagnostics as a, defineDiagnostics$1 as i, ansiFormatter$1 as n, formatDiagnostic as o, createConsoleReporter as r, colors as s, Diagnostic as t };

package/dist/nostics-SPGDgHEP.d.mts

@@ -0,0 +1,33 @@
+import { AnyDiagnosticReporter, AnyDiagnosticReporter as AnyDiagnosticReporter$1, ConsoleMethod, ConsoleReporterOptions, Diagnostic, Diagnostic as Diagnostic$1, DiagnosticCallParams, DiagnosticDefinition, DiagnosticDefinition as DiagnosticDefinition$1, DiagnosticHandle, DiagnosticInit, DiagnosticReporter, Diagnostics, Diagnostics as Diagnostics$1, createConsoleReporter, defineProdDiagnostics, formatDiagnostic } from "nostics";
+import { ansiFormatter } from "nostics/formatters/ansi";
+//#region src/utils/nostics.d.ts
+/**
+ * The reporter every {@link defineDiagnostics} call below wires in ahead of
+ * any caller-supplied ones: prints the diagnostic through devframe's own
+ * ANSI colors via `console[method]` (default `'warn'`).
+ */
+declare function devframeReporter(d: Diagnostic, { method }?: {
+  method?: 'log' | 'warn' | 'error';
+}): void;
+/**
+ * Options accepted by {@link defineDiagnostics} — identical to `nostics`'s
+ * own `DefineDiagnosticsOptions`, minus the reporter devframe already
+ * prepends.
+ */
+type DevframeDefineDiagnosticsOptions<Codes extends Record<string, DiagnosticDefinition>, Reporters extends readonly AnyDiagnosticReporter[] = []> = Parameters<typeof defineDiagnostics<Codes, Reporters>>[0];
+/**
+ * Drop-in replacement for `nostics`'s `defineDiagnostics()` with devframe's
+ * ANSI console reporter pre-wired ahead of any `reporters` passed in. Every
+ * `diagnostics.ts` in devframe core, `@devframes/hub`, `@devframes/json-render`,
+ * and the built-in plugins defines its codes through this instead of
+ * `nostics`'s own `defineDiagnostics` — the reporter registration lives
+ * here, once, so none of them need to build their own reporter (`colors`,
+ * `ansiFormatter`) or take a direct dependency on `nostics` themselves.
+ */
+declare function defineDiagnostics<const Codes extends Record<string, DiagnosticDefinition>, const Reporters extends readonly AnyDiagnosticReporter[] = []>(options: {
+  docsBase?: string | ((code: keyof Codes) => string | undefined);
+  codes: Codes;
+  reporters?: Reporters;
+}): Diagnostics<Codes, readonly [typeof devframeReporter, ...Reporters]>;
+//#endregion
+export { Diagnostic$1 as a, DiagnosticHandle as c, Diagnostics$1 as d, ansiFormatter as f, formatDiagnostic as g, defineProdDiagnostics as h, DevframeDefineDiagnosticsOptions as i, DiagnosticInit as l, defineDiagnostics as m, ConsoleMethod as n, DiagnosticCallParams as o, createConsoleReporter as p, ConsoleReporterOptions as r, DiagnosticDefinition$1 as s, AnyDiagnosticReporter$1 as t, DiagnosticReporter as u };

package/dist/recipes/common-rpc-functions.d.mts

@@ -1,7 +1,7 @@
-import "../devframe-mQ4qZAuo.mjs";
-import { E as Thenable, S as RpcFunctionSetupResult, c as RpcDump, g as RpcFunctionAgentOptions } from "../types-CnJSgRVa.mjs";
-import "../index-Dbw1p5ch.mjs";
-import { t as SimpleSchema } from "../simple-schema-BDzLeJDk.mjs";
+import "../devframe-DJMg0WLe.mjs";
+import "../index-tdrk1bzV.mjs";
+import { E as Thenable, S as RpcFunctionSetupResult, c as RpcDump, g as RpcFunctionAgentOptions } from "../types-Djq7CBXh.mjs";
+import { SimpleSchema } from "../utils/simple-schema.mjs";
 //#region src/recipes/common-rpc-functions.d.ts
 /**
  * Editor commands that `launch-editor` (the library behind

package/dist/recipes/interactive-auth.d.mts

@@ -1,5 +1,5 @@
-import { b as DevframeNodeContext, p as DevframeAuthHandler } from "../devframe-mQ4qZAuo.mjs";
-import "../index-b64Uuhy2.mjs";
+import { g as DevframeNodeContext, u as DevframeAuthHandler } from "../devframe-DJMg0WLe.mjs";
+import "../index-CB-fSUyn.mjs";
 //#region src/recipes/interactive-auth.d.ts
 interface CreateInteractiveAuthOptions {
   /**
@@ -44,7 +44,7 @@ interface CreateInteractiveAuthOptions {
  * auth.printBanner()
  *
  * // wire `auth.authorize` / `auth.onConnect` into your transport, or pass
- * // the whole handler to `startHttpAndWs({ auth, ... })`.
+ * // the whole handler to `initDevframe` / `initHub` via their `auth` option.
  * ```
  */
 declare function createInteractiveAuth(context: DevframeNodeContext, options?: CreateInteractiveAuthOptions): DevframeAuthHandler;

package/dist/recipes/interactive-auth.mjs

@@ -1,8 +1,8 @@
-import { n as colors } from "../diagnostics-reporter-CsIG85Q5.mjs";
-import { isAnonymousRpcMethod } from "../constants.mjs";
+import { s as colors } from "../nostics-CzECRXpE.mjs";
 import { n as defineRpcFunction } from "../define-BLWPsH6y.mjs";
-import { t as getInternalContext } from "../context-CBg8iRbQ.mjs";
-import { a as verifyAuthToken, n as exchangeTempAuthCode, r as getTempAuthCode, t as buildOtpAuthUrl } from "../state-BeUHDDjk.mjs";
+import { isAnonymousRpcMethod } from "../constants.mjs";
+import { a as verifyAuthToken, n as exchangeTempAuthCode, r as getTempAuthCode, t as buildOtpAuthUrl } from "../state-Cc1IeSmQ.mjs";
+import { t as getInternalContext } from "../context-xdynGSLP.mjs";
 import { t as s } from "../simple-schema-DQPZrAaZ.mjs";
 //#region src/recipes/interactive-auth.ts
 function defaultBanner(info) {
@@ -26,7 +26,7 @@ function defaultBanner(info) {
 * auth.printBanner()
 *
 * // wire `auth.authorize` / `auth.onConnect` into your transport, or pass
-* // the whole handler to `startHttpAndWs({ auth, ... })`.
+* // the whole handler to `initDevframe` / `initHub` via their `auth` option.
 * ```
 */
 function createInteractiveAuth(context, options = {}) {
@@ -105,14 +105,14 @@ function createInteractiveAuth(context, options = {}) {
 		if (isAnonymousRpcMethod(methodName)) return true;
 		return !!session.meta.isTrusted;
 	}
-	function onConnect(peer, session) {
+	function onConnect(connection, session) {
 		let token;
 		let requestOrigin;
 		try {
-			token = new URL(peer.request?.url ?? "", "http://localhost").searchParams.get("devframe_auth_token") ?? void 0;
+			token = new URL(connection.request?.url ?? "", "http://localhost").searchParams.get("devframe_auth_token") ?? void 0;
 		} catch {}
 		try {
-			requestOrigin = peer.request?.headers?.get?.("origin") ?? void 0;
+			requestOrigin = connection.request?.headers?.get?.("origin") ?? void 0;
 		} catch {}
 		if (!token) return;
 		if (isStaticToken(token)) {

package/dist/remote-assets-Bg4gCUZ_.d.mts

@@ -0,0 +1,123 @@
+//#region src/types/remote-assets.d.ts
+/**
+ * A version-locked pointer at browser assets published as their own npm
+ * package (e.g. `@devframes/plugin-git-client`), served through devframe's
+ * caching back-proxy instead of a directory shipped inside the node package.
+ *
+ * Resolution order at serve time:
+ *
+ *   1. The package installed locally (resolved from {@link resolveFrom})
+ *      — the zero-network / air-gap path. Version skew warns; a major
+ *      version mismatch throws.
+ *   2. The per-file cache under
+ *      `<storageDir project>/.remote-assets/<package>@<version>/`.
+ *   3. The CDN {@link provider} — each requested file streams through to
+ *      the browser while being written into the cache.
+ *
+ * Anywhere a static mount accepts a dist directory (`cli.distDir`,
+ * `hostStatic`, `mountStatic`) it also accepts this object — see
+ * {@link StaticAssetsSource}.
+ */
+interface RemoteAssets {
+  /** npm package name that ships the assets, e.g. `@devframes/plugin-git-client`. */
+  package: string;
+  /** Exact version to serve, e.g. `1.2.3`. Typically the host package's own version. */
+  version: string;
+  /**
+   * Subpath inside the package the served assets live under.
+   *
+   * @default 'dist'
+   */
+  path?: string;
+  /**
+   * CDN that mirrors npm and serves individual package files.
+   *
+   * @default 'jsdelivr'
+   */
+  provider?: RemoteAssetsProvider;
+  /**
+   * `import.meta.url` of the declaring module. When set, a locally
+   * installed copy of {@link package} is resolved from this module's own
+   * dependency graph first (works under pnpm's strict layout) and served
+   * with zero network. Omitting it skips the installed-package step —
+   * cache + CDN still work.
+   */
+  resolveFrom?: string | null;
+  /** Custom fetch implementation (proxies, tests). Defaults to the global `fetch`. */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Never touch the network: serve only from the locally installed package
+   * or files already in the cache.
+   *
+   * @default false
+   */
+  offline?: boolean;
+}
+/**
+ * Built-in CDN providers (`'jsdelivr'` — default, `'unpkg'`) or a custom
+ * provider for corp mirrors.
+ */
+type RemoteAssetsProvider = 'jsdelivr' | 'unpkg' | RemoteAssetsProviderCustom;
+/** A custom {@link RemoteAssets} CDN provider (e.g. an internal npm mirror). */
+interface RemoteAssetsProviderCustom {
+  /**
+   * Absolute URL serving `filePath` (package-relative, POSIX, no leading
+   * slash) of `pkg@version`.
+   */
+  fileUrl: (pkg: string, version: string, filePath: string) => string;
+  /**
+   * List every file path in `pkg@version` (package-relative, no leading
+   * slash). Powers request-path resolution (correct 404s / SPA fallback)
+   * and build-time materialization. When omitted, requests are resolved by
+   * probing {@link fileUrl} directly and builds cannot materialize from
+   * this provider.
+   */
+  listFiles?: (pkg: string, version: string, fetchImpl: typeof globalThis.fetch) => Promise<string[]>;
+}
+/**
+ * What every static-assets seam accepts: a local dist directory, or a
+ * {@link RemoteAssets} pointer served through the caching back-proxy.
+ */
+type StaticAssetsSource = string | RemoteAssets;
+/**
+ * What the remote-assets fallback page posts to `window.parent` when a
+ * devframe's client assets could be served from neither a local install nor
+ * their provider. A viewer embedding the devframe in an iframe listens for
+ * `DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE` (`devframe/constants`) and can
+ * render the failure in its own design, with the two ways out the page also
+ * spells out: install `package@version` locally, or restore network access.
+ */
+interface RemoteAssetsErrorMessage {
+  type: 'devframe:remote-assets-error';
+  /** npm package the assets are published as. */
+  package: string;
+  /** Exact version the devframe asked for. */
+  version: string;
+  /** Why the fetch failed, as reported by the provider or the network stack. */
+  reason: string;
+}
+/**
+ * A resolved, servable handle over a {@link RemoteAssets} declaration —
+ * produced by `resolveStaticAssetsSource()` (`devframe/utils/remote-assets`)
+ * and consumed by the static-serving engine (`devframe/utils/serve-static`).
+ */
+interface RemoteAssetsStore {
+  /** The declaration this store serves (with defaults applied). */
+  readonly assets: RemoteAssets & {
+    path: string;
+  };
+  /**
+   * Resolve a request path (relative to the mount base, SPA fallback to
+   * `index.html`) and return a `Response`: streamed from the cache when
+   * present, otherwise through the provider while being written into the
+   * cache. `null` on a miss (404); throws on provider/network failure.
+   */
+  serve: (urlPath: string) => Promise<Response | null>;
+  /**
+   * Download every listed file under `assets.path` into `targetDir`
+   * (paths relative to `assets.path`). Requires a provider file listing.
+   */
+  materialize: (targetDir: string) => Promise<void>;
+}
+//#endregion
+export { RemoteAssetsStore as a, RemoteAssetsProviderCustom as i, RemoteAssetsErrorMessage as n, StaticAssetsSource as o, RemoteAssetsProvider as r, RemoteAssets as t };