devframe 0.9.11 → 0.9.13

package/dist/in-page-channel/index.d.mts

@@ -9,9 +9,9 @@ import { BirpcReturn } from "birpc";
  * channel-name constant declared next to it.
  */
 interface InPageChannelProtocol {
-  /** Functions implemented by the page script, callable by panels. */
+  /** Functions and events received by the page script. */
   pageScript?: Record<string, (...args: any[]) => any>;
-  /** Functions implemented by panels, callable by the page script. */
+  /** Functions and events received by panels. */
   panel?: Record<string, (...args: any[]) => any>;
   /**
    * Shared-state slots. The page script is the authority: it owns the
@@ -26,6 +26,16 @@ type PanelFunctions<P extends InPageChannelProtocol> = SideFunctions<NonNullable
 type SharedStates<P extends InPageChannelProtocol> = P['sharedStates'] extends Record<string, object> ? P['sharedStates'] : Record<string, never>;
 type FnArgs<F> = F extends ((...args: infer A) => any) ? A : never;
 type FnReturn<F> = F extends ((...args: any[]) => infer R) ? Awaited<R> : never;
+/**
+ * Page-script functions whose resolved return type marks an event.
+ * @internal
+ */
+type PageScriptFunctionsEvents<P extends InPageChannelProtocol> = { [K in keyof PageScriptFunctions<P> as FnReturn<PageScriptFunctions<P>[K]> extends void ? K : never]: PageScriptFunctions<P>[K]; };
+/**
+ * Panel functions whose resolved return type marks an event.
+ * @internal
+ */
+type PanelFunctionsEvents<P extends InPageChannelProtocol> = { [K in keyof PanelFunctions<P> as FnReturn<PanelFunctions<P>[K]> extends void ? K : never]: PanelFunctions<P>[K]; };
 /**
  * Converts a protocol function to its accepted endpoint handler.
  *
@@ -38,46 +48,69 @@ type ProtocolHandler<F> = F extends ((...args: any[]) => any) ? (...args: FnArgs
  * fan-out), `action` performs, `query` requests data (the default).
  */
 type InPageFunctionType = 'action' | 'event' | 'query';
-/**
- * An in-page channel function definition: the `defineRpcFunction` authoring
- * shape (`name`, `type`, Standard-Schema `args`/`returns`,
- * `jsonSerializable`, `handler`) narrowed to the browser: there is no
- * `dump`/`snapshot`/`cacheable`/`agent`. When `jsonSerializable` is `true`,
- * payloads are strictly validated at the receiving endpoint and misshapen
- * values reject the call with a descriptive `InPageChannelError` instead of
- * a cryptic `DataCloneError` in the port.
- */
-type InPageFunctionDefinition<NAME extends string, TYPE extends InPageFunctionType = 'query', ARGS extends any[] = [], RETURN = void, AS extends RpcArgsSchema | undefined = undefined, RS extends RpcReturnSchema | undefined = undefined> = [AS, RS] extends [undefined, undefined] ? {
+interface InPageFunctionDefinitionBase<NAME extends string> {
   name: NAME;
-  type?: TYPE;
+  jsonSerializable?: boolean;
+}
+interface InPageEventFunctionDefinition<NAME extends string, HANDLER> extends InPageFunctionDefinitionBase<NAME> {
+  type: 'event';
+  handler?: HANDLER;
+}
+interface InPageQueryFunctionDefinition<NAME extends string, HANDLER> extends InPageFunctionDefinitionBase<NAME> {
+  type?: 'query';
+  handler: HANDLER;
+}
+interface InPageActionFunctionDefinition<NAME extends string, HANDLER> extends InPageFunctionDefinitionBase<NAME> {
+  type: 'action';
+  handler: HANDLER;
+}
+type InPageFunctionDefinitionForType<NAME extends string, TYPE extends InPageFunctionType, HANDLER> = TYPE extends 'event' ? InPageEventFunctionDefinition<NAME, HANDLER> : TYPE extends 'action' ? InPageActionFunctionDefinition<NAME, HANDLER> : InPageQueryFunctionDefinition<NAME, HANDLER>;
+type InPageFunctionDefinitionSchemas<AS extends RpcArgsSchema | undefined, RS extends RpcReturnSchema | undefined> = [AS, RS] extends [undefined, undefined] ? {
   args?: AS;
   returns?: RS;
-  jsonSerializable?: boolean;
-  handler: (...args: ARGS) => RETURN;
 } : {
-  name: NAME;
-  type?: TYPE;
   /** Standard Schema array validating (and typing) the arguments. */
   args: AS;
   /** Standard Schema typing the resolved return value. */
   returns: RS;
-  jsonSerializable?: boolean;
-  handler: (...args: InferArgsType<AS>) => Thenable<InferReturnType<RS>>;
 };
+type InPageFunctionDefinitionHandler<ARGS extends any[], RETURN, AS extends RpcArgsSchema | undefined, RS extends RpcReturnSchema | undefined> = [AS, RS] extends [undefined, undefined] ? (...args: ARGS) => RETURN : (...args: InferArgsType<AS>) => Thenable<InferReturnType<RS>>;
+/**
+ * An in-page channel function definition: the `defineRpcFunction` authoring
+ * shape (`name`, `type`, Standard-Schema `args`/`returns`,
+ * `jsonSerializable`, `handler`) narrowed to the browser: there is no
+ * `dump`/`snapshot`/`cacheable`/`agent`. When `jsonSerializable` is `true`,
+ * payloads are strictly validated at the receiving endpoint and misshapen
+ * values reject the call with a descriptive `InPageChannelError` instead of
+ * a cryptic `DataCloneError` in the port. Event definitions may omit their
+ * handler when runtime listeners subscribe through `channel.on()`.
+ */
+type InPageFunctionDefinition<NAME extends string, TYPE extends InPageFunctionType = 'query', ARGS extends any[] = [], RETURN = void, AS extends RpcArgsSchema | undefined = undefined, RS extends RpcReturnSchema | undefined = undefined> = InPageFunctionDefinitionForType<NAME, TYPE, InPageFunctionDefinitionHandler<ARGS, RETURN, AS, RS>> & InPageFunctionDefinitionSchemas<AS, RS>;
 /**
  * Function metadata with its handler constrained by a protocol function.
  *
  * @internal
  */
-interface InPageFunctionOption<F> {
-  type?: InPageFunctionType;
+interface InPageFunctionOptionBase {
   /** Optional Standard Schema array validating the arguments. */
   args?: RpcArgsSchema;
   /** Optional Standard Schema validating the resolved return value. */
   returns?: RpcReturnSchema;
   jsonSerializable?: boolean;
+}
+interface InPageEventFunctionOption<F> extends InPageFunctionOptionBase {
+  type: 'event';
+  handler?: ProtocolHandler<F>;
+}
+interface InPageQueryFunctionOption<F> extends InPageFunctionOptionBase {
+  type?: 'query';
   handler: ProtocolHandler<F>;
 }
+interface InPageActionFunctionOption<F> extends InPageFunctionOptionBase {
+  type: 'action';
+  handler: ProtocolHandler<F>;
+}
+type InPageFunctionOption<F> = InPageEventFunctionOption<F> | InPageQueryFunctionOption<F> | InPageActionFunctionOption<F>;
 /**
  * Functions implemented by {@link createPageScriptChannel}.
  *
@@ -140,7 +173,7 @@ interface InPageChannelCommonOptions {
 }
 /** Options for {@link createPageScriptChannel}. */
 interface CreatePageScriptChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
-  /** Implementations of the protocol's page-script functions. */
+  /** Every page-script function declaration; event handlers may use `channel.on()`. */
   functions: CreatePageScriptChannelOptionsFunctions<Protocol>;
   /**
    * Window whose `message` events carry panel hellos. Defaults to the
@@ -151,7 +184,7 @@ interface CreatePageScriptChannelOptions<Protocol extends InPageChannelProtocol
 }
 /** Options for {@link connectPanelChannel}. */
 interface ConnectPanelChannelOptions<Protocol extends InPageChannelProtocol = InPageChannelProtocol> extends InPageChannelCommonOptions {
-  /** Implementations of the protocol's panel functions. */
+  /** Every panel function declaration; event handlers may use `channel.on()`. */
   functions: ConnectPanelChannelOptionsFunctions<Protocol>;
   /**
    * The panel's own window (listens for the handshake grant). Defaults to
@@ -181,7 +214,7 @@ interface ConnectPanelChannelOptions<Protocol extends InPageChannelProtocol = In
    */
   helloIntervalMs?: number;
   /**
-   * Maximum `callEvent` payloads buffered while `connecting`, flushed on
+   * Maximum `emit` payloads buffered while `connecting`, flushed on
    * connect; when full, the oldest is dropped with a console warning.
    * @default 64
    */
@@ -228,11 +261,12 @@ interface PageScriptChannel<P extends InPageChannelProtocol> {
   /** Currently connected panels. */
   readonly panels: readonly PanelPeer<P>[];
   readonly events: Pick<EventEmitter<PageScriptChannelEvents<P>>, 'on' | 'once'>;
-  /**
-   * Fan a fire-and-forget event out to every connected panel; panels that
-   * don't implement the function ignore it.
-   */
-  callEvent: <K extends keyof PanelFunctions<P> & string>(name: K, ...args: FnArgs<PanelFunctions<P>[K]>) => void;
+  /** Fan an event out to every connected panel. */
+  emit: <K extends keyof PanelFunctionsEvents<P> & string>(name: K, ...args: FnArgs<PanelFunctionsEvents<P>[K]>) => void;
+  /** @deprecated Use `emit()` instead. */
+  callEvent: <K extends keyof PanelFunctionsEvents<P> & string>(name: K, ...args: FnArgs<PanelFunctionsEvents<P>[K]>) => void;
+  /** Subscribe to an event emitted by a panel. Returns an unsubscribe function. */
+  on: <K extends keyof PageScriptFunctionsEvents<P> & string>(name: K, listener: (...args: FnArgs<PageScriptFunctionsEvents<P>[K]>) => void) => () => void;
   /** Page-script-authoritative shared states, replayed to joining panels. */
   readonly sharedState: InPageSharedStateHost<P>;
   /** Adopt a pre-established port as a panel peer (bring-your-own transport). */
@@ -270,10 +304,14 @@ interface PanelChannel<P extends InPageChannelProtocol> {
    */
   call: <K extends keyof PageScriptFunctions<P> & string>(name: K, ...args: FnArgs<PageScriptFunctions<P>[K]>) => Promise<FnReturn<PageScriptFunctions<P>[K]>>;
   /**
-   * Fire-and-forget to the page script. While `connecting` the event is
-   * buffered (up to `eventBufferLimit`) and flushed on connect.
+   * Emit an event to the page script. While `connecting` the event is buffered
+   * (up to `eventBufferLimit`) and flushed on connect.
    */
-  callEvent: <K extends keyof PageScriptFunctions<P> & string>(name: K, ...args: FnArgs<PageScriptFunctions<P>[K]>) => void;
+  emit: <K extends keyof PageScriptFunctionsEvents<P> & string>(name: K, ...args: FnArgs<PageScriptFunctionsEvents<P>[K]>) => void;
+  /** @deprecated Use `emit()` instead. */
+  callEvent: <K extends keyof PageScriptFunctionsEvents<P> & string>(name: K, ...args: FnArgs<PageScriptFunctionsEvents<P>[K]>) => void;
+  /** Subscribe to an event emitted by the page script. Returns an unsubscribe function. */
+  on: <K extends keyof PanelFunctionsEvents<P> & string>(name: K, listener: (...args: FnArgs<PanelFunctionsEvents<P>[K]>) => void) => () => void;
   /** Shared states mirrored from the page-script authority. */
   readonly sharedState: InPageSharedStateHost<P>;
   /** Tear the endpoint down permanently. */
@@ -294,7 +332,7 @@ type InPageChannelErrorCode = 'timeout' |
 /** A shared-state key was first accessed without its initial value. */
 'state-uninitialized';
 /** A coded in-page channel error; every failure mode carries a stable `code`. */
-declare class InPageChannelError extends Error {
+export declare class InPageChannelError extends Error {
   readonly code: InPageChannelErrorCode;
   name: string;
   constructor(code: InPageChannelErrorCode, message: string, options?: {
@@ -312,7 +350,7 @@ declare class InPageChannelError extends Error {
  * panels all handshake the same way, and a panel reload is simply a new
  * handshake. No server is involved at any point.
  */
-declare function createPageScriptChannel<P extends InPageChannelProtocol>(options: CreatePageScriptChannelOptions<P>): PageScriptChannel<P>;
+export declare function createPageScriptChannel<P extends InPageChannelProtocol>(options: CreatePageScriptChannelOptions<P>): PageScriptChannel<P>;
 //#endregion
 //#region src/in-page-channel/panel.d.ts
 /**
@@ -327,7 +365,7 @@ declare function createPageScriptChannel<P extends InPageChannelProtocol>(option
  * (e.g. the panel opened standalone), the endpoint stays `connecting` and
  * the UI can key a fallback state off `status` / `whenConnected()`.
  */
-declare function connectPanelChannel<P extends InPageChannelProtocol>(options: ConnectPanelChannelOptions<P>): PanelChannel<P>;
+export declare function connectPanelChannel<P extends InPageChannelProtocol>(options: ConnectPanelChannelOptions<P>): PanelChannel<P>;
 //#endregion
 //#region src/in-page-channel/index.d.ts
 /**
@@ -338,6 +376,6 @@ declare function connectPanelChannel<P extends InPageChannelProtocol>(options: C
  * shared protocol file carries only the contract type and the channel-name
  * constant.
  */
-declare function defineChannelFunction<NAME extends string, TYPE extends InPageFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(definition: InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>): InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>;
+export declare function defineChannelFunction<NAME extends string, TYPE extends InPageFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(definition: InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>): InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>;
 //#endregion
-export { type ConnectPanelChannelOptions, type CreatePageScriptChannelOptions, InPageChannelError, type InPageChannelErrorCode, type InPageChannelProtocol, type InPageChannelStatus, type InPageFunctionDefinition, type PageScriptChannel, type PanelChannel, type PanelPeer, connectPanelChannel, createPageScriptChannel, defineChannelFunction };
+export type { ConnectPanelChannelOptions, CreatePageScriptChannelOptions, InPageChannelErrorCode, InPageChannelProtocol, InPageChannelStatus, InPageFunctionDefinition, PageScriptChannel, PanelChannel, PanelPeer };

package/dist/in-page-channel/index.mjs

@@ -1,8 +1,17 @@
-import { t as DEVFRAME_EVENTS } from "../events-BV4Dj59a.mjs";
+import { n as DEVFRAME_EVENTS, t as defineDiagnostics } from "../nostics-DD6gsDZA.mjs";
 import { createEventEmitter } from "../utils/events.mjs";
-import { t as createSharedState } from "../shared-state-CaxB1q0h.mjs";
+import { t as createSharedState } from "../shared-state-eQVYHNqA.mjs";
 import { nanoid } from "../utils/nanoid.mjs";
 import { createBirpc } from "birpc";
+//#region src/in-page-channel/diagnostics.ts
+const diagnostics = /* #__PURE__ */ defineDiagnostics({
+	docsBase: "https://devfra.me/errors",
+	codes: { DF0077: {
+		why: (p) => `In-page channel function "${p.name}" is not registered on this endpoint.`,
+		fix: "Declare the function in this endpoint's `functions` option before subscribing with `on()`."
+	} }
+});
+//#endregion
 //#region src/in-page-channel/protocol.ts
 /**
 * Wire protocol of the in-page channel handshake and its port-level control
@@ -167,19 +176,39 @@ function deserializeResult(codec, result) {
 * then serialize hook + `jsonSerializable` enforcement on the result.
 */
 function createLocalFunctionRegistry(codec) {
-	const wrapped = /* @__PURE__ */ new Map();
+	const definitions = /* @__PURE__ */ new Map();
+	const listeners = /* @__PURE__ */ new Map();
 	return {
 		register(definition) {
-			wrapped.set(definition.name, async (...rawArgs) => {
+			definitions.set(definition.name, definition);
+		},
+		on(name, listener) {
+			if (!definitions.has(name)) throw diagnostics.DF0077({ name });
+			let registered = listeners.get(name);
+			if (!registered) {
+				registered = /* @__PURE__ */ new Set();
+				listeners.set(name, registered);
+			}
+			registered.add(listener);
+			return () => {
+				registered.delete(listener);
+				if (registered.size === 0) listeners.delete(name);
+			};
+		},
+		resolve(name) {
+			const definition = definitions.get(name);
+			const registered = listeners.get(name);
+			if (!definition && !registered?.size) return void 0;
+			return async (...rawArgs) => {
 				const args = codec.deserialize ? rawArgs.map(codec.deserialize) : rawArgs;
-				if (definition.jsonSerializable) assertJsonSerializable(args, "its arguments", definition.name);
-				if (definition.args?.length) await validateArgs(definition.name, definition.args, args);
-				const result = await definition.handler(...args);
-				if (definition.jsonSerializable) assertJsonSerializable(result, "its return value", definition.name);
+				if (definition?.jsonSerializable) assertJsonSerializable(args, "its arguments", definition.name);
+				if (definition?.args?.length) await validateArgs(definition.name, definition.args, args);
+				const result = await definition?.handler?.(...args);
+				for (const listener of [...listeners.get(name) ?? []]) listener(...args);
+				if (definition?.jsonSerializable) assertJsonSerializable(result, "its return value", definition.name);
 				return codec.serialize && result !== void 0 ? codec.serialize(result) : result;
-			});
-		},
-		resolve: (name) => wrapped.get(name)
+			};
+		}
 	};
 }
 function wrapPostError(error) {
@@ -449,7 +478,7 @@ function createPageScriptChannel(options) {
 	let closed = false;
 	let heartbeatTimer;
 	const registry = createLocalFunctionRegistry(codec);
-	for (const [fnName, definition] of Object.entries(options.functions ?? {})) registry.register({
+	for (const [fnName, definition] of Object.entries(options.functions)) registry.register({
 		...definition,
 		name: fnName
 	});
@@ -550,6 +579,15 @@ function createPageScriptChannel(options) {
 		}
 	};
 	win?.addEventListener("message", onWindowMessage);
+	const emit = (fnName, ...args) => {
+		const wireArgs = serializeArgs(codec, args);
+		for (const peer of peers.values()) peer.attached.rpc.$callRaw({
+			method: fnName,
+			args: wireArgs,
+			event: true,
+			optional: true
+		}).catch(() => {});
+	};
 	return {
 		name,
 		instanceId,
@@ -560,15 +598,9 @@ function createPageScriptChannel(options) {
 			on: events.on,
 			once: events.once
 		},
-		callEvent: (fnName, ...args) => {
-			const wireArgs = serializeArgs(codec, args);
-			for (const peer of peers.values()) peer.attached.rpc.$callRaw({
-				method: fnName,
-				args: wireArgs,
-				event: true,
-				optional: true
-			}).catch(() => {});
-		},
+		emit,
+		callEvent: emit,
+		on: (fnName, listener) => registry.on(fnName, listener),
 		sharedState: stateHost,
 		addPanelPort: (port) => addPeer(port, `transport:${nanoid(8)}`),
 		close: () => {
@@ -615,7 +647,7 @@ function connectPanelChannel(options) {
 	const canHandshake = !!win && targets.length > 0;
 	const events = createEventEmitter();
 	const registry = createLocalFunctionRegistry(codec);
-	for (const [fnName, definition] of Object.entries(options.functions ?? {})) registry.register({
+	for (const [fnName, definition] of Object.entries(options.functions)) registry.register({
 		...definition,
 		name: fnName
 	});
@@ -794,7 +826,9 @@ function connectPanelChannel(options) {
 			});
 		},
 		call: (fnName, ...args) => enqueueCall(fnName, serializeArgs(codec, args)),
+		emit: (fnName, ...args) => sendEvent(fnName, serializeArgs(codec, args)),
 		callEvent: (fnName, ...args) => sendEvent(fnName, serializeArgs(codec, args)),
+		on: (fnName, listener) => registry.on(fnName, listener),
 		sharedState: stateHost,
 		close: () => {
 			if (status === "closed") return;

package/dist/index.d.mts

@@ -5,17 +5,17 @@ import { $ as DevframeServiceOf, At as AgentHandle, B as DevframeSetupInfo, Bt a
 import { a as RemoteAssetsStore, i as RemoteAssetsProviderCustom, n as RemoteAssetsErrorMessage, o as StaticAssetsSource, r as RemoteAssetsProvider, t as RemoteAssets } from "./remote-assets-eBvSKZMS.mjs";
 import { i as DevframeDefineDiagnosticsOptions } from "./nostics-0sKe5HIj.mjs";
 //#region src/define.d.ts
-declare const defineRpcFunction: <NAME extends string, TYPE extends RpcFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(definition: RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeNodeContext>) => RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeNodeContext>;
+export declare const defineRpcFunction: <NAME extends string, TYPE extends RpcFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(definition: RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeNodeContext>) => RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeNodeContext>;
 /**
  * Identity helper that types a devframe definition, the primary authoring
  * entry point. Import it from the package root: `import { defineDevframe } from 'devframe'`.
  */
-declare function defineDevframe(d: DevframeDefinition): DevframeDefinition;
+export declare function defineDevframe(d: DevframeDefinition): DevframeDefinition;
 /**
  * @deprecated Read {@link DevframeDefinition.clientAssets} from the definition
  * directly. This helper is internal machinery that was never meant to be part
  * of the public API and is scheduled for removal.
  */
-declare function resolveClientAssets(d: DevframeDefinition): StaticAssetsSource | undefined;
+export declare function resolveClientAssets(d: DevframeDefinition): StaticAssetsSource | undefined;
 //#endregion
-export { type AgentHandle, type AgentManifest, type AgentResource, type AgentResourceContent, type AgentResourceInput, type AgentTool, type AgentToolInput, type AgentToolProvider, type AgentToolProviderHandle, type ConnectionMeta, type ConnectionMetaSse, type ConnectionMetaWebsocket, type DevframeAgentHost, type DevframeAgentHostEvents, type DevframeCapabilities, type DevframeCliOptions, type DevframeConnectionConfigsRegistry, type DevframeDefineDiagnosticsOptions, type DevframeDefinition, type DevframeDeploymentKind, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, type DevframeDockDefaults, type DevframeDuplicationStrategy, type DevframeHost, type DevframeNodeContext, type DevframeNodeRpcSession, type DevframeNodeRpcSessionMeta, type DevframeRpcClientFunctions, type DevframeRpcConnection, type DevframeRpcConnectionRequest, type DevframeRpcOptions, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, type DevframeRpcTransportKind, type DevframeScopedNodeContext, type DevframeScopedNodeRpc, type DevframeScopedStreamingHost, type DevframeServiceDefinition, type DevframeServiceDescriptor, type DevframeServiceId, type DevframeServiceInput, type DevframeServiceMeta, type DevframeServiceOf, type DevframeServiceScopeOf, type DevframeServicesHost, type DevframeServicesRegistry, type DevframeServicesScopeRegistry, type DevframeServicesState, type DevframeSettings, type DevframeSettingsRegistry, type DevframeSettingsStore, type DevframeSetupInfo, type DevframeSnapshotRpcEntry, type DevframeSnapshotRpcInputs, type DevframeSseOptions, type DevframeStorageScope, type DevframeViewHost, type DevframeWsOptions, type EventEmitter, type EventUnsubscribe, type EventsMap, type McpAuthorization, type McpRouteOptions, type McpSetting, type RemoteAssets, type RemoteAssetsErrorMessage, type RemoteAssetsProvider, type RemoteAssetsProviderCustom, type RemoteAssetsStore, type RpcBroadcastOptions, type RpcFunctionAgentOptions, type RpcFunctionsHost, type RpcSharedStateGetOptions, type RpcSharedStateHost, type RpcStreamingChannel, type RpcStreamingChannelOptions, type RpcStreamingHost, type ScopedBroadcastOptions, type ScopedClientFunctions, type ScopedRpcFn, type ScopedServerFunctions, type ScopedSharedStates, type SettingsForNamespace, type StaticAssetsSource, defineDevframe, defineRpcFunction, resolveClientAssets };
+export type { AgentHandle, AgentManifest, AgentResource, AgentResourceContent, AgentResourceInput, AgentTool, AgentToolInput, AgentToolProvider, AgentToolProviderHandle, ConnectionMeta, ConnectionMetaSse, ConnectionMetaWebsocket, DevframeAgentHost, DevframeAgentHostEvents, DevframeCapabilities, DevframeCliOptions, DevframeConnectionConfigsRegistry, DevframeDefineDiagnosticsOptions, DevframeDefinition, DevframeDeploymentKind, DevframeDiagnosticsHost, DevframeDiagnosticsLogger, DevframeDockDefaults, DevframeDuplicationStrategy, DevframeHost, DevframeNodeContext, DevframeNodeRpcSession, DevframeNodeRpcSessionMeta, DevframeRpcClientFunctions, DevframeRpcConnection, DevframeRpcConnectionRequest, DevframeRpcOptions, DevframeRpcServerFunctions, DevframeRpcSharedStates, DevframeRpcTransportKind, DevframeScopedNodeContext, DevframeScopedNodeRpc, DevframeScopedStreamingHost, DevframeServiceDefinition, DevframeServiceDescriptor, DevframeServiceId, DevframeServiceInput, DevframeServiceMeta, DevframeServiceOf, DevframeServiceScopeOf, DevframeServicesHost, DevframeServicesRegistry, DevframeServicesScopeRegistry, DevframeServicesState, DevframeSettings, DevframeSettingsRegistry, DevframeSettingsStore, DevframeSetupInfo, DevframeSnapshotRpcEntry, DevframeSnapshotRpcInputs, DevframeSseOptions, DevframeStorageScope, DevframeViewHost, DevframeWsOptions, EventEmitter, EventUnsubscribe, EventsMap, McpAuthorization, McpRouteOptions, McpSetting, RemoteAssets, RemoteAssetsErrorMessage, RemoteAssetsProvider, RemoteAssetsProviderCustom, RemoteAssetsStore, RpcBroadcastOptions, RpcFunctionAgentOptions, RpcFunctionsHost, RpcSharedStateGetOptions, RpcSharedStateHost, RpcStreamingChannel, RpcStreamingChannelOptions, RpcStreamingHost, ScopedBroadcastOptions, ScopedClientFunctions, ScopedRpcFn, ScopedServerFunctions, ScopedSharedStates, SettingsForNamespace, StaticAssetsSource };

package/dist/{instance-shell-BWh0JQuo.d.mts → instance-shell-BUyYrKlu.d.mts}

@@ -150,8 +150,15 @@ interface CreateInstanceShellOptions<TContext extends DevframeNodeContext> {
   app?: H3;
   /** Public origin, or a getter. Derived from the first request when omitted. */
   origin?: string | (() => string);
-  /** Resolved auth intent: `undefined`/`true` gates, `false` opts out, a handler installs a scheme. */
-  auth?: boolean | DevframeAuthHandler;
+  /**
+   * Resolved auth intent: `undefined`/`true` gates with {@link createInteractiveAuth}'s
+   * defaults, `false` opts out, a handler installs a custom scheme outright.
+   * A function gates too, but builds the handler itself from the now-ready
+   * `ctx` - the seam a wrapping host (e.g. `@devframes/hub`'s UI slot) uses to
+   * hand `createInteractiveAuth` a branded `banner` while still leaving `auth`
+   * itself unset for the caller.
+   */
+  auth?: boolean | DevframeAuthHandler | ((ctx: TContext) => DevframeAuthHandler);
   /** Host `node:http` server to share the WS upgrade with. */
   server?: Server;
   /** Explicit WebSocket control; see {@link DevframeWsOptions}. `false` disables the socket (SSE-only). */

package/dist/{instance-shell-DvYCwrDy.mjs → instance-shell-xuu6jg51.mjs}

@@ -366,11 +366,16 @@ function createInstanceShell(options) {
 	};
 	/**
 	* Auth resolution: gate by default, `false` opts out, a handler object
-	* installs a custom scheme. The `external` tier has no local transport to
-	* gate (the server behind `ws.url` owns auth) so it resolves to nothing.
+	* installs a custom scheme, a function builds one from `ctx`. The `external`
+	* tier has no local transport to gate (the server behind `ws.url` owns
+	* auth) so it resolves to nothing.
 	*/
 	function resolveAuth() {
 		if (options.auth === false) return false;
+		if (typeof options.auth === "function") {
+			authHandler = options.auth(ctx);
+			return authHandler;
+		}
 		if (typeof options.auth === "object") {
 			authHandler = options.auth;
 			return options.auth;

package/dist/internal/index.d.mts

@@ -1,7 +1,7 @@
 import { v as RpcFunctionDefinitionAny } from "../types-Dq4i156u.mjs";
 import { At as AgentHandle, Bt as DevframeAgentHostEvents, F as DevframeDefinition, Ft as AgentTool, It as AgentToolInput, Lt as AgentToolProvider, Mt as AgentResource, Nt as AgentResourceContent, Pt as AgentResourceInput, Rt as AgentToolProviderHandle, Vt as EventEmitter, jt as AgentManifest, o as DevframeNodeContext, xt as DevframeHost, zt as DevframeAgentHost$1 } from "../context-BBWPLDHh.mjs";
 import { a as RemoteAssetsStore, o as StaticAssetsSource } from "../remote-assets-eBvSKZMS.mjs";
-import { a as InstanceShellInit, c as StartedServer, d as samePath, f as DevframeInstanceRecord, h as registerDevframeInstance, i as InstanceShellApi, l as createInstanceShell, m as listLiveDevframeInstances, n as InstanceRegisterConfig, o as InstanceShellInternals, p as DevframeInstanceRegistration, r as InstanceShell, s as InstanceWsTier, t as CreateInstanceShellOptions, u as resolveInstanceRegister } from "../instance-shell-BWh0JQuo.mjs";
+import { a as InstanceShellInit, c as StartedServer, d as samePath, f as DevframeInstanceRecord, h as registerDevframeInstance, i as InstanceShellApi, l as createInstanceShell, m as listLiveDevframeInstances, n as InstanceRegisterConfig, o as InstanceShellInternals, p as DevframeInstanceRegistration, r as InstanceShell, s as InstanceWsTier, t as CreateInstanceShellOptions, u as resolveInstanceRegister } from "../instance-shell-BUyYrKlu.mjs";
 import { a as resolveBasePath, i as normalizeBasePath, n as ResolvedMcpConfig, r as loadAutoMcpAdapter, s as resolveMcpConfig } from "../_shared-DEAMiPfH.mjs";
 import { n as CreateContextRpcServerOptions, r as createContextRpcServer, t as ContextRpcServer } from "../rpc-core-DiCr5etS.mjs";
 //#region src/client-assets.d.ts
@@ -15,7 +15,7 @@ import { n as CreateContextRpcServerOptions, r as createContextRpcServer, t as C
  * Internal: exposed to first-party integrations via `devframe/internal`, not
  * part of the stable public API.
  */
-declare function resolveClientAssets(d: DevframeDefinition): StaticAssetsSource | undefined;
+export declare function resolveClientAssets(d: DevframeDefinition): StaticAssetsSource | undefined;
 //#endregion
 //#region src/node/agent-args.d.ts
 /**
@@ -43,7 +43,7 @@ type AgentArgsFallback = 'wrap' | 'drop';
  * - an empty object becomes a zero-argument call
  * - anything else follows the {@link AgentArgsFallback}
  */
-declare function coerceAgentPositionalArgs(args: unknown, schemas: readonly unknown[] | undefined, fallback?: AgentArgsFallback): unknown[];
+export declare function coerceAgentPositionalArgs(args: unknown, schemas: readonly unknown[] | undefined, fallback?: AgentArgsFallback): unknown[];
 //#endregion
 //#region src/node/diagnostics.d.ts
 /**
@@ -51,7 +51,7 @@ declare function coerceAgentPositionalArgs(args: unknown, schemas: readonly unkn
  * owns DF0037–DF0041), so this file alone doesn't show the next free
  * number; check `docs/content/6.errors/` for the full allocation before adding one.
  */
-declare const diagnostics: import("nostics").Diagnostics<{
+export declare const diagnostics: import("nostics").Diagnostics<{
   readonly DF0006: {
     readonly why: (p: {
       name: string;
@@ -363,7 +363,7 @@ declare const diagnostics: import("nostics").Diagnostics<{
  * `ctx.rpc.definitions`, and accepts plugin-registered tools /
  * resources via `registerTool` / `registerResource`.
  */
-declare class DevframeAgentHost implements DevframeAgentHost$1 {
+export declare class DevframeAgentHost implements DevframeAgentHost$1 {
   readonly context: DevframeNodeContext;
   readonly events: EventEmitter<DevframeAgentHostEvents>;
   private readonly tools;
@@ -393,7 +393,7 @@ declare class DevframeAgentHost implements DevframeAgentHost$1 {
 }
 //#endregion
 //#region src/node/host-h3.d.ts
-interface CreateH3DevframeHostOptions {
+export interface CreateH3DevframeHostOptions {
   /**
    * Host the standalone server listens on, e.g. `http://localhost:9999`.
    * Consumed by `resolveOrigin` for dock entries that need an absolute URL.
@@ -427,7 +427,7 @@ interface CreateH3DevframeHostOptions {
 /**
  * h3-backed {@link DevframeHost}, used by the standalone CLI adapter.
  */
-declare function createH3DevframeHost(options: CreateH3DevframeHostOptions): DevframeHost;
+export declare function createH3DevframeHost(options: CreateH3DevframeHostOptions): DevframeHost;
 //#endregion
 //#region src/node/import-runtime-module.d.ts
 /**
@@ -438,10 +438,10 @@ declare function createH3DevframeHost(options: CreateH3DevframeHostOptions): Dev
  *
  * @internal
  */
-declare function importRuntimeModule<T = unknown>(specifier: string): Promise<T>;
+export declare function importRuntimeModule<T = unknown>(specifier: string): Promise<T>;
 //#endregion
 //#region src/node/utils.d.ts
-declare function normalizeHttpServerUrl(host: string, port: number | string): string;
+export declare function normalizeHttpServerUrl(host: string, port: number | string): string;
 //#endregion
 //#region src/rpc/wire-codec.d.ts
 /**
@@ -464,7 +464,7 @@ interface RpcWireCodec {
  *
  * @internal
  */
-declare function createRpcWireCodec(definitions?: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>>): RpcWireCodec;
+export declare function createRpcWireCodec(definitions?: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>>): RpcWireCodec;
 /**
  * Peek at a wire frame's birpc envelope without engaging a codec's
  * request-id bookkeeping; used by the SSE transport to route a frame
@@ -473,9 +473,9 @@ declare function createRpcWireCodec(definitions?: ReadonlyMap<string, Pick<RpcFu
  *
  * @internal
  */
-declare function peekRpcWireFrame(raw: string): {
+export declare function peekRpcWireFrame(raw: string): {
   t?: string;
   i?: string;
 };
 //#endregion
-export { type AgentArgsFallback, type ContextRpcServer, type CreateContextRpcServerOptions, CreateH3DevframeHostOptions, type CreateInstanceShellOptions, DevframeAgentHost, type DevframeInstanceRecord, type DevframeInstanceRegistration, type InstanceRegisterConfig, type InstanceShell, type InstanceShellApi, type InstanceShellInit, type InstanceShellInternals, type InstanceWsTier, type ResolvedMcpConfig, type RpcWireCodec, type StartedServer, coerceAgentPositionalArgs, createContextRpcServer, createH3DevframeHost, createInstanceShell, createRpcWireCodec, diagnostics, importRuntimeModule, listLiveDevframeInstances, loadAutoMcpAdapter, normalizeBasePath, normalizeHttpServerUrl, peekRpcWireFrame, registerDevframeInstance, resolveBasePath, resolveClientAssets, resolveInstanceRegister, resolveMcpConfig, samePath };
+export { type AgentArgsFallback, type ContextRpcServer, type CreateContextRpcServerOptions, type CreateInstanceShellOptions, type DevframeInstanceRecord, type DevframeInstanceRegistration, type InstanceRegisterConfig, type InstanceShell, type InstanceShellApi, type InstanceShellInit, type InstanceShellInternals, type InstanceWsTier, type ResolvedMcpConfig, type RpcWireCodec, type StartedServer, createContextRpcServer, createInstanceShell, listLiveDevframeInstances, loadAutoMcpAdapter, normalizeBasePath, registerDevframeInstance, resolveBasePath, resolveInstanceRegister, resolveMcpConfig, samePath };

package/dist/internal/index.mjs

@@ -5,6 +5,6 @@ import { n as coerceAgentPositionalArgs, t as DevframeAgentHost } from "../host-
 import { a as resolveMcpConfig, n as normalizeBasePath, r as resolveBasePath, s as importRuntimeModule, t as loadAutoMcpAdapter } from "../_shared-U8D-xzrp.mjs";
 import { t as createH3DevframeHost } from "../host-h3-BROI6SQ4.mjs";
 import { i as registerDevframeInstance, n as listLiveDevframeInstances } from "../instance-registry-DCq762YJ.mjs";
-import { i as normalizeHttpServerUrl, n as resolveInstanceRegister, r as samePath, t as createInstanceShell } from "../instance-shell-DvYCwrDy.mjs";
+import { i as normalizeHttpServerUrl, n as resolveInstanceRegister, r as samePath, t as createInstanceShell } from "../instance-shell-xuu6jg51.mjs";
 import { t as createContextRpcServer } from "../rpc-core-CvkU23bQ.mjs";
 export { DevframeAgentHost, coerceAgentPositionalArgs, createContextRpcServer, createH3DevframeHost, createInstanceShell, createRpcWireCodec, diagnostics, importRuntimeModule, listLiveDevframeInstances, loadAutoMcpAdapter, normalizeBasePath, normalizeHttpServerUrl, peekRpcWireFrame, registerDevframeInstance, resolveBasePath, resolveClientAssets, resolveInstanceRegister, resolveMcpConfig, samePath };

package/dist/node/index.d.mts

@@ -3,7 +3,7 @@ import { v as RpcFunctionDefinitionAny } from "../types-Dq4i156u.mjs";
 import { k as SharedState, l as RpcFunctionsHost, o as DevframeNodeContext, xt as DevframeHost } from "../context-BBWPLDHh.mjs";
 import { BirpcGroup } from "birpc";
 //#region src/node/context.d.ts
-interface CreateHostContextOptions {
+export interface CreateHostContextOptions {
   cwd: string;
   workspaceRoot?: string;
   mode: 'dev' | 'build';
@@ -32,15 +32,15 @@ interface CreateHostContextOptions {
  * `createKitContext` attaches `docks`, `terminals`, `messages`, and
  * `commands` when mounted into Vite DevTools.
  */
-declare function createHostContext(options: CreateHostContextOptions): Promise<DevframeNodeContext>;
+export declare function createHostContext(options: CreateHostContextOptions): Promise<DevframeNodeContext>;
 //#endregion
 //#region src/node/storage.d.ts
-interface CreateStorageOptions<T extends object> {
+export interface CreateStorageOptions<T extends object> {
   filepath: string;
   initialValue: T;
   mergeInitialValue?: false | ((initialValue: T, savedValue: T) => T);
   debounce?: number;
 }
-declare function createStorage<T extends object>(options: CreateStorageOptions<T>): SharedState<T>;
+export declare function createStorage<T extends object>(options: CreateStorageOptions<T>): SharedState<T>;
 //#endregion
-export { CreateHostContextOptions, CreateStorageOptions, type RpcFunctionsHost, createHostContext, createStorage };
+export type { RpcFunctionsHost };

package/dist/node/index.mjs

@@ -1,3 +1,3 @@
-import { t as createHostContext } from "../context-Bq27SDK-.mjs";
+import { t as createHostContext } from "../context-Cdj9z9m2.mjs";
 import { t as createStorage } from "../storage-B70AXK64.mjs";
 export { createHostContext, createStorage };