devframe 1.3.1 → 1.3.3

package/dist/{context-BNxFOPbX.d.mts → index-BhUqJUHG.d.mts}

@@ -1,12 +1,11 @@
-import { i as BirpcReturn } from "./index-Bia1vKjL.mjs";
-import { d as RpcFunctionsCollectorBase } from "./index-DuEm0sDH.mjs";
-import { t as StandardSchemaV1 } from "./index-CeEtxDmK.mjs";
-import { g as RpcFunctionDefinitionAny, h as RpcFunctionDefinition } from "./types-BmDbfHCx.mjs";
-import { n as DevframeRpcConnection, t as DevframeNodeRpcSessionMeta } from "./session-r6PDixP6.mjs";
-import { a as RemoteAssetsStore, o as StaticAssetsSource } from "./remote-assets-eBvSKZMS.mjs";
-import { h as defineDiagnostics } from "./nostics-DWvukRwa.mjs";
+import { t as StandardSchemaV1 } from "./index-BIRF0E5l.mjs";
+import { g as RpcFunctionDefinitionAny, h as RpcFunctionDefinition } from "./types-KZOyhez5.mjs";
+import { i as BirpcReturn } from "./index-BKu9BxcT.mjs";
+import { RpcFunctionsCollectorBase } from "./rpc/index.mjs";
+import { n as DevframeRpcConnection, t as DevframeNodeRpcSessionMeta } from "./session-Y9R6tqg4.mjs";
+import { defineDiagnostics } from "./utils/nostics.mjs";
+import { a as RemoteAssetsStore, o as StaticAssetsSource } from "./remote-assets-5AQMHZnV.mjs";
 import { CAC } from "cac";
-//#region src/types/events.d.ts
 interface EventsMap {
   [event: string]: any;
 }
@@ -75,8 +74,6 @@ interface EventEmitter<Events extends EventsMap> {
    */
   once: <K extends keyof Events>(event: K, cb: Events[K]) => EventUnsubscribe;
 }
-//#endregion
-//#region src/types/agent.d.ts
 /**
  * Serializable description of an agent-exposed tool. This is the shape
  * returned by the agent host manifest and surfaced over the wire by
@@ -280,322 +277,197 @@ interface DevframeAgentHost {
   /** Look up a resource by id. */
   getResource: (id: string) => AgentResource | undefined;
 }
-//#endregion
-//#region src/adapters/flags.d.ts
-/**
- * Schema map for typed CLI flags. Keys are flag names in camelCase, so
- * this matches CAC's parsed-flag output ( `--no-open` → `noOpen` ). Each
- * value is any [Standard Schema](https://standardschema.dev/) validator
- * (valibot, zod, arktype, devframe's built-in `s`, …) used to both (a)
- * derive the CAC option type when the flag is registered and (b) validate
- * the parsed value before it's forwarded to `setup(ctx, { flags })`.
- */
-type CliFlagsSchema = Record<string, StandardSchemaV1>;
+type ImmutablePrimitive = undefined | null | boolean | string | number | Function;
+type Immutable<T> = T extends ImmutablePrimitive ? T : T extends Array<infer U> ? ImmutableArray<U> : T extends Map<infer K, infer V> ? ImmutableMap<K, V> : T extends Set<infer M> ? ImmutableSet<M> : ImmutableObject<T>;
+type ImmutableArray<T> = ReadonlyArray<Immutable<T>>;
+type ImmutableMap<K, V> = ReadonlyMap<Immutable<K>, Immutable<V>>;
+type ImmutableSet<T> = ReadonlySet<Immutable<T>>;
+type ImmutableObject<T> = { readonly [K in keyof T]: Immutable<T[K]>; };
 /**
- * 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
- *   },
- * })
- * ```
+ * Serializable patch describing a single mutation to a `SharedState`.
+ * Structurally compatible with JSON-Patch and is safe to send over RPC.
  */
-declare function defineCliFlags<T extends CliFlagsSchema>(flags: T): T;
-/** Extract the parsed-output type from a {@link CliFlagsSchema}. */
-type InferCliFlags<T extends CliFlagsSchema> = { [K in keyof T]: StandardSchemaV1.InferOutput<T[K]>; };
-/** Validate the raw cac-parsed bag against a {@link CliFlagsSchema}. */
-declare function parseCliFlags(schema: CliFlagsSchema, raw: Record<string, unknown>): {
-  flags: Record<string, unknown>;
-  issues?: string[];
-};
-//#endregion
-//#region src/node/auth/handler.d.ts
+interface SharedStatePatch {
+  op: 'add' | 'remove' | 'replace';
+  path: readonly (string | number)[];
+  value?: unknown;
+}
 /**
- * A ready-made pre-auth RPC handler, as produced by
- * `devframe/recipes/interactive-auth`'s `createInteractiveAuth`. Bundles
- * everything a host adapter needs to wire an authenticated server:
- * the handshake RPC functions, the resolver gate, the connect-time trust
- * hook, and the startup banner.
- *
- * `initDevframe` / `initHub` accept one of these directly via their `auth` option
- * (see {@link https://devfra.me | devframe}'s server docs), or a host can
- * wire the four pieces itself against a lower-level transport.
+ * State host that is immutable by default with explicit mutate.
  */
-interface DevframeAuthHandler {
+interface SharedState<T> {
   /**
-   * `anonymous:devframe:auth` + `anonymous:devframe:auth:exchange` (the
-   * handshake), `anonymous:devframe:auth:request-code` (client-requested
-   * banner print), and `devframe:auth:revoke` (self-revoke); register these
-   * on the RPC host (e.g. `rpcHost.register(fn)` for each).
+   * Get the current state. Immutable.
    */
-  rpcFunctions: RpcFunctionDefinitionAny[];
+  value: () => Immutable<T>;
   /**
-   * Resolver gate: whether `methodName` is callable given `session`'s
-   * current trust state. Defaults to allowing any `anonymous:`-prefixed
-   * method (see `isAnonymousRpcMethod`) plus anything once the session is
-   * trusted.
+   * Subscribe to state changes.
    */
-  authorize: (methodName: string, session: DevframeNodeRpcSession) => boolean;
+  on: EventEmitter<SharedStateEvents<T>>['on'];
   /**
-   * Connect-time trust: reads a bearer token off the connection's initial
-   * request (a static/pre-shared token from `clientAuthTokens`, or a token
-   * minted by the code exchange) and, when valid, marks the session
-   * trusted immediately, before the client's own handshake call.
+   * Mutate the state.
    */
-  onConnect: (connection: DevframeRpcConnection, session: DevframeNodeRpcSession) => void;
+  mutate: (fn: (state: T) => void, syncId?: string) => void;
   /**
-   * Print the current one-time code and its magic-link URL. An untrusted
-   * browser client triggers this itself over
-   * `anonymous:devframe:auth:request-code`; call it directly when the host
-   * wants the code on screen without waiting for a client. Safe to call
-   * repeatedly; it only prints once per code.
+   * Apply patches to the state.
    */
-  printBanner: () => void;
+  patch: (patches: SharedStatePatch[], syncId?: string) => void;
   /**
-   * Rewrite a URL the CLI is about to open in the browser (`--open`) so the
-   * tab lands already authenticated, e.g. appending the current OTP as a
-   * query param. Called with the fully-resolved target URL; return it
-   * unchanged to opt out. Optional: a handler that doesn't need this (e.g.
-   * one gated by a pre-shared bearer token instead of an interactive code)
-   * can omit it and the URL opens as-is.
+   * Sync IDs that have been applied to the state.
    */
-  buildOpenUrl?: (url: string) => string;
+  syncIds: Set<string>;
+}
+interface SharedStateEvents<T> {
+  updated: (fullState: T, patches: SharedStatePatch[] | undefined, syncId: string) => void;
+}
+interface SharedStateOptions<T> {
+  /**
+   * Initial state.
+   */
+  initialValue: T;
+  /**
+   * Enable patches.
+   *
+   * @default false
+   */
+  enablePatches?: boolean;
 }
-//#endregion
-//#region src/types/mcp.d.ts
+declare function createSharedState<T extends object>(options: SharedStateOptions<T>): SharedState<T>;
 /**
- * The MCP adapter surface, typed here so `devframe` (which probes for and
- * lazily loads `@devframes/agentic`) and `@devframes/agentic/mcp` (which
- * implements it) share one contract without a type-level dependency cycle.
- * None of these shapes reference the MCP SDK: the SDK is an implementation
- * detail of `@devframes/agentic`, freely swappable behind this surface.
- * The h3-bound `mountMcpHttp` shapes live in `node/agentic.ts` (exported via
- * `devframe/internal`) instead: `devframe/types` must stay lib-neutral, and
- * h3's declarations are not.
+ * Serialized error shape sent over the wire when a stream ends with a failure.
+ * Stays JSON-safe so the strict-JSON encoder can carry it without coercion.
  */
-interface CreateMcpServerOptions {
+interface StreamErrorPayload {
+  name: string;
+  message: string;
+}
+/**
+ * Single buffered chunk in the server-side ring buffer.
+ *
+ * Sequence numbers start at 1 and increment per write. Subscribers track
+ * `lastSeenSeq` and ask for `afterSeq` on resubscribe so the server can
+ * replay any chunks the client missed during a brief disconnect.
+ */
+interface BufferedChunk<T> {
+  seq: number;
+  chunk: T;
+}
+interface StreamSinkEvents<T> {
+  /** Fired for each `write()`. The RPC layer subscribes and broadcasts. */
+  chunk: (seq: number, chunk: T) => void;
+  /** Terminal; fired exactly once per sink lifetime. */
+  end: (error?: StreamErrorPayload) => void;
+}
+interface CreateStreamSinkOptions {
+  id?: string;
   /**
-   * Transport to use. `createMcpServer` itself runs `'stdio'` (a standalone
-   * process with its own host context); the Streamable-HTTP transport is
-   * served route-based by the dev server instead; see `mountMcpHttp` and
-   * the `mcp` option on `createDevServer` / `createCac`'s `--mcp` flag.
+   * Size of the per-stream ring buffer kept for replay-on-resubscribe.
+   * `0` (default) disables replay.
    */
-  transport?: 'stdio';
+  replayWindow?: number;
+}
+/**
+ * Server-side producer handle. Two equivalent surfaces share one piece of
+ * state: the imperative `write/error/close` triple, and a `WritableStream<T>`
+ * for `pipeTo`-style consumption.
+ */
+interface StreamSink<T> {
+  /** Stable id used by clients to subscribe. */
+  readonly id: string;
   /**
-   * Expose shared-state keys as MCP resources.
-   * - `true` (default): every key the host publishes
-   * - `false`: none
-   * - `(key) => boolean`: filter
+   * Aborts when the consumer cancels (server-side) or when the transport
+   * loses every subscriber. Producers should poll `signal.aborted` and exit
+   * cleanly.
    */
-  exposeSharedState?: boolean | ((key: string) => boolean);
+  readonly signal: AbortSignal;
+  /** `true` after `close()` / `error()`. Further writes throw. */
+  readonly closed: boolean;
+  /** Last allocated sequence number. `0` until the first write. */
+  readonly lastSeq: number;
+  write: (chunk: T) => void;
+  error: (reason: unknown) => void;
+  close: () => void;
+  /** External-cancel path. Aborts the signal so handlers can short-circuit. */
+  abort: (reason?: unknown) => void;
+  /** `WritableStream<T>` adapter; same in-memory state as the imperative API. */
+  readonly writable: WritableStream<T>;
   /**
-   * Usage guidance sent as `instructions` in the MCP `initialize` (and
-   * `server/discover`) result. Omitted or empty sends no instructions.
+   * Internal: RPC layer subscribes to receive chunk/end notifications.
+   * Not part of the public contract; do not call directly.
+   *
+   * @internal
    */
-  instructions?: string;
+  readonly events: EventEmitter<StreamSinkEvents<T>>;
   /**
-   * Resource templates served through `resources/templates/list`, and read
-   * through `resources/read`. Omitted or empty keeps the resources unchanged.
+   * Internal replay buffer. RPC layer reads on (re)subscribe to feed
+   * missed chunks before going live.
+   *
+   * @internal
    */
-  resourceTemplates?: McpResourceTemplate[];
+  readonly buffer: ReadonlyArray<BufferedChunk<T>>;
+}
+interface CreateStreamReaderOptions {
+  id?: string;
   /**
-   * Host subscription for resource-list changes; each `notify()` sends
-   * `notifications/resources/list_changed`. See {@link McpResourcesChangedHook}.
+   * Maximum number of buffered chunks held client-side while the consumer
+   * isn't draining. On overflow, the oldest chunk is dropped.
    */
-  onResourcesChanged?: McpResourcesChangedHook;
+  highWaterMark?: number;
   /**
-   * Prompt templates served through `prompts/list` and `prompts/get`.
-   * Omitted or empty declares no `prompts` capability.
+   * Called when the chunk queue overflows the high-water mark. The RPC
+   * layer wires this to a coded warning; the primitive itself is
+   * RPC-agnostic.
    */
-  prompts?: McpPrompt[];
-  /** Override the name reported in the MCP handshake. */
-  serverName?: string;
-  /** Override the version reported in the MCP handshake. Defaults to `definition.version ?? '0.0.0'`. */
-  serverVersion?: string;
-  /** Called once the transport is connected. */
-  onReady?: (info: {
-    transport: 'stdio';
-  }) => void;
+  onOverflow?: (dropped: number) => void;
+  /** Called when the consumer cancels; the RPC layer sends `:cancel` upstream. */
+  onCancel?: () => void;
 }
 /**
- * One MCP content block in a tool result. Attach blocks to a tool's return
- * value with `withMcpContent` (from `devframe`) to send them in place of the
- * default JSON text block. `data` is base64.
+ * Client-side consumer handle. Both an `AsyncIterable<T>` (for `for await`)
+ * and exposes `readable: ReadableStream<T>` (for `pipeTo`). Pick one; they
+ * share a single internal queue, so concurrent draining will race.
  */
-type McpContentBlock = {
-  type: 'text';
-  text: string;
-} | {
-  type: 'image';
-  data: string;
-  mimeType: string;
-} | {
-  type: 'audio';
-  data: string;
-  mimeType: string;
-};
-interface McpServerHandle {
-  stop: () => Promise<void>;
-}
-interface CreateMcpFetchHandlerOptions {
-  /** Name reported in the MCP handshake. */
-  serverName: string;
-  /** Version reported in the MCP handshake. */
-  serverVersion: string;
-  /** Expose shared-state keys as MCP resources; see {@link CreateMcpServerOptions.exposeSharedState}. */
-  exposeSharedState: boolean | ((key: string) => boolean);
-  /** Usage guidance for the handshake; see {@link CreateMcpServerOptions.instructions}. */
-  instructions?: string;
-  /** Resource templates; see {@link CreateMcpServerOptions.resourceTemplates}. */
-  resourceTemplates?: McpResourceTemplate[];
-  /** Host subscription for resource-list changes; see {@link CreateMcpServerOptions.onResourcesChanged}. */
-  onResourcesChanged?: McpResourcesChangedHook;
-  /** Prompt templates; see {@link CreateMcpServerOptions.prompts}. */
-  prompts?: McpPrompt[];
-  /**
-   * Optional identity check, layered on top of the origin gate and checked
-   * **after** it: a bearer token string (matched in constant time against
-   * `Authorization: Bearer <token>`), a `(request) => boolean` callback, or
-   * `false` (the default) for origin-only, trusting same-machine callers. A
-   * callback governs identity only and cannot relax the origin gate. See
-   * {@link McpAuthorization}.
-   */
-  authorization?: McpAuthorization;
-  /**
-   * Origin allow-list beyond the loopback default. `false` disables the
-   * origin gate entirely. Default: loopback-only.
-   *
-   * Unlike the WS transport, the MCP route does **not** allow `Origin`-less
-   * requests: a route-based endpoint is reachable by any local process, so a
-   * request must carry an `Origin` that passes the gate. Native clients
-   * (e.g. `devframe connect`) send their loopback origin explicitly.
-   */
-  allowedOrigins?: readonly string[] | false;
-}
-/** Connection facts a host knows about a request beyond the `Request` itself. */
-interface McpConnectionInfo {
-  /**
-   * The connecting peer's remote address (a node socket's `remoteAddress`),
-   * used to prove a same-machine caller when the endpoint relies on the
-   * loopback origin default with no identity check. A host that can resolve a
-   * trustworthy peer address (the h3/node mount) supplies it; when it's
-   * omitted the origin gate stays the only locality signal.
-   */
-  remoteAddress?: string;
-}
-interface McpFetchHandler {
-  /**
-   * WHATWG-`fetch` handler for the MCP endpoint. Hand every method
-   * (POST/GET/DELETE) on the endpoint's path to it; routing by path is the
-   * host's job. Pass {@link McpConnectionInfo} when the host can resolve the
-   * peer address so the default trust boundary can enforce same-machine
-   * locality.
-   */
-  fetch: (request: Request, connection?: McpConnectionInfo) => Promise<Response>;
-  /** Tear down the handler (aborts in-flight exchanges, drops the change bridge). */
-  dispose: () => Promise<void>;
-}
-/** One concrete resource that an {@link McpResourceTemplate} lists in `resources/list`. */
-interface McpResourceTemplateEntry {
-  /** The resource URI. It SHOULD match the `uriTemplate` of its template, so `resources/read` finds it. */
-  uri: string;
-  name: string;
-  /** Human-readable name for display. */
-  title?: string;
-  description?: string;
-  /** Defaults to the `mimeType` of the template. */
-  mimeType?: string;
+interface StreamReader<T> extends AsyncIterable<T> {
+  readonly id: string;
+  readonly cancelled: boolean;
+  readonly done: boolean;
+  /** Highest `seq` observed. Used for replay on reconnect. */
+  readonly lastSeenSeq: number;
+  /** `ReadableStream<T>` adapter for `pipeTo`-style consumption. */
+  readonly readable: ReadableStream<T>;
+  cancel: () => void;
+  /** @internal */
+  _push: (seq: number, chunk: T) => void;
+  /** @internal */
+  _end: (error?: StreamErrorPayload) => void;
 }
 /**
- * What an {@link McpResourceTemplate} returns from `read`, sent as the
- * `resources/read` result: `text` as is, or else `json` as JSON text.
+ * Build a server-side stream sink. RPC-agnostic; the RPC host wires
+ * `events.on('chunk' | 'end')` to broadcast, and reads `buffer` to replay
+ * for late or reconnecting subscribers.
  */
-interface McpResourceTemplateContent {
-  text?: string;
-  json?: unknown;
-  /** Defaults to the `mimeType` of the template, then `application/json`. */
-  mimeType?: string;
-}
+declare function createStreamSink<T>(options?: CreateStreamSinkOptions): StreamSink<T>;
 /**
- * A resource template the MCP server lists in `resources/templates/list` and
- * reads in `resources/read`. The `uriTemplate` uses RFC 6570 level 1 only:
- * plain `{name}` expressions, with text between any two of them. Each
- * expression matches a non-empty value with no `/`, and its value is
- * percent-decoded.
- *
- * `list` and `read` get the node context of the devframe (or of the hub), so
- * they can read live state such as `ctx.rpc.sharedState` or `ctx.agent`. The
- * route options are resolved before `setup()` runs, so a template cannot
- * capture that context in a closure.
+ * Build a client-side stream reader. RPC-agnostic; the RPC host calls
+ * `_push(seq, chunk)` on each incoming chunk and `_end(error?)` on the
+ * terminal frame. Consumers iterate with `for await` or pipe `readable`.
  */
-interface McpResourceTemplate {
-  /** RFC 6570 level 1 URI template, e.g. `my-tool://file/{path}`. Anything else throws `DF0084`. */
-  uriTemplate: string;
-  name: string;
-  /** Human-readable name for display. */
+declare function createStreamReader<T>(options?: CreateStreamReaderOptions): StreamReader<T>;
+interface BrowserAgentToolManifest {
+  id: string;
   title?: string;
-  description?: string;
-  /** MIME type of every resource the template stands for. */
-  mimeType?: string;
-  /** The concrete resources the template stands for right now. They are added to `resources/list`. */
-  list?: (ctx: DevframeNodeContext) => McpResourceTemplateEntry[] | Promise<McpResourceTemplateEntry[]>;
-  /** Read one resource: `params` holds the decoded value of each `{name}`, `uri` the requested URI. */
-  read: (params: Record<string, string>, uri: string, ctx: DevframeNodeContext) => McpResourceTemplateContent | Promise<McpResourceTemplateContent>;
-}
-/**
- * A host subscription for resource-list changes. Call `notify()` each time
- * the resources change; the MCP server then sends
- * `notifications/resources/list_changed`. Return a function that removes the
- * subscription; the MCP server calls it on teardown.
- */
-type McpResourcesChangedHook = (notify: () => void, ctx: DevframeNodeContext) => () => void;
-/** One argument of an {@link McpPrompt}. */
-interface McpPromptArgument {
-  name: string;
-  description?: string;
-  /** `prompts/get` answers invalid params when a required argument is missing or empty. */
-  required?: boolean;
-}
-/** One message of the answer to `prompts/get`. */
-interface McpPromptMessage {
-  role: 'user' | 'assistant';
-  content: {
-    type: 'text';
-    text: string;
-  };
-}
-/** What an {@link McpPrompt} returns from `get`, sent as the `prompts/get` result. */
-interface McpPromptResult {
-  description?: string;
-  messages: McpPromptMessage[];
+  description: string;
+  safety: 'read' | 'action' | 'destructive';
+  tags?: readonly string[];
+  inputSchema?: unknown;
 }
-/**
- * A prompt template the MCP server lists in `prompts/list` and builds in
- * `prompts/get`. A coding agent usually offers it to the user as a slash
- * command. Each `name` is used once; a repeated name throws `DF0085`.
- */
-interface McpPrompt {
-  name: string;
-  /** Human-readable name for display. */
-  title?: string;
-  description?: string;
-  arguments?: McpPromptArgument[];
-  /** Build the messages from the arguments the coding agent sent. */
-  get: (args: Record<string, string>) => McpPromptResult | Promise<McpPromptResult>;
+/** What a connected document reports about itself alongside its tool manifest. */
+interface BrowserAgentClientInfo {
+  url: string;
+  title: string;
+  visible: boolean;
+  focused: boolean;
 }
-//#endregion
-//#region src/types/diagnostics.d.ts
 /**
  * The shared diagnostics lookup exposed by the host. A `Proxy` that resolves
  * any registered code name to its `nostics` handle (a callable that builds
@@ -652,8 +524,6 @@ interface DevframeDiagnosticsHost {
    */
   defineDiagnostics: typeof defineDiagnostics;
 }
-//#endregion
-//#region src/types/host.d.ts
 interface DevframeHost {
   /**
    * Serve static assets at the given URL base: a local directory, or a
@@ -721,274 +591,44 @@ interface DevframeHost {
  * private, `global` is per-user.
  */
 type DevframeStorageScope = 'workspace' | 'project' | 'global';
-//#endregion
-//#region src/client/browser-agent.d.ts
-interface BrowserAgentToolManifest {
-  id: string;
-  title?: string;
-  description: string;
-  safety: 'read' | 'action' | 'destructive';
-  tags?: readonly string[];
-  inputSchema?: unknown;
-}
-/** What a connected document reports about itself alongside its tool manifest. */
-interface BrowserAgentClientInfo {
-  url: string;
-  title: string;
-  visible: boolean;
-  focused: boolean;
-}
-//#endregion
-//#region src/types/rpc-augments.d.ts
-/**
- * To be extended
- */
-interface DevframeRpcClientFunctions {
-  /** Clear cached RPC results and refresh cache eligibility. */
-  'devframe:rpc:cache:invalidate': () => Promise<void>;
-  /** Invoke a tool registered in this browser document. @internal */
-  'devframe:agent:invoke-client-tool': (id: string, args: Record<string, unknown>) => Promise<unknown>;
-  /**
-   * Server→client notification that this connection's auth token has been
-   * revoked. The client drops to untrusted on receipt. Broadcast by
-   * `revokeActiveConnectionsForToken`.
-   *
-   * @internal
-   */
-  'devframe:auth:revoked': () => Promise<void>;
-  /**
-   * Streaming chunk pushed from server to subscribed clients. Wired by
-   * `RpcStreamingHost`; do not register manually.
-   *
-   * @internal
-   */
-  'devframe:streaming:chunk': (channel: string, id: string, seq: number, chunk: any) => Promise<void>;
-  /**
-   * Streaming terminator pushed from server to subscribed clients. Wired by
-   * `RpcStreamingHost`; do not register manually.
-   *
-   * @internal
-   */
-  'devframe:streaming:end': (channel: string, id: string, error?: {
-    name: string;
-    message: string;
-  }) => Promise<void>;
+interface DevframeViewHost {
   /**
-   * Server→client cancel for an in-flight upload. Wired by
-   * `RpcStreamingHost`; do not register manually.
+   * Static mounts registered through {@link DevframeViewHost.hostStatic}, each
+   * carrying the `resolveFrom` base it was mounted with so a build step that
+   * copies these itself (rather than serving them live) re-resolves a remote
+   * source to the same locally-installed copy it would serve live.
    *
    * @internal
    */
-  'devframe:streaming:upload-cancel': (channel: string, id: string) => Promise<void>;
+  buildStaticDirs: {
+    baseUrl: string;
+    source: StaticAssetsSource;
+    resolveFrom?: string | null;
+  }[];
   /**
-   * Full shared-state snapshot pushed from server to subscribed clients.
-   * Wired by `RpcSharedStateHost`; do not register manually.
+   * Helper to host static files
+   * - In `dev` mode, it will register middleware to `viteServer.middlewares` to host the static files
+   * - In `build` mode, it will copy the static files to the dist directory
    *
-   * @internal
-   */
-  'devframe:rpc:client-state:updated': (key: string, fullState: any, syncId: string) => Promise<void>;
-  /**
-   * Incremental shared-state patch pushed from server to subscribed clients.
-   * Wired by `RpcSharedStateHost`; do not register manually.
+   * Accepts a local dist directory, or a {@link StaticAssetsSource} remote
+   * declaration served through devframe's caching CDN back-proxy.
    *
-   * @internal
+   * `defaultResolveFrom` overrides, for this call only, the context's own
+   * `importMetaUrl` as the default `resolveFrom` for a remote source that
+   * doesn't set one. A shared host that mounts assets on behalf of another
+   * devframe (a hub installing a plugin) passes that plugin's `importMetaUrl`
+   * so the assets resolve against the plugin's dependency graph rather than
+   * the host's.
    */
-  'devframe:rpc:client-state:patch': (key: string, patches: any[], syncId: string) => Promise<void>;
+  hostStatic: (baseUrl: string, source: StaticAssetsSource, defaultResolveFrom?: string | null) => void;
 }
+type AnyRpcFn = (...args: any[]) => any;
 /**
- * To be extended
- */
-interface DevframeRpcServerFunctions {
-  /** Methods eligible for automatic client caching. @internal */
-  'devframe:rpc:cacheable-functions': () => Promise<string[]>;
-  /** Replace this connection's browser-agent tool manifest, tagged with the calling tab's stable client id. @internal */
-  'devframe:agent:sync-client-tools': (clientId: string, tools: BrowserAgentToolManifest[], info: BrowserAgentClientInfo) => Promise<void>;
-  /**
-   * Authenticate a connection with a previously-issued bearer token; resolves
-   * whether the connection is now trusted. The interactive handler is provided
-   * by the host adapter (e.g. Vite DevTools); the standalone server registers
-   * an auto-trust noop when `auth: false`.
-   *
-   * Named with the `anonymous:` prefix (see `isAnonymousRpcMethod`) so it is
-   * reachable before the connection is trusted; this is the *only* rule the
-   * pre-trust gate applies, no per-method allowlist.
-   *
-   * @internal
-   */
-  'anonymous:devframe:auth': (params: {
-    authToken: string;
-    ua: string;
-    origin: string;
-  }) => Promise<{
-    isTrusted: boolean;
-  }>;
-  /**
-   * Exchange a one-time authentication code (shown by the dev server) for a fresh,
-   * node-issued bearer token, returning the token on success or `null`. The
-   * handler is provided by the host adapter on top of `exchangeTempAuthCode`.
-   *
-   * Named with the `anonymous:` prefix (see `isAnonymousRpcMethod`) so it is
-   * reachable before the connection is trusted.
-   *
-   * @internal
-   */
-  'anonymous:devframe:auth:exchange': (params: {
-    code: string;
-    ua: string;
-    origin: string;
-  }) => Promise<{
-    authToken: string | null;
-  }>;
-  /**
-   * Ask the server to print its auth banner (code + magic link) for this
-   * client, e.g. when an auth UI first shows; `reissue: true` rotates the code
-   * first (the manual "re-issue" action). Registered by
-   * `recipes/interactive-auth`; a repeat request for an already-printed code
-   * is a no-op.
-   *
-   * Named with the `anonymous:` prefix (see `isAnonymousRpcMethod`) so it is
-   * reachable before the connection is trusted.
-   *
-   * @internal
-   */
-  'anonymous:devframe:auth:request-code': (params: {
-    ua: string;
-    origin: string;
-    reissue?: boolean;
-  }) => Promise<void>;
-  /**
-   * Self-revoke: the caller asks the server to revoke its own bearer token
-   * (if any) and drop to untrusted. Requires an already-trusted caller, so
-   * unlike the two handshake methods above it does **not** carry the
-   * `anonymous:` prefix. Registered by `recipes/interactive-auth`.
-   *
-   * @internal
-   */
-  'devframe:auth:revoke': () => Promise<void>;
-  /**
-   * Subscribe a client to a shared-state key. Wired by
-   * `RpcSharedStateHost`; do not register manually.
-   *
-   * @internal
-   */
-  'devframe:rpc:server-state:subscribe': (key: string) => Promise<void>;
-  /**
-   * Read the current value for a shared-state key. Wired by
-   * `RpcSharedStateHost`; do not register manually.
-   *
-   * @internal
-   */
-  'devframe:rpc:server-state:get': (key: string) => Promise<any>;
-  /**
-   * Replace a shared-state value (from the client). Wired by
-   * `RpcSharedStateHost`; do not register manually.
-   *
-   * @internal
-   */
-  'devframe:rpc:server-state:set': (key: string, value: any, syncId: string) => Promise<void>;
-  /**
-   * Apply a patch to a shared-state value (from the client). Wired by
-   * `RpcSharedStateHost`; do not register manually.
-   *
-   * @internal
-   */
-  'devframe:rpc:server-state:patch': (key: string, patches: any[], syncId: string) => Promise<void>;
-  /**
-   * Client→server streaming subscription with optional replay cursor.
-   * Wired by `RpcStreamingHost`; do not register manually.
-   *
-   * @internal
-   */
-  'devframe:streaming:subscribe': (channel: string, id: string, opts?: {
-    afterSeq?: number;
-  }) => Promise<void>;
-  /**
-   * Client→server streaming unsubscribe. Wired by `RpcStreamingHost`;
-   * do not register manually.
-   *
-   * @internal
-   */
-  'devframe:streaming:unsubscribe': (channel: string, id: string) => Promise<void>;
-  /**
-   * Client→server streaming cancellation request. Wired by
-   * `RpcStreamingHost`; do not register manually.
-   *
-   * @internal
-   */
-  'devframe:streaming:cancel': (channel: string, id: string) => Promise<void>;
-  /**
-   * Client→server upload chunk. Wired by `RpcStreamingHost`; do not
-   * register manually.
-   *
-   * @internal
-   */
-  'devframe:streaming:upload-chunk': (channel: string, id: string, seq: number, chunk: any) => Promise<void>;
-  /**
-   * Client→server upload terminator. Wired by `RpcStreamingHost`; do not
-   * register manually.
-   *
-   * @internal
-   */
-  'devframe:streaming:upload-end': (channel: string, id: string, error?: {
-    name: string;
-    message: string;
-  }) => Promise<void>;
-}
-/**
- * To be extended
- */
-interface DevframeRpcSharedStates {
-  /**
-   * Wire-service advertisements: package name → `{ package, version,
-   * scope, meta }` for every installed {@link import('./services').DevframeServiceDefinition}.
-   * Written by the node services host at the `ready()` barrier; clients read
-   * it through `client.services` (or subscribe to it directly for
-   * reactivity). Read-only from the browser.
-   */
-  'devframe:services': DevframeServicesState;
-}
-//#endregion
-//#region src/types/views.d.ts
-interface DevframeViewHost {
-  /**
-   * Static mounts registered through {@link DevframeViewHost.hostStatic}, each
-   * carrying the `resolveFrom` base it was mounted with so a build step that
-   * copies these itself (rather than serving them live) re-resolves a remote
-   * source to the same locally-installed copy it would serve live.
-   *
-   * @internal
-   */
-  buildStaticDirs: {
-    baseUrl: string;
-    source: StaticAssetsSource;
-    resolveFrom?: string | null;
-  }[];
-  /**
-   * Helper to host static files
-   * - In `dev` mode, it will register middleware to `viteServer.middlewares` to host the static files
-   * - In `build` mode, it will copy the static files to the dist directory
-   *
-   * Accepts a local dist directory, or a {@link StaticAssetsSource} remote
-   * declaration served through devframe's caching CDN back-proxy.
-   *
-   * `defaultResolveFrom` overrides, for this call only, the context's own
-   * `importMetaUrl` as the default `resolveFrom` for a remote source that
-   * doesn't set one. A shared host that mounts assets on behalf of another
-   * devframe (a hub installing a plugin) passes that plugin's `importMetaUrl`
-   * so the assets resolve against the plugin's dependency graph rather than
-   * the host's.
-   */
-  hostStatic: (baseUrl: string, source: StaticAssetsSource, defaultResolveFrom?: string | null) => void;
-}
-//#endregion
-//#region src/types/scope.d.ts
-type AnyRpcFn = (...args: any[]) => any;
-/**
- * Resolve a scoped bare name `T` back to its fully-qualified entry in
- * `Registry` (`<NS>:<T>`). Indexing the plain registry behind a `keyof`
- * guard keeps TypeScript from rejecting a generic index into the
- * key-remapped `Scoped*Functions<NS>` maps (TS2536) once a plugin augments
- * the registry, while preserving each name's argument/return typing.
+ * Resolve a scoped bare name `T` back to its fully-qualified entry in
+ * `Registry` (`<NS>:<T>`). Indexing the plain registry behind a `keyof`
+ * guard keeps TypeScript from rejecting a generic index into the
+ * key-remapped `Scoped*Functions<NS>` maps (TS2536) once a plugin augments
+ * the registry, while preserving each name's argument/return typing.
  */
 type ScopedRpcFn<Registry, NS extends string, T extends string> = `${NS}:${T}` extends keyof Registry ? Extract<Registry[`${NS}:${T}`], AnyRpcFn> : AnyRpcFn;
 /**
@@ -1161,8 +801,6 @@ interface DevframeScopedNodeContext<NS extends string = string, Settings extends
    */
   scope: DevframeNodeContext['scope'];
 }
-//#endregion
-//#region src/types/services.d.ts
 /**
  * Augmentation point mapping service ids to their implementation types.
  * Providers extend this via `declare module 'devframe'`.
@@ -1356,1097 +994,1425 @@ interface DevframeServicesHost {
    */
   ready: () => Promise<void>;
 }
-//#endregion
-//#region src/types/devframe.d.ts
-/**
- * Classification of how a devframe is being deployed. Hosted adapters
- * (`vite`, `embedded`) share their origin with a host app and must
- * namespace their mount path under `/__<id>/`. Standalone adapters
- * (`cli`, `build`) own the origin and default to `/`.
- */
-type DevframeDeploymentKind = 'standalone' | 'hosted';
 /**
- * How a hub deduplicates devframes that share an `id` when more than one
- * is mounted onto the same hub. See {@link DevframeDefinition.duplicationStrategy}.
- *
- * - `'warn'` (default): keep the first registration, drop later
- *   duplicates, and emit a warning diagnostic (`DF8105`).
- * - `'silent'`: drop later duplicates without warning.
- * - `'throw'`: throw when a duplicate is mounted.
- * - `'duplicate'`: let every instance coexist under a disambiguated
- *   dock id.
- */
-type DevframeDuplicationStrategy = 'warn' | 'silent' | 'throw' | 'duplicate';
-/**
- * Controls where the browser opens the RPC WebSocket, advertised in
- * `__connection.json` and used to bind the dev server. The three shapes map
- * to the three connection scenarios; precedence is `url` > `port` > `route`:
- *
- *   1. **Same server, different route** (default): leave `port`/`url` unset.
- *      The socket shares the HTTP server's port and binds to `route`
- *      (`__ws`). The client connects to its own origin, so the link
- *      survives a reverse proxy that rewrites the host/port/subpath.
- *
- *   2. **Different port**: set `port`. The socket binds on its own port on the
- *      same host; the client targets `ws(s)://<page-host>:<port>/<route>`.
- *
- *   3. **Remote, different origin**: set `url` to a full `ws://`/`wss://`
- *      endpoint (e.g. a public tunnel or relay). The client uses it verbatim.
+ * To be extended
  */
-interface DevframeWsOptions {
+interface DevframeRpcClientFunctions {
+  /** Clear cached RPC results and refresh cache eligibility. */
+  'devframe:rpc:cache:invalidate': () => Promise<void>;
+  /** Invoke a tool registered in this browser document. @internal */
+  'devframe:agent:invoke-client-tool': (id: string, args: Record<string, unknown>) => Promise<unknown>;
   /**
-   * Upgrade route segment the socket binds to and is advertised at, relative
-   * to the SPA base. Default: `__ws`.
+   * Server→client notification that this connection's auth token has been
+   * revoked. The client drops to untrusted on receipt. Broadcast by
+   * `revokeActiveConnectionsForToken`.
+   *
+   * @internal
    */
-  route?: string;
+  'devframe:auth:revoked': () => Promise<void>;
   /**
-   * Bind the socket on its own port instead of sharing the HTTP port. The
-   * browser connects to this port on the page's hostname. Implies
-   * {@link DevframeWsOptions.sidecar}.
+   * Streaming chunk pushed from server to subscribed clients. Wired by
+   * `RpcStreamingHost`; do not register manually.
+   *
+   * @internal
    */
-  port?: number;
+  'devframe:streaming:chunk': (channel: string, id: string, seq: number, chunk: any) => Promise<void>;
   /**
-   * Start a side-car WebSocket server on a free port, for hosts whose request
-   * handlers can't accept upgrades (Next.js route handlers, Nitro, Rsbuild).
-   * The resolved port is advertised in `__connection.json`, so the browser
-   * finds it without any further wiring. Set `port` instead to pin it.
+   * Streaming terminator pushed from server to subscribed clients. Wired by
+   * `RpcStreamingHost`; do not register manually.
+   *
+   * @internal
    */
-  sidecar?: boolean;
+  'devframe:streaming:end': (channel: string, id: string, error?: {
+    name: string;
+    message: string;
+  }) => Promise<void>;
   /**
-   * Advertise a fixed, fully-qualified endpoint on another origin (a full
-   * `ws://`/`wss://` URL). Takes precedence over `port`/`route` in the meta.
+   * Server→client cancel for an in-flight upload. Wired by
+   * `RpcStreamingHost`; do not register manually.
+   *
+   * @internal
    */
-  url?: string;
-}
-/**
- * Controls the SSE RPC endpoint, the WebSocket-free transport for hosts
- * and proxies where the upgrade isn't available. It rides whatever HTTP
- * surface serves the instance (the same one serving `__connection.json`),
- * so a relative `route` always resolves; there is no port plumbing of its
- * own. Enabled by default alongside the WebSocket; pass `sse: false` to
- * disable, or `ws: false` to run SSE-only (`backend: 'sse'`).
- */
-interface DevframeSseOptions {
+  'devframe:streaming:upload-cancel': (channel: string, id: string) => Promise<void>;
   /**
-   * Route segment the SSE endpoint binds to and is advertised at, relative
-   * to the SPA base. Default: `__sse`.
+   * Full shared-state snapshot pushed from server to subscribed clients.
+   * Wired by `RpcSharedStateHost`; do not register manually.
+   *
+   * @internal
    */
-  route?: string;
+  'devframe:rpc:client-state:updated': (key: string, fullState: any, syncId: string) => Promise<void>;
+  /**
+   * Incremental shared-state patch pushed from server to subscribed clients.
+   * Wired by `RpcSharedStateHost`; do not register manually.
+   *
+   * @internal
+   */
+  'devframe:rpc:client-state:patch': (key: string, patches: any[], syncId: string) => Promise<void>;
 }
 /**
- * An **optional** identity check layered on top of the origin gate. The
- * route-based MCP endpoint trusts same-machine callers by default (the
- * loopback origin gate is enough), so this is opt-in hardening for the cases
- * where a same-machine process is not a trust boundary, like a LAN/tunnel
- * origin, a shared/CI box, or a destructive tool surface:
- *
- * - a non-empty **bearer token string**: the request must carry
- *   `Authorization: Bearer <token>`, compared in constant time. Back it with
- *   an environment variable rather than a literal;
- * - a **callback** `(request) => boolean | Promise<boolean>`: a custom
- *   identity check (validate a signed header, an mTLS-derived claim, …). It
- *   only governs identity and cannot relax the origin gate;
- * - `false`, the default: **origin-only**, trusting same-machine callers.
- */
-type McpAuthorization = string | ((request: Request) => boolean | Promise<boolean>) | false;
-/**
- * The route-based MCP setting accepted everywhere a host mounts a devframe
- * (`initDevframe` / `initHub` / `createDevServer` options, `createCac` /
- * `--mcp`, the framework kits):
- *
- * - `'auto'`, the default: mount the route when the devframe exposes an
- *   agent surface (an `agent`-flagged RPC function, or a tool / resource /
- *   provider registered on `ctx.agent`) AND the optional `@devframes/agentic`
- *   peer (the MCP adapter and SDK) is installed. An empty agent surface
- *   mounts nothing and loads no MCP code; a non-empty one without the peer
- *   warns once (DF0078) and mounts nothing.
- * - `true`: always mount at the default `__mcp` route; a missing
- *   `@devframes/agentic` throws DF0079.
- * - `false`: never mount, and never probe or warn.
- * - {@link McpRouteOptions}: always mount (like `true`), with a custom route
- *   path, origin allow-list, or {@link McpAuthorization} identity check.
- *
- * A mounted route trusts same-machine callers by default (the loopback
- * origin gate), exactly like `mcp: true`.
- */
-type McpSetting = boolean | 'auto' | McpRouteOptions;
-/**
- * Configuration for the route-based MCP server mounted alongside the dev
- * server (via {@link DevframeCliOptions.mcp}). The endpoint speaks
- * the MCP Streamable-HTTP transport over the same origin as the SPA,
- * exposing the definition's `ctx.agent` tools + shared-state resources to
- * external MCP clients connected to the *running* server.
+ * To be extended
  */
-interface McpRouteOptions {
+interface DevframeRpcServerFunctions {
+  /** Methods eligible for automatic client caching. @internal */
+  'devframe:rpc:cacheable-functions': () => Promise<string[]>;
+  /** Replace this connection's browser-agent tool manifest, tagged with the calling tab's stable client id. @internal */
+  'devframe:agent:sync-client-tools': (clientId: string, tools: BrowserAgentToolManifest[], info: BrowserAgentClientInfo) => Promise<void>;
   /**
-   * Route segment the MCP endpoint binds to, relative to the SPA base.
-   * Default: `__mcp` (i.e. `/__mcp` standalone, `/__<id>/__mcp` hosted).
+   * Authenticate a connection with a previously-issued bearer token; resolves
+   * whether the connection is now trusted. The interactive handler is provided
+   * by the host adapter (e.g. Vite DevTools); the standalone server registers
+   * an auto-trust noop when `auth: false`.
+   *
+   * Named with the `anonymous:` prefix (see `isAnonymousRpcMethod`) so it is
+   * reachable before the connection is trusted; this is the *only* rule the
+   * pre-trust gate applies, no per-method allowlist.
+   *
+   * @internal
    */
-  path?: string;
+  'anonymous:devframe:auth': (params: {
+    authToken: string;
+    ua: string;
+    origin: string;
+  }) => Promise<{
+    isTrusted: boolean;
+  }>;
   /**
-   * Optional identity check, layered on top of the origin gate and checked
-   * **after** it. Defaults to origin-only (`false`): the route trusts
-   * same-machine callers, since the loopback origin gate already keeps
-   * arbitrary remote/browser callers out. Set a bearer token or a callback to
-   * harden the route when a same-machine process is not your trust boundary
-   * (LAN/tunnel origin, shared/CI host, destructive tools). See
-   * {@link McpAuthorization}.
+   * Exchange a one-time authentication code (shown by the dev server) for a fresh,
+   * node-issued bearer token, returning the token on success or `null`. The
+   * handler is provided by the host adapter on top of `exchangeTempAuthCode`.
+   *
+   * Named with the `anonymous:` prefix (see `isAnonymousRpcMethod`) so it is
+   * reachable before the connection is trusted.
+   *
+   * @internal
    */
-  authorization?: McpAuthorization;
+  'anonymous:devframe:auth:exchange': (params: {
+    code: string;
+    ua: string;
+    origin: string;
+  }) => Promise<{
+    authToken: string | null;
+  }>;
   /**
-   * Extra `Origin` header values to accept beyond the loopback default
-   * (`localhost`/`127.0.0.1`/`::1` and any `Origin`-less native client).
-   * Add your LAN/tunnel origin here when reaching the endpoint from another
-   * host, mirroring the WS transport's origin gate. Pass `false` to disable
-   * origin checking entirely (not recommended). Default: loopback-only.
+   * Ask the server to print its auth banner (code + magic link) for this
+   * client, e.g. when an auth UI first shows; `reissue: true` rotates the code
+   * first (the manual "re-issue" action). Registered by
+   * `recipes/interactive-auth`; a repeat request for an already-printed code
+   * is a no-op.
    *
-   * This is the endpoint's DNS-rebinding protection: the shared
-   * `isAllowedOrigin` gate the WS upgrade already uses, applied as external
-   * middleware (the approach the MCP SDK now recommends over its own
-   * deprecated `allowedHosts`/`allowedOrigins` transport flags). When you
-   * widen it past loopback, layer on {@link McpRouteOptions.authorization} to
-   * prove identity too.
+   * Named with the `anonymous:` prefix (see `isAnonymousRpcMethod`) so it is
+   * reachable before the connection is trusted.
+   *
+   * @internal
    */
-  allowedOrigins?: readonly string[] | false;
+  'anonymous:devframe:auth:request-code': (params: {
+    ua: string;
+    origin: string;
+    reissue?: boolean;
+  }) => Promise<void>;
   /**
-   * Which shared-state keys the route exposes to agents, through the built-in
-   * `devframe_state_read` tool and the `devframe://state/<key>` resources.
-   * - `true` (default): every key the host publishes
-   * - `false`: none
-   * - `(key) => boolean`: only the keys the filter accepts
+   * Self-revoke: the caller asks the server to revoke its own bearer token
+   * (if any) and drop to untrusted. Requires an already-trusted caller, so
+   * unlike the two handshake methods above it does **not** carry the
+   * `anonymous:` prefix. Registered by `recipes/interactive-auth`.
    *
-   * The states themselves stay available to the UI over RPC.
+   * @internal
    */
-  exposeSharedState?: boolean | ((key: string) => boolean);
+  'devframe:auth:revoke': () => Promise<void>;
   /**
-   * Usage guidance for the route, sent as `instructions` in the MCP
-   * `initialize` (and `server/discover`) result. An MCP client can add it to
-   * the coding agent's context, for example to say which tool to call first.
-   * Omitted or empty sends no instructions.
+   * Subscribe a client to a shared-state key. Wired by
+   * `RpcSharedStateHost`; do not register manually.
+   *
+   * @internal
    */
-  instructions?: string;
+  'devframe:rpc:server-state:subscribe': (key: string) => Promise<void>;
   /**
-   * Resource templates the route serves through MCP
-   * `resources/templates/list`. `resources/read` tries them after the
-   * registered resources and the shared-state resources (a
-   * `devframe://resource/` or `devframe://state/` URI never reaches them);
-   * the first template whose `uriTemplate` matches the URI reads it. `resources/list` adds the
-   * entries each template's `list` returns. Omitted or empty keeps the
-   * resources unchanged.
+   * Read the current value for a shared-state key. Wired by
+   * `RpcSharedStateHost`; do not register manually.
+   *
+   * @internal
    */
-  resourceTemplates?: McpResourceTemplate[];
+  'devframe:rpc:server-state:get': (key: string) => Promise<any>;
   /**
-   * Host subscription for resource-list changes. Call `notify()` each time
-   * the resources change (for example, the entries of a resource template);
-   * the route then sends `notifications/resources/list_changed`. Return a
-   * function that removes the subscription; the route calls it on teardown.
+   * Replace a shared-state value (from the client). Wired by
+   * `RpcSharedStateHost`; do not register manually.
+   *
+   * @internal
    */
-  onResourcesChanged?: McpResourcesChangedHook;
+  'devframe:rpc:server-state:set': (key: string, value: any, syncId: string) => Promise<void>;
   /**
-   * Prompt templates the route serves through MCP `prompts/list` and
-   * `prompts/get`. Omitted or empty declares no `prompts` capability.
+   * Apply a patch to a shared-state value (from the client). Wired by
+   * `RpcSharedStateHost`; do not register manually.
+   *
+   * @internal
    */
-  prompts?: McpPrompt[];
-}
-interface DevframeCliOptions {
-  /** Binary name; default: the devframe's `id`. */
-  command?: string;
-  /** Preferred port for the dev server (default 9999). */
-  port?: number;
-  /** Port scan range, forwarded to `get-port-please`. */
-  portRange?: [number, number];
-  /** Prefer a random open port. */
-  random?: boolean;
-  /** Default host to bind to; `--host` overrides. */
-  host?: string;
+  'devframe:rpc:server-state:patch': (key: string, patches: any[], syncId: string) => Promise<void>;
   /**
-   * Auto-open the browser when the dev server starts.
-   * `true` opens the resolved origin; a string opens that relative path.
-   * The `--open` / `--no-open` flags override this.
+   * Client→server streaming subscription with optional replay cursor.
+   * Wired by `RpcStreamingHost`; do not register manually.
+   *
+   * @internal
    */
-  open?: boolean | string;
+  'devframe:streaming:subscribe': (channel: string, id: string, opts?: {
+    afterSeq?: number;
+  }) => Promise<void>;
   /**
-   * Authentication for the standalone dev server.
-   *
-   *   - `undefined` / `true`: the standalone adapters (`cli` /
-   *     served `build`) auto-wire devframe's interactive OTP auth
-   *     (`createInteractiveAuth`): an untrusted client can only reach
-   *     `anonymous:` methods until it exchanges the printed one-time code.
-   *     The adapter prints the code + magic-link banner once the server is
-   *     listening.
-   *   - `false`: no gate, for trusted single-user localhost tools where an
-   *     auth round-trip only gets in the way (the built-in plugins set this).
-   *     The `--no-auth` CLI flag maps here for one-off runs.
-   *   - A {@link DevframeAuthHandler}: a custom handler (e.g. a tuned
-   *     `createInteractiveAuth`, or an entirely different scheme) passed
-   *     straight through to the RPC transport binding.
+   * Client→server streaming unsubscribe. Wired by `RpcStreamingHost`;
+   * do not register manually.
    *
-   * Hosted adapters (`vite`, `embedded`) ignore this and defer to the host's
-   * auth; `@vitejs/devtools` honors the equivalent `devtools.clientAuth`.
+   * @internal
+   */
+  'devframe:streaming:unsubscribe': (channel: string, id: string) => Promise<void>;
+  /**
+   * Client→server streaming cancellation request. Wired by
+   * `RpcStreamingHost`; do not register manually.
    *
-   * @default true
+   * @internal
    */
-  auth?: boolean | DevframeAuthHandler;
+  'devframe:streaming:cancel': (channel: string, id: string) => Promise<void>;
   /**
-   * How the browser reaches the RPC WebSocket. Defaults to sharing the HTTP
-   * port on the `__ws` route. See {@link DevframeWsOptions} for the
-   * different-port and remote-origin variants. Pass `false` to serve no
-   * WebSocket at all; clients connect over SSE instead (`backend: 'sse'`).
-   */
-  ws?: DevframeWsOptions | false;
-  /**
-   * How the browser reaches the SSE RPC endpoint, enabled by default
-   * alongside the WebSocket as the more portable transport. Pass `false`
-   * to disable, or a {@link DevframeSseOptions} to change its route.
-   */
-  sse?: boolean | DevframeSseOptions;
-  /**
-   * Capability-side CAC hook. Called with the CAC instance after the
-   * adapter registers its built-in commands (`build` / `mcp`)
-   * but before `createCac`'s own `configureCli` caller. Use this to
-   * contribute tool-specific flags and subcommands from the definition
-   * itself.
+   * Client→server upload chunk. Wired by `RpcStreamingHost`; do not
+   * register manually.
+   *
+   * @internal
    */
-  configure?: (cli: CAC) => void;
+  'devframe:streaming:upload-chunk': (channel: string, id: string, seq: number, chunk: any) => Promise<void>;
   /**
-   * Typed CLI flags for the default `dev` command, backed by any
-   * [Standard Schema](https://standardschema.dev/) validator (valibot,
-   * zod, arktype, or devframe's built-in `s`). The adapter registers
-   * matching `--kebab-key` options on CAC, validates the parsed values,
-   * and forwards the typed bag to `setup(ctx, { flags })`.
-   *
-   * Use {@link defineCliFlags} to preserve the literal schema-map
-   * shape, and {@link InferCliFlags} to recover the typed output at the
-   * call site:
-   *
-   * ```ts
-   * const appFlags = defineCliFlags({
-   *   depth: v.pipe(v.number(), v.integer()),
-   *   config: v.optional(v.string()),
-   * })
+   * Client→server upload terminator. Wired by `RpcStreamingHost`; do not
+   * register manually.
    *
-   * defineDevframe({
-   *   cli: { flags: appFlags },
-   *   setup(ctx, info) {
-   *     const flags = info.flags as InferCliFlags<typeof appFlags>
-   *   },
-   * })
-   * ```
+   * @internal
    */
-  flags?: CliFlagsSchema;
+  'devframe:streaming:upload-end': (channel: string, id: string, error?: {
+    name: string;
+    message: string;
+  }) => Promise<void>;
 }
 /**
- * Default dock attributes for the iframe entry a hub synthesizes when it
- * mounts this devframe. Framework-neutral metadata only; the hub layer
- * (`ctx.install`) merges these beneath its per-mount `dock` overrides,
- * which in turn sit beneath the locked, derived `id` / `type` / `url`.
- *
- * Every field is optional. `title` / `icon` default to the definition's
- * `name` / `icon` when omitted here; the rest are unset by default.
- * Standalone adapters (`cli` / `build`) ignore this entirely.
+ * To be extended
  */
-interface DevframeDockDefaults {
-  /** Dock entry title. Defaults to the definition's `name`. */
-  title?: string;
-  /** Translations of `title` by BCP 47 tag; see `@devframes/hub`'s `resolveTitle()`. */
-  titleLocales?: Record<string, string>;
-  /** Dock entry icon. Defaults to the definition's `icon`. */
-  icon?: string | {
-    light: string;
-    dark: string;
-  };
+interface DevframeRpcSharedStates {
   /**
-   * Sort weight within the dock; higher sorts earlier.
-   * @default 0
+   * Wire-service advertisements: package name → `{ package, version,
+   * scope, meta }` for every installed {@link import('./services').DevframeServiceDefinition}.
+   * Written by the node services host at the `ready()` barrier; clients read
+   * it through `client.services` (or subscribe to it directly for
+   * reactivity). Read-only from the browser.
    */
-  defaultOrder?: number;
+  'devframe:services': DevframeServicesState;
+}
+interface DevframeNodeRpcSession {
+  meta: DevframeNodeRpcSessionMeta;
+  rpc: BirpcReturn<DevframeRpcClientFunctions, DevframeRpcServerFunctions, false>;
+}
+interface RpcBroadcastOptions<METHOD, Args extends any[]> {
+  method: METHOD;
+  args: Args;
+  optional?: boolean;
+  event?: boolean;
+  filter?: (client: BirpcReturn<DevframeRpcClientFunctions, DevframeRpcServerFunctions, false>) => boolean | void;
+}
+type RpcFunctionsHost = RpcFunctionsCollectorBase<DevframeRpcServerFunctions, DevframeNodeContext> & {
   /**
-   * Category the entry groups under in the dock.
-   * @default 'default'
+   * Invoke a locally registered server RPC function directly.
+   *
+   * This bypasses transport and is useful for server-side cross-function calls.
    */
-  category?: string;
+  invokeLocal: <T extends keyof DevframeRpcServerFunctions, Args extends Parameters<DevframeRpcServerFunctions[T]>>(method: T, ...args: Args) => Promise<Awaited<ReturnType<DevframeRpcServerFunctions[T]>>>;
   /**
-   * Conditional-visibility expression (same syntax as command `when`
-   * clauses). Set to `'false'` to hide the entry unconditionally.
+   * Broadcast a message to all connected clients
    */
-  when?: string;
+  broadcast: <T extends keyof DevframeRpcClientFunctions, Args extends Parameters<DevframeRpcClientFunctions[T]>>(options: RpcBroadcastOptions<T, Args>) => Promise<void>;
   /**
-   * Render-only visibility expression, same syntax as {@link when}. Hides the
-   * entry's own dock-bar button when it evaluates to `false` while leaving it
-   * registered and reachable (activation, RPC lookups, etc.), unlike `when`,
-   * which is the general relevance switch for the entry as a whole.
+   * Get the current RPC client
+   *
+   * Available in RPC functions to get the current RPC client
    */
-  visibility?: string;
-  /** Badge text rendered on the dock icon (e.g. an unread count). */
-  badge?: string;
-  /** Id of the dock group this entry collapses under, if any. */
-  groupId?: string;
+  getCurrentRpcSession: () => DevframeNodeRpcSession | undefined;
   /**
-   * A client script the hub imports into the host page (this devframe's **page
-   * script**). An absolute-path `importFrom` is served by the hub under the
-   * mount base and rewritten to that URL, so mounting by package name needs no
-   * host wiring; a URL or bare specifier passes through untouched.
+   * The shared state host
    */
-  clientScript?: {
-    /**
-     * Initialize after RPC trust without waiting for dock activation.
-     * @default false
-     */
-    eager?: boolean;
-    /** An absolute filesystem path, a served URL, or a bare npm specifier. */
-    importFrom: string;
-    /**
-     * The name to import the module as.
-     * @default 'default'
-     */
-    importName?: string;
-  };
-}
-/**
- * Runtime information threaded into `setup(ctx, info)`. Adapters
- * populate the fields that make sense for their deployment. In
- * particular, `createCac` fills `flags` with the parsed CAC bag.
- */
-interface DevframeSetupInfo {
-  /** Parsed CLI flags, populated by the CLI adapter. */
-  flags?: Record<string, unknown>;
-}
-interface DevframeDefinition {
-  id: string;
-  name: string;
-  /** Semver of the tool, surfaced in hub UIs and diagnostics. */
-  version: string;
-  /** npm package name the devframe ships in (e.g. `@scope/my-tool`). */
-  packageName: string;
+  sharedState: RpcSharedStateHost;
   /**
-   * `import.meta.url` of the module that defines this devframe. **Always
-   * provide it** (`importMetaUrl: import.meta.url`): it is the resolution base
-   * for the tool's own dependency graph, which lets the host resolve
-   * everything against the plugin's own installed packages rather than the
-   * consuming app's.
-   *
-   * - **Remote assets**: becomes the default `resolveFrom` for any remote
-   *   {@link StaticAssetsSource} the devframe hosts (its `clientAssets`, and
-   *   every `ctx.views.hostStatic` call) that doesn't set one explicitly, so a
-   *   locally installed copy of the assets package is served with zero
-   *   network. A per-asset `resolveFrom` still wins, and an explicit
-   *   `resolveFrom: null` still opts out.
-   * - **Service dependencies**: becomes the base the host resolves declared
-   *   {@link DevframeServiceInput | services} from, so a plugin can ship a
-   *   service package as its own dependency instead of asking users to install
-   *   it.
+   * The streaming channel host. Provides per-channel `start()` /
+   * `pipeFrom()` producers; clients consume via `rpc.streaming.subscribe()`.
    *
-   * Optional for backward compatibility; omitting it falls back to
-   * runtime-directory resolution and disables the zero-network installed-copy
-   * fast paths above.
+   * @see RpcStreamingHost
    */
-  importMetaUrl?: string;
-  /** Project homepage or documentation URL. */
-  homepage: string;
-  /** One-line summary of what the tool does. */
-  description: string;
-  icon?: string | {
-    light: string;
-    dark: string;
-  };
+  streaming: RpcStreamingHost;
+};
+interface RpcSharedStateGetOptions<T> {
+  sharedState?: SharedState<T>;
+  initialValue?: T;
+}
+interface RpcSharedStateHost {
+  get: <T extends object = any>(key: string, options?: RpcSharedStateGetOptions<T>) => Promise<SharedState<T>>;
+  keys: () => string[];
   /**
-   * Default dock attributes applied when a hub mounts this devframe as an
-   * iframe dock entry. Consulted only by the hub install path (`ctx.install`),
-   * which merge these beneath the per-mount `dock` overrides; standalone
-   * adapters (`cli` / `build`) ignore it.
-   *
-   * @see {@link DevframeDockDefaults}
+   * Subscribe to new shared-state keys becoming available. Fires when
+   * `get(key, ...)` creates a fresh entry (not on subsequent gets).
+   * Useful for protocol adapters (e.g. MCP) that surface shared state
+   * as dynamic resources.
    */
-  dock?: DevframeDockDefaults;
+  onKeyAdded: (fn: (key: string) => void) => () => void;
   /**
-   * Mount path override. Defaults depend on the adapter:
-   * `/` for standalone (`cli` / `build`), `/__<id>/` for hosted
-   * (`vite` / `embedded`).
+   * Unregister a shared state and drop its broadcast listeners. Returns
+   * `true` when a state was removed, `false` when the key was unknown.
+   * Used by short-lived states (e.g. a disposed JSON-render view) to avoid
+   * leaking listeners and lingering entries for the context lifetime.
    */
-  basePath?: string;
+  delete: (key: string) => boolean;
+}
+/**
+ * Options for `RpcStreamingHost.create()`.
+ */
+interface RpcStreamingChannelOptions {
   /**
-   * How a hub reacts when another devframe sharing this one's `id` is
-   * mounted onto the same hub. Consulted only by hub adapters
-   * (`ctx.install`); standalone adapters (`cli` / `build`)
-   * ignore it.
+   * Size of the per-stream ring buffer kept on the server for
+   * replay-on-resubscribe. `0` (default) disables replay; on reconnect
+   * the consumer only sees chunks that arrive after subscribing.
    *
-   * @default 'warn'
+   * The buffer is per stream id, not per channel; each `channel.start()`
+   * gets its own.
    */
-  duplicationStrategy?: DevframeDuplicationStrategy;
+  replayWindow?: number;
   /**
-   * Declares which runtimes meaningfully support this devframe. Adapters
-   * act on a `false` before doing any work:
+   * Milliseconds a closed stream is retained on the server after its
+   * last subscriber leaves (or if no subscriber ever arrived). During
+   * this window, late subscribers can still join and replay the buffer
+   * + receive the `end` frame.
    *
-   * - `build: false`: `createCac` skips registering the `build` subcommand,
-   *   `createBuild` refuses (throws `DF0042`) unless `{ force: true }`, and
-   *   a hub static build (`buildHub`) silently skips the devframe - no dock,
-   *   no SPA copy, no RPCs in the dump. Useful for a devframe whose value is
-   *   inherently live (e.g. it manages real files on disk), so a static
-   *   export would only ever produce a broken, write-less shell of the tool.
-   * - `dev: false`: `createDevServer` refuses (throws `DF0058`) unless
-   *   `{ force: true }`. Useful for a devframe that only makes sense as a
-   *   static export (e.g. a report generator with nothing to serve live).
+   * Defaults to `30_000` (30 s) when `replayWindow > 0`, else `0`
+   * (immediate free). Set to `0` to opt out, or higher for longer
+   * post-mortem replay.
    */
-  capabilities?: {
-    dev?: boolean;
-    build?: boolean;
-  };
+  closedStreamRetention?: number;
+}
+/**
+ * Channel handle returned by `ctx.rpc.streaming.create(name, opts)`. A
+ * channel owns a wire namespace; calling `start()` produces individual
+ * streams keyed by id.
+ *
+ * @see {@link https://devfra.me/guide/streaming Streaming guide}
+ */
+interface RpcStreamingChannel<T = unknown> {
+  /** Channel name as registered with `ctx.rpc.streaming.create()`. */
+  readonly name: string;
   /**
-   * Wire services this devframe consumes (see `DevframeServiceDefinition`).
-   * Each entry is either a declarative descriptor
-   * (`{ package, version?, required?, options? }`, where the host imports the
-   * package's default-export factory, resolving it against **this plugin's
-   * own dependencies**) or a ready `DevframeServiceDefinition` (the factory
-   * was already called). The adapter queues these before `setup(ctx)` runs
-   * and constructs each service once at the `ctx.services.ready()` barrier,
-   * merging option sets across every declarer. Missing services are skipped
-   * unless marked `required`; clients feature-detect via
-   * `client.services.has(pkg)` and degrade.
+   * Start a new stream. Returns a server-side sink with both an imperative
+   * (`write` / `close` / `error`) surface and a `WritableStream<T>` for
+   * `pipeTo` consumption. The sink's `signal` aborts when every subscriber
+   * disconnects or cancels.
    */
-  services?: DevframeServiceInput[];
+  start: (opts?: {
+    id?: string;
+  }) => StreamSink<T>;
   /**
-   * Author's SPA dist, served as the devframe's UI. A local directory, or
-   * a {@link StaticAssetsSource} remote declaration (`{ package, version }`)
-   * served through devframe's caching CDN back-proxy so the assets need not
-   * ship inside the node package.
+   * Convenience: start a stream and pipe a `ReadableStream<T>` into it.
+   * The pipe uses `sink.signal` so cancellation propagates upstream.
    *
-   * Consumed by every adapter that serves the UI (`dev`, `build`, `vite`,
-   * `next`, and the hub install path).
+   * Node-stream interop: convert a `Readable` with `Readable.toWeb(node)`
+   * before passing it here.
    */
-  clientAssets?: StaticAssetsSource;
-  /** RPC-level configuration for this devframe (see {@link DevframeRpcOptions}). */
-  rpc?: DevframeRpcOptions;
-  /** Server-side setup: the primary entrypoint. Runs in every runtime. */
-  setup: (ctx: DevframeNodeContext, info?: DevframeSetupInfo) => void | Promise<void>;
-  cli?: DevframeCliOptions;
-}
-interface DevframeRpcOptions {
+  pipeFrom: (readable: ReadableStream<T>, opts?: {
+    id?: string;
+  }) => Promise<StreamSink<T>>;
+  /** Look up an active stream by id. Returns `undefined` if none. */
+  get: (id: string) => StreamSink<T> | undefined;
+  /** All active outbound stream ids on this channel. */
+  ids: () => string[];
   /**
-   * Opt an RPC function into the static-build snapshot **without owning its
-   * definition**, the mechanism a devframe uses to bake a wire service's
-   * RPC (e.g. `@devframes/service-git`'s `status`/`log`/`show`) into its
-   * `build` export, since the service itself defines no `dump`/`snapshot`.
+   * Open an inbound stream: the server side of a client-to-server
+   * upload. Allocates an id, returns a `StreamReader<T>` that fills as
+   * the client writes chunks. Typical pattern is to call this from an
+   * action handler, kick off background processing, and return the id
+   * so the caller can start uploading:
    *
-   * Each entry is either a bare method id (bakes the no-argument call, like
-   * `snapshot: true`) or `{ method, inputs }` where `inputs` is the list of
-   * argument-tuples to bake, or an async provider given the node context
-   * (so it can enumerate at build time, e.g. read commit hashes via the
-   * service's node API). `createBuild` resolves these after setup and
-   * executes the target's own handler per tuple; the first tuple's result
-   * becomes the fallback so any call variant resolves to a baked value.
+   * ```ts
+   * handler: async () => {
+   *   const reader = channel.openInbound()
+   *   ;(async () => {
+   *     for await (const chunk of reader) processChunk(chunk)
+   *   })()
+   *   return { uploadId: reader.id }
+   * }
+   * ```
+   *
+   * Calling `reader.cancel()` on the server sends an `upload-cancel` to
+   * the uploading client, which aborts its sink.
    */
-  snapshot?: DevframeSnapshotRpcEntry[];
+  openInbound: (opts?: {
+    id?: string;
+  }) => StreamReader<T>;
 }
-/** Argument-tuples to bake for a {@link DevframeSnapshotRpcEntry}, or a provider that computes them at build time. */
-type DevframeSnapshotRpcInputs = readonly (readonly unknown[])[] | ((ctx: DevframeNodeContext) => readonly (readonly unknown[])[] | Promise<readonly (readonly unknown[])[]>);
-/**
- * One {@link DevframeRpcOptions.snapshot} entry: a bare method id (bakes
- * the no-argument call) or a method plus the argument-tuples to bake.
- */
-type DevframeSnapshotRpcEntry = string | {
-  method: string;
-  inputs: DevframeSnapshotRpcInputs;
-};
-//#endregion
-//#region src/utils/shared-state.d.ts
-type ImmutablePrimitive = undefined | null | boolean | string | number | Function;
-type Immutable<T> = T extends ImmutablePrimitive ? T : T extends Array<infer U> ? ImmutableArray<U> : T extends Map<infer K, infer V> ? ImmutableMap<K, V> : T extends Set<infer M> ? ImmutableSet<M> : ImmutableObject<T>;
-type ImmutableArray<T> = ReadonlyArray<Immutable<T>>;
-type ImmutableMap<K, V> = ReadonlyMap<Immutable<K>, Immutable<V>>;
-type ImmutableSet<T> = ReadonlySet<Immutable<T>>;
-type ImmutableObject<T> = { readonly [K in keyof T]: Immutable<T[K]>; };
 /**
- * Serializable patch describing a single mutation to a `SharedState`.
- * Structurally compatible with JSON-Patch and is safe to send over RPC.
+ * Server-side streaming host. Lives on `ctx.rpc.streaming` alongside
+ * `ctx.rpc.sharedState`. Each named channel owns its own stream registry
+ * and wire namespace.
  */
-interface SharedStatePatch {
-  op: 'add' | 'remove' | 'replace';
-  path: readonly (string | number)[];
-  value?: unknown;
+interface RpcStreamingHost {
+  /**
+   * Register a streaming channel. Names follow the `<plugin-id>:<channel>`
+   * convention (e.g. `'my-devtool:chat-stream'`). Throws `DF0032` if the
+   * name is already taken.
+   */
+  create: <T = unknown>(name: string, opts?: RpcStreamingChannelOptions) => RpcStreamingChannel<T>;
+  /**
+   * Adapters call this when a session disconnects so the host can drop
+   * subscribers and abort orphaned streams. Most users do not need this;
+   * it's wired by the RPC server binding automatically.
+   *
+   * @internal
+   */
+  _onSessionDisconnected: (meta: DevframeNodeRpcSessionMeta) => void;
+}
+interface DevframeCapabilities {
+  rpc?: boolean;
+  views?: boolean;
 }
 /**
- * State host that is immutable by default with explicit mutate.
+ * Framework- and build-tool-agnostic node context: RPC + diagnostics +
+ * agent + the view-host (HTTP file-serving). Host adapters can wrap this
+ * to add their own surfaces; for example, `@vitejs/devtools-kit`'s
+ * `createKitContext` adds `docks`, `terminals`, `messages`, and
+ * `commands` when mounted into Vite DevTools. JSON rendering is an opt-in
+ * integration (`@devframes/json-render`) layered on top, not part of this
+ * core surface.
  */
-interface SharedState<T> {
+interface DevframeNodeContext {
+  readonly workspaceRoot: string;
+  readonly cwd: string;
   /**
-   * Get the current state. Immutable.
+   * Lifecycle distinction surfaced to plugin authors:
+   *
+   *   - `'dev'`:   long-running, interactive session. Connections come and
+   *                 go; broadcasts and shared-state mutations are debounced
+   *                 to keep the UI responsive.
+   *   - `'build'`: one-shot batch run. The context is set up, the devtool
+   *                 collects what it needs, and a snapshot is written. No
+   *                 live UI, no WS server.
+   *
+   * Names are inherited from Vite's serve/build dichotomy but the meaning
+   * is general: the same distinction applies to any tool that runs in
+   * either an interactive or a static-output mode.
    */
-  value: () => Immutable<T>;
+  readonly mode: 'dev' | 'build';
   /**
-   * Subscribe to state changes.
+   * Host runtime abstraction, exposing `mountStatic` / `resolveOrigin` /
+   * `getStorageDir`.
    */
-  on: EventEmitter<SharedStateEvents<T>>['on'];
+  host: DevframeHost;
+  rpc: RpcFunctionsHost;
+  views: DevframeViewHost;
   /**
-   * Mutate the state.
+   * Structured diagnostics host; wraps `nostics` and lets integrations
+   * register their own coded errors/warnings into the shared lookup.
    */
-  mutate: (fn: (state: T) => void, syncId?: string) => void;
+  diagnostics: DevframeDiagnosticsHost;
   /**
-   * Apply patches to the state.
+   * Agent host; aggregates the agent-exposed surface of this devtool.
    */
-  patch: (patches: SharedStatePatch[], syncId?: string) => void;
+  agent: DevframeAgentHost;
   /**
-   * Sync IDs that have been applied to the state.
+   * Cross-plugin services: a typed, namespaced registry through which one
+   * integration exposes a capability (e.g. a data-source registry) and
+   * others consume it without a hard package dependency. Ids follow the RPC
+   * namespacing rule (`<plugin-id>:<service>`); types come from augmenting
+   * the `DevframeServicesRegistry` interface. `whenAvailable` subscriptions
+   * absorb setup-order differences between provider and consumer.
    */
-  syncIds: Set<string>;
-}
-interface SharedStateEvents<T> {
-  updated: (fullState: T, patches: SharedStatePatch[] | undefined, syncId: string) => void;
-}
-interface SharedStateOptions<T> {
+  services: DevframeServicesHost;
   /**
-   * Initial state.
+   * This context's own {@link ConnectionMeta.configs}: static, boot-time
+   * config a host publishes once through the connection handshake and every
+   * client reads read-only. A plain, **non-reactive** object: mutate it
+   * during `setup(ctx)` (a plugin sets its keys, a hub aggregates across
+   * every installed devframe), never during the session, since it's serialized
+   * once, after setup, and changing it afterwards reaches no client.
+   *
+   * ```ts
+   * ctx.staticConfig.dock = {
+   *   ...ctx.staticConfig.dock,
+   *   categoryOrder: { ...ctx.staticConfig.dock?.categoryOrder, ...myOrder },
+   * }
+   * ```
    */
-  initialValue: T;
+  staticConfig: Partial<DevframeConnectionConfigsRegistry>;
   /**
-   * Enable patches.
+   * Create a namespace-scoped view of this context. The returned
+   * `ctx.scope('my-plugin')` auto-namespaces every RPC id, shared-state
+   * key, and streaming channel with `my-plugin:`, and exposes a typed
+   * top-level `settings` store. This is the preferred way to consume the
+   * context from a single tool's setup code.
    *
-   * @default false
+   * Pass `null` or `''` to un-scope and get the base context.
    */
-  enablePatches?: boolean;
+  scope: {
+    <NS extends string>(namespace: NS): DevframeScopedNodeContext<NS, SettingsForNamespace<NS>>;
+    (namespace?: null | ''): DevframeNodeContext;
+  };
 }
-declare function createSharedState<T extends object>(options: SharedStateOptions<T>): SharedState<T>;
-//#endregion
-//#region src/utils/streaming-channel.d.ts
 /**
- * Serialized error shape sent over the wire when a stream ends with a failure.
- * Stays JSON-safe so the strict-JSON encoder can carry it without coercion.
+ * Describes where the browser client should open its RPC WebSocket. The
+ * object form is the proxy-flexible default: `path` is resolved relative to
+ * where `__connection.json` was loaded, and the connection is made to the
+ * page's own origin (only the `http`→`ws` / `https`→`wss` protocol swap is
+ * applied). This survives reverse proxies that change the host/port, because
+ * the client never trusts a server-baked hostname; it reuses its own.
+ *
+ * Set `port` (and/or `host`) only when the WS endpoint genuinely lives on a
+ * different origin than the page, e.g. a side-car server on its own port.
  */
-interface StreamErrorPayload {
-  name: string;
-  message: string;
+interface ConnectionMetaWebsocket {
+  /**
+   * Path to the WS endpoint. Relative paths (the default, e.g. `__ws`) are
+   * resolved against `__connection.json`'s location; absolute paths (`/__ws`)
+   * resolve against the page origin.
+   */
+  path?: string;
+  /** Override the port. Combined with the page hostname unless `host` is set. */
+  port?: number;
+  /** Override the host (`hostname[:port]`). Use for a fully cross-origin endpoint. */
+  host?: string;
 }
 /**
- * Single buffered chunk in the server-side ring buffer.
- *
- * Sequence numbers start at 1 and increment per write. Subscribers track
- * `lastSeenSeq` and ask for `afterSeq` on resubscribe so the server can
- * replay any chunks the client missed during a brief disconnect.
+ * Object form of {@link ConnectionMeta.sse}: the same proxy-safe shape and
+ * resolution rules as {@link ConnectionMetaWebsocket}, producing an
+ * `http(s)://` endpoint instead of a `ws(s)://` one. Set `port` (and/or
+ * `host`) only when the SSE endpoint genuinely lives on a different origin
+ * than the page, e.g. a side-car server on its own port.
  */
-interface BufferedChunk<T> {
-  seq: number;
-  chunk: T;
-}
-interface StreamSinkEvents<T> {
-  /** Fired for each `write()`. The RPC layer subscribes and broadcasts. */
-  chunk: (seq: number, chunk: T) => void;
-  /** Terminal; fired exactly once per sink lifetime. */
-  end: (error?: StreamErrorPayload) => void;
-}
-interface CreateStreamSinkOptions {
-  id?: string;
+interface ConnectionMetaSse {
   /**
-   * Size of the per-stream ring buffer kept for replay-on-resubscribe.
-   * `0` (default) disables replay.
+   * Path to the SSE endpoint. Relative paths (the default, e.g. `__sse`)
+   * are resolved against `__connection.json`'s location; absolute paths
+   * (`/__sse`) resolve against the page origin.
    */
-  replayWindow?: number;
+  path?: string;
+  /** Override the port. Combined with the page hostname unless `host` is set. */
+  port?: number;
+  /** Override the host (`hostname[:port]`). Use for a fully cross-origin endpoint. */
+  host?: string;
 }
-/**
- * Server-side producer handle. Two equivalent surfaces share one piece of
- * state: the imperative `write/error/close` triple, and a `WritableStream<T>`
- * for `pipeTo`-style consumption.
- */
-interface StreamSink<T> {
-  /** Stable id used by clients to subscribe. */
-  readonly id: string;
+interface ConnectionMeta {
   /**
-   * Aborts when the consumer cancels (server-side) or when the transport
-   * loses every subscriber. Producers should poll `signal.aborted` and exit
-   * cleanly.
+   * The server's primary live-RPC transport (`websocket` / `sse`), `static`
+   * for a pre-computed RPC dump with no live server, or `none` for a server
+   * exposing no RPC transport at all (e.g. an MCP-only deployment).
    */
-  readonly signal: AbortSignal;
-  /** `true` after `close()` / `error()`. Further writes throw. */
-  readonly closed: boolean;
-  /** Last allocated sequence number. `0` until the first write. */
-  readonly lastSeq: number;
-  write: (chunk: T) => void;
-  error: (reason: unknown) => void;
-  close: () => void;
-  /** External-cancel path. Aborts the signal so handlers can short-circuit. */
-  abort: (reason?: unknown) => void;
-  /** `WritableStream<T>` adapter; same in-memory state as the imperative API. */
-  readonly writable: WritableStream<T>;
+  backend: 'websocket' | 'sse' | 'static' | 'none';
   /**
-   * Internal: RPC layer subscribes to receive chunk/end notifications.
-   * Not part of the public contract; do not call directly.
+   * WebSocket endpoint, resolved by the client into a `ws(s)://` URL:
    *
-   * @internal
+   *   - {@link ConnectionMetaWebsocket}: the proxy-flexible default; a
+   *     same-origin path relative to `__connection.json`.
+   *   - `number`: a port on the page's hostname (`ws(s)://<host>:<port>`).
+   *   - `string`: a full `ws://`/`wss://` URL used verbatim, an `http(s)://`
+   *     URL with its protocol swapped, or a path resolved same-origin.
    */
-  readonly events: EventEmitter<StreamSinkEvents<T>>;
+  websocket?: number | string | ConnectionMetaWebsocket;
   /**
-   * Internal replay buffer. RPC layer reads on (re)subscribe to feed
-   * missed chunks before going live.
+   * SSE endpoint (`GET` opens the event stream, `POST` carries RPC calls),
+   * resolved by the client into an `http(s)://` URL with the same
+   * proxy-safe rules as {@link ConnectionMeta.websocket}:
    *
-   * @internal
+   *   - {@link ConnectionMetaSse}: the proxy-flexible default; a
+   *     same-origin path relative to `__connection.json`.
+   *   - `string`: a full `http(s)://` URL used verbatim, or a path
+   *     resolved same-origin.
    */
-  readonly buffer: ReadonlyArray<BufferedChunk<T>>;
-}
-interface CreateStreamReaderOptions {
-  id?: string;
+  sse?: string | ConnectionMetaSse;
   /**
-   * Maximum number of buffered chunks held client-side while the consumer
-   * isn't draining. On overflow, the oldest chunk is dropped.
+   * Present when the dev server exposes a route-based MCP endpoint
+   * (the host's `mcp` setting). Advertises the MCP Streamable-HTTP route so in-browser
+   * tooling (e.g. an MCP inspector) can discover it without guessing the
+   * path. `path` is relative to `__connection.json`'s location, like the
+   * WebSocket `path`. `port` is set when the endpoint lives on a side-car
+   * server on its own port (bridge mode: `devframeViteBridge`,
+   * `@devframes/next`): the client combines the page hostname with `port`
+   * and resolves `path` against that origin, mirroring
+   * {@link ConnectionMetaWebsocket.port}.
    */
-  highWaterMark?: number;
+  mcp?: {
+    path: string;
+    port?: number;
+  };
   /**
-   * Called when the chunk queue overflows the high-water mark. The RPC
-   * layer wires this to a coded warning; the primitive itself is
-   * RPC-agnostic.
+   * Names of RPC functions that have declared `jsonSerializable: true`.
+   * Used by the WS / static client to dispatch the per-call wire
+   * serializer (strict JSON for these methods, structured-clone for
+   * the rest). Populated by the server / build adapter; absent on
+   * legacy clients, in which case all outgoing messages fall back to
+   * structured-clone.
    */
-  onOverflow?: (dropped: number) => void;
-  /** Called when the consumer cancels; the RPC layer sends `:cancel` upstream. */
-  onCancel?: () => void;
-}
-/**
- * Client-side consumer handle. Both an `AsyncIterable<T>` (for `for await`)
- * and exposes `readable: ReadableStream<T>` (for `pipeTo`). Pick one; they
- * share a single internal queue, so concurrent draining will race.
- */
-interface StreamReader<T> extends AsyncIterable<T> {
-  readonly id: string;
-  readonly cancelled: boolean;
-  readonly done: boolean;
-  /** Highest `seq` observed. Used for replay on reconnect. */
-  readonly lastSeenSeq: number;
-  /** `ReadableStream<T>` adapter for `pipeTo`-style consumption. */
-  readonly readable: ReadableStream<T>;
-  cancel: () => void;
-  /** @internal */
-  _push: (seq: number, chunk: T) => void;
-  /** @internal */
-  _end: (error?: StreamErrorPayload) => void;
-}
-/**
- * Build a server-side stream sink. RPC-agnostic; the RPC host wires
- * `events.on('chunk' | 'end')` to broadcast, and reads `buffer` to replay
- * for late or reconnecting subscribers.
- */
-declare function createStreamSink<T>(options?: CreateStreamSinkOptions): StreamSink<T>;
-/**
- * Build a client-side stream reader. RPC-agnostic; the RPC host calls
- * `_push(seq, chunk)` on each incoming chunk and `_end(error?)` on the
- * terminal frame. Consumers iterate with `for await` or pipe `readable`.
- */
-declare function createStreamReader<T>(options?: CreateStreamReaderOptions): StreamReader<T>;
-//#endregion
-//#region src/types/rpc.d.ts
-interface DevframeNodeRpcSession {
-  meta: DevframeNodeRpcSessionMeta;
-  rpc: BirpcReturn<DevframeRpcClientFunctions, DevframeRpcServerFunctions, false>;
-}
-interface RpcBroadcastOptions<METHOD, Args extends any[]> {
-  method: METHOD;
-  args: Args;
-  optional?: boolean;
-  event?: boolean;
-  filter?: (client: BirpcReturn<DevframeRpcClientFunctions, DevframeRpcServerFunctions, false>) => boolean | void;
-}
-type RpcFunctionsHost = RpcFunctionsCollectorBase<DevframeRpcServerFunctions, DevframeNodeContext> & {
+  jsonSerializableMethods?: string[];
   /**
-   * Invoke a locally registered server RPC function directly.
+   * URL of the `__connection.json` that owns this meta's relative paths.
+   * Two producers write it:
    *
-   * This bypasses transport and is useful for server-side cross-function calls.
-   */
-  invokeLocal: <T extends keyof DevframeRpcServerFunctions, Args extends Parameters<DevframeRpcServerFunctions[T]>>(method: T, ...args: Args) => Promise<Awaited<ReturnType<DevframeRpcServerFunctions[T]>>>;
-  /**
-   * Broadcast a message to all connected clients
+   *   - The client annotates it (absolute) when it publishes the meta on a
+   *     shared window for same-origin inheritance: a relative
+   *     `websocket.path` resolves against this, so a child SPA mounted at
+   *     another base (e.g. a hub mounting several devframes at `/__foo/`,
+   *     `/__bar/`, …) inherits a dialable endpoint rather than resolving the
+   *     path against its own mount.
+   *   - A static hub build serves it (base-absolute, e.g.
+   *     `/__devframes/__connection.json`) in each **per-frame** meta, so a
+   *     frame SPA that fetched its own copy still resolves the shared RPC
+   *     dump from the hub base. Resolved against the fetched URL.
    */
-  broadcast: <T extends keyof DevframeRpcClientFunctions, Args extends Parameters<DevframeRpcClientFunctions[T]>>(options: RpcBroadcastOptions<T, Args>) => Promise<void>;
+  baseUrl?: string;
   /**
-   * Get the current RPC client
+   * A pre-issued bearer token embedded in the meta so a client trusts the
+   * server on connect without any prompt or `localStorage` lookup. Only a
+   * **hub** serving a **per-frame** connection meta populates this; it
+   * authenticates once at the top level and bakes the resulting token into
+   * the meta each plugin iframe fetches, so a cross-origin frame (which
+   * cannot read the hub's `localStorage`) is still pre-authorized. The
+   * standalone `__connection.json` never carries a token.
    *
-   * Available in RPC functions to get the current RPC client
-   */
-  getCurrentRpcSession: () => DevframeNodeRpcSession | undefined;
-  /**
-   * The shared state host
+   * > [!WARNING]
+   * > A token in a fetchable JSON is only as protected as the URL serving
+   * > it. Emit it exclusively from hub-controlled, per-frame meta, never
+   * > from a publicly reachable static `__connection.json`.
    */
-  sharedState: RpcSharedStateHost;
+  authToken?: string;
   /**
-   * The streaming channel host. Provides per-channel `start()` /
-   * `pipeFrom()` producers; clients consume via `rpc.streaming.subscribe()`.
+   * Session-scoped token that lets a trusted external viewer register its
+   * browser origin before opening the WebSocket. The host includes it in the
+   * connection metadata, which the viewer obtains through the host page.
    *
-   * @see RpcStreamingHost
-   */
-  streaming: RpcStreamingHost;
-};
-interface RpcSharedStateGetOptions<T> {
-  sharedState?: SharedState<T>;
-  initialValue?: T;
-}
-interface RpcSharedStateHost {
-  get: <T extends object = any>(key: string, options?: RpcSharedStateGetOptions<T>) => Promise<SharedState<T>>;
-  keys: () => string[];
-  /**
-   * Subscribe to new shared-state keys becoming available. Fires when
-   * `get(key, ...)` creates a fresh entry (not on subsequent gets).
-   * Useful for protocol adapters (e.g. MCP) that surface shared state
-   * as dynamic resources.
+   * Treat this as a bearer credential. Keep connection metadata containing the
+   * token same-origin until the requesting origin has been verified.
    */
-  onKeyAdded: (fn: (key: string) => void) => () => void;
+  viewerOriginToken?: string;
   /**
-   * Unregister a shared state and drop its broadcast listeners. Returns
-   * `true` when a state was removed, `false` when the key was unknown.
-   * Used by short-lived states (e.g. a disposed JSON-render view) to avoid
-   * leaking listeners and lingering entries for the context lifetime.
+   * Static, host-declared configuration, baked in once at connect time and
+   * fixed for the life of the server (e.g. a hub's UI rebrand, or its
+   * aggregated dock-bar layout preferences). Read-only from the browser: a
+   * client only ever reads `rpc.connectionMeta.configs`, never writes to it.
+   *
+   * Contrast this with {@link DevframeSettingsRegistry} (`ctx.scope(ns).settings`)
+   * and a hub's `devframe:user-settings` shared-state key; both are
+   * mutable, user-editable, and synced bidirectionally over RPC for the
+   * life of the session. `configs` is the opposite: one-way, immutable,
+   * decided by whoever assembled the server.
+   *
+   * Each key is owned by one package, contributed via declaration merging:
+   *
+   * ```ts
+   * declare module 'devframe/types' {
+   *   interface DevframeConnectionConfigsRegistry {
+   *     'my-key': { some: 'shape' }
+   *   }
+   * }
+   * ```
    */
-  delete: (key: string) => boolean;
+  configs?: Partial<DevframeConnectionConfigsRegistry>;
 }
 /**
- * Options for `RpcStreamingHost.create()`.
+ * Augmentation point for {@link ConnectionMeta.configs}. Empty by default;
+ * a package that wants to publish static, boot-time config through the
+ * connection handshake augments this interface with its own key (see
+ * {@link ConnectionMeta.configs} for the pattern). `@devframes/hub`
+ * augments it with `dock`; `@devframes/hub-ui` augments it with `ui`.
  */
-interface RpcStreamingChannelOptions {
-  /**
-   * Size of the per-stream ring buffer kept on the server for
-   * replay-on-resubscribe. `0` (default) disables replay; on reconnect
-   * the consumer only sees chunks that arrive after subscribing.
-   *
-   * The buffer is per stream id, not per channel; each `channel.start()`
-   * gets its own.
-   */
-  replayWindow?: number;
+interface DevframeConnectionConfigsRegistry {}
+/**
+ * Schema map for typed CLI flags. Keys are flag names in camelCase, so
+ * this matches CAC's parsed-flag output ( `--no-open` → `noOpen` ). Each
+ * value is any [Standard Schema](https://standardschema.dev/) validator
+ * (valibot, zod, arktype, devframe's built-in `s`, …) used to both (a)
+ * derive the CAC option type when the flag is registered and (b) validate
+ * the parsed value before it's forwarded to `setup(ctx, { flags })`.
+ */
+type CliFlagsSchema = Record<string, StandardSchemaV1>;
+/**
+ * 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
+ *   },
+ * })
+ * ```
+ */
+declare function defineCliFlags<T extends CliFlagsSchema>(flags: T): T;
+/** Extract the parsed-output type from a {@link CliFlagsSchema}. */
+type InferCliFlags<T extends CliFlagsSchema> = { [K in keyof T]: StandardSchemaV1.InferOutput<T[K]>; };
+/** Validate the raw cac-parsed bag against a {@link CliFlagsSchema}. */
+declare function parseCliFlags(schema: CliFlagsSchema, raw: Record<string, unknown>): {
+  flags: Record<string, unknown>;
+  issues?: string[];
+};
+/**
+ * A ready-made pre-auth RPC handler, as produced by
+ * `devframe/recipes/interactive-auth`'s `createInteractiveAuth`. Bundles
+ * everything a host adapter needs to wire an authenticated server:
+ * the handshake RPC functions, the resolver gate, the connect-time trust
+ * hook, and the startup banner.
+ *
+ * `initDevframe` / `initHub` accept one of these directly via their `auth` option
+ * (see {@link https://devfra.me | devframe}'s server docs), or a host can
+ * wire the four pieces itself against a lower-level transport.
+ */
+interface DevframeAuthHandler {
   /**
-   * Milliseconds a closed stream is retained on the server after its
-   * last subscriber leaves (or if no subscriber ever arrived). During
-   * this window, late subscribers can still join and replay the buffer
-   * + receive the `end` frame.
+   * `anonymous:devframe:auth` + `anonymous:devframe:auth:exchange` (the
+   * handshake), `anonymous:devframe:auth:request-code` (client-requested
+   * banner print), and `devframe:auth:revoke` (self-revoke); register these
+   * on the RPC host (e.g. `rpcHost.register(fn)` for each).
+   */
+  rpcFunctions: RpcFunctionDefinitionAny[];
+  /**
+   * Resolver gate: whether `methodName` is callable given `session`'s
+   * current trust state. Defaults to allowing any `anonymous:`-prefixed
+   * method (see `isAnonymousRpcMethod`) plus anything once the session is
+   * trusted.
+   */
+  authorize: (methodName: string, session: DevframeNodeRpcSession) => boolean;
+  /**
+   * Connect-time trust: reads a bearer token off the connection's initial
+   * request (a static/pre-shared token from `clientAuthTokens`, or a token
+   * minted by the code exchange) and, when valid, marks the session
+   * trusted immediately, before the client's own handshake call.
+   */
+  onConnect: (connection: DevframeRpcConnection, session: DevframeNodeRpcSession) => void;
+  /**
+   * Print the current one-time code and its magic-link URL. An untrusted
+   * browser client triggers this itself over
+   * `anonymous:devframe:auth:request-code`; call it directly when the host
+   * wants the code on screen without waiting for a client. Safe to call
+   * repeatedly; it only prints once per code.
+   */
+  printBanner: () => void;
+  /**
+   * Rewrite a URL the CLI is about to open in the browser (`--open`) so the
+   * tab lands already authenticated, e.g. appending the current OTP as a
+   * query param. Called with the fully-resolved target URL; return it
+   * unchanged to opt out. Optional: a handler that doesn't need this (e.g.
+   * one gated by a pre-shared bearer token instead of an interactive code)
+   * can omit it and the URL opens as-is.
+   */
+  buildOpenUrl?: (url: string) => string;
+}
+/**
+ * The MCP adapter surface, typed here so `devframe` (which probes for and
+ * lazily loads `@devframes/agentic`) and `@devframes/agentic/mcp` (which
+ * implements it) share one contract without a type-level dependency cycle.
+ * None of these shapes reference the MCP SDK: the SDK is an implementation
+ * detail of `@devframes/agentic`, freely swappable behind this surface.
+ * The h3-bound `mountMcpHttp` shapes live in `node/agentic.ts` (exported via
+ * `devframe/internal`) instead: `devframe/types` must stay lib-neutral, and
+ * h3's declarations are not.
+ */
+interface CreateMcpServerOptions {
+  /**
+   * Transport to use. `createMcpServer` itself runs `'stdio'` (a standalone
+   * process with its own host context); the Streamable-HTTP transport is
+   * served route-based by the dev server instead; see `mountMcpHttp` and
+   * the `mcp` option on `createDevServer` / `createCac`'s `--mcp` flag.
+   */
+  transport?: 'stdio';
+  /**
+   * Expose shared-state keys as MCP resources.
+   * - `true` (default): every key the host publishes
+   * - `false`: none
+   * - `(key) => boolean`: filter
+   */
+  exposeSharedState?: boolean | ((key: string) => boolean);
+  /**
+   * Usage guidance sent as `instructions` in the MCP `initialize` (and
+   * `server/discover`) result. Omitted or empty sends no instructions.
+   */
+  instructions?: string;
+  /**
+   * Resource templates served through `resources/templates/list`, and read
+   * through `resources/read`. Omitted or empty keeps the resources unchanged.
+   */
+  resourceTemplates?: McpResourceTemplate[];
+  /**
+   * Host subscription for resource-list changes; each `notify()` sends
+   * `notifications/resources/list_changed`. See {@link McpResourcesChangedHook}.
+   */
+  onResourcesChanged?: McpResourcesChangedHook;
+  /**
+   * Prompt templates served through `prompts/list` and `prompts/get`.
+   * Omitted or empty declares no `prompts` capability.
+   */
+  prompts?: McpPrompt[];
+  /** Override the name reported in the MCP handshake. */
+  serverName?: string;
+  /** Override the version reported in the MCP handshake. Defaults to `definition.version ?? '0.0.0'`. */
+  serverVersion?: string;
+  /** Called once the transport is connected. */
+  onReady?: (info: {
+    transport: 'stdio';
+  }) => void;
+}
+/**
+ * One MCP content block in a tool result. Attach blocks to a tool's return
+ * value with `withMcpContent` (from `devframe`) to send them in place of the
+ * default JSON text block. `data` is base64.
+ */
+type McpContentBlock = {
+  type: 'text';
+  text: string;
+} | {
+  type: 'image';
+  data: string;
+  mimeType: string;
+} | {
+  type: 'audio';
+  data: string;
+  mimeType: string;
+};
+interface McpServerHandle {
+  stop: () => Promise<void>;
+}
+interface CreateMcpFetchHandlerOptions {
+  /** Name reported in the MCP handshake. */
+  serverName: string;
+  /** Version reported in the MCP handshake. */
+  serverVersion: string;
+  /** Expose shared-state keys as MCP resources; see {@link CreateMcpServerOptions.exposeSharedState}. */
+  exposeSharedState: boolean | ((key: string) => boolean);
+  /** Usage guidance for the handshake; see {@link CreateMcpServerOptions.instructions}. */
+  instructions?: string;
+  /** Resource templates; see {@link CreateMcpServerOptions.resourceTemplates}. */
+  resourceTemplates?: McpResourceTemplate[];
+  /** Host subscription for resource-list changes; see {@link CreateMcpServerOptions.onResourcesChanged}. */
+  onResourcesChanged?: McpResourcesChangedHook;
+  /** Prompt templates; see {@link CreateMcpServerOptions.prompts}. */
+  prompts?: McpPrompt[];
+  /**
+   * Optional identity check, layered on top of the origin gate and checked
+   * **after** it: a bearer token string (matched in constant time against
+   * `Authorization: Bearer <token>`), a `(request) => boolean` callback, or
+   * `false` (the default) for origin-only, trusting same-machine callers. A
+   * callback governs identity only and cannot relax the origin gate. See
+   * {@link McpAuthorization}.
+   */
+  authorization?: McpAuthorization;
+  /**
+   * Origin allow-list beyond the loopback default. `false` disables the
+   * origin gate entirely. Default: loopback-only.
    *
-   * Defaults to `30_000` (30 s) when `replayWindow > 0`, else `0`
-   * (immediate free). Set to `0` to opt out, or higher for longer
-   * post-mortem replay.
+   * Unlike the WS transport, the MCP route does **not** allow `Origin`-less
+   * requests: a route-based endpoint is reachable by any local process, so a
+   * request must carry an `Origin` that passes the gate. Native clients
+   * (e.g. `devframe connect`) send their loopback origin explicitly.
    */
-  closedStreamRetention?: number;
+  allowedOrigins?: readonly string[] | false;
+}
+/** Connection facts a host knows about a request beyond the `Request` itself. */
+interface McpConnectionInfo {
+  /**
+   * The connecting peer's remote address (a node socket's `remoteAddress`),
+   * used to prove a same-machine caller when the endpoint relies on the
+   * loopback origin default with no identity check. A host that can resolve a
+   * trustworthy peer address (the h3/node mount) supplies it; when it's
+   * omitted the origin gate stays the only locality signal.
+   */
+  remoteAddress?: string;
+}
+interface McpFetchHandler {
+  /**
+   * WHATWG-`fetch` handler for the MCP endpoint. Hand every method
+   * (POST/GET/DELETE) on the endpoint's path to it; routing by path is the
+   * host's job. Pass {@link McpConnectionInfo} when the host can resolve the
+   * peer address so the default trust boundary can enforce same-machine
+   * locality.
+   */
+  fetch: (request: Request, connection?: McpConnectionInfo) => Promise<Response>;
+  /** Tear down the handler (aborts in-flight exchanges, drops the change bridge). */
+  dispose: () => Promise<void>;
+}
+/** One concrete resource that an {@link McpResourceTemplate} lists in `resources/list`. */
+interface McpResourceTemplateEntry {
+  /** The resource URI. It SHOULD match the `uriTemplate` of its template, so `resources/read` finds it. */
+  uri: string;
+  name: string;
+  /** Human-readable name for display. */
+  title?: string;
+  description?: string;
+  /** Defaults to the `mimeType` of the template. */
+  mimeType?: string;
 }
 /**
- * Channel handle returned by `ctx.rpc.streaming.create(name, opts)`. A
- * channel owns a wire namespace; calling `start()` produces individual
- * streams keyed by id.
+ * What an {@link McpResourceTemplate} returns from `read`, sent as the
+ * `resources/read` result: `text` as is, or else `json` as JSON text.
+ */
+interface McpResourceTemplateContent {
+  text?: string;
+  json?: unknown;
+  /** Defaults to the `mimeType` of the template, then `application/json`. */
+  mimeType?: string;
+}
+/**
+ * A resource template the MCP server lists in `resources/templates/list` and
+ * reads in `resources/read`. The `uriTemplate` uses RFC 6570 level 1 only:
+ * plain `{name}` expressions, with text between any two of them. Each
+ * expression matches a non-empty value with no `/`, and its value is
+ * percent-decoded.
  *
- * @see {@link https://devfra.me/guide/streaming Streaming guide}
+ * `list` and `read` get the node context of the devframe (or of the hub), so
+ * they can read live state such as `ctx.rpc.sharedState` or `ctx.agent`. The
+ * route options are resolved before `setup()` runs, so a template cannot
+ * capture that context in a closure.
  */
-interface RpcStreamingChannel<T = unknown> {
-  /** Channel name as registered with `ctx.rpc.streaming.create()`. */
-  readonly name: string;
+interface McpResourceTemplate {
+  /** RFC 6570 level 1 URI template, e.g. `my-tool://file/{path}`. Anything else throws `DF0084`. */
+  uriTemplate: string;
+  name: string;
+  /** Human-readable name for display. */
+  title?: string;
+  description?: string;
+  /** MIME type of every resource the template stands for. */
+  mimeType?: string;
+  /** The concrete resources the template stands for right now. They are added to `resources/list`. */
+  list?: (ctx: DevframeNodeContext) => McpResourceTemplateEntry[] | Promise<McpResourceTemplateEntry[]>;
+  /** Read one resource: `params` holds the decoded value of each `{name}`, `uri` the requested URI. */
+  read: (params: Record<string, string>, uri: string, ctx: DevframeNodeContext) => McpResourceTemplateContent | Promise<McpResourceTemplateContent>;
+}
+/**
+ * A host subscription for resource-list changes. Call `notify()` each time
+ * the resources change; the MCP server then sends
+ * `notifications/resources/list_changed`. Return a function that removes the
+ * subscription; the MCP server calls it on teardown.
+ */
+type McpResourcesChangedHook = (notify: () => void, ctx: DevframeNodeContext) => () => void;
+/** One argument of an {@link McpPrompt}. */
+interface McpPromptArgument {
+  name: string;
+  description?: string;
+  /** `prompts/get` answers invalid params when a required argument is missing or empty. */
+  required?: boolean;
+}
+/** One message of the answer to `prompts/get`. */
+interface McpPromptMessage {
+  role: 'user' | 'assistant';
+  content: {
+    type: 'text';
+    text: string;
+  };
+}
+/** What an {@link McpPrompt} returns from `get`, sent as the `prompts/get` result. */
+interface McpPromptResult {
+  description?: string;
+  messages: McpPromptMessage[];
+}
+/**
+ * A prompt template the MCP server lists in `prompts/list` and builds in
+ * `prompts/get`. A coding agent usually offers it to the user as a slash
+ * command. Each `name` is used once; a repeated name throws `DF0085`.
+ */
+interface McpPrompt {
+  name: string;
+  /** Human-readable name for display. */
+  title?: string;
+  description?: string;
+  arguments?: McpPromptArgument[];
+  /** Build the messages from the arguments the coding agent sent. */
+  get: (args: Record<string, string>) => McpPromptResult | Promise<McpPromptResult>;
+}
+/**
+ * Classification of how a devframe is being deployed. Hosted adapters
+ * (`vite`, `embedded`) share their origin with a host app and must
+ * namespace their mount path under `/__<id>/`. Standalone adapters
+ * (`cli`, `build`) own the origin and default to `/`.
+ */
+type DevframeDeploymentKind = 'standalone' | 'hosted';
+/**
+ * How a hub deduplicates devframes that share an `id` when more than one
+ * is mounted onto the same hub. See {@link DevframeDefinition.duplicationStrategy}.
+ *
+ * - `'warn'` (default): keep the first registration, drop later
+ *   duplicates, and emit a warning diagnostic (`DF8105`).
+ * - `'silent'`: drop later duplicates without warning.
+ * - `'throw'`: throw when a duplicate is mounted.
+ * - `'duplicate'`: let every instance coexist under a disambiguated
+ *   dock id.
+ */
+type DevframeDuplicationStrategy = 'warn' | 'silent' | 'throw' | 'duplicate';
+/**
+ * Controls where the browser opens the RPC WebSocket, advertised in
+ * `__connection.json` and used to bind the dev server. The three shapes map
+ * to the three connection scenarios; precedence is `url` > `port` > `route`:
+ *
+ *   1. **Same server, different route** (default): leave `port`/`url` unset.
+ *      The socket shares the HTTP server's port and binds to `route`
+ *      (`__ws`). The client connects to its own origin, so the link
+ *      survives a reverse proxy that rewrites the host/port/subpath.
+ *
+ *   2. **Different port**: set `port`. The socket binds on its own port on the
+ *      same host; the client targets `ws(s)://<page-host>:<port>/<route>`.
+ *
+ *   3. **Remote, different origin**: set `url` to a full `ws://`/`wss://`
+ *      endpoint (e.g. a public tunnel or relay). The client uses it verbatim.
+ */
+interface DevframeWsOptions {
   /**
-   * Start a new stream. Returns a server-side sink with both an imperative
-   * (`write` / `close` / `error`) surface and a `WritableStream<T>` for
-   * `pipeTo` consumption. The sink's `signal` aborts when every subscriber
-   * disconnects or cancels.
+   * Upgrade route segment the socket binds to and is advertised at, relative
+   * to the SPA base. Default: `__ws`.
    */
-  start: (opts?: {
-    id?: string;
-  }) => StreamSink<T>;
+  route?: string;
+  /**
+   * Bind the socket on its own port instead of sharing the HTTP port. The
+   * browser connects to this port on the page's hostname. Implies
+   * {@link DevframeWsOptions.sidecar}.
+   */
+  port?: number;
+  /**
+   * Start a side-car WebSocket server on a free port, for hosts whose request
+   * handlers can't accept upgrades (Next.js route handlers, Nitro, Rsbuild).
+   * The resolved port is advertised in `__connection.json`, so the browser
+   * finds it without any further wiring. Set `port` instead to pin it.
+   */
+  sidecar?: boolean;
+  /**
+   * Advertise a fixed, fully-qualified endpoint on another origin (a full
+   * `ws://`/`wss://` URL). Takes precedence over `port`/`route` in the meta.
+   */
+  url?: string;
+}
+/**
+ * Controls the SSE RPC endpoint, the WebSocket-free transport for hosts
+ * and proxies where the upgrade isn't available. It rides whatever HTTP
+ * surface serves the instance (the same one serving `__connection.json`),
+ * so a relative `route` always resolves; there is no port plumbing of its
+ * own. Enabled by default alongside the WebSocket; pass `sse: false` to
+ * disable, or `ws: false` to run SSE-only (`backend: 'sse'`).
+ */
+interface DevframeSseOptions {
+  /**
+   * Route segment the SSE endpoint binds to and is advertised at, relative
+   * to the SPA base. Default: `__sse`.
+   */
+  route?: string;
+}
+/**
+ * An **optional** identity check layered on top of the origin gate. The
+ * route-based MCP endpoint trusts same-machine callers by default (the
+ * loopback origin gate is enough), so this is opt-in hardening for the cases
+ * where a same-machine process is not a trust boundary, like a LAN/tunnel
+ * origin, a shared/CI box, or a destructive tool surface:
+ *
+ * - a non-empty **bearer token string**: the request must carry
+ *   `Authorization: Bearer <token>`, compared in constant time. Back it with
+ *   an environment variable rather than a literal;
+ * - a **callback** `(request) => boolean | Promise<boolean>`: a custom
+ *   identity check (validate a signed header, an mTLS-derived claim, …). It
+ *   only governs identity and cannot relax the origin gate;
+ * - `false`, the default: **origin-only**, trusting same-machine callers.
+ */
+type McpAuthorization = string | ((request: Request) => boolean | Promise<boolean>) | false;
+/**
+ * The route-based MCP setting accepted everywhere a host mounts a devframe
+ * (`initDevframe` / `initHub` / `createDevServer` options, `createCac` /
+ * `--mcp`, the framework kits):
+ *
+ * - `'auto'`, the default: mount the route when the devframe exposes an
+ *   agent surface (an `agent`-flagged RPC function, or a tool / resource /
+ *   provider registered on `ctx.agent`) AND the optional `@devframes/agentic`
+ *   peer (the MCP adapter and SDK) is installed. An empty agent surface
+ *   mounts nothing and loads no MCP code; a non-empty one without the peer
+ *   warns once (DF0078) and mounts nothing.
+ * - `true`: always mount at the default `__mcp` route; a missing
+ *   `@devframes/agentic` throws DF0079.
+ * - `false`: never mount, and never probe or warn.
+ * - {@link McpRouteOptions}: always mount (like `true`), with a custom route
+ *   path, origin allow-list, or {@link McpAuthorization} identity check.
+ *
+ * A mounted route trusts same-machine callers by default (the loopback
+ * origin gate), exactly like `mcp: true`.
+ */
+type McpSetting = boolean | 'auto' | McpRouteOptions;
+/**
+ * Configuration for the route-based MCP server mounted alongside the dev
+ * server (via {@link DevframeCliOptions.mcp}). The endpoint speaks
+ * the MCP Streamable-HTTP transport over the same origin as the SPA,
+ * exposing the definition's `ctx.agent` tools + shared-state resources to
+ * external MCP clients connected to the *running* server.
+ */
+interface McpRouteOptions {
+  /**
+   * Route segment the MCP endpoint binds to, relative to the SPA base.
+   * Default: `__mcp` (i.e. `/__mcp` standalone, `/__<id>/__mcp` hosted).
+   */
+  path?: string;
+  /**
+   * Optional identity check, layered on top of the origin gate and checked
+   * **after** it. Defaults to origin-only (`false`): the route trusts
+   * same-machine callers, since the loopback origin gate already keeps
+   * arbitrary remote/browser callers out. Set a bearer token or a callback to
+   * harden the route when a same-machine process is not your trust boundary
+   * (LAN/tunnel origin, shared/CI host, destructive tools). See
+   * {@link McpAuthorization}.
+   */
+  authorization?: McpAuthorization;
+  /**
+   * Extra `Origin` header values to accept beyond the loopback default
+   * (`localhost`/`127.0.0.1`/`::1` and any `Origin`-less native client).
+   * Add your LAN/tunnel origin here when reaching the endpoint from another
+   * host, mirroring the WS transport's origin gate. Pass `false` to disable
+   * origin checking entirely (not recommended). Default: loopback-only.
+   *
+   * This is the endpoint's DNS-rebinding protection: the shared
+   * `isAllowedOrigin` gate the WS upgrade already uses, applied as external
+   * middleware (the approach the MCP SDK now recommends over its own
+   * deprecated `allowedHosts`/`allowedOrigins` transport flags). When you
+   * widen it past loopback, layer on {@link McpRouteOptions.authorization} to
+   * prove identity too.
+   */
+  allowedOrigins?: readonly string[] | false;
+  /**
+   * Which shared-state keys the route exposes to agents, through the built-in
+   * `devframe_state_read` tool and the `devframe://state/<key>` resources.
+   * - `true` (default): every key the host publishes
+   * - `false`: none
+   * - `(key) => boolean`: only the keys the filter accepts
+   *
+   * The states themselves stay available to the UI over RPC.
+   */
+  exposeSharedState?: boolean | ((key: string) => boolean);
+  /**
+   * Usage guidance for the route, sent as `instructions` in the MCP
+   * `initialize` (and `server/discover`) result. An MCP client can add it to
+   * the coding agent's context, for example to say which tool to call first.
+   * Omitted or empty sends no instructions.
+   */
+  instructions?: string;
+  /**
+   * Resource templates the route serves through MCP
+   * `resources/templates/list`. `resources/read` tries them after the
+   * registered resources and the shared-state resources (a
+   * `devframe://resource/` or `devframe://state/` URI never reaches them);
+   * the first template whose `uriTemplate` matches the URI reads it. `resources/list` adds the
+   * entries each template's `list` returns. Omitted or empty keeps the
+   * resources unchanged.
+   */
+  resourceTemplates?: McpResourceTemplate[];
   /**
-   * Convenience: start a stream and pipe a `ReadableStream<T>` into it.
-   * The pipe uses `sink.signal` so cancellation propagates upstream.
-   *
-   * Node-stream interop: convert a `Readable` with `Readable.toWeb(node)`
-   * before passing it here.
+   * Host subscription for resource-list changes. Call `notify()` each time
+   * the resources change (for example, the entries of a resource template);
+   * the route then sends `notifications/resources/list_changed`. Return a
+   * function that removes the subscription; the route calls it on teardown.
    */
-  pipeFrom: (readable: ReadableStream<T>, opts?: {
-    id?: string;
-  }) => Promise<StreamSink<T>>;
-  /** Look up an active stream by id. Returns `undefined` if none. */
-  get: (id: string) => StreamSink<T> | undefined;
-  /** All active outbound stream ids on this channel. */
-  ids: () => string[];
+  onResourcesChanged?: McpResourcesChangedHook;
   /**
-   * Open an inbound stream: the server side of a client-to-server
-   * upload. Allocates an id, returns a `StreamReader<T>` that fills as
-   * the client writes chunks. Typical pattern is to call this from an
-   * action handler, kick off background processing, and return the id
-   * so the caller can start uploading:
-   *
-   * ```ts
-   * handler: async () => {
-   *   const reader = channel.openInbound()
-   *   ;(async () => {
-   *     for await (const chunk of reader) processChunk(chunk)
-   *   })()
-   *   return { uploadId: reader.id }
-   * }
-   * ```
-   *
-   * Calling `reader.cancel()` on the server sends an `upload-cancel` to
-   * the uploading client, which aborts its sink.
+   * Prompt templates the route serves through MCP `prompts/list` and
+   * `prompts/get`. Omitted or empty declares no `prompts` capability.
    */
-  openInbound: (opts?: {
-    id?: string;
-  }) => StreamReader<T>;
+  prompts?: McpPrompt[];
 }
-/**
- * Server-side streaming host. Lives on `ctx.rpc.streaming` alongside
- * `ctx.rpc.sharedState`. Each named channel owns its own stream registry
- * and wire namespace.
- */
-interface RpcStreamingHost {
+interface DevframeCliOptions {
+  /** Binary name; default: the devframe's `id`. */
+  command?: string;
+  /** Preferred port for the dev server (default 9999). */
+  port?: number;
+  /** Port scan range, forwarded to `get-port-please`. */
+  portRange?: [number, number];
+  /** Prefer a random open port. */
+  random?: boolean;
+  /** Default host to bind to; `--host` overrides. */
+  host?: string;
   /**
-   * Register a streaming channel. Names follow the `<plugin-id>:<channel>`
-   * convention (e.g. `'my-devtool:chat-stream'`). Throws `DF0032` if the
-   * name is already taken.
+   * Auto-open the browser when the dev server starts.
+   * `true` opens the resolved origin; a string opens that relative path.
+   * The `--open` / `--no-open` flags override this.
    */
-  create: <T = unknown>(name: string, opts?: RpcStreamingChannelOptions) => RpcStreamingChannel<T>;
+  open?: boolean | string;
   /**
-   * Adapters call this when a session disconnects so the host can drop
-   * subscribers and abort orphaned streams. Most users do not need this;
-   * it's wired by the RPC server binding automatically.
+   * Authentication for the standalone dev server.
    *
-   * @internal
-   */
-  _onSessionDisconnected: (meta: DevframeNodeRpcSessionMeta) => void;
-}
-//#endregion
-//#region src/types/context.d.ts
-interface DevframeCapabilities {
-  rpc?: boolean;
-  views?: boolean;
-}
-/**
- * Framework- and build-tool-agnostic node context: RPC + diagnostics +
- * agent + the view-host (HTTP file-serving). Host adapters can wrap this
- * to add their own surfaces; for example, `@vitejs/devtools-kit`'s
- * `createKitContext` adds `docks`, `terminals`, `messages`, and
- * `commands` when mounted into Vite DevTools. JSON rendering is an opt-in
- * integration (`@devframes/json-render`) layered on top, not part of this
- * core surface.
- */
-interface DevframeNodeContext {
-  readonly workspaceRoot: string;
-  readonly cwd: string;
-  /**
-   * Lifecycle distinction surfaced to plugin authors:
+   *   - `undefined` / `true`: the standalone adapters (`cli` /
+   *     served `build`) auto-wire devframe's interactive OTP auth
+   *     (`createInteractiveAuth`): an untrusted client can only reach
+   *     `anonymous:` methods until it exchanges the printed one-time code.
+   *     The adapter prints the code + magic-link banner once the server is
+   *     listening.
+   *   - `false`: no gate, for trusted single-user localhost tools where an
+   *     auth round-trip only gets in the way (the built-in plugins set this).
+   *     The `--no-auth` CLI flag maps here for one-off runs.
+   *   - A {@link DevframeAuthHandler}: a custom handler (e.g. a tuned
+   *     `createInteractiveAuth`, or an entirely different scheme) passed
+   *     straight through to the RPC transport binding.
    *
-   *   - `'dev'`:   long-running, interactive session. Connections come and
-   *                 go; broadcasts and shared-state mutations are debounced
-   *                 to keep the UI responsive.
-   *   - `'build'`: one-shot batch run. The context is set up, the devtool
-   *                 collects what it needs, and a snapshot is written. No
-   *                 live UI, no WS server.
+   * Hosted adapters (`vite`, `embedded`) ignore this and defer to the host's
+   * auth; `@vitejs/devtools` honors the equivalent `devtools.clientAuth`.
    *
-   * Names are inherited from Vite's serve/build dichotomy but the meaning
-   * is general: the same distinction applies to any tool that runs in
-   * either an interactive or a static-output mode.
-   */
-  readonly mode: 'dev' | 'build';
-  /**
-   * Host runtime abstraction, exposing `mountStatic` / `resolveOrigin` /
-   * `getStorageDir`.
+   * @default true
    */
-  host: DevframeHost;
-  rpc: RpcFunctionsHost;
-  views: DevframeViewHost;
+  auth?: boolean | DevframeAuthHandler;
   /**
-   * Structured diagnostics host; wraps `nostics` and lets integrations
-   * register their own coded errors/warnings into the shared lookup.
+   * How the browser reaches the RPC WebSocket. Defaults to sharing the HTTP
+   * port on the `__ws` route. See {@link DevframeWsOptions} for the
+   * different-port and remote-origin variants. Pass `false` to serve no
+   * WebSocket at all; clients connect over SSE instead (`backend: 'sse'`).
    */
-  diagnostics: DevframeDiagnosticsHost;
+  ws?: DevframeWsOptions | false;
   /**
-   * Agent host; aggregates the agent-exposed surface of this devtool.
+   * How the browser reaches the SSE RPC endpoint, enabled by default
+   * alongside the WebSocket as the more portable transport. Pass `false`
+   * to disable, or a {@link DevframeSseOptions} to change its route.
    */
-  agent: DevframeAgentHost;
+  sse?: boolean | DevframeSseOptions;
   /**
-   * Cross-plugin services: a typed, namespaced registry through which one
-   * integration exposes a capability (e.g. a data-source registry) and
-   * others consume it without a hard package dependency. Ids follow the RPC
-   * namespacing rule (`<plugin-id>:<service>`); types come from augmenting
-   * the `DevframeServicesRegistry` interface. `whenAvailable` subscriptions
-   * absorb setup-order differences between provider and consumer.
+   * Capability-side CAC hook. Called with the CAC instance after the
+   * adapter registers its built-in commands (`build` / `mcp`)
+   * but before `createCac`'s own `configureCli` caller. Use this to
+   * contribute tool-specific flags and subcommands from the definition
+   * itself.
    */
-  services: DevframeServicesHost;
+  configure?: (cli: CAC) => void;
   /**
-   * This context's own {@link ConnectionMeta.configs}: static, boot-time
-   * config a host publishes once through the connection handshake and every
-   * client reads read-only. A plain, **non-reactive** object: mutate it
-   * during `setup(ctx)` (a plugin sets its keys, a hub aggregates across
-   * every installed devframe), never during the session, since it's serialized
-   * once, after setup, and changing it afterwards reaches no client.
+   * Typed CLI flags for the default `dev` command, backed by any
+   * [Standard Schema](https://standardschema.dev/) validator (valibot,
+   * zod, arktype, or devframe's built-in `s`). The adapter registers
+   * matching `--kebab-key` options on CAC, validates the parsed values,
+   * and forwards the typed bag to `setup(ctx, { flags })`.
+   *
+   * Use {@link defineCliFlags} to preserve the literal schema-map
+   * shape, and {@link InferCliFlags} to recover the typed output at the
+   * call site:
    *
    * ```ts
-   * ctx.staticConfig.dock = {
-   *   ...ctx.staticConfig.dock,
-   *   categoryOrder: { ...ctx.staticConfig.dock?.categoryOrder, ...myOrder },
-   * }
-   * ```
-   */
-  staticConfig: Partial<DevframeConnectionConfigsRegistry>;
-  /**
-   * Create a namespace-scoped view of this context. The returned
-   * `ctx.scope('my-plugin')` auto-namespaces every RPC id, shared-state
-   * key, and streaming channel with `my-plugin:`, and exposes a typed
-   * top-level `settings` store. This is the preferred way to consume the
-   * context from a single tool's setup code.
+   * const appFlags = defineCliFlags({
+   *   depth: v.pipe(v.number(), v.integer()),
+   *   config: v.optional(v.string()),
+   * })
    *
-   * Pass `null` or `''` to un-scope and get the base context.
+   * defineDevframe({
+   *   cli: { flags: appFlags },
+   *   setup(ctx, info) {
+   *     const flags = info.flags as InferCliFlags<typeof appFlags>
+   *   },
+   * })
+   * ```
    */
-  scope: {
-    <NS extends string>(namespace: NS): DevframeScopedNodeContext<NS, SettingsForNamespace<NS>>;
-    (namespace?: null | ''): DevframeNodeContext;
-  };
+  flags?: CliFlagsSchema;
 }
 /**
- * Describes where the browser client should open its RPC WebSocket. The
- * object form is the proxy-flexible default: `path` is resolved relative to
- * where `__connection.json` was loaded, and the connection is made to the
- * page's own origin (only the `http`→`ws` / `https`→`wss` protocol swap is
- * applied). This survives reverse proxies that change the host/port, because
- * the client never trusts a server-baked hostname; it reuses its own.
+ * Default dock attributes for the iframe entry a hub synthesizes when it
+ * mounts this devframe. Framework-neutral metadata only; the hub layer
+ * (`ctx.install`) merges these beneath its per-mount `dock` overrides,
+ * which in turn sit beneath the locked, derived `id` / `type` / `url`.
  *
- * Set `port` (and/or `host`) only when the WS endpoint genuinely lives on a
- * different origin than the page, e.g. a side-car server on its own port.
+ * Every field is optional. `title` / `icon` default to the definition's
+ * `name` / `icon` when omitted here; the rest are unset by default.
+ * Standalone adapters (`cli` / `build`) ignore this entirely.
  */
-interface ConnectionMetaWebsocket {
+interface DevframeDockDefaults {
+  /** Dock entry title. Defaults to the definition's `name`. */
+  title?: string;
+  /** Translations of `title` by BCP 47 tag; see `@devframes/hub`'s `resolveTitle()`. */
+  titleLocales?: Record<string, string>;
+  /** Dock entry icon. Defaults to the definition's `icon`. */
+  icon?: string | {
+    light: string;
+    dark: string;
+  };
   /**
-   * Path to the WS endpoint. Relative paths (the default, e.g. `__ws`) are
-   * resolved against `__connection.json`'s location; absolute paths (`/__ws`)
-   * resolve against the page origin.
+   * Sort weight within the dock; higher sorts earlier.
+   * @default 0
+   */
+  defaultOrder?: number;
+  /**
+   * Category the entry groups under in the dock.
+   * @default 'default'
+   */
+  category?: string;
+  /**
+   * Conditional-visibility expression (same syntax as command `when`
+   * clauses). Set to `'false'` to hide the entry unconditionally.
+   */
+  when?: string;
+  /**
+   * Render-only visibility expression, same syntax as {@link when}. Hides the
+   * entry's own dock-bar button when it evaluates to `false` while leaving it
+   * registered and reachable (activation, RPC lookups, etc.), unlike `when`,
+   * which is the general relevance switch for the entry as a whole.
+   */
+  visibility?: string;
+  /** Badge text rendered on the dock icon (e.g. an unread count). */
+  badge?: string;
+  /** Id of the dock group this entry collapses under, if any. */
+  groupId?: string;
+  /**
+   * A client script the hub imports into the host page (this devframe's **page
+   * script**). An absolute-path `importFrom` is served by the hub under the
+   * mount base and rewritten to that URL, so mounting by package name needs no
+   * host wiring; a URL or bare specifier passes through untouched.
    */
-  path?: string;
-  /** Override the port. Combined with the page hostname unless `host` is set. */
-  port?: number;
-  /** Override the host (`hostname[:port]`). Use for a fully cross-origin endpoint. */
-  host?: string;
+  clientScript?: {
+    /**
+     * Initialize after RPC trust without waiting for dock activation.
+     * @default false
+     */
+    eager?: boolean;
+    /** An absolute filesystem path, a served URL, or a bare npm specifier. */
+    importFrom: string;
+    /**
+     * The name to import the module as.
+     * @default 'default'
+     */
+    importName?: string;
+  };
 }
 /**
- * Object form of {@link ConnectionMeta.sse}: the same proxy-safe shape and
- * resolution rules as {@link ConnectionMetaWebsocket}, producing an
- * `http(s)://` endpoint instead of a `ws(s)://` one. Set `port` (and/or
- * `host`) only when the SSE endpoint genuinely lives on a different origin
- * than the page, e.g. a side-car server on its own port.
+ * Runtime information threaded into `setup(ctx, info)`. Adapters
+ * populate the fields that make sense for their deployment. In
+ * particular, `createCac` fills `flags` with the parsed CAC bag.
  */
-interface ConnectionMetaSse {
-  /**
-   * Path to the SSE endpoint. Relative paths (the default, e.g. `__sse`)
-   * are resolved against `__connection.json`'s location; absolute paths
-   * (`/__sse`) resolve against the page origin.
-   */
-  path?: string;
-  /** Override the port. Combined with the page hostname unless `host` is set. */
-  port?: number;
-  /** Override the host (`hostname[:port]`). Use for a fully cross-origin endpoint. */
-  host?: string;
+interface DevframeSetupInfo {
+  /** Parsed CLI flags, populated by the CLI adapter. */
+  flags?: Record<string, unknown>;
 }
-interface ConnectionMeta {
-  /**
-   * The server's primary live-RPC transport (`websocket` / `sse`), `static`
-   * for a pre-computed RPC dump with no live server, or `none` for a server
-   * exposing no RPC transport at all (e.g. an MCP-only deployment).
-   */
-  backend: 'websocket' | 'sse' | 'static' | 'none';
+interface DevframeDefinition {
+  id: string;
+  name: string;
+  /** Semver of the tool, surfaced in hub UIs and diagnostics. */
+  version: string;
+  /** npm package name the devframe ships in (e.g. `@scope/my-tool`). */
+  packageName: string;
   /**
-   * WebSocket endpoint, resolved by the client into a `ws(s)://` URL:
+   * `import.meta.url` of the module that defines this devframe. **Always
+   * provide it** (`importMetaUrl: import.meta.url`): it is the resolution base
+   * for the tool's own dependency graph, which lets the host resolve
+   * everything against the plugin's own installed packages rather than the
+   * consuming app's.
    *
-   *   - {@link ConnectionMetaWebsocket}: the proxy-flexible default; a
-   *     same-origin path relative to `__connection.json`.
-   *   - `number`: a port on the page's hostname (`ws(s)://<host>:<port>`).
-   *   - `string`: a full `ws://`/`wss://` URL used verbatim, an `http(s)://`
-   *     URL with its protocol swapped, or a path resolved same-origin.
+   * - **Remote assets**: becomes the default `resolveFrom` for any remote
+   *   {@link StaticAssetsSource} the devframe hosts (its `clientAssets`, and
+   *   every `ctx.views.hostStatic` call) that doesn't set one explicitly, so a
+   *   locally installed copy of the assets package is served with zero
+   *   network. A per-asset `resolveFrom` still wins, and an explicit
+   *   `resolveFrom: null` still opts out.
+   * - **Service dependencies**: becomes the base the host resolves declared
+   *   {@link DevframeServiceInput | services} from, so a plugin can ship a
+   *   service package as its own dependency instead of asking users to install
+   *   it.
+   *
+   * Optional for backward compatibility; omitting it falls back to
+   * runtime-directory resolution and disables the zero-network installed-copy
+   * fast paths above.
    */
-  websocket?: number | string | ConnectionMetaWebsocket;
+  importMetaUrl?: string;
+  /** Project homepage or documentation URL. */
+  homepage: string;
+  /** One-line summary of what the tool does. */
+  description: string;
+  icon?: string | {
+    light: string;
+    dark: string;
+  };
   /**
-   * SSE endpoint (`GET` opens the event stream, `POST` carries RPC calls),
-   * resolved by the client into an `http(s)://` URL with the same
-   * proxy-safe rules as {@link ConnectionMeta.websocket}:
+   * Default dock attributes applied when a hub mounts this devframe as an
+   * iframe dock entry. Consulted only by the hub install path (`ctx.install`),
+   * which merge these beneath the per-mount `dock` overrides; standalone
+   * adapters (`cli` / `build`) ignore it.
    *
-   *   - {@link ConnectionMetaSse}: the proxy-flexible default; a
-   *     same-origin path relative to `__connection.json`.
-   *   - `string`: a full `http(s)://` URL used verbatim, or a path
-   *     resolved same-origin.
+   * @see {@link DevframeDockDefaults}
    */
-  sse?: string | ConnectionMetaSse;
+  dock?: DevframeDockDefaults;
   /**
-   * Present when the dev server exposes a route-based MCP endpoint
-   * (the host's `mcp` setting). Advertises the MCP Streamable-HTTP route so in-browser
-   * tooling (e.g. an MCP inspector) can discover it without guessing the
-   * path. `path` is relative to `__connection.json`'s location, like the
-   * WebSocket `path`. `port` is set when the endpoint lives on a side-car
-   * server on its own port (bridge mode: `devframeViteBridge`,
-   * `@devframes/next`): the client combines the page hostname with `port`
-   * and resolves `path` against that origin, mirroring
-   * {@link ConnectionMetaWebsocket.port}.
+   * Mount path override. Defaults depend on the adapter:
+   * `/` for standalone (`cli` / `build`), `/__<id>/` for hosted
+   * (`vite` / `embedded`).
    */
-  mcp?: {
-    path: string;
-    port?: number;
-  };
+  basePath?: string;
   /**
-   * Names of RPC functions that have declared `jsonSerializable: true`.
-   * Used by the WS / static client to dispatch the per-call wire
-   * serializer (strict JSON for these methods, structured-clone for
-   * the rest). Populated by the server / build adapter; absent on
-   * legacy clients, in which case all outgoing messages fall back to
-   * structured-clone.
+   * How a hub reacts when another devframe sharing this one's `id` is
+   * mounted onto the same hub. Consulted only by hub adapters
+   * (`ctx.install`); standalone adapters (`cli` / `build`)
+   * ignore it.
+   *
+   * @default 'warn'
    */
-  jsonSerializableMethods?: string[];
+  duplicationStrategy?: DevframeDuplicationStrategy;
   /**
-   * URL of the `__connection.json` that owns this meta's relative paths.
-   * Two producers write it:
+   * Declares which runtimes meaningfully support this devframe. Adapters
+   * act on a `false` before doing any work:
    *
-   *   - The client annotates it (absolute) when it publishes the meta on a
-   *     shared window for same-origin inheritance: a relative
-   *     `websocket.path` resolves against this, so a child SPA mounted at
-   *     another base (e.g. a hub mounting several devframes at `/__foo/`,
-   *     `/__bar/`, …) inherits a dialable endpoint rather than resolving the
-   *     path against its own mount.
-   *   - A static hub build serves it (base-absolute, e.g.
-   *     `/__devframes/__connection.json`) in each **per-frame** meta, so a
-   *     frame SPA that fetched its own copy still resolves the shared RPC
-   *     dump from the hub base. Resolved against the fetched URL.
+   * - `build: false`: `createCac` skips registering the `build` subcommand,
+   *   `createBuild` refuses (throws `DF0042`) unless `{ force: true }`, and
+   *   a hub static build (`buildHub`) silently skips the devframe - no dock,
+   *   no SPA copy, no RPCs in the dump. Useful for a devframe whose value is
+   *   inherently live (e.g. it manages real files on disk), so a static
+   *   export would only ever produce a broken, write-less shell of the tool.
+   * - `dev: false`: `createDevServer` refuses (throws `DF0058`) unless
+   *   `{ force: true }`. Useful for a devframe that only makes sense as a
+   *   static export (e.g. a report generator with nothing to serve live).
    */
-  baseUrl?: string;
+  capabilities?: {
+    dev?: boolean;
+    build?: boolean;
+  };
   /**
-   * A pre-issued bearer token embedded in the meta so a client trusts the
-   * server on connect without any prompt or `localStorage` lookup. Only a
-   * **hub** serving a **per-frame** connection meta populates this; it
-   * authenticates once at the top level and bakes the resulting token into
-   * the meta each plugin iframe fetches, so a cross-origin frame (which
-   * cannot read the hub's `localStorage`) is still pre-authorized. The
-   * standalone `__connection.json` never carries a token.
-   *
-   * > [!WARNING]
-   * > A token in a fetchable JSON is only as protected as the URL serving
-   * > it. Emit it exclusively from hub-controlled, per-frame meta, never
-   * > from a publicly reachable static `__connection.json`.
+   * Wire services this devframe consumes (see `DevframeServiceDefinition`).
+   * Each entry is either a declarative descriptor
+   * (`{ package, version?, required?, options? }`, where the host imports the
+   * package's default-export factory, resolving it against **this plugin's
+   * own dependencies**) or a ready `DevframeServiceDefinition` (the factory
+   * was already called). The adapter queues these before `setup(ctx)` runs
+   * and constructs each service once at the `ctx.services.ready()` barrier,
+   * merging option sets across every declarer. Missing services are skipped
+   * unless marked `required`; clients feature-detect via
+   * `client.services.has(pkg)` and degrade.
    */
-  authToken?: string;
+  services?: DevframeServiceInput[];
   /**
-   * Session-scoped token that lets a trusted external viewer register its
-   * browser origin before opening the WebSocket. The host includes it in the
-   * connection metadata, which the viewer obtains through the host page.
+   * Author's SPA dist, served as the devframe's UI. A local directory, or
+   * a {@link StaticAssetsSource} remote declaration (`{ package, version }`)
+   * served through devframe's caching CDN back-proxy so the assets need not
+   * ship inside the node package.
    *
-   * Treat this as a bearer credential. Keep connection metadata containing the
-   * token same-origin until the requesting origin has been verified.
+   * Consumed by every adapter that serves the UI (`dev`, `build`, `vite`,
+   * `next`, and the hub install path).
    */
-  viewerOriginToken?: string;
+  clientAssets?: StaticAssetsSource;
+  /** RPC-level configuration for this devframe (see {@link DevframeRpcOptions}). */
+  rpc?: DevframeRpcOptions;
+  /** Server-side setup: the primary entrypoint. Runs in every runtime. */
+  setup: (ctx: DevframeNodeContext, info?: DevframeSetupInfo) => void | Promise<void>;
+  cli?: DevframeCliOptions;
+}
+interface DevframeRpcOptions {
   /**
-   * Static, host-declared configuration, baked in once at connect time and
-   * fixed for the life of the server (e.g. a hub's UI rebrand, or its
-   * aggregated dock-bar layout preferences). Read-only from the browser: a
-   * client only ever reads `rpc.connectionMeta.configs`, never writes to it.
-   *
-   * Contrast this with {@link DevframeSettingsRegistry} (`ctx.scope(ns).settings`)
-   * and a hub's `devframe:user-settings` shared-state key; both are
-   * mutable, user-editable, and synced bidirectionally over RPC for the
-   * life of the session. `configs` is the opposite: one-way, immutable,
-   * decided by whoever assembled the server.
-   *
-   * Each key is owned by one package, contributed via declaration merging:
+   * Opt an RPC function into the static-build snapshot **without owning its
+   * definition**, the mechanism a devframe uses to bake a wire service's
+   * RPC (e.g. `@devframes/service-git`'s `status`/`log`/`show`) into its
+   * `build` export, since the service itself defines no `dump`/`snapshot`.
    *
-   * ```ts
-   * declare module 'devframe/types' {
-   *   interface DevframeConnectionConfigsRegistry {
-   *     'my-key': { some: 'shape' }
-   *   }
-   * }
-   * ```
+   * Each entry is either a bare method id (bakes the no-argument call, like
+   * `snapshot: true`) or `{ method, inputs }` where `inputs` is the list of
+   * argument-tuples to bake, or an async provider given the node context
+   * (so it can enumerate at build time, e.g. read commit hashes via the
+   * service's node API). `createBuild` resolves these after setup and
+   * executes the target's own handler per tuple; the first tuple's result
+   * becomes the fallback so any call variant resolves to a baked value.
    */
-  configs?: Partial<DevframeConnectionConfigsRegistry>;
+  snapshot?: DevframeSnapshotRpcEntry[];
 }
+/** Argument-tuples to bake for a {@link DevframeSnapshotRpcEntry}, or a provider that computes them at build time. */
+type DevframeSnapshotRpcInputs = readonly (readonly unknown[])[] | ((ctx: DevframeNodeContext) => readonly (readonly unknown[])[] | Promise<readonly (readonly unknown[])[]>);
 /**
- * Augmentation point for {@link ConnectionMeta.configs}. Empty by default;
- * a package that wants to publish static, boot-time config through the
- * connection handshake augments this interface with its own key (see
- * {@link ConnectionMeta.configs} for the pattern). `@devframes/hub`
- * augments it with `dock`; `@devframes/hub-ui` augments it with `ui`.
+ * One {@link DevframeRpcOptions.snapshot} entry: a bare method id (bakes
+ * the no-argument call) or a method plus the argument-tuples to bake.
  */
-interface DevframeConnectionConfigsRegistry {}
-//#endregion
-export { DevframeServiceOf as $, AgentToolProviderHandle as $t, SharedStateEvents as A, McpFetchHandler as At, DevframeSetupInfo as B, DevframeAuthHandler as Bt, createStreamSink as C, DevframeStorageScope as Ct, ImmutableObject as D, CreateMcpServerOptions as Dt, ImmutableMap as E, CreateMcpFetchHandlerOptions as Et, DevframeDefinition as F, McpResourceTemplate as Ft, McpAuthorization as G, AgentHandle as Gt, DevframeSnapshotRpcInputs as H, InferCliFlags as Ht, DevframeDeploymentKind as I, McpResourceTemplateContent as It, DevframeServiceDefinition as J, AgentResourceContent as Jt, McpRouteOptions as K, AgentManifest as Kt, DevframeDockDefaults as L, McpResourceTemplateEntry as Lt, SharedStatePatch as M, McpPromptArgument as Mt, createSharedState as N, McpPromptMessage as Nt, ImmutableSet as O, McpConnectionInfo as Ot, DevframeCliOptions as P, McpPromptResult as Pt, DevframeServiceMeta as Q, AgentToolProvider as Qt, DevframeDuplicationStrategy as R, McpResourcesChangedHook as Rt, createStreamReader as S, DevframeHost as St, ImmutableArray as T, DevframeDiagnosticsLogger as Tt, DevframeSseOptions as U, defineCliFlags as Ut, DevframeSnapshotRpcEntry as V, CliFlagsSchema as Vt, DevframeWsOptions as W, parseCliFlags as Wt, DevframeServiceId as X, AgentTool as Xt, DevframeServiceDescriptor as Y, AgentResourceInput as Yt, DevframeServiceInput as Z, AgentToolInput as Zt, CreateStreamSinkOptions as _, DevframeViewHost as _t, DevframeConnectionConfigsRegistry as a, DevframeScopedNodeContext as at, StreamSink as b, DevframeRpcSharedStates as bt, RpcBroadcastOptions as c, DevframeSettings as ct, RpcSharedStateHost as d, ScopedBroadcastOptions as dt, DevframeAgentHost as en, DevframeServiceScopeOf as et, RpcStreamingChannel as f, ScopedClientFunctions as ft, CreateStreamReaderOptions as g, SettingsForNamespace as gt, BufferedChunk as h, ScopedSharedStates as ht, DevframeCapabilities as i, EventsMap as in, DevframeServicesState as it, SharedStateOptions as j, McpPrompt as jt, SharedState as k, McpContentBlock as kt, RpcFunctionsHost as l, DevframeSettingsRegistry as lt, RpcStreamingHost as m, ScopedServerFunctions as mt, ConnectionMetaSse as n, EventEmitter as nn, DevframeServicesRegistry as nt, DevframeNodeContext as o, DevframeScopedNodeRpc as ot, RpcStreamingChannelOptions as p, ScopedRpcFn as pt, McpSetting as q, AgentResource as qt, ConnectionMetaWebsocket as r, EventUnsubscribe as rn, DevframeServicesScopeRegistry as rt, DevframeNodeRpcSession as s, DevframeScopedStreamingHost as st, ConnectionMeta as t, DevframeAgentHostEvents as tn, DevframeServicesHost as tt, RpcSharedStateGetOptions as u, DevframeSettingsStore as ut, StreamErrorPayload as v, DevframeRpcClientFunctions as vt, Immutable as w, DevframeDiagnosticsHost as wt, StreamSinkEvents as x, BrowserAgentClientInfo as xt, StreamReader as y, DevframeRpcServerFunctions as yt, DevframeRpcOptions as z, McpServerHandle as zt };
+type DevframeSnapshotRpcEntry = string | {
+  method: string;
+  inputs: DevframeSnapshotRpcInputs;
+};
+export { DevframeServiceId as $, AgentToolProviderHandle as $t, CliFlagsSchema as A, StreamReader as At, DevframeNodeRpcSession as B, SharedState as Bt, McpPromptResult as C, DevframeDiagnosticsHost as Ct, McpResourcesChangedHook as D, CreateStreamReaderOptions as Dt, McpResourceTemplateEntry as E, BufferedChunk as Et, ConnectionMetaSse as F, Immutable as Ft, RpcStreamingChannel as G, AgentHandle as Gt, RpcFunctionsHost as H, SharedStateOptions as Ht, ConnectionMetaWebsocket as I, ImmutableArray as It, DevframeRpcClientFunctions as J, AgentResourceContent as Jt, RpcStreamingChannelOptions as K, AgentManifest as Kt, DevframeCapabilities as L, ImmutableMap as Lt, defineCliFlags as M, StreamSinkEvents as Mt, parseCliFlags as N, createStreamReader as Nt, McpServerHandle as O, CreateStreamSinkOptions as Ot, ConnectionMeta as P, createStreamSink as Pt, DevframeServiceDescriptor as Q, AgentToolProvider as Qt, DevframeConnectionConfigsRegistry as R, ImmutableObject as Rt, McpPromptMessage as S, DevframeStorageScope as St, McpResourceTemplateContent as T, BrowserAgentClientInfo as Tt, RpcSharedStateGetOptions as U, SharedStatePatch as Ut, RpcBroadcastOptions as V, SharedStateEvents as Vt, RpcSharedStateHost as W, createSharedState as Wt, DevframeRpcSharedStates as X, AgentTool as Xt, DevframeRpcServerFunctions as Y, AgentResourceInput as Yt, DevframeServiceDefinition as Z, AgentToolInput as Zt, McpConnectionInfo as _, ScopedServerFunctions as _t, DevframeDuplicationStrategy as a, DevframeServicesRegistry as at, McpPrompt as b, DevframeViewHost as bt, DevframeSnapshotRpcEntry as c, DevframeScopedNodeContext as ct, DevframeWsOptions as d, DevframeSettings as dt, DevframeAgentHost as en, DevframeServiceInput as et, McpAuthorization as f, DevframeSettingsRegistry as ft, CreateMcpServerOptions as g, ScopedRpcFn as gt, CreateMcpFetchHandlerOptions as h, ScopedClientFunctions as ht, DevframeDockDefaults as i, EventsMap as in, DevframeServicesHost as it, InferCliFlags as j, StreamSink as jt, DevframeAuthHandler as k, StreamErrorPayload as kt, DevframeSnapshotRpcInputs as l, DevframeScopedNodeRpc as lt, McpSetting as m, ScopedBroadcastOptions as mt, DevframeDefinition as n, EventEmitter as nn, DevframeServiceOf as nt, DevframeRpcOptions as o, DevframeServicesScopeRegistry as ot, McpRouteOptions as p, DevframeSettingsStore as pt, RpcStreamingHost as q, AgentResource as qt, DevframeDeploymentKind as r, EventUnsubscribe as rn, DevframeServiceScopeOf as rt, DevframeSetupInfo as s, DevframeServicesState as st, DevframeCliOptions as t, DevframeAgentHostEvents as tn, DevframeServiceMeta as tt, DevframeSseOptions as u, DevframeScopedStreamingHost as ut, McpContentBlock as v, ScopedSharedStates as vt, McpResourceTemplate as w, DevframeDiagnosticsLogger as wt, McpPromptArgument as x, DevframeHost as xt, McpFetchHandler as y, SettingsForNamespace as yt, DevframeNodeContext as z, ImmutableSet as zt };